diff --git a/.github/scripts/check_companion_release_tag_absent.py b/.github/scripts/check_companion_release_tag_absent.py
index dbd77d039..626b0dcba 100644
--- a/.github/scripts/check_companion_release_tag_absent.py
+++ b/.github/scripts/check_companion_release_tag_absent.py
@@ -1,5 +1,3 @@
-#!/usr/bin/env python3
-
 from __future__ import annotations
 
 import argparse
diff --git a/.github/scripts/cleanup_companion_releases.py b/.github/scripts/cleanup_companion_releases.py
index 9b7cdc97f..1bd9838ec 100644
--- a/.github/scripts/cleanup_companion_releases.py
+++ b/.github/scripts/cleanup_companion_releases.py
@@ -1,4 +1,3 @@
-#!/usr/bin/env python3
 """Delete obsolete Companion GitHub Releases after validating every feed marker."""
 
 from __future__ import annotations
diff --git a/.github/scripts/cleanup_test_container_versions.py b/.github/scripts/cleanup_test_container_versions.py
index bfc3fb48a..249ffeb91 100644
--- a/.github/scripts/cleanup_test_container_versions.py
+++ b/.github/scripts/cleanup_test_container_versions.py
@@ -1,5 +1,3 @@
-#!/usr/bin/env python3
-
 from __future__ import annotations
 
 import argparse
diff --git a/.github/scripts/companion_build_required.py b/.github/scripts/companion_build_required.py
index e77ad234a..2a3b27e13 100644
--- a/.github/scripts/companion_build_required.py
+++ b/.github/scripts/companion_build_required.py
@@ -1,4 +1,3 @@
-#!/usr/bin/env python3
 """Decide whether a pull request needs the expensive companion package build."""
 
 from __future__ import annotations
diff --git a/.github/scripts/manage_companion_artifact_manifest.py b/.github/scripts/manage_companion_artifact_manifest.py
index f227dc175..60c9206d9 100644
--- a/.github/scripts/manage_companion_artifact_manifest.py
+++ b/.github/scripts/manage_companion_artifact_manifest.py
@@ -1,4 +1,3 @@
-#!/usr/bin/env python3
 """Create and verify immutable Companion package artifact manifests."""
 
 from __future__ import annotations
diff --git a/.github/scripts/prepare_release_candidate.py b/.github/scripts/prepare_release_candidate.py
index 05139a821..51a9ccd6a 100644
--- a/.github/scripts/prepare_release_candidate.py
+++ b/.github/scripts/prepare_release_candidate.py
@@ -1,4 +1,3 @@
-#!/usr/bin/env python3
 """Reserve or resolve the immutable source commit for a publishable build."""
 
 from __future__ import annotations
diff --git a/.github/scripts/promote_companion_release.py b/.github/scripts/promote_companion_release.py
index 8fe8c060d..1b13aa440 100644
--- a/.github/scripts/promote_companion_release.py
+++ b/.github/scripts/promote_companion_release.py
@@ -1,5 +1,3 @@
-#!/usr/bin/env python3
-
 from __future__ import annotations
 
 import argparse
@@ -176,6 +174,8 @@ def request_asset_bytes(asset: dict, token: str | None = None) -> bytes:
                 with urllib.request.urlopen(request) as response:
                     return response.read()
             except urllib.error.URLError as error:
+                if isinstance(error, urllib.error.HTTPError):
+                    error.close()
                 if (
                     not is_retryable_asset_download_error(error)
                     or attempt == ASSET_DOWNLOAD_MAX_ATTEMPTS - 1
diff --git a/.github/scripts/resolve_companion_release_state.py b/.github/scripts/resolve_companion_release_state.py
index 627443ebb..187e61fb8 100644
--- a/.github/scripts/resolve_companion_release_state.py
+++ b/.github/scripts/resolve_companion_release_state.py
@@ -1,4 +1,3 @@
-#!/usr/bin/env python3
 """Resolve the immutable publication state for a Companion release tag."""
 
 from __future__ import annotations
diff --git a/.github/scripts/reuse_release_ci_tests.py b/.github/scripts/reuse_release_ci_tests.py
index 7447daa06..a173a9981 100644
--- a/.github/scripts/reuse_release_ci_tests.py
+++ b/.github/scripts/reuse_release_ci_tests.py
@@ -1,4 +1,3 @@
-#!/usr/bin/env python3
 """Reuse successful source checks from CI on the exact release commit."""
 
 from __future__ import annotations
@@ -15,6 +14,9 @@
 CI_WORKFLOW = "test.yml"
 API_TIMEOUT_SECONDS = 10
 JOBS_PER_PAGE = 100
+FRONTEND_REQUIRED_STEPS = frozenset(
+    {"Run browser correctness contracts", "Verify frontend type correctness"}
+)
 
 
 def github_get(url: str, token: str) -> dict[str, Any]:
@@ -63,10 +65,7 @@ def reusable_jobs(api_url: str, repository: str, sha: str, token: str) -> set[st
     successful: set[str] = set()
     page = 1
     while True:
-        jobs_url = (
-            f"{api_url}/repos/{repository}/actions/runs/{run_id}/jobs?"
-            f"filter=latest&per_page={JOBS_PER_PAGE}&page={page}"
-        )
+        jobs_url = f"{api_url}/repos/{repository}/actions/runs/{run_id}/jobs?filter=latest&per_page={JOBS_PER_PAGE}&page={page}"
         jobs = github_get(jobs_url, token).get("jobs")
         if not isinstance(jobs, list):
             raise ValueError("CI workflow jobs response is missing jobs")
@@ -74,6 +73,19 @@ def reusable_jobs(api_url: str, repository: str, sha: str, token: str) -> set[st
             if not isinstance(job, dict):
                 raise ValueError("CI workflow job is not an object")
             if job.get("name") in COMPONENTS and job.get("conclusion") == "success":
+                if job["name"] == "frontend":
+                    steps = job.get("steps", [])
+                    if not isinstance(steps, list):
+                        raise ValueError("Frontend CI job steps are not a list")
+                    successful_steps = {
+                        step.get("name")
+                        for step in steps
+                        if isinstance(step, dict)
+                        and step.get("conclusion") == "success"
+                        and isinstance(step.get("name"), str)
+                    }
+                    if not FRONTEND_REQUIRED_STEPS <= successful_steps:
+                        continue
                 successful.add(job["name"])
         if len(jobs) < JOBS_PER_PAGE:
             return successful
diff --git a/.github/scripts/should_promote_beta_tag.py b/.github/scripts/should_promote_beta_tag.py
index bb3afdb70..17efa1be5 100644
--- a/.github/scripts/should_promote_beta_tag.py
+++ b/.github/scripts/should_promote_beta_tag.py
@@ -1,5 +1,3 @@
-#!/usr/bin/env python3
-
 from __future__ import annotations
 
 import argparse
diff --git a/.github/scripts/validate_release_scope.py b/.github/scripts/validate_release_scope.py
index 7d715d596..b240af84c 100644
--- a/.github/scripts/validate_release_scope.py
+++ b/.github/scripts/validate_release_scope.py
@@ -1,4 +1,3 @@
-#!/usr/bin/env python3
 """Validate a public Sambee release's component-promotion scope."""
 
 from __future__ import annotations
diff --git a/.github/workflows/devcontainer-validate.yml b/.github/workflows/devcontainer-validate.yml
index bf2a4d0d2..9d1cc7bf0 100644
--- a/.github/workflows/devcontainer-validate.yml
+++ b/.github/workflows/devcontainer-validate.yml
@@ -33,7 +33,7 @@ permissions:
 
 jobs:
   prepare:
-    runs-on: ubuntu-24.04
+    runs-on: ubuntu-latest
     outputs:
       os_packages_refresh_key: ${{ steps.metadata.outputs.os_packages_refresh_key }}
     steps:
@@ -44,7 +44,7 @@ jobs:
 
   validate-devcontainer:
     needs: prepare
-    runs-on: ubuntu-24.04
+    runs-on: ubuntu-latest
     steps:
     - name: Checkout code
       uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
diff --git a/.github/workflows/docker-image-preview-publish.yml b/.github/workflows/docker-image-preview-publish.yml
index b68394690..c724d5638 100644
--- a/.github/workflows/docker-image-preview-publish.yml
+++ b/.github/workflows/docker-image-preview-publish.yml
@@ -222,14 +222,36 @@ jobs:
       if: steps.source-ci.outputs.frontend != 'true'
       run: cd frontend && npm ci --prefer-offline
 
-    - name: Run frontend type checks
+    - name: Verify frontend type correctness
       if: steps.source-ci.outputs.frontend != 'true'
-      run: cd frontend && npx tsc --noEmit
+      id: frontend-types
+      run: cd frontend && npm run typecheck
 
     - name: Run frontend tests
       if: steps.source-ci.outputs.frontend != 'true'
       run: cd frontend && npm run test:ci
 
+    - name: Build production frontend for browser checks
+      if: steps.source-ci.outputs.frontend != 'true'
+      run: cd frontend && npm run build
+
+    - name: Install browser dependencies
+      if: steps.source-ci.outputs.frontend != 'true'
+      run: cd frontend && npm run test:e2e:install -- --with-deps
+
+    - name: Run browser correctness contracts
+      if: steps.source-ci.outputs.frontend != 'true'
+      run: cd frontend && npm run test:browser:ci
+
+    - name: Upload browser correctness reports
+      if: ${{ !cancelled() && steps.source-ci.outputs.frontend != 'true' }}
+      uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+      with:
+        name: release-browser-correctness
+        path: frontend/test-results/ci/
+        retention-days: 7
+        if-no-files-found: warn
+
   build-and-validate-platforms:
     needs: [prepare, validate-tests]
     if: ${{ needs.prepare.outputs.publication_state == 'build' }}
@@ -243,10 +265,10 @@ jobs:
         include:
           - docker_platform: linux/amd64
             platform_id: amd64
-            runner_label: ubuntu-24.04
+            runner_label: ubuntu-latest
           - docker_platform: linux/arm64
             platform_id: arm64
-            runner_label: ubuntu-24.04-arm
+            runner_label: ubuntu-26.04-arm
     steps:
     - name: Checkout source code
       uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
@@ -564,10 +586,10 @@ jobs:
         include:
           - docker_platform: linux/amd64
             platform_id: amd64
-            runner_label: ubuntu-24.04
+            runner_label: ubuntu-latest
           - docker_platform: linux/arm64
             platform_id: arm64
-            runner_label: ubuntu-24.04-arm
+            runner_label: ubuntu-26.04-arm
     steps:
     - name: Checkout source code
       uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
diff --git a/.github/workflows/docker-image-publish.yml b/.github/workflows/docker-image-publish.yml
index a9a67beab..406c1db42 100644
--- a/.github/workflows/docker-image-publish.yml
+++ b/.github/workflows/docker-image-publish.yml
@@ -23,7 +23,7 @@ permissions:
 
 jobs:
   prepare:
-    runs-on: ubuntu-24.04
+    runs-on: ubuntu-latest
     outputs:
       checkout_ref: ${{ steps.metadata.outputs.checkout_ref }}
       release_type: ${{ steps.metadata.outputs.release_type }}
diff --git a/.github/workflows/docker-image-security-scan.yml b/.github/workflows/docker-image-security-scan.yml
index 58c4304a3..5d52ab485 100644
--- a/.github/workflows/docker-image-security-scan.yml
+++ b/.github/workflows/docker-image-security-scan.yml
@@ -17,7 +17,7 @@ permissions:
 
 jobs:
   prepare:
-    runs-on: ubuntu-24.04
+    runs-on: ubuntu-latest
     outputs:
       created: ${{ steps.metadata.outputs.created }}
       os_packages_refresh_key: ${{ steps.metadata.outputs.os_packages_refresh_key }}
@@ -39,10 +39,10 @@ jobs:
         include:
           - docker_platform: linux/amd64
             platform_id: amd64
-            runner_label: ubuntu-24.04
+            runner_label: ubuntu-latest
           - docker_platform: linux/arm64
             platform_id: arm64
-            runner_label: ubuntu-24.04-arm
+            runner_label: ubuntu-26.04-arm
     steps:
     - name: Checkout main
       uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
diff --git a/.github/workflows/docker-image-validate.yml b/.github/workflows/docker-image-validate.yml
index 9525c460e..f3b90a719 100644
--- a/.github/workflows/docker-image-validate.yml
+++ b/.github/workflows/docker-image-validate.yml
@@ -81,7 +81,7 @@ permissions:
 
 jobs:
   prepare:
-    runs-on: ubuntu-24.04
+    runs-on: ubuntu-latest
     outputs:
       created: ${{ steps.metadata.outputs.created }}
       os_packages_refresh_key: ${{ steps.metadata.outputs.os_packages_refresh_key }}
@@ -103,10 +103,10 @@ jobs:
         include:
           - docker_platform: linux/amd64
             platform_id: amd64
-            runner_label: ubuntu-24.04
+            runner_label: ubuntu-latest
           - docker_platform: linux/arm64
             platform_id: arm64
-            runner_label: ubuntu-24.04-arm
+            runner_label: ubuntu-26.04-arm
     steps:
     - name: Checkout code
       uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
index 5e7b16960..9f4eb00b3 100644
--- a/.github/workflows/lint.yml
+++ b/.github/workflows/lint.yml
@@ -10,6 +10,10 @@ on:
     branches: [ main ]
   workflow_dispatch:
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.run_id }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
 jobs:
   # ─────────────────────────────────────────────────────────────────────
   # Detect which components changed
@@ -42,6 +46,8 @@ jobs:
         }
         backend_extras = {
           "Dockerfile",
+          ".github/workflows/lint.yml",
+          "scripts/test",
           "scripts/verify-backend-lockfiles.py",
           "scripts/verify-python-runtime-image.py",
           ".github/actions/setup-runtime-python/action.yml",
@@ -117,7 +123,7 @@ jobs:
         else:
             raise SystemExit(f"Unsupported event for change detection: {event_name}")
 
-        backend = any(name.startswith("backend/") or name in backend_extras for name in filenames)
+        backend = any(name.startswith("backend/") or name.endswith(".py") or name in backend_extras for name in filenames)
         frontend = any(name.startswith("frontend/") or name in frontend_extras for name in filenames)
         companion = any(name.startswith("companion/") or name in companion_extras for name in filenames)
 
@@ -152,6 +158,9 @@ jobs:
     - name: Ruff check
       run: cd backend && ruff check app tests/test_verify_backend_lockfiles_script.py ../scripts/verify-backend-lockfiles.py
 
+    - name: Ruff executable-script check
+      run: python -m ruff check --select EXE . .github
+
     - name: Ruff format check
       run: cd backend && ruff format --check app tests/test_verify_backend_lockfiles_script.py ../scripts/verify-backend-lockfiles.py
 
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 4195e9b57..ce60c01b3 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -10,6 +10,10 @@ on:
     branches: [ main ]
   workflow_dispatch:
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.run_id }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
 jobs:
   # ──────────────────────────────────────────────
   # Detect which components changed
@@ -76,7 +80,7 @@ jobs:
   backend:
     needs: changes
     if: needs.changes.outputs.backend == 'true' || github.event_name == 'workflow_dispatch'
-    runs-on: ubuntu-24.04
+    runs-on: ubuntu-latest
     steps:
     - name: Checkout code
       uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
@@ -148,6 +152,7 @@ jobs:
     needs: changes
     if: needs.changes.outputs.frontend == 'true' || github.event_name == 'workflow_dispatch'
     runs-on: ubuntu-latest
+    timeout-minutes: 20
     steps:
     - name: Checkout code
       uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
@@ -176,12 +181,31 @@ jobs:
     - name: Install dependencies
       run: cd frontend && npm ci --prefer-offline
 
-    - name: TypeScript type check
-      run: cd frontend && npx tsc --noEmit
+    - name: Verify frontend type correctness
+      id: frontend-types
+      run: cd frontend && npm run typecheck
 
     - name: Run tests
       run: cd frontend && npm run test:ci
 
+    - name: Build production frontend
+      run: cd frontend && npm run build
+
+    - name: Install browser dependencies
+      run: cd frontend && npm run test:e2e:install -- --with-deps
+
+    - name: Run browser correctness contracts
+      run: cd frontend && npm run test:browser:ci
+
+    - name: Upload browser correctness reports
+      if: ${{ !cancelled() }}
+      uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+      with:
+        name: frontend-browser-correctness
+        path: frontend/test-results/ci/
+        retention-days: 7
+        if-no-files-found: warn
+
   # ──────────────────────────────────────────────
   # Companion: Node.js + Rust + Tauri tests
   # ──────────────────────────────────────────────
@@ -241,17 +265,12 @@ jobs:
     needs: [changes, backend, frontend, companion, website-docs]
     runs-on: ubuntu-latest
     steps:
+    - name: Checkout gate script
+      uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
     - name: Check results
+      env:
+        NEEDS_JSON: ${{ toJSON(needs) }}
+        EVENT_NAME: ${{ github.event_name }}
       run: |
-        if [[ "${{ needs.changes.result }}" != "success" ]]; then
-          echo "Change detection failed or was cancelled: ${{ needs.changes.result }}"
-          exit 1
-        fi
-        results="${{ needs.backend.result }} ${{ needs.frontend.result }} ${{ needs.companion.result }} ${{ needs.website-docs.result }}"
-        for r in $results; do
-          if [[ "$r" != "success" && "$r" != "skipped" ]]; then
-            echo "Job failed or was cancelled: $r"
-            exit 1
-          fi
-        done
-        echo "All tests passed or were skipped."
+        python3 scripts/check_ci_test_gate.py
diff --git a/.vscode/settings.json b/.vscode/settings.json
index 4e7a4da06..30020f020 100644
--- a/.vscode/settings.json
+++ b/.vscode/settings.json
@@ -107,116 +107,7 @@
   "js/ts.tsdk.path": "frontend/node_modules/typescript/lib",
   "js/ts.tsdk.promptToUseWorkspaceVersion": true,
   "js/ts.suggestionActions.enabled": false,
-  // GitHub Copilot Auto-Approve Commands
-  // Notes:
-  // - Regexes apply to subcommands individually, e.g.: sub-command-A && sub-command-B
-  // - If matchCommandLine is true, the match is applied to the entire command line
-  //   - This should only be used with start and end anchors, e.g. /^git status$/
-  //   - Since AI often varies the exact command line, matchCommandLine is not useful.
-  "chat.tools.terminal.autoApprove": {
-    // Local inspection
-    "basename": true,
-    "cat": true,
-    "cd": true,
-    "cut": true,
-    "date": true,
-    "df": true,
-    "dirname": true,
-    "du": true,
-    "echo": true,
-    "env": true,
-    "exit": true,
-    "file": true,
-    "grep": true,
-    "head": true,
-    "jq": true,
-    "ls": true,
-    "lsof": true,
-    "pgrep": true,
-    "printenv": true,
-    "ps": true,
-    "pwd": true,
-    "sort": true,
-    "stat": true,
-    "tail": true,
-    "tree": true,
-    "type": true,
-    "uniq": true,
-    "uptime": true,
-    "wc": true,
-    "which": true,
-    "who": true,
-    // Read-only Git inspection
-    "/^git(?:\\s+--no-pager)?\\s+(?:status|diff|log|show|branch|blame|rev-parse|ls-files|ls-remote|ls-tree|describe|tag|remote)\\b/": true,
-    // HTTP GET/HEAD with common non-mutating curl options.
-    // POST, PUT, DELETE, forms, uploads, output files, and custom
-    // request methods do not match and therefore require approval.
-    "/^curl\\s+(?:(?:-[fsSLI]+|--(?:fail|fail-with-body|silent|show-error|location|head|compressed))\\s+)*(?:['\\\"]?https?:\\/\\/[^\\s'\\\"]+['\\\"]?)(?:\\s+['\\\"]?https?:\\/\\/[^\\s'\\\"]+['\\\"]?)*$/": true,
-    // wget may inspect a URL or write the response only to stdout.
-    "/^wget\\s+(?:-qO-|--spider)\\s+['\\\"]?https?:\\/\\/[^\\s'\\\"]+['\\\"]?$/": true,
-    // DNS and reachability queries
-    "/^(dig|host|nslookup|ping)\\b/": true,
-    // Read-only package registry queries
-    "/^cargo\\s+search\\b/": true,
-    "/^pip3?\\s+index\\s+versions\\b/": true,
-    // Python tests and static analysis
-    "mypy": true,
-    "pytest": true,
-    // Virtualenv Python
-    "/^((\\.(\\.)?\\/|\\/workspace\\/)?backend\\/|\\.\\/)?\\.venv\\/bin\\/python\\s+-c\\s+\\'import\\s+/": true,
-    "/^((\\.(\\.)?\\/|\\/workspace\\/)?backend\\/|\\.\\/)?\\.venv\\/bin\\/python\\s+-m\\s+(compileall|json.tool|mypy|py_compile|pytest|ruff)\\b/": true,
-    "ruff": true,
-    "/^python3 -m (json.tool|unittest)\\b/": true,
-    // Frontend tests and static analysis
-    "npm test": true,
-    "npx vitest": true,
-    "npx tsc": true,
-    "npx biome": true,
-    "/^((\\.(\\.)?\\/|\\/workspace\\/)?node_modules\\/|\\.\\/)?\\.bin\\/biome\\s+(check|format)\\b/": true,
-    "/^((\\.(\\.)?\\/|\\/workspace\\/)?node_modules\\/|\\.\\/)?\\.bin\\/tsc\\b/": true,
-    // Frontend validation and builds
-    "/^npm(\\s+--prefix\\s+\\/workspace\\/frontend)?\\s+run\\s+(?:build|check|docs\\:validate|format|info|lint|redirects\\:generate|search|test(\\:.+)?|typecheck|view)\\b/": true,
-    // Rust validation and read-only inspection
-    "rustfmt": true,
-    "/^cargo\\s+(?:test|check|clippy|fmt|metadata|tree|doc)\\b/": true,
-    // Known repository validation scripts
-    "/^(?:\\.(\\.)?\\/)?scripts\\/(?:lint|test|format)(?:\\s|$)/": true,
-    "/^(?:\\.(\\.)?\\/)?scripts\\/(?:test-archive-topology-conformance)(?:\\s|$)/": true,
-    "/^python3\\s+scripts\\/(?:generate-managed-redirects|update-docs-derived-artifacts|verify-archive-single-worker)\\.py(?:\\s|$)/": true,
-    "/^python3\\s+(?:website\\/)?scripts\\/(?:docs-report|docs-editor|validate-docs-content)\\.py(?:\\s|$)/": true,
-    // Always require approval for destructive or privileged tools
-    "chmod": false,
-    "chown": false,
-    "dd": false,
-    "del": false,
-    "docker": false,
-    "kill": false,
-    "mkfs": false,
-    "mount": false,
-    "podman": false,
-    "rm": false,
-    "rmdir": false,
-    "sudo": false,
-    "su": false,
-    "umount": false,
-    // Require approval for remote access and transfer tools
-    "ftp": false,
-    "rsync": false,
-    "scp": false,
-    "sftp": false,
-    "ssh": false,
-    // Require approval for package installation or arbitrary execution
-    "apt": false,
-    "apt-get": false,
-    "corepack": false,
-    "pnpm": false,
-    "yarn": false,
-    // Require approval for Git writes and working-tree changes
-    "/^git(?:\\s+--no-pager)?\\s+(?:add|apply|bisect|checkout|cherry-pick|clean|clone|commit|fetch|merge|mv|pull|push|rebase|reset|restore|revert|rm|stash|switch|worktree)\\b/": false,
-    // Require approval for dependency and publishing operations
-    "/^npm\\s+(?:ci|install|uninstall|remove|update|publish|exec)\\b/": false,
-    "/^cargo\\s+(?:add|clean|fix|install|login|logout|new|init|package|publish|remove|run|update|watch)\\b/": false
-  },
+  // Color customization
   "workbench.colorCustomizations": {
     "activityBar.activeBackground": "#F4C430",
     "activityBar.background": "#F4C430",
@@ -243,5 +134,7 @@
     "statusBar.debuggingBackground": "#f4c430",
     "statusBar.debuggingForeground": "#15202b"
   },
-  "peacock.remoteColor": "#F4C430"
+  // Copilot and Chat Settings: allow automatic approval and terminal file writes (this is a devcontainer)
+  "chat.permissions.default": "autoApprove",
+  "chat.tools.terminal.blockDetectedFileWrites": "never"
 }
diff --git a/.vscode/tasks.json b/.vscode/tasks.json
index e6f35d5a6..5d339f7cd 100644
--- a/.vscode/tasks.json
+++ b/.vscode/tasks.json
@@ -138,7 +138,7 @@
     {
       "label": "Frontend: Type Check + Lint",
       "type": "shell",
-      "command": "npx tsc --noEmit 2>&1 && echo '✓ TypeScript type check passed' && npm run lint 2>&1 && echo '✓ Biome lint passed' && echo '' && echo '══════════════════════════════════' && echo '  All frontend checks passed ✓' && echo '══════════════════════════════════'",
+      "command": "npm run typecheck 2>&1 && echo '✓ TypeScript type check passed' && npm run lint 2>&1 && echo '✓ Biome lint passed' && echo '' && echo '══════════════════════════════════' && echo '  All frontend checks passed ✓' && echo '══════════════════════════════════'",
       "options": {
         "cwd": "${workspaceFolder}/frontend"
       },
diff --git a/TODO.md b/TODO.md
index 96a25b56b..fc5814e63 100644
--- a/TODO.md
+++ b/TODO.md
@@ -1,5 +1,14 @@
 # TODO
 
+## Bugs
+
+- Search in Markdown editor:
+   - Search terms aren't added to the search history
+
+## To improve soon
+
+- Vite production-build warning: one or more generated JavaScript chunks exceed 500 kB before gzip compression.
+
 ## Misc. commands
 
 - Add a command to open the current file list location in a new browser tab (which keyboard shortcut to assign? Ctrl+(Shift)+Tab is needed by the browser)
diff --git a/VERSION b/VERSION
index 82bd22f9c..3d45b5c65 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-2.0.13
+2.0.14
diff --git a/backend/app/api/themes.py b/backend/app/api/themes.py
index ab313d04d..0dec198f3 100644
--- a/backend/app/api/themes.py
+++ b/backend/app/api/themes.py
@@ -29,6 +29,7 @@
     "text": ("primary", "secondary"),
     "action": ("selected",),
     "components": {
+        "syntax": ("keyword", "string", "number", "comment", "type", "function", "operator", "punctuation"),
         "link": ("main", "hover"),
         "search": ("otherMatch", "currentMatch"),
         "pdfViewer": ("viewerBackground", "toolbarBackground", "toolbarText"),
@@ -71,6 +72,8 @@ def _validate_colors(value: Any, shape: Any, path: str = "") -> None:
     if not isinstance(value, dict):
         raise ValueError(f"{path} must contain all color roles")
     for key, child_shape in shape.items():
+        if path == "components" and key == "syntax" and key not in value:
+            continue
         if key not in value:
             raise ValueError(f"Missing color role: {path}.{key}".lstrip("."))
         _validate_colors(value[key], child_shape, f"{path}.{key}".lstrip("."))
diff --git a/backend/app/api/viewer.py b/backend/app/api/viewer.py
index 5d763cc03..ddcb5374c 100644
--- a/backend/app/api/viewer.py
+++ b/backend/app/api/viewer.py
@@ -243,7 +243,7 @@ async def stream_archive_member(
         inspection_projection = presentation.project_member(inspection_member)
         if inspection_projection.delivery == "preview_unavailable":
             raise HTTPException(
-                status_code=status.HTTP_413_REQUEST_ENTITY_TOO_LARGE, detail="Archive member exceeds the inline preview size limit"
+                status_code=status.HTTP_413_CONTENT_TOO_LARGE, detail="Archive member exceeds the inline preview size limit"
             )
         member_name = inspection_member.path.rsplit("/", 1)[-1]
 
@@ -528,7 +528,7 @@ async def create_normalized_pdf_response_for_source(
     max_source_size = get_integer_setting_value(SystemSettingKey.PDF_NORMALIZER_MAX_SOURCE_SIZE_BYTES)
     if metadata_revision.size is not None and metadata_revision.size > max_source_size:
         raise HTTPException(
-            status_code=status.HTTP_413_REQUEST_ENTITY_TOO_LARGE,
+            status_code=status.HTTP_413_CONTENT_TOO_LARGE,
             detail="This PDF exceeds the configured compatibility-processing size limit.",
         )
 
@@ -585,7 +585,7 @@ async def create_normalized_pdf_response_for_source(
     pdf_bytes, revision = await read_source()
     if len(pdf_bytes) > max_source_size:
         raise HTTPException(
-            status_code=status.HTTP_413_REQUEST_ENTITY_TOO_LARGE,
+            status_code=status.HTTP_413_CONTENT_TOO_LARGE,
             detail="This PDF exceeds the configured compatibility-processing size limit.",
         )
 
@@ -783,7 +783,7 @@ async def create_converted_image_response(
         file_size_mb = exc.file_size / (1024 * 1024)
         max_file_size_mb = exc.max_file_size / (1024 * 1024)
         raise HTTPException(
-            status_code=status.HTTP_413_REQUEST_ENTITY_TOO_LARGE,
+            status_code=status.HTTP_413_CONTENT_TOO_LARGE,
             detail={
                 "code": "image_preview_too_large",
                 "message": f"This image is too large to preview ({file_size_mb:.0f} MB; maximum {max_file_size_mb:.0f} MB).",
diff --git a/backend/pyproject.toml b/backend/pyproject.toml
index 010dc1130..12e0784f9 100644
--- a/backend/pyproject.toml
+++ b/backend/pyproject.toml
@@ -9,7 +9,6 @@ addopts = [
     "--strict-config",
     "--tb=short",
     "-q",
-    "--disable-warnings",
 ]
 log_cli = false
 log_level = "ERROR"
@@ -22,8 +21,7 @@ markers = [
     "security: Security vulnerability tests",
 ]
 filterwarnings = [
-    # Ignore resource warnings from test cleanup (handled in fixtures)
-    "ignore::ResourceWarning",
+    "error",
     # Starlette 1.6.0's TestClient still references AnyIO's deprecated alias.
     "ignore:The anyio\\.abc\\.BlockingPortal alias is deprecated, use anyio\\.from_thread\\.BlockingPortal instead\\.:DeprecationWarning:starlette\\.testclient",
 ]
@@ -55,7 +53,7 @@ indent-style = "space"
 
 [tool.ruff.lint]
 # Only enable essential rules (no extended plugins)
-select = ["E4", "E7", "E9", "F", "I"]
+select = ["E4", "E7", "E9", "EXE", "F", "I"]
 ignore = [
     "E501", # line too long handled by formatter/tests
 ]
diff --git a/backend/tests/test_archive_extraction.py b/backend/tests/test_archive_extraction.py
index 46371bde0..f383c7a72 100644
--- a/backend/tests/test_archive_extraction.py
+++ b/backend/tests/test_archive_extraction.py
@@ -851,7 +851,8 @@ async def test_live_source_selects_the_last_duplicate_record() -> None:
     output = io.BytesIO()
     with zipfile.ZipFile(output, "w", compression=zipfile.ZIP_DEFLATED) as archive:
         archive.writestr("duplicate.txt", "first")
-        archive.writestr("duplicate.txt", "last")
+        with pytest.warns(UserWarning, match=r"^Duplicate name: 'duplicate\.txt'$"):
+            archive.writestr("duplicate.txt", "last")
     backend = MemoryExtractionBackend(output.getvalue())
 
     source_session = LiveSourceSession(ZipReader(backend.reader, len(backend.archive)))
diff --git a/backend/tests/test_archive_zip_reader.py b/backend/tests/test_archive_zip_reader.py
index 4d46ac81a..623ca187b 100644
--- a/backend/tests/test_archive_zip_reader.py
+++ b/backend/tests/test_archive_zip_reader.py
@@ -75,7 +75,8 @@ def _duplicate_name_zip_bytes() -> bytes:
     buffer = io.BytesIO()
     with zipfile.ZipFile(buffer, "w", compression=zipfile.ZIP_STORED) as archive:
         archive.writestr("duplicate.txt", b"first")
-        archive.writestr("duplicate.txt", b"second entry")
+        with pytest.warns(UserWarning, match=r"^Duplicate name: 'duplicate\.txt'$"):
+            archive.writestr("duplicate.txt", b"second entry")
     return buffer.getvalue()
 
 
diff --git a/backend/tests/test_ci_change_detector.py b/backend/tests/test_ci_change_detector.py
index ebca1e2a3..7fe6fb09d 100644
--- a/backend/tests/test_ci_change_detector.py
+++ b/backend/tests/test_ci_change_detector.py
@@ -1,15 +1,19 @@
 """Regression tests for CI component selection."""
 
+import ast
 import json
+import re
 import sys
 from pathlib import Path
 from typing import Any
 
 import pytest
+import yaml
 
 sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "scripts"))
 
 import ci_change_detector
+from check_ci_test_gate import COMPONENT_JOBS, gate_errors
 from ci_change_detector import ARCHIVE_TOPOLOGY_PATHS, FULL_TREE_DIFF_BASE, classify_paths
 
 
@@ -51,6 +55,94 @@ def test_non_topology_component_changes_remain_selective() -> None:
     }
 
 
+@pytest.mark.parametrize("path", sorted(ci_change_detector.FRONTEND_EXTRAS))
+def test_frontend_ci_infrastructure_runs_frontend_checks(path: str) -> None:
+    assert classify_paths([path])["frontend"]
+
+
+def test_workflows_use_latest_x64_and_supported_arm_ubuntu_labels() -> None:
+    workflows = Path(__file__).resolve().parents[2] / ".github/workflows"
+    allowed = {"ubuntu-latest", "ubuntu-26.04-arm"}
+    for workflow in workflows.glob("*.yml"):
+        source = workflow.read_text()
+        assert isinstance(yaml.safe_load(source)["jobs"], dict), workflow.name
+        labels = set(re.findall(r"ubuntu-[\w.-]+", source))
+        assert labels <= allowed, f"{workflow.name}: unexpected Ubuntu labels {labels - allowed}"
+
+
+@pytest.mark.parametrize(
+    ("path", "requires_lint"),
+    [
+        ("backend/app/main.py", True),
+        (".github/scripts/promote_companion_release.py", True),
+        ("website/scripts/validate-docs-content.py", True),
+        ("scripts/ci_change_detector.py", True),
+        (".github/workflows/lint.yml", True),
+        ("scripts/test", True),
+        ("frontend/src/App.tsx", False),
+    ],
+)
+def test_python_and_lint_infrastructure_changes_schedule_backend_lint(path: str, requires_lint: bool) -> None:
+    workflow_path = Path(__file__).resolve().parents[2] / ".github/workflows/lint.yml"
+    workflow = yaml.safe_load(workflow_path.read_text())
+    detector = ast.parse(workflow["jobs"]["changes"]["steps"][0]["run"].split("\n", 1)[1].rsplit("\nPY", 1)[0])
+    selection = ast.Module(
+        body=[
+            statement
+            for statement in detector.body
+            if isinstance(statement, ast.Assign)
+            and any(isinstance(target, ast.Name) and target.id in {"backend_extras", "backend"} for target in statement.targets)
+        ],
+        type_ignores=[],
+    )
+    namespace: dict[str, Any] = {"filenames": [path]}
+    exec(compile(selection, str(workflow_path), "exec"), namespace)
+    assert namespace["backend"] is requires_lint
+
+
+def test_executable_script_lint_is_required_in_ci_and_local_validation() -> None:
+    workspace = Path(__file__).resolve().parents[2]
+    workflow = yaml.safe_load((workspace / ".github/workflows/lint.yml").read_text())
+    steps = workflow["jobs"]["lint-backend"]["steps"]
+    executable_check = next(step for step in steps if step.get("name") == "Ruff executable-script check")
+    assert executable_check["run"] == "python -m ruff check --select EXE . .github"
+    assert not executable_check.get("continue-on-error", False)
+    local_runner = (workspace / "scripts/test").read_text()
+    assert 'run_check "Ruff executable-script checks passed" "Ruff executable-script checks failed"' in local_runner
+    assert '"$BACKEND_PYTHON" -m ruff check --select EXE "$REPO_ROOT" "$REPO_ROOT/.github"' in local_runner
+
+
+def test_gate_requires_selected_components_and_allows_intentional_skips() -> None:
+    needs = {"changes": {"result": "success", "outputs": {component: "false" for component in COMPONENT_JOBS}}}
+    needs.update({job: {"result": "skipped"} for job in COMPONENT_JOBS.values()})
+    assert gate_errors(needs, "pull_request") == []
+    needs["changes"]["outputs"]["frontend"] = "true"
+    assert gate_errors(needs, "pull_request") == ["Required frontend job did not succeed: skipped"]
+    needs["frontend"]["result"] = "success"
+    assert gate_errors(needs, "pull_request") == []
+    assert gate_errors(needs, "workflow_dispatch")
+
+
+@pytest.mark.parametrize("name", ["test.yml", "lint.yml"])
+def test_only_superseded_pr_checks_are_cancelled(name: str) -> None:
+    source = Path(__file__).resolve().parents[2] / ".github/workflows" / name
+    concurrency = yaml.safe_load(source.read_text())["concurrency"]
+    assert "github.event.pull_request.number || github.run_id" in concurrency["group"]
+    assert concurrency["cancel-in-progress"] == "${{ github.event_name == 'pull_request' }}"
+
+
+@pytest.mark.parametrize("result", ["failure", "cancelled", "skipped", None])
+def test_gate_rejects_failed_change_detection(result: str | None) -> None:
+    assert gate_errors({"changes": {"result": result}}, "push")
+
+
+def test_gate_rejects_missing_outputs_and_unselected_failures() -> None:
+    assert gate_errors({"changes": {"result": "success"}}, "push")
+    needs = {"changes": {"result": "success", "outputs": {component: "false" for component in COMPONENT_JOBS}}}
+    needs.update({job: {"result": "cancelled"} for job in COMPONENT_JOBS.values()})
+    assert len(gate_errors(needs, "push")) == len(COMPONENT_JOBS)
+
+
 @pytest.mark.parametrize(
     "path",
     [
diff --git a/backend/tests/test_native_markdown_pdf_check.py b/backend/tests/test_native_markdown_pdf_check.py
new file mode 100644
index 000000000..b8febeafa
--- /dev/null
+++ b/backend/tests/test_native_markdown_pdf_check.py
@@ -0,0 +1,116 @@
+import base64
+import json
+from importlib.util import module_from_spec, spec_from_file_location
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+
+SCRIPT = Path(__file__).parents[2] / "scripts/check_native_markdown_pdf.py"
+SPEC = spec_from_file_location("check_native_markdown_pdf", SCRIPT)
+assert SPEC and SPEC.loader
+MODULE = module_from_spec(SPEC)
+SPEC.loader.exec_module(MODULE)
+
+DOCUMENT = "Document start\nconst native = 42;\nDocument tail"
+
+
+def make_report() -> dict:
+    results = []
+    for fixture in ("multiline", "long-line", "nested"):
+        for width in (1543, 390):
+            evidence = {"fixture": fixture, "width": width, "engine": "chromium", "renderedText": DOCUMENT}
+            results.append(
+                {
+                    "attachments": [
+                        {"name": "native-constraints.json", "body": base64.b64encode(json.dumps(evidence).encode()).decode()},
+                        {"name": "native.pdf", "contentType": "application/pdf", "body": base64.b64encode(b"PDF fixture").decode()},
+                    ]
+                }
+            )
+    return {"stats": {"expected": 12, "unexpected": 0, "skipped": 0, "flaky": 0}, "suites": results}
+
+
+@pytest.mark.parametrize("missing", [False, True])
+def test_checks_pdf_document_content(monkeypatch, missing: bool) -> None:
+    text = "Document tail" if missing else DOCUMENT
+    monkeypatch.setattr(MODULE, "PdfReader", lambda stream: SimpleNamespace(pages=[SimpleNamespace(extract_text=lambda: text)]))
+    results = MODULE.inspect_report(make_report())
+    assert len(results) == 6
+    assert all(result["status"] == ("fail" if missing else "pass") for result in results)
+    assert all(result["missing_lines"] == (2 if missing else 0) for result in results)
+
+
+@pytest.mark.parametrize("failure", [None, "missing", "duplicate", "unexpected", "skipped", "flaky"])
+def test_cli_requires_complete_passing_evidence(tmp_path: Path, monkeypatch, failure: str | None) -> None:
+    monkeypatch.setattr(MODULE, "PdfReader", lambda stream: SimpleNamespace(pages=[SimpleNamespace(extract_text=lambda: DOCUMENT)]))
+    report = make_report()
+    if failure == "missing":
+        report["suites"].pop()
+    elif failure == "duplicate":
+        report["suites"].append(report["suites"][0])
+    elif failure is not None:
+        report["stats"][failure] = 1
+    path = tmp_path / "report.json"
+    path.write_text(json.dumps(report))
+    monkeypatch.setattr("sys.argv", [str(SCRIPT), str(path)])
+    assert MODULE.main() == (0 if failure is None else 1)
+
+
+def test_cli_rejects_invalid_pdf(tmp_path: Path, monkeypatch, capsys) -> None:
+    path = tmp_path / "report.json"
+    path.write_text(json.dumps(make_report()))
+    monkeypatch.setattr("sys.argv", [str(SCRIPT), str(path)])
+    assert MODULE.main() == 1
+    assert "Regenerate the Playwright JSON report" in capsys.readouterr().err
+
+
+def test_requires_one_pdf_per_chromium_case() -> None:
+    report = make_report()
+    report["suites"][0]["attachments"].pop()
+    with pytest.raises(ValueError, match="exactly one PDF"):
+        MODULE.inspect_report(report)
+
+
+def test_rejects_duplicate_contract_attachments() -> None:
+    report = make_report()
+    attachments = report["suites"][0]["attachments"]
+    attachments.append(attachments[0])
+    with pytest.raises(ValueError, match="exactly one contract"):
+        MODULE.inspect_report(report)
+
+
+def test_cli_rejects_missing_contract(tmp_path: Path, monkeypatch) -> None:
+    monkeypatch.setattr(MODULE, "PdfReader", lambda stream: SimpleNamespace(pages=[SimpleNamespace(extract_text=lambda: DOCUMENT)]))
+    report = make_report()
+    report["suites"][0]["attachments"].pop(0)
+    path = tmp_path / "report.json"
+    path.write_text(json.dumps(report))
+    monkeypatch.setattr("sys.argv", [str(SCRIPT), str(path)])
+    assert MODULE.main() == 1
+
+
+@pytest.mark.parametrize("failure", [None, "duplicate-mode", "missing-image"])
+def test_independent_print_matrix_requires_both_modes_and_images(tmp_path: Path, monkeypatch, failure: str | None) -> None:
+    report = make_report()
+    original = report["suites"]
+    report["suites"] = []
+    report["stats"]["expected"] = 24
+    for mode in ("light", "dark"):
+        for result in json.loads(json.dumps(original)):
+            attachment = result["attachments"][0]
+            evidence = json.loads(base64.b64decode(attachment["body"]))
+            evidence.update(mode="light" if failure == "duplicate-mode" else mode, requiresImages=True)
+            attachment.update(name="markdown-print.json", body=base64.b64encode(json.dumps(evidence).encode()).decode())
+            report["suites"].append(result)
+    monkeypatch.setattr(
+        MODULE,
+        "PdfReader",
+        lambda stream: SimpleNamespace(
+            pages=[SimpleNamespace(images=[] if failure == "missing-image" else [object()], extract_text=lambda: DOCUMENT)]
+        ),
+    )
+    path = tmp_path / "printing.json"
+    path.write_text(json.dumps(report))
+    monkeypatch.setattr("sys.argv", [str(SCRIPT), str(path), "--printing"])
+    assert MODULE.main() == (0 if failure is None else 1)
diff --git a/backend/tests/test_promote_companion_release_script.py b/backend/tests/test_promote_companion_release_script.py
index d95fb1b97..5945c7bcb 100644
--- a/backend/tests/test_promote_companion_release_script.py
+++ b/backend/tests/test_promote_companion_release_script.py
@@ -145,16 +145,52 @@ def urlopen(_request: object) -> io.BytesIO:
     assert retry_delays == [MODULE.ASSET_DOWNLOAD_INITIAL_RETRY_DELAY_SECONDS]
 
 
+@pytest.mark.parametrize("eventually_succeeds", [True, False])
+def test_request_asset_bytes_closes_http_errors_before_retrying(monkeypatch: pytest.MonkeyPatch, eventually_succeeds: bool) -> None:
+    asset = {"name": "manifest.json", "url": "https://api.github.test/asset"}
+    error_responses: list[io.BytesIO] = []
+    retry_delays: list[int] = []
+
+    def urlopen(_request: object) -> io.BytesIO:
+        if eventually_succeeds and error_responses:
+            return io.BytesIO(b"asset contents")
+        error_response = io.BytesIO(b"temporarily unavailable")
+        error_responses.append(error_response)
+        raise urllib.error.HTTPError(asset["url"], 503, "Service Unavailable", Message(), error_response)
+
+    def retry_sleep(delay: int) -> None:
+        assert error_responses[-1].closed
+        retry_delays.append(delay)
+
+    monkeypatch.setattr(MODULE.urllib.request, "urlopen", urlopen)
+    monkeypatch.setattr(MODULE.time, "sleep", retry_sleep)
+
+    if eventually_succeeds:
+        assert MODULE.request_asset_bytes(asset, "release-token") == b"asset contents"
+        assert len(error_responses) == 1
+    else:
+        with pytest.raises(SystemExit):
+            MODULE.request_asset_bytes(asset, "release-token")
+        assert len(error_responses) == MODULE.ASSET_DOWNLOAD_MAX_ATTEMPTS
+
+    assert all(response.closed for response in error_responses)
+    assert retry_delays == [
+        MODULE.ASSET_DOWNLOAD_INITIAL_RETRY_DELAY_SECONDS * (2**attempt)
+        for attempt in range(len(error_responses) - (not eventually_succeeds))
+    ]
+
+
 def test_request_asset_bytes_does_not_retry_permanent_http_failure(
     monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
 ) -> None:
     asset = {"name": "manifest.json", "url": "https://api.github.test/asset"}
     request_count = 0
+    error_response = io.BytesIO(b"not found")
 
     def urlopen(_request: object) -> io.BytesIO:
         nonlocal request_count
         request_count += 1
-        raise urllib.error.HTTPError(asset["url"], 404, "Not Found", Message(), io.BytesIO(b"not found"))
+        raise urllib.error.HTTPError(asset["url"], 404, "Not Found", Message(), error_response)
 
     monkeypatch.setattr(MODULE.urllib.request, "urlopen", urlopen)
     monkeypatch.setattr(
@@ -167,6 +203,7 @@ def urlopen(_request: object) -> io.BytesIO:
         MODULE.request_asset_bytes(asset, "release-token")
 
     assert request_count == 1
+    assert error_response.closed
     assert "after 1 attempt(s)" in capsys.readouterr().err
 
 
diff --git a/backend/tests/test_release_workflow_configuration.py b/backend/tests/test_release_workflow_configuration.py
index 88367fc12..1a27c9163 100644
--- a/backend/tests/test_release_workflow_configuration.py
+++ b/backend/tests/test_release_workflow_configuration.py
@@ -80,8 +80,11 @@ def test_docker_release_reuses_only_verified_source_ci_jobs() -> None:
     frontend_steps = (
         "Set up Node.js",
         "Install frontend dependencies",
-        "Run frontend type checks",
+        "Verify frontend type correctness",
         "Run frontend tests",
+        "Build production frontend for browser checks",
+        "Install browser dependencies",
+        "Run browser correctness contracts",
     )
     for component, names in (("backend", backend_steps), ("frontend", frontend_steps)):
         for name in names:
diff --git a/backend/tests/test_reuse_release_ci_tests.py b/backend/tests/test_reuse_release_ci_tests.py
index 9e6b28aeb..528b8786d 100644
--- a/backend/tests/test_reuse_release_ci_tests.py
+++ b/backend/tests/test_reuse_release_ci_tests.py
@@ -6,6 +6,7 @@
 from typing import Any
 
 import pytest
+import yaml
 
 sys.path.insert(0, str(Path(__file__).resolve().parents[2] / ".github/scripts"))
 
@@ -20,6 +21,15 @@
     "status": "completed",
     "conclusion": "success",
 }
+FRONTEND_JOB = {
+    "name": "frontend",
+    "conclusion": "success",
+    "steps": [{"name": name, "conclusion": "success"} for name in reuse_ci.FRONTEND_REQUIRED_STEPS],
+}
+FRONTEND_COMMANDS = {
+    "Run browser correctness contracts": "cd frontend && npm run test:browser:ci",
+    "Verify frontend type correctness": "cd frontend && npm run typecheck",
+}
 
 
 def run_lookup(monkeypatch: pytest.MonkeyPatch, responses: list[dict[str, Any]]) -> set[str]:
@@ -43,7 +53,7 @@ def test_reuse_both_successful_jobs(monkeypatch: pytest.MonkeyPatch) -> None:
         monkeypatch,
         [
             {"workflow_runs": [RUN]},
-            {"jobs": [{"name": "backend", "conclusion": "success"}, {"name": "frontend", "conclusion": "success"}]},
+            {"jobs": [{"name": "backend", "conclusion": "success"}, FRONTEND_JOB]},
         ],
     ) == {"backend", "frontend"}
 
@@ -53,11 +63,51 @@ def test_skipped_or_failed_jobs_are_not_reused(monkeypatch: pytest.MonkeyPatch)
         monkeypatch,
         [
             {"workflow_runs": [RUN]},
-            {"jobs": [{"name": "backend", "conclusion": "skipped"}, {"name": "frontend", "conclusion": "success"}]},
+            {"jobs": [{"name": "backend", "conclusion": "skipped"}, FRONTEND_JOB]},
         ],
     ) == {"frontend"}
 
 
+@pytest.mark.parametrize("conclusion", ["skipped", "failure", "cancelled", None])
+@pytest.mark.parametrize("required_step", FRONTEND_COMMANDS)
+def test_frontend_reuse_requires_each_successful_gate(monkeypatch: pytest.MonkeyPatch, conclusion: str | None, required_step: str) -> None:
+    job = {
+        **FRONTEND_JOB,
+        "steps": [{"name": name, "conclusion": conclusion if name == required_step else "success"} for name in FRONTEND_COMMANDS],
+    }
+    assert run_lookup(monkeypatch, [{"workflow_runs": [RUN]}, {"jobs": [job]}]) == set()
+
+
+@pytest.mark.parametrize("conclusion", ["success", "failure"])
+def test_legacy_advisory_type_check_is_not_release_evidence(monkeypatch: pytest.MonkeyPatch, conclusion: str) -> None:
+    job = {
+        **FRONTEND_JOB,
+        "steps": [
+            {"name": "Run browser correctness contracts", "conclusion": "success"},
+            {"name": "TypeScript type check", "conclusion": conclusion},
+        ],
+    }
+    assert run_lookup(monkeypatch, [{"workflow_runs": [RUN]}, {"jobs": [job]}]) == set()
+
+
+def test_legacy_frontend_job_without_browser_checks_is_not_reused(monkeypatch: pytest.MonkeyPatch) -> None:
+    assert run_lookup(monkeypatch, [{"workflow_runs": [RUN]}, {"jobs": [{"name": "frontend", "conclusion": "success"}]}]) == set()
+
+
+@pytest.mark.parametrize("name,job", [("test.yml", "frontend"), ("docker-image-preview-publish.yml", "validate-tests")])
+def test_ci_and_release_require_the_same_browser_contract(name: str, job: str) -> None:
+    assert reuse_ci.FRONTEND_REQUIRED_STEPS == FRONTEND_COMMANDS.keys()
+    source = Path(__file__).resolve().parents[2] / ".github/workflows" / name
+    steps = yaml.safe_load(source.read_text())["jobs"][job]["steps"]
+    browser_steps = [step for step in steps if step.get("name") in reuse_ci.FRONTEND_REQUIRED_STEPS]
+    assert len(browser_steps) == len(reuse_ci.FRONTEND_REQUIRED_STEPS)
+    assert all(step["run"] == FRONTEND_COMMANDS[step["name"]] and not step.get("continue-on-error") for step in browser_steps)
+    commands = [step.get("run") for step in steps]
+    assert "cd frontend && npm run build" in commands
+    assert "cd frontend && npm run test:e2e:install -- --with-deps" in commands
+    assert any(step.get("with", {}).get("path") == "frontend/test-results/ci/" and step["with"]["retention-days"] == 7 for step in steps)
+
+
 @pytest.mark.parametrize(
     "runs",
     [
diff --git a/backend/tests/test_user_settings.py b/backend/tests/test_user_settings.py
index 6f6348c62..6f052768b 100644
--- a/backend/tests/test_user_settings.py
+++ b/backend/tests/test_user_settings.py
@@ -1,6 +1,7 @@
 import json
 from types import SimpleNamespace
 
+import pytest
 from fastapi.testclient import TestClient
 from sqlmodel import Session, select
 
@@ -21,6 +22,38 @@ def colors(shape: object) -> object:
     return {"name": "Test theme", "description": "Test", "mode": "dark", **colors(COLOR_SHAPE)}
 
 
+def test_legacy_theme_preserves_absent_syntax_group(client: TestClient, auth_headers_user: dict[str, str]) -> None:
+    definition = complete_theme_definition()
+    del definition["components"]["syntax"]
+    response = client.post("/api/themes", headers=auth_headers_user, json={"scope": "user", "definition": definition})
+    assert response.status_code == 201, response.text
+    assert "syntax" not in response.json()["definition"]["components"]
+    listing = client.get("/api/themes", headers=auth_headers_user)
+    assert "syntax" not in listing.json()["themes"][0]["definition"]["components"]
+
+
+@pytest.mark.parametrize("syntax", [None, {}, {"keyword": "#123456"}, {"unknown": "#123456"}, "#123456"])
+def test_supplied_syntax_requires_complete_palette(client: TestClient, auth_headers_user: dict[str, str], syntax: object) -> None:
+    definition = complete_theme_definition()
+    definition["components"]["syntax"] = syntax
+    response = client.post("/api/themes", headers=auth_headers_user, json={"scope": "user", "definition": definition})
+    assert response.status_code == 422, response.text
+    assert "syntax" in response.json()["detail"]
+
+
+def test_syntax_palette_round_trip_and_strict_values(client: TestClient, auth_headers_user: dict[str, str]) -> None:
+    definition = complete_theme_definition()
+    definition["components"]["syntax"]["keyword"] = "#aabbccdd"
+    response = client.post("/api/themes", headers=auth_headers_user, json={"scope": "user", "definition": definition})
+    assert response.status_code == 201, response.text
+    assert response.json()["definition"]["components"]["syntax"]["keyword"] == "#AABBCCDD"
+    definition["components"]["syntax"]["keyword"] = "red"
+    assert client.post("/api/themes", headers=auth_headers_user, json={"scope": "user", "definition": definition}).status_code == 422
+    definition["components"]["syntax"]["keyword"] = "#aabbccdd"
+    definition["components"]["syntax"]["unknown"] = "#123456"
+    assert client.post("/api/themes", headers=auth_headers_user, json={"scope": "user", "definition": definition}).status_code == 422
+
+
 def test_theme_rows_permissions_versions_and_deletion(
     client: TestClient, auth_headers_user: dict[str, str], auth_headers_admin: dict[str, str]
 ) -> None:
diff --git a/companion/package-lock.json b/companion/package-lock.json
index ac981e842..617082bcf 100644
--- a/companion/package-lock.json
+++ b/companion/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "sambee-companion",
-  "version": "2.0.13",
+  "version": "2.0.14",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "sambee-companion",
-      "version": "2.0.13",
+      "version": "2.0.14",
       "dependencies": {
         "@tauri-apps/api": "^2.12.4",
         "@tauri-apps/plugin-autostart": "^2.7.0",
diff --git a/companion/package.json b/companion/package.json
index 8fb3d0b05..6a33ee07c 100644
--- a/companion/package.json
+++ b/companion/package.json
@@ -1,6 +1,6 @@
 {
   "name": "sambee-companion",
-  "version": "2.0.13",
+  "version": "2.0.14",
   "private": true,
   "type": "module",
   "scripts": {
diff --git a/companion/src-tauri/Cargo.lock b/companion/src-tauri/Cargo.lock
index a28885788..a976f8056 100644
--- a/companion/src-tauri/Cargo.lock
+++ b/companion/src-tauri/Cargo.lock
@@ -3768,7 +3768,7 @@ checksum = "9774ba4a74de5f7b1c1451ed6cd5285a32eddb5cccb8cc655a4e50009e06477f"
 
 [[package]]
 name = "sambee-companion"
-version = "2.0.13"
+version = "2.0.14"
 dependencies = [
  "axum",
  "base64 0.22.1",
diff --git a/companion/src-tauri/Cargo.toml b/companion/src-tauri/Cargo.toml
index 784ef486c..f48d3d17f 100644
--- a/companion/src-tauri/Cargo.toml
+++ b/companion/src-tauri/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "sambee-companion"
-version = "2.0.13"
+version = "2.0.14"
 edition = "2021"
 description = "Sambee Companion — opens files from Sambee in native desktop editors"
 authors = []
diff --git a/companion/src-tauri/tauri.conf.json b/companion/src-tauri/tauri.conf.json
index aa574b2e5..f7f1e1b50 100644
--- a/companion/src-tauri/tauri.conf.json
+++ b/companion/src-tauri/tauri.conf.json
@@ -2,7 +2,7 @@
   "$schema": "https://raw.githubusercontent.com/nicegui/tauri-v2-schema/refs/heads/main/tauri.conf.json.schema",
   "productName": "Sambee Companion",
   "identifier": "app.sambee.companion",
-  "version": "2.0.13",
+  "version": "2.0.14",
   "build": {
     "beforeDevCommand": "npm run dev",
     "devUrl": "http://localhost:1420",
diff --git a/frontend/e2e/markdown-viewer.spec.ts b/frontend/e2e/markdown-viewer.spec.ts
index f1977a8e0..f79b56d57 100644
--- a/frontend/e2e/markdown-viewer.spec.ts
+++ b/frontend/e2e/markdown-viewer.spec.ts
@@ -1,9 +1,54 @@
-import { expect, test, type Locator, type Page, type Route } from "@playwright/test";
+import { expect, test, type BrowserContext, type Locator, type Page, type Route, type TestInfo } from "@playwright/test";
+import { replaceAll as nativeReplaceAll, SearchQuery, search, setSearchQuery } from "@codemirror/search";
+import { EditorState, type TransactionSpec } from "@codemirror/state";
+import type { EditorView } from "@codemirror/view";
+import { readFile } from "node:fs/promises";
+import { createServer } from "node:http";
+import { extname, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { StoredTheme } from "../src/services/api";
+import { editableDefinition } from "../src/theme/themeDefinition";
+import { builtInThemes } from "../src/theme/themes";
+import { MARKDOWN_HEADING_ID_PREFIX } from "../src/utils/markdownHeadingLinks";
+import { SOURCE_SEARCH_CHUNK_UNITS } from "../src/components/Editor/sourceRegexSearchProtocol";
+import { evaluateSourceResponsivenessBudgets, evaluateSourceTypingBudgets, evaluateViewerReadinessBudgets, evaluateViewerTimingBudgets, VIEWER_TIMING_TARGETS_MS, type ViewerTimingSamples } from "./viewer-performance-budgets";
 
 const DEMO_CONNECTION_ID = "85610f49-ab40-4d96-8750-ddab3e8e8764";
 const DEMO_PATH = "note.md";
 const DEMO_DIRECTORY = "Reports";
 const DEMO_ARCHIVE = "sample.zip";
+const DENSE_SYNTAX_LINE_COUNT = 6_000;
+const DENSE_EXPANSION_REPLACEMENT_UNITS = 128;
+const DENSE_EXPANSION_OUTPUT_UNITS = 780_000;
+const SOURCE_TYPING_PAYLOAD = "abcdefghijklmnopqrst0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrst012345";
+const SOURCE_TYPING_KEY_DELAY_MS = 10;
+const PROSE_ENVELOPE_PARAGRAPHS = 4_000;
+const TABLE_ENVELOPE_ROWS = 2_400;
+const TABLE_EDIT_PAYLOAD = "table edit";
+const TABLE_EDIT_CASES = [
+  { name: "first", row: 1, action: "type" },
+  { name: "middle", row: TABLE_ENVELOPE_ROWS / 2, action: "type" },
+  { name: "last", row: TABLE_ENVELOPE_ROWS, action: "type" },
+  { name: "line-break", row: TABLE_ENVELOPE_ROWS / 2, action: "line-break" },
+  { name: "composition", row: TABLE_ENVELOPE_ROWS / 2, action: "composition" },
+  { name: "close-flush", row: TABLE_ENVELOPE_ROWS / 2, action: "close" },
+  { name: "composition-close", row: TABLE_ENVELOPE_ROWS / 2, action: "composition-close" },
+] as const;
+const SCROLL_PROBE_STEPS = 60;
+const NOMINAL_60HZ_SCROLL_TARGETS_MS = { p95: 16.7, maximum: 33.3 } as const;
+const THEME_STATE_LINE_COUNT = 60;
+const THEME_STATE_SCROLL = { top: 180, left: 36 };
+const MIN_TEXT_CONTRAST_RATIO = 4.5;
+const CACHE_PROOF_ORIGIN = "http://localhost:3000";
+const CACHE_PROOF_ASSET_MAX_AGE_SECONDS = 31_536_000;
+const PRODUCTION_ASSET_CONTENT_TYPES: Record<string, string> = { ".html": "text/html", ".js": "text/javascript", ".css": "text/css", ".svg": "image/svg+xml", ".json": "application/json", ".woff2": "font/woff2" };
+const SYNTAX_PUBLICATION_FIXTURES = [
+  { name: "dense", blocks: 1, lines: DENSE_SYNTAX_LINE_COUNT },
+  { name: "near-safeguard", blocks: 1, lines: 11_111 },
+  { name: "host-envelope", blocks: 4, lines: DENSE_SYNTAX_LINE_COUNT },
+  { name: "many-blocks", blocks: 600, lines: 101 },
+  { name: "long-line", blocks: 1, lines: 6_000 },
+] as const;
 
 const LINE_BREAK_MARKDOWN = "alpha\n\n| Col 1 | Col 2 |\n| --- | --- |\n| A1 | B1 |\n| A2 | B2 |\n\nomega\n";
 const SEARCH_MARKDOWN = "alpha\n\n| Col 1 | Col 2 |\n| --- | --- |\n| alpha | B1 |\n| A2 | alpha |\n\nomega alpha\n";
@@ -20,6 +65,11 @@ const SCROLLED_SELECTION_MARKDOWN = [
 
 interface MockMarkdownViewerApiOptions {
   initialMarkdown: string;
+  filePath?: string;
+  additionalFilePaths?: readonly string[];
+  themeId?: () => string;
+  wordWrapEnabled?: boolean;
+  userRole?: "user" | "admin";
   includeDirectory?: boolean;
   includeZip?: boolean;
   existingFilePaths?: readonly string[];
@@ -27,7 +77,11 @@ interface MockMarkdownViewerApiOptions {
   onUploadBody?: (body: string, setCurrentMarkdown: (markdown: string) => void) => void;
 }
 
-async function fulfillJson(route: Route, json: unknown, status = 200): Promise<void> {
+type ViewerApiRoute = Pick<Route, "fulfill"> & {
+  request(): Pick<ReturnType<Route["request"]>, "url" | "method" | "postDataBuffer">;
+};
+
+async function fulfillJson(route: ViewerApiRoute, json: unknown, status = 200): Promise<void> {
   await route.fulfill({
     status,
     contentType: "application/json",
@@ -35,10 +89,19 @@ async function fulfillJson(route: Route, json: unknown, status = 200): Promise<v
   });
 }
 
-async function mockMarkdownViewerApi(page: Page, { initialMarkdown, includeDirectory, includeZip, existingFilePaths, onTransferStream, onUploadBody }: MockMarkdownViewerApiOptions): Promise<void> {
+async function mockMarkdownViewerApi(page: Page, options: MockMarkdownViewerApiOptions): Promise<void> {
+  const handler = createMarkdownViewerApiHandler(options);
+  await page.route("**/api/**", async route => {
+    const request = route.request();
+    if (options.onTransferStream && new URL(request.url()).pathname === `/api/browse/${DEMO_CONNECTION_ID}/transfer-stream` && request.method() === "POST") return options.onTransferStream(route);
+    await handler(route);
+  });
+}
+
+function createMarkdownViewerApiHandler({ initialMarkdown, filePath = DEMO_PATH, additionalFilePaths = [], themeId = () => "sambee-light", wordWrapEnabled, userRole = "admin", includeDirectory, includeZip, existingFilePaths, onUploadBody }: MockMarkdownViewerApiOptions): (route: ViewerApiRoute) => Promise<void> {
   let currentMarkdown = initialMarkdown;
 
-  await page.route("**/api/**", async (route) => {
+  return async (route) => {
     const request = route.request();
     const url = new URL(request.url());
     const pathname = url.pathname;
@@ -63,15 +126,41 @@ async function mockMarkdownViewerApi(page: Page, { initialMarkdown, includeDirec
       await fulfillJson(route, {
         id: "user-1",
         username: "demo-admin",
-        role: "admin",
+        role: userRole,
         is_active: true,
       });
       return;
     }
 
+    if (pathname === "/api/auth/oidc/refresh" && request.method() === "POST") {
+      await fulfillJson(route, { access_token: "ci-browser-token", token_type: "bearer", username: "demo-admin", user_id: "user-1", role: "admin" });
+      return;
+    }
+
+    if (pathname === "/api/auth/account" && request.method() === "GET") {
+      await fulfillJson(route, {
+        id: "user-1", username: "demo-admin", role: userRole, is_active: true,
+        must_change_password: false, expires_at: null, created_at: "2026-04-12T12:00:00Z",
+        has_local_password: true, identity_source: "local", password_change_available: true,
+        password_change_required: false, browser_session_management_available: false,
+        oidc_provider_name: null, current_session: null,
+      });
+      return;
+    }
+
+    if (pathname === "/api/themes" && request.method() === "GET") {
+      await fulfillJson(route, { themes: [], site_default_id: "sambee-light" });
+      return;
+    }
+
+    if (pathname === "/api/browse/recent-files" && request.method() === "POST") {
+      await fulfillJson(route, null);
+      return;
+    }
+
     if (pathname.endsWith("/auth/me/settings") && request.method() === "GET") {
       await fulfillJson(route, {
-        appearance: { theme_id: "sambee-light", custom_themes: [] },
+        appearance: { theme_id: themeId(), custom_themes: [] },
         localization: { language: "browser", regional_locale: "browser" },
         browser: {
           quick_nav_include_dot_directories: false,
@@ -81,14 +170,14 @@ async function mockMarkdownViewerApi(page: Page, { initialMarkdown, includeDirec
           selected_connection_id: null,
           viewer_associations: {},
         },
-        text_editor: { max_file_size_bytes: 52428800, word_wrap_enabled: null },
+        text_editor: { max_file_size_bytes: 52428800, word_wrap_enabled: wordWrapEnabled ?? null },
       });
       return;
     }
 
     if (pathname.endsWith("/auth/me/settings") && request.method() === "PUT") {
       await fulfillJson(route, {
-        appearance: { theme_id: "sambee-light", custom_themes: [] },
+        appearance: { theme_id: themeId(), custom_themes: [] },
         localization: { language: "browser", regional_locale: "browser" },
         browser: {
           quick_nav_include_dot_directories: false,
@@ -98,7 +187,7 @@ async function mockMarkdownViewerApi(page: Page, { initialMarkdown, includeDirec
           selected_connection_id: null,
           viewer_associations: {},
         },
-        text_editor: { max_file_size_bytes: 52428800, word_wrap_enabled: null },
+        text_editor: { max_file_size_bytes: 52428800, word_wrap_enabled: wordWrapEnabled ?? null },
       });
       return;
     }
@@ -138,15 +227,15 @@ async function mockMarkdownViewerApi(page: Page, { initialMarkdown, includeDirec
       await fulfillJson(route, {
         path: "/",
         items: [
-          {
-            name: DEMO_PATH,
-            path: DEMO_PATH,
+          ...[filePath, ...additionalFilePaths].map((entryPath) => ({
+            name: entryPath,
+            path: entryPath,
             type: "file",
             is_readable: true,
             size: currentMarkdown.length,
-            mime_type: "text/markdown",
+            mime_type: entryPath.endsWith(".md") ? "text/markdown" : "text/plain",
             modified_at: "2026-04-12T12:00:00Z",
-          },
+          })),
           ...(includeDirectory
             ? [{ name: DEMO_DIRECTORY, path: DEMO_DIRECTORY, type: "directory", is_readable: true, modified_at: "2026-04-12T12:00:00Z" }]
             : []),
@@ -203,7 +292,7 @@ async function mockMarkdownViewerApi(page: Page, { initialMarkdown, includeDirec
     if (pathname === `/api/browse/${DEMO_CONNECTION_ID}/lock` && request.method() === "POST") {
       await fulfillJson(route, {
         lock_id: "lock-1",
-        file_path: DEMO_PATH,
+        file_path: filePath,
         locked_by: "demo-admin",
         locked_at: "2026-04-12T12:00:00Z",
          lock_capability: "test-lock-capability",
@@ -231,18 +320,76 @@ async function mockMarkdownViewerApi(page: Page, { initialMarkdown, includeDirec
       await route.fulfill({
         status: 200,
         contentType: "application/json",
-        body: JSON.stringify({ path: DEMO_PATH }),
+        body: JSON.stringify({ path: filePath }),
       });
       return;
     }
 
-    if (pathname === `/api/browse/${DEMO_CONNECTION_ID}/transfer-stream` && request.method() === "POST" && onTransferStream) {
-      await onTransferStream(route);
-      return;
-    }
-
     await fulfillJson(route, { detail: `Unhandled mocked route: ${request.method()} ${pathname}` }, 404);
+  };
+}
+
+async function createCacheableViewerProxy(options: MockMarkdownViewerApiOptions) {
+  const handler = createMarkdownViewerApiHandler(options);
+  const dist = resolve(fileURLToPath(new URL("../dist/", import.meta.url)));
+  const requests: string[] = [];
+  const errors: string[] = [];
+  const uploads: { body: Buffer; contentType: string }[] = [];
+  const server = createServer((request, response) => {
+    void (async () => {
+      const url = new URL(request.url ?? "/", CACHE_PROOF_ORIGIN);
+      if (url.origin !== CACHE_PROOF_ORIGIN) {
+        response.writeHead(403).end("Only the approved demo origin is supported");
+        return;
+      }
+      requests.push(url.pathname);
+      if (url.pathname.startsWith("/api/")) {
+        const chunks: Buffer[] = [];
+        for await (const chunk of request) chunks.push(Buffer.from(chunk));
+        const body = Buffer.concat(chunks);
+        if (url.pathname.endsWith("/upload") && request.method === "POST") {
+          uploads.push({ body, contentType: request.headers["content-type"] ?? "" });
+        }
+        await handler({
+          request: () => ({ url: () => url.href, method: () => request.method ?? "GET", postDataBuffer: () => body }),
+          fulfill: async (result = {}) => {
+            if (result.path || result.response) throw new Error("Cache proxy fixtures require an explicit body");
+            const headers = { ...result.headers, "Cache-Control": "no-store", ...(result.contentType ? { "Content-Type": result.contentType } : {}) };
+            response.writeHead(result.status ?? 200, headers);
+            response.end(result.json === undefined ? result.body : JSON.stringify(result.json));
+          },
+        });
+        return;
+      }
+      const path = url.pathname === "/browse/smb/demo" ? resolve(dist, "index.html") : resolve(dist, `.${url.pathname}`);
+      if (!path.startsWith(`${dist}${sep}`)) {
+        response.writeHead(403).end("Asset path is outside the production build");
+        return;
+      }
+      try {
+        const body = await readFile(path);
+        response.writeHead(200, { "Content-Type": PRODUCTION_ASSET_CONTENT_TYPES[extname(path)] ?? "application/octet-stream", "Cache-Control": extname(path) === ".html" ? "no-store" : `public, max-age=${CACHE_PROOF_ASSET_MAX_AGE_SECONDS}, immutable` });
+        response.end(body);
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+        response.writeHead(404).end("Production asset not found");
+      }
+    })().catch(error => {
+      errors.push(error instanceof Error ? error.message : String(error));
+      if (!response.headersSent) response.writeHead(500);
+      response.end("Cache proof server failed; inspect its recorded errors");
+    });
   });
+  await new Promise<void>((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => { server.off("error", reject); resolve(); });
+  });
+  const address = server.address();
+  if (!address || typeof address === "string") throw new Error("Cache proof proxy has no TCP address");
+  return {
+    url: `http://127.0.0.1:${address.port}`, requests, errors, uploads,
+    close: () => new Promise<void>((resolve, reject) => { server.close(error => error ? reject(error) : resolve()); server.closeAllConnections(); }),
+  };
 }
 
 async function openMarkdownViewer(page: Page): Promise<void> {
@@ -250,6 +397,1944 @@ async function openMarkdownViewer(page: Page): Promise<void> {
   await page.getByRole("button", { name: `File: ${DEMO_PATH}` }).click();
 }
 
+async function serveProductionAssets(page: Page, transformJavaScript?: (source: string, pathname: string) => string): Promise<void> {
+  const dist = resolve(fileURLToPath(new URL("../dist/", import.meta.url)));
+  await page.route("http://localhost:3000/**", async (route) => {
+    const request = route.request();
+    const pathname = new URL(request.url()).pathname;
+    if (pathname.startsWith("/api/")) return route.fallback();
+    const path = request.isNavigationRequest() ? resolve(dist, "index.html") : resolve(dist, `.${pathname}`);
+    if (!path.startsWith(`${dist}${sep}`)) return route.abort();
+    try {
+      const body = await readFile(path);
+      await route.fulfill({ body: transformJavaScript && extname(path) === ".js" ? transformJavaScript(body.toString("utf8"), pathname) : body, contentType: PRODUCTION_ASSET_CONTENT_TYPES[extname(path)] ?? "application/octet-stream" });
+    } catch {
+      await route.fulfill({ status: 404, body: "Production asset not found" });
+    }
+  });
+}
+
+async function captureViewerScheduling(page: Page, testInfo: TestInfo, action: () => Promise<void>): Promise<void> {
+  if (process.env.SAMBEE_E2E_TRACE !== "1" || testInfo.project.name !== "chromium") return action();
+  if (process.env.SAMBEE_E2E_MEMORY === "1") throw new Error("Run scheduling traces separately from controlled-GC memory trials");
+  const session = await page.context().newCDPSession(page);
+  let started = false;
+  try {
+    await session.send("Tracing.start", { categories: "-*,devtools.timeline,v8,blink.user_timing,toplevel,renderer.scheduler,disabled-by-default-devtools.timeline.frame,disabled-by-default-v8.cpu_profiler", transferMode: "ReturnAsStream" });
+    started = true;
+    await page.evaluate(() => performance.mark("sambee:viewer-trace:start"));
+    await action();
+  } finally {
+    try {
+      if (started) {
+        const completed = new Promise<{ stream?: string }>((resolve) => session.once("Tracing.tracingComplete", resolve));
+        await session.send("Tracing.end");
+        const { stream } = await completed;
+        if (!stream) throw new Error("Viewer scheduling trace returned no readable stream");
+        const chunks: string[] = [];
+        try {
+          for (;;) {
+            const response = await session.send("IO.read", { handle: stream });
+            chunks.push(response.base64Encoded ? Buffer.from(response.data, "base64").toString("utf8") : response.data);
+            if (response.eof) break;
+          }
+        } finally {
+          await session.send("IO.close", { handle: stream });
+        }
+        await testInfo.attach("viewer-scheduling-trace", { body: chunks.join(""), contentType: "application/json" });
+      }
+    } finally {
+      await session.detach();
+    }
+  }
+}
+
+test.describe("production shared syntax correctness", () => {
+  test.skip(process.env.SAMBEE_E2E_PRODUCTION !== "1", "Requires the production build and approved demo route");
+  const fixtures = [
+    { label: "js", filename: "sample.js", code: 'obj.key = [true, null, /x/, "\\n"];' },
+    { label: "ts", filename: "sample.ts", code: 'const greet = (value: string): string => value; // end' },
+    { label: "py", filename: "sample.py", code: 'print(True, None) # end' },
+    { label: "sql", filename: "sample.sql", code: "SELECT count(*) FROM users WHERE id = 1; -- end" },
+    { label: "sh", filename: "sample.sh", code: 'echo "hello" # end' },
+    { label: "ps1", filename: "sample.ps1", code: '$sites = Get-Content $siteUrlFile; # end' },
+    { label: "json", filename: "sample.json", code: '{"enabled": true, "value": null}' },
+    { label: "c", filename: "sample.c", code: '#include <stdio.h> // end' },
+    { label: "mssql", filename: null, code: "SELECT TOP 1 [account] FROM [users] WHERE [id] = @id; -- end" },
+    { label: "mariadb", filename: null, code: "SELECT `account` FROM `users` LIMIT 1; # end" },
+  ];
+  const editorTokens = (editor: Locator, text: string) => editor.locator(".cm-line").evaluateAll((lines, source) => {
+    const line = lines.find((element) => element.textContent === source);
+    if (!line) return [];
+    return [...line.querySelectorAll<HTMLElement>('span[class*="sambee-syntax-"]')].flatMap((span) => {
+      const prefix = document.createRange();
+      prefix.setStart(line, 0);
+      prefix.setEnd(span, 0);
+      const from = prefix.toString().length;
+      return [...span.classList].filter((name) => name.startsWith("sambee-syntax-")).map((name) => ({
+        from, to: from + (span.textContent?.length ?? 0), text: span.textContent ?? "", category: name.slice("sambee-syntax-".length),
+      }));
+    }).sort((left, right) => left.from - right.from || left.category.localeCompare(right.category));
+  }, text);
+
+  for (const width of [1543, 390]) {
+    for (const fixture of fixtures) {
+      test(`${fixture.label} across application surfaces at ${width}px`, async ({ page }) => {
+        await page.setViewportSize({ width, height: 900 });
+        await serveProductionAssets(page);
+        let native: Awaited<ReturnType<typeof editorTokens>> | undefined;
+        if (fixture.filename) {
+          await mockMarkdownViewerApi(page, { initialMarkdown: fixture.code, filePath: fixture.filename, additionalFilePaths: [DEMO_PATH], existingFilePaths: [fixture.filename, DEMO_PATH] });
+          await page.goto("/browse/smb/demo");
+          await page.getByRole("button", { name: "Later", exact: true }).click();
+          await page.getByRole("button").filter({ has: page.getByText(fixture.filename, { exact: true }) }).click();
+          const editor = page.locator(".sambee-text-editor");
+          await expect(editor.locator(".cm-content")).toHaveAttribute("contenteditable", "false");
+          await expect.poll(async () => (await editorTokens(editor, fixture.code)).length).toBeGreaterThan(0);
+          native = await editorTokens(editor, fixture.code);
+          await page.getByRole("button", { name: "Edit", exact: true }).click();
+          await expect(editor.locator(".cm-content")).toHaveAttribute("contenteditable", "true");
+          await expect.poll(() => editorTokens(editor, fixture.code)).toEqual(native);
+          await page.getByRole("button", { name: "Close", exact: true }).click();
+        }
+
+        const markdown = `# Source\n\nPlain paragraph\n\n\`\`\`${fixture.label}\n${fixture.code}\n\`\`\`\n\n\`\`\`unknown-fence\n*not prose*\n\`\`\`\n`;
+        await mockMarkdownViewerApi(page, { initialMarkdown: markdown, existingFilePaths: [DEMO_PATH] });
+        await page.goto("/browse/smb/demo");
+        await page.getByRole("button", { name: "Later", exact: true }).click();
+        await page.getByRole("button").filter({ has: page.getByText(DEMO_PATH, { exact: true }) }).click();
+        const root = page.locator('[data-markdown-search-root="true"]');
+        const code = root.locator("pre code").first();
+        await expect(code).toHaveText(`${fixture.code}\n`);
+        const node = await code.evaluateHandle((element) => element.firstChild);
+        const previewTokens = () => code.evaluate((element) => [...CSS.highlights].flatMap(([name, highlight]) => {
+          if (!/^markdown-syntax-\d+-/.test(name)) return [];
+          return [...highlight].filter((range) => element.contains(range.startContainer)).map((range) => ({
+            from: range.startOffset, to: range.endOffset, text: range.toString(), category: name.replace(/^markdown-syntax-\d+-/, ""),
+          }));
+        }).sort((left, right) => left.from - right.from || left.category.localeCompare(right.category)));
+        await expect.poll(async () => (await previewTokens()).length).toBeGreaterThan(0);
+        const preview = await previewTokens();
+        await code.evaluate((element) => { const pre = element.closest("pre")!; pre.scrollLeft = pre.scrollWidth; });
+        await expect.poll(async () => Math.max(...(await previewTokens()).map((token) => token.to))).toBe(fixture.code.length);
+        preview.push(...await previewTokens());
+        expect(await code.evaluate((element, original) => element.firstChild === original, node)).toBe(true);
+        await node.dispose();
+        expect(await root.locator("pre code").last().evaluate((element) => [...CSS.highlights.values()].some((highlight) =>
+          [...highlight].some((range) => element.contains(range.startContainer))))).toBe(false);
+        await page.getByRole("button", { name: "Edit", exact: true }).click();
+        const source = page.getByRole("textbox", { name: "Markdown editor" });
+        await expect(source).toHaveAttribute("contenteditable", "true");
+        await expect.poll(async () => (await editorTokens(source, fixture.code)).some((token) => token.to === fixture.code.length)).toBe(true);
+        const expected = await editorTokens(source, fixture.code);
+        const requiredCategories: Record<string, string[]> = {
+          js: ["property", "boolean", "null", "regexp", "escape"],
+          py: ["boolean", "null"], sh: ["builtin"], ps1: ["builtin", "identifier"],
+          json: ["property", "boolean", "null"], c: ["metadata"],
+        };
+        expect(expected.map(token => token.category)).toEqual(expect.arrayContaining(requiredCategories[fixture.label] ?? []));
+        if (native) expect(expected).toEqual(native);
+        for (const fragment of preview) {
+          expect(expected.some((token) => token.category === fragment.category && token.from <= fragment.from && token.to >= fragment.to)).toBe(true);
+          expect(fragment.text).toBe(fixture.code.slice(fragment.from, fragment.to));
+        }
+        for (const token of expected) {
+          let covered = token.from;
+          for (const fragment of preview.filter((fragment) => fragment.category === token.category && fragment.to > token.from && fragment.from < token.to).sort((left, right) => left.from - right.from)) {
+            expect(fragment.from).toBeLessThanOrEqual(covered);
+            covered = Math.max(covered, fragment.to);
+          }
+          expect(covered).toBe(token.to);
+        }
+        await expect(source.locator(".sambee-syntax-heading").filter({ hasText: "Source" })).toHaveText(" Source");
+        expect(await editorTokens(source, "Plain paragraph")).toEqual([]);
+        expect(await editorTokens(source, "*not prose*")).toEqual([]);
+        await page.getByRole("button", { name: "Close", exact: true }).click();
+      });
+    }
+  }
+});
+
+test.describe("production nested syntax failures", () => {
+  test.skip(process.env.SAMBEE_E2E_PRODUCTION !== "1", "Requires the production build and approved demo route");
+  for (const width of [1543, 390]) {
+    for (const phase of ["load", "start", "advance", "pending-load"] as const) {
+      for (const failedFirst of [true, false]) {
+        test(`${phase}, failed first ${failedFirst}, at ${width}px`, async ({ page }) => {
+          await page.setViewportSize({ width, height: 900 });
+          let injectFailure = true;
+          const pendingMarker = "Injected pending Python grammar load";
+          let pendingLoad = false;
+          page.on("console", message => { if (message.text() === pendingMarker) pendingLoad = true; });
+          await serveProductionAssets(page, (source, pathname) => injectFailure ? `${source}\n
+import * as syntaxFaultModule from ${JSON.stringify(pathname)};
+if (typeof WorkerGlobalScope !== "undefined" && globalThis instanceof WorkerGlobalScope && typeof syntaxFaultModule.python === "function") {
+  if (${JSON.stringify(phase)} === "pending-load") {
+    console.debug(${JSON.stringify(pendingMarker)});
+    await new Promise(() => {});
+  }
+  const parser = syntaxFaultModule.python().language.parser;
+  const originalStart = parser.startParse;
+  if (${JSON.stringify(phase)} === "load") throw new Error("Injected Python grammar load failure");
+  parser.startParse = function (...args) {
+    this.startParse = originalStart;
+    if (${JSON.stringify(phase)} === "start") throw new Error("Injected Python parser startup failure");
+    const partial = originalStart.apply(this, args);
+    partial.advance = () => { throw new Error("Injected Python parser advance failure"); };
+    return partial;
+  };
+}` : source);
+          const failed = "def failed(): pass";
+          const sibling = "const sibling = 1;";
+          const healthy = "def healthy(): pass";
+          const failedFence = `\`\`\`python\n${failed}\n\`\`\``;
+          const healthyFence = `\`\`\`js\n${sibling}\n\`\`\``;
+          let nested = `# Healthy heading\n\n${(failedFirst ? [failedFence, healthyFence] : [healthyFence, failedFence]).join("\n\n")}\n\n\`\`\`python\n${healthy}\n\`\`\``;
+          for (const size of [4, 5, 6]) nested = `${"`".repeat(size)}markdown\n${nested}\n${"`".repeat(size)}`;
+          const markdown = `\`\`\`\`\`\`\`markdown\n${nested}\n\`\`\`\`\`\`\`\n\n\`\`\`js\nconst independent = 1;\n\`\`\``;
+          await mockMarkdownViewerApi(page, { initialMarkdown: markdown });
+          await page.goto("/browse/smb/demo");
+          await page.getByRole("button", { name: "Later", exact: true }).click();
+          const open = () => page.getByRole("button").filter({ has: page.getByText(DEMO_PATH, { exact: true }) }).click();
+          await open();
+          const root = page.locator('[data-markdown-search-root="true"]');
+          const code = root.locator("pre code").first();
+          await expect(code).toHaveText(`${nested}\n`);
+          const original = await code.evaluateHandle(element => element.firstChild);
+          const tokens = () => code.evaluate(element => [...CSS.highlights].flatMap(([name, highlight]) => {
+            if (!/^markdown-syntax-\d+-/.test(name)) return [];
+            return [...highlight].filter(range => element.contains(range.startContainer)).map(range => ({ from: range.startOffset, to: range.endOffset, text: range.toString(), category: name.replace(/^markdown-syntax-\d+-/, "") }));
+          }));
+          const from = nested.indexOf(failed);
+          if (phase === "pending-load") {
+            await expect.poll(() => pendingLoad).toBe(true);
+            expect(page.workers()).toHaveLength(1);
+          } else {
+            await expect.poll(tokens).toEqual(expect.arrayContaining([
+              expect.objectContaining({ text: " Healthy heading", category: "heading" }),
+              expect.objectContaining({ from: nested.indexOf(sibling), text: "const", category: "keyword" }),
+            ]));
+            expect((await tokens()).some(token => token.from < from + failed.length && token.to > from)).toBe(false);
+            if (phase !== "load") expect(await tokens()).toEqual(expect.arrayContaining([expect.objectContaining({ from: nested.indexOf(healthy), text: "def", category: "keyword" })]));
+            await expect.poll(() => root.locator("pre code").last().evaluate(element => [...CSS.highlights].some(([name, highlight]) => name.endsWith("-keyword") && [...highlight].some(range => element.contains(range.startContainer) && range.toString() === "const")))).toBe(true);
+          }
+          expect(await code.evaluate((element, original) => element.firstChild === original, original)).toBe(true);
+          await original.dispose();
+          await page.getByRole("button", { name: "Search", exact: true }).click();
+          await page.getByPlaceholder("Search", { exact: true }).fill(failed);
+          await expect(page.getByRole("button", { name: "Next match", exact: true }).locator("..").getByText("1 / 1", { exact: true })).toBeVisible();
+          await page.getByRole("button", { name: "Close", exact: true }).click();
+          await expect(root).toHaveCount(0);
+          await expect.poll(() => page.workers().length).toBe(0);
+          await expect.poll(() => page.evaluate(() => [...CSS.highlights.keys()].filter(name => name.startsWith("markdown-syntax-")).length)).toBe(0);
+          injectFailure = false;
+          await open();
+          await expect(code).toHaveText(`${nested}\n`);
+          await expect.poll(tokens).toEqual(expect.arrayContaining([expect.objectContaining({ from, text: "def", category: "keyword" })]));
+          await page.getByRole("button", { name: "Close", exact: true }).click();
+          await expect(root).toHaveCount(0);
+          await expect.poll(() => page.workers().length).toBe(0);
+        });
+      }
+    }
+    test(`nesting-depth safeguard preserves independent blocks at ${width}px`, async ({ page }) => {
+      await page.setViewportSize({ width, height: 900 });
+      await serveProductionAssets(page);
+      let nested = "```js\nconst guarded = 1;\n```";
+      for (const size of [4, 5, 6, 7]) nested = `${"`".repeat(size)}markdown\n${nested}\n${"`".repeat(size)}`;
+      await mockMarkdownViewerApi(page, { initialMarkdown: `\`\`\`\`\`\`\`\`markdown\n${nested}\n\`\`\`\`\`\`\`\`\n\n\`\`\`js\nconst independent = 1;\n\`\`\`` });
+      await page.goto("/browse/smb/demo");
+      await page.getByRole("button", { name: "Later", exact: true }).click();
+      await page.getByRole("button").filter({ has: page.getByText(DEMO_PATH, { exact: true }) }).click();
+      const root = page.locator('[data-markdown-search-root="true"]');
+      const code = root.locator("pre code");
+      await expect(code.first()).toHaveText(`${nested}\n`);
+      await expect.poll(() => code.last().evaluate(element => [...CSS.highlights].some(([name, highlight]) => name.endsWith("-keyword") && [...highlight].some(range => element.contains(range.startContainer) && range.toString() === "const")))).toBe(true);
+      expect(await code.first().evaluate(element => [...CSS.highlights.values()].some(highlight => [...highlight].some(range => element.contains(range.startContainer))))).toBe(false);
+      await page.getByRole("button", { name: "Close", exact: true }).click();
+      await expect(root).toHaveCount(0);
+      await expect.poll(() => page.workers().length).toBe(0);
+      await expect.poll(() => page.evaluate(() => [...CSS.highlights.keys()].filter(name => name.startsWith("markdown-syntax-")).length)).toBe(0);
+    });
+  }
+});
+
+test.describe("production shared syntax theme identity", () => {
+  test.skip(process.env.SAMBEE_E2E_PRODUCTION !== "1", "Requires the production build and approved demo route");
+  for (const width of [1543, 390]) {
+    for (const kind of ["text", "markdown"] as const) {
+    for (const editing of [false, true]) {
+    test(`${kind} ${editing ? "edit" : "view"} live colors and browser state at ${width}px`, async ({ page }, testInfo) => {
+      await page.setViewportSize({ width, height: 900 });
+      const grammarGate = "sambee-e2e-theme-grammar";
+      const pendingContexts = new Set<string>();
+      page.on("console", message => {
+        if (message.text().startsWith(grammarGate)) pendingContexts.add(message.text().slice(grammarGate.length));
+      });
+      await serveProductionAssets(page, source => source.replace(/\.then\((\w+)=>\1\.javascript\(\)\)/g, `.then(async grammar => {
+        const gate = new BroadcastChannel(${JSON.stringify(grammarGate)});
+        await new Promise(resolve => {
+          gate.onmessage = () => { gate.close(); resolve(); };
+          console.debug(${JSON.stringify(grammarGate)} + (typeof document === "undefined" ? "worker" : "window"));
+        });
+        return grammar.javascript();
+      })`));
+      await page.addInitScript(() => {
+        const OriginalWorker = window.Worker;
+        const requests: string[] = [];
+        const preparations: string[] = [];
+        new PerformanceObserver(list => {
+          for (const entry of list.getEntries()) {
+            if (/^sambee:preview-preparation:(?:render-parse|render-prepared-tree|render-transform|collection-walk)$/.test(entry.name)) preparations.push(entry.name);
+          }
+        }).observe({ entryTypes: ["measure"] });
+        Object.assign(window, { themeWorkerRequests: requests, themePreparationStages: preparations });
+        window.Worker = class extends OriginalWorker {
+          postMessage(message: unknown, transfer?: Transferable[]) {
+            requests.push(`${(message as { type?: string }).type}`);
+            super.postMessage(message, transfer ?? []);
+          }
+        };
+      });
+      const code = Array.from({ length: THEME_STATE_LINE_COUNT }, (_, index) => `const alpha = "hello ${index} ${"wide ".repeat(100)}"; let beta = 1;`).join("\n");
+      let themeId = "sambee-light";
+      const custom = structuredClone(builtInThemes.find((theme) => theme.id === "sambee-dark")!);
+      custom.id = "syntax-alpha";
+      custom.name = "Syntax alpha";
+      custom.components!.syntax!.keyword = "#c8f5d9bb";
+      const themes = [...builtInThemes.filter((theme) => theme.id === "sambee-light" || theme.id === "sambee-dark"), custom];
+      const filePath = kind === "text" ? "sample.js" : DEMO_PATH;
+      const [version, gitCommit] = await Promise.all([
+        readFile(new URL("../../VERSION", import.meta.url), "utf8"),
+        readFile(new URL("../../GIT_COMMIT", import.meta.url), "utf8"),
+      ]);
+      const installThemeRoutes = async () => {
+        await page.route("**/api/themes", (route) => fulfillJson(route, {
+          site_default_id: "sambee-light",
+          themes: [{ id: custom.id, definition: custom, scope: "user", version: 1 }],
+        }));
+        await page.route("**/api/version", (route) => fulfillJson(route, {
+          version: version.trim(), git_commit: gitCommit.trim(), build_time: "2026-10-22T00:00:00Z",
+        }));
+      };
+      await mockMarkdownViewerApi(page, {
+        initialMarkdown: kind === "text" ? code : `\`\`\`js\n${code}\n\`\`\``, filePath,
+        existingFilePaths: [filePath], themeId: () => themeId, wordWrapEnabled: false,
+      });
+      await installThemeRoutes();
+      await page.addLocatorHandler(page.getByRole("dialog", { name: "Update available" }), async (dialog) => {
+        await dialog.getByRole("button", { name: "Later", exact: true }).click();
+      });
+      await page.goto("/browse/smb/demo");
+      const file = page.getByRole("button", { name: filePath, exact: true }).or(page.getByRole("button", { name: `File: ${filePath}`, exact: true }));
+      await file.click();
+      if (editing) await page.getByRole("button", { name: "Edit", exact: true }).click();
+
+      const checkThemes = async (surface: Locator, preview: boolean) => {
+        const hasSyntax = () => surface.evaluate((element, isPreview) => isPreview
+          ? [...CSS.highlights].some(([name, highlight]) => name.endsWith("-keyword") && [...highlight].some((range) => element.contains(range.startContainer)))
+          : !!element.querySelector(".sambee-syntax-keyword"), preview);
+        await expect.poll(() => pendingContexts.has(preview ? "worker" : "window")).toBe(true);
+        expect(await hasSyntax()).toBe(false);
+        const searchInput = preview ? page.getByPlaceholder("Search", { exact: true }) : page.getByRole("textbox", { name: "Find", exact: true });
+        if (!(await searchInput.isVisible())) await page.getByRole("button", { name: "Search", exact: true }).click();
+        await searchInput.fill("const");
+        const searchControls = preview ? page.getByRole("button", { name: "Next match", exact: true }).locator("..") : page.getByTestId("code-mirror-find-replace-popover");
+        await expect(searchControls.getByText(new RegExp(`^[01] / ${THEME_STATE_LINE_COUNT}$`), { exact: true })).toBeVisible();
+        await page.getByRole("button", { name: "Next match", exact: true }).click();
+        await surface.focus();
+        const editable = await surface.getAttribute("contenteditable") === "true";
+        if (editable) {
+          await surface.press("Control+Home");
+          if (kind === "markdown") { await surface.press("ArrowDown"); await surface.press("Home"); }
+          for (let index = 0; index < "const".length; index += 1) await surface.press("Shift+ArrowRight");
+        }
+        await surface.evaluate((element, { preview, editable }) => {
+          if (!editable) {
+            const range = document.createRange();
+            const walker = document.createTreeWalker(element.querySelector(preview ? "code" : ".cm-line")!, NodeFilter.SHOW_TEXT);
+            let node = walker.nextNode();
+            while (node && !node.textContent!.includes("const")) node = walker.nextNode();
+            const from = node!.textContent!.indexOf("const");
+            range.setStart(node!, from);
+            range.setEnd(node!, from + "const".length);
+            window.getSelection()!.removeAllRanges();
+            window.getSelection()!.addRange(range);
+          }
+        }, { preview, editable });
+        await page.evaluate(() => new Promise<void>(resolve => requestAnimationFrame(() => requestAnimationFrame(() => resolve()))));
+        await surface.evaluate((element, { preview, scroll }) => {
+          const scroller = preview ? element.parentElement! : element.closest(".cm-scroller")!;
+          scroller.scrollTop = scroll.top;
+          let horizontal = preview ? element.querySelector("pre")! : scroller;
+          while (horizontal.parentElement && horizontal.scrollWidth <= horizontal.clientWidth) horizontal = horizontal.parentElement;
+          horizontal.scrollLeft = scroll.left;
+        }, { preview, scroll: THEME_STATE_SCROLL });
+        await page.evaluate(() => new Promise<void>(resolve => requestAnimationFrame(() => requestAnimationFrame(() => resolve()))));
+        const browserState = () => surface.evaluate((element, preview) => {
+          const selection = window.getSelection()!;
+          const offset = (node: Node | null, offset: number) => {
+            if (!node || !element.contains(node)) return null;
+            const range = document.createRange();
+            range.selectNodeContents(element);
+            range.setEnd(node, offset);
+            return range.toString().length;
+          };
+          const scroller = preview ? element.parentElement! : element.closest(".cm-scroller")!;
+          let horizontal = preview ? element.querySelector("pre")! : scroller;
+          while (horizontal.parentElement && horizontal.scrollWidth <= horizontal.clientWidth) horizontal = horizontal.parentElement;
+          return {
+            selected: selection.toString(), anchor: offset(selection.anchorNode, selection.anchorOffset), head: offset(selection.focusNode, selection.focusOffset),
+            top: scroller.scrollTop, left: horizontal.scrollLeft,
+            active: preview ? [...CSS.highlights].filter(([name]) => name.startsWith("markdown-search-") && name.endsWith("-current")).flatMap(([, ranges]) => [...ranges].map(range => ({ text: range.toString(), from: offset(range.startContainer, range.startOffset), to: offset(range.endContainer, range.endOffset) })))
+              : [...element.querySelectorAll(".cm-searchMatch-selected, .sambee-passive-search-match-selected")].map(match => ({ text: match.textContent })),
+            requests: [...(window as unknown as { themeWorkerRequests: string[] }).themeWorkerRequests],
+            renders: [...(window as unknown as { themePreparationStages: string[] }).themePreparationStages],
+          };
+        }, preview);
+        const initialState = await browserState();
+        expect(initialState.selected).toBe("const");
+        expect(initialState.top).toBeGreaterThan(0);
+        expect(initialState.left).toBeGreaterThan(0);
+        expect(initialState.active).toHaveLength(1);
+        const rootBeforeGrammar = await surface.elementHandle();
+        const textBeforeGrammar = await surface.textContent();
+        const previewNode = preview ? await surface.evaluateHandle(element => element.querySelector("code")!.firstChild) : undefined;
+        await page.evaluate(channel => {
+          const gate = new BroadcastChannel(channel);
+          gate.postMessage("release");
+          gate.close();
+        }, grammarGate);
+        await expect.poll(hasSyntax).toBe(true);
+        await page.evaluate(() => new Promise<void>(resolve => requestAnimationFrame(() => requestAnimationFrame(() => resolve()))));
+        const afterGrammar = await browserState();
+        await testInfo.attach("late-grammar-state.json", { body: JSON.stringify({ before: initialState, after: afterGrammar }), contentType: "application/json" });
+        expect({ ...afterGrammar, requests: [] }).toEqual({ ...initialState, requests: [] });
+        expect(afterGrammar.requests.filter(type => type === "start" || type === "source")).toEqual(initialState.requests.filter(type => type === "start" || type === "source"));
+        expect(await surface.evaluate((element, original) => element === original, rootBeforeGrammar)).toBe(true);
+        expect(await surface.textContent()).toBe(textBeforeGrammar);
+        if (previewNode) {
+          expect(await surface.evaluate((element, original) => element.querySelector("code")!.firstChild === original, previewNode)).toBe(true);
+          await previewNode.dispose();
+        }
+        await rootBeforeGrammar?.dispose();
+        const settledState = afterGrammar;
+        const initialCount = await searchControls.textContent();
+        const original = await surface.elementHandle();
+        const text = await surface.textContent();
+        const selector = preview ? "code" : ".cm-line";
+        const node = await surface.evaluateHandle((element, selector) => element.querySelector(selector)!.firstChild, selector);
+        const initialWorkers = page.workers();
+        for (const theme of themes) {
+          themeId = theme.id;
+          await page.evaluate(() => window.dispatchEvent(new Event("focus")));
+          const expected = theme.components!.syntax!.keyword;
+          await expect.poll(() => surface.evaluate((element, { preview, expected }) => {
+            const target = preview ? element.querySelector("code")! : [...element.querySelectorAll(".sambee-syntax-keyword")].find(token => !token.closest(".cm-searchMatch, .sambee-passive-search-match") && !token.querySelector(".cm-searchMatch, .sambee-passive-search-match"))!;
+            const name = preview ? [...CSS.highlights].find(([name, highlight]) => name.endsWith("-keyword") && [...highlight].some((range) => target.contains(range.startContainer)))?.[0] : undefined;
+            const reference = document.createElement("span");
+            reference.style.color = expected;
+            document.body.append(reference);
+            const desired = getComputedStyle(reference).color;
+            reference.remove();
+            return getComputedStyle(target, name ? `::highlight(${name})` : null).color === desired;
+          }, { preview, expected })).toBe(true);
+          expect(await browserState()).toEqual(settledState);
+          expect(await searchControls.textContent()).toBe(initialCount);
+          const contrast = await surface.evaluate((element, preview) => {
+            const canvas = document.createElement("canvas");
+            canvas.width = canvas.height = 1;
+            const context = canvas.getContext("2d", { willReadFrequently: true })!;
+            const parse = (color: string) => {
+              context.clearRect(0, 0, 1, 1);
+              context.fillStyle = color;
+              context.fillRect(0, 0, 1, 1);
+              return [...context.getImageData(0, 0, 1, 1).data].map((channel, index) => index === 3 ? channel / 255 : channel);
+            };
+            const over = (foreground: number[], background: number[]) => foreground.slice(0, 3).map((channel, index) => channel * foreground[3] + background[index] * (1 - foreground[3])).concat(1);
+            const background = (target: Element) => {
+              const ancestors: Element[] = [];
+              for (let ancestor: Element | null = target; ancestor; ancestor = ancestor.parentElement) ancestors.unshift(ancestor);
+              return ancestors.reduce((color, ancestor) => over(parse(getComputedStyle(ancestor).backgroundColor), color), [255, 255, 255, 1]);
+            };
+            const luminance = (color: number[]) => color.slice(0, 3).map(channel => channel / 255).map(channel => channel <= 0.04045 ? channel / 12.92 : ((channel + 0.055) / 1.055) ** 2.4).reduce((sum, channel, index) => sum + channel * [0.2126, 0.7152, 0.0722][index], 0);
+            const ratio = (foreground: number[], background: number[]) => {
+              const values = [luminance(over(foreground, background)), luminance(background)].sort((first, second) => second - first);
+              return (values[0] + 0.05) / (values[1] + 0.05);
+            };
+            const target = preview ? element.querySelector("code")! : [...element.querySelectorAll(".sambee-syntax-keyword")].find(token => !token.closest(".cm-searchMatch, .sambee-passive-search-match") && !token.querySelector(".cm-searchMatch, .sambee-passive-search-match"))!;
+            const base = background(target);
+            const results: { role: string; ratio: number }[] = [];
+            const syntaxName = preview ? [...CSS.highlights.keys()].find(name => /^markdown-syntax-\d+-keyword$/.test(name)) : undefined;
+            results.push({ role: "keyword", ratio: ratio(parse(getComputedStyle(target, syntaxName ? `::highlight(${syntaxName})` : null).color), base) });
+            const searchTargets = preview
+              ? [...CSS.highlights.keys()].filter(name => name.startsWith("markdown-search-")).map(name => ({ role: name.endsWith("-current") ? "current-search" : "other-search", target, style: getComputedStyle(target, `::highlight(${name})`) }))
+              : [...element.querySelectorAll(".cm-searchMatch, .sambee-passive-search-match")].slice(0, 3).map(match => ({ role: match.className.includes("selected") ? "current-search" : "other-search", target: match, style: getComputedStyle(match) }));
+            for (const match of searchTargets) {
+              const backdrop = over(parse(match.style.backgroundColor), background(match.target.parentElement!));
+              results.push({ role: match.role, ratio: ratio(parse(match.style.color), backdrop) });
+            }
+            const selected = element.querySelector(".sambee-editor-selection-range");
+            const selectionTarget = selected ?? target;
+            const selectionStyle = getComputedStyle(selectionTarget, selected ? null : "::selection");
+            const selectionBackground = over(parse(selectionStyle.backgroundColor), background(selectionTarget.parentElement!));
+            results.push({ role: "selection", ratio: ratio(parse(selectionStyle.color), selectionBackground) });
+            return results;
+          }, preview);
+          await testInfo.attach(`${theme.id}-contrast.json`, { body: JSON.stringify({ kind, editing, width, contrast, state: await browserState() }), contentType: "application/json" });
+          for (const sample of contrast) expect(sample.ratio, `${kind}/${preview ? "preview" : "source"}/${theme.id}/${sample.role}`).toBeGreaterThanOrEqual(MIN_TEXT_CONTRAST_RATIO);
+          expect(await surface.evaluate((element, original) => element === original, original)).toBe(true);
+          expect(await surface.evaluate((element, { node, selector }) => element.querySelector(selector)!.firstChild === node, { node, selector })).toBe(true);
+          expect(await surface.textContent()).toBe(text);
+          expect(page.workers()).toEqual(initialWorkers);
+          expect(await surface.evaluate((element) => {
+            const probe = document.createElement("span");
+            probe.className = "sambee-syntax-keyword";
+            probe.style.setProperty("--sambee-syntax-keyword", "rgb(225, 0, 102)");
+            element.parentElement!.append(probe);
+            const color = getComputedStyle(probe).color;
+            probe.remove();
+            return color;
+          })).toBe("rgb(225, 0, 102)");
+        }
+        await node.dispose();
+        await original?.dispose();
+        if (preview) await page.getByRole("button", { name: "Close search", exact: true }).click();
+        else {
+          await searchControls.getByRole("button", { name: "Close", exact: true }).click();
+          await expect(searchControls).toBeHidden();
+        }
+      };
+
+      const preview = kind === "markdown" && !editing;
+      const surface = preview ? page.locator('[data-markdown-search-root="true"]') : page.getByRole("textbox", { name: kind === "text" ? "Text editor" : "Markdown editor" });
+      await checkThemes(surface, preview);
+      await page.getByRole("button", { name: "Close", exact: true }).click();
+      if (editing) {
+        await expect(page.getByRole("button", { name: "Edit", exact: true })).toBeVisible();
+        await page.getByRole("button", { name: "Close", exact: true }).click();
+      }
+      await expect(surface).toHaveCount(0);
+      await expect(page).toHaveURL("/browse/smb/demo");
+      await expect(page.getByRole("button", { name: "Edit", exact: true })).toBeHidden();
+      await expect(file).toBeVisible();
+      await expect.poll(() => page.workers().length).toBe(0);
+    });
+    }
+    }
+  }
+});
+
+test.describe("production syntax theme dialog", () => {
+  test.skip(process.env.SAMBEE_E2E_PRODUCTION !== "1", "Requires the production build and approved demo route");
+
+  async function openEditor(page: Page, width: number, mode: "light" | "dark", target: "user" | "site" | "built-in" = "user", isAdmin = true) {
+    await page.setViewportSize({ width, height: width < 600 ? 600 : 900 });
+    await serveProductionAssets(page);
+    const selected: StoredTheme = {
+      id: target === "site" ? "dialog-site" : "dialog-personal", scope: target === "site" ? "site" : "user", version: 3,
+      definition: { ...editableDefinition(builtInThemes.find(theme => theme.mode === mode)!), name: "Dialog theme" },
+    };
+    const base = builtInThemes.find(theme => theme.mode === mode)!;
+    const selectedId = target === "built-in" ? base.id : selected.id;
+    const selectedName = target === "built-in" ? base.name : selected.definition.name;
+    const storedThemes: StoredTheme[] = target === "built-in" ? [] : [selected];
+    const writes: { method: string; path: string; body: unknown }[] = [];
+    const settingsWrites: unknown[] = [];
+    let nextFailure: { status: number; detail: string } | undefined;
+    await mockMarkdownViewerApi(page, { initialMarkdown: "# Theme dialog fixture", themeId: () => selectedId, userRole: isAdmin ? "admin" : "user" });
+    const [version, gitCommit] = await Promise.all([
+      readFile(new URL("../../VERSION", import.meta.url), "utf8"),
+      readFile(new URL("../../GIT_COMMIT", import.meta.url), "utf8"),
+    ]);
+    await page.route("**/api/version", route => fulfillJson(route, {
+      version: version.trim(), git_commit: gitCommit.trim(), build_time: "2026-10-22T00:00:00Z",
+    }));
+    await page.route("**/api/auth/me/settings", async route => {
+      if (route.request().method() !== "PUT") return route.fallback();
+      const update = route.request().postDataJSON();
+      if (update.field === "appearance.theme_id") settingsWrites.push(update);
+      await route.fallback();
+    });
+    await page.route("**/api/themes**", async route => {
+      const request = route.request();
+      if (request.method() === "GET") return fulfillJson(route, { site_default_id: "sambee-light", themes: storedThemes });
+      const body = request.postDataJSON();
+      const path = new URL(request.url()).pathname;
+      writes.push({ method: request.method(), path, body });
+      if (nextFailure) {
+        const failure = nextFailure;
+        nextFailure = undefined;
+        return fulfillJson(route, { detail: failure.detail }, failure.status);
+      }
+      if (request.method() === "POST" && path === "/api/themes") {
+        const created: StoredTheme = { id: `dialog-copy-${writes.length}`, scope: body.scope, version: 1, definition: body.definition };
+        storedThemes.push(created);
+        return fulfillJson(route, created);
+      }
+      if (request.method() !== "PUT" || path !== `/api/themes/${selected.id}`) return fulfillJson(route, { detail: "Unexpected theme write" }, 400);
+      selected.definition = body.definition;
+      selected.version += 1;
+      await fulfillJson(route, selected);
+    });
+    await page.addLocatorHandler(page.getByRole("dialog").filter({ has: page.getByRole("heading", { name: "Update available", exact: true }) }), async dialog => {
+      await dialog.getByRole("button", { name: "Later", exact: true }).click();
+    });
+    await page.goto("/browse/smb/demo");
+    if (width < 600) await page.getByRole("button", { name: "Open menu", exact: true }).click();
+    await page.getByRole("button", { name: "Open settings", exact: true }).click();
+    if (width < 600) await page.getByRole("list").getByText("Appearance", { exact: true }).click();
+    else await page.getByRole("listbox", { name: "Settings categories", exact: true }).getByText("Appearance", { exact: true }).click();
+    const selectedRadio = page.getByText(target === "site" ? "Site themes" : target === "user" ? "Your themes" : "Built-in themes", { exact: true }).locator("..").getByRole("radio", { name: selectedName, exact: true });
+    await expect(selectedRadio).toBeChecked();
+    await page.getByRole("button", { name: "Edit", exact: true }).click();
+    const editor = page.getByRole("dialog").filter({ has: page.getByRole("heading", { name: `Edit ${selectedName} (${target === "user" ? "personal" : target})`, exact: true }) });
+    await expect(editor).toBeVisible();
+    return { editor, selected, selectedName, selectedRadio, storedThemes, writes, settingsWrites,
+      rejectNextWrite: (status: number, detail: string) => { nextFailure = { status, detail }; },
+    };
+  }
+
+  for (const width of [1543, 390]) {
+    for (const mode of ["light", "dark"] as const) {
+    for (const target of ["user", "site"] as const) {
+      test(`${target === "user" ? "personal" : "site"} ${mode} syntax cancel, validation and versioned save at ${width}px`, async ({ page }) => {
+        const { editor, selected, selectedRadio, writes, settingsWrites } = await openEditor(page, width, mode, target, target === "site");
+        const original = structuredClone(selected.definition);
+        const expandSyntax = () => editor.getByRole("button", { name: "Syntax", exact: true }).click();
+        await expandSyntax();
+        await editor.getByRole("button", { name: "Choose Keyword color", exact: true }).click();
+        await expect(page.locator(".react-colorful__alpha")).toBeVisible();
+        await page.keyboard.press("Escape");
+        await expect(page.locator(".react-colorful__alpha")).toHaveCount(0);
+        const keyword = editor.getByRole("textbox", { name: "Keyword", exact: true });
+        const punctuation = editor.getByRole("textbox", { name: "Punctuation", exact: true });
+        await punctuation.scrollIntoViewIfNeeded();
+        await expect(punctuation).toBeInViewport();
+        const actions = await Promise.all(["Import", "Export", "Cancel", "Save copy", "Save"].map(async name => {
+          const button = editor.getByRole("button", { name, exact: true });
+          await expect(button).toBeInViewport();
+          return (await button.boundingBox())!;
+        }));
+        const field = (await punctuation.boundingBox())!;
+        expect(field.y + field.height).toBeLessThanOrEqual(Math.min(...actions.map(action => action.y)));
+        await keyword.fill("#12345678");
+        expect(writes).toEqual([]);
+        expect(selected.definition).toEqual(original);
+        await editor.getByRole("button", { name: "Cancel", exact: true }).click();
+        await expect(editor).toHaveCount(0);
+        await page.getByRole("button", { name: "Edit", exact: true }).click();
+        const name = editor.getByRole("textbox", { name: "Name", exact: true });
+        await name.fill(" ");
+        await editor.getByRole("button", { name: "Save", exact: true }).click();
+        await expect(name).toBeFocused();
+        expect(writes).toEqual([]);
+        await name.fill(original.name);
+        await expandSyntax();
+        await expect(keyword).toHaveValue(original.components!.syntax!.keyword);
+        await keyword.fill("#bad");
+        await editor.getByRole("button", { name: "Save", exact: true }).click();
+        await expect(keyword).toBeFocused();
+        await expect(keyword).toHaveAttribute("aria-invalid", "true");
+        expect(writes).toEqual([]);
+        await keyword.fill("#12345678");
+        await editor.getByRole("button", { name: "Save", exact: true }).click();
+        await expect(editor).toHaveCount(0);
+        expect(writes).toEqual([{ method: "PUT", path: `/api/themes/${selected.id}`, body: {
+          scope: target, version: 3,
+          definition: { ...original, components: { ...original.components, syntax: { ...original.components!.syntax!, keyword: "#12345678" } } },
+        } }]);
+        expect(settingsWrites).toEqual([]);
+        await expect(selectedRadio).toBeChecked();
+      });
+    }
+    }
+    for (const target of ["built-in", "site", "user"] as const) {
+      for (const isAdmin of [false, true]) {
+        test(`${isAdmin ? "admin" : "user"} ${target} syntax permissions and copy at ${width}px`, async ({ page }) => {
+          const { editor, selected, selectedRadio, writes, settingsWrites } = await openEditor(page, width, "light", target, isAdmin);
+          const original = target === "built-in" ? editableDefinition(builtInThemes[0]!) : structuredClone(selected.definition);
+          const writable = target === "user" || (target === "site" && isAdmin);
+          if (writable) await expect(editor.getByRole("button", { name: "Save", exact: true })).toBeEnabled();
+          else await expect(editor.getByRole("button", { name: "Save", exact: true })).toBeDisabled();
+          await editor.getByRole("button", { name: "Syntax", exact: true }).click();
+          const keyword = editor.getByRole("textbox", { name: "Keyword", exact: true });
+          await keyword.fill("#bad");
+          await editor.getByRole("button", { name: "Core", exact: true }).click();
+          await editor.getByRole("button", { name: "Save copy", exact: true }).click();
+          await expect(page.getByRole("menuitem", { name: "Your themes", exact: true })).toBeVisible();
+          if (isAdmin) await expect(page.getByRole("menuitem", { name: "Site themes", exact: true })).toBeVisible();
+          else await expect(page.getByRole("menuitem", { name: "Site themes", exact: true })).toHaveCount(0);
+          const destination = isAdmin ? "site" : "user";
+          await page.getByRole("menuitem", { name: isAdmin ? "Site themes" : "Your themes", exact: true }).click();
+          await expect(keyword).toBeFocused();
+          await expect(keyword).toHaveAttribute("aria-invalid", "true");
+          await expect(editor.getByRole("button", { name: "Syntax", exact: true })).toHaveAttribute("aria-expanded", "true");
+          expect(writes).toEqual([]);
+          await keyword.fill("#12345678");
+          await editor.getByRole("button", { name: "Save copy", exact: true }).click();
+          await page.keyboard.press("Escape");
+          await expect(editor.getByRole("button", { name: "Save copy", exact: true })).toBeFocused();
+          await expect(page.getByRole("menuitem", { name: "Your themes", exact: true })).toHaveCount(0);
+          await expect(editor).toBeVisible();
+          await editor.getByRole("button", { name: "Save copy", exact: true }).click();
+          await page.getByRole("menuitem", { name: isAdmin ? "Site themes" : "Your themes", exact: true }).click();
+          await expect(editor).toHaveCount(0);
+          const copiedName = target === destination ? `${original.name} (copy)` : original.name;
+          expect(writes).toEqual([{ method: "POST", path: "/api/themes", body: {
+            scope: destination,
+            definition: { ...original, name: copiedName, components: { ...original.components, syntax: { ...original.components!.syntax!, keyword: "#12345678" } } },
+          } }]);
+          expect(settingsWrites).toEqual([]);
+          await expect(selectedRadio).toBeChecked();
+          expect(selected.definition.components!.syntax).toEqual(original.components!.syntax);
+        });
+      }
+    }
+    for (const status of [403, 409]) {
+      test(`${status} save rejection preserves syntax draft at ${width}px`, async ({ page }) => {
+        const { editor, selected, writes, settingsWrites, rejectNextWrite } = await openEditor(page, width, "dark", status === 409 ? "site" : "user", status === 409);
+        const original = structuredClone(selected);
+        const detail = status === 409 ? "Theme changed in another tab. Refresh and try again." : "Theme permission changed. Refresh to check your access.";
+        rejectNextWrite(status, detail);
+        await editor.getByRole("button", { name: "Syntax", exact: true }).click();
+        const keyword = editor.getByRole("textbox", { name: "Keyword", exact: true });
+        await keyword.fill("#abcdef80");
+        await editor.getByRole("button", { name: "Save", exact: true }).click();
+        await expect(editor.getByRole("alert")).toHaveText(detail);
+        await expect(keyword).toHaveValue("#ABCDEF80");
+        await expect(editor.getByRole("button", { name: "Save", exact: true })).toBeEnabled();
+        expect(selected).toEqual(original);
+        expect(writes).toEqual([{ method: "PUT", path: `/api/themes/${selected.id}`, body: {
+          scope: original.scope, version: original.version,
+          definition: { ...original.definition, components: { ...original.definition.components, syntax: { ...original.definition.components!.syntax!, keyword: "#ABCDEF80" } } },
+        } }]);
+        await editor.getByRole("button", { name: "Cancel", exact: true }).click();
+        await expect(editor).toHaveCount(0);
+        expect(writes).toHaveLength(1);
+        expect(settingsWrites).toEqual([]);
+      });
+    }
+  }
+});
+
+interface CiWorkerProbe {
+  jobs: { kind: string; terminated: boolean; messages: string[] }[];
+  errors: string[];
+  held: boolean;
+  release: () => void;
+}
+
+async function installCiWorkerProbe(page: Page, holdNormalization = false): Promise<void> {
+  await page.addInitScript((holdNext) => {
+    const probe: CiWorkerProbe = { jobs: [], errors: [], held: false, release: () => {} };
+    Object.assign(window, { ciWorkerProbe: probe });
+    const NativeWorker = window.Worker;
+    window.Worker = class extends NativeWorker {
+      private job: CiWorkerProbe["jobs"][number];
+      constructor(url: string | URL, options?: WorkerOptions) {
+        super(url, options);
+        const path = String(url);
+        this.job = { kind: path.includes("markdownCodePreparation.worker") ? "normalization" : path.includes("markdownSyntax.worker") ? "syntax" : path.includes("sourceRegexSearch.worker") ? "regex" : "other", terminated: false, messages: [] };
+        probe.jobs.push(this.job);
+        this.addEventListener("error", event => probe.errors.push(event.message));
+        this.addEventListener("messageerror", () => probe.errors.push("Worker message could not be decoded"));
+        this.addEventListener("message", event => {
+          this.job.messages.push(event.data?.type);
+          if (event.data?.type === "error") probe.errors.push(event.data.message);
+          if (holdNext && this.job.kind === "normalization" && event.data?.type === "complete") {
+            event.stopImmediatePropagation();
+            holdNext = false;
+            probe.held = true;
+            probe.release = () => {
+              probe.held = false;
+              this.dispatchEvent(new MessageEvent("message", { data: event.data }));
+            };
+          }
+        });
+      }
+      terminate() {
+        this.job.terminated = true;
+        super.terminate();
+      }
+    };
+  }, holdNormalization);
+}
+
+const readCiProbe = (page: Page) => page.evaluate(() => {
+  const probe = (window as typeof window & { ciWorkerProbe: CiWorkerProbe }).ciWorkerProbe;
+  return { jobs: probe.jobs, errors: probe.errors, held: probe.held };
+});
+
+test.describe("production CI correctness", () => {
+  test.skip(process.env.SAMBEE_E2E_PRODUCTION !== "1", "Requires a normal production build");
+  const markdown = "# CI preview\n\n[CI tail](#ci-tail)\n\nA &amp; B and &#x1F680;\n\n```javascript\nconst alpha = 1;\n```\n\n## CI tail\n\nLast paragraph.\n";
+
+  for (const width of [1543, 390]) {
+    for (const scenario of ["real workers", "native contracts", "edit and save", "cancel and reopen"] as const) {
+      test(`CI ${scenario} at ${width}px`, async ({ browser }) => {
+        const original = scenario === "edit and save" ? "one=1 two=2\n" : markdown;
+        const proxy = await createCacheableViewerProxy({ initialMarkdown: original, existingFilePaths: [DEMO_PATH], wordWrapEnabled: false });
+        let context: BrowserContext | undefined;
+        try {
+          context = await browser.newContext({ viewport: { width, height: 900 }, serviceWorkers: "block", proxy: { server: proxy.url, bypass: "<-loopback>" } });
+          const page = await context.newPage();
+          const errors: string[] = [];
+          page.on("pageerror", error => errors.push(error.message));
+          page.on("response", response => { if (new URL(response.url()).origin === CACHE_PROOF_ORIGIN && response.status() >= 400) errors.push(`${response.status()} ${response.url()}`); });
+          await installCiWorkerProbe(page, scenario === "cancel and reopen");
+          await page.goto("/browse/smb/demo");
+          await page.getByRole("button", { name: "Later", exact: true }).click();
+          const file = page.getByRole("button", { name: DEMO_PATH, exact: true }).or(page.getByRole("button", { name: `File: ${DEMO_PATH}`, exact: true }));
+          await file.click();
+          const root = page.locator('[data-markdown-search-root="true"]');
+
+          if (scenario === "cancel and reopen") {
+            await expect.poll(async () => (await readCiProbe(page)).held).toBe(true);
+            await page.getByRole("button", { name: "Close", exact: true }).click();
+            await expect.poll(async () => (await readCiProbe(page)).jobs.every(job => job.terminated)).toBe(true);
+            await page.evaluate(() => (window as typeof window & { ciWorkerProbe: CiWorkerProbe }).ciWorkerProbe.release());
+            await expect(root).toHaveCount(0);
+            await file.click();
+          }
+
+          await expect(root).toBeVisible();
+          if (scenario !== "edit and save") {
+            await expect(root.locator("p").nth(1)).toHaveText("A & B and \u{1F680}");
+            await expect(root.locator("pre code")).toHaveText("const alpha = 1;\n");
+            await expect.poll(async () => (await readCiProbe(page)).jobs.some(job => job.kind === "syntax" && job.messages.includes("ranges") && job.messages.includes("complete"))).toBe(true);
+            expect((await readCiProbe(page)).jobs.some(job => job.kind === "normalization" && job.messages.includes("normalized-source") && job.messages.includes("tree-chunk") && job.messages.includes("complete"))).toBe(true);
+          }
+
+          if (scenario === "native contracts") {
+            const viewport = root.locator("..");
+            await expect(viewport).toBeFocused();
+            await page.keyboard.press("Tab");
+            await expect(root.getByRole("link", { name: "CI tail", exact: true })).toBeFocused();
+            await page.keyboard.press("Enter");
+            await expect(root.getByRole("heading", { name: "CI tail", exact: true })).toHaveAttribute("id", "sambee-markdown-ci-tail");
+            await viewport.focus();
+            await page.keyboard.press("Control+a");
+            const selected = await page.evaluate(() => window.getSelection()?.toString() ?? "");
+            expect(selected).toContain("const alpha = 1;");
+            expect(selected).toContain("Last paragraph.");
+            expect(await root.ariaSnapshot()).toContain('heading "CI preview" [level=1]');
+            await page.getByRole("button", { name: "Search", exact: true }).click();
+            await page.getByPlaceholder("Search", { exact: true }).fill("alpha");
+            await expect(page.getByText("1 / 1", { exact: true })).toBeVisible();
+          }
+
+          if (scenario === "edit and save") {
+            await enterMarkdownEditMode(page);
+            const editor = page.getByRole("textbox", { name: "Markdown editor" });
+            await editor.click();
+            await page.keyboard.press("Control+h");
+            const controls = page.getByRole("search");
+            await controls.getByRole("button", { name: "Use regular expression", exact: true }).click();
+            await controls.getByRole("textbox", { name: "Find", exact: true }).fill("(one|two)=(\\d)");
+            await controls.getByRole("textbox", { name: "Replace", exact: true }).fill("$2:$1");
+            await expect(controls.getByText("0 / 2", { exact: true })).toBeVisible();
+            await page.mouse.move(0, 0);
+            await expect(page.getByRole("tooltip")).toHaveCount(0);
+            await controls.getByRole("button", { name: "Replace all", exact: true }).click();
+            await expect(editor).toContainText("1:one 2:two");
+            await controls.getByRole("button", { name: "Close", exact: true }).click();
+            await editor.focus();
+            await page.keyboard.press("Control+z");
+            await expect(editor).toContainText("one=1 two=2");
+            await page.keyboard.press("Control+Shift+Z");
+            await expect(editor).toContainText("1:one 2:two");
+            await page.getByRole("button", { name: "Save", exact: true }).click();
+            await expect.poll(() => proxy.uploads.length).toBe(1);
+            const upload = proxy.uploads[0];
+            const form = await new Response(upload.body, { headers: { "Content-Type": upload.contentType } }).formData();
+            const files = [...form.values()].filter((value): value is File => typeof value !== "string");
+            expect(files).toHaveLength(1);
+            expect(await files[0].text()).toBe("1:one 2:two\n");
+            expect((await readCiProbe(page)).jobs.some(job => job.kind === "regex" && job.messages.includes("complete"))).toBe(true);
+            await page.getByRole("button", { name: "Close", exact: true }).click();
+            await expect(editor).toHaveCount(0);
+          }
+
+          await page.getByRole("button", { name: "Close", exact: true }).click();
+          await expect(root).toHaveCount(0);
+          await expect.poll(async () => (await readCiProbe(page)).jobs.every(job => job.terminated)).toBe(true);
+          expect((await readCiProbe(page)).errors).toEqual([]);
+          expect(errors).toEqual([]);
+          expect(proxy.errors).toEqual([]);
+        } finally {
+          try {
+            await context?.close();
+          } finally {
+            await proxy.close();
+          }
+        }
+      });
+    }
+  }
+});
+
+test.describe("development Markdown worker", () => {
+  test.skip(process.env.SAMBEE_E2E_DEVELOPMENT !== "1", "Requires the development server and approved demo route");
+  test("normalizes and renders entity text without DOM globals in the worker", async ({ page }) => {
+    const errors: string[] = [];
+    page.on("pageerror", (error) => errors.push(error.message));
+    await page.addLocatorHandler(page.getByRole("dialog", { name: "Update available" }), async (dialog) => {
+      await dialog.getByRole("button", { name: "Later", exact: true }).click();
+    });
+    await mockMarkdownViewerApi(page, { initialMarkdown: "# Preview\n\nA &amp; B and &#x1F680;\n\n```js\nconst alpha = 1;\n```", existingFilePaths: [DEMO_PATH] });
+    await page.goto("/browse/smb/demo");
+    await page.getByRole("button").filter({ has: page.getByText(DEMO_PATH, { exact: true }) }).click();
+    const root = page.locator('[data-markdown-search-root="true"]');
+    await expect(root.getByRole("heading", { name: "Preview" })).toBeVisible();
+    await expect(root.locator("p")).toHaveText("A & B and 🚀");
+    await expect(root.locator("pre code")).toHaveText("const alpha = 1;\n");
+    await expect(page.getByRole("alert").filter({ hasText: "Server is busy" })).toHaveCount(0);
+    expect(errors).toEqual([]);
+  });
+});
+
+test.describe("production source regex containment", () => {
+  test.skip(process.env.SAMBEE_E2E_PRODUCTION !== "1", "Requires the production build and approved demo route");
+  for (const width of [1543, 390]) {
+    test(`native commands and stalled workers at ${width}px`, async ({ page }, testInfo) => {
+      test.setTimeout(60_000);
+      await page.setViewportSize({ width, height: 900 });
+      await serveProductionAssets(page);
+      await page.addInitScript(() => {
+        const OriginalWorker = window.Worker;
+        const state = { stall: "", observed: "", live: 0, requests: [] as string[], created: 0, sources: 0, navigations: 0, holdNavigation: false, held: false, release: null as (() => void) | null };
+        Object.assign(window, { sourceRegexProbe: state });
+        window.Worker = class extends OriginalWorker {
+          private owned = false;
+          constructor(url: string | URL, options?: WorkerOptions) {
+            super(url, options);
+            this.owned = String(url).includes("sourceRegexSearch.worker");
+            if (this.owned) {
+              state.live += 1;
+              state.created += 1;
+              this.addEventListener("message", (event) => {
+                if (!state.holdNavigation || event.data.type !== "complete") return;
+                event.stopImmediatePropagation();
+                state.holdNavigation = false;
+                state.held = true;
+                state.release = () => {
+                  state.held = false;
+                  state.release = null;
+                  this.dispatchEvent(new MessageEvent("message", { data: event.data }));
+                };
+              });
+            }
+          }
+          postMessage(message: unknown, transfer?: Transferable[]) {
+            const request = message as { type?: string; operation?: string; query?: { search: string } };
+            if (this.owned && request.type === "source") state.sources += 1;
+            if (this.owned && request.type === "navigate") state.navigations += 1;
+            if (this.owned && request.type === "start") {
+              state.requests.push(request.operation!);
+              if (request.operation === state.stall) {
+                state.observed = state.stall;
+                state.stall = "";
+                request.query!.search = "(a+)+$";
+              }
+            }
+            super.postMessage(message, transfer ?? []);
+          }
+          terminate() {
+            if (this.owned) { state.live -= 1; this.owned = false; }
+            super.terminate();
+          }
+        };
+      });
+      const original = `one=1 two=2\n\n${"a".repeat(128)}!`;
+      await mockMarkdownViewerApi(page, { initialMarkdown: original, existingFilePaths: [DEMO_PATH] });
+      await page.goto("/browse/smb/demo");
+      await page.getByRole("button", { name: "Later", exact: true }).click();
+      await (width < 600 ? page.getByRole("button", { name: `File: ${DEMO_PATH}`, exact: true }) : page.getByRole("button").filter({ hasText: /^note\.md$/ })).click();
+      await page.getByRole("button", { name: "Edit", exact: true }).click();
+      const editor = page.getByRole("textbox", { name: "Markdown editor" });
+      await expect(editor).toHaveAttribute("contenteditable", "true");
+      await editor.focus();
+      await page.keyboard.press("Control+h");
+      const controls = page.getByTestId("code-mirror-find-replace-popover");
+      const find = controls.getByRole("textbox", { name: "Find", exact: true });
+      const replace = controls.getByRole("textbox", { name: "Replace", exact: true });
+      await controls.getByRole("button", { name: "Use regular expression", exact: true }).click();
+      await find.fill("(one|two)=(\\d)");
+      await expect(controls.getByText("0 / 2", { exact: true })).toBeVisible();
+      await controls.getByRole("button", { name: "Next match", exact: true }).click();
+      await expect(controls.getByText("1 / 2", { exact: true })).toBeVisible();
+      await controls.getByRole("button", { name: "Next match", exact: true }).click();
+      await expect(controls.getByText("2 / 2", { exact: true })).toBeVisible();
+      await controls.getByRole("button", { name: "Previous match", exact: true }).click();
+      await expect(controls.getByText("1 / 2", { exact: true })).toBeVisible();
+      const beforeBurst = await page.evaluate(() => {
+        const state = (window as unknown as { sourceRegexProbe: { holdNavigation: boolean; created: number; sources: number; navigations: number } }).sourceRegexProbe;
+        state.holdNavigation = true;
+        return { created: state.created, sources: state.sources, navigations: state.navigations };
+      });
+      await controls.getByRole("button", { name: "Next match", exact: true }).click();
+      await expect.poll(() => page.evaluate(() => (window as unknown as { sourceRegexProbe: { held: boolean } }).sourceRegexProbe.held)).toBe(true);
+      await controls.getByRole("button", { name: "Next match", exact: true }).click();
+      await controls.getByRole("button", { name: "Previous match", exact: true }).click();
+      await controls.getByRole("button", { name: "Next match", exact: true }).click();
+      await page.evaluate(() => (window as unknown as { sourceRegexProbe: { release: (() => void) | null } }).sourceRegexProbe.release!());
+      await expect.poll(() => page.evaluate(() => {
+        const { live, created, sources, navigations } = (window as unknown as { sourceRegexProbe: { live: number; created: number; sources: number; navigations: number } }).sourceRegexProbe;
+        return { live, created, sources, navigations };
+      })).toEqual({ live: 0, created: beforeBurst.created + 1, sources: beforeBurst.sources + 1, navigations: beforeBurst.navigations + 3 });
+      await expect(controls.getByText("1 / 2", { exact: true })).toBeVisible();
+      await replace.fill("$2:$1");
+      await expect(controls.getByText("1 / 2", { exact: true })).toBeVisible();
+      await controls.getByRole("button", { name: "Replace current match", exact: true }).click();
+      await expect(editor).toContainText("1:one two=2");
+      await expect(controls.getByText("1 / 1", { exact: true })).toBeVisible();
+      await controls.getByRole("button", { name: "Replace all", exact: true }).click();
+      await expect(editor).toContainText("1:one 2:two");
+      await editor.focus();
+      await page.keyboard.press("Control+z");
+      await expect(editor).toContainText("1:one two=2");
+      await find.fill("a+");
+      await expect(controls.getByText(/^[01] \/ 1$/)).toBeVisible();
+      const measurements: { operation: string; keyboardMs: number }[] = [];
+      for (const operation of ["count", "next", "previous", "replace-one", "replace-all"]) {
+        await page.mouse.move(0, 0);
+        await expect(page.getByRole("tooltip")).toHaveCount(0);
+        await page.evaluate((operation) => {
+          const state = (window as unknown as { sourceRegexProbe: { stall: string; observed: string } }).sourceRegexProbe;
+          state.stall = operation; state.observed = "";
+        }, operation);
+        if (operation === "count") await find.fill("a{1,}");
+        else await controls.getByRole("button", { name: { next: "Next match", previous: "Previous match", "replace-one": "Replace current match", "replace-all": "Replace all" }[operation]!, exact: true }).click();
+        await expect.poll(() => page.evaluate(() => (window as unknown as { sourceRegexProbe: { observed: string } }).sourceRegexProbe.observed)).toBe(operation);
+        await find.focus();
+        const before = await find.evaluate((element: HTMLInputElement) => { element.setSelectionRange(element.value.length, element.value.length); return element.selectionStart; });
+        const start = Date.now();
+        await find.press("ArrowLeft");
+        expect(await find.evaluate((element: HTMLInputElement) => element.selectionStart)).toBe(before! - 1);
+        measurements.push({ operation, keyboardMs: Date.now() - start });
+        await expect(controls.getByText("Loading...", { exact: true })).toBeVisible();
+        await expect(controls.getByRole("alert")).toContainText("timed out");
+        await expect(editor).toContainText("1:one two=2");
+        await find.fill("a");
+        await expect(controls.getByText(/^[0-9]+ \/ 128$/)).toBeVisible();
+        await find.fill("a+");
+        await expect(controls.getByText(/^[01] \/ 1$/)).toBeVisible();
+      }
+      await find.fill("(a+)+$");
+      await expect(controls.getByText("Loading...", { exact: true })).toBeVisible();
+      await find.press("ArrowLeft");
+      await expect(controls.getByRole("alert")).toContainText("timed out");
+      await find.fill("a+");
+      await expect(controls.getByText(/^[01] \/ 1$/)).toBeVisible();
+      await expect.poll(() => page.evaluate(() => (window as unknown as { sourceRegexProbe: { live: number } }).sourceRegexProbe.live)).toBe(0);
+      const commit = await page.evaluate(() => performance.getEntriesByName("sambee:source-search:commit").map((entry) => ({ duration: entry.duration, detail: (entry as PerformanceMeasure).detail })));
+      await testInfo.attach("source-regex-containment.json", { body: JSON.stringify({ width, measurements, commit, note: "Real viewer worker termination/restart and keyboard servicing; small-document commit samples, not large replace-all or hardware input-to-paint acceptance." }, null, 2), contentType: "application/json" });
+    });
+  }
+});
+
+test("Markdown viewer API fixtures preserve transfer-stream request handling", async ({ page }) => {
+  let receivedBody: string | undefined;
+  await mockMarkdownViewerApi(page, {
+    initialMarkdown: "hello",
+    onTransferStream: async route => {
+      const request = route.request();
+      expect(await request.headerValue("content-type")).toBe("application/octet-stream");
+      receivedBody = request.postDataBuffer()?.toString("utf8");
+      await fulfillJson(route, { status: "completed" });
+    },
+  });
+  await page.goto("http://localhost:3000/browse/smb/demo");
+  const result = await page.evaluate(async connectionId => {
+    const response = await fetch(`/api/browse/${connectionId}/transfer-stream?path=fixture.txt`, {
+      method: "POST", headers: { "Content-Type": "application/octet-stream" }, body: "fixture body",
+    });
+    return { status: response.status, body: await response.json() };
+  }, DEMO_CONNECTION_ID);
+  expect(receivedBody).toBe("fixture body");
+  expect(result).toEqual({ status: 200, body: { status: "completed" } });
+});
+
+test.describe("production syntax readiness", () => {
+  test.skip(process.env.SAMBEE_E2E_PRODUCTION !== "1", "Requires the production build and approved demo route");
+  test.beforeAll(() => {
+    if (process.env.SAMBEE_E2E_MEMORY === "1" || process.env.SAMBEE_E2E_TRACE === "1") throw new Error("Readiness acceptance must run without forced GC or diagnostic tracing.");
+  });
+  for (const width of [1543, 390]) {
+    for (const fixture of SYNTAX_PUBLICATION_FIXTURES) {
+    test(`unheld ${fixture.name} readiness at ${width}px`, async ({ page: defaultPage, browser }, testInfo) => {
+      const longLine = fixture.name === "long-line";
+      const line = longLine ? "let x=1; " : "let x=1;\n";
+      const text = `${line.repeat(fixture.lines)}${longLine ? "\n" : ""}`;
+      const markdown = Array.from({ length: fixture.blocks }, () => `\`\`\`js\n${text}\`\`\``).join("\n\n");
+      const cacheProxy = process.env.SAMBEE_E2E_HTTP_CACHE === "1" ? await createCacheableViewerProxy({ initialMarkdown: markdown }) : undefined;
+      let cacheContext: BrowserContext | undefined;
+      try {
+      cacheContext = cacheProxy ? await browser.newContext({ proxy: { server: cacheProxy.url, bypass: "<-loopback>" }, serviceWorkers: "block" }) : undefined;
+      const page = cacheContext ? await cacheContext.newPage() : defaultPage;
+      await page.setViewportSize({ width, height: 900 });
+      if (!cacheProxy) await serveProductionAssets(page);
+      await page.addInitScript(({ line, text: expectedText, lines, blocks, longLine, filename }) => {
+        const metrics: Record<string, number> = {};
+        const outcomes: { block: number; reason?: string }[] = [];
+        const syntaxWorkerUrls: string[] = [];
+        let openedAt: number | undefined;
+        let firstBlockPreparedAt: number | undefined;
+        let preparedAt: number | undefined;
+        let expected: { from: number; to: number; category: string }[] | undefined;
+        const scheduled = new Set<string>();
+        const afterFrames = (metric: string) => {
+          if (scheduled.has(metric)) return;
+          scheduled.add(metric);
+          requestAnimationFrame(() => requestAnimationFrame(() => {
+            metrics[metric] = performance.now() - openedAt!;
+          }));
+        };
+        document.addEventListener("click", (event) => {
+          const button = event.target instanceof Element ? event.target.closest("button") : null;
+          if (!(button?.getAttribute("aria-label") === `File: ${filename}` || button?.textContent?.trim() === filename)) return;
+          for (const key of Object.keys(metrics)) delete metrics[key];
+          outcomes.length = 0;
+          scheduled.clear();
+          expected = undefined;
+          firstBlockPreparedAt = undefined;
+          preparedAt = undefined;
+          openedAt = performance.now();
+          const inspect = () => {
+            const root = document.querySelector<HTMLElement>('[data-markdown-search-root="true"]');
+            const codes = root?.querySelectorAll("pre > code");
+            const code = codes?.[0];
+            const search = document.querySelector<HTMLButtonElement>('button[aria-label="Search"]');
+            if (codes?.length === blocks && [...codes].every(element => element.textContent === expectedText) && search && !search.disabled) {
+              afterFrames("firstUsableText");
+              if (!expected) {
+                expected = [];
+                const bounds = root!.parentElement!.getBoundingClientRect();
+                const preBounds = code.closest("pre")!.getBoundingClientRect();
+                const left = Math.max(bounds.left, preBounds.left);
+                const right = Math.min(bounds.right, preBounds.right);
+                const node = code.firstChild!;
+                const tokens = [[0, 3, "keyword"], [4, 5, "identifier"], [5, 6, "operator"], [6, 7, "number"], [7, 8, "punctuation"]] as const;
+                for (let index = 0; index < lines; index += 1) {
+                  const from = index * line.length;
+                  const range = new Range();
+                  range.setStart(node, from);
+                  range.setEnd(node, from + line.length - 1);
+                  const rect = range.getBoundingClientRect();
+                  if (rect.top >= bounds.bottom) break;
+                  if (longLine && rect.left >= right) break;
+                  if (rect.top < bounds.top || rect.bottom > bounds.bottom) continue;
+                  for (const [start, end, category] of tokens) {
+                    if (!longLine) {
+                      expected.push({ from: from + start, to: from + end, category });
+                      continue;
+                    }
+                    for (let offset = from + start; offset < from + end; offset += 1) {
+                      range.setStart(node, offset);
+                      range.setEnd(node, offset + 1);
+                      const character = range.getBoundingClientRect();
+                      if (character.left >= left && character.right <= right) expected.push({ from: offset, to: offset + 1, category });
+                    }
+                  }
+                }
+              }
+              const published = new Map<string, Range[]>();
+              for (const [name, ranges] of CSS.highlights) {
+                const match = /^markdown-syntax-\d+-(.+)$/.exec(name);
+                if (match) published.set(match[1], [...ranges] as Range[]);
+              }
+              const completeWindow = expected.length > 0 && expected.every(token => (published.get(token.category) ?? []).some(range =>
+                range.startContainer === code.firstChild && range.endContainer === code.firstChild && range.startOffset <= token.from && range.endOffset >= token.to));
+              if (completeWindow) {
+                afterFrames("firstVisibleSyntax");
+                if (outcomes.length === blocks) afterFrames("fullSyntaxPreparation");
+              }
+            }
+            if (Object.keys(metrics).length < 3) requestAnimationFrame(inspect);
+          };
+          requestAnimationFrame(inspect);
+        }, true);
+        const OriginalWorker = window.Worker;
+        window.Worker = class extends OriginalWorker {
+          constructor(url: string | URL, options?: WorkerOptions) {
+            super(url, options);
+            if (String(url).includes("markdownSyntax.worker")) {
+              syntaxWorkerUrls.push(String(url));
+              this.addEventListener("message", (event) => {
+              const response = event.data as { type?: string; block: number; reason?: string };
+              if (response.type === "complete") {
+                outcomes.push({ block: response.block, reason: response.reason });
+                firstBlockPreparedAt ??= performance.now();
+                preparedAt = performance.now();
+              }
+              });
+            }
+          }
+        };
+        Object.assign(window, { syntaxReadiness: () => ({ metrics, outcomes, syntaxWorkerUrls: [...syntaxWorkerUrls], expectedVisibleTokens: expected?.length ?? 0, workerFirstBlockMs: firstBlockPreparedAt === undefined || openedAt === undefined ? null : firstBlockPreparedAt - openedAt, workerResultsMs: preparedAt === undefined || openedAt === undefined ? null : preparedAt - openedAt }) });
+      }, { line, text, lines: fixture.lines, blocks: fixture.blocks, longLine, filename: DEMO_PATH });
+      if (!cacheProxy) await mockMarkdownViewerApi(page, { initialMarkdown: markdown });
+      await page.goto("http://localhost:3000/browse/smb/demo");
+      await page.getByRole("button", { name: "Later", exact: true }).click();
+      let coldSyntaxRequests: string[] = [];
+      for (const cycle of cacheProxy ? [0, 1] : [0]) {
+      const beforeOpen = cacheProxy?.requests.length ?? 0;
+      await (width < 600 ? page.getByRole("button", { name: `File: ${DEMO_PATH}`, exact: true }) : page.getByRole("button").filter({ hasText: /^note\.md$/ })).click();
+      const sample = () => page.evaluate(() => (window as unknown as { syntaxReadiness: () => { metrics: Record<string, number>; outcomes: { block: number; reason?: string }[]; syntaxWorkerUrls: string[]; expectedVisibleTokens: number; workerFirstBlockMs: number | null; workerResultsMs: number | null } }).syntaxReadiness());
+      await expect.poll(async () => Object.keys((await sample()).metrics).length).toBe(3);
+      const report = await sample();
+      const budget = evaluateViewerReadinessBudgets(report.metrics);
+      const networkAssets = cacheProxy?.requests.slice(beforeOpen).filter(path => path.endsWith(".js")) ?? [];
+      if (cacheProxy && cycle === 0) coldSyntaxRequests = networkAssets;
+      expect(report.expectedVisibleTokens).toBeGreaterThan(0);
+      expect(report.outcomes).toEqual(Array.from({ length: fixture.blocks }, (_, block) => ({ block, reason: undefined })));
+      expect(Object.values(report.metrics).every(value => Number.isFinite(value) && value >= 0)).toBe(true);
+      const root = page.locator('[data-markdown-search-root="true"]');
+      expect(await root.locator("pre > code").evaluateAll((elements, expected) => elements.every(element => element.textContent === expected), text)).toBe(true);
+      expect(await root.locator("pre > code").first().evaluate(element => {
+        const range = new Range();
+        range.setStart(element.firstChild!, 0);
+        range.setEnd(element.firstChild!, 8);
+        window.getSelection()?.removeAllRanges();
+        window.getSelection()?.addRange(range);
+        return window.getSelection()?.toString();
+      })).toBe(line.trimEnd());
+      await page.getByRole("button", { name: "Search", exact: true }).click();
+      await page.getByPlaceholder("Search", { exact: true }).fill("let x");
+      await expect(page.getByRole("button", { name: "Next match", exact: true }).locator("..").getByText(`1 / ${fixture.lines * fixture.blocks}`, { exact: true })).toBeVisible();
+      await testInfo.attach("syntax-readiness.json", { body: JSON.stringify({ fixture: fixture.name, width, engine: testInfo.project.name, trial: testInfo.repeatEachIndex, surface: "markdown-preview", cacheState: cacheProxy ? cycle === 0 ? "cold" : "warm-http-fresh-workers" : "routed-no-cache", ...report, budget, enforced: true, networkAssets, coldSyntaxRequests, cacheCondition: cacheProxy ? cycle === 0 ? "Fresh context and fresh syntax worker; ordinary HTTP with an initially empty browser cache, no preloading or request routing." : "Same page after close and zero live workers; fresh syntax worker with browser HTTP cache populated only by the measured first open." : "Fresh context and worker; routed assets disable normal HTTP caching. No cold/warm-cache acceptance claim.", scope: "Unheld file-open through exact text/control readiness and initial visible token coverage plus two frames. Functional selection/search follow timing, not hardware input/paint. Approved readiness limits enforced; no resource or full-rollout acceptance." }, null, 2), contentType: "application/json" });
+      await page.getByRole("button", { name: "Close", exact: true }).click();
+      await expect(root).toHaveCount(0);
+      await expect.poll(() => page.workers().length).toBe(0);
+      await expect.poll(() => page.evaluate(() => [...CSS.highlights.keys()].filter(name => name.startsWith("markdown-syntax-")).length)).toBe(0);
+      expect.soft(budget.status, JSON.stringify({ cacheState: cacheProxy ? cycle === 0 ? "cold" : "warm-http-fresh-workers" : "routed-no-cache", failures: budget.metrics.filter(metric => metric.status !== "pass") })).toBe("pass");
+      expect(report.syntaxWorkerUrls).toHaveLength(cycle + 1);
+      if (cacheProxy) {
+        expect(cacheProxy.errors).toEqual([]);
+        if (cycle === 0) {
+          expect(coldSyntaxRequests).toContain(new URL(report.syntaxWorkerUrls[0]).pathname);
+          expect(coldSyntaxRequests.length).toBeGreaterThan(1);
+        } else {
+          expect(report.syntaxWorkerUrls[1]).toBe(report.syntaxWorkerUrls[0]);
+          expect(networkAssets.filter(path => coldSyntaxRequests.includes(path))).toEqual([]);
+        }
+      }
+      }
+      } finally {
+        try { await cacheContext?.close(); } finally { await cacheProxy?.close(); }
+      }
+    });
+    }
+  }
+});
+
+test.describe("production native Markdown constraints", () => {
+  test.skip(process.env.SAMBEE_E2E_PRODUCTION !== "1", "Requires the production build and approved demo route");
+  const lineCount = 120;
+  const longLine = `const nativeLongLine = "${"horizontal native content ".repeat(240)}NATIVE_LONG_END";`;
+  const fixtures = [
+    { name: "multiline", code: Array.from({ length: lineCount }, (_, index) => `const nativeLine${index} = ${index};`).join("\n"), fence: "javascript" },
+    { name: "long-line", code: longLine, fence: "javascript" },
+    { name: "nested", code: "## Nested native heading\n\nNested native paragraph.\n\n```javascript\nconst nestedNative = 42;\n```\n\nNested native tail.", fence: "markdown" },
+  ];
+  for (const width of [1543, 390]) {
+    for (const fixture of fixtures) {
+      test(`${fixture.name} selection, clipboard, focus and output at ${width}px`, async ({ page }, testInfo) => {
+        await page.setViewportSize({ width, height: 900 });
+        await serveProductionAssets(page);
+        const markdown = `# Native constraints\n\n[Native tail](#native-tail)\n\nNATIVE_SELECTION_START\n\n\`\`\`\`${fixture.fence}\n${fixture.code}\n\`\`\`\`\n\nNATIVE_SELECTION_END\n\n${Array.from({ length: lineCount }, (_, index) => `Native spacer ${index}.\n`).join("\n")}\n## Native tail\n\nNATIVE_FIND_TAIL\n`;
+        await mockMarkdownViewerApi(page, { initialMarkdown: markdown, wordWrapEnabled: false });
+        await page.goto("/browse/smb/demo");
+        await page.getByRole("button", { name: "Later", exact: true }).click();
+        await (width < 600 ? page.getByRole("button", { name: `File: ${DEMO_PATH}`, exact: true }) : page.getByRole("button").filter({ hasText: /^note\.md$/ })).click();
+        const root = page.locator('[data-markdown-search-root="true"]');
+        const viewport = root.locator("..");
+        const code = root.locator("pre > code");
+        await expect(code).toHaveText(`${fixture.code}\n`);
+        const renderedText = await root.innerText();
+        await expect(viewport).toBeFocused();
+        await page.keyboard.press("Tab");
+        const link = root.getByRole("link", { name: "Native tail", exact: true });
+        await expect(link).toBeFocused();
+        const previewNode = await root.elementHandle();
+        const routeBefore = new URL(page.url());
+        await page.keyboard.press("Enter");
+        const target = root.getByRole("heading", { name: "Native tail", exact: true });
+        await expect(target).toHaveAttribute("id", `${MARKDOWN_HEADING_ID_PREFIX}native-tail`);
+        await expect(target).toBeInViewport();
+        expect(new URL(page.url()).pathname + new URL(page.url()).search).toBe(routeBefore.pathname + routeBefore.search);
+        expect(await root.evaluate((element, original) => element === original, previewNode)).toBe(true);
+        await previewNode?.dispose();
+        await viewport.focus();
+        await page.keyboard.press("Control+Home");
+        await page.keyboard.press("Control+a");
+        const selectAll = await page.evaluate(() => window.getSelection()?.toString() ?? "");
+        expect(selectAll).toContain("NATIVE_SELECTION_START");
+        expect(selectAll).toContain(fixture.code);
+        expect(selectAll).toContain("NATIVE_FIND_TAIL");
+        const selected = await root.evaluate(element => {
+          const paragraphs = [...element.querySelectorAll("p")];
+          const start = paragraphs.find(paragraph => paragraph.textContent === "NATIVE_SELECTION_START")!;
+          const end = paragraphs.find(paragraph => paragraph.textContent === "NATIVE_SELECTION_END")!;
+          const range = new Range();
+          range.setStart(start.firstChild!, 0);
+          range.setEnd(end.firstChild!, end.textContent!.length);
+          window.getSelection()?.removeAllRanges();
+          window.getSelection()?.addRange(range);
+          return window.getSelection()?.toString() ?? "";
+        });
+        expect(selected).toContain(fixture.code);
+        expect(selected.startsWith("NATIVE_SELECTION_START")).toBe(true);
+        expect(selected.endsWith("NATIVE_SELECTION_END")).toBe(true);
+        await page.keyboard.press("Control+c");
+        await viewport.evaluate(element => {
+          const target = document.createElement("textarea");
+          target.setAttribute("aria-label", "Native clipboard probe");
+          Object.assign(target.style, { position: "fixed", top: "0", left: "0", width: "1px", height: "1px" });
+          element.append(target);
+          target.focus({ preventScroll: true });
+        });
+        await page.keyboard.press("Control+v");
+        const clipboard = page.getByRole("textbox", { name: "Native clipboard probe", exact: true });
+        await expect(clipboard).toHaveValue(selected);
+        await clipboard.evaluate(element => element.remove());
+        await viewport.focus();
+        await page.keyboard.press("Control+Home");
+        await expect(root.getByRole("heading", { name: "Native constraints", exact: true })).toBeInViewport();
+        const find = await page.evaluate(() => {
+          window.getSelection()?.removeAllRanges();
+          return (window as Window & { find: (text: string) => boolean }).find("NATIVE_FIND_TAIL");
+        });
+        expect(find).toBe(true);
+        expect(await page.evaluate(() => window.getSelection()?.toString())).toBe("NATIVE_FIND_TAIL");
+        await page.evaluate(() => new Promise<void>(resolve => requestAnimationFrame(() => requestAnimationFrame(() => resolve()))));
+        const findReveal = await root.evaluate(element => {
+          const target = [...element.querySelectorAll("p")].find(paragraph => paragraph.textContent === "NATIVE_FIND_TAIL")!;
+          const bounds = target.getBoundingClientRect();
+          const viewport = element.parentElement!.getBoundingClientRect();
+          return { target: bounds.toJSON(), viewport: viewport.toJSON(), scrollTop: element.parentElement!.scrollTop, revealed: bounds.top >= viewport.top && bounds.bottom <= viewport.bottom };
+        });
+        await testInfo.attach("native-find-reveal.json", { body: JSON.stringify(findReveal, null, 2), contentType: "application/json" });
+        if (testInfo.project.name === "firefox") {
+          expect.soft(findReveal.revealed, "Firefox window.find must reveal the complete match inside the content viewport").toBe(true);
+          await expect.soft(root.getByText("NATIVE_FIND_TAIL", { exact: true })).toBeInViewport();
+        }
+        if (testInfo.project.name === "chromium") {
+          const screenState = () => root.evaluate(element => ({
+            text: element.textContent,
+            selection: window.getSelection()?.toString(),
+            top: element.parentElement!.scrollTop,
+            left: element.querySelector("pre")!.scrollLeft,
+          }));
+          const beforePrint = await screenState();
+          const pdf = await page.pdf({ printBackground: true });
+          await testInfo.attach(`native-${fixture.name}-${width}.pdf`, { body: pdf, contentType: "application/pdf" });
+          await expect.poll(screenState).toEqual(beforePrint);
+        }
+        await testInfo.attach("native-constraints.json", { body: JSON.stringify({ fixture: fixture.name, width, engine: testInfo.project.name, renderedText, selectAll, selected, headingTargetRevealed: true, findReveal, findRevealRequired: testInfo.project.name === "firefox", clipboard: "Trusted keyboard copy and paste into a temporary textarea; exact payload checked.", find: "window.find exact selection is required in both engines; reveal is required in Firefox and diagnostic-only in Chromium. Actual browser Find remains separate manual evidence.", print: testInfo.project.name === "chromium" ? "Real headless PDF attached; run scripts.check_native_markdown_pdf separately. PDF generation is not a print acceptance pass." : "Firefox print/PDF remains a manual gate." }, null, 2), contentType: "application/json" });
+      });
+    }
+  }
+});
+
+test.describe("production Markdown printing", () => {
+  test.skip(process.env.SAMBEE_E2E_PRODUCTION !== "1", "Requires the production build and approved demo route");
+  const lineCount = 120;
+  const fixtures = [
+    { name: "multiline", code: Array.from({ length: lineCount }, (_, index) => `const printLine${index} = ${index};`).join("\n"), fence: "javascript" },
+    { name: "long-line", code: `const printLongLine = "${"printable horizontal content ".repeat(240)}PRINT_LONG_END";`, fence: "javascript" },
+    { name: "nested", code: "## Printed nested heading\n\nNested printed paragraph.\n\n```javascript\nconst nestedPrint = 42;\n```\n\nNested printed tail.", fence: "markdown" },
+  ];
+  for (const width of [1543, 390]) {
+    for (const mode of ["light", "dark"] as const) {
+      for (const fixture of fixtures) {
+        test(`${fixture.name} ${mode} complete output and state at ${width}px`, async ({ page }, testInfo) => {
+          await page.setViewportSize({ width, height: 900 });
+          await serveProductionAssets(page);
+          const markdown = `# Printed document\n\nPRINT_DOCUMENT_START\n\n![Printed image](/icons/icon-180.png)\n\n\`\`\`\`${fixture.fence}\n${fixture.code}\n\`\`\`\`\n\n| Printed column | Printed value |\n| --- | --- |\n| PRINT_TABLE_START | ${"LongTableCell".repeat(30)} |\n| PRINT_TABLE_END | Complete table |\n\n${Array.from({ length: lineCount }, (_, index) => `Printed paragraph ${index}.\n`).join("\n")}\n## Printed tail\n\nPRINT_DOCUMENT_END\n`;
+          await mockMarkdownViewerApi(page, { initialMarkdown: markdown, themeId: () => `sambee-${mode}`, wordWrapEnabled: false });
+          await page.goto("/browse/smb/demo");
+          await page.getByRole("button", { name: "Later", exact: true }).click();
+          await (width < 600 ? page.getByRole("button", { name: `File: ${DEMO_PATH}`, exact: true }) : page.getByRole("button").filter({ hasText: /^note\.md$/ })).click();
+          const root = page.locator('[data-markdown-search-root="true"]');
+          await expect(root.getByRole("heading", { name: "Printed document", exact: true })).toBeVisible();
+          await expect(root.locator("pre > code")).toHaveText(`${fixture.code}\n`);
+          await expect.poll(() => root.getByRole("img", { name: "Printed image", exact: true }).evaluate(element => (element as HTMLImageElement).naturalWidth)).toBeGreaterThan(0);
+          await page.evaluate(() => document.fonts.ready);
+          await page.evaluate(() => {
+            Object.assign(window, { printCalls: 0 });
+            window.print = () => { (window as unknown as { printCalls: number }).printCalls += 1; };
+          });
+          const printButton = page.getByRole("button", { name: "Print", exact: true });
+          await expect(printButton).toHaveAttribute("title", "Print / Save as PDF");
+          await printButton.click();
+          expect(await page.evaluate(() => (window as unknown as { printCalls: number }).printCalls)).toBe(1);
+          const renderedText = await root.innerText();
+          await page.emulateMedia({ media: "print" });
+          await expect(root).toHaveCSS("color", "rgb(0, 0, 0)");
+          await expect(root).toHaveCSS("background-color", "rgb(255, 255, 255)");
+          await expect(root.locator("pre > code")).toHaveCSS("color", "rgb(0, 0, 0)");
+          await expect(root.locator("pre > code")).toHaveCSS("white-space", "pre-wrap");
+          await expect(root.locator("pre > code")).toHaveCSS("min-width", "0px");
+          await expect(root.locator("pre")).toHaveCSS("overflow", "visible");
+          await expect(printButton).not.toBeVisible();
+          expect(await root.locator("pre, table, img").evaluateAll(elements => elements.every(element => element.getBoundingClientRect().width <= element.closest('[data-markdown-search-root]')!.getBoundingClientRect().width))).toBe(true);
+          await page.emulateMedia({ media: null });
+          await root.getByText("PRINT_DOCUMENT_END", { exact: true }).scrollIntoViewIfNeeded();
+          const node = await root.elementHandle();
+          await root.locator("pre").evaluate(element => { element.scrollLeft = element.scrollWidth; });
+          await root.getByText("PRINT_DOCUMENT_END", { exact: true }).evaluate(element => {
+            const range = new Range();
+            range.selectNodeContents(element);
+            window.getSelection()?.removeAllRanges();
+            window.getSelection()?.addRange(range);
+          });
+          const screenState = () => root.evaluate(element => ({ text: element.textContent, selection: window.getSelection()?.toString(), top: element.parentElement!.scrollTop, left: element.querySelector("pre")!.scrollLeft, url: location.href }));
+          const beforePrint = await screenState();
+          expect(beforePrint.top).toBeGreaterThan(0);
+          if (testInfo.project.name === "chromium") {
+            const pdf = await page.pdf({ printBackground: false, format: "A4", margin: { top: "12mm", bottom: "12mm", left: "12mm", right: "12mm" } });
+            await testInfo.attach(`print-${fixture.name}-${mode}-${width}.pdf`, { body: pdf, contentType: "application/pdf" });
+          }
+          await expect.poll(screenState).toEqual(beforePrint);
+          expect(await root.evaluate((element, original) => element === original, node)).toBe(true);
+          await node?.dispose();
+          await testInfo.attach("markdown-print.json", { body: JSON.stringify({ fixture: fixture.name, width, mode, engine: testInfo.project.name, renderedText, requiresImages: true, scope: testInfo.project.name === "chromium" ? "Real browser PDF; inspect text and visual output separately." : "Print CSS and state restoration only; actual Firefox print output remains a manual check." }, null, 2), contentType: "application/json" });
+        });
+      }
+    }
+  }
+});
+
+test.describe("production syntax publication", () => {
+  const collectMemory = process.env.SAMBEE_E2E_MEMORY === "1";
+  const enforceBudgets = process.env.SAMBEE_E2E_BUDGETS === "1";
+  const diagnostic = collectMemory || process.env.SAMBEE_E2E_TRACE === "1";
+  test.skip(process.env.SAMBEE_E2E_PRODUCTION !== "1", "Requires the production build and approved demo route");
+  test.beforeAll(() => {
+    if (enforceBudgets && diagnostic) throw new Error("Timing budget acceptance must run without forced GC or diagnostic tracing.");
+  });
+  const fixtures = SYNTAX_PUBLICATION_FIXTURES;
+  const viewportRangeLimit = 4_000;
+
+  test("native viewer contracts retain semantic text, keyboard selection, links and print content", async ({ page }, testInfo) => {
+    const markdown = "# Viewer contract\n\nAlpha **bold** and *emphasis*.\n\n[External](https://example.org/contract) [Relative](child.md) [Hash](#tail) [Unsafe](javascript:alert(1))\n\n- [x] Complete\n- [ ] Pending\n\n| Name | Value |\n| --- | --- |\n| Alpha | beta |\n\n```javascript\nconst contract = 1;\nconsole.log(contract);\n```\n\n<script>globalThis.unsafePayload = true</script>\n\n## Tail\n\nOmega contract.\n";
+    await serveProductionAssets(page);
+    await mockMarkdownViewerApi(page, { initialMarkdown: markdown, existingFilePaths: [DEMO_PATH] });
+    await page.goto("/browse/smb/demo");
+    await page.getByRole("button", { name: "Later", exact: true }).click();
+    await page.getByRole("button").filter({ hasText: /^note\.md$/ }).click();
+    const root = page.locator('[data-markdown-search-root="true"]');
+    await expect(root.getByRole("heading", { name: "Viewer contract", exact: true })).toBeVisible();
+    await expect(root.getByRole("table")).toHaveCount(1);
+    await expect(root.getByRole("checkbox", { checked: true })).toBeDisabled();
+    await expect(root.getByRole("checkbox", { checked: false })).toBeDisabled();
+    await expect(root.locator("pre code")).toHaveText("const contract = 1;\nconsole.log(contract);\n");
+    await expect(root.getByRole("link", { name: "External", exact: true })).toHaveAttribute("href", "https://example.org/contract");
+    await expect(root.getByRole("link", { name: "Relative", exact: true })).toHaveAttribute("href", "http://localhost:3000/browse/smb/child.md");
+    const expectedHeadingId = "sambee-markdown-tail";
+    await expect(root.getByRole("heading", { name: "Tail", exact: true })).toHaveAttribute("id", expectedHeadingId);
+    await expect(root.getByRole("link", { name: "Hash", exact: true })).toHaveAttribute("href", `#${expectedHeadingId}`);
+    await expect(root.getByText("Unsafe", { exact: true })).not.toHaveAttribute("href");
+    await expect(root.locator("script")).toHaveCount(0);
+    expect(await page.evaluate(() => "unsafePayload" in globalThis)).toBe(false);
+    const viewport = root.locator("..");
+    await expect(viewport).toBeFocused();
+    await viewport.focus();
+    await page.keyboard.press("Tab");
+    await expect(root.getByRole("link", { name: "External", exact: true })).toBeFocused();
+    const text = await root.innerText();
+    await viewport.focus();
+    await page.keyboard.press("Control+a");
+    const selectAll = await page.evaluate(() => window.getSelection()?.toString() ?? "");
+    expect(selectAll).toContain("Viewer contract");
+    expect(selectAll).toContain("Omega contract.");
+    const selectedCode = await root.evaluate((element) => {
+      const range = document.createRange();
+      range.selectNodeContents(element.querySelector("pre code")!);
+      window.getSelection()?.removeAllRanges();
+      window.getSelection()?.addRange(range);
+      document.addEventListener("copy", () => { document.documentElement.dataset.contractCopy = window.getSelection()?.toString() ?? ""; }, { once: true });
+      return window.getSelection()?.toString() ?? "";
+    });
+    expect(selectedCode.trimEnd()).toBe("const contract = 1;\nconsole.log(contract);");
+    await page.keyboard.press("Control+c");
+    await expect.poll(() => page.evaluate(() => document.documentElement.dataset.contractCopy)).toBe(selectedCode);
+    const selectedNode = await root.locator("pre code").evaluateHandle((element) => element.firstChild);
+    await root.locator("pre code").evaluate((element) => (element as HTMLElement).style.setProperty("--sambee-syntax-keyword", "rgb(1, 2, 3)"));
+    await expect.poll(() => root.locator("pre code").evaluate((element) => {
+      const name = [...CSS.highlights.keys()].find((name) => /^markdown-(?:syntax|retained)-/.test(name) && name.endsWith("-keyword"));
+      return name ? getComputedStyle(element, `::highlight(${name})`).color : null;
+    })).toBe("rgb(1, 2, 3)");
+    expect(await root.locator("pre code").evaluate((element, node) => element.firstChild === node, selectedNode)).toBe(true);
+    expect(await page.evaluate(() => window.getSelection()?.toString())).toBe(selectedCode);
+    await selectedNode.dispose();
+    await root.locator("pre code").evaluate((element) => (element as HTMLElement).style.removeProperty("--sambee-syntax-keyword"));
+    await page.getByRole("button", { name: "Search", exact: true }).click();
+    const searchInput = page.getByPlaceholder("Search", { exact: true });
+    await searchInput.fill("contract");
+    await expect(page.getByText("1 / 4", { exact: true })).toBeVisible();
+    await searchInput.press("Enter");
+    await expect(page.getByText("2 / 4", { exact: true })).toBeVisible();
+    await expect(searchInput).toBeFocused();
+    const semantics = await root.ariaSnapshot();
+    expect(semantics).toContain('heading "Viewer contract" [level=1]');
+    expect(semantics).toContain('heading "Tail" [level=2]');
+    expect(semantics).toContain("table:");
+    if (testInfo.project.name === "chromium") {
+      await page.emulateMedia({ media: "print" });
+      try {
+        await expect(root.getByRole("heading", { name: "Tail", exact: true })).toBeVisible();
+        expect(await root.innerText()).toBe(text);
+        const pdf = await page.pdf();
+        expect(pdf.byteLength).toBeGreaterThan(1_000);
+        await testInfo.attach("viewer-contract.pdf", { body: pdf, contentType: "application/pdf" });
+      } finally {
+        await page.emulateMedia({ media: null });
+      }
+    }
+    await testInfo.attach("native-viewer-contracts.json", { body: JSON.stringify({ renderer: "react-markdown", text, selectAll, selectedCode, semantics, clipboardScope: "Trusted native copy event and exact selected text; OS clipboard payload and assistive-technology behavior remain manual gates." }, null, 2), contentType: "application/json" });
+    await page.getByRole("button", { name: "Close", exact: true }).click();
+    await expect(root).toHaveCount(0);
+  });
+
+  for (const width of [1543, 390]) {
+    for (const fixture of fixtures) {
+      test(`${fixture.name} at ${width}px preserves active search and selection`, async ({ page }, testInfo) => {
+        test.setTimeout(90_000);
+        const phases: { name: string; startTime: number; duration: number }[] = [];
+        const phase = async (name: string, action: () => Promise<unknown>) => {
+          const startTime = await page.evaluate(() => performance.now());
+          await action();
+          const endTime = await page.evaluate(() => new Promise<number>((done) => requestAnimationFrame(() => requestAnimationFrame(() => done(performance.now())))));
+          phases.push({ name, startTime, duration: endTime - startTime });
+        };
+        await page.setViewportSize({ width, height: 900 });
+        await serveProductionAssets(page);
+        await page.addInitScript(({ expectedBlocks, expectedMatches, filename }) => {
+          const OriginalWorker = window.Worker;
+          const pending: (() => void)[] = [];
+          let held = true;
+          let liveWorkers = 0;
+          const longTasks: { startTime: number; duration: number }[] = [];
+          const taskGaps: { startTime: number; duration: number }[] = [];
+          const searchStages: { name: string; startTime: number; duration: number }[] = [];
+          const syntaxStages: { name: string; startTime: number; duration: number }[] = [];
+          const preparationStages: { name: string; startTime: number; duration: number }[] = [];
+          const workerStages: { name: string; block: number; startTime: number; duration: number }[] = [];
+          const navigationFrames: { action: string; startTime: number; duration: number; firstFrameMs: number }[] = [];
+          const renderMilestones: { name: string; time: number }[] = [];
+          const timingSamples: ViewerTimingSamples = {};
+          let openedAt: number | undefined;
+          let navigationClicks = 0;
+          const measureExactResult = (metric: "firstExactSearch" | "changedQuery" | "lastMatchNavigation", query: string, ordinal: number) => {
+            const started = performance.now();
+            const inspect = () => {
+              const next = document.querySelector('button[aria-label="Next match"]');
+              const count = next?.parentElement?.textContent?.replace(/\s/g, "") ?? "";
+              const current = [...CSS.highlights.entries()].find(([name]) => name.startsWith("markdown-search-") && name.endsWith("-current"));
+              const active = current ? [...current[1]][0] as Range | undefined : undefined;
+              if (count.includes(`${ordinal}/${expectedMatches}`) && active?.toString() === query) {
+                requestAnimationFrame(() => requestAnimationFrame(() => {
+                  timingSamples[metric] = performance.now() - started;
+                }));
+              } else requestAnimationFrame(inspect);
+            };
+            requestAnimationFrame(inspect);
+          };
+          new PerformanceObserver((entries) => {
+            for (const entry of entries.getEntries()) {
+              const resource = entry as PerformanceResourceTiming;
+              if (/\/api\/viewer\/[^/]+\/file$/.test(new URL(resource.name).pathname)) {
+                renderMilestones.push({ name: "source-response-end", time: resource.responseEnd });
+              }
+            }
+          }).observe({ type: "resource", buffered: true });
+          const initialCommit = new MutationObserver(() => {
+            const root = document.querySelector('[data-markdown-search-root="true"]');
+            if (root?.querySelectorAll("pre > code").length !== expectedBlocks) return;
+            initialCommit.disconnect();
+            renderMilestones.push({ name: "dom-commit-observed", time: performance.now() });
+            requestAnimationFrame(() => {
+              renderMilestones.push({ name: "first-frame", time: performance.now() });
+              requestAnimationFrame(() => {
+                const completed = performance.now();
+                renderMilestones.push({ name: "second-frame", time: completed });
+                if (openedAt !== undefined) timingSamples.documentCompletion = completed - openedAt;
+              });
+            });
+          });
+          initialCommit.observe(document, { childList: true, subtree: true });
+          const keyboardFrames: { event: string; startTime: number; duration: number; firstFrameMs: number; eventAgeMs: number; value: string }[] = [];
+          new PerformanceObserver((entries) => {
+            for (const entry of entries.getEntries()) {
+              if (entry.name.startsWith("sambee:preview-search:")) searchStages.push({ name: entry.name, startTime: entry.startTime, duration: entry.duration });
+              if (entry.name.startsWith("sambee:preview-syntax:")) syntaxStages.push({ name: entry.name, startTime: entry.startTime, duration: entry.duration });
+              if (entry.name.startsWith("sambee:preview-preparation:")) preparationStages.push({ name: entry.name, startTime: entry.startTime, duration: entry.duration });
+            }
+          }).observe({ type: "measure", buffered: true });
+          document.addEventListener("click", (event) => {
+            const button = event.target instanceof Element ? event.target.closest("button") : null;
+            const action = button?.getAttribute("aria-label");
+            if (openedAt === undefined && (action === `File: ${filename}` || button?.textContent?.trim() === filename)) openedAt = performance.now();
+            if (action !== "Next match" && action !== "Previous match") return;
+            navigationClicks += 1;
+            if (navigationClicks === 3) measureExactResult("lastMatchNavigation", "let x", expectedMatches);
+            const startTime = performance.now();
+            requestAnimationFrame(() => {
+              const firstFrameMs = performance.now() - startTime;
+              requestAnimationFrame(() => navigationFrames.push({ action, startTime, firstFrameMs, duration: performance.now() - startTime }));
+            });
+          }, true);
+          for (const eventName of ["keydown", "input"]) {
+            document.addEventListener(eventName, (event) => {
+              const target = event.target;
+              if (!(target instanceof HTMLInputElement) || target.placeholder !== "Search") return;
+              const startTime = performance.now();
+              const eventAgeMs = Math.max(0, startTime - event.timeStamp);
+              const value = target.value;
+              if (eventName === "input" && value === "l") measureExactResult("firstExactSearch", value, 1);
+              if (eventName === "input" && value === "x=1") measureExactResult("changedQuery", value, 1);
+              requestAnimationFrame(() => {
+                const firstFrameMs = performance.now() - startTime;
+                requestAnimationFrame(() => keyboardFrames.push({ event: eventName, startTime, firstFrameMs, eventAgeMs, duration: performance.now() - startTime, value }));
+              });
+            }, true);
+          }
+          const longTasksSupported = PerformanceObserver.supportedEntryTypes.includes("longtask");
+          if (longTasksSupported) {
+            new PerformanceObserver((entries) => {
+              for (const entry of entries.getEntries()) longTasks.push({ startTime: entry.startTime, duration: entry.duration });
+            }).observe({ type: "longtask", buffered: true });
+          }
+          let lastTask = performance.now();
+          setInterval(() => {
+            const now = performance.now();
+            taskGaps.push({ startTime: lastTask, duration: now - lastTask });
+            lastTask = now;
+          }, 10);
+          let heldNormalization = false;
+          const pendingNormalization: (() => void)[] = [];
+          Object.assign(window, {
+            syntaxResources: () => ({ liveWorkers, heldMessages: pending.length, heldNormalizationMessages: pendingNormalization.length }),
+            holdNormalization: () => { heldNormalization = true; },
+            releaseNormalization: () => { heldNormalization = false; for (const send of pendingNormalization.splice(0)) send(); },
+            syntaxResponsiveness: () => {
+              const viewerGaps = taskGaps.filter((gap) => openedAt !== undefined && gap.startTime + gap.duration >= openedAt);
+              return { longTasksSupported, longTasks, taskGaps: viewerGaps, searchStages, syntaxStages, preparationStages, workerStages, navigationFrames, renderMilestones, keyboardFrames, timingSamples: { ...timingSamples, maximumTimerGap: viewerGaps.length ? Math.max(...viewerGaps.map((gap) => gap.duration)) : null } };
+            },
+            holdSyntax: () => { held = true; },
+            releaseSyntax: () => {
+              held = false;
+              for (const send of pending.splice(0)) send();
+            },
+          });
+          window.Worker = class extends OriginalWorker {
+            private disposed = false;
+            private syntaxWorker: boolean;
+            private blocks = new Map<number, { source: number; final?: number; firstResult?: number }>();
+            constructor(url: string | URL, options?: WorkerOptions) {
+              super(url, options);
+              this.syntaxWorker = String(url).includes("markdownSyntax.worker");
+              liveWorkers += 1;
+              this.addEventListener("message", (event) => {
+                const response = event.data as { type?: string; block?: number };
+                if (response.block === undefined) return;
+                const block = this.blocks.get(response.block);
+                if (!block) return;
+                const now = performance.now();
+                if ((response.type === "ranges" || response.type === "complete") && block.firstResult === undefined) {
+                  block.firstResult = now;
+                  workerStages.push({ name: "final-source-to-first-result", block: response.block, startTime: block.final ?? block.source, duration: now - (block.final ?? block.source) });
+                }
+                if (response.type === "complete") {
+                  workerStages.push({ name: "source-to-complete", block: response.block, startTime: block.source, duration: now - block.source });
+                  this.blocks.delete(response.block);
+                }
+              });
+            }
+            terminate() {
+              if (!this.disposed) liveWorkers -= 1;
+              this.disposed = true;
+              super.terminate();
+            }
+            postMessage(message: unknown, options?: StructuredSerializeOptions) {
+              const kind = message as { type?: string };
+              const send = () => {
+                if (this.disposed) return;
+                const request = message as { type?: string; block?: number; final?: boolean };
+                if (this.syntaxWorker && request.type === "source" && request.block !== undefined) {
+                  const block = this.blocks.get(request.block) ?? { source: performance.now() };
+                  if (request.final) block.final = performance.now();
+                  this.blocks.set(request.block, block);
+                }
+                super.postMessage(message, options);
+              };
+              if (held && this.syntaxWorker && kind.type === "source") pending.push(send);
+              else if (heldNormalization && !this.syntaxWorker && kind.type === "source") pendingNormalization.push(send);
+              else send();
+            }
+          };
+        }, { expectedBlocks: fixture.blocks, expectedMatches: fixture.lines * fixture.blocks, filename: DEMO_PATH });
+        const text = fixture.name === "long-line" ? `${"let x=1; ".repeat(fixture.lines)}\n` : "let x=1;\n".repeat(fixture.lines);
+        const markdown = Array.from({ length: fixture.blocks }, () => `\`\`\`js\n${text}\`\`\``).join("\n\n");
+        await mockMarkdownViewerApi(page, { initialMarkdown: markdown });
+        const started = Date.now();
+        await page.goto("/browse/smb/demo");
+        await page.getByRole("button", { name: "Later", exact: true }).click();
+        const heapSession = testInfo.project.name === "chromium" ? await page.context().newCDPSession(page) : null;
+        await heapSession?.send("Performance.enable");
+        if (collectMemory) await heapSession?.send("HeapProfiler.collectGarbage");
+        const sampleHeap = async () => heapSession ? await heapSession.send("Runtime.getHeapUsage") : null;
+        const sampleBrowserMetrics = async () => heapSession ? (await heapSession.send("Performance.getMetrics")).metrics.filter((metric) => ["LayoutDuration", "RecalcStyleDuration", "ScriptDuration", "Nodes"].includes(metric.name)) : null;
+        const browserMetrics = { beforeOpen: await sampleBrowserMetrics(), afterInitialRender: null as Awaited<ReturnType<typeof sampleBrowserMetrics>>, afterComplete: null as Awaited<ReturnType<typeof sampleBrowserMetrics>> };
+        const memory = { scope: "Chromium renderer heap only; excludes worker heaps and aggregate native/DOM memory. Firefox unsupported. GC runs are separate from responsiveness trials.", controlledGC: collectMemory, browserMetrics, documentStats: null as { elements: number; textNodes: number } | null, beforeOpen: await sampleHeap(), afterComplete: null as Awaited<ReturnType<typeof sampleHeap>>, afterClose: null as Awaited<ReturnType<typeof sampleHeap>>, afterCompleteGC: null as Awaited<ReturnType<typeof sampleHeap>>, afterCloseGC: null as Awaited<ReturnType<typeof sampleHeap>> };
+        const root = page.locator('[data-markdown-search-root="true"]');
+        await captureViewerScheduling(page, testInfo, async () => {
+        await phase("initial-render-through-two-frames", async () => {
+          await (width < 600
+            ? page.getByRole("button", { name: `File: ${DEMO_PATH}`, exact: true })
+            : page.getByRole("button").filter({ hasText: /^note\.md$/ })).click();
+          await expect(root.locator("pre > code")).toHaveCount(fixture.blocks);
+        });
+        const openMs = Date.now() - started;
+        browserMetrics.afterInitialRender = await sampleBrowserMetrics();
+        await page.getByRole("button", { name: "Search", exact: true }).click();
+        const searchControls = page.getByRole("button", { name: "Next match", exact: true }).locator("..");
+        const searchStarted = Date.now();
+        await phase("first-search-keyboard", async () => {
+          await page.getByPlaceholder("Search", { exact: true }).pressSequentially("l");
+          await expect.poll(() => page.evaluate(() => (window as unknown as { syntaxResponsiveness: () => { timingSamples: ViewerTimingSamples } }).syntaxResponsiveness().timingSamples.firstExactSearch)).toBeGreaterThanOrEqual(0);
+          await page.getByPlaceholder("Search", { exact: true }).pressSequentially("et x");
+          await expect(searchControls.getByText(`1 / ${fixture.lines * fixture.blocks}`, { exact: true })).toBeVisible();
+          await expect.poll(() => page.evaluate(() => {
+            const current = [...CSS.highlights.entries()].find(([name]) => name.startsWith("markdown-search-") && name.endsWith("-current"));
+            return current ? [...current[1]][0]?.toString() : null;
+          })).toBe("let x");
+        });
+        const searchMs = Date.now() - searchStarted;
+        const before = await root.evaluate((element) => {
+          const code = element.querySelector("code")!;
+          const node = document.createTreeWalker(code, NodeFilter.SHOW_TEXT).nextNode()!;
+          const range = document.createRange();
+          range.selectNodeContents(node);
+          const selection = window.getSelection()!;
+          selection.removeAllRanges();
+          selection.addRange(range);
+          Object.assign(window, { selectedSyntaxNode: node });
+          return { selected: selection.toString(), text: element.textContent };
+        });
+        const publicationStarted = Date.now();
+        await phase("syntax-release-with-active-search", async () => {
+          await page.evaluate(() => (window as unknown as { releaseSyntax: () => void }).releaseSyntax());
+          await expect.poll(() => page.evaluate(() => [...CSS.highlights.entries()].filter(([name]) => /^markdown-(?:syntax|retained)-/.test(name)).reduce((count, [, ranges]) => count + ranges.size, 0))).toBeGreaterThan(0);
+        });
+        const publicationMs = Date.now() - publicationStarted;
+        const after = await root.evaluate((element) => ({
+          text: element.textContent,
+          selected: window.getSelection()!.toString(),
+          retainedNode: element.contains((window as unknown as { selectedSyntaxNode: Node }).selectedSyntaxNode),
+          ranges: [...CSS.highlights.entries()].filter(([name]) => /^markdown-(?:syntax|retained)-/.test(name)).reduce((count, [, ranges]) => count + ranges.size, 0),
+          tokenSpans: element.querySelectorAll('[class*="sambee-syntax-"]').length,
+          searchColors: [...CSS.highlights.keys()].filter((name) => name.startsWith("markdown-search-")).map((name) => ({
+            name,
+            background: getComputedStyle(element.querySelector("code")!, `::highlight(${name})`).backgroundColor,
+          })),
+        }));
+        expect(after.text).toBe(before.text);
+        expect(after.selected).toBe(before.selected);
+        expect(after.retainedNode).toBe(true);
+        expect(after.ranges).toBeLessThanOrEqual(viewportRangeLimit);
+        expect(after.tokenSpans).toBe(0);
+        expect(after.searchColors).toHaveLength(2);
+        expect(new Set(after.searchColors.map((entry) => entry.background)).size).toBe(2);
+        expect(after.searchColors.every((entry) => entry.background && entry.background !== "rgba(0, 0, 0, 0)")).toBe(true);
+        await expect(root.locator("mark")).toHaveCount(0);
+        await expect.poll(() => page.evaluate(() => [...CSS.highlights.entries()].filter(([name]) => name.startsWith("markdown-search-") && name.endsWith("-other")).reduce((count, [, ranges]) => count + ranges.size, 0))).toBeGreaterThan(0);
+        expect(await page.evaluate(() => [...CSS.highlights.entries()].filter(([name]) => name.startsWith("markdown-search-")).reduce((count, [, ranges]) => count + ranges.size, 0))).toBeLessThanOrEqual(1_001);
+        await expect(searchControls.getByText(`1 / ${fixture.lines * fixture.blocks}`, { exact: true })).toBeVisible();
+        await page.evaluate(() => window.getSelection()?.removeAllRanges());
+        await phase("next-match", async () => {
+          await page.getByRole("button", { name: "Next match", exact: true }).click();
+          await expect(searchControls.getByText(`2 / ${fixture.lines * fixture.blocks}`, { exact: true })).toBeVisible();
+        });
+        await phase("previous-match", async () => {
+          await page.getByRole("button", { name: "Previous match", exact: true }).click();
+          await expect(searchControls.getByText(`1 / ${fixture.lines * fixture.blocks}`, { exact: true })).toBeVisible();
+        });
+        await phase("last-match-wrap", async () => {
+          await page.getByRole("button", { name: "Previous match", exact: true }).click();
+          await expect(searchControls.getByText(`${fixture.lines * fixture.blocks} / ${fixture.lines * fixture.blocks}`, { exact: true })).toBeVisible();
+          const destination = await root.evaluate((element) => {
+            const entry = [...CSS.highlights.entries()].find(([name]) => name.startsWith("markdown-search-") && name.endsWith("-current"));
+            const range = entry ? [...entry[1]][0] as Range : null;
+            const rect = range?.getBoundingClientRect();
+            const viewport = element.parentElement!.getBoundingClientRect();
+            return { text: range?.toString(), visible: !!rect && rect.bottom >= viewport.top && rect.top <= viewport.bottom && rect.right >= viewport.left && rect.left <= viewport.right };
+          });
+          expect(destination).toEqual({ text: "let x", visible: true });
+        });
+        await expect.poll(() => page.evaluate(() => (window as unknown as { syntaxResponsiveness: () => { timingSamples: ViewerTimingSamples } }).syntaxResponsiveness().timingSamples.lastMatchNavigation)).toBeGreaterThanOrEqual(0);
+        if (fixture.name === "long-line") {
+          await expect.poll(() => page.evaluate(() => {
+            const current = [...CSS.highlights.entries()].find(([name]) => name.startsWith("markdown-search-") && name.endsWith("-current"));
+            const active = current ? [...current[1]][0] as Range : null;
+            if (!active) return false;
+            return [...CSS.highlights.entries()].filter(([name]) => /^markdown-(?:syntax|retained)-/.test(name)).some(([, ranges]) => [...ranges].some((entry) => {
+              const range = entry as Range;
+                    return range.startContainer === active.startContainer && range.startOffset <= active.startOffset && range.endOffset > active.startOffset;
+            }));
+          })).toBe(true);
+          expect(await page.evaluate(() => [...CSS.highlights.entries()].filter(([name]) => /^markdown-(?:syntax|retained)-/.test(name)).reduce((total, [, ranges]) => total + ranges.size, 0))).toBeLessThan(500);
+        }
+        await phase("scroll-with-active-search", async () => {
+          await root.evaluate((element) => {
+            const viewport = element.parentElement!;
+            viewport.scrollTop = Math.max(0, viewport.scrollTop - viewport.clientHeight);
+          });
+          await expect(page.getByPlaceholder("Search", { exact: true })).toBeVisible();
+          if (fixture.name === "many-blocks") {
+            const scrolling = await root.evaluate(async (element) => {
+              const viewport = element.parentElement!;
+              const initialScroll = viewport.scrollTop;
+              const frame = () => new Promise<void>((resolve) => requestAnimationFrame(() => resolve()));
+              const visible = (pattern: RegExp) => [...CSS.highlights.entries()]
+                .filter(([name]) => pattern.test(name))
+                .some(([, ranges]) => [...ranges].some((entry) => {
+                  const rect = (entry as Range).getBoundingClientRect();
+                  const bounds = viewport.getBoundingClientRect();
+                  return rect.bottom > bounds.top && rect.top < bounds.bottom;
+                }));
+              const painted = () => visible(/^markdown-(?:syntax|retained)-/) && visible(/^markdown-search-.*-other$/);
+              let ready = painted();
+              for (let attempt = 0; !ready && attempt < 10; attempt += 1) {
+                await frame();
+                ready = painted();
+              }
+              let searchFrames = 0;
+              let syntaxFrames = 0;
+              for (let index = 0; index < 60; index += 1) {
+                viewport.scrollTop = initialScroll + (index % 2) * 8;
+                await frame();
+                if (visible(/^markdown-search-.*-other$/)) searchFrames += 1;
+                if (visible(/^markdown-(?:syntax|retained)-/)) syntaxFrames += 1;
+              }
+              return { ready, searchFrames, syntaxFrames };
+            });
+            await testInfo.attach("continuous-scroll", { body: JSON.stringify({ renderer: "react-markdown", ...scrolling }), contentType: "application/json" });
+            expect(scrolling.ready).toBe(true);
+            expect(scrolling.searchFrames).toBe(60);
+            expect(scrolling.syntaxFrames).toBe(60);
+          }
+        });
+        await phase("changed-query", async () => {
+          await page.getByPlaceholder("Search", { exact: true }).fill("x=1");
+          await expect(searchControls.getByText(`1 / ${fixture.lines * fixture.blocks}`, { exact: true })).toBeVisible();
+          expect(await root.evaluate((element) => element.contains((window as unknown as { selectedSyntaxNode: Node }).selectedSyntaxNode))).toBe(true);
+        });
+        await expect.poll(() => page.evaluate(() => (window as unknown as { syntaxResponsiveness: () => { timingSamples: ViewerTimingSamples } }).syntaxResponsiveness().timingSamples.changedQuery)).toBeGreaterThanOrEqual(0);
+        await phase("clear-query", async () => {
+          await page.getByPlaceholder("Search", { exact: true }).fill("");
+          await expect(root.locator("mark")).toHaveCount(0);
+          expect(await page.evaluate(() => [...CSS.highlights.keys()].filter((name) => name.startsWith("markdown-search-")).length)).toBe(0);
+        });
+        const responsiveness = await page.evaluate(() => (window as unknown as { syntaxResponsiveness: () => {
+          timingSamples: ViewerTimingSamples;
+          taskGaps: { startTime: number; duration: number }[];
+          longTasksSupported: boolean;
+          longTasks: { startTime: number; duration: number }[];
+          searchStages: { name: string; startTime: number; duration: number }[];
+          syntaxStages: { name: string; startTime: number; duration: number }[];
+                  preparationStages: { name: string; startTime: number; duration: number }[];
+          workerStages: { name: string; startTime: number; duration: number }[];
+          navigationFrames: { action: string; startTime: number; duration: number; firstFrameMs: number }[];
+          renderMilestones: { name: string; time: number }[];
+          keyboardFrames: { event: string; startTime: number; duration: number; firstFrameMs: number; eventAgeMs: number; value: string }[];
+        } }).syntaxResponsiveness());
+        const budgetReport = evaluateViewerTimingBudgets(responsiveness.timingSamples, diagnostic);
+        Object.assign(responsiveness, { measurementVersion: "scoped-controls-v2", traceRequested: process.env.SAMBEE_E2E_TRACE === "1", traceSupported: testInfo.project.name === "chromium" });
+        for (const stage of ["capture", "matching", "presentation", "clear", "navigation-lookup", "navigation-publication", "navigation-geometry", "navigation-scroll"]) {
+          expect(responsiveness.searchStages.some((entry) => entry.name === `sambee:preview-search:${stage}`)).toBe(true);
+        }
+        for (const stage of ["task", "viewport-geometry", "block-geometry", "mapping", "offset-geometry", "ranges", "publication"]) {
+          expect(responsiveness.syntaxStages.some((entry) => entry.name === `sambee:preview-syntax:${stage}`)).toBe(true);
+        }
+        for (const stage of [
+          "decode-elapsed",
+          "load-normalization-elapsed",
+          "collection-walk", "render-prepared-tree", "render-transform", "hast-ready-to-layout-effect",
+        ]) {
+          expect(responsiveness.preparationStages.some((entry) => entry.name === `sambee:preview-preparation:${stage}`)).toBe(true);
+        }
+        expect(responsiveness.preparationStages.some((entry) => entry.name === "sambee:preview-preparation:collection-parse")).toBe(false);
+        expect(responsiveness.preparationStages.some((entry) => entry.name === "sambee:preview-preparation:render-parse")).toBe(false);
+        expect(responsiveness.workerStages.filter((entry) => entry.name === "source-to-complete")).toHaveLength(fixture.blocks);
+        expect(responsiveness.navigationFrames).toHaveLength(3);
+        for (const milestone of ["source-response-end", "dom-commit-observed", "first-frame", "second-frame"]) {
+          expect(responsiveness.renderMilestones.filter((entry) => entry.name === milestone)).toHaveLength(1);
+        }
+        expect(responsiveness.searchStages.filter((entry) => entry.name === "sambee:preview-search:capture")).toHaveLength(1);
+        expect(responsiveness.searchStages.some((entry) => entry.name.endsWith(":markers") || entry.name.endsWith(":slices"))).toBe(false);
+        expect(responsiveness.keyboardFrames.some((entry) => entry.event === "keydown")).toBe(true);
+        expect(responsiveness.keyboardFrames.some((entry) => entry.event === "input" && entry.value === "let x")).toBe(true);
+        for (const entry of [...responsiveness.keyboardFrames, ...responsiveness.navigationFrames]) {
+          expect(Number.isFinite(entry.firstFrameMs) && entry.firstFrameMs >= 0 && entry.firstFrameMs <= entry.duration).toBe(true);
+        }
+        expect(responsiveness.keyboardFrames.every((entry) => Number.isFinite(entry.eventAgeMs) && entry.eventAgeMs >= 0)).toBe(true);
+        memory.documentStats = await root.evaluate((element) => {
+          const walker = document.createTreeWalker(element, NodeFilter.SHOW_TEXT);
+          let textNodes = 0;
+          while (walker.nextNode()) textNodes += 1;
+          return { elements: element.querySelectorAll("*").length, textNodes };
+        });
+        browserMetrics.afterComplete = await sampleBrowserMetrics();
+        memory.afterComplete = await sampleHeap();
+        await page.evaluate(() => Reflect.deleteProperty(window, "selectedSyntaxNode"));
+        if (collectMemory) {
+          await heapSession?.send("HeapProfiler.collectGarbage");
+          memory.afterCompleteGC = await sampleHeap();
+        }
+        await page.getByRole("button", { name: "Close", exact: true }).click();
+        await expect(root).toHaveCount(0);
+        await expect.poll(() => page.evaluate(() => [...CSS.highlights.keys()].filter((name) => /^markdown-(?:syntax|retained)-/.test(name)).length)).toBe(0);
+        expect(await page.evaluate(() => [...CSS.highlights.keys()].filter((name) => name.startsWith("markdown-search-")).length)).toBe(0);
+        await expect.poll(() => page.evaluate(() => (window as unknown as { syntaxResources: () => { liveWorkers: number } }).syntaxResources().liveWorkers)).toBe(0);
+        memory.afterClose = await sampleHeap();
+        if (collectMemory) {
+          await heapSession?.send("HeapProfiler.collectGarbage");
+          memory.afterCloseGC = await sampleHeap();
+        }
+        await heapSession?.detach();
+        await page.evaluate(() => (window as unknown as { holdNormalization: () => void }).holdNormalization());
+        await (width < 600
+          ? page.getByRole("button", { name: `File: ${DEMO_PATH}`, exact: true })
+          : page.getByRole("button").filter({ hasText: /^note\.md$/ })).click();
+        await expect.poll(() => page.evaluate(() => (window as unknown as { syntaxResources: () => { heldNormalizationMessages: number } }).syntaxResources().heldNormalizationMessages)).toBeGreaterThan(0);
+        await page.getByRole("button", { name: "Close", exact: true }).click();
+        await expect.poll(() => page.evaluate(() => (window as unknown as { syntaxResources: () => { liveWorkers: number } }).syntaxResources().liveWorkers)).toBe(0);
+        await page.evaluate(() => (window as unknown as { releaseNormalization: () => void }).releaseNormalization());
+        await expect(root).toHaveCount(0);
+        await page.evaluate(() => (window as unknown as { holdSyntax: () => void }).holdSyntax());
+        await (width < 600
+          ? page.getByRole("button", { name: `File: ${DEMO_PATH}`, exact: true })
+          : page.getByRole("button").filter({ hasText: /^note\.md$/ })).click();
+        await expect.poll(() => page.evaluate(() => (window as unknown as { syntaxResources: () => { heldMessages: number } }).syntaxResources().heldMessages)).toBeGreaterThan(0);
+        await page.getByRole("button", { name: "Close", exact: true }).click();
+        await expect.poll(() => page.evaluate(() => (window as unknown as { syntaxResources: () => { liveWorkers: number } }).syntaxResources().liveWorkers)).toBe(0);
+        await page.evaluate(() => (window as unknown as { releaseSyntax: () => void }).releaseSyntax());
+        await expect(root).toHaveCount(0);
+        expect(await page.evaluate(() => [...CSS.highlights.keys()].filter((name) => /^markdown-(?:syntax|retained)-/.test(name)).length)).toBe(0);
+        await testInfo.attach("publication-measurements", { body: JSON.stringify({ renderer: "react-markdown", fixture: fixture.name, width, openMs, searchMs, publicationMs, mountedRanges: after.ranges, phases, responsiveness, memory, timingScope: "Real viewer with production-built assets. Phases include Playwright synchronization and two frames. Search/syntax stages measure synchronous calls: geometry may force layout; publication does not include deferred paint. Load-normalization-elapsed includes worker startup, transfer, parsing, acknowledgements and scheduling, not main-thread CPU time. Collection reuses the render tree and is included in render-transform time. Decode is asynchronous elapsed time. HAST-ready-to-layout-effect includes element construction, reconciliation, commit and scheduling, not isolated React CPU. Keyboard/navigation samples measure event-handler entry through two frames, not hardware input-to-visible-paint latency. Syntax worker round trips start after intentional holds and include transfer, scheduling, grammar loading and result acknowledgements, not isolated parser CPU.", }), contentType: "application/json", });
+        await testInfo.attach("viewer-timing-budgets.json", { body: JSON.stringify({ renderer: "react-markdown", fixture: fixture.name, width, engine: testInfo.project.name, trial: testInfo.repeatEachIndex, enforced: enforceBudgets, measurementVersion: "browser-action-boundaries-v1", scope: "Text load from file click through two frames; first exact query from its first input event, and warm query/navigation from their input/click events through exact count/highlight readiness and two frames. Timer gaps cover the viewer window, not hardware latency or CPU attribution. Syntax is deliberately held for the existing active-search test; load completion excludes syntax preparation. This subset is not full rollout acceptance.", ...budgetReport }, null, 2), contentType: "application/json" });
+        expect(budgetReport.metrics.filter((metric) => metric.status === "invalid"), "Required timing measurements must be present and valid").toEqual([]);
+        if (enforceBudgets) expect(budgetReport.status, JSON.stringify(budgetReport.metrics.filter((metric) => metric.status !== "pass"))).toBe("pass");
+        });
+      });
+    }
+  }
+});
+
 test("edit sessions can reopen immediately after release", async ({ page }) => {
   await mockMarkdownViewerApi(page, { initialMarkdown: "Immediate re-entry\n" });
   await openMarkdownViewer(page);
@@ -276,7 +2361,7 @@ test("edit sessions can reopen immediately after release", async ({ page }) => {
     await second.session.release();
   }, { connectionId: DEMO_CONNECTION_ID, path: DEMO_PATH });
 
-  await expect.poll(() => page.evaluate(() => Object.keys(sessionStorage).filter(key => key.startsWith("sambee:edit-lock:")))).toEqual([]);
+  await expect.poll(() => page.evaluate(() => Object.keys(sessionStorage).filter((key) => key.startsWith("sambee:edit-lock:")))).toEqual([]);
 });
 
 for (const reloadKind of ["browser", "update"] as const) {
@@ -327,7 +2412,7 @@ for (const reloadKind of ["browser", "update"] as const) {
     await expect(page.getByText(/Unable to enter edit mode/)).toHaveCount(0);
     await page.getByRole("button", { name: "Close", exact: true }).click();
     await expect(page).not.toHaveURL(/mode=edit/);
-    await expect.poll(() => page.evaluate(() => Object.keys(sessionStorage).filter(key => key.startsWith("sambee:edit-lock:")))).toEqual([]);
+    await expect.poll(() => page.evaluate(() => Object.keys(sessionStorage).filter((key) => key.startsWith("sambee:edit-lock:")))).toEqual([]);
   });
 }
 
@@ -604,7 +2689,7 @@ test(`${layout} upload resolves a conflict before publishing the next file`, asy
       if (path === "first.txt" && policy === "ask") {
         await fulfillJson(route, { detail: "Destination already exists" }, 409);
       } else {
-        await fulfillJson(route, { status: "completed", replaced: policy === "replace", effects: { source: "unchanged", destination: "mutated" } });
+        await fulfillJson(route, { status: "completed", replaced: policy === "replace", effects: { source: "unchanged", destination: "mutated" }, });
       }
     },
   });
@@ -668,6 +2753,990 @@ async function enterMarkdownEditMode(page: Page): Promise<void> {
   await page.getByRole("textbox", { name: "Markdown editor" }).waitFor();
 }
 
+interface SourceResponsivenessProbe {
+  measures: { name: string; startTime: number; duration: number; detail: Record<string, unknown> }[];
+  jobs: { url: string; ranges: number; rangeBatches: number; changeChunks: number; changeUnits: number; maximumChunkUnits: number; terminated: boolean }[];
+  timerGaps: number[];
+  completionMs: number | null;
+  stop: () => void;
+}
+
+interface SourceTypingProbe {
+  inputs: { key: string; trusted: boolean; at: number; firstFrameMs: number | null; twoFrameMs: number | null }[];
+  measures: { name: string; startTime: number; duration: number; detail: { revision?: number; documentUnits: number } }[];
+  gaps: number[];
+  longTasks: { startTime: number; duration: number }[];
+  longTasksSupported: boolean;
+  stop: () => void;
+}
+
+for (const width of [1543, 390]) {
+  test(`production progressive Markdown loading cancellation at ${width}px`, async ({ browser }, testInfo) => {
+    test.skip(process.env.SAMBEE_E2E_PRODUCTION !== "1", "Requires the normal production build");
+    const source = Array.from({ length: PROSE_ENVELOPE_PARAGRAPHS }, (_, index) => `Paragraph ${index + 1}: **formatted** needle and [link](https://example.com/).`).join("\n\n");
+    const proxy = await createCacheableViewerProxy({ initialMarkdown: source });
+    let context: BrowserContext | undefined;
+    try {
+      context = await browser.newContext({ viewport: { width, height: 900 }, serviceWorkers: "block", proxy: { server: proxy.url, bypass: "<-loopback>" } });
+      const page = await context.newPage();
+      await page.goto("/browse/smb/demo");
+      await page.getByRole("button", { name: "Later", exact: true }).click();
+      await page.evaluate(() => {
+        const nativeFrame = window.requestAnimationFrame.bind(window);
+        const held: FrameRequestCallback[] = [];
+        const probe = { hold: true, held, release: () => { probe.hold = false; for (const callback of held.splice(0)) nativeFrame(callback); } };
+        (window as typeof window & { progressiveProbe: typeof probe }).progressiveProbe = probe;
+        window.requestAnimationFrame = (callback) => nativeFrame((time) => {
+          const stage = document.querySelector('[data-markdown-publication="loading"]');
+          const viewport = document.querySelector('[data-testid="markdown-viewer-content"]');
+          if (probe.hold && stage && viewport && stage.getBoundingClientRect().height >= viewport.clientHeight * 2) held.push(callback);
+          else callback(time);
+        });
+      });
+      const file = page.getByRole("button", { name: DEMO_PATH, exact: true }).or(page.getByRole("button", { name: `File: ${DEMO_PATH}`, exact: true }));
+      await file.click();
+      await page.waitForFunction(() => (window as typeof window & { progressiveProbe: { held: unknown[] } }).progressiveProbe.held.length > 0, undefined, { polling: 25 });
+      const preview = page.locator('[data-markdown-search-root="true"]');
+      expect(await preview.locator("p").count()).toBeLessThan(PROSE_ENVELOPE_PARAGRAPHS);
+      await expect(page.getByRole("button", { name: "Search", exact: true })).toBeDisabled();
+      await expect(page.getByRole("button", { name: "Edit", exact: true })).toBeDisabled();
+      await expect(page.getByRole("button", { name: "Print", exact: true })).toBeDisabled();
+      await expect(page.getByRole("status", { name: "Loading...", exact: true })).toBeVisible();
+      await expect(page.getByRole("status", { name: "Loading...", exact: true }).getByRole("progressbar")).toBeInViewport({ ratio: 1 });
+      await testInfo.attach("progressive-loading", { body: await page.screenshot(), contentType: "image/png" });
+      await page.emulateMedia({ media: "print" });
+      await expect(preview).toBeHidden();
+      await expect(page.getByText("The document is still loading. Close the print dialog and try again when loading finishes.", { exact: true })).toBeVisible();
+      await page.emulateMedia({ media: null });
+      await page.keyboard.press("Escape");
+      await expect(preview).toHaveCount(0);
+      await page.evaluate(() => (window as typeof window & { progressiveProbe: { release: () => void } }).progressiveProbe.release());
+      await file.click();
+      await expect(page.locator('[data-markdown-publication="complete"]')).toBeVisible();
+      await expect(preview.locator("p")).toHaveCount(PROSE_ENVELOPE_PARAGRAPHS);
+      await expect(page.getByRole("button", { name: "Search", exact: true })).toBeEnabled();
+      await expect(page.getByRole("button", { name: "Print", exact: true })).toBeEnabled();
+      await expect(page.getByRole("status", { name: "Loading...", exact: true })).toHaveCount(0);
+      await page.getByRole("button", { name: "Close", exact: true }).click();
+      expect(proxy.errors).toEqual([]);
+    } finally {
+      await context?.close();
+      await proxy.close();
+    }
+  });
+}
+
+for (const width of [1543, 390]) {
+  for (const fixture of ["prose", "table"] as const) {
+    test(`production prose table responsiveness ${fixture} at ${width}px`, async ({ browser }, testInfo) => {
+      test.skip(process.env.SAMBEE_E2E_PRODUCTION !== "1", "Requires the normal production build");
+      const profiling = process.env.SAMBEE_E2E_TRACE === "1";
+      test.skip(profiling && testInfo.project.name !== "chromium", "Load CPU profiling requires Chromium CDP");
+      if (process.env.SAMBEE_E2E_MEMORY === "1" || (profiling && process.env.SAMBEE_E2E_BUDGETS === "1")) throw new Error("Document/scroll timing must run separately from GC and profiling");
+      const paragraphs = Array.from({ length: PROSE_ENVELOPE_PARAGRAPHS }, (_, index) => `Paragraph ${index + 1}: **formatted** needle and [link](https://example.com/).`);
+      const rows = Array.from({ length: TABLE_ENVELOPE_ROWS }, (_, index) => `| ${index + 1} | row ${index + 1} needle |`);
+      const source = fixture === "prose" ? `${paragraphs.join("\n\n")}\n` : `| Key | Value |\n| --- | --- |\n${rows.join("\n")}\n`;
+      const expectedBlocks = fixture === "prose" ? paragraphs.map((_, index) => `Paragraph ${index + 1}: formatted needle and link.`) : ["Key", "Value", ...rows.flatMap((_, index) => [`${index + 1}`, `row ${index + 1} needle`])];
+      const expectedItems = fixture === "prose" ? PROSE_ENVELOPE_PARAGRAPHS : TABLE_ENVELOPE_ROWS;
+      const proxy = await createCacheableViewerProxy({ initialMarkdown: source });
+      let context: BrowserContext | undefined;
+      try {
+        context = await browser.newContext({ viewport: { width, height: 900 }, serviceWorkers: "block", proxy: { server: proxy.url, bypass: "<-loopback>" } });
+        const page = await context.newPage();
+        await page.goto("/browse/smb/demo");
+        await page.getByRole("button", { name: "Later", exact: true }).click();
+        await page.evaluate(({ fixture, expectedItems, profiling }) => {
+          const probe = { openAt: null as number | null, completedMs: null as number | null, firstViewportMs: null as number | null, firstViewportItems: null as number | null, maximumTimerGap: 0, stop: () => {} };
+          (window as typeof window & { proseTableProbe: typeof probe }).proseTableProbe = probe;
+          let previousTick: number | undefined;
+          let completing = false;
+          document.addEventListener("click", () => { probe.openAt = performance.now(); previousTick = probe.openAt; if (profiling) performance.mark("sambee:viewer-load:start"); }, { once: true, capture: true });
+          const timer = setInterval(() => {
+            if (previousTick === undefined || probe.completedMs !== null) return;
+            const now = performance.now();
+            probe.maximumTimerGap = Math.max(probe.maximumTimerGap, now - previousTick);
+            previousTick = now;
+          }, 0);
+          const observer = new MutationObserver(() => {
+            const root = document.querySelector('[data-markdown-search-root="true"]');
+            if (!root || completing || probe.openAt === null) return;
+            const count = root.querySelectorAll(fixture === "prose" ? "p" : "tbody tr").length;
+            const viewport = root.parentElement;
+            if (probe.firstViewportMs === null && viewport && root.getBoundingClientRect().height >= viewport.clientHeight * 2) {
+              probe.firstViewportMs = performance.now() - probe.openAt;
+              probe.firstViewportItems = count;
+            }
+            if (count !== expectedItems) return;
+            completing = true;
+            requestAnimationFrame(() => requestAnimationFrame(() => { probe.completedMs = performance.now() - (probe.openAt as number); if (profiling) performance.mark("sambee:viewer-load:complete"); }));
+          });
+          observer.observe(document.body, { childList: true, subtree: true });
+          probe.stop = () => { observer.disconnect(); clearInterval(timer); };
+        }, { fixture, expectedItems, profiling });
+        const profiler = profiling ? await context.newCDPSession(page) : undefined;
+        const traceEvents: unknown[] = [];
+        if (profiler) {
+          profiler.on("Tracing.dataCollected", event => traceEvents.push(...event.value));
+          await profiler.send("Profiler.enable");
+          await profiler.send("Profiler.start");
+          await profiler.send("Tracing.start", { categories: "devtools.timeline,blink.user_timing,v8", transferMode: "ReportEvents" });
+        }
+        await page.getByRole("button", { name: DEMO_PATH, exact: true }).or(page.getByRole("button", { name: `File: ${DEMO_PATH}`, exact: true })).click();
+        await page.waitForFunction(() => (window as typeof window & { proseTableProbe: { completedMs: number | null } }).proseTableProbe.completedMs !== null);
+        if (profiler) {
+          const profile = await profiler.send("Profiler.stop");
+          const tracingComplete = new Promise<void>(resolve => profiler.once("Tracing.tracingComplete", () => resolve()));
+          await profiler.send("Tracing.end");
+          await tracingComplete;
+          expect(profile.profile.samples?.length ?? 0).toBeGreaterThan(0);
+          expect(traceEvents).toEqual(expect.arrayContaining([
+            expect.objectContaining({ name: "sambee:viewer-load:start", ph: "I" }),
+            expect.objectContaining({ name: "sambee:viewer-load:complete", ph: "I" }),
+          ]));
+          await testInfo.attach("viewer-load-cpu-profile", { contentType: "application/json", body: JSON.stringify(profile) });
+          await testInfo.attach("viewer-load-timeline", { contentType: "application/json", body: JSON.stringify({ traceEvents }) });
+          await profiler.detach();
+        }
+        const load = await page.evaluate(() => {
+          const probe = (window as typeof window & { proseTableProbe: { completedMs: number; firstViewportMs: number | null; firstViewportItems: number | null; maximumTimerGap: number; stop: () => void } }).proseTableProbe;
+          probe.stop();
+          return { documentCompletion: probe.completedMs, maximumTimerGap: probe.maximumTimerGap, firstViewportMs: probe.firstViewportMs, firstViewportItems: probe.firstViewportItems };
+        });
+        const preview = page.locator('[data-markdown-search-root="true"]');
+        const initialRenderedText = await preview.textContent();
+        expect(await preview.locator(fixture === "prose" ? "p" : "th, td").allTextContents()).toEqual(expectedBlocks);
+        await expect(page.getByRole("button", { name: "Search", exact: true })).toBeEnabled();
+        const scrolling = await preview.evaluate(async (root, steps) => {
+          const scroller = root.parentElement;
+          if (!(scroller instanceof HTMLElement) || scroller.scrollHeight <= scroller.clientHeight) throw new Error("Expected a scrollable full document");
+          const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT);
+          const nodes: Node[] = [];
+          for (let node = walker.nextNode(); node; node = walker.nextNode()) nodes.push(node);
+          const intervals: number[] = [];
+          const offsets: number[] = [];
+          const start = performance.now();
+          let previous: number | undefined;
+          await new Promise<void>(resolve => {
+            const frame = (now: number) => {
+              if (previous !== undefined) intervals.push(now - previous);
+              if (offsets.length === steps) { resolve(); return; }
+              previous = now;
+              scroller.scrollTop = (scroller.scrollHeight - scroller.clientHeight) * offsets.length / (steps - 1);
+              offsets.push(scroller.scrollTop);
+              requestAnimationFrame(frame);
+            };
+            requestAnimationFrame(frame);
+          });
+          const after = document.createTreeWalker(root, NodeFilter.SHOW_TEXT);
+          const unchanged = nodes.every(node => after.nextNode() === node) && after.nextNode() === null;
+          const selection = window.getSelection();
+          if (!selection || !nodes.length) throw new Error("Expected native selectable document text");
+          const range = document.createRange();
+          range.selectNodeContents(root);
+          selection.removeAllRanges();
+          selection.addRange(range);
+          const selected = selection.toString();
+          selection.removeAllRanges();
+          return { intervals, offsets, elapsedMs: performance.now() - start, unchangedTextNodes: unchanged, sameRoot: document.querySelector('[data-markdown-search-root="true"]') === root, selectedText: selected, physicalRefreshHz: null };
+        }, SCROLL_PROBE_STEPS);
+        const intervals = [...scrolling.intervals].sort((left, right) => left - right);
+        const p95 = intervals[Math.ceil(intervals.length * 0.95) - 1];
+        const frameProxy = { p95, maximumMs: Math.max(...intervals), nominal60HzP95TargetMs: NOMINAL_60HZ_SCROLL_TARGETS_MS.p95, nominal60HzMaximumTargetMs: NOMINAL_60HZ_SCROLL_TARGETS_MS.maximum, status: "diagnostic", physicalRefreshHz: null, p95ExceedsNominal: p95 > NOMINAL_60HZ_SCROLL_TARGETS_MS.p95 };
+        const budgets = { status: profiling ? "diagnostic" : load.documentCompletion <= VIEWER_TIMING_TARGETS_MS.documentCompletion && load.maximumTimerGap <= VIEWER_TIMING_TARGETS_MS.maximumTimerGap ? "pass" : "fail", documentCompletion: { observedMs: load.documentCompletion, targetMs: VIEWER_TIMING_TARGETS_MS.documentCompletion }, maximumTimerGap: { observedMs: load.maximumTimerGap, targetMs: VIEWER_TIMING_TARGETS_MS.maximumTimerGap } };
+        await testInfo.attach("prose-table-responsiveness", { contentType: "application/json", body: JSON.stringify({ fixture, width, engine: testInfo.project.name, trial: testInfo.repeatEachIndex, browserVersion: browser.version(), sourceUnits: source.length, expectedItems, load, budgets, scrolling: { ...scrolling, selectedText: undefined }, frameProxy, enforced: process.env.SAMBEE_E2E_BUDGETS === "1", limitations: ["Programmatic main-thread scroll and rAF intervals, not wheel/touch/compositor smoothness or hardware paint", "Physical refresh rate and power mode unverified; no physical 60 Hz acceptance", "No eligible fenced syntax in these fixtures; syntax readiness is not applicable", "No application/native CPU attribution is inferred from interval or timer gaps"] }) });
+        expect(scrolling.sameRoot && scrolling.unchangedTextNodes).toBe(true);
+        expect(scrolling.offsets).toHaveLength(SCROLL_PROBE_STEPS);
+        expect(scrolling.offsets[0]).toBe(0);
+        expect(scrolling.offsets.at(-1)).toBeGreaterThan(0);
+        expect(intervals).toHaveLength(SCROLL_PROBE_STEPS);
+        expect(intervals.every(value => Number.isFinite(value) && value > 0)).toBe(true);
+        expect(scrolling.selectedText).toContain(fixture === "prose" ? "Paragraph 1: formatted needle and link." : "row 1 needle");
+        expect(scrolling.selectedText).toContain(fixture === "prose" ? `Paragraph ${expectedItems}: formatted needle and link.` : `row ${expectedItems} needle`);
+        expect(await preview.textContent()).toBe(initialRenderedText);
+        await page.getByRole("button", { name: "Close", exact: true }).click();
+        await expect(preview).toHaveCount(0);
+        expect(proxy.errors).toEqual([]);
+        expect(Number.isFinite(load.documentCompletion) && load.documentCompletion >= 0).toBe(true);
+        expect(Number.isFinite(load.maximumTimerGap) && load.maximumTimerGap >= 0).toBe(true);
+        if (process.env.SAMBEE_E2E_BUDGETS === "1") expect(budgets.status, JSON.stringify(budgets)).toBe("pass");
+      } finally {
+        await context?.close();
+        await proxy.close();
+      }
+    });
+  }
+}
+
+for (const width of [1543, 390]) {
+  for (const fixture of ["dense", "long-line"] as const) {
+    test(`production source typing ${fixture} at ${width}px`, async ({ browser }, testInfo) => {
+      test.skip(process.env.SAMBEE_E2E_PRODUCTION !== "1", "Requires the normal production build");
+      if (process.env.SAMBEE_E2E_MEMORY === "1" || process.env.SAMBEE_E2E_TRACE === "1") throw new Error("Typing timing must run separately from GC and profiling");
+      const initialMarkdown = `abc 123;${fixture === "dense" ? "\n" : " "}`.repeat(DENSE_SYNTAX_LINE_COUNT);
+      const proxy = await createCacheableViewerProxy({ initialMarkdown, wordWrapEnabled: false });
+      let context: BrowserContext | undefined;
+      try {
+        context = await browser.newContext({ viewport: { width, height: 900 }, serviceWorkers: "block", proxy: { server: proxy.url, bypass: "<-loopback>" } });
+        const page = await context.newPage();
+        await page.goto("/browse/smb/demo");
+        await page.getByRole("button", { name: "Later", exact: true }).click();
+        await page.getByRole("button", { name: DEMO_PATH, exact: true }).or(page.getByRole("button", { name: `File: ${DEMO_PATH}`, exact: true })).click();
+        await enterMarkdownEditMode(page);
+        const editor = page.getByRole("textbox", { name: "Markdown editor" });
+        await editor.click();
+        await page.keyboard.press("Control+End");
+        await editor.evaluate(async element => {
+          await new Promise<void>(resolve => requestAnimationFrame(() => requestAnimationFrame(() => resolve())));
+          const probe: SourceTypingProbe = { inputs: [], measures: [], gaps: [], longTasks: [], longTasksSupported: PerformanceObserver.supportedEntryTypes.includes("longtask"), stop: () => {} };
+          (window as typeof window & { sourceTypingProbe: SourceTypingProbe }).sourceTypingProbe = probe;
+          let previousTick: number | undefined;
+          const timer = setInterval(() => {
+            if (previousTick === undefined) return;
+            const now = performance.now();
+            probe.gaps.push(now - previousTick);
+            previousTick = now;
+          }, 0);
+          const keydown = (event: Event) => {
+            if (!(event instanceof KeyboardEvent) || event.key.length !== 1 || event.ctrlKey || event.metaKey || event.altKey) return;
+            const sample = { key: event.key, trusted: event.isTrusted, at: performance.now(), firstFrameMs: null as number | null, twoFrameMs: null as number | null };
+            previousTick ??= sample.at;
+            probe.inputs.push(sample);
+            requestAnimationFrame(() => {
+              sample.firstFrameMs = performance.now() - sample.at;
+              requestAnimationFrame(() => { sample.twoFrameMs = performance.now() - sample.at; });
+            });
+          };
+          element.addEventListener("keydown", keydown, true);
+          const measures = new PerformanceObserver(list => {
+            for (const entry of list.getEntries()) {
+              if (!entry.name.startsWith("sambee:source-editor:")) continue;
+              const measure = entry as PerformanceMeasure;
+              probe.measures.push({ name: measure.name, startTime: measure.startTime, duration: measure.duration, detail: measure.detail });
+            }
+          });
+          measures.observe({ type: "measure" });
+          const longTasks = probe.longTasksSupported ? new PerformanceObserver(list => {
+            for (const entry of list.getEntries()) probe.longTasks.push({ startTime: entry.startTime, duration: entry.duration });
+          }) : undefined;
+          longTasks?.observe({ type: "longtask" });
+          probe.stop = () => { clearInterval(timer); measures.disconnect(); longTasks?.disconnect(); element.removeEventListener("keydown", keydown, true); };
+        });
+        await page.keyboard.type(SOURCE_TYPING_PAYLOAD, { delay: SOURCE_TYPING_KEY_DELAY_MS });
+        await page.waitForFunction(expected => {
+          const probe = (window as typeof window & { sourceTypingProbe: SourceTypingProbe }).sourceTypingProbe;
+          return probe.inputs.length === expected && probe.inputs.every(sample => sample.twoFrameMs !== null) && probe.measures.filter(entry => entry.name === "sambee:source-editor:publish").length === expected;
+        }, SOURCE_TYPING_PAYLOAD.length);
+        await expect(page.getByLabel("Unsaved changes", { exact: true })).toBeVisible();
+        const evidence = await page.evaluate(() => {
+          const probe = (window as typeof window & { sourceTypingProbe: SourceTypingProbe }).sourceTypingProbe;
+          probe.stop();
+          return { inputs: probe.inputs, measures: probe.measures, gaps: probe.gaps, longTasks: probe.longTasks, longTasksSupported: probe.longTasksSupported };
+        });
+        const frames = evidence.inputs.map(sample => sample.twoFrameMs ?? Number.NaN).sort((left, right) => left - right);
+        const maximumStage = (name: string) => { const stages = evidence.measures.filter(entry => entry.name === name); return stages.length ? Math.max(...stages.map(entry => entry.duration)) : null; };
+        const budgets = evaluateSourceTypingBudgets({ keyboardTwoFrameP95: frames[Math.ceil(frames.length * 0.95) - 1], maximumTimerGap: evidence.gaps.length ? Math.max(...evidence.gaps) : null, serialization: maximumStage("sambee:source-editor:serialize"), synchronousPublication: maximumStage("sambee:source-editor:publish") });
+        await testInfo.attach("source-typing", { contentType: "application/json", body: JSON.stringify({ fixture, width, engine: testInfo.project.name, trial: testInfo.repeatEachIndex, browserVersion: browser.version(), sourceUnits: initialMarkdown.length, inputCount: SOURCE_TYPING_PAYLOAD.length, keyDelayMs: SOURCE_TYPING_KEY_DELAY_MS, evidence, budgets, enforced: process.env.SAMBEE_E2E_BUDGETS === "1", limitations: ["Browser keydown-to-two-frame scheduling proxy, not hardware input or physical paint", "Long Task entries are whole-renderer observations, not isolated application CPU attribution", "Missing Long Tasks support is unmeasured, not a pass"] }) });
+        expect(evidence.inputs.map(sample => sample.key).join("")).toBe(SOURCE_TYPING_PAYLOAD);
+        expect(evidence.inputs.every(sample => sample.trusted)).toBe(true);
+        for (const name of ["serialize", "publish", "normalize", "parent-update"]) {
+          const stages = evidence.measures.filter(entry => entry.name === `sambee:source-editor:${name}`);
+          expect(stages).toHaveLength(SOURCE_TYPING_PAYLOAD.length);
+          expect(stages.map(entry => entry.detail.documentUnits)).toEqual(Array.from({ length: SOURCE_TYPING_PAYLOAD.length }, (_, index) => initialMarkdown.length + index + 1));
+        }
+        expect(budgets.metrics.filter(metric => metric.status === "invalid")).toEqual([]);
+        await page.getByRole("button", { name: "Save", exact: true }).click();
+        await expect.poll(() => proxy.uploads.length).toBe(1);
+        const upload = proxy.uploads[0];
+        const form = await new Response(upload.body, { headers: { "Content-Type": upload.contentType } }).formData();
+        const files = [...form.values()].filter((value): value is File => typeof value !== "string");
+        expect(files).toHaveLength(1);
+        expect(await files[0].text()).toBe(`${initialMarkdown}${SOURCE_TYPING_PAYLOAD}`);
+        await page.getByRole("button", { name: "Close", exact: true }).click();
+        await expect(page.getByRole("textbox", { name: "Markdown editor" })).toHaveCount(0);
+        expect(proxy.errors).toEqual([]);
+        if (process.env.SAMBEE_E2E_BUDGETS === "1") expect(budgets.status, JSON.stringify(budgets)).toBe("pass");
+      } finally {
+        await context?.close();
+        await proxy.close();
+      }
+    });
+  }
+}
+
+const SOURCE_REGEX_PARITY_FIXTURES = [
+  { name: "zero-length", source: "alpha beta\nalpha\n", query: "(?=alpha)", replacement: "!", caseSensitive: false, wholeWord: false },
+  { name: "case-sensitive", source: "Alpha alpha ALPHA alphabet alpha2\nalpha\n", query: "alpha", replacement: "done", caseSensitive: true, wholeWord: false },
+  { name: "whole-word", source: "Alpha alpha alphabet alpha2 _alpha alpha_\nalpha\n", query: "alpha", replacement: "done", caseSensitive: false, wholeWord: true },
+  { name: "large-output", source: "alpha\ntail\n", query: "alpha", replacement: "x".repeat(SOURCE_SEARCH_CHUNK_UNITS * 2 + 1), caseSensitive: false, wholeWord: false },
+] as const;
+
+function nativeSourceRegexOutcome(fixture: typeof SOURCE_REGEX_PARITY_FIXTURES[number]) {
+  const query = new SearchQuery({ search: fixture.query, replace: fixture.replacement, regexp: true, literal: true, caseSensitive: fixture.caseSensitive, wholeWord: fixture.wholeWord });
+  let state = EditorState.create({ doc: fixture.source, extensions: [search()] });
+  state = state.update({ effects: setSearchQuery.of(query) }).state;
+  const cursor = query.getCursor(state);
+  let count = 0;
+  for (let match = cursor.next(); !match.done; match = cursor.next()) count += 1;
+  nativeReplaceAll({ get state() { return state; }, plugin: () => null, dispatch: (spec: TransactionSpec) => { state = state.update(spec).state; } } as unknown as EditorView);
+  return { count, output: state.doc.toString() };
+}
+
+for (const width of [1543, 390]) {
+  for (const fixture of SOURCE_REGEX_PARITY_FIXTURES) {
+    test(`production source regex parity ${fixture.name} at ${width}px`, async ({ browser }, testInfo) => {
+      test.skip(process.env.SAMBEE_E2E_PRODUCTION !== "1", "Requires the normal production build");
+      const expected = nativeSourceRegexOutcome(fixture);
+      expect(expected.count).toBeGreaterThan(0);
+      expect(expected.output).not.toBe(fixture.source);
+      const proxy = await createCacheableViewerProxy({ initialMarkdown: fixture.source, wordWrapEnabled: false });
+      let context: BrowserContext | undefined;
+      try {
+        context = await browser.newContext({ viewport: { width, height: 900 }, serviceWorkers: "block", proxy: { server: proxy.url, bypass: "<-loopback>" } });
+        await context.addInitScript(() => {
+          const jobs: { url: string; terminated: boolean; changeChunks: number; continuedChunks: number; maximumChunkUnits: number; insertedUnits: number }[] = [];
+          (window as typeof window & { sourceParityJobs: typeof jobs }).sourceParityJobs = jobs;
+          const NativeWorker = window.Worker;
+          window.Worker = class extends NativeWorker {
+            private job: typeof jobs[number];
+            constructor(url: string | URL, options?: WorkerOptions) {
+              super(url, options);
+              this.job = { url: String(url), terminated: false, changeChunks: 0, continuedChunks: 0, maximumChunkUnits: 0, insertedUnits: 0 };
+              jobs.push(this.job);
+              this.addEventListener("message", event => {
+                const message = event.data;
+                if (message?.type !== "change") return;
+                this.job.changeChunks += 1;
+                this.job.continuedChunks += Number(message.continued);
+                this.job.insertedUnits += message.insert.length;
+                this.job.maximumChunkUnits = Math.max(this.job.maximumChunkUnits, message.insert.length);
+              });
+            }
+            terminate() { this.job.terminated = true; super.terminate(); }
+          };
+        });
+        const page = await context.newPage();
+        await page.goto("/browse/smb/demo");
+        await page.getByRole("button", { name: "Later", exact: true }).click();
+        await page.getByRole("button", { name: DEMO_PATH, exact: true }).or(page.getByRole("button", { name: `File: ${DEMO_PATH}`, exact: true })).click();
+        await enterMarkdownEditMode(page);
+        await page.getByRole("textbox", { name: "Markdown editor" }).click();
+        await page.keyboard.press("Control+h");
+        const controls = page.getByRole("search");
+        await controls.getByRole("button", { name: "Use regular expression", exact: true }).click();
+        if (fixture.caseSensitive) await controls.getByRole("button", { name: "Match case", exact: true }).click();
+        if (fixture.wholeWord) await controls.getByRole("button", { name: "Match whole word", exact: true }).click();
+        await controls.getByRole("textbox", { name: "Find", exact: true }).fill(fixture.query);
+        await controls.getByRole("textbox", { name: "Replace", exact: true }).fill(fixture.replacement);
+        await expect(controls.getByText(`0 / ${expected.count}`, { exact: true })).toBeVisible();
+        await page.mouse.move(0, 0);
+        await expect(page.getByRole("tooltip")).toHaveCount(0);
+        await controls.getByRole("button", { name: "Replace all", exact: true }).click();
+        await expect(page.getByLabel("Unsaved changes", { exact: true })).toBeVisible();
+        await expect(controls.getByRole("alert")).toHaveCount(0);
+        await controls.getByRole("button", { name: "Close", exact: true }).click();
+        await page.getByRole("button", { name: "Save", exact: true }).click();
+        await expect.poll(() => proxy.uploads.length).toBe(1);
+        const upload = proxy.uploads[0];
+        const form = await new Response(upload.body, { headers: { "Content-Type": upload.contentType } }).formData();
+        const files = [...form.values()].filter((value): value is File => typeof value !== "string");
+        expect(files).toHaveLength(1);
+        expect(await files[0].text()).toBe(expected.output);
+        await page.getByRole("button", { name: "Close", exact: true }).click();
+        await expect(page.getByRole("textbox", { name: "Markdown editor" })).toHaveCount(0);
+        await expect.poll(() => page.evaluate(() => (window as typeof window & { sourceParityJobs: { terminated: boolean }[] }).sourceParityJobs.filter(job => !job.terminated).length)).toBe(0);
+        const jobs = await page.evaluate(() => (window as typeof window & { sourceParityJobs: unknown[] }).sourceParityJobs);
+        const replacements = (jobs as { changeChunks: number; continuedChunks: number; maximumChunkUnits: number; insertedUnits: number }[]).filter(job => job.changeChunks > 0);
+        expect(replacements).toHaveLength(1);
+        expect(replacements[0].maximumChunkUnits).toBeLessThanOrEqual(SOURCE_SEARCH_CHUNK_UNITS);
+        if (fixture.name === "large-output") {
+          expect(replacements[0].changeChunks).toBe(3);
+          expect(replacements[0].continuedChunks).toBe(2);
+          expect(replacements[0].insertedUnits).toBe(fixture.replacement.length);
+        }
+        await testInfo.attach("source-regex-parity", { contentType: "application/json", body: JSON.stringify({ fixture: fixture.name, width, count: expected.count, sourceUnits: fixture.source.length, outputUnits: expected.output.length, jobs, policy: "Functional parity with native CodeMirror commands; not timing or memory acceptance" }) });
+        expect(proxy.errors).toEqual([]);
+      } finally {
+        await context?.close();
+        await proxy.close();
+      }
+    });
+  }
+}
+
+for (const width of [1543, 390]) {
+  for (const fault of ["startup", "crash", "decode", "timeout", "delivery-cancel"] as const) {
+    test(`production source regex lifecycle ${fault} at ${width}px`, async ({ browser }, testInfo) => {
+      test.skip(process.env.SAMBEE_E2E_PRODUCTION !== "1", "Requires the normal production build");
+      const initialMarkdown = "abc 123;\n".repeat(DENSE_SYNTAX_LINE_COUNT);
+      const proxy = await createCacheableViewerProxy({ initialMarkdown, wordWrapEnabled: false });
+      let context: BrowserContext | undefined;
+      try {
+        context = await browser.newContext({ viewport: { width, height: 900 }, serviceWorkers: "block", proxy: { server: proxy.url, bypass: "<-loopback>" } });
+        await context.addInitScript((fault) => {
+          const probe = { injected: 0, deliveredChanges: 0, jobs: [] as { sourceSearch: boolean; terminated: boolean }[], replay: () => {} };
+          (window as typeof window & { sourceLifecycleProbe: typeof probe }).sourceLifecycleProbe = probe;
+          const NativeWorker = window.Worker;
+          window.Worker = class extends NativeWorker {
+            private job: typeof probe.jobs[number];
+            constructor(url: string | URL, options?: WorkerOptions) {
+              const sourceSearch = String(url).includes("sourceRegexSearch.worker");
+              if (sourceSearch && fault === "startup" && probe.injected === 0) {
+                probe.injected += 1;
+                throw new Error("Injected source-search construction failure");
+              }
+              super(url, options);
+              this.job = { sourceSearch, terminated: false };
+              probe.jobs.push(this.job);
+              this.addEventListener("message", event => {
+                if (!sourceSearch || probe.injected > 0) return;
+                if (fault === "delivery-cancel") {
+                  if (event.data?.type !== "change") return;
+                  if (probe.deliveredChanges++ === 0) return;
+                  event.stopImmediatePropagation();
+                  probe.injected += 1;
+                  const stale = event.data;
+                  probe.replay = () => {
+                    this.dispatchEvent(new MessageEvent("message", { data: stale }));
+                    this.dispatchEvent(new MessageEvent("message", { data: { type: "complete", announcements: [], userEvent: "input.replace.all" } }));
+                  };
+                } else if (event.data?.type === "ready") {
+                  event.stopImmediatePropagation();
+                  probe.injected += 1;
+                  if (fault === "crash") this.dispatchEvent(new ErrorEvent("error", { message: "Injected source-search execution failure", cancelable: true }));
+                  if (fault === "decode") this.dispatchEvent(new MessageEvent("messageerror"));
+                }
+              }, { capture: true });
+            }
+            terminate() { this.job.terminated = true; super.terminate(); }
+          };
+        }, fault);
+        const page = await context.newPage();
+        await page.goto("/browse/smb/demo");
+        await page.getByRole("button", { name: "Later", exact: true }).click();
+        await page.getByRole("button", { name: DEMO_PATH, exact: true }).or(page.getByRole("button", { name: `File: ${DEMO_PATH}`, exact: true })).click();
+        await enterMarkdownEditMode(page);
+        const editor = page.getByRole("textbox", { name: "Markdown editor" });
+        await editor.click();
+        await page.keyboard.press("Control+h");
+        const controls = page.getByRole("search");
+        await controls.getByRole("button", { name: "Use regular expression", exact: true }).click();
+        await controls.getByRole("textbox", { name: "Find", exact: true }).fill("abc (123)");
+        if (fault === "delivery-cancel") {
+          await controls.getByRole("textbox", { name: "Replace", exact: true }).fill("replaced-$1");
+          await expect(controls.getByText(`0 / ${DENSE_SYNTAX_LINE_COUNT}`, { exact: true })).toBeVisible();
+          await page.mouse.move(0, 0);
+          await expect(page.getByRole("tooltip")).toHaveCount(0);
+          await controls.getByRole("button", { name: "Replace all", exact: true }).click();
+          await page.waitForFunction(() => (window as typeof window & { sourceLifecycleProbe: { injected: number } }).sourceLifecycleProbe.injected === 1);
+          await expect(page.getByLabel("Unsaved changes", { exact: true })).toHaveCount(0);
+        } else {
+          const messages = { startup: /requires a working dedicated worker/, crash: /worker failed/, decode: /could not be decoded/, timeout: /did not start/ };
+          await expect(controls.getByRole("alert")).toContainText(messages[fault]);
+          await expect(page.getByLabel("Unsaved changes", { exact: true })).toHaveCount(0);
+          await page.mouse.move(0, 0);
+          await expect(page.getByRole("tooltip")).toHaveCount(0);
+          await controls.getByRole("button", { name: "Next match", exact: true }).click();
+          await expect(controls.getByText(new RegExp(`^\\d+ / ${DENSE_SYNTAX_LINE_COUNT}$`))).toBeVisible();
+          await expect(controls.getByRole("alert")).toHaveCount(0);
+        }
+        await editor.focus();
+        await page.keyboard.press("Control+End");
+        await page.keyboard.type("!");
+        await expect(page.getByLabel("Unsaved changes", { exact: true })).toBeVisible();
+        if (fault === "delivery-cancel") await page.evaluate(() => (window as typeof window & { sourceLifecycleProbe: { replay: () => void } }).sourceLifecycleProbe.replay());
+        await controls.getByRole("button", { name: "Close", exact: true }).click();
+        await page.getByRole("button", { name: "Save", exact: true }).click();
+        await expect.poll(() => proxy.uploads.length).toBe(1);
+        const upload = proxy.uploads[0];
+        const form = await new Response(upload.body, { headers: { "Content-Type": upload.contentType } }).formData();
+        const files = [...form.values()].filter((value): value is File => typeof value !== "string");
+        expect(files).toHaveLength(1);
+        expect(await files[0].text()).toBe(`${initialMarkdown}!`);
+        await page.getByRole("button", { name: "Close", exact: true }).click();
+        await expect(page.getByRole("textbox", { name: "Markdown editor" })).toHaveCount(0);
+        await expect.poll(() => page.evaluate(() => (window as typeof window & { sourceLifecycleProbe: { jobs: { terminated: boolean }[] } }).sourceLifecycleProbe.jobs.filter(job => !job.terminated).length)).toBe(0);
+        const evidence = await page.evaluate(() => {
+          const probe = (window as typeof window & { sourceLifecycleProbe: { injected: number; deliveredChanges: number; jobs: { sourceSearch: boolean; terminated: boolean }[] } }).sourceLifecycleProbe;
+          return { injected: probe.injected, deliveredChanges: probe.deliveredChanges, jobs: probe.jobs };
+        });
+        expect(evidence.injected).toBe(1);
+        expect(evidence.jobs.filter(job => job.sourceSearch).length).toBeGreaterThan(1);
+        if (fault === "delivery-cancel") expect(evidence.deliveredChanges).toBe(2);
+        await testInfo.attach("source-regex-lifecycle", { contentType: "application/json", body: JSON.stringify({ fault, width, evidence, policy: "Test-only constructor/event/ready-message injection; functional recovery and stale-delivery rejection, not timing or memory acceptance" }) });
+        expect(proxy.errors).toEqual([]);
+      } finally {
+        await context?.close();
+        await proxy.close();
+      }
+    });
+  }
+}
+
+interface ReplacementFeedbackProbe {
+  hold: boolean;
+  additions: number;
+  frames: { width: number; height: number; original: boolean; animation: string }[];
+  release: () => void;
+}
+
+for (const width of [1543, 390]) {
+  for (const regexp of [false, true]) {
+    test(`production replacement feedback ${regexp ? "regex keyboard" : "literal toolbar"} at ${width}px`, async ({ browser }, testInfo) => {
+      test.skip(process.env.SAMBEE_E2E_PRODUCTION !== "1", "Requires the normal production build");
+      const initialMarkdown = `${"abc 123;\n".repeat(DENSE_SYNTAX_LINE_COUNT)}tail`;
+      const replacement = "x".repeat(DENSE_EXPANSION_REPLACEMENT_UNITS);
+      const expected = `${`${replacement};\n`.repeat(DENSE_SYNTAX_LINE_COUNT)}tail`;
+      const proxy = await createCacheableViewerProxy({ initialMarkdown, wordWrapEnabled: false });
+      let context: BrowserContext | undefined;
+      try {
+        context = await browser.newContext({ viewport: { width, height: 900 }, serviceWorkers: "block", proxy: { server: proxy.url, bypass: "<-loopback>" } });
+        await context.addInitScript(() => {
+          const nativeFrame = window.requestAnimationFrame.bind(window);
+          const held: FrameRequestCallback[] = [];
+          const probe: ReplacementFeedbackProbe = { hold: false, additions: 0, frames: [], release: () => {
+            probe.hold = false;
+            for (const callback of held.splice(0)) nativeFrame(callback);
+          } };
+          (window as typeof window & { replacementFeedbackProbe: ReplacementFeedbackProbe }).replacementFeedbackProbe = probe;
+          window.requestAnimationFrame = callback => nativeFrame(time => {
+            if (probe.hold && document.querySelector(".sambee-source-replacement-feedback")) held.push(callback);
+            else callback(time);
+          });
+          new MutationObserver(records => {
+            for (const record of records) for (const node of record.addedNodes) {
+              if (!(node instanceof HTMLElement) || !node.matches(".sambee-source-replacement-feedback")) continue;
+              probe.additions += 1;
+              nativeFrame(() => {
+                const rect = node.getBoundingClientRect();
+                probe.frames.push({ width: rect.width, height: rect.height, original: Boolean(document.querySelector(".cm-content")?.textContent?.includes("abc 123")), animation: node.querySelector("span")?.getAnimations()[0]?.playState ?? "unavailable" });
+              });
+            }
+          }).observe(document, { childList: true, subtree: true });
+        });
+        const page = await context.newPage();
+        const errors: string[] = [];
+        page.on("pageerror", error => errors.push(error.message));
+        await page.goto("/browse/smb/demo");
+        await page.getByRole("button", { name: "Later", exact: true }).click();
+        await page.getByRole("button", { name: DEMO_PATH, exact: true }).or(page.getByRole("button", { name: `File: ${DEMO_PATH}`, exact: true })).click();
+        await enterMarkdownEditMode(page);
+        const editor = page.getByRole("textbox", { name: "Markdown editor" });
+        await editor.click();
+        await page.keyboard.press("Control+h");
+        const controls = page.getByRole("search");
+        if (regexp) await controls.getByRole("button", { name: "Use regular expression", exact: true }).click();
+        const find = controls.getByRole("textbox", { name: "Find", exact: true });
+        const replace = controls.getByRole("textbox", { name: "Replace", exact: true });
+        await find.fill("tail");
+        await replace.fill("done");
+        await expect(controls.getByText(/^[01] \/ 1$/)).toBeVisible();
+        await page.mouse.move(0, 0);
+        await controls.getByRole("button", { name: "Replace all", exact: true }).click();
+        await expect(page.getByLabel("Unsaved changes", { exact: true })).toBeVisible();
+        expect(await page.evaluate(() => (window as typeof window & { replacementFeedbackProbe: ReplacementFeedbackProbe }).replacementFeedbackProbe.additions)).toBe(0);
+        await editor.focus();
+        await page.keyboard.press("Control+z");
+        await expect(page.getByLabel("Unsaved changes", { exact: true })).toHaveCount(0);
+        await find.fill("abc 123");
+        await replace.fill(replacement);
+        await expect(controls.getByText(`0 / ${DENSE_SYNTAX_LINE_COUNT}`, { exact: true })).toBeVisible();
+        await page.evaluate(() => { (window as typeof window & { replacementFeedbackProbe: ReplacementFeedbackProbe }).replacementFeedbackProbe.hold = true; });
+        if (regexp) { await replace.focus(); await replace.press("Control+Alt+Enter"); }
+        else await controls.getByRole("button", { name: "Replace all", exact: true }).click();
+        const feedback = page.locator(".sambee-source-replacement-feedback");
+        await expect(feedback).toBeVisible();
+        await expect(feedback).toHaveAttribute("role", "status");
+        await expect(editor).toHaveAttribute("aria-busy", "true");
+        await expect.poll(() => page.evaluate(() => (window as typeof window & { replacementFeedbackProbe: ReplacementFeedbackProbe }).replacementFeedbackProbe.frames.length)).toBeGreaterThan(0);
+        await testInfo.attach("replacement-feedback.png", { body: await page.screenshot(), contentType: "image/png" });
+        const frames = await page.evaluate(() => (window as typeof window & { replacementFeedbackProbe: ReplacementFeedbackProbe }).replacementFeedbackProbe.frames);
+        expect(frames.every(frame => frame.width > 0 && frame.height > 0 && frame.original && frame.animation === "running")).toBe(true);
+        await page.evaluate(() => (window as typeof window & { replacementFeedbackProbe: ReplacementFeedbackProbe }).replacementFeedbackProbe.release());
+        await expect(page.getByLabel("Unsaved changes", { exact: true })).toBeVisible();
+        await expect(feedback).toHaveCount(0);
+        await expect(editor).not.toHaveAttribute("aria-busy");
+        await editor.focus();
+        await page.keyboard.press("Control+z");
+        await expect(page.getByLabel("Unsaved changes", { exact: true })).toHaveCount(0);
+        await page.keyboard.press("Control+Shift+Z");
+        await expect(page.getByLabel("Unsaved changes", { exact: true })).toBeVisible();
+        await controls.getByRole("button", { name: "Close", exact: true }).click();
+        await page.getByRole("button", { name: "Save", exact: true }).click();
+        await expect.poll(() => proxy.uploads.length).toBe(1);
+        const upload = proxy.uploads[0];
+        const form = await new Response(upload.body, { headers: { "Content-Type": upload.contentType } }).formData();
+        const files = [...form.values()].filter((value): value is File => typeof value !== "string");
+        expect(files).toHaveLength(1);
+        expect(await files[0].text()).toBe(expected);
+        await page.getByRole("button", { name: "Close", exact: true }).click();
+        await expect(editor).toHaveCount(0);
+        await expect(feedback).toHaveCount(0);
+        expect(errors).toEqual([]);
+        expect(proxy.errors).toEqual([]);
+        await testInfo.attach("replacement-feedback", { contentType: "application/json", body: JSON.stringify({ width, regexp, frames, exactSaveUnits: expected.length, policy: "Functional feedback/paint and atomic-history check with held animation frames; not timing acceptance." }) });
+      } finally {
+        await context?.close();
+        await proxy.close();
+      }
+    });
+  }
+}
+
+for (const width of [1543, 390]) {
+  for (const fixture of ["dense", "long-line"] as const) {
+    for (const expansion of [false, true]) {
+    test(`production source ${expansion ? "dense expansion" : "responsiveness"} ${fixture} at ${width}px`, async ({ browser }, testInfo) => {
+      test.skip(process.env.SAMBEE_E2E_PRODUCTION !== "1", "Requires the normal production build");
+      const profiling = process.env.SAMBEE_E2E_TRACE === "1";
+      const memoryMode = process.env.SAMBEE_E2E_MEMORY === "1";
+      const diagnostic = profiling || memoryMode;
+      test.skip(diagnostic && testInfo.project.name !== "chromium", "Source memory/CPU diagnostics require Chromium CDP");
+      if ((memoryMode && profiling) || (diagnostic && process.env.SAMBEE_E2E_BUDGETS === "1")) throw new Error("Source timing, GC and tracing must run separately");
+      const initialMarkdown = `abc 123;${fixture === "dense" ? "\n" : " "}`.repeat(DENSE_SYNTAX_LINE_COUNT);
+      const replacement = expansion ? "x".repeat(DENSE_EXPANSION_REPLACEMENT_UNITS) : "replaced-$1";
+      const expectedMarkdown = initialMarkdown.replace(/abc (123)/g, replacement);
+      if (expansion) {
+        expect(initialMarkdown).toHaveLength(54_000);
+        expect(expectedMarkdown).toHaveLength(DENSE_EXPANSION_OUTPUT_UNITS);
+      }
+      const proxy = await createCacheableViewerProxy({ initialMarkdown, wordWrapEnabled: false });
+      let context: BrowserContext | undefined;
+      try {
+        context = await browser.newContext({ viewport: { width, height: 900 }, serviceWorkers: "block", proxy: { server: proxy.url, bypass: "<-loopback>" } });
+        await context.addInitScript(() => {
+          const probe: SourceResponsivenessProbe = { measures: [], jobs: [], timerGaps: [], completionMs: null, stop: () => {} };
+          (window as typeof window & { sourceResponsivenessProbe: SourceResponsivenessProbe }).sourceResponsivenessProbe = probe;
+          const NativeWorker = window.Worker;
+          window.Worker = class extends NativeWorker {
+            private job: SourceResponsivenessProbe["jobs"][number];
+            constructor(url: string | URL, options?: WorkerOptions) {
+              super(url, options);
+              this.job = { url: String(url), ranges: 0, rangeBatches: 0, changeChunks: 0, changeUnits: 0, maximumChunkUnits: 0, terminated: false };
+              probe.jobs.push(this.job);
+              this.addEventListener("message", event => {
+                const message = event.data;
+                if (message?.type === "ranges") { this.job.ranges += message.ranges.length; this.job.rangeBatches += 1; }
+                if (message?.type === "change") { this.job.changeChunks += 1; this.job.changeUnits += message.insert.length; this.job.maximumChunkUnits = Math.max(this.job.maximumChunkUnits, message.insert.length); }
+              });
+            }
+            terminate() { this.job.terminated = true; super.terminate(); }
+          };
+          let commandStart: number | undefined;
+          let previousTick: number | undefined;
+          const timer = window.setInterval(() => {
+            if (commandStart === undefined || probe.completionMs !== null) return;
+            const now = performance.now();
+            if (previousTick !== undefined) probe.timerGaps.push(now - previousTick);
+            previousTick = now;
+          }, 0);
+          document.addEventListener("click", event => {
+            if (!(event.target instanceof Element) || !event.target.closest('button[aria-label="Replace all"]')) return;
+            commandStart = performance.now();
+            previousTick = commandStart;
+          }, true);
+          const observer = new PerformanceObserver(list => {
+            for (const entry of list.getEntries()) {
+              if (!entry.name.startsWith("sambee:source-")) continue;
+              const measure = entry as PerformanceMeasure;
+              probe.measures.push({ name: measure.name, startTime: measure.startTime, duration: measure.duration, detail: measure.detail });
+              if (measure.name === "sambee:source-search:commit" && measure.detail.operation === "replace-all") {
+                const start = commandStart;
+                if (start === undefined) continue;
+                const observeParentUpdate = () => {
+                  if (!document.querySelector('[role="status"][aria-label="Unsaved changes"]')) {
+                    requestAnimationFrame(observeParentUpdate);
+                    return;
+                  }
+                  requestAnimationFrame(() => requestAnimationFrame(() => { probe.completionMs = performance.now() - start; }));
+                };
+                requestAnimationFrame(observeParentUpdate);
+              }
+            }
+          });
+          observer.observe({ type: "measure" });
+          probe.stop = () => { observer.disconnect(); clearInterval(timer); };
+        });
+        const page = await context.newPage();
+        await page.goto("/browse/smb/demo");
+        await page.getByRole("button", { name: "Later", exact: true }).click();
+        const memorySession = memoryMode ? await context.newCDPSession(page) : undefined;
+        const memorySamples: { stage: string; usedSize: number; totalSize: number }[] = [];
+        const sampleMemory = async (stage: string) => {
+          if (!memorySession) return;
+          await memorySession.send("HeapProfiler.collectGarbage");
+          const heap = await memorySession.send("Runtime.getHeapUsage");
+          memorySamples.push({ stage, usedSize: heap.usedSize, totalSize: heap.totalSize });
+        };
+        await sampleMemory("pre-open");
+        await page.getByRole("button", { name: DEMO_PATH, exact: true }).or(page.getByRole("button", { name: `File: ${DEMO_PATH}`, exact: true })).click();
+        await enterMarkdownEditMode(page);
+        const editor = page.getByRole("textbox", { name: "Markdown editor" });
+        await editor.click();
+        await page.keyboard.press("Control+h");
+        const search = page.getByRole("search");
+        await search.getByRole("button", { name: "Use regular expression", exact: true }).click();
+        await search.getByRole("textbox", { name: "Find", exact: true }).fill("abc (123)");
+        await search.getByRole("textbox", { name: "Replace", exact: true }).fill(replacement);
+        await expect(search.getByText(`0 / ${DENSE_SYNTAX_LINE_COUNT}`, { exact: true })).toBeVisible();
+        await sampleMemory("counted-results");
+        await page.mouse.move(0, 0);
+        await expect(page.getByRole("tooltip")).toHaveCount(0);
+        const profiler = profiling ? await context.newCDPSession(page) : undefined;
+        if (profiler) {
+          await profiler.send("Profiler.enable");
+          await profiler.send("Profiler.start");
+        }
+        await search.getByRole("button", { name: "Replace all", exact: true }).click();
+        await page.waitForFunction(() => (window as typeof window & { sourceResponsivenessProbe: SourceResponsivenessProbe }).sourceResponsivenessProbe.completionMs !== null);
+        await expect(search.getByText("0 / 0", { exact: true })).toBeVisible();
+        await expect(page.getByRole("button", { name: "Save", exact: true })).toBeEnabled();
+        await sampleMemory("post-replacement");
+        const evidence = await page.evaluate(() => {
+          const probe = (window as typeof window & { sourceResponsivenessProbe: SourceResponsivenessProbe }).sourceResponsivenessProbe;
+          probe.stop();
+          return { measures: probe.measures, jobs: probe.jobs, completionMs: probe.completionMs, maximumTimerGap: probe.timerGaps.length ? Math.max(...probe.timerGaps) : null };
+        });
+        if (profiler) {
+          const profile = await profiler.send("Profiler.stop");
+          await testInfo.attach("source-dispatch-cpu-profile", { contentType: "application/json", body: JSON.stringify(profile) });
+          await profiler.detach();
+        }
+        const commit = evidence.measures.filter(entry => entry.name === "sambee:source-search:commit" && entry.detail.operation === "replace-all");
+        const serialization = evidence.measures.filter(entry => entry.name === "sambee:source-editor:serialize");
+        const publication = evidence.measures.filter(entry => entry.name === "sambee:source-editor:publish");
+        const budgets = evaluateSourceResponsivenessBudgets({ atomicCommit: commit[0]?.duration, serialization: serialization[0]?.duration, synchronousPublication: publication[0]?.duration, maximumTimerGap: evidence.maximumTimerGap }, diagnostic);
+        await testInfo.attach("source-responsiveness", { contentType: "application/json", body: JSON.stringify({ fixture, width, engine: testInfo.project.name, trial: testInfo.repeatEachIndex, operation: expansion ? "dense-expansion" : "original", surface: "markdown-source", cacheState: "fresh-context/fresh-workers", sourceUnits: initialMarkdown.length, outputUnits: expectedMarkdown.length, evidence, budgets, enforced: process.env.SAMBEE_E2E_BUDGETS === "1", command: `SAMBEE_E2E_PRODUCTION=1 SAMBEE_E2E_BUDGETS=1 npm run test:e2e:all -- --grep 'production source ${expansion ? "dense expansion" : "responsiveness"}' --workers=1 --repeat-each=3 --reporter=json`, limitations: ["Two animation frames are a scheduling proxy, not hardware paint or isolated React CPU", "Transfer counts are not retained/peak heap measurements", "Synchronous publication includes normalization and the parent callback, not deferred React work"] }) });
+        expect(commit).toHaveLength(1);
+        expect(serialization).toHaveLength(1);
+        expect(publication).toHaveLength(1);
+        expect(evidence.measures.filter(entry => entry.name === "sambee:source-editor:normalize")).toHaveLength(1);
+        expect(evidence.measures.filter(entry => entry.name === "sambee:source-editor:parent-update")).toHaveLength(1);
+        expect(budgets.metrics.filter(metric => metric.status === "invalid")).toEqual([]);
+        expect(commit[0].detail).toMatchObject({ documentUnits: initialMarkdown.length, changes: DENSE_SYNTAX_LINE_COUNT });
+        expect(serialization[0].detail.documentUnits).toBe(expectedMarkdown.length);
+        expect(evidence.jobs.some(job => job.ranges === DENSE_SYNTAX_LINE_COUNT && job.rangeBatches > 1)).toBe(true);
+        const replacementJobs = evidence.jobs.filter(job => job.changeChunks > 0);
+        expect(replacementJobs).toHaveLength(1);
+        expect(replacementJobs[0].changeUnits).toBe((expansion ? DENSE_EXPANSION_REPLACEMENT_UNITS : "replaced-123".length) * DENSE_SYNTAX_LINE_COUNT);
+        expect(replacementJobs[0].maximumChunkUnits).toBeLessThanOrEqual(SOURCE_SEARCH_CHUNK_UNITS);
+        await search.getByRole("button", { name: "Close", exact: true }).click();
+        await editor.focus();
+        await page.keyboard.press("Control+z");
+        await expect(page.getByLabel("Unsaved changes", { exact: true })).toHaveCount(0);
+        await page.keyboard.press("Control+h");
+        await search.getByRole("textbox", { name: "Find", exact: true }).fill("abc (123)");
+        await expect(search.getByText(`0 / ${DENSE_SYNTAX_LINE_COUNT}`, { exact: true })).toBeVisible();
+        await search.getByRole("button", { name: "Close", exact: true }).click();
+        await editor.focus();
+        await page.keyboard.press("Control+Shift+z");
+        await expect(page.getByLabel("Unsaved changes", { exact: true })).toBeVisible();
+        await page.getByRole("button", { name: "Save", exact: true }).click();
+        await expect.poll(() => proxy.uploads.length).toBe(1);
+        const upload = proxy.uploads[0];
+        const form = await new Response(upload.body, { headers: { "Content-Type": upload.contentType } }).formData();
+        const files = [...form.values()].filter((value): value is File => typeof value !== "string");
+        expect(files).toHaveLength(1);
+        expect(await files[0].text()).toBe(expectedMarkdown);
+        await page.getByRole("button", { name: "Close", exact: true }).click();
+        await expect(page.getByRole("textbox", { name: "Markdown editor" })).toHaveCount(0);
+        await expect.poll(() => page.evaluate(() => (window as typeof window & { sourceResponsivenessProbe: SourceResponsivenessProbe }).sourceResponsivenessProbe.jobs.filter(job => !job.terminated).length)).toBe(0);
+        await sampleMemory("post-close");
+        if (memorySession) {
+          const loadedRendererHeapCeilingBytes = 64 * 1024 * 1024;
+          await testInfo.attach("source-renderer-memory", { contentType: "application/json", body: JSON.stringify({ fixture, width, browserVersion: browser.version(), method: "Chromium CDP Runtime.getHeapUsage after HeapProfiler.collectGarbage at named boundaries", samples: memorySamples, loadedRendererHeapCeilingBytes, limitations: ["Observed post-GC renderer heap, not peak/worker/native/private-process memory", "Counted-results includes the whole loaded viewer, not isolated match-range bytes", "One close isn't six warmed close/reopen growth acceptance"] }) });
+          expect(memorySamples.map(sample => sample.stage)).toEqual(["pre-open", "counted-results", "post-replacement", "post-close"]);
+          for (const sample of memorySamples) expect(Number.isFinite(sample.usedSize) && sample.usedSize > 0).toBe(true);
+          for (const sample of memorySamples.filter(sample => sample.stage === "counted-results" || sample.stage === "post-replacement")) expect(sample.usedSize).toBeLessThanOrEqual(loadedRendererHeapCeilingBytes);
+          await memorySession.detach();
+        }
+        expect(proxy.errors).toEqual([]);
+        if (process.env.SAMBEE_E2E_BUDGETS === "1") expect(budgets.status, JSON.stringify(budgets)).toBe("pass");
+      } finally {
+        await context?.close();
+        await proxy.close();
+      }
+    });
+    }
+  }
+}
+
+for (const width of [1543, 390]) {
+  for (const fixture of TABLE_EDIT_CASES) {
+    test(`production large table editing ${fixture.name} at ${width}px`, async ({ browser }, testInfo) => {
+      test.skip(process.env.SAMBEE_E2E_PRODUCTION !== "1", "Requires the normal production build");
+      const profiling = process.env.SAMBEE_E2E_TRACE === "1";
+      if (process.env.SAMBEE_E2E_MEMORY === "1" || (profiling && process.env.SAMBEE_E2E_BUDGETS === "1")) throw new Error("Table editing timing must run separately from GC and profiling");
+      if (profiling && testInfo.project.name !== "chromium" && (process.env.MOZ_PROFILER_STARTUP !== "1" || !process.env.MOZ_PROFILER_SHUTDOWN)) throw new Error("Firefox table diagnostics require native startup profiling and a shutdown profile path");
+      const startedAt = performance.now();
+      const lifecycle: { stage: string; elapsedMs: number }[] = [];
+      const recordStage = (stage: string) => lifecycle.push({ stage, elapsedMs: performance.now() - startedAt });
+      const pageErrors: string[] = [];
+      const rows = Array.from({ length: TABLE_ENVELOPE_ROWS }, (_, index) => `| ${index + 1} | row ${index + 1} needle |`);
+      const source = `| Key | Value |\n| --- | --- |\n${rows.join("\n")}\n`;
+      const cellWidth = Math.max(String(TABLE_ENVELOPE_ROWS).length, String(fixture.row).length + (fixture.action === "line-break" ? "<br>".length : 0) + TABLE_EDIT_PAYLOAD.length);
+      const valueWidth = `row ${TABLE_ENVELOPE_ROWS} needle`.length;
+      const expectedRows = rows.map((_, index) => {
+        const value = `${index + 1}${index + 1 === fixture.row ? `${fixture.action === "line-break" ? "<br>" : ""}${TABLE_EDIT_PAYLOAD}` : ""}`;
+        return `| ${value.padEnd(cellWidth)} | ${`row ${index + 1} needle`.padEnd(valueWidth)} |`;
+      });
+      const expected = `\n| ${"Key".padEnd(cellWidth)} | ${"Value".padEnd(valueWidth)} |\n| ${"-".repeat(cellWidth)} | ${"-".repeat(valueWidth)} |\n${expectedRows.join("\n")}\n`.replace("<br>", "<br />");
+      const proxy = await createCacheableViewerProxy({ initialMarkdown: source });
+      let context: BrowserContext | undefined;
+      try {
+        context = await browser.newContext({ viewport: { width, height: 900 }, serviceWorkers: "block", proxy: { server: proxy.url, bypass: "<-loopback>" } });
+        const page = await context.newPage();
+        page.on("pageerror", error => pageErrors.push(error.stack ?? error.message));
+        const markPhase = async (phase: string) => {
+          if (profiling) await page.evaluate(name => performance.mark(`sambee:table-phase:${name}`), phase);
+        };
+        await page.goto("/browse/smb/demo");
+        await page.getByRole("button", { name: "Later", exact: true }).click();
+        await page.getByRole("button", { name: DEMO_PATH, exact: true }).or(page.getByRole("button", { name: `File: ${DEMO_PATH}`, exact: true })).click();
+        await enterMarkdownEditModeWithTable(page);
+        await expect(page.locator(".tbl-data-cell")).toHaveCount(TABLE_ENVELOPE_ROWS * 2);
+        const cell = page.locator(".tbl-data-cell .tbl-cell-view").nth((fixture.row - 1) * 2);
+        const nested = await activateCellEditor(cell);
+        await expect(nested).toHaveText(String(fixture.row));
+        await page.keyboard.press("End");
+        recordStage("cell-ready");
+        await page.evaluate(() => {
+          const probe = { content: document.activeElement, measures: [] as { name: string; duration: number; startTime: number; detail: unknown }[], inputs: [] as number[], gaps: [] as number[], events: [] as { type: string; phase: string; contentId: number | null; connected: boolean; trusted: boolean; key?: string; data?: string | null; inputType?: string; isComposing?: boolean; text: string | null; nested: boolean; prevented: boolean; activeText: string | null; selectionText: string | null }[], stop: () => {} };
+          (window as typeof window & { tableEditProbe: typeof probe }).tableEditProbe = probe;
+          let previous: number | undefined;
+          const input = () => {
+            const start = performance.now();
+            previous ??= start;
+            requestAnimationFrame(() => requestAnimationFrame(() => probe.inputs.push(performance.now() - start)));
+          };
+          document.addEventListener("beforeinput", input, true);
+          const contentIds = new WeakMap<Element, number>();
+          let nextContentId = 0;
+          const observeInput = (event: Event) => {
+            if (!(event.target instanceof Element) || probe.events.length >= 256) return;
+            const content = event.target.closest(".cm-content");
+            if (content && !contentIds.has(content)) contentIds.set(content, ++nextContentId);
+            const record = (phase: string) => {
+              if (probe.events.length >= 256) return;
+              const selection = document.getSelection();
+              probe.events.push({ type: event.type, phase, contentId: content ? contentIds.get(content) ?? null : null, connected: content?.isConnected ?? false, trusted: event.isTrusted, key: event instanceof KeyboardEvent ? event.key : undefined, data: event instanceof InputEvent || event instanceof CompositionEvent ? event.data : undefined, inputType: event instanceof InputEvent ? event.inputType : undefined, isComposing: event instanceof InputEvent ? event.isComposing : undefined, text: content?.closest(".tbl-cell-editor") ? content.textContent : null, nested: Boolean(content?.closest(".tbl-cell-editor")), prevented: event.defaultPrevented, activeText: document.activeElement?.closest(".tbl-cell-editor")?.textContent ?? null, selectionText: selection?.anchorNode?.textContent ?? null });
+            };
+            record("capture");
+            queueMicrotask(() => record("after-event"));
+          };
+          const eventTypes = ["keydown", "beforeinput", "input", "compositionstart", "compositionend", "focusin", "focusout"];
+          for (const type of eventTypes) document.addEventListener(type, observeInput, true);
+          const timer = setInterval(() => {
+            if (previous === undefined) return;
+            const now = performance.now();
+            probe.gaps.push(now - previous);
+            previous = now;
+          }, 0);
+          const observer = new PerformanceObserver(list => {
+            for (const entry of list.getEntries()) if (entry.name.startsWith("sambee:source-editor:") || entry.name.startsWith("sambee:edit-preparation:")) probe.measures.push({ name: entry.name, duration: entry.duration, startTime: entry.startTime, detail: entry instanceof PerformanceMeasure ? entry.detail : null });
+          });
+          observer.observe({ type: "measure" });
+          probe.stop = () => { observer.disconnect(); clearInterval(timer); document.removeEventListener("beforeinput", input, true); for (const type of eventTypes) document.removeEventListener(type, observeInput, true); };
+        });
+        await captureViewerScheduling(page, testInfo, async () => {
+        await markPhase("typing-start");
+        let compositionMethod: string | null = null;
+        const composing = fixture.action === "composition" || fixture.action === "composition-close";
+        const saveOnClose = fixture.action === "close" || fixture.action === "composition-close";
+          if (fixture.action === "line-break") await page.keyboard.press("Shift+Enter");
+          if (composing && testInfo.project.name === "chromium") {
+            compositionMethod = "Chromium CDP composition and commit with untrusted composition-end event; not physical IME";
+            const session = await context.newCDPSession(page);
+            try {
+              await session.send("Input.imeSetComposition", { text: TABLE_EDIT_PAYLOAD, selectionStart: TABLE_EDIT_PAYLOAD.length, selectionEnd: TABLE_EDIT_PAYLOAD.length });
+              await session.send("Input.insertText", { text: TABLE_EDIT_PAYLOAD });
+            } finally { await session.detach(); }
+          } else if (composing) {
+            compositionMethod = "Firefox browser composition from Playwright text insertion; not physical IME acceptance";
+            await page.keyboard.insertText(TABLE_EDIT_PAYLOAD);
+          } else await page.keyboard.type(TABLE_EDIT_PAYLOAD, { delay: SOURCE_TYPING_KEY_DELAY_MS });
+        recordStage("input-complete");
+        await markPhase("typing-complete");
+        await expect(nested).toBeFocused();
+        await markPhase("save-start");
+        if (saveOnClose) {
+          await page.getByRole("button", { name: "Close", exact: true }).click();
+          await page.getByRole("dialog").filter({ has: page.getByRole("heading", { name: "Unsaved changes", exact: true }) }).getByRole("button", { name: "Save", exact: true }).click();
+        } else await page.getByRole("button", { name: "Save", exact: true }).click();
+        recordStage("save-clicked");
+        await testInfo.attach("large-table-input", { contentType: "application/json", body: JSON.stringify(await page.evaluate(() => (window as typeof window & { tableEditProbe: { events: unknown[] } }).tableEditProbe.events)) });
+        await expect.poll(() => proxy.uploads.length).toBe(1);
+        if (composing) {
+          const compositionEvents = await page.evaluate(() => (window as typeof window & { tableEditProbe: { events: { type: string; trusted: boolean; phase: string; isComposing?: boolean }[] } }).tableEditProbe.events.filter(event => event.phase === "capture"));
+          expect(compositionEvents.some(event => event.type === "compositionstart" && event.trusted)).toBe(true);
+          expect(compositionEvents.some(event => event.type === "beforeinput" && event.isComposing && event.trusted)).toBe(true);
+          expect(compositionEvents.some(event => event.type === "compositionend" && (event.trusted || testInfo.project.name === "chromium")), JSON.stringify(compositionEvents)).toBe(true);
+        }
+        const upload = proxy.uploads[0];
+        const form = await new Response(upload.body, { headers: { "Content-Type": upload.contentType } }).formData();
+        const files = [...form.values()].filter((value): value is File => typeof value !== "string");
+        expect(files).toHaveLength(1);
+        const saved = await files[0].text();
+        await testInfo.attach("large-table-save.txt", { contentType: "text/plain", body: saved });
+        expect(saved === expected, `Exact canonical Save mismatch: expected ${expected.length} units, received ${saved.length}`).toBe(true);
+        recordStage("save-verified");
+        await markPhase("save-verified");
+        const evidence = await page.evaluate(async () => {
+          await new Promise<void>(resolve => requestAnimationFrame(() => requestAnimationFrame(() => resolve())));
+          const probe = (window as typeof window & { tableEditProbe: { content: Element | null; measures: { name: string; duration: number }[]; inputs: number[]; gaps: number[]; stop: () => void } }).tableEditProbe;
+          probe.stop();
+          return { measures: probe.measures, inputs: probe.inputs, gaps: probe.gaps, retainedCell: probe.content?.isConnected ?? false, cellFocused: document.activeElement === probe.content };
+        });
+        const frames = [...evidence.inputs].sort((left, right) => left - right);
+        const maximumStage = (name: string) => { const stages = evidence.measures.filter(entry => entry.name === name); return stages.length ? Math.max(...stages.map(entry => entry.duration)) : null; };
+        const budgets = evaluateSourceTypingBudgets({ keyboardTwoFrameP95: frames[Math.ceil(frames.length * 0.95) - 1], maximumTimerGap: evidence.gaps.length ? Math.max(...evidence.gaps) : null, serialization: maximumStage("sambee:source-editor:serialize"), synchronousPublication: maximumStage("sambee:source-editor:publish") });
+        await testInfo.attach("large-table-editing", { contentType: "application/json", body: JSON.stringify({ fixture: fixture.name, row: fixture.row, rows: TABLE_ENVELOPE_ROWS, width, engine: testInfo.project.name, trial: testInfo.repeatEachIndex, surface: "markdown-table", cacheState: "fresh-context/fresh-workers", sourceUnits: source.length, outputUnits: expected.length, payload: TABLE_EDIT_PAYLOAD, compositionMethod, saveOnClose, evidence, budgets, diagnostic: profiling, enforced: process.env.SAMBEE_E2E_BUDGETS === "1", limitations: ["Beforeinput-to-two-frame scheduling proxy, not physical input/paint", "Final native dispatch is not independently attributed", "Physical IME remains a separate gate"] }) });
+        for (const stage of ["serialize", "publish", "normalize", "parent-update"]) expect(evidence.measures.some(entry => entry.name === `sambee:source-editor:${stage}`)).toBe(true);
+        expect(budgets.metrics.filter(metric => metric.status === "invalid")).toEqual([]);
+        if (!saveOnClose) {
+          expect(evidence.retainedCell).toBe(true);
+          expect(evidence.cellFocused).toBe(true);
+        }
+        if (saveOnClose) await expect(page.getByRole("textbox", { name: "Markdown editor" })).toHaveCount(0);
+        recordStage("before-clean-check");
+        await expect(page.getByLabel("Unsaved changes", { exact: true })).toHaveCount(0);
+        if (fixture.action === "line-break") {
+          const savedCellText = await nested.textContent();
+          const renderedCellText = `${fixture.row}\n${TABLE_EDIT_PAYLOAD}`;
+          await page.keyboard.type("!");
+          await expect(nested).toHaveText(`${savedCellText}!`);
+          await expect(page.getByLabel("Unsaved changes", { exact: true })).toBeVisible();
+          await page.keyboard.press("Control+z");
+          await expect(cell).toHaveText(renderedCellText);
+          await expect(page.getByLabel("Unsaved changes", { exact: true })).toHaveCount(0);
+          await page.keyboard.press("Control+Shift+Z");
+          await expect(cell).toHaveText(`${renderedCellText}!`);
+          await expect(page.getByLabel("Unsaved changes", { exact: true })).toBeVisible();
+          await page.keyboard.press("Control+z");
+          await expect(cell).toHaveText(renderedCellText);
+          await expect(page.getByLabel("Unsaved changes", { exact: true })).toHaveCount(0);
+          recordStage("post-save-history-verified");
+        }
+        recordStage("before-close");
+        await markPhase("close-start");
+        await page.getByRole("button", { name: "Close", exact: true }).click();
+        recordStage("close-clicked");
+        await expect(page.getByRole("textbox", { name: "Markdown editor" })).toHaveCount(0);
+        await expect.poll(() => page.workers().length).toBe(0);
+        recordStage("closed");
+        await markPhase("closed");
+        expect(pageErrors).toEqual([]);
+        expect(proxy.errors).toEqual([]);
+        if (process.env.SAMBEE_E2E_BUDGETS === "1") expect(budgets.status, JSON.stringify(budgets)).toBe("pass");
+        });
+      } finally {
+        await testInfo.attach("large-table-lifecycle", { contentType: "application/json", body: JSON.stringify({ lifecycle, pageErrors }) });
+        await context?.close();
+        await proxy.close();
+      }
+    });
+  }
+}
+
 async function enterMarkdownEditModeWithTable(page: Page): Promise<void> {
   await enterMarkdownEditMode(page);
   await page.locator(".tbl-table-widget").first().waitFor();
diff --git a/frontend/e2e/viewer-performance-budgets.spec.ts b/frontend/e2e/viewer-performance-budgets.spec.ts
new file mode 100644
index 000000000..a1c60e839
--- /dev/null
+++ b/frontend/e2e/viewer-performance-budgets.spec.ts
@@ -0,0 +1,13 @@
+import { expect, test } from "@playwright/test";
+import { readFile } from "node:fs/promises";
+import { evaluateViewerAcceptanceReport, VIEWER_ACCEPTANCE_CASES } from "./viewer-performance-budgets";
+
+if (process.env.SAMBEE_E2E_REPORT) {
+  test("recorded viewer acceptance report is complete and passing", async () => {
+    const slice = process.env.SAMBEE_E2E_SLICE as keyof typeof VIEWER_ACCEPTANCE_CASES;
+    expect(Object.keys(VIEWER_ACCEPTANCE_CASES)).toContain(slice);
+    const report = JSON.parse(await readFile(process.env.SAMBEE_E2E_REPORT!, "utf8"));
+    const coverage = evaluateViewerAcceptanceReport(slice, report);
+    expect(coverage.status, JSON.stringify(coverage)).toBe("pass");
+  });
+}
diff --git a/frontend/e2e/viewer-performance-budgets.ts b/frontend/e2e/viewer-performance-budgets.ts
new file mode 100644
index 000000000..f55d7a2c0
--- /dev/null
+++ b/frontend/e2e/viewer-performance-budgets.ts
@@ -0,0 +1,189 @@
+export const VIEWER_TIMING_TARGETS_MS = {
+  documentCompletion: 1_500,
+  firstExactSearch: 1_000,
+  changedQuery: 100,
+  lastMatchNavigation: 100,
+  maximumTimerGap: 50,
+} as const;
+
+export type ViewerTimingMetric = keyof typeof VIEWER_TIMING_TARGETS_MS;
+export type ViewerTimingSamples = Partial<Record<ViewerTimingMetric, number | null>>;
+
+export interface ViewerAcceptanceSample {
+  identity: string;
+  status: string;
+  retry: number;
+}
+
+export function evaluateViewerAcceptanceCoverage(expected: readonly string[], samples: readonly ViewerAcceptanceSample[]) {
+  const expectedIdentities = new Set(expected);
+  const observed = new Map<string, ViewerAcceptanceSample[]>();
+  for (const sample of samples) {
+    const entries = observed.get(sample.identity) ?? [];
+    entries.push(sample);
+    observed.set(sample.identity, entries);
+  }
+  const missing = expected.filter(identity => !observed.has(identity));
+  const unexpected = [...observed.keys()].filter(identity => !expectedIdentities.has(identity));
+  const duplicate = [...observed].filter(([, entries]) => entries.length !== 1).map(([identity]) => identity);
+  const invalid = samples.filter(sample => sample.status !== "pass" || sample.retry !== 0).map(sample => sample.identity);
+  const validExpectation = expected.length > 0 && expectedIdentities.size === expected.length;
+  return {
+    status: validExpectation && !missing.length && !unexpected.length && !duplicate.length && !invalid.length ? "pass" : "fail",
+    expectedCount: expected.length,
+    observedCount: samples.length,
+    validExpectation,
+    missing,
+    unexpected,
+    duplicate,
+    invalid,
+  };
+}
+
+const ACCEPTANCE_WIDTHS = [1543, 390] as const;
+const ACCEPTANCE_ENGINES = ["chromium", "firefox"] as const;
+const PUBLICATION_FIXTURES = ["dense", "near-safeguard", "host-envelope", "many-blocks", "long-line"] as const;
+const sourceCases = (operation: string) => ACCEPTANCE_WIDTHS.flatMap(width => ["dense", "long-line"].map(fixture => `production source ${operation} ${fixture} at ${width}px`));
+
+export const VIEWER_ACCEPTANCE_CASES = {
+  "source-responsiveness": sourceCases("responsiveness"),
+  "dense-expansion": sourceCases("dense expansion"),
+  "source-typing": sourceCases("typing"),
+  "prose-table": ACCEPTANCE_WIDTHS.flatMap(width => ["prose", "table"].map(fixture => `production prose table responsiveness ${fixture} at ${width}px`)),
+  "table-editing": ACCEPTANCE_WIDTHS.flatMap(width => ["first", "middle", "last", "line-break", "composition", "close-flush", "composition-close"].map(fixture => `production large table editing ${fixture} at ${width}px`)),
+  publication: ACCEPTANCE_WIDTHS.flatMap(width => PUBLICATION_FIXTURES.map(fixture => `production syntax publication / ${fixture} at ${width}px preserves active search and selection`)),
+  readiness: ACCEPTANCE_WIDTHS.flatMap(width => PUBLICATION_FIXTURES.map(fixture => `production syntax readiness / unheld ${fixture} readiness at ${width}px`)),
+  "readiness-http-cache": ACCEPTANCE_WIDTHS.flatMap(width => PUBLICATION_FIXTURES.map(fixture => `production syntax readiness / unheld ${fixture} readiness at ${width}px`)),
+} as const;
+
+interface ViewerReportSuite {
+  title: string;
+  suites?: ViewerReportSuite[];
+  specs?: {
+    title: string;
+    tests: {
+      projectName: string;
+      repeatEachIndex?: number;
+      status: string;
+      results: { status: string; retry: number; attachments?: { name: string; body?: string }[] }[];
+    }[];
+  }[];
+}
+
+export function evaluateViewerAcceptanceReport(slice: keyof typeof VIEWER_ACCEPTANCE_CASES, report: { suites: ViewerReportSuite[]; errors?: unknown[] }) {
+  const trials = 3;
+  const titles = VIEWER_ACCEPTANCE_CASES[slice];
+  const identity = (title: string, engine: string, trial: number) => JSON.stringify([title, engine, trial]);
+  const expected = titles.flatMap(title => ACCEPTANCE_ENGINES.flatMap(engine => Array.from({ length: trials }, (_, trial) => identity(title, engine, trial))));
+  const samples: ViewerAcceptanceSample[] = [];
+  const visit = (suite: ViewerReportSuite, parents: string[]) => {
+    for (const spec of suite.specs ?? []) {
+      const title = [...parents, spec.title].join(" / ");
+      for (const test of spec.tests) {
+        for (const result of test.results) {
+          const attachments = result.attachments ?? [];
+          const readiness = slice === "readiness" || slice === "readiness-http-cache";
+          const name = slice === "publication" ? "viewer-timing-budgets.json" : readiness ? "syntax-readiness.json" : slice === "source-typing" ? "source-typing" : slice === "prose-table" ? "prose-table-responsiveness" : slice === "table-editing" ? "large-table-editing" : "source-responsiveness";
+          const evidence = attachments.filter(attachment => attachment.name === name);
+          let validEvidence = evidence.length === (slice === "readiness-http-cache" ? 2 : 1);
+          const cacheStates: string[] = [];
+          let trial = test.repeatEachIndex;
+          for (const attachment of evidence) {
+            try {
+              const measurement = JSON.parse(Buffer.from(attachment.body ?? "", "base64").toString("utf8"));
+              trial ??= measurement.trial;
+              validEvidence &&= Number.isInteger(trial) && (measurement.trial === undefined || measurement.trial === trial);
+              const budget = measurement.budgets ?? measurement.budget ?? measurement;
+              let computed: { status: string };
+              if (readiness) {
+                computed = evaluateViewerReadinessBudgets(measurement.metrics ?? {});
+                cacheStates.push(measurement.cacheState);
+              } else if (slice === "prose-table") {
+                computed = evaluateTimingMetrics({ documentCompletion: VIEWER_TIMING_TARGETS_MS.documentCompletion, maximumTimerGap: VIEWER_TIMING_TARGETS_MS.maximumTimerGap }, measurement.load ?? {}, false);
+              } else {
+                const values: Record<string, number | null> = {};
+                const metrics = budget.metrics ?? [];
+                for (const metric of metrics) values[metric.metric] = metric.observedMs;
+                computed = slice === "publication" ? evaluateViewerTimingBudgets(values) : slice === "source-typing" || slice === "table-editing" ? evaluateSourceTypingBudgets(values) : evaluateSourceResponsivenessBudgets(values);
+                validEvidence &&= metrics.length === Object.keys(values).length;
+              }
+              validEvidence &&= measurement.enforced === true && budget.status === "pass" && computed.status === "pass";
+            } catch { validEvidence = false; }
+          }
+          if (readiness) validEvidence &&= JSON.stringify(cacheStates.sort()) === JSON.stringify(slice === "readiness-http-cache" ? ["cold", "warm-http-fresh-workers"] : ["routed-no-cache"]);
+          samples.push({ identity: identity(title, test.projectName, trial ?? -1), retry: result.retry, status: result.status === "passed" && test.status === "expected" && validEvidence ? "pass" : "invalid" });
+        }
+      }
+    }
+    for (const child of suite.suites ?? []) visit(child, [...parents, child.title]);
+  };
+  for (const suite of report.suites) visit(suite, []);
+  const coverage = evaluateViewerAcceptanceCoverage(expected, samples);
+  return { ...coverage, status: !report.errors?.length ? coverage.status : "fail", slice };
+}
+
+export const VIEWER_READINESS_TARGETS_MS = {
+  firstUsableText: 1_500,
+  firstVisibleSyntax: 1_500,
+  fullSyntaxPreparation: 3_000,
+} as const;
+
+export type ViewerReadinessMetric = keyof typeof VIEWER_READINESS_TARGETS_MS;
+export type ViewerReadinessSamples = Partial<Record<ViewerReadinessMetric, number | null>>;
+
+export const SOURCE_RESPONSIVENESS_TARGETS_MS = {
+  atomicCommit: 50,
+  serialization: 50,
+  synchronousPublication: 50,
+  maximumTimerGap: 50,
+} as const;
+
+export type SourceResponsivenessSamples = Partial<Record<keyof typeof SOURCE_RESPONSIVENESS_TARGETS_MS, number | null>>;
+
+export function evaluateSourceResponsivenessBudgets(samples: SourceResponsivenessSamples, diagnostic = false) {
+  return evaluateTimingMetrics(SOURCE_RESPONSIVENESS_TARGETS_MS, samples, diagnostic);
+}
+
+export const SOURCE_TYPING_TARGETS_MS = {
+  keyboardTwoFrameP95: 50,
+  maximumTimerGap: 50,
+  serialization: 50,
+  synchronousPublication: 50,
+} as const;
+
+export type SourceTypingSamples = Partial<Record<keyof typeof SOURCE_TYPING_TARGETS_MS, number | null>>;
+
+export function evaluateSourceTypingBudgets(samples: SourceTypingSamples) {
+  return evaluateTimingMetrics(SOURCE_TYPING_TARGETS_MS, samples, false, ["keyboardTwoFrameP95"]);
+}
+
+function evaluateTimingMetrics<Metric extends string>(targets: Record<Metric, number>, samples: Partial<Record<Metric, number | null>>, diagnostic: boolean, exclusive: readonly Metric[] = []) {
+  const metrics = (Object.entries(targets) as [Metric, number][]).map(([metric, targetMs]) => {
+    const observedMs = samples[metric];
+    const valid = typeof observedMs === "number" && Number.isFinite(observedMs) && observedMs >= 0;
+    const status = !valid ? "invalid" : observedMs > targetMs || (observedMs === targetMs && exclusive.includes(metric)) ? "fail" : "pass";
+    return { metric, targetMs, observedMs: valid ? observedMs : null, status };
+  });
+  return {
+    status: diagnostic ? "diagnostic" : metrics.every((metric) => metric.status === "pass") ? "pass" : "fail",
+    metrics,
+  };
+}
+
+export function evaluateViewerReadinessBudgets(samples: ViewerReadinessSamples, diagnostic = false) {
+  return evaluateTimingMetrics(VIEWER_READINESS_TARGETS_MS, samples, diagnostic);
+}
+
+export function evaluateViewerTimingBudgets(samples: ViewerTimingSamples, diagnostic = false) {
+  return {
+    ...evaluateTimingMetrics(VIEWER_TIMING_TARGETS_MS, samples, diagnostic),
+    openCriteria: [
+      "Actual hardware input-to-visible-response latency",
+      "Application-owned blocking work attribution and scrolling refresh-rate acceptance",
+      "First usable text and visible syntax completion budgets",
+      "Controlled renderer heap, six-cycle shutdown growth and aggregate worker/native memory",
+      "Fresh/cached grammar isolation, large prose/tables, source typing and dense replacement",
+      "Native Find, OS clipboard, assistive technology, printing and physical-device acceptance",
+    ],
+  };
+}
diff --git a/frontend/package-lock.json b/frontend/package-lock.json
index d19ff0a22..4c8d9d97b 100644
--- a/frontend/package-lock.json
+++ b/frontend/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "sambee-frontend",
-  "version": "2.0.13",
+  "version": "2.0.14",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "sambee-frontend",
-      "version": "2.0.13",
+      "version": "2.0.14",
       "hasInstallScript": true,
       "dependencies": {
         "@codemirror/autocomplete": "^6.20.3",
@@ -19,6 +19,7 @@
         "@codemirror/view": "^6.43.14",
         "@emotion/react": "^11.11.1",
         "@emotion/styled": "^11.11.0",
+        "@lezer/highlight": "^1.2.3",
         "@mui/icons-material": "^9.5.0",
         "@mui/material": "^9.1.2",
         "@react-spring/web": "^10.1.2",
@@ -27,7 +28,6 @@
         "axios": "1.20.0",
         "codemirror": "^6.0.2",
         "codemirror-markdown-tables": "^1.0.1",
-        "highlight.js": "^11.12.0",
         "i18next": "^26.4.7",
         "react": "^19.3.1",
         "react-colorful": "^5.8.1",
@@ -37,9 +37,12 @@
         "react-pdf": "^11.0.0",
         "react-photo-view": "^1.2.7",
         "react-router-dom": "^7.18.4",
-        "rehype-highlight": "^7.0.2",
+        "rehype-slug": "6.0.0",
         "remark-gfm": "^4.0.1",
+        "remark-parse": "^11.0.0",
+        "remark-rehype": "11.1.2",
         "swiper": "^14.3.0",
+        "unified": "^11.0.5",
         "yet-another-react-lightbox": "^3.32.2"
       },
       "devDependencies": {
@@ -48,6 +51,8 @@
         "@testing-library/jest-dom": "^7.0.1",
         "@testing-library/react": "^16.3.3",
         "@testing-library/user-event": "^14.6.8",
+        "@types/hast": "^3.0.4",
+        "@types/mdast": "^4.0.4",
         "@types/node": "^26.6.5",
         "@types/react": "^19.3.0",
         "@types/react-dom": "^19.3.0",
@@ -4071,6 +4076,12 @@
         "node": ">= 0.4"
       }
     },
+    "node_modules/github-slugger": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/github-slugger/-/github-slugger-2.0.0.tgz",
+      "integrity": "sha512-IaOQ9puYtjrkq7Y0Ygl9KDZnrf/aiUJYUpVf89y8kyaxbRG7Y1SrX/jaumrv81vc61+kiMempujsM3Yw7w5qcw==",
+      "license": "ISC"
+    },
     "node_modules/gopd": {
       "version": "1.2.0",
       "resolved": "https://registry.npmjs.org/gopd/-/gopd-1.2.0.tgz",
@@ -4122,10 +4133,10 @@
         "node": ">= 0.4"
       }
     },
-    "node_modules/hast-util-is-element": {
+    "node_modules/hast-util-heading-rank": {
       "version": "3.0.0",
-      "resolved": "https://registry.npmjs.org/hast-util-is-element/-/hast-util-is-element-3.0.0.tgz",
-      "integrity": "sha512-Val9mnv2IWpLbNPqc/pUem+a7Ipj2aHacCwgNfTiK0vJKl0LF+4Ba4+v1oPHFpf3bLYmreq0/l3Gud9S5OH42g==",
+      "resolved": "https://registry.npmjs.org/hast-util-heading-rank/-/hast-util-heading-rank-3.0.0.tgz",
+      "integrity": "sha512-EJKb8oMUXVHcWZTDepnr+WNbfnXKFNf9duMesmr4S8SXTJBJ9M4Yok08pu9vxdJwdlGRhVumk9mEhkEvKGifwA==",
       "license": "MIT",
       "dependencies": {
         "@types/hast": "^3.0.0"
@@ -4162,16 +4173,13 @@
         "url": "https://opencollective.com/unified"
       }
     },
-    "node_modules/hast-util-to-text": {
-      "version": "4.0.2",
-      "resolved": "https://registry.npmjs.org/hast-util-to-text/-/hast-util-to-text-4.0.2.tgz",
-      "integrity": "sha512-KK6y/BN8lbaq654j7JgBydev7wuNMcID54lkRav1P0CaE1e47P72AWWPiGKXTJU271ooYzcvTAn/Zt0REnvc7A==",
+    "node_modules/hast-util-to-string": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/hast-util-to-string/-/hast-util-to-string-3.0.1.tgz",
+      "integrity": "sha512-XelQVTDWvqcl3axRfI0xSeoVKzyIFPwsAGSLIsKdJKQMXDYJS4WYrBNF/8J7RdhIcFI2BOHgAifggsvsxp/3+A==",
       "license": "MIT",
       "dependencies": {
-        "@types/hast": "^3.0.0",
-        "@types/unist": "^3.0.0",
-        "hast-util-is-element": "^3.0.0",
-        "unist-util-find-after": "^5.0.0"
+        "@types/hast": "^3.0.0"
       },
       "funding": {
         "type": "opencollective",
@@ -4202,15 +4210,6 @@
         "set-cookie-parser": "^3.0.1"
       }
     },
-    "node_modules/highlight.js": {
-      "version": "11.12.0",
-      "resolved": "https://registry.npmjs.org/highlight.js/-/highlight.js-11.12.0.tgz",
-      "integrity": "sha512-nbfWpyRMcMrPMmDwJB+dhX/eiaPKtc2RB+0QZskqJ3WjRA/FDS0e9hZrx8EC/lbEv8gXy98FcDbNa/dspAaJMg==",
-      "license": "BSD-3-Clause",
-      "engines": {
-        "node": ">=12.0.0"
-      }
-    },
     "node_modules/hoist-non-react-statics": {
       "version": "3.3.2",
       "resolved": "https://registry.npmjs.org/hoist-non-react-statics/-/hoist-non-react-statics-3.3.2.tgz",
@@ -4774,30 +4773,6 @@
         "loose-envify": "cli.js"
       }
     },
-    "node_modules/lowlight": {
-      "version": "3.3.0",
-      "resolved": "https://registry.npmjs.org/lowlight/-/lowlight-3.3.0.tgz",
-      "integrity": "sha512-0JNhgFoPvP6U6lE/UdVsSq99tn6DhjjpAj5MxG49ewd2mOBVtwWYIT8ClyABhq198aXXODMU6Ox8DrGy/CpTZQ==",
-      "license": "MIT",
-      "dependencies": {
-        "@types/hast": "^3.0.0",
-        "devlop": "^1.0.0",
-        "highlight.js": "~11.11.0"
-      },
-      "funding": {
-        "type": "github",
-        "url": "https://github.com/sponsors/wooorm"
-      }
-    },
-    "node_modules/lowlight/node_modules/highlight.js": {
-      "version": "11.11.2",
-      "resolved": "https://registry.npmjs.org/highlight.js/-/highlight.js-11.11.2.tgz",
-      "integrity": "sha512-oaXMACAU0kzOMXBjWpNcX+vlwSBCIAiZ9BHa7gA15NOTtT2L/l8OSZDuqS2XppOhZBPJ7hm4o8ep2kyuip2uEQ==",
-      "license": "BSD-3-Clause",
-      "engines": {
-        "node": ">=12.0.0"
-      }
-    },
     "node_modules/lru-cache": {
       "version": "11.5.3",
       "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-11.5.3.tgz",
@@ -5328,9 +5303,9 @@
       }
     },
     "node_modules/micromark-extension-gfm-table": {
-      "version": "2.1.1",
-      "resolved": "https://registry.npmjs.org/micromark-extension-gfm-table/-/micromark-extension-gfm-table-2.1.1.tgz",
-      "integrity": "sha512-t2OU/dXXioARrC6yWfJ4hqB7rct14e8f7m0cbI5hUmDyyIlwv5vEtooptH8INkbLzOatzKuVbQmAYcbWoyz6Dg==",
+      "version": "2.1.2",
+      "resolved": "https://registry.npmjs.org/micromark-extension-gfm-table/-/micromark-extension-gfm-table-2.1.2.tgz",
+      "integrity": "sha512-pRzm4kDTu0MjlmBkxmS9yYhw60nncfcEwu9NNdPFSQEFXS95ZKyIIyTSHu/o3ReBUrLKYEq+7YaXCRn/bPB4MA==",
       "license": "MIT",
       "dependencies": {
         "devlop": "^1.0.0",
@@ -6346,17 +6321,17 @@
         "node": ">=8"
       }
     },
-    "node_modules/rehype-highlight": {
-      "version": "7.0.2",
-      "resolved": "https://registry.npmjs.org/rehype-highlight/-/rehype-highlight-7.0.2.tgz",
-      "integrity": "sha512-k158pK7wdC2qL3M5NcZROZ2tR/l7zOzjxXd5VGdcfIyoijjQqpHd3JKtYSBDpDZ38UI2WJWuFAtkMDxmx5kstA==",
+    "node_modules/rehype-slug": {
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/rehype-slug/-/rehype-slug-6.0.0.tgz",
+      "integrity": "sha512-lWyvf/jwu+oS5+hL5eClVd3hNdmwM1kAC0BUvEGD19pajQMIzcNUd/k9GsfQ+FfECvX+JE+e9/btsKH0EjJT6A==",
       "license": "MIT",
       "dependencies": {
         "@types/hast": "^3.0.0",
-        "hast-util-to-text": "^4.0.0",
-        "lowlight": "^3.0.0",
-        "unist-util-visit": "^5.0.0",
-        "vfile": "^6.0.0"
+        "github-slugger": "^2.0.0",
+        "hast-util-heading-rank": "^3.0.0",
+        "hast-util-to-string": "^3.0.0",
+        "unist-util-visit": "^5.0.0"
       },
       "funding": {
         "type": "opencollective",
@@ -6962,20 +6937,6 @@
         "url": "https://opencollective.com/unified"
       }
     },
-    "node_modules/unist-util-find-after": {
-      "version": "5.0.0",
-      "resolved": "https://registry.npmjs.org/unist-util-find-after/-/unist-util-find-after-5.0.0.tgz",
-      "integrity": "sha512-amQa0Ep2m6hE2g72AugUItjbuM8X8cGQnFoHk0pGfrFeT9GZhzN5SW8nRsiGKK7Aif4CrACPENkA6P/Lw6fHGQ==",
-      "license": "MIT",
-      "dependencies": {
-        "@types/unist": "^3.0.0",
-        "unist-util-is": "^6.0.0"
-      },
-      "funding": {
-        "type": "opencollective",
-        "url": "https://opencollective.com/unified"
-      }
-    },
     "node_modules/unist-util-is": {
       "version": "6.0.1",
       "resolved": "https://registry.npmjs.org/unist-util-is/-/unist-util-is-6.0.1.tgz",
diff --git a/frontend/package.json b/frontend/package.json
index bc9f2ceea..adf66409d 100644
--- a/frontend/package.json
+++ b/frontend/package.json
@@ -1,6 +1,6 @@
 {
   "name": "sambee-frontend",
-  "version": "2.0.13",
+  "version": "2.0.14",
   "private": true,
   "type": "module",
   "scripts": {
@@ -10,13 +10,14 @@
     "preinstall": "node scripts/dependency-state.mjs --clear",
     "postinstall": "node scripts/patch-react-transition-group.mjs && npm run prepare:pdfjs-assets && node scripts/dependency-state.mjs --write",
     "check:dependencies": "node scripts/dependency-state.mjs --check",
-    "build": "npm run prepare:pdfjs-assets && tsc && vite build",
+    "typecheck": "tsc -b --noEmit",
+    "build": "npm run typecheck && npm run prepare:pdfjs-assets && vite build",
     "preview": "vite preview",
     "lint": "biome check src",
     "lint:fix": "biome check --write src",
     "format": "biome format --write src",
     "test": "vitest run",
-    "test:ci": "vitest run --maxWorkers=2",
+    "test:ci": "node scripts/run-tests-ci.mjs",
     "test:stable": "node scripts/run-tests-stable.mjs",
     "test:watch": "vitest",
     "test:ui": "vitest --ui",
@@ -24,6 +25,7 @@
     "test:coverage": "vitest run --coverage",
     "test:e2e": "playwright test --project=chromium",
     "test:e2e:all": "playwright test",
+    "test:browser:ci": "node scripts/run-browser-ci.mjs",
     "test:e2e:debug": "playwright test --project=chromium --headed --debug",
     "test:e2e:install": "playwright install chromium firefox",
     "test:changed": "vitest run --changed",
@@ -40,6 +42,7 @@
     "@codemirror/view": "^6.43.14",
     "@emotion/react": "^11.11.1",
     "@emotion/styled": "^11.11.0",
+    "@lezer/highlight": "^1.2.3",
     "@mui/icons-material": "^9.5.0",
     "@mui/material": "^9.1.2",
     "@react-spring/web": "^10.1.2",
@@ -48,7 +51,6 @@
     "axios": "1.20.0",
     "codemirror": "^6.0.2",
     "codemirror-markdown-tables": "^1.0.1",
-    "highlight.js": "^11.12.0",
     "i18next": "^26.4.7",
     "react": "^19.3.1",
     "react-colorful": "^5.8.1",
@@ -58,9 +60,12 @@
     "react-pdf": "^11.0.0",
     "react-photo-view": "^1.2.7",
     "react-router-dom": "^7.18.4",
-    "rehype-highlight": "^7.0.2",
+    "rehype-slug": "6.0.0",
     "remark-gfm": "^4.0.1",
+    "remark-parse": "^11.0.0",
+    "remark-rehype": "11.1.2",
     "swiper": "^14.3.0",
+    "unified": "^11.0.5",
     "yet-another-react-lightbox": "^3.32.2"
   },
   "overrides": {
@@ -72,6 +77,8 @@
     "@testing-library/jest-dom": "^7.0.1",
     "@testing-library/react": "^16.3.3",
     "@testing-library/user-event": "^14.6.8",
+    "@types/hast": "^3.0.4",
+    "@types/mdast": "^4.0.4",
     "@types/node": "^26.6.5",
     "@types/react": "^19.3.0",
     "@types/react-dom": "^19.3.0",
diff --git a/frontend/playwright.config.ts b/frontend/playwright.config.ts
index be0d41f8d..abd270df2 100644
--- a/frontend/playwright.config.ts
+++ b/frontend/playwright.config.ts
@@ -1,23 +1,54 @@
 import { defineConfig, devices } from "@playwright/test";
 
 const frontendE2ePort = 4173;
-const baseURL = `http://127.0.0.1:${frontendE2ePort}`;
+const productionProof = process.env.SAMBEE_E2E_PRODUCTION === "1";
+const correctnessCI = process.env.SAMBEE_E2E_CI === "1";
+const ciMode = productionProof ? "production" : "development";
+const existingAppProof = productionProof || process.env.SAMBEE_E2E_DEVELOPMENT === "1";
+const baseURL = existingAppProof ? "http://localhost:3000" : `http://127.0.0.1:${frontendE2ePort}`;
+
+if (
+  correctnessCI &&
+  ["SAMBEE_E2E_BUDGETS", "SAMBEE_E2E_MEMORY", "SAMBEE_E2E_TRACE", "SAMBEE_E2E_RETAINED", "SAMBEE_E2E_HTTP_CACHE"].some(
+    (name) => process.env[name] === "1"
+  )
+) {
+  throw new Error("Run browser correctness separately from diagnostic and alternate-renderer modes");
+}
 
 export default defineConfig({
   testDir: "./e2e",
-  timeout: 30_000,
+  timeout: correctnessCI ? 30_000 : 15_000,
   fullyParallel: false,
-  retries: process.env.CI ? 1 : 0,
+  workers: correctnessCI ? 1 : undefined,
+  retries: correctnessCI ? 0 : process.env.CI ? 1 : 0,
+  forbidOnly: correctnessCI || !!process.env.CI,
+  grep: correctnessCI ? (productionProof ? /production CI correctness/ : /development Markdown worker/) : undefined,
+  outputDir: correctnessCI ? `test-results/ci/${ciMode}-artifacts` : "test-results",
+  reporter: correctnessCI
+    ? [["list"], ["json", { outputFile: `test-results/ci/${ciMode}.json` }], ["./scripts/ci-browser-reporter.mjs", { mode: ciMode }]]
+    : undefined,
   use: {
     baseURL,
-    trace: "on-first-retry",
-  },
-  webServer: {
-    command: `npm run dev -- --host 127.0.0.1 --port ${frontendE2ePort}`,
-    url: baseURL,
-    reuseExistingServer: true,
-    timeout: 120_000,
+    trace: correctnessCI ? "retain-on-failure" : "on-first-retry",
+    screenshot: correctnessCI ? "only-on-failure" : "off",
   },
+  webServer:
+    correctnessCI && !productionProof
+      ? {
+          command: "npm run dev -- --host localhost --port 3000 --strictPort",
+          url: baseURL,
+          reuseExistingServer: !process.env.CI,
+          timeout: 120_000,
+        }
+      : existingAppProof
+        ? undefined
+        : {
+            command: `npm run dev -- --host 127.0.0.1 --port ${frontendE2ePort}`,
+            url: baseURL,
+            reuseExistingServer: true,
+            timeout: 120_000,
+          },
   projects: [
     {
       name: "chromium",
diff --git a/frontend/scripts/ci-browser-reporter.mjs b/frontend/scripts/ci-browser-reporter.mjs
new file mode 100644
index 000000000..d0b54b3ec
--- /dev/null
+++ b/frontend/scripts/ci-browser-reporter.mjs
@@ -0,0 +1,24 @@
+import { validateBrowserCases } from "./ci-test-policy.mjs";
+
+export default class CiBrowserReporter {
+  constructor(options) {
+    this.mode = options.mode;
+  }
+
+  onBegin(_config, suite) {
+    this.suite = suite;
+  }
+
+  onEnd(result) {
+    const cases = this.suite.allTests().map((test) => ({
+      engine: test.parent.project()?.name,
+      title: test.title,
+      status: test.results.at(-1)?.status,
+      attempts: test.results.length,
+    }));
+    const errors = validateBrowserCases(this.mode, cases);
+    for (const error of errors) console.error(error);
+    console.log(`Browser correctness ${this.mode}: ${cases.length} cases, ${errors.length} contract violations`);
+    if (errors.length || result.status !== "passed") return { status: "failed" };
+  }
+}
diff --git a/frontend/scripts/ci-test-policy.d.mts b/frontend/scripts/ci-test-policy.d.mts
new file mode 100644
index 000000000..170a86a34
--- /dev/null
+++ b/frontend/scripts/ci-test-policy.d.mts
@@ -0,0 +1,18 @@
+export const CI_MAX_WORKERS: number;
+export const CI_WORKER_MEMORY_BYTES: number;
+export const CI_RESERVED_MEMORY_BYTES: number;
+export const CI_BROWSER_ENGINES: readonly string[];
+export const CI_BROWSER_WIDTHS: readonly number[];
+export const CI_PRODUCTION_SCENARIOS: readonly string[];
+export const CI_DEVELOPMENT_SCENARIO: string;
+
+export interface BrowserCase {
+  engine: string | undefined;
+  title: string | undefined;
+  status: string | undefined;
+  attempts: number;
+}
+
+export function ciWorkerCount(cpuCount: number, memoryBytes: number): number;
+export function expectedBrowserCases(mode: string): string[];
+export function validateBrowserCases(mode: string, cases: readonly BrowserCase[]): string[];
diff --git a/frontend/scripts/ci-test-policy.mjs b/frontend/scripts/ci-test-policy.mjs
new file mode 100644
index 000000000..f0c9a79e6
--- /dev/null
+++ b/frontend/scripts/ci-test-policy.mjs
@@ -0,0 +1,38 @@
+export const CI_MAX_WORKERS = 4;
+export const CI_WORKER_MEMORY_BYTES = 2 * 1024 ** 3;
+export const CI_RESERVED_MEMORY_BYTES = 2 * 1024 ** 3;
+export const CI_BROWSER_ENGINES = ["chromium", "firefox"];
+export const CI_BROWSER_WIDTHS = [1543, 390];
+export const CI_PRODUCTION_SCENARIOS = ["real workers", "native contracts", "edit and save", "cancel and reopen"];
+export const CI_DEVELOPMENT_SCENARIO = "normalizes and renders entity text without DOM globals in the worker";
+
+export function ciWorkerCount(cpuCount, memoryBytes) {
+  if (!Number.isFinite(cpuCount) || cpuCount < 1 || !Number.isFinite(memoryBytes) || memoryBytes < 1) {
+    throw new Error("CI worker selection requires positive CPU and memory measurements");
+  }
+  const memoryWorkers = Math.max(1, Math.floor((memoryBytes - CI_RESERVED_MEMORY_BYTES) / CI_WORKER_MEMORY_BYTES));
+  return Math.min(CI_MAX_WORKERS, Math.floor(cpuCount), memoryWorkers);
+}
+
+export function expectedBrowserCases(mode) {
+  if (mode !== "production" && mode !== "development") throw new Error(`Unknown browser CI mode: ${mode}`);
+  const titles =
+    mode === "production"
+      ? CI_PRODUCTION_SCENARIOS.flatMap((scenario) => CI_BROWSER_WIDTHS.map((width) => `CI ${scenario} at ${width}px`))
+      : [CI_DEVELOPMENT_SCENARIO];
+  return CI_BROWSER_ENGINES.flatMap((engine) => titles.map((title) => `${engine}: ${title}`));
+}
+
+export function validateBrowserCases(mode, cases) {
+  const missing = new Set(expectedBrowserCases(mode));
+  const errors = [];
+  for (const result of cases) {
+    const identity = `${result.engine}: ${result.title}`;
+    if (!missing.delete(identity)) errors.push(`Unexpected or duplicate browser case: ${identity}`);
+    if (result.status !== "passed" || result.attempts !== 1) {
+      errors.push(`Browser case must pass once without skips/retries: ${identity} (${result.status}, ${result.attempts} attempts)`);
+    }
+  }
+  for (const identity of missing) errors.push(`Missing browser case: ${identity}`);
+  return errors;
+}
diff --git a/frontend/scripts/draft-checkpoint-performance-proof.mjs b/frontend/scripts/draft-checkpoint-performance-proof.mjs
new file mode 100644
index 000000000..97228754b
--- /dev/null
+++ b/frontend/scripts/draft-checkpoint-performance-proof.mjs
@@ -0,0 +1,255 @@
+import assert from "node:assert/strict";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { chromium, firefox } from "playwright";
+import { build } from "vite";
+
+const FRONTEND = fileURLToPath(new URL("..", import.meta.url));
+const APPROVED_URL = "http://localhost:3000/browse/smb/demo";
+const ASSET_PREFIX = "/__draft_checkpoint_proof__/";
+const HOST_TASK_LIMIT_MS = 50;
+const output = await mkdtemp(resolve(tmpdir(), "sambee-draft-checkpoint-proof-"));
+const reports = [];
+
+try {
+  await build({
+    root: FRONTEND,
+    configFile: false,
+    logLevel: "warn",
+    define: { "process.env.NODE_ENV": JSON.stringify("production") },
+    build: {
+      outDir: output,
+      emptyOutDir: true,
+      minify: true,
+      lib: {
+        entry: {
+          checkpoint: resolve(FRONTEND, "src/services/draftCheckpoint.ts"),
+          recovery: resolve(FRONTEND, "src/services/draftRecovery.ts"),
+          identity: resolve(FRONTEND, "src/services/authSession.ts"),
+          state: fileURLToPath(import.meta.resolve("@codemirror/state")),
+        },
+        formats: ["es"],
+        fileName: (_format, name) => `${name}.js`,
+      },
+    },
+  });
+  for (const [browserName, browserType] of Object.entries({ chromium, firefox })) {
+    const browser = await browserType.launch({ headless: true });
+    try {
+      for (const width of [1543, 390]) {
+        const page = await browser.newPage({ viewport: { width, height: 900 } });
+        const errors = [];
+        page.on("pageerror", (error) => errors.push(error.message));
+        await page.route(`**${ASSET_PREFIX}**`, async (route) => {
+          const pathname = new URL(route.request().url()).pathname;
+          const path = resolve(output, decodeURIComponent(pathname.slice(ASSET_PREFIX.length)));
+          if (!path.startsWith(`${output}${sep}`)) return route.abort();
+          try {
+            await route.fulfill({ body: await readFile(path), contentType: "text/javascript" });
+          } catch {
+            await route.abort();
+          }
+        });
+        await page.route(APPROVED_URL, (route) =>
+          route.fulfill({
+            contentType: "text/html",
+            body: '<!doctype html><html lang="en"><title>P1 checkpoint proof</title><input id="input" aria-label="Input probe"></html>',
+          })
+        );
+        await page.goto(APPROVED_URL);
+        for (const [fixture, source] of [
+          ["code", "let x=1;\n".repeat(24_000)],
+          ["paragraph-source", "A **formatted** paragraph of text.\n\n".repeat(4_000)],
+          ["table-source", "| first cell | second cell |\n".repeat(2_400)],
+        ]) {
+          const measurement = await page.evaluate(
+            async ({ source, prefix }) => {
+              const { Text } = await import(`${prefix}state.js`);
+              const { authSession } = await import(`${prefix}identity.js`);
+              const { createDraftCheckpointController, DRAFT_CHECKPOINT_START_MS, DRAFT_CHECKPOINT_LAG_MS, DRAFT_TRANSITION_FLUSH_MS } =
+                await import(`${prefix}checkpoint.js`);
+              const { loadDraft } = await import(`${prefix}recovery.js`);
+              authSession.setAuthenticated({ access_token: "proof-only", token_type: "bearer", user_id: "checkpoint-proof" }, false);
+              sessionStorage.clear();
+              const controller = createDraftCheckpointController("demo", "/checkpoint.md", "markdown");
+              let doc = Text.of(source.split("\n"));
+              let serializedRevision = null;
+              const edits = [];
+              const serializations = [];
+              const acknowledgements = [];
+              const writes = [];
+              const gaps = [];
+              let lastTask = performance.now();
+              const heartbeat = setInterval(() => {
+                const now = performance.now();
+                gaps.push(now - lastTask);
+                lastTask = now;
+              }, 0);
+              const original = Storage.prototype.setItem;
+              Storage.prototype.setItem = function (key, value) {
+                const start = performance.now();
+                original.call(this, key, value);
+                const completed = performance.now();
+                writes.push(completed - start);
+                acknowledgements.push({ revision: serializedRevision, at: completed });
+              };
+              try {
+                for (let revision = 1; revision <= 20; revision += 1) {
+                  doc = doc.replace(doc.length, doc.length, Text.of(["x"]));
+                  const captured = doc;
+                  edits.push({ revision, at: performance.now() });
+                  controller.request(revision, async () => {
+                    const start = performance.now();
+                    const content = captured.toString();
+                    serializedRevision = revision;
+                    serializations.push({ revision, at: start, ms: performance.now() - start });
+                    return { baseline: source, content };
+                  });
+                  await new Promise((resolve) => setTimeout(resolve, 25));
+                }
+                const flushStart = performance.now();
+                const outcome = await controller.flush();
+                const flushMs = performance.now() - flushStart;
+                const lags = edits.map((edit) => {
+                  const stored = acknowledgements.find((ack) => ack.revision >= edit.revision);
+                  if (!stored) throw new Error("An edited revision was not acknowledged");
+                  return stored.at - edit.at;
+                });
+                const firstStartMs = serializations[0].at - edits[0].at;
+                return {
+                  outcome,
+                  sourceUnits: source.length,
+                  exactContent: loadDraft("demo", "/checkpoint.md", "markdown")?.content === `${source}${"x".repeat(20)}`,
+                  serializationCount: serializations.length,
+                  firstStartMs,
+                  maxLagMs: Math.max(...lags),
+                  flushMs,
+                  maxSerializationMs: Math.max(...serializations.map((entry) => entry.ms)),
+                  maxStorageMs: Math.max(...writes),
+                  maxSnapshotToStorageMs: Math.max(
+                    ...acknowledgements.map((ack) => ack.at - serializations.find((entry) => entry.revision === ack.revision).at)
+                  ),
+                  maxTimerGapMs: Math.max(0, ...gaps),
+                  targets: { start: DRAFT_CHECKPOINT_START_MS, lag: DRAFT_CHECKPOINT_LAG_MS, flush: DRAFT_TRANSITION_FLUSH_MS },
+                };
+              } finally {
+                Storage.prototype.setItem = original;
+                clearInterval(heartbeat);
+                controller.dispose();
+                authSession.clear();
+              }
+            },
+            { source, prefix: ASSET_PREFIX }
+          );
+          assert.deepEqual(measurement.outcome, { saved: true, revision: 20 });
+          assert.equal(measurement.exactContent, true);
+          assert.ok(measurement.serializationCount < 20, "Do not serialize each edit");
+          assert.ok(measurement.firstStartMs <= measurement.targets.start, "Checkpoint start exceeded approved target");
+          assert.ok(measurement.maxLagMs <= measurement.targets.lag, "Checkpoint lag exceeded approved target");
+          assert.ok(measurement.flushMs <= measurement.targets.flush, "Transition flush exceeded approved target");
+          assert.ok(measurement.maxSerializationMs <= HOST_TASK_LIMIT_MS, "Serialization task exceeded interaction ceiling");
+          assert.ok(measurement.maxStorageMs <= HOST_TASK_LIMIT_MS, "Storage task exceeded interaction ceiling");
+          assert.ok(
+            measurement.maxSnapshotToStorageMs <= HOST_TASK_LIMIT_MS,
+            "Snapshot preparation and storage exceeded interaction ceiling"
+          );
+          assert.ok(measurement.maxTimerGapMs <= HOST_TASK_LIMIT_MS, "Scheduling responsiveness proxy exceeded ceiling");
+          reports.push({ browserName, browser: browser.version(), width, fixture, ...measurement });
+        }
+
+        const lifecycleSource = "let x=1;\n".repeat(24_000);
+        for (const lifecycle of ["late-completion", "reload"]) {
+          await page.evaluate(
+            async ({ prefix, source }) => {
+              const { authSession } = await import(`${prefix}identity.js`);
+              const { Text } = await import(`${prefix}state.js`);
+              const { createDraftCheckpointController } = await import(`${prefix}checkpoint.js`);
+              const { createDraftCheckpointSession } = await import(`${prefix}recovery.js`);
+              authSession.setAuthenticated({ access_token: "proof-only", token_type: "bearer", user_id: "checkpoint-proof" }, false);
+              sessionStorage.clear();
+              const controller = createDraftCheckpointController("demo", "/lifecycle.md", "markdown");
+              let doc = Text.of(source.split("\n"));
+              let release;
+              const deferred = new Promise((resolve) => {
+                release = resolve;
+              });
+              controller.request(1, () => deferred);
+              const flush = controller.flush();
+              document.querySelector("#input").oninput = () => {
+                doc = doc.replace(doc.length, doc.length, Text.of(["x"]));
+              };
+              window.checkpointLifecycleProof = { controller, release, flush, result: null };
+              window.addEventListener(
+                "pagehide",
+                () => {
+                  const start = performance.now();
+                  const session = createDraftCheckpointSession("demo", "/lifecycle.md", "markdown");
+                  try {
+                    const result = session.commit(session.capture(2), source, doc.toString());
+                    window.checkpointLifecycleProof.result = { ...result, ms: performance.now() - start };
+                  } finally {
+                    session.dispose();
+                  }
+                },
+                { once: true }
+              );
+              await Promise.resolve();
+            },
+            { prefix: ASSET_PREFIX, source: lifecycleSource }
+          );
+          await page.locator("#input").press("x");
+          if (lifecycle === "late-completion") {
+            const result = await page.evaluate(
+              async ({ prefix }) => {
+                window.dispatchEvent(new PageTransitionEvent("pagehide"));
+                const proof = window.checkpointLifecycleProof;
+                proof.release({ baseline: "saved", content: "obsolete async edit" });
+                const late = await proof.flush;
+                const { loadDraft } = await import(`${prefix}recovery.js`);
+                const recovered = loadDraft("demo", "/lifecycle.md", "markdown");
+                proof.controller.dispose();
+                return { latest: proof.result, late, content: recovered?.content };
+              },
+              { prefix: ASSET_PREFIX }
+            );
+            assert.equal(result.latest.saved, true);
+            assert.ok(result.latest.ms <= HOST_TASK_LIMIT_MS);
+            assert.deepEqual(result.late, { saved: false, revision: 1, reason: "stale-checkpoint" });
+            assert.equal(result.content, `${lifecycleSource}x`);
+            reports.push({
+              browserName,
+              width,
+              fixture: "synchronous-lifecycle",
+              sourceUnits: lifecycleSource.length,
+              snapshotAndStorageMs: result.latest.ms,
+            });
+          } else {
+            await page.reload();
+            const recovered = await page.evaluate(
+              async ({ prefix }) => {
+                const { authSession } = await import(`${prefix}identity.js`);
+                authSession.setAuthenticated({ access_token: "proof-only", token_type: "bearer", user_id: "checkpoint-proof" }, false);
+                const { loadDraft } = await import(`${prefix}recovery.js`);
+                return loadDraft("demo", "/lifecycle.md", "markdown")?.content;
+              },
+              { prefix: ASSET_PREFIX }
+            );
+            assert.equal(recovered, `${lifecycleSource}x`);
+          }
+        }
+        assert.deepEqual(errors, []);
+        await page.close();
+        console.log(
+          `${browserName} width=${width}: sustained-edit checkpoints, pending-snapshot keyboard input, synchronous lifecycle, late-result rejection and real reload passed`
+        );
+      }
+    } finally {
+      await browser.close();
+    }
+  }
+  console.log(JSON.stringify({ kind: "P1 recovery boundary proof, NOT integrated editor acceptance", measurements: reports }, null, 2));
+} finally {
+  await rm(output, { recursive: true, force: true });
+}
diff --git a/frontend/scripts/markdown-document-performance-proof.mjs b/frontend/scripts/markdown-document-performance-proof.mjs
new file mode 100644
index 000000000..a00f3c56c
--- /dev/null
+++ b/frontend/scripts/markdown-document-performance-proof.mjs
@@ -0,0 +1,845 @@
+import assert from "node:assert/strict";
+
+const HOST_ENVELOPE_UNITS = { "dense-code": 24_000, paragraphs: 4_000, table: 2_400 };
+const HOST_BUDGETS = { loadMs: 1_500, searchMs: 1_000, warmSearchMs: 100, navigationMs: 100, maximumTaskServiceGapMs: 50 };
+const HOST_RENDERER_HEAP_BYTES = 64 * 1_024 * 1_024;
+const HOST_SHUTDOWN_GROWTH_BYTES = 1_024 * 1_024;
+const HOST_TRIALS = 3;
+
+export function documentHostBudgetFailures(report) {
+  const failures = [];
+  for (const width of [1543, 390]) {
+    for (const [fixture, units] of Object.entries(HOST_ENVELOPE_UNITS))
+      for (let trial = 0; trial < HOST_TRIALS; trial += 1) {
+        const entries = (report.scaling ?? []).filter(
+          (entry) => entry.width === width && entry.fixture === fixture && entry.units === units && entry.trial === trial
+        );
+        const entry = entries[0];
+        const label = `${report.browserName} ${width} ${fixture} ${units} trial ${trial}`;
+        if (entries.length !== 1 || !entry?.measurement || entry.error) {
+          failures.push(`${label}: missing/duplicate/failed trial${entry?.error ? `: ${entry.error}` : ""}`);
+          continue;
+        }
+        for (const [metric, budget] of Object.entries(HOST_BUDGETS)) {
+          const actual = entry.measurement[metric];
+          if (!Number.isFinite(actual) || actual < 0 || actual > budget)
+            failures.push(`${label}: ${metric}=${actual} exceeds ${budget} ms or is invalid`);
+        }
+        if (report.browserName === "chromium") {
+          const bytes = entry.loadedRendererSnapshot?.usedSize;
+          if (!Number.isFinite(bytes) || bytes < 0 || bytes > HOST_RENDERER_HEAP_BYTES)
+            failures.push(`${label}: loaded renderer heap=${bytes} exceeds ${HOST_RENDERER_HEAP_BYTES} bytes or is unavailable`);
+        }
+      }
+    if (report.browserName === "chromium") {
+      const resource = (report.resources ?? []).find((entry) => entry.width === width && entry.supported);
+      const samples = resource?.samples;
+      if (samples?.length !== 6) failures.push(`${width}: six post-shutdown resource samples required`);
+      else {
+        const growth = samples.at(-1).usedSize - samples[1].usedSize;
+        if (!Number.isFinite(growth) || growth > HOST_SHUTDOWN_GROWTH_BYTES)
+          failures.push(`${width}: warmed shutdown heap growth=${growth} exceeds ${HOST_SHUTDOWN_GROWTH_BYTES} bytes or is unavailable`);
+        for (const sample of samples)
+          if (sample.owned.elements !== 0 || sample.owned.highlights !== 0 || sample.owned.liveWorkers !== 0)
+            failures.push(`${width}: owned resources remain after cycle ${sample.cycle}`);
+      }
+    }
+  }
+  return failures;
+}
+
+export async function runMarkdownDocumentProof(page, report, width) {
+  await page.evaluate(() => {
+    const OriginalWorker = window.Worker;
+    window.documentWorkers = [];
+    window.Worker = class extends OriginalWorker {
+      constructor(...args) {
+        super(...args);
+        window.documentWorkers.push({ worker: this, terminated: false });
+      }
+      terminate() {
+        window.documentWorkers.find((entry) => entry.worker === this).terminated = true;
+        super.terminate();
+      }
+      postMessage(message, ...args) {
+        if (message.type === "syntax-window" && window.pauseSyntaxWindow) {
+          window.pausedSyntaxWorker = this;
+          return;
+        }
+        if (message.type === "prepare") this.documentPreparation = message.document === true;
+        if (this.documentPreparation && window.pauseDocumentPublication && message.type === "ack") {
+          window.resumeDocumentPublication = () => super.postMessage(message, ...args);
+          return;
+        }
+        super.postMessage(message, ...args);
+      }
+    };
+  });
+  const fixtures = [
+    {
+      name: "unicode-boundaries",
+      source: `# Unicode boundaries\n\n${"x".repeat(2_047)}\u{1f30d}${"x".repeat(2_047)}e\u0301\n\n\`\`\`text\n${"x".repeat(2_047)}\u{1f30d}\t end\n\`\`\``,
+    },
+    { name: "empty", source: "" },
+    { name: "canonical-normalization", source: "* first\n* second\n\n| Left | Right |\n| --- | --- |\n| a\\&b | first<BR>second&#10;third |\n\n```md\n* literal<BR>\n```\n" },
+    { name: "unknown-language", source: "# Plain fallback\n\n```unknown-language-proof\nUnchanged source.\n```" },
+    { name: "image", source: "# Image sizing\n\n![Visible fixture](/__markdown_preview_proof__/fixture.png)\n\nText after image." },
+    {
+      name: "mixed",
+      source:
+        "# Whole Markdown\n\n**Strong**, *emphasis*, ~~deleted~~ and [link](https://example.com). Unicode \u{1f30d} &amp; &copy;.\n\n> Nested quote\n>\n> - first\n>   - child\n\n- [x] done\n- [ ] pending\n\n| Left | Right |\n| :--- | ---: |\n| first<br>second | `inline` |\n\n```js\nlet x = 1;\n```\n\nFootnote[^note].\n\n[^note]: Offscreen footnote.\n\n<script>window.invalid=true</script>\n[unsafe](javascript:alert%281%29)",
+    },
+    { name: "dense-code", source: `# Dense code\n\n\`\`\`js\n${"let x=1;\n".repeat(6_000)}\`\`\`\n\nLast paragraph.` },
+    {
+      name: "large-paragraph",
+      source: `# Large paragraph\n\n${"Text **strong** with \u{1f30d} and inline `code`. ".repeat(1_000)}\n\nEnd.`,
+    },
+    {
+      name: "large-table",
+      source: `# Large table\n\n| Number | Value |\n| --- | --- |\n${Array.from({ length: 800 }, (_, index) => `| ${index} | cell **${index}**<br>next |`).join("\n")}\n\nEnd.`,
+    },
+    { name: "long-line", source: `# Long line\n\n\`\`\`js\n// ${"x".repeat(60_000)}\n\`\`\`\n\nEnd.` },
+  ];
+  for (const fixture of fixtures) {
+    await page.evaluate((source) => window.codePreviewPrototype.baselineDocument(source), fixture.source);
+    await page.locator("[data-markdown-baseline] img").evaluateAll(async (images) => Promise.all(images.map((image) => image.decode())));
+    const expected = await page.evaluate(() => {
+      const container = document.querySelector("[data-markdown-baseline]");
+      const selection = window.getSelection();
+      selection.selectAllChildren(container);
+      const selected = selection.toString();
+      selection.removeAllRanges();
+      return {
+        text: container.textContent,
+        selected,
+        height: container.scrollHeight,
+        tags: [...container.querySelectorAll("h1,h2,p,table,tr,td,th,ul,ol,li,input,a,pre,code,br")].map((element) => element.tagName),
+      };
+    });
+    await page.setViewportSize({ width: width === 390 ? 1543 : 390, height: 900 });
+    expected.resizedHeight = await page.locator("[data-markdown-baseline]").evaluate((container) => container.scrollHeight);
+    await page.setViewportSize({ width, height: 900 });
+    const nativeFind = async (selector) =>
+      page.locator(selector).evaluate((container) => {
+        container.scrollTop = 0;
+        window.getSelection().removeAllRanges();
+        const found = window.find("Last paragraph.", false, false, true);
+        const selection = window.getSelection();
+        const rect = selection.rangeCount ? selection.getRangeAt(0).getBoundingClientRect() : null;
+        const viewport = container.getBoundingClientRect();
+        const result = {
+          found,
+          selected: selection.toString(),
+          visible: Boolean(rect && rect.bottom > viewport.top && rect.top < viewport.bottom),
+        };
+        selection.removeAllRanges();
+        return result;
+      });
+    const baselineFind = fixture.name === "dense-code" ? await nativeFind("[data-markdown-baseline]") : null;
+    const timing = await page.evaluate(async (source) => {
+      const start = performance.now();
+      let previous = start;
+      let maximumTaskServiceGapMs = 0;
+      let timer;
+      const probe = () => {
+        const now = performance.now();
+        maximumTaskServiceGapMs = Math.max(maximumTaskServiceGapMs, now - previous);
+        previous = now;
+        timer = setTimeout(probe, 0);
+      };
+      const longTasks = [];
+      const longTaskObservationSupported = PerformanceObserver.supportedEntryTypes.includes("longtask");
+      const observer = new PerformanceObserver((list) => longTasks.push(...list.getEntries().map((entry) => entry.duration)));
+      if (longTaskObservationSupported) observer.observe({ type: "longtask" });
+      timer = setTimeout(probe, 0);
+      try {
+        await window.codePreviewPrototype.loadDocument(source);
+        await new Promise(requestAnimationFrame);
+        await new Promise(requestAnimationFrame);
+        longTasks.push(...observer.takeRecords().map((entry) => entry.duration));
+        maximumTaskServiceGapMs = Math.max(maximumTaskServiceGapMs, performance.now() - previous);
+        return { loadToPaintMs: performance.now() - start, longTaskObservationSupported, longTasks, maximumTaskServiceGapMs };
+      } finally {
+        clearTimeout(timer);
+        observer.disconnect();
+      }
+    }, fixture.source);
+    await page.locator("[data-markdown-document] img").evaluateAll(async (images) => Promise.all(images.map((image) => image.decode())));
+    const actual = await page.evaluate(() => {
+      const container = document.querySelector("[data-markdown-document]");
+      const selection = window.getSelection();
+      selection.selectAllChildren(container);
+      const selected = selection.toString();
+      selection.removeAllRanges();
+      return {
+        stats: window.codePreviewPrototype.stats(),
+        text: container.textContent,
+        selected,
+        height: container.scrollHeight,
+        tags: [...container.querySelectorAll("h1,h2,p,table,tr,td,th,ul,ol,li,input,a,pre,code,br")].map((element) => element.tagName),
+        unsafe: container.querySelector("script,[onclick],a[href^='javascript:']") !== null,
+      };
+    });
+    assert.equal(actual.stats.complete, true);
+    assert.equal(actual.stats.error, null);
+    assert.equal(actual.text, expected.text, fixture.name);
+    assert.equal(actual.selected, expected.selected, `${fixture.name}: native selection`);
+    assert.deepEqual(actual.tags, expected.tags, fixture.name);
+    assert.equal(actual.height, expected.height, `${fixture.name}: layout`);
+    assert.equal(actual.unsafe, false);
+    assert.ok(actual.stats.largestBatch <= actual.stats.batchLimit);
+    assert.ok(actual.stats.highlightRanges <= 4_000);
+    assert.equal(actual.stats.syntaxError, null);
+    assert.ok(actual.stats.cachedSyntaxRanges <= actual.stats.syntaxCacheLimit);
+    assert.ok(actual.stats.peakCachedSyntaxRanges <= actual.stats.syntaxCacheLimit);
+    assert.ok(actual.stats.largestSyntaxPage <= actual.stats.syntaxPageLimit);
+    if (fixture.name === "dense-code") {
+      await page.waitForFunction(
+        () => !window.codePreviewPrototype.stats().syntaxFetching && window.codePreviewPrototype.stats().highlightRanges > 0
+      );
+      const top = await page.evaluate(() => {
+        const container = document.querySelector("[data-markdown-document]");
+        const node = container.querySelector("code [data-document-fragment]").firstChild;
+        window.syntaxSelectionNode = node;
+        const range = new Range();
+        range.setStart(node, 0);
+        range.setEnd(node, 3);
+        const selection = window.getSelection();
+        selection.removeAllRanges();
+        selection.addRange(range);
+        const stats = window.codePreviewPrototype.stats();
+        container.scrollTop = container.scrollHeight;
+        return stats;
+      });
+      await page.waitForFunction(() => {
+        const container = document.querySelector("[data-markdown-document]");
+        const viewport = container.getBoundingClientRect();
+        const highlight = CSS.highlights.get("document-keyword");
+        return (
+          !window.codePreviewPrototype.stats().syntaxFetching &&
+          highlight &&
+          [...highlight].some((range) => {
+            const rect = range.getBoundingClientRect();
+            return rect.bottom > viewport.top && rect.top < viewport.bottom;
+          })
+        );
+      });
+      const bottom = await page.evaluate(() => {
+        const selection = window.getSelection();
+        const stats = window.codePreviewPrototype.stats();
+        const stable =
+          selection.anchorNode === window.syntaxSelectionNode && selection.toString() === "let" && window.syntaxSelectionNode.isConnected;
+        selection.removeAllRanges();
+        window.syntaxSelectionNode = null;
+        return { ...stats, stable };
+      });
+      assert.ok(top.workerSyntaxRanges > top.syntaxCacheLimit);
+      assert.ok(bottom.peakCachedSyntaxRanges <= bottom.syntaxCacheLimit);
+      assert.ok(bottom.largestSyntaxPage <= bottom.syntaxPageLimit);
+      assert.equal(bottom.syntaxError, null);
+      assert.equal(bottom.stable, true);
+      assert.ok(bottom.syntaxPages > top.syntaxPages);
+      report.interactions.push({ width, mode: "viewport-syntax", top, bottom });
+      await page.evaluate(() => {
+        window.pauseSyntaxWindow = true;
+        document.querySelector("[data-markdown-document]").scrollTop = 0;
+      });
+      await page.waitForFunction(() => !!window.pausedSyntaxWorker);
+      const syntaxFailure = await page.evaluate(async () => {
+        const container = document.querySelector("[data-markdown-document]");
+        const node = container.querySelector("code [data-document-fragment]").firstChild;
+        const text = container.textContent;
+        window.pausedSyntaxWorker.dispatchEvent(new Event("messageerror"));
+        await new Promise(requestAnimationFrame);
+        await new Promise(requestAnimationFrame);
+        window.pauseSyntaxWindow = false;
+        window.pausedSyntaxWorker = null;
+        return { stats: window.codePreviewPrototype.stats(), textRetained: container.textContent === text, nodeRetained: node.isConnected };
+      });
+      assert.match(syntaxFailure.stats.syntaxError, /could not be decoded/);
+      assert.equal(syntaxFailure.stats.cachedSyntaxRanges, 0);
+      assert.equal(syntaxFailure.textRetained, true);
+      assert.equal(syntaxFailure.nodeRetained, true);
+      report.interactions.push({ width, mode: "viewport-syntax-failure", ...syntaxFailure });
+    }
+    await page.setViewportSize({ width: width === 390 ? 1543 : 390, height: 900 });
+    assert.equal(
+      await page.locator("[data-markdown-document]").evaluate((container) => container.scrollHeight),
+      expected.resizedHeight,
+      `${fixture.name}: resized layout`
+    );
+    await page.setViewportSize({ width, height: 900 });
+    if (baselineFind) {
+      const actualFind = await nativeFind("[data-markdown-document]");
+      assert.equal(actualFind.found, true);
+      assert.equal(actualFind.selected, "Last paragraph.");
+      assert.deepEqual(actualFind, baselineFind);
+      report.interactions.push({ width, mode: "whole-markdown", nativeFind: actualFind });
+      if (!actualFind.visible)
+        report.blockers.push({
+          width,
+          nativeFindReveal:
+            "Headless window.find selected but did not reveal in either canonical or prototype document; actual browser Find UI unverified",
+        });
+    }
+    if (fixture.name === "dense-code") assert.ok(actual.stats.highlightRanges > 0);
+    if (fixture.name === "unknown-language") assert.equal(actual.stats.fallbacks.length, 1);
+    if (fixture.name === "image") {
+      const image = await page.locator("[data-markdown-document] img").evaluate(async (element) => {
+        const before = element.nextElementSibling?.getBoundingClientRect().top ?? element.getBoundingClientRect().bottom;
+        element.style.width = "80px";
+        element.style.height = "120px";
+        await new Promise(requestAnimationFrame);
+        return {
+          loaded: element.naturalWidth > 0,
+          resized: element.getBoundingClientRect().height === 120,
+          before,
+          after: element.getBoundingClientRect().bottom,
+        };
+      });
+      assert.equal(image.loaded, true);
+      assert.equal(image.resized, true);
+      report.interactions.push({ width, mode: "whole-markdown", image });
+    }
+    if (fixture.name === "mixed") {
+      const readingTree = await page.locator("[data-markdown-document]").ariaSnapshot();
+      assert.ok(readingTree.includes("Whole Markdown"));
+      assert.ok(readingTree.includes("Offscreen footnote"));
+      await page.locator("[data-markdown-document] a[data-footnote-ref]").click();
+      const targetVisible = await page.locator("[data-markdown-document] li[id^='user-content-fn-']").evaluate((element) => {
+        const rect = element.getBoundingClientRect();
+        const viewport = document.querySelector("[data-markdown-document]").getBoundingClientRect();
+        return rect.bottom > viewport.top && rect.top < viewport.bottom;
+      });
+      assert.equal(targetVisible, true);
+      const color = await page.evaluate(() => {
+        document.getElementById("prototype").style.setProperty("--sambee-syntax-keyword", "#13579b");
+        return getComputedStyle(document.getElementById("prototype"), "::highlight(document-keyword)").color;
+      });
+      assert.equal(color, "rgb(19, 87, 155)");
+    }
+    await page.emulateMedia({ media: "print" });
+    const print = await page
+      .locator("[data-markdown-document]")
+      .evaluate((container) => ({ text: container.textContent, unclipped: container.clientHeight >= container.scrollHeight }));
+    assert.equal(print.text, expected.text);
+    assert.equal(print.unclipped, true);
+    await page.emulateMedia({ media: "screen" });
+    report.interactions.push({
+      width,
+      fixture: fixture.name,
+      mode: "whole-markdown",
+      exactText: true,
+      exactSelection: true,
+      equalHeight: true,
+      ...actual.stats,
+    });
+    report.measurements.push({
+      width,
+      fixture: fixture.name,
+      virtual: "whole-markdown",
+      cache: "sequential-worker",
+      mountedRows: actual.stats.mountedElements,
+      mountedSpans: actual.stats.mountedSpans,
+      preparationMs: null,
+      workerPipelineWallMs: actual.stats.workerPipelineWallMs,
+      indexingMs: null,
+      publicationBatches: actual.stats.batches,
+      ...timing,
+    });
+  }
+  await page.evaluate(() => {
+    const input = document.createElement("input");
+    input.id = "document-input-probe";
+    document.body.prepend(input);
+    window.documentInputEvents = [];
+    input.addEventListener("input", () => window.documentInputEvents.push(window.codePreviewPrototype.stats().complete));
+    window.pauseDocumentPublication = true;
+    window.documentOutcome = window.codePreviewPrototype
+      .loadDocument(`# Pending document\n\n${"Paragraph **text** with Unicode \u{1f30d}.\n\n".repeat(4_000)}`)
+      .then(
+        () => "complete",
+        (error) => error.name
+      );
+  });
+  await page.waitForFunction(() => {
+    const stats = window.codePreviewPrototype.stats();
+    return stats.batches > 0 && !stats.complete;
+  });
+  await page.locator("#document-input-probe").pressSequentially("responsive");
+  const partial = await page.evaluate(async () => {
+    const container = document.querySelector("[data-markdown-document]");
+    const text = container.querySelector("h1").firstChild;
+    const selection = window.getSelection();
+    const range = new Range();
+    range.setStart(text, 0);
+    range.setEnd(text, 7);
+    selection.removeAllRanges();
+    selection.addRange(range);
+    const before = window.codePreviewPrototype.stats().batches;
+    window.resumeDocumentPublication();
+    await new Promise(requestAnimationFrame);
+    await new Promise(requestAnimationFrame);
+    const after = window.codePreviewPrototype.stats().batches;
+    const stableSelection = selection.anchorNode === text && selection.focusNode === text && selection.toString() === "Pending";
+    selection.removeAllRanges();
+    const obsolete = window.documentOutcome;
+    window.pauseDocumentPublication = false;
+    await window.codePreviewPrototype.loadDocument("# Replacement\n\nLatest document.");
+    const outcome = await obsolete;
+    document.getElementById("document-input-probe").remove();
+    return {
+      before,
+      after,
+      stableSelection,
+      inputEvents: window.documentInputEvents,
+      outcome,
+      oldTextDetached: !text.isConnected,
+      text: document.querySelector("[data-markdown-document]").textContent,
+    };
+  });
+  assert.ok(partial.after > partial.before);
+  assert.equal(partial.stableSelection, true);
+  assert.ok(partial.inputEvents.some((complete) => !complete));
+  assert.equal(partial.outcome, "AbortError");
+  assert.equal(partial.oldTextDetached, true);
+  assert.equal(partial.text, "Replacement\nLatest document.");
+  const rapid = await page.evaluate(async () => {
+    const obsolete = window.codePreviewPrototype.loadDocument("# Obsolete").then(
+      () => "complete",
+      (error) => error.name
+    );
+    await window.codePreviewPrototype.loadDocument("# Current");
+    return { outcome: await obsolete, text: document.querySelector("[data-markdown-document]").textContent };
+  });
+  assert.equal(rapid.outcome, "AbortError");
+  assert.equal(rapid.text, "Current");
+  await page.evaluate(() => {
+    window.hiddenDocumentOutcome = window.codePreviewPrototype.loadDocument(
+      `# Hidden document\n\n${"Paragraph **text**.\n\n".repeat(4_000)}`
+    );
+  });
+  await page.waitForFunction(() => {
+    const stats = window.codePreviewPrototype.stats();
+    return stats.batches > 0 && !stats.complete;
+  });
+  const hidden = await page.evaluate(async () => {
+    const descriptor = Object.getOwnPropertyDescriptor(document, "hidden");
+    try {
+      Object.defineProperty(document, "hidden", { configurable: true, value: true });
+      document.dispatchEvent(new Event("visibilitychange"));
+      await window.hiddenDocumentOutcome;
+      return {
+        complete: window.codePreviewPrototype.stats().complete,
+        text: document.querySelector("[data-markdown-document]").textContent,
+      };
+    } finally {
+      if (descriptor) Object.defineProperty(document, "hidden", descriptor);
+      else delete document.hidden;
+    }
+  });
+  assert.equal(hidden.complete, true);
+  assert.equal(hidden.text, `Hidden document\n${Array.from({ length: 4_000 }, () => "Paragraph text.").join("\n")}`);
+  report.interactions.push({ width, mode: "whole-markdown", partial, rapid, hidden: { complete: hidden.complete } });
+  await page.evaluate(() => {
+    window.documentOutcome = window.codePreviewPrototype.loadDocument(`# Failure probe\n\n${"Paragraph **text**.\n\n".repeat(4_000)}`).then(
+      () => "complete",
+      (error) => error.message
+    );
+  });
+  await page.waitForFunction(() => {
+    const stats = window.codePreviewPrototype.stats();
+    return stats.batches > 0 && !stats.complete;
+  });
+  const failure = await page.evaluate(async () => {
+    const node = document.querySelector("[data-markdown-document] h1").firstChild;
+    const before = document.querySelector("[data-markdown-document]").textContent;
+    const latest = window.documentWorkers.at(-1);
+    latest.worker.dispatchEvent(new Event("messageerror"));
+    const outcome = await window.documentOutcome;
+    const stats = window.codePreviewPrototype.stats();
+    return {
+      outcome,
+      stats,
+      terminated: latest.terminated,
+      retainedText: document.querySelector("[data-markdown-document]").textContent === before,
+      nodeStable: node.isConnected,
+    };
+  });
+  assert.match(failure.outcome, /could not be decoded/);
+  assert.equal(failure.stats.complete, false);
+  assert.match(failure.stats.error, /could not be decoded/);
+  assert.equal(failure.terminated, true);
+  assert.equal(failure.retainedText, true);
+  assert.equal(failure.nodeStable, true);
+  await runDocumentSearchProof(page, report, width);
+  await page.evaluate(() => window.codePreviewPrototype.loadDocument("# Recovered\n\nReadable again."));
+  const cleanup = await page.evaluate(() => {
+    const node = document.querySelector("[data-markdown-document] h1").firstChild;
+    window.codePreviewPrototype.shutdownDocument();
+    return {
+      detached: !node.isConnected,
+      text: document.querySelector("[data-markdown-document]").textContent,
+      workersTerminated: window.documentWorkers.every((entry) => entry.terminated),
+      highlights: [...CSS.highlights.keys()].filter((name) => name.startsWith("document-")).length,
+    };
+  });
+  assert.equal(cleanup.detached, true);
+  assert.equal(cleanup.text, "");
+  assert.equal(cleanup.workersTerminated, true);
+  assert.equal(cleanup.highlights, 0);
+  report.interactions.push({ width, mode: "whole-markdown", failure, cleanup });
+  if (process.env.SAMBEE_PREVIEW_PROOF_SCALE === "1") await runDocumentScalingProof(page, report, width);
+  report.resources ??= [];
+  if (report.browserName === "chromium") {
+    const cdp = await page.context().newCDPSession(page);
+    try {
+      await cdp.send("HeapProfiler.enable");
+      const samples = [];
+      for (let cycle = 0; cycle < 6; cycle += 1) {
+        await page.evaluate(async (cycle) => {
+          await window.codePreviewPrototype.loadDocument(
+            `# Resource cycle ${cycle}\n\n\`\`\`js\n${"let x=1;\n".repeat(1_200)}\`\`\`\n\nEnd.`
+          );
+          await window.codePreviewPrototype.searchDocument("let x");
+          await window.codePreviewPrototype.jumpDocument(1_199);
+          window.codePreviewPrototype.shutdownDocument();
+          await new Promise(requestAnimationFrame);
+          await new Promise(requestAnimationFrame);
+        }, cycle);
+        await cdp.send("HeapProfiler.collectGarbage");
+        const heap = await cdp.send("Runtime.getHeapUsage");
+        const dom = await cdp.send("Memory.getDOMCounters");
+        const owned = await page.evaluate(() => ({
+          elements: document.querySelector("[data-markdown-document]").childElementCount,
+          highlights: [...CSS.highlights.keys()].filter((name) => name.startsWith("document-")).length,
+          liveWorkers: window.documentWorkers.filter((entry) => !entry.terminated).length,
+        }));
+        assert.equal(owned.elements, 0);
+        assert.equal(owned.highlights, 0);
+        assert.equal(owned.liveWorkers, 0);
+        samples.push({ cycle, ...heap, ...dom, owned });
+      }
+      report.resources.push({
+        width,
+        supported: true,
+        scope: "Chromium main-renderer heap/DOM after explicit GC; excludes worker/process memory and is not an accepted memory ceiling",
+        samples,
+      });
+    } finally {
+      await cdp.detach();
+    }
+  } else
+    report.resources.push({
+      width,
+      supported: false,
+      reason: "Chromium CDP heap and DOM counters are unavailable in this browser; no zero-memory claim",
+    });
+  await page.evaluate(
+    (source) => window.codePreviewPrototype.loadDocument(source),
+    fixtures.find((fixture) => fixture.name === "mixed").source
+  );
+}
+
+async function runDocumentScalingProof(page, report, width) {
+  const fixtures = [
+    ...[1, 4, 12].map((blocks) => ({
+      name: "dense-code",
+      units: blocks * 6_000,
+      query: "let x",
+      expected: blocks * 6_000,
+      source: Array.from({ length: blocks }, (_, index) => `## Code ${index}\n\n\`\`\`js\n${"let x=1;\n".repeat(6_000)}\`\`\``).join(
+        "\n\n"
+      ),
+    })),
+    ...[1_000, 4_000, 8_000].map((paragraphs) => ({
+      name: "paragraphs",
+      units: paragraphs,
+      query: "strong",
+      expected: paragraphs,
+      source: `# Paragraphs\n\n${"Text **strong** and inline `code`.\n\n".repeat(paragraphs)}`,
+    })),
+    ...[800, 2_400, 4_800].map((rows) => ({
+      name: "table",
+      units: rows,
+      query: "cell",
+      expected: rows,
+      source: `# Table\n\n| Number | Value |\n| --- | --- |\n${Array.from({ length: rows }, (_, index) => `| ${index} | cell **${index}**<br>next |`).join("\n")}`,
+    })),
+  ];
+  report.scaling ??= [];
+  const cdp = report.browserName === "chromium" ? await page.context().newCDPSession(page) : null;
+  try {
+    for (const fixture of fixtures.filter(
+      (fixture) => process.env.SAMBEE_PREVIEW_PROOF_BUDGETS !== "1" || fixture.units === HOST_ENVELOPE_UNITS[fixture.name]
+    ))
+      for (let trial = 0; trial < 3; trial += 1) {
+        try {
+          const measurement = await page.evaluate(
+            async ({ source, query, ordinal }) => {
+              window.codePreviewPrototype.shutdownDocument();
+              const start = performance.now();
+              let previous = start;
+              let maximumTaskServiceGapMs = 0;
+              const timer = setInterval(() => {
+                const now = performance.now();
+                maximumTaskServiceGapMs = Math.max(maximumTaskServiceGapMs, now - previous);
+                previous = now;
+              }, 0);
+              try {
+                await window.codePreviewPrototype.loadDocument(source);
+                await new Promise(requestAnimationFrame);
+                await new Promise(requestAnimationFrame);
+                const loadMs = performance.now() - start;
+                const searchStart = performance.now();
+                const result = await window.codePreviewPrototype.searchDocument(query);
+                const searchMs = performance.now() - searchStart;
+                const warmStart = performance.now();
+                const warm = await window.codePreviewPrototype.searchDocument(query.toUpperCase());
+                const warmSearchMs = performance.now() - warmStart;
+                if (warm.count !== result.count) throw new Error("Warm-index query changed the exact match count");
+                const jumpStart = performance.now();
+                const jump = await window.codePreviewPrototype.jumpDocument(ordinal);
+                await new Promise(requestAnimationFrame);
+                await new Promise(requestAnimationFrame);
+                const navigationMs = performance.now() - jumpStart;
+                maximumTaskServiceGapMs = Math.max(maximumTaskServiceGapMs, performance.now() - previous);
+                return {
+                  loadMs,
+                  searchMs,
+                  warmSearchMs,
+                  navigationMs,
+                  maximumTaskServiceGapMs,
+                  exactCount: result.count,
+                  pending: jump.pending,
+                  ...window.codePreviewPrototype.stats(),
+                };
+              } finally {
+                clearInterval(timer);
+              }
+            },
+            { source: fixture.source, query: fixture.query, ordinal: fixture.expected - 1 }
+          );
+          assert.equal(measurement.exactCount, fixture.expected);
+          assert.equal(measurement.pending, false);
+          assert.equal(measurement.syntaxError, null);
+          assert.ok(measurement.peakCachedSyntaxRanges <= measurement.syntaxCacheLimit);
+          const heap = cdp ? await cdp.send("Runtime.getHeapUsage") : null;
+          const dom = cdp ? await cdp.send("Memory.getDOMCounters") : null;
+          report.scaling.push({
+            width,
+            fixture: fixture.name,
+            units: fixture.units,
+            sourceUnits: fixture.source.length,
+            trial,
+            workerCache: "cold",
+            measurement,
+            loadedRendererSnapshot: cdp ? { ...heap, ...dom } : null,
+            memoryScope: "Loaded main-renderer snapshot only; not peak allocation or worker/native/process memory",
+          });
+        } catch (error) {
+          const failure = {
+            width,
+            fixture: fixture.name,
+            units: fixture.units,
+            sourceUnits: fixture.source.length,
+            trial,
+            error: error instanceof Error ? error.message : String(error),
+          };
+          report.scaling.push(failure);
+          report.blockers.push({ ...failure, scope: "Exploratory scaling failure; this size is not accepted as supported" });
+        }
+      }
+  } finally {
+    await page.evaluate(() => window.codePreviewPrototype.shutdownDocument());
+    if (cdp) await cdp.detach();
+  }
+}
+
+async function runDocumentSearchProof(page, report, width) {
+  await page.evaluate(() =>
+    window.codePreviewPrototype.loadDocument(
+      `# Search target\n\nA **bold** word. Next.\n\nOther paragraph.\n\n${"Repeated needle.\n\n".repeat(1_200)}\n\`\`\`text\n${"x".repeat(2_047)}\u{1f30d} edge\n\`\`\`\n\nWord word sword\n\n${"a".repeat(128)}!`
+    )
+  );
+  const search = await page.evaluate(async () => {
+    const api = window.codePreviewPrototype;
+    const container = document.querySelector("[data-markdown-document]");
+    const text = container.querySelector("h1").firstChild;
+    const selection = window.getSelection();
+    const range = new Range();
+    range.setStart(text, 0);
+    range.setEnd(text, 6);
+    selection.removeAllRanges();
+    selection.addRange(range);
+    const cases = [];
+    for (const [query, options] of [
+      ["bold word", {}],
+      ["bold\\s+word", { regexp: true }],
+      ["Next.\nOther", {}],
+      ["\u{1f30d} edge", {}],
+      ["word", { wholeWord: true }],
+      ["Word", { wholeWord: true, caseSensitive: true }],
+      ["(?=word)", { regexp: true }],
+      ["", {}],
+    ]) {
+      const result = await api.searchDocument(query, options);
+      const highlight = CSS.highlights.get("document-search")?.values().next().value;
+      cases.push({ query, count: result.count, text: highlight?.toString() ?? null, cached: result.matches.length });
+    }
+    const workersBefore = window.documentWorkers.length;
+    const result = await api.searchDocument("needle");
+    const last = await api.jumpDocument(1_199);
+    const active = api.stats().activeMatch;
+    const highlight = CSS.highlights.get("document-search").values().next().value;
+    const rect = highlight.getBoundingClientRect();
+    const viewport = container.getBoundingClientRect();
+    const lastVisible = rect.bottom > viewport.top && rect.top < viewport.bottom;
+    const lateWindow = api.stats().search.cachedMatches;
+    await api.jumpDocument(1_198);
+    await api.jumpDocument(0);
+    const stableSelection = selection.anchorNode === text && selection.focusNode === text && selection.toString() === "Search";
+    selection.removeAllRanges();
+    return {
+      cases,
+      count: result.count,
+      windowSize: result.matches.length,
+      last,
+      active,
+      lastVisible,
+      lateWindow,
+      reusedIndex: window.documentWorkers.length === workersBefore,
+      stableSelection,
+    };
+  });
+  assert.deepEqual(
+    search.cases.map((result) => result.count),
+    [1, 1, 1, 1, 3, 1, 4, 0]
+  );
+  assert.equal(search.cases[0].text, "bold word");
+  assert.equal(search.cases[3].text, "\u{1f30d} edge");
+  assert.equal(search.count, 1_200);
+  assert.equal(search.windowSize, 64);
+  assert.equal(search.last.pending, false);
+  assert.equal(search.active.ordinal, 1_199);
+  assert.equal(search.lastVisible, true);
+  assert.ok(search.lateWindow <= 64);
+  assert.equal(search.reusedIndex, true);
+  assert.equal(search.stableSelection, true);
+  const invalid = await page.evaluate(async () => {
+    try {
+      await window.codePreviewPrototype.searchDocument("[", { regexp: true });
+      return null;
+    } catch (error) {
+      return { error: error.message, stats: window.codePreviewPrototype.stats().search };
+    }
+  });
+  assert.match(invalid.error, /Invalid document search expression/);
+  assert.equal(invalid.stats.complete, false);
+  assert.equal(invalid.stats.count, null);
+  const supersession = await page.evaluate(async () => {
+    const obsolete = window.codePreviewPrototype.searchDocument("needle").then(
+      () => "complete",
+      (error) => error.name
+    );
+    const latest = await window.codePreviewPrototype.searchDocument("bold word");
+    return { obsolete: await obsolete, count: latest.count, text: CSS.highlights.get("document-search").values().next().value.toString() };
+  });
+  assert.equal(supersession.obsolete, "AbortError");
+  assert.equal(supersession.count, 1);
+  assert.equal(supersession.text, "bold word");
+  await page.evaluate(() => {
+    const input = document.createElement("input");
+    input.id = "regex-input-probe";
+    document.body.prepend(input);
+    window.regexInputStates = [];
+    input.addEventListener("input", () => window.regexInputStates.push(window.codePreviewPrototype.stats().search.complete));
+    const start = performance.now();
+    window.regexOutcome = null;
+    window.codePreviewPrototype.searchDocument("(a+)+$", { regexp: true }).then(
+      () => {
+        window.regexOutcome = { unexpected: true };
+      },
+      (error) => {
+        window.regexOutcome = {
+          error: error.message,
+          elapsedMs: performance.now() - start,
+          terminated: window.documentWorkers.at(-1).terminated,
+        };
+      }
+    );
+  });
+  await page.locator("#regex-input-probe").pressSequentially("responsive");
+  await page.waitForFunction(() => window.regexOutcome !== null);
+  const deadline = await page.evaluate(async () => {
+    const result = window.regexOutcome;
+    const stats = window.codePreviewPrototype.stats().search;
+    const inputServiced = window.regexInputStates.some((complete) => !complete);
+    document.getElementById("regex-input-probe").remove();
+    const recovered = await window.codePreviewPrototype.searchDocument("needle");
+    return { ...result, stats, inputServiced, recoveredCount: recovered.count };
+  });
+  assert.match(deadline.error, /deadline; worker terminated/);
+  assert.equal(deadline.terminated, true);
+  assert.equal(deadline.stats.count, null);
+  assert.equal(deadline.stats.complete, false);
+  assert.equal(deadline.inputServiced, true);
+  assert.equal(deadline.recoveredCount, 1_200);
+  await page.evaluate(() => {
+    window.pauseDocumentPublication = true;
+    window.pendingDocumentLoad = window.codePreviewPrototype
+      .loadDocument(`# Partial search\n\n${"Paragraph **text**.\n\n".repeat(1_500)}\n\nUnpublished-target.`)
+      .then(
+        () => "complete",
+        (error) => error.name
+      );
+  });
+  await page.waitForFunction(() => !!window.resumeDocumentPublication && window.codePreviewPrototype.stats().batches > 0);
+  const pending = await page.evaluate(async () => {
+    const api = window.codePreviewPrototype;
+    const count = (await api.searchDocument("Unpublished-target")).count;
+    const navigation = await api.jumpDocument(0);
+    const before = { ...api.stats().activeMatch };
+    window.pauseDocumentPublication = false;
+    window.resumeDocumentPublication();
+    window.resumeDocumentPublication = null;
+    const outcome = await window.pendingDocumentLoad;
+    await new Promise(requestAnimationFrame);
+    await new Promise(requestAnimationFrame);
+    const range = CSS.highlights.get("document-search").values().next().value;
+    const rect = range.getBoundingClientRect();
+    const viewport = document.querySelector("[data-markdown-document]").getBoundingClientRect();
+    return {
+      count,
+      navigation,
+      before,
+      outcome,
+      after: api.stats().activeMatch,
+      text: range.toString(),
+      visible: rect.bottom > viewport.top && rect.top < viewport.bottom,
+    };
+  });
+  assert.equal(pending.count, 1);
+  assert.equal(pending.navigation.pending, true);
+  assert.equal(pending.before.pending, true);
+  assert.equal(pending.outcome, "complete");
+  assert.equal(pending.after.pending, false);
+  assert.equal(pending.text, "Unpublished-target");
+  assert.equal(pending.visible, true);
+  const shutdown = await page.evaluate(async () => {
+    const obsolete = window.codePreviewPrototype.searchDocument("Paragraph").then(
+      () => "complete",
+      (error) => error.name
+    );
+    window.codePreviewPrototype.shutdownDocument();
+    return {
+      outcome: await obsolete,
+      highlights: [...CSS.highlights.keys()].filter((name) => name.startsWith("document-")).length,
+      workersTerminated: window.documentWorkers.every((entry) => entry.terminated),
+    };
+  });
+  assert.equal(shutdown.outcome, "AbortError");
+  assert.equal(shutdown.highlights, 0);
+  assert.equal(shutdown.workersTerminated, true);
+  report.interactions.push({ width, mode: "whole-markdown-search", search, invalid, supersession, deadline, pending, shutdown });
+}
diff --git a/frontend/scripts/markdown-preview-performance-proof.mjs b/frontend/scripts/markdown-preview-performance-proof.mjs
new file mode 100644
index 000000000..63aec6d9c
--- /dev/null
+++ b/frontend/scripts/markdown-preview-performance-proof.mjs
@@ -0,0 +1,1043 @@
+import assert from "node:assert/strict";
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { extname, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { chromium, firefox } from "playwright";
+import { build } from "vite";
+import { documentHostBudgetFailures, runMarkdownDocumentProof } from "./markdown-document-performance-proof.mjs";
+
+const FRONTEND = fileURLToPath(new URL("..", import.meta.url));
+const APPROVED_URL = "http://localhost:3000/browse/smb/demo";
+const ASSET_PREFIX = "/__markdown_preview_proof__/";
+const MAX_MOUNTED_ROWS = 40;
+const MAX_MOUNTED_SPANS = 4_000;
+const NATIVE_FIND_TARGET = "sambee-native-find-target";
+const RENDER_MODES = {
+  full: false,
+  virtual: true,
+  "retained-text": "retained-text",
+  "retained-text-worker": "retained-text-worker",
+  "retained-text-worker-progressive": "retained-text-worker-progressive",
+};
+const BROWSERS = { chromium, firefox };
+const browserName = process.env.SAMBEE_PREVIEW_PROOF_BROWSER ?? "chromium";
+assert.ok(Object.keys(BROWSERS).includes(browserName), "Unknown proof browser");
+const modeNames = (process.env.SAMBEE_PREVIEW_PROOF_MODES ?? "full,virtual,retained-text").split(",");
+assert.ok(modeNames.length > 0 && modeNames.every((name) => Object.keys(RENDER_MODES).includes(name)), "Unknown proof rendering mode");
+const output = await mkdtemp(resolve(tmpdir(), "sambee-preview-proof-"));
+const documentProof = process.env.SAMBEE_PREVIEW_PROOF_DOCUMENT === "1";
+const budgetProof = process.env.SAMBEE_PREVIEW_PROOF_BUDGETS === "1";
+assert.ok(
+  !budgetProof || (documentProof && process.env.SAMBEE_PREVIEW_PROOF_SCALE === "1"),
+  "Host budgets require whole-document scaling mode"
+);
+let browser;
+const failures = [];
+const report = {
+  kind: "P1 production-built code-only prototype; NOT live-viewer acceptance",
+  modes: modeNames,
+  browserName,
+  measurements: [],
+  interactions: [],
+  blockers: [],
+};
+
+try {
+  browser = await BROWSERS[browserName].launch({ headless: true });
+  report.browser = browser.version();
+  await build({
+    base: ASSET_PREFIX,
+    resolve: { conditions: ["worker", "module", "browser", "production"] },
+    worker: {
+      format: "es",
+      plugins: () => [
+        {
+          name: "preview-worker-diagnostics",
+          enforce: "pre",
+          resolveId(source, importer) {
+            if (source === "../services/logger" && importer?.endsWith("/utils/codeMirrorHighlighting.ts")) {
+              return resolve(FRONTEND, "scripts/prototypes/markdownCodePreparation.worker.ts");
+            }
+          },
+        },
+      ],
+    },
+    root: FRONTEND,
+    configFile: resolve(FRONTEND, "vite.config.ts"),
+    logLevel: "warn",
+    build: {
+      sourcemap: true,
+      outDir: output,
+      emptyOutDir: true,
+      minify: true,
+      rollupOptions: {
+        input: resolve(FRONTEND, "scripts/prototypes/markdownCodePreview.tsx"),
+        output: { entryFileNames: "entry.js", manualChunks: undefined },
+      },
+    },
+  });
+  for (const width of [1543, 390]) {
+    const page = await browser.newPage({ viewport: { width, height: 900 } });
+    page.on("pageerror", (error) => failures.push(error.message));
+    await page.route(`**${ASSET_PREFIX}**`, async (route) => {
+      const pathname = new URL(route.request().url()).pathname;
+      if (pathname === `${ASSET_PREFIX}fixture.png`)
+        return route.fulfill({
+          contentType: "image/png",
+          body: Buffer.from("iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+aoykAAAAASUVORK5CYII=", "base64"),
+        });
+      const path = resolve(output, decodeURIComponent(pathname.slice(ASSET_PREFIX.length)));
+      if (!path.startsWith(`${output}${sep}`)) return route.abort();
+      try {
+        await route.fulfill({ body: await readFile(path), contentType: extname(path) === ".css" ? "text/css" : "text/javascript" });
+      } catch {
+        failures.push(`Prototype asset missing: ${pathname}`);
+        await route.abort();
+      }
+    });
+    await page.route(APPROVED_URL, (route) =>
+      route.fulfill({
+        contentType: "text/html",
+        body: `<!doctype html><html lang="en"><meta name="viewport" content="width=device-width, initial-scale=1"><title>P1 code preview proof</title><body><main id="prototype"></main><script type="module" src="${ASSET_PREFIX}entry.js"></script></body></html>`,
+      })
+    );
+    await page.goto(APPROVED_URL);
+    await page.waitForFunction(() => Boolean(window.codePreviewPrototype));
+    if (documentProof) {
+      report.kind = "P1 production-built whole-Markdown prototype; NOT live-viewer acceptance";
+      await runMarkdownDocumentProof(page, report, width);
+      await page.screenshot({ path: resolve(output, `document-${width}.png`) });
+      await page.close();
+      continue;
+    }
+    const fixtures = [
+      { name: "dense", blocks: ["let x=1;\n".repeat(6_000)] },
+      { name: "near-safeguard", blocks: ["let x=1;\n".repeat(11_111)] },
+      { name: "many-blocks", blocks: Array.from({ length: 600 }, () => "let x=1;\n".repeat(101)) },
+      {
+        name: "whitespace",
+        blocks: ["let x = '\u{1f30d}';\t  // preserve  spaces\n".repeat(37), `${" \t\n\nlet x = 2;\r\n".repeat(25)}end`],
+      },
+    ];
+    for (const fixture of fixtures) {
+      for (const modeName of modeNames) {
+        const virtual = RENDER_MODES[modeName];
+        await page.goto(APPROVED_URL);
+        await page.waitForFunction(() => Boolean(window.codePreviewPrototype));
+        for (const cache of ["cold", "cached"]) {
+          const measurement = await page.evaluate(
+            async ({ blocks, virtual }) => {
+              const start = performance.now();
+              const longTasks = [];
+              const taskServiceGaps = [];
+              let lastTaskAt = start;
+              let taskProbeTimer;
+              const probeTask = () => {
+                const now = performance.now();
+                taskServiceGaps.push(now - lastTaskAt);
+                lastTaskAt = now;
+                taskProbeTimer = setTimeout(probeTask, 0);
+              };
+              taskProbeTimer = setTimeout(probeTask, 0);
+              const longTaskObservationSupported = PerformanceObserver.supportedEntryTypes.includes("longtask");
+              const observer = new PerformanceObserver((list) => {
+                longTasks.push(...list.getEntries().map((entry) => entry.duration));
+              });
+              if (longTaskObservationSupported) observer.observe({ type: "longtask", buffered: false });
+              await window.codePreviewPrototype.load(blocks, virtual);
+              await new Promise(requestAnimationFrame);
+              await new Promise(requestAnimationFrame);
+              longTasks.push(...observer.takeRecords().map((entry) => entry.duration));
+              observer.disconnect();
+              clearTimeout(taskProbeTimer);
+              taskServiceGaps.push(performance.now() - lastTaskAt);
+              return {
+                ...window.codePreviewPrototype.stats(),
+                loadToPaintMs: performance.now() - start,
+                longTasks,
+                longTaskObservationSupported,
+                taskServiceProbeCount: taskServiceGaps.length,
+                maximumTaskServiceGapMs: Math.max(...taskServiceGaps),
+              };
+            },
+            { blocks: fixture.blocks, virtual }
+          );
+          assert.equal(measurement.sourceUnits, fixture.blocks.join("").length);
+          assert.equal(measurement.matchCount, fixture.blocks.join("").split("let x").length - 1);
+          assert.equal(measurement.oversizedLines, 0);
+          if (virtual === true) {
+            assert.ok(measurement.mountedRows > 0 && measurement.mountedRows <= MAX_MOUNTED_ROWS, JSON.stringify(measurement));
+            assert.ok(measurement.mountedSpans <= MAX_MOUNTED_SPANS, JSON.stringify(measurement));
+            assert.ok(measurement.mountedTextUnits < measurement.sourceUnits);
+          } else {
+            assert.equal(measurement.mountedTextUnits, measurement.sourceUnits);
+          }
+          if (typeof virtual === "string") {
+            assert.equal(measurement.execution, virtual.startsWith("retained-text-worker") ? "worker" : "main-thread");
+            assert.equal(measurement.preparationComplete, true);
+            assert.equal(measurement.searchComplete, true);
+            if (virtual === "retained-text-worker-progressive" && fixture.name !== "whitespace") {
+              assert.ok(measurement.sourceIndexingYields > 0);
+            }
+            if (virtual.startsWith("retained-text-worker")) {
+              assert.equal(measurement.sourceUnitsSent, measurement.sourceUnits);
+              assert.equal(
+                measurement.sourceChunks,
+                fixture.blocks.reduce((count, text) => count + Math.max(1, Math.ceil(text.length / measurement.sourceChunkLimit)), 0)
+              );
+              assert.ok(measurement.largestSourceChunkUnits <= measurement.sourceChunkLimit);
+              assert.ok(measurement.transferChunks > 0);
+              assert.ok(measurement.largestChunkItems > 0 && measurement.largestChunkItems <= measurement.transferChunkLimit);
+            }
+            assert.equal(measurement.publicationComplete, true);
+            assert.equal(measurement.publishedRows, measurement.totalRows);
+            assert.ok(measurement.largestPublicationBatch <= measurement.publicationBatchLimit);
+            assert.equal(measurement.publicationBatches, Math.max(1, Math.ceil(measurement.totalRows / measurement.publicationBatchLimit)));
+          }
+          const jumps = [];
+          if (virtual) {
+            for (const ordinal of [measurement.matchCount - 1, 0, Math.floor(measurement.matchCount / 2)]) {
+              const start = performance.now();
+              await page.evaluate((target) => window.codePreviewPrototype.jump(target), ordinal);
+              await page.waitForFunction((target) => {
+                const stats = window.codePreviewPrototype.stats();
+                return stats.active === target && stats.activeMounted;
+              }, ordinal);
+              const stats = await page.evaluate(() => window.codePreviewPrototype.stats());
+              if (virtual === true) assert.ok(stats.mountedRows <= MAX_MOUNTED_ROWS, JSON.stringify(stats));
+              else {
+                assert.ok(stats.decoratedRows <= MAX_MOUNTED_ROWS, JSON.stringify(stats));
+                assert.ok(stats.highlightRanges <= MAX_MOUNTED_SPANS, JSON.stringify(stats));
+              }
+              jumps.push({ ordinal, commandToObservedMs: performance.now() - start });
+            }
+            await page.setViewportSize({ width: width === 390 ? 1543 : 390, height: 900 });
+            await page.waitForFunction(() => window.codePreviewPrototype.stats().activeMounted);
+            await page.setViewportSize({ width, height: 900 });
+            const nativeSelection = await page.evaluate((blocks) => {
+              const selection = window.getSelection();
+              const container = document.querySelector("[data-prototype-scroll]");
+              const candidateHeight = container.scrollHeight;
+              selection.selectAllChildren(container);
+              const text = selection.toString();
+              const baseline = document.createElement("div");
+              for (const block of blocks) {
+                const pre = document.createElement("pre");
+                pre.style.margin = "0";
+                pre.style.whiteSpace = "pre-wrap";
+                pre.style.overflowWrap = "anywhere";
+                pre.style.fontSize = "14px";
+                pre.style.lineHeight = "20px";
+                pre.textContent = block;
+                baseline.append(pre);
+              }
+              document.body.append(baseline);
+              baseline.style.width = `${container.clientWidth}px`;
+              const baselineHeight = baseline.getBoundingClientRect().height;
+              selection.selectAllChildren(baseline);
+              const expected = selection.toString();
+              selection.removeAllRanges();
+              baseline.remove();
+              let uncontainedSelection = null;
+              if (text !== expected && container.hasAttribute("data-retained-text")) {
+                const style = document.createElement("style");
+                style.textContent = "[data-retained-text] pre{content-visibility:visible!important}";
+                document.head.append(style);
+                selection.selectAllChildren(container);
+                uncontainedSelection = { units: selection.toString().length, exact: selection.toString() === expected };
+                selection.removeAllRanges();
+                style.remove();
+              }
+              return {
+                units: text.length,
+                baselineUnits: expected.length,
+                exact: text === expected,
+                exactDomText: container.textContent === blocks.join(""),
+                uncontainedSelection,
+                candidateHeight,
+                baselineHeight,
+              };
+            }, fixture.blocks);
+            report.interactions.push({
+              fixture: fixture.name,
+              width,
+              mode: modeName,
+              nativeSelection,
+              modelUnits: measurement.sourceUnits,
+            });
+            if (typeof virtual === "string") {
+              assert.equal(nativeSelection.exact, true, JSON.stringify(nativeSelection));
+              assert.equal(nativeSelection.exactDomText, true);
+              assert.equal(nativeSelection.candidateHeight, Math.max(480, nativeSelection.baselineHeight));
+              if (fixture.name !== "whitespace") {
+                const expectedHeight = fixture.blocks.join("").split("\n").length - 1;
+                assert.equal(nativeSelection.candidateHeight, Math.max(480, expectedHeight * 20));
+              }
+            }
+          }
+          report.measurements.push({ fixture: fixture.name, width, virtual, cache, ...measurement, jumps });
+        }
+      }
+    }
+    for (const retainedMode of modeNames.filter((name) => typeof RENDER_MODES[name] === "string")) {
+      if (retainedMode === "retained-text-worker-progressive") {
+        const indexingSupersession = await page.evaluate(async (mode) => {
+          const nativePostMessage = Worker.prototype.postMessage;
+          const workerJobs = [];
+          Worker.prototype.postMessage = function (message, ...args) {
+            if (message.type === "prepare") workerJobs.push(message.generation);
+            return nativePostMessage.call(this, message, ...args);
+          };
+          try {
+            const obsolete = window.codePreviewPrototype.load(["let x=0;\n".repeat(6_000)], mode).then(
+              () => "complete",
+              (error) => error.name
+            );
+            await window.codePreviewPrototype.load(["let x=1;\n"], mode);
+            return {
+              obsolete: await obsolete,
+              workerJobs,
+              stats: window.codePreviewPrototype.stats(),
+              text: document.querySelector("[data-retained-text]").textContent,
+            };
+          } finally {
+            Worker.prototype.postMessage = nativePostMessage;
+          }
+        }, retainedMode);
+        assert.equal(indexingSupersession.obsolete, "AbortError");
+        assert.deepEqual(indexingSupersession.workerJobs, [indexingSupersession.stats.generation]);
+        assert.equal(indexingSupersession.text, "let x=1;\n");
+        report.interactions.push({ width, mode: retainedMode, indexingSupersession });
+        await page.evaluate(
+          ({ blocks, mode }) => {
+            const nativePostMessage = Worker.prototype.postMessage;
+            Worker.prototype.postMessage = function (message, ...args) {
+              if (message.type === "run") {
+                window.releaseProgressiveWorker = () => {
+                  Worker.prototype.postMessage = nativePostMessage;
+                  nativePostMessage.call(this, message, ...args);
+                };
+                return;
+              }
+              return nativePostMessage.call(this, message, ...args);
+            };
+            const input = document.createElement("input");
+            input.id = "progressive-input-probe";
+            document.body.prepend(input);
+            window.progressiveInputEvents = [];
+            input.addEventListener("input", () =>
+              window.progressiveInputEvents.push(window.codePreviewPrototype.stats().preparationComplete)
+            );
+            window.progressiveOutcome = window.codePreviewPrototype.load(blocks, mode).then(
+              () => "complete",
+              (error) => error.name
+            );
+          },
+          { blocks: fixtures.find((fixture) => fixture.name === "many-blocks").blocks, mode: retainedMode }
+        );
+        await page.waitForFunction(
+          () =>
+            window.releaseProgressiveWorker &&
+            window.codePreviewPrototype.stats().publishedRows > 0 &&
+            !window.codePreviewPrototype.stats().preparationComplete
+        );
+        await page.locator("#progressive-input-probe").pressSequentially("responsive");
+        const beforePreparation = await page.evaluate(async () => {
+          await new Promise(requestAnimationFrame);
+          await new Promise(requestAnimationFrame);
+          const firstText = document.querySelector("[data-retained-text] [data-index]").firstChild;
+          const selection = window.getSelection();
+          const range = new Range();
+          range.setStart(firstText, 0);
+          range.setEnd(firstText, 5);
+          selection.removeAllRanges();
+          selection.addRange(range);
+          window.progressiveFirstText = firstText;
+          let pendingSearch;
+          try {
+            window.codePreviewPrototype.jump(0);
+          } catch (error) {
+            pendingSearch = error.message;
+          }
+          return {
+            ...window.codePreviewPrototype.stats(),
+            pendingSearch,
+            inputEvents: window.progressiveInputEvents,
+            inputValue: document.getElementById("progressive-input-probe").value,
+          };
+        });
+        assert.equal(beforePreparation.preparationComplete, false);
+        assert.equal(beforePreparation.searchComplete, false);
+        assert.ok(beforePreparation.mountedTextUnits > 0);
+        assert.match(beforePreparation.pendingSearch, /search preparation is pending/);
+        assert.equal(beforePreparation.inputValue, "responsive");
+        assert.ok(beforePreparation.inputEvents.length > 0 && beforePreparation.inputEvents.every((complete) => !complete));
+        const afterPreparation = await page.evaluate(async () => {
+          window.releaseProgressiveWorker();
+          const outcome = await window.progressiveOutcome;
+          await new Promise(requestAnimationFrame);
+          await new Promise(requestAnimationFrame);
+          const firstText = window.progressiveFirstText;
+          const selection = window.getSelection();
+          const result = {
+            ...window.codePreviewPrototype.stats(),
+            outcome,
+            textNodeStable: document.querySelector("[data-retained-text] [data-index]").firstChild === firstText,
+            selectionStable: selection.anchorNode === firstText && selection.focusNode === firstText && selection.toString() === "let x",
+            exactText: document.querySelector("[data-retained-text]").textContent === "let x=1;\n".repeat(600 * 101),
+          };
+          selection.removeAllRanges();
+          document.getElementById("progressive-input-probe").remove();
+          delete window.progressiveFirstText;
+          delete window.releaseProgressiveWorker;
+          return result;
+        });
+        assert.equal(afterPreparation.outcome, "complete");
+        assert.equal(afterPreparation.preparationComplete, true);
+        assert.equal(afterPreparation.searchComplete, true);
+        assert.equal(afterPreparation.textNodeStable, true);
+        assert.equal(afterPreparation.selectionStable, true);
+        assert.equal(afterPreparation.exactText, true);
+        assert.equal(afterPreparation.matchCount, 600 * 101);
+        assert.ok(afterPreparation.highlightRanges > 0);
+        report.interactions.push({ width, mode: retainedMode, beforePreparation, afterPreparation });
+
+        const progressiveFailure = await page.evaluate(async (mode) => {
+          const nativePostMessage = Worker.prototype.postMessage;
+          Worker.prototype.postMessage = function (message, ...args) {
+            if (message.type === "run") {
+              Worker.prototype.postMessage = nativePostMessage;
+              queueMicrotask(() => this.dispatchEvent(new ErrorEvent("error", { message: "proof progressive failure", cancelable: true })));
+              return;
+            }
+            return nativePostMessage.call(this, message, ...args);
+          };
+          try {
+            let outcome;
+            try {
+              await window.codePreviewPrototype.load(["let x=7;\n"], mode);
+              outcome = "unexpected success";
+            } catch (error) {
+              outcome = error.message;
+            }
+            return {
+              outcome,
+              stats: window.codePreviewPrototype.stats(),
+              text: document.querySelector("[data-retained-text]").textContent,
+            };
+          } finally {
+            Worker.prototype.postMessage = nativePostMessage;
+          }
+        }, retainedMode);
+        assert.match(progressiveFailure.outcome, /proof progressive failure/);
+        assert.match(progressiveFailure.stats.preparationError, /proof progressive failure/);
+        assert.equal(progressiveFailure.stats.preparationComplete, false);
+        assert.equal(progressiveFailure.stats.searchComplete, false);
+        assert.equal(progressiveFailure.stats.publicationComplete, true);
+        assert.equal(progressiveFailure.text, "let x=7;\n");
+
+        await page.evaluate((mode) => {
+          const nativePostMessage = Worker.prototype.postMessage;
+          Worker.prototype.postMessage = function (message, ...args) {
+            if (message.type === "run") {
+              Worker.prototype.postMessage = nativePostMessage;
+              const listener = this.onmessage;
+              window.deliverObsoleteProgressiveResult = () =>
+                listener.call(
+                  this,
+                  new MessageEvent("message", {
+                    data: { type: "complete", generation: message.generation, preparationMs: 0, indexingMs: 0 },
+                  })
+                );
+              return;
+            }
+            return nativePostMessage.call(this, message, ...args);
+          };
+          window.obsoleteProgressiveOutcome = window.codePreviewPrototype.load(["let x=8;\n".repeat(6_000)], mode).then(
+            () => "complete",
+            (error) => error.name
+          );
+        }, retainedMode);
+        await page.waitForFunction(
+          () =>
+            window.deliverObsoleteProgressiveResult &&
+            !window.codePreviewPrototype.stats().preparationComplete &&
+            window.codePreviewPrototype.stats().publishedRows > 0
+        );
+        const progressiveSupersession = await page.evaluate(async (mode) => {
+          const firstText = document.querySelector("[data-retained-text] [data-index]").firstChild;
+          const obsoleteGeneration = window.codePreviewPrototype.stats().generation;
+          await window.codePreviewPrototype.load(["let x=9;\n"], mode);
+          const outcome = await window.obsoleteProgressiveOutcome;
+          window.deliverObsoleteProgressiveResult();
+          await new Promise(requestAnimationFrame);
+          await new Promise(requestAnimationFrame);
+          delete window.deliverObsoleteProgressiveResult;
+          return {
+            outcome,
+            obsoleteGeneration,
+            stats: window.codePreviewPrototype.stats(),
+            oldTextDetached: !firstText.isConnected,
+            text: document.querySelector("[data-retained-text]").textContent,
+          };
+        }, retainedMode);
+        assert.equal(progressiveSupersession.outcome, "AbortError");
+        assert.ok(progressiveSupersession.stats.generation > progressiveSupersession.obsoleteGeneration);
+        assert.equal(progressiveSupersession.stats.preparationComplete, true);
+        assert.equal(progressiveSupersession.stats.preparationError, null);
+        assert.equal(progressiveSupersession.oldTextDetached, true);
+        assert.equal(progressiveSupersession.text, "let x=9;\n");
+        report.interactions.push({ width, mode: retainedMode, progressiveFailure, progressiveSupersession });
+      } else {
+        await page.evaluate(
+          ({ blocks, mode }) => {
+            const input = document.createElement("input");
+            input.id = "publication-input-probe";
+            document.body.prepend(input);
+            window.publicationInputEvents = [];
+            input.addEventListener("input", () => {
+              const stats = window.codePreviewPrototype.stats();
+              window.publicationInputEvents.push({
+                complete: stats.publicationComplete,
+                publishedRows: stats.publishedRows,
+                value: input.value,
+              });
+            });
+            window.publicationOutcome = window.codePreviewPrototype.load(blocks, mode).then(
+              () => ({ status: "complete" }),
+              (error) => ({ status: error.name })
+            );
+          },
+          { blocks: fixtures.find((fixture) => fixture.name === "many-blocks").blocks, mode: retainedMode }
+        );
+        await page.waitForFunction(() => {
+          const stats = window.codePreviewPrototype.stats();
+          return stats.totalRows === 4200 && stats.publishedRows > 0 && !stats.publicationComplete;
+        });
+        const selectionDuringPublication = await page.evaluate(async () => {
+          const firstText = document.querySelector("[data-retained-text] [data-index]").firstChild;
+          const selection = window.getSelection();
+          const range = new Range();
+          range.setStart(firstText, 0);
+          range.setEnd(firstText, 5);
+          selection.removeAllRanges();
+          selection.addRange(range);
+          const before = window.codePreviewPrototype.stats().publishedRows;
+          await new Promise(requestAnimationFrame);
+          await new Promise(requestAnimationFrame);
+          const after = window.codePreviewPrototype.stats().publishedRows;
+          const result = {
+            before,
+            after,
+            firstTextStable: document.querySelector("[data-retained-text] [data-index]").firstChild === firstText,
+            anchorStable: selection.anchorNode === firstText,
+            focusStable: selection.focusNode === firstText,
+            selected: selection.toString(),
+          };
+          selection.removeAllRanges();
+          return result;
+        });
+        assert.ok(selectionDuringPublication.after > selectionDuringPublication.before);
+        assert.equal(selectionDuringPublication.firstTextStable, true);
+        assert.equal(selectionDuringPublication.anchorStable, true);
+        assert.equal(selectionDuringPublication.focusStable, true);
+        assert.equal(selectionDuringPublication.selected, "let x");
+        report.interactions.push({ width, mode: retainedMode, selectionDuringPublication });
+        const pendingJump = await page.evaluate(() => {
+          const target = Math.floor(window.codePreviewPrototype.stats().matchCount / 2);
+          const supersededTarget = window.codePreviewPrototype.stats().matchCount - 1;
+          const superseded = window.codePreviewPrototype.jump(supersededTarget);
+          const result = window.codePreviewPrototype.jump(target);
+          const stats = window.codePreviewPrototype.stats();
+          return {
+            target,
+            supersededTarget,
+            supersededPending: superseded.pending,
+            pending: result.pending,
+            pendingMatch: stats.pendingMatch,
+            activeMounted: stats.activeMounted,
+            publicationBatchesAtRequest: stats.publicationBatches,
+          };
+        });
+        assert.equal(pendingJump.supersededPending, true);
+        assert.equal(pendingJump.pending, true);
+        assert.equal(pendingJump.pendingMatch, pendingJump.target);
+        assert.equal(pendingJump.activeMounted, false);
+        await page.waitForFunction((target) => {
+          const stats = window.codePreviewPrototype.stats();
+          return stats.active === target && stats.pendingMatch === null && stats.activeMounted;
+        }, pendingJump.target);
+        const priorityReveal = await page.evaluate(async () => {
+          const stats = window.codePreviewPrototype.stats();
+          const container = document.querySelector("[data-retained-text]");
+          const element = container.querySelector(`[data-index="${stats.activeRow}"]`);
+          const rect = element.getBoundingClientRect();
+          const viewport = container.getBoundingClientRect();
+          const textNode = element.firstChild;
+          const selection = window.getSelection();
+          const range = new Range();
+          range.setStart(textNode, 0);
+          range.setEnd(textNode, 5);
+          selection.removeAllRanges();
+          selection.addRange(range);
+          await new Promise(requestAnimationFrame);
+          await new Promise(requestAnimationFrame);
+          const result = {
+            publicationCompleteAtReveal: stats.publicationComplete,
+            publishedRowsAtReveal: stats.publishedRows,
+            publicationBatchesAtReveal: stats.publicationBatches,
+            totalRows: stats.totalRows,
+            targetVisible: rect.bottom > viewport.top && rect.top < viewport.bottom,
+            destinationTextStable: element.firstChild === textNode,
+            destinationSelectionStable:
+              selection.anchorNode === textNode && selection.focusNode === textNode && selection.toString() === "let x",
+            publishedRowsAfterSelection: window.codePreviewPrototype.stats().publishedRows,
+          };
+          selection.removeAllRanges();
+          return result;
+        });
+        assert.equal(priorityReveal.publicationCompleteAtReveal, false);
+        assert.ok(priorityReveal.publishedRowsAtReveal < priorityReveal.totalRows);
+        assert.equal(priorityReveal.targetVisible, true);
+        assert.equal(priorityReveal.destinationTextStable, true);
+        assert.equal(priorityReveal.destinationSelectionStable, true);
+        assert.ok(priorityReveal.publishedRowsAfterSelection > priorityReveal.publishedRowsAtReveal);
+        await page.locator("#publication-input-probe").pressSequentially("responsive");
+        const publicationInput = await page.evaluate(async () => {
+          const outcome = await window.publicationOutcome;
+          const events = window.publicationInputEvents;
+          const stats = window.codePreviewPrototype.stats();
+          document.getElementById("publication-input-probe").remove();
+          return { outcome, events, publicationBatches: stats.publicationBatches, publicationComplete: stats.publicationComplete };
+        });
+        assert.equal(publicationInput.outcome.status, "complete");
+        assert.equal(publicationInput.publicationComplete, true);
+        assert.ok(
+          publicationInput.events.some((event) => !event.complete),
+          JSON.stringify(publicationInput)
+        );
+        assert.equal(publicationInput.events.at(-1).value, "responsive");
+        await page.waitForFunction((target) => {
+          const stats = window.codePreviewPrototype.stats();
+          return stats.active === target && stats.pendingMatch === null && stats.activeMounted;
+        }, pendingJump.target);
+        const priorityCompletion = await page.evaluate(() => {
+          const stats = window.codePreviewPrototype.stats();
+          const container = document.querySelector("[data-retained-text]");
+          const indices = [...container.querySelectorAll("[data-index]")].map((element) => Number(element.dataset.index));
+          const target = container.querySelector(`[data-index="${stats.activeRow}"]`).getBoundingClientRect();
+          const viewport = container.getBoundingClientRect();
+          return {
+            priorityPublishedRows: stats.priorityPublishedRows,
+            exactOrder: indices.every((index, position) => index === position),
+            exactText: container.textContent === "let x=1;\n".repeat(600 * 101),
+            targetVisible: target.bottom > viewport.top && target.top < viewport.bottom,
+          };
+        });
+        assert.ok(priorityCompletion.priorityPublishedRows > 0);
+        assert.equal(priorityCompletion.exactOrder, true);
+        assert.equal(priorityCompletion.exactText, true);
+        assert.equal(priorityCompletion.targetVisible, true);
+        report.interactions.push({
+          width,
+          mode: retainedMode,
+          pendingJump,
+          pendingJumpRevealed: true,
+          priorityReveal,
+          priorityCompletion,
+        });
+        report.interactions.push({ width, mode: retainedMode, publicationInput });
+
+        const previousGeneration = await page.evaluate((mode) => {
+          const previous = window.codePreviewPrototype.stats().generation;
+          window.obsoletePublication = window.codePreviewPrototype.load(["let x=1;\n".repeat(11_111)], mode).then(
+            () => ({ status: "complete" }),
+            (error) => ({ status: error.name })
+          );
+          return previous;
+        }, retainedMode);
+        await page.waitForFunction((previous) => {
+          const stats = window.codePreviewPrototype.stats();
+          return stats.generation > previous && stats.publishedRows > 0 && !stats.publicationComplete;
+        }, previousGeneration);
+        const cancelledPublication = await page.evaluate(async (mode) => {
+          const firstText = document.querySelector("[data-retained-text] [data-index]").firstChild;
+          const obsoleteGeneration = window.codePreviewPrototype.stats().generation;
+          await window.codePreviewPrototype.load(["let x=2;\n"], mode);
+          const obsolete = await window.obsoletePublication;
+          await new Promise(requestAnimationFrame);
+          await new Promise(requestAnimationFrame);
+          return {
+            obsolete,
+            oldTextDetached: !firstText.isConnected,
+            generation: window.codePreviewPrototype.stats().generation,
+            obsoleteGeneration,
+            text: document.querySelector("[data-retained-text]").textContent,
+            publicationComplete: window.codePreviewPrototype.stats().publicationComplete,
+          };
+        }, retainedMode);
+        assert.equal(cancelledPublication.obsolete.status, "AbortError");
+        assert.equal(cancelledPublication.oldTextDetached, true);
+        assert.ok(cancelledPublication.generation > cancelledPublication.obsoleteGeneration);
+        assert.equal(cancelledPublication.text, "let x=2;\n");
+        assert.equal(cancelledPublication.publicationComplete, true);
+        report.interactions.push({ width, mode: retainedMode, cancelledPublication });
+
+        const cancelledPreparation = await page.evaluate(async (mode) => {
+          const obsolete = window.codePreviewPrototype.load(["let x=3;\n"], mode).then(
+            () => ({ status: "complete" }),
+            (error) => ({ status: error.name })
+          );
+          await window.codePreviewPrototype.load(["let x=4;\n"], mode);
+          return {
+            obsolete: await obsolete,
+            text: document.querySelector("[data-retained-text]").textContent,
+            publicationComplete: window.codePreviewPrototype.stats().publicationComplete,
+          };
+        }, retainedMode);
+        assert.equal(cancelledPreparation.obsolete.status, "AbortError");
+        assert.equal(cancelledPreparation.text, "let x=4;\n");
+        assert.equal(cancelledPreparation.publicationComplete, true);
+        report.interactions.push({ width, mode: retainedMode, cancelledPreparation });
+
+        if (retainedMode === "retained-text-worker") {
+          const workerRecovery = await page.evaluate(async (mode) => {
+            const NativeWorker = window.Worker;
+            const nativeTerminate = NativeWorker.prototype.terminate;
+            const nativePostMessage = NativeWorker.prototype.postMessage;
+            let sourceChunksSent = 0;
+            let firstSourceUnits = 0;
+            let notifyTransferStarted;
+            const transferStarted = new Promise((resolve) => {
+              notifyTransferStarted = resolve;
+            });
+            NativeWorker.prototype.postMessage = function (message, ...args) {
+              const result = nativePostMessage.call(this, message, ...args);
+              if (message.type === "source") {
+                sourceChunksSent += 1;
+                firstSourceUnits ||= message.text.length;
+                notifyTransferStarted();
+              }
+              return result;
+            };
+            let terminations = 0;
+            const outcomes = [];
+            NativeWorker.prototype.terminate = function () {
+              terminations += 1;
+              return nativeTerminate.call(this);
+            };
+            const outcome = async () => {
+              try {
+                await window.codePreviewPrototype.load(["let x=5;\n"], mode);
+                return "unexpected success";
+              } catch (error) {
+                return error.message;
+              }
+            };
+            try {
+              const obsolete = window.codePreviewPrototype.load(["let x=3;\n".repeat(11_111)], mode).catch((error) => error.name);
+              await Promise.race([
+                transferStarted,
+                obsolete.then(() => {
+                  throw new Error("Obsolete preparation settled before the transfer-cancellation probe");
+                }),
+              ]);
+              const sourceChunksAtCancellation = sourceChunksSent;
+              await window.codePreviewPrototype.load(["stable view\n"], "retained-text");
+              const cancellation = await obsolete;
+              const stableText = document.querySelector("[data-retained-text]").firstChild;
+              window.Worker = undefined;
+              outcomes.push(await outcome());
+              window.Worker = class {
+                constructor() {
+                  throw new Error("proof constructor failure");
+                }
+              };
+              outcomes.push(await outcome());
+              window.Worker = class extends NativeWorker {
+                constructor(...args) {
+                  super(...args);
+                  queueMicrotask(() => this.dispatchEvent(new ErrorEvent("error", { message: "proof worker crash", cancelable: true })));
+                }
+              };
+              outcomes.push(await outcome());
+              window.Worker = class extends NativeWorker {
+                constructor(...args) {
+                  super(...args);
+                  queueMicrotask(() => this.dispatchEvent(new Event("messageerror")));
+                }
+              };
+              outcomes.push(await outcome());
+              const stableViewPreserved =
+                stableText.isConnected && document.querySelector("[data-retained-text]").textContent === "stable view\n";
+              window.Worker = NativeWorker;
+              await window.codePreviewPrototype.load(["let x=6;\n"], mode);
+              return {
+                cancellation,
+                sourceChunksAtCancellation,
+                firstSourceUnits,
+                outcomes,
+                terminations,
+                stableViewPreserved,
+                text: document.querySelector("[data-retained-text]").textContent,
+              };
+            } finally {
+              window.Worker = NativeWorker;
+              NativeWorker.prototype.terminate = nativeTerminate;
+              NativeWorker.prototype.postMessage = nativePostMessage;
+            }
+          }, retainedMode);
+          report.interactions.push({ width, mode: retainedMode, workerRecovery });
+          assert.equal(workerRecovery.cancellation, "AbortError");
+          assert.equal(workerRecovery.sourceChunksAtCancellation, 1);
+          assert.ok(workerRecovery.firstSourceUnits > 0);
+          assert.ok(workerRecovery.terminations >= 3, JSON.stringify(workerRecovery));
+          assert.match(workerRecovery.outcomes[0], /unavailable; no main-thread fallback/);
+          assert.equal(workerRecovery.outcomes[1], "proof constructor failure");
+          assert.match(workerRecovery.outcomes[2], /proof worker crash/);
+          assert.match(workerRecovery.outcomes[3], /could not be decoded/);
+          assert.equal(workerRecovery.stableViewPreserved, true);
+          assert.equal(workerRecovery.text, "let x=6;\n");
+
+          const sourceBoundaryParity = await page.evaluate(async (mode) => {
+            const limit = window.codePreviewPrototype.stats().sourceChunkLimit;
+            const paddingLine = "// filler\n";
+            const padding = (units) => paddingLine.repeat(Math.floor(units / paddingLine.length)) + " ".repeat(units % paddingLine.length);
+            let source = `${padding(limit - 1 - "// ".length)}// \u{1f30d}\r\n`;
+            source += `${padding(2 * limit - 2 - source.length)}let x = 1;\r\n`;
+            source += `${padding(3 * limit - 1 - source.length)}\r\n// end\n`;
+            const blocks = ["", source, "", "let x = 2;\n", ""];
+            await window.codePreviewPrototype.load(blocks, "retained-text");
+            const expected = window.codePreviewPrototype.inspect();
+            await window.codePreviewPrototype.load(blocks, mode);
+            const actual = window.codePreviewPrototype.inspect();
+            const stats = window.codePreviewPrototype.stats();
+            const result = {
+              exactModels: JSON.stringify(actual.models) === JSON.stringify(expected.models),
+              exactMatches: JSON.stringify(actual.matches) === JSON.stringify(expected.matches),
+              exactDomText: document.querySelector("[data-retained-text]").textContent === blocks.join(""),
+              surrogateSplit: source.charCodeAt(limit - 1) === 0xd83c && source.charCodeAt(limit) === 0xdf0d,
+              querySplit: source.slice(2 * limit - 2, 2 * limit + 3) === "let x",
+              crlfSplit: source.slice(3 * limit - 1, 3 * limit + 1) === "\r\n",
+              chunks: stats.sourceChunks,
+              expectedChunks: blocks.reduce((count, text) => count + Math.max(1, Math.ceil(text.length / limit)), 0),
+            };
+            await window.codePreviewPrototype.load([], mode);
+            const empty = window.codePreviewPrototype.inspect();
+            const emptyStats = window.codePreviewPrototype.stats();
+            result.emptyDocument =
+              empty.models.length === 0 &&
+              empty.matches.length === 0 &&
+              emptyStats.sourceChunks === 0 &&
+              emptyStats.publicationComplete &&
+              document.querySelector("[data-retained-text]").textContent === "";
+            return result;
+          }, retainedMode);
+          report.interactions.push({ width, mode: retainedMode, sourceBoundaryParity });
+          for (const property of [
+            "exactModels",
+            "exactMatches",
+            "exactDomText",
+            "surrogateSplit",
+            "querySplit",
+            "crlfSplit",
+            "emptyDocument",
+          ]) {
+            assert.equal(sourceBoundaryParity[property], true, JSON.stringify(sourceBoundaryParity));
+          }
+          assert.equal(sourceBoundaryParity.chunks, sourceBoundaryParity.expectedChunks);
+        }
+      }
+      const interactionBlocks = [
+        `${"let x=1;\n".repeat(6_000)}// ${NATIVE_FIND_TARGET}\n`,
+        `${"let x=1; // wrapped text with tabs\tand Unicode \u{1f30d} ".repeat(20)}\n`.repeat(30),
+      ];
+      await page.evaluate(({ blocks, mode }) => window.codePreviewPrototype.load(blocks, mode), {
+        blocks: interactionBlocks,
+        mode: retainedMode,
+      });
+      await page.waitForFunction(() => window.codePreviewPrototype.stats().decoratedRows > 0);
+      const interaction = await page.evaluate(async (target) => {
+        const container = document.querySelector("[data-prototype-scroll]");
+        const root = document.getElementById("prototype");
+        const firstText = container.querySelector("[data-index]").firstChild;
+        const selection = window.getSelection();
+        const range = new Range();
+        range.setStart(firstText, 0);
+        range.setEnd(firstText, 5);
+        selection.removeAllRanges();
+        selection.addRange(range);
+        const anchor = selection.anchorNode;
+        const focus = selection.focusNode;
+        const selected = selection.toString();
+        root.style.setProperty("--sambee-syntax-keyword", "#13579b");
+        container.scrollTop = container.scrollHeight;
+        await new Promise(requestAnimationFrame);
+        await new Promise(requestAnimationFrame);
+        await new Promise(requestAnimationFrame);
+        const selectionStable = selection.anchorNode === anchor && selection.focusNode === focus && selection.toString() === selected;
+        const textNodeStable = container.querySelector("[data-index]").firstChild === firstText;
+        const keywordColor = getComputedStyle(root, "::highlight(preview-keyword)").color;
+        selection.removeAllRanges();
+        container.scrollTop = 0;
+        await new Promise(requestAnimationFrame);
+        await new Promise(requestAnimationFrame);
+        const findStart = performance.now();
+        const found = window.find(target, false, false, true);
+        const findMs = performance.now() - findStart;
+        await new Promise(requestAnimationFrame);
+        await new Promise(requestAnimationFrame);
+        const nativeFindSelection = selection.toString();
+        const findRange = selection.rangeCount ? selection.getRangeAt(0).getBoundingClientRect() : null;
+        const viewport = container.getBoundingClientRect();
+        const findVisible = Boolean(findRange && findRange.bottom > viewport.top && findRange.top < viewport.bottom);
+        selection.removeAllRanges();
+        const baselineStyle = document.createElement("style");
+        baselineStyle.textContent = "[data-retained-text] pre{content-visibility:visible!important}";
+        document.head.append(baselineStyle);
+        container.scrollTop = 0;
+        await new Promise(requestAnimationFrame);
+        await new Promise(requestAnimationFrame);
+        const baselineFound = window.find(target, false, false, true);
+        await new Promise(requestAnimationFrame);
+        await new Promise(requestAnimationFrame);
+        const baselineRange = selection.rangeCount ? selection.getRangeAt(0).getBoundingClientRect() : null;
+        const baselineVisible = Boolean(baselineRange && baselineRange.bottom > viewport.top && baselineRange.top < viewport.bottom);
+        selection.removeAllRanges();
+        baselineStyle.remove();
+        return {
+          selectionStable,
+          textNodeStable,
+          keywordColor,
+          found,
+          nativeFindSelection,
+          findVisible,
+          findMs,
+          baselineFound,
+          baselineVisible,
+        };
+      }, NATIVE_FIND_TARGET);
+      assert.equal(interaction.selectionStable, true);
+      assert.equal(interaction.textNodeStable, true);
+      assert.equal(interaction.keywordColor, "rgb(19, 87, 155)");
+      assert.equal(interaction.found, true);
+      assert.equal(interaction.nativeFindSelection, NATIVE_FIND_TARGET);
+      assert.equal(interaction.baselineFound, true);
+      assert.equal(interaction.findVisible, interaction.baselineVisible, JSON.stringify(interaction));
+      if (!interaction.findVisible)
+        report.blockers.push({
+          width,
+          nativeFindReveal: "Unverified: headless window.find selected but did not scroll in either contained or uncontained text",
+        });
+      const anchor = page.locator("[data-retained-text] [data-index]").last();
+      await anchor.evaluate((element) => {
+        element.id = "prototype-last-fragment";
+      });
+      await page.evaluate(() => {
+        history.replaceState(null, "", window.location.pathname + window.location.search);
+        window.location.hash = "prototype-last-fragment";
+      });
+      await page.waitForFunction(() => {
+        const last = document.getElementById("prototype-last-fragment").getBoundingClientRect();
+        const viewport = document.querySelector("[data-retained-text]").getBoundingClientRect();
+        return last.bottom > viewport.top && last.top < viewport.bottom;
+      });
+      await page.emulateMedia({ media: "print" });
+      const print = await page.evaluate(() => {
+        const container = document.querySelector("[data-retained-text]");
+        return {
+          text: container.textContent,
+          overflow: getComputedStyle(container).overflow,
+          allFragmentsVisible: [...container.querySelectorAll("[data-index]")].every(
+            (element) => getComputedStyle(element).contentVisibility === "visible"
+          ),
+          unclipped: container.clientHeight >= container.scrollHeight,
+        };
+      });
+      assert.equal(print.text, interactionBlocks.join(""));
+      assert.equal(print.overflow, "visible");
+      assert.equal(print.allFragmentsVisible, true);
+      assert.equal(print.unclipped, true);
+      await page.emulateMedia({ media: "screen" });
+      const readingTree = await page.locator("[data-retained-text]").ariaSnapshot();
+      assert.ok(readingTree.includes(NATIVE_FIND_TARGET));
+      report.interactions.push({
+        width,
+        mode: retainedMode,
+        ...interaction,
+        hashAnchorVisible: true,
+        accessibilityTreeIncludesOffscreenTarget: true,
+        printLayout: { exactText: true, unclipped: true },
+      });
+    }
+    await page.screenshot({ path: resolve(output, `preview-${width}.png`) });
+    if (modeNames.some((name) => typeof RENDER_MODES[name] === "string")) {
+      const cleanup = await page.evaluate(async () => {
+        const oldText = document.querySelector("[data-retained-text] [data-index]").firstChild;
+        await window.codePreviewPrototype.load([], true);
+        return {
+          detachedOldText: !oldText.isConnected,
+          remainingHighlightSets: [...CSS.highlights.keys()].filter((name) => name.startsWith("preview-")).length,
+        };
+      });
+      assert.equal(cleanup.detachedOldText, true);
+      assert.equal(cleanup.remainingHighlightSets, 0);
+      report.interactions.push({ width, mode: "retained-text", cleanup });
+    }
+    await page.close();
+  }
+  assert.deepEqual(failures, []);
+  if (budgetProof) {
+    report.hostBudgetFailures = documentHostBudgetFailures(report);
+    assert.deepEqual(report.hostBudgetFailures, [], "Approved provisional development-host budget gate failed; P1 remains open");
+    report.hostBudgetsPassed = true;
+  }
+  report.blockers.push(
+    "Retained-text with lightweight off-screen text DOM is the approved architecture direction; acceptance is not complete. Whole-Markdown search and regex deadline probes do not establish arbitrary-structure/layout or aggregate memory bounds, reference-device budgets, actual browser Find UI/assistive-technology behavior, production recovery policy, replacement behavior, or an accepted search latency envelope. P1 remains open."
+  );
+  if (process.env.SAMBEE_KEEP_PREVIEW_PROOF === "1") {
+    report.artifacts = output;
+    await writeFile(resolve(output, "report.json"), JSON.stringify(report, null, 2));
+  }
+  console.log(report.kind);
+  console.table(
+    report.measurements.map((measurement) => ({
+      fixture: measurement.fixture,
+      width: measurement.width,
+      virtual: measurement.virtual,
+      cache: measurement.cache,
+      rows: measurement.mountedRows,
+      spans: measurement.mountedSpans,
+      batches: measurement.publicationBatches,
+      prepareMs: measurement.preparationMs?.toFixed(1) ?? "included in pipeline",
+      pipelineMs: measurement.workerPipelineWallMs?.toFixed(1) ?? "n/a",
+      indexMs: measurement.indexingMs?.toFixed(1) ?? "included in pipeline",
+      loadToPaintMs: measurement.loadToPaintMs.toFixed(1),
+      longestTaskMs: measurement.longTaskObservationSupported ? Math.max(0, ...measurement.longTasks) : "unavailable",
+      maxTaskGapMs: measurement.maximumTaskServiceGapMs.toFixed(1),
+    }))
+  );
+  console.log(
+    "P1 interaction gate: OPEN. Provisional host targets are approved; physical devices, large-structure failures, total memory, native Find/accessibility and production acceptance remain."
+  );
+  if (report.artifacts) console.log(`Evidence: ${report.artifacts}`);
+  if (report.scaling)
+    console.log(
+      `Scaling: ${report.scaling.length} trials; ${report.scaling.filter((entry) => entry.error).length} explicit failures; provisional host budget gate ${report.hostBudgetsPassed ? "PASSED (not P1 acceptance)" : "not enabled"}`
+    );
+} catch (error) {
+  report.failure = {
+    name: error instanceof Error ? error.name : "UnknownError",
+    message: error instanceof Error ? error.message : String(error),
+  };
+  if (process.env.SAMBEE_KEEP_PREVIEW_PROOF === "1") {
+    report.artifacts = output;
+    await writeFile(resolve(output, "report.json"), JSON.stringify(report, null, 2));
+    console.error(`Failed proof evidence: ${output}`);
+  }
+  throw error;
+} finally {
+  await browser?.close();
+  if (process.env.SAMBEE_KEEP_PREVIEW_PROOF !== "1") await rm(output, { recursive: true, force: true });
+}
diff --git a/frontend/scripts/markdown-syntax-publication-proof.mjs b/frontend/scripts/markdown-syntax-publication-proof.mjs
new file mode 100644
index 000000000..d00e02998
--- /dev/null
+++ b/frontend/scripts/markdown-syntax-publication-proof.mjs
@@ -0,0 +1,138 @@
+import assert from "node:assert/strict";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { extname, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { chromium } from "playwright";
+import { build } from "vite";
+
+const FRONTEND = fileURLToPath(new URL("..", import.meta.url));
+const APPROVED_URL = "http://localhost:3000/browse/smb/demo";
+const PREFIX = "/__syntax_publication_proof__/";
+const output = await mkdtemp(resolve(tmpdir(), "sambee-live-syntax-"));
+let browser;
+try {
+  await build({
+    root: FRONTEND,
+    configFile: resolve(FRONTEND, "vite.config.ts"),
+    base: PREFIX,
+    logLevel: "warn",
+    build: {
+      outDir: output,
+      emptyOutDir: true,
+      rollupOptions: {
+        input: {
+          publication: resolve(FRONTEND, "src/utils/markdownSyntaxPublication.ts"),
+          preparation: resolve(FRONTEND, "src/utils/markdownSyntaxWorker.ts"),
+          parser: resolve(FRONTEND, "src/utils/codeMirrorHighlightingCore.ts"),
+        },
+        preserveEntrySignatures: "strict",
+        output: { entryFileNames: "[name].js" },
+      },
+    },
+  });
+  browser = await chromium.launch({ headless: true });
+  const results = [];
+  for (const width of [1543, 390]) {
+    const page = await browser.newPage({ viewport: { width, height: 900 } });
+    const errors = [];
+    page.on("pageerror", (error) => errors.push(error.message));
+    await page.route(`**${PREFIX}**`, async (route) => {
+      const pathname = new URL(route.request().url()).pathname;
+      const path = resolve(output, decodeURIComponent(pathname.slice(PREFIX.length)));
+      if (!path.startsWith(`${output}${sep}`)) return route.abort();
+      await route.fulfill({ body: await readFile(path), contentType: extname(path) === ".css" ? "text/css" : "text/javascript" });
+    });
+    await page.route(APPROVED_URL, (route) => route.fulfill({
+      contentType: "text/html",
+      body: '<!doctype html><html><meta name="viewport" content="width=device-width, initial-scale=1"><style>body{margin:0}#host{height:800px;overflow:auto;--sambee-syntax-keyword:#c00000}pre{white-space:pre-wrap;font:14px/20px monospace;margin:0}::selection{background:#aaccff}</style><div id="host"></div></html>',
+    }));
+    await page.goto(APPROVED_URL);
+    const samples = await page.evaluate(async ({ prefix }) => {
+      const { prepareMarkdownSyntax } = await import(`${prefix}preparation.js`);
+      const { createStaticHighlighter } = await import(`${prefix}parser.js`);
+      const { publishMarkdownSyntax, MAX_VIEWPORT_SYNTAX_RANGES } = await import(`${prefix}publication.js`);
+      const host = document.getElementById("host");
+      const frame = () => new Promise((resolve) => requestAnimationFrame(resolve));
+      const samples = [];
+      for (const lines of [6000, 11000]) {
+        const text = "let x=1;\n".repeat(lines);
+        const requests = [{ text, label: "js" }];
+        const started = performance.now();
+        const results = await prepareMarkdownSyntax(requests, new AbortController().signal);
+        const preparationMs = performance.now() - started;
+        const direct = await createStaticHighlighter((message) => { throw new Error(message); }).prepare(requests);
+        if (JSON.stringify(results) !== JSON.stringify(direct)) throw new Error("Production worker/parser parity failed");
+        const ranges = results[0].ranges;
+        const pre = document.createElement("pre");
+        const code = document.createElement("code");
+        pre.append(code);
+        host.replaceChildren(pre);
+        const baselineStart = performance.now();
+        const fragment = document.createDocumentFragment();
+        let offset = 0;
+        for (const range of ranges) {
+          if (range.from > offset) fragment.append(document.createTextNode(text.slice(offset, range.from)));
+          const span = document.createElement("span");
+          span.className = range.categories.map((category) => `sambee-syntax-${category}`).join(" ");
+          span.textContent = text.slice(range.from, range.to);
+          fragment.append(span);
+          offset = range.to;
+        }
+        fragment.append(document.createTextNode(text.slice(offset) + "\n"));
+        code.replaceChildren(fragment);
+        const baselineDomMs = performance.now() - baselineStart;
+        const baselineHeight = host.scrollHeight;
+        const baselineSpans = code.querySelectorAll("span").length;
+        code.textContent = `${text}\n`;
+        const node = code.firstChild;
+        const selection = document.getSelection();
+        const selected = document.createRange();
+        selected.setStart(node, 0);
+        selected.setEnd(node, 3);
+        selection.removeAllRanges();
+        selection.addRange(selected);
+        const controller = new AbortController();
+        const publicationStart = performance.now();
+        publishMarkdownSyntax(host, host, { requests, results }, controller.signal);
+        await frame();
+        await frame();
+        const publicationWallMs = performance.now() - publicationStart;
+        const decorations = () => [...CSS.highlights.entries()].filter(([name]) => name.startsWith("markdown-syntax-"));
+        const mountedRanges = decorations().reduce((sum, [, ranges]) => sum + ranges.size, 0);
+        const keywordName = decorations().find(([name]) => name.endsWith("-keyword"))[0];
+        const lightColor = getComputedStyle(code, `::highlight(${keywordName})`).color;
+        host.style.setProperty("--sambee-syntax-keyword", "#ff8800");
+        const darkColor = getComputedStyle(code, `::highlight(${keywordName})`).color;
+        if (lightColor === darkColor) throw new Error("Syntax colors did not follow theme variables");
+        if (code.textContent !== `${text}\n` || code.firstChild !== node || selection.toString() !== "let") throw new Error("Syntax publication changed text or selection");
+        if (host.scrollHeight !== baselineHeight) throw new Error("Syntax publication changed document geometry");
+        if (mountedRanges <= 0 || mountedRanges > MAX_VIEWPORT_SYNTAX_RANGES || code.children.length) throw new Error("Invalid viewport syntax work bound");
+        selection.removeAllRanges();
+        host.scrollTop = host.scrollHeight;
+        host.dispatchEvent(new Event("scroll"));
+        await frame();
+        await frame();
+        const finalRanges = decorations().flatMap(([, ranges]) => [...ranges]);
+        if (!finalRanges.length || !finalRanges.some((range) => range.startOffset > text.length / 2)) throw new Error("End-of-document syntax was not published");
+        controller.abort();
+        if (decorations().length) throw new Error("Cancelled syntax ranges survived disposal");
+        samples.push({ sourceUnits: text.length, preparationMs, baselineDomMs, baselineSpans, publicationWallMs, mountedRanges, lightColor, darkColor });
+        host.scrollTop = 0;
+        host.style.setProperty("--sambee-syntax-keyword", "#c00000");
+      }
+      const parityRequests = [{text: "name: value\n", label: "yml"}, {text: '# Heading\n\n```py\nprint("🌍")\n```', label: "md"}];
+      const parity = await prepareMarkdownSyntax(parityRequests, new AbortController().signal);
+      const direct = await createStaticHighlighter((message) => { throw new Error(message); }).prepare(parityRequests);
+      if (JSON.stringify(parity) !== JSON.stringify(direct) || parity.some((result) => !("ranges" in result))) throw new Error("Production alias/nested parser parity failed");
+      return samples;
+    }, { prefix: PREFIX });
+    assert.deepEqual(errors, []);
+    results.push({ width, samples });
+    await page.close();
+  }
+  console.log(JSON.stringify({ kind: "Production live syntax publication slice; not whole-viewer or physical-device acceptance", browser: browser.version(), results }, null, 2));
+} finally {
+  await browser?.close();
+  await rm(output, { recursive: true, force: true });
+}
diff --git a/frontend/scripts/prototypes/markdownCodePreparation.ts b/frontend/scripts/prototypes/markdownCodePreparation.ts
new file mode 100644
index 000000000..8315b7bc4
--- /dev/null
+++ b/frontend/scripts/prototypes/markdownCodePreparation.ts
@@ -0,0 +1,316 @@
+import type { CodePreviewFragment, CodePreviewModel } from "../../src/utils/markdownCodePreviewModel";
+import {
+  DOCUMENT_PUBLICATION_BATCH_ITEMS,
+  DOCUMENT_RECORD_BATCH_ITEMS,
+  DOCUMENT_TEXT_CHUNK_UNITS,
+  type DocumentSyntaxWindow,
+  type MarkdownDocumentRecord,
+} from "../../src/utils/markdownDocumentPreviewModel";
+import type { SyntaxRange } from "../../src/utils/syntaxHighlighting";
+
+export const PREPARATION_CHUNK_ITEMS = 512;
+export const PREPARATION_SOURCE_CHUNK_UNITS = 16_384;
+const WORKER_PROGRESS_TIMEOUT_MS = 30_000;
+
+export interface PreviewMatch {
+  from: number;
+  to: number;
+}
+
+export type PreparationRequest =
+  | { type: "syntax-window"; generation: number; requestId: number; window: DocumentSyntaxWindow; offset: number }
+  | { type: "prepare"; generation: number; blockCount: number; document?: boolean }
+  | { type: "source"; generation: number; sequence: number; block: number; text: string; final: boolean }
+  | { type: "run"; generation: number }
+  | { type: "ack"; generation: number };
+
+export type PreparationResponse =
+  | {
+      type: "syntax-page";
+      generation: number;
+      requestId: number;
+      records: Extract<MarkdownDocumentRecord, { kind: "syntax" }>[];
+      next: number | null;
+    }
+  | { type: "document-chunk"; generation: number; records: MarkdownDocumentRecord[] }
+  | { type: "source-ack"; generation: number; sequence: number }
+  | {
+      type: "diagnostic";
+      generation: number;
+      message: string;
+      context?: Record<string, unknown>;
+      component?: string;
+      error?: { message: string; name: string };
+    }
+  | { type: "chunk"; generation: number; block: number; ranges: SyntaxRange[]; fragments: CodePreviewFragment[]; matches: PreviewMatch[] }
+  | { type: "complete"; generation: number; preparationMs: number; indexingMs: number; syntaxRanges?: number }
+  | { type: "error"; generation: number; message: string };
+
+interface WorkerPreparation {
+  syntaxRanges: number;
+  sourceChunks: number;
+  largestSourceChunkUnits: number;
+  sourceUnitsSent: number;
+  models: CodePreviewModel[];
+  matches: PreviewMatch[];
+  preparationMs: number;
+  indexingMs: number;
+  clientAssemblyMs: number;
+  chunks: number;
+  largestChunkItems: number;
+}
+
+let worker: Worker | null = null;
+
+export function createDocumentSyntaxSession(generation: number) {
+  const current = worker;
+  if (!current) throw new Error("Document syntax worker is unavailable");
+  let nextId = 0;
+  let pending: {
+    id: number;
+    resolve: (page: Extract<PreparationResponse, { type: "syntax-page" }>) => void;
+    reject: (error: Error) => void;
+  } | null = null;
+  let disposed = false;
+  let failure: Error | null = null;
+  let timer: ReturnType<typeof setTimeout>;
+  const fail = (error: Error) => {
+    failure = error;
+    clearTimeout(timer);
+    const request = pending;
+    pending = null;
+    request?.reject(error);
+    current.terminate();
+    if (worker === current) worker = null;
+  };
+  const message = (event: MessageEvent<PreparationResponse>) => {
+    if (event.data.generation !== generation || disposed) return;
+    if (event.data.type === "error") {
+      fail(new Error(event.data.message));
+      return;
+    }
+    if (event.data.type !== "syntax-page" || event.data.requestId !== pending?.id) return;
+    if (event.data.records.length > DOCUMENT_RECORD_BATCH_ITEMS) {
+      fail(new Error("Document syntax page exceeded its record bound"));
+      return;
+    }
+    clearTimeout(timer);
+    const request = pending;
+    pending = null;
+    request.resolve(event.data);
+  };
+  const error = (event: ErrorEvent) => {
+    event.preventDefault();
+    fail(new Error(`Document syntax worker failed: ${event.message}`));
+  };
+  const decode = () => fail(new Error("Document syntax page could not be decoded"));
+  current.addEventListener("message", message);
+  current.addEventListener("error", error);
+  current.addEventListener("messageerror", decode);
+  return {
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      clearTimeout(timer);
+      const request = pending;
+      pending = null;
+      request?.reject(new DOMException("Document syntax session disposed", "AbortError"));
+      current.removeEventListener("message", message);
+      current.removeEventListener("error", error);
+      current.removeEventListener("messageerror", decode);
+    },
+    page(window: DocumentSyntaxWindow, offset: number) {
+      return new Promise<Extract<PreparationResponse, { type: "syntax-page" }>>((resolve, reject) => {
+        if (disposed || failure || pending) {
+          reject(failure ?? new Error(disposed ? "Document syntax session disposed" : "Document syntax request overlaps"));
+          return;
+        }
+        pending = { id: ++nextId, resolve, reject };
+        timer = setTimeout(
+          () => fail(new Error("Document syntax request exceeded its prototype progress timeout")),
+          WORKER_PROGRESS_TIMEOUT_MS
+        );
+        try {
+          current.postMessage({ type: "syntax-window", generation, requestId: nextId, window, offset } satisfies PreparationRequest);
+        } catch (error) {
+          fail(error instanceof Error ? error : new Error(String(error)));
+        }
+      });
+    },
+  };
+}
+
+export function shutdownCodePreviewWorker(): void {
+  worker?.terminate();
+  worker = null;
+}
+
+/** P1 execution probe; successful jobs reuse grammars, aborted jobs destroy their worker. */
+export function prepareCodePreviewInWorker(
+  blocks: string[],
+  generation: number,
+  signal: AbortSignal,
+  onDiagnostic: (diagnostic: Extract<PreparationResponse, { type: "diagnostic" }>) => void,
+  onDocumentChunk?: (records: readonly MarkdownDocumentRecord[]) => Promise<void>
+): Promise<WorkerPreparation> {
+  if (signal.aborted) return Promise.reject(new DOMException("Preparation cancelled", "AbortError"));
+  if (typeof Worker === "undefined")
+    return Promise.reject(new Error("Worker preparation is unavailable; no main-thread fallback was used"));
+  return new Promise((resolve, reject) => {
+    let current: Worker;
+    try {
+      worker ??= new Worker(new URL("./markdownCodePreparation.worker.ts", import.meta.url), { type: "module" });
+      current = worker;
+    } catch (error) {
+      reject(error);
+      return;
+    }
+    const ranges = blocks.map(() => [] as SyntaxRange[]);
+    const fragments = blocks.map(() => [] as CodePreviewFragment[]);
+    const matches: PreviewMatch[] = [];
+    const offsets: number[] = [];
+    let offset = 0;
+    for (const block of blocks) {
+      offsets.push(offset);
+      offset += block.length;
+    }
+    let chunks = 0;
+    let sourceBlock = 0;
+    let sourceOffset = 0;
+    let sourceSequence = 0;
+    let sourceComplete = false;
+    let sourceChunks = 0;
+    let largestSourceChunkUnits = 0;
+    let sourceUnitsSent = 0;
+    let largestChunkItems = 0;
+    let clientAssemblyMs = 0;
+    let settled = false;
+    let watchdog: ReturnType<typeof setTimeout>;
+    const cleanup = () => {
+      clearTimeout(watchdog);
+      signal.removeEventListener("abort", abort);
+      current.onmessage = null;
+      current.onerror = null;
+      current.removeEventListener("messageerror", decodeFailure);
+    };
+    const fail = (error: unknown) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      current.terminate();
+      if (worker === current) worker = null;
+      reject(error);
+    };
+    const abort = () => fail(new DOMException("Worker preparation cancelled", "AbortError"));
+    const armWatchdog = () => {
+      clearTimeout(watchdog);
+      watchdog = setTimeout(
+        () => fail(new Error("Worker preparation made no progress before its prototype timeout")),
+        WORKER_PROGRESS_TIMEOUT_MS
+      );
+    };
+    signal.addEventListener("abort", abort, { once: true });
+    current.onerror = (event) => {
+      event.preventDefault();
+      fail(new Error(`Worker preparation failed: ${event.message} at ${event.filename}:${event.lineno}:${event.colno}`));
+    };
+    const decodeFailure = () => fail(new Error("Worker preparation result could not be decoded"));
+    current.addEventListener("messageerror", decodeFailure);
+    current.onmessage = async (event: MessageEvent<PreparationResponse>) => {
+      if (settled || event.data.generation !== generation) return;
+      const response = event.data;
+      try {
+        armWatchdog();
+        if (response.type === "document-chunk") {
+          if (
+            !onDocumentChunk ||
+            response.records.length > DOCUMENT_PUBLICATION_BATCH_ITEMS ||
+            response.records.some(
+              (record) => (record.kind === "text" || record.kind === "attribute") && record.value.length > DOCUMENT_TEXT_CHUNK_UNITS
+            )
+          )
+            throw new Error("Invalid Markdown document batch");
+          await onDocumentChunk(response.records);
+          if (settled) return;
+          current.postMessage({ type: "ack", generation } satisfies PreparationRequest);
+          return;
+        }
+        if (response.type === "source-ack") {
+          if (sourceComplete || response.sequence !== sourceSequence) throw new Error("Invalid source acknowledgement");
+          if (sourceBlock === blocks.length) {
+            sourceComplete = true;
+            current.postMessage({ type: "run", generation } satisfies PreparationRequest);
+            return;
+          }
+          const block = sourceBlock;
+          const text = blocks[block].slice(sourceOffset, sourceOffset + PREPARATION_SOURCE_CHUNK_UNITS);
+          sourceOffset += text.length;
+          const final = sourceOffset === blocks[block].length;
+          if (final) {
+            sourceBlock += 1;
+            sourceOffset = 0;
+          }
+          sourceChunks += 1;
+          largestSourceChunkUnits = Math.max(largestSourceChunkUnits, text.length);
+          sourceUnitsSent += text.length;
+          sourceSequence += 1;
+          current.postMessage({ type: "source", generation, sequence: sourceSequence, block, text, final } satisfies PreparationRequest);
+          return;
+        }
+        if (response.type === "diagnostic") {
+          onDiagnostic(response);
+          return;
+        }
+        if (response.type === "error") {
+          fail(new Error(response.message));
+          return;
+        }
+        if (response.type === "chunk") {
+          const start = performance.now();
+          if (!Number.isInteger(response.block) || response.block < 0 || response.block >= blocks.length)
+            throw new Error("Invalid preparation block");
+          const count = response.ranges.length + response.fragments.length + response.matches.length;
+          if (count > PREPARATION_CHUNK_ITEMS) throw new Error("Preparation result exceeded its chunk bound");
+          for (const range of response.ranges) ranges[response.block].push(range);
+          for (const fragment of response.fragments) fragments[response.block].push(fragment);
+          for (const match of response.matches)
+            matches.push({ from: offsets[response.block] + match.from, to: offsets[response.block] + match.to });
+          chunks += 1;
+          largestChunkItems = Math.max(largestChunkItems, count);
+          clientAssemblyMs += performance.now() - start;
+          current.postMessage({ type: "ack", generation } satisfies PreparationRequest);
+          return;
+        }
+        if (response.type !== "complete") throw new Error("Unexpected preparation response");
+        settled = true;
+        cleanup();
+        resolve({
+          syntaxRanges: response.syntaxRanges ?? 0,
+          sourceChunks,
+          largestSourceChunkUnits,
+          sourceUnitsSent,
+          models: blocks.map((text, index) => ({ text, ranges: ranges[index], fragments: fragments[index] })),
+          matches,
+          preparationMs: response.preparationMs,
+          indexingMs: response.indexingMs,
+          clientAssemblyMs,
+          chunks,
+          largestChunkItems,
+        });
+      } catch (error) {
+        fail(error);
+      }
+    };
+    armWatchdog();
+    try {
+      current.postMessage({
+        type: "prepare",
+        generation,
+        blockCount: blocks.length,
+        document: Boolean(onDocumentChunk),
+      } satisfies PreparationRequest);
+    } catch (error) {
+      fail(error);
+    }
+  });
+}
diff --git a/frontend/scripts/prototypes/markdownCodePreparation.worker.ts b/frontend/scripts/prototypes/markdownCodePreparation.worker.ts
new file mode 100644
index 000000000..de158a1ea
--- /dev/null
+++ b/frontend/scripts/prototypes/markdownCodePreparation.worker.ts
@@ -0,0 +1,202 @@
+import { createStaticHighlighter } from "../../src/utils/codeMirrorHighlightingCore";
+import { createCodePreviewModel } from "../../src/utils/markdownCodePreviewModel";
+import {
+	createMarkdownDocumentModel,
+	DOCUMENT_PUBLICATION_BATCH_ITEMS,
+	DOCUMENT_PUBLICATION_BATCH_UNITS,
+	documentSyntaxPage,
+	type MarkdownDocumentRecord,
+	markdownDocumentRecords,
+} from "../../src/utils/markdownDocumentPreviewModel";
+import type { SyntaxRange } from "../../src/utils/syntaxHighlighting";
+import {
+	PREPARATION_CHUNK_ITEMS,
+	PREPARATION_SOURCE_CHUNK_UNITS,
+	type PreparationRequest,
+	type PreparationResponse,
+	type PreviewMatch,
+} from "./markdownCodePreparation";
+
+const MATCH_QUERY = "let x";
+let acknowledge: (() => void) | null = null;
+let activeGeneration: number | null = null;
+let sourceBlocks: string[] = [];
+let sourceParts: string[] = [];
+let expectedBlocks = 0;
+let sourceSequence = 0;
+let running = false;
+let documentMode = false;
+let documentGeneration: number | null = null;
+const documentSyntax = new Map<number, readonly SyntaxRange[]>();
+const highlightingService = createStaticHighlighter(error);
+
+function send(response: PreparationResponse): void {
+	postMessage(response);
+}
+
+export function error(message: string, context?: Record<string, unknown>, component?: string, failure?: Error): void {
+	send({
+		type: "diagnostic",
+		generation: activeGeneration ?? -1,
+		message,
+		context,
+		component,
+		error: failure ? { message: failure.message, name: failure.name } : undefined,
+	});
+}
+
+async function prepareDocument(source: string, generation: number): Promise<void> {
+	const start = performance.now();
+	const model = await createMarkdownDocumentModel(source, { normalizeSource: true });
+	documentGeneration = generation;
+	let batch: MarkdownDocumentRecord[] = [];
+	let batchUnits = 0;
+	const flush = async () => {
+		if (!batch.length) return;
+		const records = batch;
+		batch = [];
+		batchUnits = 0;
+		await new Promise<void>((resolve) => {
+			acknowledge = resolve;
+			send({ type: "document-chunk", generation, records });
+		});
+	};
+	const emit = async (record: MarkdownDocumentRecord) => {
+		const units = record.kind === "text" || record.kind === "attribute" ? record.value.length : 0;
+		if (batchUnits + units > DOCUMENT_PUBLICATION_BATCH_UNITS) await flush();
+		batch.push(record);
+		batchUnits += units;
+		if (batch.length >= DOCUMENT_PUBLICATION_BATCH_ITEMS || batchUnits >= DOCUMENT_PUBLICATION_BATCH_UNITS) await flush();
+	};
+	for (const record of markdownDocumentRecords(model)) await emit(record);
+	await flush();
+	for (const block of model.codeBlocks) {
+		const [result] = await highlightingService.prepare([block]);
+		if (!result) throw new Error("Markdown code preparation returned no result");
+		if ("ranges" in result) documentSyntax.set(block.id, result.ranges);
+		else await emit({ kind: "fallback", id: block.id, reason: result.reason });
+	}
+	await flush();
+	send({
+		type: "complete",
+		generation,
+		preparationMs: performance.now() - start,
+		indexingMs: 0,
+		syntaxRanges: [...documentSyntax.values()].reduce((count, ranges) => count + ranges.length, 0),
+	});
+}
+
+async function prepare(blocks: string[], generation: number): Promise<void> {
+	let preparationMs = 0;
+	let indexingMs = 0;
+	for (let block = 0; block < blocks.length; block += 1) {
+		const text = blocks[block];
+		const start = performance.now();
+		const [result] = await highlightingService.prepare([{ text, label: "javascript" }]);
+		preparationMs += performance.now() - start;
+		if (!("ranges" in result)) throw new Error(`Prototype block ${block} preparation failed: ${result.reason}`);
+		const indexStart = performance.now();
+		const model = createCodePreviewModel(text, result.ranges);
+		const matches: PreviewMatch[] = [];
+		for (let from = text.indexOf(MATCH_QUERY); from !== -1; from = text.indexOf(MATCH_QUERY, from + MATCH_QUERY.length)) {
+			matches.push({ from, to: from + MATCH_QUERY.length });
+		}
+		indexingMs += performance.now() - indexStart;
+		let rangeOffset = 0;
+		let fragmentOffset = 0;
+		let matchOffset = 0;
+		while (rangeOffset < model.ranges.length || fragmentOffset < model.fragments.length || matchOffset < matches.length) {
+			const ranges = model.ranges.slice(rangeOffset, rangeOffset + PREPARATION_CHUNK_ITEMS);
+			const fragments = model.fragments.slice(fragmentOffset, fragmentOffset + PREPARATION_CHUNK_ITEMS - ranges.length);
+			const matchChunk = matches.slice(matchOffset, matchOffset + PREPARATION_CHUNK_ITEMS - ranges.length - fragments.length);
+			rangeOffset += ranges.length;
+			fragmentOffset += fragments.length;
+			matchOffset += matchChunk.length;
+			await new Promise<void>((resolve) => {
+				acknowledge = resolve;
+				send({ type: "chunk", generation, block, ranges, fragments, matches: matchChunk });
+			});
+		}
+	}
+	send({ type: "complete", generation, preparationMs, indexingMs });
+}
+
+globalThis.onmessage = (event: MessageEvent<PreparationRequest>) => {
+	const request = event.data;
+	if (request.type === "syntax-window") {
+		if (request.generation !== documentGeneration) return;
+		try {
+			send({
+				type: "syntax-page",
+				generation: request.generation,
+				requestId: request.requestId,
+				...documentSyntaxPage(documentSyntax.get(request.window.id) ?? [], request.window, request.offset),
+			});
+		} catch (failure) {
+			send({ type: "error", generation: request.generation, message: failure instanceof Error ? failure.message : String(failure) });
+		}
+		return;
+	}
+	if (request.type === "prepare") {
+		if (activeGeneration !== null || !Number.isSafeInteger(request.blockCount) || request.blockCount < 0) {
+			send({ type: "error", generation: request.generation, message: "Preparation worker received an invalid or overlapping job" });
+			return;
+		}
+		activeGeneration = request.generation;
+		documentSyntax.clear();
+		documentGeneration = null;
+		documentMode = request.document === true;
+		if (documentMode && request.blockCount !== 1) {
+			send({ type: "error", generation: request.generation, message: "Markdown document preparation requires one source document" });
+			return;
+		}
+		expectedBlocks = request.blockCount;
+		sourceBlocks = [];
+		sourceParts = [];
+		sourceSequence = 0;
+		running = false;
+		send({ type: "source-ack", generation: request.generation, sequence: sourceSequence });
+		return;
+	}
+	if (request.generation !== activeGeneration) return;
+	if (request.type === "ack") {
+		const resume = acknowledge;
+		acknowledge = null;
+		resume?.();
+		return;
+	}
+	if (request.type === "source") {
+		if (
+			running || request.sequence !== sourceSequence + 1 || request.block !== sourceBlocks.length ||
+			request.block >= expectedBlocks || typeof request.text !== "string" || request.text.length > PREPARATION_SOURCE_CHUNK_UNITS ||
+			typeof request.final !== "boolean" || (!request.final && request.text.length === 0)
+		) {
+			send({ type: "error", generation: request.generation, message: "Preparation worker received an invalid source chunk" });
+			return;
+		}
+		sourceParts.push(request.text);
+		if (request.final) {
+			sourceBlocks.push(sourceParts.join(""));
+			sourceParts = [];
+		}
+		sourceSequence = request.sequence;
+		send({ type: "source-ack", generation: request.generation, sequence: sourceSequence });
+		return;
+	}
+	if (running || sourceBlocks.length !== expectedBlocks || sourceParts.length > 0) {
+		send({ type: "error", generation: request.generation, message: "Preparation worker cannot run before source transfer completes" });
+		return;
+	}
+	running = true;
+	void (documentMode ? prepareDocument(sourceBlocks[0]!, request.generation) : prepare(sourceBlocks, request.generation))
+		.catch((failure: unknown) => {
+			send({ type: "error", generation: request.generation, message: failure instanceof Error ? failure.message : "Worker preparation failed" });
+		})
+		.finally(() => {
+			acknowledge = null;
+			activeGeneration = null;
+			sourceBlocks = [];
+			sourceParts = [];
+			running = false;
+		});
+};
diff --git a/frontend/scripts/prototypes/markdownCodePreview.tsx b/frontend/scripts/prototypes/markdownCodePreview.tsx
new file mode 100644
index 000000000..da0c3587e
--- /dev/null
+++ b/frontend/scripts/prototypes/markdownCodePreview.tsx
@@ -0,0 +1,777 @@
+import { useVirtualizer } from "@tanstack/react-virtual";
+import { useLayoutEffect, useRef, useState } from "react";
+import { createRoot } from "react-dom/client";
+import { error as logError } from "../../src/services/logger";
+import { syntaxTokenStyles } from "../../src/theme/syntaxStyles";
+import { getDefaultTheme } from "../../src/theme/themes";
+import { yieldHighlightingTask } from "../../src/utils/codeMirrorHighlighting";
+import { highlightingService } from "../../src/utils/highlightingService";
+import {
+  CODE_PREVIEW_SCAN_MAX_UNITS,
+  type CodePreviewModel,
+  createCodePreviewModel,
+  createCodePreviewModelAsync,
+  findCodePreviewFragment,
+} from "../../src/utils/markdownCodePreviewModel";
+import type { DocumentSearchOptions } from "../../src/utils/markdownDocumentSearch";
+import { TOKEN_CATEGORIES, tokenClasses } from "../../src/utils/syntaxHighlighting";
+import {
+  createDocumentSyntaxSession,
+  PREPARATION_CHUNK_ITEMS,
+  PREPARATION_SOURCE_CHUNK_UNITS,
+  prepareCodePreviewInWorker,
+  shutdownCodePreviewWorker,
+} from "./markdownCodePreparation";
+import { mountMarkdownDocument, renderMarkdownDocumentBaseline } from "./markdownDocumentPreview";
+import type { DocumentSearchResult } from "./markdownDocumentSearch";
+
+const ROW_HEIGHT = 20;
+const VIEWPORT_HEIGHT = 480;
+const OVERSCAN = 3;
+const PUBLICATION_BATCH_ROWS = 64;
+const PRIORITY_NEIGHBOR_ROWS = 3;
+const SOURCE_INDEX_BLOCK_BATCH = 16;
+
+interface Match {
+  from: number;
+  to: number;
+}
+
+interface Fixture {
+  sourceIndexingYields: number;
+  sourceIndexingMs: number;
+  preparationComplete: boolean;
+  preparationError: string | null;
+  refresh?: () => void;
+  sourceChunks: number;
+  largestSourceChunkUnits: number;
+  sourceUnitsSent: number;
+  execution: "main-thread" | "worker";
+  transferChunks: number;
+  largestChunkItems: number;
+  clientAssemblyMs: number;
+  preparationWallMs: number;
+  generation: number;
+  loadStartedAt: number;
+  models: CodePreviewModel[];
+  rows: { block: number; fragment: number }[];
+  offsets: number[];
+  blockBounds: Match[];
+  rowStarts: number[];
+  matches: Match[];
+  preparationMs: number;
+  indexingMs: number;
+  text: string;
+}
+
+interface PrototypeControl {
+  searchDocument: (query: string, options?: DocumentSearchOptions) => Promise<DocumentSearchResult>;
+  jumpDocument: (ordinal: number) => Promise<{ pending: boolean }>;
+  shutdownDocument: () => void;
+  loadDocument: (source: string) => Promise<void>;
+  baselineDocument: (source: string) => Promise<void>;
+  inspect: () => { models: readonly CodePreviewModel[]; matches: readonly Match[] };
+  load: (
+    blocks: string[],
+    virtual: boolean | "retained-text" | "retained-text-worker" | "retained-text-worker-progressive"
+  ) => Promise<void>;
+  jump: (ordinal: number) => { pending: boolean };
+  stats: () => Record<string, unknown>;
+}
+
+declare global {
+  interface Window {
+    codePreviewPrototype: PrototypeControl;
+  }
+}
+
+function RetainedTextPreview({ fixture, onCommit }: { fixture: Fixture; onCommit: () => void }) {
+  const scrollRef = useRef<HTMLDivElement>(null);
+  const nodes = useRef(new Map<number, HTMLElement>());
+  const active = useRef(-1);
+  const painted = useRef({ rows: 0, ranges: 0 });
+
+  useLayoutEffect(() => {
+    if (typeof Highlight === "undefined" || !CSS.highlights) throw new Error("Retained-text prototype requires the CSS Highlight API");
+    const container = scrollRef.current;
+    if (!container) return;
+    let frame: number | null = null;
+    let publicationTimer: ReturnType<typeof setTimeout> | null = null;
+    let publishedRows = 0;
+    let publicationBatches = 0;
+    let largestPublicationBatch = 0;
+    let firstContentMs: number | null = null;
+    let publicationMs: number | null = null;
+    let pendingRow: number | null = null;
+    let activeRow: number | null = null;
+    let nextSequentialRow = 0;
+    let priorityRows: number[] = [];
+    let priorityPublishedRows = 0;
+    const publishedIndices: number[] = [];
+    const blocks = new Map<number, HTMLElement>();
+    const publicationStart = performance.now();
+    container.style.overflowAnchor = "none";
+    const visible = new Set<number>();
+    const paint = () => {
+      frame = null;
+      if (fixture.generation !== generation) return;
+      const categories = new Map<string, Range[]>();
+      const search: Range[] = [];
+      const selected: Range[] = [];
+      let rangeCount = 0;
+      for (const index of visible) {
+        const element = nodes.current.get(index);
+        const textNode = element?.firstChild;
+        if (!(textNode instanceof Text)) continue;
+        const row = fixture.rows[index];
+        const model = fixture.models[row.block];
+        const fragment = model.fragments[row.fragment];
+        const range = (from: number, to: number) => {
+          const result = new Range();
+          result.setStart(textNode, Math.max(fragment.from, from) - fragment.from);
+          result.setEnd(textNode, Math.min(fragment.to, to) - fragment.from);
+          rangeCount += 1;
+          return result;
+        };
+        for (let tokenIndex = fragment.firstRange; tokenIndex < fragment.rangeEnd; tokenIndex += 1) {
+          const token = model.ranges[tokenIndex];
+          for (const category of token.categories) {
+            const ranges = categories.get(category) ?? [];
+            ranges.push(range(token.from, token.to));
+            categories.set(category, ranges);
+          }
+        }
+        const blockOffset = fixture.offsets[row.block];
+        for (
+          let matchIndex = firstOverlap(fixture.matches, blockOffset + fragment.from);
+          matchIndex < fixture.matches.length && fixture.matches[matchIndex].from < blockOffset + fragment.to;
+          matchIndex += 1
+        ) {
+          const match = fixture.matches[matchIndex];
+          search.push(range(match.from - blockOffset, match.to - blockOffset));
+          if (matchIndex === active.current) selected.push(range(match.from - blockOffset, match.to - blockOffset));
+        }
+      }
+      for (const category of TOKEN_CATEGORIES)
+        CSS.highlights.set(`preview-${category}`, new Highlight(...(categories.get(category) ?? [])));
+      const searchHighlight = new Highlight(...search);
+      searchHighlight.priority = 1;
+      CSS.highlights.set("preview-search", searchHighlight);
+      const activeHighlight = new Highlight(...selected);
+      activeHighlight.priority = 2;
+      CSS.highlights.set("preview-active", activeHighlight);
+      painted.current = { rows: visible.size, ranges: rangeCount };
+    };
+    const schedule = () => {
+      if (frame === null) frame = requestAnimationFrame(paint);
+    };
+    fixture.refresh = schedule;
+    const revealPendingJump = () => {
+      if (pendingRow === null) return;
+      const element = nodes.current.get(pendingRow);
+      if (!element?.isConnected) return;
+      element.scrollIntoView({ block: "center" });
+      pendingRow = null;
+      schedule();
+    };
+    const observer = new IntersectionObserver(
+      (entries) => {
+        for (const entry of entries) {
+          const index = Number((entry.target as HTMLElement).dataset.index);
+          if (entry.isIntersecting) visible.add(index);
+          else visible.delete(index);
+        }
+        schedule();
+      },
+      { root: container, rootMargin: `${VIEWPORT_HEIGHT}px 0px` }
+    );
+    window.codePreviewPrototype.jump = (ordinal) => {
+      if (!fixture.preparationComplete) throw new Error("Prototype search preparation is pending");
+      const match = fixture.matches[ordinal];
+      if (!match) throw new RangeError("Prototype match ordinal is out of bounds");
+      const block = firstOverlap(fixture.blockBounds, match.from);
+      const fragment = findCodePreviewFragment(fixture.models[block], match.from - fixture.offsets[block]);
+      if (fragment === null) throw new Error("Prototype match has no fragment");
+      active.current = ordinal;
+      pendingRow = fixture.rowStarts[block] + fragment;
+      activeRow = pendingRow;
+      priorityRows = [];
+      for (let distance = 0; distance <= PRIORITY_NEIGHBOR_ROWS; distance += 1) {
+        const candidates = distance === 0 ? [pendingRow] : [pendingRow - distance, pendingRow + distance];
+        for (const index of candidates) {
+          if (index >= 0 && index < fixture.rows.length && !nodes.current.has(index)) priorityRows.push(index);
+        }
+      }
+      revealPendingJump();
+      schedule();
+      return { pending: pendingRow !== null };
+    };
+    window.codePreviewPrototype.stats = () => ({
+      preparationMs: fixture.preparationMs,
+      sourceIndexingMs: fixture.sourceIndexingMs,
+      sourceIndexingYields: fixture.sourceIndexingYields,
+      preparationComplete: fixture.preparationComplete,
+      preparationError: fixture.preparationError,
+      searchComplete: fixture.preparationComplete,
+      execution: fixture.execution,
+      transferChunks: fixture.transferChunks,
+      largestChunkItems: fixture.largestChunkItems,
+      transferChunkLimit: PREPARATION_CHUNK_ITEMS,
+      sourceChunks: fixture.sourceChunks,
+      largestSourceChunkUnits: fixture.largestSourceChunkUnits,
+      sourceUnitsSent: fixture.sourceUnitsSent,
+      sourceChunkLimit: PREPARATION_SOURCE_CHUNK_UNITS,
+      clientAssemblyMs: fixture.clientAssemblyMs,
+      preparationWallMs: fixture.preparationWallMs,
+      indexingMs: fixture.indexingMs,
+      sourceUnits: fixture.text.length,
+      generation: fixture.generation,
+      totalRows: fixture.rows.length,
+      mountedRows: nodes.current.size,
+      publishedRows,
+      publicationBatches,
+      largestPublicationBatch,
+      publicationBatchLimit: PUBLICATION_BATCH_ROWS,
+      publicationComplete: publishedRows === fixture.rows.length,
+      priorityPublishedRows,
+      activeRow,
+      firstContentMs,
+      publicationMs,
+      mountedSpans: nodes.current.size,
+      mountedTokenSpans: 0,
+      decoratedRows: painted.current.rows,
+      highlightRanges: painted.current.ranges,
+      matchCount: fixture.matches.length,
+      active: active.current,
+      pendingMatch: pendingRow === null ? null : active.current,
+      activeMounted: pendingRow === null && (CSS.highlights.get("preview-active")?.size ?? 0) > 0,
+      scrollTop: container.scrollTop,
+      oversizedLines: fixture.models.flatMap((model) => model.fragments).filter((fragment) => fragment.oversizedLine).length,
+      mountedTextUnits: container.textContent?.length ?? 0,
+    });
+    const publish = () => {
+      publicationTimer = null;
+      if (fixture.generation !== generation) return;
+      const anchor = activeRow === null ? null : nodes.current.get(activeRow);
+      const anchorRect = anchor?.getBoundingClientRect();
+      const viewport = anchorRect ? container.getBoundingClientRect() : null;
+      const anchorTop =
+        anchorRect && viewport && anchorRect.bottom > viewport.top && anchorRect.top < viewport.bottom ? anchorRect.top : null;
+      let batchRows = 0;
+      while (batchRows < PUBLICATION_BATCH_ROWS && publishedRows < fixture.rows.length) {
+        let index = priorityRows.shift();
+        const prioritized = index !== undefined;
+        if (index === undefined) {
+          while (nodes.current.has(nextSequentialRow)) nextSequentialRow += 1;
+          index = nextSequentialRow++;
+        }
+        if (nodes.current.has(index)) continue;
+        const row = fixture.rows[index];
+        const model = fixture.models[row.block];
+        const fragment = model.fragments[row.fragment];
+        const text = model.text.slice(fragment.from, fragment.to);
+        const lines = Math.max(1, text.split("\n").length - Number(text.endsWith("\n")));
+        const element = document.createElement("span");
+        element.dataset.index = String(index);
+        element.textContent = text;
+        Object.assign(element.style, {
+          margin: "0",
+          whiteSpace: "pre-wrap",
+          overflowWrap: "anywhere",
+          fontSize: "14px",
+          lineHeight: `${ROW_HEIGHT}px`,
+          display: "inline-block",
+          verticalAlign: "top",
+          width: "100%",
+          contain: "layout style",
+          minHeight: `${lines * ROW_HEIGHT}px`,
+        });
+        let block = blocks.get(row.block);
+        if (!block) {
+          block = document.createElement("pre");
+          block.dataset.block = String(row.block);
+          Object.assign(block.style, { margin: "0", whiteSpace: "normal", fontSize: "14px", lineHeight: `${ROW_HEIGHT}px` });
+          let successorBlock: HTMLElement | null = null;
+          for (const child of container.children) {
+            if (Number((child as HTMLElement).dataset.block) > row.block) {
+              successorBlock = child as HTMLElement;
+              break;
+            }
+          }
+          container.insertBefore(block, successorBlock);
+          blocks.set(row.block, block);
+        }
+        let low = 0;
+        let high = publishedIndices.length;
+        while (low < high) {
+          const middle = low + Math.floor((high - low) / 2);
+          if (publishedIndices[middle] < index) low = middle + 1;
+          else high = middle;
+        }
+        const successor = publishedIndices[low];
+        const successorNode = successor === undefined ? null : nodes.current.get(successor);
+        block.insertBefore(element, successorNode?.parentNode === block ? successorNode : null);
+        publishedIndices.splice(low, 0, index);
+        nodes.current.set(index, element);
+        observer.observe(element);
+        publishedRows += 1;
+        batchRows += 1;
+        if (prioritized) priorityPublishedRows += 1;
+      }
+      if (anchorTop !== null && anchor) container.scrollTop += anchor.getBoundingClientRect().top - anchorTop;
+      revealPendingJump();
+      largestPublicationBatch = Math.max(largestPublicationBatch, batchRows);
+      publicationBatches += 1;
+      firstContentMs ??= performance.now() - fixture.loadStartedAt;
+      if (publishedRows < fixture.rows.length) publicationTimer = setTimeout(publish, 0);
+      else {
+        container.style.overflowAnchor = "auto";
+        publicationMs = performance.now() - publicationStart;
+        onCommit();
+      }
+    };
+    publish();
+    return () => {
+      observer.disconnect();
+      delete fixture.refresh;
+      if (frame !== null) cancelAnimationFrame(frame);
+      if (publicationTimer !== null) clearTimeout(publicationTimer);
+      nodes.current.clear();
+      blocks.clear();
+      container.replaceChildren();
+      for (const category of TOKEN_CATEGORIES) CSS.highlights.delete(`preview-${category}`);
+      CSS.highlights.delete("preview-search");
+      CSS.highlights.delete("preview-active");
+    };
+  }, [fixture, onCommit]);
+
+  return <div ref={scrollRef} data-prototype-scroll data-retained-text style={{ height: VIEWPORT_HEIGHT, overflow: "auto" }} />;
+}
+
+function firstOverlap(matches: readonly Match[], offset: number): number {
+  let low = 0;
+  let high = matches.length;
+  while (low < high) {
+    const middle = low + Math.floor((high - low) / 2);
+    if (matches[middle].to <= offset) low = middle + 1;
+    else high = middle;
+  }
+  return low;
+}
+
+function fragmentContent(model: CodePreviewModel, fragmentIndex: number, matches: Match[], active: number, blockOffset: number) {
+  const fragment = model.fragments[fragmentIndex];
+  const tokens = model.ranges.slice(fragment.firstRange, fragment.rangeEnd);
+  const initialMatch = firstOverlap(matches, blockOffset + fragment.from);
+  const boundaries = new Set([fragment.from, fragment.to]);
+  for (const token of tokens) {
+    boundaries.add(Math.max(fragment.from, token.from));
+    boundaries.add(Math.min(fragment.to, token.to));
+  }
+  for (let index = initialMatch; index < matches.length && matches[index].from < blockOffset + fragment.to; index += 1) {
+    boundaries.add(Math.max(fragment.from, matches[index].from - blockOffset));
+    boundaries.add(Math.min(fragment.to, matches[index].to - blockOffset));
+  }
+  const ordered = [...boundaries].sort((left, right) => left - right);
+  let tokenIndex = 0;
+  let matchIndex = initialMatch;
+  return ordered.slice(0, -1).map((from, index) => {
+    const to = ordered[index + 1];
+    while (tokenIndex < tokens.length && tokens[tokenIndex].to <= from) tokenIndex += 1;
+    while (matchIndex < matches.length && matches[matchIndex].to <= blockOffset + from) matchIndex += 1;
+    const token = tokens[tokenIndex];
+    const matched = matches[matchIndex]?.from <= blockOffset + from;
+    const text = model.text.slice(from, to);
+    const content = matched ? <mark data-active={matchIndex === active ? "true" : undefined}>{text}</mark> : text;
+    return (
+      <span key={from} className={token?.from <= from ? tokenClasses(token.categories) : undefined}>
+        {content}
+      </span>
+    );
+  });
+}
+
+function Preview({ fixture, virtual }: { fixture: Fixture; virtual: boolean }) {
+  const scrollRef = useRef<HTMLDivElement>(null);
+  const [active, setActive] = useState(-1);
+  const virtualizer = useVirtualizer({
+    count: fixture.rows.length,
+    getScrollElement: () => scrollRef.current,
+    estimateSize: (index) => {
+      const row = fixture.rows[index];
+      const model = fixture.models[row.block];
+      const fragment = model.fragments[row.fragment];
+      const text = model.text.slice(fragment.from, fragment.to);
+      return Math.max(1, text.split("\n").length - Number(text.endsWith("\n"))) * ROW_HEIGHT;
+    },
+    overscan: OVERSCAN,
+  });
+
+  useLayoutEffect(() => {
+    window.codePreviewPrototype.jump = (ordinal) => {
+      const match = fixture.matches[ordinal];
+      if (!match) throw new RangeError("Prototype match ordinal is out of bounds");
+      const block = firstOverlap(fixture.blockBounds, match.from);
+      const fragment = findCodePreviewFragment(fixture.models[block], match.from - fixture.offsets[block]);
+      if (fragment === null) throw new Error("Prototype match has no fragment");
+      const rowIndex = fixture.rowStarts[block] + fragment;
+      setActive(ordinal);
+      if (virtual) virtualizer.scrollToIndex(rowIndex, { align: "center" });
+      else scrollRef.current?.querySelector(`[data-index="${rowIndex}"]`)?.scrollIntoView({ block: "center" });
+      return { pending: false };
+    };
+    window.codePreviewPrototype.stats = () => ({
+      preparationMs: fixture.preparationMs,
+      indexingMs: fixture.indexingMs,
+      sourceUnits: fixture.text.length,
+      totalRows: fixture.rows.length,
+      mountedRows: scrollRef.current?.querySelectorAll("[data-index]").length ?? 0,
+      mountedSpans: scrollRef.current?.querySelectorAll("span").length ?? 0,
+      matchCount: fixture.matches.length,
+      active,
+      activeMounted: Boolean(scrollRef.current?.querySelector('[data-active="true"]')),
+      scrollTop: scrollRef.current?.scrollTop,
+      oversizedLines: fixture.models.flatMap((model) => model.fragments).filter((fragment) => fragment.oversizedLine).length,
+      mountedTextUnits: scrollRef.current?.textContent?.length ?? 0,
+    });
+  });
+
+  const rows = virtual ? virtualizer.getVirtualItems() : fixture.rows.map((_, index) => ({ index, start: 0, key: index }));
+  return (
+    <div ref={scrollRef} data-prototype-scroll style={{ height: VIEWPORT_HEIGHT, overflow: "auto", overflowAnchor: "none" }}>
+      <div style={virtual ? { height: virtualizer.getTotalSize(), position: "relative" } : undefined}>
+        {rows.map((item) => {
+          const row = fixture.rows[item.index];
+          return (
+            <pre
+              key={item.key}
+              data-index={item.index}
+              ref={virtual ? virtualizer.measureElement : undefined}
+              style={{
+                margin: 0,
+                whiteSpace: "pre-wrap",
+                overflowWrap: "anywhere",
+                fontSize: 14,
+                lineHeight: `${ROW_HEIGHT}px`,
+                ...(virtual ? { position: "absolute", top: 0, left: 0, width: "100%", transform: `translateY(${item.start}px)` } : {}),
+              }}
+            >
+              <code>{fragmentContent(fixture.models[row.block], row.fragment, fixture.matches, active, fixture.offsets[row.block])}</code>
+            </pre>
+          );
+        })}
+      </div>
+    </div>
+  );
+}
+
+const rootElement = document.getElementById("prototype");
+if (!rootElement) throw new Error("Prototype root is missing");
+const root = createRoot(rootElement);
+const palette = getDefaultTheme("light").components?.syntax;
+if (!palette) throw new Error("Built-in light theme is missing its syntax palette");
+for (const [role, color] of Object.entries(palette)) rootElement.style.setProperty(`--sambee-syntax-${role}`, color);
+const style = document.createElement("style");
+style.textContent = `${Object.entries(syntaxTokenStyles)
+  .map(
+    ([selector, properties]) =>
+      `${selector}{${Object.entries(properties)
+        .map(([name, value]) => `${name.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)}:${value}`)
+        .join(";")}}`
+  )
+  .join("\n")}
+${Object.entries(syntaxTokenStyles)
+  .map(
+    ([selector, properties]) => `::highlight(preview-${selector.slice(".sambee-syntax-".length)}){color:${properties.color ?? "inherit"}}`
+  )
+  .join("\n")}
+mark,::highlight(preview-search){background:#ffe082}mark[data-active="true"],::highlight(preview-active){background:#ff8a65}body{margin:16px}
+@media print{[data-retained-text]{height:auto!important;overflow:visible!important}[data-retained-text] pre{content-visibility:visible!important}}`;
+style.textContent += `
+.document-proof{font-size:14px;line-height:20px;overflow-wrap:anywhere}
+.document-proof pre{white-space:pre-wrap;overflow-wrap:anywhere;font-size:14px;line-height:20px;contain:layout style}
+.document-proof code:has(>.document-code-fragment){white-space:normal}
+.document-code-fragment{display:inline-block;vertical-align:top;width:100%;white-space:pre-wrap;overflow-wrap:anywhere;contain:layout style}
+.document-proof table{border-collapse:collapse;width:100%;table-layout:fixed}.document-proof th,.document-proof td{border:1px solid #999;padding:4px;vertical-align:top}
+::highlight(document-search){background:#ffcc66;color:#171717}
+@media print{[data-markdown-document]{height:auto!important;overflow:visible!important}}
+${Object.entries(syntaxTokenStyles)
+  .map(
+    ([selector, properties]) => `::highlight(document-${selector.slice(".sambee-syntax-".length)}){color:${properties.color ?? "inherit"}}`
+  )
+  .join("\n")}`;
+document.head.append(style);
+let generation = 0;
+let pendingLoad: { controller: AbortController; cancelPublication?: () => void } | null = null;
+let disposeDocument: (() => void) | null = null;
+
+function createFixture(
+  models: CodePreviewModel[],
+  matches: Match[] | null,
+  metadata: Omit<Fixture, "models" | "matches" | "rows" | "offsets" | "rowStarts" | "blockBounds" | "text" | "refresh">
+): Fixture {
+  const offsets: number[] = [];
+  const rowStarts: number[] = [];
+  const blockBounds: Match[] = [];
+  let offset = 0;
+  let rowStart = 0;
+  for (const model of models) {
+    offsets.push(offset);
+    rowStarts.push(rowStart);
+    blockBounds.push({ from: offset, to: offset + model.text.length });
+    offset += model.text.length;
+    rowStart += model.fragments.length;
+  }
+  const text = models.map((model) => model.text).join("");
+  if (matches === null) {
+    matches = [];
+    for (let from = text.indexOf("let x"); from !== -1; from = text.indexOf("let x", from + "let x".length))
+      matches.push({ from, to: from + "let x".length });
+  }
+  return {
+    ...metadata,
+    models,
+    matches,
+    offsets,
+    rowStarts,
+    blockBounds,
+    text,
+    rows: models.flatMap((model, block) => model.fragments.map((_, fragment) => ({ block, fragment }))),
+  };
+}
+
+window.codePreviewPrototype = {
+  async searchDocument() {
+    throw new Error("Load a Markdown document before searching");
+  },
+  async jumpDocument() {
+    throw new Error("Load and search a Markdown document before navigating");
+  },
+  async loadDocument(source) {
+    pendingLoad?.controller.abort();
+    pendingLoad?.cancelPublication?.();
+    disposeDocument?.();
+    const request = { controller: new AbortController() };
+    pendingLoad = request;
+    const current = ++generation;
+    window.codePreviewPrototype.stats = () => ({ complete: false, error: null, batches: 0, generation: current });
+    try {
+      if (
+        typeof Highlight === "undefined" ||
+        !CSS.highlights ||
+        typeof IntersectionObserver === "undefined" ||
+        typeof ResizeObserver === "undefined"
+      ) {
+        throw new Error("Whole-Markdown preview requires CSS Highlights, IntersectionObserver and ResizeObserver; no fallback was used");
+      }
+      const view = await mountMarkdownDocument(root, request.controller.signal, source);
+      request.controller.signal.throwIfAborted();
+      disposeDocument = view.dispose;
+      window.codePreviewPrototype.stats = () => ({ ...view.stats(), generation: current });
+      window.codePreviewPrototype.inspect = () => ({ models: [], matches: [] });
+      window.codePreviewPrototype.searchDocument = view.search;
+      window.codePreviewPrototype.jumpDocument = view.jump;
+      window.codePreviewPrototype.jump = () => {
+        throw new Error("Whole-Markdown navigation is asynchronous; use jumpDocument");
+      };
+      const result = await prepareCodePreviewInWorker(
+        [source],
+        current,
+        request.controller.signal,
+        (diagnostic) => logError(diagnostic.message, diagnostic.context, diagnostic.component),
+        view.consume
+      );
+      request.controller.signal.throwIfAborted();
+      view.finish(result.preparationMs, result.syntaxRanges, createDocumentSyntaxSession(current));
+    } catch (error) {
+      if (current === generation) {
+        const stats = window.codePreviewPrototype.stats();
+        window.codePreviewPrototype.stats = () => ({
+          ...stats,
+          complete: false,
+          error: error instanceof Error ? error.message : String(error),
+        });
+      }
+      throw error;
+    } finally {
+      if (pendingLoad === request) pendingLoad = null;
+    }
+  },
+  async baselineDocument(source) {
+    pendingLoad?.controller.abort();
+    pendingLoad?.cancelPublication?.();
+    disposeDocument?.();
+    disposeDocument = null;
+    pendingLoad = null;
+    generation += 1;
+    await renderMarkdownDocumentBaseline(root, source);
+  },
+  shutdownDocument() {
+    pendingLoad?.controller.abort();
+    pendingLoad?.cancelPublication?.();
+    pendingLoad = null;
+    generation += 1;
+    disposeDocument?.();
+    disposeDocument = null;
+    shutdownCodePreviewWorker();
+    window.codePreviewPrototype.stats = () => ({ complete: false, error: null, disposed: true, generation });
+  },
+  inspect() {
+    throw new Error("Load a fixture before inspecting prepared data");
+  },
+  async load(blocks, virtual) {
+    disposeDocument?.();
+    disposeDocument = null;
+    pendingLoad?.controller.abort();
+    pendingLoad?.cancelPublication?.();
+    const request: NonNullable<typeof pendingLoad> = { controller: new AbortController() };
+    pendingLoad = request;
+    const current = ++generation;
+    const prepareStart = performance.now();
+    const progressive = virtual === "retained-text-worker-progressive";
+    let earlyFixture: Fixture | null = null;
+    let publication: Promise<void> | null = null;
+    const render = (fixture: Fixture) =>
+      new Promise<void>((resolve, reject) => {
+        request.cancelPublication = () => reject(new DOMException("Prototype publication superseded", "AbortError"));
+        root.render(<Commit key={current} fixture={fixture} virtual={virtual} onCommit={resolve} />);
+      });
+    try {
+      if (progressive) {
+        const sourceIndexStart = performance.now();
+        let sourceIndexingYields = 0;
+        const yieldSourceIndexing = async () => {
+          sourceIndexingYields += 1;
+          await yieldHighlightingTask(request.controller.signal);
+        };
+        const plainModels: CodePreviewModel[] = [];
+        let batchUnits = 0;
+        let batchBlocks = 0;
+        for (const text of blocks) {
+          plainModels.push(
+            await createCodePreviewModelAsync(text, [], {
+              signal: request.controller.signal,
+              yieldTask: yieldSourceIndexing,
+            })
+          );
+          batchUnits += text.length;
+          batchBlocks += 1;
+          if (
+            plainModels.length < blocks.length &&
+            (batchUnits >= CODE_PREVIEW_SCAN_MAX_UNITS || batchBlocks >= SOURCE_INDEX_BLOCK_BATCH)
+          ) {
+            await yieldSourceIndexing();
+            batchUnits = 0;
+            batchBlocks = 0;
+          }
+        }
+        request.controller.signal.throwIfAborted();
+        earlyFixture = createFixture(plainModels, [], {
+          sourceIndexingYields,
+          sourceIndexingMs: 0,
+          preparationComplete: false,
+          preparationError: null,
+          sourceChunks: 0,
+          largestSourceChunkUnits: 0,
+          sourceUnitsSent: 0,
+          execution: "worker",
+          transferChunks: 0,
+          largestChunkItems: 0,
+          clientAssemblyMs: 0,
+          preparationWallMs: 0,
+          generation: current,
+          loadStartedAt: prepareStart,
+          preparationMs: 0,
+          indexingMs: 0,
+        });
+        earlyFixture.sourceIndexingMs = performance.now() - sourceIndexStart;
+        publication = render(earlyFixture);
+        void publication.catch(() => undefined);
+      }
+      const workerPrepared =
+        virtual === "retained-text-worker" || progressive
+          ? await prepareCodePreviewInWorker(blocks, current, request.controller.signal, (diagnostic) => {
+              const failure = diagnostic.error ? new Error(diagnostic.error.message) : undefined;
+              if (failure && diagnostic.error) failure.name = diagnostic.error.name;
+              logError(diagnostic.message, diagnostic.context, diagnostic.component, failure);
+            })
+          : null;
+      const prepared = workerPrepared
+        ? null
+        : await highlightingService.prepare(
+            blocks.map((text) => ({ text, label: "javascript" })),
+            request.controller.signal
+          );
+      if (current !== generation) throw new DOMException("Prototype load superseded", "AbortError");
+      const preparationWallMs = performance.now() - prepareStart;
+      const preparationMs = workerPrepared?.preparationMs ?? preparationWallMs;
+      const indexStart = performance.now();
+      const models =
+        workerPrepared?.models ??
+        blocks.map((text, index) => {
+          const result = prepared![index];
+          if (!("ranges" in result)) throw new Error(`Prototype preparation failed: ${result.reason}`);
+          return createCodePreviewModel(text, result.ranges);
+        });
+      const fixture = createFixture(models, workerPrepared?.matches ?? null, {
+        sourceIndexingYields: earlyFixture?.sourceIndexingYields ?? 0,
+        sourceIndexingMs: earlyFixture?.sourceIndexingMs ?? 0,
+        preparationComplete: true,
+        preparationError: null,
+        sourceChunks: workerPrepared?.sourceChunks ?? 0,
+        largestSourceChunkUnits: workerPrepared?.largestSourceChunkUnits ?? 0,
+        sourceUnitsSent: workerPrepared?.sourceUnitsSent ?? 0,
+        execution: workerPrepared ? "worker" : "main-thread",
+        transferChunks: workerPrepared?.chunks ?? 0,
+        largestChunkItems: workerPrepared?.largestChunkItems ?? 0,
+        clientAssemblyMs: workerPrepared?.clientAssemblyMs ?? 0,
+        preparationWallMs,
+        generation: current,
+        loadStartedAt: prepareStart,
+        preparationMs,
+        indexingMs: workerPrepared?.indexingMs ?? 0,
+      });
+      fixture.indexingMs += performance.now() - indexStart;
+      if (earlyFixture) {
+        Object.assign(earlyFixture, fixture);
+        earlyFixture.refresh?.();
+        await publication;
+      } else await render(fixture);
+    } catch (error) {
+      if (earlyFixture && current === generation) {
+        earlyFixture.preparationError = error instanceof Error ? error.message : "Prototype preparation failed";
+        earlyFixture.refresh?.();
+        await publication;
+      }
+      throw error;
+    } finally {
+      if (pendingLoad === request) pendingLoad = null;
+    }
+  },
+  jump() {
+    throw new Error("Load a fixture before navigating");
+  },
+  stats() {
+    throw new Error("Load a fixture before reading metrics");
+  },
+};
+
+function Commit({
+  fixture,
+  virtual,
+  onCommit,
+}: {
+  fixture: Fixture;
+  virtual: boolean | "retained-text" | "retained-text-worker" | "retained-text-worker-progressive";
+  onCommit: () => void;
+}) {
+  useLayoutEffect(() => {
+    window.codePreviewPrototype.inspect = () => ({ models: fixture.models, matches: fixture.matches });
+    if (typeof virtual !== "string") onCommit();
+  }, [fixture, virtual, onCommit]);
+  return typeof virtual === "string" ? (
+    <RetainedTextPreview fixture={fixture} onCommit={onCommit} />
+  ) : (
+    <Preview fixture={fixture} virtual={virtual} />
+  );
+}
diff --git a/frontend/scripts/prototypes/markdownDocumentPreview.tsx b/frontend/scripts/prototypes/markdownDocumentPreview.tsx
new file mode 100644
index 000000000..9ca3065ed
--- /dev/null
+++ b/frontend/scripts/prototypes/markdownDocumentPreview.tsx
@@ -0,0 +1,511 @@
+export * from "../../src/utils/markdownDocumentPreview";import { useLayoutEffect, useRef } from "react";
+import type { Root } from "react-dom/client";
+import ReactMarkdown, { defaultUrlTransform } from "react-markdown";
+import remarkGfm from "remark-gfm";
+import { normalizeMarkdownTableCellLineBreaks, remarkRenderMarkdownTableCellLineBreaks } from "../../src/components/Viewer/markdownTableCellLineBreaks";
+import { yieldHighlightingTask } from "../../src/utils/codeMirrorHighlighting";
+import {
+  DOCUMENT_PUBLICATION_BATCH_ITEMS,
+  DOCUMENT_RECORD_BATCH_ITEMS,
+  DOCUMENT_SYNTAX_CACHE_RANGES,
+  DOCUMENT_SYNTAX_WINDOW_PARTS,
+  type DocumentSyntaxWindow,
+  type MarkdownDocumentRecord,
+} from "../../src/utils/markdownDocumentPreviewModel";
+import { DocumentSearchIndexer, type DocumentSearchOptions } from "../../src/utils/markdownDocumentSearch";
+import { type SyntaxRange, TOKEN_CATEGORIES } from "../../src/utils/syntaxHighlighting";
+import type { createDocumentSyntaxSession } from "./markdownCodePreparation";
+import { createDocumentSearchSession, type DocumentMatch, type DocumentSearchResult } from "./markdownDocumentSearch";
+
+const MAX_DECORATION_RANGES = 4_000;
+const PUBLICATION_BATCHES_PER_FRAME = 2;
+const ALLOWED_TAGS = new Set(
+  "a blockquote br code del div em h1 h2 h3 h4 h5 h6 hr img input li ol p pre section span strong sup table tbody td th thead tr ul".split(
+    " "
+  )
+);
+
+interface DocumentView {
+  search: (query: string, options?: DocumentSearchOptions) => Promise<DocumentSearchResult>;
+  jump: (ordinal: number) => Promise<{ pending: boolean }>;
+  consume: (records: readonly MarkdownDocumentRecord[]) => Promise<void>;
+  finish: (workerPipelineWallMs: number, syntaxRanges: number, session: ReturnType<typeof createDocumentSyntaxSession>) => void;
+  dispose: () => void;
+  stats: () => Record<string, unknown>;
+}
+
+async function yieldDocumentPublication(signal: AbortSignal): Promise<void> {
+  signal.throwIfAborted();
+  if (document.hidden) return yieldHighlightingTask(signal);
+  await new Promise<void>((resolve, reject) => {
+    const cleanup = () => {
+      cancelAnimationFrame(frame);
+      signal.removeEventListener("abort", abort);
+      document.removeEventListener("visibilitychange", visibility);
+    };
+    const complete = () => {
+      cleanup();
+      resolve();
+    };
+    const abort = () => {
+      cleanup();
+      reject(signal.reason);
+    };
+    const visibility = () => {
+      if (document.hidden) complete();
+    };
+    const frame = requestAnimationFrame(complete);
+    signal.addEventListener("abort", abort, { once: true });
+    document.addEventListener("visibilitychange", visibility);
+  });
+}
+
+function DocumentHost({ ready }: { ready: (element: HTMLDivElement) => (() => void) | undefined }) {
+  const ref = useRef<HTMLDivElement>(null);
+  useLayoutEffect(() => (ref.current ? ready(ref.current) : undefined), [ready]);
+  return <div ref={ref} data-markdown-document className="document-proof" style={{ height: 480, overflow: "auto" }} />;
+}
+
+export function mountMarkdownDocument(root: Root | HTMLDivElement, signal: AbortSignal, source: string, options: { hostSearch?: boolean; hostSyntax?: boolean } = {}): Promise<DocumentView> {
+  signal.throwIfAborted();
+  const searchSession = createDocumentSearchSession(source);
+  return new Promise((resolve, reject) => {
+    const abort = () => {
+      searchSession.dispose();
+      reject(signal.reason);
+    };
+    signal.addEventListener("abort", abort, { once: true });
+    const ready = (container: HTMLDivElement) => {
+          signal.removeEventListener("abort", abort);
+          if (signal.aborted) {
+            reject(signal.reason);
+            return;
+          }
+          const started = performance.now();
+          const elements = new Map<number, HTMLElement>([[0, container]]);
+          const fragmentCodes = new Map<number, number>();
+          const parts = new Map<number, { node: Text; from: number; to: number }[]>();
+          const tokens = new Map<number, SyntaxRange[]>();
+          const attributes = new Map<string, string>();
+          const searchIndexer = new DocumentSearchIndexer();
+          const searchNodes: { node: Text; from: number; to: number }[] = [];
+          let searchController: AbortController | null = null;
+          let searchQuery = "";
+          let searchOptions: DocumentSearchOptions = {};
+          let searchResult: DocumentSearchResult | null = null;
+          let searchRevision = 0;
+          let activeMatch: (DocumentMatch & { ordinal: number; pending: boolean }) | null = null;
+          const reveal = () => {
+            if (!activeMatch?.pending || disposed) return;
+            const locate = (offset: number) => {
+              let low = 0;
+              let high = searchNodes.length;
+              while (low < high) {
+                const middle = low + Math.floor((high - low) / 2);
+                if (searchNodes[middle].to < offset) low = middle + 1;
+                else high = middle;
+              }
+              return searchNodes[low];
+            };
+            const start = locate(activeMatch.from);
+            const end = locate(activeMatch.to);
+            if (!start || !end) return;
+            const range = new Range();
+            range.setStart(start.node, Math.max(0, Math.min(start.node.length, activeMatch.from - start.from)));
+            range.setEnd(end.node, Math.max(0, Math.min(end.node.length, activeMatch.to - end.from)));
+            CSS.highlights.set("document-search", new Highlight(range));
+            activeMatch.pending = false;
+            const rect = range.getBoundingClientRect();
+            const viewport = container.getBoundingClientRect();
+            container.scrollTop += rect.top - viewport.top - container.clientHeight / 2;
+          };
+          const visible = new Set<number>();
+          let frame: number | null = null;
+          let disposed = false;
+          let batches = 0;
+          let largestBatch = 0;
+          let firstContentMs: number | null = null;
+          let complete = false;
+          let workerPipelineWallMs = 0;
+          let highlightRanges = 0;
+          let decorationLimited = false;
+          let mountedSpans = 0;
+          let textUnits = 0;
+          let syntaxSession: ReturnType<typeof createDocumentSyntaxSession> | null = null;
+          let workerSyntaxRanges = 0;
+          let cachedSyntaxRanges = 0;
+          let peakCachedSyntaxRanges = 0;
+          let syntaxPages = 0;
+          let largestSyntaxPage = 0;
+          let syntaxError: string | null = null;
+          let syntaxFetching = false;
+          let syntaxWindowLimited = false;
+          let geometryProbes = 0;
+          let desiredWindows: DocumentSyntaxWindow[] = [];
+          let desiredKey = "";
+          let appliedKey = "";
+          let syntaxRevision = 0;
+          let decorationKey = "";
+          const fetchWindow = () => {
+            if (!syntaxSession || syntaxFetching || disposed || desiredKey === appliedKey || syntaxError) return;
+            syntaxFetching = true;
+            void (async () => {
+              while (!disposed && desiredKey !== appliedKey) {
+                const key = desiredKey;
+                const windows = desiredWindows;
+                tokens.clear();
+                syntaxRevision += 1;
+                cachedSyntaxRanges = 0;
+                syntaxWindowLimited = false;
+                for (const window of windows) {
+                  let offset: number | null = 0;
+                  do {
+                    const page = await syntaxSession!.page(window, offset);
+                    if (disposed || key !== desiredKey) break;
+                    syntaxPages += 1;
+                    largestSyntaxPage = Math.max(largestSyntaxPage, page.records.length);
+                    const collection = tokens.get(window.id) ?? [];
+                    for (const record of page.records) {
+                      const last = collection.at(-1);
+                      if (last?.from === record.range.from && last.to === record.range.to) continue;
+                      if (cachedSyntaxRanges === DOCUMENT_SYNTAX_CACHE_RANGES) {
+                        syntaxWindowLimited = true;
+                        break;
+                      }
+                      collection.push(record.range);
+                      cachedSyntaxRanges += 1;
+                    }
+                    tokens.set(window.id, collection);
+                    syntaxRevision += 1;
+                    peakCachedSyntaxRanges = Math.max(peakCachedSyntaxRanges, cachedSyntaxRanges);
+                    offset = page.next;
+                    schedule();
+                    if (cachedSyntaxRanges === DOCUMENT_SYNTAX_CACHE_RANGES) {
+                      syntaxWindowLimited = true;
+                      break;
+                    }
+                  } while (offset !== null);
+                  if (disposed || key !== desiredKey || syntaxWindowLimited) break;
+                }
+                if (key === desiredKey) appliedKey = key;
+              }
+            })()
+              .catch((error: unknown) => {
+                if (!disposed) {
+                  syntaxError = error instanceof Error ? error.message : String(error);
+                  tokens.clear();
+                  syntaxRevision += 1;
+                  cachedSyntaxRanges = 0;
+                  schedule();
+                }
+              })
+              .finally(() => {
+                syntaxFetching = false;
+              });
+          };
+          const fallbacks: { id: number; reason: string }[] = [];
+          const paint = () => {
+            frame = null;
+            if (disposed || signal.aborted) return;
+            if (visible.size === 0 && highlightRanges === 0 && desiredWindows.length === 0) return;
+            const categories = new Map<string, Range[]>();
+            const viewport = container.getBoundingClientRect();
+            const viewportParts = new Map<number, { node: Text; from: number; to: number }[]>();
+            const windows: DocumentSyntaxWindow[] = [];
+            geometryProbes = 0;
+            let inspectedFragments = 0;
+            for (const id of visible) {
+              if (inspectedFragments++ === DOCUMENT_SYNTAX_WINDOW_PARTS || windows.length === DOCUMENT_SYNTAX_WINDOW_PARTS) break;
+              const collection = parts.get(id) ?? [];
+              const rectFor = (index: number) => {
+                geometryProbes += 1;
+                const range = new Range();
+                range.selectNodeContents(collection[index].node);
+                return range.getBoundingClientRect();
+              };
+              let low = 0;
+              let high = collection.length;
+              while (low < high) {
+                const middle = low + Math.floor((high - low) / 2);
+                if (rectFor(middle).bottom < viewport.top - container.clientHeight) low = middle + 1;
+                else high = middle;
+              }
+              const selected = [];
+              for (let index = low; index < collection.length && windows.length < DOCUMENT_SYNTAX_WINDOW_PARTS; index += 1) {
+                if (rectFor(index).top > viewport.bottom + container.clientHeight) break;
+                const part = collection[index];
+                selected.push(part);
+                windows.push({ id: fragmentCodes.get(id)!, from: part.from, to: part.to });
+              }
+              viewportParts.set(id, selected);
+            }
+            windows.sort((left, right) => left.id - right.id || left.from - right.from);
+            const key = JSON.stringify(windows);
+            if (key !== desiredKey) {
+              desiredWindows = windows;
+              desiredKey = key;
+              tokens.clear();
+              syntaxRevision += 1;
+              cachedSyntaxRanges = 0;
+            }
+            fetchWindow();
+            const nextDecorationKey = `${key}:${syntaxRevision}`;
+            if (nextDecorationKey === decorationKey) return;
+            decorationKey = nextDecorationKey;
+            highlightRanges = 0;
+            decorationLimited = false;
+            for (const [id, selected] of viewportParts) {
+              const ranges = tokens.get(fragmentCodes.get(id)!) ?? [];
+              for (const part of selected) {
+                let low = 0;
+                let high = ranges.length;
+                while (low < high) {
+                  const middle = low + Math.floor((high - low) / 2);
+                  if (ranges[middle].to <= part.from) low = middle + 1;
+                  else high = middle;
+                }
+                for (let index = low; index < ranges.length && ranges[index].from < part.to; index += 1) {
+                  const token = ranges[index];
+                  for (const category of token.categories) {
+                    if (highlightRanges === MAX_DECORATION_RANGES) {
+                      decorationLimited = true;
+                      break;
+                    }
+                    const range = new Range();
+                    range.setStart(part.node, Math.max(part.from, token.from) - part.from);
+                    range.setEnd(part.node, Math.min(part.to, token.to) - part.from);
+                    const collection = categories.get(category) ?? [];
+                    collection.push(range);
+                    categories.set(category, collection);
+                    highlightRanges += 1;
+                  }
+                  if (decorationLimited) break;
+                }
+                if (decorationLimited) break;
+              }
+              if (decorationLimited) break;
+            }
+            for (const category of TOKEN_CATEGORIES)
+              CSS.highlights.set(`document-${category}`, new Highlight(...(categories.get(category) ?? [])));
+          };
+          const schedule = () => {
+            if (!disposed && frame === null) frame = requestAnimationFrame(paint);
+          };
+          const observer = new IntersectionObserver(
+            (entries) => {
+              for (const entry of entries) {
+                const id = Number((entry.target as HTMLElement).dataset.documentFragment);
+                if (entry.isIntersecting) visible.add(id);
+                else visible.delete(id);
+              }
+              schedule();
+            },
+            { root: container, rootMargin: "480px 0px" }
+          );
+          const resizeObserver = new ResizeObserver(schedule);
+          resizeObserver.observe(container);
+          const dispose = () => {
+            if (disposed) return;
+            disposed = true;
+            signal.removeEventListener("abort", dispose);
+            searchRevision += 1;
+            searchController?.abort();
+            searchSession.dispose();
+            syntaxSession?.dispose();
+            syntaxSession = null;
+            searchNodes.length = 0;
+            searchResult = null;
+            activeMatch = null;
+            CSS.highlights.delete("document-search");
+            observer.disconnect();
+            resizeObserver.disconnect();
+            container.removeEventListener("scroll", schedule);
+            container.removeEventListener("load", schedule, true);
+            document.fonts.removeEventListener("loadingdone", schedule);
+            if (frame !== null) cancelAnimationFrame(frame);
+            for (const category of TOKEN_CATEGORIES) CSS.highlights.delete(`document-${category}`);
+            elements.clear();
+            parts.clear();
+            tokens.clear();
+            attributes.clear();
+            visible.clear();
+            fragmentCodes.clear();
+            fallbacks.length = 0;
+            desiredWindows = [];
+            container.replaceChildren();
+          };
+          container.addEventListener("scroll", schedule, { passive: true });
+          container.addEventListener("load", schedule, true);
+          document.fonts.addEventListener("loadingdone", schedule);
+          signal.addEventListener("abort", dispose, { once: true });
+          resolve({
+            async search(query, options = {}) {
+              if (disposed) throw new DOMException("Document preview disposed", "AbortError");
+              searchController?.abort();
+              searchController = new AbortController();
+              const revision = ++searchRevision;
+              searchQuery = query;
+              searchOptions = { ...options };
+              searchResult = null;
+              activeMatch = null;
+              CSS.highlights.delete("document-search");
+              const result = await searchSession.search(query, searchOptions, searchController.signal);
+              if (revision !== searchRevision || disposed) throw new DOMException("Document search superseded", "AbortError");
+              searchResult = result;
+              if (result.matches[0]) {
+                activeMatch = { ...result.matches[0], ordinal: 0, pending: true };
+                reveal();
+              }
+              return result;
+            },
+            async jump(ordinal) {
+              if (disposed) throw new DOMException("Document preview disposed", "AbortError");
+              if (!searchResult) throw new Error("Document search results are pending or unavailable");
+              if (!Number.isSafeInteger(ordinal) || ordinal < 0 || ordinal >= searchResult.count)
+                throw new Error("Document match ordinal is out of range");
+              searchController?.abort();
+              searchController = new AbortController();
+              const revision = ++searchRevision;
+              let result = searchResult;
+              if (ordinal < result.offset || ordinal >= result.offset + result.matches.length)
+                result = await searchSession.search(searchQuery, searchOptions, searchController.signal, ordinal);
+              if (revision !== searchRevision || disposed) throw new DOMException("Document navigation superseded", "AbortError");
+              searchResult = result;
+              const match = result.matches[ordinal - result.offset];
+              if (!match) throw new Error("Document search returned no requested match");
+              activeMatch = { ...match, ordinal, pending: true };
+              reveal();
+              return { pending: activeMatch.pending };
+            },
+            async consume(records) {
+              signal.throwIfAborted();
+              if (disposed) throw new DOMException("Document preview disposed", "AbortError");
+              const additions = new Map<HTMLElement, DocumentFragment>();
+              const append = (parent: HTMLElement, node: Node) => {
+                let fragment = additions.get(parent);
+                if (!fragment) {
+                  fragment = document.createDocumentFragment();
+                  additions.set(parent, fragment);
+                }
+                fragment.append(node);
+              };
+              for (const record of records) {
+                const searchSegment = options.hostSearch ? null : searchIndexer.append(record);
+                if (record.kind === "element") {
+                  if (!ALLOWED_TAGS.has(record.tag) || !elements.has(record.parent) || elements.has(record.id))
+                    throw new Error("Invalid Markdown element record");
+                  const element = document.createElement(record.tag);
+                  if (record.tag === "span") mountedSpans += 1;
+                  if (record.fragment) {
+                    element.dataset.documentFragment = String(record.id);
+                    element.className = "document-code-fragment";
+                    fragmentCodes.set(record.id, record.parent);
+                    observer.observe(element);
+                  }
+                  append(elements.get(record.parent)!, element);
+                  elements.set(record.id, element);
+                } else if (record.kind === "text") {
+                  const parent = elements.get(record.parent);
+                  if (!parent) throw new Error("Markdown text has no parent");
+                  const node = document.createTextNode(record.value);
+                  textUnits += record.value.length;
+                  append(parent, node);
+                  if (searchSegment) searchNodes.push({ node, from: searchSegment.from, to: searchSegment.to });
+                  if (fragmentCodes.has(record.parent)) {
+                    const collection = parts.get(record.parent) ?? [];
+                    collection.push({ node, from: record.from, to: record.from + record.value.length });
+                    parts.set(record.parent, collection);
+                  }
+                } else if (record.kind === "attribute") {
+                  if (/^on/i.test(record.name) || record.name === "style") throw new Error("Unsafe Markdown attribute");
+                  const key = `${record.id}:${record.name}`;
+                  const value = (attributes.get(key) ?? "") + record.value;
+                  if (!record.final) attributes.set(key, value);
+                  else {
+                    attributes.delete(key);
+                    const element = elements.get(record.id);
+                    if (!element) throw new Error("Markdown attribute has no element");
+                    const name =
+                      record.name === "className"
+                        ? "class"
+                        : record.name.startsWith("aria")
+                          ? `aria-${record.name.slice(4).toLowerCase()}`
+                          : record.name.startsWith("data")
+                            ? record.name.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)
+                            : record.name.toLowerCase();
+                    element.setAttribute(name, name === "href" || name === "src" ? defaultUrlTransform(value) : value);
+                    if (name === "align" && ["left", "center", "right"].includes(value)) element.style.textAlign = value;
+                  }
+                } else if (record.kind === "syntax") {
+                  throw new Error("Full-document syntax records are not accepted by the viewport renderer");
+                } else fallbacks.push(record);
+              }
+              for (const [parent, fragment] of [...additions].reverse()) parent.append(fragment);
+              batches += 1;
+              largestBatch = Math.max(largestBatch, records.length);
+              if (textUnits > 0) firstContentMs ??= performance.now() - started;
+              schedule();
+              reveal();
+              if (batches % PUBLICATION_BATCHES_PER_FRAME === 0) await yieldDocumentPublication(signal);
+            },
+            finish(wallMs, syntaxRanges, session) {
+              if (!options.hostSearch) searchIndexer.finish();
+              syntaxSession = session;
+              workerSyntaxRanges = syntaxRanges;
+              workerPipelineWallMs = wallMs;
+              complete = true;
+              schedule();
+            },
+            dispose,
+            stats: () => ({
+              complete,
+              error: null,
+              batches,
+              largestBatch,
+              batchLimit: DOCUMENT_PUBLICATION_BATCH_ITEMS,
+              syntaxPageLimit: DOCUMENT_RECORD_BATCH_ITEMS,
+              firstContentMs,
+              workerPipelineWallMs,
+              highlightRanges,
+              decorationLimited,
+              cachedSyntaxRanges,
+              peakCachedSyntaxRanges,
+              syntaxCacheLimit: DOCUMENT_SYNTAX_CACHE_RANGES,
+              syntaxPages,
+              largestSyntaxPage,
+              syntaxFetching,
+              syntaxWindowLimited,
+              syntaxError,
+              workerSyntaxRanges,
+              geometryProbes,
+              fallbacks,
+              mountedElements: elements.size - 1,
+              mountedSpans,
+              textUnits,
+              search: searchSession.stats(),
+              activeMatch: activeMatch ? { ...activeMatch } : null,
+            }),
+          });
+          return dispose;
+    };
+    if (root instanceof HTMLDivElement) ready(root);
+    else root.render(<DocumentHost ready={ready} />);
+  });
+}
+
+export function renderMarkdownDocumentBaseline(root: Root, source: string): Promise<void> {
+  return new Promise((resolve) =>
+    root.render(
+      <div
+        className="document-proof"
+        data-markdown-baseline
+        style={{ height: 480, overflow: "auto" }}
+        ref={(element) => {
+          if (element) resolve();
+        }}
+      >
+        <ReactMarkdown remarkPlugins={[remarkGfm, remarkRenderMarkdownTableCellLineBreaks]}>{normalizeMarkdownTableCellLineBreaks(source)}</ReactMarkdown>
+      </div>
+    )
+  );
+}
diff --git a/frontend/scripts/prototypes/markdownDocumentSearch.ts b/frontend/scripts/prototypes/markdownDocumentSearch.ts
new file mode 100644
index 000000000..941453498
--- /dev/null
+++ b/frontend/scripts/prototypes/markdownDocumentSearch.ts
@@ -0,0 +1,179 @@
+export * from "../../src/utils/markdownDocumentSearchWorker";import type { DocumentSearchOptions } from "../../src/utils/markdownDocumentSearch";
+import { PREPARATION_SOURCE_CHUNK_UNITS } from "../../src/utils/markdownCodePreparationProtocol";
+
+export const DOCUMENT_SEARCH_WINDOW = 64;
+export const DOCUMENT_SEARCH_PROGRESS_MATCHES = 512;
+export const DOCUMENT_SEARCH_TIMEOUT_MS = 2_000;
+
+export interface DocumentMatch {
+  from: number;
+  to: number;
+}
+export interface DocumentSearchResult {
+  count: number;
+  offset: number;
+  matches: DocumentMatch[];
+}
+export type DocumentSearchRequest =
+  | { type: "init" }
+  | { type: "source"; sequence: number; text: string; final: boolean }
+  | { type: "search"; id: number; query: string; options: DocumentSearchOptions; ordinal: number }
+  | { type: "ack"; id: number };
+export type DocumentSearchResponse =
+  | { type: "source-ack"; sequence: number }
+  | { type: "ready"; textUnits: number; segments: number; parseMs: number; indexMs: number }
+  | { type: "progress"; id: number; count: number }
+  | ({ type: "result"; id: number } & DocumentSearchResult)
+  | { type: "error"; message: string };
+
+export function createDocumentSearchSession(source: string) {
+  let sourceText: string | null = source;
+  let worker: Worker | null = null;
+  let ready = false;
+  let nextId = 0;
+  let cancel: (() => void) | null = null;
+  let status: Record<string, unknown> = { complete: false, lowerBound: 0, count: null, error: null, cachedMatches: 0 };
+  const dispose = () => {
+    cancel?.();
+    worker?.terminate();
+    worker = null;
+    ready = false;
+    sourceText = null;
+    status = { complete: false, disposed: true, cachedMatches: 0 };
+  };
+  return {
+    dispose,
+    stats: () => status,
+    search(query: string, options: DocumentSearchOptions, signal: AbortSignal, ordinal = 0): Promise<DocumentSearchResult> {
+      cancel?.();
+      if (signal.aborted) return Promise.reject(signal.reason);
+      if (sourceText === null) return Promise.reject(new Error("Document search session disposed"));
+      if (!Number.isSafeInteger(ordinal) || ordinal < 0) return Promise.reject(new Error("Invalid document match ordinal"));
+      const id = ++nextId;
+      status = { complete: false, lowerBound: 0, count: null, error: null, cachedMatches: 0 };
+      return new Promise((resolve, reject) => {
+        let current: Worker;
+        try {
+          if (typeof Worker === "undefined") throw new Error("Document search requires a worker; no main-thread fallback was used");
+          worker ??= new Worker(new URL("./markdownDocumentSearch.worker.ts", import.meta.url), { type: "module" });
+          current = worker;
+        } catch (error) {
+          status = { ...status, error: error instanceof Error ? error.message : String(error) };
+          reject(error);
+          return;
+        }
+        let settled = false;
+        let timer: ReturnType<typeof setTimeout>;
+        let sequence = 0;
+        let sourceOffset = 0;
+        let sourceComplete = false;
+        const cleanup = () => {
+          clearTimeout(timer);
+          signal.removeEventListener("abort", abort);
+          current.onmessage = null;
+          current.onerror = null;
+          current.removeEventListener("messageerror", decodeFailure);
+          if (cancel === abort) cancel = null;
+        };
+        const fail = (error: unknown) => {
+          if (settled) return;
+          settled = true;
+          cleanup();
+          current.terminate();
+          if (worker === current) {
+            worker = null;
+            ready = false;
+          }
+          status = {
+            ...status,
+            complete: false,
+            count: null,
+            cachedMatches: 0,
+            error: error instanceof Error ? error.message : String(error),
+          };
+          reject(error);
+        };
+        const abort = () => fail(new DOMException("Document search superseded", "AbortError"));
+        const decodeFailure = () => fail(new Error("Document search result could not be decoded"));
+        const arm = () => {
+          clearTimeout(timer);
+          timer = setTimeout(
+            () => fail(new Error("Document search exceeded its prototype progress deadline; worker terminated")),
+            DOCUMENT_SEARCH_TIMEOUT_MS
+          );
+        };
+        const send = (request: DocumentSearchRequest) => {
+          current.postMessage(request);
+        };
+        const run = () => send({ type: "search", id, query, options, ordinal });
+        cancel = abort;
+        signal.addEventListener("abort", abort, { once: true });
+        current.addEventListener("messageerror", decodeFailure);
+        current.onerror = (event) => {
+          event.preventDefault();
+          fail(new Error(`Document search worker failed: ${event.message}`));
+        };
+        current.onmessage = (event: MessageEvent<DocumentSearchResponse>) => {
+          if (settled) return;
+          try {
+            const response = event.data;
+            if (response.type === "error") {
+              fail(new Error(response.message));
+              return;
+            }
+            arm();
+            if (response.type === "source-ack") {
+              if (ready || sourceComplete || response.sequence !== sequence)
+                throw new Error("Invalid document search source acknowledgement");
+              const text = sourceText!.slice(sourceOffset, sourceOffset + PREPARATION_SOURCE_CHUNK_UNITS);
+              sourceOffset += text.length;
+              const final = sourceOffset === sourceText!.length;
+              sourceComplete = final;
+              send({ type: "source", sequence: ++sequence, text, final });
+              return;
+            }
+            if (response.type === "ready") {
+              ready = true;
+              status = { ...status, textUnits: response.textUnits, segments: response.segments, parseMs: response.parseMs, indexMs: response.indexMs };
+              run();
+              return;
+            }
+            if (response.id !== id) return;
+            if (response.type === "progress") {
+              status = { ...status, lowerBound: response.count };
+              send({ type: "ack", id });
+              return;
+            }
+            if (
+              response.type !== "result" ||
+              !Number.isSafeInteger(response.count) ||
+              response.count < 0 ||
+              response.matches.length > DOCUMENT_SEARCH_WINDOW
+            )
+              throw new Error("Invalid document search result");
+            status = {
+              ...status,
+              complete: true,
+              count: response.count,
+              lowerBound: response.count,
+              error: null,
+              cachedMatches: response.matches.length,
+            };
+            settled = true;
+            cleanup();
+            resolve(response);
+          } catch (error) {
+            fail(error);
+          }
+        };
+        arm();
+        try {
+          if (ready) run();
+          else send({ type: "init" });
+        } catch (error) {
+          fail(error);
+        }
+      });
+    },
+  };
+}
diff --git a/frontend/scripts/prototypes/markdownDocumentSearch.worker.ts b/frontend/scripts/prototypes/markdownDocumentSearch.worker.ts
new file mode 100644
index 000000000..710f642e6
--- /dev/null
+++ b/frontend/scripts/prototypes/markdownDocumentSearch.worker.ts
@@ -0,0 +1,95 @@
+import "../../src/utils/markdownDocumentSearch.worker";import { Text } from "@codemirror/state";
+import { createMarkdownDocumentModel, markdownDocumentRecords } from "../../src/utils/markdownDocumentPreviewModel";
+import { createDocumentSearchIndex, documentSearchMatches } from "../../src/utils/markdownDocumentSearch";
+import { PREPARATION_SOURCE_CHUNK_UNITS } from "../../src/utils/markdownCodePreparationProtocol";
+import {
+  DOCUMENT_SEARCH_PROGRESS_MATCHES,
+  DOCUMENT_SEARCH_WINDOW,
+  type DocumentMatch,
+  type DocumentSearchRequest,
+  type DocumentSearchResponse,
+} from "./markdownDocumentSearch";
+
+let parts: string[] = [];
+let sequence = 0;
+let received = false;
+let index: Text | null = null;
+let acknowledge: (() => void) | null = null;
+let active: number | null = null;
+let cached: { key: string; count: number; offset: number; matches: DocumentMatch[] } | null = null;
+const send = (response: DocumentSearchResponse) => postMessage(response);
+
+async function search(request: Extract<DocumentSearchRequest, { type: "search" }>) {
+  if (!index || active !== null) throw new Error("Document search worker is not ready");
+  if (!Number.isSafeInteger(request.ordinal) || request.ordinal < 0) throw new Error("Invalid document match ordinal");
+  active = request.id;
+  try {
+    const key = JSON.stringify([request.query, !!request.options.caseSensitive, !!request.options.regexp, !!request.options.wholeWord]);
+    if (
+      cached?.key === key &&
+      (cached.count === 0 || (request.ordinal >= cached.offset && request.ordinal < cached.offset + cached.matches.length))
+    ) {
+      send({ type: "result", id: request.id, ...cached });
+      return;
+    }
+    const knownCount = cached?.key === key ? cached.count : null;
+    const offset = Math.floor(request.ordinal / DOCUMENT_SEARCH_WINDOW) * DOCUMENT_SEARCH_WINDOW;
+    const matches: DocumentMatch[] = [];
+    let count = 0;
+    for (const match of documentSearchMatches(index, request.query, request.options)) {
+      if (count >= offset && matches.length < DOCUMENT_SEARCH_WINDOW) matches.push(match);
+      count += 1;
+      if (knownCount !== null && count >= offset + DOCUMENT_SEARCH_WINDOW) break;
+      if (count % DOCUMENT_SEARCH_PROGRESS_MATCHES === 0)
+        await new Promise<void>((resolve) => {
+          acknowledge = resolve;
+          send({ type: "progress", id: request.id, count });
+        });
+    }
+    cached = { key, count: knownCount ?? count, offset, matches };
+    send({ type: "result", id: request.id, ...cached });
+  } finally {
+    active = null;
+    acknowledge = null;
+  }
+}
+
+globalThis.onmessage = (event: MessageEvent<DocumentSearchRequest>) => {
+  const request = event.data;
+  const run = async () => {
+    if (request.type === "init") {
+      if (index || received || parts.length) throw new Error("Document search worker already initialized");
+      send({ type: "source-ack", sequence: 0 });
+    } else if (request.type === "source") {
+      if (
+        received ||
+        request.sequence !== sequence + 1 ||
+        typeof request.text !== "string" ||
+        request.text.length > PREPARATION_SOURCE_CHUNK_UNITS
+      )
+        throw new Error("Invalid document search source chunk");
+      sequence = request.sequence;
+      parts.push(request.text);
+      if (!request.final) {
+        send({ type: "source-ack", sequence });
+        return;
+      }
+      received = true;
+      const source = parts.join("");
+      parts = [];
+      const parseStarted = performance.now();
+      const model = await createMarkdownDocumentModel(source);
+      const parseMs = performance.now() - parseStarted;
+      const indexStarted = performance.now();
+      const built = createDocumentSearchIndex(markdownDocumentRecords(model));
+      index = Text.of(built.text.split("\n"));
+      send({ type: "ready", textUnits: index.length, segments: built.segments.length, parseMs, indexMs: performance.now() - indexStarted });
+    } else if (request.type === "search") await search(request);
+    else if (request.type === "ack" && request.id === active) {
+      const resume = acknowledge;
+      acknowledge = null;
+      resume?.();
+    }
+  };
+  void run().catch((error: unknown) => send({ type: "error", message: error instanceof Error ? error.message : String(error) }));
+};
diff --git a/frontend/scripts/prototypes/sourceSearchContainment.worker.mjs b/frontend/scripts/prototypes/sourceSearchContainment.worker.mjs
new file mode 100644
index 000000000..8aa6a15cf
--- /dev/null
+++ b/frontend/scripts/prototypes/sourceSearchContainment.worker.mjs
@@ -0,0 +1,49 @@
+import { history, undo } from "@codemirror/commands";
+import { findNext, findPrevious, replaceAll, replaceNext, SearchQuery, search, setSearchQuery } from "@codemirror/search";
+import { EditorState } from "@codemirror/state";
+
+export function executeSourceSearchProof(request) {
+  let state = EditorState.create({ doc: request.source, extensions: [search(), history()] });
+  const query = new SearchQuery({ search: request.query, regexp: true, literal: true, replace: request.replace ?? "" });
+  if (!query.valid) throw new Error("Invalid source-search expression");
+  state = state.update({ effects: setSearchQuery.of(query), selection: request.selection ?? { anchor: 0 } }).state;
+  let edits = 0;
+  const target = {
+    get state() {
+      return state;
+    },
+    plugin: () => null,
+    dispatch: (transaction) => {
+      const applied = transaction.state ? transaction : state.update(transaction);
+      if (applied.docChanged) edits += 1;
+      state = applied.state;
+    },
+  };
+  let count = null;
+  if (["count", "active-range", "visible-matches"].includes(request.operation)) {
+    count = 0;
+    const bounds = request.operation === "visible-matches" ? [0, state.doc.length] : [];
+    const cursor = query.getCursor(state, ...bounds);
+    for (let result = cursor.next(); !result.done; result = cursor.next()) count += 1;
+  } else {
+    const command = { next: findNext, previous: findPrevious, "replace-one": replaceNext, "replace-all": replaceAll }[request.operation];
+    if (!command) throw new Error("Unknown source-search operation");
+    command(target);
+  }
+  const content = state.doc.toString();
+  const selection = { from: state.selection.main.from, to: state.selection.main.to };
+  const changes = edits;
+  const undone = request.operation === "replace-all" && undo(target);
+  return { content, selection, count, edits: changes, undone, undoContent: state.doc.toString() };
+}
+
+if (typeof globalThis.postMessage === "function") {
+  globalThis.onmessage = (event) => {
+    try {
+      globalThis.postMessage({ result: executeSourceSearchProof(event.data) });
+    } catch (error) {
+      globalThis.postMessage({ error: error instanceof Error ? error.message : String(error) });
+    }
+  };
+  globalThis.postMessage({ ready: true });
+}
diff --git a/frontend/scripts/run-browser-ci.mjs b/frontend/scripts/run-browser-ci.mjs
new file mode 100644
index 000000000..23fef320a
--- /dev/null
+++ b/frontend/scripts/run-browser-ci.mjs
@@ -0,0 +1,24 @@
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+for (const mode of ["production", "development"]) {
+  const result = spawnSync(
+    process.execPath,
+    [fileURLToPath(new URL("../node_modules/@playwright/test/cli.js", import.meta.url)), "test", ...process.argv.slice(2)],
+    {
+      cwd: fileURLToPath(new URL("../", import.meta.url)),
+      stdio: "inherit",
+      env: {
+        ...process.env,
+        SAMBEE_E2E_CI: "1",
+        SAMBEE_E2E_PRODUCTION: mode === "production" ? "1" : "0",
+        SAMBEE_E2E_DEVELOPMENT: mode === "development" ? "1" : "0",
+      },
+    }
+  );
+  if (result.error) console.error(`Could not start ${mode} browser contracts: ${result.error.message}`);
+  if (result.status !== 0) {
+    process.exitCode = result.status ?? 1;
+    break;
+  }
+}
diff --git a/frontend/scripts/run-tests-ci.mjs b/frontend/scripts/run-tests-ci.mjs
new file mode 100644
index 000000000..0c127a811
--- /dev/null
+++ b/frontend/scripts/run-tests-ci.mjs
@@ -0,0 +1,21 @@
+import { spawnSync } from "node:child_process";
+import { availableParallelism, totalmem } from "node:os";
+import { fileURLToPath } from "node:url";
+import { ciWorkerCount } from "./ci-test-policy.mjs";
+
+const cpus = availableParallelism();
+const memoryBytes = totalmem();
+console.log(
+  `CI resources: ${cpus} CPUs, ${(memoryBytes / 1024 ** 3).toFixed(1)} GiB RAM; Vitest workers=${ciWorkerCount(cpus, memoryBytes)}`
+);
+const result = spawnSync(
+  process.execPath,
+  [fileURLToPath(new URL("../node_modules/vitest/vitest.mjs", import.meta.url)), "run", ...process.argv.slice(2)],
+  {
+    cwd: fileURLToPath(new URL("../", import.meta.url)),
+    stdio: "inherit",
+    env: { ...process.env, SAMBEE_TEST_CI: "1" },
+  }
+);
+if (result.error) console.error(`Could not start CI unit tests: ${result.error.message}`);
+process.exitCode = result.status ?? 1;
diff --git a/frontend/scripts/source-search-containment-proof.mjs b/frontend/scripts/source-search-containment-proof.mjs
new file mode 100644
index 000000000..f80bbb4e0
--- /dev/null
+++ b/frontend/scripts/source-search-containment-proof.mjs
@@ -0,0 +1,491 @@
+import assert from "node:assert/strict";
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { isMainThread, parentPort, Worker } from "node:worker_threads";
+import { executeSourceSearchProof } from "./prototypes/sourceSearchContainment.worker.mjs";
+
+const OPERATION_TIMEOUT_MS = 2_000;
+const STALLED_OPERATION_TIMEOUT_MS = 200;
+const HEARTBEAT_MS = 10;
+const NATIVE_ATOMIC_MATCH_COUNT = 6_000;
+const NATIVE_ATOMIC_EXPANSION_UNITS = 128;
+const NATIVE_ATOMIC_MATCH = "abc 123";
+const NATIVE_TABLE_ROWS = 2_400;
+const NATIVE_TABLE_ROW = NATIVE_TABLE_ROWS / 2;
+const NATIVE_TABLE_PAYLOAD = "table edit";
+const NATIVE_TABLE_KEY_DELAY_MS = 10;
+const NATIVE_TABLE_TIMEOUT_MS = 15_000;
+const NATIVE_TABLE_VIEWPORT = { width: 1543, height: 900 };
+const NATIVE_TABLE_OUTER_NEWLINE_UNITS = 2;
+const NATIVE_TABLE_INPUT_PERCENTILE = 0.95;
+const OPERATIONS = ["count", "active-range", "visible-matches", "next", "previous", "replace-one", "replace-all"];
+
+if (!isMainThread) {
+  parentPort.on("message", (request) => {
+    try {
+      parentPort.postMessage({ result: executeSourceSearchProof(request) });
+    } catch (error) {
+      parentPort.postMessage({ error: error instanceof Error ? error.message : String(error) });
+    }
+  });
+  parentPort.postMessage({ ready: true });
+} else if (process.argv.includes("--native-table") || process.argv.includes("--native-atomic")) {
+  const { build } = await import("vite");
+  const { chromium, firefox } = await import("playwright");
+  const nativeTable = process.argv.includes("--native-table");
+  const profiling = nativeTable && process.env.SAMBEE_E2E_TRACE === "1";
+  const reportPrefix = nativeTable ? process.env.SAMBEE_NATIVE_TABLE_REPORT : undefined;
+  assert.ok(
+    !nativeTable || (process.env.SAMBEE_E2E_BUDGETS !== "1" && process.env.SAMBEE_E2E_MEMORY !== "1"),
+    "Native table diagnostics cannot enforce product budgets or combine with controlled GC"
+  );
+  assert.ok(!profiling || reportPrefix, "Native table profiling requires SAMBEE_NATIVE_TABLE_REPORT");
+  assert.ok(
+    !profiling || (process.env.MOZ_PROFILER_STARTUP === "1" && process.env.MOZ_PROFILER_SHUTDOWN),
+    "Native Firefox profiling requires startup profiler configuration and a shutdown profile path"
+  );
+  const entry = "native-atomic-reproduction.js";
+  const moduleSource = nativeTable
+    ? `
+    import { EditorState } from '@codemirror/state';
+    import { EditorView, keymap } from '@codemirror/view';
+    import { defaultKeymap, history, historyKeymap } from '@codemirror/commands';
+    import { markdown } from '@codemirror/lang-markdown';
+    import { forceParsing } from '@codemirror/language';
+    import { GFM } from '@lezer/markdown';
+    import { markdownTables } from 'codemirror-markdown-tables';
+    const rows = Array.from({ length: ${NATIVE_TABLE_ROWS} }, (_, index) => '| ' + (index + 1) + ' | row ' + (index + 1) + ' needle |');
+    const source = '| Key | Value |\\n| --- | --- |\\n' + rows.join('\\n') + '\\n';
+    let recording = false;
+    let previous;
+    let inputAt;
+    const inputs = [], gaps = [], transactions = [];
+    const root = new EditorView({
+      parent: document.body,
+      state: EditorState.create({ doc: source, extensions: [
+        history(), keymap.of([...defaultKeymap, ...historyKeymap]),
+        markdown({ extensions: [GFM] }),
+        markdownTables({ selectionType: 'codemirror', handlePosition: 'inside', lineWrapping: 'wrap',
+          extensions: [keymap.of(defaultKeymap)], globalKeyBindings: historyKeymap })
+      ] }),
+      dispatchTransactions(batch, view) {
+        if (!recording) { view.update(batch); return; }
+        const startedAt = performance.now();
+        for (const transaction of batch) void transaction.state;
+        const stateReadyAt = performance.now();
+        view.update(batch);
+        const updatedAt = performance.now();
+        for (const transaction of batch) if (transaction.docChanged) {
+          let removedUnits = 0, insertedUnits = 0, changeCount = 0;
+          transaction.changes.iterChanges((from, to, _fromB, _toB, text) => {
+            removedUnits += to - from; insertedUnits += text.length; changeCount += 1;
+          });
+          transactions.push({ stateApplyMs: stateReadyAt - startedAt, viewUpdateMs: updatedAt - stateReadyAt,
+            inputToRootMs: inputAt === undefined ? null : startedAt - inputAt,
+            beforeUnits: transaction.startState.doc.length, afterUnits: transaction.newDoc.length,
+            removedUnits, insertedUnits, changeCount });
+        }
+      }
+    });
+    if (!forceParsing(root, root.state.doc.length, ${NATIVE_TABLE_TIMEOUT_MS})) throw Error('Native table syntax did not finish parsing');
+    const beforeInput = event => {
+      if (!recording || !root.dom.contains(event.target)) return;
+      const start = performance.now();
+      inputAt = start;
+      previous ??= start;
+      requestAnimationFrame(() => requestAnimationFrame(() => inputs.push(performance.now() - start)));
+    };
+    document.addEventListener('beforeinput', beforeInput, true);
+    const timer = setInterval(() => {
+      if (!recording || previous === undefined) return;
+      const now = performance.now(); gaps.push(now - previous); previous = now;
+    }, 0);
+    window.nativeTable = {
+      start() { performance.mark('sambee:native-table:input-start'); recording = true; },
+      source() { return root.state.doc.toString(); },
+      async stop() {
+        await new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(resolve)));
+        performance.mark('sambee:native-table:input-end');
+        recording = false;
+        return { sourceUnits: source.length, inputs, gaps, transactions };
+      },
+      dispose() { recording = false; clearInterval(timer); document.removeEventListener('beforeinput', beforeInput, true); root.destroy(); }
+    };
+  `
+    : `
+    import { EditorState, Text } from '@codemirror/state';
+    window.nativeAtomic = (separator, expansion) => {
+      const match = ${JSON.stringify(NATIVE_ATOMIC_MATCH)};
+      const matchCount = ${NATIVE_ATOMIC_MATCH_COUNT};
+      const unit = match + ';' + separator;
+      const source = unit.repeat(matchCount);
+      const insert = expansion ? 'x'.repeat(${NATIVE_ATOMIC_EXPANSION_UNITS}) : 'replaced-123';
+      const state = EditorState.create({ doc: source });
+      const specs = Array.from({ length: matchCount }, (_, index) => ({ from: index * unit.length, to: index * unit.length + match.length, insert }));
+      const prepareAt = performance.now();
+      const changes = state.changes(specs);
+      const preparedMs = performance.now() - prepareAt;
+      const start = performance.now();
+      const result = changes.apply(state.doc);
+      const applyMs = performance.now() - start;
+      const assemblyAt = performance.now();
+      const parts = [];
+      let offset = 0;
+      changes.iterChanges((from, to, _fromB, _toB, text) => {
+        parts.push(state.doc.sliceString(offset, from), text.toString());
+        offset = to;
+      });
+      parts.push(state.doc.sliceString(offset));
+      const assembled = Text.of(parts.join('').split('\\n'));
+      const assemblyMs = performance.now() - assemblyAt;
+      const expected = (insert + ';' + separator).repeat(matchCount);
+      if (result.toString() !== expected || assembled.toString() !== expected || !assembled.eq(result)) throw Error('Native/assembled output mismatch');
+      if (changes.invert(state.doc).apply(result).toString() !== source) throw Error('Native inverse mismatch');
+      return { sourceUnits: source.length, outputUnits: result.length, changeCount: specs.length, preparedMs, applyMs, assemblyMs };
+    };
+  `;
+  const result = await build({
+    configFile: false,
+    root: fileURLToPath(new URL("..", import.meta.url)),
+    logLevel: "silent",
+    plugins: [
+      {
+        name: "native-atomic-reproduction",
+        resolveId: (id) => (id.endsWith(entry) ? resolve(fileURLToPath(new URL("..", import.meta.url)), entry) : undefined),
+        load: (id) => (id.endsWith(entry) ? moduleSource : undefined),
+      },
+    ],
+    build: { write: false, minify: !nativeTable, lib: { entry, name: "NativeAtomic", formats: ["iife"] } },
+  });
+  const output = (Array.isArray(result) ? result[0] : result).output.find((item) => item.type === "chunk");
+  assert.ok(output, "Native atomic reproduction must build a runnable chunk");
+  if (reportPrefix) await writeFile(`${reportPrefix}.bundle.js`, output.code);
+  for (const [engine, browserType] of Object.entries({ chromium, firefox })) {
+    const browser = await browserType.launch();
+    try {
+      const page = await browser.newPage(nativeTable ? { viewport: NATIVE_TABLE_VIEWPORT } : undefined);
+      const approvedUrl = "http://localhost:3000/browse/smb/demo";
+      await page.route(approvedUrl, (route) =>
+        route.fulfill({ contentType: "text/html", body: '<!doctype html><html lang="en"><title>Native atomic diagnostic</title></html>' })
+      );
+      await page.goto(approvedUrl);
+      await page.addScriptTag({ content: output.code });
+      if (nativeTable) {
+        page.setDefaultTimeout(NATIVE_TABLE_TIMEOUT_MS);
+        const errors = [];
+        let profileSession;
+        page.on("pageerror", (error) => errors.push(error.message));
+        try {
+          const cell = page.locator(".tbl-data-cell .tbl-cell-view").nth((NATIVE_TABLE_ROW - 1) * 2);
+          await cell.click();
+          const nested = page.locator(".tbl-cell-editor .cm-content");
+          await nested.waitFor({ state: "visible" });
+          await nested.focus();
+          await page.keyboard.press("End");
+          if (profiling && engine === "chromium") {
+            profileSession = await page.context().newCDPSession(page);
+            await profileSession.send("Profiler.enable");
+            await profileSession.send("Profiler.start");
+          }
+          await page.evaluate(() => window.nativeTable.start());
+          await page.keyboard.press("Shift+Enter");
+          await page.keyboard.type(NATIVE_TABLE_PAYLOAD, { delay: NATIVE_TABLE_KEY_DELAY_MS });
+          const sample = await page.evaluate(() => window.nativeTable.stop());
+          if (profileSession) {
+            const { profile } = await profileSession.send("Profiler.stop");
+            await writeFile(`${reportPrefix}.${engine}.profile.json`, JSON.stringify(profile));
+            await profileSession.detach();
+            profileSession = undefined;
+          }
+          const saved = await page.evaluate(() => window.nativeTable.source());
+          const keyWidth = String(NATIVE_TABLE_ROW).length + "<br>".length + NATIVE_TABLE_PAYLOAD.length;
+          const valueWidth = `row ${NATIVE_TABLE_ROWS} needle`.length;
+          const expectedRows = Array.from({ length: NATIVE_TABLE_ROWS }, (_, index) => {
+            const key = `${index + 1}${index + 1 === NATIVE_TABLE_ROW ? `<br>${NATIVE_TABLE_PAYLOAD}` : ""}`;
+            return `| ${key.padEnd(keyWidth)} | ${`row ${index + 1} needle`.padEnd(valueWidth)} |`;
+          });
+          const expected = `\n| ${"Key".padEnd(keyWidth)} | ${"Value".padEnd(valueWidth)} |\n| ${"-".repeat(keyWidth)} | ${"-".repeat(valueWidth)} |\n${expectedRows.join("\n")}\n`;
+          assert.equal(saved, expected, "Native table must publish the exact formatted document");
+          assert.ok(sample.inputs.length >= NATIVE_TABLE_PAYLOAD.length, "Every typed character must produce an input sample");
+          assert.ok(
+            sample.inputs.every(Number.isFinite) && sample.gaps.length > 0 && sample.gaps.every(Number.isFinite),
+            "Native timing samples must be present and finite"
+          );
+          assert.ok(sample.transactions.length > 0, "Native typing must publish root transactions");
+          for (const transaction of sample.transactions) {
+            assert.equal(transaction.changeCount, 1, "Native table edits must remain atomic");
+            assert.equal(
+              transaction.removedUnits,
+              transaction.beforeUnits - NATIVE_TABLE_OUTER_NEWLINE_UNITS,
+              "Native cell edits replace the full source table"
+            );
+            assert.equal(
+              transaction.insertedUnits,
+              transaction.afterUnits - NATIVE_TABLE_OUTER_NEWLINE_UNITS,
+              "Native replacement must contain the complete updated table"
+            );
+          }
+          await page.keyboard.press("Control+z");
+          assert.notEqual(await page.evaluate(() => window.nativeTable.source()), expected, "Native undo must change the document");
+          await page.keyboard.press("Control+Shift+Z");
+          await page.waitForFunction((expected) => window.nativeTable.source() === expected, expected);
+          const sortedInputs = [...sample.inputs].sort((left, right) => left - right);
+          const evidence = {
+            engine,
+            browserVersion: browser.version(),
+            viewport: NATIVE_TABLE_VIEWPORT,
+            rows: NATIVE_TABLE_ROWS,
+            row: NATIVE_TABLE_ROW,
+            diagnostic: true,
+            profiling,
+            payload: NATIVE_TABLE_PAYLOAD,
+            keyboardTwoFrameP95: sortedInputs[Math.ceil(sortedInputs.length * NATIVE_TABLE_INPUT_PERCENTILE) - 1],
+            maximumTimerGap: Math.max(...sample.gaps),
+            outputUnits: saved.length,
+            ...sample,
+            scope:
+              "Diagnostic unminified public CodeMirror/markdownTables only, after activation; no React, application callbacks, normalization, Save or workers. Explicit transaction.state materialization separates state application from view.update; elapsed stages are not pure CPU or product timing acceptance. Exact native output and undo/redo required.",
+          };
+          if (reportPrefix) await writeFile(`${reportPrefix}.${engine}.json`, JSON.stringify(evidence));
+          console.log(JSON.stringify(evidence));
+          assert.deepEqual(errors, [], "Native table diagnostic must have no page errors");
+        } finally {
+          if (profileSession) await profileSession.detach();
+          await page.evaluate(() => window.nativeTable.dispose());
+        }
+        assert.equal(await page.locator(".cm-editor").count(), 0, "Native editor must dispose");
+        continue;
+      }
+      for (const separator of ["\n", " "])
+        for (const expansion of [false, true]) {
+          const sample = await page.evaluate(({ separator, expansion }) => window.nativeAtomic(separator, expansion), {
+            separator,
+            expansion,
+          });
+          console.log(
+            JSON.stringify({
+              engine,
+              browserVersion: browser.version(),
+              fixture: separator === "\n" ? "dense" : "long-line",
+              operation: expansion ? "dense-expansion" : "original",
+              scope:
+                "Diagnostic native ChangeSet application and isolated span-assembly candidate; no production patch, EditorView, React, worker or DOM. Not timing acceptance or a mapping/history implementation.",
+              ...sample,
+            })
+          );
+        }
+    } finally {
+      await browser.close();
+    }
+  }
+} else {
+  async function run(request, timeout = OPERATION_TIMEOUT_MS) {
+    const worker = new Worker(new URL(import.meta.url));
+    let heartbeats = 0;
+    let ready = false;
+    let settled = false;
+    let timer;
+    const heartbeat = setInterval(() => (heartbeats += 1), HEARTBEAT_MS);
+    try {
+      return await new Promise((resolve, reject) => {
+        const deadline = () => {
+          clearTimeout(timer);
+          timer = setTimeout(
+            () => {
+              settled = true;
+              reject(Object.assign(new Error("Source-search proof deadline exceeded"), { code: "PROOF_TIMEOUT", ready, heartbeats }));
+            },
+            ready ? timeout : OPERATION_TIMEOUT_MS
+          );
+        };
+        worker.on("error", reject);
+        worker.on("exit", (code) => {
+          if (!settled) reject(new Error(`Source-search worker exited before a result (${code})`));
+        });
+        worker.on("message", (message) => {
+          if (settled) return;
+          if (message.ready) {
+            ready = true;
+            heartbeats = 0;
+            deadline();
+            worker.postMessage(request);
+          } else {
+            settled = true;
+            if (message.error) reject(new Error(message.error));
+            else resolve(message.result);
+          }
+        });
+        deadline();
+      });
+    } finally {
+      settled = true;
+      clearTimeout(timer);
+      clearInterval(heartbeat);
+      await worker.terminate();
+    }
+  }
+
+  const normal = { source: "one=1 two=2", query: "(one|two)=(\\d)", replace: "$2:$1" };
+  const expected = new Map();
+  for (const operation of OPERATIONS) {
+    const result = await run({ ...normal, operation, selection: operation === "replace-one" ? { anchor: 0, head: 5 } : undefined });
+    expected.set(operation, result);
+    if (["count", "active-range", "visible-matches"].includes(operation)) assert.equal(result.count, 2);
+    if (operation === "next") assert.deepEqual(result.selection, { from: 0, to: 5 });
+    if (operation === "previous") assert.deepEqual(result.selection, { from: 6, to: 11 });
+    if (operation === "replace-one") assert.equal(result.content, "1:one two=2");
+    if (operation === "replace-all") {
+      assert.equal(result.content, "1:one 2:two");
+      assert.equal(result.edits, 1);
+      assert.equal(result.undone, true);
+      assert.equal(result.undoContent, normal.source);
+    }
+    await assert.rejects(
+      run({ operation, source: `${"a".repeat(128)}!`, query: "(a+)+$", replace: "replacement" }, STALLED_OPERATION_TIMEOUT_MS),
+      (error) => error.code === "PROOF_TIMEOUT" && error.ready && error.heartbeats > 0
+    );
+    const retry = await run({ ...normal, operation: "count" });
+    assert.equal(retry.count, 2);
+    console.log(`${operation}: native matching/command passed; stalled worker terminated; host serviced timers; fresh-worker retry passed`);
+  }
+  await assert.rejects(run({ ...normal, operation: "count", query: "(" }), /Invalid source-search expression/);
+  const zeroWidth = await run({ operation: "replace-all", source: "aa", query: "(?=a)", replace: "x" });
+  assert.equal(zeroWidth.content, "xaxa");
+  assert.equal(zeroWidth.undoContent, "aa");
+  console.log(
+    "P1 Node-worker feasibility proof passed. Not browser/editor integration, replacement-transfer bounds, or product timeout acceptance."
+  );
+
+  if (process.env.SAMBEE_SOURCE_SEARCH_PROOF_BROWSER) {
+    const { chromium, firefox } = await import("playwright");
+    const { build } = await import("vite");
+    const browsers = { chromium, firefox };
+    const names = process.env.SAMBEE_SOURCE_SEARCH_PROOF_BROWSER.split(",");
+    assert.ok(
+      names.every((name) => Object.keys(browsers).includes(name)),
+      "Unsupported proof browser"
+    );
+    const output = await mkdtemp(resolve(tmpdir(), "sambee-source-search-proof-"));
+    const approvedUrl = "http://localhost:3000/browse/smb/demo";
+    const workerUrl = "/__source_search_proof__/worker.js";
+    const browserDeadlineMs = 500;
+    try {
+      await build({
+        configFile: false,
+        root: fileURLToPath(new URL("..", import.meta.url)),
+        logLevel: "warn",
+        build: {
+          outDir: output,
+          emptyOutDir: true,
+          minify: true,
+          rollupOptions: {
+            input: fileURLToPath(new URL("./prototypes/sourceSearchContainment.worker.mjs", import.meta.url)),
+            output: { entryFileNames: "worker.js", codeSplitting: false },
+          },
+        },
+      });
+      const workerBody = await readFile(resolve(output, "worker.js"));
+      for (const name of names) {
+        const browser = await browsers[name].launch({ headless: true });
+        try {
+          for (const width of [1543, 390]) {
+            const page = await browser.newPage({ viewport: { width, height: 900 } });
+            const errors = [];
+            page.on("pageerror", (error) => errors.push(error.message));
+            await page.route(`**${workerUrl}`, (route) => route.fulfill({ body: workerBody, contentType: "text/javascript" }));
+            await page.route(approvedUrl, (route) =>
+              route.fulfill({
+                contentType: "text/html",
+                body: '<!doctype html><html lang="en"><title>P1 source-search proof</title><input aria-label="Input probe" id="input"></html>',
+              })
+            );
+            await page.goto(approvedUrl);
+            const runBrowser = async (request, { stall = false, cancel = false } = {}) => {
+              await page.evaluate(
+                async ({ request, workerUrl, timeout, startupTimeout }) => {
+                  window.sourceSearchProofResult = null;
+                  await new Promise((resolveStarted, rejectStarted) => {
+                    const worker = new Worker(workerUrl, { type: "module" });
+                    let ready = false;
+                    let settled = false;
+                    const finish = (result) => {
+                      if (settled) return;
+                      settled = true;
+                      clearTimeout(timer);
+                      worker.terminate();
+                      window.sourceSearchProofResult = result;
+                      window.cancelSourceSearchProof = null;
+                      if (!ready) rejectStarted(new Error("Source-search browser worker failed to start"));
+                    };
+                    let timer = setTimeout(() => finish({ startupTimeout: true }), startupTimeout);
+                    window.cancelSourceSearchProof = () => finish({ cancelled: true });
+                    worker.onerror = (event) => {
+                      event.preventDefault();
+                      finish({ error: event.message });
+                    };
+                    worker.addEventListener("messageerror", () => finish({ error: "Worker response decode failed" }));
+                    worker.onmessage = (event) => {
+                      if (settled) return;
+                      if (event.data.ready) {
+                        ready = true;
+                        clearTimeout(timer);
+                        timer = setTimeout(() => finish({ timedOut: true }), timeout);
+                        worker.postMessage(request);
+                        resolveStarted();
+                      } else finish(event.data);
+                    };
+                  });
+                },
+                {
+                  request,
+                  workerUrl,
+                  timeout: stall || cancel ? browserDeadlineMs : OPERATION_TIMEOUT_MS,
+                  startupTimeout: OPERATION_TIMEOUT_MS,
+                }
+              );
+              if (stall || cancel) {
+                const input = page.locator("#input");
+                const before = await input.inputValue();
+                await input.press("x");
+                const serviced = await page.evaluate(() => ({
+                  text: document.querySelector("#input").value,
+                  pending: window.sourceSearchProofResult === null,
+                }));
+                assert.equal(serviced.text, `${before}x`);
+                assert.equal(serviced.pending, true, "Keyboard input must be serviced before worker timeout/cancellation");
+                if (cancel) await page.evaluate(() => window.cancelSourceSearchProof());
+              }
+              await page.waitForFunction(() => window.sourceSearchProofResult !== null);
+              return page.evaluate(() => window.sourceSearchProofResult);
+            };
+            for (const operation of OPERATIONS) {
+              const request = { ...normal, operation, selection: operation === "replace-one" ? { anchor: 0, head: 5 } : undefined };
+              const baseline = await runBrowser(request);
+              assert.deepEqual(baseline.result, expected.get(operation));
+              const pathological = { operation, source: `${"a".repeat(128)}!`, query: "(a+)+$", replace: "replacement" };
+              assert.deepEqual(await runBrowser(pathological, { stall: true }), { timedOut: true });
+              const retry = await runBrowser(request);
+              assert.deepEqual(retry.result, expected.get(operation));
+              assert.deepEqual(await runBrowser(pathological, { cancel: true }), { cancelled: true });
+            }
+            const invalid = await runBrowser({ ...normal, operation: "count", query: "(" });
+            assert.match(invalid.error, /Invalid source-search expression/);
+            const zeroWidthResult = await runBrowser({ operation: "replace-all", source: "aa", query: "(?=a)", replace: "x" });
+            assert.deepEqual(zeroWidthResult.result, zeroWidth);
+            assert.deepEqual(errors, []);
+            console.log(
+              `${name} ${browser.version()} width=${width}: all seven native/proxy paths, keyboard-during-stall, timeout, cancellation, restart, capture expansion and undo checks passed`
+            );
+            await page.close();
+          }
+        } finally {
+          await browser.close();
+        }
+      }
+    } finally {
+      await rm(output, { recursive: true, force: true });
+    }
+  }
+}
diff --git a/frontend/src/__tests__/App.test.tsx b/frontend/src/__tests__/App.test.tsx
index 5e2500c0f..b180d9698 100644
--- a/frontend/src/__tests__/App.test.tsx
+++ b/frontend/src/__tests__/App.test.tsx
@@ -90,7 +90,7 @@ vi.mock("../pages/FileBrowser", () => ({
           onKeyDown={(event) => {
             if (event.key !== "ArrowDown") return;
             void navigate({ search: "?settings=account" }, { flushSync: true });
-            event.currentTarget.dataset.committedSearch = screen.getByTestId("mock-file-browser-location").textContent ?? "";
+            event.currentTarget.dataset["committedSearch"] = screen.getByTestId("mock-file-browser-location").textContent ?? "";
           }}
         >
           Next settings category
diff --git a/frontend/src/__tests__/browserBootstrap.test.ts b/frontend/src/__tests__/browserBootstrap.test.ts
new file mode 100644
index 000000000..db6cd3bf3
--- /dev/null
+++ b/frontend/src/__tests__/browserBootstrap.test.ts
@@ -0,0 +1,37 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const { loadApp } = vi.hoisted(() => ({ loadApp: vi.fn() }));
+vi.mock("../index", () => {
+  loadApp();
+  return {};
+});
+
+describe("browser capability gate", () => {
+  beforeEach(() => {
+    vi.resetModules();
+    loadApp.mockClear();
+    vi.stubGlobal("Iterator", { from: vi.fn() });
+    document.body.innerHTML = '<div id="root"><p id="browser-compatibility-reason"></p></div>';
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    document.body.replaceChildren();
+  });
+
+  it.each([undefined, null, {}])("blocks app loading when Worker is %s", async (worker) => {
+    vi.stubGlobal("Worker", worker);
+    await import("../browserBootstrap");
+    expect(document.getElementById("root")).toHaveClass("browser-compatibility-unsupported");
+    expect(document.getElementById("browser-compatibility-reason")).toHaveTextContent("Missing browser capabilities: Web Workers.");
+    expect(loadApp).not.toHaveBeenCalled();
+  });
+
+  it("loads the app when the Worker API and other required capabilities are present", async () => {
+    vi.stubGlobal("Worker", vi.fn());
+    await import("../browserBootstrap");
+    await vi.waitFor(() => expect(loadApp).toHaveBeenCalledOnce());
+    expect(document.getElementById("root")).not.toHaveClass("browser-compatibility-unsupported");
+    expect(document.getElementById("root")).toBeEmptyDOMElement();
+  });
+});
diff --git a/frontend/src/__tests__/integration/browse-view-flow.test.tsx b/frontend/src/__tests__/integration/browse-view-flow.test.tsx
index c4bd79e86..d858705a2 100644
--- a/frontend/src/__tests__/integration/browse-view-flow.test.tsx
+++ b/frontend/src/__tests__/integration/browse-view-flow.test.tsx
@@ -1,3 +1,4 @@
+import { createMockAuthToken } from "../../test/fixtures/users";
 /**
  * Browse → View Flow Integration Tests (Phase 3)
  *
@@ -94,7 +95,7 @@ describe("Browse → View Flow", () => {
   beforeEach(() => {
     // Clear any previous state
     localStorage.clear();
-    authSession.setAuthenticated({ access_token: "mock-token", token_type: "bearer" }, false);
+    authSession.setAuthenticated(createMockAuthToken({ access_token: "mock-token", token_type: "bearer" }), false);
   });
 
   const renderMarkdownViewer = (props: { connectionId: string; path: string; onClose: () => void }) => {
diff --git a/frontend/src/__tests__/scripts/ci-test-policy.test.ts b/frontend/src/__tests__/scripts/ci-test-policy.test.ts
new file mode 100644
index 000000000..fdf4d77ae
--- /dev/null
+++ b/frontend/src/__tests__/scripts/ci-test-policy.test.ts
@@ -0,0 +1,112 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { API } from "typescript/unstable/sync";
+import { describe, expect, it } from "vitest";
+import { ciWorkerCount, expectedBrowserCases, validateBrowserCases } from "../../../scripts/ci-test-policy.mjs";
+
+describe("CI resource and browser policy", () => {
+  it.each([
+    [4, 16, 4],
+    [2, 8, 2],
+    [12, 31, 4],
+    [8, 6, 2],
+    [1, 1, 1],
+  ])("caps %s CPUs and %s GiB at %s workers", (cpus, gib, expected) => {
+    expect(ciWorkerCount(cpus, gib * 1024 ** 3)).toBe(expected);
+  });
+
+  it.each([
+    [0, 8],
+    [2, 0],
+    [NaN, 8],
+    [2, Infinity],
+  ])("rejects invalid resources", (cpus, memory) => {
+    expect(() => ciWorkerCount(cpus, memory)).toThrow("positive CPU and memory");
+  });
+
+  for (const mode of ["production", "development"] as const) {
+    const passing = () =>
+      expectedBrowserCases(mode).map((identity) => {
+        const [engine, title] = identity.split(": ");
+        return { engine, title, status: "passed", attempts: 1 };
+      });
+    it(`requires the complete ${mode} engine/width matrix`, () => {
+      expect(passing()).toHaveLength(mode === "production" ? 16 : 2);
+      expect(validateBrowserCases(mode, passing())).toEqual([]);
+      expect(validateBrowserCases(mode, passing().slice(1))).not.toEqual([]);
+      expect(validateBrowserCases(mode, [...passing(), passing()[0]!])).not.toEqual([]);
+    });
+    it.each(["skipped", "failed", "timedOut", "interrupted"])(`rejects ${mode} %s results`, (status) => {
+      const cases = passing();
+      cases[0]!.status = status;
+      expect(validateBrowserCases(mode, cases)).not.toEqual([]);
+    });
+    it(`rejects ${mode} retry-only success`, () => {
+      const cases = passing();
+      cases[0]!.attempts = 2;
+      expect(validateBrowserCases(mode, cases)).not.toEqual([]);
+    });
+  }
+  it("rejects unknown modes", () => expect(() => expectedBrowserCases("diagnostic")).toThrow("Unknown"));
+});
+
+describe("required frontend type correctness", () => {
+  const root = process.cwd();
+  const projectNames = ["tsconfig.app.json", "tsconfig.test.json", "tsconfig.node.json"];
+
+  it("requires the real solution check before producing normal build assets", () => {
+    const manifest = JSON.parse(readFileSync(resolve(root, "package.json"), "utf8"));
+    expect(manifest.scripts.typecheck).toBe("tsc -b --noEmit");
+    expect(manifest.scripts.build).toMatch(/^npm run typecheck && /);
+    const solution = JSON.parse(readFileSync(resolve(root, "tsconfig.json"), "utf8"));
+    expect(solution.references).toEqual(projectNames.map((path) => ({ path: `./${path}` })));
+  });
+
+  it("uses the real check in the local test runner and VS Code task", () => {
+    const runner = readFileSync(resolve(root, "../scripts/test"), "utf8");
+    expect(runner).toContain('run_check "TypeScript type check passed" "TypeScript type check failed" npm run typecheck');
+    const tasks = JSON.parse(readFileSync(resolve(root, "../.vscode/tasks.json"), "utf8"));
+    expect(tasks.tasks).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          label: "Frontend: Type Check + Lint",
+          command: expect.stringMatching(/^npm run typecheck 2>&1 && /),
+        }),
+      ])
+    );
+  });
+
+  it("preserves strict options and checks every application, test, helper, and declaration file", () => {
+    const compiler = new API();
+    try {
+      const projects = projectNames.map((name) => compiler.parseConfigFile(resolve(root, name)));
+      const strictOptions = [
+        "strict",
+        "noUnusedLocals",
+        "noUnusedParameters",
+        "noUncheckedIndexedAccess",
+        "noPropertyAccessFromIndexSignature",
+        "noFallthroughCasesInSwitch",
+      ];
+      for (const project of projects) {
+        for (const option of strictOptions) expect(project.options[option], option).toBe(true);
+        expect(project.options["noCheck"]).not.toBe(true);
+      }
+      const checkedFiles = new Set(projects.flatMap((project) => project.fileNames));
+      const sourceFiles = readdirSync(resolve(root, "src"), { recursive: true, withFileTypes: true })
+        .filter((entry) => entry.isFile() && /\.tsx?$/.test(entry.name))
+        .map((entry) => resolve(entry.parentPath, entry.name));
+      expect(sourceFiles.length).toBeGreaterThan(0);
+      expect(sourceFiles.filter((file) => !checkedFiles.has(file))).toEqual([]);
+      expect(checkedFiles.has(resolve(root, "vite.config.ts"))).toBe(true);
+      expect(checkedFiles.has(resolve(root, "vitest.config.ts"))).toBe(true);
+      expect(projects.map((project) => project.options["types"])).toEqual([
+        ["vite/client"],
+        ["vite/client", "vitest/globals", "@testing-library/jest-dom/vitest", "node"],
+        ["node"],
+      ]);
+    } finally {
+      compiler.close();
+    }
+  });
+});
diff --git a/frontend/src/browserBootstrap.ts b/frontend/src/browserBootstrap.ts
index d6d8925bf..dac10e750 100644
--- a/frontend/src/browserBootstrap.ts
+++ b/frontend/src/browserBootstrap.ts
@@ -9,6 +9,9 @@ if (!("withResolvers" in Promise) || typeof Promise.withResolvers !== "function"
 if (!("toReversed" in Array.prototype) || typeof Array.prototype.toReversed !== "function") {
   missingFeatures.push("Array.prototype.toReversed");
 }
+if (typeof globalThis.Worker !== "function") {
+  missingFeatures.push("Web Workers");
+}
 
 const simulateUnsupportedBrowser = import.meta.env.DEV && new URLSearchParams(window.location.search).has("simulateUnsupportedBrowser");
 if (simulateUnsupportedBrowser) {
diff --git a/frontend/src/components/Admin/__tests__/ConnectionDialog.test.tsx b/frontend/src/components/Admin/__tests__/ConnectionDialog.test.tsx
index a699a007d..e46d20d5a 100644
--- a/frontend/src/components/Admin/__tests__/ConnectionDialog.test.tsx
+++ b/frontend/src/components/Admin/__tests__/ConnectionDialog.test.tsx
@@ -1,6 +1,8 @@
 import { render, screen, waitFor } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 import { beforeEach, describe, expect, it, vi } from "vitest";
+import { createMockConnection } from "../../../test/fixtures/connections";
+import { uninitializedTestCallback } from "../../../test/helpers/assertions";
 import type { Connection } from "../../../types";
 import ConnectionDialog from "../ConnectionDialog";
 
@@ -36,7 +38,7 @@ const mockVisibilityOptions = [
   },
 ];
 
-const mockConnection: Connection = {
+const mockConnection: Connection = createMockConnection({
   id: "1",
   name: "Test Server",
   type: "smb",
@@ -50,7 +52,7 @@ const mockConnection: Connection = {
   can_manage: true,
   created_at: "2024-01-01T00:00:00",
   updated_at: "2024-01-01T00:00:00",
-};
+});
 
 function mockViewportWidth(width: number) {
   const originalMatchMedia = window.matchMedia;
@@ -445,7 +447,7 @@ describe("ConnectionDialog Component", () => {
   });
 
   it("keeps the save label visible while the save request is pending", async () => {
-    let resolveCreate: ((value: Connection) => void) | null = null;
+    let resolveCreate: (value: Connection) => void = uninitializedTestCallback;
     vi.mocked(api.createConnection).mockReturnValue(
       new Promise((resolve) => {
         resolveCreate = resolve;
diff --git a/frontend/src/components/Editor/SourceTextEditor.tsx b/frontend/src/components/Editor/SourceTextEditor.tsx
index 7e476293e..e375b7a51 100644
--- a/frontend/src/components/Editor/SourceTextEditor.tsx
+++ b/frontend/src/components/Editor/SourceTextEditor.tsx
@@ -1,11 +1,17 @@
 import { Annotation, Compartment, EditorSelection, EditorState, type TransactionSpec } from "@codemirror/state";
 import { type Command, EditorView, type ViewUpdate } from "@codemirror/view";
-import { forwardRef, useEffect, useImperativeHandle, useRef } from "react";
+import { useTheme } from "@mui/material";
+import { forwardRef, useEffect, useImperativeHandle, useLayoutEffect, useRef } from "react";
+import { getSyntaxVariables } from "../../theme/syntaxStyles";
 import { CODEMIRROR_EDITOR_HORIZONTAL_INSET_CSS_VARIABLE } from "../../theme/viewerStyles";
 import { getCodeMirrorHorizontalInset } from "./getCodeMirrorHorizontalInset";
 import type { SourceTextEditorHandle, SourceTextEditorProps } from "./sourceTextEditorTypes";
 
 const EXTERNAL_SYNC_ANNOTATION = Annotation.define<boolean>();
+export const SOURCE_EDITOR_MEASURES = {
+  serialize: "sambee:source-editor:serialize",
+  publish: "sambee:source-editor:publish",
+} as const;
 
 const sourceTextEditorBaseTheme = EditorView.theme({
   "&": {
@@ -82,13 +88,16 @@ export const SourceTextEditor = forwardRef<SourceTextEditorHandle, SourceTextEdi
     },
     ref
   ) => {
+    const muiTheme = useTheme();
     const containerRef = useRef<HTMLDivElement | null>(null);
     const viewRef = useRef<EditorView | null>(null);
+    const revisionRef = useRef(0);
     const preservedSelectionRef = useRef<PreservedSelectionSnapshot | null>(null);
     const readOnlyCompartmentRef = useRef(new Compartment());
     const extensionsCompartmentRef = useRef(new Compartment());
     const contentAttributesCompartmentRef = useRef(new Compartment());
     const initialValueRef = useRef(value);
+    const publishedValueRef = useRef(value);
     const initialExtensionsRef = useRef(extensions);
     const appliedExtensionsRef = useRef(extensions);
     const initialReadOnlyRef = useRef(readOnly);
@@ -113,6 +122,7 @@ export const SourceTextEditor = forwardRef<SourceTextEditorHandle, SourceTextEdi
       }
 
       const updateListener = EditorView.updateListener.of((viewUpdate: ViewUpdate) => {
+        if (viewUpdate.docChanged) revisionRef.current += 1;
         onUpdateRef.current?.(viewUpdate, viewUpdate.view);
 
         if (!viewUpdate.docChanged) {
@@ -126,7 +136,16 @@ export const SourceTextEditor = forwardRef<SourceTextEditorHandle, SourceTextEdi
         }
 
         onUserEditRef.current?.(viewUpdate);
-        onChangeRef.current(viewUpdate.state.doc.toString(), viewUpdate);
+        const serializationStart = performance.now();
+        const nextValue = viewUpdate.state.doc.toString();
+        const detail = { revision: revisionRef.current, documentUnits: nextValue.length };
+        performance.clearMeasures(SOURCE_EDITOR_MEASURES.serialize);
+        performance.measure(SOURCE_EDITOR_MEASURES.serialize, { start: serializationStart, detail });
+        publishedValueRef.current = nextValue;
+        const publicationStart = performance.now();
+        onChangeRef.current(nextValue, viewUpdate);
+        performance.clearMeasures(SOURCE_EDITOR_MEASURES.publish);
+        performance.measure(SOURCE_EDITOR_MEASURES.publish, { start: publicationStart, detail });
       });
 
       const initialState = EditorState.create({
@@ -198,23 +217,21 @@ export const SourceTextEditor = forwardRef<SourceTextEditorHandle, SourceTextEdi
       appliedExtensionsRef.current = extensions;
       view.dispatch({
         effects: extensionsCompartmentRef.current.reconfigure(extensions),
-        scrollIntoView: true,
       });
     }, [extensions]);
 
-    useEffect(() => {
+    useLayoutEffect(() => {
       const view = viewRef.current;
 
       if (!view) {
         return;
       }
 
-      const currentValue = view.state.doc.toString();
-
-      if (currentValue === value) {
+      if (publishedValueRef.current === value) {
         return;
       }
 
+      publishedValueRef.current = value;
       const currentSelection = view.state.selection.main;
       const nextAnchor = Math.min(currentSelection.anchor, value.length);
       const nextHead = Math.min(currentSelection.head, value.length);
@@ -232,6 +249,23 @@ export const SourceTextEditor = forwardRef<SourceTextEditorHandle, SourceTextEdi
         focus: () => {
           viewRef.current?.focus();
         },
+        captureSnapshot: () => {
+          const view = viewRef.current;
+          if (!view) throw new Error("Cannot capture a snapshot after the source editor is disposed");
+          if (
+            view.compositionStarted ||
+            Array.from(view.dom.querySelectorAll<HTMLElement>(".cm-editor")).some(
+              (element) => EditorView.findFromDOM(element)?.compositionStarted
+            )
+          ) {
+            throw new DOMException(
+              "Finish the current input method composition before saving or creating a recovery snapshot.",
+              "InvalidStateError"
+            );
+          }
+          const doc = view.state.doc;
+          return Object.freeze({ revision: revisionRef.current, serialize: () => doc.toString() });
+        },
         getValue: () => viewRef.current?.state.doc.toString() ?? value,
         getPrimarySelectionText: () => {
           const view = viewRef.current;
@@ -272,14 +306,19 @@ export const SourceTextEditor = forwardRef<SourceTextEditorHandle, SourceTextEdi
           }
 
           const clampedSnapshot = clampSelectionSnapshot(snapshot, view.state.doc.length);
-
-          view.dispatch({
-            selection: EditorSelection.fromJSON(clampedSnapshot.selection),
-            scrollIntoView: false,
-          });
-          view.focus();
-          view.scrollDOM.scrollTop = clampedSnapshot.scrollTop;
-          view.scrollDOM.scrollLeft = clampedSnapshot.scrollLeft;
+          const startedAt = performance.now();
+          try {
+            view.dispatch({
+              selection: EditorSelection.fromJSON(clampedSnapshot.selection),
+              scrollIntoView: false,
+            });
+            view.focus();
+            view.scrollDOM.scrollTop = clampedSnapshot.scrollTop;
+            view.scrollDOM.scrollLeft = clampedSnapshot.scrollLeft;
+          } finally {
+            performance.clearMeasures("sambee:source-editor:restore-selection");
+            performance.measure("sambee:source-editor:restore-selection", { start: startedAt });
+          }
 
           return view.hasFocus;
         },
@@ -305,7 +344,7 @@ export const SourceTextEditor = forwardRef<SourceTextEditorHandle, SourceTextEdi
       [value]
     );
 
-    return <div ref={containerRef} className={className} />;
+    return <div ref={containerRef} className={className} style={getSyntaxVariables(muiTheme)} />;
   }
 );
 
diff --git a/frontend/src/components/Editor/__tests__/SourceTextEditor.test.tsx b/frontend/src/components/Editor/__tests__/SourceTextEditor.test.tsx
index e8623ddce..4b10e9d9b 100644
--- a/frontend/src/components/Editor/__tests__/SourceTextEditor.test.tsx
+++ b/frontend/src/components/Editor/__tests__/SourceTextEditor.test.tsx
@@ -6,7 +6,7 @@ import { EditorSelection, EditorState } from "@codemirror/state";
 import { EditorView } from "@codemirror/view";
 import { render, screen, waitFor } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
-import { createRef, useState } from "react";
+import { createRef, useLayoutEffect, useState } from "react";
 import { describe, expect, it, vi } from "vitest";
 import { buildCommonEditorExtensions } from "../buildCommonEditorExtensions";
 import { getSelectionLineSegments, resolveOpaqueSelectionBackground } from "../buildEditorSelectionLayer";
@@ -18,10 +18,12 @@ import {
 import { buildMarkdownEditorExtensions } from "../buildMarkdownEditorExtensions";
 import type { MarkdownEditorThemeOptions } from "../buildMarkdownEditorTheme";
 import { buildTextEditorTheme, type TextEditorThemeOptions } from "../buildTextEditorTheme";
-import { SourceTextEditor } from "../SourceTextEditor";
+import { SOURCE_EDITOR_MEASURES, SourceTextEditor } from "../SourceTextEditor";
 import type { SourceTextEditorHandle } from "../sourceTextEditorTypes";
 
 const TEST_MARKDOWN_THEME: MarkdownEditorThemeOptions = {
+  currentSearchMatchBackground: "rgba(244, 196, 48, 0.32)",
+  otherSearchMatchBackground: "rgba(244, 196, 48, 0.18)",
   activeLineBackground: "rgba(244, 196, 48, 0.18)",
   borderColor: "rgba(31, 38, 43, 0.16)",
   isDarkMode: false,
@@ -49,6 +51,137 @@ const TEST_TEXT_THEME: TextEditorThemeOptions = {
 };
 
 describe("SourceTextEditor", () => {
+  it("measures serialization and synchronous parent publication without retaining source or repeating controlled echoes", () => {
+    const editorRef = createRef<SourceTextEditorHandle>();
+    const onChange = vi.fn();
+    const measure = vi.spyOn(performance, "measure");
+    const clearMeasures = vi.spyOn(performance, "clearMeasures");
+    try {
+      const { rerender } = render(<SourceTextEditor ref={editorRef} value="initial" ariaLabel="Measured editor" onChange={onChange} />);
+      const view = editorRef.current?.getView();
+      if (!view) throw new Error("Expected a mounted editor");
+      view.dispatch({ changes: { from: view.state.doc.length, insert: " updated" } });
+      for (const name of Object.values(SOURCE_EDITOR_MEASURES)) {
+        expect(clearMeasures).toHaveBeenCalledWith(name);
+        expect(measure).toHaveBeenCalledWith(name, {
+          start: expect.any(Number),
+          detail: { revision: 1, documentUnits: "initial updated".length },
+        });
+      }
+      expect(onChange).toHaveBeenCalledOnce();
+      measure.mockClear();
+      rerender(<SourceTextEditor ref={editorRef} value="initial updated" ariaLabel="Measured editor" onChange={onChange} />);
+      expect(measure).not.toHaveBeenCalled();
+    } finally {
+      measure.mockRestore();
+      clearMeasures.mockRestore();
+    }
+  });
+
+  it("does not serialize again when a controlled parent echoes the latest edit", () => {
+    const editorRef = createRef<SourceTextEditorHandle>();
+    const onChange = vi.fn();
+    const { rerender } = render(<SourceTextEditor ref={editorRef} value="initial" ariaLabel="Controlled editor" onChange={onChange} />);
+    const view = editorRef.current?.getView();
+    if (!view) throw new Error("Expected a mounted editor");
+    const transaction = view.state.update({ changes: { from: 7, insert: " updated" } });
+    const serialize = vi.spyOn(transaction.state.doc, "toString");
+    try {
+      view.dispatch(transaction);
+      expect(onChange).toHaveBeenLastCalledWith("initial updated", expect.anything());
+      expect(serialize).toHaveBeenCalledOnce();
+      serialize.mockClear();
+      rerender(<SourceTextEditor ref={editorRef} value="initial updated" ariaLabel="Controlled editor" onChange={onChange} />);
+      expect(serialize).not.toHaveBeenCalled();
+      expect(view.state.doc).toBe(transaction.state.doc);
+      rerender(<SourceTextEditor ref={editorRef} value="external" ariaLabel="Controlled editor" onChange={onChange} />);
+      expect(view.state.doc.toString()).toBe("external");
+      expect(onChange).toHaveBeenCalledOnce();
+    } finally {
+      serialize.mockRestore();
+    }
+  });
+
+  it("does not replay a controlled echo over an edit delivered before passive effects", () => {
+    const editorRef = createRef<SourceTextEditorHandle>();
+    const onChange = vi.fn();
+    function ControlledEditor({ value }: { value: string }) {
+      useLayoutEffect(() => {
+        if (value !== "initial updated") return;
+        const view = editorRef.current?.getView();
+        if (!view) throw new Error("Expected a mounted controlled editor");
+        view.dispatch({ changes: { from: view.state.doc.length, insert: " next" } });
+      }, [value]);
+      return <SourceTextEditor ref={editorRef} value={value} ariaLabel="Rapid controlled editor" onChange={onChange} />;
+    }
+    const { rerender } = render(<ControlledEditor value="initial" />);
+    const view = editorRef.current?.getView();
+    if (!view) throw new Error("Expected a mounted controlled editor");
+    view.dispatch({ changes: { from: view.state.doc.length, insert: " updated" } });
+    rerender(<ControlledEditor value="initial updated" />);
+    expect(view.state.doc.toString()).toBe("initial updated next");
+    expect(onChange).toHaveBeenCalledTimes(2);
+  });
+
+  it("rejects snapshots throughout an active composition, including before its first change", () => {
+    const editorRef = createRef<SourceTextEditorHandle>();
+    render(<SourceTextEditor ref={editorRef} value="initial" ariaLabel="Composition editor" onChange={() => {}} />);
+    const handle = editorRef.current;
+    const view = handle?.getView();
+    if (!handle || !view) throw new Error("Expected a mounted source editor");
+    const original = handle.captureSnapshot();
+    view.contentDOM.dispatchEvent(new CompositionEvent("compositionstart", { bubbles: true }));
+    expect(view.compositionStarted).toBe(true);
+    expect(view.composing).toBe(false);
+    expect(() => handle.captureSnapshot()).toThrow(/composition/);
+    view.dispatch({ changes: { from: view.state.doc.length, insert: " composed" }, userEvent: "input.type.compose" });
+    expect(() => handle.captureSnapshot()).toThrow(/composition/);
+    view.contentDOM.dispatchEvent(new CompositionEvent("compositionend", { bubbles: true, data: "composed" }));
+
+    expect(view.compositionStarted).toBe(false);
+    expect(handle.captureSnapshot().serialize()).toBe("initial composed");
+    expect(original.serialize()).toBe("initial");
+  });
+
+  it("captures an immutable revision without serializing the source during capture", () => {
+    const editorRef = createRef<SourceTextEditorHandle>();
+    const { unmount } = render(<SourceTextEditor ref={editorRef} value="initial" ariaLabel="Snapshot editor" onChange={() => {}} />);
+    const handle = editorRef.current;
+    const view = handle?.getView();
+    if (!handle || !view) throw new Error("Expected a mounted editor");
+    const serialize = vi.spyOn(view.state.doc, "toString");
+    try {
+      const snapshot = handle.captureSnapshot();
+      expect(serialize).not.toHaveBeenCalled();
+      expect(snapshot.revision).toBe(0);
+      expect(Object.isFrozen(snapshot)).toBe(true);
+      view.dispatch({ changes: { from: view.state.doc.length, insert: " updated" } });
+      const latest = handle.captureSnapshot();
+      expect(latest.revision).toBeGreaterThan(snapshot.revision);
+      expect(snapshot.serialize()).toBe("initial");
+      expect(latest.serialize()).toBe("initial updated");
+      unmount();
+      expect(snapshot.serialize()).toBe("initial");
+      expect(() => handle.captureSnapshot()).toThrow(/disposed/);
+    } finally {
+      serialize.mockRestore();
+    }
+  });
+
+  it("includes external document replacements in snapshot revisions", () => {
+    const editorRef = createRef<SourceTextEditorHandle>();
+    const onChange = vi.fn();
+    const { rerender } = render(<SourceTextEditor ref={editorRef} value="initial" ariaLabel="Snapshot editor" onChange={onChange} />);
+    const first = editorRef.current?.captureSnapshot();
+    rerender(<SourceTextEditor ref={editorRef} value="replacement" ariaLabel="Snapshot editor" onChange={onChange} />);
+    const latest = editorRef.current?.captureSnapshot();
+
+    expect(first?.serialize()).toBe("initial");
+    expect(latest?.serialize()).toBe("replacement");
+    expect(latest?.revision).toBeGreaterThan(first?.revision ?? -1);
+    expect(onChange).not.toHaveBeenCalled();
+  });
+
   it("scrolls the viewport with Ctrl+Arrow keys without changing the selection", async () => {
     const editorRef = createRef<SourceTextEditorHandle>();
     const initialValue = "Editor content";
@@ -228,6 +361,49 @@ describe("SourceTextEditor", () => {
     });
   });
 
+  it.each(["theme", "language"])("preserves the viewport and selection when %s extensions change", (change) => {
+    const editorRef = createRef<SourceTextEditorHandle>();
+    const onUpdate = vi.fn();
+    const onChange = vi.fn();
+    const value = "first\nsecond\nthird";
+    const { rerender } = render(
+      <SourceTextEditor
+        ref={editorRef}
+        value={value}
+        extensions={[]}
+        ariaLabel="Stable source editor"
+        onChange={onChange}
+        onUpdate={onUpdate}
+      />
+    );
+    const view = editorRef.current?.getView();
+    if (!view) throw new Error("Expected a mounted editor");
+    view.dispatch({ selection: EditorSelection.range(0, 5) });
+    const document = view.state.doc;
+    const selection = view.state.selection;
+    onUpdate.mockClear();
+
+    rerender(
+      <SourceTextEditor
+        ref={editorRef}
+        value={value}
+        extensions={change === "theme" ? buildTextEditorTheme(TEST_TEXT_THEME) : [markdown()]}
+        ariaLabel="Stable source editor"
+        onChange={onChange}
+        onUpdate={onUpdate}
+      />
+    );
+
+    expect(editorRef.current?.getView()).toBe(view);
+    expect(view.state.doc).toBe(document);
+    expect(view.state.selection).toBe(selection);
+    expect(onUpdate).toHaveBeenCalled();
+    for (const [update] of onUpdate.mock.calls) {
+      expect(update.transactions.every((transaction: { scrollIntoView: boolean }) => !transaction.scrollIntoView)).toBe(true);
+    }
+    expect(onChange).not.toHaveBeenCalled();
+  });
+
   it("retains undo history across controlled value updates", async () => {
     const user = userEvent.setup();
     const editorRef = createRef<SourceTextEditorHandle>();
@@ -560,6 +736,9 @@ describe("SourceTextEditor", () => {
 
     expect(window.getComputedStyle(editor).color).toBe(TEST_MARKDOWN_THEME.textColor);
     expect(window.getComputedStyle(activeLine).backgroundColor).toBe(TEST_MARKDOWN_THEME.activeLineBackground);
-    expect(window.getComputedStyle(linkToken).color).toBe(TEST_MARKDOWN_THEME.linkColor);
+    expect(linkToken).toHaveClass("sambee-syntax-link");
+    expect(window.getComputedStyle(editor.closest(".cm-editor")!).getPropertyValue("--sambee-syntax-link").replaceAll(" ", "")).toBe(
+      TEST_MARKDOWN_THEME.linkColor.replaceAll(" ", "")
+    );
   });
 });
diff --git a/frontend/src/components/Editor/buildCodeMirrorSearchHighlights.ts b/frontend/src/components/Editor/buildCodeMirrorSearchHighlights.ts
index 771117938..5da227251 100644
--- a/frontend/src/components/Editor/buildCodeMirrorSearchHighlights.ts
+++ b/frontend/src/components/Editor/buildCodeMirrorSearchHighlights.ts
@@ -1,6 +1,8 @@
 import { getSearchQuery, searchPanelOpen } from "@codemirror/search";
 import { type Extension, RangeSetBuilder } from "@codemirror/state";
 import { Decoration, type EditorView, ViewPlugin } from "@codemirror/view";
+import { findSelectedCodeMirrorSearchMatch, getCachedCodeMirrorSearchMatches } from "./codeMirrorSearchMatches";
+import { disposeSourceRegexSearch, sourceRegexSearchLifecycle, sourceRegexSearchUpdated } from "./sourceRegexSearch";
 
 export const PASSIVE_SEARCH_MATCH_CLASS = "sambee-passive-search-match";
 export const PASSIVE_SELECTED_SEARCH_MATCH_CLASS = "sambee-passive-search-match-selected";
@@ -19,39 +21,17 @@ function rangeEquals(left: SearchMatchRange | null, right: SearchMatchRange): bo
   return left !== null && left.from === right.from && left.to === right.to;
 }
 
-function rangeContainedInSelection(range: SearchMatchRange, selection: SearchMatchRange): boolean {
-  return selection.from <= range.from && selection.to >= range.to;
-}
-
 function resolveCurrentSearchRange(view: EditorView): SearchMatchRange | null {
-  const query = getSearchQuery(view.state);
-
-  if (!query.search) {
-    return null;
+  const ranges = getCachedCodeMirrorSearchMatches(view);
+  const selection = view.state.selection.main;
+  if (!ranges) {
+    const query = getSearchQuery(view.state);
+    if (selection.empty && !query.regexp) return null;
+    const match = query.getCursor(view.state, selection.from, selection.to).next();
+    return match.done ? null : { from: match.value.from, to: match.value.to };
   }
-
-  const cursor = query.getCursor(view.state);
-  const mainSelection = view.state.selection.main;
-  const mainSelectionRange = { from: mainSelection.from, to: mainSelection.to };
-
-  let currentRange: SearchMatchRange | null = null;
-  let containedRange: SearchMatchRange | null = null;
-
-  for (let nextMatch = cursor.next(); !nextMatch.done; nextMatch = cursor.next()) {
-    const match = nextMatch.value;
-    const matchRange = { from: match.from, to: match.to };
-
-    if (match.from === mainSelection.from && match.to === mainSelection.to) {
-      currentRange = matchRange;
-      continue;
-    }
-
-    if (containedRange === null && rangeContainedInSelection(matchRange, mainSelectionRange)) {
-      containedRange = matchRange;
-    }
-  }
-
-  return currentRange ?? containedRange;
+  const index = findSelectedCodeMirrorSearchMatch(ranges, selection);
+  return index < 0 ? null : (ranges[index] ?? null);
 }
 
 export function buildPassiveSearchHighlightExtension(): Extension {
@@ -59,7 +39,7 @@ export function buildPassiveSearchHighlightExtension(): Extension {
     class {
       decorations;
 
-      constructor(view: EditorView) {
+      constructor(private view: EditorView) {
         this.decorations = this.buildDecorations(view);
       }
 
@@ -70,6 +50,7 @@ export function buildPassiveSearchHighlightExtension(): Extension {
         docChanged: boolean;
         selectionSet: boolean;
         viewportChanged: boolean;
+        transactions?: readonly { effects: readonly { is: (effect: typeof sourceRegexSearchUpdated) => boolean }[] }[];
       }) {
         const query = getSearchQuery(update.state);
         const previousQuery = getSearchQuery(update.startState);
@@ -78,6 +59,7 @@ export function buildPassiveSearchHighlightExtension(): Extension {
           update.docChanged ||
           update.selectionSet ||
           update.viewportChanged ||
+          update.transactions?.some((transaction) => transaction.effects.some((effect) => effect.is(sourceRegexSearchUpdated))) ||
           !query.eq(previousQuery) ||
           searchPanelOpen(update.state) !== searchPanelOpen(update.startState)
         ) {
@@ -107,6 +89,28 @@ export function buildPassiveSearchHighlightExtension(): Extension {
 
         const builder = new RangeSetBuilder<Decoration>();
 
+        if (query.regexp) {
+          const ranges = getCachedCodeMirrorSearchMatches(view) ?? [];
+          for (const visible of view.visibleRanges) {
+            let low = 0;
+            let high = ranges.length;
+            while (low < high) {
+              const middle = (low + high) >>> 1;
+              const range = ranges[middle];
+              if (!range) break;
+              if (range.from < visible.from) low = middle + 1;
+              else high = middle;
+            }
+            for (let index = low; index < ranges.length; index += 1) {
+              const match = ranges[index];
+              if (!match || match.from > visible.to) break;
+              if (match.from === match.to) continue;
+              builder.add(match.from, match.to, rangeEquals(currentRange, match) ? passiveSelectedSearchMatchMark : passiveSearchMatchMark);
+            }
+          }
+          return builder.finish();
+        }
+
         for (const { from, to } of view.visibleRanges) {
           const cursor = query.getCursor(view.state, from, to);
 
@@ -125,6 +129,10 @@ export function buildPassiveSearchHighlightExtension(): Extension {
 
         return builder.finish();
       }
+
+      destroy() {
+        if (!this.view.plugin(sourceRegexSearchLifecycle)) disposeSourceRegexSearch(this.view);
+      }
     },
     {
       decorations: (value) => value.decorations,
diff --git a/frontend/src/components/Editor/buildCodeMirrorSurfaceTheme.ts b/frontend/src/components/Editor/buildCodeMirrorSurfaceTheme.ts
index fb5bffea3..a55798945 100644
--- a/frontend/src/components/Editor/buildCodeMirrorSurfaceTheme.ts
+++ b/frontend/src/components/Editor/buildCodeMirrorSurfaceTheme.ts
@@ -52,6 +52,10 @@ export function buildCodeMirrorSurfaceTheme({
         [`.${PASSIVE_SELECTED_SEARCH_MATCH_CLASS}`]: {
           backgroundColor: currentSearchMatchBackground,
         },
+        [`.cm-content .cm-searchMatch, .cm-content .cm-searchMatch *, .cm-content .${PASSIVE_SEARCH_MATCH_CLASS}, .cm-content .${PASSIVE_SEARCH_MATCH_CLASS} *`]:
+          {
+            color: textColor,
+          },
         ".cm-cursor": {
           borderLeft: `2px solid ${textColor}`,
           marginLeft: 0,
@@ -76,6 +80,11 @@ export function buildCodeMirrorSurfaceTheme({
           border: `1px solid ${borderColor}`,
           color: textColor,
         },
+        ".sambee-source-replacement-feedback": {
+          backgroundColor: surfaceBackground,
+          border: `1px solid ${borderColor}`,
+          color: textColor,
+        },
         ".cm-tooltip-autocomplete ul li[aria-selected]": {
           backgroundColor: activeLineBackground,
           color: textColor,
diff --git a/frontend/src/components/Editor/buildCommonEditorExtensions.ts b/frontend/src/components/Editor/buildCommonEditorExtensions.ts
index 72220c0cf..0d3c4c95c 100644
--- a/frontend/src/components/Editor/buildCommonEditorExtensions.ts
+++ b/frontend/src/components/Editor/buildCommonEditorExtensions.ts
@@ -5,6 +5,8 @@ import { highlightSelectionMatches, search } from "@codemirror/search";
 import type { Extension } from "@codemirror/state";
 import { drawSelection, EditorView, highlightActiveLine, keymap } from "@codemirror/view";
 import { buildSelectionLayerExtension } from "./buildEditorSelectionLayer";
+import { sourceRegexSearchLifecycle } from "./sourceRegexSearch";
+import { sourceReplacementFeedbackExtension } from "./sourceReplacementFeedback";
 
 interface CommonEditorExtensionsOptions {
   defaultSyntaxHighlighting?: boolean;
@@ -28,7 +30,7 @@ function scrollEditorViewport(
   const scrollDelta = nextScrollTop - previousScrollTop;
 
   const selection = view.state.selection.main;
-  const cursorCoords = selection.empty ? view.coordsAtPos(selection.head, selection.assoc) : null;
+  const cursorCoords = selection.empty ? view.coordsAtPos(selection.head, selection.assoc === 0 ? undefined : selection.assoc) : null;
   const scrollerRect = scrollDOM.getBoundingClientRect();
   const caretMovement =
     cursorCoords && direction === EDITOR_VIEWPORT_SCROLL_DIRECTION.DOWN
@@ -82,6 +84,8 @@ export function buildCommonEditorExtensions({
     ...(defaultSyntaxHighlighting ? [syntaxHighlighting(defaultHighlightStyle, { fallback: true })] : []),
     bracketMatching(),
     search({ top: true }),
+    sourceRegexSearchLifecycle,
+    sourceReplacementFeedbackExtension,
     ...(includeSelectionMatches ? [highlightSelectionMatches()] : []),
     highlightActiveLine(),
     ...(lineWrapping ? [EditorView.lineWrapping] : []),
diff --git a/frontend/src/components/Editor/buildMarkdownEditorExtensions.ts b/frontend/src/components/Editor/buildMarkdownEditorExtensions.ts
index 66f479dfe..d18278964 100644
--- a/frontend/src/components/Editor/buildMarkdownEditorExtensions.ts
+++ b/frontend/src/components/Editor/buildMarkdownEditorExtensions.ts
@@ -1,10 +1,11 @@
+import type { CompletionContext } from "@codemirror/autocomplete";
 import { defaultKeymap, historyKeymap } from "@codemirror/commands";
-import { markdown, markdownLanguage, pasteURLAsLink } from "@codemirror/lang-markdown";
-import { languages } from "@codemirror/language-data";
+import { pasteURLAsLink } from "@codemirror/lang-markdown";
 import { searchKeymap } from "@codemirror/search";
 import type { Extension } from "@codemirror/state";
-import { EditorView, keymap } from "@codemirror/view";
+import { EditorView, keymap, type ViewUpdate } from "@codemirror/view";
 import { markdownTableAutocompleter, markdownTables } from "codemirror-markdown-tables";
+import { createMarkdownSupport } from "../../utils/codeMirrorHighlighting";
 import { buildPassiveSearchHighlightExtension } from "./buildCodeMirrorSearchHighlights";
 import { buildCommonEditorExtensions } from "./buildCommonEditorExtensions";
 import { EDITOR_SELECTION_RANGE_CLASS, getSelectionLineSegments, type SelectionLineSegment } from "./buildEditorSelectionLayer";
@@ -22,12 +23,16 @@ export const MARKDOWN_SELECTION_RANGE_CLASS = EDITOR_SELECTION_RANGE_CLASS;
 export type MarkdownSelectionLineSegment = SelectionLineSegment;
 export const getMarkdownSelectionLineSegments = getSelectionLineSegments;
 
-export function buildMarkdownEditorExtensions(theme: MarkdownEditorThemeOptions, lineWrapping: boolean = true): Extension[] {
-  const markdownLanguageSupport = markdown({ base: markdownLanguage, codeLanguages: languages });
+export function buildMarkdownEditorExtensions(
+  theme: MarkdownEditorThemeOptions,
+  lineWrapping: boolean = true,
+  onNestedUpdate?: (update: ViewUpdate) => void
+): Extension[] {
+  const markdownLanguageSupport = createMarkdownSupport();
   const snippetAutocompleter = createMarkdownSnippetAutocompleter();
   const tableAutocompleter = markdownTableAutocompleter({ options: MARKDOWN_TABLE_AUTOCOMPLETE_OPTIONS });
   const markdownAutocompleteData = markdownLanguageSupport.language.data.of({
-    autocomplete: (context) => snippetAutocompleter(context) ?? tableAutocompleter(context),
+    autocomplete: (context: CompletionContext) => snippetAutocompleter(context) ?? tableAutocompleter(context),
   });
   const markdownTableTheme = buildMarkdownTableTheme(theme);
 
@@ -53,7 +58,7 @@ export function buildMarkdownEditorExtensions(theme: MarkdownEditorThemeOptions,
       selectionType: "codemirror",
       handlePosition: "inside",
       lineWrapping: "wrap",
-      extensions: [keymap.of(defaultKeymap)],
+      extensions: [keymap.of(defaultKeymap), ...(onNestedUpdate ? [EditorView.updateListener.of(onNestedUpdate)] : [])],
       globalKeyBindings: [...historyKeymap, ...searchKeymap],
       markdownConfig: {
         completeHTMLTags: true,
diff --git a/frontend/src/components/Editor/buildMarkdownEditorTheme.ts b/frontend/src/components/Editor/buildMarkdownEditorTheme.ts
index dfe54102d..5355a998d 100644
--- a/frontend/src/components/Editor/buildMarkdownEditorTheme.ts
+++ b/frontend/src/components/Editor/buildMarkdownEditorTheme.ts
@@ -1,6 +1,6 @@
-import { HighlightStyle, syntaxHighlighting } from "@codemirror/language";
 import type { Extension } from "@codemirror/state";
-import { tags } from "@lezer/highlight";
+import { EditorView } from "@codemirror/view";
+import { nativeSyntaxHighlighting } from "../../utils/codeMirrorHighlighting";
 import { buildCodeMirrorSurfaceTheme } from "./buildCodeMirrorSurfaceTheme";
 import { buildSelectionLayerTheme } from "./buildEditorSelectionLayer";
 
@@ -43,6 +43,7 @@ export function buildMarkdownEditorTheme({
       textColor,
     }),
     buildSelectionLayerTheme({ selectionBackground, surfaceBackground }),
-    syntaxHighlighting(HighlightStyle.define([{ tag: [tags.labelName, tags.link, tags.string, tags.url], color: linkColor }])),
+    nativeSyntaxHighlighting,
+    EditorView.theme({ "&": { "--sambee-syntax-link": linkColor } }),
   ];
 }
diff --git a/frontend/src/components/Editor/buildTextEditorTheme.ts b/frontend/src/components/Editor/buildTextEditorTheme.ts
index 8bc572450..fc53c2ab7 100644
--- a/frontend/src/components/Editor/buildTextEditorTheme.ts
+++ b/frontend/src/components/Editor/buildTextEditorTheme.ts
@@ -1,6 +1,5 @@
-import { HighlightStyle, syntaxHighlighting } from "@codemirror/language";
 import type { Extension } from "@codemirror/state";
-import { tags } from "@lezer/highlight";
+import { nativeSyntaxHighlighting } from "../../utils/codeMirrorHighlighting";
 import { buildCodeMirrorSurfaceTheme, type CodeMirrorSurfaceThemeOptions } from "./buildCodeMirrorSurfaceTheme";
 import { buildSelectionLayerTheme } from "./buildEditorSelectionLayer";
 
@@ -16,12 +15,6 @@ export function buildTextEditorTheme({ accentColor, ...surfaceOptions }: TextEdi
       selectionBackground: surfaceOptions.selectionBackground,
       surfaceBackground: surfaceOptions.surfaceBackground,
     }),
-    syntaxHighlighting(
-      HighlightStyle.define([
-        { tag: [tags.keyword, tags.controlKeyword, tags.operatorKeyword], color: accentColor },
-        { tag: [tags.string, tags.url], color: accentColor },
-        { tag: [tags.comment], color: `${surfaceOptions.textColor}99`, fontStyle: "italic" },
-      ])
-    ),
+    nativeSyntaxHighlighting,
   ];
 }
diff --git a/frontend/src/components/Editor/codeMirrorSearchMatches.ts b/frontend/src/components/Editor/codeMirrorSearchMatches.ts
new file mode 100644
index 000000000..d4dd2d75f
--- /dev/null
+++ b/frontend/src/components/Editor/codeMirrorSearchMatches.ts
@@ -0,0 +1,48 @@
+import { getSearchQuery, type SearchQuery } from "@codemirror/search";
+import type { Text } from "@codemirror/state";
+import type { EditorView } from "@codemirror/view";
+import { getSourceRegexSearch } from "./sourceRegexSearch";
+
+interface SearchMatchRange {
+  from: number;
+  to: number;
+}
+
+interface CachedSearchMatches {
+  document: Text;
+  query: SearchQuery;
+  ranges: SearchMatchRange[];
+}
+
+const matchCache = new WeakMap<EditorView, CachedSearchMatches>();
+
+export function getCachedCodeMirrorSearchMatches(view: EditorView): readonly SearchMatchRange[] | null {
+  if (getSearchQuery(view.state).regexp) return getSourceRegexSearch(view).ranges;
+  const cached = matchCache.get(view);
+  return cached?.document === view.state.doc && cached.query.eq(getSearchQuery(view.state)) ? cached.ranges : null;
+}
+
+export function getCodeMirrorSearchMatches(view: EditorView): readonly SearchMatchRange[] {
+  const cached = getCachedCodeMirrorSearchMatches(view);
+  if (cached) return cached;
+  const query = getSearchQuery(view.state);
+  const ranges: SearchMatchRange[] = [];
+  const cursor = query.getCursor(view.state);
+  for (let match = cursor.next(); !match.done; match = cursor.next()) ranges.push({ from: match.value.from, to: match.value.to });
+  matchCache.set(view, { document: view.state.doc, query, ranges });
+  return ranges;
+}
+
+export function findSelectedCodeMirrorSearchMatch(ranges: readonly SearchMatchRange[], selection: SearchMatchRange): number {
+  let low = 0;
+  let high = ranges.length;
+  while (low < high) {
+    const middle = (low + high) >>> 1;
+    const range = ranges[middle];
+    if (!range) return -1;
+    if (range.from < selection.from) low = middle + 1;
+    else high = middle;
+  }
+  const match = ranges[low];
+  return match && match.to <= selection.to ? low : -1;
+}
diff --git a/frontend/src/components/Editor/sourceRegexSearch.ts b/frontend/src/components/Editor/sourceRegexSearch.ts
new file mode 100644
index 000000000..9c336c80a
--- /dev/null
+++ b/frontend/src/components/Editor/sourceRegexSearch.ts
@@ -0,0 +1,296 @@
+import { getSearchQuery, type SearchQuery } from "@codemirror/search";
+import { type ChangeSpec, StateEffect, type Text } from "@codemirror/state";
+import { EditorView, ViewPlugin, type ViewUpdate } from "@codemirror/view";
+import {
+  SOURCE_SEARCH_CHUNK_UNITS,
+  SOURCE_SEARCH_RANGE_BATCH,
+  SOURCE_SEARCH_TIMEOUT_MS,
+  type SourceSearchOperation,
+  type SourceSearchRange,
+  type SourceSearchRequest,
+  type SourceSearchResponse,
+} from "./sourceRegexSearchProtocol";
+import { beginSourceReplacementFeedback, isHeavySourceReplacement, isSourceReplacementPending } from "./sourceReplacementFeedback";
+
+export const sourceRegexSearchUpdated = StateEffect.define<null>();
+
+type NavigationOperation = "next" | "previous";
+
+interface RegexSearchSession {
+  document: Text;
+  query: SearchQuery;
+  ranges: SourceSearchRange[];
+  pending: boolean;
+  error?: string;
+  cancel: () => void;
+  enqueueNavigation?: (operation: NavigationOperation) => boolean;
+}
+
+const sessions = new WeakMap<EditorView, RegexSearchSession>();
+
+export const sourceRegexSearchLifecycle = ViewPlugin.fromClass(
+  class {
+    constructor(private view: EditorView) {}
+
+    update(update: ViewUpdate) {
+      const session = sessions.get(this.view);
+      if (session && (update.docChanged || !session.query.eq(getSearchQuery(update.state)))) disposeSourceRegexSearch(this.view);
+    }
+
+    destroy() {
+      disposeSourceRegexSearch(this.view);
+    }
+  }
+);
+
+export function disposeSourceRegexSearch(view: EditorView): void {
+  sessions.get(view)?.cancel();
+  sessions.delete(view);
+}
+
+export function getSourceRegexSearch(view: EditorView): RegexSearchSession {
+  const query = getSearchQuery(view.state);
+  const existing = sessions.get(view);
+  if (existing?.document === view.state.doc && existing.query.eq(query)) return existing;
+  existing?.cancel();
+  const session: RegexSearchSession = { document: view.state.doc, query, ranges: [], pending: true, cancel: () => {} };
+  sessions.set(view, session);
+  if (query.valid && query.regexp) run(view, session, "count");
+  else session.pending = false;
+  return session;
+}
+
+export function runSourceRegexSearchCommand(view: EditorView, operation: Exclude<SourceSearchOperation, "count">): boolean {
+  if (!getSearchQuery(view.state).regexp) return false;
+  if (!getSearchQuery(view.state).valid) return true;
+  if ((operation === "replace-one" || operation === "replace-all") && view.state.readOnly) return true;
+  if ((operation === "replace-one" || operation === "replace-all") && isSourceReplacementPending(view)) return true;
+  const session = getSourceRegexSearch(view);
+  if ((operation === "next" || operation === "previous") && session.enqueueNavigation?.(operation)) return true;
+  session.cancel();
+  run(view, session, operation);
+  return true;
+}
+
+function run(view: EditorView, session: RegexSearchSession, operation: SourceSearchOperation): void {
+  const { document, query } = session;
+  let selection = view.state.selection;
+  const isNavigation = operation === "next" || operation === "previous";
+  const navigationQueue = new Map<number, NavigationOperation>();
+  let nextNavigation = 0;
+  let worker: Worker | undefined;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let sourceOffset = 0;
+  let stopped = false;
+  const ranges: SourceSearchRange[] = [];
+  const changes: { from: number; to: number; chunks: string[] }[] = [];
+  const announcements: string[][] = [];
+  session.pending = true;
+  session.error = undefined;
+  const current = () => sessions.get(view) === session && view.state.doc === document && query.eq(getSearchQuery(view.state));
+  const releaseReplacementBuffers = () => {
+    changes.length = 0;
+    announcements.length = 0;
+  };
+  const stopTransport = () => {
+    if (stopped) return;
+    stopped = true;
+    clearTimeout(timer);
+    navigationQueue.clear();
+    session.enqueueNavigation = undefined;
+    if (worker) {
+      worker.onmessage = null;
+      worker.onerror = null;
+      worker.removeEventListener("messageerror", decodeFailure);
+      worker.terminate();
+      worker = undefined;
+    }
+  };
+  const feedback =
+    operation === "replace-all"
+      ? beginSourceReplacementFeedback(view, () => {
+          stopTransport();
+          releaseReplacementBuffers();
+          if (session.pending && current() && selection !== view.state.selection) {
+            session.error = "Source search was cancelled because the selection changed. Try again.";
+          }
+          session.pending = false;
+        })
+      : undefined;
+  const cancel = () => {
+    stopTransport();
+    feedback?.dispose();
+    releaseReplacementBuffers();
+  };
+  session.cancel = cancel;
+  if (isNavigation) {
+    session.enqueueNavigation = (next) => {
+      if (stopped || !current() || selection !== view.state.selection) return false;
+      navigationQueue.set(nextNavigation++, next);
+      return true;
+    };
+  }
+  const notify = () => {
+    queueMicrotask(() => {
+      if (current()) view.dispatch({ effects: sourceRegexSearchUpdated.of(null) });
+    });
+  };
+  const fail = (message: string) => {
+    cancel();
+    if (!current()) return;
+    session.pending = false;
+    session.error = message;
+    notify();
+  };
+  const decodeFailure = () => fail("Source-search response could not be decoded. Try again.");
+  const send = (message: SourceSearchRequest) => {
+    clearTimeout(timer);
+    timer = setTimeout(() => fail("Source search timed out. Simplify the expression or try again."), SOURCE_SEARCH_TIMEOUT_MS);
+    worker?.postMessage(message);
+  };
+  if (operation !== "count") notify();
+  try {
+    worker = new Worker(new URL("./sourceRegexSearch.worker.ts", import.meta.url), { type: "module" });
+    worker.onerror = (event) => {
+      event.preventDefault();
+      fail("Source-search worker failed. Try the search again.");
+    };
+    worker.addEventListener("messageerror", decodeFailure);
+    worker.onmessage = (event: MessageEvent<SourceSearchResponse>) => {
+      if (stopped) return;
+      if (!current() || (operation !== "count" && selection !== view.state.selection)) {
+        cancel();
+        if (current()) {
+          session.pending = false;
+          session.error = "Source search was cancelled because the selection changed. Try again.";
+          notify();
+        }
+        return;
+      }
+      try {
+        const message = event.data;
+        if (message.type === "ready") {
+          send({
+            type: "start",
+            operation,
+            query: {
+              wordChars: view.state.languageDataAt<string>("wordChars", selection.main.head).join(""),
+              search: query.search,
+              replace: query.replace,
+              literal: query.literal,
+              caseSensitive: query.caseSensitive,
+              wholeWord: query.wholeWord,
+            },
+            selection: { anchor: selection.main.anchor, head: selection.main.head },
+          });
+        } else if (message.type === "source-ack") {
+          const text = document.sliceString(sourceOffset, Math.min(document.length, sourceOffset + SOURCE_SEARCH_CHUNK_UNITS));
+          sourceOffset += text.length;
+          send({ type: "source", text, complete: sourceOffset === document.length });
+        } else if (message.type === "ranges") {
+          if (message.ranges.length > SOURCE_SEARCH_RANGE_BATCH) throw new Error("Source-search range batch exceeded its bound");
+          for (const range of message.ranges) {
+            if (
+              !Number.isInteger(range.from) ||
+              !Number.isInteger(range.to) ||
+              range.from < 0 ||
+              range.to < range.from ||
+              range.to > document.length
+            ) {
+              throw new Error("Source search returned an invalid match range");
+            }
+            ranges.push(range);
+          }
+          send({ type: "ack" });
+        } else if (message.type === "change") {
+          if (
+            message.insert.length > SOURCE_SEARCH_CHUNK_UNITS ||
+            message.from < 0 ||
+            message.to < message.from ||
+            message.to > document.length
+          ) {
+            throw new Error("Source search returned an invalid replacement chunk");
+          }
+          if (message.continued) {
+            const previous = changes.at(-1);
+            if (!previous || previous.from !== message.from || previous.to !== message.to)
+              throw new Error("Source-search replacement lost a chunk");
+            previous.chunks.push(message.insert);
+          } else changes.push({ from: message.from, to: message.to, chunks: [message.insert] });
+          send({ type: "ack" });
+        } else if (message.type === "announcement") {
+          if (message.text.length > SOURCE_SEARCH_CHUNK_UNITS) throw new Error("Source-search announcement exceeded its chunk bound");
+          if (message.continued) {
+            const previous = announcements.at(-1);
+            if (!previous) throw new Error("Source-search announcement lost a chunk");
+            previous.push(message.text);
+          } else announcements.push([message.text]);
+          send({ type: "ack" });
+        } else if (message.type === "error") fail(message.message);
+        else if (message.type === "complete") {
+          if (!isNavigation) stopTransport();
+          if (operation === "count") {
+            session.pending = false;
+            session.ranges = ranges;
+            notify();
+          } else {
+            const plan: ChangeSpec[] = changes.map((change) => ({ from: change.from, to: change.to, insert: change.chunks.join("") }));
+            const commit = () => {
+              session.pending = isNavigation && navigationQueue.size > 0;
+              if (!current() || selection !== view.state.selection || (plan.length > 0 && view.state.readOnly)) return;
+              const commitStart = performance.now();
+              view.dispatch({
+                changes: plan,
+                selection: message.selection,
+                scrollIntoView: Boolean(message.selection),
+                effects: announcements.map((chunks) => EditorView.announce.of(chunks.join(""))),
+                userEvent: message.userEvent,
+              });
+              performance.clearMeasures("sambee:source-search:commit");
+              performance.measure("sambee:source-search:commit", {
+                start: commitStart,
+                detail: { operation, documentUnits: document.length, changes: plan.length },
+              });
+              if (isNavigation && current() && navigationQueue.size > 0) {
+                selection = view.state.selection;
+                const [index, next] = navigationQueue.entries().next().value!;
+                navigationQueue.delete(index);
+                operation = next;
+                session.pending = true;
+                send({
+                  type: "navigate",
+                  operation,
+                  selection: { anchor: selection.main.anchor, head: selection.main.head },
+                  wordChars: view.state.languageDataAt<string>("wordChars", selection.main.head).join(""),
+                });
+              } else {
+                stopTransport();
+                if (current() && session.ranges.length === 0) run(view, session, "count");
+              }
+            };
+            if (feedback) {
+              const insertedUnits = changes.reduce(
+                (total, change) => total + change.chunks.reduce((units, chunk) => units + chunk.length, 0),
+                0
+              );
+              feedback.apply(commit, isHeavySourceReplacement(document.length, changes.length, insertedUnits), (error) =>
+                fail(error instanceof Error ? error.message : "Source replacement failed. Try Replace All again.")
+              );
+            } else {
+              try {
+                commit();
+              } finally {
+                releaseReplacementBuffers();
+              }
+            }
+          }
+        } else throw new Error("Unexpected source-search worker response");
+      } catch (error) {
+        fail(error instanceof Error ? error.message : "Source-search response failed");
+      }
+    };
+    timer = setTimeout(() => fail("Source-search worker did not start. Try again."), SOURCE_SEARCH_TIMEOUT_MS);
+  } catch {
+    fail("Source search requires a working dedicated worker in this browser.");
+  }
+}
diff --git a/frontend/src/components/Editor/sourceRegexSearch.worker.ts b/frontend/src/components/Editor/sourceRegexSearch.worker.ts
new file mode 100644
index 000000000..022b2c789
--- /dev/null
+++ b/frontend/src/components/Editor/sourceRegexSearch.worker.ts
@@ -0,0 +1,129 @@
+import { findNext, findPrevious, replaceAll, replaceNext, SearchQuery, search, setSearchQuery } from "@codemirror/search";
+import { EditorState, type Text, Transaction, type TransactionSpec } from "@codemirror/state";
+import { EditorView } from "@codemirror/view";
+import {
+  SOURCE_SEARCH_CHUNK_UNITS,
+  SOURCE_SEARCH_RANGE_BATCH,
+  type SourceSearchRequest,
+  type SourceSearchResponse,
+} from "./sourceRegexSearchProtocol";
+
+let request: Extract<SourceSearchRequest, { type: "start" }> | undefined;
+let chunks: string[] = [];
+let output: Generator<SourceSearchResponse> | undefined;
+let navigationState: EditorState | undefined;
+
+function* execute(): Generator<SourceSearchResponse> {
+  if (!request) throw new Error("Source search started without a request");
+  const query = new SearchQuery({ ...request.query, regexp: true });
+  if (!query.valid) throw new Error("Invalid source-search expression");
+  let state =
+    navigationState ??
+    EditorState.create({
+      doc: chunks.join(""),
+      extensions: [search(), EditorState.languageData.of(() => [{ wordChars: request?.query.wordChars ?? "" }])],
+    });
+  chunks = [];
+  state = state.update({ effects: setSearchQuery.of(query), selection: request.selection }).state;
+  if (request.operation === "count") {
+    const cursor = query.getCursor(state);
+    let ranges = [];
+    for (let match = cursor.next(); !match.done; match = cursor.next()) {
+      ranges.push({ from: match.value.from, to: match.value.to });
+      if (ranges.length === SOURCE_SEARCH_RANGE_BATCH) {
+        yield { type: "ranges", ranges };
+        ranges = [];
+      }
+    }
+    if (ranges.length) yield { type: "ranges", ranges };
+    yield { type: "complete", announcements: [] };
+    return;
+  }
+  let transaction: Transaction | undefined;
+  const target = {
+    get state() {
+      return state;
+    },
+    plugin: () => null,
+    dispatch: (spec: TransactionSpec) => {
+      transaction = state.update(spec);
+    },
+  };
+  const commands = { next: findNext, previous: findPrevious, "replace-one": replaceNext, "replace-all": replaceAll };
+  commands[request.operation](target as unknown as EditorView);
+  if (request.operation === "next" || request.operation === "previous") navigationState = transaction?.state ?? state;
+  if (!transaction) {
+    yield { type: "complete", announcements: [] };
+    return;
+  }
+  const changes: { from: number; to: number; inserted: Text }[] = [];
+  transaction.changes.iterChanges((from, to, _fromNew, _toNew, inserted) => {
+    changes.push({ from, to, inserted });
+  }, true);
+  for (const { from, to, inserted } of changes) {
+    for (let offset = 0; offset < inserted.length || offset === 0; offset += SOURCE_SEARCH_CHUNK_UNITS) {
+      yield {
+        type: "change",
+        from,
+        to,
+        insert: inserted.sliceString(offset, Math.min(inserted.length, offset + SOURCE_SEARCH_CHUNK_UNITS)),
+        continued: offset > 0,
+      };
+    }
+  }
+  const selection = transaction.selection?.main;
+  for (const effect of transaction.effects) {
+    if (!effect.is(EditorView.announce)) continue;
+    for (let offset = 0; offset < effect.value.length; offset += SOURCE_SEARCH_CHUNK_UNITS) {
+      yield { type: "announcement", text: effect.value.slice(offset, offset + SOURCE_SEARCH_CHUNK_UNITS), continued: offset > 0 };
+    }
+  }
+  yield {
+    type: "complete",
+    selection: selection ? { anchor: selection.anchor, head: selection.head } : undefined,
+    userEvent: transaction.annotation(Transaction.userEvent),
+    announcements: [],
+  };
+}
+
+function publishNext(): void {
+  const next = output?.next();
+  if (next && !next.done) globalThis.postMessage(next.value);
+}
+
+globalThis.onmessage = (event: MessageEvent<SourceSearchRequest>) => {
+  try {
+    const message = event.data;
+    if (message.type === "start") {
+      request = message;
+      chunks = [];
+      navigationState = undefined;
+      globalThis.postMessage({ type: "source-ack" } satisfies SourceSearchResponse);
+    } else if (message.type === "navigate") {
+      if (!navigationState || !request || (request.operation !== "next" && request.operation !== "previous"))
+        throw new Error("Source navigation requires a prepared navigation document");
+      request = {
+        ...request,
+        operation: message.operation,
+        selection: message.selection,
+        query: { ...request.query, wordChars: message.wordChars },
+      };
+      output = execute();
+      publishNext();
+    } else if (message.type === "source") {
+      if (message.text.length > SOURCE_SEARCH_CHUNK_UNITS) throw new Error("Source-search transfer exceeded its chunk bound");
+      chunks.push(message.text);
+      if (message.complete) {
+        output = execute();
+        publishNext();
+      } else globalThis.postMessage({ type: "source-ack" } satisfies SourceSearchResponse);
+    } else publishNext();
+  } catch (error) {
+    output = undefined;
+    chunks = [];
+    navigationState = undefined;
+    globalThis.postMessage({ type: "error", message: error instanceof Error ? error.message : "Source search failed" });
+  }
+};
+
+globalThis.postMessage({ type: "ready" } satisfies SourceSearchResponse);
diff --git a/frontend/src/components/Editor/sourceRegexSearchProtocol.ts b/frontend/src/components/Editor/sourceRegexSearchProtocol.ts
new file mode 100644
index 000000000..927bdd1f6
--- /dev/null
+++ b/frontend/src/components/Editor/sourceRegexSearchProtocol.ts
@@ -0,0 +1,34 @@
+export const SOURCE_SEARCH_CHUNK_UNITS = 16_384;
+export const SOURCE_SEARCH_RANGE_BATCH = 512;
+export const SOURCE_SEARCH_TIMEOUT_MS = 2_000;
+
+export type SourceSearchOperation = "count" | "next" | "previous" | "replace-one" | "replace-all";
+
+export interface SourceSearchRange {
+  from: number;
+  to: number;
+}
+
+export interface SourceSearchQuery {
+  wordChars: string;
+  search: string;
+  replace: string;
+  caseSensitive: boolean;
+  wholeWord: boolean;
+  literal: boolean;
+}
+
+export type SourceSearchRequest =
+  | { type: "start"; operation: SourceSearchOperation; query: SourceSearchQuery; selection: { anchor: number; head: number } }
+  | { type: "source"; text: string; complete: boolean }
+  | { type: "navigate"; operation: "next" | "previous"; selection: { anchor: number; head: number }; wordChars: string }
+  | { type: "ack" };
+
+export type SourceSearchResponse =
+  | { type: "ready" }
+  | { type: "source-ack" }
+  | { type: "ranges"; ranges: SourceSearchRange[] }
+  | { type: "change"; from: number; to: number; insert: string; continued: boolean }
+  | { type: "announcement"; text: string; continued: boolean }
+  | { type: "complete"; selection?: { anchor: number; head: number }; userEvent?: string; announcements: string[] }
+  | { type: "error"; message: string };
diff --git a/frontend/src/components/Editor/sourceReplacementFeedback.ts b/frontend/src/components/Editor/sourceReplacementFeedback.ts
new file mode 100644
index 000000000..6067dade1
--- /dev/null
+++ b/frontend/src/components/Editor/sourceReplacementFeedback.ts
@@ -0,0 +1,189 @@
+import { getSearchQuery } from "@codemirror/search";
+import { StateEffect } from "@codemirror/state";
+import { EditorView, ViewPlugin } from "@codemirror/view";
+import { t } from "i18next";
+
+export const SOURCE_REPLACEMENT_FEEDBACK_DELAY_MS = 200;
+export const SOURCE_REPLACEMENT_HEAVY_MATCHES = 1_000;
+export const SOURCE_REPLACEMENT_HEAVY_UNITS = 50_000;
+const FEEDBACK_CLASS = "sambee-source-replacement-feedback";
+const feedbackUpdated = StateEffect.define<null>();
+
+const pending = new WeakMap<EditorView, SourceReplacementFeedback>();
+const feedbackViews = new WeakSet<EditorView>();
+
+const feedbackTheme = EditorView.baseTheme({
+  [`& .${FEEDBACK_CLASS}`]: {
+    position: "absolute",
+    bottom: "8px",
+    right: "16px",
+    zIndex: "5",
+    display: "flex",
+    alignItems: "center",
+    gap: "8px",
+    padding: "6px 10px",
+    borderRadius: "4px",
+    backgroundColor: "Canvas",
+    color: "CanvasText",
+    boxShadow: "0 1px 4px #0004",
+    pointerEvents: "none",
+    fontSize: "13px",
+  },
+  [`& .${FEEDBACK_CLASS} .sambee-replacement-spinner`]: {
+    width: "14px",
+    height: "14px",
+    flexShrink: "0",
+    border: "2px solid currentColor",
+    borderRightColor: "transparent",
+    borderRadius: "50%",
+  },
+});
+
+const feedbackLifecycle = ViewPlugin.fromClass(
+  class {
+    constructor(private view: EditorView) {
+      feedbackViews.add(view);
+    }
+
+    update() {
+      const feedback = pending.get(this.view);
+      if (feedback && !feedback.current()) feedback.dispose();
+    }
+
+    destroy() {
+      feedbackViews.delete(this.view);
+      pending.get(this.view)?.dispose();
+    }
+  }
+);
+
+export const sourceReplacementFeedbackExtension = [feedbackLifecycle, feedbackTheme];
+
+export function isSourceReplacementPending(view: EditorView): boolean {
+  return pending.has(view);
+}
+
+export function isHeavySourceReplacement(documentUnits: number, matches: number, insertedUnits: number): boolean {
+  return matches >= SOURCE_REPLACEMENT_HEAVY_MATCHES && Math.max(documentUnits, insertedUnits) >= SOURCE_REPLACEMENT_HEAVY_UNITS;
+}
+
+export function beginSourceReplacementFeedback(view: EditorView, onDispose?: () => void): SourceReplacementFeedback {
+  if (!view.plugin(feedbackLifecycle)) view.dispatch({ effects: StateEffect.appendConfig.of(sourceReplacementFeedbackExtension) });
+  pending.get(view)?.dispose();
+  const feedback = new SourceReplacementFeedback(view, onDispose);
+  pending.set(view, feedback);
+  feedback.notify();
+  return feedback;
+}
+
+class SourceReplacementFeedback {
+  private readonly document;
+  private readonly query;
+  private readonly selection;
+  private indicator?: HTMLElement;
+  private animation?: Animation;
+  private delayTimer?: ReturnType<typeof setTimeout>;
+  private hiddenTimer?: ReturnType<typeof setTimeout>;
+  private frame?: number;
+  private disposed = false;
+  private applyPending?: () => void;
+
+  constructor(
+    private readonly view: EditorView,
+    private readonly onDispose?: () => void
+  ) {
+    this.document = view.state.doc;
+    this.query = getSearchQuery(view.state);
+    this.selection = view.state.selection;
+    this.delayTimer = setTimeout(() => this.show(), SOURCE_REPLACEMENT_FEEDBACK_DELAY_MS);
+  }
+
+  current(): boolean {
+    return (
+      !this.disposed &&
+      feedbackViews.has(this.view) &&
+      this.view.state.doc === this.document &&
+      this.view.state.selection === this.selection &&
+      this.query.eq(getSearchQuery(this.view.state)) &&
+      !this.view.state.readOnly
+    );
+  }
+
+  notify(): void {
+    queueMicrotask(() => {
+      if (feedbackViews.has(this.view)) this.view.dispatch({ effects: feedbackUpdated.of(null) });
+    });
+  }
+
+  private show(): void {
+    if (!this.current() || this.indicator) return;
+    const indicator = this.view.dom.ownerDocument.createElement("div");
+    indicator.className = FEEDBACK_CLASS;
+    indicator.setAttribute("role", "status");
+    indicator.textContent = t("viewer.edit.replacing", { defaultValue: "Replacing matches..." });
+    const spinner = this.view.dom.ownerDocument.createElement("span");
+    spinner.className = "sambee-replacement-spinner";
+    spinner.setAttribute("aria-hidden", "true");
+    indicator.prepend(spinner);
+    this.view.dom.append(indicator);
+    if (!this.view.dom.ownerDocument.defaultView?.matchMedia("(prefers-reduced-motion: reduce)").matches) {
+      this.animation = spinner.animate?.([{ transform: "rotate(0deg)" }, { transform: "rotate(360deg)" }], {
+        duration: 800,
+        iterations: Number.POSITIVE_INFINITY,
+      });
+    }
+    this.view.contentDOM.setAttribute("aria-busy", "true");
+    this.indicator = indicator;
+  }
+
+  apply(action: () => void, heavy: boolean, onError: (error: unknown) => void): void {
+    clearTimeout(this.delayTimer);
+    const commit = () => {
+      try {
+        if (this.current()) action();
+      } catch (error) {
+        onError(error);
+      } finally {
+        this.dispose();
+      }
+    };
+    if (!this.indicator && !heavy) {
+      commit();
+      return;
+    }
+    this.show();
+    this.applyPending = commit;
+    const document = this.view.dom.ownerDocument;
+    document.addEventListener("visibilitychange", this.onVisibilityChange);
+    if (document.hidden) {
+      this.hiddenTimer = setTimeout(commit, 0);
+    } else {
+      this.frame = requestAnimationFrame(() => {
+        this.frame = requestAnimationFrame(commit);
+      });
+    }
+  }
+
+  private onVisibilityChange = (): void => {
+    if (!this.view.dom.ownerDocument.hidden || !this.applyPending) return;
+    if (this.frame !== undefined) cancelAnimationFrame(this.frame);
+    clearTimeout(this.hiddenTimer);
+    this.hiddenTimer = setTimeout(this.applyPending, 0);
+  };
+
+  dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    clearTimeout(this.delayTimer);
+    clearTimeout(this.hiddenTimer);
+    if (this.frame !== undefined) cancelAnimationFrame(this.frame);
+    this.view.dom.ownerDocument.removeEventListener("visibilitychange", this.onVisibilityChange);
+    this.applyPending = undefined;
+    this.animation?.cancel();
+    this.indicator?.remove();
+    this.view.contentDOM.removeAttribute("aria-busy");
+    if (pending.get(this.view) === this) pending.delete(this.view);
+    this.onDispose?.();
+    this.notify();
+  }
+}
diff --git a/frontend/src/components/Editor/sourceTextEditorTypes.ts b/frontend/src/components/Editor/sourceTextEditorTypes.ts
index 6341f9025..a615d1681 100644
--- a/frontend/src/components/Editor/sourceTextEditorTypes.ts
+++ b/frontend/src/components/Editor/sourceTextEditorTypes.ts
@@ -1,6 +1,11 @@
 import type { Extension, TransactionSpec } from "@codemirror/state";
 import type { Command, EditorView, ViewUpdate } from "@codemirror/view";
 
+export interface SourceTextSnapshot {
+  readonly revision: number;
+  serialize(): string;
+}
+
 export interface SourceTextEditorProps {
   value: string;
   extensions?: Extension[];
@@ -16,6 +21,7 @@ export interface SourceTextEditorProps {
 
 export interface SourceTextEditorHandle {
   focus: () => void;
+  captureSnapshot: () => SourceTextSnapshot;
   getValue: () => string;
   getPrimarySelectionText: () => string;
   getView: () => EditorView | null;
diff --git a/frontend/src/components/FileBrowser/DesktopToolbar.tsx b/frontend/src/components/FileBrowser/DesktopToolbar.tsx
index aefa6a6a1..267cf1901 100644
--- a/frontend/src/components/FileBrowser/DesktopToolbar.tsx
+++ b/frontend/src/components/FileBrowser/DesktopToolbar.tsx
@@ -10,7 +10,7 @@ interface DesktopToolbarProps {
   searchProvider: SearchProvider;
   searchActivationToken?: number;
   searchRefreshToken?: number;
-  searchInputRef?: React.RefObject<HTMLInputElement>;
+  searchInputRef?: React.RefObject<HTMLInputElement | null>;
   showSearch: boolean;
   onOpenHelp: () => void;
   onOpenDocumentation: () => void;
diff --git a/frontend/src/components/FileBrowser/FileBrowserAlerts.tsx b/frontend/src/components/FileBrowser/FileBrowserAlerts.tsx
index e9a735174..4652f52c3 100644
--- a/frontend/src/components/FileBrowser/FileBrowserAlerts.tsx
+++ b/frontend/src/components/FileBrowser/FileBrowserAlerts.tsx
@@ -3,6 +3,7 @@
 //
 
 import { Alert, Box, Button, Link, Stack, Typography } from "@mui/material";
+import type { TFunction } from "i18next";
 import { useTranslation } from "react-i18next";
 import type { BackendAvailabilityStatus } from "../../services/backendAvailability";
 import type { CompanionPairingErrorKind } from "../../services/localDrivePairing";
@@ -10,7 +11,7 @@ import { EmptyStateIllustration } from "./EmptyStateIllustration";
 
 export type CompanionLifecycleStatus = "renewal_required" | "auth_failed" | "lock_lost" | "recovery_required";
 
-function getCompanionLifecycleMessage(t: ReturnType<typeof useTranslation>["t"], status: CompanionLifecycleStatus): string {
+function getCompanionLifecycleMessage(t: TFunction, status: CompanionLifecycleStatus): string {
   switch (status) {
     case "renewal_required":
       return t("fileBrowser.chrome.alerts.companionLifecycle.renewal_required");
@@ -115,7 +116,7 @@ export function FileBrowserAlerts({
           sx={{ mb: 2, mx: 2 }}
           action={
             companionPairingError && onOpenLocalDrivesSettings ? (
-              <Stack direction="row" flexWrap="wrap">
+              <Stack direction="row" sx={{ flexWrap: "wrap" }}>
                 {companionPairingError === "signature" && (
                   <Button color="inherit" size="small" onClick={() => window.location.reload()}>
                     {t("settings.localDrives.reloadButton")}
diff --git a/frontend/src/components/FileBrowser/FileList.tsx b/frontend/src/components/FileBrowser/FileList.tsx
index 30d5b7702..62c13e762 100644
--- a/frontend/src/components/FileBrowser/FileList.tsx
+++ b/frontend/src/components/FileBrowser/FileList.tsx
@@ -25,7 +25,7 @@ interface FileListProps {
   onIconClick?: (file: FileEntry, index: number, extend: boolean, additive: boolean) => void;
   onClearSelection?: () => void;
   rowVirtualizer: Virtualizer<HTMLDivElement, Element>;
-  parentRef: React.RefObject<HTMLDivElement>;
+  parentRef: React.RefObject<HTMLDivElement | null>;
   listContainerRef: (node: HTMLDivElement | null) => void;
   fileRowStyles: {
     iconBox: Record<string, unknown>;
@@ -67,7 +67,7 @@ export const FileList = React.memo(
     const { t } = useTranslation();
     const listElementRef = useRef<HTMLDivElement>(null);
     const [itemMenu, setItemMenu] = useState<{
-      actions: CompactItemAction[];
+      actions: readonly CompactItemAction[];
       anchorPosition: { top: number; left: number };
       triggerElement: HTMLElement;
     } | null>(null);
@@ -99,7 +99,7 @@ export const FileList = React.memo(
 
     return (
       <Box
-        ref={(node) => {
+        ref={(node: HTMLDivElement | null) => {
           listElementRef.current = node;
           listContainerRef(node);
         }}
diff --git a/frontend/src/components/FileBrowser/FileRow.tsx b/frontend/src/components/FileBrowser/FileRow.tsx
index 6088015cc..730820a15 100644
--- a/frontend/src/components/FileBrowser/FileRow.tsx
+++ b/frontend/src/components/FileBrowser/FileRow.tsx
@@ -54,7 +54,7 @@ interface FileRowProps {
 export const shortenTargetPath = abbreviatePath;
 
 function getCompactFileMetadata(file: FileEntry): string | null {
-  if (file.type === "directory" || file.link_target?.target.type === "directory") {
+  if (file.type === "directory" || file.link_target?.target?.type === "directory") {
     return null;
   }
 
diff --git a/frontend/src/components/FileBrowser/OverwriteConflictDialog.tsx b/frontend/src/components/FileBrowser/OverwriteConflictDialog.tsx
index 86567546f..c87768500 100644
--- a/frontend/src/components/FileBrowser/OverwriteConflictDialog.tsx
+++ b/frontend/src/components/FileBrowser/OverwriteConflictDialog.tsx
@@ -149,7 +149,7 @@ const OverwriteConflictDialog: React.FC<OverwriteConflictDialogProps> = ({
   const [renameDraft, setRenameDraft] = useState("");
   const [isSubmitting, setIsSubmitting] = useState(false);
   const targetNameRef = useRef<HTMLInputElement>(null);
-  const resolutionGroupRef = useRef<HTMLDivElement>(null);
+  const resolutionGroupRef = useRef<HTMLFieldSetElement>(null);
   const previousConflictIdentityRef = useRef<string | null>(null);
   const shouldFocusInitialControlRef = useRef(false);
   const shouldFocusRenameInputRef = useRef(false);
@@ -403,7 +403,7 @@ const OverwriteConflictDialog: React.FC<OverwriteConflictDialogProps> = ({
           />
         </Box>
         {progress && (
-          <Typography variant="caption" display="block" sx={{ mt: 0.5, color: "text.secondary" }}>
+          <Typography variant="caption" sx={{ display: "block", mt: 0.5, color: "text.secondary" }}>
             {S.PROGRESS_CONTEXT(progress.current, progress.total, progress.conflictsSoFar)}
           </Typography>
         )}
diff --git a/frontend/src/components/FileBrowser/SearchBar.tsx b/frontend/src/components/FileBrowser/SearchBar.tsx
index cce9fd889..b53112928 100644
--- a/frontend/src/components/FileBrowser/SearchBar.tsx
+++ b/frontend/src/components/FileBrowser/SearchBar.tsx
@@ -11,7 +11,7 @@ import { useTranslation } from "react-i18next";
 interface SearchBarProps {
   value: string;
   onChange: (value: string) => void;
-  inputRef?: React.RefObject<HTMLInputElement>;
+  inputRef?: React.RefObject<HTMLInputElement | null>;
   useCompactLayout?: boolean;
   /** Called when ESC is pressed on an empty search field */
   onBlurToFileList?: () => void;
diff --git a/frontend/src/components/FileBrowser/UnifiedSearchBar.tsx b/frontend/src/components/FileBrowser/UnifiedSearchBar.tsx
index 08411afdc..42eb7729b 100644
--- a/frontend/src/components/FileBrowser/UnifiedSearchBar.tsx
+++ b/frontend/src/components/FileBrowser/UnifiedSearchBar.tsx
@@ -128,7 +128,7 @@ interface UnifiedSearchBarProps {
   /** Increments whenever visible results should refresh without changing dropdown visibility. */
   refreshToken?: number;
   /** Ref forwarded to the underlying <input> element */
-  inputRef?: React.RefObject<HTMLInputElement>;
+  inputRef?: React.RefObject<HTMLInputElement | null>;
   /** Remove from Tab order (dual-pane mode uses Tab for pane switching) */
   disableTabFocus?: boolean;
   /** Whether to use compact (mobile) layout styling */
diff --git a/frontend/src/components/FileBrowser/__tests__/BrowserViewerPicker.test.tsx b/frontend/src/components/FileBrowser/__tests__/BrowserViewerPicker.test.tsx
index ea034cd88..fa7936095 100644
--- a/frontend/src/components/FileBrowser/__tests__/BrowserViewerPicker.test.tsx
+++ b/frontend/src/components/FileBrowser/__tests__/BrowserViewerPicker.test.tsx
@@ -2,6 +2,8 @@ import { fireEvent, render, screen } from "@testing-library/react";
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import { BrowserViewerPicker } from "../BrowserViewerPicker";
 
+const persistenceProps = { saving: false, saveError: null, onOpenWithoutSaving: vi.fn() };
+
 vi.mock("react-i18next", () => ({
   useTranslation: () => ({
     t: (key: string) => {
@@ -35,6 +37,7 @@ describe("BrowserViewerPicker", () => {
 
     render(
       <BrowserViewerPicker
+        {...persistenceProps}
         open={true}
         fileName="report.pdf"
         viewerIds={["pdf", "markdown"]}
@@ -60,6 +63,7 @@ describe("BrowserViewerPicker", () => {
 
     render(
       <BrowserViewerPicker
+        {...persistenceProps}
         open={true}
         fileName="report.pdf"
         viewerIds={["pdf", "markdown"]}
@@ -90,6 +94,7 @@ describe("BrowserViewerPicker", () => {
 
     render(
       <BrowserViewerPicker
+        {...persistenceProps}
         open={true}
         fileName="archive.bin"
         viewerIds={["image", "markdown", "pdf"]}
@@ -117,6 +122,7 @@ describe("BrowserViewerPicker", () => {
 
     render(
       <BrowserViewerPicker
+        {...persistenceProps}
         open={true}
         fileName="notes.MD"
         viewerIds={["image", "markdown", "pdf"]}
@@ -143,6 +149,7 @@ describe("BrowserViewerPicker", () => {
   it("renders the text viewer option when provided", () => {
     render(
       <BrowserViewerPicker
+        {...persistenceProps}
         open={true}
         fileName="notes.txt"
         viewerIds={["text"]}
@@ -160,6 +167,7 @@ describe("BrowserViewerPicker", () => {
   it("focuses the viewer list when the dialog opens", async () => {
     render(
       <BrowserViewerPicker
+        {...persistenceProps}
         open={true}
         fileName="report.pdf"
         viewerIds={["pdf", "markdown"]}
@@ -183,6 +191,7 @@ describe("BrowserViewerPicker", () => {
 
     render(
       <BrowserViewerPicker
+        {...persistenceProps}
         open={true}
         fileName="report.pdf"
         viewerIds={["pdf", "markdown"]}
@@ -210,6 +219,7 @@ describe("BrowserViewerPicker", () => {
 
     render(
       <BrowserViewerPicker
+        {...persistenceProps}
         open={true}
         fileName="report.pdf"
         viewerIds={["pdf", "markdown"]}
@@ -235,6 +245,7 @@ describe("BrowserViewerPicker", () => {
 
     render(
       <BrowserViewerPicker
+        {...persistenceProps}
         open={true}
         fileName="report.pdf"
         viewerIds={["pdf"]}
diff --git a/frontend/src/components/FileBrowser/__tests__/CompactCreateMenu.test.tsx b/frontend/src/components/FileBrowser/__tests__/CompactCreateMenu.test.tsx
index 8f8b70318..0748132f0 100644
--- a/frontend/src/components/FileBrowser/__tests__/CompactCreateMenu.test.tsx
+++ b/frontend/src/components/FileBrowser/__tests__/CompactCreateMenu.test.tsx
@@ -2,6 +2,7 @@ import { fireEvent, render, screen } from "@testing-library/react";
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import { setLocale } from "../../../i18n";
 import type { FileOperationAction } from "../../../pages/FileBrowser/fileOperationActions";
+import { requireTestValue } from "../../../test/helpers/assertions";
 import { CompactCreateMenu } from "../CompactCreateMenu";
 
 const actions: FileOperationAction[] = [
@@ -41,7 +42,7 @@ describe("CompactCreateMenu", () => {
     fireEvent.click(screen.getByRole("button", { name: "Create new item" }));
 
     fireEvent.click(screen.getByRole("menuitem", { name: "New folder" }));
-    expect(actions[0].onClick).toHaveBeenCalledOnce();
+    expect(requireTestValue(actions[0]).onClick).toHaveBeenCalledOnce();
 
     fireEvent.click(screen.getByRole("button", { name: "Create new item" }));
     expect(screen.getByRole("menuitem", { name: "New file" })).toHaveAttribute("aria-disabled", "true");
diff --git a/frontend/src/components/FileBrowser/__tests__/CompactSelectionActions.test.tsx b/frontend/src/components/FileBrowser/__tests__/CompactSelectionActions.test.tsx
index 4b6f223dc..94c9d4e4a 100644
--- a/frontend/src/components/FileBrowser/__tests__/CompactSelectionActions.test.tsx
+++ b/frontend/src/components/FileBrowser/__tests__/CompactSelectionActions.test.tsx
@@ -2,6 +2,7 @@ import { fireEvent, render, screen } from "@testing-library/react";
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import { setLocale } from "../../../i18n";
 import type { FileOperationAction } from "../../../pages/FileBrowser/fileOperationActions";
+import { requireTestValue } from "../../../test/helpers/assertions";
 import { CompactSelectionActions } from "../CompactSelectionActions";
 
 const actions: FileOperationAction[] = [
@@ -46,14 +47,14 @@ describe("CompactSelectionActions", () => {
 
     fireEvent.click(screen.getByRole("button", { name: "Selection actions" }));
     fireEvent.click(screen.getByRole("menuitem", { name: "Create archive" }));
-    expect(actions[0].onClick).toHaveBeenCalledOnce();
+    expect(requireTestValue(actions[0]).onClick).toHaveBeenCalledOnce();
     fireEvent.click(screen.getByRole("button", { name: "Selection actions" }));
     expect(screen.getByRole("menuitem", { name: "Delete" })).toHaveAttribute("aria-disabled", "true");
   });
 
   it("keeps the action snapshot that was present when the menu opened", () => {
-    const firstAction = { ...actions[0], onClick: vi.fn() };
-    const secondAction = { ...actions[0], label: "Later action", onClick: vi.fn() };
+    const firstAction = { ...requireTestValue(actions[0]), onClick: vi.fn() };
+    const secondAction = { ...requireTestValue(actions[0]), label: "Later action", onClick: vi.fn() };
     const { rerender } = render(
       <CompactSelectionActions actions={actions} getActions={() => [firstAction]} selectedCount={1} onClearSelection={() => {}} />
     );
diff --git a/frontend/src/components/FileBrowser/__tests__/ConfirmDeleteDialog.test.tsx b/frontend/src/components/FileBrowser/__tests__/ConfirmDeleteDialog.test.tsx
index dd0606246..5303748a1 100644
--- a/frontend/src/components/FileBrowser/__tests__/ConfirmDeleteDialog.test.tsx
+++ b/frontend/src/components/FileBrowser/__tests__/ConfirmDeleteDialog.test.tsx
@@ -19,7 +19,7 @@ import { CONFIRM_DELETE_STRINGS } from "../confirmDeleteDialogStrings";
 describe("ConfirmDeleteDialog", () => {
   const defaultProps = {
     open: true,
-    items: [{ name: "readme.txt", path: "readme.txt", type: FileType.FILE, size: 0, modified_at: "", is_readable: true }],
+    items: [{ name: "readme.txt", path: "readme.txt", type: FileType.FILE, size: 0, modified_at: "", is_readable: true, is_hidden: false }],
     isDeleting: false,
     onClose: vi.fn(),
     onConfirm: vi.fn(),
diff --git a/frontend/src/components/FileBrowser/__tests__/ConnectionSelector.test.tsx b/frontend/src/components/FileBrowser/__tests__/ConnectionSelector.test.tsx
index 6a001ec81..e83f469b5 100644
--- a/frontend/src/components/FileBrowser/__tests__/ConnectionSelector.test.tsx
+++ b/frontend/src/components/FileBrowser/__tests__/ConnectionSelector.test.tsx
@@ -3,6 +3,7 @@ import userEvent from "@testing-library/user-event";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { setLocale } from "../../../i18n";
 import { CONNECTION_TYPE_LOCAL, LOCAL_DRIVE_PREFIX } from "../../../services/backendRouter";
+import { createMockConnection } from "../../../test/fixtures/connections";
 import { SambeeThemeProvider } from "../../../theme/ThemeContext";
 import { ConnectionSelector } from "../ConnectionSelector";
 
@@ -12,7 +13,7 @@ describe("ConnectionSelector", () => {
   });
 
   const connections = [
-    {
+    createMockConnection({
       id: "server-1",
       name: "Office Share",
       type: "smb",
@@ -22,8 +23,8 @@ describe("ConnectionSelector", () => {
       username: "alex",
       created_at: "2026-03-11T00:00:00Z",
       updated_at: "2026-03-11T00:00:00Z",
-    },
-    {
+    }),
+    createMockConnection({
       id: `${LOCAL_DRIVE_PREFIX}c`,
       name: "Local Disk (C:)",
       type: CONNECTION_TYPE_LOCAL,
@@ -33,7 +34,7 @@ describe("ConnectionSelector", () => {
       username: "",
       created_at: "2026-03-11T00:00:00Z",
       updated_at: "2026-03-11T00:00:00Z",
-    },
+    }),
   ];
 
   it.each([
diff --git a/frontend/src/components/FileBrowser/__tests__/DynamicViewer.test.tsx b/frontend/src/components/FileBrowser/__tests__/DynamicViewer.test.tsx
index 9499b5d2d..7a37caf62 100644
--- a/frontend/src/components/FileBrowser/__tests__/DynamicViewer.test.tsx
+++ b/frontend/src/components/FileBrowser/__tests__/DynamicViewer.test.tsx
@@ -290,7 +290,7 @@ describe("DynamicViewer", () => {
     mockGetViewerComponentLoadResult.mockResolvedValue({
       status: "loaded",
       component: function LoadedViewer({ path, isTransitioning, onCurrentIndexChange, navigation }: ViewerComponentProps) {
-        useKeyboardShortcuts({ shortcuts: [{ id: "download", keys: "d", handler: download }] });
+        useKeyboardShortcuts({ shortcuts: [{ description: "Save", id: "download", keys: "d", handler: download }] });
         return (
           <div
             data-testid="loaded-viewer"
diff --git a/frontend/src/components/FileBrowser/__tests__/FileList.test.tsx b/frontend/src/components/FileBrowser/__tests__/FileList.test.tsx
index 63e66f423..b6f2168d6 100644
--- a/frontend/src/components/FileBrowser/__tests__/FileList.test.tsx
+++ b/frontend/src/components/FileBrowser/__tests__/FileList.test.tsx
@@ -2,8 +2,9 @@ import type { Virtualizer } from "@tanstack/react-virtual";
 import { fireEvent, render, screen } from "@testing-library/react";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { setLocale, translate } from "../../../i18n";
+import { requireTestValue } from "../../../test/helpers/assertions";
 import { FILE_BROWSER_ROW_HEIGHT } from "../../../theme/constants";
-import type { FileEntry } from "../../../types";
+import { type FileEntry, FileType } from "../../../types";
 import { FileList } from "../FileList";
 
 const rowVirtualizerStub = {
@@ -29,7 +30,7 @@ describe("FileList", () => {
     const file: FileEntry = {
       name: "readme.txt",
       path: "readme.txt",
-      type: "file",
+      type: FileType.FILE,
       is_readable: true,
       is_hidden: false,
     };
@@ -124,7 +125,7 @@ describe("FileList", () => {
       {
         name: "readme.txt",
         path: "readme.txt",
-        type: "file",
+        type: FileType.FILE,
         size: 123,
         mime_type: "text/plain",
         modified_at: "2026-07-15T00:00:00Z",
@@ -157,7 +158,7 @@ describe("FileList", () => {
       {
         name: "readme.txt",
         path: "readme.txt",
-        type: "file",
+        type: FileType.FILE,
         size: 123,
         modified_at: "2026-07-15T00:00:00Z",
         is_readable: true,
@@ -207,7 +208,7 @@ describe("FileList", () => {
       {
         name: "readme.txt",
         path: "readme.txt",
-        type: "file",
+        type: FileType.FILE,
         size: 123,
         modified_at: "2026-07-15T00:00:00Z",
         is_readable: true,
@@ -224,7 +225,7 @@ describe("FileList", () => {
       <FileList
         files={files}
         focusedIndex={0}
-        selectedFiles={new Set([files[0].path])}
+        selectedFiles={new Set([requireTestValue(files[0]).path])}
         onFileClick={() => {}}
         onToggleItemSelection={onToggleItemSelection}
         onSelectItem={() => {}}
@@ -252,7 +253,7 @@ describe("FileList", () => {
       {
         name: "readme.txt",
         path: "readme.txt",
-        type: "file",
+        type: FileType.FILE,
         size: 123,
         modified_at: "2026-07-15T00:00:00Z",
         is_readable: true,
@@ -264,7 +265,7 @@ describe("FileList", () => {
       <FileList
         files={files}
         focusedIndex={0}
-        selectedFiles={new Set([files[0].path])}
+        selectedFiles={new Set([requireTestValue(files[0]).path])}
         onFileClick={() => {}}
         compactOverlay={<div data-testid="selection-dock-overlay" />}
         compactOverlayLayout="dock"
@@ -286,7 +287,7 @@ describe("FileList", () => {
       {
         name: "backup.zip",
         path: "backup.zip",
-        type: "file",
+        type: FileType.FILE,
         size: 123,
         modified_at: "2026-07-15T00:00:00Z",
         is_readable: true,
diff --git a/frontend/src/components/FileBrowser/__tests__/FileOperationsToolbar.test.tsx b/frontend/src/components/FileBrowser/__tests__/FileOperationsToolbar.test.tsx
index 70e7b2ee4..256c10d71 100644
--- a/frontend/src/components/FileBrowser/__tests__/FileOperationsToolbar.test.tsx
+++ b/frontend/src/components/FileBrowser/__tests__/FileOperationsToolbar.test.tsx
@@ -2,12 +2,15 @@ import { act, fireEvent, render, screen, waitFor } from "@testing-library/react"
 import userEvent from "@testing-library/user-event";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import type { FileOperationAction } from "../../../pages/FileBrowser/fileOperationActions";
+import { requireTestValue } from "../../../test/helpers/assertions";
 import { SambeeThemeProvider } from "../../../theme/ThemeContext";
 import { FileOperationsToolbar } from "../FileOperationsToolbar";
 
 function createAction(id: FileOperationAction["id"], overrides: Partial<FileOperationAction> = {}): FileOperationAction {
   return {
     id,
+    surface: "desktop-toolbar",
+    scope: "selection",
     priority: 1,
     label: id,
     shortcut: "F1",
@@ -84,10 +87,10 @@ describe("FileOperationsToolbar", () => {
         disconnect() {}
       }
     );
-    vi.spyOn(HTMLElement.prototype, "getBoundingClientRect").mockImplementation(function () {
-      if (this.dataset.operationId) return { width: 100 } as DOMRect;
+    vi.spyOn(HTMLElement.prototype, "getBoundingClientRect").mockImplementation(function (this: HTMLElement) {
+      if (this.dataset["operationId"]) return { width: 100 } as DOMRect;
       if (this.hasAttribute("data-more-button")) return { width: 44 } as DOMRect;
-      if (this.dataset.testid === "file-operations-toolbar") return { width: 180 } as DOMRect;
+      if (this.dataset["testid"] === "file-operations-toolbar") return { width: 180 } as DOMRect;
       return { width: 0 } as DOMRect;
     });
 
@@ -116,10 +119,10 @@ describe("FileOperationsToolbar", () => {
         disconnect() {}
       }
     );
-    vi.spyOn(HTMLElement.prototype, "getBoundingClientRect").mockImplementation(function () {
-      if (this.dataset.operationId) return { width: operationWidth } as DOMRect;
+    vi.spyOn(HTMLElement.prototype, "getBoundingClientRect").mockImplementation(function (this: HTMLElement) {
+      if (this.dataset["operationId"]) return { width: operationWidth } as DOMRect;
       if (this.hasAttribute("data-more-button")) return { width: 60 } as DOMRect;
-      if (this.dataset.testid === "file-operations-toolbar") return { width: toolbarWidth } as DOMRect;
+      if (this.dataset["testid"] === "file-operations-toolbar") return { width: toolbarWidth } as DOMRect;
       return { width: 0 } as DOMRect;
     });
     const copy = createAction("copy", { label: "Copy" });
@@ -135,7 +138,7 @@ describe("FileOperationsToolbar", () => {
     expect(move.onClick).toHaveBeenCalledOnce();
 
     toolbarWidth = 600;
-    act(() => observers[0]([], {} as ResizeObserver));
+    act(() => requireTestValue(observers[0])([], {} as ResizeObserver));
 
     await waitFor(() => expect(screen.queryByRole("button", { name: "More" })).not.toBeInTheDocument());
     expect(screen.getByRole("button", { name: "Move" })).toBeInTheDocument();
@@ -162,10 +165,10 @@ describe("FileOperationsToolbar", () => {
         disconnect() {}
       }
     );
-    vi.spyOn(HTMLElement.prototype, "getBoundingClientRect").mockImplementation(function () {
-      if (this.dataset.operationId) return { width: 100 } as DOMRect;
+    vi.spyOn(HTMLElement.prototype, "getBoundingClientRect").mockImplementation(function (this: HTMLElement) {
+      if (this.dataset["operationId"]) return { width: 100 } as DOMRect;
       if (this.hasAttribute("data-more-button")) return { width: 60 } as DOMRect;
-      if (this.dataset.testid === "file-operations-toolbar") return { width: 80 } as DOMRect;
+      if (this.dataset["testid"] === "file-operations-toolbar") return { width: 80 } as DOMRect;
       return { width: 0 } as DOMRect;
     });
     const onUploadTriggerChange = vi.fn();
@@ -203,10 +206,10 @@ describe("FileOperationsToolbar", () => {
         disconnect() {}
       }
     );
-    vi.spyOn(HTMLElement.prototype, "getBoundingClientRect").mockImplementation(function () {
-      if (this.dataset.operationId) return { width: 100 } as DOMRect;
+    vi.spyOn(HTMLElement.prototype, "getBoundingClientRect").mockImplementation(function (this: HTMLElement) {
+      if (this.dataset["operationId"]) return { width: 100 } as DOMRect;
       if (this.hasAttribute("data-more-button")) return { width: 60 } as DOMRect;
-      if (this.dataset.testid === "file-operations-toolbar") return { width: 180 } as DOMRect;
+      if (this.dataset["testid"] === "file-operations-toolbar") return { width: 180 } as DOMRect;
       return { width: 0 } as DOMRect;
     });
     const move = createAction("move", { label: "Move", enabled: false });
diff --git a/frontend/src/components/FileBrowser/__tests__/FileRow.test.tsx b/frontend/src/components/FileBrowser/__tests__/FileRow.test.tsx
index 08ee2603a..fc2fc7b58 100644
--- a/frontend/src/components/FileBrowser/__tests__/FileRow.test.tsx
+++ b/frontend/src/components/FileBrowser/__tests__/FileRow.test.tsx
@@ -3,20 +3,21 @@ import { afterEach, describe, expect, it, vi } from "vitest";
 import { setLocale, translate } from "../../../i18n";
 import { formatDate, formatFileSize } from "../../../pages/FileBrowser/formatters";
 import { FILE_BROWSER_ROW_HEIGHT } from "../../../theme/constants";
-import { FileType } from "../../../types";
+import { type FileInfo, FileType } from "../../../types";
 import { FileRow, shortenTargetPath } from "../FileRow";
 
 function createDefaultFileRowProps() {
+  const file: FileInfo = {
+    name: "report.pdf",
+    path: "/report.pdf",
+    type: FileType.FILE,
+    size: 1024,
+    modified_at: "2024-01-01T00:00:00Z",
+    is_readable: true,
+    is_hidden: false,
+  };
   return {
-    file: {
-      name: "report.pdf",
-      path: "/report.pdf",
-      type: FileType.FILE,
-      size: 1024,
-      modified_at: "2024-01-01T00:00:00Z",
-      is_readable: true,
-      is_hidden: false,
-    },
+    file,
     useCompactLayout: false,
     index: 0,
     isSelected: true,
diff --git a/frontend/src/components/FileBrowser/__tests__/SecondaryActionStrip.test.tsx b/frontend/src/components/FileBrowser/__tests__/SecondaryActionStrip.test.tsx
index 953a554ea..b17362248 100644
--- a/frontend/src/components/FileBrowser/__tests__/SecondaryActionStrip.test.tsx
+++ b/frontend/src/components/FileBrowser/__tests__/SecondaryActionStrip.test.tsx
@@ -1,6 +1,7 @@
 import { render, screen } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 import { describe, expect, it, vi } from "vitest";
+import { createMockConnection } from "../../../test/fixtures/connections";
 import { SambeeThemeProvider } from "../../../theme/ThemeContext";
 import { SecondaryActionStrip } from "../SecondaryActionStrip";
 
@@ -34,7 +35,7 @@ describe("SecondaryActionStrip", () => {
       <SambeeThemeProvider>
         <SecondaryActionStrip
           connections={[
-            {
+            createMockConnection({
               id: "demo-conn",
               name: "Demo",
               type: "smb",
@@ -44,7 +45,7 @@ describe("SecondaryActionStrip", () => {
               username: "demo-user",
               created_at: "2026-03-11T00:00:00Z",
               updated_at: "2026-03-11T00:00:00Z",
-            },
+            }),
           ]}
           selectedConnectionId="demo-conn"
           onConnectionChange={vi.fn()}
@@ -86,7 +87,7 @@ describe("SecondaryActionStrip", () => {
       <SambeeThemeProvider>
         <SecondaryActionStrip
           connections={[
-            {
+            createMockConnection({
               id: "demo-conn",
               name: "Demo",
               type: "smb",
@@ -96,7 +97,7 @@ describe("SecondaryActionStrip", () => {
               username: "demo-user",
               created_at: "2026-03-11T00:00:00Z",
               updated_at: "2026-03-11T00:00:00Z",
-            },
+            }),
           ]}
           selectedConnectionId="demo-conn"
           onConnectionChange={vi.fn()}
@@ -131,7 +132,7 @@ describe("SecondaryActionStrip", () => {
       <SambeeThemeProvider>
         <SecondaryActionStrip
           connections={[
-            {
+            createMockConnection({
               id: "demo-conn",
               name: "Demo",
               type: "smb",
@@ -141,7 +142,7 @@ describe("SecondaryActionStrip", () => {
               username: "demo-user",
               created_at: "2026-03-11T00:00:00Z",
               updated_at: "2026-03-11T00:00:00Z",
-            },
+            }),
           ]}
           selectedConnectionId="demo-conn"
           onConnectionChange={vi.fn()}
diff --git a/frontend/src/components/FileBrowser/__tests__/StatusBar.test.tsx b/frontend/src/components/FileBrowser/__tests__/StatusBar.test.tsx
index 99e21f50e..bccdf2a96 100644
--- a/frontend/src/components/FileBrowser/__tests__/StatusBar.test.tsx
+++ b/frontend/src/components/FileBrowser/__tests__/StatusBar.test.tsx
@@ -2,15 +2,15 @@ import { render, screen } from "@testing-library/react";
 import { afterEach, describe, expect, it } from "vitest";
 import { setLocale, translate } from "../../../i18n";
 import { SambeeThemeProvider } from "../../../theme/ThemeContext";
-import type { FileEntry } from "../../../types";
+import { type FileEntry, FileType } from "../../../types";
 import { StatusBar } from "../StatusBar";
 
 const baseFile: FileEntry = {
   name: "notes.txt",
   path: "/notes.txt",
-  type: "file",
+  type: FileType.FILE,
   size: 1024,
-  modified_at: null,
+  modified_at: undefined,
   is_readable: true,
   is_hidden: false,
 };
diff --git a/frontend/src/components/FileBrowser/__tests__/UnifiedSearchBar.test.tsx b/frontend/src/components/FileBrowser/__tests__/UnifiedSearchBar.test.tsx
index 0516a9763..9c1222546 100644
--- a/frontend/src/components/FileBrowser/__tests__/UnifiedSearchBar.test.tsx
+++ b/frontend/src/components/FileBrowser/__tests__/UnifiedSearchBar.test.tsx
@@ -198,7 +198,7 @@ function createGroupedProvider(onSelect: SearchProvider["onSelect"]): SearchProv
 function createRemovableGroupedProvider(): SearchProvider {
   let hasRemovedRecent = false;
 
-  const getResults = () => [
+  const getResults = (): Awaited<ReturnType<SearchProvider["fetchResults"]>> => [
     { kind: "group-header" as const, id: "recent", value: "", label: "Recent files" },
     ...(!hasRemovedRecent
       ? [
@@ -218,7 +218,7 @@ function createRemovableGroupedProvider(): SearchProvider {
       icon: "recent-file" as const,
       primaryText: "Second recent file",
     },
-    { kind: "group-header" as const, id: "current", value: "", label: "Current directory" },
+    { kind: "group-header" as const, id: "current", value: "" as const, label: "Current directory" },
     {
       kind: "result" as const,
       id: "current-file",
diff --git a/frontend/src/components/FileBrowser/search/useDirectorySearchProvider.tsx b/frontend/src/components/FileBrowser/search/useDirectorySearchProvider.tsx
index e84301bf0..67822fa7b 100644
--- a/frontend/src/components/FileBrowser/search/useDirectorySearchProvider.tsx
+++ b/frontend/src/components/FileBrowser/search/useDirectorySearchProvider.tsx
@@ -315,7 +315,7 @@ export function useDirectorySearchProvider(
   // onSelect
   //
   const onSelect = useCallback(
-    (value: string) => {
+    (value: string): undefined => {
       if (value.startsWith(RECENT_DIRECTORY_PREFIX)) {
         const directory = recentDirectoriesRef.current.get(value.slice(RECENT_DIRECTORY_PREFIX.length));
         if (directory) {
diff --git a/frontend/src/components/FileBrowser/search/useFileSearchProvider.tsx b/frontend/src/components/FileBrowser/search/useFileSearchProvider.tsx
index a669b4d80..cc610052e 100644
--- a/frontend/src/components/FileBrowser/search/useFileSearchProvider.tsx
+++ b/frontend/src/components/FileBrowser/search/useFileSearchProvider.tsx
@@ -97,7 +97,7 @@ export function useFileSearchProvider({
               {
                 id: "recent-group-header",
                 kind: "group-header" as const,
-                value: "",
+                value: "" as const,
                 label: t("fileBrowser.search.groups.recentFiles"),
               },
             ]
@@ -116,7 +116,7 @@ export function useFileSearchProvider({
               {
                 id: "current-directory-group-header",
                 kind: "group-header" as const,
-                value: "",
+                value: "" as const,
                 label: t("fileBrowser.search.groups.currentDirectory"),
               },
             ]
diff --git a/frontend/src/components/FileBrowser/sortControlsStrings.ts b/frontend/src/components/FileBrowser/sortControlsStrings.ts
index c593e0b91..2c87cc051 100644
--- a/frontend/src/components/FileBrowser/sortControlsStrings.ts
+++ b/frontend/src/components/FileBrowser/sortControlsStrings.ts
@@ -1,7 +1,8 @@
+import type { ParseKeys } from "i18next";
 import { translate } from "../../i18n";
 import type { SortField } from "../../pages/FileBrowser/types";
 
-const SORT_FIELD_KEYS: Record<SortField, string> = {
+const SORT_FIELD_KEYS: Record<SortField, ParseKeys> = {
   name: "fileBrowser.chrome.sort.fields.name",
   size: "fileBrowser.chrome.sort.fields.size",
   modified: "fileBrowser.chrome.sort.fields.modified",
diff --git a/frontend/src/components/FileBrowser/viewModeSelectorStrings.ts b/frontend/src/components/FileBrowser/viewModeSelectorStrings.ts
index e38060503..d3e7b3d64 100644
--- a/frontend/src/components/FileBrowser/viewModeSelectorStrings.ts
+++ b/frontend/src/components/FileBrowser/viewModeSelectorStrings.ts
@@ -1,7 +1,8 @@
+import type { ParseKeys } from "i18next";
 import { translate } from "../../i18n";
 import type { ViewMode } from "../../pages/FileBrowser/types";
 
-const VIEW_MODE_KEYS: Record<ViewMode, string> = {
+const VIEW_MODE_KEYS: Record<ViewMode, ParseKeys> = {
   list: "fileBrowser.chrome.viewMode.options.list",
   details: "fileBrowser.chrome.viewMode.options.details",
 };
diff --git a/frontend/src/components/Mobile/MobileSettingsDrawer.tsx b/frontend/src/components/Mobile/MobileSettingsDrawer.tsx
index 1bfa4a8d6..4f0b54f3f 100644
--- a/frontend/src/components/Mobile/MobileSettingsDrawer.tsx
+++ b/frontend/src/components/Mobile/MobileSettingsDrawer.tsx
@@ -121,7 +121,7 @@ export const MobileSettingsDrawer: React.FC<MobileSettingsDrawerProps> = ({
                 subheaderSx={{ bgcolor: "background.default", textTransform: "uppercase", letterSpacing: 0.8 }}
                 itemButtonSx={{ py: 2 }}
                 itemIconSx={{ color: "primary.main" }}
-                primaryTypographyProps={{ fontWeight: "medium" }}
+                primaryTypographyProps={{ sx: { fontWeight: "medium" } }}
               />
             </Box>
           )}
diff --git a/frontend/src/components/Mobile/__tests__/HamburgerMenu.test.tsx b/frontend/src/components/Mobile/__tests__/HamburgerMenu.test.tsx
index bad5ac4ef..d60fb695d 100644
--- a/frontend/src/components/Mobile/__tests__/HamburgerMenu.test.tsx
+++ b/frontend/src/components/Mobile/__tests__/HamburgerMenu.test.tsx
@@ -2,6 +2,7 @@ import { createTheme } from "@mui/material";
 import { fireEvent, render, screen, waitFor } from "@testing-library/react";
 import { BrowserRouter } from "react-router-dom";
 import { beforeEach, describe, expect, test, vi } from "vitest";
+import { requireTestValue } from "../../../test/helpers/assertions";
 import "../../../i18n";
 import HamburgerMenu from "../../../components/Mobile/HamburgerMenu";
 import { mobileNavigationDrawerTypographySx } from "../../../theme/mobileShell";
@@ -109,7 +110,7 @@ describe("HamburgerMenu", () => {
       throw new Error("Main drawer typography must remain theme-aware.");
     }
 
-    const styles = mobileNavigationDrawerTypographySx(theme);
+    const styles = requireTestValue(mobileNavigationDrawerTypographySx(theme));
     expect(styles[theme.breakpoints.down("sm")]).toMatchObject({
       "& .MuiTypography-h6": { fontSize: "20px" },
       "& .MuiListItemText-primary, & .MuiInputBase-input, & .MuiSelect-select": { fontSize: "17px" },
diff --git a/frontend/src/components/ResizableDialog.tsx b/frontend/src/components/ResizableDialog.tsx
index 743bec41a..2f27702ac 100644
--- a/frontend/src/components/ResizableDialog.tsx
+++ b/frontend/src/components/ResizableDialog.tsx
@@ -42,12 +42,14 @@ function getViewportSize(): ResizableDialogViewport {
 }
 
 function isResizableDialogSize(value: unknown): value is ResizableDialogSize {
-  if (typeof value !== "object" || value === null) {
+  if (typeof value !== "object" || value === null || !("width" in value) || !("height" in value)) {
     return false;
   }
 
-  const { width, height } = value as Partial<ResizableDialogSize>;
-  return Number.isFinite(width) && Number.isFinite(height) && width > 0 && height > 0;
+  const { width, height } = value;
+  return (
+    typeof width === "number" && typeof height === "number" && Number.isFinite(width) && Number.isFinite(height) && width > 0 && height > 0
+  );
 }
 
 function clampDimension(value: number, minimum: number, maximum: number): number {
diff --git a/frontend/src/components/Settings/SettingsDialog.tsx b/frontend/src/components/Settings/SettingsDialog.tsx
index e50a24c3c..ca35502b5 100644
--- a/frontend/src/components/Settings/SettingsDialog.tsx
+++ b/frontend/src/components/Settings/SettingsDialog.tsx
@@ -159,7 +159,7 @@ const SettingsDialog: React.FC<SettingsDialogProps> = ({
         backdrop: {
           sx: (theme) => {
             const surfaces = getOverlaySurfaceTokens(theme.palette.background.default, theme.palette.mode);
-            return surfaces.backdrop ? { bgcolor: surfaces.backdrop } : undefined;
+            return surfaces.backdrop ? { bgcolor: surfaces.backdrop } : {};
           },
         },
         paper: {
diff --git a/frontend/src/components/Settings/SettingsFormLayout.tsx b/frontend/src/components/Settings/SettingsFormLayout.tsx
index 27ba84f86..baf0645ba 100644
--- a/frontend/src/components/Settings/SettingsFormLayout.tsx
+++ b/frontend/src/components/Settings/SettingsFormLayout.tsx
@@ -1,4 +1,5 @@
-import { alpha, Box, type ReactNode, Tooltip } from "@mui/material";
+import { alpha, Box, Tooltip } from "@mui/material";
+import type { ReactNode } from "react";
 import { SettingsGroup } from "./SettingsGroup";
 
 interface SettingsFormSectionProps {
diff --git a/frontend/src/components/Settings/SettingsSectionHeader.tsx b/frontend/src/components/Settings/SettingsSectionHeader.tsx
index badcc6015..f3e08358a 100644
--- a/frontend/src/components/Settings/SettingsSectionHeader.tsx
+++ b/frontend/src/components/Settings/SettingsSectionHeader.tsx
@@ -35,7 +35,7 @@ export function SettingsSectionHeader({
     <Box sx={resolvedSx}>
       <Box sx={{ minWidth: 0 }}>
         {showTitle && (
-          <Typography variant="h5" fontWeight="medium">
+          <Typography variant="h5" sx={{ fontWeight: "medium" }}>
             {title}
           </Typography>
         )}
diff --git a/frontend/src/components/Settings/ThemeEditorDialog.tsx b/frontend/src/components/Settings/ThemeEditorDialog.tsx
index ca7e08018..3ec993b65 100644
--- a/frontend/src/components/Settings/ThemeEditorDialog.tsx
+++ b/frontend/src/components/Settings/ThemeEditorDialog.tsx
@@ -17,6 +17,7 @@ import {
 import { type ChangeEvent, useRef, useState } from "react";
 import { HexAlphaColorPicker } from "react-colorful";
 import api, { getThemeRequestError, type StoredTheme } from "../../services/api";
+import { resolveSyntaxTheme } from "../../theme/resolveSyntaxTheme";
 import {
   COLOR_ROLES,
   colorAt,
@@ -44,12 +45,12 @@ interface ThemeEditorDialogProps {
   onSaved: (themeId: string, isCopy: boolean) => Promise<void>;
 }
 
-const GROUPS = ["Core", "Viewers", "Markdown", "Search", "Alerts"] as const;
+const GROUPS = ["Core", "Viewers", "Markdown", "Syntax", "Search", "Alerts"] as const;
 
 export function ThemeEditorDialog({ theme, stored, storedThemes, isAdmin, onClose, onSaved }: ThemeEditorDialogProps) {
   const muiTheme = useTheme();
   const usesDesktopFormLayout = useMediaQuery(muiTheme.breakpoints.up("md"));
-  const [draft, setDraft] = useState<ThemeConfig>(() => structuredClone(theme));
+  const [draft, setDraft] = useState<ThemeConfig>(() => resolveSyntaxTheme(theme));
   const [inputColors, setInputColors] = useState<Record<string, string>>({});
   const [group, setGroup] = useState<string | null>("Core");
   const [anchor, setAnchor] = useState<HTMLElement | null>(null);
diff --git a/frontend/src/components/Settings/__tests__/ThemeEditorDialog.test.tsx b/frontend/src/components/Settings/__tests__/ThemeEditorDialog.test.tsx
index ef8ffa943..15a520d6a 100644
--- a/frontend/src/components/Settings/__tests__/ThemeEditorDialog.test.tsx
+++ b/frontend/src/components/Settings/__tests__/ThemeEditorDialog.test.tsx
@@ -89,7 +89,7 @@ describe("ThemeEditorDialog", () => {
     const user = userEvent.setup();
     const create = vi.spyOn(api, "createTheme");
     const { onClose } = renderEditor();
-    expect(screen.getByRole("button", { name: "Save", exact: true })).toBeDisabled();
+    expect(screen.getByRole("button", { name: "Save" })).toBeDisabled();
 
     await user.clear(screen.getByDisplayValue(theme.primary.main));
     await user.type(screen.getByRole("textbox", { name: /Main/ }), "#bad");
@@ -120,6 +120,51 @@ describe("ThemeEditorDialog", () => {
     expect(create).not.toHaveBeenCalled();
   });
 
+  it("edits syntax through the existing picker, validation focus and copy workflow", async () => {
+    const user = userEvent.setup();
+    const create = vi.spyOn(api, "createTheme").mockResolvedValue({ id: "syntax-copy", version: 1, scope: "user", definition: theme });
+    const original = structuredClone(theme.components!.syntax);
+    renderEditor();
+    await user.click(screen.getByRole("button", { name: "Syntax" }));
+    await user.click(screen.getByRole("button", { name: "Choose Keyword color" }));
+    expect(document.querySelector(".react-colorful__alpha")).toBeInTheDocument();
+    await user.keyboard("{Escape}");
+    const keyword = screen.getByRole("textbox", { name: "Keyword" });
+    await user.clear(keyword);
+    await user.type(keyword, "invalid");
+    await chooseCopyDestination(user);
+    await waitFor(() => expect(keyword).toHaveFocus());
+    expect(keyword).toHaveAttribute("aria-invalid", "true");
+    expect(create).not.toHaveBeenCalled();
+    await user.clear(keyword);
+    await user.type(keyword, "#12345678");
+    expect(theme.components!.syntax).toEqual(original);
+    await chooseCopyDestination(user);
+    await waitFor(() =>
+      expect(create).toHaveBeenCalledWith(
+        expect.objectContaining({
+          components: expect.objectContaining({ syntax: { ...original, keyword: "#12345678" } }),
+        }),
+        "user"
+      )
+    );
+  });
+
+  it("discards syntax edits on Cancel without changing the active definition", async () => {
+    const user = userEvent.setup();
+    const create = vi.spyOn(api, "createTheme");
+    const { onClose } = renderEditor();
+    const original = structuredClone(theme.components!.syntax);
+    await user.click(screen.getByRole("button", { name: "Syntax" }));
+    const keyword = screen.getByRole("textbox", { name: "Keyword" });
+    await user.clear(keyword);
+    await user.type(keyword, "#123456");
+    await user.click(screen.getByRole("button", { name: "Cancel" }));
+    expect(create).not.toHaveBeenCalled();
+    expect(onClose).toHaveBeenCalledOnce();
+    expect(theme.components!.syntax).toEqual(original);
+  });
+
   it("offers an alpha picker and saves a copied built-in with a server-generated ID", async () => {
     const user = userEvent.setup();
     const created = vi.spyOn(api, "createTheme").mockResolvedValue({ id: "server-id", version: 1, scope: "user", definition: theme });
@@ -177,7 +222,7 @@ describe("ThemeEditorDialog", () => {
 
     await user.clear(screen.getByDisplayValue("Writable"));
     await user.type(screen.getByRole("textbox", { name: /Name/ }), "Updated");
-    await user.click(screen.getByRole("button", { name: "Save", exact: true }));
+    await user.click(screen.getByRole("button", { name: "Save" }));
 
     await waitFor(() => expect(update).toHaveBeenCalledWith(stored, expect.objectContaining({ name: "Updated" })));
     expect(onSaved).toHaveBeenCalledWith(stored.id, false);
@@ -311,7 +356,7 @@ describe("ThemeEditorDialog", () => {
     );
 
     expect(screen.queryByRole("combobox", { name: "Storage" })).not.toBeInTheDocument();
-    expect(screen.getByRole("button", { name: "Save", exact: true })).toBeEnabled();
+    expect(screen.getByRole("button", { name: "Save" })).toBeEnabled();
     await chooseCopyDestination(user);
 
     await waitFor(() => expect(create).toHaveBeenCalledWith(expect.objectContaining({ name: "Site theme" }), "user"));
diff --git a/frontend/src/components/Settings/__tests__/settingsTypographyStyles.test.ts b/frontend/src/components/Settings/__tests__/settingsTypographyStyles.test.ts
index b5b3e068c..b745c2104 100644
--- a/frontend/src/components/Settings/__tests__/settingsTypographyStyles.test.ts
+++ b/frontend/src/components/Settings/__tests__/settingsTypographyStyles.test.ts
@@ -1,5 +1,6 @@
 import { createTheme } from "@mui/material";
 import { describe, expect, it } from "vitest";
+import { requireTestValue } from "../../../test/helpers/assertions";
 import { COMPACT_LAYOUT_SIZE } from "../../../theme/constants";
 import { settingsCompactTypographyScopeSx } from "../settingsTypographyStyles";
 
@@ -24,7 +25,7 @@ describe("settings compact typography", () => {
       throw new Error("Settings compact typography must remain theme-aware.");
     }
 
-    const styles = settingsCompactTypographyScopeSx(theme);
+    const styles = requireTestValue(settingsCompactTypographyScopeSx(theme));
     const compactStyles = styles[theme.breakpoints.down("sm")];
 
     expect(compactStyles).toMatchObject({
diff --git a/frontend/src/components/Settings/settingsNavigation.ts b/frontend/src/components/Settings/settingsNavigation.ts
index de0bd0773..9211d923f 100644
--- a/frontend/src/components/Settings/settingsNavigation.ts
+++ b/frontend/src/components/Settings/settingsNavigation.ts
@@ -1,3 +1,4 @@
+import type { ParseKeys } from "i18next";
 import { translate } from "../../i18n";
 import { SETTINGS_CATEGORY_ORDER, type SettingsCategory } from "./settingsCategories";
 
@@ -17,7 +18,7 @@ export interface VisibleSettingsSection {
 
 interface SettingsCategoryMeta {
   label: string;
-  descriptionKey: string;
+  descriptionKey: Extract<ParseKeys, `settings.categories.${string}.description` | `settings.connectionsSubgroups.${string}.description`>;
   route: string;
   section: SettingsSection;
   adminOnly?: boolean;
@@ -178,7 +179,7 @@ export function getSettingsViewTitle(view: MobileSettingsView): string {
   return view === "main" ? translate("settings.shell.title") : getSettingsNavItemLabel(view);
 }
 
-export function getSettingsCategoryDescriptionKey(category: SettingsCategory): string {
+export function getSettingsCategoryDescriptionKey(category: SettingsCategory): SettingsCategoryMeta["descriptionKey"] {
   return SETTINGS_CATEGORY_META[category].descriptionKey;
 }
 
diff --git a/frontend/src/components/Settings/settingsTypographyStyles.ts b/frontend/src/components/Settings/settingsTypographyStyles.ts
index 5067195fe..1ec06cc62 100644
--- a/frontend/src/components/Settings/settingsTypographyStyles.ts
+++ b/frontend/src/components/Settings/settingsTypographyStyles.ts
@@ -7,7 +7,7 @@ export const settingsListItemTitleSx: SxProps<Theme> = {
 };
 
 /** Compact typography policy for the full-page settings shells only. */
-export const settingsCompactTypographyScopeSx: SxProps<Theme> = (theme) => ({
+export const settingsCompactTypographyScopeSx = ((theme: Theme) => ({
   [theme.breakpoints.down("sm")]: {
     "& .MuiAppBar-root .MuiTypography-h6": {
       fontSize: `${COMPACT_LAYOUT_SIZE.SETTINGS_APP_BAR_TITLE_PX}px`,
@@ -35,4 +35,4 @@ export const settingsCompactTypographyScopeSx: SxProps<Theme> = (theme) => ({
       fontSize: `${COMPACT_LAYOUT_SIZE.SETTINGS_METADATA_TEXT_PX}px`,
     },
   },
-});
+})) satisfies SxProps<Theme>;
diff --git a/frontend/src/components/ThemeSelector.tsx b/frontend/src/components/ThemeSelector.tsx
index 6e7d44fe5..40fec1412 100644
--- a/frontend/src/components/ThemeSelector.tsx
+++ b/frontend/src/components/ThemeSelector.tsx
@@ -150,7 +150,7 @@ export function ThemeSelectorDialog({ open, onClose }: ThemeSelectorDialogProps)
 //
 
 interface ThemePreviewProps {
-  theme: { primary: { main: string }; secondary: { main: string }; mode: "light" | "dark" };
+  theme: { primary: { main: string }; mode: "light" | "dark" };
 }
 
 /**
diff --git a/frontend/src/components/Viewer/CodeMirrorFindReplacePopover.tsx b/frontend/src/components/Viewer/CodeMirrorFindReplacePopover.tsx
index ee3428341..8fe7a517f 100644
--- a/frontend/src/components/Viewer/CodeMirrorFindReplacePopover.tsx
+++ b/frontend/src/components/Viewer/CodeMirrorFindReplacePopover.tsx
@@ -41,12 +41,14 @@ export interface CodeMirrorFindReplacePopoverProps {
   regex: boolean;
   replaceText: string;
   searchMatches: number;
+  searchPending?: boolean;
+  searchError?: string;
   searchText: string;
   wholeWord: boolean;
 }
 
 function navigateHistory(
-  event: ReactKeyboardEvent<HTMLInputElement>,
+  event: ReactKeyboardEvent<HTMLElement>,
   history: string[],
   historyIndexRef: MutableRefObject<number | null>,
   historyDraftRef: MutableRefObject<string>,
@@ -75,11 +77,14 @@ function navigateHistory(
 
   if (event.key === "ArrowUp") {
     const nextHistoryIndex = historyIndex === null ? 0 : Math.min(historyIndex + 1, history.length - 1);
+    const entry = history[nextHistoryIndex];
+    if (entry === undefined) return;
     historyIndexRef.current = nextHistoryIndex;
-    onValueChange(history[nextHistoryIndex]);
+    onValueChange(entry);
     return;
   }
 
+  if (historyIndex === null) return;
   const nextHistoryIndex = historyIndex - 1;
   if (nextHistoryIndex < 0) {
     historyIndexRef.current = null;
@@ -87,8 +92,10 @@ function navigateHistory(
     return;
   }
 
+  const entry = history[nextHistoryIndex];
+  if (entry === undefined) return;
   historyIndexRef.current = nextHistoryIndex;
-  onValueChange(history[nextHistoryIndex]);
+  onValueChange(entry);
 }
 
 export function CodeMirrorFindReplacePopover({
@@ -113,6 +120,8 @@ export function CodeMirrorFindReplacePopover({
   regex,
   replaceText,
   searchMatches,
+  searchPending = false,
+  searchError,
   searchText,
   wholeWord,
 }: CodeMirrorFindReplacePopoverProps) {
@@ -126,7 +135,8 @@ export function CodeMirrorFindReplacePopover({
   const [findHistory, setFindHistory] = useState(() => readCodeMirrorFindReplaceHistory(CODEMIRROR_FIND_HISTORY_STORAGE_KEY));
   const [replaceHistory, setReplaceHistory] = useState(() => readCodeMirrorFindReplaceHistory(CODEMIRROR_REPLACE_HISTORY_STORAGE_KEY));
   const hasMatches = isSearchValid && searchMatches > 0;
-  const replaceDisabled = disabled || !hasMatches;
+  const canNavigate = hasMatches || (isSearchValid && regex && Boolean(searchText) && (searchPending || Boolean(searchError)));
+  const replaceDisabled = disabled || searchPending || Boolean(searchError) || !hasMatches;
   const dialogSurfaces = getOverlaySurfaceTokens(theme.palette.background.default, theme.palette.mode);
 
   useEffect(() => {
@@ -226,10 +236,10 @@ export function CodeMirrorFindReplacePopover({
     const lastFocusableElementIndex = focusableElements.length - 1;
     if (!event.shiftKey && activeElementIndex === lastFocusableElementIndex) {
       event.preventDefault();
-      focusableElements[0].focus();
+      focusableElements[0]?.focus();
     } else if (event.shiftKey && activeElementIndex === 0) {
       event.preventDefault();
-      focusableElements[lastFocusableElementIndex].focus();
+      focusableElements[lastFocusableElementIndex]?.focus();
     }
   };
 
@@ -266,6 +276,11 @@ export function CodeMirrorFindReplacePopover({
           zIndex: (currentTheme) => currentTheme.zIndex.modal + 1,
         }}
       >
+        {searchError && (
+          <Typography color="error" role="alert" sx={{ fontSize: "0.875rem", overflowWrap: "anywhere" }}>
+            {searchError}
+          </Typography>
+        )}
         <Box
           sx={{
             alignItems: "center",
@@ -307,10 +322,16 @@ export function CodeMirrorFindReplacePopover({
                   <InputAdornment position="end">
                     <Typography
                       aria-live="polite"
-                      color={hasMatches ? "text.secondary" : "error"}
+                      color={hasMatches || searchPending ? "text.secondary" : "error"}
                       sx={{ fontSize: "0.875rem", fontVariantNumeric: "tabular-nums", whiteSpace: "nowrap" }}
                     >
-                      {isSearchValid ? `${currentMatch} / ${searchMatches}` : t("viewer.edit.invalidRegularExpression")}
+                      {searchPending
+                        ? t("app.loading")
+                        : searchError
+                          ? "?"
+                          : isSearchValid
+                            ? `${currentMatch} / ${searchMatches}`
+                            : t("viewer.edit.invalidRegularExpression")}
                     </Typography>
                   </InputAdornment>
                 ),
@@ -412,7 +433,7 @@ export function CodeMirrorFindReplacePopover({
                 <span>
                   <IconButton
                     aria-label={t("viewer.edit.previousMatch")}
-                    disabled={disabled || !hasMatches}
+                    disabled={disabled || !canNavigate}
                     onClick={handleFindPrevious}
                     size="small"
                     sx={{ height: 30, p: 0.25, width: 26 }}
@@ -425,7 +446,7 @@ export function CodeMirrorFindReplacePopover({
                 <span>
                   <IconButton
                     aria-label={t("viewer.edit.nextMatch")}
-                    disabled={disabled || !hasMatches}
+                    disabled={disabled || !canNavigate}
                     onClick={handleFindNext}
                     size="small"
                     sx={{ height: 30, p: 0.25, width: 26 }}
diff --git a/frontend/src/components/Viewer/MarkdownEditorErrorBoundary.tsx b/frontend/src/components/Viewer/MarkdownEditorErrorBoundary.tsx
index bbe58ca4d..49a33942b 100644
--- a/frontend/src/components/Viewer/MarkdownEditorErrorBoundary.tsx
+++ b/frontend/src/components/Viewer/MarkdownEditorErrorBoundary.tsx
@@ -43,7 +43,7 @@ class MarkdownEditorErrorBoundary extends Component<MarkdownEditorErrorBoundaryP
     return (
       <Box sx={{ display: "flex", flexDirection: "column", gap: 2, py: 2 }}>
         <Alert severity="error">
-          <Typography variant="subtitle1" fontWeight={600} gutterBottom>
+          <Typography variant="subtitle1" gutterBottom sx={{ fontWeight: 600 }}>
             {this.props.title}
           </Typography>
           <Typography variant="body2">{this.props.description}</Typography>
diff --git a/frontend/src/components/Viewer/MarkdownRichEditor.tsx b/frontend/src/components/Viewer/MarkdownRichEditor.tsx
index 2c5291178..2d01f712d 100644
--- a/frontend/src/components/Viewer/MarkdownRichEditor.tsx
+++ b/frontend/src/components/Viewer/MarkdownRichEditor.tsx
@@ -1,29 +1,39 @@
-import { findNext, findPrevious, replaceAll, replaceNext } from "@codemirror/search";
-import { EditorSelection } from "@codemirror/state";
-import type { ViewUpdate } from "@codemirror/view";
+import { EditorSelection, type EditorState } from "@codemirror/state";
+import { EditorView, type ViewUpdate } from "@codemirror/view";
 import { insertEmptyMarkdownTable } from "codemirror-markdown-tables";
-import { forwardRef, useCallback, useEffect, useImperativeHandle, useMemo, useRef, useState } from "react";
+import { forwardRef, useCallback, useEffect, useImperativeHandle, useLayoutEffect, useMemo, useRef, useState } from "react";
+import { DRAFT_TRANSITION_FLUSH_MS } from "../../services/draftCheckpoint";
+import { error as logError } from "../../services/logger";
+import { createMarkdownEditNormalization } from "../../utils/markdownCodePreparation";
 import { buildMarkdownEditorExtensions } from "../Editor/buildMarkdownEditorExtensions";
 import type { MarkdownEditorThemeOptions } from "../Editor/buildMarkdownEditorTheme";
 import { SourceTextEditor } from "../Editor/SourceTextEditor";
-import type { SourceTextEditorHandle } from "../Editor/sourceTextEditorTypes";
+import type { SourceTextEditorHandle, SourceTextSnapshot } from "../Editor/sourceTextEditorTypes";
 import {
+  findNext,
+  findPrevious,
   getCodeMirrorFindReplaceMetrics,
+  replaceAll,
+  replaceNext,
   shouldAutoNavigateCodeMirrorFindReplace,
   updateCodeMirrorFindReplaceQuery,
 } from "./codeMirrorFindReplace";
-import {
-  normalizeMarkdownTableCellLineBreaks,
-  prepareMarkdownTableCellLineBreaksForEditor,
-  preserveUnchangedMarkdownTableSource,
-} from "./markdownTableCellLineBreaks";
+import { needsMarkdownTableSourceComparison, prepareMarkdownTableCellLineBreaksForEditor } from "./markdownTableCellLineBreaks";
 
 const insertDefaultMarkdownTable = insertEmptyMarkdownTable({
   size: { rows: 2, cols: 2 },
 });
+const SNAPSHOT_FLUSH_MEASURE = "sambee:edit-preparation:snapshot-flush";
+
+export const MARKDOWN_SOURCE_MEASURES = {
+  normalize: "sambee:source-editor:normalize",
+  parentUpdate: "sambee:source-editor:parent-update",
+} as const;
 
 export interface MarkdownRichEditorHandle {
   focus: () => void;
+  captureSnapshot: (signal?: AbortSignal) => Promise<SourceTextSnapshot>;
+  captureSnapshotSync: () => SourceTextSnapshot;
   flushPendingEdits: () => Promise<void>;
   getCanonicalMarkdown: () => string;
   getPrimarySelectionText: () => string;
@@ -44,6 +54,8 @@ export interface MarkdownRichEditorHandle {
 }
 
 export interface MarkdownRichEditorSearchState {
+  pending?: boolean;
+  error?: string;
   searchText: string;
   searchMatches: number;
   currentMatch: number;
@@ -58,6 +70,7 @@ export interface MarkdownRichEditorProps {
   diffMarkdown?: string;
   onChange: (markdown: string) => void;
   onUserEdit?: (viewUpdate?: ViewUpdate) => void;
+  onNormalizationStateChange?: (pending: boolean, error?: Error) => void;
   ariaLabel: string;
   theme: MarkdownEditorThemeOptions;
   autoFocus?: boolean;
@@ -81,12 +94,21 @@ interface NestedPublicationState {
   resolvePending: (() => void) | null;
 }
 
-function normalizeTableCellBreaksIfNeeded(markdown: string): string {
-  return markdown.includes("<br") ? normalizeMarkdownTableCellLineBreaks(markdown) : markdown;
+interface NestedInput {
+  view: EditorView | null;
+  state: EditorState | null;
+  generation: number;
+  hadPendingPublication: boolean;
+  clipboardEvent: "paste" | "cut" | null;
 }
 
-function getCurrentDoc(editorRef: React.RefObject<SourceTextEditorHandle | null>, previousMarkdown: string): string {
-  return preserveUnchangedMarkdownTableSource(previousMarkdown, normalizeTableCellBreaksIfNeeded(editorRef.current?.getValue() ?? ""));
+interface NestedComposition {
+  view: EditorView;
+  doc: EditorState["doc"];
+  generation: number;
+  acknowledged: boolean;
+  data: string | null;
+  acknowledgedInput?: { doc: EditorState["doc"]; generation: number; data: string | null };
 }
 
 function getEventTargetElement(target: EventTarget | null): Element | null {
@@ -247,6 +269,7 @@ const MarkdownRichEditor = forwardRef<MarkdownRichEditorHandle, MarkdownRichEdit
       diffMarkdown,
       onChange,
       onUserEdit,
+      onNormalizationStateChange,
       ariaLabel,
       theme,
       autoFocus = false,
@@ -279,22 +302,59 @@ const MarkdownRichEditor = forwardRef<MarkdownRichEditorHandle, MarkdownRichEdit
       pendingPromise: null,
       resolvePending: null,
     });
-    const extensions = useMemo(() => buildMarkdownEditorExtensions(theme, lineWrapping), [lineWrapping, theme]);
+    const nestedInputRef = useRef<NestedInput | null>(null);
+    const nestedCompositionRef = useRef<NestedComposition | null>(null);
+    const preservedNestedSelectionRef = useRef<{
+      view: EditorView;
+      state: EditorState;
+      scrollTop: number;
+      scrollLeft: number;
+    } | null>(null);
     const [editorMarkdown, setEditorMarkdown] = useState(() => prepareMarkdownTableCellLineBreaksForEditor(markdown));
-
-    useEffect(() => {
+    const normalizationRef = useRef<ReturnType<typeof createMarkdownEditNormalization> | null>(null);
+    const normalizationEpochRef = useRef(0);
+    const normalizationFailureRef = useRef<Error | null>(null);
+    const normalizationRequestRef = useRef<{ baseline: string; preserveOnly: boolean } | null>(null);
+    const canonicalRef = useRef({ source: editorMarkdown, markdown });
+    const callbacksRef = useRef({ onChange, onNormalizationStateChange, baseline: diffMarkdown ?? markdown });
+
+    useLayoutEffect(() => {
+      callbacksRef.current = { onChange, onNormalizationStateChange, baseline: diffMarkdown ?? markdown };
+    }, [diffMarkdown, markdown, onChange, onNormalizationStateChange]);
+
+    useLayoutEffect(() => {
       if (markdown === lastPublishedCanonicalMarkdownRef.current) {
         return;
       }
 
-      setEditorMarkdown(prepareMarkdownTableCellLineBreaksForEditor(markdown));
+      normalizationRef.current?.dispose();
+      normalizationEpochRef.current += 1;
+      normalizationRef.current = null;
+      normalizationFailureRef.current = null;
+      normalizationRequestRef.current = null;
+      preservedNestedSelectionRef.current = null;
+      const source = prepareMarkdownTableCellLineBreaksForEditor(markdown);
+      canonicalRef.current = { source, markdown };
+      setEditorMarkdown(source);
       lastPublishedCanonicalMarkdownRef.current = null;
+      callbacksRef.current.onNormalizationStateChange?.(false);
     }, [markdown]);
 
+    useLayoutEffect(
+      () => () => {
+        normalizationEpochRef.current += 1;
+        normalizationRef.current?.dispose();
+        normalizationRef.current = null;
+        preservedNestedSelectionRef.current = null;
+      },
+      []
+    );
+
     const markNestedPublicationPending = useCallback(() => {
       const publicationState = nestedPublicationStateRef.current;
 
       publicationState.observedGeneration += 1;
+      callbacksRef.current.onNormalizationStateChange?.(true);
 
       if (publicationState.pendingPromise) {
         return;
@@ -307,37 +367,151 @@ const MarkdownRichEditor = forwardRef<MarkdownRichEditorHandle, MarkdownRichEdit
 
     const resolveNestedPublication = useCallback(() => {
       const publicationState = nestedPublicationStateRef.current;
+      const composition = nestedCompositionRef.current;
+      if (composition && composition.generation === publicationState.observedGeneration && composition.doc === composition.view.state.doc) {
+        composition.acknowledged = true;
+        composition.acknowledgedInput = { doc: composition.doc, generation: composition.generation, data: composition.data };
+      }
 
       if (publicationState.observedGeneration <= publicationState.publishedGeneration) {
         return;
       }
 
       publicationState.publishedGeneration = publicationState.observedGeneration;
+      nestedInputRef.current = null;
       const resolvePending = publicationState.resolvePending;
       publicationState.pendingPromise = null;
       publicationState.resolvePending = null;
       resolvePending?.();
+      if (!normalizationRef.current && canonicalRef.current.source === editorRef.current?.getValue()) {
+        callbacksRef.current.onNormalizationStateChange?.(false);
+      }
     }, []);
 
-    const flushNestedPublication = useCallback(async () => {
+    const handleNestedUpdate = useCallback(
+      (update: ViewUpdate) => {
+        if (!update.docChanged) return;
+        const input = nestedInputRef.current;
+        const publication = nestedPublicationStateRef.current;
+        const composition = nestedCompositionRef.current;
+        if (composition?.view === update.view) {
+          composition.doc = update.state.doc;
+          composition.generation = publication.observedGeneration;
+          composition.acknowledged = false;
+        }
+        if (
+          input?.view === update.view &&
+          input.generation === publication.observedGeneration &&
+          !input.hadPendingPublication &&
+          update.startState.doc.toString().trim() === update.state.doc.toString().trim()
+        ) {
+          resolveNestedPublication();
+        }
+      },
+      [resolveNestedPublication]
+    );
+    const extensions = useMemo(
+      () => buildMarkdownEditorExtensions(theme, lineWrapping, handleNestedUpdate),
+      [handleNestedUpdate, lineWrapping, theme]
+    );
+
+    const flushNestedPublication = useCallback(async (signal?: AbortSignal) => {
       const publicationState = nestedPublicationStateRef.current;
 
-      if (publicationState.observedGeneration <= publicationState.publishedGeneration) {
-        return;
+      while (publicationState.observedGeneration > publicationState.publishedGeneration) {
+        signal?.throwIfAborted();
+        const pending = publicationState.pendingPromise;
+        if (!pending) throw new Error("Nested Markdown publication is pending without a completion signal");
+        if (!signal) {
+          await pending;
+          continue;
+        }
+        await new Promise<void>((resolve, reject) => {
+          const abort = () => {
+            signal.removeEventListener("abort", abort);
+            reject(signal.reason);
+          };
+          signal.addEventListener("abort", abort, { once: true });
+          void pending.then(() => {
+            signal.removeEventListener("abort", abort);
+            resolve();
+          });
+        });
       }
+      signal?.throwIfAborted();
+    }, []);
 
-      await publicationState.pendingPromise;
+    const publishCanonical = useCallback((source: string, canonicalMarkdown: string) => {
+      canonicalRef.current = { source, markdown: canonicalMarkdown };
+      lastPublishedCanonicalMarkdownRef.current = canonicalMarkdown;
+      const parentUpdateStart = performance.now();
+      callbacksRef.current.onChange(canonicalMarkdown);
+      callbacksRef.current.onNormalizationStateChange?.(
+        nestedPublicationStateRef.current.observedGeneration > nestedPublicationStateRef.current.publishedGeneration
+      );
+      performance.clearMeasures(MARKDOWN_SOURCE_MEASURES.parentUpdate);
+      performance.measure(MARKDOWN_SOURCE_MEASURES.parentUpdate, {
+        start: parentUpdateStart,
+        detail: { documentUnits: source.length, canonicalUnits: canonicalMarkdown.length },
+      });
     }, []);
 
+    const requestNormalization = useCallback(
+      (source: string, preserveOnly = false) => {
+        normalizationFailureRef.current = null;
+        callbacksRef.current.onNormalizationStateChange?.(true);
+        if (!normalizationRef.current) {
+          normalizationRef.current = createMarkdownEditNormalization(
+            (diagnostic) => logError(diagnostic.message, diagnostic.context, diagnostic.component),
+            (snapshot) => publishCanonical(snapshot.source, snapshot.normalizedSource),
+            (error) => {
+              normalizationFailureRef.current = error;
+              callbacksRef.current.onNormalizationStateChange?.(true, error);
+              logError("Markdown edit normalization failed; keep the editor open and retry saving", { error }, "MarkdownRichEditor");
+            }
+          );
+        }
+        const baseline = callbacksRef.current.baseline;
+        normalizationRequestRef.current = { baseline, preserveOnly };
+        normalizationRef.current.request(source, baseline, preserveOnly);
+      },
+      [publishCanonical]
+    );
+
+    useLayoutEffect(() => {
+      const baseline = diffMarkdown ?? markdown;
+      const source = editorRef.current?.getValue();
+      if (
+        source !== undefined &&
+        needsMarkdownTableSourceComparison(baseline, canonicalRef.current.markdown) &&
+        normalizationRequestRef.current?.baseline !== baseline
+      ) {
+        requestNormalization(source, normalizationRequestRef.current?.preserveOnly ?? true);
+      }
+    }, [diffMarkdown, markdown, requestNormalization]);
+
     const handleChange = useCallback(
       (nextValue: string) => {
         resolveNestedPublication();
         setEditorMarkdown(nextValue);
-        const canonicalMarkdown = normalizeTableCellBreaksIfNeeded(nextValue);
-        lastPublishedCanonicalMarkdownRef.current = canonicalMarkdown;
-        onChange(canonicalMarkdown);
+        const normalizationStart = performance.now();
+        if (nextValue.includes("<br")) {
+          requestNormalization(nextValue);
+        } else if (needsMarkdownTableSourceComparison(callbacksRef.current.baseline, nextValue)) {
+          publishCanonical(nextValue, nextValue);
+          requestNormalization(nextValue, true);
+        } else {
+          normalizationRef.current?.dispose();
+          normalizationRef.current = null;
+          normalizationFailureRef.current = null;
+          normalizationRequestRef.current = null;
+          publishCanonical(nextValue, nextValue);
+        }
+        const detail = { documentUnits: nextValue.length, canonicalUnits: nextValue.includes("<br") ? null : nextValue.length };
+        performance.clearMeasures(MARKDOWN_SOURCE_MEASURES.normalize);
+        performance.measure(MARKDOWN_SOURCE_MEASURES.normalize, { start: normalizationStart, detail });
       },
-      [onChange, resolveNestedPublication]
+      [publishCanonical, requestNormalization, resolveNestedPublication]
     );
 
     const reportSearchState = useCallback(() => {
@@ -347,6 +521,8 @@ const MarkdownRichEditor = forwardRef<MarkdownRichEditorHandle, MarkdownRichEdit
 
       const metrics = getCodeMirrorFindReplaceMetrics(editorRef.current?.getView());
       onSearchStateChange({
+        pending: metrics.pending,
+        error: metrics.error,
         searchText: searchOpen ? searchText : "",
         searchMatches: searchOpen ? metrics.matches : 0,
         currentMatch: searchOpen ? metrics.currentMatch : 0,
@@ -406,6 +582,16 @@ const MarkdownRichEditor = forwardRef<MarkdownRichEditorHandle, MarkdownRichEdit
       searchWholeWord,
     ]);
 
+    const preserveNestedSelection = useCallback((target: EventTarget | null) => {
+      const root = editorRef.current?.getView();
+      if (!root || !(target instanceof HTMLElement) || !root.dom.contains(target)) return;
+      const nested = EditorView.findFromDOM(target);
+      preservedNestedSelectionRef.current =
+        nested && nested !== root
+          ? { view: nested, state: nested.state, scrollTop: root.scrollDOM.scrollTop, scrollLeft: root.scrollDOM.scrollLeft }
+          : null;
+    }, []);
+
     useEffect(() => {
       const rootView = editorRef.current?.getView();
 
@@ -413,32 +599,204 @@ const MarkdownRichEditor = forwardRef<MarkdownRichEditorHandle, MarkdownRichEdit
         return;
       }
 
+      const handleEditorFocus = (event: FocusEvent) => preserveNestedSelection(event.target);
       const handlePotentialNestedEdit = (event: Event) => {
         const targetElement = getEventTargetElement(event.target);
 
-        if (!targetElement || !rootView.dom.contains(targetElement) || !targetElement.closest(".tbl-cell-editor")) {
+        if (
+          !(targetElement instanceof HTMLElement) ||
+          !rootView.dom.contains(targetElement) ||
+          !targetElement.closest(".tbl-cell-editor")
+        ) {
           return;
         }
 
+        const publication = nestedPublicationStateRef.current;
+        const view = EditorView.findFromDOM(targetElement);
+        const composition = nestedCompositionRef.current;
+        if (event.type === "compositionstart" && view && view !== rootView) {
+          nestedCompositionRef.current = {
+            view,
+            doc: view.state.doc,
+            generation: publication.observedGeneration,
+            acknowledged: publication.observedGeneration === publication.publishedGeneration,
+            data: "",
+          };
+          return;
+        }
+        if (event instanceof CompositionEvent && event.type === "compositionend") {
+          nestedCompositionRef.current = null;
+          const acknowledged = composition?.acknowledgedInput;
+          const input = nestedInputRef.current;
+          if (
+            composition &&
+            view &&
+            acknowledged &&
+            input &&
+            composition.view === view &&
+            acknowledged.doc === view.state.doc &&
+            acknowledged.data === event.data &&
+            acknowledged.generation === publication.publishedGeneration &&
+            input.view === view &&
+            input.state?.doc === acknowledged.doc &&
+            input.generation === publication.observedGeneration &&
+            !input.hadPendingPublication &&
+            Array.from(view.contentDOM.querySelectorAll(".cm-line"), (line) => line.textContent ?? "").join("\n") ===
+              view.state.doc.toString()
+          ) {
+            resolveNestedPublication();
+            return;
+          }
+          if (
+            composition?.view === view &&
+            composition.acknowledged &&
+            composition.doc === view?.state.doc &&
+            composition.data === event.data &&
+            composition.generation === publication.publishedGeneration &&
+            publication.observedGeneration === publication.publishedGeneration
+          ) {
+            return;
+          }
+        }
+        const previousInput = nestedInputRef.current;
+        if (
+          event instanceof InputEvent &&
+          !event.isComposing &&
+          view &&
+          view !== rootView &&
+          previousInput?.view === view &&
+          previousInput.generation === publication.observedGeneration &&
+          previousInput.state?.doc === view.state.doc &&
+          ((previousInput.clipboardEvent === "paste" && event.inputType === "insertFromPaste") ||
+            (previousInput.clipboardEvent === "cut" && event.inputType === "deleteByCut"))
+        ) {
+          previousInput.clipboardEvent = null;
+          return;
+        }
+        const hadPendingPublication = publication.observedGeneration > publication.publishedGeneration;
         markNestedPublicationPending();
+        if (event instanceof InputEvent && event.isComposing && composition?.view === view) {
+          composition.data = event.data;
+          composition.generation = publication.observedGeneration;
+          composition.acknowledged = false;
+        }
+        nestedInputRef.current = {
+          view,
+          state: view?.state ?? null,
+          generation: publication.observedGeneration,
+          hadPendingPublication,
+          clipboardEvent: event.type === "paste" || event.type === "cut" ? event.type : null,
+        };
       };
 
+      rootView.dom.addEventListener("focusin", handleEditorFocus, true);
+      rootView.dom.addEventListener("focusout", handleEditorFocus, true);
       rootView.dom.addEventListener("beforeinput", handlePotentialNestedEdit, true);
+      rootView.dom.addEventListener("compositionstart", handlePotentialNestedEdit, true);
       rootView.dom.addEventListener("compositionend", handlePotentialNestedEdit, true);
       rootView.dom.addEventListener("paste", handlePotentialNestedEdit, true);
       rootView.dom.addEventListener("cut", handlePotentialNestedEdit, true);
 
       return () => {
+        rootView.dom.removeEventListener("focusin", handleEditorFocus, true);
+        rootView.dom.removeEventListener("focusout", handleEditorFocus, true);
         rootView.dom.removeEventListener("beforeinput", handlePotentialNestedEdit, true);
+        rootView.dom.removeEventListener("compositionstart", handlePotentialNestedEdit, true);
         rootView.dom.removeEventListener("compositionend", handlePotentialNestedEdit, true);
         rootView.dom.removeEventListener("paste", handlePotentialNestedEdit, true);
         rootView.dom.removeEventListener("cut", handlePotentialNestedEdit, true);
+        nestedInputRef.current = null;
+        nestedCompositionRef.current = null;
         nestedPublicationStateRef.current.resolvePending?.();
         nestedPublicationStateRef.current.pendingPromise = null;
         nestedPublicationStateRef.current.resolvePending = null;
         nestedPublicationStateRef.current.publishedGeneration = nestedPublicationStateRef.current.observedGeneration;
       };
-    }, [markNestedPublicationPending]);
+    }, [markNestedPublicationPending, preserveNestedSelection, resolveNestedPublication]);
+
+    const getCanonicalMarkdown = useCallback(() => {
+      const source = editorRef.current?.getValue();
+      if (source === undefined) throw new Error("Cannot read Markdown after the editor is disposed");
+      const prepared = normalizationRef.current?.captureSnapshotSync();
+      if (canonicalRef.current.source !== source) {
+        throw new DOMException(
+          "Markdown normalization has not finished publishing. Retry after the current edit finishes.",
+          "InvalidStateError"
+        );
+      }
+      if (
+        needsMarkdownTableSourceComparison(callbacksRef.current.baseline, canonicalRef.current.markdown) &&
+        prepared?.baseline !== callbacksRef.current.baseline
+      ) {
+        throw new DOMException(
+          "Markdown source preservation has not finished publishing. Retry after the current edit finishes.",
+          "InvalidStateError"
+        );
+      }
+      return canonicalRef.current.markdown;
+    }, []);
+
+    const flushPendingEdits = useCallback(
+      async (signal?: AbortSignal) => {
+        const epoch = normalizationEpochRef.current;
+        const assertCurrentDocument = () => {
+          if (!editorRef.current) throw new Error("Cannot capture a snapshot after the Markdown editor is disposed");
+          if (normalizationEpochRef.current !== epoch) {
+            throw new DOMException("Markdown document changed while its snapshot was being prepared", "AbortError");
+          }
+        };
+        if (normalizationFailureRef.current) {
+          const source = editorRef.current?.getValue();
+          if (source === undefined) throw new Error("Cannot retry normalization after the Markdown editor is disposed");
+          requestNormalization(source);
+        }
+        do {
+          await flushNestedPublication(signal);
+          assertCurrentDocument();
+          if (
+            !normalizationRef.current ||
+            normalizationRequestRef.current?.preserveOnly ||
+            normalizationRequestRef.current?.baseline !== callbacksRef.current.baseline
+          ) {
+            const source = editorRef.current?.getValue();
+            if (source === undefined) throw new Error("Cannot normalize Markdown after the editor is disposed");
+            requestNormalization(source);
+          }
+          const normalization = normalizationRef.current;
+          try {
+            await normalization?.flush(signal);
+          } catch (error) {
+            signal?.throwIfAborted();
+            assertCurrentDocument();
+            if (normalization !== normalizationRef.current && editorRef.current) continue;
+            throw error;
+          }
+          signal?.throwIfAborted();
+          assertCurrentDocument();
+        } while (
+          !normalizationRef.current ||
+          normalizationRequestRef.current?.preserveOnly ||
+          normalizationRequestRef.current?.baseline !== callbacksRef.current.baseline ||
+          nestedPublicationStateRef.current.observedGeneration > nestedPublicationStateRef.current.publishedGeneration
+        );
+      },
+      [flushNestedPublication, requestNormalization]
+    );
+
+    const captureSnapshotSync = useCallback((): SourceTextSnapshot => {
+      const publication = nestedPublicationStateRef.current;
+      if (publication.observedGeneration > publication.publishedGeneration) {
+        throw new DOMException("Markdown edits have not finished publishing. Retry after the current edit finishes.", "InvalidStateError");
+      }
+      const editor = editorRef.current;
+      if (!editor) throw new Error("Cannot capture a snapshot after the Markdown editor is disposed");
+      const snapshot = editor.captureSnapshot();
+      const canonicalMarkdown = getCanonicalMarkdown();
+      return Object.freeze({
+        revision: snapshot.revision,
+        serialize: () => canonicalMarkdown,
+      });
+    }, [getCanonicalMarkdown]);
 
     useImperativeHandle(
       ref,
@@ -446,13 +804,50 @@ const MarkdownRichEditor = forwardRef<MarkdownRichEditorHandle, MarkdownRichEdit
         focus: () => {
           editorRef.current?.focus();
         },
-        flushPendingEdits: flushNestedPublication,
-        getCanonicalMarkdown: () => getCurrentDoc(editorRef, diffMarkdown ?? markdown),
+        captureSnapshot: async (signal) => {
+          const startedAt = performance.now();
+          const deadline = new AbortController();
+          const timeout = window.setTimeout(() => {
+            deadline.abort(
+              new DOMException("Markdown edits have not finished publishing. Retry saving after the current edit finishes.", "TimeoutError")
+            );
+          }, DRAFT_TRANSITION_FLUSH_MS);
+          const flushSignal = signal ? AbortSignal.any([signal, deadline.signal]) : deadline.signal;
+          try {
+            await flushPendingEdits(flushSignal);
+            flushSignal.throwIfAborted();
+            return captureSnapshotSync();
+          } finally {
+            window.clearTimeout(timeout);
+            performance.clearMeasures(SNAPSHOT_FLUSH_MEASURE);
+            performance.measure(SNAPSHOT_FLUSH_MEASURE, { start: startedAt, detail: { documentEpoch: normalizationEpochRef.current } });
+          }
+        },
+        captureSnapshotSync,
+        flushPendingEdits,
+        getCanonicalMarkdown,
         getPrimarySelectionText: () => editorRef.current?.getPrimarySelectionText() ?? "",
         preserveSelection: () => {
           editorRef.current?.preserveSelection();
+          const root = editorRef.current?.getView();
+          preserveNestedSelection(root?.root.activeElement ?? null);
+        },
+        restorePreservedSelection: () => {
+          const root = editorRef.current?.getView();
+          const preserved = preservedNestedSelectionRef.current;
+          if (root && preserved?.view.dom.isConnected && root.dom.contains(preserved.view.dom)) {
+            const nested = preserved.view;
+            if (nested.hasFocus) return true;
+            if (nested.state.doc === preserved.state.doc && !nested.state.selection.eq(preserved.state.selection)) {
+              nested.dispatch({ selection: preserved.state.selection, scrollIntoView: false });
+            }
+            nested.focus();
+            root.scrollDOM.scrollTop = preserved.scrollTop;
+            root.scrollDOM.scrollLeft = preserved.scrollLeft;
+            return nested.hasFocus;
+          }
+          return editorRef.current?.restorePreservedSelection() ?? false;
         },
-        restorePreservedSelection: () => editorRef.current?.restorePreservedSelection() ?? false,
         focusCurrentSearchResult: () => {
           const view = editorRef.current?.getView();
 
@@ -510,7 +905,7 @@ const MarkdownRichEditor = forwardRef<MarkdownRichEditorHandle, MarkdownRichEdit
           reportSearchState();
         },
       }),
-      [diffMarkdown, flushNestedPublication, markdown, reportSearchState]
+      [captureSnapshotSync, flushPendingEdits, getCanonicalMarkdown, preserveNestedSelection, reportSearchState]
     );
 
     return (
diff --git a/frontend/src/components/Viewer/MarkdownViewer.tsx b/frontend/src/components/Viewer/MarkdownViewer.tsx
index 6e40149b0..de7fedaa3 100644
--- a/frontend/src/components/Viewer/MarkdownViewer.tsx
+++ b/frontend/src/components/Viewer/MarkdownViewer.tsx
@@ -1,18 +1,20 @@
-import { Alert, Box, Button, CircularProgress, Dialog, useMediaQuery, useTheme } from "@mui/material";
+import { Alert, Box, Button, CircularProgress, Dialog, GlobalStyles, useMediaQuery, useTheme } from "@mui/material";
+import type { Root as MarkdownRoot } from "mdast";
 import {
+  createRef,
   type ErrorInfo,
   type ForwardRefExoticComponent,
   memo,
   type RefAttributes,
+  type RefObject,
   useCallback,
   useEffect,
+  useLayoutEffect,
   useMemo,
   useRef,
   useState,
 } from "react";
 import { useTranslation } from "react-i18next";
-import ReactMarkdown from "react-markdown";
-import rehypeHighlight from "rehype-highlight";
 import remarkGfm from "remark-gfm";
 import {
   BROWSER_SHORTCUTS,
@@ -37,28 +39,35 @@ import { clearDraft, type DraftSnapshot, loadDraft, registerDraftSnapshot, saveD
 import { error as logError, info as logInfo } from "../../services/logger";
 import { useSambeeTheme } from "../../theme";
 import { getSearchHighlightColors } from "../../theme/commonStyles";
+import { getSyntaxVariables } from "../../theme/syntaxStyles";
 import {
   CODEMIRROR_EDITOR_CONTENT_PADDING,
   CODEMIRROR_EDITOR_HORIZONTAL_INSET_CSS_VARIABLE,
   getMarkdownContentStyles,
   getMarkdownTableSurfaceColors,
   getViewerColors,
+  MARKDOWN_VIEWER_PRINT_STYLES,
   VIEWER_SCROLL_END_PADDING,
 } from "../../theme/viewerStyles";
 import { isApiError } from "../../types";
 import { getApiErrorMessage } from "../../utils/apiErrors";
-import {
-  activateDomTextSearchMatch,
-  applyDomTextSearchHighlights,
-  clearDomTextSearchHighlights,
-  DOM_TEXT_SEARCH_CURRENT_MATCH_ATTRIBUTE,
-  DOM_TEXT_SEARCH_HIGHLIGHT_SELECTOR,
-  type DomTextSearchMatch,
-} from "../../utils/domTextSearch";
 import { openExternalUrl } from "../../utils/externalLinks";
 import type { ViewerComponentProps } from "../../utils/FileTypeRegistry";
 import { blurActiveToolbarControl } from "../../utils/keyboardUtils";
+import { normalizeMarkdownSource } from "../../utils/markdownCodePreparation";
+import { rehypeMarkdownHeadingLinks } from "../../utils/markdownHeadingLinks";
+import { remarkPreparedMarkdownTree } from "../../utils/markdownPreparedTree";
+import {
+  recordMarkdownPreparation,
+  rehypeMeasureMarkdownPreparation,
+  remarkCollectMarkdownCodeBlocks,
+  remarkMeasureMarkdownPreparation,
+} from "../../utils/markdownSyntax";
+import { publishMarkdownSyntax } from "../../utils/markdownSyntaxPublication";
+import { prepareMarkdownSyntax } from "../../utils/markdownSyntaxWorker";
 import { createShareFile, supportsNativeShare } from "../../utils/nativeShare";
+import type { CodeBlockRequest } from "../../utils/syntaxHighlighting";
+import { createViewportDomTextSearch } from "../../utils/viewportDomTextSearch";
 import { ResponsiveDialogShell } from "../Dialog/ResponsiveDialogShell";
 import { HelpMenu } from "../FileBrowser/HelpMenu";
 import { KeyboardShortcutsHelp } from "../KeyboardShortcutsHelp";
@@ -80,12 +89,12 @@ import {
 } from "./markdownEditorConstants";
 import { areMarkdownSearchStatesEqual } from "./markdownSearchState";
 import { normalizeMarkdownTableCellLineBreaks, remarkRenderMarkdownTableCellLineBreaks } from "./markdownTableCellLineBreaks";
+import { PROGRESSIVE_MARKDOWN_MIN_UNITS, ProgressiveMarkdown } from "./ProgressiveMarkdown";
 import { RecoveredDraftDialog } from "./RecoveredDraftDialog";
 import { useMarkdownEditSession } from "./useMarkdownEditSession";
 import { VIEWER_SEARCH_INPUT_ATTRIBUTE, ViewerControls, ViewerFilenameBadge } from "./ViewerControls";
 import { downloadViewerBlob } from "./viewerContent";
-import { createEditToolbarAction, createSaveToolbarAction } from "./viewerToolbarActions";
-import "highlight.js/styles/github.css";
+import { createEditToolbarAction, createPrintToolbarAction, createSaveToolbarAction } from "./viewerToolbarActions";
 
 const MARKDOWN_SEARCH_ROOT_SELECTOR = '[data-markdown-search-root="true"]';
 const MARKDOWN_HASH_PREFIX = "#";
@@ -97,6 +106,90 @@ const MARKDOWN_VIEWER_EDIT_FOCUS_RETRY_DELAYS_MS = [
 
 type MarkdownRichEditorComponent = ForwardRefExoticComponent<MarkdownRichEditorProps & RefAttributes<MarkdownRichEditorHandle>>;
 
+interface MarkdownPreviewGeneration {
+  id: number;
+  source: string;
+  tree?: MarkdownRoot;
+  requests: RefObject<readonly CodeBlockRequest[] | null>;
+}
+
+const MarkdownPreview = memo(function MarkdownPreview({
+  generation,
+  onExternalLink,
+  onPending,
+  onReady,
+  onFailure,
+}: {
+  generation: MarkdownPreviewGeneration;
+  onExternalLink: () => void;
+  onPending: (generation: MarkdownPreviewGeneration) => void;
+  onReady: (generation: MarkdownPreviewGeneration) => void;
+  onFailure: (generation: MarkdownPreviewGeneration, error: unknown) => void;
+}) {
+  const content = generation.source;
+  const preparation = useMemo(() => ({ source: content, hastReady: 0, requests: [] as CodeBlockRequest[] }), [content]);
+  useLayoutEffect(() => {
+    generation.requests.current = preparation.requests;
+    if (preparation.source === content && preparation.hastReady)
+      recordMarkdownPreparation("hast-ready-to-layout-effect", preparation.hastReady);
+  }, [content, generation, preparation]);
+  return (
+    <ProgressiveMarkdown
+      onPending={() => onPending(generation)}
+      onReady={() => onReady(generation)}
+      onFailure={(error) => onFailure(generation, error)}
+      remarkPlugins={[
+        remarkGfm,
+        remarkMeasureMarkdownPreparation,
+        [remarkPreparedMarkdownTree, generation.tree],
+        [
+          remarkCollectMarkdownCodeBlocks,
+          (requests: CodeBlockRequest[]) => {
+            preparation.requests = requests;
+          },
+        ],
+        remarkRenderMarkdownTableCellLineBreaks,
+      ]}
+      rehypePlugins={[
+        rehypeMarkdownHeadingLinks,
+        [
+          rehypeMeasureMarkdownPreparation,
+          () => {
+            preparation.hastReady = performance.now();
+          },
+        ],
+      ]}
+      components={{
+        a: ({ href, node: _node, ...props }) => {
+          if (typeof href !== "string") return <a {...props} />;
+          const resolvedHref = resolveMarkdownLinkHref(href);
+          if (!resolvedHref) return <span>{props.children}</span>;
+          const opensNewTab = !resolvedHref.startsWith(MARKDOWN_HASH_PREFIX);
+          return (
+            <a
+              {...props}
+              href={resolvedHref}
+              rel={opensNewTab ? "noopener noreferrer" : undefined}
+              target={opensNewTab ? "_blank" : undefined}
+              onClick={
+                opensNewTab
+                  ? (event) => {
+                      event.preventDefault();
+                      openExternalUrl(resolvedHref);
+                      onExternalLink();
+                    }
+                  : undefined
+              }
+            />
+          );
+        },
+      }}
+    >
+      {content}
+    </ProgressiveMarkdown>
+  );
+});
+
 function resolveMarkdownLinkHref(href: string): string | null {
   const trimmedHref = href.trim();
 
@@ -204,12 +297,15 @@ export const MarkdownViewer: React.FC<ViewerComponentProps> = ({
   const contentProviders = useContentProviderRegistry();
   const { t } = useTranslation();
   const [content, setContent] = useState<string>("");
+  const [preparedPreview, setPreparedPreview] = useState<{ source: string; tree: MarkdownRoot } | null>(null);
   const [draftContent, setDraftContent] = useState<string>("");
   const [loading, setLoading] = useState(true);
   const [error, setError] = useState<string | null>(null);
   const [editError, setEditError] = useState<string | null>(null);
+  const [printError, setPrintError] = useState(false);
   const [shareRevision, setShareRevision] = useState(0);
   const [draftStorageWarning, setDraftStorageWarning] = useState<string | null>(null);
+  const [normalizationPending, setNormalizationPending] = useState(false);
   const [recoveryDraft, setRecoveryDraft] = useState<DraftSnapshot | null>(null);
   const [isResumingRecoveryDraft, setIsResumingRecoveryDraft] = useState(false);
   const [resumedRecoveryDraft, setResumedRecoveryDraft] = useState(false);
@@ -254,7 +350,43 @@ export const MarkdownViewer: React.FC<ViewerComponentProps> = ({
   const dialogRef = useRef<HTMLDivElement>(null);
   const unsavedChangesCancelButtonRef = useRef<HTMLButtonElement | null>(null);
   const editSessionRef = useRef<ContentEditSession | null>(null);
-  const searchHighlightsRef = useRef<DomTextSearchMatch[]>([]);
+  const previewSearchRef = useRef<ReturnType<typeof createViewportDomTextSearch> | null>(null);
+  const [previewSearchRevision, setPreviewSearchRevision] = useState(0);
+  const previewGenerationCounter = useRef(0);
+  const previewGeneration = useMemo<MarkdownPreviewGeneration>(
+    () => ({
+      id: ++previewGenerationCounter.current,
+      source: content,
+      tree: preparedPreview?.source === content ? preparedPreview.tree : undefined,
+      requests: createRef<readonly CodeBlockRequest[]>(),
+    }),
+    [content, preparedPreview]
+  );
+  const previewRevision = `${previewGeneration.id}:plain`;
+  const latestPreviewGeneration = useRef(previewGeneration);
+  latestPreviewGeneration.current = previewGeneration;
+  const [readyPreviewGeneration, setReadyPreviewGeneration] = useState<MarkdownPreviewGeneration | null>(null);
+  const previewReady = content.length < PROGRESSIVE_MARKDOWN_MIN_UNITS || readyPreviewGeneration === previewGeneration;
+  const handlePreviewPending = useCallback((generation: MarkdownPreviewGeneration) => {
+    if (latestPreviewGeneration.current === generation) setReadyPreviewGeneration(null);
+  }, []);
+  const handlePreviewReady = useCallback((generation: MarkdownPreviewGeneration) => {
+    if (latestPreviewGeneration.current === generation) setReadyPreviewGeneration(generation);
+  }, []);
+  const handlePreviewFailure = useCallback(
+    (generation: MarkdownPreviewGeneration, failure: unknown) => {
+      if (latestPreviewGeneration.current !== generation) return;
+      logError("Unable to finish rendering Markdown; close and reopen the file to retry", { error: failure });
+      setError(t("viewer.renderingFailed"));
+    },
+    [t]
+  );
+  useEffect(() => {
+    if (isEditing) setReadyPreviewGeneration(null);
+  }, [isEditing]);
+  const activeMatchRef = useRef(currentSearchMatch);
+  activeMatchRef.current = currentSearchMatch;
+  const lastPreviewSearch = useRef<{ generation: number; query: string } | null>(null);
   const editBaselineContentRef = useRef("");
   const isEditingRef = useRef(false);
   const editorLoadStateRef = useRef<EditorModuleLoadState>("idle");
@@ -313,6 +445,49 @@ export const MarkdownViewer: React.FC<ViewerComponentProps> = ({
     contentRef.current?.focus({ preventScroll: true });
   }, [isEditing]);
 
+  useEffect(() => {
+    const viewport = contentRef.current;
+    if (isEditing || loading || error || !viewport) return;
+    let restore: (() => void) | undefined;
+    let frame: number | undefined;
+    const beforePrint = () => {
+      if (frame !== undefined) cancelAnimationFrame(frame);
+      const scroll = [viewport, ...viewport.querySelectorAll("pre, table")].map((element) => ({
+        element,
+        top: element.scrollTop,
+        left: element.scrollLeft,
+      }));
+      const selection = window.getSelection();
+      const ranges = selection ? Array.from({ length: selection.rangeCount }, (_, index) => selection.getRangeAt(index).cloneRange()) : [];
+      const focus = document.activeElement;
+      restore = () => {
+        if (focus instanceof HTMLElement && focus.isConnected) focus.focus({ preventScroll: true });
+        if (selection && ranges.every((range) => range.startContainer.isConnected && range.endContainer.isConnected)) {
+          selection.removeAllRanges();
+          for (const range of ranges) selection.addRange(range);
+        }
+        for (const { element, top, left } of scroll) {
+          element.scrollTop = top;
+          element.scrollLeft = left;
+        }
+      };
+    };
+    const afterPrint = () => {
+      frame = requestAnimationFrame(() => {
+        restore?.();
+        restore = undefined;
+        frame = undefined;
+      });
+    };
+    window.addEventListener("beforeprint", beforePrint);
+    window.addEventListener("afterprint", afterPrint);
+    return () => {
+      window.removeEventListener("beforeprint", beforePrint);
+      window.removeEventListener("afterprint", afterPrint);
+      if (frame !== undefined) cancelAnimationFrame(frame);
+    };
+  }, [error, isEditing, loading]);
+
   const restoreEditingFocus = useCallback(() => {
     if (!isEditing) {
       return;
@@ -413,6 +588,7 @@ export const MarkdownViewer: React.FC<ViewerComponentProps> = ({
     clearPendingBaselineSync,
     handleEditorChange,
     handleEditorUserEdit,
+    getEditGeneration,
     markEditSessionPristine,
     requestRestoreEditingFocus,
   } = useMarkdownEditSession({
@@ -432,6 +608,7 @@ export const MarkdownViewer: React.FC<ViewerComponentProps> = ({
     const abortController = new AbortController();
 
     const loadContent = async () => {
+      let sourceLoaded = false;
       try {
         setLoading(true);
         setError(null);
@@ -443,14 +620,29 @@ export const MarkdownViewer: React.FC<ViewerComponentProps> = ({
               { kind: "text" },
               { signal: abortController.signal, virtualSource },
               contentProviders
-            ).then((blob) => blob.text()),
+            ).then(async (blob) => {
+              const start = performance.now();
+              try {
+                return await blob.text();
+              } finally {
+                recordMarkdownPreparation("decode-elapsed", start);
+              }
+            }),
           {
             signal: abortController.signal,
             maxRetries: 1,
             retryDelay: 1000,
           }
         );
-        const normalizedData = normalizeMarkdownTableCellLineBreaks(data);
+        sourceLoaded = true;
+        const normalizationStart = performance.now();
+        let tree: MarkdownRoot | undefined;
+        const normalizedData = await normalizeMarkdownSource(data, abortController.signal, (prepared) => {
+          tree = prepared;
+        });
+        if (abortController.signal.aborted) return;
+        recordMarkdownPreparation("load-normalization-elapsed", normalizationStart);
+        setPreparedPreview(tree ? { source: normalizedData, tree } : null);
         setContent(normalizedData);
         if (!isEditingRef.current && !isReadOnly) {
           const recoveredDraft = loadDraft(connectionId, path, "markdown");
@@ -465,9 +657,10 @@ export const MarkdownViewer: React.FC<ViewerComponentProps> = ({
         }
 
         // Show "server busy" only for actual transient/network errors
-        const errorMessage = checkIsTransientError(err)
-          ? getTransientErrorMessage()
-          : getApiErrorMessage(err, "Failed to load markdown file", { includeOriginalMessage: true });
+        const errorMessage =
+          !sourceLoaded && checkIsTransientError(err)
+            ? getTransientErrorMessage()
+            : getApiErrorMessage(err, "Failed to load markdown file", { includeOriginalMessage: true });
 
         setError(errorMessage);
         logError("Error loading markdown:", {
@@ -489,51 +682,56 @@ export const MarkdownViewer: React.FC<ViewerComponentProps> = ({
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [connectionId, contentProviders, fetchWithRetry, isReadOnly, path, setEditBaselineContent, virtualSource]);
 
-  useEffect(() => {
-    if (!isEditing) {
+  const snapshotDraft = useCallback(() => {
+    if (!isEditingRef.current) {
       return;
     }
 
-    if (draftContent === editBaselineContentRef.current) {
-      clearDraft(connectionId, path, "markdown");
-      setDraftStorageWarning(null);
-      return;
-    }
-
-    const timeoutId = window.setTimeout(() => {
-      const result = saveDraft(connectionId, path, "markdown", editBaselineContentRef.current, draftContent);
-      if (result.saved || result.reason === "no-user") {
+    try {
+      const editor = editorRef.current;
+      if (!editor) throw new Error("The Markdown editor is not mounted");
+      const latestContent = editor.captureSnapshotSync().serialize();
+      if (latestContent === editBaselineContentRef.current) {
+        clearDraft(connectionId, path, "markdown");
         setDraftStorageWarning(null);
-        return;
+      } else {
+        const result = saveDraft(connectionId, path, "markdown", editBaselineContentRef.current, latestContent);
+        if (result.saved || result.reason === "no-user") {
+          setDraftStorageWarning(null);
+        } else {
+          setDraftStorageWarning(
+            result.reason === "too-large" ? t("viewer.edit.recovery.tooLargeWarning") : t("viewer.edit.recovery.storageUnavailableWarning")
+          );
+        }
       }
+    } catch (error) {
+      logError("Markdown recovery snapshot failed; keep the editor open and save the file", {
+        error,
+        connectionId,
+        path,
+      });
+      if (editorRef.current) setDraftStorageWarning(t("viewer.edit.recovery.storageUnavailableWarning"));
+    }
+  }, [connectionId, path, t]);
 
-      setDraftStorageWarning(
-        result.reason === "too-large" ? t("viewer.edit.recovery.tooLargeWarning") : t("viewer.edit.recovery.storageUnavailableWarning")
-      );
-    }, DRAFT_SNAPSHOT_DEBOUNCE_MS);
-
+  useEffect(() => {
+    if (!isEditing || normalizationPending) return;
+    if (draftContent === editBaselineContentRef.current) {
+      snapshotDraft();
+      return;
+    }
+    const timeoutId = window.setTimeout(snapshotDraft, DRAFT_SNAPSHOT_DEBOUNCE_MS);
     return () => window.clearTimeout(timeoutId);
-  }, [connectionId, draftContent, isEditing, path, t]);
+  }, [draftContent, isEditing, normalizationPending, snapshotDraft]);
 
   useEffect(() => {
-    const snapshot = () => {
-      if (!isEditingRef.current) {
-        return;
-      }
-
-      if (draftContent === editBaselineContentRef.current) {
-        clearDraft(connectionId, path, "markdown");
-      } else {
-        saveDraft(connectionId, path, "markdown", editBaselineContentRef.current, draftContent);
-      }
-    };
-    const unregister = registerDraftSnapshot(snapshot);
-    window.addEventListener("pagehide", snapshot);
+    const unregister = registerDraftSnapshot(snapshotDraft);
+    window.addEventListener("pagehide", snapshotDraft);
     return () => {
       unregister();
-      window.removeEventListener("pagehide", snapshot);
+      window.removeEventListener("pagehide", snapshotDraft);
     };
-  }, [connectionId, draftContent, path]);
+  }, [snapshotDraft]);
 
   // Auto-focus the content when loaded so keyboard scrolling works
   useEffect(() => {
@@ -543,6 +741,7 @@ export const MarkdownViewer: React.FC<ViewerComponentProps> = ({
 
     // Small delay to ensure dialog transition is complete.
     const timeoutId = window.setTimeout(() => {
+      if (isViewerSearchInputFocused()) return;
       focusViewerContent();
     }, MARKDOWN_VIEWER_CONTENT_AUTOFOCUS_DELAY_MS);
 
@@ -583,7 +782,11 @@ export const MarkdownViewer: React.FC<ViewerComponentProps> = ({
     }
   }, [isEditing]);
 
-  const hasUnsavedChanges = isEditing && draftContent !== editBaselineContent;
+  const handleNormalizationStateChange = useCallback((pending: boolean, error?: Error) => {
+    setNormalizationPending(pending);
+    if (error) setEditError(error.message);
+  }, []);
+  const hasUnsavedChanges = isEditing && (normalizationPending || draftContent !== editBaselineContent);
   const unsavedChangesIndicator = hasUnsavedChanges ? (
     <Box
       component="span"
@@ -688,37 +891,79 @@ export const MarkdownViewer: React.FC<ViewerComponentProps> = ({
   });
 
   useEffect(() => {
-    const markdownRoot = contentRef.current?.querySelector(MARKDOWN_SEARCH_ROOT_SELECTOR);
-    clearDomTextSearchHighlights(markdownRoot instanceof HTMLElement ? markdownRoot : null);
-    searchHighlightsRef.current = [];
+    const requests = previewGeneration.requests.current;
+    if (isEditing || loading || !previewReady || error || !requests?.length) return;
+    const controller = new AbortController();
+    let dispose: (() => void) | undefined;
+    void prepareMarkdownSyntax(requests, controller.signal)
+      .then((results) => {
+        if (controller.signal.aborted || latestPreviewGeneration.current !== previewGeneration) return;
+        const viewport = contentRef.current;
+        const root = viewport?.querySelector<HTMLElement>(MARKDOWN_SEARCH_ROOT_SELECTOR);
+        if (viewport && root) {
+          dispose = publishMarkdownSyntax(root, viewport, { requests, results }, controller.signal);
+        }
+      })
+      .catch((failure: unknown) => {
+        if (!controller.signal.aborted)
+          logError(
+            "Markdown syntax preparation failed; retaining plain text",
+            { operation: "prepare" },
+            "MarkdownViewer",
+            failure instanceof Error ? failure : undefined
+          );
+      });
+    return () => {
+      controller.abort();
+      dispose?.();
+    };
+  }, [error, isEditing, loading, previewGeneration, previewReady]);
+
+  useLayoutEffect(() => {
+    const viewport = contentRef.current;
+    const markdownRoot = viewport?.querySelector(MARKDOWN_SEARCH_ROOT_SELECTOR);
+    if (isEditing || loading || !previewReady || error || !viewport || !(markdownRoot instanceof HTMLElement)) return;
+    if (markdownRoot?.getAttribute("data-markdown-preview-revision") !== previewRevision) return;
+    const search = createViewportDomTextSearch(markdownRoot, viewport, () => setPreviewSearchRevision((revision) => revision + 1));
+    previewSearchRef.current = search;
+    if (!search.supported) {
+      logInfo(
+        "Preview search highlighting is unavailable in this browser; counts and navigation remain available. Use a browser supporting CSS Highlights for visible matches."
+      );
+    }
+    return () => {
+      search.dispose();
+      if (previewSearchRef.current === search) previewSearchRef.current = null;
+    };
+  }, [error, isEditing, loading, previewRevision, previewReady]);
 
-    if (isEditing || !activeViewerSearchText.trim() || loading || error) {
+  useLayoutEffect(() => {
+    const search = previewSearchRef.current;
+    if (isEditing || !activeViewerSearchText.trim() || loading || !previewReady || error) {
+      search?.setQuery("", previewSearchRevision);
       setSearchMatches(0);
       setCurrentSearchMatch(0);
       return;
     }
 
-    if (!(markdownRoot instanceof HTMLElement)) {
+    if (!search) {
       setSearchMatches(0);
       setCurrentSearchMatch(0);
       return;
     }
 
-    const highlights = applyDomTextSearchHighlights(markdownRoot, activeViewerSearchText);
-    searchHighlightsRef.current = highlights;
-    const initialMatch = highlights.length > 0 ? 1 : 0;
-    setSearchMatches(highlights.length);
+    const count = search.setQuery(activeViewerSearchText, previewSearchRevision);
+    const unchangedSearch =
+      lastPreviewSearch.current?.generation === previewGeneration.id && lastPreviewSearch.current.query === activeViewerSearchText;
+    const initialMatch = count > 0 ? (unchangedSearch ? Math.max(1, Math.min(activeMatchRef.current, count)) : 1) : 0;
+    lastPreviewSearch.current = { generation: previewGeneration.id, query: activeViewerSearchText };
+    setSearchMatches(count);
     setCurrentSearchMatch(initialMatch);
-    activateDomTextSearchMatch(highlights, initialMatch);
-
-    return () => {
-      clearDomTextSearchHighlights(markdownRoot);
-      searchHighlightsRef.current = [];
-    };
-  }, [activeViewerSearchText, error, isEditing, loading]);
+    search.activate(initialMatch, !unchangedSearch);
+  }, [activeViewerSearchText, error, isEditing, loading, previewGeneration.id, previewReady, previewSearchRevision]);
 
   useEffect(() => {
-    activateDomTextSearchMatch(searchHighlightsRef.current, currentSearchMatch);
+    previewSearchRef.current?.activate(currentSearchMatch);
   }, [currentSearchMatch]);
 
   useEffect(() => {
@@ -786,7 +1031,7 @@ export const MarkdownViewer: React.FC<ViewerComponentProps> = ({
   const handleEnterEditMode = useCallback(
     async (initialDraft = content): Promise<boolean> => {
       if (editSessionRef.current || isAcquiring) return Boolean(editSessionRef.current);
-      if (isReadOnly || loading || error) {
+      if (isReadOnly || loading || !previewReady || error) {
         return false;
       }
 
@@ -844,6 +1089,7 @@ export const MarkdownViewer: React.FC<ViewerComponentProps> = ({
       isReadOnly,
       isAcquiring,
       loading,
+      previewReady,
       markEditSessionPristine,
       path,
       searchPanelOpen,
@@ -876,7 +1122,7 @@ export const MarkdownViewer: React.FC<ViewerComponentProps> = ({
     isEditing,
     isSaving,
     isAcquiring,
-    loading,
+    loading: loading || (!isEditing && !previewReady),
     dirty: hasUnsavedChanges,
     enterEdit: handleEnterEditMode,
     exitEdit: exitEditMode,
@@ -939,42 +1185,53 @@ export const MarkdownViewer: React.FC<ViewerComponentProps> = ({
       setIsSaving(true);
 
       try {
-        let savedContent = draftContent;
-
-        if (editorRef.current) {
-          // While a nested table cell is focused, the wrapper draft can be
-          // behind the live nested editor. Save must flush pending publication
-          // and then persist the editor's canonical export, not the stale draft.
-          emitMarkdownDebugTrace("MarkdownViewer", "persistDraft:flush-start");
-          await editorRef.current.flushPendingEdits();
-          emitMarkdownDebugTrace("MarkdownViewer", "persistDraft:flush-resolved");
-          savedContent = editorRef.current.getCanonicalMarkdown();
-          emitMarkdownDebugTrace("MarkdownViewer", "persistDraft:getCanonicalMarkdown", {
-            savedContentLength: savedContent.length,
-          });
-        }
-
-        savedContent = normalizeMarkdownTableCellLineBreaks(savedContent);
+        const editor = editorRef.current;
+        if (!editor) throw new Error("Markdown editor is no longer available for saving");
+        const saveGeneration = getEditGeneration();
+        emitMarkdownDebugTrace("MarkdownViewer", "persistDraft:flush-start");
+        const snapshot = await editor.captureSnapshot();
+        emitMarkdownDebugTrace("MarkdownViewer", "persistDraft:flush-resolved");
+        const savedContent = snapshot.serialize();
+        emitMarkdownDebugTrace("MarkdownViewer", "persistDraft:getCanonicalMarkdown", {
+          savedContentLength: savedContent.length,
+          revision: snapshot.revision,
+        });
 
         if (!editSession) throw new Error("Edit session is no longer active");
         await editSession.writeText(savedContent, { mimeType: "text/markdown;charset=utf-8" });
         emitMarkdownDebugTrace("MarkdownViewer", "persistDraft:save-resolved", {
           savedContentLength: savedContent.length,
         });
+        let hasNewerEdits = getEditGeneration() !== saveGeneration;
+        if (hasNewerEdits) {
+          try {
+            hasNewerEdits = editor.captureSnapshotSync().serialize() !== savedContent;
+          } catch (error) {
+            logInfo(
+              "Markdown Save completed; newer edits remain dirty because their snapshot is not ready",
+              { error, path, connectionId },
+              "MarkdownViewer"
+            );
+          }
+        }
         clearPendingBaselineSync();
-        beginBaselineSyncWindow();
+        if (hasNewerEdits) clearBaselineSyncWindow();
+        else beginBaselineSyncWindow();
+        setPreparedPreview((prepared) => (prepared?.source === savedContent ? prepared : null));
         setContent(savedContent);
         setShareRevision((revision) => revision + 1);
-        setDraftContent(savedContent);
         setEditBaselineContent(savedContent);
-        markEditSessionPristine();
-        clearDraft(connectionId, path, "markdown");
+        if (!hasNewerEdits) {
+          setDraftContent(savedContent);
+          markEditSessionPristine();
+          clearDraft(connectionId, path, "markdown");
+        }
 
-        if (afterSave === "cancel-edit") {
+        if (afterSave === "cancel-edit" && !hasNewerEdits) {
           await exitEditMode(savedContent);
         }
 
-        return true;
+        return !hasNewerEdits;
       } catch (err) {
         emitMarkdownDebugTrace("MarkdownViewer", "persistDraft:error", {
           message: err instanceof Error ? err.message : String(err),
@@ -997,11 +1254,13 @@ export const MarkdownViewer: React.FC<ViewerComponentProps> = ({
     },
     [
       beginBaselineSyncWindow,
+      clearBaselineSyncWindow,
       clearPendingBaselineSync,
       connectionId,
       draftContent,
       editSession,
       exitEditMode,
+      getEditGeneration,
       isEditing,
       isReadOnly,
       markEditSessionPristine,
@@ -1167,7 +1426,7 @@ export const MarkdownViewer: React.FC<ViewerComponentProps> = ({
 
   const handleOpenSearch = useCallback(
     (_event?: KeyboardEvent) => {
-      if (loading || error || (isEditing && !editorSearchState.isSearchable)) {
+      if (loading || error || (!isEditing && !previewReady) || (isEditing && !editorSearchState.isSearchable)) {
         return;
       }
 
@@ -1183,7 +1442,7 @@ export const MarkdownViewer: React.FC<ViewerComponentProps> = ({
 
       setSearchPanelOpen(true);
     },
-    [editorSearchState.isSearchable, error, isEditing, loading]
+    [editorSearchState.isSearchable, error, isEditing, loading, previewReady]
   );
 
   const handleOpenReplace = useCallback(() => {
@@ -1219,6 +1478,7 @@ export const MarkdownViewer: React.FC<ViewerComponentProps> = ({
 
   const handleSearchPanelToggle = useCallback(
     (open: boolean) => {
+      if (open && !isEditing && !previewReady) return;
       if (open) {
         if (isEditing) {
           setEditorSearchText("");
@@ -1231,7 +1491,7 @@ export const MarkdownViewer: React.FC<ViewerComponentProps> = ({
 
       closeSearchPanel({ preserveQuery: isEditing, restoreEditorFocus: false });
     },
-    [closeSearchPanel, isEditing]
+    [closeSearchPanel, isEditing, previewReady]
   );
 
   const handleSearchClose = useCallback(
@@ -1498,12 +1758,12 @@ export const MarkdownViewer: React.FC<ViewerComponentProps> = ({
       {
         ...COMMON_SHORTCUTS.NEXT_MATCH,
         handler: handleSearchNext,
-        enabled: isEditing && searchMatches > 0,
+        enabled: isEditing && (searchMatches > 0 || Boolean(editorSearchState.pending || editorSearchState.error)),
       },
       {
         ...COMMON_SHORTCUTS.PREVIOUS_MATCH,
         handler: handleSearchPrevious,
-        enabled: isEditing && searchMatches > 0,
+        enabled: isEditing && (searchMatches > 0 || Boolean(editorSearchState.pending || editorSearchState.error)),
       },
       {
         ...COMMON_SHORTCUTS.SAVE,
@@ -1618,6 +1878,8 @@ export const MarkdownViewer: React.FC<ViewerComponentProps> = ({
       isSaving,
       loading,
       editorSearchMode,
+      editorSearchState.pending,
+      editorSearchState.error,
       searchPanelOpen,
       searchMatches,
       setWordWrapEnabled,
@@ -1628,7 +1890,7 @@ export const MarkdownViewer: React.FC<ViewerComponentProps> = ({
 
   const isSearchable = isEditing
     ? !editorFailed && editorLoadState === "loaded" && !editorLoadError && editorSearchState.isSearchable
-    : !loading && !error && content.trim().length > 0;
+    : !loading && previewReady && !error && content.trim().length > 0;
 
   useKeyboardShortcuts({
     active: !showViewerHelp && !showEditorHelp,
@@ -1650,6 +1912,20 @@ export const MarkdownViewer: React.FC<ViewerComponentProps> = ({
             }),
           ]
         : [
+            createPrintToolbarAction({
+              id: "print-markdown",
+              isMobile,
+              disabled: loading || !previewReady || !!error,
+              onClick: () => {
+                setPrintError(false);
+                try {
+                  window.print();
+                } catch (error) {
+                  logError("Unable to open Markdown print dialog", { error });
+                  setPrintError(true);
+                }
+              },
+            }),
             ...(isReadOnly
               ? []
               : [
@@ -1659,11 +1935,23 @@ export const MarkdownViewer: React.FC<ViewerComponentProps> = ({
                       void handleEnterEditMode();
                     },
                     isMobile,
-                    disabled: loading || !!error,
+                    disabled: loading || !previewReady || !!error,
                   }),
                 ]),
           ],
-    [editorLoadError, editorLoadState, error, handleEnterEditMode, handleSave, isEditing, isMobile, isReadOnly, isSaving, loading]
+    [
+      editorLoadError,
+      editorLoadState,
+      error,
+      handleEnterEditMode,
+      handleSave,
+      isEditing,
+      isMobile,
+      isReadOnly,
+      isSaving,
+      loading,
+      previewReady,
+    ]
   );
 
   // Log when markdown viewer opens
@@ -1695,7 +1983,9 @@ export const MarkdownViewer: React.FC<ViewerComponentProps> = ({
 
   return (
     <>
+      {!isEditing && !loading && !error && <GlobalStyles styles={MARKDOWN_VIEWER_PRINT_STYLES} />}
       <Dialog
+        data-markdown-print-viewer={!isEditing && !loading && !error ? "true" : undefined}
         inert={isTransitioning}
         open={true}
         onClose={handleDialogClose}
@@ -1714,10 +2004,10 @@ export const MarkdownViewer: React.FC<ViewerComponentProps> = ({
             onKeyDown: handlePaperKeyDown,
             sx: {
               margin: 0,
-              width: "100dvw",
-              maxWidth: "100dvw",
-              height: "100dvh",
-              maxHeight: "100dvh",
+              width: "100%",
+              maxWidth: "100%",
+              height: "100%",
+              maxHeight: "100%",
               display: "flex",
               flexDirection: "column",
               backgroundColor: viewerBg,
@@ -1726,6 +2016,7 @@ export const MarkdownViewer: React.FC<ViewerComponentProps> = ({
         }}
       >
         <Box
+          data-markdown-print-frame="true"
           sx={{
             position: "relative",
             width: "100%",
@@ -1738,6 +2029,7 @@ export const MarkdownViewer: React.FC<ViewerComponentProps> = ({
         >
           {/* Markdown Controls Overlay */}
           <Box
+            data-markdown-print-controls="true"
             sx={{
               flexShrink: 0,
               zIndex: 1,
@@ -1786,11 +2078,16 @@ export const MarkdownViewer: React.FC<ViewerComponentProps> = ({
                 <ViewerShareMenu
                   onFile={nativeSharing.shareFile}
                   onText={() =>
-                    nativeSharing.shareText(() => (isEditing ? (editorRef.current?.getCanonicalMarkdown() ?? draftContent) : content))
+                    nativeSharing.shareText(() => {
+                      if (!isEditing) return content;
+                      const editor = editorRef.current;
+                      if (!editor) throw new Error("The Markdown editor is not mounted for sharing");
+                      return editor.captureSnapshotSync().serialize();
+                    })
                   }
                   fileDisabled={!nativeSharing.ready || isSaving}
                   filePreparing={nativeSharing.preparing}
-                  textDisabled={loading || Boolean(error)}
+                  textDisabled={loading || Boolean(error) || (isEditing && normalizationPending)}
                   disabled={nativeSharing.sharing}
                 />
               }
@@ -1805,6 +2102,8 @@ export const MarkdownViewer: React.FC<ViewerComponentProps> = ({
               focusTarget={editorSearchFocusTarget}
               isReplaceMode={editorSearchMode === "replace"}
               isSearchValid={editorSearchState.isValid}
+              searchPending={editorSearchState.pending}
+              searchError={editorSearchState.error}
               onCaseSensitiveChange={setEditorSearchCaseSensitive}
               onClose={() => closeSearchPanel({ preserveQuery: true, restoreEditorFocus: true })}
               onFindNext={handleSearchNext}
@@ -1831,6 +2130,12 @@ export const MarkdownViewer: React.FC<ViewerComponentProps> = ({
             </Alert>
           )}
 
+          {printError && (
+            <Alert severity="error" sx={{ m: 2, flexShrink: 0 }}>
+              {t("viewer.printError")}
+            </Alert>
+          )}
+
           {nativeSharing.failureDialog}
 
           {draftStorageWarning && (
@@ -1951,6 +2256,7 @@ export const MarkdownViewer: React.FC<ViewerComponentProps> = ({
                       lineWrapping={wordWrapEnabled}
                       onChange={handleEditorChange}
                       onUserEdit={handleEditorUserEdit}
+                      onNormalizationStateChange={handleNormalizationStateChange}
                       ariaLabel={t("viewer.edit.editorLabel")}
                       autoFocus={true}
                       readOnly={editorShouldBeReadOnly || routedEditing.isExiting}
@@ -1968,66 +2274,33 @@ export const MarkdownViewer: React.FC<ViewerComponentProps> = ({
               </Box>
             ) : (
               <Box
+                key={previewRevision}
                 data-markdown-search-root="true"
+                data-markdown-preview-revision={previewRevision}
+                onClickCapture={(event) => {
+                  if (!previewReady && event.target instanceof Element && event.target.closest('a[href^="#"]')) event.preventDefault();
+                }}
+                style={getSyntaxVariables(muiTheme, linkColor)}
                 sx={{
                   ...getMarkdownContentStyles(viewerText, linkColor, linkHoverColor),
-                  [`& ${DOM_TEXT_SEARCH_HIGHLIGHT_SELECTOR}`]: {
-                    backgroundColor: searchHighlightColors.otherMatches,
-                    borderRadius: 0.5,
-                    padding: 0,
-                  },
-                  [`& ${DOM_TEXT_SEARCH_HIGHLIGHT_SELECTOR}[${DOM_TEXT_SEARCH_CURRENT_MATCH_ATTRIBUTE}="true"]`]: {
-                    backgroundColor: searchHighlightColors.currentMatch,
-                  },
+                  ...(!previewReady ? { "@media print": { display: "none !important" } } : {}),
+                  "--sambee-search-other": searchHighlightColors.otherMatches,
+                  "--sambee-search-current": searchHighlightColors.currentMatch,
+                  "--sambee-search-foreground": viewerText,
                 }}
               >
-                <ReactMarkdown
-                  remarkPlugins={[remarkGfm, remarkRenderMarkdownTableCellLineBreaks]}
-                  rehypePlugins={[rehypeHighlight]}
-                  components={{
-                    // Destructure `node` (injected by react-markdown's passNode)
-                    // so it is not spread onto the native <a> DOM element.
-                    a: ({ href, node: _node, ...props }) => {
-                      if (typeof href !== "string") {
-                        return <a {...props} />;
-                      }
-
-                      const resolvedHref = resolveMarkdownLinkHref(href);
-
-                      if (!resolvedHref) {
-                        return <span>{props.children}</span>;
-                      }
-
-                      const opensNewTab = !resolvedHref.startsWith(MARKDOWN_HASH_PREFIX);
-
-                      const handleLinkClick = opensNewTab
-                        ? (event: React.MouseEvent) => {
-                            event.preventDefault();
-                            openExternalUrl(resolvedHref);
-
-                            // External links leave focus on the clicked anchor.
-                            // Restore focus to the viewer surface so single-key
-                            // shortcuts keep working when the user returns.
-                            focusViewerContent();
-                          }
-                        : undefined;
-
-                      return (
-                        <a
-                          {...props}
-                          href={resolvedHref}
-                          rel={opensNewTab ? "noopener noreferrer" : undefined}
-                          target={opensNewTab ? "_blank" : undefined}
-                          onClick={handleLinkClick}
-                        />
-                      );
-                    },
-                  }}
-                >
-                  {content}
-                </ReactMarkdown>
+                <MarkdownPreview
+                  generation={previewGeneration}
+                  onExternalLink={focusViewerContent}
+                  onPending={handlePreviewPending}
+                  onReady={handlePreviewReady}
+                  onFailure={handlePreviewFailure}
+                />
               </Box>
             )}
+            {!isEditing && !loading && !error && !previewReady && (
+              <Box sx={{ display: "none", "@media print": { display: "block" } }}>{t("viewer.renderingPrintPending")}</Box>
+            )}
           </Box>
         </Box>
       </Dialog>
diff --git a/frontend/src/components/Viewer/PDFViewer.tsx b/frontend/src/components/Viewer/PDFViewer.tsx
index 4f2c82071..af92de556 100644
--- a/frontend/src/components/Viewer/PDFViewer.tsx
+++ b/frontend/src/components/Viewer/PDFViewer.tsx
@@ -1528,7 +1528,7 @@ const PDFViewer: React.FC<ViewerComponentProps> = ({
 
           {/* Error state */}
           {error && (
-            <Box p={2}>
+            <Box sx={{ p: 2 }}>
               <Alert
                 severity="error"
                 action={
@@ -1617,7 +1617,7 @@ const PDFViewer: React.FC<ViewerComponentProps> = ({
                 onPassword={handleDocumentPassword}
                 loading={null}
                 error={
-                  <Box p={2}>
+                  <Box sx={{ p: 2 }}>
                     <Alert severity="error">Failed to load PDF document</Alert>
                   </Box>
                 }
diff --git a/frontend/src/components/Viewer/ProgressiveMarkdown.tsx b/frontend/src/components/Viewer/ProgressiveMarkdown.tsx
new file mode 100644
index 000000000..40332ad48
--- /dev/null
+++ b/frontend/src/components/Viewer/ProgressiveMarkdown.tsx
@@ -0,0 +1,336 @@
+import { Box, CircularProgress } from "@mui/material";
+import type { Element, Root, RootContent } from "hast";
+import { type ComponentType, memo, useLayoutEffect, useMemo, useRef, useState } from "react";
+import { flushSync } from "react-dom";
+import { useTranslation } from "react-i18next";
+import ReactMarkdown, { type Components, type Options } from "react-markdown";
+import type { Plugin } from "unified";
+
+export const PROGRESSIVE_MARKDOWN_MIN_UNITS = 50_000;
+export const PROGRESSIVE_MARKDOWN_BATCH_NODES = 1_024;
+export const PROGRESSIVE_MARKDOWN_BATCH_UNITS = 8_192;
+export const PROGRESSIVE_MARKDOWN_FRAME_MS = 4;
+export const PROGRESSIVE_MARKDOWN_FRAME_BATCHES = 4;
+export const PROGRESSIVE_MARKDOWN_VIEWPORTS = 2;
+export const PROGRESSIVE_MARKDOWN_FEEDBACK_MS = 200;
+const SLOT_TAG = "sambee-markdown-stage";
+const TABLE_CONTAINERS = new Set(["table", "thead", "tbody", "tfoot", "tr"]);
+const HIGH_SURROGATE_START = 0xd800;
+const HIGH_SURROGATE_END = 0xdbff;
+
+interface Weight {
+  nodes: number;
+  units: number;
+}
+
+interface Slot {
+  id: number;
+  children: RootContent[];
+  index: number;
+  offset: number;
+  sequence: number;
+  first?: PublicationBatch;
+}
+
+interface PublicationBatch {
+  id: number;
+  children: RootContent[];
+}
+
+function createPublication(source: Options["children"]) {
+  const weights = new WeakMap<RootContent, Weight>();
+  const slots = new Map<number, Slot>();
+  const queued = new Map<number, () => void>();
+  let nextId = 0;
+  let frame: number | undefined;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let root: HTMLElement | null = null;
+  let ready = false;
+  let advancing = false;
+  let initialViewportFilled = false;
+  let onComplete = () => {};
+  let onFailure = (_error: unknown) => {};
+
+  function register(children: RootContent[], parentTag?: string): Element {
+    const id = nextId++;
+    const content =
+      parentTag && TABLE_CONTAINERS.has(parentTag)
+        ? children.filter((child) => child.type !== "text" || child.value.trim().length > 0)
+        : children;
+    slots.set(id, { id, children: content, index: 0, offset: 0, sequence: 0 });
+    return { type: "element", tagName: SLOT_TAG, properties: { stageId: id }, children: [] };
+  }
+
+  function take(slot: Slot): PublicationBatch {
+    const batch: RootContent[] = [];
+    let nodes = 0;
+    let units = 0;
+    while (slot.index < slot.children.length && nodes < PROGRESSIVE_MARKDOWN_BATCH_NODES && units < PROGRESSIVE_MARKDOWN_BATCH_UNITS) {
+      const child = slot.children[slot.index];
+      if (!child) throw new Error("Markdown publication is missing a staged node.");
+      const weight = weights.get(child) ?? { nodes: 1, units: "value" in child ? child.value.length : 0 };
+      if ((child.type === "text" || child.type === "raw") && child.value.length - slot.offset > PROGRESSIVE_MARKDOWN_BATCH_UNITS - units) {
+        let end = slot.offset + PROGRESSIVE_MARKDOWN_BATCH_UNITS - units;
+        const boundary = child.value.charCodeAt(end - 1);
+        if (boundary >= HIGH_SURROGATE_START && boundary <= HIGH_SURROGATE_END) end -= 1;
+        if (end === slot.offset) break;
+        batch.push({ type: "text", value: child.value.slice(slot.offset, end) });
+        slot.offset = end;
+        break;
+      }
+      if (
+        child.type === "element" &&
+        (weight.nodes > PROGRESSIVE_MARKDOWN_BATCH_NODES || weight.units > PROGRESSIVE_MARKDOWN_BATCH_UNITS)
+      ) {
+        if (batch.length) break;
+        batch.push({ ...child, properties: { ...child.properties }, children: [register(child.children, child.tagName)] });
+        slot.index += 1;
+        break;
+      } else {
+        if (
+          batch.length &&
+          (nodes + weight.nodes > PROGRESSIVE_MARKDOWN_BATCH_NODES || units + weight.units > PROGRESSIVE_MARKDOWN_BATCH_UNITS)
+        )
+          break;
+        batch.push(
+          slot.offset && (child.type === "text" || child.type === "raw") ? { ...child, value: child.value.slice(slot.offset) } : child
+        );
+        nodes += weight.nodes;
+        units += weight.units;
+      }
+      slot.index += 1;
+      slot.offset = 0;
+    }
+    return { id: slot.sequence++, children: batch };
+  }
+
+  function cancelFrame() {
+    if (frame !== undefined) cancelAnimationFrame(frame);
+    if (timer !== undefined) clearTimeout(timer);
+    frame = undefined;
+    timer = undefined;
+  }
+
+  function schedule() {
+    if (!root || ready || advancing || frame !== undefined || timer !== undefined) return;
+    if (document.hidden) timer = setTimeout(advance, 0);
+    else frame = requestAnimationFrame(advance);
+  }
+
+  function advance() {
+    frame = undefined;
+    timer = undefined;
+    if (!root) return;
+    advancing = true;
+    try {
+      const start = performance.now();
+      const viewportHeight = initialViewportFilled
+        ? 0
+        : root.closest<HTMLElement>('[data-testid="markdown-viewer-content"]')?.clientHeight || window.innerHeight;
+      if (!initialViewportFilled && root.getBoundingClientRect().height >= viewportHeight * PROGRESSIVE_MARKDOWN_VIEWPORTS)
+        initialViewportFilled = true;
+      let batches = 0;
+      while (queued.size) {
+        const [id, append] = queued.entries().next().value!;
+        queued.delete(id);
+        flushSync(append);
+        if (!root) return;
+        batches += 1;
+        if (performance.now() - start >= PROGRESSIVE_MARKDOWN_FRAME_MS || batches >= PROGRESSIVE_MARKDOWN_FRAME_BATCHES) break;
+        if (!initialViewportFilled && root.getBoundingClientRect().height >= viewportHeight * PROGRESSIVE_MARKDOWN_VIEWPORTS) {
+          initialViewportFilled = true;
+          break;
+        }
+      }
+      if (!queued.size) {
+        ready = true;
+        onComplete();
+      }
+    } catch (error) {
+      queued.clear();
+      root = null;
+      onFailure(error);
+    } finally {
+      advancing = false;
+      schedule();
+    }
+  }
+
+  const stage: Plugin<[], Root> = () => (tree) => {
+    const pending: { node: RootContent; visited: boolean }[] = tree.children.map((node) => ({ node, visited: false }));
+    while (pending.length) {
+      const entry = pending.pop()!;
+      if (!entry.visited && "children" in entry.node) {
+        pending.push({ ...entry, visited: true });
+        for (const child of entry.node.children) pending.push({ node: child as RootContent, visited: false });
+      } else {
+        const weight = { nodes: 1, units: "value" in entry.node ? entry.node.value.length : 0 };
+        if ("children" in entry.node)
+          for (const child of entry.node.children) {
+            const childWeight = weights.get(child as RootContent)!;
+            weight.nodes += childWeight.nodes;
+            weight.units += childWeight.units;
+          }
+        weights.set(entry.node, weight);
+      }
+    }
+    tree.children = [register(tree.children)];
+  };
+
+  return {
+    source,
+    stage,
+    slots,
+    take,
+    enqueue(id: number, append: () => void) {
+      queued.set(id, append);
+      schedule();
+      return () => {
+        queued.delete(id);
+      };
+    },
+    start(element: HTMLElement, complete: () => void, failure: (error: unknown) => void) {
+      root = element;
+      onComplete = complete;
+      onFailure = failure;
+      const visibilityChanged = () => {
+        cancelFrame();
+        schedule();
+      };
+      document.addEventListener("visibilitychange", visibilityChanged);
+      schedule();
+      return () => {
+        root = null;
+        cancelFrame();
+        document.removeEventListener("visibilitychange", visibilityChanged);
+      };
+    },
+  };
+}
+
+const injectTree: Plugin<[RootContent[]], Root> = (children) => (tree) => {
+  tree.children = children;
+};
+
+type ProgressiveMarkdownProps = Pick<Options, "children" | "remarkPlugins" | "rehypePlugins" | "components"> & {
+  onPending?: () => void;
+  onReady: () => void;
+  onFailure: (error: unknown) => void;
+};
+
+export function ProgressiveMarkdown({
+  onPending,
+  onReady,
+  onFailure,
+  children,
+  remarkPlugins,
+  rehypePlugins,
+  components: linkComponents,
+}: ProgressiveMarkdownProps) {
+  const { t } = useTranslation();
+  const heavy = (children?.length ?? 0) >= PROGRESSIVE_MARKDOWN_MIN_UNITS;
+  const renderOptions = useMemo(
+    () => ({ children, remarkPlugins, rehypePlugins, components: linkComponents }),
+    [children, remarkPlugins, rehypePlugins, linkComponents]
+  );
+  const publication = useMemo(() => createPublication(renderOptions.children), [renderOptions]);
+  const root = useRef<HTMLDivElement>(null);
+  const callbacks = useRef({ onPending, onReady, onFailure });
+  callbacks.current = { onPending, onReady, onFailure };
+  const [complete, setComplete] = useState(false);
+  const [feedback, setFeedback] = useState(false);
+  const Stage = useMemo(() => {
+    const Batch = memo(({ children }: { children: RootContent[] }) => (
+      <ReactMarkdown components={components} rehypePlugins={[[injectTree, children]]}>
+        {""}
+      </ReactMarkdown>
+    ));
+    const SlotComponent = ({ node }: { node: Element }) => {
+      const slot = publication.slots.get(Number(node.properties["stageId"]))!;
+      const [batches, setBatches] = useState(() => {
+        if (!slot.first) slot.first = publication.take(slot);
+        return [slot.first];
+      });
+      useLayoutEffect(() => {
+        if (!batches.length || slot.index >= slot.children.length) return;
+        return publication.enqueue(slot.id, () => {
+          const next = publication.take(slot);
+          setBatches((current) => [...current, next]);
+        });
+      }, [batches.length, slot]);
+      return batches.map((batch) => <Batch key={batch.id}>{batch.children}</Batch>);
+    };
+    const components = { ...linkComponents, [SLOT_TAG]: SlotComponent as ComponentType<unknown> } as Components;
+    return { components };
+  }, [publication, linkComponents]);
+  const stagedDocument = useMemo(
+    () => (
+      <ReactMarkdown
+        components={Stage.components}
+        remarkPlugins={remarkPlugins}
+        rehypePlugins={[...(rehypePlugins ?? []), publication.stage]}
+      >
+        {children}
+      </ReactMarkdown>
+    ),
+    [publication, Stage, children, remarkPlugins, rehypePlugins]
+  );
+
+  useLayoutEffect(() => {
+    if (!heavy) {
+      callbacks.current.onReady();
+      return;
+    }
+    if (!root.current) return;
+    callbacks.current.onPending?.();
+    setComplete(false);
+    setFeedback(false);
+    const stop = publication.start(
+      root.current,
+      () => {
+        clearTimeout(feedbackTimer);
+        setFeedback(false);
+        setComplete(true);
+        callbacks.current.onReady();
+      },
+      (error) => callbacks.current.onFailure(error)
+    );
+    const feedbackTimer = setTimeout(() => setFeedback(true), PROGRESSIVE_MARKDOWN_FEEDBACK_MS);
+    return () => {
+      clearTimeout(feedbackTimer);
+      stop();
+    };
+  }, [heavy, publication]);
+
+  if (!heavy)
+    return (
+      <ReactMarkdown components={linkComponents} remarkPlugins={remarkPlugins} rehypePlugins={rehypePlugins}>
+        {children}
+      </ReactMarkdown>
+    );
+  return (
+    <div ref={root} aria-busy={!complete} data-markdown-publication={complete ? "complete" : "loading"}>
+      {stagedDocument}
+      {feedback && !complete && (
+        <Box
+          role="status"
+          aria-label={t("app.loading")}
+          sx={{
+            position: "sticky",
+            bottom: 8,
+            height: 20,
+            marginTop: "-20px",
+            display: "flex",
+            justifyContent: "flex-end",
+            pointerEvents: "none",
+            "@media (prefers-reduced-motion: reduce)": {
+              "& .MuiCircularProgress-root, & .MuiCircularProgress-circle": { animation: "none" },
+            },
+          }}
+        >
+          <CircularProgress size={20} disableShrink />
+        </Box>
+      )}
+    </div>
+  );
+}
diff --git a/frontend/src/components/Viewer/RetainedMarkdownPreview.tsx b/frontend/src/components/Viewer/RetainedMarkdownPreview.tsx
new file mode 100644
index 000000000..66d35b247
--- /dev/null
+++ b/frontend/src/components/Viewer/RetainedMarkdownPreview.tsx
@@ -0,0 +1,136 @@
+import { useLayoutEffect, useRef, useState } from "react";
+import { error as logError } from "../../services/logger";
+import { syntaxTokenStyles } from "../../theme/syntaxStyles";
+import { openExternalUrl } from "../../utils/externalLinks";
+import type { PreparationResponse } from "../../utils/markdownCodePreparation";
+import { mountMarkdownDocument } from "../../utils/markdownDocumentPreview";
+import { recordMarkdownPreparation } from "../../utils/markdownSyntax";
+
+type DocumentView = Awaited<ReturnType<typeof mountMarkdownDocument>>;
+
+interface RetainedDocumentPreparation {
+  syntaxSession: Parameters<DocumentView["finish"]>[2];
+  syntaxRanges: number;
+  documentTimings?: unknown;
+  transportTimings?: unknown;
+}
+
+export interface RetainedMarkdownPreviewProps {
+  generation: { id: number; source: string };
+  onExternalLink: () => void;
+  resolveLink: (href: string) => string | null;
+  prepareDocument: (request: {
+    source: string;
+    generation: number;
+    signal: AbortSignal;
+    onRecords: DocumentView["consume"];
+    onDiagnostic: (diagnostic: Extract<PreparationResponse, { type: "diagnostic" }>) => void;
+  }) => Promise<RetainedDocumentPreparation>;
+}
+
+export function RetainedMarkdownPreview({ generation, onExternalLink, resolveLink, prepareDocument }: RetainedMarkdownPreviewProps) {
+  const host = useRef<HTMLDivElement>(null);
+  const [failure, setFailure] = useState<{ generation: number; message: string } | null>(null);
+  useLayoutEffect(() => {
+    const element = host.current;
+    const viewport = element?.parentElement?.parentElement;
+    if (!element || !viewport) return;
+    const controller = new AbortController();
+    const prefix = `markdown-retained-${generation.id}`;
+    let view: DocumentView | undefined;
+    let syntaxSession: RetainedDocumentPreparation["syntaxSession"] | undefined;
+    const style = document.createElement("style");
+    style.textContent = Object.entries(syntaxTokenStyles)
+      .map(
+        ([selector, properties]) =>
+          `::highlight(${prefix}-${selector.slice(".sambee-syntax-".length)}){color:${properties.color ?? "inherit"}}`
+      )
+      .join("\n");
+    document.head.append(style);
+    element.dataset["markdownRetainedState"] = "pending";
+    const configureLink = (anchor: HTMLAnchorElement, href: string) => {
+      const resolved = resolveLink(href);
+      if (!resolved) {
+        anchor.removeAttribute("href");
+        return;
+      }
+      anchor.setAttribute("href", resolved);
+      if (!resolved.startsWith("#")) {
+        anchor.target = "_blank";
+        anchor.rel = "noopener noreferrer";
+      }
+    };
+    const click = (event: MouseEvent) => {
+      const anchor = event.target instanceof Element ? event.target.closest("a") : null;
+      const href = anchor?.getAttribute("href");
+      if (!href || href.startsWith("#")) return;
+      event.preventDefault();
+      const resolved = resolveLink(href);
+      if (!resolved) return;
+      openExternalUrl(resolved);
+      onExternalLink();
+    };
+    element.addEventListener("click", click);
+    const start = performance.now();
+    void (async () => {
+      const mountedView = await mountMarkdownDocument(element, controller.signal, generation.source, {
+        hostSearch: true,
+        viewport,
+        highlightPrefix: prefix,
+        configureLink,
+      });
+      view = mountedView;
+      controller.signal.throwIfAborted();
+      const result = await prepareDocument({
+        source: generation.source,
+        generation: generation.id,
+        signal: controller.signal,
+        onDiagnostic: (diagnostic) => {
+          logError(
+            diagnostic.message,
+            diagnostic.context,
+            diagnostic.component,
+            diagnostic.error ? new Error(diagnostic.error.message) : undefined
+          );
+        },
+        onRecords: (records) => mountedView.consume(records),
+      });
+      syntaxSession = result.syntaxSession;
+      controller.signal.throwIfAborted();
+      if (!syntaxSession) throw new Error("Retained Markdown preparation returned no syntax session");
+      view.finish(performance.now() - start, result.syntaxRanges, syntaxSession);
+      recordMarkdownPreparation("retained-document-complete", start);
+      Object.defineProperty(element, "retainedMarkdownStats", {
+        configurable: true,
+        value: () => ({ ...view?.stats(), documentTimings: result.documentTimings, transportTimings: result.transportTimings }),
+      });
+      element.dataset["markdownRetainedState"] = "complete";
+    })().catch((error: unknown) => {
+      syntaxSession?.dispose();
+      view?.dispose();
+      if (controller.signal.aborted) return;
+      element.dataset["markdownRetainedState"] = "failed";
+      logError(
+        "Retained Markdown preview failed",
+        { operation: "prepare-document" },
+        "MarkdownViewer",
+        error instanceof Error ? error : undefined
+      );
+      setFailure({ generation: generation.id, message: error instanceof Error ? error.message : "Markdown preview failed" });
+    });
+    return () => {
+      controller.abort();
+      syntaxSession?.dispose();
+      view?.dispose();
+      element.removeEventListener("click", click);
+      style.remove();
+      Reflect.deleteProperty(element, "retainedMarkdownStats");
+    };
+  }, [generation, onExternalLink, resolveLink, prepareDocument]);
+  return (
+    <>
+      <div ref={host} data-markdown-retained-root="true" />
+      {failure?.generation === generation.id ? <div role="alert">{failure.message}</div> : null}
+    </>
+  );
+}
diff --git a/frontend/src/components/Viewer/TextCodeEditor.tsx b/frontend/src/components/Viewer/TextCodeEditor.tsx
index a36170a49..8b348282f 100644
--- a/frontend/src/components/Viewer/TextCodeEditor.tsx
+++ b/frontend/src/components/Viewer/TextCodeEditor.tsx
@@ -1,21 +1,25 @@
-import { LanguageDescription } from "@codemirror/language";
-import { languages } from "@codemirror/language-data";
-import { findNext, findPrevious, replaceAll, replaceNext } from "@codemirror/search";
 import type { Extension } from "@codemirror/state";
 import { forwardRef, useCallback, useEffect, useImperativeHandle, useMemo, useRef, useState } from "react";
+import { loadNativeLanguage, resolveFilename } from "../../utils/codeMirrorHighlighting";
 import { buildPassiveSearchHighlightExtension } from "../Editor/buildCodeMirrorSearchHighlights";
 import { buildCommonEditorExtensions } from "../Editor/buildCommonEditorExtensions";
 import { buildTextEditorTheme, type TextEditorThemeOptions } from "../Editor/buildTextEditorTheme";
 import { SourceTextEditor } from "../Editor/SourceTextEditor";
-import type { SourceTextEditorHandle } from "../Editor/sourceTextEditorTypes";
+import type { SourceTextEditorHandle, SourceTextSnapshot } from "../Editor/sourceTextEditorTypes";
 import {
+  findNext,
+  findPrevious,
   getCodeMirrorFindReplaceMetrics,
+  replaceAll,
+  replaceNext,
   shouldAutoNavigateCodeMirrorFindReplace,
   updateCodeMirrorFindReplaceQuery,
 } from "./codeMirrorFindReplace";
 
 export interface TextCodeEditorHandle {
   focus: () => void;
+  captureSnapshot: (signal?: AbortSignal) => Promise<SourceTextSnapshot>;
+  captureSnapshotSync: () => SourceTextSnapshot;
   flushPendingEdits: () => Promise<void>;
   getCanonicalText: () => string;
   getPrimarySelectionText: () => string;
@@ -29,6 +33,8 @@ export interface TextCodeEditorHandle {
 }
 
 export interface TextCodeEditorSearchState {
+  pending?: boolean;
+  error?: string;
   searchText: string;
   searchMatches: number;
   currentMatch: number;
@@ -96,7 +102,7 @@ export const TextCodeEditor = forwardRef<TextCodeEditorHandle, TextCodeEditorPro
     } | null>(null);
     const extensions = useMemo(
       () => [
-        ...buildCommonEditorExtensions({ highlightSelectionMatches: false, lineWrapping }),
+        ...buildCommonEditorExtensions({ defaultSyntaxHighlighting: false, highlightSelectionMatches: false, lineWrapping }),
         ...buildTextEditorTheme(theme),
         buildPassiveSearchHighlightExtension(),
         ...languageExtensions,
@@ -105,15 +111,14 @@ export const TextCodeEditor = forwardRef<TextCodeEditorHandle, TextCodeEditorPro
     );
     useEffect(() => {
       let cancelled = false;
-      const languageDescription = LanguageDescription.matchFilename(languages, filename);
+      const resolved = resolveFilename(filename);
 
-      if (!languageDescription) {
+      if (!("language" in resolved)) {
         setLanguageExtensions(EMPTY_EXTENSIONS);
         return;
       }
 
-      void languageDescription
-        .load()
+      void loadNativeLanguage(resolved.language)
         .then((support) => {
           if (cancelled) {
             return;
@@ -139,6 +144,8 @@ export const TextCodeEditor = forwardRef<TextCodeEditorHandle, TextCodeEditorPro
 
       const metrics = getCodeMirrorFindReplaceMetrics(editorRef.current?.getView());
       onSearchStateChange({
+        pending: metrics.pending,
+        error: metrics.error,
         searchText: searchOpen ? searchText : "",
         searchMatches: searchOpen ? metrics.matches : 0,
         currentMatch: searchOpen ? metrics.currentMatch : 0,
@@ -196,12 +203,23 @@ export const TextCodeEditor = forwardRef<TextCodeEditorHandle, TextCodeEditorPro
       searchWholeWord,
     ]);
 
+    const captureSnapshotSync = useCallback((): SourceTextSnapshot => {
+      const editor = editorRef.current;
+      if (!editor) throw new Error("Cannot capture a snapshot after the text editor is disposed");
+      return editor.captureSnapshot();
+    }, []);
+
     useImperativeHandle(
       ref,
       () => ({
         focus: () => {
           editorRef.current?.focus();
         },
+        captureSnapshot: async (signal) => {
+          signal?.throwIfAborted();
+          return captureSnapshotSync();
+        },
+        captureSnapshotSync,
         flushPendingEdits: async () => {},
         getCanonicalText: () => editorRef.current?.getValue() ?? text,
         getPrimarySelectionText: () => editorRef.current?.getPrimarySelectionText() ?? "",
@@ -230,7 +248,7 @@ export const TextCodeEditor = forwardRef<TextCodeEditorHandle, TextCodeEditorPro
           reportSearchState();
         },
       }),
-      [reportSearchState, text]
+      [captureSnapshotSync, reportSearchState, text]
     );
 
     return (
diff --git a/frontend/src/components/Viewer/TextViewer.tsx b/frontend/src/components/Viewer/TextViewer.tsx
index a690ccd99..b9b33d4d2 100644
--- a/frontend/src/components/Viewer/TextViewer.tsx
+++ b/frontend/src/components/Viewer/TextViewer.tsx
@@ -101,6 +101,8 @@ function areTextEditorSearchStatesEqual(left: TextCodeEditorSearchState, right:
     left.isSearchOpen === right.isSearchOpen &&
     left.isSearchable === right.isSearchable &&
     left.isValid === right.isValid &&
+    left.pending === right.pending &&
+    left.error === right.error &&
     left.viewMode === right.viewMode
   );
 }
@@ -246,6 +248,7 @@ export const TextViewer: React.FC<ViewerComponentProps> = ({
     clearPendingBaselineSync,
     handleEditorChange,
     handleEditorUserEdit,
+    getEditGeneration,
     markEditSessionPristine,
     requestRestoreEditingFocus,
   } = useMarkdownEditSession({
@@ -294,9 +297,9 @@ export const TextViewer: React.FC<ViewerComponentProps> = ({
         }
 
         if (checkIsTransientError(err)) {
-          setError(getTransientErrorMessage(err, translationRef.current("errors.failedToLoadFile")));
+          setError(getTransientErrorMessage());
         } else {
-          setError(getApiErrorMessage(err, translationRef.current("errors.failedToLoadFile"), { includeOriginalMessage: true }));
+          setError(getApiErrorMessage(err, translationRef.current("viewer.text.loadFailed"), { includeOriginalMessage: true }));
         }
       } finally {
         if (!abortController.signal.aborted) {
@@ -312,51 +315,51 @@ export const TextViewer: React.FC<ViewerComponentProps> = ({
     };
   }, [connectionId, contentProviders, fetchWithRetry, isReadOnly, path, setEditBaselineContent, virtualSource]);
 
-  useEffect(() => {
-    if (!isEditing) {
+  const snapshotDraft = useCallback(() => {
+    if (!isEditingRef.current) {
       return;
     }
 
-    if (draftContent === editBaselineContentRef.current) {
-      clearDraft(connectionId, path, "text");
-      setDraftStorageWarning(null);
-      return;
-    }
-
-    const timeoutId = window.setTimeout(() => {
-      const result = saveDraft(connectionId, path, "text", editBaselineContentRef.current, draftContent);
-      if (result.saved || result.reason === "no-user") {
+    try {
+      const editor = editorRef.current;
+      if (!editor) throw new Error("The text editor is not mounted");
+      const latestContent = editor.captureSnapshotSync().serialize();
+      if (latestContent === editBaselineContentRef.current) {
+        clearDraft(connectionId, path, "text");
         setDraftStorageWarning(null);
-        return;
+      } else {
+        const result = saveDraft(connectionId, path, "text", editBaselineContentRef.current, latestContent);
+        if (result.saved || result.reason === "no-user") {
+          setDraftStorageWarning(null);
+        } else {
+          setDraftStorageWarning(
+            result.reason === "too-large" ? t("viewer.edit.recovery.tooLargeWarning") : t("viewer.edit.recovery.storageUnavailableWarning")
+          );
+        }
       }
+    } catch (error) {
+      logError("Text recovery snapshot failed; keep the editor open and save the file", { error, connectionId, path });
+    }
+  }, [connectionId, path, t]);
 
-      setDraftStorageWarning(
-        result.reason === "too-large" ? t("viewer.edit.recovery.tooLargeWarning") : t("viewer.edit.recovery.storageUnavailableWarning")
-      );
-    }, DRAFT_SNAPSHOT_DEBOUNCE_MS);
-
+  useEffect(() => {
+    if (!isEditing) return;
+    if (draftContent === editBaselineContentRef.current) {
+      snapshotDraft();
+      return;
+    }
+    const timeoutId = window.setTimeout(snapshotDraft, DRAFT_SNAPSHOT_DEBOUNCE_MS);
     return () => window.clearTimeout(timeoutId);
-  }, [connectionId, draftContent, isEditing, path, t]);
+  }, [draftContent, isEditing, snapshotDraft]);
 
   useEffect(() => {
-    const snapshot = () => {
-      if (!isEditingRef.current) {
-        return;
-      }
-
-      if (draftContent === editBaselineContentRef.current) {
-        clearDraft(connectionId, path, "text");
-      } else {
-        saveDraft(connectionId, path, "text", editBaselineContentRef.current, draftContent);
-      }
-    };
-    const unregister = registerDraftSnapshot(snapshot);
-    window.addEventListener("pagehide", snapshot);
+    const unregister = registerDraftSnapshot(snapshotDraft);
+    window.addEventListener("pagehide", snapshotDraft);
     return () => {
       unregister();
-      window.removeEventListener("pagehide", snapshot);
+      window.removeEventListener("pagehide", snapshotDraft);
     };
-  }, [connectionId, draftContent, path]);
+  }, [snapshotDraft]);
 
   const releaseEditSession = useCallback(async () => {
     const session = editSessionRef.current;
@@ -414,7 +417,7 @@ export const TextViewer: React.FC<ViewerComponentProps> = ({
     loadFile: loadShareFile,
   });
 
-  const handleDownload = useCallback(async () => {
+  const handleDownload = useCallback(async (): Promise<void> => {
     try {
       if (virtualSource) {
         downloadViewerBlob(await readVirtualContent(virtualSource, path, { download: true }, contentProviders), filename);
@@ -590,27 +593,30 @@ export const TextViewer: React.FC<ViewerComponentProps> = ({
       setIsSaving(true);
 
       try {
-        let savedContent = draftContent;
-        if (editorRef.current) {
-          await editorRef.current.flushPendingEdits();
-          savedContent = editorRef.current.getCanonicalText();
-        }
+        const editor = editorRef.current;
+        if (!editor) throw new Error("Text editor is no longer available for saving");
+        const saveGeneration = getEditGeneration();
+        const snapshot = await editor.captureSnapshot();
+        const savedContent = snapshot.serialize();
 
         if (!editSession) throw new Error("Edit session is no longer active");
         await editSession.writeText(savedContent);
+        const hasNewerEdits = getEditGeneration() !== saveGeneration && editor.getCanonicalText() !== savedContent;
         setContent(savedContent);
         setShareRevision((revision) => revision + 1);
-        setDraftContent(savedContent);
         setEditBaselineContent(savedContent);
         clearBaselineSyncWindow();
-        markEditSessionPristine();
-        clearDraft(connectionId, path, "text");
+        if (!hasNewerEdits) {
+          setDraftContent(savedContent);
+          markEditSessionPristine();
+          clearDraft(connectionId, path, "text");
+        }
 
-        if (afterSave === "cancel-edit") {
+        if (afterSave === "cancel-edit" && !hasNewerEdits) {
           await exitEditMode(savedContent);
         }
 
-        return true;
+        return !hasNewerEdits;
       } catch (err) {
         setEditError(getApiErrorMessage(err, t("viewer.text.saveFailed"), { includeOriginalMessage: true }));
         logError("Failed to save text file", { error: err, path, connectionId });
@@ -627,9 +633,9 @@ export const TextViewer: React.FC<ViewerComponentProps> = ({
     [
       clearBaselineSyncWindow,
       connectionId,
-      draftContent,
       editSession,
       exitEditMode,
+      getEditGeneration,
       isEditing,
       isReadOnly,
       markEditSessionPristine,
@@ -740,22 +746,22 @@ export const TextViewer: React.FC<ViewerComponentProps> = ({
   );
 
   const handleSearchNext = useCallback(() => {
-    if (searchMatches === 0) {
+    if (searchMatches === 0 && !editorSearchState.pending && !editorSearchState.error) {
       return;
     }
 
     editorRef.current?.focusCurrentSearchResult();
     editorRef.current?.nextSearchResult();
-  }, [searchMatches]);
+  }, [searchMatches, editorSearchState.pending, editorSearchState.error]);
 
   const handleSearchPrevious = useCallback(() => {
-    if (searchMatches === 0) {
+    if (searchMatches === 0 && !editorSearchState.pending && !editorSearchState.error) {
       return;
     }
 
     editorRef.current?.focusCurrentSearchResult();
     editorRef.current?.previousSearchResult();
-  }, [searchMatches]);
+  }, [searchMatches, editorSearchState.pending, editorSearchState.error]);
 
   const handleReplaceCurrent = useCallback(() => {
     if (!isEditing || isSaving) {
@@ -826,7 +832,11 @@ export const TextViewer: React.FC<ViewerComponentProps> = ({
       },
       { ...COMMON_SHORTCUTS.NEXT_MATCH, handler: handleSearchNext, enabled: !isEditing && searchMatches > 0 },
       { ...COMMON_SHORTCUTS.PREVIOUS_MATCH, handler: handleSearchPrevious, enabled: !isEditing && searchMatches > 0 },
-      { ...COMMON_SHORTCUTS.EDIT, handler: () => void handleEnterEditMode(), enabled: !isEditing && !isReadOnly && !exceedsEditorLimit },
+      {
+        ...COMMON_SHORTCUTS.EDIT,
+        handler: (): void => void handleEnterEditMode(),
+        enabled: !isEditing && !isReadOnly && !exceedsEditorLimit,
+      },
       { ...VIEWER_SHORTCUTS.FULLSCREEN, handler: handleToggleFullscreen, enabled: !isEditing },
       { ...COMMON_SHORTCUTS.CLOSE, handler: handleEscape, allowInInput: false, enabled: !isEditing && !unsavedChangesDialogOpen },
       { ...BROWSER_SHORTCUTS.SHOW_HELP, handler: () => setShowViewerHelp(true), enabled: !isEditing },
@@ -894,14 +904,24 @@ export const TextViewer: React.FC<ViewerComponentProps> = ({
         handler: () => setWordWrapEnabled(!wordWrapEnabled),
         enabled: !loading && !error && !exceedsEditorLimit,
       },
-      { ...COMMON_SHORTCUTS.NEXT_MATCH, handler: handleSearchNext, enabled: isEditing && searchMatches > 0 },
-      { ...COMMON_SHORTCUTS.PREVIOUS_MATCH, handler: handleSearchPrevious, enabled: isEditing && searchMatches > 0 },
-      { ...COMMON_SHORTCUTS.SAVE, handler: () => void handleSave(), allowInInput: true, enabled: isEditing && !isSaving },
+      {
+        ...COMMON_SHORTCUTS.NEXT_MATCH,
+        handler: handleSearchNext,
+        enabled: isEditing && (searchMatches > 0 || Boolean(editorSearchState.pending || editorSearchState.error)),
+      },
+      {
+        ...COMMON_SHORTCUTS.PREVIOUS_MATCH,
+        handler: handleSearchPrevious,
+        enabled: isEditing && (searchMatches > 0 || Boolean(editorSearchState.pending || editorSearchState.error)),
+      },
+      { ...COMMON_SHORTCUTS.SAVE, handler: (): void => void handleSave(), allowInInput: true, enabled: isEditing && !isSaving },
       { ...COMMON_SHORTCUTS.CLOSE, handler: handleEscape, allowInInput: false, enabled: isEditing && !unsavedChangesDialogOpen },
       { ...BROWSER_SHORTCUTS.SHOW_HELP_ALTERNATE, handler: () => setShowEditorHelp(true), enabled: isEditing },
     ],
     [
       editorSearchState.isSearchable,
+      editorSearchState.pending,
+      editorSearchState.error,
       error,
       exceedsEditorLimit,
       handleDownload,
@@ -1118,6 +1138,8 @@ export const TextViewer: React.FC<ViewerComponentProps> = ({
             focusTarget={searchFocusTarget}
             isReplaceMode={searchMode === "replace"}
             isSearchValid={editorSearchState.isValid}
+            searchPending={editorSearchState.pending}
+            searchError={editorSearchState.error}
             onCaseSensitiveChange={setSearchCaseSensitive}
             onClose={() => closeSearchPanel({ preserveQuery: true, restoreEditorFocus: true })}
             onFindNext={handleSearchNext}
diff --git a/frontend/src/components/Viewer/__tests__/ImageViewer.test.tsx b/frontend/src/components/Viewer/__tests__/ImageViewer.test.tsx
index 38c8d81be..a844d81b4 100644
--- a/frontend/src/components/Viewer/__tests__/ImageViewer.test.tsx
+++ b/frontend/src/components/Viewer/__tests__/ImageViewer.test.tsx
@@ -287,7 +287,7 @@ describe("ImageViewer", () => {
       currentImageLoadPhase: "decoding" as const,
       imageSourceRevision: 0,
       markImageAsDecoded,
-      getCachedImageSrc: () => undefined,
+      getCachedImageSrc: (): string | undefined => undefined,
     };
     mockUseCachedImageGallery.mockImplementation(() => gallery);
 
diff --git a/frontend/src/components/Viewer/__tests__/MarkdownRichEditor.test.tsx b/frontend/src/components/Viewer/__tests__/MarkdownRichEditor.test.tsx
index 28ae1545f..0fb3bccfa 100644
--- a/frontend/src/components/Viewer/__tests__/MarkdownRichEditor.test.tsx
+++ b/frontend/src/components/Viewer/__tests__/MarkdownRichEditor.test.tsx
@@ -1,11 +1,75 @@
-import { render, screen, waitFor } from "@testing-library/react";
+import { undo } from "@codemirror/commands";
+import { getSearchQuery } from "@codemirror/search";
+import { EditorView } from "@codemirror/view";
+import { act, render, screen, waitFor } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
-import { createRef } from "react";
-import { describe, expect, it, vi } from "vitest";
+import { createRef, useLayoutEffect } from "react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { authSession } from "../../../services/authSession";
+import { createDraftCheckpointController, DRAFT_TRANSITION_FLUSH_MS } from "../../../services/draftCheckpoint";
+import { loadDraft } from "../../../services/draftRecovery";
+import { requireTestValue } from "../../../test/helpers/assertions";
+import type { PreparationRequest, PreparationResponse } from "../../../utils/markdownCodePreparation";
 import type { MarkdownEditorThemeOptions } from "../../Editor/buildMarkdownEditorTheme";
-import MarkdownRichEditor, { type MarkdownRichEditorHandle, type MarkdownRichEditorSearchState } from "../MarkdownRichEditor";
+import { getCodeMirrorFindReplaceMetrics } from "../codeMirrorFindReplace";
+import MarkdownRichEditor, {
+  MARKDOWN_SOURCE_MEASURES,
+  type MarkdownRichEditorHandle,
+  type MarkdownRichEditorSearchState,
+} from "../MarkdownRichEditor";
+import { normalizeMarkdownTableCellLineBreaks, preserveUnchangedMarkdownTableSource } from "../markdownTableCellLineBreaks";
+
+class EditNormalizationWorker extends EventTarget {
+  static instances: EditNormalizationWorker[] = [];
+  static hold = false;
+  onmessage: ((event: MessageEvent<PreparationResponse>) => void) | null = null;
+  source = "";
+  baseline = "";
+  preserveTableSource = false;
+  preserveOnly = false;
+  generation = 0;
+  terminated = false;
+  constructor() {
+    super();
+    EditNormalizationWorker.instances.push(this);
+  }
+  postMessage(message: PreparationRequest) {
+    queueMicrotask(() => {
+      if (this.terminated) return;
+      this.generation = message.generation;
+      if (message.type === "prepare") {
+        this.preserveTableSource = message.preserveTableSource === true;
+        this.preserveOnly = message.preserveOnly === true;
+        this.receive({ type: "source-ack", generation: this.generation, sequence: 0 });
+      } else if (message.type === "source") {
+        if (message.block === 0) this.source += message.text;
+        else this.baseline += message.text;
+        this.receive({ type: "source-ack", generation: this.generation, sequence: message.sequence });
+      } else if (message.type === "run" && !EditNormalizationWorker.hold) this.complete();
+    });
+  }
+  receive(response: PreparationResponse) {
+    this.onmessage?.(new MessageEvent("message", { data: response }));
+  }
+  complete() {
+    const normalized = this.preserveOnly ? this.source : normalizeMarkdownTableCellLineBreaks(this.source);
+    this.receive({
+      type: "normalized-source",
+      generation: this.generation,
+      sequence: 1,
+      text: this.preserveTableSource ? preserveUnchangedMarkdownTableSource(this.baseline, normalized) : normalized,
+      final: true,
+    });
+    this.receive({ type: "complete", generation: this.generation, preparationMs: 1 });
+  }
+  terminate() {
+    this.terminated = true;
+  }
+}
 
 const TEST_MARKDOWN_THEME: MarkdownEditorThemeOptions = {
+  currentSearchMatchBackground: "rgba(244, 196, 48, 0.32)",
+  otherSearchMatchBackground: "rgba(244, 196, 48, 0.18)",
   activeLineBackground: "rgba(244, 196, 48, 0.18)",
   borderColor: "rgba(31, 38, 43, 0.16)",
   isDarkMode: false,
@@ -39,7 +103,823 @@ function appendNestedEditorTarget(editor: HTMLElement): HTMLElement {
   return nestedEditable;
 }
 
+function signalClipboardPreflight(nested: HTMLElement, clipboardEvent: string): void {
+  const root = nested.closest(".tbl-table-widget")?.closest(".cm-editor");
+  if (!root) throw new Error("Expected the root Markdown editor around a real table widget");
+  root.addEventListener(clipboardEvent, (event) => event.stopImmediatePropagation(), { capture: true, once: true });
+  nested.dispatchEvent(new Event(clipboardEvent, { bubbles: true }));
+}
+
 describe("MarkdownRichEditor", () => {
+  let location: ReturnType<typeof vi.spyOn>;
+  beforeEach(() => {
+    EditNormalizationWorker.instances = [];
+    EditNormalizationWorker.hold = false;
+    vi.stubGlobal("Worker", EditNormalizationWorker);
+    location = vi.spyOn(window.location, "toString").mockReturnValue("http://localhost:3000/");
+  });
+  afterEach(() => {
+    location.mockRestore();
+    vi.unstubAllGlobals();
+  });
+
+  it("keeps edits pending until only the latest worker revision is published and flushed", async () => {
+    EditNormalizationWorker.hold = true;
+    const editorRef = createRef<MarkdownRichEditorHandle>();
+    const onChange = vi.fn();
+    const onNormalizationStateChange = vi.fn();
+    render(
+      <MarkdownRichEditor
+        ref={editorRef}
+        markdown="start"
+        ariaLabel="Worker Markdown"
+        theme={TEST_MARKDOWN_THEME}
+        onChange={onChange}
+        onNormalizationStateChange={onNormalizationStateChange}
+      />
+    );
+    const view = EditorView.findFromDOM(screen.getByLabelText("Worker Markdown"));
+    const handle = editorRef.current;
+    if (!view || !handle) throw new Error("Expected a mounted Markdown editor");
+    act(() =>
+      view.dispatch({ changes: { from: 0, to: view.state.doc.length, insert: "| A |\n| - |\n| first<br>second |\n" }, userEvent: "input" })
+    );
+    await waitFor(() => expect(requireTestValue(EditNormalizationWorker.instances[0]).source).toContain("first<br>second"));
+    expect(onNormalizationStateChange).toHaveBeenLastCalledWith(true);
+    expect(onChange).not.toHaveBeenCalled();
+    expect(() => handle.captureSnapshotSync()).toThrow(/normalization/);
+    const captured = handle.captureSnapshot();
+    act(() => view.dispatch({ changes: { from: view.state.doc.length, insert: "latest" }, userEvent: "input" }));
+    await act(async () => requireTestValue(EditNormalizationWorker.instances[0]).complete());
+    await waitFor(() => expect(requireTestValue(EditNormalizationWorker.instances[1]).source).toContain("latest"));
+    expect(onChange).not.toHaveBeenCalled();
+    await act(async () => requireTestValue(EditNormalizationWorker.instances[1]).complete());
+    const snapshot = await captured;
+    expect(snapshot.serialize()).toContain("first<br />second");
+    expect(snapshot.serialize()).toContain("latest");
+    expect(onChange).toHaveBeenCalledTimes(1);
+    expect(onNormalizationStateChange).toHaveBeenLastCalledWith(false);
+    expect(view.state.doc.toString()).toContain("first<br>second");
+    act(() => view.dispatch({ changes: { from: view.state.doc.length, insert: " newer" }, userEvent: "input" }));
+    expect(snapshot.serialize()).not.toContain("newer");
+    expect(() => handle.captureSnapshotSync()).toThrow(/normalization/);
+  });
+
+  it("keeps failed normalization dirty and retries only on an explicit snapshot request", async () => {
+    EditNormalizationWorker.hold = true;
+    const editorRef = createRef<MarkdownRichEditorHandle>();
+    const onChange = vi.fn();
+    const onNormalizationStateChange = vi.fn();
+    render(
+      <MarkdownRichEditor
+        ref={editorRef}
+        markdown="start"
+        ariaLabel="Failed worker"
+        theme={TEST_MARKDOWN_THEME}
+        onChange={onChange}
+        onNormalizationStateChange={onNormalizationStateChange}
+      />
+    );
+    const view = EditorView.findFromDOM(screen.getByLabelText("Failed worker"));
+    const handle = editorRef.current;
+    if (!view || !handle) throw new Error("Expected the Markdown editor");
+    act(() => view.dispatch({ changes: { from: 0, to: view.state.doc.length, insert: "first<br>second" }, userEvent: "input" }));
+    await waitFor(() => expect(requireTestValue(EditNormalizationWorker.instances[0]).source).toContain("first<br>second"));
+    const worker = requireTestValue(EditNormalizationWorker.instances[0]);
+    await act(async () => worker.receive({ type: "error", generation: worker.generation, message: "normalization unavailable" }));
+    expect(onNormalizationStateChange).toHaveBeenLastCalledWith(true, expect.objectContaining({ message: "normalization unavailable" }));
+    expect(onChange).not.toHaveBeenCalled();
+    expect(() => handle.captureSnapshotSync()).toThrow("normalization unavailable");
+    expect(EditNormalizationWorker.instances).toHaveLength(1);
+    const retry = handle.captureSnapshot();
+    await waitFor(() => expect(requireTestValue(EditNormalizationWorker.instances[1]).source).toContain("first<br>second"));
+    await act(async () => requireTestValue(EditNormalizationWorker.instances[1]).complete());
+    expect((await retry).serialize()).toBe("first<br>second");
+    expect(onChange).toHaveBeenCalledTimes(1);
+    expect(view.state.doc.toString()).toContain("first<br>second");
+  });
+
+  it("cancels held normalization on an external document update without replaying a late result", async () => {
+    EditNormalizationWorker.hold = true;
+    const editorRef = createRef<MarkdownRichEditorHandle>();
+    const onChange = vi.fn();
+    const { rerender } = render(
+      <MarkdownRichEditor ref={editorRef} markdown="first" ariaLabel="Switching worker" theme={TEST_MARKDOWN_THEME} onChange={onChange} />
+    );
+    const view = EditorView.findFromDOM(screen.getByLabelText("Switching worker"));
+    if (!view) throw new Error("Expected the Markdown editor");
+    act(() =>
+      view.dispatch({ changes: { from: 0, to: view.state.doc.length, insert: "| A |\n| - |\n| first<br>second |\n" }, userEvent: "input" })
+    );
+    await waitFor(() => expect(requireTestValue(EditNormalizationWorker.instances[0]).source).toContain("first<br>second"));
+    const worker = requireTestValue(EditNormalizationWorker.instances[0]);
+    const late = worker.onmessage;
+    const cancelled = expect(editorRef.current?.captureSnapshot()).rejects.toMatchObject({ name: "AbortError" });
+    rerender(
+      <MarkdownRichEditor
+        ref={editorRef}
+        markdown="different document"
+        ariaLabel="Switching worker"
+        theme={TEST_MARKDOWN_THEME}
+        onChange={onChange}
+      />
+    );
+    await cancelled;
+    expect(worker.terminated).toBe(true);
+    await act(async () =>
+      late?.(new MessageEvent("message", { data: { type: "error", generation: worker.generation, message: "obsolete" } }))
+    );
+    expect(onChange).not.toHaveBeenCalled();
+    expect(view.state.doc.toString()).toBe("different document");
+    expect(editorRef.current?.captureSnapshotSync().serialize()).toBe("different document");
+  });
+
+  it("prepares immutable source-preserving bytes again when only the baseline changes", async () => {
+    const editorRef = createRef<MarkdownRichEditorHandle>();
+    const markdown = "Intro\n\n| A |\n| - |\n| foo |\n";
+    const oldBaseline = "Before\n\n| A |\n| --- |\n| foo |\n";
+    const newBaseline = "Before\n\n| A |\n| ----- |\n| foo |\n";
+    const { rerender } = render(
+      <MarkdownRichEditor
+        ref={editorRef}
+        markdown={markdown}
+        diffMarkdown={oldBaseline}
+        ariaLabel="Baseline snapshot"
+        theme={TEST_MARKDOWN_THEME}
+        onChange={() => {}}
+      />
+    );
+    const handle = editorRef.current;
+    if (!handle) throw new Error("Expected the Markdown editor");
+    const original = await handle.captureSnapshot();
+    expect(original.serialize()).toBe(preserveUnchangedMarkdownTableSource(oldBaseline, markdown));
+    EditNormalizationWorker.hold = true;
+    rerender(
+      <MarkdownRichEditor
+        ref={editorRef}
+        markdown={markdown}
+        diffMarkdown={newBaseline}
+        ariaLabel="Baseline snapshot"
+        theme={TEST_MARKDOWN_THEME}
+        onChange={() => {}}
+      />
+    );
+    expect(() => handle.captureSnapshotSync()).toThrow(/normalization/);
+    await waitFor(() => expect(EditNormalizationWorker.instances.at(-1)?.baseline).toBe(newBaseline));
+    await act(async () => EditNormalizationWorker.instances.at(-1)?.complete());
+    expect(handle.captureSnapshotSync().serialize()).toBe(preserveUnchangedMarkdownTableSource(newBaseline, markdown));
+    expect(original.serialize()).toBe(preserveUnchangedMarkdownTableSource(oldBaseline, markdown));
+  });
+
+  it("normalizes whole-document Save snapshots through the worker after the typing fast path", async () => {
+    const editorRef = createRef<MarkdownRichEditorHandle>();
+    render(
+      <MarkdownRichEditor ref={editorRef} markdown="start" ariaLabel="Canonical Save" theme={TEST_MARKDOWN_THEME} onChange={() => {}} />
+    );
+    const view = EditorView.findFromDOM(screen.getByLabelText("Canonical Save"));
+    if (!view) throw new Error("Expected the Markdown editor");
+    act(() =>
+      view.dispatch({
+        changes: { from: 0, to: view.state.doc.length, insert: "* first\n* second\n\n1. first\n2. second\n" },
+        userEvent: "input",
+      })
+    );
+    const snapshot = await editorRef.current?.captureSnapshot();
+    expect(snapshot?.serialize()).toBe("- first\n- second\n\n1. first\n1. second\n");
+    expect(EditNormalizationWorker.instances).toHaveLength(1);
+    expect(requireTestValue(EditNormalizationWorker.instances[0]).terminated).toBe(true);
+  });
+
+  it("does not replay a canonical echo over an edit delivered before passive effects", () => {
+    const onChange = vi.fn();
+    function ControlledEditor({ markdown }: { markdown: string }) {
+      useLayoutEffect(() => {
+        if (markdown !== "initial updated") return;
+        const view = EditorView.findFromDOM(screen.getByRole("textbox", { name: "Rapid canonical editor" }));
+        if (!view) throw new Error("Expected a mounted Markdown editor");
+        view.dispatch({ changes: { from: view.state.doc.length, insert: " next" } });
+      }, [markdown]);
+      return <MarkdownRichEditor markdown={markdown} ariaLabel="Rapid canonical editor" theme={TEST_MARKDOWN_THEME} onChange={onChange} />;
+    }
+    const { rerender } = render(<ControlledEditor markdown="initial" />);
+    const view = EditorView.findFromDOM(screen.getByRole("textbox", { name: "Rapid canonical editor" }));
+    if (!view) throw new Error("Expected a mounted Markdown editor");
+    act(() => view.dispatch({ changes: { from: view.state.doc.length, insert: " updated" } }));
+    rerender(<ControlledEditor markdown="initial updated" />);
+    expect(view.state.doc.toString()).toBe("initial updated next");
+    expect(onChange).toHaveBeenCalledTimes(2);
+  });
+
+  it("measures normalization and synchronous parent updates without retaining document content", async () => {
+    const user = userEvent.setup();
+    const onChange = vi.fn();
+    const measure = vi.spyOn(performance, "measure");
+    const clearMeasures = vi.spyOn(performance, "clearMeasures");
+    try {
+      render(<MarkdownRichEditor markdown="alpha" ariaLabel="Measured Markdown" theme={TEST_MARKDOWN_THEME} onChange={onChange} />);
+      await user.click(await screen.findByLabelText("Measured Markdown"));
+      await user.keyboard("!");
+      const canonical = onChange.mock.calls.at(-1)?.[0];
+      expect(canonical).toContain("!");
+      for (const name of Object.values(MARKDOWN_SOURCE_MEASURES)) {
+        expect(clearMeasures).toHaveBeenCalledWith(name);
+        expect(measure).toHaveBeenCalledWith(name, {
+          start: expect.any(Number),
+          detail: { documentUnits: canonical.length, canonicalUnits: canonical.length },
+        });
+      }
+    } finally {
+      measure.mockRestore();
+      clearMeasures.mockRestore();
+    }
+  });
+
+  it.each([true, false])("captures only final composition text with publication before compositionend %s", async (publishedBeforeEnd) => {
+    const user = userEvent.setup();
+    const editorRef = createRef<MarkdownRichEditorHandle>();
+    render(
+      <MarkdownRichEditor
+        ref={editorRef}
+        markdown={"Intro\n\n| A |\n| - |\n| foo |\n\ntail"}
+        ariaLabel="Nested composition"
+        theme={TEST_MARKDOWN_THEME}
+        onChange={() => {}}
+      />
+    );
+    await user.click(await screen.findByText("foo"));
+    await waitFor(() => expect(document.querySelector(".tbl-cell-editor .cm-content")).not.toBeNull());
+    const nested = document.querySelector<HTMLElement>(".tbl-cell-editor .cm-content");
+    const view = nested && EditorView.findFromDOM(nested);
+    const handle = editorRef.current;
+    if (!nested || !view || !handle) throw new Error("Expected a mounted nested composition editor");
+    nested.dispatchEvent(new CompositionEvent("compositionstart", { bubbles: true }));
+    expect(() => handle.captureSnapshotSync()).toThrow(/composition/);
+    await expect(handle.captureSnapshot()).rejects.toMatchObject({ name: "InvalidStateError" });
+    nested.dispatchEvent(
+      new InputEvent("beforeinput", { bubbles: true, inputType: "insertCompositionText", data: "intermediate", isComposing: true })
+    );
+    await act(async () => {
+      view.dispatch({ changes: { from: 0, to: view.state.doc.length, insert: "intermediate" }, userEvent: "input.type.compose" });
+    });
+    await waitFor(() => expect(handle.getCanonicalMarkdown()).toContain("intermediate"));
+    await expect(handle.captureSnapshot()).rejects.toMatchObject({ name: "InvalidStateError" });
+    const publishFinal = async () => {
+      nested.dispatchEvent(
+        new InputEvent("beforeinput", { bubbles: true, inputType: "insertCompositionText", data: "finished", isComposing: true })
+      );
+      await act(async () => {
+        view.dispatch({ changes: { from: 0, to: view.state.doc.length, insert: "finished" }, userEvent: "input.type.compose" });
+      });
+    };
+    if (publishedBeforeEnd) {
+      await publishFinal();
+      await waitFor(() => expect(handle.getCanonicalMarkdown()).toContain("finished"));
+    }
+    nested.dispatchEvent(new CompositionEvent("compositionend", { bubbles: true, data: "finished" }));
+    const snapshot = handle.captureSnapshot();
+    if (!publishedBeforeEnd) await publishFinal();
+
+    expect((await snapshot).serialize()).toContain("finished");
+    expect((await snapshot).serialize()).not.toContain("intermediate");
+    expect(handle.captureSnapshotSync().serialize()).toContain("finished");
+  });
+
+  it.each([false, true])("flushes an identical composition commit only without unpublished DOM text %s", async (unpublishedDom) => {
+    const user = userEvent.setup();
+    const editorRef = createRef<MarkdownRichEditorHandle>();
+    render(
+      <MarkdownRichEditor
+        ref={editorRef}
+        markdown={"| A |\n| - |\n| foo |"}
+        ariaLabel="Repeated composition"
+        theme={TEST_MARKDOWN_THEME}
+        onChange={() => {}}
+      />
+    );
+    await user.click(await screen.findByText("foo"));
+    await waitFor(() => expect(document.querySelector(".tbl-cell-editor .cm-content")).not.toBeNull());
+    const nested = document.querySelector<HTMLElement>(".tbl-cell-editor .cm-content");
+    const view = nested && EditorView.findFromDOM(nested);
+    const handle = editorRef.current;
+    if (!nested || !view || !handle) throw new Error("Expected a mounted nested composition editor");
+    nested.dispatchEvent(new CompositionEvent("compositionstart", { bubbles: true }));
+    const input = () =>
+      nested.dispatchEvent(
+        new InputEvent("beforeinput", { bubbles: true, inputType: "insertCompositionText", data: "finished", isComposing: true })
+      );
+    input();
+    await act(async () => {
+      view.dispatch({ changes: { from: 0, to: view.state.doc.length, insert: "finished" }, userEvent: "input.type.compose" });
+    });
+    await waitFor(() => expect(handle.getCanonicalMarkdown()).toContain("finished"));
+    input();
+    const root = nested.closest(".tbl-table-widget")?.closest<HTMLElement>(".cm-editor");
+    const rootView = root && EditorView.findFromDOM(root);
+    if (!rootView) throw new Error("Expected the root Markdown editor");
+    const dispatch = unpublishedDom ? vi.spyOn(rootView, "dispatch").mockImplementation(() => {}) : null;
+    if (unpublishedDom) {
+      const line = nested.querySelector(".cm-line");
+      if (!line) throw new Error("Expected nested editor text");
+      line.textContent = "not published";
+    }
+    nested.dispatchEvent(new CompositionEvent("compositionend", { bubbles: true, data: "finished" }));
+    try {
+      if (unpublishedDom) {
+        const controller = new AbortController();
+        const pending = handle.captureSnapshot(controller.signal);
+        const rejected = expect(pending).rejects.toMatchObject({ name: "AbortError" });
+        controller.abort();
+        await rejected;
+      } else expect((await handle.captureSnapshot()).serialize()).toContain("finished");
+    } finally {
+      dispatch?.mockRestore();
+    }
+  });
+
+  it("does not acknowledge a finished composition while its root publication is stalled", async () => {
+    const user = userEvent.setup();
+    const editorRef = createRef<MarkdownRichEditorHandle>();
+    render(
+      <MarkdownRichEditor
+        ref={editorRef}
+        markdown={"Intro\n\n| A |\n| - |\n| foo |\n\ntail"}
+        ariaLabel="Stalled composition"
+        theme={TEST_MARKDOWN_THEME}
+        onChange={() => {}}
+      />
+    );
+    await user.click(await screen.findByText("foo"));
+    await waitFor(() => expect(document.querySelector(".tbl-cell-editor .cm-content")).not.toBeNull());
+    const nested = document.querySelector<HTMLElement>(".tbl-cell-editor .cm-content");
+    const root = nested?.closest(".tbl-table-widget")?.closest<HTMLElement>(".cm-editor");
+    const view = nested && EditorView.findFromDOM(nested);
+    const rootView = root && EditorView.findFromDOM(root);
+    const handle = editorRef.current;
+    if (!nested || !view || !rootView || !handle) throw new Error("Expected mounted nested and root editors");
+    const dispatch = vi.spyOn(rootView, "dispatch").mockImplementation(() => {});
+    const controller = new AbortController();
+    try {
+      nested.dispatchEvent(new CompositionEvent("compositionstart", { bubbles: true }));
+      nested.dispatchEvent(
+        new InputEvent("beforeinput", { bubbles: true, inputType: "insertCompositionText", data: "finished", isComposing: true })
+      );
+      await act(async () => {
+        view.dispatch({ changes: { from: 0, to: view.state.doc.length, insert: "finished" }, userEvent: "input.type.compose" });
+      });
+      nested.dispatchEvent(new CompositionEvent("compositionend", { bubbles: true, data: "finished" }));
+      expect(() => handle.captureSnapshotSync()).toThrow(/publishing/);
+      const captured = vi.fn();
+      const pending = handle.captureSnapshot(controller.signal).then(captured);
+      const rejected = expect(pending).rejects.toMatchObject({ name: "AbortError" });
+      await Promise.resolve();
+      expect(captured).not.toHaveBeenCalled();
+      expect(handle.getCanonicalMarkdown()).not.toContain("finished");
+      controller.abort();
+      await rejected;
+    } finally {
+      controller.abort();
+      dispatch.mockRestore();
+    }
+  });
+
+  it("captures unchanged source after an empty nested composition ends", async () => {
+    const user = userEvent.setup();
+    const editorRef = createRef<MarkdownRichEditorHandle>();
+    render(
+      <MarkdownRichEditor
+        ref={editorRef}
+        markdown={"Intro\n\n| A |\n| - |\n| foo |\n\ntail"}
+        ariaLabel="Empty composition"
+        theme={TEST_MARKDOWN_THEME}
+        onChange={() => {}}
+      />
+    );
+    await user.click(await screen.findByText("foo"));
+    await waitFor(() => expect(document.querySelector(".tbl-cell-editor .cm-content")).not.toBeNull());
+    const nested = document.querySelector<HTMLElement>(".tbl-cell-editor .cm-content");
+    const handle = editorRef.current;
+    if (!nested || !handle) throw new Error("Expected a mounted nested editor");
+    const original = await handle.captureSnapshot();
+    nested.dispatchEvent(new CompositionEvent("compositionstart", { bubbles: true }));
+    await expect(handle.captureSnapshot()).rejects.toMatchObject({ name: "InvalidStateError" });
+    nested.dispatchEvent(new CompositionEvent("compositionend", { bubbles: true, data: "" }));
+
+    const snapshot = await handle.captureSnapshot();
+    expect(snapshot.serialize()).toBe(original.serialize());
+    expect(snapshot.revision).toBe(original.revision);
+  });
+
+  it.each([
+    { whitespace: " ", clipboardEvent: null, inputType: "insertText" },
+    { whitespace: "\t", clipboardEvent: null, inputType: "insertText" },
+    { whitespace: "\n", clipboardEvent: null, inputType: "insertText" },
+    { whitespace: " ", clipboardEvent: "paste", inputType: "insertFromPaste" },
+    { whitespace: " ", clipboardEvent: "cut", inputType: "deleteByCut" },
+  ])("captures the unchanged root after $inputType with whitespace $whitespace", async ({ whitespace, clipboardEvent, inputType }) => {
+    const user = userEvent.setup();
+    const editorRef = createRef<MarkdownRichEditorHandle>();
+    render(
+      <MarkdownRichEditor
+        ref={editorRef}
+        markdown={"Intro\n\n| A |\n| - |\n| foo |\n\ntail"}
+        ariaLabel="Nested Markdown"
+        theme={TEST_MARKDOWN_THEME}
+        onChange={() => {}}
+      />
+    );
+    await user.click(await screen.findByText("foo"));
+    await waitFor(() => expect(document.querySelector(".tbl-cell-editor .cm-content")).not.toBeNull());
+    const nested = document.querySelector<HTMLElement>(".tbl-cell-editor .cm-content");
+    const nestedView = nested && EditorView.findFromDOM(nested);
+    const handle = editorRef.current;
+    if (!nested || !nestedView || !handle) throw new Error("Expected a mounted nested table editor");
+    if (clipboardEvent === "cut") {
+      nestedView.dispatch({ changes: { from: nestedView.state.doc.length, insert: whitespace }, userEvent: "input" });
+    }
+    const original = await handle.captureSnapshot();
+    if (clipboardEvent) {
+      signalClipboardPreflight(nested, clipboardEvent);
+    }
+    nested.dispatchEvent(new InputEvent("beforeinput", { bubbles: true, inputType, data: whitespace }));
+    nestedView.dispatch({
+      changes:
+        clipboardEvent === "cut"
+          ? { from: nestedView.state.doc.length - whitespace.length, to: nestedView.state.doc.length }
+          : { from: nestedView.state.doc.length, insert: whitespace },
+      userEvent: "input",
+    });
+    await Promise.resolve();
+    vi.useFakeTimers();
+    try {
+      const [snapshot] = await Promise.all([handle.captureSnapshot(), vi.advanceTimersByTimeAsync(DRAFT_TRANSITION_FLUSH_MS)]);
+      expect(snapshot.serialize()).toBe(original.serialize());
+      expect(snapshot.revision).toBe(original.revision);
+      expect(handle.getCanonicalMarkdown()).toBe(original.serialize());
+      expect(vi.getTimerCount()).toBe(0);
+    } finally {
+      vi.useRealTimers();
+    }
+    nestedView.dispatch({ changes: { from: 0, to: nestedView.state.doc.length, insert: "recovered" }, userEvent: "input" });
+    expect((await handle.captureSnapshot()).serialize()).toContain("recovered");
+  });
+
+  it.each([null, "paste"])("does not acknowledge an older unpublished input after clipboard preflight %j", async (clipboardEvent) => {
+    const user = userEvent.setup();
+    const editorRef = createRef<MarkdownRichEditorHandle>();
+    render(
+      <MarkdownRichEditor
+        ref={editorRef}
+        markdown={"Intro\n\n| A |\n| - |\n| foo |\n\ntail"}
+        ariaLabel="Nested Markdown"
+        theme={TEST_MARKDOWN_THEME}
+        onChange={() => {}}
+      />
+    );
+    await user.click(await screen.findByText("foo"));
+    await waitFor(() => expect(document.querySelector(".tbl-cell-editor .cm-content")).not.toBeNull());
+    const nested = document.querySelector<HTMLElement>(".tbl-cell-editor .cm-content");
+    const nestedView = nested && EditorView.findFromDOM(nested);
+    const handle = editorRef.current;
+    if (!nested || !nestedView || !handle) throw new Error("Expected a mounted nested table editor");
+    appendNestedEditorTarget(screen.getByLabelText("Nested Markdown")).dispatchEvent(
+      new InputEvent("beforeinput", { bubbles: true, inputType: "insertText", data: "pending" })
+    );
+    if (clipboardEvent) signalClipboardPreflight(nested, clipboardEvent);
+    nested.dispatchEvent(
+      new InputEvent("beforeinput", { bubbles: true, inputType: clipboardEvent ? "insertFromPaste" : "insertText", data: " " })
+    );
+    nestedView.dispatch({ changes: { from: nestedView.state.doc.length, insert: " " }, userEvent: "input" });
+    vi.useFakeTimers();
+    try {
+      await Promise.all([
+        expect(handle.captureSnapshot()).rejects.toMatchObject({ name: "TimeoutError" }),
+        vi.advanceTimersByTimeAsync(DRAFT_TRANSITION_FLUSH_MS),
+      ]);
+      expect(handle.getCanonicalMarkdown()).toContain("foo");
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it.each([
+    { inputType: "insertText", interveningChange: false },
+    { inputType: "deleteByCut", interveningChange: false },
+    { inputType: "insertFromPaste", interveningChange: true },
+  ])(
+    "keeps clipboard input pending for $inputType with intervening change $interveningChange",
+    async ({ inputType, interveningChange }) => {
+      const user = userEvent.setup();
+      const editorRef = createRef<MarkdownRichEditorHandle>();
+      render(
+        <MarkdownRichEditor
+          ref={editorRef}
+          markdown={"Intro\n\n| A |\n| - |\n| foo |\n\ntail"}
+          ariaLabel="Nested Markdown"
+          theme={TEST_MARKDOWN_THEME}
+          onChange={() => {}}
+        />
+      );
+      await user.click(await screen.findByText("foo"));
+      await waitFor(() => expect(document.querySelector(".tbl-cell-editor .cm-content")).not.toBeNull());
+      const nested = document.querySelector<HTMLElement>(".tbl-cell-editor .cm-content");
+      const nestedView = nested && EditorView.findFromDOM(nested);
+      const rootView = EditorView.findFromDOM(screen.getByLabelText("Nested Markdown"));
+      const handle = editorRef.current;
+      if (!nested || !nestedView || !rootView || !handle) throw new Error("Expected mounted root and nested editors");
+      const dispatch = vi.spyOn(rootView, "dispatch").mockImplementation(() => {});
+      try {
+        signalClipboardPreflight(nested, "paste");
+        if (interveningChange) {
+          nestedView.dispatch({ changes: { from: 0, to: nestedView.state.doc.length, insert: "unpublished" }, userEvent: "input" });
+          await Promise.resolve();
+        }
+        nested.dispatchEvent(new InputEvent("beforeinput", { bubbles: true, inputType, data: " " }));
+        nestedView.dispatch({ changes: { from: nestedView.state.doc.length, insert: " " }, userEvent: "input" });
+        vi.useFakeTimers();
+        await Promise.all([
+          expect(handle.captureSnapshot()).rejects.toMatchObject({ name: "TimeoutError" }),
+          vi.advanceTimersByTimeAsync(DRAFT_TRANSITION_FLUSH_MS),
+        ]);
+        expect(handle.getCanonicalMarkdown()).toContain("foo");
+        expect(handle.getCanonicalMarkdown()).not.toContain("unpublished");
+      } finally {
+        vi.useRealTimers();
+        dispatch.mockRestore();
+      }
+    }
+  );
+
+  it("captures an edit published by the real nested table editor", async () => {
+    const user = userEvent.setup();
+    const editorRef = createRef<MarkdownRichEditorHandle>();
+    render(
+      <MarkdownRichEditor
+        ref={editorRef}
+        markdown={"Intro\n\n| A |\n| - |\n| foo |\n\ntail"}
+        ariaLabel="Nested Markdown"
+        theme={TEST_MARKDOWN_THEME}
+        onChange={() => {}}
+      />
+    );
+    await user.click(await screen.findByText("foo"));
+    await waitFor(() => expect(document.querySelector(".tbl-cell-editor .cm-content")).not.toBeNull());
+    const nested = document.querySelector<HTMLElement>(".tbl-cell-editor .cm-content");
+    const nestedView = nested && EditorView.findFromDOM(nested);
+    if (!nested || !nestedView) throw new Error("Expected the real nested CodeMirror editor");
+    nested.dispatchEvent(new InputEvent("beforeinput", { bubbles: true, inputType: "insertText", data: "changed" }));
+    const snapshot = editorRef.current?.captureSnapshot();
+    nestedView.dispatch({ changes: { from: 0, to: nestedView.state.doc.length, insert: "changed" }, userEvent: "input" });
+
+    expect((await snapshot)?.serialize()).toContain("changed");
+    expect((await snapshot)?.serialize()).not.toContain("foo");
+  });
+
+  it("keeps snapshot source and canonical table formatting stable across later edits", async () => {
+    const user = userEvent.setup();
+    const editorRef = createRef<MarkdownRichEditorHandle>();
+    const markdown = "Intro\n\n| A |\n| - |\n| foo<br />bar |\n\ntail";
+    render(
+      <MarkdownRichEditor
+        ref={editorRef}
+        markdown={markdown}
+        ariaLabel="Snapshot Markdown"
+        theme={TEST_MARKDOWN_THEME}
+        onChange={() => {}}
+      />
+    );
+    const editor = await screen.findByLabelText("Snapshot Markdown");
+    const snapshot = await editorRef.current?.captureSnapshot();
+    expect(snapshot?.serialize()).toBe(markdown);
+
+    await user.click(editor);
+    await user.keyboard("{Control>}{End}{/Control}!");
+    const latest = await editorRef.current?.captureSnapshot();
+    expect(snapshot?.serialize()).toBe(markdown);
+    expect(latest?.revision).toBeGreaterThan(snapshot?.revision ?? -1);
+    expect(latest?.serialize()).toContain("foo<br />bar");
+    expect(latest?.serialize()).toContain("!");
+  });
+
+  it("persists a latest-revision checkpoint only after nested Markdown publication", async () => {
+    const user = userEvent.setup();
+    const editorRef = createRef<MarkdownRichEditorHandle>();
+    authSession.setAuthenticated(
+      { access_token: "test", token_type: "bearer", user_id: "editor-snapshot-user", username: "snapshot-user" },
+      false
+    );
+    const controller = createDraftCheckpointController("snapshot-connection", "/note.md", "markdown");
+    try {
+      render(
+        <MarkdownRichEditor
+          ref={editorRef}
+          markdown="alpha"
+          ariaLabel="Snapshot Markdown"
+          theme={TEST_MARKDOWN_THEME}
+          onChange={() => {}}
+        />
+      );
+      const editor = await screen.findByLabelText("Snapshot Markdown");
+      const nested = appendNestedEditorTarget(editor);
+      nested.dispatchEvent(new InputEvent("beforeinput", { bubbles: true, inputType: "insertText", data: "!" }));
+      const handle = editorRef.current;
+      if (!handle) throw new Error("Expected a mounted Markdown editor");
+      controller.request(1, async (signal) => {
+        const snapshot = await handle.captureSnapshot(signal);
+        expect(snapshot.revision).toBe(1);
+        return { baseline: "alpha", content: snapshot.serialize() };
+      });
+      let acknowledged = false;
+      const flush = controller.flush().then((outcome) => {
+        acknowledged = outcome.saved;
+        return outcome;
+      });
+      await Promise.resolve();
+      expect(acknowledged).toBe(false);
+      expect(loadDraft("snapshot-connection", "/note.md", "markdown")).toBeNull();
+      await user.click(editor);
+      await user.keyboard("!");
+
+      await expect(flush).resolves.toEqual({ saved: true, revision: 1 });
+      expect(loadDraft("snapshot-connection", "/note.md", "markdown")?.content).toBe(handle.getCanonicalMarkdown());
+      expect(loadDraft("snapshot-connection", "/note.md", "markdown")?.content).toContain("!");
+    } finally {
+      controller.dispose();
+      authSession.clear();
+      sessionStorage.clear();
+    }
+  });
+
+  it.each([
+    [false, false],
+    [false, true],
+    [true, false],
+    [true, true],
+  ])(
+    "restores the same nested cell without focusing the root after pending edit %s and capture after blur %s",
+    async (editAfterCapture, captureAfterBlur) => {
+      const user = userEvent.setup();
+      const editorRef = createRef<MarkdownRichEditorHandle>();
+      render(
+        <MarkdownRichEditor
+          ref={editorRef}
+          markdown={"| A |\n| - |\n| foo |\n"}
+          ariaLabel="Preserved table focus"
+          theme={TEST_MARKDOWN_THEME}
+          onChange={() => {}}
+        />
+      );
+      const root = EditorView.findFromDOM(screen.getByLabelText("Preserved table focus"));
+      await user.click(await screen.findByText("foo"));
+      const content = document.querySelector<HTMLElement>(".tbl-cell-editor .cm-content");
+      const nested = content && EditorView.findFromDOM(content);
+      const handle = editorRef.current;
+      if (!root || !nested || !handle) throw new Error("Expected root and nested Markdown editors");
+      expect(root).not.toBe(nested);
+      const rootFocus = vi.spyOn(root, "focus");
+      await waitFor(() => expect(nested.hasFocus).toBe(true));
+      await act(async () => nested.dispatch({ selection: { anchor: 1, head: 2 } }));
+      const capturedSelection = nested.state.selection;
+      if (!captureAfterBlur) handle.preserveSelection();
+      const button = document.createElement("button");
+      document.body.append(button);
+      try {
+        button.focus();
+        if (captureAfterBlur) handle.preserveSelection();
+        if (editAfterCapture) {
+          await act(async () => nested.dispatch({ changes: { from: nested.state.doc.length, insert: "!" }, selection: { anchor: 4 } }));
+        } else {
+          await act(async () => nested.dispatch({ selection: { anchor: 0 } }));
+        }
+        const expectedSelection = editAfterCapture ? nested.state.selection : capturedSelection;
+        rootFocus.mockClear();
+        act(() => expect(handle.restorePreservedSelection()).toBe(true));
+        expect(nested.hasFocus).toBe(true);
+        expect(nested.state.selection.eq(expectedSelection)).toBe(true);
+        expect(rootFocus).not.toHaveBeenCalled();
+        expect(document.querySelector(".tbl-cell-editor .cm-content")).toBe(content);
+      } finally {
+        rootFocus.mockRestore();
+        button.remove();
+      }
+    }
+  );
+
+  it.each([false, true])("forgets nested focus after external document replacement %s or root focus", async (replaceDocument) => {
+    const user = userEvent.setup();
+    const editorRef = createRef<MarkdownRichEditorHandle>();
+    const props = { ref: editorRef, ariaLabel: "Root focus fallback", theme: TEST_MARKDOWN_THEME, onChange: () => {} };
+    const { rerender } = render(<MarkdownRichEditor {...props} markdown={"| A |\n| - |\n| foo |\n\nparagraph"} />);
+    const root = EditorView.findFromDOM(screen.getByLabelText("Root focus fallback"));
+    await user.click(await screen.findByText("foo"));
+    const content = document.querySelector<HTMLElement>(".tbl-cell-editor .cm-content");
+    const nested = content && EditorView.findFromDOM(content);
+    const handle = editorRef.current;
+    if (!root || !nested || !handle) throw new Error("Expected root and nested Markdown editors");
+    await waitFor(() => expect(nested.hasFocus).toBe(true));
+    handle.preserveSelection();
+    if (replaceDocument) rerender(<MarkdownRichEditor {...props} markdown="replacement" />);
+    else
+      await act(async () => {
+        root.dispatch({ selection: { anchor: root.state.doc.length } });
+        root.focus();
+      });
+    const nestedFocus = vi.spyOn(nested, "focus");
+    const button = document.createElement("button");
+    document.body.append(button);
+    try {
+      button.focus();
+      handle.preserveSelection();
+      act(() => expect(handle.restorePreservedSelection()).toBe(true));
+      expect(root.hasFocus).toBe(true);
+      expect(nestedFocus).not.toHaveBeenCalled();
+    } finally {
+      nestedFocus.mockRestore();
+      button.remove();
+    }
+  });
+
+  it("cancels a pending snapshot without cancelling shared nested publication", async () => {
+    const user = userEvent.setup();
+    const editorRef = createRef<MarkdownRichEditorHandle>();
+    render(
+      <MarkdownRichEditor ref={editorRef} markdown="alpha" ariaLabel="Snapshot Markdown" theme={TEST_MARKDOWN_THEME} onChange={() => {}} />
+    );
+    const editor = await screen.findByLabelText("Snapshot Markdown");
+    appendNestedEditorTarget(editor).dispatchEvent(new InputEvent("beforeinput", { bubbles: true, inputType: "insertText", data: "!" }));
+    const abort = new AbortController();
+    const cancelled = editorRef.current?.captureSnapshot(abort.signal);
+    const rejection = expect(cancelled).rejects.toMatchObject({ name: "AbortError" });
+    const current = editorRef.current?.captureSnapshot();
+    abort.abort();
+    await rejection;
+    await user.click(editor);
+    await user.keyboard("!");
+
+    expect((await current)?.serialize()).toContain("!");
+  });
+
+  it("rejects a pending snapshot when its editor unmounts instead of returning empty source", async () => {
+    const editorRef = createRef<MarkdownRichEditorHandle>();
+    const { unmount } = render(
+      <MarkdownRichEditor ref={editorRef} markdown="alpha" ariaLabel="Snapshot Markdown" theme={TEST_MARKDOWN_THEME} onChange={() => {}} />
+    );
+    const editor = await screen.findByLabelText("Snapshot Markdown");
+    appendNestedEditorTarget(editor).dispatchEvent(new InputEvent("beforeinput", { bubbles: true, inputType: "insertText", data: "!" }));
+    const snapshot = editorRef.current?.captureSnapshot();
+    const rejection = expect(snapshot).rejects.toThrow(/disposed/);
+    unmount();
+
+    await rejection;
+  });
+
+  it.each(["dark", "custom-alpha"])("preserves Markdown identity, search and undo across a %s theme change", async (variant) => {
+    const markdown = "# alpha\n\n".repeat(120);
+    const onChange = vi.fn();
+    const props = { ariaLabel: "Theme Markdown", markdown, theme: TEST_MARKDOWN_THEME, onChange, searchOpen: true, searchText: "alpha" };
+    const { rerender } = render(<MarkdownRichEditor {...props} />);
+    const editor = await screen.findByLabelText("Theme Markdown");
+    const view = EditorView.findFromDOM(editor);
+    if (!view) throw new Error("Expected a mounted Markdown editor");
+    await act(async () => {
+      view.dispatch({ changes: { from: markdown.length, insert: "draft" }, selection: { anchor: 2, head: 7 } });
+    });
+    const doc = view.state.doc;
+    const selection = view.state.selection;
+    const query = getSearchQuery(view.state);
+    const metrics = getCodeMirrorFindReplaceMetrics(view);
+    view.scrollDOM.scrollTop = 240;
+    view.scrollDOM.scrollLeft = 30;
+    onChange.mockClear();
+
+    rerender(
+      <MarkdownRichEditor
+        {...props}
+        markdown={doc.toString()}
+        theme={{
+          ...TEST_MARKDOWN_THEME,
+          isDarkMode: true,
+          textColor: "rgb(240, 242, 244)",
+          surfaceBackground: variant === "dark" ? "rgb(24, 26, 28)" : "rgba(24, 26, 28, 0.8)",
+          selectionBackground: "rgba(60, 180, 210, 0.4)",
+        }}
+      />
+    );
+
+    await waitFor(() => expect(view.state.facet(EditorView.darkTheme)).toBe(true));
+    expect(EditorView.findFromDOM(screen.getByLabelText("Theme Markdown"))).toBe(view);
+    expect(view.state.doc).toBe(doc);
+    expect(view.state.selection).toBe(selection);
+    expect(getSearchQuery(view.state)).toBe(query);
+    expect(getCodeMirrorFindReplaceMetrics(view)).toEqual(metrics);
+    expect(view.scrollDOM.scrollTop).toBe(240);
+    expect(view.scrollDOM.scrollLeft).toBe(30);
+    expect(onChange).not.toHaveBeenCalled();
+    await act(async () => {
+      expect(undo(view)).toBe(true);
+    });
+    expect(view.state.doc.toString()).toBe(markdown);
+  });
+
   it("reconfigures ordinary Markdown line wrapping", async () => {
     const { rerender } = render(
       <MarkdownRichEditor
diff --git a/frontend/src/components/Viewer/__tests__/MarkdownViewer.test.tsx b/frontend/src/components/Viewer/__tests__/MarkdownViewer.test.tsx
index 2eef2d202..7e51e9edd 100644
--- a/frontend/src/components/Viewer/__tests__/MarkdownViewer.test.tsx
+++ b/frontend/src/components/Viewer/__tests__/MarkdownViewer.test.tsx
@@ -1,4 +1,5 @@
 import type { ViewUpdate } from "@codemirror/view";
+import { createTheme, ThemeProvider } from "@mui/material";
 import { act, configure, fireEvent, render as renderBase, screen, waitFor, within } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 import { forwardRef, type ReactNode, useEffect, useImperativeHandle, useRef, useState } from "react";
@@ -8,10 +9,22 @@ import { type ViewerLeaveGuard, WorkspaceNavigationGuard } from "../../../hooks/
 import { ContentProviderRegistryContext } from "../../../pages/FileBrowser/contentProviders";
 import apiService from "../../../services/api";
 import { authSession } from "../../../services/authSession";
+import { loadDraft, snapshotRegisteredDrafts } from "../../../services/draftRecovery";
+import { logger } from "../../../services/logger";
 import { createStorageBackedTestContentProviderRegistry, readBlobAsText } from "../../../test/helpers";
+import { requireTestElement, requireTestValue, uninitializedTestCallback } from "../../../test/helpers/assertions";
 import { SambeeThemeProvider } from "../../../theme";
+import { getDefaultTheme } from "../../../theme/themes";
+import { highlightingService } from "../../../utils/highlightingService";
+import * as markdownCodePreparation from "../../../utils/markdownCodePreparation";
+import * as markdownDocumentPreview from "../../../utils/markdownDocumentPreview";
+import * as markdownSyntaxPublication from "../../../utils/markdownSyntaxPublication";
+import * as markdownSyntaxWorker from "../../../utils/markdownSyntaxWorker";
+import type { PreparedCodeBlock } from "../../../utils/syntaxHighlighting";
 import MarkdownViewer from "../MarkdownViewer";
+import { MARKDOWN_VIEWER_CONTENT_AUTOFOCUS_DELAY_MS } from "../markdownEditorConstants";
 import { normalizeMarkdownTableCellLineBreaks } from "../markdownTableCellLineBreaks";
+import { RetainedMarkdownPreview, type RetainedMarkdownPreviewProps } from "../RetainedMarkdownPreview";
 import { createViewerSearchTestDriver } from "./viewerSearchTestUtils";
 
 const contentProviders = createStorageBackedTestContentProviderRegistry();
@@ -73,12 +86,14 @@ const mockMarkdownEditorBehavior = {
   focusCurrentSearchResultCalls: 0,
   focusResetsScrollPosition: false,
   flushRejectError: null as Error | null,
+  pendingSnapshot: null as Promise<void> | null,
   initialNormalizedMarkdown: null as string | null,
   lastSearchAutoNavigate: true,
   lastSearchOpen: false,
   lastSearchText: "",
   lastRestoredScrollTop: null as number | null,
   moveCaretToEndOnMarkdownPropChangeWhenFocused: false,
+  onNormalizationStateChange: null as ((pending: boolean) => void) | null,
   preserveSelectionCalls: 0,
   restorePreservedSelectionCalls: 0,
   skipUserEdit: false,
@@ -111,6 +126,8 @@ const mockEditLockInfo = {
 const MockMarkdownRichEditor = forwardRef<
   {
     focus: () => void;
+    captureSnapshot: () => Promise<{ revision: number; serialize: () => string }>;
+    captureSnapshotSync: () => { revision: number; serialize: () => string };
     flushPendingEdits: () => Promise<void>;
     getCanonicalMarkdown: () => string;
     getPrimarySelectionText: () => string;
@@ -133,6 +150,7 @@ const MockMarkdownRichEditor = forwardRef<
     markdown: string;
     onChange: (markdown: string) => void;
     onUserEdit?: (viewUpdate?: ViewUpdate) => void;
+    onNormalizationStateChange?: (pending: boolean, error?: Error) => void;
     ariaLabel: string;
     autoFocus?: boolean;
     readOnly?: boolean;
@@ -160,6 +178,7 @@ const MockMarkdownRichEditor = forwardRef<
       markdown,
       onChange,
       onUserEdit,
+      onNormalizationStateChange,
       ariaLabel,
       readOnly = false,
       className,
@@ -177,6 +196,7 @@ const MockMarkdownRichEditor = forwardRef<
     mockMarkdownEditorBehavior.lastSearchOpen = searchOpen;
     mockMarkdownEditorBehavior.lastSearchText = searchText;
     mockMarkdownEditorBehavior.lastSearchAutoNavigate = searchAutoNavigate;
+    mockMarkdownEditorBehavior.onNormalizationStateChange = onNormalizationStateChange ?? null;
 
     const textareaRef = useRef<HTMLTextAreaElement | null>(null);
     const toolbarButtonRef = useRef<HTMLButtonElement | null>(null);
@@ -320,6 +340,31 @@ const MockMarkdownRichEditor = forwardRef<
 
         return restored;
       },
+      captureSnapshot: async () => {
+        if (mockMarkdownEditorBehavior.flushRejectError) throw mockMarkdownEditorBehavior.flushRejectError;
+        const content = normalizeMarkdownTableCellLineBreaks(
+          mockMarkdownEditorBehavior.canonicalMarkdownOverride ?? latestMarkdownRef.current
+        );
+        await mockMarkdownEditorBehavior.pendingSnapshot;
+        return {
+          revision: 0,
+          serialize: () => {
+            if (mockMarkdownEditorBehavior.throwOnCanonicalExport) throw mockMarkdownEditorBehavior.throwOnCanonicalExport;
+            return content;
+          },
+        };
+      },
+      captureSnapshotSync: () => {
+        if (mockMarkdownEditorBehavior.flushRejectError) throw mockMarkdownEditorBehavior.flushRejectError;
+        const content = mockMarkdownEditorBehavior.canonicalMarkdownOverride ?? textareaRef.current?.value ?? latestMarkdownRef.current;
+        return {
+          revision: 0,
+          serialize: () => {
+            if (mockMarkdownEditorBehavior.throwOnCanonicalExport) throw mockMarkdownEditorBehavior.throwOnCanonicalExport;
+            return content;
+          },
+        };
+      },
       flushPendingEdits: () => {
         if (mockMarkdownEditorBehavior.flushRejectError) {
           return Promise.reject(mockMarkdownEditorBehavior.flushRejectError);
@@ -452,6 +497,98 @@ const MockMarkdownRichEditor = forwardRef<
 
 MockMarkdownRichEditor.displayName = "MockMarkdownRichEditor";
 
+describe("test-only retained Markdown host", () => {
+  afterEach(() => vi.restoreAllMocks());
+
+  const props = { onExternalLink: () => {}, resolveLink: (href: string) => href };
+  const createResult = () => ({
+    syntaxSession: { dispose: vi.fn(), page: vi.fn() },
+    syntaxRanges: 0,
+    sourceChunks: 1,
+    largestSourceChunkUnits: 1,
+    sourceUnitsSent: 1,
+    models: [],
+    matches: [],
+    preparationMs: 0,
+    indexingMs: 0,
+    clientAssemblyMs: 0,
+    chunks: 1,
+    largestChunkItems: 1,
+  });
+  const createView = () => ({
+    consume: vi.fn().mockResolvedValue(undefined),
+    finish: vi.fn(),
+    dispose: vi.fn(),
+    stats: vi.fn().mockReturnValue({}),
+    search: vi.fn(),
+    jump: vi.fn(),
+  });
+
+  it("aborts its document job and disposes a syntax session that arrives after unmount", async () => {
+    const view = createView();
+    const result = createResult();
+    vi.spyOn(markdownDocumentPreview, "mountMarkdownDocument").mockResolvedValue(view);
+    let complete!: (value: typeof result) => void;
+    const prepare = vi.fn<RetainedMarkdownPreviewProps["prepareDocument"]>().mockImplementation(
+      () =>
+        new Promise((resolve) => {
+          complete = resolve;
+        })
+    );
+    const host = render(
+      <div>
+        <div>
+          <RetainedMarkdownPreview {...props} prepareDocument={prepare} generation={{ id: 10, source: "canonical" }} />
+        </div>
+      </div>
+    );
+    await waitFor(() => expect(prepare).toHaveBeenCalledOnce());
+    const request = requireTestValue(prepare.mock.calls[0])[0];
+    expect(request).toEqual(expect.objectContaining({ source: "canonical", generation: 10 }));
+    await request.onRecords([{ kind: "text", id: 1, parent: 0, value: "canonical", from: 0 }]);
+    expect(view.consume).toHaveBeenCalledWith([{ kind: "text", id: 1, parent: 0, value: "canonical", from: 0 }]);
+    expect(document.head.textContent).toContain("markdown-retained-10");
+    host.unmount();
+    expect(request.signal.aborted).toBe(true);
+    expect(view.dispose).toHaveBeenCalledOnce();
+    await act(async () => complete(result));
+    expect(result.syntaxSession.dispose).toHaveBeenCalledOnce();
+    expect(view.finish).not.toHaveBeenCalled();
+    expect(document.head.textContent).not.toContain("markdown-retained-10");
+  });
+
+  it("does not retain an earlier generation's failure and disposes a completed session", async () => {
+    const view = createView();
+    const result = createResult();
+    vi.spyOn(logger, "error").mockImplementation(() => {});
+    vi.spyOn(markdownDocumentPreview, "mountMarkdownDocument").mockResolvedValue(view);
+    const prepare = vi
+      .fn<RetainedMarkdownPreviewProps["prepareDocument"]>()
+      .mockRejectedValueOnce(new Error("document failed"))
+      .mockResolvedValueOnce(result);
+    const host = render(
+      <div>
+        <div>
+          <RetainedMarkdownPreview {...props} prepareDocument={prepare} generation={{ id: 11, source: "first" }} />
+        </div>
+      </div>
+    );
+    expect(await screen.findByRole("alert")).toHaveTextContent("document failed");
+    host.rerender(
+      <div>
+        <div>
+          <RetainedMarkdownPreview {...props} prepareDocument={prepare} generation={{ id: 12, source: "second" }} />
+        </div>
+      </div>
+    );
+    expect(screen.queryByRole("alert")).not.toBeInTheDocument();
+    await waitFor(() => expect(host.container.querySelector('[data-markdown-retained-state="complete"]')).not.toBeNull());
+    expect(view.finish).toHaveBeenCalledWith(expect.any(Number), 0, result.syntaxSession);
+    host.unmount();
+    expect(result.syntaxSession.dispose).toHaveBeenCalledOnce();
+  });
+});
+
 describe("MarkdownViewer", () => {
   afterEach(() => vi.unstubAllGlobals());
 
@@ -519,10 +656,33 @@ describe("MarkdownViewer", () => {
   });
   const viewerSearch = createViewerSearchTestDriver({
     assertCurrentMatchActive: () => {
-      expect(document.querySelectorAll('mark[data-text-search-current="true"]').length).toBeGreaterThan(0);
+      expect(
+        [...CSS.highlights.entries()].some(
+          ([name, ranges]) => name.startsWith("markdown-search-") && name.endsWith("-current") && ranges.size === 1
+        )
+      ).toBe(true);
     },
   });
 
+  function enableSearchHighlights() {
+    vi.stubGlobal("CSS", { highlights: new Map<string, Set<Range>>() });
+    vi.stubGlobal(
+      "IntersectionObserver",
+      class {
+        observe = vi.fn();
+        disconnect = vi.fn();
+      }
+    );
+    vi.stubGlobal(
+      "Highlight",
+      class extends Set<Range> {
+        constructor(...ranges: Range[]) {
+          super(ranges);
+        }
+      }
+    );
+  }
+
   function suppressExpectedRenderCrashNoise(message: string): () => void {
     const consoleErrorSpy = vi.spyOn(console, "error").mockImplementation((...args: unknown[]) => {
       const combinedMessage = args.map((value) => (value instanceof Error ? value.message : String(value))).join(" ");
@@ -551,10 +711,11 @@ describe("MarkdownViewer", () => {
     sessionStorage.clear();
     localStorage.setItem("access_token", "mock-token");
     vi.restoreAllMocks();
+    vi.spyOn(apiService, "getThemes").mockResolvedValue({ themes: [], site_default_id: "sambee-light" });
     vi.spyOn(apiService, "writeTextWithEditLock").mockImplementation(async (connectionId, path, content, _lockInfo, options) => {
       await apiService.saveTextFile(connectionId, path, content, {
         filename: path.split("/").pop() ?? path,
-        mimeType: options.mimeType,
+        mimeType: requireTestValue(options).mimeType,
       });
     });
     vi.spyOn(apiService, "acquireEditLock").mockResolvedValue(mockEditLockInfo);
@@ -571,12 +732,14 @@ describe("MarkdownViewer", () => {
     mockMarkdownEditorBehavior.focusCurrentSearchResultCalls = 0;
     mockMarkdownEditorBehavior.focusResetsScrollPosition = false;
     mockMarkdownEditorBehavior.flushRejectError = null;
+    mockMarkdownEditorBehavior.pendingSnapshot = null;
     mockMarkdownEditorBehavior.initialNormalizedMarkdown = null;
     mockMarkdownEditorBehavior.lastSearchAutoNavigate = true;
     mockMarkdownEditorBehavior.lastSearchOpen = false;
     mockMarkdownEditorBehavior.lastSearchText = "";
     mockMarkdownEditorBehavior.lastRestoredScrollTop = null;
     mockMarkdownEditorBehavior.moveCaretToEndOnMarkdownPropChangeWhenFocused = false;
+    mockMarkdownEditorBehavior.onNormalizationStateChange = null;
     mockMarkdownEditorBehavior.preserveSelectionCalls = 0;
     mockMarkdownEditorBehavior.restorePreservedSelectionCalls = 0;
     mockMarkdownEditorBehavior.skipUserEdit = false;
@@ -606,6 +769,331 @@ describe("MarkdownViewer", () => {
     );
   }
 
+  it("prints read-only previews and reports native dialog failures without changing content", async () => {
+    vi.spyOn(apiService, "getFileContent").mockResolvedValue("# Printable preview");
+    const print = vi
+      .spyOn(window, "print")
+      .mockImplementationOnce(() => {
+        throw new Error("Printing blocked");
+      })
+      .mockImplementation(() => {});
+    renderViewerWithProps({ isReadOnly: true });
+    await screen.findByRole("heading", { name: "Printable preview" });
+    const button = screen.getByRole("button", { name: "Print" });
+    await userEvent.click(button);
+    expect(await screen.findByText("The print dialog couldn't open. Try Print from your browser menu.")).toBeInTheDocument();
+    await userEvent.click(button);
+    expect(print).toHaveBeenCalledTimes(2);
+    expect(screen.queryByText("The print dialog couldn't open. Try Print from your browser menu.")).not.toBeInTheDocument();
+    expect(screen.getByRole("heading", { name: "Printable preview" })).toBeInTheDocument();
+  });
+
+  it("doesn't offer preview printing while editing", async () => {
+    vi.spyOn(apiService, "getFileContent").mockResolvedValue("# Printable preview");
+    renderViewer();
+    await screen.findByRole("heading", { name: "Printable preview" });
+    await userEvent.click(screen.getByRole("button", { name: "Edit" }));
+    await screen.findByRole("button", { name: "Save" });
+    expect(screen.queryByRole("button", { name: "Print" })).not.toBeInTheDocument();
+  });
+
+  it("restores native print scroll and selection and releases its lifecycle listeners", async () => {
+    vi.spyOn(apiService, "getFileContent").mockResolvedValue("```js\nconst printed = 1;\n```\n");
+    const { unmount } = renderViewer();
+    const code = await screen.findByText("const printed = 1;");
+    const viewport = screen.getByTestId("markdown-viewer-content");
+    const pre = code.closest("pre")!;
+    viewport.focus();
+    viewport.scrollTop = 120;
+    pre.scrollLeft = 48;
+    const selection = window.getSelection()!;
+    const range = new Range();
+    range.selectNodeContents(code);
+    selection.removeAllRanges();
+    selection.addRange(range);
+    const selected = selection.toString();
+    act(() => window.dispatchEvent(new Event("beforeprint")));
+    viewport.scrollTop = 0;
+    pre.scrollLeft = 0;
+    selection.removeAllRanges();
+    act(() => window.dispatchEvent(new Event("afterprint")));
+    await waitFor(() => {
+      expect(viewport.scrollTop).toBe(120);
+      expect(pre.scrollLeft).toBe(48);
+      expect(selection.toString()).toBe(selected);
+    });
+    unmount();
+    const frame = vi.spyOn(window, "requestAnimationFrame");
+    window.dispatchEvent(new Event("beforeprint"));
+    window.dispatchEvent(new Event("afterprint"));
+    expect(frame).not.toHaveBeenCalled();
+    selection.removeAllRanges();
+  });
+
+  it("reports a local normalization failure without blaming the server", async () => {
+    vi.spyOn(apiService, "getFileContent").mockResolvedValue("# Preview");
+    vi.spyOn(markdownCodePreparation, "normalizeMarkdownSource").mockRejectedValue(new Error("Markdown worker initialization failed"));
+    renderViewer();
+
+    expect(await screen.findByText("Failed to load markdown file: Markdown worker initialization failed")).toBeInTheDocument();
+    expect(screen.queryByText(/Server is busy/)).not.toBeInTheDocument();
+  });
+
+  it("prepares collected requests only after their semantic code blocks commit without a collection parse", async () => {
+    vi.spyOn(apiService, "getFileContent").mockResolvedValue("> ```js title\n> const x=1;\n> ```\n\n```\nplain\n```\n");
+    const measure = vi.spyOn(performance, "measure");
+    const prepare = vi.spyOn(highlightingService, "prepare").mockImplementation((requests) => {
+      const code = document.querySelectorAll('[data-markdown-search-root="true"] pre code');
+      expect([...code].map((element) => element.textContent)).toEqual(["const x=1;\n", "plain\n"]);
+      expect(requests).toEqual([
+        { text: "const x=1;", label: "js" },
+        { text: "plain", label: null },
+      ]);
+      return Promise.resolve(requests.map(() => ({ ranges: [] })));
+    });
+    renderViewer();
+    await screen.findByText("const x=1;");
+    await waitFor(() => expect(prepare).toHaveBeenCalledOnce());
+    expect(measure.mock.calls.some(([name]) => name === "sambee:preview-preparation:collection-parse")).toBe(false);
+  });
+
+  it("keeps plain text, selection and search usable when syntax preparation fails", async () => {
+    enableSearchHighlights();
+    vi.spyOn(apiService, "getFileContent").mockResolvedValue("# Preview\n\n```js\nconst x=1; const x=2;\n```\n");
+    let rejectPreparation!: (error: Error) => void;
+    const prepare = vi.spyOn(markdownSyntaxWorker, "prepareMarkdownSyntax").mockImplementation(
+      () =>
+        new Promise((_resolve, reject) => {
+          rejectPreparation = reject;
+        })
+    );
+    const publish = vi.spyOn(markdownSyntaxPublication, "publishMarkdownSyntax");
+    renderViewer();
+    const code = await screen.findByText("const x=1; const x=2;");
+    await waitFor(() => expect(prepare).toHaveBeenCalledOnce());
+    await viewerSearch.openSearch("const x");
+    await screen.findByText("1 / 2");
+    const root = document.querySelector('[data-markdown-search-root="true"]');
+    const viewport = screen.getByTestId("markdown-viewer-content");
+    viewport.scrollTop = 123;
+    const selection = window.getSelection()!;
+    const range = document.createRange();
+    range.selectNodeContents(code);
+    selection.removeAllRanges();
+    selection.addRange(range);
+    const selected = selection.toString();
+    try {
+      await act(async () => rejectPreparation(new Error("Syntax worker response could not be decoded")));
+      expect(document.querySelector('[data-markdown-search-root="true"]')).toBe(root);
+      expect(root?.querySelector("code")).toBe(code);
+      expect(code.textContent).toBe("const x=1; const x=2;\n");
+      expect(selection.toString()).toBe(selected);
+      expect(viewport.scrollTop).toBe(123);
+      expect(screen.getByRole("heading", { name: "Preview" })).toBeInTheDocument();
+      expect(screen.queryByText(/Failed to load markdown file/)).not.toBeInTheDocument();
+      expect(publish).not.toHaveBeenCalled();
+      fireEvent.click(screen.getByRole("button", { name: "Next match" }));
+      expect(await screen.findByText("2 / 2")).toBeInTheDocument();
+      expect(prepare).toHaveBeenCalledOnce();
+    } finally {
+      selection.removeAllRanges();
+    }
+  });
+
+  it.each([2, 3])("publishes only the latest of %s documents after obsolete results arrive", async (documentCount) => {
+    const documents = [
+      { path: "/docs/readme.md", label: "js", text: "const old=1;" },
+      { path: "/docs/replacement.md", label: "python", text: "print(2)" },
+      { path: "/docs/latest.md", label: "rust", text: "let latest = 3;" },
+    ].slice(0, documentCount);
+    const load = vi.spyOn(apiService, "getFileContent");
+    for (const document of documents) load.mockResolvedValueOnce(`\`\`\`${document.label}\n${document.text}\n\`\`\``);
+    const completions: ((results: readonly PreparedCodeBlock[]) => void)[] = [];
+    const prepare = vi.spyOn(highlightingService, "prepare").mockImplementation(() => new Promise((resolve) => completions.push(resolve)));
+    const publish = vi.spyOn(markdownSyntaxPublication, "publishMarkdownSyntax").mockReturnValue(vi.fn());
+    const viewer = renderViewer();
+    for (const [index, document] of documents.entries()) {
+      if (index > 0)
+        viewer.rerender(
+          <SambeeThemeProvider>
+            <MarkdownViewer connectionId="conn1" path={document.path} onClose={() => {}} />
+          </SambeeThemeProvider>
+        );
+      await screen.findByText(document.text);
+      await waitFor(() => expect(prepare).toHaveBeenCalledTimes(index + 1));
+      expect(prepare.mock.calls[index]![0]).toEqual([{ text: document.text, label: document.label }]);
+    }
+    for (let index = documents.length - 2; index >= 0; index -= 1) {
+      expect(prepare.mock.calls[index]![1]!.aborted).toBe(true);
+      await act(async () => completions[index]!([{ ranges: [] }]));
+    }
+    expect(publish).not.toHaveBeenCalled();
+    const latest = documents[documents.length - 1]!;
+    expect(prepare.mock.calls[documents.length - 1]![1]!.aborted).toBe(false);
+    await act(async () => completions[documents.length - 1]!([{ ranges: [] }]));
+    expect(publish).toHaveBeenCalledOnce();
+    expect(publish.mock.calls[0]![2].requests).toEqual([{ text: latest.text, label: latest.label }]);
+    expect(publish.mock.calls[0]![0].querySelector("code")?.textContent).toBe(`${latest.text}\n`);
+  });
+
+  it("preserves the semantic DOM, active logical match and scroll when syntax becomes available", async () => {
+    vi.spyOn(apiService, "getFileContent").mockResolvedValue("```js\nconst x=1; const x=2;\n```");
+    let finish!: (results: readonly PreparedCodeBlock[]) => void;
+    const prepare = vi.spyOn(highlightingService, "prepare").mockImplementation(
+      () =>
+        new Promise((resolve) => {
+          finish = resolve;
+        })
+    );
+    renderViewer();
+    await screen.findByText("const x=1; const x=2;");
+    await waitFor(() => expect(prepare).toHaveBeenCalledTimes(1));
+    const search = await viewerSearch.openSearch("missing");
+    fireEvent.change(search, { target: { value: "const x" } });
+    await screen.findByText("1 / 2");
+    fireEvent.click(screen.getByRole("button", { name: "Next match" }));
+    await screen.findByText("2 / 2");
+    const root = document.querySelector('[data-markdown-search-root="true"]')!;
+    const scroll = root.parentElement!;
+    scroll.scrollTop = 123;
+    const scrollIntoView = vi.fn();
+    const previousScroll = Object.getOwnPropertyDescriptor(HTMLElement.prototype, "scrollIntoView");
+    Object.defineProperty(HTMLElement.prototype, "scrollIntoView", { configurable: true, value: scrollIntoView });
+    try {
+      await act(async () =>
+        finish([
+          {
+            ranges: [
+              { from: 0, to: 5, categories: ["keyword"] },
+              { from: 11, to: 16, categories: ["keyword"] },
+            ],
+          },
+        ])
+      );
+      expect(document.querySelector('[data-markdown-search-root="true"]')).toBe(root);
+      expect(root.querySelector("code")?.textContent).toBe("const x=1; const x=2;\n");
+      expect(document.querySelectorAll(".sambee-syntax-keyword")).toHaveLength(0);
+      expect(screen.getByText("2 / 2")).toBeInTheDocument();
+      expect(scroll.scrollTop).toBe(123);
+      expect(scrollIntoView).not.toHaveBeenCalled();
+      expect(prepare).toHaveBeenCalledTimes(1);
+      fireEvent.change(search, { target: { value: "x=2" } });
+      expect(await screen.findByText("1 / 1")).toBeInTheDocument();
+    } finally {
+      if (previousScroll) Object.defineProperty(HTMLElement.prototype, "scrollIntoView", previousScroll);
+      else Reflect.deleteProperty(HTMLElement.prototype, "scrollIntoView");
+    }
+  });
+
+  it.each(["dark", "custom-alpha"])("changes %s preview colors without reprocessing content or resetting native state", async (variant) => {
+    const load = vi.spyOn(apiService, "getFileContent").mockResolvedValue("```js\nconst x=1; const x=2;\n```");
+    const prepare = vi.spyOn(highlightingService, "prepare").mockResolvedValue([{ ranges: [{ from: 0, to: 5, categories: ["keyword"] }] }]);
+    const dispose = vi.fn();
+    const publish = vi.spyOn(markdownSyntaxPublication, "publishMarkdownSyntax").mockReturnValue(dispose);
+    const onClose = vi.fn();
+    const tree = (theme: ReturnType<typeof createTheme>) => (
+      <SambeeThemeProvider>
+        <ThemeProvider theme={theme}>
+          <MarkdownViewer connectionId="conn1" path="/docs/readme.md" onClose={onClose} />
+        </ThemeProvider>
+      </SambeeThemeProvider>
+    );
+    const viewer = render(tree(createTheme()));
+    await screen.findByText("const x=1; const x=2;");
+    await waitFor(() => expect(publish).toHaveBeenCalledOnce());
+    const search = await viewerSearch.openSearch("const x");
+    await screen.findByText("1 / 2");
+    fireEvent.click(screen.getByRole("button", { name: "Next match" }));
+    await screen.findByText("2 / 2");
+    const root = document.querySelector<HTMLElement>('[data-markdown-search-root="true"]')!;
+    const code = root.querySelector("code")!;
+    const node = code.firstChild;
+    const selection = document.getSelection()!;
+    const range = document.createRange();
+    range.selectNodeContents(code);
+    selection.removeAllRanges();
+    selection.addRange(range);
+    const scroll = root.parentElement!;
+    scroll.scrollTop = 123;
+    const keyword = variant === "dark" ? "#80cbc4" : "#12ab3478";
+
+    viewer.rerender(
+      tree(
+        createTheme({
+          palette: {
+            mode: "dark",
+            syntax: { ...getDefaultTheme("dark").components!.syntax!, keyword },
+          },
+        })
+      )
+    );
+
+    await waitFor(() => expect(root.style.getPropertyValue("--sambee-syntax-keyword")).toBe(keyword));
+    expect(document.querySelector('[data-markdown-search-root="true"]')).toBe(root);
+    expect(code.firstChild).toBe(node);
+    expect(selection.toString()).toBe("const x=1; const x=2;\n");
+    expect(screen.getByText("2 / 2")).toBeInTheDocument();
+    expect(scroll.scrollTop).toBe(123);
+    expect(load).toHaveBeenCalledOnce();
+    expect(prepare).toHaveBeenCalledOnce();
+    expect(publish).toHaveBeenCalledOnce();
+    expect(dispose).not.toHaveBeenCalled();
+    selection.removeAllRanges();
+    fireEvent.change(search, { target: { value: "x=2" } });
+    expect(await screen.findByText("1 / 1")).toBeInTheDocument();
+    await userEvent.click(screen.getByRole("button", { name: "Close" }));
+    expect(onClose).toHaveBeenCalledOnce();
+    viewer.unmount();
+    expect(dispose).toHaveBeenCalledOnce();
+  });
+
+  it("preserves native selection without replacing the preview when syntax becomes available", async () => {
+    vi.spyOn(apiService, "getFileContent").mockResolvedValue("```js\nconst x=1;\n```");
+    let finish!: (results: readonly PreparedCodeBlock[]) => void;
+    vi.spyOn(highlightingService, "prepare").mockImplementation(
+      () =>
+        new Promise((resolve) => {
+          finish = resolve;
+        })
+    );
+    renderViewer();
+    await screen.findByText("const x=1;");
+    const root = document.querySelector('[data-markdown-search-root="true"]')!;
+    const range = document.createRange();
+    range.selectNodeContents(root.querySelector("code")!);
+    const selection = document.getSelection()!;
+    selection.removeAllRanges();
+    selection.addRange(range);
+    await act(async () => finish([{ ranges: [{ from: 0, to: 5, categories: ["keyword"] }] }]));
+    expect(document.querySelector('[data-markdown-search-root="true"]')).toBe(root);
+    expect(selection.toString()).toBe("const x=1;\n");
+    act(() => {
+      selection.removeAllRanges();
+      document.dispatchEvent(new Event("selectionchange"));
+    });
+    expect(document.querySelector('[data-markdown-search-root="true"]')).toBe(root);
+    expect(root.querySelector("code")?.textContent).toBe("const x=1;\n");
+  });
+
+  it("aborts obsolete syntax preparation on unmount and ignores a late result", async () => {
+    vi.spyOn(apiService, "getFileContent").mockResolvedValue("```js\nconst x=1;\n```");
+    let finish!: (results: readonly PreparedCodeBlock[]) => void;
+    const prepare = vi.spyOn(highlightingService, "prepare").mockImplementation(
+      () =>
+        new Promise((resolve) => {
+          finish = resolve;
+        })
+    );
+    const { unmount } = renderViewer();
+    await screen.findByText("const x=1;");
+    await waitFor(() => expect(prepare).toHaveBeenCalledTimes(1));
+    const signal = prepare.mock.calls[0]![1]!;
+    unmount();
+    expect(signal.aborted).toBe(true);
+    await act(async () => finish([{ ranges: [{ from: 0, to: 5, categories: ["keyword"] }] }]));
+    expect(document.querySelector(".sambee-syntax-keyword")).toBeNull();
+  });
+
   it.each(["Back", "Close"])("leaves clean editing with %s and serializes rapid re-entry behind lock release", async (action) => {
     vi.spyOn(apiService, "getFileContent").mockResolvedValue("# Readme\n");
     vi.spyOn(apiService, "supportsEditLocks").mockReturnValue(true);
@@ -778,6 +1266,134 @@ describe("MarkdownViewer", () => {
     expect(getFileContentSpy).toHaveBeenCalledTimes(1);
   });
 
+  it.each(["pagehide", "registered"])("captures current Markdown before React publication on %s", async (trigger) => {
+    vi.spyOn(authSession, "getUserId").mockReturnValue("test-user");
+    vi.spyOn(apiService, "getFileContent").mockResolvedValueOnce("# Readme\n");
+    vi.spyOn(apiService, "getThemes").mockResolvedValue({ themes: [], site_default_id: "sambee-light" });
+    vi.spyOn(apiService, "getOriginalFileBlob").mockResolvedValue(new Blob(["# Readme\n"], { type: "text/markdown" }));
+    vi.spyOn(apiService, "releaseEditLock").mockResolvedValue();
+    vi.spyOn(apiService, "saveTextFile").mockResolvedValue();
+    renderViewer();
+    await userEvent.setup().click(await screen.findByRole("button", { name: "Edit" }));
+    const editor = await screen.findByRole("textbox", { name: "Markdown editor" });
+    fireEvent.change(editor, { target: { value: "# Older React draft\n" } });
+    const storage = vi.spyOn(Storage.prototype, "setItem");
+    const draftKey = `sambee_oidc_draft:test-user:conn1:markdown:${encodeURIComponent("/docs/readme.md")}`;
+    const valueSetter = Object.getOwnPropertyDescriptor(HTMLTextAreaElement.prototype, "value")?.set;
+    if (!valueSetter) throw new Error("Expected the native textarea value setter");
+    valueSetter.call(editor, "# Latest editor revision\n");
+    mockMarkdownEditorBehavior.canonicalMarkdownOverride = "# Latest editor revision\n";
+    act(() => {
+      if (trigger === "pagehide") window.dispatchEvent(new Event("pagehide"));
+      else snapshotRegisteredDrafts();
+    });
+    expect(loadDraft("conn1", "/docs/readme.md", "markdown")).toMatchObject({
+      baseline: "# Readme\n",
+      content: "# Latest editor revision\n",
+    });
+    await waitFor(() => expect(storage.mock.calls.filter(([key]) => key === draftKey).length).toBeGreaterThanOrEqual(2));
+    expect(
+      storage.mock.calls
+        .filter(([key]) => key === draftKey)
+        .every(([, value]) => JSON.parse(value).content === "# Latest editor revision\n")
+    ).toBe(true);
+    expect(loadDraft("conn1", "/docs/readme.md", "markdown")?.content).toBe("# Latest editor revision\n");
+    expect(apiService.saveTextFile).not.toHaveBeenCalled();
+  });
+
+  it.each(["capture", "serialization", "storage"])("preserves the last recovery checkpoint on %s failure", async (failure) => {
+    vi.spyOn(authSession, "getUserId").mockReturnValue("test-user");
+    vi.spyOn(authSession, "refreshIfNeeded").mockResolvedValue(undefined);
+    vi.spyOn(apiService, "getFileContent").mockResolvedValueOnce("# Readme\n");
+    vi.spyOn(apiService, "getThemes").mockResolvedValue({ themes: [], site_default_id: "sambee-light" });
+    vi.spyOn(apiService, "getOriginalFileBlob").mockResolvedValue(new Blob(["# Readme\n"], { type: "text/markdown" }));
+    vi.spyOn(apiService, "saveTextFile").mockResolvedValue();
+    const release = vi.spyOn(apiService, "releaseEditLock").mockResolvedValue();
+    renderViewer();
+    await userEvent.setup().click(await screen.findByRole("button", { name: "Edit" }));
+    const editor = await screen.findByRole("textbox", { name: "Markdown editor" });
+    fireEvent.change(editor, { target: { value: "# Acknowledged draft\n" } });
+    act(() => {
+      snapshotRegisteredDrafts();
+    });
+    const acknowledged = loadDraft("conn1", "/docs/readme.md", "markdown");
+    expect(acknowledged?.content).toBe("# Acknowledged draft\n");
+    fireEvent.change(editor, { target: { value: "# Newer draft\n" } });
+    const error = new DOMException("The latest snapshot is unavailable", "InvalidStateError");
+    if (failure === "capture") mockMarkdownEditorBehavior.flushRejectError = error;
+    if (failure === "serialization") mockMarkdownEditorBehavior.throwOnCanonicalExport = error;
+    const storage =
+      failure === "storage"
+        ? vi.spyOn(Storage.prototype, "setItem").mockImplementation(() => {
+            throw error;
+          })
+        : null;
+    try {
+      act(() => {
+        window.dispatchEvent(new Event("pagehide"));
+        snapshotRegisteredDrafts();
+      });
+      expect(loadDraft("conn1", "/docs/readme.md", "markdown")).toEqual(acknowledged);
+      expect(editor).toHaveValue("# Newer draft\n");
+      expect(apiService.saveTextFile).not.toHaveBeenCalled();
+      expect(release).not.toHaveBeenCalled();
+    } finally {
+      mockMarkdownEditorBehavior.flushRejectError = null;
+      mockMarkdownEditorBehavior.throwOnCanonicalExport = null;
+      storage?.mockRestore();
+    }
+    act(() => {
+      snapshotRegisteredDrafts();
+    });
+    expect(loadDraft("conn1", "/docs/readme.md", "markdown")?.content).toBe("# Newer draft\n");
+  });
+
+  it("retries recovery after normalization completes without changing the published draft", async () => {
+    const token = { access_token: "mock-token", token_type: "bearer", user_id: "test-user", username: "test-user" };
+    authSession.setAuthenticated(token, false);
+    vi.spyOn(authSession, "getUserId").mockReturnValue("test-user");
+    vi.spyOn(authSession, "refreshIfNeeded").mockResolvedValue(undefined);
+    vi.spyOn(authSession, "requestRefresh").mockResolvedValue(token);
+    vi.spyOn(apiService, "getFileContent").mockResolvedValueOnce("# Readme\n");
+    vi.spyOn(apiService, "getOriginalFileBlob").mockResolvedValue(new Blob(["# Readme\n"], { type: "text/markdown" }));
+    vi.spyOn(apiService, "releaseEditLock").mockResolvedValue();
+    vi.spyOn(apiService, "saveTextFile").mockResolvedValue();
+    const { unmount } = renderViewer();
+    await userEvent.setup().click(await screen.findByRole("button", { name: "Edit" }));
+    const editor = await screen.findByRole("textbox", { name: "Markdown editor" });
+    vi.useFakeTimers();
+    try {
+      fireEvent.change(editor, { target: { value: "# Acknowledged draft\n" } });
+      act(() => snapshotRegisteredDrafts());
+      const acknowledged = loadDraft("conn1", "/docs/readme.md", "markdown");
+      expect(acknowledged?.content).toBe("# Acknowledged draft\n");
+      act(() => {
+        mockMarkdownEditorBehavior.flushRejectError = new DOMException("Normalization pending", "InvalidStateError");
+        mockMarkdownEditorBehavior.onNormalizationStateChange?.(true);
+        fireEvent.change(editor, { target: { value: "# Latest | draft\n" } });
+      });
+      await act(async () => vi.advanceTimersByTimeAsync(250));
+      expect(loadDraft("conn1", "/docs/readme.md", "markdown")).toEqual(acknowledged);
+
+      act(() => {
+        mockMarkdownEditorBehavior.flushRejectError = null;
+        mockMarkdownEditorBehavior.onNormalizationStateChange?.(false);
+      });
+      await act(async () => vi.advanceTimersByTimeAsync(249));
+      expect(loadDraft("conn1", "/docs/readme.md", "markdown")).toEqual(acknowledged);
+      await act(async () => vi.advanceTimersByTimeAsync(1));
+      expect(loadDraft("conn1", "/docs/readme.md", "markdown")).toMatchObject({
+        baseline: "# Readme\n",
+        content: "# Latest | draft\n",
+      });
+      expect(editor).toHaveValue("# Latest | draft\n");
+      expect(apiService.saveTextFile).not.toHaveBeenCalled();
+    } finally {
+      unmount();
+      vi.useRealTimers();
+    }
+  });
+
   it("clears the local draft when Markdown returns to its saved baseline", async () => {
     vi.spyOn(authSession, "getUserId").mockReturnValue("test-user");
     vi.spyOn(apiService, "getFileContent").mockResolvedValueOnce("# Readme\n");
@@ -1280,7 +1896,7 @@ describe("MarkdownViewer", () => {
       locked_by: "alice",
       locked_at: "2026-03-23T12:00:00Z",
     });
-    let resolveSave: (() => void) | null = null;
+    let resolveSave: () => void = uninitializedTestCallback;
     const saveSpy = vi.spyOn(apiService, "saveTextFile").mockImplementation(
       () =>
         new Promise<void>((resolve) => {
@@ -1441,7 +2057,11 @@ describe("MarkdownViewer", () => {
     expect(releaseSpy).not.toHaveBeenCalledWith("conn1", "/docs/readme.md");
   });
 
-  it("fails closed when flushing pending editor edits fails before save", async () => {
+  it.each([
+    new Error("Flush failed"),
+    new DOMException("Markdown publication timed out", "TimeoutError"),
+    new DOMException("Finish the current input method composition before saving or creating a recovery snapshot.", "InvalidStateError"),
+  ])("retains edits and permits retry when snapshot capture fails: %s", async (failure) => {
     vi.spyOn(apiService, "getFileContent").mockResolvedValueOnce("# Readme\n");
     vi.spyOn(apiService, "supportsEditLocks").mockReturnValue(true);
     vi.spyOn(apiService, "acquireEditLock").mockResolvedValueOnce({
@@ -1454,7 +2074,7 @@ describe("MarkdownViewer", () => {
     });
     const saveSpy = vi.spyOn(apiService, "saveTextFile").mockResolvedValue();
     const releaseSpy = vi.spyOn(apiService, "releaseEditLock").mockResolvedValue();
-    mockMarkdownEditorBehavior.flushRejectError = new Error("Flush failed");
+    mockMarkdownEditorBehavior.flushRejectError = failure;
 
     renderViewer();
 
@@ -1466,12 +2086,139 @@ describe("MarkdownViewer", () => {
     fireEvent.click(screen.getByRole("button", { name: "Save" }));
 
     await waitFor(() => {
-      expect(screen.getByText("Failed to save markdown changes.: Flush failed")).toBeInTheDocument();
+      expect(screen.getByText(`Failed to save markdown changes.: ${failure.message}`)).toBeInTheDocument();
     });
 
     expect(saveSpy).not.toHaveBeenCalled();
     expect(screen.getByRole("textbox", { name: "Markdown editor" })).toBeInTheDocument();
+    expect(editor).toHaveValue("# Updated\n");
     expect(releaseSpy).not.toHaveBeenCalledWith("conn1", "/docs/readme.md");
+    mockMarkdownEditorBehavior.flushRejectError = null;
+    fireEvent.click(screen.getByRole("button", { name: "Save" }));
+    await waitFor(() => expect(saveSpy).toHaveBeenCalled());
+    expect(editor).toHaveValue("# Updated\n");
+  });
+
+  it.each([
+    { latest: "# Newer unsaved\n", pending: false },
+    { latest: "# Saved\n", pending: false },
+    { latest: "# Newer unsaved\n", pending: true },
+  ])("acknowledges Markdown Save without losing current draft $latest with normalization pending $pending", async ({ latest, pending }) => {
+    vi.spyOn(apiService, "getFileContent").mockResolvedValueOnce("# Readme\n");
+    vi.spyOn(apiService, "getThemes").mockResolvedValue({ themes: [], site_default_id: "sambee-light" });
+    vi.spyOn(apiService, "getOriginalFileBlob").mockResolvedValue(new Blob(["# Saved\n"], { type: "text/markdown" }));
+    vi.spyOn(apiService, "releaseEditLock").mockResolvedValue();
+    let finishWrite: (() => void) | undefined;
+    const save = vi.spyOn(apiService, "saveTextFile").mockImplementationOnce(
+      () =>
+        new Promise<void>((resolve) => {
+          finishWrite = resolve;
+        })
+    );
+    renderViewer();
+    await screen.findByText("Readme");
+    fireEvent.click(screen.getByRole("button", { name: "Edit" }));
+    const editor = await screen.findByRole("textbox", { name: "Markdown editor" });
+    fireEvent.change(editor, { target: { value: "# Saved\n" } });
+    fireEvent.click(screen.getByRole("button", { name: "Save" }));
+    await waitFor(() => expect(save).toHaveBeenCalledTimes(1));
+    expect(editor).not.toHaveAttribute("readonly");
+    fireEvent.change(editor, { target: { value: "# Newer unsaved\n" } });
+    if (latest === "# Saved\n") fireEvent.change(editor, { target: { value: latest } });
+    if (pending) mockMarkdownEditorBehavior.flushRejectError = new DOMException("Normalization pending", "InvalidStateError");
+    if (!finishWrite) throw new Error("Expected a pending Markdown write");
+    await act(async () => {
+      finishWrite?.();
+    });
+
+    expect(editor).toHaveValue(latest);
+    expect(screen.queryByText(/Failed to save markdown changes/)).not.toBeInTheDocument();
+    fireEvent.click(screen.getByRole("button", { name: "Close" }));
+    if (latest !== "# Saved\n") {
+      const dialog = await screen.findByRole("dialog", { name: "Unsaved changes" });
+      fireEvent.click(within(dialog).getByRole("button", { name: "Discard" }));
+    } else {
+      expect(screen.queryByRole("dialog", { name: "Unsaved changes" })).not.toBeInTheDocument();
+    }
+    expect(await screen.findByRole("heading", { name: "Saved" })).toBeInTheDocument();
+  });
+
+  it("keeps edits made during snapshot preparation dirty after saving the captured revision", async () => {
+    vi.spyOn(apiService, "getFileContent").mockResolvedValueOnce("# Readme\n");
+    vi.spyOn(apiService, "getOriginalFileBlob").mockResolvedValue(new Blob(["# Captured\n"], { type: "text/markdown" }));
+    const release = vi.spyOn(apiService, "releaseEditLock").mockResolvedValue();
+    const save = vi.spyOn(apiService, "saveTextFile").mockResolvedValue();
+    let finishSnapshot!: () => void;
+    mockMarkdownEditorBehavior.pendingSnapshot = new Promise<void>((resolve) => {
+      finishSnapshot = resolve;
+    });
+    renderViewer();
+    fireEvent.click(await screen.findByRole("button", { name: "Edit" }));
+    const editor = await screen.findByRole("textbox", { name: "Markdown editor" });
+    fireEvent.change(editor, { target: { value: "# Captured\n" } });
+    fireEvent.click(screen.getByRole("button", { name: "Save" }));
+    expect(screen.getByRole("button", { name: "Save" })).toBeDisabled();
+    expect(save).not.toHaveBeenCalled();
+    expect(editor).not.toHaveAttribute("readonly");
+    fireEvent.change(editor, { target: { value: "# Newer while preparing\n" } });
+    await act(async () => {
+      finishSnapshot();
+    });
+    await waitFor(() => expect(screen.getByRole("button", { name: "Save" })).toBeEnabled());
+    expect(save).toHaveBeenCalledExactlyOnceWith("conn1", "/docs/readme.md", "# Captured\n", {
+      filename: "readme.md",
+      mimeType: "text/markdown;charset=utf-8",
+    });
+    expect(editor).toHaveValue("# Newer while preparing\n");
+    expect(screen.getByRole("status", { name: /unsaved changes/i })).toBeInTheDocument();
+    fireEvent.click(screen.getByRole("button", { name: "Close" }));
+    const dialog = await screen.findByRole("dialog", { name: "Unsaved changes" });
+    expect(release).not.toHaveBeenCalled();
+    fireEvent.click(within(dialog).getByRole("button", { name: "Discard" }));
+    expect(await screen.findByRole("heading", { name: "Captured" })).toBeInTheDocument();
+    expect(save).toHaveBeenCalledOnce();
+  });
+
+  it("preserves newer edits after a delayed write fails and retries the latest snapshot", async () => {
+    vi.spyOn(apiService, "getFileContent").mockResolvedValueOnce("# Readme\n");
+    const release = vi.spyOn(apiService, "releaseEditLock").mockResolvedValue();
+    let failWrite: ((reason: Error) => void) | undefined;
+    const save = vi
+      .spyOn(apiService, "saveTextFile")
+      .mockResolvedValue()
+      .mockImplementationOnce(
+        () =>
+          new Promise<void>((_resolve, reject) => {
+            failWrite = reject;
+          })
+      );
+    renderViewer();
+    await screen.findByText("Readme");
+    fireEvent.click(screen.getByRole("button", { name: "Edit" }));
+    const editor = await screen.findByRole("textbox", { name: "Markdown editor" });
+    fireEvent.change(editor, { target: { value: "# First snapshot\n" } });
+    fireEvent.click(screen.getByRole("button", { name: "Save" }));
+    await waitFor(() => expect(save).toHaveBeenCalledTimes(1));
+    expect(save.mock.calls[0]?.[2]).toBe("# First snapshot\n");
+    fireEvent.change(editor, { target: { value: "# Newer unsaved\n" } });
+    const rejectWrite = failWrite;
+    if (!rejectWrite) throw new Error("Expected a pending Markdown write");
+    await act(async () => rejectWrite(new Error("Disk full")));
+    expect(await screen.findByText("Failed to save markdown changes.: Disk full")).toBeInTheDocument();
+    expect(editor).toHaveValue("# Newer unsaved\n");
+    expect(editor).not.toHaveAttribute("readonly");
+    expect(release).not.toHaveBeenCalled();
+    fireEvent.click(screen.getByRole("button", { name: "Close" }));
+    const dialog = await screen.findByRole("dialog", { name: "Unsaved changes" });
+    fireEvent.click(within(dialog).getByRole("button", { name: "Cancel" }));
+    await waitFor(() => expect(screen.queryByRole("dialog", { name: "Unsaved changes" })).not.toBeInTheDocument());
+    fireEvent.click(screen.getByRole("button", { name: "Save" }));
+    await waitFor(() => expect(save).toHaveBeenCalledTimes(2));
+    expect(save.mock.calls[1]?.[2]).toBe("# Newer unsaved\n");
+    await waitFor(() => expect(screen.getByRole("button", { name: "Save" })).toBeEnabled());
+    fireEvent.click(screen.getByRole("button", { name: "Close" }));
+    expect(await screen.findByRole("heading", { name: "Newer unsaved" })).toBeInTheDocument();
+    expect(screen.queryByRole("dialog", { name: "Unsaved changes" })).not.toBeInTheDocument();
   });
 
   it("fails closed when canonical markdown export throws before save", async () => {
@@ -1542,7 +2289,62 @@ describe("MarkdownViewer", () => {
     expect(releaseSpy).not.toHaveBeenCalledWith("conn1", "/docs/readme.md");
   });
 
+  it("does not steal search focus when delayed preview autofocus runs", async () => {
+    vi.spyOn(apiService, "getFileContent").mockResolvedValueOnce("alpha beta\n");
+    const callbacks: (() => void)[] = [];
+    const originalTimeout = setTimeout;
+    const timer = vi.spyOn(window, "setTimeout").mockImplementation((callback, delay, ...args) => {
+      if (delay === MARKDOWN_VIEWER_CONTENT_AUTOFOCUS_DELAY_MS && typeof callback === "function") {
+        callbacks.push(() => callback(...args));
+      }
+      return originalTimeout(callback, delay, ...args);
+    });
+    try {
+      renderViewer();
+      await screen.findByText("alpha beta");
+      const search = await viewerSearch.openSearch("alpha");
+      expect(search).toHaveFocus();
+      expect(callbacks.length).toBeGreaterThan(0);
+      act(() => {
+        for (const callback of callbacks) callback();
+      });
+      expect(search).toHaveFocus();
+      fireEvent.change(search, { target: { value: "beta" } });
+      expect(await screen.findByText("1 / 1")).toBeInTheDocument();
+    } finally {
+      timer.mockRestore();
+    }
+  });
+
+  it("restores open search after leaving edit mode in a progressively rendered preview", async () => {
+    enableSearchHighlights();
+    const paragraphCount = 1500;
+    const markdown = `# Search fixture\n\n${"needle ordinary paragraph text for the search fixture.\n\n".repeat(paragraphCount)}`;
+    vi.spyOn(apiService, "getFileContent").mockResolvedValue(markdown);
+    vi.spyOn(apiService, "getOriginalFileBlob").mockResolvedValue(new Blob([markdown], { type: "text/markdown" }));
+    vi.spyOn(apiService, "supportsEditLocks").mockReturnValue(true);
+    vi.spyOn(apiService, "releaseEditLock").mockResolvedValue();
+
+    renderViewer();
+
+    await waitFor(() => expect(screen.getByRole("button", { name: "Edit" })).toBeEnabled());
+    fireEvent.click(screen.getByRole("button", { name: "Edit" }));
+    await screen.findByRole("textbox", { name: "Markdown editor" });
+    const closeViewerButton = screen.getByRole("button", { name: "Close" });
+    await viewerSearch.openSearch("needle");
+    fireEvent.click(closeViewerButton);
+
+    await waitFor(() => expect(screen.queryByRole("textbox", { name: "Markdown editor" })).not.toBeInTheDocument());
+    await waitFor(() => expect(document.querySelector('[data-markdown-publication="complete"]')).not.toBeNull());
+    expect(screen.getByDisplayValue("needle")).toBeInTheDocument();
+    expect(await screen.findByText(`1 / ${paragraphCount}`)).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: "Next match" })).toBeEnabled();
+    fireEvent.click(screen.getByRole("button", { name: "Next match" }));
+    expect(await screen.findByText(`2 / ${paragraphCount}`)).toBeInTheDocument();
+  });
+
   it("searches rendered markdown and navigates between matches", async () => {
+    enableSearchHighlights();
     vi.spyOn(apiService, "getFileContent").mockResolvedValueOnce("# Alpha\n\nAlpha beta alpha\n");
 
     renderViewer();
@@ -1553,9 +2355,7 @@ describe("MarkdownViewer", () => {
       expectedCounterText: "1 / 3",
     });
 
-    await waitFor(() => {
-      expect(document.querySelectorAll('mark[data-text-search-highlight="true"]').length).toBe(3);
-    });
+    expect(document.querySelectorAll('mark[data-text-search-highlight="true"]')).toHaveLength(0);
 
     await viewerSearch.expectRefinedSearchKeepsCurrentMatchActive({
       refinedSearchTerm: "al",
@@ -1570,6 +2370,7 @@ describe("MarkdownViewer", () => {
   });
 
   it("treats cross-inline markdown text as a single search match", async () => {
+    enableSearchHighlights();
     vi.spyOn(apiService, "getFileContent").mockResolvedValueOnce("sam**bee** sambee\n");
 
     renderViewer();
@@ -1581,7 +2382,9 @@ describe("MarkdownViewer", () => {
       expect(screen.getByText("1 / 2")).toBeInTheDocument();
     });
 
-    expect(document.querySelectorAll('mark[data-text-search-highlight="true"]').length).toBe(3);
+    const current = [...CSS.highlights.entries()].find(([name]) => name.startsWith("markdown-search-") && name.endsWith("-current"));
+    expect(requireTestValue([...current![1]][0]).toString()).toBe("sambee");
+    expect(document.querySelectorAll('mark[data-text-search-highlight="true"]')).toHaveLength(0);
 
     fireEvent.click(screen.getByRole("button", { name: "Next match" }));
 
@@ -2398,7 +3201,7 @@ describe("MarkdownViewer", () => {
     await screen.findByText("Alpha");
     fireEvent.click(screen.getByRole("button", { name: "Edit" }));
 
-    const editor = await screen.findByRole("textbox", { name: "Markdown editor" });
+    const editor = requireTestElement(await screen.findByRole("textbox", { name: "Markdown editor" }), HTMLTextAreaElement);
     const selectionStart = editor.value.indexOf("beta");
     const selectionEnd = selectionStart + "beta".length;
 
@@ -2424,7 +3227,7 @@ describe("MarkdownViewer", () => {
     await screen.findByText("Alpha");
     fireEvent.click(screen.getByRole("button", { name: "Edit" }));
 
-    const editor = await screen.findByRole("textbox", { name: "Markdown editor" });
+    const editor = requireTestElement(await screen.findByRole("textbox", { name: "Markdown editor" }), HTMLTextAreaElement);
     const betaStart = editor.value.indexOf("beta");
     const betaEnd = betaStart + "beta".length;
 
@@ -2470,7 +3273,7 @@ describe("MarkdownViewer", () => {
     await screen.findByText("Alpha");
     fireEvent.click(screen.getByRole("button", { name: "Edit" }));
 
-    const editor = await screen.findByRole("textbox", { name: "Markdown editor" });
+    const editor = requireTestElement(await screen.findByRole("textbox", { name: "Markdown editor" }), HTMLTextAreaElement);
     const betaStart = editor.value.indexOf("beta");
     const betaEnd = betaStart + "beta".length;
 
diff --git a/frontend/src/components/Viewer/__tests__/ProgressiveMarkdown.test.tsx b/frontend/src/components/Viewer/__tests__/ProgressiveMarkdown.test.tsx
new file mode 100644
index 000000000..51db72bc7
--- /dev/null
+++ b/frontend/src/components/Viewer/__tests__/ProgressiveMarkdown.test.tsx
@@ -0,0 +1,261 @@
+import { act, render, waitFor } from "@testing-library/react";
+import { StrictMode } from "react";
+import ReactMarkdown from "react-markdown";
+import remarkGfm from "remark-gfm";
+import { describe, expect, it, vi } from "vitest";
+import { rehypeMarkdownHeadingLinks } from "../../../utils/markdownHeadingLinks";
+import {
+  PROGRESSIVE_MARKDOWN_FRAME_BATCHES,
+  PROGRESSIVE_MARKDOWN_FRAME_MS,
+  PROGRESSIVE_MARKDOWN_MIN_UNITS,
+  ProgressiveMarkdown,
+} from "../ProgressiveMarkdown";
+
+vi.mock("react-i18next", () => ({ useTranslation: () => ({ t: (key: string) => key }) }));
+
+describe("progressive rendered Markdown", () => {
+  it("keeps ordinary documents immediate", () => {
+    const ready = vi.fn();
+    const result = render(
+      <ProgressiveMarkdown onReady={ready} onFailure={vi.fn()}>
+        # Small
+      </ProgressiveMarkdown>
+    );
+    expect(result.container.querySelector("h1")?.textContent).toBe("Small");
+    expect(result.container.querySelector("[aria-busy]")).toBeNull();
+    expect(ready).toHaveBeenCalledOnce();
+  });
+
+  it("appends a whole-document transform without replacing earlier nodes", async () => {
+    const ready = vi.fn();
+    const failed = vi.fn();
+    const transformed = vi.fn();
+    const observeTransform = () => transformed;
+    const source = `# Repeat\n\n[Reference][last]\n\n${"A formatted **paragraph**.\n\n".repeat(2_000)}# Repeat\n\n[last]: https://example.com\n`;
+    expect(source.length).toBeGreaterThan(PROGRESSIVE_MARKDOWN_MIN_UNITS);
+    const result = render(
+      <ProgressiveMarkdown
+        remarkPlugins={[remarkGfm]}
+        rehypePlugins={[rehypeMarkdownHeadingLinks, observeTransform]}
+        onReady={ready}
+        onFailure={failed}
+      >
+        {source}
+      </ProgressiveMarkdown>
+    );
+    const heading = result.container.querySelector("h1");
+    expect(heading?.id).toBe("sambee-markdown-repeat");
+    expect(result.container.querySelector("a")?.href).toBe("https://example.com/");
+    expect(result.container.querySelectorAll("p").length).toBeLessThan(2_001);
+    await waitFor(() => expect(ready).toHaveBeenCalledOnce(), { timeout: 10_000 });
+    expect(result.container.querySelector("h1")).toBe(heading);
+    expect(result.container.querySelectorAll("p")).toHaveLength(2_001);
+    expect(result.container.querySelectorAll("h1")[1]?.id).toBe("sambee-markdown-repeat-1");
+    expect(failed).not.toHaveBeenCalled();
+    expect(transformed).toHaveBeenCalledOnce();
+  });
+
+  it("yields at the initial viewport fill then uses the time budget below it", async () => {
+    const frames: FrameRequestCallback[] = [];
+    vi.stubGlobal("requestAnimationFrame", (callback: FrameRequestCallback) => frames.push(callback));
+    vi.stubGlobal("cancelAnimationFrame", vi.fn());
+    const ready = vi.fn();
+    let now: ReturnType<typeof vi.spyOn> | undefined;
+    try {
+      const result = render(
+        <ProgressiveMarkdown onReady={ready} onFailure={vi.fn()}>
+          {"paragraph\n\n".repeat(5_000)}
+        </ProgressiveMarkdown>
+      );
+      const count = () => result.container.querySelectorAll("p").length;
+      const initialCount = count();
+      let frameStartCount = initialCount;
+      const bounds = vi.fn(() => ({ height: (count() - initialCount) * window.innerHeight }));
+      Object.defineProperty(result.container.firstElementChild, "getBoundingClientRect", { value: bounds });
+      now = vi
+        .spyOn(performance, "now")
+        .mockImplementation(() => ((count() - frameStartCount) / initialCount) * (PROGRESSIVE_MARKDOWN_FRAME_MS / 2));
+      await act(async () => frames.shift()!(0));
+      const firstAppend = count() - initialCount;
+      expect(firstAppend).toBeGreaterThan(0);
+      expect(ready).not.toHaveBeenCalled();
+      const filledCount = count();
+      frameStartCount = filledCount;
+      await act(async () => frames.shift()!(0));
+      expect(count() - filledCount).toBeGreaterThan(firstAppend);
+      expect(count()).toBeLessThan(5_000);
+      expect(bounds).toHaveBeenCalledTimes(2);
+      expect(ready).not.toHaveBeenCalled();
+      const boundedCount = count();
+      now.mockReturnValue(0);
+      await act(async () => frames.shift()!(0));
+      expect(count() - boundedCount).toBe(firstAppend * PROGRESSIVE_MARKDOWN_FRAME_BATCHES);
+      expect(count()).toBeLessThan(5_000);
+      expect(ready).not.toHaveBeenCalled();
+      result.unmount();
+    } finally {
+      now?.mockRestore();
+      vi.unstubAllGlobals();
+    }
+  });
+
+  it("delays feedback and cancels an obsolete source generation", async () => {
+    vi.useFakeTimers();
+    const frames: FrameRequestCallback[] = [];
+    vi.stubGlobal("requestAnimationFrame", (callback: FrameRequestCallback) => frames.push(callback));
+    vi.stubGlobal("cancelAnimationFrame", vi.fn());
+    const ready = vi.fn();
+    try {
+      const result = render(
+        <ProgressiveMarkdown onReady={ready} onFailure={vi.fn()}>
+          {"a paragraph\n\n".repeat(5_000)}
+        </ProgressiveMarkdown>
+      );
+      expect(result.queryByRole("status")).toBeNull();
+      act(() => vi.advanceTimersByTime(199));
+      expect(result.queryByRole("status")).toBeNull();
+      act(() => vi.advanceTimersByTime(1));
+      expect(result.getByRole("status").getAttribute("aria-label")).toBe("app.loading");
+      result.rerender(
+        <ProgressiveMarkdown onReady={ready} onFailure={vi.fn()}>
+          # New source
+        </ProgressiveMarkdown>
+      );
+      await act(async () => {
+        for (const callback of frames.splice(0)) callback(0);
+      });
+      expect(result.container.textContent).toBe("New source");
+      expect(ready).toHaveBeenCalledOnce();
+      expect(result.queryByRole("status")).toBeNull();
+    } finally {
+      vi.unstubAllGlobals();
+      vi.useRealTimers();
+    }
+  });
+
+  it("subdivides one large code block and cancels on unmount", async () => {
+    const callbacks: FrameRequestCallback[] = [];
+    vi.stubGlobal(
+      "requestAnimationFrame",
+      vi.fn((callback: FrameRequestCallback) => {
+        callbacks.push(callback);
+        return callbacks.length;
+      })
+    );
+    vi.stubGlobal("cancelAnimationFrame", vi.fn());
+    const ready = vi.fn();
+    const code = "a line of code\n".repeat(5_000);
+    try {
+      const result = render(<ProgressiveMarkdown onReady={ready} onFailure={vi.fn()}>{`\`\`\`txt\n${code}\`\`\``}</ProgressiveMarkdown>);
+      expect(result.container.querySelectorAll("pre")).toHaveLength(1);
+      expect(result.container.querySelector("code")?.textContent?.length).toBeLessThan(code.length);
+      result.unmount();
+      await act(async () => {
+        for (const callback of callbacks.splice(0)) callback(0);
+      });
+      expect(ready).not.toHaveBeenCalled();
+    } finally {
+      vi.unstubAllGlobals();
+    }
+  });
+
+  it("finishes in a hidden tab without waiting for animation frames", async () => {
+    const hidden = vi.spyOn(document, "hidden", "get").mockReturnValue(true);
+    const frame = vi.fn();
+    vi.stubGlobal("requestAnimationFrame", frame);
+    const ready = vi.fn();
+    try {
+      const result = render(
+        <ProgressiveMarkdown onReady={ready} onFailure={vi.fn()}>
+          {"hidden paragraph\n\n".repeat(4_000)}
+        </ProgressiveMarkdown>
+      );
+      await waitFor(() => expect(ready).toHaveBeenCalledOnce());
+      expect(result.container.querySelectorAll("p")).toHaveLength(4_000);
+      expect(frame).not.toHaveBeenCalled();
+      result.unmount();
+    } finally {
+      hidden.mockRestore();
+      vi.unstubAllGlobals();
+    }
+  });
+
+  it("restarts safely when the same source receives a new rendering configuration", async () => {
+    const source = "a **formatted** paragraph\n\n".repeat(2_000);
+    const pending = vi.fn();
+    const ready = vi.fn();
+    const failed = vi.fn();
+    const result = render(
+      <ProgressiveMarkdown remarkPlugins={[remarkGfm]} onPending={pending} onReady={ready} onFailure={failed}>
+        {source}
+      </ProgressiveMarkdown>
+    );
+    await waitFor(() => expect(ready).toHaveBeenCalledOnce());
+    result.rerender(
+      <ProgressiveMarkdown remarkPlugins={[remarkGfm]} onPending={pending} onReady={ready} onFailure={failed}>
+        {source}
+      </ProgressiveMarkdown>
+    );
+    expect(result.container.querySelector('[aria-busy="true"]')).not.toBeNull();
+    expect(result.container.querySelectorAll("p").length).toBeLessThan(2_000);
+    await waitFor(() => expect(ready).toHaveBeenCalledTimes(2));
+    expect(pending).toHaveBeenCalledTimes(2);
+    expect(result.container.querySelectorAll("p")).toHaveLength(2_000);
+    expect(failed).not.toHaveBeenCalled();
+  });
+
+  it("reports a failed append without scheduling success afterward", async () => {
+    const frames: FrameRequestCallback[] = [];
+    vi.stubGlobal("requestAnimationFrame", (callback: FrameRequestCallback) => frames.push(callback));
+    vi.stubGlobal("cancelAnimationFrame", vi.fn());
+    const ready = vi.fn();
+    const failed = vi.fn();
+    const failure = new Error("Unable to read publication bounds");
+    try {
+      const result = render(
+        <ProgressiveMarkdown onReady={ready} onFailure={failed}>
+          {"paragraph\n\n".repeat(5_000)}
+        </ProgressiveMarkdown>
+      );
+      Object.defineProperty(result.container.firstElementChild, "getBoundingClientRect", {
+        value: () => {
+          throw failure;
+        },
+      });
+      await act(async () => {
+        for (const callback of frames.splice(0)) callback(0);
+      });
+      expect(failed).toHaveBeenCalledExactlyOnceWith(failure);
+      expect(ready).not.toHaveBeenCalled();
+      expect(frames).toHaveLength(0);
+      result.unmount();
+    } finally {
+      vi.unstubAllGlobals();
+    }
+  });
+
+  it("preserves a single large native table and complete code text under Strict Mode", async () => {
+    const rows = Array.from({ length: 2_400 }, (_, index) => `| ${index} | **row ${index}** |`).join("\n");
+    const code = `${"x".repeat(8_191)}\u{1f600}${"next\n".repeat(10_000)}`;
+    const source = `| Key | Value |\n| --- | --- |\n${rows}\n\n\`\`\`txt\n${code}\`\`\`\n\n<script>unsafe()</script>`;
+    const ready = vi.fn();
+    const failed = vi.fn();
+    const result = render(
+      <StrictMode>
+        <ProgressiveMarkdown remarkPlugins={[remarkGfm]} onReady={ready} onFailure={failed}>
+          {source}
+        </ProgressiveMarkdown>
+      </StrictMode>
+    );
+    expect(result.container.querySelectorAll("tbody tr").length).toBeLessThan(2_400);
+    await waitFor(() => expect(ready).toHaveBeenCalledOnce(), { timeout: 10_000 });
+    const expected = render(<ReactMarkdown remarkPlugins={[remarkGfm]}>{source}</ReactMarkdown>);
+    expect(result.container.querySelectorAll("table")).toHaveLength(1);
+    expect(result.container.querySelectorAll("tbody tr")).toHaveLength(2_400);
+    expect(result.container.querySelectorAll("pre")).toHaveLength(1);
+    expect(result.container.querySelector("code")?.textContent).toBe(code);
+    expect(result.container.querySelector("script")).toBeNull();
+    expect(result.container.textContent).toBe(expected.container.textContent);
+    expect(failed).not.toHaveBeenCalled();
+  }, 15_000);
+});
diff --git a/frontend/src/components/Viewer/__tests__/TextCodeEditor.test.tsx b/frontend/src/components/Viewer/__tests__/TextCodeEditor.test.tsx
index dd0da3e4f..13563f62b 100644
--- a/frontend/src/components/Viewer/__tests__/TextCodeEditor.test.tsx
+++ b/frontend/src/components/Viewer/__tests__/TextCodeEditor.test.tsx
@@ -1,7 +1,37 @@
-import { render, screen, waitFor } from "@testing-library/react";
+import { history, redo, undo } from "@codemirror/commands";
+import {
+  findNext,
+  findPrevious,
+  getSearchQuery,
+  replaceAll as nativeReplaceAll,
+  replaceNext,
+  SearchQuery,
+  search,
+  setSearchQuery,
+} from "@codemirror/search";
+import { EditorSelection, EditorState, StateEffect, Transaction, type TransactionSpec } from "@codemirror/state";
+import { EditorView, type ViewPlugin, type ViewUpdate } from "@codemirror/view";
+import { act, render, screen, waitFor } from "@testing-library/react";
 import { createRef } from "react";
-import { describe, expect, it } from "vitest";
+import { describe, expect, it, vi } from "vitest";
+import { requireTestValue } from "../../../test/helpers/assertions";
+import { buildPassiveSearchHighlightExtension } from "../../Editor/buildCodeMirrorSearchHighlights";
 import type { TextEditorThemeOptions } from "../../Editor/buildTextEditorTheme";
+import { findSelectedCodeMirrorSearchMatch } from "../../Editor/codeMirrorSearchMatches";
+import { runSourceRegexSearchCommand, sourceRegexSearchLifecycle } from "../../Editor/sourceRegexSearch";
+import {
+  SOURCE_SEARCH_CHUNK_UNITS,
+  SOURCE_SEARCH_TIMEOUT_MS,
+  type SourceSearchOperation,
+  type SourceSearchRequest,
+  type SourceSearchResponse,
+} from "../../Editor/sourceRegexSearchProtocol";
+import {
+  beginSourceReplacementFeedback,
+  isSourceReplacementPending,
+  SOURCE_REPLACEMENT_FEEDBACK_DELAY_MS,
+} from "../../Editor/sourceReplacementFeedback";
+import { getCodeMirrorFindReplaceMetrics, replaceAll } from "../codeMirrorFindReplace";
 import { TextCodeEditor, type TextCodeEditorHandle } from "../TextCodeEditor";
 
 const TEST_TEXT_THEME: TextEditorThemeOptions = {
@@ -16,7 +46,993 @@ const TEST_TEXT_THEME: TextEditorThemeOptions = {
   textColor: "rgb(31, 38, 43)",
 };
 
+function mockSearchWorkers() {
+  const location = vi.spyOn(window.location, "toString").mockReturnValue("http://localhost:3000/");
+  const workers: MockWorker[] = [];
+  class MockWorker {
+    onmessage?: ((event: { data: SourceSearchResponse }) => void) | null;
+    onerror?: ((event: ErrorEvent) => void) | null;
+    postMessage = vi.fn();
+    terminate = vi.fn();
+    addEventListener = vi.fn();
+    removeEventListener = vi.fn();
+    constructor() {
+      workers.push(this);
+    }
+    emit(message: SourceSearchResponse) {
+      this.onmessage?.({ data: message });
+    }
+  }
+  vi.stubGlobal("Worker", MockWorker);
+  return {
+    workers,
+    restore: () => {
+      vi.unstubAllGlobals();
+      location.mockRestore();
+    },
+  };
+}
+
 describe("TextCodeEditor", () => {
+  it("matches native search, replacement, positions and history after repeatable generated edits in the real worker", async () => {
+    const randomConfig = { seed: 0x5eed1234, multiplier: 1_664_525, increment: 1_013_904_223, steps: 16, maximumDeletion: 5 };
+    const tokens = ["alpha", "Alpha", "ALPHA", "alphabet", "alpha2", "_alpha", "-alpha-", "\n", "\uD83D\uDE80", "e\u0301", " "];
+    const replacements = ["", "$2:$1", "ALPHA\nalpha", "\uD83D\uDE80alpha"];
+    const operations: SourceSearchOperation[] = ["count", "next", "previous", "replace-one", "replace-all"];
+    const commands = { next: findNext, previous: findPrevious, "replace-one": replaceNext, "replace-all": nativeReplaceAll };
+    const responses: SourceSearchResponse[] = [];
+    const effectiveOperations = new Set<SourceSearchOperation>();
+    const selectionDirections = new Set<number>();
+    vi.stubGlobal("postMessage", (response: SourceSearchResponse) => responses.push(response));
+    vi.stubGlobal("onmessage", null);
+    try {
+      await import("../../Editor/sourceRegexSearch.worker");
+      expect(responses.splice(0)).toEqual([{ type: "ready" }]);
+      const handler = globalThis.onmessage!;
+      const send = (message: SourceSearchRequest) => handler.call(window, new MessageEvent("message", { data: message }));
+      for (const expression of ["(alpha)(\\d?)", "(?=alpha)"]) {
+        for (const caseSensitive of [false, true]) {
+          for (const wholeWord of [false, true]) {
+            for (const wordChars of ["", "-"]) {
+              let seed = randomConfig.seed;
+              const choose = (limit: number) => {
+                seed = (Math.imul(seed, randomConfig.multiplier) + randomConfig.increment) >>> 0;
+                return (seed >>> 8) % limit;
+              };
+              let state = EditorState.create({
+                doc: tokens.join(" "),
+                extensions: [search(), history(), EditorState.languageData.of(() => [{ wordChars }])],
+              });
+              for (let step = 0; step < randomConfig.steps; step += 1) {
+                const from = choose(state.doc.length + 1);
+                const to = from + choose(Math.min(randomConfig.maximumDeletion, state.doc.length - from) + 1);
+                state = state.update({ changes: { from, to, insert: tokens[choose(tokens.length)] }, userEvent: "input.type" }).state;
+                const anchor = choose(state.doc.length + 1);
+                const head = step % 3 === 0 ? anchor : choose(state.doc.length + 1);
+                selectionDirections.add(Math.sign(head - anchor));
+                const replace = requireTestValue(replacements[step % replacements.length]);
+                const query = new SearchQuery({ search: expression, replace, regexp: true, literal: true, caseSensitive, wholeWord });
+                state = state.update({ selection: EditorSelection.range(anchor, head), effects: setSearchQuery.of(query) }).state;
+                const operation = requireTestValue(operations[step % operations.length]);
+                const context = JSON.stringify({
+                  seed: randomConfig.seed,
+                  step,
+                  expression,
+                  caseSensitive,
+                  wholeWord,
+                  wordChars,
+                  operation,
+                });
+                const changes: { from: number; to: number; insert: string }[] = [];
+                const ranges: { from: number; to: number }[] = [];
+                let completion: Extract<SourceSearchResponse, { type: "complete" }> | undefined;
+                let sourceOffset = 0;
+                responses.length = 0;
+                send({
+                  type: "start",
+                  operation,
+                  query: { search: expression, replace, caseSensitive, wholeWord, wordChars, literal: true },
+                  selection: { anchor, head },
+                });
+                for (let responseIndex = 0; responseIndex < responses.length; responseIndex += 1) {
+                  const response = requireTestValue(responses[responseIndex]);
+                  if (response.type === "source-ack") {
+                    const text = state.doc.sliceString(sourceOffset, sourceOffset + SOURCE_SEARCH_CHUNK_UNITS);
+                    sourceOffset += text.length;
+                    send({ type: "source", text, complete: sourceOffset === state.doc.length });
+                  } else if (response.type === "ranges") {
+                    ranges.push(...response.ranges);
+                    send({ type: "ack" });
+                  } else if (response.type === "change") {
+                    if (response.continued) {
+                      expect(changes.at(-1), context).toMatchObject({ from: response.from, to: response.to });
+                      requireTestValue(changes[changes.length - 1]).insert += response.insert;
+                    } else changes.push({ from: response.from, to: response.to, insert: response.insert });
+                    send({ type: "ack" });
+                  } else if (response.type === "announcement") send({ type: "ack" });
+                  else if (response.type === "complete") completion = response;
+                  else throw new Error(`${context}: unexpected worker response ${JSON.stringify(response)}`);
+                }
+                expect(completion, context).toBeDefined();
+                if (operation === "count") {
+                  const expectedRanges = [];
+                  const cursor = query.getCursor(state);
+                  for (let match = cursor.next(); !match.done; match = cursor.next())
+                    expectedRanges.push({ from: match.value.from, to: match.value.to });
+                  expect(ranges, context).toEqual(expectedRanges);
+                  expect(changes, context).toEqual([]);
+                  if (ranges.length) effectiveOperations.add(operation);
+                  continue;
+                }
+                let expectedTransaction: Transaction | undefined;
+                commands[operation]({
+                  state,
+                  plugin: () => null,
+                  dispatch: (spec: TransactionSpec) => {
+                    expectedTransaction = state.update(spec);
+                  },
+                } as unknown as EditorView);
+                const expected = expectedTransaction?.state ?? state;
+                const replay = state.update({ changes, selection: completion!.selection, userEvent: completion!.userEvent });
+                expect(replay.state.doc.toString(), context).toBe(expected.doc.toString());
+                expect(replay.state.selection.toJSON(), context).toEqual(expected.selection.toJSON());
+                if (replay.docChanged || !replay.state.selection.eq(state.selection)) effectiveOperations.add(requireTestValue(operation));
+                expect(completion!.userEvent, context).toBe(expectedTransaction?.annotation(Transaction.userEvent));
+                const expectedChanges = expectedTransaction?.changes ?? state.changes();
+                for (let position = 0; position <= state.doc.length; position += 1) {
+                  for (const association of [-1, 1])
+                    expect(replay.changes.mapPos(position, association), context).toBe(expectedChanges.mapPos(position, association));
+                }
+                let actualHistory = replay.state;
+                let expectedHistory = expected;
+                for (const historyCommand of [undo, redo]) {
+                  const actualResult = historyCommand({
+                    state: actualHistory,
+                    dispatch: (transaction) => {
+                      actualHistory = transaction.state;
+                    },
+                  });
+                  const expectedResult = historyCommand({
+                    state: expectedHistory,
+                    dispatch: (transaction) => {
+                      expectedHistory = transaction.state;
+                    },
+                  });
+                  expect(actualResult, context).toBe(expectedResult);
+                  expect(actualHistory.doc.toString(), context).toBe(expectedHistory.doc.toString());
+                  expect(actualHistory.selection.toJSON(), context).toEqual(expectedHistory.selection.toJSON());
+                }
+                state = replay.state;
+              }
+            }
+          }
+        }
+      }
+      for (const expression of ["alpha", "(?=alpha)", "a.a", "a+"]) {
+        for (const wholeWord of [false, true]) {
+          const query = new SearchQuery({ search: expression, regexp: true, wholeWord });
+          let requestWordChars = "$";
+          let reference = EditorState.create({
+            doc: "alpha alphabet ALPHA $alpha\nalpha alpha",
+            selection: EditorSelection.range(10, 2),
+            extensions: [search(), EditorState.languageData.of(() => [{ wordChars: requestWordChars }])],
+          });
+          reference = reference.update({ effects: setSearchQuery.of(query) }).state;
+          const navigation: ("next" | "previous")[] = ["next", "next", "previous", "next", "next", "next", "next", "previous", "previous"];
+          for (const [index, operation] of navigation.entries()) {
+            requestWordChars = index % 2 ? "" : "$";
+            const selection = { anchor: reference.selection.main.anchor, head: reference.selection.main.head };
+            responses.length = 0;
+            if (index === 0) {
+              send({
+                type: "start",
+                operation,
+                query: { search: expression, replace: "", caseSensitive: false, wholeWord, wordChars: requestWordChars, literal: true },
+                selection,
+              });
+              expect(responses.splice(0)).toEqual([{ type: "source-ack" }]);
+              send({ type: "source", text: reference.doc.toString(), complete: true });
+            } else send({ type: "navigate", operation, selection, wordChars: requestWordChars });
+            commands[operation]({
+              state: reference,
+              plugin: () => null,
+              dispatch: (spec: TransactionSpec) => {
+                reference = reference.update(spec).state;
+              },
+            } as unknown as EditorView);
+            let completion: Extract<SourceSearchResponse, { type: "complete" }> | undefined;
+            for (let responseIndex = 0; responseIndex < responses.length; responseIndex += 1) {
+              const response = requireTestValue(responses[responseIndex]);
+              if (response.type === "announcement") send({ type: "ack" });
+              else if (response.type === "complete") completion = response;
+              else throw new Error(`Unexpected navigation response ${JSON.stringify(response)}`);
+            }
+            expect(completion).toBeDefined();
+            expect(completion!.selection ?? selection).toEqual({
+              anchor: reference.selection.main.anchor,
+              head: reference.selection.main.head,
+            });
+          }
+        }
+      }
+      expect([...effectiveOperations].sort()).toEqual([...operations].sort());
+      expect([...selectionDirections].sort()).toEqual([-1, 0, 1]);
+    } finally {
+      vi.unstubAllGlobals();
+    }
+  });
+
+  it.each([
+    { name: "case-sensitive", search: "alpha", caseSensitive: true, wholeWord: false },
+    { name: "whole-word", search: "alpha", caseSensitive: false, wholeWord: true },
+    { name: "case-sensitive whole-word", search: "alpha", caseSensitive: true, wholeWord: true },
+    { name: "zero-length", search: "(?=alpha)", caseSensitive: false, wholeWord: false },
+  ])("preserves native position mapping and history for $name worker replacements", ({ search: expression, ...options }) => {
+    const mock = mockSearchWorkers();
+    const source = "\uD83D\uDE80 Alpha alpha alphabet _alpha alpha_\nalpha tail";
+    const query = new SearchQuery({ ...options, search: expression, replace: "XY\nZ", regexp: true, literal: true });
+    const transactions: Transaction[] = [];
+    const view = new EditorView({
+      state: EditorState.create({
+        doc: source,
+        selection: EditorSelection.range(source.length - 2, 3),
+        extensions: [
+          search(),
+          history(),
+          sourceRegexSearchLifecycle,
+          EditorView.updateListener.of((update) => {
+            transactions.push(...update.transactions.filter((transaction) => transaction.docChanged));
+          }),
+        ],
+      }),
+    });
+    const reference = new EditorView({
+      state: EditorState.create({ doc: source, selection: view.state.selection, extensions: [search(), history()] }),
+    });
+    try {
+      for (const editor of [view, reference]) editor.dispatch({ effects: setSearchQuery.of(query) });
+      const before = view.state;
+      let expectedTransaction: Transaction | undefined;
+      const dispatch = vi.spyOn(reference, "dispatch").mockImplementation((...specs) => {
+        expectedTransaction = reference.state.update(...specs);
+        reference.update([expectedTransaction]);
+      });
+      nativeReplaceAll(reference);
+      dispatch.mockRestore();
+      expect(expectedTransaction?.docChanged).toBe(true);
+      runSourceRegexSearchCommand(view, "replace-all");
+      const worker = mock.workers.at(-1)!;
+      expectedTransaction!.changes.iterChanges((from, to, _fromNew, _toNew, inserted) => {
+        worker.emit({ type: "change", from, to, insert: inserted.toString(), continued: false });
+      });
+      worker.emit({ type: "complete", announcements: [] });
+      expect(transactions).toHaveLength(1);
+      expect(view.state.doc.eq(reference.state.doc)).toBe(true);
+      expect(view.state.selection.toJSON()).toEqual(reference.state.selection.toJSON());
+      for (let position = 0; position <= source.length; position += 1) {
+        for (const association of [-1, 1]) {
+          expect(requireTestValue(transactions[0]).changes.mapPos(position, association)).toBe(
+            expectedTransaction!.changes.mapPos(position, association)
+          );
+        }
+      }
+      expect(undo(view)).toBe(true);
+      expect(view.state.doc.eq(before.doc)).toBe(true);
+      expect(view.state.selection.toJSON()).toEqual(before.selection.toJSON());
+      expect(redo(view)).toBe(true);
+      expect(view.state.doc.eq(reference.state.doc)).toBe(true);
+      expect(view.state.selection.toJSON()).toEqual(reference.state.selection.toJSON());
+    } finally {
+      view.destroy();
+      reference.destroy();
+      mock.restore();
+    }
+  });
+
+  it("keeps quick literal replacements synchronous without busy feedback", () => {
+    const view = new EditorView({ state: EditorState.create({ doc: "alpha alpha", extensions: [search()] }) });
+    try {
+      view.dispatch({ effects: setSearchQuery.of(new SearchQuery({ search: "alpha", replace: "done" })) });
+      replaceAll(view);
+      expect(view.state.doc.toString()).toBe("done done");
+      expect(view.dom.querySelector('[role="status"]')).toBeNull();
+      expect(isSourceReplacementPending(view)).toBe(false);
+    } finally {
+      view.destroy();
+    }
+  });
+
+  it("delays preparation feedback and removes it immediately on completion", async () => {
+    vi.useFakeTimers();
+    const view = new EditorView({ state: EditorState.create({ doc: "alpha", extensions: [search()] }) });
+    try {
+      const quick = beginSourceReplacementFeedback(view);
+      quick.apply(
+        () => {},
+        false,
+        () => {}
+      );
+      await vi.advanceTimersByTimeAsync(SOURCE_REPLACEMENT_FEEDBACK_DELAY_MS);
+      expect(view.dom.querySelector('[role="status"]')).toBeNull();
+      const slow = beginSourceReplacementFeedback(view);
+      await vi.advanceTimersByTimeAsync(SOURCE_REPLACEMENT_FEEDBACK_DELAY_MS - 1);
+      expect(view.dom.querySelector('[role="status"]')).toBeNull();
+      await vi.advanceTimersByTimeAsync(1);
+      expect(view.dom.querySelector('[role="status"]')).not.toBeNull();
+      slow.dispose();
+      expect(view.dom.querySelector('[role="status"]')).toBeNull();
+      expect(view.dom).not.toHaveAttribute("aria-busy");
+    } finally {
+      view.destroy();
+      vi.useRealTimers();
+    }
+  });
+
+  it("paints heavy literal feedback before applying once and cancels stale work", async () => {
+    vi.useFakeTimers();
+    const source = "alpha ".repeat(10_000);
+    const view = new EditorView({ state: EditorState.create({ doc: source, extensions: [search()] }) });
+    try {
+      view.dispatch({ effects: setSearchQuery.of(new SearchQuery({ search: "alpha", replace: "done" })) });
+      replaceAll(view);
+      replaceAll(view);
+      expect(view.state.doc.toString()).toBe(source);
+      expect(view.dom.querySelector('[role="status"]')).not.toBeNull();
+      view.dispatch({ changes: { from: 0, insert: "new " } });
+      await vi.advanceTimersByTimeAsync(100);
+      expect(view.state.doc.toString()).toBe(`new ${source}`);
+      expect(isSourceReplacementPending(view)).toBe(false);
+      expect(view.dom.querySelector('[role="status"]')).toBeNull();
+    } finally {
+      view.destroy();
+      vi.useRealTimers();
+    }
+  });
+
+  it("keeps quick worker replacements free of feedback and delays slow preparation", async () => {
+    vi.useFakeTimers();
+    const mock = mockSearchWorkers();
+    const view = new EditorView({ state: EditorState.create({ doc: "aa aa", extensions: [search(), sourceRegexSearchLifecycle] }) });
+    try {
+      view.dispatch({ effects: setSearchQuery.of(new SearchQuery({ search: "a+", replace: "b", regexp: true })) });
+      runSourceRegexSearchCommand(view, "replace-all");
+      const quick = mock.workers.at(-1)!;
+      quick.emit({ type: "change", from: 0, to: 2, insert: "b", continued: false });
+      quick.emit({ type: "complete", announcements: [] });
+      expect(view.state.doc.toString()).toBe("b aa");
+      expect(view.dom.querySelector('[role="status"]')).toBeNull();
+      runSourceRegexSearchCommand(view, "replace-all");
+      const slow = mock.workers.at(-1)!;
+      await vi.advanceTimersByTimeAsync(SOURCE_REPLACEMENT_FEEDBACK_DELAY_MS - 1);
+      expect(view.dom.querySelector('[role="status"]')).toBeNull();
+      await vi.advanceTimersByTimeAsync(1);
+      expect(view.dom.querySelector('[role="status"]')).not.toBeNull();
+      slow.emit({ type: "error", message: "Replacement failed; retry." });
+      expect(view.dom.querySelector('[role="status"]')).toBeNull();
+      expect(isSourceReplacementPending(view)).toBe(false);
+    } finally {
+      view.destroy();
+      mock.restore();
+      vi.useRealTimers();
+    }
+  });
+
+  it("applies a heavy literal plan once with native undo and redo", async () => {
+    vi.useFakeTimers();
+    const source = "alpha ".repeat(10_000);
+    let transactions = 0;
+    const view = new EditorView({
+      state: EditorState.create({
+        doc: source,
+        extensions: [
+          search(),
+          history(),
+          EditorView.updateListener.of((update) => {
+            if (update.docChanged) transactions += 1;
+          }),
+        ],
+      }),
+    });
+    try {
+      view.dispatch({ effects: setSearchQuery.of(new SearchQuery({ search: "alpha", replace: "done" })) });
+      replaceAll(view);
+      replaceAll(view);
+      expect(view.state.doc.toString()).toBe(source);
+      expect(view.contentDOM).toHaveAttribute("aria-busy", "true");
+      await vi.advanceTimersByTimeAsync(100);
+      expect(view.state.doc.toString()).toBe("done ".repeat(10_000));
+      expect(transactions).toBe(1);
+      expect(view.dom.querySelector('[role="status"]')).toBeNull();
+      expect(view.contentDOM).not.toHaveAttribute("aria-busy");
+      undo(view);
+      expect(view.state.doc.toString()).toBe(source);
+      redo(view);
+      expect(view.state.doc.toString()).toBe("done ".repeat(10_000));
+    } finally {
+      view.destroy();
+      vi.useRealTimers();
+    }
+  });
+
+  it.each(["selection", "query", "read-only", "destroy"])("cancels a deferred heavy replacement on %s", async (reason) => {
+    vi.useFakeTimers();
+    const source = "alpha ".repeat(10_000);
+    const view = new EditorView({ state: EditorState.create({ doc: source, extensions: [search()] }) });
+    const destroyView = vi.spyOn(view, "destroy");
+    try {
+      view.dispatch({ effects: setSearchQuery.of(new SearchQuery({ search: "alpha", replace: "done" })) });
+      replaceAll(view);
+      if (reason === "selection") view.dispatch({ selection: { anchor: 2 } });
+      if (reason === "query") view.dispatch({ effects: setSearchQuery.of(new SearchQuery({ search: "other" })) });
+      if (reason === "read-only") view.dispatch({ effects: StateEffect.appendConfig.of(EditorState.readOnly.of(true)) });
+      if (reason === "destroy") view.destroy();
+      await vi.advanceTimersByTimeAsync(100);
+      expect(view.state.doc.toString()).toBe(source);
+      expect(isSourceReplacementPending(view)).toBe(false);
+      expect(view.dom.querySelector('[role="status"]')).toBeNull();
+    } finally {
+      if (!(destroyView.mock.calls.length > 0)) view.destroy();
+      vi.useRealTimers();
+    }
+  });
+
+  it("keeps slow worker feedback through the paint boundary and clears pending on selection cancellation", async () => {
+    vi.useFakeTimers();
+    const mock = mockSearchWorkers();
+    const view = new EditorView({ state: EditorState.create({ doc: "aa aa", extensions: [search(), sourceRegexSearchLifecycle] }) });
+    try {
+      view.dispatch({ effects: setSearchQuery.of(new SearchQuery({ search: "a+", replace: "b", regexp: true })) });
+      runSourceRegexSearchCommand(view, "replace-all");
+      const worker = mock.workers.at(-1)!;
+      await vi.advanceTimersByTimeAsync(SOURCE_REPLACEMENT_FEEDBACK_DELAY_MS);
+      worker.emit({ type: "change", from: 0, to: 2, insert: "b", continued: false });
+      worker.emit({ type: "complete", announcements: [] });
+      expect(view.state.doc.toString()).toBe("aa aa");
+      view.dispatch({ selection: { anchor: 3 } });
+      await vi.advanceTimersByTimeAsync(100);
+      expect(view.state.doc.toString()).toBe("aa aa");
+      expect(getCodeMirrorFindReplaceMetrics(view).pending).toBe(false);
+      expect(view.dom.querySelector('[role="status"]')).toBeNull();
+    } finally {
+      view.destroy();
+      mock.restore();
+      vi.useRealTimers();
+    }
+  });
+
+  it("completes heavy work in a hidden document and clears feedback after an application error", async () => {
+    vi.useFakeTimers();
+    const hidden = vi.spyOn(document, "hidden", "get").mockReturnValue(true);
+    const view = new EditorView({ state: EditorState.create({ doc: "alpha", extensions: [search()] }) });
+    try {
+      const action = vi.fn(() => {
+        throw new Error("Apply failed");
+      });
+      const failure = vi.fn();
+      beginSourceReplacementFeedback(view).apply(action, true, failure);
+      await vi.advanceTimersByTimeAsync(1);
+      expect(action).toHaveBeenCalledOnce();
+      expect(failure).toHaveBeenCalledWith(expect.objectContaining({ message: "Apply failed" }));
+      expect(view.dom.querySelector('[role="status"]')).toBeNull();
+      expect(isSourceReplacementPending(view)).toBe(false);
+    } finally {
+      view.destroy();
+      hidden.mockRestore();
+      vi.useRealTimers();
+    }
+  });
+
+  it.each(["timeout", "destroy"])("clears slow worker feedback on %s", async (reason) => {
+    vi.useFakeTimers();
+    const mock = mockSearchWorkers();
+    const view = new EditorView({ state: EditorState.create({ doc: "alpha", extensions: [search(), sourceRegexSearchLifecycle] }) });
+    const destroyView = vi.spyOn(view, "destroy");
+    try {
+      view.dispatch({ effects: setSearchQuery.of(new SearchQuery({ search: "a", regexp: true })) });
+      runSourceRegexSearchCommand(view, "replace-all");
+      const worker = mock.workers.at(-1)!;
+      await vi.advanceTimersByTimeAsync(SOURCE_REPLACEMENT_FEEDBACK_DELAY_MS);
+      expect(view.dom.querySelector('[role="status"]')).not.toBeNull();
+      if (reason === "destroy") view.destroy();
+      else await vi.advanceTimersByTimeAsync(SOURCE_SEARCH_TIMEOUT_MS);
+      expect(view.dom.querySelector('[role="status"]')).toBeNull();
+      expect(isSourceReplacementPending(view)).toBe(false);
+      expect(worker.terminate).toHaveBeenCalledOnce();
+    } finally {
+      if (!(destroyView.mock.calls.length > 0)) view.destroy();
+      mock.restore();
+      vi.useRealTimers();
+    }
+  });
+
+  it("does not animate replacement feedback when reduced motion is requested", async () => {
+    vi.useFakeTimers();
+    const view = new EditorView({ state: EditorState.create({ doc: "alpha", extensions: [search()] }) });
+    const matchMedia = vi.spyOn(window, "matchMedia").mockReturnValue({ matches: true } as MediaQueryList);
+    const animate = vi.fn();
+    const previousAnimate = HTMLElement.prototype.animate;
+    HTMLElement.prototype.animate = animate;
+    try {
+      const feedback = beginSourceReplacementFeedback(view);
+      await vi.advanceTimersByTimeAsync(SOURCE_REPLACEMENT_FEEDBACK_DELAY_MS);
+      expect(view.dom.querySelector('[role="status"]')).not.toBeNull();
+      expect(animate).not.toHaveBeenCalled();
+      feedback.dispose();
+    } finally {
+      view.destroy();
+      HTMLElement.prototype.animate = previousAnimate;
+      matchMedia.mockRestore();
+      vi.useRealTimers();
+    }
+  });
+
+  it("retains an unchanged regex session when passive decorations are reconfigured", () => {
+    const mock = mockSearchWorkers();
+    const extensions = () => [search(), sourceRegexSearchLifecycle, buildPassiveSearchHighlightExtension()];
+    const view = new EditorView({ state: EditorState.create({ doc: "aa", extensions: extensions() }) });
+    try {
+      view.dispatch({ effects: setSearchQuery.of(new SearchQuery({ search: "a+", regexp: true })) });
+      view.dispatch({ effects: StateEffect.reconfigure.of(extensions()) });
+      expect(getCodeMirrorFindReplaceMetrics(view).pending).toBe(true);
+      expect(mock.workers).toHaveLength(1);
+      expect(requireTestValue(mock.workers[0]).terminate).not.toHaveBeenCalled();
+    } finally {
+      view.destroy();
+      mock.restore();
+    }
+    expect(requireTestValue(mock.workers[0]).terminate).toHaveBeenCalledOnce();
+  });
+
+  it("publishes exact regex counts only after the final worker batch without recounting selection changes", async () => {
+    const mock = mockSearchWorkers();
+    const view = new EditorView({
+      state: EditorState.create({ doc: "aa aa", extensions: [search(), buildPassiveSearchHighlightExtension()] }),
+    });
+    const cursor = vi.spyOn(SearchQuery.prototype, "getCursor");
+    try {
+      view.dispatch({ effects: setSearchQuery.of(new SearchQuery({ search: "a+", regexp: true })) });
+      expect(getCodeMirrorFindReplaceMetrics(view).pending).toBe(true);
+      const worker = requireTestValue(mock.workers[0]);
+      worker.emit({ type: "ready" });
+      expect(worker.postMessage).toHaveBeenLastCalledWith(expect.objectContaining({ query: expect.objectContaining({ wordChars: "" }) }));
+      worker.emit({ type: "source-ack" });
+      worker.emit({
+        type: "ranges",
+        ranges: [
+          { from: 0, to: 2 },
+          { from: 3, to: 5 },
+        ],
+      });
+      expect(getCodeMirrorFindReplaceMetrics(view)).toMatchObject({ matches: 0, pending: true });
+      worker.emit({ type: "complete", announcements: [] });
+      await Promise.resolve();
+      view.dispatch({ selection: { anchor: 3, head: 5 } });
+      expect(getCodeMirrorFindReplaceMetrics(view)).toMatchObject({ matches: 2, currentMatch: 2, pending: false });
+      expect(mock.workers).toHaveLength(1);
+      expect(cursor).not.toHaveBeenCalled();
+      expect(worker.terminate).toHaveBeenCalledOnce();
+    } finally {
+      cursor.mockRestore();
+      view.destroy();
+      mock.restore();
+    }
+  });
+
+  it.each(["complete", "failure", "cancel", "destroy"])("releases regex worker callbacks after %s", async (reason) => {
+    const mock = mockSearchWorkers();
+    const view = new EditorView({
+      state: EditorState.create({ doc: "aa aa", extensions: [search(), sourceRegexSearchLifecycle] }),
+    });
+    const destroyView = vi.spyOn(view, "destroy");
+    try {
+      view.dispatch({ effects: setSearchQuery.of(new SearchQuery({ search: "a+", regexp: true })) });
+      getCodeMirrorFindReplaceMetrics(view);
+      const worker = requireTestValue(mock.workers[0]);
+      const decode = worker.addEventListener.mock.calls.find(([type]) => type === "messageerror")?.[1];
+      expect(decode).toBeTypeOf("function");
+      if (reason === "complete") worker.emit({ type: "complete", announcements: [] });
+      else if (reason === "failure") worker.emit({ type: "error", message: "Search failed" });
+      else if (reason === "cancel") view.dispatch({ changes: { from: 0, insert: "new " } });
+      else view.destroy();
+      await Promise.resolve();
+      expect(worker.terminate).toHaveBeenCalledOnce();
+      expect(worker.onmessage).toBeNull();
+      expect(worker.onerror).toBeNull();
+      expect(worker.removeEventListener).toHaveBeenCalledWith("messageerror", decode);
+    } finally {
+      if (!(destroyView.mock.calls.length > 0)) view.destroy();
+      mock.restore();
+    }
+  });
+
+  it("preserves repeated regex navigation without restarting the active worker", () => {
+    const mock = mockSearchWorkers();
+    const view = new EditorView({
+      state: EditorState.create({ doc: "aa aa aa aa", extensions: [search(), sourceRegexSearchLifecycle] }),
+    });
+    try {
+      view.dispatch({ effects: setSearchQuery.of(new SearchQuery({ search: "a+", regexp: true })) });
+      getCodeMirrorFindReplaceMetrics(view);
+      requireTestValue(mock.workers[0]).emit({
+        type: "ranges",
+        ranges: [0, 3, 6, 9].map((from) => ({ from, to: from + 2 })),
+      });
+      requireTestValue(mock.workers[0]).emit({ type: "complete", announcements: [] });
+      for (let index = 0; index < 3; index += 1) runSourceRegexSearchCommand(view, "next");
+      expect(mock.workers).toHaveLength(2);
+      const worker = requireTestValue(mock.workers[1]);
+      expect(worker.terminate).not.toHaveBeenCalled();
+      for (const from of [0, 3, 6]) {
+        worker.emit({ type: "complete", selection: { anchor: from, head: from + 2 }, announcements: [] });
+        expect(view.state.selection.main.from).toBe(from);
+      }
+      expect(worker.postMessage.mock.calls.map(([message]) => message)).toEqual([
+        { type: "navigate", operation: "next", selection: { anchor: 0, head: 2 }, wordChars: "" },
+        { type: "navigate", operation: "next", selection: { anchor: 3, head: 5 }, wordChars: "" },
+      ]);
+      expect(worker.terminate).toHaveBeenCalledOnce();
+      expect(getCodeMirrorFindReplaceMetrics(view)).toMatchObject({ pending: false, matches: 4, currentMatch: 3 });
+    } finally {
+      view.destroy();
+      mock.restore();
+    }
+  });
+
+  it.each(["next", "previous"] as const)("keeps mixed queued regex navigation in order after %s", (operation) => {
+    const mock = mockSearchWorkers();
+    const view = new EditorView({
+      state: EditorState.create({
+        doc: "$alpha alpha",
+        extensions: [search(), sourceRegexSearchLifecycle, EditorState.languageData.of(() => [{ wordChars: "$" }])],
+      }),
+    });
+    try {
+      view.dispatch({ effects: setSearchQuery.of(new SearchQuery({ search: "alpha", regexp: true, wholeWord: true })) });
+      runSourceRegexSearchCommand(view, operation);
+      runSourceRegexSearchCommand(view, "previous");
+      runSourceRegexSearchCommand(view, "next");
+      const worker = mock.workers.at(-1)!;
+      worker.emit({ type: "complete", selection: { anchor: 7, head: 12 }, announcements: [] });
+      expect(getCodeMirrorFindReplaceMetrics(view).pending).toBe(true);
+      expect(worker.postMessage).toHaveBeenLastCalledWith({
+        type: "navigate",
+        operation: "previous",
+        selection: { anchor: 7, head: 12 },
+        wordChars: "$",
+      });
+      worker.emit({ type: "complete", announcements: [] });
+      expect(worker.postMessage).toHaveBeenLastCalledWith({
+        type: "navigate",
+        operation: "next",
+        selection: { anchor: 7, head: 12 },
+        wordChars: "$",
+      });
+      worker.emit({ type: "complete", selection: { anchor: 7, head: 12 }, announcements: [] });
+      expect(worker.terminate).toHaveBeenCalledOnce();
+    } finally {
+      view.destroy();
+      mock.restore();
+    }
+  });
+
+  it.each(["selection", "document", "query", "destroy", "error", "timeout"])("cancels queued regex navigation on %s", async (reason) => {
+    vi.useFakeTimers();
+    const mock = mockSearchWorkers();
+    const view = new EditorView({ state: EditorState.create({ doc: "aa aa", extensions: [search(), sourceRegexSearchLifecycle] }) });
+    const destroyView = vi.spyOn(view, "destroy");
+    try {
+      view.dispatch({ effects: setSearchQuery.of(new SearchQuery({ search: "a+", regexp: true })) });
+      runSourceRegexSearchCommand(view, "next");
+      runSourceRegexSearchCommand(view, "previous");
+      const worker = mock.workers.at(-1)!;
+      if (reason === "selection") {
+        view.dispatch({ selection: { anchor: 3 } });
+        view.dispatch({ selection: { anchor: 0 } });
+      } else if (reason === "document") view.dispatch({ changes: { from: 0, insert: "new " } });
+      else if (reason === "query") view.dispatch({ effects: setSearchQuery.of(new SearchQuery({ search: "b+", regexp: true })) });
+      else if (reason === "destroy") view.destroy();
+      else if (reason === "error") worker.emit({ type: "error", message: "Navigation failed" });
+      else await vi.advanceTimersByTimeAsync(SOURCE_SEARCH_TIMEOUT_MS);
+      worker.emit({ type: "complete", selection: { anchor: 0, head: 2 }, announcements: [] });
+      expect(view.state.selection.main.empty).toBe(true);
+      expect(worker.terminate).toHaveBeenCalledOnce();
+      expect(worker.postMessage).not.toHaveBeenCalledWith(expect.objectContaining({ type: "navigate" }));
+    } finally {
+      if (!(destroyView.mock.calls.length > 0)) view.destroy();
+      mock.restore();
+      vi.useRealTimers();
+    }
+  });
+
+  it("allows pending navigation but rejects a replacement after selection changes away and back", async () => {
+    const mock = mockSearchWorkers();
+    const view = new EditorView({
+      state: EditorState.create({ doc: "aa aa", extensions: [search(), buildPassiveSearchHighlightExtension()] }),
+    });
+    try {
+      view.dispatch({ effects: setSearchQuery.of(new SearchQuery({ search: "a+", regexp: true })) });
+      expect(runSourceRegexSearchCommand(view, "next")).toBe(true);
+      expect(requireTestValue(mock.workers[0]).terminate).toHaveBeenCalledOnce();
+      requireTestValue(mock.workers[1]).emit({ type: "complete", selection: { anchor: 0, head: 2 }, announcements: [] });
+      expect(view.state.selection.main.to).toBe(2);
+      runSourceRegexSearchCommand(view, "replace-all");
+      const worker = mock.workers.at(-1)!;
+      worker.emit({ type: "change", from: 0, to: 2, insert: "replacement", continued: false });
+      expect(view.state.doc.toString()).toBe("aa aa");
+      view.dispatch({ selection: { anchor: 3 } });
+      view.dispatch({ selection: { anchor: 0, head: 2 } });
+      worker.emit({ type: "complete", announcements: [] });
+      await Promise.resolve();
+      expect(view.state.doc.toString()).toBe("aa aa");
+      expect(getCodeMirrorFindReplaceMetrics(view).error).toMatch(/selection changed/);
+    } finally {
+      view.destroy();
+      mock.restore();
+    }
+  });
+
+  it("terminates a stalled regex worker and permits a fresh-worker retry", async () => {
+    vi.useFakeTimers();
+    const mock = mockSearchWorkers();
+    const view = new EditorView({
+      state: EditorState.create({ doc: "aaaa!", extensions: [search(), buildPassiveSearchHighlightExtension()] }),
+    });
+    try {
+      view.dispatch({ effects: setSearchQuery.of(new SearchQuery({ search: "(a+)+$", regexp: true })) });
+      requireTestValue(mock.workers[0]).emit({ type: "ready" });
+      await vi.advanceTimersByTimeAsync(SOURCE_SEARCH_TIMEOUT_MS);
+      expect(getCodeMirrorFindReplaceMetrics(view)).toMatchObject({ pending: false, matches: 0 });
+      expect(getCodeMirrorFindReplaceMetrics(view).error).toMatch(/timed out/);
+      expect(requireTestValue(mock.workers[0]).terminate).toHaveBeenCalledOnce();
+      runSourceRegexSearchCommand(view, "next");
+      expect(mock.workers).toHaveLength(2);
+      expect(getCodeMirrorFindReplaceMetrics(view)).toMatchObject({ pending: true, error: undefined });
+    } finally {
+      view.destroy();
+      mock.restore();
+      vi.useRealTimers();
+    }
+  });
+
+  it("discards buffered replacements after a document or query revision changes", async () => {
+    const mock = mockSearchWorkers();
+    const view = new EditorView({
+      state: EditorState.create({ doc: "aa aa", extensions: [search(), buildPassiveSearchHighlightExtension()] }),
+    });
+    try {
+      view.dispatch({ effects: setSearchQuery.of(new SearchQuery({ search: "a+", regexp: true })) });
+      runSourceRegexSearchCommand(view, "replace-all");
+      const staleDocument = mock.workers.at(-1)!;
+      staleDocument.emit({ type: "change", from: 0, to: 2, insert: "wrong", continued: false });
+      view.dispatch({ changes: { from: 0, insert: "new " } });
+      staleDocument.emit({ type: "complete", announcements: [] });
+      expect(view.state.doc.toString()).toBe("new aa aa");
+      runSourceRegexSearchCommand(view, "replace-all");
+      const staleQuery = mock.workers.at(-1)!;
+      staleQuery.emit({ type: "change", from: 4, to: 6, insert: "wrong", continued: false });
+      view.dispatch({ effects: setSearchQuery.of(new SearchQuery({ search: "new", regexp: true })) });
+      staleQuery.emit({ type: "complete", announcements: [] });
+      await Promise.resolve();
+      expect(view.state.doc.toString()).toBe("new aa aa");
+      expect(staleDocument.terminate).toHaveBeenCalledOnce();
+      expect(staleQuery.terminate).toHaveBeenCalledOnce();
+    } finally {
+      view.destroy();
+      mock.restore();
+    }
+  });
+
+  it("passes native language word characters to the regex worker", () => {
+    const mock = mockSearchWorkers();
+    const view = new EditorView({
+      state: EditorState.create({
+        doc: "$alpha alpha",
+        extensions: [search(), buildPassiveSearchHighlightExtension(), EditorState.languageData.of(() => [{ wordChars: "$" }])],
+      }),
+    });
+    try {
+      view.dispatch({ effects: setSearchQuery.of(new SearchQuery({ search: "alpha", regexp: true, wholeWord: true })) });
+      requireTestValue(mock.workers[0]).emit({ type: "ready" });
+      expect(requireTestValue(mock.workers[0]).postMessage).toHaveBeenLastCalledWith(
+        expect.objectContaining({ query: expect.objectContaining({ wordChars: "$" }) })
+      );
+    } finally {
+      view.destroy();
+      mock.restore();
+    }
+  });
+
+  it("does not execute regex cursors on the main thread while worker results are pending", () => {
+    const location = vi.spyOn(window.location, "toString").mockReturnValue("http://localhost:3000/");
+    vi.stubGlobal(
+      "Worker",
+      class {
+        addEventListener() {}
+        terminate() {}
+      }
+    );
+    const view = new EditorView({
+      state: EditorState.create({ doc: "aaaa!", extensions: [search(), buildPassiveSearchHighlightExtension()] }),
+    });
+    const cursor = vi.spyOn(SearchQuery.prototype, "getCursor");
+    try {
+      view.dispatch({ effects: setSearchQuery.of(new SearchQuery({ search: "(a+)+$", regexp: true })) });
+      view.dispatch({ selection: { anchor: 0, head: 4 } });
+      expect(getCodeMirrorFindReplaceMetrics(view)).toMatchObject({ matches: 0, pending: true });
+      expect(cursor).not.toHaveBeenCalled();
+    } finally {
+      cursor.mockRestore();
+      view.destroy();
+      vi.unstubAllGlobals();
+      location.mockRestore();
+    }
+  });
+
+  it("bounds cold decoration cursors to the selection or viewport and reuses warm metrics", () => {
+    const passiveHighlights = buildPassiveSearchHighlightExtension();
+    const view = new EditorView({
+      state: EditorState.create({ doc: "word\n".repeat(6_000), extensions: [search(), passiveHighlights] }),
+    });
+    Object.defineProperty(view, "visibleRanges", { configurable: true, get: () => [{ from: 0, to: 20 }] });
+    const cursor = vi.spyOn(SearchQuery.prototype, "getCursor");
+    const refreshViewport = () => {
+      const plugin = view.plugin(
+        passiveHighlights as ViewPlugin<{
+          update: (update: Pick<ViewUpdate, "view" | "state" | "startState" | "docChanged" | "selectionSet" | "viewportChanged">) => void;
+        }>
+      );
+      if (!plugin) throw new Error("Expected passive search decorations");
+      plugin.update({ view, state: view.state, startState: view.state, docChanged: false, selectionSet: false, viewportChanged: true });
+    };
+    try {
+      view.dispatch({ effects: setSearchQuery.of(new SearchQuery({ search: "word" })) });
+      for (const index of [0, 2_999, 5_999]) view.dispatch({ selection: { anchor: index * 5, head: index * 5 + 4 } });
+      refreshViewport();
+      expect(cursor.mock.calls.length).toBeGreaterThan(0);
+      expect(
+        cursor.mock.calls.every(
+          ([, from, to]) => (from === 0 && to === 20) || [0, 2_999, 5_999].some((index) => from === index * 5 && to === index * 5 + 4)
+        )
+      ).toBe(true);
+      expect(getCodeMirrorFindReplaceMetrics(view).matches).toBe(6_000);
+      cursor.mockClear();
+      for (const index of [0, 2_999, 5_999]) view.dispatch({ selection: { anchor: index * 5, head: index * 5 + 4 } });
+      refreshViewport();
+      expect(cursor.mock.calls.every(([, from, to]) => from === 0 && to === 20)).toBe(true);
+    } finally {
+      cursor.mockRestore();
+      view.destroy();
+    }
+  });
+
+  it("locates a contained active match with logarithmic range access", () => {
+    const ranges = Array.from({ length: 60_000 }, (_, index) => ({ from: index * 5, to: index * 5 + 4 }));
+    let reads = 0;
+    const indexed = new Proxy(ranges, {
+      get(target, property, receiver) {
+        if (typeof property === "string" && /^\d+$/.test(property)) reads += 1;
+        return Reflect.get(target, property, receiver);
+      },
+    });
+    expect(findSelectedCodeMirrorSearchMatch(indexed, { from: 299_990, to: 300_000 })).toBe(59_998);
+    expect(reads).toBeLessThan(20);
+    expect(findSelectedCodeMirrorSearchMatch(ranges, { from: 1, to: 4 })).toBe(-1);
+    expect(findSelectedCodeMirrorSearchMatch([], { from: 0, to: 0 })).toBe(-1);
+  });
+
+  it("reuses counts across selection changes and invalidates them on edits or query changes", () => {
+    const view = new EditorView({ state: EditorState.create({ doc: "word ".repeat(6_000), extensions: [search()] }) });
+    const cursor = vi.spyOn(SearchQuery.prototype, "getCursor");
+    try {
+      view.dispatch({ effects: setSearchQuery.of(new SearchQuery({ search: "word" })) });
+      expect(getCodeMirrorFindReplaceMetrics(view).matches).toBe(6_000);
+      const initialCalls = cursor.mock.calls.length;
+      for (const index of [0, 2_999, 5_999]) {
+        view.dispatch({ selection: { anchor: index * 5, head: index * 5 + 4 } });
+        expect(getCodeMirrorFindReplaceMetrics(view).currentMatch).toBe(index + 1);
+      }
+      expect(cursor).toHaveBeenCalledTimes(initialCalls);
+      view.dispatch({ selection: { anchor: 1, head: 9 } });
+      expect(getCodeMirrorFindReplaceMetrics(view).currentMatch).toBe(2);
+      expect(cursor).toHaveBeenCalledTimes(initialCalls);
+      view.dispatch({ changes: { from: 0, to: 5, insert: "" } });
+      expect(getCodeMirrorFindReplaceMetrics(view).matches).toBe(5_999);
+      expect(cursor.mock.calls.length).toBeGreaterThan(initialCalls);
+      view.dispatch({ effects: setSearchQuery.of(new SearchQuery({ search: "missing" })) });
+      expect(getCodeMirrorFindReplaceMetrics(view).matches).toBe(0);
+    } finally {
+      cursor.mockRestore();
+      view.destroy();
+    }
+  });
+  it("captures source snapshots and rejects capture after cancellation or unmount", async () => {
+    const editorRef = createRef<TextCodeEditorHandle>();
+    const { unmount } = render(
+      <TextCodeEditor
+        ref={editorRef}
+        ariaLabel="Snapshot text"
+        filename="notes.txt"
+        text="latest text"
+        theme={TEST_TEXT_THEME}
+        onChange={() => {}}
+      />
+    );
+    await screen.findByLabelText("Snapshot text");
+    const handle = editorRef.current;
+    if (!handle) throw new Error("Expected a mounted text editor");
+    const snapshot = await handle.captureSnapshot();
+    expect(handle.captureSnapshotSync().serialize()).toBe("latest text");
+    const editor = screen.getByLabelText("Snapshot text");
+    editor.dispatchEvent(new CompositionEvent("compositionstart", { bubbles: true }));
+    expect(() => handle.captureSnapshotSync()).toThrow(/composition/);
+    editor.dispatchEvent(new CompositionEvent("compositionend", { bubbles: true }));
+    expect(snapshot.serialize()).toBe("latest text");
+    const abort = new AbortController();
+    abort.abort();
+    await expect(handle.captureSnapshot(abort.signal)).rejects.toMatchObject({ name: "AbortError" });
+    unmount();
+
+    expect(snapshot.serialize()).toBe("latest text");
+    expect(() => handle.captureSnapshotSync()).toThrow(/disposed/);
+    await expect(handle.captureSnapshot()).rejects.toThrow(/disposed/);
+  });
+
+  it.each(["dark", "custom-alpha"])("preserves editor identity, search and undo across a %s theme change", async (variant) => {
+    const text = "const alpha = 1;\n".repeat(120);
+    const onChange = vi.fn();
+    const props = {
+      ariaLabel: "Theme text",
+      filename: "sample.js",
+      text,
+      theme: TEST_TEXT_THEME,
+      onChange,
+      searchOpen: true,
+      searchText: "alpha",
+    };
+    const { rerender } = render(<TextCodeEditor {...props} />);
+    const editor = await screen.findByLabelText("Theme text");
+    const view = EditorView.findFromDOM(editor);
+    if (!view) throw new Error("Expected a mounted text editor");
+    await act(async () => {
+      view.dispatch({ changes: { from: text.length, insert: "// draft" }, selection: { anchor: 6, head: 11 } });
+    });
+    const doc = view.state.doc;
+    const selection = view.state.selection;
+    const query = getSearchQuery(view.state);
+    const metrics = getCodeMirrorFindReplaceMetrics(view);
+    view.scrollDOM.scrollTop = 240;
+    view.scrollDOM.scrollLeft = 30;
+    onChange.mockClear();
+
+    rerender(
+      <TextCodeEditor
+        {...props}
+        text={doc.toString()}
+        theme={{
+          ...TEST_TEXT_THEME,
+          isDarkMode: true,
+          textColor: "rgb(240, 242, 244)",
+          surfaceBackground: variant === "dark" ? "rgb(24, 26, 28)" : "rgba(24, 26, 28, 0.8)",
+          selectionBackground: "rgba(60, 180, 210, 0.4)",
+        }}
+      />
+    );
+
+    await waitFor(() => expect(view.state.facet(EditorView.darkTheme)).toBe(true));
+    expect(EditorView.findFromDOM(screen.getByLabelText("Theme text"))).toBe(view);
+    expect(view.state.doc).toBe(doc);
+    expect(view.state.selection).toBe(selection);
+    expect(getSearchQuery(view.state)).toBe(query);
+    expect(getCodeMirrorFindReplaceMetrics(view)).toEqual(metrics);
+    expect(view.scrollDOM.scrollTop).toBe(240);
+    expect(view.scrollDOM.scrollLeft).toBe(30);
+    expect(onChange).not.toHaveBeenCalled();
+    await act(async () => {
+      expect(undo(view)).toBe(true);
+    });
+    expect(view.state.doc.toString()).toBe(text);
+  });
+
   it("reconfigures line wrapping without recreating the editor", async () => {
     const { rerender } = render(
       <TextCodeEditor
diff --git a/frontend/src/components/Viewer/__tests__/TextViewer.test.tsx b/frontend/src/components/Viewer/__tests__/TextViewer.test.tsx
index 333ac6cfb..ab4629896 100644
--- a/frontend/src/components/Viewer/__tests__/TextViewer.test.tsx
+++ b/frontend/src/components/Viewer/__tests__/TextViewer.test.tsx
@@ -9,6 +9,7 @@ import i18n from "../../../i18n";
 import { ContentProviderRegistryContext } from "../../../pages/FileBrowser/contentProviders";
 import apiService from "../../../services/api";
 import { authSession } from "../../../services/authSession";
+import { loadDraft, snapshotRegisteredDrafts } from "../../../services/draftRecovery";
 import { createStorageBackedTestContentProviderRegistry, readBlobAsText } from "../../../test/helpers";
 import { SambeeThemeProvider } from "../../../theme";
 import { CODEMIRROR_FIND_HISTORY_STORAGE_KEY, CODEMIRROR_REPLACE_HISTORY_STORAGE_KEY } from "../codeMirrorFindReplaceConstants";
@@ -56,7 +57,9 @@ const { mockSetWordWrapEnabled, mockTextEditorCommands, useTextEditorMaxFileSize
       replaceAllSearchResults: vi.fn(),
       replaceCurrentSearchResult: vi.fn(),
     },
-    useTextEditorMaxFileSizeBytesPreferenceMock: vi.fn(() => [52_428_800, vi.fn()] as const),
+    useTextEditorMaxFileSizeBytesPreferenceMock: vi.fn<
+      typeof import("../../../pages/FileBrowser/preferences").useTextEditorMaxFileSizeBytesPreference
+    >(() => [52_428_800, vi.fn()]),
     useTextEditorWordWrapPreferenceMock: vi.fn(() => [false, mockSetWordWrapEnabled] as const),
   }));
 
@@ -68,11 +71,22 @@ vi.mock("../../../pages/FileBrowser/preferences", () => ({
 vi.mock("../TextCodeEditor", () => {
   const MockTextCodeEditor = forwardRef(function MockTextCodeEditor(props: MockTextCodeEditorProps, ref) {
     const latestTextRef = useRef(props.text);
+    const textareaRef = useRef<HTMLTextAreaElement | null>(null);
 
     latestTextRef.current = props.text;
 
     useImperativeHandle(ref, () => ({
       focus: vi.fn(),
+      captureSnapshotSync: () => {
+        const editor = textareaRef.current;
+        if (!editor) throw new Error("Expected the mounted mock text editor");
+        const content = editor.value;
+        return { revision: 0, serialize: () => content };
+      },
+      captureSnapshot: async () => {
+        const content = latestTextRef.current;
+        return { revision: 0, serialize: () => content };
+      },
       flushPendingEdits: vi.fn().mockResolvedValue(undefined),
       getCanonicalText: () => latestTextRef.current,
       getPrimarySelectionText: () => "",
@@ -87,10 +101,10 @@ vi.mock("../TextCodeEditor", () => {
 
     useEffect(() => {
       props.onSearchStateChange?.({
-        searchText: props.searchText,
+        searchText: props.searchText ?? "",
         searchMatches: props.searchText ? 2 : 0,
         currentMatch: props.searchText ? 1 : 0,
-        isSearchOpen: props.searchOpen,
+        isSearchOpen: props.searchOpen ?? false,
         isSearchable: true,
         isValid: true,
         viewMode: "source",
@@ -99,6 +113,7 @@ vi.mock("../TextCodeEditor", () => {
 
     return (
       <textarea
+        ref={textareaRef}
         aria-label={props.ariaLabel}
         className={props.className}
         readOnly={props.readOnly}
@@ -388,6 +403,41 @@ describe("TextViewer", () => {
     });
   });
 
+  it.each(["newer unsaved revision", "saved revision"])("acknowledges only saved content while the current draft is %s", async (latest) => {
+    vi.spyOn(apiService, "getThemes").mockResolvedValue({ themes: [], site_default_id: "sambee-light" });
+    vi.spyOn(apiService, "getOriginalFileBlob").mockResolvedValue(new Blob(["saved revision"], { type: "text/plain" }));
+    let finishWrite: (() => void) | undefined;
+    vi.mocked(apiService.writeTextWithEditLock).mockImplementationOnce(
+      () =>
+        new Promise<void>((resolve) => {
+          finishWrite = resolve;
+        })
+    );
+    renderViewer();
+    const editor = await enterEditMode();
+    fireEvent.change(editor, { target: { value: "saved revision" } });
+    fireEvent.click(screen.getByRole("button", { name: "Save" }));
+    await waitFor(() => expect(apiService.writeTextWithEditLock).toHaveBeenCalledTimes(1));
+    expect(editor).not.toHaveAttribute("readonly");
+    fireEvent.change(editor, { target: { value: "newer unsaved revision" } });
+    if (latest === "saved revision") fireEvent.change(editor, { target: { value: latest } });
+    if (!finishWrite) throw new Error("Expected a pending file write");
+    await act(async () => {
+      finishWrite?.();
+    });
+
+    expect(editor).toHaveValue(latest);
+    fireEvent.click(screen.getByRole("button", { name: "Close" }));
+    if (latest !== "saved revision") {
+      const dialog = await screen.findByRole("dialog", { name: "Unsaved changes" });
+      fireEvent.click(within(dialog).getByRole("button", { name: "Discard" }));
+    } else {
+      expect(screen.queryByRole("dialog", { name: "Unsaved changes" })).not.toBeInTheDocument();
+    }
+    await waitFor(() => expect(screen.getByRole("textbox", { name: "Text editor" })).toHaveAttribute("readonly"));
+    expect(screen.getByRole("textbox", { name: "Text editor" })).toHaveValue("saved revision");
+  });
+
   it("closes exactly once on Escape from the viewer dialog", async () => {
     const onClose = vi.fn();
     renderViewer({ onClose });
@@ -669,6 +719,29 @@ describe("TextViewer", () => {
     });
   });
 
+  it.each(["pagehide", "registered"])("captures current editor text before React publication on %s", async (trigger) => {
+    vi.spyOn(authSession, "getUserId").mockReturnValue("test-user");
+    renderViewer();
+    const editor = await enterEditMode();
+    fireEvent.change(editor, { target: { value: "older React draft" } });
+    const storage = vi.spyOn(Storage.prototype, "setItem");
+    const draftKey = `sambee_oidc_draft:test-user:conn1:text:${encodeURIComponent("/docs/readme.txt")}`;
+    const valueSetter = Object.getOwnPropertyDescriptor(HTMLTextAreaElement.prototype, "value")?.set;
+    if (!valueSetter) throw new Error("Expected the native textarea value setter");
+    valueSetter.call(editor, "latest editor revision");
+    act(() => {
+      if (trigger === "pagehide") window.dispatchEvent(new Event("pagehide"));
+      else snapshotRegisteredDrafts();
+    });
+    expect(loadDraft("conn1", "/docs/readme.txt", "text")).toMatchObject({ baseline: "hello world", content: "latest editor revision" });
+    await waitFor(() => expect(storage.mock.calls.filter(([key]) => key === draftKey).length).toBeGreaterThanOrEqual(2));
+    expect(
+      storage.mock.calls.filter(([key]) => key === draftKey).every(([, value]) => JSON.parse(value).content === "latest editor revision")
+    ).toBe(true);
+    expect(loadDraft("conn1", "/docs/readme.txt", "text")?.content).toBe("latest editor revision");
+    expect(apiService.writeTextWithEditLock).not.toHaveBeenCalled();
+  });
+
   it("clears the local draft when text returns to its saved baseline", async () => {
     vi.spyOn(authSession, "getUserId").mockReturnValue("test-user");
     renderViewer();
diff --git a/frontend/src/components/Viewer/__tests__/markdownEditorSearch.test.tsx b/frontend/src/components/Viewer/__tests__/markdownEditorSearch.test.tsx
index 3f9847e46..3d420e4c2 100644
--- a/frontend/src/components/Viewer/__tests__/markdownEditorSearch.test.tsx
+++ b/frontend/src/components/Viewer/__tests__/markdownEditorSearch.test.tsx
@@ -293,7 +293,8 @@ describe("codeMirrorFindReplace", () => {
     expect(getRootSearchMetrics(view)).toMatchObject({ isValid: true, matches: 1 });
 
     updateRootSearchQuery(view, { ...DEFAULT_SEARCH_OPTIONS, regexp: true, searchText: "alpha\\d" });
-    expect(getRootSearchMetrics(view)).toMatchObject({ isValid: true, matches: 1 });
+    expect(getRootSearchMetrics(view)).toMatchObject({ isValid: true, matches: 0 });
+    expect(getRootSearchMetrics(view).error).toMatch(/worker/i);
 
     updateRootSearchQuery(view, { ...DEFAULT_SEARCH_OPTIONS, regexp: true, searchText: "(" });
     expect(getRootSearchMetrics(view)).toMatchObject({ isValid: false, matches: 0 });
diff --git a/frontend/src/components/Viewer/__tests__/markdownTableCellLineBreaks.test.tsx b/frontend/src/components/Viewer/__tests__/markdownTableCellLineBreaks.test.tsx
index 201fcb8fb..64b6f6d44 100644
--- a/frontend/src/components/Viewer/__tests__/markdownTableCellLineBreaks.test.tsx
+++ b/frontend/src/components/Viewer/__tests__/markdownTableCellLineBreaks.test.tsx
@@ -47,6 +47,20 @@ describe("markdownTableCellLineBreaks", () => {
     expect(normalizeMarkdownTableCellLineBreaks(normalized)).toBe(normalized);
   });
 
+  it("assembles many table replacements without changing surrounding UTF-16 source", () => {
+    const rowCount = 2400;
+    const prefix = "Before \u{1F642} <BR> stays literal.\n\n| Left | Right |\n| --- | --- |\n";
+    const suffix = "\nAfter `literal<BR>` stays unchanged.\n";
+    const sourceRows = Array.from({ length: rowCount }, (_, index) => `| ${index}<BR>middle&#10;end<br><br> | text |\n`);
+    const expectedRows = Array.from({ length: rowCount }, (_, index) => `| ${index}<br />middle<br />end | text |\n`);
+    const expected = prefix + expectedRows.join("") + suffix;
+
+    expect(normalizeMarkdownTableCellLineBreaks(prefix + sourceRows.join("") + suffix)).toBe(expected);
+    expect(prepareMarkdownTableCellLineBreaksForEditor(expected)).toBe(
+      prefix + expectedRows.join("").replaceAll("<br />", "<br>") + suffix
+    );
+  });
+
   it("canonicalizes list markers while preserving list-like text in fenced code", () => {
     const markdown = [
       "* first",
@@ -89,6 +103,35 @@ describe("markdownTableCellLineBreaks", () => {
     expect(normalizeMarkdownTableCellLineBreaks(markdown)).toBe(["| Value |", "| --- |", "| asterisk (*) and a&b |", ""].join("\n"));
   });
 
+  it("reparses changed escape offsets before normalizing later breaks and list markers", () => {
+    const markdown = [
+      "| Left | Right |",
+      "| --- | --- |",
+      "| a\\&b | foo<BR>bar |",
+      "",
+      "* item",
+      "",
+      "```md",
+      "* literal<BR>",
+      "```",
+      "",
+    ].join("\n");
+    const expected = [
+      "| Left | Right |",
+      "| --- | --- |",
+      "| a&b | foo<br />bar |",
+      "",
+      "- item",
+      "",
+      "```md",
+      "* literal<BR>",
+      "```",
+      "",
+    ].join("\n");
+    expect(normalizeMarkdownTableCellLineBreaks(markdown)).toBe(expected);
+    expect(normalizeMarkdownTableCellLineBreaks(expected)).toBe(expected);
+  });
+
   it("keeps table-cell escapes that preserve Markdown semantics", () => {
     const markdown = ["| Value |", "| --- |", "| \\*literal\\* and \\&copy; |", ""].join("\n");
 
diff --git a/frontend/src/components/Viewer/codeMirrorFindReplace.ts b/frontend/src/components/Viewer/codeMirrorFindReplace.ts
index 2b18c4e3c..b75153418 100644
--- a/frontend/src/components/Viewer/codeMirrorFindReplace.ts
+++ b/frontend/src/components/Viewer/codeMirrorFindReplace.ts
@@ -1,5 +1,46 @@
-import { getSearchQuery, SearchQuery, setSearchQuery } from "@codemirror/search";
-import type { EditorView } from "@codemirror/view";
+import {
+  getSearchQuery,
+  findNext as nativeFindNext,
+  findPrevious as nativeFindPrevious,
+  replaceAll as nativeReplaceAll,
+  replaceNext as nativeReplaceNext,
+  SearchQuery,
+  setSearchQuery,
+} from "@codemirror/search";
+import { EditorView } from "@codemirror/view";
+import { t } from "i18next";
+import { logger } from "../../services/logger";
+import { findSelectedCodeMirrorSearchMatch, getCodeMirrorSearchMatches } from "../Editor/codeMirrorSearchMatches";
+import { getSourceRegexSearch, runSourceRegexSearchCommand } from "../Editor/sourceRegexSearch";
+import {
+  beginSourceReplacementFeedback,
+  isHeavySourceReplacement,
+  isSourceReplacementPending,
+  SOURCE_REPLACEMENT_HEAVY_MATCHES,
+} from "../Editor/sourceReplacementFeedback";
+
+export const findNext = (view: EditorView): boolean => runSourceRegexSearchCommand(view, "next") || nativeFindNext(view);
+export const findPrevious = (view: EditorView): boolean => runSourceRegexSearchCommand(view, "previous") || nativeFindPrevious(view);
+export const replaceNext = (view: EditorView): boolean => runSourceRegexSearchCommand(view, "replace-one") || nativeReplaceNext(view);
+export const replaceAll = (view: EditorView): boolean => {
+  if (isSourceReplacementPending(view)) return true;
+  if (runSourceRegexSearchCommand(view, "replace-all")) return true;
+  const query = getSearchQuery(view.state);
+  if (!query.valid || view.state.readOnly) return nativeReplaceAll(view);
+  const cursor = query.getCursor(view.state);
+  let matches = 0;
+  for (let match = cursor.next(); !match.done && matches < SOURCE_REPLACEMENT_HEAVY_MATCHES; match = cursor.next()) matches += 1;
+  if (!isHeavySourceReplacement(view.state.doc.length, matches, matches * query.replace.length)) return nativeReplaceAll(view);
+  beginSourceReplacementFeedback(view).apply(
+    () => nativeReplaceAll(view),
+    true,
+    (error) => {
+      logger.error("Atomic replacement failed; retry Replace All.", { error });
+      view.dispatch({ effects: EditorView.announce.of(t("viewer.edit.replacementFailed")) });
+    }
+  );
+  return true;
+};
 
 export interface CodeMirrorFindReplaceRequest {
   caseSensitive: boolean;
@@ -10,6 +51,8 @@ export interface CodeMirrorFindReplaceRequest {
 }
 
 export interface CodeMirrorFindReplaceMetrics {
+  pending: boolean;
+  error?: string;
   currentMatch: number;
   isSearchable: boolean;
   isValid: boolean;
@@ -25,50 +68,31 @@ export interface CodeMirrorFindReplaceOptions {
   wholeWord: boolean;
 }
 
-interface SearchMatchRange {
-  from: number;
-  to: number;
-}
-
-function rangeContainedInSelection(range: SearchMatchRange, selection: SearchMatchRange): boolean {
-  return selection.from <= range.from && selection.to >= range.to;
-}
-
 function resolveSearchMatchState(view: EditorView): CodeMirrorFindReplaceMetrics {
   const query = getSearchQuery(view.state);
   const searchText = query.search;
   const isSearchable = view.state.doc.length > 0;
 
   if (!searchText) {
-    return { currentMatch: 0, isSearchable, isValid: true, matches: 0, searchText };
+    return { currentMatch: 0, isSearchable, isValid: true, matches: 0, searchText, pending: false };
   }
 
   if (!query.valid) {
-    return { currentMatch: 0, isSearchable, isValid: false, matches: 0, searchText };
-  }
-
-  const cursor = query.getCursor(view.state);
-  const mainSelection = view.state.selection.main;
-  const mainSelectionRange = { from: mainSelection.from, to: mainSelection.to };
-  let matches = 0;
-  let currentMatch = 0;
-  let containedMatchIndex = 0;
-
-  for (let nextMatch = cursor.next(); !nextMatch.done; nextMatch = cursor.next()) {
-    matches += 1;
-    const match = nextMatch.value;
-
-    if (match.from === mainSelection.from && match.to === mainSelection.to) {
-      currentMatch = matches;
-      continue;
-    }
-
-    if (containedMatchIndex === 0 && rangeContainedInSelection(match, mainSelectionRange)) {
-      containedMatchIndex = matches;
-    }
+    return { currentMatch: 0, isSearchable, isValid: false, matches: 0, searchText, pending: false };
   }
 
-  return { currentMatch: currentMatch || containedMatchIndex, isSearchable, isValid: true, matches, searchText };
+  const ranges = getCodeMirrorSearchMatches(view);
+  const currentMatch = findSelectedCodeMirrorSearchMatch(ranges, view.state.selection.main) + 1;
+  const regex = query.regexp ? getSourceRegexSearch(view) : undefined;
+  return {
+    currentMatch,
+    isSearchable,
+    isValid: true,
+    matches: ranges.length,
+    searchText,
+    pending: isSourceReplacementPending(view) || (regex?.pending ?? false),
+    error: regex?.error,
+  };
 }
 
 export function updateCodeMirrorFindReplaceQuery(view: EditorView | null | undefined, options: CodeMirrorFindReplaceOptions): void {
@@ -92,7 +116,7 @@ export function updateCodeMirrorFindReplaceQuery(view: EditorView | null | undef
 
 export function getCodeMirrorFindReplaceMetrics(view: EditorView | null | undefined): CodeMirrorFindReplaceMetrics {
   if (!view) {
-    return { currentMatch: 0, isSearchable: false, isValid: true, matches: 0, searchText: "" };
+    return { currentMatch: 0, isSearchable: false, isValid: true, matches: 0, searchText: "", pending: false };
   }
 
   return resolveSearchMatchState(view);
diff --git a/frontend/src/components/Viewer/markdownSearchState.ts b/frontend/src/components/Viewer/markdownSearchState.ts
index a1e09deb7..8f9d96109 100644
--- a/frontend/src/components/Viewer/markdownSearchState.ts
+++ b/frontend/src/components/Viewer/markdownSearchState.ts
@@ -11,6 +11,8 @@ export function areMarkdownSearchStatesEqual(
     previousState.isSearchOpen === nextState.isSearchOpen &&
     previousState.isSearchable === nextState.isSearchable &&
     previousState.isValid === nextState.isValid &&
+    previousState.pending === nextState.pending &&
+    previousState.error === nextState.error &&
     previousState.viewMode === nextState.viewMode
   );
 }
diff --git a/frontend/src/components/Viewer/markdownTableCellLineBreaks.ts b/frontend/src/components/Viewer/markdownTableCellLineBreaks.ts
index 0ac3a7c8f..e2b8ee214 100644
--- a/frontend/src/components/Viewer/markdownTableCellLineBreaks.ts
+++ b/frontend/src/components/Viewer/markdownTableCellLineBreaks.ts
@@ -81,13 +81,21 @@ function applyMarkdownReplacements(markdown: string, replacements: MarkdownRepla
     return markdown;
   }
 
-  let nextMarkdown = markdown;
-
-  for (const { startOffset, endOffset, replacement } of [...replacements].sort((left, right) => right.startOffset - left.startOffset)) {
-    nextMarkdown = `${nextMarkdown.slice(0, startOffset)}${replacement}${nextMarkdown.slice(endOffset)}`;
+  const segments: string[] = [];
+  let previousEndOffset = 0;
+
+  for (const { startOffset, endOffset, replacement } of [...replacements].sort((left, right) => left.startOffset - right.startOffset)) {
+    if (startOffset < previousEndOffset || endOffset < startOffset || endOffset > markdown.length) {
+      throw new Error(
+        `Invalid Markdown replacement range ${startOffset}:${endOffset} after ${previousEndOffset} in ${markdown.length} units`
+      );
+    }
+    segments.push(markdown.slice(previousEndOffset, startOffset), replacement);
+    previousEndOffset = endOffset;
   }
 
-  return nextMarkdown;
+  segments.push(markdown.slice(previousEndOffset));
+  return segments.join("");
 }
 
 function setMarkdownReplacement(replacements: Map<string, MarkdownReplacement>, replacement: MarkdownReplacement): void {
@@ -270,8 +278,7 @@ function haveEquivalentMarkdownTables(previousMarkdown: string, nextMarkdown: st
   );
 }
 
-function removeRedundantTableCellEscapes(markdown: string): string {
-  const tree = markdownParser.parse(markdown) as Root;
+function removeRedundantTableCellEscapes(markdown: string, tree: Root): string {
   const escapeOffsetGroups: number[][] = [];
 
   visit(tree, "tableCell", (node) => {
@@ -319,9 +326,10 @@ function removeRedundantTableCellEscapes(markdown: string): string {
   return normalizedMarkdown;
 }
 
-export function normalizeMarkdownTableCellLineBreaks(markdown: string): string {
-  const sourceMarkdown = removeRedundantTableCellEscapes(markdown);
-  const tree = markdownParser.parse(sourceMarkdown) as Root;
+export function normalizeMarkdownTableCellLineBreaks(markdown: string, onPrepared?: (source: string, tree: Root) => void): string {
+  const sourceTree = markdownParser.parse(markdown) as Root;
+  const sourceMarkdown = removeRedundantTableCellEscapes(markdown, sourceTree);
+  const tree = sourceMarkdown === markdown ? sourceTree : (markdownParser.parse(sourceMarkdown) as Root);
   const replacements = new Map<string, MarkdownReplacement>();
 
   visit(tree, "tableCell", (node) => {
@@ -332,7 +340,9 @@ export function normalizeMarkdownTableCellLineBreaks(markdown: string): string {
 
   collectListMarkerReplacements(sourceMarkdown, tree, replacements);
 
-  return applyMarkdownReplacements(sourceMarkdown, [...replacements.values()]);
+  const normalized = applyMarkdownReplacements(sourceMarkdown, [...replacements.values()]);
+  if (onPrepared) onPrepared(normalized, normalized === sourceMarkdown ? tree : (markdownParser.parse(normalized) as Root));
+  return normalized;
 }
 
 export function prepareMarkdownTableCellLineBreaksForEditor(markdown: string): string {
@@ -351,8 +361,12 @@ export function prepareMarkdownTableCellLineBreaksForEditor(markdown: string): s
   return applyMarkdownReplacements(markdown, replacements);
 }
 
+export function needsMarkdownTableSourceComparison(previousMarkdown: string, nextMarkdown: string): boolean {
+  return previousMarkdown !== nextMarkdown && previousMarkdown.includes("|") && nextMarkdown.includes("|");
+}
+
 export function preserveUnchangedMarkdownTableSource(previousMarkdown: string, nextMarkdown: string): string {
-  if (previousMarkdown === nextMarkdown) {
+  if (!needsMarkdownTableSourceComparison(previousMarkdown, nextMarkdown)) {
     return nextMarkdown;
   }
 
diff --git a/frontend/src/components/Viewer/useMarkdownEditSession.ts b/frontend/src/components/Viewer/useMarkdownEditSession.ts
index 32034a396..99b472257 100644
--- a/frontend/src/components/Viewer/useMarkdownEditSession.ts
+++ b/frontend/src/components/Viewer/useMarkdownEditSession.ts
@@ -23,6 +23,7 @@ export interface MarkdownEditSessionController {
   clearPendingBaselineSync: () => void;
   handleEditorChange: (markdown: string) => void;
   handleEditorUserEdit: (viewUpdate?: ViewUpdate) => void;
+  getEditGeneration: () => number;
   hasUserEditedInSession: boolean;
   markEditSessionPristine: () => void;
   requestRestoreEditingFocus: () => void;
@@ -38,6 +39,7 @@ export function useMarkdownEditSession({
   setEditBaselineContent,
 }: UseMarkdownEditSessionOptions): MarkdownEditSessionController {
   const hasUserEditedRef = useRef(false);
+  const editGenerationRef = useRef(0);
   const [hasUserEditedInSession, setHasUserEditedInSession] = useState(false);
   const allowBaselineSyncRef = useRef(false);
   const pendingRestoreEditorFocusRef = useRef(false);
@@ -61,12 +63,15 @@ export function useMarkdownEditSession({
     setHasUserEditedInSession(false);
   }, []);
 
+  const getEditGeneration = useCallback(() => editGenerationRef.current, []);
+
   const requestRestoreEditingFocus = useCallback(() => {
     pendingRestoreEditorFocusRef.current = true;
   }, []);
 
   const handleEditorChange = useCallback(
     (nextMarkdown: string) => {
+      editGenerationRef.current += 1;
       if (isEditing && allowBaselineSyncRef.current && !hasUserEditedRef.current) {
         clearPendingBaselineSync();
         const requestId = pendingBaselineSyncRequestIdRef.current;
@@ -99,6 +104,7 @@ export function useMarkdownEditSession({
       }
 
       clearBaselineSyncWindow();
+      editGenerationRef.current += 1;
       hasUserEditedRef.current = true;
       setHasUserEditedInSession(true);
     },
@@ -176,6 +182,7 @@ export function useMarkdownEditSession({
     clearPendingBaselineSync,
     handleEditorChange,
     handleEditorUserEdit,
+    getEditGeneration,
     hasUserEditedInSession,
     markEditSessionPristine,
     requestRestoreEditingFocus,
diff --git a/frontend/src/components/Viewer/viewerToolbarActions.tsx b/frontend/src/components/Viewer/viewerToolbarActions.tsx
index 1fa903f18..fa332648c 100644
--- a/frontend/src/components/Viewer/viewerToolbarActions.tsx
+++ b/frontend/src/components/Viewer/viewerToolbarActions.tsx
@@ -1,4 +1,4 @@
-import { Edit, Save } from "@mui/icons-material";
+import { Edit, Print, Save } from "@mui/icons-material";
 import { COMMON_SHORTCUTS } from "../../config/keyboardShortcuts";
 import { withShortcut } from "../../hooks/useKeyboardShortcuts";
 import { translate } from "../../i18n";
@@ -72,3 +72,19 @@ export function createSaveToolbarAction({
     title: withShortcut(COMMON_SHORTCUTS.SAVE),
   });
 }
+
+export function createPrintToolbarAction({
+  onClick,
+  isMobile,
+  disabled,
+  id = "print",
+}: CommonViewerToolbarActionOptions): ViewerToolbarAction {
+  return createIconToolbarAction({
+    id,
+    label: translate("common.actions.print"),
+    icon: <Print fontSize={getToolbarIconFontSize(isMobile)} />,
+    onClick,
+    disabled,
+    title: translate("viewer.printTitle"),
+  });
+}
diff --git a/frontend/src/components/__tests__/ErrorBoundary.test.tsx b/frontend/src/components/__tests__/ErrorBoundary.test.tsx
index df4ea38a2..82f5f7c43 100644
--- a/frontend/src/components/__tests__/ErrorBoundary.test.tsx
+++ b/frontend/src/components/__tests__/ErrorBoundary.test.tsx
@@ -3,7 +3,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { setLocale } from "../../i18n";
 import ErrorBoundary from "../ErrorBoundary";
 
-function ThrowingComponent() {
+function ThrowingComponent(): never {
   throw new Error("Boom");
 }
 
diff --git a/frontend/src/components/__tests__/ThemeSelector.test.tsx b/frontend/src/components/__tests__/ThemeSelector.test.tsx
index e9cba68ce..802d016a0 100644
--- a/frontend/src/components/__tests__/ThemeSelector.test.tsx
+++ b/frontend/src/components/__tests__/ThemeSelector.test.tsx
@@ -192,7 +192,7 @@ describe("ThemeSelector Component", () => {
       await user.click(screen.getByText(/Sambee dark/i).closest("button")!);
 
       expect(screen.getByRole("status", { name: "Saving setting" })).toBeInTheDocument();
-      expect(screen.getAllByRole("button").filter((button) => button.closest(".MuiCard-root"))).toSatisfy((cards) =>
+      expect(screen.getAllByRole("button").filter((button) => button.closest(".MuiCard-root"))).toSatisfy((cards: HTMLElement[]) =>
         cards.every((card) => card.hasAttribute("disabled"))
       );
     });
diff --git a/frontend/src/config/__tests__/browserCommands.test.ts b/frontend/src/config/__tests__/browserCommands.test.ts
index 86af51501..7863cced8 100644
--- a/frontend/src/config/__tests__/browserCommands.test.ts
+++ b/frontend/src/config/__tests__/browserCommands.test.ts
@@ -35,6 +35,8 @@ function createContext(): BrowserCommandContext {
     createArchive: () => {},
     extractArchive: () => {},
     openInApp: () => {},
+    openInViewerPicker: () => {},
+    openInNativePicker: () => {},
     toggleDualPane: () => {},
     focusLeftPane: () => {},
     focusRightPane: () => {},
diff --git a/frontend/src/config/browserCommands.ts b/frontend/src/config/browserCommands.ts
index ab87fe56f..54b994510 100644
--- a/frontend/src/config/browserCommands.ts
+++ b/frontend/src/config/browserCommands.ts
@@ -1,3 +1,4 @@
+import type { ParseKeys } from "i18next";
 import type { KeyboardShortcut } from "../hooks/useKeyboardShortcuts";
 import { translate } from "../i18n";
 
@@ -58,9 +59,9 @@ export interface BrowserCommandDefinition {
 
 interface BrowserCommandTemplate {
   id: string;
-  titleKey: string;
-  categoryKey: string;
-  descriptionKey?: string;
+  titleKey: ParseKeys;
+  categoryKey: ParseKeys;
+  descriptionKey?: ParseKeys;
   keywords?: string[];
   defaultShortcutIds?: string[];
   shortcutLabel?: string;
diff --git a/frontend/src/hooks/__tests__/useBackendRecoveryMonitor.test.ts b/frontend/src/hooks/__tests__/useBackendRecoveryMonitor.test.ts
index 1cd8a0ea5..78f0a96c8 100644
--- a/frontend/src/hooks/__tests__/useBackendRecoveryMonitor.test.ts
+++ b/frontend/src/hooks/__tests__/useBackendRecoveryMonitor.test.ts
@@ -2,7 +2,12 @@ import { act, renderHook } from "@testing-library/react";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { setOidcExchangePending } from "../../services/api";
 import { AuthSessionError, authSession } from "../../services/authSession";
-import { getBackendAvailabilitySnapshot, resetBackendAvailabilityForTests } from "../../services/backendAvailability";
+import {
+  type BackendAvailabilityStatus,
+  getBackendAvailabilitySnapshot,
+  resetBackendAvailabilityForTests,
+} from "../../services/backendAvailability";
+import { createMockAuthToken } from "../../test/fixtures/users";
 import { useBackendRecoveryMonitor } from "../useBackendRecoveryMonitor";
 
 async function flushAsyncWork(): Promise<void> {
@@ -33,9 +38,12 @@ describe("useBackendRecoveryMonitor", () => {
 
     vi.stubGlobal("fetch", fetchMock);
 
-    const { rerender } = renderHook(({ status }) => useBackendRecoveryMonitor({ status, onRecovered, onReconnectNow }), {
-      initialProps: { status: "available" as const },
-    });
+    const { rerender } = renderHook<ReturnType<typeof useBackendRecoveryMonitor>, { status: BackendAvailabilityStatus }>(
+      ({ status }: { status: BackendAvailabilityStatus }) => useBackendRecoveryMonitor({ status, onRecovered, onReconnectNow }),
+      {
+        initialProps: { status: "available" as const },
+      }
+    );
 
     rerender({ status: "unavailable" });
 
@@ -60,9 +68,12 @@ describe("useBackendRecoveryMonitor", () => {
 
     vi.stubGlobal("fetch", fetchMock);
 
-    const { rerender } = renderHook(({ status }) => useBackendRecoveryMonitor({ status, onReconnectNow }), {
-      initialProps: { status: "available" as const },
-    });
+    const { rerender } = renderHook<ReturnType<typeof useBackendRecoveryMonitor>, { status: BackendAvailabilityStatus }>(
+      ({ status }: { status: BackendAvailabilityStatus }) => useBackendRecoveryMonitor({ status, onReconnectNow }),
+      {
+        initialProps: { status: "available" as const },
+      }
+    );
 
     rerender({ status: "unavailable" });
 
@@ -83,7 +94,9 @@ describe("useBackendRecoveryMonitor", () => {
 
     vi.stubGlobal("fetch", fetchMock);
 
-    renderHook(() => useBackendRecoveryMonitor({ status: "available" }));
+    renderHook<ReturnType<typeof useBackendRecoveryMonitor>, { status: BackendAvailabilityStatus }>(() =>
+      useBackendRecoveryMonitor({ status: "available" })
+    );
 
     expect(fetchMock).toHaveBeenCalledTimes(0);
 
@@ -100,7 +113,9 @@ describe("useBackendRecoveryMonitor", () => {
 
     vi.stubGlobal("fetch", fetchMock);
 
-    renderHook(() => useBackendRecoveryMonitor({ status: "available" }));
+    renderHook<ReturnType<typeof useBackendRecoveryMonitor>, { status: BackendAvailabilityStatus }>(() =>
+      useBackendRecoveryMonitor({ status: "available" })
+    );
 
     act(() => {
       window.dispatchEvent(new Event("focus"));
@@ -133,7 +148,9 @@ describe("useBackendRecoveryMonitor", () => {
 
     vi.stubGlobal("fetch", fetchMock);
 
-    renderHook(() => useBackendRecoveryMonitor({ status: "available" }));
+    renderHook<ReturnType<typeof useBackendRecoveryMonitor>, { status: BackendAvailabilityStatus }>(() =>
+      useBackendRecoveryMonitor({ status: "available" })
+    );
 
     act(() => {
       window.dispatchEvent(new PageTransitionEvent("pageshow", { persisted: false }));
@@ -148,7 +165,9 @@ describe("useBackendRecoveryMonitor", () => {
 
     vi.stubGlobal("fetch", fetchMock);
 
-    renderHook(() => useBackendRecoveryMonitor({ status: "available" }));
+    renderHook<ReturnType<typeof useBackendRecoveryMonitor>, { status: BackendAvailabilityStatus }>(() =>
+      useBackendRecoveryMonitor({ status: "available" })
+    );
 
     act(() => {
       window.dispatchEvent(new PageTransitionEvent("pageshow", { persisted: true }));
@@ -161,12 +180,15 @@ describe("useBackendRecoveryMonitor", () => {
   it("uses an authenticated recovery probe when an access token is present", async () => {
     const fetchMock = vi.fn<typeof fetch>().mockResolvedValue(new Response(null, { status: 200 }));
 
-    authSession.setAuthenticated({ access_token: "token-123", token_type: "bearer" }, false);
+    authSession.setAuthenticated(createMockAuthToken({ access_token: "token-123", token_type: "bearer" }), false);
     vi.stubGlobal("fetch", fetchMock);
 
-    const { rerender } = renderHook(({ status }) => useBackendRecoveryMonitor({ status }), {
-      initialProps: { status: "available" as const },
-    });
+    const { rerender } = renderHook<ReturnType<typeof useBackendRecoveryMonitor>, { status: BackendAvailabilityStatus }>(
+      ({ status }: { status: BackendAvailabilityStatus }) => useBackendRecoveryMonitor({ status }),
+      {
+        initialProps: { status: "available" as const },
+      }
+    );
 
     rerender({ status: "unavailable" });
 
@@ -188,15 +210,20 @@ describe("useBackendRecoveryMonitor", () => {
       .fn<typeof fetch>()
       .mockResolvedValueOnce(new Response(null, { status: 401 }))
       .mockResolvedValueOnce(new Response(null, { status: 200 }));
-    const refreshMock = vi.spyOn(authSession, "requestRefresh").mockResolvedValue({ access_token: "renewed-token", token_type: "bearer" });
+    const refreshMock = vi
+      .spyOn(authSession, "requestRefresh")
+      .mockResolvedValue(createMockAuthToken({ access_token: "renewed-token", token_type: "bearer" }));
     const onReconnectNow = vi.fn();
 
-    authSession.setAuthenticated({ access_token: "expired-token", token_type: "bearer" }, false);
+    authSession.setAuthenticated(createMockAuthToken({ access_token: "expired-token", token_type: "bearer" }), false);
     vi.stubGlobal("fetch", fetchMock);
 
-    const { rerender } = renderHook(({ status }) => useBackendRecoveryMonitor({ status, onReconnectNow }), {
-      initialProps: { status: "available" as const },
-    });
+    const { rerender } = renderHook<ReturnType<typeof useBackendRecoveryMonitor>, { status: BackendAvailabilityStatus }>(
+      ({ status }: { status: BackendAvailabilityStatus }) => useBackendRecoveryMonitor({ status, onReconnectNow }),
+      {
+        initialProps: { status: "available" as const },
+      }
+    );
 
     rerender({ status: "unavailable" });
     await flushAsyncWork();
@@ -223,16 +250,18 @@ describe("useBackendRecoveryMonitor", () => {
     );
     const refresh = vi.spyOn(authSession, "requestRefresh");
     const onAuthenticationFailure = vi.fn();
-    authSession.setAuthenticated({ access_token: "session-a", token_type: "bearer" }, false);
+    authSession.setAuthenticated(createMockAuthToken({ access_token: "session-a", token_type: "bearer" }), false);
     vi.stubGlobal("fetch", fetchMock);
 
-    renderHook(() => useBackendRecoveryMonitor({ status: "available", onAuthenticationFailure }));
+    renderHook<ReturnType<typeof useBackendRecoveryMonitor>, { status: BackendAvailabilityStatus }>(() =>
+      useBackendRecoveryMonitor({ status: "available", onAuthenticationFailure })
+    );
     act(() => window.dispatchEvent(new Event("focus")));
     expect(fetchMock).toHaveBeenCalledWith(
       expect.any(String),
       expect.objectContaining({ headers: expect.objectContaining({ Authorization: "Bearer session-a" }) })
     );
-    authSession.setAuthenticated({ access_token: "session-b", token_type: "bearer" }, false);
+    authSession.setAuthenticated(createMockAuthToken({ access_token: "session-b", token_type: "bearer" }), false);
     await act(async () => {
       finishProbe(new Response(null, { status: 401 }));
     });
@@ -257,9 +286,11 @@ describe("useBackendRecoveryMonitor", () => {
     );
     const refresh = vi.spyOn(authSession, "requestRefresh");
     const onAuthenticationFailure = vi.fn();
-    authSession.setAuthenticated({ access_token: "session-a", token_type: "bearer" }, false);
+    authSession.setAuthenticated(createMockAuthToken({ access_token: "session-a", token_type: "bearer" }), false);
     setOidcExchangePending(true);
-    renderHook(() => useBackendRecoveryMonitor({ status: "available", onAuthenticationFailure }));
+    renderHook<ReturnType<typeof useBackendRecoveryMonitor>, { status: BackendAvailabilityStatus }>(() =>
+      useBackendRecoveryMonitor({ status: "available", onAuthenticationFailure })
+    );
     act(() => window.dispatchEvent(new Event("focus")));
     setOidcExchangePending(false);
     await act(async () => {
@@ -281,13 +312,15 @@ describe("useBackendRecoveryMonitor", () => {
       })
     );
     const onAuthenticationFailure = vi.fn();
-    authSession.setAuthenticated({ access_token: "session-a", token_type: "bearer" }, false);
+    authSession.setAuthenticated(createMockAuthToken({ access_token: "session-a", token_type: "bearer" }), false);
     vi.stubGlobal("fetch", vi.fn<typeof fetch>().mockResolvedValue(new Response(null, { status: 401 })));
-    renderHook(() => useBackendRecoveryMonitor({ status: "available", onAuthenticationFailure }));
+    renderHook<ReturnType<typeof useBackendRecoveryMonitor>, { status: BackendAvailabilityStatus }>(() =>
+      useBackendRecoveryMonitor({ status: "available", onAuthenticationFailure })
+    );
     act(() => window.dispatchEvent(new Event("focus")));
     await flushAsyncWork();
     expect(refresh).toHaveBeenCalledTimes(1);
-    authSession.setAuthenticated({ access_token: "session-b", token_type: "bearer" }, false);
+    authSession.setAuthenticated(createMockAuthToken({ access_token: "session-b", token_type: "bearer" }), false);
     await act(async () => {
       failRefresh(new AuthSessionError("reauthentication-required", "A expired"));
     });
@@ -304,14 +337,21 @@ describe("useBackendRecoveryMonitor", () => {
 
     vi.spyOn(authSession, "requestRefresh").mockRejectedValue(new AuthSessionError("refresh-uncertain", "Refresh result is uncertain."));
     authSession.setAuthenticated(
-      { access_token: "still-usable-token", token_type: "bearer", access_token_expires_at: new Date(Date.now() + 60_000).toISOString() },
+      createMockAuthToken({
+        access_token: "still-usable-token",
+        token_type: "bearer",
+        access_token_expires_at: new Date(Date.now() + 60_000).toISOString(),
+      }),
       true
     );
     vi.stubGlobal("fetch", fetchMock);
 
-    const { rerender } = renderHook(({ status }) => useBackendRecoveryMonitor({ status, onAuthenticationFailure }), {
-      initialProps: { status: "available" as const },
-    });
+    const { rerender } = renderHook<ReturnType<typeof useBackendRecoveryMonitor>, { status: BackendAvailabilityStatus }>(
+      ({ status }: { status: BackendAvailabilityStatus }) => useBackendRecoveryMonitor({ status, onAuthenticationFailure }),
+      {
+        initialProps: { status: "available" as const },
+      }
+    );
 
     rerender({ status: "unavailable" });
     await flushAsyncWork();
@@ -332,12 +372,15 @@ describe("useBackendRecoveryMonitor", () => {
     const onAuthenticationFailure = vi.fn();
 
     vi.spyOn(authSession, "requestRefresh").mockRejectedValue(new AuthSessionError("reauthentication-required", "Sign-in required."));
-    authSession.setAuthenticated({ access_token: "expired-token", token_type: "bearer" }, false);
+    authSession.setAuthenticated(createMockAuthToken({ access_token: "expired-token", token_type: "bearer" }), false);
     vi.stubGlobal("fetch", fetchMock);
 
-    const { rerender } = renderHook(({ status }) => useBackendRecoveryMonitor({ status, onAuthenticationFailure }), {
-      initialProps: { status: "available" as const },
-    });
+    const { rerender } = renderHook<ReturnType<typeof useBackendRecoveryMonitor>, { status: BackendAvailabilityStatus }>(
+      ({ status }: { status: BackendAvailabilityStatus }) => useBackendRecoveryMonitor({ status, onAuthenticationFailure }),
+      {
+        initialProps: { status: "available" as const },
+      }
+    );
 
     rerender({ status: "unavailable" });
     await flushAsyncWork();
@@ -351,9 +394,12 @@ describe("useBackendRecoveryMonitor", () => {
 
     vi.stubGlobal("fetch", fetchMock);
 
-    const { rerender } = renderHook(({ status }) => useBackendRecoveryMonitor({ status }), {
-      initialProps: { status: "available" as const },
-    });
+    const { rerender } = renderHook<ReturnType<typeof useBackendRecoveryMonitor>, { status: BackendAvailabilityStatus }>(
+      ({ status }: { status: BackendAvailabilityStatus }) => useBackendRecoveryMonitor({ status }),
+      {
+        initialProps: { status: "available" as const },
+      }
+    );
 
     rerender({ status: "reconnecting" });
 
diff --git a/frontend/src/hooks/__tests__/useCachedImageGallery.test.tsx b/frontend/src/hooks/__tests__/useCachedImageGallery.test.tsx
index df5c6f1ba..c7ab48217 100644
--- a/frontend/src/hooks/__tests__/useCachedImageGallery.test.tsx
+++ b/frontend/src/hooks/__tests__/useCachedImageGallery.test.tsx
@@ -1,9 +1,9 @@
 import { act, renderHook, waitFor } from "@testing-library/react";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-
 import apiService from "../../services/api";
 import { logger } from "../../services/logger";
 import { PreviewUnavailableError } from "../../services/previewPolicy";
+import { uninitializedTestCallback } from "../../test/helpers/assertions";
 import { IMAGE_LOAD_CANCELED_MESSAGE, IMAGE_LOAD_FAILED_MESSAGE, useCachedImageGallery } from "../useCachedImageGallery";
 
 vi.mock("../../services/api", () => ({
@@ -406,7 +406,7 @@ describe("useCachedImageGallery", () => {
 
   it("retries an in-flight preload once after it is promoted to the current image", async () => {
     const requestedPaths: string[] = [];
-    let rejectFirstPreloadAttempt: ((error: unknown) => void) | null = null;
+    let rejectFirstPreloadAttempt: (error: unknown) => void = uninitializedTestCallback;
     let preloadAttempts = 0;
 
     vi.mocked(apiService.getImageBlob).mockImplementation((_connectionId: string, path: string, options?: { signal?: AbortSignal }) => {
@@ -534,7 +534,7 @@ describe("useCachedImageGallery", () => {
 
   it("does not retry a request after it is demoted from current to overlap", async () => {
     const requestedPaths: string[] = [];
-    let rejectCurrentAttempt: ((error: unknown) => void) | null = null;
+    let rejectCurrentAttempt: (error: unknown) => void = uninitializedTestCallback;
     let firstPathAttempts = 0;
 
     vi.mocked(apiService.getImageBlob).mockImplementation((_connectionId: string, path: string, _options?: { signal?: AbortSignal }) => {
@@ -712,7 +712,7 @@ describe("useCachedImageGallery", () => {
 
   it("does not relaunch a request that fails after being demoted from current to overlap", async () => {
     const requestedPaths: string[] = [];
-    let rejectDemotedAttempt: ((error: unknown) => void) | null = null;
+    let rejectDemotedAttempt: (error: unknown) => void = uninitializedTestCallback;
 
     vi.mocked(apiService.getImageBlob).mockImplementation((_connectionId: string, path: string) => {
       requestedPaths.push(path);
@@ -795,7 +795,7 @@ describe("useCachedImageGallery", () => {
     });
 
     const { rerender } = renderHook(
-      ({ connectionId, images }) =>
+      ({ connectionId, images }: { connectionId: string; images: string[] }) =>
         useCachedImageGallery({
           connectionId,
           loadImageBlob: loadMockImageBlob,
@@ -806,7 +806,6 @@ describe("useCachedImageGallery", () => {
       {
         initialProps: {
           connectionId: "conn-1",
-          loadImageBlob: (path, options) => apiService.getImageBlob("conn-1", path, options),
           images: ["/a0.jpg", "/shared.jpg", "/a2.jpg"],
         },
       }
@@ -818,7 +817,6 @@ describe("useCachedImageGallery", () => {
 
     rerender({
       connectionId: "conn-1",
-      loadImageBlob: (path, options) => apiService.getImageBlob("conn-1", path, options),
       images: ["/b0.jpg", "/shared.jpg", "/b2.jpg"],
     });
 
@@ -1182,7 +1180,7 @@ describe("useCachedImageGallery", () => {
   });
 
   it("does not let a previous gallery request populate the new gallery cache when it resolves late", async () => {
-    let resolveOldGalleryCurrent: ((blob: Blob) => void) | null = null;
+    let resolveOldGalleryCurrent: (blob: Blob) => void = uninitializedTestCallback;
     const requestedPaths: string[] = [];
 
     vi.mocked(apiService.getImageBlob).mockImplementation((_connectionId: string, path: string) => {
diff --git a/frontend/src/hooks/__tests__/useKeyboardShortcuts.test.ts b/frontend/src/hooks/__tests__/useKeyboardShortcuts.test.ts
index 8ce06712f..189b37e66 100644
--- a/frontend/src/hooks/__tests__/useKeyboardShortcuts.test.ts
+++ b/frontend/src/hooks/__tests__/useKeyboardShortcuts.test.ts
@@ -1,5 +1,6 @@
 import { renderHook } from "@testing-library/react";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { requireTestValue } from "../../test/helpers/assertions";
 import type { KeyboardShortcut } from "../useKeyboardShortcuts";
 import { formatShortcut, useKeyboardShortcuts, withShortcut } from "../useKeyboardShortcuts";
 
@@ -46,9 +47,9 @@ describe("useKeyboardShortcuts", () => {
     it("keeps icon activation local while allowing file-list navigation", () => {
       const list = document.createElement("div");
       list.tabIndex = 0;
-      list.dataset.testid = "file-list-container";
+      list.dataset["testid"] = "file-list-container";
       const icon = document.createElement("button");
-      icon.dataset.fileSelectionIcon = "true";
+      icon.dataset["fileSelectionIcon"] = "true";
       list.appendChild(icon);
       document.body.appendChild(list);
       const shortcuts: KeyboardShortcut[] = [
@@ -116,10 +117,10 @@ describe("useKeyboardShortcuts", () => {
       ];
 
       renderHook(() => useKeyboardShortcuts({ shortcuts }));
-      const _event = simulateKeyPress("a");
+      simulateKeyPress("a");
 
       expect(mockHandler).toHaveBeenCalledWith(expect.any(KeyboardEvent));
-      expect((mockHandler as ReturnType<typeof vi.fn>).mock.calls[0][0].key).toBe("a");
+      expect(requireTestValue((mockHandler as ReturnType<typeof vi.fn>).mock.calls[0])[0].key).toBe("a");
     });
 
     it("should not trigger handler when disabled", () => {
diff --git a/frontend/src/hooks/__tests__/useSystemSettingPersistence.test.tsx b/frontend/src/hooks/__tests__/useSystemSettingPersistence.test.tsx
index a27c51e69..a617765ab 100644
--- a/frontend/src/hooks/__tests__/useSystemSettingPersistence.test.tsx
+++ b/frontend/src/hooks/__tests__/useSystemSettingPersistence.test.tsx
@@ -64,7 +64,7 @@ describe("useSystemSettingPersistence", () => {
       await expect(outcome!).resolves.toMatchObject({ status: "failed" });
       expect(requestSignal?.aborted).toBe(true);
       expect(result.current.isPending("limit")).toBe(false);
-      expect(result.current.fieldErrors.limit).toBe("Saving this setting timed out. Check the connection and try again.");
+      expect(result.current.fieldErrors["limit"]).toBe("Saving this setting timed out. Check the connection and try again.");
     } finally {
       vi.useRealTimers();
     }
diff --git a/frontend/src/hooks/useBackendRecoveryMonitor.ts b/frontend/src/hooks/useBackendRecoveryMonitor.ts
index 4900cfa79..de41eee16 100644
--- a/frontend/src/hooks/useBackendRecoveryMonitor.ts
+++ b/frontend/src/hooks/useBackendRecoveryMonitor.ts
@@ -30,7 +30,7 @@ interface BackendRecoveryMonitorOptions {
 
 function getRecoveryDelay(failures: number): number {
   const index = Math.min(failures, RECOVERY_RETRY_DELAYS_MS.length - 1);
-  return RECOVERY_RETRY_DELAYS_MS[index];
+  return RECOVERY_RETRY_DELAYS_MS[index] ?? RECOVERY_RETRY_DELAYS_MS[0];
 }
 
 interface RecoveryProbeRequest {
@@ -123,7 +123,7 @@ export function useBackendRecoveryMonitor({
       const isSuperseded = () => {
         const currentToken = authSession.getAccessToken();
         return Boolean(
-          probeRequest.headers.Authorization && currentToken && probeRequest.headers.Authorization !== `Bearer ${currentToken}`
+          probeRequest.headers["Authorization"] && currentToken && probeRequest.headers["Authorization"] !== `Bearer ${currentToken}`
         );
       };
 
@@ -137,7 +137,7 @@ export function useBackendRecoveryMonitor({
         if (isSuperseded()) return;
         if (response.status === 401 && (exchangePendingAtDispatch || isOidcExchangePending())) return;
 
-        if (response.status === 401 && probeRequest.headers.Authorization) {
+        if (response.status === 401 && probeRequest.headers["Authorization"]) {
           markBackendAvailable();
           await authSession.requestRefresh();
           if (isSuperseded()) return;
diff --git a/frontend/src/hooks/useCachedImageGallery.ts b/frontend/src/hooks/useCachedImageGallery.ts
index 24dd818c3..82e502877 100644
--- a/frontend/src/hooks/useCachedImageGallery.ts
+++ b/frontend/src/hooks/useCachedImageGallery.ts
@@ -197,6 +197,8 @@ function getImageLoadErrorMessage(err: unknown): string {
   if (
     typeof detail === "object" &&
     detail !== null &&
+    "code" in detail &&
+    "message" in detail &&
     detail.code === IMAGE_PREVIEW_TOO_LARGE_ERROR_CODE &&
     typeof detail.message === "string" &&
     detail.message.trim()
@@ -360,7 +362,7 @@ export const useCachedImageGallery = ({
   // Cache of blob URLs for loaded images, keyed by index
   const imageCacheRef = useRef<Map<number, string>>(committedSessionResources.imageCache);
   // Timer for delayed spinner display
-  const loadingTimerRef = useRef<NodeJS.Timeout | null>(null);
+  const loadingTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const isMountedRef = useRef(true);
   const failedBackgroundRequestKeysRef = useRef<Set<string>>(committedSessionResources.failedBackgroundRequestKeys);
   // Track in-flight requests by image index so a preload can be promoted to the
diff --git a/frontend/src/hooks/useSelectableListbox.ts b/frontend/src/hooks/useSelectableListbox.ts
index 9cef8407c..af5d3de5a 100644
--- a/frontend/src/hooks/useSelectableListbox.ts
+++ b/frontend/src/hooks/useSelectableListbox.ts
@@ -69,28 +69,32 @@ export function useSelectableListbox<T extends string>({
         0,
         options.findIndex((option) => option.value === selectedValue)
       );
+      const selectIndex = (index: number) => {
+        const option = options[index];
+        if (option) onSelectValue(option.value);
+      };
 
       switch (event.key) {
         case "ArrowDown": {
           event.preventDefault();
           const nextIndex = Math.min(currentIndex + 1, options.length - 1);
-          onSelectValue(options[nextIndex].value);
+          selectIndex(nextIndex);
           break;
         }
         case "ArrowUp": {
           event.preventDefault();
           const nextIndex = Math.max(currentIndex - 1, 0);
-          onSelectValue(options[nextIndex].value);
+          selectIndex(nextIndex);
           break;
         }
         case "Home": {
           event.preventDefault();
-          onSelectValue(options[0].value);
+          selectIndex(0);
           break;
         }
         case "End": {
           event.preventDefault();
-          onSelectValue(options[options.length - 1].value);
+          selectIndex(options.length - 1);
           break;
         }
         case "Enter":
diff --git a/frontend/src/i18n/resources.ts b/frontend/src/i18n/resources.ts
index bd6aa59a0..ab9e31362 100644
--- a/frontend/src/i18n/resources.ts
+++ b/frontend/src/i18n/resources.ts
@@ -15,6 +15,7 @@ export const EN_TRANSLATIONS = {
       edit: "Edit",
       logout: "Logout",
       move: "Move",
+      print: "Print",
       rename: "Rename",
       replace: "Replace",
       retry: "Retry",
@@ -1282,6 +1283,10 @@ export const EN_TRANSLATIONS = {
     },
   },
   viewer: {
+    renderingFailed: "Unable to finish rendering this document. Close and reopen the file to retry.",
+    renderingPrintPending: "The document is still loading. Close the print dialog and try again when loading finishes.",
+    printTitle: "Print / Save as PDF",
+    printError: "The print dialog couldn't open. Try Print from your browser menu.",
     helpTitles: {
       pdf: "PDF viewer shortcuts",
       image: "Image viewer shortcuts",
@@ -1360,6 +1365,8 @@ export const EN_TRANSLATIONS = {
       regularExpression: "Use regular expression",
       regularExpressionShortcut: "Use regular expression (Alt+R)",
       replaceAll: "Replace all",
+      replacing: "Replacing matches...",
+      replacementFailed: "Replacement failed. Try Replace All again.",
       replaceCurrent: "Replace current match",
       wholeWord: "Match whole word",
       wholeWordShortcut: "Match whole word (Alt+W)",
@@ -1379,6 +1386,7 @@ export const EN_TRANSLATIONS = {
       redo: "Redo",
     },
     text: {
+      loadFailed: "Failed to load file.",
       lockFailed: "Unable to enter text edit mode. {{message}}",
       lockFailedReason: "Failed to acquire edit lock.",
       saveFailed: "Failed to save text file changes.",
diff --git a/frontend/src/pages/AdvancedSettings.tsx b/frontend/src/pages/AdvancedSettings.tsx
index fc0601af7..cc2cbff50 100644
--- a/frontend/src/pages/AdvancedSettings.tsx
+++ b/frontend/src/pages/AdvancedSettings.tsx
@@ -74,8 +74,8 @@ function getByteUnitFactor(unitLabel: ByteUnitLabel): number {
 function createFormState(settings: AdvancedSystemSettings): AdvancedSettingsFormState {
   return {
     temporaryArchiveDownloadSizeBytes: settings.temporary_archive_download_size_bytes?.value ?? null,
-    imagemagickMaxFileSizeBytes: settings.preprocessors.imagemagick.max_file_size_bytes.value,
-    imagemagickTimeoutSeconds: settings.preprocessors.imagemagick.timeout_seconds.value,
+    imagemagickMaxFileSizeBytes: settings.preprocessors["imagemagick"]?.max_file_size_bytes.value ?? null,
+    imagemagickTimeoutSeconds: settings.preprocessors["imagemagick"]?.timeout_seconds.value ?? null,
     pdfCacheQuotaBytes: settings.pdf?.cache_quota_bytes.value ?? null,
     pdfCacheInactivityTtlSeconds: settings.pdf?.cache_inactivity_ttl_seconds.value ?? null,
     pdfMaxSourceSizeBytes: settings.pdf?.max_source_size_bytes.value ?? null,
@@ -373,7 +373,7 @@ function applyIntegerSettingUpdate(setting: IntegerSystemSetting, update: Advanc
 
 function applyAdvancedSettingUpdate(settings: AdvancedSystemSettings, update: AdvancedSystemSettingsUpdate): AdvancedSystemSettings {
   const updateSetting = (setting: IntegerSystemSetting) => applyIntegerSettingUpdate(setting, update);
-  const imagemagick = settings.preprocessors.imagemagick;
+  const imagemagick = settings.preprocessors["imagemagick"];
   return {
     ...settings,
     temporary_archive_download_size_bytes: settings.temporary_archive_download_size_bytes
@@ -381,10 +381,14 @@ function applyAdvancedSettingUpdate(settings: AdvancedSystemSettings, update: Ad
       : undefined,
     preprocessors: {
       ...settings.preprocessors,
-      imagemagick: {
-        max_file_size_bytes: updateSetting(imagemagick.max_file_size_bytes),
-        timeout_seconds: updateSetting(imagemagick.timeout_seconds),
-      },
+      ...(imagemagick
+        ? {
+            imagemagick: {
+              max_file_size_bytes: updateSetting(imagemagick.max_file_size_bytes),
+              timeout_seconds: updateSetting(imagemagick.timeout_seconds),
+            },
+          }
+        : {}),
     },
     ...(settings.pdf
       ? {
@@ -469,6 +473,9 @@ export function AdvancedSettings({ dialogSafeHeader = false }: AdvancedSettingsP
     void refresh(true);
   };
 
+  const imagemagick = settings?.preprocessors["imagemagick"];
+  const pdf = settings?.pdf;
+
   return (
     <SettingsPage
       category="admin-system"
@@ -507,102 +514,100 @@ export function AdvancedSettings({ dialogSafeHeader = false }: AdvancedSettingsP
           )}
           <SettingsGroup title={t("settings.advanced.sections.preprocessors")}>
             <Stack spacing={3.5}>
-              <SettingsGroup title={t("settings.advanced.sections.imageMagick")} level="subsection">
-                <ByteSizeSettingField
-                  setting={settings.preprocessors.imagemagick.max_file_size_bytes}
-                  value={formState.imagemagickMaxFileSizeBytes}
-                  onChange={(value) =>
-                    updateFormField("imagemagickMaxFileSizeBytes", value, settings.preprocessors.imagemagick.max_file_size_bytes)
-                  }
-                  {...getFieldPersistenceProps(settings.preprocessors.imagemagick.max_file_size_bytes)}
-                />
-                <SettingField
-                  setting={settings.preprocessors.imagemagick.timeout_seconds}
-                  value={formState.imagemagickTimeoutSeconds}
-                  onChange={(value) =>
-                    updateFormField("imagemagickTimeoutSeconds", value, settings.preprocessors.imagemagick.timeout_seconds)
-                  }
-                  unitAdornment={t("settings.advanced.fields.seconds")}
-                  {...getFieldPersistenceProps(settings.preprocessors.imagemagick.timeout_seconds)}
-                />
-              </SettingsGroup>
-              {settings.pdf && (
+              {imagemagick && (
+                <SettingsGroup title={t("settings.advanced.sections.imageMagick")} level="subsection">
+                  <ByteSizeSettingField
+                    setting={imagemagick.max_file_size_bytes}
+                    value={formState.imagemagickMaxFileSizeBytes}
+                    onChange={(value) => updateFormField("imagemagickMaxFileSizeBytes", value, imagemagick.max_file_size_bytes)}
+                    {...getFieldPersistenceProps(imagemagick.max_file_size_bytes)}
+                  />
+                  <SettingField
+                    setting={imagemagick.timeout_seconds}
+                    value={formState.imagemagickTimeoutSeconds}
+                    onChange={(value) => updateFormField("imagemagickTimeoutSeconds", value, imagemagick.timeout_seconds)}
+                    unitAdornment={t("settings.advanced.fields.seconds")}
+                    {...getFieldPersistenceProps(imagemagick.timeout_seconds)}
+                  />
+                </SettingsGroup>
+              )}
+              {pdf && (
                 <SettingsGroup title={t("settings.advanced.sections.pdfCompatibility")} level="subsection">
                   <ByteSizeSettingField
-                    setting={settings.pdf.cache_quota_bytes}
+                    setting={pdf.cache_quota_bytes}
                     value={formState.pdfCacheQuotaBytes}
-                    onChange={(value) => updateFormField("pdfCacheQuotaBytes", value, settings.pdf.cache_quota_bytes)}
-                    {...getFieldPersistenceProps(settings.pdf.cache_quota_bytes)}
+                    onChange={(value) => updateFormField("pdfCacheQuotaBytes", value, pdf.cache_quota_bytes)}
+                    {...getFieldPersistenceProps(pdf.cache_quota_bytes)}
                   />
                   <SettingField
-                    setting={settings.pdf.cache_inactivity_ttl_seconds}
+                    setting={pdf.cache_inactivity_ttl_seconds}
                     value={formState.pdfCacheInactivityTtlSeconds}
-                    onChange={(value) => updateFormField("pdfCacheInactivityTtlSeconds", value, settings.pdf.cache_inactivity_ttl_seconds)}
+                    onChange={(value) => updateFormField("pdfCacheInactivityTtlSeconds", value, pdf.cache_inactivity_ttl_seconds)}
                     unitAdornment={t("settings.advanced.fields.seconds")}
-                    {...getFieldPersistenceProps(settings.pdf.cache_inactivity_ttl_seconds)}
+                    {...getFieldPersistenceProps(pdf.cache_inactivity_ttl_seconds)}
                   />
                   <ByteSizeSettingField
-                    setting={settings.pdf.max_source_size_bytes}
+                    setting={pdf.max_source_size_bytes}
                     value={formState.pdfMaxSourceSizeBytes}
-                    onChange={(value) => updateFormField("pdfMaxSourceSizeBytes", value, settings.pdf.max_source_size_bytes)}
-                    {...getFieldPersistenceProps(settings.pdf.max_source_size_bytes)}
+                    onChange={(value) => updateFormField("pdfMaxSourceSizeBytes", value, pdf.max_source_size_bytes)}
+                    {...getFieldPersistenceProps(pdf.max_source_size_bytes)}
                   />
                   <ByteSizeSettingField
-                    setting={settings.pdf.max_output_size_bytes}
+                    setting={pdf.max_output_size_bytes}
                     value={formState.pdfMaxOutputSizeBytes}
-                    onChange={(value) => updateFormField("pdfMaxOutputSizeBytes", value, settings.pdf.max_output_size_bytes)}
-                    {...getFieldPersistenceProps(settings.pdf.max_output_size_bytes)}
+                    onChange={(value) => updateFormField("pdfMaxOutputSizeBytes", value, pdf.max_output_size_bytes)}
+                    {...getFieldPersistenceProps(pdf.max_output_size_bytes)}
                   />
                   <ByteSizeSettingField
-                    setting={settings.pdf.address_space_bytes}
+                    setting={pdf.address_space_bytes}
                     value={formState.pdfAddressSpaceBytes}
-                    onChange={(value) => updateFormField("pdfAddressSpaceBytes", value, settings.pdf.address_space_bytes)}
-                    {...getFieldPersistenceProps(settings.pdf.address_space_bytes)}
+                    onChange={(value) => updateFormField("pdfAddressSpaceBytes", value, pdf.address_space_bytes)}
+                    {...getFieldPersistenceProps(pdf.address_space_bytes)}
                   />
                   <ByteSizeSettingField
-                    setting={settings.pdf.temporary_disk_bytes}
+                    setting={pdf.temporary_disk_bytes}
                     value={formState.pdfTemporaryDiskBytes}
-                    onChange={(value) => updateFormField("pdfTemporaryDiskBytes", value, settings.pdf.temporary_disk_bytes)}
-                    {...getFieldPersistenceProps(settings.pdf.temporary_disk_bytes)}
+                    onChange={(value) => updateFormField("pdfTemporaryDiskBytes", value, pdf.temporary_disk_bytes)}
+                    {...getFieldPersistenceProps(pdf.temporary_disk_bytes)}
                   />
                   <SettingField
-                    setting={settings.pdf.timeout_seconds}
+                    setting={pdf.timeout_seconds}
                     value={formState.pdfTimeoutSeconds}
-                    onChange={(value) => updateFormField("pdfTimeoutSeconds", value, settings.pdf.timeout_seconds)}
+                    onChange={(value) => updateFormField("pdfTimeoutSeconds", value, pdf.timeout_seconds)}
                     unitAdornment={t("settings.advanced.fields.seconds")}
-                    {...getFieldPersistenceProps(settings.pdf.timeout_seconds)}
+                    {...getFieldPersistenceProps(pdf.timeout_seconds)}
                   />
                   <SettingField
-                    setting={settings.pdf.cpu_time_seconds}
+                    setting={pdf.cpu_time_seconds}
                     value={formState.pdfCpuTimeSeconds}
-                    onChange={(value) => updateFormField("pdfCpuTimeSeconds", value, settings.pdf.cpu_time_seconds)}
+                    onChange={(value) => updateFormField("pdfCpuTimeSeconds", value, pdf.cpu_time_seconds)}
                     unitAdornment={t("settings.advanced.fields.seconds")}
-                    {...getFieldPersistenceProps(settings.pdf.cpu_time_seconds)}
+                    {...getFieldPersistenceProps(pdf.cpu_time_seconds)}
                   />
                   <SettingField
-                    setting={settings.pdf.max_concurrent}
+                    setting={pdf.max_concurrent}
                     value={formState.pdfMaxConcurrent}
-                    onChange={(value) => updateFormField("pdfMaxConcurrent", value, settings.pdf.max_concurrent)}
-                    {...getFieldPersistenceProps(settings.pdf.max_concurrent)}
+                    onChange={(value) => updateFormField("pdfMaxConcurrent", value, pdf.max_concurrent)}
+                    {...getFieldPersistenceProps(pdf.max_concurrent)}
                   />
                   <SettingField
-                    setting={settings.pdf.queue_wait_seconds}
+                    setting={pdf.queue_wait_seconds}
                     value={formState.pdfQueueWaitSeconds}
-                    onChange={(value) => updateFormField("pdfQueueWaitSeconds", value, settings.pdf.queue_wait_seconds)}
+                    onChange={(value) => updateFormField("pdfQueueWaitSeconds", value, pdf.queue_wait_seconds)}
                     unitAdornment={t("settings.advanced.fields.seconds")}
-                    {...getFieldPersistenceProps(settings.pdf.queue_wait_seconds)}
+                    {...getFieldPersistenceProps(pdf.queue_wait_seconds)}
                   />
                   <SettingField
-                    setting={settings.pdf.screen_derivative_enabled}
+                    setting={pdf.screen_derivative_enabled}
                     value={formState.pdfScreenDerivativeEnabled}
-                    onChange={(value) => updateFormField("pdfScreenDerivativeEnabled", value, settings.pdf.screen_derivative_enabled)}
-                    {...getFieldPersistenceProps(settings.pdf.screen_derivative_enabled)}
+                    onChange={(value) => updateFormField("pdfScreenDerivativeEnabled", value, pdf.screen_derivative_enabled)}
+                    {...getFieldPersistenceProps(pdf.screen_derivative_enabled)}
                   />
                   <SettingField
-                    setting={settings.pdf.screen_max_decoded_pixels}
+                    setting={pdf.screen_max_decoded_pixels}
                     value={formState.pdfScreenMaxDecodedPixels}
-                    onChange={(value) => updateFormField("pdfScreenMaxDecodedPixels", value, settings.pdf.screen_max_decoded_pixels)}
-                    {...getFieldPersistenceProps(settings.pdf.screen_max_decoded_pixels)}
+                    onChange={(value) => updateFormField("pdfScreenMaxDecodedPixels", value, pdf.screen_max_decoded_pixels)}
+                    {...getFieldPersistenceProps(pdf.screen_max_decoded_pixels)}
                   />
                 </SettingsGroup>
               )}
diff --git a/frontend/src/pages/FileBrowser/__tests__/preferences.test.ts b/frontend/src/pages/FileBrowser/__tests__/preferences.test.ts
index 5163f5060..44d43483a 100644
--- a/frontend/src/pages/FileBrowser/__tests__/preferences.test.ts
+++ b/frontend/src/pages/FileBrowser/__tests__/preferences.test.ts
@@ -92,9 +92,12 @@ describe("File Browser preferences", () => {
   });
 
   it("shows Quick Bar hints according to compact layout, saved evidence, and visibility mode", () => {
-    const { result, rerender } = renderHook(({ visibility, compact }) => useQuickBarKeyboardHints(visibility, compact), {
-      initialProps: { visibility: "auto" as const, compact: true },
-    });
+    const { result, rerender } = renderHook<boolean, { visibility: "auto" | "always" | "never"; compact: boolean }>(
+      ({ visibility, compact }) => useQuickBarKeyboardHints(visibility, compact),
+      {
+        initialProps: { visibility: "auto" as const, compact: true },
+      }
+    );
 
     expect(result.current).toBe(false);
 
diff --git a/frontend/src/pages/FileBrowser/access.ts b/frontend/src/pages/FileBrowser/access.ts
index e49aa0de2..11d26ca92 100644
--- a/frontend/src/pages/FileBrowser/access.ts
+++ b/frontend/src/pages/FileBrowser/access.ts
@@ -18,7 +18,7 @@ export function isConnectionWritable(connection: Connection | undefined): boolea
 }
 
 export function canOpenFileInApp(connection: Connection | undefined): boolean {
-  return Boolean(connection) && (isLocalDrive(connection.id) || !isConnectionReadOnly(connection));
+  return connection !== undefined && (isLocalDrive(connection.id) || !isConnectionReadOnly(connection));
 }
 
 export function canCopyToConnection(sourceConnection: Connection | undefined, destinationConnection: Connection | undefined): boolean {
diff --git a/frontend/src/pages/FileBrowser/archiveExtractionExecution.ts b/frontend/src/pages/FileBrowser/archiveExtractionExecution.ts
index d8dc6f032..fe602bfb1 100644
--- a/frontend/src/pages/FileBrowser/archiveExtractionExecution.ts
+++ b/frontend/src/pages/FileBrowser/archiveExtractionExecution.ts
@@ -1,4 +1,8 @@
-import api, { type ArchiveLiveExtractionStatus, type LocalArchiveRelayExtractionStatus } from "../../services/api";
+import api, {
+  type ArchiveLiveExtractionStatus,
+  type LocalArchiveExecution,
+  type LocalArchiveRelayExtractionStatus,
+} from "../../services/api";
 import { isLocalDrive } from "../../services/backendRouter";
 import {
   beginForegroundLocalArchiveRequest,
@@ -31,12 +35,12 @@ function archiveExtractionSummary(checkpointJson: string | undefined): ArchiveEx
       throw new Error("Archive extraction aggregate is invalid");
     }
     return {
-      filesExtracted: nonNegativeCounter(aggregate.files_extracted),
-      directoriesCreated: nonNegativeCounter(aggregate.directories_created),
-      extractedBytes: nonNegativeCounter(aggregate.extracted_bytes),
-      membersProcessed: nonNegativeCounter(aggregate.members_processed),
-      filesSkipped: nonNegativeCounter(aggregate.members_skipped),
-      filesReplaced: nonNegativeCounter(aggregate.files_replaced),
+      filesExtracted: nonNegativeCounter(Reflect.get(aggregate, "files_extracted")),
+      directoriesCreated: nonNegativeCounter(Reflect.get(aggregate, "directories_created")),
+      extractedBytes: nonNegativeCounter(Reflect.get(aggregate, "extracted_bytes")),
+      membersProcessed: nonNegativeCounter(Reflect.get(aggregate, "members_processed")),
+      filesSkipped: nonNegativeCounter(Reflect.get(aggregate, "members_skipped")),
+      filesReplaced: nonNegativeCounter(Reflect.get(aggregate, "files_replaced")),
       partialMembers: 0,
     };
   } catch {
@@ -158,7 +162,7 @@ export function startZipArchiveExtraction(request: ArchiveExtractionRequest): Ar
 
   let operationId: string | null = null;
   let localSignal: AbortSignal | null = null;
-  let localExecution: { executionId: string; revision: number } | null = null;
+  let localExecution: { executionId: string; revision: number; pendingDecision?: LocalArchiveExecution["pendingDecision"] } | null = null;
   let localCancellation: Promise<void> | null = null;
   let awaitingDecision = false;
   let cancellationRequested = false;
diff --git a/frontend/src/pages/FileBrowser/contentOperationBoundary.test.ts b/frontend/src/pages/FileBrowser/contentOperationBoundary.test.ts
index b0310483c..ea915b8b1 100644
--- a/frontend/src/pages/FileBrowser/contentOperationBoundary.test.ts
+++ b/frontend/src/pages/FileBrowser/contentOperationBoundary.test.ts
@@ -54,23 +54,23 @@ function findForbiddenTransportImports(sourceFilePath: string, ast: unknown): st
     }
 
     const node = value as Record<string, unknown>;
-    const type = node.type;
-    const source = node.source as Record<string, unknown> | undefined;
-    const firstArgument = (node.arguments as unknown[] | undefined)?.[0] as Record<string, unknown> | undefined;
-    const typeImportArgument = node.argument as Record<string, unknown> | undefined;
+    const type = node["type"];
+    const source = node["source"] as Record<string, unknown> | undefined;
+    const firstArgument = (node["arguments"] as unknown[] | undefined)?.[0] as Record<string, unknown> | undefined;
+    const typeImportArgument = node["argument"] as Record<string, unknown> | undefined;
     const moduleSpecifier =
-      typeof source?.value === "string"
-        ? source.value
+      typeof source?.["value"] === "string"
+        ? source["value"]
         : type === "CallExpression" &&
-            (node.callee as Record<string, unknown> | undefined)?.type === "Import" &&
-            typeof firstArgument?.value === "string"
-          ? firstArgument.value
+            (node["callee"] as Record<string, unknown> | undefined)?.["type"] === "Import" &&
+            typeof firstArgument?.["value"] === "string"
+          ? firstArgument["value"]
           : type === "CallExpression" &&
-              (node.callee as Record<string, unknown> | undefined)?.name === "require" &&
-              typeof firstArgument?.value === "string"
-            ? firstArgument.value
-            : type === "TSImportType" && typeof typeImportArgument?.value === "string"
-              ? typeImportArgument.value
+              (node["callee"] as Record<string, unknown> | undefined)?.["name"] === "require" &&
+              typeof firstArgument?.["value"] === "string"
+            ? firstArgument["value"]
+            : type === "TSImportType" && typeof typeImportArgument?.["value"] === "string"
+              ? typeImportArgument["value"]
               : null;
     if (typeof moduleSpecifier === "string" && isForbiddenTransportSpecifier(sourceFilePath, moduleSpecifier)) {
       forbiddenImports.push(`${sourceFilePath}: ${moduleSpecifier}`);
@@ -82,9 +82,9 @@ function findForbiddenTransportImports(sourceFilePath: string, ast: unknown): st
 }
 
 function getPropertyName(node: Record<string, unknown>): string | null {
-  const key = node.key as Record<string, unknown> | undefined;
-  if (key?.type === "Identifier" && typeof key.name === "string") return key.name;
-  if (key?.type === "StringLiteral" && typeof key.value === "string") return key.value;
+  const key = node["key"] as Record<string, unknown> | undefined;
+  if (key?.["type"] === "Identifier" && typeof key["name"] === "string") return key["name"];
+  if (key?.["type"] === "StringLiteral" && typeof key["value"] === "string") return key["value"];
   return null;
 }
 
@@ -100,13 +100,13 @@ function findForbiddenListingLoaderAccess(sourceFilePath: string, ast: unknown):
     }
 
     const node = value as Record<string, unknown>;
-    const type = node.type;
-    const property = node.property as Record<string, unknown> | undefined;
+    const type = node["type"];
+    const property = node["property"] as Record<string, unknown> | undefined;
     const propertyName = getPropertyName(node);
-    const memberName = property?.type === "Identifier" && typeof property.name === "string" ? property.name : null;
+    const memberName = property?.["type"] === "Identifier" && typeof property["name"] === "string" ? property["name"] : null;
     if (
       (type === "MemberExpression" || type === "OptionalMemberExpression") &&
-      !node.computed &&
+      !node["computed"] &&
       memberName !== null &&
       privateListingLoaderNames.has(memberName)
     ) {
diff --git a/frontend/src/pages/FileBrowser/contentOperations.test.ts b/frontend/src/pages/FileBrowser/contentOperations.test.ts
index ef4f7a5b3..7242c58e5 100644
--- a/frontend/src/pages/FileBrowser/contentOperations.test.ts
+++ b/frontend/src/pages/FileBrowser/contentOperations.test.ts
@@ -3,6 +3,9 @@ import type { TFunction } from "i18next";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import api from "../../services/api";
 import { browserHistoryService } from "../../services/browserHistoryService";
+import { StorageArchiveOperationCoordinator } from "../../services/storageArchiveOperations";
+import type { StorageBackendRegistry } from "../../services/storageContracts";
+import { requireTestValue } from "../../test/helpers/assertions";
 import { FileType } from "../../types";
 import {
   createContentItem,
@@ -275,9 +278,13 @@ describe("content operations", () => {
     );
 
     expect(copyWithinBackend).toHaveBeenCalledWith(
-      expect.objectContaining({ targetName: undefined, targetResolutionPolicy: "ask", transferAttemptId: onAttemptStart.mock.calls[0][0] })
+      expect.objectContaining({
+        targetName: undefined,
+        targetResolutionPolicy: "ask",
+        transferAttemptId: requireTestValue(onAttemptStart.mock.calls[0])[0],
+      })
     );
-    expect(onAttemptSettled).toHaveBeenCalledWith(onAttemptStart.mock.calls[0][0]);
+    expect(onAttemptSettled).toHaveBeenCalledWith(requireTestValue(onAttemptStart.mock.calls[0])[0]);
     expect(api.copyItem).not.toHaveBeenCalled();
   });
 
@@ -892,8 +899,8 @@ describe("content operations", () => {
     );
 
     expect(sourceBackend.copyWithinBackend).toHaveBeenCalledTimes(2);
-    expect(sourceBackend.copyWithinBackend.mock.calls[0][0].transferAttemptId).not.toBe(
-      sourceBackend.copyWithinBackend.mock.calls[1][0].transferAttemptId
+    expect(requireTestValue(sourceBackend.copyWithinBackend.mock.calls[0])[0].transferAttemptId).not.toBe(
+      requireTestValue(sourceBackend.copyWithinBackend.mock.calls[1])[0].transferAttemptId
     );
     expect(destinationBackend.remove).not.toHaveBeenCalled();
   });
@@ -978,7 +985,7 @@ describe("content operations", () => {
   it("retries refreshed leaf conflicts without restarting the directory traversal", async () => {
     const root = { name: "root", path: "root", type: "directory" };
     const existing = { name: "report.txt", path: "output/root/report.txt", type: "file" };
-    const conflict = (target: typeof existing) => ({
+    const conflict = (target: typeof existing & { modified_at?: string }) => ({
       response: {
         status: 409,
         data: { detail: { incoming_file: { name: "report.txt", path: "root/report.txt", type: "file" }, existing_file: target } },
@@ -1281,19 +1288,45 @@ describe("content operations", () => {
     const sources = [virtualItemHandle(zipLocation, "inner/one.txt"), virtualItemHandle(zipLocation, "inner/two.txt")];
     const destination = physicalLocation("source", "output");
     const target = { kind: "smb" as const, connectionId: "source" };
-    const storageRegistry = {
-      resolveItem: vi.fn(({ path }) => ({ target, path, resolvedTarget: { target } })),
-      resolveDirectory: vi.fn(({ path }) => ({ target, path, resolvedTarget: { target } })),
-      getCapabilities: vi.fn(() => ({ readable: true, writable: true })),
+    const resolvedTarget = {
+      target,
+      connection: null,
+      capabilitySnapshot: {
+        capabilityRevision: 1,
+        connections: [],
+        companion: { status: "unpaired" as const, revision: 0, drives: [], error: null },
+      },
     };
-    const archiveOperations = {
-      start: vi.fn(() => ({ result: Promise.resolve({ status: "completed" }), cancel: vi.fn(), isCancellationRequested: () => false })),
+    const storageRegistry: StorageBackendRegistry = {
+      resolveItem: vi.fn(({ path }) => ({ target, path, resolvedTarget })),
+      resolveDirectory: vi.fn(({ path }) => ({ target, path, resolvedTarget })),
+      getBackend: vi.fn(() => {
+        throw new Error("Archive creation should use the coordinator, not resolve a backend directly");
+      }),
+      getCapabilities: vi.fn(() => ({
+        readable: true,
+        writable: true,
+        canEditText: true,
+        canList: true,
+        canReadArchive: true,
+        preview: { imageConversion: true, imageResizing: true, pdfNormalization: true },
+        canWriteFile: true,
+        canResolveActivation: true,
+        canOpenInNativeApp: true,
+      })),
     };
-    const context = { ...environment, storageRegistry, archiveOperations } as never;
+    const archiveOperations = new StorageArchiveOperationCoordinator(storageRegistry);
+    const startArchive = vi.spyOn(archiveOperations, "start").mockReturnValue({
+      result: Promise.resolve({ status: "completed", effects: { source: "unchanged", destination: "mutated" } }),
+      recoveryReady: Promise.resolve(null),
+      cancel: vi.fn(),
+      isCancellationRequested: () => false,
+    });
+    const context = { ...environment, storageRegistry, archiveOperations };
 
     expect(getCreateContainerAvailability({ sources, destination }, context)).toEqual({ available: true });
     await expect(startCreateContainer({ sources, destination, name: "selected.zip" }, context).result).resolves.toBeUndefined();
-    expect(archiveOperations.start).toHaveBeenCalledWith(
+    expect(startArchive).toHaveBeenCalledWith(
       expect.objectContaining({
         sources: [expect.objectContaining({ path: "files.zip" })],
         selectedMemberPaths: ["inner/one.txt", "inner/two.txt"],
@@ -1303,12 +1336,18 @@ describe("content operations", () => {
       available: false,
       reason: "unsupported-source",
     });
-    const localTarget = { kind: "local" as const, connectionId: "local-drive:c" };
+    const localTarget = { kind: "local" as const, driveId: "c" };
     expect(
-      getCreateContainerAvailability({ sources, destination }, {
-        ...context,
-        storageRegistry: { ...storageRegistry, resolveDirectory: () => ({ target: localTarget }) },
-      } as never)
+      getCreateContainerAvailability(
+        { sources, destination },
+        {
+          ...context,
+          storageRegistry: {
+            ...storageRegistry,
+            resolveDirectory: ({ path }) => ({ target: localTarget, path, resolvedTarget: { ...resolvedTarget, target: localTarget } }),
+          },
+        }
+      )
     ).toEqual({ available: false, reason: "unsupported-source" });
   });
 
diff --git a/frontend/src/pages/FileBrowser/contentOperations.ts b/frontend/src/pages/FileBrowser/contentOperations.ts
index 626787b35..abb3536a7 100644
--- a/frontend/src/pages/FileBrowser/contentOperations.ts
+++ b/frontend/src/pages/FileBrowser/contentOperations.ts
@@ -36,6 +36,7 @@ export async function downloadContentSelection(
 ): Promise<void> {
   const item = items[0];
   if (!item || !items.every((selected) => selected.entry.is_readable)) throw new Error("Select readable items to download");
+  const virtualSource = item.handle.kind === "virtual" ? item.handle.location.source.path : null;
   if (items.length > 1 || item.entry.type === FileType.DIRECTORY) {
     if (item.handle.kind === "physical" && items.every((selected) => selected.handle.kind === "physical")) {
       await downloadPhysicalSelection(
@@ -50,7 +51,7 @@ export async function downloadContentSelection(
         (selected) =>
           selected.handle.kind === "virtual" &&
           selected.handle.location.providerId === "zip" &&
-          selected.handle.location.source.path === item.handle.location.source.path
+          selected.handle.location.source.path === virtualSource
       )
     ) {
       await downloadZipSelection(
@@ -488,6 +489,13 @@ export async function executeTransferTree(
   };
   const preservePartialEffects = (result: ContentTransferResult): ContentTransferResult => {
     if (result.status === "skipped") return result;
+    if (result.status === "completed_with_source_retained") {
+      const effects = partialEffects();
+      if (effects.source === "unknown" || effects.destination === "unknown") {
+        return { status: "outcome_unknown", replaced, effects };
+      }
+      return { ...result, replaced, effects: { source: effects.source, destination: effects.destination } };
+    }
     return { ...result, replaced, effects: partialEffects() };
   };
   const decide = async (
diff --git a/frontend/src/pages/FileBrowser/contentProviders.test.ts b/frontend/src/pages/FileBrowser/contentProviders.test.ts
index 36ed3fa3a..2ab784693 100644
--- a/frontend/src/pages/FileBrowser/contentProviders.test.ts
+++ b/frontend/src/pages/FileBrowser/contentProviders.test.ts
@@ -2,6 +2,8 @@ import { describe, expect, it, vi } from "vitest";
 import api from "../../services/api";
 import { PreviewUnavailableError } from "../../services/previewPolicy";
 import { createStorageBackedTestContentProviderRegistry } from "../../test/helpers";
+import { requireTestValue } from "../../test/helpers/assertions";
+import { createMockLocalArchiveExecution } from "../../test/helpers/mockFactories";
 import { FileType } from "../../types";
 import { getArchiveExtractionAvailability, startArchiveExtraction } from "./contentOperations";
 import {
@@ -128,7 +130,7 @@ describe("content providers", () => {
       archive: { path: "archives/one.zip", size: 1 },
       path: "images",
       items: [{ name: "blocked.png", path: "images/blocked.png", type: FileType.FILE, state: "blocked", is_hidden: false }],
-      total: 1,
+
       page_size: 100,
     });
 
@@ -154,7 +156,7 @@ describe("content providers", () => {
       archive: { path: "archives/one.zip", size: 1 },
       path: "images",
       items: [{ name: "nested", path: "images/nested", type: FileType.DIRECTORY, state: "readable", is_hidden: false }],
-      total: 1,
+
       page_size: 100,
     });
 
@@ -195,7 +197,8 @@ describe("content providers", () => {
       }),
     };
     vi.mocked(api.listDirectory).mockResolvedValueOnce({
-      items: [{ name: "readme.md", path: "docs/readme.md", type: FileType.FILE }],
+      path: "docs",
+      items: [{ name: "readme.md", path: "docs/readme.md", type: FileType.FILE, is_readable: true, is_hidden: false }],
       total: 1,
     });
 
@@ -204,7 +207,9 @@ describe("content providers", () => {
       .list(location);
 
     expect(api.listDirectory).toHaveBeenCalledWith("local-drive:c", "docs", { signal: undefined });
-    expect(listing.items).toEqual([physicalItem(location, { name: "readme.md", path: "docs/readme.md", type: FileType.FILE })]);
+    expect(listing.items).toEqual([
+      physicalItem(location, { name: "readme.md", path: "docs/readme.md", type: FileType.FILE, is_readable: true, is_hidden: false }),
+    ]);
   });
 
   it("does not use the local-drive compatibility path when SMB directory resolution fails", async () => {
@@ -280,33 +285,39 @@ describe("content providers", () => {
 
   it("extracts a local ZIP through its content provider", async () => {
     const localArchiveLocation = virtualLocation("zip", "local-drive:c", physicalLocation("local-drive:c", "archives/one.zip"), "");
-    vi.mocked(api.startLocalArchiveExtraction).mockResolvedValueOnce({
-      execution_id: "local-extract-1",
-      phase: "streaming",
-      revision: 1,
-      progress: localArchiveProgress(),
-      cancellation_requested: false,
-    });
-    vi.mocked(api.waitForLocalArchiveExecution).mockImplementationOnce(async (_connectionId, _executionId, onUpdate) => {
-      onUpdate?.({
+    vi.mocked(api.startLocalArchiveExtraction).mockResolvedValueOnce(
+      createMockLocalArchiveExecution({
         execution_id: "local-extract-1",
         phase: "streaming",
         revision: 1,
-        progress: localArchiveProgress(2, 0, 3, 10),
-        cancellation_requested: false,
-        aggregate_counters: extractionAggregate(1, 1, 5),
-      });
-      const completed = {
-        execution_id: "local-extract-1",
-        phase: "completed" as const,
-        revision: 2,
-        progress: localArchiveProgress(3, 1, 3, 10),
+        progress: localArchiveProgress(),
         cancellation_requested: false,
-        aggregate_counters: extractionAggregate(2, 1, 10, 1),
-      };
-      onUpdate?.(completed);
-      return completed;
-    });
+      })
+    );
+    vi.mocked(api.waitForLocalArchiveExecution).mockImplementationOnce(
+      requireTestValue(async (_connectionId, _executionId, onUpdate) => {
+        onUpdate?.(
+          createMockLocalArchiveExecution({
+            execution_id: "local-extract-1",
+            phase: "streaming",
+            revision: 1,
+            progress: localArchiveProgress(2, 0, 3, 10),
+            cancellation_requested: false,
+            aggregate_counters: extractionAggregate(1, 1, 5),
+          })
+        );
+        const completed = createMockLocalArchiveExecution({
+          execution_id: "local-extract-1",
+          phase: "completed" as const,
+          revision: 2,
+          progress: localArchiveProgress(3, 1, 3, 10),
+          cancellation_requested: false,
+          aggregate_counters: extractionAggregate(2, 1, 10, 1),
+        });
+        onUpdate?.(completed);
+        return completed;
+      })
+    );
 
     const execution = startArchiveExtraction(createStorageBackedTestContentProviderRegistry(), {
       source: localArchiveLocation,
@@ -344,21 +355,25 @@ describe("content providers", () => {
 
   it("extracts a local ZIP to a different local drive through the Companion", async () => {
     const localArchiveLocation = virtualLocation("zip", "local-drive:c", physicalLocation("local-drive:c", "archives/one.zip"), "");
-    vi.mocked(api.startLocalArchiveExtraction).mockResolvedValueOnce({
-      execution_id: "cross-drive-extract-1",
-      phase: "streaming",
-      revision: 1,
-      progress: localArchiveProgress(),
-      cancellation_requested: false,
-    });
-    vi.mocked(api.waitForLocalArchiveExecution).mockResolvedValueOnce({
-      execution_id: "cross-drive-extract-1",
-      phase: "completed",
-      revision: 2,
-      progress: localArchiveProgress(1, 0, 1, 5),
-      cancellation_requested: false,
-      aggregate_counters: extractionAggregate(1, 0, 5),
-    });
+    vi.mocked(api.startLocalArchiveExtraction).mockResolvedValueOnce(
+      createMockLocalArchiveExecution({
+        execution_id: "cross-drive-extract-1",
+        phase: "streaming",
+        revision: 1,
+        progress: localArchiveProgress(),
+        cancellation_requested: false,
+      })
+    );
+    vi.mocked(api.waitForLocalArchiveExecution).mockResolvedValueOnce(
+      createMockLocalArchiveExecution({
+        execution_id: "cross-drive-extract-1",
+        phase: "completed",
+        revision: 2,
+        progress: localArchiveProgress(1, 0, 1, 5),
+        cancellation_requested: false,
+        aggregate_counters: extractionAggregate(1, 0, 5),
+      })
+    );
 
     await expect(
       startArchiveExtraction(createStorageBackedTestContentProviderRegistry(), {
@@ -413,47 +428,55 @@ describe("content providers", () => {
 
   it("resumes a paused direct-local extraction through the Companion decision endpoint", async () => {
     const localArchiveLocation = virtualLocation("zip", "local-drive:c", physicalLocation("local-drive:c", "archives/one.zip"), "");
-    vi.mocked(api.startLocalArchiveExtraction).mockResolvedValueOnce({
-      execution_id: "local-extract-1",
-      phase: "streaming",
-      revision: 1,
-      progress: localArchiveProgress(),
-      cancellation_requested: false,
-    });
-    vi.mocked(api.waitForLocalArchiveExecution)
-      .mockResolvedValueOnce({
+    vi.mocked(api.startLocalArchiveExtraction).mockResolvedValueOnce(
+      createMockLocalArchiveExecution({
         execution_id: "local-extract-1",
-        phase: "awaiting_user_decision",
-        revision: 2,
+        phase: "streaming",
+        revision: 1,
         progress: localArchiveProgress(),
         cancellation_requested: false,
-        pendingDecision: {
-          kind: "collision",
-          source_session_id: "source-session-1",
-          delivery_sequence: 1,
-          decision_revision: 1,
-          member_path: "source.txt",
-          is_directory: false,
-          source: { path: "source.txt", size: 5, modified_at: "2025-01-01T12:00:00Z" },
-          target: { path: "renamed.txt", size: 10, modified_at: "2025-01-02T12:00:00Z" },
-          allowed_actions: ["skip", "skip_all", "replace", "replace_all", "replace_older", "rename"],
-        },
       })
-      .mockResolvedValueOnce({
+    );
+    vi.mocked(api.waitForLocalArchiveExecution)
+      .mockResolvedValueOnce(
+        createMockLocalArchiveExecution({
+          execution_id: "local-extract-1",
+          phase: "awaiting_user_decision",
+          revision: 2,
+          progress: localArchiveProgress(),
+          cancellation_requested: false,
+          pendingDecision: {
+            kind: "collision",
+            source_session_id: "source-session-1",
+            delivery_sequence: 1,
+            decision_revision: 1,
+            member_path: "source.txt",
+            is_directory: false,
+            source: { path: "source.txt", size: 5, modified_at: "2025-01-01T12:00:00Z" },
+            target: { path: "renamed.txt", size: 10, modified_at: "2025-01-02T12:00:00Z" },
+            allowed_actions: ["skip", "skip_all", "replace", "replace_all", "replace_older", "rename"],
+          },
+        })
+      )
+      .mockResolvedValueOnce(
+        createMockLocalArchiveExecution({
+          execution_id: "local-extract-1",
+          phase: "completed",
+          revision: 4,
+          progress: localArchiveProgress(1),
+          cancellation_requested: false,
+          aggregate_counters: extractionAggregate(1, 0, 5),
+        })
+      );
+    vi.mocked(api.decideLocalArchiveExecution).mockResolvedValueOnce(
+      createMockLocalArchiveExecution({
         execution_id: "local-extract-1",
-        phase: "completed",
-        revision: 4,
-        progress: localArchiveProgress(1),
+        phase: "streaming",
+        revision: 3,
+        progress: localArchiveProgress(),
         cancellation_requested: false,
-        aggregate_counters: extractionAggregate(1, 0, 5),
-      });
-    vi.mocked(api.decideLocalArchiveExecution).mockResolvedValueOnce({
-      execution_id: "local-extract-1",
-      phase: "streaming",
-      revision: 3,
-      progress: localArchiveProgress(),
-      cancellation_requested: false,
-    });
+      })
+    );
 
     const execution = startArchiveExtraction(createStorageBackedTestContentProviderRegistry(), {
       source: localArchiveLocation,
@@ -483,47 +506,55 @@ describe("content providers", () => {
 
   it("retries a paused direct-local member error through the Companion decision endpoint", async () => {
     const localArchiveLocation = virtualLocation("zip", "local-drive:c", physicalLocation("local-drive:c", "archives/one.zip"), "");
-    vi.mocked(api.startLocalArchiveExtraction).mockResolvedValueOnce({
-      execution_id: "local-extract-1",
-      phase: "streaming",
-      revision: 1,
-      progress: localArchiveProgress(),
-      cancellation_requested: false,
-    });
-    vi.mocked(api.waitForLocalArchiveExecution)
-      .mockResolvedValueOnce({
+    vi.mocked(api.startLocalArchiveExtraction).mockResolvedValueOnce(
+      createMockLocalArchiveExecution({
         execution_id: "local-extract-1",
-        phase: "awaiting_user_decision",
-        revision: 2,
+        phase: "streaming",
+        revision: 1,
         progress: localArchiveProgress(),
         cancellation_requested: false,
-        pendingDecision: {
-          kind: "member_error",
-          source_session_id: "source-session-1",
-          delivery_sequence: 1,
-          decision_revision: 1,
-          member_path: "source.txt",
-          target_path: "archives/one/source.txt",
-          message: "archive member integrity check failed",
-          partial_output: true,
-          allowed_actions: ["retry", "ignore"],
-        },
       })
-      .mockResolvedValueOnce({
+    );
+    vi.mocked(api.waitForLocalArchiveExecution)
+      .mockResolvedValueOnce(
+        createMockLocalArchiveExecution({
+          execution_id: "local-extract-1",
+          phase: "awaiting_user_decision",
+          revision: 2,
+          progress: localArchiveProgress(),
+          cancellation_requested: false,
+          pendingDecision: {
+            kind: "member_error",
+            source_session_id: "source-session-1",
+            delivery_sequence: 1,
+            decision_revision: 1,
+            member_path: "source.txt",
+            target_path: "archives/one/source.txt",
+            message: "archive member integrity check failed",
+            partial_output: true,
+            allowed_actions: ["retry", "ignore"],
+          },
+        })
+      )
+      .mockResolvedValueOnce(
+        createMockLocalArchiveExecution({
+          execution_id: "local-extract-1",
+          phase: "completed",
+          revision: 4,
+          progress: localArchiveProgress(1),
+          cancellation_requested: false,
+          aggregate_counters: extractionAggregate(1, 0, 5),
+        })
+      );
+    vi.mocked(api.decideLocalArchiveExecution).mockResolvedValueOnce(
+      createMockLocalArchiveExecution({
         execution_id: "local-extract-1",
-        phase: "completed",
-        revision: 4,
-        progress: localArchiveProgress(1),
+        phase: "streaming",
+        revision: 3,
+        progress: localArchiveProgress(),
         cancellation_requested: false,
-        aggregate_counters: extractionAggregate(1, 0, 5),
-      });
-    vi.mocked(api.decideLocalArchiveExecution).mockResolvedValueOnce({
-      execution_id: "local-extract-1",
-      phase: "streaming",
-      revision: 3,
-      progress: localArchiveProgress(),
-      cancellation_requested: false,
-    });
+      })
+    );
 
     const execution = startArchiveExtraction(createStorageBackedTestContentProviderRegistry(), {
       source: localArchiveLocation,
@@ -556,27 +587,33 @@ describe("content providers", () => {
 
   it("cancels a direct-local ZIP extraction through its execution handle", async () => {
     const localArchiveLocation = virtualLocation("zip", "local-drive:c", physicalLocation("local-drive:c", "archives/one.zip"), "");
-    vi.mocked(api.startLocalArchiveExtraction).mockResolvedValueOnce({
-      execution_id: "local-extract-1",
-      phase: "streaming",
-      revision: 1,
-      progress: localArchiveProgress(),
-      cancellation_requested: false,
-    });
-    vi.mocked(api.cancelLocalArchiveExecutionWithRevisionRetry).mockResolvedValueOnce({
-      execution_id: "local-extract-1",
-      phase: "streaming",
-      revision: 2,
-      progress: localArchiveProgress(),
-      cancellation_requested: true,
-    });
-    vi.mocked(api.waitForLocalArchiveExecution).mockResolvedValueOnce({
-      execution_id: "local-extract-1",
-      phase: "cancelled",
-      revision: 3,
-      progress: localArchiveProgress(),
-      cancellation_requested: true,
-    });
+    vi.mocked(api.startLocalArchiveExtraction).mockResolvedValueOnce(
+      createMockLocalArchiveExecution({
+        execution_id: "local-extract-1",
+        phase: "streaming",
+        revision: 1,
+        progress: localArchiveProgress(),
+        cancellation_requested: false,
+      })
+    );
+    vi.mocked(api.cancelLocalArchiveExecutionWithRevisionRetry).mockResolvedValueOnce(
+      createMockLocalArchiveExecution({
+        execution_id: "local-extract-1",
+        phase: "streaming",
+        revision: 2,
+        progress: localArchiveProgress(),
+        cancellation_requested: true,
+      })
+    );
+    vi.mocked(api.waitForLocalArchiveExecution).mockResolvedValueOnce(
+      createMockLocalArchiveExecution({
+        execution_id: "local-extract-1",
+        phase: "cancelled",
+        revision: 3,
+        progress: localArchiveProgress(),
+        cancellation_requested: true,
+      })
+    );
 
     const execution = startArchiveExtraction(createStorageBackedTestContentProviderRegistry(), {
       source: localArchiveLocation,
@@ -614,27 +651,33 @@ describe("content providers", () => {
 
   it("uses the shared direct-local cancellation helper after a progress revision race", async () => {
     const localArchiveLocation = virtualLocation("zip", "local-drive:c", physicalLocation("local-drive:c", "archives/one.zip"), "");
-    vi.mocked(api.startLocalArchiveExtraction).mockResolvedValueOnce({
-      execution_id: "local-extract-1",
-      phase: "streaming",
-      revision: 1,
-      progress: localArchiveProgress(),
-      cancellation_requested: false,
-    });
-    vi.mocked(api.cancelLocalArchiveExecutionWithRevisionRetry).mockResolvedValueOnce({
-      execution_id: "local-extract-1",
-      phase: "streaming",
-      revision: 3,
-      progress: localArchiveProgress(),
-      cancellation_requested: true,
-    });
-    vi.mocked(api.waitForLocalArchiveExecution).mockResolvedValueOnce({
-      execution_id: "local-extract-1",
-      phase: "cancelled",
-      revision: 4,
-      progress: localArchiveProgress(),
-      cancellation_requested: true,
-    });
+    vi.mocked(api.startLocalArchiveExtraction).mockResolvedValueOnce(
+      createMockLocalArchiveExecution({
+        execution_id: "local-extract-1",
+        phase: "streaming",
+        revision: 1,
+        progress: localArchiveProgress(),
+        cancellation_requested: false,
+      })
+    );
+    vi.mocked(api.cancelLocalArchiveExecutionWithRevisionRetry).mockResolvedValueOnce(
+      createMockLocalArchiveExecution({
+        execution_id: "local-extract-1",
+        phase: "streaming",
+        revision: 3,
+        progress: localArchiveProgress(),
+        cancellation_requested: true,
+      })
+    );
+    vi.mocked(api.waitForLocalArchiveExecution).mockResolvedValueOnce(
+      createMockLocalArchiveExecution({
+        execution_id: "local-extract-1",
+        phase: "cancelled",
+        revision: 4,
+        progress: localArchiveProgress(),
+        cancellation_requested: true,
+      })
+    );
 
     const execution = startArchiveExtraction(createStorageBackedTestContentProviderRegistry(), {
       source: localArchiveLocation,
@@ -781,21 +824,25 @@ describe("content providers", () => {
     vi.clearAllMocks();
     const localArchiveLocation = virtualLocation("zip", "local-drive:c", physicalLocation("local-drive:c", "archives/one.zip"), "");
     const otherSmbArchiveLocation = virtualLocation("zip", "conn-1", physicalLocation("conn-1", "archives/one.zip"), "");
-    vi.mocked(api.startLocalArchiveExtraction).mockResolvedValueOnce({
-      execution_id: "local-extract-1",
-      phase: "streaming",
-      revision: 1,
-      progress: localArchiveProgress(),
-      cancellation_requested: false,
-    });
-    vi.mocked(api.waitForLocalArchiveExecution).mockResolvedValueOnce({
-      execution_id: "local-extract-1",
-      phase: "completed",
-      revision: 2,
-      progress: localArchiveProgress(),
-      cancellation_requested: false,
-      aggregate_counters: extractionAggregate(),
-    });
+    vi.mocked(api.startLocalArchiveExtraction).mockResolvedValueOnce(
+      createMockLocalArchiveExecution({
+        execution_id: "local-extract-1",
+        phase: "streaming",
+        revision: 1,
+        progress: localArchiveProgress(),
+        cancellation_requested: false,
+      })
+    );
+    vi.mocked(api.waitForLocalArchiveExecution).mockResolvedValueOnce(
+      createMockLocalArchiveExecution({
+        execution_id: "local-extract-1",
+        phase: "completed",
+        revision: 2,
+        progress: localArchiveProgress(),
+        cancellation_requested: false,
+        aggregate_counters: extractionAggregate(),
+      })
+    );
 
     await expect(
       startArchiveExtraction(createStorageBackedTestContentProviderRegistry(), {
diff --git a/frontend/src/pages/FileBrowser/fileOperationActions.test.ts b/frontend/src/pages/FileBrowser/fileOperationActions.test.ts
index e38f53d53..d1bd872f6 100644
--- a/frontend/src/pages/FileBrowser/fileOperationActions.test.ts
+++ b/frontend/src/pages/FileBrowser/fileOperationActions.test.ts
@@ -26,7 +26,20 @@ function createContext(hasTwoPanes: boolean) {
     labels: Object.fromEntries(actionIds.map((id) => [id, id])) as Record<FileOperationActionId, string>,
     shortcuts: Object.fromEntries(actionIds.map((id) => [id, "F1"])) as Record<FileOperationActionId, string>,
     unavailableReasons: { delete: "Select an item to delete." },
-    handlers: Object.fromEntries(actionIds.map((id) => [id, vi.fn()])) as Record<FileOperationActionId, () => void>,
+    handlers: {
+      "new-directory": vi.fn(),
+      "new-file": vi.fn(),
+      rename: vi.fn(),
+      delete: vi.fn(),
+      copy: vi.fn(),
+      move: vi.fn(),
+      "create-archive": vi.fn(),
+      "extract-archive": vi.fn(),
+      download: vi.fn(),
+      share: vi.fn(),
+      upload: vi.fn(),
+      refresh: vi.fn(),
+    } satisfies Record<FileOperationActionId, () => void>,
   };
 }
 
diff --git a/frontend/src/pages/FileBrowser/itemActionAvailability.test.ts b/frontend/src/pages/FileBrowser/itemActionAvailability.test.ts
index 41a67bd6c..77599fff8 100644
--- a/frontend/src/pages/FileBrowser/itemActionAvailability.test.ts
+++ b/frontend/src/pages/FileBrowser/itemActionAvailability.test.ts
@@ -46,7 +46,7 @@ describe("getItemActionAvailability", () => {
 
   it("treats links to directories as folders", () => {
     const item = createItem("documents-link");
-    item.entry.link_target = { target: { type: FileType.DIRECTORY } };
+    item.entry.link_target = { source_path: item.entry.path, state: "resolved", target: { name: "target", type: FileType.DIRECTORY } };
 
     expect(
       getItemActionAvailability({
diff --git a/frontend/src/pages/FileBrowser/routing.ts b/frontend/src/pages/FileBrowser/routing.ts
index 2f5a3b47a..eeaa9c59f 100644
--- a/frontend/src/pages/FileBrowser/routing.ts
+++ b/frontend/src/pages/FileBrowser/routing.ts
@@ -112,7 +112,6 @@ export const buildBrowseRouteTarget = (
     return {
       kind: BROWSE_TARGET_KIND_LOCAL,
       targetId: driveId,
-      connectionId,
       path: buildRoutePath(path, virtualLocation),
       ...(virtualLocation ? { virtualLocation } : {}),
     };
diff --git a/frontend/src/pages/FileBrowser/types.ts b/frontend/src/pages/FileBrowser/types.ts
index ff5c89679..effb70540 100644
--- a/frontend/src/pages/FileBrowser/types.ts
+++ b/frontend/src/pages/FileBrowser/types.ts
@@ -214,7 +214,7 @@ export interface UseFileBrowserPaneReturn {
   sortDirection: "asc" | "desc";
   setSortDirection: React.Dispatch<React.SetStateAction<"asc" | "desc">>;
   viewMode: ViewMode;
-  setViewMode: React.Dispatch<React.SetStateAction<ViewMode>>;
+  setViewMode: (viewMode: ViewMode) => void;
   focusedIndex: number;
 
   // ── Selection State (multi-select) ────────────────────────────────────
@@ -271,8 +271,8 @@ export interface UseFileBrowserPaneReturn {
   openInAppLoading: boolean;
 
   // ── Refs (needed by parent for WebSocket wiring / shortcut checks) ────
-  parentRef: React.RefObject<HTMLDivElement>;
-  searchInputRef: React.RefObject<HTMLInputElement>;
+  parentRef: React.RefObject<HTMLDivElement | null>;
+  searchInputRef: React.RefObject<HTMLInputElement | null>;
   listContainerRef: (node: HTMLDivElement | null) => void;
   listContainerEl: HTMLDivElement | null;
   /** Always-current mirror of sortedFiles for use in callbacks. */
diff --git a/frontend/src/pages/FileBrowser/useBrowserUpload.ts b/frontend/src/pages/FileBrowser/useBrowserUpload.ts
index d836f2da3..fc57f9f34 100644
--- a/frontend/src/pages/FileBrowser/useBrowserUpload.ts
+++ b/frontend/src/pages/FileBrowser/useBrowserUpload.ts
@@ -260,7 +260,7 @@ export function useBrowserUpload({
                 directoryChanges.writingPaths.add(parent);
                 const result = await publishBrowserFile(file, destination.connectionId, joinPath(parent, name), policy, {
                   signal: controller.signal,
-                  onProgress: updateProgress,
+                  onProgress: (bytes) => updateProgress(bytes),
                   onUploadSent: () => updateProgress(file.size, "publishing"),
                 });
                 if (result.status === "completed") {
diff --git a/frontend/src/pages/FileBrowser/useFileBrowserPane.ts b/frontend/src/pages/FileBrowser/useFileBrowserPane.ts
index 810fd1bf3..c85eac551 100644
--- a/frontend/src/pages/FileBrowser/useFileBrowserPane.ts
+++ b/frontend/src/pages/FileBrowser/useFileBrowserPane.ts
@@ -32,6 +32,7 @@ import type { StorageBackendRegistry } from "../../services/storageContracts";
 import { useSambeeTheme } from "../../theme";
 import type { FileEntry, RecentFileValidationError } from "../../types";
 import { FileType, isApiError } from "../../types";
+import { getApiErrorMessage } from "../../utils/apiErrors";
 import { getAllViewerIds, getCompatibleViewerIds, getFileTypeByExtension, isImageFile, type ViewerId } from "../../utils/FileTypeRegistry";
 import { compareLocalizedStrings } from "../../utils/localeFormatting";
 import { getConnectionById, isConnectionReadOnly } from "./access";
@@ -113,6 +114,8 @@ const UNAVAILABLE_STORAGE_REGISTRY: StorageBackendRegistry = {
       writable: false,
       canList: false,
       canReadArchive: false,
+      canEditText: false,
+      preview: { imageConversion: false, imageResizing: false, pdfNormalization: false },
       canWriteFile: false,
       canResolveActivation: false,
       canOpenInNativeApp: false,
@@ -560,9 +563,10 @@ export function useFileBrowserPane(config: UseFileBrowserPaneConfig): UseFileBro
   const latestVirtualActivationIdRef = React.useRef(0);
   const pendingLocationRef = React.useRef<{ connectionId: string; path: string } | null>(null);
   const latestLocalActivationRequestIdRef = React.useRef(0);
-  const loadPhysicalDirectoryRef =
-    React.useRef<(path: string, forceRefresh?: boolean, preserveVisibleContent?: boolean) => Promise<void>>();
-  const loadArchiveFilesRef = React.useRef<(location: ArchiveLocation, append?: boolean) => Promise<void>>();
+  const loadPhysicalDirectoryRef = React.useRef<
+    ((path: string, forceRefresh?: boolean, preserveVisibleContent?: boolean) => Promise<void>) | undefined
+  >(undefined);
+  const loadArchiveFilesRef = React.useRef<((location: ArchiveLocation, append?: boolean) => Promise<void>) | undefined>(undefined);
   const loadMoreVirtualItemsRef = React.useRef<() => void>(() => {});
   const latestLoadRequestIdRef = React.useRef(0);
   const directoryLoadAbortRef = React.useRef<AbortController | null>(null);
@@ -959,29 +963,26 @@ export function useFileBrowserPane(config: UseFileBrowserPaneConfig): UseFileBro
           setCompanionPairingError({ kind: pairingErrorKind, message: errorMessage });
         } else if (isClientTimeoutError(err)) {
           errorMessage = DIRECTORY_LOAD_TIMEOUT_ERROR;
-        } else if (err && typeof err === "object" && "message" in err) {
-          const error = err as Error & { code?: string };
-          const message = error.message;
-          if (message.includes("Network Error") || message.includes("ECONNREFUSED") || error.code === "ECONNREFUSED") {
+        } else if (err && typeof err === "object" && "message" in err && typeof err.message === "string") {
+          const message = err.message;
+          if (message.includes("Network Error") || message.includes("ECONNREFUSED") || ("code" in err && err.code === "ECONNREFUSED")) {
             errorMessage = DIRECTORY_LOAD_NETWORK_ERROR;
           } else if (isApiError(err)) {
             if (err.response?.status === 404) {
-              const detail = err.response?.data?.detail;
-              errorMessage = detail || "Directory not found. It may have been removed or renamed.";
+              errorMessage = getApiErrorMessage(err, "Directory not found. It may have been removed or renamed.");
             } else if (err.response?.status === 504) {
-              errorMessage = err.response?.data?.detail || DIRECTORY_LOAD_TIMEOUT_ERROR;
-            } else if (err.response?.data?.detail) {
-              errorMessage = err.response.data.detail;
+              errorMessage = getApiErrorMessage(err, DIRECTORY_LOAD_TIMEOUT_ERROR);
+            } else {
+              errorMessage = getApiErrorMessage(err, errorMessage);
             }
           }
         } else if (isApiError(err)) {
           if (err.response?.status === 404) {
-            const detail = err.response?.data?.detail;
-            errorMessage = detail || "Directory not found. It may have been removed or renamed.";
+            errorMessage = getApiErrorMessage(err, "Directory not found. It may have been removed or renamed.");
           } else if (err.response?.status === 504) {
-            errorMessage = err.response?.data?.detail || DIRECTORY_LOAD_TIMEOUT_ERROR;
-          } else if (err.response?.data?.detail) {
-            errorMessage = err.response.data.detail;
+            errorMessage = getApiErrorMessage(err, DIRECTORY_LOAD_TIMEOUT_ERROR);
+          } else {
+            errorMessage = getApiErrorMessage(err, errorMessage);
           }
         }
 
@@ -2813,10 +2814,7 @@ export function useFileBrowserPane(config: UseFileBrowserPaneConfig): UseFileBro
 
       logger.info(`Deleted ${deleteTargets.length} item(s).`, { paths: deleteTargets.map((target) => target.handle.path) }, "file-browser");
     } catch (err: unknown) {
-      let detail = "Failed to delete item.";
-      if (isApiError(err) && err.response?.data?.detail) {
-        detail = err.response.data.detail;
-      }
+      const detail = getApiErrorMessage(err, "Failed to delete item.");
       setError(detail);
       setDeleteTargets((currentTargets) => currentTargets.slice(deletedCount));
       logger.error("Delete failed.", { error: err, paths: deleteTargets.map((target) => target.handle.path) }, "file-browser");
@@ -2885,10 +2883,7 @@ export function useFileBrowserPane(config: UseFileBrowserPaneConfig): UseFileBro
 
         logger.info(`Renamed: ${renameTarget.handle.path} -> ${newName}`, undefined, "file-browser");
       } catch (err: unknown) {
-        let detail = "Failed to rename item.";
-        if (isApiError(err) && err.response?.data?.detail) {
-          detail = err.response.data.detail;
-        }
+        const detail = getApiErrorMessage(err, "Failed to rename item.");
         setRenameError(detail);
         logger.error(`Rename failed: ${renameTarget.handle.path}`, { error: err }, "file-browser");
       } finally {
@@ -2965,10 +2960,7 @@ export function useFileBrowserPane(config: UseFileBrowserPaneConfig): UseFileBro
 
         logger.info(`Created ${createItemType}: ${name}`, undefined, "file-browser");
       } catch (err: unknown) {
-        let detail = "Failed to create item.";
-        if (isApiError(err) && err.response?.data?.detail) {
-          detail = err.response.data.detail;
-        }
+        const detail = getApiErrorMessage(err, "Failed to create item.");
         setCreateError(detail);
         logger.error(`Create failed: ${name}`, { error: err }, "file-browser");
       } finally {
@@ -3403,8 +3395,7 @@ export function useFileBrowserPane(config: UseFileBrowserPaneConfig): UseFileBro
       const segments = targetPath.split("/").filter(Boolean);
       let physicalPath = "";
 
-      for (let index = 0; index < segments.length; index += 1) {
-        const segment = segments[index];
+      for (const [index, segment] of segments.entries()) {
         const candidatePath = joinRoutePath(physicalPath, segment);
         const providerId = providerRegistry.getVirtualProviderIdForFilename(candidatePath);
         if (!providerId) {
@@ -3524,7 +3515,7 @@ export function useFileBrowserPane(config: UseFileBrowserPaneConfig): UseFileBro
 
         // Quick-bar inputs own their keyboard interaction. File-list handlers
         // must not react while focus remains inside the quick bar.
-        if (input.dataset.quickBarInput === "true") {
+        if (input.dataset["quickBarInput"] === "true") {
           return;
         }
 
diff --git a/frontend/src/pages/FileBrowser/useWorkspaceNavigation.ts b/frontend/src/pages/FileBrowser/useWorkspaceNavigation.ts
index 6c5a701dc..dda3c8121 100644
--- a/frontend/src/pages/FileBrowser/useWorkspaceNavigation.ts
+++ b/frontend/src/pages/FileBrowser/useWorkspaceNavigation.ts
@@ -150,8 +150,9 @@ export function useWorkspaceNavigation({
         existingVirtual.path === virtual.virtualPath
       : !existingVirtual;
     if (
+      existing &&
       sameVirtual &&
-      existing?.connectionId === target?.connectionId &&
+      existing.connectionId === target?.connectionId &&
       existing.path === path &&
       existing.viewerId === viewer.viewerId &&
       retry === resolvedRetry.current
@@ -221,7 +222,7 @@ export function useWorkspaceNavigation({
   return {
     navigateRoute,
     openViewer,
-    closeViewer: () => navigateRoute({ ...route, viewer: undefined }),
+    closeViewer: () => navigateRoute({ ...route, viewer: undefined }, { flushSync: true }),
     changeImage: (paneId: PaneId, index: number) => {
       const info = panes.current[paneId].viewInfo;
       const path = info?.images?.[index];
@@ -237,7 +238,7 @@ export function useWorkspaceNavigation({
     changeMode: (mode: "view" | "edit", replace = false) => {
       if (!viewer || viewer.mode === mode) return;
       const next = { ...route, viewer: { ...viewer, mode } };
-      navigateRoute(next, { replace });
+      navigateRoute(next, { replace, flushSync: true });
     },
     openSettings: (settings: MobileSettingsView) => navigateRoute({ ...route, settings }, { flushSync: true }),
     closeSettings: () => navigateRoute({ ...route, settings: undefined }),
diff --git a/frontend/src/pages/FileSearchSettings.tsx b/frontend/src/pages/FileSearchSettings.tsx
index fa65da3da..fad4969d5 100644
--- a/frontend/src/pages/FileSearchSettings.tsx
+++ b/frontend/src/pages/FileSearchSettings.tsx
@@ -1,5 +1,16 @@
 import { Add as AddIcon, Cancel as CancelIcon } from "@mui/icons-material";
-import { Alert, Button, Checkbox, FormControl, FormControlLabel, FormGroup, FormLabel, Stack, TextField } from "@mui/material";
+import {
+  Alert,
+  Button,
+  Checkbox,
+  FormControl,
+  FormControlLabel,
+  FormGroup,
+  FormHelperText,
+  FormLabel,
+  Stack,
+  TextField,
+} from "@mui/material";
 import { useEffect, useState } from "react";
 import { useTranslation } from "react-i18next";
 import { CompactBadge as Chip } from "../components/CompactBadge";
@@ -130,7 +141,8 @@ export function FileSearchSettings() {
             value={Number.isNaN(settings.retention_limit) ? "" : settings.retention_limit}
             error={Boolean(validation.retention)}
             helperText={
-              persistence.fieldErrors.retention_limit ?? (validation.retention ? t("settings.fileSearch.retentionLimitError") : undefined)
+              persistence.fieldErrors["retention_limit"] ??
+              (validation.retention ? t("settings.fileSearch.retentionLimitError") : undefined)
             }
             onChange={(event) => {
               persistence.clearFieldFeedback("retention_limit");
@@ -167,7 +179,7 @@ export function FileSearchSettings() {
             value={Number.isNaN(settings.result_limit) ? "" : settings.result_limit}
             error={Boolean(validation.results)}
             helperText={
-              persistence.fieldErrors.result_limit ?? (validation.results ? t("settings.fileSearch.resultLimitError") : undefined)
+              persistence.fieldErrors["result_limit"] ?? (validation.results ? t("settings.fileSearch.resultLimitError") : undefined)
             }
             onChange={(event) => {
               persistence.clearFieldFeedback("result_limit");
@@ -210,7 +222,7 @@ export function FileSearchSettings() {
             }}
           >
             <FormLabel component="legend" sx={{ color: "text.primary", fontSize: "0.875rem", fontWeight: 500 }}>
-              <Stack direction="row" spacing={1} alignItems="center">
+              <Stack direction="row" spacing={1} sx={{ alignItems: "center" }}>
                 {t("settings.fileSearch.excludedCategories")}
                 <SettingPersistenceIndicator
                   pending={persistence.isPending("excluded_categories")}
@@ -245,8 +257,8 @@ export function FileSearchSettings() {
                 label={t("settings.fileSearch.excludeTemporaryBackup")}
               />
             </FormGroup>
-            {persistence.fieldErrors.excluded_categories ? (
-              <FormHelperText error>{persistence.fieldErrors.excluded_categories}</FormHelperText>
+            {persistence.fieldErrors["excluded_categories"] ? (
+              <FormHelperText error>{persistence.fieldErrors["excluded_categories"]}</FormHelperText>
             ) : null}
           </FormControl>
           <Stack spacing={1}>
@@ -256,7 +268,7 @@ export function FileSearchSettings() {
               error={Boolean(validation.extensions || extensionInputError)}
               helperText={
                 extensionInputError ??
-                persistence.fieldErrors.excluded_extensions ??
+                persistence.fieldErrors["excluded_extensions"] ??
                 (validation.extensions
                   ? t("settings.fileSearch.excludedExtensionsError")
                   : normalizedExtensionPreview && isValidExtension(normalizedExtensionPreview)
@@ -288,7 +300,7 @@ export function FileSearchSettings() {
               {t("settings.fileSearch.excludedExtensionsAdd")}
             </Button>
             {settings.excluded_extensions.length > 0 ? (
-              <Stack direction="row" spacing={1} useFlexGap flexWrap="wrap">
+              <Stack direction="row" spacing={1} useFlexGap sx={{ flexWrap: "wrap" }}>
                 {settings.excluded_extensions.map((extension) => (
                   <Chip
                     key={extension}
diff --git a/frontend/src/pages/NetworkSettings.tsx b/frontend/src/pages/NetworkSettings.tsx
index 74deeb783..cb4fbd4d9 100644
--- a/frontend/src/pages/NetworkSettings.tsx
+++ b/frontend/src/pages/NetworkSettings.tsx
@@ -75,9 +75,9 @@ export function NetworkSettings() {
             if (event.key === "Enter") event.currentTarget.blur();
           }}
           disabled={persistence.isPending("public_url")}
-          error={Boolean(persistence.fieldErrors.public_url)}
+          error={Boolean(persistence.fieldErrors["public_url"])}
           helperText={
-            persistence.fieldErrors.public_url ??
+            persistence.fieldErrors["public_url"] ??
             "The externally reachable HTTPS origin, without a path. Changing it cancels incomplete OIDC sign-ins."
           }
           slotProps={{
@@ -114,9 +114,9 @@ export function NetworkSettings() {
             })
           }
           disabled={persistence.isPending("trusted_proxy_cidrs")}
-          error={Boolean(persistence.fieldErrors.trusted_proxy_cidrs)}
+          error={Boolean(persistence.fieldErrors["trusted_proxy_cidrs"])}
           helperText={
-            persistence.fieldErrors.trusted_proxy_cidrs ??
+            persistence.fieldErrors["trusted_proxy_cidrs"] ??
             "One CIDR per line. Leave empty unless a reverse proxy you operate forwards client IP addresses."
           }
           slotProps={{
diff --git a/frontend/src/pages/PreferencesSettings.tsx b/frontend/src/pages/PreferencesSettings.tsx
index 54363ee42..6c820b8b5 100644
--- a/frontend/src/pages/PreferencesSettings.tsx
+++ b/frontend/src/pages/PreferencesSettings.tsx
@@ -5,6 +5,7 @@ import StarIcon from "@mui/icons-material/Star";
 import { Box, Button, FormControl, InputLabel, MenuItem, Radio, Select, Typography } from "@mui/material";
 import type { SelectChangeEvent } from "@mui/material/Select";
 import axios from "axios";
+import type { TFunction } from "i18next";
 import { useMemo, useState } from "react";
 import { useTranslation } from "react-i18next";
 import { CompactBadge as Chip } from "../components/CompactBadge";
@@ -41,7 +42,7 @@ const REGIONAL_LOCALE_LABEL_KEYS = {
 } as const satisfies Record<(typeof REGIONAL_LOCALE_OPTIONS)[number], string>;
 const PREVIEW_DATE = new Date("2026-03-22T14:35:00Z");
 
-function getLanguageOptionLabel(t: ReturnType<typeof useTranslation>["t"], language: string): string {
+function getLanguageOptionLabel(t: TFunction, language: string): string {
   return language === PSEUDO_LANGUAGE
     ? t("settings.appearancePage.pseudoLanguageOption")
     : t("settings.appearancePage.englishLanguageOption");
diff --git a/frontend/src/pages/SmbSettings.tsx b/frontend/src/pages/SmbSettings.tsx
index f77cefea6..e93ab8b09 100644
--- a/frontend/src/pages/SmbSettings.tsx
+++ b/frontend/src/pages/SmbSettings.tsx
@@ -145,8 +145,8 @@ export function SmbSettings({ dialogSafeHeader = false }: SmbSettingsProps) {
               onChange={(event) => void persistField({ field: "authentication_mode", value: event.target.value as SmbAuthenticationMode })}
               onFocus={() => restoreAuthenticationModeFocus()}
               disabled={persistence.isPending("authentication_mode")}
-              error={Boolean(persistence.fieldErrors.authentication_mode)}
-              helperText={persistence.fieldErrors.authentication_mode ?? t("settings.smbSettings.helper.authenticationMode")}
+              error={Boolean(persistence.fieldErrors["authentication_mode"])}
+              helperText={persistence.fieldErrors["authentication_mode"] ?? t("settings.smbSettings.helper.authenticationMode")}
               slotProps={{ input: { endAdornment: getStatusAdornment("authentication_mode") } }}
             >
               <MenuItem value="negotiate">{t("settings.smbSettings.options.negotiate")}</MenuItem>
@@ -160,8 +160,8 @@ export function SmbSettings({ dialogSafeHeader = false }: SmbSettingsProps) {
               onChange={(event) => void persistField({ field: "encryption_mode", value: event.target.value as SmbEncryptionMode })}
               onFocus={() => restoreEncryptionModeFocus()}
               disabled={persistence.isPending("encryption_mode")}
-              error={Boolean(persistence.fieldErrors.encryption_mode)}
-              helperText={persistence.fieldErrors.encryption_mode ?? t("settings.smbSettings.helper.encryptionMode")}
+              error={Boolean(persistence.fieldErrors["encryption_mode"])}
+              helperText={persistence.fieldErrors["encryption_mode"] ?? t("settings.smbSettings.helper.encryptionMode")}
               slotProps={{ input: { endAdornment: getStatusAdornment("encryption_mode") } }}
             >
               <MenuItem value="signing_only">{t("settings.smbSettings.options.signingOnly")}</MenuItem>
@@ -187,11 +187,11 @@ export function SmbSettings({ dialogSafeHeader = false }: SmbSettingsProps) {
               }}
               disabled={persistence.isPending("connection_timeout_seconds")}
               error={
-                Boolean(persistence.fieldErrors.connection_timeout_seconds) ||
+                Boolean(persistence.fieldErrors["connection_timeout_seconds"]) ||
                 Boolean(touchedFields.connection_timeout_seconds && !hasValidConnectionTimeout)
               }
               helperText={
-                persistence.fieldErrors.connection_timeout_seconds ??
+                persistence.fieldErrors["connection_timeout_seconds"] ??
                 (touchedFields.connection_timeout_seconds && !hasValidConnectionTimeout
                   ? t("settings.smbSettings.connectionTimeoutError")
                   : t("settings.smbSettings.helper.connectionTimeout"))
@@ -221,11 +221,11 @@ export function SmbSettings({ dialogSafeHeader = false }: SmbSettingsProps) {
               }}
               disabled={persistence.isPending("read_chunk_size_bytes")}
               error={
-                Boolean(persistence.fieldErrors.read_chunk_size_bytes) ||
+                Boolean(persistence.fieldErrors["read_chunk_size_bytes"]) ||
                 Boolean(touchedFields.read_chunk_size_bytes && !hasValidReadChunkSize)
               }
               helperText={
-                persistence.fieldErrors.read_chunk_size_bytes ??
+                persistence.fieldErrors["read_chunk_size_bytes"] ??
                 (touchedFields.read_chunk_size_bytes && !hasValidReadChunkSize
                   ? t("settings.smbSettings.readChunkSizeError")
                   : t("settings.smbSettings.helper.readChunkSize"))
diff --git a/frontend/src/pages/__tests__/AccountSettings.test.tsx b/frontend/src/pages/__tests__/AccountSettings.test.tsx
index dc01a8502..85ba362c4 100644
--- a/frontend/src/pages/__tests__/AccountSettings.test.tsx
+++ b/frontend/src/pages/__tests__/AccountSettings.test.tsx
@@ -3,6 +3,7 @@ import userEvent from "@testing-library/user-event";
 import { MemoryRouter, Route, Routes } from "react-router-dom";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { setRegionalLocalePreference } from "../../i18n";
+import { requireTestValue } from "../../test/helpers/assertions";
 import { SambeeThemeProvider } from "../../theme";
 import type { CurrentAccount } from "../../types";
 import { formatLocalizedDateTime } from "../../utils/localeFormatting";
@@ -104,7 +105,7 @@ describe("AccountSettings", () => {
     vi.mocked(api.getCurrentAccount).mockResolvedValue({
       ...PASSWORD_ACCOUNT,
       current_session: {
-        ...PASSWORD_ACCOUNT.current_session,
+        ...requireTestValue(PASSWORD_ACCOUNT.current_session),
         started_at: startedAt,
       },
     });
diff --git a/frontend/src/pages/__tests__/AdvancedSettings.test.tsx b/frontend/src/pages/__tests__/AdvancedSettings.test.tsx
index a552257e8..af9cc256a 100644
--- a/frontend/src/pages/__tests__/AdvancedSettings.test.tsx
+++ b/frontend/src/pages/__tests__/AdvancedSettings.test.tsx
@@ -99,6 +99,19 @@ describe("AdvancedSettings", () => {
     expect(screen.queryByRole("button", { name: /save changes/i })).not.toBeInTheDocument();
   });
 
+  it("does not invent settings for an unavailable optional preprocessor", async () => {
+    vi.mocked(api.getAdvancedSettings).mockResolvedValue({ preprocessors: {} });
+    render(
+      <SambeeThemeProvider>
+        <AdvancedSettings />
+      </SambeeThemeProvider>
+    );
+    expect(await screen.findByText("Preprocessors")).toBeInTheDocument();
+    expect(screen.queryByLabelText("Maximum file size")).not.toBeInTheDocument();
+    expect(screen.queryByLabelText("Conversion timeout")).not.toBeInTheDocument();
+    expect(api.updateAdvancedSettings).not.toHaveBeenCalled();
+  });
+
   it("does not save unchanged values when focus leaves a field", async () => {
     const user = userEvent.setup();
     render(
diff --git a/frontend/src/pages/__tests__/AuthenticationSettings.test.tsx b/frontend/src/pages/__tests__/AuthenticationSettings.test.tsx
index 59e8a35f4..cdaecc675 100644
--- a/frontend/src/pages/__tests__/AuthenticationSettings.test.tsx
+++ b/frontend/src/pages/__tests__/AuthenticationSettings.test.tsx
@@ -6,6 +6,7 @@ import { loadAuthenticationSettingsData, SETTINGS_DATA_CACHE_KEYS } from "../../
 import { clearCachedAsyncData, getCachedAsyncData, primeCachedAsyncData } from "../../hooks/useCachedAsyncData";
 import api from "../../services/api";
 import { authSession } from "../../services/authSession";
+import { uninitializedTestCallback } from "../../test/helpers/assertions";
 import type { OidcAdminConfigurationRead, OidcReviewedPolicy, OidcTestedIdentity, RedactedOidcConfiguration } from "../../types";
 import { AuthenticationSettings } from "../AuthenticationSettings";
 
@@ -268,6 +269,7 @@ describe("Authentication settings", () => {
     const activated = configuration("Activated Provider");
     vi.mocked(api.getOidcConfiguration).mockResolvedValueOnce(response(active)).mockResolvedValueOnce(response(activated));
     vi.mocked(api.getOidcTestResult).mockResolvedValue({
+      refresh_token_returned: true,
       flow_id: "test-flow",
       candidate: tested,
       replacement_mappings: [],
@@ -322,6 +324,7 @@ describe("Authentication settings", () => {
     window.location.hash = "";
     vi.mocked(api.getOidcConfiguration).mockResolvedValue(response(configuration("Active Provider")));
     vi.mocked(api.getOidcTestResult).mockResolvedValue({
+      refresh_token_returned: true,
       flow_id: "stored-flow",
       candidate: configuration("Stored Provider"),
       replacement_mappings: [],
@@ -658,6 +661,7 @@ describe("Authentication settings", () => {
     window.location.hash = "flow=test-flow";
     vi.mocked(api.getOidcConfiguration).mockResolvedValue(response(configuration("Active Provider")));
     vi.mocked(api.getOidcTestResult).mockResolvedValue({
+      refresh_token_returned: true,
       flow_id: "test-flow",
       candidate: configuration("Tested Provider"),
       replacement_mappings: [],
@@ -688,6 +692,7 @@ describe("Authentication settings", () => {
     vi.spyOn(window, "confirm").mockReturnValue(true);
     vi.mocked(api.getOidcConfiguration).mockResolvedValue(response(configuration("Old Provider")));
     vi.mocked(api.getOidcTestResult).mockResolvedValue({
+      refresh_token_returned: true,
       flow_id: "test-flow",
       candidate: configuration("New Provider"),
       replacement_mappings: [
@@ -1236,7 +1241,7 @@ describe("Authentication settings", () => {
 
   it("keeps active group drafts unchanged when a policy preview resolves", async () => {
     const user = userEvent.setup();
-    let resolvePreview: (identity: OidcTestedIdentity) => void;
+    let resolvePreview: (identity: OidcTestedIdentity) => void = uninitializedTestCallback;
     const previewResult = new Promise<OidcTestedIdentity>((resolve) => {
       resolvePreview = resolve;
     });
diff --git a/frontend/src/pages/__tests__/ConnectionSettings.test.tsx b/frontend/src/pages/__tests__/ConnectionSettings.test.tsx
index 23dac7ac1..8e4cb0583 100644
--- a/frontend/src/pages/__tests__/ConnectionSettings.test.tsx
+++ b/frontend/src/pages/__tests__/ConnectionSettings.test.tsx
@@ -2,6 +2,8 @@ import { render, screen, waitFor, within } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import { clearCachedAsyncData } from "../../hooks/useCachedAsyncData";
+import { createMockConnection } from "../../test/fixtures/connections";
+import { requireTestValue } from "../../test/helpers/assertions";
 import { SambeeThemeProvider } from "../../theme";
 import { ConnectionSettings } from "../ConnectionSettings";
 
@@ -139,7 +141,7 @@ describe("ConnectionSettings", () => {
   it("does not render an empty padded header block in headerless mobile mode", async () => {
     mockMobileMode(true);
     vi.mocked(api.getConnections).mockResolvedValue([
-      {
+      createMockConnection({
         id: "shared-1",
         name: "Accounting",
         type: "smb",
@@ -151,7 +153,7 @@ describe("ConnectionSettings", () => {
         scope: "shared",
         access_mode: "read_write",
         can_manage: false,
-      },
+      }),
     ]);
 
     render(
@@ -170,7 +172,7 @@ describe("ConnectionSettings", () => {
 
   it("does not render an empty header or add top margin in headerless desktop mode", async () => {
     vi.mocked(api.getConnections).mockResolvedValue([
-      {
+      createMockConnection({
         id: "shared-1",
         name: "Accounting",
         type: "smb",
@@ -182,7 +184,7 @@ describe("ConnectionSettings", () => {
         scope: "shared",
         access_mode: "read_write",
         can_manage: true,
-      },
+      }),
     ]);
 
     render(
@@ -201,7 +203,7 @@ describe("ConnectionSettings", () => {
 
   it("uses bold body text for connection names and aligns each group's first row with its section", async () => {
     vi.mocked(api.getConnections).mockResolvedValue([
-      {
+      createMockConnection({
         id: "shared-1",
         name: "Accounting",
         type: "smb",
@@ -213,7 +215,7 @@ describe("ConnectionSettings", () => {
         scope: "shared",
         access_mode: "read_write",
         can_manage: true,
-      },
+      }),
     ]);
 
     renderSettings();
@@ -229,7 +231,7 @@ describe("ConnectionSettings", () => {
 
   it("shows a read-only badge for read-only connections", async () => {
     vi.mocked(api.getConnections).mockResolvedValue([
-      {
+      createMockConnection({
         id: "shared-1",
         name: "Accounting",
         type: "smb",
@@ -241,7 +243,7 @@ describe("ConnectionSettings", () => {
         scope: "shared",
         access_mode: "read_only",
         can_manage: true,
-      },
+      }),
     ]);
 
     renderSettings();
@@ -253,7 +255,7 @@ describe("ConnectionSettings", () => {
 
   it("does not show a read-only badge for default read and write connections", async () => {
     vi.mocked(api.getConnections).mockResolvedValue([
-      {
+      createMockConnection({
         id: "shared-1",
         name: "Accounting",
         type: "smb",
@@ -265,7 +267,7 @@ describe("ConnectionSettings", () => {
         scope: "shared",
         access_mode: "read_write",
         can_manage: true,
-      },
+      }),
     ]);
 
     renderSettings();
@@ -282,7 +284,7 @@ describe("ConnectionSettings", () => {
       role: "viewer",
     });
     vi.mocked(api.getConnections).mockResolvedValue([
-      {
+      createMockConnection({
         id: "private-1",
         name: "Viewer Private Share",
         type: "smb",
@@ -294,7 +296,7 @@ describe("ConnectionSettings", () => {
         scope: "private",
         access_mode: "read_only",
         can_manage: false,
-      },
+      }),
     ]);
 
     renderSettings();
@@ -316,7 +318,7 @@ describe("ConnectionSettings", () => {
       role: "viewer",
     });
     vi.mocked(api.getConnections).mockResolvedValue([
-      {
+      createMockConnection({
         id: "private-1",
         name: "Viewer Private Share",
         type: "smb",
@@ -328,7 +330,7 @@ describe("ConnectionSettings", () => {
         scope: "private",
         access_mode: "read_only",
         can_manage: false,
-      },
+      }),
     ]);
 
     renderSettings();
@@ -341,7 +343,7 @@ describe("ConnectionSettings", () => {
   it("omits Test Connection from the small-screen connection actions menu", async () => {
     mockMobileMode(true);
     vi.mocked(api.getConnections).mockResolvedValue([
-      {
+      createMockConnection({
         id: "private-1",
         name: "Managed Private Share",
         type: "smb",
@@ -353,7 +355,7 @@ describe("ConnectionSettings", () => {
         scope: "private",
         access_mode: "read_write",
         can_manage: true,
-      },
+      }),
     ]);
 
     const user = userEvent.setup();
@@ -369,7 +371,7 @@ describe("ConnectionSettings", () => {
 
   it("omits Test Connection from managed desktop actions", async () => {
     vi.mocked(api.getConnections).mockResolvedValue([
-      {
+      createMockConnection({
         id: "private-1",
         name: "Managed Private Share",
         type: "smb",
@@ -381,7 +383,7 @@ describe("ConnectionSettings", () => {
         scope: "private",
         access_mode: "read_write",
         can_manage: true,
-      },
+      }),
     ]);
 
     renderSettings();
@@ -414,7 +416,7 @@ describe("ConnectionSettings", () => {
   it("persists updated visibility when editing and reopening a connection", async () => {
     const user = userEvent.setup();
     let connections = [
-      {
+      createMockConnection({
         id: "shared-1",
         name: "Accounting",
         type: "smb",
@@ -426,7 +428,7 @@ describe("ConnectionSettings", () => {
         scope: "shared" as const,
         access_mode: "read_write" as const,
         can_manage: true,
-      },
+      }),
     ];
 
     vi.mocked(api.getConnections).mockImplementation(async () => connections);
@@ -436,7 +438,7 @@ describe("ConnectionSettings", () => {
         ...updates,
       }));
 
-      return connections[0] as (typeof connections)[number];
+      return requireTestValue(connections[0]);
     });
 
     render(
diff --git a/frontend/src/pages/__tests__/FileBrowser-archive-interruption.test.tsx b/frontend/src/pages/__tests__/FileBrowser-archive-interruption.test.tsx
index 5549ee222..43c63532c 100644
--- a/frontend/src/pages/__tests__/FileBrowser-archive-interruption.test.tsx
+++ b/frontend/src/pages/__tests__/FileBrowser-archive-interruption.test.tsx
@@ -8,6 +8,7 @@ import {
   storeForegroundArchiveOperation,
 } from "../../services/foregroundArchiveOperation";
 import { resetCurrentUserSettingsStoreForTests } from "../../services/userSettingsStore";
+import { createMockAuthToken } from "../../test/fixtures/users";
 import { type ApiMock, setupSuccessfulApiMocks } from "../../test/helpers";
 import { renderBrowser } from "./FileBrowser.test.utils";
 
@@ -18,7 +19,7 @@ describe("FileBrowser archive interruption recovery", () => {
     vi.clearAllMocks();
     resetCurrentUserSettingsStoreForTests();
     clearForegroundArchiveOperation();
-    authSession.setAuthenticated({ access_token: "fake-token", token_type: "bearer" }, false);
+    authSession.setAuthenticated(createMockAuthToken({ access_token: "fake-token", token_type: "bearer" }), false);
     setupSuccessfulApiMocks(api as unknown as ApiMock);
   });
 
diff --git a/frontend/src/pages/__tests__/FileBrowser-image-viewer.test.tsx b/frontend/src/pages/__tests__/FileBrowser-image-viewer.test.tsx
index 6688a623a..c082bc84e 100644
--- a/frontend/src/pages/__tests__/FileBrowser-image-viewer.test.tsx
+++ b/frontend/src/pages/__tests__/FileBrowser-image-viewer.test.tsx
@@ -6,11 +6,16 @@ import { beforeEach, describe, expect, it, vi } from "vitest";
 import { useCachedImageGallery } from "../../hooks/useCachedImageGallery";
 import apiService from "../../services/api";
 import { authSession } from "../../services/authSession";
+import { createMockConnection } from "../../test/fixtures/connections";
+import { createMockAuthToken } from "../../test/fixtures/users";
+import { requireTestValue } from "../../test/helpers/assertions";
 import { SambeeThemeProvider } from "../../theme/ThemeContext";
 import { FileType } from "../../types";
 import type { ViewerComponentProps } from "../../utils/FileTypeRegistry";
 import FileBrowser from "../FileBrowser";
 
+const FILE_LIST_READY_TIMEOUT_MS = 5000;
+
 const { loadImageBlob, recordFilename } = vi.hoisted(() => ({
   loadImageBlob: vi.fn(),
   recordFilename: vi.fn(),
@@ -115,11 +120,11 @@ describe("Browser - Image View Integration", () => {
     loadImageBlob.mockResolvedValue(new Blob(["image"], { type: "image/jpeg" }));
 
     // Set up authentication
-    authSession.setAuthenticated({ access_token: "fake-token", token_type: "bearer" }, false);
+    authSession.setAuthenticated(createMockAuthToken({ access_token: "fake-token", token_type: "bearer" }), false);
 
     // Mock successful API responses
     mockedApi.getConnections.mockResolvedValue([
-      {
+      createMockConnection({
         id: "conn-1",
         name: "Test Server",
         slug: "test-server-1",
@@ -130,7 +135,7 @@ describe("Browser - Image View Integration", () => {
         username: "user",
         created_at: "2024-01-01T00:00:00Z",
         updated_at: "2024-01-01T00:00:00Z",
-      },
+      }),
     ]);
   });
 
@@ -150,7 +155,7 @@ describe("Browser - Image View Integration", () => {
     });
     mockedApi.getFileInfo.mockResolvedValue({ type: FileType.FILE, mime_type: "image/jpeg", size: 10 } as never);
     const { router } = renderBrowser();
-    fireEvent.click(await screen.findByRole("button", { name: "File: one.jpg" }));
+    fireEvent.click(await screen.findByRole("button", { name: /: one\.jpg$/ }, { timeout: FILE_LIST_READY_TIMEOUT_MS }));
     expect(await screen.findByTestId("image-view")).toHaveAttribute("data-path", "one.jpg");
     await waitFor(() => expect(loadImageBlob).toHaveBeenCalledTimes(2));
     recordFilename.mockClear();
@@ -192,7 +197,7 @@ describe("Browser - Image View Integration", () => {
     });
     mockedApi.getFileInfo.mockResolvedValue({ type: FileType.FILE, mime_type: "image/jpeg", size: 10 } as never);
     const { router } = renderBrowser();
-    fireEvent.click(await screen.findByRole("button", { name: "File: one.jpg" }));
+    fireEvent.click(await screen.findByRole("button", { name: /: one\.jpg$/ }, { timeout: FILE_LIST_READY_TIMEOUT_MS }));
     await screen.findByTestId("image-view");
     await waitFor(() => expect(loadImageBlob).toHaveBeenCalledTimes(2));
     let backNavigation: Promise<void> | undefined;
@@ -241,7 +246,7 @@ describe("Browser - Image View Integration", () => {
     const imageFile = imageButtons[0];
 
     // Click on the image file
-    fireEvent.click(imageFile);
+    fireEvent.click(requireTestValue(imageFile));
 
     // Image view should open
     const view = await screen.findByTestId("image-view");
@@ -338,7 +343,7 @@ describe("Browser - Image View Integration", () => {
     const imageFile = imageButtons[0];
 
     // Click on the image file
-    fireEvent.click(imageFile);
+    fireEvent.click(requireTestValue(imageFile));
 
     // Image view should open
     const view = await screen.findByTestId("image-view");
@@ -372,7 +377,7 @@ describe("Browser - Image View Integration", () => {
     });
     const imageButtons = screen.getAllByRole("button", { name: /photo\.jpg/i });
     const imageFile = imageButtons[0];
-    fireEvent.click(imageFile);
+    fireEvent.click(requireTestValue(imageFile));
 
     // Wait for view to open
     const view = await screen.findByTestId("image-view");
@@ -408,7 +413,7 @@ describe("Browser - Image View Integration", () => {
     const markdownFile = markdownButtons[0];
 
     // Click on the markdown file
-    fireEvent.click(markdownFile);
+    fireEvent.click(requireTestValue(markdownFile));
 
     // Markdown view should open
     const view = await screen.findByTestId("markdown-view");
diff --git a/frontend/src/pages/__tests__/FileBrowser-interactions.test.tsx b/frontend/src/pages/__tests__/FileBrowser-interactions.test.tsx
index 0c33b9525..34df4b4b1 100644
--- a/frontend/src/pages/__tests__/FileBrowser-interactions.test.tsx
+++ b/frontend/src/pages/__tests__/FileBrowser-interactions.test.tsx
@@ -1,3 +1,6 @@
+import { createMockAuthToken } from "../../test/fixtures/users";
+import { requireTestValue } from "../../test/helpers/assertions";
+import { createMockCurrentUserSettings } from "../../test/helpers/mockFactories";
 /**
  * Browser Component - Interactions Tests
  * Tests for keyboard navigation, search/filter, sorting, settings, and refresh
@@ -70,7 +73,7 @@ const regularTransferTestItems = [
 ];
 
 const setupRegularFileTransferListing = () => {
-  vi.mocked(api.listDirectory).mockImplementation((_connectionId, path) =>
+  vi.mocked(api.listDirectory).mockImplementation((_connectionId, path = "") =>
     Promise.resolve(
       path === "" || path === "/"
         ? { path: "", items: regularTransferTestItems, total: regularTransferTestItems.length }
@@ -124,7 +127,7 @@ describe("Browser Component - Interactions", () => {
     vi.mocked(api.copyItem).mockReset();
     vi.mocked(api.moveItem).mockReset();
     resetCurrentUserSettingsStoreForTests();
-    authSession.setAuthenticated({ access_token: "fake-token", token_type: "bearer" }, false);
+    authSession.setAuthenticated(createMockAuthToken({ access_token: "fake-token", token_type: "bearer" }), false);
     localStorage.removeItem("selectedConnectionId");
     localStorage.removeItem(QUICK_NAV_INCLUDE_DOT_DIRECTORIES_STORAGE_KEY);
 
@@ -149,7 +152,7 @@ describe("Browser Component - Interactions", () => {
       renderBrowser("/browse/smb/test-server-1");
       for (const focusReturned of [true, false, true]) {
         hasFocus.mockReturnValue(focusReturned);
-        fireEvent.click(await screen.findByRole("button", { name: "Upload", exact: true }));
+        fireEvent.click(await screen.findByRole("button", { name: "Upload" }));
         fireEvent.click(await screen.findByRole("menuitem", { name: "Files" }));
         if (!focusReturned) expect(pickers).toHaveLength(1);
       }
@@ -181,7 +184,7 @@ describe("Browser Component - Interactions", () => {
       const listContainer = (await screen.findAllByTestId("virtual-list"))[0]!;
       await user.click(listContainer);
       await user.keyboard(" ");
-      fireEvent.click(screen.getByRole("button", { name: "Upload", exact: true }));
+      fireEvent.click(screen.getByRole("button", { name: "Upload" }));
       fireEvent.click(await screen.findByRole("menuitem", { name: "Files" }));
       expect(pickers).toHaveLength(1);
 
@@ -209,7 +212,7 @@ describe("Browser Component - Interactions", () => {
     const listContainer = await screen.findByTestId("virtual-list");
     await user.click(listContainer);
     await user.keyboard(" ");
-    await user.click(screen.getByRole("button", { name: "Download", exact: true }));
+    await user.click(screen.getByRole("button", { name: "Download" }));
 
     expect(await screen.findByText("Preparing download")).toBeInTheDocument();
     const cancel = await screen.findByRole("button", { name: "Cancel" });
@@ -227,7 +230,7 @@ describe("Browser Component - Interactions", () => {
     const listContainer = await screen.findByTestId("virtual-list");
     await user.click(listContainer);
     await user.keyboard(" ");
-    await user.click(screen.getByRole("button", { name: "Download", exact: true }));
+    await user.click(screen.getByRole("button", { name: "Download" }));
 
     await waitFor(() => expect(api.downloadFile).toHaveBeenCalled());
     expect(screen.queryByText("Preparing download")).not.toBeInTheDocument();
@@ -245,7 +248,7 @@ describe("Browser Component - Interactions", () => {
     const listContainer = await screen.findByTestId("virtual-list");
     await user.click(listContainer);
     await user.keyboard(" ");
-    await user.click(screen.getByRole("button", { name: "Download", exact: true }));
+    await user.click(screen.getByRole("button", { name: "Download" }));
 
     expect(await screen.findByText("Preparing archive")).toBeInTheDocument();
     await user.click(screen.getByRole("button", { name: "Cancel" }));
@@ -256,7 +259,7 @@ describe("Browser Component - Interactions", () => {
     const pickerClick = vi.spyOn(HTMLInputElement.prototype, "click").mockImplementation(() => {});
     try {
       renderBrowser("/browse/smb/test-server-1");
-      fireEvent.click(await screen.findByRole("button", { name: "Upload", exact: true }));
+      fireEvent.click(await screen.findByRole("button", { name: "Upload" }));
       fireEvent.click(await screen.findByRole("button", { name: /folder: documents/i, hidden: true }));
       await waitFor(() => expectDirectoryLoad("conn-1", "Documents"));
       fireEvent.click(screen.getByRole("menuitem", { name: "Files" }));
@@ -270,7 +273,7 @@ describe("Browser Component - Interactions", () => {
 
   it("navigates the upload choices by keyboard and restores focus on Escape", async () => {
     renderBrowser("/browse/smb/test-server-1");
-    const trigger = await screen.findByRole("button", { name: "Upload", exact: true });
+    const trigger = await screen.findByRole("button", { name: "Upload" });
     trigger.focus();
     fireEvent.click(trigger);
     const files = await screen.findByRole("menuitem", { name: "Files" });
@@ -302,7 +305,7 @@ describe("Browser Component - Interactions", () => {
     });
     try {
       renderBrowser("/browse/smb/test-server-1");
-      fireEvent.click(await screen.findByRole("button", { name: "Upload", exact: true }));
+      fireEvent.click(await screen.findByRole("button", { name: "Upload" }));
       fireEvent.click(await screen.findByRole("menuitem", { name: "Files" }));
       expect(picker).not.toBeNull();
       fireEvent.click(await screen.findByRole("button", { name: /folder: documents/i }));
@@ -325,7 +328,7 @@ describe("Browser Component - Interactions", () => {
     });
     try {
       renderBrowser("/browse/smb/test-server-1");
-      fireEvent.click(await screen.findByRole("button", { name: "Upload", exact: true }));
+      fireEvent.click(await screen.findByRole("button", { name: "Upload" }));
       fireEvent.click(await screen.findByRole("menuitem", { name: "Folder" }));
 
       expect(await screen.findByText(/did not provide usable folder paths/)).toBeInTheDocument();
@@ -348,7 +351,7 @@ describe("Browser Component - Interactions", () => {
     vi.mocked(api.publishBrowserFile).mockResolvedValue(completedTransferResult);
     try {
       renderBrowser("/browse/smb/test-server-1");
-      fireEvent.click(await screen.findByRole("button", { name: "Upload", exact: true }));
+      fireEvent.click(await screen.findByRole("button", { name: "Upload" }));
       fireEvent.click(await screen.findByRole("menuitem", { name: "Folder" }));
 
       await waitFor(() =>
@@ -389,7 +392,7 @@ describe("Browser Component - Interactions", () => {
     vi.mocked(api.publishBrowserFile).mockResolvedValue(completedTransferResult);
     try {
       renderBrowser("/browse/smb/test-server-1");
-      fireEvent.click(await screen.findByRole("button", { name: "Upload", exact: true }));
+      fireEvent.click(await screen.findByRole("button", { name: "Upload" }));
       fireEvent.click(await screen.findByRole("menuitem", { name: "Folder" }));
 
       await waitFor(() =>
@@ -421,7 +424,7 @@ describe("Browser Component - Interactions", () => {
     vi.mocked(api.publishBrowserFile).mockResolvedValue(completedTransferResult);
     try {
       renderBrowser("/browse/smb/test-server-1");
-      fireEvent.click(await screen.findByRole("button", { name: "Upload", exact: true }));
+      fireEvent.click(await screen.findByRole("button", { name: "Upload" }));
       fireEvent.click(await screen.findByRole("menuitem", { name: "Folder" }));
 
       await waitFor(() =>
@@ -449,7 +452,7 @@ describe("Browser Component - Interactions", () => {
     vi.mocked(api.publishBrowserFile).mockResolvedValue(completedTransferResult);
     try {
       renderBrowser("/browse/smb/test-server-1");
-      fireEvent.click(await screen.findByRole("button", { name: "Upload", exact: true }));
+      fireEvent.click(await screen.findByRole("button", { name: "Upload" }));
       fireEvent.click(await screen.findByRole("menuitem", { name: "Folder" }));
 
       expect(await screen.findByRole("button", { name: "Cancel upload" })).toBeInTheDocument();
@@ -480,7 +483,7 @@ describe("Browser Component - Interactions", () => {
     });
     try {
       renderBrowser("/browse/smb/test-server-1");
-      const trigger = await screen.findByRole("button", { name: "Upload", exact: true });
+      const trigger = await screen.findByRole("button", { name: "Upload" });
       fireEvent.click(trigger);
       fireEvent.click(await screen.findByRole("menuitem", { name: "Folder" }));
       expect(await screen.findByRole("button", { name: "Cancel upload" })).toBeInTheDocument();
@@ -512,7 +515,7 @@ describe("Browser Component - Interactions", () => {
     });
     try {
       renderBrowser("/browse/smb/test-server-1");
-      fireEvent.click(await screen.findByRole("button", { name: "Upload", exact: true }));
+      fireEvent.click(await screen.findByRole("button", { name: "Upload" }));
       fireEvent.click(await screen.findByRole("menuitem", { name: "Folder" }));
 
       expect(await screen.findByText(/Inspect the destination before retrying/)).toBeInTheDocument();
@@ -534,7 +537,7 @@ describe("Browser Component - Interactions", () => {
       .mockResolvedValueOnce(completedTransferResult);
     try {
       renderBrowser("/browse/smb/test-server-1");
-      fireEvent.click(await screen.findByRole("button", { name: "Upload", exact: true }));
+      fireEvent.click(await screen.findByRole("button", { name: "Upload" }));
       fireEvent.click(await screen.findByRole("menuitem", { name: "Files" }));
 
       await waitFor(() => expect(api.publishBrowserFile).toHaveBeenCalledTimes(2));
@@ -597,11 +600,11 @@ describe("Browser Component - Interactions", () => {
     );
     try {
       renderBrowser("/browse/smb/test-server-1");
-      fireEvent.click(await screen.findByRole("button", { name: "Upload", exact: true }));
+      fireEvent.click(await screen.findByRole("button", { name: "Upload" }));
       fireEvent.click(await screen.findByRole("menuitem", { name: "Files" }));
       await waitFor(() => expect(api.publishBrowserFile).toHaveBeenCalledOnce());
       expect(screen.getByText(/Sending/)).toBeInTheDocument();
-      const options = vi.mocked(api.publishBrowserFile).mock.calls[0][4];
+      const options = requireTestValue(vi.mocked(api.publishBrowserFile).mock.calls[0])[4];
       act(() => options?.onProgress?.(3, 5));
       expect(screen.getByText(/3 B \/ 5 B/)).toBeInTheDocument();
       act(() => options?.onProgress?.(5, 5));
@@ -634,7 +637,7 @@ describe("Browser Component - Interactions", () => {
       const rootLoads = () =>
         vi.mocked(api.listDirectory).mock.calls.filter(([connectionId, path]) => connectionId === "conn-1" && path === "").length;
       const initialLoads = rootLoads();
-      fireEvent.click(screen.getByRole("button", { name: "Upload", exact: true }));
+      fireEvent.click(screen.getByRole("button", { name: "Upload" }));
       fireEvent.click(await screen.findByRole("menuitem", { name: "Files" }));
       await waitFor(() => expect(completeUpload).toBeDefined());
       fireEvent.click(screen.getByRole("button", { name: /folder: documents/i }));
@@ -848,7 +851,7 @@ describe("Browser Component - Interactions", () => {
     it("maintains sort preference across navigation", async () => {
       const user = userEvent.setup();
 
-      vi.mocked(api.listDirectory).mockImplementation((_connectionId, path) => {
+      vi.mocked(api.listDirectory).mockImplementation((_connectionId, path = "") => {
         if (path === "Documents") {
           return Promise.resolve({
             items: [
@@ -1138,7 +1141,7 @@ describe("Browser Component - Interactions", () => {
       ).length;
 
       const listContainer = (await screen.findAllByTestId("virtual-list"))[0];
-      await user.click(listContainer);
+      await user.click(requireTestValue(listContainer));
       await user.keyboard(" ");
       await user.keyboard("{F5}");
 
@@ -1173,7 +1176,7 @@ describe("Browser Component - Interactions", () => {
         const nested = { ...regularTransferTestItems[0]!, name: "nested", path: "Documents/nested", type: FileType.DIRECTORY };
         const file = { ...regularTransferTestItems[0]!, name: "report.txt", path: "Documents/nested/report.txt" };
         const secondFile = { ...file, path: "Pictures/report.txt" };
-        vi.mocked(api.listDirectory).mockImplementation(async (connectionId, path) => ({
+        vi.mocked(api.listDirectory).mockImplementation(async (connectionId, path = "") => ({
           path,
           items:
             connectionId === "conn-1"
@@ -1242,7 +1245,7 @@ describe("Browser Component - Interactions", () => {
           await user.click(within(await screen.findByRole("dialog")).getByRole("button", { name: "Move" }));
 
           if (childStatus === "conflict") {
-            await user.click(await screen.findByRole("radio", { name: "Overwrite", exact: true }));
+            await user.click(await screen.findByRole("radio", { name: "Overwrite" }));
             await user.click(screen.getByRole("checkbox", { name: /apply this choice to remaining conflicts/i }));
             await user.click(screen.getByRole("button", { name: "Continue" }));
             await waitFor(() => expect(api.moveItem).toHaveBeenCalledTimes(3));
@@ -1309,13 +1312,13 @@ describe("Browser Component - Interactions", () => {
         const user = userEvent.setup();
         renderBrowser("/browse/smb/test-server-1?p2=smb/test-server-2/Documents");
         const listContainer = (await screen.findAllByTestId("virtual-list"))[0];
-        await user.click(listContainer);
+        await user.click(requireTestValue(listContainer));
         await user.keyboard(" ");
         await user.keyboard("{F5}");
         const dialog = await screen.findByRole("dialog");
         await user.click(within(dialog).getByRole("button", { name: "Copy" }));
         await waitFor(() => expect(api.copyItem).toHaveBeenCalledOnce());
-        const attemptId = vi.mocked(api.copyItem).mock.calls[0][6]?.transferAttemptId;
+        const attemptId = requireTestValue(vi.mocked(api.copyItem).mock.calls[0])[6]?.transferAttemptId;
         expect(attemptId).toMatch(/^[\da-f-]{36}$/);
         const socket = sockets.find((entry) => entry.url.includes("/api/ws"));
         expect(socket).toBeDefined();
@@ -1354,7 +1357,7 @@ describe("Browser Component - Interactions", () => {
       renderBrowser("/browse/smb/test-server-1?p2=smb/test-server-2/Documents");
 
       const [listContainer] = await screen.findAllByTestId("virtual-list");
-      await user.click(listContainer);
+      await user.click(requireTestValue(listContainer));
       await user.keyboard(" ");
       await user.keyboard("{F5}");
       await screen.findByRole("dialog");
@@ -1417,7 +1420,7 @@ describe("Browser Component - Interactions", () => {
       });
 
       const listContainer = (await screen.findAllByTestId("virtual-list"))[0];
-      await user.click(listContainer);
+      await user.click(requireTestValue(listContainer));
       await user.keyboard("{Control>}a{/Control}");
       await user.keyboard("{F5}");
       await user.click(within(await screen.findByRole("dialog")).getByRole("button", { name: "Copy" }));
@@ -1459,7 +1462,7 @@ describe("Browser Component - Interactions", () => {
       });
 
       const listContainer = (await screen.findAllByTestId("virtual-list"))[0];
-      await user.click(listContainer);
+      await user.click(requireTestValue(listContainer));
       await user.keyboard(" ");
       await user.keyboard("{F5}");
       await user.click(within(await screen.findByRole("dialog")).getByRole("button", { name: "Copy" }));
@@ -1513,7 +1516,7 @@ describe("Browser Component - Interactions", () => {
       });
 
       const listContainer = (await screen.findAllByTestId("virtual-list"))[0];
-      await user.click(listContainer);
+      await user.click(requireTestValue(listContainer));
       await user.keyboard(" ");
       await user.keyboard("{F5}");
       await user.click(within(await screen.findByRole("dialog")).getByRole("button", { name: "Copy" }));
@@ -1550,7 +1553,7 @@ describe("Browser Component - Interactions", () => {
       });
 
       const listContainer = (await screen.findAllByTestId("virtual-list"))[0];
-      await user.click(listContainer);
+      await user.click(requireTestValue(listContainer));
       await user.keyboard(" ");
       await user.keyboard("{F6}");
 
@@ -1572,7 +1575,7 @@ describe("Browser Component - Interactions", () => {
       });
 
       const listContainer = (await screen.findAllByTestId("virtual-list"))[0];
-      await user.click(listContainer);
+      await user.click(requireTestValue(listContainer));
       await user.keyboard(" ");
       await user.keyboard("{F5}");
 
@@ -1593,7 +1596,7 @@ describe("Browser Component - Interactions", () => {
       });
 
       const listContainer = (await screen.findAllByTestId("virtual-list"))[0];
-      await user.click(listContainer);
+      await user.click(requireTestValue(listContainer));
 
       const event = createEvent.keyDown(document, { key: "F5" });
       fireEvent(document, event);
@@ -1609,7 +1612,7 @@ describe("Browser Component - Interactions", () => {
       renderBrowser("/browse/smb/test-server-1?p2=smb/test-server-2");
 
       const [listContainer] = await screen.findAllByTestId("file-list-container");
-      listContainer.focus();
+      requireTestValue(listContainer).focus();
 
       const copyEvent = createEvent.keyDown(document, { key: "F5" });
       fireEvent(document, copyEvent);
@@ -1687,7 +1690,7 @@ describe("Browser Component - Interactions", () => {
       });
 
       const listContainer = (await screen.findAllByTestId("virtual-list"))[0];
-      await user.click(listContainer);
+      await user.click(requireTestValue(listContainer));
       await user.keyboard(" ");
       await user.keyboard("{F6}");
 
@@ -1714,20 +1717,24 @@ describe("Browser Component - Interactions", () => {
         ],
         total: 1,
       });
-      vi.mocked(api.getCurrentUserSettings).mockResolvedValue({
-        appearance: { theme_id: "sambee-light", custom_themes: [] },
-        localization: {
-          language: "browser",
-          regional_locale: "browser",
-        },
-        browser: {
-          quick_nav_include_dot_directories: false,
-          file_browser_view_mode: "list",
-          pane_mode: "single",
-          selected_connection_id: null,
-          viewer_associations: {},
-        },
-      });
+      vi.mocked(api.getCurrentUserSettings).mockResolvedValue(
+        createMockCurrentUserSettings({
+          appearance: { theme_id: "sambee-light", custom_themes: [] },
+          localization: {
+            language: "browser",
+            regional_locale: "browser",
+          },
+          browser: {
+            touch_friendly_file_selection: "auto",
+            quick_bar_shortcut_hint_visibility: "auto",
+            quick_nav_include_dot_directories: false,
+            file_browser_view_mode: "list",
+            pane_mode: "single",
+            selected_connection_id: null,
+            viewer_associations: {},
+          },
+        })
+      );
 
       renderBrowser("/browse/smb/test-server-1");
 
@@ -1801,20 +1808,24 @@ describe("Browser Component - Interactions", () => {
         ],
         total: 1,
       });
-      vi.mocked(api.getCurrentUserSettings).mockResolvedValue({
-        appearance: { theme_id: "sambee-light", custom_themes: [] },
-        localization: {
-          language: "browser",
-          regional_locale: "browser",
-        },
-        browser: {
-          quick_nav_include_dot_directories: false,
-          file_browser_view_mode: "list",
-          pane_mode: "single",
-          selected_connection_id: null,
-          viewer_associations: { "mime:application/pdf": "pdf" },
-        },
-      });
+      vi.mocked(api.getCurrentUserSettings).mockResolvedValue(
+        createMockCurrentUserSettings({
+          appearance: { theme_id: "sambee-light", custom_themes: [] },
+          localization: {
+            language: "browser",
+            regional_locale: "browser",
+          },
+          browser: {
+            touch_friendly_file_selection: "auto",
+            quick_bar_shortcut_hint_visibility: "auto",
+            quick_nav_include_dot_directories: false,
+            file_browser_view_mode: "list",
+            pane_mode: "single",
+            selected_connection_id: null,
+            viewer_associations: { "mime:application/pdf": "pdf" },
+          },
+        })
+      );
 
       renderBrowser("/browse/smb/test-server-1");
 
@@ -1948,7 +1959,7 @@ describe("Browser Component - Interactions", () => {
         archive: { path: "temp.zip", size: 102400 },
         path: "",
         items: [{ name: "inside.txt", path: "inside.txt", type: FileType.FILE, state: "readable", is_hidden: false }],
-        total: 1,
+
         page_size: 100,
       });
 
@@ -1990,7 +2001,7 @@ describe("Browser Component - Interactions", () => {
         archive: { path: "temp.zip", size: 102400 },
         path: "",
         items: [{ name: "inside.txt", path: "inside.txt", type: FileType.FILE, state: "readable", is_hidden: false }],
-        total: 1,
+
         page_size: 100,
       });
 
@@ -2049,7 +2060,7 @@ describe("Browser Component - Interactions", () => {
       renderBrowser("/browse/smb/test-server-1?p2=smb/test-server-2");
 
       const [listContainer] = await screen.findAllByTestId("file-list-container");
-      listContainer.focus();
+      requireTestValue(listContainer).focus();
       fireEvent.keyDown(document, { key: "F9", altKey: true });
       expect(screen.queryByRole("dialog", { name: "Extract from ZIP Archive" })).not.toBeInTheDocument();
 
@@ -2075,7 +2086,7 @@ describe("Browser Component - Interactions", () => {
       renderBrowser("/browse/smb/test-server-1?p2=smb/test-server-2");
 
       const [listContainer] = await screen.findAllByTestId("virtual-list");
-      await user.click(listContainer);
+      await user.click(requireTestValue(listContainer));
       await user.keyboard(" ");
       await user.keyboard("{Alt>}{F5}{/Alt}");
       await screen.findByRole("dialog", { name: "Create ZIP Archive" });
@@ -2113,7 +2124,7 @@ describe("Browser Component - Interactions", () => {
         archive: { path: "archive.zip", size: 1 },
         path: "",
         items: [{ name: "inside.txt", path: "inside.txt", type: FileType.FILE, state: "readable", is_hidden: false }],
-        total: 1,
+
         page_size: 100,
       });
       vi.mocked(api.prepareArchiveOperation).mockResolvedValueOnce({ id: "extract-selected" } as never);
@@ -2153,7 +2164,7 @@ describe("Browser Component - Interactions", () => {
         archive: { path: "archive.zip", size: 1 },
         path: "",
         items: [{ name: "inside.txt", path: "inside.txt", type: FileType.FILE, state: "readable", is_hidden: false }],
-        total: 1,
+
         page_size: 100,
       });
       renderBrowser("/browse/smb/test-server-1?p2=smb/test-server-2/archive.zip&active=2");
@@ -2177,7 +2188,7 @@ describe("Browser Component - Interactions", () => {
         archive: { path: "archive.zip", size: 1 },
         path: "",
         items: [{ name: "inside.txt", path: "inside.txt", type: FileType.FILE, state: "readable", is_hidden: false }],
-        total: 1,
+
         page_size: 100,
       });
       vi.mocked(api.prepareArchiveOperation).mockResolvedValueOnce({ id: "extract-cancelled" } as never);
@@ -2216,23 +2227,27 @@ describe("Browser Component - Interactions", () => {
         ],
         total: 1,
       });
-      vi.mocked(api.getCurrentUserSettings).mockResolvedValue({
-        appearance: { theme_id: "sambee-light", custom_themes: [] },
-        localization: {
-          language: "browser",
-          regional_locale: "browser",
-        },
-        browser: {
-          quick_nav_include_dot_directories: false,
-          file_browser_view_mode: "list",
-          pane_mode: "single",
-          selected_connection_id: null,
-          viewer_associations: {
-            "mime:application/pdf": "markdown",
-            "ext:.pdf": "markdown",
+      vi.mocked(api.getCurrentUserSettings).mockResolvedValue(
+        createMockCurrentUserSettings({
+          appearance: { theme_id: "sambee-light", custom_themes: [] },
+          localization: {
+            language: "browser",
+            regional_locale: "browser",
           },
-        },
-      });
+          browser: {
+            touch_friendly_file_selection: "auto",
+            quick_bar_shortcut_hint_visibility: "auto",
+            quick_nav_include_dot_directories: false,
+            file_browser_view_mode: "list",
+            pane_mode: "single",
+            selected_connection_id: null,
+            viewer_associations: {
+              "mime:application/pdf": "markdown",
+              "ext:.pdf": "markdown",
+            },
+          },
+        })
+      );
 
       renderBrowser("/browse/smb/test-server-1");
 
@@ -2816,7 +2831,7 @@ describe("Browser Component - Interactions", () => {
         };
       });
 
-      vi.mocked(api.listDirectory).mockImplementation(async (connectionId, path) => {
+      vi.mocked(api.listDirectory).mockImplementation(async (connectionId, path = "") => {
         if (connectionId === "conn-2" && path === "RightTarget") {
           return {
             items: [],
@@ -2871,20 +2886,24 @@ describe("Browser Component - Interactions", () => {
       const user = userEvent.setup();
 
       localStorage.setItem(QUICK_NAV_INCLUDE_DOT_DIRECTORIES_STORAGE_KEY, "true");
-      vi.mocked(api.getCurrentUserSettings).mockResolvedValue({
-        appearance: { theme_id: "sambee-light", custom_themes: [] },
-        localization: {
-          language: "browser",
-          regional_locale: "browser",
-        },
-        browser: {
-          quick_nav_include_dot_directories: true,
-          file_browser_view_mode: "list",
-          pane_mode: "single",
-          selected_connection_id: null,
-          viewer_associations: {},
-        },
-      });
+      vi.mocked(api.getCurrentUserSettings).mockResolvedValue(
+        createMockCurrentUserSettings({
+          appearance: { theme_id: "sambee-light", custom_themes: [] },
+          localization: {
+            language: "browser",
+            regional_locale: "browser",
+          },
+          browser: {
+            touch_friendly_file_selection: "auto",
+            quick_bar_shortcut_hint_visibility: "auto",
+            quick_nav_include_dot_directories: true,
+            file_browser_view_mode: "list",
+            pane_mode: "single",
+            selected_connection_id: null,
+            viewer_associations: {},
+          },
+        })
+      );
 
       renderBrowser("/browse/smb/test-server-1");
 
@@ -3067,7 +3086,7 @@ describe("Browser Component - Interactions", () => {
       const user = userEvent.setup();
 
       // Start in a subdirectory
-      vi.mocked(api.listDirectory).mockImplementation((_connectionId, path) => {
+      vi.mocked(api.listDirectory).mockImplementation((_connectionId, path = "") => {
         if (path === "Documents") {
           return Promise.resolve({
             items: [
@@ -3107,7 +3126,7 @@ describe("Browser Component - Interactions", () => {
     it("does not navigate to parent when Backspace is pressed in an empty commands quick bar", async () => {
       const user = userEvent.setup();
 
-      vi.mocked(api.listDirectory).mockImplementation((_connectionId, path) => {
+      vi.mocked(api.listDirectory).mockImplementation((_connectionId, path = "") => {
         if (path === "Documents") {
           return Promise.resolve({
             items: [
@@ -3538,7 +3557,7 @@ describe("Browser Component - Interactions", () => {
       const downloadBlob = vi.spyOn(viewerContent, "downloadViewerBlob").mockImplementation(() => {});
 
       try {
-        vi.mocked(api.listDirectory).mockImplementation(async (_connectionId, path) => ({
+        vi.mocked(api.listDirectory).mockImplementation(async (_connectionId, path = "") => ({
           path,
           items: path
             ? []
@@ -3682,7 +3701,7 @@ describe("Browser Component - Interactions", () => {
           path: `file-${index}.txt`,
           size: index === 0 ? 200 * 1024 * 1024 : undefined,
         }));
-        vi.mocked(api.listDirectory).mockImplementation(async (_connectionId, path) => ({
+        vi.mocked(api.listDirectory).mockImplementation(async (_connectionId, path = "") => ({
           path,
           items: path ? [] : items,
           total: path ? 0 : items.length,
@@ -3782,7 +3801,7 @@ describe("Browser Component - Interactions", () => {
       const { share, restore } = setupCompactNativeShare();
 
       try {
-        vi.mocked(api.listDirectory).mockImplementation(async (_connectionId, path) => ({
+        vi.mocked(api.listDirectory).mockImplementation(async (_connectionId, path = "") => ({
           path,
           items: path ? [] : [{ ...regularTransferTestItems[0]!, type: FileType.DIRECTORY }, regularTransferTestItems[1]!],
           total: path ? 0 : 2,
@@ -3804,7 +3823,9 @@ describe("Browser Component - Interactions", () => {
         vi.mocked(api.getOriginalFileBlob).mockImplementation(
           (_connectionId, _path, options) =>
             new Promise((_resolve, reject) =>
-              options.signal?.addEventListener("abort", () => reject(new DOMException("Cancelled", "AbortError")), { once: true })
+              requireTestValue(options).signal?.addEventListener("abort", () => reject(new DOMException("Cancelled", "AbortError")), {
+                once: true,
+              })
             )
         );
         await user.click(screen.getByRole("button", { name: "More actions for Pictures" }));
diff --git a/frontend/src/pages/__tests__/FileBrowser-navigation.test.tsx b/frontend/src/pages/__tests__/FileBrowser-navigation.test.tsx
index ffd629e0b..5575ae0ae 100644
--- a/frontend/src/pages/__tests__/FileBrowser-navigation.test.tsx
+++ b/frontend/src/pages/__tests__/FileBrowser-navigation.test.tsx
@@ -1,3 +1,5 @@
+import { createMockAuthToken } from "../../test/fixtures/users";
+import { requireTestValue, uninitializedTestCallback } from "../../test/helpers/assertions";
 /**
  * Browser Component - Navigation Tests
  * Tests for directory navigation, breadcrumbs, URL handling, and connection switching
@@ -9,6 +11,7 @@ import { beforeEach, describe, expect, it, vi } from "vitest";
 import api from "../../services/api";
 import { authSession } from "../../services/authSession";
 import { type ApiMock, createMarkdownViewerMock, createSettingsDialogMock, setupNavigationApiMocks } from "../../test/helpers";
+import { createMockCurrentUserSettings } from "../../test/helpers/mockFactories";
 import type { FileInfo } from "../../types";
 import { FileType } from "../../types";
 import { mockDirectoryListing, renderBrowser } from "./FileBrowser.test.utils";
@@ -27,7 +30,7 @@ const createDirectoryEntry = (name: string, path: string): FileInfo => ({
   name,
   path,
   type: FileType.DIRECTORY,
-  size: null,
+  size: undefined,
   modified_at: "2024-01-12T10:00:00Z",
   is_readable: true,
   is_hidden: false,
@@ -55,7 +58,7 @@ vi.mock("@tanstack/react-virtual", () => import("../../__mocks__/@tanstack/react
 describe("Browser Component - Navigation", () => {
   beforeEach(() => {
     vi.clearAllMocks();
-    authSession.setAuthenticated({ access_token: "fake-token", token_type: "bearer" }, false);
+    authSession.setAuthenticated(createMockAuthToken({ access_token: "fake-token", token_type: "bearer" }), false);
     localStorage.removeItem("selectedConnectionId");
 
     // Use navigation mock factory for directory navigation tests
@@ -101,7 +104,7 @@ describe("Browser Component - Navigation", () => {
 
     // Click on Documents folder - get the button role to be more specific
     const documentsFolders = screen.getAllByRole("button", { name: /documents/i });
-    await user.click(documentsFolders[0]);
+    await user.click(requireTestValue(documentsFolders[0]));
 
     // Should load files from Documents directory
     await waitFor(() => {
@@ -245,7 +248,7 @@ describe("Browser Component - Navigation", () => {
       },
     ];
 
-    let resolveSubfolder: ((value: { items: FileInfo[]; path: string; total: number }) => void) | null = null;
+    let resolveSubfolder: (value: { items: FileInfo[]; path: string; total: number }) => void = uninitializedTestCallback;
 
     vi.mocked(api.listDirectory).mockImplementation(async (_connectionId, path) => {
       if (path === "Documents") {
@@ -262,7 +265,7 @@ describe("Browser Component - Navigation", () => {
     expect(await screen.findByText("readme.txt")).toBeInTheDocument();
 
     const documentsFolders = screen.getAllByRole("button", { name: /documents/i });
-    await user.click(documentsFolders[0]);
+    await user.click(requireTestValue(documentsFolders[0]));
 
     await waitFor(() => {
       expectDirectoryLoad("conn-1", "Documents");
@@ -353,20 +356,24 @@ describe("Browser Component - Navigation", () => {
   });
 
   it("uses the persisted user setting for the default connection when no URL param", async () => {
-    vi.mocked(api.getCurrentUserSettings).mockResolvedValue({
-      appearance: { theme_id: "sambee-light", custom_themes: [] },
-      localization: {
-        language: "browser",
-        regional_locale: "browser",
-      },
-      browser: {
-        quick_nav_include_dot_directories: false,
-        file_browser_view_mode: "list",
-        pane_mode: "single",
-        selected_connection_id: "conn-1",
-        viewer_associations: {},
-      },
-    });
+    vi.mocked(api.getCurrentUserSettings).mockResolvedValue(
+      createMockCurrentUserSettings({
+        appearance: { theme_id: "sambee-light", custom_themes: [] },
+        localization: {
+          language: "browser",
+          regional_locale: "browser",
+        },
+        browser: {
+          quick_bar_shortcut_hint_visibility: "auto",
+          touch_friendly_file_selection: "auto",
+          quick_nav_include_dot_directories: false,
+          file_browser_view_mode: "list",
+          pane_mode: "single",
+          selected_connection_id: "conn-1",
+          viewer_associations: {},
+        },
+      })
+    );
 
     renderBrowser("/browse");
 
@@ -431,8 +438,8 @@ describe("Browser Component - Navigation", () => {
   it("ignores stale directory responses after switching connections", async () => {
     const user = userEvent.setup();
 
-    let resolveConn1: ((value: typeof mockDirectoryListing) => void) | null = null;
-    let resolveConn2: ((value: { items: FileInfo[]; path: string; total: number }) => void) | null = null;
+    let resolveConn1: (value: typeof mockDirectoryListing) => void = uninitializedTestCallback;
+    let resolveConn2: (value: { items: FileInfo[]; path: string; total: number }) => void = uninitializedTestCallback;
 
     const conn2Files: FileInfo[] = [
       {
diff --git a/frontend/src/pages/__tests__/FileBrowser-pdf-viewer.test.tsx b/frontend/src/pages/__tests__/FileBrowser-pdf-viewer.test.tsx
index 7a75a7d76..de1df3d1a 100644
--- a/frontend/src/pages/__tests__/FileBrowser-pdf-viewer.test.tsx
+++ b/frontend/src/pages/__tests__/FileBrowser-pdf-viewer.test.tsx
@@ -1,3 +1,6 @@
+import { createMockConnection } from "../../test/fixtures/connections";
+import { createMockAuthToken } from "../../test/fixtures/users";
+import { requireTestValue } from "../../test/helpers/assertions";
 /**
  * Browser Component - PDF Viewer Integration Tests
  * Tests for PDF file viewing workflows
@@ -15,6 +18,8 @@ import { SambeeThemeProvider } from "../../theme/ThemeContext";
 import { FileType } from "../../types";
 import FileBrowser from "../FileBrowser";
 
+const FILE_LIST_READY_TIMEOUT_MS = 5000;
+
 // Mock the API service
 vi.mock("../../services/api");
 const mockedApi = apiService as MockedObject<typeof apiService>;
@@ -86,13 +91,16 @@ vi.mock("react-pdf", () => ({
  * Handles the case where filename appears in both file list and status bar
  */
 async function getFileButton(filename: string): Promise<HTMLElement> {
-  await waitFor(() => {
-    const elements = screen.getAllByText(filename);
-    expect(elements.length).toBeGreaterThan(0);
-  });
+  await waitFor(
+    () => {
+      const elements = screen.getAllByText(filename);
+      expect(elements.length).toBeGreaterThan(0);
+    },
+    { timeout: FILE_LIST_READY_TIMEOUT_MS }
+  );
   // Get the button that contains the filename (file list, not status bar)
   const buttons = screen.getAllByRole("button", { name: new RegExp(filename, "i") });
-  return buttons[0];
+  return requireTestValue(buttons[0]);
 }
 
 // Mock ResizeObserver
@@ -160,11 +168,11 @@ describe("Browser - PDF Viewer Integration", () => {
     vi.clearAllMocks();
 
     // Set up authentication
-    authSession.setAuthenticated({ access_token: "fake-token", token_type: "bearer" }, false);
+    authSession.setAuthenticated(createMockAuthToken({ access_token: "fake-token", token_type: "bearer" }), false);
 
     // Mock successful API responses
     mockedApi.getConnections.mockResolvedValue([
-      {
+      createMockConnection({
         id: "conn-1",
         name: "Test Server",
         slug: "test-server-1",
@@ -175,7 +183,7 @@ describe("Browser - PDF Viewer Integration", () => {
         username: "user",
         created_at: "2024-01-01T00:00:00Z",
         updated_at: "2024-01-01T00:00:00Z",
-      },
+      }),
     ]);
 
     // Mock PDF blob response
diff --git a/frontend/src/pages/__tests__/FileBrowser-rendering.test.tsx b/frontend/src/pages/__tests__/FileBrowser-rendering.test.tsx
index bb88977eb..b6e8cb3f3 100644
--- a/frontend/src/pages/__tests__/FileBrowser-rendering.test.tsx
+++ b/frontend/src/pages/__tests__/FileBrowser-rendering.test.tsx
@@ -1,3 +1,4 @@
+import { createMockAuthToken } from "../../test/fixtures/users";
 /**
  * Browser Component - Rendering Tests
  * Tests for basic rendering, loading states, errors, and empty states
@@ -46,7 +47,7 @@ describe("Browser Component - Rendering", () => {
   beforeEach(() => {
     vi.clearAllMocks();
     resetBackendAvailabilityForTests();
-    authSession.setAuthenticated({ access_token: "fake-token", token_type: "bearer" }, false);
+    authSession.setAuthenticated(createMockAuthToken({ access_token: "fake-token", token_type: "bearer" }), false);
     localStorage.removeItem("selectedConnectionId");
     sessionStorage.clear();
 
diff --git a/frontend/src/pages/__tests__/FileBrowser-url-routing.test.tsx b/frontend/src/pages/__tests__/FileBrowser-url-routing.test.tsx
index edafc0ca8..d59926f6f 100644
--- a/frontend/src/pages/__tests__/FileBrowser-url-routing.test.tsx
+++ b/frontend/src/pages/__tests__/FileBrowser-url-routing.test.tsx
@@ -1,3 +1,4 @@
+import { createMockAuthToken } from "../../test/fixtures/users";
 /**
  * FileBrowser — URL Routing Tests (Phase 3)
  * ==========================================
@@ -97,7 +98,7 @@ describe("FileBrowser — URL Routing (Phase 3)", () => {
   afterEach(() => vi.unstubAllGlobals());
   beforeEach(() => {
     vi.clearAllMocks();
-    authSession.setAuthenticated({ access_token: "fake-token", token_type: "bearer" }, false);
+    authSession.setAuthenticated(createMockAuthToken({ access_token: "fake-token", token_type: "bearer" }), false);
     localStorage.removeItem("selectedConnectionId");
     localStorage.removeItem("dual-pane-mode");
     localStorage.removeItem("active-pane");
@@ -499,7 +500,7 @@ describe("FileBrowser — URL Routing (Phase 3)", () => {
     });
 
     it("serializes archive navigation and restores a virtual archive deep link", async () => {
-      vi.mocked(api.listDirectory).mockImplementation(async (_connectionId, path) => ({
+      vi.mocked(api.listDirectory).mockImplementation(async (_connectionId, path = "") => ({
         path,
         items:
           path === "Archives"
@@ -515,7 +516,7 @@ describe("FileBrowser — URL Routing (Phase 3)", () => {
             : [],
         total: path === "Archives" ? 1 : 0,
       }));
-      vi.mocked(api.listArchiveDirectory).mockImplementation(async (_connectionId, archivePath, virtualPath) => ({
+      vi.mocked(api.listArchiveDirectory).mockImplementation(async (_connectionId, archivePath, virtualPath = "") => ({
         archive: { path: archivePath, size: 1 },
         path: virtualPath,
         items:
@@ -553,7 +554,7 @@ describe("FileBrowser — URL Routing (Phase 3)", () => {
     });
 
     it("hydrates an archive deep link through its virtual provider", async () => {
-      vi.mocked(api.listArchiveDirectory).mockImplementation(async (_connectionId, archivePath, virtualPath) => ({
+      vi.mocked(api.listArchiveDirectory).mockImplementation(async (_connectionId, archivePath, virtualPath = "") => ({
         archive: { path: archivePath, size: 1 },
         path: virtualPath,
         items:
diff --git a/frontend/src/pages/__tests__/FileBrowser-viewer.test.tsx b/frontend/src/pages/__tests__/FileBrowser-viewer.test.tsx
index 6bc9890d2..e2732a40a 100644
--- a/frontend/src/pages/__tests__/FileBrowser-viewer.test.tsx
+++ b/frontend/src/pages/__tests__/FileBrowser-viewer.test.tsx
@@ -1,3 +1,5 @@
+import { createMockAuthToken } from "../../test/fixtures/users";
+import { requireTestValue } from "../../test/helpers/assertions";
 /**
  * Browser Component - View and Advanced Tests
  * Tests for file view, connection switching, and edge cases
@@ -34,7 +36,7 @@ vi.mock("@tanstack/react-virtual", () => import("../../__mocks__/@tanstack/react
 describe("Browser Component - View and Advanced", () => {
   beforeEach(() => {
     vi.clearAllMocks();
-    authSession.setAuthenticated({ access_token: "fake-token", token_type: "bearer" }, false);
+    authSession.setAuthenticated(createMockAuthToken({ access_token: "fake-token", token_type: "bearer" }), false);
     localStorage.removeItem("selectedConnectionId");
 
     // Use mock factory for successful API responses
@@ -234,9 +236,9 @@ describe("Browser Component - View and Advanced", () => {
       const documentsFolder = documentsFolders[0]; // Use first Documents button
 
       // Click multiple times rapidly
-      await user.click(documentsFolder);
-      await user.click(documentsFolder);
-      await user.click(documentsFolder);
+      await user.click(requireTestValue(documentsFolder));
+      await user.click(requireTestValue(documentsFolder));
+      await user.click(requireTestValue(documentsFolder));
 
       // Should handle gracefully - at least one Documents should exist
       const documentsElements = screen.getAllByText("Documents");
diff --git a/frontend/src/pages/__tests__/FileBrowser-websocket-behavior.test.tsx b/frontend/src/pages/__tests__/FileBrowser-websocket-behavior.test.tsx
index d26bdf994..edb2aac2f 100644
--- a/frontend/src/pages/__tests__/FileBrowser-websocket-behavior.test.tsx
+++ b/frontend/src/pages/__tests__/FileBrowser-websocket-behavior.test.tsx
@@ -8,7 +8,9 @@ import api from "../../services/api";
 import { authSession } from "../../services/authSession";
 import { getBackendAvailabilitySnapshot, resetBackendAvailabilityForTests } from "../../services/backendAvailability";
 import { logger } from "../../services/logger";
+import { createMockAuthToken } from "../../test/fixtures/users";
 import { type ApiMock, setupSuccessfulApiMocks } from "../../test/helpers";
+import { requireTestValue } from "../../test/helpers/assertions";
 import { SambeeThemeProvider } from "../../theme/ThemeContext";
 import FileBrowser from "../FileBrowser";
 
@@ -107,8 +109,9 @@ function renderBrowserWithNavigator(initialPath: string) {
         throw new Error("navigate function was not initialized");
       }
 
+      const navigate = navigateFn;
       act(() => {
-        navigateFn(path);
+        navigate(path);
       });
     },
   };
@@ -127,7 +130,7 @@ describe("FileBrowser WebSocket behavior", () => {
   beforeEach(() => {
     vi.clearAllMocks();
     resetBackendAvailabilityForTests();
-    authSession.setAuthenticated({ access_token: "fake-token", token_type: "bearer" }, false);
+    authSession.setAuthenticated(createMockAuthToken({ access_token: "fake-token", token_type: "bearer" }), false);
     InspectableWebSocket.instances = [];
     Object.defineProperty(globalThis, "WebSocket", {
       configurable: true,
@@ -245,7 +248,7 @@ describe("FileBrowser WebSocket behavior", () => {
       await waitFor(() => expect(api.listDirectory).toHaveBeenCalledTimes(1));
       const backendSocket = InspectableWebSocket.instances.find(isServerSocket);
       backendSocket?.open();
-      fireEvent.click(screen.getByRole("button", { name: "Upload", exact: true }));
+      fireEvent.click(screen.getByRole("button", { name: "Upload" }));
       fireEvent.click(await screen.findByRole("menuitem", { name: "Files" }));
       await waitFor(() => expect(finishUpload).toBeDefined());
 
@@ -275,7 +278,7 @@ describe("FileBrowser WebSocket behavior", () => {
     vi.mocked(api.publishBrowserFile).mockImplementation(
       (_file, _connectionId, _path, _policy, options) =>
         new Promise((resolve) => {
-          options.signal?.addEventListener(
+          requireTestValue(options).signal?.addEventListener(
             "abort",
             () => resolve({ status: "cancelled", replaced: false, effects: { source: "unchanged", destination: "unchanged" } }),
             { once: true }
@@ -293,7 +296,7 @@ describe("FileBrowser WebSocket behavior", () => {
       await waitFor(() => expect(api.listDirectory).toHaveBeenCalledTimes(1));
       const backendSocket = InspectableWebSocket.instances.find(isServerSocket);
       backendSocket?.open();
-      fireEvent.click(screen.getByRole("button", { name: "Upload", exact: true }));
+      fireEvent.click(screen.getByRole("button", { name: "Upload" }));
       fireEvent.click(await screen.findByRole("menuitem", { name: "Files" }));
       await waitFor(() => expect(api.publishBrowserFile).toHaveBeenCalledOnce());
 
@@ -303,7 +306,7 @@ describe("FileBrowser WebSocket behavior", () => {
         );
       });
       expect(api.listDirectory).toHaveBeenCalledTimes(1);
-      fireEvent.click(await screen.findByRole("button", { name: "Cancel", exact: true }));
+      fireEvent.click(await screen.findByRole("button", { name: "Cancel" }));
       await waitFor(() => expect(api.listDirectory).toHaveBeenCalledTimes(2));
     } finally {
       pickerClick.mockRestore();
diff --git a/frontend/src/pages/__tests__/FileBrowserPane.test.tsx b/frontend/src/pages/__tests__/FileBrowserPane.test.tsx
index 35b19ada7..eeb3c4b4a 100644
--- a/frontend/src/pages/__tests__/FileBrowserPane.test.tsx
+++ b/frontend/src/pages/__tests__/FileBrowserPane.test.tsx
@@ -26,6 +26,7 @@ import { beforeEach, describe, expect, it, vi } from "vitest";
 import { createMockConnection } from "../../test/fixtures/connections";
 import type { Connection, FileEntry } from "../../types";
 import { FileType } from "../../types";
+import { physicalLocation } from "../FileBrowser/contentProviders";
 import { FileBrowserPane, type FileBrowserPaneProps } from "../FileBrowser/FileBrowserPane";
 import type { UseFileBrowserPaneReturn } from "../FileBrowser/types";
 
@@ -105,7 +106,7 @@ vi.mock("@tanstack/react-virtual", () => import("../../__mocks__/@tanstack/react
 
 const TEST_CONNECTION_ID = "conn-1";
 
-const testConnections: Connection[] = [
+const testConnections: [Connection, Connection] = [
   createMockConnection({ id: TEST_CONNECTION_ID, name: "My NAS" }),
   createMockConnection({ id: "conn-2", name: "Backup Server" }),
 ];
@@ -141,6 +142,21 @@ function createMockPane(overrides: Partial<UseFileBrowserPaneReturn> = {}): UseF
     connectionId: TEST_CONNECTION_ID,
     setConnectionId: vi.fn(),
     currentPath: "some/path",
+    currentLocation: physicalLocation(TEST_CONNECTION_ID, "some/path"),
+    contentCapabilities: { browse: true, read: true, download: true, extract: true, mutate: true, openInNativeApp: true },
+    companionPairingError: null,
+    removeSelectedPaths: vi.fn(),
+    selectItem: vi.fn(),
+    toggleItemSelection: vi.fn(),
+    selectItemFromIcon: vi.fn(),
+    getItemsByPaths: vi.fn().mockReturnValue([]),
+    handleOpenFileAtPath: vi.fn().mockResolvedValue(undefined),
+    navigateToPath: vi.fn(),
+    handleDeleteForFile: vi.fn(),
+    seedDirectorySnapshot: vi.fn(),
+    applyLocation: vi.fn(),
+    captureRecoverySnapshot: vi.fn().mockReturnValue(null),
+    restoreRecoverySnapshot: vi.fn(),
     setCurrentPath: vi.fn(),
     archiveLocation: null,
     archiveHasMore: false,
@@ -189,7 +205,7 @@ function createMockPane(overrides: Partial<UseFileBrowserPaneReturn> = {}): UseF
 
     // Dialog state
     deleteDialogOpen: false,
-    deleteTarget: null,
+    deleteTargets: [],
     isDeleting: false,
     renameDialogOpen: false,
     renameTarget: null,
@@ -287,6 +303,7 @@ function defaultProps(overrides: Partial<FileBrowserPaneProps> = {}): FileBrowse
     useCompactLayout: false,
     isUsingKeyboard: false,
     onPaneFocus: vi.fn(),
+    searchProvider: createMockPane().directorySearchProvider,
     ...overrides,
   };
 }
@@ -374,7 +391,7 @@ describe("FileBrowserPane", () => {
 
     it("renders an archive location in the existing breadcrumb trail", () => {
       const pane = createMockPane({
-        archiveLocation: { archivePath: "some/path/backup.zip", virtualPath: "nested" },
+        archiveLocation: { providerId: "zip", archivePath: "some/path/backup.zip", virtualPath: "nested" },
       });
       render(<FileBrowserPane {...defaultProps({ pane })} />);
 
diff --git a/frontend/src/pages/__tests__/Login.test.tsx b/frontend/src/pages/__tests__/Login.test.tsx
index 8f9dba402..c00aed1a4 100644
--- a/frontend/src/pages/__tests__/Login.test.tsx
+++ b/frontend/src/pages/__tests__/Login.test.tsx
@@ -4,7 +4,9 @@ import { MemoryRouter, Route, Routes, useLocation } from "react-router-dom";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { authSession } from "../../services/authSession";
 import { OIDC_ATTEMPT_MARKER, OIDC_LOGIN_CHANNEL, OIDC_LOGOUT_MARKER } from "../../services/oidcAuth";
+import { createMockAuthToken } from "../../test/fixtures/users";
 import { render } from "../../test/utils/test-utils";
+import type { AuthToken } from "../../types";
 import Login from "../Login";
 
 // Mock the entire API module
@@ -90,7 +92,9 @@ describe("Login Component", () => {
 
   it.each(["/browse/smb/demo", "/settings/appearance"])("recovers the tab's own destination %s after another OIDC login", async (path) => {
     vi.stubGlobal("BroadcastChannel", LoginChannel);
-    vi.spyOn(authSession, "requestRefresh").mockResolvedValue({ access_token: "restored-token", token_type: "bearer" });
+    vi.spyOn(authSession, "requestRefresh").mockResolvedValue(
+      createMockAuthToken({ access_token: "restored-token", token_type: "bearer" })
+    );
     vi.mocked(mockGetAuthConfig).mockResolvedValue({
       sign_in_mode: "oidc_or_password",
       oidc: { display_name: "Example Identity", authorization_path: "/api/auth/oidc/authorize" },
@@ -120,7 +124,7 @@ describe("Login Component", () => {
     const refresh = vi
       .spyOn(authSession, "requestRefresh")
       .mockRejectedValueOnce(new Error("No browser session"))
-      .mockResolvedValueOnce({ access_token: "restored-token", token_type: "bearer" });
+      .mockResolvedValueOnce(createMockAuthToken({ access_token: "restored-token", token_type: "bearer" }));
     vi.mocked(mockGetAuthConfig).mockResolvedValue({
       sign_in_mode: "oidc_or_password",
       oidc: { display_name: "Example Identity", authorization_path: "/api/auth/oidc/authorize" },
@@ -146,7 +150,9 @@ describe("Login Component", () => {
 
   it("recovers on focus when BroadcastChannel is unavailable", async () => {
     vi.stubGlobal("BroadcastChannel", undefined);
-    const refresh = vi.spyOn(authSession, "requestRefresh").mockResolvedValue({ access_token: "restored-token", token_type: "bearer" });
+    const refresh = vi
+      .spyOn(authSession, "requestRefresh")
+      .mockResolvedValue(createMockAuthToken({ access_token: "restored-token", token_type: "bearer" }));
     vi.mocked(mockGetAuthConfig).mockResolvedValue({
       sign_in_mode: "oidc_or_password",
       oidc: { display_name: "Example Identity", authorization_path: "/api/auth/oidc/authorize" },
@@ -203,8 +209,8 @@ describe("Login Component", () => {
 
   it("lets a login hint supersede a pending focus refresh", async () => {
     vi.stubGlobal("BroadcastChannel", LoginChannel);
-    let finishFocus!: (response: { access_token: string; token_type: string }) => void;
-    let finishHint!: (response: { access_token: string; token_type: string }) => void;
+    let finishFocus!: (response: AuthToken) => void;
+    let finishHint!: (response: AuthToken) => void;
     const refresh = vi
       .spyOn(authSession, "requestRefresh")
       .mockReturnValueOnce(
@@ -236,15 +242,15 @@ describe("Login Component", () => {
     expect(refresh).toHaveBeenCalledTimes(2);
     expect(refresh).toHaveBeenNthCalledWith(2, { newLogin: true });
 
-    await act(async () => finishFocus({ access_token: "old-session", token_type: "bearer" }));
+    await act(async () => finishFocus(createMockAuthToken({ access_token: "old-session", token_type: "bearer" })));
     expect(screen.getByLabelText(/username/i)).toBeInTheDocument();
-    await act(async () => finishHint({ access_token: "new-session", token_type: "bearer" }));
+    await act(async () => finishHint(createMockAuthToken({ access_token: "new-session", token_type: "bearer" })));
     expect(await screen.findByText("/browse")).toBeInTheDocument();
   });
 
   it("waits for a login hint received during configuration loading before starting OIDC", async () => {
     vi.stubGlobal("BroadcastChannel", LoginChannel);
-    let finishRefresh!: (response: { access_token: string; token_type: string }) => void;
+    let finishRefresh!: (response: AuthToken) => void;
     vi.spyOn(authSession, "requestRefresh").mockReturnValue(
       new Promise((resolve) => {
         finishRefresh = resolve;
@@ -267,7 +273,7 @@ describe("Login Component", () => {
     await waitFor(() => expect(authSession.requestRefresh).toHaveBeenCalledOnce());
     expect(window.location.assign).not.toHaveBeenCalled();
 
-    finishRefresh({ access_token: "restored-token", token_type: "bearer" });
+    finishRefresh(createMockAuthToken({ access_token: "restored-token", token_type: "bearer" }));
     expect(await screen.findByText("/browse")).toBeInTheDocument();
     expect(window.location.assign).not.toHaveBeenCalled();
   });
diff --git a/frontend/src/pages/__tests__/OidcCallback.test.tsx b/frontend/src/pages/__tests__/OidcCallback.test.tsx
index 725e95e78..3ab872b06 100644
--- a/frontend/src/pages/__tests__/OidcCallback.test.tsx
+++ b/frontend/src/pages/__tests__/OidcCallback.test.tsx
@@ -3,6 +3,7 @@ import { HttpResponse, http } from "msw";
 import { type ReactNode, StrictMode, useEffect, useState } from "react";
 import { createMemoryRouter, Route, RouterProvider, Routes } from "react-router-dom";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { createMockAuthToken } from "../../test/fixtures/users";
 import { server } from "../../test/mocks/server";
 import { SambeeThemeProvider, useSambeeTheme } from "../../theme";
 import OidcCallback from "../OidcCallback";
@@ -130,7 +131,9 @@ describe("OIDC callback", () => {
         }
       }
     );
-    vi.mocked(exchangeOidcGrant).mockResolvedValue({ access_token: "sambee-token", token_type: "bearer", return_path: "/browse" });
+    vi.mocked(exchangeOidcGrant).mockResolvedValue(
+      createMockAuthToken({ access_token: "sambee-token", token_type: "bearer", return_path: "/browse" })
+    );
 
     render(
       <MemoryRouter initialEntries={["/login/oidc/callback"]}>
@@ -173,7 +176,7 @@ describe("OIDC callback", () => {
   });
 
   it("finishes the same-user callback despite late 401s from A and loads protected data with B", async () => {
-    const sessionA = { access_token: "session-a", token_type: "bearer", user_id: "same-user" };
+    const sessionA = createMockAuthToken({ access_token: "session-a", token_type: "bearer", user_id: "same-user" });
     const sessionB = {
       access_token: "session-b",
       token_type: "bearer",
diff --git a/frontend/src/pages/__tests__/PreferencesSettings.test.tsx b/frontend/src/pages/__tests__/PreferencesSettings.test.tsx
index 1bbd1f6b9..c4d53b685 100644
--- a/frontend/src/pages/__tests__/PreferencesSettings.test.tsx
+++ b/frontend/src/pages/__tests__/PreferencesSettings.test.tsx
@@ -259,7 +259,7 @@ describe("AppearanceSettings", () => {
     render(<AppearanceSettings />);
 
     act(() => screen.getByRole("radio", { name: "Sambee dark" }).focus());
-    await user.click(screen.getByRole("button", { name: "Delete", exact: true }));
+    await user.click(screen.getByRole("button", { name: "Delete" }));
     await user.click(within(screen.getByRole("dialog", { name: "Delete theme?" })).getByRole("button", { name: "Delete" }));
 
     await waitFor(() => expect(themeContextState.refreshThemes).toHaveBeenCalledOnce());
diff --git a/frontend/src/pages/__tests__/SmbSettings.test.tsx b/frontend/src/pages/__tests__/SmbSettings.test.tsx
index 863814d6b..6e9e92924 100644
--- a/frontend/src/pages/__tests__/SmbSettings.test.tsx
+++ b/frontend/src/pages/__tests__/SmbSettings.test.tsx
@@ -34,7 +34,6 @@ const smbSettings: SmbSettingsData = {
     encryption_mode: "signing_only",
     connection_timeout_seconds: 30,
   },
-  policy_source: "default",
   require_signing: true,
   require_encryption: false,
 };
diff --git a/frontend/src/pages/__tests__/UserManagementSettings.test.tsx b/frontend/src/pages/__tests__/UserManagementSettings.test.tsx
index c49e89870..3693757b2 100644
--- a/frontend/src/pages/__tests__/UserManagementSettings.test.tsx
+++ b/frontend/src/pages/__tests__/UserManagementSettings.test.tsx
@@ -10,6 +10,8 @@ import {
   primeCachedAsyncData,
 } from "../../hooks/useCachedAsyncData";
 import { setRegionalLocalePreference } from "../../i18n";
+import { createMockAdminUser, createMockAdminUserList } from "../../test/fixtures/users";
+import { requireTestElement, requireTestValue } from "../../test/helpers/assertions";
 import { SambeeThemeProvider } from "../../theme";
 import type { AdminUserCreateResult, AdminUserPasswordResetResult } from "../../types";
 import { USER_DIRECTORY_VISIBLE_COLUMNS_STORAGE_KEY, UserManagementSettings } from "../UserManagementSettings";
@@ -86,21 +88,23 @@ describe("UserManagementSettings", () => {
     window.localStorage.removeItem(USER_DIRECTORY_VISIBLE_COLUMNS_STORAGE_KEY);
     window.history.replaceState(null, "", window.location.pathname);
     vi.mocked(isControlledReauthenticationInProgress).mockReturnValue(false);
-    vi.mocked(api.getUsers).mockResolvedValue([
-      {
-        id: "user-1",
-        username: "admin",
-        role: "admin",
-        is_active: true,
-        must_change_password: false,
-        has_local_password: true,
-        oidc_role_assignment: null,
-        oidc: null,
-        pending_oidc: null,
-        created_at: "2026-03-01T10:00:00Z",
-        updated_at: "2026-03-01T10:00:00Z",
-      },
-    ]);
+    vi.mocked(api.getUsers).mockResolvedValue(
+      createMockAdminUserList([
+        createMockAdminUser({
+          id: "user-1",
+          username: "admin",
+          role: "admin",
+          is_active: true,
+          must_change_password: false,
+          has_local_password: true,
+          oidc_role_assignment: null,
+          oidc: null,
+          pending_oidc: null,
+          created_at: "2026-03-01T10:00:00Z",
+          updated_at: "2026-03-01T10:00:00Z",
+        }),
+      ])
+    );
     vi.mocked(api.getCurrentUser).mockResolvedValue({
       id: "user-1",
       username: "admin",
@@ -218,34 +222,36 @@ describe("UserManagementSettings", () => {
   });
 
   it("uses the inline bold username confirmation when deleting another user", async () => {
-    vi.mocked(api.getUsers).mockResolvedValue([
-      {
-        id: "user-1",
-        username: "admin",
-        role: "admin",
-        is_active: true,
-        must_change_password: false,
-        has_local_password: true,
-        oidc_role_assignment: null,
-        oidc: null,
-        pending_oidc: null,
-        created_at: "2026-03-01T10:00:00Z",
-        updated_at: "2026-03-01T10:00:00Z",
-      },
-      {
-        id: "user-2",
-        username: "other-user",
-        role: "viewer",
-        is_active: true,
-        must_change_password: false,
-        has_local_password: false,
-        oidc_role_assignment: null,
-        oidc: null,
-        pending_oidc: null,
-        created_at: "2026-03-01T10:00:00Z",
-        updated_at: "2026-03-01T10:00:00Z",
-      },
-    ]);
+    vi.mocked(api.getUsers).mockResolvedValue(
+      createMockAdminUserList([
+        createMockAdminUser({
+          id: "user-1",
+          username: "admin",
+          role: "admin",
+          is_active: true,
+          must_change_password: false,
+          has_local_password: true,
+          oidc_role_assignment: null,
+          oidc: null,
+          pending_oidc: null,
+          created_at: "2026-03-01T10:00:00Z",
+          updated_at: "2026-03-01T10:00:00Z",
+        }),
+        createMockAdminUser({
+          id: "user-2",
+          username: "other-user",
+          role: "viewer",
+          is_active: true,
+          must_change_password: false,
+          has_local_password: false,
+          oidc_role_assignment: null,
+          oidc: null,
+          pending_oidc: null,
+          created_at: "2026-03-01T10:00:00Z",
+          updated_at: "2026-03-01T10:00:00Z",
+        }),
+      ])
+    );
     const user = userEvent.setup();
 
     render(
@@ -417,23 +423,25 @@ describe("UserManagementSettings", () => {
 
   it("uses the role selector and read-only identity fields for linked OIDC users", async () => {
     mockOidcAuthenticationEnabled();
-    vi.mocked(api.getUsers).mockResolvedValue([
-      {
-        id: "user-1",
-        username: "admin",
-        name: "OIDC Admin",
-        email: "admin@example.test",
-        role: "admin",
-        is_active: true,
-        must_change_password: false,
-        has_local_password: true,
-        oidc_role_assignment: null,
-        oidc: { identity_id: "identity-1", provider_display_name: "Corporate login", last_login_at: null, inherited_role: "editor" },
-        pending_oidc: null,
-        created_at: "2026-03-01T10:00:00Z",
-        updated_at: "2026-03-01T10:00:00Z",
-      },
-    ]);
+    vi.mocked(api.getUsers).mockResolvedValue(
+      createMockAdminUserList([
+        createMockAdminUser({
+          id: "user-1",
+          username: "admin",
+          name: "OIDC Admin",
+          email: "admin@example.test",
+          role: "admin",
+          is_active: true,
+          must_change_password: false,
+          has_local_password: true,
+          oidc_role_assignment: null,
+          oidc: { identity_id: "identity-1", provider_display_name: "Corporate login", last_login_at: null, inherited_role: "editor" },
+          pending_oidc: null,
+          created_at: "2026-03-01T10:00:00Z",
+          updated_at: "2026-03-01T10:00:00Z",
+        }),
+      ])
+    );
     const user = userEvent.setup();
 
     render(
@@ -454,36 +462,38 @@ describe("UserManagementSettings", () => {
 
   it("shows the inherited OIDC role and clears an individual override", async () => {
     mockOidcAuthenticationEnabled();
-    vi.mocked(api.getUsers).mockResolvedValue([
-      {
-        id: "user-1",
-        username: "admin",
-        role: "admin",
-        is_active: true,
-        must_change_password: false,
-        has_local_password: true,
-        oidc_role_assignment: null,
-        oidc: null,
-        pending_oidc: null,
-        created_at: "2026-03-01T10:00:00Z",
-        updated_at: "2026-03-01T10:00:00Z",
-      },
-      {
-        id: "user-2",
-        username: "oidc-user",
-        name: "OIDC User",
-        email: "oidc-user@example.test",
-        role: "admin",
-        is_active: true,
-        must_change_password: false,
-        has_local_password: false,
-        oidc_role_assignment: "admin",
-        oidc: { identity_id: "identity-2", provider_display_name: "Corporate login", last_login_at: null, inherited_role: "viewer" },
-        pending_oidc: null,
-        created_at: "2026-03-01T10:00:00Z",
-        updated_at: "2026-03-01T10:00:00Z",
-      },
-    ]);
+    vi.mocked(api.getUsers).mockResolvedValue(
+      createMockAdminUserList([
+        createMockAdminUser({
+          id: "user-1",
+          username: "admin",
+          role: "admin",
+          is_active: true,
+          must_change_password: false,
+          has_local_password: true,
+          oidc_role_assignment: null,
+          oidc: null,
+          pending_oidc: null,
+          created_at: "2026-03-01T10:00:00Z",
+          updated_at: "2026-03-01T10:00:00Z",
+        }),
+        createMockAdminUser({
+          id: "user-2",
+          username: "oidc-user",
+          name: "OIDC User",
+          email: "oidc-user@example.test",
+          role: "admin",
+          is_active: true,
+          must_change_password: false,
+          has_local_password: false,
+          oidc_role_assignment: "admin",
+          oidc: { identity_id: "identity-2", provider_display_name: "Corporate login", last_login_at: null, inherited_role: "viewer" },
+          pending_oidc: null,
+          created_at: "2026-03-01T10:00:00Z",
+          updated_at: "2026-03-01T10:00:00Z",
+        }),
+      ])
+    );
     const user = userEvent.setup();
 
     render(
@@ -515,38 +525,40 @@ describe("UserManagementSettings", () => {
 
   it("does not offer an inherited role for a pending OIDC mapping", async () => {
     mockOidcAuthenticationEnabled();
-    vi.mocked(api.getUsers).mockResolvedValue([
-      {
-        id: "user-1",
-        username: "admin",
-        role: "admin",
-        is_active: true,
-        must_change_password: false,
-        has_local_password: true,
-        oidc_role_assignment: null,
-        oidc: null,
-        pending_oidc: null,
-        created_at: "2026-03-01T10:00:00Z",
-        updated_at: "2026-03-01T10:00:00Z",
-      },
-      {
-        id: "user-2",
-        username: "pending-user",
-        role: "admin",
-        is_active: true,
-        must_change_password: false,
-        has_local_password: false,
-        oidc_role_assignment: "admin",
-        oidc: null,
-        pending_oidc: {
-          expected_username: "provider-user",
-          created_by_username: "admin",
+    vi.mocked(api.getUsers).mockResolvedValue(
+      createMockAdminUserList([
+        createMockAdminUser({
+          id: "user-1",
+          username: "admin",
+          role: "admin",
+          is_active: true,
+          must_change_password: false,
+          has_local_password: true,
+          oidc_role_assignment: null,
+          oidc: null,
+          pending_oidc: null,
           created_at: "2026-03-01T10:00:00Z",
-        },
-        created_at: "2026-03-01T10:00:00Z",
-        updated_at: "2026-03-01T10:00:00Z",
-      },
-    ]);
+          updated_at: "2026-03-01T10:00:00Z",
+        }),
+        createMockAdminUser({
+          id: "user-2",
+          username: "pending-user",
+          role: "admin",
+          is_active: true,
+          must_change_password: false,
+          has_local_password: false,
+          oidc_role_assignment: "admin",
+          oidc: null,
+          pending_oidc: {
+            expected_username: "provider-user",
+            created_by_username: "admin",
+            created_at: "2026-03-01T10:00:00Z",
+          },
+          created_at: "2026-03-01T10:00:00Z",
+          updated_at: "2026-03-01T10:00:00Z",
+        }),
+      ])
+    );
     const user = userEvent.setup();
 
     render(
@@ -566,34 +578,36 @@ describe("UserManagementSettings", () => {
 
   it("does not offer an inherited role until a linked OIDC account has a verified role", async () => {
     mockOidcAuthenticationEnabled();
-    vi.mocked(api.getUsers).mockResolvedValue([
-      {
-        id: "user-1",
-        username: "admin",
-        role: "admin",
-        is_active: true,
-        must_change_password: false,
-        has_local_password: true,
-        oidc_role_assignment: null,
-        oidc: null,
-        pending_oidc: null,
-        created_at: "2026-03-01T10:00:00Z",
-        updated_at: "2026-03-01T10:00:00Z",
-      },
-      {
-        id: "user-2",
-        username: "unresolved-oidc-user",
-        role: "admin",
-        is_active: true,
-        must_change_password: false,
-        has_local_password: false,
-        oidc_role_assignment: "admin",
-        oidc: { identity_id: "identity-2", provider_display_name: "Corporate login", last_login_at: null, inherited_role: null },
-        pending_oidc: null,
-        created_at: "2026-03-01T10:00:00Z",
-        updated_at: "2026-03-01T10:00:00Z",
-      },
-    ]);
+    vi.mocked(api.getUsers).mockResolvedValue(
+      createMockAdminUserList([
+        createMockAdminUser({
+          id: "user-1",
+          username: "admin",
+          role: "admin",
+          is_active: true,
+          must_change_password: false,
+          has_local_password: true,
+          oidc_role_assignment: null,
+          oidc: null,
+          pending_oidc: null,
+          created_at: "2026-03-01T10:00:00Z",
+          updated_at: "2026-03-01T10:00:00Z",
+        }),
+        createMockAdminUser({
+          id: "user-2",
+          username: "unresolved-oidc-user",
+          role: "admin",
+          is_active: true,
+          must_change_password: false,
+          has_local_password: false,
+          oidc_role_assignment: "admin",
+          oidc: { identity_id: "identity-2", provider_display_name: "Corporate login", last_login_at: null, inherited_role: null },
+          pending_oidc: null,
+          created_at: "2026-03-01T10:00:00Z",
+          updated_at: "2026-03-01T10:00:00Z",
+        }),
+      ])
+    );
     const user = userEvent.setup();
 
     render(
@@ -897,8 +911,9 @@ describe("UserManagementSettings", () => {
         expect.stringContaining("Expiration: Never"),
         "",
       ]);
-      expect(within(row.children[5]).getByRole("button", { name: "Edit admin" })).toBeInTheDocument();
-      expect(within(row.children[5]).getByRole("button", { name: "User actions for admin" })).toBeInTheDocument();
+      const actionsCell = within(requireTestElement(row.children[5], HTMLElement));
+      expect(actionsCell.getByRole("button", { name: "Edit admin" })).toBeInTheDocument();
+      expect(actionsCell.getByRole("button", { name: "User actions for admin" })).toBeInTheDocument();
     } finally {
       restoreViewport();
     }
@@ -923,34 +938,36 @@ describe("UserManagementSettings", () => {
     ];
     window.localStorage.setItem(USER_DIRECTORY_VISIBLE_COLUMNS_STORAGE_KEY, JSON.stringify(columns));
     mockOidcAuthenticationEnabled();
-    vi.mocked(api.getUsers).mockResolvedValue([
-      {
-        id: "long-user",
-        username: "very-long-username-without-spaces",
-        name: "Layout test",
-        email,
-        role: "admin",
-        is_active: false,
-        must_change_password: true,
-        has_local_password: true,
-        expires_at: "2025-01-01T10:00:00Z",
-        created_at: timestamp,
-        updated_at: timestamp,
-        oidc_role_assignment: "admin",
-        pending_oidc: null,
-        oidc: {
-          identity_id: "identity",
-          user_id: "long-user",
-          provider_display_name: provider,
-          issuer: "https://idp.example",
-          subject: "subject",
-          last_seen_username: "long-user",
-          last_groups: [],
+    vi.mocked(api.getUsers).mockResolvedValue(
+      createMockAdminUserList([
+        createMockAdminUser({
+          id: "long-user",
+          username: "very-long-username-without-spaces",
+          name: "Layout test",
+          email,
+          role: "admin",
+          is_active: false,
+          must_change_password: true,
+          has_local_password: true,
+          expires_at: "2025-01-01T10:00:00Z",
           created_at: timestamp,
-          last_login_at: timestamp,
-        },
-      },
-    ]);
+          updated_at: timestamp,
+          oidc_role_assignment: "admin",
+          pending_oidc: null,
+          oidc: {
+            identity_id: "identity",
+            user_id: "long-user",
+            provider_display_name: provider,
+            issuer: "https://idp.example",
+            subject: "subject",
+            last_seen_username: "long-user",
+            last_groups: [],
+            created_at: timestamp,
+            last_login_at: timestamp,
+          },
+        }),
+      ])
+    );
     await setRegionalLocalePreference("de-DE");
     try {
       render(
@@ -1008,21 +1025,23 @@ describe("UserManagementSettings", () => {
     let resolveSortedUsers: ((users: Awaited<ReturnType<typeof api.getUsers>>) => void) | undefined;
 
     vi.mocked(api.getUsers)
-      .mockResolvedValueOnce([
-        {
-          id: "user-1",
-          username: "admin",
-          role: "admin",
-          is_active: true,
-          must_change_password: false,
-          has_local_password: true,
-          oidc_role_assignment: null,
-          oidc: null,
-          pending_oidc: null,
-          created_at: "2026-03-01T10:00:00Z",
-          updated_at: "2026-03-01T10:00:00Z",
-        },
-      ])
+      .mockResolvedValueOnce(
+        createMockAdminUserList([
+          createMockAdminUser({
+            id: "user-1",
+            username: "admin",
+            role: "admin",
+            is_active: true,
+            must_change_password: false,
+            has_local_password: true,
+            oidc_role_assignment: null,
+            oidc: null,
+            pending_oidc: null,
+            created_at: "2026-03-01T10:00:00Z",
+            updated_at: "2026-03-01T10:00:00Z",
+          }),
+        ])
+      )
       .mockImplementationOnce(
         () =>
           new Promise((resolve) => {
@@ -1045,21 +1064,23 @@ describe("UserManagementSettings", () => {
       expect(api.getCurrentUser).toHaveBeenCalledTimes(2);
       expect(api.getOidcConfiguration).toHaveBeenCalledTimes(1);
 
-      resolveSortedUsers?.([
-        {
-          id: "user-1",
-          username: "admin",
-          role: "admin",
-          is_active: true,
-          must_change_password: false,
-          has_local_password: true,
-          oidc_role_assignment: null,
-          oidc: null,
-          pending_oidc: null,
-          created_at: "2026-03-01T10:00:00Z",
-          updated_at: "2026-03-01T10:00:00Z",
-        },
-      ]);
+      resolveSortedUsers?.(
+        createMockAdminUserList([
+          createMockAdminUser({
+            id: "user-1",
+            username: "admin",
+            role: "admin",
+            is_active: true,
+            must_change_password: false,
+            has_local_password: true,
+            oidc_role_assignment: null,
+            oidc: null,
+            pending_oidc: null,
+            created_at: "2026-03-01T10:00:00Z",
+            updated_at: "2026-03-01T10:00:00Z",
+          }),
+        ])
+      );
       await waitFor(() => expect(api.getUsers).toHaveBeenCalledTimes(2));
       await waitFor(() => expect(screen.queryByRole("progressbar", { name: "Updating user directory" })).not.toBeInTheDocument());
     } finally {
@@ -1070,21 +1091,23 @@ describe("UserManagementSettings", () => {
   it("hides OIDC-only controls and clears OIDC query parameters when OIDC is disabled", async () => {
     const restoreViewport = mockViewportWidth(1200);
     window.history.replaceState(null, "", `${window.location.pathname}?auth=oidc&oidc_state=linked&role_source=oidc_groups`);
-    vi.mocked(api.getUsers).mockResolvedValue([
-      {
-        id: "user-1",
-        username: "admin",
-        role: "admin",
-        is_active: true,
-        must_change_password: false,
-        has_local_password: false,
-        oidc_role_assignment: null,
-        oidc: { identity_id: "identity-1", provider_display_name: "Corporate login", last_login_at: null },
-        pending_oidc: { expected_username: "admin", created_by_username: "admin", created_at: "2026-03-01T10:00:00Z" },
-        created_at: "2026-03-01T10:00:00Z",
-        updated_at: "2026-03-01T10:00:00Z",
-      },
-    ]);
+    vi.mocked(api.getUsers).mockResolvedValue(
+      createMockAdminUserList([
+        createMockAdminUser({
+          id: "user-1",
+          username: "admin",
+          role: "admin",
+          is_active: true,
+          must_change_password: false,
+          has_local_password: false,
+          oidc_role_assignment: null,
+          oidc: { identity_id: "identity-1", provider_display_name: "Corporate login", last_login_at: null },
+          pending_oidc: { expected_username: "admin", created_by_username: "admin", created_at: "2026-03-01T10:00:00Z" },
+          created_at: "2026-03-01T10:00:00Z",
+          updated_at: "2026-03-01T10:00:00Z",
+        }),
+      ])
+    );
     const user = userEvent.setup();
 
     try {
@@ -1095,7 +1118,7 @@ describe("UserManagementSettings", () => {
       );
 
       await screen.findByText("admin (you)", { exact: true });
-      await user.click(await screen.findByRole("button", { name: "Filters", exact: true }));
+      await user.click(await screen.findByRole("button", { name: "Filters" }));
 
       expect(screen.queryByRole("combobox", { name: "OIDC state" })).not.toBeInTheDocument();
       expect(screen.queryByRole("combobox", { name: "Role source" })).not.toBeInTheDocument();
@@ -1180,42 +1203,44 @@ describe("UserManagementSettings", () => {
 
   it("shows OIDC state and hides password reset for a passwordless account", async () => {
     mockOidcAuthenticationEnabled();
-    vi.mocked(api.getUsers).mockResolvedValue([
-      {
-        id: "user-1",
-        username: "admin",
-        role: "admin",
-        is_active: true,
-        must_change_password: false,
-        has_local_password: false,
-        oidc_role_assignment: null,
-        oidc: {
-          identity_id: "identity-1",
-          provider_display_name: "Corporate login",
-          last_login_at: "2026-03-01T10:00:00Z",
-        },
-        pending_oidc: null,
-        created_at: "2026-03-01T10:00:00Z",
-        updated_at: "2026-03-01T10:00:00Z",
-      },
-      {
-        id: "user-2",
-        username: "second-oidc-user",
-        role: "viewer",
-        is_active: true,
-        must_change_password: false,
-        has_local_password: false,
-        oidc_role_assignment: null,
-        oidc: {
-          identity_id: "identity-2",
-          provider_display_name: "Corporate login",
-          last_login_at: null,
-        },
-        pending_oidc: null,
-        created_at: "2026-03-01T10:00:00Z",
-        updated_at: "2026-03-01T10:00:00Z",
-      },
-    ]);
+    vi.mocked(api.getUsers).mockResolvedValue(
+      createMockAdminUserList([
+        createMockAdminUser({
+          id: "user-1",
+          username: "admin",
+          role: "admin",
+          is_active: true,
+          must_change_password: false,
+          has_local_password: false,
+          oidc_role_assignment: null,
+          oidc: {
+            identity_id: "identity-1",
+            provider_display_name: "Corporate login",
+            last_login_at: "2026-03-01T10:00:00Z",
+          },
+          pending_oidc: null,
+          created_at: "2026-03-01T10:00:00Z",
+          updated_at: "2026-03-01T10:00:00Z",
+        }),
+        createMockAdminUser({
+          id: "user-2",
+          username: "second-oidc-user",
+          role: "viewer",
+          is_active: true,
+          must_change_password: false,
+          has_local_password: false,
+          oidc_role_assignment: null,
+          oidc: {
+            identity_id: "identity-2",
+            provider_display_name: "Corporate login",
+            last_login_at: null,
+          },
+          pending_oidc: null,
+          created_at: "2026-03-01T10:00:00Z",
+          updated_at: "2026-03-01T10:00:00Z",
+        }),
+      ])
+    );
 
     render(
       <SambeeThemeProvider>
@@ -1224,7 +1249,7 @@ describe("UserManagementSettings", () => {
     );
 
     expect((await screen.findAllByText("OIDC", { exact: true })).length).toBeGreaterThan(0);
-    const lastSignIn = screen.getAllByTestId("user-row-last-oidc-sign-in")[0];
+    const lastSignIn = requireTestValue(screen.getAllByTestId("user-row-last-oidc-sign-in")[0]);
     expect(
       within(lastSignIn).getByText(new Intl.DateTimeFormat(undefined, { dateStyle: "short" }).format(new Date("2026-03-01T10:00:00Z")))
     ).toBeInTheDocument();
@@ -1240,79 +1265,82 @@ describe("UserManagementSettings", () => {
     ["oidc_only", "uniform"],
     ["oidc_or_password", "group_based"],
   ] as const)("renders directory identities in %s mode", async (authMode, roleAssignmentMode) => {
-    vi.mocked(api.getUsers).mockResolvedValue([
-      {
-        id: "user-1",
-        username: "local-user",
-        role: "admin",
-        is_active: true,
-        must_change_password: false,
-        has_local_password: true,
-        oidc_role_assignment: null,
-        oidc: null,
-        pending_oidc: null,
-        created_at: "2026-03-01T10:00:00Z",
-        updated_at: "2026-03-01T10:00:00Z",
-      },
-      {
-        id: "user-2",
-        username: "inherited-user",
-        role: "editor",
-        is_active: true,
-        must_change_password: false,
-        has_local_password: false,
-        oidc_role_assignment: null,
-        oidc: { identity_id: "identity-2", provider_display_name: "Corporate login", last_login_at: null, inherited_role: "editor" },
-        pending_oidc: null,
-        created_at: "2026-03-01T10:00:00Z",
-        updated_at: "2026-03-01T10:00:00Z",
-      },
-      {
-        id: "user-3",
-        username: "override-user",
-        role: "admin",
-        is_active: true,
-        must_change_password: false,
-        has_local_password: true,
-        oidc_role_assignment: "admin",
-        oidc: { identity_id: "identity-3", provider_display_name: "Corporate login", last_login_at: null, inherited_role: "editor" },
-        pending_oidc: null,
-        created_at: "2026-03-01T10:00:00Z",
-        updated_at: "2026-03-01T10:00:00Z",
-      },
-      {
-        id: "user-4",
-        username: "pending-user",
-        role: "admin",
-        is_active: true,
-        must_change_password: false,
-        has_local_password: false,
-        oidc_role_assignment: "admin",
-        oidc: null,
-        pending_oidc: {
-          expected_username: "pending-user",
-          created_by_username: "local-user",
+    vi.mocked(api.getUsers).mockResolvedValue(
+      createMockAdminUserList([
+        createMockAdminUser({
+          id: "user-1",
+          username: "local-user",
+          role: "admin",
+          is_active: true,
+          must_change_password: false,
+          has_local_password: true,
+          oidc_role_assignment: null,
+          oidc: null,
+          pending_oidc: null,
           created_at: "2026-03-01T10:00:00Z",
-        },
-        created_at: "2026-03-01T10:00:00Z",
-        updated_at: "2026-03-01T10:00:00Z",
-      },
-      {
-        id: "user-5",
-        username: "unresolved-user",
-        role: "editor",
-        is_active: true,
-        must_change_password: false,
-        has_local_password: false,
-        oidc_role_assignment: null,
-        oidc: { identity_id: "identity-5", provider_display_name: "Corporate login", last_login_at: null, inherited_role: null },
-        pending_oidc: null,
-        created_at: "2026-03-01T10:00:00Z",
-        updated_at: "2026-03-01T10:00:00Z",
-      },
-    ]);
+          updated_at: "2026-03-01T10:00:00Z",
+        }),
+        createMockAdminUser({
+          id: "user-2",
+          username: "inherited-user",
+          role: "editor",
+          is_active: true,
+          must_change_password: false,
+          has_local_password: false,
+          oidc_role_assignment: null,
+          oidc: { identity_id: "identity-2", provider_display_name: "Corporate login", last_login_at: null, inherited_role: "editor" },
+          pending_oidc: null,
+          created_at: "2026-03-01T10:00:00Z",
+          updated_at: "2026-03-01T10:00:00Z",
+        }),
+        createMockAdminUser({
+          id: "user-3",
+          username: "override-user",
+          role: "admin",
+          is_active: true,
+          must_change_password: false,
+          has_local_password: true,
+          oidc_role_assignment: "admin",
+          oidc: { identity_id: "identity-3", provider_display_name: "Corporate login", last_login_at: null, inherited_role: "editor" },
+          pending_oidc: null,
+          created_at: "2026-03-01T10:00:00Z",
+          updated_at: "2026-03-01T10:00:00Z",
+        }),
+        createMockAdminUser({
+          id: "user-4",
+          username: "pending-user",
+          role: "admin",
+          is_active: true,
+          must_change_password: false,
+          has_local_password: false,
+          oidc_role_assignment: "admin",
+          oidc: null,
+          pending_oidc: {
+            expected_username: "pending-user",
+            created_by_username: "local-user",
+            created_at: "2026-03-01T10:00:00Z",
+          },
+          created_at: "2026-03-01T10:00:00Z",
+          updated_at: "2026-03-01T10:00:00Z",
+        }),
+        createMockAdminUser({
+          id: "user-5",
+          username: "unresolved-user",
+          role: "editor",
+          is_active: true,
+          must_change_password: false,
+          has_local_password: false,
+          oidc_role_assignment: null,
+          oidc: { identity_id: "identity-5", provider_display_name: "Corporate login", last_login_at: null, inherited_role: null },
+          pending_oidc: null,
+          created_at: "2026-03-01T10:00:00Z",
+          updated_at: "2026-03-01T10:00:00Z",
+        }),
+      ])
+    );
     vi.mocked(api.getOidcConfiguration).mockResolvedValue({
       configuration: {
+        no_refresh_session_limit_hours: 8,
         display_name: "Corporate login",
         issuer_url: "https://idp.example.test",
         client_id: "sambee",
@@ -1377,46 +1405,49 @@ describe("UserManagementSettings", () => {
 
   it("uses the centralized OIDC mapping dialog and closes change and move workflows with Escape", async () => {
     const restoreViewport = mockViewportWidth(1200);
-    vi.mocked(api.getUsers).mockResolvedValue([
-      {
-        id: "user-1",
-        username: "linked-admin",
-        role: "admin",
-        is_active: true,
-        must_change_password: false,
-        has_local_password: true,
-        oidc_role_assignment: null,
-        oidc: {
-          identity_id: "identity-1",
-          user_id: "user-1",
-          provider_display_name: "Corporate login",
-          issuer: "https://idp.example.test",
-          subject: "provider-subject-1",
-          last_seen_username: "linked-admin",
-          last_groups: ["admins", "operators"],
+    vi.mocked(api.getUsers).mockResolvedValue(
+      createMockAdminUserList([
+        createMockAdminUser({
+          id: "user-1",
+          username: "linked-admin",
+          role: "admin",
+          is_active: true,
+          must_change_password: false,
+          has_local_password: true,
+          oidc_role_assignment: null,
+          oidc: {
+            identity_id: "identity-1",
+            user_id: "user-1",
+            provider_display_name: "Corporate login",
+            issuer: "https://idp.example.test",
+            subject: "provider-subject-1",
+            last_seen_username: "linked-admin",
+            last_groups: ["admins", "operators"],
+            created_at: "2026-03-01T10:00:00Z",
+            last_login_at: null,
+          },
+          pending_oidc: null,
           created_at: "2026-03-01T10:00:00Z",
-          last_login_at: null,
-        },
-        pending_oidc: null,
-        created_at: "2026-03-01T10:00:00Z",
-        updated_at: "2026-03-01T10:00:00Z",
-      },
-      {
-        id: "user-2",
-        username: "unmapped-user",
-        role: "viewer",
-        is_active: true,
-        must_change_password: false,
-        has_local_password: true,
-        oidc_role_assignment: null,
-        oidc: null,
-        pending_oidc: null,
-        created_at: "2026-03-01T10:00:00Z",
-        updated_at: "2026-03-01T10:00:00Z",
-      },
-    ]);
+          updated_at: "2026-03-01T10:00:00Z",
+        }),
+        createMockAdminUser({
+          id: "user-2",
+          username: "unmapped-user",
+          role: "viewer",
+          is_active: true,
+          must_change_password: false,
+          has_local_password: true,
+          oidc_role_assignment: null,
+          oidc: null,
+          pending_oidc: null,
+          created_at: "2026-03-01T10:00:00Z",
+          updated_at: "2026-03-01T10:00:00Z",
+        }),
+      ])
+    );
     vi.mocked(api.getOidcConfiguration).mockResolvedValue({
       configuration: {
+        no_refresh_session_limit_hours: 8,
         display_name: "Corporate login",
         issuer_url: "https://idp.example.test",
         client_id: "sambee",
@@ -1589,36 +1620,39 @@ describe("UserManagementSettings", () => {
     },
   ] as const)("confirms $action only after explicit acceptance", async ({ action, username, method, warning }) => {
     const restoreViewport = mockViewportWidth(1200);
-    vi.mocked(api.getUsers).mockResolvedValue([
-      {
-        id: "user-1",
-        username: "pending-user",
-        role: "editor",
-        is_active: true,
-        must_change_password: false,
-        has_local_password: true,
-        oidc_role_assignment: null,
-        oidc: null,
-        pending_oidc: { expected_username: "pending-user", created_by_username: "admin", created_at: "2026-03-01T10:00:00Z" },
-        created_at: "2026-03-01T10:00:00Z",
-        updated_at: "2026-03-01T10:00:00Z",
-      },
-      {
-        id: "user-2",
-        username: "linked-user",
-        role: "editor",
-        is_active: true,
-        must_change_password: false,
-        has_local_password: true,
-        oidc_role_assignment: null,
-        oidc: { identity_id: "identity-2", provider_display_name: "Corporate login", last_login_at: null },
-        pending_oidc: null,
-        created_at: "2026-03-01T10:00:00Z",
-        updated_at: "2026-03-01T10:00:00Z",
-      },
-    ]);
+    vi.mocked(api.getUsers).mockResolvedValue(
+      createMockAdminUserList([
+        createMockAdminUser({
+          id: "user-1",
+          username: "pending-user",
+          role: "editor",
+          is_active: true,
+          must_change_password: false,
+          has_local_password: true,
+          oidc_role_assignment: null,
+          oidc: null,
+          pending_oidc: { expected_username: "pending-user", created_by_username: "admin", created_at: "2026-03-01T10:00:00Z" },
+          created_at: "2026-03-01T10:00:00Z",
+          updated_at: "2026-03-01T10:00:00Z",
+        }),
+        createMockAdminUser({
+          id: "user-2",
+          username: "linked-user",
+          role: "editor",
+          is_active: true,
+          must_change_password: false,
+          has_local_password: true,
+          oidc_role_assignment: null,
+          oidc: { identity_id: "identity-2", provider_display_name: "Corporate login", last_login_at: null },
+          pending_oidc: null,
+          created_at: "2026-03-01T10:00:00Z",
+          updated_at: "2026-03-01T10:00:00Z",
+        }),
+      ])
+    );
     vi.mocked(api.getOidcConfiguration).mockResolvedValue({
       configuration: {
+        no_refresh_session_limit_hours: 8,
         display_name: "Corporate login",
         issuer_url: "https://idp.example.test",
         client_id: "sambee",
@@ -1644,7 +1678,7 @@ describe("UserManagementSettings", () => {
       auth_enforcement_disabled: false,
       health: { status: "healthy", public_url_configured: false, public_url: null, redirect_uri: null, reasons: [] },
     });
-    vi.mocked(api[method]).mockResolvedValue(undefined);
+    vi.mocked(api[method]).mockResolvedValue({ identity_mapping_revision: 1, pending_mappings: [] });
     const user = userEvent.setup();
     render(
       <SambeeThemeProvider>
diff --git a/frontend/src/pages/__tests__/useFileBrowserPane.test.tsx b/frontend/src/pages/__tests__/useFileBrowserPane.test.tsx
index 172ca8acd..0401c772b 100644
--- a/frontend/src/pages/__tests__/useFileBrowserPane.test.tsx
+++ b/frontend/src/pages/__tests__/useFileBrowserPane.test.tsx
@@ -1,16 +1,17 @@
 import { act, renderHook, waitFor } from "@testing-library/react";
 import type { ReactNode } from "react";
 import { beforeEach, describe, expect, it, vi } from "vitest";
-
 import api from "../../services/api";
 import { authSession } from "../../services/authSession";
 import { resetCurrentUserSettingsStoreForTests } from "../../services/userSettingsStore";
+import { createMockAuthToken } from "../../test/fixtures/users";
 import {
   type ApiMock,
   createFakeContentProviderRegistry,
   createStorageBackedTestContentProviderRegistry,
   setupSuccessfulApiMocks,
 } from "../../test/helpers";
+import { requireTestValue } from "../../test/helpers/assertions";
 import { SambeeThemeProvider } from "../../theme/ThemeContext";
 import { FileType, type LocalLinkTargetListing } from "../../types";
 import type { ContentProviderRegistry } from "../FileBrowser/contentProviders";
@@ -72,7 +73,7 @@ describe("useFileBrowserPane", () => {
   beforeEach(() => {
     vi.clearAllMocks();
     resetCurrentUserSettingsStoreForTests();
-    authSession.setAuthenticated({ access_token: "fake-token", token_type: "bearer" }, false);
+    authSession.setAuthenticated(createMockAuthToken({ access_token: "fake-token", token_type: "bearer" }), false);
     setupSuccessfulApiMocks(api as unknown as ApiMock);
     vi.mocked(getPreferredViewerId).mockResolvedValue(null);
     vi.mocked(setPreferredViewerId).mockResolvedValue();
@@ -83,32 +84,34 @@ describe("useFileBrowserPane", () => {
     act(() => result.current.applyLocation("conn-1", ""));
     await waitFor(() => expect(result.current.sortedFiles).toHaveLength(3));
 
-    act(() => result.current.selectItemFromIcon(result.current.sortedFiles[0], 0, false, false));
-    act(() => result.current.selectItemFromIcon(result.current.sortedFiles[2], 2, true, false));
+    act(() => result.current.selectItemFromIcon(requireTestValue(result.current.sortedFiles[0]), 0, false, false));
+    act(() => result.current.selectItemFromIcon(requireTestValue(result.current.sortedFiles[2]), 2, true, false));
     expect([...result.current.selectedFiles]).toEqual(result.current.sortedFiles.map((file) => file.path));
 
-    act(() => result.current.selectItemFromIcon(result.current.sortedFiles[1], 1, false, false));
-    act(() => result.current.selectItemFromIcon(result.current.sortedFiles[0], 0, true, true));
+    act(() => result.current.selectItemFromIcon(requireTestValue(result.current.sortedFiles[1]), 1, false, false));
+    act(() => result.current.selectItemFromIcon(requireTestValue(result.current.sortedFiles[0]), 0, true, true));
     expect(result.current.selectedFiles.size).toBe(3);
 
     act(() => result.current.handleClearSelection());
-    act(() => result.current.selectItemFromIcon(result.current.sortedFiles[2], 2, true, false));
-    expect([...result.current.selectedFiles]).toEqual([result.current.sortedFiles[2].path]);
+    act(() => result.current.selectItemFromIcon(requireTestValue(result.current.sortedFiles[2]), 2, true, false));
+    expect([...result.current.selectedFiles]).toEqual([requireTestValue(result.current.sortedFiles[2]).path]);
   });
 
   it("keeps earlier selections when extending a mouse range without Ctrl", async () => {
-    const entries = ["A", "B", "C", "D", "E"].map((name) => ({ ...mockDirectoryListing.items[2], name, path: name }));
+    const entries = ["A", "B", "C", "D", "E"].map((name) => ({ ...requireTestValue(mockDirectoryListing.items[2]), name, path: name }));
     vi.mocked(api.listDirectory).mockResolvedValue({ ...mockDirectoryListing, items: entries, total: entries.length });
     const { result } = renderHook(() => useFileBrowserPane({ rowHeight: 40, connections: mockConnections }), { wrapper });
     act(() => result.current.applyLocation("conn-1", ""));
     await waitFor(() => expect(result.current.sortedFiles).toHaveLength(5));
 
     const [first, , middle, , last] = result.current.sortedFiles;
-    act(() => result.current.selectItemFromIcon(first, 0, false, false));
-    act(() => result.current.selectItemFromIcon(middle, 2, false, false));
-    act(() => result.current.selectItemFromIcon(last, 4, true, false));
+    act(() => result.current.selectItemFromIcon(requireTestValue(first), 0, false, false));
+    act(() => result.current.selectItemFromIcon(requireTestValue(middle), 2, false, false));
+    act(() => result.current.selectItemFromIcon(requireTestValue(last), 4, true, false));
 
-    expect(result.current.selectedFiles).toEqual(new Set([first.path, ...result.current.sortedFiles.slice(2).map((file) => file.path)]));
+    expect(result.current.selectedFiles).toEqual(
+      new Set([requireTestValue(first).path, ...result.current.sortedFiles.slice(2).map((file) => file.path)])
+    );
   });
 
   it("adds a clicked item after a refresh removes the range anchor", async () => {
@@ -117,18 +120,22 @@ describe("useFileBrowserPane", () => {
     await waitFor(() => expect(result.current.sortedFiles).toHaveLength(3));
 
     const [first, middle, last] = result.current.sortedFiles;
-    act(() => result.current.selectItemFromIcon(first, 0, false, false));
-    act(() => result.current.selectItemFromIcon(last, 2, false, false));
+    act(() => result.current.selectItemFromIcon(requireTestValue(first), 0, false, false));
+    act(() => result.current.selectItemFromIcon(requireTestValue(last), 2, false, false));
 
-    vi.mocked(api.listDirectory).mockResolvedValue({ ...mockDirectoryListing, items: [first, middle], total: 2 });
+    vi.mocked(api.listDirectory).mockResolvedValue({
+      ...mockDirectoryListing,
+      items: [requireTestValue(first), requireTestValue(middle)],
+      total: 2,
+    });
     act(() => result.current.handleRefresh());
     await waitFor(() => {
       expect(result.current.sortedFiles).toHaveLength(2);
-      expect(result.current.selectedFiles).toEqual(new Set([first.path]));
+      expect(result.current.selectedFiles).toEqual(new Set([requireTestValue(first).path]));
     });
 
-    act(() => result.current.selectItemFromIcon(middle, 1, true, true));
-    expect(result.current.selectedFiles).toEqual(new Set([first.path, middle.path]));
+    act(() => result.current.selectItemFromIcon(requireTestValue(middle), 1, true, true));
+    expect(result.current.selectedFiles).toEqual(new Set([requireTestValue(first).path, requireTestValue(middle).path]));
   });
 
   it("uses a keyboard selection as the anchor for an icon range", async () => {
@@ -143,7 +150,7 @@ describe("useFileBrowserPane", () => {
     list.focus();
     act(() => result.current.handleToggleSelection());
     expect(result.current.selectedFiles.size).toBe(1);
-    act(() => result.current.selectItemFromIcon(result.current.sortedFiles[2], 2, true, false));
+    act(() => result.current.selectItemFromIcon(requireTestValue(result.current.sortedFiles[2]), 2, true, false));
     expect([...result.current.selectedFiles]).toEqual(result.current.sortedFiles.map((file) => file.path));
     list.remove();
   });
@@ -420,7 +427,7 @@ describe("useFileBrowserPane", () => {
       archive: { path: "Archives/backup.zip", size: 1 },
       path: "docs",
       items: [{ ...archiveMember, state: "readable" }],
-      total: 1,
+
       page_size: 100,
     });
 
@@ -475,7 +482,7 @@ describe("useFileBrowserPane", () => {
 
   it("normalizes same-drive absolute Windows paths for local-drive panes", async () => {
     const localDriveConnection = {
-      ...mockConnections[0],
+      ...requireTestValue(mockConnections[0]),
       id: "local-drive:d",
       slug: "d",
       type: "local",
@@ -503,7 +510,7 @@ describe("useFileBrowserPane", () => {
   });
 
   it("enriches a current local directory with deferred link target metadata", async () => {
-    const localDriveConnection = { ...mockConnections[0], id: "local-drive:c", slug: "c", type: "local" };
+    const localDriveConnection = { ...requireTestValue(mockConnections[0]), id: "local-drive:c", slug: "c", type: "local" };
     const linksListing = {
       path: "Links",
       total: 1,
@@ -558,7 +565,7 @@ describe("useFileBrowserPane", () => {
   });
 
   it("enriches cached local links when an earlier metadata request was interrupted", async () => {
-    const localDriveConnection = { ...mockConnections[0], id: "local-drive:c", slug: "c", type: "local" };
+    const localDriveConnection = { ...requireTestValue(mockConnections[0]), id: "local-drive:c", slug: "c", type: "local" };
     const linksListing = {
       path: "Links",
       total: 1,
@@ -583,7 +590,7 @@ describe("useFileBrowserPane", () => {
         },
       ],
     };
-    vi.mocked(api.listDirectory).mockImplementation(async (_connectionId, path) =>
+    vi.mocked(api.listDirectory).mockImplementation(async (_connectionId, path = "") =>
       path === "Links" ? linksListing : { path, total: 0, items: [] }
     );
     vi.mocked(api.listLocalLinkTargets)
@@ -626,7 +633,7 @@ describe("useFileBrowserPane", () => {
   });
 
   it("does not recreate an invalidated directory cache while enriching local links", async () => {
-    const localDriveConnection = { ...mockConnections[0], id: "local-drive:c", slug: "c", type: "local" };
+    const localDriveConnection = { ...requireTestValue(mockConnections[0]), id: "local-drive:c", slug: "c", type: "local" };
     const targets = deferred<LocalLinkTargetListing>();
     const linkEntry = {
       name: "Archive.lnk",
@@ -636,7 +643,7 @@ describe("useFileBrowserPane", () => {
       is_hidden: false,
       link_kind: "windows_shortcut" as const,
     };
-    vi.mocked(api.listDirectory).mockImplementation(async (_connectionId, path) => ({
+    vi.mocked(api.listDirectory).mockImplementation(async (_connectionId, path = "") => ({
       path,
       items: path === "Links" ? [linkEntry] : [],
       total: path === "Links" ? 1 : 0,
@@ -660,9 +667,9 @@ describe("useFileBrowserPane", () => {
   });
 
   it("ignores deferred link target metadata after navigating away", async () => {
-    const localDriveConnection = { ...mockConnections[0], id: "local-drive:c", slug: "c", type: "local" };
+    const localDriveConnection = { ...requireTestValue(mockConnections[0]), id: "local-drive:c", slug: "c", type: "local" };
     const targets = deferred<LocalLinkTargetListing>();
-    vi.mocked(api.listDirectory).mockImplementation(async (_connectionId, path) =>
+    vi.mocked(api.listDirectory).mockImplementation(async (_connectionId, path = "") =>
       path === "Links"
         ? {
             path,
@@ -735,7 +742,7 @@ describe("useFileBrowserPane", () => {
 
   it("records a local directory only after Companion confirms its type", async () => {
     const localDriveConnection = {
-      ...mockConnections[0],
+      ...requireTestValue(mockConnections[0]),
       id: "local-drive:d",
       slug: "d",
       type: "local",
@@ -795,8 +802,8 @@ describe("useFileBrowserPane", () => {
   });
 
   it("navigates to a directory resolved from a local link on another drive", async () => {
-    const sourceConnection = { ...mockConnections[0], id: "local-drive:c", slug: "c", type: "local" };
-    const targetConnection = { ...mockConnections[0], id: "local-drive:d", slug: "d", type: "local", name: "Drive D" };
+    const sourceConnection = { ...requireTestValue(mockConnections[0]), id: "local-drive:c", slug: "c", type: "local" };
+    const targetConnection = { ...requireTestValue(mockConnections[0]), id: "local-drive:d", slug: "d", type: "local", name: "Drive D" };
     const link = {
       name: "Archive.lnk",
       path: "Archive.lnk",
@@ -845,7 +852,7 @@ describe("useFileBrowserPane", () => {
   });
 
   it("opens a local ZIP as a virtual pane location instead of resolving a native file", async () => {
-    const localConnection = { ...mockConnections[0], id: "local-drive:c", slug: "c", type: "local" };
+    const localConnection = { ...requireTestValue(mockConnections[0]), id: "local-drive:c", slug: "c", type: "local" };
     const archive = {
       name: "backup.zip",
       path: "backup.zip",
@@ -897,7 +904,7 @@ describe("useFileBrowserPane", () => {
         archive: { path: "backup.zip", size: 1 },
         path: "",
         items: [{ name: "first.txt", path: "first.txt", type: FileType.FILE, state: "readable", is_hidden: false }],
-        total: 2,
+
         page_size: 1,
         next_cursor: "page-two",
       })
@@ -905,7 +912,7 @@ describe("useFileBrowserPane", () => {
         archive: { path: "backup.zip", size: 1 },
         path: "",
         items: [{ name: "second.txt", path: "second.txt", type: FileType.FILE, state: "readable", is_hidden: false }],
-        total: 2,
+
         page_size: 1,
         next_cursor: null,
       });
@@ -957,20 +964,13 @@ describe("useFileBrowserPane", () => {
       is_readable: true,
       is_hidden: false,
     };
-    const pendingAppend = deferred<{
-      archive: { path: string; size: number };
-      path: string;
-      items: Array<{ name: string; path: string; type: FileType; state: string; is_hidden: boolean }>;
-      total: number;
-      page_size: number;
-      next_cursor: string | null;
-    }>();
+    const pendingAppend = deferred<Awaited<ReturnType<typeof api.listArchiveDirectory>>>();
     vi.mocked(api.listArchiveDirectory)
       .mockResolvedValueOnce({
         archive: { path: "backup.zip", size: 1 },
         path: "",
         items: [{ name: "first.txt", path: "first.txt", type: FileType.FILE, state: "readable", is_hidden: false }],
-        total: 3,
+
         page_size: 1,
         next_cursor: "page-two",
       })
@@ -979,7 +979,7 @@ describe("useFileBrowserPane", () => {
         archive: { path: "backup.zip", size: 1 },
         path: "",
         items: [{ name: "refreshed.txt", path: "refreshed.txt", type: FileType.FILE, state: "readable", is_hidden: false }],
-        total: 2,
+
         page_size: 1,
         next_cursor: "page-two",
       })
@@ -987,7 +987,7 @@ describe("useFileBrowserPane", () => {
         archive: { path: "backup.zip", size: 1 },
         path: "",
         items: [{ name: "second.txt", path: "second.txt", type: FileType.FILE, state: "readable", is_hidden: false }],
-        total: 2,
+
         page_size: 1,
         next_cursor: null,
       });
@@ -1053,7 +1053,7 @@ describe("useFileBrowserPane", () => {
       ],
       total: 2,
     });
-    vi.mocked(api.listArchiveDirectory).mockImplementation((_connectionId, _archivePath, virtualPath) =>
+    vi.mocked(api.listArchiveDirectory).mockImplementation((_connectionId, _archivePath, virtualPath = "") =>
       Promise.resolve({
         archive: { path: "Archives/backup.zip", size: 1 },
         path: virtualPath,
@@ -1133,7 +1133,7 @@ describe("useFileBrowserPane", () => {
       archive: { path: "backup.zip", size: 1 },
       path: "",
       items: [{ name: "notes.txt", path: "notes.txt", type: FileType.FILE, state: "readable", is_hidden: false }],
-      total: 1,
+
       page_size: 100,
     });
 
@@ -1172,7 +1172,7 @@ describe("useFileBrowserPane", () => {
       archive: { path: "Archives/backup.zip", size: 1 },
       path: "",
       items: [{ name: "notes.txt", path: "notes.txt", type: FileType.FILE, state: "readable", is_hidden: false }],
-      total: 1,
+
       page_size: 100,
     });
 
@@ -1212,7 +1212,7 @@ describe("useFileBrowserPane", () => {
       archive: { path: "backup.zip", size: 1 },
       path: "",
       items: [{ name: "inside.txt", path: "inside.txt", type: FileType.FILE, state: "readable", is_hidden: false }],
-      total: 1,
+
       page_size: 100,
     });
 
@@ -1300,9 +1300,9 @@ describe("useFileBrowserPane", () => {
     await waitFor(() => expect(result.current.files).toHaveLength(3));
 
     const snapshot = deferred<typeof mockDirectoryListing>();
-    const newEntry = { ...mockDirectoryListing.items[2], name: "new-after-snapshot.txt", path: "new-after-snapshot.txt" };
+    const newEntry = { ...requireTestValue(mockDirectoryListing.items[2]), name: "new-after-snapshot.txt", path: "new-after-snapshot.txt" };
     const freshListing = { ...mockDirectoryListing, items: [...mockDirectoryListing.items, newEntry], total: 4 };
-    vi.mocked(api.listDirectory).mockResolvedValue(freshListing).mockReturnValueOnce(snapshot.promise);
+    vi.mocked(api.listDirectory).mockResolvedValue(requireTestValue(freshListing)).mockReturnValueOnce(snapshot.promise);
 
     vi.useFakeTimers();
     try {
@@ -1329,7 +1329,7 @@ describe("useFileBrowserPane", () => {
     vi.mocked(api.listDirectory).mockReturnValueOnce(initialListing.promise).mockReturnValueOnce(refresh.promise);
     const { result } = renderHook(() => useFileBrowserPane({ rowHeight: 40, connections: mockConnections }), { wrapper });
     act(() => result.current.applyLocation("conn-1", ""));
-    const initialSignal = vi.mocked(api.listDirectory).mock.calls[0][2]?.signal;
+    const initialSignal = requireTestValue(vi.mocked(api.listDirectory).mock.calls[0])[2]?.signal;
 
     act(() => result.current.handleDirectoryChanged({ connectionId: "conn-1", path: "" }));
     expect(api.listDirectory).toHaveBeenCalledTimes(1);
@@ -1453,14 +1453,14 @@ describe("useFileBrowserPane", () => {
         archive: { path: "Archives/backup.zip", size: 1 },
         path: "",
         items: [{ name: "before.txt", path: "before.txt", type: FileType.FILE, state: "readable", is_hidden: false }],
-        total: 1,
+
         page_size: 100,
       })
       .mockResolvedValueOnce({
         archive: { path: "Archives/backup.zip", size: 1 },
         path: "",
         items: [{ name: "after.txt", path: "after.txt", type: FileType.FILE, state: "readable", is_hidden: false }],
-        total: 1,
+
         page_size: 100,
       });
 
@@ -1492,14 +1492,14 @@ describe("useFileBrowserPane", () => {
         archive: { path: "backup.zip", size: 1 },
         path: "",
         items: [{ name: "before.txt", path: "before.txt", type: FileType.FILE, state: "readable", is_hidden: false }],
-        total: 1,
+
         page_size: 100,
       })
       .mockResolvedValueOnce({
         archive: { path: "backup.zip", size: 1 },
         path: "",
         items: [{ name: "after.txt", path: "after.txt", type: FileType.FILE, state: "readable", is_hidden: false }],
-        total: 1,
+
         page_size: 100,
       });
 
@@ -1522,12 +1522,12 @@ describe("useFileBrowserPane", () => {
 
   it("exits an archive before switching connections", async () => {
     const archive = { name: "backup.zip", path: "backup.zip", type: FileType.FILE, is_readable: true, is_hidden: false };
-    const otherConnection = { ...mockConnections[0], id: "conn-2", name: "Other Server", slug: "other-server" };
+    const otherConnection = { ...requireTestValue(mockConnections[0]), id: "conn-2", name: "Other Server", slug: "other-server" };
     vi.mocked(api.listArchiveDirectory).mockResolvedValue({
       archive: { path: "Archives/backup.zip", size: 1 },
       path: "",
       items: [{ name: "notes.txt", path: "notes.txt", type: FileType.FILE, state: "readable", is_hidden: false }],
-      total: 1,
+
       page_size: 100,
     });
 
@@ -1565,14 +1565,14 @@ describe("useFileBrowserPane", () => {
         archive: { path: "Archives/backup.zip", size: 1 },
         path: "",
         items: [{ name: "notes.txt", path: "notes.txt", type: FileType.FILE, state: "readable", is_hidden: false }],
-        total: 1,
+
         page_size: 100,
       })
       .mockResolvedValueOnce({
         archive: { path: "Archives/backup.zip", size: 1 },
         path: "",
         items: [{ name: "notes.txt", path: "notes.txt", type: FileType.FILE, state: "blocked", is_hidden: false }],
-        total: 1,
+
         page_size: 100,
       });
 
@@ -1618,7 +1618,7 @@ describe("useFileBrowserPane", () => {
       archive: { path: "backup.zip", size: 1 },
       path: "",
       items: [{ name: "report.txt", path: "report.txt", type: FileType.FILE, state: "readable", is_hidden: false }],
-      total: 1,
+
       page_size: 100,
     });
 
@@ -1669,7 +1669,7 @@ describe("useFileBrowserPane", () => {
       archive: { path: "backup.zip", size: 1 },
       path: "",
       items: [{ name: "inside.png", path: "images/inside.png", type: FileType.FILE, state: "readable", is_hidden: false }],
-      total: 1,
+
       page_size: 100,
     });
 
@@ -1729,7 +1729,7 @@ describe("useFileBrowserPane", () => {
       archive: { path: "backup.zip", size: 1 },
       path: "",
       items: [{ name, path, type: FileType.FILE, state: "readable", is_hidden: false }],
-      total: 1,
+
       page_size: 100,
     });
 
@@ -1784,7 +1784,7 @@ describe("useFileBrowserPane", () => {
       archive: { path: "backup.zip", size: 1 },
       path: "",
       items: [{ name: "inside.sss", path: "files/inside.sss", type: FileType.FILE, state: "readable", is_hidden: false }],
-      total: 1,
+
       page_size: 100,
     });
 
@@ -1828,7 +1828,7 @@ describe("useFileBrowserPane", () => {
       archive: { path: "backup.zip", size: 1 },
       path: "",
       items: [{ name: "nested.zip", path: "archives/nested.zip", type: FileType.FILE, state: "readable", is_hidden: false }],
-      total: 1,
+
       page_size: 100,
     });
 
@@ -1869,7 +1869,7 @@ describe("useFileBrowserPane", () => {
       archive: { path: "backup.zip", size: 1 },
       path: "",
       items: [{ name: "readme.md", path: "docs/readme.md", type: FileType.FILE, state: "readable", is_hidden: false }],
-      total: 1,
+
       page_size: 100,
     });
     vi.mocked(getPreferredViewerId).mockResolvedValueOnce(null).mockResolvedValueOnce("text");
@@ -1935,7 +1935,7 @@ describe("useFileBrowserPane", () => {
       archive: { path: "backup.zip", size: 1 },
       path: "",
       items: [{ name: "readme.md", path: "docs/readme.md", type: FileType.FILE, state: "readable", is_hidden: false }],
-      total: 1,
+
       page_size: 100,
     });
     vi.mocked(getPreferredViewerId).mockResolvedValue(null);
@@ -1989,7 +1989,7 @@ describe("useFileBrowserPane", () => {
         archive: { path: "backup.zip", size: 1 },
         path: "",
         items: [{ name: "first.png", path: "images/first.png", type: FileType.FILE, state: "readable", is_hidden: false }],
-        total: 2,
+
         page_size: 1,
         next_cursor: "page-two",
       })
@@ -1997,7 +1997,7 @@ describe("useFileBrowserPane", () => {
         archive: { path: "backup.zip", size: 1 },
         path: "",
         items: [{ name: "second.png", path: "images/second.png", type: FileType.FILE, state: "readable", is_hidden: false }],
-        total: 2,
+
         page_size: 1,
         next_cursor: null,
       });
@@ -2039,7 +2039,7 @@ describe("useFileBrowserPane", () => {
   });
 
   it("opens the resolved local file rather than its link source", async () => {
-    const localConnection = { ...mockConnections[0], id: "local-drive:c", slug: "c", type: "local" };
+    const localConnection = { ...requireTestValue(mockConnections[0]), id: "local-drive:c", slug: "c", type: "local" };
     const link = {
       name: "Report.lnk",
       path: "Report.lnk",
@@ -2090,7 +2090,7 @@ describe("useFileBrowserPane", () => {
   });
 
   it("opens a resolved local link target with the native app", async () => {
-    const localConnection = { ...mockConnections[0], id: "local-drive:c", slug: "c", type: "local" };
+    const localConnection = { ...requireTestValue(mockConnections[0]), id: "local-drive:c", slug: "c", type: "local" };
     const link = {
       name: "Report.lnk",
       path: "Report.lnk",
@@ -2135,7 +2135,7 @@ describe("useFileBrowserPane", () => {
   });
 
   it("shows a link-resolution error without opening the source file", async () => {
-    const localConnection = { ...mockConnections[0], id: "local-drive:c", slug: "c", type: "local" };
+    const localConnection = { ...requireTestValue(mockConnections[0]), id: "local-drive:c", slug: "c", type: "local" };
     const link = {
       name: "Missing.lnk",
       path: "Missing.lnk",
@@ -2175,7 +2175,7 @@ describe("useFileBrowserPane", () => {
   });
 
   it("ignores a local activation result after navigation supersedes it", async () => {
-    const localConnection = { ...mockConnections[0], id: "local-drive:c", slug: "c", type: "local" };
+    const localConnection = { ...requireTestValue(mockConnections[0]), id: "local-drive:c", slug: "c", type: "local" };
     const link = {
       name: "Report.lnk",
       path: "Report.lnk",
@@ -2238,7 +2238,7 @@ describe("useFileBrowserPane", () => {
   });
 
   it("ignores deferred viewer selection for a superseded local activation", async () => {
-    const localConnection = { ...mockConnections[0], id: "local-drive:c", slug: "c", type: "local" };
+    const localConnection = { ...requireTestValue(mockConnections[0]), id: "local-drive:c", slug: "c", type: "local" };
     const link = {
       name: "Report.lnk",
       path: "Report.lnk",
@@ -2304,8 +2304,8 @@ describe("useFileBrowserPane", () => {
   });
 
   it("lets a non-local recent file supersede a pending local link activation", async () => {
-    const localConnection = { ...mockConnections[0], id: "local-drive:c", slug: "c", type: "local" };
-    const remoteConnection = { ...mockConnections[0], id: "conn-2", slug: "archive", name: "Archive" };
+    const localConnection = { ...requireTestValue(mockConnections[0]), id: "local-drive:c", slug: "c", type: "local" };
+    const remoteConnection = { ...requireTestValue(mockConnections[0]), id: "conn-2", slug: "archive", name: "Archive" };
     const link = {
       name: "Report.lnk",
       path: "Report.lnk",
@@ -2615,7 +2615,7 @@ describe("useFileBrowserPane", () => {
   });
 
   it("removes a local recent record only when Companion confirms its target is missing", async () => {
-    const localConnection = { ...mockConnections[0], id: "local-drive:c", slug: "c", type: "local" };
+    const localConnection = { ...requireTestValue(mockConnections[0]), id: "local-drive:c", slug: "c", type: "local" };
     vi.mocked(api.resolveLocalActivation).mockRejectedValue({
       response: { data: { code: "local_link_target_missing" }, status: 404 },
     });
@@ -2640,7 +2640,7 @@ describe("useFileBrowserPane", () => {
   });
 
   it("preserves a local recent record when Companion is unavailable", async () => {
-    const localConnection = { ...mockConnections[0], id: "local-drive:c", slug: "c", type: "local" };
+    const localConnection = { ...requireTestValue(mockConnections[0]), id: "local-drive:c", slug: "c", type: "local" };
     vi.mocked(api.resolveLocalActivation).mockRejectedValue({
       response: { data: { detail: "Unknown drive" }, status: 404 },
     });
@@ -2666,7 +2666,7 @@ describe("useFileBrowserPane", () => {
     ["recent_file_native_launch_failed", "Failed to launch the native application."],
     ["recent_file_target_not_file", "Not a file: Documents/report.txt"],
   ])("removes a local recent record after a classified %s native-open failure", async (code, detail) => {
-    const localConnection = { ...mockConnections[0], id: "local-drive:c", slug: "c", type: "local" };
+    const localConnection = { ...requireTestValue(mockConnections[0]), id: "local-drive:c", slug: "c", type: "local" };
     vi.mocked(api.resolveLocalActivation).mockResolvedValue({
       drive_id: "c",
       path: "Documents/report.txt",
@@ -2705,7 +2705,7 @@ describe("useFileBrowserPane", () => {
   });
 
   it("opens a local recent shortcut at its resolved file target", async () => {
-    const sourceConnection = { ...mockConnections[0], id: "local-drive:c", slug: "c", type: "local" };
+    const sourceConnection = { ...requireTestValue(mockConnections[0]), id: "local-drive:c", slug: "c", type: "local" };
     vi.mocked(api.resolveLocalActivation).mockResolvedValue({
       drive_id: "d",
       path: "Reports/quarterly.pdf",
@@ -2742,7 +2742,7 @@ describe("useFileBrowserPane", () => {
   });
 
   it("navigates to a directory resolved from a local recent shortcut", async () => {
-    const sourceConnection = { ...mockConnections[0], id: "local-drive:c", slug: "c", type: "local" };
+    const sourceConnection = { ...requireTestValue(mockConnections[0]), id: "local-drive:c", slug: "c", type: "local" };
     const onNavigateDirectory = vi.fn();
     vi.mocked(api.resolveLocalActivation).mockResolvedValue({
       drive_id: "d",
@@ -2775,7 +2775,7 @@ describe("useFileBrowserPane", () => {
   });
 
   it("ignores a recent local activation result after navigation supersedes it", async () => {
-    const localConnection = { ...mockConnections[0], id: "local-drive:c", slug: "c", type: "local" };
+    const localConnection = { ...requireTestValue(mockConnections[0]), id: "local-drive:c", slug: "c", type: "local" };
     let resolveActivation!: (value: Awaited<ReturnType<typeof api.resolveLocalActivation>>) => void;
     vi.mocked(api.resolveLocalActivation).mockImplementation(
       () =>
@@ -2831,7 +2831,10 @@ describe("useFileBrowserPane", () => {
   });
 
   it("opens an image recent outside the active pane without reusing its gallery", async () => {
-    const viewerConnections = [mockConnections[0], { ...mockConnections[0], id: "conn-2", name: "Archive", slug: "archive" }];
+    const viewerConnections = [
+      requireTestValue(mockConnections[0]),
+      { ...requireTestValue(mockConnections[0]), id: "conn-2", name: "Archive", slug: "archive" },
+    ];
     vi.mocked(api.validateRecentFileTarget).mockResolvedValue({
       name: "outside.png",
       path: "outside.png",
diff --git a/frontend/src/services/__tests__/api.test.ts b/frontend/src/services/__tests__/api.test.ts
index ea9838b82..0a564681b 100644
--- a/frontend/src/services/__tests__/api.test.ts
+++ b/frontend/src/services/__tests__/api.test.ts
@@ -1,5 +1,6 @@
 import type { AxiosResponse } from "axios";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { createMockAuthToken } from "../../test/fixtures/users";
 import type {
   AdvancedSystemSettings,
   AuthToken,
@@ -47,7 +48,12 @@ vi.mock("axios", () => {
 // Get reference to the mocked functions for assertions
 import axios from "axios";
 // Now import the API service (it will use the mocked axios.create)
-import apiService, { ExpiredEditLockError, OIDC_FINALIZATION_REQUEST_TIMEOUT_MS, setOidcExchangePending } from "../api";
+import apiService, {
+  ExpiredEditLockError,
+  OIDC_FINALIZATION_REQUEST_TIMEOUT_MS,
+  setOidcExchangePending,
+  startControlledReauthentication,
+} from "../api";
 import { AuthSessionError, authSession } from "../authSession";
 import { getBackendAvailabilitySnapshot, markBackendUnavailable, resetBackendAvailabilityForTests } from "../backendAvailability";
 import * as backendRouter from "../backendRouter";
@@ -65,7 +71,10 @@ const mockAxiosInstance = mockedAxios.create() as ReturnType<typeof mockedAxios.
 };
 const requestInterceptorUse = vi.mocked(mockAxiosInstance.interceptors.request.use);
 const requestInterceptorHandlers = requestInterceptorUse.mock.calls[0] as
-  | [((config: { url?: string; headers: Record<string, string> }) => Promise<unknown>)?, ((error: unknown) => Promise<never>)?]
+  | [
+      ((config: { url?: string; method?: string; headers: Record<string, string> }) => Promise<unknown>)?,
+      ((error: unknown) => Promise<never>)?,
+    ]
   | undefined;
 const requestHandler = requestInterceptorHandlers?.[0];
 const responseInterceptorUse = vi.mocked(mockAxiosInstance.interceptors.response.use);
@@ -129,9 +138,9 @@ describe("API Service", () => {
 
   describe("OIDC request classification", () => {
     it.each(["oidc_reauthentication_required", undefined])("ignores obsolete token 401s (%s)", async (code) => {
-      authSession.setAuthenticated({ access_token: "session-a", token_type: "bearer", user_id: "same-user" }, true);
+      authSession.setAuthenticated(createMockAuthToken({ access_token: "session-a", token_type: "bearer", user_id: "same-user" }), true);
       const request = (await requestHandler?.({ url: "/themes", method: "get", headers: {} })) as { headers: Record<string, string> };
-      authSession.setAuthenticated({ access_token: "session-b", token_type: "bearer", user_id: "same-user" }, true);
+      authSession.setAuthenticated(createMockAuthToken({ access_token: "session-b", token_type: "bearer", user_id: "same-user" }), true);
       markBackendUnavailable("Recovery in progress");
       const availabilityBeforeFailure = getBackendAvailabilitySnapshot();
       const refresh = vi.spyOn(authSession, "requestRefresh");
@@ -150,14 +159,16 @@ describe("API Service", () => {
       const currentRequest = (await requestHandler?.({ url: "/themes", method: "get", headers: {} })) as {
         headers: Record<string, string>;
       };
-      expect(currentRequest.headers.Authorization).toBe("Bearer session-b");
+      expect(currentRequest.headers["Authorization"]).toBe("Bearer session-b");
       responseSuccessHandler?.({ config: { method: "get", url: "/themes" }, status: 200, statusText: "OK" } as never);
       expect(window.location.assign).not.toHaveBeenCalled();
     });
 
     it("keeps current-token 401 handling and never replays a write", async () => {
-      authSession.setAuthenticated({ access_token: "session-b", token_type: "bearer" }, true);
-      const refresh = vi.spyOn(authSession, "requestRefresh").mockResolvedValue({ access_token: "renewed", token_type: "bearer" });
+      authSession.setAuthenticated(createMockAuthToken({ access_token: "session-b", token_type: "bearer" }), true);
+      const refresh = vi
+        .spyOn(authSession, "requestRefresh")
+        .mockResolvedValue(createMockAuthToken({ access_token: "renewed", token_type: "bearer" }));
       const error = {
         response: { status: 401, headers: {} },
         message: "Unauthorized",
@@ -173,7 +184,7 @@ describe("API Service", () => {
     });
 
     it.each(["success", "failure"])("does not act on A's 401 when its refresh settles after B (%s)", async (outcome) => {
-      authSession.setAuthenticated({ access_token: "session-a", token_type: "bearer" }, true);
+      authSession.setAuthenticated(createMockAuthToken({ access_token: "session-a", token_type: "bearer" }), true);
       let finishRefresh!: (response: AuthToken) => void;
       let failRefresh!: (reason: Error) => void;
       const refresh = new Promise<AuthToken>((resolve, reject) => {
@@ -188,8 +199,8 @@ describe("API Service", () => {
         config: { url: "/themes", method: "get", headers: { Authorization: "Bearer session-a" } },
       };
       const pending = responseErrorHandler?.(error as never);
-      authSession.setAuthenticated({ access_token: "session-b", token_type: "bearer" }, true);
-      if (outcome === "success") finishRefresh({ access_token: "old-refresh", token_type: "bearer" });
+      authSession.setAuthenticated(createMockAuthToken({ access_token: "session-b", token_type: "bearer" }), true);
+      if (outcome === "success") finishRefresh(createMockAuthToken({ access_token: "old-refresh", token_type: "bearer" }));
       else failRefresh(new Error("Refresh failed"));
 
       await expect(pending).rejects.toBe(error);
@@ -206,9 +217,9 @@ describe("API Service", () => {
           failRefresh = reject;
         })
       );
-      authSession.setAuthenticated({ access_token: "session-a", token_type: "bearer" }, true);
+      authSession.setAuthenticated(createMockAuthToken({ access_token: "session-a", token_type: "bearer" }), true);
       const request = requestHandler?.({ url: "/themes", method: "get", headers: {} });
-      authSession.setAuthenticated({ access_token: "session-b", token_type: "bearer" }, true);
+      authSession.setAuthenticated(createMockAuthToken({ access_token: "session-b", token_type: "bearer" }), true);
       failRefresh(new AuthSessionError("reauthentication-required", "Session expired"));
       await expect(request).rejects.toMatchObject({ code: "reauthentication-required" });
       expect(window.location.assign).not.toHaveBeenCalled();
@@ -285,20 +296,35 @@ describe("API Service", () => {
       expect(authSession.requestRefresh).not.toHaveBeenCalled();
     });
 
+    it("attempts a synchronous snapshot before sign-in without requiring a storage acknowledgement", () => {
+      const snapshot = vi.fn(() => {
+        expect(window.location.assign).not.toHaveBeenCalled();
+        return { saved: false as const, reason: "storage-unavailable" as const };
+      });
+      const unregister = draftRecovery.registerDraftSnapshot(snapshot);
+      try {
+        startControlledReauthentication();
+        expect(snapshot).toHaveBeenCalledOnce();
+        expect(window.location.assign).toHaveBeenCalledOnce();
+      } finally {
+        unregister();
+      }
+    });
+
     it("preserves drafts and the browse return path at a no-refresh deadline", async () => {
       vi.spyOn(authSession, "refreshIfNeeded").mockRestore();
       const originalPathname = window.location.pathname;
       const originalSearch = window.location.search;
       const deadline = Date.now() + 30_000;
       authSession.setAuthenticated(
-        {
+        createMockAuthToken({
           access_token: "expiring-token",
           token_type: "bearer",
           user_id: "user-1",
           oidc_session_capability: "reauthorization_only",
           oidc_session_expires_at: new Date(deadline).toISOString(),
           access_token_expires_at: new Date(deadline).toISOString(),
-        },
+        }),
         true
       );
       const snapshotDrafts = vi.spyOn(draftRecovery, "snapshotRegisteredDrafts");
@@ -328,6 +354,7 @@ describe("API Service", () => {
     await apiService.finalizeOidcConfiguration(
       "flow-id",
       {
+        no_refresh_session_limit_hours: 8,
         sign_in_mode: "oidc_only",
         interactive_reauthentication_max_age_days: 30,
         admission_mode: "selected_groups",
@@ -349,6 +376,7 @@ describe("API Service", () => {
         reviewed_policy: {
           sign_in_mode: "oidc_only",
           interactive_reauthentication_max_age_days: 30,
+          no_refresh_session_limit_hours: 8,
           admission_mode: "selected_groups",
           admission_groups: ["users"],
           role_assignment_mode: "uniform",
diff --git a/frontend/src/services/__tests__/authApi.test.ts b/frontend/src/services/__tests__/authApi.test.ts
index 8e57a043f..294f7a2d5 100644
--- a/frontend/src/services/__tests__/authApi.test.ts
+++ b/frontend/src/services/__tests__/authApi.test.ts
@@ -1,3 +1,4 @@
+import { requireTestValue } from "../../test/helpers/assertions";
 /**
  * Contract tests for Authentication API
  *
@@ -287,7 +288,7 @@ describe("Authentication API Contract Tests", () => {
       await apiService.changePassword("current123", "new456");
 
       // Verify request structure
-      const callArgs = mockAxiosInstance.post.mock.calls[0];
+      const callArgs = requireTestValue(mockAxiosInstance.post.mock.calls[0]);
       expect(callArgs[0]).toBe("/auth/change-password");
       expect(callArgs[1]).toEqual({
         current_password: "current123",
diff --git a/frontend/src/services/__tests__/authSession.test.ts b/frontend/src/services/__tests__/authSession.test.ts
index ad9a99f34..9824be4f0 100644
--- a/frontend/src/services/__tests__/authSession.test.ts
+++ b/frontend/src/services/__tests__/authSession.test.ts
@@ -1,5 +1,6 @@
 import { HttpResponse, http } from "msw";
 import { afterEach, describe, expect, it, vi } from "vitest";
+import { createMockAuthToken } from "../../test/fixtures/users";
 import { server } from "../../test/mocks/server";
 import { type AuthSessionError, AuthSessionManager } from "../authSession";
 
@@ -23,16 +24,16 @@ describe("AuthSessionManager", () => {
     );
     session = new AuthSessionManager();
     session.setAuthenticated(
-      {
+      createMockAuthToken({
         access_token: "still-usable-token",
         token_type: "bearer",
         access_token_expires_at: new Date(Date.now() + 60_000).toISOString(),
         oidc_refresh_generation: 7,
-      },
+      }),
       true
     );
 
-    await expect(session.requestRefresh()).rejects.toMatchObject<AuthSessionError>({ code: "refresh-uncertain" });
+    await expect(session.requestRefresh()).rejects.toMatchObject<Partial<AuthSessionError>>({ code: "refresh-uncertain" });
 
     expect(session.getState()).toBe("refresh-uncertain");
     expect(session.getAccessToken()).toBe("still-usable-token");
@@ -45,20 +46,20 @@ describe("AuthSessionManager", () => {
     const redirect = vi.fn();
     session.setReauthenticationHandler(redirect);
     session.setAuthenticated(
-      {
+      createMockAuthToken({
         access_token: "no-refresh-token",
         token_type: "bearer",
         user_id: "user-1",
         oidc_session_capability: "reauthorization_only",
         oidc_session_expires_at: new Date(deadline).toISOString(),
         access_token_expires_at: new Date(deadline).toISOString(),
-      },
+      }),
       true
     );
     expect(session.hasUsableAccessToken()).toBe(true);
     const clock = vi.spyOn(Date, "now").mockReturnValue(deadline);
     try {
-      await expect(session.refreshIfNeeded()).rejects.toMatchObject<AuthSessionError>({ code: "reauthentication-required" });
+      await expect(session.refreshIfNeeded()).rejects.toMatchObject<Partial<AuthSessionError>>({ code: "reauthentication-required" });
       expect(session.hasUsableAccessToken()).toBe(false);
       expect(redirect).toHaveBeenCalledOnce();
     } finally {
@@ -77,13 +78,13 @@ describe("AuthSessionManager", () => {
     );
     session = new AuthSessionManager();
     session.setAuthenticated(
-      {
+      createMockAuthToken({
         access_token: "old-session",
         token_type: "bearer",
         user_id: "user-1",
         oidc_session_expires_at: new Date(deadline).toISOString(),
         access_token_expires_at: new Date(deadline).toISOString(),
-      },
+      }),
       true
     );
     const clock = vi.spyOn(Date, "now").mockReturnValue(deadline);
@@ -113,7 +114,7 @@ describe("AuthSessionManager", () => {
       })
     );
     session = new AuthSessionManager();
-    session.setAuthenticated({ access_token: "expired-session", token_type: "bearer", user_id: "user-1" }, true);
+    session.setAuthenticated(createMockAuthToken({ access_token: "expired-session", token_type: "bearer", user_id: "user-1" }), true);
     const oldRefresh = session.requestRefresh();
     const oldFailure = expect(oldRefresh).rejects.toThrow();
     await vi.waitFor(() => expect(refreshRequests).toBe(1));
@@ -159,10 +160,10 @@ describe("AuthSessionManager", () => {
     const identities: Array<{ epoch: number; userId: string | null }> = [];
     session.subscribeToIdentity((identity) => identities.push(identity));
 
-    session.setAuthenticated({ access_token: "first-token", token_type: "bearer", user_id: "user-1" }, true);
-    session.setAuthenticated({ access_token: "refreshed-token", token_type: "bearer", user_id: "user-1" }, true);
+    session.setAuthenticated(createMockAuthToken({ access_token: "first-token", token_type: "bearer", user_id: "user-1" }), true);
+    session.setAuthenticated(createMockAuthToken({ access_token: "refreshed-token", token_type: "bearer", user_id: "user-1" }), true);
     session.clear();
-    session.setAuthenticated({ access_token: "second-token", token_type: "bearer", user_id: "user-1" }, true);
+    session.setAuthenticated(createMockAuthToken({ access_token: "second-token", token_type: "bearer", user_id: "user-1" }), true);
 
     expect(identities).toEqual([
       { epoch: 1, userId: "user-1" },
@@ -189,7 +190,7 @@ describe("AuthSessionManager", () => {
     session.subscribeToIdentity(({ epoch }) => identities.push(epoch));
     const bootstrap = session.bootstrap();
     await vi.waitFor(() => expect(session?.getState()).toBe("refreshing"));
-    session.setAuthenticated({ access_token: "new-session", token_type: "bearer", user_id: "same-user" }, true);
+    session.setAuthenticated(createMockAuthToken({ access_token: "new-session", token_type: "bearer", user_id: "same-user" }), true);
     session.completeLoginBootstrap();
     finishRefresh();
     await bootstrap;
@@ -224,13 +225,13 @@ describe("AuthSessionManager", () => {
       })
     );
     session = new AuthSessionManager();
-    session.setAuthenticated({ access_token: "session-a", token_type: "bearer", user_id: "same-user" }, true);
+    session.setAuthenticated(createMockAuthToken({ access_token: "session-a", token_type: "bearer", user_id: "same-user" }), true);
     const oldRefresh = session.requestRefresh();
     const oldFailure = expect(oldRefresh).rejects.toThrow();
     await vi.waitFor(() => expect(requests).toBe(1));
 
     session.beginNewLogin();
-    session.setAuthenticated({ access_token: "session-b", token_type: "bearer", user_id: "same-user" }, true);
+    session.setAuthenticated(createMockAuthToken({ access_token: "session-b", token_type: "bearer", user_id: "same-user" }), true);
     const newRefresh = session.requestRefresh();
     await vi.waitFor(() => expect(requests).toBe(2));
     releaseOld();
@@ -267,11 +268,11 @@ describe("AuthSessionManager", () => {
       })
     );
     session = new AuthSessionManager();
-    session.setAuthenticated({ access_token: "session-a", token_type: "bearer" }, true);
+    session.setAuthenticated(createMockAuthToken({ access_token: "session-a", token_type: "bearer" }), true);
     const oldRefresh = session.requestRefresh();
     const oldFailure = expect(oldRefresh).rejects.toThrow();
     session.beginNewLogin();
-    session.setAuthenticated({ access_token: "session-b", token_type: "bearer" }, true);
+    session.setAuthenticated(createMockAuthToken({ access_token: "session-b", token_type: "bearer" }), true);
     releaseLock();
 
     await oldFailure;
diff --git a/frontend/src/services/__tests__/connectionApi.test.ts b/frontend/src/services/__tests__/connectionApi.test.ts
index 137ad01ae..8632481cb 100644
--- a/frontend/src/services/__tests__/connectionApi.test.ts
+++ b/frontend/src/services/__tests__/connectionApi.test.ts
@@ -1,3 +1,5 @@
+import { createMockConnection } from "../../test/fixtures/connections";
+import { requireTestValue } from "../../test/helpers/assertions";
 /**
  * Contract tests for Connection Management API
  *
@@ -55,7 +57,7 @@ describe("Connection Management API Contract Tests", () => {
   describe("Contract Tests - GET /connections", () => {
     it("should return array of connections", async () => {
       const backendResponse: Connection[] = [
-        {
+        createMockConnection({
           id: "123e4567-e89b-12d3-a456-426614174000",
           name: "Test Server",
           type: "smb",
@@ -66,7 +68,7 @@ describe("Connection Management API Contract Tests", () => {
           path_prefix: "/",
           created_at: "2024-01-01T00:00:00Z",
           updated_at: "2024-01-01T00:00:00Z",
-        },
+        }),
       ];
 
       mockAxiosInstance.get.mockResolvedValueOnce({
@@ -82,7 +84,7 @@ describe("Connection Management API Contract Tests", () => {
 
     it("should include all required connection fields", async () => {
       const backendResponse: Connection[] = [
-        {
+        createMockConnection({
           id: "123e4567-e89b-12d3-a456-426614174000",
           name: "Test Server",
           type: "smb",
@@ -93,7 +95,7 @@ describe("Connection Management API Contract Tests", () => {
           path_prefix: "/data",
           created_at: "2024-01-01T12:30:00Z",
           updated_at: "2024-01-02T08:15:00Z",
-        },
+        }),
       ];
 
       mockAxiosInstance.get.mockResolvedValueOnce({
@@ -118,7 +120,7 @@ describe("Connection Management API Contract Tests", () => {
 
     it("should have correct field types", async () => {
       const backendResponse: Connection[] = [
-        {
+        createMockConnection({
           id: "123e4567-e89b-12d3-a456-426614174000",
           name: "Test Server",
           type: "smb",
@@ -129,7 +131,7 @@ describe("Connection Management API Contract Tests", () => {
           path_prefix: "/",
           created_at: "2024-01-01T00:00:00Z",
           updated_at: "2024-01-01T00:00:00Z",
-        },
+        }),
       ];
 
       mockAxiosInstance.get.mockResolvedValueOnce({
@@ -137,7 +139,7 @@ describe("Connection Management API Contract Tests", () => {
       } as AxiosResponse);
 
       const result = await apiService.getConnections();
-      const conn = result[0];
+      const conn = requireTestValue(result[0]);
 
       // Verify types
       expect(typeof conn.id).toBe("string");
@@ -155,7 +157,7 @@ describe("Connection Management API Contract Tests", () => {
     it("should parse UUID strings correctly", async () => {
       const uuid = "123e4567-e89b-12d3-a456-426614174000";
       const backendResponse: Connection[] = [
-        {
+        createMockConnection({
           id: uuid,
           name: "Test",
           type: "smb",
@@ -166,7 +168,7 @@ describe("Connection Management API Contract Tests", () => {
           path_prefix: "/",
           created_at: "2024-01-01T00:00:00Z",
           updated_at: "2024-01-01T00:00:00Z",
-        },
+        }),
       ];
 
       mockAxiosInstance.get.mockResolvedValueOnce({
@@ -176,13 +178,13 @@ describe("Connection Management API Contract Tests", () => {
       const result = await apiService.getConnections();
 
       // UUID should be a valid UUID string
-      expect(result[0].id).toBe(uuid);
-      expect(result[0].id).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i);
+      expect(requireTestValue(result[0]).id).toBe(uuid);
+      expect(requireTestValue(result[0]).id).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i);
     });
 
     it("should parse ISO 8601 timestamps", async () => {
       const backendResponse: Connection[] = [
-        {
+        createMockConnection({
           id: "123e4567-e89b-12d3-a456-426614174000",
           name: "Test",
           type: "smb",
@@ -193,7 +195,7 @@ describe("Connection Management API Contract Tests", () => {
           path_prefix: "/",
           created_at: "2024-01-15T10:30:45Z",
           updated_at: "2024-02-20T14:25:30.123Z",
-        },
+        }),
       ];
 
       mockAxiosInstance.get.mockResolvedValueOnce({
@@ -203,12 +205,12 @@ describe("Connection Management API Contract Tests", () => {
       const result = await apiService.getConnections();
 
       // Timestamps should be ISO 8601 strings
-      expect(result[0].created_at).toBe("2024-01-15T10:30:45Z");
-      expect(result[0].updated_at).toBe("2024-02-20T14:25:30.123Z");
+      expect(requireTestValue(result[0]).created_at).toBe("2024-01-15T10:30:45Z");
+      expect(requireTestValue(result[0]).updated_at).toBe("2024-02-20T14:25:30.123Z");
 
       // Should be parseable as dates
-      expect(new Date(result[0].created_at).toISOString()).toBeTruthy();
-      expect(new Date(result[0].updated_at).toISOString()).toBeTruthy();
+      expect(new Date(requireTestValue(result[0]).created_at).toISOString()).toBeTruthy();
+      expect(new Date(requireTestValue(result[0]).updated_at).toISOString()).toBeTruthy();
     });
 
     it("should handle empty connections array", async () => {
@@ -224,7 +226,7 @@ describe("Connection Management API Contract Tests", () => {
 
     it("should handle multiple connections", async () => {
       const backendResponse: Connection[] = [
-        {
+        createMockConnection({
           id: "123e4567-e89b-12d3-a456-426614174000",
           name: "Server 1",
           type: "smb",
@@ -235,8 +237,8 @@ describe("Connection Management API Contract Tests", () => {
           path_prefix: "/",
           created_at: "2024-01-01T00:00:00Z",
           updated_at: "2024-01-01T00:00:00Z",
-        },
-        {
+        }),
+        createMockConnection({
           id: "223e4567-e89b-12d3-a456-426614174001",
           name: "Server 2",
           type: "smb",
@@ -247,7 +249,7 @@ describe("Connection Management API Contract Tests", () => {
           path_prefix: "/data",
           created_at: "2024-01-02T00:00:00Z",
           updated_at: "2024-01-02T00:00:00Z",
-        },
+        }),
       ];
 
       mockAxiosInstance.get.mockResolvedValueOnce({
@@ -257,8 +259,8 @@ describe("Connection Management API Contract Tests", () => {
       const result = await apiService.getConnections();
 
       expect(result).toHaveLength(2);
-      expect(result[0].name).toBe("Server 1");
-      expect(result[1].name).toBe("Server 2");
+      expect(requireTestValue(result[0]).name).toBe("Server 1");
+      expect(requireTestValue(result[1]).name).toBe("Server 2");
     });
   });
 
@@ -277,7 +279,7 @@ describe("Connection Management API Contract Tests", () => {
         access_mode: "read_write",
       };
 
-      const backendResponse: Connection = {
+      const backendResponse: Connection = createMockConnection({
         id: "323e4567-e89b-12d3-a456-426614174002",
         name: "New Server",
         type: "smb",
@@ -291,7 +293,7 @@ describe("Connection Management API Contract Tests", () => {
         can_manage: true,
         created_at: "2024-03-01T10:00:00Z",
         updated_at: "2024-03-01T10:00:00Z",
-      };
+      });
 
       mockAxiosInstance.post.mockResolvedValueOnce({
         data: backendResponse,
@@ -320,7 +322,7 @@ describe("Connection Management API Contract Tests", () => {
         access_mode: "read_write",
       };
 
-      const backendResponse: Connection = {
+      const backendResponse: Connection = createMockConnection({
         id: "423e4567-e89b-12d3-a456-426614174003",
         name: "Test",
         type: "smb",
@@ -334,7 +336,7 @@ describe("Connection Management API Contract Tests", () => {
         can_manage: true,
         created_at: "2024-03-01T10:00:00Z",
         updated_at: "2024-03-01T10:00:00Z",
-      };
+      });
 
       mockAxiosInstance.post.mockResolvedValueOnce({
         data: backendResponse,
@@ -361,7 +363,7 @@ describe("Connection Management API Contract Tests", () => {
         access_mode: "read_write",
       };
 
-      const backendResponse: Connection = {
+      const backendResponse: Connection = createMockConnection({
         id: "523e4567-e89b-12d3-a456-426614174004",
         name: "Test",
         type: "smb",
@@ -375,7 +377,7 @@ describe("Connection Management API Contract Tests", () => {
         can_manage: true,
         created_at: "2024-03-01T10:00:00Z",
         updated_at: "2024-03-01T10:00:00Z",
-      };
+      });
 
       mockAxiosInstance.post.mockResolvedValueOnce({
         data: backendResponse,
@@ -405,7 +407,7 @@ describe("Connection Management API Contract Tests", () => {
         share_name: "updated_share",
       };
 
-      const backendResponse: Connection = {
+      const backendResponse: Connection = createMockConnection({
         id: connectionId,
         name: "Updated Name",
         type: "smb",
@@ -419,7 +421,7 @@ describe("Connection Management API Contract Tests", () => {
         can_manage: true,
         created_at: "2024-01-01T00:00:00Z",
         updated_at: "2024-03-01T15:00:00Z", // Updated timestamp
-      };
+      });
 
       mockAxiosInstance.put.mockResolvedValueOnce({
         data: backendResponse,
@@ -438,7 +440,7 @@ describe("Connection Management API Contract Tests", () => {
       const originalTimestamp = "2024-01-01T00:00:00Z";
       const updatedTimestamp = "2024-03-01T16:30:00Z";
 
-      const backendResponse: Connection = {
+      const backendResponse: Connection = createMockConnection({
         id: connectionId,
         name: "Test",
         type: "smb",
@@ -452,7 +454,7 @@ describe("Connection Management API Contract Tests", () => {
         can_manage: true,
         created_at: originalTimestamp,
         updated_at: updatedTimestamp,
-      };
+      });
 
       mockAxiosInstance.put.mockResolvedValueOnce({
         data: backendResponse,
@@ -471,7 +473,7 @@ describe("Connection Management API Contract Tests", () => {
     it("should match Connection type structure", async () => {
       const connectionId = "823e4567-e89b-12d3-a456-426614174007";
 
-      const backendResponse: Connection = {
+      const backendResponse: Connection = createMockConnection({
         id: connectionId,
         name: "Test",
         type: "smb",
@@ -485,7 +487,7 @@ describe("Connection Management API Contract Tests", () => {
         can_manage: true,
         created_at: "2024-01-01T00:00:00Z",
         updated_at: "2024-03-01T00:00:00Z",
-      };
+      });
 
       mockAxiosInstance.put.mockResolvedValueOnce({
         data: backendResponse,
@@ -622,6 +624,8 @@ describe("Connection Management API Contract Tests", () => {
 
     it("should handle validation errors on create", async () => {
       const invalidConnection: ConnectionCreate = {
+        scope: "private",
+        access_mode: "read_write",
         name: "",
         type: "smb",
         host: "",
diff --git a/frontend/src/services/__tests__/draftCheckpoint.test.ts b/frontend/src/services/__tests__/draftCheckpoint.test.ts
new file mode 100644
index 000000000..97fc7d154
--- /dev/null
+++ b/frontend/src/services/__tests__/draftCheckpoint.test.ts
@@ -0,0 +1,186 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const { getIdentity, getUserId } = vi.hoisted(() => ({ getIdentity: vi.fn(), getUserId: vi.fn() }));
+vi.mock("../authSession", () => ({ authSession: { getIdentity, getUserId } }));
+
+import {
+  createDraftCheckpointController,
+  DRAFT_CHECKPOINT_LAG_MS,
+  DRAFT_CHECKPOINT_START_MS,
+  type DraftCheckpointContent,
+} from "../draftCheckpoint";
+import { clearDraft, loadDraft } from "../draftRecovery";
+
+const USER_ID = "checkpoint-user";
+const CONNECTION_ID = "connection";
+const PATH = "notes/a.md";
+const content = (value: string): DraftCheckpointContent => ({ baseline: "saved", content: value });
+
+function deferredSnapshot() {
+  let resolve!: (snapshot: DraftCheckpointContent) => void;
+  let reject!: (error: Error) => void;
+  const promise = new Promise<DraftCheckpointContent>((finish, fail) => {
+    resolve = finish;
+    reject = fail;
+  });
+  return { promise, resolve, reject };
+}
+
+describe("revisioned draft checkpoints", () => {
+  let controller: ReturnType<typeof createDraftCheckpointController>;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    sessionStorage.clear();
+    getUserId.mockReturnValue(USER_ID);
+    getIdentity.mockImplementation(() => ({ userId: getUserId(), epoch: 0 }));
+    controller = createDraftCheckpointController(CONNECTION_ID, PATH, "markdown");
+  });
+
+  afterEach(() => {
+    controller.dispose();
+    vi.restoreAllMocks();
+    vi.useRealTimers();
+  });
+
+  it("coalesces sustained edits without resetting the oldest edit's start deadline", async () => {
+    const obsolete = vi.fn(async () => content("obsolete"));
+    const latest = vi.fn(async () => content("latest"));
+    controller.request(1, obsolete);
+    await vi.advanceTimersByTimeAsync(DRAFT_CHECKPOINT_START_MS / 2);
+    controller.request(2, latest);
+    await vi.advanceTimersByTimeAsync(DRAFT_CHECKPOINT_START_MS / 2);
+
+    expect(obsolete).not.toHaveBeenCalled();
+    expect(latest).toHaveBeenCalledOnce();
+    expect(controller.getOutcome()).toEqual({ saved: true, revision: 2 });
+    expect(loadDraft(CONNECTION_ID, PATH, "markdown")?.content).toBe("latest");
+  });
+
+  it("flushes the captured latest revision immediately rather than waiting for the start timer", async () => {
+    controller.request(1, async () => content("latest edit"));
+
+    await expect(controller.flush()).resolves.toEqual({ saved: true, revision: 1 });
+    expect(loadDraft(CONNECTION_ID, PATH, "markdown")?.content).toBe("latest edit");
+    expect(vi.getTimerCount()).toBe(0);
+  });
+
+  it("performs no redundant persistence when flushing an untouched session", async () => {
+    const write = vi.spyOn(Storage.prototype, "setItem");
+
+    await expect(controller.flush()).resolves.toEqual({ saved: true, revision: null });
+    expect(write).not.toHaveBeenCalled();
+  });
+
+  it("waits for pending latest edits when an older snapshot is already in flight", async () => {
+    const older = deferredSnapshot();
+    controller.request(1, () => older.promise);
+    await vi.advanceTimersByTimeAsync(DRAFT_CHECKPOINT_START_MS);
+    controller.request(2, async () => content("newer edit"));
+    const flush = controller.flush();
+    older.resolve(content("older edit"));
+
+    await expect(flush).resolves.toEqual({ saved: true, revision: 2 });
+    expect(loadDraft(CONNECTION_ID, PATH, "markdown")?.content).toBe("newer edit");
+  });
+
+  it("times out a stalled checkpoint, aborts preparation, and ignores late completion", async () => {
+    const stalled = deferredSnapshot();
+    let signal: AbortSignal | undefined;
+    controller.request(1, (capturedSignal) => {
+      signal = capturedSignal;
+      return stalled.promise;
+    });
+    await vi.advanceTimersByTimeAsync(DRAFT_CHECKPOINT_LAG_MS);
+
+    expect(controller.getOutcome()).toEqual({ saved: false, revision: 1, reason: "timeout" });
+    expect(signal?.aborted).toBe(true);
+    stalled.resolve(content("late edit"));
+    await Promise.resolve();
+    await Promise.resolve();
+    expect(loadDraft(CONNECTION_ID, PATH, "markdown")).toBeNull();
+  });
+
+  it("keeps the latest live revision recoverable after a previous snapshot times out", async () => {
+    const stalled = deferredSnapshot();
+    controller.request(1, () => stalled.promise);
+    await vi.advanceTimersByTimeAsync(DRAFT_CHECKPOINT_START_MS);
+    controller.request(2, async () => content("latest edit"));
+    const flush = controller.flush();
+    await vi.advanceTimersByTimeAsync(DRAFT_CHECKPOINT_LAG_MS - DRAFT_CHECKPOINT_START_MS);
+
+    await expect(flush).resolves.toEqual({ saved: true, revision: 2 });
+    expect(loadDraft(CONNECTION_ID, PATH, "markdown")?.content).toBe("latest edit");
+    stalled.reject(new Error("Late serializer failure"));
+    await Promise.resolve();
+  });
+
+  it("reports serialization failure explicitly and allows a later recovery attempt", async () => {
+    controller.request(1, async () => {
+      throw new Error("Snapshot failed");
+    });
+    await expect(controller.flush()).resolves.toEqual({ saved: false, revision: 1, reason: "snapshot-failed" });
+    controller.request(1, async () => content("retried edit"));
+    await expect(controller.flush()).resolves.toEqual({ saved: true, revision: 1 });
+  });
+
+  it.each(["identity", "cleared", "disposed"])("rejects completion after authority is %s", async (change) => {
+    const pending = deferredSnapshot();
+    controller.request(1, () => pending.promise);
+    const flush = controller.flush();
+    await Promise.resolve();
+    if (change === "identity") getUserId.mockReturnValue("other-user");
+    if (change === "cleared") clearDraft(CONNECTION_ID, PATH, "markdown");
+    if (change === "disposed") controller.dispose();
+    pending.resolve(content("obsolete edit"));
+
+    await expect(flush).resolves.toEqual({ saved: false, revision: 1, reason: change === "disposed" ? "disposed" : "stale-checkpoint" });
+    expect(sessionStorage.length).toBe(0);
+  });
+
+  it("does not start queued serialization after disposal", async () => {
+    const serialize = vi.fn(async () => content("obsolete edit"));
+    controller.request(1, serialize);
+    controller.dispose();
+    await vi.advanceTimersByTimeAsync(DRAFT_CHECKPOINT_LAG_MS);
+
+    expect(serialize).not.toHaveBeenCalled();
+    expect(vi.getTimerCount()).toBe(0);
+  });
+
+  it("uses elapsed time rather than wall-clock changes for checkpoint deadlines", async () => {
+    controller.request(1, async () => content("latest edit"));
+    vi.setSystemTime(new Date("2030-01-01T00:00:00Z"));
+    await vi.advanceTimersByTimeAsync(DRAFT_CHECKPOINT_START_MS);
+
+    expect(controller.getOutcome()).toEqual({ saved: true, revision: 1 });
+  });
+
+  it.each(["no-user", "too-large", "storage-unavailable"])("preserves explicit %s failure feedback", async (reason) => {
+    if (reason === "no-user") {
+      controller.dispose();
+      getUserId.mockReturnValue(null);
+      controller = createDraftCheckpointController(CONNECTION_ID, PATH, "markdown");
+    }
+    if (reason === "storage-unavailable") {
+      vi.spyOn(Storage.prototype, "setItem").mockImplementation(() => {
+        throw new DOMException("Storage unavailable", "SecurityError");
+      });
+    }
+    const draftByteLimit = 2 * 1024 * 1024;
+    controller.request(1, async () => content(reason === "too-large" ? "a".repeat(draftByteLimit + 1) : "latest edit"));
+
+    await expect(controller.flush()).resolves.toEqual({ saved: false, revision: 1, reason });
+    expect(sessionStorage.length).toBe(0);
+  });
+
+  it("does not invoke a serializer disposed before its first microtask", async () => {
+    const serialize = vi.fn(async () => content("obsolete edit"));
+    controller.request(1, serialize);
+    const flush = controller.flush();
+    controller.dispose();
+
+    await expect(flush).resolves.toEqual({ saved: false, revision: 1, reason: "disposed" });
+    expect(serialize).not.toHaveBeenCalled();
+  });
+});
diff --git a/frontend/src/services/__tests__/draftRecovery.test.ts b/frontend/src/services/__tests__/draftRecovery.test.ts
index c44d2f807..96da614fa 100644
--- a/frontend/src/services/__tests__/draftRecovery.test.ts
+++ b/frontend/src/services/__tests__/draftRecovery.test.ts
@@ -1,33 +1,230 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
-const { getUserId } = vi.hoisted(() => ({ getUserId: vi.fn() }));
+const { getIdentity, getUserId } = vi.hoisted(() => ({ getIdentity: vi.fn(), getUserId: vi.fn() }));
 
-vi.mock("../authSession", () => ({ authSession: { getUserId } }));
+vi.mock("../authSession", () => ({ authSession: { getIdentity, getUserId } }));
 
 import {
+  clearCurrentUserDrafts,
   clearDraft,
+  createDraftCheckpointSession,
   DRAFT_RECOVERY_CHANGED_EVENT,
   getUnsavedDraftsForConnection,
   loadDraft,
   purgeExpiredDraftsForCurrentUser,
+  registerDraftSnapshot,
   saveDraft,
+  snapshotRegisteredDrafts,
 } from "../draftRecovery";
 
 const USER_ID = "test-user";
 const CONNECTION_ID = "connection";
+const DRAFT_BYTE_LIMIT = 2 * 1024 * 1024;
 
 describe("draft recovery", () => {
   beforeEach(() => {
     sessionStorage.clear();
     getUserId.mockReturnValue(USER_ID);
+    getIdentity.mockImplementation(() => ({ userId: getUserId(), epoch: 0 }));
     vi.useFakeTimers();
     vi.setSystemTime(new Date("2026-03-09T12:00:00.000Z"));
   });
 
   afterEach(() => {
+    vi.restoreAllMocks();
     vi.useRealTimers();
   });
 
+  it("acknowledges a snapshot only after its exact content is stored", () => {
+    const content = "latest edit\n\tincluding whitespace";
+
+    expect(saveDraft(CONNECTION_ID, "notes/a.md", "markdown", "saved", content)).toEqual({ saved: true });
+    expect(loadDraft(CONNECTION_ID, "notes/a.md", "markdown")).toEqual(
+      expect.objectContaining({ baseline: "saved", content, updatedAt: Date.now() })
+    );
+  });
+
+  it("rejects an older deferred checkpoint after a newer revision is acknowledged", async () => {
+    const session = createDraftCheckpointSession(CONNECTION_ID, "notes/a.md", "markdown");
+    try {
+      const older = session.capture(1);
+      const newer = session.capture(2);
+      let finishOlder!: () => void;
+      const pending = new Promise<void>((resolve) => {
+        finishOlder = resolve;
+      }).then(() => session.commit(older, "saved", "older edit"));
+
+      expect(session.commit(newer, "saved", "newer edit")).toEqual({ saved: true });
+      finishOlder();
+      await expect(pending).resolves.toEqual({ saved: false, reason: "stale-checkpoint" });
+      expect(loadDraft(CONNECTION_ID, "notes/a.md", "markdown")?.content).toBe("newer edit");
+    } finally {
+      session.dispose();
+    }
+  });
+
+  it.each(["other-account", "same-account-new-epoch"])("rejects captured authority after %s", (change) => {
+    const session = createDraftCheckpointSession(CONNECTION_ID, "notes/a.md", "markdown");
+    const checkpoint = session.capture(0);
+    try {
+      if (change === "other-account") getUserId.mockReturnValue("other-user");
+      else getIdentity.mockReturnValue({ userId: USER_ID, epoch: 1 });
+      expect(session.commit(checkpoint, "saved", "obsolete edit")).toEqual({ saved: false, reason: "stale-checkpoint" });
+      expect(sessionStorage.length).toBe(0);
+    } finally {
+      session.dispose();
+    }
+  });
+
+  it("rejects a closed session when a reopened document reuses revision numbers", () => {
+    const oldSession = createDraftCheckpointSession(CONNECTION_ID, "notes/a.md", "markdown");
+    const oldCheckpoint = oldSession.capture(0);
+    const newSession = createDraftCheckpointSession(CONNECTION_ID, "notes/a.md", "markdown");
+    try {
+      oldSession.dispose();
+      expect(newSession.commit(newSession.capture(0), "saved", "new session edit")).toEqual({ saved: true });
+      expect(oldSession.commit(oldCheckpoint, "saved", "old session edit")).toEqual({ saved: false, reason: "stale-checkpoint" });
+      expect(loadDraft(CONNECTION_ID, "notes/a.md", "markdown")?.content).toBe("new session edit");
+    } finally {
+      oldSession.dispose();
+      newSession.dispose();
+    }
+  });
+
+  it.each(["single", "all"])("invalidates pending writes when clearing %s drafts without stored content", (scope) => {
+    const session = createDraftCheckpointSession(CONNECTION_ID, "notes/a.md", "markdown");
+    const checkpoint = session.capture(0);
+    try {
+      if (scope === "single") clearDraft(CONNECTION_ID, "notes/./a.md", "markdown");
+      else clearCurrentUserDrafts();
+      expect(session.commit(checkpoint, "saved", "obsolete edit")).toEqual({ saved: false, reason: "stale-checkpoint" });
+      expect(sessionStorage.length).toBe(0);
+    } finally {
+      session.dispose();
+    }
+  });
+
+  it("keeps a recreated draft safe from checkpoints captured before clearing", () => {
+    const session = createDraftCheckpointSession(CONNECTION_ID, "notes/a.md", "markdown");
+    const checkpoint = session.capture(1);
+    try {
+      clearDraft(CONNECTION_ID, "notes/a.md", "markdown");
+      saveDraft(CONNECTION_ID, "notes/a.md", "markdown", "saved", "recreated draft");
+      expect(session.commit(checkpoint, "saved", "obsolete draft")).toEqual({ saved: false, reason: "stale-checkpoint" });
+      expect(loadDraft(CONNECTION_ID, "notes/a.md", "markdown")?.content).toBe("recreated draft");
+    } finally {
+      session.dispose();
+    }
+  });
+
+  it("allows retry after storage failure without acknowledging the failed revision", () => {
+    const session = createDraftCheckpointSession(CONNECTION_ID, "notes/a.md", "markdown");
+    const checkpoint = session.capture(1);
+    const write = vi.spyOn(Storage.prototype, "setItem").mockImplementationOnce(() => {
+      throw new DOMException("Storage quota exceeded", "QuotaExceededError");
+    });
+    try {
+      expect(session.commit(checkpoint, "saved", "latest edit")).toEqual({ saved: false, reason: "storage-unavailable" });
+      expect(session.commit(checkpoint, "saved", "latest edit")).toEqual({ saved: true });
+      expect(loadDraft(CONNECTION_ID, "notes/a.md", "markdown")?.content).toBe("latest edit");
+    } finally {
+      write.mockRestore();
+      session.dispose();
+    }
+  });
+
+  it("rejects forged checkpoints and invalid revisions", () => {
+    const session = createDraftCheckpointSession(CONNECTION_ID, "notes/a.md", "markdown");
+    try {
+      expect(session.commit({ revision: 0 }, "saved", "forged edit")).toEqual({ saved: false, reason: "stale-checkpoint" });
+      for (const revision of [-1, Number.NaN, Number.POSITIVE_INFINITY, Number.MAX_SAFE_INTEGER + 1, 0.5]) {
+        expect(() => session.capture(revision)).toThrow(RangeError);
+      }
+      session.capture(2);
+      expect(() => session.capture(1)).toThrow(RangeError);
+    } finally {
+      session.dispose();
+    }
+  });
+
+  it("rechecks authority after synchronous invalid-draft cleanup callbacks", () => {
+    const session = createDraftCheckpointSession(CONNECTION_ID, "notes/a.md", "markdown");
+    const checkpoint = session.capture(0);
+    sessionStorage.setItem(`sambee_oidc_draft:${USER_ID}:${CONNECTION_ID}:markdown:${encodeURIComponent("/notes/a.md")}`, "invalid");
+    const changeAccount = () => getUserId.mockReturnValue("other-user");
+    window.addEventListener(DRAFT_RECOVERY_CHANGED_EVENT, changeAccount);
+    try {
+      expect(session.commit(checkpoint, "saved", "obsolete edit")).toEqual({ saved: false, reason: "stale-checkpoint" });
+      expect(sessionStorage.length).toBe(0);
+    } finally {
+      window.removeEventListener(DRAFT_RECOVERY_CHANGED_EVENT, changeAccount);
+      session.dispose();
+    }
+  });
+
+  it("reports missing identity without creating a checkpoint", () => {
+    getUserId.mockReturnValue(null);
+
+    expect(saveDraft(CONNECTION_ID, "notes/a.md", "markdown", "saved", "draft")).toEqual({ saved: false, reason: "no-user" });
+    expect(sessionStorage.length).toBe(0);
+  });
+
+  it("accepts the byte limit and preserves the last checkpoint when a later draft exceeds it", () => {
+    const content = "a".repeat(DRAFT_BYTE_LIMIT);
+    expect(saveDraft(CONNECTION_ID, "notes/a.txt", "text", "saved", content)).toEqual({ saved: true });
+
+    expect(saveDraft(CONNECTION_ID, "notes/a.txt", "text", "saved", `${content}a`)).toEqual({ saved: false, reason: "too-large" });
+    expect(loadDraft(CONNECTION_ID, "notes/a.txt", "text")?.content).toBe(content);
+  });
+
+  it("applies the draft limit to UTF-8 bytes rather than source length", () => {
+    const content = "\u00e9".repeat(DRAFT_BYTE_LIMIT / 2 + 1);
+
+    expect(content.length).toBeLessThan(DRAFT_BYTE_LIMIT);
+    expect(saveDraft(CONNECTION_ID, "notes/a.txt", "text", "saved", content)).toEqual({ saved: false, reason: "too-large" });
+    expect(sessionStorage.length).toBe(0);
+  });
+
+  it("reports failed persistence and retains the previous acknowledged checkpoint", () => {
+    saveDraft(CONNECTION_ID, "notes/a.md", "markdown", "saved", "acknowledged draft");
+    vi.spyOn(Storage.prototype, "setItem").mockImplementation(() => {
+      throw new DOMException("Storage quota exceeded", "QuotaExceededError");
+    });
+
+    expect(saveDraft(CONNECTION_ID, "notes/a.md", "markdown", "saved", "latest edit")).toEqual({
+      saved: false,
+      reason: "storage-unavailable",
+    });
+    expect(loadDraft(CONNECTION_ID, "notes/a.md", "markdown")?.content).toBe("acknowledged draft");
+  });
+
+  it("isolates current-user checkpoints and clearing from another user's drafts", () => {
+    saveDraft(CONNECTION_ID, "notes/a.md", "markdown", "saved", "first user's draft");
+    getUserId.mockReturnValue("other-user");
+    expect(loadDraft(CONNECTION_ID, "notes/a.md", "markdown")).toBeNull();
+    saveDraft(CONNECTION_ID, "notes/a.md", "markdown", "saved", "second user's draft");
+    clearCurrentUserDrafts();
+    expect(loadDraft(CONNECTION_ID, "notes/a.md", "markdown")).toBeNull();
+
+    getUserId.mockReturnValue(USER_ID);
+    expect(loadDraft(CONNECTION_ID, "notes/a.md", "markdown")?.content).toBe("first user's draft");
+  });
+
+  it("runs registered lifecycle snapshots synchronously and stops after unregistering", () => {
+    const snapshot = vi.fn(() => saveDraft(CONNECTION_ID, "notes/a.md", "markdown", "saved", "latest edit"));
+    const unregister = registerDraftSnapshot(snapshot);
+    try {
+      snapshotRegisteredDrafts();
+      expect(snapshot).toHaveBeenCalledOnce();
+      expect(loadDraft(CONNECTION_ID, "notes/a.md", "markdown")?.content).toBe("latest edit");
+      unregister();
+      snapshotRegisteredDrafts();
+      expect(snapshot).toHaveBeenCalledOnce();
+    } finally {
+      unregister();
+    }
+  });
+
   it("enumerates only changed, valid drafts for a connection", () => {
     saveDraft(CONNECTION_ID, "notes/a.md", "markdown", "saved", "local draft");
     saveDraft(CONNECTION_ID, "notes/b.txt", "text", "same", "same");
diff --git a/frontend/src/services/__tests__/foregroundArchiveOperation.test.ts b/frontend/src/services/__tests__/foregroundArchiveOperation.test.ts
index 85bf48eb8..cb6be26d2 100644
--- a/frontend/src/services/__tests__/foregroundArchiveOperation.test.ts
+++ b/frontend/src/services/__tests__/foregroundArchiveOperation.test.ts
@@ -28,7 +28,7 @@ describe("foreground archive operation tracking", () => {
 
   it("persists an opaque recovery handle for adapter-owned archive work", () => {
     const recovery = {
-      schemaVersion: 2,
+      schemaVersion: 2 as const,
       contractVersion: "v2" as const,
       backendKind: "smb" as const,
       opaqueOperationId: "operation-a",
diff --git a/frontend/src/services/__tests__/mobileLoggingApi.test.ts b/frontend/src/services/__tests__/mobileLoggingApi.test.ts
index 397789267..72724b3c7 100644
--- a/frontend/src/services/__tests__/mobileLoggingApi.test.ts
+++ b/frontend/src/services/__tests__/mobileLoggingApi.test.ts
@@ -1,3 +1,4 @@
+import { requireTestValue } from "../../test/helpers/assertions";
 /**
  * Mobile Logging API Contract Tests
  *
@@ -402,7 +403,7 @@ describe("Mobile Logging API Contract Tests", () => {
       expect(typeof result.total_size).toBe("number");
 
       // Verify file structure
-      const file = result.files[0];
+      const file = requireTestValue(result.files[0]);
       expect(file).toHaveProperty("filename");
       expect(file).toHaveProperty("size");
       expect(file).toHaveProperty("modified");
diff --git a/frontend/src/services/__tests__/userSettingsStore.test.ts b/frontend/src/services/__tests__/userSettingsStore.test.ts
index e23e4b710..5ff0a5865 100644
--- a/frontend/src/services/__tests__/userSettingsStore.test.ts
+++ b/frontend/src/services/__tests__/userSettingsStore.test.ts
@@ -1,6 +1,7 @@
 import { act, renderHook } from "@testing-library/react";
 import { createElement, type ReactNode } from "react";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { createMockAuthToken } from "../../test/fixtures/users";
 
 const { getCurrentUserSettingsMock, updateCurrentUserSettingsMock } = vi.hoisted(() => ({
   getCurrentUserSettingsMock: vi.fn(),
@@ -65,7 +66,7 @@ const settings = {
 
 async function authenticateAndLoad() {
   getCurrentUserSettingsMock.mockResolvedValue(settings);
-  authSession.setAuthenticated({ access_token: "token", token_type: "bearer", user_id: "user-1" }, false);
+  authSession.setAuthenticated(createMockAuthToken({ access_token: "token", token_type: "bearer", user_id: "user-1" }), false);
   await refreshCurrentUserSettings();
   await refreshCurrentUserSettings();
 }
@@ -98,7 +99,7 @@ describe("userSettingsStore", () => {
   });
 
   it("keeps a canonical field response when the initial settings snapshot is unavailable", async () => {
-    authSession.setAuthenticated({ access_token: "token", token_type: "bearer", user_id: "user-1" }, false);
+    authSession.setAuthenticated(createMockAuthToken({ access_token: "token", token_type: "bearer", user_id: "user-1" }), false);
     const result = { field: "appearance.theme_id", value: "sambee-dark" } as const;
     updateCurrentUserSettingsMock.mockResolvedValue(result);
 
@@ -125,7 +126,7 @@ describe("userSettingsStore", () => {
       ...settings,
       appearance: { ...settings.appearance, has_theme_override: false },
     });
-    authSession.setAuthenticated({ access_token: "token", token_type: "bearer", user_id: "user-1" }, false);
+    authSession.setAuthenticated(createMockAuthToken({ access_token: "token", token_type: "bearer", user_id: "user-1" }), false);
     await refreshCurrentUserSettings();
     await refreshCurrentUserSettings();
     updateCurrentUserSettingsMock.mockResolvedValue({ field: "appearance.theme_id", value: "sambee-light" });
diff --git a/frontend/src/services/__tests__/viewerApi.test.ts b/frontend/src/services/__tests__/viewerApi.test.ts
index 0b5531ac0..eedd04542 100644
--- a/frontend/src/services/__tests__/viewerApi.test.ts
+++ b/frontend/src/services/__tests__/viewerApi.test.ts
@@ -1,3 +1,4 @@
+import { requireTestValue } from "../../test/helpers/assertions";
 /**
  * Contract tests for Viewer API
  *
@@ -125,7 +126,7 @@ describe("Viewer API Contract Tests", () => {
       });
 
       // Verify request included viewport parameters
-      const callArgs = mockAxiosInstance.get.mock.calls[0];
+      const callArgs = requireTestValue(mockAxiosInstance.get.mock.calls[0]);
       expect(callArgs[0]).toBe(`/viewer/${testConnectionId}/file`);
       expect(callArgs[1]?.params).toHaveProperty("viewport_width");
       expect(callArgs[1]?.params).toHaveProperty("viewport_height");
@@ -146,7 +147,7 @@ describe("Viewer API Contract Tests", () => {
       });
 
       // Verify no_resizing parameter was sent
-      const callArgs = mockAxiosInstance.get.mock.calls[0];
+      const callArgs = requireTestValue(mockAxiosInstance.get.mock.calls[0]);
       expect(callArgs[1]?.params).toHaveProperty("no_resizing", 1);
     });
 
@@ -166,7 +167,7 @@ describe("Viewer API Contract Tests", () => {
       });
 
       // Verify signal was passed
-      const callArgs = mockAxiosInstance.get.mock.calls[0];
+      const callArgs = requireTestValue(mockAxiosInstance.get.mock.calls[0]);
       expect(callArgs[1]?.signal).toBe(abortController.signal);
     });
 
@@ -245,7 +246,7 @@ describe("Viewer API Contract Tests", () => {
       });
 
       // Verify signal was passed
-      const callArgs = mockAxiosInstance.get.mock.calls[0];
+      const callArgs = requireTestValue(mockAxiosInstance.get.mock.calls[0]);
       expect(callArgs[1]?.signal).toBe(abortController.signal);
     });
 
@@ -260,7 +261,10 @@ describe("Viewer API Contract Tests", () => {
 
       await apiService.getPdfBlob(testConnectionId, "/document.pdf", { pdfVariant: "normalized" });
 
-      expect(mockAxiosInstance.get.mock.calls[0][1]?.params).toEqual({ path: "/document.pdf", pdf_variant: "normalized" });
+      expect(requireTestValue(mockAxiosInstance.get.mock.calls[0])[1]?.params).toEqual({
+        path: "/document.pdf",
+        pdf_variant: "normalized",
+      });
     });
 
     it("should include the physical display profile for compatibility selection", async () => {
@@ -277,7 +281,7 @@ describe("Viewer API Contract Tests", () => {
         screenProfile: { width: 5120, height: 2880, zoomPercent: 200 },
       });
 
-      expect(mockAxiosInstance.get.mock.calls[0][1]?.params).toEqual({
+      expect(requireTestValue(mockAxiosInstance.get.mock.calls[0])[1]?.params).toEqual({
         path: "/document.pdf",
         pdf_variant: "normalized",
         screen_width: 5120,
diff --git a/frontend/src/services/api.ts b/frontend/src/services/api.ts
index d5c7907fc..c22bb4528 100644
--- a/frontend/src/services/api.ts
+++ b/frontend/src/services/api.ts
@@ -283,7 +283,6 @@ function getDevicePixelDimension(value: number | undefined): number | undefined
 
 let controlledReauthenticationInProgress = false;
 let oidcExchangePending = window.location.pathname === "/login/oidc/callback";
-
 export function setOidcExchangePending(pending: boolean): void {
   oidcExchangePending = pending;
 }
@@ -378,7 +377,7 @@ class ApiService {
 
   constructor() {
     // Use absolute URL for tests (required by MSW), relative for production
-    const baseURL = import.meta.env.VITE_API_URL || (import.meta.env.MODE === "test" ? "http://localhost:3000/api" : "/api");
+    const baseURL = import.meta.env["VITE_API_URL"] || (import.meta.env.MODE === "test" ? "http://localhost:3000/api" : "/api");
     this.api = axios.create({
       baseURL,
     });
diff --git a/frontend/src/services/authConfig.ts b/frontend/src/services/authConfig.ts
index d072a1ee8..fd81c41db 100644
--- a/frontend/src/services/authConfig.ts
+++ b/frontend/src/services/authConfig.ts
@@ -29,7 +29,7 @@ export async function getAuthConfig(): Promise<AuthConfig> {
   }
 
   try {
-    const baseURL = import.meta.env.VITE_API_URL || "/api";
+    const baseURL = import.meta.env["VITE_API_URL"] || "/api";
     const response = await axios.get<unknown>(`${baseURL}/auth/config`);
     authConfigCache = parseAuthConfig(response.data);
     logger.info(`Auth configuration loaded: ${authConfigCache.sign_in_mode}`, {}, "auth");
@@ -45,7 +45,7 @@ function isOidcPublicConfig(value: unknown): value is OidcPublicConfig {
     return false;
   }
   const candidate = value as Record<string, unknown>;
-  return typeof candidate.display_name === "string" && typeof candidate.authorization_path === "string";
+  return typeof candidate["display_name"] === "string" && typeof candidate["authorization_path"] === "string";
 }
 
 export function parseAuthConfig(value: unknown): AuthConfig {
diff --git a/frontend/src/services/authSession.ts b/frontend/src/services/authSession.ts
index ae40e2f88..2354ffec6 100644
--- a/frontend/src/services/authSession.ts
+++ b/frontend/src/services/authSession.ts
@@ -15,7 +15,7 @@ export interface AuthIdentity {
   userId: string | null;
 }
 
-const API_BASE_URL = import.meta.env.VITE_API_URL || (import.meta.env.MODE === "test" ? "http://localhost:3000/api" : "/api");
+const API_BASE_URL = import.meta.env["VITE_API_URL"] || (import.meta.env.MODE === "test" ? "http://localhost:3000/api" : "/api");
 const REFRESH_SAFETY_MARGIN_MS = 5 * 60_000;
 const REFRESH_JITTER_RATIO = 0.05;
 const REFRESH_RETRY_DELAY_MS = 30_000;
diff --git a/frontend/src/services/backendRouter.ts b/frontend/src/services/backendRouter.ts
index 0812ea03a..b8b83b4c7 100644
--- a/frontend/src/services/backendRouter.ts
+++ b/frontend/src/services/backendRouter.ts
@@ -25,7 +25,8 @@ const BACKSLASH = "\\";
 export const CONNECTION_TYPE_LOCAL = "local";
 
 /** Base URL for the primary Sambee backend API. */
-export const SERVER_API_BASE_URL = import.meta.env.VITE_API_URL || (import.meta.env.MODE === "test" ? "http://localhost:3000/api" : "/api");
+export const SERVER_API_BASE_URL =
+  import.meta.env["VITE_API_URL"] || (import.meta.env.MODE === "test" ? "http://localhost:3000/api" : "/api");
 
 // ── Drive ↔ Connection Mapping ───────────────────────────────────────────────
 
@@ -45,6 +46,9 @@ export function driveToConnection(drive: DriveInfo): Connection {
     port: 21549,
     share_name: drive.id,
     username: "",
+    scope: "private",
+    access_mode: "read_write",
+    can_manage: false,
     created_at: "",
     updated_at: "",
   };
diff --git a/frontend/src/services/browserHistoryService.ts b/frontend/src/services/browserHistoryService.ts
index bc1778780..de12b335e 100644
--- a/frontend/src/services/browserHistoryService.ts
+++ b/frontend/src/services/browserHistoryService.ts
@@ -20,11 +20,15 @@ export interface BrowserHistoryService {
 export const browserHistoryService: BrowserHistoryService = {
   searchRecentFiles: (query, resultLimit, signal) => api.searchRecentFiles(query, resultLimit, signal),
   hasItemType: async (connectionId, path, expectedType) => (await api.getFileInfo(connectionId, path)).type === expectedType,
-  recordRecentFile: (connectionId, path) => api.recordRecentFile(connectionId, path),
+  recordRecentFile: async (connectionId, path) => {
+    await api.recordRecentFile(connectionId, path);
+  },
   removeRecentFile: (recordId) => api.removeRecentFile(recordId),
   validateRecentFileTarget: (recordId) => api.validateRecentFileTarget(recordId),
   searchRecentDirectories: (query, resultLimit, signal) => api.searchRecentDirectories(query, resultLimit, signal),
-  recordRecentDirectory: (connectionId, path) => api.recordRecentDirectory(connectionId, path),
+  recordRecentDirectory: async (connectionId, path) => {
+    await api.recordRecentDirectory(connectionId, path);
+  },
   removeRecentDirectory: (recordId) => api.removeRecentDirectory(recordId),
   searchDirectories: (connectionId, query, options) => api.searchDirectories(connectionId, query, options),
 };
diff --git a/frontend/src/services/companionSession.ts b/frontend/src/services/companionSession.ts
index c07e0b070..9bc1e5d82 100644
--- a/frontend/src/services/companionSession.ts
+++ b/frontend/src/services/companionSession.ts
@@ -27,8 +27,10 @@ async function sign(secret: string, value: string): Promise<string> {
 function compareCodePoints(left: string, right: string): number {
   const leftPoints = Array.from(left, (character) => character.codePointAt(0) ?? 0);
   const rightPoints = Array.from(right, (character) => character.codePointAt(0) ?? 0);
-  for (let index = 0; index < Math.min(leftPoints.length, rightPoints.length); index += 1) {
-    if (leftPoints[index] !== rightPoints[index]) return leftPoints[index] - rightPoints[index];
+  for (const [index, leftPoint] of leftPoints.entries()) {
+    const rightPoint = rightPoints[index];
+    if (rightPoint === undefined) break;
+    if (leftPoint !== rightPoint) return leftPoint - rightPoint;
   }
   return leftPoints.length - rightPoints.length;
 }
diff --git a/frontend/src/services/draftCheckpoint.ts b/frontend/src/services/draftCheckpoint.ts
new file mode 100644
index 000000000..9cf0c3b77
--- /dev/null
+++ b/frontend/src/services/draftCheckpoint.ts
@@ -0,0 +1,145 @@
+import { createDraftCheckpointSession, type DraftCheckpoint, type DraftEditorType, type DraftSaveResult } from "./draftRecovery";
+
+export const DRAFT_CHECKPOINT_START_MS = 250;
+export const DRAFT_CHECKPOINT_LAG_MS = 1_000;
+export const DRAFT_TRANSITION_FLUSH_MS = 2_000;
+export const DRAFT_CHECKPOINT_TASK_MS = 50;
+
+export interface DraftCheckpointContent {
+  baseline: string;
+  content: string;
+}
+
+export type DraftCheckpointOutcome =
+  | { saved: true; revision: number | null }
+  | {
+      saved: false;
+      revision: number;
+      reason: Extract<DraftSaveResult, { saved: false }>["reason"] | "snapshot-failed" | "timeout" | "disposed";
+    };
+
+interface PendingCheckpoint {
+  checkpoint: DraftCheckpoint;
+  requestedAt: number;
+  serialize: (signal: AbortSignal) => Promise<DraftCheckpointContent>;
+}
+
+export function createDraftCheckpointController(connectionId: string, path: string, editorType: DraftEditorType) {
+  const session = createDraftCheckpointSession(connectionId, path, editorType);
+  let pending: PendingCheckpoint | null = null;
+  let active: Promise<DraftCheckpointOutcome> | null = null;
+  let cancelActive: (() => void) | null = null;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let latestRevision = -1;
+  let disposed = false;
+  let lastOutcome: DraftCheckpointOutcome = { saved: true, revision: null };
+
+  function schedule(): void {
+    if (disposed || active || !pending || timer !== undefined) return;
+    const delay = Math.max(0, pending.requestedAt + DRAFT_CHECKPOINT_START_MS - DRAFT_CHECKPOINT_TASK_MS - performance.now());
+    timer = setTimeout(() => {
+      timer = undefined;
+      void runNext();
+    }, delay);
+  }
+
+  function runNext(): Promise<DraftCheckpointOutcome> {
+    if (active) return active;
+    if (!pending) return Promise.resolve(lastOutcome);
+    const job = pending;
+    pending = null;
+    clearTimeout(timer);
+    timer = undefined;
+    const revision = job.checkpoint.revision;
+    const controller = new AbortController();
+    const operation = new Promise<DraftCheckpointOutcome>((resolve) => {
+      let settled = false;
+      let deadline: ReturnType<typeof setTimeout> | undefined;
+      const finish = (outcome: DraftCheckpointOutcome) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(deadline);
+        lastOutcome = outcome;
+        resolve(outcome);
+      };
+      const fail = (reason: "disposed" | "timeout") => {
+        finish({ saved: false, revision, reason });
+        controller.abort();
+      };
+      cancelActive = () => fail("disposed");
+      const remaining = job.requestedAt + DRAFT_CHECKPOINT_LAG_MS - performance.now();
+      if (remaining <= 0) {
+        fail("timeout");
+        return;
+      }
+      deadline = setTimeout(() => fail("timeout"), remaining);
+      void Promise.resolve()
+        .then(() => {
+          if (controller.signal.aborted) return null;
+          return job.serialize(controller.signal);
+        })
+        .then((snapshot) => {
+          if (settled || snapshot === null) return;
+          if (performance.now() >= job.requestedAt + DRAFT_CHECKPOINT_LAG_MS) {
+            fail("timeout");
+            return;
+          }
+          if (typeof snapshot.baseline !== "string" || typeof snapshot.content !== "string") {
+            finish({ saved: false, revision, reason: "snapshot-failed" });
+            return;
+          }
+          const result = session.commit(job.checkpoint, snapshot.baseline, snapshot.content);
+          finish({ ...result, revision });
+        })
+        .catch(() => finish({ saved: false, revision, reason: "snapshot-failed" }));
+    });
+    active = operation.finally(() => {
+      active = null;
+      cancelActive = null;
+      schedule();
+    });
+    return active;
+  }
+
+  return {
+    request(revision: number, serialize: PendingCheckpoint["serialize"]): void {
+      if (disposed) throw new Error("Cannot request a checkpoint for a disposed editor session");
+      const checkpoint = session.capture(revision);
+      latestRevision = revision;
+      pending = { checkpoint, requestedAt: pending?.requestedAt ?? performance.now(), serialize };
+      schedule();
+    },
+    getOutcome(): DraftCheckpointOutcome {
+      return lastOutcome;
+    },
+    async flush(): Promise<DraftCheckpointOutcome> {
+      if (disposed) return { saved: false, revision: latestRevision, reason: "disposed" };
+      const targetRevision = latestRevision;
+      if (targetRevision < 0) return lastOutcome;
+      let deadline: ReturnType<typeof setTimeout> | undefined;
+      const completion = async () => {
+        let outcome = await runNext();
+        while (!disposed && (outcome.revision ?? -1) < targetRevision && pending) outcome = await runNext();
+        return outcome;
+      };
+      try {
+        return await Promise.race([
+          completion(),
+          new Promise<DraftCheckpointOutcome>((resolve) => {
+            deadline = setTimeout(() => resolve({ saved: false, revision: targetRevision, reason: "timeout" }), DRAFT_TRANSITION_FLUSH_MS);
+          }),
+        ]);
+      } finally {
+        clearTimeout(deadline);
+      }
+    },
+    dispose(): void {
+      disposed = true;
+      clearTimeout(timer);
+      timer = undefined;
+      pending = null;
+      session.dispose();
+      cancelActive?.();
+    },
+  };
+}
diff --git a/frontend/src/services/draftRecovery.ts b/frontend/src/services/draftRecovery.ts
index 032f79d5e..79c4143a3 100644
--- a/frontend/src/services/draftRecovery.ts
+++ b/frontend/src/services/draftRecovery.ts
@@ -23,13 +23,26 @@ export interface UnsavedDraftMetadata {
   updatedAt: number;
 }
 
-export type DraftSaveResult = { saved: true } | { saved: false; reason: "no-user" | "too-large" | "storage-unavailable" };
+export type DraftSaveResult =
+  | { saved: true }
+  | { saved: false; reason: "no-user" | "too-large" | "storage-unavailable" | "stale-checkpoint" };
+
+export interface DraftCheckpoint {
+  readonly revision: number;
+}
+
+export interface DraftCheckpointSession {
+  capture(revision: number): DraftCheckpoint;
+  commit(checkpoint: DraftCheckpoint, baseline: string, content: string): DraftSaveResult;
+  dispose(): void;
+}
 
 interface RegisteredDraft {
   snapshot: () => void;
 }
 
 const registeredDrafts = new Set<RegisteredDraft>();
+const checkpointSessions = new Map<string, object>();
 
 function normalizePath(path: string): string {
   const segments: string[] = [];
@@ -55,11 +68,14 @@ function hashBaseline(value: string): string {
   return (hash >>> 0).toString(16).padStart(8, "0");
 }
 
-function key(connectionId: string, path: string, editorType: DraftEditorType): string | null {
-  const userId = authSession.getUserId();
+function keyForUser(userId: string | null, connectionId: string, path: string, editorType: DraftEditorType): string | null {
   return userId ? `${DRAFT_PREFIX}:${userId}:${connectionId}:${editorType}:${encodeURIComponent(normalizePath(path))}` : null;
 }
 
+function key(connectionId: string, path: string, editorType: DraftEditorType): string | null {
+  return keyForUser(authSession.getUserId(), connectionId, path, editorType);
+}
+
 function parseDraftSnapshot(value: string): DraftSnapshot | null {
   try {
     const parsed = JSON.parse(value) as Partial<DraftSnapshot>;
@@ -126,14 +142,25 @@ export function saveDraft(
   baseline: string,
   content: string
 ): DraftSaveResult {
+  const storageKey = key(connectionId, path, editorType);
+  if (storageKey) checkpointSessions.delete(storageKey);
+  return writeDraft(storageKey, baseline, content);
+}
+
+function writeDraft(
+  storageKey: string | null,
+  baseline: string,
+  content: string,
+  authority?: { isCurrent(): boolean; acknowledge(): void }
+): DraftSaveResult {
+  if (authority && !authority.isCurrent()) return { saved: false, reason: "stale-checkpoint" };
   if (new Blob([content]).size > MAX_DRAFT_BYTES) {
     return { saved: false, reason: "too-large" };
   }
-  const storageKey = key(connectionId, path, editorType);
   if (!storageKey) {
     return { saved: false, reason: "no-user" };
   }
-  const current = loadDraft(connectionId, path, editorType);
+  const current = loadDraftAtKey(storageKey);
   const hadUnsavedDraft = current !== null && current.content !== current.baseline;
   const snapshot: DraftSnapshot = {
     baseline,
@@ -143,7 +170,10 @@ export function saveDraft(
     updatedAt: Date.now(),
   };
   try {
-    sessionStorage.setItem(storageKey, JSON.stringify(snapshot));
+    const serialized = JSON.stringify(snapshot);
+    if (authority && !authority.isCurrent()) return { saved: false, reason: "stale-checkpoint" };
+    sessionStorage.setItem(storageKey, serialized);
+    authority?.acknowledge();
     if (!hadUnsavedDraft) {
       notifyDraftRecoveryChanged();
     }
@@ -153,11 +183,60 @@ export function saveDraft(
   }
 }
 
+export function createDraftCheckpointSession(connectionId: string, path: string, editorType: DraftEditorType): DraftCheckpointSession {
+  const identity = authSession.getIdentity();
+  const storageKey = keyForUser(identity.userId, connectionId, path, editorType);
+  const session = {};
+  const checkpoints = new WeakSet<DraftCheckpoint>();
+  let acknowledgedRevision = -1;
+  let latestRevision = -1;
+  let disposed = false;
+  if (storageKey) checkpointSessions.set(storageKey, session);
+  const isCurrent = (checkpoint: DraftCheckpoint) => {
+    const currentIdentity = authSession.getIdentity();
+    return (
+      !disposed &&
+      storageKey !== null &&
+      checkpointSessions.get(storageKey) === session &&
+      checkpoints.has(checkpoint) &&
+      checkpoint.revision > acknowledgedRevision &&
+      currentIdentity.userId === identity.userId &&
+      currentIdentity.epoch === identity.epoch
+    );
+  };
+
+  return {
+    capture(revision) {
+      if (!Number.isSafeInteger(revision) || revision < 0 || revision < latestRevision) {
+        throw new RangeError("Draft checkpoint revisions must be nonnegative, safe integers in increasing order");
+      }
+      latestRevision = revision;
+      const checkpoint = Object.freeze({ revision });
+      checkpoints.add(checkpoint);
+      return checkpoint;
+    },
+    commit(checkpoint, baseline, content) {
+      if (!identity.userId) return { saved: false, reason: "no-user" };
+      return writeDraft(storageKey, baseline, content, {
+        isCurrent: () => isCurrent(checkpoint),
+        acknowledge: () => {
+          acknowledgedRevision = checkpoint.revision;
+        },
+      });
+    },
+    dispose() {
+      disposed = true;
+      if (storageKey && checkpointSessions.get(storageKey) === session) checkpointSessions.delete(storageKey);
+    },
+  };
+}
+
 export function loadDraft(connectionId: string, path: string, editorType: DraftEditorType): DraftSnapshot | null {
   const storageKey = key(connectionId, path, editorType);
-  if (!storageKey) {
-    return null;
-  }
+  return storageKey ? loadDraftAtKey(storageKey) : null;
+}
+
+function loadDraftAtKey(storageKey: string): DraftSnapshot | null {
   try {
     const value = sessionStorage.getItem(storageKey);
     if (!value) {
@@ -183,6 +262,7 @@ export function loadDraft(connectionId: string, path: string, editorType: DraftE
 export function clearDraft(connectionId: string, path: string, editorType: DraftEditorType): void {
   const storageKey = key(connectionId, path, editorType);
   if (storageKey) {
+    checkpointSessions.delete(storageKey);
     try {
       const hadDraft = sessionStorage.getItem(storageKey) !== null;
       sessionStorage.removeItem(storageKey);
@@ -281,9 +361,12 @@ export function clearCurrentUserDrafts(): void {
   if (!userId) {
     return;
   }
+  const prefix = `${DRAFT_PREFIX}:${userId}:`;
+  for (const storageKey of checkpointSessions.keys()) {
+    if (storageKey.startsWith(prefix)) checkpointSessions.delete(storageKey);
+  }
   let changed = false;
   try {
-    const prefix = `${DRAFT_PREFIX}:${userId}:`;
     for (let index = sessionStorage.length - 1; index >= 0; index -= 1) {
       const storageKey = sessionStorage.key(index);
       if (storageKey?.startsWith(prefix)) {
diff --git a/frontend/src/services/foregroundArchiveOperation.ts b/frontend/src/services/foregroundArchiveOperation.ts
index b47b0e635..ac6bfad00 100644
--- a/frontend/src/services/foregroundArchiveOperation.ts
+++ b/frontend/src/services/foregroundArchiveOperation.ts
@@ -93,7 +93,7 @@ export function requestForegroundArchiveCancellation(operationId: string): void
   const headers: HeadersInit = { "Content-Type": "application/json" };
   const token = authSession.getAccessToken();
   if (token) {
-    headers.Authorization = `Bearer ${token}`;
+    headers["Authorization"] = `Bearer ${token}`;
   }
   void fetch(cancellationUrl(operationId), {
     method: "POST",
diff --git a/frontend/src/services/logBuffer.ts b/frontend/src/services/logBuffer.ts
index 672af6e60..cf72bea32 100644
--- a/frontend/src/services/logBuffer.ts
+++ b/frontend/src/services/logBuffer.ts
@@ -38,7 +38,7 @@ export class LogBuffer {
   private flushCallback: FlushCallback;
   private maxLogs: number;
   private flushIntervalMs: number;
-  private flushTimer: NodeJS.Timeout | null = null;
+  private flushTimer: ReturnType<typeof setInterval> | null = null;
   private isEnabled = false;
 
   /**
diff --git a/frontend/src/services/logTransport.ts b/frontend/src/services/logTransport.ts
index d54b3294b..abd222ccf 100644
--- a/frontend/src/services/logTransport.ts
+++ b/frontend/src/services/logTransport.ts
@@ -40,7 +40,7 @@ export class LogTransport {
     };
 
     if (token) {
-      headers.Authorization = `Bearer ${token}`;
+      headers["Authorization"] = `Bearer ${token}`;
     }
 
     const response = await fetch(url, {
diff --git a/frontend/src/services/logger.ts b/frontend/src/services/logger.ts
index 1a0905b33..3dedf3185 100644
--- a/frontend/src/services/logger.ts
+++ b/frontend/src/services/logger.ts
@@ -52,7 +52,7 @@ class Logger {
     // Detect test environment - vitest sets this or we can check if vitest globals exist
     this.isTest =
       import.meta.env["VITEST"] === true ||
-      (typeof process !== "undefined" && process.env?.["VITEST"] === "true") ||
+      import.meta.env.MODE === "test" ||
       // Alternative: check if vitest globals are available
       (typeof globalThis !== "undefined" && ("describe" in globalThis || "it" in globalThis || "test" in globalThis));
     // In production, only show warnings and errors; in development, show all logs
diff --git a/frontend/src/services/runtimeWarmup.ts b/frontend/src/services/runtimeWarmup.ts
index d7782bd0a..cb393a7f3 100644
--- a/frontend/src/services/runtimeWarmup.ts
+++ b/frontend/src/services/runtimeWarmup.ts
@@ -1,20 +1,9 @@
 let warmupScheduled = false;
 const IS_TEST_ENVIRONMENT =
   import.meta.env["VITEST"] === true ||
-  (typeof process !== "undefined" && process.env?.["VITEST"] === "true") ||
+  import.meta.env.MODE === "test" ||
   (typeof globalThis !== "undefined" && ("describe" in globalThis || "it" in globalThis || "test" in globalThis));
 
-type IdleCallbackHandle = number;
-
-interface IdleCallbackDeadline {
-  didTimeout: boolean;
-  timeRemaining: () => number;
-}
-
-interface IdleWindow extends Window {
-  requestIdleCallback?: (callback: (deadline: IdleCallbackDeadline) => void, options?: { timeout?: number }) => IdleCallbackHandle;
-}
-
 async function warmRuntimeModules(): Promise<void> {
   await Promise.allSettled([
     import("../components/Viewer/ImageViewer"),
@@ -42,9 +31,8 @@ export function scheduleRuntimeWarmup(): void {
     void warmRuntimeModules();
   };
 
-  const idleWindow = window as IdleWindow;
-  if (typeof idleWindow.requestIdleCallback === "function") {
-    idleWindow.requestIdleCallback(
+  if (typeof window.requestIdleCallback === "function") {
+    window.requestIdleCallback(
       () => {
         runWarmup();
       },
diff --git a/frontend/src/services/storageBackends.test.ts b/frontend/src/services/storageBackends.test.ts
index f50b7f29d..109b83cba 100644
--- a/frontend/src/services/storageBackends.test.ts
+++ b/frontend/src/services/storageBackends.test.ts
@@ -1,4 +1,5 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { requireTestValue } from "../test/helpers/assertions";
 import api, { ExpiredEditLockError } from "./api";
 import { authSession } from "./authSession";
 import { clearEditLockRecovery } from "./editLockRecovery";
@@ -240,7 +241,7 @@ describe("SambeeSmbBackend archive reads", () => {
         destination_path: "archives/selected.zip",
       })
     );
-    expect(JSON.parse(vi.mocked(api.prepareArchiveOperation).mock.calls[0]![0].plan_json)).toEqual({
+    expect(JSON.parse(requireTestValue(vi.mocked(api.prepareArchiveOperation).mock.calls[0]![0].plan_json))).toEqual({
       source_paths: ["archives/source.zip"],
     });
     await expect(
diff --git a/frontend/src/services/storageBackends.ts b/frontend/src/services/storageBackends.ts
index 258867bf4..909ebf2bf 100644
--- a/frontend/src/services/storageBackends.ts
+++ b/frontend/src/services/storageBackends.ts
@@ -179,7 +179,12 @@ abstract class ApiStorageBackend implements StorageBackend {
       return { status: "removed" };
     } catch (error) {
       const detail = isApiError(error) ? error.response?.data?.detail : null;
-      if (error.response?.status === 409 && typeof detail === "string" && detail.startsWith("Directory is not empty:")) {
+      if (
+        isApiError(error) &&
+        error.response?.status === 409 &&
+        typeof detail === "string" &&
+        detail.startsWith("Directory is not empty:")
+      ) {
         return { status: "not_empty" };
       }
       throw error;
diff --git a/frontend/src/services/storageRegistry.ts b/frontend/src/services/storageRegistry.ts
index fbad8077c..b76352cdc 100644
--- a/frontend/src/services/storageRegistry.ts
+++ b/frontend/src/services/storageRegistry.ts
@@ -19,6 +19,7 @@ const UNAVAILABLE_CAPABILITIES: StorageBackendCapabilities = {
   canReadArchive: false,
   preview: { imageConversion: false, imageResizing: false, pdfNormalization: false },
   canWriteFile: false,
+  canEditText: false,
   canResolveActivation: false,
   canOpenInNativeApp: false,
 };
diff --git a/frontend/src/services/userSettingsStore.ts b/frontend/src/services/userSettingsStore.ts
index 8d2ccf677..6ce430b4e 100644
--- a/frontend/src/services/userSettingsStore.ts
+++ b/frontend/src/services/userSettingsStore.ts
@@ -9,7 +9,10 @@ export { SETTING_SUCCESS_DISPLAY_MS } from "./settingSaveFeedback";
 
 export type CurrentUserSettingsField = CurrentUserSettingsUpdate["field"];
 
-type ValueForField<Field extends CurrentUserSettingsField> = Extract<CurrentUserSettingsUpdate, { field: Field }>["value"];
+type CurrentUserSettingValues = {
+  [Field in CurrentUserSettingsField]: Extract<CurrentUserSettingsUpdate, { field: Field }>["value"];
+};
+type ValueForField<Field extends CurrentUserSettingsField> = CurrentUserSettingValues[Field];
 type CurrentUserSettingValue = CurrentUserSettingsUpdate["value"];
 
 export interface CurrentUserSetting<Field extends CurrentUserSettingsField> {
diff --git a/frontend/src/test/fixtures/connections.ts b/frontend/src/test/fixtures/connections.ts
index 9a6beac76..bf9bbc55a 100644
--- a/frontend/src/test/fixtures/connections.ts
+++ b/frontend/src/test/fixtures/connections.ts
@@ -8,7 +8,7 @@ import type { Connection } from "../../types";
 /**
  * Standard test connections for general use
  */
-export const mockConnections: Connection[] = [
+export const mockConnections: [Connection, Connection] = [
   {
     id: "conn-1",
     name: "Test Server 1",
diff --git a/frontend/src/test/fixtures/users.ts b/frontend/src/test/fixtures/users.ts
index 93e9d950a..edc6d760a 100644
--- a/frontend/src/test/fixtures/users.ts
+++ b/frontend/src/test/fixtures/users.ts
@@ -3,7 +3,63 @@
  * Reusable user data for tests
  */
 
-import type { User } from "../../types";
+import type { AdminUser, AdminUserListResponse, AuthToken, User } from "../../types";
+
+export function createMockAuthToken(overrides: Partial<AuthToken> = {}): AuthToken {
+  return {
+    access_token: "mock-token",
+    token_type: "bearer",
+    username: "test-user",
+    ...overrides,
+  };
+}
+
+export function createMockAdminUser(
+  overrides: Omit<Partial<AdminUser>, "oidc"> & { oidc?: Partial<NonNullable<AdminUser["oidc"]>> | null } = {}
+): AdminUser {
+  return {
+    id: "user-1",
+    username: "test-user",
+    role: "editor",
+    is_active: true,
+    must_change_password: false,
+    has_local_password: true,
+    oidc_role_assignment: null,
+    pending_oidc: null,
+    created_at: "2024-01-01T00:00:00Z",
+    updated_at: "2024-01-01T00:00:00Z",
+    ...overrides,
+    oidc: overrides.oidc
+      ? {
+          identity_id: "identity-1",
+          user_id: overrides.id ?? "user-1",
+          provider_display_name: "Test provider",
+          issuer: "https://identity.example.test",
+          subject: overrides.id ?? "user-1",
+          last_seen_username: overrides.username ?? "test-user",
+          last_groups: [],
+          created_at: "2024-01-01T00:00:00Z",
+          last_login_at: null,
+          ...overrides.oidc,
+        }
+      : null,
+  };
+}
+
+export function createMockAdminUserList(items: AdminUser[]): AdminUserListResponse {
+  return {
+    items,
+    total: items.length,
+    summary: {
+      total: items.length,
+      active_admins: items.filter((user) => user.is_active && user.role === "admin").length,
+      disabled: items.filter((user) => !user.is_active).length,
+      expiring_soon: 0,
+      pending_oidc: items.filter((user) => user.pending_oidc !== null).length,
+      unavailable_sign_in: items.filter((user) => !user.has_local_password && user.oidc === null).length,
+    },
+  };
+}
 
 /**
  * Standard admin user for testing
diff --git a/frontend/src/test/helpers/assertions.test.ts b/frontend/src/test/helpers/assertions.test.ts
new file mode 100644
index 000000000..fce194572
--- /dev/null
+++ b/frontend/src/test/helpers/assertions.test.ts
@@ -0,0 +1,25 @@
+import { describe, expect, it } from "vitest";
+import { requireTestElement, requireTestValue, uninitializedTestCallback } from "./assertions";
+
+describe("requireTestValue", () => {
+  it.each([null, undefined])("fails explicitly for %s", (value) => {
+    expect(() => requireTestValue(value)).toThrow("Expected a test fixture or result to be present");
+  });
+
+  it.each([false, 0, "", { value: 1 }])("preserves an existing value", (value) => {
+    expect(requireTestValue(value)).toBe(value);
+  });
+});
+
+it("fails explicitly for an uninitialized callback", () => {
+  expect(uninitializedTestCallback).toThrow("Test callback invoked before initialization");
+});
+
+it("requires the actual DOM element type", () => {
+  const textarea = document.createElement("textarea");
+  expect(requireTestElement(textarea, HTMLTextAreaElement)).toBe(textarea);
+  expect(() => requireTestElement(document.createElement("div"), HTMLTextAreaElement)).toThrow(
+    "Expected a HTMLTextAreaElement test element"
+  );
+  expect(() => requireTestElement(null, HTMLElement)).toThrow("Expected a HTMLElement test element");
+});
diff --git a/frontend/src/test/helpers/assertions.ts b/frontend/src/test/helpers/assertions.ts
new file mode 100644
index 000000000..8fe8052af
--- /dev/null
+++ b/frontend/src/test/helpers/assertions.ts
@@ -0,0 +1,20 @@
+export function requireTestValue<Value>(value: Value | null | undefined): Value {
+  if (value === null || value === undefined) {
+    throw new Error("Expected a test fixture or result to be present");
+  }
+  return value;
+}
+
+export function uninitializedTestCallback(): never {
+  throw new Error("Test callback invoked before initialization");
+}
+
+export function requireTestElement<ElementType extends Element>(
+  value: Element | null | undefined,
+  elementType: new () => ElementType
+): ElementType {
+  if (!(value instanceof elementType)) {
+    throw new Error(`Expected a ${elementType.name} test element`);
+  }
+  return value;
+}
diff --git a/frontend/src/test/helpers/mockFactories.ts b/frontend/src/test/helpers/mockFactories.ts
index 115662b59..4ed6adb5a 100644
--- a/frontend/src/test/helpers/mockFactories.ts
+++ b/frontend/src/test/helpers/mockFactories.ts
@@ -5,9 +5,41 @@
 
 import type { Mock } from "vitest";
 import { vi } from "vitest";
+import type { LocalArchiveExecution } from "../../services/api";
 import type { Connection, CurrentUserSettings, DirectoryListing, User } from "../../types";
 import { mockConnections, mockDirectoryListing, mockEmptyDirectory, mockNestedDirectory } from "../fixtures";
 
+export function createMockCurrentUserSettings(overrides: Partial<CurrentUserSettings> = {}): CurrentUserSettings {
+  return {
+    appearance: { theme_id: "sambee-light", custom_themes: [] },
+    localization: { language: "browser", regional_locale: "browser" },
+    browser: {
+      quick_nav_include_dot_directories: false,
+      quick_bar_shortcut_hint_visibility: "auto",
+      touch_friendly_file_selection: "auto",
+      file_browser_view_mode: "list",
+      pane_mode: "single",
+      selected_connection_id: null,
+      viewer_associations: {},
+    },
+    text_editor: { max_file_size_bytes: 52428800, word_wrap_enabled: null },
+    ...overrides,
+  };
+}
+
+export function createMockLocalArchiveExecution(overrides: Partial<LocalArchiveExecution> = {}): LocalArchiveExecution {
+  return {
+    contract_version: "v2",
+    execution_id: "test-execution",
+    kind: "extract",
+    phase: "streaming",
+    revision: 1,
+    progress: { completedMembers: 0, skippedMembers: 0, failedMembers: 0 },
+    cancellation_requested: false,
+    ...overrides,
+  };
+}
+
 /**
  * API Mock Factory Interface
  */
@@ -67,6 +99,7 @@ export function setupSuccessfulApiMocks(api: ApiMock): void {
     },
     text_editor: {
       max_file_size_bytes: 52428800,
+      word_wrap_enabled: null,
     },
   };
 
@@ -180,6 +213,7 @@ export function setupNavigationApiMocks(api: ApiMock): void {
     },
     text_editor: {
       max_file_size_bytes: 52428800,
+      word_wrap_enabled: null,
     },
   };
 
@@ -250,6 +284,8 @@ export function createMockApi(): ApiMock {
   return {
     getConnections: vi.fn(),
     listDirectory: vi.fn(),
+    listArchiveDirectory: vi.fn(),
+    listLocalLinkTargets: vi.fn(),
     getCurrentUser: vi.fn(),
     getCurrentUserSettings: vi.fn(),
     testConnection: vi.fn(),
diff --git a/frontend/src/test/integration-utils.tsx b/frontend/src/test/integration-utils.tsx
index f5069e8b6..9e9c91a64 100644
--- a/frontend/src/test/integration-utils.tsx
+++ b/frontend/src/test/integration-utils.tsx
@@ -41,7 +41,7 @@ export function renderApp(initialRoute = "/") {
         <Suspense fallback={<div>Loading...</div>}>
           <Routes>
             <Route path="/login" element={<Login />} />
-            <Route path="/browse/:targetType/:targetId/*" element={<Browser />} />
+            <Route path="/browse/:targetType/:targetId/*" element={<FileBrowser />} />
             <Route path="/browse" element={<FileBrowser />} />
             <Route path="/" element={<Navigate to="/browse" replace />} />
           </Routes>
diff --git a/frontend/src/test/setup.ts b/frontend/src/test/setup.ts
index 042aebf0b..12c5f7dd4 100644
--- a/frontend/src/test/setup.ts
+++ b/frontend/src/test/setup.ts
@@ -37,19 +37,20 @@ Object.defineProperty(window, "location", {
 // Start MSW server before all tests
 beforeAll(() => {
   server.listen({
-    onUnhandledRequest(request, print) {
+    onUnhandledFrame({ frame, defaults }) {
       // Ignore WebSocket connection attempts - they're mocked separately
-      if (request.url.includes("/api/ws") || request.url.startsWith("ws://")) {
+      if (frame.protocol === "ws") {
         return;
       }
+      const request = frame.data && typeof frame.data === "object" && "request" in frame.data ? frame.data.request : null;
       // Ignore companion background health probes triggered by FileBrowser.
       // These requests are expected during test startup and their failures are
       // already handled by the hook as a normal "companion unavailable" path.
-      if (request.url === "http://localhost:21549/api/health") {
+      if (request instanceof Request && (request.url.includes("/api/ws") || request.url === "http://localhost:21549/api/health")) {
         return;
       }
       // Warn about other unhandled requests
-      print.warning();
+      defaults.warn();
     },
   });
 });
@@ -149,7 +150,7 @@ Object.defineProperty(window, "localStorage", {
   value: localStorageMock,
 });
 
-if (typeof globalThis.Iterator === "undefined") {
+if (typeof Reflect.get(globalThis, "Iterator") === "undefined") {
   class IteratorHelperPolyfill<TValue> {
     private readonly values: TValue[];
 
diff --git a/frontend/src/theme/ThemeContext.tsx b/frontend/src/theme/ThemeContext.tsx
index e59ebf8dc..35c5a792a 100644
--- a/frontend/src/theme/ThemeContext.tsx
+++ b/frontend/src/theme/ThemeContext.tsx
@@ -11,6 +11,8 @@ import {
   OVERLAY_SURFACE_CSS_VARIABLE,
   resolveThemePalette,
 } from "./palette";
+import { resolveSyntaxTheme } from "./resolveSyntaxTheme";
+import { syntaxTokenStyles } from "./syntaxStyles";
 import { builtInThemes, getDefaultTheme } from "./themes";
 import type { ThemeConfig } from "./types";
 
@@ -109,7 +111,7 @@ export function SambeeThemeProvider({ children }: ThemeProviderProps) {
 
   // All available themes (built-in + custom)
   const availableThemes = useMemo(
-    () => [...builtInThemes, ...storedThemes.map((stored) => ({ ...stored.definition, id: stored.id }))],
+    () => [...builtInThemes, ...storedThemes.map((stored) => resolveSyntaxTheme({ ...stored.definition, id: stored.id }))],
     [storedThemes]
   );
 
@@ -179,7 +181,9 @@ export function SambeeThemeProvider({ children }: ThemeProviderProps) {
         action,
         appBar,
         statusBar,
+        link,
         markdownDocument: currentTheme.components?.markdownViewer?.document,
+        syntax: currentTheme.components?.syntax,
       },
       typography: {
         fontFamily: ["-apple-system", "BlinkMacSystemFont", '"Segoe UI"', "Roboto", '"Helvetica Neue"', "Arial", "sans-serif"].join(","),
@@ -187,6 +191,7 @@ export function SambeeThemeProvider({ children }: ThemeProviderProps) {
       components: {
         MuiCssBaseline: {
           styleOverrides: {
+            ...syntaxTokenStyles,
             body: {
               scrollbarColor: `${scrollbarThumb} ${scrollbarTrack}`,
               "&::-webkit-scrollbar, & *::-webkit-scrollbar": {
diff --git a/frontend/src/theme/__tests__/ThemeContext.test.tsx b/frontend/src/theme/__tests__/ThemeContext.test.tsx
index e574d5997..85a3e3807 100644
--- a/frontend/src/theme/__tests__/ThemeContext.test.tsx
+++ b/frontend/src/theme/__tests__/ThemeContext.test.tsx
@@ -2,6 +2,7 @@ import { readFileSync } from "node:fs";
 import { act, renderHook, waitFor } from "@testing-library/react";
 import type { ReactNode } from "react";
 import { beforeEach, describe, expect, it, vi } from "vitest";
+import { createMockAuthToken } from "../../test/fixtures/users";
 
 const { useCurrentUserSettingMock, getThemesMock, getCurrentUserMock, refreshSettingsMock } = vi.hoisted(() => ({
   useCurrentUserSettingMock: vi.fn(),
@@ -82,7 +83,8 @@ describe("ThemeContext", () => {
 
     await waitFor(() => expect(result.current.currentTheme).toMatchObject(customTheme));
     expect(result.current.muiTheme.palette.mode).toBe("dark");
-    expect(result.current.availableThemes).toContainEqual(customTheme);
+    expect(result.current.availableThemes).toContainEqual(expect.objectContaining(customTheme));
+    expect(result.current.muiTheme.palette.syntax).toEqual(result.current.currentTheme.components?.syntax);
     expect(document.querySelector('meta[name="theme-color"]')).toHaveAttribute("content", "#123456");
   });
 
@@ -116,13 +118,13 @@ describe("ThemeContext", () => {
   it("reloads themes and user settings once for a same-user login, not for a token refresh", async () => {
     const { unmount } = renderHook(() => useSambeeTheme(), { wrapper: createWrapper() });
     await waitFor(() => expect(getThemesMock).toHaveBeenCalledTimes(1));
-    authSession.setAuthenticated({ access_token: "a", token_type: "bearer", user_id: "same-user" }, true);
+    authSession.setAuthenticated(createMockAuthToken({ access_token: "a", token_type: "bearer", user_id: "same-user" }), true);
     await waitFor(() => expect(getThemesMock).toHaveBeenCalledTimes(2));
     await waitFor(() => expect(refreshSettingsMock).toHaveBeenCalledTimes(2));
-    authSession.setAuthenticated({ access_token: "refreshed", token_type: "bearer", user_id: "same-user" }, true);
+    authSession.setAuthenticated(createMockAuthToken({ access_token: "refreshed", token_type: "bearer", user_id: "same-user" }), true);
     expect(getThemesMock).toHaveBeenCalledTimes(2);
     expect(refreshSettingsMock).toHaveBeenCalledTimes(2);
-    authSession.setAuthenticated({ access_token: "b", token_type: "bearer", user_id: "same-user" }, true);
+    authSession.setAuthenticated(createMockAuthToken({ access_token: "b", token_type: "bearer", user_id: "same-user" }), true);
     authSession.notifyNewLogin();
     await waitFor(() => expect(getThemesMock).toHaveBeenCalledTimes(3));
     await waitFor(() => expect(refreshSettingsMock).toHaveBeenCalledTimes(3));
@@ -146,14 +148,16 @@ describe("ThemeContext", () => {
           rejectUser = reject;
         })
     );
-    authSession.setAuthenticated({ access_token: "a", token_type: "bearer", user_id: "same-user" }, true);
+    authSession.setAuthenticated(createMockAuthToken({ access_token: "a", token_type: "bearer", user_id: "same-user" }), true);
     const tracing = vi.spyOn(logger, "initializeBackendTracing").mockResolvedValue(undefined);
     const { result, unmount } = renderHook(() => useSambeeTheme(), { wrapper: createWrapper() });
     await waitFor(() => expect(getThemesMock).toHaveBeenCalledTimes(1));
     getThemesMock.mockResolvedValue({ themes: [], site_default_id: "sambee-dark" });
     getCurrentUserMock.mockResolvedValue({ role: "admin" });
     await act(async () => {
-      await completeAuthentication({ access_token: "b", token_type: "bearer", user_id: "same-user", return_path: "/browse" });
+      await completeAuthentication(
+        createMockAuthToken({ access_token: "b", token_type: "bearer", user_id: "same-user", return_path: "/browse" })
+      );
     });
     await waitFor(() => expect(result.current.currentTheme.id).toBe("sambee-dark"));
     await act(async () => {
diff --git a/frontend/src/theme/__tests__/resolveSyntaxTheme.test.ts b/frontend/src/theme/__tests__/resolveSyntaxTheme.test.ts
new file mode 100644
index 000000000..ab35c4377
--- /dev/null
+++ b/frontend/src/theme/__tests__/resolveSyntaxTheme.test.ts
@@ -0,0 +1,67 @@
+import { createTheme } from "@mui/material/styles";
+import { describe, expect, it } from "vitest";
+import { resolveSyntaxTheme } from "../resolveSyntaxTheme";
+import { getSyntaxVariables, syntaxTokenStyles } from "../syntaxStyles";
+import { editableDefinition, parseThemeImport } from "../themeDefinition";
+import { getDefaultTheme } from "../themes";
+
+describe("syntax theme compatibility", () => {
+  it.each(["light", "dark"] as const)("reuses existing %s theme roles for richer token categories", (mode) => {
+    const palette = getDefaultTheme(mode).components!.syntax!;
+    const variables = getSyntaxVariables(createTheme({ palette: { mode, syntax: palette } }));
+    for (const [category, role] of [
+      ["builtin", "function"],
+      ["property", "type"],
+      ["boolean", "keyword"],
+      ["null", "keyword"],
+      ["regexp", "type"],
+      ["escape", "operator"],
+      ["metadata", "keyword"],
+    ] as const) {
+      expect(syntaxTokenStyles[`.sambee-syntax-${category}`]).toEqual({ color: `var(--sambee-syntax-${role})` });
+      expect(variables[`--sambee-syntax-${role}` as keyof typeof variables]).toBe(palette[role]);
+    }
+    expect(Object.keys(palette)).toHaveLength(8);
+    expect(syntaxTokenStyles[".sambee-syntax-identifier"]).toEqual({ color: "var(--sambee-syntax-foreground, inherit)" });
+  });
+  it("does not let typography-only classes override combined heading or link colors", () => {
+    for (const category of ["emphasis", "strong", "strikethrough"]) {
+      expect(syntaxTokenStyles[`.sambee-syntax-${category}`]).not.toHaveProperty("color");
+    }
+  });
+  it.each(["light", "dark"] as const)("resolves legacy %s themes without mutation", (mode) => {
+    const legacy = structuredClone(getDefaultTheme(mode));
+    delete legacy.components!.syntax;
+    const snapshot = structuredClone(legacy);
+    const resolved = resolveSyntaxTheme(legacy);
+    expect(resolved.components!.syntax).toEqual(getDefaultTheme(mode).components!.syntax);
+    expect(legacy).toEqual(snapshot);
+    expect(resolveSyntaxTheme(resolved)).toEqual(resolved);
+    expect(parseThemeImport(JSON.stringify({ version: 1, definition: editableDefinition(legacy) })).components!.syntax).toEqual(
+      resolved.components!.syntax
+    );
+    const oldExport = editableDefinition(legacy);
+    delete oldExport.components!.syntax;
+    expect(parseThemeImport(JSON.stringify({ version: 1, definition: oldExport })).components!.syntax).toEqual(resolved.components!.syntax);
+  });
+
+  it.each([
+    null,
+    {},
+    { keyword: "#123456" },
+    { ...getDefaultTheme().components!.syntax, extra: "#123456" },
+    { ...getDefaultTheme().components!.syntax, string: "red" },
+  ])("rejects supplied malformed groups %j", (syntax) => {
+    const theme = structuredClone(getDefaultTheme());
+    Object.assign(theme.components!, { syntax });
+    expect(() => resolveSyntaxTheme(theme)).toThrow("Syntax colors");
+  });
+
+  it("retains custom alpha colors through export and import", () => {
+    const theme = structuredClone(getDefaultTheme());
+    theme.components!.syntax!.keyword = "#12345678";
+    expect(parseThemeImport(JSON.stringify({ version: 1, definition: editableDefinition(theme) })).components!.syntax).toEqual(
+      theme.components!.syntax
+    );
+  });
+});
diff --git a/frontend/src/theme/__tests__/themes.test.ts b/frontend/src/theme/__tests__/themes.test.ts
index a5cdf5d2e..68517fd94 100644
--- a/frontend/src/theme/__tests__/themes.test.ts
+++ b/frontend/src/theme/__tests__/themes.test.ts
@@ -1,5 +1,9 @@
+import { createTheme, getContrastRatio } from "@mui/material/styles";
+import { blend, decomposeColor } from "@mui/system/colorManipulator";
 import { describe, expect, it } from "vitest";
 import builtInThemeIds from "../../../../shared/built_in_theme_ids.json";
+import { requireTestValue } from "../../test/helpers/assertions";
+import { getSearchHighlightColors } from "../commonStyles";
 import { resolveThemePalette } from "../palette";
 import { builtInThemes, getDefaultTheme, getThemeById } from "../themes";
 
@@ -8,6 +12,32 @@ import { builtInThemes, getDefaultTheme, getThemeById } from "../themes";
 //
 
 describe("Theme System - themes.ts", () => {
+  it.each(builtInThemes)("keeps all $id syntax roles readable on viewer and code backgrounds", (definition) => {
+    const document = definition.components!.markdownViewer!;
+    for (const foreground of Object.values(definition.components!.syntax!)) {
+      for (const background of [document.viewerBackground, document.document!.blockBackground]) {
+        expect(getContrastRatio(foreground, background)).toBeGreaterThanOrEqual(4.5);
+      }
+    }
+  });
+
+  it.each(builtInThemes)("keeps $id search text readable on viewer and code backgrounds", (definition) => {
+    const theme = createTheme({ palette: { mode: definition.mode } });
+    const document = definition.components!.markdownViewer!;
+    const highlights = getSearchHighlightColors(theme, definition);
+    for (const overlay of Object.values(highlights)) {
+      const opacity = Number(decomposeColor(overlay).values[3]);
+      for (const [foreground, background] of [
+        [document.viewerText, document.viewerBackground],
+        [document.document!.codeText, document.document!.blockBackground],
+      ]) {
+        expect(
+          getContrastRatio(requireTestValue(foreground), blend(requireTestValue(background), overlay, opacity))
+        ).toBeGreaterThanOrEqual(4.5);
+      }
+    }
+  });
+
   describe("builtInThemes", () => {
     it("should have at least 2 built-in themes", () => {
       expect(builtInThemes.length).toBeGreaterThanOrEqual(2);
diff --git a/frontend/src/theme/__tests__/viewerStyles.test.ts b/frontend/src/theme/__tests__/viewerStyles.test.ts
index b3e689e44..80d5b3e0a 100644
--- a/frontend/src/theme/__tests__/viewerStyles.test.ts
+++ b/frontend/src/theme/__tests__/viewerStyles.test.ts
@@ -51,18 +51,18 @@ describe("viewerStyles markdown regressions", () => {
     const inlineCodeStyles = styles["& code:not(pre code)"] as Record<string, unknown>;
     const preCodeStyles = styles["& pre code, & pre code.hljs"] as Record<string, unknown>;
 
-    expect(resolveThemeValue(preStyles.backgroundColor, darkTheme)).toBe("#1f1914");
-    expect(resolveThemeValue(preStyles.color, darkTheme)).toBe("#ebe8e2");
-    expect(resolveThemeValue(preStyles.border, darkTheme)).toBe("1px solid #504535");
-    expect(preStyles.padding).toBe("1.25rem");
+    expect(resolveThemeValue(preStyles["backgroundColor"], darkTheme)).toBe("#1f1914");
+    expect(resolveThemeValue(preStyles["color"], darkTheme)).toBe("#ebe8e2");
+    expect(resolveThemeValue(preStyles["border"], darkTheme)).toBe("1px solid #504535");
+    expect(preStyles["padding"]).toBe("1.25rem");
 
-    expect(preCodeStyles.display).toBe("block");
-    expect(preCodeStyles.padding).toBe(0);
-    expect(preCodeStyles.backgroundColor).toBe("transparent");
+    expect(preCodeStyles["display"]).toBe("block");
+    expect(preCodeStyles["padding"]).toBe(0);
+    expect(preCodeStyles["backgroundColor"]).toBe("transparent");
 
-    expect(resolveThemeValue(inlineCodeStyles.backgroundColor, darkTheme)).toBe("#2b2925");
-    expect(resolveThemeValue(inlineCodeStyles.color, darkTheme)).toBe("#ebe8e2");
-    expect(resolveThemeValue(inlineCodeStyles.border, darkTheme)).toBe("1px solid #3b3935");
+    expect(resolveThemeValue(inlineCodeStyles["backgroundColor"], darkTheme)).toBe("#2b2925");
+    expect(resolveThemeValue(inlineCodeStyles["color"], darkTheme)).toBe("#ebe8e2");
+    expect(resolveThemeValue(inlineCodeStyles["border"], darkTheme)).toBe("1px solid #3b3935");
   });
 
   it("keeps markdown tables naturally sized but horizontally scrollable", () => {
@@ -71,19 +71,19 @@ describe("viewerStyles markdown regressions", () => {
 
     const tableStyles = styles["& table"] as Record<string, unknown>;
 
-    expect(tableStyles.display).toBe("block");
-    expect(tableStyles.width).toBe("max-content");
-    expect(tableStyles.maxWidth).toBe("100%");
-    expect(tableStyles.overflowX).toBe("auto");
-    expect(tableStyles.border).toBe(0);
-    expect(resolveThemeValue(tableStyles.boxShadow, lightTheme)).toBe("inset 0 0 0 1px #d4c4ae");
-    expect(resolveThemeValue(tableStyles.backgroundColor, lightTheme)).toBe("#fbf9f4");
+    expect(tableStyles["display"]).toBe("block");
+    expect(tableStyles["width"]).toBe("max-content");
+    expect(tableStyles["maxWidth"]).toBe("100%");
+    expect(tableStyles["overflowX"]).toBe("auto");
+    expect(tableStyles["border"]).toBe(0);
+    expect(resolveThemeValue(tableStyles["boxShadow"], lightTheme)).toBe("inset 0 0 0 1px #d4c4ae");
+    expect(resolveThemeValue(tableStyles["backgroundColor"], lightTheme)).toBe("#fbf9f4");
   });
 
   it("keeps end padding outside the shrunk Markdown content", () => {
     const styles = getMarkdownContentStyles("#1f262b", "#c24400", "#ff5900") as Record<string, unknown>;
 
-    expect(styles.flexShrink).toBe(0);
-    expect(styles.pb).toEqual(VIEWER_SCROLL_END_PADDING);
+    expect(styles["flexShrink"]).toBe(0);
+    expect(styles["pb"]).toEqual(VIEWER_SCROLL_END_PADDING);
   });
 });
diff --git a/frontend/src/theme/commonStyles.ts b/frontend/src/theme/commonStyles.ts
index 93edce75a..8c1416b19 100644
--- a/frontend/src/theme/commonStyles.ts
+++ b/frontend/src/theme/commonStyles.ts
@@ -9,6 +9,10 @@ import type { ThemeConfig } from "./types";
 /** Focus ring width to match FOCUS_OUTLINE_WIDTH_PX from theme constants */
 const FOCUS_RING_WIDTH = 3;
 const CONTAINED_BUTTON_FOCUS_INNER_RING_WIDTH = 1;
+const SEARCH_HIGHLIGHT_OPACITY = {
+  light: { other: 0.3, current: 0.36 },
+  dark: { other: 0.4, current: 0.44 },
+};
 
 export function getControlAccentColor(theme: Theme): string {
   return theme.palette.mode === "dark" ? theme.palette.primary.main : (theme.palette.primary.dark ?? theme.palette.primary.main);
@@ -64,10 +68,11 @@ export function getSearchHighlightColors(theme: Theme, themeConfig?: ThemeConfig
   const otherMatchesBase =
     themeConfig?.components?.search?.otherMatch ?? theme.palette.warning.main ?? theme.palette.primary.dark ?? theme.palette.primary.main;
   const currentMatchBase = themeConfig?.components?.search?.currentMatch ?? theme.palette.info.main ?? theme.palette.primary.main;
+  const opacity = SEARCH_HIGHLIGHT_OPACITY[theme.palette.mode];
 
   return {
-    otherMatches: alpha(otherMatchesBase, theme.palette.mode === "dark" ? 0.5 : 0.3),
-    currentMatch: alpha(currentMatchBase, theme.palette.mode === "dark" ? 0.52 : 0.36),
+    otherMatches: alpha(otherMatchesBase, opacity.other),
+    currentMatch: alpha(currentMatchBase, opacity.current),
   };
 }
 
@@ -110,7 +115,7 @@ export function getSecondaryActionStripStyle(theme: Theme) {
   };
 }
 
-export const secondaryActionStripSx: SxProps<Theme> = (theme) => getSecondaryActionStripStyle(theme);
+export const secondaryActionStripSx = ((theme: Theme) => getSecondaryActionStripStyle(theme)) satisfies SxProps<Theme>;
 
 export function getSecondaryToolbarMenuPaperStyle(theme: Theme) {
   const colors = getSecondaryToolbarSurfaceColors(theme);
diff --git a/frontend/src/theme/mobileShell.ts b/frontend/src/theme/mobileShell.ts
index e5587cab4..b6b15bec9 100644
--- a/frontend/src/theme/mobileShell.ts
+++ b/frontend/src/theme/mobileShell.ts
@@ -15,7 +15,7 @@ export const MOBILE_VIEWPORT_HEIGHT = "100dvh";
  * This prevents iOS Safari and Chrome mobile browser UI changes from dragging
  * the entire app surface under hardware cutouts or browser chrome.
  */
-export function getMobileViewportShellSx(lockToViewport = false): SxProps<Theme> {
+export function getMobileViewportShellSx(lockToViewport = false) {
   return {
     display: "flex",
     flexDirection: "column",
@@ -32,7 +32,7 @@ export function getMobileViewportShellSx(lockToViewport = false): SxProps<Theme>
           inset: { xs: 0 },
         }
       : {}),
-  };
+  } satisfies SxProps<Theme>;
 }
 
 export const mobileSafeAreaAppBarSx: SxProps<Theme> = {
@@ -59,15 +59,15 @@ export const mobileScrollableContentSx: SxProps<Theme> = {
   WebkitOverflowScrolling: "touch",
 };
 
-export const mobileFullscreenDrawerPaperSx: SxProps<Theme> = {
+export const mobileFullscreenDrawerPaperSx = {
   width: "100%",
   height: MOBILE_VIEWPORT_HEIGHT,
   maxHeight: MOBILE_VIEWPORT_HEIGHT,
   overflow: "hidden",
-};
+} satisfies SxProps<Theme>;
 
 /** Compact typography policy for the main navigation drawer. */
-export const mobileNavigationDrawerTypographySx: SxProps<Theme> = (theme) => ({
+export const mobileNavigationDrawerTypographySx = ((theme: Theme) => ({
   [theme.breakpoints.down("sm")]: {
     "& .MuiTypography-h6": {
       fontSize: `${COMPACT_LAYOUT_SIZE.DIALOG_TITLE_PX}px`,
@@ -76,4 +76,4 @@ export const mobileNavigationDrawerTypographySx: SxProps<Theme> = (theme) => ({
       fontSize: `${COMPACT_LAYOUT_SIZE.MENU_TEXT_PX}px`,
     },
   },
-});
+})) satisfies SxProps<Theme>;
diff --git a/frontend/src/theme/mui-theme-extensions.d.ts b/frontend/src/theme/mui-theme-extensions.d.ts
index 5ded35dce..0bbaea55a 100644
--- a/frontend/src/theme/mui-theme-extensions.d.ts
+++ b/frontend/src/theme/mui-theme-extensions.d.ts
@@ -3,12 +3,14 @@
  */
 
 import "@mui/material/styles";
-import type { ThemeConfig } from "./types";
+import type { SyntaxPalette, ThemeConfig } from "./types";
 
 type MarkdownDocumentColors = NonNullable<NonNullable<ThemeConfig["components"]>["markdownViewer"]>["document"];
 
 declare module "@mui/material/styles" {
   interface Palette {
+    link?: { main: string; hover: string };
+    syntax?: SyntaxPalette;
     chrome?: string;
     markdownDocument?: MarkdownDocumentColors;
     appBar?: {
@@ -24,6 +26,8 @@ declare module "@mui/material/styles" {
   }
 
   interface PaletteOptions {
+    link?: { main: string; hover: string };
+    syntax?: SyntaxPalette;
     chrome?: string;
     markdownDocument?: MarkdownDocumentColors;
     appBar?: {
diff --git a/frontend/src/theme/resolveSyntaxTheme.ts b/frontend/src/theme/resolveSyntaxTheme.ts
new file mode 100644
index 000000000..f59380f66
--- /dev/null
+++ b/frontend/src/theme/resolveSyntaxTheme.ts
@@ -0,0 +1,22 @@
+import { getDefaultTheme } from "./themes";
+import { HEX_COLOR_PATTERN, SYNTAX_COLOR_ROLES, type ThemeConfig } from "./types";
+
+export function resolveSyntaxTheme(theme: ThemeConfig): ThemeConfig {
+  const syntax = theme.components?.syntax;
+  if (syntax !== undefined || Object.keys(theme.components ?? {}).includes("syntax")) {
+    if (
+      !syntax ||
+      typeof syntax !== "object" ||
+      Array.isArray(syntax) ||
+      Object.keys(syntax).length !== SYNTAX_COLOR_ROLES.length ||
+      SYNTAX_COLOR_ROLES.some((role) => typeof syntax[role] !== "string" || !HEX_COLOR_PATTERN.test(syntax[role]))
+    ) {
+      throw new Error("Syntax colors must contain exactly all eight valid #RRGGBB or #RRGGBBAA roles.");
+    }
+    return structuredClone(theme);
+  }
+  return {
+    ...structuredClone(theme),
+    components: { ...structuredClone(theme.components), syntax: { ...getDefaultTheme(theme.mode).components!.syntax! } },
+  };
+}
diff --git a/frontend/src/theme/syntaxStyles.ts b/frontend/src/theme/syntaxStyles.ts
new file mode 100644
index 000000000..0a6c6bebf
--- /dev/null
+++ b/frontend/src/theme/syntaxStyles.ts
@@ -0,0 +1,35 @@
+import type { Theme } from "@mui/material";
+import type { CSSProperties } from "react";
+import { TOKEN_CATEGORIES, TOKEN_COLOR_ROLES, tokenClasses } from "../utils/syntaxHighlighting";
+import { getDefaultTheme } from "./themes";
+import { SYNTAX_COLOR_ROLES } from "./types";
+
+export const syntaxTokenStyles = Object.fromEntries(
+  TOKEN_CATEGORIES.map((category) => {
+    const role = TOKEN_COLOR_ROLES[category];
+    const color =
+      category === "identifier" || category === "inlineCode"
+        ? "var(--sambee-syntax-foreground, inherit)"
+        : category === "emphasis" || category === "strong" || category === "strikethrough"
+          ? "inherit"
+          : `var(--sambee-syntax-${role})`;
+    return [
+      `.${tokenClasses([category])}`,
+      {
+        ...(category === "emphasis" || category === "strong" || category === "strikethrough" ? {} : { color }),
+        ...(category === "emphasis" ? { fontStyle: "italic" } : {}),
+        ...(category === "strong" ? { fontWeight: "bold" } : {}),
+        ...(category === "strikethrough" ? { textDecoration: "line-through" } : {}),
+      },
+    ];
+  })
+);
+
+export function getSyntaxVariables(theme: Theme, linkColor?: string): CSSProperties {
+  const palette = theme.palette.syntax ?? getDefaultTheme(theme.palette.mode).components!.syntax!;
+  return {
+    ...Object.fromEntries(SYNTAX_COLOR_ROLES.map((role) => [`--sambee-syntax-${role}`, palette[role]])),
+    "--sambee-syntax-foreground": theme.palette.markdownDocument?.codeText ?? "inherit",
+    "--sambee-syntax-link": linkColor ?? theme.palette.link?.main ?? getDefaultTheme(theme.palette.mode).components!.link!.main,
+  } as CSSProperties;
+}
diff --git a/frontend/src/theme/themeDefinition.ts b/frontend/src/theme/themeDefinition.ts
index 3cb3c84de..ef378cf6c 100644
--- a/frontend/src/theme/themeDefinition.ts
+++ b/frontend/src/theme/themeDefinition.ts
@@ -1,7 +1,9 @@
-import { THEME_SCHEMA, type ThemeConfig, type ThemeFieldSchema } from "./types";
+import { resolveSyntaxTheme } from "./resolveSyntaxTheme";
+import { HEX_COLOR_PATTERN, THEME_SCHEMA, type ThemeConfig, type ThemeFieldSchema } from "./types";
+
+export { HEX_COLOR_PATTERN } from "./types";
 
 export const THEME_DEFINITION_VERSION = 1;
-export const HEX_COLOR_PATTERN = /^#[\da-fA-F]{6}(?:[\da-fA-F]{2})?$/;
 const COPY_SUFFIX = " (copy)";
 
 export function getThemeCopyName(name: string, existingNames: Iterable<string>, alwaysCopy = false): string {
@@ -31,13 +33,14 @@ function collectColors(schema: ThemeFieldSchema, prefix: string, group: string):
 }
 
 export const COLOR_ROLES: ColorRole[] = [
+  ...collectColors(THEME_SCHEMA["components"]!.fields!["syntax"]!, "components.syntax", "Syntax"),
   ...["primary", "background", "text", "action"].flatMap((key) => collectColors(THEME_SCHEMA[key]!, key, "Core")),
   ...["pdfViewer", "imageViewer", "markdownViewer"].flatMap((key) =>
-    collectColors(THEME_SCHEMA.components!.fields![key]!, `components.${key}`, key === "markdownViewer" ? "Markdown" : "Viewers")
+    collectColors(THEME_SCHEMA["components"]!.fields![key]!, `components.${key}`, key === "markdownViewer" ? "Markdown" : "Viewers")
   ),
   ...["link", "search", "alert"].flatMap((key) =>
     collectColors(
-      THEME_SCHEMA.components!.fields![key]!,
+      THEME_SCHEMA["components"]!.fields![key]!,
       `components.${key}`,
       key === "link" ? "Core" : key === "search" ? "Search" : "Alerts"
     )
@@ -72,6 +75,11 @@ export function withColor(theme: ThemeConfig, path: string, color: string): Them
 }
 
 export function validateThemeDefinition(theme: ThemeConfig): string | null {
+  try {
+    theme = resolveSyntaxTheme(theme);
+  } catch (error) {
+    return error instanceof Error ? error.message : "Invalid syntax colors.";
+  }
   if (!theme.name.trim()) return "Enter a theme name.";
   if (theme.mode !== "light" && theme.mode !== "dark") return "Choose light or dark mode.";
   for (const role of COLOR_ROLES) {
@@ -81,7 +89,7 @@ export function validateThemeDefinition(theme: ThemeConfig): string | null {
 }
 
 export function editableDefinition(theme: ThemeConfig): Omit<ThemeConfig, "id"> {
-  const copy = structuredClone(theme);
+  const copy = resolveSyntaxTheme(theme);
   const { id: _id, ...definition } = copy;
   void _id;
   delete definition.background?.paper;
@@ -95,15 +103,18 @@ export function parseThemeImport(source: string): ThemeConfig {
   if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("Import a versioned theme definition.");
   const exportFile = parsed as Record<string, unknown>;
   if (
-    exportFile.version !== THEME_DEFINITION_VERSION ||
-    !exportFile.definition ||
-    typeof exportFile.definition !== "object" ||
-    Array.isArray(exportFile.definition)
+    exportFile["version"] !== THEME_DEFINITION_VERSION ||
+    !exportFile["definition"] ||
+    typeof exportFile["definition"] !== "object" ||
+    Array.isArray(exportFile["definition"])
   ) {
     throw new Error("Unsupported theme format or version.");
   }
-  const definition = exportFile.definition as Record<string, unknown>;
-  if (typeof definition.name !== "string" || (definition.description !== undefined && typeof definition.description !== "string")) {
+  const definition = exportFile["definition"] as Record<string, unknown>;
+  if (
+    typeof definition["name"] !== "string" ||
+    (definition["description"] !== undefined && typeof definition["description"] !== "string")
+  ) {
     throw new Error("Theme name and description must be text.");
   }
   const allowedPaths = new Set(["id", "name", "description", "mode"]);
@@ -119,7 +130,7 @@ export function parseThemeImport(source: string): ThemeConfig {
     }
   };
   checkPaths(definition);
-  const theme = { ...(exportFile.definition as ThemeConfig), id: "draft" };
+  const theme = resolveSyntaxTheme({ ...(exportFile["definition"] as ThemeConfig), id: "draft" });
   for (const role of COLOR_ROLES) {
     const value = colorAt(theme, role.path);
     if (!HEX_COLOR_PATTERN.test(value ?? "")) {
diff --git a/frontend/src/theme/themes.ts b/frontend/src/theme/themes.ts
index fd503a402..e27bc1d30 100644
--- a/frontend/src/theme/themes.ts
+++ b/frontend/src/theme/themes.ts
@@ -33,6 +33,16 @@ export const builtInThemes: ThemeConfig[] = [
       selected: "#F4C43029", // 16% opacity
     },
     components: {
+      syntax: {
+        keyword: "#A62640",
+        string: "#216A35",
+        number: "#805400",
+        comment: "#626A73",
+        type: "#6851A5",
+        function: "#005C99",
+        operator: "#8F3540",
+        punctuation: "#525960",
+      },
       link: {
         main: "#C24400", // Dark for readability
         hover: "#FF5900", // Lighter on hover for visual feedback
@@ -123,6 +133,16 @@ export const builtInThemes: ThemeConfig[] = [
       selected: "#D4A02038", // 22% opacity
     },
     components: {
+      syntax: {
+        keyword: "#FF8999",
+        string: "#A3D99B",
+        number: "#EDC47C",
+        comment: "#A2A9B1",
+        type: "#D1B3F0",
+        function: "#8FC8F5",
+        operator: "#F2A6B0",
+        punctuation: "#BCC3CB",
+      },
       link: {
         main: "#D4A020", // Default dark-mode primary shade
         hover: "#F4C430", // Brighter hover shade
diff --git a/frontend/src/theme/types.ts b/frontend/src/theme/types.ts
index 87a1634aa..cc89d789d 100644
--- a/frontend/src/theme/types.ts
+++ b/frontend/src/theme/types.ts
@@ -1,5 +1,9 @@
 import type { PaletteMode } from "@mui/material";
 
+export const SYNTAX_COLOR_ROLES = ["keyword", "string", "number", "comment", "type", "function", "operator", "punctuation"] as const;
+export const HEX_COLOR_PATTERN = /^#[\da-fA-F]{6}(?:[\da-fA-F]{2})?$/;
+export type SyntaxPalette = Record<(typeof SYNTAX_COLOR_ROLES)[number], string>;
+
 //
 // Theme types
 //
@@ -47,6 +51,7 @@ export interface ThemeConfig {
   };
   /** Component-specific semantic colors */
   components?: {
+    syntax?: SyntaxPalette;
     /** Link colors */
     link?: {
       /** Default link color */
@@ -294,6 +299,23 @@ export const THEME_SCHEMA: Record<string, ThemeFieldSchema> = {
     type: "color",
     required: false,
     fields: {
+      syntax: {
+        label: "Syntax",
+        description: "Shared code foreground colors",
+        type: "color",
+        required: false,
+        fields: Object.fromEntries(
+          SYNTAX_COLOR_ROLES.map((role) => [
+            role,
+            {
+              label: `${role.charAt(0).toUpperCase()}${role.slice(1)}`,
+              description: `Code ${role} foreground`,
+              type: "color" as const,
+              required: true,
+            },
+          ])
+        ),
+      },
       link: {
         label: "Links",
         description: "Colors for links and their hover state",
@@ -455,7 +477,7 @@ export const THEME_SCHEMA: Record<string, ThemeFieldSchema> = {
           (["info", "success", "warning", "error"] as const).map((kind) => [
             kind,
             {
-              label: kind[0].toUpperCase() + kind.slice(1),
+              label: kind.charAt(0).toUpperCase() + kind.slice(1),
               description: `${kind} message colors`,
               type: "color",
               required: true,
diff --git a/frontend/src/theme/viewerStyles.ts b/frontend/src/theme/viewerStyles.ts
index c8bca58d5..4ec251586 100644
--- a/frontend/src/theme/viewerStyles.ts
+++ b/frontend/src/theme/viewerStyles.ts
@@ -126,6 +126,71 @@ export const VIEWER_SCROLL_END_PADDING = {
   xs: "clamp(64px, 18dvh, 192px)",
   sm: "clamp(64px, 18dvh, 192px)",
 } as const;
+export const MARKDOWN_VIEWER_PRINT_STYLES = {
+  "@media print": {
+    "body:has([data-markdown-print-viewer])": { height: "auto !important", overflow: "visible !important" },
+    "body:has([data-markdown-print-viewer]) > :not([data-markdown-print-viewer])": { display: "none !important" },
+    "[data-markdown-print-viewer]": { position: "static !important", overflow: "visible" },
+    "[data-markdown-print-viewer] .MuiBackdrop-root, [data-markdown-print-frame] > :not([data-testid='markdown-viewer-content'])": {
+      display: "none !important",
+    },
+    "[data-markdown-print-viewer] .MuiDialog-paper, [data-markdown-print-viewer] [data-markdown-search-root]": {
+      color: "#000 !important",
+      backgroundColor: "#fff !important",
+    },
+    "[data-markdown-print-viewer] [data-markdown-search-root]": {
+      "--sambee-syntax-foreground": "#000 !important",
+      "--sambee-syntax-keyword": "#000 !important",
+      "--sambee-syntax-string": "#000 !important",
+      "--sambee-syntax-number": "#000 !important",
+      "--sambee-syntax-comment": "#000 !important",
+      "--sambee-syntax-type": "#000 !important",
+      "--sambee-syntax-function": "#000 !important",
+      "--sambee-syntax-operator": "#000 !important",
+      "--sambee-syntax-punctuation": "#000 !important",
+      "--sambee-search-foreground": "#000 !important",
+      "--sambee-search-other": "transparent !important",
+      "--sambee-search-current": "transparent !important",
+    },
+    "[data-markdown-print-viewer] [data-markdown-search-root] *": {
+      color: "#000 !important",
+      backgroundColor: "transparent !important",
+      boxShadow: "none !important",
+      textShadow: "none !important",
+    },
+    "[data-markdown-print-viewer] .MuiDialog-container, [data-markdown-print-viewer] .MuiDialog-paper, [data-markdown-print-frame], [data-markdown-print-viewer] [data-testid='markdown-viewer-content']":
+      {
+        position: "static",
+        display: "block",
+        width: "auto",
+        maxWidth: "none",
+        height: "auto",
+        maxHeight: "none",
+        minHeight: 0,
+        overflow: "visible",
+        flex: "none",
+        margin: 0,
+        paddingBottom: 0,
+      },
+    "[data-markdown-print-viewer] [data-markdown-search-root] pre, [data-markdown-print-viewer] [data-markdown-search-root] pre code": {
+      minWidth: 0,
+      whiteSpace: "pre-wrap",
+      overflowWrap: "anywhere",
+      overflow: "visible",
+    },
+    "[data-markdown-print-viewer] [data-markdown-search-root] table": {
+      display: "table",
+      width: "100%",
+      tableLayout: "fixed",
+      overflowWrap: "anywhere",
+    },
+    "[data-markdown-print-viewer] thead": { display: "table-header-group" },
+    "[data-markdown-print-viewer] tr, [data-markdown-print-viewer] img": { breakInside: "avoid" },
+    "[data-markdown-print-viewer] h1, [data-markdown-print-viewer] h2, [data-markdown-print-viewer] h3": { breakAfter: "avoid" },
+    "[data-markdown-print-viewer] p": { orphans: 3, widows: 3 },
+    "[data-markdown-print-viewer] img": { maxWidth: "100%", maxHeight: "240mm", objectFit: "contain" },
+  },
+} as const;
 export const MARKDOWN_TABLE_CELL_PADDING_INLINE = "0.675rem";
 export const MARKDOWN_TABLE_CELL_PADDING_BLOCK = "0.8em";
 export const MARKDOWN_TABLE_FONT_SIZE = "0.9375em";
diff --git a/frontend/src/types/index.ts b/frontend/src/types/index.ts
index 34e94d08b..5836a0e8c 100644
--- a/frontend/src/types/index.ts
+++ b/frontend/src/types/index.ts
@@ -762,10 +762,15 @@ export interface OidcMappingValidationDetail {
 }
 
 // API Error type for axios errors
+export interface ImagePreviewTooLargeError {
+  code: "image_preview_too_large";
+  message: string;
+}
+
 export interface ApiError {
   response?: {
     data?: {
-      detail?: string | ConflictInfo | OidcMappingValidationDetail | RecentFileValidationError;
+      detail?: string | ConflictInfo | OidcMappingValidationDetail | RecentFileValidationError | ImagePreviewTooLargeError;
       code?: string;
     };
     status?: number;
diff --git a/frontend/src/utils/FileTypeRegistry.ts b/frontend/src/utils/FileTypeRegistry.ts
index d788d9e3b..9f52da58d 100644
--- a/frontend/src/utils/FileTypeRegistry.ts
+++ b/frontend/src/utils/FileTypeRegistry.ts
@@ -42,7 +42,7 @@ export type ViewerId = "image" | "markdown" | "pdf" | "text";
 
 export interface ViewerDefinition {
   id: ViewerId;
-  translationKey: string;
+  translationKey: import("i18next").ParseKeys;
   description: string;
 }
 
diff --git a/frontend/src/utils/__tests__/domTextSearch.test.ts b/frontend/src/utils/__tests__/domTextSearch.test.ts
index 0cf8d0d6d..ff6b3a6b7 100644
--- a/frontend/src/utils/__tests__/domTextSearch.test.ts
+++ b/frontend/src/utils/__tests__/domTextSearch.test.ts
@@ -1,14 +1,80 @@
-import { describe, expect, it } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { requireTestValue } from "../../test/helpers/assertions";
 import {
   activateDomTextSearchMatch,
   applyDomTextSearchHighlights,
+  buildHighlightSlices,
   clearDomTextSearchHighlights,
+  createDomTextIndex,
   DOM_TEXT_SEARCH_CURRENT_MATCH_ATTRIBUTE,
   DOM_TEXT_SEARCH_HIGHLIGHT_SELECTOR,
   DOM_TEXT_SEARCH_MATCH_ID_ATTRIBUTE,
 } from "../domTextSearch";
+import { createViewportDomTextSearch, MAX_VIEWPORT_SEARCH_RANGES } from "../viewportDomTextSearch";
 
 describe("domTextSearch", () => {
+  it("assembles many blocks without inspecting a growing concatenated string", () => {
+    const container = document.createElement("div");
+    const text = "let x=1;\n".repeat(101);
+    container.innerHTML = Array.from({ length: 600 }, () => `<pre><code>${text}</code></pre>`).join("");
+    const original = String.prototype.endsWith;
+    let growingStringChecks = 0;
+    const endsWith = vi.spyOn(String.prototype, "endsWith").mockImplementation(function (this: string, search, end) {
+      if (this.length > text.length) growingStringChecks += 1;
+      return original.call(this, search, end);
+    });
+    try {
+      const index = createDomTextIndex(container);
+      expect(index.fullText).toBe(text.repeat(600));
+      expect(index.segments).toHaveLength(600);
+      expect(index.segments.at(-1)?.end).toBe(index.fullText.length);
+      expect(growingStringChecks).toBe(0);
+    } finally {
+      endsWith.mockRestore();
+    }
+  });
+
+  it("reports separate search stages and retains only the latest entry per stage", () => {
+    const container = document.createElement("div");
+    container.innerHTML = "<p>Alpha beta alpha</p>";
+    const measure = vi.spyOn(performance, "measure");
+    const clear = vi.spyOn(performance, "clearMeasures");
+    try {
+      for (let iteration = 0; iteration < 2; iteration += 1) {
+        applyDomTextSearchHighlights(container, "alpha");
+        clearDomTextSearchHighlights(container);
+      }
+      const names = ["capture", "matching", "slices", "markers", "clear"].map((stage) => `sambee:preview-search:${stage}`);
+      expect(measure.mock.calls.map(([name]) => name)).toEqual([...names, ...names]);
+      expect(clear.mock.calls.map(([name]) => name)).toEqual([...names, ...names]);
+      for (const [, options] of measure.mock.calls) {
+        expect(options).toEqual({ start: expect.any(Number), end: expect.any(Number) });
+      }
+    } finally {
+      measure.mockRestore();
+      clear.mockRestore();
+    }
+  });
+
+  it("updates only the old and new match when navigating many results", () => {
+    const matches = Array.from({ length: 6_000 }, (_, id) => ({ id, elements: [document.createElement("mark")] }));
+    activateDomTextSearchMatch(matches, 1, false);
+    const set = vi.spyOn(Element.prototype, "setAttribute");
+    const remove = vi.spyOn(Element.prototype, "removeAttribute");
+    try {
+      activateDomTextSearchMatch(matches, matches.length, false);
+      expect(set).toHaveBeenCalledTimes(1);
+      expect(remove).toHaveBeenCalledTimes(1);
+      activateDomTextSearchMatch(matches, matches.length, false);
+      expect(set).toHaveBeenCalledTimes(1);
+      expect(remove).toHaveBeenCalledTimes(1);
+      activateDomTextSearchMatch(matches, 0, false);
+      expect(remove).toHaveBeenCalledTimes(2);
+    } finally {
+      set.mockRestore();
+      remove.mockRestore();
+    }
+  });
   it("highlights case-insensitive matches within text nodes", () => {
     const container = document.createElement("div");
     container.innerHTML = "<p>Alpha beta ALPHA</p>";
@@ -55,6 +121,48 @@ describe("domTextSearch", () => {
     expect(container.querySelectorAll(DOM_TEXT_SEARCH_HIGHLIGHT_SELECTOR)).toHaveLength(0);
   });
 
+  it.each(["const x", "x  =", "=\t1", "1;\nconst"])("preserves isolated code whitespace for %j", (query) => {
+    const container = document.createElement("div");
+    container.innerHTML = "<pre><code><span>const</span> <span>x</span>  <span>=</span>\t<span>1;</span>\n<span>const</span></code></pre>";
+    const original = container.textContent;
+    const matches = applyDomTextSearchHighlights(container, query);
+    expect(matches).toHaveLength(1);
+    expect(
+      requireTestValue(matches[0])
+        .elements.map((element) => element.textContent)
+        .join("")
+    ).toBe(query);
+    clearDomTextSearchHighlights(container);
+    expect(container.textContent).toBe(original);
+    expect(applyDomTextSearchHighlights(container, query)).toHaveLength(1);
+  });
+
+  it("does not index prose layout indentation", () => {
+    const container = document.createElement("div");
+    container.innerHTML = "<p><span>sam</span>\n  <strong>bee</strong></p>";
+    expect(applyDomTextSearchHighlights(container, "sambee")).toHaveLength(1);
+  });
+
+  it("walks ordered segments proportionally to matches and emitted slices", () => {
+    let inspections = 0;
+    const repetitions = 6000;
+    const segments = Array.from({ length: repetitions * 2 }, (_, index) => ({
+      node: document.createTextNode(index % 2 === 0 ? "let" : " "),
+      get start() {
+        inspections += 1;
+        return Math.floor(index / 2) * 4 + (index % 2 === 0 ? 0 : 3);
+      },
+      get end() {
+        inspections += 1;
+        return Math.floor(index / 2) * 4 + (index % 2 === 0 ? 3 : 4);
+      },
+    }));
+    const matches = Array.from({ length: repetitions }, (_, index) => ({ id: index, start: index * 4, end: index * 4 + 3 }));
+    const slices = buildHighlightSlices({ fullText: "let ".repeat(repetitions), segments }, matches);
+    expect(slices.size).toBe(repetitions);
+    expect(inspections).toBeLessThan((segments.length + matches.length) * 8);
+  });
+
   it("clears highlights and restores the original text content", () => {
     const container = document.createElement("div");
     container.innerHTML = "<p>Alpha <strong>beta</strong> alpha</p>";
@@ -65,4 +173,315 @@ describe("domTextSearch", () => {
     expect(container.querySelectorAll(DOM_TEXT_SEARCH_HIGHLIGHT_SELECTOR)).toHaveLength(0);
     expect(container.textContent).toBe("Alpha beta alpha");
   });
+
+  it("coalesces dense marker text without normalizing live ranges or replacing inline elements", () => {
+    const container = document.createElement("div");
+    container.innerHTML = `<p>${"alpha ".repeat(6_000)}<strong>beta</strong> alpha</p>`;
+    const strong = container.querySelector("strong");
+    const original = container.textContent;
+    applyDomTextSearchHighlights(container, "alpha");
+    const normalize = vi.spyOn(Node.prototype, "normalize");
+    try {
+      clearDomTextSearchHighlights(container);
+      expect(normalize).not.toHaveBeenCalled();
+      expect(container.textContent).toBe(original);
+      expect(container.querySelector("strong")).toBe(strong);
+      expect(container.firstChild?.childNodes).toHaveLength(3);
+      expect(container.querySelectorAll(DOM_TEXT_SEARCH_HIGHLIGHT_SELECTOR)).toHaveLength(0);
+    } finally {
+      normalize.mockRestore();
+    }
+  });
+});
+
+describe("viewport DOM search", () => {
+  let frames: Map<number, FrameRequestCallback>;
+  let highlights: Map<string, Set<Range>>;
+  let session: ReturnType<typeof createViewportDomTextSearch> | undefined;
+  let root: HTMLDivElement;
+  let viewport: HTMLDivElement;
+  let nextFrame: number;
+  let notifyIntersections: IntersectionObserverCallback;
+  let disconnectIntersections: ReturnType<typeof vi.fn>;
+
+  function flushFrames() {
+    for (let iteration = 0; frames.size && iteration < 100; iteration += 1) {
+      const pending = [...frames.values()];
+      frames.clear();
+      for (const callback of pending) callback(0);
+    }
+    expect(frames.size).toBe(0);
+  }
+
+  beforeEach(() => {
+    frames = new Map();
+    highlights = new Map();
+    nextFrame = 0;
+    disconnectIntersections = vi.fn();
+    vi.stubGlobal(
+      "IntersectionObserver",
+      class {
+        constructor(callback: IntersectionObserverCallback) {
+          notifyIntersections = callback;
+        }
+        observe(target: Element) {
+          notifyIntersections([{ target, isIntersecting: true } as IntersectionObserverEntry], {} as IntersectionObserver);
+        }
+        disconnect = disconnectIntersections;
+      }
+    );
+    vi.stubGlobal("requestAnimationFrame", (callback: FrameRequestCallback) => {
+      frames.set(++nextFrame, callback);
+      return nextFrame;
+    });
+    vi.stubGlobal("cancelAnimationFrame", (id: number) => frames.delete(id));
+    vi.stubGlobal(
+      "Highlight",
+      class extends Set<Range> {
+        constructor(...ranges: Range[]) {
+          super(ranges);
+        }
+      }
+    );
+    vi.stubGlobal("CSS", { highlights });
+    viewport = document.createElement("div");
+    root = document.createElement("div");
+    viewport.append(root);
+    document.body.append(viewport);
+    vi.spyOn(viewport, "getBoundingClientRect").mockReturnValue({ top: 0, bottom: 120 } as DOMRect);
+    vi.spyOn(Element.prototype, "getBoundingClientRect").mockReturnValue({ top: 0, bottom: 120 } as DOMRect);
+    vi.spyOn(Range.prototype, "getBoundingClientRect").mockImplementation(function (this: Range) {
+      return { top: this.startOffset, bottom: this.endOffset } as DOMRect;
+    });
+  });
+
+  afterEach(() => {
+    session?.dispose();
+    session = undefined;
+    viewport.remove();
+    vi.restoreAllMocks();
+    vi.unstubAllGlobals();
+  });
+
+  it("reuses capture across queries and preserves text nodes and native selection", () => {
+    root.innerHTML = "<p>sam<strong>bee</strong> sambee</p><pre><code>const x  =\t1;\nconst</code></pre>";
+    const node = root.querySelector("p")!.firstChild!;
+    const range = document.createRange();
+    range.selectNodeContents(root);
+    const selection = document.getSelection()!;
+    selection.removeAllRanges();
+    selection.addRange(range);
+    const original = selection.toString();
+    const measure = vi.spyOn(performance, "measure");
+    const geometry = vi.mocked(Range.prototype.getBoundingClientRect);
+    geometry.mockClear();
+    session = createViewportDomTextSearch(root, viewport, vi.fn());
+    expect(session.setQuery("sambee")).toBe(2);
+    session.activate(1, false);
+    flushFrames();
+    expect(geometry).not.toHaveBeenCalled();
+    expect([...highlights.values()].flatMap((set) => [...set]).some((highlight) => highlight.toString() === "sambee")).toBe(true);
+    expect(session.setQuery("x  =\t1;\nconst")).toBe(1);
+    session.activate(1, false);
+    flushFrames();
+    expect(measure.mock.calls.filter(([name]) => name === "sambee:preview-search:capture")).toHaveLength(1);
+    expect(root.querySelector("p")!.firstChild).toBe(node);
+    expect(root.querySelectorAll("mark")).toHaveLength(0);
+    expect(selection.toString()).toBe(original);
+    selection.removeAllRanges();
+  });
+
+  it.each([
+    { top: 0, bottom: 120 },
+    { top: 480, bottom: 600 },
+    { top: 120, bottom: 180 },
+  ])("retains vertical range lookup when the text box is clipped at $top/$bottom", (bounds) => {
+    root.innerHTML = `<p>${"alpha ".repeat(100)}</p>`;
+    Object.defineProperty(viewport, "getBoundingClientRect", { configurable: true, value: vi.fn(() => bounds) });
+    Object.defineProperty(root.firstElementChild, "getBoundingClientRect", {
+      configurable: true,
+      value: vi.fn(() => ({ top: 0, bottom: 600 })),
+    });
+    const geometry = vi.mocked(Range.prototype.getBoundingClientRect);
+    geometry.mockClear();
+    session = createViewportDomTextSearch(root, viewport, vi.fn());
+    expect(session.setQuery("alpha")).toBe(100);
+    flushFrames();
+    expect(geometry).toHaveBeenCalled();
+    const ranges = [...highlights.values()].flatMap((collection) => [...collection]);
+    expect(ranges).toHaveLength((bounds.bottom - bounds.top) / "alpha ".length);
+    expect(ranges.every((range) => range.startOffset >= bounds.top && range.endOffset <= bounds.bottom)).toBe(true);
+    expect(ranges.every((range) => range.toString() === "alpha")).toBe(true);
+  });
+
+  it("reduces horizontal probes while preserving exact search ranges after nested scrolling", () => {
+    const source = "alpha ".repeat(6_000);
+    root.innerHTML = `<pre style="white-space: pre"><code>${source}</code></pre>`;
+    const pre = root.querySelector("pre")!;
+    const code = root.querySelector("code")!;
+    const node = code.firstChild;
+    const bounds = { top: 0, bottom: 120, left: 0, right: 120 };
+    Object.defineProperties(pre, { scrollWidth: { value: source.length }, clientWidth: { value: bounds.right } });
+    for (const element of [viewport, pre, code])
+      Object.defineProperty(element, "getBoundingClientRect", {
+        configurable: true,
+        value: vi.fn(() => bounds),
+      });
+    const geometry = vi.mocked(Range.prototype.getBoundingClientRect);
+    geometry.mockImplementation(function (this: Range) {
+      return { ...bounds, left: this.startOffset - pre.scrollLeft, right: this.endOffset - pre.scrollLeft } as DOMRect;
+    });
+    geometry.mockClear();
+    session = createViewportDomTextSearch(root, viewport, vi.fn());
+    expect(session.setQuery("alpha")).toBe(6_000);
+    flushFrames();
+    expect(geometry.mock.calls.length).toBeLessThan(20);
+    const visible = () => [...highlights.values()].flatMap((collection) => [...collection]);
+    expect(visible()).toHaveLength(20);
+    expect(visible().every((range) => range.toString() === "alpha" && range.endOffset <= bounds.right)).toBe(true);
+    pre.scrollLeft = 30_000;
+    pre.dispatchEvent(new Event("scroll"));
+    flushFrames();
+    expect(visible()).toHaveLength(20);
+    expect(
+      visible().every(
+        (range) => range.toString() === "alpha" && range.startOffset >= pre.scrollLeft && range.endOffset <= pre.scrollLeft + bounds.right
+      )
+    ).toBe(true);
+    expect(code.firstChild).toBe(node);
+    expect(code.textContent).toBe(source);
+    Object.defineProperty(pre, "getBoundingClientRect", {
+      configurable: true,
+      value: vi.fn(() => ({ ...bounds, left: 200, right: 320 })),
+    });
+    geometry.mockClear();
+    viewport.dispatchEvent(new Event("scroll"));
+    flushFrames();
+    expect(visible()).toHaveLength(0);
+    expect(geometry).not.toHaveBeenCalled();
+  });
+
+  it("bounds visible ranges and does not capture or match during viewport updates or navigation", () => {
+    root.innerHTML = `<pre><code>${"alpha ".repeat(6_000)}</code></pre>`;
+    session = createViewportDomTextSearch(root, viewport, vi.fn());
+    expect(session.setQuery("alpha")).toBe(6_000);
+    flushFrames();
+    const measure = vi.spyOn(performance, "measure");
+    session.activate(6_000);
+    viewport.dispatchEvent(new Event("scroll"));
+    flushFrames();
+    expect(measure.mock.calls.some(([name]) => name.endsWith(":capture") || name.endsWith(":matching"))).toBe(false);
+    for (const stage of ["navigation-lookup", "navigation-publication", "navigation-geometry", "navigation-scroll"]) {
+      expect(measure.mock.calls.some(([name]) => name === `sambee:preview-search:${stage}`)).toBe(true);
+    }
+    expect([...highlights.values()].reduce((sum, set) => sum + set.size, 0)).toBeLessThanOrEqual(MAX_VIEWPORT_SEARCH_RANGES + 1);
+    expect(
+      [...highlights.entries()]
+        .find(([name]) => name.endsWith("-current"))?.[1]
+        .values()
+        .next()
+        .value?.toString()
+    ).toBe("alpha");
+    expect(viewport.scrollTop).toBeGreaterThan(0);
+    expect(root.querySelectorAll("mark")).toHaveLength(0);
+  });
+
+  it("paints late-document matches during continuous scrolling without traversing off-screen segments", () => {
+    root.innerHTML = "<p>alpha</p>".repeat(600);
+    const paragraphs = [...root.querySelectorAll("p")];
+    const destination = requireTestValue(paragraphs[599]);
+    const probes = paragraphs.map((paragraph, index) => {
+      const probe = vi.fn(() => (index === 599 ? { top: 0, bottom: 120 } : { top: -20, bottom: -10 }) as DOMRect);
+      Object.defineProperty(paragraph, "getBoundingClientRect", { configurable: true, value: probe });
+      return probe;
+    });
+    session = createViewportDomTextSearch(root, viewport, vi.fn());
+    expect(session.setQuery("alpha")).toBe(600);
+    const intersectionEntry = (target: Element, isIntersecting: boolean): IntersectionObserverEntry => ({
+      target,
+      isIntersecting,
+      boundingClientRect: new DOMRect(),
+      intersectionRect: new DOMRect(),
+      intersectionRatio: isIntersecting ? 1 : 0,
+      rootBounds: null,
+      time: 0,
+    });
+    notifyIntersections(
+      paragraphs.map((target) => intersectionEntry(target, target === destination)),
+      {} as IntersectionObserver
+    );
+    const measure = vi.spyOn(performance, "measure");
+    for (let iteration = 0; iteration < 60; iteration += 1) {
+      const previousFrame = [...frames.keys()][0];
+      viewport.dispatchEvent(new Event("scroll"));
+      if (previousFrame !== undefined) expect([...frames.keys()]).toEqual([previousFrame]);
+      if (iteration > 0) expect([...highlights.values()].some((collection) => collection.size === 1)).toBe(true);
+      const pending = [...frames.values()];
+      frames.clear();
+      for (const callback of pending) callback(0);
+      const ranges = [...highlights.values()].flatMap((collection) => [...collection]);
+      expect(ranges).toHaveLength(1);
+      expect(requireTestValue(ranges[0]).startContainer).toBe(destination.firstChild);
+      expect(requireTestValue(ranges[0]).toString()).toBe("alpha");
+    }
+    expect(probes.slice(0, -1).every((probe) => probe.mock.calls.length === 0)).toBe(true);
+    expect(measure.mock.calls.some(([name]) => name.endsWith(":capture") || name.endsWith(":matching"))).toBe(false);
+    notifyIntersections([intersectionEntry(destination, false)], {} as IntersectionObserver);
+    flushFrames();
+    expect([...highlights.values()].every((collection) => collection.size === 0)).toBe(true);
+    session.dispose();
+    expect(disconnectIntersections).toHaveBeenCalled();
+    expect(highlights.size).toBe(0);
+    expect(frames.size).toBe(0);
+  });
+
+  it("invalidates on text replacement but not theme changes and handles queued mutations before queries", async () => {
+    root.innerHTML = "<p>alpha</p>";
+    const invalidated = vi.fn();
+    session = createViewportDomTextSearch(root, viewport, invalidated);
+    expect(session.setQuery("alpha")).toBe(1);
+    root.style.color = "red";
+    await Promise.resolve();
+    expect(invalidated).not.toHaveBeenCalled();
+    root.querySelector("p")!.textContent = "beta beta";
+    expect(session.setQuery("beta")).toBe(2);
+    await Promise.resolve();
+    expect(invalidated).not.toHaveBeenCalled();
+    root.querySelector("p")!.firstChild!.textContent = "gamma";
+    await Promise.resolve();
+    expect(invalidated).toHaveBeenCalledTimes(1);
+    expect(session.setQuery("gamma")).toBe(1);
+  });
+
+  it("releases owned highlights, styles and scheduled frames on disposal", () => {
+    root.innerHTML = "<p>alpha</p>";
+    session = createViewportDomTextSearch(root, viewport, vi.fn());
+    session.setQuery("alpha");
+    session.activate(1, false);
+    flushFrames();
+    const style = [...document.head.querySelectorAll("style")].find((style) => style.textContent?.includes("markdown-search-"));
+    expect(style?.textContent?.match(/color: var\(--sambee-search-foreground\)/g)).toHaveLength(2);
+    expect([...highlights.entries()].find(([name]) => name.endsWith("-current"))?.[1]).toHaveProperty("priority", 1);
+    viewport.dispatchEvent(new Event("scroll"));
+    expect(frames.size).toBe(1);
+    session.dispose();
+    expect(frames.size).toBe(0);
+    expect(highlights.size).toBe(0);
+    expect([...document.head.querySelectorAll("style")].some((style) => style.textContent?.includes("markdown-search-"))).toBe(false);
+    expect(session.setQuery("alpha")).toBe(0);
+  });
+
+  it.each(["Highlight", "IntersectionObserver"])(
+    "keeps counts and navigation without marker mutation when %s is unavailable",
+    (capability) => {
+      vi.stubGlobal(capability, undefined);
+      root.innerHTML = "<p>alpha alpha</p>";
+      session = createViewportDomTextSearch(root, viewport, vi.fn());
+      expect(session.supported).toBe(false);
+      expect(session.setQuery("alpha")).toBe(2);
+      session.activate(2);
+      expect(root.innerHTML).toBe("<p>alpha alpha</p>");
+      expect(highlights.size).toBe(0);
+    }
+  );
 });
diff --git a/frontend/src/utils/__tests__/markdownCodePreviewModel.test.ts b/frontend/src/utils/__tests__/markdownCodePreviewModel.test.ts
new file mode 100644
index 000000000..acb866c81
--- /dev/null
+++ b/frontend/src/utils/__tests__/markdownCodePreviewModel.test.ts
@@ -0,0 +1,191 @@
+import { describe, expect, it } from "vitest";
+import {
+  CODE_PREVIEW_FRAGMENT_MAX_LINES,
+  CODE_PREVIEW_FRAGMENT_MAX_UNITS,
+  CODE_PREVIEW_SCAN_MAX_UNITS,
+  CODE_PREVIEW_STEP_MAX_OPERATIONS,
+  createCodePreviewModel,
+  createCodePreviewModelAsync,
+  findCodePreviewFragment,
+} from "../markdownCodePreviewModel";
+
+describe("P1 code preview fragmentation", () => {
+  it("cooperatively produces identical models for dense, Unicode, and oversized source", async () => {
+    for (const text of [
+      "",
+      "let x=1;\n".repeat(6_000),
+      `${" \t\u{1f30d}\r\n\n".repeat(100)}end`,
+      "x".repeat(CODE_PREVIEW_SCAN_MAX_UNITS * 3),
+    ]) {
+      let yields = 0;
+      const ranges = text.length ? [{ from: 0, to: text.length, categories: ["string"] as const }] : [];
+      const model = await createCodePreviewModelAsync(text, ranges, {
+        yieldTask: async () => {
+          yields += 1;
+        },
+      });
+      expect(model).toEqual(createCodePreviewModel(text, ranges));
+      if (text.length > CODE_PREVIEW_SCAN_MAX_UNITS) expect(yields).toBeGreaterThan(0);
+    }
+  });
+
+  it("stops a single oversized-line scan at its first cooperative boundary", async () => {
+    const controller = new AbortController();
+    let yields = 0;
+    await expect(
+      createCodePreviewModelAsync("x".repeat(CODE_PREVIEW_SCAN_MAX_UNITS * 10), [], {
+        signal: controller.signal,
+        yieldTask: async () => {
+          yields += 1;
+          controller.abort();
+        },
+      })
+    ).rejects.toMatchObject({ name: "AbortError" });
+    expect(yields).toBe(1);
+  });
+
+  it("keeps scan-window boundaries independent from line and token boundaries", async () => {
+    for (const units of [
+      CODE_PREVIEW_SCAN_MAX_UNITS - 1,
+      CODE_PREVIEW_SCAN_MAX_UNITS,
+      CODE_PREVIEW_SCAN_MAX_UNITS + 1,
+      CODE_PREVIEW_SCAN_MAX_UNITS * 2 + 1,
+    ]) {
+      const text = `${"x".repeat(units)}\n${"a\n".repeat(CODE_PREVIEW_FRAGMENT_MAX_LINES)}last`;
+      const ranges = [{ from: units - 1, to: units + 2, categories: ["string"] as const }];
+      const model = await createCodePreviewModelAsync(text, ranges, { yieldTask: async () => undefined });
+      const middleEnd = units + 1 + CODE_PREVIEW_FRAGMENT_MAX_LINES * "a\n".length;
+      expect(model.fragments).toEqual([
+        { from: 0, to: units + 1, firstRange: 0, rangeEnd: 1, oversizedLine: true },
+        { from: units + 1, to: middleEnd, firstRange: 0, rangeEnd: 1, oversizedLine: false },
+        { from: middleEnd, to: text.length, firstRange: 1, rangeEnd: 1, oversizedLine: false },
+      ]);
+    }
+  });
+
+  it("propagates scheduling failures without returning a partial model", async () => {
+    const failure = new Error("Index scheduling failed");
+    await expect(
+      createCodePreviewModelAsync("x".repeat(CODE_PREVIEW_SCAN_MAX_UNITS), [], {
+        yieldTask: async () => {
+          throw failure;
+        },
+      })
+    ).rejects.toBe(failure);
+  });
+
+  it("checks cancellation before reading ranges and during range validation", async () => {
+    const controller = new AbortController();
+    let reads = 0;
+    const ranges = new Proxy(
+      Array.from({ length: CODE_PREVIEW_STEP_MAX_OPERATIONS * 3 }, (_, index) => ({
+        from: index,
+        to: index + 1,
+        categories: ["keyword"] as const,
+      })),
+      {
+        get(target, property, receiver) {
+          if (typeof property === "string" && /^\d+$/.test(property)) reads += 1;
+          return Reflect.get(target, property, receiver);
+        },
+      }
+    );
+    await expect(
+      createCodePreviewModelAsync("x".repeat(ranges.length), ranges, {
+        signal: controller.signal,
+        yieldTask: async () => {
+          controller.abort();
+        },
+      })
+    ).rejects.toMatchObject({ name: "AbortError" });
+    expect(reads).toBe(CODE_PREVIEW_STEP_MAX_OPERATIONS);
+    reads = 0;
+    await expect(
+      createCodePreviewModelAsync("x", ranges, {
+        signal: controller.signal,
+        yieldTask: async () => undefined,
+      })
+    ).rejects.toMatchObject({ name: "AbortError" });
+    expect(reads).toBe(0);
+  });
+
+  it("retains all 54,000 code units without a cumulative cutoff", () => {
+    const text = "let x=1;\n".repeat(6_000);
+    const model = createCodePreviewModel(text, []);
+    expect(text.length).toBe(54_000);
+    expect(model.fragments.map(({ from, to }) => text.slice(from, to)).join("")).toBe(text);
+    expect(model.fragments).toHaveLength(Math.ceil(6_000 / CODE_PREVIEW_FRAGMENT_MAX_LINES));
+    for (const fragment of model.fragments) {
+      expect(fragment.to - fragment.from).toBeLessThanOrEqual(CODE_PREVIEW_FRAGMENT_MAX_UNITS);
+      expect(fragment.oversizedLine).toBe(false);
+    }
+    const many = createCodePreviewModel(text.repeat(10), []);
+    expect(many.fragments.at(-1)?.to).toBe(540_000);
+  });
+
+  it("preserves tabs, CRLF, Unicode, blank lines, and an unterminated final line", () => {
+    const text = `${" \t\u{1f30d}\r\n\n".repeat(100)}end`;
+    const model = createCodePreviewModel(text, []);
+    expect(model.fragments.map(({ from, to }) => text.slice(from, to)).join("")).toBe(text);
+    for (const { from, to } of model.fragments) {
+      expect(findCodePreviewFragment(model, from)).toBe(model.fragments.findIndex((fragment) => fragment.from === from));
+      expect(findCodePreviewFragment(model, to - 1)).not.toBeNull();
+    }
+    for (const invalid of [-1, text.length, Number.NaN, 1.5]) expect(findCodePreviewFragment(model, invalid)).toBeNull();
+    expect(createCodePreviewModel("", []).fragments).toEqual([]);
+  });
+
+  it("associates crossing tokens and neutral gaps with only their overlapping fragments", () => {
+    const text = "a\n".repeat(CODE_PREVIEW_FRAGMENT_MAX_LINES * 3);
+    const boundary = CODE_PREVIEW_FRAGMENT_MAX_LINES * 2;
+    const ranges = [
+      { from: 0, to: 1, categories: ["keyword"] as const },
+      { from: boundary - 1, to: boundary + 1, categories: ["string"] as const },
+      { from: boundary * 2 + 1, to: boundary * 2 + 2, categories: ["comment"] as const },
+    ];
+    const model = createCodePreviewModel(text, ranges);
+    expect(model.fragments.map(({ firstRange, rangeEnd }) => [firstRange, rangeEnd])).toEqual([
+      [0, 2],
+      [1, 2],
+      [2, 3],
+    ]);
+    expect(ranges).toEqual(model.ranges);
+  });
+
+  it("indexes ranges in a single ordered pass rather than rescanning per fragment", () => {
+    const text = "x\n".repeat(10_000);
+    const ranges = Array.from({ length: 10_000 }, (_, index) => ({ from: index * 2, to: index * 2 + 1, categories: ["keyword"] as const }));
+    let reads = 0;
+    const observed = new Proxy(ranges, {
+      get(target, property, receiver) {
+        if (typeof property === "string" && /^\d+$/.test(property)) reads += 1;
+        return Reflect.get(target, property, receiver);
+      },
+    });
+    const model = createCodePreviewModel(text, observed);
+    expect(model.fragments.length).toBeGreaterThan(100);
+    expect(reads).toBeLessThan(ranges.length * 8);
+  });
+
+  it("flags oversized lines instead of claiming to bound their DOM work or changing their wrapping", () => {
+    const longLine = "\u{1f30d}".repeat(CODE_PREVIEW_FRAGMENT_MAX_UNITS);
+    const text = `first\n${longLine}\nlast`;
+    const model = createCodePreviewModel(text, []);
+    expect(model.fragments.map(({ oversizedLine }) => oversizedLine)).toEqual([false, true, false]);
+    expect(model.fragments.map(({ from, to }) => text.slice(from, to)).join("")).toBe(text);
+  });
+
+  it("rejects invalid token data before publication", () => {
+    for (const ranges of [
+      [{ from: -1, to: 1, categories: ["keyword"] as const }],
+      [{ from: 0, to: 4, categories: ["keyword"] as const }],
+      [{ from: 1, to: 1, categories: ["keyword"] as const }],
+      [{ from: 0, to: 1.5, categories: ["keyword"] as const }],
+      [
+        { from: 0, to: 2, categories: ["keyword"] as const },
+        { from: 1, to: 3, categories: ["string"] as const },
+      ],
+    ])
+      expect(() => createCodePreviewModel("abc", ranges)).toThrow(RangeError);
+  });
+});
diff --git a/frontend/src/utils/__tests__/markdownSyntax.test.tsx b/frontend/src/utils/__tests__/markdownSyntax.test.tsx
new file mode 100644
index 000000000..ebc255a84
--- /dev/null
+++ b/frontend/src/utils/__tests__/markdownSyntax.test.tsx
@@ -0,0 +1,1271 @@
+import { readFileSync } from "node:fs";
+import { render } from "@testing-library/react";
+import ReactMarkdown from "react-markdown";
+import remarkGfm from "remark-gfm";
+import remarkParse from "remark-parse";
+import { unified } from "unified";
+import { describe, expect, it, vi } from "vitest";
+import {
+  normalizeMarkdownTableCellLineBreaks,
+  remarkRenderMarkdownTableCellLineBreaks,
+} from "../../components/Viewer/markdownTableCellLineBreaks";
+import { requireTestValue } from "../../test/helpers/assertions";
+import {
+  createMarkdownEditNormalization,
+  PREPARATION_SOURCE_CHUNK_UNITS,
+  type PreparationRequest,
+  type PreparationResponse,
+  prepareCodePreviewInWorker,
+  WORKER_PROGRESS_TIMEOUT_MS,
+} from "../markdownCodePreparation";
+import {
+  createMarkdownDocumentModel,
+  DOCUMENT_RECORD_BATCH_ITEMS,
+  DOCUMENT_TEXT_CHUNK_UNITS,
+  documentSyntaxPage,
+  markdownDocumentRecords,
+} from "../markdownDocumentPreviewModel";
+import { createDocumentSearchIndex, documentSearchMatches } from "../markdownDocumentSearch";
+import { rehypeMarkdownHeadingLinks } from "../markdownHeadingLinks";
+import {
+  createMarkdownTreeReceiver,
+  MARKDOWN_TREE_BATCH_UNITS,
+  MARKDOWN_TREE_TEXT_UNITS,
+  markdownTreeRecords,
+  remarkPreparedMarkdownTree,
+} from "../markdownPreparedTree";
+import {
+  collectMarkdownCodeBlocks,
+  rehypeMeasureMarkdownPreparation,
+  rehypePreparedSyntax,
+  remarkCollectMarkdownCodeBlocks,
+  remarkMeasureMarkdownPreparation,
+} from "../markdownSyntax";
+import { MAX_VIEWPORT_SYNTAX_RANGES, publishMarkdownSyntax, visibleSyntaxColumnWindows } from "../markdownSyntaxPublication";
+import { prepareMarkdownSyntax } from "../markdownSyntaxWorker";
+import {
+  SYNTAX_RESULT_PAGE_RANGES,
+  SYNTAX_SOURCE_CHUNK_UNITS,
+  SYNTAX_WORKER_PROGRESS_TIMEOUT_MS,
+  type SyntaxWorkerRequest,
+  type SyntaxWorkerResponse,
+} from "../markdownSyntaxWorkerProtocol";
+import { TOKEN_COLOR_ROLES } from "../syntaxHighlighting";
+
+class PreparationWorker extends EventTarget {
+  static instances: PreparationWorker[] = [];
+  onmessage: ((event: MessageEvent<PreparationResponse>) => void) | null = null;
+  postMessage = vi.fn<(message: PreparationRequest) => void>();
+  terminate = vi.fn();
+  constructor() {
+    super();
+    PreparationWorker.instances.push(this);
+  }
+  receive(response: PreparationResponse) {
+    this.onmessage?.(new MessageEvent("message", { data: response }));
+  }
+}
+
+class SyntaxWorker extends EventTarget {
+  static instances: SyntaxWorker[] = [];
+  postMessage = vi.fn<(message: SyntaxWorkerRequest) => void>();
+  terminate = vi.fn();
+  constructor() {
+    super();
+    SyntaxWorker.instances.push(this);
+  }
+  receive(response: SyntaxWorkerResponse) {
+    this.dispatchEvent(new MessageEvent("message", { data: response }));
+  }
+}
+
+function mockSyntaxIntersections() {
+  let notify: IntersectionObserverCallback;
+  const disconnect = vi.fn();
+  vi.stubGlobal(
+    "IntersectionObserver",
+    class {
+      constructor(callback: IntersectionObserverCallback) {
+        notify = callback;
+      }
+      observe = vi.fn();
+      disconnect = disconnect;
+    }
+  );
+  return {
+    disconnect,
+    publish: (targets: Element[], isIntersecting = true) =>
+      notify(
+        targets.map((target) => ({ target, isIntersecting }) as IntersectionObserverEntry),
+        {} as IntersectionObserver
+      ),
+  };
+}
+
+describe("engine-neutral Markdown syntax adapter", () => {
+  it("creates safe, stable heading targets and resolves Unicode and duplicate fragments", () => {
+    const markdown =
+      "# Location\n\n## Café **déjà**\n\n## Repeat\n\n## Repeat\n\n[Unicode](#caf%C3%A9-d%C3%A9j%C3%A0) [Duplicate](#repeat-1) [Existing](#sambee-markdown-repeat)\n";
+    const first = render(<ReactMarkdown rehypePlugins={[rehypeMarkdownHeadingLinks]}>{markdown}</ReactMarkdown>);
+    const ids = [...first.container.querySelectorAll("h1,h2")].map((heading) => heading.id);
+    expect(ids).toEqual(["sambee-markdown-location", "sambee-markdown-café-déjà", "sambee-markdown-repeat", "sambee-markdown-repeat-1"]);
+    expect([...first.container.querySelectorAll("a")].map((link) => link.getAttribute("href"))).toEqual([
+      "#sambee-markdown-caf%C3%A9-d%C3%A9j%C3%A0",
+      "#sambee-markdown-repeat-1",
+      "#sambee-markdown-repeat",
+    ]);
+    first.unmount();
+    const second = render(<ReactMarkdown rehypePlugins={[rehypeMarkdownHeadingLinks]}>{markdown}</ReactMarkdown>);
+    expect([...second.container.querySelectorAll("h1,h2")].map((heading) => heading.id)).toEqual(ids);
+  });
+
+  it("leaves unknown, malformed and non-heading fragments and external links alone", () => {
+    const markdown =
+      "# Known\n\n[Missing](#absent) [Malformed](#%ZZ) [External](https://example.org/#known)\n\nFootnote[^note].\n\n[^note]: Note text.\n";
+    const { container } = render(
+      <ReactMarkdown remarkPlugins={[remarkGfm]} rehypePlugins={[rehypeMarkdownHeadingLinks]}>
+        {markdown}
+      </ReactMarkdown>
+    );
+    expect([...container.querySelectorAll("a")].slice(0, 3).map((link) => link.getAttribute("href"))).toEqual([
+      "#absent",
+      "#%ZZ",
+      "https://example.org/#known",
+    ]);
+    const reference = container.querySelector("a[data-footnote-ref]")!;
+    expect(reference.getAttribute("href")).toBe("#user-content-fn-note");
+    expect(container.querySelector('[id="user-content-fn-note"]')).not.toBeNull();
+  });
+
+  it("keeps production normalization independent of retired preview proofs", () => {
+    for (const filename of ["markdownCodePreparation.ts", "markdownCodePreparation.worker.ts", "markdownCodePreparationProtocol.ts"]) {
+      const source = readFileSync(`src/utils/${filename}`, "utf8");
+      expect(source).not.toMatch(/markdown(?:CodePreviewModel|DocumentPreviewModel|DocumentSearch)|createStaticHighlighter|MATCH_QUERY/);
+    }
+  });
+
+  it.each([
+    "# Heading\n\nPlain **strong** [safe](https://example.com).\n\n<script>unsafe()</script>\n",
+    "* item\n\n| A | B |\n| - | - |\n| a\\&b | first<BR>second |\n\n```md\n* literal<BR>\n```\n",
+    `[link][ref]\n\n[ref]: https://example.com "title"\n\n![alt](image.png)\n\n~~~js meta\n${"const rocket = '🚀';\n".repeat(200)}~~~\n`,
+  ])("reuses an equivalent canonical tree without changing ReactMarkdown output (%#)", (source) => {
+    let tree: ReturnType<ReturnType<typeof createMarkdownTreeReceiver>["finish"]> | undefined;
+    const canonical = normalizeMarkdownTableCellLineBreaks(source, (_text, parsed) => {
+      tree = parsed;
+    });
+    expect(tree).toEqual(unified().use(remarkParse).use(remarkGfm).parse(canonical));
+    const receiver = createMarkdownTreeReceiver();
+    for (const record of markdownTreeRecords(tree!)) receiver.consume([record]);
+    const restored = receiver.finish();
+    expect(restored).toEqual(tree);
+    const baseline = render(
+      <ReactMarkdown remarkPlugins={[remarkGfm, remarkRenderMarkdownTableCellLineBreaks]}>{canonical}</ReactMarkdown>
+    );
+    const html = baseline.container.innerHTML;
+    baseline.unmount();
+    const prepared = render(
+      <ReactMarkdown remarkPlugins={[remarkGfm, [remarkPreparedMarkdownTree, restored], remarkRenderMarkdownTableCellLineBreaks]}>
+        {canonical}
+      </ReactMarkdown>
+    );
+    expect(prepared.container.innerHTML).toBe(html);
+    prepared.unmount();
+    expect(restored).toEqual(tree);
+  });
+
+  it("rejects malformed and oversized tree records", () => {
+    const receiver = createMarkdownTreeReceiver();
+    expect(() => receiver.finish()).toThrow("Incomplete");
+    expect(() => receiver.consume([{ kind: "node", id: 1, parent: null, node: { type: "text" }, children: false }])).toThrow("Invalid");
+    receiver.consume([{ kind: "node", id: 0, parent: null, node: { type: "root" }, children: true }]);
+    expect(() => receiver.consume([{ kind: "text", id: 0, key: "__proto__", value: "bad" }])).toThrow("Invalid");
+    expect(() => receiver.consume([{ kind: "text", id: 0, key: "value", value: "x".repeat(MARKDOWN_TREE_TEXT_UNITS + 1) }])).toThrow(
+      "Invalid"
+    );
+    expect(() =>
+      receiver.consume(
+        Array.from({ length: MARKDOWN_TREE_BATCH_UNITS / MARKDOWN_TREE_TEXT_UNITS + 1 }, () => ({
+          kind: "text" as const,
+          id: 0,
+          key: "value",
+          value: "x".repeat(MARKDOWN_TREE_TEXT_UNITS),
+        }))
+      )
+    ).toThrow("text bound");
+  });
+
+  it("chunks wide-table alignment metadata without imposing a column cutoff", () => {
+    const source = `|${" header |".repeat(600)}\n|${" :---: |".repeat(600)}\n|${" value |".repeat(600)}\n`;
+    const tree = unified().use(remarkParse).use(remarkGfm).parse(source);
+    const receiver = createMarkdownTreeReceiver();
+    for (const record of markdownTreeRecords(tree)) receiver.consume([record]);
+    expect(receiver.finish()).toEqual(tree);
+  });
+
+  it.each([
+    { type: "root", value: "unbounded inline text" },
+    { type: "root", align: Array(600).fill(null) },
+    { type: "root", position: { start: { line: 1, column: 1, offset: "unbounded metadata" }, end: { line: 1, column: 1, offset: 0 } } },
+  ])("rejects text and arrays outside the bounded field channel (%#)", (node) => {
+    expect(() => createMarkdownTreeReceiver().consume([{ kind: "node", id: 0, parent: null, node, children: true }])).toThrow("tree node");
+  });
+
+  it("isolates normalization workers, bounds results and cleans up success, cancellation, decode errors and timeouts", async () => {
+    PreparationWorker.instances = [];
+    vi.stubGlobal("Worker", PreparationWorker);
+    const location = vi.spyOn(window.location, "toString").mockReturnValue("http://localhost:3000/");
+    try {
+      const controller = new AbortController();
+      const pending = prepareCodePreviewInWorker(["* item"], 1, controller.signal, vi.fn());
+      const worker = requireTestValue(PreparationWorker.instances[0]);
+      expect(requireTestValue(worker.postMessage.mock.calls[0])[0]).toEqual({ type: "prepare", generation: 1, prepareTree: undefined });
+      const cancelledController = new AbortController();
+      const cancelled = prepareCodePreviewInWorker(["new"], 2, cancelledController.signal, vi.fn());
+      const cancelledWorker = requireTestValue(PreparationWorker.instances[1]);
+      expect(cancelledWorker).not.toBe(worker);
+      worker.receive({ type: "source-ack", generation: 1, sequence: 0 });
+      worker.receive({ type: "source-ack", generation: 1, sequence: 1 });
+      expect(worker.postMessage).toHaveBeenLastCalledWith({ type: "run", generation: 1 });
+      worker.receive({ type: "normalized-source", generation: 1, sequence: 1, text: "- ", final: false });
+      worker.receive({ type: "normalized-source", generation: 1, sequence: 2, text: "item", final: true });
+      worker.receive({ type: "complete", generation: 1, preparationMs: 1 });
+      expect((await pending).normalizedSource).toBe("- item");
+      expect(worker.terminate).toHaveBeenCalledOnce();
+      expect(worker.onmessage).toBeNull();
+      const treeJob = prepareCodePreviewInWorker([""], 20, new AbortController().signal, vi.fn(), { prepareTree: true });
+      const treeWorker = PreparationWorker.instances.at(-1)!;
+      treeWorker.receive({ type: "source-ack", generation: 20, sequence: 0 });
+      treeWorker.receive({ type: "source-ack", generation: 20, sequence: 1 });
+      treeWorker.receive({ type: "normalized-source", generation: 20, sequence: 1, text: "", final: true });
+      treeWorker.receive({
+        type: "tree-chunk",
+        generation: 20,
+        sequence: 1,
+        records: [{ kind: "node", id: 0, parent: null, node: { type: "root" }, children: true }],
+        final: true,
+      });
+      expect(treeWorker.postMessage).toHaveBeenLastCalledWith({ type: "ack", generation: 20 });
+      treeWorker.postMessage.mockClear();
+      expect(treeWorker.postMessage).not.toHaveBeenCalled();
+      await vi.waitFor(() => expect(treeWorker.postMessage).toHaveBeenCalledExactlyOnceWith({ type: "ack", generation: 20 }));
+      treeWorker.receive({ type: "complete", generation: 20, preparationMs: 1 });
+      expect((await treeJob).preparedTree).toEqual({ type: "root", children: [] });
+      expect(treeWorker.terminate).toHaveBeenCalledOnce();
+      PreparationWorker.instances.pop();
+      for (const mode of ["missing-final", "stale-then-cancel", "bad-sequence"] as const) {
+        const treeController = new AbortController();
+        const incomplete = prepareCodePreviewInWorker([""], 21, treeController.signal, vi.fn(), { prepareTree: true });
+        const incompleteWorker = PreparationWorker.instances.at(-1)!;
+        incompleteWorker.receive({ type: "source-ack", generation: 21, sequence: 0 });
+        incompleteWorker.receive({ type: "source-ack", generation: 21, sequence: 1 });
+        incompleteWorker.receive({ type: "normalized-source", generation: 21, sequence: 1, text: "", final: true });
+        const page = {
+          type: "tree-chunk" as const,
+          generation: 21,
+          sequence: 1,
+          records: [{ kind: "node" as const, id: 0, parent: null, node: { type: "root" }, children: true }],
+          final: false,
+        };
+        if (mode === "missing-final") {
+          incompleteWorker.receive(page);
+          incompleteWorker.receive({ type: "complete", generation: 21, preparationMs: 0 });
+          await expect(incomplete).rejects.toThrow("final tree chunk");
+        } else if (mode === "bad-sequence") {
+          incompleteWorker.receive({ ...page, sequence: 2 });
+          await expect(incomplete).rejects.toThrow("tree sequence");
+        } else {
+          incompleteWorker.receive({ ...page, generation: 22 });
+          incompleteWorker.receive(page);
+          const sends = incompleteWorker.postMessage.mock.calls.length;
+          treeController.abort();
+          await expect(incomplete).rejects.toMatchObject({ name: "AbortError" });
+          expect(incompleteWorker.postMessage.mock.calls).toHaveLength(sends);
+        }
+        expect(incompleteWorker.terminate).toHaveBeenCalledOnce();
+        expect(incompleteWorker.onmessage).toBeNull();
+        PreparationWorker.instances.pop();
+      }
+      const late = cancelledWorker.onmessage;
+      cancelledController.abort();
+      await expect(cancelled).rejects.toMatchObject({ name: "AbortError" });
+      late?.(new MessageEvent("message", { data: { type: "complete", generation: 2, preparationMs: 0, indexingMs: 0 } }));
+      expect(cancelledWorker.terminate).toHaveBeenCalledOnce();
+      expect(cancelledWorker.onmessage).toBeNull();
+
+      const malformed = prepareCodePreviewInWorker(["bad"], 3, new AbortController().signal, vi.fn());
+      const malformedWorker = requireTestValue(PreparationWorker.instances[2]);
+      malformedWorker.receive({ type: "source-ack", generation: 3, sequence: 0 });
+      malformedWorker.receive({ type: "source-ack", generation: 3, sequence: 1 });
+      malformedWorker.receive({
+        type: "normalized-source",
+        generation: 3,
+        sequence: 1,
+        text: "x".repeat(PREPARATION_SOURCE_CHUNK_UNITS + 1),
+        final: true,
+      });
+      await expect(malformed).rejects.toThrow("Invalid normalized Markdown source chunk");
+      expect(malformedWorker.terminate).toHaveBeenCalledOnce();
+
+      const undecodable = prepareCodePreviewInWorker(["bad"], 4, new AbortController().signal, vi.fn());
+      const undecodableWorker = requireTestValue(PreparationWorker.instances[3]);
+      undecodableWorker.dispatchEvent(new Event("messageerror"));
+      await expect(undecodable).rejects.toThrow("could not be decoded");
+      expect(undecodableWorker.terminate).toHaveBeenCalledOnce();
+
+      vi.useFakeTimers();
+      const stalled = prepareCodePreviewInWorker(["bad"], 5, new AbortController().signal, vi.fn());
+      const stalledWorker = requireTestValue(PreparationWorker.instances[4]);
+      const rejection = expect(stalled).rejects.toThrow("made no progress");
+      await vi.advanceTimersByTimeAsync(WORKER_PROGRESS_TIMEOUT_MS);
+      await rejection;
+      expect(stalledWorker.terminate).toHaveBeenCalledOnce();
+      vi.useRealTimers();
+
+      const source = "x".repeat(PREPARATION_SOURCE_CHUNK_UNITS * 2 + 1);
+      const chunked = prepareCodePreviewInWorker([source], 6, new AbortController().signal, vi.fn());
+      const chunkedWorker = PreparationWorker.instances.at(-1)!;
+      for (let sequence = 0; sequence <= 3; sequence += 1) {
+        chunkedWorker.receive({ type: "source-ack", generation: 6, sequence });
+      }
+      const sent = chunkedWorker.postMessage.mock.calls.map(([message]) => message).filter((message) => message.type === "source");
+      expect(sent.map((message) => message.text).join("")).toBe(source);
+      expect(sent.map((message) => message.text.length)).toEqual([PREPARATION_SOURCE_CHUNK_UNITS, PREPARATION_SOURCE_CHUNK_UNITS, 1]);
+      expect(sent.map((message) => message.final)).toEqual([false, false, true]);
+      expect(chunkedWorker.postMessage).toHaveBeenLastCalledWith({ type: "run", generation: 6 });
+      for (const [index, message] of sent.entries()) {
+        chunkedWorker.receive({ type: "normalized-source", generation: 6, sequence: index + 1, text: message.text, final: message.final });
+      }
+      chunkedWorker.receive({ type: "complete", generation: 6, preparationMs: 1 });
+      await expect(chunked).resolves.toMatchObject({ normalizedSource: source });
+      expect(chunkedWorker.terminate).toHaveBeenCalledOnce();
+      await expect(prepareCodePreviewInWorker([], 7, new AbortController().signal, vi.fn())).rejects.toThrow("one source document");
+      await expect(prepareCodePreviewInWorker(["a", "b"], 7, new AbortController().signal, vi.fn())).rejects.toThrow("one source document");
+    } finally {
+      vi.useRealTimers();
+      location.mockRestore();
+      vi.unstubAllGlobals();
+    }
+  });
+
+  it.each(["", "baseline".repeat(PREPARATION_SOURCE_CHUNK_UNITS)])(
+    "transfers a source-preservation baseline in acknowledged bounded chunks (%#. case)",
+    async (baseline) => {
+      PreparationWorker.instances = [];
+      vi.stubGlobal("Worker", PreparationWorker);
+      const location = vi.spyOn(window.location, "toString").mockReturnValue("http://localhost:3000/");
+      const edits = createMarkdownEditNormalization(vi.fn());
+      const measure = vi.spyOn(performance, "measure");
+      try {
+        const source = "source\uD83D\uDE00";
+        const generation = edits.request(source, baseline);
+        const worker = requireTestValue(PreparationWorker.instances[0]);
+        expect(worker.postMessage).toHaveBeenCalledWith(expect.objectContaining({ preserveTableSource: true }));
+        const transferred = ["", ""];
+        let sequence = 0;
+        while (true) {
+          worker.receive({ type: "source-ack", generation, sequence });
+          const message = worker.postMessage.mock.calls.at(-1)![0];
+          if (message.type === "run") break;
+          if (message.type !== "source") throw new Error("Expected an acknowledged source chunk");
+          expect(message.text.length).toBeLessThanOrEqual(PREPARATION_SOURCE_CHUNK_UNITS);
+          transferred[message.block] += message.text;
+          expect(message.sequence).toBe(++sequence);
+        }
+        expect(transferred).toEqual([source, baseline]);
+        worker.receive({ type: "normalized-source", generation, sequence: 1, text: "prepared snapshot", final: true });
+        worker.receive({ type: "complete", generation, preparationMs: 1, normalizationMs: 0.25, preservationMs: 0.75 });
+        await expect(edits.flush()).resolves.toEqual({ generation, source, baseline, normalizedSource: "prepared snapshot" });
+        expect(worker.terminate).toHaveBeenCalledOnce();
+        const timings = measure.mock.calls.filter(([name]) => name.startsWith("sambee:edit-preparation:"));
+        for (const [, options] of timings) {
+          expect(options).toHaveProperty("start", expect.any(Number));
+          for (const value of Object.values((options as PerformanceMeasureOptions).detail)) {
+            expect(value === null || typeof value === "number" || typeof value === "boolean").toBe(true);
+          }
+        }
+        expect(measure).toHaveBeenCalledWith("sambee:edit-preparation:transport", {
+          start: expect.any(Number),
+          detail: {
+            generation,
+            sourceUnits: source.length,
+            baselineUnits: baseline.length,
+            preserveOnly: false,
+            sourceChunks: sequence,
+            resultChunks: 1,
+            workerPreparationMs: 1,
+            workerNormalizationMs: 0.25,
+            workerPreservationMs: 0.75,
+          },
+        });
+      } finally {
+        edits.dispose();
+        measure.mockRestore();
+        location.mockRestore();
+        vi.unstubAllGlobals();
+      }
+    }
+  );
+
+  it("rejects a result received before its complete baseline transfer", async () => {
+    PreparationWorker.instances = [];
+    vi.stubGlobal("Worker", PreparationWorker);
+    const location = vi.spyOn(window.location, "toString").mockReturnValue("http://localhost:3000/");
+    try {
+      const pending = prepareCodePreviewInWorker(["source"], 1, new AbortController().signal, vi.fn(), { preserveTableSource: "baseline" });
+      const worker = requireTestValue(PreparationWorker.instances[0]);
+      worker.receive({ type: "source-ack", generation: 1, sequence: 0 });
+      worker.receive({ type: "source-ack", generation: 1, sequence: 1 });
+      worker.receive({ type: "normalized-source", generation: 1, sequence: 1, text: "too early", final: true });
+      await expect(pending).rejects.toThrow("Invalid normalized Markdown source chunk");
+      expect(worker.terminate).toHaveBeenCalledOnce();
+      await expect(
+        prepareCodePreviewInWorker(["source"], 2, new AbortController().signal, vi.fn(), { preserveOnly: true })
+      ).rejects.toThrow("requires a baseline");
+      await expect(
+        prepareCodePreviewInWorker(["source"], 2, new AbortController().signal, vi.fn(), {
+          prepareTree: true,
+          preserveTableSource: "baseline",
+        })
+      ).rejects.toThrow("cannot also prepare a preview tree");
+    } finally {
+      location.mockRestore();
+      vi.unstubAllGlobals();
+    }
+  });
+
+  it("binds coalesced snapshot bytes to the latest baseline and normalization policy", async () => {
+    PreparationWorker.instances = [];
+    vi.stubGlobal("Worker", PreparationWorker);
+    const location = vi.spyOn(window.location, "toString").mockReturnValue("http://localhost:3000/");
+    const published = vi.fn();
+    const edits = createMarkdownEditNormalization(vi.fn(), published);
+    const complete = (worker: PreparationWorker, generation: number, text: string) => {
+      for (const sequence of [0, 1, 2]) worker.receive({ type: "source-ack", generation, sequence });
+      worker.receive({ type: "normalized-source", generation, sequence: 1, text, final: true });
+      worker.receive({ type: "complete", generation, preparationMs: 1 });
+    };
+    try {
+      const old = edits.request("same source", "old baseline", true);
+      const latest = edits.request("same source", "new baseline");
+      expect(PreparationWorker.instances).toHaveLength(1);
+      expect(requireTestValue(PreparationWorker.instances[0]).postMessage).toHaveBeenCalledWith(
+        expect.objectContaining({ preserveOnly: true })
+      );
+      const flushed = edits.flush();
+      complete(requireTestValue(PreparationWorker.instances[0]), old, "obsolete preserved bytes");
+      await vi.waitFor(() => expect(PreparationWorker.instances).toHaveLength(2));
+      expect(published).not.toHaveBeenCalled();
+      expect(() => edits.captureSnapshotSync()).toThrow(/not finished/);
+      complete(requireTestValue(PreparationWorker.instances[1]), latest, "current normalized bytes");
+      const snapshot = await flushed;
+      expect(snapshot).toEqual({
+        generation: latest,
+        source: "same source",
+        baseline: "new baseline",
+        normalizedSource: "current normalized bytes",
+      });
+      expect(Object.isFrozen(snapshot)).toBe(true);
+      expect(published).toHaveBeenCalledExactlyOnceWith(snapshot);
+    } finally {
+      edits.dispose();
+      location.mockRestore();
+      vi.unstubAllGlobals();
+    }
+  });
+
+  it.each(["success", "failure"])("bounds edit normalization and suppresses stale %s with immutable snapshots", async (outcome) => {
+    PreparationWorker.instances = [];
+    vi.stubGlobal("Worker", PreparationWorker);
+    const location = vi.spyOn(window.location, "toString").mockReturnValue("http://localhost:3000/");
+    const diagnostic = vi.fn();
+    const published = vi.fn();
+    const failed = vi.fn();
+    const edits = createMarkdownEditNormalization(diagnostic, published, failed);
+    const complete = (worker: PreparationWorker, generation: number, text: string) => {
+      worker.receive({ type: "source-ack", generation, sequence: 0 });
+      worker.receive({ type: "source-ack", generation, sequence: 1 });
+      worker.receive({ type: "normalized-source", generation, sequence: 1, text, final: true });
+      worker.receive({ type: "complete", generation, preparationMs: 1 });
+    };
+    try {
+      const first = edits.request("first<BR>edit");
+      const firstWorker = requireTestValue(PreparationWorker.instances[0]);
+      for (let index = 0; index < 100; index += 1) edits.request(`intermediate ${index}`);
+      const latest = edits.request("latest<BR>edit");
+      expect(PreparationWorker.instances).toHaveLength(1);
+      expect(() => edits.captureSnapshotSync()).toThrow(/not finished/);
+      const flushed = edits.flush();
+      firstWorker.receive({ type: "diagnostic", generation: first, message: "obsolete" });
+      if (outcome === "success") complete(firstWorker, first, "obsolete normalized text");
+      else firstWorker.receive({ type: "error", generation: first, message: "obsolete failure" });
+      await vi.waitFor(() => expect(PreparationWorker.instances).toHaveLength(2));
+      expect(diagnostic).not.toHaveBeenCalled();
+      expect(published).not.toHaveBeenCalled();
+      expect(failed).not.toHaveBeenCalled();
+      expect(() => edits.captureSnapshotSync()).toThrow(/not finished/);
+      expect(firstWorker.terminate).toHaveBeenCalledOnce();
+      const currentWorker = requireTestValue(PreparationWorker.instances[1]);
+      expect(currentWorker.postMessage).toHaveBeenCalledExactlyOnceWith({ type: "prepare", generation: latest, prepareTree: undefined });
+      complete(currentWorker, latest, "latest<br />edit");
+      const captured = await flushed;
+      expect(captured).toEqual({ generation: latest, source: "latest<BR>edit", normalizedSource: "latest<br />edit" });
+      expect(Object.isFrozen(captured)).toBe(true);
+      expect(published).toHaveBeenCalledExactlyOnceWith(captured);
+      expect(edits.captureSnapshotSync()).toBe(captured);
+      expect(currentWorker.terminate).toHaveBeenCalledOnce();
+      const next = edits.request("next");
+      expect(() => edits.captureSnapshotSync()).toThrow(/not finished/);
+      expect(captured.normalizedSource).toBe("latest<br />edit");
+      complete(requireTestValue(PreparationWorker.instances[2]), next, "next");
+      await expect(edits.flush()).resolves.toMatchObject({ generation: next, normalizedSource: "next" });
+      expect(captured.normalizedSource).toBe("latest<br />edit");
+    } finally {
+      edits.dispose();
+      location.mockRestore();
+      vi.unstubAllGlobals();
+    }
+  });
+
+  it("preserves edit normalization failures, allows explicit retry and aborts flush without cancelling current content", async () => {
+    PreparationWorker.instances = [];
+    vi.stubGlobal("Worker", PreparationWorker);
+    const location = vi.spyOn(window.location, "toString").mockReturnValue("http://localhost:3000/");
+    const edits = createMarkdownEditNormalization(vi.fn());
+    try {
+      const failed = edits.request("unchanged draft");
+      const failure = expect(edits.flush()).rejects.toThrow("worker failed");
+      requireTestValue(PreparationWorker.instances[0]).receive({ type: "error", generation: failed, message: "worker failed" });
+      await failure;
+      expect(() => edits.captureSnapshotSync()).toThrow("worker failed");
+      await expect(edits.flush()).rejects.toThrow("worker failed");
+      expect(PreparationWorker.instances).toHaveLength(1);
+      const retry = edits.request("unchanged draft");
+      const controller = new AbortController();
+      const cancelled = expect(edits.flush(controller.signal)).rejects.toMatchObject({ name: "AbortError" });
+      controller.abort();
+      await cancelled;
+      const worker = requireTestValue(PreparationWorker.instances[1]);
+      expect(worker.terminate).not.toHaveBeenCalled();
+      worker.receive({ type: "source-ack", generation: retry, sequence: 0 });
+      worker.receive({ type: "source-ack", generation: retry, sequence: 1 });
+      worker.receive({ type: "normalized-source", generation: retry, sequence: 1, text: "unchanged draft", final: true });
+      worker.receive({ type: "complete", generation: retry, preparationMs: 1 });
+      await expect(edits.flush()).resolves.toMatchObject({ normalizedSource: "unchanged draft" });
+      await expect(edits.flush(controller.signal)).rejects.toMatchObject({ name: "AbortError" });
+    } finally {
+      edits.dispose();
+      location.mockRestore();
+      vi.unstubAllGlobals();
+    }
+  });
+
+  it.each(["construction", "execution", "decode", "timeout", "no-worker"] as const)(
+    "rejects edit normalization %s failure without a synchronous fallback or automatic retry",
+    async (mode) => {
+      PreparationWorker.instances = [];
+      vi.stubGlobal("Worker", PreparationWorker);
+      if (mode === "construction") {
+        vi.stubGlobal(
+          "Worker",
+          class {
+            constructor() {
+              throw new Error("worker startup failed");
+            }
+          }
+        );
+      } else if (mode === "no-worker") vi.stubGlobal("Worker", undefined);
+      if (mode === "timeout") vi.useFakeTimers();
+      const location = vi.spyOn(window.location, "toString").mockReturnValue("http://localhost:3000/");
+      const edits = createMarkdownEditNormalization(vi.fn());
+      try {
+        const generation = edits.request("| A |\n| - |\n| first<BR>second |\n");
+        const expected = /startup failed|execution failed|could not be decoded|made no progress|unavailable/;
+        const rejected = expect(edits.flush()).rejects.toThrow(expected);
+        const worker = PreparationWorker.instances[0];
+        if (mode === "execution") requireTestValue(worker).receive({ type: "error", generation, message: "worker execution failed" });
+        else if (mode === "decode") requireTestValue(worker).dispatchEvent(new Event("messageerror"));
+        else if (mode === "timeout") await vi.advanceTimersByTimeAsync(WORKER_PROGRESS_TIMEOUT_MS);
+        await rejected;
+        expect(() => edits.captureSnapshotSync()).toThrow(expected);
+        await expect(edits.flush()).rejects.toThrow(expected);
+        expect(PreparationWorker.instances).toHaveLength(mode === "construction" || mode === "no-worker" ? 0 : 1);
+        if (worker) {
+          expect(worker.terminate).toHaveBeenCalledOnce();
+          expect(worker.onmessage).toBeNull();
+        }
+      } finally {
+        edits.dispose();
+        location.mockRestore();
+        vi.useRealTimers();
+        vi.unstubAllGlobals();
+      }
+    }
+  );
+
+  it("disposes active and queued edits without publishing late worker messages", async () => {
+    PreparationWorker.instances = [];
+    vi.stubGlobal("Worker", PreparationWorker);
+    const location = vi.spyOn(window.location, "toString").mockReturnValue("http://localhost:3000/");
+    const diagnostic = vi.fn();
+    const edits = createMarkdownEditNormalization(diagnostic);
+    try {
+      const generation = edits.request("active draft");
+      edits.request("queued draft");
+      const worker = requireTestValue(PreparationWorker.instances[0]);
+      const lateMessage = worker.onmessage;
+      const disposed = expect(edits.flush()).rejects.toMatchObject({ name: "AbortError" });
+      edits.dispose();
+      edits.dispose();
+      lateMessage?.(new MessageEvent("message", { data: { type: "diagnostic", generation, message: "late" } }));
+      await disposed;
+      expect(diagnostic).not.toHaveBeenCalled();
+      expect(PreparationWorker.instances).toHaveLength(1);
+      expect(worker.terminate).toHaveBeenCalledOnce();
+      expect(worker.onmessage).toBeNull();
+      expect(() => edits.request("after close")).toThrow(/disposed/);
+      expect(() => edits.captureSnapshotSync()).toThrow(/disposed/);
+      await expect(edits.flush()).rejects.toMatchObject({ name: "AbortError" });
+    } finally {
+      edits.dispose();
+      location.mockRestore();
+      vi.unstubAllGlobals();
+    }
+  });
+
+  it("normalizes document preparation with the existing canonical source rules only when requested", async () => {
+    const source = "* item\n\n| A | B |\n| - | - |\n| a\\&b | first<BR>second |\n\n```md\n* literal<BR>\n```\n";
+    const canonical = "- item\n\n| A | B |\n| - | - |\n| a&b | first<br />second |\n\n```md\n* literal<BR>\n```\n";
+    const original = await createMarkdownDocumentModel(source);
+    expect(original.source).toBe(source);
+    const normalized = await createMarkdownDocumentModel(source, { normalizeSource: true });
+    expect(normalized.source).toBe(canonical);
+    const baseline = await createMarkdownDocumentModel(canonical);
+    expect([...markdownDocumentRecords(normalized)]).toEqual([...markdownDocumentRecords(baseline)]);
+  });
+
+  it.each([
+    {
+      source: '> ```TS title\n> const rocket = "\ud83d\ude80";\n> ```\n\n~~~unknown metadata\nraw\n~~~\n\n```\nplain\n```\n',
+      expected: [
+        { text: 'const rocket = "\ud83d\ude80";', label: "TS" },
+        { text: "raw", label: "unknown" },
+        { text: "plain", label: null },
+      ],
+    },
+    { source: "1. item\n\n   ```python\n   print(1)\n   ```\n", expected: [{ text: "print(1)", label: "python" }] },
+    { source: "# Heading\n\n    alpha\n    beta\n", expected: [{ text: "alpha\nbeta", label: null }] },
+    { source: "Paragraph with `inline code`.\n", expected: [] },
+  ])("collects identical ordered code requests from the render tree: $source", ({ source, expected }) => {
+    const collected = vi.fn();
+    const preview = render(
+      <ReactMarkdown remarkPlugins={[remarkGfm, [remarkCollectMarkdownCodeBlocks, collected]]}>{source}</ReactMarkdown>
+    );
+    expect(collected).toHaveBeenCalledExactlyOnceWith(expected);
+    expect(collectMarkdownCodeBlocks(source)).toEqual(expected);
+    expect([...preview.container.querySelectorAll("pre code")].map((code) => code.textContent)).toEqual(
+      expected.map((request) => `${request.text}\n`)
+    );
+    preview.unmount();
+  });
+
+  it("measures render parsing and transforms without changing semantic output", () => {
+    const source = "# Title\n\nsam**bee** [safe](https://example.com)\n\n```js\nlet x=1;\n```\n";
+    const baseline = render(<ReactMarkdown>{source}</ReactMarkdown>);
+    const expected = baseline.container.innerHTML;
+    baseline.unmount();
+    const expectedRequests = collectMarkdownCodeBlocks(source);
+    const measure = vi.spyOn(performance, "measure");
+    const ready = vi.fn();
+    const collected = vi.fn();
+    try {
+      const measured = render(
+        <ReactMarkdown
+          remarkPlugins={[remarkMeasureMarkdownPreparation, [remarkCollectMarkdownCodeBlocks, collected]]}
+          rehypePlugins={[[rehypeMeasureMarkdownPreparation, ready]]}
+        >
+          {source}
+        </ReactMarkdown>
+      );
+      expect(measured.container.innerHTML).toBe(expected);
+      expect(ready).toHaveBeenCalledOnce();
+      expect(collected).toHaveBeenCalledExactlyOnceWith(expectedRequests);
+      expect(measure.mock.calls.some(([name]) => name === "sambee:preview-preparation:collection-parse")).toBe(false);
+      for (const stage of ["render-parse", "render-transform", "collection-walk"]) {
+        expect(measure.mock.calls.some(([name]) => name === `sambee:preview-preparation:${stage}`)).toBe(true);
+      }
+      measured.unmount();
+    } finally {
+      measure.mockRestore();
+    }
+  });
+
+  it("bounds worker transfer, acknowledges result pages asynchronously and cancels pending work", async () => {
+    SyntaxWorker.instances = [];
+    vi.stubGlobal("Worker", SyntaxWorker);
+    const locationString = vi.spyOn(window.location, "toString").mockReturnValue("http://localhost:3000/");
+    vi.useFakeTimers();
+    const controller = new AbortController();
+    try {
+      const text = "x".repeat(SYNTAX_SOURCE_CHUNK_UNITS * 2 + 1);
+      const pending = prepareMarkdownSyntax(
+        [{ text, label: "js" }, { text: "x".repeat(100_001) }, { text: "end", label: "py" }],
+        controller.signal
+      );
+      const worker = requireTestValue(SyntaxWorker.instances[0]);
+      expect(requireTestValue(worker.postMessage.mock.calls[0])[0]).toEqual({
+        type: "source",
+        block: 0,
+        text: text.slice(0, SYNTAX_SOURCE_CHUNK_UNITS),
+        label: "js",
+        final: false,
+      });
+      worker.receive({ type: "source-ack" });
+      worker.receive({ type: "source-ack" });
+      expect(requireTestValue(worker.postMessage.mock.calls[2])[0]).toMatchObject({ text: "x", final: true });
+      const ranges = Array.from({ length: SYNTAX_RESULT_PAGE_RANGES }, (_, index) => ({
+        from: index,
+        to: index + 1,
+        categories: ["keyword"] as const,
+      }));
+      worker.receive({ type: "ranges", block: 0, ranges });
+      expect(worker.postMessage).toHaveBeenCalledTimes(3);
+      await vi.advanceTimersByTimeAsync(0);
+      expect(requireTestValue(worker.postMessage.mock.calls[3])[0]).toEqual({ type: "ack" });
+      worker.receive({ type: "complete", block: 0 });
+      expect(requireTestValue(worker.postMessage.mock.calls[4])[0]).toEqual({
+        type: "source",
+        block: 1,
+        text: "end",
+        label: "py",
+        final: true,
+      });
+      worker.receive({ type: "complete", block: 1, reason: "unknown-language" });
+      await expect(pending).resolves.toEqual([{ ranges }, { reason: "block-too-large" }, { reason: "unknown-language" }]);
+      expect(worker.terminate).toHaveBeenCalledOnce();
+      const cancelled = prepareMarkdownSyntax([{ text: "new" }], controller.signal);
+      const rejection = expect(cancelled).rejects.toMatchObject({ name: "AbortError" });
+      controller.abort();
+      await rejection;
+      expect(requireTestValue(SyntaxWorker.instances[1]).terminate).toHaveBeenCalledOnce();
+      expect(vi.getTimerCount()).toBe(0);
+    } finally {
+      controller.abort();
+      locationString.mockRestore();
+      vi.useRealTimers();
+      vi.unstubAllGlobals();
+    }
+  });
+  it.each([
+    ["construction", "Construction failed"],
+    ["crash", "Syntax worker failed"],
+    ["decode", "could not be decoded"],
+    ["timeout", "made no progress"],
+    ["send", "Delivery failed"],
+    ["ack-send", "Delivery failed"],
+    ["worker-error", "Preparation failed"],
+    ["wrong-block", "Invalid syntax result page"],
+    ["oversized-page", "Invalid syntax result page"],
+    ["invalid-offset", "Invalid syntax result offsets"],
+    ["obsolete-completion", "Obsolete syntax block result"],
+  ])("cleans up syntax %s failures and permits a fresh request", async (fault, message) => {
+    SyntaxWorker.instances = [];
+    let failConstruction = fault === "construction";
+    vi.stubGlobal(
+      "Worker",
+      class extends SyntaxWorker {
+        constructor() {
+          if (failConstruction) throw new Error("Construction failed");
+          super();
+          if (fault === "send" && SyntaxWorker.instances.length === 1)
+            this.postMessage.mockImplementationOnce(() => {
+              throw new Error("Delivery failed");
+            });
+        }
+      }
+    );
+    vi.spyOn(window.location, "toString").mockReturnValue("http://localhost:3000/");
+    vi.useFakeTimers();
+    const controller = new AbortController();
+    const removeAbort = vi.spyOn(controller.signal, "removeEventListener");
+    try {
+      const pending = prepareMarkdownSyntax([{ text: "const x = 1", label: "js" }], controller.signal);
+      const rejection = expect(pending).rejects.toThrow(message);
+      const worker = SyntaxWorker.instances[0];
+      if (worker && fault !== "send") {
+        const removeListener = vi.spyOn(worker, "removeEventListener");
+        const range = { from: 0, to: 5, categories: ["keyword"] as const };
+        worker.receive({ type: "ranges", block: 0, ranges: [range] });
+        if (fault === "crash") {
+          const event = new ErrorEvent("error", { message: "Execution failed", cancelable: true });
+          worker.dispatchEvent(event);
+          expect(event.defaultPrevented).toBe(true);
+        } else if (fault === "decode") worker.dispatchEvent(new Event("messageerror"));
+        else if (fault === "timeout") await vi.advanceTimersByTimeAsync(SYNTAX_WORKER_PROGRESS_TIMEOUT_MS);
+        else if (fault === "ack-send") {
+          worker.postMessage.mockImplementationOnce(() => {
+            throw new Error("Delivery failed");
+          });
+          await vi.advanceTimersByTimeAsync(0);
+        } else if (fault === "worker-error") worker.receive({ type: "error", message: "Preparation failed" });
+        else if (fault === "wrong-block") worker.receive({ type: "ranges", block: 1, ranges: [] });
+        else if (fault === "oversized-page")
+          worker.receive({ type: "ranges", block: 0, ranges: Array(SYNTAX_RESULT_PAGE_RANGES + 1).fill(range) });
+        else if (fault === "invalid-offset") worker.receive({ type: "ranges", block: 0, ranges: [range] });
+        else if (fault === "obsolete-completion") worker.receive({ type: "complete", block: 1 });
+        await rejection;
+        for (const event of ["message", "error", "messageerror"]) expect(removeListener).toHaveBeenCalledWith(event, expect.any(Function));
+      } else await rejection;
+
+      if (worker) {
+        expect(worker.terminate).toHaveBeenCalledOnce();
+        expect(removeAbort).toHaveBeenCalledWith("abort", expect.any(Function));
+        const sent = worker.postMessage.mock.calls.length;
+        worker.receive({ type: "source-ack" });
+        worker.receive({ type: "complete", block: 0 });
+        controller.abort();
+        await vi.runAllTimersAsync();
+        expect(worker.postMessage).toHaveBeenCalledTimes(sent);
+        expect(worker.terminate).toHaveBeenCalledOnce();
+      }
+      expect(vi.getTimerCount()).toBe(0);
+
+      failConstruction = false;
+      const retried = prepareMarkdownSyntax([{ text: "retry", label: "js" }], new AbortController().signal);
+      const fresh = SyntaxWorker.instances.at(-1)!;
+      expect(fresh).not.toBe(worker);
+      fresh.receive({ type: "complete", block: 0 });
+      await expect(retried).resolves.toEqual([{ ranges: [] }]);
+      expect(fresh.terminate).toHaveBeenCalledOnce();
+      expect(vi.getTimerCount()).toBe(0);
+    } finally {
+      controller.abort();
+      vi.restoreAllMocks();
+      vi.unstubAllGlobals();
+      vi.useRealTimers();
+    }
+  });
+
+  it("bounds live syntax ranges without changing text or selection and cancels queued publication", () => {
+    const intersections = mockSyntaxIntersections();
+    const frames = new Map<number, FrameRequestCallback>();
+    let nextFrame = 0;
+    const highlights = new Map<string, Set<Range>>();
+    vi.stubGlobal("CSS", { highlights });
+    vi.stubGlobal(
+      "Highlight",
+      class extends Set<Range> {
+        constructor(...ranges: Range[]) {
+          super(ranges);
+        }
+      }
+    );
+    vi.stubGlobal("requestAnimationFrame", (callback: FrameRequestCallback) => {
+      frames.set(++nextFrame, callback);
+      return nextFrame;
+    });
+    vi.stubGlobal("cancelAnimationFrame", (id: number) => frames.delete(id));
+    const source = "x ".repeat(MAX_VIEWPORT_SYNTAX_RANGES + 1);
+    const { container, unmount } = render(<ReactMarkdown>{`\`\`\`js\n${source}\n\`\`\``}</ReactMarkdown>);
+    const code = container.querySelector("code")!;
+    const node = code.firstChild;
+    const rect = { top: 0, bottom: 10 } as DOMRect;
+    vi.spyOn(container, "getBoundingClientRect").mockReturnValue({ top: 0, bottom: 20 } as DOMRect);
+    vi.spyOn(code, "getBoundingClientRect").mockReturnValue(rect);
+    const geometry = vi.spyOn(Range.prototype, "getBoundingClientRect").mockReturnValue(rect);
+    const selection = document.getSelection()!;
+    const range = document.createRange();
+    range.selectNodeContents(code);
+    selection.removeAllRanges();
+    selection.addRange(range);
+    const selected = selection.toString();
+    const controller = new AbortController();
+    try {
+      const measurements = vi.spyOn(performance, "measure");
+      const dispose = publishMarkdownSyntax(
+        container,
+        container,
+        {
+          requests: [{ text: source, label: "js" }],
+          results: [
+            {
+              ranges: Array.from({ length: MAX_VIEWPORT_SYNTAX_RANGES + 1 }, (_, index) => ({
+                from: index * 2,
+                to: index * 2 + 1,
+                categories: ["keyword"],
+              })),
+            },
+          ],
+        },
+        controller.signal
+      );
+      const style = [...document.head.querySelectorAll("style")].find((element) =>
+        element.textContent?.includes("::highlight(markdown-syntax-")
+      );
+      expect(style).toBeDefined();
+      for (const [category, role] of Object.entries(TOKEN_COLOR_ROLES)) {
+        expect(style!.textContent).toMatch(new RegExp(`-${category}\\) \\{ color: var\\(--sambee-syntax-${role}\\); \\}`));
+      }
+      const runFrame = () => {
+        const pending = [...frames.values()];
+        frames.clear();
+        for (const callback of pending) callback(0);
+      };
+      intersections.publish([code]);
+      runFrame();
+      expect(geometry).not.toHaveBeenCalled();
+      for (const stage of ["task", "viewport-geometry", "block-geometry", "mapping", "offset-geometry", "ranges", "publication"]) {
+        expect(measurements.mock.calls.some(([name]) => name === `sambee:preview-syntax:${stage}`)).toBe(true);
+      }
+      measurements.mockRestore();
+      expect([...highlights.values()].reduce((total, ranges) => total + ranges.size, 0)).toBe(MAX_VIEWPORT_SYNTAX_RANGES);
+      expect([...highlights.values()].every((highlight) => (highlight as Set<Range> & { priority: number }).priority === -1)).toBe(true);
+      expect(code.firstChild).toBe(node);
+      expect(code.textContent).toBe(`${source}\n`);
+      expect(selection.toString()).toBe(selected);
+      container.dispatchEvent(new Event("scroll"));
+      expect(frames.size).toBe(1);
+      controller.abort();
+      expect(frames.size).toBe(0);
+      expect(highlights.size).toBe(0);
+      expect(style!.isConnected).toBe(false);
+      expect(intersections.disconnect).toHaveBeenCalledOnce();
+      dispose();
+    } finally {
+      controller.abort();
+      selection.removeAllRanges();
+      geometry.mockRestore();
+      vi.unstubAllGlobals();
+      unmount();
+    }
+  });
+  it.each([
+    [0, 5],
+    [5, 7],
+    [7, 9],
+    [9, 10],
+    [10, 10],
+    [11, 12],
+  ])("retains exact horizontal boundaries with nonuniform and coincident UTF-16 positions (%s/%s)", (left, right) => {
+    const text = "\tA\u{1f642}\u754ce\u0301";
+    const characterRights = [4, 5, 7, 7, 9, 10, 10];
+    const pre = document.createElement("pre");
+    pre.style.whiteSpace = "pre";
+    Object.defineProperties(pre, { scrollWidth: { value: 20 }, clientWidth: { value: 1 } });
+    const rect = vi.spyOn(pre, "getBoundingClientRect").mockReturnValue({ left, right } as DOMRect);
+    const rangeAt = (from: number) => ({ getBoundingClientRect: () => ({ right: characterRights[from] }) }) as Range;
+    const expected = (edge: number) => {
+      const index = characterRights.findIndex((position) => position >= edge);
+      return index < 0 ? text.length : index;
+    };
+    try {
+      expect(visibleSyntaxColumnWindows(text, rangeAt, { left, right }, 0, text.length, pre)).toEqual([
+        { from: expected(left), to: Math.min(text.length, expected(right) + 1) },
+      ]);
+    } finally {
+      rect.mockRestore();
+    }
+  });
+
+  it.each([
+    { left: -200, right: -100 },
+    { left: 100, right: 200 },
+  ])("skips character probes when the horizontal clip is outside the viewport (%#)", (clip) => {
+    const pre = document.createElement("pre");
+    pre.style.whiteSpace = "pre";
+    Object.defineProperties(pre, { scrollWidth: { value: 100 }, clientWidth: { value: 50 } });
+    const rect = vi.spyOn(pre, "getBoundingClientRect").mockReturnValue(clip as DOMRect);
+    const rangeAt = vi.fn();
+    try {
+      expect(visibleSyntaxColumnWindows("text", rangeAt, { left: 0, right: 50 }, 0, 4, pre)).toEqual([]);
+      expect(rangeAt).not.toHaveBeenCalled();
+    } finally {
+      rect.mockRestore();
+    }
+  });
+
+  it.each(["load", "loadingdone"])("refreshes clipped syntax after nested scroll and %s without changing text", (eventType) => {
+    const intersections = mockSyntaxIntersections();
+    const frames = new Map<number, FrameRequestCallback>();
+    const highlights = new Map<string, Set<Range>>();
+    let nextFrame = 0;
+    vi.stubGlobal("CSS", { highlights });
+    vi.stubGlobal(
+      "Highlight",
+      class extends Set<Range> {
+        constructor(...ranges: Range[]) {
+          super(ranges);
+        }
+      }
+    );
+    vi.stubGlobal("requestAnimationFrame", (callback: FrameRequestCallback) => {
+      frames.set(++nextFrame, callback);
+      return nextFrame;
+    });
+    vi.stubGlobal("cancelAnimationFrame", (id: number) => frames.delete(id));
+    const source = "x ".repeat(6_000);
+    const { container, unmount } = render(<ReactMarkdown>{`\`\`\`js\n${source}\n\`\`\``}</ReactMarkdown>);
+    const code = container.querySelector("code")!;
+    const pre = container.querySelector("pre")!;
+    pre.style.whiteSpace = "pre";
+    Object.defineProperties(pre, { scrollWidth: { value: source.length }, clientWidth: { value: 100 } });
+    const rect = { top: 0, bottom: 10, left: 0, right: 100 } as DOMRect;
+    vi.spyOn(container, "getBoundingClientRect").mockReturnValue(rect);
+    vi.spyOn(code, "getBoundingClientRect").mockReturnValue(rect);
+    vi.spyOn(pre, "getBoundingClientRect").mockReturnValue(rect);
+    const fonts = new EventTarget();
+    const originalFonts = Object.getOwnPropertyDescriptor(document, "fonts");
+    Object.defineProperty(document, "fonts", { configurable: true, value: fonts });
+    const removeFontListener = vi.spyOn(fonts, "removeEventListener");
+    const removeRootListener = vi.spyOn(container, "removeEventListener");
+    const loadTarget = document.createElement("img");
+    container.append(loadTarget);
+    let characterWidth = 1;
+    const geometry = vi.spyOn(Range.prototype, "getBoundingClientRect").mockImplementation(function (this: Range) {
+      return { ...rect, left: this.startOffset * characterWidth - pre.scrollLeft, right: this.endOffset * characterWidth - pre.scrollLeft };
+    });
+    const controller = new AbortController();
+    const runFrame = () => {
+      const pending = [...frames.values()];
+      frames.clear();
+      for (const callback of pending) callback(0);
+    };
+    try {
+      publishMarkdownSyntax(
+        container,
+        container,
+        {
+          requests: [{ text: source, label: "js" }],
+          results: [
+            { ranges: Array.from({ length: 6_000 }, (_, index) => ({ from: index * 2, to: index * 2 + 1, categories: ["keyword"] })) },
+          ],
+        },
+        controller.signal
+      );
+      intersections.publish([code]);
+      runFrame();
+      const visible = () => [...highlights.values()].flatMap((ranges) => [...ranges]);
+      expect(visible().length).toBeGreaterThan(0);
+      expect(visible().length).toBeLessThan(100);
+      expect(Math.max(...visible().map((range) => range.endOffset))).toBeLessThanOrEqual(102);
+      expect(geometry.mock.calls.length).toBeLessThan(20);
+      pre.scrollLeft = 10_000;
+      pre.dispatchEvent(new Event("scroll"));
+      expect(frames.size).toBe(1);
+      runFrame();
+      expect(Math.min(...visible().map((range) => range.startOffset))).toBeGreaterThanOrEqual(9_999);
+      pre.scrollLeft = 0;
+      characterWidth = 0.5;
+      const target = eventType === "load" ? loadTarget : fonts;
+      target.dispatchEvent(new Event(eventType));
+      target.dispatchEvent(new Event(eventType));
+      expect(frames.size).toBe(1);
+      runFrame();
+      expect(Math.min(...visible().map((range) => range.startOffset))).toBe(0);
+      expect(Math.max(...visible().map((range) => range.endOffset))).toBeGreaterThan(190);
+      expect(Math.max(...visible().map((range) => range.endOffset))).toBeLessThanOrEqual(202);
+      expect(code.textContent).toBe(`${source}\n`);
+      controller.abort();
+      expect(frames.size).toBe(0);
+      expect(highlights.size).toBe(0);
+      expect(removeFontListener).toHaveBeenCalledWith("loadingdone", expect.any(Function));
+      expect(removeRootListener).toHaveBeenCalledWith("load", expect.any(Function), true);
+      target.dispatchEvent(new Event(eventType));
+      expect(frames.size).toBe(0);
+    } finally {
+      controller.abort();
+      if (originalFonts) Object.defineProperty(document, "fonts", originalFonts);
+      else Reflect.deleteProperty(document, "fonts");
+      removeFontListener.mockRestore();
+      removeRootListener.mockRestore();
+      geometry.mockRestore();
+      vi.unstubAllGlobals();
+      unmount();
+    }
+  });
+
+  it("publishes a late visible block during continuous scrolling without scanning off-screen blocks", () => {
+    const intersections = mockSyntaxIntersections();
+    const frames = new Map<number, FrameRequestCallback>();
+    const highlights = new Map<string, Set<Range>>();
+    let nextFrame = 0;
+    vi.stubGlobal("requestAnimationFrame", (callback: FrameRequestCallback) => {
+      frames.set(++nextFrame, callback);
+      return nextFrame;
+    });
+    vi.stubGlobal("cancelAnimationFrame", (id: number) => frames.delete(id));
+    vi.stubGlobal("CSS", { highlights });
+    vi.stubGlobal(
+      "Highlight",
+      class extends Set<Range> {
+        constructor(...ranges: Range[]) {
+          super(ranges);
+        }
+      }
+    );
+    const { container, unmount } = render(<ReactMarkdown>{"```js\nx\n```\n\n".repeat(600)}</ReactMarkdown>);
+    const blocks = [...container.querySelectorAll("code")];
+    const destination = requireTestValue(blocks[599]);
+    const bounds = { top: 0, bottom: 20 } as DOMRect;
+    const geometry = vi.spyOn(Range.prototype, "getBoundingClientRect").mockReturnValue(bounds);
+    vi.spyOn(container, "getBoundingClientRect").mockReturnValue(bounds);
+    const probes = blocks.map((block, index) =>
+      vi.spyOn(block, "getBoundingClientRect").mockReturnValue(index === 599 ? bounds : ({ top: -20, bottom: -10 } as DOMRect))
+    );
+    const controller = new AbortController();
+    try {
+      publishMarkdownSyntax(
+        container,
+        container,
+        {
+          requests: blocks.map(() => ({ text: "x", label: "js" })),
+          results: blocks.map(() => ({ ranges: [{ from: 0, to: 1, categories: ["keyword"] }] })),
+        },
+        controller.signal
+      );
+      intersections.publish([destination]);
+      for (let iteration = 0; iteration < 60; iteration += 1) {
+        container.dispatchEvent(new Event("scroll"));
+        const pending = [...frames.values()];
+        frames.clear();
+        for (const callback of pending) callback(0);
+        const ranges = [...highlights.values()].flatMap((collection) => [...collection]);
+        expect(ranges).toHaveLength(1);
+        expect(requireTestValue(ranges[0]).startContainer).toBe(destination.firstChild);
+      }
+      expect(probes.slice(0, -1).every((probe) => probe.mock.calls.length === 0)).toBe(true);
+      intersections.publish([destination], false);
+      const pending = [...frames.values()];
+      frames.clear();
+      for (const callback of pending) callback(0);
+      expect([...highlights.values()].every((collection) => collection.size === 0)).toBe(true);
+      controller.abort();
+      expect(intersections.disconnect).toHaveBeenCalledOnce();
+      expect(highlights.size).toBe(0);
+      expect(frames.size).toBe(0);
+    } finally {
+      controller.abort();
+      geometry.mockRestore();
+      vi.restoreAllMocks();
+      vi.unstubAllGlobals();
+      unmount();
+    }
+  });
+
+  it("pages only intersecting syntax ranges without losing boundary tokens", () => {
+    const ranges = Array.from({ length: 200 }, (_, index) => ({ from: index * 3, to: index * 3 + 2, categories: ["keyword"] as const }));
+    const window = { id: 7, from: 4, to: 502 };
+    const collected = [];
+    let offset: number | null = 0;
+    while (offset !== null) {
+      const page = documentSyntaxPage(ranges, window, offset);
+      expect(page.records.length).toBeLessThanOrEqual(DOCUMENT_RECORD_BATCH_ITEMS);
+      collected.push(...page.records);
+      offset = page.next;
+    }
+    expect(collected.map((record) => record.range)).toEqual(ranges.filter((range) => range.to > window.from && range.from < window.to));
+    expect(documentSyntaxPage(ranges, { id: 7, from: 2, to: 3 }, 0).records).toEqual([]);
+    expect(() => documentSyntaxPage(ranges, window, -1)).toThrow("Invalid document syntax window");
+  });
+  it("indexes rendered Markdown across inline markup, blocks and text chunks without joining words", async () => {
+    const model = await createMarkdownDocumentModel(
+      `# Header\n\nA **bold** word.\n\nNext paragraph.\n\n\`\`\`text\n${"x".repeat(2_047)}🌍 end\n\`\`\``
+    );
+    const index = createDocumentSearchIndex(markdownDocumentRecords(model));
+    expect(index.text).toBe(`Header\nA bold word.\nNext paragraph.\n${"x".repeat(2_047)}🌍 end\n`);
+    for (const query of ["bold word", "word.\nNext", "🌍 end"]) {
+      expect([...documentSearchMatches(index.text, query)]).toEqual([
+        { from: index.text.indexOf(query), to: index.text.indexOf(query) + query.length },
+      ]);
+    }
+    expect([...documentSearchMatches(index.text, "word.Next")]).toEqual([]);
+    expect([...documentSearchMatches("WORD word sword", "word", { wholeWord: true })]).toHaveLength(2);
+    expect([...documentSearchMatches("WORD word sword", "word", { wholeWord: true, caseSensitive: true })]).toEqual([{ from: 5, to: 9 }]);
+    expect([...documentSearchMatches("ab\nab", "a.", { regexp: true })]).toEqual([
+      { from: 0, to: 2 },
+      { from: 3, to: 5 },
+    ]);
+    expect([...documentSearchMatches("🌍", "(?=.)", { regexp: true })].length).toBeGreaterThan(0);
+    expect(() => [...documentSearchMatches("text", "[", { regexp: true })]).toThrow("Invalid document search expression");
+    const match = requireTestValue([...documentSearchMatches(index.text, "🌍 end")][0]);
+    expect(index.segments.filter((segment) => segment.to > match.from && segment.from < match.to)).toHaveLength(2);
+  });
+  it("streams semantic whole-Markdown records with bounded text and source-ordered parents", async () => {
+    const source = `# Heading\n\n**Strong** and [safe](https://example.com).\n\n| A | B |\n| - | - |\n| first<br>second | cell |\n\n- [x] done\n\n\`\`\`js\n${"let x=1;\n".repeat(600)}\`\`\`\n\n<script>ignored()</script>`;
+    const model = await createMarkdownDocumentModel(source);
+    const records = [...markdownDocumentRecords(model)];
+    const ids = new Set([0]);
+    for (const record of records) {
+      if (record.kind === "element" || record.kind === "text") {
+        expect(ids.has(record.parent)).toBe(true);
+        expect(ids.has(record.id)).toBe(false);
+        ids.add(record.id);
+      }
+      if (record.kind === "text" || record.kind === "attribute") expect(record.value.length).toBeLessThanOrEqual(DOCUMENT_TEXT_CHUNK_UNITS);
+    }
+    const tags = records.filter((record) => record.kind === "element").map((record) => record.tag);
+    for (const tag of ["h1", "strong", "a", "table", "br", "ul", "input", "pre", "code"]) expect(tags).toContain(tag);
+    expect(tags).not.toContain("script");
+    expect(
+      records
+        .filter((record) => record.kind === "text")
+        .map((record) => record.value)
+        .join("")
+    ).toContain("<script>ignored()</script>");
+    const tableParents = new Set(
+      records
+        .filter((record) => record.kind === "element" && ["table", "thead", "tbody", "tr"].includes(record.tag))
+        .map((record) => record.id)
+    );
+    expect(records.filter((record) => record.kind === "text" && tableParents.has(record.parent))).toEqual([]);
+    expect(model.codeBlocks.map(({ text, label }) => ({ text, label }))).toEqual([{ text: "let x=1;\n".repeat(600), label: "js" }]);
+  });
+  it("keeps the contract and renderer independent of engine imports", () => {
+    const contract = readFileSync("src/utils/syntaxHighlighting.ts", "utf8");
+    const renderer = readFileSync("src/utils/markdownSyntax.ts", "utf8");
+    const presentation = readFileSync("src/theme/syntaxStyles.ts", "utf8");
+    for (const source of [contract, renderer, presentation]) {
+      expect(source).not.toMatch(/from\s+["'][^"']*(?:@codemirror|@lezer|codeMirrorHighlighting|highlightingService)[^"']*["']/);
+    }
+    expect(contract).not.toMatch(/\bimport\b/);
+  });
+  it("collects exact code occurrences from the Markdown AST", () => {
+    expect(collectMarkdownCodeBlocks("```js\nlet x=1\n```\n\n```js\nlet x=1\n```\n\n    plain")).toEqual([
+      { text: "let x=1", label: "js" },
+      { text: "let x=1", label: "js" },
+      { text: "plain", label: null },
+    ]);
+  });
+
+  it("renders prepared ranges, combinations, neutral gaps and Unicode without a parser engine", () => {
+    const source = "```js\nlet x='🌍';\n```\n\n```js\nlet x='🌍';\n```";
+    const requests = collectMarkdownCodeBlocks(source);
+    const results = [
+      {
+        ranges: [
+          { from: 0, to: 3, categories: ["keyword", "strong"] as const },
+          { from: 6, to: 10, categories: ["string"] as const },
+        ],
+      },
+      { reason: "parsing-failure" as const },
+    ];
+    const { container } = render(<ReactMarkdown rehypePlugins={[[rehypePreparedSyntax, { requests, results }]]}>{source}</ReactMarkdown>);
+    const blocks = container.querySelectorAll("pre code");
+    expect(blocks[0]!.textContent).toBe("let x='🌍';\n");
+    expect(blocks[1]!.textContent).toBe(blocks[0]!.textContent);
+    expect(blocks[0]!.querySelector(".sambee-syntax-keyword.sambee-syntax-strong")).not.toBeNull();
+    expect(blocks[1]!.querySelector("span")).toBeNull();
+  });
+
+  it("keeps stale, invalid and empty results neutral without changing text", () => {
+    const source = "```\nhello\n```";
+    const requests = collectMarkdownCodeBlocks(source);
+    for (const result of [{ ranges: [] }, { ranges: [{ from: 0, to: 99, categories: ["keyword"] as const }] }]) {
+      const { container, unmount } = render(
+        <ReactMarkdown rehypePlugins={[[rehypePreparedSyntax, { requests, results: [result] }]]}>{source}</ReactMarkdown>
+      );
+      expect(container.querySelector("code")?.textContent).toBe("hello\n");
+      expect(container.querySelector("span")).toBeNull();
+      unmount();
+    }
+  });
+});
diff --git a/frontend/src/utils/__tests__/syntaxHighlighting.test.ts b/frontend/src/utils/__tests__/syntaxHighlighting.test.ts
new file mode 100644
index 000000000..72e8f1eb0
--- /dev/null
+++ b/frontend/src/utils/__tests__/syntaxHighlighting.test.ts
@@ -0,0 +1,406 @@
+import { languages } from "@codemirror/language-data";
+import { EditorState } from "@codemirror/state";
+import { EditorView } from "@codemirror/view";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import * as logger from "../../services/logger";
+import {
+  codeMirrorHighlighting,
+  loadNativeLanguage,
+  MAX_STATIC_BLOCK_LENGTH,
+  nativeSyntaxHighlighting,
+  resolveFence,
+  resolveFilename,
+  yieldHighlightingTask,
+} from "../codeMirrorHighlighting";
+
+describe("shared syntax highlighting", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+    vi.unstubAllGlobals();
+    vi.useRealTimers();
+  });
+  it("resolves exact aliases and filenames without guessing extensions", () => {
+    expect(resolveFence("JS")).toEqual(resolveFilename("example.js"));
+    expect(resolveFence("py")).toEqual(resolveFilename("example.py"));
+    expect(resolveFence("unknown-fence")).toEqual({ reason: "unknown-language" });
+    expect(resolveFence("text")).toEqual({ reason: "plain-text" });
+  });
+
+  it.each([
+    ["mssql", "ms sql"],
+    ["mariadb", "mariadb sql"],
+  ])("resolves %s to its registered dialect rather than generic SQL", (label, language) => {
+    expect(resolveFence(label)).toEqual({ language });
+    expect(resolveFence(` ${label.toUpperCase()} title=example `)).toEqual({ language });
+    expect(resolveFence(`${label}-unknown`)).toEqual({ reason: "unknown-language" });
+    expect(resolveFilename("example.sql")).toEqual({ language: "sql" });
+  });
+
+  it.each(["javascript", "typescript", "python", "sql", "shell"])("produces ordered application ranges for %s", async (label) => {
+    const text = label === "python" ? 'def greet():\n  return "hello 🌍"' : "let x = 1; // hello 🌍\n";
+    const [result] = await codeMirrorHighlighting.prepare([{ text, label }]);
+    expect(result).toHaveProperty("ranges");
+    if (!result || !("ranges" in result)) return;
+    let previous = 0;
+    for (const range of result.ranges) {
+      expect(range.from).toBeGreaterThanOrEqual(previous);
+      expect(range.to).toBeGreaterThan(range.from);
+      expect(range.to).toBeLessThanOrEqual(text.length);
+      expect(range.categories.length).toBeGreaterThan(0);
+      previous = range.to;
+    }
+    expect(result.ranges.length).toBeGreaterThan(0);
+  });
+
+  it("settles independent fallback outcomes", async () => {
+    expect(
+      await codeMirrorHighlighting.prepare([
+        { text: "x", label: "unknown-fence" },
+        { text: "x" },
+        { text: "x".repeat(MAX_STATIC_BLOCK_LENGTH + 1), label: "javascript" },
+        { text: "const x=1", label: "js" },
+      ])
+    ).toEqual([{ reason: "unknown-language" }, { reason: "plain-text" }, { reason: "block-too-large" }, { ranges: expect.any(Array) }]);
+  });
+
+  it.each([
+    ["powershell", "$sites = Get-Content $siteUrlFile;", "Get-Content", "builtin"],
+    ["shell", 'echo "$HOME"', "echo", "builtin"],
+    ["javascript", "const result = obj.value;", "value", "property"],
+    ["json", '{"enabled": true}', '"enabled"', "property"],
+    ["javascript", "const enabled = true;", "true", "boolean"],
+    ["python", "enabled = True", "True", "boolean"],
+    ["json", '{"value": null}', "null", "null"],
+    ["python", "value = None", "None", "null"],
+    ["javascript", "const pattern = /foo+/g;", "/foo+/g", "regexp"],
+    ["javascript", 'const text = "a\\nb";', "\\n", "escape"],
+    ["python", "@decorator\ndef greet(): pass", "@", "metadata"],
+    ["c", "#include <stdio.h>", "#include", "metadata"],
+  ])("preserves shared %s tags for %s", async (label, text, token, category) => {
+    const fence = `\`\`\`${label}\n${text}\n\`\`\``;
+    const [result, nested] = await codeMirrorHighlighting.prepare([
+      { text, label },
+      { text: fence, label: "markdown" },
+    ]);
+    if (!result || !("ranges" in result)) throw new Error("Missing syntax ranges");
+    const from = text.indexOf(token);
+    expect(result.ranges).toContainEqual({ from, to: from + token.length, categories: [category] });
+    if (!nested || !("ranges" in nested)) throw new Error("Missing nested syntax ranges");
+    const nestedFrom = fence.indexOf(text) + from;
+    expect(nested.ranges).toContainEqual({ from: nestedFrom, to: nestedFrom + token.length, categories: [category] });
+    const resolved = resolveFence(label);
+    if (!("language" in resolved)) throw new Error("Missing test language");
+    const support = await loadNativeLanguage(resolved.language);
+    const view = new EditorView({ state: EditorState.create({ doc: text, extensions: [support, nativeSyntaxHighlighting] }) });
+    try {
+      expect([...view.contentDOM.querySelectorAll(`.sambee-syntax-${category}`)].map((span) => span.textContent)).toContain(token);
+      expect(view.state.doc.toString()).toBe(text);
+    } finally {
+      view.destroy();
+    }
+  });
+
+  it("rejects cancellation without publishing partial results", async () => {
+    const controller = new AbortController();
+    const request = codeMirrorHighlighting.prepare([{ text: "let x=1", label: "js" }], controller.signal);
+    controller.abort();
+    await expect(request).rejects.toMatchObject({ name: "AbortError" });
+  });
+
+  it("settles nested Markdown fences identically on cold and warm loads", async () => {
+    const blocks = [{ text: '```python\ndef greet():\n  return "hello"\n```', label: "markdown" }];
+    const cold = await codeMirrorHighlighting.prepare(blocks);
+    const warm = await codeMirrorHighlighting.prepare(blocks);
+    expect(cold).toEqual(warm);
+    expect(cold[0]).toMatchObject({ ranges: expect.arrayContaining([expect.objectContaining({ categories: ["keyword"] })]) });
+  });
+
+  it("settles different repeated nested Markdown configurations", async () => {
+    const text = "~~~~markdown\n```python\ndef first(): pass\n```\n~~~~\n\n~~~~markdown\n```javascript\nconst second=1;\n```\n~~~~";
+    const [result] = await codeMirrorHighlighting.prepare([{ text, label: "markdown" }]);
+    expect(result).toHaveProperty("ranges");
+    if (!result || !("ranges" in result)) return;
+    const keywords = result.ranges.filter((range) => range.categories.includes("keyword")).map((range) => text.slice(range.from, range.to));
+    expect(keywords).toContain("def");
+    expect(keywords).toContain("const");
+  });
+
+  it.each([true, false])("isolates a nested grammar loading failure with failed fence first: %s", async (failedFirst) => {
+    const description = languages.find((language) => language.name === "Python")!;
+    const support = await description.load();
+    const load = vi.spyOn(description, "load").mockRejectedValue(new Error("Grammar unavailable"));
+    const log = vi.spyOn(logger, "error").mockImplementation(() => {});
+    const failedCode = "PRIVATE_SOURCE";
+    const failedFence = `\`\`\`python\n${failedCode}\n\`\`\``;
+    const successfulFence = "```javascript\nconst sibling = 1;\n```";
+    const fences = failedFirst ? [failedFence, successfulFence] : [successfulFence, failedFence];
+    const text = `# Heading\n\n${fences.join("\n\n")}`;
+    const results = await codeMirrorHighlighting.prepare([
+      { text, label: "markdown" },
+      { text: "const independent = 1;", label: "js" },
+    ]);
+    const result = results[0];
+    if (!result || !("ranges" in result)) throw new Error("Missing enclosing Markdown ranges");
+    expect(result.ranges).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ categories: ["heading"] }),
+        expect.objectContaining({ from: text.indexOf("const sibling"), categories: ["keyword"] }),
+      ])
+    );
+    const failedFrom = text.indexOf(failedCode);
+    expect(result.ranges.some((range) => range.from < failedFrom + failedCode.length && range.to > failedFrom)).toBe(false);
+    expect(results[1]).toHaveProperty("ranges");
+    expect(log).toHaveBeenCalledTimes(1);
+    expect(log.mock.calls[0]?.[1]).toEqual({ language: "python", operation: "load" });
+    expect(JSON.stringify(log.mock.calls)).not.toContain(failedCode);
+    load.mockResolvedValue(support);
+    const [recovered] = await codeMirrorHighlighting.prepare([{ text: "```python\ndef recovered(): pass\n```", label: "markdown" }]);
+    expect(recovered).toMatchObject({ ranges: expect.arrayContaining([expect.objectContaining({ categories: ["keyword"] })]) });
+  });
+
+  it("preserves cancellation when a nested grammar rejects after abort", async () => {
+    const description = languages.find((language) => language.name === "Python")!;
+    const support = await description.load();
+    let rejectLoad!: (error: Error) => void;
+    const pendingLoad = new Promise<typeof support>((_resolve, reject) => {
+      rejectLoad = reject;
+    });
+    const load = vi.spyOn(description, "load").mockReturnValue(pendingLoad);
+    const log = vi.spyOn(logger, "error").mockImplementation(() => {});
+    const controller = new AbortController();
+    const request = codeMirrorHighlighting.prepare([{ text: "```python\ndef pending(): pass\n```", label: "markdown" }], controller.signal);
+    await vi.waitFor(() => expect(load).toHaveBeenCalledOnce());
+    controller.abort();
+    await expect(request).rejects.toMatchObject({ name: "AbortError" });
+    rejectLoad(new Error("Late grammar failure"));
+    await Promise.resolve();
+    expect(log).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    { failedFirst: true, phase: "start" },
+    { failedFirst: false, phase: "start" },
+    { failedFirst: true, phase: "advance" },
+    { failedFirst: false, phase: "advance" },
+  ])("isolates a nested grammar parsing failure ($phase, failed first: $failedFirst)", async ({ failedFirst, phase }) => {
+    const description = languages.find((language) => language.name === "Python")!;
+    const support = await description.load();
+    const startParse = support.language.parser.startParse.bind(support.language.parser);
+    const parse = vi.spyOn(support.language.parser, "startParse").mockImplementation((...args) => {
+      if (phase === "start") throw new Error("Parser unavailable");
+      const partial = startParse(...args);
+      vi.spyOn(partial, "advance").mockImplementation(() => {
+        throw new Error("Parser advance failed");
+      });
+      return partial;
+    });
+    const log = vi.spyOn(logger, "error").mockImplementation(() => {});
+    const failedCode = "PRIVATE_SOURCE";
+    const failedFence = `\`\`\`python\n${failedCode}\n\`\`\``;
+    const successfulFence = "```javascript\nconst sibling = 1;\n```";
+    const fences = failedFirst ? [failedFence, successfulFence] : [successfulFence, failedFence];
+    const text = `# Heading\n\n${fences.join("\n\n")}`;
+    const [result, independent] = await codeMirrorHighlighting.prepare([
+      { text, label: "markdown" },
+      { text: "const independent = 1;", label: "js" },
+    ]);
+    if (!result || !("ranges" in result)) throw new Error("Missing enclosing Markdown ranges");
+    expect(result.ranges).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ categories: ["heading"] }),
+        expect.objectContaining({ from: text.indexOf("const sibling"), categories: ["keyword"] }),
+      ])
+    );
+    const failedFrom = text.indexOf(failedCode);
+    expect(result.ranges.some((range) => range.from < failedFrom + failedCode.length && range.to > failedFrom)).toBe(false);
+    expect(independent).toHaveProperty("ranges");
+    expect(log).toHaveBeenCalledTimes(1);
+    expect(log.mock.calls[0]?.[1]).toEqual({ language: "python", operation: "parse" });
+    expect(JSON.stringify(log.mock.calls)).not.toContain(failedCode);
+    parse.mockRestore();
+    const [recovered] = await codeMirrorHighlighting.prepare([{ text: "```python\ndef recovered(): pass\n```", label: "markdown" }]);
+    expect(recovered).toMatchObject({ ranges: expect.arrayContaining([expect.objectContaining({ categories: ["keyword"] })]) });
+  });
+
+  it("does not poison later fences using the same grammar after one parse fails", async () => {
+    const description = languages.find((language) => language.name === "Python")!;
+    const support = await description.load();
+    vi.spyOn(support.language.parser, "startParse").mockImplementationOnce(() => {
+      throw new Error("First fence failed");
+    });
+    vi.spyOn(logger, "error").mockImplementation(() => {});
+    const text = "# Heading\n\n```python\nPRIVATE_SOURCE\n```\n\n```python\ndef sibling(): pass\n```";
+    const [result] = await codeMirrorHighlighting.prepare([{ text, label: "markdown" }]);
+    if (!result || !("ranges" in result)) throw new Error("Missing enclosing Markdown ranges");
+    expect(result.ranges).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ categories: ["heading"] }),
+        expect.objectContaining({ from: text.indexOf("def sibling"), categories: ["keyword"] }),
+      ])
+    );
+  });
+
+  it("does not turn cancellation during a nested parse into plain-text success", async () => {
+    const description = languages.find((language) => language.name === "Python")!;
+    const support = await description.load();
+    const controller = new AbortController();
+    vi.spyOn(support.language.parser, "startParse").mockImplementation(() => {
+      controller.abort();
+      throw new Error("Parser interrupted");
+    });
+    const log = vi.spyOn(logger, "error").mockImplementation(() => {});
+    await expect(
+      codeMirrorHighlighting.prepare([{ text: "```python\ndef pending(): pass\n```", label: "markdown" }], controller.signal)
+    ).rejects.toMatchObject({ name: "AbortError" });
+    expect(log).not.toHaveBeenCalled();
+  });
+
+  it("scopes Markdown structure to markers and leaves unknown code and prose neutral", async () => {
+    const text =
+      '# Heading\n\nPlain paragraph\n\n*emphasis* **strong** ~~strike~~\n\n- item\n\n> quote\n\n[link](https://example.com) ![alt](image.png)\n\n`inline`\n\n---\n\n```js\nconst x="code";\n```\n\n```unknown\n*not prose*\n```';
+    const [result] = await codeMirrorHighlighting.prepare([{ text, label: "markdown" }]);
+    if (!result || !("ranges" in result)) throw new Error("Missing Markdown ranges");
+    const tokens = result.ranges.map((range) => ({ text: text.slice(range.from, range.to), categories: range.categories }));
+    for (const [value, category] of [
+      [" Heading", "heading"],
+      ["emphasis", "emphasis"],
+      ["strong", "strong"],
+      ["strike", "strikethrough"],
+      ["-", "structure"],
+      [">", "structure"],
+      ["link", "link"],
+      ["inline", "inlineCode"],
+      ["---", "structure"],
+      ["js", "structure"],
+      ["const", "keyword"],
+      ['"code"', "string"],
+    ]) {
+      expect(tokens).toContainEqual({ text: value, categories: expect.arrayContaining([category]) });
+    }
+    for (const neutral of ["Plain paragraph", " item", " quote", "*not prose*"]) {
+      const from = text.indexOf(neutral);
+      expect(result.ranges.some((range) => range.from < from + neutral.length && range.to > from)).toBe(false);
+    }
+  });
+
+  it("counts Markdown levels independently of embedded code", async () => {
+    const nest = (text: string, length: number) => `${"`".repeat(length)}markdown\n${text}\n${"`".repeat(length)}`;
+    const base = "```javascript\nconst x=1;\n```";
+    const atLimit = nest(nest(nest(base, 4), 5), 6);
+    const aboveLimit = nest(atLimit, 7);
+    const results = await codeMirrorHighlighting.prepare([
+      { text: atLimit, label: "markdown" },
+      { text: aboveLimit, label: "markdown" },
+    ]);
+    expect(results[0]).toHaveProperty("ranges");
+    expect(results[1]).toEqual({ reason: "nesting-depth" });
+  });
+
+  it.each([
+    ["javascript", "function greet(x) { return x + 1; } // end"],
+    ["typescript", "const greet = (x: string): string => x;"],
+    ["python", 'def greet(x):\n  return "hello" # end'],
+    ["sql", "SELECT count(*) FROM users WHERE id = 1;"],
+    ["mssql", "SELECT TOP 1 [account] FROM [users] WHERE [id] = @id; -- end"],
+    ["mariadb", "SELECT `account` FROM `users` LIMIT 1; # end"],
+    ["shell", 'echo "hello" # end'],
+    ["powershell", "$sites = Get-Content $siteUrlFile;"],
+    ["javascript", 'obj.value = [true, null, /foo+/g, "a\\nb"];'],
+    ["json", '{"enabled": true, "value": null}'],
+    ["c", "#include <stdio.h>"],
+  ])("emits the same native and static classes for %s", async (label, text) => {
+    const resolved = resolveFence(label);
+    if (!("language" in resolved)) throw new Error("Missing test language");
+    const support = await loadNativeLanguage(resolved.language);
+    const view = new EditorView({ state: EditorState.create({ doc: text, extensions: [support, nativeSyntaxHighlighting] }) });
+    try {
+      const [result] = await codeMirrorHighlighting.prepare([{ text, label }]);
+      if (!result || !("ranges" in result)) throw new Error("Missing token ranges");
+      const nativeTokens = Array.from(view.contentDOM.querySelectorAll("span[class*='sambee-syntax-']"), (span) => ({
+        text: span.textContent,
+        classes: span.className,
+      }));
+      const staticTokens = result.ranges.map((range) => ({
+        text: text.slice(range.from, range.to),
+        classes: range.categories.map((category) => `sambee-syntax-${category}`).join(" "),
+      }));
+      expect(nativeTokens).toEqual(staticTokens);
+    } finally {
+      view.destroy();
+    }
+  });
+
+  it("yields a browser task for every block even with warm grammars and no aggregate cutoff", async () => {
+    const taskYield = vi.fn(async () => {});
+    vi.stubGlobal("scheduler", { yield: taskYield });
+    const text = `//${"x".repeat(900)}`;
+    const blocks = Array.from({ length: 600 }, () => ({ text, label: "js" }));
+    expect(blocks.reduce((sum, block) => sum + block.text.length, 0)).toBeGreaterThan(500_000);
+    const results = await codeMirrorHighlighting.prepare(blocks);
+    expect(results).toHaveLength(600);
+    expect(results.every((result) => "ranges" in result)).toBe(true);
+    expect(taskYield).toHaveBeenCalledTimes(600);
+  });
+
+  it("uses timer tasks when scheduler.yield is unavailable", async () => {
+    vi.useFakeTimers();
+    vi.stubGlobal("scheduler", undefined);
+    let finished = false;
+    const task = yieldHighlightingTask().then(() => {
+      finished = true;
+    });
+    await Promise.resolve();
+    expect(finished).toBe(false);
+    await vi.runAllTimersAsync();
+    await task;
+    expect(finished).toBe(true);
+  });
+
+  it("aborts a shared grammar wait promptly while a new request can reuse it", async () => {
+    vi.stubGlobal("scheduler", { yield: async () => {} });
+    const description = languages.find((language) => language.name === "JavaScript")!;
+    const support = await description.load();
+    let finish!: (value: typeof support) => void;
+    const sharedLoad = new Promise<typeof support>((resolve) => {
+      finish = resolve;
+    });
+    const load = vi.spyOn(description, "load").mockReturnValue(sharedLoad);
+    const controller = new AbortController();
+    const obsolete = codeMirrorHighlighting.prepare([{ text: "let x=1", label: "js" }], controller.signal);
+    await vi.waitFor(() => expect(load).toHaveBeenCalledTimes(1));
+    controller.abort();
+    await expect(obsolete).rejects.toMatchObject({ name: "AbortError" });
+    const current = codeMirrorHighlighting.prepare([{ text: "let x=2", label: "js" }]);
+    finish(support);
+    expect((await current)[0]).toHaveProperty("ranges");
+  });
+
+  it("does not start guarded grammar work and tests the exact size boundary", async () => {
+    vi.stubGlobal("scheduler", { yield: async () => {} });
+    const description = languages.find((language) => language.name === "JavaScript")!;
+    const load = vi.spyOn(description, "load");
+    expect(await codeMirrorHighlighting.prepare([{ text: " ".repeat(MAX_STATIC_BLOCK_LENGTH + 1), label: "js" }])).toEqual([
+      { reason: "block-too-large" },
+    ]);
+    expect(load).not.toHaveBeenCalled();
+    const results = await codeMirrorHighlighting.prepare(
+      [MAX_STATIC_BLOCK_LENGTH - 1, MAX_STATIC_BLOCK_LENGTH].map((length) => ({ text: `//${"x".repeat(length - 2)}`, label: "js" }))
+    );
+    expect(results.every((result) => "ranges" in result)).toBe(true);
+  });
+
+  it("settles loading failures independently and logs context without source text", async () => {
+    const description = languages.find((language) => language.name === "JavaScript")!;
+    vi.spyOn(description, "load").mockRejectedValueOnce(new Error("Grammar unavailable"));
+    const log = vi.spyOn(logger, "error").mockImplementation(() => {});
+    const results = await codeMirrorHighlighting.prepare([
+      { text: "PRIVATE_SOURCE", label: "js" },
+      { text: "def greet(): pass", label: "py" },
+    ]);
+    expect(results[0]).toEqual({ reason: "loading-failure" });
+    expect(results[1]).toHaveProperty("ranges");
+    expect(log).toHaveBeenCalledTimes(1);
+    expect(log.mock.calls[0]?.[1]).toEqual({ language: "javascript", operation: "load" });
+    expect(JSON.stringify(log.mock.calls)).not.toContain("PRIVATE_SOURCE");
+  });
+});
diff --git a/frontend/src/utils/__tests__/viewerPerformanceBudgets.test.ts b/frontend/src/utils/__tests__/viewerPerformanceBudgets.test.ts
new file mode 100644
index 000000000..f87ec8899
--- /dev/null
+++ b/frontend/src/utils/__tests__/viewerPerformanceBudgets.test.ts
@@ -0,0 +1,233 @@
+import { describe, expect, test } from "vitest";
+import {
+  evaluateSourceResponsivenessBudgets,
+  evaluateSourceTypingBudgets,
+  evaluateViewerAcceptanceCoverage,
+  evaluateViewerAcceptanceReport,
+  evaluateViewerReadinessBudgets,
+  evaluateViewerTimingBudgets,
+  SOURCE_RESPONSIVENESS_TARGETS_MS,
+  SOURCE_TYPING_TARGETS_MS,
+  VIEWER_ACCEPTANCE_CASES,
+  VIEWER_READINESS_TARGETS_MS,
+  VIEWER_TIMING_TARGETS_MS,
+} from "../../../e2e/viewer-performance-budgets";
+import { requireTestValue } from "../../test/helpers/assertions";
+
+describe("viewer acceptance report", () => {
+  const attachment = {
+    name: "source-responsiveness",
+    body: Buffer.from(
+      JSON.stringify({ enforced: true, budgets: evaluateSourceResponsivenessBudgets(SOURCE_RESPONSIVENESS_TARGETS_MS) })
+    ).toString("base64"),
+  };
+  const report = () => ({
+    errors: [],
+    suites: [
+      {
+        title: "markdown-viewer.spec.ts",
+        specs: VIEWER_ACCEPTANCE_CASES["dense-expansion"].map((title) => ({
+          title,
+          tests: ["chromium", "firefox"].flatMap((projectName) =>
+            Array.from({ length: 3 }, (_, repeatEachIndex) => ({
+              projectName,
+              repeatEachIndex,
+              status: "expected",
+              results: [{ status: "passed", retry: 0, attachments: [{ ...attachment }] }],
+            }))
+          ),
+        })),
+      },
+    ],
+  });
+
+  test("requires all 24 fixed expansion trials and their enforced evidence", () => {
+    const result = evaluateViewerAcceptanceReport("dense-expansion", report());
+    expect(result).toMatchObject({ status: "pass", expectedCount: 24, observedCount: 24 });
+  });
+
+  test("reads trial identity from attachments in the real Playwright JSON schema", () => {
+    const realSchema = report();
+    for (const spec of requireTestValue(realSchema.suites[0]).specs)
+      for (const entry of spec.tests) {
+        requireTestValue(requireTestValue(entry.results[0]).attachments[0]).body = Buffer.from(
+          JSON.stringify({
+            trial: entry.repeatEachIndex,
+            enforced: true,
+            budgets: evaluateSourceResponsivenessBudgets(SOURCE_RESPONSIVENESS_TARGETS_MS),
+          })
+        ).toString("base64");
+        Reflect.deleteProperty(entry, "repeatEachIndex");
+      }
+    expect(evaluateViewerAcceptanceReport("dense-expansion", realSchema).status).toBe("pass");
+  });
+
+  test("rejects a passing subset and a missing report", () => {
+    const subset = report();
+    requireTestValue(subset.suites[0]).specs.pop();
+    expect(evaluateViewerAcceptanceReport("dense-expansion", subset).status).toBe("fail");
+    expect(evaluateViewerAcceptanceReport("dense-expansion", { suites: [] }).status).toBe("fail");
+  });
+
+  test("rejects missing, duplicate, invalid, unenforced and failing attachments", () => {
+    for (const attachments of [
+      [],
+      [attachment, attachment],
+      [{ ...attachment, body: "invalid" }],
+      [{ ...attachment, body: Buffer.from(JSON.stringify({ enforced: false, budgets: { status: "pass" } })).toString("base64") }],
+      [{ ...attachment, body: Buffer.from(JSON.stringify({ enforced: true, budgets: { status: "fail" } })).toString("base64") }],
+    ]) {
+      const invalid = report();
+      requireTestValue(requireTestValue(requireTestValue(requireTestValue(invalid.suites[0]).specs[0]).tests[0]).results[0]).attachments =
+        attachments;
+      expect(evaluateViewerAcceptanceReport("dense-expansion", invalid).status).toBe("fail");
+    }
+  });
+
+  test("recomputes metrics instead of trusting a pass label", () => {
+    for (const metrics of [
+      [],
+      [{ metric: "atomicCommit", observedMs: -1 }],
+      [...evaluateSourceResponsivenessBudgets(SOURCE_RESPONSIVENESS_TARGETS_MS).metrics, { metric: "atomicCommit", observedMs: 0 }],
+    ]) {
+      const invalid = report();
+      requireTestValue(requireTestValue(requireTestValue(requireTestValue(invalid.suites[0]).specs[0]).tests[0]).results[0]).attachments = [
+        { ...attachment, body: Buffer.from(JSON.stringify({ enforced: true, budgets: { status: "pass", metrics } })).toString("base64") },
+      ];
+      expect(evaluateViewerAcceptanceReport("dense-expansion", invalid).status).toBe("fail");
+    }
+  });
+
+  test("rejects skips, retries, repeated trials and report errors", () => {
+    const skipped = report();
+    requireTestValue(requireTestValue(requireTestValue(requireTestValue(skipped.suites[0]).specs[0]).tests[0]).results[0]).status =
+      "skipped";
+    expect(evaluateViewerAcceptanceReport("dense-expansion", skipped).status).toBe("fail");
+    const retried = report();
+    requireTestValue(requireTestValue(requireTestValue(requireTestValue(retried.suites[0]).specs[0]).tests[0]).results[0]).retry = 1;
+    expect(evaluateViewerAcceptanceReport("dense-expansion", retried).status).toBe("fail");
+    const duplicate = report();
+    requireTestValue(requireTestValue(duplicate.suites[0]).specs[0]).tests.push(
+      requireTestValue(requireTestValue(requireTestValue(duplicate.suites[0]).specs[0]).tests[0])
+    );
+    expect(evaluateViewerAcceptanceReport("dense-expansion", duplicate).status).toBe("fail");
+    expect(evaluateViewerAcceptanceReport("dense-expansion", { ...report(), errors: ["interrupted"] }).status).toBe("fail");
+  });
+});
+
+describe("viewer acceptance coverage", () => {
+  const expected = ["chromium/1543/dense/cold/1", "firefox/390/dense/cold/1"] as const;
+  const samples = expected.map((identity) => ({ identity, status: "pass", retry: 0 }));
+  const firstSample = requireTestValue(samples[0]);
+  const secondSample = requireTestValue(samples[1]);
+
+  test("requires every expected identity exactly once", () => {
+    expect(evaluateViewerAcceptanceCoverage(expected, samples).status).toBe("pass");
+    expect(evaluateViewerAcceptanceCoverage(expected, samples.slice(1)).missing).toEqual([expected[0]]);
+    expect(evaluateViewerAcceptanceCoverage(expected, [...samples, firstSample]).duplicate).toEqual([expected[0]]);
+    expect(evaluateViewerAcceptanceCoverage(expected, [...samples, { ...firstSample, identity: "unexpected" }]).unexpected).toEqual([
+      "unexpected",
+    ]);
+  });
+
+  test("rejects empty or duplicate expectations", () => {
+    expect(evaluateViewerAcceptanceCoverage([], []).status).toBe("fail");
+    expect(evaluateViewerAcceptanceCoverage([...expected, expected[0]], samples).status).toBe("fail");
+  });
+
+  for (const status of ["fail", "invalid", "skipped", "diagnostic", "unverified"]) {
+    test(`rejects ${status} samples`, () => {
+      expect(evaluateViewerAcceptanceCoverage(expected, [{ ...firstSample, status }, secondSample]).status).toBe("fail");
+    });
+  }
+
+  test("rejects retries even when the final result passes", () => {
+    expect(evaluateViewerAcceptanceCoverage(expected, [{ ...firstSample, retry: 1 }, secondSample]).status).toBe("fail");
+  });
+});
+
+describe("source typing budget evaluation", () => {
+  test("keeps keyboard p95 strictly below 50 ms", () => {
+    expect(evaluateSourceTypingBudgets(SOURCE_TYPING_TARGETS_MS).status).toBe("fail");
+    expect(
+      evaluateSourceTypingBudgets({ ...SOURCE_TYPING_TARGETS_MS, keyboardTwoFrameP95: SOURCE_TYPING_TARGETS_MS.keyboardTwoFrameP95 - 0.1 })
+        .status
+    ).toBe("pass");
+  });
+  for (const metric of Object.keys(SOURCE_TYPING_TARGETS_MS) as (keyof typeof SOURCE_TYPING_TARGETS_MS)[]) {
+    test(`rejects missing, invalid and over-budget ${metric}`, () => {
+      for (const sample of [undefined, null, Number.NaN, Number.POSITIVE_INFINITY, -1, SOURCE_TYPING_TARGETS_MS[metric] + 1]) {
+        const report = evaluateSourceTypingBudgets({
+          ...SOURCE_TYPING_TARGETS_MS,
+          keyboardTwoFrameP95: SOURCE_TYPING_TARGETS_MS.keyboardTwoFrameP95 - 0.1,
+          [metric]: sample,
+        });
+        expect(report.status).toBe("fail");
+        expect(report.metrics.find((entry) => entry.metric === metric)?.status).not.toBe("pass");
+      }
+    });
+  }
+});
+
+describe("source responsiveness budget evaluation", () => {
+  for (const metric of Object.keys(SOURCE_RESPONSIVENESS_TARGETS_MS) as (keyof typeof SOURCE_RESPONSIVENESS_TARGETS_MS)[]) {
+    test(`enforces ${metric}, including missing and invalid samples`, () => {
+      expect(evaluateSourceResponsivenessBudgets(SOURCE_RESPONSIVENESS_TARGETS_MS).status).toBe("pass");
+      for (const sample of [undefined, null, Number.NaN, Number.POSITIVE_INFINITY, -1, SOURCE_RESPONSIVENESS_TARGETS_MS[metric] + 1]) {
+        const report = evaluateSourceResponsivenessBudgets({ ...SOURCE_RESPONSIVENESS_TARGETS_MS, [metric]: sample });
+        expect(report.status).toBe("fail");
+        expect(report.metrics.find((entry) => entry.metric === metric)?.status).not.toBe("pass");
+      }
+    });
+  }
+  test("does not count diagnostic evidence as acceptance", () => {
+    expect(evaluateSourceResponsivenessBudgets(SOURCE_RESPONSIVENESS_TARGETS_MS, true).status).toBe("diagnostic");
+  });
+});
+
+describe("viewer timing budget evaluation", () => {
+  test("accepts the exact targets and rejects an over-budget sample", () => {
+    expect(evaluateViewerTimingBudgets(VIEWER_TIMING_TARGETS_MS).status).toBe("pass");
+    const report = evaluateViewerTimingBudgets({ ...VIEWER_TIMING_TARGETS_MS, changedQuery: VIEWER_TIMING_TARGETS_MS.changedQuery + 1 });
+    expect(report.status).toBe("fail");
+    expect(report.metrics.find((metric) => metric.metric === "changedQuery")?.status).toBe("fail");
+    expect(report.openCriteria.length).toBeGreaterThan(0);
+  });
+
+  for (const sample of [undefined, null, Number.NaN, Number.POSITIVE_INFINITY, -1]) {
+    test(`rejects a missing or invalid measurement: ${String(sample)}`, () => {
+      const report = evaluateViewerTimingBudgets({ ...VIEWER_TIMING_TARGETS_MS, documentCompletion: sample });
+      expect(report.status).toBe("fail");
+      expect(report.metrics.find((metric) => metric.metric === "documentCompletion")).toMatchObject({
+        status: "invalid",
+        observedMs: null,
+      });
+    });
+  }
+
+  test("does not turn diagnostic measurements into an acceptance pass", () => {
+    const report = evaluateViewerTimingBudgets(VIEWER_TIMING_TARGETS_MS, true);
+    expect(report.status).toBe("diagnostic");
+  });
+});
+
+describe("viewer readiness budget evaluation", () => {
+  for (const metric of Object.keys(VIEWER_READINESS_TARGETS_MS) as (keyof typeof VIEWER_READINESS_TARGETS_MS)[]) {
+    test(`accepts the exact target and rejects an over-budget ${metric}`, () => {
+      expect(evaluateViewerReadinessBudgets(VIEWER_READINESS_TARGETS_MS).status).toBe("pass");
+      const report = evaluateViewerReadinessBudgets({ ...VIEWER_READINESS_TARGETS_MS, [metric]: VIEWER_READINESS_TARGETS_MS[metric] + 1 });
+      expect(report.status).toBe("fail");
+      expect(report.metrics.find((entry) => entry.metric === metric)?.status).toBe("fail");
+    });
+    for (const sample of [undefined, null, Number.NaN, Number.POSITIVE_INFINITY, -1]) {
+      test(`rejects invalid ${metric}: ${String(sample)}`, () => {
+        const report = evaluateViewerReadinessBudgets({ ...VIEWER_READINESS_TARGETS_MS, [metric]: sample });
+        expect(report.status).toBe("fail");
+        expect(report.metrics.find((entry) => entry.metric === metric)).toMatchObject({ status: "invalid", observedMs: null });
+      });
+    }
+  }
+  test("does not turn diagnostic readiness measurements into acceptance", () => {
+    expect(evaluateViewerReadinessBudgets(VIEWER_READINESS_TARGETS_MS, true).status).toBe("diagnostic");
+  });
+});
diff --git a/frontend/src/utils/codeMirrorHighlighting.ts b/frontend/src/utils/codeMirrorHighlighting.ts
new file mode 100644
index 000000000..f1b750c7b
--- /dev/null
+++ b/frontend/src/utils/codeMirrorHighlighting.ts
@@ -0,0 +1,19 @@
+import { error as logError } from "../services/logger";
+import { createStaticHighlighter, loadNativeLanguage as loadLanguage } from "./codeMirrorHighlightingCore";
+import type { LanguageId } from "./syntaxHighlighting";
+
+export {
+  createMarkdownSupport,
+  MAX_MARKDOWN_LEVELS,
+  MAX_STATIC_BLOCK_LENGTH,
+  nativeSyntaxHighlighting,
+  resolveFence,
+  resolveFilename,
+  yieldHighlightingTask,
+} from "./codeMirrorHighlightingCore";
+
+export const codeMirrorHighlighting = createStaticHighlighter((...args) => logError(...args));
+
+export function loadNativeLanguage(id: LanguageId) {
+  return loadLanguage(id, logError);
+}
diff --git a/frontend/src/utils/codeMirrorHighlightingCore.ts b/frontend/src/utils/codeMirrorHighlightingCore.ts
new file mode 100644
index 000000000..49964716e
--- /dev/null
+++ b/frontend/src/utils/codeMirrorHighlightingCore.ts
@@ -0,0 +1,316 @@
+import { markdown, markdownLanguage } from "@codemirror/lang-markdown";
+import {
+  HighlightStyle,
+  Language,
+  LanguageDescription,
+  type LanguageSupport,
+  languageDataProp,
+  syntaxHighlighting,
+} from "@codemirror/language";
+import { languages } from "@codemirror/language-data";
+import type { Extension } from "@codemirror/state";
+import { NodeType, Parser, type PartialParse, Tree } from "@lezer/common";
+import { highlightTree, styleTags, type Tag, tags } from "@lezer/highlight";
+import {
+  type HighlightingService,
+  type LanguageId,
+  type LanguageResolution,
+  type PlainTextReason,
+  type PreparedCodeBlock,
+  type SyntaxRange,
+  type TokenCategory,
+  tokenClasses,
+} from "./syntaxHighlighting";
+
+export type SyntaxDiagnosticReporter = (message: string, context?: Record<string, unknown>, component?: string, failure?: Error) => void;
+export const MAX_STATIC_BLOCK_LENGTH = 100_000;
+export const MAX_MARKDOWN_LEVELS = 4;
+const PLAIN_LABELS = new Set(["", "text", "txt", "plaintext", "plain", "none"]);
+const FENCE_ALIASES: Record<string, string> = {
+  js: "javascript",
+  jsx: "jsx",
+  ts: "typescript",
+  tsx: "tsx",
+  py: "python",
+  sh: "shell",
+  bash: "shell",
+  zsh: "shell",
+  yml: "yaml",
+  md: "markdown",
+  html: "html",
+  cs: "c#",
+  csharp: "c#",
+  cpp: "c++",
+  rb: "ruby",
+  rs: "rust",
+  ps1: "powershell",
+  shellsession: "shell",
+  console: "shell",
+  docker: "dockerfile",
+  htm: "html",
+  kt: "kotlin",
+  mssql: "ms sql",
+  mariadb: "mariadb sql",
+};
+const codeRules: { tag: Tag | readonly Tag[]; categories: readonly TokenCategory[] }[] = [
+  { tag: tags.keyword, categories: ["keyword"] },
+  { tag: [tags.string, tags.character], categories: ["string"] },
+  { tag: tags.regexp, categories: ["regexp"] },
+  { tag: tags.escape, categories: ["escape"] },
+  { tag: tags.number, categories: ["number"] },
+  { tag: tags.bool, categories: ["boolean"] },
+  { tag: tags.null, categories: ["null"] },
+  { tag: tags.comment, categories: ["comment"] },
+  { tag: [tags.typeName, tags.className, tags.namespace], categories: ["type"] },
+  { tag: [tags.name, tags.variableName], categories: ["identifier"] },
+  { tag: tags.propertyName, categories: ["property"] },
+  { tag: [tags.function(tags.variableName), tags.function(tags.propertyName)], categories: ["function"] },
+  {
+    tag: [
+      tags.standard(tags.variableName),
+      tags.standard(tags.propertyName),
+      tags.standard(tags.function(tags.variableName)),
+      tags.standard(tags.function(tags.propertyName)),
+    ],
+    categories: ["builtin"],
+  },
+  { tag: tags.meta, categories: ["metadata"] },
+  { tag: tags.operator, categories: ["operator"] },
+  { tag: [tags.punctuation, tags.bracket], categories: ["punctuation"] },
+];
+const markdownRules: typeof codeRules = [
+  { tag: tags.heading, categories: ["heading"] },
+  { tag: [tags.processingInstruction, tags.meta, tags.contentSeparator], categories: ["structure"] },
+  { tag: [tags.link, tags.url, tags.labelName], categories: ["link"] },
+  { tag: tags.monospace, categories: ["inlineCode"] },
+  { tag: tags.emphasis, categories: ["emphasis"] },
+  { tag: tags.strong, categories: ["strong"] },
+  { tag: tags.strikethrough, categories: ["strikethrough"] },
+];
+const toStyle = (rules: typeof codeRules) => rules.map(({ tag, categories }) => ({ tag, class: tokenClasses(categories) }));
+const codeStyle = HighlightStyle.define(toStyle(codeRules));
+const sourceStyle = HighlightStyle.define(toStyle(markdownRules), { scope: markdownLanguage });
+const scopedCodeStyle = {
+  style: codeStyle.style,
+  scope: (node: Parameters<NonNullable<typeof sourceStyle.scope>>[0]) => node.prop(languageDataProp) !== markdownLanguage.data,
+};
+export const nativeSyntaxHighlighting: Extension = [syntaxHighlighting(scopedCodeStyle), syntaxHighlighting(sourceStyle)];
+
+function descriptionForFence(label?: string | null): LanguageDescription | null {
+  const normalized = label?.trim().split(/\s+/)[0]?.toLowerCase() ?? "";
+  if (PLAIN_LABELS.has(normalized)) return null;
+  return LanguageDescription.matchLanguageName(languages, FENCE_ALIASES[normalized] ?? normalized, false);
+}
+function resolution(description: LanguageDescription | null): LanguageResolution {
+  return description ? { language: description.name.toLowerCase() as LanguageId } : { reason: "unknown-language" };
+}
+export function resolveFilename(filename: string): LanguageResolution {
+  return resolution(LanguageDescription.matchFilename(languages, filename));
+}
+export function resolveFence(label?: string | null): LanguageResolution {
+  const normalized = label?.trim().split(/\s+/)[0]?.toLowerCase() ?? "";
+  return PLAIN_LABELS.has(normalized) ? { reason: "plain-text" } : resolution(descriptionForFence(label));
+}
+function getDescription(id: LanguageId): LanguageDescription {
+  const description = languages.find((candidate) => candidate.name.toLowerCase() === id);
+  if (!description) throw new Error(`Unsupported application language: ${id}`);
+  return description;
+}
+export function createMarkdownSupport(
+  codeLanguages: NonNullable<Parameters<typeof markdown>[0]>["codeLanguages"] = descriptionForFence
+): LanguageSupport {
+  return markdown({ base: markdownLanguage, codeLanguages, extensions: [{ props: [styleTags({ CodeText: [], CodeInfo: tags.meta })] }] });
+}
+export async function loadNativeLanguage(id: LanguageId, report: SyntaxDiagnosticReporter): Promise<LanguageSupport> {
+  const description = getDescription(id);
+  try {
+    const support = await description.load();
+    return support.language.name === "markdown" ? createMarkdownSupport() : support;
+  } catch (error) {
+    report(
+      "Syntax language loading failed; using plain text",
+      { language: id, operation: "load" },
+      "syntaxHighlighting",
+      error instanceof Error ? error : undefined
+    );
+    throw error;
+  }
+}
+function checkAbort(signal?: AbortSignal): void {
+  if (signal?.aborted) throw new DOMException("Highlighting cancelled", "AbortError");
+}
+async function abortable<T>(promise: Promise<T>, signal?: AbortSignal): Promise<T> {
+  checkAbort(signal);
+  if (!signal) return promise;
+  return new Promise<T>((resolve, reject) => {
+    const abort = () => reject(new DOMException("Highlighting cancelled", "AbortError"));
+    signal.addEventListener("abort", abort, { once: true });
+    promise.then(resolve, reject).finally(() => signal.removeEventListener("abort", abort));
+  });
+}
+export async function yieldHighlightingTask(signal?: AbortSignal): Promise<void> {
+  checkAbort(signal);
+  const scheduler = (globalThis as typeof globalThis & { scheduler?: { yield(): Promise<void> } }).scheduler;
+  await abortable(scheduler ? scheduler.yield() : new Promise<void>((resolve) => setTimeout(resolve, 0)), signal);
+  checkAbort(signal);
+}
+class PreparationFailure extends Error {
+  constructor(readonly reason: PlainTextReason) {
+    super(reason);
+  }
+}
+function isolateNestedParser(language: Language, id: LanguageId, report: SyntaxDiagnosticReporter, signal?: AbortSignal): Language {
+  const parser = new (class extends Parser {
+    createParse(...args: Parameters<Parser["createParse"]>): PartialParse {
+      const ranges = args[2];
+      const from = ranges[0]?.from ?? 0;
+      const end = ranges.at(-1)?.to ?? from;
+      let partial: PartialParse | undefined;
+      let stoppedAt: number | null = null;
+      const fail = (error: unknown) => {
+        checkAbort(signal);
+        partial = undefined;
+        report(
+          "Nested syntax parsing failed; retaining plain text for this fence",
+          { language: id, operation: "parse" },
+          "syntaxHighlighting",
+          error instanceof Error ? error : undefined
+        );
+      };
+      try {
+        partial = language.parser.startParse(...args);
+      } catch (error) {
+        fail(error);
+      }
+      return {
+        advance() {
+          checkAbort(signal);
+          try {
+            if (partial) return partial.advance();
+          } catch (error) {
+            fail(error);
+          }
+          return new Tree(NodeType.none, [], [], Math.max(0, Math.min(end, stoppedAt ?? end) - from));
+        },
+        get parsedPos() {
+          return partial?.parsedPos ?? Math.min(end, stoppedAt ?? end);
+        },
+        get stoppedAt() {
+          return partial?.stoppedAt ?? stoppedAt;
+        },
+        stopAt(position) {
+          stoppedAt = position;
+          try {
+            partial?.stopAt(position);
+          } catch (error) {
+            fail(error);
+          }
+        },
+      };
+    }
+  })();
+  return new Language(language.data, parser, [], language.name);
+}
+async function prepareLanguage(
+  text: string,
+  id: LanguageId,
+  level: number,
+  preparedLanguages: Map<LanguageId, Language>,
+  report: SyntaxDiagnosticReporter,
+  signal?: AbortSignal
+): Promise<Language> {
+  checkAbort(signal);
+  if (text.length > MAX_STATIC_BLOCK_LENGTH) throw new PreparationFailure("block-too-large");
+  const description = getDescription(id);
+  const isMarkdown = description.name.toLowerCase() === "markdown";
+  if (isMarkdown && level > MAX_MARKDOWN_LEVELS) throw new PreparationFailure("nesting-depth");
+  let support: LanguageSupport;
+  try {
+    support = await abortable(description.load(), signal);
+  } catch (error) {
+    checkAbort(signal);
+    report(
+      "Syntax language loading failed; using plain text",
+      { language: id, operation: "load" },
+      "syntaxHighlighting",
+      error instanceof Error ? error : undefined
+    );
+    throw new PreparationFailure("loading-failure");
+  }
+  checkAbort(signal);
+  if (!isMarkdown) {
+    preparedLanguages.set(id, support.language);
+    return support.language;
+  }
+  const discovery = createMarkdownSupport(() => null);
+  const tree = discovery.language.parser.parse(text);
+  const cursor = tree.cursor();
+  do {
+    if (cursor.name !== "FencedCode") continue;
+    const info = cursor.node.getChild("CodeInfo");
+    const code = cursor.node.getChild("CodeText");
+    if (!info || !code) continue;
+    const nested = resolveFence(text.slice(info.from, info.to));
+    if (!("language" in nested)) continue;
+    await yieldHighlightingTask(signal);
+    try {
+      await prepareLanguage(text.slice(code.from, code.to), nested.language, level + 1, preparedLanguages, report, signal);
+    } catch (error) {
+      checkAbort(signal);
+      if (!(error instanceof PreparationFailure) || error.reason !== "loading-failure") throw error;
+    }
+  } while (cursor.next());
+  checkAbort(signal);
+  const configured = createMarkdownSupport((label) => {
+    const nested = resolveFence(label);
+    if (!("language" in nested)) return null;
+    const language = preparedLanguages.get(nested.language);
+    return language ? isolateNestedParser(language, nested.language, report, signal) : null;
+  }).language;
+  preparedLanguages.set(id, configured);
+  return configured;
+}
+export function createStaticHighlighter(report: SyntaxDiagnosticReporter): HighlightingService {
+  return {
+    resolveFilename,
+    resolveFence,
+    async prepare(blocks, signal) {
+      const results: PreparedCodeBlock[] = [];
+      for (const block of blocks) {
+        await yieldHighlightingTask(signal);
+        if (block.text.length > MAX_STATIC_BLOCK_LENGTH) {
+          results.push({ reason: "block-too-large" });
+          continue;
+        }
+        const resolved = resolveFence(block.label);
+        if (!("language" in resolved)) {
+          results.push(resolved);
+          continue;
+        }
+        try {
+          const language = await prepareLanguage(block.text, resolved.language, 1, new Map(), report, signal);
+          checkAbort(signal);
+          const ranges: SyntaxRange[] = [];
+          highlightTree(language.parser.parse(block.text), [scopedCodeStyle, sourceStyle], (from, to, classes) => {
+            ranges.push({ from, to, categories: classes.split(" ").map((name) => name.slice("sambee-syntax-".length) as TokenCategory) });
+          });
+          results.push({ ranges });
+        } catch (error) {
+          checkAbort(signal);
+          if (error instanceof PreparationFailure) results.push({ reason: error.reason });
+          else {
+            report(
+              "Syntax parsing failed; using plain text",
+              { language: resolved.language, operation: "parse" },
+              "syntaxHighlighting",
+              error instanceof Error ? error : undefined
+            );
+            results.push({ reason: "parsing-failure" });
+          }
+        }
+      }
+      checkAbort(signal);
+      return results;
+    },
+  };
+}
diff --git a/frontend/src/utils/domTextSearch.ts b/frontend/src/utils/domTextSearch.ts
index dbedeb36a..3a0016937 100644
--- a/frontend/src/utils/domTextSearch.ts
+++ b/frontend/src/utils/domTextSearch.ts
@@ -8,18 +8,38 @@ export interface DomTextSearchMatch {
   elements: HTMLElement[];
 }
 
-interface IndexedTextSegment {
+const activeMatches = new WeakMap<DomTextSearchMatch[], DomTextSearchMatch>();
+
+function measureSearchStage<Result>(stage: string, operation: () => Result): Result {
+  const start = performance.now();
+  try {
+    return operation();
+  } finally {
+    const name = `sambee:preview-search:${stage}`;
+    performance.clearMeasures?.(name);
+    performance.measure?.(name, { start, end: performance.now() });
+  }
+}
+
+export interface IndexedTextSegment {
   node: Text;
   start: number;
   end: number;
 }
 
-interface IndexedDomText {
+export interface IndexedDomText {
   fullText: string;
   segments: IndexedTextSegment[];
 }
 
-interface LogicalMatch {
+interface DomTextIndexBuilder {
+  chunks: string[];
+  length: number;
+  lastCharacter: string;
+  segments: IndexedTextSegment[];
+}
+
+export interface LogicalMatch {
   id: number;
   start: number;
   end: number;
@@ -75,42 +95,61 @@ export function clearDomTextSearchHighlights(container: ParentNode | null): void
     return;
   }
 
+  measureSearchStage("clear", () => clearHighlights(container));
+}
+
+function clearHighlights(container: ParentNode): void {
   const highlights = container.querySelectorAll(DOM_TEXT_SEARCH_HIGHLIGHT_SELECTOR);
+  const parents = new Set<Element | Document | DocumentFragment>();
   for (const highlight of highlights) {
     const parent = highlight.parentNode;
-    if (!parent) {
-      continue;
+    if (parent instanceof Element || parent instanceof Document || parent instanceof DocumentFragment) parents.add(parent);
+  }
+  for (const parent of parents) {
+    const fragment = document.createDocumentFragment();
+    let text = "";
+    for (const child of Array.from(parent.childNodes)) {
+      if (child instanceof Text || (child instanceof HTMLElement && child.matches(DOM_TEXT_SEARCH_HIGHLIGHT_SELECTOR))) {
+        text += child.textContent ?? "";
+      } else {
+        if (text) fragment.append(document.createTextNode(text));
+        text = "";
+        fragment.append(child);
+      }
     }
-
-    parent.replaceChild(document.createTextNode(highlight.textContent ?? ""), highlight);
-    parent.normalize();
+    if (text) fragment.append(document.createTextNode(text));
+    parent.replaceChildren(fragment);
   }
 }
 
-function appendBlockSeparator(indexedText: IndexedDomText): void {
-  if (!indexedText.fullText || indexedText.fullText.endsWith("\n")) {
+function appendBlockSeparator(indexedText: DomTextIndexBuilder): void {
+  if (!indexedText.length || indexedText.lastCharacter === "\n") {
     return;
   }
 
-  indexedText.fullText += "\n";
+  indexedText.chunks.push("\n");
+  indexedText.length += 1;
+  indexedText.lastCharacter = "\n";
 }
 
-function indexTextNode(node: Text, indexedText: IndexedDomText): void {
+function indexTextNode(node: Text, indexedText: DomTextIndexBuilder): void {
   const text = node.textContent ?? "";
-  if (!text.trim()) {
+  if (!text || (!text.trim() && !node.parentElement?.closest("pre"))) {
     return;
   }
 
-  const start = indexedText.fullText.length;
-  indexedText.fullText += text;
+  const start = indexedText.length;
+  indexedText.chunks.push(text);
+  indexedText.length += text.length;
+  indexedText.lastCharacter = text.slice(-1);
   indexedText.segments.push({
     node,
     start,
-    end: indexedText.fullText.length,
+    end: indexedText.length,
   });
 }
 
-function buildIndexedDomText(node: Node, indexedText: IndexedDomText, isRoot = false): void {
+function buildIndexedDomText(node: Node, indexedText: DomTextIndexBuilder, isRoot = false): void {
   if (node instanceof Text) {
     if (node.parentElement?.closest(DOM_TEXT_SEARCH_HIGHLIGHT_SELECTOR)) {
       return;
@@ -141,18 +180,20 @@ function buildIndexedDomText(node: Node, indexedText: IndexedDomText, isRoot = f
   }
 }
 
-function createDomTextIndex(container: HTMLElement): IndexedDomText {
-  const indexedText: IndexedDomText = {
-    fullText: "",
+export function createDomTextIndex(container: HTMLElement): IndexedDomText {
+  const indexedText: DomTextIndexBuilder = {
+    chunks: [],
+    length: 0,
+    lastCharacter: "",
     segments: [],
   };
 
   buildIndexedDomText(container, indexedText, true);
 
-  return indexedText;
+  return { fullText: indexedText.chunks.join(""), segments: indexedText.segments };
 }
 
-function findLogicalMatches(fullText: string, query: string): LogicalMatch[] {
+export function findLogicalMatches(fullText: string, query: string): LogicalMatch[] {
   const normalizedQuery = query.trim().toLocaleLowerCase();
   if (!normalizedQuery) {
     return [];
@@ -182,14 +223,19 @@ function findLogicalMatches(fullText: string, query: string): LogicalMatch[] {
   return matches;
 }
 
-function buildHighlightSlices(indexedText: IndexedDomText, matches: LogicalMatch[]): Map<Text, HighlightSlice[]> {
+export function buildHighlightSlices(indexedText: IndexedDomText, matches: LogicalMatch[]): Map<Text, HighlightSlice[]> {
   const slicesByNode = new Map<Text, HighlightSlice[]>();
+  let segmentIndex = 0;
 
   for (const match of matches) {
-    for (const segment of indexedText.segments) {
-      if (segment.end <= match.start || segment.start >= match.end) {
-        continue;
-      }
+    while (segmentIndex < indexedText.segments.length) {
+      const segment = indexedText.segments[segmentIndex];
+      if (!segment || segment.end > match.start) break;
+      segmentIndex += 1;
+    }
+    for (let overlapIndex = segmentIndex; overlapIndex < indexedText.segments.length; overlapIndex += 1) {
+      const segment = indexedText.segments[overlapIndex];
+      if (!segment || segment.start >= match.end) break;
 
       const overlappingStart = Math.max(match.start, segment.start);
       const overlappingEnd = Math.min(match.end, segment.end);
@@ -240,31 +286,29 @@ function applyHighlightSlices(slicesByNode: Map<Text, HighlightSlice[]>, matchCo
 }
 
 export function applyDomTextSearchHighlights(container: HTMLElement, query: string): DomTextSearchMatch[] {
-  const indexedText = createDomTextIndex(container);
-  const matches = findLogicalMatches(indexedText.fullText, query);
+  const indexedText = measureSearchStage("capture", () => createDomTextIndex(container));
+  const matches = measureSearchStage("matching", () => findLogicalMatches(indexedText.fullText, query));
 
   if (matches.length === 0) {
     return [];
   }
 
-  const slicesByNode = buildHighlightSlices(indexedText, matches);
-  return applyHighlightSlices(slicesByNode, matches.length);
+  const slicesByNode = measureSearchStage("slices", () => buildHighlightSlices(indexedText, matches));
+  return measureSearchStage("markers", () => applyHighlightSlices(slicesByNode, matches.length));
 }
 
-export function activateDomTextSearchMatch(matches: DomTextSearchMatch[], currentMatch: number): HTMLElement | null {
-  for (const [index, match] of matches.entries()) {
-    const isCurrentMatch = index === currentMatch - 1;
-    for (const highlight of match.elements) {
-      if (isCurrentMatch) {
-        highlight.setAttribute(DOM_TEXT_SEARCH_CURRENT_MATCH_ATTRIBUTE, "true");
-      } else {
-        highlight.removeAttribute(DOM_TEXT_SEARCH_CURRENT_MATCH_ATTRIBUTE);
-      }
-    }
+export function activateDomTextSearchMatch(matches: DomTextSearchMatch[], currentMatch: number, scroll = true): HTMLElement | null {
+  const previous = activeMatches.get(matches);
+  const current = currentMatch > 0 ? matches[currentMatch - 1] : undefined;
+  if (previous !== current) {
+    for (const highlight of previous?.elements ?? []) highlight.removeAttribute(DOM_TEXT_SEARCH_CURRENT_MATCH_ATTRIBUTE);
+    for (const highlight of current?.elements ?? []) highlight.setAttribute(DOM_TEXT_SEARCH_CURRENT_MATCH_ATTRIBUTE, "true");
+    if (current) activeMatches.set(matches, current);
+    else activeMatches.delete(matches);
   }
 
-  const activeHighlight = currentMatch > 0 ? (matches[currentMatch - 1]?.elements[0] ?? null) : null;
-  if (activeHighlight && typeof activeHighlight.scrollIntoView === "function") {
+  const activeHighlight = current?.elements[0] ?? null;
+  if (scroll && activeHighlight && typeof activeHighlight.scrollIntoView === "function") {
     activeHighlight.scrollIntoView({ block: "center", inline: "nearest" });
   }
 
diff --git a/frontend/src/utils/highlightingService.ts b/frontend/src/utils/highlightingService.ts
new file mode 100644
index 000000000..d0651f042
--- /dev/null
+++ b/frontend/src/utils/highlightingService.ts
@@ -0,0 +1,4 @@
+import { codeMirrorHighlighting } from "./codeMirrorHighlighting";
+import type { HighlightingService } from "./syntaxHighlighting";
+
+export const highlightingService: HighlightingService = codeMirrorHighlighting;
diff --git a/frontend/src/utils/markdownCodePreparation.ts b/frontend/src/utils/markdownCodePreparation.ts
new file mode 100644
index 000000000..d9e55618e
--- /dev/null
+++ b/frontend/src/utils/markdownCodePreparation.ts
@@ -0,0 +1,398 @@
+import type { Root } from "mdast";
+import { normalizeMarkdownTableCellLineBreaks } from "../components/Viewer/markdownTableCellLineBreaks";
+import { error as logError, info as logInfo } from "../services/logger";
+import {
+  PREPARATION_SOURCE_CHUNK_UNITS,
+  type PreparationRequest,
+  type PreparationResponse,
+  WORKER_PROGRESS_TIMEOUT_MS,
+} from "./markdownCodePreparationProtocol";
+import { createMarkdownTreeReceiver } from "./markdownPreparedTree";
+
+export {
+  PREPARATION_SOURCE_CHUNK_UNITS,
+  type PreparationRequest,
+  type PreparationResponse,
+  WORKER_PROGRESS_TIMEOUT_MS,
+} from "./markdownCodePreparationProtocol";
+
+const NORMALIZATION_GENERATION = 0;
+const EDIT_PREPARATION_PREFIX = "sambee:edit-preparation";
+
+function measureEditPreparation(stage: string, start: number, detail: Record<string, number | boolean | null>): void {
+  const name = `${EDIT_PREPARATION_PREFIX}:${stage}`;
+  performance.clearMeasures(name);
+  performance.measure(name, { start, detail });
+}
+
+export interface MarkdownEditNormalizationSnapshot {
+  readonly generation: number;
+  readonly source: string;
+  readonly baseline?: string;
+  readonly preserveOnly?: boolean;
+  readonly normalizedSource: string;
+}
+
+export function createMarkdownEditNormalization(
+  onDiagnostic: (diagnostic: Extract<PreparationResponse, { type: "diagnostic" }>) => void,
+  onNormalized?: (snapshot: MarkdownEditNormalizationSnapshot) => void,
+  onFailure?: (error: Error) => void
+) {
+  type Request = { generation: number; source: string; baseline?: string; preserveOnly?: boolean; requestedAt: number };
+  type Job = { controller: AbortController; done: Promise<void> };
+  let generation = NORMALIZATION_GENERATION;
+  let latest: Request | null = null;
+  let pending: Request | null = null;
+  let active: Job | null = null;
+  let snapshot: MarkdownEditNormalizationSnapshot | null = null;
+  let failure: Error | null = null;
+  let disposed = false;
+
+  const assertLive = () => {
+    if (disposed) throw new DOMException("Markdown edit normalization was disposed", "AbortError");
+  };
+
+  const startPending = () => {
+    if (disposed || active || !pending) return;
+    const request = pending;
+    pending = null;
+    const startedAt = performance.now();
+    const detail = {
+      generation: request.generation,
+      sourceUnits: request.source.length,
+      baselineUnits: request.baseline?.length ?? 0,
+      preserveOnly: request.preserveOnly === true,
+    };
+    measureEditPreparation("queue", request.requestedAt, detail);
+    const controller = new AbortController();
+    const job: Job = { controller, done: Promise.resolve() };
+    active = job;
+    job.done = (async () => {
+      try {
+        const result = await prepareCodePreviewInWorker(
+          [request.source],
+          request.generation,
+          controller.signal,
+          (diagnostic) => {
+            if (!disposed && latest === request) onDiagnostic(diagnostic);
+          },
+          { preserveTableSource: request.baseline, preserveOnly: request.preserveOnly }
+        );
+        if (!disposed && latest === request) {
+          const { requestedAt: _requestedAt, ...identity } = request;
+          snapshot = Object.freeze({ ...identity, normalizedSource: result.normalizedSource });
+          onNormalized?.(snapshot);
+        }
+      } catch (error) {
+        if (!disposed && latest === request) {
+          failure = error instanceof Error ? error : new Error(String(error));
+          onFailure?.(failure);
+        }
+      } finally {
+        measureEditPreparation("job", startedAt, { ...detail, current: latest === request, disposed });
+        active = null;
+        startPending();
+      }
+    })();
+  };
+
+  const captureSnapshotSync = (): MarkdownEditNormalizationSnapshot => {
+    assertLive();
+    if (failure) throw failure;
+    if (!snapshot || snapshot.generation !== latest?.generation) {
+      throw new DOMException(
+        "Markdown normalization has not finished publishing. Retry after the current edit finishes.",
+        "InvalidStateError"
+      );
+    }
+    return snapshot;
+  };
+
+  return {
+    request(source: string, baseline?: string, preserveOnly = false): number {
+      assertLive();
+      latest = {
+        source,
+        generation: ++generation,
+        requestedAt: performance.now(),
+        ...(baseline === undefined ? {} : { baseline }),
+        ...(preserveOnly ? { preserveOnly } : {}),
+      };
+      pending = latest;
+      snapshot = null;
+      failure = null;
+      startPending();
+      return generation;
+    },
+    captureSnapshotSync,
+    async flush(signal?: AbortSignal): Promise<MarkdownEditNormalizationSnapshot> {
+      signal?.throwIfAborted();
+      assertLive();
+      while (active) {
+        const completion = active.done;
+        if (!signal) await completion;
+        else {
+          await new Promise<void>((resolve, reject) => {
+            const abort = () => {
+              signal.removeEventListener("abort", abort);
+              reject(signal.reason);
+            };
+            signal.addEventListener("abort", abort, { once: true });
+            void completion.then(() => {
+              signal.removeEventListener("abort", abort);
+              resolve();
+            });
+          });
+        }
+        signal?.throwIfAborted();
+        assertLive();
+      }
+      return captureSnapshotSync();
+    },
+    dispose(): void {
+      if (disposed) return;
+      disposed = true;
+      latest = null;
+      pending = null;
+      snapshot = null;
+      failure = null;
+      active?.controller.abort();
+    },
+  };
+}
+
+export async function normalizeMarkdownSource(source: string, signal: AbortSignal, onPrepared?: (tree: Root) => void): Promise<string> {
+  signal.throwIfAborted();
+  if (typeof Worker === "undefined") {
+    logInfo(
+      "Web Workers are unavailable; Markdown load normalization will run on the main thread",
+      { operation: "normalize" },
+      "MarkdownViewer"
+    );
+    return normalizeMarkdownTableCellLineBreaks(source, onPrepared ? (_source, tree) => onPrepared(tree) : undefined);
+  }
+  const result = await prepareCodePreviewInWorker(
+    [source],
+    NORMALIZATION_GENERATION,
+    signal,
+    (diagnostic) => {
+      logError(
+        diagnostic.message,
+        diagnostic.context,
+        diagnostic.component,
+        diagnostic.error ? new Error(diagnostic.error.message) : undefined
+      );
+    },
+    { prepareTree: Boolean(onPrepared) }
+  );
+  signal.throwIfAborted();
+  if (onPrepared) {
+    if (!result.preparedTree) throw new Error("Markdown normalization worker returned no canonical tree");
+    onPrepared(result.preparedTree);
+  }
+  return result.normalizedSource;
+}
+
+export function prepareCodePreviewInWorker(
+  blocks: readonly string[],
+  generation: number,
+  signal: AbortSignal,
+  onDiagnostic: (diagnostic: Extract<PreparationResponse, { type: "diagnostic" }>) => void,
+  options: { prepareTree?: boolean; preserveTableSource?: string; preserveOnly?: boolean } = {}
+): Promise<{ normalizedSource: string; preparedTree?: Root; preparationMs: number }> {
+  if (signal.aborted) return Promise.reject(new DOMException("Preparation cancelled", "AbortError"));
+  const initialSource = blocks[0];
+  if (blocks.length !== 1 || initialSource === undefined)
+    return Promise.reject(new Error("Markdown normalization requires one source document"));
+  if (options.prepareTree && options.preserveTableSource !== undefined)
+    return Promise.reject(new Error("Source-preserving edit preparation cannot also prepare a preview tree"));
+  if (options.preserveOnly && options.preserveTableSource === undefined)
+    return Promise.reject(new Error("Source-preservation-only preparation requires a baseline"));
+  if (typeof Worker === "undefined")
+    return Promise.reject(new Error("Worker preparation is unavailable; no main-thread fallback was used"));
+  return new Promise((resolve, reject) => {
+    const startedAt = performance.now();
+    let current: Worker;
+    try {
+      current = new Worker(new URL("./markdownCodePreparation.worker.ts", import.meta.url), { type: "module" });
+    } catch (error) {
+      reject(error);
+      return;
+    }
+    const sources = options.preserveTableSource === undefined ? [initialSource] : [initialSource, options.preserveTableSource];
+    const measured = options.preserveTableSource !== undefined;
+    const detail = {
+      generation,
+      sourceUnits: initialSource.length,
+      baselineUnits: options.preserveTableSource?.length ?? 0,
+      preserveOnly: options.preserveOnly === true,
+    };
+    let transferStartedAt = startedAt;
+    let runAt = startedAt;
+    let resultStartedAt: number | undefined;
+    let sourceBlock = 0;
+    let sourceOffset = 0;
+    let sourceSequence = 0;
+    let sourceFinal = false;
+    let sourceComplete = false;
+    const normalizedParts: string[] = [];
+    let normalizedFinal = false;
+    const treeReceiver = options.prepareTree ? createMarkdownTreeReceiver() : null;
+    let treeFinal = false;
+    let treeSequence = 0;
+    let treeDelivery: ReturnType<typeof setTimeout> | undefined;
+    let settled = false;
+    let watchdog: ReturnType<typeof setTimeout>;
+    const cleanup = () => {
+      clearTimeout(watchdog);
+      clearTimeout(treeDelivery);
+      signal.removeEventListener("abort", abort);
+      current.onmessage = null;
+      current.onerror = null;
+      current.removeEventListener("messageerror", decodeFailure);
+      current.terminate();
+    };
+    const fail = (error: unknown) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      reject(error);
+    };
+    const abort = () => fail(new DOMException("Worker preparation cancelled", "AbortError"));
+    const armWatchdog = () => {
+      clearTimeout(watchdog);
+      watchdog = setTimeout(() => fail(new Error("Worker preparation made no progress before its timeout")), WORKER_PROGRESS_TIMEOUT_MS);
+    };
+    signal.addEventListener("abort", abort, { once: true });
+    current.onerror = (event) => {
+      event.preventDefault();
+      fail(new Error(`Worker preparation failed: ${event.message} at ${event.filename}:${event.lineno}:${event.colno}`));
+    };
+    const decodeFailure = () => fail(new Error("Worker preparation result could not be decoded"));
+    current.addEventListener("messageerror", decodeFailure);
+    current.onmessage = (event: MessageEvent<PreparationResponse>) => {
+      if (settled || event.data.generation !== generation) return;
+      const response = event.data;
+      try {
+        armWatchdog();
+        if (response.type === "tree-chunk") {
+          if (
+            !treeReceiver ||
+            !normalizedFinal ||
+            treeFinal ||
+            response.sequence !== treeSequence + 1 ||
+            typeof response.final !== "boolean"
+          )
+            throw new Error("Invalid canonical Markdown tree sequence");
+          treeReceiver.consume(response.records);
+          treeSequence = response.sequence;
+          treeFinal = response.final;
+          treeDelivery = setTimeout(() => {
+            if (!settled) {
+              try {
+                current.postMessage({ type: "ack", generation } satisfies PreparationRequest);
+              } catch (error) {
+                fail(error);
+              }
+            }
+          }, 0);
+          return;
+        }
+        if (response.type === "normalized-source") {
+          if (
+            !sourceComplete ||
+            normalizedFinal ||
+            response.sequence !== normalizedParts.length + 1 ||
+            typeof response.text !== "string" ||
+            response.text.length > PREPARATION_SOURCE_CHUNK_UNITS ||
+            typeof response.final !== "boolean" ||
+            (!response.final && !response.text.length)
+          )
+            throw new Error("Invalid normalized Markdown source chunk");
+          if (resultStartedAt === undefined) {
+            resultStartedAt = performance.now();
+            if (measured) measureEditPreparation("run-to-result", runAt, detail);
+          }
+          normalizedParts.push(response.text);
+          normalizedFinal = response.final;
+          current.postMessage({ type: "ack", generation } satisfies PreparationRequest);
+          return;
+        }
+        if (response.type === "source-ack") {
+          if (sourceComplete || response.sequence !== sourceSequence) throw new Error("Invalid source acknowledgement");
+          if (response.sequence === 0) {
+            if (measured) measureEditPreparation("startup", startedAt, detail);
+            transferStartedAt = performance.now();
+          }
+          if (sourceFinal) {
+            if (measured) measureEditPreparation(sourceBlock === 0 ? "source-transfer" : "baseline-transfer", transferStartedAt, detail);
+            if (sourceBlock === sources.length - 1) {
+              sourceComplete = true;
+              runAt = performance.now();
+              current.postMessage({ type: "run", generation } satisfies PreparationRequest);
+              return;
+            }
+            sourceBlock += 1;
+            sourceOffset = 0;
+            transferStartedAt = performance.now();
+          }
+          const source = sources[sourceBlock];
+          if (source === undefined) throw new Error("Markdown worker requested an unavailable source block");
+          const text = source.slice(sourceOffset, sourceOffset + PREPARATION_SOURCE_CHUNK_UNITS);
+          sourceOffset += text.length;
+          sourceFinal = sourceOffset === source.length;
+          sourceSequence += 1;
+          current.postMessage({
+            type: "source",
+            generation,
+            sequence: sourceSequence,
+            block: sourceBlock,
+            text,
+            final: sourceFinal,
+          } satisfies PreparationRequest);
+          return;
+        }
+        if (response.type === "diagnostic") {
+          onDiagnostic(response);
+          return;
+        }
+        if (response.type === "error") {
+          fail(new Error(response.message));
+          return;
+        }
+        if (response.type !== "complete") throw new Error("Unexpected preparation response");
+        if (!normalizedFinal) throw new Error("Markdown normalization completed before its final source chunk");
+        if (treeReceiver && !treeFinal) throw new Error("Markdown normalization completed before its final tree chunk");
+        const preparedTree = treeReceiver?.finish();
+        if (measured) {
+          if (resultStartedAt !== undefined) measureEditPreparation("result-delivery", resultStartedAt, detail);
+          measureEditPreparation("transport", startedAt, {
+            ...detail,
+            sourceChunks: sourceSequence,
+            resultChunks: normalizedParts.length,
+            workerPreparationMs: response.preparationMs,
+            workerNormalizationMs: response.normalizationMs ?? null,
+            workerPreservationMs: response.preservationMs ?? null,
+          });
+        }
+        settled = true;
+        cleanup();
+        resolve({ normalizedSource: normalizedParts.join(""), preparedTree, preparationMs: response.preparationMs });
+      } catch (error) {
+        fail(error);
+      }
+    };
+    armWatchdog();
+    try {
+      current.postMessage({
+        type: "prepare",
+        generation,
+        prepareTree: options.prepareTree,
+        ...(options.preserveTableSource === undefined ? {} : { preserveTableSource: true }),
+        ...(options.preserveOnly ? { preserveOnly: true } : {}),
+      } satisfies PreparationRequest);
+    } catch (error) {
+      fail(error);
+    }
+  });
+}
diff --git a/frontend/src/utils/markdownCodePreparation.worker.ts b/frontend/src/utils/markdownCodePreparation.worker.ts
new file mode 100644
index 000000000..7861fdf8f
--- /dev/null
+++ b/frontend/src/utils/markdownCodePreparation.worker.ts
@@ -0,0 +1,160 @@
+import type { Root } from "mdast";
+import {
+  normalizeMarkdownTableCellLineBreaks,
+  preserveUnchangedMarkdownTableSource,
+} from "../components/Viewer/markdownTableCellLineBreaks";
+import { PREPARATION_SOURCE_CHUNK_UNITS, type PreparationRequest, type PreparationResponse } from "./markdownCodePreparationProtocol";
+import {
+  MARKDOWN_TREE_BATCH_RECORDS,
+  MARKDOWN_TREE_BATCH_UNITS,
+  type MarkdownTreeRecord,
+  markdownTreeRecords,
+} from "./markdownPreparedTree";
+
+let acknowledge: (() => void) | null = null;
+let activeGeneration: number | null = null;
+let sourceParts: string[] = [];
+let baselineParts: string[] = [];
+let sourceBlock = 0;
+let sourceSequence = 0;
+let sourceFinal = false;
+let running = false;
+let prepareTree = false;
+let preserveTableSource = false;
+let preserveOnly = false;
+
+function send(response: PreparationResponse): void {
+  postMessage(response);
+}
+
+async function normalizeSource(source: string, generation: number, baseline?: string): Promise<void> {
+  const start = performance.now();
+  let tree: Root | undefined;
+  const normalized = preserveOnly
+    ? source
+    : normalizeMarkdownTableCellLineBreaks(
+        source,
+        prepareTree
+          ? (_source, parsed) => {
+              tree = parsed;
+            }
+          : undefined
+      );
+  const normalizedAt = performance.now();
+  const text = baseline === undefined ? normalized : preserveUnchangedMarkdownTableSource(baseline, normalized);
+  const preparedAt = performance.now();
+  const normalizationMs = normalizedAt - start;
+  const preservationMs = preparedAt - normalizedAt;
+  const preparationMs = preparedAt - start;
+  let sequence = 0;
+  for (let offset = 0; offset < Math.max(1, text.length); offset += PREPARATION_SOURCE_CHUNK_UNITS) {
+    const chunk = text.slice(offset, offset + PREPARATION_SOURCE_CHUNK_UNITS);
+    await new Promise<void>((resolve) => {
+      acknowledge = resolve;
+      send({ type: "normalized-source", generation, sequence: ++sequence, text: chunk, final: offset + chunk.length === text.length });
+    });
+  }
+  if (tree) {
+    let records: MarkdownTreeRecord[] = [];
+    let units = 0;
+    let treeSequence = 0;
+    const flush = async (final: boolean) => {
+      const batch = records;
+      records = [];
+      units = 0;
+      await new Promise<void>((resolve) => {
+        acknowledge = resolve;
+        send({ type: "tree-chunk", generation, sequence: ++treeSequence, records: batch, final });
+      });
+    };
+    for (const record of markdownTreeRecords(tree)) {
+      const size = record.kind === "text" ? record.value.length : String(record.node["type"]).length;
+      if (records.length === MARKDOWN_TREE_BATCH_RECORDS || units + size > MARKDOWN_TREE_BATCH_UNITS) await flush(false);
+      records.push(record);
+      units += size;
+    }
+    await flush(true);
+  }
+  send({ type: "complete", generation, preparationMs, normalizationMs, preservationMs });
+}
+
+globalThis.onmessage = (event: MessageEvent<PreparationRequest>) => {
+  const request = event.data;
+  if (request.type === "prepare") {
+    if (
+      activeGeneration !== null ||
+      !Number.isSafeInteger(request.generation) ||
+      (request.prepareTree && request.preserveTableSource) ||
+      (request.preserveOnly && !request.preserveTableSource)
+    ) {
+      send({ type: "error", generation: request.generation, message: "Preparation worker received an invalid or overlapping job" });
+      return;
+    }
+    activeGeneration = request.generation;
+    prepareTree = request.prepareTree === true;
+    preserveTableSource = request.preserveTableSource === true;
+    preserveOnly = request.preserveOnly === true;
+    sourceParts = [];
+    baselineParts = [];
+    sourceBlock = 0;
+    sourceSequence = 0;
+    sourceFinal = false;
+    running = false;
+    send({ type: "source-ack", generation: request.generation, sequence: sourceSequence });
+    return;
+  }
+  if (request.generation !== activeGeneration) return;
+  if (request.type === "ack") {
+    const resume = acknowledge;
+    acknowledge = null;
+    resume?.();
+    return;
+  }
+  if (request.type === "source") {
+    if (
+      running ||
+      (sourceFinal && (!preserveTableSource || sourceBlock !== 0)) ||
+      request.sequence !== sourceSequence + 1 ||
+      request.block !== sourceBlock + (sourceFinal ? 1 : 0) ||
+      typeof request.text !== "string" ||
+      request.text.length > PREPARATION_SOURCE_CHUNK_UNITS ||
+      typeof request.final !== "boolean" ||
+      (!request.final && request.text.length === 0)
+    ) {
+      send({ type: "error", generation: request.generation, message: "Preparation worker received an invalid source chunk" });
+      return;
+    }
+    sourceBlock = request.block;
+    (sourceBlock === 0 ? sourceParts : baselineParts).push(request.text);
+    sourceFinal = request.final;
+    sourceSequence = request.sequence;
+    send({ type: "source-ack", generation: request.generation, sequence: sourceSequence });
+    return;
+  }
+  if (request.type !== "run" || running || !sourceFinal || sourceBlock !== (preserveTableSource ? 1 : 0)) {
+    send({ type: "error", generation: request.generation, message: "Preparation worker cannot run before source transfer completes" });
+    return;
+  }
+  running = true;
+  const source = sourceParts.join("");
+  const baseline = preserveTableSource ? baselineParts.join("") : undefined;
+  sourceParts = [];
+  baselineParts = [];
+  void normalizeSource(source, request.generation, baseline)
+    .catch((error: unknown) => {
+      send({
+        type: "error",
+        generation: request.generation,
+        message: error instanceof Error ? error.message : "Worker preparation failed",
+      });
+    })
+    .finally(() => {
+      acknowledge = null;
+      activeGeneration = null;
+      sourceParts = [];
+      baselineParts = [];
+      sourceBlock = 0;
+      sourceFinal = false;
+      running = false;
+    });
+};
diff --git a/frontend/src/utils/markdownCodePreparationProtocol.ts b/frontend/src/utils/markdownCodePreparationProtocol.ts
new file mode 100644
index 000000000..6ebbc4ec6
--- /dev/null
+++ b/frontend/src/utils/markdownCodePreparationProtocol.ts
@@ -0,0 +1,25 @@
+import type { MarkdownTreeRecord } from "./markdownPreparedTree";
+
+export const PREPARATION_SOURCE_CHUNK_UNITS = 16_384;
+export const WORKER_PROGRESS_TIMEOUT_MS = 30_000;
+
+export type PreparationRequest =
+  | { type: "prepare"; generation: number; prepareTree?: boolean; preserveTableSource?: boolean; preserveOnly?: boolean }
+  | { type: "source"; generation: number; sequence: number; block: number; text: string; final: boolean }
+  | { type: "run"; generation: number }
+  | { type: "ack"; generation: number };
+
+export type PreparationResponse =
+  | { type: "normalized-source"; generation: number; sequence: number; text: string; final: boolean }
+  | { type: "tree-chunk"; generation: number; sequence: number; records: MarkdownTreeRecord[]; final: boolean }
+  | { type: "source-ack"; generation: number; sequence: number }
+  | {
+      type: "diagnostic";
+      generation: number;
+      message: string;
+      context?: Record<string, unknown>;
+      component?: string;
+      error?: { message: string; name: string };
+    }
+  | { type: "complete"; generation: number; preparationMs: number; normalizationMs?: number; preservationMs?: number }
+  | { type: "error"; generation: number; message: string };
diff --git a/frontend/src/utils/markdownCodePreviewModel.ts b/frontend/src/utils/markdownCodePreviewModel.ts
new file mode 100644
index 000000000..99483af46
--- /dev/null
+++ b/frontend/src/utils/markdownCodePreviewModel.ts
@@ -0,0 +1,126 @@
+import type { SyntaxRange } from "./syntaxHighlighting";
+
+export const CODE_PREVIEW_FRAGMENT_MAX_UNITS = 2_048;
+export const CODE_PREVIEW_FRAGMENT_MAX_LINES = 16;
+export const CODE_PREVIEW_SCAN_MAX_UNITS = 16_384;
+export const CODE_PREVIEW_STEP_MAX_OPERATIONS = 512;
+
+export interface CodePreviewFragment {
+  from: number;
+  to: number;
+  firstRange: number;
+  rangeEnd: number;
+  oversizedLine: boolean;
+}
+
+export interface CodePreviewModel {
+  text: string;
+  ranges: readonly SyntaxRange[];
+  fragments: readonly CodePreviewFragment[];
+}
+
+/** Code-only P1 prototype; oversized lines require a separate horizontal layout strategy. */
+export function createCodePreviewModel(text: string, ranges: readonly SyntaxRange[]): CodePreviewModel {
+  const steps = codePreviewModelSteps(text, ranges);
+  let step = steps.next();
+  while (!step.done) step = steps.next();
+  return step.value;
+}
+
+export async function createCodePreviewModelAsync(
+  text: string,
+  ranges: readonly SyntaxRange[],
+  options: { yieldTask: () => Promise<void>; signal?: AbortSignal }
+): Promise<CodePreviewModel> {
+  options.signal?.throwIfAborted();
+  const steps = codePreviewModelSteps(text, ranges);
+  let step = steps.next();
+  while (!step.done) {
+    await options.yieldTask();
+    options.signal?.throwIfAborted();
+    step = steps.next();
+  }
+  return step.value;
+}
+
+function* codePreviewModelSteps(text: string, ranges: readonly SyntaxRange[]): Generator<void, CodePreviewModel> {
+  let operations = 0;
+  let scannedUnits = 0;
+  const checkpoint = (units = 0): boolean => {
+    operations += 1;
+    scannedUnits += units;
+    if (operations < CODE_PREVIEW_STEP_MAX_OPERATIONS && scannedUnits < CODE_PREVIEW_SCAN_MAX_UNITS) return false;
+    operations = 0;
+    scannedUnits = 0;
+    return true;
+  };
+  let previousEnd = 0;
+  for (const range of ranges) {
+    if (
+      !Number.isInteger(range.from) ||
+      !Number.isInteger(range.to) ||
+      range.from < previousEnd ||
+      range.to <= range.from ||
+      range.to > text.length
+    ) {
+      throw new RangeError("Code preview requires ordered, non-overlapping, in-bounds token ranges");
+    }
+    previousEnd = range.to;
+    if (checkpoint()) yield;
+  }
+
+  const fragments: CodePreviewFragment[] = [];
+  let from = 0;
+  let lineStart = 0;
+  let lines = 0;
+  let firstRange = 0;
+  let rangeEnd = 0;
+  function* append(to: number, oversizedLine = false): Generator<void, void> {
+    while (firstRange < ranges.length && ranges[firstRange]!.to <= from) {
+      firstRange += 1;
+      if (checkpoint()) yield;
+    }
+    rangeEnd = Math.max(firstRange, rangeEnd);
+    while (rangeEnd < ranges.length && ranges[rangeEnd]!.from < to) {
+      rangeEnd += 1;
+      if (checkpoint()) yield;
+    }
+    fragments.push({ from, to, firstRange, rangeEnd, oversizedLine });
+    from = to;
+    lines = 0;
+    if (checkpoint()) yield;
+  }
+
+  let scanPosition = 0;
+  while (lineStart < text.length) {
+    const scanEnd = Math.min(text.length, scanPosition + CODE_PREVIEW_SCAN_MAX_UNITS - scannedUnits);
+    const newline = text.slice(scanPosition, scanEnd).indexOf("\n");
+    const lineEnd = newline === -1 ? scanEnd : scanPosition + newline + 1;
+    if (checkpoint(lineEnd - scanPosition)) yield;
+    scanPosition = lineEnd;
+    if (newline === -1 && scanEnd < text.length) continue;
+    if (lineEnd - lineStart > CODE_PREVIEW_FRAGMENT_MAX_UNITS) {
+      if (from < lineStart) yield* append(lineStart);
+      yield* append(lineEnd, true);
+    } else {
+      if (lineEnd - from > CODE_PREVIEW_FRAGMENT_MAX_UNITS) yield* append(lineStart);
+      lines += 1;
+      if (lines === CODE_PREVIEW_FRAGMENT_MAX_LINES) yield* append(lineEnd);
+    }
+    lineStart = lineEnd;
+  }
+  if (from < text.length) yield* append(text.length);
+  return { text, ranges, fragments };
+}
+
+export function findCodePreviewFragment(model: CodePreviewModel, offset: number): number | null {
+  if (!Number.isInteger(offset) || offset < 0 || offset >= model.text.length) return null;
+  let low = 0;
+  let high = model.fragments.length;
+  while (low < high) {
+    const middle = low + Math.floor((high - low) / 2);
+    if (model.fragments[middle]!.to <= offset) low = middle + 1;
+    else high = middle;
+  }
+  return low;
+}
diff --git a/frontend/src/utils/markdownDocumentPreview.tsx b/frontend/src/utils/markdownDocumentPreview.tsx
new file mode 100644
index 000000000..8d9dbc1da
--- /dev/null
+++ b/frontend/src/utils/markdownDocumentPreview.tsx
@@ -0,0 +1,612 @@
+import { useLayoutEffect, useRef } from "react";
+import type { Root } from "react-dom/client";
+import ReactMarkdown, { defaultUrlTransform } from "react-markdown";
+import remarkGfm from "remark-gfm";
+import {
+  normalizeMarkdownTableCellLineBreaks,
+  remarkRenderMarkdownTableCellLineBreaks,
+} from "../components/Viewer/markdownTableCellLineBreaks";
+import { yieldHighlightingTask } from "./codeMirrorHighlighting";
+import {
+  DOCUMENT_PUBLICATION_BATCH_ITEMS,
+  DOCUMENT_PUBLICATION_BATCH_UNITS,
+  DOCUMENT_RECORD_BATCH_ITEMS,
+  DOCUMENT_SYNTAX_CACHE_RANGES,
+  DOCUMENT_SYNTAX_WINDOW_PARTS,
+  type DocumentSyntaxWindow,
+  type MarkdownDocumentRecord,
+} from "./markdownDocumentPreviewModel";
+import { DocumentSearchIndexer, type DocumentSearchOptions } from "./markdownDocumentSearch";
+import { createDocumentSearchSession, type DocumentMatch, type DocumentSearchResult } from "./markdownDocumentSearchWorker";
+import { visibleSyntaxColumnWindows } from "./markdownSyntaxPublication";
+import { type SyntaxRange, TOKEN_CATEGORIES } from "./syntaxHighlighting";
+
+const MAX_DECORATION_RANGES = 4_000;
+const PUBLICATION_BATCHES_PER_FRAME = 8;
+const PUBLICATION_ASSEMBLY_BUDGET_MS = 4;
+const ALLOWED_TAGS = new Set(
+  "a blockquote br code del div em h1 h2 h3 h4 h5 h6 hr img input li ol p pre section span strong sup table tbody td th thead tr ul".split(
+    " "
+  )
+);
+
+interface DocumentSyntaxSession {
+  dispose(): void;
+  page(
+    window: DocumentSyntaxWindow,
+    offset: number
+  ): Promise<{
+    records: Extract<MarkdownDocumentRecord, { kind: "syntax" }>[];
+    next: number | null;
+  }>;
+}
+
+interface DocumentView {
+  search: (query: string, options?: DocumentSearchOptions) => Promise<DocumentSearchResult>;
+  jump: (ordinal: number) => Promise<{ pending: boolean }>;
+  consume: (records: readonly MarkdownDocumentRecord[]) => Promise<void>;
+  finish: (workerPipelineWallMs: number, syntaxRanges: number, session: DocumentSyntaxSession) => void;
+  dispose: () => void;
+  stats: () => Record<string, unknown>;
+}
+
+async function yieldDocumentPublication(signal: AbortSignal): Promise<void> {
+  signal.throwIfAborted();
+  if (document.hidden) return yieldHighlightingTask(signal);
+  await new Promise<void>((resolve, reject) => {
+    const cleanup = () => {
+      cancelAnimationFrame(frame);
+      signal.removeEventListener("abort", abort);
+      document.removeEventListener("visibilitychange", visibility);
+    };
+    const complete = () => {
+      cleanup();
+      resolve();
+    };
+    const abort = () => {
+      cleanup();
+      reject(signal.reason);
+    };
+    const visibility = () => {
+      if (document.hidden) complete();
+    };
+    const frame = requestAnimationFrame(complete);
+    signal.addEventListener("abort", abort, { once: true });
+    document.addEventListener("visibilitychange", visibility);
+  });
+}
+
+function DocumentHost({ ready }: { ready: (element: HTMLDivElement) => (() => void) | undefined }) {
+  const ref = useRef<HTMLDivElement>(null);
+  useLayoutEffect(() => (ref.current ? ready(ref.current) : undefined), [ready]);
+  return <div ref={ref} data-markdown-document className="document-proof" style={{ height: 480, overflow: "auto" }} />;
+}
+
+export function mountMarkdownDocument(
+  root: Root | HTMLDivElement,
+  signal: AbortSignal,
+  source: string,
+  options: {
+    hostSearch?: boolean;
+    viewport?: HTMLElement;
+    highlightPrefix?: string;
+    configureLink?: (anchor: HTMLAnchorElement, href: string) => void;
+  } = {}
+): Promise<DocumentView> {
+  signal.throwIfAborted();
+  const highlightPrefix = options.highlightPrefix ?? "document";
+  const searchSession = createDocumentSearchSession(source);
+  return new Promise((resolve, reject) => {
+    const abort = () => {
+      searchSession.dispose();
+      reject(signal.reason);
+    };
+    signal.addEventListener("abort", abort, { once: true });
+    const ready = (container: HTMLDivElement) => {
+      signal.removeEventListener("abort", abort);
+      if (signal.aborted) {
+        reject(signal.reason);
+        return;
+      }
+      const started = performance.now();
+      let assemblyMs = 0;
+      let largestAssemblyMs = 0;
+      let frameWaitMs = 0;
+      let viewportPaintMs = 0;
+      let largestViewportPaintMs = 0;
+      let publicationRecords = 0;
+      let largestBatchUnits = 0;
+      let batchesSinceYield = 0;
+      let assemblySinceYieldMs = 0;
+      const elements = new Map<number, HTMLElement>([[0, container]]);
+      const fragmentCodes = new Map<number, number>();
+      const parts = new Map<number, { node: Text; from: number; to: number }[]>();
+      const tokens = new Map<number, SyntaxRange[]>();
+      const attributes = new Map<string, string>();
+      const searchIndexer = new DocumentSearchIndexer();
+      const searchNodes: { node: Text; from: number; to: number }[] = [];
+      let searchController: AbortController | null = null;
+      let searchQuery = "";
+      let searchOptions: DocumentSearchOptions = {};
+      let searchResult: DocumentSearchResult | null = null;
+      let searchRevision = 0;
+      let activeMatch: (DocumentMatch & { ordinal: number; pending: boolean }) | null = null;
+      const reveal = () => {
+        if (!activeMatch?.pending || disposed) return;
+        const locate = (offset: number) => {
+          let low = 0;
+          let high = searchNodes.length;
+          while (low < high) {
+            const middle = low + Math.floor((high - low) / 2);
+            const node = searchNodes[middle];
+            if (node && node.to < offset) low = middle + 1;
+            else high = middle;
+          }
+          return searchNodes[low];
+        };
+        const start = locate(activeMatch.from);
+        const end = locate(activeMatch.to);
+        if (!start || !end) return;
+        const range = new Range();
+        range.setStart(start.node, Math.max(0, Math.min(start.node.length, activeMatch.from - start.from)));
+        range.setEnd(end.node, Math.max(0, Math.min(end.node.length, activeMatch.to - end.from)));
+        CSS.highlights.set(`${highlightPrefix}-search`, new Highlight(range));
+        activeMatch.pending = false;
+        const rect = range.getBoundingClientRect();
+        const viewport = (options.viewport ?? container).getBoundingClientRect();
+        (options.viewport ?? container).scrollTop += rect.top - viewport.top - (options.viewport ?? container).clientHeight / 2;
+      };
+      const visible = new Set<number>();
+      let frame: number | null = null;
+      let disposed = false;
+      let batches = 0;
+      let largestBatch = 0;
+      let firstContentMs: number | null = null;
+      let complete = false;
+      let workerPipelineWallMs = 0;
+      let highlightRanges = 0;
+      let decorationLimited = false;
+      let mountedSpans = 0;
+      let textUnits = 0;
+      let syntaxSession: DocumentSyntaxSession | null = null;
+      let workerSyntaxRanges = 0;
+      let cachedSyntaxRanges = 0;
+      let peakCachedSyntaxRanges = 0;
+      let syntaxPages = 0;
+      let largestSyntaxPage = 0;
+      let syntaxError: string | null = null;
+      let syntaxFetching = false;
+      let syntaxWindowLimited = false;
+      let geometryProbes = 0;
+      let desiredWindows: DocumentSyntaxWindow[] = [];
+      let desiredKey = "";
+      let appliedKey = "";
+      let syntaxRevision = 0;
+      let decorationKey = "";
+      const fetchWindow = () => {
+        if (!syntaxSession || syntaxFetching || disposed || desiredKey === appliedKey || syntaxError) return;
+        syntaxFetching = true;
+        void (async () => {
+          while (!disposed && desiredKey !== appliedKey) {
+            const key = desiredKey;
+            const windows = desiredWindows;
+            tokens.clear();
+            syntaxRevision += 1;
+            cachedSyntaxRanges = 0;
+            syntaxWindowLimited = false;
+            for (const window of windows) {
+              let offset: number | null = 0;
+              do {
+                const page = await syntaxSession!.page(window, offset);
+                if (disposed || key !== desiredKey) break;
+                syntaxPages += 1;
+                largestSyntaxPage = Math.max(largestSyntaxPage, page.records.length);
+                const collection = tokens.get(window.id) ?? [];
+                for (const record of page.records) {
+                  const last = collection.at(-1);
+                  if (last?.from === record.range.from && last.to === record.range.to) continue;
+                  if (cachedSyntaxRanges === DOCUMENT_SYNTAX_CACHE_RANGES) {
+                    syntaxWindowLimited = true;
+                    break;
+                  }
+                  collection.push(record.range);
+                  cachedSyntaxRanges += 1;
+                }
+                tokens.set(window.id, collection);
+                syntaxRevision += 1;
+                peakCachedSyntaxRanges = Math.max(peakCachedSyntaxRanges, cachedSyntaxRanges);
+                offset = page.next;
+                schedule();
+                if (cachedSyntaxRanges === DOCUMENT_SYNTAX_CACHE_RANGES) {
+                  syntaxWindowLimited = true;
+                  break;
+                }
+              } while (offset !== null);
+              if (disposed || key !== desiredKey || syntaxWindowLimited) break;
+            }
+            if (key === desiredKey) appliedKey = key;
+          }
+        })()
+          .catch((error: unknown) => {
+            if (!disposed) {
+              syntaxError = error instanceof Error ? error.message : String(error);
+              tokens.clear();
+              syntaxRevision += 1;
+              cachedSyntaxRanges = 0;
+              schedule();
+            }
+          })
+          .finally(() => {
+            syntaxFetching = false;
+          });
+      };
+      const fallbacks: { id: number; reason: string }[] = [];
+      const paintViewport = () => {
+        frame = null;
+        if (disposed || signal.aborted) return;
+        if (visible.size === 0 && highlightRanges === 0 && desiredWindows.length === 0) return;
+        const categories = new Map<string, Range[]>();
+        const viewport = (options.viewport ?? container).getBoundingClientRect();
+        const viewportParts = new Map<number, { node: Text; from: number; to: number }[]>();
+        const windows: DocumentSyntaxWindow[] = [];
+        geometryProbes = 0;
+        let inspectedFragments = 0;
+        for (const id of visible) {
+          if (inspectedFragments++ === DOCUMENT_SYNTAX_WINDOW_PARTS || windows.length === DOCUMENT_SYNTAX_WINDOW_PARTS) break;
+          const collection = parts.get(id) ?? [];
+          const codeId = fragmentCodes.get(id);
+          if (codeId === undefined) continue;
+          const rectFor = (index: number) => {
+            geometryProbes += 1;
+            const part = collection[index];
+            if (!part) throw new Error("Missing visible Markdown text fragment");
+            const range = new Range();
+            range.selectNodeContents(part.node);
+            return range.getBoundingClientRect();
+          };
+          let low = 0;
+          let high = collection.length;
+          while (low < high) {
+            const middle = low + Math.floor((high - low) / 2);
+            if (rectFor(middle).bottom < viewport.top - (options.viewport ?? container).clientHeight) low = middle + 1;
+            else high = middle;
+          }
+          const selected = [];
+          for (let index = low; index < collection.length && windows.length < DOCUMENT_SYNTAX_WINDOW_PARTS; index += 1) {
+            if (rectFor(index).top > viewport.bottom + (options.viewport ?? container).clientHeight) break;
+            const part = collection[index];
+            if (!part) continue;
+            const pre = part.node.parentElement?.closest("pre") ?? null;
+            const rangeAt = (from: number, to: number) => {
+              const range = new Range();
+              range.setStart(part.node, from);
+              range.setEnd(part.node, to);
+              return range;
+            };
+            const clipped = visibleSyntaxColumnWindows(part.node.data, rangeAt, viewport, 0, part.node.length, pre);
+            selected.push(part);
+            for (const window of clipped) {
+              if (window.to <= window.from || windows.length === DOCUMENT_SYNTAX_WINDOW_PARTS) continue;
+              windows.push({ id: codeId, from: part.from + window.from, to: part.from + window.to });
+            }
+          }
+          viewportParts.set(id, selected);
+        }
+        windows.sort((left, right) => left.id - right.id || left.from - right.from);
+        const key = JSON.stringify(windows);
+        if (key !== desiredKey) {
+          desiredWindows = windows;
+          desiredKey = key;
+          tokens.clear();
+          syntaxRevision += 1;
+          cachedSyntaxRanges = 0;
+        }
+        fetchWindow();
+        const nextDecorationKey = `${key}:${syntaxRevision}`;
+        if (nextDecorationKey === decorationKey) return;
+        decorationKey = nextDecorationKey;
+        highlightRanges = 0;
+        decorationLimited = false;
+        for (const [id, selected] of viewportParts) {
+          const codeId = fragmentCodes.get(id);
+          const ranges = codeId === undefined ? [] : (tokens.get(codeId) ?? []);
+          for (const part of selected) {
+            let low = 0;
+            let high = ranges.length;
+            while (low < high) {
+              const middle = low + Math.floor((high - low) / 2);
+              const range = ranges[middle];
+              if (range && range.to <= part.from) low = middle + 1;
+              else high = middle;
+            }
+            for (let index = low; index < ranges.length; index += 1) {
+              const token = ranges[index];
+              if (!token || token.from >= part.to) break;
+              for (const category of token.categories) {
+                if (highlightRanges === MAX_DECORATION_RANGES) {
+                  decorationLimited = true;
+                  break;
+                }
+                const range = new Range();
+                range.setStart(part.node, Math.max(part.from, token.from) - part.from);
+                range.setEnd(part.node, Math.min(part.to, token.to) - part.from);
+                const collection = categories.get(category) ?? [];
+                collection.push(range);
+                categories.set(category, collection);
+                highlightRanges += 1;
+              }
+              if (decorationLimited) break;
+            }
+            if (decorationLimited) break;
+          }
+          if (decorationLimited) break;
+        }
+        for (const category of TOKEN_CATEGORIES)
+          CSS.highlights.set(`${highlightPrefix}-${category}`, new Highlight(...(categories.get(category) ?? [])));
+      };
+      const paint = () => {
+        const start = performance.now();
+        try {
+          paintViewport();
+        } finally {
+          const end = performance.now();
+          viewportPaintMs += end - start;
+          largestViewportPaintMs = Math.max(largestViewportPaintMs, end - start);
+          const name = "sambee:preview-preparation:retained-viewport-paint";
+          performance.clearMeasures(name);
+          performance.measure(name, { start, end });
+        }
+      };
+      const schedule = () => {
+        if (!disposed && frame === null) frame = requestAnimationFrame(paint);
+      };
+      const observer = new IntersectionObserver(
+        (entries) => {
+          for (const entry of entries) {
+            const id = Number((entry.target as HTMLElement).dataset["documentFragment"]);
+            if (entry.isIntersecting) visible.add(id);
+            else visible.delete(id);
+          }
+          schedule();
+        },
+        { root: options.viewport ?? container, rootMargin: "480px 0px" }
+      );
+      const resizeObserver = new ResizeObserver(schedule);
+      resizeObserver.observe(options.viewport ?? container);
+      const dispose = () => {
+        if (disposed) return;
+        disposed = true;
+        signal.removeEventListener("abort", dispose);
+        searchRevision += 1;
+        searchController?.abort();
+        searchSession.dispose();
+        syntaxSession?.dispose();
+        syntaxSession = null;
+        searchNodes.length = 0;
+        searchResult = null;
+        activeMatch = null;
+        CSS.highlights.delete(`${highlightPrefix}-search`);
+        observer.disconnect();
+        resizeObserver.disconnect();
+        container.removeEventListener("scroll", schedule);
+        container.removeEventListener("scroll", schedule, true);
+        options.viewport?.removeEventListener("scroll", schedule);
+        container.removeEventListener("load", schedule, true);
+        document.fonts.removeEventListener("loadingdone", schedule);
+        if (frame !== null) cancelAnimationFrame(frame);
+        for (const category of TOKEN_CATEGORIES) CSS.highlights.delete(`${highlightPrefix}-${category}`);
+        elements.clear();
+        parts.clear();
+        tokens.clear();
+        attributes.clear();
+        visible.clear();
+        fragmentCodes.clear();
+        fallbacks.length = 0;
+        desiredWindows = [];
+        container.replaceChildren();
+      };
+      container.addEventListener("scroll", schedule, { passive: true });
+      container.addEventListener("scroll", schedule, true);
+      options.viewport?.addEventListener("scroll", schedule, { passive: true });
+      container.addEventListener("load", schedule, true);
+      document.fonts.addEventListener("loadingdone", schedule);
+      signal.addEventListener("abort", dispose, { once: true });
+      resolve({
+        async search(query, options = {}) {
+          if (disposed) throw new DOMException("Document preview disposed", "AbortError");
+          searchController?.abort();
+          searchController = new AbortController();
+          const revision = ++searchRevision;
+          searchQuery = query;
+          searchOptions = { ...options };
+          searchResult = null;
+          activeMatch = null;
+          CSS.highlights.delete(`${highlightPrefix}-search`);
+          const result = await searchSession.search(query, searchOptions, searchController.signal);
+          if (revision !== searchRevision || disposed) throw new DOMException("Document search superseded", "AbortError");
+          searchResult = result;
+          if (result.matches[0]) {
+            activeMatch = { ...result.matches[0], ordinal: 0, pending: true };
+            reveal();
+          }
+          return result;
+        },
+        async jump(ordinal) {
+          if (disposed) throw new DOMException("Document preview disposed", "AbortError");
+          if (!searchResult) throw new Error("Document search results are pending or unavailable");
+          if (!Number.isSafeInteger(ordinal) || ordinal < 0 || ordinal >= searchResult.count)
+            throw new Error("Document match ordinal is out of range");
+          searchController?.abort();
+          searchController = new AbortController();
+          const revision = ++searchRevision;
+          let result = searchResult;
+          if (ordinal < result.offset || ordinal >= result.offset + result.matches.length)
+            result = await searchSession.search(searchQuery, searchOptions, searchController.signal, ordinal);
+          if (revision !== searchRevision || disposed) throw new DOMException("Document navigation superseded", "AbortError");
+          searchResult = result;
+          const match = result.matches[ordinal - result.offset];
+          if (!match) throw new Error("Document search returned no requested match");
+          activeMatch = { ...match, ordinal, pending: true };
+          reveal();
+          return { pending: activeMatch.pending };
+        },
+        async consume(records) {
+          const assemblyStart = performance.now();
+          signal.throwIfAborted();
+          if (disposed) throw new DOMException("Document preview disposed", "AbortError");
+          const additions = new Map<HTMLElement, DocumentFragment>();
+          const append = (parent: HTMLElement, node: Node) => {
+            let fragment = additions.get(parent);
+            if (!fragment) {
+              fragment = document.createDocumentFragment();
+              additions.set(parent, fragment);
+            }
+            fragment.append(node);
+          };
+          for (const record of records) {
+            const searchSegment = options.hostSearch ? null : searchIndexer.append(record);
+            if (record.kind === "element") {
+              if (!ALLOWED_TAGS.has(record.tag) || !elements.has(record.parent) || elements.has(record.id))
+                throw new Error("Invalid Markdown element record");
+              const element = document.createElement(record.tag);
+              if (record.tag === "span") mountedSpans += 1;
+              if (record.fragment) {
+                element.dataset["documentFragment"] = String(record.id);
+                element.className = "document-code-fragment";
+                fragmentCodes.set(record.id, record.parent);
+                observer.observe(element);
+              }
+              append(elements.get(record.parent)!, element);
+              elements.set(record.id, element);
+            } else if (record.kind === "text") {
+              const parent = elements.get(record.parent);
+              if (!parent) throw new Error("Markdown text has no parent");
+              const node = document.createTextNode(record.value);
+              textUnits += record.value.length;
+              append(parent, node);
+              if (searchSegment) searchNodes.push({ node, from: searchSegment.from, to: searchSegment.to });
+              if (fragmentCodes.has(record.parent)) {
+                const collection = parts.get(record.parent) ?? [];
+                collection.push({ node, from: record.from, to: record.from + record.value.length });
+                parts.set(record.parent, collection);
+              }
+            } else if (record.kind === "attribute") {
+              if (/^on/i.test(record.name) || record.name === "style") throw new Error("Unsafe Markdown attribute");
+              const key = `${record.id}:${record.name}`;
+              const value = (attributes.get(key) ?? "") + record.value;
+              if (!record.final) attributes.set(key, value);
+              else {
+                attributes.delete(key);
+                const element = elements.get(record.id);
+                if (!element) throw new Error("Markdown attribute has no element");
+                const name =
+                  record.name === "className"
+                    ? "class"
+                    : record.name.startsWith("aria")
+                      ? `aria-${record.name.slice(4).toLowerCase()}`
+                      : record.name.startsWith("data")
+                        ? record.name.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)
+                        : record.name.toLowerCase();
+                element.setAttribute(name, name === "href" || name === "src" ? defaultUrlTransform(value) : value);
+                if (name === "href" && element instanceof HTMLAnchorElement) options.configureLink?.(element, value);
+                if (name === "align" && ["left", "center", "right"].includes(value)) element.style.textAlign = value;
+              }
+            } else if (record.kind === "syntax") {
+              throw new Error("Full-document syntax records are not accepted by the viewport renderer");
+            } else fallbacks.push(record);
+          }
+          for (const [parent, fragment] of [...additions].reverse()) parent.append(fragment);
+          batches += 1;
+          largestBatch = Math.max(largestBatch, records.length);
+          largestBatchUnits = Math.max(
+            largestBatchUnits,
+            records.reduce((units, record) => units + (record.kind === "text" || record.kind === "attribute" ? record.value.length : 0), 0)
+          );
+          if (textUnits > 0) firstContentMs ??= performance.now() - started;
+          schedule();
+          reveal();
+          const assemblyDuration = performance.now() - assemblyStart;
+          assemblyMs += assemblyDuration;
+          largestAssemblyMs = Math.max(largestAssemblyMs, assemblyDuration);
+          publicationRecords += records.length;
+          batchesSinceYield += 1;
+          assemblySinceYieldMs += assemblyDuration;
+          if (batchesSinceYield >= PUBLICATION_BATCHES_PER_FRAME || assemblySinceYieldMs >= PUBLICATION_ASSEMBLY_BUDGET_MS) {
+            const waitStart = performance.now();
+            await yieldDocumentPublication(signal);
+            frameWaitMs += performance.now() - waitStart;
+            batchesSinceYield = 0;
+            assemblySinceYieldMs = 0;
+          }
+        },
+        finish(wallMs, syntaxRanges, session) {
+          if (!options.hostSearch) searchIndexer.finish();
+          syntaxSession = session;
+          workerSyntaxRanges = syntaxRanges;
+          workerPipelineWallMs = wallMs;
+          complete = true;
+          schedule();
+        },
+        dispose,
+        stats: () => ({
+          complete,
+          assemblyMs,
+          largestAssemblyMs,
+          frameWaitMs,
+          viewportPaintMs,
+          largestViewportPaintMs,
+          publicationRecords,
+          error: null,
+          batches,
+          largestBatch,
+          batchLimit: DOCUMENT_PUBLICATION_BATCH_ITEMS,
+          largestBatchUnits,
+          batchUnitLimit: DOCUMENT_PUBLICATION_BATCH_UNITS,
+          syntaxPageLimit: DOCUMENT_RECORD_BATCH_ITEMS,
+          firstContentMs,
+          workerPipelineWallMs,
+          highlightRanges,
+          decorationLimited,
+          cachedSyntaxRanges,
+          peakCachedSyntaxRanges,
+          syntaxCacheLimit: DOCUMENT_SYNTAX_CACHE_RANGES,
+          syntaxPages,
+          largestSyntaxPage,
+          syntaxFetching,
+          syntaxWindowLimited,
+          syntaxError,
+          workerSyntaxRanges,
+          geometryProbes,
+          fallbacks,
+          mountedElements: elements.size - 1,
+          mountedSpans,
+          textUnits,
+          search: searchSession.stats(),
+          activeMatch: activeMatch ? { ...activeMatch } : null,
+        }),
+      });
+      return dispose;
+    };
+    if (root instanceof HTMLDivElement) ready(root);
+    else root.render(<DocumentHost ready={ready} />);
+  });
+}
+
+export function renderMarkdownDocumentBaseline(root: Root, source: string): Promise<void> {
+  return new Promise((resolve) =>
+    root.render(
+      <div
+        className="document-proof"
+        data-markdown-baseline
+        style={{ height: 480, overflow: "auto" }}
+        ref={(element) => {
+          if (element) resolve();
+        }}
+      >
+        <ReactMarkdown remarkPlugins={[remarkGfm, remarkRenderMarkdownTableCellLineBreaks]}>
+          {normalizeMarkdownTableCellLineBreaks(source)}
+        </ReactMarkdown>
+      </div>
+    )
+  );
+}
diff --git a/frontend/src/utils/markdownDocumentPreviewModel.ts b/frontend/src/utils/markdownDocumentPreviewModel.ts
new file mode 100644
index 000000000..a40478cfc
--- /dev/null
+++ b/frontend/src/utils/markdownDocumentPreviewModel.ts
@@ -0,0 +1,143 @@
+import type { Element, ElementContent, Root } from "hast";
+import remarkGfm from "remark-gfm";
+import remarkParse from "remark-parse";
+import remarkRehype from "remark-rehype";
+import { unified } from "unified";
+import {
+  normalizeMarkdownTableCellLineBreaks,
+  remarkRenderMarkdownTableCellLineBreaks,
+} from "../components/Viewer/markdownTableCellLineBreaks";
+import { createCodePreviewModel } from "./markdownCodePreviewModel";
+import type { CodeBlockRequest, SyntaxRange } from "./syntaxHighlighting";
+
+export const DOCUMENT_RECORD_BATCH_ITEMS = 64;
+export const DOCUMENT_PUBLICATION_BATCH_ITEMS = 512;
+export const DOCUMENT_PUBLICATION_BATCH_UNITS = 16_384;
+export const DOCUMENT_TEXT_CHUNK_UNITS = 2_048;
+export const DOCUMENT_SYNTAX_CACHE_RANGES = 4_000;
+export const DOCUMENT_SYNTAX_WINDOW_PARTS = 40;
+const TABLE_STRUCTURE_TAGS = new Set(["table", "thead", "tbody", "tfoot", "tr"]);
+
+export type MarkdownDocumentRecord =
+  | { kind: "element"; id: number; parent: number; tag: string; fragment?: boolean }
+  | { kind: "attribute"; id: number; name: string; value: string; final: boolean }
+  | { kind: "text"; id: number; parent: number; value: string; from: number }
+  | { kind: "syntax"; id: number; range: SyntaxRange }
+  | { kind: "fallback"; id: number; reason: string };
+
+export interface MarkdownDocumentModel {
+  source: string;
+  tree: Root;
+  codeBlocks: (CodeBlockRequest & { id: number })[];
+}
+
+export interface DocumentSyntaxWindow {
+  id: number;
+  from: number;
+  to: number;
+}
+
+export function documentSyntaxPage(
+  ranges: readonly SyntaxRange[],
+  window: DocumentSyntaxWindow,
+  offset: number
+): { records: Extract<MarkdownDocumentRecord, { kind: "syntax" }>[]; next: number | null } {
+  if (
+    !Number.isSafeInteger(offset) ||
+    offset < 0 ||
+    !Number.isSafeInteger(window.from) ||
+    !Number.isSafeInteger(window.to) ||
+    window.from < 0 ||
+    window.to < window.from
+  )
+    throw new Error("Invalid document syntax window");
+  let low = 0;
+  let high = ranges.length;
+  while (low < high) {
+    const middle = low + Math.floor((high - low) / 2);
+    const range = ranges[middle];
+    if (range && range.to <= window.from) low = middle + 1;
+    else high = middle;
+  }
+  const records: Extract<MarkdownDocumentRecord, { kind: "syntax" }>[] = [];
+  let index = low + offset;
+  for (; index < ranges.length && records.length < DOCUMENT_RECORD_BATCH_ITEMS; index += 1) {
+    const range = ranges[index];
+    if (!range || range.from >= window.to) break;
+    records.push({ kind: "syntax", id: window.id, range });
+  }
+  const nextRange = ranges[index];
+  return { records, next: nextRange && nextRange.from < window.to ? index - low : null };
+}
+
+export async function createMarkdownDocumentModel(
+  source: string,
+  options: { normalizeSource?: boolean } = {}
+): Promise<MarkdownDocumentModel> {
+  const normalizedSource = options.normalizeSource ? normalizeMarkdownTableCellLineBreaks(source) : source;
+  const processor = unified()
+    .use(remarkParse)
+    .use(remarkGfm)
+    .use(remarkRenderMarkdownTableCellLineBreaks)
+    .use(remarkRehype, { allowDangerousHtml: true });
+  const tree = (await processor.run(processor.parse(normalizedSource))) as Root;
+  return { source: normalizedSource, tree, codeBlocks: [] };
+}
+
+export function* markdownDocumentRecords(model: MarkdownDocumentModel): Generator<MarkdownDocumentRecord> {
+  let nextId = 1;
+  const stack: { node: ElementContent; parent: number; parentTag?: string; from?: number; fragment?: boolean }[] = [...model.tree.children]
+    .reverse()
+    .map((node) => ({ node: node as ElementContent, parent: 0 }));
+  while (stack.length) {
+    const entry = stack.pop()!;
+    const { node, parent } = entry;
+    if ("value" in node && typeof node.value === "string") {
+      if (TABLE_STRUCTURE_TAGS.has(entry.parentTag ?? "") && /^\s*$/.test(node.value)) continue;
+      for (let from = 0; from < node.value.length; from += DOCUMENT_TEXT_CHUNK_UNITS) {
+        yield {
+          kind: "text",
+          id: nextId++,
+          parent,
+          value: node.value.slice(from, from + DOCUMENT_TEXT_CHUNK_UNITS),
+          from: (entry.from ?? 0) + from,
+        };
+      }
+      continue;
+    }
+    if (node.type !== "element") continue;
+    const id = nextId++;
+    yield { kind: "element", id, parent, tag: node.tagName, fragment: entry.fragment };
+    for (const [name, value] of Object.entries(node.properties)) {
+      if (value === null || value === undefined || value === false) continue;
+      const text = Array.isArray(value) ? value.join(" ") : value === true ? "" : String(value);
+      for (let from = 0; from < Math.max(1, text.length); from += DOCUMENT_TEXT_CHUNK_UNITS) {
+        yield {
+          kind: "attribute",
+          id,
+          name,
+          value: text.slice(from, from + DOCUMENT_TEXT_CHUNK_UNITS),
+          final: from + DOCUMENT_TEXT_CHUNK_UNITS >= text.length,
+        };
+      }
+    }
+    if (node.tagName === "code" && entry.parentTag === "pre" && node.children.every((child) => child.type === "text")) {
+      const text = node.children.map((child) => (child.type === "text" ? child.value : "")).join("");
+      const label = Array.isArray(node.properties["className"])
+        ? node.properties["className"].find((name) => String(name).startsWith("language-"))
+        : undefined;
+      model.codeBlocks.push({ id, text, label: label ? String(label).slice("language-".length) : null });
+      for (const fragment of [...createCodePreviewModel(text, []).fragments].reverse()) {
+        const span: Element = {
+          type: "element",
+          tagName: "span",
+          properties: {},
+          children: [{ type: "text", value: text.slice(fragment.from, fragment.to) }],
+        };
+        stack.push({ node: span, parent: id, from: fragment.from, fragment: true });
+      }
+    } else {
+      for (const child of [...node.children].reverse()) stack.push({ node: child, parent: id, parentTag: node.tagName, from: entry.from });
+    }
+  }
+}
diff --git a/frontend/src/utils/markdownDocumentSearch.ts b/frontend/src/utils/markdownDocumentSearch.ts
new file mode 100644
index 000000000..1144cdcfe
--- /dev/null
+++ b/frontend/src/utils/markdownDocumentSearch.ts
@@ -0,0 +1,89 @@
+import { SearchQuery } from "@codemirror/search";
+import { Text } from "@codemirror/state";
+import type { MarkdownDocumentRecord } from "./markdownDocumentPreviewModel";
+
+const BLOCK_TAGS = new Set("blockquote br div h1 h2 h3 h4 h5 h6 hr li ol p pre section table tbody td th thead tr ul".split(" "));
+
+export interface DocumentSearchOptions {
+  caseSensitive?: boolean;
+  regexp?: boolean;
+  wholeWord?: boolean;
+}
+
+export interface DocumentSearchSegment {
+  id: number;
+  from: number;
+  to: number;
+}
+
+export interface DocumentSearchIndex {
+  text: string;
+  segments: DocumentSearchSegment[];
+}
+
+export class DocumentSearchIndexer {
+  length = 0;
+  private endsWithNewline = false;
+  private ancestors = [{ id: 0, block: false, pre: false }];
+
+  private separator() {
+    if (!this.length || this.endsWithNewline) return;
+    this.length += 1;
+    this.endsWithNewline = true;
+  }
+
+  append(record: MarkdownDocumentRecord): DocumentSearchSegment | null {
+    if (record.kind !== "element" && record.kind !== "text") return null;
+    while (this.ancestors.at(-1)?.id !== record.parent) {
+      if (this.ancestors.length === 1) throw new Error("Search record has no source-ordered parent");
+      if (this.ancestors.pop()!.block) this.separator();
+    }
+    if (record.kind === "element") {
+      const block = BLOCK_TAGS.has(record.tag);
+      if (block) this.separator();
+      this.ancestors.push({ id: record.id, block, pre: record.tag === "pre" || this.ancestors.at(-1)!.pre });
+    } else {
+      if (!this.ancestors.at(-1)!.pre && record.value.includes("\n") && /^\s*$/.test(record.value)) return null;
+      const segment = { id: record.id, from: this.length, to: this.length + record.value.length };
+      this.length = segment.to;
+      this.endsWithNewline = record.value.endsWith("\n");
+      return segment;
+    }
+    return null;
+  }
+
+  finish(): void {
+    while (this.ancestors.length > 1) if (this.ancestors.pop()!.block) this.separator();
+  }
+}
+
+export function createDocumentSearchIndex(records: Iterable<MarkdownDocumentRecord>): DocumentSearchIndex {
+  const chunks: string[] = [];
+  const segments: DocumentSearchSegment[] = [];
+  const indexer = new DocumentSearchIndexer();
+  for (const record of records) {
+    const before = indexer.length;
+    const segment = indexer.append(record);
+    if ((segment?.from ?? indexer.length) > before) chunks.push("\n");
+    if (segment && record.kind === "text") {
+      segments.push(segment);
+      chunks.push(record.value);
+    }
+  }
+  const before = indexer.length;
+  indexer.finish();
+  if (indexer.length > before) chunks.push("\n");
+  return { text: chunks.join(""), segments };
+}
+
+export function* documentSearchMatches(
+  text: string | Text,
+  query: string,
+  options: DocumentSearchOptions = {}
+): Generator<{ from: number; to: number }> {
+  if (!query) return;
+  const search = new SearchQuery({ search: query, literal: true, ...options });
+  if (!search.valid) throw new Error("Invalid document search expression");
+  const cursor = search.getCursor(typeof text === "string" ? Text.of(text.split("\n")) : text);
+  for (let result = cursor.next(); !result.done; result = cursor.next()) yield { from: result.value.from, to: result.value.to };
+}
diff --git a/frontend/src/utils/markdownDocumentSearch.worker.ts b/frontend/src/utils/markdownDocumentSearch.worker.ts
new file mode 100644
index 000000000..529941d06
--- /dev/null
+++ b/frontend/src/utils/markdownDocumentSearch.worker.ts
@@ -0,0 +1,95 @@
+import { Text } from "@codemirror/state";
+import { PREPARATION_SOURCE_CHUNK_UNITS } from "./markdownCodePreparationProtocol";
+import { createMarkdownDocumentModel, markdownDocumentRecords } from "./markdownDocumentPreviewModel";
+import { createDocumentSearchIndex, documentSearchMatches } from "./markdownDocumentSearch";
+import {
+  DOCUMENT_SEARCH_PROGRESS_MATCHES,
+  DOCUMENT_SEARCH_WINDOW,
+  type DocumentMatch,
+  type DocumentSearchRequest,
+  type DocumentSearchResponse,
+} from "./markdownDocumentSearchWorker";
+
+let parts: string[] = [];
+let sequence = 0;
+let received = false;
+let index: Text | null = null;
+let acknowledge: (() => void) | null = null;
+let active: number | null = null;
+let cached: { key: string; count: number; offset: number; matches: DocumentMatch[] } | null = null;
+const send = (response: DocumentSearchResponse) => postMessage(response);
+
+async function search(request: Extract<DocumentSearchRequest, { type: "search" }>) {
+  if (!index || active !== null) throw new Error("Document search worker is not ready");
+  if (!Number.isSafeInteger(request.ordinal) || request.ordinal < 0) throw new Error("Invalid document match ordinal");
+  active = request.id;
+  try {
+    const key = JSON.stringify([request.query, !!request.options.caseSensitive, !!request.options.regexp, !!request.options.wholeWord]);
+    if (
+      cached?.key === key &&
+      (cached.count === 0 || (request.ordinal >= cached.offset && request.ordinal < cached.offset + cached.matches.length))
+    ) {
+      send({ type: "result", id: request.id, ...cached });
+      return;
+    }
+    const knownCount = cached?.key === key ? cached.count : null;
+    const offset = Math.floor(request.ordinal / DOCUMENT_SEARCH_WINDOW) * DOCUMENT_SEARCH_WINDOW;
+    const matches: DocumentMatch[] = [];
+    let count = 0;
+    for (const match of documentSearchMatches(index, request.query, request.options)) {
+      if (count >= offset && matches.length < DOCUMENT_SEARCH_WINDOW) matches.push(match);
+      count += 1;
+      if (knownCount !== null && count >= offset + DOCUMENT_SEARCH_WINDOW) break;
+      if (count % DOCUMENT_SEARCH_PROGRESS_MATCHES === 0)
+        await new Promise<void>((resolve) => {
+          acknowledge = resolve;
+          send({ type: "progress", id: request.id, count });
+        });
+    }
+    cached = { key, count: knownCount ?? count, offset, matches };
+    send({ type: "result", id: request.id, ...cached });
+  } finally {
+    active = null;
+    acknowledge = null;
+  }
+}
+
+globalThis.onmessage = (event: MessageEvent<DocumentSearchRequest>) => {
+  const request = event.data;
+  const run = async () => {
+    if (request.type === "init") {
+      if (index || received || parts.length) throw new Error("Document search worker already initialized");
+      send({ type: "source-ack", sequence: 0 });
+    } else if (request.type === "source") {
+      if (
+        received ||
+        request.sequence !== sequence + 1 ||
+        typeof request.text !== "string" ||
+        request.text.length > PREPARATION_SOURCE_CHUNK_UNITS
+      )
+        throw new Error("Invalid document search source chunk");
+      sequence = request.sequence;
+      parts.push(request.text);
+      if (!request.final) {
+        send({ type: "source-ack", sequence });
+        return;
+      }
+      received = true;
+      const source = parts.join("");
+      parts = [];
+      const parseStarted = performance.now();
+      const model = await createMarkdownDocumentModel(source);
+      const parseMs = performance.now() - parseStarted;
+      const indexStarted = performance.now();
+      const built = createDocumentSearchIndex(markdownDocumentRecords(model));
+      index = Text.of(built.text.split("\n"));
+      send({ type: "ready", textUnits: index.length, segments: built.segments.length, parseMs, indexMs: performance.now() - indexStarted });
+    } else if (request.type === "search") await search(request);
+    else if (request.type === "ack" && request.id === active) {
+      const resume = acknowledge;
+      acknowledge = null;
+      resume?.();
+    }
+  };
+  void run().catch((error: unknown) => send({ type: "error", message: error instanceof Error ? error.message : String(error) }));
+};
diff --git a/frontend/src/utils/markdownDocumentSearchWorker.ts b/frontend/src/utils/markdownDocumentSearchWorker.ts
new file mode 100644
index 000000000..38b33402a
--- /dev/null
+++ b/frontend/src/utils/markdownDocumentSearchWorker.ts
@@ -0,0 +1,185 @@
+import { PREPARATION_SOURCE_CHUNK_UNITS } from "./markdownCodePreparationProtocol";
+import type { DocumentSearchOptions } from "./markdownDocumentSearch";
+
+export const DOCUMENT_SEARCH_WINDOW = 64;
+export const DOCUMENT_SEARCH_PROGRESS_MATCHES = 512;
+export const DOCUMENT_SEARCH_TIMEOUT_MS = 2_000;
+
+export interface DocumentMatch {
+  from: number;
+  to: number;
+}
+export interface DocumentSearchResult {
+  count: number;
+  offset: number;
+  matches: DocumentMatch[];
+}
+export type DocumentSearchRequest =
+  | { type: "init" }
+  | { type: "source"; sequence: number; text: string; final: boolean }
+  | { type: "search"; id: number; query: string; options: DocumentSearchOptions; ordinal: number }
+  | { type: "ack"; id: number };
+export type DocumentSearchResponse =
+  | { type: "source-ack"; sequence: number }
+  | { type: "ready"; textUnits: number; segments: number; parseMs: number; indexMs: number }
+  | { type: "progress"; id: number; count: number }
+  | ({ type: "result"; id: number } & DocumentSearchResult)
+  | { type: "error"; message: string };
+
+export function createDocumentSearchSession(source: string) {
+  let sourceText: string | null = source;
+  let worker: Worker | null = null;
+  let ready = false;
+  let nextId = 0;
+  let cancel: (() => void) | null = null;
+  let status: Record<string, unknown> = { complete: false, lowerBound: 0, count: null, error: null, cachedMatches: 0 };
+  const dispose = () => {
+    cancel?.();
+    worker?.terminate();
+    worker = null;
+    ready = false;
+    sourceText = null;
+    status = { complete: false, disposed: true, cachedMatches: 0 };
+  };
+  return {
+    dispose,
+    stats: () => status,
+    search(query: string, options: DocumentSearchOptions, signal: AbortSignal, ordinal = 0): Promise<DocumentSearchResult> {
+      cancel?.();
+      if (signal.aborted) return Promise.reject(signal.reason);
+      if (sourceText === null) return Promise.reject(new Error("Document search session disposed"));
+      if (!Number.isSafeInteger(ordinal) || ordinal < 0) return Promise.reject(new Error("Invalid document match ordinal"));
+      const id = ++nextId;
+      status = { complete: false, lowerBound: 0, count: null, error: null, cachedMatches: 0 };
+      return new Promise((resolve, reject) => {
+        let current: Worker;
+        try {
+          if (typeof Worker === "undefined") throw new Error("Document search requires a worker; no main-thread fallback was used");
+          worker ??= new Worker(new URL("./markdownDocumentSearch.worker.ts", import.meta.url), { type: "module" });
+          current = worker;
+        } catch (error) {
+          status = { ...status, error: error instanceof Error ? error.message : String(error) };
+          reject(error);
+          return;
+        }
+        let settled = false;
+        let timer: ReturnType<typeof setTimeout>;
+        let sequence = 0;
+        let sourceOffset = 0;
+        let sourceComplete = false;
+        const cleanup = () => {
+          clearTimeout(timer);
+          signal.removeEventListener("abort", abort);
+          current.onmessage = null;
+          current.onerror = null;
+          current.removeEventListener("messageerror", decodeFailure);
+          if (cancel === abort) cancel = null;
+        };
+        const fail = (error: unknown) => {
+          if (settled) return;
+          settled = true;
+          cleanup();
+          current.terminate();
+          if (worker === current) {
+            worker = null;
+            ready = false;
+          }
+          status = {
+            ...status,
+            complete: false,
+            count: null,
+            cachedMatches: 0,
+            error: error instanceof Error ? error.message : String(error),
+          };
+          reject(error);
+        };
+        const abort = () => fail(new DOMException("Document search superseded", "AbortError"));
+        const decodeFailure = () => fail(new Error("Document search result could not be decoded"));
+        const arm = () => {
+          clearTimeout(timer);
+          timer = setTimeout(
+            () => fail(new Error("Document search exceeded its prototype progress deadline; worker terminated")),
+            DOCUMENT_SEARCH_TIMEOUT_MS
+          );
+        };
+        const send = (request: DocumentSearchRequest) => {
+          current.postMessage(request);
+        };
+        const run = () => send({ type: "search", id, query, options, ordinal });
+        cancel = abort;
+        signal.addEventListener("abort", abort, { once: true });
+        current.addEventListener("messageerror", decodeFailure);
+        current.onerror = (event) => {
+          event.preventDefault();
+          fail(new Error(`Document search worker failed: ${event.message}`));
+        };
+        current.onmessage = (event: MessageEvent<DocumentSearchResponse>) => {
+          if (settled) return;
+          try {
+            const response = event.data;
+            if (response.type === "error") {
+              fail(new Error(response.message));
+              return;
+            }
+            arm();
+            if (response.type === "source-ack") {
+              if (ready || sourceComplete || response.sequence !== sequence)
+                throw new Error("Invalid document search source acknowledgement");
+              const text = sourceText!.slice(sourceOffset, sourceOffset + PREPARATION_SOURCE_CHUNK_UNITS);
+              sourceOffset += text.length;
+              const final = sourceOffset === sourceText!.length;
+              sourceComplete = final;
+              send({ type: "source", sequence: ++sequence, text, final });
+              return;
+            }
+            if (response.type === "ready") {
+              ready = true;
+              status = {
+                ...status,
+                textUnits: response.textUnits,
+                segments: response.segments,
+                parseMs: response.parseMs,
+                indexMs: response.indexMs,
+              };
+              run();
+              return;
+            }
+            if (response.id !== id) return;
+            if (response.type === "progress") {
+              status = { ...status, lowerBound: response.count };
+              send({ type: "ack", id });
+              return;
+            }
+            if (
+              response.type !== "result" ||
+              !Number.isSafeInteger(response.count) ||
+              response.count < 0 ||
+              response.matches.length > DOCUMENT_SEARCH_WINDOW
+            )
+              throw new Error("Invalid document search result");
+            status = {
+              ...status,
+              complete: true,
+              count: response.count,
+              lowerBound: response.count,
+              error: null,
+              cachedMatches: response.matches.length,
+            };
+            settled = true;
+            cleanup();
+            resolve(response);
+          } catch (error) {
+            fail(error);
+          }
+        };
+        arm();
+        try {
+          if (ready) run();
+          else send({ type: "init" });
+        } catch (error) {
+          fail(error);
+        }
+      });
+    },
+  };
+}
diff --git a/frontend/src/utils/markdownHeadingLinks.ts b/frontend/src/utils/markdownHeadingLinks.ts
new file mode 100644
index 000000000..65716ce81
--- /dev/null
+++ b/frontend/src/utils/markdownHeadingLinks.ts
@@ -0,0 +1,34 @@
+import type { Element, Root } from "hast";
+import rehypeSlug from "rehype-slug";
+import type { Plugin } from "unified";
+
+export const MARKDOWN_HEADING_ID_PREFIX = "sambee-markdown-";
+
+export const rehypeMarkdownHeadingLinks: Plugin<[], Root> = () => {
+  const assignIds = rehypeSlug({ prefix: MARKDOWN_HEADING_ID_PREFIX });
+  return (tree) => {
+    assignIds(tree);
+    const targets = new Set<string>();
+    const links: Element[] = [];
+    const visit = (node: Root | Element) => {
+      if (node.type === "element") {
+        if (/^h[1-6]$/.test(node.tagName) && typeof node.properties["id"] === "string") targets.add(node.properties["id"]);
+        if (node.tagName === "a") links.push(node);
+      }
+      for (const child of node.children) if (child.type === "element") visit(child);
+    };
+    visit(tree);
+    for (const link of links) {
+      const href = link.properties["href"];
+      if (typeof href !== "string" || !href.startsWith("#")) continue;
+      let fragment: string;
+      try {
+        fragment = decodeURIComponent(href.slice(1));
+      } catch {
+        continue;
+      }
+      const id = fragment.startsWith(MARKDOWN_HEADING_ID_PREFIX) ? fragment : `${MARKDOWN_HEADING_ID_PREFIX}${fragment}`;
+      if (targets.has(id)) link.properties["href"] = `#${encodeURIComponent(id)}`;
+    }
+  };
+};
diff --git a/frontend/src/utils/markdownPreparedTree.ts b/frontend/src/utils/markdownPreparedTree.ts
new file mode 100644
index 000000000..85d3d88cb
--- /dev/null
+++ b/frontend/src/utils/markdownPreparedTree.ts
@@ -0,0 +1,145 @@
+import type { Root, RootContent } from "mdast";
+import type { Plugin } from "unified";
+
+export const MARKDOWN_TREE_BATCH_RECORDS = 512;
+export const MARKDOWN_TREE_BATCH_UNITS = 16_384;
+export const MARKDOWN_TREE_TEXT_UNITS = 2_048;
+const TREE_TEXT_FIELDS = new Set(["value", "lang", "meta", "url", "title", "alt", "identifier", "label", "referenceType", "align"]);
+
+function validNodeMetadata(node: Record<string, unknown>): boolean {
+  return Object.entries(node).every(([key, value]) => {
+    if (key === "type") return typeof value === "string" && value.length <= MARKDOWN_TREE_TEXT_UNITS;
+    if (TREE_TEXT_FIELDS.has(key)) return value === null || value === undefined;
+    if (key === "depth" || key === "start") return value === null || Number.isSafeInteger(value);
+    if (key === "ordered" || key === "spread" || key === "checked") return value === null || typeof value === "boolean";
+    if (key !== "position" || !value || typeof value !== "object" || Object.keys(value).length !== 2) return false;
+    return ["start", "end"].every((boundary) => {
+      const point = (value as Record<string, unknown>)[boundary];
+      return (
+        point !== null &&
+        typeof point === "object" &&
+        Object.keys(point).length === 3 &&
+        ["line", "column", "offset"].every((coordinate) => {
+          const number = (point as Record<string, unknown>)[coordinate];
+          return typeof number === "number" && Number.isSafeInteger(number) && number >= (coordinate === "offset" ? 0 : 1);
+        })
+      );
+    });
+  });
+}
+
+type MarkdownNode = Root | RootContent;
+export type MarkdownTreeRecord =
+  | { kind: "node"; id: number; parent: number | null; node: Record<string, unknown>; children: boolean }
+  | { kind: "text"; id: number; key: string; value: string };
+
+export function* markdownTreeRecords(tree: Root): Generator<MarkdownTreeRecord> {
+  const pending: { node: MarkdownNode; parent: number | null }[] = [{ node: tree, parent: null }];
+  let nextId = 0;
+  while (pending.length) {
+    const { node, parent } = pending.pop()!;
+    const id = nextId++;
+    const data: Record<string, unknown> = {};
+    const text: [string, string][] = [];
+    for (const [key, value] of Object.entries(node)) {
+      if (key === "children") continue;
+      if (key === "align") text.push([key, JSON.stringify(value)]);
+      else if (typeof value === "string" && key !== "type") text.push([key, value]);
+      else data[key] = value;
+    }
+    const children = "children" in node ? node.children : null;
+    yield { kind: "node", id, parent, node: data, children: children !== null };
+    for (const [key, value] of text) {
+      for (let offset = 0; offset < Math.max(1, value.length); offset += MARKDOWN_TREE_TEXT_UNITS)
+        yield { kind: "text", id, key, value: value.slice(offset, offset + MARKDOWN_TREE_TEXT_UNITS) };
+    }
+    if (children) {
+      for (let index = children.length - 1; index >= 0; index -= 1) {
+        const child = children[index];
+        if (child) pending.push({ node: child, parent: id });
+      }
+    }
+  }
+}
+
+export function createMarkdownTreeReceiver() {
+  const nodes: Record<string, unknown>[] = [];
+  const fields = new Map<number, Map<string, string[]>>();
+  let finished = false;
+  return {
+    consume(records: readonly MarkdownTreeRecord[]) {
+      if (finished || records.length > MARKDOWN_TREE_BATCH_RECORDS) throw new Error("Invalid Markdown tree batch");
+      let units = 0;
+      for (const record of records) {
+        if (!Number.isSafeInteger(record.id) || record.id < 0) throw new Error("Invalid Markdown tree node identifier");
+        if (record.kind === "node") {
+          if (
+            record.id !== nodes.length ||
+            typeof record.node["type"] !== "string" ||
+            record.node["type"].length > MARKDOWN_TREE_TEXT_UNITS ||
+            (record.id === 0 ? record.parent !== null || record.node["type"] !== "root" : record.parent === null) ||
+            typeof record.children !== "boolean" ||
+            !validNodeMetadata(record.node)
+          )
+            throw new Error("Invalid Markdown tree node");
+          const node = { ...record.node, ...(record.children ? { children: [] } : {}) };
+          if (record.parent !== null) {
+            const children = nodes[record.parent]?.["children"];
+            if (!Number.isSafeInteger(record.parent) || !Array.isArray(children)) throw new Error("Invalid Markdown tree parent");
+            children.push(node);
+          }
+          nodes.push(node);
+          units += record.node["type"].length;
+        } else if (record.kind === "text") {
+          if (
+            !nodes[record.id] ||
+            !TREE_TEXT_FIELDS.has(record.key) ||
+            typeof record.value !== "string" ||
+            record.value.length > MARKDOWN_TREE_TEXT_UNITS
+          )
+            throw new Error("Invalid Markdown tree text");
+          const nodeFields = fields.get(record.id) ?? new Map<string, string[]>();
+          const chunks = nodeFields.get(record.key) ?? [];
+          chunks.push(record.value);
+          nodeFields.set(record.key, chunks);
+          fields.set(record.id, nodeFields);
+          units += record.value.length;
+        } else throw new Error("Unexpected Markdown tree record");
+      }
+      if (units > MARKDOWN_TREE_BATCH_UNITS) throw new Error("Markdown tree batch exceeded its text bound");
+    },
+    finish(): Root {
+      if (finished || nodes[0]?.["type"] !== "root" || !Array.isArray(nodes[0]?.["children"])) throw new Error("Incomplete Markdown tree");
+      finished = true;
+      for (const [id, nodeFields] of fields) {
+        const node = nodes[id];
+        if (!node) throw new Error("Missing Markdown tree node for text fields");
+        for (const [key, chunks] of nodeFields) {
+          const text = chunks.join("");
+          if (key === "align") {
+            const alignment: unknown = JSON.parse(text);
+            if (!Array.isArray(alignment) || alignment.some((value) => value !== null && !["left", "right", "center"].includes(value)))
+              throw new Error("Invalid Markdown table alignment");
+            node[key] = alignment;
+          } else node[key] = text;
+        }
+      }
+      fields.clear();
+      return nodes[0] as unknown as Root;
+    },
+  };
+}
+
+export const remarkPreparedMarkdownTree: Plugin<[Root | undefined], Root> = function (tree) {
+  if (tree)
+    this.parser = () => {
+      const start = performance.now();
+      try {
+        return structuredClone(tree);
+      } finally {
+        const name = "sambee:preview-preparation:render-prepared-tree";
+        performance.clearMeasures?.(name);
+        performance.measure?.(name, { start, end: performance.now() });
+      }
+    };
+};
diff --git a/frontend/src/utils/markdownSyntax.ts b/frontend/src/utils/markdownSyntax.ts
new file mode 100644
index 000000000..70f6a745c
--- /dev/null
+++ b/frontend/src/utils/markdownSyntax.ts
@@ -0,0 +1,99 @@
+import type { Element, ElementContent, Root } from "hast";
+import type { Root as MarkdownRoot } from "mdast";
+import remarkGfm from "remark-gfm";
+import remarkParse from "remark-parse";
+import { type Plugin, unified } from "unified";
+import { type CodeBlockRequest, type PreparedCodeBlock, tokenClasses } from "./syntaxHighlighting";
+
+export interface PreparedMarkdownSyntax {
+  requests: readonly CodeBlockRequest[];
+  results: readonly PreparedCodeBlock[];
+}
+
+export function recordMarkdownPreparation(stage: string, start: number): void {
+  const name = `sambee:preview-preparation:${stage}`;
+  performance.clearMeasures?.(name);
+  performance.measure?.(name, { start, end: performance.now() });
+}
+
+export const remarkMeasureMarkdownPreparation: Plugin<[], MarkdownRoot> = function () {
+  const parser = this.parser;
+  if (parser) {
+    this.parser = (...args) => {
+      const start = performance.now();
+      try {
+        return parser(...args);
+      } finally {
+        recordMarkdownPreparation("render-parse", start);
+      }
+    };
+  }
+  return (_tree, file) => {
+    file.data["sambeeMarkdownTransformStart"] = performance.now();
+  };
+};
+
+export const rehypeMeasureMarkdownPreparation: Plugin<[(() => void)?], Root> = (onReady) => (_tree, file) => {
+  const start = file.data["sambeeMarkdownTransformStart"];
+  if (typeof start === "number") recordMarkdownPreparation("render-transform", start);
+  onReady?.();
+};
+
+export function collectMarkdownCodeBlocks(source: string): CodeBlockRequest[] {
+  const parseStart = performance.now();
+  const tree = unified().use(remarkParse).use(remarkGfm).parse(source) as MarkdownRoot;
+  recordMarkdownPreparation("collection-parse", parseStart);
+  return collectMarkdownCodeBlocksFromTree(tree);
+}
+
+export const remarkCollectMarkdownCodeBlocks: Plugin<[(requests: CodeBlockRequest[]) => void], MarkdownRoot> = (onCollected) => (tree) => {
+  onCollected(collectMarkdownCodeBlocksFromTree(tree));
+};
+
+function collectMarkdownCodeBlocksFromTree(tree: MarkdownRoot): CodeBlockRequest[] {
+  const walkStart = performance.now();
+  const blocks: CodeBlockRequest[] = [];
+  const visit = (node: MarkdownRoot | MarkdownRoot["children"][number]) => {
+    if (node.type === "code") blocks.push({ text: node.value, label: node.lang });
+    if ("children" in node) for (const child of node.children) visit(child as MarkdownRoot["children"][number]);
+  };
+  visit(tree);
+  recordMarkdownPreparation("collection-walk", walkStart);
+  return blocks;
+}
+
+export function rehypePreparedSyntax(prepared?: PreparedMarkdownSyntax) {
+  return (tree: Root): void => {
+    if (!prepared) return;
+    let index = 0;
+    const visit = (node: Root | Element): void => {
+      if (node.type === "element" && node.tagName === "pre") {
+        const code = node.children.find((child): child is Element => child.type === "element" && child.tagName === "code");
+        if (!code) return;
+        const request = prepared.requests[index];
+        const result = prepared.results[index++];
+        if (!request || !result || !("ranges" in result) || code.children.some((child) => child.type !== "text")) return;
+        const text = code.children.map((child) => (child.type === "text" ? child.value : "")).join("");
+        if (text !== request.text && text !== `${request.text}\n`) return;
+        const children: ElementContent[] = [];
+        let offset = 0;
+        for (const range of result.ranges) {
+          if (range.from < offset || range.to <= range.from || range.to > request.text.length) return;
+          if (range.from > offset) children.push({ type: "text", value: text.slice(offset, range.from) });
+          children.push({
+            type: "element",
+            tagName: "span",
+            properties: { className: tokenClasses(range.categories).split(" ") },
+            children: [{ type: "text", value: text.slice(range.from, range.to) }],
+          });
+          offset = range.to;
+        }
+        if (offset < text.length) children.push({ type: "text", value: text.slice(offset) });
+        code.children = children;
+        return;
+      }
+      for (const child of node.children) if (child.type === "element") visit(child);
+    };
+    visit(tree);
+  };
+}
diff --git a/frontend/src/utils/markdownSyntax.worker.ts b/frontend/src/utils/markdownSyntax.worker.ts
new file mode 100644
index 000000000..5ee08ae61
--- /dev/null
+++ b/frontend/src/utils/markdownSyntax.worker.ts
@@ -0,0 +1,63 @@
+import { createStaticHighlighter, MAX_STATIC_BLOCK_LENGTH } from "./codeMirrorHighlightingCore";
+import {
+  SYNTAX_RESULT_PAGE_RANGES,
+  SYNTAX_SOURCE_CHUNK_UNITS,
+  type SyntaxWorkerRequest,
+  type SyntaxWorkerResponse,
+} from "./markdownSyntaxWorkerProtocol";
+
+function send(message: SyntaxWorkerResponse): void {
+  postMessage(message);
+}
+
+const highlighter = createStaticHighlighter((message, context, component, failure) => {
+  send({ type: "diagnostic", message, context, component, error: failure?.message });
+});
+let parts: string[] = [];
+let length = 0;
+let block = 0;
+let busy = false;
+let acknowledge: (() => void) | null = null;
+
+async function receive(message: SyntaxWorkerRequest): Promise<void> {
+  if (message.type === "ack") {
+    const resolve = acknowledge;
+    acknowledge = null;
+    if (!resolve) throw new Error("Unexpected syntax result acknowledgement");
+    resolve();
+    return;
+  }
+  if (busy || message.block !== block || message.text.length > SYNTAX_SOURCE_CHUNK_UNITS) {
+    throw new Error("Invalid syntax source sequence or chunk size");
+  }
+  parts.push(message.text);
+  length += message.text.length;
+  if (length > MAX_STATIC_BLOCK_LENGTH) throw new Error("Syntax source exceeded the parser block limit");
+  if (!message.final) {
+    send({ type: "source-ack" });
+    return;
+  }
+  busy = true;
+  const text = parts.join("");
+  parts = [];
+  length = 0;
+  const [result] = await highlighter.prepare([{ text, label: message.label }]);
+  if (!result) throw new Error("Syntax preparation returned no result");
+  if ("ranges" in result) {
+    for (let offset = 0; offset < result.ranges.length; offset += SYNTAX_RESULT_PAGE_RANGES) {
+      await new Promise<void>((resolve) => {
+        acknowledge = resolve;
+        send({ type: "ranges", block, ranges: result.ranges.slice(offset, offset + SYNTAX_RESULT_PAGE_RANGES) });
+      });
+    }
+  }
+  const completed = block++;
+  busy = false;
+  send({ type: "complete", block: completed, reason: "reason" in result ? result.reason : undefined });
+}
+
+globalThis.onmessage = (event: MessageEvent<SyntaxWorkerRequest>) => {
+  void receive(event.data).catch((error: unknown) => {
+    send({ type: "error", message: error instanceof Error ? error.message : "Syntax worker preparation failed" });
+  });
+};
diff --git a/frontend/src/utils/markdownSyntaxPublication.ts b/frontend/src/utils/markdownSyntaxPublication.ts
new file mode 100644
index 000000000..4fd0068d2
--- /dev/null
+++ b/frontend/src/utils/markdownSyntaxPublication.ts
@@ -0,0 +1,228 @@
+import type { PreparedMarkdownSyntax } from "./markdownSyntax";
+import { TOKEN_CATEGORIES, TOKEN_COLOR_ROLES, type TokenCategory } from "./syntaxHighlighting";
+
+export const MAX_VIEWPORT_SYNTAX_RANGES = 4_000;
+const BLOCKS_PER_FRAME = 16;
+const SYNTAX_HIGHLIGHT_PRIORITY = -1;
+let publicationId = 0;
+
+function measureSyntaxStage<Result>(stage: string, operation: () => Result): Result {
+  const start = performance.now();
+  try {
+    return operation();
+  } finally {
+    const name = `sambee:preview-syntax:${stage}`;
+    performance.clearMeasures?.(name);
+    performance.measure?.(name, { start, end: performance.now() });
+  }
+}
+
+export function visibleSyntaxColumnWindows(
+  text: string,
+  rangeAt: (from: number, to: number) => Range,
+  bounds: Pick<DOMRect, "left" | "right">,
+  from: number,
+  to: number,
+  pre: HTMLElement | null
+): { from: number; to: number }[] {
+  if (!pre || pre.scrollWidth <= pre.clientWidth || getComputedStyle(pre).whiteSpace !== "pre" || getComputedStyle(pre).direction === "rtl")
+    return [{ from, to }];
+  const clip = pre.getBoundingClientRect();
+  if (clip.right < bounds.left || clip.left > bounds.right) return [];
+  const windows: { from: number; to: number }[] = [];
+  let lineStart = from;
+  while (lineStart < to) {
+    const newline = text.indexOf("\n", lineStart);
+    const lineEnd = newline < 0 ? to : Math.min(to, newline + 1);
+    const columnAt = (edge: number, start = lineStart) => {
+      let low = start;
+      let high = lineEnd;
+      if (low < high && rangeAt(low, low + 1).getBoundingClientRect().right >= edge) return low;
+      while (low < high) {
+        const middle = (low + high) >>> 1;
+        if (rangeAt(middle, middle + 1).getBoundingClientRect().right < edge) low = middle + 1;
+        else high = middle;
+      }
+      return low;
+    };
+    const visibleFrom = columnAt(Math.max(bounds.left, clip.left));
+    windows.push({
+      from: visibleFrom,
+      to: Math.min(lineEnd, columnAt(Math.min(bounds.right, clip.right), visibleFrom) + 1),
+    });
+    lineStart = lineEnd;
+  }
+  return windows;
+}
+
+export function publishMarkdownSyntax(
+  root: HTMLElement,
+  viewport: HTMLElement,
+  prepared: PreparedMarkdownSyntax,
+  signal: AbortSignal
+): () => void {
+  if (signal.aborted || typeof Highlight === "undefined" || !globalThis.CSS?.highlights || typeof IntersectionObserver === "undefined")
+    return () => {};
+  const prefix = `markdown-syntax-${++publicationId}`;
+  const names = new Map(TOKEN_CATEGORIES.map((category) => [category, `${prefix}-${category}`]));
+  const style = document.createElement("style");
+  style.textContent = TOKEN_CATEGORIES.map((category) => {
+    const color = TOKEN_COLOR_ROLES[category];
+    return `::highlight(${names.get(category)}) { color: var(--sambee-syntax-${color}); }`;
+  }).join("\n");
+  document.head.append(style);
+  const blocks = Array.from(root.querySelectorAll<HTMLElement>("pre > code"));
+  const blockIndices = new Map(blocks.map((block, index) => [block, index]));
+  const visibleBlocks = new Set<number>();
+  let pendingBlocks: number[] = [];
+  let frame: number | null = null;
+  let disposed = false;
+  let nextBlock = 0;
+  let count = 0;
+  const categories = new Map<TokenCategory, Range[]>();
+
+  const paint = () => measureSyntaxStage("task", paintTask);
+  const paintTask = () => {
+    frame = null;
+    if (disposed || signal.aborted) return;
+    const bounds = measureSyntaxStage("viewport-geometry", () => viewport.getBoundingClientRect());
+    const limit = Math.min(pendingBlocks.length, nextBlock + BLOCKS_PER_FRAME);
+    for (; nextBlock < limit && count < MAX_VIEWPORT_SYNTAX_RANGES; nextBlock += 1) {
+      const index = pendingBlocks[nextBlock];
+      if (index === undefined) continue;
+      const code = blocks[index];
+      const result = prepared.results[index];
+      const request = prepared.requests[index];
+      if (!code || !request || !result || !("ranges" in result)) continue;
+      const rect = measureSyntaxStage("block-geometry", () => code.getBoundingClientRect());
+      if (rect.bottom < bounds.top || rect.top > bounds.bottom) continue;
+      const { nodes, length, valid } = measureSyntaxStage("mapping", () => {
+        const walker = document.createTreeWalker(code, NodeFilter.SHOW_TEXT);
+        const nodes: { node: Text; from: number; to: number }[] = [];
+        let length = 0;
+        while (walker.nextNode()) {
+          const node = walker.currentNode as Text;
+          nodes.push({ node, from: length, to: length + node.length });
+          length += node.length;
+        }
+        return { nodes, length, valid: code.textContent === request.text || code.textContent === `${request.text}\n` };
+      });
+      if (!nodes.length || !valid) continue;
+      const locate = (offset: number) => {
+        let low = 0;
+        let high = nodes.length - 1;
+        while (low < high) {
+          const middle = (low + high) >>> 1;
+          const node = nodes[middle];
+          if (node && node.to <= offset) low = middle + 1;
+          else high = middle;
+        }
+        return nodes[low];
+      };
+      const rangeAt = (from: number, to: number) => {
+        const start = locate(from);
+        const end = locate(to);
+        if (!start || !end) throw new Error("Cannot map syntax range to document text");
+        const range = new Range();
+        range.setStart(start.node, Math.min(start.node.length, from - start.from));
+        range.setEnd(end.node, Math.min(end.node.length, to - end.from));
+        return range;
+      };
+      const offsetAt = (top: number) => {
+        let low = 0;
+        let high = Math.min(request.text.length, length);
+        while (low < high) {
+          const middle = (low + high) >>> 1;
+          if (rangeAt(middle, Math.min(middle + 1, length)).getBoundingClientRect().bottom < top) low = middle + 1;
+          else high = middle;
+        }
+        return low;
+      };
+      const windows = measureSyntaxStage("offset-geometry", () => {
+        const from = rect.top >= bounds.top ? 0 : offsetAt(bounds.top);
+        const to = rect.bottom <= bounds.bottom ? request.text.length : Math.min(request.text.length, offsetAt(bounds.bottom) + 1);
+        return visibleSyntaxColumnWindows(request.text, rangeAt, bounds, from, to, code.closest("pre"));
+      });
+      measureSyntaxStage("ranges", () => {
+        for (const { from, to } of windows) {
+          let low = 0;
+          let high = result.ranges.length;
+          while (low < high) {
+            const middle = (low + high) >>> 1;
+            const token = result.ranges[middle];
+            if (token && token.to <= from) low = middle + 1;
+            else high = middle;
+          }
+          for (let index = low; index < result.ranges.length && count < MAX_VIEWPORT_SYNTAX_RANGES; index += 1) {
+            const token = result.ranges[index];
+            if (!token || token.from >= to) break;
+            const range = rangeAt(Math.max(from, token.from), Math.min(to, token.to));
+            for (const category of token.categories) {
+              if (count === MAX_VIEWPORT_SYNTAX_RANGES) break;
+              const ranges = categories.get(category) ?? [];
+              ranges.push(range);
+              categories.set(category, ranges);
+              count += 1;
+            }
+          }
+        }
+      });
+    }
+    measureSyntaxStage("publication", () => {
+      for (const [category, name] of names) {
+        const highlight = new Highlight(...(categories.get(category) ?? []));
+        highlight.priority = SYNTAX_HIGHLIGHT_PRIORITY;
+        CSS.highlights.set(name, highlight);
+      }
+    });
+    if (nextBlock < pendingBlocks.length && count < MAX_VIEWPORT_SYNTAX_RANGES) frame = requestAnimationFrame(paint);
+  };
+  const refresh = () => {
+    if (disposed || signal.aborted) return;
+    pendingBlocks = [...visibleBlocks].sort((left, right) => left - right);
+    nextBlock = 0;
+    count = 0;
+    categories.clear();
+    if (frame === null) frame = requestAnimationFrame(paint);
+  };
+  const intersections = new IntersectionObserver(
+    (entries) => {
+      for (const entry of entries) {
+        const index = blockIndices.get(entry.target as HTMLElement);
+        if (index === undefined) continue;
+        if (entry.isIntersecting) visibleBlocks.add(index);
+        else visibleBlocks.delete(index);
+      }
+      refresh();
+    },
+    { root: viewport }
+  );
+  for (const block of blocks) intersections.observe(block);
+  const observer = new ResizeObserver(refresh);
+  observer.observe(viewport);
+  const mutations = new MutationObserver(refresh);
+  mutations.observe(root, { subtree: true, childList: true, characterData: true });
+  viewport.addEventListener("scroll", refresh, { passive: true });
+  root.addEventListener("scroll", refresh, { capture: true, passive: true });
+  root.addEventListener("load", refresh, true);
+  const fonts = document.fonts;
+  fonts?.addEventListener("loadingdone", refresh);
+  const dispose = () => {
+    if (disposed) return;
+    disposed = true;
+    if (frame !== null) cancelAnimationFrame(frame);
+    intersections.disconnect();
+    observer.disconnect();
+    mutations.disconnect();
+    viewport.removeEventListener("scroll", refresh);
+    root.removeEventListener("scroll", refresh, true);
+    root.removeEventListener("load", refresh, true);
+    fonts?.removeEventListener("loadingdone", refresh);
+    signal.removeEventListener("abort", dispose);
+    for (const name of names.values()) CSS.highlights.delete(name);
+    style.remove();
+  };
+  signal.addEventListener("abort", dispose, { once: true });
+  refresh();
+  return dispose;
+}
diff --git a/frontend/src/utils/markdownSyntaxWorker.ts b/frontend/src/utils/markdownSyntaxWorker.ts
new file mode 100644
index 000000000..84a28d42d
--- /dev/null
+++ b/frontend/src/utils/markdownSyntaxWorker.ts
@@ -0,0 +1,131 @@
+import { error as logError } from "../services/logger";
+import { MAX_STATIC_BLOCK_LENGTH } from "./codeMirrorHighlightingCore";
+import { highlightingService } from "./highlightingService";
+import {
+  SYNTAX_RESULT_PAGE_RANGES,
+  SYNTAX_SOURCE_CHUNK_UNITS,
+  SYNTAX_WORKER_PROGRESS_TIMEOUT_MS,
+  type SyntaxWorkerRequest,
+  type SyntaxWorkerResponse,
+} from "./markdownSyntaxWorkerProtocol";
+import type { CodeBlockRequest, PreparedCodeBlock, SyntaxRange } from "./syntaxHighlighting";
+
+export function prepareMarkdownSyntax(blocks: readonly CodeBlockRequest[], signal: AbortSignal): Promise<readonly PreparedCodeBlock[]> {
+  if (signal.aborted) return Promise.reject(new DOMException("Syntax preparation cancelled", "AbortError"));
+  if (!blocks.length) return Promise.resolve([]);
+  if (typeof Worker === "undefined") return highlightingService.prepare(blocks, signal);
+  return new Promise((resolve, reject) => {
+    let worker: Worker;
+    try {
+      worker = new Worker(new URL("./markdownSyntax.worker.ts", import.meta.url), { type: "module" });
+    } catch (error) {
+      reject(error);
+      return;
+    }
+    const results: PreparedCodeBlock[] = [];
+    let block = 0;
+    let workerBlock = 0;
+    let offset = 0;
+    let ranges: SyntaxRange[] = [];
+    let settled = false;
+    let timer: ReturnType<typeof setTimeout>;
+    let delivery: ReturnType<typeof setTimeout> | undefined;
+    const cleanup = () => {
+      clearTimeout(timer);
+      clearTimeout(delivery);
+      signal.removeEventListener("abort", abort);
+      worker.removeEventListener("message", message);
+      worker.removeEventListener("error", error);
+      worker.removeEventListener("messageerror", decode);
+      worker.terminate();
+    };
+    const fail = (failure: unknown) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      reject(failure);
+    };
+    const abort = () => fail(new DOMException("Syntax preparation cancelled", "AbortError"));
+    const error = (event: ErrorEvent) => {
+      event.preventDefault();
+      fail(new Error(`Syntax worker failed; retaining plain text: ${event.message}`));
+    };
+    const decode = () => fail(new Error("Syntax worker response could not be decoded; retaining plain text"));
+    const send = (request: SyntaxWorkerRequest) => {
+      if (settled) return;
+      clearTimeout(timer);
+      timer = setTimeout(() => fail(new Error("Syntax worker made no progress; retaining plain text")), SYNTAX_WORKER_PROGRESS_TIMEOUT_MS);
+      try {
+        worker.postMessage(request);
+      } catch (failure) {
+        fail(failure);
+      }
+    };
+    const source = () => {
+      if (settled) return;
+      while (block < blocks.length) {
+        const request = blocks[block];
+        if (!request) {
+          fail(new Error("Missing syntax source block"));
+          return;
+        }
+        if (request.text.length <= MAX_STATIC_BLOCK_LENGTH) break;
+        results.push({ reason: "block-too-large" });
+        block += 1;
+      }
+      if (block === blocks.length) {
+        settled = true;
+        cleanup();
+        resolve(results);
+        return;
+      }
+      const request = blocks[block];
+      if (!request) {
+        fail(new Error("Missing syntax source block"));
+        return;
+      }
+      const text = request.text.slice(offset, offset + SYNTAX_SOURCE_CHUNK_UNITS);
+      offset += text.length;
+      send({ type: "source", block: workerBlock, text, label: request.label, final: offset === request.text.length });
+    };
+    const message = (event: MessageEvent<SyntaxWorkerResponse>) => {
+      if (settled || signal.aborted) return;
+      try {
+        const response = event.data;
+        if (response.type === "diagnostic") {
+          logError(response.message, response.context, response.component, response.error ? new Error(response.error) : undefined);
+        } else if (response.type === "error") {
+          fail(new Error(response.message));
+        } else if (response.type === "source-ack") {
+          source();
+        } else if (response.type === "ranges") {
+          const request = blocks[block];
+          if (!request || response.block !== workerBlock || response.ranges.length > SYNTAX_RESULT_PAGE_RANGES)
+            throw new Error("Invalid syntax result page");
+          for (const range of response.ranges) {
+            if (range.from < (ranges.at(-1)?.to ?? 0) || range.to <= range.from || range.to > request.text.length)
+              throw new Error("Invalid syntax result offsets");
+            ranges.push(range);
+          }
+          clearTimeout(delivery);
+          delivery = setTimeout(() => send({ type: "ack" }), 0);
+        } else if (response.type === "complete") {
+          if (response.block !== workerBlock) throw new Error("Obsolete syntax block result");
+          results.push(response.reason ? { reason: response.reason } : { ranges });
+          ranges = [];
+          offset = 0;
+          block += 1;
+          workerBlock += 1;
+          source();
+        }
+      } catch (failure) {
+        fail(failure);
+      }
+    };
+    worker.addEventListener("message", message);
+    worker.addEventListener("error", error);
+    worker.addEventListener("messageerror", decode);
+    signal.addEventListener("abort", abort, { once: true });
+    source();
+  });
+}
diff --git a/frontend/src/utils/markdownSyntaxWorkerProtocol.ts b/frontend/src/utils/markdownSyntaxWorkerProtocol.ts
new file mode 100644
index 000000000..a90792b69
--- /dev/null
+++ b/frontend/src/utils/markdownSyntaxWorkerProtocol.ts
@@ -0,0 +1,16 @@
+import type { CodeBlockRequest, PlainTextReason, SyntaxRange } from "./syntaxHighlighting";
+
+export const SYNTAX_SOURCE_CHUNK_UNITS = 16_384;
+export const SYNTAX_RESULT_PAGE_RANGES = 512;
+export const SYNTAX_WORKER_PROGRESS_TIMEOUT_MS = 30_000;
+
+export type SyntaxWorkerRequest =
+  | { type: "source"; block: number; text: string; label: CodeBlockRequest["label"]; final: boolean }
+  | { type: "ack" };
+
+export type SyntaxWorkerResponse =
+  | { type: "source-ack" }
+  | { type: "ranges"; block: number; ranges: SyntaxRange[] }
+  | { type: "complete"; block: number; reason?: PlainTextReason }
+  | { type: "diagnostic"; message: string; context?: Record<string, unknown>; component?: string; error?: string }
+  | { type: "error"; message: string };
diff --git a/frontend/src/utils/randomUuid.ts b/frontend/src/utils/randomUuid.ts
index ee30ddebe..fa6b21cd7 100644
--- a/frontend/src/utils/randomUuid.ts
+++ b/frontend/src/utils/randomUuid.ts
@@ -3,8 +3,9 @@ export function randomUuid(): string {
 
   const bytes = new Uint8Array(16);
   crypto.getRandomValues(bytes);
-  bytes[6] = (bytes[6] & 0x0f) | 0x40;
-  bytes[8] = (bytes[8] & 0x3f) | 0x80;
+  const view = new DataView(bytes.buffer);
+  view.setUint8(6, (view.getUint8(6) & 0x0f) | 0x40);
+  view.setUint8(8, (view.getUint8(8) & 0x3f) | 0x80);
   const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
   return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
 }
diff --git a/frontend/src/utils/syntaxHighlighting.ts b/frontend/src/utils/syntaxHighlighting.ts
new file mode 100644
index 000000000..7e6fbba4a
--- /dev/null
+++ b/frontend/src/utils/syntaxHighlighting.ts
@@ -0,0 +1,81 @@
+export const TOKEN_CATEGORIES = [
+  "keyword",
+  "string",
+  "number",
+  "comment",
+  "type",
+  "function",
+  "operator",
+  "punctuation",
+  "identifier",
+  "builtin",
+  "property",
+  "boolean",
+  "null",
+  "regexp",
+  "escape",
+  "metadata",
+  "heading",
+  "structure",
+  "link",
+  "inlineCode",
+  "emphasis",
+  "strong",
+  "strikethrough",
+] as const;
+
+export type TokenCategory = (typeof TOKEN_CATEGORIES)[number];
+export const TOKEN_COLOR_ROLES = {
+  keyword: "keyword",
+  string: "string",
+  number: "number",
+  comment: "comment",
+  type: "type",
+  function: "function",
+  operator: "operator",
+  punctuation: "punctuation",
+  identifier: "foreground",
+  builtin: "function",
+  property: "type",
+  boolean: "keyword",
+  null: "keyword",
+  regexp: "type",
+  escape: "operator",
+  metadata: "keyword",
+  heading: "keyword",
+  structure: "keyword",
+  link: "link",
+  inlineCode: "foreground",
+  emphasis: "emphasis",
+  strong: "strong",
+  strikethrough: "strikethrough",
+} as const satisfies Record<TokenCategory, string>;
+declare const languageId: unique symbol;
+export type LanguageId = string & { readonly [languageId]: true };
+export type PlainTextReason =
+  | "unknown-language"
+  | "plain-text"
+  | "block-too-large"
+  | "nesting-depth"
+  | "loading-failure"
+  | "parsing-failure";
+export type LanguageResolution = { language: LanguageId } | { reason: "unknown-language" | "plain-text" };
+export interface SyntaxRange {
+  from: number;
+  to: number;
+  categories: readonly TokenCategory[];
+}
+export interface CodeBlockRequest {
+  text: string;
+  label?: string | null;
+}
+export type PreparedCodeBlock = { ranges: readonly SyntaxRange[] } | { reason: PlainTextReason };
+export interface HighlightingService {
+  resolveFilename(filename: string): LanguageResolution;
+  resolveFence(label?: string | null): LanguageResolution;
+  prepare(blocks: readonly CodeBlockRequest[], signal?: AbortSignal): Promise<readonly PreparedCodeBlock[]>;
+}
+
+export function tokenClasses(categories: readonly TokenCategory[]): string {
+  return categories.map((category) => `sambee-syntax-${category}`).join(" ");
+}
diff --git a/frontend/src/utils/version.ts b/frontend/src/utils/version.ts
index 3e634124b..43ad1f576 100644
--- a/frontend/src/utils/version.ts
+++ b/frontend/src/utils/version.ts
@@ -25,7 +25,7 @@ export async function fetchVersionInfo(): Promise<VersionInfo | null> {
 
   try {
     // Use absolute URL for tests (required by MSW), relative for production
-    const baseURL = import.meta.env.VITE_API_URL || (import.meta.env.MODE === "test" ? "http://localhost:3000/api" : "/api");
+    const baseURL = import.meta.env["VITE_API_URL"] || (import.meta.env.MODE === "test" ? "http://localhost:3000/api" : "/api");
     const response = await fetch(`${baseURL}/version`, { signal: abortController.signal });
     if (!response.ok) {
       logger.warn("Failed to fetch version info", { status: response.statusText }, "api");
diff --git a/frontend/src/utils/viewportDomTextSearch.ts b/frontend/src/utils/viewportDomTextSearch.ts
new file mode 100644
index 000000000..539f978b7
--- /dev/null
+++ b/frontend/src/utils/viewportDomTextSearch.ts
@@ -0,0 +1,279 @@
+import { createDomTextIndex, findLogicalMatches, type IndexedDomText, type LogicalMatch } from "./domTextSearch";
+
+export const MAX_VIEWPORT_SEARCH_RANGES = 1_000;
+const SEGMENTS_PER_FRAME = 32;
+const SEARCH_MEASURE_PREFIX = "sambee:preview-search:";
+let sessionId = 0;
+
+function measure<Result>(stage: string, operation: () => Result): Result {
+  const start = performance.now();
+  try {
+    return operation();
+  } finally {
+    const name = `${SEARCH_MEASURE_PREFIX}${stage}`;
+    performance.clearMeasures?.(name);
+    performance.measure?.(name, { start, end: performance.now() });
+  }
+}
+
+export function createViewportDomTextSearch(root: HTMLElement, viewport: HTMLElement, onInvalidated: () => void) {
+  const prefix = `markdown-search-${++sessionId}`;
+  const otherName = `${prefix}-other`;
+  const currentName = `${prefix}-current`;
+  const registry = globalThis.CSS?.highlights;
+  const HighlightType = globalThis.Highlight;
+  const supported = typeof HighlightType !== "undefined" && !!registry && typeof IntersectionObserver !== "undefined";
+  const style = document.createElement("style");
+  style.textContent = `::highlight(${otherName}) { background-color: var(--sambee-search-other); color: var(--sambee-search-foreground); }
+::highlight(${currentName}) { background-color: var(--sambee-search-current); color: var(--sambee-search-foreground); }`;
+  if (supported) document.head.append(style);
+  let indexed: IndexedDomText | null = null;
+  let indexedRevision = 0;
+  let matches: LogicalMatch[] = [];
+  let current = 0;
+  let frame: number | null = null;
+  let disposed = false;
+  let nextSegment = 0;
+  let pendingSegments: number[] = [];
+  const segmentIndices = new Map<Element, number[]>();
+  const visibleSegments = new Set<number>();
+  let ranges: Range[] = [];
+
+  const locate = (offset: number) => {
+    if (!indexed) return undefined;
+    const segments = indexed.segments;
+    let low = 0;
+    let high = segments.length - 1;
+    while (low < high) {
+      const middle = (low + high) >>> 1;
+      const segment = segments[middle];
+      if (segment && segment.end <= offset) low = middle + 1;
+      else high = middle;
+    }
+    return segments[low];
+  };
+  const rangeAt = (from: number, to: number) => {
+    const first = locate(from);
+    const last = locate(Math.max(from, to - 1));
+    if (!first || !last) return null;
+    const range = document.createRange();
+    range.setStart(first.node, Math.min(first.node.length, Math.max(0, from - first.start)));
+    range.setEnd(last.node, Math.min(last.node.length, Math.max(0, to - last.start)));
+    return range;
+  };
+  const firstMatchAt = (offset: number) => {
+    let low = 0;
+    let high = matches.length;
+    while (low < high) {
+      const middle = (low + high) >>> 1;
+      const match = matches[middle];
+      if (match && match.end <= offset) low = middle + 1;
+      else high = middle;
+    }
+    return low;
+  };
+  const paint = () => {
+    frame = null;
+    if (disposed || !supported || !indexed) return;
+    measure("presentation", () => {
+      const bounds = viewport.getBoundingClientRect();
+      const limit = Math.min(pendingSegments.length, nextSegment + SEGMENTS_PER_FRAME);
+      for (; nextSegment < limit && ranges.length < MAX_VIEWPORT_SEARCH_RANGES; nextSegment += 1) {
+        const index = pendingSegments[nextSegment];
+        if (index === undefined) continue;
+        const segment = indexed?.segments[index];
+        if (!segment) continue;
+        const parent = segment.node.parentElement;
+        if (!parent) continue;
+        const box = parent.getBoundingClientRect();
+        if (box.bottom < bounds.top || box.top > bounds.bottom) continue;
+        const offsetAt = (top: number) => {
+          let low = segment.start;
+          let high = segment.end;
+          while (low < high) {
+            const middle = (low + high) >>> 1;
+            const range = rangeAt(middle, middle + 1)!;
+            if (range.getBoundingClientRect().bottom < top) low = middle + 1;
+            else high = middle;
+          }
+          return low;
+        };
+        const from = box.top >= bounds.top ? segment.start : offsetAt(bounds.top);
+        const to = box.bottom <= bounds.bottom ? segment.end : Math.min(segment.end, offsetAt(bounds.bottom) + 1);
+        const pre = parent.closest("pre");
+        const horizontal =
+          pre &&
+          pre.scrollWidth > pre.clientWidth &&
+          getComputedStyle(pre).whiteSpace === "pre" &&
+          getComputedStyle(pre).direction !== "rtl";
+        const clip = horizontal ? pre.getBoundingClientRect() : bounds;
+        if (horizontal && (clip.right < bounds.left || clip.left > bounds.right)) continue;
+        let lineStart = from;
+        while (lineStart < to && ranges.length < MAX_VIEWPORT_SEARCH_RANGES) {
+          const newline = horizontal ? segment.node.data.indexOf("\n", lineStart - segment.start) : -1;
+          const lineEnd = newline < 0 ? to : Math.min(to, segment.start + newline + 1);
+          const columnAt = (edge: number, start = lineStart) => {
+            let low = start;
+            let high = lineEnd;
+            if (low < high && rangeAt(low, low + 1)!.getBoundingClientRect().right >= edge) return low;
+            while (low < high) {
+              const middle = (low + high) >>> 1;
+              if (rangeAt(middle, middle + 1)!.getBoundingClientRect().right < edge) low = middle + 1;
+              else high = middle;
+            }
+            return low;
+          };
+          const visibleFrom = horizontal ? columnAt(Math.max(bounds.left, clip.left)) : lineStart;
+          const visibleTo = horizontal ? Math.min(lineEnd, columnAt(Math.min(bounds.right, clip.right), visibleFrom) + 1) : lineEnd;
+          for (let index = firstMatchAt(visibleFrom); index < matches.length && ranges.length < MAX_VIEWPORT_SEARCH_RANGES; index += 1) {
+            const match = matches[index];
+            if (!match || match.start >= visibleTo) break;
+            const range = rangeAt(Math.max(visibleFrom, match.start), Math.min(visibleTo, match.end));
+            if (range) ranges.push(range);
+          }
+          lineStart = lineEnd;
+        }
+      }
+      registry.set(otherName, new HighlightType(...ranges));
+      if (nextSegment < pendingSegments.length && ranges.length < MAX_VIEWPORT_SEARCH_RANGES) frame = requestAnimationFrame(paint);
+    });
+  };
+  const refresh = () => {
+    if (disposed) return;
+    ranges = [];
+    pendingSegments = [...visibleSegments].sort((left, right) => left - right);
+    nextSegment = 0;
+    if (supported) {
+      if (!matches.length) {
+        registry.delete(otherName);
+        if (frame !== null) cancelAnimationFrame(frame);
+        frame = null;
+      } else if (frame === null) frame = requestAnimationFrame(paint);
+    }
+  };
+  const intersections = supported
+    ? new IntersectionObserver(
+        (entries) => {
+          for (const entry of entries) {
+            for (const index of segmentIndices.get(entry.target) ?? []) {
+              if (entry.isIntersecting) visibleSegments.add(index);
+              else visibleSegments.delete(index);
+            }
+          }
+          refresh();
+        },
+        { root: viewport }
+      )
+    : null;
+  const resetVisibility = () => {
+    intersections?.disconnect();
+    segmentIndices.clear();
+    visibleSegments.clear();
+  };
+  const observeSegments = () => {
+    resetVisibility();
+    if (!supported || !indexed) return;
+    indexed.segments.forEach((segment, index) => {
+      const parent = segment.node.parentElement;
+      if (!parent) return;
+      const indices = segmentIndices.get(parent) ?? [];
+      indices.push(index);
+      segmentIndices.set(parent, indices);
+    });
+    for (const parent of segmentIndices.keys()) intersections?.observe(parent);
+  };
+  const activate = (match: number, scroll = true) => {
+    if (disposed || current === match) return;
+    current = match;
+    if (supported) registry.delete(currentName);
+    const logical = matches[current - 1];
+    if (!logical || !indexed) return;
+    const range = measure("navigation-lookup", () => rangeAt(logical.start, logical.end));
+    if (!range) return;
+    if (supported) {
+      measure("navigation-publication", () => {
+        const highlight = new HighlightType(range);
+        highlight.priority = 1;
+        registry.set(currentName, highlight);
+      });
+    }
+    if (scroll && typeof range.getBoundingClientRect === "function") {
+      const { box, bounds } = measure("navigation-geometry", () => ({
+        box: range.getBoundingClientRect(),
+        bounds: viewport.getBoundingClientRect(),
+      }));
+      measure("navigation-scroll", () => {
+        viewport.scrollTop += box.top - bounds.top - viewport.clientHeight / 2;
+        const pre = locate(logical.start)?.node.parentElement?.closest("pre");
+        if (pre && pre.scrollWidth > pre.clientWidth) {
+          pre.scrollLeft += box.left - pre.getBoundingClientRect().left - pre.clientWidth / 2;
+        }
+      });
+      refresh();
+    }
+  };
+  const invalidate = () => {
+    if (disposed) return;
+    indexed = null;
+    resetVisibility();
+    matches = [];
+    current = 0;
+    if (supported) registry.delete(currentName);
+    refresh();
+    onInvalidated();
+  };
+  const mutations = new MutationObserver(invalidate);
+  mutations.observe(root, { subtree: true, childList: true, characterData: true });
+  const resize = new ResizeObserver(refresh);
+  resize.observe(viewport);
+  viewport.addEventListener("scroll", refresh, { passive: true });
+  root.addEventListener("scroll", refresh, { capture: true, passive: true });
+  root.addEventListener("load", refresh, true);
+  document.fonts?.addEventListener("loadingdone", refresh);
+
+  return {
+    supported,
+    setQuery(query: string, revision = 0): number {
+      if (disposed) return 0;
+      if (mutations.takeRecords().length || indexedRevision !== revision) indexed = null;
+      indexedRevision = revision;
+      if (query.trim()) {
+        if (!indexed) {
+          indexed = measure("capture", () => createDomTextIndex(root));
+          observeSegments();
+        }
+        matches = measure("matching", () => findLogicalMatches(indexed!.fullText, query));
+      } else {
+        matches = [];
+      }
+      current = 0;
+      if (supported) {
+        registry.delete(currentName);
+        registry.delete(otherName);
+      }
+      measure("clear", refresh);
+      return matches.length;
+    },
+    activate,
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      resetVisibility();
+      mutations.disconnect();
+      resize.disconnect();
+      viewport.removeEventListener("scroll", refresh);
+      root.removeEventListener("scroll", refresh, true);
+      root.removeEventListener("load", refresh, true);
+      document.fonts?.removeEventListener("loadingdone", refresh);
+      if (frame !== null) cancelAnimationFrame(frame);
+      if (supported) {
+        registry.delete(otherName);
+        registry.delete(currentName);
+      }
+      indexed = null;
+      matches = [];
+      ranges = [];
+      style.remove();
+    },
+  };
+}
diff --git a/frontend/tsconfig.app.json b/frontend/tsconfig.app.json
index 0f1940ddb..930cdb85f 100644
--- a/frontend/tsconfig.app.json
+++ b/frontend/tsconfig.app.json
@@ -3,7 +3,7 @@
     "target": "ES2020",
     "useDefineForClassFields": true,
     "lib": [
-      "ES2020",
+      "ES2023",
       "DOM",
       "DOM.Iterable"
     ],
@@ -17,6 +17,9 @@
     "moduleDetection": "force",
     "noEmit": true,
     "jsx": "react-jsx",
+    "types": [
+      "vite/client"
+    ],
     /* Linting */
     "strict": true,
     "noUnusedLocals": true,
@@ -27,5 +30,11 @@
   },
   "include": [
     "src"
+  ],
+  "exclude": [
+    "src/**/__tests__/**",
+    "src/**/*.test.ts",
+    "src/**/*.test.tsx",
+    "src/test/**"
   ]
 }
diff --git a/frontend/tsconfig.app.tsbuildinfo b/frontend/tsconfig.app.tsbuildinfo
new file mode 100644
index 000000000..c0082458c
--- /dev/null
+++ b/frontend/tsconfig.app.tsbuildinfo
@@ -0,0 +1 @@
+{"version":"7.0.2","root":["./src/App.tsx","./src/browserBootstrap.ts","./src/index.tsx","./src/vite-env.d.ts","./src/__mocks__/@tanstack/react-virtual.tsx","./src/components/AppUpdatePrompt.tsx","./src/components/CompactBadge.tsx","./src/components/ErrorBoundary.tsx","./src/components/KeyboardShortcutsHelp.tsx","./src/components/ResizableDialog.tsx","./src/components/SambeeLogo.tsx","./src/components/ThemeSelector.tsx","./src/components/themeSelectorStrings.ts","./src/components/Admin/ConnectionDialog.tsx","./src/components/Admin/ConnectionList.tsx","./src/components/Admin/DeleteDialog.tsx","./src/components/Admin/connectionDialogConstants.ts","./src/components/Admin/dialogActionStyles.ts","./src/components/Dialog/DialogNotice.tsx","./src/components/Dialog/DialogReadOnlyField.tsx","./src/components/Dialog/ResponsiveDialogShell.tsx","./src/components/Editor/SourceTextEditor.tsx","./src/components/Editor/buildCodeMirrorSearchHighlights.ts","./src/components/Editor/buildCodeMirrorSurfaceTheme.ts","./src/components/Editor/buildCommonEditorExtensions.ts","./src/components/Editor/buildEditorSelectionLayer.ts","./src/components/Editor/buildMarkdownAutocomplete.ts","./src/components/Editor/buildMarkdownEditorExtensions.ts","./src/components/Editor/buildMarkdownEditorTheme.ts","./src/components/Editor/buildMarkdownTableTheme.ts","./src/components/Editor/buildTextEditorTheme.ts","./src/components/Editor/codeMirrorSearchMatches.ts","./src/components/Editor/getCodeMirrorHorizontalInset.ts","./src/components/Editor/sourceRegexSearch.ts","./src/components/Editor/sourceRegexSearch.worker.ts","./src/components/Editor/sourceRegexSearchProtocol.ts","./src/components/Editor/sourceReplacementFeedback.ts","./src/components/Editor/sourceTextEditorTypes.ts","./src/components/FileBrowser/ArchiveExtractDialog.tsx","./src/components/FileBrowser/ArchiveMemberErrorResolver.tsx","./src/components/FileBrowser/ArchiveOperationProgress.tsx","./src/components/FileBrowser/BreadcrumbsNavigation.tsx","./src/components/FileBrowser/BrowserViewerPicker.tsx","./src/components/FileBrowser/CompactCreateMenu.tsx","./src/components/FileBrowser/CompactItemActionsMenu.tsx","./src/components/FileBrowser/CompactSelectionActions.tsx","./src/components/FileBrowser/CompanionPairingDialog.tsx","./src/components/FileBrowser/ConfirmDeleteDialog.tsx","./src/components/FileBrowser/ConnectionSelector.tsx","./src/components/FileBrowser/CopyMoveDialog.tsx","./src/components/FileBrowser/CreateItemDialog.tsx","./src/components/FileBrowser/DesktopToolbar.tsx","./src/components/FileBrowser/DesktopToolbarActions.tsx","./src/components/FileBrowser/DialogIdentifierDisplay.tsx","./src/components/FileBrowser/DialogOperationContext.tsx","./src/components/FileBrowser/DynamicViewer.tsx","./src/components/FileBrowser/EmptyStateIllustration.tsx","./src/components/FileBrowser/FileBrowserAlerts.tsx","./src/components/FileBrowser/FileList.tsx","./src/components/FileBrowser/FileOperationsToolbar.tsx","./src/components/FileBrowser/FileRow.tsx","./src/components/FileBrowser/FileRowButton.tsx","./src/components/FileBrowser/HelpMenu.tsx","./src/components/FileBrowser/InlineItemName.tsx","./src/components/FileBrowser/MobileToolbar.tsx","./src/components/FileBrowser/NameInputDialog.tsx","./src/components/FileBrowser/OverwriteConflictDialog.tsx","./src/components/FileBrowser/PillButtonTooltip.tsx","./src/components/FileBrowser/QuickBarResultRow.tsx","./src/components/FileBrowser/RenameDialog.tsx","./src/components/FileBrowser/SearchBar.tsx","./src/components/FileBrowser/SecondaryActionStrip.tsx","./src/components/FileBrowser/SortControls.tsx","./src/components/FileBrowser/StatusBar.tsx","./src/components/FileBrowser/ToolbarIconButton.tsx","./src/components/FileBrowser/UnifiedSearchBar.tsx","./src/components/FileBrowser/ViewModeSelector.tsx","./src/components/FileBrowser/confirmDeleteDialogStrings.ts","./src/components/FileBrowser/copyMoveDialogStrings.ts","./src/components/FileBrowser/createItemDialogStrings.ts","./src/components/FileBrowser/filenameFieldProps.ts","./src/components/FileBrowser/formatConnectionPath.ts","./src/components/FileBrowser/itemNameNormalization.ts","./src/components/FileBrowser/nameDialogStrings.ts","./src/components/FileBrowser/overwriteConflictStrings.ts","./src/components/FileBrowser/renameDialogStrings.ts","./src/components/FileBrowser/sortControlsStrings.ts","./src/components/FileBrowser/statusBarStrings.ts","./src/components/FileBrowser/viewModeSelectorStrings.ts","./src/components/FileBrowser/search/index.ts","./src/components/FileBrowser/search/normalizeQuerySeparators.ts","./src/components/FileBrowser/search/recentHistory.ts","./src/components/FileBrowser/search/types.ts","./src/components/FileBrowser/search/useBrowserCommandsProvider.tsx","./src/components/FileBrowser/search/useDirectorySearchProvider.tsx","./src/components/FileBrowser/search/useFileSearchProvider.tsx","./src/components/FileBrowser/search/useSmartBrowserSearchProvider.tsx","./src/components/Form/FormLayout.tsx","./src/components/Mobile/HamburgerMenu.tsx","./src/components/Mobile/MobileSettingsDrawer.tsx","./src/components/Settings/SettingSaveStatus.tsx","./src/components/Settings/SettingsActionBar.tsx","./src/components/Settings/SettingsCategoryContent.tsx","./src/components/Settings/SettingsCategoryDescription.tsx","./src/components/Settings/SettingsCategoryList.tsx","./src/components/Settings/SettingsDialog.tsx","./src/components/Settings/SettingsFeedback.tsx","./src/components/Settings/SettingsFieldHelp.tsx","./src/components/Settings/SettingsFormLayout.tsx","./src/components/Settings/SettingsGroup.tsx","./src/components/Settings/SettingsLayout.tsx","./src/components/Settings/SettingsList.tsx","./src/components/Settings/SettingsPage.tsx","./src/components/Settings/SettingsPasswordVisibilityToggle.tsx","./src/components/Settings/SettingsSectionHeader.tsx","./src/components/Settings/SettingsSectionList.tsx","./src/components/Settings/SettingsSelectMenuItem.tsx","./src/components/Settings/SettingsSidebar.tsx","./src/components/Settings/SettingsState.tsx","./src/components/Settings/ThemeEditorDialog.tsx","./src/components/Settings/localDrivesCopy.ts","./src/components/Settings/settingsButtonStyles.ts","./src/components/Settings/settingsCategories.ts","./src/components/Settings/settingsDataSources.ts","./src/components/Settings/settingsDialogSize.ts","./src/components/Settings/settingsNavigation.ts","./src/components/Settings/settingsSurface.ts","./src/components/Settings/settingsTypographyStyles.ts","./src/components/Settings/useSettingsAccess.ts","./src/components/Sharing/ViewerShareMenu.tsx","./src/components/Sharing/useNativeSharing.tsx","./src/components/Viewer/CodeMirrorFindReplacePopover.tsx","./src/components/Viewer/ImageControls.tsx","./src/components/Viewer/ImageViewer.tsx","./src/components/Viewer/MarkdownEditorErrorBoundary.tsx","./src/components/Viewer/MarkdownRichEditor.tsx","./src/components/Viewer/MarkdownViewer.tsx","./src/components/Viewer/PDFControls.tsx","./src/components/Viewer/PDFViewer.tsx","./src/components/Viewer/ProgressiveMarkdown.tsx","./src/components/Viewer/RecoveredDraftDialog.tsx","./src/components/Viewer/RetainedMarkdownPreview.tsx","./src/components/Viewer/TextCodeEditor.tsx","./src/components/Viewer/TextViewer.tsx","./src/components/Viewer/ViewerControls.tsx","./src/components/Viewer/codeMirrorFindReplace.ts","./src/components/Viewer/codeMirrorFindReplaceConstants.ts","./src/components/Viewer/codeMirrorFindReplaceHistory.ts","./src/components/Viewer/focusRestoration.ts","./src/components/Viewer/loadMarkdownRichEditor.ts","./src/components/Viewer/markdownDebugTrace.ts","./src/components/Viewer/markdownEditorConstants.ts","./src/components/Viewer/markdownSearchState.ts","./src/components/Viewer/markdownTableCellLineBreaks.ts","./src/components/Viewer/useMarkdownEditSession.ts","./src/components/Viewer/viewerContent.ts","./src/components/Viewer/viewerToolbarActions.tsx","./src/config/browserCommands.ts","./src/config/keyboardShortcuts.ts","./src/hooks/useApiRetry.ts","./src/hooks/useBackendRecoveryMonitor.ts","./src/hooks/useCachedAsyncData.ts","./src/hooks/useCachedImageGallery.ts","./src/hooks/useCompanion.ts","./src/hooks/useDraftRecoveryCleanup.ts","./src/hooks/useFocusTrap.ts","./src/hooks/useKeyboardShortcuts.ts","./src/hooks/usePillButtonMenu.ts","./src/hooks/useRemoveLocationFragment.ts","./src/hooks/useRestoreFocusAfterPending.ts","./src/hooks/useRoutedViewerEditing.tsx","./src/hooks/useSelectableListbox.ts","./src/hooks/useSwipeGesture.ts","./src/hooks/useSystemSettingPersistence.tsx","./src/hooks/useViewerSharing.ts","./src/i18n/CompanionLocalizationSync.tsx","./src/i18n/LocalePreferencesProvider.tsx","./src/i18n/i18next.d.ts","./src/i18n/index.ts","./src/i18n/resources.ts","./src/pages/AboutSettings.tsx","./src/pages/AccountSettings.tsx","./src/pages/AdvancedSettings.tsx","./src/pages/AuthenticationSettings.tsx","./src/pages/ConnectionSettings.tsx","./src/pages/ConnectionsSettings.tsx","./src/pages/FileBrowser.tsx","./src/pages/FileBrowserSettings.tsx","./src/pages/FileSearchSettings.tsx","./src/pages/LocalDrivesSettings.tsx","./src/pages/Login.tsx","./src/pages/NetworkSettings.tsx","./src/pages/OidcCallback.tsx","./src/pages/PasswordChange.tsx","./src/pages/PreferencesSettings.tsx","./src/pages/SmbSettings.tsx","./src/pages/TextEditorSettings.tsx","./src/pages/UserManagementSettings.tsx","./src/pages/FileBrowser/FileBrowserPane.tsx","./src/pages/FileBrowser/access.ts","./src/pages/FileBrowser/archiveExtractionExecution.ts","./src/pages/FileBrowser/browserUploadManifest.ts","./src/pages/FileBrowser/contentOperations.ts","./src/pages/FileBrowser/contentProviders.ts","./src/pages/FileBrowser/fileOperationActions.ts","./src/pages/FileBrowser/formatters.ts","./src/pages/FileBrowser/itemActionAvailability.ts","./src/pages/FileBrowser/preferences.ts","./src/pages/FileBrowser/routing.ts","./src/pages/FileBrowser/types.ts","./src/pages/FileBrowser/useBrowserDownload.ts","./src/pages/FileBrowser/useBrowserUpload.ts","./src/pages/FileBrowser/useFileBrowserPane.ts","./src/pages/FileBrowser/useWorkspaceNavigation.ts","./src/pages/FileBrowser/viewerPreferences.ts","./src/services/accountSession.ts","./src/services/api.ts","./src/services/authConfig.ts","./src/services/authSession.ts","./src/services/backendAvailability.ts","./src/services/backendRecoveryEvents.ts","./src/services/backendRouter.ts","./src/services/browserConnectionCatalogService.ts","./src/services/browserContentServices.ts","./src/services/browserHistoryService.ts","./src/services/browserLinkTargetService.ts","./src/services/browserRecoverySnapshot.ts","./src/services/companion.ts","./src/services/companionLocalizationSync.ts","./src/services/companionSession.ts","./src/services/draftCheckpoint.ts","./src/services/draftRecovery.ts","./src/services/editLockRecovery.ts","./src/services/foregroundArchiveOperation.ts","./src/services/foregroundTransferOperation.ts","./src/services/historySync.ts","./src/services/localDrivePairing.ts","./src/services/logBuffer.ts","./src/services/logTransport.ts","./src/services/logger.ts","./src/services/loggingConfig.ts","./src/services/oidcAuth.ts","./src/services/passwordChange.ts","./src/services/previewPolicy.ts","./src/services/recentDirectoriesSync.ts","./src/services/recentFilesSync.ts","./src/services/runtimeWarmup.ts","./src/services/serverWebsocket.ts","./src/services/settingSaveFeedback.ts","./src/services/storageArchiveOperations.ts","./src/services/storageBackends.ts","./src/services/storageContracts.ts","./src/services/storageRegistry.ts","./src/services/storageTransferOperations.ts","./src/services/userSettingsStore.ts","./src/theme/ThemeContext.tsx","./src/theme/commonStyles.ts","./src/theme/constants.ts","./src/theme/index.ts","./src/theme/mobileShell.ts","./src/theme/mui-theme-extensions.d.ts","./src/theme/palette.ts","./src/theme/resolveSyntaxTheme.ts","./src/theme/syntaxStyles.ts","./src/theme/themeDefinition.ts","./src/theme/themes.ts","./src/theme/types.ts","./src/theme/viewerStyles.ts","./src/types/index.ts","./src/utils/FileTypeRegistry.ts","./src/utils/apiErrors.ts","./src/utils/buildInfo.ts","./src/utils/codeMirrorHighlighting.ts","./src/utils/codeMirrorHighlightingCore.ts","./src/utils/domTextSearch.ts","./src/utils/externalLinks.ts","./src/utils/fileEntries.ts","./src/utils/fileIcons.tsx","./src/utils/highlightingService.ts","./src/utils/keyboardUtils.ts","./src/utils/localeFormatting.ts","./src/utils/markdownCodePreparation.ts","./src/utils/markdownCodePreparation.worker.ts","./src/utils/markdownCodePreparationProtocol.ts","./src/utils/markdownCodePreviewModel.ts","./src/utils/markdownDocumentPreview.tsx","./src/utils/markdownDocumentPreviewModel.ts","./src/utils/markdownDocumentSearch.ts","./src/utils/markdownDocumentSearch.worker.ts","./src/utils/markdownDocumentSearchWorker.ts","./src/utils/markdownHeadingLinks.ts","./src/utils/markdownPreparedTree.ts","./src/utils/markdownSyntax.ts","./src/utils/markdownSyntax.worker.ts","./src/utils/markdownSyntaxPublication.ts","./src/utils/markdownSyntaxWorker.ts","./src/utils/markdownSyntaxWorkerProtocol.ts","./src/utils/nativeShare.ts","./src/utils/pathDisplay.ts","./src/utils/randomUuid.ts","./src/utils/syntaxHighlighting.ts","./src/utils/userAccess.ts","./src/utils/version.ts","./src/utils/viewportDomTextSearch.ts"],"packageJsons":["./node_modules/@codemirror/autocomplete/package.json","./node_modules/@codemirror/commands/package.json","./node_modules/@codemirror/lang-markdown/package.json","./node_modules/@codemirror/language-data/package.json","./node_modules/@codemirror/language/package.json","./node_modules/@codemirror/search/package.json","./node_modules/@codemirror/state/package.json","./node_modules/@codemirror/streamparser/package.json","./node_modules/@codemirror/view/package.json","./node_modules/@emotion/cache/package.json","./node_modules/@emotion/react/package.json","./node_modules/@emotion/serialize/package.json","./node_modules/@emotion/sheet/package.json","./node_modules/@emotion/styled/package.json","./node_modules/@emotion/utils/package.json","./node_modules/@lezer/common/package.json","./node_modules/@lezer/highlight/package.json","./node_modules/@lezer/lr/package.json","./node_modules/@lezer/markdown/package.json","./node_modules/@mui/icons-material/package.json","./node_modules/@mui/material/package.json","./node_modules/@mui/private-theming/package.json","./node_modules/@mui/styled-engine/package.json","./node_modules/@mui/system/package.json","./node_modules/@mui/types/package.json","./node_modules/@mui/utils/package.json","./node_modules/@popperjs/core/package.json","./node_modules/@react-spring/animated/package.json","./node_modules/@react-spring/core/package.json","./node_modules/@react-spring/rafz/package.json","./node_modules/@react-spring/shared/package.json","./node_modules/@react-spring/types/package.json","./node_modules/@react-spring/web/package.json","./node_modules/@tanstack/react-virtual/package.json","./node_modules/@tanstack/virtual-core/package.json","./node_modules/@types/chai/package.json","./node_modules/@types/deep-eql/package.json","./node_modules/@types/hast/package.json","./node_modules/@types/mdast/package.json","./node_modules/@types/node/package.json","./node_modules/@types/prop-types/package.json","./node_modules/@types/react-dom/package.json","./node_modules/@types/react/package.json","./node_modules/@types/unist/package.json","./node_modules/@use-gesture/core/actions/package.json","./node_modules/@use-gesture/core/package.json","./node_modules/@use-gesture/core/types/package.json","./node_modules/@use-gesture/core/utils/package.json","./node_modules/@use-gesture/react/package.json","./node_modules/@vitest/coverage-v8/package.json","./node_modules/@vitest/mocker/package.json","./node_modules/@vitest/ui/package.json","./node_modules/assertion-error/package.json","./node_modules/axios/package.json","./node_modules/chai/package.json","./node_modules/codemirror-markdown-tables/package.json","./node_modules/cookie-es/package.json","./node_modules/csstype/package.json","./node_modules/expect-type/package.json","./node_modules/i18next/package.json","./node_modules/jsdom/package.json","./node_modules/make-event-props/package.json","./node_modules/markdown-table/package.json","./node_modules/mdast-util-from-markdown/package.json","./node_modules/mdast-util-gfm-footnote/package.json","./node_modules/mdast-util-gfm-table/package.json","./node_modules/mdast-util-gfm/package.json","./node_modules/mdast-util-to-hast/package.json","./node_modules/mdast-util-to-markdown/package.json","./node_modules/micromark-extension-gfm-footnote/package.json","./node_modules/micromark-extension-gfm-strikethrough/package.json","./node_modules/micromark-extension-gfm/package.json","./node_modules/micromark-util-types/package.json","./node_modules/msw/package.json","./node_modules/pdfjs-dist/package.json","./node_modules/prop-types/package.json","./node_modules/react-colorful/package.json","./node_modules/react-dom/package.json","./node_modules/react-i18next/package.json","./node_modules/react-markdown/package.json","./node_modules/react-pdf/package.json","./node_modules/react-router-dom/package.json","./node_modules/react-router/package.json","./node_modules/react/package.json","./node_modules/rehype-slug/package.json","./node_modules/remark-gfm/package.json","./node_modules/remark-parse/package.json","./node_modules/remark-rehype/package.json","./node_modules/style-mod/package.json","./node_modules/tinybench/package.json","./node_modules/trough/package.json","./node_modules/typescript/package.json","./node_modules/unified/package.json","./node_modules/unist-util-is/package.json","./node_modules/unist-util-visit-parents/package.json","./node_modules/unist-util-visit/package.json","./node_modules/vfile-message/package.json","./node_modules/vfile/package.json","./node_modules/vite/package.json","./node_modules/vitest/package.json","./node_modules/yet-another-react-lightbox/package.json","./package.json"],"missingPackageJsons":["./node_modules/@codemirror/autocomplete/dist/package.json","./node_modules/@codemirror/commands/dist/package.json","./node_modules/@codemirror/lang-markdown/dist/package.json","./node_modules/@codemirror/language-data/dist/package.json","./node_modules/@codemirror/language/dist/package.json","./node_modules/@codemirror/search/dist/package.json","./node_modules/@codemirror/state/dist/package.json","./node_modules/@codemirror/streamparser/dist/package.json","./node_modules/@codemirror/view/dist/package.json","./node_modules/@edge-runtime/vm/package.json","./node_modules/@emotion/cache/dist/declarations/package.json","./node_modules/@emotion/cache/dist/declarations/src/package.json","./node_modules/@emotion/cache/dist/package.json","./node_modules/@emotion/react/dist/declarations/package.json","./node_modules/@emotion/react/dist/declarations/src/package.json","./node_modules/@emotion/react/dist/package.json","./node_modules/@emotion/serialize/dist/declarations/package.json","./node_modules/@emotion/serialize/dist/declarations/src/package.json","./node_modules/@emotion/serialize/dist/package.json","./node_modules/@emotion/sheet/dist/declarations/package.json","./node_modules/@emotion/sheet/dist/declarations/src/package.json","./node_modules/@emotion/sheet/dist/package.json","./node_modules/@emotion/styled/dist/declarations/package.json","./node_modules/@emotion/styled/dist/declarations/src/package.json","./node_modules/@emotion/styled/dist/package.json","./node_modules/@emotion/utils/dist/declarations/package.json","./node_modules/@emotion/utils/dist/declarations/src/package.json","./node_modules/@emotion/utils/dist/package.json","./node_modules/@lezer/common/dist/package.json","./node_modules/@lezer/highlight/dist/package.json","./node_modules/@lezer/lr/dist/package.json","./node_modules/@lezer/markdown/dist/package.json","./node_modules/@mui/icons-material/Add/package.json","./node_modules/@mui/icons-material/ArrowBack/package.json","./node_modules/@mui/icons-material/ArrowDownward/package.json","./node_modules/@mui/icons-material/ArrowDropDown/package.json","./node_modules/@mui/icons-material/ArrowUpward/package.json","./node_modules/@mui/icons-material/ArrowUpwardOutlined/package.json","./node_modules/@mui/icons-material/BlockOutlined/package.json","./node_modules/@mui/icons-material/BugReportOutlined/package.json","./node_modules/@mui/icons-material/CheckCircle/package.json","./node_modules/@mui/icons-material/CheckCircleOutlined/package.json","./node_modules/@mui/icons-material/CircleOutlined/package.json","./node_modules/@mui/icons-material/Clear/package.json","./node_modules/@mui/icons-material/Close/package.json","./node_modules/@mui/icons-material/CloudUploadOutlined/package.json","./node_modules/@mui/icons-material/Computer/package.json","./node_modules/@mui/icons-material/ContentCopy/package.json","./node_modules/@mui/icons-material/Delete/package.json","./node_modules/@mui/icons-material/DeleteSweep/package.json","./node_modules/@mui/icons-material/DescriptionOutlined/package.json","./node_modules/@mui/icons-material/Download/package.json","./node_modules/@mui/icons-material/Edit/package.json","./node_modules/@mui/icons-material/EditNote/package.json","./node_modules/@mui/icons-material/ErrorOutlineOutlined/package.json","./node_modules/@mui/icons-material/ExpandMore/package.json","./node_modules/@mui/icons-material/Folder/package.json","./node_modules/@mui/icons-material/ForumOutlined/package.json","./node_modules/@mui/icons-material/HelpOutlineOutlined/package.json","./node_modules/@mui/icons-material/HistoryOutlined/package.json","./node_modules/@mui/icons-material/Home/package.json","./node_modules/@mui/icons-material/IosShare/package.json","./node_modules/@mui/icons-material/Keyboard/package.json","./node_modules/@mui/icons-material/KeyboardCommandKey/package.json","./node_modules/@mui/icons-material/Lan/package.json","./node_modules/@mui/icons-material/LinkOff/package.json","./node_modules/@mui/icons-material/MoreVert/package.json","./node_modules/@mui/icons-material/Notes/package.json","./node_modules/@mui/icons-material/OpenInNew/package.json","./node_modules/@mui/icons-material/RadioButtonUnchecked/package.json","./node_modules/@mui/icons-material/Refresh/package.json","./node_modules/@mui/icons-material/RestartAlt/package.json","./node_modules/@mui/icons-material/Search/package.json","./node_modules/@mui/icons-material/Settings/package.json","./node_modules/@mui/icons-material/Shortcut/package.json","./node_modules/@mui/icons-material/Star/package.json","./node_modules/@mui/icons-material/Usb/package.json","./node_modules/@mui/icons-material/VerticalSplit/package.json","./node_modules/@mui/icons-material/ViewList/package.json","./node_modules/@mui/icons-material/ViewModule/package.json","./node_modules/@mui/icons-material/Visibility/package.json","./node_modules/@mui/material-pigment-css/package.json","./node_modules/@mui/material/Accordion/package.json","./node_modules/@mui/material/AccordionActions/package.json","./node_modules/@mui/material/AccordionDetails/package.json","./node_modules/@mui/material/AccordionSummary/package.json","./node_modules/@mui/material/Alert/package.json","./node_modules/@mui/material/AlertTitle/package.json","./node_modules/@mui/material/AppBar/package.json","./node_modules/@mui/material/Autocomplete/package.json","./node_modules/@mui/material/Avatar/package.json","./node_modules/@mui/material/AvatarGroup/package.json","./node_modules/@mui/material/Backdrop/package.json","./node_modules/@mui/material/Badge/package.json","./node_modules/@mui/material/BottomNavigation/package.json","./node_modules/@mui/material/BottomNavigationAction/package.json","./node_modules/@mui/material/Box/package.json","./node_modules/@mui/material/Breadcrumbs/package.json","./node_modules/@mui/material/Button/package.json","./node_modules/@mui/material/ButtonBase/package.json","./node_modules/@mui/material/ButtonGroup/package.json","./node_modules/@mui/material/Card/package.json","./node_modules/@mui/material/CardActionArea/package.json","./node_modules/@mui/material/CardActions/package.json","./node_modules/@mui/material/CardContent/package.json","./node_modules/@mui/material/CardHeader/package.json","./node_modules/@mui/material/CardMedia/package.json","./node_modules/@mui/material/Checkbox/package.json","./node_modules/@mui/material/Chip/package.json","./node_modules/@mui/material/CircularProgress/package.json","./node_modules/@mui/material/ClickAwayListener/package.json","./node_modules/@mui/material/Collapse/package.json","./node_modules/@mui/material/Container/package.json","./node_modules/@mui/material/CssBaseline/package.json","./node_modules/@mui/material/Dialog/package.json","./node_modules/@mui/material/DialogActions/package.json","./node_modules/@mui/material/DialogContent/package.json","./node_modules/@mui/material/DialogContentText/package.json","./node_modules/@mui/material/DialogTitle/package.json","./node_modules/@mui/material/Divider/package.json","./node_modules/@mui/material/Drawer/package.json","./node_modules/@mui/material/Fab/package.json","./node_modules/@mui/material/Fade/package.json","./node_modules/@mui/material/FilledInput/package.json","./node_modules/@mui/material/FormControl/package.json","./node_modules/@mui/material/FormControlLabel/package.json","./node_modules/@mui/material/FormGroup/package.json","./node_modules/@mui/material/FormHelperText/package.json","./node_modules/@mui/material/FormLabel/package.json","./node_modules/@mui/material/GlobalStyles/package.json","./node_modules/@mui/material/Grid/package.json","./node_modules/@mui/material/Grow/package.json","./node_modules/@mui/material/Icon/package.json","./node_modules/@mui/material/IconButton/package.json","./node_modules/@mui/material/ImageList/package.json","./node_modules/@mui/material/ImageListItem/package.json","./node_modules/@mui/material/ImageListItemBar/package.json","./node_modules/@mui/material/InitColorSchemeScript/package.json","./node_modules/@mui/material/Input/package.json","./node_modules/@mui/material/InputAdornment/package.json","./node_modules/@mui/material/InputBase/package.json","./node_modules/@mui/material/InputLabel/package.json","./node_modules/@mui/material/LinearProgress/package.json","./node_modules/@mui/material/Link/package.json","./node_modules/@mui/material/List/package.json","./node_modules/@mui/material/ListItem/package.json","./node_modules/@mui/material/ListItemAvatar/package.json","./node_modules/@mui/material/ListItemButton/package.json","./node_modules/@mui/material/ListItemIcon/package.json","./node_modules/@mui/material/ListItemSecondaryAction/package.json","./node_modules/@mui/material/ListItemText/package.json","./node_modules/@mui/material/ListSubheader/package.json","./node_modules/@mui/material/Menu/package.json","./node_modules/@mui/material/MenuItem/package.json","./node_modules/@mui/material/MenuList/package.json","./node_modules/@mui/material/MobileStepper/package.json","./node_modules/@mui/material/Modal/package.json","./node_modules/@mui/material/NativeSelect/package.json","./node_modules/@mui/material/NoSsr/package.json","./node_modules/@mui/material/OutlinedInput/package.json","./node_modules/@mui/material/OverridableComponent/package.json","./node_modules/@mui/material/Pagination/package.json","./node_modules/@mui/material/PaginationItem/package.json","./node_modules/@mui/material/Paper/package.json","./node_modules/@mui/material/Popover/package.json","./node_modules/@mui/material/Popper/package.json","./node_modules/@mui/material/Portal/package.json","./node_modules/@mui/material/Radio/package.json","./node_modules/@mui/material/RadioGroup/package.json","./node_modules/@mui/material/Rating/package.json","./node_modules/@mui/material/ScopedCssBaseline/package.json","./node_modules/@mui/material/Select/package.json","./node_modules/@mui/material/Select/utils/package.json","./node_modules/@mui/material/Skeleton/package.json","./node_modules/@mui/material/Slide/package.json","./node_modules/@mui/material/Slider/package.json","./node_modules/@mui/material/Snackbar/package.json","./node_modules/@mui/material/SnackbarContent/package.json","./node_modules/@mui/material/SpeedDial/package.json","./node_modules/@mui/material/SpeedDialAction/package.json","./node_modules/@mui/material/SpeedDialIcon/package.json","./node_modules/@mui/material/Stack/package.json","./node_modules/@mui/material/Step/package.json","./node_modules/@mui/material/StepButton/package.json","./node_modules/@mui/material/StepConnector/package.json","./node_modules/@mui/material/StepContent/package.json","./node_modules/@mui/material/StepIcon/package.json","./node_modules/@mui/material/StepLabel/package.json","./node_modules/@mui/material/Stepper/package.json","./node_modules/@mui/material/SvgIcon/package.json","./node_modules/@mui/material/SwipeableDrawer/package.json","./node_modules/@mui/material/Switch/package.json","./node_modules/@mui/material/Tab/package.json","./node_modules/@mui/material/TabScrollButton/package.json","./node_modules/@mui/material/Table/package.json","./node_modules/@mui/material/TableBody/package.json","./node_modules/@mui/material/TableCell/package.json","./node_modules/@mui/material/TableContainer/package.json","./node_modules/@mui/material/TableFooter/package.json","./node_modules/@mui/material/TableHead/package.json","./node_modules/@mui/material/TablePagination/package.json","./node_modules/@mui/material/TablePaginationActions/package.json","./node_modules/@mui/material/TableRow/package.json","./node_modules/@mui/material/TableSortLabel/package.json","./node_modules/@mui/material/Tabs/package.json","./node_modules/@mui/material/TextField/package.json","./node_modules/@mui/material/TextareaAutosize/package.json","./node_modules/@mui/material/ToggleButton/package.json","./node_modules/@mui/material/ToggleButtonGroup/package.json","./node_modules/@mui/material/Toolbar/package.json","./node_modules/@mui/material/Tooltip/package.json","./node_modules/@mui/material/Typography/package.json","./node_modules/@mui/material/Unstable_TrapFocus/package.json","./node_modules/@mui/material/Zoom/package.json","./node_modules/@mui/material/colors/package.json","./node_modules/@mui/material/darkScrollbar/package.json","./node_modules/@mui/material/generateUtilityClass/package.json","./node_modules/@mui/material/generateUtilityClasses/package.json","./node_modules/@mui/material/internal/package.json","./node_modules/@mui/material/styles/package.json","./node_modules/@mui/material/transitions/package.json","./node_modules/@mui/material/useAutocomplete/package.json","./node_modules/@mui/material/useMediaQuery/package.json","./node_modules/@mui/material/usePagination/package.json","./node_modules/@mui/material/useScrollTrigger/package.json","./node_modules/@mui/material/utils/package.json","./node_modules/@mui/material/version/package.json","./node_modules/@mui/private-theming/ThemeProvider/package.json","./node_modules/@mui/private-theming/defaultTheme/package.json","./node_modules/@mui/private-theming/useTheme/package.json","./node_modules/@mui/styled-engine/GlobalStyles/package.json","./node_modules/@mui/styled-engine/StyledEngineProvider/package.json","./node_modules/@mui/system/Box/package.json","./node_modules/@mui/system/Container/package.json","./node_modules/@mui/system/GlobalStyles/package.json","./node_modules/@mui/system/Grid/package.json","./node_modules/@mui/system/InitColorSchemeScript/package.json","./node_modules/@mui/system/RtlProvider/package.json","./node_modules/@mui/system/Stack/package.json","./node_modules/@mui/system/ThemeProvider/package.json","./node_modules/@mui/system/borders/package.json","./node_modules/@mui/system/breakpoints/package.json","./node_modules/@mui/system/colorManipulator/package.json","./node_modules/@mui/system/compose/package.json","./node_modules/@mui/system/createBox/package.json","./node_modules/@mui/system/createBreakpoints/package.json","./node_modules/@mui/system/createStyled/package.json","./node_modules/@mui/system/createTheme/package.json","./node_modules/@mui/system/cssContainerQueries/package.json","./node_modules/@mui/system/cssGrid/package.json","./node_modules/@mui/system/cssVars/package.json","./node_modules/@mui/system/display/package.json","./node_modules/@mui/system/flexbox/package.json","./node_modules/@mui/system/getThemeValue/package.json","./node_modules/@mui/system/palette/package.json","./node_modules/@mui/system/positions/package.json","./node_modules/@mui/system/responsivePropType/package.json","./node_modules/@mui/system/shadows/package.json","./node_modules/@mui/system/sizing/package.json","./node_modules/@mui/system/spacing/package.json","./node_modules/@mui/system/style/package.json","./node_modules/@mui/system/styleFunctionSx/package.json","./node_modules/@mui/system/styled/package.json","./node_modules/@mui/system/typography/package.json","./node_modules/@mui/system/useMediaQuery/package.json","./node_modules/@mui/system/useTheme/package.json","./node_modules/@mui/system/useThemeProps/package.json","./node_modules/@mui/system/useThemeWithoutDefault/package.json","./node_modules/@mui/system/version/package.json","./node_modules/@mui/utils/ClassNameGenerator/package.json","./node_modules/@mui/utils/capitalize/package.json","./node_modules/@mui/utils/composeClasses/package.json","./node_modules/@mui/utils/createChainedFunction/package.json","./node_modules/@mui/utils/debounce/package.json","./node_modules/@mui/utils/deprecatedPropType/package.json","./node_modules/@mui/utils/generateUtilityClass/package.json","./node_modules/@mui/utils/generateUtilityClasses/package.json","./node_modules/@mui/utils/getActiveElement/package.json","./node_modules/@mui/utils/isMuiElement/package.json","./node_modules/@mui/utils/ownerDocument/package.json","./node_modules/@mui/utils/ownerWindow/package.json","./node_modules/@mui/utils/requirePropFactory/package.json","./node_modules/@mui/utils/setRef/package.json","./node_modules/@mui/utils/types/package.json","./node_modules/@mui/utils/unsupportedProp/package.json","./node_modules/@mui/utils/useControlled/package.json","./node_modules/@mui/utils/useEnhancedEffect/package.json","./node_modules/@mui/utils/useEventCallback/package.json","./node_modules/@mui/utils/useForkRef/package.json","./node_modules/@mui/utils/useId/package.json","./node_modules/@opentelemetry/api/package.json","./node_modules/@popperjs/core/lib/modifiers/package.json","./node_modules/@popperjs/core/lib/package.json","./node_modules/@popperjs/core/lib/utils/package.json","./node_modules/@react-spring/animated/dist/package.json","./node_modules/@react-spring/core/dist/package.json","./node_modules/@react-spring/rafz/dist/package.json","./node_modules/@react-spring/shared/dist/package.json","./node_modules/@react-spring/types/dist/package.json","./node_modules/@react-spring/web/dist/package.json","./node_modules/@tanstack/react-virtual/dist/esm/package.json","./node_modules/@tanstack/react-virtual/dist/package.json","./node_modules/@tanstack/virtual-core/dist/esm/package.json","./node_modules/@tanstack/virtual-core/dist/package.json","./node_modules/@types/pdfjs-dist/build/pdf.worker.min.mjs?url/package.json","./node_modules/@types/pdfjs-dist/package.json","./node_modules/@types/react-dom/client/package.json","./node_modules/@types/react-pdf/dist/Page/AnnotationLayer.css/package.json","./node_modules/@types/react-pdf/dist/Page/TextLayer.css/package.json","./node_modules/@types/react-pdf/package.json","./node_modules/@types/react/jsx-runtime/package.json","./node_modules/@types/vite/client/package.json","./node_modules/@types/yet-another-react-lightbox/package.json","./node_modules/@types/yet-another-react-lightbox/styles.css/package.json","./node_modules/@use-gesture/core/actions/dist/package.json","./node_modules/@use-gesture/core/dist/declarations/package.json","./node_modules/@use-gesture/core/dist/declarations/src/config/package.json","./node_modules/@use-gesture/core/dist/declarations/src/engines/package.json","./node_modules/@use-gesture/core/dist/declarations/src/package.json","./node_modules/@use-gesture/core/dist/declarations/src/types/package.json","./node_modules/@use-gesture/core/dist/declarations/src/utils/package.json","./node_modules/@use-gesture/core/dist/package.json","./node_modules/@use-gesture/core/types/dist/package.json","./node_modules/@use-gesture/core/utils/dist/package.json","./node_modules/@use-gesture/react/dist/declarations/package.json","./node_modules/@use-gesture/react/dist/declarations/src/package.json","./node_modules/@use-gesture/react/dist/package.json","./node_modules/@vitejs/devtools/package.json","./node_modules/@vitest/browser-playwright/package.json","./node_modules/@vitest/browser-preview/package.json","./node_modules/@vitest/browser-webdriverio/package.json","./node_modules/@vitest/coverage-istanbul/package.json","./node_modules/@vitest/mocker/dist/package.json","./node_modules/codemirror-markdown-tables/dist/package.json","./node_modules/cookie-es/dist/package.json","./node_modules/deep-eql/package.json","./node_modules/esbuild/package.json","./node_modules/expect-type/dist/package.json","./node_modules/happy-dom/package.json","./node_modules/hast/package.json","./node_modules/i18next/typescript/package.json","./node_modules/jiti/package.json","./node_modules/less/package.json","./node_modules/make-event-props/dist/package.json","./node_modules/mdast-util-from-markdown/lib/package.json","./node_modules/mdast-util-gfm-footnote/lib/package.json","./node_modules/mdast-util-gfm-table/lib/package.json","./node_modules/mdast-util-gfm/lib/package.json","./node_modules/mdast-util-to-hast/lib/handlers/package.json","./node_modules/mdast-util-to-hast/lib/package.json","./node_modules/mdast-util-to-markdown/lib/handle/package.json","./node_modules/mdast-util-to-markdown/lib/package.json","./node_modules/mdast/package.json","./node_modules/micromark-extension-gfm-footnote/lib/package.json","./node_modules/micromark-extension-gfm-strikethrough/lib/package.json","./node_modules/pdfjs-dist/build/pdf.worker.min.mjs?url/package.json","./node_modules/pdfjs-dist/types/package.json","./node_modules/pdfjs-dist/types/src/core/package.json","./node_modules/pdfjs-dist/types/src/display/annotation_layer.js/package.json","./node_modules/pdfjs-dist/types/src/display/api.js/package.json","./node_modules/pdfjs-dist/types/src/display/editor/drawers/package.json","./node_modules/pdfjs-dist/types/src/display/editor/package.json","./node_modules/pdfjs-dist/types/src/display/package.json","./node_modules/pdfjs-dist/types/src/package.json","./node_modules/pdfjs-dist/types/src/shared/package.json","./node_modules/pdfjs-dist/types/web/package.json","./node_modules/pdfjs-dist/web/package.json","./node_modules/pdfjs-dist/web/pdf_viewer.mjs/package.json","./node_modules/react-colorful/dist/components/package.json","./node_modules/react-colorful/dist/package.json","./node_modules/react-colorful/dist/utils/package.json","./node_modules/react-dom/client/package.json","./node_modules/react-markdown/lib/package.json","./node_modules/react-pdf/dist/Page/AnnotationLayer.css/package.json","./node_modules/react-pdf/dist/Page/TextLayer.css/package.json","./node_modules/react-pdf/dist/package.json","./node_modules/react-pdf/dist/shared/hooks/package.json","./node_modules/react-pdf/dist/shared/package.json","./node_modules/react-router-dom/dist/package.json","./node_modules/react-router/dist/package.json","./node_modules/react-router/dist/production/lib/dom-export/package.json","./node_modules/react-router/dist/production/lib/dom/package.json","./node_modules/react-router/dist/production/lib/dom/ssr/package.json","./node_modules/react-router/dist/production/lib/package.json","./node_modules/react-router/dist/production/lib/router/package.json","./node_modules/react-router/dist/production/lib/rsc/html-stream/package.json","./node_modules/react-router/dist/production/lib/rsc/package.json","./node_modules/react-router/dist/production/lib/server-runtime/package.json","./node_modules/react-router/dist/production/lib/server-runtime/sessions/package.json","./node_modules/react-router/dist/production/lib/types/package.json","./node_modules/react-router/dist/production/package.json","./node_modules/react-router/dom/package.json","./node_modules/react/jsx-runtime/package.json","./node_modules/rehype-slug/lib/package.json","./node_modules/remark-gfm/lib/package.json","./node_modules/remark-parse/lib/package.json","./node_modules/remark-rehype/lib/package.json","./node_modules/sass-embedded/package.json","./node_modules/sass/package.json","./node_modules/style-mod/src/package.json","./node_modules/stylus/package.json","./node_modules/sugarss/package.json","./node_modules/terser/package.json","./node_modules/tinybench/dist/package.json","./node_modules/trough/lib/package.json","./node_modules/tsx/package.json","./node_modules/unified/lib/package.json","./node_modules/unist-util-is/lib/package.json","./node_modules/unist-util-visit-parents/lib/package.json","./node_modules/unist-util-visit/lib/package.json","./node_modules/unist/package.json","./node_modules/vfile-message/lib/package.json","./node_modules/vfile/lib/package.json","./node_modules/vite/client/package.json","./node_modules/vite/dist/node/chunks/package.json","./node_modules/vite/dist/node/package.json","./node_modules/vite/dist/package.json","./node_modules/vite/module-runner/package.json","./node_modules/vite/types/package.json","./node_modules/vitest/dist/chunks/package.json","./node_modules/vitest/dist/package.json","./node_modules/yaml/package.json","./node_modules/yet-another-react-lightbox/dist/package.json","./node_modules/yet-another-react-lightbox/dist/plugins/fullscreen/package.json","./node_modules/yet-another-react-lightbox/dist/plugins/package.json","./node_modules/yet-another-react-lightbox/dist/plugins/zoom/package.json","./node_modules/yet-another-react-lightbox/plugins/fullscreen/package.json","./node_modules/yet-another-react-lightbox/plugins/zoom/package.json","./node_modules/yet-another-react-lightbox/styles.css/package.json"]}
\ No newline at end of file
diff --git a/frontend/tsconfig.json b/frontend/tsconfig.json
index d32ff6820..f22f27abc 100644
--- a/frontend/tsconfig.json
+++ b/frontend/tsconfig.json
@@ -1,4 +1,14 @@
 {
   "files": [],
-  "references": [{ "path": "./tsconfig.app.json" }, { "path": "./tsconfig.node.json" }]
+  "references": [
+    {
+      "path": "./tsconfig.app.json"
+    },
+    {
+      "path": "./tsconfig.test.json"
+    },
+    {
+      "path": "./tsconfig.node.json"
+    }
+  ]
 }
diff --git a/frontend/tsconfig.test.json b/frontend/tsconfig.test.json
new file mode 100644
index 000000000..e10ccb6fc
--- /dev/null
+++ b/frontend/tsconfig.test.json
@@ -0,0 +1,20 @@
+{
+  "extends": "./tsconfig.app.json",
+  "compilerOptions": {
+    "types": [
+      "vite/client",
+      "vitest/globals",
+      "@testing-library/jest-dom/vitest",
+      "node"
+    ],
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.test.tsbuildinfo"
+  },
+  "include": [
+    "src/**/*.d.ts",
+    "src/**/__tests__/**/*",
+    "src/**/*.test.ts",
+    "src/**/*.test.tsx",
+    "src/test/**/*"
+  ],
+  "exclude": []
+}
diff --git a/frontend/vite.config.ts b/frontend/vite.config.ts
index ebf4e33c9..1f614ce39 100644
--- a/frontend/vite.config.ts
+++ b/frontend/vite.config.ts
@@ -1,11 +1,13 @@
 import type { ServerResponse } from "node:http";
 import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import react from "@vitejs/plugin-react";
 import { createLogger, defineConfig } from "vite";
 
 const FRONTEND_DIR = dirname(fileURLToPath(import.meta.url));
+const WORKER_CHARACTER_DECODER = createRequire(import.meta.url).resolve("decode-named-character-reference");
 const WORKSPACE_ROOT = resolve(FRONTEND_DIR, "..");
 const BACKEND_PROXY_TARGET = "http://localhost:8000";
 const BACKEND_PROXY_TIMEOUT_MS = 60_000;
@@ -106,6 +108,9 @@ export default defineConfig({
   plugins: [react()],
   resolve: {
     dedupe: ["react", "react-dom"],
+    alias: {
+      "decode-named-character-reference": WORKER_CHARACTER_DECODER,
+    },
   },
   server: {
     host: "0.0.0.0",
@@ -163,6 +168,13 @@ export default defineConfig({
   },
   worker: {
     format: "es",
+    plugins: () => [{
+      name: "worker-character-decoder",
+      enforce: "pre",
+      resolveId(source) {
+        if (source === "decode-named-character-reference") return WORKER_CHARACTER_DECODER;
+      },
+    }],
   },
   optimizeDeps: {
     // Crawl lazy-loaded route modules during startup so navigation does not
diff --git a/frontend/vitest.config.ts b/frontend/vitest.config.ts
index 4f384bf71..8e8f77ec6 100644
--- a/frontend/vitest.config.ts
+++ b/frontend/vitest.config.ts
@@ -1,6 +1,8 @@
+import { availableParallelism, totalmem } from "node:os";
 import { fileURLToPath } from "node:url";
 import react from "@vitejs/plugin-react";
 import { defineConfig } from "vitest/config";
+import { ciWorkerCount } from "./scripts/ci-test-policy.mjs";
 
 export default defineConfig({
   plugins: [react()],
@@ -13,6 +15,7 @@ export default defineConfig({
     // Enable parallel file execution for better performance
     // Uses threads by default with fileParallelism enabled
     fileParallelism: true,
+    maxWorkers: process.env["SAMBEE_TEST_CI"] === "1" ? ciWorkerCount(availableParallelism(), totalmem()) : undefined,
     // Maximum number of concurrent test files
     maxConcurrency: 5,
     // Timeout for each test (default is 5000ms)
diff --git a/scripts/check_ci_test_gate.py b/scripts/check_ci_test_gate.py
new file mode 100644
index 000000000..519bb375a
--- /dev/null
+++ b/scripts/check_ci_test_gate.py
@@ -0,0 +1,54 @@
+"""Require each selected CI component to complete successfully."""
+
+import json
+import os
+from collections.abc import Mapping
+
+COMPONENT_JOBS = {
+    "backend": "backend",
+    "frontend": "frontend",
+    "companion": "companion",
+    "website": "website-docs",
+}
+
+
+def gate_errors(needs: Mapping[str, dict], event_name: str) -> list[str]:
+    """Return failures, including unexpected skips and malformed selection outputs."""
+    changes = needs.get("changes", {})
+    if changes.get("result") != "success":
+        return [f"Change detection did not succeed: {changes.get('result')}"]
+    outputs = changes.get("outputs", {})
+    errors = []
+    for component, job in COMPONENT_JOBS.items():
+        selection = outputs.get(component)
+        result = needs.get(job, {}).get("result")
+        if selection not in {"true", "false"}:
+            errors.append(
+                f"Missing or invalid component selection: {component}={selection}"
+            )
+        elif event_name == "workflow_dispatch" or selection == "true":
+            if result != "success":
+                errors.append(f"Required {job} job did not succeed: {result}")
+        elif result not in {"success", "skipped"}:
+            errors.append(f"Unselected {job} job failed or was cancelled: {result}")
+    return errors
+
+
+def main() -> int:
+    """Validate GitHub's needs context without interpreting it as shell code."""
+    try:
+        errors = gate_errors(
+            json.loads(os.environ["NEEDS_JSON"]), os.environ["EVENT_NAME"]
+        )
+    except (KeyError, TypeError, AttributeError, json.JSONDecodeError) as error:
+        print(f"Cannot validate CI results: {error}")
+        return 1
+    for error in errors:
+        print(error)
+    if not errors:
+        print("All selected CI components succeeded.")
+    return int(bool(errors))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/scripts/check_native_markdown_pdf.py b/scripts/check_native_markdown_pdf.py
new file mode 100644
index 000000000..5d0b92342
--- /dev/null
+++ b/scripts/check_native_markdown_pdf.py
@@ -0,0 +1,146 @@
+"""Check actual PDF attachments in a native Markdown Playwright JSON report."""
+
+import argparse
+import base64
+import io
+import json
+import sys
+from pathlib import Path
+
+from pypdf import PdfReader
+
+
+def attachment_bytes(attachment: dict) -> bytes:
+    if "body" in attachment:
+        return base64.b64decode(attachment["body"], validate=True)
+    return Path(attachment["path"]).read_bytes()
+
+
+def inspect_report(value: object) -> list[dict]:
+    results = []
+    if isinstance(value, list):
+        for child in value:
+            results.extend(inspect_report(child))
+    elif isinstance(value, dict):
+        attachments = value.get("attachments", [])
+        evidence = [
+            item
+            for item in attachments
+            if item.get("name") in ("native-constraints.json", "markdown-print.json")
+        ]
+        if evidence:
+            if len(evidence) != 1:
+                raise ValueError("Each native case must attach exactly one contract")
+            contract = json.loads(attachment_bytes(evidence[0]))
+            if contract["engine"] != "chromium":
+                return results
+            pdfs = [
+                item
+                for item in attachments
+                if item.get("contentType") == "application/pdf"
+            ]
+            if len(pdfs) != 1:
+                raise ValueError(
+                    "Each Chromium native case must attach exactly one PDF"
+                )
+            reader = PdfReader(io.BytesIO(attachment_bytes(pdfs[0])))
+            text = "\n".join(page.extract_text() or "" for page in reader.pages)
+            normalized = "".join(text.split())
+            expected_lines = [
+                line.strip()
+                for line in contract["renderedText"].splitlines()
+                if line.strip()
+            ]
+            missing = [
+                line
+                for line in expected_lines
+                if "".join(line.split()) not in normalized
+            ]
+            image_count = (
+                sum(len(page.images) for page in reader.pages)
+                if contract.get("requiresImages")
+                else 0
+            )
+            results.append(
+                {
+                    "fixture": contract["fixture"],
+                    "width": contract["width"],
+                    "mode": contract.get("mode"),
+                    "pages": len(reader.pages),
+                    "status": "fail"
+                    if missing or (contract.get("requiresImages") and image_count == 0)
+                    else "pass",
+                    "images": image_count,
+                    "missing_lines": len(missing),
+                    "missing_examples": [line[:160] for line in missing[:5]],
+                    "scope": "PDF text extraction, not visual clipping, physical printing or Firefox acceptance",
+                }
+            )
+        else:
+            for child in value.values():
+                results.extend(inspect_report(child))
+    return results
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("report", type=Path)
+    parser.add_argument(
+        "--printing",
+        action="store_true",
+        help="Require the independent light/dark printing matrix",
+    )
+    arguments = parser.parse_args()
+    try:
+        report = json.loads(arguments.report.read_text())
+        results = inspect_report(report)
+        expected_cases = {
+            (fixture, width)
+            for fixture in ("multiline", "long-line", "nested")
+            for width in (1543, 390)
+        }
+        actual_cases = {(result["fixture"], result["width"]) for result in results}
+        if arguments.printing:
+            expected_cases = {
+                (fixture, width, mode)
+                for fixture, width in expected_cases
+                for mode in ("light", "dark")
+            }
+            actual_cases = {
+                (result["fixture"], result["width"], result["mode"])
+                for result in results
+            }
+        complete = actual_cases == expected_cases and len(results) == len(
+            expected_cases
+        )
+        stats = report.get("stats", {})
+        browser_checks_pass = stats.get("expected") == (
+            24 if arguments.printing else 12
+        ) and all(stats.get(key) == 0 for key in ("unexpected", "skipped", "flaky"))
+        accepted = (
+            complete
+            and browser_checks_pass
+            and all(result["status"] == "pass" for result in results)
+        )
+        print(
+            json.dumps(
+                {
+                    "status": "pass" if accepted else "fail",
+                    "complete_pdf_matrix": complete,
+                    "browser_checks_pass": browser_checks_pass,
+                    "results": results,
+                },
+                indent=2,
+            )
+        )
+        return 0 if accepted else 1
+    except Exception as error:
+        print(
+            f"Native Markdown PDF verification failed: {error}. Regenerate the Playwright JSON report and check its PDF attachments.",
+            file=sys.stderr,
+        )
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/scripts/check_tauri_version_alignment.py b/scripts/check_tauri_version_alignment.py
index 846432a98..ce577e71c 100644
--- a/scripts/check_tauri_version_alignment.py
+++ b/scripts/check_tauri_version_alignment.py
@@ -1,13 +1,11 @@
-#!/usr/bin/env python3
 """Validate that Tauri JavaScript packages align with Rust crate minors."""
 
 from __future__ import annotations
 
 import json
 import sys
-from pathlib import Path
-
 import tomllib
+from pathlib import Path
 
 REPO_ROOT = Path(__file__).resolve().parent.parent
 COMPANION_DIR = REPO_ROOT / "companion"
diff --git a/scripts/ci_change_detector.py b/scripts/ci_change_detector.py
index 61cfd122a..a48f65873 100644
--- a/scripts/ci_change_detector.py
+++ b/scripts/ci_change_detector.py
@@ -1,4 +1,3 @@
-#!/usr/bin/env python3
 """Select CI components from changed repository paths."""
 
 from __future__ import annotations
@@ -21,9 +20,23 @@
         "scripts/setup-test-images",
         "scripts/verify-python-runtime-image.py",
         ".github/actions/setup-runtime-python/action.yml",
+        ".github/scripts/reuse_release_ci_tests.py",
+        "scripts/check_ci_test_gate.py",
+    }
+)
+FRONTEND_EXTRAS = frozenset(
+    {
+        "VERSION",
+        "scripts/sync-version",
+        "scripts/ci_change_detector.py",
+        "scripts/check_ci_test_gate.py",
+        ".github/workflows/test.yml",
+        ".github/workflows/lint.yml",
+        ".github/workflows/docker-image-preview-publish.yml",
+        ".github/scripts/reuse_release_ci_tests.py",
+        ".github/actions/sync-version-check/action.yml",
     }
 )
-FRONTEND_EXTRAS = frozenset({"VERSION", "scripts/sync-version"})
 COMPANION_EXTRAS = frozenset({"VERSION", "scripts/sync-version"})
 WEBSITE_EXTRAS = frozenset({"VERSION"})
 FULL_TREE_DIFF_BASE = "__empty_tree__"
diff --git a/scripts/test b/scripts/test
index 200270bd7..12885575b 100755
--- a/scripts/test
+++ b/scripts/test
@@ -79,7 +79,10 @@ run_check "Test images generated" "Failed to generate test images" env QUIET=1 "
 echo -e "${YELLOW}=== Backend: Static Analysis ===${NC}"
 cd "$BACKEND_DIR" || exit 1
 
-# mypy - Type checking (non-fatal, just warnings)
+echo -e "${BLUE}Running Ruff executable-script checks...${NC}"
+run_check "Ruff executable-script checks passed" "Ruff executable-script checks failed" "$BACKEND_PYTHON" -m ruff check --select EXE "$REPO_ROOT" "$REPO_ROOT/.github"
+
+# mypy - Type checking
 echo -e "${BLUE}Running mypy (type checking)...${NC}"
 run_check "mypy passed" "mypy failed" "$BACKEND_PYTHON" -m mypy app
 
@@ -130,7 +133,7 @@ cd "$REPO_ROOT/frontend" || exit 1
 
 # TypeScript - Type checking
 echo -e "${BLUE}Running TypeScript compiler (type checking)...${NC}"
-run_check "TypeScript type check passed" "TypeScript type check failed" npx tsc --noEmit
+run_check "TypeScript type check passed" "TypeScript type check failed" npm run typecheck
 
 echo -e "${BLUE}Running Biome lint...${NC}"
 run_check "Frontend lint passed" "Frontend lint failed" npm run lint
diff --git a/scripts/update-docs-derived-artifacts.py b/scripts/update-docs-derived-artifacts.py
index a789c99bc..d7bd1a5e3 100644
--- a/scripts/update-docs-derived-artifacts.py
+++ b/scripts/update-docs-derived-artifacts.py
@@ -1,4 +1,3 @@
-#!/usr/bin/env python3
 """Refresh committed docs-derived artifacts when relevant docs inputs change."""
 
 from __future__ import annotations
diff --git a/website-meta/docs-reports/docs-structure-report.html b/website-meta/docs-reports/docs-structure-report.html
index af4e57140..608473a34 100644
--- a/website-meta/docs-reports/docs-structure-report.html
+++ b/website-meta/docs-reports/docs-structure-report.html
@@ -268,7 +268,7 @@ <h2 class="diff-modal__title" id="diff-modal-title">Content diff</h2>
     </div>
   </div>
 
-  <script id="report-data" type="application/json">{"meta": {"title": "Docs Structure Report", "current_version": "1.0", "report_output": "website-meta/docs-reports/docs-structure-report.html"}, "versions": [{"slug": "0.7", "label": "0.7", "status": null, "visible": true, "searchable": false, "is_current": false}, {"slug": "0.8", "label": "0.8", "status": null, "visible": true, "searchable": false, "is_current": false}, {"slug": "0.9", "label": "0.9", "status": null, "visible": true, "searchable": false, "is_current": false}, {"slug": "1.0", "label": "1.0", "status": "current", "visible": true, "searchable": true, "is_current": true}, {"slug": "2.0", "label": "2.0", "status": "preview", "visible": true, "searchable": false, "is_current": false}], "warnings": [], "rows": [{"id": "book:user-guide", "parent_id": null, "depth": 0, "kind": "book", "label": "user-guide", "title": "User Guide", "path": "user-guide", "has_children": true, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"User Guide\"\n+++\n\nUse this guide to access files on network shares, explore files on your computer, view files in the browser, edit Markdown in the browser, or open files in desktop apps and upload your changes back.\n\n## Start Here If You Want To\n\n- Find out what Sambee is.\n- Understand what Sambee helps you do.\n- Learn how to use Sambee.\n\n## In This Guide\n\n- [Getting Started](./getting-started/what-is-sambee/): Understand what Sambee is.\n- [Accessing Files](./accessing-files/connect-to-an-smb-share/): Connect to SMB shares and access local drives from your computer.\n- [Browsing and Navigation](./browsing-and-navigation/dual-pane-mode/): Move through folders efficiently on desktop or mobile.\n- [Viewing \u0026 Editing Files](./viewing-and-editing-files/view-images-and-read-documents/): View images, read documents, edit Markdown in the browser, or continue in desktop apps.\n- [Companion App](./companion-app/install-and-pair-the-companion-app/): Install Companion and manage desktop-app behavior.\n- [Troubleshooting](./troubleshooting/common-user-problems/): Solve common user problems before escalating.\n- [Reference](./reference/supported-file-formats/): Check supported file formats.\n\n## Use the Right Guide\n\n- Use this User Guide for everyday tasks in Sambee.\n- Use the [Admin Guide](../admin-guide/) when the question is really about provisioning, deployment, service health, or environment policy.\n- Use the [Developer Guide](../developer-guide/) when the question becomes implementation-facing.\n\n", "0.8": "+++\ntitle = \"User Guide\"\n+++\n\nUse this guide to access files on network shares, explore files on your computer, view files in the browser, edit Markdown in the browser, or open files in desktop apps and upload your changes back.\n\n## Start Here If You Want To\n\n- Find out what Sambee is.\n- Understand what Sambee helps you do.\n- Learn how to use Sambee.\n\n## In This Guide\n\n- [Getting Started](./getting-started/what-is-sambee/): Understand what Sambee is.\n- [Accessing Files](./accessing-files/connect-to-an-smb-share/): Connect to SMB shares and access local drives from your computer.\n- [Browsing and Navigation](./browsing-and-navigation/dual-pane-mode/): Move through folders efficiently on desktop or mobile.\n- [Viewing \u0026 Editing Files](./viewing-and-editing-files/view-images-and-read-documents/): View images, read documents, edit Markdown in the browser, or continue in desktop apps.\n- [Companion App](./companion-app/install-and-pair-the-companion-app/): Install Companion and manage desktop-app behavior.\n- [Troubleshooting](./troubleshooting/common-user-problems/): Solve common user problems before escalating.\n- [Reference](./reference/supported-file-formats/): Check supported file formats.\n\n## Use the Right Guide\n\n- Use this User Guide for everyday tasks in Sambee.\n- Use the [Admin Guide](../admin-guide/) when the question is really about provisioning, deployment, service health, or environment policy.\n- Use the [Developer Guide](../developer-guide/) when the question becomes implementation-facing.\n\n", "0.9": "+++\ntitle = \"User Guide\"\n+++\n\nUse this guide to access files on network shares, explore files on your computer, view files in the browser, edit Markdown in the browser, or open files in desktop apps and upload your changes back.\n\n## Start Here If You Want To\n\n- Find out what Sambee is.\n- Understand what Sambee helps you do.\n- Learn how to use Sambee.\n\n## In This Guide\n\n- [Getting Started](./getting-started/what-is-sambee/): Understand what Sambee is.\n- [Accessing Files](./accessing-files/connect-to-an-smb-share/): Connect to SMB shares and access local drives from your computer.\n- [Browsing and Navigation](./browsing-and-navigation/dual-pane-mode/): Move through folders efficiently on desktop or mobile.\n- [Viewing \u0026 Editing Files](./viewing-and-editing-files/view-images-and-read-documents/): View images, read documents, edit Markdown in the browser, or continue in desktop apps.\n- [Companion App](./companion-app/install-and-pair-the-companion-app/): Install Companion and manage desktop-app behavior.\n- [Troubleshooting](./troubleshooting/common-user-problems/): Solve common user problems before escalating.\n- [Reference](./reference/supported-file-formats/): Check supported file formats.\n\n## Use the Right Guide\n\n- Use this User Guide for everyday tasks in Sambee.\n- Use the [Admin Guide](../admin-guide/) when the question is really about provisioning, deployment, service health, or environment policy.\n- Use the [Developer Guide](../developer-guide/) when the question becomes implementation-facing.\n\n", "1.0": "+++\ntitle = \"User Guide\"\n+++\n\nUse this guide to access files on network shares, explore files on your computer, view files in the browser, edit Markdown in the browser, or open files in desktop apps and upload your changes back.\n\n## Start Here If You Want To\n\n- Find out what Sambee is.\n- Understand what Sambee helps you do.\n- Learn how to use Sambee.\n\n## In This Guide\n\n- [Getting Started](./getting-started/what-is-sambee/): Understand what Sambee is.\n- [Accessing Files](./accessing-files/connect-to-an-smb-share/): Connect to SMB shares and access local drives from your computer.\n- [Browsing and Navigation](./browsing-and-navigation/dual-pane-mode/): Move through folders efficiently on desktop or mobile.\n- [Viewing \u0026 Editing Files](./viewing-and-editing-files/view-images-and-read-documents/): View images, read documents, edit Markdown in the browser, or continue in desktop apps.\n- [Companion App](./companion-app/install-and-pair-the-companion-app/): Install Companion and manage desktop-app behavior.\n- [Troubleshooting](./troubleshooting/common-user-problems/): Solve common user problems before escalating.\n- [Reference](./reference/supported-file-formats/): Check supported file formats.\n\n## Use the Right Guide\n\n- Use this User Guide for everyday tasks in Sambee.\n- Use the [Admin Guide](../admin-guide/) when the question is really about provisioning, deployment, service health, or environment policy.\n- Use the [Developer Guide](../developer-guide/) when the question becomes implementation-facing.\n\n", "2.0": "+++\ntitle = \"User Guide\"\n+++\n\nUse this guide to access files on network shares, explore files on your computer, view files in the browser, edit Markdown in the browser, or open files in desktop apps and upload your changes back.\n\n## Start Here If You Want To\n\n- Find out what Sambee is.\n- Understand what Sambee helps you do.\n- Learn how to use Sambee.\n\n## In This Guide\n\n- [Getting Started](./getting-started/what-is-sambee/): Understand what Sambee is.\n- [Accessing Files](./accessing-files/connect-to-an-smb-share/): Connect to SMB shares and access local drives from your computer.\n- [Browsing and Navigation](./browsing-and-navigation/dual-pane-mode/): Move through folders efficiently on desktop or mobile.\n- [Viewing \u0026 Editing Files](./viewing-and-editing-files/view-images-and-read-documents/): View images, read documents, edit Markdown in the browser, or continue in desktop apps.\n- [Companion App](./companion-app/install-and-pair-the-companion-app/): Install Companion and manage desktop-app behavior.\n- [Troubleshooting](./troubleshooting/common-user-problems/): Solve common user problems before escalating.\n- [Reference](./reference/supported-file-formats/): Check supported file formats.\n\n## Use the Right Guide\n\n- Use this User Guide for everyday tasks in Sambee.\n- Use the [Admin Guide](../admin-guide/) when the question is really about provisioning, deployment, service health, or environment policy.\n- Use the [Developer Guide](../developer-guide/) when the question becomes implementation-facing.\n\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:user-guide/getting-started", "parent_id": "book:user-guide", "depth": 1, "kind": "section", "label": "getting-started", "title": "Getting Started", "path": "user-guide/getting-started", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:user-guide/getting-started/what-is-sambee", "parent_id": "section:user-guide/getting-started", "depth": 2, "kind": "page", "label": "what-is-sambee", "title": "What Is Sambee", "path": "user-guide/getting-started/what-is-sambee", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "branched", "source_version": "0.7", "diff_added": 26, "diff_removed": 6}, "2.0": {"state": "inherited", "source_version": "1.0"}}, "content_versions": {"0.7": "+++\ntitle = \"What Is Sambee?\"\n+++\n\n## Browser-Based File Manager\n\nSambee is a browser-based viewer and manager for files on SMB network shares and on your computer's local drives. It supports single-pane and dual-pane views and can replace Total Commander-style tools in your browser and on your phone.\n\n### Supports SMB Shares and Local Drives\n\nSMB shares are accessed through Sambee's server component, which translates between HTTP(S), which your browser understands, and SMB, which a file server understands. Local drive access is provided by Sambee Companion, a helper app that can be installed on your computer and acts as a small service your browser can talk to.\n\nAll of this means that Sambee brings your files and folders into the browser and makes them accessible from your phone in much the same way as from your PC or Mac.\n\n## Image and PDF Viewer, Markdown Editor\n\nSambee is more than a file manager. It is built for speed and includes a fast image browser with broad file type support, a Markdown editor, and a PDF viewer. All of these work directly in the browser and do not require additional software, except Companion for local-drive access.\n\n## Desktop App Integration\n\nSambee also bridges the gap between the browser and the apps installed on your computer. It lets you open a file in its traditional desktop app directly from the browser. In other words, you can open Word, Excel, or Photoshop files in their respective native apps. When you are done editing, your changes are uploaded back to the original storage location, such as a file share. All of this happens through a smooth, browser-based workflow.\n", "0.8": "+++\ntitle = \"What Is Sambee?\"\n+++\n\n## Browser-Based File Manager\n\nSambee is a browser-based viewer and manager for files on SMB network shares and on your computer's local drives. It supports single-pane and dual-pane views and can replace Total Commander-style tools in your browser and on your phone.\n\n### Supports SMB Shares and Local Drives\n\nSMB shares are accessed through Sambee's server component, which translates between HTTP(S), which your browser understands, and SMB, which a file server understands. Local drive access is provided by Sambee Companion, a helper app that can be installed on your computer and acts as a small service your browser can talk to.\n\nAll of this means that Sambee brings your files and folders into the browser and makes them accessible from your phone in much the same way as from your PC or Mac.\n\n## Image and PDF Viewer, Markdown Editor\n\nSambee is more than a file manager. It is built for speed and includes a fast image browser with broad file type support, a Markdown editor, and a PDF viewer. All of these work directly in the browser and do not require additional software, except Companion for local-drive access.\n\n## Desktop App Integration\n\nSambee also bridges the gap between the browser and the apps installed on your computer. It lets you open a file in its traditional desktop app directly from the browser. In other words, you can open Word, Excel, or Photoshop files in their respective native apps. When you are done editing, your changes are uploaded back to the original storage location, such as a file share. All of this happens through a smooth, browser-based workflow.\n", "0.9": "+++\ntitle = \"What Is Sambee?\"\n+++\n\n## Browser-Based File Manager\n\nSambee is a browser-based viewer and manager for files on SMB network shares and on your computer's local drives. It supports single-pane and dual-pane views and can replace Total Commander-style tools in your browser and on your phone.\n\n### Supports SMB Shares and Local Drives\n\nSMB shares are accessed through Sambee's server component, which translates between HTTP(S), which your browser understands, and SMB, which a file server understands. Local drive access is provided by Sambee Companion, a helper app that can be installed on your computer and acts as a small service your browser can talk to.\n\nAll of this means that Sambee brings your files and folders into the browser and makes them accessible from your phone in much the same way as from your PC or Mac.\n\n## Image and PDF Viewer, Markdown Editor\n\nSambee is more than a file manager. It is built for speed and includes a fast image browser with broad file type support, a Markdown editor, and a PDF viewer. All of these work directly in the browser and do not require additional software, except Companion for local-drive access.\n\n## Desktop App Integration\n\nSambee also bridges the gap between the browser and the apps installed on your computer. It lets you open a file in its traditional desktop app directly from the browser. In other words, you can open Word, Excel, or Photoshop files in their respective native apps. When you are done editing, your changes are uploaded back to the original storage location, such as a file share. All of this happens through a smooth, browser-based workflow.\n", "1.0": "+++\ntitle = \"What Is Sambee?\"\n+++\n\n## Sambee Turns Your Storage Into a Modern Workspace\n\nSambee gives organizations and individuals a self-hosted, browser-based workspace for files on existing **SMB shares** and **local drives**. Users can browse, view, and edit files from PCs, phones, and tablets, or open and edit them in desktop apps with changes uploaded back to their original location.\n\n## Browser-Based File Manager\n\nSambee can replace traditional tools like Windows File Explorer.\n\n### Works on PCs, Phones, and Tablets\n\nSambee is optimized for large screens as well as for compact mobile devices.\n\n### Supports SMB Shares and Local Drives\n\nSMB shares are accessed through Sambee's server component, which translates between HTTP(S), which your browser understands, and SMB, which a file server understands.\n\nLocal drive access is provided by Sambee Companion, a helper app that can be installed on your computer and acts as a small service your browser can talk to.\n\n## View and Edit Files\n\n### Image \u0026 PDF Viewers\n\nSambee is much more than a file manager. It includes a fast image browser with broad file type support, and a robust PDF viewer that opens even problematic PDFs. All of these work directly in the browser and do not require additional software.\n\n### Markdown \u0026 Text Editors\n\nMarkdown files are rendered with rich formatting and can be modified efficiently with user-friendly WYSIWYG editing of Markdown tables.\n\nText files of any kind can be viewed and edited in the built-in text editor, complete with syntax highlighting and search \u0026 replace.\n\n### Desktop App Integration\n\nSambee also bridges the gap between the browser and the apps installed on your computer. It lets you open a file in its traditional desktop app directly from the browser. In other words, you can open Word, Excel, or Photoshop files in their respective native apps. When you are done editing, your changes are uploaded back to the original storage location, such as a file share. All of this happens through a smooth, browser-based workflow.\n\n## Free \u0026 Open Source\n\nSambee is free and open source software designed for self-hosting as a Docker container.\n", "2.0": "+++\ntitle = \"What Is Sambee?\"\n+++\n\n## Sambee Turns Your Storage Into a Modern Workspace\n\nSambee gives organizations and individuals a self-hosted, browser-based workspace for files on existing **SMB shares** and **local drives**. Users can browse, view, and edit files from PCs, phones, and tablets, or open and edit them in desktop apps with changes uploaded back to their original location.\n\n## Browser-Based File Manager\n\nSambee can replace traditional tools like Windows File Explorer.\n\n### Works on PCs, Phones, and Tablets\n\nSambee is optimized for large screens as well as for compact mobile devices.\n\n### Supports SMB Shares and Local Drives\n\nSMB shares are accessed through Sambee's server component, which translates between HTTP(S), which your browser understands, and SMB, which a file server understands.\n\nLocal drive access is provided by Sambee Companion, a helper app that can be installed on your computer and acts as a small service your browser can talk to.\n\n## View and Edit Files\n\n### Image \u0026 PDF Viewers\n\nSambee is much more than a file manager. It includes a fast image browser with broad file type support, and a robust PDF viewer that opens even problematic PDFs. All of these work directly in the browser and do not require additional software.\n\n### Markdown \u0026 Text Editors\n\nMarkdown files are rendered with rich formatting and can be modified efficiently with user-friendly WYSIWYG editing of Markdown tables.\n\nText files of any kind can be viewed and edited in the built-in text editor, complete with syntax highlighting and search \u0026 replace.\n\n### Desktop App Integration\n\nSambee also bridges the gap between the browser and the apps installed on your computer. It lets you open a file in its traditional desktop app directly from the browser. In other words, you can open Word, Excel, or Photoshop files in their respective native apps. When you are done editing, your changes are uploaded back to the original storage location, such as a file share. All of this happens through a smooth, browser-based workflow.\n\n## Free \u0026 Open Source\n\nSambee is free and open source software designed for self-hosting as a Docker container.\n"}, "page_contents": {"0.7": "+++\ntitle = \"What Is Sambee?\"\n+++\n\n## Browser-Based File Manager\n\nSambee is a browser-based viewer and manager for files on SMB network shares and on your computer's local drives. It supports single-pane and dual-pane views and can replace Total Commander-style tools in your browser and on your phone.\n\n### Supports SMB Shares and Local Drives\n\nSMB shares are accessed through Sambee's server component, which translates between HTTP(S), which your browser understands, and SMB, which a file server understands. Local drive access is provided by Sambee Companion, a helper app that can be installed on your computer and acts as a small service your browser can talk to.\n\nAll of this means that Sambee brings your files and folders into the browser and makes them accessible from your phone in much the same way as from your PC or Mac.\n\n## Image and PDF Viewer, Markdown Editor\n\nSambee is more than a file manager. It is built for speed and includes a fast image browser with broad file type support, a Markdown editor, and a PDF viewer. All of these work directly in the browser and do not require additional software, except Companion for local-drive access.\n\n## Desktop App Integration\n\nSambee also bridges the gap between the browser and the apps installed on your computer. It lets you open a file in its traditional desktop app directly from the browser. In other words, you can open Word, Excel, or Photoshop files in their respective native apps. When you are done editing, your changes are uploaded back to the original storage location, such as a file share. All of this happens through a smooth, browser-based workflow.\n", "0.8": "+++\ntitle = \"What Is Sambee?\"\n+++\n\n## Browser-Based File Manager\n\nSambee is a browser-based viewer and manager for files on SMB network shares and on your computer's local drives. It supports single-pane and dual-pane views and can replace Total Commander-style tools in your browser and on your phone.\n\n### Supports SMB Shares and Local Drives\n\nSMB shares are accessed through Sambee's server component, which translates between HTTP(S), which your browser understands, and SMB, which a file server understands. Local drive access is provided by Sambee Companion, a helper app that can be installed on your computer and acts as a small service your browser can talk to.\n\nAll of this means that Sambee brings your files and folders into the browser and makes them accessible from your phone in much the same way as from your PC or Mac.\n\n## Image and PDF Viewer, Markdown Editor\n\nSambee is more than a file manager. It is built for speed and includes a fast image browser with broad file type support, a Markdown editor, and a PDF viewer. All of these work directly in the browser and do not require additional software, except Companion for local-drive access.\n\n## Desktop App Integration\n\nSambee also bridges the gap between the browser and the apps installed on your computer. It lets you open a file in its traditional desktop app directly from the browser. In other words, you can open Word, Excel, or Photoshop files in their respective native apps. When you are done editing, your changes are uploaded back to the original storage location, such as a file share. All of this happens through a smooth, browser-based workflow.\n", "0.9": "+++\ntitle = \"What Is Sambee?\"\n+++\n\n## Browser-Based File Manager\n\nSambee is a browser-based viewer and manager for files on SMB network shares and on your computer's local drives. It supports single-pane and dual-pane views and can replace Total Commander-style tools in your browser and on your phone.\n\n### Supports SMB Shares and Local Drives\n\nSMB shares are accessed through Sambee's server component, which translates between HTTP(S), which your browser understands, and SMB, which a file server understands. Local drive access is provided by Sambee Companion, a helper app that can be installed on your computer and acts as a small service your browser can talk to.\n\nAll of this means that Sambee brings your files and folders into the browser and makes them accessible from your phone in much the same way as from your PC or Mac.\n\n## Image and PDF Viewer, Markdown Editor\n\nSambee is more than a file manager. It is built for speed and includes a fast image browser with broad file type support, a Markdown editor, and a PDF viewer. All of these work directly in the browser and do not require additional software, except Companion for local-drive access.\n\n## Desktop App Integration\n\nSambee also bridges the gap between the browser and the apps installed on your computer. It lets you open a file in its traditional desktop app directly from the browser. In other words, you can open Word, Excel, or Photoshop files in their respective native apps. When you are done editing, your changes are uploaded back to the original storage location, such as a file share. All of this happens through a smooth, browser-based workflow.\n", "1.0": "+++\ntitle = \"What Is Sambee?\"\n+++\n\n## Sambee Turns Your Storage Into a Modern Workspace\n\nSambee gives organizations and individuals a self-hosted, browser-based workspace for files on existing **SMB shares** and **local drives**. Users can browse, view, and edit files from PCs, phones, and tablets, or open and edit them in desktop apps with changes uploaded back to their original location.\n\n## Browser-Based File Manager\n\nSambee can replace traditional tools like Windows File Explorer.\n\n### Works on PCs, Phones, and Tablets\n\nSambee is optimized for large screens as well as for compact mobile devices.\n\n### Supports SMB Shares and Local Drives\n\nSMB shares are accessed through Sambee's server component, which translates between HTTP(S), which your browser understands, and SMB, which a file server understands.\n\nLocal drive access is provided by Sambee Companion, a helper app that can be installed on your computer and acts as a small service your browser can talk to.\n\n## View and Edit Files\n\n### Image \u0026 PDF Viewers\n\nSambee is much more than a file manager. It includes a fast image browser with broad file type support, and a robust PDF viewer that opens even problematic PDFs. All of these work directly in the browser and do not require additional software.\n\n### Markdown \u0026 Text Editors\n\nMarkdown files are rendered with rich formatting and can be modified efficiently with user-friendly WYSIWYG editing of Markdown tables.\n\nText files of any kind can be viewed and edited in the built-in text editor, complete with syntax highlighting and search \u0026 replace.\n\n### Desktop App Integration\n\nSambee also bridges the gap between the browser and the apps installed on your computer. It lets you open a file in its traditional desktop app directly from the browser. In other words, you can open Word, Excel, or Photoshop files in their respective native apps. When you are done editing, your changes are uploaded back to the original storage location, such as a file share. All of this happens through a smooth, browser-based workflow.\n\n## Free \u0026 Open Source\n\nSambee is free and open source software designed for self-hosting as a Docker container.\n", "2.0": "+++\ntitle = \"What Is Sambee?\"\n+++\n\n## Sambee Turns Your Storage Into a Modern Workspace\n\nSambee gives organizations and individuals a self-hosted, browser-based workspace for files on existing **SMB shares** and **local drives**. Users can browse, view, and edit files from PCs, phones, and tablets, or open and edit them in desktop apps with changes uploaded back to their original location.\n\n## Browser-Based File Manager\n\nSambee can replace traditional tools like Windows File Explorer.\n\n### Works on PCs, Phones, and Tablets\n\nSambee is optimized for large screens as well as for compact mobile devices.\n\n### Supports SMB Shares and Local Drives\n\nSMB shares are accessed through Sambee's server component, which translates between HTTP(S), which your browser understands, and SMB, which a file server understands.\n\nLocal drive access is provided by Sambee Companion, a helper app that can be installed on your computer and acts as a small service your browser can talk to.\n\n## View and Edit Files\n\n### Image \u0026 PDF Viewers\n\nSambee is much more than a file manager. It includes a fast image browser with broad file type support, and a robust PDF viewer that opens even problematic PDFs. All of these work directly in the browser and do not require additional software.\n\n### Markdown \u0026 Text Editors\n\nMarkdown files are rendered with rich formatting and can be modified efficiently with user-friendly WYSIWYG editing of Markdown tables.\n\nText files of any kind can be viewed and edited in the built-in text editor, complete with syntax highlighting and search \u0026 replace.\n\n### Desktop App Integration\n\nSambee also bridges the gap between the browser and the apps installed on your computer. It lets you open a file in its traditional desktop app directly from the browser. In other words, you can open Word, Excel, or Photoshop files in their respective native apps. When you are done editing, your changes are uploaded back to the original storage location, such as a file share. All of this happens through a smooth, browser-based workflow.\n\n## Free \u0026 Open Source\n\nSambee is free and open source software designed for self-hosting as a Docker container.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:user-guide/getting-started/manage-your-account", "parent_id": "section:user-guide/getting-started", "depth": 2, "kind": "page", "label": "manage-your-account", "title": "Manage Your Account", "path": "user-guide/getting-started/manage-your-account", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "authored"}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "branched", "source_version": "0.9", "diff_added": 6, "diff_removed": 0}}, "content_versions": {"0.9": "+++\ntitle = \"Manage Your Account\"\n+++\n\nOpen **Settings** \u003e **Account** to review the identity Sambee uses for your current sign-in, including your username, optional name and email, and assigned role.\n\n## Sign Out\n\nSelect **Sign out** next to **This browser** in **Sessions** to return to the sign-in page. For OIDC, this also revokes the current OIDC browser session. For a password sign-in, Sambee clears the current browser's local access token; password sessions are not stored as server-side browser sessions.\n\n## Change a Local Password\n\nThe **Password** section appears when local password sign-in is configured and your account has a local password. It remains available when runtime authentication enforcement is temporarily bypassed. Enter your current password, then enter and confirm a new password. Sambee signs out the current browser after a successful change; sign in again with the new password.\n\nWhen your organization uses **OIDC only**, the Password section is unavailable because local passwords cannot be used to sign in.\n\n## Manage Sessions\n\nThe **Sessions** section separates **This browser** from **Other sessions**. It always shows the current browser when authentication is enforced. A password sign-in can show its sign-in type, but it has no server-side session ID, browser label, sign-in time, or activity history.\n\nOther sessions are active OIDC browser sessions. They show when each session was created and last active. For newly created sessions, Sambee can also show a coarse browser and operating-system label, such as **Firefox on Linux**. These labels do not identify a device or host, and older sessions might not have one.\n\n- Select **Sign out** next to the current browser to revoke its OIDC browser session and return to the sign-in page.\n- Select **Revoke** to end another browser session.\n\nRevoking a browser session immediately invalidates its Sambee API tokens. It does not sign the user out of the identity provider itself. See [OpenID Connect Authentication Operations](../../../admin-guide/authentication/openid-connect-authentication-operations/) for session lifecycle details.\n\nWhen authentication is not enforced, Sambee cannot identify or end a browser session. The **Sessions** section shows this status without a session entry or sign-out action.\n", "1.0": "+++\ntitle = \"Manage Your Account\"\n+++\n\nOpen **Settings** \u003e **Account** to review the identity Sambee uses for your current sign-in, including your username, optional name and email, and assigned role.\n\n## Sign Out\n\nSelect **Sign out** next to **This browser** in **Sessions** to return to the sign-in page. For OIDC, this also revokes the current OIDC browser session. For a password sign-in, Sambee clears the current browser's local access token; password sessions are not stored as server-side browser sessions.\n\n## Change a Local Password\n\nThe **Password** section appears when local password sign-in is configured and your account has a local password. It remains available when runtime authentication enforcement is temporarily bypassed. Enter your current password, then enter and confirm a new password. Sambee signs out the current browser after a successful change; sign in again with the new password.\n\nWhen your organization uses **OIDC only**, the Password section is unavailable because local passwords cannot be used to sign in.\n\n## Manage Sessions\n\nThe **Sessions** section separates **This browser** from **Other sessions**. It always shows the current browser when authentication is enforced. A password sign-in can show its sign-in type, but it has no server-side session ID, browser label, sign-in time, or activity history.\n\nOther sessions are active OIDC browser sessions. They show when each session was created and last active. For newly created sessions, Sambee can also show a coarse browser and operating-system label, such as **Firefox on Linux**. These labels do not identify a device or host, and older sessions might not have one.\n\n- Select **Sign out** next to the current browser to revoke its OIDC browser session and return to the sign-in page.\n- Select **Revoke** to end another browser session.\n\nRevoking a browser session immediately invalidates its Sambee API tokens. It does not sign the user out of the identity provider itself. See [OpenID Connect Authentication Operations](../../../admin-guide/authentication/openid-connect-authentication-operations/) for session lifecycle details.\n\nWhen authentication is not enforced, Sambee cannot identify or end a browser session. The **Sessions** section shows this status without a session entry or sign-out action.\n", "2.0": "+++\ntitle = \"Manage Your Account\"\n+++\n\nOpen **Settings** \u003e **Account** to review the identity Sambee uses for your current sign-in, including your username, optional name and email, and assigned role.\n\n## Sign In With A Local Password\n\nUsernames aren't case-sensitive: `Testuser` and `testuser` sign in to the same account. Leading and trailing username whitespace is ignored. Passwords remain case-sensitive and aren't trimmed. Use **Show password** beside the password field to reveal what you've entered, and **Hide password** to conceal it again.\n\nIf an older installation already contains accounts whose usernames differ only by case, those accounts temporarily require their exact username spelling. Ask an administrator to resolve the conflicting names. Once the conflict is resolved, capitalization no longer matters.\n\n## Sign Out\n\nSelect **Sign out** next to **This browser** in **Sessions** to return to the sign-in page. For OIDC, this also revokes the current OIDC browser session. For a password sign-in, Sambee clears the current browser's local access token; password sessions are not stored as server-side browser sessions.\n\n## Change a Local Password\n\nThe **Password** section appears when local password sign-in is configured and your account has a local password. It remains available when runtime authentication enforcement is temporarily bypassed. Enter your current password, then enter and confirm a new password. Sambee signs out the current browser after a successful change; sign in again with the new password.\n\nWhen your organization uses **OIDC only**, the Password section is unavailable because local passwords cannot be used to sign in.\n\n## Manage Sessions\n\nThe **Sessions** section separates **This browser** from **Other sessions**. It always shows the current browser when authentication is enforced. A password sign-in can show its sign-in type, but it has no server-side session ID, browser label, sign-in time, or activity history.\n\nOther sessions are active OIDC browser sessions. They show when each session was created and last active. For newly created sessions, Sambee can also show a coarse browser and operating-system label, such as **Firefox on Linux**. These labels do not identify a device or host, and older sessions might not have one.\n\n- Select **Sign out** next to the current browser to revoke its OIDC browser session and return to the sign-in page.\n- Select **Revoke** to end another browser session.\n\nRevoking a browser session immediately invalidates its Sambee API tokens. It does not sign the user out of the identity provider itself. See [OpenID Connect Authentication Operations](../../../admin-guide/authentication/openid-connect-authentication-operations/) for session lifecycle details.\n\nWhen authentication is not enforced, Sambee cannot identify or end a browser session. The **Sessions** section shows this status without a session entry or sign-out action.\n"}, "page_contents": {"0.9": "+++\ntitle = \"Manage Your Account\"\n+++\n\nOpen **Settings** \u003e **Account** to review the identity Sambee uses for your current sign-in, including your username, optional name and email, and assigned role.\n\n## Sign Out\n\nSelect **Sign out** next to **This browser** in **Sessions** to return to the sign-in page. For OIDC, this also revokes the current OIDC browser session. For a password sign-in, Sambee clears the current browser's local access token; password sessions are not stored as server-side browser sessions.\n\n## Change a Local Password\n\nThe **Password** section appears when local password sign-in is configured and your account has a local password. It remains available when runtime authentication enforcement is temporarily bypassed. Enter your current password, then enter and confirm a new password. Sambee signs out the current browser after a successful change; sign in again with the new password.\n\nWhen your organization uses **OIDC only**, the Password section is unavailable because local passwords cannot be used to sign in.\n\n## Manage Sessions\n\nThe **Sessions** section separates **This browser** from **Other sessions**. It always shows the current browser when authentication is enforced. A password sign-in can show its sign-in type, but it has no server-side session ID, browser label, sign-in time, or activity history.\n\nOther sessions are active OIDC browser sessions. They show when each session was created and last active. For newly created sessions, Sambee can also show a coarse browser and operating-system label, such as **Firefox on Linux**. These labels do not identify a device or host, and older sessions might not have one.\n\n- Select **Sign out** next to the current browser to revoke its OIDC browser session and return to the sign-in page.\n- Select **Revoke** to end another browser session.\n\nRevoking a browser session immediately invalidates its Sambee API tokens. It does not sign the user out of the identity provider itself. See [OpenID Connect Authentication Operations](../../../admin-guide/authentication/openid-connect-authentication-operations/) for session lifecycle details.\n\nWhen authentication is not enforced, Sambee cannot identify or end a browser session. The **Sessions** section shows this status without a session entry or sign-out action.\n", "1.0": "+++\ntitle = \"Manage Your Account\"\n+++\n\nOpen **Settings** \u003e **Account** to review the identity Sambee uses for your current sign-in, including your username, optional name and email, and assigned role.\n\n## Sign Out\n\nSelect **Sign out** next to **This browser** in **Sessions** to return to the sign-in page. For OIDC, this also revokes the current OIDC browser session. For a password sign-in, Sambee clears the current browser's local access token; password sessions are not stored as server-side browser sessions.\n\n## Change a Local Password\n\nThe **Password** section appears when local password sign-in is configured and your account has a local password. It remains available when runtime authentication enforcement is temporarily bypassed. Enter your current password, then enter and confirm a new password. Sambee signs out the current browser after a successful change; sign in again with the new password.\n\nWhen your organization uses **OIDC only**, the Password section is unavailable because local passwords cannot be used to sign in.\n\n## Manage Sessions\n\nThe **Sessions** section separates **This browser** from **Other sessions**. It always shows the current browser when authentication is enforced. A password sign-in can show its sign-in type, but it has no server-side session ID, browser label, sign-in time, or activity history.\n\nOther sessions are active OIDC browser sessions. They show when each session was created and last active. For newly created sessions, Sambee can also show a coarse browser and operating-system label, such as **Firefox on Linux**. These labels do not identify a device or host, and older sessions might not have one.\n\n- Select **Sign out** next to the current browser to revoke its OIDC browser session and return to the sign-in page.\n- Select **Revoke** to end another browser session.\n\nRevoking a browser session immediately invalidates its Sambee API tokens. It does not sign the user out of the identity provider itself. See [OpenID Connect Authentication Operations](../../../admin-guide/authentication/openid-connect-authentication-operations/) for session lifecycle details.\n\nWhen authentication is not enforced, Sambee cannot identify or end a browser session. The **Sessions** section shows this status without a session entry or sign-out action.\n", "2.0": "+++\ntitle = \"Manage Your Account\"\n+++\n\nOpen **Settings** \u003e **Account** to review the identity Sambee uses for your current sign-in, including your username, optional name and email, and assigned role.\n\n## Sign In With A Local Password\n\nUsernames aren't case-sensitive: `Testuser` and `testuser` sign in to the same account. Leading and trailing username whitespace is ignored. Passwords remain case-sensitive and aren't trimmed. Use **Show password** beside the password field to reveal what you've entered, and **Hide password** to conceal it again.\n\nIf an older installation already contains accounts whose usernames differ only by case, those accounts temporarily require their exact username spelling. Ask an administrator to resolve the conflicting names. Once the conflict is resolved, capitalization no longer matters.\n\n## Sign Out\n\nSelect **Sign out** next to **This browser** in **Sessions** to return to the sign-in page. For OIDC, this also revokes the current OIDC browser session. For a password sign-in, Sambee clears the current browser's local access token; password sessions are not stored as server-side browser sessions.\n\n## Change a Local Password\n\nThe **Password** section appears when local password sign-in is configured and your account has a local password. It remains available when runtime authentication enforcement is temporarily bypassed. Enter your current password, then enter and confirm a new password. Sambee signs out the current browser after a successful change; sign in again with the new password.\n\nWhen your organization uses **OIDC only**, the Password section is unavailable because local passwords cannot be used to sign in.\n\n## Manage Sessions\n\nThe **Sessions** section separates **This browser** from **Other sessions**. It always shows the current browser when authentication is enforced. A password sign-in can show its sign-in type, but it has no server-side session ID, browser label, sign-in time, or activity history.\n\nOther sessions are active OIDC browser sessions. They show when each session was created and last active. For newly created sessions, Sambee can also show a coarse browser and operating-system label, such as **Firefox on Linux**. These labels do not identify a device or host, and older sessions might not have one.\n\n- Select **Sign out** next to the current browser to revoke its OIDC browser session and return to the sign-in page.\n- Select **Revoke** to end another browser session.\n\nRevoking a browser session immediately invalidates its Sambee API tokens. It does not sign the user out of the identity provider itself. See [OpenID Connect Authentication Operations](../../../admin-guide/authentication/openid-connect-authentication-operations/) for session lifecycle details.\n\nWhen authentication is not enforced, Sambee cannot identify or end a browser session. The **Sessions** section shows this status without a session entry or sign-out action.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:user-guide/accessing-files", "parent_id": "book:user-guide", "depth": 1, "kind": "section", "label": "accessing-files", "title": "Accessing Files", "path": "user-guide/accessing-files", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:user-guide/accessing-files/connect-to-an-smb-share", "parent_id": "section:user-guide/accessing-files", "depth": 2, "kind": "page", "label": "connect-to-an-smb-share", "title": "Connect To An Smb Share", "path": "user-guide/accessing-files/connect-to-an-smb-share", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Connect to an SMB Share\"\n+++\n\nSMB connections are managed in Sambee's settings, which you can open via the gear icon or with the keyboard shortcut \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e,\u003c/kbd\u003e.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nConnecting to SMB shares does not require the Sambee Companion app. Companion is only for local-drive access and desktop-app integration.\n{{\u003c /admonition \u003e}}\n\n## Add a New Connection\n\nNavigate to **Settings** \u003e **Connections**, select **Add Connection**, and fill out the form.\n\nHints and tips:\n\n- **Connection name:** This is the display name for the connection in Sambee's UI.\n- **Path prefix:** If you specify a subdirectory in the share, Sambee's connection root will start in that subdirectory.\n- **Visibility:** Connections can be for your account only or for all users on the Sambee server.\n- **Access mode:** If you want to prevent modifications to the data on the share, set this to **read only**.\n\n## Explore Files of a Connection\n\nTo explore the files and folders in an SMB connection, locate the **Connection List** in the main UI and select the connection you want to open (keyboard shortcut: \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e).\n", "0.8": "+++\ntitle = \"Connect to an SMB Share\"\n+++\n\nSMB connections are managed in Sambee's settings, which you can open via the gear icon or with the keyboard shortcut \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e,\u003c/kbd\u003e.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nConnecting to SMB shares does not require the Sambee Companion app. Companion is only for local-drive access and desktop-app integration.\n{{\u003c /admonition \u003e}}\n\n## Add a New Connection\n\nNavigate to **Settings** \u003e **Connections**, select **Add Connection**, and fill out the form.\n\nHints and tips:\n\n- **Connection name:** This is the display name for the connection in Sambee's UI.\n- **Path prefix:** If you specify a subdirectory in the share, Sambee's connection root will start in that subdirectory.\n- **Visibility:** Connections can be for your account only or for all users on the Sambee server.\n- **Access mode:** If you want to prevent modifications to the data on the share, set this to **read only**.\n\n## Explore Files of a Connection\n\nTo explore the files and folders in an SMB connection, locate the **Connection List** in the main UI and select the connection you want to open (keyboard shortcut: \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e).\n", "0.9": "+++\ntitle = \"Connect to an SMB Share\"\n+++\n\nSMB connections are managed in Sambee's settings, which you can open via the gear icon or with the keyboard shortcut \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e,\u003c/kbd\u003e.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nConnecting to SMB shares does not require the Sambee Companion app. Companion is only for local-drive access and desktop-app integration.\n{{\u003c /admonition \u003e}}\n\n## Add a New Connection\n\nNavigate to **Settings** \u003e **Connections**, select **Add Connection**, and fill out the form.\n\nHints and tips:\n\n- **Connection name:** This is the display name for the connection in Sambee's UI.\n- **Path prefix:** If you specify a subdirectory in the share, Sambee's connection root will start in that subdirectory.\n- **Visibility:** Connections can be for your account only or for all users on the Sambee server.\n- **Access mode:** If you want to prevent modifications to the data on the share, set this to **read only**.\n\n## Explore Files of a Connection\n\nTo explore the files and folders in an SMB connection, locate the **Connection List** in the main UI and select the connection you want to open (keyboard shortcut: \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e).\n", "1.0": "+++\ntitle = \"Connect to an SMB Share\"\n+++\n\nSMB connections are managed in Sambee's settings, which you can open via the gear icon or with the keyboard shortcut \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e,\u003c/kbd\u003e.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nConnecting to SMB shares does not require the Sambee Companion app. Companion is only for local-drive access and desktop-app integration.\n{{\u003c /admonition \u003e}}\n\n## Add a New Connection\n\nNavigate to **Settings** \u003e **Connections**, select **Add Connection**, and fill out the form.\n\nHints and tips:\n\n- **Connection name:** This is the display name for the connection in Sambee's UI.\n- **Path prefix:** If you specify a subdirectory in the share, Sambee's connection root will start in that subdirectory.\n- **Visibility:** Connections can be for your account only or for all users on the Sambee server.\n- **Access mode:** If you want to prevent modifications to the data on the share, set this to **read only**.\n\n## Explore Files of a Connection\n\nTo explore the files and folders in an SMB connection, locate the **Connection List** in the main UI and select the connection you want to open (keyboard shortcut: \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e).\n", "2.0": "+++\ntitle = \"Connect to an SMB Share\"\n+++\n\nSMB connections are managed in Sambee's settings, which you can open via the gear icon or with the keyboard shortcut \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e,\u003c/kbd\u003e.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nConnecting to SMB shares does not require the Sambee Companion app. Companion is only for local-drive access and desktop-app integration.\n{{\u003c /admonition \u003e}}\n\n## Add a New Connection\n\nNavigate to **Settings** \u003e **Connections**, select **Add Connection**, and fill out the form.\n\nHints and tips:\n\n- **Connection name:** This is the display name for the connection in Sambee's UI.\n- **Path prefix:** If you specify a subdirectory in the share, Sambee's connection root will start in that subdirectory.\n- **Visibility:** Connections can be for your account only or for all users on the Sambee server.\n- **Access mode:** If you want to prevent modifications to the data on the share, set this to **read only**.\n\n## Explore Files of a Connection\n\nTo explore the files and folders in an SMB connection, locate the **Connection List** in the main UI and select the connection you want to open (keyboard shortcut: \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e).\n"}, "page_contents": {"0.7": "+++\ntitle = \"Connect to an SMB Share\"\n+++\n\nSMB connections are managed in Sambee's settings, which you can open via the gear icon or with the keyboard shortcut \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e,\u003c/kbd\u003e.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nConnecting to SMB shares does not require the Sambee Companion app. Companion is only for local-drive access and desktop-app integration.\n{{\u003c /admonition \u003e}}\n\n## Add a New Connection\n\nNavigate to **Settings** \u003e **Connections**, select **Add Connection**, and fill out the form.\n\nHints and tips:\n\n- **Connection name:** This is the display name for the connection in Sambee's UI.\n- **Path prefix:** If you specify a subdirectory in the share, Sambee's connection root will start in that subdirectory.\n- **Visibility:** Connections can be for your account only or for all users on the Sambee server.\n- **Access mode:** If you want to prevent modifications to the data on the share, set this to **read only**.\n\n## Explore Files of a Connection\n\nTo explore the files and folders in an SMB connection, locate the **Connection List** in the main UI and select the connection you want to open (keyboard shortcut: \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e).\n", "0.8": "+++\ntitle = \"Connect to an SMB Share\"\n+++\n\nSMB connections are managed in Sambee's settings, which you can open via the gear icon or with the keyboard shortcut \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e,\u003c/kbd\u003e.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nConnecting to SMB shares does not require the Sambee Companion app. Companion is only for local-drive access and desktop-app integration.\n{{\u003c /admonition \u003e}}\n\n## Add a New Connection\n\nNavigate to **Settings** \u003e **Connections**, select **Add Connection**, and fill out the form.\n\nHints and tips:\n\n- **Connection name:** This is the display name for the connection in Sambee's UI.\n- **Path prefix:** If you specify a subdirectory in the share, Sambee's connection root will start in that subdirectory.\n- **Visibility:** Connections can be for your account only or for all users on the Sambee server.\n- **Access mode:** If you want to prevent modifications to the data on the share, set this to **read only**.\n\n## Explore Files of a Connection\n\nTo explore the files and folders in an SMB connection, locate the **Connection List** in the main UI and select the connection you want to open (keyboard shortcut: \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e).\n", "0.9": "+++\ntitle = \"Connect to an SMB Share\"\n+++\n\nSMB connections are managed in Sambee's settings, which you can open via the gear icon or with the keyboard shortcut \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e,\u003c/kbd\u003e.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nConnecting to SMB shares does not require the Sambee Companion app. Companion is only for local-drive access and desktop-app integration.\n{{\u003c /admonition \u003e}}\n\n## Add a New Connection\n\nNavigate to **Settings** \u003e **Connections**, select **Add Connection**, and fill out the form.\n\nHints and tips:\n\n- **Connection name:** This is the display name for the connection in Sambee's UI.\n- **Path prefix:** If you specify a subdirectory in the share, Sambee's connection root will start in that subdirectory.\n- **Visibility:** Connections can be for your account only or for all users on the Sambee server.\n- **Access mode:** If you want to prevent modifications to the data on the share, set this to **read only**.\n\n## Explore Files of a Connection\n\nTo explore the files and folders in an SMB connection, locate the **Connection List** in the main UI and select the connection you want to open (keyboard shortcut: \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e).\n", "1.0": "+++\ntitle = \"Connect to an SMB Share\"\n+++\n\nSMB connections are managed in Sambee's settings, which you can open via the gear icon or with the keyboard shortcut \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e,\u003c/kbd\u003e.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nConnecting to SMB shares does not require the Sambee Companion app. Companion is only for local-drive access and desktop-app integration.\n{{\u003c /admonition \u003e}}\n\n## Add a New Connection\n\nNavigate to **Settings** \u003e **Connections**, select **Add Connection**, and fill out the form.\n\nHints and tips:\n\n- **Connection name:** This is the display name for the connection in Sambee's UI.\n- **Path prefix:** If you specify a subdirectory in the share, Sambee's connection root will start in that subdirectory.\n- **Visibility:** Connections can be for your account only or for all users on the Sambee server.\n- **Access mode:** If you want to prevent modifications to the data on the share, set this to **read only**.\n\n## Explore Files of a Connection\n\nTo explore the files and folders in an SMB connection, locate the **Connection List** in the main UI and select the connection you want to open (keyboard shortcut: \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e).\n", "2.0": "+++\ntitle = \"Connect to an SMB Share\"\n+++\n\nSMB connections are managed in Sambee's settings, which you can open via the gear icon or with the keyboard shortcut \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e,\u003c/kbd\u003e.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nConnecting to SMB shares does not require the Sambee Companion app. Companion is only for local-drive access and desktop-app integration.\n{{\u003c /admonition \u003e}}\n\n## Add a New Connection\n\nNavigate to **Settings** \u003e **Connections**, select **Add Connection**, and fill out the form.\n\nHints and tips:\n\n- **Connection name:** This is the display name for the connection in Sambee's UI.\n- **Path prefix:** If you specify a subdirectory in the share, Sambee's connection root will start in that subdirectory.\n- **Visibility:** Connections can be for your account only or for all users on the Sambee server.\n- **Access mode:** If you want to prevent modifications to the data on the share, set this to **read only**.\n\n## Explore Files of a Connection\n\nTo explore the files and folders in an SMB connection, locate the **Connection List** in the main UI and select the connection you want to open (keyboard shortcut: \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e).\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:user-guide/accessing-files/access-local-drives", "parent_id": "section:user-guide/accessing-files", "depth": 2, "kind": "page", "label": "access-local-drives", "title": "Access Local Drives", "path": "user-guide/accessing-files/access-local-drives", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Access Local Drives\"\n+++\n\nLocal-drive access is available after Sambee Companion is [installed and paired](../../companion-app/install-and-pair-the-companion-app/).\n\n## Before You Start\n\nLocal drives in the browser require all of the following:\n\n- a desktop browser\n- Sambee Companion installed and running on the same computer\n- a completed trust approval for this browser\n\nIf any of those pieces is missing, continue with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/).\n\n## Explore Local Drives\n\nWhen Companion is running and this browser is paired, local drives appear in the **Connection List** next to SMB connections (keyboard shortcut: \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e).\n\nThe list reflects the drives and mounted volumes that the current desktop user can already access through the operating system. Typical examples include:\n\n- **Disks**, e.g., `C:\\`\n- **Removable drives**, such as USB storage.\n- **Mapped network drives**, e.g., SMB connections mounted by the operating system.\n- **Virtual or cloud-backed drives**, e.g., from Google Drive, OneDrive, or Dropbox.\n\nSambee asks Companion for the current drive list when needed. You do not need to configure local drives manually in the browser.\n\n## If Local Drives Do Not Appear\n\nOpen **Settings** \u003e **Local Drives** and check the current status.\n\n- If Companion is not running, start it and refresh the page.\n- If the browser is not paired, pair this browser with Companion.\n- If Local Drives reports that pairing needs repair, reapprove this browser so Sambee can store a fresh local browser secret.\n\nFor a step-by-step recovery checklist, continue with [Common User Problems](../../troubleshooting/common-user-problems/).\n", "0.8": "+++\ntitle = \"Access Local Drives\"\n+++\n\nLocal-drive access is available after Sambee Companion is [installed and paired](../../companion-app/install-and-pair-the-companion-app/).\n\n## Before You Start\n\nLocal drives in the browser require all of the following:\n\n- a desktop browser\n- Sambee Companion installed and running on the same computer\n- a completed trust approval for this browser\n\nIf any of those pieces is missing, continue with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/).\n\n## Explore Local Drives\n\nWhen Companion is running and this browser is paired, local drives appear in the **Connection List** next to SMB connections (keyboard shortcut: \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e).\n\nThe list reflects the drives and mounted volumes that the current desktop user can already access through the operating system. Typical examples include:\n\n- **Disks**, e.g., `C:\\`\n- **Removable drives**, such as USB storage.\n- **Mapped network drives**, e.g., SMB connections mounted by the operating system.\n- **Virtual or cloud-backed drives**, e.g., from Google Drive, OneDrive, or Dropbox.\n\nSambee asks Companion for the current drive list when needed. You do not need to configure local drives manually in the browser.\n\n## If Local Drives Do Not Appear\n\nOpen **Settings** \u003e **Local Drives** and check the current status.\n\n- If Companion is not running, start it and refresh the page.\n- If the browser is not paired, pair this browser with Companion.\n- If Local Drives reports that pairing needs repair, reapprove this browser so Sambee can store a fresh local browser secret.\n\nFor a step-by-step recovery checklist, continue with [Common User Problems](../../troubleshooting/common-user-problems/).\n", "0.9": "+++\ntitle = \"Access Local Drives\"\n+++\n\nLocal-drive access is available after Sambee Companion is [installed and paired](../../companion-app/install-and-pair-the-companion-app/).\n\n## Before You Start\n\nLocal drives in the browser require all of the following:\n\n- a desktop browser\n- Sambee Companion installed and running on the same computer\n- a completed trust approval for this browser\n\nIf any of those pieces is missing, continue with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/).\n\n## Explore Local Drives\n\nWhen Companion is running and this browser is paired, local drives appear in the **Connection List** next to SMB connections (keyboard shortcut: \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e).\n\nThe list reflects the drives and mounted volumes that the current desktop user can already access through the operating system. Typical examples include:\n\n- **Disks**, e.g., `C:\\`\n- **Removable drives**, such as USB storage.\n- **Mapped network drives**, e.g., SMB connections mounted by the operating system.\n- **Virtual or cloud-backed drives**, e.g., from Google Drive, OneDrive, or Dropbox.\n\nSambee asks Companion for the current drive list when needed. You do not need to configure local drives manually in the browser.\n\n## If Local Drives Do Not Appear\n\nOpen **Settings** \u003e **Local Drives** and check the current status.\n\n- If Companion is not running, start it and refresh the page.\n- If the browser is not paired, pair this browser with Companion.\n- If Local Drives reports that pairing needs repair, reapprove this browser so Sambee can store a fresh local browser secret.\n\nFor a step-by-step recovery checklist, continue with [Common User Problems](../../troubleshooting/common-user-problems/).\n", "1.0": "+++\ntitle = \"Access Local Drives\"\n+++\n\nLocal-drive access is available after Sambee Companion is [installed and paired](../../companion-app/install-and-pair-the-companion-app/).\n\n## Before You Start\n\nLocal drives in the browser require all of the following:\n\n- a desktop browser\n- Sambee Companion installed and running on the same computer\n- a completed trust approval for this browser\n\nIf any of those pieces is missing, continue with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/).\n\n## Explore Local Drives\n\nWhen Companion is running and this browser is paired, local drives appear in the **Connection List** next to SMB connections (keyboard shortcut: \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e).\n\nThe list reflects the drives and mounted volumes that the current desktop user can already access through the operating system. Typical examples include:\n\n- **Disks**, e.g., `C:\\`\n- **Removable drives**, such as USB storage.\n- **Mapped network drives**, e.g., SMB connections mounted by the operating system.\n- **Virtual or cloud-backed drives**, e.g., from Google Drive, OneDrive, or Dropbox.\n\nSambee asks Companion for the current drive list when needed. You do not need to configure local drives manually in the browser.\n\n## If Local Drives Do Not Appear\n\nOpen **Settings** \u003e **Local Drives** and check the current status.\n\n- If Companion is not running, start it and refresh the page.\n- If the browser is not paired, pair this browser with Companion.\n- If Local Drives reports that pairing needs repair, reapprove this browser so Sambee can store a fresh local browser secret.\n\nFor a step-by-step recovery checklist, continue with [Common User Problems](../../troubleshooting/common-user-problems/).\n", "2.0": "+++\ntitle = \"Access Local Drives\"\n+++\n\nLocal-drive access is available after Sambee Companion is [installed and paired](../../companion-app/install-and-pair-the-companion-app/).\n\n## Before You Start\n\nLocal drives in the browser require all of the following:\n\n- a desktop browser\n- Sambee Companion installed and running on the same computer\n- a completed trust approval for this browser\n\nIf any of those pieces is missing, continue with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/).\n\n## Explore Local Drives\n\nWhen Companion is running and this browser is paired, local drives appear in the **Connection List** next to SMB connections (keyboard shortcut: \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e).\n\nThe list reflects the drives and mounted volumes that the current desktop user can already access through the operating system. Typical examples include:\n\n- **Disks**, e.g., `C:\\`\n- **Removable drives**, such as USB storage.\n- **Mapped network drives**, e.g., SMB connections mounted by the operating system.\n- **Virtual or cloud-backed drives**, e.g., from Google Drive, OneDrive, or Dropbox.\n\nSambee asks Companion for the current drive list when needed. You do not need to configure local drives manually in the browser.\n\n## If Local Drives Do Not Appear\n\nOpen **Settings** \u003e **Local Drives** and check the current status.\n\n- If Companion is not running, start it and refresh the page.\n- If the browser is not paired, pair this browser with Companion.\n- If Local Drives reports that pairing needs repair, reapprove this browser so Sambee can store a fresh local browser secret.\n\nFor a step-by-step recovery checklist, continue with [Common User Problems](../../troubleshooting/common-user-problems/).\n"}, "page_contents": {"0.7": "+++\ntitle = \"Access Local Drives\"\n+++\n\nLocal-drive access is available after Sambee Companion is [installed and paired](../../companion-app/install-and-pair-the-companion-app/).\n\n## Before You Start\n\nLocal drives in the browser require all of the following:\n\n- a desktop browser\n- Sambee Companion installed and running on the same computer\n- a completed trust approval for this browser\n\nIf any of those pieces is missing, continue with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/).\n\n## Explore Local Drives\n\nWhen Companion is running and this browser is paired, local drives appear in the **Connection List** next to SMB connections (keyboard shortcut: \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e).\n\nThe list reflects the drives and mounted volumes that the current desktop user can already access through the operating system. Typical examples include:\n\n- **Disks**, e.g., `C:\\`\n- **Removable drives**, such as USB storage.\n- **Mapped network drives**, e.g., SMB connections mounted by the operating system.\n- **Virtual or cloud-backed drives**, e.g., from Google Drive, OneDrive, or Dropbox.\n\nSambee asks Companion for the current drive list when needed. You do not need to configure local drives manually in the browser.\n\n## If Local Drives Do Not Appear\n\nOpen **Settings** \u003e **Local Drives** and check the current status.\n\n- If Companion is not running, start it and refresh the page.\n- If the browser is not paired, pair this browser with Companion.\n- If Local Drives reports that pairing needs repair, reapprove this browser so Sambee can store a fresh local browser secret.\n\nFor a step-by-step recovery checklist, continue with [Common User Problems](../../troubleshooting/common-user-problems/).\n", "0.8": "+++\ntitle = \"Access Local Drives\"\n+++\n\nLocal-drive access is available after Sambee Companion is [installed and paired](../../companion-app/install-and-pair-the-companion-app/).\n\n## Before You Start\n\nLocal drives in the browser require all of the following:\n\n- a desktop browser\n- Sambee Companion installed and running on the same computer\n- a completed trust approval for this browser\n\nIf any of those pieces is missing, continue with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/).\n\n## Explore Local Drives\n\nWhen Companion is running and this browser is paired, local drives appear in the **Connection List** next to SMB connections (keyboard shortcut: \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e).\n\nThe list reflects the drives and mounted volumes that the current desktop user can already access through the operating system. Typical examples include:\n\n- **Disks**, e.g., `C:\\`\n- **Removable drives**, such as USB storage.\n- **Mapped network drives**, e.g., SMB connections mounted by the operating system.\n- **Virtual or cloud-backed drives**, e.g., from Google Drive, OneDrive, or Dropbox.\n\nSambee asks Companion for the current drive list when needed. You do not need to configure local drives manually in the browser.\n\n## If Local Drives Do Not Appear\n\nOpen **Settings** \u003e **Local Drives** and check the current status.\n\n- If Companion is not running, start it and refresh the page.\n- If the browser is not paired, pair this browser with Companion.\n- If Local Drives reports that pairing needs repair, reapprove this browser so Sambee can store a fresh local browser secret.\n\nFor a step-by-step recovery checklist, continue with [Common User Problems](../../troubleshooting/common-user-problems/).\n", "0.9": "+++\ntitle = \"Access Local Drives\"\n+++\n\nLocal-drive access is available after Sambee Companion is [installed and paired](../../companion-app/install-and-pair-the-companion-app/).\n\n## Before You Start\n\nLocal drives in the browser require all of the following:\n\n- a desktop browser\n- Sambee Companion installed and running on the same computer\n- a completed trust approval for this browser\n\nIf any of those pieces is missing, continue with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/).\n\n## Explore Local Drives\n\nWhen Companion is running and this browser is paired, local drives appear in the **Connection List** next to SMB connections (keyboard shortcut: \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e).\n\nThe list reflects the drives and mounted volumes that the current desktop user can already access through the operating system. Typical examples include:\n\n- **Disks**, e.g., `C:\\`\n- **Removable drives**, such as USB storage.\n- **Mapped network drives**, e.g., SMB connections mounted by the operating system.\n- **Virtual or cloud-backed drives**, e.g., from Google Drive, OneDrive, or Dropbox.\n\nSambee asks Companion for the current drive list when needed. You do not need to configure local drives manually in the browser.\n\n## If Local Drives Do Not Appear\n\nOpen **Settings** \u003e **Local Drives** and check the current status.\n\n- If Companion is not running, start it and refresh the page.\n- If the browser is not paired, pair this browser with Companion.\n- If Local Drives reports that pairing needs repair, reapprove this browser so Sambee can store a fresh local browser secret.\n\nFor a step-by-step recovery checklist, continue with [Common User Problems](../../troubleshooting/common-user-problems/).\n", "1.0": "+++\ntitle = \"Access Local Drives\"\n+++\n\nLocal-drive access is available after Sambee Companion is [installed and paired](../../companion-app/install-and-pair-the-companion-app/).\n\n## Before You Start\n\nLocal drives in the browser require all of the following:\n\n- a desktop browser\n- Sambee Companion installed and running on the same computer\n- a completed trust approval for this browser\n\nIf any of those pieces is missing, continue with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/).\n\n## Explore Local Drives\n\nWhen Companion is running and this browser is paired, local drives appear in the **Connection List** next to SMB connections (keyboard shortcut: \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e).\n\nThe list reflects the drives and mounted volumes that the current desktop user can already access through the operating system. Typical examples include:\n\n- **Disks**, e.g., `C:\\`\n- **Removable drives**, such as USB storage.\n- **Mapped network drives**, e.g., SMB connections mounted by the operating system.\n- **Virtual or cloud-backed drives**, e.g., from Google Drive, OneDrive, or Dropbox.\n\nSambee asks Companion for the current drive list when needed. You do not need to configure local drives manually in the browser.\n\n## If Local Drives Do Not Appear\n\nOpen **Settings** \u003e **Local Drives** and check the current status.\n\n- If Companion is not running, start it and refresh the page.\n- If the browser is not paired, pair this browser with Companion.\n- If Local Drives reports that pairing needs repair, reapprove this browser so Sambee can store a fresh local browser secret.\n\nFor a step-by-step recovery checklist, continue with [Common User Problems](../../troubleshooting/common-user-problems/).\n", "2.0": "+++\ntitle = \"Access Local Drives\"\n+++\n\nLocal-drive access is available after Sambee Companion is [installed and paired](../../companion-app/install-and-pair-the-companion-app/).\n\n## Before You Start\n\nLocal drives in the browser require all of the following:\n\n- a desktop browser\n- Sambee Companion installed and running on the same computer\n- a completed trust approval for this browser\n\nIf any of those pieces is missing, continue with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/).\n\n## Explore Local Drives\n\nWhen Companion is running and this browser is paired, local drives appear in the **Connection List** next to SMB connections (keyboard shortcut: \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e).\n\nThe list reflects the drives and mounted volumes that the current desktop user can already access through the operating system. Typical examples include:\n\n- **Disks**, e.g., `C:\\`\n- **Removable drives**, such as USB storage.\n- **Mapped network drives**, e.g., SMB connections mounted by the operating system.\n- **Virtual or cloud-backed drives**, e.g., from Google Drive, OneDrive, or Dropbox.\n\nSambee asks Companion for the current drive list when needed. You do not need to configure local drives manually in the browser.\n\n## If Local Drives Do Not Appear\n\nOpen **Settings** \u003e **Local Drives** and check the current status.\n\n- If Companion is not running, start it and refresh the page.\n- If the browser is not paired, pair this browser with Companion.\n- If Local Drives reports that pairing needs repair, reapprove this browser so Sambee can store a fresh local browser secret.\n\nFor a step-by-step recovery checklist, continue with [Common User Problems](../../troubleshooting/common-user-problems/).\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:user-guide/browsing-and-navigation", "parent_id": "book:user-guide", "depth": 1, "kind": "section", "label": "browsing-and-navigation", "title": "Browsing and Navigation", "path": "user-guide/browsing-and-navigation", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:user-guide/browsing-and-navigation/smart-navigation-and-the-quick-bar", "parent_id": "section:user-guide/browsing-and-navigation", "depth": 2, "kind": "page", "label": "smart-navigation-and-the-quick-bar", "title": "Smart Navigation And The Quick Bar", "path": "user-guide/browsing-and-navigation/smart-navigation-and-the-quick-bar", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "branched", "source_version": "0.7", "diff_added": 57, "diff_removed": 15}, "2.0": {"state": "branched", "source_version": "1.0", "diff_added": 6, "diff_removed": 0}}, "content_versions": {"0.7": "+++\ntitle = \"Smart Navigation and the Quick Bar\"\n+++\n\nThe quick bar is one of Sambee's core navigation features.\n\nIf you have used Visual Studio Code, the interaction model will feel familiar: one shared bar helps you navigate, filter, and run commands quickly.\n\nThe quick bar has multiple modes:\n\n- Smart navigation with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e\n- File list filtering with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e\n- Command mode with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e or \u003ckbd\u003eF1\u003c/kbd\u003e\n\n## Jump to Any Directory with Smart Navigation\n\n1. Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e to open smart navigation.\n1. Type part of a directory name.\n1. Sambee lists all matches across the current connection.\n1. Choose the match you want to jump to and open that directory immediately.\n\n## Filter Files in the Current Directory\n\n1. Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e to open the quick bar in file list filtering mode.\n1. Type part of a file or directory name.\n1. Sambee filters the file list to only those items matching your search term.\n\n## Locate and Run Any Command\n\n1. Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e or \u003ckbd\u003eF1\u003c/kbd\u003e to open the quick bar in command mode.\n1. Type part of the name of a command.\n1. Sambee lists all matching commands.\n1. Choose the command you want to run.\n", "0.8": "+++\ntitle = \"Smart Navigation and the Quick Bar\"\n+++\n\nThe quick bar is one of Sambee's core navigation features.\n\nIf you have used Visual Studio Code, the interaction model will feel familiar: one shared bar helps you navigate, filter, and run commands quickly.\n\nThe quick bar has multiple modes:\n\n- Smart navigation with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e\n- File list filtering with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e\n- Command mode with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e or \u003ckbd\u003eF1\u003c/kbd\u003e\n\n## Jump to Any Directory with Smart Navigation\n\n1. Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e to open smart navigation.\n1. Type part of a directory name.\n1. Sambee lists all matches across the current connection.\n1. Choose the match you want to jump to and open that directory immediately.\n\n## Filter Files in the Current Directory\n\n1. Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e to open the quick bar in file list filtering mode.\n1. Type part of a file or directory name.\n1. Sambee filters the file list to only those items matching your search term.\n\n## Locate and Run Any Command\n\n1. Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e or \u003ckbd\u003eF1\u003c/kbd\u003e to open the quick bar in command mode.\n1. Type part of the name of a command.\n1. Sambee lists all matching commands.\n1. Choose the command you want to run.\n", "0.9": "+++\ntitle = \"Smart Navigation and the Quick Bar\"\n+++\n\nThe quick bar is one of Sambee's core navigation features.\n\nIf you have used Visual Studio Code, the interaction model will feel familiar: one shared bar helps you navigate, filter, and run commands quickly.\n\nThe quick bar has multiple modes:\n\n- Smart navigation with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e\n- File list filtering with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e\n- Command mode with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e or \u003ckbd\u003eF1\u003c/kbd\u003e\n\n## Jump to Any Directory with Smart Navigation\n\n1. Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e to open smart navigation.\n1. Type part of a directory name.\n1. Sambee lists all matches across the current connection.\n1. Choose the match you want to jump to and open that directory immediately.\n\n## Filter Files in the Current Directory\n\n1. Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e to open the quick bar in file list filtering mode.\n1. Type part of a file or directory name.\n1. Sambee filters the file list to only those items matching your search term.\n\n## Locate and Run Any Command\n\n1. Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e or \u003ckbd\u003eF1\u003c/kbd\u003e to open the quick bar in command mode.\n1. Type part of the name of a command.\n1. Sambee lists all matching commands.\n1. Choose the command you want to run.\n", "1.0": "+++\ntitle = \"Smart Navigation and the Quick Bar\"\n+++\n\nThe quick bar provides fast navigation, File Search, and commands from one shared control.\n\nThe quick bar has multiple modes:\n\n- Smart navigation with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e\n- File Search with \u003ckbd\u003e/\u003c/kbd\u003e\n- Command mode with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e\n\n## Jump to Any Directory with Smart Navigation\n\n1. Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e to open smart navigation.\n1. Type part of a directory name.\n1. Sambee lists matches across the current connection.\n1. Choose a match to open that directory.\n\n### Recent Directory History\n\nRecent directories appear before cache-based directory matches, including when the search box is empty. Choose a recent directory to switch to its connection and open the saved location. A directory that is both recent and present in the active connection's cache is shown once in Recent directories.\n\nTo remove only the selected item from Recent directories, press \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDelete\u003c/kbd\u003e. This removes history metadata; it never deletes the underlying directory or its contents.\n\nSambee records a directory after it opens successfully. History is private to your account. You can clear your directory history from **Settings** \u003e **File Browser** \u003e **Directory Navigation**.\n\n## Find Files with File Search\n\n1. Press \u003ckbd\u003e/\u003c/kbd\u003e when the file browser has keyboard focus.\n1. Type part of a filename.\n1. Review the separate Recent files and Current directory groups.\n1. Select a file and press \u003ckbd\u003eEnter\u003c/kbd\u003e to open it.\n\nFile Search doesn't build a global file index. It searches the files currently loaded in the active directory and your per-user recent-file history. A file that appears in both places is shown once in Recent files.\n\nUse modifiers with \u003ckbd\u003eEnter\u003c/kbd\u003e or a result click to choose how to open the selected file:\n\n- \u003ckbd\u003eCtrl\u003c/kbd\u003e opens it in the associated native application.\n- \u003ckbd\u003eShift\u003c/kbd\u003e opens the browser viewer picker.\n- \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e opens the native application picker.\n\nTo remove only a selected item from Recent files, press \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDelete\u003c/kbd\u003e. This removes history metadata; it never deletes the underlying file.\n\nRecent files are recorded when you attempt to open a regular file. History is private to your account and follows the configured retention and exclusion policy. The system verifies remote SMB targets and local Companion targets as regular files before keeping a history record.\n\nThe File Search settings show whether Sambee is using the built-in defaults or an administrator's saved system override. Administrators can reset an override to the built-in defaults. Lowering retention removes the oldest records immediately, and setting retention to zero clears history and prevents new records. Image, temporary, backup, and configured extension exclusions apply before a record is stored.\n\nIf a recent remote file no longer exists, Sambee removes its stale history entry after confirming that state. For local drives, Companion distinguishes a missing or no-longer-regular file from an unavailable drive; confirmed stale targets are removed, while unavailable, unpaired, or temporarily failing local drives keep their history for a later retry.\n\nYou can clear your own history from **Settings** \u003e **File Browser** \u003e **File Search**. Administrators can set retention, per-group result limits, and exclusion rules in **Settings** \u003e **File Search**. Add each extension exclusion as one literal extension; Sambee normalizes it, such as `TMP` to `.tmp`, and lets you remove it from the exclusion list.\n\n## Quick Bar Shortcut Hints\n\nChoose when shortcut hints appear in **Settings** \u003e **File Browser** \u003e **Shortcut hints**:\n\n- **Auto** shows hints on larger layouts and after you use a keyboard in the current compact-layout session.\n- **Always** shows hints in every layout.\n- **Never** hides the shortcut labels while keeping Quick Bar status information visible.\n\n## Touch-Friendly File Selection\n\nChoose when touch-friendly file selection is available in **Settings** \u003e **File Browser** \u003e **File selection**. This keeps the desktop layout and toolbar on larger devices while making row selection easier to use by touch.\n\n- **Automatic** enables touch selection when the browser reports a coarse primary pointer, which is typical for a tablet.\n- **Always on** enables touch selection in every larger layout.\n- **Off** leaves touch selection disabled in larger layouts.\n\nPhone layouts always provide touch selection. When touch selection is available, select an item from its More actions menu or touch and hold its row. Tap additional rows to add or remove them from the selection, then use the selection controls at the bottom of the pane for bulk actions.\n\n## Locate and Run Any Command\n\n1. Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e to open command mode.\n1. Type part of a command name.\n1. Choose the command to run.\n", "2.0": "+++\ntitle = \"Smart Navigation and the Quick Bar\"\n+++\n\nThe quick bar provides fast navigation, File Search, and commands from one shared control.\n\nThe quick bar has multiple modes:\n\n- Smart navigation with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e\n- File Search with \u003ckbd\u003e/\u003c/kbd\u003e\n- Command mode with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e\n\n## Jump to Any Directory with Smart Navigation\n\n1. Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e to open smart navigation.\n1. Type part of a directory name.\n1. Sambee lists matches across the current connection.\n1. Choose a match to open that directory.\n\n### Recent Directory History\n\nRecent directories appear before cache-based directory matches, including when the search box is empty. Choose a recent directory to switch to its connection and open the saved location. A directory that is both recent and present in the active connection's cache is shown once in Recent directories.\n\nTo remove only the selected item from Recent directories, press \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDelete\u003c/kbd\u003e. This removes history metadata; it never deletes the underlying directory or its contents.\n\nSambee records a directory after it opens successfully. History is private to your account. You can clear your directory history from **Settings** \u003e **File Browser** \u003e **Directory Navigation**.\n\n## Find Files with File Search\n\n1. Press \u003ckbd\u003e/\u003c/kbd\u003e when the file browser has keyboard focus.\n1. Type part of a filename.\n1. Review the separate Recent files and Current directory groups.\n1. Select a file and press \u003ckbd\u003eEnter\u003c/kbd\u003e to open it.\n\nFile Search doesn't build a global file index. It searches the files currently loaded in the active directory and your per-user recent-file history. A file that appears in both places is shown once in Recent files.\n\nUse modifiers with \u003ckbd\u003eEnter\u003c/kbd\u003e or a result click to choose how to open the selected file:\n\n- \u003ckbd\u003eCtrl\u003c/kbd\u003e opens it in the associated native application.\n- \u003ckbd\u003eShift\u003c/kbd\u003e opens the browser viewer picker.\n- \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e opens the native application picker.\n\nTo remove only a selected item from Recent files, press \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDelete\u003c/kbd\u003e. This removes history metadata; it never deletes the underlying file.\n\nRecent files are recorded when you attempt to open a regular file. History is private to your account and follows the configured retention and exclusion policy. The system verifies remote SMB targets and local Companion targets as regular files before keeping a history record.\n\nThe File Search settings show whether Sambee is using the built-in defaults or an administrator's saved system override. Administrators can reset an override to the built-in defaults. Lowering retention removes the oldest records immediately, and setting retention to zero clears history and prevents new records. Image, temporary, backup, and configured extension exclusions apply before a record is stored.\n\nIf a recent remote file no longer exists, Sambee removes its stale history entry after confirming that state. For local drives, Companion distinguishes a missing or no-longer-regular file from an unavailable drive; confirmed stale targets are removed, while unavailable, unpaired, or temporarily failing local drives keep their history for a later retry.\n\nYou can clear your own history from **Settings** \u003e **File Browser** \u003e **File Search**. Administrators can set retention, per-group result limits, and exclusion rules in **Settings** \u003e **File Search**. Add each extension exclusion as one literal extension; Sambee normalizes it, such as `TMP` to `.tmp`, and lets you remove it from the exclusion list.\n\n## Quick Bar Shortcut Hints\n\nChoose when shortcut hints appear in **Settings** \u003e **File Browser** \u003e **Shortcut hints**:\n\n- **Auto** shows hints on larger layouts and after you use a keyboard in the current compact-layout session.\n- **Always** shows hints in every layout.\n- **Never** hides the shortcut labels while keeping Quick Bar status information visible.\n\n## Desktop Mouse Selection\n\nOn desktop with touch selection off, click a file or folder name to open it, or click its icon to select it. Once an item is selected, the icons become selection controls and the pane's status bar shows the selected count. Click more icons to add or remove items. \u003ckbd\u003eShift\u003c/kbd\u003e-click an icon to add a range from the last selected item without losing earlier selections. \u003ckbd\u003eCtrl\u003c/kbd\u003e or \u003ckbd\u003eCmd\u003c/kbd\u003e with \u003ckbd\u003eShift\u003c/kbd\u003e also adds a range. Keyboard selection and icon selection share the same range anchor.\n\nClick a row outside its icon, click empty list space, or press \u003ckbd\u003eEscape\u003c/kbd\u003e to clear selection. The click that clears selection doesn't open a file; click again to open it. Sorting or starting File Search clears that pane's selection. Each pane keeps its own selection when you switch panes. Bulk actions use the selected items, while a focused item alone is not a selection.\n\n## Touch-Friendly File Selection\n\nChoose when touch-friendly file selection is available in **Settings** \u003e **File Browser** \u003e **File selection**. This keeps the desktop layout and toolbar on larger devices while making row selection easier to use by touch.\n\n- **Automatic** enables touch selection when the browser reports a coarse primary pointer, which is typical for a tablet.\n- **Always on** enables touch selection in every larger layout.\n- **Off** leaves touch selection disabled in larger layouts.\n\nPhone layouts always provide touch selection. When touch selection is available, select an item from its More actions menu or touch and hold its row. Tap additional rows to add or remove them from the selection, then use the selection controls at the bottom of the pane for bulk actions.\n\n## Locate and Run Any Command\n\n1. Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e to open command mode.\n1. Type part of a command name.\n1. Choose the command to run.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Smart Navigation and the Quick Bar\"\n+++\n\nThe quick bar is one of Sambee's core navigation features.\n\nIf you have used Visual Studio Code, the interaction model will feel familiar: one shared bar helps you navigate, filter, and run commands quickly.\n\nThe quick bar has multiple modes:\n\n- Smart navigation with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e\n- File list filtering with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e\n- Command mode with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e or \u003ckbd\u003eF1\u003c/kbd\u003e\n\n## Jump to Any Directory with Smart Navigation\n\n1. Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e to open smart navigation.\n1. Type part of a directory name.\n1. Sambee lists all matches across the current connection.\n1. Choose the match you want to jump to and open that directory immediately.\n\n## Filter Files in the Current Directory\n\n1. Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e to open the quick bar in file list filtering mode.\n1. Type part of a file or directory name.\n1. Sambee filters the file list to only those items matching your search term.\n\n## Locate and Run Any Command\n\n1. Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e or \u003ckbd\u003eF1\u003c/kbd\u003e to open the quick bar in command mode.\n1. Type part of the name of a command.\n1. Sambee lists all matching commands.\n1. Choose the command you want to run.\n", "0.8": "+++\ntitle = \"Smart Navigation and the Quick Bar\"\n+++\n\nThe quick bar is one of Sambee's core navigation features.\n\nIf you have used Visual Studio Code, the interaction model will feel familiar: one shared bar helps you navigate, filter, and run commands quickly.\n\nThe quick bar has multiple modes:\n\n- Smart navigation with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e\n- File list filtering with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e\n- Command mode with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e or \u003ckbd\u003eF1\u003c/kbd\u003e\n\n## Jump to Any Directory with Smart Navigation\n\n1. Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e to open smart navigation.\n1. Type part of a directory name.\n1. Sambee lists all matches across the current connection.\n1. Choose the match you want to jump to and open that directory immediately.\n\n## Filter Files in the Current Directory\n\n1. Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e to open the quick bar in file list filtering mode.\n1. Type part of a file or directory name.\n1. Sambee filters the file list to only those items matching your search term.\n\n## Locate and Run Any Command\n\n1. Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e or \u003ckbd\u003eF1\u003c/kbd\u003e to open the quick bar in command mode.\n1. Type part of the name of a command.\n1. Sambee lists all matching commands.\n1. Choose the command you want to run.\n", "0.9": "+++\ntitle = \"Smart Navigation and the Quick Bar\"\n+++\n\nThe quick bar is one of Sambee's core navigation features.\n\nIf you have used Visual Studio Code, the interaction model will feel familiar: one shared bar helps you navigate, filter, and run commands quickly.\n\nThe quick bar has multiple modes:\n\n- Smart navigation with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e\n- File list filtering with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e\n- Command mode with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e or \u003ckbd\u003eF1\u003c/kbd\u003e\n\n## Jump to Any Directory with Smart Navigation\n\n1. Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e to open smart navigation.\n1. Type part of a directory name.\n1. Sambee lists all matches across the current connection.\n1. Choose the match you want to jump to and open that directory immediately.\n\n## Filter Files in the Current Directory\n\n1. Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e to open the quick bar in file list filtering mode.\n1. Type part of a file or directory name.\n1. Sambee filters the file list to only those items matching your search term.\n\n## Locate and Run Any Command\n\n1. Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e or \u003ckbd\u003eF1\u003c/kbd\u003e to open the quick bar in command mode.\n1. Type part of the name of a command.\n1. Sambee lists all matching commands.\n1. Choose the command you want to run.\n", "1.0": "+++\ntitle = \"Smart Navigation and the Quick Bar\"\n+++\n\nThe quick bar provides fast navigation, File Search, and commands from one shared control.\n\nThe quick bar has multiple modes:\n\n- Smart navigation with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e\n- File Search with \u003ckbd\u003e/\u003c/kbd\u003e\n- Command mode with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e\n\n## Jump to Any Directory with Smart Navigation\n\n1. Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e to open smart navigation.\n1. Type part of a directory name.\n1. Sambee lists matches across the current connection.\n1. Choose a match to open that directory.\n\n### Recent Directory History\n\nRecent directories appear before cache-based directory matches, including when the search box is empty. Choose a recent directory to switch to its connection and open the saved location. A directory that is both recent and present in the active connection's cache is shown once in Recent directories.\n\nTo remove only the selected item from Recent directories, press \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDelete\u003c/kbd\u003e. This removes history metadata; it never deletes the underlying directory or its contents.\n\nSambee records a directory after it opens successfully. History is private to your account. You can clear your directory history from **Settings** \u003e **File Browser** \u003e **Directory Navigation**.\n\n## Find Files with File Search\n\n1. Press \u003ckbd\u003e/\u003c/kbd\u003e when the file browser has keyboard focus.\n1. Type part of a filename.\n1. Review the separate Recent files and Current directory groups.\n1. Select a file and press \u003ckbd\u003eEnter\u003c/kbd\u003e to open it.\n\nFile Search doesn't build a global file index. It searches the files currently loaded in the active directory and your per-user recent-file history. A file that appears in both places is shown once in Recent files.\n\nUse modifiers with \u003ckbd\u003eEnter\u003c/kbd\u003e or a result click to choose how to open the selected file:\n\n- \u003ckbd\u003eCtrl\u003c/kbd\u003e opens it in the associated native application.\n- \u003ckbd\u003eShift\u003c/kbd\u003e opens the browser viewer picker.\n- \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e opens the native application picker.\n\nTo remove only a selected item from Recent files, press \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDelete\u003c/kbd\u003e. This removes history metadata; it never deletes the underlying file.\n\nRecent files are recorded when you attempt to open a regular file. History is private to your account and follows the configured retention and exclusion policy. The system verifies remote SMB targets and local Companion targets as regular files before keeping a history record.\n\nThe File Search settings show whether Sambee is using the built-in defaults or an administrator's saved system override. Administrators can reset an override to the built-in defaults. Lowering retention removes the oldest records immediately, and setting retention to zero clears history and prevents new records. Image, temporary, backup, and configured extension exclusions apply before a record is stored.\n\nIf a recent remote file no longer exists, Sambee removes its stale history entry after confirming that state. For local drives, Companion distinguishes a missing or no-longer-regular file from an unavailable drive; confirmed stale targets are removed, while unavailable, unpaired, or temporarily failing local drives keep their history for a later retry.\n\nYou can clear your own history from **Settings** \u003e **File Browser** \u003e **File Search**. Administrators can set retention, per-group result limits, and exclusion rules in **Settings** \u003e **File Search**. Add each extension exclusion as one literal extension; Sambee normalizes it, such as `TMP` to `.tmp`, and lets you remove it from the exclusion list.\n\n## Quick Bar Shortcut Hints\n\nChoose when shortcut hints appear in **Settings** \u003e **File Browser** \u003e **Shortcut hints**:\n\n- **Auto** shows hints on larger layouts and after you use a keyboard in the current compact-layout session.\n- **Always** shows hints in every layout.\n- **Never** hides the shortcut labels while keeping Quick Bar status information visible.\n\n## Touch-Friendly File Selection\n\nChoose when touch-friendly file selection is available in **Settings** \u003e **File Browser** \u003e **File selection**. This keeps the desktop layout and toolbar on larger devices while making row selection easier to use by touch.\n\n- **Automatic** enables touch selection when the browser reports a coarse primary pointer, which is typical for a tablet.\n- **Always on** enables touch selection in every larger layout.\n- **Off** leaves touch selection disabled in larger layouts.\n\nPhone layouts always provide touch selection. When touch selection is available, select an item from its More actions menu or touch and hold its row. Tap additional rows to add or remove them from the selection, then use the selection controls at the bottom of the pane for bulk actions.\n\n## Locate and Run Any Command\n\n1. Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e to open command mode.\n1. Type part of a command name.\n1. Choose the command to run.\n", "2.0": "+++\ntitle = \"Smart Navigation and the Quick Bar\"\n+++\n\nThe quick bar provides fast navigation, File Search, and commands from one shared control.\n\nThe quick bar has multiple modes:\n\n- Smart navigation with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e\n- File Search with \u003ckbd\u003e/\u003c/kbd\u003e\n- Command mode with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e\n\n## Jump to Any Directory with Smart Navigation\n\n1. Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e to open smart navigation.\n1. Type part of a directory name.\n1. Sambee lists matches across the current connection.\n1. Choose a match to open that directory.\n\n### Recent Directory History\n\nRecent directories appear before cache-based directory matches, including when the search box is empty. Choose a recent directory to switch to its connection and open the saved location. A directory that is both recent and present in the active connection's cache is shown once in Recent directories.\n\nTo remove only the selected item from Recent directories, press \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDelete\u003c/kbd\u003e. This removes history metadata; it never deletes the underlying directory or its contents.\n\nSambee records a directory after it opens successfully. History is private to your account. You can clear your directory history from **Settings** \u003e **File Browser** \u003e **Directory Navigation**.\n\n## Find Files with File Search\n\n1. Press \u003ckbd\u003e/\u003c/kbd\u003e when the file browser has keyboard focus.\n1. Type part of a filename.\n1. Review the separate Recent files and Current directory groups.\n1. Select a file and press \u003ckbd\u003eEnter\u003c/kbd\u003e to open it.\n\nFile Search doesn't build a global file index. It searches the files currently loaded in the active directory and your per-user recent-file history. A file that appears in both places is shown once in Recent files.\n\nUse modifiers with \u003ckbd\u003eEnter\u003c/kbd\u003e or a result click to choose how to open the selected file:\n\n- \u003ckbd\u003eCtrl\u003c/kbd\u003e opens it in the associated native application.\n- \u003ckbd\u003eShift\u003c/kbd\u003e opens the browser viewer picker.\n- \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e opens the native application picker.\n\nTo remove only a selected item from Recent files, press \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDelete\u003c/kbd\u003e. This removes history metadata; it never deletes the underlying file.\n\nRecent files are recorded when you attempt to open a regular file. History is private to your account and follows the configured retention and exclusion policy. The system verifies remote SMB targets and local Companion targets as regular files before keeping a history record.\n\nThe File Search settings show whether Sambee is using the built-in defaults or an administrator's saved system override. Administrators can reset an override to the built-in defaults. Lowering retention removes the oldest records immediately, and setting retention to zero clears history and prevents new records. Image, temporary, backup, and configured extension exclusions apply before a record is stored.\n\nIf a recent remote file no longer exists, Sambee removes its stale history entry after confirming that state. For local drives, Companion distinguishes a missing or no-longer-regular file from an unavailable drive; confirmed stale targets are removed, while unavailable, unpaired, or temporarily failing local drives keep their history for a later retry.\n\nYou can clear your own history from **Settings** \u003e **File Browser** \u003e **File Search**. Administrators can set retention, per-group result limits, and exclusion rules in **Settings** \u003e **File Search**. Add each extension exclusion as one literal extension; Sambee normalizes it, such as `TMP` to `.tmp`, and lets you remove it from the exclusion list.\n\n## Quick Bar Shortcut Hints\n\nChoose when shortcut hints appear in **Settings** \u003e **File Browser** \u003e **Shortcut hints**:\n\n- **Auto** shows hints on larger layouts and after you use a keyboard in the current compact-layout session.\n- **Always** shows hints in every layout.\n- **Never** hides the shortcut labels while keeping Quick Bar status information visible.\n\n## Desktop Mouse Selection\n\nOn desktop with touch selection off, click a file or folder name to open it, or click its icon to select it. Once an item is selected, the icons become selection controls and the pane's status bar shows the selected count. Click more icons to add or remove items. \u003ckbd\u003eShift\u003c/kbd\u003e-click an icon to add a range from the last selected item without losing earlier selections. \u003ckbd\u003eCtrl\u003c/kbd\u003e or \u003ckbd\u003eCmd\u003c/kbd\u003e with \u003ckbd\u003eShift\u003c/kbd\u003e also adds a range. Keyboard selection and icon selection share the same range anchor.\n\nClick a row outside its icon, click empty list space, or press \u003ckbd\u003eEscape\u003c/kbd\u003e to clear selection. The click that clears selection doesn't open a file; click again to open it. Sorting or starting File Search clears that pane's selection. Each pane keeps its own selection when you switch panes. Bulk actions use the selected items, while a focused item alone is not a selection.\n\n## Touch-Friendly File Selection\n\nChoose when touch-friendly file selection is available in **Settings** \u003e **File Browser** \u003e **File selection**. This keeps the desktop layout and toolbar on larger devices while making row selection easier to use by touch.\n\n- **Automatic** enables touch selection when the browser reports a coarse primary pointer, which is typical for a tablet.\n- **Always on** enables touch selection in every larger layout.\n- **Off** leaves touch selection disabled in larger layouts.\n\nPhone layouts always provide touch selection. When touch selection is available, select an item from its More actions menu or touch and hold its row. Tap additional rows to add or remove them from the selection, then use the selection controls at the bottom of the pane for bulk actions.\n\n## Locate and Run Any Command\n\n1. Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e to open command mode.\n1. Type part of a command name.\n1. Choose the command to run.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:user-guide/browsing-and-navigation/dual-pane-mode", "parent_id": "section:user-guide/browsing-and-navigation", "depth": 2, "kind": "page", "label": "dual-pane-mode", "title": "Dual Pane Mode", "path": "user-guide/browsing-and-navigation/dual-pane-mode", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "branched", "source_version": "0.7", "diff_added": 5, "diff_removed": 1}, "2.0": {"state": "branched", "source_version": "1.0", "diff_added": 13, "diff_removed": 2}}, "content_versions": {"0.7": "+++\ntitle = \"Dual-Pane Mode\"\n+++\n\nSambee's dual-pane mode shows the contents of two directories next to each other. This layout was popularized by Norton Commander and later Total Commander. It makes it easier to move or copy files between directories and to compare two directories visually.\n\n## Work in Dual-Pane Mode\n\nTo switch between single-pane and dual-pane mode:\n\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e to switch from single-pane to dual-pane mode and back.\n\nTo move focus between the left and right panes:\n\n- Use \u003ckbd\u003eTab\u003c/kbd\u003e to move the input focus between the left and right pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e to focus the left pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e to focus the right pane.\n\nTo copy or move files and directories:\n\n- Press \u003ckbd\u003eF5\u003c/kbd\u003e to copy the currently selected items in the active pane to the location in the inactive pane.\n- Press \u003ckbd\u003eF6\u003c/kbd\u003e to move instead of copying.\n\n{{\u003c admonition type=\"note\" \u003e}}\nCopying files and directories between different SMB connections, different local drives, and SMB connections and local drives is supported. For a move across those boundaries, Sambee creates the destination but retains the source when it cannot safely verify and delete that source. Check both panes before deleting a retained source yourself.\n{{\u003c /admonition \u003e}}\n\n## Extract Selected ZIP Members\n\nWhen the active pane shows a ZIP archive, select the files or directories to extract and press \u003ckbd\u003eF5\u003c/kbd\u003e. Sambee extracts the selected members into the physical location in the inactive pane. Selecting a directory extracts all of its contents, including empty directories.\n\nArchive members can't be moved. \u003ckbd\u003eF6\u003c/kbd\u003e stays unavailable in a ZIP archive pane and doesn't modify the archive.\n\n## Requirements\n\n- Dual-pane mode is currently a desktop-only feature (i.e., not available on mobile due to screen size limitations).\n", "0.8": "+++\ntitle = \"Dual-Pane Mode\"\n+++\n\nSambee's dual-pane mode shows the contents of two directories next to each other. This layout was popularized by Norton Commander and later Total Commander. It makes it easier to move or copy files between directories and to compare two directories visually.\n\n## Work in Dual-Pane Mode\n\nTo switch between single-pane and dual-pane mode:\n\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e to switch from single-pane to dual-pane mode and back.\n\nTo move focus between the left and right panes:\n\n- Use \u003ckbd\u003eTab\u003c/kbd\u003e to move the input focus between the left and right pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e to focus the left pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e to focus the right pane.\n\nTo copy or move files and directories:\n\n- Press \u003ckbd\u003eF5\u003c/kbd\u003e to copy the currently selected items in the active pane to the location in the inactive pane.\n- Press \u003ckbd\u003eF6\u003c/kbd\u003e to move instead of copying.\n\n{{\u003c admonition type=\"note\" \u003e}}\nCopying files and directories between different SMB connections, different local drives, and SMB connections and local drives is supported. For a move across those boundaries, Sambee creates the destination but retains the source when it cannot safely verify and delete that source. Check both panes before deleting a retained source yourself.\n{{\u003c /admonition \u003e}}\n\n## Extract Selected ZIP Members\n\nWhen the active pane shows a ZIP archive, select the files or directories to extract and press \u003ckbd\u003eF5\u003c/kbd\u003e. Sambee extracts the selected members into the physical location in the inactive pane. Selecting a directory extracts all of its contents, including empty directories.\n\nArchive members can't be moved. \u003ckbd\u003eF6\u003c/kbd\u003e stays unavailable in a ZIP archive pane and doesn't modify the archive.\n\n## Requirements\n\n- Dual-pane mode is currently a desktop-only feature (i.e., not available on mobile due to screen size limitations).\n", "0.9": "+++\ntitle = \"Dual-Pane Mode\"\n+++\n\nSambee's dual-pane mode shows the contents of two directories next to each other. This layout was popularized by Norton Commander and later Total Commander. It makes it easier to move or copy files between directories and to compare two directories visually.\n\n## Work in Dual-Pane Mode\n\nTo switch between single-pane and dual-pane mode:\n\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e to switch from single-pane to dual-pane mode and back.\n\nTo move focus between the left and right panes:\n\n- Use \u003ckbd\u003eTab\u003c/kbd\u003e to move the input focus between the left and right pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e to focus the left pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e to focus the right pane.\n\nTo copy or move files and directories:\n\n- Press \u003ckbd\u003eF5\u003c/kbd\u003e to copy the currently selected items in the active pane to the location in the inactive pane.\n- Press \u003ckbd\u003eF6\u003c/kbd\u003e to move instead of copying.\n\n{{\u003c admonition type=\"note\" \u003e}}\nCopying files and directories between different SMB connections, different local drives, and SMB connections and local drives is supported. For a move across those boundaries, Sambee creates the destination but retains the source when it cannot safely verify and delete that source. Check both panes before deleting a retained source yourself.\n{{\u003c /admonition \u003e}}\n\n## Extract Selected ZIP Members\n\nWhen the active pane shows a ZIP archive, select the files or directories to extract and press \u003ckbd\u003eF5\u003c/kbd\u003e. Sambee extracts the selected members into the physical location in the inactive pane. Selecting a directory extracts all of its contents, including empty directories.\n\nArchive members can't be moved. \u003ckbd\u003eF6\u003c/kbd\u003e stays unavailable in a ZIP archive pane and doesn't modify the archive.\n\n## Requirements\n\n- Dual-pane mode is currently a desktop-only feature (i.e., not available on mobile due to screen size limitations).\n", "1.0": "+++\ntitle = \"Dual-Pane Mode\"\n+++\n\nSambee's dual-pane mode shows the contents of two directories next to each other. This layout was popularized by Norton Commander and later Total Commander. It makes it easier to move or copy files between directories and to compare two directories visually.\n\n## Work in Dual-Pane Mode\n\nTo switch between single-pane and dual-pane mode:\n\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e to switch from single-pane to dual-pane mode and back.\n\nTo move focus between the left and right panes:\n\n- Use \u003ckbd\u003eTab\u003c/kbd\u003e to move the input focus between the left and right pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e to focus the left pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e to focus the right pane.\n\nTo copy or move files and directories:\n\n- Press \u003ckbd\u003eF5\u003c/kbd\u003e to copy the currently selected items in the active pane to the location in the inactive pane.\n- Press \u003ckbd\u003eF6\u003c/kbd\u003e to move instead of copying.\n\n{{\u003c admonition type=\"note\" \u003e}}\nYou can copy and move files and directories between different SMB connections, different local drives, and SMB connections and local drives. Sambee completes the destination copy before it removes the original during a move.\n{{\u003c /admonition \u003e}}\n\nWhile a copy or move is in progress, the dialog shows its progress. Select Cancel to stop an active transfer. If a destination item already exists, use the Target already exists dialog to skip it or choose a different name.\n\nIf Sambee creates the destination for a move but can't remove the original, it reports the partial move and keeps the original in place. Review both panes before trying the move again.\n\n## Extract Selected ZIP Members\n\nWhen the active pane shows a ZIP archive, select the files or directories to extract and press \u003ckbd\u003eF5\u003c/kbd\u003e. Sambee extracts the selected members into the physical location in the inactive pane. Selecting a directory extracts all of its contents, including empty directories.\n\nArchive members can't be moved. \u003ckbd\u003eF6\u003c/kbd\u003e stays unavailable in a ZIP archive pane and doesn't modify the archive.\n\n## Requirements\n\n- Dual-pane mode is currently a desktop-only feature (i.e., not available on mobile due to screen size limitations).\n", "2.0": "+++\ntitle = \"Dual-Pane Mode\"\n+++\n\nSambee's dual-pane mode shows the contents of two directories next to each other. This layout was popularized by Norton Commander and later Total Commander. It makes it easier to move or copy files between directories and to compare two directories visually.\n\n## Work in Dual-Pane Mode\n\nTo switch between single-pane and dual-pane mode:\n\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e to switch from single-pane to dual-pane mode and back.\n\nTo move focus between the left and right panes:\n\n- Use \u003ckbd\u003eTab\u003c/kbd\u003e to move the input focus between the left and right pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e to focus the left pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e to focus the right pane.\n\nTo copy or move files and directories:\n\n- Press \u003ckbd\u003eF5\u003c/kbd\u003e to copy the currently selected items in the active pane to the location in the inactive pane.\n- Press \u003ckbd\u003eF6\u003c/kbd\u003e to move instead of copying.\n\n{{\u003c admonition type=\"note\" \u003e}}\nYou can copy and move files and directories between different SMB connections, different local drives, and SMB connections and local drives. Sambee completes the destination copy before it removes the original during a move.\n{{\u003c /admonition \u003e}}\n\nWhile a copy or move is in progress, the dialog shows its progress. Select Cancel to stop an active transfer. If a destination file already exists, use the Target already exists dialog to skip it, overwrite it, overwrite it only when the source is newer, or choose a different name. Apply the choice to remaining conflicts when appropriate. Directories with the same name are merged without removing destination-only entries. A file can't replace a directory or vice versa.\n\n### Partial Moves and Cancellation\n\nTransfers between SMB connections publish a complete destination file before removing the source. An authorized overwrite replaces the destination atomically, without first deleting the visible file. During a move, Sambee protects the opened source from concurrent writes and renames; an incompatible open writer can prevent the transfer from starting.\n\n- Cancelling before publication leaves both locations unchanged for that file.\n- Cancelling after publication but before source deletion keeps the destination and reports that the source was retained.\n- A rejected source deletion also keeps the destination and reports the retained source.\n- If a deletion acknowledgement or final close is lost, Sambee reports uncertainty about the source while retaining the confirmed destination. Cancellation after deletion has started can't guarantee that the source remains.\n\nSambee refreshes both panes after a batch. A directory can be partially moved even when its overall result is cancelled, failed, or uncertain. Earlier completed files and confirmed replacements aren't rolled back. An uncertain child stops the remaining batch; a retained-source warning can allow later items to continue. Each selected directory keeps the destination parent captured when the confirmation dialog opened.\n\nAfter a partial or uncertain move, inspect both locations before starting another operation. Don't assume the source was retained when its deletion couldn't be confirmed. The completed dialog offers Close rather than repeating the batch. If source validation fails after a copy was published, the destination remains and Sambee reports the validation failure.\n\n## Extract Selected ZIP Members\n\nWhen the active pane shows a ZIP archive, select the files or directories to extract and press \u003ckbd\u003eF5\u003c/kbd\u003e. Sambee extracts the selected members into the physical location in the inactive pane. Selecting a directory extracts all of its contents, including empty directories.\n\nArchive members can't be moved. \u003ckbd\u003eF6\u003c/kbd\u003e stays unavailable in a ZIP archive pane and doesn't modify the archive.\n\n## Requirements\n\n- Dual-pane mode is currently a desktop-only feature (i.e., not available on mobile due to screen size limitations).\n"}, "page_contents": {"0.7": "+++\ntitle = \"Dual-Pane Mode\"\n+++\n\nSambee's dual-pane mode shows the contents of two directories next to each other. This layout was popularized by Norton Commander and later Total Commander. It makes it easier to move or copy files between directories and to compare two directories visually.\n\n## Work in Dual-Pane Mode\n\nTo switch between single-pane and dual-pane mode:\n\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e to switch from single-pane to dual-pane mode and back.\n\nTo move focus between the left and right panes:\n\n- Use \u003ckbd\u003eTab\u003c/kbd\u003e to move the input focus between the left and right pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e to focus the left pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e to focus the right pane.\n\nTo copy or move files and directories:\n\n- Press \u003ckbd\u003eF5\u003c/kbd\u003e to copy the currently selected items in the active pane to the location in the inactive pane.\n- Press \u003ckbd\u003eF6\u003c/kbd\u003e to move instead of copying.\n\n{{\u003c admonition type=\"note\" \u003e}}\nCopying files and directories between different SMB connections, different local drives, and SMB connections and local drives is supported. For a move across those boundaries, Sambee creates the destination but retains the source when it cannot safely verify and delete that source. Check both panes before deleting a retained source yourself.\n{{\u003c /admonition \u003e}}\n\n## Extract Selected ZIP Members\n\nWhen the active pane shows a ZIP archive, select the files or directories to extract and press \u003ckbd\u003eF5\u003c/kbd\u003e. Sambee extracts the selected members into the physical location in the inactive pane. Selecting a directory extracts all of its contents, including empty directories.\n\nArchive members can't be moved. \u003ckbd\u003eF6\u003c/kbd\u003e stays unavailable in a ZIP archive pane and doesn't modify the archive.\n\n## Requirements\n\n- Dual-pane mode is currently a desktop-only feature (i.e., not available on mobile due to screen size limitations).\n", "0.8": "+++\ntitle = \"Dual-Pane Mode\"\n+++\n\nSambee's dual-pane mode shows the contents of two directories next to each other. This layout was popularized by Norton Commander and later Total Commander. It makes it easier to move or copy files between directories and to compare two directories visually.\n\n## Work in Dual-Pane Mode\n\nTo switch between single-pane and dual-pane mode:\n\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e to switch from single-pane to dual-pane mode and back.\n\nTo move focus between the left and right panes:\n\n- Use \u003ckbd\u003eTab\u003c/kbd\u003e to move the input focus between the left and right pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e to focus the left pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e to focus the right pane.\n\nTo copy or move files and directories:\n\n- Press \u003ckbd\u003eF5\u003c/kbd\u003e to copy the currently selected items in the active pane to the location in the inactive pane.\n- Press \u003ckbd\u003eF6\u003c/kbd\u003e to move instead of copying.\n\n{{\u003c admonition type=\"note\" \u003e}}\nCopying files and directories between different SMB connections, different local drives, and SMB connections and local drives is supported. For a move across those boundaries, Sambee creates the destination but retains the source when it cannot safely verify and delete that source. Check both panes before deleting a retained source yourself.\n{{\u003c /admonition \u003e}}\n\n## Extract Selected ZIP Members\n\nWhen the active pane shows a ZIP archive, select the files or directories to extract and press \u003ckbd\u003eF5\u003c/kbd\u003e. Sambee extracts the selected members into the physical location in the inactive pane. Selecting a directory extracts all of its contents, including empty directories.\n\nArchive members can't be moved. \u003ckbd\u003eF6\u003c/kbd\u003e stays unavailable in a ZIP archive pane and doesn't modify the archive.\n\n## Requirements\n\n- Dual-pane mode is currently a desktop-only feature (i.e., not available on mobile due to screen size limitations).\n", "0.9": "+++\ntitle = \"Dual-Pane Mode\"\n+++\n\nSambee's dual-pane mode shows the contents of two directories next to each other. This layout was popularized by Norton Commander and later Total Commander. It makes it easier to move or copy files between directories and to compare two directories visually.\n\n## Work in Dual-Pane Mode\n\nTo switch between single-pane and dual-pane mode:\n\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e to switch from single-pane to dual-pane mode and back.\n\nTo move focus between the left and right panes:\n\n- Use \u003ckbd\u003eTab\u003c/kbd\u003e to move the input focus between the left and right pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e to focus the left pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e to focus the right pane.\n\nTo copy or move files and directories:\n\n- Press \u003ckbd\u003eF5\u003c/kbd\u003e to copy the currently selected items in the active pane to the location in the inactive pane.\n- Press \u003ckbd\u003eF6\u003c/kbd\u003e to move instead of copying.\n\n{{\u003c admonition type=\"note\" \u003e}}\nCopying files and directories between different SMB connections, different local drives, and SMB connections and local drives is supported. For a move across those boundaries, Sambee creates the destination but retains the source when it cannot safely verify and delete that source. Check both panes before deleting a retained source yourself.\n{{\u003c /admonition \u003e}}\n\n## Extract Selected ZIP Members\n\nWhen the active pane shows a ZIP archive, select the files or directories to extract and press \u003ckbd\u003eF5\u003c/kbd\u003e. Sambee extracts the selected members into the physical location in the inactive pane. Selecting a directory extracts all of its contents, including empty directories.\n\nArchive members can't be moved. \u003ckbd\u003eF6\u003c/kbd\u003e stays unavailable in a ZIP archive pane and doesn't modify the archive.\n\n## Requirements\n\n- Dual-pane mode is currently a desktop-only feature (i.e., not available on mobile due to screen size limitations).\n", "1.0": "+++\ntitle = \"Dual-Pane Mode\"\n+++\n\nSambee's dual-pane mode shows the contents of two directories next to each other. This layout was popularized by Norton Commander and later Total Commander. It makes it easier to move or copy files between directories and to compare two directories visually.\n\n## Work in Dual-Pane Mode\n\nTo switch between single-pane and dual-pane mode:\n\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e to switch from single-pane to dual-pane mode and back.\n\nTo move focus between the left and right panes:\n\n- Use \u003ckbd\u003eTab\u003c/kbd\u003e to move the input focus between the left and right pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e to focus the left pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e to focus the right pane.\n\nTo copy or move files and directories:\n\n- Press \u003ckbd\u003eF5\u003c/kbd\u003e to copy the currently selected items in the active pane to the location in the inactive pane.\n- Press \u003ckbd\u003eF6\u003c/kbd\u003e to move instead of copying.\n\n{{\u003c admonition type=\"note\" \u003e}}\nYou can copy and move files and directories between different SMB connections, different local drives, and SMB connections and local drives. Sambee completes the destination copy before it removes the original during a move.\n{{\u003c /admonition \u003e}}\n\nWhile a copy or move is in progress, the dialog shows its progress. Select Cancel to stop an active transfer. If a destination item already exists, use the Target already exists dialog to skip it or choose a different name.\n\nIf Sambee creates the destination for a move but can't remove the original, it reports the partial move and keeps the original in place. Review both panes before trying the move again.\n\n## Extract Selected ZIP Members\n\nWhen the active pane shows a ZIP archive, select the files or directories to extract and press \u003ckbd\u003eF5\u003c/kbd\u003e. Sambee extracts the selected members into the physical location in the inactive pane. Selecting a directory extracts all of its contents, including empty directories.\n\nArchive members can't be moved. \u003ckbd\u003eF6\u003c/kbd\u003e stays unavailable in a ZIP archive pane and doesn't modify the archive.\n\n## Requirements\n\n- Dual-pane mode is currently a desktop-only feature (i.e., not available on mobile due to screen size limitations).\n", "2.0": "+++\ntitle = \"Dual-Pane Mode\"\n+++\n\nSambee's dual-pane mode shows the contents of two directories next to each other. This layout was popularized by Norton Commander and later Total Commander. It makes it easier to move or copy files between directories and to compare two directories visually.\n\n## Work in Dual-Pane Mode\n\nTo switch between single-pane and dual-pane mode:\n\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e to switch from single-pane to dual-pane mode and back.\n\nTo move focus between the left and right panes:\n\n- Use \u003ckbd\u003eTab\u003c/kbd\u003e to move the input focus between the left and right pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e to focus the left pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e to focus the right pane.\n\nTo copy or move files and directories:\n\n- Press \u003ckbd\u003eF5\u003c/kbd\u003e to copy the currently selected items in the active pane to the location in the inactive pane.\n- Press \u003ckbd\u003eF6\u003c/kbd\u003e to move instead of copying.\n\n{{\u003c admonition type=\"note\" \u003e}}\nYou can copy and move files and directories between different SMB connections, different local drives, and SMB connections and local drives. Sambee completes the destination copy before it removes the original during a move.\n{{\u003c /admonition \u003e}}\n\nWhile a copy or move is in progress, the dialog shows its progress. Select Cancel to stop an active transfer. If a destination file already exists, use the Target already exists dialog to skip it, overwrite it, overwrite it only when the source is newer, or choose a different name. Apply the choice to remaining conflicts when appropriate. Directories with the same name are merged without removing destination-only entries. A file can't replace a directory or vice versa.\n\n### Partial Moves and Cancellation\n\nTransfers between SMB connections publish a complete destination file before removing the source. An authorized overwrite replaces the destination atomically, without first deleting the visible file. During a move, Sambee protects the opened source from concurrent writes and renames; an incompatible open writer can prevent the transfer from starting.\n\n- Cancelling before publication leaves both locations unchanged for that file.\n- Cancelling after publication but before source deletion keeps the destination and reports that the source was retained.\n- A rejected source deletion also keeps the destination and reports the retained source.\n- If a deletion acknowledgement or final close is lost, Sambee reports uncertainty about the source while retaining the confirmed destination. Cancellation after deletion has started can't guarantee that the source remains.\n\nSambee refreshes both panes after a batch. A directory can be partially moved even when its overall result is cancelled, failed, or uncertain. Earlier completed files and confirmed replacements aren't rolled back. An uncertain child stops the remaining batch; a retained-source warning can allow later items to continue. Each selected directory keeps the destination parent captured when the confirmation dialog opened.\n\nAfter a partial or uncertain move, inspect both locations before starting another operation. Don't assume the source was retained when its deletion couldn't be confirmed. The completed dialog offers Close rather than repeating the batch. If source validation fails after a copy was published, the destination remains and Sambee reports the validation failure.\n\n## Extract Selected ZIP Members\n\nWhen the active pane shows a ZIP archive, select the files or directories to extract and press \u003ckbd\u003eF5\u003c/kbd\u003e. Sambee extracts the selected members into the physical location in the inactive pane. Selecting a directory extracts all of its contents, including empty directories.\n\nArchive members can't be moved. \u003ckbd\u003eF6\u003c/kbd\u003e stays unavailable in a ZIP archive pane and doesn't modify the archive.\n\n## Requirements\n\n- Dual-pane mode is currently a desktop-only feature (i.e., not available on mobile due to screen size limitations).\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:user-guide/browsing-and-navigation/keyboard-navigation-and-shortcuts", "parent_id": "section:user-guide/browsing-and-navigation", "depth": 2, "kind": "page", "label": "keyboard-navigation-and-shortcuts", "title": "Keyboard Navigation And Shortcuts", "path": "user-guide/browsing-and-navigation/keyboard-navigation-and-shortcuts", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "branched", "source_version": "0.7", "diff_added": 37, "diff_removed": 4}, "2.0": {"state": "inherited", "source_version": "1.0"}}, "content_versions": {"0.7": "+++\ntitle = \"Keyboard Navigation and Shortcuts\"\n+++\n\nKeyboard navigation is a first-class part of Sambee.\n\n## Keyboard-First Principles\n\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many file browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n- Safety still wins: Shortcuts that would be unsafe in text fields, dialogs, or incompatible states are intentionally blocked.\n\nIf you want the live in-app list, press \u003ckbd\u003e?\u003c/kbd\u003e while using Sambee.\n\n## File List and Main UI\n\nUse these shortcuts when the main file list or browser shell has focus.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eDown\u003c/kbd\u003e | Move to the previous or next row in the current file list |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last visible item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move up or down by a page in the current list |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file or enter the focused directory |\n| \u003ckbd\u003eBackspace\u003c/kbd\u003e | Go up to the parent directory |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Open the connection selector |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Open smart navigation |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Filter the current directory in the active pane |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e / \u003ckbd\u003eF1\u003c/kbd\u003e | Open commands |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e,\u003c/kbd\u003e | Open settings |\n| \u003ckbd\u003e?\u003c/kbd\u003e | Show keyboard shortcuts help |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Refresh the current file list |\n| \u003ckbd\u003eF2\u003c/kbd\u003e | Rename the focused item |\n| \u003ckbd\u003eDel\u003c/kbd\u003e | Delete the focused item |\n| \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new directory |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file in the companion app |\n\n## Selection and Dual-Pane Workflows\n\nThese shortcuts matter most when you are working keyboard-first across one or two panes.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eIns\u003c/kbd\u003e or \u003ckbd\u003eSpace\u003c/kbd\u003e | Toggle selection on the focused item and move down |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Extend selection upward or downward |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eA\u003c/kbd\u003e | Select all items in the current list |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e | Toggle dual-pane mode |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e / \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e | Focus the left or right pane |\n| \u003ckbd\u003eTab\u003c/kbd\u003e | Move focus to the other pane |\n| \u003ckbd\u003eF5\u003c/kbd\u003e / \u003ckbd\u003eF6\u003c/kbd\u003e | Copy or move selected items to the other pane |\n\n## Viewers\n\nViewers share a common keyboard model for closing, searching, paging, and visual controls.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the viewer |\n| \u003ckbd\u003eD\u003c/kbd\u003e | Download the current file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search inside supported viewers |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last page or item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move to the previous or next page |\n| \u003ckbd\u003eLeft\u003c/kbd\u003e / \u003ckbd\u003eRight\u003c/kbd\u003e | Move to the previous or next page or item |\n| \u003ckbd\u003e+\u003c/kbd\u003e / \u003ckbd\u003e-\u003c/kbd\u003e | Zoom in or out |\n| \u003ckbd\u003e0\u003c/kbd\u003e | Reset zoom |\n| \u003ckbd\u003eR\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Rotate right or left |\n| \u003ckbd\u003eF\u003c/kbd\u003e | Toggle fullscreen |\n\nSome viewer shortcuts depend on the file type. For example, search applies to searchable viewers, and page navigation applies to paged or gallery-style viewers.\n\n## Markdown Editor\n\nMarkdown files build on the shared viewer shortcuts and add editor-specific formatting actions.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eE\u003c/kbd\u003e | Switch a Markdown file from viewing to editing |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e | Save the current Markdown file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search in the current Markdown content |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Create a link |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eT\u003c/kbd\u003e | Insert a table |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Insert a thematic break |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Apply inline code |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Insert a code block |\n| \u003ckbd\u003eF\u003c/kbd\u003e | Toggle fullscreen in the Markdown viewer |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the Markdown viewer |\n\n## When to Use the Built-In Shortcut Help\n\nThis page summarizes the most useful keyboard shortcuts by UI area.\n\nUse the built-in shortcuts help when you want the live in-app list for your current screen, or when you want a quick reminder without leaving the file browser.\n", "0.8": "+++\ntitle = \"Keyboard Navigation and Shortcuts\"\n+++\n\nKeyboard navigation is a first-class part of Sambee.\n\n## Keyboard-First Principles\n\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many file browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n- Safety still wins: Shortcuts that would be unsafe in text fields, dialogs, or incompatible states are intentionally blocked.\n\nIf you want the live in-app list, press \u003ckbd\u003e?\u003c/kbd\u003e while using Sambee.\n\n## File List and Main UI\n\nUse these shortcuts when the main file list or browser shell has focus.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eDown\u003c/kbd\u003e | Move to the previous or next row in the current file list |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last visible item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move up or down by a page in the current list |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file or enter the focused directory |\n| \u003ckbd\u003eBackspace\u003c/kbd\u003e | Go up to the parent directory |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Open the connection selector |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Open smart navigation |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Filter the current directory in the active pane |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e / \u003ckbd\u003eF1\u003c/kbd\u003e | Open commands |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e,\u003c/kbd\u003e | Open settings |\n| \u003ckbd\u003e?\u003c/kbd\u003e | Show keyboard shortcuts help |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Refresh the current file list |\n| \u003ckbd\u003eF2\u003c/kbd\u003e | Rename the focused item |\n| \u003ckbd\u003eDel\u003c/kbd\u003e | Delete the focused item |\n| \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new directory |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file in the companion app |\n\n## Selection and Dual-Pane Workflows\n\nThese shortcuts matter most when you are working keyboard-first across one or two panes.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eIns\u003c/kbd\u003e or \u003ckbd\u003eSpace\u003c/kbd\u003e | Toggle selection on the focused item and move down |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Extend selection upward or downward |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eA\u003c/kbd\u003e | Select all items in the current list |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e | Toggle dual-pane mode |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e / \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e | Focus the left or right pane |\n| \u003ckbd\u003eTab\u003c/kbd\u003e | Move focus to the other pane |\n| \u003ckbd\u003eF5\u003c/kbd\u003e / \u003ckbd\u003eF6\u003c/kbd\u003e | Copy or move selected items to the other pane |\n\n## Viewers\n\nViewers share a common keyboard model for closing, searching, paging, and visual controls.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the viewer |\n| \u003ckbd\u003eD\u003c/kbd\u003e | Download the current file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search inside supported viewers |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last page or item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move to the previous or next page |\n| \u003ckbd\u003eLeft\u003c/kbd\u003e / \u003ckbd\u003eRight\u003c/kbd\u003e | Move to the previous or next page or item |\n| \u003ckbd\u003e+\u003c/kbd\u003e / \u003ckbd\u003e-\u003c/kbd\u003e | Zoom in or out |\n| \u003ckbd\u003e0\u003c/kbd\u003e | Reset zoom |\n| \u003ckbd\u003eR\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Rotate right or left |\n| \u003ckbd\u003eF\u003c/kbd\u003e | Toggle fullscreen |\n\nSome viewer shortcuts depend on the file type. For example, search applies to searchable viewers, and page navigation applies to paged or gallery-style viewers.\n\n## Markdown Editor\n\nMarkdown files build on the shared viewer shortcuts and add editor-specific formatting actions.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eE\u003c/kbd\u003e | Switch a Markdown file from viewing to editing |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e | Save the current Markdown file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search in the current Markdown content |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Create a link |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eT\u003c/kbd\u003e | Insert a table |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Insert a thematic break |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Apply inline code |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Insert a code block |\n| \u003ckbd\u003eF\u003c/kbd\u003e | Toggle fullscreen in the Markdown viewer |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the Markdown viewer |\n\n## When to Use the Built-In Shortcut Help\n\nThis page summarizes the most useful keyboard shortcuts by UI area.\n\nUse the built-in shortcuts help when you want the live in-app list for your current screen, or when you want a quick reminder without leaving the file browser.\n", "0.9": "+++\ntitle = \"Keyboard Navigation and Shortcuts\"\n+++\n\nKeyboard navigation is a first-class part of Sambee.\n\n## Keyboard-First Principles\n\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many file browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n- Safety still wins: Shortcuts that would be unsafe in text fields, dialogs, or incompatible states are intentionally blocked.\n\nIf you want the live in-app list, press \u003ckbd\u003e?\u003c/kbd\u003e while using Sambee.\n\n## File List and Main UI\n\nUse these shortcuts when the main file list or browser shell has focus.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eDown\u003c/kbd\u003e | Move to the previous or next row in the current file list |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last visible item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move up or down by a page in the current list |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file or enter the focused directory |\n| \u003ckbd\u003eBackspace\u003c/kbd\u003e | Go up to the parent directory |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Open the connection selector |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Open smart navigation |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Filter the current directory in the active pane |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e / \u003ckbd\u003eF1\u003c/kbd\u003e | Open commands |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e,\u003c/kbd\u003e | Open settings |\n| \u003ckbd\u003e?\u003c/kbd\u003e | Show keyboard shortcuts help |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Refresh the current file list |\n| \u003ckbd\u003eF2\u003c/kbd\u003e | Rename the focused item |\n| \u003ckbd\u003eDel\u003c/kbd\u003e | Delete the focused item |\n| \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new directory |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file in the companion app |\n\n## Selection and Dual-Pane Workflows\n\nThese shortcuts matter most when you are working keyboard-first across one or two panes.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eIns\u003c/kbd\u003e or \u003ckbd\u003eSpace\u003c/kbd\u003e | Toggle selection on the focused item and move down |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Extend selection upward or downward |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eA\u003c/kbd\u003e | Select all items in the current list |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e | Toggle dual-pane mode |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e / \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e | Focus the left or right pane |\n| \u003ckbd\u003eTab\u003c/kbd\u003e | Move focus to the other pane |\n| \u003ckbd\u003eF5\u003c/kbd\u003e / \u003ckbd\u003eF6\u003c/kbd\u003e | Copy or move selected items to the other pane |\n\n## Viewers\n\nViewers share a common keyboard model for closing, searching, paging, and visual controls.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the viewer |\n| \u003ckbd\u003eD\u003c/kbd\u003e | Download the current file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search inside supported viewers |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last page or item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move to the previous or next page |\n| \u003ckbd\u003eLeft\u003c/kbd\u003e / \u003ckbd\u003eRight\u003c/kbd\u003e | Move to the previous or next page or item |\n| \u003ckbd\u003e+\u003c/kbd\u003e / \u003ckbd\u003e-\u003c/kbd\u003e | Zoom in or out |\n| \u003ckbd\u003e0\u003c/kbd\u003e | Reset zoom |\n| \u003ckbd\u003eR\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Rotate right or left |\n| \u003ckbd\u003eF\u003c/kbd\u003e | Toggle fullscreen |\n\nSome viewer shortcuts depend on the file type. For example, search applies to searchable viewers, and page navigation applies to paged or gallery-style viewers.\n\n## Markdown Editor\n\nMarkdown files build on the shared viewer shortcuts and add editor-specific formatting actions.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eE\u003c/kbd\u003e | Switch a Markdown file from viewing to editing |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e | Save the current Markdown file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search in the current Markdown content |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Create a link |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eT\u003c/kbd\u003e | Insert a table |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Insert a thematic break |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Apply inline code |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Insert a code block |\n| \u003ckbd\u003eF\u003c/kbd\u003e | Toggle fullscreen in the Markdown viewer |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the Markdown viewer |\n\n## When to Use the Built-In Shortcut Help\n\nThis page summarizes the most useful keyboard shortcuts by UI area.\n\nUse the built-in shortcuts help when you want the live in-app list for your current screen, or when you want a quick reminder without leaving the file browser.\n", "1.0": "+++\ntitle = \"Keyboard Navigation and Shortcuts\"\n+++\n\nKeyboard navigation is a first-class part of Sambee.\n\n## Keyboard-First Principles\n\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many file browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n- Safety still wins: Shortcuts that would be unsafe in text fields, dialogs, or incompatible states are intentionally blocked.\n\nIf you want the live in-app list, press \u003ckbd\u003e?\u003c/kbd\u003e or \u003ckbd\u003eF1\u003c/kbd\u003e. While editing Markdown or text, use \u003ckbd\u003eF1\u003c/kbd\u003e so you can type question marks normally.\n\n## File List and Main UI\n\nUse these shortcuts when the main file list or browser shell has focus.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eDown\u003c/kbd\u003e | Move to the previous or next row in the current file list |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last visible item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move up or down by a page in the current list |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file or enter the focused directory |\n| \u003ckbd\u003eBackspace\u003c/kbd\u003e | Go up to the parent directory |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Open the connection selector |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Open smart navigation |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Filter the current directory in the active pane |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e | Open commands |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e,\u003c/kbd\u003e | Open settings |\n| \u003ckbd\u003e?\u003c/kbd\u003e / \u003ckbd\u003eF1\u003c/kbd\u003e | Show keyboard shortcuts help |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Refresh the current file list |\n| \u003ckbd\u003eF2\u003c/kbd\u003e | Rename the focused item |\n| \u003ckbd\u003eDel\u003c/kbd\u003e | Delete the focused item |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eD\u003c/kbd\u003e | Download the selected items, or the focused item if nothing is selected |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eU\u003c/kbd\u003e | Upload files to the current writable folder |\n| \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new directory |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file in the companion app |\n\nWhen the focused item is a local shortcut or filesystem link, Sambee resolves its target before activating it. A directory target opens in its drive and directory, including a different local drive. A file target follows the same behavior as opening that file directly: \u003ckbd\u003eEnter\u003c/kbd\u003e uses the selected viewer, while \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e opens it in the companion app. If the target is missing or inaccessible, Sambee shows an error instead of opening the link itself.\n\n## Selection and Dual-Pane Workflows\n\nThese shortcuts matter most when you are working keyboard-first across one or two panes.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eIns\u003c/kbd\u003e or \u003ckbd\u003eSpace\u003c/kbd\u003e | Toggle selection on the focused item and move down |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Extend selection upward or downward |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eA\u003c/kbd\u003e | Select all items in the current list |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e | Toggle dual-pane mode |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e / \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e | Focus the left or right pane |\n| \u003ckbd\u003eTab\u003c/kbd\u003e | Move focus to the other pane |\n| \u003ckbd\u003eF5\u003c/kbd\u003e / \u003ckbd\u003eF6\u003c/kbd\u003e | Copy or move selected items to the other pane |\n\n## Viewers\n\nViewers share a common keyboard model for closing, searching, paging, and visual controls.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the viewer |\n| \u003ckbd\u003eD\u003c/kbd\u003e | Download the current file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search inside supported viewers |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last page or item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move to the previous or next page |\n| \u003ckbd\u003eLeft\u003c/kbd\u003e / \u003ckbd\u003eRight\u003c/kbd\u003e | Move to the previous or next page or item |\n| \u003ckbd\u003e+\u003c/kbd\u003e / \u003ckbd\u003e-\u003c/kbd\u003e | Zoom in or out |\n| \u003ckbd\u003e0\u003c/kbd\u003e | Reset zoom |\n| \u003ckbd\u003eR\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Rotate right or left |\n| \u003ckbd\u003eF\u003c/kbd\u003e | Toggle fullscreen |\n| \u003ckbd\u003e?\u003c/kbd\u003e / \u003ckbd\u003eF1\u003c/kbd\u003e | Show keyboard shortcuts help |\n\nSome viewer shortcuts depend on the file type. For example, search applies to searchable viewers, and page navigation applies to paged or gallery-style viewers.\n\n## Markdown Editor\n\nMarkdown files build on the shared viewer shortcuts and add editor-specific formatting actions.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eE\u003c/kbd\u003e | Switch a Markdown file from viewing to editing |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e | Save the current Markdown file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e | Toggle bold text |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eI\u003c/kbd\u003e | Toggle italic text |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search in the current Markdown content |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Open find and replace for the current Markdown content |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e in the Replace field | Replace the current match |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e in the Replace field | Replace all matches |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eC\u003c/kbd\u003e | Toggle case-sensitive matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eW\u003c/kbd\u003e | Toggle whole-word matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Toggle regular-expression matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eZ\u003c/kbd\u003e | Toggle word wrap |\n| \u003ckbd\u003eF1\u003c/kbd\u003e | Show Text editor shortcuts |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Create a link |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eT\u003c/kbd\u003e | Insert a table |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Insert a thematic break |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Apply inline code |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Insert a code block |\n| \u003ckbd\u003eF1\u003c/kbd\u003e | Show Markdown editor shortcuts |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the Markdown viewer |\n\nFind and replace opens as a compact panel in the upper-right of the viewer, with a small margin below the toolbar. It shows the current match and total result count. Use the visible previous, next, replace, and replace-all controls after entering a search. The fields display `Search (\u21c5 for history)` and `Replace (\u21c5 for history)` until you type; each keeps up to ten recent values locally, available with \u003ckbd\u003eUp\u003c/kbd\u003e and \u003ckbd\u003eDown\u003c/kbd\u003e. Invalid regular expressions are reported without changing the document.\n\n## Text Editor\n\nText files use the same CodeMirror find controls as the Markdown editor. Find is available while viewing or editing a supported text file; replace is available while editing.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search in the current text content |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Open find and replace while editing |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e in the Replace field | Replace the current match |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e in the Replace field | Replace all matches |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eC\u003c/kbd\u003e | Toggle case-sensitive matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eW\u003c/kbd\u003e | Toggle whole-word matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Toggle regular-expression matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eZ\u003c/kbd\u003e | Toggle word wrap |\n\n## When to Use the Built-In Shortcut Help\n\nThis page summarizes the most useful keyboard shortcuts by UI area.\n\nUse the built-in shortcuts help when you want the live in-app list for your current screen, or when you want a quick reminder without leaving the file browser.\n", "2.0": "+++\ntitle = \"Keyboard Navigation and Shortcuts\"\n+++\n\nKeyboard navigation is a first-class part of Sambee.\n\n## Keyboard-First Principles\n\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many file browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n- Safety still wins: Shortcuts that would be unsafe in text fields, dialogs, or incompatible states are intentionally blocked.\n\nIf you want the live in-app list, press \u003ckbd\u003e?\u003c/kbd\u003e or \u003ckbd\u003eF1\u003c/kbd\u003e. While editing Markdown or text, use \u003ckbd\u003eF1\u003c/kbd\u003e so you can type question marks normally.\n\n## File List and Main UI\n\nUse these shortcuts when the main file list or browser shell has focus.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eDown\u003c/kbd\u003e | Move to the previous or next row in the current file list |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last visible item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move up or down by a page in the current list |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file or enter the focused directory |\n| \u003ckbd\u003eBackspace\u003c/kbd\u003e | Go up to the parent directory |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Open the connection selector |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Open smart navigation |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Filter the current directory in the active pane |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e | Open commands |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e,\u003c/kbd\u003e | Open settings |\n| \u003ckbd\u003e?\u003c/kbd\u003e / \u003ckbd\u003eF1\u003c/kbd\u003e | Show keyboard shortcuts help |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Refresh the current file list |\n| \u003ckbd\u003eF2\u003c/kbd\u003e | Rename the focused item |\n| \u003ckbd\u003eDel\u003c/kbd\u003e | Delete the focused item |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eD\u003c/kbd\u003e | Download the selected items, or the focused item if nothing is selected |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eU\u003c/kbd\u003e | Upload files to the current writable folder |\n| \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new directory |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file in the companion app |\n\nWhen the focused item is a local shortcut or filesystem link, Sambee resolves its target before activating it. A directory target opens in its drive and directory, including a different local drive. A file target follows the same behavior as opening that file directly: \u003ckbd\u003eEnter\u003c/kbd\u003e uses the selected viewer, while \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e opens it in the companion app. If the target is missing or inaccessible, Sambee shows an error instead of opening the link itself.\n\n## Selection and Dual-Pane Workflows\n\nThese shortcuts matter most when you are working keyboard-first across one or two panes.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eIns\u003c/kbd\u003e or \u003ckbd\u003eSpace\u003c/kbd\u003e | Toggle selection on the focused item and move down |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Extend selection upward or downward |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eA\u003c/kbd\u003e | Select all items in the current list |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e | Toggle dual-pane mode |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e / \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e | Focus the left or right pane |\n| \u003ckbd\u003eTab\u003c/kbd\u003e | Move focus to the other pane |\n| \u003ckbd\u003eF5\u003c/kbd\u003e / \u003ckbd\u003eF6\u003c/kbd\u003e | Copy or move selected items to the other pane |\n\n## Viewers\n\nViewers share a common keyboard model for closing, searching, paging, and visual controls.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the viewer |\n| \u003ckbd\u003eD\u003c/kbd\u003e | Download the current file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search inside supported viewers |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last page or item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move to the previous or next page |\n| \u003ckbd\u003eLeft\u003c/kbd\u003e / \u003ckbd\u003eRight\u003c/kbd\u003e | Move to the previous or next page or item |\n| \u003ckbd\u003e+\u003c/kbd\u003e / \u003ckbd\u003e-\u003c/kbd\u003e | Zoom in or out |\n| \u003ckbd\u003e0\u003c/kbd\u003e | Reset zoom |\n| \u003ckbd\u003eR\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Rotate right or left |\n| \u003ckbd\u003eF\u003c/kbd\u003e | Toggle fullscreen |\n| \u003ckbd\u003e?\u003c/kbd\u003e / \u003ckbd\u003eF1\u003c/kbd\u003e | Show keyboard shortcuts help |\n\nSome viewer shortcuts depend on the file type. For example, search applies to searchable viewers, and page navigation applies to paged or gallery-style viewers.\n\n## Markdown Editor\n\nMarkdown files build on the shared viewer shortcuts and add editor-specific formatting actions.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eE\u003c/kbd\u003e | Switch a Markdown file from viewing to editing |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e | Save the current Markdown file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e | Toggle bold text |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eI\u003c/kbd\u003e | Toggle italic text |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search in the current Markdown content |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Open find and replace for the current Markdown content |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e in the Replace field | Replace the current match |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e in the Replace field | Replace all matches |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eC\u003c/kbd\u003e | Toggle case-sensitive matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eW\u003c/kbd\u003e | Toggle whole-word matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Toggle regular-expression matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eZ\u003c/kbd\u003e | Toggle word wrap |\n| \u003ckbd\u003eF1\u003c/kbd\u003e | Show Text editor shortcuts |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Create a link |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eT\u003c/kbd\u003e | Insert a table |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Insert a thematic break |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Apply inline code |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Insert a code block |\n| \u003ckbd\u003eF1\u003c/kbd\u003e | Show Markdown editor shortcuts |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the Markdown viewer |\n\nFind and replace opens as a compact panel in the upper-right of the viewer, with a small margin below the toolbar. It shows the current match and total result count. Use the visible previous, next, replace, and replace-all controls after entering a search. The fields display `Search (\u21c5 for history)` and `Replace (\u21c5 for history)` until you type; each keeps up to ten recent values locally, available with \u003ckbd\u003eUp\u003c/kbd\u003e and \u003ckbd\u003eDown\u003c/kbd\u003e. Invalid regular expressions are reported without changing the document.\n\n## Text Editor\n\nText files use the same CodeMirror find controls as the Markdown editor. Find is available while viewing or editing a supported text file; replace is available while editing.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search in the current text content |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Open find and replace while editing |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e in the Replace field | Replace the current match |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e in the Replace field | Replace all matches |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eC\u003c/kbd\u003e | Toggle case-sensitive matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eW\u003c/kbd\u003e | Toggle whole-word matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Toggle regular-expression matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eZ\u003c/kbd\u003e | Toggle word wrap |\n\n## When to Use the Built-In Shortcut Help\n\nThis page summarizes the most useful keyboard shortcuts by UI area.\n\nUse the built-in shortcuts help when you want the live in-app list for your current screen, or when you want a quick reminder without leaving the file browser.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Keyboard Navigation and Shortcuts\"\n+++\n\nKeyboard navigation is a first-class part of Sambee.\n\n## Keyboard-First Principles\n\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many file browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n- Safety still wins: Shortcuts that would be unsafe in text fields, dialogs, or incompatible states are intentionally blocked.\n\nIf you want the live in-app list, press \u003ckbd\u003e?\u003c/kbd\u003e while using Sambee.\n\n## File List and Main UI\n\nUse these shortcuts when the main file list or browser shell has focus.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eDown\u003c/kbd\u003e | Move to the previous or next row in the current file list |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last visible item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move up or down by a page in the current list |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file or enter the focused directory |\n| \u003ckbd\u003eBackspace\u003c/kbd\u003e | Go up to the parent directory |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Open the connection selector |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Open smart navigation |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Filter the current directory in the active pane |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e / \u003ckbd\u003eF1\u003c/kbd\u003e | Open commands |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e,\u003c/kbd\u003e | Open settings |\n| \u003ckbd\u003e?\u003c/kbd\u003e | Show keyboard shortcuts help |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Refresh the current file list |\n| \u003ckbd\u003eF2\u003c/kbd\u003e | Rename the focused item |\n| \u003ckbd\u003eDel\u003c/kbd\u003e | Delete the focused item |\n| \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new directory |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file in the companion app |\n\n## Selection and Dual-Pane Workflows\n\nThese shortcuts matter most when you are working keyboard-first across one or two panes.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eIns\u003c/kbd\u003e or \u003ckbd\u003eSpace\u003c/kbd\u003e | Toggle selection on the focused item and move down |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Extend selection upward or downward |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eA\u003c/kbd\u003e | Select all items in the current list |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e | Toggle dual-pane mode |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e / \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e | Focus the left or right pane |\n| \u003ckbd\u003eTab\u003c/kbd\u003e | Move focus to the other pane |\n| \u003ckbd\u003eF5\u003c/kbd\u003e / \u003ckbd\u003eF6\u003c/kbd\u003e | Copy or move selected items to the other pane |\n\n## Viewers\n\nViewers share a common keyboard model for closing, searching, paging, and visual controls.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the viewer |\n| \u003ckbd\u003eD\u003c/kbd\u003e | Download the current file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search inside supported viewers |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last page or item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move to the previous or next page |\n| \u003ckbd\u003eLeft\u003c/kbd\u003e / \u003ckbd\u003eRight\u003c/kbd\u003e | Move to the previous or next page or item |\n| \u003ckbd\u003e+\u003c/kbd\u003e / \u003ckbd\u003e-\u003c/kbd\u003e | Zoom in or out |\n| \u003ckbd\u003e0\u003c/kbd\u003e | Reset zoom |\n| \u003ckbd\u003eR\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Rotate right or left |\n| \u003ckbd\u003eF\u003c/kbd\u003e | Toggle fullscreen |\n\nSome viewer shortcuts depend on the file type. For example, search applies to searchable viewers, and page navigation applies to paged or gallery-style viewers.\n\n## Markdown Editor\n\nMarkdown files build on the shared viewer shortcuts and add editor-specific formatting actions.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eE\u003c/kbd\u003e | Switch a Markdown file from viewing to editing |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e | Save the current Markdown file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search in the current Markdown content |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Create a link |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eT\u003c/kbd\u003e | Insert a table |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Insert a thematic break |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Apply inline code |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Insert a code block |\n| \u003ckbd\u003eF\u003c/kbd\u003e | Toggle fullscreen in the Markdown viewer |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the Markdown viewer |\n\n## When to Use the Built-In Shortcut Help\n\nThis page summarizes the most useful keyboard shortcuts by UI area.\n\nUse the built-in shortcuts help when you want the live in-app list for your current screen, or when you want a quick reminder without leaving the file browser.\n", "0.8": "+++\ntitle = \"Keyboard Navigation and Shortcuts\"\n+++\n\nKeyboard navigation is a first-class part of Sambee.\n\n## Keyboard-First Principles\n\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many file browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n- Safety still wins: Shortcuts that would be unsafe in text fields, dialogs, or incompatible states are intentionally blocked.\n\nIf you want the live in-app list, press \u003ckbd\u003e?\u003c/kbd\u003e while using Sambee.\n\n## File List and Main UI\n\nUse these shortcuts when the main file list or browser shell has focus.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eDown\u003c/kbd\u003e | Move to the previous or next row in the current file list |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last visible item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move up or down by a page in the current list |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file or enter the focused directory |\n| \u003ckbd\u003eBackspace\u003c/kbd\u003e | Go up to the parent directory |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Open the connection selector |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Open smart navigation |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Filter the current directory in the active pane |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e / \u003ckbd\u003eF1\u003c/kbd\u003e | Open commands |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e,\u003c/kbd\u003e | Open settings |\n| \u003ckbd\u003e?\u003c/kbd\u003e | Show keyboard shortcuts help |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Refresh the current file list |\n| \u003ckbd\u003eF2\u003c/kbd\u003e | Rename the focused item |\n| \u003ckbd\u003eDel\u003c/kbd\u003e | Delete the focused item |\n| \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new directory |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file in the companion app |\n\n## Selection and Dual-Pane Workflows\n\nThese shortcuts matter most when you are working keyboard-first across one or two panes.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eIns\u003c/kbd\u003e or \u003ckbd\u003eSpace\u003c/kbd\u003e | Toggle selection on the focused item and move down |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Extend selection upward or downward |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eA\u003c/kbd\u003e | Select all items in the current list |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e | Toggle dual-pane mode |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e / \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e | Focus the left or right pane |\n| \u003ckbd\u003eTab\u003c/kbd\u003e | Move focus to the other pane |\n| \u003ckbd\u003eF5\u003c/kbd\u003e / \u003ckbd\u003eF6\u003c/kbd\u003e | Copy or move selected items to the other pane |\n\n## Viewers\n\nViewers share a common keyboard model for closing, searching, paging, and visual controls.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the viewer |\n| \u003ckbd\u003eD\u003c/kbd\u003e | Download the current file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search inside supported viewers |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last page or item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move to the previous or next page |\n| \u003ckbd\u003eLeft\u003c/kbd\u003e / \u003ckbd\u003eRight\u003c/kbd\u003e | Move to the previous or next page or item |\n| \u003ckbd\u003e+\u003c/kbd\u003e / \u003ckbd\u003e-\u003c/kbd\u003e | Zoom in or out |\n| \u003ckbd\u003e0\u003c/kbd\u003e | Reset zoom |\n| \u003ckbd\u003eR\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Rotate right or left |\n| \u003ckbd\u003eF\u003c/kbd\u003e | Toggle fullscreen |\n\nSome viewer shortcuts depend on the file type. For example, search applies to searchable viewers, and page navigation applies to paged or gallery-style viewers.\n\n## Markdown Editor\n\nMarkdown files build on the shared viewer shortcuts and add editor-specific formatting actions.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eE\u003c/kbd\u003e | Switch a Markdown file from viewing to editing |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e | Save the current Markdown file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search in the current Markdown content |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Create a link |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eT\u003c/kbd\u003e | Insert a table |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Insert a thematic break |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Apply inline code |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Insert a code block |\n| \u003ckbd\u003eF\u003c/kbd\u003e | Toggle fullscreen in the Markdown viewer |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the Markdown viewer |\n\n## When to Use the Built-In Shortcut Help\n\nThis page summarizes the most useful keyboard shortcuts by UI area.\n\nUse the built-in shortcuts help when you want the live in-app list for your current screen, or when you want a quick reminder without leaving the file browser.\n", "0.9": "+++\ntitle = \"Keyboard Navigation and Shortcuts\"\n+++\n\nKeyboard navigation is a first-class part of Sambee.\n\n## Keyboard-First Principles\n\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many file browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n- Safety still wins: Shortcuts that would be unsafe in text fields, dialogs, or incompatible states are intentionally blocked.\n\nIf you want the live in-app list, press \u003ckbd\u003e?\u003c/kbd\u003e while using Sambee.\n\n## File List and Main UI\n\nUse these shortcuts when the main file list or browser shell has focus.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eDown\u003c/kbd\u003e | Move to the previous or next row in the current file list |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last visible item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move up or down by a page in the current list |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file or enter the focused directory |\n| \u003ckbd\u003eBackspace\u003c/kbd\u003e | Go up to the parent directory |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Open the connection selector |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Open smart navigation |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Filter the current directory in the active pane |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e / \u003ckbd\u003eF1\u003c/kbd\u003e | Open commands |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e,\u003c/kbd\u003e | Open settings |\n| \u003ckbd\u003e?\u003c/kbd\u003e | Show keyboard shortcuts help |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Refresh the current file list |\n| \u003ckbd\u003eF2\u003c/kbd\u003e | Rename the focused item |\n| \u003ckbd\u003eDel\u003c/kbd\u003e | Delete the focused item |\n| \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new directory |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file in the companion app |\n\n## Selection and Dual-Pane Workflows\n\nThese shortcuts matter most when you are working keyboard-first across one or two panes.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eIns\u003c/kbd\u003e or \u003ckbd\u003eSpace\u003c/kbd\u003e | Toggle selection on the focused item and move down |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Extend selection upward or downward |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eA\u003c/kbd\u003e | Select all items in the current list |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e | Toggle dual-pane mode |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e / \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e | Focus the left or right pane |\n| \u003ckbd\u003eTab\u003c/kbd\u003e | Move focus to the other pane |\n| \u003ckbd\u003eF5\u003c/kbd\u003e / \u003ckbd\u003eF6\u003c/kbd\u003e | Copy or move selected items to the other pane |\n\n## Viewers\n\nViewers share a common keyboard model for closing, searching, paging, and visual controls.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the viewer |\n| \u003ckbd\u003eD\u003c/kbd\u003e | Download the current file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search inside supported viewers |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last page or item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move to the previous or next page |\n| \u003ckbd\u003eLeft\u003c/kbd\u003e / \u003ckbd\u003eRight\u003c/kbd\u003e | Move to the previous or next page or item |\n| \u003ckbd\u003e+\u003c/kbd\u003e / \u003ckbd\u003e-\u003c/kbd\u003e | Zoom in or out |\n| \u003ckbd\u003e0\u003c/kbd\u003e | Reset zoom |\n| \u003ckbd\u003eR\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Rotate right or left |\n| \u003ckbd\u003eF\u003c/kbd\u003e | Toggle fullscreen |\n\nSome viewer shortcuts depend on the file type. For example, search applies to searchable viewers, and page navigation applies to paged or gallery-style viewers.\n\n## Markdown Editor\n\nMarkdown files build on the shared viewer shortcuts and add editor-specific formatting actions.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eE\u003c/kbd\u003e | Switch a Markdown file from viewing to editing |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e | Save the current Markdown file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search in the current Markdown content |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Create a link |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eT\u003c/kbd\u003e | Insert a table |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Insert a thematic break |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Apply inline code |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Insert a code block |\n| \u003ckbd\u003eF\u003c/kbd\u003e | Toggle fullscreen in the Markdown viewer |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the Markdown viewer |\n\n## When to Use the Built-In Shortcut Help\n\nThis page summarizes the most useful keyboard shortcuts by UI area.\n\nUse the built-in shortcuts help when you want the live in-app list for your current screen, or when you want a quick reminder without leaving the file browser.\n", "1.0": "+++\ntitle = \"Keyboard Navigation and Shortcuts\"\n+++\n\nKeyboard navigation is a first-class part of Sambee.\n\n## Keyboard-First Principles\n\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many file browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n- Safety still wins: Shortcuts that would be unsafe in text fields, dialogs, or incompatible states are intentionally blocked.\n\nIf you want the live in-app list, press \u003ckbd\u003e?\u003c/kbd\u003e or \u003ckbd\u003eF1\u003c/kbd\u003e. While editing Markdown or text, use \u003ckbd\u003eF1\u003c/kbd\u003e so you can type question marks normally.\n\n## File List and Main UI\n\nUse these shortcuts when the main file list or browser shell has focus.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eDown\u003c/kbd\u003e | Move to the previous or next row in the current file list |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last visible item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move up or down by a page in the current list |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file or enter the focused directory |\n| \u003ckbd\u003eBackspace\u003c/kbd\u003e | Go up to the parent directory |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Open the connection selector |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Open smart navigation |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Filter the current directory in the active pane |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e | Open commands |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e,\u003c/kbd\u003e | Open settings |\n| \u003ckbd\u003e?\u003c/kbd\u003e / \u003ckbd\u003eF1\u003c/kbd\u003e | Show keyboard shortcuts help |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Refresh the current file list |\n| \u003ckbd\u003eF2\u003c/kbd\u003e | Rename the focused item |\n| \u003ckbd\u003eDel\u003c/kbd\u003e | Delete the focused item |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eD\u003c/kbd\u003e | Download the selected items, or the focused item if nothing is selected |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eU\u003c/kbd\u003e | Upload files to the current writable folder |\n| \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new directory |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file in the companion app |\n\nWhen the focused item is a local shortcut or filesystem link, Sambee resolves its target before activating it. A directory target opens in its drive and directory, including a different local drive. A file target follows the same behavior as opening that file directly: \u003ckbd\u003eEnter\u003c/kbd\u003e uses the selected viewer, while \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e opens it in the companion app. If the target is missing or inaccessible, Sambee shows an error instead of opening the link itself.\n\n## Selection and Dual-Pane Workflows\n\nThese shortcuts matter most when you are working keyboard-first across one or two panes.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eIns\u003c/kbd\u003e or \u003ckbd\u003eSpace\u003c/kbd\u003e | Toggle selection on the focused item and move down |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Extend selection upward or downward |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eA\u003c/kbd\u003e | Select all items in the current list |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e | Toggle dual-pane mode |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e / \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e | Focus the left or right pane |\n| \u003ckbd\u003eTab\u003c/kbd\u003e | Move focus to the other pane |\n| \u003ckbd\u003eF5\u003c/kbd\u003e / \u003ckbd\u003eF6\u003c/kbd\u003e | Copy or move selected items to the other pane |\n\n## Viewers\n\nViewers share a common keyboard model for closing, searching, paging, and visual controls.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the viewer |\n| \u003ckbd\u003eD\u003c/kbd\u003e | Download the current file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search inside supported viewers |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last page or item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move to the previous or next page |\n| \u003ckbd\u003eLeft\u003c/kbd\u003e / \u003ckbd\u003eRight\u003c/kbd\u003e | Move to the previous or next page or item |\n| \u003ckbd\u003e+\u003c/kbd\u003e / \u003ckbd\u003e-\u003c/kbd\u003e | Zoom in or out |\n| \u003ckbd\u003e0\u003c/kbd\u003e | Reset zoom |\n| \u003ckbd\u003eR\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Rotate right or left |\n| \u003ckbd\u003eF\u003c/kbd\u003e | Toggle fullscreen |\n| \u003ckbd\u003e?\u003c/kbd\u003e / \u003ckbd\u003eF1\u003c/kbd\u003e | Show keyboard shortcuts help |\n\nSome viewer shortcuts depend on the file type. For example, search applies to searchable viewers, and page navigation applies to paged or gallery-style viewers.\n\n## Markdown Editor\n\nMarkdown files build on the shared viewer shortcuts and add editor-specific formatting actions.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eE\u003c/kbd\u003e | Switch a Markdown file from viewing to editing |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e | Save the current Markdown file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e | Toggle bold text |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eI\u003c/kbd\u003e | Toggle italic text |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search in the current Markdown content |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Open find and replace for the current Markdown content |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e in the Replace field | Replace the current match |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e in the Replace field | Replace all matches |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eC\u003c/kbd\u003e | Toggle case-sensitive matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eW\u003c/kbd\u003e | Toggle whole-word matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Toggle regular-expression matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eZ\u003c/kbd\u003e | Toggle word wrap |\n| \u003ckbd\u003eF1\u003c/kbd\u003e | Show Text editor shortcuts |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Create a link |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eT\u003c/kbd\u003e | Insert a table |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Insert a thematic break |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Apply inline code |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Insert a code block |\n| \u003ckbd\u003eF1\u003c/kbd\u003e | Show Markdown editor shortcuts |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the Markdown viewer |\n\nFind and replace opens as a compact panel in the upper-right of the viewer, with a small margin below the toolbar. It shows the current match and total result count. Use the visible previous, next, replace, and replace-all controls after entering a search. The fields display `Search (\u21c5 for history)` and `Replace (\u21c5 for history)` until you type; each keeps up to ten recent values locally, available with \u003ckbd\u003eUp\u003c/kbd\u003e and \u003ckbd\u003eDown\u003c/kbd\u003e. Invalid regular expressions are reported without changing the document.\n\n## Text Editor\n\nText files use the same CodeMirror find controls as the Markdown editor. Find is available while viewing or editing a supported text file; replace is available while editing.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search in the current text content |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Open find and replace while editing |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e in the Replace field | Replace the current match |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e in the Replace field | Replace all matches |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eC\u003c/kbd\u003e | Toggle case-sensitive matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eW\u003c/kbd\u003e | Toggle whole-word matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Toggle regular-expression matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eZ\u003c/kbd\u003e | Toggle word wrap |\n\n## When to Use the Built-In Shortcut Help\n\nThis page summarizes the most useful keyboard shortcuts by UI area.\n\nUse the built-in shortcuts help when you want the live in-app list for your current screen, or when you want a quick reminder without leaving the file browser.\n", "2.0": "+++\ntitle = \"Keyboard Navigation and Shortcuts\"\n+++\n\nKeyboard navigation is a first-class part of Sambee.\n\n## Keyboard-First Principles\n\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many file browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n- Safety still wins: Shortcuts that would be unsafe in text fields, dialogs, or incompatible states are intentionally blocked.\n\nIf you want the live in-app list, press \u003ckbd\u003e?\u003c/kbd\u003e or \u003ckbd\u003eF1\u003c/kbd\u003e. While editing Markdown or text, use \u003ckbd\u003eF1\u003c/kbd\u003e so you can type question marks normally.\n\n## File List and Main UI\n\nUse these shortcuts when the main file list or browser shell has focus.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eDown\u003c/kbd\u003e | Move to the previous or next row in the current file list |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last visible item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move up or down by a page in the current list |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file or enter the focused directory |\n| \u003ckbd\u003eBackspace\u003c/kbd\u003e | Go up to the parent directory |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Open the connection selector |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Open smart navigation |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Filter the current directory in the active pane |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e | Open commands |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e,\u003c/kbd\u003e | Open settings |\n| \u003ckbd\u003e?\u003c/kbd\u003e / \u003ckbd\u003eF1\u003c/kbd\u003e | Show keyboard shortcuts help |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Refresh the current file list |\n| \u003ckbd\u003eF2\u003c/kbd\u003e | Rename the focused item |\n| \u003ckbd\u003eDel\u003c/kbd\u003e | Delete the focused item |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eD\u003c/kbd\u003e | Download the selected items, or the focused item if nothing is selected |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eU\u003c/kbd\u003e | Upload files to the current writable folder |\n| \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new directory |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file in the companion app |\n\nWhen the focused item is a local shortcut or filesystem link, Sambee resolves its target before activating it. A directory target opens in its drive and directory, including a different local drive. A file target follows the same behavior as opening that file directly: \u003ckbd\u003eEnter\u003c/kbd\u003e uses the selected viewer, while \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e opens it in the companion app. If the target is missing or inaccessible, Sambee shows an error instead of opening the link itself.\n\n## Selection and Dual-Pane Workflows\n\nThese shortcuts matter most when you are working keyboard-first across one or two panes.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eIns\u003c/kbd\u003e or \u003ckbd\u003eSpace\u003c/kbd\u003e | Toggle selection on the focused item and move down |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Extend selection upward or downward |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eA\u003c/kbd\u003e | Select all items in the current list |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e | Toggle dual-pane mode |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e / \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e | Focus the left or right pane |\n| \u003ckbd\u003eTab\u003c/kbd\u003e | Move focus to the other pane |\n| \u003ckbd\u003eF5\u003c/kbd\u003e / \u003ckbd\u003eF6\u003c/kbd\u003e | Copy or move selected items to the other pane |\n\n## Viewers\n\nViewers share a common keyboard model for closing, searching, paging, and visual controls.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the viewer |\n| \u003ckbd\u003eD\u003c/kbd\u003e | Download the current file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search inside supported viewers |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last page or item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move to the previous or next page |\n| \u003ckbd\u003eLeft\u003c/kbd\u003e / \u003ckbd\u003eRight\u003c/kbd\u003e | Move to the previous or next page or item |\n| \u003ckbd\u003e+\u003c/kbd\u003e / \u003ckbd\u003e-\u003c/kbd\u003e | Zoom in or out |\n| \u003ckbd\u003e0\u003c/kbd\u003e | Reset zoom |\n| \u003ckbd\u003eR\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Rotate right or left |\n| \u003ckbd\u003eF\u003c/kbd\u003e | Toggle fullscreen |\n| \u003ckbd\u003e?\u003c/kbd\u003e / \u003ckbd\u003eF1\u003c/kbd\u003e | Show keyboard shortcuts help |\n\nSome viewer shortcuts depend on the file type. For example, search applies to searchable viewers, and page navigation applies to paged or gallery-style viewers.\n\n## Markdown Editor\n\nMarkdown files build on the shared viewer shortcuts and add editor-specific formatting actions.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eE\u003c/kbd\u003e | Switch a Markdown file from viewing to editing |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e | Save the current Markdown file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e | Toggle bold text |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eI\u003c/kbd\u003e | Toggle italic text |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search in the current Markdown content |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Open find and replace for the current Markdown content |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e in the Replace field | Replace the current match |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e in the Replace field | Replace all matches |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eC\u003c/kbd\u003e | Toggle case-sensitive matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eW\u003c/kbd\u003e | Toggle whole-word matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Toggle regular-expression matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eZ\u003c/kbd\u003e | Toggle word wrap |\n| \u003ckbd\u003eF1\u003c/kbd\u003e | Show Text editor shortcuts |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Create a link |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eT\u003c/kbd\u003e | Insert a table |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Insert a thematic break |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Apply inline code |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Insert a code block |\n| \u003ckbd\u003eF1\u003c/kbd\u003e | Show Markdown editor shortcuts |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the Markdown viewer |\n\nFind and replace opens as a compact panel in the upper-right of the viewer, with a small margin below the toolbar. It shows the current match and total result count. Use the visible previous, next, replace, and replace-all controls after entering a search. The fields display `Search (\u21c5 for history)` and `Replace (\u21c5 for history)` until you type; each keeps up to ten recent values locally, available with \u003ckbd\u003eUp\u003c/kbd\u003e and \u003ckbd\u003eDown\u003c/kbd\u003e. Invalid regular expressions are reported without changing the document.\n\n## Text Editor\n\nText files use the same CodeMirror find controls as the Markdown editor. Find is available while viewing or editing a supported text file; replace is available while editing.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search in the current text content |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Open find and replace while editing |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e in the Replace field | Replace the current match |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e in the Replace field | Replace all matches |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eC\u003c/kbd\u003e | Toggle case-sensitive matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eW\u003c/kbd\u003e | Toggle whole-word matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Toggle regular-expression matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eZ\u003c/kbd\u003e | Toggle word wrap |\n\n## When to Use the Built-In Shortcut Help\n\nThis page summarizes the most useful keyboard shortcuts by UI area.\n\nUse the built-in shortcuts help when you want the live in-app list for your current screen, or when you want a quick reminder without leaving the file browser.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:user-guide/browsing-and-navigation/mobile-navigation", "parent_id": "section:user-guide/browsing-and-navigation", "depth": 2, "kind": "page", "label": "mobile-navigation", "title": "Mobile Navigation", "path": "user-guide/browsing-and-navigation/mobile-navigation", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "branched", "source_version": "0.7", "diff_added": 35, "diff_removed": 0}}, "content_versions": {"0.7": "+++\ntitle = \"Mobile Navigation\"\n+++\n\nSambee is designed and optimized for phones and tablets as well as for desktops. Because each platform has different strengths, the mobile experience differs from the desktop experience in some cases.\n\n## Where Mobile Excels\n\nMobile is a good fit when you want to:\n\n- Explore network shares made available through Sambee.\n- View images, read PDFs, and edit Markdown files.\n- Share content from file servers on mobile platforms.\n\n## What Changes on Mobile\n\nCompared with desktop, mobile navigation is more compact:\n\n- The interface focuses on single-pane navigation.\n- Toolbar space is tighter.\n- Some desktop-oriented browser controls are simplified or moved behind menus.\n- Opening files in natively installed apps is not available.\n- Local drive access is not available.\n", "0.8": "+++\ntitle = \"Mobile Navigation\"\n+++\n\nSambee is designed and optimized for phones and tablets as well as for desktops. Because each platform has different strengths, the mobile experience differs from the desktop experience in some cases.\n\n## Where Mobile Excels\n\nMobile is a good fit when you want to:\n\n- Explore network shares made available through Sambee.\n- View images, read PDFs, and edit Markdown files.\n- Share content from file servers on mobile platforms.\n\n## What Changes on Mobile\n\nCompared with desktop, mobile navigation is more compact:\n\n- The interface focuses on single-pane navigation.\n- Toolbar space is tighter.\n- Some desktop-oriented browser controls are simplified or moved behind menus.\n- Opening files in natively installed apps is not available.\n- Local drive access is not available.\n", "0.9": "+++\ntitle = \"Mobile Navigation\"\n+++\n\nSambee is designed and optimized for phones and tablets as well as for desktops. Because each platform has different strengths, the mobile experience differs from the desktop experience in some cases.\n\n## Where Mobile Excels\n\nMobile is a good fit when you want to:\n\n- Explore network shares made available through Sambee.\n- View images, read PDFs, and edit Markdown files.\n- Share content from file servers on mobile platforms.\n\n## What Changes on Mobile\n\nCompared with desktop, mobile navigation is more compact:\n\n- The interface focuses on single-pane navigation.\n- Toolbar space is tighter.\n- Some desktop-oriented browser controls are simplified or moved behind menus.\n- Opening files in natively installed apps is not available.\n- Local drive access is not available.\n", "1.0": "+++\ntitle = \"Mobile Navigation\"\n+++\n\nSambee is designed and optimized for phones and tablets as well as for desktops. Because each platform has different strengths, the mobile experience differs from the desktop experience in some cases.\n\n## Where Mobile Excels\n\nMobile is a good fit when you want to:\n\n- Explore network shares made available through Sambee.\n- View images, read PDFs, and edit Markdown files.\n- Share content from file servers on mobile platforms.\n\n## What Changes on Mobile\n\nCompared with desktop, mobile navigation is more compact:\n\n- The interface focuses on single-pane navigation.\n- Toolbar space is tighter.\n- Some desktop-oriented browser controls are simplified or moved behind menus.\n- Opening files in natively installed apps is not available.\n- Local drive access is not available.\n", "2.0": "+++\ntitle = \"Mobile Navigation\"\n+++\n\nSambee is designed and optimized for phones and tablets as well as for desktops. Because each platform has different strengths, the mobile experience differs from the desktop experience in some cases.\n\n## Where Mobile Excels\n\nMobile is a good fit when you want to:\n\n- Explore network shares made available through Sambee.\n- View images, read PDFs, and edit Markdown files.\n- Share content from file servers on mobile platforms.\n\n## What Changes on Mobile\n\nCompared with desktop, mobile navigation is more compact:\n\n- The interface focuses on single-pane navigation.\n- Toolbar space is tighter.\n- Some desktop-oriented browser controls are simplified or moved behind menus.\n- Opening files in natively installed apps is not available.\n- Local drive access is not available.\n\n## Back, Forward, and Bookmarks\n\nOpening or closing a file, entering or leaving its editor, moving between gallery images, and navigating or closing settings update the browser address and add history entries. You can bookmark or share that address on desktop or mobile. The recipient still needs access to the connection and file; local-drive links also need a paired companion with that drive available.\n\nUse browser Back to retrace your navigation steps. If you open an image and close it, Back reopens that image; another Back returns to the file list from before you opened it. Forward follows those same locations in the other direction. Reopening an editor checks access and obtains a new edit lock. History doesn't undo saved file changes or restore discarded edits. Starting a new navigation after Back replaces the old Forward branch.\n\nIf you have unsaved edits, Back or another navigation asks you to **Save**, **Discard**, or **Cancel**. Cancel keeps your draft and current location. A failed save keeps you in the editor. Your browser can also warn before reloading or closing a tab with unsaved edits.\n\nSettings **Close** reveals the underlying workspace and adds a history entry, so browser Back reopens the last settings category. Closing a directly opened viewer or settings bookmark also adds an entry without sending you to an unrelated page. The mobile settings back arrow follows your history; without an earlier location observed in this workspace, it uses an in-app parent. Resizing between phone and desktop layouts keeps the selected settings category.\n\nRefreshing a bookmark restores its requested location, not a different workspace saved earlier in the tab. A missing file or unavailable connection offers recovery actions rather than silently opening another file.\n\n## Share Files and Text\n\nOn a phone, use **Share** in a file's action menu, or select several files and choose **Share** from the selection menu. Sambee prepares the stored files first. When they're ready, tap **Share** to open your device's share sheet. Multiple files are submitted together; Sambee doesn't silently drop files or retry a smaller selection.\n\nImage and PDF viewers have a sharing icon in the top bar. They share the resource you're viewing, including a compatible converted image or normalized PDF when needed. An image's extension matches the shared format. PDF sharing includes the whole displayed document, not just the visible page. Sharing from the file list instead uses the stored files without viewer conversions.\n\nIn text and Markdown viewers and editors, the same sharing icon opens two choices:\n\n- **Share as file** shares the saved file without saving your edits first.\n- **Share as text** shares the loaded text or your current editor contents, including unsaved changes. Markdown is shared as source text, not rendered HTML.\n\nThe file choice shows a preparation indicator while its attachment loads. You can still share text independently of that preparation.\n\nSharing availability and accepted attachment types depend on your browser and device. A browser can reject an attachment even after its capability check succeeds. Sambee won't silently replace a rejected attachment with text; choose **Share as text** explicitly where available.\n\n### If Sharing Fails\n\nWhen a prepared attachment can't be shared, use **Download** and try sharing it from your device's Files app. For failed image/PDF viewer sharing, this recovery download uses the same displayed resource. Ordinary download controls keep their existing behavior. For several files, download each prepared file in turn. If attachment preparation fails, text and Markdown viewers offer **Retry** without automatically opening the share sheet.\n\nChoose **Details** in sharing-failure feedback to open a diagnostic report. The copy icon copies the report; if clipboard access isn't available, select the report to copy it manually. The report excludes file names, paths, shared text, file contents, and credentials. Sambee doesn't upload it automatically. Closing Details keeps the failure feedback and its recovery actions available.\n\nCancelling the native share sheet doesn't show an error. Completion of the browser's share request doesn't confirm what a receiving app received.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Mobile Navigation\"\n+++\n\nSambee is designed and optimized for phones and tablets as well as for desktops. Because each platform has different strengths, the mobile experience differs from the desktop experience in some cases.\n\n## Where Mobile Excels\n\nMobile is a good fit when you want to:\n\n- Explore network shares made available through Sambee.\n- View images, read PDFs, and edit Markdown files.\n- Share content from file servers on mobile platforms.\n\n## What Changes on Mobile\n\nCompared with desktop, mobile navigation is more compact:\n\n- The interface focuses on single-pane navigation.\n- Toolbar space is tighter.\n- Some desktop-oriented browser controls are simplified or moved behind menus.\n- Opening files in natively installed apps is not available.\n- Local drive access is not available.\n", "0.8": "+++\ntitle = \"Mobile Navigation\"\n+++\n\nSambee is designed and optimized for phones and tablets as well as for desktops. Because each platform has different strengths, the mobile experience differs from the desktop experience in some cases.\n\n## Where Mobile Excels\n\nMobile is a good fit when you want to:\n\n- Explore network shares made available through Sambee.\n- View images, read PDFs, and edit Markdown files.\n- Share content from file servers on mobile platforms.\n\n## What Changes on Mobile\n\nCompared with desktop, mobile navigation is more compact:\n\n- The interface focuses on single-pane navigation.\n- Toolbar space is tighter.\n- Some desktop-oriented browser controls are simplified or moved behind menus.\n- Opening files in natively installed apps is not available.\n- Local drive access is not available.\n", "0.9": "+++\ntitle = \"Mobile Navigation\"\n+++\n\nSambee is designed and optimized for phones and tablets as well as for desktops. Because each platform has different strengths, the mobile experience differs from the desktop experience in some cases.\n\n## Where Mobile Excels\n\nMobile is a good fit when you want to:\n\n- Explore network shares made available through Sambee.\n- View images, read PDFs, and edit Markdown files.\n- Share content from file servers on mobile platforms.\n\n## What Changes on Mobile\n\nCompared with desktop, mobile navigation is more compact:\n\n- The interface focuses on single-pane navigation.\n- Toolbar space is tighter.\n- Some desktop-oriented browser controls are simplified or moved behind menus.\n- Opening files in natively installed apps is not available.\n- Local drive access is not available.\n", "1.0": "+++\ntitle = \"Mobile Navigation\"\n+++\n\nSambee is designed and optimized for phones and tablets as well as for desktops. Because each platform has different strengths, the mobile experience differs from the desktop experience in some cases.\n\n## Where Mobile Excels\n\nMobile is a good fit when you want to:\n\n- Explore network shares made available through Sambee.\n- View images, read PDFs, and edit Markdown files.\n- Share content from file servers on mobile platforms.\n\n## What Changes on Mobile\n\nCompared with desktop, mobile navigation is more compact:\n\n- The interface focuses on single-pane navigation.\n- Toolbar space is tighter.\n- Some desktop-oriented browser controls are simplified or moved behind menus.\n- Opening files in natively installed apps is not available.\n- Local drive access is not available.\n", "2.0": "+++\ntitle = \"Mobile Navigation\"\n+++\n\nSambee is designed and optimized for phones and tablets as well as for desktops. Because each platform has different strengths, the mobile experience differs from the desktop experience in some cases.\n\n## Where Mobile Excels\n\nMobile is a good fit when you want to:\n\n- Explore network shares made available through Sambee.\n- View images, read PDFs, and edit Markdown files.\n- Share content from file servers on mobile platforms.\n\n## What Changes on Mobile\n\nCompared with desktop, mobile navigation is more compact:\n\n- The interface focuses on single-pane navigation.\n- Toolbar space is tighter.\n- Some desktop-oriented browser controls are simplified or moved behind menus.\n- Opening files in natively installed apps is not available.\n- Local drive access is not available.\n\n## Back, Forward, and Bookmarks\n\nOpening or closing a file, entering or leaving its editor, moving between gallery images, and navigating or closing settings update the browser address and add history entries. You can bookmark or share that address on desktop or mobile. The recipient still needs access to the connection and file; local-drive links also need a paired companion with that drive available.\n\nUse browser Back to retrace your navigation steps. If you open an image and close it, Back reopens that image; another Back returns to the file list from before you opened it. Forward follows those same locations in the other direction. Reopening an editor checks access and obtains a new edit lock. History doesn't undo saved file changes or restore discarded edits. Starting a new navigation after Back replaces the old Forward branch.\n\nIf you have unsaved edits, Back or another navigation asks you to **Save**, **Discard**, or **Cancel**. Cancel keeps your draft and current location. A failed save keeps you in the editor. Your browser can also warn before reloading or closing a tab with unsaved edits.\n\nSettings **Close** reveals the underlying workspace and adds a history entry, so browser Back reopens the last settings category. Closing a directly opened viewer or settings bookmark also adds an entry without sending you to an unrelated page. The mobile settings back arrow follows your history; without an earlier location observed in this workspace, it uses an in-app parent. Resizing between phone and desktop layouts keeps the selected settings category.\n\nRefreshing a bookmark restores its requested location, not a different workspace saved earlier in the tab. A missing file or unavailable connection offers recovery actions rather than silently opening another file.\n\n## Share Files and Text\n\nOn a phone, use **Share** in a file's action menu, or select several files and choose **Share** from the selection menu. Sambee prepares the stored files first. When they're ready, tap **Share** to open your device's share sheet. Multiple files are submitted together; Sambee doesn't silently drop files or retry a smaller selection.\n\nImage and PDF viewers have a sharing icon in the top bar. They share the resource you're viewing, including a compatible converted image or normalized PDF when needed. An image's extension matches the shared format. PDF sharing includes the whole displayed document, not just the visible page. Sharing from the file list instead uses the stored files without viewer conversions.\n\nIn text and Markdown viewers and editors, the same sharing icon opens two choices:\n\n- **Share as file** shares the saved file without saving your edits first.\n- **Share as text** shares the loaded text or your current editor contents, including unsaved changes. Markdown is shared as source text, not rendered HTML.\n\nThe file choice shows a preparation indicator while its attachment loads. You can still share text independently of that preparation.\n\nSharing availability and accepted attachment types depend on your browser and device. A browser can reject an attachment even after its capability check succeeds. Sambee won't silently replace a rejected attachment with text; choose **Share as text** explicitly where available.\n\n### If Sharing Fails\n\nWhen a prepared attachment can't be shared, use **Download** and try sharing it from your device's Files app. For failed image/PDF viewer sharing, this recovery download uses the same displayed resource. Ordinary download controls keep their existing behavior. For several files, download each prepared file in turn. If attachment preparation fails, text and Markdown viewers offer **Retry** without automatically opening the share sheet.\n\nChoose **Details** in sharing-failure feedback to open a diagnostic report. The copy icon copies the report; if clipboard access isn't available, select the report to copy it manually. The report excludes file names, paths, shared text, file contents, and credentials. Sambee doesn't upload it automatically. Closing Details keeps the failure feedback and its recovery actions available.\n\nCancelling the native share sheet doesn't show an error. Completion of the browser's share request doesn't confirm what a receiving app received.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:user-guide/viewing-and-editing-files", "parent_id": "book:user-guide", "depth": 1, "kind": "section", "label": "viewing-and-editing-files", "title": "Viewing \u0026 Editing Files", "path": "user-guide/viewing-and-editing-files", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:user-guide/viewing-and-editing-files/view-images-and-read-documents", "parent_id": "section:user-guide/viewing-and-editing-files", "depth": 2, "kind": "page", "label": "view-images-and-read-documents", "title": "View Images And Read Documents", "path": "user-guide/viewing-and-editing-files/view-images-and-read-documents", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"View Images \u0026 Read Documents\"\n+++\n\nSambee can display many types of files directly in the browser.\n\n## Images\n\nThe image viewer is optimized for speed and efficiency, making it possible to browse even large collections of high-resolution images smoothly.\n\nWhen possible, Sambee passes images through unchanged from storage to the browser. This happens when the file size is not too large and the image format is natively supported by browsers. In all other cases, images are converted on the fly on the server. This typically takes only a few hundred milliseconds and enables Sambee to support a [wide range of image formats](../../reference/supported-file-formats/).\n\nSambee's image viewer comes with controls such as:\n\n- Zoom\n- Pan\n- Rotate\n- Full-screen\n- Previous/next\n- Download\n\nWhile the image viewer optimizes images for display in the browser, downloaded images are always the unaltered original.\n\n## PDFs\n\nPDF files are preprocessed on the server to maximize compatibility and potentially reduce file size.\n\nSambee's PDF viewer comes with controls such as:\n\n- Search\n- Zoom\n- Pan\n- Rotate\n- Full-screen\n- Previous/next\n- Download\n\nPDF search works in any PDF document that has a text layer.\n\nWhile the PDF viewer optimizes documents for display in the browser, downloaded files are always the unaltered original.\n\n## Markdown\n\nMarkdown files are shown fully rendered for easier reading rather than as raw source code.\n\nSambee's Markdown viewer comes with controls such as:\n\n- Search\n- Full-screen\n- Previous/next\n- Download\n\nMarkdown editing is covered separately in [Edit Markdown](../edit-markdown/).\n\n## Full List of Supported File Types\n\nSee [Supported File Formats](../../reference/supported-file-formats/) for a complete list of supported file types.\n", "0.8": "+++\ntitle = \"View Images \u0026 Read Documents\"\n+++\n\nSambee can display many types of files directly in the browser.\n\n## Images\n\nThe image viewer is optimized for speed and efficiency, making it possible to browse even large collections of high-resolution images smoothly.\n\nWhen possible, Sambee passes images through unchanged from storage to the browser. This happens when the file size is not too large and the image format is natively supported by browsers. In all other cases, images are converted on the fly on the server. This typically takes only a few hundred milliseconds and enables Sambee to support a [wide range of image formats](../../reference/supported-file-formats/).\n\nSambee's image viewer comes with controls such as:\n\n- Zoom\n- Pan\n- Rotate\n- Full-screen\n- Previous/next\n- Download\n\nWhile the image viewer optimizes images for display in the browser, downloaded images are always the unaltered original.\n\n## PDFs\n\nPDF files are preprocessed on the server to maximize compatibility and potentially reduce file size.\n\nSambee's PDF viewer comes with controls such as:\n\n- Search\n- Zoom\n- Pan\n- Rotate\n- Full-screen\n- Previous/next\n- Download\n\nPDF search works in any PDF document that has a text layer.\n\nWhile the PDF viewer optimizes documents for display in the browser, downloaded files are always the unaltered original.\n\n## Markdown\n\nMarkdown files are shown fully rendered for easier reading rather than as raw source code.\n\nSambee's Markdown viewer comes with controls such as:\n\n- Search\n- Full-screen\n- Previous/next\n- Download\n\nMarkdown editing is covered separately in [Edit Markdown](../edit-markdown/).\n\n## Full List of Supported File Types\n\nSee [Supported File Formats](../../reference/supported-file-formats/) for a complete list of supported file types.\n", "0.9": "+++\ntitle = \"View Images \u0026 Read Documents\"\n+++\n\nSambee can display many types of files directly in the browser.\n\n## Images\n\nThe image viewer is optimized for speed and efficiency, making it possible to browse even large collections of high-resolution images smoothly.\n\nWhen possible, Sambee passes images through unchanged from storage to the browser. This happens when the file size is not too large and the image format is natively supported by browsers. In all other cases, images are converted on the fly on the server. This typically takes only a few hundred milliseconds and enables Sambee to support a [wide range of image formats](../../reference/supported-file-formats/).\n\nSambee's image viewer comes with controls such as:\n\n- Zoom\n- Pan\n- Rotate\n- Full-screen\n- Previous/next\n- Download\n\nWhile the image viewer optimizes images for display in the browser, downloaded images are always the unaltered original.\n\n## PDFs\n\nPDF files are preprocessed on the server to maximize compatibility and potentially reduce file size.\n\nSambee's PDF viewer comes with controls such as:\n\n- Search\n- Zoom\n- Pan\n- Rotate\n- Full-screen\n- Previous/next\n- Download\n\nPDF search works in any PDF document that has a text layer.\n\nWhile the PDF viewer optimizes documents for display in the browser, downloaded files are always the unaltered original.\n\n## Markdown\n\nMarkdown files are shown fully rendered for easier reading rather than as raw source code.\n\nSambee's Markdown viewer comes with controls such as:\n\n- Search\n- Full-screen\n- Previous/next\n- Download\n\nMarkdown editing is covered separately in [Edit Markdown](../edit-markdown/).\n\n## Full List of Supported File Types\n\nSee [Supported File Formats](../../reference/supported-file-formats/) for a complete list of supported file types.\n", "1.0": "+++\ntitle = \"View Images \u0026 Read Documents\"\n+++\n\nSambee can display many types of files directly in the browser.\n\n## Images\n\nThe image viewer is optimized for speed and efficiency, making it possible to browse even large collections of high-resolution images smoothly.\n\nWhen possible, Sambee passes images through unchanged from storage to the browser. This happens when the file size is not too large and the image format is natively supported by browsers. In all other cases, images are converted on the fly on the server. This typically takes only a few hundred milliseconds and enables Sambee to support a [wide range of image formats](../../reference/supported-file-formats/).\n\nSambee's image viewer comes with controls such as:\n\n- Zoom\n- Pan\n- Rotate\n- Full-screen\n- Previous/next\n- Download\n\nWhile the image viewer optimizes images for display in the browser, downloaded images are always the unaltered original.\n\n## PDFs\n\nPDF files are preprocessed on the server to maximize compatibility and potentially reduce file size.\n\nSambee's PDF viewer comes with controls such as:\n\n- Search\n- Zoom\n- Pan\n- Rotate\n- Full-screen\n- Previous/next\n- Download\n\nPDF search works in any PDF document that has a text layer.\n\nWhile the PDF viewer optimizes documents for display in the browser, downloaded files are always the unaltered original.\n\n## Markdown\n\nMarkdown files are shown fully rendered for easier reading rather than as raw source code.\n\nSambee's Markdown viewer comes with controls such as:\n\n- Search\n- Full-screen\n- Previous/next\n- Download\n\nMarkdown editing is covered separately in [Edit Markdown](../edit-markdown/).\n\n## Full List of Supported File Types\n\nSee [Supported File Formats](../../reference/supported-file-formats/) for a complete list of supported file types.\n", "2.0": "+++\ntitle = \"View Images \u0026 Read Documents\"\n+++\n\nSambee can display many types of files directly in the browser.\n\n## Images\n\nThe image viewer is optimized for speed and efficiency, making it possible to browse even large collections of high-resolution images smoothly.\n\nWhen possible, Sambee passes images through unchanged from storage to the browser. This happens when the file size is not too large and the image format is natively supported by browsers. In all other cases, images are converted on the fly on the server. This typically takes only a few hundred milliseconds and enables Sambee to support a [wide range of image formats](../../reference/supported-file-formats/).\n\nSambee's image viewer comes with controls such as:\n\n- Zoom\n- Pan\n- Rotate\n- Full-screen\n- Previous/next\n- Download\n\nWhile the image viewer optimizes images for display in the browser, downloaded images are always the unaltered original.\n\n## PDFs\n\nPDF files are preprocessed on the server to maximize compatibility and potentially reduce file size.\n\nSambee's PDF viewer comes with controls such as:\n\n- Search\n- Zoom\n- Pan\n- Rotate\n- Full-screen\n- Previous/next\n- Download\n\nPDF search works in any PDF document that has a text layer.\n\nWhile the PDF viewer optimizes documents for display in the browser, downloaded files are always the unaltered original.\n\n## Markdown\n\nMarkdown files are shown fully rendered for easier reading rather than as raw source code.\n\nSambee's Markdown viewer comes with controls such as:\n\n- Search\n- Full-screen\n- Previous/next\n- Download\n\nMarkdown editing is covered separately in [Edit Markdown](../edit-markdown/).\n\n## Full List of Supported File Types\n\nSee [Supported File Formats](../../reference/supported-file-formats/) for a complete list of supported file types.\n"}, "page_contents": {"0.7": "+++\ntitle = \"View Images \u0026 Read Documents\"\n+++\n\nSambee can display many types of files directly in the browser.\n\n## Images\n\nThe image viewer is optimized for speed and efficiency, making it possible to browse even large collections of high-resolution images smoothly.\n\nWhen possible, Sambee passes images through unchanged from storage to the browser. This happens when the file size is not too large and the image format is natively supported by browsers. In all other cases, images are converted on the fly on the server. This typically takes only a few hundred milliseconds and enables Sambee to support a [wide range of image formats](../../reference/supported-file-formats/).\n\nSambee's image viewer comes with controls such as:\n\n- Zoom\n- Pan\n- Rotate\n- Full-screen\n- Previous/next\n- Download\n\nWhile the image viewer optimizes images for display in the browser, downloaded images are always the unaltered original.\n\n## PDFs\n\nPDF files are preprocessed on the server to maximize compatibility and potentially reduce file size.\n\nSambee's PDF viewer comes with controls such as:\n\n- Search\n- Zoom\n- Pan\n- Rotate\n- Full-screen\n- Previous/next\n- Download\n\nPDF search works in any PDF document that has a text layer.\n\nWhile the PDF viewer optimizes documents for display in the browser, downloaded files are always the unaltered original.\n\n## Markdown\n\nMarkdown files are shown fully rendered for easier reading rather than as raw source code.\n\nSambee's Markdown viewer comes with controls such as:\n\n- Search\n- Full-screen\n- Previous/next\n- Download\n\nMarkdown editing is covered separately in [Edit Markdown](../edit-markdown/).\n\n## Full List of Supported File Types\n\nSee [Supported File Formats](../../reference/supported-file-formats/) for a complete list of supported file types.\n", "0.8": "+++\ntitle = \"View Images \u0026 Read Documents\"\n+++\n\nSambee can display many types of files directly in the browser.\n\n## Images\n\nThe image viewer is optimized for speed and efficiency, making it possible to browse even large collections of high-resolution images smoothly.\n\nWhen possible, Sambee passes images through unchanged from storage to the browser. This happens when the file size is not too large and the image format is natively supported by browsers. In all other cases, images are converted on the fly on the server. This typically takes only a few hundred milliseconds and enables Sambee to support a [wide range of image formats](../../reference/supported-file-formats/).\n\nSambee's image viewer comes with controls such as:\n\n- Zoom\n- Pan\n- Rotate\n- Full-screen\n- Previous/next\n- Download\n\nWhile the image viewer optimizes images for display in the browser, downloaded images are always the unaltered original.\n\n## PDFs\n\nPDF files are preprocessed on the server to maximize compatibility and potentially reduce file size.\n\nSambee's PDF viewer comes with controls such as:\n\n- Search\n- Zoom\n- Pan\n- Rotate\n- Full-screen\n- Previous/next\n- Download\n\nPDF search works in any PDF document that has a text layer.\n\nWhile the PDF viewer optimizes documents for display in the browser, downloaded files are always the unaltered original.\n\n## Markdown\n\nMarkdown files are shown fully rendered for easier reading rather than as raw source code.\n\nSambee's Markdown viewer comes with controls such as:\n\n- Search\n- Full-screen\n- Previous/next\n- Download\n\nMarkdown editing is covered separately in [Edit Markdown](../edit-markdown/).\n\n## Full List of Supported File Types\n\nSee [Supported File Formats](../../reference/supported-file-formats/) for a complete list of supported file types.\n", "0.9": "+++\ntitle = \"View Images \u0026 Read Documents\"\n+++\n\nSambee can display many types of files directly in the browser.\n\n## Images\n\nThe image viewer is optimized for speed and efficiency, making it possible to browse even large collections of high-resolution images smoothly.\n\nWhen possible, Sambee passes images through unchanged from storage to the browser. This happens when the file size is not too large and the image format is natively supported by browsers. In all other cases, images are converted on the fly on the server. This typically takes only a few hundred milliseconds and enables Sambee to support a [wide range of image formats](../../reference/supported-file-formats/).\n\nSambee's image viewer comes with controls such as:\n\n- Zoom\n- Pan\n- Rotate\n- Full-screen\n- Previous/next\n- Download\n\nWhile the image viewer optimizes images for display in the browser, downloaded images are always the unaltered original.\n\n## PDFs\n\nPDF files are preprocessed on the server to maximize compatibility and potentially reduce file size.\n\nSambee's PDF viewer comes with controls such as:\n\n- Search\n- Zoom\n- Pan\n- Rotate\n- Full-screen\n- Previous/next\n- Download\n\nPDF search works in any PDF document that has a text layer.\n\nWhile the PDF viewer optimizes documents for display in the browser, downloaded files are always the unaltered original.\n\n## Markdown\n\nMarkdown files are shown fully rendered for easier reading rather than as raw source code.\n\nSambee's Markdown viewer comes with controls such as:\n\n- Search\n- Full-screen\n- Previous/next\n- Download\n\nMarkdown editing is covered separately in [Edit Markdown](../edit-markdown/).\n\n## Full List of Supported File Types\n\nSee [Supported File Formats](../../reference/supported-file-formats/) for a complete list of supported file types.\n", "1.0": "+++\ntitle = \"View Images \u0026 Read Documents\"\n+++\n\nSambee can display many types of files directly in the browser.\n\n## Images\n\nThe image viewer is optimized for speed and efficiency, making it possible to browse even large collections of high-resolution images smoothly.\n\nWhen possible, Sambee passes images through unchanged from storage to the browser. This happens when the file size is not too large and the image format is natively supported by browsers. In all other cases, images are converted on the fly on the server. This typically takes only a few hundred milliseconds and enables Sambee to support a [wide range of image formats](../../reference/supported-file-formats/).\n\nSambee's image viewer comes with controls such as:\n\n- Zoom\n- Pan\n- Rotate\n- Full-screen\n- Previous/next\n- Download\n\nWhile the image viewer optimizes images for display in the browser, downloaded images are always the unaltered original.\n\n## PDFs\n\nPDF files are preprocessed on the server to maximize compatibility and potentially reduce file size.\n\nSambee's PDF viewer comes with controls such as:\n\n- Search\n- Zoom\n- Pan\n- Rotate\n- Full-screen\n- Previous/next\n- Download\n\nPDF search works in any PDF document that has a text layer.\n\nWhile the PDF viewer optimizes documents for display in the browser, downloaded files are always the unaltered original.\n\n## Markdown\n\nMarkdown files are shown fully rendered for easier reading rather than as raw source code.\n\nSambee's Markdown viewer comes with controls such as:\n\n- Search\n- Full-screen\n- Previous/next\n- Download\n\nMarkdown editing is covered separately in [Edit Markdown](../edit-markdown/).\n\n## Full List of Supported File Types\n\nSee [Supported File Formats](../../reference/supported-file-formats/) for a complete list of supported file types.\n", "2.0": "+++\ntitle = \"View Images \u0026 Read Documents\"\n+++\n\nSambee can display many types of files directly in the browser.\n\n## Images\n\nThe image viewer is optimized for speed and efficiency, making it possible to browse even large collections of high-resolution images smoothly.\n\nWhen possible, Sambee passes images through unchanged from storage to the browser. This happens when the file size is not too large and the image format is natively supported by browsers. In all other cases, images are converted on the fly on the server. This typically takes only a few hundred milliseconds and enables Sambee to support a [wide range of image formats](../../reference/supported-file-formats/).\n\nSambee's image viewer comes with controls such as:\n\n- Zoom\n- Pan\n- Rotate\n- Full-screen\n- Previous/next\n- Download\n\nWhile the image viewer optimizes images for display in the browser, downloaded images are always the unaltered original.\n\n## PDFs\n\nPDF files are preprocessed on the server to maximize compatibility and potentially reduce file size.\n\nSambee's PDF viewer comes with controls such as:\n\n- Search\n- Zoom\n- Pan\n- Rotate\n- Full-screen\n- Previous/next\n- Download\n\nPDF search works in any PDF document that has a text layer.\n\nWhile the PDF viewer optimizes documents for display in the browser, downloaded files are always the unaltered original.\n\n## Markdown\n\nMarkdown files are shown fully rendered for easier reading rather than as raw source code.\n\nSambee's Markdown viewer comes with controls such as:\n\n- Search\n- Full-screen\n- Previous/next\n- Download\n\nMarkdown editing is covered separately in [Edit Markdown](../edit-markdown/).\n\n## Full List of Supported File Types\n\nSee [Supported File Formats](../../reference/supported-file-formats/) for a complete list of supported file types.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:user-guide/viewing-and-editing-files/edit-markdown", "parent_id": "section:user-guide/viewing-and-editing-files", "depth": 2, "kind": "page", "label": "edit-markdown", "title": "Edit Markdown", "path": "user-guide/viewing-and-editing-files/edit-markdown", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "branched", "source_version": "0.7", "diff_added": 2, "diff_removed": 0}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "branched", "source_version": "0.9", "diff_added": 3, "diff_removed": 1}}, "content_versions": {"0.7": "+++\ntitle = \"Edit Markdown\"\n+++\n\nMarkdown files are opened in Sambee's [Markdown viewer](../view-images-and-read-documents/). From there, you can seamlessly switch to a full-fledged Markdown editor.\n\n## Entering Edit Mode\n\nIn the Markdown viewer's toolbar, click the edit icon or press \u003ckbd\u003eE\u003c/kbd\u003e to switch to the Markdown editor. It opens in rich-text mode, but you can switch to source mode if you prefer to edit raw Markdown.\n\n## Saving Changes\n\nA small indicator next to the file name shows whether the document has unsaved changes. Click the save icon or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e at any time to save the current state of the document.\n\n## Leaving Edit Mode\n\nClick the X icon or press \u003ckbd\u003eEsc\u003c/kbd\u003e to leave the Markdown editor. If there are unsaved changes, you are asked whether to save them.\n", "0.8": "+++\ntitle = \"Edit Markdown\"\n+++\n\nMarkdown files are opened in Sambee's [Markdown viewer](../view-images-and-read-documents/). From there, you can seamlessly switch to a full-fledged Markdown editor.\n\n## Entering Edit Mode\n\nIn the Markdown viewer's toolbar, click the edit icon or press \u003ckbd\u003eE\u003c/kbd\u003e to switch to the Markdown editor. It opens in rich-text mode, but you can switch to source mode if you prefer to edit raw Markdown.\n\n## Saving Changes\n\nA small indicator next to the file name shows whether the document has unsaved changes. Click the save icon or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e at any time to save the current state of the document.\n\n## Leaving Edit Mode\n\nClick the X icon or press \u003ckbd\u003eEsc\u003c/kbd\u003e to leave the Markdown editor. If there are unsaved changes, you are asked whether to save them.\n", "0.9": "+++\ntitle = \"Edit Markdown\"\n+++\n\nMarkdown files are opened in Sambee's [Markdown viewer](../view-images-and-read-documents/). From there, you can seamlessly switch to a full-fledged Markdown editor.\n\n## Entering Edit Mode\n\nIn the Markdown viewer's toolbar, click the edit icon or press \u003ckbd\u003eE\u003c/kbd\u003e to switch to the Markdown editor. It opens in rich-text mode, but you can switch to source mode if you prefer to edit raw Markdown.\n\n## Saving Changes\n\nA small indicator next to the file name shows whether the document has unsaved changes. Click the save icon or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e at any time to save the current state of the document.\n\nIf Sambee must send you through OIDC sign-in while you are editing, it saves an eligible unsaved Markdown draft in this browser tab before leaving the page. See [Recover Unsaved In-Browser Edits](../recover-unsaved-edits/) for how recovery works.\n\n## Leaving Edit Mode\n\nClick the X icon or press \u003ckbd\u003eEsc\u003c/kbd\u003e to leave the Markdown editor. If there are unsaved changes, you are asked whether to save them.\n", "1.0": "+++\ntitle = \"Edit Markdown\"\n+++\n\nMarkdown files are opened in Sambee's [Markdown viewer](../view-images-and-read-documents/). From there, you can seamlessly switch to a full-fledged Markdown editor.\n\n## Entering Edit Mode\n\nIn the Markdown viewer's toolbar, click the edit icon or press \u003ckbd\u003eE\u003c/kbd\u003e to switch to the Markdown editor. It opens in rich-text mode, but you can switch to source mode if you prefer to edit raw Markdown.\n\n## Saving Changes\n\nA small indicator next to the file name shows whether the document has unsaved changes. Click the save icon or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e at any time to save the current state of the document.\n\nIf Sambee must send you through OIDC sign-in while you are editing, it saves an eligible unsaved Markdown draft in this browser tab before leaving the page. See [Recover Unsaved In-Browser Edits](../recover-unsaved-edits/) for how recovery works.\n\n## Leaving Edit Mode\n\nClick the X icon or press \u003ckbd\u003eEsc\u003c/kbd\u003e to leave the Markdown editor. If there are unsaved changes, you are asked whether to save them.\n", "2.0": "+++\ntitle = \"Edit Markdown\"\n+++\n\nMarkdown files are opened in Sambee's [Markdown viewer](../view-images-and-read-documents/). From there, you can seamlessly switch to a full-fledged Markdown editor.\n\n## Entering Edit Mode\n\nIn the Markdown viewer's toolbar, click the edit icon or press \u003ckbd\u003eE\u003c/kbd\u003e to switch to the Markdown editor. It opens in rich-text mode, but you can switch to source mode if you prefer to edit raw Markdown.\n\n## Saving Changes\n\nA small indicator next to the file name shows whether the document has unsaved changes. Click the save icon or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e at any time to save the current state of the document.\n\nIf Sambee must send you through OIDC sign-in while you are editing, it saves an eligible unsaved Markdown draft in this browser tab before leaving the page. See [Recover Unsaved In-Browser Edits](../recover-unsaved-edits/) for how recovery works.\n\n## Leaving Edit Mode\n\nClick the X icon or press \u003ckbd\u003eEsc\u003c/kbd\u003e to leave the Markdown editor and return to the viewer. If there are unsaved changes, choose **Save** to save them and return to the viewer, **Discard** to return without saving, or **Cancel** to keep editing. If saving fails, the editor stays open with your changes.\n\nFrom the viewer, click the X icon again to return to the file list. The text editor uses the same two-step close sequence.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Edit Markdown\"\n+++\n\nMarkdown files are opened in Sambee's [Markdown viewer](../view-images-and-read-documents/). From there, you can seamlessly switch to a full-fledged Markdown editor.\n\n## Entering Edit Mode\n\nIn the Markdown viewer's toolbar, click the edit icon or press \u003ckbd\u003eE\u003c/kbd\u003e to switch to the Markdown editor. It opens in rich-text mode, but you can switch to source mode if you prefer to edit raw Markdown.\n\n## Saving Changes\n\nA small indicator next to the file name shows whether the document has unsaved changes. Click the save icon or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e at any time to save the current state of the document.\n\n## Leaving Edit Mode\n\nClick the X icon or press \u003ckbd\u003eEsc\u003c/kbd\u003e to leave the Markdown editor. If there are unsaved changes, you are asked whether to save them.\n", "0.8": "+++\ntitle = \"Edit Markdown\"\n+++\n\nMarkdown files are opened in Sambee's [Markdown viewer](../view-images-and-read-documents/). From there, you can seamlessly switch to a full-fledged Markdown editor.\n\n## Entering Edit Mode\n\nIn the Markdown viewer's toolbar, click the edit icon or press \u003ckbd\u003eE\u003c/kbd\u003e to switch to the Markdown editor. It opens in rich-text mode, but you can switch to source mode if you prefer to edit raw Markdown.\n\n## Saving Changes\n\nA small indicator next to the file name shows whether the document has unsaved changes. Click the save icon or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e at any time to save the current state of the document.\n\n## Leaving Edit Mode\n\nClick the X icon or press \u003ckbd\u003eEsc\u003c/kbd\u003e to leave the Markdown editor. If there are unsaved changes, you are asked whether to save them.\n", "0.9": "+++\ntitle = \"Edit Markdown\"\n+++\n\nMarkdown files are opened in Sambee's [Markdown viewer](../view-images-and-read-documents/). From there, you can seamlessly switch to a full-fledged Markdown editor.\n\n## Entering Edit Mode\n\nIn the Markdown viewer's toolbar, click the edit icon or press \u003ckbd\u003eE\u003c/kbd\u003e to switch to the Markdown editor. It opens in rich-text mode, but you can switch to source mode if you prefer to edit raw Markdown.\n\n## Saving Changes\n\nA small indicator next to the file name shows whether the document has unsaved changes. Click the save icon or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e at any time to save the current state of the document.\n\nIf Sambee must send you through OIDC sign-in while you are editing, it saves an eligible unsaved Markdown draft in this browser tab before leaving the page. See [Recover Unsaved In-Browser Edits](../recover-unsaved-edits/) for how recovery works.\n\n## Leaving Edit Mode\n\nClick the X icon or press \u003ckbd\u003eEsc\u003c/kbd\u003e to leave the Markdown editor. If there are unsaved changes, you are asked whether to save them.\n", "1.0": "+++\ntitle = \"Edit Markdown\"\n+++\n\nMarkdown files are opened in Sambee's [Markdown viewer](../view-images-and-read-documents/). From there, you can seamlessly switch to a full-fledged Markdown editor.\n\n## Entering Edit Mode\n\nIn the Markdown viewer's toolbar, click the edit icon or press \u003ckbd\u003eE\u003c/kbd\u003e to switch to the Markdown editor. It opens in rich-text mode, but you can switch to source mode if you prefer to edit raw Markdown.\n\n## Saving Changes\n\nA small indicator next to the file name shows whether the document has unsaved changes. Click the save icon or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e at any time to save the current state of the document.\n\nIf Sambee must send you through OIDC sign-in while you are editing, it saves an eligible unsaved Markdown draft in this browser tab before leaving the page. See [Recover Unsaved In-Browser Edits](../recover-unsaved-edits/) for how recovery works.\n\n## Leaving Edit Mode\n\nClick the X icon or press \u003ckbd\u003eEsc\u003c/kbd\u003e to leave the Markdown editor. If there are unsaved changes, you are asked whether to save them.\n", "2.0": "+++\ntitle = \"Edit Markdown\"\n+++\n\nMarkdown files are opened in Sambee's [Markdown viewer](../view-images-and-read-documents/). From there, you can seamlessly switch to a full-fledged Markdown editor.\n\n## Entering Edit Mode\n\nIn the Markdown viewer's toolbar, click the edit icon or press \u003ckbd\u003eE\u003c/kbd\u003e to switch to the Markdown editor. It opens in rich-text mode, but you can switch to source mode if you prefer to edit raw Markdown.\n\n## Saving Changes\n\nA small indicator next to the file name shows whether the document has unsaved changes. Click the save icon or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e at any time to save the current state of the document.\n\nIf Sambee must send you through OIDC sign-in while you are editing, it saves an eligible unsaved Markdown draft in this browser tab before leaving the page. See [Recover Unsaved In-Browser Edits](../recover-unsaved-edits/) for how recovery works.\n\n## Leaving Edit Mode\n\nClick the X icon or press \u003ckbd\u003eEsc\u003c/kbd\u003e to leave the Markdown editor and return to the viewer. If there are unsaved changes, choose **Save** to save them and return to the viewer, **Discard** to return without saving, or **Cancel** to keep editing. If saving fails, the editor stays open with your changes.\n\nFrom the viewer, click the X icon again to return to the file list. The text editor uses the same two-step close sequence.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:user-guide/viewing-and-editing-files/edit-files-in-desktop-apps", "parent_id": "section:user-guide/viewing-and-editing-files", "depth": 2, "kind": "page", "label": "edit-files-in-desktop-apps", "title": "Edit Files In Desktop Apps", "path": "user-guide/viewing-and-editing-files/edit-files-in-desktop-apps", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Edit Files in Desktop Apps\"\n+++\n\nSambee can open files in installed desktop apps through its Companion helper. If the file is on a local drive, the desktop app can access it directly. In that case, Companion opens the app with the original file path.\n\nIf the file is on one of Sambee's SMB connections, the desktop app cannot access it directly. In that case, Companion opens a temporary local copy in the desktop app and synchronizes your changes back to the original location.\n\nThe remainder of this page describes the second case.\n\n## Before You Begin\n\nYou need:\n\n- Sambee Companion installed and running on your computer.\n- A desktop app that can open the file type you want to edit.\n\nNeed Companion first? Start with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/).\n\n## Start the Editing Workflow\n\nIn Sambee, right-click the file and choose **Open in companion app**, or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nSambee hands the request to Companion through a `sambee://` link. When your browser asks whether to allow that link to open, choose **yes**.\n{{\u003c /admonition \u003e}}\n\n{{\u003c admonition type=\"note\" \u003e}}\nIf your Sambee site is behind a proxy server, Companion may show a separate **Sambee Authentication** window before opening the file. Sign in there and then continue the desktop-editing workflow.\n{{\u003c /admonition \u003e}}\n\n### What Happens Under the Hood\n\nCompanion handles the rest of the edit session:\n\n- It acquires an edit lock for the file on the file share.\n- It downloads the file and stores a temporary local copy.\n- If needed, it asks you which desktop app should open the file.\n- It opens the local copy in that app.\n- It shows a **Done Editing** window, which you use to upload the modified local copy when you are done.\n\n## Choose an App to Open the File\n\nThe first time you open a file type, Companion may show an app picker listing the installed apps available for that file type. Choose an app from the list for that extension and optionally remember that choice for later. For app-selection help, use [Desktop App Picker](../../companion-app/desktop-app-picker/).\n\n## Finish the Editing Session\n\nClosing the desktop app by itself does not upload the file and does not finish the session. Uploading is initiated in the **Done Editing** window.\n\n- Changed file: use **Done Editing \u2014 Hold to Upload**.\n- Unchanged file: use **Done Editing \u2014 Hold to Close**.\n- Do not want to keep the local changes: use **Discard Changes \u2014 Hold**.\n\nIf the **Done Editing** window tells you that the session expired, authentication failed, the lock was lost, or recovery is required, reopen the file from Sambee instead of retrying the old desktop-editing session indefinitely. That starts a fresh authenticated edit session with a new server-side lock.\n", "0.8": "+++\ntitle = \"Edit Files in Desktop Apps\"\n+++\n\nSambee can open files in installed desktop apps through its Companion helper. If the file is on a local drive, the desktop app can access it directly. In that case, Companion opens the app with the original file path.\n\nIf the file is on one of Sambee's SMB connections, the desktop app cannot access it directly. In that case, Companion opens a temporary local copy in the desktop app and synchronizes your changes back to the original location.\n\nThe remainder of this page describes the second case.\n\n## Before You Begin\n\nYou need:\n\n- Sambee Companion installed and running on your computer.\n- A desktop app that can open the file type you want to edit.\n\nNeed Companion first? Start with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/).\n\n## Start the Editing Workflow\n\nIn Sambee, right-click the file and choose **Open in companion app**, or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nSambee hands the request to Companion through a `sambee://` link. When your browser asks whether to allow that link to open, choose **yes**.\n{{\u003c /admonition \u003e}}\n\n{{\u003c admonition type=\"note\" \u003e}}\nIf your Sambee site is behind a proxy server, Companion may show a separate **Sambee Authentication** window before opening the file. Sign in there and then continue the desktop-editing workflow.\n{{\u003c /admonition \u003e}}\n\n### What Happens Under the Hood\n\nCompanion handles the rest of the edit session:\n\n- It acquires an edit lock for the file on the file share.\n- It downloads the file and stores a temporary local copy.\n- If needed, it asks you which desktop app should open the file.\n- It opens the local copy in that app.\n- It shows a **Done Editing** window, which you use to upload the modified local copy when you are done.\n\n## Choose an App to Open the File\n\nThe first time you open a file type, Companion may show an app picker listing the installed apps available for that file type. Choose an app from the list for that extension and optionally remember that choice for later. For app-selection help, use [Desktop App Picker](../../companion-app/desktop-app-picker/).\n\n## Finish the Editing Session\n\nClosing the desktop app by itself does not upload the file and does not finish the session. Uploading is initiated in the **Done Editing** window.\n\n- Changed file: use **Done Editing \u2014 Hold to Upload**.\n- Unchanged file: use **Done Editing \u2014 Hold to Close**.\n- Do not want to keep the local changes: use **Discard Changes \u2014 Hold**.\n\nIf the **Done Editing** window tells you that the session expired, authentication failed, the lock was lost, or recovery is required, reopen the file from Sambee instead of retrying the old desktop-editing session indefinitely. That starts a fresh authenticated edit session with a new server-side lock.\n", "0.9": "+++\ntitle = \"Edit Files in Desktop Apps\"\n+++\n\nSambee can open files in installed desktop apps through its Companion helper. If the file is on a local drive, the desktop app can access it directly. In that case, Companion opens the app with the original file path.\n\nIf the file is on one of Sambee's SMB connections, the desktop app cannot access it directly. In that case, Companion opens a temporary local copy in the desktop app and synchronizes your changes back to the original location.\n\nThe remainder of this page describes the second case.\n\n## Before You Begin\n\nYou need:\n\n- Sambee Companion installed and running on your computer.\n- A desktop app that can open the file type you want to edit.\n\nNeed Companion first? Start with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/).\n\n## Start the Editing Workflow\n\nIn Sambee, right-click the file and choose **Open in companion app**, or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nSambee hands the request to Companion through a `sambee://` link. When your browser asks whether to allow that link to open, choose **yes**.\n{{\u003c /admonition \u003e}}\n\n{{\u003c admonition type=\"note\" \u003e}}\nIf your Sambee site is behind a proxy server, Companion may show a separate **Sambee Authentication** window before opening the file. Sign in there and then continue the desktop-editing workflow.\n{{\u003c /admonition \u003e}}\n\n### What Happens Under the Hood\n\nCompanion handles the rest of the edit session:\n\n- It acquires an edit lock for the file on the file share.\n- It downloads the file and stores a temporary local copy.\n- If needed, it asks you which desktop app should open the file.\n- It opens the local copy in that app.\n- It shows a **Done Editing** window, which you use to upload the modified local copy when you are done.\n\n## Choose an App to Open the File\n\nThe first time you open a file type, Companion may show an app picker listing the installed apps available for that file type. Choose an app from the list for that extension and optionally remember that choice for later. For app-selection help, use [Desktop App Picker](../../companion-app/desktop-app-picker/).\n\n## Finish the Editing Session\n\nClosing the desktop app by itself does not upload the file and does not finish the session. Uploading is initiated in the **Done Editing** window.\n\n- Changed file: use **Done Editing \u2014 Hold to Upload**.\n- Unchanged file: use **Done Editing \u2014 Hold to Close**.\n- Do not want to keep the local changes: use **Discard Changes \u2014 Hold**.\n\nIf the **Done Editing** window tells you that the session expired, authentication failed, the lock was lost, or recovery is required, reopen the file from Sambee instead of retrying the old desktop-editing session indefinitely. That starts a fresh authenticated edit session with a new server-side lock.\n", "1.0": "+++\ntitle = \"Edit Files in Desktop Apps\"\n+++\n\nSambee can open files in installed desktop apps through its Companion helper. If the file is on a local drive, the desktop app can access it directly. In that case, Companion opens the app with the original file path.\n\nIf the file is on one of Sambee's SMB connections, the desktop app cannot access it directly. In that case, Companion opens a temporary local copy in the desktop app and synchronizes your changes back to the original location.\n\nThe remainder of this page describes the second case.\n\n## Before You Begin\n\nYou need:\n\n- Sambee Companion installed and running on your computer.\n- A desktop app that can open the file type you want to edit.\n\nNeed Companion first? Start with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/).\n\n## Start the Editing Workflow\n\nIn Sambee, right-click the file and choose **Open in companion app**, or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nSambee hands the request to Companion through a `sambee://` link. When your browser asks whether to allow that link to open, choose **yes**.\n{{\u003c /admonition \u003e}}\n\n{{\u003c admonition type=\"note\" \u003e}}\nIf your Sambee site is behind a proxy server, Companion may show a separate **Sambee Authentication** window before opening the file. Sign in there and then continue the desktop-editing workflow.\n{{\u003c /admonition \u003e}}\n\n### What Happens Under the Hood\n\nCompanion handles the rest of the edit session:\n\n- It acquires an edit lock for the file on the file share.\n- It downloads the file and stores a temporary local copy.\n- If needed, it asks you which desktop app should open the file.\n- It opens the local copy in that app.\n- It shows a **Done Editing** window, which you use to upload the modified local copy when you are done.\n\n## Choose an App to Open the File\n\nThe first time you open a file type, Companion may show an app picker listing the installed apps available for that file type. Choose an app from the list for that extension and optionally remember that choice for later. For app-selection help, use [Desktop App Picker](../../companion-app/desktop-app-picker/).\n\n## Finish the Editing Session\n\nClosing the desktop app by itself does not upload the file and does not finish the session. Uploading is initiated in the **Done Editing** window.\n\n- Changed file: use **Done Editing \u2014 Hold to Upload**.\n- Unchanged file: use **Done Editing \u2014 Hold to Close**.\n- Do not want to keep the local changes: use **Discard Changes \u2014 Hold**.\n\nIf the **Done Editing** window tells you that the session expired, authentication failed, the lock was lost, or recovery is required, reopen the file from Sambee instead of retrying the old desktop-editing session indefinitely. That starts a fresh authenticated edit session with a new server-side lock.\n", "2.0": "+++\ntitle = \"Edit Files in Desktop Apps\"\n+++\n\nSambee can open files in installed desktop apps through its Companion helper. If the file is on a local drive, the desktop app can access it directly. In that case, Companion opens the app with the original file path.\n\nIf the file is on one of Sambee's SMB connections, the desktop app cannot access it directly. In that case, Companion opens a temporary local copy in the desktop app and synchronizes your changes back to the original location.\n\nThe remainder of this page describes the second case.\n\n## Before You Begin\n\nYou need:\n\n- Sambee Companion installed and running on your computer.\n- A desktop app that can open the file type you want to edit.\n\nNeed Companion first? Start with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/).\n\n## Start the Editing Workflow\n\nIn Sambee, right-click the file and choose **Open in companion app**, or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nSambee hands the request to Companion through a `sambee://` link. When your browser asks whether to allow that link to open, choose **yes**.\n{{\u003c /admonition \u003e}}\n\n{{\u003c admonition type=\"note\" \u003e}}\nIf your Sambee site is behind a proxy server, Companion may show a separate **Sambee Authentication** window before opening the file. Sign in there and then continue the desktop-editing workflow.\n{{\u003c /admonition \u003e}}\n\n### What Happens Under the Hood\n\nCompanion handles the rest of the edit session:\n\n- It acquires an edit lock for the file on the file share.\n- It downloads the file and stores a temporary local copy.\n- If needed, it asks you which desktop app should open the file.\n- It opens the local copy in that app.\n- It shows a **Done Editing** window, which you use to upload the modified local copy when you are done.\n\n## Choose an App to Open the File\n\nThe first time you open a file type, Companion may show an app picker listing the installed apps available for that file type. Choose an app from the list for that extension and optionally remember that choice for later. For app-selection help, use [Desktop App Picker](../../companion-app/desktop-app-picker/).\n\n## Finish the Editing Session\n\nClosing the desktop app by itself does not upload the file and does not finish the session. Uploading is initiated in the **Done Editing** window.\n\n- Changed file: use **Done Editing \u2014 Hold to Upload**.\n- Unchanged file: use **Done Editing \u2014 Hold to Close**.\n- Do not want to keep the local changes: use **Discard Changes \u2014 Hold**.\n\nIf the **Done Editing** window tells you that the session expired, authentication failed, the lock was lost, or recovery is required, reopen the file from Sambee instead of retrying the old desktop-editing session indefinitely. That starts a fresh authenticated edit session with a new server-side lock.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Edit Files in Desktop Apps\"\n+++\n\nSambee can open files in installed desktop apps through its Companion helper. If the file is on a local drive, the desktop app can access it directly. In that case, Companion opens the app with the original file path.\n\nIf the file is on one of Sambee's SMB connections, the desktop app cannot access it directly. In that case, Companion opens a temporary local copy in the desktop app and synchronizes your changes back to the original location.\n\nThe remainder of this page describes the second case.\n\n## Before You Begin\n\nYou need:\n\n- Sambee Companion installed and running on your computer.\n- A desktop app that can open the file type you want to edit.\n\nNeed Companion first? Start with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/).\n\n## Start the Editing Workflow\n\nIn Sambee, right-click the file and choose **Open in companion app**, or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nSambee hands the request to Companion through a `sambee://` link. When your browser asks whether to allow that link to open, choose **yes**.\n{{\u003c /admonition \u003e}}\n\n{{\u003c admonition type=\"note\" \u003e}}\nIf your Sambee site is behind a proxy server, Companion may show a separate **Sambee Authentication** window before opening the file. Sign in there and then continue the desktop-editing workflow.\n{{\u003c /admonition \u003e}}\n\n### What Happens Under the Hood\n\nCompanion handles the rest of the edit session:\n\n- It acquires an edit lock for the file on the file share.\n- It downloads the file and stores a temporary local copy.\n- If needed, it asks you which desktop app should open the file.\n- It opens the local copy in that app.\n- It shows a **Done Editing** window, which you use to upload the modified local copy when you are done.\n\n## Choose an App to Open the File\n\nThe first time you open a file type, Companion may show an app picker listing the installed apps available for that file type. Choose an app from the list for that extension and optionally remember that choice for later. For app-selection help, use [Desktop App Picker](../../companion-app/desktop-app-picker/).\n\n## Finish the Editing Session\n\nClosing the desktop app by itself does not upload the file and does not finish the session. Uploading is initiated in the **Done Editing** window.\n\n- Changed file: use **Done Editing \u2014 Hold to Upload**.\n- Unchanged file: use **Done Editing \u2014 Hold to Close**.\n- Do not want to keep the local changes: use **Discard Changes \u2014 Hold**.\n\nIf the **Done Editing** window tells you that the session expired, authentication failed, the lock was lost, or recovery is required, reopen the file from Sambee instead of retrying the old desktop-editing session indefinitely. That starts a fresh authenticated edit session with a new server-side lock.\n", "0.8": "+++\ntitle = \"Edit Files in Desktop Apps\"\n+++\n\nSambee can open files in installed desktop apps through its Companion helper. If the file is on a local drive, the desktop app can access it directly. In that case, Companion opens the app with the original file path.\n\nIf the file is on one of Sambee's SMB connections, the desktop app cannot access it directly. In that case, Companion opens a temporary local copy in the desktop app and synchronizes your changes back to the original location.\n\nThe remainder of this page describes the second case.\n\n## Before You Begin\n\nYou need:\n\n- Sambee Companion installed and running on your computer.\n- A desktop app that can open the file type you want to edit.\n\nNeed Companion first? Start with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/).\n\n## Start the Editing Workflow\n\nIn Sambee, right-click the file and choose **Open in companion app**, or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nSambee hands the request to Companion through a `sambee://` link. When your browser asks whether to allow that link to open, choose **yes**.\n{{\u003c /admonition \u003e}}\n\n{{\u003c admonition type=\"note\" \u003e}}\nIf your Sambee site is behind a proxy server, Companion may show a separate **Sambee Authentication** window before opening the file. Sign in there and then continue the desktop-editing workflow.\n{{\u003c /admonition \u003e}}\n\n### What Happens Under the Hood\n\nCompanion handles the rest of the edit session:\n\n- It acquires an edit lock for the file on the file share.\n- It downloads the file and stores a temporary local copy.\n- If needed, it asks you which desktop app should open the file.\n- It opens the local copy in that app.\n- It shows a **Done Editing** window, which you use to upload the modified local copy when you are done.\n\n## Choose an App to Open the File\n\nThe first time you open a file type, Companion may show an app picker listing the installed apps available for that file type. Choose an app from the list for that extension and optionally remember that choice for later. For app-selection help, use [Desktop App Picker](../../companion-app/desktop-app-picker/).\n\n## Finish the Editing Session\n\nClosing the desktop app by itself does not upload the file and does not finish the session. Uploading is initiated in the **Done Editing** window.\n\n- Changed file: use **Done Editing \u2014 Hold to Upload**.\n- Unchanged file: use **Done Editing \u2014 Hold to Close**.\n- Do not want to keep the local changes: use **Discard Changes \u2014 Hold**.\n\nIf the **Done Editing** window tells you that the session expired, authentication failed, the lock was lost, or recovery is required, reopen the file from Sambee instead of retrying the old desktop-editing session indefinitely. That starts a fresh authenticated edit session with a new server-side lock.\n", "0.9": "+++\ntitle = \"Edit Files in Desktop Apps\"\n+++\n\nSambee can open files in installed desktop apps through its Companion helper. If the file is on a local drive, the desktop app can access it directly. In that case, Companion opens the app with the original file path.\n\nIf the file is on one of Sambee's SMB connections, the desktop app cannot access it directly. In that case, Companion opens a temporary local copy in the desktop app and synchronizes your changes back to the original location.\n\nThe remainder of this page describes the second case.\n\n## Before You Begin\n\nYou need:\n\n- Sambee Companion installed and running on your computer.\n- A desktop app that can open the file type you want to edit.\n\nNeed Companion first? Start with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/).\n\n## Start the Editing Workflow\n\nIn Sambee, right-click the file and choose **Open in companion app**, or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nSambee hands the request to Companion through a `sambee://` link. When your browser asks whether to allow that link to open, choose **yes**.\n{{\u003c /admonition \u003e}}\n\n{{\u003c admonition type=\"note\" \u003e}}\nIf your Sambee site is behind a proxy server, Companion may show a separate **Sambee Authentication** window before opening the file. Sign in there and then continue the desktop-editing workflow.\n{{\u003c /admonition \u003e}}\n\n### What Happens Under the Hood\n\nCompanion handles the rest of the edit session:\n\n- It acquires an edit lock for the file on the file share.\n- It downloads the file and stores a temporary local copy.\n- If needed, it asks you which desktop app should open the file.\n- It opens the local copy in that app.\n- It shows a **Done Editing** window, which you use to upload the modified local copy when you are done.\n\n## Choose an App to Open the File\n\nThe first time you open a file type, Companion may show an app picker listing the installed apps available for that file type. Choose an app from the list for that extension and optionally remember that choice for later. For app-selection help, use [Desktop App Picker](../../companion-app/desktop-app-picker/).\n\n## Finish the Editing Session\n\nClosing the desktop app by itself does not upload the file and does not finish the session. Uploading is initiated in the **Done Editing** window.\n\n- Changed file: use **Done Editing \u2014 Hold to Upload**.\n- Unchanged file: use **Done Editing \u2014 Hold to Close**.\n- Do not want to keep the local changes: use **Discard Changes \u2014 Hold**.\n\nIf the **Done Editing** window tells you that the session expired, authentication failed, the lock was lost, or recovery is required, reopen the file from Sambee instead of retrying the old desktop-editing session indefinitely. That starts a fresh authenticated edit session with a new server-side lock.\n", "1.0": "+++\ntitle = \"Edit Files in Desktop Apps\"\n+++\n\nSambee can open files in installed desktop apps through its Companion helper. If the file is on a local drive, the desktop app can access it directly. In that case, Companion opens the app with the original file path.\n\nIf the file is on one of Sambee's SMB connections, the desktop app cannot access it directly. In that case, Companion opens a temporary local copy in the desktop app and synchronizes your changes back to the original location.\n\nThe remainder of this page describes the second case.\n\n## Before You Begin\n\nYou need:\n\n- Sambee Companion installed and running on your computer.\n- A desktop app that can open the file type you want to edit.\n\nNeed Companion first? Start with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/).\n\n## Start the Editing Workflow\n\nIn Sambee, right-click the file and choose **Open in companion app**, or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nSambee hands the request to Companion through a `sambee://` link. When your browser asks whether to allow that link to open, choose **yes**.\n{{\u003c /admonition \u003e}}\n\n{{\u003c admonition type=\"note\" \u003e}}\nIf your Sambee site is behind a proxy server, Companion may show a separate **Sambee Authentication** window before opening the file. Sign in there and then continue the desktop-editing workflow.\n{{\u003c /admonition \u003e}}\n\n### What Happens Under the Hood\n\nCompanion handles the rest of the edit session:\n\n- It acquires an edit lock for the file on the file share.\n- It downloads the file and stores a temporary local copy.\n- If needed, it asks you which desktop app should open the file.\n- It opens the local copy in that app.\n- It shows a **Done Editing** window, which you use to upload the modified local copy when you are done.\n\n## Choose an App to Open the File\n\nThe first time you open a file type, Companion may show an app picker listing the installed apps available for that file type. Choose an app from the list for that extension and optionally remember that choice for later. For app-selection help, use [Desktop App Picker](../../companion-app/desktop-app-picker/).\n\n## Finish the Editing Session\n\nClosing the desktop app by itself does not upload the file and does not finish the session. Uploading is initiated in the **Done Editing** window.\n\n- Changed file: use **Done Editing \u2014 Hold to Upload**.\n- Unchanged file: use **Done Editing \u2014 Hold to Close**.\n- Do not want to keep the local changes: use **Discard Changes \u2014 Hold**.\n\nIf the **Done Editing** window tells you that the session expired, authentication failed, the lock was lost, or recovery is required, reopen the file from Sambee instead of retrying the old desktop-editing session indefinitely. That starts a fresh authenticated edit session with a new server-side lock.\n", "2.0": "+++\ntitle = \"Edit Files in Desktop Apps\"\n+++\n\nSambee can open files in installed desktop apps through its Companion helper. If the file is on a local drive, the desktop app can access it directly. In that case, Companion opens the app with the original file path.\n\nIf the file is on one of Sambee's SMB connections, the desktop app cannot access it directly. In that case, Companion opens a temporary local copy in the desktop app and synchronizes your changes back to the original location.\n\nThe remainder of this page describes the second case.\n\n## Before You Begin\n\nYou need:\n\n- Sambee Companion installed and running on your computer.\n- A desktop app that can open the file type you want to edit.\n\nNeed Companion first? Start with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/).\n\n## Start the Editing Workflow\n\nIn Sambee, right-click the file and choose **Open in companion app**, or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nSambee hands the request to Companion through a `sambee://` link. When your browser asks whether to allow that link to open, choose **yes**.\n{{\u003c /admonition \u003e}}\n\n{{\u003c admonition type=\"note\" \u003e}}\nIf your Sambee site is behind a proxy server, Companion may show a separate **Sambee Authentication** window before opening the file. Sign in there and then continue the desktop-editing workflow.\n{{\u003c /admonition \u003e}}\n\n### What Happens Under the Hood\n\nCompanion handles the rest of the edit session:\n\n- It acquires an edit lock for the file on the file share.\n- It downloads the file and stores a temporary local copy.\n- If needed, it asks you which desktop app should open the file.\n- It opens the local copy in that app.\n- It shows a **Done Editing** window, which you use to upload the modified local copy when you are done.\n\n## Choose an App to Open the File\n\nThe first time you open a file type, Companion may show an app picker listing the installed apps available for that file type. Choose an app from the list for that extension and optionally remember that choice for later. For app-selection help, use [Desktop App Picker](../../companion-app/desktop-app-picker/).\n\n## Finish the Editing Session\n\nClosing the desktop app by itself does not upload the file and does not finish the session. Uploading is initiated in the **Done Editing** window.\n\n- Changed file: use **Done Editing \u2014 Hold to Upload**.\n- Unchanged file: use **Done Editing \u2014 Hold to Close**.\n- Do not want to keep the local changes: use **Discard Changes \u2014 Hold**.\n\nIf the **Done Editing** window tells you that the session expired, authentication failed, the lock was lost, or recovery is required, reopen the file from Sambee instead of retrying the old desktop-editing session indefinitely. That starts a fresh authenticated edit session with a new server-side lock.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:user-guide/viewing-and-editing-files/file-locking-and-conflict-resolution", "parent_id": "section:user-guide/viewing-and-editing-files", "depth": 2, "kind": "page", "label": "file-locking-and-conflict-resolution", "title": "File Locking And Conflict Resolution", "path": "user-guide/viewing-and-editing-files/file-locking-and-conflict-resolution", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"File Locking \u0026 Conflict Resolution\"\n+++\n\nSambee uses two protections that are easy to confuse:\n\n- **Edit locks** stop a file from being edited simultaneously in two places.\n- **Conflict resolution** happens later when Companion tries to upload a desktop-edited file back to the server and notices the server-side copy was changed, too.\n\n## Edit Locks\n\nSambee uses edit locks on SMB connections to prevent other users from editing a file at the same time as you do.\n\n### Markdown Editing\n\nSambee acquires an edit lock before it opens the Markdown editor. Sambee releases the lock when you leave the editor.\n\nIf the file is already locked by another user, Sambee does not enter edit mode. Instead, it keeps the file in the read-only viewer and shows an error explaining that the file is already locked for editing.\n\n### Desktop Editing\n\nCompanion acquires an edit lock before downloading the temporary local copy.\n\nIf another user already holds that lock, the desktop-editing workflow cannot start.\n\nWhen you upload, discard changes, or finish an unchanged session, Companion releases that lock.\n\n## Conflict Resolution after Desktop Editing\n\nBefore uploading, Companion checks whether the server copy changed after the local copy was downloaded.\n\nIf it did, the **Done Editing** window switches to a conflict resolution dialog.\n\nThe choices are:\n\n- **Overwrite Server Version**: replace the current server copy with your edited version\n- **Save as Copy**: upload your changes as a separate `(conflict copy)` file\n- **Cancel**: go back without uploading yet\n\n## If a Desktop Editing Session is Interrupted\n\nIf Companion is closed during an editing session, it shows an **Unsaved Files Found** recovery dialog the next time it starts.\n\nThe choices are:\n\n- **Upload**: send the saved local edits back to the server\n- **Discard**: throw the temporary copy away\n- **Later**: keep the session for later recovery\n", "0.8": "+++\ntitle = \"File Locking \u0026 Conflict Resolution\"\n+++\n\nSambee uses two protections that are easy to confuse:\n\n- **Edit locks** stop a file from being edited simultaneously in two places.\n- **Conflict resolution** happens later when Companion tries to upload a desktop-edited file back to the server and notices the server-side copy was changed, too.\n\n## Edit Locks\n\nSambee uses edit locks on SMB connections to prevent other users from editing a file at the same time as you do.\n\n### Markdown Editing\n\nSambee acquires an edit lock before it opens the Markdown editor. Sambee releases the lock when you leave the editor.\n\nIf the file is already locked by another user, Sambee does not enter edit mode. Instead, it keeps the file in the read-only viewer and shows an error explaining that the file is already locked for editing.\n\n### Desktop Editing\n\nCompanion acquires an edit lock before downloading the temporary local copy.\n\nIf another user already holds that lock, the desktop-editing workflow cannot start.\n\nWhen you upload, discard changes, or finish an unchanged session, Companion releases that lock.\n\n## Conflict Resolution after Desktop Editing\n\nBefore uploading, Companion checks whether the server copy changed after the local copy was downloaded.\n\nIf it did, the **Done Editing** window switches to a conflict resolution dialog.\n\nThe choices are:\n\n- **Overwrite Server Version**: replace the current server copy with your edited version\n- **Save as Copy**: upload your changes as a separate `(conflict copy)` file\n- **Cancel**: go back without uploading yet\n\n## If a Desktop Editing Session is Interrupted\n\nIf Companion is closed during an editing session, it shows an **Unsaved Files Found** recovery dialog the next time it starts.\n\nThe choices are:\n\n- **Upload**: send the saved local edits back to the server\n- **Discard**: throw the temporary copy away\n- **Later**: keep the session for later recovery\n", "0.9": "+++\ntitle = \"File Locking \u0026 Conflict Resolution\"\n+++\n\nSambee uses two protections that are easy to confuse:\n\n- **Edit locks** stop a file from being edited simultaneously in two places.\n- **Conflict resolution** happens later when Companion tries to upload a desktop-edited file back to the server and notices the server-side copy was changed, too.\n\n## Edit Locks\n\nSambee uses edit locks on SMB connections to prevent other users from editing a file at the same time as you do.\n\n### Markdown Editing\n\nSambee acquires an edit lock before it opens the Markdown editor. Sambee releases the lock when you leave the editor.\n\nIf the file is already locked by another user, Sambee does not enter edit mode. Instead, it keeps the file in the read-only viewer and shows an error explaining that the file is already locked for editing.\n\n### Desktop Editing\n\nCompanion acquires an edit lock before downloading the temporary local copy.\n\nIf another user already holds that lock, the desktop-editing workflow cannot start.\n\nWhen you upload, discard changes, or finish an unchanged session, Companion releases that lock.\n\n## Conflict Resolution after Desktop Editing\n\nBefore uploading, Companion checks whether the server copy changed after the local copy was downloaded.\n\nIf it did, the **Done Editing** window switches to a conflict resolution dialog.\n\nThe choices are:\n\n- **Overwrite Server Version**: replace the current server copy with your edited version\n- **Save as Copy**: upload your changes as a separate `(conflict copy)` file\n- **Cancel**: go back without uploading yet\n\n## If a Desktop Editing Session is Interrupted\n\nIf Companion is closed during an editing session, it shows an **Unsaved Files Found** recovery dialog the next time it starts.\n\nThe choices are:\n\n- **Upload**: send the saved local edits back to the server\n- **Discard**: throw the temporary copy away\n- **Later**: keep the session for later recovery\n", "1.0": "+++\ntitle = \"File Locking \u0026 Conflict Resolution\"\n+++\n\nSambee uses two protections that are easy to confuse:\n\n- **Edit locks** stop a file from being edited simultaneously in two places.\n- **Conflict resolution** happens later when Companion tries to upload a desktop-edited file back to the server and notices the server-side copy was changed, too.\n\n## Edit Locks\n\nSambee uses edit locks on SMB connections to prevent other users from editing a file at the same time as you do.\n\n### Markdown Editing\n\nSambee acquires an edit lock before it opens the Markdown editor. Sambee releases the lock when you leave the editor.\n\nIf the file is already locked by another user, Sambee does not enter edit mode. Instead, it keeps the file in the read-only viewer and shows an error explaining that the file is already locked for editing.\n\n### Desktop Editing\n\nCompanion acquires an edit lock before downloading the temporary local copy.\n\nIf another user already holds that lock, the desktop-editing workflow cannot start.\n\nWhen you upload, discard changes, or finish an unchanged session, Companion releases that lock.\n\n## Conflict Resolution after Desktop Editing\n\nBefore uploading, Companion checks whether the server copy changed after the local copy was downloaded.\n\nIf it did, the **Done Editing** window switches to a conflict resolution dialog.\n\nThe choices are:\n\n- **Overwrite Server Version**: replace the current server copy with your edited version\n- **Save as Copy**: upload your changes as a separate `(conflict copy)` file\n- **Cancel**: go back without uploading yet\n\n## If a Desktop Editing Session is Interrupted\n\nIf Companion is closed during an editing session, it shows an **Unsaved Files Found** recovery dialog the next time it starts.\n\nThe choices are:\n\n- **Upload**: send the saved local edits back to the server\n- **Discard**: throw the temporary copy away\n- **Later**: keep the session for later recovery\n", "2.0": "+++\ntitle = \"File Locking \u0026 Conflict Resolution\"\n+++\n\nSambee uses two protections that are easy to confuse:\n\n- **Edit locks** stop a file from being edited simultaneously in two places.\n- **Conflict resolution** happens later when Companion tries to upload a desktop-edited file back to the server and notices the server-side copy was changed, too.\n\n## Edit Locks\n\nSambee uses edit locks on SMB connections to prevent other users from editing a file at the same time as you do.\n\n### Markdown Editing\n\nSambee acquires an edit lock before it opens the Markdown editor. Sambee releases the lock when you leave the editor.\n\nIf the file is already locked by another user, Sambee does not enter edit mode. Instead, it keeps the file in the read-only viewer and shows an error explaining that the file is already locked for editing.\n\n### Desktop Editing\n\nCompanion acquires an edit lock before downloading the temporary local copy.\n\nIf another user already holds that lock, the desktop-editing workflow cannot start.\n\nWhen you upload, discard changes, or finish an unchanged session, Companion releases that lock.\n\n## Conflict Resolution after Desktop Editing\n\nBefore uploading, Companion checks whether the server copy changed after the local copy was downloaded.\n\nIf it did, the **Done Editing** window switches to a conflict resolution dialog.\n\nThe choices are:\n\n- **Overwrite Server Version**: replace the current server copy with your edited version\n- **Save as Copy**: upload your changes as a separate `(conflict copy)` file\n- **Cancel**: go back without uploading yet\n\n## If a Desktop Editing Session is Interrupted\n\nIf Companion is closed during an editing session, it shows an **Unsaved Files Found** recovery dialog the next time it starts.\n\nThe choices are:\n\n- **Upload**: send the saved local edits back to the server\n- **Discard**: throw the temporary copy away\n- **Later**: keep the session for later recovery\n"}, "page_contents": {"0.7": "+++\ntitle = \"File Locking \u0026 Conflict Resolution\"\n+++\n\nSambee uses two protections that are easy to confuse:\n\n- **Edit locks** stop a file from being edited simultaneously in two places.\n- **Conflict resolution** happens later when Companion tries to upload a desktop-edited file back to the server and notices the server-side copy was changed, too.\n\n## Edit Locks\n\nSambee uses edit locks on SMB connections to prevent other users from editing a file at the same time as you do.\n\n### Markdown Editing\n\nSambee acquires an edit lock before it opens the Markdown editor. Sambee releases the lock when you leave the editor.\n\nIf the file is already locked by another user, Sambee does not enter edit mode. Instead, it keeps the file in the read-only viewer and shows an error explaining that the file is already locked for editing.\n\n### Desktop Editing\n\nCompanion acquires an edit lock before downloading the temporary local copy.\n\nIf another user already holds that lock, the desktop-editing workflow cannot start.\n\nWhen you upload, discard changes, or finish an unchanged session, Companion releases that lock.\n\n## Conflict Resolution after Desktop Editing\n\nBefore uploading, Companion checks whether the server copy changed after the local copy was downloaded.\n\nIf it did, the **Done Editing** window switches to a conflict resolution dialog.\n\nThe choices are:\n\n- **Overwrite Server Version**: replace the current server copy with your edited version\n- **Save as Copy**: upload your changes as a separate `(conflict copy)` file\n- **Cancel**: go back without uploading yet\n\n## If a Desktop Editing Session is Interrupted\n\nIf Companion is closed during an editing session, it shows an **Unsaved Files Found** recovery dialog the next time it starts.\n\nThe choices are:\n\n- **Upload**: send the saved local edits back to the server\n- **Discard**: throw the temporary copy away\n- **Later**: keep the session for later recovery\n", "0.8": "+++\ntitle = \"File Locking \u0026 Conflict Resolution\"\n+++\n\nSambee uses two protections that are easy to confuse:\n\n- **Edit locks** stop a file from being edited simultaneously in two places.\n- **Conflict resolution** happens later when Companion tries to upload a desktop-edited file back to the server and notices the server-side copy was changed, too.\n\n## Edit Locks\n\nSambee uses edit locks on SMB connections to prevent other users from editing a file at the same time as you do.\n\n### Markdown Editing\n\nSambee acquires an edit lock before it opens the Markdown editor. Sambee releases the lock when you leave the editor.\n\nIf the file is already locked by another user, Sambee does not enter edit mode. Instead, it keeps the file in the read-only viewer and shows an error explaining that the file is already locked for editing.\n\n### Desktop Editing\n\nCompanion acquires an edit lock before downloading the temporary local copy.\n\nIf another user already holds that lock, the desktop-editing workflow cannot start.\n\nWhen you upload, discard changes, or finish an unchanged session, Companion releases that lock.\n\n## Conflict Resolution after Desktop Editing\n\nBefore uploading, Companion checks whether the server copy changed after the local copy was downloaded.\n\nIf it did, the **Done Editing** window switches to a conflict resolution dialog.\n\nThe choices are:\n\n- **Overwrite Server Version**: replace the current server copy with your edited version\n- **Save as Copy**: upload your changes as a separate `(conflict copy)` file\n- **Cancel**: go back without uploading yet\n\n## If a Desktop Editing Session is Interrupted\n\nIf Companion is closed during an editing session, it shows an **Unsaved Files Found** recovery dialog the next time it starts.\n\nThe choices are:\n\n- **Upload**: send the saved local edits back to the server\n- **Discard**: throw the temporary copy away\n- **Later**: keep the session for later recovery\n", "0.9": "+++\ntitle = \"File Locking \u0026 Conflict Resolution\"\n+++\n\nSambee uses two protections that are easy to confuse:\n\n- **Edit locks** stop a file from being edited simultaneously in two places.\n- **Conflict resolution** happens later when Companion tries to upload a desktop-edited file back to the server and notices the server-side copy was changed, too.\n\n## Edit Locks\n\nSambee uses edit locks on SMB connections to prevent other users from editing a file at the same time as you do.\n\n### Markdown Editing\n\nSambee acquires an edit lock before it opens the Markdown editor. Sambee releases the lock when you leave the editor.\n\nIf the file is already locked by another user, Sambee does not enter edit mode. Instead, it keeps the file in the read-only viewer and shows an error explaining that the file is already locked for editing.\n\n### Desktop Editing\n\nCompanion acquires an edit lock before downloading the temporary local copy.\n\nIf another user already holds that lock, the desktop-editing workflow cannot start.\n\nWhen you upload, discard changes, or finish an unchanged session, Companion releases that lock.\n\n## Conflict Resolution after Desktop Editing\n\nBefore uploading, Companion checks whether the server copy changed after the local copy was downloaded.\n\nIf it did, the **Done Editing** window switches to a conflict resolution dialog.\n\nThe choices are:\n\n- **Overwrite Server Version**: replace the current server copy with your edited version\n- **Save as Copy**: upload your changes as a separate `(conflict copy)` file\n- **Cancel**: go back without uploading yet\n\n## If a Desktop Editing Session is Interrupted\n\nIf Companion is closed during an editing session, it shows an **Unsaved Files Found** recovery dialog the next time it starts.\n\nThe choices are:\n\n- **Upload**: send the saved local edits back to the server\n- **Discard**: throw the temporary copy away\n- **Later**: keep the session for later recovery\n", "1.0": "+++\ntitle = \"File Locking \u0026 Conflict Resolution\"\n+++\n\nSambee uses two protections that are easy to confuse:\n\n- **Edit locks** stop a file from being edited simultaneously in two places.\n- **Conflict resolution** happens later when Companion tries to upload a desktop-edited file back to the server and notices the server-side copy was changed, too.\n\n## Edit Locks\n\nSambee uses edit locks on SMB connections to prevent other users from editing a file at the same time as you do.\n\n### Markdown Editing\n\nSambee acquires an edit lock before it opens the Markdown editor. Sambee releases the lock when you leave the editor.\n\nIf the file is already locked by another user, Sambee does not enter edit mode. Instead, it keeps the file in the read-only viewer and shows an error explaining that the file is already locked for editing.\n\n### Desktop Editing\n\nCompanion acquires an edit lock before downloading the temporary local copy.\n\nIf another user already holds that lock, the desktop-editing workflow cannot start.\n\nWhen you upload, discard changes, or finish an unchanged session, Companion releases that lock.\n\n## Conflict Resolution after Desktop Editing\n\nBefore uploading, Companion checks whether the server copy changed after the local copy was downloaded.\n\nIf it did, the **Done Editing** window switches to a conflict resolution dialog.\n\nThe choices are:\n\n- **Overwrite Server Version**: replace the current server copy with your edited version\n- **Save as Copy**: upload your changes as a separate `(conflict copy)` file\n- **Cancel**: go back without uploading yet\n\n## If a Desktop Editing Session is Interrupted\n\nIf Companion is closed during an editing session, it shows an **Unsaved Files Found** recovery dialog the next time it starts.\n\nThe choices are:\n\n- **Upload**: send the saved local edits back to the server\n- **Discard**: throw the temporary copy away\n- **Later**: keep the session for later recovery\n", "2.0": "+++\ntitle = \"File Locking \u0026 Conflict Resolution\"\n+++\n\nSambee uses two protections that are easy to confuse:\n\n- **Edit locks** stop a file from being edited simultaneously in two places.\n- **Conflict resolution** happens later when Companion tries to upload a desktop-edited file back to the server and notices the server-side copy was changed, too.\n\n## Edit Locks\n\nSambee uses edit locks on SMB connections to prevent other users from editing a file at the same time as you do.\n\n### Markdown Editing\n\nSambee acquires an edit lock before it opens the Markdown editor. Sambee releases the lock when you leave the editor.\n\nIf the file is already locked by another user, Sambee does not enter edit mode. Instead, it keeps the file in the read-only viewer and shows an error explaining that the file is already locked for editing.\n\n### Desktop Editing\n\nCompanion acquires an edit lock before downloading the temporary local copy.\n\nIf another user already holds that lock, the desktop-editing workflow cannot start.\n\nWhen you upload, discard changes, or finish an unchanged session, Companion releases that lock.\n\n## Conflict Resolution after Desktop Editing\n\nBefore uploading, Companion checks whether the server copy changed after the local copy was downloaded.\n\nIf it did, the **Done Editing** window switches to a conflict resolution dialog.\n\nThe choices are:\n\n- **Overwrite Server Version**: replace the current server copy with your edited version\n- **Save as Copy**: upload your changes as a separate `(conflict copy)` file\n- **Cancel**: go back without uploading yet\n\n## If a Desktop Editing Session is Interrupted\n\nIf Companion is closed during an editing session, it shows an **Unsaved Files Found** recovery dialog the next time it starts.\n\nThe choices are:\n\n- **Upload**: send the saved local edits back to the server\n- **Discard**: throw the temporary copy away\n- **Later**: keep the session for later recovery\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:user-guide/viewing-and-editing-files/recover-unsaved-edits", "parent_id": "section:user-guide/viewing-and-editing-files", "depth": 2, "kind": "page", "label": "recover-unsaved-edits", "title": "Recover Unsaved Edits", "path": "user-guide/viewing-and-editing-files/recover-unsaved-edits", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "authored"}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "inherited", "source_version": "0.9"}}, "content_versions": {"0.9": "+++\ntitle = \"Recover Unsaved In-Browser Edits\"\n+++\n\nSambee can preserve eligible unsaved Markdown and plain-text edits when a required OIDC sign-in takes you away from the editor.\n\n## When Sambee Saves A Draft\n\nSambee saves a tab-scoped recovery draft before a controlled sign-in redirect and while you continue editing. This protects work when the browser session expires, an administrator revokes the session, or the identity provider requires you to sign in again.\n\nDrafts stay in the current browser tab. They are not uploaded to Sambee, shared with another browser, or shown after you sign in as a different account.\n\n## Return To Your Edit\n\nAfter you finish signing in, Sambee returns you to the file you were editing.\n\n- If the remote file has not changed, Sambee restores your unsaved draft in the editor.\n- If the remote file changed, Sambee shows a recovery choice and does not overwrite the remote version automatically.\n- Save the restored draft when you are ready. Sambee removes its recovery copy after a successful save or when you deliberately discard it.\n\n## Recovery Limits\n\nDraft recovery depends on browser tab storage. Sambee keeps recovery drafts only for a limited time and displays a warning when a draft is too large or the browser cannot store it. Save important work regularly; do not rely on draft recovery as a replacement for saving.\n\nClosing the tab, explicitly discarding the draft, or signing out can remove the recovery copy.\n\n", "1.0": "+++\ntitle = \"Recover Unsaved In-Browser Edits\"\n+++\n\nSambee can preserve eligible unsaved Markdown and plain-text edits when a required OIDC sign-in takes you away from the editor.\n\n## When Sambee Saves A Draft\n\nSambee saves a tab-scoped recovery draft before a controlled sign-in redirect and while you continue editing. This protects work when the browser session expires, an administrator revokes the session, or the identity provider requires you to sign in again.\n\nDrafts stay in the current browser tab. They are not uploaded to Sambee, shared with another browser, or shown after you sign in as a different account.\n\n## Return To Your Edit\n\nAfter you finish signing in, Sambee returns you to the file you were editing.\n\n- If the remote file has not changed, Sambee restores your unsaved draft in the editor.\n- If the remote file changed, Sambee shows a recovery choice and does not overwrite the remote version automatically.\n- Save the restored draft when you are ready. Sambee removes its recovery copy after a successful save or when you deliberately discard it.\n\n## Recovery Limits\n\nDraft recovery depends on browser tab storage. Sambee keeps recovery drafts only for a limited time and displays a warning when a draft is too large or the browser cannot store it. Save important work regularly; do not rely on draft recovery as a replacement for saving.\n\nClosing the tab, explicitly discarding the draft, or signing out can remove the recovery copy.\n\n", "2.0": "+++\ntitle = \"Recover Unsaved In-Browser Edits\"\n+++\n\nSambee can preserve eligible unsaved Markdown and plain-text edits when a required OIDC sign-in takes you away from the editor.\n\n## When Sambee Saves A Draft\n\nSambee saves a tab-scoped recovery draft before a controlled sign-in redirect and while you continue editing. This protects work when the browser session expires, an administrator revokes the session, or the identity provider requires you to sign in again.\n\nDrafts stay in the current browser tab. They are not uploaded to Sambee, shared with another browser, or shown after you sign in as a different account.\n\n## Return To Your Edit\n\nAfter you finish signing in, Sambee returns you to the file you were editing.\n\n- If the remote file has not changed, Sambee restores your unsaved draft in the editor.\n- If the remote file changed, Sambee shows a recovery choice and does not overwrite the remote version automatically.\n- Save the restored draft when you are ready. Sambee removes its recovery copy after a successful save or when you deliberately discard it.\n\n## Recovery Limits\n\nDraft recovery depends on browser tab storage. Sambee keeps recovery drafts only for a limited time and displays a warning when a draft is too large or the browser cannot store it. Save important work regularly; do not rely on draft recovery as a replacement for saving.\n\nClosing the tab, explicitly discarding the draft, or signing out can remove the recovery copy.\n\n"}, "page_contents": {"0.9": "+++\ntitle = \"Recover Unsaved In-Browser Edits\"\n+++\n\nSambee can preserve eligible unsaved Markdown and plain-text edits when a required OIDC sign-in takes you away from the editor.\n\n## When Sambee Saves A Draft\n\nSambee saves a tab-scoped recovery draft before a controlled sign-in redirect and while you continue editing. This protects work when the browser session expires, an administrator revokes the session, or the identity provider requires you to sign in again.\n\nDrafts stay in the current browser tab. They are not uploaded to Sambee, shared with another browser, or shown after you sign in as a different account.\n\n## Return To Your Edit\n\nAfter you finish signing in, Sambee returns you to the file you were editing.\n\n- If the remote file has not changed, Sambee restores your unsaved draft in the editor.\n- If the remote file changed, Sambee shows a recovery choice and does not overwrite the remote version automatically.\n- Save the restored draft when you are ready. Sambee removes its recovery copy after a successful save or when you deliberately discard it.\n\n## Recovery Limits\n\nDraft recovery depends on browser tab storage. Sambee keeps recovery drafts only for a limited time and displays a warning when a draft is too large or the browser cannot store it. Save important work regularly; do not rely on draft recovery as a replacement for saving.\n\nClosing the tab, explicitly discarding the draft, or signing out can remove the recovery copy.\n\n", "1.0": "+++\ntitle = \"Recover Unsaved In-Browser Edits\"\n+++\n\nSambee can preserve eligible unsaved Markdown and plain-text edits when a required OIDC sign-in takes you away from the editor.\n\n## When Sambee Saves A Draft\n\nSambee saves a tab-scoped recovery draft before a controlled sign-in redirect and while you continue editing. This protects work when the browser session expires, an administrator revokes the session, or the identity provider requires you to sign in again.\n\nDrafts stay in the current browser tab. They are not uploaded to Sambee, shared with another browser, or shown after you sign in as a different account.\n\n## Return To Your Edit\n\nAfter you finish signing in, Sambee returns you to the file you were editing.\n\n- If the remote file has not changed, Sambee restores your unsaved draft in the editor.\n- If the remote file changed, Sambee shows a recovery choice and does not overwrite the remote version automatically.\n- Save the restored draft when you are ready. Sambee removes its recovery copy after a successful save or when you deliberately discard it.\n\n## Recovery Limits\n\nDraft recovery depends on browser tab storage. Sambee keeps recovery drafts only for a limited time and displays a warning when a draft is too large or the browser cannot store it. Save important work regularly; do not rely on draft recovery as a replacement for saving.\n\nClosing the tab, explicitly discarding the draft, or signing out can remove the recovery copy.\n\n", "2.0": "+++\ntitle = \"Recover Unsaved In-Browser Edits\"\n+++\n\nSambee can preserve eligible unsaved Markdown and plain-text edits when a required OIDC sign-in takes you away from the editor.\n\n## When Sambee Saves A Draft\n\nSambee saves a tab-scoped recovery draft before a controlled sign-in redirect and while you continue editing. This protects work when the browser session expires, an administrator revokes the session, or the identity provider requires you to sign in again.\n\nDrafts stay in the current browser tab. They are not uploaded to Sambee, shared with another browser, or shown after you sign in as a different account.\n\n## Return To Your Edit\n\nAfter you finish signing in, Sambee returns you to the file you were editing.\n\n- If the remote file has not changed, Sambee restores your unsaved draft in the editor.\n- If the remote file changed, Sambee shows a recovery choice and does not overwrite the remote version automatically.\n- Save the restored draft when you are ready. Sambee removes its recovery copy after a successful save or when you deliberately discard it.\n\n## Recovery Limits\n\nDraft recovery depends on browser tab storage. Sambee keeps recovery drafts only for a limited time and displays a warning when a draft is too large or the browser cannot store it. Save important work regularly; do not rely on draft recovery as a replacement for saving.\n\nClosing the tab, explicitly discarding the draft, or signing out can remove the recovery copy.\n\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:user-guide/viewing-and-editing-files/download-and-upload-files", "parent_id": "section:user-guide/viewing-and-editing-files", "depth": 2, "kind": "page", "label": "download-and-upload-files", "title": "Download And Upload Files", "path": "user-guide/viewing-and-editing-files/download-and-upload-files", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "missing"}, "1.0": {"state": "authored"}, "2.0": {"state": "inherited", "source_version": "1.0"}}, "content_versions": {"1.0": "+++\ntitle = \"Download and Upload Files\"\n+++\n\nUse **Download** to save a file to your computer. Select a folder or several items in the same directory to download them together as `Sambee-download.zip`. The ZIP preserves the selected folders and their contents. Downloads don't create a ZIP in the source share or drive.\n\nDownload is available from the file browser toolbar and the compact item or selection menu. You can also select members or folders inside a ZIP stored on an SMB share or a paired local drive and download them as a new ZIP.\n\nTo keep a new archive in an SMB share instead, open a ZIP in one pane and a writable folder on the same SMB connection in the other pane. Select files or folders inside the ZIP, then choose **Create archive**. Unlike **Download**, this writes a persistent ZIP to the destination folder. Creating an archive from ZIP members isn't available for local-drive or mixed-connection destinations.\n\n## Upload Files and Folders\n\nOpen a writable folder in an SMB share or paired local drive. On desktop, choose **Upload** (or press `Ctrl` + `U`), then choose **Files** for one or more files or **Folder** for one folder. On a compact screen, use the **+** menu to choose **Upload files** or **Upload folder** directly. Folder selection depends on your browser; when it isn't supported, **Upload files** remains available. A folder picker may not return an empty folder, but dragging that folder into the browser can preserve it in supported browsers.\n\nYou can also drag files and folders from your computer onto a file list. The drop cue names the connection and current folder receiving them. In dual-pane mode, drop onto the pane you want; dropping on a file or folder row still targets that pane's current folder, not the row. If drops aren't supported by your browser or the destination isn't writable, use the upload picker instead.\n\nUploaded folders keep their names and internal structure. If a folder with the same name already exists, Sambee merges into it without removing files already there. If a file blocks a folder, or a folder blocks a file, you can skip or rename the incoming item; a folder isn't overwritten. Individual file conflicts can be skipped, renamed, or replaced.\n\nFiles upload one at a time. The progress notice shows the current file and path, and the final notice reports completed, skipped, failed, or uncertain results and folder counts. Cancelling or failing partway through doesn't undo files or folders already created. If a folder upload has an uncertain outcome, Sambee stops the remaining transfers; inspect the destination before trying again.\n\n## Download Limits\n\nSelected-item ZIPs are prepared in private temporary storage and removed after the download finishes or is cancelled. The default ZIP size limit is 250 MiB; administrators can change it in Advanced Settings. Local ZIP-member downloads also require the selected members' uncompressed data to fit this limit. A download exceeding the limit fails without leaving a partial ZIP in your share or drive. Single-file downloads are separate from this ZIP limit.\n", "2.0": "+++\ntitle = \"Download and Upload Files\"\n+++\n\nUse **Download** to save a file to your computer. Select a folder or several items in the same directory to download them together as `Sambee-download.zip`. The ZIP preserves the selected folders and their contents. Downloads don't create a ZIP in the source share or drive.\n\nDownload is available from the file browser toolbar and the compact item or selection menu. You can also select members or folders inside a ZIP stored on an SMB share or a paired local drive and download them as a new ZIP.\n\nTo keep a new archive in an SMB share instead, open a ZIP in one pane and a writable folder on the same SMB connection in the other pane. Select files or folders inside the ZIP, then choose **Create archive**. Unlike **Download**, this writes a persistent ZIP to the destination folder. Creating an archive from ZIP members isn't available for local-drive or mixed-connection destinations.\n\n## Upload Files and Folders\n\nOpen a writable folder in an SMB share or paired local drive. On desktop, choose **Upload** (or press `Ctrl` + `U`), then choose **Files** for one or more files or **Folder** for one folder. On a compact screen, use the **+** menu to choose **Upload files** or **Upload folder** directly. Folder selection depends on your browser; when it isn't supported, **Upload files** remains available. A folder picker may not return an empty folder, but dragging that folder into the browser can preserve it in supported browsers.\n\nYou can also drag files and folders from your computer onto a file list. The drop cue names the connection and current folder receiving them. In dual-pane mode, drop onto the pane you want; dropping on a file or folder row still targets that pane's current folder, not the row. If drops aren't supported by your browser or the destination isn't writable, use the upload picker instead.\n\nUploaded folders keep their names and internal structure. If a folder with the same name already exists, Sambee merges into it without removing files already there. If a file blocks a folder, or a folder blocks a file, you can skip or rename the incoming item; a folder isn't overwritten. Individual file conflicts can be skipped, renamed, or replaced.\n\nFiles upload one at a time. The progress notice shows the current file and path, and the final notice reports completed, skipped, failed, or uncertain results and folder counts. Cancelling or failing partway through doesn't undo files or folders already created. If a folder upload has an uncertain outcome, Sambee stops the remaining transfers; inspect the destination before trying again.\n\n## Download Limits\n\nSelected-item ZIPs are prepared in private temporary storage and removed after the download finishes or is cancelled. The default ZIP size limit is 250 MiB; administrators can change it in Advanced Settings. Local ZIP-member downloads also require the selected members' uncompressed data to fit this limit. A download exceeding the limit fails without leaving a partial ZIP in your share or drive. Single-file downloads are separate from this ZIP limit.\n"}, "page_contents": {"1.0": "+++\ntitle = \"Download and Upload Files\"\n+++\n\nUse **Download** to save a file to your computer. Select a folder or several items in the same directory to download them together as `Sambee-download.zip`. The ZIP preserves the selected folders and their contents. Downloads don't create a ZIP in the source share or drive.\n\nDownload is available from the file browser toolbar and the compact item or selection menu. You can also select members or folders inside a ZIP stored on an SMB share or a paired local drive and download them as a new ZIP.\n\nTo keep a new archive in an SMB share instead, open a ZIP in one pane and a writable folder on the same SMB connection in the other pane. Select files or folders inside the ZIP, then choose **Create archive**. Unlike **Download**, this writes a persistent ZIP to the destination folder. Creating an archive from ZIP members isn't available for local-drive or mixed-connection destinations.\n\n## Upload Files and Folders\n\nOpen a writable folder in an SMB share or paired local drive. On desktop, choose **Upload** (or press `Ctrl` + `U`), then choose **Files** for one or more files or **Folder** for one folder. On a compact screen, use the **+** menu to choose **Upload files** or **Upload folder** directly. Folder selection depends on your browser; when it isn't supported, **Upload files** remains available. A folder picker may not return an empty folder, but dragging that folder into the browser can preserve it in supported browsers.\n\nYou can also drag files and folders from your computer onto a file list. The drop cue names the connection and current folder receiving them. In dual-pane mode, drop onto the pane you want; dropping on a file or folder row still targets that pane's current folder, not the row. If drops aren't supported by your browser or the destination isn't writable, use the upload picker instead.\n\nUploaded folders keep their names and internal structure. If a folder with the same name already exists, Sambee merges into it without removing files already there. If a file blocks a folder, or a folder blocks a file, you can skip or rename the incoming item; a folder isn't overwritten. Individual file conflicts can be skipped, renamed, or replaced.\n\nFiles upload one at a time. The progress notice shows the current file and path, and the final notice reports completed, skipped, failed, or uncertain results and folder counts. Cancelling or failing partway through doesn't undo files or folders already created. If a folder upload has an uncertain outcome, Sambee stops the remaining transfers; inspect the destination before trying again.\n\n## Download Limits\n\nSelected-item ZIPs are prepared in private temporary storage and removed after the download finishes or is cancelled. The default ZIP size limit is 250 MiB; administrators can change it in Advanced Settings. Local ZIP-member downloads also require the selected members' uncompressed data to fit this limit. A download exceeding the limit fails without leaving a partial ZIP in your share or drive. Single-file downloads are separate from this ZIP limit.\n", "2.0": "+++\ntitle = \"Download and Upload Files\"\n+++\n\nUse **Download** to save a file to your computer. Select a folder or several items in the same directory to download them together as `Sambee-download.zip`. The ZIP preserves the selected folders and their contents. Downloads don't create a ZIP in the source share or drive.\n\nDownload is available from the file browser toolbar and the compact item or selection menu. You can also select members or folders inside a ZIP stored on an SMB share or a paired local drive and download them as a new ZIP.\n\nTo keep a new archive in an SMB share instead, open a ZIP in one pane and a writable folder on the same SMB connection in the other pane. Select files or folders inside the ZIP, then choose **Create archive**. Unlike **Download**, this writes a persistent ZIP to the destination folder. Creating an archive from ZIP members isn't available for local-drive or mixed-connection destinations.\n\n## Upload Files and Folders\n\nOpen a writable folder in an SMB share or paired local drive. On desktop, choose **Upload** (or press `Ctrl` + `U`), then choose **Files** for one or more files or **Folder** for one folder. On a compact screen, use the **+** menu to choose **Upload files** or **Upload folder** directly. Folder selection depends on your browser; when it isn't supported, **Upload files** remains available. A folder picker may not return an empty folder, but dragging that folder into the browser can preserve it in supported browsers.\n\nYou can also drag files and folders from your computer onto a file list. The drop cue names the connection and current folder receiving them. In dual-pane mode, drop onto the pane you want; dropping on a file or folder row still targets that pane's current folder, not the row. If drops aren't supported by your browser or the destination isn't writable, use the upload picker instead.\n\nUploaded folders keep their names and internal structure. If a folder with the same name already exists, Sambee merges into it without removing files already there. If a file blocks a folder, or a folder blocks a file, you can skip or rename the incoming item; a folder isn't overwritten. Individual file conflicts can be skipped, renamed, or replaced.\n\nFiles upload one at a time. The progress notice shows the current file and path, and the final notice reports completed, skipped, failed, or uncertain results and folder counts. Cancelling or failing partway through doesn't undo files or folders already created. If a folder upload has an uncertain outcome, Sambee stops the remaining transfers; inspect the destination before trying again.\n\n## Download Limits\n\nSelected-item ZIPs are prepared in private temporary storage and removed after the download finishes or is cancelled. The default ZIP size limit is 250 MiB; administrators can change it in Advanced Settings. Local ZIP-member downloads also require the selected members' uncompressed data to fit this limit. A download exceeding the limit fails without leaving a partial ZIP in your share or drive. Single-file downloads are separate from this ZIP limit.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:user-guide/companion-app", "parent_id": "book:user-guide", "depth": 1, "kind": "section", "label": "companion-app", "title": "Companion App", "path": "user-guide/companion-app", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:user-guide/companion-app/install-and-pair-the-companion-app", "parent_id": "section:user-guide/companion-app", "depth": 2, "kind": "page", "label": "install-and-pair-the-companion-app", "title": "Install And Pair The Companion App", "path": "user-guide/companion-app/install-and-pair-the-companion-app", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "branched", "source_version": "0.7", "diff_added": 17, "diff_removed": 4}, "0.9": {"state": "inherited", "source_version": "0.8"}, "1.0": {"state": "inherited", "source_version": "0.8"}, "2.0": {"state": "branched", "source_version": "0.8", "diff_added": 15, "diff_removed": 2}}, "content_versions": {"0.7": "+++\ntitle = \"Install and Pair the Companion App\"\n+++\n\nSambee Companion is a desktop helper app that enables Sambee to connect from the browser to local drives on your computer and to open files in natively installed desktop apps.\n\nYou do not need Companion for accessing SMB shares from the browser.\n\n## Install Companion\n\n1. Open **Settings** \u003e **Local Drives** and select **Download for this computer** to download the Companion installer.\n1. Run the installer and follow the prompts. Make sure to enable auto-starting Companion.\n1. Once the installer is completed, Companion should be running.\n1. You can find the Companion icon in the system tray (Linux, Windows) or the menu bar (macOS).\n\n## Pair This Browser With Companion\n\n{{\u003c admonition type=\"note\" title=\"\" \u003e}}\nDuring pairing, Sambee and Companion exchange data that is needed to establish a secure connection. The concept is similar in nature to Bluetooth pairing.\n{{\u003c /admonition \u003e}}\n\nOpen **Settings** \u003e **Local Drives**. Sambee checks whether it can find the Companion app. You should see a check mark next to **Companion app is running**.\n\nSelect **Pair this browser**. Sambee and Companion both display a verification code. Confirm that both codes match, then finish pairing. Sambee should now show a check mark next to **This browser is paired**.\n\nPairing is scoped to the current browser origin and browser profile, not to the whole computer. If you use Sambee from a different browser, a different browser profile, or a different Sambee site origin, approve that browser separately.\n\nOnce this browser is paired with Companion, local drives on your computer appear in Sambee's connection list.\n", "0.8": "+++\ntitle = \"Install and Pair the Companion App\"\n+++\n\nSambee Companion is a desktop helper app that enables Sambee to connect from the browser to local drives on your computer and to open files in natively installed desktop apps.\n\nYou do not need Companion for accessing SMB shares from the browser.\n\n## Install Companion\n\n1. Open **Settings** \u003e **Local Drives** and select **Download for this computer** to download the Companion installer.\n1. Run the installer and follow the prompts. Make sure to enable auto-starting Companion.\n1. Once the installer is completed, Companion should be running.\n1. You can find the Companion icon in the system tray (Linux, Windows) or the menu bar (macOS).\n\n## Pair Sambee With Companion\n\n{{\u003c admonition type=\"note\" title=\"\" \u003e}}\nDuring pairing, Sambee and Companion exchange data that is needed to establish a secure connection. The concept is similar in nature to Bluetooth pairing.\n{{\u003c /admonition \u003e}}\n\nOpen **Settings** \u003e **Local Drives**. Sambee checks whether it can find the Companion app. You should see a check mark next to **Companion app is running**.\n\nSelect **Pair this browser**. Sambee starts a pairing request for the exact site you are currently using, and Companion opens a native approval window that shows both:\n\n- the requesting browser origin\n- a short verification code\n\nSambee shows the same verification code in the browser. Confirm the pairing only when both codes match and the origin shown in Companion is the Sambee site you expect.\n\nAfter you approve the request in Companion and confirm it in the browser, Sambee should show a check mark next to **This browser is paired**.\n\nOnce Sambee is paired with Companion, local drives on your computer appear in Sambee's connection list.\n\n## What to Expect Later\n\nPairing is specific to the current browser origin.\n\n- If you use Sambee from a different site or port, that browser origin may need its own pairing.\n- If you close the pairing dialog before finishing, the request is cancelled instead of staying pending silently.\n- If Sambee later reports that the browser needs repair, start pairing again from **Settings** \u003e **Local Drives** to restore the browser-side secret.\n", "0.9": "+++\ntitle = \"Install and Pair the Companion App\"\n+++\n\nSambee Companion is a desktop helper app that enables Sambee to connect from the browser to local drives on your computer and to open files in natively installed desktop apps.\n\nYou do not need Companion for accessing SMB shares from the browser.\n\n## Install Companion\n\n1. Open **Settings** \u003e **Local Drives** and select **Download for this computer** to download the Companion installer.\n1. Run the installer and follow the prompts. Make sure to enable auto-starting Companion.\n1. Once the installer is completed, Companion should be running.\n1. You can find the Companion icon in the system tray (Linux, Windows) or the menu bar (macOS).\n\n## Pair Sambee With Companion\n\n{{\u003c admonition type=\"note\" title=\"\" \u003e}}\nDuring pairing, Sambee and Companion exchange data that is needed to establish a secure connection. The concept is similar in nature to Bluetooth pairing.\n{{\u003c /admonition \u003e}}\n\nOpen **Settings** \u003e **Local Drives**. Sambee checks whether it can find the Companion app. You should see a check mark next to **Companion app is running**.\n\nSelect **Pair this browser**. Sambee starts a pairing request for the exact site you are currently using, and Companion opens a native approval window that shows both:\n\n- the requesting browser origin\n- a short verification code\n\nSambee shows the same verification code in the browser. Confirm the pairing only when both codes match and the origin shown in Companion is the Sambee site you expect.\n\nAfter you approve the request in Companion and confirm it in the browser, Sambee should show a check mark next to **This browser is paired**.\n\nOnce Sambee is paired with Companion, local drives on your computer appear in Sambee's connection list.\n\n## What to Expect Later\n\nPairing is specific to the current browser origin.\n\n- If you use Sambee from a different site or port, that browser origin may need its own pairing.\n- If you close the pairing dialog before finishing, the request is cancelled instead of staying pending silently.\n- If Sambee later reports that the browser needs repair, start pairing again from **Settings** \u003e **Local Drives** to restore the browser-side secret.\n", "1.0": "+++\ntitle = \"Install and Pair the Companion App\"\n+++\n\nSambee Companion is a desktop helper app that enables Sambee to connect from the browser to local drives on your computer and to open files in natively installed desktop apps.\n\nYou do not need Companion for accessing SMB shares from the browser.\n\n## Install Companion\n\n1. Open **Settings** \u003e **Local Drives** and select **Download for this computer** to download the Companion installer.\n1. Run the installer and follow the prompts. Make sure to enable auto-starting Companion.\n1. Once the installer is completed, Companion should be running.\n1. You can find the Companion icon in the system tray (Linux, Windows) or the menu bar (macOS).\n\n## Pair Sambee With Companion\n\n{{\u003c admonition type=\"note\" title=\"\" \u003e}}\nDuring pairing, Sambee and Companion exchange data that is needed to establish a secure connection. The concept is similar in nature to Bluetooth pairing.\n{{\u003c /admonition \u003e}}\n\nOpen **Settings** \u003e **Local Drives**. Sambee checks whether it can find the Companion app. You should see a check mark next to **Companion app is running**.\n\nSelect **Pair this browser**. Sambee starts a pairing request for the exact site you are currently using, and Companion opens a native approval window that shows both:\n\n- the requesting browser origin\n- a short verification code\n\nSambee shows the same verification code in the browser. Confirm the pairing only when both codes match and the origin shown in Companion is the Sambee site you expect.\n\nAfter you approve the request in Companion and confirm it in the browser, Sambee should show a check mark next to **This browser is paired**.\n\nOnce Sambee is paired with Companion, local drives on your computer appear in Sambee's connection list.\n\n## What to Expect Later\n\nPairing is specific to the current browser origin.\n\n- If you use Sambee from a different site or port, that browser origin may need its own pairing.\n- If you close the pairing dialog before finishing, the request is cancelled instead of staying pending silently.\n- If Sambee later reports that the browser needs repair, start pairing again from **Settings** \u003e **Local Drives** to restore the browser-side secret.\n", "2.0": "+++\ntitle = \"Install and Pair the Companion App\"\n+++\n\nSambee Companion is a desktop helper app that enables Sambee to connect from the browser to local drives on your computer and to open files in natively installed desktop apps.\n\nYou do not need Companion for accessing SMB shares from the browser.\n\n## Install Companion\n\n1. Open **Settings** \u003e **Local Drives** and select **Download for this computer** to download the Companion installer.\n1. Run the installer and follow the prompts. Make sure to enable auto-starting Companion.\n1. Once the installer is completed, Companion should be running.\n1. You can find the Companion icon in the system tray (Linux, Windows) or the menu bar (macOS).\n\n## Pair Sambee With Companion\n\nOpen Sambee over HTTPS before pairing from another computer or a network address. Browsers don't provide the cryptographic APIs needed by Companion on ordinary HTTP sites. Local development on `http://localhost` is an exception. If **Local Drives** warns that a secure browser context with Web Crypto support is unavailable, use HTTPS; if you're already using HTTPS, check that your browser supports and permits Web Crypto. You don't need HTTPS to download the Companion installer.\n\n{{\u003c admonition type=\"note\" title=\"\" \u003e}}\nDuring pairing, Sambee and Companion exchange data that is needed to establish a secure connection. The concept is similar in nature to Bluetooth pairing.\n{{\u003c /admonition \u003e}}\n\nOpen **Settings** \u003e **Local Drives**. Sambee checks whether it can find the Companion app. You should see a check mark next to **Companion app is running**.\n\nSelect **Pair this browser**. Sambee starts a pairing request for the exact site you are currently using, and Companion opens a native approval window that shows both:\n\n- the requesting browser origin\n- a short verification code\n\nSambee shows the same verification code in the browser. Confirm the pairing only when both codes match and the origin shown in Companion is the Sambee site you expect.\n\nAfter you approve the request in Companion and confirm it in the browser, Sambee verifies local access and shows a check mark next to **This browser is paired**.\n\nOnce Sambee is paired with Companion, local drives on your computer appear in Sambee's connection list.\n\n## What to Expect Later\n\nPairing is specific to the current browser origin.\n\n- If you use Sambee from a different site or port, that browser origin may need its own pairing.\n- If you close the pairing dialog before finishing, the request is cancelled instead of staying pending silently.\n\n## Restore Local-Drive Access\n\nIf a local drive reports a pairing error, open **Settings** \u003e **Local Drives** from the file-list alert. **Ready** means the browser has passed an authenticated pairing check; having a stored pairing alone is not enough.\n\n1. If Companion needs an update, install the available version, restart Companion, and reload the Sambee page. Re-pairing will not resolve an incompatible version.\n1. If Sambee needs an update, reload the page. If the version mismatch remains, update Sambee. Updating Companion or re-pairing will not fix a newer Companion protocol.\n1. If the file-list alert says this browser isn't paired, open **Local Drives** and select **Pair This Browser**. Reloading alone won't restore a missing or removed pairing.\n1. If Companion rejects the browser's signature, reload the Sambee page first. A page left open across an update may still use the previous authentication protocol.\n1. Run **Test Current Pairing**. If it still fails with a signature error after reloading, use **Pair This Browser** and approve the new code in Companion.\n\nIf Sambee cannot check the pairing status, select **Retry**. Wait for a confirmed status before starting a new pairing. Companion pairing secrets do not expire on a 30-day timer. An unavailable Companion or a temporary failed check does not mean you need to re-pair.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Install and Pair the Companion App\"\n+++\n\nSambee Companion is a desktop helper app that enables Sambee to connect from the browser to local drives on your computer and to open files in natively installed desktop apps.\n\nYou do not need Companion for accessing SMB shares from the browser.\n\n## Install Companion\n\n1. Open **Settings** \u003e **Local Drives** and select **Download for this computer** to download the Companion installer.\n1. Run the installer and follow the prompts. Make sure to enable auto-starting Companion.\n1. Once the installer is completed, Companion should be running.\n1. You can find the Companion icon in the system tray (Linux, Windows) or the menu bar (macOS).\n\n## Pair This Browser With Companion\n\n{{\u003c admonition type=\"note\" title=\"\" \u003e}}\nDuring pairing, Sambee and Companion exchange data that is needed to establish a secure connection. The concept is similar in nature to Bluetooth pairing.\n{{\u003c /admonition \u003e}}\n\nOpen **Settings** \u003e **Local Drives**. Sambee checks whether it can find the Companion app. You should see a check mark next to **Companion app is running**.\n\nSelect **Pair this browser**. Sambee and Companion both display a verification code. Confirm that both codes match, then finish pairing. Sambee should now show a check mark next to **This browser is paired**.\n\nPairing is scoped to the current browser origin and browser profile, not to the whole computer. If you use Sambee from a different browser, a different browser profile, or a different Sambee site origin, approve that browser separately.\n\nOnce this browser is paired with Companion, local drives on your computer appear in Sambee's connection list.\n", "0.8": "+++\ntitle = \"Install and Pair the Companion App\"\n+++\n\nSambee Companion is a desktop helper app that enables Sambee to connect from the browser to local drives on your computer and to open files in natively installed desktop apps.\n\nYou do not need Companion for accessing SMB shares from the browser.\n\n## Install Companion\n\n1. Open **Settings** \u003e **Local Drives** and select **Download for this computer** to download the Companion installer.\n1. Run the installer and follow the prompts. Make sure to enable auto-starting Companion.\n1. Once the installer is completed, Companion should be running.\n1. You can find the Companion icon in the system tray (Linux, Windows) or the menu bar (macOS).\n\n## Pair Sambee With Companion\n\n{{\u003c admonition type=\"note\" title=\"\" \u003e}}\nDuring pairing, Sambee and Companion exchange data that is needed to establish a secure connection. The concept is similar in nature to Bluetooth pairing.\n{{\u003c /admonition \u003e}}\n\nOpen **Settings** \u003e **Local Drives**. Sambee checks whether it can find the Companion app. You should see a check mark next to **Companion app is running**.\n\nSelect **Pair this browser**. Sambee starts a pairing request for the exact site you are currently using, and Companion opens a native approval window that shows both:\n\n- the requesting browser origin\n- a short verification code\n\nSambee shows the same verification code in the browser. Confirm the pairing only when both codes match and the origin shown in Companion is the Sambee site you expect.\n\nAfter you approve the request in Companion and confirm it in the browser, Sambee should show a check mark next to **This browser is paired**.\n\nOnce Sambee is paired with Companion, local drives on your computer appear in Sambee's connection list.\n\n## What to Expect Later\n\nPairing is specific to the current browser origin.\n\n- If you use Sambee from a different site or port, that browser origin may need its own pairing.\n- If you close the pairing dialog before finishing, the request is cancelled instead of staying pending silently.\n- If Sambee later reports that the browser needs repair, start pairing again from **Settings** \u003e **Local Drives** to restore the browser-side secret.\n", "0.9": "+++\ntitle = \"Install and Pair the Companion App\"\n+++\n\nSambee Companion is a desktop helper app that enables Sambee to connect from the browser to local drives on your computer and to open files in natively installed desktop apps.\n\nYou do not need Companion for accessing SMB shares from the browser.\n\n## Install Companion\n\n1. Open **Settings** \u003e **Local Drives** and select **Download for this computer** to download the Companion installer.\n1. Run the installer and follow the prompts. Make sure to enable auto-starting Companion.\n1. Once the installer is completed, Companion should be running.\n1. You can find the Companion icon in the system tray (Linux, Windows) or the menu bar (macOS).\n\n## Pair Sambee With Companion\n\n{{\u003c admonition type=\"note\" title=\"\" \u003e}}\nDuring pairing, Sambee and Companion exchange data that is needed to establish a secure connection. The concept is similar in nature to Bluetooth pairing.\n{{\u003c /admonition \u003e}}\n\nOpen **Settings** \u003e **Local Drives**. Sambee checks whether it can find the Companion app. You should see a check mark next to **Companion app is running**.\n\nSelect **Pair this browser**. Sambee starts a pairing request for the exact site you are currently using, and Companion opens a native approval window that shows both:\n\n- the requesting browser origin\n- a short verification code\n\nSambee shows the same verification code in the browser. Confirm the pairing only when both codes match and the origin shown in Companion is the Sambee site you expect.\n\nAfter you approve the request in Companion and confirm it in the browser, Sambee should show a check mark next to **This browser is paired**.\n\nOnce Sambee is paired with Companion, local drives on your computer appear in Sambee's connection list.\n\n## What to Expect Later\n\nPairing is specific to the current browser origin.\n\n- If you use Sambee from a different site or port, that browser origin may need its own pairing.\n- If you close the pairing dialog before finishing, the request is cancelled instead of staying pending silently.\n- If Sambee later reports that the browser needs repair, start pairing again from **Settings** \u003e **Local Drives** to restore the browser-side secret.\n", "1.0": "+++\ntitle = \"Install and Pair the Companion App\"\n+++\n\nSambee Companion is a desktop helper app that enables Sambee to connect from the browser to local drives on your computer and to open files in natively installed desktop apps.\n\nYou do not need Companion for accessing SMB shares from the browser.\n\n## Install Companion\n\n1. Open **Settings** \u003e **Local Drives** and select **Download for this computer** to download the Companion installer.\n1. Run the installer and follow the prompts. Make sure to enable auto-starting Companion.\n1. Once the installer is completed, Companion should be running.\n1. You can find the Companion icon in the system tray (Linux, Windows) or the menu bar (macOS).\n\n## Pair Sambee With Companion\n\n{{\u003c admonition type=\"note\" title=\"\" \u003e}}\nDuring pairing, Sambee and Companion exchange data that is needed to establish a secure connection. The concept is similar in nature to Bluetooth pairing.\n{{\u003c /admonition \u003e}}\n\nOpen **Settings** \u003e **Local Drives**. Sambee checks whether it can find the Companion app. You should see a check mark next to **Companion app is running**.\n\nSelect **Pair this browser**. Sambee starts a pairing request for the exact site you are currently using, and Companion opens a native approval window that shows both:\n\n- the requesting browser origin\n- a short verification code\n\nSambee shows the same verification code in the browser. Confirm the pairing only when both codes match and the origin shown in Companion is the Sambee site you expect.\n\nAfter you approve the request in Companion and confirm it in the browser, Sambee should show a check mark next to **This browser is paired**.\n\nOnce Sambee is paired with Companion, local drives on your computer appear in Sambee's connection list.\n\n## What to Expect Later\n\nPairing is specific to the current browser origin.\n\n- If you use Sambee from a different site or port, that browser origin may need its own pairing.\n- If you close the pairing dialog before finishing, the request is cancelled instead of staying pending silently.\n- If Sambee later reports that the browser needs repair, start pairing again from **Settings** \u003e **Local Drives** to restore the browser-side secret.\n", "2.0": "+++\ntitle = \"Install and Pair the Companion App\"\n+++\n\nSambee Companion is a desktop helper app that enables Sambee to connect from the browser to local drives on your computer and to open files in natively installed desktop apps.\n\nYou do not need Companion for accessing SMB shares from the browser.\n\n## Install Companion\n\n1. Open **Settings** \u003e **Local Drives** and select **Download for this computer** to download the Companion installer.\n1. Run the installer and follow the prompts. Make sure to enable auto-starting Companion.\n1. Once the installer is completed, Companion should be running.\n1. You can find the Companion icon in the system tray (Linux, Windows) or the menu bar (macOS).\n\n## Pair Sambee With Companion\n\nOpen Sambee over HTTPS before pairing from another computer or a network address. Browsers don't provide the cryptographic APIs needed by Companion on ordinary HTTP sites. Local development on `http://localhost` is an exception. If **Local Drives** warns that a secure browser context with Web Crypto support is unavailable, use HTTPS; if you're already using HTTPS, check that your browser supports and permits Web Crypto. You don't need HTTPS to download the Companion installer.\n\n{{\u003c admonition type=\"note\" title=\"\" \u003e}}\nDuring pairing, Sambee and Companion exchange data that is needed to establish a secure connection. The concept is similar in nature to Bluetooth pairing.\n{{\u003c /admonition \u003e}}\n\nOpen **Settings** \u003e **Local Drives**. Sambee checks whether it can find the Companion app. You should see a check mark next to **Companion app is running**.\n\nSelect **Pair this browser**. Sambee starts a pairing request for the exact site you are currently using, and Companion opens a native approval window that shows both:\n\n- the requesting browser origin\n- a short verification code\n\nSambee shows the same verification code in the browser. Confirm the pairing only when both codes match and the origin shown in Companion is the Sambee site you expect.\n\nAfter you approve the request in Companion and confirm it in the browser, Sambee verifies local access and shows a check mark next to **This browser is paired**.\n\nOnce Sambee is paired with Companion, local drives on your computer appear in Sambee's connection list.\n\n## What to Expect Later\n\nPairing is specific to the current browser origin.\n\n- If you use Sambee from a different site or port, that browser origin may need its own pairing.\n- If you close the pairing dialog before finishing, the request is cancelled instead of staying pending silently.\n\n## Restore Local-Drive Access\n\nIf a local drive reports a pairing error, open **Settings** \u003e **Local Drives** from the file-list alert. **Ready** means the browser has passed an authenticated pairing check; having a stored pairing alone is not enough.\n\n1. If Companion needs an update, install the available version, restart Companion, and reload the Sambee page. Re-pairing will not resolve an incompatible version.\n1. If Sambee needs an update, reload the page. If the version mismatch remains, update Sambee. Updating Companion or re-pairing will not fix a newer Companion protocol.\n1. If the file-list alert says this browser isn't paired, open **Local Drives** and select **Pair This Browser**. Reloading alone won't restore a missing or removed pairing.\n1. If Companion rejects the browser's signature, reload the Sambee page first. A page left open across an update may still use the previous authentication protocol.\n1. Run **Test Current Pairing**. If it still fails with a signature error after reloading, use **Pair This Browser** and approve the new code in Companion.\n\nIf Sambee cannot check the pairing status, select **Retry**. Wait for a confirmed status before starting a new pairing. Companion pairing secrets do not expire on a 30-day timer. An unavailable Companion or a temporary failed check does not mean you need to re-pair.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:user-guide/companion-app/desktop-app-picker", "parent_id": "section:user-guide/companion-app", "depth": 2, "kind": "page", "label": "desktop-app-picker", "title": "Desktop App Picker", "path": "user-guide/companion-app/desktop-app-picker", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Desktop App Picker\"\n+++\n\nThe app picker lets you choose which installed desktop app should open a file.\n\n## The App Picker\n\nWhen you use **Open in companion app**, Sambee hands the request to Companion. Companion then opens an app picker dialog that lists the installed apps registered for the selected file type.\n\nThe picker groups apps into these sections:\n\n- **Default**\n- **Suggested apps**\n- **More options**\n\n### Choose or Change the App\n\nTo continue:\n\n- Select the app you want.\n- Choose **Open**.\n\nYou can also use **Choose another app** to browse to a specific executable.\n\n### Remember the Selection\n\nIf you turn on **Always use this app** for a file type, Companion saves that executable as the preferred app for that extension.\n\nOn later opens, Companion still shows the picker, but it preselects the saved app for you. It does not silently skip the picker.\n\nIf you want to replace the remembered app for an extension, choose a different app and leave **Always use this app** turned on when you open it.\n", "0.8": "+++\ntitle = \"Desktop App Picker\"\n+++\n\nThe app picker lets you choose which installed desktop app should open a file.\n\n## The App Picker\n\nWhen you use **Open in companion app**, Sambee hands the request to Companion. Companion then opens an app picker dialog that lists the installed apps registered for the selected file type.\n\nThe picker groups apps into these sections:\n\n- **Default**\n- **Suggested apps**\n- **More options**\n\n### Choose or Change the App\n\nTo continue:\n\n- Select the app you want.\n- Choose **Open**.\n\nYou can also use **Choose another app** to browse to a specific executable.\n\n### Remember the Selection\n\nIf you turn on **Always use this app** for a file type, Companion saves that executable as the preferred app for that extension.\n\nOn later opens, Companion still shows the picker, but it preselects the saved app for you. It does not silently skip the picker.\n\nIf you want to replace the remembered app for an extension, choose a different app and leave **Always use this app** turned on when you open it.\n", "0.9": "+++\ntitle = \"Desktop App Picker\"\n+++\n\nThe app picker lets you choose which installed desktop app should open a file.\n\n## The App Picker\n\nWhen you use **Open in companion app**, Sambee hands the request to Companion. Companion then opens an app picker dialog that lists the installed apps registered for the selected file type.\n\nThe picker groups apps into these sections:\n\n- **Default**\n- **Suggested apps**\n- **More options**\n\n### Choose or Change the App\n\nTo continue:\n\n- Select the app you want.\n- Choose **Open**.\n\nYou can also use **Choose another app** to browse to a specific executable.\n\n### Remember the Selection\n\nIf you turn on **Always use this app** for a file type, Companion saves that executable as the preferred app for that extension.\n\nOn later opens, Companion still shows the picker, but it preselects the saved app for you. It does not silently skip the picker.\n\nIf you want to replace the remembered app for an extension, choose a different app and leave **Always use this app** turned on when you open it.\n", "1.0": "+++\ntitle = \"Desktop App Picker\"\n+++\n\nThe app picker lets you choose which installed desktop app should open a file.\n\n## The App Picker\n\nWhen you use **Open in companion app**, Sambee hands the request to Companion. Companion then opens an app picker dialog that lists the installed apps registered for the selected file type.\n\nThe picker groups apps into these sections:\n\n- **Default**\n- **Suggested apps**\n- **More options**\n\n### Choose or Change the App\n\nTo continue:\n\n- Select the app you want.\n- Choose **Open**.\n\nYou can also use **Choose another app** to browse to a specific executable.\n\n### Remember the Selection\n\nIf you turn on **Always use this app** for a file type, Companion saves that executable as the preferred app for that extension.\n\nOn later opens, Companion still shows the picker, but it preselects the saved app for you. It does not silently skip the picker.\n\nIf you want to replace the remembered app for an extension, choose a different app and leave **Always use this app** turned on when you open it.\n", "2.0": "+++\ntitle = \"Desktop App Picker\"\n+++\n\nThe app picker lets you choose which installed desktop app should open a file.\n\n## The App Picker\n\nWhen you use **Open in companion app**, Sambee hands the request to Companion. Companion then opens an app picker dialog that lists the installed apps registered for the selected file type.\n\nThe picker groups apps into these sections:\n\n- **Default**\n- **Suggested apps**\n- **More options**\n\n### Choose or Change the App\n\nTo continue:\n\n- Select the app you want.\n- Choose **Open**.\n\nYou can also use **Choose another app** to browse to a specific executable.\n\n### Remember the Selection\n\nIf you turn on **Always use this app** for a file type, Companion saves that executable as the preferred app for that extension.\n\nOn later opens, Companion still shows the picker, but it preselects the saved app for you. It does not silently skip the picker.\n\nIf you want to replace the remembered app for an extension, choose a different app and leave **Always use this app** turned on when you open it.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Desktop App Picker\"\n+++\n\nThe app picker lets you choose which installed desktop app should open a file.\n\n## The App Picker\n\nWhen you use **Open in companion app**, Sambee hands the request to Companion. Companion then opens an app picker dialog that lists the installed apps registered for the selected file type.\n\nThe picker groups apps into these sections:\n\n- **Default**\n- **Suggested apps**\n- **More options**\n\n### Choose or Change the App\n\nTo continue:\n\n- Select the app you want.\n- Choose **Open**.\n\nYou can also use **Choose another app** to browse to a specific executable.\n\n### Remember the Selection\n\nIf you turn on **Always use this app** for a file type, Companion saves that executable as the preferred app for that extension.\n\nOn later opens, Companion still shows the picker, but it preselects the saved app for you. It does not silently skip the picker.\n\nIf you want to replace the remembered app for an extension, choose a different app and leave **Always use this app** turned on when you open it.\n", "0.8": "+++\ntitle = \"Desktop App Picker\"\n+++\n\nThe app picker lets you choose which installed desktop app should open a file.\n\n## The App Picker\n\nWhen you use **Open in companion app**, Sambee hands the request to Companion. Companion then opens an app picker dialog that lists the installed apps registered for the selected file type.\n\nThe picker groups apps into these sections:\n\n- **Default**\n- **Suggested apps**\n- **More options**\n\n### Choose or Change the App\n\nTo continue:\n\n- Select the app you want.\n- Choose **Open**.\n\nYou can also use **Choose another app** to browse to a specific executable.\n\n### Remember the Selection\n\nIf you turn on **Always use this app** for a file type, Companion saves that executable as the preferred app for that extension.\n\nOn later opens, Companion still shows the picker, but it preselects the saved app for you. It does not silently skip the picker.\n\nIf you want to replace the remembered app for an extension, choose a different app and leave **Always use this app** turned on when you open it.\n", "0.9": "+++\ntitle = \"Desktop App Picker\"\n+++\n\nThe app picker lets you choose which installed desktop app should open a file.\n\n## The App Picker\n\nWhen you use **Open in companion app**, Sambee hands the request to Companion. Companion then opens an app picker dialog that lists the installed apps registered for the selected file type.\n\nThe picker groups apps into these sections:\n\n- **Default**\n- **Suggested apps**\n- **More options**\n\n### Choose or Change the App\n\nTo continue:\n\n- Select the app you want.\n- Choose **Open**.\n\nYou can also use **Choose another app** to browse to a specific executable.\n\n### Remember the Selection\n\nIf you turn on **Always use this app** for a file type, Companion saves that executable as the preferred app for that extension.\n\nOn later opens, Companion still shows the picker, but it preselects the saved app for you. It does not silently skip the picker.\n\nIf you want to replace the remembered app for an extension, choose a different app and leave **Always use this app** turned on when you open it.\n", "1.0": "+++\ntitle = \"Desktop App Picker\"\n+++\n\nThe app picker lets you choose which installed desktop app should open a file.\n\n## The App Picker\n\nWhen you use **Open in companion app**, Sambee hands the request to Companion. Companion then opens an app picker dialog that lists the installed apps registered for the selected file type.\n\nThe picker groups apps into these sections:\n\n- **Default**\n- **Suggested apps**\n- **More options**\n\n### Choose or Change the App\n\nTo continue:\n\n- Select the app you want.\n- Choose **Open**.\n\nYou can also use **Choose another app** to browse to a specific executable.\n\n### Remember the Selection\n\nIf you turn on **Always use this app** for a file type, Companion saves that executable as the preferred app for that extension.\n\nOn later opens, Companion still shows the picker, but it preselects the saved app for you. It does not silently skip the picker.\n\nIf you want to replace the remembered app for an extension, choose a different app and leave **Always use this app** turned on when you open it.\n", "2.0": "+++\ntitle = \"Desktop App Picker\"\n+++\n\nThe app picker lets you choose which installed desktop app should open a file.\n\n## The App Picker\n\nWhen you use **Open in companion app**, Sambee hands the request to Companion. Companion then opens an app picker dialog that lists the installed apps registered for the selected file type.\n\nThe picker groups apps into these sections:\n\n- **Default**\n- **Suggested apps**\n- **More options**\n\n### Choose or Change the App\n\nTo continue:\n\n- Select the app you want.\n- Choose **Open**.\n\nYou can also use **Choose another app** to browse to a specific executable.\n\n### Remember the Selection\n\nIf you turn on **Always use this app** for a file type, Companion saves that executable as the preferred app for that extension.\n\nOn later opens, Companion still shows the picker, but it preselects the saved app for you. It does not silently skip the picker.\n\nIf you want to replace the remembered app for an extension, choose a different app and leave **Always use this app** turned on when you open it.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:user-guide/troubleshooting", "parent_id": "book:user-guide", "depth": 1, "kind": "section", "label": "troubleshooting", "title": "Troubleshooting", "path": "user-guide/troubleshooting", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:user-guide/troubleshooting/common-user-problems", "parent_id": "section:user-guide/troubleshooting", "depth": 2, "kind": "page", "label": "common-user-problems", "title": "Common User Problems", "path": "user-guide/troubleshooting/common-user-problems", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "branched", "source_version": "0.7", "diff_added": 5, "diff_removed": 8}, "0.9": {"state": "inherited", "source_version": "0.8"}, "1.0": {"state": "inherited", "source_version": "0.8"}, "2.0": {"state": "inherited", "source_version": "0.8"}}, "content_versions": {"0.7": "+++\ntitle = \"Common User Problems\"\n+++\n\n## Local Drives Are Not Available\n\nLocal drives in the browser require a desktop browser, Sambee Companion, and a working browser pairing for the current browser profile.\n\nWork through this checklist:\n\n1. Confirm that you are using a desktop browser. Local-drive access is not available on iPhone, iPad, or Android browsers.\n1. Confirm that Sambee Companion is installed and running on the same computer as the browser.\n1. Open **Settings** \u003e **Local Drives** and check the current status.\n1. If the browser is not paired, start pairing again for this browser.\n1. If Local Drives reports that pairing needs repair, repair the pairing so Sambee can store a fresh browser-side secret.\n\nIf you still need the full setup flow, continue with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/) and [Access Local Drives](../../accessing-files/access-local-drives/).\n\n## Open in Desktop App Does Nothing\n\nThis usually means Sambee Companion is not running, or the browser blocked the handoff to the helper app.\n\nCheck these first:\n\n- Confirm that Sambee Companion is running on your computer.\n- Allow the browser to open the `sambee://` link if the browser asks for permission.\n- On Linux, confirm that the deep-link handler is registered with `xdg-mime query default x-scheme-handler/sambee`.\n\nStart with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/) if Companion may not be installed or running yet.\n\nNormal desktop-editing workflow: [Edit Files in Desktop Apps](../../viewing-and-editing-files/edit-files-in-desktop-apps/).\n\n## Changes Do Not Upload Back after Editing\n\nThe desktop-editing session may have expired or been interrupted.\n\nTypical signs are that the **Done Editing** window says the session expired, authentication failed, the lock was lost, or recovery is required.\n\nStart by reopening the file from Sambee so Companion can establish a fresh edit session and lock context.\n\nSee: [File Locking \u0026 Conflict Resolution](../../viewing-and-editing-files/file-locking-and-conflict-resolution/).\n", "0.8": "+++\ntitle = \"Common User Problems\"\n+++\n\n## Local Drives Are Not Available\n\nLocal drives in the browser require a desktop browser, Sambee Companion, and a working browser pairing.\n\nWork through this checklist:\n\n1. Confirm that you are using a desktop browser. Local-drive access is not available on iPhone, iPad, or Android browsers.\n1. Confirm that Sambee Companion is installed and running on the same computer as the browser.\n1. Open **Settings** \u003e **Local Drives** and check the current status.\n1. If Sambee shows **Waiting for approval**, finish or reject the request in the Companion pairing window.\n1. If Sambee shows that this browser needs repair, start pairing again to restore the browser-side secret.\n1. If you closed the pairing dialog earlier, start a new pairing request. Pending requests are cancelled when either side closes the pairing UI.\n\nIf you still need the full setup flow, continue with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/) and [Access Local Drives](../../accessing-files/access-local-drives/).\n\n## Open in Desktop App Does Nothing\n\nThis usually means Sambee Companion is not running, or the browser blocked the handoff to the helper app.\n\nCheck these first:\n\n- Confirm that Sambee Companion is running on your computer.\n- Allow the browser to open the `sambee://` link if the browser asks for permission.\n- On Linux, confirm that the deep-link handler is registered with `xdg-mime query default x-scheme-handler/sambee`.\n\nStart with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/) if Companion may not be installed or running yet.\n\nNormal desktop-editing workflow: [Edit Files in Desktop Apps](../../viewing-and-editing-files/edit-files-in-desktop-apps/).\n\n## Changes Do Not Upload Back after Editing\n\nThe Companion session may have been interrupted.\n\nSee: [File Locking \u0026 Conflict Resolution](../../viewing-and-editing-files/file-locking-and-conflict-resolution/).\n", "0.9": "+++\ntitle = \"Common User Problems\"\n+++\n\n## Local Drives Are Not Available\n\nLocal drives in the browser require a desktop browser, Sambee Companion, and a working browser pairing.\n\nWork through this checklist:\n\n1. Confirm that you are using a desktop browser. Local-drive access is not available on iPhone, iPad, or Android browsers.\n1. Confirm that Sambee Companion is installed and running on the same computer as the browser.\n1. Open **Settings** \u003e **Local Drives** and check the current status.\n1. If Sambee shows **Waiting for approval**, finish or reject the request in the Companion pairing window.\n1. If Sambee shows that this browser needs repair, start pairing again to restore the browser-side secret.\n1. If you closed the pairing dialog earlier, start a new pairing request. Pending requests are cancelled when either side closes the pairing UI.\n\nIf you still need the full setup flow, continue with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/) and [Access Local Drives](../../accessing-files/access-local-drives/).\n\n## Open in Desktop App Does Nothing\n\nThis usually means Sambee Companion is not running, or the browser blocked the handoff to the helper app.\n\nCheck these first:\n\n- Confirm that Sambee Companion is running on your computer.\n- Allow the browser to open the `sambee://` link if the browser asks for permission.\n- On Linux, confirm that the deep-link handler is registered with `xdg-mime query default x-scheme-handler/sambee`.\n\nStart with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/) if Companion may not be installed or running yet.\n\nNormal desktop-editing workflow: [Edit Files in Desktop Apps](../../viewing-and-editing-files/edit-files-in-desktop-apps/).\n\n## Changes Do Not Upload Back after Editing\n\nThe Companion session may have been interrupted.\n\nSee: [File Locking \u0026 Conflict Resolution](../../viewing-and-editing-files/file-locking-and-conflict-resolution/).\n", "1.0": "+++\ntitle = \"Common User Problems\"\n+++\n\n## Local Drives Are Not Available\n\nLocal drives in the browser require a desktop browser, Sambee Companion, and a working browser pairing.\n\nWork through this checklist:\n\n1. Confirm that you are using a desktop browser. Local-drive access is not available on iPhone, iPad, or Android browsers.\n1. Confirm that Sambee Companion is installed and running on the same computer as the browser.\n1. Open **Settings** \u003e **Local Drives** and check the current status.\n1. If Sambee shows **Waiting for approval**, finish or reject the request in the Companion pairing window.\n1. If Sambee shows that this browser needs repair, start pairing again to restore the browser-side secret.\n1. If you closed the pairing dialog earlier, start a new pairing request. Pending requests are cancelled when either side closes the pairing UI.\n\nIf you still need the full setup flow, continue with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/) and [Access Local Drives](../../accessing-files/access-local-drives/).\n\n## Open in Desktop App Does Nothing\n\nThis usually means Sambee Companion is not running, or the browser blocked the handoff to the helper app.\n\nCheck these first:\n\n- Confirm that Sambee Companion is running on your computer.\n- Allow the browser to open the `sambee://` link if the browser asks for permission.\n- On Linux, confirm that the deep-link handler is registered with `xdg-mime query default x-scheme-handler/sambee`.\n\nStart with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/) if Companion may not be installed or running yet.\n\nNormal desktop-editing workflow: [Edit Files in Desktop Apps](../../viewing-and-editing-files/edit-files-in-desktop-apps/).\n\n## Changes Do Not Upload Back after Editing\n\nThe Companion session may have been interrupted.\n\nSee: [File Locking \u0026 Conflict Resolution](../../viewing-and-editing-files/file-locking-and-conflict-resolution/).\n", "2.0": "+++\ntitle = \"Common User Problems\"\n+++\n\n## Local Drives Are Not Available\n\nLocal drives in the browser require a desktop browser, Sambee Companion, and a working browser pairing.\n\nWork through this checklist:\n\n1. Confirm that you are using a desktop browser. Local-drive access is not available on iPhone, iPad, or Android browsers.\n1. Confirm that Sambee Companion is installed and running on the same computer as the browser.\n1. Open **Settings** \u003e **Local Drives** and check the current status.\n1. If Sambee shows **Waiting for approval**, finish or reject the request in the Companion pairing window.\n1. If Sambee shows that this browser needs repair, start pairing again to restore the browser-side secret.\n1. If you closed the pairing dialog earlier, start a new pairing request. Pending requests are cancelled when either side closes the pairing UI.\n\nIf you still need the full setup flow, continue with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/) and [Access Local Drives](../../accessing-files/access-local-drives/).\n\n## Open in Desktop App Does Nothing\n\nThis usually means Sambee Companion is not running, or the browser blocked the handoff to the helper app.\n\nCheck these first:\n\n- Confirm that Sambee Companion is running on your computer.\n- Allow the browser to open the `sambee://` link if the browser asks for permission.\n- On Linux, confirm that the deep-link handler is registered with `xdg-mime query default x-scheme-handler/sambee`.\n\nStart with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/) if Companion may not be installed or running yet.\n\nNormal desktop-editing workflow: [Edit Files in Desktop Apps](../../viewing-and-editing-files/edit-files-in-desktop-apps/).\n\n## Changes Do Not Upload Back after Editing\n\nThe Companion session may have been interrupted.\n\nSee: [File Locking \u0026 Conflict Resolution](../../viewing-and-editing-files/file-locking-and-conflict-resolution/).\n"}, "page_contents": {"0.7": "+++\ntitle = \"Common User Problems\"\n+++\n\n## Local Drives Are Not Available\n\nLocal drives in the browser require a desktop browser, Sambee Companion, and a working browser pairing for the current browser profile.\n\nWork through this checklist:\n\n1. Confirm that you are using a desktop browser. Local-drive access is not available on iPhone, iPad, or Android browsers.\n1. Confirm that Sambee Companion is installed and running on the same computer as the browser.\n1. Open **Settings** \u003e **Local Drives** and check the current status.\n1. If the browser is not paired, start pairing again for this browser.\n1. If Local Drives reports that pairing needs repair, repair the pairing so Sambee can store a fresh browser-side secret.\n\nIf you still need the full setup flow, continue with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/) and [Access Local Drives](../../accessing-files/access-local-drives/).\n\n## Open in Desktop App Does Nothing\n\nThis usually means Sambee Companion is not running, or the browser blocked the handoff to the helper app.\n\nCheck these first:\n\n- Confirm that Sambee Companion is running on your computer.\n- Allow the browser to open the `sambee://` link if the browser asks for permission.\n- On Linux, confirm that the deep-link handler is registered with `xdg-mime query default x-scheme-handler/sambee`.\n\nStart with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/) if Companion may not be installed or running yet.\n\nNormal desktop-editing workflow: [Edit Files in Desktop Apps](../../viewing-and-editing-files/edit-files-in-desktop-apps/).\n\n## Changes Do Not Upload Back after Editing\n\nThe desktop-editing session may have expired or been interrupted.\n\nTypical signs are that the **Done Editing** window says the session expired, authentication failed, the lock was lost, or recovery is required.\n\nStart by reopening the file from Sambee so Companion can establish a fresh edit session and lock context.\n\nSee: [File Locking \u0026 Conflict Resolution](../../viewing-and-editing-files/file-locking-and-conflict-resolution/).\n", "0.8": "+++\ntitle = \"Common User Problems\"\n+++\n\n## Local Drives Are Not Available\n\nLocal drives in the browser require a desktop browser, Sambee Companion, and a working browser pairing.\n\nWork through this checklist:\n\n1. Confirm that you are using a desktop browser. Local-drive access is not available on iPhone, iPad, or Android browsers.\n1. Confirm that Sambee Companion is installed and running on the same computer as the browser.\n1. Open **Settings** \u003e **Local Drives** and check the current status.\n1. If Sambee shows **Waiting for approval**, finish or reject the request in the Companion pairing window.\n1. If Sambee shows that this browser needs repair, start pairing again to restore the browser-side secret.\n1. If you closed the pairing dialog earlier, start a new pairing request. Pending requests are cancelled when either side closes the pairing UI.\n\nIf you still need the full setup flow, continue with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/) and [Access Local Drives](../../accessing-files/access-local-drives/).\n\n## Open in Desktop App Does Nothing\n\nThis usually means Sambee Companion is not running, or the browser blocked the handoff to the helper app.\n\nCheck these first:\n\n- Confirm that Sambee Companion is running on your computer.\n- Allow the browser to open the `sambee://` link if the browser asks for permission.\n- On Linux, confirm that the deep-link handler is registered with `xdg-mime query default x-scheme-handler/sambee`.\n\nStart with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/) if Companion may not be installed or running yet.\n\nNormal desktop-editing workflow: [Edit Files in Desktop Apps](../../viewing-and-editing-files/edit-files-in-desktop-apps/).\n\n## Changes Do Not Upload Back after Editing\n\nThe Companion session may have been interrupted.\n\nSee: [File Locking \u0026 Conflict Resolution](../../viewing-and-editing-files/file-locking-and-conflict-resolution/).\n", "0.9": "+++\ntitle = \"Common User Problems\"\n+++\n\n## Local Drives Are Not Available\n\nLocal drives in the browser require a desktop browser, Sambee Companion, and a working browser pairing.\n\nWork through this checklist:\n\n1. Confirm that you are using a desktop browser. Local-drive access is not available on iPhone, iPad, or Android browsers.\n1. Confirm that Sambee Companion is installed and running on the same computer as the browser.\n1. Open **Settings** \u003e **Local Drives** and check the current status.\n1. If Sambee shows **Waiting for approval**, finish or reject the request in the Companion pairing window.\n1. If Sambee shows that this browser needs repair, start pairing again to restore the browser-side secret.\n1. If you closed the pairing dialog earlier, start a new pairing request. Pending requests are cancelled when either side closes the pairing UI.\n\nIf you still need the full setup flow, continue with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/) and [Access Local Drives](../../accessing-files/access-local-drives/).\n\n## Open in Desktop App Does Nothing\n\nThis usually means Sambee Companion is not running, or the browser blocked the handoff to the helper app.\n\nCheck these first:\n\n- Confirm that Sambee Companion is running on your computer.\n- Allow the browser to open the `sambee://` link if the browser asks for permission.\n- On Linux, confirm that the deep-link handler is registered with `xdg-mime query default x-scheme-handler/sambee`.\n\nStart with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/) if Companion may not be installed or running yet.\n\nNormal desktop-editing workflow: [Edit Files in Desktop Apps](../../viewing-and-editing-files/edit-files-in-desktop-apps/).\n\n## Changes Do Not Upload Back after Editing\n\nThe Companion session may have been interrupted.\n\nSee: [File Locking \u0026 Conflict Resolution](../../viewing-and-editing-files/file-locking-and-conflict-resolution/).\n", "1.0": "+++\ntitle = \"Common User Problems\"\n+++\n\n## Local Drives Are Not Available\n\nLocal drives in the browser require a desktop browser, Sambee Companion, and a working browser pairing.\n\nWork through this checklist:\n\n1. Confirm that you are using a desktop browser. Local-drive access is not available on iPhone, iPad, or Android browsers.\n1. Confirm that Sambee Companion is installed and running on the same computer as the browser.\n1. Open **Settings** \u003e **Local Drives** and check the current status.\n1. If Sambee shows **Waiting for approval**, finish or reject the request in the Companion pairing window.\n1. If Sambee shows that this browser needs repair, start pairing again to restore the browser-side secret.\n1. If you closed the pairing dialog earlier, start a new pairing request. Pending requests are cancelled when either side closes the pairing UI.\n\nIf you still need the full setup flow, continue with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/) and [Access Local Drives](../../accessing-files/access-local-drives/).\n\n## Open in Desktop App Does Nothing\n\nThis usually means Sambee Companion is not running, or the browser blocked the handoff to the helper app.\n\nCheck these first:\n\n- Confirm that Sambee Companion is running on your computer.\n- Allow the browser to open the `sambee://` link if the browser asks for permission.\n- On Linux, confirm that the deep-link handler is registered with `xdg-mime query default x-scheme-handler/sambee`.\n\nStart with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/) if Companion may not be installed or running yet.\n\nNormal desktop-editing workflow: [Edit Files in Desktop Apps](../../viewing-and-editing-files/edit-files-in-desktop-apps/).\n\n## Changes Do Not Upload Back after Editing\n\nThe Companion session may have been interrupted.\n\nSee: [File Locking \u0026 Conflict Resolution](../../viewing-and-editing-files/file-locking-and-conflict-resolution/).\n", "2.0": "+++\ntitle = \"Common User Problems\"\n+++\n\n## Local Drives Are Not Available\n\nLocal drives in the browser require a desktop browser, Sambee Companion, and a working browser pairing.\n\nWork through this checklist:\n\n1. Confirm that you are using a desktop browser. Local-drive access is not available on iPhone, iPad, or Android browsers.\n1. Confirm that Sambee Companion is installed and running on the same computer as the browser.\n1. Open **Settings** \u003e **Local Drives** and check the current status.\n1. If Sambee shows **Waiting for approval**, finish or reject the request in the Companion pairing window.\n1. If Sambee shows that this browser needs repair, start pairing again to restore the browser-side secret.\n1. If you closed the pairing dialog earlier, start a new pairing request. Pending requests are cancelled when either side closes the pairing UI.\n\nIf you still need the full setup flow, continue with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/) and [Access Local Drives](../../accessing-files/access-local-drives/).\n\n## Open in Desktop App Does Nothing\n\nThis usually means Sambee Companion is not running, or the browser blocked the handoff to the helper app.\n\nCheck these first:\n\n- Confirm that Sambee Companion is running on your computer.\n- Allow the browser to open the `sambee://` link if the browser asks for permission.\n- On Linux, confirm that the deep-link handler is registered with `xdg-mime query default x-scheme-handler/sambee`.\n\nStart with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/) if Companion may not be installed or running yet.\n\nNormal desktop-editing workflow: [Edit Files in Desktop Apps](../../viewing-and-editing-files/edit-files-in-desktop-apps/).\n\n## Changes Do Not Upload Back after Editing\n\nThe Companion session may have been interrupted.\n\nSee: [File Locking \u0026 Conflict Resolution](../../viewing-and-editing-files/file-locking-and-conflict-resolution/).\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:user-guide/reference", "parent_id": "book:user-guide", "depth": 1, "kind": "section", "label": "reference", "title": "Reference", "path": "user-guide/reference", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:user-guide/reference/supported-file-formats", "parent_id": "section:user-guide/reference", "depth": 2, "kind": "page", "label": "supported-file-formats", "title": "Supported File Formats", "path": "user-guide/reference/supported-file-formats", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "branched", "source_version": "0.7", "diff_added": 2, "diff_removed": 0}, "0.9": {"state": "inherited", "source_version": "0.8"}, "1.0": {"state": "branched", "source_version": "0.8", "diff_added": 11, "diff_removed": 3}, "2.0": {"state": "inherited", "source_version": "1.0"}}, "content_versions": {"0.7": "+++\ntitle = \"Supported File Formats\"\n+++\n\nThis page lists the file types Sambee can open in its viewers in the browser.\n\n## Overview\n\n| Category | Extensions | What to expect |\n|---|---|---|\n| Common browser image formats | `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`, `.svg`, `.avif` | Open in the image viewer with zoom, pan, and related controls. |\n| Converted image formats | `.tif`, `.tiff`, `.heic`, `.heif`, `.bmp`, `.dib`, `.ico`, `.cur`, `.pcx`, `.tga`, `.ppm`, `.pgm`, `.pbm`, `.pnm`, `.xbm`, `.xpm`, `.psd`, `.psb`, `.eps`, `.ai`, `.jp2`, `.j2k`, `.jpt`, `.j2c`, `.jpc`, `.jxl`, `.exr`, `.hdr`, `.fits`, `.fit`, `.fts`, `.svs`, `.ndpi`, `.scn`, `.mrxs`, `.vms`, `.vmu`, `.bif`, `.img`, `.mat` | Sambee converts the file into a browser-ready image before opening it in the image viewer. |\n| PDF | `.pdf` | Open in the PDF viewer with page navigation, search, zoom, and download support. |\n| Markdown | `.md`, `.markdown` | Open in a rendered Markdown view with an optional edit path. |\n\n## Format-Specific Notes\n\nSome converted image formats have specific behavior that is useful to know ahead of time.\n\n- CMYK images are converted to browser-safe sRGB.\n- Multi-page TIFF files open with the first page rather than every page in the source file.\n- PSD and PSB files show the flattened composite view, not interactive layer editing.\n- EPS and AI files are rendered into a high-quality raster image for viewing in the browser.\n- HDR formats such as EXR and Radiance HDR are tone-mapped for ordinary browser display.\n- Whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF open as an overview or first practical level rather than as a full microscopy workstation.\n- FITS and similar scientific-image files use visibility scaling so the content is inspectable in the browser.\n\n## When a File Type Is Not Supported or You Need the Original\n\nIf a file type is not supported by Sambee's viewers, or if you need the original editing experience, use one of the following:\n\n- Download the file.\n- Open it in a desktop app through Companion.\n\nFor the broader workflow explanation, see [View Images \u0026 Read Documents](../../viewing-and-editing-files/view-images-and-read-documents/).\n", "0.8": "+++\ntitle = \"Supported File Formats\"\n+++\n\nThis page lists the file types Sambee can open in its viewers in the browser.\n\n## Overview\n\n| Category | Extensions | What to expect |\n|---|---|---|\n| Common browser image formats | `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`, `.svg`, `.avif` | Open in the image viewer with zoom, pan, and related controls. |\n| Converted image formats | `.tif`, `.tiff`, `.heic`, `.heif`, `.bmp`, `.dib`, `.ico`, `.cur`, `.pcx`, `.tga`, `.ppm`, `.pgm`, `.pbm`, `.pnm`, `.xbm`, `.xpm`, `.psd`, `.psb`, `.eps`, `.ai`, `.jp2`, `.j2k`, `.jpt`, `.j2c`, `.jpc`, `.jxl`, `.exr`, `.hdr`, `.fits`, `.fit`, `.fts`, `.svs`, `.ndpi`, `.scn`, `.mrxs`, `.vms`, `.vmu`, `.bif`, `.img`, `.mat` | Sambee converts the file into a browser-ready image before opening it in the image viewer. |\n| PDF | `.pdf` | Open in the PDF viewer with page navigation, search, zoom, and download support. |\n| Markdown | `.md`, `.markdown` | Open in a rendered Markdown view with an optional edit path. |\n| Text and code with syntax highlighting | `.js`, `.mjs`, `.jsx`, `.ts`, `.tsx`, `.py`, `.java`, `.rb`, `.php`, `.go`, `.rs`, `.c`, `.h`, `.cpp`, `.cc`, `.cxx`, `.hpp`, `.cs`, `.html`, `.htm`, `.css`, `.scss`, `.sass`, `.json`, `.xml`, `.yaml`, `.yml`, `.toml`, `.ini`, `.sql`, `.sh`, `.bash`, `.ps1` | Open in the CodeMirror-based source editor with syntax highlighting. |\n| Text and code without syntax highlighting | `.txt`, `.conf`, `.log`, `.env`, `.bat`, `.cmd` | Open in the CodeMirror-based source editor as plain text. |\n\n## Format-Specific Notes\n\nSome converted image formats have specific behavior that is useful to know ahead of time.\n\n- CMYK images are converted to browser-safe sRGB.\n- Multi-page TIFF files open with the first page rather than every page in the source file.\n- PSD and PSB files show the flattened composite view, not interactive layer editing.\n- EPS and AI files are rendered into a high-quality raster image for viewing in the browser.\n- HDR formats such as EXR and Radiance HDR are tone-mapped for ordinary browser display.\n- Whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF open as an overview or first practical level rather than as a full microscopy workstation.\n- FITS and similar scientific-image files use visibility scaling so the content is inspectable in the browser.\n\n## When a File Type Is Not Supported or You Need the Original\n\nIf a file type is not supported by Sambee's viewers, or if you need the original editing experience, use one of the following:\n\n- Download the file.\n- Open it in a desktop app through Companion.\n\nFor the broader workflow explanation, see [View Images \u0026 Read Documents](../../viewing-and-editing-files/view-images-and-read-documents/).\n", "0.9": "+++\ntitle = \"Supported File Formats\"\n+++\n\nThis page lists the file types Sambee can open in its viewers in the browser.\n\n## Overview\n\n| Category | Extensions | What to expect |\n|---|---|---|\n| Common browser image formats | `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`, `.svg`, `.avif` | Open in the image viewer with zoom, pan, and related controls. |\n| Converted image formats | `.tif`, `.tiff`, `.heic`, `.heif`, `.bmp`, `.dib`, `.ico`, `.cur`, `.pcx`, `.tga`, `.ppm`, `.pgm`, `.pbm`, `.pnm`, `.xbm`, `.xpm`, `.psd`, `.psb`, `.eps`, `.ai`, `.jp2`, `.j2k`, `.jpt`, `.j2c`, `.jpc`, `.jxl`, `.exr`, `.hdr`, `.fits`, `.fit`, `.fts`, `.svs`, `.ndpi`, `.scn`, `.mrxs`, `.vms`, `.vmu`, `.bif`, `.img`, `.mat` | Sambee converts the file into a browser-ready image before opening it in the image viewer. |\n| PDF | `.pdf` | Open in the PDF viewer with page navigation, search, zoom, and download support. |\n| Markdown | `.md`, `.markdown` | Open in a rendered Markdown view with an optional edit path. |\n| Text and code with syntax highlighting | `.js`, `.mjs`, `.jsx`, `.ts`, `.tsx`, `.py`, `.java`, `.rb`, `.php`, `.go`, `.rs`, `.c`, `.h`, `.cpp`, `.cc`, `.cxx`, `.hpp`, `.cs`, `.html`, `.htm`, `.css`, `.scss`, `.sass`, `.json`, `.xml`, `.yaml`, `.yml`, `.toml`, `.ini`, `.sql`, `.sh`, `.bash`, `.ps1` | Open in the CodeMirror-based source editor with syntax highlighting. |\n| Text and code without syntax highlighting | `.txt`, `.conf`, `.log`, `.env`, `.bat`, `.cmd` | Open in the CodeMirror-based source editor as plain text. |\n\n## Format-Specific Notes\n\nSome converted image formats have specific behavior that is useful to know ahead of time.\n\n- CMYK images are converted to browser-safe sRGB.\n- Multi-page TIFF files open with the first page rather than every page in the source file.\n- PSD and PSB files show the flattened composite view, not interactive layer editing.\n- EPS and AI files are rendered into a high-quality raster image for viewing in the browser.\n- HDR formats such as EXR and Radiance HDR are tone-mapped for ordinary browser display.\n- Whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF open as an overview or first practical level rather than as a full microscopy workstation.\n- FITS and similar scientific-image files use visibility scaling so the content is inspectable in the browser.\n\n## When a File Type Is Not Supported or You Need the Original\n\nIf a file type is not supported by Sambee's viewers, or if you need the original editing experience, use one of the following:\n\n- Download the file.\n- Open it in a desktop app through Companion.\n\nFor the broader workflow explanation, see [View Images \u0026 Read Documents](../../viewing-and-editing-files/view-images-and-read-documents/).\n", "1.0": "+++\ntitle = \"Supported File Formats\"\n+++\n\nThis page lists the file types Sambee can process, open or edit in its browser-based UI.\n\n## Viewers and Editors\n\n| Category | Extensions | What to expect |\n|---|---|---|\n| Common browser image formats | `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`, `.svg`, `.avif` | Open in the image viewer with zoom, pan, and related controls. |\n| Converted image formats | `.tif`, `.tiff`, `.heic`, `.heif`, `.bmp`, `.dib`, `.ico`, `.cur`, `.pcx`, `.tga`, `.ppm`, `.pgm`, `.pbm`, `.pnm`, `.xbm`, `.xpm`, `.psd`, `.psb`, `.eps`, `.ai`, `.jp2`, `.j2k`, `.jpt`, `.j2c`, `.jpc`, `.jxl`, `.exr`, `.hdr`, `.fits`, `.fit`, `.fts`, `.svs`, `.ndpi`, `.scn`, `.mrxs`, `.vms`, `.vmu`, `.bif`, `.img`, `.mat` | Sambee converts the file into a browser-ready image before opening it in the image viewer. |\n| PDF | `.pdf` | Open in the PDF viewer with page navigation, search, zoom, and download support. |\n| Markdown | `.md`, `.markdown` | Open in a rendered Markdown view with an optional edit path. |\n| Text and code with syntax highlighting | `.js`, `.mjs`, `.jsx`, `.ts`, `.tsx`, `.py`, `.java`, `.rb`, `.php`, `.go`, `.rs`, `.c`, `.h`, `.cpp`, `.cc`, `.cxx`, `.hpp`, `.cs`, `.html`, `.htm`, `.css`, `.scss`, `.sass`, `.json`, `.xml`, `.yaml`, `.yml`, `.toml`, `.ini`, `.sql`, `.sh`, `.bash`, `.ps1` | Open in the CodeMirror-based source editor with syntax highlighting. |\n| Text and code without syntax highlighting | `.txt`, `.conf`, `.log`, `.env`, `.bat`, `.cmd` | Open in the CodeMirror-based source editor as plain text. |\n\n### Format-Specific Notes\n\nSome converted image formats have specific behavior that is useful to know ahead of time.\n\n- CMYK images are converted to browser-safe sRGB.\n- Multi-page TIFF files open with the first page rather than every page in the source file.\n- PSD and PSB files show the flattened composite view, not interactive layer editing.\n- EPS and AI files are rendered into a high-quality raster image for viewing in the browser.\n- HDR formats such as EXR and Radiance HDR are tone-mapped for ordinary browser display.\n- Whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF open as an overview or first practical level rather than as a full microscopy workstation.\n- FITS and similar scientific-image files use visibility scaling so the content is inspectable in the browser.\n\n## Archive Formats\n\nSambee can browse and extract `.zip` archives.\n\n| Archive format | Supported compression methods | Notes |\n|---|---|---|\n| ZIP | Stored, Deflate, BZIP2 | ZIP64 archives are supported. Entries that use other compression methods can't be opened or extracted. |\n\n## When a File Type Is Not Supported or You Need the Original\n\nIf a file type is not supported by Sambee's viewers, or if you need the original editing experience, use one of the following:\n\n- Download the file.\n- Open it in a desktop app through Companion.\n\nFor the broader workflow explanation, see [View Images \u0026 Read Documents](../../viewing-and-editing-files/view-images-and-read-documents/).\n", "2.0": "+++\ntitle = \"Supported File Formats\"\n+++\n\nThis page lists the file types Sambee can process, open or edit in its browser-based UI.\n\n## Viewers and Editors\n\n| Category | Extensions | What to expect |\n|---|---|---|\n| Common browser image formats | `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`, `.svg`, `.avif` | Open in the image viewer with zoom, pan, and related controls. |\n| Converted image formats | `.tif`, `.tiff`, `.heic`, `.heif`, `.bmp`, `.dib`, `.ico`, `.cur`, `.pcx`, `.tga`, `.ppm`, `.pgm`, `.pbm`, `.pnm`, `.xbm`, `.xpm`, `.psd`, `.psb`, `.eps`, `.ai`, `.jp2`, `.j2k`, `.jpt`, `.j2c`, `.jpc`, `.jxl`, `.exr`, `.hdr`, `.fits`, `.fit`, `.fts`, `.svs`, `.ndpi`, `.scn`, `.mrxs`, `.vms`, `.vmu`, `.bif`, `.img`, `.mat` | Sambee converts the file into a browser-ready image before opening it in the image viewer. |\n| PDF | `.pdf` | Open in the PDF viewer with page navigation, search, zoom, and download support. |\n| Markdown | `.md`, `.markdown` | Open in a rendered Markdown view with an optional edit path. |\n| Text and code with syntax highlighting | `.js`, `.mjs`, `.jsx`, `.ts`, `.tsx`, `.py`, `.java`, `.rb`, `.php`, `.go`, `.rs`, `.c`, `.h`, `.cpp`, `.cc`, `.cxx`, `.hpp`, `.cs`, `.html`, `.htm`, `.css`, `.scss`, `.sass`, `.json`, `.xml`, `.yaml`, `.yml`, `.toml`, `.ini`, `.sql`, `.sh`, `.bash`, `.ps1` | Open in the CodeMirror-based source editor with syntax highlighting. |\n| Text and code without syntax highlighting | `.txt`, `.conf`, `.log`, `.env`, `.bat`, `.cmd` | Open in the CodeMirror-based source editor as plain text. |\n\n### Format-Specific Notes\n\nSome converted image formats have specific behavior that is useful to know ahead of time.\n\n- CMYK images are converted to browser-safe sRGB.\n- Multi-page TIFF files open with the first page rather than every page in the source file.\n- PSD and PSB files show the flattened composite view, not interactive layer editing.\n- EPS and AI files are rendered into a high-quality raster image for viewing in the browser.\n- HDR formats such as EXR and Radiance HDR are tone-mapped for ordinary browser display.\n- Whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF open as an overview or first practical level rather than as a full microscopy workstation.\n- FITS and similar scientific-image files use visibility scaling so the content is inspectable in the browser.\n\n## Archive Formats\n\nSambee can browse and extract `.zip` archives.\n\n| Archive format | Supported compression methods | Notes |\n|---|---|---|\n| ZIP | Stored, Deflate, BZIP2 | ZIP64 archives are supported. Entries that use other compression methods can't be opened or extracted. |\n\n## When a File Type Is Not Supported or You Need the Original\n\nIf a file type is not supported by Sambee's viewers, or if you need the original editing experience, use one of the following:\n\n- Download the file.\n- Open it in a desktop app through Companion.\n\nFor the broader workflow explanation, see [View Images \u0026 Read Documents](../../viewing-and-editing-files/view-images-and-read-documents/).\n"}, "page_contents": {"0.7": "+++\ntitle = \"Supported File Formats\"\n+++\n\nThis page lists the file types Sambee can open in its viewers in the browser.\n\n## Overview\n\n| Category | Extensions | What to expect |\n|---|---|---|\n| Common browser image formats | `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`, `.svg`, `.avif` | Open in the image viewer with zoom, pan, and related controls. |\n| Converted image formats | `.tif`, `.tiff`, `.heic`, `.heif`, `.bmp`, `.dib`, `.ico`, `.cur`, `.pcx`, `.tga`, `.ppm`, `.pgm`, `.pbm`, `.pnm`, `.xbm`, `.xpm`, `.psd`, `.psb`, `.eps`, `.ai`, `.jp2`, `.j2k`, `.jpt`, `.j2c`, `.jpc`, `.jxl`, `.exr`, `.hdr`, `.fits`, `.fit`, `.fts`, `.svs`, `.ndpi`, `.scn`, `.mrxs`, `.vms`, `.vmu`, `.bif`, `.img`, `.mat` | Sambee converts the file into a browser-ready image before opening it in the image viewer. |\n| PDF | `.pdf` | Open in the PDF viewer with page navigation, search, zoom, and download support. |\n| Markdown | `.md`, `.markdown` | Open in a rendered Markdown view with an optional edit path. |\n\n## Format-Specific Notes\n\nSome converted image formats have specific behavior that is useful to know ahead of time.\n\n- CMYK images are converted to browser-safe sRGB.\n- Multi-page TIFF files open with the first page rather than every page in the source file.\n- PSD and PSB files show the flattened composite view, not interactive layer editing.\n- EPS and AI files are rendered into a high-quality raster image for viewing in the browser.\n- HDR formats such as EXR and Radiance HDR are tone-mapped for ordinary browser display.\n- Whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF open as an overview or first practical level rather than as a full microscopy workstation.\n- FITS and similar scientific-image files use visibility scaling so the content is inspectable in the browser.\n\n## When a File Type Is Not Supported or You Need the Original\n\nIf a file type is not supported by Sambee's viewers, or if you need the original editing experience, use one of the following:\n\n- Download the file.\n- Open it in a desktop app through Companion.\n\nFor the broader workflow explanation, see [View Images \u0026 Read Documents](../../viewing-and-editing-files/view-images-and-read-documents/).\n", "0.8": "+++\ntitle = \"Supported File Formats\"\n+++\n\nThis page lists the file types Sambee can open in its viewers in the browser.\n\n## Overview\n\n| Category | Extensions | What to expect |\n|---|---|---|\n| Common browser image formats | `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`, `.svg`, `.avif` | Open in the image viewer with zoom, pan, and related controls. |\n| Converted image formats | `.tif`, `.tiff`, `.heic`, `.heif`, `.bmp`, `.dib`, `.ico`, `.cur`, `.pcx`, `.tga`, `.ppm`, `.pgm`, `.pbm`, `.pnm`, `.xbm`, `.xpm`, `.psd`, `.psb`, `.eps`, `.ai`, `.jp2`, `.j2k`, `.jpt`, `.j2c`, `.jpc`, `.jxl`, `.exr`, `.hdr`, `.fits`, `.fit`, `.fts`, `.svs`, `.ndpi`, `.scn`, `.mrxs`, `.vms`, `.vmu`, `.bif`, `.img`, `.mat` | Sambee converts the file into a browser-ready image before opening it in the image viewer. |\n| PDF | `.pdf` | Open in the PDF viewer with page navigation, search, zoom, and download support. |\n| Markdown | `.md`, `.markdown` | Open in a rendered Markdown view with an optional edit path. |\n| Text and code with syntax highlighting | `.js`, `.mjs`, `.jsx`, `.ts`, `.tsx`, `.py`, `.java`, `.rb`, `.php`, `.go`, `.rs`, `.c`, `.h`, `.cpp`, `.cc`, `.cxx`, `.hpp`, `.cs`, `.html`, `.htm`, `.css`, `.scss`, `.sass`, `.json`, `.xml`, `.yaml`, `.yml`, `.toml`, `.ini`, `.sql`, `.sh`, `.bash`, `.ps1` | Open in the CodeMirror-based source editor with syntax highlighting. |\n| Text and code without syntax highlighting | `.txt`, `.conf`, `.log`, `.env`, `.bat`, `.cmd` | Open in the CodeMirror-based source editor as plain text. |\n\n## Format-Specific Notes\n\nSome converted image formats have specific behavior that is useful to know ahead of time.\n\n- CMYK images are converted to browser-safe sRGB.\n- Multi-page TIFF files open with the first page rather than every page in the source file.\n- PSD and PSB files show the flattened composite view, not interactive layer editing.\n- EPS and AI files are rendered into a high-quality raster image for viewing in the browser.\n- HDR formats such as EXR and Radiance HDR are tone-mapped for ordinary browser display.\n- Whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF open as an overview or first practical level rather than as a full microscopy workstation.\n- FITS and similar scientific-image files use visibility scaling so the content is inspectable in the browser.\n\n## When a File Type Is Not Supported or You Need the Original\n\nIf a file type is not supported by Sambee's viewers, or if you need the original editing experience, use one of the following:\n\n- Download the file.\n- Open it in a desktop app through Companion.\n\nFor the broader workflow explanation, see [View Images \u0026 Read Documents](../../viewing-and-editing-files/view-images-and-read-documents/).\n", "0.9": "+++\ntitle = \"Supported File Formats\"\n+++\n\nThis page lists the file types Sambee can open in its viewers in the browser.\n\n## Overview\n\n| Category | Extensions | What to expect |\n|---|---|---|\n| Common browser image formats | `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`, `.svg`, `.avif` | Open in the image viewer with zoom, pan, and related controls. |\n| Converted image formats | `.tif`, `.tiff`, `.heic`, `.heif`, `.bmp`, `.dib`, `.ico`, `.cur`, `.pcx`, `.tga`, `.ppm`, `.pgm`, `.pbm`, `.pnm`, `.xbm`, `.xpm`, `.psd`, `.psb`, `.eps`, `.ai`, `.jp2`, `.j2k`, `.jpt`, `.j2c`, `.jpc`, `.jxl`, `.exr`, `.hdr`, `.fits`, `.fit`, `.fts`, `.svs`, `.ndpi`, `.scn`, `.mrxs`, `.vms`, `.vmu`, `.bif`, `.img`, `.mat` | Sambee converts the file into a browser-ready image before opening it in the image viewer. |\n| PDF | `.pdf` | Open in the PDF viewer with page navigation, search, zoom, and download support. |\n| Markdown | `.md`, `.markdown` | Open in a rendered Markdown view with an optional edit path. |\n| Text and code with syntax highlighting | `.js`, `.mjs`, `.jsx`, `.ts`, `.tsx`, `.py`, `.java`, `.rb`, `.php`, `.go`, `.rs`, `.c`, `.h`, `.cpp`, `.cc`, `.cxx`, `.hpp`, `.cs`, `.html`, `.htm`, `.css`, `.scss`, `.sass`, `.json`, `.xml`, `.yaml`, `.yml`, `.toml`, `.ini`, `.sql`, `.sh`, `.bash`, `.ps1` | Open in the CodeMirror-based source editor with syntax highlighting. |\n| Text and code without syntax highlighting | `.txt`, `.conf`, `.log`, `.env`, `.bat`, `.cmd` | Open in the CodeMirror-based source editor as plain text. |\n\n## Format-Specific Notes\n\nSome converted image formats have specific behavior that is useful to know ahead of time.\n\n- CMYK images are converted to browser-safe sRGB.\n- Multi-page TIFF files open with the first page rather than every page in the source file.\n- PSD and PSB files show the flattened composite view, not interactive layer editing.\n- EPS and AI files are rendered into a high-quality raster image for viewing in the browser.\n- HDR formats such as EXR and Radiance HDR are tone-mapped for ordinary browser display.\n- Whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF open as an overview or first practical level rather than as a full microscopy workstation.\n- FITS and similar scientific-image files use visibility scaling so the content is inspectable in the browser.\n\n## When a File Type Is Not Supported or You Need the Original\n\nIf a file type is not supported by Sambee's viewers, or if you need the original editing experience, use one of the following:\n\n- Download the file.\n- Open it in a desktop app through Companion.\n\nFor the broader workflow explanation, see [View Images \u0026 Read Documents](../../viewing-and-editing-files/view-images-and-read-documents/).\n", "1.0": "+++\ntitle = \"Supported File Formats\"\n+++\n\nThis page lists the file types Sambee can process, open or edit in its browser-based UI.\n\n## Viewers and Editors\n\n| Category | Extensions | What to expect |\n|---|---|---|\n| Common browser image formats | `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`, `.svg`, `.avif` | Open in the image viewer with zoom, pan, and related controls. |\n| Converted image formats | `.tif`, `.tiff`, `.heic`, `.heif`, `.bmp`, `.dib`, `.ico`, `.cur`, `.pcx`, `.tga`, `.ppm`, `.pgm`, `.pbm`, `.pnm`, `.xbm`, `.xpm`, `.psd`, `.psb`, `.eps`, `.ai`, `.jp2`, `.j2k`, `.jpt`, `.j2c`, `.jpc`, `.jxl`, `.exr`, `.hdr`, `.fits`, `.fit`, `.fts`, `.svs`, `.ndpi`, `.scn`, `.mrxs`, `.vms`, `.vmu`, `.bif`, `.img`, `.mat` | Sambee converts the file into a browser-ready image before opening it in the image viewer. |\n| PDF | `.pdf` | Open in the PDF viewer with page navigation, search, zoom, and download support. |\n| Markdown | `.md`, `.markdown` | Open in a rendered Markdown view with an optional edit path. |\n| Text and code with syntax highlighting | `.js`, `.mjs`, `.jsx`, `.ts`, `.tsx`, `.py`, `.java`, `.rb`, `.php`, `.go`, `.rs`, `.c`, `.h`, `.cpp`, `.cc`, `.cxx`, `.hpp`, `.cs`, `.html`, `.htm`, `.css`, `.scss`, `.sass`, `.json`, `.xml`, `.yaml`, `.yml`, `.toml`, `.ini`, `.sql`, `.sh`, `.bash`, `.ps1` | Open in the CodeMirror-based source editor with syntax highlighting. |\n| Text and code without syntax highlighting | `.txt`, `.conf`, `.log`, `.env`, `.bat`, `.cmd` | Open in the CodeMirror-based source editor as plain text. |\n\n### Format-Specific Notes\n\nSome converted image formats have specific behavior that is useful to know ahead of time.\n\n- CMYK images are converted to browser-safe sRGB.\n- Multi-page TIFF files open with the first page rather than every page in the source file.\n- PSD and PSB files show the flattened composite view, not interactive layer editing.\n- EPS and AI files are rendered into a high-quality raster image for viewing in the browser.\n- HDR formats such as EXR and Radiance HDR are tone-mapped for ordinary browser display.\n- Whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF open as an overview or first practical level rather than as a full microscopy workstation.\n- FITS and similar scientific-image files use visibility scaling so the content is inspectable in the browser.\n\n## Archive Formats\n\nSambee can browse and extract `.zip` archives.\n\n| Archive format | Supported compression methods | Notes |\n|---|---|---|\n| ZIP | Stored, Deflate, BZIP2 | ZIP64 archives are supported. Entries that use other compression methods can't be opened or extracted. |\n\n## When a File Type Is Not Supported or You Need the Original\n\nIf a file type is not supported by Sambee's viewers, or if you need the original editing experience, use one of the following:\n\n- Download the file.\n- Open it in a desktop app through Companion.\n\nFor the broader workflow explanation, see [View Images \u0026 Read Documents](../../viewing-and-editing-files/view-images-and-read-documents/).\n", "2.0": "+++\ntitle = \"Supported File Formats\"\n+++\n\nThis page lists the file types Sambee can process, open or edit in its browser-based UI.\n\n## Viewers and Editors\n\n| Category | Extensions | What to expect |\n|---|---|---|\n| Common browser image formats | `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`, `.svg`, `.avif` | Open in the image viewer with zoom, pan, and related controls. |\n| Converted image formats | `.tif`, `.tiff`, `.heic`, `.heif`, `.bmp`, `.dib`, `.ico`, `.cur`, `.pcx`, `.tga`, `.ppm`, `.pgm`, `.pbm`, `.pnm`, `.xbm`, `.xpm`, `.psd`, `.psb`, `.eps`, `.ai`, `.jp2`, `.j2k`, `.jpt`, `.j2c`, `.jpc`, `.jxl`, `.exr`, `.hdr`, `.fits`, `.fit`, `.fts`, `.svs`, `.ndpi`, `.scn`, `.mrxs`, `.vms`, `.vmu`, `.bif`, `.img`, `.mat` | Sambee converts the file into a browser-ready image before opening it in the image viewer. |\n| PDF | `.pdf` | Open in the PDF viewer with page navigation, search, zoom, and download support. |\n| Markdown | `.md`, `.markdown` | Open in a rendered Markdown view with an optional edit path. |\n| Text and code with syntax highlighting | `.js`, `.mjs`, `.jsx`, `.ts`, `.tsx`, `.py`, `.java`, `.rb`, `.php`, `.go`, `.rs`, `.c`, `.h`, `.cpp`, `.cc`, `.cxx`, `.hpp`, `.cs`, `.html`, `.htm`, `.css`, `.scss`, `.sass`, `.json`, `.xml`, `.yaml`, `.yml`, `.toml`, `.ini`, `.sql`, `.sh`, `.bash`, `.ps1` | Open in the CodeMirror-based source editor with syntax highlighting. |\n| Text and code without syntax highlighting | `.txt`, `.conf`, `.log`, `.env`, `.bat`, `.cmd` | Open in the CodeMirror-based source editor as plain text. |\n\n### Format-Specific Notes\n\nSome converted image formats have specific behavior that is useful to know ahead of time.\n\n- CMYK images are converted to browser-safe sRGB.\n- Multi-page TIFF files open with the first page rather than every page in the source file.\n- PSD and PSB files show the flattened composite view, not interactive layer editing.\n- EPS and AI files are rendered into a high-quality raster image for viewing in the browser.\n- HDR formats such as EXR and Radiance HDR are tone-mapped for ordinary browser display.\n- Whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF open as an overview or first practical level rather than as a full microscopy workstation.\n- FITS and similar scientific-image files use visibility scaling so the content is inspectable in the browser.\n\n## Archive Formats\n\nSambee can browse and extract `.zip` archives.\n\n| Archive format | Supported compression methods | Notes |\n|---|---|---|\n| ZIP | Stored, Deflate, BZIP2 | ZIP64 archives are supported. Entries that use other compression methods can't be opened or extracted. |\n\n## When a File Type Is Not Supported or You Need the Original\n\nIf a file type is not supported by Sambee's viewers, or if you need the original editing experience, use one of the following:\n\n- Download the file.\n- Open it in a desktop app through Companion.\n\nFor the broader workflow explanation, see [View Images \u0026 Read Documents](../../viewing-and-editing-files/view-images-and-read-documents/).\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "book:admin-guide", "parent_id": null, "depth": 0, "kind": "book", "label": "admin-guide", "title": "Admin Guide", "path": "admin-guide", "has_children": true, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "branched", "source_version": "0.7", "diff_added": 1, "diff_removed": 1}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "inherited", "source_version": "0.9"}}, "content_versions": {"0.7": "+++\ntitle = \"Admin Guide\"\n+++\n\nUse this guide to plan and deploy a Sambee service, configure storage, networking, and persistence, maintain it, and recover the deployment.\n\n## Start Here if You Want To\n\n- Understand what Sambee needs in order to run.\n- Deploy Sambee with Docker and persistent storage.\n- Place Sambee behind a reverse proxy for HTTPS or hostname-based access.\n- Handle routine operations such as logs, restarts, upgrades, and backups.\n\n## In This Guide\n\n- [Architecture Overview](./overview-and-planning/architecture-overview/): Understand how Sambee fits into your environment and what the deployment model looks like.\n- [Installation and Deployment](./installation-and-deployment/deploy-sambee-with-docker/): Follow the shortest path to a working deployment and first admin sign-in.\n- [Network and Reverse Proxy](./network-and-reverse-proxy/put-sambee-behind-a-reverse-proxy/): Configure HTTPS, hostnames, and reverse-proxy setup.\n- [Configuration](./configuration/configuration-key-reference/): Review the config keys admins most often change and follow the related path and persistence references.\n- [Operations and Maintenance](./operations-and-maintenance/view-logs-and-restart-services/): Handle logs, restarts, routine checks, upgrades, and backups.\n- [Reference](./reference/port-and-path-reference/): Check ports, paths, and companion-support lookup material.\n\n## Use the Right Guide\n\n- Use this Admin Guide for deployment, configuration, operations, and service recovery work.\n- Use the [User Guide](../user-guide/) when the next step belongs to the person using Sambee day to day.\n- Use the [Developer Guide](../developer-guide/) when the question becomes implementation-facing.\n\n", "0.8": "+++\ntitle = \"Admin Guide\"\n+++\n\nUse this guide to plan and deploy a Sambee service, configure storage, networking, and persistence, maintain it, and recover the deployment.\n\n## Start Here if You Want To\n\n- Understand what Sambee needs in order to run.\n- Deploy Sambee with Docker and persistent storage.\n- Place Sambee behind a reverse proxy for HTTPS or hostname-based access.\n- Handle routine operations such as logs, restarts, upgrades, and backups.\n\n## In This Guide\n\n- [Architecture Overview](./overview-and-planning/architecture-overview/): Understand how Sambee fits into your environment and what the deployment model looks like.\n- [Installation and Deployment](./installation-and-deployment/deploy-sambee-with-docker/): Follow the shortest path to a working deployment and first admin sign-in.\n- [Network and Reverse Proxy](./network-and-reverse-proxy/put-sambee-behind-a-reverse-proxy/): Configure HTTPS, hostnames, and reverse-proxy setup.\n- [Configuration](./configuration/configuration-key-reference/): Review the config keys admins most often change and follow the related path and persistence references.\n- [Operations and Maintenance](./operations-and-maintenance/view-logs-and-restart-services/): Handle logs, restarts, routine checks, upgrades, and backups.\n- [Reference](./reference/port-and-path-reference/): Check ports, paths, and companion-support lookup material.\n\n## Use the Right Guide\n\n- Use this Admin Guide for deployment, configuration, operations, and service recovery work.\n- Use the [User Guide](../user-guide/) when the next step belongs to the person using Sambee day to day.\n- Use the [Developer Guide](../developer-guide/) when the question becomes implementation-facing.\n\n", "0.9": "+++\ntitle = \"Admin Guide\"\n+++\n\nUse this guide to plan and deploy a Sambee service, configure storage, networking, and persistence, maintain it, and recover the deployment.\n\n## Start Here if You Want To\n\n- Understand what Sambee needs in order to run.\n- Deploy Sambee with Docker and persistent storage.\n- Place Sambee behind a reverse proxy for HTTPS or hostname-based access.\n- Handle routine operations such as logs, restarts, upgrades, and backups.\n\n## In This Guide\n\n- [Architecture Overview](./overview-and-planning/architecture-overview/): Understand how Sambee fits into your environment and what the deployment model looks like.\n- [Installation and Deployment](./installation-and-deployment/deploy-sambee-with-docker/): Follow the shortest path to a working deployment and first admin sign-in.\n- [Network and Reverse Proxy](./network-and-reverse-proxy/put-sambee-behind-a-reverse-proxy/): Configure HTTPS, hostnames, and reverse-proxy setup.\n- [Authentication](./authentication/authentication-overview/): Choose and operate local-password, OpenID Connect, or perimeter-trust access.\n- [Operations and Maintenance](./operations-and-maintenance/view-logs-and-restart-services/): Handle logs, restarts, routine checks, upgrades, and backups.\n- [Reference](./reference/port-and-path-reference/): Check ports, paths, and companion-support lookup material.\n\n## Use the Right Guide\n\n- Use this Admin Guide for deployment, configuration, operations, and service recovery work.\n- Use the [User Guide](../user-guide/) when the next step belongs to the person using Sambee day to day.\n- Use the [Developer Guide](../developer-guide/) when the question becomes implementation-facing.\n\n", "1.0": "+++\ntitle = \"Admin Guide\"\n+++\n\nUse this guide to plan and deploy a Sambee service, configure storage, networking, and persistence, maintain it, and recover the deployment.\n\n## Start Here if You Want To\n\n- Understand what Sambee needs in order to run.\n- Deploy Sambee with Docker and persistent storage.\n- Place Sambee behind a reverse proxy for HTTPS or hostname-based access.\n- Handle routine operations such as logs, restarts, upgrades, and backups.\n\n## In This Guide\n\n- [Architecture Overview](./overview-and-planning/architecture-overview/): Understand how Sambee fits into your environment and what the deployment model looks like.\n- [Installation and Deployment](./installation-and-deployment/deploy-sambee-with-docker/): Follow the shortest path to a working deployment and first admin sign-in.\n- [Network and Reverse Proxy](./network-and-reverse-proxy/put-sambee-behind-a-reverse-proxy/): Configure HTTPS, hostnames, and reverse-proxy setup.\n- [Authentication](./authentication/authentication-overview/): Choose and operate local-password, OpenID Connect, or perimeter-trust access.\n- [Operations and Maintenance](./operations-and-maintenance/view-logs-and-restart-services/): Handle logs, restarts, routine checks, upgrades, and backups.\n- [Reference](./reference/port-and-path-reference/): Check ports, paths, and companion-support lookup material.\n\n## Use the Right Guide\n\n- Use this Admin Guide for deployment, configuration, operations, and service recovery work.\n- Use the [User Guide](../user-guide/) when the next step belongs to the person using Sambee day to day.\n- Use the [Developer Guide](../developer-guide/) when the question becomes implementation-facing.\n\n", "2.0": "+++\ntitle = \"Admin Guide\"\n+++\n\nUse this guide to plan and deploy a Sambee service, configure storage, networking, and persistence, maintain it, and recover the deployment.\n\n## Start Here if You Want To\n\n- Understand what Sambee needs in order to run.\n- Deploy Sambee with Docker and persistent storage.\n- Place Sambee behind a reverse proxy for HTTPS or hostname-based access.\n- Handle routine operations such as logs, restarts, upgrades, and backups.\n\n## In This Guide\n\n- [Architecture Overview](./overview-and-planning/architecture-overview/): Understand how Sambee fits into your environment and what the deployment model looks like.\n- [Installation and Deployment](./installation-and-deployment/deploy-sambee-with-docker/): Follow the shortest path to a working deployment and first admin sign-in.\n- [Network and Reverse Proxy](./network-and-reverse-proxy/put-sambee-behind-a-reverse-proxy/): Configure HTTPS, hostnames, and reverse-proxy setup.\n- [Authentication](./authentication/authentication-overview/): Choose and operate local-password, OpenID Connect, or perimeter-trust access.\n- [Operations and Maintenance](./operations-and-maintenance/view-logs-and-restart-services/): Handle logs, restarts, routine checks, upgrades, and backups.\n- [Reference](./reference/port-and-path-reference/): Check ports, paths, and companion-support lookup material.\n\n## Use the Right Guide\n\n- Use this Admin Guide for deployment, configuration, operations, and service recovery work.\n- Use the [User Guide](../user-guide/) when the next step belongs to the person using Sambee day to day.\n- Use the [Developer Guide](../developer-guide/) when the question becomes implementation-facing.\n\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:admin-guide/overview-and-planning", "parent_id": "book:admin-guide", "depth": 1, "kind": "section", "label": "overview-and-planning", "title": "Overview and Planning", "path": "admin-guide/overview-and-planning", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:admin-guide/overview-and-planning/architecture-overview", "parent_id": "section:admin-guide/overview-and-planning", "depth": 2, "kind": "page", "label": "architecture-overview", "title": "Architecture Overview", "path": "admin-guide/overview-and-planning/architecture-overview", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Architecture Overview\"\n+++\n\nSambee has a deliberately simple architecture: a single container contains everything that is needed, plus - optionally - a reverse proxy.\n\n## Single Docker Container\n\nAt the center of a Sambee deployment is:\n\n- A container running the Sambee backend and serving the frontend via HTTP.\n- A local data directory holding the SQLite database and other persistent application state.\n- Network connectivity from the Sambee backend to the SMB shares you want to access through Sambee.\n\nBrowsers connect to Sambee either directly or through a reverse proxy.\n\n## What Is Required and What Is Optional\n\n| Component or concern | Required | Notes |\n|---|---|---|\n| Sambee application container | Yes | This is the web application users open in their browsers. |\n| Local persistent data directory | Yes | Stores the SQLite database and other data Sambee must keep across restarts. |\n| SMB connectivity | Yes | Sambee must be able to reach the SMB storage it presents to users. |\n| Reverse proxy | No | Add one when you need HTTPS, hostname routing, or controlled external access. |\n| Companion app on user desktops | No | Needed only for local-drive access and desktop-app editing workflows.\n", "0.8": "+++\ntitle = \"Architecture Overview\"\n+++\n\nSambee has a deliberately simple architecture: a single container contains everything that is needed, plus - optionally - a reverse proxy.\n\n## Single Docker Container\n\nAt the center of a Sambee deployment is:\n\n- A container running the Sambee backend and serving the frontend via HTTP.\n- A local data directory holding the SQLite database and other persistent application state.\n- Network connectivity from the Sambee backend to the SMB shares you want to access through Sambee.\n\nBrowsers connect to Sambee either directly or through a reverse proxy.\n\n## What Is Required and What Is Optional\n\n| Component or concern | Required | Notes |\n|---|---|---|\n| Sambee application container | Yes | This is the web application users open in their browsers. |\n| Local persistent data directory | Yes | Stores the SQLite database and other data Sambee must keep across restarts. |\n| SMB connectivity | Yes | Sambee must be able to reach the SMB storage it presents to users. |\n| Reverse proxy | No | Add one when you need HTTPS, hostname routing, or controlled external access. |\n| Companion app on user desktops | No | Needed only for local-drive access and desktop-app editing workflows.\n", "0.9": "+++\ntitle = \"Architecture Overview\"\n+++\n\nSambee has a deliberately simple architecture: a single container contains everything that is needed, plus - optionally - a reverse proxy.\n\n## Single Docker Container\n\nAt the center of a Sambee deployment is:\n\n- A container running the Sambee backend and serving the frontend via HTTP.\n- A local data directory holding the SQLite database and other persistent application state.\n- Network connectivity from the Sambee backend to the SMB shares you want to access through Sambee.\n\nBrowsers connect to Sambee either directly or through a reverse proxy.\n\n## What Is Required and What Is Optional\n\n| Component or concern | Required | Notes |\n|---|---|---|\n| Sambee application container | Yes | This is the web application users open in their browsers. |\n| Local persistent data directory | Yes | Stores the SQLite database and other data Sambee must keep across restarts. |\n| SMB connectivity | Yes | Sambee must be able to reach the SMB storage it presents to users. |\n| Reverse proxy | No | Add one when you need HTTPS, hostname routing, or controlled external access. |\n| Companion app on user desktops | No | Needed only for local-drive access and desktop-app editing workflows.\n", "1.0": "+++\ntitle = \"Architecture Overview\"\n+++\n\nSambee has a deliberately simple architecture: a single container contains everything that is needed, plus - optionally - a reverse proxy.\n\n## Single Docker Container\n\nAt the center of a Sambee deployment is:\n\n- A container running the Sambee backend and serving the frontend via HTTP.\n- A local data directory holding the SQLite database and other persistent application state.\n- Network connectivity from the Sambee backend to the SMB shares you want to access through Sambee.\n\nBrowsers connect to Sambee either directly or through a reverse proxy.\n\n## What Is Required and What Is Optional\n\n| Component or concern | Required | Notes |\n|---|---|---|\n| Sambee application container | Yes | This is the web application users open in their browsers. |\n| Local persistent data directory | Yes | Stores the SQLite database and other data Sambee must keep across restarts. |\n| SMB connectivity | Yes | Sambee must be able to reach the SMB storage it presents to users. |\n| Reverse proxy | No | Add one when you need HTTPS, hostname routing, or controlled external access. |\n| Companion app on user desktops | No | Needed only for local-drive access and desktop-app editing workflows.\n", "2.0": "+++\ntitle = \"Architecture Overview\"\n+++\n\nSambee has a deliberately simple architecture: a single container contains everything that is needed, plus - optionally - a reverse proxy.\n\n## Single Docker Container\n\nAt the center of a Sambee deployment is:\n\n- A container running the Sambee backend and serving the frontend via HTTP.\n- A local data directory holding the SQLite database and other persistent application state.\n- Network connectivity from the Sambee backend to the SMB shares you want to access through Sambee.\n\nBrowsers connect to Sambee either directly or through a reverse proxy.\n\n## What Is Required and What Is Optional\n\n| Component or concern | Required | Notes |\n|---|---|---|\n| Sambee application container | Yes | This is the web application users open in their browsers. |\n| Local persistent data directory | Yes | Stores the SQLite database and other data Sambee must keep across restarts. |\n| SMB connectivity | Yes | Sambee must be able to reach the SMB storage it presents to users. |\n| Reverse proxy | No | Add one when you need HTTPS, hostname routing, or controlled external access. |\n| Companion app on user desktops | No | Needed only for local-drive access and desktop-app editing workflows.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Architecture Overview\"\n+++\n\nSambee has a deliberately simple architecture: a single container contains everything that is needed, plus - optionally - a reverse proxy.\n\n## Single Docker Container\n\nAt the center of a Sambee deployment is:\n\n- A container running the Sambee backend and serving the frontend via HTTP.\n- A local data directory holding the SQLite database and other persistent application state.\n- Network connectivity from the Sambee backend to the SMB shares you want to access through Sambee.\n\nBrowsers connect to Sambee either directly or through a reverse proxy.\n\n## What Is Required and What Is Optional\n\n| Component or concern | Required | Notes |\n|---|---|---|\n| Sambee application container | Yes | This is the web application users open in their browsers. |\n| Local persistent data directory | Yes | Stores the SQLite database and other data Sambee must keep across restarts. |\n| SMB connectivity | Yes | Sambee must be able to reach the SMB storage it presents to users. |\n| Reverse proxy | No | Add one when you need HTTPS, hostname routing, or controlled external access. |\n| Companion app on user desktops | No | Needed only for local-drive access and desktop-app editing workflows.\n", "0.8": "+++\ntitle = \"Architecture Overview\"\n+++\n\nSambee has a deliberately simple architecture: a single container contains everything that is needed, plus - optionally - a reverse proxy.\n\n## Single Docker Container\n\nAt the center of a Sambee deployment is:\n\n- A container running the Sambee backend and serving the frontend via HTTP.\n- A local data directory holding the SQLite database and other persistent application state.\n- Network connectivity from the Sambee backend to the SMB shares you want to access through Sambee.\n\nBrowsers connect to Sambee either directly or through a reverse proxy.\n\n## What Is Required and What Is Optional\n\n| Component or concern | Required | Notes |\n|---|---|---|\n| Sambee application container | Yes | This is the web application users open in their browsers. |\n| Local persistent data directory | Yes | Stores the SQLite database and other data Sambee must keep across restarts. |\n| SMB connectivity | Yes | Sambee must be able to reach the SMB storage it presents to users. |\n| Reverse proxy | No | Add one when you need HTTPS, hostname routing, or controlled external access. |\n| Companion app on user desktops | No | Needed only for local-drive access and desktop-app editing workflows.\n", "0.9": "+++\ntitle = \"Architecture Overview\"\n+++\n\nSambee has a deliberately simple architecture: a single container contains everything that is needed, plus - optionally - a reverse proxy.\n\n## Single Docker Container\n\nAt the center of a Sambee deployment is:\n\n- A container running the Sambee backend and serving the frontend via HTTP.\n- A local data directory holding the SQLite database and other persistent application state.\n- Network connectivity from the Sambee backend to the SMB shares you want to access through Sambee.\n\nBrowsers connect to Sambee either directly or through a reverse proxy.\n\n## What Is Required and What Is Optional\n\n| Component or concern | Required | Notes |\n|---|---|---|\n| Sambee application container | Yes | This is the web application users open in their browsers. |\n| Local persistent data directory | Yes | Stores the SQLite database and other data Sambee must keep across restarts. |\n| SMB connectivity | Yes | Sambee must be able to reach the SMB storage it presents to users. |\n| Reverse proxy | No | Add one when you need HTTPS, hostname routing, or controlled external access. |\n| Companion app on user desktops | No | Needed only for local-drive access and desktop-app editing workflows.\n", "1.0": "+++\ntitle = \"Architecture Overview\"\n+++\n\nSambee has a deliberately simple architecture: a single container contains everything that is needed, plus - optionally - a reverse proxy.\n\n## Single Docker Container\n\nAt the center of a Sambee deployment is:\n\n- A container running the Sambee backend and serving the frontend via HTTP.\n- A local data directory holding the SQLite database and other persistent application state.\n- Network connectivity from the Sambee backend to the SMB shares you want to access through Sambee.\n\nBrowsers connect to Sambee either directly or through a reverse proxy.\n\n## What Is Required and What Is Optional\n\n| Component or concern | Required | Notes |\n|---|---|---|\n| Sambee application container | Yes | This is the web application users open in their browsers. |\n| Local persistent data directory | Yes | Stores the SQLite database and other data Sambee must keep across restarts. |\n| SMB connectivity | Yes | Sambee must be able to reach the SMB storage it presents to users. |\n| Reverse proxy | No | Add one when you need HTTPS, hostname routing, or controlled external access. |\n| Companion app on user desktops | No | Needed only for local-drive access and desktop-app editing workflows.\n", "2.0": "+++\ntitle = \"Architecture Overview\"\n+++\n\nSambee has a deliberately simple architecture: a single container contains everything that is needed, plus - optionally - a reverse proxy.\n\n## Single Docker Container\n\nAt the center of a Sambee deployment is:\n\n- A container running the Sambee backend and serving the frontend via HTTP.\n- A local data directory holding the SQLite database and other persistent application state.\n- Network connectivity from the Sambee backend to the SMB shares you want to access through Sambee.\n\nBrowsers connect to Sambee either directly or through a reverse proxy.\n\n## What Is Required and What Is Optional\n\n| Component or concern | Required | Notes |\n|---|---|---|\n| Sambee application container | Yes | This is the web application users open in their browsers. |\n| Local persistent data directory | Yes | Stores the SQLite database and other data Sambee must keep across restarts. |\n| SMB connectivity | Yes | Sambee must be able to reach the SMB storage it presents to users. |\n| Reverse proxy | No | Add one when you need HTTPS, hostname routing, or controlled external access. |\n| Companion app on user desktops | No | Needed only for local-drive access and desktop-app editing workflows.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:admin-guide/installation-and-deployment", "parent_id": "book:admin-guide", "depth": 1, "kind": "section", "label": "installation-and-deployment", "title": "Installation and Deployment", "path": "admin-guide/installation-and-deployment", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:admin-guide/installation-and-deployment/deploy-sambee-with-docker", "parent_id": "section:admin-guide/installation-and-deployment", "depth": 2, "kind": "page", "label": "deploy-sambee-with-docker", "title": "Deploy Sambee With Docker", "path": "admin-guide/installation-and-deployment/deploy-sambee-with-docker", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "branched", "source_version": "0.7", "diff_added": 1, "diff_removed": 8}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "branched", "source_version": "0.9", "diff_added": 1, "diff_removed": 1}}, "content_versions": {"0.7": "+++\ntitle = \"Deploy Sambee with Docker\"\n+++\n\n## Before You Start\n\nYou need:\n\n- Docker and `docker compose` installed.\n- A host that can reach the SMB file servers Sambee will use.\n- A deployment directory where you can keep local files such as `docker-compose.yml`, optional `config.toml`, and the persistent `data/` directory.\n\nYou do not need to clone the repository or build Sambee locally for a normal Docker deployment. Sambee publishes ready-to-run container images to GitHub Container Registry.\n\n## 1. Create a Deployment Directory\n\nCreate a dedicated directory for your local deployment files and move into it:\n\n```bash\nmkdir -p sambee\ncd sambee\n```\n\nThis directory will hold your Compose file, optional configuration file, and persistent application data.\n\n## 2. Prepare Persistent Storage\n\nCreate the local data directory and set ownership to user and group ID `1000`, which the containerized application uses:\n\n```bash\nmkdir -p ./data\nchown -Rfv 1000:1000 ./data\n```\n\nThis directory contains the Sambee database and other state that must survive restarts, rebuilds, and host reboots.\n\n## 3. Create the Compose File\n\nCreate `docker-compose.yml` with this content:\n\n```yaml\nservices:\n\tsambee:\n\t\timage: ghcr.io/helgeklein/sambee:stable\n\t\trestart: unless-stopped\n\t\tvolumes:\n\t\t\t- ./data:/app/data\n\t\t\t# Optional: uncomment when you create config.toml locally.\n\t\t\t# - ./config.toml:/app/config.toml:ro\n\t\tports:\n\t\t\t- 8000:8000\n```\n\n#### Select a Release Channel\n\nSambee has three different release channels. You select which to follow via the Docker image tag:\n\n- `stable` for the production channel.\n- `beta` for prerelease builds.\n- `test` for preview builds.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nWhile Sambee is in beta, the `stable` tag may not be available yet.\n{{\u003c /admonition \u003e}}\n\n## 4. Optional: Create a Local Configuration File\n\nYou do not need `config.toml` for a basic deployment. Create it only if you need to override defaults such as authentication, logging, or Companion download settings.\n\nCreate `config.toml` with only the settings you want to change. For example:\n\n```toml\n[app]\nlog_level = \"INFO\"\n\n[security]\nauth_method = \"password\"\n\n[admin]\nusername = \"admin\"\n```\n\nIf you create `config.toml`, uncomment the read-only bind mount in `docker-compose.yml`.\n\nKeep this file local. In production, mount it read-only.\n\n## 5. Pull and Start Sambee\n\nPull the configured image:\n\n```bash\ndocker compose pull\n```\n\nThen start the application:\n\n```bash\ndocker compose up -d\n```\n\nBy default, the service is available at:\n\n- Frontend: `http://localhost:8000`\n- Backend API: `http://localhost:8000/api`\n- API docs: `http://localhost:8000/docs`\n\n## Verify the Deployment\n\nBefore moving on, confirm that the deployment really came up cleanly.\n\n- The `docker compose ps` output shows the `sambee` service running.\n- The frontend URL responds on the expected host port.\n- The startup logs do not show an obvious failure loop.\n\nFor a quick log review:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\nOnce the deployment is healthy, continue with the first login procedure on the next page.\n", "0.8": "+++\ntitle = \"Deploy Sambee with Docker\"\n+++\n\n## Before You Start\n\nYou need:\n\n- Docker and `docker compose` installed.\n- A host that can reach the SMB file servers Sambee will use.\n- A deployment directory where you can keep local files such as `docker-compose.yml`, optional `config.toml`, and the persistent `data/` directory.\n\nYou do not need to clone the repository or build Sambee locally for a normal Docker deployment. Sambee publishes ready-to-run container images to GitHub Container Registry.\n\n## 1. Create a Deployment Directory\n\nCreate a dedicated directory for your local deployment files and move into it:\n\n```bash\nmkdir -p sambee\ncd sambee\n```\n\nThis directory will hold your Compose file, optional configuration file, and persistent application data.\n\n## 2. Prepare Persistent Storage\n\nCreate the local data directory and set ownership to user and group ID `1000`, which the containerized application uses:\n\n```bash\nmkdir -p ./data\nchown -Rfv 1000:1000 ./data\n```\n\nThis directory contains the Sambee database and other state that must survive restarts, rebuilds, and host reboots.\n\n## 3. Create the Compose File\n\nCreate `docker-compose.yml` with this content:\n\n```yaml\nservices:\n\tsambee:\n\t\timage: ghcr.io/helgeklein/sambee:stable\n\t\trestart: unless-stopped\n\t\tvolumes:\n\t\t\t- ./data:/app/data\n\t\t\t# Optional: uncomment when you create config.toml locally.\n\t\t\t# - ./config.toml:/app/config.toml:ro\n\t\tports:\n\t\t\t- 8000:8000\n```\n\n#### Select a Release Channel\n\nSambee has three different release channels. You select which to follow via the Docker image tag:\n\n- `stable` for the production channel.\n- `beta` for prerelease builds.\n- `test` for preview builds.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nWhile Sambee is in beta, the `stable` tag may not be available yet.\n{{\u003c /admonition \u003e}}\n\n## 4. Optional: Create a Local Configuration File\n\nYou do not need `config.toml` for a basic deployment. Create it only if you need to override defaults such as authentication, logging, or Companion download settings.\n\nCreate `config.toml` with only the settings you want to change. For example:\n\n```toml\n[app]\nlog_level = \"INFO\"\n\n[security]\nauth_method = \"password\"\n\n[admin]\nusername = \"admin\"\n```\n\nIf you create `config.toml`, uncomment the read-only bind mount in `docker-compose.yml`.\n\nKeep this file local. In production, mount it read-only.\n\n## 5. Pull and Start Sambee\n\nPull the configured image:\n\n```bash\ndocker compose pull\n```\n\nThen start the application:\n\n```bash\ndocker compose up -d\n```\n\nBy default, the service is available at:\n\n- Frontend: `http://localhost:8000`\n- Backend API: `http://localhost:8000/api`\n- API docs: `http://localhost:8000/docs`\n\n## Verify the Deployment\n\nBefore moving on, confirm that the deployment really came up cleanly.\n\n- The `docker compose ps` output shows the `sambee` service running.\n- The frontend URL responds on the expected host port.\n- The startup logs do not show an obvious failure loop.\n\nFor a quick log review:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\nOnce the deployment is healthy, continue with the first login procedure on the next page.\n", "0.9": "+++\ntitle = \"Deploy Sambee with Docker\"\n+++\n\n## Before You Start\n\nYou need:\n\n- Docker and `docker compose` installed.\n- A host that can reach the SMB file servers Sambee will use.\n- A deployment directory where you can keep local files such as `docker-compose.yml`, optional `config.toml`, and the persistent `data/` directory.\n\nYou do not need to clone the repository or build Sambee locally for a normal Docker deployment. Sambee publishes ready-to-run container images to GitHub Container Registry.\n\n## 1. Create a Deployment Directory\n\nCreate a dedicated directory for your local deployment files and move into it:\n\n```bash\nmkdir -p sambee\ncd sambee\n```\n\nThis directory will hold your Compose file, optional configuration file, and persistent application data.\n\n## 2. Prepare Persistent Storage\n\nCreate the local data directory and set ownership to user and group ID `1000`, which the containerized application uses:\n\n```bash\nmkdir -p ./data\nchown -Rfv 1000:1000 ./data\n```\n\nThis directory contains the Sambee database and other state that must survive restarts, rebuilds, and host reboots.\n\n## 3. Create the Compose File\n\nCreate `docker-compose.yml` with this content:\n\n```yaml\nservices:\n\tsambee:\n\t\timage: ghcr.io/helgeklein/sambee:stable\n\t\trestart: unless-stopped\n\t\tvolumes:\n\t\t\t- ./data:/app/data\n\t\t\t# Optional: uncomment when you create config.toml locally.\n\t\t\t# - ./config.toml:/app/config.toml:ro\n\t\tports:\n\t\t\t- 8000:8000\n```\n\n#### Select a Release Channel\n\nSambee has three different release channels. You select which to follow via the Docker image tag:\n\n- `stable` for the production channel.\n- `beta` for prerelease builds.\n- `test` for preview builds.\n\n## 4. Optional: Create a Local Configuration File\n\nYou do not need `config.toml` for a basic deployment. Create it only if you need to override defaults such as logging or Companion download settings. Configure the authentication mode in **Settings** \u003e **Administration** \u003e **Authentication** after signing in.\n\nCreate `config.toml` with only the settings you want to change. For example:\n\n```toml\n[app]\nlog_level = \"INFO\"\n\n[admin]\nusername = \"admin\"\n```\n\nIf you create `config.toml`, uncomment the read-only bind mount in `docker-compose.yml`.\n\nKeep this file local. In production, mount it read-only.\n\n## 5. Pull and Start Sambee\n\nPull the configured image:\n\n```bash\ndocker compose pull\n```\n\nThen start the application:\n\n```bash\ndocker compose up -d\n```\n\nBy default, the service is available at:\n\n- Frontend: `http://localhost:8000`\n- Backend API: `http://localhost:8000/api`\n- API docs: `http://localhost:8000/docs`\n\n## Verify the Deployment\n\nBefore moving on, confirm that the deployment really came up cleanly.\n\n- The `docker compose ps` output shows the `sambee` service running.\n- The frontend URL responds on the expected host port.\n- The startup logs do not show an obvious failure loop.\n\nFor a quick log review:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\nOnce the deployment is healthy, continue with the first login procedure on the next page.\n", "1.0": "+++\ntitle = \"Deploy Sambee with Docker\"\n+++\n\n## Before You Start\n\nYou need:\n\n- Docker and `docker compose` installed.\n- A host that can reach the SMB file servers Sambee will use.\n- A deployment directory where you can keep local files such as `docker-compose.yml`, optional `config.toml`, and the persistent `data/` directory.\n\nYou do not need to clone the repository or build Sambee locally for a normal Docker deployment. Sambee publishes ready-to-run container images to GitHub Container Registry.\n\n## 1. Create a Deployment Directory\n\nCreate a dedicated directory for your local deployment files and move into it:\n\n```bash\nmkdir -p sambee\ncd sambee\n```\n\nThis directory will hold your Compose file, optional configuration file, and persistent application data.\n\n## 2. Prepare Persistent Storage\n\nCreate the local data directory and set ownership to user and group ID `1000`, which the containerized application uses:\n\n```bash\nmkdir -p ./data\nchown -Rfv 1000:1000 ./data\n```\n\nThis directory contains the Sambee database and other state that must survive restarts, rebuilds, and host reboots.\n\n## 3. Create the Compose File\n\nCreate `docker-compose.yml` with this content:\n\n```yaml\nservices:\n\tsambee:\n\t\timage: ghcr.io/helgeklein/sambee:stable\n\t\trestart: unless-stopped\n\t\tvolumes:\n\t\t\t- ./data:/app/data\n\t\t\t# Optional: uncomment when you create config.toml locally.\n\t\t\t# - ./config.toml:/app/config.toml:ro\n\t\tports:\n\t\t\t- 8000:8000\n```\n\n#### Select a Release Channel\n\nSambee has three different release channels. You select which to follow via the Docker image tag:\n\n- `stable` for the production channel.\n- `beta` for prerelease builds.\n- `test` for preview builds.\n\n## 4. Optional: Create a Local Configuration File\n\nYou do not need `config.toml` for a basic deployment. Create it only if you need to override defaults such as logging or Companion download settings. Configure the authentication mode in **Settings** \u003e **Administration** \u003e **Authentication** after signing in.\n\nCreate `config.toml` with only the settings you want to change. For example:\n\n```toml\n[app]\nlog_level = \"INFO\"\n\n[admin]\nusername = \"admin\"\n```\n\nIf you create `config.toml`, uncomment the read-only bind mount in `docker-compose.yml`.\n\nKeep this file local. In production, mount it read-only.\n\n## 5. Pull and Start Sambee\n\nPull the configured image:\n\n```bash\ndocker compose pull\n```\n\nThen start the application:\n\n```bash\ndocker compose up -d\n```\n\nBy default, the service is available at:\n\n- Frontend: `http://localhost:8000`\n- Backend API: `http://localhost:8000/api`\n- API docs: `http://localhost:8000/docs`\n\n## Verify the Deployment\n\nBefore moving on, confirm that the deployment really came up cleanly.\n\n- The `docker compose ps` output shows the `sambee` service running.\n- The frontend URL responds on the expected host port.\n- The startup logs do not show an obvious failure loop.\n\nFor a quick log review:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\nOnce the deployment is healthy, continue with the first login procedure on the next page.\n", "2.0": "+++\ntitle = \"Deploy Sambee with Docker\"\n+++\n\n## Before You Start\n\nYou need:\n\n- Docker and `docker compose` installed.\n- A host that can reach the SMB file servers Sambee will use.\n- A deployment directory where you can keep local files such as `docker-compose.yml`, optional `config.toml`, and the persistent `data/` directory.\n\nYou do not need to clone the repository or build Sambee locally for a normal Docker deployment. Sambee publishes ready-to-run container images to GitHub Container Registry.\n\n## 1. Create a Deployment Directory\n\nCreate a dedicated directory for your local deployment files and move into it:\n\n```bash\nmkdir -p sambee\ncd sambee\n```\n\nThis directory will hold your Compose file, optional configuration file, and persistent application data.\n\n## 2. Prepare Persistent Storage\n\nCreate the local data directory and set ownership to user and group ID `1000`, which the containerized application uses:\n\n```bash\nmkdir -p ./data\nchown -Rfv 1000:1000 ./data\n```\n\nThis directory contains the Sambee database and other state that must survive restarts, rebuilds, and host reboots.\n\n## 3. Create the Compose File\n\nCreate `docker-compose.yml` with this content:\n\n```yaml\nservices:\n\tsambee:\n\t\timage: ghcr.io/sambee-app/sambee:stable\n\t\trestart: unless-stopped\n\t\tvolumes:\n\t\t\t- ./data:/app/data\n\t\t\t# Optional: uncomment when you create config.toml locally.\n\t\t\t# - ./config.toml:/app/config.toml:ro\n\t\tports:\n\t\t\t- 8000:8000\n```\n\n#### Select a Release Channel\n\nSambee has three different release channels. You select which to follow via the Docker image tag:\n\n- `stable` for the production channel.\n- `beta` for prerelease builds.\n- `test` for preview builds.\n\n## 4. Optional: Create a Local Configuration File\n\nYou do not need `config.toml` for a basic deployment. Create it only if you need to override defaults such as logging or Companion download settings. Configure the authentication mode in **Settings** \u003e **Administration** \u003e **Authentication** after signing in.\n\nCreate `config.toml` with only the settings you want to change. For example:\n\n```toml\n[app]\nlog_level = \"INFO\"\n\n[admin]\nusername = \"admin\"\n```\n\nIf you create `config.toml`, uncomment the read-only bind mount in `docker-compose.yml`.\n\nKeep this file local. In production, mount it read-only.\n\n## 5. Pull and Start Sambee\n\nPull the configured image:\n\n```bash\ndocker compose pull\n```\n\nThen start the application:\n\n```bash\ndocker compose up -d\n```\n\nBy default, the service is available at:\n\n- Frontend: `http://localhost:8000`\n- Backend API: `http://localhost:8000/api`\n- API docs: `http://localhost:8000/docs`\n\n## Verify the Deployment\n\nBefore moving on, confirm that the deployment really came up cleanly.\n\n- The `docker compose ps` output shows the `sambee` service running.\n- The frontend URL responds on the expected host port.\n- The startup logs do not show an obvious failure loop.\n\nFor a quick log review:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\nOnce the deployment is healthy, continue with the first login procedure on the next page.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Deploy Sambee with Docker\"\n+++\n\n## Before You Start\n\nYou need:\n\n- Docker and `docker compose` installed.\n- A host that can reach the SMB file servers Sambee will use.\n- A deployment directory where you can keep local files such as `docker-compose.yml`, optional `config.toml`, and the persistent `data/` directory.\n\nYou do not need to clone the repository or build Sambee locally for a normal Docker deployment. Sambee publishes ready-to-run container images to GitHub Container Registry.\n\n## 1. Create a Deployment Directory\n\nCreate a dedicated directory for your local deployment files and move into it:\n\n```bash\nmkdir -p sambee\ncd sambee\n```\n\nThis directory will hold your Compose file, optional configuration file, and persistent application data.\n\n## 2. Prepare Persistent Storage\n\nCreate the local data directory and set ownership to user and group ID `1000`, which the containerized application uses:\n\n```bash\nmkdir -p ./data\nchown -Rfv 1000:1000 ./data\n```\n\nThis directory contains the Sambee database and other state that must survive restarts, rebuilds, and host reboots.\n\n## 3. Create the Compose File\n\nCreate `docker-compose.yml` with this content:\n\n```yaml\nservices:\n\tsambee:\n\t\timage: ghcr.io/helgeklein/sambee:stable\n\t\trestart: unless-stopped\n\t\tvolumes:\n\t\t\t- ./data:/app/data\n\t\t\t# Optional: uncomment when you create config.toml locally.\n\t\t\t# - ./config.toml:/app/config.toml:ro\n\t\tports:\n\t\t\t- 8000:8000\n```\n\n#### Select a Release Channel\n\nSambee has three different release channels. You select which to follow via the Docker image tag:\n\n- `stable` for the production channel.\n- `beta` for prerelease builds.\n- `test` for preview builds.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nWhile Sambee is in beta, the `stable` tag may not be available yet.\n{{\u003c /admonition \u003e}}\n\n## 4. Optional: Create a Local Configuration File\n\nYou do not need `config.toml` for a basic deployment. Create it only if you need to override defaults such as authentication, logging, or Companion download settings.\n\nCreate `config.toml` with only the settings you want to change. For example:\n\n```toml\n[app]\nlog_level = \"INFO\"\n\n[security]\nauth_method = \"password\"\n\n[admin]\nusername = \"admin\"\n```\n\nIf you create `config.toml`, uncomment the read-only bind mount in `docker-compose.yml`.\n\nKeep this file local. In production, mount it read-only.\n\n## 5. Pull and Start Sambee\n\nPull the configured image:\n\n```bash\ndocker compose pull\n```\n\nThen start the application:\n\n```bash\ndocker compose up -d\n```\n\nBy default, the service is available at:\n\n- Frontend: `http://localhost:8000`\n- Backend API: `http://localhost:8000/api`\n- API docs: `http://localhost:8000/docs`\n\n## Verify the Deployment\n\nBefore moving on, confirm that the deployment really came up cleanly.\n\n- The `docker compose ps` output shows the `sambee` service running.\n- The frontend URL responds on the expected host port.\n- The startup logs do not show an obvious failure loop.\n\nFor a quick log review:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\nOnce the deployment is healthy, continue with the first login procedure on the next page.\n", "0.8": "+++\ntitle = \"Deploy Sambee with Docker\"\n+++\n\n## Before You Start\n\nYou need:\n\n- Docker and `docker compose` installed.\n- A host that can reach the SMB file servers Sambee will use.\n- A deployment directory where you can keep local files such as `docker-compose.yml`, optional `config.toml`, and the persistent `data/` directory.\n\nYou do not need to clone the repository or build Sambee locally for a normal Docker deployment. Sambee publishes ready-to-run container images to GitHub Container Registry.\n\n## 1. Create a Deployment Directory\n\nCreate a dedicated directory for your local deployment files and move into it:\n\n```bash\nmkdir -p sambee\ncd sambee\n```\n\nThis directory will hold your Compose file, optional configuration file, and persistent application data.\n\n## 2. Prepare Persistent Storage\n\nCreate the local data directory and set ownership to user and group ID `1000`, which the containerized application uses:\n\n```bash\nmkdir -p ./data\nchown -Rfv 1000:1000 ./data\n```\n\nThis directory contains the Sambee database and other state that must survive restarts, rebuilds, and host reboots.\n\n## 3. Create the Compose File\n\nCreate `docker-compose.yml` with this content:\n\n```yaml\nservices:\n\tsambee:\n\t\timage: ghcr.io/helgeklein/sambee:stable\n\t\trestart: unless-stopped\n\t\tvolumes:\n\t\t\t- ./data:/app/data\n\t\t\t# Optional: uncomment when you create config.toml locally.\n\t\t\t# - ./config.toml:/app/config.toml:ro\n\t\tports:\n\t\t\t- 8000:8000\n```\n\n#### Select a Release Channel\n\nSambee has three different release channels. You select which to follow via the Docker image tag:\n\n- `stable` for the production channel.\n- `beta` for prerelease builds.\n- `test` for preview builds.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nWhile Sambee is in beta, the `stable` tag may not be available yet.\n{{\u003c /admonition \u003e}}\n\n## 4. Optional: Create a Local Configuration File\n\nYou do not need `config.toml` for a basic deployment. Create it only if you need to override defaults such as authentication, logging, or Companion download settings.\n\nCreate `config.toml` with only the settings you want to change. For example:\n\n```toml\n[app]\nlog_level = \"INFO\"\n\n[security]\nauth_method = \"password\"\n\n[admin]\nusername = \"admin\"\n```\n\nIf you create `config.toml`, uncomment the read-only bind mount in `docker-compose.yml`.\n\nKeep this file local. In production, mount it read-only.\n\n## 5. Pull and Start Sambee\n\nPull the configured image:\n\n```bash\ndocker compose pull\n```\n\nThen start the application:\n\n```bash\ndocker compose up -d\n```\n\nBy default, the service is available at:\n\n- Frontend: `http://localhost:8000`\n- Backend API: `http://localhost:8000/api`\n- API docs: `http://localhost:8000/docs`\n\n## Verify the Deployment\n\nBefore moving on, confirm that the deployment really came up cleanly.\n\n- The `docker compose ps` output shows the `sambee` service running.\n- The frontend URL responds on the expected host port.\n- The startup logs do not show an obvious failure loop.\n\nFor a quick log review:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\nOnce the deployment is healthy, continue with the first login procedure on the next page.\n", "0.9": "+++\ntitle = \"Deploy Sambee with Docker\"\n+++\n\n## Before You Start\n\nYou need:\n\n- Docker and `docker compose` installed.\n- A host that can reach the SMB file servers Sambee will use.\n- A deployment directory where you can keep local files such as `docker-compose.yml`, optional `config.toml`, and the persistent `data/` directory.\n\nYou do not need to clone the repository or build Sambee locally for a normal Docker deployment. Sambee publishes ready-to-run container images to GitHub Container Registry.\n\n## 1. Create a Deployment Directory\n\nCreate a dedicated directory for your local deployment files and move into it:\n\n```bash\nmkdir -p sambee\ncd sambee\n```\n\nThis directory will hold your Compose file, optional configuration file, and persistent application data.\n\n## 2. Prepare Persistent Storage\n\nCreate the local data directory and set ownership to user and group ID `1000`, which the containerized application uses:\n\n```bash\nmkdir -p ./data\nchown -Rfv 1000:1000 ./data\n```\n\nThis directory contains the Sambee database and other state that must survive restarts, rebuilds, and host reboots.\n\n## 3. Create the Compose File\n\nCreate `docker-compose.yml` with this content:\n\n```yaml\nservices:\n\tsambee:\n\t\timage: ghcr.io/helgeklein/sambee:stable\n\t\trestart: unless-stopped\n\t\tvolumes:\n\t\t\t- ./data:/app/data\n\t\t\t# Optional: uncomment when you create config.toml locally.\n\t\t\t# - ./config.toml:/app/config.toml:ro\n\t\tports:\n\t\t\t- 8000:8000\n```\n\n#### Select a Release Channel\n\nSambee has three different release channels. You select which to follow via the Docker image tag:\n\n- `stable` for the production channel.\n- `beta` for prerelease builds.\n- `test` for preview builds.\n\n## 4. Optional: Create a Local Configuration File\n\nYou do not need `config.toml` for a basic deployment. Create it only if you need to override defaults such as logging or Companion download settings. Configure the authentication mode in **Settings** \u003e **Administration** \u003e **Authentication** after signing in.\n\nCreate `config.toml` with only the settings you want to change. For example:\n\n```toml\n[app]\nlog_level = \"INFO\"\n\n[admin]\nusername = \"admin\"\n```\n\nIf you create `config.toml`, uncomment the read-only bind mount in `docker-compose.yml`.\n\nKeep this file local. In production, mount it read-only.\n\n## 5. Pull and Start Sambee\n\nPull the configured image:\n\n```bash\ndocker compose pull\n```\n\nThen start the application:\n\n```bash\ndocker compose up -d\n```\n\nBy default, the service is available at:\n\n- Frontend: `http://localhost:8000`\n- Backend API: `http://localhost:8000/api`\n- API docs: `http://localhost:8000/docs`\n\n## Verify the Deployment\n\nBefore moving on, confirm that the deployment really came up cleanly.\n\n- The `docker compose ps` output shows the `sambee` service running.\n- The frontend URL responds on the expected host port.\n- The startup logs do not show an obvious failure loop.\n\nFor a quick log review:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\nOnce the deployment is healthy, continue with the first login procedure on the next page.\n", "1.0": "+++\ntitle = \"Deploy Sambee with Docker\"\n+++\n\n## Before You Start\n\nYou need:\n\n- Docker and `docker compose` installed.\n- A host that can reach the SMB file servers Sambee will use.\n- A deployment directory where you can keep local files such as `docker-compose.yml`, optional `config.toml`, and the persistent `data/` directory.\n\nYou do not need to clone the repository or build Sambee locally for a normal Docker deployment. Sambee publishes ready-to-run container images to GitHub Container Registry.\n\n## 1. Create a Deployment Directory\n\nCreate a dedicated directory for your local deployment files and move into it:\n\n```bash\nmkdir -p sambee\ncd sambee\n```\n\nThis directory will hold your Compose file, optional configuration file, and persistent application data.\n\n## 2. Prepare Persistent Storage\n\nCreate the local data directory and set ownership to user and group ID `1000`, which the containerized application uses:\n\n```bash\nmkdir -p ./data\nchown -Rfv 1000:1000 ./data\n```\n\nThis directory contains the Sambee database and other state that must survive restarts, rebuilds, and host reboots.\n\n## 3. Create the Compose File\n\nCreate `docker-compose.yml` with this content:\n\n```yaml\nservices:\n\tsambee:\n\t\timage: ghcr.io/helgeklein/sambee:stable\n\t\trestart: unless-stopped\n\t\tvolumes:\n\t\t\t- ./data:/app/data\n\t\t\t# Optional: uncomment when you create config.toml locally.\n\t\t\t# - ./config.toml:/app/config.toml:ro\n\t\tports:\n\t\t\t- 8000:8000\n```\n\n#### Select a Release Channel\n\nSambee has three different release channels. You select which to follow via the Docker image tag:\n\n- `stable` for the production channel.\n- `beta` for prerelease builds.\n- `test` for preview builds.\n\n## 4. Optional: Create a Local Configuration File\n\nYou do not need `config.toml` for a basic deployment. Create it only if you need to override defaults such as logging or Companion download settings. Configure the authentication mode in **Settings** \u003e **Administration** \u003e **Authentication** after signing in.\n\nCreate `config.toml` with only the settings you want to change. For example:\n\n```toml\n[app]\nlog_level = \"INFO\"\n\n[admin]\nusername = \"admin\"\n```\n\nIf you create `config.toml`, uncomment the read-only bind mount in `docker-compose.yml`.\n\nKeep this file local. In production, mount it read-only.\n\n## 5. Pull and Start Sambee\n\nPull the configured image:\n\n```bash\ndocker compose pull\n```\n\nThen start the application:\n\n```bash\ndocker compose up -d\n```\n\nBy default, the service is available at:\n\n- Frontend: `http://localhost:8000`\n- Backend API: `http://localhost:8000/api`\n- API docs: `http://localhost:8000/docs`\n\n## Verify the Deployment\n\nBefore moving on, confirm that the deployment really came up cleanly.\n\n- The `docker compose ps` output shows the `sambee` service running.\n- The frontend URL responds on the expected host port.\n- The startup logs do not show an obvious failure loop.\n\nFor a quick log review:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\nOnce the deployment is healthy, continue with the first login procedure on the next page.\n", "2.0": "+++\ntitle = \"Deploy Sambee with Docker\"\n+++\n\n## Before You Start\n\nYou need:\n\n- Docker and `docker compose` installed.\n- A host that can reach the SMB file servers Sambee will use.\n- A deployment directory where you can keep local files such as `docker-compose.yml`, optional `config.toml`, and the persistent `data/` directory.\n\nYou do not need to clone the repository or build Sambee locally for a normal Docker deployment. Sambee publishes ready-to-run container images to GitHub Container Registry.\n\n## 1. Create a Deployment Directory\n\nCreate a dedicated directory for your local deployment files and move into it:\n\n```bash\nmkdir -p sambee\ncd sambee\n```\n\nThis directory will hold your Compose file, optional configuration file, and persistent application data.\n\n## 2. Prepare Persistent Storage\n\nCreate the local data directory and set ownership to user and group ID `1000`, which the containerized application uses:\n\n```bash\nmkdir -p ./data\nchown -Rfv 1000:1000 ./data\n```\n\nThis directory contains the Sambee database and other state that must survive restarts, rebuilds, and host reboots.\n\n## 3. Create the Compose File\n\nCreate `docker-compose.yml` with this content:\n\n```yaml\nservices:\n\tsambee:\n\t\timage: ghcr.io/sambee-app/sambee:stable\n\t\trestart: unless-stopped\n\t\tvolumes:\n\t\t\t- ./data:/app/data\n\t\t\t# Optional: uncomment when you create config.toml locally.\n\t\t\t# - ./config.toml:/app/config.toml:ro\n\t\tports:\n\t\t\t- 8000:8000\n```\n\n#### Select a Release Channel\n\nSambee has three different release channels. You select which to follow via the Docker image tag:\n\n- `stable` for the production channel.\n- `beta` for prerelease builds.\n- `test` for preview builds.\n\n## 4. Optional: Create a Local Configuration File\n\nYou do not need `config.toml` for a basic deployment. Create it only if you need to override defaults such as logging or Companion download settings. Configure the authentication mode in **Settings** \u003e **Administration** \u003e **Authentication** after signing in.\n\nCreate `config.toml` with only the settings you want to change. For example:\n\n```toml\n[app]\nlog_level = \"INFO\"\n\n[admin]\nusername = \"admin\"\n```\n\nIf you create `config.toml`, uncomment the read-only bind mount in `docker-compose.yml`.\n\nKeep this file local. In production, mount it read-only.\n\n## 5. Pull and Start Sambee\n\nPull the configured image:\n\n```bash\ndocker compose pull\n```\n\nThen start the application:\n\n```bash\ndocker compose up -d\n```\n\nBy default, the service is available at:\n\n- Frontend: `http://localhost:8000`\n- Backend API: `http://localhost:8000/api`\n- API docs: `http://localhost:8000/docs`\n\n## Verify the Deployment\n\nBefore moving on, confirm that the deployment really came up cleanly.\n\n- The `docker compose ps` output shows the `sambee` service running.\n- The frontend URL responds on the expected host port.\n- The startup logs do not show an obvious failure loop.\n\nFor a quick log review:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\nOnce the deployment is healthy, continue with the first login procedure on the next page.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:admin-guide/installation-and-deployment/first-startup-and-first-admin-login", "parent_id": "section:admin-guide/installation-and-deployment", "depth": 2, "kind": "page", "label": "first-startup-and-first-admin-login", "title": "First Startup And First Admin Login", "path": "admin-guide/installation-and-deployment/first-startup-and-first-admin-login", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"First Startup and First Admin Login\"\n+++\n\nOnce the container is up, retrieve the initial credentials and confirm that you can sign in as the first administrator.\n\n## Retrieve the Initial Admin Password\n\nGet the first-time admin password from the logs:\n\n```bash\ndocker compose logs sambee --tail 100 | grep -A 5 \"FIRST-TIME SETUP\"\n```\n\nYou are looking for a log block labeled `FIRST-TIME SETUP - SAVE THESE CREDENTIALS` with lines for the username and password.\n\nYou will need:\n\n- Username: `admin`, unless you changed it through configuration.\n- Password: The generated password from the logs.\n\n## Sign In\n\nOpen Sambee in the browser at the frontend URL for your deployment and sign in with the initial admin credentials.\n\nThis first sign-in confirms that:\n\n- The service is reachable.\n- The frontend is loading.\n- The backend startup completed far enough to expose the first-time setup information.\n", "0.8": "+++\ntitle = \"First Startup and First Admin Login\"\n+++\n\nOnce the container is up, retrieve the initial credentials and confirm that you can sign in as the first administrator.\n\n## Retrieve the Initial Admin Password\n\nGet the first-time admin password from the logs:\n\n```bash\ndocker compose logs sambee --tail 100 | grep -A 5 \"FIRST-TIME SETUP\"\n```\n\nYou are looking for a log block labeled `FIRST-TIME SETUP - SAVE THESE CREDENTIALS` with lines for the username and password.\n\nYou will need:\n\n- Username: `admin`, unless you changed it through configuration.\n- Password: The generated password from the logs.\n\n## Sign In\n\nOpen Sambee in the browser at the frontend URL for your deployment and sign in with the initial admin credentials.\n\nThis first sign-in confirms that:\n\n- The service is reachable.\n- The frontend is loading.\n- The backend startup completed far enough to expose the first-time setup information.\n", "0.9": "+++\ntitle = \"First Startup and First Admin Login\"\n+++\n\nOnce the container is up, retrieve the initial credentials and confirm that you can sign in as the first administrator.\n\n## Retrieve the Initial Admin Password\n\nGet the first-time admin password from the logs:\n\n```bash\ndocker compose logs sambee --tail 100 | grep -A 5 \"FIRST-TIME SETUP\"\n```\n\nYou are looking for a log block labeled `FIRST-TIME SETUP - SAVE THESE CREDENTIALS` with lines for the username and password.\n\nYou will need:\n\n- Username: `admin`, unless you changed it through configuration.\n- Password: The generated password from the logs.\n\n## Sign In\n\nOpen Sambee in the browser at the frontend URL for your deployment and sign in with the initial admin credentials.\n\nThis first sign-in confirms that:\n\n- The service is reachable.\n- The frontend is loading.\n- The backend startup completed far enough to expose the first-time setup information.\n", "1.0": "+++\ntitle = \"First Startup and First Admin Login\"\n+++\n\nOnce the container is up, retrieve the initial credentials and confirm that you can sign in as the first administrator.\n\n## Retrieve the Initial Admin Password\n\nGet the first-time admin password from the logs:\n\n```bash\ndocker compose logs sambee --tail 100 | grep -A 5 \"FIRST-TIME SETUP\"\n```\n\nYou are looking for a log block labeled `FIRST-TIME SETUP - SAVE THESE CREDENTIALS` with lines for the username and password.\n\nYou will need:\n\n- Username: `admin`, unless you changed it through configuration.\n- Password: The generated password from the logs.\n\n## Sign In\n\nOpen Sambee in the browser at the frontend URL for your deployment and sign in with the initial admin credentials.\n\nThis first sign-in confirms that:\n\n- The service is reachable.\n- The frontend is loading.\n- The backend startup completed far enough to expose the first-time setup information.\n", "2.0": "+++\ntitle = \"First Startup and First Admin Login\"\n+++\n\nOnce the container is up, retrieve the initial credentials and confirm that you can sign in as the first administrator.\n\n## Retrieve the Initial Admin Password\n\nGet the first-time admin password from the logs:\n\n```bash\ndocker compose logs sambee --tail 100 | grep -A 5 \"FIRST-TIME SETUP\"\n```\n\nYou are looking for a log block labeled `FIRST-TIME SETUP - SAVE THESE CREDENTIALS` with lines for the username and password.\n\nYou will need:\n\n- Username: `admin`, unless you changed it through configuration.\n- Password: The generated password from the logs.\n\n## Sign In\n\nOpen Sambee in the browser at the frontend URL for your deployment and sign in with the initial admin credentials.\n\nThis first sign-in confirms that:\n\n- The service is reachable.\n- The frontend is loading.\n- The backend startup completed far enough to expose the first-time setup information.\n"}, "page_contents": {"0.7": "+++\ntitle = \"First Startup and First Admin Login\"\n+++\n\nOnce the container is up, retrieve the initial credentials and confirm that you can sign in as the first administrator.\n\n## Retrieve the Initial Admin Password\n\nGet the first-time admin password from the logs:\n\n```bash\ndocker compose logs sambee --tail 100 | grep -A 5 \"FIRST-TIME SETUP\"\n```\n\nYou are looking for a log block labeled `FIRST-TIME SETUP - SAVE THESE CREDENTIALS` with lines for the username and password.\n\nYou will need:\n\n- Username: `admin`, unless you changed it through configuration.\n- Password: The generated password from the logs.\n\n## Sign In\n\nOpen Sambee in the browser at the frontend URL for your deployment and sign in with the initial admin credentials.\n\nThis first sign-in confirms that:\n\n- The service is reachable.\n- The frontend is loading.\n- The backend startup completed far enough to expose the first-time setup information.\n", "0.8": "+++\ntitle = \"First Startup and First Admin Login\"\n+++\n\nOnce the container is up, retrieve the initial credentials and confirm that you can sign in as the first administrator.\n\n## Retrieve the Initial Admin Password\n\nGet the first-time admin password from the logs:\n\n```bash\ndocker compose logs sambee --tail 100 | grep -A 5 \"FIRST-TIME SETUP\"\n```\n\nYou are looking for a log block labeled `FIRST-TIME SETUP - SAVE THESE CREDENTIALS` with lines for the username and password.\n\nYou will need:\n\n- Username: `admin`, unless you changed it through configuration.\n- Password: The generated password from the logs.\n\n## Sign In\n\nOpen Sambee in the browser at the frontend URL for your deployment and sign in with the initial admin credentials.\n\nThis first sign-in confirms that:\n\n- The service is reachable.\n- The frontend is loading.\n- The backend startup completed far enough to expose the first-time setup information.\n", "0.9": "+++\ntitle = \"First Startup and First Admin Login\"\n+++\n\nOnce the container is up, retrieve the initial credentials and confirm that you can sign in as the first administrator.\n\n## Retrieve the Initial Admin Password\n\nGet the first-time admin password from the logs:\n\n```bash\ndocker compose logs sambee --tail 100 | grep -A 5 \"FIRST-TIME SETUP\"\n```\n\nYou are looking for a log block labeled `FIRST-TIME SETUP - SAVE THESE CREDENTIALS` with lines for the username and password.\n\nYou will need:\n\n- Username: `admin`, unless you changed it through configuration.\n- Password: The generated password from the logs.\n\n## Sign In\n\nOpen Sambee in the browser at the frontend URL for your deployment and sign in with the initial admin credentials.\n\nThis first sign-in confirms that:\n\n- The service is reachable.\n- The frontend is loading.\n- The backend startup completed far enough to expose the first-time setup information.\n", "1.0": "+++\ntitle = \"First Startup and First Admin Login\"\n+++\n\nOnce the container is up, retrieve the initial credentials and confirm that you can sign in as the first administrator.\n\n## Retrieve the Initial Admin Password\n\nGet the first-time admin password from the logs:\n\n```bash\ndocker compose logs sambee --tail 100 | grep -A 5 \"FIRST-TIME SETUP\"\n```\n\nYou are looking for a log block labeled `FIRST-TIME SETUP - SAVE THESE CREDENTIALS` with lines for the username and password.\n\nYou will need:\n\n- Username: `admin`, unless you changed it through configuration.\n- Password: The generated password from the logs.\n\n## Sign In\n\nOpen Sambee in the browser at the frontend URL for your deployment and sign in with the initial admin credentials.\n\nThis first sign-in confirms that:\n\n- The service is reachable.\n- The frontend is loading.\n- The backend startup completed far enough to expose the first-time setup information.\n", "2.0": "+++\ntitle = \"First Startup and First Admin Login\"\n+++\n\nOnce the container is up, retrieve the initial credentials and confirm that you can sign in as the first administrator.\n\n## Retrieve the Initial Admin Password\n\nGet the first-time admin password from the logs:\n\n```bash\ndocker compose logs sambee --tail 100 | grep -A 5 \"FIRST-TIME SETUP\"\n```\n\nYou are looking for a log block labeled `FIRST-TIME SETUP - SAVE THESE CREDENTIALS` with lines for the username and password.\n\nYou will need:\n\n- Username: `admin`, unless you changed it through configuration.\n- Password: The generated password from the logs.\n\n## Sign In\n\nOpen Sambee in the browser at the frontend URL for your deployment and sign in with the initial admin credentials.\n\nThis first sign-in confirms that:\n\n- The service is reachable.\n- The frontend is loading.\n- The backend startup completed far enough to expose the first-time setup information.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:admin-guide/network-and-reverse-proxy", "parent_id": "book:admin-guide", "depth": 1, "kind": "section", "label": "network-and-reverse-proxy", "title": "Network and Reverse Proxy", "path": "admin-guide/network-and-reverse-proxy", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:admin-guide/network-and-reverse-proxy/put-sambee-behind-a-reverse-proxy", "parent_id": "section:admin-guide/network-and-reverse-proxy", "depth": 2, "kind": "page", "label": "put-sambee-behind-a-reverse-proxy", "title": "Put Sambee Behind A Reverse Proxy", "path": "admin-guide/network-and-reverse-proxy/put-sambee-behind-a-reverse-proxy", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Put Sambee behind a Reverse Proxy\"\n+++\n\nFor production-style deployments, place a reverse proxy in front of Sambee to handle HTTPS.\n\n## Why Use a Reverse Proxy\n\nA reverse proxy gives you a cleaner operational model for:\n\n- HTTPS and certificate management\n- A stable hostname and routing layer in front of the container\n\n## Caddy Example\n\nIf you already run a dockerized Caddy environment, the Sambee service can be connected to that network with a compose layout like this:\n\n```yaml\nservices:\n  sambee:\n    container_name: sambee\n    hostname: sambee\n    build: .\n    restart: unless-stopped\n    networks:\n      - caddy_caddynet\n    expose:\n      - \"8000\"\n    volumes:\n      - ./data:/app/data\n      # Optional:\n      # - ./config.toml:/app/config.toml:ro\n\nnetworks:\n  caddy_caddynet:\n    external: true\n```\n\nHere, `expose` makes Sambee's port `8000` available to other containers on the same Docker network without publishing it directly to the host.\n\nThe important point is that Sambee serves plain HTTP to the reverse proxy and does not act as the HTTPS edge itself.\n\n## Companion Native Editing Behind Interactive Auth\n\nIf your reverse proxy protects the Sambee backend with an interactive login flow, Companion native editing can still work, but the proxy setup has to satisfy a few constraints.\n\nThe Companion runtime opens its own `Sambee Authentication` webview when reverse-proxy auth intercepts backend API calls. After the user signs in there, Companion reuses backend-origin cookies from that embedded webview for its Rust-side API requests.\n\nFor that to work reliably:\n\n- The reverse-proxy cookie must be valid for the Sambee backend origin that Companion calls.\n- The login flow must work inside the system webview used by Tauri on the target desktop platform.\n- The proxy must not depend on browser features that are unavailable in that embedded webview.\n- The proxy must allow authenticated requests to the Companion backend endpoints after the embedded webview has established the proxy session.\n\n{{\u003c admonition type=\"note\" \u003e}}\nCompanion does not and cannot read cookies from the user\u2019s Sambee frontend browser session.\n{{\u003c /admonition \u003e}}\n\nOperationally, that means you should test both the browser UI and a real Companion native-edit session when introducing or changing proxy auth. A useful native-edit test signs in through the Companion authentication window, opens an SMB-backed file in a desktop app, uploads or closes the edit session, and confirms that lock release works without a second unexpected login prompt.\n", "0.8": "+++\ntitle = \"Put Sambee behind a Reverse Proxy\"\n+++\n\nFor production-style deployments, place a reverse proxy in front of Sambee to handle HTTPS.\n\n## Why Use a Reverse Proxy\n\nA reverse proxy gives you a cleaner operational model for:\n\n- HTTPS and certificate management\n- A stable hostname and routing layer in front of the container\n\n## Caddy Example\n\nIf you already run a dockerized Caddy environment, the Sambee service can be connected to that network with a compose layout like this:\n\n```yaml\nservices:\n  sambee:\n    container_name: sambee\n    hostname: sambee\n    build: .\n    restart: unless-stopped\n    networks:\n      - caddy_caddynet\n    expose:\n      - \"8000\"\n    volumes:\n      - ./data:/app/data\n      # Optional:\n      # - ./config.toml:/app/config.toml:ro\n\nnetworks:\n  caddy_caddynet:\n    external: true\n```\n\nHere, `expose` makes Sambee's port `8000` available to other containers on the same Docker network without publishing it directly to the host.\n\nThe important point is that Sambee serves plain HTTP to the reverse proxy and does not act as the HTTPS edge itself.\n\n## Companion Native Editing Behind Interactive Auth\n\nIf your reverse proxy protects the Sambee backend with an interactive login flow, Companion native editing can still work, but the proxy setup has to satisfy a few constraints.\n\nThe Companion runtime opens its own `Sambee Authentication` webview when reverse-proxy auth intercepts backend API calls. After the user signs in there, Companion reuses backend-origin cookies from that embedded webview for its Rust-side API requests.\n\nFor that to work reliably:\n\n- The reverse-proxy cookie must be valid for the Sambee backend origin that Companion calls.\n- The login flow must work inside the system webview used by Tauri on the target desktop platform.\n- The proxy must not depend on browser features that are unavailable in that embedded webview.\n- The proxy must allow authenticated requests to the Companion backend endpoints after the embedded webview has established the proxy session.\n\n{{\u003c admonition type=\"note\" \u003e}}\nCompanion does not and cannot read cookies from the user\u2019s Sambee frontend browser session.\n{{\u003c /admonition \u003e}}\n\nOperationally, that means you should test both the browser UI and a real Companion native-edit session when introducing or changing proxy auth. A useful native-edit test signs in through the Companion authentication window, opens an SMB-backed file in a desktop app, uploads or closes the edit session, and confirms that lock release works without a second unexpected login prompt.\n", "0.9": "+++\ntitle = \"Put Sambee behind a Reverse Proxy\"\n+++\n\nFor production-style deployments, place a reverse proxy in front of Sambee to handle HTTPS.\n\n## Why Use a Reverse Proxy\n\nA reverse proxy gives you a cleaner operational model for:\n\n- HTTPS and certificate management\n- A stable hostname and routing layer in front of the container\n\n## Caddy Example\n\nIf you already run a dockerized Caddy environment, the Sambee service can be connected to that network with a compose layout like this:\n\n```yaml\nservices:\n  sambee:\n    container_name: sambee\n    hostname: sambee\n    build: .\n    restart: unless-stopped\n    networks:\n      - caddy_caddynet\n    expose:\n      - \"8000\"\n    volumes:\n      - ./data:/app/data\n      # Optional:\n      # - ./config.toml:/app/config.toml:ro\n\nnetworks:\n  caddy_caddynet:\n    external: true\n```\n\nHere, `expose` makes Sambee's port `8000` available to other containers on the same Docker network without publishing it directly to the host.\n\nThe important point is that Sambee serves plain HTTP to the reverse proxy and does not act as the HTTPS edge itself.\n\n## Companion Native Editing Behind Interactive Auth\n\nIf your reverse proxy protects the Sambee backend with an interactive login flow, Companion native editing can still work, but the proxy setup has to satisfy a few constraints.\n\nThe Companion runtime opens its own `Sambee Authentication` webview when reverse-proxy auth intercepts backend API calls. After the user signs in there, Companion reuses backend-origin cookies from that embedded webview for its Rust-side API requests.\n\nFor that to work reliably:\n\n- The reverse-proxy cookie must be valid for the Sambee backend origin that Companion calls.\n- The login flow must work inside the system webview used by Tauri on the target desktop platform.\n- The proxy must not depend on browser features that are unavailable in that embedded webview.\n- The proxy must allow authenticated requests to the Companion backend endpoints after the embedded webview has established the proxy session.\n\n{{\u003c admonition type=\"note\" \u003e}}\nCompanion does not and cannot read cookies from the user\u2019s Sambee frontend browser session.\n{{\u003c /admonition \u003e}}\n\nOperationally, that means you should test both the browser UI and a real Companion native-edit session when introducing or changing proxy auth. A useful native-edit test signs in through the Companion authentication window, opens an SMB-backed file in a desktop app, uploads or closes the edit session, and confirms that lock release works without a second unexpected login prompt.\n", "1.0": "+++\ntitle = \"Put Sambee behind a Reverse Proxy\"\n+++\n\nFor production-style deployments, place a reverse proxy in front of Sambee to handle HTTPS.\n\n## Why Use a Reverse Proxy\n\nA reverse proxy gives you a cleaner operational model for:\n\n- HTTPS and certificate management\n- A stable hostname and routing layer in front of the container\n\n## Caddy Example\n\nIf you already run a dockerized Caddy environment, the Sambee service can be connected to that network with a compose layout like this:\n\n```yaml\nservices:\n  sambee:\n    container_name: sambee\n    hostname: sambee\n    build: .\n    restart: unless-stopped\n    networks:\n      - caddy_caddynet\n    expose:\n      - \"8000\"\n    volumes:\n      - ./data:/app/data\n      # Optional:\n      # - ./config.toml:/app/config.toml:ro\n\nnetworks:\n  caddy_caddynet:\n    external: true\n```\n\nHere, `expose` makes Sambee's port `8000` available to other containers on the same Docker network without publishing it directly to the host.\n\nThe important point is that Sambee serves plain HTTP to the reverse proxy and does not act as the HTTPS edge itself.\n\n## Companion Native Editing Behind Interactive Auth\n\nIf your reverse proxy protects the Sambee backend with an interactive login flow, Companion native editing can still work, but the proxy setup has to satisfy a few constraints.\n\nThe Companion runtime opens its own `Sambee Authentication` webview when reverse-proxy auth intercepts backend API calls. After the user signs in there, Companion reuses backend-origin cookies from that embedded webview for its Rust-side API requests.\n\nFor that to work reliably:\n\n- The reverse-proxy cookie must be valid for the Sambee backend origin that Companion calls.\n- The login flow must work inside the system webview used by Tauri on the target desktop platform.\n- The proxy must not depend on browser features that are unavailable in that embedded webview.\n- The proxy must allow authenticated requests to the Companion backend endpoints after the embedded webview has established the proxy session.\n\n{{\u003c admonition type=\"note\" \u003e}}\nCompanion does not and cannot read cookies from the user\u2019s Sambee frontend browser session.\n{{\u003c /admonition \u003e}}\n\nOperationally, that means you should test both the browser UI and a real Companion native-edit session when introducing or changing proxy auth. A useful native-edit test signs in through the Companion authentication window, opens an SMB-backed file in a desktop app, uploads or closes the edit session, and confirms that lock release works without a second unexpected login prompt.\n", "2.0": "+++\ntitle = \"Put Sambee behind a Reverse Proxy\"\n+++\n\nFor production-style deployments, place a reverse proxy in front of Sambee to handle HTTPS.\n\n## Why Use a Reverse Proxy\n\nA reverse proxy gives you a cleaner operational model for:\n\n- HTTPS and certificate management\n- A stable hostname and routing layer in front of the container\n\n## Caddy Example\n\nIf you already run a dockerized Caddy environment, the Sambee service can be connected to that network with a compose layout like this:\n\n```yaml\nservices:\n  sambee:\n    container_name: sambee\n    hostname: sambee\n    build: .\n    restart: unless-stopped\n    networks:\n      - caddy_caddynet\n    expose:\n      - \"8000\"\n    volumes:\n      - ./data:/app/data\n      # Optional:\n      # - ./config.toml:/app/config.toml:ro\n\nnetworks:\n  caddy_caddynet:\n    external: true\n```\n\nHere, `expose` makes Sambee's port `8000` available to other containers on the same Docker network without publishing it directly to the host.\n\nThe important point is that Sambee serves plain HTTP to the reverse proxy and does not act as the HTTPS edge itself.\n\n## Companion Native Editing Behind Interactive Auth\n\nIf your reverse proxy protects the Sambee backend with an interactive login flow, Companion native editing can still work, but the proxy setup has to satisfy a few constraints.\n\nThe Companion runtime opens its own `Sambee Authentication` webview when reverse-proxy auth intercepts backend API calls. After the user signs in there, Companion reuses backend-origin cookies from that embedded webview for its Rust-side API requests.\n\nFor that to work reliably:\n\n- The reverse-proxy cookie must be valid for the Sambee backend origin that Companion calls.\n- The login flow must work inside the system webview used by Tauri on the target desktop platform.\n- The proxy must not depend on browser features that are unavailable in that embedded webview.\n- The proxy must allow authenticated requests to the Companion backend endpoints after the embedded webview has established the proxy session.\n\n{{\u003c admonition type=\"note\" \u003e}}\nCompanion does not and cannot read cookies from the user\u2019s Sambee frontend browser session.\n{{\u003c /admonition \u003e}}\n\nOperationally, that means you should test both the browser UI and a real Companion native-edit session when introducing or changing proxy auth. A useful native-edit test signs in through the Companion authentication window, opens an SMB-backed file in a desktop app, uploads or closes the edit session, and confirms that lock release works without a second unexpected login prompt.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Put Sambee behind a Reverse Proxy\"\n+++\n\nFor production-style deployments, place a reverse proxy in front of Sambee to handle HTTPS.\n\n## Why Use a Reverse Proxy\n\nA reverse proxy gives you a cleaner operational model for:\n\n- HTTPS and certificate management\n- A stable hostname and routing layer in front of the container\n\n## Caddy Example\n\nIf you already run a dockerized Caddy environment, the Sambee service can be connected to that network with a compose layout like this:\n\n```yaml\nservices:\n  sambee:\n    container_name: sambee\n    hostname: sambee\n    build: .\n    restart: unless-stopped\n    networks:\n      - caddy_caddynet\n    expose:\n      - \"8000\"\n    volumes:\n      - ./data:/app/data\n      # Optional:\n      # - ./config.toml:/app/config.toml:ro\n\nnetworks:\n  caddy_caddynet:\n    external: true\n```\n\nHere, `expose` makes Sambee's port `8000` available to other containers on the same Docker network without publishing it directly to the host.\n\nThe important point is that Sambee serves plain HTTP to the reverse proxy and does not act as the HTTPS edge itself.\n\n## Companion Native Editing Behind Interactive Auth\n\nIf your reverse proxy protects the Sambee backend with an interactive login flow, Companion native editing can still work, but the proxy setup has to satisfy a few constraints.\n\nThe Companion runtime opens its own `Sambee Authentication` webview when reverse-proxy auth intercepts backend API calls. After the user signs in there, Companion reuses backend-origin cookies from that embedded webview for its Rust-side API requests.\n\nFor that to work reliably:\n\n- The reverse-proxy cookie must be valid for the Sambee backend origin that Companion calls.\n- The login flow must work inside the system webview used by Tauri on the target desktop platform.\n- The proxy must not depend on browser features that are unavailable in that embedded webview.\n- The proxy must allow authenticated requests to the Companion backend endpoints after the embedded webview has established the proxy session.\n\n{{\u003c admonition type=\"note\" \u003e}}\nCompanion does not and cannot read cookies from the user\u2019s Sambee frontend browser session.\n{{\u003c /admonition \u003e}}\n\nOperationally, that means you should test both the browser UI and a real Companion native-edit session when introducing or changing proxy auth. A useful native-edit test signs in through the Companion authentication window, opens an SMB-backed file in a desktop app, uploads or closes the edit session, and confirms that lock release works without a second unexpected login prompt.\n", "0.8": "+++\ntitle = \"Put Sambee behind a Reverse Proxy\"\n+++\n\nFor production-style deployments, place a reverse proxy in front of Sambee to handle HTTPS.\n\n## Why Use a Reverse Proxy\n\nA reverse proxy gives you a cleaner operational model for:\n\n- HTTPS and certificate management\n- A stable hostname and routing layer in front of the container\n\n## Caddy Example\n\nIf you already run a dockerized Caddy environment, the Sambee service can be connected to that network with a compose layout like this:\n\n```yaml\nservices:\n  sambee:\n    container_name: sambee\n    hostname: sambee\n    build: .\n    restart: unless-stopped\n    networks:\n      - caddy_caddynet\n    expose:\n      - \"8000\"\n    volumes:\n      - ./data:/app/data\n      # Optional:\n      # - ./config.toml:/app/config.toml:ro\n\nnetworks:\n  caddy_caddynet:\n    external: true\n```\n\nHere, `expose` makes Sambee's port `8000` available to other containers on the same Docker network without publishing it directly to the host.\n\nThe important point is that Sambee serves plain HTTP to the reverse proxy and does not act as the HTTPS edge itself.\n\n## Companion Native Editing Behind Interactive Auth\n\nIf your reverse proxy protects the Sambee backend with an interactive login flow, Companion native editing can still work, but the proxy setup has to satisfy a few constraints.\n\nThe Companion runtime opens its own `Sambee Authentication` webview when reverse-proxy auth intercepts backend API calls. After the user signs in there, Companion reuses backend-origin cookies from that embedded webview for its Rust-side API requests.\n\nFor that to work reliably:\n\n- The reverse-proxy cookie must be valid for the Sambee backend origin that Companion calls.\n- The login flow must work inside the system webview used by Tauri on the target desktop platform.\n- The proxy must not depend on browser features that are unavailable in that embedded webview.\n- The proxy must allow authenticated requests to the Companion backend endpoints after the embedded webview has established the proxy session.\n\n{{\u003c admonition type=\"note\" \u003e}}\nCompanion does not and cannot read cookies from the user\u2019s Sambee frontend browser session.\n{{\u003c /admonition \u003e}}\n\nOperationally, that means you should test both the browser UI and a real Companion native-edit session when introducing or changing proxy auth. A useful native-edit test signs in through the Companion authentication window, opens an SMB-backed file in a desktop app, uploads or closes the edit session, and confirms that lock release works without a second unexpected login prompt.\n", "0.9": "+++\ntitle = \"Put Sambee behind a Reverse Proxy\"\n+++\n\nFor production-style deployments, place a reverse proxy in front of Sambee to handle HTTPS.\n\n## Why Use a Reverse Proxy\n\nA reverse proxy gives you a cleaner operational model for:\n\n- HTTPS and certificate management\n- A stable hostname and routing layer in front of the container\n\n## Caddy Example\n\nIf you already run a dockerized Caddy environment, the Sambee service can be connected to that network with a compose layout like this:\n\n```yaml\nservices:\n  sambee:\n    container_name: sambee\n    hostname: sambee\n    build: .\n    restart: unless-stopped\n    networks:\n      - caddy_caddynet\n    expose:\n      - \"8000\"\n    volumes:\n      - ./data:/app/data\n      # Optional:\n      # - ./config.toml:/app/config.toml:ro\n\nnetworks:\n  caddy_caddynet:\n    external: true\n```\n\nHere, `expose` makes Sambee's port `8000` available to other containers on the same Docker network without publishing it directly to the host.\n\nThe important point is that Sambee serves plain HTTP to the reverse proxy and does not act as the HTTPS edge itself.\n\n## Companion Native Editing Behind Interactive Auth\n\nIf your reverse proxy protects the Sambee backend with an interactive login flow, Companion native editing can still work, but the proxy setup has to satisfy a few constraints.\n\nThe Companion runtime opens its own `Sambee Authentication` webview when reverse-proxy auth intercepts backend API calls. After the user signs in there, Companion reuses backend-origin cookies from that embedded webview for its Rust-side API requests.\n\nFor that to work reliably:\n\n- The reverse-proxy cookie must be valid for the Sambee backend origin that Companion calls.\n- The login flow must work inside the system webview used by Tauri on the target desktop platform.\n- The proxy must not depend on browser features that are unavailable in that embedded webview.\n- The proxy must allow authenticated requests to the Companion backend endpoints after the embedded webview has established the proxy session.\n\n{{\u003c admonition type=\"note\" \u003e}}\nCompanion does not and cannot read cookies from the user\u2019s Sambee frontend browser session.\n{{\u003c /admonition \u003e}}\n\nOperationally, that means you should test both the browser UI and a real Companion native-edit session when introducing or changing proxy auth. A useful native-edit test signs in through the Companion authentication window, opens an SMB-backed file in a desktop app, uploads or closes the edit session, and confirms that lock release works without a second unexpected login prompt.\n", "1.0": "+++\ntitle = \"Put Sambee behind a Reverse Proxy\"\n+++\n\nFor production-style deployments, place a reverse proxy in front of Sambee to handle HTTPS.\n\n## Why Use a Reverse Proxy\n\nA reverse proxy gives you a cleaner operational model for:\n\n- HTTPS and certificate management\n- A stable hostname and routing layer in front of the container\n\n## Caddy Example\n\nIf you already run a dockerized Caddy environment, the Sambee service can be connected to that network with a compose layout like this:\n\n```yaml\nservices:\n  sambee:\n    container_name: sambee\n    hostname: sambee\n    build: .\n    restart: unless-stopped\n    networks:\n      - caddy_caddynet\n    expose:\n      - \"8000\"\n    volumes:\n      - ./data:/app/data\n      # Optional:\n      # - ./config.toml:/app/config.toml:ro\n\nnetworks:\n  caddy_caddynet:\n    external: true\n```\n\nHere, `expose` makes Sambee's port `8000` available to other containers on the same Docker network without publishing it directly to the host.\n\nThe important point is that Sambee serves plain HTTP to the reverse proxy and does not act as the HTTPS edge itself.\n\n## Companion Native Editing Behind Interactive Auth\n\nIf your reverse proxy protects the Sambee backend with an interactive login flow, Companion native editing can still work, but the proxy setup has to satisfy a few constraints.\n\nThe Companion runtime opens its own `Sambee Authentication` webview when reverse-proxy auth intercepts backend API calls. After the user signs in there, Companion reuses backend-origin cookies from that embedded webview for its Rust-side API requests.\n\nFor that to work reliably:\n\n- The reverse-proxy cookie must be valid for the Sambee backend origin that Companion calls.\n- The login flow must work inside the system webview used by Tauri on the target desktop platform.\n- The proxy must not depend on browser features that are unavailable in that embedded webview.\n- The proxy must allow authenticated requests to the Companion backend endpoints after the embedded webview has established the proxy session.\n\n{{\u003c admonition type=\"note\" \u003e}}\nCompanion does not and cannot read cookies from the user\u2019s Sambee frontend browser session.\n{{\u003c /admonition \u003e}}\n\nOperationally, that means you should test both the browser UI and a real Companion native-edit session when introducing or changing proxy auth. A useful native-edit test signs in through the Companion authentication window, opens an SMB-backed file in a desktop app, uploads or closes the edit session, and confirms that lock release works without a second unexpected login prompt.\n", "2.0": "+++\ntitle = \"Put Sambee behind a Reverse Proxy\"\n+++\n\nFor production-style deployments, place a reverse proxy in front of Sambee to handle HTTPS.\n\n## Why Use a Reverse Proxy\n\nA reverse proxy gives you a cleaner operational model for:\n\n- HTTPS and certificate management\n- A stable hostname and routing layer in front of the container\n\n## Caddy Example\n\nIf you already run a dockerized Caddy environment, the Sambee service can be connected to that network with a compose layout like this:\n\n```yaml\nservices:\n  sambee:\n    container_name: sambee\n    hostname: sambee\n    build: .\n    restart: unless-stopped\n    networks:\n      - caddy_caddynet\n    expose:\n      - \"8000\"\n    volumes:\n      - ./data:/app/data\n      # Optional:\n      # - ./config.toml:/app/config.toml:ro\n\nnetworks:\n  caddy_caddynet:\n    external: true\n```\n\nHere, `expose` makes Sambee's port `8000` available to other containers on the same Docker network without publishing it directly to the host.\n\nThe important point is that Sambee serves plain HTTP to the reverse proxy and does not act as the HTTPS edge itself.\n\n## Companion Native Editing Behind Interactive Auth\n\nIf your reverse proxy protects the Sambee backend with an interactive login flow, Companion native editing can still work, but the proxy setup has to satisfy a few constraints.\n\nThe Companion runtime opens its own `Sambee Authentication` webview when reverse-proxy auth intercepts backend API calls. After the user signs in there, Companion reuses backend-origin cookies from that embedded webview for its Rust-side API requests.\n\nFor that to work reliably:\n\n- The reverse-proxy cookie must be valid for the Sambee backend origin that Companion calls.\n- The login flow must work inside the system webview used by Tauri on the target desktop platform.\n- The proxy must not depend on browser features that are unavailable in that embedded webview.\n- The proxy must allow authenticated requests to the Companion backend endpoints after the embedded webview has established the proxy session.\n\n{{\u003c admonition type=\"note\" \u003e}}\nCompanion does not and cannot read cookies from the user\u2019s Sambee frontend browser session.\n{{\u003c /admonition \u003e}}\n\nOperationally, that means you should test both the browser UI and a real Companion native-edit session when introducing or changing proxy auth. A useful native-edit test signs in through the Companion authentication window, opens an SMB-backed file in a desktop app, uploads or closes the edit session, and confirms that lock release works without a second unexpected login prompt.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:admin-guide/network-and-reverse-proxy/network-settings", "parent_id": "section:admin-guide/network-and-reverse-proxy", "depth": 2, "kind": "page", "label": "network-settings", "title": "Network Settings", "path": "admin-guide/network-and-reverse-proxy/network-settings", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "authored"}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "inherited", "source_version": "0.9"}}, "content_versions": {"0.9": "+++\ntitle = \"Network Settings\"\n+++\n\nOpen **Settings** \u003e **Administration** \u003e **Network** to configure the settings Sambee uses for external URLs and reverse-proxy client addresses.\n\n## Public URL\n\nSet **Public URL** to Sambee's externally reachable HTTPS origin, for example:\n\n```text\nhttps://files.example.com\n```\n\nDo not include a path. Changing the public URL cancels incomplete OIDC sign-ins and tests.\n\n## Trusted Reverse Proxy CIDRs\n\nConfigure **Trusted reverse proxy CIDRs** only when all of the following is true:\n\n- A reverse proxy sits in front of Sambee.\n- The proxy forwards the original visitor IP address.\n- You want Sambee to use that address for authentication request limits.\n\nEnter the IP addresses or network ranges of the proxies that connect directly to Sambee. Do not enter end-user networks or arbitrary private ranges.\n\n### Example\n\nIf Nginx at `10.20.30.15` is the only server that can reach Sambee and it forwards `X-Forwarded-For`, enter `10.20.30.15/32`.\n\n", "1.0": "+++\ntitle = \"Network Settings\"\n+++\n\nOpen **Settings** \u003e **Administration** \u003e **Network** to configure the settings Sambee uses for external URLs and reverse-proxy client addresses.\n\n## Public URL\n\nSet **Public URL** to Sambee's externally reachable HTTPS origin, for example:\n\n```text\nhttps://files.example.com\n```\n\nDo not include a path. Changing the public URL cancels incomplete OIDC sign-ins and tests.\n\n## Trusted Reverse Proxy CIDRs\n\nConfigure **Trusted reverse proxy CIDRs** only when all of the following is true:\n\n- A reverse proxy sits in front of Sambee.\n- The proxy forwards the original visitor IP address.\n- You want Sambee to use that address for authentication request limits.\n\nEnter the IP addresses or network ranges of the proxies that connect directly to Sambee. Do not enter end-user networks or arbitrary private ranges.\n\n### Example\n\nIf Nginx at `10.20.30.15` is the only server that can reach Sambee and it forwards `X-Forwarded-For`, enter `10.20.30.15/32`.\n\n", "2.0": "+++\ntitle = \"Network Settings\"\n+++\n\nOpen **Settings** \u003e **Administration** \u003e **Network** to configure the settings Sambee uses for external URLs and reverse-proxy client addresses.\n\n## Public URL\n\nSet **Public URL** to Sambee's externally reachable HTTPS origin, for example:\n\n```text\nhttps://files.example.com\n```\n\nDo not include a path. Changing the public URL cancels incomplete OIDC sign-ins and tests.\n\n## Trusted Reverse Proxy CIDRs\n\nConfigure **Trusted reverse proxy CIDRs** only when all of the following is true:\n\n- A reverse proxy sits in front of Sambee.\n- The proxy forwards the original visitor IP address.\n- You want Sambee to use that address for authentication request limits.\n\nEnter the IP addresses or network ranges of the proxies that connect directly to Sambee. Do not enter end-user networks or arbitrary private ranges.\n\n### Example\n\nIf Nginx at `10.20.30.15` is the only server that can reach Sambee and it forwards `X-Forwarded-For`, enter `10.20.30.15/32`.\n\n"}, "page_contents": {"0.9": "+++\ntitle = \"Network Settings\"\n+++\n\nOpen **Settings** \u003e **Administration** \u003e **Network** to configure the settings Sambee uses for external URLs and reverse-proxy client addresses.\n\n## Public URL\n\nSet **Public URL** to Sambee's externally reachable HTTPS origin, for example:\n\n```text\nhttps://files.example.com\n```\n\nDo not include a path. Changing the public URL cancels incomplete OIDC sign-ins and tests.\n\n## Trusted Reverse Proxy CIDRs\n\nConfigure **Trusted reverse proxy CIDRs** only when all of the following is true:\n\n- A reverse proxy sits in front of Sambee.\n- The proxy forwards the original visitor IP address.\n- You want Sambee to use that address for authentication request limits.\n\nEnter the IP addresses or network ranges of the proxies that connect directly to Sambee. Do not enter end-user networks or arbitrary private ranges.\n\n### Example\n\nIf Nginx at `10.20.30.15` is the only server that can reach Sambee and it forwards `X-Forwarded-For`, enter `10.20.30.15/32`.\n\n", "1.0": "+++\ntitle = \"Network Settings\"\n+++\n\nOpen **Settings** \u003e **Administration** \u003e **Network** to configure the settings Sambee uses for external URLs and reverse-proxy client addresses.\n\n## Public URL\n\nSet **Public URL** to Sambee's externally reachable HTTPS origin, for example:\n\n```text\nhttps://files.example.com\n```\n\nDo not include a path. Changing the public URL cancels incomplete OIDC sign-ins and tests.\n\n## Trusted Reverse Proxy CIDRs\n\nConfigure **Trusted reverse proxy CIDRs** only when all of the following is true:\n\n- A reverse proxy sits in front of Sambee.\n- The proxy forwards the original visitor IP address.\n- You want Sambee to use that address for authentication request limits.\n\nEnter the IP addresses or network ranges of the proxies that connect directly to Sambee. Do not enter end-user networks or arbitrary private ranges.\n\n### Example\n\nIf Nginx at `10.20.30.15` is the only server that can reach Sambee and it forwards `X-Forwarded-For`, enter `10.20.30.15/32`.\n\n", "2.0": "+++\ntitle = \"Network Settings\"\n+++\n\nOpen **Settings** \u003e **Administration** \u003e **Network** to configure the settings Sambee uses for external URLs and reverse-proxy client addresses.\n\n## Public URL\n\nSet **Public URL** to Sambee's externally reachable HTTPS origin, for example:\n\n```text\nhttps://files.example.com\n```\n\nDo not include a path. Changing the public URL cancels incomplete OIDC sign-ins and tests.\n\n## Trusted Reverse Proxy CIDRs\n\nConfigure **Trusted reverse proxy CIDRs** only when all of the following is true:\n\n- A reverse proxy sits in front of Sambee.\n- The proxy forwards the original visitor IP address.\n- You want Sambee to use that address for authentication request limits.\n\nEnter the IP addresses or network ranges of the proxies that connect directly to Sambee. Do not enter end-user networks or arbitrary private ranges.\n\n### Example\n\nIf Nginx at `10.20.30.15` is the only server that can reach Sambee and it forwards `X-Forwarded-For`, enter `10.20.30.15/32`.\n\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:admin-guide/configuration", "parent_id": "book:admin-guide", "depth": 1, "kind": "section", "label": "configuration", "title": "Configuration", "path": "admin-guide/configuration", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "missing"}, "1.0": {"state": "missing"}, "2.0": {"state": "missing"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:admin-guide/configuration/configuration-key-reference", "parent_id": "section:admin-guide/configuration", "depth": 2, "kind": "page", "label": "configuration-key-reference", "title": "Configuration Key Reference", "path": "admin-guide/configuration/configuration-key-reference", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "missing"}, "1.0": {"state": "missing"}, "2.0": {"state": "missing"}}, "content_versions": {"0.7": "+++\ntitle = \"Configuration Key Reference\"\n+++\n\nThis page is a compact map of the optional `config.toml` file.\n\nUse `config.example.toml` as the source of truth for supported keys. This page explains the sections that matter most in day-to-day administration.\n\n## How to Use This Reference\n\n- Copy only the keys you actually need into the local `config.toml`.\n- Keep the file local to the deployment and mount it read-only in production.\n- Treat commented defaults in `config.example.toml` as the baseline behavior unless you override them intentionally.\n- Expect most basic deployments to use only a small subset of these keys.\n\n## High-Value Sections and Keys\n\n| Section | Key | Operational effect |\n|---|---|---|\n| `[app]` | `log_level` | Sets backend log verbosity |\n| `[security]` | `auth_method` | Chooses between built-in password auth and proxy-managed auth |\n| `[security]` | `access_token_expire_minutes` | Changes session-token lifetime |\n| `[admin]` | `username` | Sets the initial administrator username |\n| `[image_viewer]` | `conv_size_thresh` | Controls when large images are always converted for viewing |\n| `[frontend_logging]` | `logging_enabled`, `log_level` | Controls browser-console logging behavior |\n| `[frontend_logging]` | `tracing_enabled`, `tracing_level`, `tracing_retention_hours` | Controls backend trace collection for frontend logging |\n| `[frontend_logging]` | `tracing_components`, `tracing_username_regex` | Restricts tracing by component or user scope |\n| `[directory_cache]` | `location`, `coalesce_interval_seconds`, `max_staleness_minutes` | Controls the saved directory index Sambee keeps to make browsing and search recover faster after restarts |\n| `[smb]` | `read_chunk_size_bytes` | Changes SMB read chunk size |\n| `[preprocessors.imagemagick]` | `max_file_size_bytes`, `timeout_seconds` | Sets conversion limits for ImageMagick preprocessing |\n| `[companion_downloads]` | `metadata_feed_url` | Changes where Sambee resolves Companion download metadata |\n| `[companion_downloads.pin]` | `version`, `published_at`, `notes`, asset URLs | Pins Companion download links to a specific published release instead of following the promoted feed |\n\n## Keys That Deserve Extra Care\n\nThese areas have the highest operational impact:\n\n- `auth_method`: Can change who is responsible for authentication at the deployment boundary.\n- Frontend logging and tracing keys: Can change both local debugging visibility and backend trace collection volume.\n- `directory_cache.location`: Changes where the saved SMB directory index lives on disk.\n- Companion download keys: Change what download links Sambee presents to users.\n", "0.8": "+++\ntitle = \"Configuration Key Reference\"\n+++\n\nThis page is a compact map of the optional `config.toml` file.\n\nUse `config.example.toml` as the source of truth for supported keys. This page explains the sections that matter most in day-to-day administration.\n\n## How to Use This Reference\n\n- Copy only the keys you actually need into the local `config.toml`.\n- Keep the file local to the deployment and mount it read-only in production.\n- Treat commented defaults in `config.example.toml` as the baseline behavior unless you override them intentionally.\n- Expect most basic deployments to use only a small subset of these keys.\n\n## High-Value Sections and Keys\n\n| Section | Key | Operational effect |\n|---|---|---|\n| `[app]` | `log_level` | Sets backend log verbosity |\n| `[security]` | `auth_method` | Chooses between built-in password auth and proxy-managed auth |\n| `[security]` | `access_token_expire_minutes` | Changes session-token lifetime |\n| `[admin]` | `username` | Sets the initial administrator username |\n| `[image_viewer]` | `conv_size_thresh` | Controls when large images are always converted for viewing |\n| `[frontend_logging]` | `logging_enabled`, `log_level` | Controls browser-console logging behavior |\n| `[frontend_logging]` | `tracing_enabled`, `tracing_level`, `tracing_retention_hours` | Controls backend trace collection for frontend logging |\n| `[frontend_logging]` | `tracing_components`, `tracing_username_regex` | Restricts tracing by component or user scope |\n| `[directory_cache]` | `location`, `coalesce_interval_seconds`, `max_staleness_minutes` | Controls the saved directory index Sambee keeps to make browsing and search recover faster after restarts |\n| `[smb]` | `read_chunk_size_bytes` | Changes SMB read chunk size |\n| `[preprocessors.imagemagick]` | `max_file_size_bytes`, `timeout_seconds` | Sets conversion limits for ImageMagick preprocessing |\n| `[companion_downloads]` | `metadata_feed_url` | Changes where Sambee resolves Companion download metadata |\n| `[companion_downloads.pin]` | `version`, `published_at`, `notes`, asset URLs | Pins Companion download links to a specific published release instead of following the promoted feed |\n\n## Keys That Deserve Extra Care\n\nThese areas have the highest operational impact:\n\n- `auth_method`: Can change who is responsible for authentication at the deployment boundary.\n- Frontend logging and tracing keys: Can change both local debugging visibility and backend trace collection volume.\n- `directory_cache.location`: Changes where the saved SMB directory index lives on disk.\n- Companion download keys: Change what download links Sambee presents to users.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Configuration Key Reference\"\n+++\n\nThis page is a compact map of the optional `config.toml` file.\n\nUse `config.example.toml` as the source of truth for supported keys. This page explains the sections that matter most in day-to-day administration.\n\n## How to Use This Reference\n\n- Copy only the keys you actually need into the local `config.toml`.\n- Keep the file local to the deployment and mount it read-only in production.\n- Treat commented defaults in `config.example.toml` as the baseline behavior unless you override them intentionally.\n- Expect most basic deployments to use only a small subset of these keys.\n\n## High-Value Sections and Keys\n\n| Section | Key | Operational effect |\n|---|---|---|\n| `[app]` | `log_level` | Sets backend log verbosity |\n| `[security]` | `auth_method` | Chooses between built-in password auth and proxy-managed auth |\n| `[security]` | `access_token_expire_minutes` | Changes session-token lifetime |\n| `[admin]` | `username` | Sets the initial administrator username |\n| `[image_viewer]` | `conv_size_thresh` | Controls when large images are always converted for viewing |\n| `[frontend_logging]` | `logging_enabled`, `log_level` | Controls browser-console logging behavior |\n| `[frontend_logging]` | `tracing_enabled`, `tracing_level`, `tracing_retention_hours` | Controls backend trace collection for frontend logging |\n| `[frontend_logging]` | `tracing_components`, `tracing_username_regex` | Restricts tracing by component or user scope |\n| `[directory_cache]` | `location`, `coalesce_interval_seconds`, `max_staleness_minutes` | Controls the saved directory index Sambee keeps to make browsing and search recover faster after restarts |\n| `[smb]` | `read_chunk_size_bytes` | Changes SMB read chunk size |\n| `[preprocessors.imagemagick]` | `max_file_size_bytes`, `timeout_seconds` | Sets conversion limits for ImageMagick preprocessing |\n| `[companion_downloads]` | `metadata_feed_url` | Changes where Sambee resolves Companion download metadata |\n| `[companion_downloads.pin]` | `version`, `published_at`, `notes`, asset URLs | Pins Companion download links to a specific published release instead of following the promoted feed |\n\n## Keys That Deserve Extra Care\n\nThese areas have the highest operational impact:\n\n- `auth_method`: Can change who is responsible for authentication at the deployment boundary.\n- Frontend logging and tracing keys: Can change both local debugging visibility and backend trace collection volume.\n- `directory_cache.location`: Changes where the saved SMB directory index lives on disk.\n- Companion download keys: Change what download links Sambee presents to users.\n", "0.8": "+++\ntitle = \"Configuration Key Reference\"\n+++\n\nThis page is a compact map of the optional `config.toml` file.\n\nUse `config.example.toml` as the source of truth for supported keys. This page explains the sections that matter most in day-to-day administration.\n\n## How to Use This Reference\n\n- Copy only the keys you actually need into the local `config.toml`.\n- Keep the file local to the deployment and mount it read-only in production.\n- Treat commented defaults in `config.example.toml` as the baseline behavior unless you override them intentionally.\n- Expect most basic deployments to use only a small subset of these keys.\n\n## High-Value Sections and Keys\n\n| Section | Key | Operational effect |\n|---|---|---|\n| `[app]` | `log_level` | Sets backend log verbosity |\n| `[security]` | `auth_method` | Chooses between built-in password auth and proxy-managed auth |\n| `[security]` | `access_token_expire_minutes` | Changes session-token lifetime |\n| `[admin]` | `username` | Sets the initial administrator username |\n| `[image_viewer]` | `conv_size_thresh` | Controls when large images are always converted for viewing |\n| `[frontend_logging]` | `logging_enabled`, `log_level` | Controls browser-console logging behavior |\n| `[frontend_logging]` | `tracing_enabled`, `tracing_level`, `tracing_retention_hours` | Controls backend trace collection for frontend logging |\n| `[frontend_logging]` | `tracing_components`, `tracing_username_regex` | Restricts tracing by component or user scope |\n| `[directory_cache]` | `location`, `coalesce_interval_seconds`, `max_staleness_minutes` | Controls the saved directory index Sambee keeps to make browsing and search recover faster after restarts |\n| `[smb]` | `read_chunk_size_bytes` | Changes SMB read chunk size |\n| `[preprocessors.imagemagick]` | `max_file_size_bytes`, `timeout_seconds` | Sets conversion limits for ImageMagick preprocessing |\n| `[companion_downloads]` | `metadata_feed_url` | Changes where Sambee resolves Companion download metadata |\n| `[companion_downloads.pin]` | `version`, `published_at`, `notes`, asset URLs | Pins Companion download links to a specific published release instead of following the promoted feed |\n\n## Keys That Deserve Extra Care\n\nThese areas have the highest operational impact:\n\n- `auth_method`: Can change who is responsible for authentication at the deployment boundary.\n- Frontend logging and tracing keys: Can change both local debugging visibility and backend trace collection volume.\n- `directory_cache.location`: Changes where the saved SMB directory index lives on disk.\n- Companion download keys: Change what download links Sambee presents to users.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:admin-guide/operations-and-maintenance", "parent_id": "book:admin-guide", "depth": 1, "kind": "section", "label": "operations-and-maintenance", "title": "Operations and Maintenance", "path": "admin-guide/operations-and-maintenance", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:admin-guide/operations-and-maintenance/view-logs-and-restart-services", "parent_id": "section:admin-guide/operations-and-maintenance", "depth": 2, "kind": "page", "label": "view-logs-and-restart-services", "title": "View Logs And Restart Services", "path": "admin-guide/operations-and-maintenance/view-logs-and-restart-services", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"View Logs and Restart Services\"\n+++\n\nOnce Sambee is in service, logs and controlled restarts are the core day-to-day admin tools.\n\n## View Logs\n\nTo follow logs for all services:\n\n```bash\ndocker compose logs -f\n```\n\nTo focus on the Sambee service only:\n\n```bash\ndocker compose logs -f sambee\n```\n\nUse the service-specific view first when the issue is clearly about the application itself.\n\nIf you only need recent startup output, use:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\n## Stop the Deployment\n\nTo stop the services:\n\n```bash\ndocker compose down\n```\n\nUse a full stop when you need to perform controlled maintenance, rebuild the image, or restore deployment files.\n\n## Restart as Part of Operations\n\nRoutine restarts are not a substitute for troubleshooting, but they are a legitimate step when:\n\n- You just changed deployment files.\n- You rebuilt the image.\n- You completed a controlled maintenance step.\n\nTo restart only the Sambee service:\n\n```bash\ndocker compose restart sambee\n```\n\nIf you restart repeatedly without understanding the failure, stop restarting and inspect the logs, deployment files, proxy path, and persistent data assumptions directly.\n", "0.8": "+++\ntitle = \"View Logs and Restart Services\"\n+++\n\nOnce Sambee is in service, logs and controlled restarts are the core day-to-day admin tools.\n\n## View Logs\n\nTo follow logs for all services:\n\n```bash\ndocker compose logs -f\n```\n\nTo focus on the Sambee service only:\n\n```bash\ndocker compose logs -f sambee\n```\n\nUse the service-specific view first when the issue is clearly about the application itself.\n\nIf you only need recent startup output, use:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\n## Stop the Deployment\n\nTo stop the services:\n\n```bash\ndocker compose down\n```\n\nUse a full stop when you need to perform controlled maintenance, rebuild the image, or restore deployment files.\n\n## Restart as Part of Operations\n\nRoutine restarts are not a substitute for troubleshooting, but they are a legitimate step when:\n\n- You just changed deployment files.\n- You rebuilt the image.\n- You completed a controlled maintenance step.\n\nTo restart only the Sambee service:\n\n```bash\ndocker compose restart sambee\n```\n\nIf you restart repeatedly without understanding the failure, stop restarting and inspect the logs, deployment files, proxy path, and persistent data assumptions directly.\n", "0.9": "+++\ntitle = \"View Logs and Restart Services\"\n+++\n\nOnce Sambee is in service, logs and controlled restarts are the core day-to-day admin tools.\n\n## View Logs\n\nTo follow logs for all services:\n\n```bash\ndocker compose logs -f\n```\n\nTo focus on the Sambee service only:\n\n```bash\ndocker compose logs -f sambee\n```\n\nUse the service-specific view first when the issue is clearly about the application itself.\n\nIf you only need recent startup output, use:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\n## Stop the Deployment\n\nTo stop the services:\n\n```bash\ndocker compose down\n```\n\nUse a full stop when you need to perform controlled maintenance, rebuild the image, or restore deployment files.\n\n## Restart as Part of Operations\n\nRoutine restarts are not a substitute for troubleshooting, but they are a legitimate step when:\n\n- You just changed deployment files.\n- You rebuilt the image.\n- You completed a controlled maintenance step.\n\nTo restart only the Sambee service:\n\n```bash\ndocker compose restart sambee\n```\n\nIf you restart repeatedly without understanding the failure, stop restarting and inspect the logs, deployment files, proxy path, and persistent data assumptions directly.\n", "1.0": "+++\ntitle = \"View Logs and Restart Services\"\n+++\n\nOnce Sambee is in service, logs and controlled restarts are the core day-to-day admin tools.\n\n## View Logs\n\nTo follow logs for all services:\n\n```bash\ndocker compose logs -f\n```\n\nTo focus on the Sambee service only:\n\n```bash\ndocker compose logs -f sambee\n```\n\nUse the service-specific view first when the issue is clearly about the application itself.\n\nIf you only need recent startup output, use:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\n## Stop the Deployment\n\nTo stop the services:\n\n```bash\ndocker compose down\n```\n\nUse a full stop when you need to perform controlled maintenance, rebuild the image, or restore deployment files.\n\n## Restart as Part of Operations\n\nRoutine restarts are not a substitute for troubleshooting, but they are a legitimate step when:\n\n- You just changed deployment files.\n- You rebuilt the image.\n- You completed a controlled maintenance step.\n\nTo restart only the Sambee service:\n\n```bash\ndocker compose restart sambee\n```\n\nIf you restart repeatedly without understanding the failure, stop restarting and inspect the logs, deployment files, proxy path, and persistent data assumptions directly.\n", "2.0": "+++\ntitle = \"View Logs and Restart Services\"\n+++\n\nOnce Sambee is in service, logs and controlled restarts are the core day-to-day admin tools.\n\n## View Logs\n\nTo follow logs for all services:\n\n```bash\ndocker compose logs -f\n```\n\nTo focus on the Sambee service only:\n\n```bash\ndocker compose logs -f sambee\n```\n\nUse the service-specific view first when the issue is clearly about the application itself.\n\nIf you only need recent startup output, use:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\n## Stop the Deployment\n\nTo stop the services:\n\n```bash\ndocker compose down\n```\n\nUse a full stop when you need to perform controlled maintenance, rebuild the image, or restore deployment files.\n\n## Restart as Part of Operations\n\nRoutine restarts are not a substitute for troubleshooting, but they are a legitimate step when:\n\n- You just changed deployment files.\n- You rebuilt the image.\n- You completed a controlled maintenance step.\n\nTo restart only the Sambee service:\n\n```bash\ndocker compose restart sambee\n```\n\nIf you restart repeatedly without understanding the failure, stop restarting and inspect the logs, deployment files, proxy path, and persistent data assumptions directly.\n"}, "page_contents": {"0.7": "+++\ntitle = \"View Logs and Restart Services\"\n+++\n\nOnce Sambee is in service, logs and controlled restarts are the core day-to-day admin tools.\n\n## View Logs\n\nTo follow logs for all services:\n\n```bash\ndocker compose logs -f\n```\n\nTo focus on the Sambee service only:\n\n```bash\ndocker compose logs -f sambee\n```\n\nUse the service-specific view first when the issue is clearly about the application itself.\n\nIf you only need recent startup output, use:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\n## Stop the Deployment\n\nTo stop the services:\n\n```bash\ndocker compose down\n```\n\nUse a full stop when you need to perform controlled maintenance, rebuild the image, or restore deployment files.\n\n## Restart as Part of Operations\n\nRoutine restarts are not a substitute for troubleshooting, but they are a legitimate step when:\n\n- You just changed deployment files.\n- You rebuilt the image.\n- You completed a controlled maintenance step.\n\nTo restart only the Sambee service:\n\n```bash\ndocker compose restart sambee\n```\n\nIf you restart repeatedly without understanding the failure, stop restarting and inspect the logs, deployment files, proxy path, and persistent data assumptions directly.\n", "0.8": "+++\ntitle = \"View Logs and Restart Services\"\n+++\n\nOnce Sambee is in service, logs and controlled restarts are the core day-to-day admin tools.\n\n## View Logs\n\nTo follow logs for all services:\n\n```bash\ndocker compose logs -f\n```\n\nTo focus on the Sambee service only:\n\n```bash\ndocker compose logs -f sambee\n```\n\nUse the service-specific view first when the issue is clearly about the application itself.\n\nIf you only need recent startup output, use:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\n## Stop the Deployment\n\nTo stop the services:\n\n```bash\ndocker compose down\n```\n\nUse a full stop when you need to perform controlled maintenance, rebuild the image, or restore deployment files.\n\n## Restart as Part of Operations\n\nRoutine restarts are not a substitute for troubleshooting, but they are a legitimate step when:\n\n- You just changed deployment files.\n- You rebuilt the image.\n- You completed a controlled maintenance step.\n\nTo restart only the Sambee service:\n\n```bash\ndocker compose restart sambee\n```\n\nIf you restart repeatedly without understanding the failure, stop restarting and inspect the logs, deployment files, proxy path, and persistent data assumptions directly.\n", "0.9": "+++\ntitle = \"View Logs and Restart Services\"\n+++\n\nOnce Sambee is in service, logs and controlled restarts are the core day-to-day admin tools.\n\n## View Logs\n\nTo follow logs for all services:\n\n```bash\ndocker compose logs -f\n```\n\nTo focus on the Sambee service only:\n\n```bash\ndocker compose logs -f sambee\n```\n\nUse the service-specific view first when the issue is clearly about the application itself.\n\nIf you only need recent startup output, use:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\n## Stop the Deployment\n\nTo stop the services:\n\n```bash\ndocker compose down\n```\n\nUse a full stop when you need to perform controlled maintenance, rebuild the image, or restore deployment files.\n\n## Restart as Part of Operations\n\nRoutine restarts are not a substitute for troubleshooting, but they are a legitimate step when:\n\n- You just changed deployment files.\n- You rebuilt the image.\n- You completed a controlled maintenance step.\n\nTo restart only the Sambee service:\n\n```bash\ndocker compose restart sambee\n```\n\nIf you restart repeatedly without understanding the failure, stop restarting and inspect the logs, deployment files, proxy path, and persistent data assumptions directly.\n", "1.0": "+++\ntitle = \"View Logs and Restart Services\"\n+++\n\nOnce Sambee is in service, logs and controlled restarts are the core day-to-day admin tools.\n\n## View Logs\n\nTo follow logs for all services:\n\n```bash\ndocker compose logs -f\n```\n\nTo focus on the Sambee service only:\n\n```bash\ndocker compose logs -f sambee\n```\n\nUse the service-specific view first when the issue is clearly about the application itself.\n\nIf you only need recent startup output, use:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\n## Stop the Deployment\n\nTo stop the services:\n\n```bash\ndocker compose down\n```\n\nUse a full stop when you need to perform controlled maintenance, rebuild the image, or restore deployment files.\n\n## Restart as Part of Operations\n\nRoutine restarts are not a substitute for troubleshooting, but they are a legitimate step when:\n\n- You just changed deployment files.\n- You rebuilt the image.\n- You completed a controlled maintenance step.\n\nTo restart only the Sambee service:\n\n```bash\ndocker compose restart sambee\n```\n\nIf you restart repeatedly without understanding the failure, stop restarting and inspect the logs, deployment files, proxy path, and persistent data assumptions directly.\n", "2.0": "+++\ntitle = \"View Logs and Restart Services\"\n+++\n\nOnce Sambee is in service, logs and controlled restarts are the core day-to-day admin tools.\n\n## View Logs\n\nTo follow logs for all services:\n\n```bash\ndocker compose logs -f\n```\n\nTo focus on the Sambee service only:\n\n```bash\ndocker compose logs -f sambee\n```\n\nUse the service-specific view first when the issue is clearly about the application itself.\n\nIf you only need recent startup output, use:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\n## Stop the Deployment\n\nTo stop the services:\n\n```bash\ndocker compose down\n```\n\nUse a full stop when you need to perform controlled maintenance, rebuild the image, or restore deployment files.\n\n## Restart as Part of Operations\n\nRoutine restarts are not a substitute for troubleshooting, but they are a legitimate step when:\n\n- You just changed deployment files.\n- You rebuilt the image.\n- You completed a controlled maintenance step.\n\nTo restart only the Sambee service:\n\n```bash\ndocker compose restart sambee\n```\n\nIf you restart repeatedly without understanding the failure, stop restarting and inspect the logs, deployment files, proxy path, and persistent data assumptions directly.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:admin-guide/operations-and-maintenance/update-sambee-safely", "parent_id": "section:admin-guide/operations-and-maintenance", "depth": 2, "kind": "page", "label": "update-sambee-safely", "title": "Update Sambee Safely", "path": "admin-guide/operations-and-maintenance/update-sambee-safely", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "branched", "source_version": "0.7", "diff_added": 24, "diff_removed": 0}, "2.0": {"state": "inherited", "source_version": "1.0"}}, "content_versions": {"0.7": "+++\ntitle = \"Update Sambee Safely\"\n+++\n\nUpdates should be deliberate. Do not upgrade production from the current branch tip.\n\n## Recommended Update Flow\n\nFetch the available tags and move to the release you intend to deploy:\n\n```bash\ngit fetch --tags\ngit checkout \u003crelease-tag\u003e\ndocker compose down\ndocker compose build --pull --no-cache\ndocker compose up -d\n```\n\n## Why This Flow Matters\n\nThis sequence makes the deployed version explicit and avoids drifting forward to whatever changed upstream most recently.\n\nIt also gives you a clean rebuild point instead of assuming the currently cached image still matches your operational intent.\n\n## Before You Upgrade\n\nBefore performing an update, confirm:\n\n- You know exactly which version you are moving to.\n- Your backup posture is acceptable.\n- Any local deployment files such as `docker-compose.yml` and optional `config.toml` are in the state you expect.\n\n## After You Upgrade\n\nAfter the new version is up:\n\n- Confirm that the frontend loads.\n- Confirm that you can sign in as expected.\n- Confirm that key SMB workflows still work.\n- Check logs for obvious startup regressions.\n\n## Verify the Upgraded Deployment\n\nTreat upgrade verification as part of the upgrade, not as optional follow-up.\n\nAt minimum, confirm:\n\n- You are on the intended release tag or commit.\n- The `docker compose ps` output shows the service healthy.\n- The frontend and sign-in path still work.\n- Key SMB workflows still behave as expected.\n- The recent logs do not show an obvious startup or migration regression.\n\nIf the service does not return cleanly after the update, stop changing versions and inspect the deployment state, recent logs, proxy path, and persistent data assumptions before proceeding.\n", "0.8": "+++\ntitle = \"Update Sambee Safely\"\n+++\n\nUpdates should be deliberate. Do not upgrade production from the current branch tip.\n\n## Recommended Update Flow\n\nFetch the available tags and move to the release you intend to deploy:\n\n```bash\ngit fetch --tags\ngit checkout \u003crelease-tag\u003e\ndocker compose down\ndocker compose build --pull --no-cache\ndocker compose up -d\n```\n\n## Why This Flow Matters\n\nThis sequence makes the deployed version explicit and avoids drifting forward to whatever changed upstream most recently.\n\nIt also gives you a clean rebuild point instead of assuming the currently cached image still matches your operational intent.\n\n## Before You Upgrade\n\nBefore performing an update, confirm:\n\n- You know exactly which version you are moving to.\n- Your backup posture is acceptable.\n- Any local deployment files such as `docker-compose.yml` and optional `config.toml` are in the state you expect.\n\n## After You Upgrade\n\nAfter the new version is up:\n\n- Confirm that the frontend loads.\n- Confirm that you can sign in as expected.\n- Confirm that key SMB workflows still work.\n- Check logs for obvious startup regressions.\n\n## Verify the Upgraded Deployment\n\nTreat upgrade verification as part of the upgrade, not as optional follow-up.\n\nAt minimum, confirm:\n\n- You are on the intended release tag or commit.\n- The `docker compose ps` output shows the service healthy.\n- The frontend and sign-in path still work.\n- Key SMB workflows still behave as expected.\n- The recent logs do not show an obvious startup or migration regression.\n\nIf the service does not return cleanly after the update, stop changing versions and inspect the deployment state, recent logs, proxy path, and persistent data assumptions before proceeding.\n", "0.9": "+++\ntitle = \"Update Sambee Safely\"\n+++\n\nUpdates should be deliberate. Do not upgrade production from the current branch tip.\n\n## Recommended Update Flow\n\nFetch the available tags and move to the release you intend to deploy:\n\n```bash\ngit fetch --tags\ngit checkout \u003crelease-tag\u003e\ndocker compose down\ndocker compose build --pull --no-cache\ndocker compose up -d\n```\n\n## Why This Flow Matters\n\nThis sequence makes the deployed version explicit and avoids drifting forward to whatever changed upstream most recently.\n\nIt also gives you a clean rebuild point instead of assuming the currently cached image still matches your operational intent.\n\n## Before You Upgrade\n\nBefore performing an update, confirm:\n\n- You know exactly which version you are moving to.\n- Your backup posture is acceptable.\n- Any local deployment files such as `docker-compose.yml` and optional `config.toml` are in the state you expect.\n\n## After You Upgrade\n\nAfter the new version is up:\n\n- Confirm that the frontend loads.\n- Confirm that you can sign in as expected.\n- Confirm that key SMB workflows still work.\n- Check logs for obvious startup regressions.\n\n## Verify the Upgraded Deployment\n\nTreat upgrade verification as part of the upgrade, not as optional follow-up.\n\nAt minimum, confirm:\n\n- You are on the intended release tag or commit.\n- The `docker compose ps` output shows the service healthy.\n- The frontend and sign-in path still work.\n- Key SMB workflows still behave as expected.\n- The recent logs do not show an obvious startup or migration regression.\n\nIf the service does not return cleanly after the update, stop changing versions and inspect the deployment state, recent logs, proxy path, and persistent data assumptions before proceeding.\n", "1.0": "+++\ntitle = \"Update Sambee Safely\"\n+++\n\nUpdates should be deliberate. Do not upgrade production from the current branch tip.\n\n## Recommended Update Flow\n\nFetch the available tags and move to the release you intend to deploy:\n\n```bash\ngit fetch --tags\ngit checkout \u003crelease-tag\u003e\ndocker compose down\ndocker compose build --pull --no-cache\ndocker compose up -d\n```\n\n## Archive V2 Cutover\n\nThe Archive V2 release does not retain interrupted Archive V1 work. Complete this one-time procedure before starting the new image when the preflight reports legacy archive operations.\n\n1. Stop Sambee and make a cold backup of `data/`, `docker-compose.yml`, and `config.toml` if you use one.\n1. Run the V2 preflight against the deployment's mounted database:\n\n   ```bash\n   docker compose run --rm --entrypoint /app/scripts/preflight-archive-v2-cutover sambee\n   ```\n\n1. If the preflight lists legacy operations, review the output. Those operations cannot be resumed after the cutover.\n1. Explicitly discard only the listed legacy archive operations:\n\n   ```bash\n   docker compose run --rm --entrypoint /app/scripts/reset-archive-v2-cutover-state sambee \\\n     --confirm-discard-legacy-archive-state\n   ```\n\n1. Run the preflight again. Continue only when it reports `\"ready\": true`.\n1. Start the new image with `docker compose up -d`. Startup runs the preflight again before applying database migrations.\n\nDo not run the reset command while an older Sambee backend can still create archive operations. The command affects only legacy archive-operation state; it does not reset users, connections, or other application data.\n\n## Why This Flow Matters\n\nThis sequence makes the deployed version explicit and avoids drifting forward to whatever changed upstream most recently.\n\nIt also gives you a clean rebuild point instead of assuming the currently cached image still matches your operational intent.\n\n## Before You Upgrade\n\nBefore performing an update, confirm:\n\n- You know exactly which version you are moving to.\n- Your backup posture is acceptable.\n- Any local deployment files such as `docker-compose.yml` and optional `config.toml` are in the state you expect.\n\n## After You Upgrade\n\nAfter the new version is up:\n\n- Confirm that the frontend loads.\n- Confirm that you can sign in as expected.\n- Confirm that key SMB workflows still work.\n- Check logs for obvious startup regressions.\n\n## Verify the Upgraded Deployment\n\nTreat upgrade verification as part of the upgrade, not as optional follow-up.\n\nAt minimum, confirm:\n\n- You are on the intended release tag or commit.\n- The `docker compose ps` output shows the service healthy.\n- The frontend and sign-in path still work.\n- Key SMB workflows still behave as expected.\n- The recent logs do not show an obvious startup or migration regression.\n\nIf the service does not return cleanly after the update, stop changing versions and inspect the deployment state, recent logs, proxy path, and persistent data assumptions before proceeding.", "2.0": "+++\ntitle = \"Update Sambee Safely\"\n+++\n\nUpdates should be deliberate. Do not upgrade production from the current branch tip.\n\n## Recommended Update Flow\n\nFetch the available tags and move to the release you intend to deploy:\n\n```bash\ngit fetch --tags\ngit checkout \u003crelease-tag\u003e\ndocker compose down\ndocker compose build --pull --no-cache\ndocker compose up -d\n```\n\n## Archive V2 Cutover\n\nThe Archive V2 release does not retain interrupted Archive V1 work. Complete this one-time procedure before starting the new image when the preflight reports legacy archive operations.\n\n1. Stop Sambee and make a cold backup of `data/`, `docker-compose.yml`, and `config.toml` if you use one.\n1. Run the V2 preflight against the deployment's mounted database:\n\n   ```bash\n   docker compose run --rm --entrypoint /app/scripts/preflight-archive-v2-cutover sambee\n   ```\n\n1. If the preflight lists legacy operations, review the output. Those operations cannot be resumed after the cutover.\n1. Explicitly discard only the listed legacy archive operations:\n\n   ```bash\n   docker compose run --rm --entrypoint /app/scripts/reset-archive-v2-cutover-state sambee \\\n     --confirm-discard-legacy-archive-state\n   ```\n\n1. Run the preflight again. Continue only when it reports `\"ready\": true`.\n1. Start the new image with `docker compose up -d`. Startup runs the preflight again before applying database migrations.\n\nDo not run the reset command while an older Sambee backend can still create archive operations. The command affects only legacy archive-operation state; it does not reset users, connections, or other application data.\n\n## Why This Flow Matters\n\nThis sequence makes the deployed version explicit and avoids drifting forward to whatever changed upstream most recently.\n\nIt also gives you a clean rebuild point instead of assuming the currently cached image still matches your operational intent.\n\n## Before You Upgrade\n\nBefore performing an update, confirm:\n\n- You know exactly which version you are moving to.\n- Your backup posture is acceptable.\n- Any local deployment files such as `docker-compose.yml` and optional `config.toml` are in the state you expect.\n\n## After You Upgrade\n\nAfter the new version is up:\n\n- Confirm that the frontend loads.\n- Confirm that you can sign in as expected.\n- Confirm that key SMB workflows still work.\n- Check logs for obvious startup regressions.\n\n## Verify the Upgraded Deployment\n\nTreat upgrade verification as part of the upgrade, not as optional follow-up.\n\nAt minimum, confirm:\n\n- You are on the intended release tag or commit.\n- The `docker compose ps` output shows the service healthy.\n- The frontend and sign-in path still work.\n- Key SMB workflows still behave as expected.\n- The recent logs do not show an obvious startup or migration regression.\n\nIf the service does not return cleanly after the update, stop changing versions and inspect the deployment state, recent logs, proxy path, and persistent data assumptions before proceeding."}, "page_contents": {"0.7": "+++\ntitle = \"Update Sambee Safely\"\n+++\n\nUpdates should be deliberate. Do not upgrade production from the current branch tip.\n\n## Recommended Update Flow\n\nFetch the available tags and move to the release you intend to deploy:\n\n```bash\ngit fetch --tags\ngit checkout \u003crelease-tag\u003e\ndocker compose down\ndocker compose build --pull --no-cache\ndocker compose up -d\n```\n\n## Why This Flow Matters\n\nThis sequence makes the deployed version explicit and avoids drifting forward to whatever changed upstream most recently.\n\nIt also gives you a clean rebuild point instead of assuming the currently cached image still matches your operational intent.\n\n## Before You Upgrade\n\nBefore performing an update, confirm:\n\n- You know exactly which version you are moving to.\n- Your backup posture is acceptable.\n- Any local deployment files such as `docker-compose.yml` and optional `config.toml` are in the state you expect.\n\n## After You Upgrade\n\nAfter the new version is up:\n\n- Confirm that the frontend loads.\n- Confirm that you can sign in as expected.\n- Confirm that key SMB workflows still work.\n- Check logs for obvious startup regressions.\n\n## Verify the Upgraded Deployment\n\nTreat upgrade verification as part of the upgrade, not as optional follow-up.\n\nAt minimum, confirm:\n\n- You are on the intended release tag or commit.\n- The `docker compose ps` output shows the service healthy.\n- The frontend and sign-in path still work.\n- Key SMB workflows still behave as expected.\n- The recent logs do not show an obvious startup or migration regression.\n\nIf the service does not return cleanly after the update, stop changing versions and inspect the deployment state, recent logs, proxy path, and persistent data assumptions before proceeding.\n", "0.8": "+++\ntitle = \"Update Sambee Safely\"\n+++\n\nUpdates should be deliberate. Do not upgrade production from the current branch tip.\n\n## Recommended Update Flow\n\nFetch the available tags and move to the release you intend to deploy:\n\n```bash\ngit fetch --tags\ngit checkout \u003crelease-tag\u003e\ndocker compose down\ndocker compose build --pull --no-cache\ndocker compose up -d\n```\n\n## Why This Flow Matters\n\nThis sequence makes the deployed version explicit and avoids drifting forward to whatever changed upstream most recently.\n\nIt also gives you a clean rebuild point instead of assuming the currently cached image still matches your operational intent.\n\n## Before You Upgrade\n\nBefore performing an update, confirm:\n\n- You know exactly which version you are moving to.\n- Your backup posture is acceptable.\n- Any local deployment files such as `docker-compose.yml` and optional `config.toml` are in the state you expect.\n\n## After You Upgrade\n\nAfter the new version is up:\n\n- Confirm that the frontend loads.\n- Confirm that you can sign in as expected.\n- Confirm that key SMB workflows still work.\n- Check logs for obvious startup regressions.\n\n## Verify the Upgraded Deployment\n\nTreat upgrade verification as part of the upgrade, not as optional follow-up.\n\nAt minimum, confirm:\n\n- You are on the intended release tag or commit.\n- The `docker compose ps` output shows the service healthy.\n- The frontend and sign-in path still work.\n- Key SMB workflows still behave as expected.\n- The recent logs do not show an obvious startup or migration regression.\n\nIf the service does not return cleanly after the update, stop changing versions and inspect the deployment state, recent logs, proxy path, and persistent data assumptions before proceeding.\n", "0.9": "+++\ntitle = \"Update Sambee Safely\"\n+++\n\nUpdates should be deliberate. Do not upgrade production from the current branch tip.\n\n## Recommended Update Flow\n\nFetch the available tags and move to the release you intend to deploy:\n\n```bash\ngit fetch --tags\ngit checkout \u003crelease-tag\u003e\ndocker compose down\ndocker compose build --pull --no-cache\ndocker compose up -d\n```\n\n## Why This Flow Matters\n\nThis sequence makes the deployed version explicit and avoids drifting forward to whatever changed upstream most recently.\n\nIt also gives you a clean rebuild point instead of assuming the currently cached image still matches your operational intent.\n\n## Before You Upgrade\n\nBefore performing an update, confirm:\n\n- You know exactly which version you are moving to.\n- Your backup posture is acceptable.\n- Any local deployment files such as `docker-compose.yml` and optional `config.toml` are in the state you expect.\n\n## After You Upgrade\n\nAfter the new version is up:\n\n- Confirm that the frontend loads.\n- Confirm that you can sign in as expected.\n- Confirm that key SMB workflows still work.\n- Check logs for obvious startup regressions.\n\n## Verify the Upgraded Deployment\n\nTreat upgrade verification as part of the upgrade, not as optional follow-up.\n\nAt minimum, confirm:\n\n- You are on the intended release tag or commit.\n- The `docker compose ps` output shows the service healthy.\n- The frontend and sign-in path still work.\n- Key SMB workflows still behave as expected.\n- The recent logs do not show an obvious startup or migration regression.\n\nIf the service does not return cleanly after the update, stop changing versions and inspect the deployment state, recent logs, proxy path, and persistent data assumptions before proceeding.\n", "1.0": "+++\ntitle = \"Update Sambee Safely\"\n+++\n\nUpdates should be deliberate. Do not upgrade production from the current branch tip.\n\n## Recommended Update Flow\n\nFetch the available tags and move to the release you intend to deploy:\n\n```bash\ngit fetch --tags\ngit checkout \u003crelease-tag\u003e\ndocker compose down\ndocker compose build --pull --no-cache\ndocker compose up -d\n```\n\n## Archive V2 Cutover\n\nThe Archive V2 release does not retain interrupted Archive V1 work. Complete this one-time procedure before starting the new image when the preflight reports legacy archive operations.\n\n1. Stop Sambee and make a cold backup of `data/`, `docker-compose.yml`, and `config.toml` if you use one.\n1. Run the V2 preflight against the deployment's mounted database:\n\n   ```bash\n   docker compose run --rm --entrypoint /app/scripts/preflight-archive-v2-cutover sambee\n   ```\n\n1. If the preflight lists legacy operations, review the output. Those operations cannot be resumed after the cutover.\n1. Explicitly discard only the listed legacy archive operations:\n\n   ```bash\n   docker compose run --rm --entrypoint /app/scripts/reset-archive-v2-cutover-state sambee \\\n     --confirm-discard-legacy-archive-state\n   ```\n\n1. Run the preflight again. Continue only when it reports `\"ready\": true`.\n1. Start the new image with `docker compose up -d`. Startup runs the preflight again before applying database migrations.\n\nDo not run the reset command while an older Sambee backend can still create archive operations. The command affects only legacy archive-operation state; it does not reset users, connections, or other application data.\n\n## Why This Flow Matters\n\nThis sequence makes the deployed version explicit and avoids drifting forward to whatever changed upstream most recently.\n\nIt also gives you a clean rebuild point instead of assuming the currently cached image still matches your operational intent.\n\n## Before You Upgrade\n\nBefore performing an update, confirm:\n\n- You know exactly which version you are moving to.\n- Your backup posture is acceptable.\n- Any local deployment files such as `docker-compose.yml` and optional `config.toml` are in the state you expect.\n\n## After You Upgrade\n\nAfter the new version is up:\n\n- Confirm that the frontend loads.\n- Confirm that you can sign in as expected.\n- Confirm that key SMB workflows still work.\n- Check logs for obvious startup regressions.\n\n## Verify the Upgraded Deployment\n\nTreat upgrade verification as part of the upgrade, not as optional follow-up.\n\nAt minimum, confirm:\n\n- You are on the intended release tag or commit.\n- The `docker compose ps` output shows the service healthy.\n- The frontend and sign-in path still work.\n- Key SMB workflows still behave as expected.\n- The recent logs do not show an obvious startup or migration regression.\n\nIf the service does not return cleanly after the update, stop changing versions and inspect the deployment state, recent logs, proxy path, and persistent data assumptions before proceeding.", "2.0": "+++\ntitle = \"Update Sambee Safely\"\n+++\n\nUpdates should be deliberate. Do not upgrade production from the current branch tip.\n\n## Recommended Update Flow\n\nFetch the available tags and move to the release you intend to deploy:\n\n```bash\ngit fetch --tags\ngit checkout \u003crelease-tag\u003e\ndocker compose down\ndocker compose build --pull --no-cache\ndocker compose up -d\n```\n\n## Archive V2 Cutover\n\nThe Archive V2 release does not retain interrupted Archive V1 work. Complete this one-time procedure before starting the new image when the preflight reports legacy archive operations.\n\n1. Stop Sambee and make a cold backup of `data/`, `docker-compose.yml`, and `config.toml` if you use one.\n1. Run the V2 preflight against the deployment's mounted database:\n\n   ```bash\n   docker compose run --rm --entrypoint /app/scripts/preflight-archive-v2-cutover sambee\n   ```\n\n1. If the preflight lists legacy operations, review the output. Those operations cannot be resumed after the cutover.\n1. Explicitly discard only the listed legacy archive operations:\n\n   ```bash\n   docker compose run --rm --entrypoint /app/scripts/reset-archive-v2-cutover-state sambee \\\n     --confirm-discard-legacy-archive-state\n   ```\n\n1. Run the preflight again. Continue only when it reports `\"ready\": true`.\n1. Start the new image with `docker compose up -d`. Startup runs the preflight again before applying database migrations.\n\nDo not run the reset command while an older Sambee backend can still create archive operations. The command affects only legacy archive-operation state; it does not reset users, connections, or other application data.\n\n## Why This Flow Matters\n\nThis sequence makes the deployed version explicit and avoids drifting forward to whatever changed upstream most recently.\n\nIt also gives you a clean rebuild point instead of assuming the currently cached image still matches your operational intent.\n\n## Before You Upgrade\n\nBefore performing an update, confirm:\n\n- You know exactly which version you are moving to.\n- Your backup posture is acceptable.\n- Any local deployment files such as `docker-compose.yml` and optional `config.toml` are in the state you expect.\n\n## After You Upgrade\n\nAfter the new version is up:\n\n- Confirm that the frontend loads.\n- Confirm that you can sign in as expected.\n- Confirm that key SMB workflows still work.\n- Check logs for obvious startup regressions.\n\n## Verify the Upgraded Deployment\n\nTreat upgrade verification as part of the upgrade, not as optional follow-up.\n\nAt minimum, confirm:\n\n- You are on the intended release tag or commit.\n- The `docker compose ps` output shows the service healthy.\n- The frontend and sign-in path still work.\n- Key SMB workflows still behave as expected.\n- The recent logs do not show an obvious startup or migration regression.\n\nIf the service does not return cleanly after the update, stop changing versions and inspect the deployment state, recent logs, proxy path, and persistent data assumptions before proceeding."}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:admin-guide/operations-and-maintenance/backup-and-restore-planning", "parent_id": "section:admin-guide/operations-and-maintenance", "depth": 2, "kind": "page", "label": "backup-and-restore-planning", "title": "Backup And Restore Planning", "path": "admin-guide/operations-and-maintenance/backup-and-restore-planning", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Backup and Restore Planning\"\n+++\n\nBackup planning for Sambee is mainly about preserving the deployment state that the service cannot recreate on its own.\n\n## What Must Be Protected\n\nAt minimum, protect:\n\n- `data/sambee.db`\n- your local `docker-compose.yml`\n- your local `config.toml`, if you use one\n\nThe database is the most important part because it contains users, connections, security keys, and encrypted passwords.\n\n## Simple Backup Pattern\n\nThe simplest safe backup is a cold backup:\n\n1. Stop the Sambee service.\n2. Copy `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Store the backup on different storage from the Sambee host.\n\nExample:\n\n```bash\ndocker compose stop sambee\ncp -a data docker-compose.yml /path/to/backup/\n# If You Use Config.toml, Back It up Too.\n# Cp -a Config.toml /Path/to/backup/\ndocker compose up -d sambee\n```\n\nIf you do not use `config.toml`, skip that copy step.\n\n## Basic Restore Flow\n\nAt minimum, a restore should look like this:\n\n1. Recreate the deployment directory on the replacement host.\n2. Restore `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Restore ownership on `data/` if needed so the container can write to it.\n4. Start Sambee with `docker compose up -d`.\n5. Confirm sign-in, logs, and a basic SMB workflow.\n", "0.8": "+++\ntitle = \"Backup and Restore Planning\"\n+++\n\nBackup planning for Sambee is mainly about preserving the deployment state that the service cannot recreate on its own.\n\n## What Must Be Protected\n\nAt minimum, protect:\n\n- `data/sambee.db`\n- your local `docker-compose.yml`\n- your local `config.toml`, if you use one\n\nThe database is the most important part because it contains users, connections, security keys, and encrypted passwords.\n\n## Simple Backup Pattern\n\nThe simplest safe backup is a cold backup:\n\n1. Stop the Sambee service.\n2. Copy `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Store the backup on different storage from the Sambee host.\n\nExample:\n\n```bash\ndocker compose stop sambee\ncp -a data docker-compose.yml /path/to/backup/\n# If You Use Config.toml, Back It up Too.\n# Cp -a Config.toml /Path/to/backup/\ndocker compose up -d sambee\n```\n\nIf you do not use `config.toml`, skip that copy step.\n\n## Basic Restore Flow\n\nAt minimum, a restore should look like this:\n\n1. Recreate the deployment directory on the replacement host.\n2. Restore `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Restore ownership on `data/` if needed so the container can write to it.\n4. Start Sambee with `docker compose up -d`.\n5. Confirm sign-in, logs, and a basic SMB workflow.\n", "0.9": "+++\ntitle = \"Backup and Restore Planning\"\n+++\n\nBackup planning for Sambee is mainly about preserving the deployment state that the service cannot recreate on its own.\n\n## What Must Be Protected\n\nAt minimum, protect:\n\n- `data/sambee.db`\n- your local `docker-compose.yml`\n- your local `config.toml`, if you use one\n\nThe database is the most important part because it contains users, connections, security keys, and encrypted passwords.\n\n## Simple Backup Pattern\n\nThe simplest safe backup is a cold backup:\n\n1. Stop the Sambee service.\n2. Copy `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Store the backup on different storage from the Sambee host.\n\nExample:\n\n```bash\ndocker compose stop sambee\ncp -a data docker-compose.yml /path/to/backup/\n# If You Use Config.toml, Back It up Too.\n# Cp -a Config.toml /Path/to/backup/\ndocker compose up -d sambee\n```\n\nIf you do not use `config.toml`, skip that copy step.\n\n## Basic Restore Flow\n\nAt minimum, a restore should look like this:\n\n1. Recreate the deployment directory on the replacement host.\n2. Restore `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Restore ownership on `data/` if needed so the container can write to it.\n4. Start Sambee with `docker compose up -d`.\n5. Confirm sign-in, logs, and a basic SMB workflow.\n", "1.0": "+++\ntitle = \"Backup and Restore Planning\"\n+++\n\nBackup planning for Sambee is mainly about preserving the deployment state that the service cannot recreate on its own.\n\n## What Must Be Protected\n\nAt minimum, protect:\n\n- `data/sambee.db`\n- your local `docker-compose.yml`\n- your local `config.toml`, if you use one\n\nThe database is the most important part because it contains users, connections, security keys, and encrypted passwords.\n\n## Simple Backup Pattern\n\nThe simplest safe backup is a cold backup:\n\n1. Stop the Sambee service.\n2. Copy `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Store the backup on different storage from the Sambee host.\n\nExample:\n\n```bash\ndocker compose stop sambee\ncp -a data docker-compose.yml /path/to/backup/\n# If You Use Config.toml, Back It up Too.\n# Cp -a Config.toml /Path/to/backup/\ndocker compose up -d sambee\n```\n\nIf you do not use `config.toml`, skip that copy step.\n\n## Basic Restore Flow\n\nAt minimum, a restore should look like this:\n\n1. Recreate the deployment directory on the replacement host.\n2. Restore `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Restore ownership on `data/` if needed so the container can write to it.\n4. Start Sambee with `docker compose up -d`.\n5. Confirm sign-in, logs, and a basic SMB workflow.\n", "2.0": "+++\ntitle = \"Backup and Restore Planning\"\n+++\n\nBackup planning for Sambee is mainly about preserving the deployment state that the service cannot recreate on its own.\n\n## What Must Be Protected\n\nAt minimum, protect:\n\n- `data/sambee.db`\n- your local `docker-compose.yml`\n- your local `config.toml`, if you use one\n\nThe database is the most important part because it contains users, connections, security keys, and encrypted passwords.\n\n## Simple Backup Pattern\n\nThe simplest safe backup is a cold backup:\n\n1. Stop the Sambee service.\n2. Copy `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Store the backup on different storage from the Sambee host.\n\nExample:\n\n```bash\ndocker compose stop sambee\ncp -a data docker-compose.yml /path/to/backup/\n# If You Use Config.toml, Back It up Too.\n# Cp -a Config.toml /Path/to/backup/\ndocker compose up -d sambee\n```\n\nIf you do not use `config.toml`, skip that copy step.\n\n## Basic Restore Flow\n\nAt minimum, a restore should look like this:\n\n1. Recreate the deployment directory on the replacement host.\n2. Restore `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Restore ownership on `data/` if needed so the container can write to it.\n4. Start Sambee with `docker compose up -d`.\n5. Confirm sign-in, logs, and a basic SMB workflow.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Backup and Restore Planning\"\n+++\n\nBackup planning for Sambee is mainly about preserving the deployment state that the service cannot recreate on its own.\n\n## What Must Be Protected\n\nAt minimum, protect:\n\n- `data/sambee.db`\n- your local `docker-compose.yml`\n- your local `config.toml`, if you use one\n\nThe database is the most important part because it contains users, connections, security keys, and encrypted passwords.\n\n## Simple Backup Pattern\n\nThe simplest safe backup is a cold backup:\n\n1. Stop the Sambee service.\n2. Copy `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Store the backup on different storage from the Sambee host.\n\nExample:\n\n```bash\ndocker compose stop sambee\ncp -a data docker-compose.yml /path/to/backup/\n# If You Use Config.toml, Back It up Too.\n# Cp -a Config.toml /Path/to/backup/\ndocker compose up -d sambee\n```\n\nIf you do not use `config.toml`, skip that copy step.\n\n## Basic Restore Flow\n\nAt minimum, a restore should look like this:\n\n1. Recreate the deployment directory on the replacement host.\n2. Restore `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Restore ownership on `data/` if needed so the container can write to it.\n4. Start Sambee with `docker compose up -d`.\n5. Confirm sign-in, logs, and a basic SMB workflow.\n", "0.8": "+++\ntitle = \"Backup and Restore Planning\"\n+++\n\nBackup planning for Sambee is mainly about preserving the deployment state that the service cannot recreate on its own.\n\n## What Must Be Protected\n\nAt minimum, protect:\n\n- `data/sambee.db`\n- your local `docker-compose.yml`\n- your local `config.toml`, if you use one\n\nThe database is the most important part because it contains users, connections, security keys, and encrypted passwords.\n\n## Simple Backup Pattern\n\nThe simplest safe backup is a cold backup:\n\n1. Stop the Sambee service.\n2. Copy `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Store the backup on different storage from the Sambee host.\n\nExample:\n\n```bash\ndocker compose stop sambee\ncp -a data docker-compose.yml /path/to/backup/\n# If You Use Config.toml, Back It up Too.\n# Cp -a Config.toml /Path/to/backup/\ndocker compose up -d sambee\n```\n\nIf you do not use `config.toml`, skip that copy step.\n\n## Basic Restore Flow\n\nAt minimum, a restore should look like this:\n\n1. Recreate the deployment directory on the replacement host.\n2. Restore `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Restore ownership on `data/` if needed so the container can write to it.\n4. Start Sambee with `docker compose up -d`.\n5. Confirm sign-in, logs, and a basic SMB workflow.\n", "0.9": "+++\ntitle = \"Backup and Restore Planning\"\n+++\n\nBackup planning for Sambee is mainly about preserving the deployment state that the service cannot recreate on its own.\n\n## What Must Be Protected\n\nAt minimum, protect:\n\n- `data/sambee.db`\n- your local `docker-compose.yml`\n- your local `config.toml`, if you use one\n\nThe database is the most important part because it contains users, connections, security keys, and encrypted passwords.\n\n## Simple Backup Pattern\n\nThe simplest safe backup is a cold backup:\n\n1. Stop the Sambee service.\n2. Copy `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Store the backup on different storage from the Sambee host.\n\nExample:\n\n```bash\ndocker compose stop sambee\ncp -a data docker-compose.yml /path/to/backup/\n# If You Use Config.toml, Back It up Too.\n# Cp -a Config.toml /Path/to/backup/\ndocker compose up -d sambee\n```\n\nIf you do not use `config.toml`, skip that copy step.\n\n## Basic Restore Flow\n\nAt minimum, a restore should look like this:\n\n1. Recreate the deployment directory on the replacement host.\n2. Restore `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Restore ownership on `data/` if needed so the container can write to it.\n4. Start Sambee with `docker compose up -d`.\n5. Confirm sign-in, logs, and a basic SMB workflow.\n", "1.0": "+++\ntitle = \"Backup and Restore Planning\"\n+++\n\nBackup planning for Sambee is mainly about preserving the deployment state that the service cannot recreate on its own.\n\n## What Must Be Protected\n\nAt minimum, protect:\n\n- `data/sambee.db`\n- your local `docker-compose.yml`\n- your local `config.toml`, if you use one\n\nThe database is the most important part because it contains users, connections, security keys, and encrypted passwords.\n\n## Simple Backup Pattern\n\nThe simplest safe backup is a cold backup:\n\n1. Stop the Sambee service.\n2. Copy `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Store the backup on different storage from the Sambee host.\n\nExample:\n\n```bash\ndocker compose stop sambee\ncp -a data docker-compose.yml /path/to/backup/\n# If You Use Config.toml, Back It up Too.\n# Cp -a Config.toml /Path/to/backup/\ndocker compose up -d sambee\n```\n\nIf you do not use `config.toml`, skip that copy step.\n\n## Basic Restore Flow\n\nAt minimum, a restore should look like this:\n\n1. Recreate the deployment directory on the replacement host.\n2. Restore `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Restore ownership on `data/` if needed so the container can write to it.\n4. Start Sambee with `docker compose up -d`.\n5. Confirm sign-in, logs, and a basic SMB workflow.\n", "2.0": "+++\ntitle = \"Backup and Restore Planning\"\n+++\n\nBackup planning for Sambee is mainly about preserving the deployment state that the service cannot recreate on its own.\n\n## What Must Be Protected\n\nAt minimum, protect:\n\n- `data/sambee.db`\n- your local `docker-compose.yml`\n- your local `config.toml`, if you use one\n\nThe database is the most important part because it contains users, connections, security keys, and encrypted passwords.\n\n## Simple Backup Pattern\n\nThe simplest safe backup is a cold backup:\n\n1. Stop the Sambee service.\n2. Copy `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Store the backup on different storage from the Sambee host.\n\nExample:\n\n```bash\ndocker compose stop sambee\ncp -a data docker-compose.yml /path/to/backup/\n# If You Use Config.toml, Back It up Too.\n# Cp -a Config.toml /Path/to/backup/\ndocker compose up -d sambee\n```\n\nIf you do not use `config.toml`, skip that copy step.\n\n## Basic Restore Flow\n\nAt minimum, a restore should look like this:\n\n1. Recreate the deployment directory on the replacement host.\n2. Restore `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Restore ownership on `data/` if needed so the container can write to it.\n4. Start Sambee with `docker compose up -d`.\n5. Confirm sign-in, logs, and a basic SMB workflow.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:admin-guide/reference", "parent_id": "book:admin-guide", "depth": 1, "kind": "section", "label": "reference", "title": "Reference", "path": "admin-guide/reference", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:admin-guide/reference/port-and-path-reference", "parent_id": "section:admin-guide/reference", "depth": 2, "kind": "page", "label": "port-and-path-reference", "title": "Port And Path Reference", "path": "admin-guide/reference/port-and-path-reference", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Port and Path Reference\"\n+++\n\nThis is the main lookup page for Sambee service ports, deployment files, persistent paths, and container-side paths.\n\n## Service Ports and URLs\n\n| Item | Default value | Notes |\n|---|---|---|\n| Sambee application port | `8000` | Default application port in the sample deployment |\n| Frontend URL | `http://localhost:8000` | Default direct-access frontend URL |\n| Backend API | `http://localhost:8000/api` | Default API path |\n| API docs | `http://localhost:8000/docs` | Default API documentation path |\n\n## Deployment Files and Paths\n\n| Path | Purpose |\n|---|---|\n| `docker-compose.yml` | Local deployment definition |\n| `config.toml` | Optional local configuration file |\n| `data/` | Persistent application data directory that must be backed up |\n| `data/sambee.db` | SQLite database containing users, connections, security keys, and encrypted passwords |\n| `data/directory_cache/` | Default location for Sambee's saved directory index when the relative cache setting is used |\n\n## Container-Side Paths\n\n| Path | Purpose |\n|---|---|\n| `/app/data` | Container-side mount point for persistent data |\n| `/app/data/sambee.db` | Container-side database path |\n| `/app/config.toml` | Container-side path for the optional mounted config file |\n| `/app/data/directory_cache/` | Default container-side location for the saved directory index |\n\n## Host-to-Container Mapping\n\n- Host-side `./data` becomes `/app/data` in the container.\n- Host-side `./config.toml` can be mounted read-only as `/app/config.toml`.\n- Deleting or replacing files under `data/` changes persistent deployment state, not just temporary cache files.\n", "0.8": "+++\ntitle = \"Port and Path Reference\"\n+++\n\nThis is the main lookup page for Sambee service ports, deployment files, persistent paths, and container-side paths.\n\n## Service Ports and URLs\n\n| Item | Default value | Notes |\n|---|---|---|\n| Sambee application port | `8000` | Default application port in the sample deployment |\n| Frontend URL | `http://localhost:8000` | Default direct-access frontend URL |\n| Backend API | `http://localhost:8000/api` | Default API path |\n| API docs | `http://localhost:8000/docs` | Default API documentation path |\n\n## Deployment Files and Paths\n\n| Path | Purpose |\n|---|---|\n| `docker-compose.yml` | Local deployment definition |\n| `config.toml` | Optional local configuration file |\n| `data/` | Persistent application data directory that must be backed up |\n| `data/sambee.db` | SQLite database containing users, connections, security keys, and encrypted passwords |\n| `data/directory_cache/` | Default location for Sambee's saved directory index when the relative cache setting is used |\n\n## Container-Side Paths\n\n| Path | Purpose |\n|---|---|\n| `/app/data` | Container-side mount point for persistent data |\n| `/app/data/sambee.db` | Container-side database path |\n| `/app/config.toml` | Container-side path for the optional mounted config file |\n| `/app/data/directory_cache/` | Default container-side location for the saved directory index |\n\n## Host-to-Container Mapping\n\n- Host-side `./data` becomes `/app/data` in the container.\n- Host-side `./config.toml` can be mounted read-only as `/app/config.toml`.\n- Deleting or replacing files under `data/` changes persistent deployment state, not just temporary cache files.\n", "0.9": "+++\ntitle = \"Port and Path Reference\"\n+++\n\nThis is the main lookup page for Sambee service ports, deployment files, persistent paths, and container-side paths.\n\n## Service Ports and URLs\n\n| Item | Default value | Notes |\n|---|---|---|\n| Sambee application port | `8000` | Default application port in the sample deployment |\n| Frontend URL | `http://localhost:8000` | Default direct-access frontend URL |\n| Backend API | `http://localhost:8000/api` | Default API path |\n| API docs | `http://localhost:8000/docs` | Default API documentation path |\n\n## Deployment Files and Paths\n\n| Path | Purpose |\n|---|---|\n| `docker-compose.yml` | Local deployment definition |\n| `config.toml` | Optional local configuration file |\n| `data/` | Persistent application data directory that must be backed up |\n| `data/sambee.db` | SQLite database containing users, connections, security keys, and encrypted passwords |\n| `data/directory_cache/` | Default location for Sambee's saved directory index when the relative cache setting is used |\n\n## Container-Side Paths\n\n| Path | Purpose |\n|---|---|\n| `/app/data` | Container-side mount point for persistent data |\n| `/app/data/sambee.db` | Container-side database path |\n| `/app/config.toml` | Container-side path for the optional mounted config file |\n| `/app/data/directory_cache/` | Default container-side location for the saved directory index |\n\n## Host-to-Container Mapping\n\n- Host-side `./data` becomes `/app/data` in the container.\n- Host-side `./config.toml` can be mounted read-only as `/app/config.toml`.\n- Deleting or replacing files under `data/` changes persistent deployment state, not just temporary cache files.\n", "1.0": "+++\ntitle = \"Port and Path Reference\"\n+++\n\nThis is the main lookup page for Sambee service ports, deployment files, persistent paths, and container-side paths.\n\n## Service Ports and URLs\n\n| Item | Default value | Notes |\n|---|---|---|\n| Sambee application port | `8000` | Default application port in the sample deployment |\n| Frontend URL | `http://localhost:8000` | Default direct-access frontend URL |\n| Backend API | `http://localhost:8000/api` | Default API path |\n| API docs | `http://localhost:8000/docs` | Default API documentation path |\n\n## Deployment Files and Paths\n\n| Path | Purpose |\n|---|---|\n| `docker-compose.yml` | Local deployment definition |\n| `config.toml` | Optional local configuration file |\n| `data/` | Persistent application data directory that must be backed up |\n| `data/sambee.db` | SQLite database containing users, connections, security keys, and encrypted passwords |\n| `data/directory_cache/` | Default location for Sambee's saved directory index when the relative cache setting is used |\n\n## Container-Side Paths\n\n| Path | Purpose |\n|---|---|\n| `/app/data` | Container-side mount point for persistent data |\n| `/app/data/sambee.db` | Container-side database path |\n| `/app/config.toml` | Container-side path for the optional mounted config file |\n| `/app/data/directory_cache/` | Default container-side location for the saved directory index |\n\n## Host-to-Container Mapping\n\n- Host-side `./data` becomes `/app/data` in the container.\n- Host-side `./config.toml` can be mounted read-only as `/app/config.toml`.\n- Deleting or replacing files under `data/` changes persistent deployment state, not just temporary cache files.\n", "2.0": "+++\ntitle = \"Port and Path Reference\"\n+++\n\nThis is the main lookup page for Sambee service ports, deployment files, persistent paths, and container-side paths.\n\n## Service Ports and URLs\n\n| Item | Default value | Notes |\n|---|---|---|\n| Sambee application port | `8000` | Default application port in the sample deployment |\n| Frontend URL | `http://localhost:8000` | Default direct-access frontend URL |\n| Backend API | `http://localhost:8000/api` | Default API path |\n| API docs | `http://localhost:8000/docs` | Default API documentation path |\n\n## Deployment Files and Paths\n\n| Path | Purpose |\n|---|---|\n| `docker-compose.yml` | Local deployment definition |\n| `config.toml` | Optional local configuration file |\n| `data/` | Persistent application data directory that must be backed up |\n| `data/sambee.db` | SQLite database containing users, connections, security keys, and encrypted passwords |\n| `data/directory_cache/` | Default location for Sambee's saved directory index when the relative cache setting is used |\n\n## Container-Side Paths\n\n| Path | Purpose |\n|---|---|\n| `/app/data` | Container-side mount point for persistent data |\n| `/app/data/sambee.db` | Container-side database path |\n| `/app/config.toml` | Container-side path for the optional mounted config file |\n| `/app/data/directory_cache/` | Default container-side location for the saved directory index |\n\n## Host-to-Container Mapping\n\n- Host-side `./data` becomes `/app/data` in the container.\n- Host-side `./config.toml` can be mounted read-only as `/app/config.toml`.\n- Deleting or replacing files under `data/` changes persistent deployment state, not just temporary cache files.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Port and Path Reference\"\n+++\n\nThis is the main lookup page for Sambee service ports, deployment files, persistent paths, and container-side paths.\n\n## Service Ports and URLs\n\n| Item | Default value | Notes |\n|---|---|---|\n| Sambee application port | `8000` | Default application port in the sample deployment |\n| Frontend URL | `http://localhost:8000` | Default direct-access frontend URL |\n| Backend API | `http://localhost:8000/api` | Default API path |\n| API docs | `http://localhost:8000/docs` | Default API documentation path |\n\n## Deployment Files and Paths\n\n| Path | Purpose |\n|---|---|\n| `docker-compose.yml` | Local deployment definition |\n| `config.toml` | Optional local configuration file |\n| `data/` | Persistent application data directory that must be backed up |\n| `data/sambee.db` | SQLite database containing users, connections, security keys, and encrypted passwords |\n| `data/directory_cache/` | Default location for Sambee's saved directory index when the relative cache setting is used |\n\n## Container-Side Paths\n\n| Path | Purpose |\n|---|---|\n| `/app/data` | Container-side mount point for persistent data |\n| `/app/data/sambee.db` | Container-side database path |\n| `/app/config.toml` | Container-side path for the optional mounted config file |\n| `/app/data/directory_cache/` | Default container-side location for the saved directory index |\n\n## Host-to-Container Mapping\n\n- Host-side `./data` becomes `/app/data` in the container.\n- Host-side `./config.toml` can be mounted read-only as `/app/config.toml`.\n- Deleting or replacing files under `data/` changes persistent deployment state, not just temporary cache files.\n", "0.8": "+++\ntitle = \"Port and Path Reference\"\n+++\n\nThis is the main lookup page for Sambee service ports, deployment files, persistent paths, and container-side paths.\n\n## Service Ports and URLs\n\n| Item | Default value | Notes |\n|---|---|---|\n| Sambee application port | `8000` | Default application port in the sample deployment |\n| Frontend URL | `http://localhost:8000` | Default direct-access frontend URL |\n| Backend API | `http://localhost:8000/api` | Default API path |\n| API docs | `http://localhost:8000/docs` | Default API documentation path |\n\n## Deployment Files and Paths\n\n| Path | Purpose |\n|---|---|\n| `docker-compose.yml` | Local deployment definition |\n| `config.toml` | Optional local configuration file |\n| `data/` | Persistent application data directory that must be backed up |\n| `data/sambee.db` | SQLite database containing users, connections, security keys, and encrypted passwords |\n| `data/directory_cache/` | Default location for Sambee's saved directory index when the relative cache setting is used |\n\n## Container-Side Paths\n\n| Path | Purpose |\n|---|---|\n| `/app/data` | Container-side mount point for persistent data |\n| `/app/data/sambee.db` | Container-side database path |\n| `/app/config.toml` | Container-side path for the optional mounted config file |\n| `/app/data/directory_cache/` | Default container-side location for the saved directory index |\n\n## Host-to-Container Mapping\n\n- Host-side `./data` becomes `/app/data` in the container.\n- Host-side `./config.toml` can be mounted read-only as `/app/config.toml`.\n- Deleting or replacing files under `data/` changes persistent deployment state, not just temporary cache files.\n", "0.9": "+++\ntitle = \"Port and Path Reference\"\n+++\n\nThis is the main lookup page for Sambee service ports, deployment files, persistent paths, and container-side paths.\n\n## Service Ports and URLs\n\n| Item | Default value | Notes |\n|---|---|---|\n| Sambee application port | `8000` | Default application port in the sample deployment |\n| Frontend URL | `http://localhost:8000` | Default direct-access frontend URL |\n| Backend API | `http://localhost:8000/api` | Default API path |\n| API docs | `http://localhost:8000/docs` | Default API documentation path |\n\n## Deployment Files and Paths\n\n| Path | Purpose |\n|---|---|\n| `docker-compose.yml` | Local deployment definition |\n| `config.toml` | Optional local configuration file |\n| `data/` | Persistent application data directory that must be backed up |\n| `data/sambee.db` | SQLite database containing users, connections, security keys, and encrypted passwords |\n| `data/directory_cache/` | Default location for Sambee's saved directory index when the relative cache setting is used |\n\n## Container-Side Paths\n\n| Path | Purpose |\n|---|---|\n| `/app/data` | Container-side mount point for persistent data |\n| `/app/data/sambee.db` | Container-side database path |\n| `/app/config.toml` | Container-side path for the optional mounted config file |\n| `/app/data/directory_cache/` | Default container-side location for the saved directory index |\n\n## Host-to-Container Mapping\n\n- Host-side `./data` becomes `/app/data` in the container.\n- Host-side `./config.toml` can be mounted read-only as `/app/config.toml`.\n- Deleting or replacing files under `data/` changes persistent deployment state, not just temporary cache files.\n", "1.0": "+++\ntitle = \"Port and Path Reference\"\n+++\n\nThis is the main lookup page for Sambee service ports, deployment files, persistent paths, and container-side paths.\n\n## Service Ports and URLs\n\n| Item | Default value | Notes |\n|---|---|---|\n| Sambee application port | `8000` | Default application port in the sample deployment |\n| Frontend URL | `http://localhost:8000` | Default direct-access frontend URL |\n| Backend API | `http://localhost:8000/api` | Default API path |\n| API docs | `http://localhost:8000/docs` | Default API documentation path |\n\n## Deployment Files and Paths\n\n| Path | Purpose |\n|---|---|\n| `docker-compose.yml` | Local deployment definition |\n| `config.toml` | Optional local configuration file |\n| `data/` | Persistent application data directory that must be backed up |\n| `data/sambee.db` | SQLite database containing users, connections, security keys, and encrypted passwords |\n| `data/directory_cache/` | Default location for Sambee's saved directory index when the relative cache setting is used |\n\n## Container-Side Paths\n\n| Path | Purpose |\n|---|---|\n| `/app/data` | Container-side mount point for persistent data |\n| `/app/data/sambee.db` | Container-side database path |\n| `/app/config.toml` | Container-side path for the optional mounted config file |\n| `/app/data/directory_cache/` | Default container-side location for the saved directory index |\n\n## Host-to-Container Mapping\n\n- Host-side `./data` becomes `/app/data` in the container.\n- Host-side `./config.toml` can be mounted read-only as `/app/config.toml`.\n- Deleting or replacing files under `data/` changes persistent deployment state, not just temporary cache files.\n", "2.0": "+++\ntitle = \"Port and Path Reference\"\n+++\n\nThis is the main lookup page for Sambee service ports, deployment files, persistent paths, and container-side paths.\n\n## Service Ports and URLs\n\n| Item | Default value | Notes |\n|---|---|---|\n| Sambee application port | `8000` | Default application port in the sample deployment |\n| Frontend URL | `http://localhost:8000` | Default direct-access frontend URL |\n| Backend API | `http://localhost:8000/api` | Default API path |\n| API docs | `http://localhost:8000/docs` | Default API documentation path |\n\n## Deployment Files and Paths\n\n| Path | Purpose |\n|---|---|\n| `docker-compose.yml` | Local deployment definition |\n| `config.toml` | Optional local configuration file |\n| `data/` | Persistent application data directory that must be backed up |\n| `data/sambee.db` | SQLite database containing users, connections, security keys, and encrypted passwords |\n| `data/directory_cache/` | Default location for Sambee's saved directory index when the relative cache setting is used |\n\n## Container-Side Paths\n\n| Path | Purpose |\n|---|---|\n| `/app/data` | Container-side mount point for persistent data |\n| `/app/data/sambee.db` | Container-side database path |\n| `/app/config.toml` | Container-side path for the optional mounted config file |\n| `/app/data/directory_cache/` | Default container-side location for the saved directory index |\n\n## Host-to-Container Mapping\n\n- Host-side `./data` becomes `/app/data` in the container.\n- Host-side `./config.toml` can be mounted read-only as `/app/config.toml`.\n- Deleting or replacing files under `data/` changes persistent deployment state, not just temporary cache files.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:admin-guide/reference/companion-support-reference", "parent_id": "section:admin-guide/reference", "depth": 2, "kind": "page", "label": "companion-support-reference", "title": "Companion Support Reference", "path": "admin-guide/reference/companion-support-reference", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Companion Support Reference\"\n+++\n\n## Communication and Security Model\n\nSambee uses two different browser-to-companion paths, depending on the workflow.\n\n- Local-drive browsing uses the companion's localhost API on `127.0.0.1:21549`.\n- Real-time local directory updates use a localhost WebSocket on the same port.\n- Desktop-app opening uses the `sambee://` custom URI scheme.\n\nThe localhost API is bound to the local machine only. It is not meant for remote network access.\n\nLocalhost traffic is authenticated after pairing, but it is not transport-encrypted.\n\n- HTTP requests use an HMAC derived from a shared secret and a current timestamp.\n- WebSocket and browser resource URLs use the same HMAC model through query parameters because browsers cannot attach custom headers in those cases.\n- The companion rejects requests outside the allowed clock-skew window.\n- Pairing is scoped to the browser origin, not just to the machine as a whole.\n\nThe shared secret is created only after the user confirms the same pairing code in both the browser and the companion. The companion stores its copy in the OS credential store. The browser stores its copy locally for that paired browser profile at that Sambee origin.\n\nIf you need contributor-level implementation detail, continue to the developer guide page [Browser-to-Companion Trust Model](../../../../0.7/developer-guide/companion-architecture/browser-to-companion-trust-model/).\n\n## Preference Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%APPDATA%\\app.sambee.companion\\` |\n| macOS | `~/Library/Application Support/app.sambee.companion/` |\n| Linux | `~/.local/share/app.sambee.companion/` |\n\nDeleting `user-preferences.json` and `app-preferences.json` resets companion settings.\n\n## Log Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%LOCALAPPDATA%\\Sambee\\Companion\\logs\\sambee-companion.log` |\n| macOS | `~/Library/Application Support/app.sambee.companion/logs/sambee-companion.log` |\n| Linux | `~/.local/share/sambee-companion/logs/sambee-companion.log` |\n\nThe companion writes both Rust-backend messages and TypeScript-frontend messages into the same rotating log file.\n\n## Log Levels\n\n| Level | When captured | Typical use |\n|---|---|---|\n| `error` | Always | failures that stop an operation from completing |\n| `warn` | Always | degraded but non-fatal behavior |\n| `info` | Verbose mode only | lifecycle steps and state transitions |\n| `debug` | Verbose mode only for Sambee app and frontend logs | detailed diagnostic context |\n\nErrors and warnings are always written, even when verbose logging is off. That keeps production incidents diagnosable without requiring the user to reproduce them in a special logging mode.\n\nNormal verbose logging keeps dependency transport logs quiet. HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls` are enabled separately because they can be very noisy.\n\n## Logging Controls\n\nLogging settings are read once at startup, so restart the companion after changing logging registry values or logging environment variables.\n\nTwo logging toggles are available:\n\n| Setting | Purpose |\n|---|---|\n| `VerboseLogging` | Enables verbose Sambee app and frontend logs. |\n| `TransportLogging` | Enables HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls`. |\n\n### Windows Registry Values\n\nOn Windows, configure logging through registry values under:\n\n```text\nHKEY_CURRENT_USER\\Software\\Sambee\\Companion\n```\n\nUse type `REG_DWORD`. A non-zero value enables the setting. A missing value or `0` leaves the setting disabled.\n\nTo enable verbose Sambee app and frontend logs:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 1 /f\n```\n\nTo enable HTTP transport diagnostics:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 1 /f\n```\n\nTo disable them again:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 0 /f\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 0 /f\n```\n\nRestart Companion after changing either registry value.\n\n### Linux and macOS Environment Variables\n\nOn Linux and macOS, launch the companion with environment variables for the logging modes you need.\n\nVerbose Sambee app and frontend logs:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 ./sambee-companion\n```\n\nHTTP transport diagnostics:\n\n```bash\nSAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nYou can combine both logging modes:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 SAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nThe environment variables are also available on Windows for one-off terminal-launched debugging and take precedence over the registry values. Use `0` or `false` to force a setting off for that launch.\n\nUse verbose logging when the normal log file does not explain why startup, local-drive access, or file-return workflows are failing. Add transport diagnostics when you need HTTP, TLS, proxy, or HTTP/2 details.\n\n## Support Log Checklist\n\nWhen collecting Companion logs for a native-editing issue, include:\n\n- Whether the `Sambee Authentication` window appeared.\n- Whether the failure happened during token exchange, file-info lookup, lock acquisition, download, upload, lock release, or heartbeat.\n- Whether Companion reported a lifecycle state such as renewal required, authentication failed, lock lost, or recovery required.\n- The reverse proxy or SSO product in front of Sambee, if one is used.\n- The Companion log file from the affected desktop.\n\nWhen verbose logging is enabled, include any operation or lock identifiers shown near the failing step. Those identifiers help correlate token exchange, lock acquisition, renewal, upload, and release events without exposing the secret material itself.\n\nCompanion sanitizes URLs before writing request diagnostics. Sensitive query values such as tokens, secrets, passwords, cookies, authorization data, sessions, keys, and theme payloads should not appear in support logs.\n\n## Log Rotation\n\nThe companion rotates logs automatically to avoid unbounded disk growth.\n\n- Maximum file size: 5 MB per log file.\n- Maximum files: 3 total, including the active file.\n- Worst-case disk usage: About 15 MB.\n\nRotation uses the usual numbered-copy scheme: the active `.log` becomes `.log.1`, the previous `.log.1` becomes `.log.2`, and the oldest rotated file is removed.\n\n## Log Format\n\nEach line follows this structure:\n\n```text\nYYYY-MM-DDThh:mm:ss.mmmZ LEVEL [module] message\n```\n\nExample:\n\n```text\n2026-02-17T14:30:45.123Z INFO  [sambee_companion_lib] Step 1: Exchanging URI token...\n2026-02-17T14:30:45.456Z ERROR [frontend] Upload failed: network timeout\n2026-02-17T14:30:46.789Z WARN  [sambee_companion_lib::commands::upload] Upload attempt 1/3 failed: connection refused\n```\n\nFrontend messages use the module target `frontend` so you can distinguish browser-side UI logging from Rust-side command and backend behavior.\n\n## How Logging Reaches the File\n\nThe companion uses one unified file-log pipeline.\n\n### Rust Side\n\nThe Rust logging module in `companion/src-tauri/src/logging.rs` implements the `log::Log` trait. Existing Rust-side `info!()`, `warn!()`, `error!()`, and `debug!()` calls therefore write into the same rotating companion log file.\n\nIf file logging initialization fails, the app falls back to stderr logging so startup can still proceed and terminal-launched sessions still have diagnostic output.\n\n### Frontend Side\n\nThe frontend logger in `companion/src/lib/logger.ts` writes to both:\n\n- The browser console for local developer-tools visibility.\n- The Rust backend through the `log_from_frontend` Tauri command so the same message lands in the file log.\n\nThat means support logs can contain both frontend and backend events in one timeline.\n\nThe frontend logger is fire-and-forget. Logging should never block the UI or surface a user-facing error because the log write itself failed.\n\n## Windows Webview2 Runtime Data\n\nOn Windows, the embedded WebView2 runtime stores its data at:\n\n- `%LOCALAPPDATA%\\app.sambee.companion\\EBWebView\\`\n\nThis directory is runtime-managed and is recreated automatically if removed.\n", "0.8": "+++\ntitle = \"Companion Support Reference\"\n+++\n\n## Communication and Security Model\n\nSambee uses two different browser-to-companion paths, depending on the workflow.\n\n- Local-drive browsing uses the companion's localhost API on `127.0.0.1:21549`.\n- Real-time local directory updates use a localhost WebSocket on the same port.\n- Desktop-app opening uses the `sambee://` custom URI scheme.\n\nThe localhost API is bound to the local machine only. It is not meant for remote network access.\n\nLocalhost traffic is authenticated after pairing, but it is not transport-encrypted.\n\n- HTTP requests use an HMAC derived from a shared secret and a current timestamp.\n- WebSocket and browser resource URLs use the same HMAC model through query parameters because browsers cannot attach custom headers in those cases.\n- The companion rejects requests outside the allowed clock-skew window.\n- Pairing is scoped to the browser origin, not just to the machine as a whole.\n\nThe shared secret is created only after the user confirms the same pairing code in both the browser and the companion. The companion stores its copy in the OS credential store. The browser stores its copy locally for that paired browser profile at that Sambee origin.\n\nIf you need contributor-level implementation detail, continue to the developer guide page [Browser-to-Companion Trust Model](../../../../0.7/developer-guide/companion-architecture/browser-to-companion-trust-model/).\n\n## Preference Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%APPDATA%\\app.sambee.companion\\` |\n| macOS | `~/Library/Application Support/app.sambee.companion/` |\n| Linux | `~/.local/share/app.sambee.companion/` |\n\nDeleting `user-preferences.json` and `app-preferences.json` resets companion settings.\n\n## Log Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%LOCALAPPDATA%\\Sambee\\Companion\\logs\\sambee-companion.log` |\n| macOS | `~/Library/Application Support/app.sambee.companion/logs/sambee-companion.log` |\n| Linux | `~/.local/share/sambee-companion/logs/sambee-companion.log` |\n\nThe companion writes both Rust-backend messages and TypeScript-frontend messages into the same rotating log file.\n\n## Log Levels\n\n| Level | When captured | Typical use |\n|---|---|---|\n| `error` | Always | failures that stop an operation from completing |\n| `warn` | Always | degraded but non-fatal behavior |\n| `info` | Verbose mode only | lifecycle steps and state transitions |\n| `debug` | Verbose mode only for Sambee app and frontend logs | detailed diagnostic context |\n\nErrors and warnings are always written, even when verbose logging is off. That keeps production incidents diagnosable without requiring the user to reproduce them in a special logging mode.\n\nNormal verbose logging keeps dependency transport logs quiet. HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls` are enabled separately because they can be very noisy.\n\n## Logging Controls\n\nLogging settings are read once at startup, so restart the companion after changing logging registry values or logging environment variables.\n\nTwo logging toggles are available:\n\n| Setting | Purpose |\n|---|---|\n| `VerboseLogging` | Enables verbose Sambee app and frontend logs. |\n| `TransportLogging` | Enables HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls`. |\n\n### Windows Registry Values\n\nOn Windows, configure logging through registry values under:\n\n```text\nHKEY_CURRENT_USER\\Software\\Sambee\\Companion\n```\n\nUse type `REG_DWORD`. A non-zero value enables the setting. A missing value or `0` leaves the setting disabled.\n\nTo enable verbose Sambee app and frontend logs:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 1 /f\n```\n\nTo enable HTTP transport diagnostics:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 1 /f\n```\n\nTo disable them again:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 0 /f\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 0 /f\n```\n\nRestart Companion after changing either registry value.\n\n### Linux and macOS Environment Variables\n\nOn Linux and macOS, launch the companion with environment variables for the logging modes you need.\n\nVerbose Sambee app and frontend logs:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 ./sambee-companion\n```\n\nHTTP transport diagnostics:\n\n```bash\nSAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nYou can combine both logging modes:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 SAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nThe environment variables are also available on Windows for one-off terminal-launched debugging and take precedence over the registry values. Use `0` or `false` to force a setting off for that launch.\n\nUse verbose logging when the normal log file does not explain why startup, local-drive access, or file-return workflows are failing. Add transport diagnostics when you need HTTP, TLS, proxy, or HTTP/2 details.\n\n## Support Log Checklist\n\nWhen collecting Companion logs for a native-editing issue, include:\n\n- Whether the `Sambee Authentication` window appeared.\n- Whether the failure happened during token exchange, file-info lookup, lock acquisition, download, upload, lock release, or heartbeat.\n- Whether Companion reported a lifecycle state such as renewal required, authentication failed, lock lost, or recovery required.\n- The reverse proxy or SSO product in front of Sambee, if one is used.\n- The Companion log file from the affected desktop.\n\nWhen verbose logging is enabled, include any operation or lock identifiers shown near the failing step. Those identifiers help correlate token exchange, lock acquisition, renewal, upload, and release events without exposing the secret material itself.\n\nCompanion sanitizes URLs before writing request diagnostics. Sensitive query values such as tokens, secrets, passwords, cookies, authorization data, sessions, keys, and theme payloads should not appear in support logs.\n\n## Log Rotation\n\nThe companion rotates logs automatically to avoid unbounded disk growth.\n\n- Maximum file size: 5 MB per log file.\n- Maximum files: 3 total, including the active file.\n- Worst-case disk usage: About 15 MB.\n\nRotation uses the usual numbered-copy scheme: the active `.log` becomes `.log.1`, the previous `.log.1` becomes `.log.2`, and the oldest rotated file is removed.\n\n## Log Format\n\nEach line follows this structure:\n\n```text\nYYYY-MM-DDThh:mm:ss.mmmZ LEVEL [module] message\n```\n\nExample:\n\n```text\n2026-02-17T14:30:45.123Z INFO  [sambee_companion_lib] Step 1: Exchanging URI token...\n2026-02-17T14:30:45.456Z ERROR [frontend] Upload failed: network timeout\n2026-02-17T14:30:46.789Z WARN  [sambee_companion_lib::commands::upload] Upload attempt 1/3 failed: connection refused\n```\n\nFrontend messages use the module target `frontend` so you can distinguish browser-side UI logging from Rust-side command and backend behavior.\n\n## How Logging Reaches the File\n\nThe companion uses one unified file-log pipeline.\n\n### Rust Side\n\nThe Rust logging module in `companion/src-tauri/src/logging.rs` implements the `log::Log` trait. Existing Rust-side `info!()`, `warn!()`, `error!()`, and `debug!()` calls therefore write into the same rotating companion log file.\n\nIf file logging initialization fails, the app falls back to stderr logging so startup can still proceed and terminal-launched sessions still have diagnostic output.\n\n### Frontend Side\n\nThe frontend logger in `companion/src/lib/logger.ts` writes to both:\n\n- The browser console for local developer-tools visibility.\n- The Rust backend through the `log_from_frontend` Tauri command so the same message lands in the file log.\n\nThat means support logs can contain both frontend and backend events in one timeline.\n\nThe frontend logger is fire-and-forget. Logging should never block the UI or surface a user-facing error because the log write itself failed.\n\n## Windows Webview2 Runtime Data\n\nOn Windows, the embedded WebView2 runtime stores its data at:\n\n- `%LOCALAPPDATA%\\app.sambee.companion\\EBWebView\\`\n\nThis directory is runtime-managed and is recreated automatically if removed.\n", "0.9": "+++\ntitle = \"Companion Support Reference\"\n+++\n\n## Communication and Security Model\n\nSambee uses two different browser-to-companion paths, depending on the workflow.\n\n- Local-drive browsing uses the companion's localhost API on `127.0.0.1:21549`.\n- Real-time local directory updates use a localhost WebSocket on the same port.\n- Desktop-app opening uses the `sambee://` custom URI scheme.\n\nThe localhost API is bound to the local machine only. It is not meant for remote network access.\n\nLocalhost traffic is authenticated after pairing, but it is not transport-encrypted.\n\n- HTTP requests use an HMAC derived from a shared secret and a current timestamp.\n- WebSocket and browser resource URLs use the same HMAC model through query parameters because browsers cannot attach custom headers in those cases.\n- The companion rejects requests outside the allowed clock-skew window.\n- Pairing is scoped to the browser origin, not just to the machine as a whole.\n\nThe shared secret is created only after the user confirms the same pairing code in both the browser and the companion. The companion stores its copy in the OS credential store. The browser stores its copy locally for that paired browser profile at that Sambee origin.\n\nIf you need contributor-level implementation detail, continue to the developer guide page [Browser-to-Companion Trust Model](../../../../0.7/developer-guide/companion-architecture/browser-to-companion-trust-model/).\n\n## Preference Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%APPDATA%\\app.sambee.companion\\` |\n| macOS | `~/Library/Application Support/app.sambee.companion/` |\n| Linux | `~/.local/share/app.sambee.companion/` |\n\nDeleting `user-preferences.json` and `app-preferences.json` resets companion settings.\n\n## Log Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%LOCALAPPDATA%\\Sambee\\Companion\\logs\\sambee-companion.log` |\n| macOS | `~/Library/Application Support/app.sambee.companion/logs/sambee-companion.log` |\n| Linux | `~/.local/share/sambee-companion/logs/sambee-companion.log` |\n\nThe companion writes both Rust-backend messages and TypeScript-frontend messages into the same rotating log file.\n\n## Log Levels\n\n| Level | When captured | Typical use |\n|---|---|---|\n| `error` | Always | failures that stop an operation from completing |\n| `warn` | Always | degraded but non-fatal behavior |\n| `info` | Verbose mode only | lifecycle steps and state transitions |\n| `debug` | Verbose mode only for Sambee app and frontend logs | detailed diagnostic context |\n\nErrors and warnings are always written, even when verbose logging is off. That keeps production incidents diagnosable without requiring the user to reproduce them in a special logging mode.\n\nNormal verbose logging keeps dependency transport logs quiet. HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls` are enabled separately because they can be very noisy.\n\n## Logging Controls\n\nLogging settings are read once at startup, so restart the companion after changing logging registry values or logging environment variables.\n\nTwo logging toggles are available:\n\n| Setting | Purpose |\n|---|---|\n| `VerboseLogging` | Enables verbose Sambee app and frontend logs. |\n| `TransportLogging` | Enables HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls`. |\n\n### Windows Registry Values\n\nOn Windows, configure logging through registry values under:\n\n```text\nHKEY_CURRENT_USER\\Software\\Sambee\\Companion\n```\n\nUse type `REG_DWORD`. A non-zero value enables the setting. A missing value or `0` leaves the setting disabled.\n\nTo enable verbose Sambee app and frontend logs:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 1 /f\n```\n\nTo enable HTTP transport diagnostics:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 1 /f\n```\n\nTo disable them again:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 0 /f\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 0 /f\n```\n\nRestart Companion after changing either registry value.\n\n### Linux and macOS Environment Variables\n\nOn Linux and macOS, launch the companion with environment variables for the logging modes you need.\n\nVerbose Sambee app and frontend logs:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 ./sambee-companion\n```\n\nHTTP transport diagnostics:\n\n```bash\nSAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nYou can combine both logging modes:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 SAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nThe environment variables are also available on Windows for one-off terminal-launched debugging and take precedence over the registry values. Use `0` or `false` to force a setting off for that launch.\n\nUse verbose logging when the normal log file does not explain why startup, local-drive access, or file-return workflows are failing. Add transport diagnostics when you need HTTP, TLS, proxy, or HTTP/2 details.\n\n## Support Log Checklist\n\nWhen collecting Companion logs for a native-editing issue, include:\n\n- Whether the `Sambee Authentication` window appeared.\n- Whether the failure happened during token exchange, file-info lookup, lock acquisition, download, upload, lock release, or heartbeat.\n- Whether Companion reported a lifecycle state such as renewal required, authentication failed, lock lost, or recovery required.\n- The reverse proxy or SSO product in front of Sambee, if one is used.\n- The Companion log file from the affected desktop.\n\nWhen verbose logging is enabled, include any operation or lock identifiers shown near the failing step. Those identifiers help correlate token exchange, lock acquisition, renewal, upload, and release events without exposing the secret material itself.\n\nCompanion sanitizes URLs before writing request diagnostics. Sensitive query values such as tokens, secrets, passwords, cookies, authorization data, sessions, keys, and theme payloads should not appear in support logs.\n\n## Log Rotation\n\nThe companion rotates logs automatically to avoid unbounded disk growth.\n\n- Maximum file size: 5 MB per log file.\n- Maximum files: 3 total, including the active file.\n- Worst-case disk usage: About 15 MB.\n\nRotation uses the usual numbered-copy scheme: the active `.log` becomes `.log.1`, the previous `.log.1` becomes `.log.2`, and the oldest rotated file is removed.\n\n## Log Format\n\nEach line follows this structure:\n\n```text\nYYYY-MM-DDThh:mm:ss.mmmZ LEVEL [module] message\n```\n\nExample:\n\n```text\n2026-02-17T14:30:45.123Z INFO  [sambee_companion_lib] Step 1: Exchanging URI token...\n2026-02-17T14:30:45.456Z ERROR [frontend] Upload failed: network timeout\n2026-02-17T14:30:46.789Z WARN  [sambee_companion_lib::commands::upload] Upload attempt 1/3 failed: connection refused\n```\n\nFrontend messages use the module target `frontend` so you can distinguish browser-side UI logging from Rust-side command and backend behavior.\n\n## How Logging Reaches the File\n\nThe companion uses one unified file-log pipeline.\n\n### Rust Side\n\nThe Rust logging module in `companion/src-tauri/src/logging.rs` implements the `log::Log` trait. Existing Rust-side `info!()`, `warn!()`, `error!()`, and `debug!()` calls therefore write into the same rotating companion log file.\n\nIf file logging initialization fails, the app falls back to stderr logging so startup can still proceed and terminal-launched sessions still have diagnostic output.\n\n### Frontend Side\n\nThe frontend logger in `companion/src/lib/logger.ts` writes to both:\n\n- The browser console for local developer-tools visibility.\n- The Rust backend through the `log_from_frontend` Tauri command so the same message lands in the file log.\n\nThat means support logs can contain both frontend and backend events in one timeline.\n\nThe frontend logger is fire-and-forget. Logging should never block the UI or surface a user-facing error because the log write itself failed.\n\n## Windows Webview2 Runtime Data\n\nOn Windows, the embedded WebView2 runtime stores its data at:\n\n- `%LOCALAPPDATA%\\app.sambee.companion\\EBWebView\\`\n\nThis directory is runtime-managed and is recreated automatically if removed.\n", "1.0": "+++\ntitle = \"Companion Support Reference\"\n+++\n\n## Communication and Security Model\n\nSambee uses two different browser-to-companion paths, depending on the workflow.\n\n- Local-drive browsing uses the companion's localhost API on `127.0.0.1:21549`.\n- Real-time local directory updates use a localhost WebSocket on the same port.\n- Desktop-app opening uses the `sambee://` custom URI scheme.\n\nThe localhost API is bound to the local machine only. It is not meant for remote network access.\n\nLocalhost traffic is authenticated after pairing, but it is not transport-encrypted.\n\n- HTTP requests use an HMAC derived from a shared secret and a current timestamp.\n- WebSocket and browser resource URLs use the same HMAC model through query parameters because browsers cannot attach custom headers in those cases.\n- The companion rejects requests outside the allowed clock-skew window.\n- Pairing is scoped to the browser origin, not just to the machine as a whole.\n\nThe shared secret is created only after the user confirms the same pairing code in both the browser and the companion. The companion stores its copy in the OS credential store. The browser stores its copy locally for that paired browser profile at that Sambee origin.\n\nIf you need contributor-level implementation detail, continue to the developer guide page [Browser-to-Companion Trust Model](../../../../0.7/developer-guide/companion-architecture/browser-to-companion-trust-model/).\n\n## Preference Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%APPDATA%\\app.sambee.companion\\` |\n| macOS | `~/Library/Application Support/app.sambee.companion/` |\n| Linux | `~/.local/share/app.sambee.companion/` |\n\nDeleting `user-preferences.json` and `app-preferences.json` resets companion settings.\n\n## Log Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%LOCALAPPDATA%\\Sambee\\Companion\\logs\\sambee-companion.log` |\n| macOS | `~/Library/Application Support/app.sambee.companion/logs/sambee-companion.log` |\n| Linux | `~/.local/share/sambee-companion/logs/sambee-companion.log` |\n\nThe companion writes both Rust-backend messages and TypeScript-frontend messages into the same rotating log file.\n\n## Log Levels\n\n| Level | When captured | Typical use |\n|---|---|---|\n| `error` | Always | failures that stop an operation from completing |\n| `warn` | Always | degraded but non-fatal behavior |\n| `info` | Verbose mode only | lifecycle steps and state transitions |\n| `debug` | Verbose mode only for Sambee app and frontend logs | detailed diagnostic context |\n\nErrors and warnings are always written, even when verbose logging is off. That keeps production incidents diagnosable without requiring the user to reproduce them in a special logging mode.\n\nNormal verbose logging keeps dependency transport logs quiet. HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls` are enabled separately because they can be very noisy.\n\n## Logging Controls\n\nLogging settings are read once at startup, so restart the companion after changing logging registry values or logging environment variables.\n\nTwo logging toggles are available:\n\n| Setting | Purpose |\n|---|---|\n| `VerboseLogging` | Enables verbose Sambee app and frontend logs. |\n| `TransportLogging` | Enables HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls`. |\n\n### Windows Registry Values\n\nOn Windows, configure logging through registry values under:\n\n```text\nHKEY_CURRENT_USER\\Software\\Sambee\\Companion\n```\n\nUse type `REG_DWORD`. A non-zero value enables the setting. A missing value or `0` leaves the setting disabled.\n\nTo enable verbose Sambee app and frontend logs:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 1 /f\n```\n\nTo enable HTTP transport diagnostics:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 1 /f\n```\n\nTo disable them again:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 0 /f\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 0 /f\n```\n\nRestart Companion after changing either registry value.\n\n### Linux and macOS Environment Variables\n\nOn Linux and macOS, launch the companion with environment variables for the logging modes you need.\n\nVerbose Sambee app and frontend logs:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 ./sambee-companion\n```\n\nHTTP transport diagnostics:\n\n```bash\nSAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nYou can combine both logging modes:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 SAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nThe environment variables are also available on Windows for one-off terminal-launched debugging and take precedence over the registry values. Use `0` or `false` to force a setting off for that launch.\n\nUse verbose logging when the normal log file does not explain why startup, local-drive access, or file-return workflows are failing. Add transport diagnostics when you need HTTP, TLS, proxy, or HTTP/2 details.\n\n## Support Log Checklist\n\nWhen collecting Companion logs for a native-editing issue, include:\n\n- Whether the `Sambee Authentication` window appeared.\n- Whether the failure happened during token exchange, file-info lookup, lock acquisition, download, upload, lock release, or heartbeat.\n- Whether Companion reported a lifecycle state such as renewal required, authentication failed, lock lost, or recovery required.\n- The reverse proxy or SSO product in front of Sambee, if one is used.\n- The Companion log file from the affected desktop.\n\nWhen verbose logging is enabled, include any operation or lock identifiers shown near the failing step. Those identifiers help correlate token exchange, lock acquisition, renewal, upload, and release events without exposing the secret material itself.\n\nCompanion sanitizes URLs before writing request diagnostics. Sensitive query values such as tokens, secrets, passwords, cookies, authorization data, sessions, keys, and theme payloads should not appear in support logs.\n\n## Log Rotation\n\nThe companion rotates logs automatically to avoid unbounded disk growth.\n\n- Maximum file size: 5 MB per log file.\n- Maximum files: 3 total, including the active file.\n- Worst-case disk usage: About 15 MB.\n\nRotation uses the usual numbered-copy scheme: the active `.log` becomes `.log.1`, the previous `.log.1` becomes `.log.2`, and the oldest rotated file is removed.\n\n## Log Format\n\nEach line follows this structure:\n\n```text\nYYYY-MM-DDThh:mm:ss.mmmZ LEVEL [module] message\n```\n\nExample:\n\n```text\n2026-02-17T14:30:45.123Z INFO  [sambee_companion_lib] Step 1: Exchanging URI token...\n2026-02-17T14:30:45.456Z ERROR [frontend] Upload failed: network timeout\n2026-02-17T14:30:46.789Z WARN  [sambee_companion_lib::commands::upload] Upload attempt 1/3 failed: connection refused\n```\n\nFrontend messages use the module target `frontend` so you can distinguish browser-side UI logging from Rust-side command and backend behavior.\n\n## How Logging Reaches the File\n\nThe companion uses one unified file-log pipeline.\n\n### Rust Side\n\nThe Rust logging module in `companion/src-tauri/src/logging.rs` implements the `log::Log` trait. Existing Rust-side `info!()`, `warn!()`, `error!()`, and `debug!()` calls therefore write into the same rotating companion log file.\n\nIf file logging initialization fails, the app falls back to stderr logging so startup can still proceed and terminal-launched sessions still have diagnostic output.\n\n### Frontend Side\n\nThe frontend logger in `companion/src/lib/logger.ts` writes to both:\n\n- The browser console for local developer-tools visibility.\n- The Rust backend through the `log_from_frontend` Tauri command so the same message lands in the file log.\n\nThat means support logs can contain both frontend and backend events in one timeline.\n\nThe frontend logger is fire-and-forget. Logging should never block the UI or surface a user-facing error because the log write itself failed.\n\n## Windows Webview2 Runtime Data\n\nOn Windows, the embedded WebView2 runtime stores its data at:\n\n- `%LOCALAPPDATA%\\app.sambee.companion\\EBWebView\\`\n\nThis directory is runtime-managed and is recreated automatically if removed.\n", "2.0": "+++\ntitle = \"Companion Support Reference\"\n+++\n\n## Communication and Security Model\n\nSambee uses two different browser-to-companion paths, depending on the workflow.\n\n- Local-drive browsing uses the companion's localhost API on `127.0.0.1:21549`.\n- Real-time local directory updates use a localhost WebSocket on the same port.\n- Desktop-app opening uses the `sambee://` custom URI scheme.\n\nThe localhost API is bound to the local machine only. It is not meant for remote network access.\n\nLocalhost traffic is authenticated after pairing, but it is not transport-encrypted.\n\n- HTTP requests use an HMAC derived from a shared secret and a current timestamp.\n- WebSocket and browser resource URLs use the same HMAC model through query parameters because browsers cannot attach custom headers in those cases.\n- The companion rejects requests outside the allowed clock-skew window.\n- Pairing is scoped to the browser origin, not just to the machine as a whole.\n\nThe shared secret is created only after the user confirms the same pairing code in both the browser and the companion. The companion stores its copy in the OS credential store. The browser stores its copy locally for that paired browser profile at that Sambee origin.\n\nIf you need contributor-level implementation detail, continue to the developer guide page [Browser-to-Companion Trust Model](../../../../0.7/developer-guide/companion-architecture/browser-to-companion-trust-model/).\n\n## Preference Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%APPDATA%\\app.sambee.companion\\` |\n| macOS | `~/Library/Application Support/app.sambee.companion/` |\n| Linux | `~/.local/share/app.sambee.companion/` |\n\nDeleting `user-preferences.json` and `app-preferences.json` resets companion settings.\n\n## Log Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%LOCALAPPDATA%\\Sambee\\Companion\\logs\\sambee-companion.log` |\n| macOS | `~/Library/Application Support/app.sambee.companion/logs/sambee-companion.log` |\n| Linux | `~/.local/share/sambee-companion/logs/sambee-companion.log` |\n\nThe companion writes both Rust-backend messages and TypeScript-frontend messages into the same rotating log file.\n\n## Log Levels\n\n| Level | When captured | Typical use |\n|---|---|---|\n| `error` | Always | failures that stop an operation from completing |\n| `warn` | Always | degraded but non-fatal behavior |\n| `info` | Verbose mode only | lifecycle steps and state transitions |\n| `debug` | Verbose mode only for Sambee app and frontend logs | detailed diagnostic context |\n\nErrors and warnings are always written, even when verbose logging is off. That keeps production incidents diagnosable without requiring the user to reproduce them in a special logging mode.\n\nNormal verbose logging keeps dependency transport logs quiet. HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls` are enabled separately because they can be very noisy.\n\n## Logging Controls\n\nLogging settings are read once at startup, so restart the companion after changing logging registry values or logging environment variables.\n\nTwo logging toggles are available:\n\n| Setting | Purpose |\n|---|---|\n| `VerboseLogging` | Enables verbose Sambee app and frontend logs. |\n| `TransportLogging` | Enables HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls`. |\n\n### Windows Registry Values\n\nOn Windows, configure logging through registry values under:\n\n```text\nHKEY_CURRENT_USER\\Software\\Sambee\\Companion\n```\n\nUse type `REG_DWORD`. A non-zero value enables the setting. A missing value or `0` leaves the setting disabled.\n\nTo enable verbose Sambee app and frontend logs:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 1 /f\n```\n\nTo enable HTTP transport diagnostics:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 1 /f\n```\n\nTo disable them again:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 0 /f\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 0 /f\n```\n\nRestart Companion after changing either registry value.\n\n### Linux and macOS Environment Variables\n\nOn Linux and macOS, launch the companion with environment variables for the logging modes you need.\n\nVerbose Sambee app and frontend logs:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 ./sambee-companion\n```\n\nHTTP transport diagnostics:\n\n```bash\nSAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nYou can combine both logging modes:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 SAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nThe environment variables are also available on Windows for one-off terminal-launched debugging and take precedence over the registry values. Use `0` or `false` to force a setting off for that launch.\n\nUse verbose logging when the normal log file does not explain why startup, local-drive access, or file-return workflows are failing. Add transport diagnostics when you need HTTP, TLS, proxy, or HTTP/2 details.\n\n## Support Log Checklist\n\nWhen collecting Companion logs for a native-editing issue, include:\n\n- Whether the `Sambee Authentication` window appeared.\n- Whether the failure happened during token exchange, file-info lookup, lock acquisition, download, upload, lock release, or heartbeat.\n- Whether Companion reported a lifecycle state such as renewal required, authentication failed, lock lost, or recovery required.\n- The reverse proxy or SSO product in front of Sambee, if one is used.\n- The Companion log file from the affected desktop.\n\nWhen verbose logging is enabled, include any operation or lock identifiers shown near the failing step. Those identifiers help correlate token exchange, lock acquisition, renewal, upload, and release events without exposing the secret material itself.\n\nCompanion sanitizes URLs before writing request diagnostics. Sensitive query values such as tokens, secrets, passwords, cookies, authorization data, sessions, keys, and theme payloads should not appear in support logs.\n\n## Log Rotation\n\nThe companion rotates logs automatically to avoid unbounded disk growth.\n\n- Maximum file size: 5 MB per log file.\n- Maximum files: 3 total, including the active file.\n- Worst-case disk usage: About 15 MB.\n\nRotation uses the usual numbered-copy scheme: the active `.log` becomes `.log.1`, the previous `.log.1` becomes `.log.2`, and the oldest rotated file is removed.\n\n## Log Format\n\nEach line follows this structure:\n\n```text\nYYYY-MM-DDThh:mm:ss.mmmZ LEVEL [module] message\n```\n\nExample:\n\n```text\n2026-02-17T14:30:45.123Z INFO  [sambee_companion_lib] Step 1: Exchanging URI token...\n2026-02-17T14:30:45.456Z ERROR [frontend] Upload failed: network timeout\n2026-02-17T14:30:46.789Z WARN  [sambee_companion_lib::commands::upload] Upload attempt 1/3 failed: connection refused\n```\n\nFrontend messages use the module target `frontend` so you can distinguish browser-side UI logging from Rust-side command and backend behavior.\n\n## How Logging Reaches the File\n\nThe companion uses one unified file-log pipeline.\n\n### Rust Side\n\nThe Rust logging module in `companion/src-tauri/src/logging.rs` implements the `log::Log` trait. Existing Rust-side `info!()`, `warn!()`, `error!()`, and `debug!()` calls therefore write into the same rotating companion log file.\n\nIf file logging initialization fails, the app falls back to stderr logging so startup can still proceed and terminal-launched sessions still have diagnostic output.\n\n### Frontend Side\n\nThe frontend logger in `companion/src/lib/logger.ts` writes to both:\n\n- The browser console for local developer-tools visibility.\n- The Rust backend through the `log_from_frontend` Tauri command so the same message lands in the file log.\n\nThat means support logs can contain both frontend and backend events in one timeline.\n\nThe frontend logger is fire-and-forget. Logging should never block the UI or surface a user-facing error because the log write itself failed.\n\n## Windows Webview2 Runtime Data\n\nOn Windows, the embedded WebView2 runtime stores its data at:\n\n- `%LOCALAPPDATA%\\app.sambee.companion\\EBWebView\\`\n\nThis directory is runtime-managed and is recreated automatically if removed.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Companion Support Reference\"\n+++\n\n## Communication and Security Model\n\nSambee uses two different browser-to-companion paths, depending on the workflow.\n\n- Local-drive browsing uses the companion's localhost API on `127.0.0.1:21549`.\n- Real-time local directory updates use a localhost WebSocket on the same port.\n- Desktop-app opening uses the `sambee://` custom URI scheme.\n\nThe localhost API is bound to the local machine only. It is not meant for remote network access.\n\nLocalhost traffic is authenticated after pairing, but it is not transport-encrypted.\n\n- HTTP requests use an HMAC derived from a shared secret and a current timestamp.\n- WebSocket and browser resource URLs use the same HMAC model through query parameters because browsers cannot attach custom headers in those cases.\n- The companion rejects requests outside the allowed clock-skew window.\n- Pairing is scoped to the browser origin, not just to the machine as a whole.\n\nThe shared secret is created only after the user confirms the same pairing code in both the browser and the companion. The companion stores its copy in the OS credential store. The browser stores its copy locally for that paired browser profile at that Sambee origin.\n\nIf you need contributor-level implementation detail, continue to the developer guide page [Browser-to-Companion Trust Model](../../../../0.7/developer-guide/companion-architecture/browser-to-companion-trust-model/).\n\n## Preference Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%APPDATA%\\app.sambee.companion\\` |\n| macOS | `~/Library/Application Support/app.sambee.companion/` |\n| Linux | `~/.local/share/app.sambee.companion/` |\n\nDeleting `user-preferences.json` and `app-preferences.json` resets companion settings.\n\n## Log Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%LOCALAPPDATA%\\Sambee\\Companion\\logs\\sambee-companion.log` |\n| macOS | `~/Library/Application Support/app.sambee.companion/logs/sambee-companion.log` |\n| Linux | `~/.local/share/sambee-companion/logs/sambee-companion.log` |\n\nThe companion writes both Rust-backend messages and TypeScript-frontend messages into the same rotating log file.\n\n## Log Levels\n\n| Level | When captured | Typical use |\n|---|---|---|\n| `error` | Always | failures that stop an operation from completing |\n| `warn` | Always | degraded but non-fatal behavior |\n| `info` | Verbose mode only | lifecycle steps and state transitions |\n| `debug` | Verbose mode only for Sambee app and frontend logs | detailed diagnostic context |\n\nErrors and warnings are always written, even when verbose logging is off. That keeps production incidents diagnosable without requiring the user to reproduce them in a special logging mode.\n\nNormal verbose logging keeps dependency transport logs quiet. HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls` are enabled separately because they can be very noisy.\n\n## Logging Controls\n\nLogging settings are read once at startup, so restart the companion after changing logging registry values or logging environment variables.\n\nTwo logging toggles are available:\n\n| Setting | Purpose |\n|---|---|\n| `VerboseLogging` | Enables verbose Sambee app and frontend logs. |\n| `TransportLogging` | Enables HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls`. |\n\n### Windows Registry Values\n\nOn Windows, configure logging through registry values under:\n\n```text\nHKEY_CURRENT_USER\\Software\\Sambee\\Companion\n```\n\nUse type `REG_DWORD`. A non-zero value enables the setting. A missing value or `0` leaves the setting disabled.\n\nTo enable verbose Sambee app and frontend logs:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 1 /f\n```\n\nTo enable HTTP transport diagnostics:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 1 /f\n```\n\nTo disable them again:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 0 /f\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 0 /f\n```\n\nRestart Companion after changing either registry value.\n\n### Linux and macOS Environment Variables\n\nOn Linux and macOS, launch the companion with environment variables for the logging modes you need.\n\nVerbose Sambee app and frontend logs:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 ./sambee-companion\n```\n\nHTTP transport diagnostics:\n\n```bash\nSAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nYou can combine both logging modes:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 SAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nThe environment variables are also available on Windows for one-off terminal-launched debugging and take precedence over the registry values. Use `0` or `false` to force a setting off for that launch.\n\nUse verbose logging when the normal log file does not explain why startup, local-drive access, or file-return workflows are failing. Add transport diagnostics when you need HTTP, TLS, proxy, or HTTP/2 details.\n\n## Support Log Checklist\n\nWhen collecting Companion logs for a native-editing issue, include:\n\n- Whether the `Sambee Authentication` window appeared.\n- Whether the failure happened during token exchange, file-info lookup, lock acquisition, download, upload, lock release, or heartbeat.\n- Whether Companion reported a lifecycle state such as renewal required, authentication failed, lock lost, or recovery required.\n- The reverse proxy or SSO product in front of Sambee, if one is used.\n- The Companion log file from the affected desktop.\n\nWhen verbose logging is enabled, include any operation or lock identifiers shown near the failing step. Those identifiers help correlate token exchange, lock acquisition, renewal, upload, and release events without exposing the secret material itself.\n\nCompanion sanitizes URLs before writing request diagnostics. Sensitive query values such as tokens, secrets, passwords, cookies, authorization data, sessions, keys, and theme payloads should not appear in support logs.\n\n## Log Rotation\n\nThe companion rotates logs automatically to avoid unbounded disk growth.\n\n- Maximum file size: 5 MB per log file.\n- Maximum files: 3 total, including the active file.\n- Worst-case disk usage: About 15 MB.\n\nRotation uses the usual numbered-copy scheme: the active `.log` becomes `.log.1`, the previous `.log.1` becomes `.log.2`, and the oldest rotated file is removed.\n\n## Log Format\n\nEach line follows this structure:\n\n```text\nYYYY-MM-DDThh:mm:ss.mmmZ LEVEL [module] message\n```\n\nExample:\n\n```text\n2026-02-17T14:30:45.123Z INFO  [sambee_companion_lib] Step 1: Exchanging URI token...\n2026-02-17T14:30:45.456Z ERROR [frontend] Upload failed: network timeout\n2026-02-17T14:30:46.789Z WARN  [sambee_companion_lib::commands::upload] Upload attempt 1/3 failed: connection refused\n```\n\nFrontend messages use the module target `frontend` so you can distinguish browser-side UI logging from Rust-side command and backend behavior.\n\n## How Logging Reaches the File\n\nThe companion uses one unified file-log pipeline.\n\n### Rust Side\n\nThe Rust logging module in `companion/src-tauri/src/logging.rs` implements the `log::Log` trait. Existing Rust-side `info!()`, `warn!()`, `error!()`, and `debug!()` calls therefore write into the same rotating companion log file.\n\nIf file logging initialization fails, the app falls back to stderr logging so startup can still proceed and terminal-launched sessions still have diagnostic output.\n\n### Frontend Side\n\nThe frontend logger in `companion/src/lib/logger.ts` writes to both:\n\n- The browser console for local developer-tools visibility.\n- The Rust backend through the `log_from_frontend` Tauri command so the same message lands in the file log.\n\nThat means support logs can contain both frontend and backend events in one timeline.\n\nThe frontend logger is fire-and-forget. Logging should never block the UI or surface a user-facing error because the log write itself failed.\n\n## Windows Webview2 Runtime Data\n\nOn Windows, the embedded WebView2 runtime stores its data at:\n\n- `%LOCALAPPDATA%\\app.sambee.companion\\EBWebView\\`\n\nThis directory is runtime-managed and is recreated automatically if removed.\n", "0.8": "+++\ntitle = \"Companion Support Reference\"\n+++\n\n## Communication and Security Model\n\nSambee uses two different browser-to-companion paths, depending on the workflow.\n\n- Local-drive browsing uses the companion's localhost API on `127.0.0.1:21549`.\n- Real-time local directory updates use a localhost WebSocket on the same port.\n- Desktop-app opening uses the `sambee://` custom URI scheme.\n\nThe localhost API is bound to the local machine only. It is not meant for remote network access.\n\nLocalhost traffic is authenticated after pairing, but it is not transport-encrypted.\n\n- HTTP requests use an HMAC derived from a shared secret and a current timestamp.\n- WebSocket and browser resource URLs use the same HMAC model through query parameters because browsers cannot attach custom headers in those cases.\n- The companion rejects requests outside the allowed clock-skew window.\n- Pairing is scoped to the browser origin, not just to the machine as a whole.\n\nThe shared secret is created only after the user confirms the same pairing code in both the browser and the companion. The companion stores its copy in the OS credential store. The browser stores its copy locally for that paired browser profile at that Sambee origin.\n\nIf you need contributor-level implementation detail, continue to the developer guide page [Browser-to-Companion Trust Model](../../../../0.7/developer-guide/companion-architecture/browser-to-companion-trust-model/).\n\n## Preference Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%APPDATA%\\app.sambee.companion\\` |\n| macOS | `~/Library/Application Support/app.sambee.companion/` |\n| Linux | `~/.local/share/app.sambee.companion/` |\n\nDeleting `user-preferences.json` and `app-preferences.json` resets companion settings.\n\n## Log Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%LOCALAPPDATA%\\Sambee\\Companion\\logs\\sambee-companion.log` |\n| macOS | `~/Library/Application Support/app.sambee.companion/logs/sambee-companion.log` |\n| Linux | `~/.local/share/sambee-companion/logs/sambee-companion.log` |\n\nThe companion writes both Rust-backend messages and TypeScript-frontend messages into the same rotating log file.\n\n## Log Levels\n\n| Level | When captured | Typical use |\n|---|---|---|\n| `error` | Always | failures that stop an operation from completing |\n| `warn` | Always | degraded but non-fatal behavior |\n| `info` | Verbose mode only | lifecycle steps and state transitions |\n| `debug` | Verbose mode only for Sambee app and frontend logs | detailed diagnostic context |\n\nErrors and warnings are always written, even when verbose logging is off. That keeps production incidents diagnosable without requiring the user to reproduce them in a special logging mode.\n\nNormal verbose logging keeps dependency transport logs quiet. HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls` are enabled separately because they can be very noisy.\n\n## Logging Controls\n\nLogging settings are read once at startup, so restart the companion after changing logging registry values or logging environment variables.\n\nTwo logging toggles are available:\n\n| Setting | Purpose |\n|---|---|\n| `VerboseLogging` | Enables verbose Sambee app and frontend logs. |\n| `TransportLogging` | Enables HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls`. |\n\n### Windows Registry Values\n\nOn Windows, configure logging through registry values under:\n\n```text\nHKEY_CURRENT_USER\\Software\\Sambee\\Companion\n```\n\nUse type `REG_DWORD`. A non-zero value enables the setting. A missing value or `0` leaves the setting disabled.\n\nTo enable verbose Sambee app and frontend logs:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 1 /f\n```\n\nTo enable HTTP transport diagnostics:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 1 /f\n```\n\nTo disable them again:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 0 /f\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 0 /f\n```\n\nRestart Companion after changing either registry value.\n\n### Linux and macOS Environment Variables\n\nOn Linux and macOS, launch the companion with environment variables for the logging modes you need.\n\nVerbose Sambee app and frontend logs:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 ./sambee-companion\n```\n\nHTTP transport diagnostics:\n\n```bash\nSAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nYou can combine both logging modes:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 SAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nThe environment variables are also available on Windows for one-off terminal-launched debugging and take precedence over the registry values. Use `0` or `false` to force a setting off for that launch.\n\nUse verbose logging when the normal log file does not explain why startup, local-drive access, or file-return workflows are failing. Add transport diagnostics when you need HTTP, TLS, proxy, or HTTP/2 details.\n\n## Support Log Checklist\n\nWhen collecting Companion logs for a native-editing issue, include:\n\n- Whether the `Sambee Authentication` window appeared.\n- Whether the failure happened during token exchange, file-info lookup, lock acquisition, download, upload, lock release, or heartbeat.\n- Whether Companion reported a lifecycle state such as renewal required, authentication failed, lock lost, or recovery required.\n- The reverse proxy or SSO product in front of Sambee, if one is used.\n- The Companion log file from the affected desktop.\n\nWhen verbose logging is enabled, include any operation or lock identifiers shown near the failing step. Those identifiers help correlate token exchange, lock acquisition, renewal, upload, and release events without exposing the secret material itself.\n\nCompanion sanitizes URLs before writing request diagnostics. Sensitive query values such as tokens, secrets, passwords, cookies, authorization data, sessions, keys, and theme payloads should not appear in support logs.\n\n## Log Rotation\n\nThe companion rotates logs automatically to avoid unbounded disk growth.\n\n- Maximum file size: 5 MB per log file.\n- Maximum files: 3 total, including the active file.\n- Worst-case disk usage: About 15 MB.\n\nRotation uses the usual numbered-copy scheme: the active `.log` becomes `.log.1`, the previous `.log.1` becomes `.log.2`, and the oldest rotated file is removed.\n\n## Log Format\n\nEach line follows this structure:\n\n```text\nYYYY-MM-DDThh:mm:ss.mmmZ LEVEL [module] message\n```\n\nExample:\n\n```text\n2026-02-17T14:30:45.123Z INFO  [sambee_companion_lib] Step 1: Exchanging URI token...\n2026-02-17T14:30:45.456Z ERROR [frontend] Upload failed: network timeout\n2026-02-17T14:30:46.789Z WARN  [sambee_companion_lib::commands::upload] Upload attempt 1/3 failed: connection refused\n```\n\nFrontend messages use the module target `frontend` so you can distinguish browser-side UI logging from Rust-side command and backend behavior.\n\n## How Logging Reaches the File\n\nThe companion uses one unified file-log pipeline.\n\n### Rust Side\n\nThe Rust logging module in `companion/src-tauri/src/logging.rs` implements the `log::Log` trait. Existing Rust-side `info!()`, `warn!()`, `error!()`, and `debug!()` calls therefore write into the same rotating companion log file.\n\nIf file logging initialization fails, the app falls back to stderr logging so startup can still proceed and terminal-launched sessions still have diagnostic output.\n\n### Frontend Side\n\nThe frontend logger in `companion/src/lib/logger.ts` writes to both:\n\n- The browser console for local developer-tools visibility.\n- The Rust backend through the `log_from_frontend` Tauri command so the same message lands in the file log.\n\nThat means support logs can contain both frontend and backend events in one timeline.\n\nThe frontend logger is fire-and-forget. Logging should never block the UI or surface a user-facing error because the log write itself failed.\n\n## Windows Webview2 Runtime Data\n\nOn Windows, the embedded WebView2 runtime stores its data at:\n\n- `%LOCALAPPDATA%\\app.sambee.companion\\EBWebView\\`\n\nThis directory is runtime-managed and is recreated automatically if removed.\n", "0.9": "+++\ntitle = \"Companion Support Reference\"\n+++\n\n## Communication and Security Model\n\nSambee uses two different browser-to-companion paths, depending on the workflow.\n\n- Local-drive browsing uses the companion's localhost API on `127.0.0.1:21549`.\n- Real-time local directory updates use a localhost WebSocket on the same port.\n- Desktop-app opening uses the `sambee://` custom URI scheme.\n\nThe localhost API is bound to the local machine only. It is not meant for remote network access.\n\nLocalhost traffic is authenticated after pairing, but it is not transport-encrypted.\n\n- HTTP requests use an HMAC derived from a shared secret and a current timestamp.\n- WebSocket and browser resource URLs use the same HMAC model through query parameters because browsers cannot attach custom headers in those cases.\n- The companion rejects requests outside the allowed clock-skew window.\n- Pairing is scoped to the browser origin, not just to the machine as a whole.\n\nThe shared secret is created only after the user confirms the same pairing code in both the browser and the companion. The companion stores its copy in the OS credential store. The browser stores its copy locally for that paired browser profile at that Sambee origin.\n\nIf you need contributor-level implementation detail, continue to the developer guide page [Browser-to-Companion Trust Model](../../../../0.7/developer-guide/companion-architecture/browser-to-companion-trust-model/).\n\n## Preference Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%APPDATA%\\app.sambee.companion\\` |\n| macOS | `~/Library/Application Support/app.sambee.companion/` |\n| Linux | `~/.local/share/app.sambee.companion/` |\n\nDeleting `user-preferences.json` and `app-preferences.json` resets companion settings.\n\n## Log Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%LOCALAPPDATA%\\Sambee\\Companion\\logs\\sambee-companion.log` |\n| macOS | `~/Library/Application Support/app.sambee.companion/logs/sambee-companion.log` |\n| Linux | `~/.local/share/sambee-companion/logs/sambee-companion.log` |\n\nThe companion writes both Rust-backend messages and TypeScript-frontend messages into the same rotating log file.\n\n## Log Levels\n\n| Level | When captured | Typical use |\n|---|---|---|\n| `error` | Always | failures that stop an operation from completing |\n| `warn` | Always | degraded but non-fatal behavior |\n| `info` | Verbose mode only | lifecycle steps and state transitions |\n| `debug` | Verbose mode only for Sambee app and frontend logs | detailed diagnostic context |\n\nErrors and warnings are always written, even when verbose logging is off. That keeps production incidents diagnosable without requiring the user to reproduce them in a special logging mode.\n\nNormal verbose logging keeps dependency transport logs quiet. HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls` are enabled separately because they can be very noisy.\n\n## Logging Controls\n\nLogging settings are read once at startup, so restart the companion after changing logging registry values or logging environment variables.\n\nTwo logging toggles are available:\n\n| Setting | Purpose |\n|---|---|\n| `VerboseLogging` | Enables verbose Sambee app and frontend logs. |\n| `TransportLogging` | Enables HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls`. |\n\n### Windows Registry Values\n\nOn Windows, configure logging through registry values under:\n\n```text\nHKEY_CURRENT_USER\\Software\\Sambee\\Companion\n```\n\nUse type `REG_DWORD`. A non-zero value enables the setting. A missing value or `0` leaves the setting disabled.\n\nTo enable verbose Sambee app and frontend logs:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 1 /f\n```\n\nTo enable HTTP transport diagnostics:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 1 /f\n```\n\nTo disable them again:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 0 /f\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 0 /f\n```\n\nRestart Companion after changing either registry value.\n\n### Linux and macOS Environment Variables\n\nOn Linux and macOS, launch the companion with environment variables for the logging modes you need.\n\nVerbose Sambee app and frontend logs:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 ./sambee-companion\n```\n\nHTTP transport diagnostics:\n\n```bash\nSAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nYou can combine both logging modes:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 SAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nThe environment variables are also available on Windows for one-off terminal-launched debugging and take precedence over the registry values. Use `0` or `false` to force a setting off for that launch.\n\nUse verbose logging when the normal log file does not explain why startup, local-drive access, or file-return workflows are failing. Add transport diagnostics when you need HTTP, TLS, proxy, or HTTP/2 details.\n\n## Support Log Checklist\n\nWhen collecting Companion logs for a native-editing issue, include:\n\n- Whether the `Sambee Authentication` window appeared.\n- Whether the failure happened during token exchange, file-info lookup, lock acquisition, download, upload, lock release, or heartbeat.\n- Whether Companion reported a lifecycle state such as renewal required, authentication failed, lock lost, or recovery required.\n- The reverse proxy or SSO product in front of Sambee, if one is used.\n- The Companion log file from the affected desktop.\n\nWhen verbose logging is enabled, include any operation or lock identifiers shown near the failing step. Those identifiers help correlate token exchange, lock acquisition, renewal, upload, and release events without exposing the secret material itself.\n\nCompanion sanitizes URLs before writing request diagnostics. Sensitive query values such as tokens, secrets, passwords, cookies, authorization data, sessions, keys, and theme payloads should not appear in support logs.\n\n## Log Rotation\n\nThe companion rotates logs automatically to avoid unbounded disk growth.\n\n- Maximum file size: 5 MB per log file.\n- Maximum files: 3 total, including the active file.\n- Worst-case disk usage: About 15 MB.\n\nRotation uses the usual numbered-copy scheme: the active `.log` becomes `.log.1`, the previous `.log.1` becomes `.log.2`, and the oldest rotated file is removed.\n\n## Log Format\n\nEach line follows this structure:\n\n```text\nYYYY-MM-DDThh:mm:ss.mmmZ LEVEL [module] message\n```\n\nExample:\n\n```text\n2026-02-17T14:30:45.123Z INFO  [sambee_companion_lib] Step 1: Exchanging URI token...\n2026-02-17T14:30:45.456Z ERROR [frontend] Upload failed: network timeout\n2026-02-17T14:30:46.789Z WARN  [sambee_companion_lib::commands::upload] Upload attempt 1/3 failed: connection refused\n```\n\nFrontend messages use the module target `frontend` so you can distinguish browser-side UI logging from Rust-side command and backend behavior.\n\n## How Logging Reaches the File\n\nThe companion uses one unified file-log pipeline.\n\n### Rust Side\n\nThe Rust logging module in `companion/src-tauri/src/logging.rs` implements the `log::Log` trait. Existing Rust-side `info!()`, `warn!()`, `error!()`, and `debug!()` calls therefore write into the same rotating companion log file.\n\nIf file logging initialization fails, the app falls back to stderr logging so startup can still proceed and terminal-launched sessions still have diagnostic output.\n\n### Frontend Side\n\nThe frontend logger in `companion/src/lib/logger.ts` writes to both:\n\n- The browser console for local developer-tools visibility.\n- The Rust backend through the `log_from_frontend` Tauri command so the same message lands in the file log.\n\nThat means support logs can contain both frontend and backend events in one timeline.\n\nThe frontend logger is fire-and-forget. Logging should never block the UI or surface a user-facing error because the log write itself failed.\n\n## Windows Webview2 Runtime Data\n\nOn Windows, the embedded WebView2 runtime stores its data at:\n\n- `%LOCALAPPDATA%\\app.sambee.companion\\EBWebView\\`\n\nThis directory is runtime-managed and is recreated automatically if removed.\n", "1.0": "+++\ntitle = \"Companion Support Reference\"\n+++\n\n## Communication and Security Model\n\nSambee uses two different browser-to-companion paths, depending on the workflow.\n\n- Local-drive browsing uses the companion's localhost API on `127.0.0.1:21549`.\n- Real-time local directory updates use a localhost WebSocket on the same port.\n- Desktop-app opening uses the `sambee://` custom URI scheme.\n\nThe localhost API is bound to the local machine only. It is not meant for remote network access.\n\nLocalhost traffic is authenticated after pairing, but it is not transport-encrypted.\n\n- HTTP requests use an HMAC derived from a shared secret and a current timestamp.\n- WebSocket and browser resource URLs use the same HMAC model through query parameters because browsers cannot attach custom headers in those cases.\n- The companion rejects requests outside the allowed clock-skew window.\n- Pairing is scoped to the browser origin, not just to the machine as a whole.\n\nThe shared secret is created only after the user confirms the same pairing code in both the browser and the companion. The companion stores its copy in the OS credential store. The browser stores its copy locally for that paired browser profile at that Sambee origin.\n\nIf you need contributor-level implementation detail, continue to the developer guide page [Browser-to-Companion Trust Model](../../../../0.7/developer-guide/companion-architecture/browser-to-companion-trust-model/).\n\n## Preference Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%APPDATA%\\app.sambee.companion\\` |\n| macOS | `~/Library/Application Support/app.sambee.companion/` |\n| Linux | `~/.local/share/app.sambee.companion/` |\n\nDeleting `user-preferences.json` and `app-preferences.json` resets companion settings.\n\n## Log Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%LOCALAPPDATA%\\Sambee\\Companion\\logs\\sambee-companion.log` |\n| macOS | `~/Library/Application Support/app.sambee.companion/logs/sambee-companion.log` |\n| Linux | `~/.local/share/sambee-companion/logs/sambee-companion.log` |\n\nThe companion writes both Rust-backend messages and TypeScript-frontend messages into the same rotating log file.\n\n## Log Levels\n\n| Level | When captured | Typical use |\n|---|---|---|\n| `error` | Always | failures that stop an operation from completing |\n| `warn` | Always | degraded but non-fatal behavior |\n| `info` | Verbose mode only | lifecycle steps and state transitions |\n| `debug` | Verbose mode only for Sambee app and frontend logs | detailed diagnostic context |\n\nErrors and warnings are always written, even when verbose logging is off. That keeps production incidents diagnosable without requiring the user to reproduce them in a special logging mode.\n\nNormal verbose logging keeps dependency transport logs quiet. HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls` are enabled separately because they can be very noisy.\n\n## Logging Controls\n\nLogging settings are read once at startup, so restart the companion after changing logging registry values or logging environment variables.\n\nTwo logging toggles are available:\n\n| Setting | Purpose |\n|---|---|\n| `VerboseLogging` | Enables verbose Sambee app and frontend logs. |\n| `TransportLogging` | Enables HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls`. |\n\n### Windows Registry Values\n\nOn Windows, configure logging through registry values under:\n\n```text\nHKEY_CURRENT_USER\\Software\\Sambee\\Companion\n```\n\nUse type `REG_DWORD`. A non-zero value enables the setting. A missing value or `0` leaves the setting disabled.\n\nTo enable verbose Sambee app and frontend logs:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 1 /f\n```\n\nTo enable HTTP transport diagnostics:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 1 /f\n```\n\nTo disable them again:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 0 /f\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 0 /f\n```\n\nRestart Companion after changing either registry value.\n\n### Linux and macOS Environment Variables\n\nOn Linux and macOS, launch the companion with environment variables for the logging modes you need.\n\nVerbose Sambee app and frontend logs:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 ./sambee-companion\n```\n\nHTTP transport diagnostics:\n\n```bash\nSAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nYou can combine both logging modes:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 SAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nThe environment variables are also available on Windows for one-off terminal-launched debugging and take precedence over the registry values. Use `0` or `false` to force a setting off for that launch.\n\nUse verbose logging when the normal log file does not explain why startup, local-drive access, or file-return workflows are failing. Add transport diagnostics when you need HTTP, TLS, proxy, or HTTP/2 details.\n\n## Support Log Checklist\n\nWhen collecting Companion logs for a native-editing issue, include:\n\n- Whether the `Sambee Authentication` window appeared.\n- Whether the failure happened during token exchange, file-info lookup, lock acquisition, download, upload, lock release, or heartbeat.\n- Whether Companion reported a lifecycle state such as renewal required, authentication failed, lock lost, or recovery required.\n- The reverse proxy or SSO product in front of Sambee, if one is used.\n- The Companion log file from the affected desktop.\n\nWhen verbose logging is enabled, include any operation or lock identifiers shown near the failing step. Those identifiers help correlate token exchange, lock acquisition, renewal, upload, and release events without exposing the secret material itself.\n\nCompanion sanitizes URLs before writing request diagnostics. Sensitive query values such as tokens, secrets, passwords, cookies, authorization data, sessions, keys, and theme payloads should not appear in support logs.\n\n## Log Rotation\n\nThe companion rotates logs automatically to avoid unbounded disk growth.\n\n- Maximum file size: 5 MB per log file.\n- Maximum files: 3 total, including the active file.\n- Worst-case disk usage: About 15 MB.\n\nRotation uses the usual numbered-copy scheme: the active `.log` becomes `.log.1`, the previous `.log.1` becomes `.log.2`, and the oldest rotated file is removed.\n\n## Log Format\n\nEach line follows this structure:\n\n```text\nYYYY-MM-DDThh:mm:ss.mmmZ LEVEL [module] message\n```\n\nExample:\n\n```text\n2026-02-17T14:30:45.123Z INFO  [sambee_companion_lib] Step 1: Exchanging URI token...\n2026-02-17T14:30:45.456Z ERROR [frontend] Upload failed: network timeout\n2026-02-17T14:30:46.789Z WARN  [sambee_companion_lib::commands::upload] Upload attempt 1/3 failed: connection refused\n```\n\nFrontend messages use the module target `frontend` so you can distinguish browser-side UI logging from Rust-side command and backend behavior.\n\n## How Logging Reaches the File\n\nThe companion uses one unified file-log pipeline.\n\n### Rust Side\n\nThe Rust logging module in `companion/src-tauri/src/logging.rs` implements the `log::Log` trait. Existing Rust-side `info!()`, `warn!()`, `error!()`, and `debug!()` calls therefore write into the same rotating companion log file.\n\nIf file logging initialization fails, the app falls back to stderr logging so startup can still proceed and terminal-launched sessions still have diagnostic output.\n\n### Frontend Side\n\nThe frontend logger in `companion/src/lib/logger.ts` writes to both:\n\n- The browser console for local developer-tools visibility.\n- The Rust backend through the `log_from_frontend` Tauri command so the same message lands in the file log.\n\nThat means support logs can contain both frontend and backend events in one timeline.\n\nThe frontend logger is fire-and-forget. Logging should never block the UI or surface a user-facing error because the log write itself failed.\n\n## Windows Webview2 Runtime Data\n\nOn Windows, the embedded WebView2 runtime stores its data at:\n\n- `%LOCALAPPDATA%\\app.sambee.companion\\EBWebView\\`\n\nThis directory is runtime-managed and is recreated automatically if removed.\n", "2.0": "+++\ntitle = \"Companion Support Reference\"\n+++\n\n## Communication and Security Model\n\nSambee uses two different browser-to-companion paths, depending on the workflow.\n\n- Local-drive browsing uses the companion's localhost API on `127.0.0.1:21549`.\n- Real-time local directory updates use a localhost WebSocket on the same port.\n- Desktop-app opening uses the `sambee://` custom URI scheme.\n\nThe localhost API is bound to the local machine only. It is not meant for remote network access.\n\nLocalhost traffic is authenticated after pairing, but it is not transport-encrypted.\n\n- HTTP requests use an HMAC derived from a shared secret and a current timestamp.\n- WebSocket and browser resource URLs use the same HMAC model through query parameters because browsers cannot attach custom headers in those cases.\n- The companion rejects requests outside the allowed clock-skew window.\n- Pairing is scoped to the browser origin, not just to the machine as a whole.\n\nThe shared secret is created only after the user confirms the same pairing code in both the browser and the companion. The companion stores its copy in the OS credential store. The browser stores its copy locally for that paired browser profile at that Sambee origin.\n\nIf you need contributor-level implementation detail, continue to the developer guide page [Browser-to-Companion Trust Model](../../../../0.7/developer-guide/companion-architecture/browser-to-companion-trust-model/).\n\n## Preference Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%APPDATA%\\app.sambee.companion\\` |\n| macOS | `~/Library/Application Support/app.sambee.companion/` |\n| Linux | `~/.local/share/app.sambee.companion/` |\n\nDeleting `user-preferences.json` and `app-preferences.json` resets companion settings.\n\n## Log Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%LOCALAPPDATA%\\Sambee\\Companion\\logs\\sambee-companion.log` |\n| macOS | `~/Library/Application Support/app.sambee.companion/logs/sambee-companion.log` |\n| Linux | `~/.local/share/sambee-companion/logs/sambee-companion.log` |\n\nThe companion writes both Rust-backend messages and TypeScript-frontend messages into the same rotating log file.\n\n## Log Levels\n\n| Level | When captured | Typical use |\n|---|---|---|\n| `error` | Always | failures that stop an operation from completing |\n| `warn` | Always | degraded but non-fatal behavior |\n| `info` | Verbose mode only | lifecycle steps and state transitions |\n| `debug` | Verbose mode only for Sambee app and frontend logs | detailed diagnostic context |\n\nErrors and warnings are always written, even when verbose logging is off. That keeps production incidents diagnosable without requiring the user to reproduce them in a special logging mode.\n\nNormal verbose logging keeps dependency transport logs quiet. HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls` are enabled separately because they can be very noisy.\n\n## Logging Controls\n\nLogging settings are read once at startup, so restart the companion after changing logging registry values or logging environment variables.\n\nTwo logging toggles are available:\n\n| Setting | Purpose |\n|---|---|\n| `VerboseLogging` | Enables verbose Sambee app and frontend logs. |\n| `TransportLogging` | Enables HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls`. |\n\n### Windows Registry Values\n\nOn Windows, configure logging through registry values under:\n\n```text\nHKEY_CURRENT_USER\\Software\\Sambee\\Companion\n```\n\nUse type `REG_DWORD`. A non-zero value enables the setting. A missing value or `0` leaves the setting disabled.\n\nTo enable verbose Sambee app and frontend logs:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 1 /f\n```\n\nTo enable HTTP transport diagnostics:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 1 /f\n```\n\nTo disable them again:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 0 /f\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 0 /f\n```\n\nRestart Companion after changing either registry value.\n\n### Linux and macOS Environment Variables\n\nOn Linux and macOS, launch the companion with environment variables for the logging modes you need.\n\nVerbose Sambee app and frontend logs:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 ./sambee-companion\n```\n\nHTTP transport diagnostics:\n\n```bash\nSAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nYou can combine both logging modes:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 SAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nThe environment variables are also available on Windows for one-off terminal-launched debugging and take precedence over the registry values. Use `0` or `false` to force a setting off for that launch.\n\nUse verbose logging when the normal log file does not explain why startup, local-drive access, or file-return workflows are failing. Add transport diagnostics when you need HTTP, TLS, proxy, or HTTP/2 details.\n\n## Support Log Checklist\n\nWhen collecting Companion logs for a native-editing issue, include:\n\n- Whether the `Sambee Authentication` window appeared.\n- Whether the failure happened during token exchange, file-info lookup, lock acquisition, download, upload, lock release, or heartbeat.\n- Whether Companion reported a lifecycle state such as renewal required, authentication failed, lock lost, or recovery required.\n- The reverse proxy or SSO product in front of Sambee, if one is used.\n- The Companion log file from the affected desktop.\n\nWhen verbose logging is enabled, include any operation or lock identifiers shown near the failing step. Those identifiers help correlate token exchange, lock acquisition, renewal, upload, and release events without exposing the secret material itself.\n\nCompanion sanitizes URLs before writing request diagnostics. Sensitive query values such as tokens, secrets, passwords, cookies, authorization data, sessions, keys, and theme payloads should not appear in support logs.\n\n## Log Rotation\n\nThe companion rotates logs automatically to avoid unbounded disk growth.\n\n- Maximum file size: 5 MB per log file.\n- Maximum files: 3 total, including the active file.\n- Worst-case disk usage: About 15 MB.\n\nRotation uses the usual numbered-copy scheme: the active `.log` becomes `.log.1`, the previous `.log.1` becomes `.log.2`, and the oldest rotated file is removed.\n\n## Log Format\n\nEach line follows this structure:\n\n```text\nYYYY-MM-DDThh:mm:ss.mmmZ LEVEL [module] message\n```\n\nExample:\n\n```text\n2026-02-17T14:30:45.123Z INFO  [sambee_companion_lib] Step 1: Exchanging URI token...\n2026-02-17T14:30:45.456Z ERROR [frontend] Upload failed: network timeout\n2026-02-17T14:30:46.789Z WARN  [sambee_companion_lib::commands::upload] Upload attempt 1/3 failed: connection refused\n```\n\nFrontend messages use the module target `frontend` so you can distinguish browser-side UI logging from Rust-side command and backend behavior.\n\n## How Logging Reaches the File\n\nThe companion uses one unified file-log pipeline.\n\n### Rust Side\n\nThe Rust logging module in `companion/src-tauri/src/logging.rs` implements the `log::Log` trait. Existing Rust-side `info!()`, `warn!()`, `error!()`, and `debug!()` calls therefore write into the same rotating companion log file.\n\nIf file logging initialization fails, the app falls back to stderr logging so startup can still proceed and terminal-launched sessions still have diagnostic output.\n\n### Frontend Side\n\nThe frontend logger in `companion/src/lib/logger.ts` writes to both:\n\n- The browser console for local developer-tools visibility.\n- The Rust backend through the `log_from_frontend` Tauri command so the same message lands in the file log.\n\nThat means support logs can contain both frontend and backend events in one timeline.\n\nThe frontend logger is fire-and-forget. Logging should never block the UI or surface a user-facing error because the log write itself failed.\n\n## Windows Webview2 Runtime Data\n\nOn Windows, the embedded WebView2 runtime stores its data at:\n\n- `%LOCALAPPDATA%\\app.sambee.companion\\EBWebView\\`\n\nThis directory is runtime-managed and is recreated automatically if removed.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:admin-guide/reference/configuration-file-reference", "parent_id": "section:admin-guide/reference", "depth": 2, "kind": "page", "label": "configuration-file-reference", "title": "Configuration File Reference", "path": "admin-guide/reference/configuration-file-reference", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "authored"}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "inherited", "source_version": "0.9"}}, "content_versions": {"0.9": "+++\ntitle = \"Configuration File Reference\"\n+++\n\nThis page is a compact map of the optional `config.toml` file.\n\nUse `config.example.toml` as the source of truth for supported keys. This page explains the sections that matter most in day-to-day administration.\n\n## How to Use This Reference\n\n- Copy only the keys you actually need into the local `config.toml`.\n- Keep the file local to the deployment and mount it read-only in production.\n- Treat commented defaults in `config.example.toml` as the baseline behavior unless you override them intentionally.\n- Expect most basic deployments to use only a small subset of these keys.\n\n## High-Value Sections and Keys\n\n| Section | Key | Operational effect |\n|---|---|---|\n| `[app]` | `log_level` | Sets application diagnostic verbosity and Uvicorn lifecycle logging. |\n| `[app]` | `access_log_level` | Sets Uvicorn HTTP request access-log verbosity. |\n| `[app]` | `protocol_log_level` | Sets Uvicorn WebSocket connection, frame, and keepalive log verbosity. |\n| `[auth]` | `disable_enforcement` | Temporarily bypasses all Sambee authentication enforcement at runtime. |\n| `[security]` | `access_token_expire_minutes` | Changes the short-lived API-token lifetime. OIDC sessions refresh this token in the background; configure the OIDC interactive sign-in interval separately in Authentication settings. |\n| `[admin]` | `username` | Sets the initial administrator username. |\n| `[image_viewer]` | `conv_size_thresh` | Controls when large images are always converted for viewing. |\n| `[frontend_logging]` | `logging_enabled`, `log_level` | Controls browser-console logging behavior. |\n| `[frontend_logging]` | `tracing_enabled`, `tracing_level`, `tracing_retention_hours` | Controls backend trace collection for frontend logging. |\n| `[frontend_logging]` | `tracing_components`, `tracing_username_regex` | Restricts tracing by component or user scope. |\n| `[directory_cache]` | `location`, `coalesce_interval_seconds`, `max_staleness_minutes` | Controls the saved directory index Sambee keeps to make browsing and search recover faster after restarts. |\n| `[preprocessors.imagemagick]` | `max_file_size_bytes`, `timeout_seconds` | Sets conversion limits for ImageMagick preprocessing. |\n| `[companion_downloads]` | `metadata_feed_url` | Changes where Sambee resolves Companion download metadata. |\n| `[companion_downloads.pin]` | `version`, `published_at`, `notes`, asset URLs | Pins Companion download links to a specific published release instead of following the promoted feed. |\n\n## Backend Logging Levels\n\nThe `[app]` logging keys accept `DEBUG`, `INFO`, `WARNING`, or `ERROR`, regardless of case.\n\n```toml\n[app]\nlog_level = \"INFO\"\naccess_log_level = \"WARNING\"\nprotocol_log_level = \"WARNING\"\n```\n\n`log_level` defaults to `INFO`. `access_log_level` and `protocol_log_level` default to `WARNING`, which keeps routine successful HTTP requests and verbose WebSocket frames or pings out of normal logs. Raise either setting only for focused diagnosis. Uvicorn startup, shutdown, and error messages continue to use `log_level`.\n\n## Keys That Deserve Extra Care\n\nThese areas have the highest operational impact:\n\n- `[auth].disable_enforcement`: Bypasses all Sambee authentication enforcement. Use it only with a trusted reverse proxy or network perimeter that already enforces access control. It does not change the mode selected in Authentication settings and requires a restart after removal. The retired `auth_method` key is rejected at startup.\n- Backend logging keys: Can significantly increase log volume, particularly `protocol_log_level = \"DEBUG\"`.\n- Frontend logging and tracing keys: Can change both local debugging visibility and backend trace collection volume.\n- `directory_cache.location`: Changes where the saved SMB directory index lives on disk.\n- Companion download keys: Change what download links Sambee presents to users.\n", "1.0": "+++\ntitle = \"Configuration File Reference\"\n+++\n\nThis page is a compact map of the optional `config.toml` file.\n\nUse `config.example.toml` as the source of truth for supported keys. This page explains the sections that matter most in day-to-day administration.\n\n## How to Use This Reference\n\n- Copy only the keys you actually need into the local `config.toml`.\n- Keep the file local to the deployment and mount it read-only in production.\n- Treat commented defaults in `config.example.toml` as the baseline behavior unless you override them intentionally.\n- Expect most basic deployments to use only a small subset of these keys.\n\n## High-Value Sections and Keys\n\n| Section | Key | Operational effect |\n|---|---|---|\n| `[app]` | `log_level` | Sets application diagnostic verbosity and Uvicorn lifecycle logging. |\n| `[app]` | `access_log_level` | Sets Uvicorn HTTP request access-log verbosity. |\n| `[app]` | `protocol_log_level` | Sets Uvicorn WebSocket connection, frame, and keepalive log verbosity. |\n| `[auth]` | `disable_enforcement` | Temporarily bypasses all Sambee authentication enforcement at runtime. |\n| `[security]` | `access_token_expire_minutes` | Changes the short-lived API-token lifetime. OIDC sessions refresh this token in the background; configure the OIDC interactive sign-in interval separately in Authentication settings. |\n| `[admin]` | `username` | Sets the initial administrator username. |\n| `[image_viewer]` | `conv_size_thresh` | Controls when large images are always converted for viewing. |\n| `[frontend_logging]` | `logging_enabled`, `log_level` | Controls browser-console logging behavior. |\n| `[frontend_logging]` | `tracing_enabled`, `tracing_level`, `tracing_retention_hours` | Controls backend trace collection for frontend logging. |\n| `[frontend_logging]` | `tracing_components`, `tracing_username_regex` | Restricts tracing by component or user scope. |\n| `[directory_cache]` | `location`, `coalesce_interval_seconds`, `max_staleness_minutes` | Controls the saved directory index Sambee keeps to make browsing and search recover faster after restarts. |\n| `[preprocessors.imagemagick]` | `max_file_size_bytes`, `timeout_seconds` | Sets conversion limits for ImageMagick preprocessing. |\n| `[companion_downloads]` | `metadata_feed_url` | Changes where Sambee resolves Companion download metadata. |\n| `[companion_downloads.pin]` | `version`, `published_at`, `notes`, asset URLs | Pins Companion download links to a specific published release instead of following the promoted feed. |\n\n## Backend Logging Levels\n\nThe `[app]` logging keys accept `DEBUG`, `INFO`, `WARNING`, or `ERROR`, regardless of case.\n\n```toml\n[app]\nlog_level = \"INFO\"\naccess_log_level = \"WARNING\"\nprotocol_log_level = \"WARNING\"\n```\n\n`log_level` defaults to `INFO`. `access_log_level` and `protocol_log_level` default to `WARNING`, which keeps routine successful HTTP requests and verbose WebSocket frames or pings out of normal logs. Raise either setting only for focused diagnosis. Uvicorn startup, shutdown, and error messages continue to use `log_level`.\n\n## Keys That Deserve Extra Care\n\nThese areas have the highest operational impact:\n\n- `[auth].disable_enforcement`: Bypasses all Sambee authentication enforcement. Use it only with a trusted reverse proxy or network perimeter that already enforces access control. It does not change the mode selected in Authentication settings and requires a restart after removal. The retired `auth_method` key is rejected at startup.\n- Backend logging keys: Can significantly increase log volume, particularly `protocol_log_level = \"DEBUG\"`.\n- Frontend logging and tracing keys: Can change both local debugging visibility and backend trace collection volume.\n- `directory_cache.location`: Changes where the saved SMB directory index lives on disk.\n- Companion download keys: Change what download links Sambee presents to users.\n", "2.0": "+++\ntitle = \"Configuration File Reference\"\n+++\n\nThis page is a compact map of the optional `config.toml` file.\n\nUse `config.example.toml` as the source of truth for supported keys. This page explains the sections that matter most in day-to-day administration.\n\n## How to Use This Reference\n\n- Copy only the keys you actually need into the local `config.toml`.\n- Keep the file local to the deployment and mount it read-only in production.\n- Treat commented defaults in `config.example.toml` as the baseline behavior unless you override them intentionally.\n- Expect most basic deployments to use only a small subset of these keys.\n\n## High-Value Sections and Keys\n\n| Section | Key | Operational effect |\n|---|---|---|\n| `[app]` | `log_level` | Sets application diagnostic verbosity and Uvicorn lifecycle logging. |\n| `[app]` | `access_log_level` | Sets Uvicorn HTTP request access-log verbosity. |\n| `[app]` | `protocol_log_level` | Sets Uvicorn WebSocket connection, frame, and keepalive log verbosity. |\n| `[auth]` | `disable_enforcement` | Temporarily bypasses all Sambee authentication enforcement at runtime. |\n| `[security]` | `access_token_expire_minutes` | Changes the short-lived API-token lifetime. OIDC sessions refresh this token in the background; configure the OIDC interactive sign-in interval separately in Authentication settings. |\n| `[admin]` | `username` | Sets the initial administrator username. |\n| `[image_viewer]` | `conv_size_thresh` | Controls when large images are always converted for viewing. |\n| `[frontend_logging]` | `logging_enabled`, `log_level` | Controls browser-console logging behavior. |\n| `[frontend_logging]` | `tracing_enabled`, `tracing_level`, `tracing_retention_hours` | Controls backend trace collection for frontend logging. |\n| `[frontend_logging]` | `tracing_components`, `tracing_username_regex` | Restricts tracing by component or user scope. |\n| `[directory_cache]` | `location`, `coalesce_interval_seconds`, `max_staleness_minutes` | Controls the saved directory index Sambee keeps to make browsing and search recover faster after restarts. |\n| `[preprocessors.imagemagick]` | `max_file_size_bytes`, `timeout_seconds` | Sets conversion limits for ImageMagick preprocessing. |\n| `[companion_downloads]` | `metadata_feed_url` | Changes where Sambee resolves Companion download metadata. |\n| `[companion_downloads.pin]` | `version`, `published_at`, `notes`, asset URLs | Pins Companion download links to a specific published release instead of following the promoted feed. |\n\n## Backend Logging Levels\n\nThe `[app]` logging keys accept `DEBUG`, `INFO`, `WARNING`, or `ERROR`, regardless of case.\n\n```toml\n[app]\nlog_level = \"INFO\"\naccess_log_level = \"WARNING\"\nprotocol_log_level = \"WARNING\"\n```\n\n`log_level` defaults to `INFO`. `access_log_level` and `protocol_log_level` default to `WARNING`, which keeps routine successful HTTP requests and verbose WebSocket frames or pings out of normal logs. Raise either setting only for focused diagnosis. Uvicorn startup, shutdown, and error messages continue to use `log_level`.\n\n## Keys That Deserve Extra Care\n\nThese areas have the highest operational impact:\n\n- `[auth].disable_enforcement`: Bypasses all Sambee authentication enforcement. Use it only with a trusted reverse proxy or network perimeter that already enforces access control. It does not change the mode selected in Authentication settings and requires a restart after removal. The retired `auth_method` key is rejected at startup.\n- Backend logging keys: Can significantly increase log volume, particularly `protocol_log_level = \"DEBUG\"`.\n- Frontend logging and tracing keys: Can change both local debugging visibility and backend trace collection volume.\n- `directory_cache.location`: Changes where the saved SMB directory index lives on disk.\n- Companion download keys: Change what download links Sambee presents to users.\n"}, "page_contents": {"0.9": "+++\ntitle = \"Configuration File Reference\"\n+++\n\nThis page is a compact map of the optional `config.toml` file.\n\nUse `config.example.toml` as the source of truth for supported keys. This page explains the sections that matter most in day-to-day administration.\n\n## How to Use This Reference\n\n- Copy only the keys you actually need into the local `config.toml`.\n- Keep the file local to the deployment and mount it read-only in production.\n- Treat commented defaults in `config.example.toml` as the baseline behavior unless you override them intentionally.\n- Expect most basic deployments to use only a small subset of these keys.\n\n## High-Value Sections and Keys\n\n| Section | Key | Operational effect |\n|---|---|---|\n| `[app]` | `log_level` | Sets application diagnostic verbosity and Uvicorn lifecycle logging. |\n| `[app]` | `access_log_level` | Sets Uvicorn HTTP request access-log verbosity. |\n| `[app]` | `protocol_log_level` | Sets Uvicorn WebSocket connection, frame, and keepalive log verbosity. |\n| `[auth]` | `disable_enforcement` | Temporarily bypasses all Sambee authentication enforcement at runtime. |\n| `[security]` | `access_token_expire_minutes` | Changes the short-lived API-token lifetime. OIDC sessions refresh this token in the background; configure the OIDC interactive sign-in interval separately in Authentication settings. |\n| `[admin]` | `username` | Sets the initial administrator username. |\n| `[image_viewer]` | `conv_size_thresh` | Controls when large images are always converted for viewing. |\n| `[frontend_logging]` | `logging_enabled`, `log_level` | Controls browser-console logging behavior. |\n| `[frontend_logging]` | `tracing_enabled`, `tracing_level`, `tracing_retention_hours` | Controls backend trace collection for frontend logging. |\n| `[frontend_logging]` | `tracing_components`, `tracing_username_regex` | Restricts tracing by component or user scope. |\n| `[directory_cache]` | `location`, `coalesce_interval_seconds`, `max_staleness_minutes` | Controls the saved directory index Sambee keeps to make browsing and search recover faster after restarts. |\n| `[preprocessors.imagemagick]` | `max_file_size_bytes`, `timeout_seconds` | Sets conversion limits for ImageMagick preprocessing. |\n| `[companion_downloads]` | `metadata_feed_url` | Changes where Sambee resolves Companion download metadata. |\n| `[companion_downloads.pin]` | `version`, `published_at`, `notes`, asset URLs | Pins Companion download links to a specific published release instead of following the promoted feed. |\n\n## Backend Logging Levels\n\nThe `[app]` logging keys accept `DEBUG`, `INFO`, `WARNING`, or `ERROR`, regardless of case.\n\n```toml\n[app]\nlog_level = \"INFO\"\naccess_log_level = \"WARNING\"\nprotocol_log_level = \"WARNING\"\n```\n\n`log_level` defaults to `INFO`. `access_log_level` and `protocol_log_level` default to `WARNING`, which keeps routine successful HTTP requests and verbose WebSocket frames or pings out of normal logs. Raise either setting only for focused diagnosis. Uvicorn startup, shutdown, and error messages continue to use `log_level`.\n\n## Keys That Deserve Extra Care\n\nThese areas have the highest operational impact:\n\n- `[auth].disable_enforcement`: Bypasses all Sambee authentication enforcement. Use it only with a trusted reverse proxy or network perimeter that already enforces access control. It does not change the mode selected in Authentication settings and requires a restart after removal. The retired `auth_method` key is rejected at startup.\n- Backend logging keys: Can significantly increase log volume, particularly `protocol_log_level = \"DEBUG\"`.\n- Frontend logging and tracing keys: Can change both local debugging visibility and backend trace collection volume.\n- `directory_cache.location`: Changes where the saved SMB directory index lives on disk.\n- Companion download keys: Change what download links Sambee presents to users.\n", "1.0": "+++\ntitle = \"Configuration File Reference\"\n+++\n\nThis page is a compact map of the optional `config.toml` file.\n\nUse `config.example.toml` as the source of truth for supported keys. This page explains the sections that matter most in day-to-day administration.\n\n## How to Use This Reference\n\n- Copy only the keys you actually need into the local `config.toml`.\n- Keep the file local to the deployment and mount it read-only in production.\n- Treat commented defaults in `config.example.toml` as the baseline behavior unless you override them intentionally.\n- Expect most basic deployments to use only a small subset of these keys.\n\n## High-Value Sections and Keys\n\n| Section | Key | Operational effect |\n|---|---|---|\n| `[app]` | `log_level` | Sets application diagnostic verbosity and Uvicorn lifecycle logging. |\n| `[app]` | `access_log_level` | Sets Uvicorn HTTP request access-log verbosity. |\n| `[app]` | `protocol_log_level` | Sets Uvicorn WebSocket connection, frame, and keepalive log verbosity. |\n| `[auth]` | `disable_enforcement` | Temporarily bypasses all Sambee authentication enforcement at runtime. |\n| `[security]` | `access_token_expire_minutes` | Changes the short-lived API-token lifetime. OIDC sessions refresh this token in the background; configure the OIDC interactive sign-in interval separately in Authentication settings. |\n| `[admin]` | `username` | Sets the initial administrator username. |\n| `[image_viewer]` | `conv_size_thresh` | Controls when large images are always converted for viewing. |\n| `[frontend_logging]` | `logging_enabled`, `log_level` | Controls browser-console logging behavior. |\n| `[frontend_logging]` | `tracing_enabled`, `tracing_level`, `tracing_retention_hours` | Controls backend trace collection for frontend logging. |\n| `[frontend_logging]` | `tracing_components`, `tracing_username_regex` | Restricts tracing by component or user scope. |\n| `[directory_cache]` | `location`, `coalesce_interval_seconds`, `max_staleness_minutes` | Controls the saved directory index Sambee keeps to make browsing and search recover faster after restarts. |\n| `[preprocessors.imagemagick]` | `max_file_size_bytes`, `timeout_seconds` | Sets conversion limits for ImageMagick preprocessing. |\n| `[companion_downloads]` | `metadata_feed_url` | Changes where Sambee resolves Companion download metadata. |\n| `[companion_downloads.pin]` | `version`, `published_at`, `notes`, asset URLs | Pins Companion download links to a specific published release instead of following the promoted feed. |\n\n## Backend Logging Levels\n\nThe `[app]` logging keys accept `DEBUG`, `INFO`, `WARNING`, or `ERROR`, regardless of case.\n\n```toml\n[app]\nlog_level = \"INFO\"\naccess_log_level = \"WARNING\"\nprotocol_log_level = \"WARNING\"\n```\n\n`log_level` defaults to `INFO`. `access_log_level` and `protocol_log_level` default to `WARNING`, which keeps routine successful HTTP requests and verbose WebSocket frames or pings out of normal logs. Raise either setting only for focused diagnosis. Uvicorn startup, shutdown, and error messages continue to use `log_level`.\n\n## Keys That Deserve Extra Care\n\nThese areas have the highest operational impact:\n\n- `[auth].disable_enforcement`: Bypasses all Sambee authentication enforcement. Use it only with a trusted reverse proxy or network perimeter that already enforces access control. It does not change the mode selected in Authentication settings and requires a restart after removal. The retired `auth_method` key is rejected at startup.\n- Backend logging keys: Can significantly increase log volume, particularly `protocol_log_level = \"DEBUG\"`.\n- Frontend logging and tracing keys: Can change both local debugging visibility and backend trace collection volume.\n- `directory_cache.location`: Changes where the saved SMB directory index lives on disk.\n- Companion download keys: Change what download links Sambee presents to users.\n", "2.0": "+++\ntitle = \"Configuration File Reference\"\n+++\n\nThis page is a compact map of the optional `config.toml` file.\n\nUse `config.example.toml` as the source of truth for supported keys. This page explains the sections that matter most in day-to-day administration.\n\n## How to Use This Reference\n\n- Copy only the keys you actually need into the local `config.toml`.\n- Keep the file local to the deployment and mount it read-only in production.\n- Treat commented defaults in `config.example.toml` as the baseline behavior unless you override them intentionally.\n- Expect most basic deployments to use only a small subset of these keys.\n\n## High-Value Sections and Keys\n\n| Section | Key | Operational effect |\n|---|---|---|\n| `[app]` | `log_level` | Sets application diagnostic verbosity and Uvicorn lifecycle logging. |\n| `[app]` | `access_log_level` | Sets Uvicorn HTTP request access-log verbosity. |\n| `[app]` | `protocol_log_level` | Sets Uvicorn WebSocket connection, frame, and keepalive log verbosity. |\n| `[auth]` | `disable_enforcement` | Temporarily bypasses all Sambee authentication enforcement at runtime. |\n| `[security]` | `access_token_expire_minutes` | Changes the short-lived API-token lifetime. OIDC sessions refresh this token in the background; configure the OIDC interactive sign-in interval separately in Authentication settings. |\n| `[admin]` | `username` | Sets the initial administrator username. |\n| `[image_viewer]` | `conv_size_thresh` | Controls when large images are always converted for viewing. |\n| `[frontend_logging]` | `logging_enabled`, `log_level` | Controls browser-console logging behavior. |\n| `[frontend_logging]` | `tracing_enabled`, `tracing_level`, `tracing_retention_hours` | Controls backend trace collection for frontend logging. |\n| `[frontend_logging]` | `tracing_components`, `tracing_username_regex` | Restricts tracing by component or user scope. |\n| `[directory_cache]` | `location`, `coalesce_interval_seconds`, `max_staleness_minutes` | Controls the saved directory index Sambee keeps to make browsing and search recover faster after restarts. |\n| `[preprocessors.imagemagick]` | `max_file_size_bytes`, `timeout_seconds` | Sets conversion limits for ImageMagick preprocessing. |\n| `[companion_downloads]` | `metadata_feed_url` | Changes where Sambee resolves Companion download metadata. |\n| `[companion_downloads.pin]` | `version`, `published_at`, `notes`, asset URLs | Pins Companion download links to a specific published release instead of following the promoted feed. |\n\n## Backend Logging Levels\n\nThe `[app]` logging keys accept `DEBUG`, `INFO`, `WARNING`, or `ERROR`, regardless of case.\n\n```toml\n[app]\nlog_level = \"INFO\"\naccess_log_level = \"WARNING\"\nprotocol_log_level = \"WARNING\"\n```\n\n`log_level` defaults to `INFO`. `access_log_level` and `protocol_log_level` default to `WARNING`, which keeps routine successful HTTP requests and verbose WebSocket frames or pings out of normal logs. Raise either setting only for focused diagnosis. Uvicorn startup, shutdown, and error messages continue to use `log_level`.\n\n## Keys That Deserve Extra Care\n\nThese areas have the highest operational impact:\n\n- `[auth].disable_enforcement`: Bypasses all Sambee authentication enforcement. Use it only with a trusted reverse proxy or network perimeter that already enforces access control. It does not change the mode selected in Authentication settings and requires a restart after removal. The retired `auth_method` key is rejected at startup.\n- Backend logging keys: Can significantly increase log volume, particularly `protocol_log_level = \"DEBUG\"`.\n- Frontend logging and tracing keys: Can change both local debugging visibility and backend trace collection volume.\n- `directory_cache.location`: Changes where the saved SMB directory index lives on disk.\n- Companion download keys: Change what download links Sambee presents to users.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:admin-guide/reference/smb-settings", "parent_id": "section:admin-guide/reference", "depth": 2, "kind": "page", "label": "smb-settings", "title": "Smb Settings", "path": "admin-guide/reference/smb-settings", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "authored"}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "inherited", "source_version": "0.9"}}, "content_versions": {"0.9": "+++\ntitle = \"SMB Settings\"\n+++\n\nAdministrators configure Sambee's runtime SMB behavior in **Settings** \u003e **Administration** \u003e **SMB**. These controls apply to every configured SMB connection.\n\n## Protection\n\n### Authentication Mode\n\n- **Automatic (Kerberos or NTLM)** uses Kerberos when available and otherwise falls back to NTLM. This is the practical option for compatible domain and NAS environments.\n- **Kerberos required** blocks NTLM fallback. Choose it when every SMB server is correctly configured for Kerberos authentication.\n\n### Transport Protection\n\nSMB signing is always required by Sambee. It verifies that SMB messages have not been altered in transit.\n\n- **Signing only (SMB 2 compatible)** is the default. It permits signed, unencrypted SMB 2 connections for trusted home and small-organization networks. File contents, names, and metadata are visible to network observers in this mode.\n- **Signing and encryption (SMB 3+)** requires encrypted SMB traffic. Choose it for shared or untrusted networks that need confidentiality. This blocks SMB 2-only servers because SMB encryption requires SMB 3 or later.\n\n## Connection Behavior\n\nSet the SMB connection timeout to limit how long Sambee waits to establish a transport connection.\n\n## File Streaming\n\nSet the SMB read chunk size to control how much file data Sambee reads per streaming operation. The setting is stored as an administrator setting and is not available in `config.toml`.\n\n", "1.0": "+++\ntitle = \"SMB Settings\"\n+++\n\nAdministrators configure Sambee's runtime SMB behavior in **Settings** \u003e **Administration** \u003e **SMB**. These controls apply to every configured SMB connection.\n\n## Protection\n\n### Authentication Mode\n\n- **Automatic (Kerberos or NTLM)** uses Kerberos when available and otherwise falls back to NTLM. This is the practical option for compatible domain and NAS environments.\n- **Kerberos required** blocks NTLM fallback. Choose it when every SMB server is correctly configured for Kerberos authentication.\n\n### Transport Protection\n\nSMB signing is always required by Sambee. It verifies that SMB messages have not been altered in transit.\n\n- **Signing only (SMB 2 compatible)** is the default. It permits signed, unencrypted SMB 2 connections for trusted home and small-organization networks. File contents, names, and metadata are visible to network observers in this mode.\n- **Signing and encryption (SMB 3+)** requires encrypted SMB traffic. Choose it for shared or untrusted networks that need confidentiality. This blocks SMB 2-only servers because SMB encryption requires SMB 3 or later.\n\n## Connection Behavior\n\nSet the SMB connection timeout to limit how long Sambee waits to establish a transport connection.\n\n## File Streaming\n\nSet the SMB read chunk size to control how much file data Sambee reads per streaming operation. The setting is stored as an administrator setting and is not available in `config.toml`.\n\n", "2.0": "+++\ntitle = \"SMB Settings\"\n+++\n\nAdministrators configure Sambee's runtime SMB behavior in **Settings** \u003e **Administration** \u003e **SMB**. These controls apply to every configured SMB connection.\n\n## Protection\n\n### Authentication Mode\n\n- **Automatic (Kerberos or NTLM)** uses Kerberos when available and otherwise falls back to NTLM. This is the practical option for compatible domain and NAS environments.\n- **Kerberos required** blocks NTLM fallback. Choose it when every SMB server is correctly configured for Kerberos authentication.\n\n### Transport Protection\n\nSMB signing is always required by Sambee. It verifies that SMB messages have not been altered in transit.\n\n- **Signing only (SMB 2 compatible)** is the default. It permits signed, unencrypted SMB 2 connections for trusted home and small-organization networks. File contents, names, and metadata are visible to network observers in this mode.\n- **Signing and encryption (SMB 3+)** requires encrypted SMB traffic. Choose it for shared or untrusted networks that need confidentiality. This blocks SMB 2-only servers because SMB encryption requires SMB 3 or later.\n\n## Connection Behavior\n\nSet the SMB connection timeout to limit how long Sambee waits to establish a transport connection.\n\n## File Streaming\n\nSet the SMB read chunk size to control how much file data Sambee reads per streaming operation. The setting is stored as an administrator setting and is not available in `config.toml`.\n\n"}, "page_contents": {"0.9": "+++\ntitle = \"SMB Settings\"\n+++\n\nAdministrators configure Sambee's runtime SMB behavior in **Settings** \u003e **Administration** \u003e **SMB**. These controls apply to every configured SMB connection.\n\n## Protection\n\n### Authentication Mode\n\n- **Automatic (Kerberos or NTLM)** uses Kerberos when available and otherwise falls back to NTLM. This is the practical option for compatible domain and NAS environments.\n- **Kerberos required** blocks NTLM fallback. Choose it when every SMB server is correctly configured for Kerberos authentication.\n\n### Transport Protection\n\nSMB signing is always required by Sambee. It verifies that SMB messages have not been altered in transit.\n\n- **Signing only (SMB 2 compatible)** is the default. It permits signed, unencrypted SMB 2 connections for trusted home and small-organization networks. File contents, names, and metadata are visible to network observers in this mode.\n- **Signing and encryption (SMB 3+)** requires encrypted SMB traffic. Choose it for shared or untrusted networks that need confidentiality. This blocks SMB 2-only servers because SMB encryption requires SMB 3 or later.\n\n## Connection Behavior\n\nSet the SMB connection timeout to limit how long Sambee waits to establish a transport connection.\n\n## File Streaming\n\nSet the SMB read chunk size to control how much file data Sambee reads per streaming operation. The setting is stored as an administrator setting and is not available in `config.toml`.\n\n", "1.0": "+++\ntitle = \"SMB Settings\"\n+++\n\nAdministrators configure Sambee's runtime SMB behavior in **Settings** \u003e **Administration** \u003e **SMB**. These controls apply to every configured SMB connection.\n\n## Protection\n\n### Authentication Mode\n\n- **Automatic (Kerberos or NTLM)** uses Kerberos when available and otherwise falls back to NTLM. This is the practical option for compatible domain and NAS environments.\n- **Kerberos required** blocks NTLM fallback. Choose it when every SMB server is correctly configured for Kerberos authentication.\n\n### Transport Protection\n\nSMB signing is always required by Sambee. It verifies that SMB messages have not been altered in transit.\n\n- **Signing only (SMB 2 compatible)** is the default. It permits signed, unencrypted SMB 2 connections for trusted home and small-organization networks. File contents, names, and metadata are visible to network observers in this mode.\n- **Signing and encryption (SMB 3+)** requires encrypted SMB traffic. Choose it for shared or untrusted networks that need confidentiality. This blocks SMB 2-only servers because SMB encryption requires SMB 3 or later.\n\n## Connection Behavior\n\nSet the SMB connection timeout to limit how long Sambee waits to establish a transport connection.\n\n## File Streaming\n\nSet the SMB read chunk size to control how much file data Sambee reads per streaming operation. The setting is stored as an administrator setting and is not available in `config.toml`.\n\n", "2.0": "+++\ntitle = \"SMB Settings\"\n+++\n\nAdministrators configure Sambee's runtime SMB behavior in **Settings** \u003e **Administration** \u003e **SMB**. These controls apply to every configured SMB connection.\n\n## Protection\n\n### Authentication Mode\n\n- **Automatic (Kerberos or NTLM)** uses Kerberos when available and otherwise falls back to NTLM. This is the practical option for compatible domain and NAS environments.\n- **Kerberos required** blocks NTLM fallback. Choose it when every SMB server is correctly configured for Kerberos authentication.\n\n### Transport Protection\n\nSMB signing is always required by Sambee. It verifies that SMB messages have not been altered in transit.\n\n- **Signing only (SMB 2 compatible)** is the default. It permits signed, unencrypted SMB 2 connections for trusted home and small-organization networks. File contents, names, and metadata are visible to network observers in this mode.\n- **Signing and encryption (SMB 3+)** requires encrypted SMB traffic. Choose it for shared or untrusted networks that need confidentiality. This blocks SMB 2-only servers because SMB encryption requires SMB 3 or later.\n\n## Connection Behavior\n\nSet the SMB connection timeout to limit how long Sambee waits to establish a transport connection.\n\n## File Streaming\n\nSet the SMB read chunk size to control how much file data Sambee reads per streaming operation. The setting is stored as an administrator setting and is not available in `config.toml`.\n\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:admin-guide/authentication", "parent_id": "book:admin-guide", "depth": 1, "kind": "section", "label": "authentication", "title": "Authentication", "path": "admin-guide/authentication", "has_children": true, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:admin-guide/authentication/authentication-overview", "parent_id": "section:admin-guide/authentication", "depth": 2, "kind": "page", "label": "authentication-overview", "title": "Authentication Overview", "path": "admin-guide/authentication/authentication-overview", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "authored"}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "inherited", "source_version": "0.9"}}, "content_versions": {"0.9": "+++\ntitle = \"Authentication Overview\"\n+++\n\nSambee supports multiple authentication modes: OpenID Connect (OIDC), local passwords, and no authentication (perimeter-trust mode).\n\nTo configure Sambee authenticaion, open **Settings** \u003e **Administration** \u003e **Authentication**.\n\n## Choose an Authentication Mode\n\n| Mode | Login behavior | User management |\n|---|---|---|\n| No authentication | Sambee does not authenticate users. Use this only when a trusted reverse proxy or network perimeter controls all access to Sambee. | Creating users and managing local passwords are unavailable. |\n| Password only (default) | Shows the local username and password form. | Administrators can create users and set or reset local passwords. |\n| OIDC or password | Shows the OIDC login and local username/password fields on the same page. | Administrators can create local-password users. OIDC also provisions passwordless users after an admitted sign-in. |\n| OIDC only | Starts the OIDC login transparently. | Sambee provisions passwordless users after their first admitted OIDC sign-in. Manual user creation and local-password management are unavailable. |\n\nUse **OIDC or password** while introducing OIDC. Switch to **OIDC only** only after an administrator has completed the interactive test and verified the recovery procedure. Select **Password only** when local credentials should be the only sign-in method.\n\nFor local-password setup and recovery, see [Password Authentication](../password-authentication/). For provider setup, see [OpenID Connect Authentication Setup](../openid-connect-authentication-setup/).\n\n## Authentication Configuration\n\nSambee stores the selected authentication mode in its database. New installations default to **Password only** until an administrator selects another mode in **Settings** \u003e **Administration** \u003e **Authentication**.\n\nThe [configuration file](../../reference/configuration-file-reference) has one authentication-related runtime override: it bypasses authentication enforcement without changing the mode saved in the UI. This override is useful mainly during development.\n\n## No Authentication\n\n**No authentication** is a perimeter-trust mode. Sambee does not validate a user identity, consume reverse-proxy identity headers, or enforce a proxy-specific authorization policy. It assumes that every request reaching Sambee was already authorized by infrastructure you operate.\n\nBefore activation, the UI requires an explicit acknowledgement and revokes all active Sambee sessions. Do not enable this mode on a directly reachable service or behind a proxy that does not enforce authentication and access control.\n\nSambee keeps existing user records and local password hashes when you select this mode, but does not use them for authentication. User Management does not offer manual user creation or local-password resets until you select a password-capable mode.\n\n", "1.0": "+++\ntitle = \"Authentication Overview\"\n+++\n\nSambee supports multiple authentication modes: OpenID Connect (OIDC), local passwords, and no authentication (perimeter-trust mode).\n\nTo configure Sambee authenticaion, open **Settings** \u003e **Administration** \u003e **Authentication**.\n\n## Choose an Authentication Mode\n\n| Mode | Login behavior | User management |\n|---|---|---|\n| No authentication | Sambee does not authenticate users. Use this only when a trusted reverse proxy or network perimeter controls all access to Sambee. | Creating users and managing local passwords are unavailable. |\n| Password only (default) | Shows the local username and password form. | Administrators can create users and set or reset local passwords. |\n| OIDC or password | Shows the OIDC login and local username/password fields on the same page. | Administrators can create local-password users. OIDC also provisions passwordless users after an admitted sign-in. |\n| OIDC only | Starts the OIDC login transparently. | Sambee provisions passwordless users after their first admitted OIDC sign-in. Manual user creation and local-password management are unavailable. |\n\nUse **OIDC or password** while introducing OIDC. Switch to **OIDC only** only after an administrator has completed the interactive test and verified the recovery procedure. Select **Password only** when local credentials should be the only sign-in method.\n\nFor local-password setup and recovery, see [Password Authentication](../password-authentication/). For provider setup, see [OpenID Connect Authentication Setup](../openid-connect-authentication-setup/).\n\n## Authentication Configuration\n\nSambee stores the selected authentication mode in its database. New installations default to **Password only** until an administrator selects another mode in **Settings** \u003e **Administration** \u003e **Authentication**.\n\nThe [configuration file](../../reference/configuration-file-reference) has one authentication-related runtime override: it bypasses authentication enforcement without changing the mode saved in the UI. This override is useful mainly during development.\n\n## No Authentication\n\n**No authentication** is a perimeter-trust mode. Sambee does not validate a user identity, consume reverse-proxy identity headers, or enforce a proxy-specific authorization policy. It assumes that every request reaching Sambee was already authorized by infrastructure you operate.\n\nBefore activation, the UI requires an explicit acknowledgement and revokes all active Sambee sessions. Do not enable this mode on a directly reachable service or behind a proxy that does not enforce authentication and access control.\n\nSambee keeps existing user records and local password hashes when you select this mode, but does not use them for authentication. User Management does not offer manual user creation or local-password resets until you select a password-capable mode.\n\n", "2.0": "+++\ntitle = \"Authentication Overview\"\n+++\n\nSambee supports multiple authentication modes: OpenID Connect (OIDC), local passwords, and no authentication (perimeter-trust mode).\n\nTo configure Sambee authenticaion, open **Settings** \u003e **Administration** \u003e **Authentication**.\n\n## Choose an Authentication Mode\n\n| Mode | Login behavior | User management |\n|---|---|---|\n| No authentication | Sambee does not authenticate users. Use this only when a trusted reverse proxy or network perimeter controls all access to Sambee. | Creating users and managing local passwords are unavailable. |\n| Password only (default) | Shows the local username and password form. | Administrators can create users and set or reset local passwords. |\n| OIDC or password | Shows the OIDC login and local username/password fields on the same page. | Administrators can create local-password users. OIDC also provisions passwordless users after an admitted sign-in. |\n| OIDC only | Starts the OIDC login transparently. | Sambee provisions passwordless users after their first admitted OIDC sign-in. Manual user creation and local-password management are unavailable. |\n\nUse **OIDC or password** while introducing OIDC. Switch to **OIDC only** only after an administrator has completed the interactive test and verified the recovery procedure. Select **Password only** when local credentials should be the only sign-in method.\n\nFor local-password setup and recovery, see [Password Authentication](../password-authentication/). For provider setup, see [OpenID Connect Authentication Setup](../openid-connect-authentication-setup/).\n\n## Authentication Configuration\n\nSambee stores the selected authentication mode in its database. New installations default to **Password only** until an administrator selects another mode in **Settings** \u003e **Administration** \u003e **Authentication**.\n\nThe [configuration file](../../reference/configuration-file-reference) has one authentication-related runtime override: it bypasses authentication enforcement without changing the mode saved in the UI. This override is useful mainly during development.\n\n## No Authentication\n\n**No authentication** is a perimeter-trust mode. Sambee does not validate a user identity, consume reverse-proxy identity headers, or enforce a proxy-specific authorization policy. It assumes that every request reaching Sambee was already authorized by infrastructure you operate.\n\nBefore activation, the UI requires an explicit acknowledgement and revokes all active Sambee sessions. Do not enable this mode on a directly reachable service or behind a proxy that does not enforce authentication and access control.\n\nSambee keeps existing user records and local password hashes when you select this mode, but does not use them for authentication. User Management does not offer manual user creation or local-password resets until you select a password-capable mode.\n\n"}, "page_contents": {"0.9": "+++\ntitle = \"Authentication Overview\"\n+++\n\nSambee supports multiple authentication modes: OpenID Connect (OIDC), local passwords, and no authentication (perimeter-trust mode).\n\nTo configure Sambee authenticaion, open **Settings** \u003e **Administration** \u003e **Authentication**.\n\n## Choose an Authentication Mode\n\n| Mode | Login behavior | User management |\n|---|---|---|\n| No authentication | Sambee does not authenticate users. Use this only when a trusted reverse proxy or network perimeter controls all access to Sambee. | Creating users and managing local passwords are unavailable. |\n| Password only (default) | Shows the local username and password form. | Administrators can create users and set or reset local passwords. |\n| OIDC or password | Shows the OIDC login and local username/password fields on the same page. | Administrators can create local-password users. OIDC also provisions passwordless users after an admitted sign-in. |\n| OIDC only | Starts the OIDC login transparently. | Sambee provisions passwordless users after their first admitted OIDC sign-in. Manual user creation and local-password management are unavailable. |\n\nUse **OIDC or password** while introducing OIDC. Switch to **OIDC only** only after an administrator has completed the interactive test and verified the recovery procedure. Select **Password only** when local credentials should be the only sign-in method.\n\nFor local-password setup and recovery, see [Password Authentication](../password-authentication/). For provider setup, see [OpenID Connect Authentication Setup](../openid-connect-authentication-setup/).\n\n## Authentication Configuration\n\nSambee stores the selected authentication mode in its database. New installations default to **Password only** until an administrator selects another mode in **Settings** \u003e **Administration** \u003e **Authentication**.\n\nThe [configuration file](../../reference/configuration-file-reference) has one authentication-related runtime override: it bypasses authentication enforcement without changing the mode saved in the UI. This override is useful mainly during development.\n\n## No Authentication\n\n**No authentication** is a perimeter-trust mode. Sambee does not validate a user identity, consume reverse-proxy identity headers, or enforce a proxy-specific authorization policy. It assumes that every request reaching Sambee was already authorized by infrastructure you operate.\n\nBefore activation, the UI requires an explicit acknowledgement and revokes all active Sambee sessions. Do not enable this mode on a directly reachable service or behind a proxy that does not enforce authentication and access control.\n\nSambee keeps existing user records and local password hashes when you select this mode, but does not use them for authentication. User Management does not offer manual user creation or local-password resets until you select a password-capable mode.\n\n", "1.0": "+++\ntitle = \"Authentication Overview\"\n+++\n\nSambee supports multiple authentication modes: OpenID Connect (OIDC), local passwords, and no authentication (perimeter-trust mode).\n\nTo configure Sambee authenticaion, open **Settings** \u003e **Administration** \u003e **Authentication**.\n\n## Choose an Authentication Mode\n\n| Mode | Login behavior | User management |\n|---|---|---|\n| No authentication | Sambee does not authenticate users. Use this only when a trusted reverse proxy or network perimeter controls all access to Sambee. | Creating users and managing local passwords are unavailable. |\n| Password only (default) | Shows the local username and password form. | Administrators can create users and set or reset local passwords. |\n| OIDC or password | Shows the OIDC login and local username/password fields on the same page. | Administrators can create local-password users. OIDC also provisions passwordless users after an admitted sign-in. |\n| OIDC only | Starts the OIDC login transparently. | Sambee provisions passwordless users after their first admitted OIDC sign-in. Manual user creation and local-password management are unavailable. |\n\nUse **OIDC or password** while introducing OIDC. Switch to **OIDC only** only after an administrator has completed the interactive test and verified the recovery procedure. Select **Password only** when local credentials should be the only sign-in method.\n\nFor local-password setup and recovery, see [Password Authentication](../password-authentication/). For provider setup, see [OpenID Connect Authentication Setup](../openid-connect-authentication-setup/).\n\n## Authentication Configuration\n\nSambee stores the selected authentication mode in its database. New installations default to **Password only** until an administrator selects another mode in **Settings** \u003e **Administration** \u003e **Authentication**.\n\nThe [configuration file](../../reference/configuration-file-reference) has one authentication-related runtime override: it bypasses authentication enforcement without changing the mode saved in the UI. This override is useful mainly during development.\n\n## No Authentication\n\n**No authentication** is a perimeter-trust mode. Sambee does not validate a user identity, consume reverse-proxy identity headers, or enforce a proxy-specific authorization policy. It assumes that every request reaching Sambee was already authorized by infrastructure you operate.\n\nBefore activation, the UI requires an explicit acknowledgement and revokes all active Sambee sessions. Do not enable this mode on a directly reachable service or behind a proxy that does not enforce authentication and access control.\n\nSambee keeps existing user records and local password hashes when you select this mode, but does not use them for authentication. User Management does not offer manual user creation or local-password resets until you select a password-capable mode.\n\n", "2.0": "+++\ntitle = \"Authentication Overview\"\n+++\n\nSambee supports multiple authentication modes: OpenID Connect (OIDC), local passwords, and no authentication (perimeter-trust mode).\n\nTo configure Sambee authenticaion, open **Settings** \u003e **Administration** \u003e **Authentication**.\n\n## Choose an Authentication Mode\n\n| Mode | Login behavior | User management |\n|---|---|---|\n| No authentication | Sambee does not authenticate users. Use this only when a trusted reverse proxy or network perimeter controls all access to Sambee. | Creating users and managing local passwords are unavailable. |\n| Password only (default) | Shows the local username and password form. | Administrators can create users and set or reset local passwords. |\n| OIDC or password | Shows the OIDC login and local username/password fields on the same page. | Administrators can create local-password users. OIDC also provisions passwordless users after an admitted sign-in. |\n| OIDC only | Starts the OIDC login transparently. | Sambee provisions passwordless users after their first admitted OIDC sign-in. Manual user creation and local-password management are unavailable. |\n\nUse **OIDC or password** while introducing OIDC. Switch to **OIDC only** only after an administrator has completed the interactive test and verified the recovery procedure. Select **Password only** when local credentials should be the only sign-in method.\n\nFor local-password setup and recovery, see [Password Authentication](../password-authentication/). For provider setup, see [OpenID Connect Authentication Setup](../openid-connect-authentication-setup/).\n\n## Authentication Configuration\n\nSambee stores the selected authentication mode in its database. New installations default to **Password only** until an administrator selects another mode in **Settings** \u003e **Administration** \u003e **Authentication**.\n\nThe [configuration file](../../reference/configuration-file-reference) has one authentication-related runtime override: it bypasses authentication enforcement without changing the mode saved in the UI. This override is useful mainly during development.\n\n## No Authentication\n\n**No authentication** is a perimeter-trust mode. Sambee does not validate a user identity, consume reverse-proxy identity headers, or enforce a proxy-specific authorization policy. It assumes that every request reaching Sambee was already authorized by infrastructure you operate.\n\nBefore activation, the UI requires an explicit acknowledgement and revokes all active Sambee sessions. Do not enable this mode on a directly reachable service or behind a proxy that does not enforce authentication and access control.\n\nSambee keeps existing user records and local password hashes when you select this mode, but does not use them for authentication. User Management does not offer manual user creation or local-password resets until you select a password-capable mode.\n\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:admin-guide/authentication/password-authentication", "parent_id": "section:admin-guide/authentication", "depth": 2, "kind": "page", "label": "password-authentication", "title": "Password Authentication", "path": "admin-guide/authentication/password-authentication", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "authored"}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "inherited", "source_version": "0.9"}}, "content_versions": {"0.9": "+++\ntitle = \"Password Authentication\"\n+++\n\nPassword authentication uses Sambee's local username and password form. Select **Password only** in **Settings** \u003e **Administration** \u003e **Authentication** when local credentials should be the only sign-in method.\n\nSee [Authentication Overview](../authentication-overview/) to compare all authentication modes.\n\nAdministrators can create users and set or reset local passwords in **Password only** and **OIDC or password** modes. Sambee retains existing password hashes when local-password sign-in is disabled, but User Management cannot create or reset local passwords until a password-capable mode is active again.\n\n## Switch to Password-Only Access\n\nThe web activation requires at least one active, unexpired administrator with a local password. Before confirmation, Sambee shows how many active, unexpired accounts have no local password and requires explicit acknowledgement that they will lose sign-in access.\n\nSambee revokes all current sessions only when the configuration and displayed account count are still current. If either changes, Authentication settings reloads the current impact and requires confirmation again.\n\n## Recover From an OIDC Failure\n\nIf OIDC prevents web access, run the backend CLI from the application environment:\n\n```bash\ncd backend\npython -m app.oidc_admin set-mode password-only\n```\n\nFor Docker Compose, run the same module inside the backend container. The command displays the number of active local-password administrators and active passwordless accounts that will lose access. Review those counts, then type `password-only` exactly to confirm. Sambee rechecks the configuration and both counts before applying the change; if they changed, rerun the command and review the new impact.\n\nThe command refuses to proceed if no active local-password administrator exists. For deliberate containment of a compromised identity provider, `set-mode password-only --force` permits the switch after an explicit warning and confirmation. This leaves no usable administrator and is not a credential-reset or login-bypass mechanism. `--force` is rejected when a usable local administrator exists.\n\n", "1.0": "+++\ntitle = \"Password Authentication\"\n+++\n\nPassword authentication uses Sambee's local username and password form. Select **Password only** in **Settings** \u003e **Administration** \u003e **Authentication** when local credentials should be the only sign-in method.\n\nSee [Authentication Overview](../authentication-overview/) to compare all authentication modes.\n\nAdministrators can create users and set or reset local passwords in **Password only** and **OIDC or password** modes. Sambee retains existing password hashes when local-password sign-in is disabled, but User Management cannot create or reset local passwords until a password-capable mode is active again.\n\n## Switch to Password-Only Access\n\nThe web activation requires at least one active, unexpired administrator with a local password. Before confirmation, Sambee shows how many active, unexpired accounts have no local password and requires explicit acknowledgement that they will lose sign-in access.\n\nSambee revokes all current sessions only when the configuration and displayed account count are still current. If either changes, Authentication settings reloads the current impact and requires confirmation again.\n\n## Recover From an OIDC Failure\n\nIf OIDC prevents web access, run the backend CLI from the application environment:\n\n```bash\ncd backend\npython -m app.oidc_admin set-mode password-only\n```\n\nFor Docker Compose, run the same module inside the backend container. The command displays the number of active local-password administrators and active passwordless accounts that will lose access. Review those counts, then type `password-only` exactly to confirm. Sambee rechecks the configuration and both counts before applying the change; if they changed, rerun the command and review the new impact.\n\nThe command refuses to proceed if no active local-password administrator exists. For deliberate containment of a compromised identity provider, `set-mode password-only --force` permits the switch after an explicit warning and confirmation. This leaves no usable administrator and is not a credential-reset or login-bypass mechanism. `--force` is rejected when a usable local administrator exists.\n\n", "2.0": "+++\ntitle = \"Password Authentication\"\n+++\n\nPassword authentication uses Sambee's local username and password form. Select **Password only** in **Settings** \u003e **Administration** \u003e **Authentication** when local credentials should be the only sign-in method.\n\nSee [Authentication Overview](../authentication-overview/) to compare all authentication modes.\n\nAdministrators can create users and set or reset local passwords in **Password only** and **OIDC or password** modes. Sambee retains existing password hashes when local-password sign-in is disabled, but User Management cannot create or reset local passwords until a password-capable mode is active again.\n\n## Switch to Password-Only Access\n\nThe web activation requires at least one active, unexpired administrator with a local password. Before confirmation, Sambee shows how many active, unexpired accounts have no local password and requires explicit acknowledgement that they will lose sign-in access.\n\nSambee revokes all current sessions only when the configuration and displayed account count are still current. If either changes, Authentication settings reloads the current impact and requires confirmation again.\n\n## Recover From an OIDC Failure\n\nIf OIDC prevents web access, run the backend CLI from the application environment:\n\n```bash\ncd backend\npython -m app.oidc_admin set-mode password-only\n```\n\nFor Docker Compose, run the same module inside the backend container. The command displays the number of active local-password administrators and active passwordless accounts that will lose access. Review those counts, then type `password-only` exactly to confirm. Sambee rechecks the configuration and both counts before applying the change; if they changed, rerun the command and review the new impact.\n\nThe command refuses to proceed if no active local-password administrator exists. For deliberate containment of a compromised identity provider, `set-mode password-only --force` permits the switch after an explicit warning and confirmation. This leaves no usable administrator and is not a credential-reset or login-bypass mechanism. `--force` is rejected when a usable local administrator exists.\n\n"}, "page_contents": {"0.9": "+++\ntitle = \"Password Authentication\"\n+++\n\nPassword authentication uses Sambee's local username and password form. Select **Password only** in **Settings** \u003e **Administration** \u003e **Authentication** when local credentials should be the only sign-in method.\n\nSee [Authentication Overview](../authentication-overview/) to compare all authentication modes.\n\nAdministrators can create users and set or reset local passwords in **Password only** and **OIDC or password** modes. Sambee retains existing password hashes when local-password sign-in is disabled, but User Management cannot create or reset local passwords until a password-capable mode is active again.\n\n## Switch to Password-Only Access\n\nThe web activation requires at least one active, unexpired administrator with a local password. Before confirmation, Sambee shows how many active, unexpired accounts have no local password and requires explicit acknowledgement that they will lose sign-in access.\n\nSambee revokes all current sessions only when the configuration and displayed account count are still current. If either changes, Authentication settings reloads the current impact and requires confirmation again.\n\n## Recover From an OIDC Failure\n\nIf OIDC prevents web access, run the backend CLI from the application environment:\n\n```bash\ncd backend\npython -m app.oidc_admin set-mode password-only\n```\n\nFor Docker Compose, run the same module inside the backend container. The command displays the number of active local-password administrators and active passwordless accounts that will lose access. Review those counts, then type `password-only` exactly to confirm. Sambee rechecks the configuration and both counts before applying the change; if they changed, rerun the command and review the new impact.\n\nThe command refuses to proceed if no active local-password administrator exists. For deliberate containment of a compromised identity provider, `set-mode password-only --force` permits the switch after an explicit warning and confirmation. This leaves no usable administrator and is not a credential-reset or login-bypass mechanism. `--force` is rejected when a usable local administrator exists.\n\n", "1.0": "+++\ntitle = \"Password Authentication\"\n+++\n\nPassword authentication uses Sambee's local username and password form. Select **Password only** in **Settings** \u003e **Administration** \u003e **Authentication** when local credentials should be the only sign-in method.\n\nSee [Authentication Overview](../authentication-overview/) to compare all authentication modes.\n\nAdministrators can create users and set or reset local passwords in **Password only** and **OIDC or password** modes. Sambee retains existing password hashes when local-password sign-in is disabled, but User Management cannot create or reset local passwords until a password-capable mode is active again.\n\n## Switch to Password-Only Access\n\nThe web activation requires at least one active, unexpired administrator with a local password. Before confirmation, Sambee shows how many active, unexpired accounts have no local password and requires explicit acknowledgement that they will lose sign-in access.\n\nSambee revokes all current sessions only when the configuration and displayed account count are still current. If either changes, Authentication settings reloads the current impact and requires confirmation again.\n\n## Recover From an OIDC Failure\n\nIf OIDC prevents web access, run the backend CLI from the application environment:\n\n```bash\ncd backend\npython -m app.oidc_admin set-mode password-only\n```\n\nFor Docker Compose, run the same module inside the backend container. The command displays the number of active local-password administrators and active passwordless accounts that will lose access. Review those counts, then type `password-only` exactly to confirm. Sambee rechecks the configuration and both counts before applying the change; if they changed, rerun the command and review the new impact.\n\nThe command refuses to proceed if no active local-password administrator exists. For deliberate containment of a compromised identity provider, `set-mode password-only --force` permits the switch after an explicit warning and confirmation. This leaves no usable administrator and is not a credential-reset or login-bypass mechanism. `--force` is rejected when a usable local administrator exists.\n\n", "2.0": "+++\ntitle = \"Password Authentication\"\n+++\n\nPassword authentication uses Sambee's local username and password form. Select **Password only** in **Settings** \u003e **Administration** \u003e **Authentication** when local credentials should be the only sign-in method.\n\nSee [Authentication Overview](../authentication-overview/) to compare all authentication modes.\n\nAdministrators can create users and set or reset local passwords in **Password only** and **OIDC or password** modes. Sambee retains existing password hashes when local-password sign-in is disabled, but User Management cannot create or reset local passwords until a password-capable mode is active again.\n\n## Switch to Password-Only Access\n\nThe web activation requires at least one active, unexpired administrator with a local password. Before confirmation, Sambee shows how many active, unexpired accounts have no local password and requires explicit acknowledgement that they will lose sign-in access.\n\nSambee revokes all current sessions only when the configuration and displayed account count are still current. If either changes, Authentication settings reloads the current impact and requires confirmation again.\n\n## Recover From an OIDC Failure\n\nIf OIDC prevents web access, run the backend CLI from the application environment:\n\n```bash\ncd backend\npython -m app.oidc_admin set-mode password-only\n```\n\nFor Docker Compose, run the same module inside the backend container. The command displays the number of active local-password administrators and active passwordless accounts that will lose access. Review those counts, then type `password-only` exactly to confirm. Sambee rechecks the configuration and both counts before applying the change; if they changed, rerun the command and review the new impact.\n\nThe command refuses to proceed if no active local-password administrator exists. For deliberate containment of a compromised identity provider, `set-mode password-only --force` permits the switch after an explicit warning and confirmation. This leaves no usable administrator and is not a credential-reset or login-bypass mechanism. `--force` is rejected when a usable local administrator exists.\n\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:admin-guide/authentication/openid-connect-authentication-setup", "parent_id": "section:admin-guide/authentication", "depth": 2, "kind": "page", "label": "openid-connect-authentication-setup", "title": "Openid Connect Authentication Setup", "path": "admin-guide/authentication/openid-connect-authentication-setup", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "authored"}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "branched", "source_version": "0.9", "diff_added": 23, "diff_removed": 7}}, "content_versions": {"0.9": "+++\ntitle = \"OpenID Connect Authentication Setup\"\n+++\n\nOpenID Connect (OIDC) is Sambee's preferred authentication method.\n\n## Preparation\n\n### Copy OIDC Callback URI\n\nOpen **Settings** \u003e **Administration** \u003e **Authentication** and select an OIDC authentication mode. Select **Configure OIDC** and copy the OIDC callback URI from the dialog that opens. You need the URI in the next step. It has the following format:\n\n```text\nhttps://files.example.com/api/auth/oidc/callback\n```\n\n## Configure the OpenID Connect Identity Provider (IdP)\n\n### Provider Properties\n\nIn your identity provider, create a new OpenID Connect IdP with the following properties:\n\n- Confidential web client\n- Authorization code flow\n- PKCE with `S256`\n- `client_secret_basic` token endpoint authentication\n- `RS256`-signed ID tokens\n- Sambee's callback URI (see above)\n- The scopes `openid`, `profile`, `email`, and `offline_access`\n   - Add `groups` only when using group admission or group-based role mappings\n- Authorization-code and refresh-token grants\n\nConfigure token lifetimes:\n\n- Refresh token:\n   - A shorter lifetime requires users to sign in again sooner.\n   - A longer lifetime increases the impact period if the token is compromised.\n   - Maximum useful length: slightly longer than Sambee's interactive sign-in interval (default: 30 days).\n- Access token and ID token:\n   - Lifetimes should be short, e.g., 1 hour.\n\n### Verify the Username Claim\n\nSambee needs to match OIDC provider usernames to its own usernames. Many OIDC providers return a username in the field `preferred_username` when the `profile` scope is enabled. To ensure that username claim is suitable, verify the following with your OIDC provider:\n\n- How to enable returning the username claim (typically through the `profile` scope).\n- The field name of the username claim (typically `preferred_username`).\n- The username claim is present for every person who can sign in, stable for that person, and unique across all provider users.\n\n### Authelia Example\n\nThe relevant Authelia client entry can look like this:\n\n```yaml\nidentity_providers:\n  oidc:\n    lifespans:\n      custom:\n        sambee:\n          # Maximum useful length: Sambee's interactive sign-in interval + 1 day\n          refresh_token: '31d'\n    clients:\n      - client_id: sambee\n        client_name: Sambee\n        client_secret: '$pbkdf2-sha512$replace-with-a-hashed-random-secret'\n        redirect_uris:\n          - https://files.example.com/api/auth/oidc/callback\n        grant_types:\n          - authorization_code\n          - refresh_token\n        response_types:\n          - code\n        lifespan: sambee\n        scopes:\n          - openid\n          - profile\n          - email\n          - offline_access\n          # Add groups when using group admission or group-based role mappings.\n          - groups\n```\n\nNotes:\n\n- See Authelia's instructions for generating a [hashed client secret](https://www.authelia.com/integration/openid-connect/frequently-asked-questions/#how-do-i-generate-a-client-identifier-or-client-secret).\n- Use your own values for the following fields: `redirect_uris`.\n- The `profile` scope makes Authelia's `preferred_username` claim available from the username used to sign in, which is exactly what Sambee expects in its default OIDC settings (see below).\n- See the [Authelia documentation](https://www.authelia.com/configuration/identity-providers/openid-connect/clients/) more details and default values.\n\n## Configure Sambee\n\nOpen **Settings** \u003e **Administration** \u003e **Authentication**.\n\n### 1. Choose the Sign-In Mode\n\nSelect one of these values in **Authentication mode**:\n\n- **OIDC or password**\n- **OIDC only**\n\nThe **Access** panel shows whether OIDC is configured and healthy. Select **Configure OIDC** to enter or change the provider settings.\n\n### 2. Enter Provider Details\n\nIn the setup dialog, complete these fields in the **Provider** section:\n\n| Sambee field | Value to enter |\n|---|---|\n| **Provider name** | A recognizable name for the provider, such as `Authelia` or `Microsoft Entra ID`. |\n| **Issuer URL** | The provider's HTTPS issuer URL. For Authelia, this is normally the externally reachable URL of the Authelia portal, such as `https://auth.example.com`. \u003cbr /\u003eOpen `https://auth.example.com/.well-known/openid-configuration` and enter the exact value of its `issuer` field. |\n| **Client ID** | The client ID configured in the OIDC IdP. |\n| **Client secret** | The matching client secret as plain text (unhashed).\u003cbr /\u003eOn later changes, leave this blank to retain the stored secret. \u003cbr /\u003eThe visibility button only reveals the value currently typed in the browser; Sambee never returns the stored secret. |\n| **Scopes** | A comma-separated list. Include `openid`, `offline_access`, and every scope required to return the claims configured below, such as `profile` and `email`. Add `groups` when using group admission or group-based role mappings. |\n\n### 3. Configure Session Policy\n\nSet **Interactive sign-in interval (days)** to control how long a verified IdP sign-in can be renewed in the background. The default is 30 days.\n\nDuring this interval, Sambee refreshes its short-lived API token in the background. At the interval deadline, Sambee requires a fresh interactive IdP sign-in.\n\n### 4. Configure Access\n\nComplete these fields in the **Access** section:\n\n| Sambee field | Value to enter |\n|---|---|\n| **Admission** | **All authenticated users** is the default. Select **Only selected groups** to require membership in named groups before Sambee evaluates the person's role. |\n| **Admission groups** | When **Admission** is **Only selected groups**, enter the exact identity-provider groups that may sign in, separated by commas. |\n\n### 5. Configure Role Assignment\n\nChoose how Sambee assigns roles after an identity passes the admission policy:\n\n| Role assignment | Behavior |\n|---|---|\n| **All users are assigned to the same role** | Select **Administrator**, **Editor** (default), or **Viewer**. Every admitted user receives that role unless they have an individual assignment. This is the simplest choice for smaller environments. |\n| **Group-based** | Enter exact identity-provider groups for **Administrator**, **Editor**, and **Viewer**. A person without an individual assignment must match a configured group; otherwise Sambee denies access. |\n\nIn group-based mode, a group can appear in only one role mapping. When a person matches multiple mappings, Sambee grants the highest role: Administrator, then Editor, then Viewer.\n\nDuring activation (see below), Sambee gives the administrator completing the test an individual **Administrator** assignment. Individual assignments for linked or pending accounts always take precedence over the configured role assignment.\n\n### 6. Advanced Claims\n\nThe default claim names work with most OpenID Connect providers. Expand **Advanced claims** only when the provider returns different claim names.\n\n#### Claims\n\n| Sambee field | Value to enter |\n|---|---|\n| **Username claim** | The stable, unique claim used to identify a person, commonly `preferred_username`. |\n| **Name claim** | Optional claim containing the person's display name, commonly `name`. |\n| **Email claim** | Optional claim containing the person's email address, commonly `email`. |\n| **Groups claim** | Optional claim containing group membership, commonly `groups`. Required only for selected-group admission or group-based role assignment. |\n\nSambee records the OIDC issuer and subject for each linked account. By default, Sambee also treats the configured IdP as authoritative for usernames: when an admitted IdP user has the same username as a local account, Sambee links that identity to the local account. This also updates an existing link when an IdP migration changes the issuer or subject. Keep **Automatically link OIDC identities to local accounts by username** enabled unless you need to resolve username matches manually.\n\n### 7. Connect and Test\n\nSelect **Connect and test** in the setup dialog. Sambee redirects you to the provider and returns to the dialog for review. This verifies that:\n\n- Signing in via the specified OIDC configuration succeeds.\n- Sambee can read and evaluate the resulting OIDC user identity.\n- The tested identity passes the selected admission rule, so the current administrator can keep administrator access after activation.\n\nReview the resulting identity before activation:\n\n- **Username**, **Email**, and **Groups** show the claims Sambee received.\n- **Admission** and **Matching admission group** show whether the tested identity passes the admission rule.\n\nOIDC activation remains unavailable unless the tested OIDC identity passes the admission rule to prevent the local admin making the changes from locking themselves out.\n\n### 8. Review and Activate\n\nSelect **Activate configuration** when the review is complete. The administrator who started the setup is linked to the tested provider identity automatically.\n\nWhen OIDC is active, users sign in normally after an IdP migration or subject reset. With automatic username linking enabled, Sambee updates their stored OIDC link during their next admitted sign-in and signs out existing Sambee sessions for that account. Until then, their existing OIDC link and IdP-managed full name and email remain read-only in User Management.\n\nAfter activation, see [OpenID Connect Authentication Operations](../openid-connect-authentication-operations/) for session, account-mapping, auditing, and request-limit administration.\n", "1.0": "+++\ntitle = \"OpenID Connect Authentication Setup\"\n+++\n\nOpenID Connect (OIDC) is Sambee's preferred authentication method.\n\n## Preparation\n\n### Copy OIDC Callback URI\n\nOpen **Settings** \u003e **Administration** \u003e **Authentication** and select an OIDC authentication mode. Select **Configure OIDC** and copy the OIDC callback URI from the dialog that opens. You need the URI in the next step. It has the following format:\n\n```text\nhttps://files.example.com/api/auth/oidc/callback\n```\n\n## Configure the OpenID Connect Identity Provider (IdP)\n\n### Provider Properties\n\nIn your identity provider, create a new OpenID Connect IdP with the following properties:\n\n- Confidential web client\n- Authorization code flow\n- PKCE with `S256`\n- `client_secret_basic` token endpoint authentication\n- `RS256`-signed ID tokens\n- Sambee's callback URI (see above)\n- The scopes `openid`, `profile`, `email`, and `offline_access`\n   - Add `groups` only when using group admission or group-based role mappings\n- Authorization-code and refresh-token grants\n\nConfigure token lifetimes:\n\n- Refresh token:\n   - A shorter lifetime requires users to sign in again sooner.\n   - A longer lifetime increases the impact period if the token is compromised.\n   - Maximum useful length: slightly longer than Sambee's interactive sign-in interval (default: 30 days).\n- Access token and ID token:\n   - Lifetimes should be short, e.g., 1 hour.\n\n### Verify the Username Claim\n\nSambee needs to match OIDC provider usernames to its own usernames. Many OIDC providers return a username in the field `preferred_username` when the `profile` scope is enabled. To ensure that username claim is suitable, verify the following with your OIDC provider:\n\n- How to enable returning the username claim (typically through the `profile` scope).\n- The field name of the username claim (typically `preferred_username`).\n- The username claim is present for every person who can sign in, stable for that person, and unique across all provider users.\n\n### Authelia Example\n\nThe relevant Authelia client entry can look like this:\n\n```yaml\nidentity_providers:\n  oidc:\n    lifespans:\n      custom:\n        sambee:\n          # Maximum useful length: Sambee's interactive sign-in interval + 1 day\n          refresh_token: '31d'\n    clients:\n      - client_id: sambee\n        client_name: Sambee\n        client_secret: '$pbkdf2-sha512$replace-with-a-hashed-random-secret'\n        redirect_uris:\n          - https://files.example.com/api/auth/oidc/callback\n        grant_types:\n          - authorization_code\n          - refresh_token\n        response_types:\n          - code\n        lifespan: sambee\n        scopes:\n          - openid\n          - profile\n          - email\n          - offline_access\n          # Add groups when using group admission or group-based role mappings.\n          - groups\n```\n\nNotes:\n\n- See Authelia's instructions for generating a [hashed client secret](https://www.authelia.com/integration/openid-connect/frequently-asked-questions/#how-do-i-generate-a-client-identifier-or-client-secret).\n- Use your own values for the following fields: `redirect_uris`.\n- The `profile` scope makes Authelia's `preferred_username` claim available from the username used to sign in, which is exactly what Sambee expects in its default OIDC settings (see below).\n- See the [Authelia documentation](https://www.authelia.com/configuration/identity-providers/openid-connect/clients/) more details and default values.\n\n## Configure Sambee\n\nOpen **Settings** \u003e **Administration** \u003e **Authentication**.\n\n### 1. Choose the Sign-In Mode\n\nSelect one of these values in **Authentication mode**:\n\n- **OIDC or password**\n- **OIDC only**\n\nThe **Access** panel shows whether OIDC is configured and healthy. Select **Configure OIDC** to enter or change the provider settings.\n\n### 2. Enter Provider Details\n\nIn the setup dialog, complete these fields in the **Provider** section:\n\n| Sambee field | Value to enter |\n|---|---|\n| **Provider name** | A recognizable name for the provider, such as `Authelia` or `Microsoft Entra ID`. |\n| **Issuer URL** | The provider's HTTPS issuer URL. For Authelia, this is normally the externally reachable URL of the Authelia portal, such as `https://auth.example.com`. \u003cbr /\u003eOpen `https://auth.example.com/.well-known/openid-configuration` and enter the exact value of its `issuer` field. |\n| **Client ID** | The client ID configured in the OIDC IdP. |\n| **Client secret** | The matching client secret as plain text (unhashed).\u003cbr /\u003eOn later changes, leave this blank to retain the stored secret. \u003cbr /\u003eThe visibility button only reveals the value currently typed in the browser; Sambee never returns the stored secret. |\n| **Scopes** | A comma-separated list. Include `openid`, `offline_access`, and every scope required to return the claims configured below, such as `profile` and `email`. Add `groups` when using group admission or group-based role mappings. |\n\n### 3. Configure Session Policy\n\nSet **Interactive sign-in interval (days)** to control how long a verified IdP sign-in can be renewed in the background. The default is 30 days.\n\nDuring this interval, Sambee refreshes its short-lived API token in the background. At the interval deadline, Sambee requires a fresh interactive IdP sign-in.\n\n### 4. Configure Access\n\nComplete these fields in the **Access** section:\n\n| Sambee field | Value to enter |\n|---|---|\n| **Admission** | **All authenticated users** is the default. Select **Only selected groups** to require membership in named groups before Sambee evaluates the person's role. |\n| **Admission groups** | When **Admission** is **Only selected groups**, enter the exact identity-provider groups that may sign in, separated by commas. |\n\n### 5. Configure Role Assignment\n\nChoose how Sambee assigns roles after an identity passes the admission policy:\n\n| Role assignment | Behavior |\n|---|---|\n| **All users are assigned to the same role** | Select **Administrator**, **Editor** (default), or **Viewer**. Every admitted user receives that role unless they have an individual assignment. This is the simplest choice for smaller environments. |\n| **Group-based** | Enter exact identity-provider groups for **Administrator**, **Editor**, and **Viewer**. A person without an individual assignment must match a configured group; otherwise Sambee denies access. |\n\nIn group-based mode, a group can appear in only one role mapping. When a person matches multiple mappings, Sambee grants the highest role: Administrator, then Editor, then Viewer.\n\nDuring activation (see below), Sambee gives the administrator completing the test an individual **Administrator** assignment. Individual assignments for linked or pending accounts always take precedence over the configured role assignment.\n\n### 6. Advanced Claims\n\nThe default claim names work with most OpenID Connect providers. Expand **Advanced claims** only when the provider returns different claim names.\n\n#### Claims\n\n| Sambee field | Value to enter |\n|---|---|\n| **Username claim** | The stable, unique claim used to identify a person, commonly `preferred_username`. |\n| **Name claim** | Optional claim containing the person's display name, commonly `name`. |\n| **Email claim** | Optional claim containing the person's email address, commonly `email`. |\n| **Groups claim** | Optional claim containing group membership, commonly `groups`. Required only for selected-group admission or group-based role assignment. |\n\nSambee records the OIDC issuer and subject for each linked account. By default, Sambee also treats the configured IdP as authoritative for usernames: when an admitted IdP user has the same username as a local account, Sambee links that identity to the local account. This also updates an existing link when an IdP migration changes the issuer or subject. Keep **Automatically link OIDC identities to local accounts by username** enabled unless you need to resolve username matches manually.\n\n### 7. Connect and Test\n\nSelect **Connect and test** in the setup dialog. Sambee redirects you to the provider and returns to the dialog for review. This verifies that:\n\n- Signing in via the specified OIDC configuration succeeds.\n- Sambee can read and evaluate the resulting OIDC user identity.\n- The tested identity passes the selected admission rule, so the current administrator can keep administrator access after activation.\n\nReview the resulting identity before activation:\n\n- **Username**, **Email**, and **Groups** show the claims Sambee received.\n- **Admission** and **Matching admission group** show whether the tested identity passes the admission rule.\n\nOIDC activation remains unavailable unless the tested OIDC identity passes the admission rule to prevent the local admin making the changes from locking themselves out.\n\n### 8. Review and Activate\n\nSelect **Activate configuration** when the review is complete. The administrator who started the setup is linked to the tested provider identity automatically.\n\nWhen OIDC is active, users sign in normally after an IdP migration or subject reset. With automatic username linking enabled, Sambee updates their stored OIDC link during their next admitted sign-in and signs out existing Sambee sessions for that account. Until then, their existing OIDC link and IdP-managed full name and email remain read-only in User Management.\n\nAfter activation, see [OpenID Connect Authentication Operations](../openid-connect-authentication-operations/) for session, account-mapping, auditing, and request-limit administration.\n", "2.0": "+++\ntitle = \"OpenID Connect Authentication Setup\"\n+++\n\nOpenID Connect (OIDC) is Sambee's preferred authentication method.\n\n## Preparation\n\n### Copy OIDC Callback URI\n\nOpen **Settings** \u003e **Administration** \u003e **Authentication** and select an OIDC authentication mode. Select **Configure OIDC** and copy the OIDC callback URI from the dialog that opens. You need the URI in the next step. It has the following format:\n\n```text\nhttps://files.example.com/api/auth/oidc/callback\n```\n\n## Configure the OpenID Connect Identity Provider (IdP)\n\n### Provider Properties\n\nIn your identity provider, create a new OpenID Connect IdP with the following properties:\n\n- Confidential web client\n- Authorization code flow\n- PKCE with `S256`\n- `client_secret_basic` token endpoint authentication\n- `RS256`-signed ID tokens\n- Sambee's callback URI (see above)\n- Scopes:\n   - `openid`: required\n   - `profile`: often necessary for the provider to return `preferred_username`, which Sambee requires\n   - `email`: optional\n   - `groups`: required when using group admission or group-based role mappings\n   - `offline_access`: may be required for refresh tokens, depending on the provider\n- Authorization code grant\n- Refresh token grant: optional\n\n#### Token Lifetimes\n\nConfigure token lifetimes:\n\n- Refresh token, if the provider issues one:\n   - A shorter lifetime requires users to sign in again sooner.\n   - A longer lifetime increases the impact period if the token is compromised.\n   - Maximum useful length: slightly longer than Sambee's interactive sign-in interval (default: 30 days).\n- Access token and ID token:\n   - Lifetimes should be short, e.g., 1 hour.\n\n#### Refresh Tokens\n\nHaving the provider issue refresh tokens is recommended as that enables background session renewal without user interaction.\n\nProviders that don't issue refresh tokens can still be used with Sambee. They must return an ID token with a valid `auth_time` claim when Sambee requests `max_age`.\n\n### Verify the Username Claim\n\nSambee needs to match OIDC provider usernames to its own usernames. Many OIDC providers return a username in the field `preferred_username` when the `profile` scope is enabled. To ensure that username claim is suitable, verify the following with your OIDC provider:\n\n- How to enable returning the username claim (typically through the `profile` scope).\n- The field name of the username claim (typically `preferred_username`).\n- The username claim is present for every person who can sign in, stable for that person, and unique across all provider users.\n\n### Authelia Example\n\nThe relevant Authelia client entry can look like this:\n\n```yaml\nidentity_providers:\n  oidc:\n    lifespans:\n      custom:\n        sambee:\n          # Maximum useful length: Sambee's interactive sign-in interval + 1 day\n          refresh_token: '31d'\n    clients:\n      - client_id: sambee\n        client_name: Sambee\n        client_secret: '$pbkdf2-sha512$replace-with-a-hashed-random-secret'\n        redirect_uris:\n          - https://files.example.com/api/auth/oidc/callback\n        grant_types:\n          - authorization_code\n          - refresh_token\n        response_types:\n          - code\n        lifespan: sambee\n        scopes:\n          - openid\n          - profile\n          - email\n          - offline_access\n          # Add groups when using group admission or group-based role mappings.\n          - groups\n```\n\nNotes:\n\n- See Authelia's instructions for generating a [hashed client secret](https://www.authelia.com/integration/openid-connect/frequently-asked-questions/#how-do-i-generate-a-client-identifier-or-client-secret).\n- Use your own values for the following fields: `redirect_uris`.\n- The `profile` scope makes Authelia's `preferred_username` claim available from the username used to sign in, which is exactly what Sambee expects in its default OIDC settings (see below).\n- See the [Authelia documentation](https://www.authelia.com/configuration/identity-providers/openid-connect/clients/) more details and default values.\n\n## Configure Sambee\n\nOpen **Settings** \u003e **Administration** \u003e **Authentication**.\n\n### 1. Choose the Sign-In Mode\n\nSelect one of these values in **Authentication mode**:\n\n- **OIDC or password**\n- **OIDC only**\n\nThe **Access** panel shows whether OIDC is configured and healthy. Select **Configure OIDC** to enter or change the provider settings.\n\n### 2. Enter Provider Details\n\nIn the setup dialog, complete these fields in the **Provider** section:\n\n| Sambee field | Value to enter |\n|---|---|\n| **Provider name** | A recognizable name for the provider, such as `Authelia` or `Microsoft Entra ID`. |\n| **Issuer URL** | The provider's HTTPS issuer URL. For Authelia, this is normally the externally reachable URL of the Authelia portal, such as `https://auth.example.com`. \u003cbr /\u003eOpen `https://auth.example.com/.well-known/openid-configuration` and enter the exact value of its `issuer` field. |\n| **Client ID** | The client ID configured in the OIDC IdP. |\n| **Client secret** | The matching client secret as plain text (unhashed).\u003cbr /\u003eOn later changes, leave this blank to retain the stored secret. \u003cbr /\u003eThe visibility button only reveals the value currently typed in the browser; Sambee never returns the stored secret. |\n| **Scopes** | A comma-separated list. Include `openid` and every scope required for the configured claims, such as `profile` and `email`. Add `groups` for group admission or group-based role mappings. Add `offline_access` only if supported and needed for provider refresh tokens. |\n\n### 3. Configure Session Policy\n\nSet **Interactive sign-in interval (days)** to control the maximum age of a verified IdP sign-in. The default is 30 days.\n\nSet **Session limit without refresh token (hours)** separately for sign-ins that return no refresh token (default 8 hours; allowed range 1-24 hours).\n\nSambee issues short-lived API tokens (up to 60 minutes) while the browser session remains valid. With a refresh token, Sambee can renew through the IdP until the authentication-age limit. Without one, Sambee can issue another API token from the browser cookie only until the fixed session limit. Reducing that limit shortens existing no-refresh sessions; increasing it does not extend them. When the applicable deadline arrives, Sambee starts a new top-level IdP authorization, which might reuse the IdP's existing SSO session.\n\n### 4. Configure Access\n\nComplete these fields in the **Access** section:\n\n| Sambee field | Value to enter |\n|---|---|\n| **Admission** | **All authenticated users** is the default. Select **Only selected groups** to require membership in named groups before Sambee evaluates the person's role. |\n| **Admission groups** | When **Admission** is **Only selected groups**, enter the exact identity-provider groups that may sign in, separated by commas. |\n\n### 5. Configure Role Assignment\n\nChoose how Sambee assigns roles after an identity passes the admission policy:\n\n| Role assignment | Behavior |\n|---|---|\n| **All users are assigned to the same role** | Select **Administrator**, **Editor** (default), or **Viewer**. Every admitted user receives that role unless they have an individual assignment. This is the simplest choice for smaller environments. |\n| **Group-based** | Enter exact identity-provider groups for **Administrator**, **Editor**, and **Viewer**. A person without an individual assignment must match a configured group; otherwise Sambee denies access. |\n\nIn group-based mode, a group can appear in only one role mapping. When a person matches multiple mappings, Sambee grants the highest role: Administrator, then Editor, then Viewer.\n\nDuring activation (see below), Sambee gives the administrator completing the test an individual **Administrator** assignment. Individual assignments for linked or pending accounts always take precedence over the configured role assignment.\n\n### 6. Advanced Claims\n\nThe default claim names work with most OpenID Connect providers. Expand **Advanced claims** only when the provider returns different claim names.\n\n#### Claims\n\n| Sambee field | Value to enter |\n|---|---|\n| **Username claim** | The stable, unique claim used to identify a person, commonly `preferred_username`. |\n| **Name claim** | Optional claim containing the person's display name, commonly `name`. |\n| **Email claim** | Optional claim containing the person's email address, commonly `email`. |\n| **Groups claim** | Optional claim containing group membership, commonly `groups`. Required only for selected-group admission or group-based role assignment. |\n\nSambee records the OIDC issuer and subject for each linked account. By default, Sambee also treats the configured IdP as authoritative for usernames: when an admitted IdP user has the same username as a local account, Sambee links that identity to the local account. This also updates an existing link when an IdP migration changes the issuer or subject. Keep **Automatically link OIDC identities to local accounts by username** enabled unless you need to resolve username matches manually.\n\n### 7. Connect and Test\n\nSelect **Connect and test** in the setup dialog. Sambee redirects you to the provider and returns to the dialog for review. This verifies that:\n\n- Signing in via the specified OIDC configuration succeeds.\n- Sambee can read and evaluate the resulting OIDC user identity.\n- The tested identity passes the selected admission rule, so the current administrator can keep administrator access after activation.\n\nReview the resulting identity before activation:\n\n- **Username**, **Email**, and **Groups** show the claims Sambee received.\n- **Admission** and **Matching admission group** show whether the tested identity passes the admission rule.\n- **Session renewal** reports whether this particular test returned a refresh token. A test without one can still succeed; users will need to sign in again after the configured no-refresh session limit.\n\nOIDC activation remains unavailable unless the tested OIDC identity passes the admission rule to prevent the local admin making the changes from locking themselves out.\n\n### 8. Review and Activate\n\nSelect **Activate configuration** when the review is complete. The administrator who started the setup is linked to the tested provider identity automatically.\n\nWhen OIDC is active, users sign in normally after an IdP migration or subject reset. With automatic username linking enabled, Sambee updates their stored OIDC link during their next admitted sign-in and signs out existing Sambee sessions for that account. Until then, their existing OIDC link and IdP-managed full name and email remain read-only in User Management.\n\nAfter activation, see [OpenID Connect Authentication Operations](../openid-connect-authentication-operations/) for session, account-mapping, auditing, and request-limit administration.\n"}, "page_contents": {"0.9": "+++\ntitle = \"OpenID Connect Authentication Setup\"\n+++\n\nOpenID Connect (OIDC) is Sambee's preferred authentication method.\n\n## Preparation\n\n### Copy OIDC Callback URI\n\nOpen **Settings** \u003e **Administration** \u003e **Authentication** and select an OIDC authentication mode. Select **Configure OIDC** and copy the OIDC callback URI from the dialog that opens. You need the URI in the next step. It has the following format:\n\n```text\nhttps://files.example.com/api/auth/oidc/callback\n```\n\n## Configure the OpenID Connect Identity Provider (IdP)\n\n### Provider Properties\n\nIn your identity provider, create a new OpenID Connect IdP with the following properties:\n\n- Confidential web client\n- Authorization code flow\n- PKCE with `S256`\n- `client_secret_basic` token endpoint authentication\n- `RS256`-signed ID tokens\n- Sambee's callback URI (see above)\n- The scopes `openid`, `profile`, `email`, and `offline_access`\n   - Add `groups` only when using group admission or group-based role mappings\n- Authorization-code and refresh-token grants\n\nConfigure token lifetimes:\n\n- Refresh token:\n   - A shorter lifetime requires users to sign in again sooner.\n   - A longer lifetime increases the impact period if the token is compromised.\n   - Maximum useful length: slightly longer than Sambee's interactive sign-in interval (default: 30 days).\n- Access token and ID token:\n   - Lifetimes should be short, e.g., 1 hour.\n\n### Verify the Username Claim\n\nSambee needs to match OIDC provider usernames to its own usernames. Many OIDC providers return a username in the field `preferred_username` when the `profile` scope is enabled. To ensure that username claim is suitable, verify the following with your OIDC provider:\n\n- How to enable returning the username claim (typically through the `profile` scope).\n- The field name of the username claim (typically `preferred_username`).\n- The username claim is present for every person who can sign in, stable for that person, and unique across all provider users.\n\n### Authelia Example\n\nThe relevant Authelia client entry can look like this:\n\n```yaml\nidentity_providers:\n  oidc:\n    lifespans:\n      custom:\n        sambee:\n          # Maximum useful length: Sambee's interactive sign-in interval + 1 day\n          refresh_token: '31d'\n    clients:\n      - client_id: sambee\n        client_name: Sambee\n        client_secret: '$pbkdf2-sha512$replace-with-a-hashed-random-secret'\n        redirect_uris:\n          - https://files.example.com/api/auth/oidc/callback\n        grant_types:\n          - authorization_code\n          - refresh_token\n        response_types:\n          - code\n        lifespan: sambee\n        scopes:\n          - openid\n          - profile\n          - email\n          - offline_access\n          # Add groups when using group admission or group-based role mappings.\n          - groups\n```\n\nNotes:\n\n- See Authelia's instructions for generating a [hashed client secret](https://www.authelia.com/integration/openid-connect/frequently-asked-questions/#how-do-i-generate-a-client-identifier-or-client-secret).\n- Use your own values for the following fields: `redirect_uris`.\n- The `profile` scope makes Authelia's `preferred_username` claim available from the username used to sign in, which is exactly what Sambee expects in its default OIDC settings (see below).\n- See the [Authelia documentation](https://www.authelia.com/configuration/identity-providers/openid-connect/clients/) more details and default values.\n\n## Configure Sambee\n\nOpen **Settings** \u003e **Administration** \u003e **Authentication**.\n\n### 1. Choose the Sign-In Mode\n\nSelect one of these values in **Authentication mode**:\n\n- **OIDC or password**\n- **OIDC only**\n\nThe **Access** panel shows whether OIDC is configured and healthy. Select **Configure OIDC** to enter or change the provider settings.\n\n### 2. Enter Provider Details\n\nIn the setup dialog, complete these fields in the **Provider** section:\n\n| Sambee field | Value to enter |\n|---|---|\n| **Provider name** | A recognizable name for the provider, such as `Authelia` or `Microsoft Entra ID`. |\n| **Issuer URL** | The provider's HTTPS issuer URL. For Authelia, this is normally the externally reachable URL of the Authelia portal, such as `https://auth.example.com`. \u003cbr /\u003eOpen `https://auth.example.com/.well-known/openid-configuration` and enter the exact value of its `issuer` field. |\n| **Client ID** | The client ID configured in the OIDC IdP. |\n| **Client secret** | The matching client secret as plain text (unhashed).\u003cbr /\u003eOn later changes, leave this blank to retain the stored secret. \u003cbr /\u003eThe visibility button only reveals the value currently typed in the browser; Sambee never returns the stored secret. |\n| **Scopes** | A comma-separated list. Include `openid`, `offline_access`, and every scope required to return the claims configured below, such as `profile` and `email`. Add `groups` when using group admission or group-based role mappings. |\n\n### 3. Configure Session Policy\n\nSet **Interactive sign-in interval (days)** to control how long a verified IdP sign-in can be renewed in the background. The default is 30 days.\n\nDuring this interval, Sambee refreshes its short-lived API token in the background. At the interval deadline, Sambee requires a fresh interactive IdP sign-in.\n\n### 4. Configure Access\n\nComplete these fields in the **Access** section:\n\n| Sambee field | Value to enter |\n|---|---|\n| **Admission** | **All authenticated users** is the default. Select **Only selected groups** to require membership in named groups before Sambee evaluates the person's role. |\n| **Admission groups** | When **Admission** is **Only selected groups**, enter the exact identity-provider groups that may sign in, separated by commas. |\n\n### 5. Configure Role Assignment\n\nChoose how Sambee assigns roles after an identity passes the admission policy:\n\n| Role assignment | Behavior |\n|---|---|\n| **All users are assigned to the same role** | Select **Administrator**, **Editor** (default), or **Viewer**. Every admitted user receives that role unless they have an individual assignment. This is the simplest choice for smaller environments. |\n| **Group-based** | Enter exact identity-provider groups for **Administrator**, **Editor**, and **Viewer**. A person without an individual assignment must match a configured group; otherwise Sambee denies access. |\n\nIn group-based mode, a group can appear in only one role mapping. When a person matches multiple mappings, Sambee grants the highest role: Administrator, then Editor, then Viewer.\n\nDuring activation (see below), Sambee gives the administrator completing the test an individual **Administrator** assignment. Individual assignments for linked or pending accounts always take precedence over the configured role assignment.\n\n### 6. Advanced Claims\n\nThe default claim names work with most OpenID Connect providers. Expand **Advanced claims** only when the provider returns different claim names.\n\n#### Claims\n\n| Sambee field | Value to enter |\n|---|---|\n| **Username claim** | The stable, unique claim used to identify a person, commonly `preferred_username`. |\n| **Name claim** | Optional claim containing the person's display name, commonly `name`. |\n| **Email claim** | Optional claim containing the person's email address, commonly `email`. |\n| **Groups claim** | Optional claim containing group membership, commonly `groups`. Required only for selected-group admission or group-based role assignment. |\n\nSambee records the OIDC issuer and subject for each linked account. By default, Sambee also treats the configured IdP as authoritative for usernames: when an admitted IdP user has the same username as a local account, Sambee links that identity to the local account. This also updates an existing link when an IdP migration changes the issuer or subject. Keep **Automatically link OIDC identities to local accounts by username** enabled unless you need to resolve username matches manually.\n\n### 7. Connect and Test\n\nSelect **Connect and test** in the setup dialog. Sambee redirects you to the provider and returns to the dialog for review. This verifies that:\n\n- Signing in via the specified OIDC configuration succeeds.\n- Sambee can read and evaluate the resulting OIDC user identity.\n- The tested identity passes the selected admission rule, so the current administrator can keep administrator access after activation.\n\nReview the resulting identity before activation:\n\n- **Username**, **Email**, and **Groups** show the claims Sambee received.\n- **Admission** and **Matching admission group** show whether the tested identity passes the admission rule.\n\nOIDC activation remains unavailable unless the tested OIDC identity passes the admission rule to prevent the local admin making the changes from locking themselves out.\n\n### 8. Review and Activate\n\nSelect **Activate configuration** when the review is complete. The administrator who started the setup is linked to the tested provider identity automatically.\n\nWhen OIDC is active, users sign in normally after an IdP migration or subject reset. With automatic username linking enabled, Sambee updates their stored OIDC link during their next admitted sign-in and signs out existing Sambee sessions for that account. Until then, their existing OIDC link and IdP-managed full name and email remain read-only in User Management.\n\nAfter activation, see [OpenID Connect Authentication Operations](../openid-connect-authentication-operations/) for session, account-mapping, auditing, and request-limit administration.\n", "1.0": "+++\ntitle = \"OpenID Connect Authentication Setup\"\n+++\n\nOpenID Connect (OIDC) is Sambee's preferred authentication method.\n\n## Preparation\n\n### Copy OIDC Callback URI\n\nOpen **Settings** \u003e **Administration** \u003e **Authentication** and select an OIDC authentication mode. Select **Configure OIDC** and copy the OIDC callback URI from the dialog that opens. You need the URI in the next step. It has the following format:\n\n```text\nhttps://files.example.com/api/auth/oidc/callback\n```\n\n## Configure the OpenID Connect Identity Provider (IdP)\n\n### Provider Properties\n\nIn your identity provider, create a new OpenID Connect IdP with the following properties:\n\n- Confidential web client\n- Authorization code flow\n- PKCE with `S256`\n- `client_secret_basic` token endpoint authentication\n- `RS256`-signed ID tokens\n- Sambee's callback URI (see above)\n- The scopes `openid`, `profile`, `email`, and `offline_access`\n   - Add `groups` only when using group admission or group-based role mappings\n- Authorization-code and refresh-token grants\n\nConfigure token lifetimes:\n\n- Refresh token:\n   - A shorter lifetime requires users to sign in again sooner.\n   - A longer lifetime increases the impact period if the token is compromised.\n   - Maximum useful length: slightly longer than Sambee's interactive sign-in interval (default: 30 days).\n- Access token and ID token:\n   - Lifetimes should be short, e.g., 1 hour.\n\n### Verify the Username Claim\n\nSambee needs to match OIDC provider usernames to its own usernames. Many OIDC providers return a username in the field `preferred_username` when the `profile` scope is enabled. To ensure that username claim is suitable, verify the following with your OIDC provider:\n\n- How to enable returning the username claim (typically through the `profile` scope).\n- The field name of the username claim (typically `preferred_username`).\n- The username claim is present for every person who can sign in, stable for that person, and unique across all provider users.\n\n### Authelia Example\n\nThe relevant Authelia client entry can look like this:\n\n```yaml\nidentity_providers:\n  oidc:\n    lifespans:\n      custom:\n        sambee:\n          # Maximum useful length: Sambee's interactive sign-in interval + 1 day\n          refresh_token: '31d'\n    clients:\n      - client_id: sambee\n        client_name: Sambee\n        client_secret: '$pbkdf2-sha512$replace-with-a-hashed-random-secret'\n        redirect_uris:\n          - https://files.example.com/api/auth/oidc/callback\n        grant_types:\n          - authorization_code\n          - refresh_token\n        response_types:\n          - code\n        lifespan: sambee\n        scopes:\n          - openid\n          - profile\n          - email\n          - offline_access\n          # Add groups when using group admission or group-based role mappings.\n          - groups\n```\n\nNotes:\n\n- See Authelia's instructions for generating a [hashed client secret](https://www.authelia.com/integration/openid-connect/frequently-asked-questions/#how-do-i-generate-a-client-identifier-or-client-secret).\n- Use your own values for the following fields: `redirect_uris`.\n- The `profile` scope makes Authelia's `preferred_username` claim available from the username used to sign in, which is exactly what Sambee expects in its default OIDC settings (see below).\n- See the [Authelia documentation](https://www.authelia.com/configuration/identity-providers/openid-connect/clients/) more details and default values.\n\n## Configure Sambee\n\nOpen **Settings** \u003e **Administration** \u003e **Authentication**.\n\n### 1. Choose the Sign-In Mode\n\nSelect one of these values in **Authentication mode**:\n\n- **OIDC or password**\n- **OIDC only**\n\nThe **Access** panel shows whether OIDC is configured and healthy. Select **Configure OIDC** to enter or change the provider settings.\n\n### 2. Enter Provider Details\n\nIn the setup dialog, complete these fields in the **Provider** section:\n\n| Sambee field | Value to enter |\n|---|---|\n| **Provider name** | A recognizable name for the provider, such as `Authelia` or `Microsoft Entra ID`. |\n| **Issuer URL** | The provider's HTTPS issuer URL. For Authelia, this is normally the externally reachable URL of the Authelia portal, such as `https://auth.example.com`. \u003cbr /\u003eOpen `https://auth.example.com/.well-known/openid-configuration` and enter the exact value of its `issuer` field. |\n| **Client ID** | The client ID configured in the OIDC IdP. |\n| **Client secret** | The matching client secret as plain text (unhashed).\u003cbr /\u003eOn later changes, leave this blank to retain the stored secret. \u003cbr /\u003eThe visibility button only reveals the value currently typed in the browser; Sambee never returns the stored secret. |\n| **Scopes** | A comma-separated list. Include `openid`, `offline_access`, and every scope required to return the claims configured below, such as `profile` and `email`. Add `groups` when using group admission or group-based role mappings. |\n\n### 3. Configure Session Policy\n\nSet **Interactive sign-in interval (days)** to control how long a verified IdP sign-in can be renewed in the background. The default is 30 days.\n\nDuring this interval, Sambee refreshes its short-lived API token in the background. At the interval deadline, Sambee requires a fresh interactive IdP sign-in.\n\n### 4. Configure Access\n\nComplete these fields in the **Access** section:\n\n| Sambee field | Value to enter |\n|---|---|\n| **Admission** | **All authenticated users** is the default. Select **Only selected groups** to require membership in named groups before Sambee evaluates the person's role. |\n| **Admission groups** | When **Admission** is **Only selected groups**, enter the exact identity-provider groups that may sign in, separated by commas. |\n\n### 5. Configure Role Assignment\n\nChoose how Sambee assigns roles after an identity passes the admission policy:\n\n| Role assignment | Behavior |\n|---|---|\n| **All users are assigned to the same role** | Select **Administrator**, **Editor** (default), or **Viewer**. Every admitted user receives that role unless they have an individual assignment. This is the simplest choice for smaller environments. |\n| **Group-based** | Enter exact identity-provider groups for **Administrator**, **Editor**, and **Viewer**. A person without an individual assignment must match a configured group; otherwise Sambee denies access. |\n\nIn group-based mode, a group can appear in only one role mapping. When a person matches multiple mappings, Sambee grants the highest role: Administrator, then Editor, then Viewer.\n\nDuring activation (see below), Sambee gives the administrator completing the test an individual **Administrator** assignment. Individual assignments for linked or pending accounts always take precedence over the configured role assignment.\n\n### 6. Advanced Claims\n\nThe default claim names work with most OpenID Connect providers. Expand **Advanced claims** only when the provider returns different claim names.\n\n#### Claims\n\n| Sambee field | Value to enter |\n|---|---|\n| **Username claim** | The stable, unique claim used to identify a person, commonly `preferred_username`. |\n| **Name claim** | Optional claim containing the person's display name, commonly `name`. |\n| **Email claim** | Optional claim containing the person's email address, commonly `email`. |\n| **Groups claim** | Optional claim containing group membership, commonly `groups`. Required only for selected-group admission or group-based role assignment. |\n\nSambee records the OIDC issuer and subject for each linked account. By default, Sambee also treats the configured IdP as authoritative for usernames: when an admitted IdP user has the same username as a local account, Sambee links that identity to the local account. This also updates an existing link when an IdP migration changes the issuer or subject. Keep **Automatically link OIDC identities to local accounts by username** enabled unless you need to resolve username matches manually.\n\n### 7. Connect and Test\n\nSelect **Connect and test** in the setup dialog. Sambee redirects you to the provider and returns to the dialog for review. This verifies that:\n\n- Signing in via the specified OIDC configuration succeeds.\n- Sambee can read and evaluate the resulting OIDC user identity.\n- The tested identity passes the selected admission rule, so the current administrator can keep administrator access after activation.\n\nReview the resulting identity before activation:\n\n- **Username**, **Email**, and **Groups** show the claims Sambee received.\n- **Admission** and **Matching admission group** show whether the tested identity passes the admission rule.\n\nOIDC activation remains unavailable unless the tested OIDC identity passes the admission rule to prevent the local admin making the changes from locking themselves out.\n\n### 8. Review and Activate\n\nSelect **Activate configuration** when the review is complete. The administrator who started the setup is linked to the tested provider identity automatically.\n\nWhen OIDC is active, users sign in normally after an IdP migration or subject reset. With automatic username linking enabled, Sambee updates their stored OIDC link during their next admitted sign-in and signs out existing Sambee sessions for that account. Until then, their existing OIDC link and IdP-managed full name and email remain read-only in User Management.\n\nAfter activation, see [OpenID Connect Authentication Operations](../openid-connect-authentication-operations/) for session, account-mapping, auditing, and request-limit administration.\n", "2.0": "+++\ntitle = \"OpenID Connect Authentication Setup\"\n+++\n\nOpenID Connect (OIDC) is Sambee's preferred authentication method.\n\n## Preparation\n\n### Copy OIDC Callback URI\n\nOpen **Settings** \u003e **Administration** \u003e **Authentication** and select an OIDC authentication mode. Select **Configure OIDC** and copy the OIDC callback URI from the dialog that opens. You need the URI in the next step. It has the following format:\n\n```text\nhttps://files.example.com/api/auth/oidc/callback\n```\n\n## Configure the OpenID Connect Identity Provider (IdP)\n\n### Provider Properties\n\nIn your identity provider, create a new OpenID Connect IdP with the following properties:\n\n- Confidential web client\n- Authorization code flow\n- PKCE with `S256`\n- `client_secret_basic` token endpoint authentication\n- `RS256`-signed ID tokens\n- Sambee's callback URI (see above)\n- Scopes:\n   - `openid`: required\n   - `profile`: often necessary for the provider to return `preferred_username`, which Sambee requires\n   - `email`: optional\n   - `groups`: required when using group admission or group-based role mappings\n   - `offline_access`: may be required for refresh tokens, depending on the provider\n- Authorization code grant\n- Refresh token grant: optional\n\n#### Token Lifetimes\n\nConfigure token lifetimes:\n\n- Refresh token, if the provider issues one:\n   - A shorter lifetime requires users to sign in again sooner.\n   - A longer lifetime increases the impact period if the token is compromised.\n   - Maximum useful length: slightly longer than Sambee's interactive sign-in interval (default: 30 days).\n- Access token and ID token:\n   - Lifetimes should be short, e.g., 1 hour.\n\n#### Refresh Tokens\n\nHaving the provider issue refresh tokens is recommended as that enables background session renewal without user interaction.\n\nProviders that don't issue refresh tokens can still be used with Sambee. They must return an ID token with a valid `auth_time` claim when Sambee requests `max_age`.\n\n### Verify the Username Claim\n\nSambee needs to match OIDC provider usernames to its own usernames. Many OIDC providers return a username in the field `preferred_username` when the `profile` scope is enabled. To ensure that username claim is suitable, verify the following with your OIDC provider:\n\n- How to enable returning the username claim (typically through the `profile` scope).\n- The field name of the username claim (typically `preferred_username`).\n- The username claim is present for every person who can sign in, stable for that person, and unique across all provider users.\n\n### Authelia Example\n\nThe relevant Authelia client entry can look like this:\n\n```yaml\nidentity_providers:\n  oidc:\n    lifespans:\n      custom:\n        sambee:\n          # Maximum useful length: Sambee's interactive sign-in interval + 1 day\n          refresh_token: '31d'\n    clients:\n      - client_id: sambee\n        client_name: Sambee\n        client_secret: '$pbkdf2-sha512$replace-with-a-hashed-random-secret'\n        redirect_uris:\n          - https://files.example.com/api/auth/oidc/callback\n        grant_types:\n          - authorization_code\n          - refresh_token\n        response_types:\n          - code\n        lifespan: sambee\n        scopes:\n          - openid\n          - profile\n          - email\n          - offline_access\n          # Add groups when using group admission or group-based role mappings.\n          - groups\n```\n\nNotes:\n\n- See Authelia's instructions for generating a [hashed client secret](https://www.authelia.com/integration/openid-connect/frequently-asked-questions/#how-do-i-generate-a-client-identifier-or-client-secret).\n- Use your own values for the following fields: `redirect_uris`.\n- The `profile` scope makes Authelia's `preferred_username` claim available from the username used to sign in, which is exactly what Sambee expects in its default OIDC settings (see below).\n- See the [Authelia documentation](https://www.authelia.com/configuration/identity-providers/openid-connect/clients/) more details and default values.\n\n## Configure Sambee\n\nOpen **Settings** \u003e **Administration** \u003e **Authentication**.\n\n### 1. Choose the Sign-In Mode\n\nSelect one of these values in **Authentication mode**:\n\n- **OIDC or password**\n- **OIDC only**\n\nThe **Access** panel shows whether OIDC is configured and healthy. Select **Configure OIDC** to enter or change the provider settings.\n\n### 2. Enter Provider Details\n\nIn the setup dialog, complete these fields in the **Provider** section:\n\n| Sambee field | Value to enter |\n|---|---|\n| **Provider name** | A recognizable name for the provider, such as `Authelia` or `Microsoft Entra ID`. |\n| **Issuer URL** | The provider's HTTPS issuer URL. For Authelia, this is normally the externally reachable URL of the Authelia portal, such as `https://auth.example.com`. \u003cbr /\u003eOpen `https://auth.example.com/.well-known/openid-configuration` and enter the exact value of its `issuer` field. |\n| **Client ID** | The client ID configured in the OIDC IdP. |\n| **Client secret** | The matching client secret as plain text (unhashed).\u003cbr /\u003eOn later changes, leave this blank to retain the stored secret. \u003cbr /\u003eThe visibility button only reveals the value currently typed in the browser; Sambee never returns the stored secret. |\n| **Scopes** | A comma-separated list. Include `openid` and every scope required for the configured claims, such as `profile` and `email`. Add `groups` for group admission or group-based role mappings. Add `offline_access` only if supported and needed for provider refresh tokens. |\n\n### 3. Configure Session Policy\n\nSet **Interactive sign-in interval (days)** to control the maximum age of a verified IdP sign-in. The default is 30 days.\n\nSet **Session limit without refresh token (hours)** separately for sign-ins that return no refresh token (default 8 hours; allowed range 1-24 hours).\n\nSambee issues short-lived API tokens (up to 60 minutes) while the browser session remains valid. With a refresh token, Sambee can renew through the IdP until the authentication-age limit. Without one, Sambee can issue another API token from the browser cookie only until the fixed session limit. Reducing that limit shortens existing no-refresh sessions; increasing it does not extend them. When the applicable deadline arrives, Sambee starts a new top-level IdP authorization, which might reuse the IdP's existing SSO session.\n\n### 4. Configure Access\n\nComplete these fields in the **Access** section:\n\n| Sambee field | Value to enter |\n|---|---|\n| **Admission** | **All authenticated users** is the default. Select **Only selected groups** to require membership in named groups before Sambee evaluates the person's role. |\n| **Admission groups** | When **Admission** is **Only selected groups**, enter the exact identity-provider groups that may sign in, separated by commas. |\n\n### 5. Configure Role Assignment\n\nChoose how Sambee assigns roles after an identity passes the admission policy:\n\n| Role assignment | Behavior |\n|---|---|\n| **All users are assigned to the same role** | Select **Administrator**, **Editor** (default), or **Viewer**. Every admitted user receives that role unless they have an individual assignment. This is the simplest choice for smaller environments. |\n| **Group-based** | Enter exact identity-provider groups for **Administrator**, **Editor**, and **Viewer**. A person without an individual assignment must match a configured group; otherwise Sambee denies access. |\n\nIn group-based mode, a group can appear in only one role mapping. When a person matches multiple mappings, Sambee grants the highest role: Administrator, then Editor, then Viewer.\n\nDuring activation (see below), Sambee gives the administrator completing the test an individual **Administrator** assignment. Individual assignments for linked or pending accounts always take precedence over the configured role assignment.\n\n### 6. Advanced Claims\n\nThe default claim names work with most OpenID Connect providers. Expand **Advanced claims** only when the provider returns different claim names.\n\n#### Claims\n\n| Sambee field | Value to enter |\n|---|---|\n| **Username claim** | The stable, unique claim used to identify a person, commonly `preferred_username`. |\n| **Name claim** | Optional claim containing the person's display name, commonly `name`. |\n| **Email claim** | Optional claim containing the person's email address, commonly `email`. |\n| **Groups claim** | Optional claim containing group membership, commonly `groups`. Required only for selected-group admission or group-based role assignment. |\n\nSambee records the OIDC issuer and subject for each linked account. By default, Sambee also treats the configured IdP as authoritative for usernames: when an admitted IdP user has the same username as a local account, Sambee links that identity to the local account. This also updates an existing link when an IdP migration changes the issuer or subject. Keep **Automatically link OIDC identities to local accounts by username** enabled unless you need to resolve username matches manually.\n\n### 7. Connect and Test\n\nSelect **Connect and test** in the setup dialog. Sambee redirects you to the provider and returns to the dialog for review. This verifies that:\n\n- Signing in via the specified OIDC configuration succeeds.\n- Sambee can read and evaluate the resulting OIDC user identity.\n- The tested identity passes the selected admission rule, so the current administrator can keep administrator access after activation.\n\nReview the resulting identity before activation:\n\n- **Username**, **Email**, and **Groups** show the claims Sambee received.\n- **Admission** and **Matching admission group** show whether the tested identity passes the admission rule.\n- **Session renewal** reports whether this particular test returned a refresh token. A test without one can still succeed; users will need to sign in again after the configured no-refresh session limit.\n\nOIDC activation remains unavailable unless the tested OIDC identity passes the admission rule to prevent the local admin making the changes from locking themselves out.\n\n### 8. Review and Activate\n\nSelect **Activate configuration** when the review is complete. The administrator who started the setup is linked to the tested provider identity automatically.\n\nWhen OIDC is active, users sign in normally after an IdP migration or subject reset. With automatic username linking enabled, Sambee updates their stored OIDC link during their next admitted sign-in and signs out existing Sambee sessions for that account. Until then, their existing OIDC link and IdP-managed full name and email remain read-only in User Management.\n\nAfter activation, see [OpenID Connect Authentication Operations](../openid-connect-authentication-operations/) for session, account-mapping, auditing, and request-limit administration.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:admin-guide/authentication/openid-connect-authentication-operations", "parent_id": "section:admin-guide/authentication", "depth": 2, "kind": "page", "label": "openid-connect-authentication-operations", "title": "Openid Connect Authentication Operations", "path": "admin-guide/authentication/openid-connect-authentication-operations", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "authored"}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "branched", "source_version": "0.9", "diff_added": 25, "diff_removed": 4}}, "content_versions": {"0.9": "+++\ntitle = \"OpenID Connect Authentication Operations\"\n+++\n\nUse this guide to manage OIDC sessions, account mappings, and audit records after completing [OpenID Connect Authentication Setup](../openid-connect-authentication-setup/).\n\n## Session Lifecycle\n\nFor each OIDC browser session, Sambee stores the provider refresh token encrypted on the server. The browser holds only a short-lived API token in memory and an `HttpOnly` session cookie. Reloading the page can obtain a new API token from that cookie without exposing the provider refresh token to browser storage, URLs, logs, or API responses.\n\nSambee renews the API token in the background until the configured interactive sign-in interval ends. Refreshing does not extend the original verified sign-in time.\n\nAn interactive sign-in is required when the interval ends, the identity provider rejects or revokes the refresh token, a refresh result is uncertain, an access policy changes, or the browser session is revoked. Sambee returns the user to the same safe route after sign-in. See [Recover Unsaved In-Browser Edits](../../../user-guide/viewing-and-editing-files/recover-unsaved-edits/) for the editing behavior during required sign-in.\n\n## Manage OIDC Sessions\n\nUsers can open **Settings** \u003e **Account** to review their current session and other active OIDC browser sessions. The page separates **This browser** from **Other sessions**. For a local password sign-in, the current entry is not a persistent server-side browser session. For an OIDC sign-in, Sambee shows when each session was created and last active. Newly created OIDC sessions can also show a coarse browser and operating-system label without exposing a device fingerprint or token details. Existing sessions might not have a label. See [Manage Your Account](../../../user-guide/getting-started/manage-your-account/) for the user-facing controls.\n\n- Select **Sign out** next to the current browser to revoke its session and return to the sign-in page.\n- Select **Revoke** to end another browser session.\n\nRevocation immediately invalidates API tokens issued for the affected browser sessions. It does not sign the user out of the identity provider itself.\n\n## Manage Account Mappings\n\nOpen **Settings** \u003e **Administration** \u003e **Users** to review how each local account authenticates. An account can show **Local password**, **OIDC linked**, or both. Established mappings show the provider name and most recent OIDC sign-in. With automatic username linking enabled, an admitted IdP user with the same username automatically links to that local account or updates its existing OIDC link. A pending mapping shows the provider username that must complete the first admitted OIDC sign-in, who created the mapping, and when.\n\nIn **OIDC only** mode, Sambee creates a passwordless account automatically when an admitted identity signs in for the first time. User Management does not offer manual user creation or local-password resets in this mode. Existing accounts can still be reviewed and mapped when an administrator needs to resolve an identity collision or apply an individual OIDC role before the first sign-in.\n\n### Assign Individual Roles\n\nFor a linked or pending account, set **OIDC role assignment** to **Administrator**, **Editor**, or **Viewer** to create an individual override. Select **Use configured role assignment** to apply the provider's uniform or group-based policy instead. Individual assignments take precedence over the configured policy and work without a groups claim unless selected-group admission requires one.\n\n### Change Mappings\n\nAdministrators can map an unlinked local account to an expected provider username, cancel a pending mapping, or change a linked account to a different provider username. Changing a linked username removes the established identity and creates a pending mapping.\n\nUse **Advanced OIDC actions** to view the stored identity properties, including issuer, subject, last-seen provider username, and verified group snapshot. You can also move an established identity to another active, unlinked local account or detach it from a local account. Changing, moving, or detaching an established identity revokes affected Sambee sessions. Detaching does not revoke access at the identity provider; remove provider admission separately when the person must no longer sign in.\n\nMapping updates are atomic and revision checked. If another administrator changes mappings while the page is open, Sambee rejects the stale update; reload the users page and review the current state. In **OIDC only** mode, Sambee prevents removal of the last active OIDC administrator mapping.\n\nDeleting a local user also removes their established identity, pending mappings targeting that user, and incomplete OIDC flows in the same transaction. Pending mappings that the deleted user created for other accounts remain active and show **Deleted user** as their creator. Deletion remains subject to the last-administrator guard.\n\n## Audit Events\n\nOIDC configuration and identity events are stored in the Sambee database. They do not contain raw subjects, provider tokens, client secrets, authorization codes, nonces, verifiers, or one-time login grants. Events are retained until the database is removed or an external retention process deletes them.\n\nExport the complete audit stream as JSON Lines:\n\n```bash\ncd backend\npython -m app.oidc_admin export-audit --output sambee-audit.jsonl\n```\n\n## Authentication Request Limits\n\nSambee enforces authentication limits in the application. A reverse proxy can add stricter limits but does not replace these defaults:\n\n| Request | Default limit |\n|---|---|\n| Start OIDC authorization | 20 requests per source IP per 5 minutes |\n| Process OIDC callback | 60 requests per source IP per 5 minutes |\n| Exchange OIDC login grant | 30 requests per source IP per 5 minutes |\n| Password sign-in | 10 attempts per source IP per 5 minutes and 10 attempts per submitted username per 15 minutes |\n\nLimits refill continuously. A rejected API request returns `Retry-After`; browser-based OIDC requests return to the sign-in page with a generic retry message. Password forms larger than 64 KiB are rejected before parsing. These responses do not expose account existence, the active sign-in mode, provider payloads, or submitted credentials.\n\n", "1.0": "+++\ntitle = \"OpenID Connect Authentication Operations\"\n+++\n\nUse this guide to manage OIDC sessions, account mappings, and audit records after completing [OpenID Connect Authentication Setup](../openid-connect-authentication-setup/).\n\n## Session Lifecycle\n\nFor each OIDC browser session, Sambee stores the provider refresh token encrypted on the server. The browser holds only a short-lived API token in memory and an `HttpOnly` session cookie. Reloading the page can obtain a new API token from that cookie without exposing the provider refresh token to browser storage, URLs, logs, or API responses.\n\nSambee renews the API token in the background until the configured interactive sign-in interval ends. Refreshing does not extend the original verified sign-in time.\n\nAn interactive sign-in is required when the interval ends, the identity provider rejects or revokes the refresh token, a refresh result is uncertain, an access policy changes, or the browser session is revoked. Sambee returns the user to the same safe route after sign-in. See [Recover Unsaved In-Browser Edits](../../../user-guide/viewing-and-editing-files/recover-unsaved-edits/) for the editing behavior during required sign-in.\n\n## Manage OIDC Sessions\n\nUsers can open **Settings** \u003e **Account** to review their current session and other active OIDC browser sessions. The page separates **This browser** from **Other sessions**. For a local password sign-in, the current entry is not a persistent server-side browser session. For an OIDC sign-in, Sambee shows when each session was created and last active. Newly created OIDC sessions can also show a coarse browser and operating-system label without exposing a device fingerprint or token details. Existing sessions might not have a label. See [Manage Your Account](../../../user-guide/getting-started/manage-your-account/) for the user-facing controls.\n\n- Select **Sign out** next to the current browser to revoke its session and return to the sign-in page.\n- Select **Revoke** to end another browser session.\n\nRevocation immediately invalidates API tokens issued for the affected browser sessions. It does not sign the user out of the identity provider itself.\n\n## Manage Account Mappings\n\nOpen **Settings** \u003e **Administration** \u003e **Users** to review how each local account authenticates. An account can show **Local password**, **OIDC linked**, or both. Established mappings show the provider name and most recent OIDC sign-in. With automatic username linking enabled, an admitted IdP user with the same username automatically links to that local account or updates its existing OIDC link. A pending mapping shows the provider username that must complete the first admitted OIDC sign-in, who created the mapping, and when.\n\nIn **OIDC only** mode, Sambee creates a passwordless account automatically when an admitted identity signs in for the first time. User Management does not offer manual user creation or local-password resets in this mode. Existing accounts can still be reviewed and mapped when an administrator needs to resolve an identity collision or apply an individual OIDC role before the first sign-in.\n\n### Assign Individual Roles\n\nFor a linked or pending account, set **OIDC role assignment** to **Administrator**, **Editor**, or **Viewer** to create an individual override. Select **Use configured role assignment** to apply the provider's uniform or group-based policy instead. Individual assignments take precedence over the configured policy and work without a groups claim unless selected-group admission requires one.\n\n### Change Mappings\n\nAdministrators can map an unlinked local account to an expected provider username, cancel a pending mapping, or change a linked account to a different provider username. Changing a linked username removes the established identity and creates a pending mapping.\n\nUse **Advanced OIDC actions** to view the stored identity properties, including issuer, subject, last-seen provider username, and verified group snapshot. You can also move an established identity to another active, unlinked local account or detach it from a local account. Changing, moving, or detaching an established identity revokes affected Sambee sessions. Detaching does not revoke access at the identity provider; remove provider admission separately when the person must no longer sign in.\n\nMapping updates are atomic and revision checked. If another administrator changes mappings while the page is open, Sambee rejects the stale update; reload the users page and review the current state. In **OIDC only** mode, Sambee prevents removal of the last active OIDC administrator mapping.\n\nDeleting a local user also removes their established identity, pending mappings targeting that user, and incomplete OIDC flows in the same transaction. Pending mappings that the deleted user created for other accounts remain active and show **Deleted user** as their creator. Deletion remains subject to the last-administrator guard.\n\n## Audit Events\n\nOIDC configuration and identity events are stored in the Sambee database. They do not contain raw subjects, provider tokens, client secrets, authorization codes, nonces, verifiers, or one-time login grants. Events are retained until the database is removed or an external retention process deletes them.\n\nExport the complete audit stream as JSON Lines:\n\n```bash\ncd backend\npython -m app.oidc_admin export-audit --output sambee-audit.jsonl\n```\n\n## Authentication Request Limits\n\nSambee enforces authentication limits in the application. A reverse proxy can add stricter limits but does not replace these defaults:\n\n| Request | Default limit |\n|---|---|\n| Start OIDC authorization | 20 requests per source IP per 5 minutes |\n| Process OIDC callback | 60 requests per source IP per 5 minutes |\n| Exchange OIDC login grant | 30 requests per source IP per 5 minutes |\n| Password sign-in | 10 attempts per source IP per 5 minutes and 10 attempts per submitted username per 15 minutes |\n\nLimits refill continuously. A rejected API request returns `Retry-After`; browser-based OIDC requests return to the sign-in page with a generic retry message. Password forms larger than 64 KiB are rejected before parsing. These responses do not expose account existence, the active sign-in mode, provider payloads, or submitted credentials.\n\n", "2.0": "+++\ntitle = \"OpenID Connect Authentication Operations\"\n+++\n\nUse this guide to manage OIDC sessions, account mappings, and audit records after completing [OpenID Connect Authentication Setup](../openid-connect-authentication-setup/).\n\n## Session Lifecycle\n\nWhen a provider returns a refresh token, Sambee stores it encrypted on the server. If the provider returns none, Sambee stores no provider token. In both cases, the browser holds only a short-lived API token in memory and an `HttpOnly` session cookie. Reloading the page can obtain a new API token from that cookie without exposing provider tokens to browser storage, URLs, logs, or API responses.\n\nSambee renews the API token in the background while the session remains valid. A session with a refresh token is limited by the configured interactive sign-in interval (default 30 days from the verified IdP authentication). A session without a refresh token has a fixed limit of 8 hours from the callback by default, configurable from 1 to 24 hours. Neither local activity nor API-token renewal extends that deadline; the earlier applicable deadline always wins. Reducing the no-refresh limit permanently shortens existing sessions, including pending sign-ins.\n\nA new top-level authorization is required when the applicable deadline ends, the identity provider rejects or revokes a refresh token, a refresh result is uncertain, an access policy changes, or the browser session is revoked. The IdP might use its SSO cookie to return quickly, but this is not guaranteed. Sambee returns the user to the same safe route after sign-in. Registered text and Markdown drafts are snapshotted before an authentication redirect when storage is available; other unsaved work might be interrupted. See [Recover Unsaved In-Browser Edits](../../../user-guide/viewing-and-editing-files/recover-unsaved-edits/) for limitations and recovery behavior.\n\n## Manage OIDC Sessions\n\nUsers can open **Settings** \u003e **Account** to review their current session and other active OIDC browser sessions. The page separates **This browser** from **Other sessions**. For a local password sign-in, the current entry is not a persistent server-side browser session. For an OIDC sign-in, Sambee shows when each session was created and last active. Newly created OIDC sessions can also show a coarse browser and operating-system label without exposing a device fingerprint or token details. Existing sessions might not have a label. See [Manage Your Account](../../../user-guide/getting-started/manage-your-account/) for the user-facing controls.\n\n- Select **Sign out** next to the current browser to revoke its session and return to the sign-in page.\n- Select **Revoke** to end another browser session.\n\nRevocation immediately invalidates API tokens issued for the affected browser sessions. It does not sign the user out of the identity provider itself.\n\n## Manage Account Mappings\n\nOpen **Settings** \u003e **Administration** \u003e **Users** to review how each local account authenticates. An account can show **Local password**, **OIDC linked**, or both. Established mappings show the provider name and most recent OIDC sign-in. With automatic username linking enabled, an admitted IdP user with the same username automatically links to that local account or updates its existing OIDC link. A pending mapping shows the provider username that must complete the first admitted OIDC sign-in, who created the mapping, and when.\n\nIn **OIDC only** mode, Sambee creates a passwordless account automatically when an admitted identity signs in for the first time. User Management does not offer manual user creation or local-password resets in this mode. Existing accounts can still be reviewed and mapped when an administrator needs to resolve an identity collision or apply an individual OIDC role before the first sign-in.\n\n### Assign Individual Roles\n\nFor a linked or pending account, set **OIDC role assignment** to **Administrator**, **Editor**, or **Viewer** to create an individual override. Select **Use configured role assignment** to apply the provider's uniform or group-based policy instead. Individual assignments take precedence over the configured policy and work without a groups claim unless selected-group admission requires one.\n\n### Change Mappings\n\nAdministrators can map an unlinked local account to an expected provider username, cancel a pending mapping, or change a linked account to a different provider username. Changing a linked username removes the established identity and creates a pending mapping.\n\nUse **Advanced OIDC actions** to view the stored identity properties, including issuer, subject, last-seen provider username, and verified group snapshot. You can also move an established identity to another active, unlinked local account or detach it from a local account. Changing, moving, or detaching an established identity revokes affected Sambee sessions. Detaching does not revoke access at the identity provider; remove provider admission separately when the person must no longer sign in.\n\nMapping updates are atomic and revision checked. If another administrator changes mappings while the page is open, Sambee rejects the stale update; reload the users page and review the current state. In **OIDC only** mode, Sambee prevents removal of the last active OIDC administrator mapping.\n\nDeleting a local user also removes their established identity, pending mappings targeting that user, and incomplete OIDC flows in the same transaction. Pending mappings that the deleted user created for other accounts remain active and show **Deleted user** as their creator. Deletion remains subject to the last-administrator guard.\n\n## Local Username Matching And Upgrade Conflicts\n\nLocal-password sign-in matches usernames without regard to capitalization, using Unicode case folding and ignoring leading and trailing whitespace. Stored spelling is preserved. Passwords remain case-sensitive. New accounts and renamed accounts can't introduce case-insensitive duplicates, including accounts created through OIDC.\n\nUpgrades complete automatically even if existing accounts have conflicting names, such as `UserA` and `usera`. Accounts, passwords, roles, ownership, and identity links are preserved. Each conflicting account continues to accept only its exact stored username spelling; other capitalizations are rejected without choosing an account by its password. Disabled, expired, and passwordless accounts also count toward a conflict.\n\n**Settings** \u003e **Administration** \u003e **Users** lists conflicts in a warning, regardless of directory filters or pagination. Resolve a conflict by renaming an account through its normal editor, or deleting an account that's no longer needed. Deleting an account remains subject to the normal deletion consequences and administrator safeguards. Unchanged usernames and case-only renames remain available while resolving existing conflicts. Once only one account has a comparison key, case-insensitive password sign-in applies automatically, without restarting or rerunning a migration.\n\nOIDC identity matching and automatic linking still require the exact username spelling. A case-only match doesn't automatically link an identity or create another account; resolve that collision through the existing identity-mapping controls.\n\n## Require A Local Password Change\n\nWhen creating a local user or resetting an existing local password, enable **Require change on next password sign-in** to require a new password before the user can continue. The user directory shows **Pwd change req'd** while this requirement is pending.\n\nAfter signing in with the temporary or existing local password, the user must enter that password, choose a different password, and confirm it. They can sign out instead, but can't browse files, use administration settings, or issue companion credentials until the change succeeds. Successful changes invalidate existing Sambee tokens and require another sign-in.\n\nThe requirement applies only to local-password sessions. A linked user can still sign in through OIDC; that doesn't clear the local-password requirement or change the identity provider's password. Passwordless OIDC accounts have no local password to reset. In **OIDC only** mode, local password changes are unavailable.\n\nExisting password-change flags are enforced after upgrading. They aren't cleared automatically. If a user can't complete the change, an administrator can set another local password through User Management. Switch the requirement off during that reset only when the replacement password is intended to be permanent. Authentication-disabled mode doesn't enforce the change workflow.\n\n## Audit Events\n\nOIDC configuration, identity events, and successful local password changes and resets are stored in the Sambee database. They do not contain passwords, raw subjects, provider tokens, client secrets, authorization codes, nonces, verifiers, or one-time login grants. Events are retained until the database is removed or an external retention process deletes them.\n\nExport the complete audit stream as JSON Lines:\n\n```bash\ncd backend\npython -m app.oidc_admin export-audit --output sambee-audit.jsonl\n```\n\n## Authentication Request Limits\n\nSambee enforces authentication limits in the application. A reverse proxy can add stricter limits but does not replace these defaults:\n\n| Request | Default limit |\n|---|---|\n| Start OIDC authorization | 20 requests per source IP per 5 minutes |\n| Process OIDC callback | 60 requests per source IP per 5 minutes |\n| Exchange OIDC login grant | 30 requests per source IP per 5 minutes |\n| Password sign-in | 10 attempts per source IP per 5 minutes and 10 attempts per submitted username per 15 minutes |\n\nLimits refill continuously. A rejected API request returns `Retry-After`; browser-based OIDC requests return to the sign-in page with a generic retry message. Password forms larger than 64 KiB are rejected before parsing. These responses do not expose account existence, the active sign-in mode, provider payloads, or submitted credentials.\n\nAll capitalization and Unicode case-folding variants of a username share the same username-based password limit, including legacy conflicting accounts.\n"}, "page_contents": {"0.9": "+++\ntitle = \"OpenID Connect Authentication Operations\"\n+++\n\nUse this guide to manage OIDC sessions, account mappings, and audit records after completing [OpenID Connect Authentication Setup](../openid-connect-authentication-setup/).\n\n## Session Lifecycle\n\nFor each OIDC browser session, Sambee stores the provider refresh token encrypted on the server. The browser holds only a short-lived API token in memory and an `HttpOnly` session cookie. Reloading the page can obtain a new API token from that cookie without exposing the provider refresh token to browser storage, URLs, logs, or API responses.\n\nSambee renews the API token in the background until the configured interactive sign-in interval ends. Refreshing does not extend the original verified sign-in time.\n\nAn interactive sign-in is required when the interval ends, the identity provider rejects or revokes the refresh token, a refresh result is uncertain, an access policy changes, or the browser session is revoked. Sambee returns the user to the same safe route after sign-in. See [Recover Unsaved In-Browser Edits](../../../user-guide/viewing-and-editing-files/recover-unsaved-edits/) for the editing behavior during required sign-in.\n\n## Manage OIDC Sessions\n\nUsers can open **Settings** \u003e **Account** to review their current session and other active OIDC browser sessions. The page separates **This browser** from **Other sessions**. For a local password sign-in, the current entry is not a persistent server-side browser session. For an OIDC sign-in, Sambee shows when each session was created and last active. Newly created OIDC sessions can also show a coarse browser and operating-system label without exposing a device fingerprint or token details. Existing sessions might not have a label. See [Manage Your Account](../../../user-guide/getting-started/manage-your-account/) for the user-facing controls.\n\n- Select **Sign out** next to the current browser to revoke its session and return to the sign-in page.\n- Select **Revoke** to end another browser session.\n\nRevocation immediately invalidates API tokens issued for the affected browser sessions. It does not sign the user out of the identity provider itself.\n\n## Manage Account Mappings\n\nOpen **Settings** \u003e **Administration** \u003e **Users** to review how each local account authenticates. An account can show **Local password**, **OIDC linked**, or both. Established mappings show the provider name and most recent OIDC sign-in. With automatic username linking enabled, an admitted IdP user with the same username automatically links to that local account or updates its existing OIDC link. A pending mapping shows the provider username that must complete the first admitted OIDC sign-in, who created the mapping, and when.\n\nIn **OIDC only** mode, Sambee creates a passwordless account automatically when an admitted identity signs in for the first time. User Management does not offer manual user creation or local-password resets in this mode. Existing accounts can still be reviewed and mapped when an administrator needs to resolve an identity collision or apply an individual OIDC role before the first sign-in.\n\n### Assign Individual Roles\n\nFor a linked or pending account, set **OIDC role assignment** to **Administrator**, **Editor**, or **Viewer** to create an individual override. Select **Use configured role assignment** to apply the provider's uniform or group-based policy instead. Individual assignments take precedence over the configured policy and work without a groups claim unless selected-group admission requires one.\n\n### Change Mappings\n\nAdministrators can map an unlinked local account to an expected provider username, cancel a pending mapping, or change a linked account to a different provider username. Changing a linked username removes the established identity and creates a pending mapping.\n\nUse **Advanced OIDC actions** to view the stored identity properties, including issuer, subject, last-seen provider username, and verified group snapshot. You can also move an established identity to another active, unlinked local account or detach it from a local account. Changing, moving, or detaching an established identity revokes affected Sambee sessions. Detaching does not revoke access at the identity provider; remove provider admission separately when the person must no longer sign in.\n\nMapping updates are atomic and revision checked. If another administrator changes mappings while the page is open, Sambee rejects the stale update; reload the users page and review the current state. In **OIDC only** mode, Sambee prevents removal of the last active OIDC administrator mapping.\n\nDeleting a local user also removes their established identity, pending mappings targeting that user, and incomplete OIDC flows in the same transaction. Pending mappings that the deleted user created for other accounts remain active and show **Deleted user** as their creator. Deletion remains subject to the last-administrator guard.\n\n## Audit Events\n\nOIDC configuration and identity events are stored in the Sambee database. They do not contain raw subjects, provider tokens, client secrets, authorization codes, nonces, verifiers, or one-time login grants. Events are retained until the database is removed or an external retention process deletes them.\n\nExport the complete audit stream as JSON Lines:\n\n```bash\ncd backend\npython -m app.oidc_admin export-audit --output sambee-audit.jsonl\n```\n\n## Authentication Request Limits\n\nSambee enforces authentication limits in the application. A reverse proxy can add stricter limits but does not replace these defaults:\n\n| Request | Default limit |\n|---|---|\n| Start OIDC authorization | 20 requests per source IP per 5 minutes |\n| Process OIDC callback | 60 requests per source IP per 5 minutes |\n| Exchange OIDC login grant | 30 requests per source IP per 5 minutes |\n| Password sign-in | 10 attempts per source IP per 5 minutes and 10 attempts per submitted username per 15 minutes |\n\nLimits refill continuously. A rejected API request returns `Retry-After`; browser-based OIDC requests return to the sign-in page with a generic retry message. Password forms larger than 64 KiB are rejected before parsing. These responses do not expose account existence, the active sign-in mode, provider payloads, or submitted credentials.\n\n", "1.0": "+++\ntitle = \"OpenID Connect Authentication Operations\"\n+++\n\nUse this guide to manage OIDC sessions, account mappings, and audit records after completing [OpenID Connect Authentication Setup](../openid-connect-authentication-setup/).\n\n## Session Lifecycle\n\nFor each OIDC browser session, Sambee stores the provider refresh token encrypted on the server. The browser holds only a short-lived API token in memory and an `HttpOnly` session cookie. Reloading the page can obtain a new API token from that cookie without exposing the provider refresh token to browser storage, URLs, logs, or API responses.\n\nSambee renews the API token in the background until the configured interactive sign-in interval ends. Refreshing does not extend the original verified sign-in time.\n\nAn interactive sign-in is required when the interval ends, the identity provider rejects or revokes the refresh token, a refresh result is uncertain, an access policy changes, or the browser session is revoked. Sambee returns the user to the same safe route after sign-in. See [Recover Unsaved In-Browser Edits](../../../user-guide/viewing-and-editing-files/recover-unsaved-edits/) for the editing behavior during required sign-in.\n\n## Manage OIDC Sessions\n\nUsers can open **Settings** \u003e **Account** to review their current session and other active OIDC browser sessions. The page separates **This browser** from **Other sessions**. For a local password sign-in, the current entry is not a persistent server-side browser session. For an OIDC sign-in, Sambee shows when each session was created and last active. Newly created OIDC sessions can also show a coarse browser and operating-system label without exposing a device fingerprint or token details. Existing sessions might not have a label. See [Manage Your Account](../../../user-guide/getting-started/manage-your-account/) for the user-facing controls.\n\n- Select **Sign out** next to the current browser to revoke its session and return to the sign-in page.\n- Select **Revoke** to end another browser session.\n\nRevocation immediately invalidates API tokens issued for the affected browser sessions. It does not sign the user out of the identity provider itself.\n\n## Manage Account Mappings\n\nOpen **Settings** \u003e **Administration** \u003e **Users** to review how each local account authenticates. An account can show **Local password**, **OIDC linked**, or both. Established mappings show the provider name and most recent OIDC sign-in. With automatic username linking enabled, an admitted IdP user with the same username automatically links to that local account or updates its existing OIDC link. A pending mapping shows the provider username that must complete the first admitted OIDC sign-in, who created the mapping, and when.\n\nIn **OIDC only** mode, Sambee creates a passwordless account automatically when an admitted identity signs in for the first time. User Management does not offer manual user creation or local-password resets in this mode. Existing accounts can still be reviewed and mapped when an administrator needs to resolve an identity collision or apply an individual OIDC role before the first sign-in.\n\n### Assign Individual Roles\n\nFor a linked or pending account, set **OIDC role assignment** to **Administrator**, **Editor**, or **Viewer** to create an individual override. Select **Use configured role assignment** to apply the provider's uniform or group-based policy instead. Individual assignments take precedence over the configured policy and work without a groups claim unless selected-group admission requires one.\n\n### Change Mappings\n\nAdministrators can map an unlinked local account to an expected provider username, cancel a pending mapping, or change a linked account to a different provider username. Changing a linked username removes the established identity and creates a pending mapping.\n\nUse **Advanced OIDC actions** to view the stored identity properties, including issuer, subject, last-seen provider username, and verified group snapshot. You can also move an established identity to another active, unlinked local account or detach it from a local account. Changing, moving, or detaching an established identity revokes affected Sambee sessions. Detaching does not revoke access at the identity provider; remove provider admission separately when the person must no longer sign in.\n\nMapping updates are atomic and revision checked. If another administrator changes mappings while the page is open, Sambee rejects the stale update; reload the users page and review the current state. In **OIDC only** mode, Sambee prevents removal of the last active OIDC administrator mapping.\n\nDeleting a local user also removes their established identity, pending mappings targeting that user, and incomplete OIDC flows in the same transaction. Pending mappings that the deleted user created for other accounts remain active and show **Deleted user** as their creator. Deletion remains subject to the last-administrator guard.\n\n## Audit Events\n\nOIDC configuration and identity events are stored in the Sambee database. They do not contain raw subjects, provider tokens, client secrets, authorization codes, nonces, verifiers, or one-time login grants. Events are retained until the database is removed or an external retention process deletes them.\n\nExport the complete audit stream as JSON Lines:\n\n```bash\ncd backend\npython -m app.oidc_admin export-audit --output sambee-audit.jsonl\n```\n\n## Authentication Request Limits\n\nSambee enforces authentication limits in the application. A reverse proxy can add stricter limits but does not replace these defaults:\n\n| Request | Default limit |\n|---|---|\n| Start OIDC authorization | 20 requests per source IP per 5 minutes |\n| Process OIDC callback | 60 requests per source IP per 5 minutes |\n| Exchange OIDC login grant | 30 requests per source IP per 5 minutes |\n| Password sign-in | 10 attempts per source IP per 5 minutes and 10 attempts per submitted username per 15 minutes |\n\nLimits refill continuously. A rejected API request returns `Retry-After`; browser-based OIDC requests return to the sign-in page with a generic retry message. Password forms larger than 64 KiB are rejected before parsing. These responses do not expose account existence, the active sign-in mode, provider payloads, or submitted credentials.\n\n", "2.0": "+++\ntitle = \"OpenID Connect Authentication Operations\"\n+++\n\nUse this guide to manage OIDC sessions, account mappings, and audit records after completing [OpenID Connect Authentication Setup](../openid-connect-authentication-setup/).\n\n## Session Lifecycle\n\nWhen a provider returns a refresh token, Sambee stores it encrypted on the server. If the provider returns none, Sambee stores no provider token. In both cases, the browser holds only a short-lived API token in memory and an `HttpOnly` session cookie. Reloading the page can obtain a new API token from that cookie without exposing provider tokens to browser storage, URLs, logs, or API responses.\n\nSambee renews the API token in the background while the session remains valid. A session with a refresh token is limited by the configured interactive sign-in interval (default 30 days from the verified IdP authentication). A session without a refresh token has a fixed limit of 8 hours from the callback by default, configurable from 1 to 24 hours. Neither local activity nor API-token renewal extends that deadline; the earlier applicable deadline always wins. Reducing the no-refresh limit permanently shortens existing sessions, including pending sign-ins.\n\nA new top-level authorization is required when the applicable deadline ends, the identity provider rejects or revokes a refresh token, a refresh result is uncertain, an access policy changes, or the browser session is revoked. The IdP might use its SSO cookie to return quickly, but this is not guaranteed. Sambee returns the user to the same safe route after sign-in. Registered text and Markdown drafts are snapshotted before an authentication redirect when storage is available; other unsaved work might be interrupted. See [Recover Unsaved In-Browser Edits](../../../user-guide/viewing-and-editing-files/recover-unsaved-edits/) for limitations and recovery behavior.\n\n## Manage OIDC Sessions\n\nUsers can open **Settings** \u003e **Account** to review their current session and other active OIDC browser sessions. The page separates **This browser** from **Other sessions**. For a local password sign-in, the current entry is not a persistent server-side browser session. For an OIDC sign-in, Sambee shows when each session was created and last active. Newly created OIDC sessions can also show a coarse browser and operating-system label without exposing a device fingerprint or token details. Existing sessions might not have a label. See [Manage Your Account](../../../user-guide/getting-started/manage-your-account/) for the user-facing controls.\n\n- Select **Sign out** next to the current browser to revoke its session and return to the sign-in page.\n- Select **Revoke** to end another browser session.\n\nRevocation immediately invalidates API tokens issued for the affected browser sessions. It does not sign the user out of the identity provider itself.\n\n## Manage Account Mappings\n\nOpen **Settings** \u003e **Administration** \u003e **Users** to review how each local account authenticates. An account can show **Local password**, **OIDC linked**, or both. Established mappings show the provider name and most recent OIDC sign-in. With automatic username linking enabled, an admitted IdP user with the same username automatically links to that local account or updates its existing OIDC link. A pending mapping shows the provider username that must complete the first admitted OIDC sign-in, who created the mapping, and when.\n\nIn **OIDC only** mode, Sambee creates a passwordless account automatically when an admitted identity signs in for the first time. User Management does not offer manual user creation or local-password resets in this mode. Existing accounts can still be reviewed and mapped when an administrator needs to resolve an identity collision or apply an individual OIDC role before the first sign-in.\n\n### Assign Individual Roles\n\nFor a linked or pending account, set **OIDC role assignment** to **Administrator**, **Editor**, or **Viewer** to create an individual override. Select **Use configured role assignment** to apply the provider's uniform or group-based policy instead. Individual assignments take precedence over the configured policy and work without a groups claim unless selected-group admission requires one.\n\n### Change Mappings\n\nAdministrators can map an unlinked local account to an expected provider username, cancel a pending mapping, or change a linked account to a different provider username. Changing a linked username removes the established identity and creates a pending mapping.\n\nUse **Advanced OIDC actions** to view the stored identity properties, including issuer, subject, last-seen provider username, and verified group snapshot. You can also move an established identity to another active, unlinked local account or detach it from a local account. Changing, moving, or detaching an established identity revokes affected Sambee sessions. Detaching does not revoke access at the identity provider; remove provider admission separately when the person must no longer sign in.\n\nMapping updates are atomic and revision checked. If another administrator changes mappings while the page is open, Sambee rejects the stale update; reload the users page and review the current state. In **OIDC only** mode, Sambee prevents removal of the last active OIDC administrator mapping.\n\nDeleting a local user also removes their established identity, pending mappings targeting that user, and incomplete OIDC flows in the same transaction. Pending mappings that the deleted user created for other accounts remain active and show **Deleted user** as their creator. Deletion remains subject to the last-administrator guard.\n\n## Local Username Matching And Upgrade Conflicts\n\nLocal-password sign-in matches usernames without regard to capitalization, using Unicode case folding and ignoring leading and trailing whitespace. Stored spelling is preserved. Passwords remain case-sensitive. New accounts and renamed accounts can't introduce case-insensitive duplicates, including accounts created through OIDC.\n\nUpgrades complete automatically even if existing accounts have conflicting names, such as `UserA` and `usera`. Accounts, passwords, roles, ownership, and identity links are preserved. Each conflicting account continues to accept only its exact stored username spelling; other capitalizations are rejected without choosing an account by its password. Disabled, expired, and passwordless accounts also count toward a conflict.\n\n**Settings** \u003e **Administration** \u003e **Users** lists conflicts in a warning, regardless of directory filters or pagination. Resolve a conflict by renaming an account through its normal editor, or deleting an account that's no longer needed. Deleting an account remains subject to the normal deletion consequences and administrator safeguards. Unchanged usernames and case-only renames remain available while resolving existing conflicts. Once only one account has a comparison key, case-insensitive password sign-in applies automatically, without restarting or rerunning a migration.\n\nOIDC identity matching and automatic linking still require the exact username spelling. A case-only match doesn't automatically link an identity or create another account; resolve that collision through the existing identity-mapping controls.\n\n## Require A Local Password Change\n\nWhen creating a local user or resetting an existing local password, enable **Require change on next password sign-in** to require a new password before the user can continue. The user directory shows **Pwd change req'd** while this requirement is pending.\n\nAfter signing in with the temporary or existing local password, the user must enter that password, choose a different password, and confirm it. They can sign out instead, but can't browse files, use administration settings, or issue companion credentials until the change succeeds. Successful changes invalidate existing Sambee tokens and require another sign-in.\n\nThe requirement applies only to local-password sessions. A linked user can still sign in through OIDC; that doesn't clear the local-password requirement or change the identity provider's password. Passwordless OIDC accounts have no local password to reset. In **OIDC only** mode, local password changes are unavailable.\n\nExisting password-change flags are enforced after upgrading. They aren't cleared automatically. If a user can't complete the change, an administrator can set another local password through User Management. Switch the requirement off during that reset only when the replacement password is intended to be permanent. Authentication-disabled mode doesn't enforce the change workflow.\n\n## Audit Events\n\nOIDC configuration, identity events, and successful local password changes and resets are stored in the Sambee database. They do not contain passwords, raw subjects, provider tokens, client secrets, authorization codes, nonces, verifiers, or one-time login grants. Events are retained until the database is removed or an external retention process deletes them.\n\nExport the complete audit stream as JSON Lines:\n\n```bash\ncd backend\npython -m app.oidc_admin export-audit --output sambee-audit.jsonl\n```\n\n## Authentication Request Limits\n\nSambee enforces authentication limits in the application. A reverse proxy can add stricter limits but does not replace these defaults:\n\n| Request | Default limit |\n|---|---|\n| Start OIDC authorization | 20 requests per source IP per 5 minutes |\n| Process OIDC callback | 60 requests per source IP per 5 minutes |\n| Exchange OIDC login grant | 30 requests per source IP per 5 minutes |\n| Password sign-in | 10 attempts per source IP per 5 minutes and 10 attempts per submitted username per 15 minutes |\n\nLimits refill continuously. A rejected API request returns `Retry-After`; browser-based OIDC requests return to the sign-in page with a generic retry message. Password forms larger than 64 KiB are rejected before parsing. These responses do not expose account existence, the active sign-in mode, provider payloads, or submitted credentials.\n\nAll capitalization and Unicode case-folding variants of a username share the same username-based password limit, including legacy conflicting accounts.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "book:developer-guide", "parent_id": null, "depth": 0, "kind": "book", "label": "developer-guide", "title": "Developer Guide", "path": "developer-guide", "has_children": true, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Developer Guide\"\n+++\n\nUse this guide to understand how Sambee is built across the backend, frontend, and companion, work safely in the repository and choose the right contributor workflow, understand the architecture and cross-cutting systems before changing code, and validate changes with the right checks before review or release.\n\n## Start Here if You Want To\n\n- Understand how the browser app, backend, and companion fit together.\n- Find the right place in the repository before changing code.\n- Set up the development environment and use the common contributor workflows.\n- Understand the high-level architecture of the backend, frontend, and companion.\n- Understand deeper contributor rules for preview pipelines, companion trust, or version-sensitive changes.\n- Choose the right validation commands before you open a pull request.\n\n## In This Guide\n\n- [Project Orientation](./project-orientation/): Understand the product boundaries and the repository layout.\n- [Local Development Workflow](./local-development-workflow/): Set up the environment and find the commands you will actually use.\n- [Backend Architecture](./backend-architecture/): Understand the FastAPI service, SMB-facing behavior, and server-side contracts.\n- [Frontend Architecture](./frontend-architecture/): Understand the browser app, page structure, and UI behavior contracts.\n- [Companion Architecture](./companion-architecture/): Understand the desktop app, pairing model, local-drive access, and native-app editing workflow.\n- [Cross-Cutting Systems](./cross-cutting-systems/): Understand shared logging, localization, and other rules that span more than one app.\n- [Testing and Quality Gates](./testing-and-quality-gates/): Choose the right checks for the change you are making.\n- [Contribution Workflows](./contribution-workflows/): Plan and review changes with the right scope and validation depth.\n- [Security](./security/): Understand dependency automation, vulnerability scanning, and release-artifact integrity.\n- [Release and Versioning](./release-and-versioning/): Handle dependency updates and version metadata safely.\n\n## Use the Right Guide\n\n- Use the Developer Guide when the next question is implementation-facing.\n- Use the [Website Dev Guide](../website-dev-guide/) when the work is on the public website, published docs content, docs tooling, or shared website theme systems.\n- Use the [User Guide](../user-guide/) when the next step belongs to the person using Sambee in normal workflows.\n- Use the [Admin Guide](../admin-guide/) when the next step is deployment, configuration, operations, or escalation.\n\n", "0.8": "+++\ntitle = \"Developer Guide\"\n+++\n\nUse this guide to understand how Sambee is built across the backend, frontend, and companion, work safely in the repository and choose the right contributor workflow, understand the architecture and cross-cutting systems before changing code, and validate changes with the right checks before review or release.\n\n## Start Here if You Want To\n\n- Understand how the browser app, backend, and companion fit together.\n- Find the right place in the repository before changing code.\n- Set up the development environment and use the common contributor workflows.\n- Understand the high-level architecture of the backend, frontend, and companion.\n- Understand deeper contributor rules for preview pipelines, companion trust, or version-sensitive changes.\n- Choose the right validation commands before you open a pull request.\n\n## In This Guide\n\n- [Project Orientation](./project-orientation/): Understand the product boundaries and the repository layout.\n- [Local Development Workflow](./local-development-workflow/): Set up the environment and find the commands you will actually use.\n- [Backend Architecture](./backend-architecture/): Understand the FastAPI service, SMB-facing behavior, and server-side contracts.\n- [Frontend Architecture](./frontend-architecture/): Understand the browser app, page structure, and UI behavior contracts.\n- [Companion Architecture](./companion-architecture/): Understand the desktop app, pairing model, local-drive access, and native-app editing workflow.\n- [Cross-Cutting Systems](./cross-cutting-systems/): Understand shared logging, localization, and other rules that span more than one app.\n- [Testing and Quality Gates](./testing-and-quality-gates/): Choose the right checks for the change you are making.\n- [Contribution Workflows](./contribution-workflows/): Plan and review changes with the right scope and validation depth.\n- [Security](./security/): Understand dependency automation, vulnerability scanning, and release-artifact integrity.\n- [Release and Versioning](./release-and-versioning/): Handle dependency updates and version metadata safely.\n\n## Use the Right Guide\n\n- Use the Developer Guide when the next question is implementation-facing.\n- Use the [Website Dev Guide](../website-dev-guide/) when the work is on the public website, published docs content, docs tooling, or shared website theme systems.\n- Use the [User Guide](../user-guide/) when the next step belongs to the person using Sambee in normal workflows.\n- Use the [Admin Guide](../admin-guide/) when the next step is deployment, configuration, operations, or escalation.\n\n", "0.9": "+++\ntitle = \"Developer Guide\"\n+++\n\nUse this guide to understand how Sambee is built across the backend, frontend, and companion, work safely in the repository and choose the right contributor workflow, understand the architecture and cross-cutting systems before changing code, and validate changes with the right checks before review or release.\n\n## Start Here if You Want To\n\n- Understand how the browser app, backend, and companion fit together.\n- Find the right place in the repository before changing code.\n- Set up the development environment and use the common contributor workflows.\n- Understand the high-level architecture of the backend, frontend, and companion.\n- Understand deeper contributor rules for preview pipelines, companion trust, or version-sensitive changes.\n- Choose the right validation commands before you open a pull request.\n\n## In This Guide\n\n- [Project Orientation](./project-orientation/): Understand the product boundaries and the repository layout.\n- [Local Development Workflow](./local-development-workflow/): Set up the environment and find the commands you will actually use.\n- [Backend Architecture](./backend-architecture/): Understand the FastAPI service, SMB-facing behavior, and server-side contracts.\n- [Frontend Architecture](./frontend-architecture/): Understand the browser app, page structure, and UI behavior contracts.\n- [Companion Architecture](./companion-architecture/): Understand the desktop app, pairing model, local-drive access, and native-app editing workflow.\n- [Cross-Cutting Systems](./cross-cutting-systems/): Understand shared logging, localization, and other rules that span more than one app.\n- [Testing and Quality Gates](./testing-and-quality-gates/): Choose the right checks for the change you are making.\n- [Contribution Workflows](./contribution-workflows/): Plan and review changes with the right scope and validation depth.\n- [Security](./security/): Understand dependency automation, vulnerability scanning, and release-artifact integrity.\n- [Release and Versioning](./release-and-versioning/): Handle dependency updates and version metadata safely.\n\n## Use the Right Guide\n\n- Use the Developer Guide when the next question is implementation-facing.\n- Use the [Website Dev Guide](../website-dev-guide/) when the work is on the public website, published docs content, docs tooling, or shared website theme systems.\n- Use the [User Guide](../user-guide/) when the next step belongs to the person using Sambee in normal workflows.\n- Use the [Admin Guide](../admin-guide/) when the next step is deployment, configuration, operations, or escalation.\n\n", "1.0": "+++\ntitle = \"Developer Guide\"\n+++\n\nUse this guide to understand how Sambee is built across the backend, frontend, and companion, work safely in the repository and choose the right contributor workflow, understand the architecture and cross-cutting systems before changing code, and validate changes with the right checks before review or release.\n\n## Start Here if You Want To\n\n- Understand how the browser app, backend, and companion fit together.\n- Find the right place in the repository before changing code.\n- Set up the development environment and use the common contributor workflows.\n- Understand the high-level architecture of the backend, frontend, and companion.\n- Understand deeper contributor rules for preview pipelines, companion trust, or version-sensitive changes.\n- Choose the right validation commands before you open a pull request.\n\n## In This Guide\n\n- [Project Orientation](./project-orientation/): Understand the product boundaries and the repository layout.\n- [Local Development Workflow](./local-development-workflow/): Set up the environment and find the commands you will actually use.\n- [Backend Architecture](./backend-architecture/): Understand the FastAPI service, SMB-facing behavior, and server-side contracts.\n- [Frontend Architecture](./frontend-architecture/): Understand the browser app, page structure, and UI behavior contracts.\n- [Companion Architecture](./companion-architecture/): Understand the desktop app, pairing model, local-drive access, and native-app editing workflow.\n- [Cross-Cutting Systems](./cross-cutting-systems/): Understand shared logging, localization, and other rules that span more than one app.\n- [Testing and Quality Gates](./testing-and-quality-gates/): Choose the right checks for the change you are making.\n- [Contribution Workflows](./contribution-workflows/): Plan and review changes with the right scope and validation depth.\n- [Security](./security/): Understand dependency automation, vulnerability scanning, and release-artifact integrity.\n- [Release and Versioning](./release-and-versioning/): Handle dependency updates and version metadata safely.\n\n## Use the Right Guide\n\n- Use the Developer Guide when the next question is implementation-facing.\n- Use the [Website Dev Guide](../website-dev-guide/) when the work is on the public website, published docs content, docs tooling, or shared website theme systems.\n- Use the [User Guide](../user-guide/) when the next step belongs to the person using Sambee in normal workflows.\n- Use the [Admin Guide](../admin-guide/) when the next step is deployment, configuration, operations, or escalation.\n\n", "2.0": "+++\ntitle = \"Developer Guide\"\n+++\n\nUse this guide to understand how Sambee is built across the backend, frontend, and companion, work safely in the repository and choose the right contributor workflow, understand the architecture and cross-cutting systems before changing code, and validate changes with the right checks before review or release.\n\n## Start Here if You Want To\n\n- Understand how the browser app, backend, and companion fit together.\n- Find the right place in the repository before changing code.\n- Set up the development environment and use the common contributor workflows.\n- Understand the high-level architecture of the backend, frontend, and companion.\n- Understand deeper contributor rules for preview pipelines, companion trust, or version-sensitive changes.\n- Choose the right validation commands before you open a pull request.\n\n## In This Guide\n\n- [Project Orientation](./project-orientation/): Understand the product boundaries and the repository layout.\n- [Local Development Workflow](./local-development-workflow/): Set up the environment and find the commands you will actually use.\n- [Backend Architecture](./backend-architecture/): Understand the FastAPI service, SMB-facing behavior, and server-side contracts.\n- [Frontend Architecture](./frontend-architecture/): Understand the browser app, page structure, and UI behavior contracts.\n- [Companion Architecture](./companion-architecture/): Understand the desktop app, pairing model, local-drive access, and native-app editing workflow.\n- [Cross-Cutting Systems](./cross-cutting-systems/): Understand shared logging, localization, and other rules that span more than one app.\n- [Testing and Quality Gates](./testing-and-quality-gates/): Choose the right checks for the change you are making.\n- [Contribution Workflows](./contribution-workflows/): Plan and review changes with the right scope and validation depth.\n- [Security](./security/): Understand dependency automation, vulnerability scanning, and release-artifact integrity.\n- [Release and Versioning](./release-and-versioning/): Handle dependency updates and version metadata safely.\n\n## Use the Right Guide\n\n- Use the Developer Guide when the next question is implementation-facing.\n- Use the [Website Dev Guide](../website-dev-guide/) when the work is on the public website, published docs content, docs tooling, or shared website theme systems.\n- Use the [User Guide](../user-guide/) when the next step belongs to the person using Sambee in normal workflows.\n- Use the [Admin Guide](../admin-guide/) when the next step is deployment, configuration, operations, or escalation.\n\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:developer-guide/project-orientation", "parent_id": "book:developer-guide", "depth": 1, "kind": "section", "label": "project-orientation", "title": "Project Orientation", "path": "developer-guide/project-orientation", "has_children": true, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Project Orientation\"\n+++\n\nStart here when you need the high-level mental model before changing anything.\n\n- [What Sambee Consists Of](./what-sambee-consists-of/): the system boundaries contributors need to preserve\n- [Repository Tour](./repository-tour/): where backend, frontend, companion, and shared repo workflows live\n\nIf you already understand the system boundaries and just need to get running locally, continue to [Local Development Workflow](../local-development-workflow/).\n", "0.8": "+++\ntitle = \"Project Orientation\"\n+++\n\nStart here when you need the high-level mental model before changing anything.\n\n- [What Sambee Consists Of](./what-sambee-consists-of/): the system boundaries contributors need to preserve\n- [Repository Tour](./repository-tour/): where backend, frontend, companion, and shared repo workflows live\n\nIf you already understand the system boundaries and just need to get running locally, continue to [Local Development Workflow](../local-development-workflow/).\n", "0.9": "+++\ntitle = \"Project Orientation\"\n+++\n\nStart here when you need the high-level mental model before changing anything.\n\n- [What Sambee Consists Of](./what-sambee-consists-of/): the system boundaries contributors need to preserve\n- [Repository Tour](./repository-tour/): where backend, frontend, companion, and shared repo workflows live\n\nIf you already understand the system boundaries and just need to get running locally, continue to [Local Development Workflow](../local-development-workflow/).\n", "1.0": "+++\ntitle = \"Project Orientation\"\n+++\n\nStart here when you need the high-level mental model before changing anything.\n\n- [What Sambee Consists Of](./what-sambee-consists-of/): the system boundaries contributors need to preserve\n- [Repository Tour](./repository-tour/): where backend, frontend, companion, and shared repo workflows live\n\nIf you already understand the system boundaries and just need to get running locally, continue to [Local Development Workflow](../local-development-workflow/).\n", "2.0": "+++\ntitle = \"Project Orientation\"\n+++\n\nStart here when you need the high-level mental model before changing anything.\n\n- [What Sambee Consists Of](./what-sambee-consists-of/): the system boundaries contributors need to preserve\n- [Repository Tour](./repository-tour/): where backend, frontend, companion, and shared repo workflows live\n\nIf you already understand the system boundaries and just need to get running locally, continue to [Local Development Workflow](../local-development-workflow/).\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/project-orientation/what-sambee-consists-of", "parent_id": "section:developer-guide/project-orientation", "depth": 2, "kind": "page", "label": "what-sambee-consists-of", "title": "What Sambee Consists Of", "path": "developer-guide/project-orientation/what-sambee-consists-of", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"What Sambee Consists Of\"\n+++\n\nSambee is not a single app with one execution model. It is a coordinated system with separate responsibilities in the browser, on the server, and on the desktop.\n\n## The Major Pieces\n\n| Subsystem | Main responsibility | Where it lives |\n|---|---|---|\n| Browser app | User-facing file browsing, preview, editing UI, and service calls | `frontend/` |\n| Backend service | Authentication, API endpoints, SMB access, server-side file handling, locks, and notifications | `backend/` |\n| Companion app | Native-app editing, local-drive access, pairing, and desktop-local integrations | `companion/` |\n\n## Capability Boundaries Contributors Must Preserve\n\nSambee deliberately separates browser-only workflows from companion-backed workflows.\n\nBrowser-only workflows:\n\n- browsing SMB shares\n- previewing supported content in the browser\n- managing files through the web interface\n- editing Markdown directly in the browser\n\nCompanion-backed workflows:\n\n- browsing local drives on the same machine as the browser\n- opening files in installed native desktop applications\n- returning native-app edits to the source location\n- syncing localization and other browser-to-desktop state where the product requires it\n\nThose boundaries matter because the product makes different trust, runtime, and platform assumptions in each path.\n\n## How a Normal Request Path Splits\n\nFor an SMB-browser workflow:\n\n1. The browser app issues authenticated API calls.\n2. The backend enforces server-side policy and talks to SMB storage.\n3. The browser renders the result.\n\nFor a companion-backed workflow:\n\n1. The browser app still owns the main user workflow.\n2. The companion is discovered or launched locally.\n3. Browser and companion exchange trusted local information through pairing or deep links, depending on the flow.\n4. The backend remains the source of truth for SMB edit workflows, while the companion adds desktop-local capability.\n\n## What This Means for Contributors\n\nWhen you change Sambee, do not treat every feature as interchangeable.\n\n- A frontend-only change can still break a backend contract.\n- A backend change can alter browser behavior, companion behavior, or both.\n- A companion change can affect desktop editing, local drives, and paired browser expectations.\n\nUse the rest of this guide to go deeper into each subsystem rather than trying to keep the whole model in your head at once.\n", "0.8": "+++\ntitle = \"What Sambee Consists Of\"\n+++\n\nSambee is not a single app with one execution model. It is a coordinated system with separate responsibilities in the browser, on the server, and on the desktop.\n\n## The Major Pieces\n\n| Subsystem | Main responsibility | Where it lives |\n|---|---|---|\n| Browser app | User-facing file browsing, preview, editing UI, and service calls | `frontend/` |\n| Backend service | Authentication, API endpoints, SMB access, server-side file handling, locks, and notifications | `backend/` |\n| Companion app | Native-app editing, local-drive access, pairing, and desktop-local integrations | `companion/` |\n\n## Capability Boundaries Contributors Must Preserve\n\nSambee deliberately separates browser-only workflows from companion-backed workflows.\n\nBrowser-only workflows:\n\n- browsing SMB shares\n- previewing supported content in the browser\n- managing files through the web interface\n- editing Markdown directly in the browser\n\nCompanion-backed workflows:\n\n- browsing local drives on the same machine as the browser\n- opening files in installed native desktop applications\n- returning native-app edits to the source location\n- syncing localization and other browser-to-desktop state where the product requires it\n\nThose boundaries matter because the product makes different trust, runtime, and platform assumptions in each path.\n\n## How a Normal Request Path Splits\n\nFor an SMB-browser workflow:\n\n1. The browser app issues authenticated API calls.\n2. The backend enforces server-side policy and talks to SMB storage.\n3. The browser renders the result.\n\nFor a companion-backed workflow:\n\n1. The browser app still owns the main user workflow.\n2. The companion is discovered or launched locally.\n3. Browser and companion exchange trusted local information through pairing or deep links, depending on the flow.\n4. The backend remains the source of truth for SMB edit workflows, while the companion adds desktop-local capability.\n\n## What This Means for Contributors\n\nWhen you change Sambee, do not treat every feature as interchangeable.\n\n- A frontend-only change can still break a backend contract.\n- A backend change can alter browser behavior, companion behavior, or both.\n- A companion change can affect desktop editing, local drives, and paired browser expectations.\n\nUse the rest of this guide to go deeper into each subsystem rather than trying to keep the whole model in your head at once.\n", "0.9": "+++\ntitle = \"What Sambee Consists Of\"\n+++\n\nSambee is not a single app with one execution model. It is a coordinated system with separate responsibilities in the browser, on the server, and on the desktop.\n\n## The Major Pieces\n\n| Subsystem | Main responsibility | Where it lives |\n|---|---|---|\n| Browser app | User-facing file browsing, preview, editing UI, and service calls | `frontend/` |\n| Backend service | Authentication, API endpoints, SMB access, server-side file handling, locks, and notifications | `backend/` |\n| Companion app | Native-app editing, local-drive access, pairing, and desktop-local integrations | `companion/` |\n\n## Capability Boundaries Contributors Must Preserve\n\nSambee deliberately separates browser-only workflows from companion-backed workflows.\n\nBrowser-only workflows:\n\n- browsing SMB shares\n- previewing supported content in the browser\n- managing files through the web interface\n- editing Markdown directly in the browser\n\nCompanion-backed workflows:\n\n- browsing local drives on the same machine as the browser\n- opening files in installed native desktop applications\n- returning native-app edits to the source location\n- syncing localization and other browser-to-desktop state where the product requires it\n\nThose boundaries matter because the product makes different trust, runtime, and platform assumptions in each path.\n\n## How a Normal Request Path Splits\n\nFor an SMB-browser workflow:\n\n1. The browser app issues authenticated API calls.\n2. The backend enforces server-side policy and talks to SMB storage.\n3. The browser renders the result.\n\nFor a companion-backed workflow:\n\n1. The browser app still owns the main user workflow.\n2. The companion is discovered or launched locally.\n3. Browser and companion exchange trusted local information through pairing or deep links, depending on the flow.\n4. The backend remains the source of truth for SMB edit workflows, while the companion adds desktop-local capability.\n\n## What This Means for Contributors\n\nWhen you change Sambee, do not treat every feature as interchangeable.\n\n- A frontend-only change can still break a backend contract.\n- A backend change can alter browser behavior, companion behavior, or both.\n- A companion change can affect desktop editing, local drives, and paired browser expectations.\n\nUse the rest of this guide to go deeper into each subsystem rather than trying to keep the whole model in your head at once.\n", "1.0": "+++\ntitle = \"What Sambee Consists Of\"\n+++\n\nSambee is not a single app with one execution model. It is a coordinated system with separate responsibilities in the browser, on the server, and on the desktop.\n\n## The Major Pieces\n\n| Subsystem | Main responsibility | Where it lives |\n|---|---|---|\n| Browser app | User-facing file browsing, preview, editing UI, and service calls | `frontend/` |\n| Backend service | Authentication, API endpoints, SMB access, server-side file handling, locks, and notifications | `backend/` |\n| Companion app | Native-app editing, local-drive access, pairing, and desktop-local integrations | `companion/` |\n\n## Capability Boundaries Contributors Must Preserve\n\nSambee deliberately separates browser-only workflows from companion-backed workflows.\n\nBrowser-only workflows:\n\n- browsing SMB shares\n- previewing supported content in the browser\n- managing files through the web interface\n- editing Markdown directly in the browser\n\nCompanion-backed workflows:\n\n- browsing local drives on the same machine as the browser\n- opening files in installed native desktop applications\n- returning native-app edits to the source location\n- syncing localization and other browser-to-desktop state where the product requires it\n\nThose boundaries matter because the product makes different trust, runtime, and platform assumptions in each path.\n\n## How a Normal Request Path Splits\n\nFor an SMB-browser workflow:\n\n1. The browser app issues authenticated API calls.\n2. The backend enforces server-side policy and talks to SMB storage.\n3. The browser renders the result.\n\nFor a companion-backed workflow:\n\n1. The browser app still owns the main user workflow.\n2. The companion is discovered or launched locally.\n3. Browser and companion exchange trusted local information through pairing or deep links, depending on the flow.\n4. The backend remains the source of truth for SMB edit workflows, while the companion adds desktop-local capability.\n\n## What This Means for Contributors\n\nWhen you change Sambee, do not treat every feature as interchangeable.\n\n- A frontend-only change can still break a backend contract.\n- A backend change can alter browser behavior, companion behavior, or both.\n- A companion change can affect desktop editing, local drives, and paired browser expectations.\n\nUse the rest of this guide to go deeper into each subsystem rather than trying to keep the whole model in your head at once.\n", "2.0": "+++\ntitle = \"What Sambee Consists Of\"\n+++\n\nSambee is not a single app with one execution model. It is a coordinated system with separate responsibilities in the browser, on the server, and on the desktop.\n\n## The Major Pieces\n\n| Subsystem | Main responsibility | Where it lives |\n|---|---|---|\n| Browser app | User-facing file browsing, preview, editing UI, and service calls | `frontend/` |\n| Backend service | Authentication, API endpoints, SMB access, server-side file handling, locks, and notifications | `backend/` |\n| Companion app | Native-app editing, local-drive access, pairing, and desktop-local integrations | `companion/` |\n\n## Capability Boundaries Contributors Must Preserve\n\nSambee deliberately separates browser-only workflows from companion-backed workflows.\n\nBrowser-only workflows:\n\n- browsing SMB shares\n- previewing supported content in the browser\n- managing files through the web interface\n- editing Markdown directly in the browser\n\nCompanion-backed workflows:\n\n- browsing local drives on the same machine as the browser\n- opening files in installed native desktop applications\n- returning native-app edits to the source location\n- syncing localization and other browser-to-desktop state where the product requires it\n\nThose boundaries matter because the product makes different trust, runtime, and platform assumptions in each path.\n\n## How a Normal Request Path Splits\n\nFor an SMB-browser workflow:\n\n1. The browser app issues authenticated API calls.\n2. The backend enforces server-side policy and talks to SMB storage.\n3. The browser renders the result.\n\nFor a companion-backed workflow:\n\n1. The browser app still owns the main user workflow.\n2. The companion is discovered or launched locally.\n3. Browser and companion exchange trusted local information through pairing or deep links, depending on the flow.\n4. The backend remains the source of truth for SMB edit workflows, while the companion adds desktop-local capability.\n\n## What This Means for Contributors\n\nWhen you change Sambee, do not treat every feature as interchangeable.\n\n- A frontend-only change can still break a backend contract.\n- A backend change can alter browser behavior, companion behavior, or both.\n- A companion change can affect desktop editing, local drives, and paired browser expectations.\n\nUse the rest of this guide to go deeper into each subsystem rather than trying to keep the whole model in your head at once.\n"}, "page_contents": {"0.7": "+++\ntitle = \"What Sambee Consists Of\"\n+++\n\nSambee is not a single app with one execution model. It is a coordinated system with separate responsibilities in the browser, on the server, and on the desktop.\n\n## The Major Pieces\n\n| Subsystem | Main responsibility | Where it lives |\n|---|---|---|\n| Browser app | User-facing file browsing, preview, editing UI, and service calls | `frontend/` |\n| Backend service | Authentication, API endpoints, SMB access, server-side file handling, locks, and notifications | `backend/` |\n| Companion app | Native-app editing, local-drive access, pairing, and desktop-local integrations | `companion/` |\n\n## Capability Boundaries Contributors Must Preserve\n\nSambee deliberately separates browser-only workflows from companion-backed workflows.\n\nBrowser-only workflows:\n\n- browsing SMB shares\n- previewing supported content in the browser\n- managing files through the web interface\n- editing Markdown directly in the browser\n\nCompanion-backed workflows:\n\n- browsing local drives on the same machine as the browser\n- opening files in installed native desktop applications\n- returning native-app edits to the source location\n- syncing localization and other browser-to-desktop state where the product requires it\n\nThose boundaries matter because the product makes different trust, runtime, and platform assumptions in each path.\n\n## How a Normal Request Path Splits\n\nFor an SMB-browser workflow:\n\n1. The browser app issues authenticated API calls.\n2. The backend enforces server-side policy and talks to SMB storage.\n3. The browser renders the result.\n\nFor a companion-backed workflow:\n\n1. The browser app still owns the main user workflow.\n2. The companion is discovered or launched locally.\n3. Browser and companion exchange trusted local information through pairing or deep links, depending on the flow.\n4. The backend remains the source of truth for SMB edit workflows, while the companion adds desktop-local capability.\n\n## What This Means for Contributors\n\nWhen you change Sambee, do not treat every feature as interchangeable.\n\n- A frontend-only change can still break a backend contract.\n- A backend change can alter browser behavior, companion behavior, or both.\n- A companion change can affect desktop editing, local drives, and paired browser expectations.\n\nUse the rest of this guide to go deeper into each subsystem rather than trying to keep the whole model in your head at once.\n", "0.8": "+++\ntitle = \"What Sambee Consists Of\"\n+++\n\nSambee is not a single app with one execution model. It is a coordinated system with separate responsibilities in the browser, on the server, and on the desktop.\n\n## The Major Pieces\n\n| Subsystem | Main responsibility | Where it lives |\n|---|---|---|\n| Browser app | User-facing file browsing, preview, editing UI, and service calls | `frontend/` |\n| Backend service | Authentication, API endpoints, SMB access, server-side file handling, locks, and notifications | `backend/` |\n| Companion app | Native-app editing, local-drive access, pairing, and desktop-local integrations | `companion/` |\n\n## Capability Boundaries Contributors Must Preserve\n\nSambee deliberately separates browser-only workflows from companion-backed workflows.\n\nBrowser-only workflows:\n\n- browsing SMB shares\n- previewing supported content in the browser\n- managing files through the web interface\n- editing Markdown directly in the browser\n\nCompanion-backed workflows:\n\n- browsing local drives on the same machine as the browser\n- opening files in installed native desktop applications\n- returning native-app edits to the source location\n- syncing localization and other browser-to-desktop state where the product requires it\n\nThose boundaries matter because the product makes different trust, runtime, and platform assumptions in each path.\n\n## How a Normal Request Path Splits\n\nFor an SMB-browser workflow:\n\n1. The browser app issues authenticated API calls.\n2. The backend enforces server-side policy and talks to SMB storage.\n3. The browser renders the result.\n\nFor a companion-backed workflow:\n\n1. The browser app still owns the main user workflow.\n2. The companion is discovered or launched locally.\n3. Browser and companion exchange trusted local information through pairing or deep links, depending on the flow.\n4. The backend remains the source of truth for SMB edit workflows, while the companion adds desktop-local capability.\n\n## What This Means for Contributors\n\nWhen you change Sambee, do not treat every feature as interchangeable.\n\n- A frontend-only change can still break a backend contract.\n- A backend change can alter browser behavior, companion behavior, or both.\n- A companion change can affect desktop editing, local drives, and paired browser expectations.\n\nUse the rest of this guide to go deeper into each subsystem rather than trying to keep the whole model in your head at once.\n", "0.9": "+++\ntitle = \"What Sambee Consists Of\"\n+++\n\nSambee is not a single app with one execution model. It is a coordinated system with separate responsibilities in the browser, on the server, and on the desktop.\n\n## The Major Pieces\n\n| Subsystem | Main responsibility | Where it lives |\n|---|---|---|\n| Browser app | User-facing file browsing, preview, editing UI, and service calls | `frontend/` |\n| Backend service | Authentication, API endpoints, SMB access, server-side file handling, locks, and notifications | `backend/` |\n| Companion app | Native-app editing, local-drive access, pairing, and desktop-local integrations | `companion/` |\n\n## Capability Boundaries Contributors Must Preserve\n\nSambee deliberately separates browser-only workflows from companion-backed workflows.\n\nBrowser-only workflows:\n\n- browsing SMB shares\n- previewing supported content in the browser\n- managing files through the web interface\n- editing Markdown directly in the browser\n\nCompanion-backed workflows:\n\n- browsing local drives on the same machine as the browser\n- opening files in installed native desktop applications\n- returning native-app edits to the source location\n- syncing localization and other browser-to-desktop state where the product requires it\n\nThose boundaries matter because the product makes different trust, runtime, and platform assumptions in each path.\n\n## How a Normal Request Path Splits\n\nFor an SMB-browser workflow:\n\n1. The browser app issues authenticated API calls.\n2. The backend enforces server-side policy and talks to SMB storage.\n3. The browser renders the result.\n\nFor a companion-backed workflow:\n\n1. The browser app still owns the main user workflow.\n2. The companion is discovered or launched locally.\n3. Browser and companion exchange trusted local information through pairing or deep links, depending on the flow.\n4. The backend remains the source of truth for SMB edit workflows, while the companion adds desktop-local capability.\n\n## What This Means for Contributors\n\nWhen you change Sambee, do not treat every feature as interchangeable.\n\n- A frontend-only change can still break a backend contract.\n- A backend change can alter browser behavior, companion behavior, or both.\n- A companion change can affect desktop editing, local drives, and paired browser expectations.\n\nUse the rest of this guide to go deeper into each subsystem rather than trying to keep the whole model in your head at once.\n", "1.0": "+++\ntitle = \"What Sambee Consists Of\"\n+++\n\nSambee is not a single app with one execution model. It is a coordinated system with separate responsibilities in the browser, on the server, and on the desktop.\n\n## The Major Pieces\n\n| Subsystem | Main responsibility | Where it lives |\n|---|---|---|\n| Browser app | User-facing file browsing, preview, editing UI, and service calls | `frontend/` |\n| Backend service | Authentication, API endpoints, SMB access, server-side file handling, locks, and notifications | `backend/` |\n| Companion app | Native-app editing, local-drive access, pairing, and desktop-local integrations | `companion/` |\n\n## Capability Boundaries Contributors Must Preserve\n\nSambee deliberately separates browser-only workflows from companion-backed workflows.\n\nBrowser-only workflows:\n\n- browsing SMB shares\n- previewing supported content in the browser\n- managing files through the web interface\n- editing Markdown directly in the browser\n\nCompanion-backed workflows:\n\n- browsing local drives on the same machine as the browser\n- opening files in installed native desktop applications\n- returning native-app edits to the source location\n- syncing localization and other browser-to-desktop state where the product requires it\n\nThose boundaries matter because the product makes different trust, runtime, and platform assumptions in each path.\n\n## How a Normal Request Path Splits\n\nFor an SMB-browser workflow:\n\n1. The browser app issues authenticated API calls.\n2. The backend enforces server-side policy and talks to SMB storage.\n3. The browser renders the result.\n\nFor a companion-backed workflow:\n\n1. The browser app still owns the main user workflow.\n2. The companion is discovered or launched locally.\n3. Browser and companion exchange trusted local information through pairing or deep links, depending on the flow.\n4. The backend remains the source of truth for SMB edit workflows, while the companion adds desktop-local capability.\n\n## What This Means for Contributors\n\nWhen you change Sambee, do not treat every feature as interchangeable.\n\n- A frontend-only change can still break a backend contract.\n- A backend change can alter browser behavior, companion behavior, or both.\n- A companion change can affect desktop editing, local drives, and paired browser expectations.\n\nUse the rest of this guide to go deeper into each subsystem rather than trying to keep the whole model in your head at once.\n", "2.0": "+++\ntitle = \"What Sambee Consists Of\"\n+++\n\nSambee is not a single app with one execution model. It is a coordinated system with separate responsibilities in the browser, on the server, and on the desktop.\n\n## The Major Pieces\n\n| Subsystem | Main responsibility | Where it lives |\n|---|---|---|\n| Browser app | User-facing file browsing, preview, editing UI, and service calls | `frontend/` |\n| Backend service | Authentication, API endpoints, SMB access, server-side file handling, locks, and notifications | `backend/` |\n| Companion app | Native-app editing, local-drive access, pairing, and desktop-local integrations | `companion/` |\n\n## Capability Boundaries Contributors Must Preserve\n\nSambee deliberately separates browser-only workflows from companion-backed workflows.\n\nBrowser-only workflows:\n\n- browsing SMB shares\n- previewing supported content in the browser\n- managing files through the web interface\n- editing Markdown directly in the browser\n\nCompanion-backed workflows:\n\n- browsing local drives on the same machine as the browser\n- opening files in installed native desktop applications\n- returning native-app edits to the source location\n- syncing localization and other browser-to-desktop state where the product requires it\n\nThose boundaries matter because the product makes different trust, runtime, and platform assumptions in each path.\n\n## How a Normal Request Path Splits\n\nFor an SMB-browser workflow:\n\n1. The browser app issues authenticated API calls.\n2. The backend enforces server-side policy and talks to SMB storage.\n3. The browser renders the result.\n\nFor a companion-backed workflow:\n\n1. The browser app still owns the main user workflow.\n2. The companion is discovered or launched locally.\n3. Browser and companion exchange trusted local information through pairing or deep links, depending on the flow.\n4. The backend remains the source of truth for SMB edit workflows, while the companion adds desktop-local capability.\n\n## What This Means for Contributors\n\nWhen you change Sambee, do not treat every feature as interchangeable.\n\n- A frontend-only change can still break a backend contract.\n- A backend change can alter browser behavior, companion behavior, or both.\n- A companion change can affect desktop editing, local drives, and paired browser expectations.\n\nUse the rest of this guide to go deeper into each subsystem rather than trying to keep the whole model in your head at once.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/project-orientation/repository-tour", "parent_id": "section:developer-guide/project-orientation", "depth": 2, "kind": "page", "label": "repository-tour", "title": "Repository Tour", "path": "developer-guide/project-orientation/repository-tour", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Repository Tour\"\n+++\n\nThis repository is organized around product boundaries, not just programming languages.\n\n## Top-Level Areas\n\n| Path | What it contains | Start here when |\n|---|---|---|\n| `backend/` | FastAPI application, models, services, storage code, and backend tests | you are changing API behavior, SMB handling, server-side validation, or edit-lock behavior |\n| `frontend/` | React browser app, UI components, pages, hooks, services, and browser-side tests | you are changing the main web UI or browser behavior |\n| `companion/` | Tauri desktop app with Preact UI and Rust backend | you are changing local-drive access, native-app editing, pairing, or desktop-side behavior |\n| `scripts/` | repo-level helper scripts for dev services, tests, version sync, and setup | you need the supported workflow instead of an ad hoc command |\n\n## Important Root Files\n\nThese files shape contributor workflows even though they are not feature code.\n\n| Path | Why it matters |\n|---|---|\n| `VERSION` | single source of truth for the current release identifier |\n| `config.example.toml` | starting point for local configuration |\n| `config.toml` | active local configuration in development or deployment |\n| `README.md` | high-level product framing |\n| `AGENTS.md` | repository-specific working rules for this environment |\n| `biome.json` | shared formatting and lint configuration for JavaScript and TypeScript work |\n\n## Product-Specific Notes\n\n- `backend/app/` is where the service code lives. Use it when the browser depends on server behavior or when SMB behavior changes.\n- `backend/tests/` holds the backend validation layer. Keep it close to backend behavior changes.\n- `frontend/src/` is the main browser app surface. Pages, services, and UI contracts all converge here.\n- `companion/src/` holds the desktop UI, while `companion/src-tauri/` holds the Rust backend, local API, and deep-link handling.\n## Where to Look First for Common Changes\n\n- Browser workflow change: start in `frontend/`, then confirm the backend or companion contract the UI depends on.\n- SMB behavior change: start in `backend/`, then validate the frontend behavior that consumes it.\n- Native-app editing or local-drive change: start in `companion/`, then review the related browser and backend contract.\n\n## What Not to Do\n\n- Do not treat the repo as three isolated apps. Many changes cross backend, frontend, and companion boundaries.\n- Do not assume lockfiles, version metadata, or generated files are incidental. Several workflows rely on them as reviewed source.\n\nIf you know which area you need, continue to [Local Development Workflow](../../local-development-workflow/) or jump directly to the relevant architecture section.\n", "0.8": "+++\ntitle = \"Repository Tour\"\n+++\n\nThis repository is organized around product boundaries, not just programming languages.\n\n## Top-Level Areas\n\n| Path | What it contains | Start here when |\n|---|---|---|\n| `backend/` | FastAPI application, models, services, storage code, and backend tests | you are changing API behavior, SMB handling, server-side validation, or edit-lock behavior |\n| `frontend/` | React browser app, UI components, pages, hooks, services, and browser-side tests | you are changing the main web UI or browser behavior |\n| `companion/` | Tauri desktop app with Preact UI and Rust backend | you are changing local-drive access, native-app editing, pairing, or desktop-side behavior |\n| `scripts/` | repo-level helper scripts for dev services, tests, version sync, and setup | you need the supported workflow instead of an ad hoc command |\n\n## Important Root Files\n\nThese files shape contributor workflows even though they are not feature code.\n\n| Path | Why it matters |\n|---|---|\n| `VERSION` | single source of truth for the current release identifier |\n| `config.example.toml` | starting point for local configuration |\n| `config.toml` | active local configuration in development or deployment |\n| `README.md` | high-level product framing |\n| `AGENTS.md` | repository-specific working rules for this environment |\n| `biome.json` | shared formatting and lint configuration for JavaScript and TypeScript work |\n\n## Product-Specific Notes\n\n- `backend/app/` is where the service code lives. Use it when the browser depends on server behavior or when SMB behavior changes.\n- `backend/tests/` holds the backend validation layer. Keep it close to backend behavior changes.\n- `frontend/src/` is the main browser app surface. Pages, services, and UI contracts all converge here.\n- `companion/src/` holds the desktop UI, while `companion/src-tauri/` holds the Rust backend, local API, and deep-link handling.\n## Where to Look First for Common Changes\n\n- Browser workflow change: start in `frontend/`, then confirm the backend or companion contract the UI depends on.\n- SMB behavior change: start in `backend/`, then validate the frontend behavior that consumes it.\n- Native-app editing or local-drive change: start in `companion/`, then review the related browser and backend contract.\n\n## What Not to Do\n\n- Do not treat the repo as three isolated apps. Many changes cross backend, frontend, and companion boundaries.\n- Do not assume lockfiles, version metadata, or generated files are incidental. Several workflows rely on them as reviewed source.\n\nIf you know which area you need, continue to [Local Development Workflow](../../local-development-workflow/) or jump directly to the relevant architecture section.\n", "0.9": "+++\ntitle = \"Repository Tour\"\n+++\n\nThis repository is organized around product boundaries, not just programming languages.\n\n## Top-Level Areas\n\n| Path | What it contains | Start here when |\n|---|---|---|\n| `backend/` | FastAPI application, models, services, storage code, and backend tests | you are changing API behavior, SMB handling, server-side validation, or edit-lock behavior |\n| `frontend/` | React browser app, UI components, pages, hooks, services, and browser-side tests | you are changing the main web UI or browser behavior |\n| `companion/` | Tauri desktop app with Preact UI and Rust backend | you are changing local-drive access, native-app editing, pairing, or desktop-side behavior |\n| `scripts/` | repo-level helper scripts for dev services, tests, version sync, and setup | you need the supported workflow instead of an ad hoc command |\n\n## Important Root Files\n\nThese files shape contributor workflows even though they are not feature code.\n\n| Path | Why it matters |\n|---|---|\n| `VERSION` | single source of truth for the current release identifier |\n| `config.example.toml` | starting point for local configuration |\n| `config.toml` | active local configuration in development or deployment |\n| `README.md` | high-level product framing |\n| `AGENTS.md` | repository-specific working rules for this environment |\n| `biome.json` | shared formatting and lint configuration for JavaScript and TypeScript work |\n\n## Product-Specific Notes\n\n- `backend/app/` is where the service code lives. Use it when the browser depends on server behavior or when SMB behavior changes.\n- `backend/tests/` holds the backend validation layer. Keep it close to backend behavior changes.\n- `frontend/src/` is the main browser app surface. Pages, services, and UI contracts all converge here.\n- `companion/src/` holds the desktop UI, while `companion/src-tauri/` holds the Rust backend, local API, and deep-link handling.\n## Where to Look First for Common Changes\n\n- Browser workflow change: start in `frontend/`, then confirm the backend or companion contract the UI depends on.\n- SMB behavior change: start in `backend/`, then validate the frontend behavior that consumes it.\n- Native-app editing or local-drive change: start in `companion/`, then review the related browser and backend contract.\n\n## What Not to Do\n\n- Do not treat the repo as three isolated apps. Many changes cross backend, frontend, and companion boundaries.\n- Do not assume lockfiles, version metadata, or generated files are incidental. Several workflows rely on them as reviewed source.\n\nIf you know which area you need, continue to [Local Development Workflow](../../local-development-workflow/) or jump directly to the relevant architecture section.\n", "1.0": "+++\ntitle = \"Repository Tour\"\n+++\n\nThis repository is organized around product boundaries, not just programming languages.\n\n## Top-Level Areas\n\n| Path | What it contains | Start here when |\n|---|---|---|\n| `backend/` | FastAPI application, models, services, storage code, and backend tests | you are changing API behavior, SMB handling, server-side validation, or edit-lock behavior |\n| `frontend/` | React browser app, UI components, pages, hooks, services, and browser-side tests | you are changing the main web UI or browser behavior |\n| `companion/` | Tauri desktop app with Preact UI and Rust backend | you are changing local-drive access, native-app editing, pairing, or desktop-side behavior |\n| `scripts/` | repo-level helper scripts for dev services, tests, version sync, and setup | you need the supported workflow instead of an ad hoc command |\n\n## Important Root Files\n\nThese files shape contributor workflows even though they are not feature code.\n\n| Path | Why it matters |\n|---|---|\n| `VERSION` | single source of truth for the current release identifier |\n| `config.example.toml` | starting point for local configuration |\n| `config.toml` | active local configuration in development or deployment |\n| `README.md` | high-level product framing |\n| `AGENTS.md` | repository-specific working rules for this environment |\n| `biome.json` | shared formatting and lint configuration for JavaScript and TypeScript work |\n\n## Product-Specific Notes\n\n- `backend/app/` is where the service code lives. Use it when the browser depends on server behavior or when SMB behavior changes.\n- `backend/tests/` holds the backend validation layer. Keep it close to backend behavior changes.\n- `frontend/src/` is the main browser app surface. Pages, services, and UI contracts all converge here.\n- `companion/src/` holds the desktop UI, while `companion/src-tauri/` holds the Rust backend, local API, and deep-link handling.\n## Where to Look First for Common Changes\n\n- Browser workflow change: start in `frontend/`, then confirm the backend or companion contract the UI depends on.\n- SMB behavior change: start in `backend/`, then validate the frontend behavior that consumes it.\n- Native-app editing or local-drive change: start in `companion/`, then review the related browser and backend contract.\n\n## What Not to Do\n\n- Do not treat the repo as three isolated apps. Many changes cross backend, frontend, and companion boundaries.\n- Do not assume lockfiles, version metadata, or generated files are incidental. Several workflows rely on them as reviewed source.\n\nIf you know which area you need, continue to [Local Development Workflow](../../local-development-workflow/) or jump directly to the relevant architecture section.\n", "2.0": "+++\ntitle = \"Repository Tour\"\n+++\n\nThis repository is organized around product boundaries, not just programming languages.\n\n## Top-Level Areas\n\n| Path | What it contains | Start here when |\n|---|---|---|\n| `backend/` | FastAPI application, models, services, storage code, and backend tests | you are changing API behavior, SMB handling, server-side validation, or edit-lock behavior |\n| `frontend/` | React browser app, UI components, pages, hooks, services, and browser-side tests | you are changing the main web UI or browser behavior |\n| `companion/` | Tauri desktop app with Preact UI and Rust backend | you are changing local-drive access, native-app editing, pairing, or desktop-side behavior |\n| `scripts/` | repo-level helper scripts for dev services, tests, version sync, and setup | you need the supported workflow instead of an ad hoc command |\n\n## Important Root Files\n\nThese files shape contributor workflows even though they are not feature code.\n\n| Path | Why it matters |\n|---|---|\n| `VERSION` | single source of truth for the current release identifier |\n| `config.example.toml` | starting point for local configuration |\n| `config.toml` | active local configuration in development or deployment |\n| `README.md` | high-level product framing |\n| `AGENTS.md` | repository-specific working rules for this environment |\n| `biome.json` | shared formatting and lint configuration for JavaScript and TypeScript work |\n\n## Product-Specific Notes\n\n- `backend/app/` is where the service code lives. Use it when the browser depends on server behavior or when SMB behavior changes.\n- `backend/tests/` holds the backend validation layer. Keep it close to backend behavior changes.\n- `frontend/src/` is the main browser app surface. Pages, services, and UI contracts all converge here.\n- `companion/src/` holds the desktop UI, while `companion/src-tauri/` holds the Rust backend, local API, and deep-link handling.\n## Where to Look First for Common Changes\n\n- Browser workflow change: start in `frontend/`, then confirm the backend or companion contract the UI depends on.\n- SMB behavior change: start in `backend/`, then validate the frontend behavior that consumes it.\n- Native-app editing or local-drive change: start in `companion/`, then review the related browser and backend contract.\n\n## What Not to Do\n\n- Do not treat the repo as three isolated apps. Many changes cross backend, frontend, and companion boundaries.\n- Do not assume lockfiles, version metadata, or generated files are incidental. Several workflows rely on them as reviewed source.\n\nIf you know which area you need, continue to [Local Development Workflow](../../local-development-workflow/) or jump directly to the relevant architecture section.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Repository Tour\"\n+++\n\nThis repository is organized around product boundaries, not just programming languages.\n\n## Top-Level Areas\n\n| Path | What it contains | Start here when |\n|---|---|---|\n| `backend/` | FastAPI application, models, services, storage code, and backend tests | you are changing API behavior, SMB handling, server-side validation, or edit-lock behavior |\n| `frontend/` | React browser app, UI components, pages, hooks, services, and browser-side tests | you are changing the main web UI or browser behavior |\n| `companion/` | Tauri desktop app with Preact UI and Rust backend | you are changing local-drive access, native-app editing, pairing, or desktop-side behavior |\n| `scripts/` | repo-level helper scripts for dev services, tests, version sync, and setup | you need the supported workflow instead of an ad hoc command |\n\n## Important Root Files\n\nThese files shape contributor workflows even though they are not feature code.\n\n| Path | Why it matters |\n|---|---|\n| `VERSION` | single source of truth for the current release identifier |\n| `config.example.toml` | starting point for local configuration |\n| `config.toml` | active local configuration in development or deployment |\n| `README.md` | high-level product framing |\n| `AGENTS.md` | repository-specific working rules for this environment |\n| `biome.json` | shared formatting and lint configuration for JavaScript and TypeScript work |\n\n## Product-Specific Notes\n\n- `backend/app/` is where the service code lives. Use it when the browser depends on server behavior or when SMB behavior changes.\n- `backend/tests/` holds the backend validation layer. Keep it close to backend behavior changes.\n- `frontend/src/` is the main browser app surface. Pages, services, and UI contracts all converge here.\n- `companion/src/` holds the desktop UI, while `companion/src-tauri/` holds the Rust backend, local API, and deep-link handling.\n## Where to Look First for Common Changes\n\n- Browser workflow change: start in `frontend/`, then confirm the backend or companion contract the UI depends on.\n- SMB behavior change: start in `backend/`, then validate the frontend behavior that consumes it.\n- Native-app editing or local-drive change: start in `companion/`, then review the related browser and backend contract.\n\n## What Not to Do\n\n- Do not treat the repo as three isolated apps. Many changes cross backend, frontend, and companion boundaries.\n- Do not assume lockfiles, version metadata, or generated files are incidental. Several workflows rely on them as reviewed source.\n\nIf you know which area you need, continue to [Local Development Workflow](../../local-development-workflow/) or jump directly to the relevant architecture section.\n", "0.8": "+++\ntitle = \"Repository Tour\"\n+++\n\nThis repository is organized around product boundaries, not just programming languages.\n\n## Top-Level Areas\n\n| Path | What it contains | Start here when |\n|---|---|---|\n| `backend/` | FastAPI application, models, services, storage code, and backend tests | you are changing API behavior, SMB handling, server-side validation, or edit-lock behavior |\n| `frontend/` | React browser app, UI components, pages, hooks, services, and browser-side tests | you are changing the main web UI or browser behavior |\n| `companion/` | Tauri desktop app with Preact UI and Rust backend | you are changing local-drive access, native-app editing, pairing, or desktop-side behavior |\n| `scripts/` | repo-level helper scripts for dev services, tests, version sync, and setup | you need the supported workflow instead of an ad hoc command |\n\n## Important Root Files\n\nThese files shape contributor workflows even though they are not feature code.\n\n| Path | Why it matters |\n|---|---|\n| `VERSION` | single source of truth for the current release identifier |\n| `config.example.toml` | starting point for local configuration |\n| `config.toml` | active local configuration in development or deployment |\n| `README.md` | high-level product framing |\n| `AGENTS.md` | repository-specific working rules for this environment |\n| `biome.json` | shared formatting and lint configuration for JavaScript and TypeScript work |\n\n## Product-Specific Notes\n\n- `backend/app/` is where the service code lives. Use it when the browser depends on server behavior or when SMB behavior changes.\n- `backend/tests/` holds the backend validation layer. Keep it close to backend behavior changes.\n- `frontend/src/` is the main browser app surface. Pages, services, and UI contracts all converge here.\n- `companion/src/` holds the desktop UI, while `companion/src-tauri/` holds the Rust backend, local API, and deep-link handling.\n## Where to Look First for Common Changes\n\n- Browser workflow change: start in `frontend/`, then confirm the backend or companion contract the UI depends on.\n- SMB behavior change: start in `backend/`, then validate the frontend behavior that consumes it.\n- Native-app editing or local-drive change: start in `companion/`, then review the related browser and backend contract.\n\n## What Not to Do\n\n- Do not treat the repo as three isolated apps. Many changes cross backend, frontend, and companion boundaries.\n- Do not assume lockfiles, version metadata, or generated files are incidental. Several workflows rely on them as reviewed source.\n\nIf you know which area you need, continue to [Local Development Workflow](../../local-development-workflow/) or jump directly to the relevant architecture section.\n", "0.9": "+++\ntitle = \"Repository Tour\"\n+++\n\nThis repository is organized around product boundaries, not just programming languages.\n\n## Top-Level Areas\n\n| Path | What it contains | Start here when |\n|---|---|---|\n| `backend/` | FastAPI application, models, services, storage code, and backend tests | you are changing API behavior, SMB handling, server-side validation, or edit-lock behavior |\n| `frontend/` | React browser app, UI components, pages, hooks, services, and browser-side tests | you are changing the main web UI or browser behavior |\n| `companion/` | Tauri desktop app with Preact UI and Rust backend | you are changing local-drive access, native-app editing, pairing, or desktop-side behavior |\n| `scripts/` | repo-level helper scripts for dev services, tests, version sync, and setup | you need the supported workflow instead of an ad hoc command |\n\n## Important Root Files\n\nThese files shape contributor workflows even though they are not feature code.\n\n| Path | Why it matters |\n|---|---|\n| `VERSION` | single source of truth for the current release identifier |\n| `config.example.toml` | starting point for local configuration |\n| `config.toml` | active local configuration in development or deployment |\n| `README.md` | high-level product framing |\n| `AGENTS.md` | repository-specific working rules for this environment |\n| `biome.json` | shared formatting and lint configuration for JavaScript and TypeScript work |\n\n## Product-Specific Notes\n\n- `backend/app/` is where the service code lives. Use it when the browser depends on server behavior or when SMB behavior changes.\n- `backend/tests/` holds the backend validation layer. Keep it close to backend behavior changes.\n- `frontend/src/` is the main browser app surface. Pages, services, and UI contracts all converge here.\n- `companion/src/` holds the desktop UI, while `companion/src-tauri/` holds the Rust backend, local API, and deep-link handling.\n## Where to Look First for Common Changes\n\n- Browser workflow change: start in `frontend/`, then confirm the backend or companion contract the UI depends on.\n- SMB behavior change: start in `backend/`, then validate the frontend behavior that consumes it.\n- Native-app editing or local-drive change: start in `companion/`, then review the related browser and backend contract.\n\n## What Not to Do\n\n- Do not treat the repo as three isolated apps. Many changes cross backend, frontend, and companion boundaries.\n- Do not assume lockfiles, version metadata, or generated files are incidental. Several workflows rely on them as reviewed source.\n\nIf you know which area you need, continue to [Local Development Workflow](../../local-development-workflow/) or jump directly to the relevant architecture section.\n", "1.0": "+++\ntitle = \"Repository Tour\"\n+++\n\nThis repository is organized around product boundaries, not just programming languages.\n\n## Top-Level Areas\n\n| Path | What it contains | Start here when |\n|---|---|---|\n| `backend/` | FastAPI application, models, services, storage code, and backend tests | you are changing API behavior, SMB handling, server-side validation, or edit-lock behavior |\n| `frontend/` | React browser app, UI components, pages, hooks, services, and browser-side tests | you are changing the main web UI or browser behavior |\n| `companion/` | Tauri desktop app with Preact UI and Rust backend | you are changing local-drive access, native-app editing, pairing, or desktop-side behavior |\n| `scripts/` | repo-level helper scripts for dev services, tests, version sync, and setup | you need the supported workflow instead of an ad hoc command |\n\n## Important Root Files\n\nThese files shape contributor workflows even though they are not feature code.\n\n| Path | Why it matters |\n|---|---|\n| `VERSION` | single source of truth for the current release identifier |\n| `config.example.toml` | starting point for local configuration |\n| `config.toml` | active local configuration in development or deployment |\n| `README.md` | high-level product framing |\n| `AGENTS.md` | repository-specific working rules for this environment |\n| `biome.json` | shared formatting and lint configuration for JavaScript and TypeScript work |\n\n## Product-Specific Notes\n\n- `backend/app/` is where the service code lives. Use it when the browser depends on server behavior or when SMB behavior changes.\n- `backend/tests/` holds the backend validation layer. Keep it close to backend behavior changes.\n- `frontend/src/` is the main browser app surface. Pages, services, and UI contracts all converge here.\n- `companion/src/` holds the desktop UI, while `companion/src-tauri/` holds the Rust backend, local API, and deep-link handling.\n## Where to Look First for Common Changes\n\n- Browser workflow change: start in `frontend/`, then confirm the backend or companion contract the UI depends on.\n- SMB behavior change: start in `backend/`, then validate the frontend behavior that consumes it.\n- Native-app editing or local-drive change: start in `companion/`, then review the related browser and backend contract.\n\n## What Not to Do\n\n- Do not treat the repo as three isolated apps. Many changes cross backend, frontend, and companion boundaries.\n- Do not assume lockfiles, version metadata, or generated files are incidental. Several workflows rely on them as reviewed source.\n\nIf you know which area you need, continue to [Local Development Workflow](../../local-development-workflow/) or jump directly to the relevant architecture section.\n", "2.0": "+++\ntitle = \"Repository Tour\"\n+++\n\nThis repository is organized around product boundaries, not just programming languages.\n\n## Top-Level Areas\n\n| Path | What it contains | Start here when |\n|---|---|---|\n| `backend/` | FastAPI application, models, services, storage code, and backend tests | you are changing API behavior, SMB handling, server-side validation, or edit-lock behavior |\n| `frontend/` | React browser app, UI components, pages, hooks, services, and browser-side tests | you are changing the main web UI or browser behavior |\n| `companion/` | Tauri desktop app with Preact UI and Rust backend | you are changing local-drive access, native-app editing, pairing, or desktop-side behavior |\n| `scripts/` | repo-level helper scripts for dev services, tests, version sync, and setup | you need the supported workflow instead of an ad hoc command |\n\n## Important Root Files\n\nThese files shape contributor workflows even though they are not feature code.\n\n| Path | Why it matters |\n|---|---|\n| `VERSION` | single source of truth for the current release identifier |\n| `config.example.toml` | starting point for local configuration |\n| `config.toml` | active local configuration in development or deployment |\n| `README.md` | high-level product framing |\n| `AGENTS.md` | repository-specific working rules for this environment |\n| `biome.json` | shared formatting and lint configuration for JavaScript and TypeScript work |\n\n## Product-Specific Notes\n\n- `backend/app/` is where the service code lives. Use it when the browser depends on server behavior or when SMB behavior changes.\n- `backend/tests/` holds the backend validation layer. Keep it close to backend behavior changes.\n- `frontend/src/` is the main browser app surface. Pages, services, and UI contracts all converge here.\n- `companion/src/` holds the desktop UI, while `companion/src-tauri/` holds the Rust backend, local API, and deep-link handling.\n## Where to Look First for Common Changes\n\n- Browser workflow change: start in `frontend/`, then confirm the backend or companion contract the UI depends on.\n- SMB behavior change: start in `backend/`, then validate the frontend behavior that consumes it.\n- Native-app editing or local-drive change: start in `companion/`, then review the related browser and backend contract.\n\n## What Not to Do\n\n- Do not treat the repo as three isolated apps. Many changes cross backend, frontend, and companion boundaries.\n- Do not assume lockfiles, version metadata, or generated files are incidental. Several workflows rely on them as reviewed source.\n\nIf you know which area you need, continue to [Local Development Workflow](../../local-development-workflow/) or jump directly to the relevant architecture section.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:developer-guide/local-development-workflow", "parent_id": "book:developer-guide", "depth": 1, "kind": "section", "label": "local-development-workflow", "title": "Local Development Workflow", "path": "developer-guide/local-development-workflow", "has_children": true, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Local Development Workflow\"\n+++\n\nThis section is the contributor entry point for getting Sambee running locally and validating your changes.\n\nStart with:\n\n- [Set up the Development Environment](./set-up-the-development-environment/)\n- [Common Task Commands](./common-task-commands/)\n\nIf you already have the repo running locally and want subsystem context, continue to [Backend Architecture](../backend-architecture/), [Frontend Architecture](../frontend-architecture/), or [Companion Architecture](../companion-architecture/).\n", "0.8": "+++\ntitle = \"Local Development Workflow\"\n+++\n\nThis section is the contributor entry point for getting Sambee running locally and validating your changes.\n\nStart with:\n\n- [Set up the Development Environment](./set-up-the-development-environment/)\n- [Common Task Commands](./common-task-commands/)\n\nIf you already have the repo running locally and want subsystem context, continue to [Backend Architecture](../backend-architecture/), [Frontend Architecture](../frontend-architecture/), or [Companion Architecture](../companion-architecture/).\n", "0.9": "+++\ntitle = \"Local Development Workflow\"\n+++\n\nThis section is the contributor entry point for getting Sambee running locally and validating your changes.\n\nStart with:\n\n- [Set up the Development Environment](./set-up-the-development-environment/)\n- [Common Task Commands](./common-task-commands/)\n\nIf you already have the repo running locally and want subsystem context, continue to [Backend Architecture](../backend-architecture/), [Frontend Architecture](../frontend-architecture/), or [Companion Architecture](../companion-architecture/).\n", "1.0": "+++\ntitle = \"Local Development Workflow\"\n+++\n\nThis section is the contributor entry point for getting Sambee running locally and validating your changes.\n\nStart with:\n\n- [Set up the Development Environment](./set-up-the-development-environment/)\n- [Common Task Commands](./common-task-commands/)\n\nIf you already have the repo running locally and want subsystem context, continue to [Backend Architecture](../backend-architecture/), [Frontend Architecture](../frontend-architecture/), or [Companion Architecture](../companion-architecture/).\n", "2.0": "+++\ntitle = \"Local Development Workflow\"\n+++\n\nThis section is the contributor entry point for getting Sambee running locally and validating your changes.\n\nStart with:\n\n- [Set up the Development Environment](./set-up-the-development-environment/)\n- [Common Task Commands](./common-task-commands/)\n\nIf you already have the repo running locally and want subsystem context, continue to [Backend Architecture](../backend-architecture/), [Frontend Architecture](../frontend-architecture/), or [Companion Architecture](../companion-architecture/).\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/local-development-workflow/set-up-the-development-environment", "parent_id": "section:developer-guide/local-development-workflow", "depth": 2, "kind": "page", "label": "set-up-the-development-environment", "title": "Set Up The Development Environment", "path": "developer-guide/local-development-workflow/set-up-the-development-environment", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "branched", "source_version": "0.7", "diff_added": 7, "diff_removed": 0}, "0.9": {"state": "branched", "source_version": "0.8", "diff_added": 13, "diff_removed": 2}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "inherited", "source_version": "0.9"}}, "content_versions": {"0.7": "+++\ntitle = \"Set up the Development Environment\"\n+++\n\nThe supported contributor path is the repository dev container.\n\n## Preferred Setup Path\n\nThe project is designed to be opened in VS Code with Dev Containers.\n\nBaseline assumptions from the maintained setup:\n\n- Python is pinned to the reviewed `3.13.12` baseline.\n- Node and npm are available for frontend and companion work.\n- Rust tooling is available for companion development.\n- post-create setup installs reviewed dependencies, initializes local state, and prepares default config where needed.\n\n## First-Time Setup\n\n1. Open the repository in VS Code.\n2. Reopen in the dev container when prompted.\n3. Let the post-create setup complete.\n\nThe standard setup performs these tasks automatically:\n\n- configures Git hooks used by the repository workflow\n- installs backend dependencies from the hashed lockfiles\n- installs Node dependencies from the committed lockfiles\n- installs `pip-audit` and `cargo-audit` at the pinned versions used in CI\n- initializes the local database\n- creates a default `config.toml` if one is missing\n\nThe Git-hook setup matters more than it first appears.\n\n- the repo uses hooks from `.githooks/`\n- those hooks keep `GIT_COMMIT` aligned after commits and checkouts\n- they preserve the repository's Git LFS hook integration\n- they block pushes of `wip/*` branches\n\nIf you work outside the dev container, run:\n\n```bash\n./scripts/setup-git-hooks\n```\n\n## Local Service URLs\n\nIn the standard development setup, the main services are:\n\n- frontend: `http://localhost:3000`\n- backend: `http://localhost:8000`\n\nThe backend and frontend dev servers are usually started automatically by the workspace tasks.\n\n## Dependency Trust Rules\n\nContributors are expected to use the reviewed dependency workflow rather than ad hoc installs.\n\n- use `npm ci` in `frontend/`, `companion/`, and `website/` for routine installs\n- use the backend lockfile workflow instead of floating Python installs\n- treat `requirements*.txt`, lockfiles, and version metadata as reviewed source, not disposable setup noise\n- keep Tauri JavaScript packages and Rust crates aligned when companion dependencies move\n- treat Python runtime upgrades and high-risk frontend ecosystem upgrades as coordinated manual changes\n\n## Configuration Expectations\n\nLocal development depends on configuration, but the repo is designed to create a sane default local configuration automatically.\n\n- `config.example.toml` is the template\n- `config.toml` is the active local configuration\n- the backend startup workflow creates a default config with secure keys if one is missing\n\nDo not assume production deployment rules and local development rules are identical. The Admin Guide covers deployment-specific setup.\n\n## When to Leave the Happy Path\n\nUse the default container-based workflow unless you have a specific reason not to.\n\n- If your issue is environment-specific, fix the supported workflow first.\n- If you change tooling or dependencies, expect to update the corresponding reviewed inputs and rerun the relevant validation commands.\n- If you change version metadata, treat `VERSION` and the sync workflow as part of the change.\n\n## Common Setup Failures\n\nIf startup fails immediately after opening the dev container, start with the supported workflow rather than ad hoc fixes.\n\nCommon cases:\n\n- missing `config.toml`: the backend startup workflow should create a default config automatically\n- frontend `vite: not found` or `node_modules` permission failures: remove the broken install and rerun `npm ci` in `frontend/`\n- service startup confusion: backend and frontend dev servers are usually started by workspace tasks, so check task state before assuming the app itself is broken\n\nOnce the environment is ready, continue to [Common Task Commands](../common-task-commands/).\n", "0.8": "+++\ntitle = \"Set up the Development Environment\"\n+++\n\nThe supported contributor path is the repository dev container.\n\n## Preferred Setup Path\n\nThe project is designed to be opened in VS Code with Dev Containers.\n\nBaseline assumptions from the maintained setup:\n\n- Python is pinned to the reviewed `3.13.12` baseline.\n- Node and npm are available for frontend and companion work.\n- Rust tooling is available for companion development.\n- post-create setup installs reviewed dependencies, initializes local state, and prepares default config where needed.\n\n## First-Time Setup\n\n1. Open the repository in VS Code.\n2. Reopen in the dev container when prompted.\n3. Let the post-create setup complete.\n\nThe standard setup performs these tasks automatically:\n\n- configures Git hooks used by the repository workflow\n- installs backend dependencies from the hashed lockfiles\n- installs Node dependencies from the committed lockfiles\n- installs `pip-audit` and `cargo-audit` at the pinned versions used in CI\n- initializes the local database\n- creates a default `config.toml` if one is missing\n\nThe Git-hook setup matters more than it first appears.\n\n- the repo uses hooks from `.githooks/`\n- those hooks keep `GIT_COMMIT` aligned after commits and checkouts\n- they preserve the repository's Git LFS hook integration\n- they block pushes of `wip/*` branches\n- they refresh the committed docs structure report automatically when staged docs inputs affect it\n\nIf you work outside the dev container, run:\n\n```bash\n./scripts/setup-git-hooks\n```\n\nWhen you want to refresh docs-derived artifacts manually, use the workspace task `Website: Refresh Docs Derived Artifacts` or run:\n\n```bash\npython3 scripts/update-docs-derived-artifacts.py\n```\n\n## Local Service URLs\n\nIn the standard development setup, the main services are:\n\n- frontend: `http://localhost:3000`\n- backend: `http://localhost:8000`\n\nThe backend and frontend dev servers are usually started automatically by the workspace tasks.\n\n## Dependency Trust Rules\n\nContributors are expected to use the reviewed dependency workflow rather than ad hoc installs.\n\n- use `npm ci` in `frontend/`, `companion/`, and `website/` for routine installs\n- use the backend lockfile workflow instead of floating Python installs\n- treat `requirements*.txt`, lockfiles, and version metadata as reviewed source, not disposable setup noise\n- keep Tauri JavaScript packages and Rust crates aligned when companion dependencies move\n- treat Python runtime upgrades and high-risk frontend ecosystem upgrades as coordinated manual changes\n\n## Configuration Expectations\n\nLocal development depends on configuration, but the repo is designed to create a sane default local configuration automatically.\n\n- `config.example.toml` is the template\n- `config.toml` is the active local configuration\n- the backend startup workflow creates a default config with secure keys if one is missing\n\nDo not assume production deployment rules and local development rules are identical. The Admin Guide covers deployment-specific setup.\n\n## When to Leave the Happy Path\n\nUse the default container-based workflow unless you have a specific reason not to.\n\n- If your issue is environment-specific, fix the supported workflow first.\n- If you change tooling or dependencies, expect to update the corresponding reviewed inputs and rerun the relevant validation commands.\n- If you change version metadata, treat `VERSION` and the sync workflow as part of the change.\n\n## Common Setup Failures\n\nIf startup fails immediately after opening the dev container, start with the supported workflow rather than ad hoc fixes.\n\nCommon cases:\n\n- missing `config.toml`: the backend startup workflow should create a default config automatically\n- frontend `vite: not found` or `node_modules` permission failures: remove the broken install and rerun `npm ci` in `frontend/`\n- service startup confusion: backend and frontend dev servers are usually started by workspace tasks, so check task state before assuming the app itself is broken\n\nOnce the environment is ready, continue to [Common Task Commands](../common-task-commands/).", "0.9": "+++\ntitle = \"Set up the Development Environment\"\n+++\n\nThe supported contributor path is the repository dev container.\n\n## Preferred Setup Path\n\nThe project is designed to be opened in VS Code with Dev Containers.\n\nBaseline assumptions from the maintained setup:\n\n- The dev container and production image inherit the same pinned Python runtime base from the root `Dockerfile`.\n- Node and npm are available for frontend and companion work.\n- Rust tooling is available for companion development.\n- post-create setup installs reviewed dependencies, initializes local state, and prepares default config where needed.\n\n### Runtime Package Refreshes\n\nThe shared runtime base refreshes Debian packages, including SQLite, before it installs the runtime dependencies. Production and CI image builds use a unique refresh key, so each build checks the current Debian packages instead of reusing a cached package-upgrade layer.\n\nLocal Dev Containers can reuse Docker's build cache. Use **Dev Containers: Rebuild Container Without Cache** when you need the current available Debian packages locally. The runtime's Python, SQLite module, and `libsqlite3-0` package versions are reported by Docker image validation in CI.\n\nIndependent builds made on different days can resolve different Debian security updates. This is intentional: the shared base controls the package policy and Python runtime, while regular rebuilds keep native packages current without maintaining a separate internal base-image release process.\n\n## First-Time Setup\n\n1. Open the repository in VS Code.\n2. Reopen in the dev container when prompted.\n3. Let the post-create setup complete.\n\nThe standard setup performs these tasks automatically:\n\n- configures Git hooks used by the repository workflow\n- installs backend dependencies from the hashed lockfiles\n- installs Node dependencies from the committed lockfiles\n- installs `pip-audit` and `cargo-audit` at the pinned versions used in CI\n- initializes the local database\n- creates a default `config.toml` if one is missing\n\nBackend tools run from `backend/.venv`. VS Code selects that interpreter, and the backend workspace tasks use it explicitly. Use `backend/.venv/bin/python -m \u003ctool\u003e` for manual backend commands.\n\nThe Git-hook setup matters more than it first appears.\n\n- the repo uses hooks from `.githooks/`\n- those hooks keep `GIT_COMMIT` aligned after commits and checkouts\n- they preserve the repository's Git LFS hook integration\n- they block pushes of `wip/*` branches\n- they refresh the committed docs structure report automatically when staged docs inputs affect it\n\nIf you work outside the dev container, run:\n\n```bash\n./scripts/setup-git-hooks\n```\n\nWhen you want to refresh docs-derived artifacts manually, use the workspace task `Website: Refresh Docs Derived Artifacts` or run:\n\n```bash\npython3 scripts/update-docs-derived-artifacts.py\n```\n\n## Local Service URLs\n\nIn the standard development setup, the main services are:\n\n- frontend: `http://localhost:3000`\n- backend: `http://localhost:8000`\n\nThe backend and frontend dev servers are usually started automatically by the workspace tasks.\n\n## Dependency Trust Rules\n\nContributors are expected to use the reviewed dependency workflow rather than ad hoc installs.\n\n- use `npm ci` in `frontend/`, `companion/`, and `website/` for routine installs\n- use the backend lockfile workflow instead of floating Python installs\n- treat `requirements*.txt`, lockfiles, and version metadata as reviewed source, not disposable setup noise\n- keep Tauri JavaScript packages and Rust crates aligned when companion dependencies move\n- review Dependabot Python runtime image updates with the Docker target validation results\n- treat high-risk frontend ecosystem upgrades as coordinated manual changes\n\n## Configuration Expectations\n\nLocal development depends on configuration, but the repo is designed to create a sane default local configuration automatically.\n\n- `config.example.toml` is the template\n- `config.toml` is the active local configuration\n- the backend startup workflow creates a default config with secure keys if one is missing\n\nDo not assume production deployment rules and local development rules are identical. The Admin Guide covers deployment-specific setup.\n\n## When to Leave the Happy Path\n\nUse the default container-based workflow unless you have a specific reason not to.\n\n- If your issue is environment-specific, fix the supported workflow first.\n- If you change tooling or dependencies, expect to update the corresponding reviewed inputs and rerun the relevant validation commands.\n- If you change version metadata, treat `VERSION` and the sync workflow as part of the change.\n\n## Common Setup Failures\n\nIf startup fails immediately after opening the dev container, start with the supported workflow rather than ad hoc fixes.\n\nCommon cases:\n\n- missing `config.toml`: the backend startup workflow should create a default config automatically\n- frontend `vite: not found` or `node_modules` permission failures: remove the broken install and rerun `npm ci` in `frontend/`\n- service startup confusion: backend and frontend dev servers are usually started by workspace tasks, so check task state before assuming the app itself is broken\n\nOnce the environment is ready, continue to [Common Task Commands](../common-task-commands/).\n", "1.0": "+++\ntitle = \"Set up the Development Environment\"\n+++\n\nThe supported contributor path is the repository dev container.\n\n## Preferred Setup Path\n\nThe project is designed to be opened in VS Code with Dev Containers.\n\nBaseline assumptions from the maintained setup:\n\n- The dev container and production image inherit the same pinned Python runtime base from the root `Dockerfile`.\n- Node and npm are available for frontend and companion work.\n- Rust tooling is available for companion development.\n- post-create setup installs reviewed dependencies, initializes local state, and prepares default config where needed.\n\n### Runtime Package Refreshes\n\nThe shared runtime base refreshes Debian packages, including SQLite, before it installs the runtime dependencies. Production and CI image builds use a unique refresh key, so each build checks the current Debian packages instead of reusing a cached package-upgrade layer.\n\nLocal Dev Containers can reuse Docker's build cache. Use **Dev Containers: Rebuild Container Without Cache** when you need the current available Debian packages locally. The runtime's Python, SQLite module, and `libsqlite3-0` package versions are reported by Docker image validation in CI.\n\nIndependent builds made on different days can resolve different Debian security updates. This is intentional: the shared base controls the package policy and Python runtime, while regular rebuilds keep native packages current without maintaining a separate internal base-image release process.\n\n## First-Time Setup\n\n1. Open the repository in VS Code.\n2. Reopen in the dev container when prompted.\n3. Let the post-create setup complete.\n\nThe standard setup performs these tasks automatically:\n\n- configures Git hooks used by the repository workflow\n- installs backend dependencies from the hashed lockfiles\n- installs Node dependencies from the committed lockfiles\n- installs `pip-audit` and `cargo-audit` at the pinned versions used in CI\n- initializes the local database\n- creates a default `config.toml` if one is missing\n\nBackend tools run from `backend/.venv`. VS Code selects that interpreter, and the backend workspace tasks use it explicitly. Use `backend/.venv/bin/python -m \u003ctool\u003e` for manual backend commands.\n\nThe Git-hook setup matters more than it first appears.\n\n- the repo uses hooks from `.githooks/`\n- those hooks keep `GIT_COMMIT` aligned after commits and checkouts\n- they preserve the repository's Git LFS hook integration\n- they block pushes of `wip/*` branches\n- they refresh the committed docs structure report automatically when staged docs inputs affect it\n\nIf you work outside the dev container, run:\n\n```bash\n./scripts/setup-git-hooks\n```\n\nWhen you want to refresh docs-derived artifacts manually, use the workspace task `Website: Refresh Docs Derived Artifacts` or run:\n\n```bash\npython3 scripts/update-docs-derived-artifacts.py\n```\n\n## Local Service URLs\n\nIn the standard development setup, the main services are:\n\n- frontend: `http://localhost:3000`\n- backend: `http://localhost:8000`\n\nThe backend and frontend dev servers are usually started automatically by the workspace tasks.\n\n## Dependency Trust Rules\n\nContributors are expected to use the reviewed dependency workflow rather than ad hoc installs.\n\n- use `npm ci` in `frontend/`, `companion/`, and `website/` for routine installs\n- use the backend lockfile workflow instead of floating Python installs\n- treat `requirements*.txt`, lockfiles, and version metadata as reviewed source, not disposable setup noise\n- keep Tauri JavaScript packages and Rust crates aligned when companion dependencies move\n- review Dependabot Python runtime image updates with the Docker target validation results\n- treat high-risk frontend ecosystem upgrades as coordinated manual changes\n\n## Configuration Expectations\n\nLocal development depends on configuration, but the repo is designed to create a sane default local configuration automatically.\n\n- `config.example.toml` is the template\n- `config.toml` is the active local configuration\n- the backend startup workflow creates a default config with secure keys if one is missing\n\nDo not assume production deployment rules and local development rules are identical. The Admin Guide covers deployment-specific setup.\n\n## When to Leave the Happy Path\n\nUse the default container-based workflow unless you have a specific reason not to.\n\n- If your issue is environment-specific, fix the supported workflow first.\n- If you change tooling or dependencies, expect to update the corresponding reviewed inputs and rerun the relevant validation commands.\n- If you change version metadata, treat `VERSION` and the sync workflow as part of the change.\n\n## Common Setup Failures\n\nIf startup fails immediately after opening the dev container, start with the supported workflow rather than ad hoc fixes.\n\nCommon cases:\n\n- missing `config.toml`: the backend startup workflow should create a default config automatically\n- frontend `vite: not found` or `node_modules` permission failures: remove the broken install and rerun `npm ci` in `frontend/`\n- service startup confusion: backend and frontend dev servers are usually started by workspace tasks, so check task state before assuming the app itself is broken\n\nOnce the environment is ready, continue to [Common Task Commands](../common-task-commands/).\n", "2.0": "+++\ntitle = \"Set up the Development Environment\"\n+++\n\nThe supported contributor path is the repository dev container.\n\n## Preferred Setup Path\n\nThe project is designed to be opened in VS Code with Dev Containers.\n\nBaseline assumptions from the maintained setup:\n\n- The dev container and production image inherit the same pinned Python runtime base from the root `Dockerfile`.\n- Node and npm are available for frontend and companion work.\n- Rust tooling is available for companion development.\n- post-create setup installs reviewed dependencies, initializes local state, and prepares default config where needed.\n\n### Runtime Package Refreshes\n\nThe shared runtime base refreshes Debian packages, including SQLite, before it installs the runtime dependencies. Production and CI image builds use a unique refresh key, so each build checks the current Debian packages instead of reusing a cached package-upgrade layer.\n\nLocal Dev Containers can reuse Docker's build cache. Use **Dev Containers: Rebuild Container Without Cache** when you need the current available Debian packages locally. The runtime's Python, SQLite module, and `libsqlite3-0` package versions are reported by Docker image validation in CI.\n\nIndependent builds made on different days can resolve different Debian security updates. This is intentional: the shared base controls the package policy and Python runtime, while regular rebuilds keep native packages current without maintaining a separate internal base-image release process.\n\n## First-Time Setup\n\n1. Open the repository in VS Code.\n2. Reopen in the dev container when prompted.\n3. Let the post-create setup complete.\n\nThe standard setup performs these tasks automatically:\n\n- configures Git hooks used by the repository workflow\n- installs backend dependencies from the hashed lockfiles\n- installs Node dependencies from the committed lockfiles\n- installs `pip-audit` and `cargo-audit` at the pinned versions used in CI\n- initializes the local database\n- creates a default `config.toml` if one is missing\n\nBackend tools run from `backend/.venv`. VS Code selects that interpreter, and the backend workspace tasks use it explicitly. Use `backend/.venv/bin/python -m \u003ctool\u003e` for manual backend commands.\n\nThe Git-hook setup matters more than it first appears.\n\n- the repo uses hooks from `.githooks/`\n- those hooks keep `GIT_COMMIT` aligned after commits and checkouts\n- they preserve the repository's Git LFS hook integration\n- they block pushes of `wip/*` branches\n- they refresh the committed docs structure report automatically when staged docs inputs affect it\n\nIf you work outside the dev container, run:\n\n```bash\n./scripts/setup-git-hooks\n```\n\nWhen you want to refresh docs-derived artifacts manually, use the workspace task `Website: Refresh Docs Derived Artifacts` or run:\n\n```bash\npython3 scripts/update-docs-derived-artifacts.py\n```\n\n## Local Service URLs\n\nIn the standard development setup, the main services are:\n\n- frontend: `http://localhost:3000`\n- backend: `http://localhost:8000`\n\nThe backend and frontend dev servers are usually started automatically by the workspace tasks.\n\n## Dependency Trust Rules\n\nContributors are expected to use the reviewed dependency workflow rather than ad hoc installs.\n\n- use `npm ci` in `frontend/`, `companion/`, and `website/` for routine installs\n- use the backend lockfile workflow instead of floating Python installs\n- treat `requirements*.txt`, lockfiles, and version metadata as reviewed source, not disposable setup noise\n- keep Tauri JavaScript packages and Rust crates aligned when companion dependencies move\n- review Dependabot Python runtime image updates with the Docker target validation results\n- treat high-risk frontend ecosystem upgrades as coordinated manual changes\n\n## Configuration Expectations\n\nLocal development depends on configuration, but the repo is designed to create a sane default local configuration automatically.\n\n- `config.example.toml` is the template\n- `config.toml` is the active local configuration\n- the backend startup workflow creates a default config with secure keys if one is missing\n\nDo not assume production deployment rules and local development rules are identical. The Admin Guide covers deployment-specific setup.\n\n## When to Leave the Happy Path\n\nUse the default container-based workflow unless you have a specific reason not to.\n\n- If your issue is environment-specific, fix the supported workflow first.\n- If you change tooling or dependencies, expect to update the corresponding reviewed inputs and rerun the relevant validation commands.\n- If you change version metadata, treat `VERSION` and the sync workflow as part of the change.\n\n## Common Setup Failures\n\nIf startup fails immediately after opening the dev container, start with the supported workflow rather than ad hoc fixes.\n\nCommon cases:\n\n- missing `config.toml`: the backend startup workflow should create a default config automatically\n- frontend `vite: not found` or `node_modules` permission failures: remove the broken install and rerun `npm ci` in `frontend/`\n- service startup confusion: backend and frontend dev servers are usually started by workspace tasks, so check task state before assuming the app itself is broken\n\nOnce the environment is ready, continue to [Common Task Commands](../common-task-commands/).\n"}, "page_contents": {"0.7": "+++\ntitle = \"Set up the Development Environment\"\n+++\n\nThe supported contributor path is the repository dev container.\n\n## Preferred Setup Path\n\nThe project is designed to be opened in VS Code with Dev Containers.\n\nBaseline assumptions from the maintained setup:\n\n- Python is pinned to the reviewed `3.13.12` baseline.\n- Node and npm are available for frontend and companion work.\n- Rust tooling is available for companion development.\n- post-create setup installs reviewed dependencies, initializes local state, and prepares default config where needed.\n\n## First-Time Setup\n\n1. Open the repository in VS Code.\n2. Reopen in the dev container when prompted.\n3. Let the post-create setup complete.\n\nThe standard setup performs these tasks automatically:\n\n- configures Git hooks used by the repository workflow\n- installs backend dependencies from the hashed lockfiles\n- installs Node dependencies from the committed lockfiles\n- installs `pip-audit` and `cargo-audit` at the pinned versions used in CI\n- initializes the local database\n- creates a default `config.toml` if one is missing\n\nThe Git-hook setup matters more than it first appears.\n\n- the repo uses hooks from `.githooks/`\n- those hooks keep `GIT_COMMIT` aligned after commits and checkouts\n- they preserve the repository's Git LFS hook integration\n- they block pushes of `wip/*` branches\n\nIf you work outside the dev container, run:\n\n```bash\n./scripts/setup-git-hooks\n```\n\n## Local Service URLs\n\nIn the standard development setup, the main services are:\n\n- frontend: `http://localhost:3000`\n- backend: `http://localhost:8000`\n\nThe backend and frontend dev servers are usually started automatically by the workspace tasks.\n\n## Dependency Trust Rules\n\nContributors are expected to use the reviewed dependency workflow rather than ad hoc installs.\n\n- use `npm ci` in `frontend/`, `companion/`, and `website/` for routine installs\n- use the backend lockfile workflow instead of floating Python installs\n- treat `requirements*.txt`, lockfiles, and version metadata as reviewed source, not disposable setup noise\n- keep Tauri JavaScript packages and Rust crates aligned when companion dependencies move\n- treat Python runtime upgrades and high-risk frontend ecosystem upgrades as coordinated manual changes\n\n## Configuration Expectations\n\nLocal development depends on configuration, but the repo is designed to create a sane default local configuration automatically.\n\n- `config.example.toml` is the template\n- `config.toml` is the active local configuration\n- the backend startup workflow creates a default config with secure keys if one is missing\n\nDo not assume production deployment rules and local development rules are identical. The Admin Guide covers deployment-specific setup.\n\n## When to Leave the Happy Path\n\nUse the default container-based workflow unless you have a specific reason not to.\n\n- If your issue is environment-specific, fix the supported workflow first.\n- If you change tooling or dependencies, expect to update the corresponding reviewed inputs and rerun the relevant validation commands.\n- If you change version metadata, treat `VERSION` and the sync workflow as part of the change.\n\n## Common Setup Failures\n\nIf startup fails immediately after opening the dev container, start with the supported workflow rather than ad hoc fixes.\n\nCommon cases:\n\n- missing `config.toml`: the backend startup workflow should create a default config automatically\n- frontend `vite: not found` or `node_modules` permission failures: remove the broken install and rerun `npm ci` in `frontend/`\n- service startup confusion: backend and frontend dev servers are usually started by workspace tasks, so check task state before assuming the app itself is broken\n\nOnce the environment is ready, continue to [Common Task Commands](../common-task-commands/).\n", "0.8": "+++\ntitle = \"Set up the Development Environment\"\n+++\n\nThe supported contributor path is the repository dev container.\n\n## Preferred Setup Path\n\nThe project is designed to be opened in VS Code with Dev Containers.\n\nBaseline assumptions from the maintained setup:\n\n- Python is pinned to the reviewed `3.13.12` baseline.\n- Node and npm are available for frontend and companion work.\n- Rust tooling is available for companion development.\n- post-create setup installs reviewed dependencies, initializes local state, and prepares default config where needed.\n\n## First-Time Setup\n\n1. Open the repository in VS Code.\n2. Reopen in the dev container when prompted.\n3. Let the post-create setup complete.\n\nThe standard setup performs these tasks automatically:\n\n- configures Git hooks used by the repository workflow\n- installs backend dependencies from the hashed lockfiles\n- installs Node dependencies from the committed lockfiles\n- installs `pip-audit` and `cargo-audit` at the pinned versions used in CI\n- initializes the local database\n- creates a default `config.toml` if one is missing\n\nThe Git-hook setup matters more than it first appears.\n\n- the repo uses hooks from `.githooks/`\n- those hooks keep `GIT_COMMIT` aligned after commits and checkouts\n- they preserve the repository's Git LFS hook integration\n- they block pushes of `wip/*` branches\n- they refresh the committed docs structure report automatically when staged docs inputs affect it\n\nIf you work outside the dev container, run:\n\n```bash\n./scripts/setup-git-hooks\n```\n\nWhen you want to refresh docs-derived artifacts manually, use the workspace task `Website: Refresh Docs Derived Artifacts` or run:\n\n```bash\npython3 scripts/update-docs-derived-artifacts.py\n```\n\n## Local Service URLs\n\nIn the standard development setup, the main services are:\n\n- frontend: `http://localhost:3000`\n- backend: `http://localhost:8000`\n\nThe backend and frontend dev servers are usually started automatically by the workspace tasks.\n\n## Dependency Trust Rules\n\nContributors are expected to use the reviewed dependency workflow rather than ad hoc installs.\n\n- use `npm ci` in `frontend/`, `companion/`, and `website/` for routine installs\n- use the backend lockfile workflow instead of floating Python installs\n- treat `requirements*.txt`, lockfiles, and version metadata as reviewed source, not disposable setup noise\n- keep Tauri JavaScript packages and Rust crates aligned when companion dependencies move\n- treat Python runtime upgrades and high-risk frontend ecosystem upgrades as coordinated manual changes\n\n## Configuration Expectations\n\nLocal development depends on configuration, but the repo is designed to create a sane default local configuration automatically.\n\n- `config.example.toml` is the template\n- `config.toml` is the active local configuration\n- the backend startup workflow creates a default config with secure keys if one is missing\n\nDo not assume production deployment rules and local development rules are identical. The Admin Guide covers deployment-specific setup.\n\n## When to Leave the Happy Path\n\nUse the default container-based workflow unless you have a specific reason not to.\n\n- If your issue is environment-specific, fix the supported workflow first.\n- If you change tooling or dependencies, expect to update the corresponding reviewed inputs and rerun the relevant validation commands.\n- If you change version metadata, treat `VERSION` and the sync workflow as part of the change.\n\n## Common Setup Failures\n\nIf startup fails immediately after opening the dev container, start with the supported workflow rather than ad hoc fixes.\n\nCommon cases:\n\n- missing `config.toml`: the backend startup workflow should create a default config automatically\n- frontend `vite: not found` or `node_modules` permission failures: remove the broken install and rerun `npm ci` in `frontend/`\n- service startup confusion: backend and frontend dev servers are usually started by workspace tasks, so check task state before assuming the app itself is broken\n\nOnce the environment is ready, continue to [Common Task Commands](../common-task-commands/).", "0.9": "+++\ntitle = \"Set up the Development Environment\"\n+++\n\nThe supported contributor path is the repository dev container.\n\n## Preferred Setup Path\n\nThe project is designed to be opened in VS Code with Dev Containers.\n\nBaseline assumptions from the maintained setup:\n\n- The dev container and production image inherit the same pinned Python runtime base from the root `Dockerfile`.\n- Node and npm are available for frontend and companion work.\n- Rust tooling is available for companion development.\n- post-create setup installs reviewed dependencies, initializes local state, and prepares default config where needed.\n\n### Runtime Package Refreshes\n\nThe shared runtime base refreshes Debian packages, including SQLite, before it installs the runtime dependencies. Production and CI image builds use a unique refresh key, so each build checks the current Debian packages instead of reusing a cached package-upgrade layer.\n\nLocal Dev Containers can reuse Docker's build cache. Use **Dev Containers: Rebuild Container Without Cache** when you need the current available Debian packages locally. The runtime's Python, SQLite module, and `libsqlite3-0` package versions are reported by Docker image validation in CI.\n\nIndependent builds made on different days can resolve different Debian security updates. This is intentional: the shared base controls the package policy and Python runtime, while regular rebuilds keep native packages current without maintaining a separate internal base-image release process.\n\n## First-Time Setup\n\n1. Open the repository in VS Code.\n2. Reopen in the dev container when prompted.\n3. Let the post-create setup complete.\n\nThe standard setup performs these tasks automatically:\n\n- configures Git hooks used by the repository workflow\n- installs backend dependencies from the hashed lockfiles\n- installs Node dependencies from the committed lockfiles\n- installs `pip-audit` and `cargo-audit` at the pinned versions used in CI\n- initializes the local database\n- creates a default `config.toml` if one is missing\n\nBackend tools run from `backend/.venv`. VS Code selects that interpreter, and the backend workspace tasks use it explicitly. Use `backend/.venv/bin/python -m \u003ctool\u003e` for manual backend commands.\n\nThe Git-hook setup matters more than it first appears.\n\n- the repo uses hooks from `.githooks/`\n- those hooks keep `GIT_COMMIT` aligned after commits and checkouts\n- they preserve the repository's Git LFS hook integration\n- they block pushes of `wip/*` branches\n- they refresh the committed docs structure report automatically when staged docs inputs affect it\n\nIf you work outside the dev container, run:\n\n```bash\n./scripts/setup-git-hooks\n```\n\nWhen you want to refresh docs-derived artifacts manually, use the workspace task `Website: Refresh Docs Derived Artifacts` or run:\n\n```bash\npython3 scripts/update-docs-derived-artifacts.py\n```\n\n## Local Service URLs\n\nIn the standard development setup, the main services are:\n\n- frontend: `http://localhost:3000`\n- backend: `http://localhost:8000`\n\nThe backend and frontend dev servers are usually started automatically by the workspace tasks.\n\n## Dependency Trust Rules\n\nContributors are expected to use the reviewed dependency workflow rather than ad hoc installs.\n\n- use `npm ci` in `frontend/`, `companion/`, and `website/` for routine installs\n- use the backend lockfile workflow instead of floating Python installs\n- treat `requirements*.txt`, lockfiles, and version metadata as reviewed source, not disposable setup noise\n- keep Tauri JavaScript packages and Rust crates aligned when companion dependencies move\n- review Dependabot Python runtime image updates with the Docker target validation results\n- treat high-risk frontend ecosystem upgrades as coordinated manual changes\n\n## Configuration Expectations\n\nLocal development depends on configuration, but the repo is designed to create a sane default local configuration automatically.\n\n- `config.example.toml` is the template\n- `config.toml` is the active local configuration\n- the backend startup workflow creates a default config with secure keys if one is missing\n\nDo not assume production deployment rules and local development rules are identical. The Admin Guide covers deployment-specific setup.\n\n## When to Leave the Happy Path\n\nUse the default container-based workflow unless you have a specific reason not to.\n\n- If your issue is environment-specific, fix the supported workflow first.\n- If you change tooling or dependencies, expect to update the corresponding reviewed inputs and rerun the relevant validation commands.\n- If you change version metadata, treat `VERSION` and the sync workflow as part of the change.\n\n## Common Setup Failures\n\nIf startup fails immediately after opening the dev container, start with the supported workflow rather than ad hoc fixes.\n\nCommon cases:\n\n- missing `config.toml`: the backend startup workflow should create a default config automatically\n- frontend `vite: not found` or `node_modules` permission failures: remove the broken install and rerun `npm ci` in `frontend/`\n- service startup confusion: backend and frontend dev servers are usually started by workspace tasks, so check task state before assuming the app itself is broken\n\nOnce the environment is ready, continue to [Common Task Commands](../common-task-commands/).\n", "1.0": "+++\ntitle = \"Set up the Development Environment\"\n+++\n\nThe supported contributor path is the repository dev container.\n\n## Preferred Setup Path\n\nThe project is designed to be opened in VS Code with Dev Containers.\n\nBaseline assumptions from the maintained setup:\n\n- The dev container and production image inherit the same pinned Python runtime base from the root `Dockerfile`.\n- Node and npm are available for frontend and companion work.\n- Rust tooling is available for companion development.\n- post-create setup installs reviewed dependencies, initializes local state, and prepares default config where needed.\n\n### Runtime Package Refreshes\n\nThe shared runtime base refreshes Debian packages, including SQLite, before it installs the runtime dependencies. Production and CI image builds use a unique refresh key, so each build checks the current Debian packages instead of reusing a cached package-upgrade layer.\n\nLocal Dev Containers can reuse Docker's build cache. Use **Dev Containers: Rebuild Container Without Cache** when you need the current available Debian packages locally. The runtime's Python, SQLite module, and `libsqlite3-0` package versions are reported by Docker image validation in CI.\n\nIndependent builds made on different days can resolve different Debian security updates. This is intentional: the shared base controls the package policy and Python runtime, while regular rebuilds keep native packages current without maintaining a separate internal base-image release process.\n\n## First-Time Setup\n\n1. Open the repository in VS Code.\n2. Reopen in the dev container when prompted.\n3. Let the post-create setup complete.\n\nThe standard setup performs these tasks automatically:\n\n- configures Git hooks used by the repository workflow\n- installs backend dependencies from the hashed lockfiles\n- installs Node dependencies from the committed lockfiles\n- installs `pip-audit` and `cargo-audit` at the pinned versions used in CI\n- initializes the local database\n- creates a default `config.toml` if one is missing\n\nBackend tools run from `backend/.venv`. VS Code selects that interpreter, and the backend workspace tasks use it explicitly. Use `backend/.venv/bin/python -m \u003ctool\u003e` for manual backend commands.\n\nThe Git-hook setup matters more than it first appears.\n\n- the repo uses hooks from `.githooks/`\n- those hooks keep `GIT_COMMIT` aligned after commits and checkouts\n- they preserve the repository's Git LFS hook integration\n- they block pushes of `wip/*` branches\n- they refresh the committed docs structure report automatically when staged docs inputs affect it\n\nIf you work outside the dev container, run:\n\n```bash\n./scripts/setup-git-hooks\n```\n\nWhen you want to refresh docs-derived artifacts manually, use the workspace task `Website: Refresh Docs Derived Artifacts` or run:\n\n```bash\npython3 scripts/update-docs-derived-artifacts.py\n```\n\n## Local Service URLs\n\nIn the standard development setup, the main services are:\n\n- frontend: `http://localhost:3000`\n- backend: `http://localhost:8000`\n\nThe backend and frontend dev servers are usually started automatically by the workspace tasks.\n\n## Dependency Trust Rules\n\nContributors are expected to use the reviewed dependency workflow rather than ad hoc installs.\n\n- use `npm ci` in `frontend/`, `companion/`, and `website/` for routine installs\n- use the backend lockfile workflow instead of floating Python installs\n- treat `requirements*.txt`, lockfiles, and version metadata as reviewed source, not disposable setup noise\n- keep Tauri JavaScript packages and Rust crates aligned when companion dependencies move\n- review Dependabot Python runtime image updates with the Docker target validation results\n- treat high-risk frontend ecosystem upgrades as coordinated manual changes\n\n## Configuration Expectations\n\nLocal development depends on configuration, but the repo is designed to create a sane default local configuration automatically.\n\n- `config.example.toml` is the template\n- `config.toml` is the active local configuration\n- the backend startup workflow creates a default config with secure keys if one is missing\n\nDo not assume production deployment rules and local development rules are identical. The Admin Guide covers deployment-specific setup.\n\n## When to Leave the Happy Path\n\nUse the default container-based workflow unless you have a specific reason not to.\n\n- If your issue is environment-specific, fix the supported workflow first.\n- If you change tooling or dependencies, expect to update the corresponding reviewed inputs and rerun the relevant validation commands.\n- If you change version metadata, treat `VERSION` and the sync workflow as part of the change.\n\n## Common Setup Failures\n\nIf startup fails immediately after opening the dev container, start with the supported workflow rather than ad hoc fixes.\n\nCommon cases:\n\n- missing `config.toml`: the backend startup workflow should create a default config automatically\n- frontend `vite: not found` or `node_modules` permission failures: remove the broken install and rerun `npm ci` in `frontend/`\n- service startup confusion: backend and frontend dev servers are usually started by workspace tasks, so check task state before assuming the app itself is broken\n\nOnce the environment is ready, continue to [Common Task Commands](../common-task-commands/).\n", "2.0": "+++\ntitle = \"Set up the Development Environment\"\n+++\n\nThe supported contributor path is the repository dev container.\n\n## Preferred Setup Path\n\nThe project is designed to be opened in VS Code with Dev Containers.\n\nBaseline assumptions from the maintained setup:\n\n- The dev container and production image inherit the same pinned Python runtime base from the root `Dockerfile`.\n- Node and npm are available for frontend and companion work.\n- Rust tooling is available for companion development.\n- post-create setup installs reviewed dependencies, initializes local state, and prepares default config where needed.\n\n### Runtime Package Refreshes\n\nThe shared runtime base refreshes Debian packages, including SQLite, before it installs the runtime dependencies. Production and CI image builds use a unique refresh key, so each build checks the current Debian packages instead of reusing a cached package-upgrade layer.\n\nLocal Dev Containers can reuse Docker's build cache. Use **Dev Containers: Rebuild Container Without Cache** when you need the current available Debian packages locally. The runtime's Python, SQLite module, and `libsqlite3-0` package versions are reported by Docker image validation in CI.\n\nIndependent builds made on different days can resolve different Debian security updates. This is intentional: the shared base controls the package policy and Python runtime, while regular rebuilds keep native packages current without maintaining a separate internal base-image release process.\n\n## First-Time Setup\n\n1. Open the repository in VS Code.\n2. Reopen in the dev container when prompted.\n3. Let the post-create setup complete.\n\nThe standard setup performs these tasks automatically:\n\n- configures Git hooks used by the repository workflow\n- installs backend dependencies from the hashed lockfiles\n- installs Node dependencies from the committed lockfiles\n- installs `pip-audit` and `cargo-audit` at the pinned versions used in CI\n- initializes the local database\n- creates a default `config.toml` if one is missing\n\nBackend tools run from `backend/.venv`. VS Code selects that interpreter, and the backend workspace tasks use it explicitly. Use `backend/.venv/bin/python -m \u003ctool\u003e` for manual backend commands.\n\nThe Git-hook setup matters more than it first appears.\n\n- the repo uses hooks from `.githooks/`\n- those hooks keep `GIT_COMMIT` aligned after commits and checkouts\n- they preserve the repository's Git LFS hook integration\n- they block pushes of `wip/*` branches\n- they refresh the committed docs structure report automatically when staged docs inputs affect it\n\nIf you work outside the dev container, run:\n\n```bash\n./scripts/setup-git-hooks\n```\n\nWhen you want to refresh docs-derived artifacts manually, use the workspace task `Website: Refresh Docs Derived Artifacts` or run:\n\n```bash\npython3 scripts/update-docs-derived-artifacts.py\n```\n\n## Local Service URLs\n\nIn the standard development setup, the main services are:\n\n- frontend: `http://localhost:3000`\n- backend: `http://localhost:8000`\n\nThe backend and frontend dev servers are usually started automatically by the workspace tasks.\n\n## Dependency Trust Rules\n\nContributors are expected to use the reviewed dependency workflow rather than ad hoc installs.\n\n- use `npm ci` in `frontend/`, `companion/`, and `website/` for routine installs\n- use the backend lockfile workflow instead of floating Python installs\n- treat `requirements*.txt`, lockfiles, and version metadata as reviewed source, not disposable setup noise\n- keep Tauri JavaScript packages and Rust crates aligned when companion dependencies move\n- review Dependabot Python runtime image updates with the Docker target validation results\n- treat high-risk frontend ecosystem upgrades as coordinated manual changes\n\n## Configuration Expectations\n\nLocal development depends on configuration, but the repo is designed to create a sane default local configuration automatically.\n\n- `config.example.toml` is the template\n- `config.toml` is the active local configuration\n- the backend startup workflow creates a default config with secure keys if one is missing\n\nDo not assume production deployment rules and local development rules are identical. The Admin Guide covers deployment-specific setup.\n\n## When to Leave the Happy Path\n\nUse the default container-based workflow unless you have a specific reason not to.\n\n- If your issue is environment-specific, fix the supported workflow first.\n- If you change tooling or dependencies, expect to update the corresponding reviewed inputs and rerun the relevant validation commands.\n- If you change version metadata, treat `VERSION` and the sync workflow as part of the change.\n\n## Common Setup Failures\n\nIf startup fails immediately after opening the dev container, start with the supported workflow rather than ad hoc fixes.\n\nCommon cases:\n\n- missing `config.toml`: the backend startup workflow should create a default config automatically\n- frontend `vite: not found` or `node_modules` permission failures: remove the broken install and rerun `npm ci` in `frontend/`\n- service startup confusion: backend and frontend dev servers are usually started by workspace tasks, so check task state before assuming the app itself is broken\n\nOnce the environment is ready, continue to [Common Task Commands](../common-task-commands/).\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/local-development-workflow/common-task-commands", "parent_id": "section:developer-guide/local-development-workflow", "depth": 2, "kind": "page", "label": "common-task-commands", "title": "Common Task Commands", "path": "developer-guide/local-development-workflow/common-task-commands", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "branched", "source_version": "0.7", "diff_added": 16, "diff_removed": 0}, "0.9": {"state": "inherited", "source_version": "0.8"}, "1.0": {"state": "inherited", "source_version": "0.8"}, "2.0": {"state": "inherited", "source_version": "0.8"}}, "content_versions": {"0.7": "+++\ntitle = \"Common Task Commands\"\n+++\n\nPrefer the committed scripts and workspace tasks over improvised one-off commands.\n\n## Daily Entry Points\n\n| Goal | Preferred command or task |\n|---|---|\n| Start backend dev server | VS Code task `Backend: Start Dev Server` or `./scripts/start-backend` |\n| Start frontend dev server | VS Code task `Frontend: Start Dev Server` or `./scripts/start-frontend` |\n| Start both local dev servers together | `./scripts/dev-start` |\n| Stop local dev servers together | `./scripts/dev-stop` |\n| Inspect local dev logs | `./scripts/logs` |\n| Run fast repo tests | `./scripts/test` |\n| Run repo tests with coverage | `COVERAGE=1 ./scripts/test` |\n\n## Backend Commands\n\nUse these when you are changing backend behavior, API contracts, or SMB handling.\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nUseful related task:\n\n- VS Code task `Backend: Run Tests`\n- VS Code task `Backend: Type Check (mypy)`\n\n## Frontend Commands\n\nUse these when the browser UI, routing, services, or typed frontend behavior changes.\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nUseful related task:\n\n- VS Code task `Frontend: Run Tests`\n- VS Code task `Frontend: Type Check + Lint`\n\n## Companion Commands\n\nUse these when local-drive access, native-app editing, or Tauri-side behavior changes.\n\n```bash\ncd companion \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nUseful related task:\n\n- VS Code task `Companion: Run Rust Tests`\n- VS Code task `Companion: Validation Suite`\n\n## Local Dev Logs and Service Control\n\nUse the committed helper scripts first when you are diagnosing the supported local development workflow.\n\n### Combined Dev Server Control\n\nThese scripts manage the local backend and frontend together:\n\n```bash\n./scripts/dev-start\n./scripts/dev-stop\n./scripts/dev-stop \u0026\u0026 ./scripts/dev-start\n```\n\nUse those entry points when you want the repo's own startup logging and local log-file layout instead of ad hoc process control.\n\n### Log Inspection\n\nThe supported local log viewer is:\n\n```bash\n./scripts/logs\n./scripts/logs -f\n./scripts/logs -n 200\n```\n\nThat script summarizes service status and tails the main local development log files.\n\nThe current local log files are:\n\n- `/tmp/backend.log`\n- `/tmp/frontend.log`\n- `/tmp/dev-start.log`\n- `/tmp/post-start.log`\n\nYou can inspect individual files directly when needed:\n\n```bash\ntail -f /tmp/backend.log\ntail -f /tmp/frontend.log\ntail -f /tmp/dev-start.log\ntail -f /tmp/post-start.log\n```\n\n### Search and Status Checks\n\nWhen the helper scripts are not enough, targeted shell checks are still useful.\n\n```bash\npgrep -f \"uvicorn.*app.main:app\"\npgrep -f \"vite\"\nlsof -i :3000,8000\ngrep -i error /tmp/*.log\ngrep -i warning /tmp/*.log\ngrep -i smb /tmp/backend.log\ngrep -E \"\\([0-9]{4,}\\.[0-9]+ms\\)\" /tmp/backend.log\n```\n\nTreat these as diagnostics for the local development environment, not as the primary supported control surface.\n\nBe especially careful with broad `pkill -f vite`-style commands in a workspace that can also run website or companion dev servers.\n\n### Rotating and Clearing Local Logs\n\nWhen local logs become noisy, use the committed rotation script first:\n\n```bash\n./scripts/rotate-logs\n```\n\nThat script archives current `/tmp/*.log` files into `/tmp/logs-archive/` and truncates the live files in place so active writers keep working.\n\nTo inspect archived logs:\n\n```bash\nls -lh /tmp/logs-archive/\n```\n\nManual truncation is still possible for local development, but it is a deliberately destructive cleanup step:\n\n```bash\n\u003e /tmp/backend.log\n\u003e /tmp/frontend.log\n\u003e /tmp/dev-start.log\n\u003e /tmp/post-start.log\n```\n\nUse that only when you intentionally want to discard the current local log history.\n\n### Practical Local Triage Order\n\nFor the supported dev workflow, a reasonable first pass is:\n\n1. run `./scripts/logs`\n2. verify the expected dev processes or ports if the summary looks wrong\n3. search `/tmp/*.log` for the concrete failure signal\n4. restart with `./scripts/dev-stop \u0026\u0026 ./scripts/dev-start` if the issue is clearly local-process state rather than a code defect\n\n## Version Sync\n\nWhen you change `VERSION`, run the sync script and review all resulting metadata changes together.\n\n```bash\n./scripts/sync-version\n```\n\nThat workflow updates the frontend and companion package metadata and related version-bearing files.\n\n## Command Selection Rule of Thumb\n\n- smallest relevant change: run the checks for the area you changed\n- cross-boundary change: run checks for every touched subsystem\n- dependency or versioning change: run the affected subsystem checks plus the sync workflow if `VERSION` changed\n\nFor the broader validation strategy and how to choose depth, continue to [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/).\n", "0.8": "+++\ntitle = \"Common Task Commands\"\n+++\n\nPrefer the committed scripts and workspace tasks over improvised one-off commands.\n\n## Daily Entry Points\n\n| Goal | Preferred command or task |\n|---|---|\n| Start backend dev server | VS Code task `Backend: Start Dev Server` or `./scripts/start-backend` |\n| Start frontend dev server | VS Code task `Frontend: Start Dev Server` or `./scripts/start-frontend` |\n| Start both local dev servers together | `./scripts/dev-start` |\n| Stop local dev servers together | `./scripts/dev-stop` |\n| Inspect local dev logs | `./scripts/logs` |\n| Run fast repo tests | `./scripts/test` |\n| Run repo tests with coverage | `COVERAGE=1 ./scripts/test` |\n\n`./scripts/test` now includes the companion Windows GNU target compatibility check when the local toolchain is available.\nIn the devcontainer, that toolchain is preinstalled as part of the image build.\n\n## Backend Commands\n\nUse these when you are changing backend behavior, API contracts, or SMB handling.\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nUseful related task:\n\n- VS Code task `Backend: Run Tests`\n- VS Code task `Backend: Type Check (mypy)`\n\n## Frontend Commands\n\nUse these when the browser UI, routing, services, or typed frontend behavior changes.\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nUseful related task:\n\n- VS Code task `Frontend: Run Tests`\n- VS Code task `Frontend: Type Check + Lint`\n\n## Companion Commands\n\nUse these when local-drive access, native-app editing, or Tauri-side behavior changes.\n\n```bash\ncd companion \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run check:rust:windows\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nUse `npm run check:rust:windows` as a local Windows-target compatibility check.\nIt runs `cargo check` for `x86_64-pc-windows-gnu` from Linux and is intended to catch cross-target breakage early without replacing the real Windows release build.\n\nUseful related task:\n\n- VS Code task `Companion: Run Rust Tests`\n- VS Code task `Companion: Validation Suite`\n\nThe committed devcontainer image now includes:\n\n- the Rust target `x86_64-pc-windows-gnu`\n- the MinGW toolchain package `gcc-mingw-w64-x86-64`\n\nThat means a rebuilt devcontainer can run the companion Windows GNU cross-check without extra manual setup.\n\n## Local Dev Logs and Service Control\n\nUse the committed helper scripts first when you are diagnosing the supported local development workflow.\n\n### Combined Dev Server Control\n\nThese scripts manage the local backend and frontend together:\n\n```bash\n./scripts/dev-start\n./scripts/dev-stop\n./scripts/dev-stop \u0026\u0026 ./scripts/dev-start\n```\n\nUse those entry points when you want the repo's own startup logging and local log-file layout instead of ad hoc process control.\n\n### Log Inspection\n\nThe supported local log viewer is:\n\n```bash\n./scripts/logs\n./scripts/logs -f\n./scripts/logs -n 200\n```\n\nThat script summarizes service status and tails the main local development log files.\n\nThe current local log files are:\n\n- `/tmp/backend.log`\n- `/tmp/frontend.log`\n- `/tmp/dev-start.log`\n- `/tmp/post-start.log`\n\nYou can inspect individual files directly when needed:\n\n```bash\ntail -f /tmp/backend.log\ntail -f /tmp/frontend.log\ntail -f /tmp/dev-start.log\ntail -f /tmp/post-start.log\n```\n\n### Search and Status Checks\n\nWhen the helper scripts are not enough, targeted shell checks are still useful.\n\n```bash\npgrep -f \"uvicorn.*app.main:app\"\npgrep -f \"vite\"\nlsof -i :3000,8000\ngrep -i error /tmp/*.log\ngrep -i warning /tmp/*.log\ngrep -i smb /tmp/backend.log\ngrep -E \"\\([0-9]{4,}\\.[0-9]+ms\\)\" /tmp/backend.log\n```\n\nTreat these as diagnostics for the local development environment, not as the primary supported control surface.\n\nBe especially careful with broad `pkill -f vite`-style commands in a workspace that can also run website or companion dev servers.\n\n### Rotating and Clearing Local Logs\n\nWhen local logs become noisy, use the committed rotation script first:\n\n```bash\n./scripts/rotate-logs\n```\n\nThat script archives current `/tmp/*.log` files into `/tmp/logs-archive/` and truncates the live files in place so active writers keep working.\n\nTo inspect archived logs:\n\n```bash\nls -lh /tmp/logs-archive/\n```\n\nManual truncation is still possible for local development, but it is a deliberately destructive cleanup step:\n\n```bash\n\u003e /tmp/backend.log\n\u003e /tmp/frontend.log\n\u003e /tmp/dev-start.log\n\u003e /tmp/post-start.log\n```\n\nUse that only when you intentionally want to discard the current local log history.\n\n### Practical Local Triage Order\n\nFor the supported dev workflow, a reasonable first pass is:\n\n1. run `./scripts/logs`\n2. verify the expected dev processes or ports if the summary looks wrong\n3. search `/tmp/*.log` for the concrete failure signal\n4. restart with `./scripts/dev-stop \u0026\u0026 ./scripts/dev-start` if the issue is clearly local-process state rather than a code defect\n\n## Version Sync\n\nWhen you change `VERSION`, run the sync script and review all resulting metadata changes together.\n\n```bash\n./scripts/sync-version\n```\n\nThat workflow updates the frontend and companion package metadata and related version-bearing files.\n\n## Command Selection Rule of Thumb\n\n- smallest relevant change: run the checks for the area you changed\n- cross-boundary change: run checks for every touched subsystem\n- dependency or versioning change: run the affected subsystem checks plus the sync workflow if `VERSION` changed\n\nFor companion-native changes that affect packaging, Windows-specific crates, or Tauri platform integration, include the Windows GNU cross-check in the local validation set even when you are not creating release artifacts.\n\nFor the broader validation strategy and how to choose depth, continue to [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/).\n", "0.9": "+++\ntitle = \"Common Task Commands\"\n+++\n\nPrefer the committed scripts and workspace tasks over improvised one-off commands.\n\n## Daily Entry Points\n\n| Goal | Preferred command or task |\n|---|---|\n| Start backend dev server | VS Code task `Backend: Start Dev Server` or `./scripts/start-backend` |\n| Start frontend dev server | VS Code task `Frontend: Start Dev Server` or `./scripts/start-frontend` |\n| Start both local dev servers together | `./scripts/dev-start` |\n| Stop local dev servers together | `./scripts/dev-stop` |\n| Inspect local dev logs | `./scripts/logs` |\n| Run fast repo tests | `./scripts/test` |\n| Run repo tests with coverage | `COVERAGE=1 ./scripts/test` |\n\n`./scripts/test` now includes the companion Windows GNU target compatibility check when the local toolchain is available.\nIn the devcontainer, that toolchain is preinstalled as part of the image build.\n\n## Backend Commands\n\nUse these when you are changing backend behavior, API contracts, or SMB handling.\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nUseful related task:\n\n- VS Code task `Backend: Run Tests`\n- VS Code task `Backend: Type Check (mypy)`\n\n## Frontend Commands\n\nUse these when the browser UI, routing, services, or typed frontend behavior changes.\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nUseful related task:\n\n- VS Code task `Frontend: Run Tests`\n- VS Code task `Frontend: Type Check + Lint`\n\n## Companion Commands\n\nUse these when local-drive access, native-app editing, or Tauri-side behavior changes.\n\n```bash\ncd companion \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run check:rust:windows\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nUse `npm run check:rust:windows` as a local Windows-target compatibility check.\nIt runs `cargo check` for `x86_64-pc-windows-gnu` from Linux and is intended to catch cross-target breakage early without replacing the real Windows release build.\n\nUseful related task:\n\n- VS Code task `Companion: Run Rust Tests`\n- VS Code task `Companion: Validation Suite`\n\nThe committed devcontainer image now includes:\n\n- the Rust target `x86_64-pc-windows-gnu`\n- the MinGW toolchain package `gcc-mingw-w64-x86-64`\n\nThat means a rebuilt devcontainer can run the companion Windows GNU cross-check without extra manual setup.\n\n## Local Dev Logs and Service Control\n\nUse the committed helper scripts first when you are diagnosing the supported local development workflow.\n\n### Combined Dev Server Control\n\nThese scripts manage the local backend and frontend together:\n\n```bash\n./scripts/dev-start\n./scripts/dev-stop\n./scripts/dev-stop \u0026\u0026 ./scripts/dev-start\n```\n\nUse those entry points when you want the repo's own startup logging and local log-file layout instead of ad hoc process control.\n\n### Log Inspection\n\nThe supported local log viewer is:\n\n```bash\n./scripts/logs\n./scripts/logs -f\n./scripts/logs -n 200\n```\n\nThat script summarizes service status and tails the main local development log files.\n\nThe current local log files are:\n\n- `/tmp/backend.log`\n- `/tmp/frontend.log`\n- `/tmp/dev-start.log`\n- `/tmp/post-start.log`\n\nYou can inspect individual files directly when needed:\n\n```bash\ntail -f /tmp/backend.log\ntail -f /tmp/frontend.log\ntail -f /tmp/dev-start.log\ntail -f /tmp/post-start.log\n```\n\n### Search and Status Checks\n\nWhen the helper scripts are not enough, targeted shell checks are still useful.\n\n```bash\npgrep -f \"uvicorn.*app.main:app\"\npgrep -f \"vite\"\nlsof -i :3000,8000\ngrep -i error /tmp/*.log\ngrep -i warning /tmp/*.log\ngrep -i smb /tmp/backend.log\ngrep -E \"\\([0-9]{4,}\\.[0-9]+ms\\)\" /tmp/backend.log\n```\n\nTreat these as diagnostics for the local development environment, not as the primary supported control surface.\n\nBe especially careful with broad `pkill -f vite`-style commands in a workspace that can also run website or companion dev servers.\n\n### Rotating and Clearing Local Logs\n\nWhen local logs become noisy, use the committed rotation script first:\n\n```bash\n./scripts/rotate-logs\n```\n\nThat script archives current `/tmp/*.log` files into `/tmp/logs-archive/` and truncates the live files in place so active writers keep working.\n\nTo inspect archived logs:\n\n```bash\nls -lh /tmp/logs-archive/\n```\n\nManual truncation is still possible for local development, but it is a deliberately destructive cleanup step:\n\n```bash\n\u003e /tmp/backend.log\n\u003e /tmp/frontend.log\n\u003e /tmp/dev-start.log\n\u003e /tmp/post-start.log\n```\n\nUse that only when you intentionally want to discard the current local log history.\n\n### Practical Local Triage Order\n\nFor the supported dev workflow, a reasonable first pass is:\n\n1. run `./scripts/logs`\n2. verify the expected dev processes or ports if the summary looks wrong\n3. search `/tmp/*.log` for the concrete failure signal\n4. restart with `./scripts/dev-stop \u0026\u0026 ./scripts/dev-start` if the issue is clearly local-process state rather than a code defect\n\n## Version Sync\n\nWhen you change `VERSION`, run the sync script and review all resulting metadata changes together.\n\n```bash\n./scripts/sync-version\n```\n\nThat workflow updates the frontend and companion package metadata and related version-bearing files.\n\n## Command Selection Rule of Thumb\n\n- smallest relevant change: run the checks for the area you changed\n- cross-boundary change: run checks for every touched subsystem\n- dependency or versioning change: run the affected subsystem checks plus the sync workflow if `VERSION` changed\n\nFor companion-native changes that affect packaging, Windows-specific crates, or Tauri platform integration, include the Windows GNU cross-check in the local validation set even when you are not creating release artifacts.\n\nFor the broader validation strategy and how to choose depth, continue to [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/).\n", "1.0": "+++\ntitle = \"Common Task Commands\"\n+++\n\nPrefer the committed scripts and workspace tasks over improvised one-off commands.\n\n## Daily Entry Points\n\n| Goal | Preferred command or task |\n|---|---|\n| Start backend dev server | VS Code task `Backend: Start Dev Server` or `./scripts/start-backend` |\n| Start frontend dev server | VS Code task `Frontend: Start Dev Server` or `./scripts/start-frontend` |\n| Start both local dev servers together | `./scripts/dev-start` |\n| Stop local dev servers together | `./scripts/dev-stop` |\n| Inspect local dev logs | `./scripts/logs` |\n| Run fast repo tests | `./scripts/test` |\n| Run repo tests with coverage | `COVERAGE=1 ./scripts/test` |\n\n`./scripts/test` now includes the companion Windows GNU target compatibility check when the local toolchain is available.\nIn the devcontainer, that toolchain is preinstalled as part of the image build.\n\n## Backend Commands\n\nUse these when you are changing backend behavior, API contracts, or SMB handling.\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nUseful related task:\n\n- VS Code task `Backend: Run Tests`\n- VS Code task `Backend: Type Check (mypy)`\n\n## Frontend Commands\n\nUse these when the browser UI, routing, services, or typed frontend behavior changes.\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nUseful related task:\n\n- VS Code task `Frontend: Run Tests`\n- VS Code task `Frontend: Type Check + Lint`\n\n## Companion Commands\n\nUse these when local-drive access, native-app editing, or Tauri-side behavior changes.\n\n```bash\ncd companion \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run check:rust:windows\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nUse `npm run check:rust:windows` as a local Windows-target compatibility check.\nIt runs `cargo check` for `x86_64-pc-windows-gnu` from Linux and is intended to catch cross-target breakage early without replacing the real Windows release build.\n\nUseful related task:\n\n- VS Code task `Companion: Run Rust Tests`\n- VS Code task `Companion: Validation Suite`\n\nThe committed devcontainer image now includes:\n\n- the Rust target `x86_64-pc-windows-gnu`\n- the MinGW toolchain package `gcc-mingw-w64-x86-64`\n\nThat means a rebuilt devcontainer can run the companion Windows GNU cross-check without extra manual setup.\n\n## Local Dev Logs and Service Control\n\nUse the committed helper scripts first when you are diagnosing the supported local development workflow.\n\n### Combined Dev Server Control\n\nThese scripts manage the local backend and frontend together:\n\n```bash\n./scripts/dev-start\n./scripts/dev-stop\n./scripts/dev-stop \u0026\u0026 ./scripts/dev-start\n```\n\nUse those entry points when you want the repo's own startup logging and local log-file layout instead of ad hoc process control.\n\n### Log Inspection\n\nThe supported local log viewer is:\n\n```bash\n./scripts/logs\n./scripts/logs -f\n./scripts/logs -n 200\n```\n\nThat script summarizes service status and tails the main local development log files.\n\nThe current local log files are:\n\n- `/tmp/backend.log`\n- `/tmp/frontend.log`\n- `/tmp/dev-start.log`\n- `/tmp/post-start.log`\n\nYou can inspect individual files directly when needed:\n\n```bash\ntail -f /tmp/backend.log\ntail -f /tmp/frontend.log\ntail -f /tmp/dev-start.log\ntail -f /tmp/post-start.log\n```\n\n### Search and Status Checks\n\nWhen the helper scripts are not enough, targeted shell checks are still useful.\n\n```bash\npgrep -f \"uvicorn.*app.main:app\"\npgrep -f \"vite\"\nlsof -i :3000,8000\ngrep -i error /tmp/*.log\ngrep -i warning /tmp/*.log\ngrep -i smb /tmp/backend.log\ngrep -E \"\\([0-9]{4,}\\.[0-9]+ms\\)\" /tmp/backend.log\n```\n\nTreat these as diagnostics for the local development environment, not as the primary supported control surface.\n\nBe especially careful with broad `pkill -f vite`-style commands in a workspace that can also run website or companion dev servers.\n\n### Rotating and Clearing Local Logs\n\nWhen local logs become noisy, use the committed rotation script first:\n\n```bash\n./scripts/rotate-logs\n```\n\nThat script archives current `/tmp/*.log` files into `/tmp/logs-archive/` and truncates the live files in place so active writers keep working.\n\nTo inspect archived logs:\n\n```bash\nls -lh /tmp/logs-archive/\n```\n\nManual truncation is still possible for local development, but it is a deliberately destructive cleanup step:\n\n```bash\n\u003e /tmp/backend.log\n\u003e /tmp/frontend.log\n\u003e /tmp/dev-start.log\n\u003e /tmp/post-start.log\n```\n\nUse that only when you intentionally want to discard the current local log history.\n\n### Practical Local Triage Order\n\nFor the supported dev workflow, a reasonable first pass is:\n\n1. run `./scripts/logs`\n2. verify the expected dev processes or ports if the summary looks wrong\n3. search `/tmp/*.log` for the concrete failure signal\n4. restart with `./scripts/dev-stop \u0026\u0026 ./scripts/dev-start` if the issue is clearly local-process state rather than a code defect\n\n## Version Sync\n\nWhen you change `VERSION`, run the sync script and review all resulting metadata changes together.\n\n```bash\n./scripts/sync-version\n```\n\nThat workflow updates the frontend and companion package metadata and related version-bearing files.\n\n## Command Selection Rule of Thumb\n\n- smallest relevant change: run the checks for the area you changed\n- cross-boundary change: run checks for every touched subsystem\n- dependency or versioning change: run the affected subsystem checks plus the sync workflow if `VERSION` changed\n\nFor companion-native changes that affect packaging, Windows-specific crates, or Tauri platform integration, include the Windows GNU cross-check in the local validation set even when you are not creating release artifacts.\n\nFor the broader validation strategy and how to choose depth, continue to [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/).\n", "2.0": "+++\ntitle = \"Common Task Commands\"\n+++\n\nPrefer the committed scripts and workspace tasks over improvised one-off commands.\n\n## Daily Entry Points\n\n| Goal | Preferred command or task |\n|---|---|\n| Start backend dev server | VS Code task `Backend: Start Dev Server` or `./scripts/start-backend` |\n| Start frontend dev server | VS Code task `Frontend: Start Dev Server` or `./scripts/start-frontend` |\n| Start both local dev servers together | `./scripts/dev-start` |\n| Stop local dev servers together | `./scripts/dev-stop` |\n| Inspect local dev logs | `./scripts/logs` |\n| Run fast repo tests | `./scripts/test` |\n| Run repo tests with coverage | `COVERAGE=1 ./scripts/test` |\n\n`./scripts/test` now includes the companion Windows GNU target compatibility check when the local toolchain is available.\nIn the devcontainer, that toolchain is preinstalled as part of the image build.\n\n## Backend Commands\n\nUse these when you are changing backend behavior, API contracts, or SMB handling.\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nUseful related task:\n\n- VS Code task `Backend: Run Tests`\n- VS Code task `Backend: Type Check (mypy)`\n\n## Frontend Commands\n\nUse these when the browser UI, routing, services, or typed frontend behavior changes.\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nUseful related task:\n\n- VS Code task `Frontend: Run Tests`\n- VS Code task `Frontend: Type Check + Lint`\n\n## Companion Commands\n\nUse these when local-drive access, native-app editing, or Tauri-side behavior changes.\n\n```bash\ncd companion \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run check:rust:windows\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nUse `npm run check:rust:windows` as a local Windows-target compatibility check.\nIt runs `cargo check` for `x86_64-pc-windows-gnu` from Linux and is intended to catch cross-target breakage early without replacing the real Windows release build.\n\nUseful related task:\n\n- VS Code task `Companion: Run Rust Tests`\n- VS Code task `Companion: Validation Suite`\n\nThe committed devcontainer image now includes:\n\n- the Rust target `x86_64-pc-windows-gnu`\n- the MinGW toolchain package `gcc-mingw-w64-x86-64`\n\nThat means a rebuilt devcontainer can run the companion Windows GNU cross-check without extra manual setup.\n\n## Local Dev Logs and Service Control\n\nUse the committed helper scripts first when you are diagnosing the supported local development workflow.\n\n### Combined Dev Server Control\n\nThese scripts manage the local backend and frontend together:\n\n```bash\n./scripts/dev-start\n./scripts/dev-stop\n./scripts/dev-stop \u0026\u0026 ./scripts/dev-start\n```\n\nUse those entry points when you want the repo's own startup logging and local log-file layout instead of ad hoc process control.\n\n### Log Inspection\n\nThe supported local log viewer is:\n\n```bash\n./scripts/logs\n./scripts/logs -f\n./scripts/logs -n 200\n```\n\nThat script summarizes service status and tails the main local development log files.\n\nThe current local log files are:\n\n- `/tmp/backend.log`\n- `/tmp/frontend.log`\n- `/tmp/dev-start.log`\n- `/tmp/post-start.log`\n\nYou can inspect individual files directly when needed:\n\n```bash\ntail -f /tmp/backend.log\ntail -f /tmp/frontend.log\ntail -f /tmp/dev-start.log\ntail -f /tmp/post-start.log\n```\n\n### Search and Status Checks\n\nWhen the helper scripts are not enough, targeted shell checks are still useful.\n\n```bash\npgrep -f \"uvicorn.*app.main:app\"\npgrep -f \"vite\"\nlsof -i :3000,8000\ngrep -i error /tmp/*.log\ngrep -i warning /tmp/*.log\ngrep -i smb /tmp/backend.log\ngrep -E \"\\([0-9]{4,}\\.[0-9]+ms\\)\" /tmp/backend.log\n```\n\nTreat these as diagnostics for the local development environment, not as the primary supported control surface.\n\nBe especially careful with broad `pkill -f vite`-style commands in a workspace that can also run website or companion dev servers.\n\n### Rotating and Clearing Local Logs\n\nWhen local logs become noisy, use the committed rotation script first:\n\n```bash\n./scripts/rotate-logs\n```\n\nThat script archives current `/tmp/*.log` files into `/tmp/logs-archive/` and truncates the live files in place so active writers keep working.\n\nTo inspect archived logs:\n\n```bash\nls -lh /tmp/logs-archive/\n```\n\nManual truncation is still possible for local development, but it is a deliberately destructive cleanup step:\n\n```bash\n\u003e /tmp/backend.log\n\u003e /tmp/frontend.log\n\u003e /tmp/dev-start.log\n\u003e /tmp/post-start.log\n```\n\nUse that only when you intentionally want to discard the current local log history.\n\n### Practical Local Triage Order\n\nFor the supported dev workflow, a reasonable first pass is:\n\n1. run `./scripts/logs`\n2. verify the expected dev processes or ports if the summary looks wrong\n3. search `/tmp/*.log` for the concrete failure signal\n4. restart with `./scripts/dev-stop \u0026\u0026 ./scripts/dev-start` if the issue is clearly local-process state rather than a code defect\n\n## Version Sync\n\nWhen you change `VERSION`, run the sync script and review all resulting metadata changes together.\n\n```bash\n./scripts/sync-version\n```\n\nThat workflow updates the frontend and companion package metadata and related version-bearing files.\n\n## Command Selection Rule of Thumb\n\n- smallest relevant change: run the checks for the area you changed\n- cross-boundary change: run checks for every touched subsystem\n- dependency or versioning change: run the affected subsystem checks plus the sync workflow if `VERSION` changed\n\nFor companion-native changes that affect packaging, Windows-specific crates, or Tauri platform integration, include the Windows GNU cross-check in the local validation set even when you are not creating release artifacts.\n\nFor the broader validation strategy and how to choose depth, continue to [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/).\n"}, "page_contents": {"0.7": "+++\ntitle = \"Common Task Commands\"\n+++\n\nPrefer the committed scripts and workspace tasks over improvised one-off commands.\n\n## Daily Entry Points\n\n| Goal | Preferred command or task |\n|---|---|\n| Start backend dev server | VS Code task `Backend: Start Dev Server` or `./scripts/start-backend` |\n| Start frontend dev server | VS Code task `Frontend: Start Dev Server` or `./scripts/start-frontend` |\n| Start both local dev servers together | `./scripts/dev-start` |\n| Stop local dev servers together | `./scripts/dev-stop` |\n| Inspect local dev logs | `./scripts/logs` |\n| Run fast repo tests | `./scripts/test` |\n| Run repo tests with coverage | `COVERAGE=1 ./scripts/test` |\n\n## Backend Commands\n\nUse these when you are changing backend behavior, API contracts, or SMB handling.\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nUseful related task:\n\n- VS Code task `Backend: Run Tests`\n- VS Code task `Backend: Type Check (mypy)`\n\n## Frontend Commands\n\nUse these when the browser UI, routing, services, or typed frontend behavior changes.\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nUseful related task:\n\n- VS Code task `Frontend: Run Tests`\n- VS Code task `Frontend: Type Check + Lint`\n\n## Companion Commands\n\nUse these when local-drive access, native-app editing, or Tauri-side behavior changes.\n\n```bash\ncd companion \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nUseful related task:\n\n- VS Code task `Companion: Run Rust Tests`\n- VS Code task `Companion: Validation Suite`\n\n## Local Dev Logs and Service Control\n\nUse the committed helper scripts first when you are diagnosing the supported local development workflow.\n\n### Combined Dev Server Control\n\nThese scripts manage the local backend and frontend together:\n\n```bash\n./scripts/dev-start\n./scripts/dev-stop\n./scripts/dev-stop \u0026\u0026 ./scripts/dev-start\n```\n\nUse those entry points when you want the repo's own startup logging and local log-file layout instead of ad hoc process control.\n\n### Log Inspection\n\nThe supported local log viewer is:\n\n```bash\n./scripts/logs\n./scripts/logs -f\n./scripts/logs -n 200\n```\n\nThat script summarizes service status and tails the main local development log files.\n\nThe current local log files are:\n\n- `/tmp/backend.log`\n- `/tmp/frontend.log`\n- `/tmp/dev-start.log`\n- `/tmp/post-start.log`\n\nYou can inspect individual files directly when needed:\n\n```bash\ntail -f /tmp/backend.log\ntail -f /tmp/frontend.log\ntail -f /tmp/dev-start.log\ntail -f /tmp/post-start.log\n```\n\n### Search and Status Checks\n\nWhen the helper scripts are not enough, targeted shell checks are still useful.\n\n```bash\npgrep -f \"uvicorn.*app.main:app\"\npgrep -f \"vite\"\nlsof -i :3000,8000\ngrep -i error /tmp/*.log\ngrep -i warning /tmp/*.log\ngrep -i smb /tmp/backend.log\ngrep -E \"\\([0-9]{4,}\\.[0-9]+ms\\)\" /tmp/backend.log\n```\n\nTreat these as diagnostics for the local development environment, not as the primary supported control surface.\n\nBe especially careful with broad `pkill -f vite`-style commands in a workspace that can also run website or companion dev servers.\n\n### Rotating and Clearing Local Logs\n\nWhen local logs become noisy, use the committed rotation script first:\n\n```bash\n./scripts/rotate-logs\n```\n\nThat script archives current `/tmp/*.log` files into `/tmp/logs-archive/` and truncates the live files in place so active writers keep working.\n\nTo inspect archived logs:\n\n```bash\nls -lh /tmp/logs-archive/\n```\n\nManual truncation is still possible for local development, but it is a deliberately destructive cleanup step:\n\n```bash\n\u003e /tmp/backend.log\n\u003e /tmp/frontend.log\n\u003e /tmp/dev-start.log\n\u003e /tmp/post-start.log\n```\n\nUse that only when you intentionally want to discard the current local log history.\n\n### Practical Local Triage Order\n\nFor the supported dev workflow, a reasonable first pass is:\n\n1. run `./scripts/logs`\n2. verify the expected dev processes or ports if the summary looks wrong\n3. search `/tmp/*.log` for the concrete failure signal\n4. restart with `./scripts/dev-stop \u0026\u0026 ./scripts/dev-start` if the issue is clearly local-process state rather than a code defect\n\n## Version Sync\n\nWhen you change `VERSION`, run the sync script and review all resulting metadata changes together.\n\n```bash\n./scripts/sync-version\n```\n\nThat workflow updates the frontend and companion package metadata and related version-bearing files.\n\n## Command Selection Rule of Thumb\n\n- smallest relevant change: run the checks for the area you changed\n- cross-boundary change: run checks for every touched subsystem\n- dependency or versioning change: run the affected subsystem checks plus the sync workflow if `VERSION` changed\n\nFor the broader validation strategy and how to choose depth, continue to [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/).\n", "0.8": "+++\ntitle = \"Common Task Commands\"\n+++\n\nPrefer the committed scripts and workspace tasks over improvised one-off commands.\n\n## Daily Entry Points\n\n| Goal | Preferred command or task |\n|---|---|\n| Start backend dev server | VS Code task `Backend: Start Dev Server` or `./scripts/start-backend` |\n| Start frontend dev server | VS Code task `Frontend: Start Dev Server` or `./scripts/start-frontend` |\n| Start both local dev servers together | `./scripts/dev-start` |\n| Stop local dev servers together | `./scripts/dev-stop` |\n| Inspect local dev logs | `./scripts/logs` |\n| Run fast repo tests | `./scripts/test` |\n| Run repo tests with coverage | `COVERAGE=1 ./scripts/test` |\n\n`./scripts/test` now includes the companion Windows GNU target compatibility check when the local toolchain is available.\nIn the devcontainer, that toolchain is preinstalled as part of the image build.\n\n## Backend Commands\n\nUse these when you are changing backend behavior, API contracts, or SMB handling.\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nUseful related task:\n\n- VS Code task `Backend: Run Tests`\n- VS Code task `Backend: Type Check (mypy)`\n\n## Frontend Commands\n\nUse these when the browser UI, routing, services, or typed frontend behavior changes.\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nUseful related task:\n\n- VS Code task `Frontend: Run Tests`\n- VS Code task `Frontend: Type Check + Lint`\n\n## Companion Commands\n\nUse these when local-drive access, native-app editing, or Tauri-side behavior changes.\n\n```bash\ncd companion \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run check:rust:windows\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nUse `npm run check:rust:windows` as a local Windows-target compatibility check.\nIt runs `cargo check` for `x86_64-pc-windows-gnu` from Linux and is intended to catch cross-target breakage early without replacing the real Windows release build.\n\nUseful related task:\n\n- VS Code task `Companion: Run Rust Tests`\n- VS Code task `Companion: Validation Suite`\n\nThe committed devcontainer image now includes:\n\n- the Rust target `x86_64-pc-windows-gnu`\n- the MinGW toolchain package `gcc-mingw-w64-x86-64`\n\nThat means a rebuilt devcontainer can run the companion Windows GNU cross-check without extra manual setup.\n\n## Local Dev Logs and Service Control\n\nUse the committed helper scripts first when you are diagnosing the supported local development workflow.\n\n### Combined Dev Server Control\n\nThese scripts manage the local backend and frontend together:\n\n```bash\n./scripts/dev-start\n./scripts/dev-stop\n./scripts/dev-stop \u0026\u0026 ./scripts/dev-start\n```\n\nUse those entry points when you want the repo's own startup logging and local log-file layout instead of ad hoc process control.\n\n### Log Inspection\n\nThe supported local log viewer is:\n\n```bash\n./scripts/logs\n./scripts/logs -f\n./scripts/logs -n 200\n```\n\nThat script summarizes service status and tails the main local development log files.\n\nThe current local log files are:\n\n- `/tmp/backend.log`\n- `/tmp/frontend.log`\n- `/tmp/dev-start.log`\n- `/tmp/post-start.log`\n\nYou can inspect individual files directly when needed:\n\n```bash\ntail -f /tmp/backend.log\ntail -f /tmp/frontend.log\ntail -f /tmp/dev-start.log\ntail -f /tmp/post-start.log\n```\n\n### Search and Status Checks\n\nWhen the helper scripts are not enough, targeted shell checks are still useful.\n\n```bash\npgrep -f \"uvicorn.*app.main:app\"\npgrep -f \"vite\"\nlsof -i :3000,8000\ngrep -i error /tmp/*.log\ngrep -i warning /tmp/*.log\ngrep -i smb /tmp/backend.log\ngrep -E \"\\([0-9]{4,}\\.[0-9]+ms\\)\" /tmp/backend.log\n```\n\nTreat these as diagnostics for the local development environment, not as the primary supported control surface.\n\nBe especially careful with broad `pkill -f vite`-style commands in a workspace that can also run website or companion dev servers.\n\n### Rotating and Clearing Local Logs\n\nWhen local logs become noisy, use the committed rotation script first:\n\n```bash\n./scripts/rotate-logs\n```\n\nThat script archives current `/tmp/*.log` files into `/tmp/logs-archive/` and truncates the live files in place so active writers keep working.\n\nTo inspect archived logs:\n\n```bash\nls -lh /tmp/logs-archive/\n```\n\nManual truncation is still possible for local development, but it is a deliberately destructive cleanup step:\n\n```bash\n\u003e /tmp/backend.log\n\u003e /tmp/frontend.log\n\u003e /tmp/dev-start.log\n\u003e /tmp/post-start.log\n```\n\nUse that only when you intentionally want to discard the current local log history.\n\n### Practical Local Triage Order\n\nFor the supported dev workflow, a reasonable first pass is:\n\n1. run `./scripts/logs`\n2. verify the expected dev processes or ports if the summary looks wrong\n3. search `/tmp/*.log` for the concrete failure signal\n4. restart with `./scripts/dev-stop \u0026\u0026 ./scripts/dev-start` if the issue is clearly local-process state rather than a code defect\n\n## Version Sync\n\nWhen you change `VERSION`, run the sync script and review all resulting metadata changes together.\n\n```bash\n./scripts/sync-version\n```\n\nThat workflow updates the frontend and companion package metadata and related version-bearing files.\n\n## Command Selection Rule of Thumb\n\n- smallest relevant change: run the checks for the area you changed\n- cross-boundary change: run checks for every touched subsystem\n- dependency or versioning change: run the affected subsystem checks plus the sync workflow if `VERSION` changed\n\nFor companion-native changes that affect packaging, Windows-specific crates, or Tauri platform integration, include the Windows GNU cross-check in the local validation set even when you are not creating release artifacts.\n\nFor the broader validation strategy and how to choose depth, continue to [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/).\n", "0.9": "+++\ntitle = \"Common Task Commands\"\n+++\n\nPrefer the committed scripts and workspace tasks over improvised one-off commands.\n\n## Daily Entry Points\n\n| Goal | Preferred command or task |\n|---|---|\n| Start backend dev server | VS Code task `Backend: Start Dev Server` or `./scripts/start-backend` |\n| Start frontend dev server | VS Code task `Frontend: Start Dev Server` or `./scripts/start-frontend` |\n| Start both local dev servers together | `./scripts/dev-start` |\n| Stop local dev servers together | `./scripts/dev-stop` |\n| Inspect local dev logs | `./scripts/logs` |\n| Run fast repo tests | `./scripts/test` |\n| Run repo tests with coverage | `COVERAGE=1 ./scripts/test` |\n\n`./scripts/test` now includes the companion Windows GNU target compatibility check when the local toolchain is available.\nIn the devcontainer, that toolchain is preinstalled as part of the image build.\n\n## Backend Commands\n\nUse these when you are changing backend behavior, API contracts, or SMB handling.\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nUseful related task:\n\n- VS Code task `Backend: Run Tests`\n- VS Code task `Backend: Type Check (mypy)`\n\n## Frontend Commands\n\nUse these when the browser UI, routing, services, or typed frontend behavior changes.\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nUseful related task:\n\n- VS Code task `Frontend: Run Tests`\n- VS Code task `Frontend: Type Check + Lint`\n\n## Companion Commands\n\nUse these when local-drive access, native-app editing, or Tauri-side behavior changes.\n\n```bash\ncd companion \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run check:rust:windows\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nUse `npm run check:rust:windows` as a local Windows-target compatibility check.\nIt runs `cargo check` for `x86_64-pc-windows-gnu` from Linux and is intended to catch cross-target breakage early without replacing the real Windows release build.\n\nUseful related task:\n\n- VS Code task `Companion: Run Rust Tests`\n- VS Code task `Companion: Validation Suite`\n\nThe committed devcontainer image now includes:\n\n- the Rust target `x86_64-pc-windows-gnu`\n- the MinGW toolchain package `gcc-mingw-w64-x86-64`\n\nThat means a rebuilt devcontainer can run the companion Windows GNU cross-check without extra manual setup.\n\n## Local Dev Logs and Service Control\n\nUse the committed helper scripts first when you are diagnosing the supported local development workflow.\n\n### Combined Dev Server Control\n\nThese scripts manage the local backend and frontend together:\n\n```bash\n./scripts/dev-start\n./scripts/dev-stop\n./scripts/dev-stop \u0026\u0026 ./scripts/dev-start\n```\n\nUse those entry points when you want the repo's own startup logging and local log-file layout instead of ad hoc process control.\n\n### Log Inspection\n\nThe supported local log viewer is:\n\n```bash\n./scripts/logs\n./scripts/logs -f\n./scripts/logs -n 200\n```\n\nThat script summarizes service status and tails the main local development log files.\n\nThe current local log files are:\n\n- `/tmp/backend.log`\n- `/tmp/frontend.log`\n- `/tmp/dev-start.log`\n- `/tmp/post-start.log`\n\nYou can inspect individual files directly when needed:\n\n```bash\ntail -f /tmp/backend.log\ntail -f /tmp/frontend.log\ntail -f /tmp/dev-start.log\ntail -f /tmp/post-start.log\n```\n\n### Search and Status Checks\n\nWhen the helper scripts are not enough, targeted shell checks are still useful.\n\n```bash\npgrep -f \"uvicorn.*app.main:app\"\npgrep -f \"vite\"\nlsof -i :3000,8000\ngrep -i error /tmp/*.log\ngrep -i warning /tmp/*.log\ngrep -i smb /tmp/backend.log\ngrep -E \"\\([0-9]{4,}\\.[0-9]+ms\\)\" /tmp/backend.log\n```\n\nTreat these as diagnostics for the local development environment, not as the primary supported control surface.\n\nBe especially careful with broad `pkill -f vite`-style commands in a workspace that can also run website or companion dev servers.\n\n### Rotating and Clearing Local Logs\n\nWhen local logs become noisy, use the committed rotation script first:\n\n```bash\n./scripts/rotate-logs\n```\n\nThat script archives current `/tmp/*.log` files into `/tmp/logs-archive/` and truncates the live files in place so active writers keep working.\n\nTo inspect archived logs:\n\n```bash\nls -lh /tmp/logs-archive/\n```\n\nManual truncation is still possible for local development, but it is a deliberately destructive cleanup step:\n\n```bash\n\u003e /tmp/backend.log\n\u003e /tmp/frontend.log\n\u003e /tmp/dev-start.log\n\u003e /tmp/post-start.log\n```\n\nUse that only when you intentionally want to discard the current local log history.\n\n### Practical Local Triage Order\n\nFor the supported dev workflow, a reasonable first pass is:\n\n1. run `./scripts/logs`\n2. verify the expected dev processes or ports if the summary looks wrong\n3. search `/tmp/*.log` for the concrete failure signal\n4. restart with `./scripts/dev-stop \u0026\u0026 ./scripts/dev-start` if the issue is clearly local-process state rather than a code defect\n\n## Version Sync\n\nWhen you change `VERSION`, run the sync script and review all resulting metadata changes together.\n\n```bash\n./scripts/sync-version\n```\n\nThat workflow updates the frontend and companion package metadata and related version-bearing files.\n\n## Command Selection Rule of Thumb\n\n- smallest relevant change: run the checks for the area you changed\n- cross-boundary change: run checks for every touched subsystem\n- dependency or versioning change: run the affected subsystem checks plus the sync workflow if `VERSION` changed\n\nFor companion-native changes that affect packaging, Windows-specific crates, or Tauri platform integration, include the Windows GNU cross-check in the local validation set even when you are not creating release artifacts.\n\nFor the broader validation strategy and how to choose depth, continue to [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/).\n", "1.0": "+++\ntitle = \"Common Task Commands\"\n+++\n\nPrefer the committed scripts and workspace tasks over improvised one-off commands.\n\n## Daily Entry Points\n\n| Goal | Preferred command or task |\n|---|---|\n| Start backend dev server | VS Code task `Backend: Start Dev Server` or `./scripts/start-backend` |\n| Start frontend dev server | VS Code task `Frontend: Start Dev Server` or `./scripts/start-frontend` |\n| Start both local dev servers together | `./scripts/dev-start` |\n| Stop local dev servers together | `./scripts/dev-stop` |\n| Inspect local dev logs | `./scripts/logs` |\n| Run fast repo tests | `./scripts/test` |\n| Run repo tests with coverage | `COVERAGE=1 ./scripts/test` |\n\n`./scripts/test` now includes the companion Windows GNU target compatibility check when the local toolchain is available.\nIn the devcontainer, that toolchain is preinstalled as part of the image build.\n\n## Backend Commands\n\nUse these when you are changing backend behavior, API contracts, or SMB handling.\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nUseful related task:\n\n- VS Code task `Backend: Run Tests`\n- VS Code task `Backend: Type Check (mypy)`\n\n## Frontend Commands\n\nUse these when the browser UI, routing, services, or typed frontend behavior changes.\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nUseful related task:\n\n- VS Code task `Frontend: Run Tests`\n- VS Code task `Frontend: Type Check + Lint`\n\n## Companion Commands\n\nUse these when local-drive access, native-app editing, or Tauri-side behavior changes.\n\n```bash\ncd companion \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run check:rust:windows\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nUse `npm run check:rust:windows` as a local Windows-target compatibility check.\nIt runs `cargo check` for `x86_64-pc-windows-gnu` from Linux and is intended to catch cross-target breakage early without replacing the real Windows release build.\n\nUseful related task:\n\n- VS Code task `Companion: Run Rust Tests`\n- VS Code task `Companion: Validation Suite`\n\nThe committed devcontainer image now includes:\n\n- the Rust target `x86_64-pc-windows-gnu`\n- the MinGW toolchain package `gcc-mingw-w64-x86-64`\n\nThat means a rebuilt devcontainer can run the companion Windows GNU cross-check without extra manual setup.\n\n## Local Dev Logs and Service Control\n\nUse the committed helper scripts first when you are diagnosing the supported local development workflow.\n\n### Combined Dev Server Control\n\nThese scripts manage the local backend and frontend together:\n\n```bash\n./scripts/dev-start\n./scripts/dev-stop\n./scripts/dev-stop \u0026\u0026 ./scripts/dev-start\n```\n\nUse those entry points when you want the repo's own startup logging and local log-file layout instead of ad hoc process control.\n\n### Log Inspection\n\nThe supported local log viewer is:\n\n```bash\n./scripts/logs\n./scripts/logs -f\n./scripts/logs -n 200\n```\n\nThat script summarizes service status and tails the main local development log files.\n\nThe current local log files are:\n\n- `/tmp/backend.log`\n- `/tmp/frontend.log`\n- `/tmp/dev-start.log`\n- `/tmp/post-start.log`\n\nYou can inspect individual files directly when needed:\n\n```bash\ntail -f /tmp/backend.log\ntail -f /tmp/frontend.log\ntail -f /tmp/dev-start.log\ntail -f /tmp/post-start.log\n```\n\n### Search and Status Checks\n\nWhen the helper scripts are not enough, targeted shell checks are still useful.\n\n```bash\npgrep -f \"uvicorn.*app.main:app\"\npgrep -f \"vite\"\nlsof -i :3000,8000\ngrep -i error /tmp/*.log\ngrep -i warning /tmp/*.log\ngrep -i smb /tmp/backend.log\ngrep -E \"\\([0-9]{4,}\\.[0-9]+ms\\)\" /tmp/backend.log\n```\n\nTreat these as diagnostics for the local development environment, not as the primary supported control surface.\n\nBe especially careful with broad `pkill -f vite`-style commands in a workspace that can also run website or companion dev servers.\n\n### Rotating and Clearing Local Logs\n\nWhen local logs become noisy, use the committed rotation script first:\n\n```bash\n./scripts/rotate-logs\n```\n\nThat script archives current `/tmp/*.log` files into `/tmp/logs-archive/` and truncates the live files in place so active writers keep working.\n\nTo inspect archived logs:\n\n```bash\nls -lh /tmp/logs-archive/\n```\n\nManual truncation is still possible for local development, but it is a deliberately destructive cleanup step:\n\n```bash\n\u003e /tmp/backend.log\n\u003e /tmp/frontend.log\n\u003e /tmp/dev-start.log\n\u003e /tmp/post-start.log\n```\n\nUse that only when you intentionally want to discard the current local log history.\n\n### Practical Local Triage Order\n\nFor the supported dev workflow, a reasonable first pass is:\n\n1. run `./scripts/logs`\n2. verify the expected dev processes or ports if the summary looks wrong\n3. search `/tmp/*.log` for the concrete failure signal\n4. restart with `./scripts/dev-stop \u0026\u0026 ./scripts/dev-start` if the issue is clearly local-process state rather than a code defect\n\n## Version Sync\n\nWhen you change `VERSION`, run the sync script and review all resulting metadata changes together.\n\n```bash\n./scripts/sync-version\n```\n\nThat workflow updates the frontend and companion package metadata and related version-bearing files.\n\n## Command Selection Rule of Thumb\n\n- smallest relevant change: run the checks for the area you changed\n- cross-boundary change: run checks for every touched subsystem\n- dependency or versioning change: run the affected subsystem checks plus the sync workflow if `VERSION` changed\n\nFor companion-native changes that affect packaging, Windows-specific crates, or Tauri platform integration, include the Windows GNU cross-check in the local validation set even when you are not creating release artifacts.\n\nFor the broader validation strategy and how to choose depth, continue to [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/).\n", "2.0": "+++\ntitle = \"Common Task Commands\"\n+++\n\nPrefer the committed scripts and workspace tasks over improvised one-off commands.\n\n## Daily Entry Points\n\n| Goal | Preferred command or task |\n|---|---|\n| Start backend dev server | VS Code task `Backend: Start Dev Server` or `./scripts/start-backend` |\n| Start frontend dev server | VS Code task `Frontend: Start Dev Server` or `./scripts/start-frontend` |\n| Start both local dev servers together | `./scripts/dev-start` |\n| Stop local dev servers together | `./scripts/dev-stop` |\n| Inspect local dev logs | `./scripts/logs` |\n| Run fast repo tests | `./scripts/test` |\n| Run repo tests with coverage | `COVERAGE=1 ./scripts/test` |\n\n`./scripts/test` now includes the companion Windows GNU target compatibility check when the local toolchain is available.\nIn the devcontainer, that toolchain is preinstalled as part of the image build.\n\n## Backend Commands\n\nUse these when you are changing backend behavior, API contracts, or SMB handling.\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nUseful related task:\n\n- VS Code task `Backend: Run Tests`\n- VS Code task `Backend: Type Check (mypy)`\n\n## Frontend Commands\n\nUse these when the browser UI, routing, services, or typed frontend behavior changes.\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nUseful related task:\n\n- VS Code task `Frontend: Run Tests`\n- VS Code task `Frontend: Type Check + Lint`\n\n## Companion Commands\n\nUse these when local-drive access, native-app editing, or Tauri-side behavior changes.\n\n```bash\ncd companion \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run check:rust:windows\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nUse `npm run check:rust:windows` as a local Windows-target compatibility check.\nIt runs `cargo check` for `x86_64-pc-windows-gnu` from Linux and is intended to catch cross-target breakage early without replacing the real Windows release build.\n\nUseful related task:\n\n- VS Code task `Companion: Run Rust Tests`\n- VS Code task `Companion: Validation Suite`\n\nThe committed devcontainer image now includes:\n\n- the Rust target `x86_64-pc-windows-gnu`\n- the MinGW toolchain package `gcc-mingw-w64-x86-64`\n\nThat means a rebuilt devcontainer can run the companion Windows GNU cross-check without extra manual setup.\n\n## Local Dev Logs and Service Control\n\nUse the committed helper scripts first when you are diagnosing the supported local development workflow.\n\n### Combined Dev Server Control\n\nThese scripts manage the local backend and frontend together:\n\n```bash\n./scripts/dev-start\n./scripts/dev-stop\n./scripts/dev-stop \u0026\u0026 ./scripts/dev-start\n```\n\nUse those entry points when you want the repo's own startup logging and local log-file layout instead of ad hoc process control.\n\n### Log Inspection\n\nThe supported local log viewer is:\n\n```bash\n./scripts/logs\n./scripts/logs -f\n./scripts/logs -n 200\n```\n\nThat script summarizes service status and tails the main local development log files.\n\nThe current local log files are:\n\n- `/tmp/backend.log`\n- `/tmp/frontend.log`\n- `/tmp/dev-start.log`\n- `/tmp/post-start.log`\n\nYou can inspect individual files directly when needed:\n\n```bash\ntail -f /tmp/backend.log\ntail -f /tmp/frontend.log\ntail -f /tmp/dev-start.log\ntail -f /tmp/post-start.log\n```\n\n### Search and Status Checks\n\nWhen the helper scripts are not enough, targeted shell checks are still useful.\n\n```bash\npgrep -f \"uvicorn.*app.main:app\"\npgrep -f \"vite\"\nlsof -i :3000,8000\ngrep -i error /tmp/*.log\ngrep -i warning /tmp/*.log\ngrep -i smb /tmp/backend.log\ngrep -E \"\\([0-9]{4,}\\.[0-9]+ms\\)\" /tmp/backend.log\n```\n\nTreat these as diagnostics for the local development environment, not as the primary supported control surface.\n\nBe especially careful with broad `pkill -f vite`-style commands in a workspace that can also run website or companion dev servers.\n\n### Rotating and Clearing Local Logs\n\nWhen local logs become noisy, use the committed rotation script first:\n\n```bash\n./scripts/rotate-logs\n```\n\nThat script archives current `/tmp/*.log` files into `/tmp/logs-archive/` and truncates the live files in place so active writers keep working.\n\nTo inspect archived logs:\n\n```bash\nls -lh /tmp/logs-archive/\n```\n\nManual truncation is still possible for local development, but it is a deliberately destructive cleanup step:\n\n```bash\n\u003e /tmp/backend.log\n\u003e /tmp/frontend.log\n\u003e /tmp/dev-start.log\n\u003e /tmp/post-start.log\n```\n\nUse that only when you intentionally want to discard the current local log history.\n\n### Practical Local Triage Order\n\nFor the supported dev workflow, a reasonable first pass is:\n\n1. run `./scripts/logs`\n2. verify the expected dev processes or ports if the summary looks wrong\n3. search `/tmp/*.log` for the concrete failure signal\n4. restart with `./scripts/dev-stop \u0026\u0026 ./scripts/dev-start` if the issue is clearly local-process state rather than a code defect\n\n## Version Sync\n\nWhen you change `VERSION`, run the sync script and review all resulting metadata changes together.\n\n```bash\n./scripts/sync-version\n```\n\nThat workflow updates the frontend and companion package metadata and related version-bearing files.\n\n## Command Selection Rule of Thumb\n\n- smallest relevant change: run the checks for the area you changed\n- cross-boundary change: run checks for every touched subsystem\n- dependency or versioning change: run the affected subsystem checks plus the sync workflow if `VERSION` changed\n\nFor companion-native changes that affect packaging, Windows-specific crates, or Tauri platform integration, include the Windows GNU cross-check in the local validation set even when you are not creating release artifacts.\n\nFor the broader validation strategy and how to choose depth, continue to [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/).\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:developer-guide/backend-architecture", "parent_id": "book:developer-guide", "depth": 1, "kind": "section", "label": "backend-architecture", "title": "Backend Architecture", "path": "developer-guide/backend-architecture", "has_children": true, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Backend Architecture\"\n+++\n\nThe backend is where Sambee's server-side behavior becomes real: authentication, API shape, SMB access, file operations, edit locks, and change notifications all converge here.\n\nStart with:\n\n- [Backend Overview](./backend-overview/)\n- [Request Flow and Service Boundaries](./request-flow-and-service-boundaries/)\n- [Image Preprocessing and Conversion Pipeline](./image-preprocessing-and-conversion-pipeline/)\n- [SMB Change Notification and Directory Freshness](./smb-change-notification-and-directory-freshness/)\n- [File Operations and Edit Locking](./file-operations-and-edit-locking/)\n\nUse this section before you change browser-visible behavior that depends on the API, SMB semantics, or server-side validation.\n", "0.8": "+++\ntitle = \"Backend Architecture\"\n+++\n\nThe backend is where Sambee's server-side behavior becomes real: authentication, API shape, SMB access, file operations, edit locks, and change notifications all converge here.\n\nStart with:\n\n- [Backend Overview](./backend-overview/)\n- [Request Flow and Service Boundaries](./request-flow-and-service-boundaries/)\n- [Image Preprocessing and Conversion Pipeline](./image-preprocessing-and-conversion-pipeline/)\n- [SMB Change Notification and Directory Freshness](./smb-change-notification-and-directory-freshness/)\n- [File Operations and Edit Locking](./file-operations-and-edit-locking/)\n\nUse this section before you change browser-visible behavior that depends on the API, SMB semantics, or server-side validation.\n", "0.9": "+++\ntitle = \"Backend Architecture\"\n+++\n\nThe backend is where Sambee's server-side behavior becomes real: authentication, API shape, SMB access, file operations, edit locks, and change notifications all converge here.\n\nStart with:\n\n- [Backend Overview](./backend-overview/)\n- [Request Flow and Service Boundaries](./request-flow-and-service-boundaries/)\n- [Image Preprocessing and Conversion Pipeline](./image-preprocessing-and-conversion-pipeline/)\n- [SMB Change Notification and Directory Freshness](./smb-change-notification-and-directory-freshness/)\n- [File Operations and Edit Locking](./file-operations-and-edit-locking/)\n\nUse this section before you change browser-visible behavior that depends on the API, SMB semantics, or server-side validation.\n", "1.0": "+++\ntitle = \"Backend Architecture\"\n+++\n\nThe backend is where Sambee's server-side behavior becomes real: authentication, API shape, SMB access, file operations, edit locks, and change notifications all converge here.\n\nStart with:\n\n- [Backend Overview](./backend-overview/)\n- [Request Flow and Service Boundaries](./request-flow-and-service-boundaries/)\n- [Image Preprocessing and Conversion Pipeline](./image-preprocessing-and-conversion-pipeline/)\n- [SMB Change Notification and Directory Freshness](./smb-change-notification-and-directory-freshness/)\n- [File Operations and Edit Locking](./file-operations-and-edit-locking/)\n\nUse this section before you change browser-visible behavior that depends on the API, SMB semantics, or server-side validation.\n", "2.0": "+++\ntitle = \"Backend Architecture\"\n+++\n\nThe backend is where Sambee's server-side behavior becomes real: authentication, API shape, SMB access, file operations, edit locks, and change notifications all converge here.\n\nStart with:\n\n- [Backend Overview](./backend-overview/)\n- [Request Flow and Service Boundaries](./request-flow-and-service-boundaries/)\n- [Image Preprocessing and Conversion Pipeline](./image-preprocessing-and-conversion-pipeline/)\n- [SMB Change Notification and Directory Freshness](./smb-change-notification-and-directory-freshness/)\n- [File Operations and Edit Locking](./file-operations-and-edit-locking/)\n\nUse this section before you change browser-visible behavior that depends on the API, SMB semantics, or server-side validation.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/backend-architecture/backend-overview", "parent_id": "section:developer-guide/backend-architecture", "depth": 2, "kind": "page", "label": "backend-overview", "title": "Backend Overview", "path": "developer-guide/backend-architecture/backend-overview", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Backend Overview\"\n+++\n\nThe backend is the policy and integration layer between the browser-facing product and the storage systems Sambee works with.\n\n## What the Backend Owns\n\nThe backend is responsible for:\n\n- authentication and authorization\n- API endpoints consumed by the browser app and companion flows\n- SMB access and server-side file operations\n- server-side preview and download behavior where the product needs it\n- edit-lock and conflict-handling behavior for companion-assisted editing\n- directory-change notification and other state that must stay authoritative on the server side\n\n## Main Code Areas\n\nThe exact module layout evolves, but the backend is organized around a few stable concerns.\n\n| Area | Responsibility |\n|---|---|\n| `backend/app/api/` | request handlers and HTTP-facing endpoints |\n| `backend/app/models/` | API and domain models used across request and response boundaries |\n| `backend/app/storage/` | storage backends and storage-facing behavior, including SMB access |\n| `backend/app/services/` | longer-running or cross-cutting service behavior such as monitoring and background coordination |\n| `backend/app/db/` | database setup and models for persisted application state |\n| `backend/tests/` | pytest coverage for server behavior and contracts |\n\n## Request and Storage Flow\n\nFor the common SMB flow:\n\n1. The frontend issues an authenticated API request.\n2. The backend validates input and permissions.\n3. The backend performs the requested SMB operation through the storage layer.\n4. The backend returns a typed response the frontend or companion can rely on.\n\nThis is why the backend, not the browser, is the source of truth for SMB semantics and conflict-sensitive operations.\n\nIf you need the detailed layer breakdown, continue to [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/).\n\n## Important Backend Contracts\n\n### API Contract Stability\n\nThe frontend relies on typed request and response shapes. That is why contract testing guidance exists and why contributors should treat API shape changes as user-visible changes, not internal refactors.\n\n### File-Type and Preview Behavior\n\nThe backend contributes to preview behavior through MIME detection, file-type classification, and conversion decisions for formats that are not natively browser-friendly. Those rules have to stay aligned with frontend expectations.\n\n### Edit Locking and Companion Flows\n\nFor companion-assisted editing of SMB-backed files, the backend owns the server-side lock, heartbeat, upload, and conflict rules. A desktop-side improvement that ignores those rules can easily create data-loss regressions.\n\nFor the full lifecycle, continue to [File Operations and Edit Locking](../file-operations-and-edit-locking/).\n\n### Change Notification\n\nThe backend also owns SMB-side change monitoring and the notifications that tell browser clients when directory state should refresh.\n\nFor the watcher architecture, subscriber model, and cache-freshness split, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## What Usually Breaks When This Layer Changes\n\n- frontend assumptions about response shape\n- viewer or file-management behavior that depends on MIME or category detection\n- companion editing flows that depend on lock or upload semantics\n- directory freshness in the browser when change notifications stop matching product expectations\n\n## Go Deeper\n\n- [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/): how API, models, storage, services, and WebSocket coordination fit together\n- [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/): how backend watchers, WebSocket notifications, and cache freshness fit together\n- [File Operations and Edit Locking](../file-operations-and-edit-locking/): how ordinary file operations differ from companion-assisted SMB editing and lock handling\n\n## Validation Expectations\n\nWhen the backend changes, start with:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nThen add frontend or companion checks if the backend change affects a shared contract.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) for the broader decision rule.\n", "0.8": "+++\ntitle = \"Backend Overview\"\n+++\n\nThe backend is the policy and integration layer between the browser-facing product and the storage systems Sambee works with.\n\n## What the Backend Owns\n\nThe backend is responsible for:\n\n- authentication and authorization\n- API endpoints consumed by the browser app and companion flows\n- SMB access and server-side file operations\n- server-side preview and download behavior where the product needs it\n- edit-lock and conflict-handling behavior for companion-assisted editing\n- directory-change notification and other state that must stay authoritative on the server side\n\n## Main Code Areas\n\nThe exact module layout evolves, but the backend is organized around a few stable concerns.\n\n| Area | Responsibility |\n|---|---|\n| `backend/app/api/` | request handlers and HTTP-facing endpoints |\n| `backend/app/models/` | API and domain models used across request and response boundaries |\n| `backend/app/storage/` | storage backends and storage-facing behavior, including SMB access |\n| `backend/app/services/` | longer-running or cross-cutting service behavior such as monitoring and background coordination |\n| `backend/app/db/` | database setup and models for persisted application state |\n| `backend/tests/` | pytest coverage for server behavior and contracts |\n\n## Request and Storage Flow\n\nFor the common SMB flow:\n\n1. The frontend issues an authenticated API request.\n2. The backend validates input and permissions.\n3. The backend performs the requested SMB operation through the storage layer.\n4. The backend returns a typed response the frontend or companion can rely on.\n\nThis is why the backend, not the browser, is the source of truth for SMB semantics and conflict-sensitive operations.\n\nIf you need the detailed layer breakdown, continue to [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/).\n\n## Important Backend Contracts\n\n### API Contract Stability\n\nThe frontend relies on typed request and response shapes. That is why contract testing guidance exists and why contributors should treat API shape changes as user-visible changes, not internal refactors.\n\n### File-Type and Preview Behavior\n\nThe backend contributes to preview behavior through MIME detection, file-type classification, and conversion decisions for formats that are not natively browser-friendly. Those rules have to stay aligned with frontend expectations.\n\n### Edit Locking and Companion Flows\n\nFor companion-assisted editing of SMB-backed files, the backend owns the server-side lock, heartbeat, upload, and conflict rules. A desktop-side improvement that ignores those rules can easily create data-loss regressions.\n\nFor the full lifecycle, continue to [File Operations and Edit Locking](../file-operations-and-edit-locking/).\n\n### Change Notification\n\nThe backend also owns SMB-side change monitoring and the notifications that tell browser clients when directory state should refresh.\n\nFor the watcher architecture, subscriber model, and cache-freshness split, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## What Usually Breaks When This Layer Changes\n\n- frontend assumptions about response shape\n- viewer or file-management behavior that depends on MIME or category detection\n- companion editing flows that depend on lock or upload semantics\n- directory freshness in the browser when change notifications stop matching product expectations\n\n## Go Deeper\n\n- [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/): how API, models, storage, services, and WebSocket coordination fit together\n- [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/): how backend watchers, WebSocket notifications, and cache freshness fit together\n- [File Operations and Edit Locking](../file-operations-and-edit-locking/): how ordinary file operations differ from companion-assisted SMB editing and lock handling\n\n## Validation Expectations\n\nWhen the backend changes, start with:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nThen add frontend or companion checks if the backend change affects a shared contract.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) for the broader decision rule.\n", "0.9": "+++\ntitle = \"Backend Overview\"\n+++\n\nThe backend is the policy and integration layer between the browser-facing product and the storage systems Sambee works with.\n\n## What the Backend Owns\n\nThe backend is responsible for:\n\n- authentication and authorization\n- API endpoints consumed by the browser app and companion flows\n- SMB access and server-side file operations\n- server-side preview and download behavior where the product needs it\n- edit-lock and conflict-handling behavior for companion-assisted editing\n- directory-change notification and other state that must stay authoritative on the server side\n\n## Main Code Areas\n\nThe exact module layout evolves, but the backend is organized around a few stable concerns.\n\n| Area | Responsibility |\n|---|---|\n| `backend/app/api/` | request handlers and HTTP-facing endpoints |\n| `backend/app/models/` | API and domain models used across request and response boundaries |\n| `backend/app/storage/` | storage backends and storage-facing behavior, including SMB access |\n| `backend/app/services/` | longer-running or cross-cutting service behavior such as monitoring and background coordination |\n| `backend/app/db/` | database setup and models for persisted application state |\n| `backend/tests/` | pytest coverage for server behavior and contracts |\n\n## Request and Storage Flow\n\nFor the common SMB flow:\n\n1. The frontend issues an authenticated API request.\n2. The backend validates input and permissions.\n3. The backend performs the requested SMB operation through the storage layer.\n4. The backend returns a typed response the frontend or companion can rely on.\n\nThis is why the backend, not the browser, is the source of truth for SMB semantics and conflict-sensitive operations.\n\nIf you need the detailed layer breakdown, continue to [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/).\n\n## Important Backend Contracts\n\n### API Contract Stability\n\nThe frontend relies on typed request and response shapes. That is why contract testing guidance exists and why contributors should treat API shape changes as user-visible changes, not internal refactors.\n\n### File-Type and Preview Behavior\n\nThe backend contributes to preview behavior through MIME detection, file-type classification, and conversion decisions for formats that are not natively browser-friendly. Those rules have to stay aligned with frontend expectations.\n\n### Edit Locking and Companion Flows\n\nFor companion-assisted editing of SMB-backed files, the backend owns the server-side lock, heartbeat, upload, and conflict rules. A desktop-side improvement that ignores those rules can easily create data-loss regressions.\n\nFor the full lifecycle, continue to [File Operations and Edit Locking](../file-operations-and-edit-locking/).\n\n### Change Notification\n\nThe backend also owns SMB-side change monitoring and the notifications that tell browser clients when directory state should refresh.\n\nFor the watcher architecture, subscriber model, and cache-freshness split, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## What Usually Breaks When This Layer Changes\n\n- frontend assumptions about response shape\n- viewer or file-management behavior that depends on MIME or category detection\n- companion editing flows that depend on lock or upload semantics\n- directory freshness in the browser when change notifications stop matching product expectations\n\n## Go Deeper\n\n- [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/): how API, models, storage, services, and WebSocket coordination fit together\n- [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/): how backend watchers, WebSocket notifications, and cache freshness fit together\n- [File Operations and Edit Locking](../file-operations-and-edit-locking/): how ordinary file operations differ from companion-assisted SMB editing and lock handling\n\n## Validation Expectations\n\nWhen the backend changes, start with:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nThen add frontend or companion checks if the backend change affects a shared contract.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) for the broader decision rule.\n", "1.0": "+++\ntitle = \"Backend Overview\"\n+++\n\nThe backend is the policy and integration layer between the browser-facing product and the storage systems Sambee works with.\n\n## What the Backend Owns\n\nThe backend is responsible for:\n\n- authentication and authorization\n- API endpoints consumed by the browser app and companion flows\n- SMB access and server-side file operations\n- server-side preview and download behavior where the product needs it\n- edit-lock and conflict-handling behavior for companion-assisted editing\n- directory-change notification and other state that must stay authoritative on the server side\n\n## Main Code Areas\n\nThe exact module layout evolves, but the backend is organized around a few stable concerns.\n\n| Area | Responsibility |\n|---|---|\n| `backend/app/api/` | request handlers and HTTP-facing endpoints |\n| `backend/app/models/` | API and domain models used across request and response boundaries |\n| `backend/app/storage/` | storage backends and storage-facing behavior, including SMB access |\n| `backend/app/services/` | longer-running or cross-cutting service behavior such as monitoring and background coordination |\n| `backend/app/db/` | database setup and models for persisted application state |\n| `backend/tests/` | pytest coverage for server behavior and contracts |\n\n## Request and Storage Flow\n\nFor the common SMB flow:\n\n1. The frontend issues an authenticated API request.\n2. The backend validates input and permissions.\n3. The backend performs the requested SMB operation through the storage layer.\n4. The backend returns a typed response the frontend or companion can rely on.\n\nThis is why the backend, not the browser, is the source of truth for SMB semantics and conflict-sensitive operations.\n\nIf you need the detailed layer breakdown, continue to [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/).\n\n## Important Backend Contracts\n\n### API Contract Stability\n\nThe frontend relies on typed request and response shapes. That is why contract testing guidance exists and why contributors should treat API shape changes as user-visible changes, not internal refactors.\n\n### File-Type and Preview Behavior\n\nThe backend contributes to preview behavior through MIME detection, file-type classification, and conversion decisions for formats that are not natively browser-friendly. Those rules have to stay aligned with frontend expectations.\n\n### Edit Locking and Companion Flows\n\nFor companion-assisted editing of SMB-backed files, the backend owns the server-side lock, heartbeat, upload, and conflict rules. A desktop-side improvement that ignores those rules can easily create data-loss regressions.\n\nFor the full lifecycle, continue to [File Operations and Edit Locking](../file-operations-and-edit-locking/).\n\n### Change Notification\n\nThe backend also owns SMB-side change monitoring and the notifications that tell browser clients when directory state should refresh.\n\nFor the watcher architecture, subscriber model, and cache-freshness split, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## What Usually Breaks When This Layer Changes\n\n- frontend assumptions about response shape\n- viewer or file-management behavior that depends on MIME or category detection\n- companion editing flows that depend on lock or upload semantics\n- directory freshness in the browser when change notifications stop matching product expectations\n\n## Go Deeper\n\n- [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/): how API, models, storage, services, and WebSocket coordination fit together\n- [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/): how backend watchers, WebSocket notifications, and cache freshness fit together\n- [File Operations and Edit Locking](../file-operations-and-edit-locking/): how ordinary file operations differ from companion-assisted SMB editing and lock handling\n\n## Validation Expectations\n\nWhen the backend changes, start with:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nThen add frontend or companion checks if the backend change affects a shared contract.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) for the broader decision rule.\n", "2.0": "+++\ntitle = \"Backend Overview\"\n+++\n\nThe backend is the policy and integration layer between the browser-facing product and the storage systems Sambee works with.\n\n## What the Backend Owns\n\nThe backend is responsible for:\n\n- authentication and authorization\n- API endpoints consumed by the browser app and companion flows\n- SMB access and server-side file operations\n- server-side preview and download behavior where the product needs it\n- edit-lock and conflict-handling behavior for companion-assisted editing\n- directory-change notification and other state that must stay authoritative on the server side\n\n## Main Code Areas\n\nThe exact module layout evolves, but the backend is organized around a few stable concerns.\n\n| Area | Responsibility |\n|---|---|\n| `backend/app/api/` | request handlers and HTTP-facing endpoints |\n| `backend/app/models/` | API and domain models used across request and response boundaries |\n| `backend/app/storage/` | storage backends and storage-facing behavior, including SMB access |\n| `backend/app/services/` | longer-running or cross-cutting service behavior such as monitoring and background coordination |\n| `backend/app/db/` | database setup and models for persisted application state |\n| `backend/tests/` | pytest coverage for server behavior and contracts |\n\n## Request and Storage Flow\n\nFor the common SMB flow:\n\n1. The frontend issues an authenticated API request.\n2. The backend validates input and permissions.\n3. The backend performs the requested SMB operation through the storage layer.\n4. The backend returns a typed response the frontend or companion can rely on.\n\nThis is why the backend, not the browser, is the source of truth for SMB semantics and conflict-sensitive operations.\n\nIf you need the detailed layer breakdown, continue to [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/).\n\n## Important Backend Contracts\n\n### API Contract Stability\n\nThe frontend relies on typed request and response shapes. That is why contract testing guidance exists and why contributors should treat API shape changes as user-visible changes, not internal refactors.\n\n### File-Type and Preview Behavior\n\nThe backend contributes to preview behavior through MIME detection, file-type classification, and conversion decisions for formats that are not natively browser-friendly. Those rules have to stay aligned with frontend expectations.\n\n### Edit Locking and Companion Flows\n\nFor companion-assisted editing of SMB-backed files, the backend owns the server-side lock, heartbeat, upload, and conflict rules. A desktop-side improvement that ignores those rules can easily create data-loss regressions.\n\nFor the full lifecycle, continue to [File Operations and Edit Locking](../file-operations-and-edit-locking/).\n\n### Change Notification\n\nThe backend also owns SMB-side change monitoring and the notifications that tell browser clients when directory state should refresh.\n\nFor the watcher architecture, subscriber model, and cache-freshness split, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## What Usually Breaks When This Layer Changes\n\n- frontend assumptions about response shape\n- viewer or file-management behavior that depends on MIME or category detection\n- companion editing flows that depend on lock or upload semantics\n- directory freshness in the browser when change notifications stop matching product expectations\n\n## Go Deeper\n\n- [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/): how API, models, storage, services, and WebSocket coordination fit together\n- [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/): how backend watchers, WebSocket notifications, and cache freshness fit together\n- [File Operations and Edit Locking](../file-operations-and-edit-locking/): how ordinary file operations differ from companion-assisted SMB editing and lock handling\n\n## Validation Expectations\n\nWhen the backend changes, start with:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nThen add frontend or companion checks if the backend change affects a shared contract.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) for the broader decision rule.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Backend Overview\"\n+++\n\nThe backend is the policy and integration layer between the browser-facing product and the storage systems Sambee works with.\n\n## What the Backend Owns\n\nThe backend is responsible for:\n\n- authentication and authorization\n- API endpoints consumed by the browser app and companion flows\n- SMB access and server-side file operations\n- server-side preview and download behavior where the product needs it\n- edit-lock and conflict-handling behavior for companion-assisted editing\n- directory-change notification and other state that must stay authoritative on the server side\n\n## Main Code Areas\n\nThe exact module layout evolves, but the backend is organized around a few stable concerns.\n\n| Area | Responsibility |\n|---|---|\n| `backend/app/api/` | request handlers and HTTP-facing endpoints |\n| `backend/app/models/` | API and domain models used across request and response boundaries |\n| `backend/app/storage/` | storage backends and storage-facing behavior, including SMB access |\n| `backend/app/services/` | longer-running or cross-cutting service behavior such as monitoring and background coordination |\n| `backend/app/db/` | database setup and models for persisted application state |\n| `backend/tests/` | pytest coverage for server behavior and contracts |\n\n## Request and Storage Flow\n\nFor the common SMB flow:\n\n1. The frontend issues an authenticated API request.\n2. The backend validates input and permissions.\n3. The backend performs the requested SMB operation through the storage layer.\n4. The backend returns a typed response the frontend or companion can rely on.\n\nThis is why the backend, not the browser, is the source of truth for SMB semantics and conflict-sensitive operations.\n\nIf you need the detailed layer breakdown, continue to [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/).\n\n## Important Backend Contracts\n\n### API Contract Stability\n\nThe frontend relies on typed request and response shapes. That is why contract testing guidance exists and why contributors should treat API shape changes as user-visible changes, not internal refactors.\n\n### File-Type and Preview Behavior\n\nThe backend contributes to preview behavior through MIME detection, file-type classification, and conversion decisions for formats that are not natively browser-friendly. Those rules have to stay aligned with frontend expectations.\n\n### Edit Locking and Companion Flows\n\nFor companion-assisted editing of SMB-backed files, the backend owns the server-side lock, heartbeat, upload, and conflict rules. A desktop-side improvement that ignores those rules can easily create data-loss regressions.\n\nFor the full lifecycle, continue to [File Operations and Edit Locking](../file-operations-and-edit-locking/).\n\n### Change Notification\n\nThe backend also owns SMB-side change monitoring and the notifications that tell browser clients when directory state should refresh.\n\nFor the watcher architecture, subscriber model, and cache-freshness split, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## What Usually Breaks When This Layer Changes\n\n- frontend assumptions about response shape\n- viewer or file-management behavior that depends on MIME or category detection\n- companion editing flows that depend on lock or upload semantics\n- directory freshness in the browser when change notifications stop matching product expectations\n\n## Go Deeper\n\n- [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/): how API, models, storage, services, and WebSocket coordination fit together\n- [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/): how backend watchers, WebSocket notifications, and cache freshness fit together\n- [File Operations and Edit Locking](../file-operations-and-edit-locking/): how ordinary file operations differ from companion-assisted SMB editing and lock handling\n\n## Validation Expectations\n\nWhen the backend changes, start with:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nThen add frontend or companion checks if the backend change affects a shared contract.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) for the broader decision rule.\n", "0.8": "+++\ntitle = \"Backend Overview\"\n+++\n\nThe backend is the policy and integration layer between the browser-facing product and the storage systems Sambee works with.\n\n## What the Backend Owns\n\nThe backend is responsible for:\n\n- authentication and authorization\n- API endpoints consumed by the browser app and companion flows\n- SMB access and server-side file operations\n- server-side preview and download behavior where the product needs it\n- edit-lock and conflict-handling behavior for companion-assisted editing\n- directory-change notification and other state that must stay authoritative on the server side\n\n## Main Code Areas\n\nThe exact module layout evolves, but the backend is organized around a few stable concerns.\n\n| Area | Responsibility |\n|---|---|\n| `backend/app/api/` | request handlers and HTTP-facing endpoints |\n| `backend/app/models/` | API and domain models used across request and response boundaries |\n| `backend/app/storage/` | storage backends and storage-facing behavior, including SMB access |\n| `backend/app/services/` | longer-running or cross-cutting service behavior such as monitoring and background coordination |\n| `backend/app/db/` | database setup and models for persisted application state |\n| `backend/tests/` | pytest coverage for server behavior and contracts |\n\n## Request and Storage Flow\n\nFor the common SMB flow:\n\n1. The frontend issues an authenticated API request.\n2. The backend validates input and permissions.\n3. The backend performs the requested SMB operation through the storage layer.\n4. The backend returns a typed response the frontend or companion can rely on.\n\nThis is why the backend, not the browser, is the source of truth for SMB semantics and conflict-sensitive operations.\n\nIf you need the detailed layer breakdown, continue to [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/).\n\n## Important Backend Contracts\n\n### API Contract Stability\n\nThe frontend relies on typed request and response shapes. That is why contract testing guidance exists and why contributors should treat API shape changes as user-visible changes, not internal refactors.\n\n### File-Type and Preview Behavior\n\nThe backend contributes to preview behavior through MIME detection, file-type classification, and conversion decisions for formats that are not natively browser-friendly. Those rules have to stay aligned with frontend expectations.\n\n### Edit Locking and Companion Flows\n\nFor companion-assisted editing of SMB-backed files, the backend owns the server-side lock, heartbeat, upload, and conflict rules. A desktop-side improvement that ignores those rules can easily create data-loss regressions.\n\nFor the full lifecycle, continue to [File Operations and Edit Locking](../file-operations-and-edit-locking/).\n\n### Change Notification\n\nThe backend also owns SMB-side change monitoring and the notifications that tell browser clients when directory state should refresh.\n\nFor the watcher architecture, subscriber model, and cache-freshness split, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## What Usually Breaks When This Layer Changes\n\n- frontend assumptions about response shape\n- viewer or file-management behavior that depends on MIME or category detection\n- companion editing flows that depend on lock or upload semantics\n- directory freshness in the browser when change notifications stop matching product expectations\n\n## Go Deeper\n\n- [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/): how API, models, storage, services, and WebSocket coordination fit together\n- [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/): how backend watchers, WebSocket notifications, and cache freshness fit together\n- [File Operations and Edit Locking](../file-operations-and-edit-locking/): how ordinary file operations differ from companion-assisted SMB editing and lock handling\n\n## Validation Expectations\n\nWhen the backend changes, start with:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nThen add frontend or companion checks if the backend change affects a shared contract.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) for the broader decision rule.\n", "0.9": "+++\ntitle = \"Backend Overview\"\n+++\n\nThe backend is the policy and integration layer between the browser-facing product and the storage systems Sambee works with.\n\n## What the Backend Owns\n\nThe backend is responsible for:\n\n- authentication and authorization\n- API endpoints consumed by the browser app and companion flows\n- SMB access and server-side file operations\n- server-side preview and download behavior where the product needs it\n- edit-lock and conflict-handling behavior for companion-assisted editing\n- directory-change notification and other state that must stay authoritative on the server side\n\n## Main Code Areas\n\nThe exact module layout evolves, but the backend is organized around a few stable concerns.\n\n| Area | Responsibility |\n|---|---|\n| `backend/app/api/` | request handlers and HTTP-facing endpoints |\n| `backend/app/models/` | API and domain models used across request and response boundaries |\n| `backend/app/storage/` | storage backends and storage-facing behavior, including SMB access |\n| `backend/app/services/` | longer-running or cross-cutting service behavior such as monitoring and background coordination |\n| `backend/app/db/` | database setup and models for persisted application state |\n| `backend/tests/` | pytest coverage for server behavior and contracts |\n\n## Request and Storage Flow\n\nFor the common SMB flow:\n\n1. The frontend issues an authenticated API request.\n2. The backend validates input and permissions.\n3. The backend performs the requested SMB operation through the storage layer.\n4. The backend returns a typed response the frontend or companion can rely on.\n\nThis is why the backend, not the browser, is the source of truth for SMB semantics and conflict-sensitive operations.\n\nIf you need the detailed layer breakdown, continue to [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/).\n\n## Important Backend Contracts\n\n### API Contract Stability\n\nThe frontend relies on typed request and response shapes. That is why contract testing guidance exists and why contributors should treat API shape changes as user-visible changes, not internal refactors.\n\n### File-Type and Preview Behavior\n\nThe backend contributes to preview behavior through MIME detection, file-type classification, and conversion decisions for formats that are not natively browser-friendly. Those rules have to stay aligned with frontend expectations.\n\n### Edit Locking and Companion Flows\n\nFor companion-assisted editing of SMB-backed files, the backend owns the server-side lock, heartbeat, upload, and conflict rules. A desktop-side improvement that ignores those rules can easily create data-loss regressions.\n\nFor the full lifecycle, continue to [File Operations and Edit Locking](../file-operations-and-edit-locking/).\n\n### Change Notification\n\nThe backend also owns SMB-side change monitoring and the notifications that tell browser clients when directory state should refresh.\n\nFor the watcher architecture, subscriber model, and cache-freshness split, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## What Usually Breaks When This Layer Changes\n\n- frontend assumptions about response shape\n- viewer or file-management behavior that depends on MIME or category detection\n- companion editing flows that depend on lock or upload semantics\n- directory freshness in the browser when change notifications stop matching product expectations\n\n## Go Deeper\n\n- [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/): how API, models, storage, services, and WebSocket coordination fit together\n- [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/): how backend watchers, WebSocket notifications, and cache freshness fit together\n- [File Operations and Edit Locking](../file-operations-and-edit-locking/): how ordinary file operations differ from companion-assisted SMB editing and lock handling\n\n## Validation Expectations\n\nWhen the backend changes, start with:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nThen add frontend or companion checks if the backend change affects a shared contract.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) for the broader decision rule.\n", "1.0": "+++\ntitle = \"Backend Overview\"\n+++\n\nThe backend is the policy and integration layer between the browser-facing product and the storage systems Sambee works with.\n\n## What the Backend Owns\n\nThe backend is responsible for:\n\n- authentication and authorization\n- API endpoints consumed by the browser app and companion flows\n- SMB access and server-side file operations\n- server-side preview and download behavior where the product needs it\n- edit-lock and conflict-handling behavior for companion-assisted editing\n- directory-change notification and other state that must stay authoritative on the server side\n\n## Main Code Areas\n\nThe exact module layout evolves, but the backend is organized around a few stable concerns.\n\n| Area | Responsibility |\n|---|---|\n| `backend/app/api/` | request handlers and HTTP-facing endpoints |\n| `backend/app/models/` | API and domain models used across request and response boundaries |\n| `backend/app/storage/` | storage backends and storage-facing behavior, including SMB access |\n| `backend/app/services/` | longer-running or cross-cutting service behavior such as monitoring and background coordination |\n| `backend/app/db/` | database setup and models for persisted application state |\n| `backend/tests/` | pytest coverage for server behavior and contracts |\n\n## Request and Storage Flow\n\nFor the common SMB flow:\n\n1. The frontend issues an authenticated API request.\n2. The backend validates input and permissions.\n3. The backend performs the requested SMB operation through the storage layer.\n4. The backend returns a typed response the frontend or companion can rely on.\n\nThis is why the backend, not the browser, is the source of truth for SMB semantics and conflict-sensitive operations.\n\nIf you need the detailed layer breakdown, continue to [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/).\n\n## Important Backend Contracts\n\n### API Contract Stability\n\nThe frontend relies on typed request and response shapes. That is why contract testing guidance exists and why contributors should treat API shape changes as user-visible changes, not internal refactors.\n\n### File-Type and Preview Behavior\n\nThe backend contributes to preview behavior through MIME detection, file-type classification, and conversion decisions for formats that are not natively browser-friendly. Those rules have to stay aligned with frontend expectations.\n\n### Edit Locking and Companion Flows\n\nFor companion-assisted editing of SMB-backed files, the backend owns the server-side lock, heartbeat, upload, and conflict rules. A desktop-side improvement that ignores those rules can easily create data-loss regressions.\n\nFor the full lifecycle, continue to [File Operations and Edit Locking](../file-operations-and-edit-locking/).\n\n### Change Notification\n\nThe backend also owns SMB-side change monitoring and the notifications that tell browser clients when directory state should refresh.\n\nFor the watcher architecture, subscriber model, and cache-freshness split, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## What Usually Breaks When This Layer Changes\n\n- frontend assumptions about response shape\n- viewer or file-management behavior that depends on MIME or category detection\n- companion editing flows that depend on lock or upload semantics\n- directory freshness in the browser when change notifications stop matching product expectations\n\n## Go Deeper\n\n- [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/): how API, models, storage, services, and WebSocket coordination fit together\n- [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/): how backend watchers, WebSocket notifications, and cache freshness fit together\n- [File Operations and Edit Locking](../file-operations-and-edit-locking/): how ordinary file operations differ from companion-assisted SMB editing and lock handling\n\n## Validation Expectations\n\nWhen the backend changes, start with:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nThen add frontend or companion checks if the backend change affects a shared contract.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) for the broader decision rule.\n", "2.0": "+++\ntitle = \"Backend Overview\"\n+++\n\nThe backend is the policy and integration layer between the browser-facing product and the storage systems Sambee works with.\n\n## What the Backend Owns\n\nThe backend is responsible for:\n\n- authentication and authorization\n- API endpoints consumed by the browser app and companion flows\n- SMB access and server-side file operations\n- server-side preview and download behavior where the product needs it\n- edit-lock and conflict-handling behavior for companion-assisted editing\n- directory-change notification and other state that must stay authoritative on the server side\n\n## Main Code Areas\n\nThe exact module layout evolves, but the backend is organized around a few stable concerns.\n\n| Area | Responsibility |\n|---|---|\n| `backend/app/api/` | request handlers and HTTP-facing endpoints |\n| `backend/app/models/` | API and domain models used across request and response boundaries |\n| `backend/app/storage/` | storage backends and storage-facing behavior, including SMB access |\n| `backend/app/services/` | longer-running or cross-cutting service behavior such as monitoring and background coordination |\n| `backend/app/db/` | database setup and models for persisted application state |\n| `backend/tests/` | pytest coverage for server behavior and contracts |\n\n## Request and Storage Flow\n\nFor the common SMB flow:\n\n1. The frontend issues an authenticated API request.\n2. The backend validates input and permissions.\n3. The backend performs the requested SMB operation through the storage layer.\n4. The backend returns a typed response the frontend or companion can rely on.\n\nThis is why the backend, not the browser, is the source of truth for SMB semantics and conflict-sensitive operations.\n\nIf you need the detailed layer breakdown, continue to [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/).\n\n## Important Backend Contracts\n\n### API Contract Stability\n\nThe frontend relies on typed request and response shapes. That is why contract testing guidance exists and why contributors should treat API shape changes as user-visible changes, not internal refactors.\n\n### File-Type and Preview Behavior\n\nThe backend contributes to preview behavior through MIME detection, file-type classification, and conversion decisions for formats that are not natively browser-friendly. Those rules have to stay aligned with frontend expectations.\n\n### Edit Locking and Companion Flows\n\nFor companion-assisted editing of SMB-backed files, the backend owns the server-side lock, heartbeat, upload, and conflict rules. A desktop-side improvement that ignores those rules can easily create data-loss regressions.\n\nFor the full lifecycle, continue to [File Operations and Edit Locking](../file-operations-and-edit-locking/).\n\n### Change Notification\n\nThe backend also owns SMB-side change monitoring and the notifications that tell browser clients when directory state should refresh.\n\nFor the watcher architecture, subscriber model, and cache-freshness split, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## What Usually Breaks When This Layer Changes\n\n- frontend assumptions about response shape\n- viewer or file-management behavior that depends on MIME or category detection\n- companion editing flows that depend on lock or upload semantics\n- directory freshness in the browser when change notifications stop matching product expectations\n\n## Go Deeper\n\n- [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/): how API, models, storage, services, and WebSocket coordination fit together\n- [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/): how backend watchers, WebSocket notifications, and cache freshness fit together\n- [File Operations and Edit Locking](../file-operations-and-edit-locking/): how ordinary file operations differ from companion-assisted SMB editing and lock handling\n\n## Validation Expectations\n\nWhen the backend changes, start with:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nThen add frontend or companion checks if the backend change affects a shared contract.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) for the broader decision rule.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/backend-architecture/request-flow-and-service-boundaries", "parent_id": "section:developer-guide/backend-architecture", "depth": 2, "kind": "page", "label": "request-flow-and-service-boundaries", "title": "Request Flow And Service Boundaries", "path": "developer-guide/backend-architecture/request-flow-and-service-boundaries", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Request Flow and Service Boundaries\"\n+++\n\nThe backend is easiest to change safely when you treat it as layered coordination instead of one large request handler.\n\n## The Main Boundaries\n\n| Area | What it should own |\n|---|---|\n| `backend/app/api/` | HTTP and WebSocket entry points, request parsing, response shaping, and protocol-specific concerns |\n| `backend/app/models/` | request and response models plus typed data contracts |\n| `backend/app/storage/` | storage-facing behavior such as SMB operations and file handling |\n| `backend/app/services/` | cross-request or longer-lived coordination such as directory monitoring or image conversion |\n| `backend/app/db/` | persisted application state and database integration |\n\nContributors get into trouble when logic that belongs in one boundary starts leaking into another.\n\n## Common Request Paths\n\n### Standard Browser API Flow\n\nFor a typical browse or file-management request:\n\n1. a handler in `backend/app/api/` receives the request\n2. request data is validated against typed models\n3. the handler calls storage or service logic\n4. the backend returns a typed response for the frontend to consume\n\nThe handler should remain the HTTP-facing boundary, not the place where SMB implementation details accumulate.\n\n### Viewer and Preview Flow\n\nPreview-related requests are not just file streaming.\n\nThey can involve:\n\n- MIME classification through the file-type registry\n- conversion decisions for non-browser-native images\n- streaming or materialized responses depending on the format\n\nThis is one reason preview behavior spans both `api/`, `utils/`, and `services/` code.\n\nIf the change affects server-side conversion or preprocessing, continue to [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/).\n\n### Directory-Change Flow\n\nDirectory freshness is coordinated through a service boundary.\n\n1. the WebSocket layer manages subscriptions\n2. the directory monitor owns SMB-side watcher lifecycle for browser subscriptions\n3. the directory cache uses its own watcher path to keep connection-level directory-search data fresh\n4. change notifications are pushed back to subscribed clients when browser-visible refresh is needed\n\nThat split matters because connection recovery and handle cleanup are not ordinary request work.\n\nIf the change affects watcher lifecycle, subscriber bookkeeping, or directory freshness behavior, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## Why the Layering Matters\n\n### API Contracts\n\nThe frontend and companion depend on stable request and response shapes. If you change an API contract, you are changing a cross-boundary contract, not just moving code around.\n\n### Storage Semantics\n\nThe storage layer is where SMB-specific behavior belongs. It should not be reimplemented ad hoc in handlers just because a feature needs a quick change.\n\n### Long-Lived Coordination\n\nBackground coordination such as directory monitoring belongs in services because it outlives one request and needs explicit lifecycle management.\n\n## Signs the Boundary Is Slipping\n\n- request handlers know too much about SMB implementation details\n- the same response-shaping logic is duplicated across endpoints\n- storage helpers start taking HTTP-specific parameters\n- service-level coordination is recreated inside one endpoint instead of reused\n\n## Where to Continue\n\n- Use [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/) when the change affects the backend preview pipeline, conversion policy, or preprocessor behavior.\n- Use [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/) when the change affects watcher lifecycle, WebSocket refresh behavior, or directory-cache freshness.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the change affects create, rename, copy, move, upload, or companion-assisted editing.\n- Use [Frontend Overview](../../frontend-architecture/frontend-overview/) when the backend change alters browser-visible workflow behavior.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the changed boundary requires broader validation.\n", "0.8": "+++\ntitle = \"Request Flow and Service Boundaries\"\n+++\n\nThe backend is easiest to change safely when you treat it as layered coordination instead of one large request handler.\n\n## The Main Boundaries\n\n| Area | What it should own |\n|---|---|\n| `backend/app/api/` | HTTP and WebSocket entry points, request parsing, response shaping, and protocol-specific concerns |\n| `backend/app/models/` | request and response models plus typed data contracts |\n| `backend/app/storage/` | storage-facing behavior such as SMB operations and file handling |\n| `backend/app/services/` | cross-request or longer-lived coordination such as directory monitoring or image conversion |\n| `backend/app/db/` | persisted application state and database integration |\n\nContributors get into trouble when logic that belongs in one boundary starts leaking into another.\n\n## Common Request Paths\n\n### Standard Browser API Flow\n\nFor a typical browse or file-management request:\n\n1. a handler in `backend/app/api/` receives the request\n2. request data is validated against typed models\n3. the handler calls storage or service logic\n4. the backend returns a typed response for the frontend to consume\n\nThe handler should remain the HTTP-facing boundary, not the place where SMB implementation details accumulate.\n\n### Viewer and Preview Flow\n\nPreview-related requests are not just file streaming.\n\nThey can involve:\n\n- MIME classification through the file-type registry\n- conversion decisions for non-browser-native images\n- streaming or materialized responses depending on the format\n\nThis is one reason preview behavior spans both `api/`, `utils/`, and `services/` code.\n\nIf the change affects server-side conversion or preprocessing, continue to [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/).\n\n### Directory-Change Flow\n\nDirectory freshness is coordinated through a service boundary.\n\n1. the WebSocket layer manages subscriptions\n2. the directory monitor owns SMB-side watcher lifecycle for browser subscriptions\n3. the directory cache uses its own watcher path to keep connection-level directory-search data fresh\n4. change notifications are pushed back to subscribed clients when browser-visible refresh is needed\n\nThat split matters because connection recovery and handle cleanup are not ordinary request work.\n\nIf the change affects watcher lifecycle, subscriber bookkeeping, or directory freshness behavior, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## Why the Layering Matters\n\n### API Contracts\n\nThe frontend and companion depend on stable request and response shapes. If you change an API contract, you are changing a cross-boundary contract, not just moving code around.\n\n### Storage Semantics\n\nThe storage layer is where SMB-specific behavior belongs. It should not be reimplemented ad hoc in handlers just because a feature needs a quick change.\n\n### Long-Lived Coordination\n\nBackground coordination such as directory monitoring belongs in services because it outlives one request and needs explicit lifecycle management.\n\n## Signs the Boundary Is Slipping\n\n- request handlers know too much about SMB implementation details\n- the same response-shaping logic is duplicated across endpoints\n- storage helpers start taking HTTP-specific parameters\n- service-level coordination is recreated inside one endpoint instead of reused\n\n## Where to Continue\n\n- Use [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/) when the change affects the backend preview pipeline, conversion policy, or preprocessor behavior.\n- Use [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/) when the change affects watcher lifecycle, WebSocket refresh behavior, or directory-cache freshness.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the change affects create, rename, copy, move, upload, or companion-assisted editing.\n- Use [Frontend Overview](../../frontend-architecture/frontend-overview/) when the backend change alters browser-visible workflow behavior.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the changed boundary requires broader validation.\n", "0.9": "+++\ntitle = \"Request Flow and Service Boundaries\"\n+++\n\nThe backend is easiest to change safely when you treat it as layered coordination instead of one large request handler.\n\n## The Main Boundaries\n\n| Area | What it should own |\n|---|---|\n| `backend/app/api/` | HTTP and WebSocket entry points, request parsing, response shaping, and protocol-specific concerns |\n| `backend/app/models/` | request and response models plus typed data contracts |\n| `backend/app/storage/` | storage-facing behavior such as SMB operations and file handling |\n| `backend/app/services/` | cross-request or longer-lived coordination such as directory monitoring or image conversion |\n| `backend/app/db/` | persisted application state and database integration |\n\nContributors get into trouble when logic that belongs in one boundary starts leaking into another.\n\n## Common Request Paths\n\n### Standard Browser API Flow\n\nFor a typical browse or file-management request:\n\n1. a handler in `backend/app/api/` receives the request\n2. request data is validated against typed models\n3. the handler calls storage or service logic\n4. the backend returns a typed response for the frontend to consume\n\nThe handler should remain the HTTP-facing boundary, not the place where SMB implementation details accumulate.\n\n### Viewer and Preview Flow\n\nPreview-related requests are not just file streaming.\n\nThey can involve:\n\n- MIME classification through the file-type registry\n- conversion decisions for non-browser-native images\n- streaming or materialized responses depending on the format\n\nThis is one reason preview behavior spans both `api/`, `utils/`, and `services/` code.\n\nIf the change affects server-side conversion or preprocessing, continue to [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/).\n\n### Directory-Change Flow\n\nDirectory freshness is coordinated through a service boundary.\n\n1. the WebSocket layer manages subscriptions\n2. the directory monitor owns SMB-side watcher lifecycle for browser subscriptions\n3. the directory cache uses its own watcher path to keep connection-level directory-search data fresh\n4. change notifications are pushed back to subscribed clients when browser-visible refresh is needed\n\nThat split matters because connection recovery and handle cleanup are not ordinary request work.\n\nIf the change affects watcher lifecycle, subscriber bookkeeping, or directory freshness behavior, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## Why the Layering Matters\n\n### API Contracts\n\nThe frontend and companion depend on stable request and response shapes. If you change an API contract, you are changing a cross-boundary contract, not just moving code around.\n\n### Storage Semantics\n\nThe storage layer is where SMB-specific behavior belongs. It should not be reimplemented ad hoc in handlers just because a feature needs a quick change.\n\n### Long-Lived Coordination\n\nBackground coordination such as directory monitoring belongs in services because it outlives one request and needs explicit lifecycle management.\n\n## Signs the Boundary Is Slipping\n\n- request handlers know too much about SMB implementation details\n- the same response-shaping logic is duplicated across endpoints\n- storage helpers start taking HTTP-specific parameters\n- service-level coordination is recreated inside one endpoint instead of reused\n\n## Where to Continue\n\n- Use [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/) when the change affects the backend preview pipeline, conversion policy, or preprocessor behavior.\n- Use [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/) when the change affects watcher lifecycle, WebSocket refresh behavior, or directory-cache freshness.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the change affects create, rename, copy, move, upload, or companion-assisted editing.\n- Use [Frontend Overview](../../frontend-architecture/frontend-overview/) when the backend change alters browser-visible workflow behavior.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the changed boundary requires broader validation.\n", "1.0": "+++\ntitle = \"Request Flow and Service Boundaries\"\n+++\n\nThe backend is easiest to change safely when you treat it as layered coordination instead of one large request handler.\n\n## The Main Boundaries\n\n| Area | What it should own |\n|---|---|\n| `backend/app/api/` | HTTP and WebSocket entry points, request parsing, response shaping, and protocol-specific concerns |\n| `backend/app/models/` | request and response models plus typed data contracts |\n| `backend/app/storage/` | storage-facing behavior such as SMB operations and file handling |\n| `backend/app/services/` | cross-request or longer-lived coordination such as directory monitoring or image conversion |\n| `backend/app/db/` | persisted application state and database integration |\n\nContributors get into trouble when logic that belongs in one boundary starts leaking into another.\n\n## Common Request Paths\n\n### Standard Browser API Flow\n\nFor a typical browse or file-management request:\n\n1. a handler in `backend/app/api/` receives the request\n2. request data is validated against typed models\n3. the handler calls storage or service logic\n4. the backend returns a typed response for the frontend to consume\n\nThe handler should remain the HTTP-facing boundary, not the place where SMB implementation details accumulate.\n\n### Viewer and Preview Flow\n\nPreview-related requests are not just file streaming.\n\nThey can involve:\n\n- MIME classification through the file-type registry\n- conversion decisions for non-browser-native images\n- streaming or materialized responses depending on the format\n\nThis is one reason preview behavior spans both `api/`, `utils/`, and `services/` code.\n\nIf the change affects server-side conversion or preprocessing, continue to [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/).\n\n### Directory-Change Flow\n\nDirectory freshness is coordinated through a service boundary.\n\n1. the WebSocket layer manages subscriptions\n2. the directory monitor owns SMB-side watcher lifecycle for browser subscriptions\n3. the directory cache uses its own watcher path to keep connection-level directory-search data fresh\n4. change notifications are pushed back to subscribed clients when browser-visible refresh is needed\n\nThat split matters because connection recovery and handle cleanup are not ordinary request work.\n\nIf the change affects watcher lifecycle, subscriber bookkeeping, or directory freshness behavior, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## Why the Layering Matters\n\n### API Contracts\n\nThe frontend and companion depend on stable request and response shapes. If you change an API contract, you are changing a cross-boundary contract, not just moving code around.\n\n### Storage Semantics\n\nThe storage layer is where SMB-specific behavior belongs. It should not be reimplemented ad hoc in handlers just because a feature needs a quick change.\n\n### Long-Lived Coordination\n\nBackground coordination such as directory monitoring belongs in services because it outlives one request and needs explicit lifecycle management.\n\n## Signs the Boundary Is Slipping\n\n- request handlers know too much about SMB implementation details\n- the same response-shaping logic is duplicated across endpoints\n- storage helpers start taking HTTP-specific parameters\n- service-level coordination is recreated inside one endpoint instead of reused\n\n## Where to Continue\n\n- Use [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/) when the change affects the backend preview pipeline, conversion policy, or preprocessor behavior.\n- Use [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/) when the change affects watcher lifecycle, WebSocket refresh behavior, or directory-cache freshness.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the change affects create, rename, copy, move, upload, or companion-assisted editing.\n- Use [Frontend Overview](../../frontend-architecture/frontend-overview/) when the backend change alters browser-visible workflow behavior.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the changed boundary requires broader validation.\n", "2.0": "+++\ntitle = \"Request Flow and Service Boundaries\"\n+++\n\nThe backend is easiest to change safely when you treat it as layered coordination instead of one large request handler.\n\n## The Main Boundaries\n\n| Area | What it should own |\n|---|---|\n| `backend/app/api/` | HTTP and WebSocket entry points, request parsing, response shaping, and protocol-specific concerns |\n| `backend/app/models/` | request and response models plus typed data contracts |\n| `backend/app/storage/` | storage-facing behavior such as SMB operations and file handling |\n| `backend/app/services/` | cross-request or longer-lived coordination such as directory monitoring or image conversion |\n| `backend/app/db/` | persisted application state and database integration |\n\nContributors get into trouble when logic that belongs in one boundary starts leaking into another.\n\n## Common Request Paths\n\n### Standard Browser API Flow\n\nFor a typical browse or file-management request:\n\n1. a handler in `backend/app/api/` receives the request\n2. request data is validated against typed models\n3. the handler calls storage or service logic\n4. the backend returns a typed response for the frontend to consume\n\nThe handler should remain the HTTP-facing boundary, not the place where SMB implementation details accumulate.\n\n### Viewer and Preview Flow\n\nPreview-related requests are not just file streaming.\n\nThey can involve:\n\n- MIME classification through the file-type registry\n- conversion decisions for non-browser-native images\n- streaming or materialized responses depending on the format\n\nThis is one reason preview behavior spans both `api/`, `utils/`, and `services/` code.\n\nIf the change affects server-side conversion or preprocessing, continue to [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/).\n\n### Directory-Change Flow\n\nDirectory freshness is coordinated through a service boundary.\n\n1. the WebSocket layer manages subscriptions\n2. the directory monitor owns SMB-side watcher lifecycle for browser subscriptions\n3. the directory cache uses its own watcher path to keep connection-level directory-search data fresh\n4. change notifications are pushed back to subscribed clients when browser-visible refresh is needed\n\nThat split matters because connection recovery and handle cleanup are not ordinary request work.\n\nIf the change affects watcher lifecycle, subscriber bookkeeping, or directory freshness behavior, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## Why the Layering Matters\n\n### API Contracts\n\nThe frontend and companion depend on stable request and response shapes. If you change an API contract, you are changing a cross-boundary contract, not just moving code around.\n\n### Storage Semantics\n\nThe storage layer is where SMB-specific behavior belongs. It should not be reimplemented ad hoc in handlers just because a feature needs a quick change.\n\n### Long-Lived Coordination\n\nBackground coordination such as directory monitoring belongs in services because it outlives one request and needs explicit lifecycle management.\n\n## Signs the Boundary Is Slipping\n\n- request handlers know too much about SMB implementation details\n- the same response-shaping logic is duplicated across endpoints\n- storage helpers start taking HTTP-specific parameters\n- service-level coordination is recreated inside one endpoint instead of reused\n\n## Where to Continue\n\n- Use [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/) when the change affects the backend preview pipeline, conversion policy, or preprocessor behavior.\n- Use [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/) when the change affects watcher lifecycle, WebSocket refresh behavior, or directory-cache freshness.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the change affects create, rename, copy, move, upload, or companion-assisted editing.\n- Use [Frontend Overview](../../frontend-architecture/frontend-overview/) when the backend change alters browser-visible workflow behavior.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the changed boundary requires broader validation.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Request Flow and Service Boundaries\"\n+++\n\nThe backend is easiest to change safely when you treat it as layered coordination instead of one large request handler.\n\n## The Main Boundaries\n\n| Area | What it should own |\n|---|---|\n| `backend/app/api/` | HTTP and WebSocket entry points, request parsing, response shaping, and protocol-specific concerns |\n| `backend/app/models/` | request and response models plus typed data contracts |\n| `backend/app/storage/` | storage-facing behavior such as SMB operations and file handling |\n| `backend/app/services/` | cross-request or longer-lived coordination such as directory monitoring or image conversion |\n| `backend/app/db/` | persisted application state and database integration |\n\nContributors get into trouble when logic that belongs in one boundary starts leaking into another.\n\n## Common Request Paths\n\n### Standard Browser API Flow\n\nFor a typical browse or file-management request:\n\n1. a handler in `backend/app/api/` receives the request\n2. request data is validated against typed models\n3. the handler calls storage or service logic\n4. the backend returns a typed response for the frontend to consume\n\nThe handler should remain the HTTP-facing boundary, not the place where SMB implementation details accumulate.\n\n### Viewer and Preview Flow\n\nPreview-related requests are not just file streaming.\n\nThey can involve:\n\n- MIME classification through the file-type registry\n- conversion decisions for non-browser-native images\n- streaming or materialized responses depending on the format\n\nThis is one reason preview behavior spans both `api/`, `utils/`, and `services/` code.\n\nIf the change affects server-side conversion or preprocessing, continue to [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/).\n\n### Directory-Change Flow\n\nDirectory freshness is coordinated through a service boundary.\n\n1. the WebSocket layer manages subscriptions\n2. the directory monitor owns SMB-side watcher lifecycle for browser subscriptions\n3. the directory cache uses its own watcher path to keep connection-level directory-search data fresh\n4. change notifications are pushed back to subscribed clients when browser-visible refresh is needed\n\nThat split matters because connection recovery and handle cleanup are not ordinary request work.\n\nIf the change affects watcher lifecycle, subscriber bookkeeping, or directory freshness behavior, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## Why the Layering Matters\n\n### API Contracts\n\nThe frontend and companion depend on stable request and response shapes. If you change an API contract, you are changing a cross-boundary contract, not just moving code around.\n\n### Storage Semantics\n\nThe storage layer is where SMB-specific behavior belongs. It should not be reimplemented ad hoc in handlers just because a feature needs a quick change.\n\n### Long-Lived Coordination\n\nBackground coordination such as directory monitoring belongs in services because it outlives one request and needs explicit lifecycle management.\n\n## Signs the Boundary Is Slipping\n\n- request handlers know too much about SMB implementation details\n- the same response-shaping logic is duplicated across endpoints\n- storage helpers start taking HTTP-specific parameters\n- service-level coordination is recreated inside one endpoint instead of reused\n\n## Where to Continue\n\n- Use [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/) when the change affects the backend preview pipeline, conversion policy, or preprocessor behavior.\n- Use [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/) when the change affects watcher lifecycle, WebSocket refresh behavior, or directory-cache freshness.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the change affects create, rename, copy, move, upload, or companion-assisted editing.\n- Use [Frontend Overview](../../frontend-architecture/frontend-overview/) when the backend change alters browser-visible workflow behavior.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the changed boundary requires broader validation.\n", "0.8": "+++\ntitle = \"Request Flow and Service Boundaries\"\n+++\n\nThe backend is easiest to change safely when you treat it as layered coordination instead of one large request handler.\n\n## The Main Boundaries\n\n| Area | What it should own |\n|---|---|\n| `backend/app/api/` | HTTP and WebSocket entry points, request parsing, response shaping, and protocol-specific concerns |\n| `backend/app/models/` | request and response models plus typed data contracts |\n| `backend/app/storage/` | storage-facing behavior such as SMB operations and file handling |\n| `backend/app/services/` | cross-request or longer-lived coordination such as directory monitoring or image conversion |\n| `backend/app/db/` | persisted application state and database integration |\n\nContributors get into trouble when logic that belongs in one boundary starts leaking into another.\n\n## Common Request Paths\n\n### Standard Browser API Flow\n\nFor a typical browse or file-management request:\n\n1. a handler in `backend/app/api/` receives the request\n2. request data is validated against typed models\n3. the handler calls storage or service logic\n4. the backend returns a typed response for the frontend to consume\n\nThe handler should remain the HTTP-facing boundary, not the place where SMB implementation details accumulate.\n\n### Viewer and Preview Flow\n\nPreview-related requests are not just file streaming.\n\nThey can involve:\n\n- MIME classification through the file-type registry\n- conversion decisions for non-browser-native images\n- streaming or materialized responses depending on the format\n\nThis is one reason preview behavior spans both `api/`, `utils/`, and `services/` code.\n\nIf the change affects server-side conversion or preprocessing, continue to [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/).\n\n### Directory-Change Flow\n\nDirectory freshness is coordinated through a service boundary.\n\n1. the WebSocket layer manages subscriptions\n2. the directory monitor owns SMB-side watcher lifecycle for browser subscriptions\n3. the directory cache uses its own watcher path to keep connection-level directory-search data fresh\n4. change notifications are pushed back to subscribed clients when browser-visible refresh is needed\n\nThat split matters because connection recovery and handle cleanup are not ordinary request work.\n\nIf the change affects watcher lifecycle, subscriber bookkeeping, or directory freshness behavior, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## Why the Layering Matters\n\n### API Contracts\n\nThe frontend and companion depend on stable request and response shapes. If you change an API contract, you are changing a cross-boundary contract, not just moving code around.\n\n### Storage Semantics\n\nThe storage layer is where SMB-specific behavior belongs. It should not be reimplemented ad hoc in handlers just because a feature needs a quick change.\n\n### Long-Lived Coordination\n\nBackground coordination such as directory monitoring belongs in services because it outlives one request and needs explicit lifecycle management.\n\n## Signs the Boundary Is Slipping\n\n- request handlers know too much about SMB implementation details\n- the same response-shaping logic is duplicated across endpoints\n- storage helpers start taking HTTP-specific parameters\n- service-level coordination is recreated inside one endpoint instead of reused\n\n## Where to Continue\n\n- Use [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/) when the change affects the backend preview pipeline, conversion policy, or preprocessor behavior.\n- Use [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/) when the change affects watcher lifecycle, WebSocket refresh behavior, or directory-cache freshness.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the change affects create, rename, copy, move, upload, or companion-assisted editing.\n- Use [Frontend Overview](../../frontend-architecture/frontend-overview/) when the backend change alters browser-visible workflow behavior.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the changed boundary requires broader validation.\n", "0.9": "+++\ntitle = \"Request Flow and Service Boundaries\"\n+++\n\nThe backend is easiest to change safely when you treat it as layered coordination instead of one large request handler.\n\n## The Main Boundaries\n\n| Area | What it should own |\n|---|---|\n| `backend/app/api/` | HTTP and WebSocket entry points, request parsing, response shaping, and protocol-specific concerns |\n| `backend/app/models/` | request and response models plus typed data contracts |\n| `backend/app/storage/` | storage-facing behavior such as SMB operations and file handling |\n| `backend/app/services/` | cross-request or longer-lived coordination such as directory monitoring or image conversion |\n| `backend/app/db/` | persisted application state and database integration |\n\nContributors get into trouble when logic that belongs in one boundary starts leaking into another.\n\n## Common Request Paths\n\n### Standard Browser API Flow\n\nFor a typical browse or file-management request:\n\n1. a handler in `backend/app/api/` receives the request\n2. request data is validated against typed models\n3. the handler calls storage or service logic\n4. the backend returns a typed response for the frontend to consume\n\nThe handler should remain the HTTP-facing boundary, not the place where SMB implementation details accumulate.\n\n### Viewer and Preview Flow\n\nPreview-related requests are not just file streaming.\n\nThey can involve:\n\n- MIME classification through the file-type registry\n- conversion decisions for non-browser-native images\n- streaming or materialized responses depending on the format\n\nThis is one reason preview behavior spans both `api/`, `utils/`, and `services/` code.\n\nIf the change affects server-side conversion or preprocessing, continue to [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/).\n\n### Directory-Change Flow\n\nDirectory freshness is coordinated through a service boundary.\n\n1. the WebSocket layer manages subscriptions\n2. the directory monitor owns SMB-side watcher lifecycle for browser subscriptions\n3. the directory cache uses its own watcher path to keep connection-level directory-search data fresh\n4. change notifications are pushed back to subscribed clients when browser-visible refresh is needed\n\nThat split matters because connection recovery and handle cleanup are not ordinary request work.\n\nIf the change affects watcher lifecycle, subscriber bookkeeping, or directory freshness behavior, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## Why the Layering Matters\n\n### API Contracts\n\nThe frontend and companion depend on stable request and response shapes. If you change an API contract, you are changing a cross-boundary contract, not just moving code around.\n\n### Storage Semantics\n\nThe storage layer is where SMB-specific behavior belongs. It should not be reimplemented ad hoc in handlers just because a feature needs a quick change.\n\n### Long-Lived Coordination\n\nBackground coordination such as directory monitoring belongs in services because it outlives one request and needs explicit lifecycle management.\n\n## Signs the Boundary Is Slipping\n\n- request handlers know too much about SMB implementation details\n- the same response-shaping logic is duplicated across endpoints\n- storage helpers start taking HTTP-specific parameters\n- service-level coordination is recreated inside one endpoint instead of reused\n\n## Where to Continue\n\n- Use [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/) when the change affects the backend preview pipeline, conversion policy, or preprocessor behavior.\n- Use [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/) when the change affects watcher lifecycle, WebSocket refresh behavior, or directory-cache freshness.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the change affects create, rename, copy, move, upload, or companion-assisted editing.\n- Use [Frontend Overview](../../frontend-architecture/frontend-overview/) when the backend change alters browser-visible workflow behavior.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the changed boundary requires broader validation.\n", "1.0": "+++\ntitle = \"Request Flow and Service Boundaries\"\n+++\n\nThe backend is easiest to change safely when you treat it as layered coordination instead of one large request handler.\n\n## The Main Boundaries\n\n| Area | What it should own |\n|---|---|\n| `backend/app/api/` | HTTP and WebSocket entry points, request parsing, response shaping, and protocol-specific concerns |\n| `backend/app/models/` | request and response models plus typed data contracts |\n| `backend/app/storage/` | storage-facing behavior such as SMB operations and file handling |\n| `backend/app/services/` | cross-request or longer-lived coordination such as directory monitoring or image conversion |\n| `backend/app/db/` | persisted application state and database integration |\n\nContributors get into trouble when logic that belongs in one boundary starts leaking into another.\n\n## Common Request Paths\n\n### Standard Browser API Flow\n\nFor a typical browse or file-management request:\n\n1. a handler in `backend/app/api/` receives the request\n2. request data is validated against typed models\n3. the handler calls storage or service logic\n4. the backend returns a typed response for the frontend to consume\n\nThe handler should remain the HTTP-facing boundary, not the place where SMB implementation details accumulate.\n\n### Viewer and Preview Flow\n\nPreview-related requests are not just file streaming.\n\nThey can involve:\n\n- MIME classification through the file-type registry\n- conversion decisions for non-browser-native images\n- streaming or materialized responses depending on the format\n\nThis is one reason preview behavior spans both `api/`, `utils/`, and `services/` code.\n\nIf the change affects server-side conversion or preprocessing, continue to [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/).\n\n### Directory-Change Flow\n\nDirectory freshness is coordinated through a service boundary.\n\n1. the WebSocket layer manages subscriptions\n2. the directory monitor owns SMB-side watcher lifecycle for browser subscriptions\n3. the directory cache uses its own watcher path to keep connection-level directory-search data fresh\n4. change notifications are pushed back to subscribed clients when browser-visible refresh is needed\n\nThat split matters because connection recovery and handle cleanup are not ordinary request work.\n\nIf the change affects watcher lifecycle, subscriber bookkeeping, or directory freshness behavior, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## Why the Layering Matters\n\n### API Contracts\n\nThe frontend and companion depend on stable request and response shapes. If you change an API contract, you are changing a cross-boundary contract, not just moving code around.\n\n### Storage Semantics\n\nThe storage layer is where SMB-specific behavior belongs. It should not be reimplemented ad hoc in handlers just because a feature needs a quick change.\n\n### Long-Lived Coordination\n\nBackground coordination such as directory monitoring belongs in services because it outlives one request and needs explicit lifecycle management.\n\n## Signs the Boundary Is Slipping\n\n- request handlers know too much about SMB implementation details\n- the same response-shaping logic is duplicated across endpoints\n- storage helpers start taking HTTP-specific parameters\n- service-level coordination is recreated inside one endpoint instead of reused\n\n## Where to Continue\n\n- Use [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/) when the change affects the backend preview pipeline, conversion policy, or preprocessor behavior.\n- Use [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/) when the change affects watcher lifecycle, WebSocket refresh behavior, or directory-cache freshness.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the change affects create, rename, copy, move, upload, or companion-assisted editing.\n- Use [Frontend Overview](../../frontend-architecture/frontend-overview/) when the backend change alters browser-visible workflow behavior.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the changed boundary requires broader validation.\n", "2.0": "+++\ntitle = \"Request Flow and Service Boundaries\"\n+++\n\nThe backend is easiest to change safely when you treat it as layered coordination instead of one large request handler.\n\n## The Main Boundaries\n\n| Area | What it should own |\n|---|---|\n| `backend/app/api/` | HTTP and WebSocket entry points, request parsing, response shaping, and protocol-specific concerns |\n| `backend/app/models/` | request and response models plus typed data contracts |\n| `backend/app/storage/` | storage-facing behavior such as SMB operations and file handling |\n| `backend/app/services/` | cross-request or longer-lived coordination such as directory monitoring or image conversion |\n| `backend/app/db/` | persisted application state and database integration |\n\nContributors get into trouble when logic that belongs in one boundary starts leaking into another.\n\n## Common Request Paths\n\n### Standard Browser API Flow\n\nFor a typical browse or file-management request:\n\n1. a handler in `backend/app/api/` receives the request\n2. request data is validated against typed models\n3. the handler calls storage or service logic\n4. the backend returns a typed response for the frontend to consume\n\nThe handler should remain the HTTP-facing boundary, not the place where SMB implementation details accumulate.\n\n### Viewer and Preview Flow\n\nPreview-related requests are not just file streaming.\n\nThey can involve:\n\n- MIME classification through the file-type registry\n- conversion decisions for non-browser-native images\n- streaming or materialized responses depending on the format\n\nThis is one reason preview behavior spans both `api/`, `utils/`, and `services/` code.\n\nIf the change affects server-side conversion or preprocessing, continue to [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/).\n\n### Directory-Change Flow\n\nDirectory freshness is coordinated through a service boundary.\n\n1. the WebSocket layer manages subscriptions\n2. the directory monitor owns SMB-side watcher lifecycle for browser subscriptions\n3. the directory cache uses its own watcher path to keep connection-level directory-search data fresh\n4. change notifications are pushed back to subscribed clients when browser-visible refresh is needed\n\nThat split matters because connection recovery and handle cleanup are not ordinary request work.\n\nIf the change affects watcher lifecycle, subscriber bookkeeping, or directory freshness behavior, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## Why the Layering Matters\n\n### API Contracts\n\nThe frontend and companion depend on stable request and response shapes. If you change an API contract, you are changing a cross-boundary contract, not just moving code around.\n\n### Storage Semantics\n\nThe storage layer is where SMB-specific behavior belongs. It should not be reimplemented ad hoc in handlers just because a feature needs a quick change.\n\n### Long-Lived Coordination\n\nBackground coordination such as directory monitoring belongs in services because it outlives one request and needs explicit lifecycle management.\n\n## Signs the Boundary Is Slipping\n\n- request handlers know too much about SMB implementation details\n- the same response-shaping logic is duplicated across endpoints\n- storage helpers start taking HTTP-specific parameters\n- service-level coordination is recreated inside one endpoint instead of reused\n\n## Where to Continue\n\n- Use [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/) when the change affects the backend preview pipeline, conversion policy, or preprocessor behavior.\n- Use [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/) when the change affects watcher lifecycle, WebSocket refresh behavior, or directory-cache freshness.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the change affects create, rename, copy, move, upload, or companion-assisted editing.\n- Use [Frontend Overview](../../frontend-architecture/frontend-overview/) when the backend change alters browser-visible workflow behavior.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the changed boundary requires broader validation.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/backend-architecture/image-preprocessing-and-conversion-pipeline", "parent_id": "section:developer-guide/backend-architecture", "depth": 2, "kind": "page", "label": "image-preprocessing-and-conversion-pipeline", "title": "Image Preprocessing And Conversion Pipeline", "path": "developer-guide/backend-architecture/image-preprocessing-and-conversion-pipeline", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Image Preprocessing and Conversion Pipeline\"\n+++\n\nSambee's image preview path is not one converter with one code path.\n\nFor browser preview, the backend uses two related layers:\n\n- `backend/app/services/image_converter.py` for the general conversion pipeline\n- `backend/app/services/preprocessor.py` for formats that must be normalized before the general pipeline can produce browser-ready output\n\nUse this page when a format change affects backend conversion behavior, external image-tool dependencies, or preprocessing policy.\n\n## Why Preprocessing Exists\n\nSome formats can be decoded and converted directly through the main image-conversion path.\n\nOthers need an explicit preprocessing stage first because Sambee does not rely on the normal stack to decode them safely or usefully for browser preview.\n\nThat is the current role of preprocessing for formats such as:\n\n- `psd`\n- `psb`\n- `eps`\n- `ai`\n\nThe design goal is direct conversion to the final browser-ready result, not a chain of intermediate file formats.\n\n## Main Backend Pieces\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/services/image_converter.py` | primary image conversion path, libvips-backed processing, output-format selection, resizing, and MIME return values |\n| `backend/app/services/preprocessor.py` | preprocessor abstraction, ImageMagick-backed implementation, format registry, and factory behavior |\n| `backend/app/core/image_settings.py` | centralized encoder arguments and output-tuning settings |\n| `imagemagick-policy.xml` | repository-managed ImageMagick policy that constrains resource and delegate behavior |\n\n## Runtime Flow\n\nAt a high level, the backend image-preview flow is:\n\n1. the viewer request reaches the backend preview path\n2. the backend determines the file extension and preview behavior\n3. the converter checks whether the extension requires preprocessing\n4. preprocessable formats are sent to the registered preprocessor directly to produce browser-ready bytes\n5. all other convertible formats stay on the libvips-backed conversion path\n6. the viewer endpoint returns the converted bytes with the resulting MIME type\n\nThis is why preview changes can span registry metadata, service logic, environment dependencies, and viewer expectations at the same time.\n\n## General Conversion Path\n\n`convert_image_for_viewer(...)` in `image_converter.py` is the main entry point.\n\nFor the general conversion path it is responsible for:\n\n- loading image data through libvips\n- detecting alpha handling needs\n- converting colorspaces for web-safe output\n- downscaling when max dimensions are configured\n- choosing a final output format such as WebP, JPEG, or PNG\n- returning `(bytes, mime_type, converter_name, duration_ms)` for the caller\n\nThis is the path used for formats such as TIFF, HEIC, BMP, ICO, and similar server-converted formats that do not need the separate preprocessing registry.\n\n## Preprocessing Path\n\nWhen the extension is registered in `PreprocessorRegistry`, the converter takes a different route.\n\n`PreprocessorRegistry.requires_preprocessing(extension)` decides whether the format uses the preprocessing path.\n\nIf it does:\n\n1. the converter resolves the preprocessor with `get_preprocessor_for_format(...)`\n2. the preprocessor converts the source bytes directly to the final browser-ready format\n3. the converter returns those bytes without sending them through a second conversion stage\n\nCurrent product behavior intentionally chooses:\n\n- JPEG output for raster-oriented preprocessable formats such as PSD and PSB\n- PNG output for vector-style preprocessable formats such as EPS and AI when transparency preservation matters more\n\nThat is a product behavior decision, not just an implementation convenience.\n\n## Preprocessor Abstractions\n\nThe preprocessing service is structured around three backend concepts.\n\n### Preprocessorinterface\n\n`PreprocessorInterface` defines the contract every preprocessor must satisfy.\n\nKey responsibilities include:\n\n- `check_availability()`\n- `validate_input(...)`\n- `convert_to_final_format(...)`\n\nIt also centralizes file-size and timeout access through system settings so those limits do not get hard-coded in format-specific code.\n\n### Imagemagickpreprocessor\n\n`ImageMagickPreprocessor` is the only built-in implementation today.\n\nIt is responsible for:\n\n- requiring ImageMagick 7 through `magick`\n- validating supported extensions\n- converting PSD, PSB, EPS, and AI input directly to JPEG or PNG\n- applying centralized output arguments from `image_settings.py`\n- handling colorspace normalization, including CMYK-to-sRGB conversion behavior\n- enforcing timeout and size checks before or during conversion\n\nFor vector formats such as EPS and AI, it also applies density settings so rendered output quality is usable in the browser.\n\n### Preprocessor Registry and Factory\n\n`PreprocessorRegistry` is the single source of truth for which extensions require preprocessing and which preprocessor class handles them.\n\nThe registry:\n\n- normalizes extension lookup case-insensitively\n- maps extensions such as `psd`, `psb`, `eps`, and `ai` to `ImageMagickPreprocessor`\n- allows explicit runtime registration of additional formats\n- does not implement multi-tool fallback chains itself\n\n`PreprocessorFactory` is the configuration-oriented construction layer.\n\nIt currently supports:\n\n- `PREPROCESSOR=imagemagick`\n- `PREPROCESSOR=auto`\n\n`auto` currently means: use ImageMagick if it is available.\n\n## Security and Policy Constraints\n\nThe preprocessing path runs external tooling, so its constraints are part of the product contract.\n\nImportant protections include:\n\n- repository-managed ImageMagick policy in `imagemagick-policy.xml`\n- resource limits for memory, disk, and image dimensions\n- disabled network delegates\n- disabled indirect path reads\n- application-layer behavior that pipes bytes through stdin and stdout instead of constructing shell commands around user-controlled paths\n\nContributors should treat these protections as required behavior. If a format change needs weaker policy or looser limits, that is an architectural change, not a local implementation tweak.\n\n## Operational Behavior\n\nThe preprocessing path is designed to fail explicitly rather than degrade silently.\n\n- invalid input is rejected during validation\n- unavailable ImageMagick raises preprocessing errors\n- timeout failures surface as preprocessing errors\n- unsupported extensions are rejected by the registry path\n\nThe converter then turns preprocessing failures into user-visible conversion failures for the preview API.\n\n## Configuration Surface\n\nThe main advanced settings for ImageMagick-backed preprocessing are:\n\n- `preprocessors.imagemagick.max_file_size_bytes`\n- `preprocessors.imagemagick.timeout_seconds`\n\nContributors should adjust those only when they understand the operational impact on preview latency, memory pressure, and denial-of-service resistance.\n\n## Adding or Changing a Preprocessing Path Safely\n\nUse this sequence when introducing a new preprocessable format or a new preprocessing backend:\n\n1. decide that the format really belongs in preprocessing rather than the ordinary libvips-backed conversion path\n2. implement or reuse a `PreprocessorInterface` subclass\n3. register the extension in `PreprocessorRegistry`\n4. update file-type metadata and viewer expectations if the format becomes previewable\n5. validate ImageMagick policy or other tool-level constraints if the new path needs different capabilities\n6. add backend tests for availability, validation, timeout behavior, and successful conversion output\n\nIf you skip the first decision, it becomes easy to route a format through preprocessing simply because it works locally, even when it weakens the long-term architecture.\n\n## Common Failure Modes\n\n- a new format is registered for preprocessing when the ordinary conversion path would have been safer or simpler\n- extension registration and file-type metadata drift apart\n- ImageMagick availability differs between local development and deployment\n- policy restrictions block a format in production even though it worked in a permissive local environment\n- timeout or file-size limits are raised casually to make one sample file work, increasing operational risk for everyone else\n\n## Where to Continue\n\n- Use [Viewer Architecture and Preview Contracts](../../frontend-architecture/viewer-architecture-and-preview-contracts/) for the browser-visible preview contract, file-type registry alignment, and viewer routing implications.\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider validation coverage.\n\n## Validation Expectations\n\nWhen you change preprocessing or image-conversion architecture, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects preview behavior, add the relevant frontend checks as well.\n", "0.8": "+++\ntitle = \"Image Preprocessing and Conversion Pipeline\"\n+++\n\nSambee's image preview path is not one converter with one code path.\n\nFor browser preview, the backend uses two related layers:\n\n- `backend/app/services/image_converter.py` for the general conversion pipeline\n- `backend/app/services/preprocessor.py` for formats that must be normalized before the general pipeline can produce browser-ready output\n\nUse this page when a format change affects backend conversion behavior, external image-tool dependencies, or preprocessing policy.\n\n## Why Preprocessing Exists\n\nSome formats can be decoded and converted directly through the main image-conversion path.\n\nOthers need an explicit preprocessing stage first because Sambee does not rely on the normal stack to decode them safely or usefully for browser preview.\n\nThat is the current role of preprocessing for formats such as:\n\n- `psd`\n- `psb`\n- `eps`\n- `ai`\n\nThe design goal is direct conversion to the final browser-ready result, not a chain of intermediate file formats.\n\n## Main Backend Pieces\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/services/image_converter.py` | primary image conversion path, libvips-backed processing, output-format selection, resizing, and MIME return values |\n| `backend/app/services/preprocessor.py` | preprocessor abstraction, ImageMagick-backed implementation, format registry, and factory behavior |\n| `backend/app/core/image_settings.py` | centralized encoder arguments and output-tuning settings |\n| `imagemagick-policy.xml` | repository-managed ImageMagick policy that constrains resource and delegate behavior |\n\n## Runtime Flow\n\nAt a high level, the backend image-preview flow is:\n\n1. the viewer request reaches the backend preview path\n2. the backend determines the file extension and preview behavior\n3. the converter checks whether the extension requires preprocessing\n4. preprocessable formats are sent to the registered preprocessor directly to produce browser-ready bytes\n5. all other convertible formats stay on the libvips-backed conversion path\n6. the viewer endpoint returns the converted bytes with the resulting MIME type\n\nThis is why preview changes can span registry metadata, service logic, environment dependencies, and viewer expectations at the same time.\n\n## General Conversion Path\n\n`convert_image_for_viewer(...)` in `image_converter.py` is the main entry point.\n\nFor the general conversion path it is responsible for:\n\n- loading image data through libvips\n- detecting alpha handling needs\n- converting colorspaces for web-safe output\n- downscaling when max dimensions are configured\n- choosing a final output format such as WebP, JPEG, or PNG\n- returning `(bytes, mime_type, converter_name, duration_ms)` for the caller\n\nThis is the path used for formats such as TIFF, HEIC, BMP, ICO, and similar server-converted formats that do not need the separate preprocessing registry.\n\n## Preprocessing Path\n\nWhen the extension is registered in `PreprocessorRegistry`, the converter takes a different route.\n\n`PreprocessorRegistry.requires_preprocessing(extension)` decides whether the format uses the preprocessing path.\n\nIf it does:\n\n1. the converter resolves the preprocessor with `get_preprocessor_for_format(...)`\n2. the preprocessor converts the source bytes directly to the final browser-ready format\n3. the converter returns those bytes without sending them through a second conversion stage\n\nCurrent product behavior intentionally chooses:\n\n- JPEG output for raster-oriented preprocessable formats such as PSD and PSB\n- PNG output for vector-style preprocessable formats such as EPS and AI when transparency preservation matters more\n\nThat is a product behavior decision, not just an implementation convenience.\n\n## Preprocessor Abstractions\n\nThe preprocessing service is structured around three backend concepts.\n\n### Preprocessorinterface\n\n`PreprocessorInterface` defines the contract every preprocessor must satisfy.\n\nKey responsibilities include:\n\n- `check_availability()`\n- `validate_input(...)`\n- `convert_to_final_format(...)`\n\nIt also centralizes file-size and timeout access through system settings so those limits do not get hard-coded in format-specific code.\n\n### Imagemagickpreprocessor\n\n`ImageMagickPreprocessor` is the only built-in implementation today.\n\nIt is responsible for:\n\n- requiring ImageMagick 7 through `magick`\n- validating supported extensions\n- converting PSD, PSB, EPS, and AI input directly to JPEG or PNG\n- applying centralized output arguments from `image_settings.py`\n- handling colorspace normalization, including CMYK-to-sRGB conversion behavior\n- enforcing timeout and size checks before or during conversion\n\nFor vector formats such as EPS and AI, it also applies density settings so rendered output quality is usable in the browser.\n\n### Preprocessor Registry and Factory\n\n`PreprocessorRegistry` is the single source of truth for which extensions require preprocessing and which preprocessor class handles them.\n\nThe registry:\n\n- normalizes extension lookup case-insensitively\n- maps extensions such as `psd`, `psb`, `eps`, and `ai` to `ImageMagickPreprocessor`\n- allows explicit runtime registration of additional formats\n- does not implement multi-tool fallback chains itself\n\n`PreprocessorFactory` is the configuration-oriented construction layer.\n\nIt currently supports:\n\n- `PREPROCESSOR=imagemagick`\n- `PREPROCESSOR=auto`\n\n`auto` currently means: use ImageMagick if it is available.\n\n## Security and Policy Constraints\n\nThe preprocessing path runs external tooling, so its constraints are part of the product contract.\n\nImportant protections include:\n\n- repository-managed ImageMagick policy in `imagemagick-policy.xml`\n- resource limits for memory, disk, and image dimensions\n- disabled network delegates\n- disabled indirect path reads\n- application-layer behavior that pipes bytes through stdin and stdout instead of constructing shell commands around user-controlled paths\n\nContributors should treat these protections as required behavior. If a format change needs weaker policy or looser limits, that is an architectural change, not a local implementation tweak.\n\n## Operational Behavior\n\nThe preprocessing path is designed to fail explicitly rather than degrade silently.\n\n- invalid input is rejected during validation\n- unavailable ImageMagick raises preprocessing errors\n- timeout failures surface as preprocessing errors\n- unsupported extensions are rejected by the registry path\n\nThe converter then turns preprocessing failures into user-visible conversion failures for the preview API.\n\n## Configuration Surface\n\nThe main advanced settings for ImageMagick-backed preprocessing are:\n\n- `preprocessors.imagemagick.max_file_size_bytes`\n- `preprocessors.imagemagick.timeout_seconds`\n\nContributors should adjust those only when they understand the operational impact on preview latency, memory pressure, and denial-of-service resistance.\n\n## Adding or Changing a Preprocessing Path Safely\n\nUse this sequence when introducing a new preprocessable format or a new preprocessing backend:\n\n1. decide that the format really belongs in preprocessing rather than the ordinary libvips-backed conversion path\n2. implement or reuse a `PreprocessorInterface` subclass\n3. register the extension in `PreprocessorRegistry`\n4. update file-type metadata and viewer expectations if the format becomes previewable\n5. validate ImageMagick policy or other tool-level constraints if the new path needs different capabilities\n6. add backend tests for availability, validation, timeout behavior, and successful conversion output\n\nIf you skip the first decision, it becomes easy to route a format through preprocessing simply because it works locally, even when it weakens the long-term architecture.\n\n## Common Failure Modes\n\n- a new format is registered for preprocessing when the ordinary conversion path would have been safer or simpler\n- extension registration and file-type metadata drift apart\n- ImageMagick availability differs between local development and deployment\n- policy restrictions block a format in production even though it worked in a permissive local environment\n- timeout or file-size limits are raised casually to make one sample file work, increasing operational risk for everyone else\n\n## Where to Continue\n\n- Use [Viewer Architecture and Preview Contracts](../../frontend-architecture/viewer-architecture-and-preview-contracts/) for the browser-visible preview contract, file-type registry alignment, and viewer routing implications.\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider validation coverage.\n\n## Validation Expectations\n\nWhen you change preprocessing or image-conversion architecture, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects preview behavior, add the relevant frontend checks as well.\n", "0.9": "+++\ntitle = \"Image Preprocessing and Conversion Pipeline\"\n+++\n\nSambee's image preview path is not one converter with one code path.\n\nFor browser preview, the backend uses two related layers:\n\n- `backend/app/services/image_converter.py` for the general conversion pipeline\n- `backend/app/services/preprocessor.py` for formats that must be normalized before the general pipeline can produce browser-ready output\n\nUse this page when a format change affects backend conversion behavior, external image-tool dependencies, or preprocessing policy.\n\n## Why Preprocessing Exists\n\nSome formats can be decoded and converted directly through the main image-conversion path.\n\nOthers need an explicit preprocessing stage first because Sambee does not rely on the normal stack to decode them safely or usefully for browser preview.\n\nThat is the current role of preprocessing for formats such as:\n\n- `psd`\n- `psb`\n- `eps`\n- `ai`\n\nThe design goal is direct conversion to the final browser-ready result, not a chain of intermediate file formats.\n\n## Main Backend Pieces\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/services/image_converter.py` | primary image conversion path, libvips-backed processing, output-format selection, resizing, and MIME return values |\n| `backend/app/services/preprocessor.py` | preprocessor abstraction, ImageMagick-backed implementation, format registry, and factory behavior |\n| `backend/app/core/image_settings.py` | centralized encoder arguments and output-tuning settings |\n| `imagemagick-policy.xml` | repository-managed ImageMagick policy that constrains resource and delegate behavior |\n\n## Runtime Flow\n\nAt a high level, the backend image-preview flow is:\n\n1. the viewer request reaches the backend preview path\n2. the backend determines the file extension and preview behavior\n3. the converter checks whether the extension requires preprocessing\n4. preprocessable formats are sent to the registered preprocessor directly to produce browser-ready bytes\n5. all other convertible formats stay on the libvips-backed conversion path\n6. the viewer endpoint returns the converted bytes with the resulting MIME type\n\nThis is why preview changes can span registry metadata, service logic, environment dependencies, and viewer expectations at the same time.\n\n## General Conversion Path\n\n`convert_image_for_viewer(...)` in `image_converter.py` is the main entry point.\n\nFor the general conversion path it is responsible for:\n\n- loading image data through libvips\n- detecting alpha handling needs\n- converting colorspaces for web-safe output\n- downscaling when max dimensions are configured\n- choosing a final output format such as WebP, JPEG, or PNG\n- returning `(bytes, mime_type, converter_name, duration_ms)` for the caller\n\nThis is the path used for formats such as TIFF, HEIC, BMP, ICO, and similar server-converted formats that do not need the separate preprocessing registry.\n\n## Preprocessing Path\n\nWhen the extension is registered in `PreprocessorRegistry`, the converter takes a different route.\n\n`PreprocessorRegistry.requires_preprocessing(extension)` decides whether the format uses the preprocessing path.\n\nIf it does:\n\n1. the converter resolves the preprocessor with `get_preprocessor_for_format(...)`\n2. the preprocessor converts the source bytes directly to the final browser-ready format\n3. the converter returns those bytes without sending them through a second conversion stage\n\nCurrent product behavior intentionally chooses:\n\n- JPEG output for raster-oriented preprocessable formats such as PSD and PSB\n- PNG output for vector-style preprocessable formats such as EPS and AI when transparency preservation matters more\n\nThat is a product behavior decision, not just an implementation convenience.\n\n## Preprocessor Abstractions\n\nThe preprocessing service is structured around three backend concepts.\n\n### Preprocessorinterface\n\n`PreprocessorInterface` defines the contract every preprocessor must satisfy.\n\nKey responsibilities include:\n\n- `check_availability()`\n- `validate_input(...)`\n- `convert_to_final_format(...)`\n\nIt also centralizes file-size and timeout access through system settings so those limits do not get hard-coded in format-specific code.\n\n### Imagemagickpreprocessor\n\n`ImageMagickPreprocessor` is the only built-in implementation today.\n\nIt is responsible for:\n\n- requiring ImageMagick 7 through `magick`\n- validating supported extensions\n- converting PSD, PSB, EPS, and AI input directly to JPEG or PNG\n- applying centralized output arguments from `image_settings.py`\n- handling colorspace normalization, including CMYK-to-sRGB conversion behavior\n- enforcing timeout and size checks before or during conversion\n\nFor vector formats such as EPS and AI, it also applies density settings so rendered output quality is usable in the browser.\n\n### Preprocessor Registry and Factory\n\n`PreprocessorRegistry` is the single source of truth for which extensions require preprocessing and which preprocessor class handles them.\n\nThe registry:\n\n- normalizes extension lookup case-insensitively\n- maps extensions such as `psd`, `psb`, `eps`, and `ai` to `ImageMagickPreprocessor`\n- allows explicit runtime registration of additional formats\n- does not implement multi-tool fallback chains itself\n\n`PreprocessorFactory` is the configuration-oriented construction layer.\n\nIt currently supports:\n\n- `PREPROCESSOR=imagemagick`\n- `PREPROCESSOR=auto`\n\n`auto` currently means: use ImageMagick if it is available.\n\n## Security and Policy Constraints\n\nThe preprocessing path runs external tooling, so its constraints are part of the product contract.\n\nImportant protections include:\n\n- repository-managed ImageMagick policy in `imagemagick-policy.xml`\n- resource limits for memory, disk, and image dimensions\n- disabled network delegates\n- disabled indirect path reads\n- application-layer behavior that pipes bytes through stdin and stdout instead of constructing shell commands around user-controlled paths\n\nContributors should treat these protections as required behavior. If a format change needs weaker policy or looser limits, that is an architectural change, not a local implementation tweak.\n\n## Operational Behavior\n\nThe preprocessing path is designed to fail explicitly rather than degrade silently.\n\n- invalid input is rejected during validation\n- unavailable ImageMagick raises preprocessing errors\n- timeout failures surface as preprocessing errors\n- unsupported extensions are rejected by the registry path\n\nThe converter then turns preprocessing failures into user-visible conversion failures for the preview API.\n\n## Configuration Surface\n\nThe main advanced settings for ImageMagick-backed preprocessing are:\n\n- `preprocessors.imagemagick.max_file_size_bytes`\n- `preprocessors.imagemagick.timeout_seconds`\n\nContributors should adjust those only when they understand the operational impact on preview latency, memory pressure, and denial-of-service resistance.\n\n## Adding or Changing a Preprocessing Path Safely\n\nUse this sequence when introducing a new preprocessable format or a new preprocessing backend:\n\n1. decide that the format really belongs in preprocessing rather than the ordinary libvips-backed conversion path\n2. implement or reuse a `PreprocessorInterface` subclass\n3. register the extension in `PreprocessorRegistry`\n4. update file-type metadata and viewer expectations if the format becomes previewable\n5. validate ImageMagick policy or other tool-level constraints if the new path needs different capabilities\n6. add backend tests for availability, validation, timeout behavior, and successful conversion output\n\nIf you skip the first decision, it becomes easy to route a format through preprocessing simply because it works locally, even when it weakens the long-term architecture.\n\n## Common Failure Modes\n\n- a new format is registered for preprocessing when the ordinary conversion path would have been safer or simpler\n- extension registration and file-type metadata drift apart\n- ImageMagick availability differs between local development and deployment\n- policy restrictions block a format in production even though it worked in a permissive local environment\n- timeout or file-size limits are raised casually to make one sample file work, increasing operational risk for everyone else\n\n## Where to Continue\n\n- Use [Viewer Architecture and Preview Contracts](../../frontend-architecture/viewer-architecture-and-preview-contracts/) for the browser-visible preview contract, file-type registry alignment, and viewer routing implications.\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider validation coverage.\n\n## Validation Expectations\n\nWhen you change preprocessing or image-conversion architecture, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects preview behavior, add the relevant frontend checks as well.\n", "1.0": "+++\ntitle = \"Image Preprocessing and Conversion Pipeline\"\n+++\n\nSambee's image preview path is not one converter with one code path.\n\nFor browser preview, the backend uses two related layers:\n\n- `backend/app/services/image_converter.py` for the general conversion pipeline\n- `backend/app/services/preprocessor.py` for formats that must be normalized before the general pipeline can produce browser-ready output\n\nUse this page when a format change affects backend conversion behavior, external image-tool dependencies, or preprocessing policy.\n\n## Why Preprocessing Exists\n\nSome formats can be decoded and converted directly through the main image-conversion path.\n\nOthers need an explicit preprocessing stage first because Sambee does not rely on the normal stack to decode them safely or usefully for browser preview.\n\nThat is the current role of preprocessing for formats such as:\n\n- `psd`\n- `psb`\n- `eps`\n- `ai`\n\nThe design goal is direct conversion to the final browser-ready result, not a chain of intermediate file formats.\n\n## Main Backend Pieces\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/services/image_converter.py` | primary image conversion path, libvips-backed processing, output-format selection, resizing, and MIME return values |\n| `backend/app/services/preprocessor.py` | preprocessor abstraction, ImageMagick-backed implementation, format registry, and factory behavior |\n| `backend/app/core/image_settings.py` | centralized encoder arguments and output-tuning settings |\n| `imagemagick-policy.xml` | repository-managed ImageMagick policy that constrains resource and delegate behavior |\n\n## Runtime Flow\n\nAt a high level, the backend image-preview flow is:\n\n1. the viewer request reaches the backend preview path\n2. the backend determines the file extension and preview behavior\n3. the converter checks whether the extension requires preprocessing\n4. preprocessable formats are sent to the registered preprocessor directly to produce browser-ready bytes\n5. all other convertible formats stay on the libvips-backed conversion path\n6. the viewer endpoint returns the converted bytes with the resulting MIME type\n\nThis is why preview changes can span registry metadata, service logic, environment dependencies, and viewer expectations at the same time.\n\n## General Conversion Path\n\n`convert_image_for_viewer(...)` in `image_converter.py` is the main entry point.\n\nFor the general conversion path it is responsible for:\n\n- loading image data through libvips\n- detecting alpha handling needs\n- converting colorspaces for web-safe output\n- downscaling when max dimensions are configured\n- choosing a final output format such as WebP, JPEG, or PNG\n- returning `(bytes, mime_type, converter_name, duration_ms)` for the caller\n\nThis is the path used for formats such as TIFF, HEIC, BMP, ICO, and similar server-converted formats that do not need the separate preprocessing registry.\n\n## Preprocessing Path\n\nWhen the extension is registered in `PreprocessorRegistry`, the converter takes a different route.\n\n`PreprocessorRegistry.requires_preprocessing(extension)` decides whether the format uses the preprocessing path.\n\nIf it does:\n\n1. the converter resolves the preprocessor with `get_preprocessor_for_format(...)`\n2. the preprocessor converts the source bytes directly to the final browser-ready format\n3. the converter returns those bytes without sending them through a second conversion stage\n\nCurrent product behavior intentionally chooses:\n\n- JPEG output for raster-oriented preprocessable formats such as PSD and PSB\n- PNG output for vector-style preprocessable formats such as EPS and AI when transparency preservation matters more\n\nThat is a product behavior decision, not just an implementation convenience.\n\n## Preprocessor Abstractions\n\nThe preprocessing service is structured around three backend concepts.\n\n### Preprocessorinterface\n\n`PreprocessorInterface` defines the contract every preprocessor must satisfy.\n\nKey responsibilities include:\n\n- `check_availability()`\n- `validate_input(...)`\n- `convert_to_final_format(...)`\n\nIt also centralizes file-size and timeout access through system settings so those limits do not get hard-coded in format-specific code.\n\n### Imagemagickpreprocessor\n\n`ImageMagickPreprocessor` is the only built-in implementation today.\n\nIt is responsible for:\n\n- requiring ImageMagick 7 through `magick`\n- validating supported extensions\n- converting PSD, PSB, EPS, and AI input directly to JPEG or PNG\n- applying centralized output arguments from `image_settings.py`\n- handling colorspace normalization, including CMYK-to-sRGB conversion behavior\n- enforcing timeout and size checks before or during conversion\n\nFor vector formats such as EPS and AI, it also applies density settings so rendered output quality is usable in the browser.\n\n### Preprocessor Registry and Factory\n\n`PreprocessorRegistry` is the single source of truth for which extensions require preprocessing and which preprocessor class handles them.\n\nThe registry:\n\n- normalizes extension lookup case-insensitively\n- maps extensions such as `psd`, `psb`, `eps`, and `ai` to `ImageMagickPreprocessor`\n- allows explicit runtime registration of additional formats\n- does not implement multi-tool fallback chains itself\n\n`PreprocessorFactory` is the configuration-oriented construction layer.\n\nIt currently supports:\n\n- `PREPROCESSOR=imagemagick`\n- `PREPROCESSOR=auto`\n\n`auto` currently means: use ImageMagick if it is available.\n\n## Security and Policy Constraints\n\nThe preprocessing path runs external tooling, so its constraints are part of the product contract.\n\nImportant protections include:\n\n- repository-managed ImageMagick policy in `imagemagick-policy.xml`\n- resource limits for memory, disk, and image dimensions\n- disabled network delegates\n- disabled indirect path reads\n- application-layer behavior that pipes bytes through stdin and stdout instead of constructing shell commands around user-controlled paths\n\nContributors should treat these protections as required behavior. If a format change needs weaker policy or looser limits, that is an architectural change, not a local implementation tweak.\n\n## Operational Behavior\n\nThe preprocessing path is designed to fail explicitly rather than degrade silently.\n\n- invalid input is rejected during validation\n- unavailable ImageMagick raises preprocessing errors\n- timeout failures surface as preprocessing errors\n- unsupported extensions are rejected by the registry path\n\nThe converter then turns preprocessing failures into user-visible conversion failures for the preview API.\n\n## Configuration Surface\n\nThe main advanced settings for ImageMagick-backed preprocessing are:\n\n- `preprocessors.imagemagick.max_file_size_bytes`\n- `preprocessors.imagemagick.timeout_seconds`\n\nContributors should adjust those only when they understand the operational impact on preview latency, memory pressure, and denial-of-service resistance.\n\n## Adding or Changing a Preprocessing Path Safely\n\nUse this sequence when introducing a new preprocessable format or a new preprocessing backend:\n\n1. decide that the format really belongs in preprocessing rather than the ordinary libvips-backed conversion path\n2. implement or reuse a `PreprocessorInterface` subclass\n3. register the extension in `PreprocessorRegistry`\n4. update file-type metadata and viewer expectations if the format becomes previewable\n5. validate ImageMagick policy or other tool-level constraints if the new path needs different capabilities\n6. add backend tests for availability, validation, timeout behavior, and successful conversion output\n\nIf you skip the first decision, it becomes easy to route a format through preprocessing simply because it works locally, even when it weakens the long-term architecture.\n\n## Common Failure Modes\n\n- a new format is registered for preprocessing when the ordinary conversion path would have been safer or simpler\n- extension registration and file-type metadata drift apart\n- ImageMagick availability differs between local development and deployment\n- policy restrictions block a format in production even though it worked in a permissive local environment\n- timeout or file-size limits are raised casually to make one sample file work, increasing operational risk for everyone else\n\n## Where to Continue\n\n- Use [Viewer Architecture and Preview Contracts](../../frontend-architecture/viewer-architecture-and-preview-contracts/) for the browser-visible preview contract, file-type registry alignment, and viewer routing implications.\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider validation coverage.\n\n## Validation Expectations\n\nWhen you change preprocessing or image-conversion architecture, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects preview behavior, add the relevant frontend checks as well.\n", "2.0": "+++\ntitle = \"Image Preprocessing and Conversion Pipeline\"\n+++\n\nSambee's image preview path is not one converter with one code path.\n\nFor browser preview, the backend uses two related layers:\n\n- `backend/app/services/image_converter.py` for the general conversion pipeline\n- `backend/app/services/preprocessor.py` for formats that must be normalized before the general pipeline can produce browser-ready output\n\nUse this page when a format change affects backend conversion behavior, external image-tool dependencies, or preprocessing policy.\n\n## Why Preprocessing Exists\n\nSome formats can be decoded and converted directly through the main image-conversion path.\n\nOthers need an explicit preprocessing stage first because Sambee does not rely on the normal stack to decode them safely or usefully for browser preview.\n\nThat is the current role of preprocessing for formats such as:\n\n- `psd`\n- `psb`\n- `eps`\n- `ai`\n\nThe design goal is direct conversion to the final browser-ready result, not a chain of intermediate file formats.\n\n## Main Backend Pieces\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/services/image_converter.py` | primary image conversion path, libvips-backed processing, output-format selection, resizing, and MIME return values |\n| `backend/app/services/preprocessor.py` | preprocessor abstraction, ImageMagick-backed implementation, format registry, and factory behavior |\n| `backend/app/core/image_settings.py` | centralized encoder arguments and output-tuning settings |\n| `imagemagick-policy.xml` | repository-managed ImageMagick policy that constrains resource and delegate behavior |\n\n## Runtime Flow\n\nAt a high level, the backend image-preview flow is:\n\n1. the viewer request reaches the backend preview path\n2. the backend determines the file extension and preview behavior\n3. the converter checks whether the extension requires preprocessing\n4. preprocessable formats are sent to the registered preprocessor directly to produce browser-ready bytes\n5. all other convertible formats stay on the libvips-backed conversion path\n6. the viewer endpoint returns the converted bytes with the resulting MIME type\n\nThis is why preview changes can span registry metadata, service logic, environment dependencies, and viewer expectations at the same time.\n\n## General Conversion Path\n\n`convert_image_for_viewer(...)` in `image_converter.py` is the main entry point.\n\nFor the general conversion path it is responsible for:\n\n- loading image data through libvips\n- detecting alpha handling needs\n- converting colorspaces for web-safe output\n- downscaling when max dimensions are configured\n- choosing a final output format such as WebP, JPEG, or PNG\n- returning `(bytes, mime_type, converter_name, duration_ms)` for the caller\n\nThis is the path used for formats such as TIFF, HEIC, BMP, ICO, and similar server-converted formats that do not need the separate preprocessing registry.\n\n## Preprocessing Path\n\nWhen the extension is registered in `PreprocessorRegistry`, the converter takes a different route.\n\n`PreprocessorRegistry.requires_preprocessing(extension)` decides whether the format uses the preprocessing path.\n\nIf it does:\n\n1. the converter resolves the preprocessor with `get_preprocessor_for_format(...)`\n2. the preprocessor converts the source bytes directly to the final browser-ready format\n3. the converter returns those bytes without sending them through a second conversion stage\n\nCurrent product behavior intentionally chooses:\n\n- JPEG output for raster-oriented preprocessable formats such as PSD and PSB\n- PNG output for vector-style preprocessable formats such as EPS and AI when transparency preservation matters more\n\nThat is a product behavior decision, not just an implementation convenience.\n\n## Preprocessor Abstractions\n\nThe preprocessing service is structured around three backend concepts.\n\n### Preprocessorinterface\n\n`PreprocessorInterface` defines the contract every preprocessor must satisfy.\n\nKey responsibilities include:\n\n- `check_availability()`\n- `validate_input(...)`\n- `convert_to_final_format(...)`\n\nIt also centralizes file-size and timeout access through system settings so those limits do not get hard-coded in format-specific code.\n\n### Imagemagickpreprocessor\n\n`ImageMagickPreprocessor` is the only built-in implementation today.\n\nIt is responsible for:\n\n- requiring ImageMagick 7 through `magick`\n- validating supported extensions\n- converting PSD, PSB, EPS, and AI input directly to JPEG or PNG\n- applying centralized output arguments from `image_settings.py`\n- handling colorspace normalization, including CMYK-to-sRGB conversion behavior\n- enforcing timeout and size checks before or during conversion\n\nFor vector formats such as EPS and AI, it also applies density settings so rendered output quality is usable in the browser.\n\n### Preprocessor Registry and Factory\n\n`PreprocessorRegistry` is the single source of truth for which extensions require preprocessing and which preprocessor class handles them.\n\nThe registry:\n\n- normalizes extension lookup case-insensitively\n- maps extensions such as `psd`, `psb`, `eps`, and `ai` to `ImageMagickPreprocessor`\n- allows explicit runtime registration of additional formats\n- does not implement multi-tool fallback chains itself\n\n`PreprocessorFactory` is the configuration-oriented construction layer.\n\nIt currently supports:\n\n- `PREPROCESSOR=imagemagick`\n- `PREPROCESSOR=auto`\n\n`auto` currently means: use ImageMagick if it is available.\n\n## Security and Policy Constraints\n\nThe preprocessing path runs external tooling, so its constraints are part of the product contract.\n\nImportant protections include:\n\n- repository-managed ImageMagick policy in `imagemagick-policy.xml`\n- resource limits for memory, disk, and image dimensions\n- disabled network delegates\n- disabled indirect path reads\n- application-layer behavior that pipes bytes through stdin and stdout instead of constructing shell commands around user-controlled paths\n\nContributors should treat these protections as required behavior. If a format change needs weaker policy or looser limits, that is an architectural change, not a local implementation tweak.\n\n## Operational Behavior\n\nThe preprocessing path is designed to fail explicitly rather than degrade silently.\n\n- invalid input is rejected during validation\n- unavailable ImageMagick raises preprocessing errors\n- timeout failures surface as preprocessing errors\n- unsupported extensions are rejected by the registry path\n\nThe converter then turns preprocessing failures into user-visible conversion failures for the preview API.\n\n## Configuration Surface\n\nThe main advanced settings for ImageMagick-backed preprocessing are:\n\n- `preprocessors.imagemagick.max_file_size_bytes`\n- `preprocessors.imagemagick.timeout_seconds`\n\nContributors should adjust those only when they understand the operational impact on preview latency, memory pressure, and denial-of-service resistance.\n\n## Adding or Changing a Preprocessing Path Safely\n\nUse this sequence when introducing a new preprocessable format or a new preprocessing backend:\n\n1. decide that the format really belongs in preprocessing rather than the ordinary libvips-backed conversion path\n2. implement or reuse a `PreprocessorInterface` subclass\n3. register the extension in `PreprocessorRegistry`\n4. update file-type metadata and viewer expectations if the format becomes previewable\n5. validate ImageMagick policy or other tool-level constraints if the new path needs different capabilities\n6. add backend tests for availability, validation, timeout behavior, and successful conversion output\n\nIf you skip the first decision, it becomes easy to route a format through preprocessing simply because it works locally, even when it weakens the long-term architecture.\n\n## Common Failure Modes\n\n- a new format is registered for preprocessing when the ordinary conversion path would have been safer or simpler\n- extension registration and file-type metadata drift apart\n- ImageMagick availability differs between local development and deployment\n- policy restrictions block a format in production even though it worked in a permissive local environment\n- timeout or file-size limits are raised casually to make one sample file work, increasing operational risk for everyone else\n\n## Where to Continue\n\n- Use [Viewer Architecture and Preview Contracts](../../frontend-architecture/viewer-architecture-and-preview-contracts/) for the browser-visible preview contract, file-type registry alignment, and viewer routing implications.\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider validation coverage.\n\n## Validation Expectations\n\nWhen you change preprocessing or image-conversion architecture, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects preview behavior, add the relevant frontend checks as well.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Image Preprocessing and Conversion Pipeline\"\n+++\n\nSambee's image preview path is not one converter with one code path.\n\nFor browser preview, the backend uses two related layers:\n\n- `backend/app/services/image_converter.py` for the general conversion pipeline\n- `backend/app/services/preprocessor.py` for formats that must be normalized before the general pipeline can produce browser-ready output\n\nUse this page when a format change affects backend conversion behavior, external image-tool dependencies, or preprocessing policy.\n\n## Why Preprocessing Exists\n\nSome formats can be decoded and converted directly through the main image-conversion path.\n\nOthers need an explicit preprocessing stage first because Sambee does not rely on the normal stack to decode them safely or usefully for browser preview.\n\nThat is the current role of preprocessing for formats such as:\n\n- `psd`\n- `psb`\n- `eps`\n- `ai`\n\nThe design goal is direct conversion to the final browser-ready result, not a chain of intermediate file formats.\n\n## Main Backend Pieces\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/services/image_converter.py` | primary image conversion path, libvips-backed processing, output-format selection, resizing, and MIME return values |\n| `backend/app/services/preprocessor.py` | preprocessor abstraction, ImageMagick-backed implementation, format registry, and factory behavior |\n| `backend/app/core/image_settings.py` | centralized encoder arguments and output-tuning settings |\n| `imagemagick-policy.xml` | repository-managed ImageMagick policy that constrains resource and delegate behavior |\n\n## Runtime Flow\n\nAt a high level, the backend image-preview flow is:\n\n1. the viewer request reaches the backend preview path\n2. the backend determines the file extension and preview behavior\n3. the converter checks whether the extension requires preprocessing\n4. preprocessable formats are sent to the registered preprocessor directly to produce browser-ready bytes\n5. all other convertible formats stay on the libvips-backed conversion path\n6. the viewer endpoint returns the converted bytes with the resulting MIME type\n\nThis is why preview changes can span registry metadata, service logic, environment dependencies, and viewer expectations at the same time.\n\n## General Conversion Path\n\n`convert_image_for_viewer(...)` in `image_converter.py` is the main entry point.\n\nFor the general conversion path it is responsible for:\n\n- loading image data through libvips\n- detecting alpha handling needs\n- converting colorspaces for web-safe output\n- downscaling when max dimensions are configured\n- choosing a final output format such as WebP, JPEG, or PNG\n- returning `(bytes, mime_type, converter_name, duration_ms)` for the caller\n\nThis is the path used for formats such as TIFF, HEIC, BMP, ICO, and similar server-converted formats that do not need the separate preprocessing registry.\n\n## Preprocessing Path\n\nWhen the extension is registered in `PreprocessorRegistry`, the converter takes a different route.\n\n`PreprocessorRegistry.requires_preprocessing(extension)` decides whether the format uses the preprocessing path.\n\nIf it does:\n\n1. the converter resolves the preprocessor with `get_preprocessor_for_format(...)`\n2. the preprocessor converts the source bytes directly to the final browser-ready format\n3. the converter returns those bytes without sending them through a second conversion stage\n\nCurrent product behavior intentionally chooses:\n\n- JPEG output for raster-oriented preprocessable formats such as PSD and PSB\n- PNG output for vector-style preprocessable formats such as EPS and AI when transparency preservation matters more\n\nThat is a product behavior decision, not just an implementation convenience.\n\n## Preprocessor Abstractions\n\nThe preprocessing service is structured around three backend concepts.\n\n### Preprocessorinterface\n\n`PreprocessorInterface` defines the contract every preprocessor must satisfy.\n\nKey responsibilities include:\n\n- `check_availability()`\n- `validate_input(...)`\n- `convert_to_final_format(...)`\n\nIt also centralizes file-size and timeout access through system settings so those limits do not get hard-coded in format-specific code.\n\n### Imagemagickpreprocessor\n\n`ImageMagickPreprocessor` is the only built-in implementation today.\n\nIt is responsible for:\n\n- requiring ImageMagick 7 through `magick`\n- validating supported extensions\n- converting PSD, PSB, EPS, and AI input directly to JPEG or PNG\n- applying centralized output arguments from `image_settings.py`\n- handling colorspace normalization, including CMYK-to-sRGB conversion behavior\n- enforcing timeout and size checks before or during conversion\n\nFor vector formats such as EPS and AI, it also applies density settings so rendered output quality is usable in the browser.\n\n### Preprocessor Registry and Factory\n\n`PreprocessorRegistry` is the single source of truth for which extensions require preprocessing and which preprocessor class handles them.\n\nThe registry:\n\n- normalizes extension lookup case-insensitively\n- maps extensions such as `psd`, `psb`, `eps`, and `ai` to `ImageMagickPreprocessor`\n- allows explicit runtime registration of additional formats\n- does not implement multi-tool fallback chains itself\n\n`PreprocessorFactory` is the configuration-oriented construction layer.\n\nIt currently supports:\n\n- `PREPROCESSOR=imagemagick`\n- `PREPROCESSOR=auto`\n\n`auto` currently means: use ImageMagick if it is available.\n\n## Security and Policy Constraints\n\nThe preprocessing path runs external tooling, so its constraints are part of the product contract.\n\nImportant protections include:\n\n- repository-managed ImageMagick policy in `imagemagick-policy.xml`\n- resource limits for memory, disk, and image dimensions\n- disabled network delegates\n- disabled indirect path reads\n- application-layer behavior that pipes bytes through stdin and stdout instead of constructing shell commands around user-controlled paths\n\nContributors should treat these protections as required behavior. If a format change needs weaker policy or looser limits, that is an architectural change, not a local implementation tweak.\n\n## Operational Behavior\n\nThe preprocessing path is designed to fail explicitly rather than degrade silently.\n\n- invalid input is rejected during validation\n- unavailable ImageMagick raises preprocessing errors\n- timeout failures surface as preprocessing errors\n- unsupported extensions are rejected by the registry path\n\nThe converter then turns preprocessing failures into user-visible conversion failures for the preview API.\n\n## Configuration Surface\n\nThe main advanced settings for ImageMagick-backed preprocessing are:\n\n- `preprocessors.imagemagick.max_file_size_bytes`\n- `preprocessors.imagemagick.timeout_seconds`\n\nContributors should adjust those only when they understand the operational impact on preview latency, memory pressure, and denial-of-service resistance.\n\n## Adding or Changing a Preprocessing Path Safely\n\nUse this sequence when introducing a new preprocessable format or a new preprocessing backend:\n\n1. decide that the format really belongs in preprocessing rather than the ordinary libvips-backed conversion path\n2. implement or reuse a `PreprocessorInterface` subclass\n3. register the extension in `PreprocessorRegistry`\n4. update file-type metadata and viewer expectations if the format becomes previewable\n5. validate ImageMagick policy or other tool-level constraints if the new path needs different capabilities\n6. add backend tests for availability, validation, timeout behavior, and successful conversion output\n\nIf you skip the first decision, it becomes easy to route a format through preprocessing simply because it works locally, even when it weakens the long-term architecture.\n\n## Common Failure Modes\n\n- a new format is registered for preprocessing when the ordinary conversion path would have been safer or simpler\n- extension registration and file-type metadata drift apart\n- ImageMagick availability differs between local development and deployment\n- policy restrictions block a format in production even though it worked in a permissive local environment\n- timeout or file-size limits are raised casually to make one sample file work, increasing operational risk for everyone else\n\n## Where to Continue\n\n- Use [Viewer Architecture and Preview Contracts](../../frontend-architecture/viewer-architecture-and-preview-contracts/) for the browser-visible preview contract, file-type registry alignment, and viewer routing implications.\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider validation coverage.\n\n## Validation Expectations\n\nWhen you change preprocessing or image-conversion architecture, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects preview behavior, add the relevant frontend checks as well.\n", "0.8": "+++\ntitle = \"Image Preprocessing and Conversion Pipeline\"\n+++\n\nSambee's image preview path is not one converter with one code path.\n\nFor browser preview, the backend uses two related layers:\n\n- `backend/app/services/image_converter.py` for the general conversion pipeline\n- `backend/app/services/preprocessor.py` for formats that must be normalized before the general pipeline can produce browser-ready output\n\nUse this page when a format change affects backend conversion behavior, external image-tool dependencies, or preprocessing policy.\n\n## Why Preprocessing Exists\n\nSome formats can be decoded and converted directly through the main image-conversion path.\n\nOthers need an explicit preprocessing stage first because Sambee does not rely on the normal stack to decode them safely or usefully for browser preview.\n\nThat is the current role of preprocessing for formats such as:\n\n- `psd`\n- `psb`\n- `eps`\n- `ai`\n\nThe design goal is direct conversion to the final browser-ready result, not a chain of intermediate file formats.\n\n## Main Backend Pieces\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/services/image_converter.py` | primary image conversion path, libvips-backed processing, output-format selection, resizing, and MIME return values |\n| `backend/app/services/preprocessor.py` | preprocessor abstraction, ImageMagick-backed implementation, format registry, and factory behavior |\n| `backend/app/core/image_settings.py` | centralized encoder arguments and output-tuning settings |\n| `imagemagick-policy.xml` | repository-managed ImageMagick policy that constrains resource and delegate behavior |\n\n## Runtime Flow\n\nAt a high level, the backend image-preview flow is:\n\n1. the viewer request reaches the backend preview path\n2. the backend determines the file extension and preview behavior\n3. the converter checks whether the extension requires preprocessing\n4. preprocessable formats are sent to the registered preprocessor directly to produce browser-ready bytes\n5. all other convertible formats stay on the libvips-backed conversion path\n6. the viewer endpoint returns the converted bytes with the resulting MIME type\n\nThis is why preview changes can span registry metadata, service logic, environment dependencies, and viewer expectations at the same time.\n\n## General Conversion Path\n\n`convert_image_for_viewer(...)` in `image_converter.py` is the main entry point.\n\nFor the general conversion path it is responsible for:\n\n- loading image data through libvips\n- detecting alpha handling needs\n- converting colorspaces for web-safe output\n- downscaling when max dimensions are configured\n- choosing a final output format such as WebP, JPEG, or PNG\n- returning `(bytes, mime_type, converter_name, duration_ms)` for the caller\n\nThis is the path used for formats such as TIFF, HEIC, BMP, ICO, and similar server-converted formats that do not need the separate preprocessing registry.\n\n## Preprocessing Path\n\nWhen the extension is registered in `PreprocessorRegistry`, the converter takes a different route.\n\n`PreprocessorRegistry.requires_preprocessing(extension)` decides whether the format uses the preprocessing path.\n\nIf it does:\n\n1. the converter resolves the preprocessor with `get_preprocessor_for_format(...)`\n2. the preprocessor converts the source bytes directly to the final browser-ready format\n3. the converter returns those bytes without sending them through a second conversion stage\n\nCurrent product behavior intentionally chooses:\n\n- JPEG output for raster-oriented preprocessable formats such as PSD and PSB\n- PNG output for vector-style preprocessable formats such as EPS and AI when transparency preservation matters more\n\nThat is a product behavior decision, not just an implementation convenience.\n\n## Preprocessor Abstractions\n\nThe preprocessing service is structured around three backend concepts.\n\n### Preprocessorinterface\n\n`PreprocessorInterface` defines the contract every preprocessor must satisfy.\n\nKey responsibilities include:\n\n- `check_availability()`\n- `validate_input(...)`\n- `convert_to_final_format(...)`\n\nIt also centralizes file-size and timeout access through system settings so those limits do not get hard-coded in format-specific code.\n\n### Imagemagickpreprocessor\n\n`ImageMagickPreprocessor` is the only built-in implementation today.\n\nIt is responsible for:\n\n- requiring ImageMagick 7 through `magick`\n- validating supported extensions\n- converting PSD, PSB, EPS, and AI input directly to JPEG or PNG\n- applying centralized output arguments from `image_settings.py`\n- handling colorspace normalization, including CMYK-to-sRGB conversion behavior\n- enforcing timeout and size checks before or during conversion\n\nFor vector formats such as EPS and AI, it also applies density settings so rendered output quality is usable in the browser.\n\n### Preprocessor Registry and Factory\n\n`PreprocessorRegistry` is the single source of truth for which extensions require preprocessing and which preprocessor class handles them.\n\nThe registry:\n\n- normalizes extension lookup case-insensitively\n- maps extensions such as `psd`, `psb`, `eps`, and `ai` to `ImageMagickPreprocessor`\n- allows explicit runtime registration of additional formats\n- does not implement multi-tool fallback chains itself\n\n`PreprocessorFactory` is the configuration-oriented construction layer.\n\nIt currently supports:\n\n- `PREPROCESSOR=imagemagick`\n- `PREPROCESSOR=auto`\n\n`auto` currently means: use ImageMagick if it is available.\n\n## Security and Policy Constraints\n\nThe preprocessing path runs external tooling, so its constraints are part of the product contract.\n\nImportant protections include:\n\n- repository-managed ImageMagick policy in `imagemagick-policy.xml`\n- resource limits for memory, disk, and image dimensions\n- disabled network delegates\n- disabled indirect path reads\n- application-layer behavior that pipes bytes through stdin and stdout instead of constructing shell commands around user-controlled paths\n\nContributors should treat these protections as required behavior. If a format change needs weaker policy or looser limits, that is an architectural change, not a local implementation tweak.\n\n## Operational Behavior\n\nThe preprocessing path is designed to fail explicitly rather than degrade silently.\n\n- invalid input is rejected during validation\n- unavailable ImageMagick raises preprocessing errors\n- timeout failures surface as preprocessing errors\n- unsupported extensions are rejected by the registry path\n\nThe converter then turns preprocessing failures into user-visible conversion failures for the preview API.\n\n## Configuration Surface\n\nThe main advanced settings for ImageMagick-backed preprocessing are:\n\n- `preprocessors.imagemagick.max_file_size_bytes`\n- `preprocessors.imagemagick.timeout_seconds`\n\nContributors should adjust those only when they understand the operational impact on preview latency, memory pressure, and denial-of-service resistance.\n\n## Adding or Changing a Preprocessing Path Safely\n\nUse this sequence when introducing a new preprocessable format or a new preprocessing backend:\n\n1. decide that the format really belongs in preprocessing rather than the ordinary libvips-backed conversion path\n2. implement or reuse a `PreprocessorInterface` subclass\n3. register the extension in `PreprocessorRegistry`\n4. update file-type metadata and viewer expectations if the format becomes previewable\n5. validate ImageMagick policy or other tool-level constraints if the new path needs different capabilities\n6. add backend tests for availability, validation, timeout behavior, and successful conversion output\n\nIf you skip the first decision, it becomes easy to route a format through preprocessing simply because it works locally, even when it weakens the long-term architecture.\n\n## Common Failure Modes\n\n- a new format is registered for preprocessing when the ordinary conversion path would have been safer or simpler\n- extension registration and file-type metadata drift apart\n- ImageMagick availability differs between local development and deployment\n- policy restrictions block a format in production even though it worked in a permissive local environment\n- timeout or file-size limits are raised casually to make one sample file work, increasing operational risk for everyone else\n\n## Where to Continue\n\n- Use [Viewer Architecture and Preview Contracts](../../frontend-architecture/viewer-architecture-and-preview-contracts/) for the browser-visible preview contract, file-type registry alignment, and viewer routing implications.\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider validation coverage.\n\n## Validation Expectations\n\nWhen you change preprocessing or image-conversion architecture, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects preview behavior, add the relevant frontend checks as well.\n", "0.9": "+++\ntitle = \"Image Preprocessing and Conversion Pipeline\"\n+++\n\nSambee's image preview path is not one converter with one code path.\n\nFor browser preview, the backend uses two related layers:\n\n- `backend/app/services/image_converter.py` for the general conversion pipeline\n- `backend/app/services/preprocessor.py` for formats that must be normalized before the general pipeline can produce browser-ready output\n\nUse this page when a format change affects backend conversion behavior, external image-tool dependencies, or preprocessing policy.\n\n## Why Preprocessing Exists\n\nSome formats can be decoded and converted directly through the main image-conversion path.\n\nOthers need an explicit preprocessing stage first because Sambee does not rely on the normal stack to decode them safely or usefully for browser preview.\n\nThat is the current role of preprocessing for formats such as:\n\n- `psd`\n- `psb`\n- `eps`\n- `ai`\n\nThe design goal is direct conversion to the final browser-ready result, not a chain of intermediate file formats.\n\n## Main Backend Pieces\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/services/image_converter.py` | primary image conversion path, libvips-backed processing, output-format selection, resizing, and MIME return values |\n| `backend/app/services/preprocessor.py` | preprocessor abstraction, ImageMagick-backed implementation, format registry, and factory behavior |\n| `backend/app/core/image_settings.py` | centralized encoder arguments and output-tuning settings |\n| `imagemagick-policy.xml` | repository-managed ImageMagick policy that constrains resource and delegate behavior |\n\n## Runtime Flow\n\nAt a high level, the backend image-preview flow is:\n\n1. the viewer request reaches the backend preview path\n2. the backend determines the file extension and preview behavior\n3. the converter checks whether the extension requires preprocessing\n4. preprocessable formats are sent to the registered preprocessor directly to produce browser-ready bytes\n5. all other convertible formats stay on the libvips-backed conversion path\n6. the viewer endpoint returns the converted bytes with the resulting MIME type\n\nThis is why preview changes can span registry metadata, service logic, environment dependencies, and viewer expectations at the same time.\n\n## General Conversion Path\n\n`convert_image_for_viewer(...)` in `image_converter.py` is the main entry point.\n\nFor the general conversion path it is responsible for:\n\n- loading image data through libvips\n- detecting alpha handling needs\n- converting colorspaces for web-safe output\n- downscaling when max dimensions are configured\n- choosing a final output format such as WebP, JPEG, or PNG\n- returning `(bytes, mime_type, converter_name, duration_ms)` for the caller\n\nThis is the path used for formats such as TIFF, HEIC, BMP, ICO, and similar server-converted formats that do not need the separate preprocessing registry.\n\n## Preprocessing Path\n\nWhen the extension is registered in `PreprocessorRegistry`, the converter takes a different route.\n\n`PreprocessorRegistry.requires_preprocessing(extension)` decides whether the format uses the preprocessing path.\n\nIf it does:\n\n1. the converter resolves the preprocessor with `get_preprocessor_for_format(...)`\n2. the preprocessor converts the source bytes directly to the final browser-ready format\n3. the converter returns those bytes without sending them through a second conversion stage\n\nCurrent product behavior intentionally chooses:\n\n- JPEG output for raster-oriented preprocessable formats such as PSD and PSB\n- PNG output for vector-style preprocessable formats such as EPS and AI when transparency preservation matters more\n\nThat is a product behavior decision, not just an implementation convenience.\n\n## Preprocessor Abstractions\n\nThe preprocessing service is structured around three backend concepts.\n\n### Preprocessorinterface\n\n`PreprocessorInterface` defines the contract every preprocessor must satisfy.\n\nKey responsibilities include:\n\n- `check_availability()`\n- `validate_input(...)`\n- `convert_to_final_format(...)`\n\nIt also centralizes file-size and timeout access through system settings so those limits do not get hard-coded in format-specific code.\n\n### Imagemagickpreprocessor\n\n`ImageMagickPreprocessor` is the only built-in implementation today.\n\nIt is responsible for:\n\n- requiring ImageMagick 7 through `magick`\n- validating supported extensions\n- converting PSD, PSB, EPS, and AI input directly to JPEG or PNG\n- applying centralized output arguments from `image_settings.py`\n- handling colorspace normalization, including CMYK-to-sRGB conversion behavior\n- enforcing timeout and size checks before or during conversion\n\nFor vector formats such as EPS and AI, it also applies density settings so rendered output quality is usable in the browser.\n\n### Preprocessor Registry and Factory\n\n`PreprocessorRegistry` is the single source of truth for which extensions require preprocessing and which preprocessor class handles them.\n\nThe registry:\n\n- normalizes extension lookup case-insensitively\n- maps extensions such as `psd`, `psb`, `eps`, and `ai` to `ImageMagickPreprocessor`\n- allows explicit runtime registration of additional formats\n- does not implement multi-tool fallback chains itself\n\n`PreprocessorFactory` is the configuration-oriented construction layer.\n\nIt currently supports:\n\n- `PREPROCESSOR=imagemagick`\n- `PREPROCESSOR=auto`\n\n`auto` currently means: use ImageMagick if it is available.\n\n## Security and Policy Constraints\n\nThe preprocessing path runs external tooling, so its constraints are part of the product contract.\n\nImportant protections include:\n\n- repository-managed ImageMagick policy in `imagemagick-policy.xml`\n- resource limits for memory, disk, and image dimensions\n- disabled network delegates\n- disabled indirect path reads\n- application-layer behavior that pipes bytes through stdin and stdout instead of constructing shell commands around user-controlled paths\n\nContributors should treat these protections as required behavior. If a format change needs weaker policy or looser limits, that is an architectural change, not a local implementation tweak.\n\n## Operational Behavior\n\nThe preprocessing path is designed to fail explicitly rather than degrade silently.\n\n- invalid input is rejected during validation\n- unavailable ImageMagick raises preprocessing errors\n- timeout failures surface as preprocessing errors\n- unsupported extensions are rejected by the registry path\n\nThe converter then turns preprocessing failures into user-visible conversion failures for the preview API.\n\n## Configuration Surface\n\nThe main advanced settings for ImageMagick-backed preprocessing are:\n\n- `preprocessors.imagemagick.max_file_size_bytes`\n- `preprocessors.imagemagick.timeout_seconds`\n\nContributors should adjust those only when they understand the operational impact on preview latency, memory pressure, and denial-of-service resistance.\n\n## Adding or Changing a Preprocessing Path Safely\n\nUse this sequence when introducing a new preprocessable format or a new preprocessing backend:\n\n1. decide that the format really belongs in preprocessing rather than the ordinary libvips-backed conversion path\n2. implement or reuse a `PreprocessorInterface` subclass\n3. register the extension in `PreprocessorRegistry`\n4. update file-type metadata and viewer expectations if the format becomes previewable\n5. validate ImageMagick policy or other tool-level constraints if the new path needs different capabilities\n6. add backend tests for availability, validation, timeout behavior, and successful conversion output\n\nIf you skip the first decision, it becomes easy to route a format through preprocessing simply because it works locally, even when it weakens the long-term architecture.\n\n## Common Failure Modes\n\n- a new format is registered for preprocessing when the ordinary conversion path would have been safer or simpler\n- extension registration and file-type metadata drift apart\n- ImageMagick availability differs between local development and deployment\n- policy restrictions block a format in production even though it worked in a permissive local environment\n- timeout or file-size limits are raised casually to make one sample file work, increasing operational risk for everyone else\n\n## Where to Continue\n\n- Use [Viewer Architecture and Preview Contracts](../../frontend-architecture/viewer-architecture-and-preview-contracts/) for the browser-visible preview contract, file-type registry alignment, and viewer routing implications.\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider validation coverage.\n\n## Validation Expectations\n\nWhen you change preprocessing or image-conversion architecture, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects preview behavior, add the relevant frontend checks as well.\n", "1.0": "+++\ntitle = \"Image Preprocessing and Conversion Pipeline\"\n+++\n\nSambee's image preview path is not one converter with one code path.\n\nFor browser preview, the backend uses two related layers:\n\n- `backend/app/services/image_converter.py` for the general conversion pipeline\n- `backend/app/services/preprocessor.py` for formats that must be normalized before the general pipeline can produce browser-ready output\n\nUse this page when a format change affects backend conversion behavior, external image-tool dependencies, or preprocessing policy.\n\n## Why Preprocessing Exists\n\nSome formats can be decoded and converted directly through the main image-conversion path.\n\nOthers need an explicit preprocessing stage first because Sambee does not rely on the normal stack to decode them safely or usefully for browser preview.\n\nThat is the current role of preprocessing for formats such as:\n\n- `psd`\n- `psb`\n- `eps`\n- `ai`\n\nThe design goal is direct conversion to the final browser-ready result, not a chain of intermediate file formats.\n\n## Main Backend Pieces\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/services/image_converter.py` | primary image conversion path, libvips-backed processing, output-format selection, resizing, and MIME return values |\n| `backend/app/services/preprocessor.py` | preprocessor abstraction, ImageMagick-backed implementation, format registry, and factory behavior |\n| `backend/app/core/image_settings.py` | centralized encoder arguments and output-tuning settings |\n| `imagemagick-policy.xml` | repository-managed ImageMagick policy that constrains resource and delegate behavior |\n\n## Runtime Flow\n\nAt a high level, the backend image-preview flow is:\n\n1. the viewer request reaches the backend preview path\n2. the backend determines the file extension and preview behavior\n3. the converter checks whether the extension requires preprocessing\n4. preprocessable formats are sent to the registered preprocessor directly to produce browser-ready bytes\n5. all other convertible formats stay on the libvips-backed conversion path\n6. the viewer endpoint returns the converted bytes with the resulting MIME type\n\nThis is why preview changes can span registry metadata, service logic, environment dependencies, and viewer expectations at the same time.\n\n## General Conversion Path\n\n`convert_image_for_viewer(...)` in `image_converter.py` is the main entry point.\n\nFor the general conversion path it is responsible for:\n\n- loading image data through libvips\n- detecting alpha handling needs\n- converting colorspaces for web-safe output\n- downscaling when max dimensions are configured\n- choosing a final output format such as WebP, JPEG, or PNG\n- returning `(bytes, mime_type, converter_name, duration_ms)` for the caller\n\nThis is the path used for formats such as TIFF, HEIC, BMP, ICO, and similar server-converted formats that do not need the separate preprocessing registry.\n\n## Preprocessing Path\n\nWhen the extension is registered in `PreprocessorRegistry`, the converter takes a different route.\n\n`PreprocessorRegistry.requires_preprocessing(extension)` decides whether the format uses the preprocessing path.\n\nIf it does:\n\n1. the converter resolves the preprocessor with `get_preprocessor_for_format(...)`\n2. the preprocessor converts the source bytes directly to the final browser-ready format\n3. the converter returns those bytes without sending them through a second conversion stage\n\nCurrent product behavior intentionally chooses:\n\n- JPEG output for raster-oriented preprocessable formats such as PSD and PSB\n- PNG output for vector-style preprocessable formats such as EPS and AI when transparency preservation matters more\n\nThat is a product behavior decision, not just an implementation convenience.\n\n## Preprocessor Abstractions\n\nThe preprocessing service is structured around three backend concepts.\n\n### Preprocessorinterface\n\n`PreprocessorInterface` defines the contract every preprocessor must satisfy.\n\nKey responsibilities include:\n\n- `check_availability()`\n- `validate_input(...)`\n- `convert_to_final_format(...)`\n\nIt also centralizes file-size and timeout access through system settings so those limits do not get hard-coded in format-specific code.\n\n### Imagemagickpreprocessor\n\n`ImageMagickPreprocessor` is the only built-in implementation today.\n\nIt is responsible for:\n\n- requiring ImageMagick 7 through `magick`\n- validating supported extensions\n- converting PSD, PSB, EPS, and AI input directly to JPEG or PNG\n- applying centralized output arguments from `image_settings.py`\n- handling colorspace normalization, including CMYK-to-sRGB conversion behavior\n- enforcing timeout and size checks before or during conversion\n\nFor vector formats such as EPS and AI, it also applies density settings so rendered output quality is usable in the browser.\n\n### Preprocessor Registry and Factory\n\n`PreprocessorRegistry` is the single source of truth for which extensions require preprocessing and which preprocessor class handles them.\n\nThe registry:\n\n- normalizes extension lookup case-insensitively\n- maps extensions such as `psd`, `psb`, `eps`, and `ai` to `ImageMagickPreprocessor`\n- allows explicit runtime registration of additional formats\n- does not implement multi-tool fallback chains itself\n\n`PreprocessorFactory` is the configuration-oriented construction layer.\n\nIt currently supports:\n\n- `PREPROCESSOR=imagemagick`\n- `PREPROCESSOR=auto`\n\n`auto` currently means: use ImageMagick if it is available.\n\n## Security and Policy Constraints\n\nThe preprocessing path runs external tooling, so its constraints are part of the product contract.\n\nImportant protections include:\n\n- repository-managed ImageMagick policy in `imagemagick-policy.xml`\n- resource limits for memory, disk, and image dimensions\n- disabled network delegates\n- disabled indirect path reads\n- application-layer behavior that pipes bytes through stdin and stdout instead of constructing shell commands around user-controlled paths\n\nContributors should treat these protections as required behavior. If a format change needs weaker policy or looser limits, that is an architectural change, not a local implementation tweak.\n\n## Operational Behavior\n\nThe preprocessing path is designed to fail explicitly rather than degrade silently.\n\n- invalid input is rejected during validation\n- unavailable ImageMagick raises preprocessing errors\n- timeout failures surface as preprocessing errors\n- unsupported extensions are rejected by the registry path\n\nThe converter then turns preprocessing failures into user-visible conversion failures for the preview API.\n\n## Configuration Surface\n\nThe main advanced settings for ImageMagick-backed preprocessing are:\n\n- `preprocessors.imagemagick.max_file_size_bytes`\n- `preprocessors.imagemagick.timeout_seconds`\n\nContributors should adjust those only when they understand the operational impact on preview latency, memory pressure, and denial-of-service resistance.\n\n## Adding or Changing a Preprocessing Path Safely\n\nUse this sequence when introducing a new preprocessable format or a new preprocessing backend:\n\n1. decide that the format really belongs in preprocessing rather than the ordinary libvips-backed conversion path\n2. implement or reuse a `PreprocessorInterface` subclass\n3. register the extension in `PreprocessorRegistry`\n4. update file-type metadata and viewer expectations if the format becomes previewable\n5. validate ImageMagick policy or other tool-level constraints if the new path needs different capabilities\n6. add backend tests for availability, validation, timeout behavior, and successful conversion output\n\nIf you skip the first decision, it becomes easy to route a format through preprocessing simply because it works locally, even when it weakens the long-term architecture.\n\n## Common Failure Modes\n\n- a new format is registered for preprocessing when the ordinary conversion path would have been safer or simpler\n- extension registration and file-type metadata drift apart\n- ImageMagick availability differs between local development and deployment\n- policy restrictions block a format in production even though it worked in a permissive local environment\n- timeout or file-size limits are raised casually to make one sample file work, increasing operational risk for everyone else\n\n## Where to Continue\n\n- Use [Viewer Architecture and Preview Contracts](../../frontend-architecture/viewer-architecture-and-preview-contracts/) for the browser-visible preview contract, file-type registry alignment, and viewer routing implications.\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider validation coverage.\n\n## Validation Expectations\n\nWhen you change preprocessing or image-conversion architecture, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects preview behavior, add the relevant frontend checks as well.\n", "2.0": "+++\ntitle = \"Image Preprocessing and Conversion Pipeline\"\n+++\n\nSambee's image preview path is not one converter with one code path.\n\nFor browser preview, the backend uses two related layers:\n\n- `backend/app/services/image_converter.py` for the general conversion pipeline\n- `backend/app/services/preprocessor.py` for formats that must be normalized before the general pipeline can produce browser-ready output\n\nUse this page when a format change affects backend conversion behavior, external image-tool dependencies, or preprocessing policy.\n\n## Why Preprocessing Exists\n\nSome formats can be decoded and converted directly through the main image-conversion path.\n\nOthers need an explicit preprocessing stage first because Sambee does not rely on the normal stack to decode them safely or usefully for browser preview.\n\nThat is the current role of preprocessing for formats such as:\n\n- `psd`\n- `psb`\n- `eps`\n- `ai`\n\nThe design goal is direct conversion to the final browser-ready result, not a chain of intermediate file formats.\n\n## Main Backend Pieces\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/services/image_converter.py` | primary image conversion path, libvips-backed processing, output-format selection, resizing, and MIME return values |\n| `backend/app/services/preprocessor.py` | preprocessor abstraction, ImageMagick-backed implementation, format registry, and factory behavior |\n| `backend/app/core/image_settings.py` | centralized encoder arguments and output-tuning settings |\n| `imagemagick-policy.xml` | repository-managed ImageMagick policy that constrains resource and delegate behavior |\n\n## Runtime Flow\n\nAt a high level, the backend image-preview flow is:\n\n1. the viewer request reaches the backend preview path\n2. the backend determines the file extension and preview behavior\n3. the converter checks whether the extension requires preprocessing\n4. preprocessable formats are sent to the registered preprocessor directly to produce browser-ready bytes\n5. all other convertible formats stay on the libvips-backed conversion path\n6. the viewer endpoint returns the converted bytes with the resulting MIME type\n\nThis is why preview changes can span registry metadata, service logic, environment dependencies, and viewer expectations at the same time.\n\n## General Conversion Path\n\n`convert_image_for_viewer(...)` in `image_converter.py` is the main entry point.\n\nFor the general conversion path it is responsible for:\n\n- loading image data through libvips\n- detecting alpha handling needs\n- converting colorspaces for web-safe output\n- downscaling when max dimensions are configured\n- choosing a final output format such as WebP, JPEG, or PNG\n- returning `(bytes, mime_type, converter_name, duration_ms)` for the caller\n\nThis is the path used for formats such as TIFF, HEIC, BMP, ICO, and similar server-converted formats that do not need the separate preprocessing registry.\n\n## Preprocessing Path\n\nWhen the extension is registered in `PreprocessorRegistry`, the converter takes a different route.\n\n`PreprocessorRegistry.requires_preprocessing(extension)` decides whether the format uses the preprocessing path.\n\nIf it does:\n\n1. the converter resolves the preprocessor with `get_preprocessor_for_format(...)`\n2. the preprocessor converts the source bytes directly to the final browser-ready format\n3. the converter returns those bytes without sending them through a second conversion stage\n\nCurrent product behavior intentionally chooses:\n\n- JPEG output for raster-oriented preprocessable formats such as PSD and PSB\n- PNG output for vector-style preprocessable formats such as EPS and AI when transparency preservation matters more\n\nThat is a product behavior decision, not just an implementation convenience.\n\n## Preprocessor Abstractions\n\nThe preprocessing service is structured around three backend concepts.\n\n### Preprocessorinterface\n\n`PreprocessorInterface` defines the contract every preprocessor must satisfy.\n\nKey responsibilities include:\n\n- `check_availability()`\n- `validate_input(...)`\n- `convert_to_final_format(...)`\n\nIt also centralizes file-size and timeout access through system settings so those limits do not get hard-coded in format-specific code.\n\n### Imagemagickpreprocessor\n\n`ImageMagickPreprocessor` is the only built-in implementation today.\n\nIt is responsible for:\n\n- requiring ImageMagick 7 through `magick`\n- validating supported extensions\n- converting PSD, PSB, EPS, and AI input directly to JPEG or PNG\n- applying centralized output arguments from `image_settings.py`\n- handling colorspace normalization, including CMYK-to-sRGB conversion behavior\n- enforcing timeout and size checks before or during conversion\n\nFor vector formats such as EPS and AI, it also applies density settings so rendered output quality is usable in the browser.\n\n### Preprocessor Registry and Factory\n\n`PreprocessorRegistry` is the single source of truth for which extensions require preprocessing and which preprocessor class handles them.\n\nThe registry:\n\n- normalizes extension lookup case-insensitively\n- maps extensions such as `psd`, `psb`, `eps`, and `ai` to `ImageMagickPreprocessor`\n- allows explicit runtime registration of additional formats\n- does not implement multi-tool fallback chains itself\n\n`PreprocessorFactory` is the configuration-oriented construction layer.\n\nIt currently supports:\n\n- `PREPROCESSOR=imagemagick`\n- `PREPROCESSOR=auto`\n\n`auto` currently means: use ImageMagick if it is available.\n\n## Security and Policy Constraints\n\nThe preprocessing path runs external tooling, so its constraints are part of the product contract.\n\nImportant protections include:\n\n- repository-managed ImageMagick policy in `imagemagick-policy.xml`\n- resource limits for memory, disk, and image dimensions\n- disabled network delegates\n- disabled indirect path reads\n- application-layer behavior that pipes bytes through stdin and stdout instead of constructing shell commands around user-controlled paths\n\nContributors should treat these protections as required behavior. If a format change needs weaker policy or looser limits, that is an architectural change, not a local implementation tweak.\n\n## Operational Behavior\n\nThe preprocessing path is designed to fail explicitly rather than degrade silently.\n\n- invalid input is rejected during validation\n- unavailable ImageMagick raises preprocessing errors\n- timeout failures surface as preprocessing errors\n- unsupported extensions are rejected by the registry path\n\nThe converter then turns preprocessing failures into user-visible conversion failures for the preview API.\n\n## Configuration Surface\n\nThe main advanced settings for ImageMagick-backed preprocessing are:\n\n- `preprocessors.imagemagick.max_file_size_bytes`\n- `preprocessors.imagemagick.timeout_seconds`\n\nContributors should adjust those only when they understand the operational impact on preview latency, memory pressure, and denial-of-service resistance.\n\n## Adding or Changing a Preprocessing Path Safely\n\nUse this sequence when introducing a new preprocessable format or a new preprocessing backend:\n\n1. decide that the format really belongs in preprocessing rather than the ordinary libvips-backed conversion path\n2. implement or reuse a `PreprocessorInterface` subclass\n3. register the extension in `PreprocessorRegistry`\n4. update file-type metadata and viewer expectations if the format becomes previewable\n5. validate ImageMagick policy or other tool-level constraints if the new path needs different capabilities\n6. add backend tests for availability, validation, timeout behavior, and successful conversion output\n\nIf you skip the first decision, it becomes easy to route a format through preprocessing simply because it works locally, even when it weakens the long-term architecture.\n\n## Common Failure Modes\n\n- a new format is registered for preprocessing when the ordinary conversion path would have been safer or simpler\n- extension registration and file-type metadata drift apart\n- ImageMagick availability differs between local development and deployment\n- policy restrictions block a format in production even though it worked in a permissive local environment\n- timeout or file-size limits are raised casually to make one sample file work, increasing operational risk for everyone else\n\n## Where to Continue\n\n- Use [Viewer Architecture and Preview Contracts](../../frontend-architecture/viewer-architecture-and-preview-contracts/) for the browser-visible preview contract, file-type registry alignment, and viewer routing implications.\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider validation coverage.\n\n## Validation Expectations\n\nWhen you change preprocessing or image-conversion architecture, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects preview behavior, add the relevant frontend checks as well.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/backend-architecture/smb-change-notification-and-directory-freshness", "parent_id": "section:developer-guide/backend-architecture", "depth": 2, "kind": "page", "label": "smb-change-notification-and-directory-freshness", "title": "Smb Change Notification And Directory Freshness", "path": "developer-guide/backend-architecture/smb-change-notification-and-directory-freshness", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "branched", "source_version": "0.7", "diff_added": 23, "diff_removed": 1}}, "content_versions": {"0.7": "+++\ntitle = \"SMB Change Notification and Directory Freshness\"\n+++\n\nSambee uses SMB2/SMB3 `CHANGE_NOTIFY` support to keep directory state fresh without falling back to naive polling.\n\nThat capability is used in two different backend paths:\n\n- `backend/app/services/directory_monitor.py` for browser-visible WebSocket refresh notifications\n- `backend/app/services/directory_cache.py` for per-connection directory-cache freshness\n\nUse this page when a backend change affects WebSocket directory updates, SMB watcher lifecycle, or how the product maintains fresh directory state over time.\n\n## Why This Matters\n\nDirectory freshness is a cross-boundary product contract.\n\nUsers expect Sambee to react when:\n\n- another SMB client creates, deletes, renames, or edits content in the current directory\n- the current browser view should refresh because the underlying SMB directory changed\n- cached directory-search data should stay reasonably current without rescanning the entire tree on every request\n\nThat is why the backend owns change-notification behavior instead of leaving refresh decisions entirely to the browser.\n\n## The Two Change-Notification Paths\n\nSambee does not have a single watcher for all purposes.\n\n### Browser Notification Path\n\n`directory_monitor.py` is responsible for directory-specific monitoring tied to active WebSocket subscriptions.\n\nIts job is to:\n\n- start watching a directory when the first browser subscriber appears\n- share one SMB monitor across multiple subscribers for the same watched path\n- stop monitoring when the last subscriber leaves\n- send `directory_changed` messages back through the WebSocket layer\n\nThis is the path that keeps an open file browser view fresh.\n\n### Directory-Cache Freshness Path\n\n`directory_cache.py` uses its own `CHANGE_NOTIFY` watcher for a different reason.\n\nIts job is to:\n\n- watch the share root or effective path prefix for directory-name changes\n- keep the in-memory directory cache aligned with adds, removes, and renames\n- combine event-driven updates with periodic full rescans as a safety net\n- preserve fast directory-search behavior without rebuilding the entire cache on every navigation event\n\nThis is not the same as the browser WebSocket monitor, even though both rely on SMB `CHANGE_NOTIFY`.\n\n## Browser Notification Flow\n\nAt a high level, the browser-facing flow is:\n\n1. the browser opens the backend WebSocket endpoint\n2. it sends a subscription message for a connection and directory path\n3. `ConnectionManager` resolves access, applies any `path_prefix`, and starts monitoring if this is the first subscriber\n4. `DirectoryMonitor` opens SMB resources for that resolved directory and starts a background watcher thread\n5. when the SMB server reports a change, the backend emits `directory_changed` to all subscribers for the user-facing path\n6. when the last subscriber leaves, the monitor stops and releases its SMB resources\n\nRepresentative client messages include:\n\n- subscribe: `{ \"action\": \"subscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- unsubscribe: `{ \"action\": \"unsubscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- server notification: `{ \"type\": \"directory_changed\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n\n## Path Resolution and Subscription Keys\n\nOne subtle but important part of the design is that browser subscriptions and SMB watches do not always use the same path string.\n\nThe WebSocket layer keys subscriptions by the user-facing path.\n\nIf the SMB connection has a `path_prefix`, the backend resolves the actual watched SMB path by combining:\n\n- the normalized connection prefix\n- the user-facing relative path\n\nThat resolved SMB path is what `DirectoryMonitor` actually watches.\n\nThe callback then maps notifications back to the user-facing path before sending `directory_changed` over the WebSocket.\n\nIf you remove that mapping, subscriptions stop lining up with the paths the browser thinks it subscribed to.\n\n## Main Components\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/api/websocket.py` | WebSocket endpoint, subscription bookkeeping, access checks, path-prefix resolution, and delivery of `directory_changed` events |\n| `backend/app/services/directory_monitor.py` | per-directory SMB watchers for active browser subscriptions |\n| `backend/app/services/directory_cache.py` | per-connection directory cache plus root-level `CHANGE_NOTIFY` watcher for cache freshness |\n| `backend/app/main.py` | application shutdown hooks for directory caches and directory monitors |\n\n## Directory Monitor Lifecycle\n\nThe browser-facing monitor is reference-counted by subscription demand.\n\n`DirectoryMonitor` keeps one `MonitoredDirectory` per `connection_id:path` key and tracks subscriber counts.\n\nThat means:\n\n- the first subscriber starts the monitor\n- later subscribers reuse the same watched directory instance\n- unsubscribing decrements the count\n- the monitor only stops when the count reaches zero\n\nThis avoids opening duplicate SMB watcher handles for the same directory just because multiple browser clients are watching it.\n\n## SMB Resource Management\n\n`MonitoredDirectory` owns low-level SMB resources directly.\n\nCreation follows this order:\n\n1. connection\n2. session\n3. tree connect\n4. directory open handle\n5. `FileSystemWatcher`\n\nCleanup happens in reverse order so partial failure does not leak handles.\n\nThat ordering is important because change-notification bugs are often really handle-lifecycle bugs.\n\n## Watched Events\n\nThe browser-facing monitor currently watches for:\n\n- file-name changes\n- directory-name changes\n- size changes\n- last-write changes\n\nIt uses tree watching so changes in subdirectories can also surface through the same watch.\n\nThe directory-cache watcher is narrower by design.\n\nIt watches directory-name changes across the tree because the cache only needs enough signal to update its directory index efficiently.\n\n## Recovery and Failure Handling\n\nThe directory monitor treats connection failures as part of normal long-lived operation, not as impossible edge cases.\n\nCurrent behavior includes:\n\n- exponential backoff for reconnect attempts\n- retry jitter to avoid synchronized reconnect storms\n- capped retry attempts before giving up\n- explicit detection of connection, socket, and timeout failures\n- stop-on-delete behavior when the watched directory itself is deleted\n\nThe cache watcher has its own retry loop and also tolerates `CHANGE_NOTIFY` buffer-overflow conditions by relying on later rescans to restore correctness.\n\nThat distinction matters: browser notification is path-specific and subscriber-driven, while the cache watcher is connection-scoped and consistency-oriented.\n\n## Shutdown Behavior\n\nSambee shuts these systems down explicitly.\n\nDuring application shutdown:\n\n- directory caches are stopped through `shutdown_directory_cache()`\n- directory monitors are stopped through `shutdown_monitor()`\n\nThat explicit shutdown path exists to release watcher threads and SMB handles cleanly instead of depending on interpreter teardown.\n\n## Performance Characteristics\n\nThe design tries to keep freshness inexpensive without resorting to constant polling.\n\n- SMB `CHANGE_NOTIFY` is event-driven rather than poll-based\n- multiple browser subscribers share one monitor for the same watched path\n- directory-cache updates avoid full rescans for every single directory rename or add event\n- periodic rescans remain in place as a correctness safety net, not the primary freshness mechanism\n\n## Limits and Tradeoffs\n\nContributors need to preserve a few constraints here.\n\n- this requires SMB2 or later\n- some notifications can still be missed during network instability, which is why manual refresh and periodic cache rescans still matter\n- the browser-facing path is optimized for telling clients to refresh, not for transmitting rich per-file diffs\n- cache freshness and browser freshness are related concerns, but they are not the same subsystem and should not be collapsed casually\n\n## Common Failure Modes\n\n- path-prefix resolution is ignored, so the monitor watches the wrong SMB directory\n- subscriber bookkeeping drifts, so monitors are leaked or stopped too early\n- WebSocket disconnect cleanup forgets to release the last subscriber's monitor\n- a recovery change handles one timeout path but leaks SMB resources on reconnect\n- buffer-overflow or rename-edge handling is simplified in ways that quietly degrade cache correctness\n\n## Where to Continue\n\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the changed behavior interacts with uploads, moves, renames, or companion-assisted editing.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider backend or browser validation.\n\n## Validation Expectations\n\nWhen you change SMB change-notification behavior, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects browser-visible refresh behavior, add the relevant frontend checks as well.\n", "0.8": "+++\ntitle = \"SMB Change Notification and Directory Freshness\"\n+++\n\nSambee uses SMB2/SMB3 `CHANGE_NOTIFY` support to keep directory state fresh without falling back to naive polling.\n\nThat capability is used in two different backend paths:\n\n- `backend/app/services/directory_monitor.py` for browser-visible WebSocket refresh notifications\n- `backend/app/services/directory_cache.py` for per-connection directory-cache freshness\n\nUse this page when a backend change affects WebSocket directory updates, SMB watcher lifecycle, or how the product maintains fresh directory state over time.\n\n## Why This Matters\n\nDirectory freshness is a cross-boundary product contract.\n\nUsers expect Sambee to react when:\n\n- another SMB client creates, deletes, renames, or edits content in the current directory\n- the current browser view should refresh because the underlying SMB directory changed\n- cached directory-search data should stay reasonably current without rescanning the entire tree on every request\n\nThat is why the backend owns change-notification behavior instead of leaving refresh decisions entirely to the browser.\n\n## The Two Change-Notification Paths\n\nSambee does not have a single watcher for all purposes.\n\n### Browser Notification Path\n\n`directory_monitor.py` is responsible for directory-specific monitoring tied to active WebSocket subscriptions.\n\nIts job is to:\n\n- start watching a directory when the first browser subscriber appears\n- share one SMB monitor across multiple subscribers for the same watched path\n- stop monitoring when the last subscriber leaves\n- send `directory_changed` messages back through the WebSocket layer\n\nThis is the path that keeps an open file browser view fresh.\n\n### Directory-Cache Freshness Path\n\n`directory_cache.py` uses its own `CHANGE_NOTIFY` watcher for a different reason.\n\nIts job is to:\n\n- watch the share root or effective path prefix for directory-name changes\n- keep the in-memory directory cache aligned with adds, removes, and renames\n- combine event-driven updates with periodic full rescans as a safety net\n- preserve fast directory-search behavior without rebuilding the entire cache on every navigation event\n\nThis is not the same as the browser WebSocket monitor, even though both rely on SMB `CHANGE_NOTIFY`.\n\n## Browser Notification Flow\n\nAt a high level, the browser-facing flow is:\n\n1. the browser opens the backend WebSocket endpoint\n2. it sends a subscription message for a connection and directory path\n3. `ConnectionManager` resolves access, applies any `path_prefix`, and starts monitoring if this is the first subscriber\n4. `DirectoryMonitor` opens SMB resources for that resolved directory and starts a background watcher thread\n5. when the SMB server reports a change, the backend emits `directory_changed` to all subscribers for the user-facing path\n6. when the last subscriber leaves, the monitor stops and releases its SMB resources\n\nRepresentative client messages include:\n\n- subscribe: `{ \"action\": \"subscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- unsubscribe: `{ \"action\": \"unsubscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- server notification: `{ \"type\": \"directory_changed\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n\n## Path Resolution and Subscription Keys\n\nOne subtle but important part of the design is that browser subscriptions and SMB watches do not always use the same path string.\n\nThe WebSocket layer keys subscriptions by the user-facing path.\n\nIf the SMB connection has a `path_prefix`, the backend resolves the actual watched SMB path by combining:\n\n- the normalized connection prefix\n- the user-facing relative path\n\nThat resolved SMB path is what `DirectoryMonitor` actually watches.\n\nThe callback then maps notifications back to the user-facing path before sending `directory_changed` over the WebSocket.\n\nIf you remove that mapping, subscriptions stop lining up with the paths the browser thinks it subscribed to.\n\n## Main Components\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/api/websocket.py` | WebSocket endpoint, subscription bookkeeping, access checks, path-prefix resolution, and delivery of `directory_changed` events |\n| `backend/app/services/directory_monitor.py` | per-directory SMB watchers for active browser subscriptions |\n| `backend/app/services/directory_cache.py` | per-connection directory cache plus root-level `CHANGE_NOTIFY` watcher for cache freshness |\n| `backend/app/main.py` | application shutdown hooks for directory caches and directory monitors |\n\n## Directory Monitor Lifecycle\n\nThe browser-facing monitor is reference-counted by subscription demand.\n\n`DirectoryMonitor` keeps one `MonitoredDirectory` per `connection_id:path` key and tracks subscriber counts.\n\nThat means:\n\n- the first subscriber starts the monitor\n- later subscribers reuse the same watched directory instance\n- unsubscribing decrements the count\n- the monitor only stops when the count reaches zero\n\nThis avoids opening duplicate SMB watcher handles for the same directory just because multiple browser clients are watching it.\n\n## SMB Resource Management\n\n`MonitoredDirectory` owns low-level SMB resources directly.\n\nCreation follows this order:\n\n1. connection\n2. session\n3. tree connect\n4. directory open handle\n5. `FileSystemWatcher`\n\nCleanup happens in reverse order so partial failure does not leak handles.\n\nThat ordering is important because change-notification bugs are often really handle-lifecycle bugs.\n\n## Watched Events\n\nThe browser-facing monitor currently watches for:\n\n- file-name changes\n- directory-name changes\n- size changes\n- last-write changes\n\nIt uses tree watching so changes in subdirectories can also surface through the same watch.\n\nThe directory-cache watcher is narrower by design.\n\nIt watches directory-name changes across the tree because the cache only needs enough signal to update its directory index efficiently.\n\n## Recovery and Failure Handling\n\nThe directory monitor treats connection failures as part of normal long-lived operation, not as impossible edge cases.\n\nCurrent behavior includes:\n\n- exponential backoff for reconnect attempts\n- retry jitter to avoid synchronized reconnect storms\n- capped retry attempts before giving up\n- explicit detection of connection, socket, and timeout failures\n- stop-on-delete behavior when the watched directory itself is deleted\n\nThe cache watcher has its own retry loop and also tolerates `CHANGE_NOTIFY` buffer-overflow conditions by relying on later rescans to restore correctness.\n\nThat distinction matters: browser notification is path-specific and subscriber-driven, while the cache watcher is connection-scoped and consistency-oriented.\n\n## Shutdown Behavior\n\nSambee shuts these systems down explicitly.\n\nDuring application shutdown:\n\n- directory caches are stopped through `shutdown_directory_cache()`\n- directory monitors are stopped through `shutdown_monitor()`\n\nThat explicit shutdown path exists to release watcher threads and SMB handles cleanly instead of depending on interpreter teardown.\n\n## Performance Characteristics\n\nThe design tries to keep freshness inexpensive without resorting to constant polling.\n\n- SMB `CHANGE_NOTIFY` is event-driven rather than poll-based\n- multiple browser subscribers share one monitor for the same watched path\n- directory-cache updates avoid full rescans for every single directory rename or add event\n- periodic rescans remain in place as a correctness safety net, not the primary freshness mechanism\n\n## Limits and Tradeoffs\n\nContributors need to preserve a few constraints here.\n\n- this requires SMB2 or later\n- some notifications can still be missed during network instability, which is why manual refresh and periodic cache rescans still matter\n- the browser-facing path is optimized for telling clients to refresh, not for transmitting rich per-file diffs\n- cache freshness and browser freshness are related concerns, but they are not the same subsystem and should not be collapsed casually\n\n## Common Failure Modes\n\n- path-prefix resolution is ignored, so the monitor watches the wrong SMB directory\n- subscriber bookkeeping drifts, so monitors are leaked or stopped too early\n- WebSocket disconnect cleanup forgets to release the last subscriber's monitor\n- a recovery change handles one timeout path but leaks SMB resources on reconnect\n- buffer-overflow or rename-edge handling is simplified in ways that quietly degrade cache correctness\n\n## Where to Continue\n\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the changed behavior interacts with uploads, moves, renames, or companion-assisted editing.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider backend or browser validation.\n\n## Validation Expectations\n\nWhen you change SMB change-notification behavior, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects browser-visible refresh behavior, add the relevant frontend checks as well.\n", "0.9": "+++\ntitle = \"SMB Change Notification and Directory Freshness\"\n+++\n\nSambee uses SMB2/SMB3 `CHANGE_NOTIFY` support to keep directory state fresh without falling back to naive polling.\n\nThat capability is used in two different backend paths:\n\n- `backend/app/services/directory_monitor.py` for browser-visible WebSocket refresh notifications\n- `backend/app/services/directory_cache.py` for per-connection directory-cache freshness\n\nUse this page when a backend change affects WebSocket directory updates, SMB watcher lifecycle, or how the product maintains fresh directory state over time.\n\n## Why This Matters\n\nDirectory freshness is a cross-boundary product contract.\n\nUsers expect Sambee to react when:\n\n- another SMB client creates, deletes, renames, or edits content in the current directory\n- the current browser view should refresh because the underlying SMB directory changed\n- cached directory-search data should stay reasonably current without rescanning the entire tree on every request\n\nThat is why the backend owns change-notification behavior instead of leaving refresh decisions entirely to the browser.\n\n## The Two Change-Notification Paths\n\nSambee does not have a single watcher for all purposes.\n\n### Browser Notification Path\n\n`directory_monitor.py` is responsible for directory-specific monitoring tied to active WebSocket subscriptions.\n\nIts job is to:\n\n- start watching a directory when the first browser subscriber appears\n- share one SMB monitor across multiple subscribers for the same watched path\n- stop monitoring when the last subscriber leaves\n- send `directory_changed` messages back through the WebSocket layer\n\nThis is the path that keeps an open file browser view fresh.\n\n### Directory-Cache Freshness Path\n\n`directory_cache.py` uses its own `CHANGE_NOTIFY` watcher for a different reason.\n\nIts job is to:\n\n- watch the share root or effective path prefix for directory-name changes\n- keep the in-memory directory cache aligned with adds, removes, and renames\n- combine event-driven updates with periodic full rescans as a safety net\n- preserve fast directory-search behavior without rebuilding the entire cache on every navigation event\n\nThis is not the same as the browser WebSocket monitor, even though both rely on SMB `CHANGE_NOTIFY`.\n\n## Browser Notification Flow\n\nAt a high level, the browser-facing flow is:\n\n1. the browser opens the backend WebSocket endpoint\n2. it sends a subscription message for a connection and directory path\n3. `ConnectionManager` resolves access, applies any `path_prefix`, and starts monitoring if this is the first subscriber\n4. `DirectoryMonitor` opens SMB resources for that resolved directory and starts a background watcher thread\n5. when the SMB server reports a change, the backend emits `directory_changed` to all subscribers for the user-facing path\n6. when the last subscriber leaves, the monitor stops and releases its SMB resources\n\nRepresentative client messages include:\n\n- subscribe: `{ \"action\": \"subscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- unsubscribe: `{ \"action\": \"unsubscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- server notification: `{ \"type\": \"directory_changed\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n\n## Path Resolution and Subscription Keys\n\nOne subtle but important part of the design is that browser subscriptions and SMB watches do not always use the same path string.\n\nThe WebSocket layer keys subscriptions by the user-facing path.\n\nIf the SMB connection has a `path_prefix`, the backend resolves the actual watched SMB path by combining:\n\n- the normalized connection prefix\n- the user-facing relative path\n\nThat resolved SMB path is what `DirectoryMonitor` actually watches.\n\nThe callback then maps notifications back to the user-facing path before sending `directory_changed` over the WebSocket.\n\nIf you remove that mapping, subscriptions stop lining up with the paths the browser thinks it subscribed to.\n\n## Main Components\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/api/websocket.py` | WebSocket endpoint, subscription bookkeeping, access checks, path-prefix resolution, and delivery of `directory_changed` events |\n| `backend/app/services/directory_monitor.py` | per-directory SMB watchers for active browser subscriptions |\n| `backend/app/services/directory_cache.py` | per-connection directory cache plus root-level `CHANGE_NOTIFY` watcher for cache freshness |\n| `backend/app/main.py` | application shutdown hooks for directory caches and directory monitors |\n\n## Directory Monitor Lifecycle\n\nThe browser-facing monitor is reference-counted by subscription demand.\n\n`DirectoryMonitor` keeps one `MonitoredDirectory` per `connection_id:path` key and tracks subscriber counts.\n\nThat means:\n\n- the first subscriber starts the monitor\n- later subscribers reuse the same watched directory instance\n- unsubscribing decrements the count\n- the monitor only stops when the count reaches zero\n\nThis avoids opening duplicate SMB watcher handles for the same directory just because multiple browser clients are watching it.\n\n## SMB Resource Management\n\n`MonitoredDirectory` owns low-level SMB resources directly.\n\nCreation follows this order:\n\n1. connection\n2. session\n3. tree connect\n4. directory open handle\n5. `FileSystemWatcher`\n\nCleanup happens in reverse order so partial failure does not leak handles.\n\nThat ordering is important because change-notification bugs are often really handle-lifecycle bugs.\n\n## Watched Events\n\nThe browser-facing monitor currently watches for:\n\n- file-name changes\n- directory-name changes\n- size changes\n- last-write changes\n\nIt uses tree watching so changes in subdirectories can also surface through the same watch.\n\nThe directory-cache watcher is narrower by design.\n\nIt watches directory-name changes across the tree because the cache only needs enough signal to update its directory index efficiently.\n\n## Recovery and Failure Handling\n\nThe directory monitor treats connection failures as part of normal long-lived operation, not as impossible edge cases.\n\nCurrent behavior includes:\n\n- exponential backoff for reconnect attempts\n- retry jitter to avoid synchronized reconnect storms\n- capped retry attempts before giving up\n- explicit detection of connection, socket, and timeout failures\n- stop-on-delete behavior when the watched directory itself is deleted\n\nThe cache watcher has its own retry loop and also tolerates `CHANGE_NOTIFY` buffer-overflow conditions by relying on later rescans to restore correctness.\n\nThat distinction matters: browser notification is path-specific and subscriber-driven, while the cache watcher is connection-scoped and consistency-oriented.\n\n## Shutdown Behavior\n\nSambee shuts these systems down explicitly.\n\nDuring application shutdown:\n\n- directory caches are stopped through `shutdown_directory_cache()`\n- directory monitors are stopped through `shutdown_monitor()`\n\nThat explicit shutdown path exists to release watcher threads and SMB handles cleanly instead of depending on interpreter teardown.\n\n## Performance Characteristics\n\nThe design tries to keep freshness inexpensive without resorting to constant polling.\n\n- SMB `CHANGE_NOTIFY` is event-driven rather than poll-based\n- multiple browser subscribers share one monitor for the same watched path\n- directory-cache updates avoid full rescans for every single directory rename or add event\n- periodic rescans remain in place as a correctness safety net, not the primary freshness mechanism\n\n## Limits and Tradeoffs\n\nContributors need to preserve a few constraints here.\n\n- this requires SMB2 or later\n- some notifications can still be missed during network instability, which is why manual refresh and periodic cache rescans still matter\n- the browser-facing path is optimized for telling clients to refresh, not for transmitting rich per-file diffs\n- cache freshness and browser freshness are related concerns, but they are not the same subsystem and should not be collapsed casually\n\n## Common Failure Modes\n\n- path-prefix resolution is ignored, so the monitor watches the wrong SMB directory\n- subscriber bookkeeping drifts, so monitors are leaked or stopped too early\n- WebSocket disconnect cleanup forgets to release the last subscriber's monitor\n- a recovery change handles one timeout path but leaks SMB resources on reconnect\n- buffer-overflow or rename-edge handling is simplified in ways that quietly degrade cache correctness\n\n## Where to Continue\n\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the changed behavior interacts with uploads, moves, renames, or companion-assisted editing.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider backend or browser validation.\n\n## Validation Expectations\n\nWhen you change SMB change-notification behavior, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects browser-visible refresh behavior, add the relevant frontend checks as well.\n", "1.0": "+++\ntitle = \"SMB Change Notification and Directory Freshness\"\n+++\n\nSambee uses SMB2/SMB3 `CHANGE_NOTIFY` support to keep directory state fresh without falling back to naive polling.\n\nThat capability is used in two different backend paths:\n\n- `backend/app/services/directory_monitor.py` for browser-visible WebSocket refresh notifications\n- `backend/app/services/directory_cache.py` for per-connection directory-cache freshness\n\nUse this page when a backend change affects WebSocket directory updates, SMB watcher lifecycle, or how the product maintains fresh directory state over time.\n\n## Why This Matters\n\nDirectory freshness is a cross-boundary product contract.\n\nUsers expect Sambee to react when:\n\n- another SMB client creates, deletes, renames, or edits content in the current directory\n- the current browser view should refresh because the underlying SMB directory changed\n- cached directory-search data should stay reasonably current without rescanning the entire tree on every request\n\nThat is why the backend owns change-notification behavior instead of leaving refresh decisions entirely to the browser.\n\n## The Two Change-Notification Paths\n\nSambee does not have a single watcher for all purposes.\n\n### Browser Notification Path\n\n`directory_monitor.py` is responsible for directory-specific monitoring tied to active WebSocket subscriptions.\n\nIts job is to:\n\n- start watching a directory when the first browser subscriber appears\n- share one SMB monitor across multiple subscribers for the same watched path\n- stop monitoring when the last subscriber leaves\n- send `directory_changed` messages back through the WebSocket layer\n\nThis is the path that keeps an open file browser view fresh.\n\n### Directory-Cache Freshness Path\n\n`directory_cache.py` uses its own `CHANGE_NOTIFY` watcher for a different reason.\n\nIts job is to:\n\n- watch the share root or effective path prefix for directory-name changes\n- keep the in-memory directory cache aligned with adds, removes, and renames\n- combine event-driven updates with periodic full rescans as a safety net\n- preserve fast directory-search behavior without rebuilding the entire cache on every navigation event\n\nThis is not the same as the browser WebSocket monitor, even though both rely on SMB `CHANGE_NOTIFY`.\n\n## Browser Notification Flow\n\nAt a high level, the browser-facing flow is:\n\n1. the browser opens the backend WebSocket endpoint\n2. it sends a subscription message for a connection and directory path\n3. `ConnectionManager` resolves access, applies any `path_prefix`, and starts monitoring if this is the first subscriber\n4. `DirectoryMonitor` opens SMB resources for that resolved directory and starts a background watcher thread\n5. when the SMB server reports a change, the backend emits `directory_changed` to all subscribers for the user-facing path\n6. when the last subscriber leaves, the monitor stops and releases its SMB resources\n\nRepresentative client messages include:\n\n- subscribe: `{ \"action\": \"subscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- unsubscribe: `{ \"action\": \"unsubscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- server notification: `{ \"type\": \"directory_changed\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n\n## Path Resolution and Subscription Keys\n\nOne subtle but important part of the design is that browser subscriptions and SMB watches do not always use the same path string.\n\nThe WebSocket layer keys subscriptions by the user-facing path.\n\nIf the SMB connection has a `path_prefix`, the backend resolves the actual watched SMB path by combining:\n\n- the normalized connection prefix\n- the user-facing relative path\n\nThat resolved SMB path is what `DirectoryMonitor` actually watches.\n\nThe callback then maps notifications back to the user-facing path before sending `directory_changed` over the WebSocket.\n\nIf you remove that mapping, subscriptions stop lining up with the paths the browser thinks it subscribed to.\n\n## Main Components\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/api/websocket.py` | WebSocket endpoint, subscription bookkeeping, access checks, path-prefix resolution, and delivery of `directory_changed` events |\n| `backend/app/services/directory_monitor.py` | per-directory SMB watchers for active browser subscriptions |\n| `backend/app/services/directory_cache.py` | per-connection directory cache plus root-level `CHANGE_NOTIFY` watcher for cache freshness |\n| `backend/app/main.py` | application shutdown hooks for directory caches and directory monitors |\n\n## Directory Monitor Lifecycle\n\nThe browser-facing monitor is reference-counted by subscription demand.\n\n`DirectoryMonitor` keeps one `MonitoredDirectory` per `connection_id:path` key and tracks subscriber counts.\n\nThat means:\n\n- the first subscriber starts the monitor\n- later subscribers reuse the same watched directory instance\n- unsubscribing decrements the count\n- the monitor only stops when the count reaches zero\n\nThis avoids opening duplicate SMB watcher handles for the same directory just because multiple browser clients are watching it.\n\n## SMB Resource Management\n\n`MonitoredDirectory` owns low-level SMB resources directly.\n\nCreation follows this order:\n\n1. connection\n2. session\n3. tree connect\n4. directory open handle\n5. `FileSystemWatcher`\n\nCleanup happens in reverse order so partial failure does not leak handles.\n\nThat ordering is important because change-notification bugs are often really handle-lifecycle bugs.\n\n## Watched Events\n\nThe browser-facing monitor currently watches for:\n\n- file-name changes\n- directory-name changes\n- size changes\n- last-write changes\n\nIt uses tree watching so changes in subdirectories can also surface through the same watch.\n\nThe directory-cache watcher is narrower by design.\n\nIt watches directory-name changes across the tree because the cache only needs enough signal to update its directory index efficiently.\n\n## Recovery and Failure Handling\n\nThe directory monitor treats connection failures as part of normal long-lived operation, not as impossible edge cases.\n\nCurrent behavior includes:\n\n- exponential backoff for reconnect attempts\n- retry jitter to avoid synchronized reconnect storms\n- capped retry attempts before giving up\n- explicit detection of connection, socket, and timeout failures\n- stop-on-delete behavior when the watched directory itself is deleted\n\nThe cache watcher has its own retry loop and also tolerates `CHANGE_NOTIFY` buffer-overflow conditions by relying on later rescans to restore correctness.\n\nThat distinction matters: browser notification is path-specific and subscriber-driven, while the cache watcher is connection-scoped and consistency-oriented.\n\n## Shutdown Behavior\n\nSambee shuts these systems down explicitly.\n\nDuring application shutdown:\n\n- directory caches are stopped through `shutdown_directory_cache()`\n- directory monitors are stopped through `shutdown_monitor()`\n\nThat explicit shutdown path exists to release watcher threads and SMB handles cleanly instead of depending on interpreter teardown.\n\n## Performance Characteristics\n\nThe design tries to keep freshness inexpensive without resorting to constant polling.\n\n- SMB `CHANGE_NOTIFY` is event-driven rather than poll-based\n- multiple browser subscribers share one monitor for the same watched path\n- directory-cache updates avoid full rescans for every single directory rename or add event\n- periodic rescans remain in place as a correctness safety net, not the primary freshness mechanism\n\n## Limits and Tradeoffs\n\nContributors need to preserve a few constraints here.\n\n- this requires SMB2 or later\n- some notifications can still be missed during network instability, which is why manual refresh and periodic cache rescans still matter\n- the browser-facing path is optimized for telling clients to refresh, not for transmitting rich per-file diffs\n- cache freshness and browser freshness are related concerns, but they are not the same subsystem and should not be collapsed casually\n\n## Common Failure Modes\n\n- path-prefix resolution is ignored, so the monitor watches the wrong SMB directory\n- subscriber bookkeeping drifts, so monitors are leaked or stopped too early\n- WebSocket disconnect cleanup forgets to release the last subscriber's monitor\n- a recovery change handles one timeout path but leaks SMB resources on reconnect\n- buffer-overflow or rename-edge handling is simplified in ways that quietly degrade cache correctness\n\n## Where to Continue\n\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the changed behavior interacts with uploads, moves, renames, or companion-assisted editing.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider backend or browser validation.\n\n## Validation Expectations\n\nWhen you change SMB change-notification behavior, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects browser-visible refresh behavior, add the relevant frontend checks as well.\n", "2.0": "+++\ntitle = \"SMB Change Notification and Directory Freshness\"\n+++\n\nSambee uses SMB2/SMB3 `CHANGE_NOTIFY` support to keep directory state fresh without falling back to naive polling.\n\nThat capability is used in two different backend paths:\n\n- `backend/app/services/directory_monitor.py` for browser-visible WebSocket refresh notifications\n- `backend/app/services/directory_cache.py` for per-connection directory-cache freshness\n\nUse this page when a backend change affects WebSocket directory updates, SMB watcher lifecycle, or how the product maintains fresh directory state over time.\n\n## Why This Matters\n\nDirectory freshness is a cross-boundary product contract.\n\nUsers expect Sambee to react when:\n\n- another SMB client creates, deletes, renames, or edits content in the current directory\n- the current browser view should refresh because the underlying SMB directory changed\n- cached directory-search data should stay reasonably current without rescanning the entire tree on every request\n\nThat is why the backend owns change-notification behavior instead of leaving refresh decisions entirely to the browser.\n\n## The Two Change-Notification Paths\n\nSambee does not have a single watcher for all purposes.\n\n### Browser Notification Path\n\n`directory_monitor.py` is responsible for directory-specific monitoring tied to active WebSocket subscriptions.\n\nIts job is to:\n\n- start watching a directory when the first browser subscriber appears\n- share one SMB monitor across multiple subscribers for the same watched path\n- stop monitoring when the last subscriber leaves\n- send `directory_changed` messages back through the WebSocket layer\n\nThis is the path that keeps an open file browser view fresh.\n\n### Directory-Cache Freshness Path\n\n`directory_cache.py` uses its own `CHANGE_NOTIFY` watcher for a different reason.\n\nIts job is to:\n\n- watch the share root or effective path prefix for directory-name changes\n- keep the in-memory directory cache aligned with adds, removes, and renames\n- combine event-driven updates with periodic full rescans as a safety net\n- preserve fast directory-search behavior without rebuilding the entire cache on every navigation event\n\nThis is not the same as the browser WebSocket monitor, even though both rely on SMB `CHANGE_NOTIFY`.\n\n## Browser Notification Flow\n\nAt a high level, the browser-facing flow is:\n\n1. the browser opens the backend WebSocket endpoint\n2. it sends a subscription message for a connection and directory path\n3. `ConnectionManager` resolves access, applies any `path_prefix`, and starts monitoring if this is the first subscriber\n4. `DirectoryMonitor` opens SMB resources for that resolved directory and starts a background watcher thread\n5. when the SMB server reports a change, the backend emits `directory_changed` to all subscribers for the user-facing path\n6. when the last subscriber leaves, the monitor stops and releases its SMB resources\n\nRepresentative client messages include:\n\n- subscribe: `{ \"action\": \"subscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- unsubscribe: `{ \"action\": \"unsubscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- server notification: `{ \"type\": \"directory_changed\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n\n## Path Resolution and Subscription Keys\n\nOne subtle but important part of the design is that browser subscriptions and SMB watches do not always use the same path string.\n\nThe WebSocket layer keys subscriptions by the user-facing path.\n\nIf the SMB connection has a `path_prefix`, the backend resolves the actual watched SMB path by combining:\n\n- the normalized connection prefix\n- the user-facing relative path\n\nThat resolved SMB path is what `DirectoryMonitor` actually watches.\n\nThe callback then maps notifications back to the user-facing path before sending `directory_changed` over the WebSocket.\n\nIf you remove that mapping, subscriptions stop lining up with the paths the browser thinks it subscribed to.\n\n## Main Components\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/api/websocket.py` | WebSocket endpoint, subscription bookkeeping, access checks, path-prefix resolution, and delivery of `directory_changed` events |\n| `backend/app/services/directory_monitor.py` | per-directory SMB watchers for active browser subscriptions |\n| `backend/app/services/directory_cache.py` | per-connection directory cache plus root-level `CHANGE_NOTIFY` watcher for cache freshness |\n| `backend/app/main.py` | application shutdown hooks for directory caches and directory monitors |\n\n## Directory Monitor Lifecycle\n\nThe browser-facing monitor is reference-counted by subscription demand.\n\n`DirectoryMonitor` keeps one `MonitoredDirectory` per `connection_id:path` key and tracks subscriber counts.\n\nThat means:\n\n- the first subscriber starts the monitor\n- later subscribers reuse the same watched directory instance\n- unsubscribing decrements the count\n- the monitor only stops when the count reaches zero\n\nThis avoids opening duplicate SMB watcher handles for the same directory just because multiple browser clients are watching it.\n\n## SMB Resource Management\n\n`MonitoredDirectory` owns low-level SMB resources directly.\n\nCreation follows this order:\n\n1. connection\n2. session\n3. tree connect\n4. directory open handle\n5. `FileSystemWatcher`\n\nCleanup happens in reverse order so partial failure does not leak handles.\n\nThat ordering is important because change-notification bugs are often really handle-lifecycle bugs.\n\n## Watched Events\n\nThe browser-facing monitor currently watches for:\n\n- file-name changes\n- directory-name changes\n- size changes\n- last-write changes\n\nThe browser-facing monitor watches only immediate children of the subscribed directory. Writes deeper in the tree, such as installing packages in a project's `node_modules` folder, don't invalidate an ancestor's file list. If the SMB server reports a metadata change for an immediate child directory, that change can still trigger a refresh.\n\nThe directory-cache watcher is narrower by design.\n\nIt watches directory-name changes across the tree because the cache only needs enough signal to update its directory index efficiently.\n\n## Directory-Index Consistency\n\nA full rescan builds a replacement index while the current index continues to serve directory searches. If any directory read fails or times out, the replacement isn't published or persisted. The existing index remains available, and the scan error is recorded for diagnosis. A later successful rescan can replace it.\n\nWhile a rescan is running, directory additions, removals, and renames update the live index and are also recorded in order. Under the cache lock, Sambee checks pending operations before and after each directory read and before publication. Additions are safe to merge. Removals and renames can only be merged when they don't overlap a read that's already started.\n\nIf a removal or rename changes a directory that's already been read, one being read, an ancestor of either, or an immediate child's name, the replacement is ambiguous. Notifications can arrive after a read already reflects the change, so replaying them could rename or remove fresh paths a second time. Sambee discards the replacement rather than publishing or persisting it; the live index, including its recent changes, remains available. Only one rescan can run at a time, and cancellation discards pending reconciliation without discarding live updates.\n\nDirectory junctions, symbolic links, and unrecognized directory reparse points are indexed as destinations, but scans don't descend into their targets. This prevents ancestor links from causing repeated traversal. DFS referrals are identified by their reparse tag and remain traversable through the SMB client's referral support, so directories below DFS links stay searchable.\n\n### Persisted Snapshots\n\nVersion 2 snapshots are bound to the connection's host, port, share, normalized path prefix, username, and connection revision. The revision changes when the connection is edited, including credential changes. Passwords aren't stored in snapshot metadata.\n\nA snapshot with a different source identity is ignored, including when trying the backup file. Older version 1 snapshots are also ignored, so existing installations rebuild the directory index once after upgrading. Matching snapshots still provide immediate search results while background verification checks freshness.\n\nStartup verification and the periodic rescan loop have separate tracked tasks. Removing a cache or shutting down the application cancels both tasks, along with initial scanning and snapshot flushing.\n\n## Recovery and Failure Handling\n\nThe directory monitor treats connection failures as part of normal long-lived operation, not as impossible edge cases.\n\nCurrent behavior includes:\n\n- exponential backoff for reconnect attempts\n- retry jitter to avoid synchronized reconnect storms\n- capped retry attempts before giving up\n- explicit detection of connection, socket, and timeout failures\n- stop-on-delete behavior when the watched directory itself is deleted\n\nThe cache watcher has its own retry loop and also tolerates `CHANGE_NOTIFY` buffer-overflow conditions by relying on later rescans to restore correctness.\n\nThat distinction matters: browser notification is path-specific and subscriber-driven, while the cache watcher is connection-scoped and consistency-oriented.\n\n## Shutdown Behavior\n\nSambee shuts these systems down explicitly.\n\nDuring application shutdown:\n\n- directory caches are stopped through `shutdown_directory_cache()`\n- directory monitors are stopped through `shutdown_monitor()`\n\nThat explicit shutdown path exists to release watcher threads and SMB handles cleanly instead of depending on interpreter teardown.\n\n## Performance Characteristics\n\nThe design tries to keep freshness inexpensive without resorting to constant polling.\n\n- SMB `CHANGE_NOTIFY` is event-driven rather than poll-based\n- multiple browser subscribers share one monitor for the same watched path\n- browser-facing monitors don't request recursive subtree notifications\n- each browser pane keeps loaded physical-directory rows visible during automatic refreshes, including a previously loaded empty listing\n- automatic refreshes wait for an active listing request and combine newer notifications into one pending refresh, starting at most once per second\n- navigation and pane disposal cancel queued refreshes\n- directory-cache updates avoid full rescans for every single directory rename or add event\n- periodic rescans remain in place as a correctness safety net, not the primary freshness mechanism\n\n## Limits and Tradeoffs\n\nContributors need to preserve a few constraints here.\n\n- this requires SMB2 or later\n- some notifications can still be missed during network instability, which is why manual refresh and periodic cache rescans still matter\n- the browser-facing path is optimized for telling clients to refresh, not for transmitting rich per-file diffs\n- cache freshness and browser freshness are related concerns, but they are not the same subsystem and should not be collapsed casually\n\n## Common Failure Modes\n\n- path-prefix resolution is ignored, so the monitor watches the wrong SMB directory\n- subscriber bookkeeping drifts, so monitors are leaked or stopped too early\n- WebSocket disconnect cleanup forgets to release the last subscriber's monitor\n- a recovery change handles one timeout path but leaks SMB resources on reconnect\n- buffer-overflow or rename-edge handling is simplified in ways that quietly degrade cache correctness\n\n## Where to Continue\n\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the changed behavior interacts with uploads, moves, renames, or companion-assisted editing.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider backend or browser validation.\n\n## Validation Expectations\n\nWhen you change SMB change-notification behavior, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects browser-visible refresh behavior, add the relevant frontend checks as well.\n"}, "page_contents": {"0.7": "+++\ntitle = \"SMB Change Notification and Directory Freshness\"\n+++\n\nSambee uses SMB2/SMB3 `CHANGE_NOTIFY` support to keep directory state fresh without falling back to naive polling.\n\nThat capability is used in two different backend paths:\n\n- `backend/app/services/directory_monitor.py` for browser-visible WebSocket refresh notifications\n- `backend/app/services/directory_cache.py` for per-connection directory-cache freshness\n\nUse this page when a backend change affects WebSocket directory updates, SMB watcher lifecycle, or how the product maintains fresh directory state over time.\n\n## Why This Matters\n\nDirectory freshness is a cross-boundary product contract.\n\nUsers expect Sambee to react when:\n\n- another SMB client creates, deletes, renames, or edits content in the current directory\n- the current browser view should refresh because the underlying SMB directory changed\n- cached directory-search data should stay reasonably current without rescanning the entire tree on every request\n\nThat is why the backend owns change-notification behavior instead of leaving refresh decisions entirely to the browser.\n\n## The Two Change-Notification Paths\n\nSambee does not have a single watcher for all purposes.\n\n### Browser Notification Path\n\n`directory_monitor.py` is responsible for directory-specific monitoring tied to active WebSocket subscriptions.\n\nIts job is to:\n\n- start watching a directory when the first browser subscriber appears\n- share one SMB monitor across multiple subscribers for the same watched path\n- stop monitoring when the last subscriber leaves\n- send `directory_changed` messages back through the WebSocket layer\n\nThis is the path that keeps an open file browser view fresh.\n\n### Directory-Cache Freshness Path\n\n`directory_cache.py` uses its own `CHANGE_NOTIFY` watcher for a different reason.\n\nIts job is to:\n\n- watch the share root or effective path prefix for directory-name changes\n- keep the in-memory directory cache aligned with adds, removes, and renames\n- combine event-driven updates with periodic full rescans as a safety net\n- preserve fast directory-search behavior without rebuilding the entire cache on every navigation event\n\nThis is not the same as the browser WebSocket monitor, even though both rely on SMB `CHANGE_NOTIFY`.\n\n## Browser Notification Flow\n\nAt a high level, the browser-facing flow is:\n\n1. the browser opens the backend WebSocket endpoint\n2. it sends a subscription message for a connection and directory path\n3. `ConnectionManager` resolves access, applies any `path_prefix`, and starts monitoring if this is the first subscriber\n4. `DirectoryMonitor` opens SMB resources for that resolved directory and starts a background watcher thread\n5. when the SMB server reports a change, the backend emits `directory_changed` to all subscribers for the user-facing path\n6. when the last subscriber leaves, the monitor stops and releases its SMB resources\n\nRepresentative client messages include:\n\n- subscribe: `{ \"action\": \"subscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- unsubscribe: `{ \"action\": \"unsubscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- server notification: `{ \"type\": \"directory_changed\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n\n## Path Resolution and Subscription Keys\n\nOne subtle but important part of the design is that browser subscriptions and SMB watches do not always use the same path string.\n\nThe WebSocket layer keys subscriptions by the user-facing path.\n\nIf the SMB connection has a `path_prefix`, the backend resolves the actual watched SMB path by combining:\n\n- the normalized connection prefix\n- the user-facing relative path\n\nThat resolved SMB path is what `DirectoryMonitor` actually watches.\n\nThe callback then maps notifications back to the user-facing path before sending `directory_changed` over the WebSocket.\n\nIf you remove that mapping, subscriptions stop lining up with the paths the browser thinks it subscribed to.\n\n## Main Components\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/api/websocket.py` | WebSocket endpoint, subscription bookkeeping, access checks, path-prefix resolution, and delivery of `directory_changed` events |\n| `backend/app/services/directory_monitor.py` | per-directory SMB watchers for active browser subscriptions |\n| `backend/app/services/directory_cache.py` | per-connection directory cache plus root-level `CHANGE_NOTIFY` watcher for cache freshness |\n| `backend/app/main.py` | application shutdown hooks for directory caches and directory monitors |\n\n## Directory Monitor Lifecycle\n\nThe browser-facing monitor is reference-counted by subscription demand.\n\n`DirectoryMonitor` keeps one `MonitoredDirectory` per `connection_id:path` key and tracks subscriber counts.\n\nThat means:\n\n- the first subscriber starts the monitor\n- later subscribers reuse the same watched directory instance\n- unsubscribing decrements the count\n- the monitor only stops when the count reaches zero\n\nThis avoids opening duplicate SMB watcher handles for the same directory just because multiple browser clients are watching it.\n\n## SMB Resource Management\n\n`MonitoredDirectory` owns low-level SMB resources directly.\n\nCreation follows this order:\n\n1. connection\n2. session\n3. tree connect\n4. directory open handle\n5. `FileSystemWatcher`\n\nCleanup happens in reverse order so partial failure does not leak handles.\n\nThat ordering is important because change-notification bugs are often really handle-lifecycle bugs.\n\n## Watched Events\n\nThe browser-facing monitor currently watches for:\n\n- file-name changes\n- directory-name changes\n- size changes\n- last-write changes\n\nIt uses tree watching so changes in subdirectories can also surface through the same watch.\n\nThe directory-cache watcher is narrower by design.\n\nIt watches directory-name changes across the tree because the cache only needs enough signal to update its directory index efficiently.\n\n## Recovery and Failure Handling\n\nThe directory monitor treats connection failures as part of normal long-lived operation, not as impossible edge cases.\n\nCurrent behavior includes:\n\n- exponential backoff for reconnect attempts\n- retry jitter to avoid synchronized reconnect storms\n- capped retry attempts before giving up\n- explicit detection of connection, socket, and timeout failures\n- stop-on-delete behavior when the watched directory itself is deleted\n\nThe cache watcher has its own retry loop and also tolerates `CHANGE_NOTIFY` buffer-overflow conditions by relying on later rescans to restore correctness.\n\nThat distinction matters: browser notification is path-specific and subscriber-driven, while the cache watcher is connection-scoped and consistency-oriented.\n\n## Shutdown Behavior\n\nSambee shuts these systems down explicitly.\n\nDuring application shutdown:\n\n- directory caches are stopped through `shutdown_directory_cache()`\n- directory monitors are stopped through `shutdown_monitor()`\n\nThat explicit shutdown path exists to release watcher threads and SMB handles cleanly instead of depending on interpreter teardown.\n\n## Performance Characteristics\n\nThe design tries to keep freshness inexpensive without resorting to constant polling.\n\n- SMB `CHANGE_NOTIFY` is event-driven rather than poll-based\n- multiple browser subscribers share one monitor for the same watched path\n- directory-cache updates avoid full rescans for every single directory rename or add event\n- periodic rescans remain in place as a correctness safety net, not the primary freshness mechanism\n\n## Limits and Tradeoffs\n\nContributors need to preserve a few constraints here.\n\n- this requires SMB2 or later\n- some notifications can still be missed during network instability, which is why manual refresh and periodic cache rescans still matter\n- the browser-facing path is optimized for telling clients to refresh, not for transmitting rich per-file diffs\n- cache freshness and browser freshness are related concerns, but they are not the same subsystem and should not be collapsed casually\n\n## Common Failure Modes\n\n- path-prefix resolution is ignored, so the monitor watches the wrong SMB directory\n- subscriber bookkeeping drifts, so monitors are leaked or stopped too early\n- WebSocket disconnect cleanup forgets to release the last subscriber's monitor\n- a recovery change handles one timeout path but leaks SMB resources on reconnect\n- buffer-overflow or rename-edge handling is simplified in ways that quietly degrade cache correctness\n\n## Where to Continue\n\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the changed behavior interacts with uploads, moves, renames, or companion-assisted editing.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider backend or browser validation.\n\n## Validation Expectations\n\nWhen you change SMB change-notification behavior, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects browser-visible refresh behavior, add the relevant frontend checks as well.\n", "0.8": "+++\ntitle = \"SMB Change Notification and Directory Freshness\"\n+++\n\nSambee uses SMB2/SMB3 `CHANGE_NOTIFY` support to keep directory state fresh without falling back to naive polling.\n\nThat capability is used in two different backend paths:\n\n- `backend/app/services/directory_monitor.py` for browser-visible WebSocket refresh notifications\n- `backend/app/services/directory_cache.py` for per-connection directory-cache freshness\n\nUse this page when a backend change affects WebSocket directory updates, SMB watcher lifecycle, or how the product maintains fresh directory state over time.\n\n## Why This Matters\n\nDirectory freshness is a cross-boundary product contract.\n\nUsers expect Sambee to react when:\n\n- another SMB client creates, deletes, renames, or edits content in the current directory\n- the current browser view should refresh because the underlying SMB directory changed\n- cached directory-search data should stay reasonably current without rescanning the entire tree on every request\n\nThat is why the backend owns change-notification behavior instead of leaving refresh decisions entirely to the browser.\n\n## The Two Change-Notification Paths\n\nSambee does not have a single watcher for all purposes.\n\n### Browser Notification Path\n\n`directory_monitor.py` is responsible for directory-specific monitoring tied to active WebSocket subscriptions.\n\nIts job is to:\n\n- start watching a directory when the first browser subscriber appears\n- share one SMB monitor across multiple subscribers for the same watched path\n- stop monitoring when the last subscriber leaves\n- send `directory_changed` messages back through the WebSocket layer\n\nThis is the path that keeps an open file browser view fresh.\n\n### Directory-Cache Freshness Path\n\n`directory_cache.py` uses its own `CHANGE_NOTIFY` watcher for a different reason.\n\nIts job is to:\n\n- watch the share root or effective path prefix for directory-name changes\n- keep the in-memory directory cache aligned with adds, removes, and renames\n- combine event-driven updates with periodic full rescans as a safety net\n- preserve fast directory-search behavior without rebuilding the entire cache on every navigation event\n\nThis is not the same as the browser WebSocket monitor, even though both rely on SMB `CHANGE_NOTIFY`.\n\n## Browser Notification Flow\n\nAt a high level, the browser-facing flow is:\n\n1. the browser opens the backend WebSocket endpoint\n2. it sends a subscription message for a connection and directory path\n3. `ConnectionManager` resolves access, applies any `path_prefix`, and starts monitoring if this is the first subscriber\n4. `DirectoryMonitor` opens SMB resources for that resolved directory and starts a background watcher thread\n5. when the SMB server reports a change, the backend emits `directory_changed` to all subscribers for the user-facing path\n6. when the last subscriber leaves, the monitor stops and releases its SMB resources\n\nRepresentative client messages include:\n\n- subscribe: `{ \"action\": \"subscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- unsubscribe: `{ \"action\": \"unsubscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- server notification: `{ \"type\": \"directory_changed\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n\n## Path Resolution and Subscription Keys\n\nOne subtle but important part of the design is that browser subscriptions and SMB watches do not always use the same path string.\n\nThe WebSocket layer keys subscriptions by the user-facing path.\n\nIf the SMB connection has a `path_prefix`, the backend resolves the actual watched SMB path by combining:\n\n- the normalized connection prefix\n- the user-facing relative path\n\nThat resolved SMB path is what `DirectoryMonitor` actually watches.\n\nThe callback then maps notifications back to the user-facing path before sending `directory_changed` over the WebSocket.\n\nIf you remove that mapping, subscriptions stop lining up with the paths the browser thinks it subscribed to.\n\n## Main Components\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/api/websocket.py` | WebSocket endpoint, subscription bookkeeping, access checks, path-prefix resolution, and delivery of `directory_changed` events |\n| `backend/app/services/directory_monitor.py` | per-directory SMB watchers for active browser subscriptions |\n| `backend/app/services/directory_cache.py` | per-connection directory cache plus root-level `CHANGE_NOTIFY` watcher for cache freshness |\n| `backend/app/main.py` | application shutdown hooks for directory caches and directory monitors |\n\n## Directory Monitor Lifecycle\n\nThe browser-facing monitor is reference-counted by subscription demand.\n\n`DirectoryMonitor` keeps one `MonitoredDirectory` per `connection_id:path` key and tracks subscriber counts.\n\nThat means:\n\n- the first subscriber starts the monitor\n- later subscribers reuse the same watched directory instance\n- unsubscribing decrements the count\n- the monitor only stops when the count reaches zero\n\nThis avoids opening duplicate SMB watcher handles for the same directory just because multiple browser clients are watching it.\n\n## SMB Resource Management\n\n`MonitoredDirectory` owns low-level SMB resources directly.\n\nCreation follows this order:\n\n1. connection\n2. session\n3. tree connect\n4. directory open handle\n5. `FileSystemWatcher`\n\nCleanup happens in reverse order so partial failure does not leak handles.\n\nThat ordering is important because change-notification bugs are often really handle-lifecycle bugs.\n\n## Watched Events\n\nThe browser-facing monitor currently watches for:\n\n- file-name changes\n- directory-name changes\n- size changes\n- last-write changes\n\nIt uses tree watching so changes in subdirectories can also surface through the same watch.\n\nThe directory-cache watcher is narrower by design.\n\nIt watches directory-name changes across the tree because the cache only needs enough signal to update its directory index efficiently.\n\n## Recovery and Failure Handling\n\nThe directory monitor treats connection failures as part of normal long-lived operation, not as impossible edge cases.\n\nCurrent behavior includes:\n\n- exponential backoff for reconnect attempts\n- retry jitter to avoid synchronized reconnect storms\n- capped retry attempts before giving up\n- explicit detection of connection, socket, and timeout failures\n- stop-on-delete behavior when the watched directory itself is deleted\n\nThe cache watcher has its own retry loop and also tolerates `CHANGE_NOTIFY` buffer-overflow conditions by relying on later rescans to restore correctness.\n\nThat distinction matters: browser notification is path-specific and subscriber-driven, while the cache watcher is connection-scoped and consistency-oriented.\n\n## Shutdown Behavior\n\nSambee shuts these systems down explicitly.\n\nDuring application shutdown:\n\n- directory caches are stopped through `shutdown_directory_cache()`\n- directory monitors are stopped through `shutdown_monitor()`\n\nThat explicit shutdown path exists to release watcher threads and SMB handles cleanly instead of depending on interpreter teardown.\n\n## Performance Characteristics\n\nThe design tries to keep freshness inexpensive without resorting to constant polling.\n\n- SMB `CHANGE_NOTIFY` is event-driven rather than poll-based\n- multiple browser subscribers share one monitor for the same watched path\n- directory-cache updates avoid full rescans for every single directory rename or add event\n- periodic rescans remain in place as a correctness safety net, not the primary freshness mechanism\n\n## Limits and Tradeoffs\n\nContributors need to preserve a few constraints here.\n\n- this requires SMB2 or later\n- some notifications can still be missed during network instability, which is why manual refresh and periodic cache rescans still matter\n- the browser-facing path is optimized for telling clients to refresh, not for transmitting rich per-file diffs\n- cache freshness and browser freshness are related concerns, but they are not the same subsystem and should not be collapsed casually\n\n## Common Failure Modes\n\n- path-prefix resolution is ignored, so the monitor watches the wrong SMB directory\n- subscriber bookkeeping drifts, so monitors are leaked or stopped too early\n- WebSocket disconnect cleanup forgets to release the last subscriber's monitor\n- a recovery change handles one timeout path but leaks SMB resources on reconnect\n- buffer-overflow or rename-edge handling is simplified in ways that quietly degrade cache correctness\n\n## Where to Continue\n\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the changed behavior interacts with uploads, moves, renames, or companion-assisted editing.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider backend or browser validation.\n\n## Validation Expectations\n\nWhen you change SMB change-notification behavior, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects browser-visible refresh behavior, add the relevant frontend checks as well.\n", "0.9": "+++\ntitle = \"SMB Change Notification and Directory Freshness\"\n+++\n\nSambee uses SMB2/SMB3 `CHANGE_NOTIFY` support to keep directory state fresh without falling back to naive polling.\n\nThat capability is used in two different backend paths:\n\n- `backend/app/services/directory_monitor.py` for browser-visible WebSocket refresh notifications\n- `backend/app/services/directory_cache.py` for per-connection directory-cache freshness\n\nUse this page when a backend change affects WebSocket directory updates, SMB watcher lifecycle, or how the product maintains fresh directory state over time.\n\n## Why This Matters\n\nDirectory freshness is a cross-boundary product contract.\n\nUsers expect Sambee to react when:\n\n- another SMB client creates, deletes, renames, or edits content in the current directory\n- the current browser view should refresh because the underlying SMB directory changed\n- cached directory-search data should stay reasonably current without rescanning the entire tree on every request\n\nThat is why the backend owns change-notification behavior instead of leaving refresh decisions entirely to the browser.\n\n## The Two Change-Notification Paths\n\nSambee does not have a single watcher for all purposes.\n\n### Browser Notification Path\n\n`directory_monitor.py` is responsible for directory-specific monitoring tied to active WebSocket subscriptions.\n\nIts job is to:\n\n- start watching a directory when the first browser subscriber appears\n- share one SMB monitor across multiple subscribers for the same watched path\n- stop monitoring when the last subscriber leaves\n- send `directory_changed` messages back through the WebSocket layer\n\nThis is the path that keeps an open file browser view fresh.\n\n### Directory-Cache Freshness Path\n\n`directory_cache.py` uses its own `CHANGE_NOTIFY` watcher for a different reason.\n\nIts job is to:\n\n- watch the share root or effective path prefix for directory-name changes\n- keep the in-memory directory cache aligned with adds, removes, and renames\n- combine event-driven updates with periodic full rescans as a safety net\n- preserve fast directory-search behavior without rebuilding the entire cache on every navigation event\n\nThis is not the same as the browser WebSocket monitor, even though both rely on SMB `CHANGE_NOTIFY`.\n\n## Browser Notification Flow\n\nAt a high level, the browser-facing flow is:\n\n1. the browser opens the backend WebSocket endpoint\n2. it sends a subscription message for a connection and directory path\n3. `ConnectionManager` resolves access, applies any `path_prefix`, and starts monitoring if this is the first subscriber\n4. `DirectoryMonitor` opens SMB resources for that resolved directory and starts a background watcher thread\n5. when the SMB server reports a change, the backend emits `directory_changed` to all subscribers for the user-facing path\n6. when the last subscriber leaves, the monitor stops and releases its SMB resources\n\nRepresentative client messages include:\n\n- subscribe: `{ \"action\": \"subscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- unsubscribe: `{ \"action\": \"unsubscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- server notification: `{ \"type\": \"directory_changed\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n\n## Path Resolution and Subscription Keys\n\nOne subtle but important part of the design is that browser subscriptions and SMB watches do not always use the same path string.\n\nThe WebSocket layer keys subscriptions by the user-facing path.\n\nIf the SMB connection has a `path_prefix`, the backend resolves the actual watched SMB path by combining:\n\n- the normalized connection prefix\n- the user-facing relative path\n\nThat resolved SMB path is what `DirectoryMonitor` actually watches.\n\nThe callback then maps notifications back to the user-facing path before sending `directory_changed` over the WebSocket.\n\nIf you remove that mapping, subscriptions stop lining up with the paths the browser thinks it subscribed to.\n\n## Main Components\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/api/websocket.py` | WebSocket endpoint, subscription bookkeeping, access checks, path-prefix resolution, and delivery of `directory_changed` events |\n| `backend/app/services/directory_monitor.py` | per-directory SMB watchers for active browser subscriptions |\n| `backend/app/services/directory_cache.py` | per-connection directory cache plus root-level `CHANGE_NOTIFY` watcher for cache freshness |\n| `backend/app/main.py` | application shutdown hooks for directory caches and directory monitors |\n\n## Directory Monitor Lifecycle\n\nThe browser-facing monitor is reference-counted by subscription demand.\n\n`DirectoryMonitor` keeps one `MonitoredDirectory` per `connection_id:path` key and tracks subscriber counts.\n\nThat means:\n\n- the first subscriber starts the monitor\n- later subscribers reuse the same watched directory instance\n- unsubscribing decrements the count\n- the monitor only stops when the count reaches zero\n\nThis avoids opening duplicate SMB watcher handles for the same directory just because multiple browser clients are watching it.\n\n## SMB Resource Management\n\n`MonitoredDirectory` owns low-level SMB resources directly.\n\nCreation follows this order:\n\n1. connection\n2. session\n3. tree connect\n4. directory open handle\n5. `FileSystemWatcher`\n\nCleanup happens in reverse order so partial failure does not leak handles.\n\nThat ordering is important because change-notification bugs are often really handle-lifecycle bugs.\n\n## Watched Events\n\nThe browser-facing monitor currently watches for:\n\n- file-name changes\n- directory-name changes\n- size changes\n- last-write changes\n\nIt uses tree watching so changes in subdirectories can also surface through the same watch.\n\nThe directory-cache watcher is narrower by design.\n\nIt watches directory-name changes across the tree because the cache only needs enough signal to update its directory index efficiently.\n\n## Recovery and Failure Handling\n\nThe directory monitor treats connection failures as part of normal long-lived operation, not as impossible edge cases.\n\nCurrent behavior includes:\n\n- exponential backoff for reconnect attempts\n- retry jitter to avoid synchronized reconnect storms\n- capped retry attempts before giving up\n- explicit detection of connection, socket, and timeout failures\n- stop-on-delete behavior when the watched directory itself is deleted\n\nThe cache watcher has its own retry loop and also tolerates `CHANGE_NOTIFY` buffer-overflow conditions by relying on later rescans to restore correctness.\n\nThat distinction matters: browser notification is path-specific and subscriber-driven, while the cache watcher is connection-scoped and consistency-oriented.\n\n## Shutdown Behavior\n\nSambee shuts these systems down explicitly.\n\nDuring application shutdown:\n\n- directory caches are stopped through `shutdown_directory_cache()`\n- directory monitors are stopped through `shutdown_monitor()`\n\nThat explicit shutdown path exists to release watcher threads and SMB handles cleanly instead of depending on interpreter teardown.\n\n## Performance Characteristics\n\nThe design tries to keep freshness inexpensive without resorting to constant polling.\n\n- SMB `CHANGE_NOTIFY` is event-driven rather than poll-based\n- multiple browser subscribers share one monitor for the same watched path\n- directory-cache updates avoid full rescans for every single directory rename or add event\n- periodic rescans remain in place as a correctness safety net, not the primary freshness mechanism\n\n## Limits and Tradeoffs\n\nContributors need to preserve a few constraints here.\n\n- this requires SMB2 or later\n- some notifications can still be missed during network instability, which is why manual refresh and periodic cache rescans still matter\n- the browser-facing path is optimized for telling clients to refresh, not for transmitting rich per-file diffs\n- cache freshness and browser freshness are related concerns, but they are not the same subsystem and should not be collapsed casually\n\n## Common Failure Modes\n\n- path-prefix resolution is ignored, so the monitor watches the wrong SMB directory\n- subscriber bookkeeping drifts, so monitors are leaked or stopped too early\n- WebSocket disconnect cleanup forgets to release the last subscriber's monitor\n- a recovery change handles one timeout path but leaks SMB resources on reconnect\n- buffer-overflow or rename-edge handling is simplified in ways that quietly degrade cache correctness\n\n## Where to Continue\n\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the changed behavior interacts with uploads, moves, renames, or companion-assisted editing.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider backend or browser validation.\n\n## Validation Expectations\n\nWhen you change SMB change-notification behavior, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects browser-visible refresh behavior, add the relevant frontend checks as well.\n", "1.0": "+++\ntitle = \"SMB Change Notification and Directory Freshness\"\n+++\n\nSambee uses SMB2/SMB3 `CHANGE_NOTIFY` support to keep directory state fresh without falling back to naive polling.\n\nThat capability is used in two different backend paths:\n\n- `backend/app/services/directory_monitor.py` for browser-visible WebSocket refresh notifications\n- `backend/app/services/directory_cache.py` for per-connection directory-cache freshness\n\nUse this page when a backend change affects WebSocket directory updates, SMB watcher lifecycle, or how the product maintains fresh directory state over time.\n\n## Why This Matters\n\nDirectory freshness is a cross-boundary product contract.\n\nUsers expect Sambee to react when:\n\n- another SMB client creates, deletes, renames, or edits content in the current directory\n- the current browser view should refresh because the underlying SMB directory changed\n- cached directory-search data should stay reasonably current without rescanning the entire tree on every request\n\nThat is why the backend owns change-notification behavior instead of leaving refresh decisions entirely to the browser.\n\n## The Two Change-Notification Paths\n\nSambee does not have a single watcher for all purposes.\n\n### Browser Notification Path\n\n`directory_monitor.py` is responsible for directory-specific monitoring tied to active WebSocket subscriptions.\n\nIts job is to:\n\n- start watching a directory when the first browser subscriber appears\n- share one SMB monitor across multiple subscribers for the same watched path\n- stop monitoring when the last subscriber leaves\n- send `directory_changed` messages back through the WebSocket layer\n\nThis is the path that keeps an open file browser view fresh.\n\n### Directory-Cache Freshness Path\n\n`directory_cache.py` uses its own `CHANGE_NOTIFY` watcher for a different reason.\n\nIts job is to:\n\n- watch the share root or effective path prefix for directory-name changes\n- keep the in-memory directory cache aligned with adds, removes, and renames\n- combine event-driven updates with periodic full rescans as a safety net\n- preserve fast directory-search behavior without rebuilding the entire cache on every navigation event\n\nThis is not the same as the browser WebSocket monitor, even though both rely on SMB `CHANGE_NOTIFY`.\n\n## Browser Notification Flow\n\nAt a high level, the browser-facing flow is:\n\n1. the browser opens the backend WebSocket endpoint\n2. it sends a subscription message for a connection and directory path\n3. `ConnectionManager` resolves access, applies any `path_prefix`, and starts monitoring if this is the first subscriber\n4. `DirectoryMonitor` opens SMB resources for that resolved directory and starts a background watcher thread\n5. when the SMB server reports a change, the backend emits `directory_changed` to all subscribers for the user-facing path\n6. when the last subscriber leaves, the monitor stops and releases its SMB resources\n\nRepresentative client messages include:\n\n- subscribe: `{ \"action\": \"subscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- unsubscribe: `{ \"action\": \"unsubscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- server notification: `{ \"type\": \"directory_changed\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n\n## Path Resolution and Subscription Keys\n\nOne subtle but important part of the design is that browser subscriptions and SMB watches do not always use the same path string.\n\nThe WebSocket layer keys subscriptions by the user-facing path.\n\nIf the SMB connection has a `path_prefix`, the backend resolves the actual watched SMB path by combining:\n\n- the normalized connection prefix\n- the user-facing relative path\n\nThat resolved SMB path is what `DirectoryMonitor` actually watches.\n\nThe callback then maps notifications back to the user-facing path before sending `directory_changed` over the WebSocket.\n\nIf you remove that mapping, subscriptions stop lining up with the paths the browser thinks it subscribed to.\n\n## Main Components\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/api/websocket.py` | WebSocket endpoint, subscription bookkeeping, access checks, path-prefix resolution, and delivery of `directory_changed` events |\n| `backend/app/services/directory_monitor.py` | per-directory SMB watchers for active browser subscriptions |\n| `backend/app/services/directory_cache.py` | per-connection directory cache plus root-level `CHANGE_NOTIFY` watcher for cache freshness |\n| `backend/app/main.py` | application shutdown hooks for directory caches and directory monitors |\n\n## Directory Monitor Lifecycle\n\nThe browser-facing monitor is reference-counted by subscription demand.\n\n`DirectoryMonitor` keeps one `MonitoredDirectory` per `connection_id:path` key and tracks subscriber counts.\n\nThat means:\n\n- the first subscriber starts the monitor\n- later subscribers reuse the same watched directory instance\n- unsubscribing decrements the count\n- the monitor only stops when the count reaches zero\n\nThis avoids opening duplicate SMB watcher handles for the same directory just because multiple browser clients are watching it.\n\n## SMB Resource Management\n\n`MonitoredDirectory` owns low-level SMB resources directly.\n\nCreation follows this order:\n\n1. connection\n2. session\n3. tree connect\n4. directory open handle\n5. `FileSystemWatcher`\n\nCleanup happens in reverse order so partial failure does not leak handles.\n\nThat ordering is important because change-notification bugs are often really handle-lifecycle bugs.\n\n## Watched Events\n\nThe browser-facing monitor currently watches for:\n\n- file-name changes\n- directory-name changes\n- size changes\n- last-write changes\n\nIt uses tree watching so changes in subdirectories can also surface through the same watch.\n\nThe directory-cache watcher is narrower by design.\n\nIt watches directory-name changes across the tree because the cache only needs enough signal to update its directory index efficiently.\n\n## Recovery and Failure Handling\n\nThe directory monitor treats connection failures as part of normal long-lived operation, not as impossible edge cases.\n\nCurrent behavior includes:\n\n- exponential backoff for reconnect attempts\n- retry jitter to avoid synchronized reconnect storms\n- capped retry attempts before giving up\n- explicit detection of connection, socket, and timeout failures\n- stop-on-delete behavior when the watched directory itself is deleted\n\nThe cache watcher has its own retry loop and also tolerates `CHANGE_NOTIFY` buffer-overflow conditions by relying on later rescans to restore correctness.\n\nThat distinction matters: browser notification is path-specific and subscriber-driven, while the cache watcher is connection-scoped and consistency-oriented.\n\n## Shutdown Behavior\n\nSambee shuts these systems down explicitly.\n\nDuring application shutdown:\n\n- directory caches are stopped through `shutdown_directory_cache()`\n- directory monitors are stopped through `shutdown_monitor()`\n\nThat explicit shutdown path exists to release watcher threads and SMB handles cleanly instead of depending on interpreter teardown.\n\n## Performance Characteristics\n\nThe design tries to keep freshness inexpensive without resorting to constant polling.\n\n- SMB `CHANGE_NOTIFY` is event-driven rather than poll-based\n- multiple browser subscribers share one monitor for the same watched path\n- directory-cache updates avoid full rescans for every single directory rename or add event\n- periodic rescans remain in place as a correctness safety net, not the primary freshness mechanism\n\n## Limits and Tradeoffs\n\nContributors need to preserve a few constraints here.\n\n- this requires SMB2 or later\n- some notifications can still be missed during network instability, which is why manual refresh and periodic cache rescans still matter\n- the browser-facing path is optimized for telling clients to refresh, not for transmitting rich per-file diffs\n- cache freshness and browser freshness are related concerns, but they are not the same subsystem and should not be collapsed casually\n\n## Common Failure Modes\n\n- path-prefix resolution is ignored, so the monitor watches the wrong SMB directory\n- subscriber bookkeeping drifts, so monitors are leaked or stopped too early\n- WebSocket disconnect cleanup forgets to release the last subscriber's monitor\n- a recovery change handles one timeout path but leaks SMB resources on reconnect\n- buffer-overflow or rename-edge handling is simplified in ways that quietly degrade cache correctness\n\n## Where to Continue\n\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the changed behavior interacts with uploads, moves, renames, or companion-assisted editing.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider backend or browser validation.\n\n## Validation Expectations\n\nWhen you change SMB change-notification behavior, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects browser-visible refresh behavior, add the relevant frontend checks as well.\n", "2.0": "+++\ntitle = \"SMB Change Notification and Directory Freshness\"\n+++\n\nSambee uses SMB2/SMB3 `CHANGE_NOTIFY` support to keep directory state fresh without falling back to naive polling.\n\nThat capability is used in two different backend paths:\n\n- `backend/app/services/directory_monitor.py` for browser-visible WebSocket refresh notifications\n- `backend/app/services/directory_cache.py` for per-connection directory-cache freshness\n\nUse this page when a backend change affects WebSocket directory updates, SMB watcher lifecycle, or how the product maintains fresh directory state over time.\n\n## Why This Matters\n\nDirectory freshness is a cross-boundary product contract.\n\nUsers expect Sambee to react when:\n\n- another SMB client creates, deletes, renames, or edits content in the current directory\n- the current browser view should refresh because the underlying SMB directory changed\n- cached directory-search data should stay reasonably current without rescanning the entire tree on every request\n\nThat is why the backend owns change-notification behavior instead of leaving refresh decisions entirely to the browser.\n\n## The Two Change-Notification Paths\n\nSambee does not have a single watcher for all purposes.\n\n### Browser Notification Path\n\n`directory_monitor.py` is responsible for directory-specific monitoring tied to active WebSocket subscriptions.\n\nIts job is to:\n\n- start watching a directory when the first browser subscriber appears\n- share one SMB monitor across multiple subscribers for the same watched path\n- stop monitoring when the last subscriber leaves\n- send `directory_changed` messages back through the WebSocket layer\n\nThis is the path that keeps an open file browser view fresh.\n\n### Directory-Cache Freshness Path\n\n`directory_cache.py` uses its own `CHANGE_NOTIFY` watcher for a different reason.\n\nIts job is to:\n\n- watch the share root or effective path prefix for directory-name changes\n- keep the in-memory directory cache aligned with adds, removes, and renames\n- combine event-driven updates with periodic full rescans as a safety net\n- preserve fast directory-search behavior without rebuilding the entire cache on every navigation event\n\nThis is not the same as the browser WebSocket monitor, even though both rely on SMB `CHANGE_NOTIFY`.\n\n## Browser Notification Flow\n\nAt a high level, the browser-facing flow is:\n\n1. the browser opens the backend WebSocket endpoint\n2. it sends a subscription message for a connection and directory path\n3. `ConnectionManager` resolves access, applies any `path_prefix`, and starts monitoring if this is the first subscriber\n4. `DirectoryMonitor` opens SMB resources for that resolved directory and starts a background watcher thread\n5. when the SMB server reports a change, the backend emits `directory_changed` to all subscribers for the user-facing path\n6. when the last subscriber leaves, the monitor stops and releases its SMB resources\n\nRepresentative client messages include:\n\n- subscribe: `{ \"action\": \"subscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- unsubscribe: `{ \"action\": \"unsubscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- server notification: `{ \"type\": \"directory_changed\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n\n## Path Resolution and Subscription Keys\n\nOne subtle but important part of the design is that browser subscriptions and SMB watches do not always use the same path string.\n\nThe WebSocket layer keys subscriptions by the user-facing path.\n\nIf the SMB connection has a `path_prefix`, the backend resolves the actual watched SMB path by combining:\n\n- the normalized connection prefix\n- the user-facing relative path\n\nThat resolved SMB path is what `DirectoryMonitor` actually watches.\n\nThe callback then maps notifications back to the user-facing path before sending `directory_changed` over the WebSocket.\n\nIf you remove that mapping, subscriptions stop lining up with the paths the browser thinks it subscribed to.\n\n## Main Components\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/api/websocket.py` | WebSocket endpoint, subscription bookkeeping, access checks, path-prefix resolution, and delivery of `directory_changed` events |\n| `backend/app/services/directory_monitor.py` | per-directory SMB watchers for active browser subscriptions |\n| `backend/app/services/directory_cache.py` | per-connection directory cache plus root-level `CHANGE_NOTIFY` watcher for cache freshness |\n| `backend/app/main.py` | application shutdown hooks for directory caches and directory monitors |\n\n## Directory Monitor Lifecycle\n\nThe browser-facing monitor is reference-counted by subscription demand.\n\n`DirectoryMonitor` keeps one `MonitoredDirectory` per `connection_id:path` key and tracks subscriber counts.\n\nThat means:\n\n- the first subscriber starts the monitor\n- later subscribers reuse the same watched directory instance\n- unsubscribing decrements the count\n- the monitor only stops when the count reaches zero\n\nThis avoids opening duplicate SMB watcher handles for the same directory just because multiple browser clients are watching it.\n\n## SMB Resource Management\n\n`MonitoredDirectory` owns low-level SMB resources directly.\n\nCreation follows this order:\n\n1. connection\n2. session\n3. tree connect\n4. directory open handle\n5. `FileSystemWatcher`\n\nCleanup happens in reverse order so partial failure does not leak handles.\n\nThat ordering is important because change-notification bugs are often really handle-lifecycle bugs.\n\n## Watched Events\n\nThe browser-facing monitor currently watches for:\n\n- file-name changes\n- directory-name changes\n- size changes\n- last-write changes\n\nThe browser-facing monitor watches only immediate children of the subscribed directory. Writes deeper in the tree, such as installing packages in a project's `node_modules` folder, don't invalidate an ancestor's file list. If the SMB server reports a metadata change for an immediate child directory, that change can still trigger a refresh.\n\nThe directory-cache watcher is narrower by design.\n\nIt watches directory-name changes across the tree because the cache only needs enough signal to update its directory index efficiently.\n\n## Directory-Index Consistency\n\nA full rescan builds a replacement index while the current index continues to serve directory searches. If any directory read fails or times out, the replacement isn't published or persisted. The existing index remains available, and the scan error is recorded for diagnosis. A later successful rescan can replace it.\n\nWhile a rescan is running, directory additions, removals, and renames update the live index and are also recorded in order. Under the cache lock, Sambee checks pending operations before and after each directory read and before publication. Additions are safe to merge. Removals and renames can only be merged when they don't overlap a read that's already started.\n\nIf a removal or rename changes a directory that's already been read, one being read, an ancestor of either, or an immediate child's name, the replacement is ambiguous. Notifications can arrive after a read already reflects the change, so replaying them could rename or remove fresh paths a second time. Sambee discards the replacement rather than publishing or persisting it; the live index, including its recent changes, remains available. Only one rescan can run at a time, and cancellation discards pending reconciliation without discarding live updates.\n\nDirectory junctions, symbolic links, and unrecognized directory reparse points are indexed as destinations, but scans don't descend into their targets. This prevents ancestor links from causing repeated traversal. DFS referrals are identified by their reparse tag and remain traversable through the SMB client's referral support, so directories below DFS links stay searchable.\n\n### Persisted Snapshots\n\nVersion 2 snapshots are bound to the connection's host, port, share, normalized path prefix, username, and connection revision. The revision changes when the connection is edited, including credential changes. Passwords aren't stored in snapshot metadata.\n\nA snapshot with a different source identity is ignored, including when trying the backup file. Older version 1 snapshots are also ignored, so existing installations rebuild the directory index once after upgrading. Matching snapshots still provide immediate search results while background verification checks freshness.\n\nStartup verification and the periodic rescan loop have separate tracked tasks. Removing a cache or shutting down the application cancels both tasks, along with initial scanning and snapshot flushing.\n\n## Recovery and Failure Handling\n\nThe directory monitor treats connection failures as part of normal long-lived operation, not as impossible edge cases.\n\nCurrent behavior includes:\n\n- exponential backoff for reconnect attempts\n- retry jitter to avoid synchronized reconnect storms\n- capped retry attempts before giving up\n- explicit detection of connection, socket, and timeout failures\n- stop-on-delete behavior when the watched directory itself is deleted\n\nThe cache watcher has its own retry loop and also tolerates `CHANGE_NOTIFY` buffer-overflow conditions by relying on later rescans to restore correctness.\n\nThat distinction matters: browser notification is path-specific and subscriber-driven, while the cache watcher is connection-scoped and consistency-oriented.\n\n## Shutdown Behavior\n\nSambee shuts these systems down explicitly.\n\nDuring application shutdown:\n\n- directory caches are stopped through `shutdown_directory_cache()`\n- directory monitors are stopped through `shutdown_monitor()`\n\nThat explicit shutdown path exists to release watcher threads and SMB handles cleanly instead of depending on interpreter teardown.\n\n## Performance Characteristics\n\nThe design tries to keep freshness inexpensive without resorting to constant polling.\n\n- SMB `CHANGE_NOTIFY` is event-driven rather than poll-based\n- multiple browser subscribers share one monitor for the same watched path\n- browser-facing monitors don't request recursive subtree notifications\n- each browser pane keeps loaded physical-directory rows visible during automatic refreshes, including a previously loaded empty listing\n- automatic refreshes wait for an active listing request and combine newer notifications into one pending refresh, starting at most once per second\n- navigation and pane disposal cancel queued refreshes\n- directory-cache updates avoid full rescans for every single directory rename or add event\n- periodic rescans remain in place as a correctness safety net, not the primary freshness mechanism\n\n## Limits and Tradeoffs\n\nContributors need to preserve a few constraints here.\n\n- this requires SMB2 or later\n- some notifications can still be missed during network instability, which is why manual refresh and periodic cache rescans still matter\n- the browser-facing path is optimized for telling clients to refresh, not for transmitting rich per-file diffs\n- cache freshness and browser freshness are related concerns, but they are not the same subsystem and should not be collapsed casually\n\n## Common Failure Modes\n\n- path-prefix resolution is ignored, so the monitor watches the wrong SMB directory\n- subscriber bookkeeping drifts, so monitors are leaked or stopped too early\n- WebSocket disconnect cleanup forgets to release the last subscriber's monitor\n- a recovery change handles one timeout path but leaks SMB resources on reconnect\n- buffer-overflow or rename-edge handling is simplified in ways that quietly degrade cache correctness\n\n## Where to Continue\n\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the changed behavior interacts with uploads, moves, renames, or companion-assisted editing.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider backend or browser validation.\n\n## Validation Expectations\n\nWhen you change SMB change-notification behavior, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects browser-visible refresh behavior, add the relevant frontend checks as well.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/backend-architecture/file-operations-and-edit-locking", "parent_id": "section:developer-guide/backend-architecture", "depth": 2, "kind": "page", "label": "file-operations-and-edit-locking", "title": "File Operations And Edit Locking", "path": "developer-guide/backend-architecture/file-operations-and-edit-locking", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"File Operations and Edit Locking\"\n+++\n\nNot every file operation in Sambee follows the same lifecycle.\n\n## Two Different Operation Families\n\n### Ordinary File Operations\n\nThese are the browser-facing operations such as:\n\n- browse and inspect\n- create and rename\n- copy and move\n- upload and download\n- delete\n\nThese requests usually enter through the browser-facing API and are executed through the backend storage layer.\n\n### Companion-Assisted SMB Editing\n\nThis is the higher-risk path used when a user opens an SMB-backed file in a native desktop app.\n\nThat flow adds:\n\n- token exchange\n- file download to a temp location\n- backend-managed edit locking\n- lock heartbeat and lock-status checks\n- upload or discard decision at the end of editing\n- conflict handling before the server copy is replaced\n\n## Ordinary File Operations\n\nThe browser file-management path depends on typed request models and clear storage semantics.\n\n- copy and move requests use structured request data instead of ad hoc parameters\n- same-path or invalid operations are rejected explicitly\n- server-side copy and move semantics depend on the backend's storage capabilities\n- conflict responses and validation errors are part of the user-visible contract\n\nThe backend should stay authoritative here, even when the frontend tries to make the operation feel immediate.\n\n## Why Edit Locking Exists\n\nNative-app editing of SMB-backed files is a coordination problem, not just a download-and-upload shortcut.\n\nThe backend owns the server-facing lock lifecycle so that:\n\n- concurrent edits are visible and controllable\n- the companion can refresh the lock while editing is still in progress\n- stale or interrupted sessions can be detected\n- conflict decisions happen against the real server state\n\n## High-Level Companion Edit Lifecycle\n\nFor the SMB-backed desktop editing path:\n\n1. the companion exchanges the deep-link token for an authenticated session\n2. it fetches file metadata and downloads the file\n3. it acquires the edit lock from the backend\n4. it keeps the lock alive with heartbeat traffic while the file is open\n5. it uploads the changed file or discards it\n6. it releases the lock and closes out the operation\n\nThe backend is the source of truth for lock state even though the companion is the actor performing the desktop-side work.\n\n## Conflict Handling\n\nBefore a modified file is written back, the system compares the expected server state with the current one.\n\nIf the server copy changed while the user was editing, the companion should not silently overwrite it. That is why conflict handling is part of the backend contract rather than just a local desktop decision.\n\n## Important Distinction: Local Drives\n\nLocal-drive workflows do not use this backend edit-lock lifecycle.\n\n- local files are handled through the paired localhost companion API\n- direct local open can avoid download, lock, upload, and \"Done Editing\" entirely\n- SMB-backed native-app editing still depends on backend lock and upload semantics\n\nDo not blur those two paths when changing edit behavior.\n\n## Adjacent Concern: Freshness after Operations\n\nAfter file operations complete, the browser still needs fresh directory state. That is where change notification and WebSocket refresh behavior become relevant.\n\nOrdinary CRUD operations and companion-assisted edit completion both depend on the rest of the system noticing that directory state has changed.\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npm test\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nChoose the exact subset based on whether the change affects ordinary browser file management, companion editing, or both.\n", "0.8": "+++\ntitle = \"File Operations and Edit Locking\"\n+++\n\nNot every file operation in Sambee follows the same lifecycle.\n\n## Two Different Operation Families\n\n### Ordinary File Operations\n\nThese are the browser-facing operations such as:\n\n- browse and inspect\n- create and rename\n- copy and move\n- upload and download\n- delete\n\nThese requests usually enter through the browser-facing API and are executed through the backend storage layer.\n\n### Companion-Assisted SMB Editing\n\nThis is the higher-risk path used when a user opens an SMB-backed file in a native desktop app.\n\nThat flow adds:\n\n- token exchange\n- file download to a temp location\n- backend-managed edit locking\n- lock heartbeat and lock-status checks\n- upload or discard decision at the end of editing\n- conflict handling before the server copy is replaced\n\n## Ordinary File Operations\n\nThe browser file-management path depends on typed request models and clear storage semantics.\n\n- copy and move requests use structured request data instead of ad hoc parameters\n- same-path or invalid operations are rejected explicitly\n- server-side copy and move semantics depend on the backend's storage capabilities\n- conflict responses and validation errors are part of the user-visible contract\n\nThe backend should stay authoritative here, even when the frontend tries to make the operation feel immediate.\n\n## Why Edit Locking Exists\n\nNative-app editing of SMB-backed files is a coordination problem, not just a download-and-upload shortcut.\n\nThe backend owns the server-facing lock lifecycle so that:\n\n- concurrent edits are visible and controllable\n- the companion can refresh the lock while editing is still in progress\n- stale or interrupted sessions can be detected\n- conflict decisions happen against the real server state\n\n## High-Level Companion Edit Lifecycle\n\nFor the SMB-backed desktop editing path:\n\n1. the companion exchanges the deep-link token for an authenticated session\n2. it fetches file metadata and downloads the file\n3. it acquires the edit lock from the backend\n4. it keeps the lock alive with heartbeat traffic while the file is open\n5. it uploads the changed file or discards it\n6. it releases the lock and closes out the operation\n\nThe backend is the source of truth for lock state even though the companion is the actor performing the desktop-side work.\n\n## Conflict Handling\n\nBefore a modified file is written back, the system compares the expected server state with the current one.\n\nIf the server copy changed while the user was editing, the companion should not silently overwrite it. That is why conflict handling is part of the backend contract rather than just a local desktop decision.\n\n## Important Distinction: Local Drives\n\nLocal-drive workflows do not use this backend edit-lock lifecycle.\n\n- local files are handled through the paired localhost companion API\n- direct local open can avoid download, lock, upload, and \"Done Editing\" entirely\n- SMB-backed native-app editing still depends on backend lock and upload semantics\n\nDo not blur those two paths when changing edit behavior.\n\n## Adjacent Concern: Freshness after Operations\n\nAfter file operations complete, the browser still needs fresh directory state. That is where change notification and WebSocket refresh behavior become relevant.\n\nOrdinary CRUD operations and companion-assisted edit completion both depend on the rest of the system noticing that directory state has changed.\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npm test\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nChoose the exact subset based on whether the change affects ordinary browser file management, companion editing, or both.\n", "0.9": "+++\ntitle = \"File Operations and Edit Locking\"\n+++\n\nNot every file operation in Sambee follows the same lifecycle.\n\n## Two Different Operation Families\n\n### Ordinary File Operations\n\nThese are the browser-facing operations such as:\n\n- browse and inspect\n- create and rename\n- copy and move\n- upload and download\n- delete\n\nThese requests usually enter through the browser-facing API and are executed through the backend storage layer.\n\n### Companion-Assisted SMB Editing\n\nThis is the higher-risk path used when a user opens an SMB-backed file in a native desktop app.\n\nThat flow adds:\n\n- token exchange\n- file download to a temp location\n- backend-managed edit locking\n- lock heartbeat and lock-status checks\n- upload or discard decision at the end of editing\n- conflict handling before the server copy is replaced\n\n## Ordinary File Operations\n\nThe browser file-management path depends on typed request models and clear storage semantics.\n\n- copy and move requests use structured request data instead of ad hoc parameters\n- same-path or invalid operations are rejected explicitly\n- server-side copy and move semantics depend on the backend's storage capabilities\n- conflict responses and validation errors are part of the user-visible contract\n\nThe backend should stay authoritative here, even when the frontend tries to make the operation feel immediate.\n\n## Why Edit Locking Exists\n\nNative-app editing of SMB-backed files is a coordination problem, not just a download-and-upload shortcut.\n\nThe backend owns the server-facing lock lifecycle so that:\n\n- concurrent edits are visible and controllable\n- the companion can refresh the lock while editing is still in progress\n- stale or interrupted sessions can be detected\n- conflict decisions happen against the real server state\n\n## High-Level Companion Edit Lifecycle\n\nFor the SMB-backed desktop editing path:\n\n1. the companion exchanges the deep-link token for an authenticated session\n2. it fetches file metadata and downloads the file\n3. it acquires the edit lock from the backend\n4. it keeps the lock alive with heartbeat traffic while the file is open\n5. it uploads the changed file or discards it\n6. it releases the lock and closes out the operation\n\nThe backend is the source of truth for lock state even though the companion is the actor performing the desktop-side work.\n\n## Conflict Handling\n\nBefore a modified file is written back, the system compares the expected server state with the current one.\n\nIf the server copy changed while the user was editing, the companion should not silently overwrite it. That is why conflict handling is part of the backend contract rather than just a local desktop decision.\n\n## Important Distinction: Local Drives\n\nLocal-drive workflows do not use this backend edit-lock lifecycle.\n\n- local files are handled through the paired localhost companion API\n- direct local open can avoid download, lock, upload, and \"Done Editing\" entirely\n- SMB-backed native-app editing still depends on backend lock and upload semantics\n\nDo not blur those two paths when changing edit behavior.\n\n## Adjacent Concern: Freshness after Operations\n\nAfter file operations complete, the browser still needs fresh directory state. That is where change notification and WebSocket refresh behavior become relevant.\n\nOrdinary CRUD operations and companion-assisted edit completion both depend on the rest of the system noticing that directory state has changed.\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npm test\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nChoose the exact subset based on whether the change affects ordinary browser file management, companion editing, or both.\n", "1.0": "+++\ntitle = \"File Operations and Edit Locking\"\n+++\n\nNot every file operation in Sambee follows the same lifecycle.\n\n## Two Different Operation Families\n\n### Ordinary File Operations\n\nThese are the browser-facing operations such as:\n\n- browse and inspect\n- create and rename\n- copy and move\n- upload and download\n- delete\n\nThese requests usually enter through the browser-facing API and are executed through the backend storage layer.\n\n### Companion-Assisted SMB Editing\n\nThis is the higher-risk path used when a user opens an SMB-backed file in a native desktop app.\n\nThat flow adds:\n\n- token exchange\n- file download to a temp location\n- backend-managed edit locking\n- lock heartbeat and lock-status checks\n- upload or discard decision at the end of editing\n- conflict handling before the server copy is replaced\n\n## Ordinary File Operations\n\nThe browser file-management path depends on typed request models and clear storage semantics.\n\n- copy and move requests use structured request data instead of ad hoc parameters\n- same-path or invalid operations are rejected explicitly\n- server-side copy and move semantics depend on the backend's storage capabilities\n- conflict responses and validation errors are part of the user-visible contract\n\nThe backend should stay authoritative here, even when the frontend tries to make the operation feel immediate.\n\n## Why Edit Locking Exists\n\nNative-app editing of SMB-backed files is a coordination problem, not just a download-and-upload shortcut.\n\nThe backend owns the server-facing lock lifecycle so that:\n\n- concurrent edits are visible and controllable\n- the companion can refresh the lock while editing is still in progress\n- stale or interrupted sessions can be detected\n- conflict decisions happen against the real server state\n\n## High-Level Companion Edit Lifecycle\n\nFor the SMB-backed desktop editing path:\n\n1. the companion exchanges the deep-link token for an authenticated session\n2. it fetches file metadata and downloads the file\n3. it acquires the edit lock from the backend\n4. it keeps the lock alive with heartbeat traffic while the file is open\n5. it uploads the changed file or discards it\n6. it releases the lock and closes out the operation\n\nThe backend is the source of truth for lock state even though the companion is the actor performing the desktop-side work.\n\n## Conflict Handling\n\nBefore a modified file is written back, the system compares the expected server state with the current one.\n\nIf the server copy changed while the user was editing, the companion should not silently overwrite it. That is why conflict handling is part of the backend contract rather than just a local desktop decision.\n\n## Important Distinction: Local Drives\n\nLocal-drive workflows do not use this backend edit-lock lifecycle.\n\n- local files are handled through the paired localhost companion API\n- direct local open can avoid download, lock, upload, and \"Done Editing\" entirely\n- SMB-backed native-app editing still depends on backend lock and upload semantics\n\nDo not blur those two paths when changing edit behavior.\n\n## Adjacent Concern: Freshness after Operations\n\nAfter file operations complete, the browser still needs fresh directory state. That is where change notification and WebSocket refresh behavior become relevant.\n\nOrdinary CRUD operations and companion-assisted edit completion both depend on the rest of the system noticing that directory state has changed.\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npm test\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nChoose the exact subset based on whether the change affects ordinary browser file management, companion editing, or both.\n", "2.0": "+++\ntitle = \"File Operations and Edit Locking\"\n+++\n\nNot every file operation in Sambee follows the same lifecycle.\n\n## Two Different Operation Families\n\n### Ordinary File Operations\n\nThese are the browser-facing operations such as:\n\n- browse and inspect\n- create and rename\n- copy and move\n- upload and download\n- delete\n\nThese requests usually enter through the browser-facing API and are executed through the backend storage layer.\n\n### Companion-Assisted SMB Editing\n\nThis is the higher-risk path used when a user opens an SMB-backed file in a native desktop app.\n\nThat flow adds:\n\n- token exchange\n- file download to a temp location\n- backend-managed edit locking\n- lock heartbeat and lock-status checks\n- upload or discard decision at the end of editing\n- conflict handling before the server copy is replaced\n\n## Ordinary File Operations\n\nThe browser file-management path depends on typed request models and clear storage semantics.\n\n- copy and move requests use structured request data instead of ad hoc parameters\n- same-path or invalid operations are rejected explicitly\n- server-side copy and move semantics depend on the backend's storage capabilities\n- conflict responses and validation errors are part of the user-visible contract\n\nThe backend should stay authoritative here, even when the frontend tries to make the operation feel immediate.\n\n## Why Edit Locking Exists\n\nNative-app editing of SMB-backed files is a coordination problem, not just a download-and-upload shortcut.\n\nThe backend owns the server-facing lock lifecycle so that:\n\n- concurrent edits are visible and controllable\n- the companion can refresh the lock while editing is still in progress\n- stale or interrupted sessions can be detected\n- conflict decisions happen against the real server state\n\n## High-Level Companion Edit Lifecycle\n\nFor the SMB-backed desktop editing path:\n\n1. the companion exchanges the deep-link token for an authenticated session\n2. it fetches file metadata and downloads the file\n3. it acquires the edit lock from the backend\n4. it keeps the lock alive with heartbeat traffic while the file is open\n5. it uploads the changed file or discards it\n6. it releases the lock and closes out the operation\n\nThe backend is the source of truth for lock state even though the companion is the actor performing the desktop-side work.\n\n## Conflict Handling\n\nBefore a modified file is written back, the system compares the expected server state with the current one.\n\nIf the server copy changed while the user was editing, the companion should not silently overwrite it. That is why conflict handling is part of the backend contract rather than just a local desktop decision.\n\n## Important Distinction: Local Drives\n\nLocal-drive workflows do not use this backend edit-lock lifecycle.\n\n- local files are handled through the paired localhost companion API\n- direct local open can avoid download, lock, upload, and \"Done Editing\" entirely\n- SMB-backed native-app editing still depends on backend lock and upload semantics\n\nDo not blur those two paths when changing edit behavior.\n\n## Adjacent Concern: Freshness after Operations\n\nAfter file operations complete, the browser still needs fresh directory state. That is where change notification and WebSocket refresh behavior become relevant.\n\nOrdinary CRUD operations and companion-assisted edit completion both depend on the rest of the system noticing that directory state has changed.\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npm test\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nChoose the exact subset based on whether the change affects ordinary browser file management, companion editing, or both.\n"}, "page_contents": {"0.7": "+++\ntitle = \"File Operations and Edit Locking\"\n+++\n\nNot every file operation in Sambee follows the same lifecycle.\n\n## Two Different Operation Families\n\n### Ordinary File Operations\n\nThese are the browser-facing operations such as:\n\n- browse and inspect\n- create and rename\n- copy and move\n- upload and download\n- delete\n\nThese requests usually enter through the browser-facing API and are executed through the backend storage layer.\n\n### Companion-Assisted SMB Editing\n\nThis is the higher-risk path used when a user opens an SMB-backed file in a native desktop app.\n\nThat flow adds:\n\n- token exchange\n- file download to a temp location\n- backend-managed edit locking\n- lock heartbeat and lock-status checks\n- upload or discard decision at the end of editing\n- conflict handling before the server copy is replaced\n\n## Ordinary File Operations\n\nThe browser file-management path depends on typed request models and clear storage semantics.\n\n- copy and move requests use structured request data instead of ad hoc parameters\n- same-path or invalid operations are rejected explicitly\n- server-side copy and move semantics depend on the backend's storage capabilities\n- conflict responses and validation errors are part of the user-visible contract\n\nThe backend should stay authoritative here, even when the frontend tries to make the operation feel immediate.\n\n## Why Edit Locking Exists\n\nNative-app editing of SMB-backed files is a coordination problem, not just a download-and-upload shortcut.\n\nThe backend owns the server-facing lock lifecycle so that:\n\n- concurrent edits are visible and controllable\n- the companion can refresh the lock while editing is still in progress\n- stale or interrupted sessions can be detected\n- conflict decisions happen against the real server state\n\n## High-Level Companion Edit Lifecycle\n\nFor the SMB-backed desktop editing path:\n\n1. the companion exchanges the deep-link token for an authenticated session\n2. it fetches file metadata and downloads the file\n3. it acquires the edit lock from the backend\n4. it keeps the lock alive with heartbeat traffic while the file is open\n5. it uploads the changed file or discards it\n6. it releases the lock and closes out the operation\n\nThe backend is the source of truth for lock state even though the companion is the actor performing the desktop-side work.\n\n## Conflict Handling\n\nBefore a modified file is written back, the system compares the expected server state with the current one.\n\nIf the server copy changed while the user was editing, the companion should not silently overwrite it. That is why conflict handling is part of the backend contract rather than just a local desktop decision.\n\n## Important Distinction: Local Drives\n\nLocal-drive workflows do not use this backend edit-lock lifecycle.\n\n- local files are handled through the paired localhost companion API\n- direct local open can avoid download, lock, upload, and \"Done Editing\" entirely\n- SMB-backed native-app editing still depends on backend lock and upload semantics\n\nDo not blur those two paths when changing edit behavior.\n\n## Adjacent Concern: Freshness after Operations\n\nAfter file operations complete, the browser still needs fresh directory state. That is where change notification and WebSocket refresh behavior become relevant.\n\nOrdinary CRUD operations and companion-assisted edit completion both depend on the rest of the system noticing that directory state has changed.\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npm test\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nChoose the exact subset based on whether the change affects ordinary browser file management, companion editing, or both.\n", "0.8": "+++\ntitle = \"File Operations and Edit Locking\"\n+++\n\nNot every file operation in Sambee follows the same lifecycle.\n\n## Two Different Operation Families\n\n### Ordinary File Operations\n\nThese are the browser-facing operations such as:\n\n- browse and inspect\n- create and rename\n- copy and move\n- upload and download\n- delete\n\nThese requests usually enter through the browser-facing API and are executed through the backend storage layer.\n\n### Companion-Assisted SMB Editing\n\nThis is the higher-risk path used when a user opens an SMB-backed file in a native desktop app.\n\nThat flow adds:\n\n- token exchange\n- file download to a temp location\n- backend-managed edit locking\n- lock heartbeat and lock-status checks\n- upload or discard decision at the end of editing\n- conflict handling before the server copy is replaced\n\n## Ordinary File Operations\n\nThe browser file-management path depends on typed request models and clear storage semantics.\n\n- copy and move requests use structured request data instead of ad hoc parameters\n- same-path or invalid operations are rejected explicitly\n- server-side copy and move semantics depend on the backend's storage capabilities\n- conflict responses and validation errors are part of the user-visible contract\n\nThe backend should stay authoritative here, even when the frontend tries to make the operation feel immediate.\n\n## Why Edit Locking Exists\n\nNative-app editing of SMB-backed files is a coordination problem, not just a download-and-upload shortcut.\n\nThe backend owns the server-facing lock lifecycle so that:\n\n- concurrent edits are visible and controllable\n- the companion can refresh the lock while editing is still in progress\n- stale or interrupted sessions can be detected\n- conflict decisions happen against the real server state\n\n## High-Level Companion Edit Lifecycle\n\nFor the SMB-backed desktop editing path:\n\n1. the companion exchanges the deep-link token for an authenticated session\n2. it fetches file metadata and downloads the file\n3. it acquires the edit lock from the backend\n4. it keeps the lock alive with heartbeat traffic while the file is open\n5. it uploads the changed file or discards it\n6. it releases the lock and closes out the operation\n\nThe backend is the source of truth for lock state even though the companion is the actor performing the desktop-side work.\n\n## Conflict Handling\n\nBefore a modified file is written back, the system compares the expected server state with the current one.\n\nIf the server copy changed while the user was editing, the companion should not silently overwrite it. That is why conflict handling is part of the backend contract rather than just a local desktop decision.\n\n## Important Distinction: Local Drives\n\nLocal-drive workflows do not use this backend edit-lock lifecycle.\n\n- local files are handled through the paired localhost companion API\n- direct local open can avoid download, lock, upload, and \"Done Editing\" entirely\n- SMB-backed native-app editing still depends on backend lock and upload semantics\n\nDo not blur those two paths when changing edit behavior.\n\n## Adjacent Concern: Freshness after Operations\n\nAfter file operations complete, the browser still needs fresh directory state. That is where change notification and WebSocket refresh behavior become relevant.\n\nOrdinary CRUD operations and companion-assisted edit completion both depend on the rest of the system noticing that directory state has changed.\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npm test\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nChoose the exact subset based on whether the change affects ordinary browser file management, companion editing, or both.\n", "0.9": "+++\ntitle = \"File Operations and Edit Locking\"\n+++\n\nNot every file operation in Sambee follows the same lifecycle.\n\n## Two Different Operation Families\n\n### Ordinary File Operations\n\nThese are the browser-facing operations such as:\n\n- browse and inspect\n- create and rename\n- copy and move\n- upload and download\n- delete\n\nThese requests usually enter through the browser-facing API and are executed through the backend storage layer.\n\n### Companion-Assisted SMB Editing\n\nThis is the higher-risk path used when a user opens an SMB-backed file in a native desktop app.\n\nThat flow adds:\n\n- token exchange\n- file download to a temp location\n- backend-managed edit locking\n- lock heartbeat and lock-status checks\n- upload or discard decision at the end of editing\n- conflict handling before the server copy is replaced\n\n## Ordinary File Operations\n\nThe browser file-management path depends on typed request models and clear storage semantics.\n\n- copy and move requests use structured request data instead of ad hoc parameters\n- same-path or invalid operations are rejected explicitly\n- server-side copy and move semantics depend on the backend's storage capabilities\n- conflict responses and validation errors are part of the user-visible contract\n\nThe backend should stay authoritative here, even when the frontend tries to make the operation feel immediate.\n\n## Why Edit Locking Exists\n\nNative-app editing of SMB-backed files is a coordination problem, not just a download-and-upload shortcut.\n\nThe backend owns the server-facing lock lifecycle so that:\n\n- concurrent edits are visible and controllable\n- the companion can refresh the lock while editing is still in progress\n- stale or interrupted sessions can be detected\n- conflict decisions happen against the real server state\n\n## High-Level Companion Edit Lifecycle\n\nFor the SMB-backed desktop editing path:\n\n1. the companion exchanges the deep-link token for an authenticated session\n2. it fetches file metadata and downloads the file\n3. it acquires the edit lock from the backend\n4. it keeps the lock alive with heartbeat traffic while the file is open\n5. it uploads the changed file or discards it\n6. it releases the lock and closes out the operation\n\nThe backend is the source of truth for lock state even though the companion is the actor performing the desktop-side work.\n\n## Conflict Handling\n\nBefore a modified file is written back, the system compares the expected server state with the current one.\n\nIf the server copy changed while the user was editing, the companion should not silently overwrite it. That is why conflict handling is part of the backend contract rather than just a local desktop decision.\n\n## Important Distinction: Local Drives\n\nLocal-drive workflows do not use this backend edit-lock lifecycle.\n\n- local files are handled through the paired localhost companion API\n- direct local open can avoid download, lock, upload, and \"Done Editing\" entirely\n- SMB-backed native-app editing still depends on backend lock and upload semantics\n\nDo not blur those two paths when changing edit behavior.\n\n## Adjacent Concern: Freshness after Operations\n\nAfter file operations complete, the browser still needs fresh directory state. That is where change notification and WebSocket refresh behavior become relevant.\n\nOrdinary CRUD operations and companion-assisted edit completion both depend on the rest of the system noticing that directory state has changed.\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npm test\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nChoose the exact subset based on whether the change affects ordinary browser file management, companion editing, or both.\n", "1.0": "+++\ntitle = \"File Operations and Edit Locking\"\n+++\n\nNot every file operation in Sambee follows the same lifecycle.\n\n## Two Different Operation Families\n\n### Ordinary File Operations\n\nThese are the browser-facing operations such as:\n\n- browse and inspect\n- create and rename\n- copy and move\n- upload and download\n- delete\n\nThese requests usually enter through the browser-facing API and are executed through the backend storage layer.\n\n### Companion-Assisted SMB Editing\n\nThis is the higher-risk path used when a user opens an SMB-backed file in a native desktop app.\n\nThat flow adds:\n\n- token exchange\n- file download to a temp location\n- backend-managed edit locking\n- lock heartbeat and lock-status checks\n- upload or discard decision at the end of editing\n- conflict handling before the server copy is replaced\n\n## Ordinary File Operations\n\nThe browser file-management path depends on typed request models and clear storage semantics.\n\n- copy and move requests use structured request data instead of ad hoc parameters\n- same-path or invalid operations are rejected explicitly\n- server-side copy and move semantics depend on the backend's storage capabilities\n- conflict responses and validation errors are part of the user-visible contract\n\nThe backend should stay authoritative here, even when the frontend tries to make the operation feel immediate.\n\n## Why Edit Locking Exists\n\nNative-app editing of SMB-backed files is a coordination problem, not just a download-and-upload shortcut.\n\nThe backend owns the server-facing lock lifecycle so that:\n\n- concurrent edits are visible and controllable\n- the companion can refresh the lock while editing is still in progress\n- stale or interrupted sessions can be detected\n- conflict decisions happen against the real server state\n\n## High-Level Companion Edit Lifecycle\n\nFor the SMB-backed desktop editing path:\n\n1. the companion exchanges the deep-link token for an authenticated session\n2. it fetches file metadata and downloads the file\n3. it acquires the edit lock from the backend\n4. it keeps the lock alive with heartbeat traffic while the file is open\n5. it uploads the changed file or discards it\n6. it releases the lock and closes out the operation\n\nThe backend is the source of truth for lock state even though the companion is the actor performing the desktop-side work.\n\n## Conflict Handling\n\nBefore a modified file is written back, the system compares the expected server state with the current one.\n\nIf the server copy changed while the user was editing, the companion should not silently overwrite it. That is why conflict handling is part of the backend contract rather than just a local desktop decision.\n\n## Important Distinction: Local Drives\n\nLocal-drive workflows do not use this backend edit-lock lifecycle.\n\n- local files are handled through the paired localhost companion API\n- direct local open can avoid download, lock, upload, and \"Done Editing\" entirely\n- SMB-backed native-app editing still depends on backend lock and upload semantics\n\nDo not blur those two paths when changing edit behavior.\n\n## Adjacent Concern: Freshness after Operations\n\nAfter file operations complete, the browser still needs fresh directory state. That is where change notification and WebSocket refresh behavior become relevant.\n\nOrdinary CRUD operations and companion-assisted edit completion both depend on the rest of the system noticing that directory state has changed.\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npm test\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nChoose the exact subset based on whether the change affects ordinary browser file management, companion editing, or both.\n", "2.0": "+++\ntitle = \"File Operations and Edit Locking\"\n+++\n\nNot every file operation in Sambee follows the same lifecycle.\n\n## Two Different Operation Families\n\n### Ordinary File Operations\n\nThese are the browser-facing operations such as:\n\n- browse and inspect\n- create and rename\n- copy and move\n- upload and download\n- delete\n\nThese requests usually enter through the browser-facing API and are executed through the backend storage layer.\n\n### Companion-Assisted SMB Editing\n\nThis is the higher-risk path used when a user opens an SMB-backed file in a native desktop app.\n\nThat flow adds:\n\n- token exchange\n- file download to a temp location\n- backend-managed edit locking\n- lock heartbeat and lock-status checks\n- upload or discard decision at the end of editing\n- conflict handling before the server copy is replaced\n\n## Ordinary File Operations\n\nThe browser file-management path depends on typed request models and clear storage semantics.\n\n- copy and move requests use structured request data instead of ad hoc parameters\n- same-path or invalid operations are rejected explicitly\n- server-side copy and move semantics depend on the backend's storage capabilities\n- conflict responses and validation errors are part of the user-visible contract\n\nThe backend should stay authoritative here, even when the frontend tries to make the operation feel immediate.\n\n## Why Edit Locking Exists\n\nNative-app editing of SMB-backed files is a coordination problem, not just a download-and-upload shortcut.\n\nThe backend owns the server-facing lock lifecycle so that:\n\n- concurrent edits are visible and controllable\n- the companion can refresh the lock while editing is still in progress\n- stale or interrupted sessions can be detected\n- conflict decisions happen against the real server state\n\n## High-Level Companion Edit Lifecycle\n\nFor the SMB-backed desktop editing path:\n\n1. the companion exchanges the deep-link token for an authenticated session\n2. it fetches file metadata and downloads the file\n3. it acquires the edit lock from the backend\n4. it keeps the lock alive with heartbeat traffic while the file is open\n5. it uploads the changed file or discards it\n6. it releases the lock and closes out the operation\n\nThe backend is the source of truth for lock state even though the companion is the actor performing the desktop-side work.\n\n## Conflict Handling\n\nBefore a modified file is written back, the system compares the expected server state with the current one.\n\nIf the server copy changed while the user was editing, the companion should not silently overwrite it. That is why conflict handling is part of the backend contract rather than just a local desktop decision.\n\n## Important Distinction: Local Drives\n\nLocal-drive workflows do not use this backend edit-lock lifecycle.\n\n- local files are handled through the paired localhost companion API\n- direct local open can avoid download, lock, upload, and \"Done Editing\" entirely\n- SMB-backed native-app editing still depends on backend lock and upload semantics\n\nDo not blur those two paths when changing edit behavior.\n\n## Adjacent Concern: Freshness after Operations\n\nAfter file operations complete, the browser still needs fresh directory state. That is where change notification and WebSocket refresh behavior become relevant.\n\nOrdinary CRUD operations and companion-assisted edit completion both depend on the rest of the system noticing that directory state has changed.\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npm test\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nChoose the exact subset based on whether the change affects ordinary browser file management, companion editing, or both.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:developer-guide/frontend-architecture", "parent_id": "book:developer-guide", "depth": 1, "kind": "section", "label": "frontend-architecture", "title": "Frontend Architecture", "path": "developer-guide/frontend-architecture", "has_children": true, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Frontend Architecture\"\n+++\n\nThe frontend is the primary user-facing product surface. It is where Sambee's browsing, preview, editing, and navigation workflows become visible.\n\nStart with:\n\n- [Frontend Overview](./frontend-overview/)\n- [Theming System and Theme Selection](./theming-system-and-theme-selection/)\n- [File Browser and Navigation Model](./file-browser-and-navigation-model/)\n- [Keyboard Shortcuts and Command Model](./keyboard-shortcuts-and-command-model/)\n- [Viewer Architecture and Preview Contracts](./viewer-architecture-and-preview-contracts/)\n\nUse this section when you need to understand how browser-side behavior connects to the backend and companion.\n", "0.8": "+++\ntitle = \"Frontend Architecture\"\n+++\n\nThe frontend is the primary user-facing product surface. It is where Sambee's browsing, preview, editing, and navigation workflows become visible.\n\nStart with:\n\n- [Frontend Overview](./frontend-overview/)\n- [Theming System and Theme Selection](./theming-system-and-theme-selection/)\n- [File Browser and Navigation Model](./file-browser-and-navigation-model/)\n- [Keyboard Shortcuts and Command Model](./keyboard-shortcuts-and-command-model/)\n- [Viewer Architecture and Preview Contracts](./viewer-architecture-and-preview-contracts/)\n\nUse this section when you need to understand how browser-side behavior connects to the backend and companion.\n", "0.9": "+++\ntitle = \"Frontend Architecture\"\n+++\n\nThe frontend is the primary user-facing product surface. It is where Sambee's browsing, preview, editing, and navigation workflows become visible.\n\nStart with:\n\n- [Frontend Overview](./frontend-overview/)\n- [Theming System and Theme Selection](./theming-system-and-theme-selection/)\n- [File Browser and Navigation Model](./file-browser-and-navigation-model/)\n- [Keyboard Shortcuts and Command Model](./keyboard-shortcuts-and-command-model/)\n- [Viewer Architecture and Preview Contracts](./viewer-architecture-and-preview-contracts/)\n\nUse this section when you need to understand how browser-side behavior connects to the backend and companion.\n", "1.0": "+++\ntitle = \"Frontend Architecture\"\n+++\n\nThe frontend is the primary user-facing product surface. It is where Sambee's browsing, preview, editing, and navigation workflows become visible.\n\nStart with:\n\n- [Frontend Overview](./frontend-overview/)\n- [Theming System and Theme Selection](./theming-system-and-theme-selection/)\n- [File Browser and Navigation Model](./file-browser-and-navigation-model/)\n- [Keyboard Shortcuts and Command Model](./keyboard-shortcuts-and-command-model/)\n- [Viewer Architecture and Preview Contracts](./viewer-architecture-and-preview-contracts/)\n\nUse this section when you need to understand how browser-side behavior connects to the backend and companion.\n", "2.0": "+++\ntitle = \"Frontend Architecture\"\n+++\n\nThe frontend is the primary user-facing product surface. It is where Sambee's browsing, preview, editing, and navigation workflows become visible.\n\nStart with:\n\n- [Frontend Overview](./frontend-overview/)\n- [Theming System and Theme Selection](./theming-system-and-theme-selection/)\n- [File Browser and Navigation Model](./file-browser-and-navigation-model/)\n- [Keyboard Shortcuts and Command Model](./keyboard-shortcuts-and-command-model/)\n- [Viewer Architecture and Preview Contracts](./viewer-architecture-and-preview-contracts/)\n\nUse this section when you need to understand how browser-side behavior connects to the backend and companion.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/frontend-architecture/frontend-overview", "parent_id": "section:developer-guide/frontend-architecture", "depth": 2, "kind": "page", "label": "frontend-overview", "title": "Frontend Overview", "path": "developer-guide/frontend-architecture/frontend-overview", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Frontend Overview\"\n+++\n\nThe frontend is a React and TypeScript application built with Vite. It is responsible for presenting Sambee's workflows clearly while respecting the backend and companion contracts behind them.\n\n## What the Frontend Owns\n\nThe browser app is responsible for:\n\n- routing users into the main product surfaces\n- rendering the file browser, viewer, and editing flows\n- managing browser-side state, selection, and navigation behavior\n- calling backend and companion-facing services through typed client code\n- applying theming, localization, and browser-side logging behavior\n\n## Main Frontend Areas\n\n| Area | Responsibility |\n|---|---|\n| `frontend/src/pages/` | page-level product flows such as the file browser |\n| `frontend/src/components/` | reusable UI building blocks |\n| `frontend/src/services/` | API clients, browser-to-companion integration, and other service helpers |\n| `frontend/src/i18n/` | typed translation resources and locale wiring |\n| `frontend/src/theme/` | theme configuration and theme-selection behavior |\n| `frontend/src/utils/` | formatting, registry, and other supporting utilities |\n\n## File Browser as the Core Surface\n\nThe file browser is the center of the main product UI.\n\n- it supports single-pane and dual-pane workflows\n- it keeps layout state and pane routing aligned with the URL\n- it coordinates selection, search, sorting, CRUD actions, viewer state, and keyboard behavior\n- it handles WebSocket-driven directory refresh behavior\n\nThat is why frontend changes in the file browser often have broader user impact than they first appear to.\n\nFor the main browsing surface itself, continue to [File Browser and Navigation Model](../file-browser-and-navigation-model/).\n\n## Frontend Contracts That Matter\n\n### Backend Contracts\n\nThe frontend depends on stable backend response shapes. When those change, update the corresponding types, service logic, and contract tests together.\n\n### Companion Contracts\n\nThe frontend is also the browser-side orchestrator for companion detection, pairing, local-drive access, and native-app editing initiation. That means browser-side state and desktop-side behavior are tightly linked even though they live in different projects.\n\n### Theming and Localization\n\nThe app treats theme behavior and localization as typed, explicit systems rather than loose UI sugar.\n\n- frontend copy should come from the translation system\n- locale handling and regional formatting are treated as product behavior\n- theme behavior is centralized instead of ad hoc component styling\n\n## Cross-Cutting Frontend Concerns\n\n- keyboard-first browsing and command surfaces\n- typed logging and backend tracing configuration\n- viewer behavior by file type and preview capability\n- responsive behavior, including mobile limitations and dual-pane desktop features\n\n## Rendering Hazards and Prevention Rules\n\nThis codebase has already hit at least one subtle React rendering failure where the app was logically correct but the browser still lost the first user click.\n\nThe useful lesson is that React rendering behavior, native event timing, portal trees, and third-party props can interact in ways that are easy to miss during normal component-level work.\n\n### Representative Failure Mode\n\nOne real frontend regression affected Markdown links inside the viewer.\n\n- links in the Markdown viewer ignored the first click when the viewer had been opened via keyboard\n- the second click worked\n- opening the viewer via mouse did not reproduce the problem\n\nThe root cause was not a single bad line. It was the combination of several implementation details:\n\n1. a global capture-phase `pointerdown` handler in `FileBrowser.tsx` updated keyboard-versus-pointer focus state synchronously\n2. React treated that update as a discrete-event flush and applied it between `pointerdown` and `click`\n3. the viewer shell was still expensive enough that the re-render cascaded through the portal-rendered viewer tree\n4. `react-markdown` override props included a `node` value that would have been dangerous to spread onto a native DOM anchor\n\nThe current code fixes that by deferring the focus-state update with `requestAnimationFrame`, memoizing the dynamic viewer shell, and stripping `node` out of the Markdown link override before spreading the remaining props.\n\n### Why This Class of Bug Matters\n\nThis kind of problem is easy to underestimate because:\n\n- it can be input-mode specific rather than globally reproducible\n- it may only appear when several otherwise-correct abstractions interact\n- the visible symptom can look like a browser bug or flaky click handling when the real cause is a mid-event re-render\n\nContributors should treat event timing and render isolation as architecture concerns, not just local component details.\n\n### Prevention Rules\n\n#### 1. Do Not Trigger Synchronous State Changes in Capture-Phase Pointer Handlers Unless Necessary\n\nCapture-phase `pointerdown` and `mousedown` handlers can run before the click sequence finishes. If they trigger state updates synchronously, React can re-render in the middle of the browser's interaction pipeline.\n\nWhen the state change is not required immediately, defer it past the current event cycle with `requestAnimationFrame`.\n\n#### 2. Keep Portal-Rendered Viewer Surfaces Render-Isolated\n\nViewer trees rendered through dialogs or other portals should not re-render just because an unrelated parent concern changed.\n\nIn practice this means:\n\n- memoize portal-rendered viewer shells when they are intended to be stable\n- be skeptical of parent state changes that can cascade into the viewer tree during active pointer interaction\n- review viewer wrappers such as `DynamicViewer` with the same care as the concrete viewer components themselves\n\n#### 3. Never Blindly Spread Third-Party Props onto Native DOM Elements\n\nLibraries such as `react-markdown` can inject props that are valid for the library layer but unsafe for direct DOM output.\n\nWhen overriding renderers:\n\n- explicitly destructure library-only props such as `node`\n- spread only the remaining DOM-safe props onto native elements\n- assume that leaking unknown props onto the interaction target can change browser behavior in ways that are hard to diagnose\n\n### Practical Audit Checks\n\nWhen debugging or reviewing similar issues, use targeted searches like these:\n\n```bash\ngrep -rn 'addEventListener.*capture' frontend/src/\ngrep -rn '\\.\\.\\.props' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/FileBrowser/DynamicViewer.tsx\n```\n\nThese are not exhaustive audits, but they are good first-pass checks for the specific failure pattern this codebase has already seen.\n\n## Go Deeper\n\n- [Theming System and Theme Selection](../theming-system-and-theme-selection/): theme configuration, built-in themes, persistence, and how the UI switches themes\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL routing, keyboard flows, and refresh behavior\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): central shortcut definitions, browser commands, quick-bar modes, and context-aware handlers\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): file-type registries, preview selection, and conversion-sensitive viewer behavior\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared frontend-facing rules for diagnostics, translatable UI copy, and locale behavior\n\n## Validation Expectations\n\nWhen frontend behavior changes, start with:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change also affects backend or companion contracts, add the matching checks there too.\n", "0.8": "+++\ntitle = \"Frontend Overview\"\n+++\n\nThe frontend is a React and TypeScript application built with Vite. It is responsible for presenting Sambee's workflows clearly while respecting the backend and companion contracts behind them.\n\n## What the Frontend Owns\n\nThe browser app is responsible for:\n\n- routing users into the main product surfaces\n- rendering the file browser, viewer, and editing flows\n- managing browser-side state, selection, and navigation behavior\n- calling backend and companion-facing services through typed client code\n- applying theming, localization, and browser-side logging behavior\n\n## Main Frontend Areas\n\n| Area | Responsibility |\n|---|---|\n| `frontend/src/pages/` | page-level product flows such as the file browser |\n| `frontend/src/components/` | reusable UI building blocks |\n| `frontend/src/services/` | API clients, browser-to-companion integration, and other service helpers |\n| `frontend/src/i18n/` | typed translation resources and locale wiring |\n| `frontend/src/theme/` | theme configuration and theme-selection behavior |\n| `frontend/src/utils/` | formatting, registry, and other supporting utilities |\n\n## File Browser as the Core Surface\n\nThe file browser is the center of the main product UI.\n\n- it supports single-pane and dual-pane workflows\n- it keeps layout state and pane routing aligned with the URL\n- it coordinates selection, search, sorting, CRUD actions, viewer state, and keyboard behavior\n- it handles WebSocket-driven directory refresh behavior\n\nThat is why frontend changes in the file browser often have broader user impact than they first appear to.\n\nFor the main browsing surface itself, continue to [File Browser and Navigation Model](../file-browser-and-navigation-model/).\n\n## Frontend Contracts That Matter\n\n### Backend Contracts\n\nThe frontend depends on stable backend response shapes. When those change, update the corresponding types, service logic, and contract tests together.\n\n### Companion Contracts\n\nThe frontend is also the browser-side orchestrator for companion detection, pairing, local-drive access, and native-app editing initiation. That means browser-side state and desktop-side behavior are tightly linked even though they live in different projects.\n\n### Theming and Localization\n\nThe app treats theme behavior and localization as typed, explicit systems rather than loose UI sugar.\n\n- frontend copy should come from the translation system\n- locale handling and regional formatting are treated as product behavior\n- theme behavior is centralized instead of ad hoc component styling\n\n## Cross-Cutting Frontend Concerns\n\n- keyboard-first browsing and command surfaces\n- typed logging and backend tracing configuration\n- viewer behavior by file type and preview capability\n- responsive behavior, including mobile limitations and dual-pane desktop features\n\n## Rendering Hazards and Prevention Rules\n\nThis codebase has already hit at least one subtle React rendering failure where the app was logically correct but the browser still lost the first user click.\n\nThe useful lesson is that React rendering behavior, native event timing, portal trees, and third-party props can interact in ways that are easy to miss during normal component-level work.\n\n### Representative Failure Mode\n\nOne real frontend regression affected Markdown links inside the viewer.\n\n- links in the Markdown viewer ignored the first click when the viewer had been opened via keyboard\n- the second click worked\n- opening the viewer via mouse did not reproduce the problem\n\nThe root cause was not a single bad line. It was the combination of several implementation details:\n\n1. a global capture-phase `pointerdown` handler in `FileBrowser.tsx` updated keyboard-versus-pointer focus state synchronously\n2. React treated that update as a discrete-event flush and applied it between `pointerdown` and `click`\n3. the viewer shell was still expensive enough that the re-render cascaded through the portal-rendered viewer tree\n4. `react-markdown` override props included a `node` value that would have been dangerous to spread onto a native DOM anchor\n\nThe current code fixes that by deferring the focus-state update with `requestAnimationFrame`, memoizing the dynamic viewer shell, and stripping `node` out of the Markdown link override before spreading the remaining props.\n\n### Why This Class of Bug Matters\n\nThis kind of problem is easy to underestimate because:\n\n- it can be input-mode specific rather than globally reproducible\n- it may only appear when several otherwise-correct abstractions interact\n- the visible symptom can look like a browser bug or flaky click handling when the real cause is a mid-event re-render\n\nContributors should treat event timing and render isolation as architecture concerns, not just local component details.\n\n### Prevention Rules\n\n#### 1. Do Not Trigger Synchronous State Changes in Capture-Phase Pointer Handlers Unless Necessary\n\nCapture-phase `pointerdown` and `mousedown` handlers can run before the click sequence finishes. If they trigger state updates synchronously, React can re-render in the middle of the browser's interaction pipeline.\n\nWhen the state change is not required immediately, defer it past the current event cycle with `requestAnimationFrame`.\n\n#### 2. Keep Portal-Rendered Viewer Surfaces Render-Isolated\n\nViewer trees rendered through dialogs or other portals should not re-render just because an unrelated parent concern changed.\n\nIn practice this means:\n\n- memoize portal-rendered viewer shells when they are intended to be stable\n- be skeptical of parent state changes that can cascade into the viewer tree during active pointer interaction\n- review viewer wrappers such as `DynamicViewer` with the same care as the concrete viewer components themselves\n\n#### 3. Never Blindly Spread Third-Party Props onto Native DOM Elements\n\nLibraries such as `react-markdown` can inject props that are valid for the library layer but unsafe for direct DOM output.\n\nWhen overriding renderers:\n\n- explicitly destructure library-only props such as `node`\n- spread only the remaining DOM-safe props onto native elements\n- assume that leaking unknown props onto the interaction target can change browser behavior in ways that are hard to diagnose\n\n### Practical Audit Checks\n\nWhen debugging or reviewing similar issues, use targeted searches like these:\n\n```bash\ngrep -rn 'addEventListener.*capture' frontend/src/\ngrep -rn '\\.\\.\\.props' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/FileBrowser/DynamicViewer.tsx\n```\n\nThese are not exhaustive audits, but they are good first-pass checks for the specific failure pattern this codebase has already seen.\n\n## Go Deeper\n\n- [Theming System and Theme Selection](../theming-system-and-theme-selection/): theme configuration, built-in themes, persistence, and how the UI switches themes\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL routing, keyboard flows, and refresh behavior\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): central shortcut definitions, browser commands, quick-bar modes, and context-aware handlers\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): file-type registries, preview selection, and conversion-sensitive viewer behavior\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared frontend-facing rules for diagnostics, translatable UI copy, and locale behavior\n\n## Validation Expectations\n\nWhen frontend behavior changes, start with:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change also affects backend or companion contracts, add the matching checks there too.\n", "0.9": "+++\ntitle = \"Frontend Overview\"\n+++\n\nThe frontend is a React and TypeScript application built with Vite. It is responsible for presenting Sambee's workflows clearly while respecting the backend and companion contracts behind them.\n\n## What the Frontend Owns\n\nThe browser app is responsible for:\n\n- routing users into the main product surfaces\n- rendering the file browser, viewer, and editing flows\n- managing browser-side state, selection, and navigation behavior\n- calling backend and companion-facing services through typed client code\n- applying theming, localization, and browser-side logging behavior\n\n## Main Frontend Areas\n\n| Area | Responsibility |\n|---|---|\n| `frontend/src/pages/` | page-level product flows such as the file browser |\n| `frontend/src/components/` | reusable UI building blocks |\n| `frontend/src/services/` | API clients, browser-to-companion integration, and other service helpers |\n| `frontend/src/i18n/` | typed translation resources and locale wiring |\n| `frontend/src/theme/` | theme configuration and theme-selection behavior |\n| `frontend/src/utils/` | formatting, registry, and other supporting utilities |\n\n## File Browser as the Core Surface\n\nThe file browser is the center of the main product UI.\n\n- it supports single-pane and dual-pane workflows\n- it keeps layout state and pane routing aligned with the URL\n- it coordinates selection, search, sorting, CRUD actions, viewer state, and keyboard behavior\n- it handles WebSocket-driven directory refresh behavior\n\nThat is why frontend changes in the file browser often have broader user impact than they first appear to.\n\nFor the main browsing surface itself, continue to [File Browser and Navigation Model](../file-browser-and-navigation-model/).\n\n## Frontend Contracts That Matter\n\n### Backend Contracts\n\nThe frontend depends on stable backend response shapes. When those change, update the corresponding types, service logic, and contract tests together.\n\n### Companion Contracts\n\nThe frontend is also the browser-side orchestrator for companion detection, pairing, local-drive access, and native-app editing initiation. That means browser-side state and desktop-side behavior are tightly linked even though they live in different projects.\n\n### Theming and Localization\n\nThe app treats theme behavior and localization as typed, explicit systems rather than loose UI sugar.\n\n- frontend copy should come from the translation system\n- locale handling and regional formatting are treated as product behavior\n- theme behavior is centralized instead of ad hoc component styling\n\n## Cross-Cutting Frontend Concerns\n\n- keyboard-first browsing and command surfaces\n- typed logging and backend tracing configuration\n- viewer behavior by file type and preview capability\n- responsive behavior, including mobile limitations and dual-pane desktop features\n\n## Rendering Hazards and Prevention Rules\n\nThis codebase has already hit at least one subtle React rendering failure where the app was logically correct but the browser still lost the first user click.\n\nThe useful lesson is that React rendering behavior, native event timing, portal trees, and third-party props can interact in ways that are easy to miss during normal component-level work.\n\n### Representative Failure Mode\n\nOne real frontend regression affected Markdown links inside the viewer.\n\n- links in the Markdown viewer ignored the first click when the viewer had been opened via keyboard\n- the second click worked\n- opening the viewer via mouse did not reproduce the problem\n\nThe root cause was not a single bad line. It was the combination of several implementation details:\n\n1. a global capture-phase `pointerdown` handler in `FileBrowser.tsx` updated keyboard-versus-pointer focus state synchronously\n2. React treated that update as a discrete-event flush and applied it between `pointerdown` and `click`\n3. the viewer shell was still expensive enough that the re-render cascaded through the portal-rendered viewer tree\n4. `react-markdown` override props included a `node` value that would have been dangerous to spread onto a native DOM anchor\n\nThe current code fixes that by deferring the focus-state update with `requestAnimationFrame`, memoizing the dynamic viewer shell, and stripping `node` out of the Markdown link override before spreading the remaining props.\n\n### Why This Class of Bug Matters\n\nThis kind of problem is easy to underestimate because:\n\n- it can be input-mode specific rather than globally reproducible\n- it may only appear when several otherwise-correct abstractions interact\n- the visible symptom can look like a browser bug or flaky click handling when the real cause is a mid-event re-render\n\nContributors should treat event timing and render isolation as architecture concerns, not just local component details.\n\n### Prevention Rules\n\n#### 1. Do Not Trigger Synchronous State Changes in Capture-Phase Pointer Handlers Unless Necessary\n\nCapture-phase `pointerdown` and `mousedown` handlers can run before the click sequence finishes. If they trigger state updates synchronously, React can re-render in the middle of the browser's interaction pipeline.\n\nWhen the state change is not required immediately, defer it past the current event cycle with `requestAnimationFrame`.\n\n#### 2. Keep Portal-Rendered Viewer Surfaces Render-Isolated\n\nViewer trees rendered through dialogs or other portals should not re-render just because an unrelated parent concern changed.\n\nIn practice this means:\n\n- memoize portal-rendered viewer shells when they are intended to be stable\n- be skeptical of parent state changes that can cascade into the viewer tree during active pointer interaction\n- review viewer wrappers such as `DynamicViewer` with the same care as the concrete viewer components themselves\n\n#### 3. Never Blindly Spread Third-Party Props onto Native DOM Elements\n\nLibraries such as `react-markdown` can inject props that are valid for the library layer but unsafe for direct DOM output.\n\nWhen overriding renderers:\n\n- explicitly destructure library-only props such as `node`\n- spread only the remaining DOM-safe props onto native elements\n- assume that leaking unknown props onto the interaction target can change browser behavior in ways that are hard to diagnose\n\n### Practical Audit Checks\n\nWhen debugging or reviewing similar issues, use targeted searches like these:\n\n```bash\ngrep -rn 'addEventListener.*capture' frontend/src/\ngrep -rn '\\.\\.\\.props' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/FileBrowser/DynamicViewer.tsx\n```\n\nThese are not exhaustive audits, but they are good first-pass checks for the specific failure pattern this codebase has already seen.\n\n## Go Deeper\n\n- [Theming System and Theme Selection](../theming-system-and-theme-selection/): theme configuration, built-in themes, persistence, and how the UI switches themes\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL routing, keyboard flows, and refresh behavior\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): central shortcut definitions, browser commands, quick-bar modes, and context-aware handlers\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): file-type registries, preview selection, and conversion-sensitive viewer behavior\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared frontend-facing rules for diagnostics, translatable UI copy, and locale behavior\n\n## Validation Expectations\n\nWhen frontend behavior changes, start with:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change also affects backend or companion contracts, add the matching checks there too.\n", "1.0": "+++\ntitle = \"Frontend Overview\"\n+++\n\nThe frontend is a React and TypeScript application built with Vite. It is responsible for presenting Sambee's workflows clearly while respecting the backend and companion contracts behind them.\n\n## What the Frontend Owns\n\nThe browser app is responsible for:\n\n- routing users into the main product surfaces\n- rendering the file browser, viewer, and editing flows\n- managing browser-side state, selection, and navigation behavior\n- calling backend and companion-facing services through typed client code\n- applying theming, localization, and browser-side logging behavior\n\n## Main Frontend Areas\n\n| Area | Responsibility |\n|---|---|\n| `frontend/src/pages/` | page-level product flows such as the file browser |\n| `frontend/src/components/` | reusable UI building blocks |\n| `frontend/src/services/` | API clients, browser-to-companion integration, and other service helpers |\n| `frontend/src/i18n/` | typed translation resources and locale wiring |\n| `frontend/src/theme/` | theme configuration and theme-selection behavior |\n| `frontend/src/utils/` | formatting, registry, and other supporting utilities |\n\n## File Browser as the Core Surface\n\nThe file browser is the center of the main product UI.\n\n- it supports single-pane and dual-pane workflows\n- it keeps layout state and pane routing aligned with the URL\n- it coordinates selection, search, sorting, CRUD actions, viewer state, and keyboard behavior\n- it handles WebSocket-driven directory refresh behavior\n\nThat is why frontend changes in the file browser often have broader user impact than they first appear to.\n\nFor the main browsing surface itself, continue to [File Browser and Navigation Model](../file-browser-and-navigation-model/).\n\n## Frontend Contracts That Matter\n\n### Backend Contracts\n\nThe frontend depends on stable backend response shapes. When those change, update the corresponding types, service logic, and contract tests together.\n\n### Companion Contracts\n\nThe frontend is also the browser-side orchestrator for companion detection, pairing, local-drive access, and native-app editing initiation. That means browser-side state and desktop-side behavior are tightly linked even though they live in different projects.\n\n### Theming and Localization\n\nThe app treats theme behavior and localization as typed, explicit systems rather than loose UI sugar.\n\n- frontend copy should come from the translation system\n- locale handling and regional formatting are treated as product behavior\n- theme behavior is centralized instead of ad hoc component styling\n\n## Cross-Cutting Frontend Concerns\n\n- keyboard-first browsing and command surfaces\n- typed logging and backend tracing configuration\n- viewer behavior by file type and preview capability\n- responsive behavior, including mobile limitations and dual-pane desktop features\n\n## Rendering Hazards and Prevention Rules\n\nThis codebase has already hit at least one subtle React rendering failure where the app was logically correct but the browser still lost the first user click.\n\nThe useful lesson is that React rendering behavior, native event timing, portal trees, and third-party props can interact in ways that are easy to miss during normal component-level work.\n\n### Representative Failure Mode\n\nOne real frontend regression affected Markdown links inside the viewer.\n\n- links in the Markdown viewer ignored the first click when the viewer had been opened via keyboard\n- the second click worked\n- opening the viewer via mouse did not reproduce the problem\n\nThe root cause was not a single bad line. It was the combination of several implementation details:\n\n1. a global capture-phase `pointerdown` handler in `FileBrowser.tsx` updated keyboard-versus-pointer focus state synchronously\n2. React treated that update as a discrete-event flush and applied it between `pointerdown` and `click`\n3. the viewer shell was still expensive enough that the re-render cascaded through the portal-rendered viewer tree\n4. `react-markdown` override props included a `node` value that would have been dangerous to spread onto a native DOM anchor\n\nThe current code fixes that by deferring the focus-state update with `requestAnimationFrame`, memoizing the dynamic viewer shell, and stripping `node` out of the Markdown link override before spreading the remaining props.\n\n### Why This Class of Bug Matters\n\nThis kind of problem is easy to underestimate because:\n\n- it can be input-mode specific rather than globally reproducible\n- it may only appear when several otherwise-correct abstractions interact\n- the visible symptom can look like a browser bug or flaky click handling when the real cause is a mid-event re-render\n\nContributors should treat event timing and render isolation as architecture concerns, not just local component details.\n\n### Prevention Rules\n\n#### 1. Do Not Trigger Synchronous State Changes in Capture-Phase Pointer Handlers Unless Necessary\n\nCapture-phase `pointerdown` and `mousedown` handlers can run before the click sequence finishes. If they trigger state updates synchronously, React can re-render in the middle of the browser's interaction pipeline.\n\nWhen the state change is not required immediately, defer it past the current event cycle with `requestAnimationFrame`.\n\n#### 2. Keep Portal-Rendered Viewer Surfaces Render-Isolated\n\nViewer trees rendered through dialogs or other portals should not re-render just because an unrelated parent concern changed.\n\nIn practice this means:\n\n- memoize portal-rendered viewer shells when they are intended to be stable\n- be skeptical of parent state changes that can cascade into the viewer tree during active pointer interaction\n- review viewer wrappers such as `DynamicViewer` with the same care as the concrete viewer components themselves\n\n#### 3. Never Blindly Spread Third-Party Props onto Native DOM Elements\n\nLibraries such as `react-markdown` can inject props that are valid for the library layer but unsafe for direct DOM output.\n\nWhen overriding renderers:\n\n- explicitly destructure library-only props such as `node`\n- spread only the remaining DOM-safe props onto native elements\n- assume that leaking unknown props onto the interaction target can change browser behavior in ways that are hard to diagnose\n\n### Practical Audit Checks\n\nWhen debugging or reviewing similar issues, use targeted searches like these:\n\n```bash\ngrep -rn 'addEventListener.*capture' frontend/src/\ngrep -rn '\\.\\.\\.props' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/FileBrowser/DynamicViewer.tsx\n```\n\nThese are not exhaustive audits, but they are good first-pass checks for the specific failure pattern this codebase has already seen.\n\n## Go Deeper\n\n- [Theming System and Theme Selection](../theming-system-and-theme-selection/): theme configuration, built-in themes, persistence, and how the UI switches themes\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL routing, keyboard flows, and refresh behavior\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): central shortcut definitions, browser commands, quick-bar modes, and context-aware handlers\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): file-type registries, preview selection, and conversion-sensitive viewer behavior\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared frontend-facing rules for diagnostics, translatable UI copy, and locale behavior\n\n## Validation Expectations\n\nWhen frontend behavior changes, start with:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change also affects backend or companion contracts, add the matching checks there too.\n", "2.0": "+++\ntitle = \"Frontend Overview\"\n+++\n\nThe frontend is a React and TypeScript application built with Vite. It is responsible for presenting Sambee's workflows clearly while respecting the backend and companion contracts behind them.\n\n## What the Frontend Owns\n\nThe browser app is responsible for:\n\n- routing users into the main product surfaces\n- rendering the file browser, viewer, and editing flows\n- managing browser-side state, selection, and navigation behavior\n- calling backend and companion-facing services through typed client code\n- applying theming, localization, and browser-side logging behavior\n\n## Main Frontend Areas\n\n| Area | Responsibility |\n|---|---|\n| `frontend/src/pages/` | page-level product flows such as the file browser |\n| `frontend/src/components/` | reusable UI building blocks |\n| `frontend/src/services/` | API clients, browser-to-companion integration, and other service helpers |\n| `frontend/src/i18n/` | typed translation resources and locale wiring |\n| `frontend/src/theme/` | theme configuration and theme-selection behavior |\n| `frontend/src/utils/` | formatting, registry, and other supporting utilities |\n\n## File Browser as the Core Surface\n\nThe file browser is the center of the main product UI.\n\n- it supports single-pane and dual-pane workflows\n- it keeps layout state and pane routing aligned with the URL\n- it coordinates selection, search, sorting, CRUD actions, viewer state, and keyboard behavior\n- it handles WebSocket-driven directory refresh behavior\n\nThat is why frontend changes in the file browser often have broader user impact than they first appear to.\n\nFor the main browsing surface itself, continue to [File Browser and Navigation Model](../file-browser-and-navigation-model/).\n\n## Frontend Contracts That Matter\n\n### Backend Contracts\n\nThe frontend depends on stable backend response shapes. When those change, update the corresponding types, service logic, and contract tests together.\n\n### Companion Contracts\n\nThe frontend is also the browser-side orchestrator for companion detection, pairing, local-drive access, and native-app editing initiation. That means browser-side state and desktop-side behavior are tightly linked even though they live in different projects.\n\n### Theming and Localization\n\nThe app treats theme behavior and localization as typed, explicit systems rather than loose UI sugar.\n\n- frontend copy should come from the translation system\n- locale handling and regional formatting are treated as product behavior\n- theme behavior is centralized instead of ad hoc component styling\n\n## Cross-Cutting Frontend Concerns\n\n- keyboard-first browsing and command surfaces\n- typed logging and backend tracing configuration\n- viewer behavior by file type and preview capability\n- responsive behavior, including mobile limitations and dual-pane desktop features\n\n## Rendering Hazards and Prevention Rules\n\nThis codebase has already hit at least one subtle React rendering failure where the app was logically correct but the browser still lost the first user click.\n\nThe useful lesson is that React rendering behavior, native event timing, portal trees, and third-party props can interact in ways that are easy to miss during normal component-level work.\n\n### Representative Failure Mode\n\nOne real frontend regression affected Markdown links inside the viewer.\n\n- links in the Markdown viewer ignored the first click when the viewer had been opened via keyboard\n- the second click worked\n- opening the viewer via mouse did not reproduce the problem\n\nThe root cause was not a single bad line. It was the combination of several implementation details:\n\n1. a global capture-phase `pointerdown` handler in `FileBrowser.tsx` updated keyboard-versus-pointer focus state synchronously\n2. React treated that update as a discrete-event flush and applied it between `pointerdown` and `click`\n3. the viewer shell was still expensive enough that the re-render cascaded through the portal-rendered viewer tree\n4. `react-markdown` override props included a `node` value that would have been dangerous to spread onto a native DOM anchor\n\nThe current code fixes that by deferring the focus-state update with `requestAnimationFrame`, memoizing the dynamic viewer shell, and stripping `node` out of the Markdown link override before spreading the remaining props.\n\n### Why This Class of Bug Matters\n\nThis kind of problem is easy to underestimate because:\n\n- it can be input-mode specific rather than globally reproducible\n- it may only appear when several otherwise-correct abstractions interact\n- the visible symptom can look like a browser bug or flaky click handling when the real cause is a mid-event re-render\n\nContributors should treat event timing and render isolation as architecture concerns, not just local component details.\n\n### Prevention Rules\n\n#### 1. Do Not Trigger Synchronous State Changes in Capture-Phase Pointer Handlers Unless Necessary\n\nCapture-phase `pointerdown` and `mousedown` handlers can run before the click sequence finishes. If they trigger state updates synchronously, React can re-render in the middle of the browser's interaction pipeline.\n\nWhen the state change is not required immediately, defer it past the current event cycle with `requestAnimationFrame`.\n\n#### 2. Keep Portal-Rendered Viewer Surfaces Render-Isolated\n\nViewer trees rendered through dialogs or other portals should not re-render just because an unrelated parent concern changed.\n\nIn practice this means:\n\n- memoize portal-rendered viewer shells when they are intended to be stable\n- be skeptical of parent state changes that can cascade into the viewer tree during active pointer interaction\n- review viewer wrappers such as `DynamicViewer` with the same care as the concrete viewer components themselves\n\n#### 3. Never Blindly Spread Third-Party Props onto Native DOM Elements\n\nLibraries such as `react-markdown` can inject props that are valid for the library layer but unsafe for direct DOM output.\n\nWhen overriding renderers:\n\n- explicitly destructure library-only props such as `node`\n- spread only the remaining DOM-safe props onto native elements\n- assume that leaking unknown props onto the interaction target can change browser behavior in ways that are hard to diagnose\n\n### Practical Audit Checks\n\nWhen debugging or reviewing similar issues, use targeted searches like these:\n\n```bash\ngrep -rn 'addEventListener.*capture' frontend/src/\ngrep -rn '\\.\\.\\.props' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/FileBrowser/DynamicViewer.tsx\n```\n\nThese are not exhaustive audits, but they are good first-pass checks for the specific failure pattern this codebase has already seen.\n\n## Go Deeper\n\n- [Theming System and Theme Selection](../theming-system-and-theme-selection/): theme configuration, built-in themes, persistence, and how the UI switches themes\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL routing, keyboard flows, and refresh behavior\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): central shortcut definitions, browser commands, quick-bar modes, and context-aware handlers\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): file-type registries, preview selection, and conversion-sensitive viewer behavior\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared frontend-facing rules for diagnostics, translatable UI copy, and locale behavior\n\n## Validation Expectations\n\nWhen frontend behavior changes, start with:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change also affects backend or companion contracts, add the matching checks there too.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Frontend Overview\"\n+++\n\nThe frontend is a React and TypeScript application built with Vite. It is responsible for presenting Sambee's workflows clearly while respecting the backend and companion contracts behind them.\n\n## What the Frontend Owns\n\nThe browser app is responsible for:\n\n- routing users into the main product surfaces\n- rendering the file browser, viewer, and editing flows\n- managing browser-side state, selection, and navigation behavior\n- calling backend and companion-facing services through typed client code\n- applying theming, localization, and browser-side logging behavior\n\n## Main Frontend Areas\n\n| Area | Responsibility |\n|---|---|\n| `frontend/src/pages/` | page-level product flows such as the file browser |\n| `frontend/src/components/` | reusable UI building blocks |\n| `frontend/src/services/` | API clients, browser-to-companion integration, and other service helpers |\n| `frontend/src/i18n/` | typed translation resources and locale wiring |\n| `frontend/src/theme/` | theme configuration and theme-selection behavior |\n| `frontend/src/utils/` | formatting, registry, and other supporting utilities |\n\n## File Browser as the Core Surface\n\nThe file browser is the center of the main product UI.\n\n- it supports single-pane and dual-pane workflows\n- it keeps layout state and pane routing aligned with the URL\n- it coordinates selection, search, sorting, CRUD actions, viewer state, and keyboard behavior\n- it handles WebSocket-driven directory refresh behavior\n\nThat is why frontend changes in the file browser often have broader user impact than they first appear to.\n\nFor the main browsing surface itself, continue to [File Browser and Navigation Model](../file-browser-and-navigation-model/).\n\n## Frontend Contracts That Matter\n\n### Backend Contracts\n\nThe frontend depends on stable backend response shapes. When those change, update the corresponding types, service logic, and contract tests together.\n\n### Companion Contracts\n\nThe frontend is also the browser-side orchestrator for companion detection, pairing, local-drive access, and native-app editing initiation. That means browser-side state and desktop-side behavior are tightly linked even though they live in different projects.\n\n### Theming and Localization\n\nThe app treats theme behavior and localization as typed, explicit systems rather than loose UI sugar.\n\n- frontend copy should come from the translation system\n- locale handling and regional formatting are treated as product behavior\n- theme behavior is centralized instead of ad hoc component styling\n\n## Cross-Cutting Frontend Concerns\n\n- keyboard-first browsing and command surfaces\n- typed logging and backend tracing configuration\n- viewer behavior by file type and preview capability\n- responsive behavior, including mobile limitations and dual-pane desktop features\n\n## Rendering Hazards and Prevention Rules\n\nThis codebase has already hit at least one subtle React rendering failure where the app was logically correct but the browser still lost the first user click.\n\nThe useful lesson is that React rendering behavior, native event timing, portal trees, and third-party props can interact in ways that are easy to miss during normal component-level work.\n\n### Representative Failure Mode\n\nOne real frontend regression affected Markdown links inside the viewer.\n\n- links in the Markdown viewer ignored the first click when the viewer had been opened via keyboard\n- the second click worked\n- opening the viewer via mouse did not reproduce the problem\n\nThe root cause was not a single bad line. It was the combination of several implementation details:\n\n1. a global capture-phase `pointerdown` handler in `FileBrowser.tsx` updated keyboard-versus-pointer focus state synchronously\n2. React treated that update as a discrete-event flush and applied it between `pointerdown` and `click`\n3. the viewer shell was still expensive enough that the re-render cascaded through the portal-rendered viewer tree\n4. `react-markdown` override props included a `node` value that would have been dangerous to spread onto a native DOM anchor\n\nThe current code fixes that by deferring the focus-state update with `requestAnimationFrame`, memoizing the dynamic viewer shell, and stripping `node` out of the Markdown link override before spreading the remaining props.\n\n### Why This Class of Bug Matters\n\nThis kind of problem is easy to underestimate because:\n\n- it can be input-mode specific rather than globally reproducible\n- it may only appear when several otherwise-correct abstractions interact\n- the visible symptom can look like a browser bug or flaky click handling when the real cause is a mid-event re-render\n\nContributors should treat event timing and render isolation as architecture concerns, not just local component details.\n\n### Prevention Rules\n\n#### 1. Do Not Trigger Synchronous State Changes in Capture-Phase Pointer Handlers Unless Necessary\n\nCapture-phase `pointerdown` and `mousedown` handlers can run before the click sequence finishes. If they trigger state updates synchronously, React can re-render in the middle of the browser's interaction pipeline.\n\nWhen the state change is not required immediately, defer it past the current event cycle with `requestAnimationFrame`.\n\n#### 2. Keep Portal-Rendered Viewer Surfaces Render-Isolated\n\nViewer trees rendered through dialogs or other portals should not re-render just because an unrelated parent concern changed.\n\nIn practice this means:\n\n- memoize portal-rendered viewer shells when they are intended to be stable\n- be skeptical of parent state changes that can cascade into the viewer tree during active pointer interaction\n- review viewer wrappers such as `DynamicViewer` with the same care as the concrete viewer components themselves\n\n#### 3. Never Blindly Spread Third-Party Props onto Native DOM Elements\n\nLibraries such as `react-markdown` can inject props that are valid for the library layer but unsafe for direct DOM output.\n\nWhen overriding renderers:\n\n- explicitly destructure library-only props such as `node`\n- spread only the remaining DOM-safe props onto native elements\n- assume that leaking unknown props onto the interaction target can change browser behavior in ways that are hard to diagnose\n\n### Practical Audit Checks\n\nWhen debugging or reviewing similar issues, use targeted searches like these:\n\n```bash\ngrep -rn 'addEventListener.*capture' frontend/src/\ngrep -rn '\\.\\.\\.props' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/FileBrowser/DynamicViewer.tsx\n```\n\nThese are not exhaustive audits, but they are good first-pass checks for the specific failure pattern this codebase has already seen.\n\n## Go Deeper\n\n- [Theming System and Theme Selection](../theming-system-and-theme-selection/): theme configuration, built-in themes, persistence, and how the UI switches themes\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL routing, keyboard flows, and refresh behavior\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): central shortcut definitions, browser commands, quick-bar modes, and context-aware handlers\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): file-type registries, preview selection, and conversion-sensitive viewer behavior\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared frontend-facing rules for diagnostics, translatable UI copy, and locale behavior\n\n## Validation Expectations\n\nWhen frontend behavior changes, start with:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change also affects backend or companion contracts, add the matching checks there too.\n", "0.8": "+++\ntitle = \"Frontend Overview\"\n+++\n\nThe frontend is a React and TypeScript application built with Vite. It is responsible for presenting Sambee's workflows clearly while respecting the backend and companion contracts behind them.\n\n## What the Frontend Owns\n\nThe browser app is responsible for:\n\n- routing users into the main product surfaces\n- rendering the file browser, viewer, and editing flows\n- managing browser-side state, selection, and navigation behavior\n- calling backend and companion-facing services through typed client code\n- applying theming, localization, and browser-side logging behavior\n\n## Main Frontend Areas\n\n| Area | Responsibility |\n|---|---|\n| `frontend/src/pages/` | page-level product flows such as the file browser |\n| `frontend/src/components/` | reusable UI building blocks |\n| `frontend/src/services/` | API clients, browser-to-companion integration, and other service helpers |\n| `frontend/src/i18n/` | typed translation resources and locale wiring |\n| `frontend/src/theme/` | theme configuration and theme-selection behavior |\n| `frontend/src/utils/` | formatting, registry, and other supporting utilities |\n\n## File Browser as the Core Surface\n\nThe file browser is the center of the main product UI.\n\n- it supports single-pane and dual-pane workflows\n- it keeps layout state and pane routing aligned with the URL\n- it coordinates selection, search, sorting, CRUD actions, viewer state, and keyboard behavior\n- it handles WebSocket-driven directory refresh behavior\n\nThat is why frontend changes in the file browser often have broader user impact than they first appear to.\n\nFor the main browsing surface itself, continue to [File Browser and Navigation Model](../file-browser-and-navigation-model/).\n\n## Frontend Contracts That Matter\n\n### Backend Contracts\n\nThe frontend depends on stable backend response shapes. When those change, update the corresponding types, service logic, and contract tests together.\n\n### Companion Contracts\n\nThe frontend is also the browser-side orchestrator for companion detection, pairing, local-drive access, and native-app editing initiation. That means browser-side state and desktop-side behavior are tightly linked even though they live in different projects.\n\n### Theming and Localization\n\nThe app treats theme behavior and localization as typed, explicit systems rather than loose UI sugar.\n\n- frontend copy should come from the translation system\n- locale handling and regional formatting are treated as product behavior\n- theme behavior is centralized instead of ad hoc component styling\n\n## Cross-Cutting Frontend Concerns\n\n- keyboard-first browsing and command surfaces\n- typed logging and backend tracing configuration\n- viewer behavior by file type and preview capability\n- responsive behavior, including mobile limitations and dual-pane desktop features\n\n## Rendering Hazards and Prevention Rules\n\nThis codebase has already hit at least one subtle React rendering failure where the app was logically correct but the browser still lost the first user click.\n\nThe useful lesson is that React rendering behavior, native event timing, portal trees, and third-party props can interact in ways that are easy to miss during normal component-level work.\n\n### Representative Failure Mode\n\nOne real frontend regression affected Markdown links inside the viewer.\n\n- links in the Markdown viewer ignored the first click when the viewer had been opened via keyboard\n- the second click worked\n- opening the viewer via mouse did not reproduce the problem\n\nThe root cause was not a single bad line. It was the combination of several implementation details:\n\n1. a global capture-phase `pointerdown` handler in `FileBrowser.tsx` updated keyboard-versus-pointer focus state synchronously\n2. React treated that update as a discrete-event flush and applied it between `pointerdown` and `click`\n3. the viewer shell was still expensive enough that the re-render cascaded through the portal-rendered viewer tree\n4. `react-markdown` override props included a `node` value that would have been dangerous to spread onto a native DOM anchor\n\nThe current code fixes that by deferring the focus-state update with `requestAnimationFrame`, memoizing the dynamic viewer shell, and stripping `node` out of the Markdown link override before spreading the remaining props.\n\n### Why This Class of Bug Matters\n\nThis kind of problem is easy to underestimate because:\n\n- it can be input-mode specific rather than globally reproducible\n- it may only appear when several otherwise-correct abstractions interact\n- the visible symptom can look like a browser bug or flaky click handling when the real cause is a mid-event re-render\n\nContributors should treat event timing and render isolation as architecture concerns, not just local component details.\n\n### Prevention Rules\n\n#### 1. Do Not Trigger Synchronous State Changes in Capture-Phase Pointer Handlers Unless Necessary\n\nCapture-phase `pointerdown` and `mousedown` handlers can run before the click sequence finishes. If they trigger state updates synchronously, React can re-render in the middle of the browser's interaction pipeline.\n\nWhen the state change is not required immediately, defer it past the current event cycle with `requestAnimationFrame`.\n\n#### 2. Keep Portal-Rendered Viewer Surfaces Render-Isolated\n\nViewer trees rendered through dialogs or other portals should not re-render just because an unrelated parent concern changed.\n\nIn practice this means:\n\n- memoize portal-rendered viewer shells when they are intended to be stable\n- be skeptical of parent state changes that can cascade into the viewer tree during active pointer interaction\n- review viewer wrappers such as `DynamicViewer` with the same care as the concrete viewer components themselves\n\n#### 3. Never Blindly Spread Third-Party Props onto Native DOM Elements\n\nLibraries such as `react-markdown` can inject props that are valid for the library layer but unsafe for direct DOM output.\n\nWhen overriding renderers:\n\n- explicitly destructure library-only props such as `node`\n- spread only the remaining DOM-safe props onto native elements\n- assume that leaking unknown props onto the interaction target can change browser behavior in ways that are hard to diagnose\n\n### Practical Audit Checks\n\nWhen debugging or reviewing similar issues, use targeted searches like these:\n\n```bash\ngrep -rn 'addEventListener.*capture' frontend/src/\ngrep -rn '\\.\\.\\.props' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/FileBrowser/DynamicViewer.tsx\n```\n\nThese are not exhaustive audits, but they are good first-pass checks for the specific failure pattern this codebase has already seen.\n\n## Go Deeper\n\n- [Theming System and Theme Selection](../theming-system-and-theme-selection/): theme configuration, built-in themes, persistence, and how the UI switches themes\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL routing, keyboard flows, and refresh behavior\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): central shortcut definitions, browser commands, quick-bar modes, and context-aware handlers\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): file-type registries, preview selection, and conversion-sensitive viewer behavior\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared frontend-facing rules for diagnostics, translatable UI copy, and locale behavior\n\n## Validation Expectations\n\nWhen frontend behavior changes, start with:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change also affects backend or companion contracts, add the matching checks there too.\n", "0.9": "+++\ntitle = \"Frontend Overview\"\n+++\n\nThe frontend is a React and TypeScript application built with Vite. It is responsible for presenting Sambee's workflows clearly while respecting the backend and companion contracts behind them.\n\n## What the Frontend Owns\n\nThe browser app is responsible for:\n\n- routing users into the main product surfaces\n- rendering the file browser, viewer, and editing flows\n- managing browser-side state, selection, and navigation behavior\n- calling backend and companion-facing services through typed client code\n- applying theming, localization, and browser-side logging behavior\n\n## Main Frontend Areas\n\n| Area | Responsibility |\n|---|---|\n| `frontend/src/pages/` | page-level product flows such as the file browser |\n| `frontend/src/components/` | reusable UI building blocks |\n| `frontend/src/services/` | API clients, browser-to-companion integration, and other service helpers |\n| `frontend/src/i18n/` | typed translation resources and locale wiring |\n| `frontend/src/theme/` | theme configuration and theme-selection behavior |\n| `frontend/src/utils/` | formatting, registry, and other supporting utilities |\n\n## File Browser as the Core Surface\n\nThe file browser is the center of the main product UI.\n\n- it supports single-pane and dual-pane workflows\n- it keeps layout state and pane routing aligned with the URL\n- it coordinates selection, search, sorting, CRUD actions, viewer state, and keyboard behavior\n- it handles WebSocket-driven directory refresh behavior\n\nThat is why frontend changes in the file browser often have broader user impact than they first appear to.\n\nFor the main browsing surface itself, continue to [File Browser and Navigation Model](../file-browser-and-navigation-model/).\n\n## Frontend Contracts That Matter\n\n### Backend Contracts\n\nThe frontend depends on stable backend response shapes. When those change, update the corresponding types, service logic, and contract tests together.\n\n### Companion Contracts\n\nThe frontend is also the browser-side orchestrator for companion detection, pairing, local-drive access, and native-app editing initiation. That means browser-side state and desktop-side behavior are tightly linked even though they live in different projects.\n\n### Theming and Localization\n\nThe app treats theme behavior and localization as typed, explicit systems rather than loose UI sugar.\n\n- frontend copy should come from the translation system\n- locale handling and regional formatting are treated as product behavior\n- theme behavior is centralized instead of ad hoc component styling\n\n## Cross-Cutting Frontend Concerns\n\n- keyboard-first browsing and command surfaces\n- typed logging and backend tracing configuration\n- viewer behavior by file type and preview capability\n- responsive behavior, including mobile limitations and dual-pane desktop features\n\n## Rendering Hazards and Prevention Rules\n\nThis codebase has already hit at least one subtle React rendering failure where the app was logically correct but the browser still lost the first user click.\n\nThe useful lesson is that React rendering behavior, native event timing, portal trees, and third-party props can interact in ways that are easy to miss during normal component-level work.\n\n### Representative Failure Mode\n\nOne real frontend regression affected Markdown links inside the viewer.\n\n- links in the Markdown viewer ignored the first click when the viewer had been opened via keyboard\n- the second click worked\n- opening the viewer via mouse did not reproduce the problem\n\nThe root cause was not a single bad line. It was the combination of several implementation details:\n\n1. a global capture-phase `pointerdown` handler in `FileBrowser.tsx` updated keyboard-versus-pointer focus state synchronously\n2. React treated that update as a discrete-event flush and applied it between `pointerdown` and `click`\n3. the viewer shell was still expensive enough that the re-render cascaded through the portal-rendered viewer tree\n4. `react-markdown` override props included a `node` value that would have been dangerous to spread onto a native DOM anchor\n\nThe current code fixes that by deferring the focus-state update with `requestAnimationFrame`, memoizing the dynamic viewer shell, and stripping `node` out of the Markdown link override before spreading the remaining props.\n\n### Why This Class of Bug Matters\n\nThis kind of problem is easy to underestimate because:\n\n- it can be input-mode specific rather than globally reproducible\n- it may only appear when several otherwise-correct abstractions interact\n- the visible symptom can look like a browser bug or flaky click handling when the real cause is a mid-event re-render\n\nContributors should treat event timing and render isolation as architecture concerns, not just local component details.\n\n### Prevention Rules\n\n#### 1. Do Not Trigger Synchronous State Changes in Capture-Phase Pointer Handlers Unless Necessary\n\nCapture-phase `pointerdown` and `mousedown` handlers can run before the click sequence finishes. If they trigger state updates synchronously, React can re-render in the middle of the browser's interaction pipeline.\n\nWhen the state change is not required immediately, defer it past the current event cycle with `requestAnimationFrame`.\n\n#### 2. Keep Portal-Rendered Viewer Surfaces Render-Isolated\n\nViewer trees rendered through dialogs or other portals should not re-render just because an unrelated parent concern changed.\n\nIn practice this means:\n\n- memoize portal-rendered viewer shells when they are intended to be stable\n- be skeptical of parent state changes that can cascade into the viewer tree during active pointer interaction\n- review viewer wrappers such as `DynamicViewer` with the same care as the concrete viewer components themselves\n\n#### 3. Never Blindly Spread Third-Party Props onto Native DOM Elements\n\nLibraries such as `react-markdown` can inject props that are valid for the library layer but unsafe for direct DOM output.\n\nWhen overriding renderers:\n\n- explicitly destructure library-only props such as `node`\n- spread only the remaining DOM-safe props onto native elements\n- assume that leaking unknown props onto the interaction target can change browser behavior in ways that are hard to diagnose\n\n### Practical Audit Checks\n\nWhen debugging or reviewing similar issues, use targeted searches like these:\n\n```bash\ngrep -rn 'addEventListener.*capture' frontend/src/\ngrep -rn '\\.\\.\\.props' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/FileBrowser/DynamicViewer.tsx\n```\n\nThese are not exhaustive audits, but they are good first-pass checks for the specific failure pattern this codebase has already seen.\n\n## Go Deeper\n\n- [Theming System and Theme Selection](../theming-system-and-theme-selection/): theme configuration, built-in themes, persistence, and how the UI switches themes\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL routing, keyboard flows, and refresh behavior\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): central shortcut definitions, browser commands, quick-bar modes, and context-aware handlers\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): file-type registries, preview selection, and conversion-sensitive viewer behavior\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared frontend-facing rules for diagnostics, translatable UI copy, and locale behavior\n\n## Validation Expectations\n\nWhen frontend behavior changes, start with:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change also affects backend or companion contracts, add the matching checks there too.\n", "1.0": "+++\ntitle = \"Frontend Overview\"\n+++\n\nThe frontend is a React and TypeScript application built with Vite. It is responsible for presenting Sambee's workflows clearly while respecting the backend and companion contracts behind them.\n\n## What the Frontend Owns\n\nThe browser app is responsible for:\n\n- routing users into the main product surfaces\n- rendering the file browser, viewer, and editing flows\n- managing browser-side state, selection, and navigation behavior\n- calling backend and companion-facing services through typed client code\n- applying theming, localization, and browser-side logging behavior\n\n## Main Frontend Areas\n\n| Area | Responsibility |\n|---|---|\n| `frontend/src/pages/` | page-level product flows such as the file browser |\n| `frontend/src/components/` | reusable UI building blocks |\n| `frontend/src/services/` | API clients, browser-to-companion integration, and other service helpers |\n| `frontend/src/i18n/` | typed translation resources and locale wiring |\n| `frontend/src/theme/` | theme configuration and theme-selection behavior |\n| `frontend/src/utils/` | formatting, registry, and other supporting utilities |\n\n## File Browser as the Core Surface\n\nThe file browser is the center of the main product UI.\n\n- it supports single-pane and dual-pane workflows\n- it keeps layout state and pane routing aligned with the URL\n- it coordinates selection, search, sorting, CRUD actions, viewer state, and keyboard behavior\n- it handles WebSocket-driven directory refresh behavior\n\nThat is why frontend changes in the file browser often have broader user impact than they first appear to.\n\nFor the main browsing surface itself, continue to [File Browser and Navigation Model](../file-browser-and-navigation-model/).\n\n## Frontend Contracts That Matter\n\n### Backend Contracts\n\nThe frontend depends on stable backend response shapes. When those change, update the corresponding types, service logic, and contract tests together.\n\n### Companion Contracts\n\nThe frontend is also the browser-side orchestrator for companion detection, pairing, local-drive access, and native-app editing initiation. That means browser-side state and desktop-side behavior are tightly linked even though they live in different projects.\n\n### Theming and Localization\n\nThe app treats theme behavior and localization as typed, explicit systems rather than loose UI sugar.\n\n- frontend copy should come from the translation system\n- locale handling and regional formatting are treated as product behavior\n- theme behavior is centralized instead of ad hoc component styling\n\n## Cross-Cutting Frontend Concerns\n\n- keyboard-first browsing and command surfaces\n- typed logging and backend tracing configuration\n- viewer behavior by file type and preview capability\n- responsive behavior, including mobile limitations and dual-pane desktop features\n\n## Rendering Hazards and Prevention Rules\n\nThis codebase has already hit at least one subtle React rendering failure where the app was logically correct but the browser still lost the first user click.\n\nThe useful lesson is that React rendering behavior, native event timing, portal trees, and third-party props can interact in ways that are easy to miss during normal component-level work.\n\n### Representative Failure Mode\n\nOne real frontend regression affected Markdown links inside the viewer.\n\n- links in the Markdown viewer ignored the first click when the viewer had been opened via keyboard\n- the second click worked\n- opening the viewer via mouse did not reproduce the problem\n\nThe root cause was not a single bad line. It was the combination of several implementation details:\n\n1. a global capture-phase `pointerdown` handler in `FileBrowser.tsx` updated keyboard-versus-pointer focus state synchronously\n2. React treated that update as a discrete-event flush and applied it between `pointerdown` and `click`\n3. the viewer shell was still expensive enough that the re-render cascaded through the portal-rendered viewer tree\n4. `react-markdown` override props included a `node` value that would have been dangerous to spread onto a native DOM anchor\n\nThe current code fixes that by deferring the focus-state update with `requestAnimationFrame`, memoizing the dynamic viewer shell, and stripping `node` out of the Markdown link override before spreading the remaining props.\n\n### Why This Class of Bug Matters\n\nThis kind of problem is easy to underestimate because:\n\n- it can be input-mode specific rather than globally reproducible\n- it may only appear when several otherwise-correct abstractions interact\n- the visible symptom can look like a browser bug or flaky click handling when the real cause is a mid-event re-render\n\nContributors should treat event timing and render isolation as architecture concerns, not just local component details.\n\n### Prevention Rules\n\n#### 1. Do Not Trigger Synchronous State Changes in Capture-Phase Pointer Handlers Unless Necessary\n\nCapture-phase `pointerdown` and `mousedown` handlers can run before the click sequence finishes. If they trigger state updates synchronously, React can re-render in the middle of the browser's interaction pipeline.\n\nWhen the state change is not required immediately, defer it past the current event cycle with `requestAnimationFrame`.\n\n#### 2. Keep Portal-Rendered Viewer Surfaces Render-Isolated\n\nViewer trees rendered through dialogs or other portals should not re-render just because an unrelated parent concern changed.\n\nIn practice this means:\n\n- memoize portal-rendered viewer shells when they are intended to be stable\n- be skeptical of parent state changes that can cascade into the viewer tree during active pointer interaction\n- review viewer wrappers such as `DynamicViewer` with the same care as the concrete viewer components themselves\n\n#### 3. Never Blindly Spread Third-Party Props onto Native DOM Elements\n\nLibraries such as `react-markdown` can inject props that are valid for the library layer but unsafe for direct DOM output.\n\nWhen overriding renderers:\n\n- explicitly destructure library-only props such as `node`\n- spread only the remaining DOM-safe props onto native elements\n- assume that leaking unknown props onto the interaction target can change browser behavior in ways that are hard to diagnose\n\n### Practical Audit Checks\n\nWhen debugging or reviewing similar issues, use targeted searches like these:\n\n```bash\ngrep -rn 'addEventListener.*capture' frontend/src/\ngrep -rn '\\.\\.\\.props' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/FileBrowser/DynamicViewer.tsx\n```\n\nThese are not exhaustive audits, but they are good first-pass checks for the specific failure pattern this codebase has already seen.\n\n## Go Deeper\n\n- [Theming System and Theme Selection](../theming-system-and-theme-selection/): theme configuration, built-in themes, persistence, and how the UI switches themes\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL routing, keyboard flows, and refresh behavior\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): central shortcut definitions, browser commands, quick-bar modes, and context-aware handlers\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): file-type registries, preview selection, and conversion-sensitive viewer behavior\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared frontend-facing rules for diagnostics, translatable UI copy, and locale behavior\n\n## Validation Expectations\n\nWhen frontend behavior changes, start with:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change also affects backend or companion contracts, add the matching checks there too.\n", "2.0": "+++\ntitle = \"Frontend Overview\"\n+++\n\nThe frontend is a React and TypeScript application built with Vite. It is responsible for presenting Sambee's workflows clearly while respecting the backend and companion contracts behind them.\n\n## What the Frontend Owns\n\nThe browser app is responsible for:\n\n- routing users into the main product surfaces\n- rendering the file browser, viewer, and editing flows\n- managing browser-side state, selection, and navigation behavior\n- calling backend and companion-facing services through typed client code\n- applying theming, localization, and browser-side logging behavior\n\n## Main Frontend Areas\n\n| Area | Responsibility |\n|---|---|\n| `frontend/src/pages/` | page-level product flows such as the file browser |\n| `frontend/src/components/` | reusable UI building blocks |\n| `frontend/src/services/` | API clients, browser-to-companion integration, and other service helpers |\n| `frontend/src/i18n/` | typed translation resources and locale wiring |\n| `frontend/src/theme/` | theme configuration and theme-selection behavior |\n| `frontend/src/utils/` | formatting, registry, and other supporting utilities |\n\n## File Browser as the Core Surface\n\nThe file browser is the center of the main product UI.\n\n- it supports single-pane and dual-pane workflows\n- it keeps layout state and pane routing aligned with the URL\n- it coordinates selection, search, sorting, CRUD actions, viewer state, and keyboard behavior\n- it handles WebSocket-driven directory refresh behavior\n\nThat is why frontend changes in the file browser often have broader user impact than they first appear to.\n\nFor the main browsing surface itself, continue to [File Browser and Navigation Model](../file-browser-and-navigation-model/).\n\n## Frontend Contracts That Matter\n\n### Backend Contracts\n\nThe frontend depends on stable backend response shapes. When those change, update the corresponding types, service logic, and contract tests together.\n\n### Companion Contracts\n\nThe frontend is also the browser-side orchestrator for companion detection, pairing, local-drive access, and native-app editing initiation. That means browser-side state and desktop-side behavior are tightly linked even though they live in different projects.\n\n### Theming and Localization\n\nThe app treats theme behavior and localization as typed, explicit systems rather than loose UI sugar.\n\n- frontend copy should come from the translation system\n- locale handling and regional formatting are treated as product behavior\n- theme behavior is centralized instead of ad hoc component styling\n\n## Cross-Cutting Frontend Concerns\n\n- keyboard-first browsing and command surfaces\n- typed logging and backend tracing configuration\n- viewer behavior by file type and preview capability\n- responsive behavior, including mobile limitations and dual-pane desktop features\n\n## Rendering Hazards and Prevention Rules\n\nThis codebase has already hit at least one subtle React rendering failure where the app was logically correct but the browser still lost the first user click.\n\nThe useful lesson is that React rendering behavior, native event timing, portal trees, and third-party props can interact in ways that are easy to miss during normal component-level work.\n\n### Representative Failure Mode\n\nOne real frontend regression affected Markdown links inside the viewer.\n\n- links in the Markdown viewer ignored the first click when the viewer had been opened via keyboard\n- the second click worked\n- opening the viewer via mouse did not reproduce the problem\n\nThe root cause was not a single bad line. It was the combination of several implementation details:\n\n1. a global capture-phase `pointerdown` handler in `FileBrowser.tsx` updated keyboard-versus-pointer focus state synchronously\n2. React treated that update as a discrete-event flush and applied it between `pointerdown` and `click`\n3. the viewer shell was still expensive enough that the re-render cascaded through the portal-rendered viewer tree\n4. `react-markdown` override props included a `node` value that would have been dangerous to spread onto a native DOM anchor\n\nThe current code fixes that by deferring the focus-state update with `requestAnimationFrame`, memoizing the dynamic viewer shell, and stripping `node` out of the Markdown link override before spreading the remaining props.\n\n### Why This Class of Bug Matters\n\nThis kind of problem is easy to underestimate because:\n\n- it can be input-mode specific rather than globally reproducible\n- it may only appear when several otherwise-correct abstractions interact\n- the visible symptom can look like a browser bug or flaky click handling when the real cause is a mid-event re-render\n\nContributors should treat event timing and render isolation as architecture concerns, not just local component details.\n\n### Prevention Rules\n\n#### 1. Do Not Trigger Synchronous State Changes in Capture-Phase Pointer Handlers Unless Necessary\n\nCapture-phase `pointerdown` and `mousedown` handlers can run before the click sequence finishes. If they trigger state updates synchronously, React can re-render in the middle of the browser's interaction pipeline.\n\nWhen the state change is not required immediately, defer it past the current event cycle with `requestAnimationFrame`.\n\n#### 2. Keep Portal-Rendered Viewer Surfaces Render-Isolated\n\nViewer trees rendered through dialogs or other portals should not re-render just because an unrelated parent concern changed.\n\nIn practice this means:\n\n- memoize portal-rendered viewer shells when they are intended to be stable\n- be skeptical of parent state changes that can cascade into the viewer tree during active pointer interaction\n- review viewer wrappers such as `DynamicViewer` with the same care as the concrete viewer components themselves\n\n#### 3. Never Blindly Spread Third-Party Props onto Native DOM Elements\n\nLibraries such as `react-markdown` can inject props that are valid for the library layer but unsafe for direct DOM output.\n\nWhen overriding renderers:\n\n- explicitly destructure library-only props such as `node`\n- spread only the remaining DOM-safe props onto native elements\n- assume that leaking unknown props onto the interaction target can change browser behavior in ways that are hard to diagnose\n\n### Practical Audit Checks\n\nWhen debugging or reviewing similar issues, use targeted searches like these:\n\n```bash\ngrep -rn 'addEventListener.*capture' frontend/src/\ngrep -rn '\\.\\.\\.props' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/FileBrowser/DynamicViewer.tsx\n```\n\nThese are not exhaustive audits, but they are good first-pass checks for the specific failure pattern this codebase has already seen.\n\n## Go Deeper\n\n- [Theming System and Theme Selection](../theming-system-and-theme-selection/): theme configuration, built-in themes, persistence, and how the UI switches themes\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL routing, keyboard flows, and refresh behavior\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): central shortcut definitions, browser commands, quick-bar modes, and context-aware handlers\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): file-type registries, preview selection, and conversion-sensitive viewer behavior\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared frontend-facing rules for diagnostics, translatable UI copy, and locale behavior\n\n## Validation Expectations\n\nWhen frontend behavior changes, start with:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change also affects backend or companion contracts, add the matching checks there too.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/frontend-architecture/theming-system-and-theme-selection", "parent_id": "section:developer-guide/frontend-architecture", "depth": 2, "kind": "page", "label": "theming-system-and-theme-selection", "title": "Theming System And Theme Selection", "path": "developer-guide/frontend-architecture/theming-system-and-theme-selection", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "branched", "source_version": "0.7", "diff_added": 42, "diff_removed": 5}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "branched", "source_version": "0.9", "diff_added": 31, "diff_removed": 275}}, "content_versions": {"0.7": "+++\ntitle = \"Theming System and Theme Selection\"\n+++\n\nSambee's theming system is centralized. Theme configuration, runtime state, persistence, and selection UI are all treated as one frontend subsystem.\n\nUse this page when you are changing palette behavior, adding a built-in theme, wiring a theme-aware component, or debugging why a selected theme is not applied consistently.\n\n## Main Pieces\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/theme/types.ts` | TypeScript theme interfaces and theme configuration shape |\n| `frontend/src/theme/themes.ts` | built-in theme definitions plus default-theme helpers |\n| `frontend/src/theme/ThemeContext.tsx` | runtime theme state, persistence, and theme switching |\n| `frontend/src/theme/index.ts` | public theme exports for the rest of the app |\n| `frontend/src/components/ThemeSelector.tsx` | theme-selection UI and dialog |\n| `frontend/src/components/themeSelectorStrings.ts` | localized strings and built-in-theme labels for the selector |\n\nThese pieces matter together. Theme behavior is not just a palette file or just a toolbar widget.\n\n## What the System Supports\n\nThe theme model currently supports:\n\n- built-in light and dark themes\n- persistent theme preferences\n- custom theme storage and runtime selection\n- theme-aware MUI palette generation\n- one shared provider that updates the app when the theme changes\n\n## Built-In Themes\n\nThe built-in themes live in `builtInThemes` in `frontend/src/theme/themes.ts`.\n\nCurrent built-ins include:\n\n- `sambee-light`: the default light branded theme\n- `sambee-dark`: the default dark branded theme\n\nThe helper functions contributors use most are:\n\n- `getDefaultTheme()`\n- `getDefaultTheme(\"light\")`\n- `getDefaultTheme(\"dark\")`\n- `getThemeById(id)`\n\nThe theme module also includes compile-time assertions around the default-theme indices so the expected built-in defaults cannot silently disappear.\n\n## Runtime Flow\n\nAt runtime, theme selection follows this path:\n\n1. the app renders inside `SambeeThemeProvider`\n2. the current theme ID is restored from persisted state when available\n3. built-in themes are resolved from code and combined with persisted custom themes\n4. `useSambeeTheme().setThemeById()` updates the active theme\n5. the selected theme is persisted\n6. the MUI theme instance updates and the UI re-renders\n\nThat is why a theme bug can look like a local component styling issue while actually being a context, persistence, or provider problem.\n\n## Theme Context Contract\n\n`useSambeeTheme()` is the main runtime entry point.\n\nContributors typically consume values such as:\n\n- `currentTheme`\n- `muiTheme`\n- `availableThemes`\n- `setThemeById`\n- `addCustomTheme`\n\nThe hook must be used inside `SambeeThemeProvider`. If you bypass that provider boundary, theme state becomes inconsistent immediately.\n\nRepresentative usage:\n\n```tsx\nimport { useSambeeTheme } from \"../theme\";\n\nfunction ThemeExample() {\n\tconst { currentTheme, setThemeById } = useSambeeTheme();\n\n\treturn (\n\t\t\u003cbutton onClick={() =\u003e setThemeById(\"sambee-dark\")}\u003e\n\t\t\tCurrent: {currentTheme.name}\n\t\t\u003c/button\u003e\n\t);\n}\n```\n\n## Theme Configuration Model\n\nThemes are expressed as typed configuration rather than ad hoc color overrides.\n\nThe palette surface includes areas such as:\n\n- `primary`\n- `secondary`\n- `background`\n- `text`\n- `action`\n\nCommon uses in the UI include:\n\n- directory emphasis and action colors from `primary`\n- page and surface backgrounds from `background`\n- readable foreground text from `text`\n- hover and selection states from `action`\n\nMaterial UI also derives additional palette values such as divider color when enough base information is present.\n\n## Built-In Theme Characteristics\n\nThe current built-ins intentionally align with Sambee's branding.\n\n### Sambee Light\n\n- ID: `sambee-light`\n- mode: light\n- branded golden primary palette\n- cream-toned background\n- dark secondary contrast surface\n\n### Sambee Dark\n\n- ID: `sambee-dark`\n- mode: dark\n- branded golden primary palette\n- dark background\n- light secondary contrast surface\n\nThe exact palette values live in `frontend/src/theme/themes.ts`. Keep the docs focused on architectural meaning rather than duplicating every color token when the code is already authoritative.\n\n## Theme Selector UI\n\nThe visible selection UI lives in `frontend/src/components/ThemeSelector.tsx`.\n\nThe selector:\n\n- opens a dialog listing available themes\n- shows a preview of theme colors\n- uses localized strings through `themeSelectorStrings.ts`\n- calls `setThemeById` when the user changes themes\n\nThe selector is already integrated into the file-browser toolbar, and the current preferences UI also consumes the same theme state.\n\n## Persistence Model\n\nTheme preferences are persisted in local storage.\n\nThe main keys are:\n\n- `theme-id-current`: the currently selected theme ID\n- `themes-builtin`: built-in themes as last synchronized from code\n- `themes-custom`: user-created custom themes\n\nThis matters for two reasons:\n\n- the selected theme survives reloads\n- built-in theme definitions can still be refreshed from code when the app updates\n\nThe system syncs built-in themes from code so users pick up reviewed built-in theme changes without losing their custom themes.\n\n## Custom Themes\n\nThe theme context supports custom themes in addition to the built-ins.\n\nThat means contributors should treat theme IDs, storage layout, and theme resolution as stable interfaces rather than temporary implementation details.\n\nWhen adding custom-theme features or editing persistence logic:\n\n- preserve separation between built-in and custom theme sets\n- keep the active theme valid even if a custom theme is removed\n- preserve a safe fallback to the default theme\n\nRepresentative pattern:\n\n```tsx\nimport { useSambeeTheme } from \"../theme\";\n\nfunction addExampleTheme() {\n\tconst { addCustomTheme } = useSambeeTheme();\n\n\taddCustomTheme({\n\t\tid: \"my-custom-theme\",\n\t\tname: \"My Custom Theme\",\n\t\tdescription: \"A unique theme\",\n\t\tmode: \"light\",\n\t\tprimary: { main: \"#ff6b6b\" },\n\t\tsecondary: { main: \"#4ecdc4\" },\n\t});\n}\n```\n\n## Theme Schema and Future Builder Support\n\n`frontend/src/theme/types.ts` also exports `THEME_SCHEMA`.\n\nThat schema is runtime-accessible metadata describing:\n\n- field types such as text, color, and select\n- labels and descriptions for UI\n- required versus optional fields\n- nested field definitions\n- select options such as `light` and `dark`\n\nIt exists so future theme-builder tooling can generate forms and validation from one typed source instead of re-encoding theme structure in multiple places.\n\n## Theme-Aware Component Rules\n\nWhen building UI components:\n\n- use the active MUI theme instead of hard-coded surface and text colors when the style belongs to the app theme\n- prefer `useTheme()` or the shared theme context rather than duplicating palette lookups manually\n- keep file-type icon colors and other intentionally non-theme registry colors separate from the app palette when they serve a different product purpose\n\nA theme-aware component typically reads from `theme.palette` and `theme.spacing` rather than introducing standalone constants.\n\n## Browser and PWA Integration\n\nThe theme system also updates the browser `theme-color` meta tag to match the selected theme's primary color.\n\nThat affects:\n\n- browser UI tinting on supported browsers\n- Android browser chrome behavior\n- installed PWA status-bar appearance\n\nIf a theme appears correct inside the app but wrong in browser chrome, check this integration path rather than only inspecting component styles.\n\n## Common Failure Modes\n\n- a component hard-codes colors that should come from the active theme\n- a new built-in theme is added without keeping default-theme helpers valid\n- theme state is read outside `SambeeThemeProvider`\n- a persistence change breaks fallback to the default theme\n- built-in theme updates and custom theme persistence start overwriting each other\n- contributors treat selector labels as static strings instead of localized UI copy\n\n## Validation Expectations\n\nWhen the theming system changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nPay particular attention to:\n\n- theme-provider tests under `frontend/src/theme/__tests__/`\n- built-in-theme and default-theme tests\n- `types.test.ts` coverage around `THEME_SCHEMA`\n- theme-selector tests under `frontend/src/components/__tests__/`\n- manual checks that text remains readable in both built-in themes\n\n## Where to Continue\n\n- [Frontend Overview](../frontend-overview/): broader browser-app structure and the place of theme behavior in the frontend\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): another shared frontend subsystem with central configuration and runtime binding\n- [Localization and Locale Behavior](../../cross-cutting-systems/localization-and-locale-behavior/): shared UI-system rules that often change alongside settings and preferences surfaces\n", "0.8": "+++\ntitle = \"Theming System and Theme Selection\"\n+++\n\nSambee's theming system is centralized. Theme configuration, runtime state, persistence, and selection UI are all treated as one frontend subsystem.\n\nUse this page when you are changing palette behavior, adding a built-in theme, wiring a theme-aware component, or debugging why a selected theme is not applied consistently.\n\n## Main Pieces\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/theme/types.ts` | TypeScript theme interfaces and theme configuration shape |\n| `frontend/src/theme/themes.ts` | built-in theme definitions plus default-theme helpers |\n| `frontend/src/theme/ThemeContext.tsx` | runtime theme state, persistence, and theme switching |\n| `frontend/src/theme/index.ts` | public theme exports for the rest of the app |\n| `frontend/src/components/ThemeSelector.tsx` | theme-selection UI and dialog |\n| `frontend/src/components/themeSelectorStrings.ts` | localized strings and built-in-theme labels for the selector |\n\nThese pieces matter together. Theme behavior is not just a palette file or just a toolbar widget.\n\n## What the System Supports\n\nThe theme model currently supports:\n\n- built-in light and dark themes\n- persistent theme preferences\n- custom theme storage and runtime selection\n- theme-aware MUI palette generation\n- one shared provider that updates the app when the theme changes\n\n## Built-In Themes\n\nThe built-in themes live in `builtInThemes` in `frontend/src/theme/themes.ts`.\n\nCurrent built-ins include:\n\n- `sambee-light`: the default light branded theme\n- `sambee-dark`: the default dark branded theme\n\nThe helper functions contributors use most are:\n\n- `getDefaultTheme()`\n- `getDefaultTheme(\"light\")`\n- `getDefaultTheme(\"dark\")`\n- `getThemeById(id)`\n\nThe theme module also includes compile-time assertions around the default-theme indices so the expected built-in defaults cannot silently disappear.\n\n## Runtime Flow\n\nAt runtime, theme selection follows this path:\n\n1. the app renders inside `SambeeThemeProvider`\n2. the current theme ID is restored from persisted state when available\n3. built-in themes are resolved from code and combined with persisted custom themes\n4. `useSambeeTheme().setThemeById()` updates the active theme\n5. the selected theme is persisted\n6. the MUI theme instance updates and the UI re-renders\n\nThat is why a theme bug can look like a local component styling issue while actually being a context, persistence, or provider problem.\n\n## Theme Context Contract\n\n`useSambeeTheme()` is the main runtime entry point.\n\nContributors typically consume values such as:\n\n- `currentTheme`\n- `muiTheme`\n- `availableThemes`\n- `setThemeById`\n- `addCustomTheme`\n\nThe hook must be used inside `SambeeThemeProvider`. If you bypass that provider boundary, theme state becomes inconsistent immediately.\n\nRepresentative usage:\n\n```tsx\nimport { useSambeeTheme } from \"../theme\";\n\nfunction ThemeExample() {\n\tconst { currentTheme, setThemeById } = useSambeeTheme();\n\n\treturn (\n\t\t\u003cbutton onClick={() =\u003e setThemeById(\"sambee-dark\")}\u003e\n\t\t\tCurrent: {currentTheme.name}\n\t\t\u003c/button\u003e\n\t);\n}\n```\n\n## Theme Configuration Model\n\nThemes are expressed as typed configuration rather than ad hoc color overrides.\n\nThe palette surface includes areas such as:\n\n- `primary`\n- `secondary`\n- `background`\n- `text`\n- `action`\n\nCommon uses in the UI include:\n\n- directory emphasis and action colors from `primary`\n- page and surface backgrounds from `background`\n- readable foreground text from `text`\n- hover and selection states from `action`\n\nMaterial UI also derives additional palette values such as divider color when enough base information is present.\n\n## Built-In Theme Characteristics\n\nThe current built-ins intentionally align with Sambee's branding.\n\n### Sambee Light\n\n- ID: `sambee-light`\n- mode: light\n- branded golden primary palette\n- cream-toned background\n- dark secondary contrast surface\n\n### Sambee Dark\n\n- ID: `sambee-dark`\n- mode: dark\n- branded golden primary palette\n- dark background\n- light secondary contrast surface\n\nThe exact palette values live in `frontend/src/theme/themes.ts`. Keep the docs focused on architectural meaning rather than duplicating every color token when the code is already authoritative.\n\n## Theme Selector UI\n\nThe visible selection UI lives in `frontend/src/components/ThemeSelector.tsx`.\n\nThe selector:\n\n- opens a dialog listing available themes\n- shows a preview of theme colors\n- uses localized strings through `themeSelectorStrings.ts`\n- calls `setThemeById` when the user changes themes\n\nThe selector is already integrated into the file-browser toolbar, and the current preferences UI also consumes the same theme state.\n\n## Persistence Model\n\nTheme preferences are persisted in local storage.\n\nThe main keys are:\n\n- `theme-id-current`: the currently selected theme ID\n- `themes-builtin`: built-in themes as last synchronized from code\n- `themes-custom`: user-created custom themes\n\nThis matters for two reasons:\n\n- the selected theme survives reloads\n- built-in theme definitions can still be refreshed from code when the app updates\n\nThe system syncs built-in themes from code so users pick up reviewed built-in theme changes without losing their custom themes.\n\n## Custom Themes\n\nThe theme context supports custom themes in addition to the built-ins.\n\nThat means contributors should treat theme IDs, storage layout, and theme resolution as stable interfaces rather than temporary implementation details.\n\nWhen adding custom-theme features or editing persistence logic:\n\n- preserve separation between built-in and custom theme sets\n- keep the active theme valid even if a custom theme is removed\n- preserve a safe fallback to the default theme\n\nRepresentative pattern:\n\n```tsx\nimport { useSambeeTheme } from \"../theme\";\n\nfunction addExampleTheme() {\n\tconst { addCustomTheme } = useSambeeTheme();\n\n\taddCustomTheme({\n\t\tid: \"my-custom-theme\",\n\t\tname: \"My Custom Theme\",\n\t\tdescription: \"A unique theme\",\n\t\tmode: \"light\",\n\t\tprimary: { main: \"#ff6b6b\" },\n\t\tsecondary: { main: \"#4ecdc4\" },\n\t});\n}\n```\n\n## Theme Schema and Future Builder Support\n\n`frontend/src/theme/types.ts` also exports `THEME_SCHEMA`.\n\nThat schema is runtime-accessible metadata describing:\n\n- field types such as text, color, and select\n- labels and descriptions for UI\n- required versus optional fields\n- nested field definitions\n- select options such as `light` and `dark`\n\nIt exists so future theme-builder tooling can generate forms and validation from one typed source instead of re-encoding theme structure in multiple places.\n\n## Theme-Aware Component Rules\n\nWhen building UI components:\n\n- use the active MUI theme instead of hard-coded surface and text colors when the style belongs to the app theme\n- prefer `useTheme()` or the shared theme context rather than duplicating palette lookups manually\n- keep file-type icon colors and other intentionally non-theme registry colors separate from the app palette when they serve a different product purpose\n\nA theme-aware component typically reads from `theme.palette` and `theme.spacing` rather than introducing standalone constants.\n\n## Browser and PWA Integration\n\nThe theme system also updates the browser `theme-color` meta tag to match the selected theme's primary color.\n\nThat affects:\n\n- browser UI tinting on supported browsers\n- Android browser chrome behavior\n- installed PWA status-bar appearance\n\nIf a theme appears correct inside the app but wrong in browser chrome, check this integration path rather than only inspecting component styles.\n\n## Common Failure Modes\n\n- a component hard-codes colors that should come from the active theme\n- a new built-in theme is added without keeping default-theme helpers valid\n- theme state is read outside `SambeeThemeProvider`\n- a persistence change breaks fallback to the default theme\n- built-in theme updates and custom theme persistence start overwriting each other\n- contributors treat selector labels as static strings instead of localized UI copy\n\n## Validation Expectations\n\nWhen the theming system changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nPay particular attention to:\n\n- theme-provider tests under `frontend/src/theme/__tests__/`\n- built-in-theme and default-theme tests\n- `types.test.ts` coverage around `THEME_SCHEMA`\n- theme-selector tests under `frontend/src/components/__tests__/`\n- manual checks that text remains readable in both built-in themes\n\n## Where to Continue\n\n- [Frontend Overview](../frontend-overview/): broader browser-app structure and the place of theme behavior in the frontend\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): another shared frontend subsystem with central configuration and runtime binding\n- [Localization and Locale Behavior](../../cross-cutting-systems/localization-and-locale-behavior/): shared UI-system rules that often change alongside settings and preferences surfaces\n", "0.9": "+++\ntitle = \"Theming System and Theme Selection\"\n+++\n\nSambee's theming system is centralized. Theme configuration, runtime state, persistence, and selection UI are all treated as one frontend subsystem.\n\nUse this page when you are changing palette behavior, adding a built-in theme, wiring a theme-aware component, or debugging why a selected theme is not applied consistently.\n\n## Main Pieces\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/theme/types.ts` | TypeScript theme interfaces and theme configuration shape |\n| `frontend/src/theme/themes.ts` | built-in theme definitions plus default-theme helpers |\n| `frontend/src/theme/ThemeContext.tsx` | runtime theme state, persistence, and theme switching |\n| `frontend/src/theme/index.ts` | public theme exports for the rest of the app |\n| `frontend/src/components/ThemeSelector.tsx` | theme-selection UI and dialog |\n| `frontend/src/components/themeSelectorStrings.ts` | localized strings and built-in-theme labels for the selector |\n\nThese pieces matter together. Theme behavior is not just a palette file or just a toolbar widget.\n\n## What the System Supports\n\nThe theme model currently supports:\n\n- built-in light and dark themes\n- persistent theme preferences\n- custom theme storage and runtime selection\n- theme-aware MUI palette generation\n- one shared provider that updates the app when the theme changes\n\n## Built-In Themes\n\nThe built-in themes live in `builtInThemes` in `frontend/src/theme/themes.ts`.\n\nCurrent built-ins include:\n\n- `sambee-light`: the default light branded theme\n- `sambee-dark`: the default dark branded theme\n\nThe helper functions contributors use most are:\n\n- `getDefaultTheme()`\n- `getDefaultTheme(\"light\")`\n- `getDefaultTheme(\"dark\")`\n- `getThemeById(id)`\n\nThe theme module also includes compile-time assertions around the default-theme indices so the expected built-in defaults cannot silently disappear.\n\n## Runtime Flow\n\nAt runtime, theme selection follows this path:\n\n1. the app renders inside `SambeeThemeProvider`\n2. the current theme ID is restored from persisted state when available\n3. built-in themes are resolved from code and combined with persisted custom themes\n4. `useSambeeTheme().setThemeById()` updates the active theme\n5. the selected theme is persisted\n6. the MUI theme instance updates and the UI re-renders\n\nThat is why a theme bug can look like a local component styling issue while actually being a context, persistence, or provider problem.\n\n## Theme Context Contract\n\n`useSambeeTheme()` is the main runtime entry point.\n\nContributors typically consume values such as:\n\n- `currentTheme`\n- `muiTheme`\n- `availableThemes`\n- `setThemeById`\n- `addCustomTheme`\n\nThe hook must be used inside `SambeeThemeProvider`. If you bypass that provider boundary, theme state becomes inconsistent immediately.\n\nRepresentative usage:\n\n```tsx\nimport { useSambeeTheme } from \"../theme\";\n\nfunction ThemeExample() {\n\tconst { currentTheme, setThemeById } = useSambeeTheme();\n\n\treturn (\n\t\t\u003cbutton onClick={() =\u003e setThemeById(\"sambee-dark\")}\u003e\n\t\t\tCurrent: {currentTheme.name}\n\t\t\u003c/button\u003e\n\t);\n}\n```\n\n## Theme Configuration Model\n\nThemes are expressed as typed configuration rather than ad hoc color overrides.\n\nThe palette surface includes areas such as:\n\n- `primary`\n- `secondary`\n- `background`\n- `text`\n- `action`\n\nCommon uses in the UI include:\n\n- default primary controls and selected navigation from `primary.main`\n- high-emphasis dark-mode states from `primary.light`\n- light-mode pressed and contrast-sensitive controls from `primary.dark`\n- page and standard application surfaces from `background.default`\n- readable foreground text from `text`\n- selection fills from `action.selected`\n\nMaterial UI also derives additional palette values such as divider color when enough base information is present.\n\n### Surface Policy\n\n`background.default` is the standard application surface. Use it for pages, standard dialogs, settings, and compact controls.\n\n`background.paper` remains populated at runtime because Material UI expects the token. Sambee normalizes it to `background.default`; application components should not select it as a separate surface.\n\nThe shared settings form surface is a deliberate derived exception: it darkens the default surface by 4% in light mode and lightens it by 8% in dark mode. Inside a dark dialog, it uses a 12% black mix of the actual dialog paper surface, preserving a warm but recessed form area; its outlined fields inherit the dialog paper surface to remain visually distinct from the surrounding form layer. Application chrome is another exception: light-mode AppBar and StatusBar use the primary color, while dark-mode chrome uses the shared opaque brown `#382c0a`. Standard Material UI Dialog papers and popup menus use that same opaque dark-mode color, preventing the backdrop from showing through. Fullscreen viewers retain their dedicated viewer surfaces. Dark dialog backdrops use a high-opacity neutral composite of `background.default`, preventing nested dialogs from tinting the surface behind them. Dialogs do not add an elevation shadow because the modal backdrop provides their separation. Menu selection, hover, and keyboard focus use `action.selected`.\n\nStandard Material UI Alerts use the theme's `components.alert` semantic colors for their info, success, warning, and error backgrounds, text, and icons. Apply alert semantics through the shared theme rather than per-component overrides.\n\n### Primary Palette Roles\n\n`primary.main` is the default primary control color. It should not be the brightest available shade in a dark theme, because Material UI applies it to contained buttons, radios, selected icons, and many other default controls.\n\nUse `primary.light` for brighter dark-mode hover and high-emphasis states. Use `primary.dark` for pressed and contrast-sensitive light-mode controls. Do not swap `main` and `dark` between modes: Material UI treats `dark` as the darker interaction shade.\n\nThe built-in dark theme uses a subdued golden `main`, a brighter golden `light`, and a darker pressed `dark` shade. The exact values live in `frontend/src/theme/themes.ts`.\n\n### Foreground Color Policy\n\nStandard application UI uses two base foreground roles:\n\n- `text.primary` is high-emphasis text: headings, selected or active labels, form values, selectable menu choices, file names, and information required to complete the current task.\n- `text.secondary` is the default supporting layer: descriptions, metadata, timestamps, helper copy, captions, inactive navigation icons, and other text that should be readable without competing with the task.\n\nThe built-in dark theme intentionally makes `text.secondary` a muted version of the warm primary text. This reduces glare during extended use while preserving a clear emphasis hierarchy. Use `text.disabled` for non-interactive content and dedicated palette roles such as `statusBar.textSecondary`, alert colors, and viewer toolbar colors when the surface has its own semantic contract.\n\nFor Material UI `Typography`, apply dotted palette roles through `sx`, for example `sx={{ color: \"text.secondary\" }}`. In this application's Material UI v9 configuration, `color=\"text.secondary\"` does not emit a palette color rule, so the element falls back to inherited text.\n\nIcons should inherit the role of their associated text. Use `currentColor` for adaptable inline SVG illustrations. Brand assets, file-type registry icons, document rendering, syntax highlighting, and semantic alerts are deliberate exceptions: their colors convey identity, content type, or state and should remain separately named rather than being forced into the general text palette.\n\n## Built-In Theme Characteristics\n\nThe current built-ins intentionally align with Sambee's branding.\n\n### Sambee Light\n\n- ID: `sambee-light`\n- mode: light\n- branded golden primary palette\n- cream-toned background\n- dark secondary contrast surface\n\n### Sambee Dark\n\n- ID: `sambee-dark`\n- mode: dark\n- branded golden primary palette\n- dark background\n- light secondary contrast surface\n\nThe exact palette values live in `frontend/src/theme/themes.ts`. Keep the docs focused on architectural meaning rather than duplicating every color token when the code is already authoritative.\n\n## Theme Selector UI\n\nThe visible selection UI lives in `frontend/src/components/ThemeSelector.tsx`.\n\nThe selector:\n\n- opens a dialog listing available themes\n- shows a preview of theme colors\n- uses localized strings through `themeSelectorStrings.ts`\n- calls `setThemeById` when the user changes themes\n\nThe selector is already integrated into the file-browser toolbar, and the current preferences UI also consumes the same theme state.\n\n## Persistence Model\n\nTheme preferences are persisted in local storage.\n\nThe main keys are:\n\n- `theme-id-current`: the currently selected theme ID\n- `themes-custom`: user-created custom themes\n\nThis matters for two reasons:\n\n- the selected theme survives reloads\n- built-in theme definitions can still be refreshed from code when the app updates\n\nThe system syncs built-in themes from code so users pick up reviewed built-in theme changes without losing their custom themes.\n\n## Custom Themes\n\nThe theme context supports custom themes in addition to the built-ins.\n\nThat means contributors should treat theme IDs, storage layout, and theme resolution as stable interfaces rather than temporary implementation details.\n\nWhen adding custom-theme features or editing persistence logic:\n\n- preserve separation between built-in and custom theme sets\n- keep the active theme valid even if a custom theme is removed\n- preserve a safe fallback to the default theme\n\nRepresentative pattern:\n\n```tsx\nimport { useSambeeTheme } from \"../theme\";\n\nfunction addExampleTheme() {\n\tconst { addCustomTheme } = useSambeeTheme();\n\n\taddCustomTheme({\n\t\tid: \"my-custom-theme\",\n\t\tname: \"My Custom Theme\",\n\t\tdescription: \"A unique theme\",\n\t\tmode: \"light\",\n\t\tprimary: { main: \"#ff6b6b\" },\n\t});\n}\n```\n\n## Theme Schema and Future Builder Support\n\n`frontend/src/theme/types.ts` also exports `THEME_SCHEMA`.\n\nThat schema is runtime-accessible metadata describing:\n\n- field types such as text, color, and select\n- labels and descriptions for UI\n- required versus optional fields\n- nested field definitions\n- select options such as `light` and `dark`\n\nNew custom themes should provide `primary.main` and may provide the other primary shades, background, text, and selection colors. The runtime resolver supplies stable mode-aware defaults for omitted optional fields so existing minimally configured themes remain valid.\n\n`action.focus`, `components.appBar`, and `components.statusBar` are honored for already persisted themes but are intentionally not exposed by `THEME_SCHEMA`. New themes derive those values from the palette contract.\n\nIt exists so future theme-builder tooling can generate forms and validation from one typed source instead of re-encoding theme structure in multiple places.\n\n## Theme-Aware Component Rules\n\nWhen building UI components:\n\n- use the active MUI theme instead of hard-coded surface and text colors when the style belongs to the app theme\n- use `text.primary` and `text.secondary` to establish normal UI hierarchy; do not recreate muted text with local opacity values\n- prefer `useTheme()` or the shared theme context rather than duplicating palette lookups manually\n- derive viewer toolbar borders, muted labels, disabled controls, and subtle fills from the configured toolbar text color\n- keep file-type icon colors and other intentionally non-theme registry colors separate from the app palette when they serve a different product purpose\n\nA theme-aware component typically reads from `theme.palette` and `theme.spacing` rather than introducing standalone constants.\n\n## Browser and PWA Integration\n\nThe theme system also updates the browser `theme-color` meta tag to match the selected theme's primary color.\n\nThat affects:\n\n- browser UI tinting on supported browsers\n- Android browser chrome behavior\n- installed PWA status-bar appearance\n\nIf a theme appears correct inside the app but wrong in browser chrome, check this integration path rather than only inspecting component styles.\n\n## Common Failure Modes\n\n- a component hard-codes colors that should come from the active theme\n- a new built-in theme is added without keeping default-theme helpers valid\n- theme state is read outside `SambeeThemeProvider`\n- a persistence change breaks fallback to the default theme\n- built-in theme updates and custom theme persistence start overwriting each other\n- contributors treat selector labels as static strings instead of localized UI copy\n\n## Validation Expectations\n\nWhen the theming system changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nPay particular attention to:\n\n- theme-provider tests under `frontend/src/theme/__tests__/`\n- built-in-theme and default-theme tests\n- `types.test.ts` coverage around `THEME_SCHEMA`\n- theme-selector tests under `frontend/src/components/__tests__/`\n- manual checks that text remains readable in both built-in themes\n\n## Where to Continue\n\n- [Frontend Overview](../frontend-overview/): broader browser-app structure and the place of theme behavior in the frontend\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): another shared frontend subsystem with central configuration and runtime binding\n- [Localization and Locale Behavior](../../cross-cutting-systems/localization-and-locale-behavior/): shared UI-system rules that often change alongside settings and preferences surfaces\n", "1.0": "+++\ntitle = \"Theming System and Theme Selection\"\n+++\n\nSambee's theming system is centralized. Theme configuration, runtime state, persistence, and selection UI are all treated as one frontend subsystem.\n\nUse this page when you are changing palette behavior, adding a built-in theme, wiring a theme-aware component, or debugging why a selected theme is not applied consistently.\n\n## Main Pieces\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/theme/types.ts` | TypeScript theme interfaces and theme configuration shape |\n| `frontend/src/theme/themes.ts` | built-in theme definitions plus default-theme helpers |\n| `frontend/src/theme/ThemeContext.tsx` | runtime theme state, persistence, and theme switching |\n| `frontend/src/theme/index.ts` | public theme exports for the rest of the app |\n| `frontend/src/components/ThemeSelector.tsx` | theme-selection UI and dialog |\n| `frontend/src/components/themeSelectorStrings.ts` | localized strings and built-in-theme labels for the selector |\n\nThese pieces matter together. Theme behavior is not just a palette file or just a toolbar widget.\n\n## What the System Supports\n\nThe theme model currently supports:\n\n- built-in light and dark themes\n- persistent theme preferences\n- custom theme storage and runtime selection\n- theme-aware MUI palette generation\n- one shared provider that updates the app when the theme changes\n\n## Built-In Themes\n\nThe built-in themes live in `builtInThemes` in `frontend/src/theme/themes.ts`.\n\nCurrent built-ins include:\n\n- `sambee-light`: the default light branded theme\n- `sambee-dark`: the default dark branded theme\n\nThe helper functions contributors use most are:\n\n- `getDefaultTheme()`\n- `getDefaultTheme(\"light\")`\n- `getDefaultTheme(\"dark\")`\n- `getThemeById(id)`\n\nThe theme module also includes compile-time assertions around the default-theme indices so the expected built-in defaults cannot silently disappear.\n\n## Runtime Flow\n\nAt runtime, theme selection follows this path:\n\n1. the app renders inside `SambeeThemeProvider`\n2. the current theme ID is restored from persisted state when available\n3. built-in themes are resolved from code and combined with persisted custom themes\n4. `useSambeeTheme().setThemeById()` updates the active theme\n5. the selected theme is persisted\n6. the MUI theme instance updates and the UI re-renders\n\nThat is why a theme bug can look like a local component styling issue while actually being a context, persistence, or provider problem.\n\n## Theme Context Contract\n\n`useSambeeTheme()` is the main runtime entry point.\n\nContributors typically consume values such as:\n\n- `currentTheme`\n- `muiTheme`\n- `availableThemes`\n- `setThemeById`\n- `addCustomTheme`\n\nThe hook must be used inside `SambeeThemeProvider`. If you bypass that provider boundary, theme state becomes inconsistent immediately.\n\nRepresentative usage:\n\n```tsx\nimport { useSambeeTheme } from \"../theme\";\n\nfunction ThemeExample() {\n\tconst { currentTheme, setThemeById } = useSambeeTheme();\n\n\treturn (\n\t\t\u003cbutton onClick={() =\u003e setThemeById(\"sambee-dark\")}\u003e\n\t\t\tCurrent: {currentTheme.name}\n\t\t\u003c/button\u003e\n\t);\n}\n```\n\n## Theme Configuration Model\n\nThemes are expressed as typed configuration rather than ad hoc color overrides.\n\nThe palette surface includes areas such as:\n\n- `primary`\n- `secondary`\n- `background`\n- `text`\n- `action`\n\nCommon uses in the UI include:\n\n- default primary controls and selected navigation from `primary.main`\n- high-emphasis dark-mode states from `primary.light`\n- light-mode pressed and contrast-sensitive controls from `primary.dark`\n- page and standard application surfaces from `background.default`\n- readable foreground text from `text`\n- selection fills from `action.selected`\n\nMaterial UI also derives additional palette values such as divider color when enough base information is present.\n\n### Surface Policy\n\n`background.default` is the standard application surface. Use it for pages, standard dialogs, settings, and compact controls.\n\n`background.paper` remains populated at runtime because Material UI expects the token. Sambee normalizes it to `background.default`; application components should not select it as a separate surface.\n\nThe shared settings form surface is a deliberate derived exception: it darkens the default surface by 4% in light mode and lightens it by 8% in dark mode. Inside a dark dialog, it uses a 12% black mix of the actual dialog paper surface, preserving a warm but recessed form area; its outlined fields inherit the dialog paper surface to remain visually distinct from the surrounding form layer. Application chrome is another exception: light-mode AppBar and StatusBar use the primary color, while dark-mode chrome uses the shared opaque brown `#382c0a`. Standard Material UI Dialog papers and popup menus use that same opaque dark-mode color, preventing the backdrop from showing through. Fullscreen viewers retain their dedicated viewer surfaces. Dark dialog backdrops use a high-opacity neutral composite of `background.default`, preventing nested dialogs from tinting the surface behind them. Dialogs do not add an elevation shadow because the modal backdrop provides their separation. Menu selection, hover, and keyboard focus use `action.selected`.\n\nStandard Material UI Alerts use the theme's `components.alert` semantic colors for their info, success, warning, and error backgrounds, text, and icons. Apply alert semantics through the shared theme rather than per-component overrides.\n\n### Primary Palette Roles\n\n`primary.main` is the default primary control color. It should not be the brightest available shade in a dark theme, because Material UI applies it to contained buttons, radios, selected icons, and many other default controls.\n\nUse `primary.light` for brighter dark-mode hover and high-emphasis states. Use `primary.dark` for pressed and contrast-sensitive light-mode controls. Do not swap `main` and `dark` between modes: Material UI treats `dark` as the darker interaction shade.\n\nThe built-in dark theme uses a subdued golden `main`, a brighter golden `light`, and a darker pressed `dark` shade. The exact values live in `frontend/src/theme/themes.ts`.\n\n### Foreground Color Policy\n\nStandard application UI uses two base foreground roles:\n\n- `text.primary` is high-emphasis text: headings, selected or active labels, form values, selectable menu choices, file names, and information required to complete the current task.\n- `text.secondary` is the default supporting layer: descriptions, metadata, timestamps, helper copy, captions, inactive navigation icons, and other text that should be readable without competing with the task.\n\nThe built-in dark theme intentionally makes `text.secondary` a muted version of the warm primary text. This reduces glare during extended use while preserving a clear emphasis hierarchy. Use `text.disabled` for non-interactive content and dedicated palette roles such as `statusBar.textSecondary`, alert colors, and viewer toolbar colors when the surface has its own semantic contract.\n\nFor Material UI `Typography`, apply dotted palette roles through `sx`, for example `sx={{ color: \"text.secondary\" }}`. In this application's Material UI v9 configuration, `color=\"text.secondary\"` does not emit a palette color rule, so the element falls back to inherited text.\n\nIcons should inherit the role of their associated text. Use `currentColor` for adaptable inline SVG illustrations. Brand assets, file-type registry icons, document rendering, syntax highlighting, and semantic alerts are deliberate exceptions: their colors convey identity, content type, or state and should remain separately named rather than being forced into the general text palette.\n\n## Built-In Theme Characteristics\n\nThe current built-ins intentionally align with Sambee's branding.\n\n### Sambee Light\n\n- ID: `sambee-light`\n- mode: light\n- branded golden primary palette\n- cream-toned background\n- dark secondary contrast surface\n\n### Sambee Dark\n\n- ID: `sambee-dark`\n- mode: dark\n- branded golden primary palette\n- dark background\n- light secondary contrast surface\n\nThe exact palette values live in `frontend/src/theme/themes.ts`. Keep the docs focused on architectural meaning rather than duplicating every color token when the code is already authoritative.\n\n## Theme Selector UI\n\nThe visible selection UI lives in `frontend/src/components/ThemeSelector.tsx`.\n\nThe selector:\n\n- opens a dialog listing available themes\n- shows a preview of theme colors\n- uses localized strings through `themeSelectorStrings.ts`\n- calls `setThemeById` when the user changes themes\n\nThe selector is already integrated into the file-browser toolbar, and the current preferences UI also consumes the same theme state.\n\n## Persistence Model\n\nTheme preferences are persisted in local storage.\n\nThe main keys are:\n\n- `theme-id-current`: the currently selected theme ID\n- `themes-custom`: user-created custom themes\n\nThis matters for two reasons:\n\n- the selected theme survives reloads\n- built-in theme definitions can still be refreshed from code when the app updates\n\nThe system syncs built-in themes from code so users pick up reviewed built-in theme changes without losing their custom themes.\n\n## Custom Themes\n\nThe theme context supports custom themes in addition to the built-ins.\n\nThat means contributors should treat theme IDs, storage layout, and theme resolution as stable interfaces rather than temporary implementation details.\n\nWhen adding custom-theme features or editing persistence logic:\n\n- preserve separation between built-in and custom theme sets\n- keep the active theme valid even if a custom theme is removed\n- preserve a safe fallback to the default theme\n\nRepresentative pattern:\n\n```tsx\nimport { useSambeeTheme } from \"../theme\";\n\nfunction addExampleTheme() {\n\tconst { addCustomTheme } = useSambeeTheme();\n\n\taddCustomTheme({\n\t\tid: \"my-custom-theme\",\n\t\tname: \"My Custom Theme\",\n\t\tdescription: \"A unique theme\",\n\t\tmode: \"light\",\n\t\tprimary: { main: \"#ff6b6b\" },\n\t});\n}\n```\n\n## Theme Schema and Future Builder Support\n\n`frontend/src/theme/types.ts` also exports `THEME_SCHEMA`.\n\nThat schema is runtime-accessible metadata describing:\n\n- field types such as text, color, and select\n- labels and descriptions for UI\n- required versus optional fields\n- nested field definitions\n- select options such as `light` and `dark`\n\nNew custom themes should provide `primary.main` and may provide the other primary shades, background, text, and selection colors. The runtime resolver supplies stable mode-aware defaults for omitted optional fields so existing minimally configured themes remain valid.\n\n`action.focus`, `components.appBar`, and `components.statusBar` are honored for already persisted themes but are intentionally not exposed by `THEME_SCHEMA`. New themes derive those values from the palette contract.\n\nIt exists so future theme-builder tooling can generate forms and validation from one typed source instead of re-encoding theme structure in multiple places.\n\n## Theme-Aware Component Rules\n\nWhen building UI components:\n\n- use the active MUI theme instead of hard-coded surface and text colors when the style belongs to the app theme\n- use `text.primary` and `text.secondary` to establish normal UI hierarchy; do not recreate muted text with local opacity values\n- prefer `useTheme()` or the shared theme context rather than duplicating palette lookups manually\n- derive viewer toolbar borders, muted labels, disabled controls, and subtle fills from the configured toolbar text color\n- keep file-type icon colors and other intentionally non-theme registry colors separate from the app palette when they serve a different product purpose\n\nA theme-aware component typically reads from `theme.palette` and `theme.spacing` rather than introducing standalone constants.\n\n## Browser and PWA Integration\n\nThe theme system also updates the browser `theme-color` meta tag to match the selected theme's primary color.\n\nThat affects:\n\n- browser UI tinting on supported browsers\n- Android browser chrome behavior\n- installed PWA status-bar appearance\n\nIf a theme appears correct inside the app but wrong in browser chrome, check this integration path rather than only inspecting component styles.\n\n## Common Failure Modes\n\n- a component hard-codes colors that should come from the active theme\n- a new built-in theme is added without keeping default-theme helpers valid\n- theme state is read outside `SambeeThemeProvider`\n- a persistence change breaks fallback to the default theme\n- built-in theme updates and custom theme persistence start overwriting each other\n- contributors treat selector labels as static strings instead of localized UI copy\n\n## Validation Expectations\n\nWhen the theming system changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nPay particular attention to:\n\n- theme-provider tests under `frontend/src/theme/__tests__/`\n- built-in-theme and default-theme tests\n- `types.test.ts` coverage around `THEME_SCHEMA`\n- theme-selector tests under `frontend/src/components/__tests__/`\n- manual checks that text remains readable in both built-in themes\n\n## Where to Continue\n\n- [Frontend Overview](../frontend-overview/): broader browser-app structure and the place of theme behavior in the frontend\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): another shared frontend subsystem with central configuration and runtime binding\n- [Localization and Locale Behavior](../../cross-cutting-systems/localization-and-locale-behavior/): shared UI-system rules that often change alongside settings and preferences surfaces\n", "2.0": "+++\ntitle = \"Theming System and Theme Selection\"\n+++\n\nSambee has two built-in themes (`sambee-light` and `sambee-dark`), user-owned themes, and administrator-managed site themes. Built-in IDs stay stable across upgrades, so updating their palettes doesn't change anyone's selection.\n\n## Theme Data\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/theme/types.ts` | Palette types and editor field labels |\n| `frontend/src/theme/themes.ts` | Built-in definitions with stable IDs |\n| `frontend/src/theme/themeDefinition.ts` | Editable color catalog, hex checks, and versioned import/export |\n| `frontend/src/theme/palette.ts` | Shared effective palette for the app |\n| `frontend/src/theme/viewerStyles.ts` | Viewer and Markdown document surfaces |\n| `frontend/src/theme/ThemeContext.tsx` | Registry refresh and Material UI theme |\n| `frontend/src/pages/PreferencesSettings.tsx` | Selection grid and selected-theme actions |\n| `frontend/src/components/Settings/ThemeEditorDialog.tsx` | Responsive theme editor |\n| `backend/app/api/themes.py` | Validated theme operations and site default |\n\nEach editable theme has its own server row with a globally unique ID, scope, owner (for user themes), and version. Built-in definitions remain in frontend code. A new theme ID is assigned by the server; an ID in an imported file does not claim or replace a stored theme.\n\nNew and imported themes must define every editable color role. Colors use `#RRGGBB` or `#RRGGBBAA`; the server normalizes valid hex to uppercase. The role catalog includes primary, backgrounds, text, selection, links, viewer surfaces, Markdown document surfaces, search highlights, and alerts. File-type icons and document syntax colors aren't theme roles. Derived colors such as scrollbar shades, focus rings, and `background.paper` compatibility aren't editor fields. Keyboard focus rings follow the theme's primary text color: 57% opacity in light mode and 94% in dark mode. Changing that text color changes the focus color too, including in copied themes; legacy saved focus colors are ignored. Choose primary text that remains readable against the theme's surfaces.\n\n## Selection And Defaults\n\n`SambeeThemeProvider` combines built-ins with the current user's themes and shared site themes from `GET /api/themes`. The per-user selection is saved separately through `appearance.theme_id` in `PUT /api/auth/me/settings`. The backend reports whether that value is an explicit override.\n\nA user without an override follows the site default (initially `sambee-light`). A user who explicitly chooses `sambee-light` keeps that ID even if an administrator changes the site default. The selected ID points at a theme definition, never at a frozen copy of a built-in. The provider refreshes shared themes, the default, and user settings on initial load, tab focus, visibility return, and local writes. It discards out-of-date responses when the account changes.\n\nAppearance settings display Your themes, Site themes, then Built-in themes. Clicking a tile or selecting its radio applies the theme and creates an explicit user override, even when it already matches the site default. Moving focus between radios doesn't change the applied theme or the target of Copy, Edit, Delete, and Set as default. The Default chip is distinct from the selected radio. Copy keeps writable themes in their group and copies read-only themes into Your themes without applying the copy. Editing read-only themes permits inspection and Save copy, but not Save. Only an administrator can save or delete site themes or make a built-in or site theme the default.\n\n## Editing And Persistence\n\nThe editor uses a responsive dialog with collapsible color groups. A swatch opens an alpha-aware picker and each color has an editable hex field. Invalid text stays in the field without changing the valid draft. Changes in the editor aren't applied to the app until Save succeeds; Cancel discards the draft. Import replaces only the draft after validating a versioned JSON definition, and Export writes the same format.\n\n`POST /api/themes` creates a theme. Save copy opens a destination menu with Your themes for everyone and Site themes for administrators. It always creates a new theme in the chosen group without changing the applied selection. If its name already exists in that group, the editor adds ` (copy)` or a numbered copy suffix. Save updates only the opened theme in its existing group and cannot create a copy. `PUT /api/themes/{id}` and `DELETE /api/themes/{id}?version=...` require the version read by the client; a stale version returns HTTP 409. The server checks ownership, admin permissions, names, IDs, and palette completeness before committing. Bulk writes to `appearance.custom_themes` are no longer supported. There is no migration of older custom themes or compatibility promise for older exports.\n\nDeleting a theme clears explicit selections referencing it. If it was the site default, that setting is cleared too; users without an override then fall back to Sambee light. An explicit selection of another theme is unaffected.\n\n## Component Guidance\n\nPrefer the effective colors in `resolveThemePalette` and the MUI palette to hard-coded surfaces. `background.default` is the normal application surface; `background.paper` resolves to the same value for MUI compatibility. Dark chrome and dialogs use the editable `background.chrome` role. Markdown code, tables, blockquotes, and heading borders use the built-in theme's explicit document colors.\n\nViewer toolbar foreground variants, scrollbars, and subdued states can still derive opacity-adjusted values from their source color. Keep fixed colors for assets, syntax/content rendering, and file-type icons separate from the editor palette.\n\n## Verification\n\nRun focused theme tests and the project checks after changing the palette, API, or editor:\n\n```bash\ncd frontend \u0026\u0026 npm run test -- src/theme/__tests__ src/pages/__tests__/PreferencesSettings.test.tsx\ncd frontend \u0026\u0026 npm run build \u0026\u0026 npm run lint\ncd backend \u0026\u0026 .venv/bin/python -m pytest tests/test_user_settings.py\n```\n\nCheck the Appearance grid and editor on a phone and desktop in both built-in modes. Verify selection and saved-theme refresh after focus, color picker keyboard use and placement, alpha values and export, Cancel without applying the draft, and stale-save feedback.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Theming System and Theme Selection\"\n+++\n\nSambee's theming system is centralized. Theme configuration, runtime state, persistence, and selection UI are all treated as one frontend subsystem.\n\nUse this page when you are changing palette behavior, adding a built-in theme, wiring a theme-aware component, or debugging why a selected theme is not applied consistently.\n\n## Main Pieces\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/theme/types.ts` | TypeScript theme interfaces and theme configuration shape |\n| `frontend/src/theme/themes.ts` | built-in theme definitions plus default-theme helpers |\n| `frontend/src/theme/ThemeContext.tsx` | runtime theme state, persistence, and theme switching |\n| `frontend/src/theme/index.ts` | public theme exports for the rest of the app |\n| `frontend/src/components/ThemeSelector.tsx` | theme-selection UI and dialog |\n| `frontend/src/components/themeSelectorStrings.ts` | localized strings and built-in-theme labels for the selector |\n\nThese pieces matter together. Theme behavior is not just a palette file or just a toolbar widget.\n\n## What the System Supports\n\nThe theme model currently supports:\n\n- built-in light and dark themes\n- persistent theme preferences\n- custom theme storage and runtime selection\n- theme-aware MUI palette generation\n- one shared provider that updates the app when the theme changes\n\n## Built-In Themes\n\nThe built-in themes live in `builtInThemes` in `frontend/src/theme/themes.ts`.\n\nCurrent built-ins include:\n\n- `sambee-light`: the default light branded theme\n- `sambee-dark`: the default dark branded theme\n\nThe helper functions contributors use most are:\n\n- `getDefaultTheme()`\n- `getDefaultTheme(\"light\")`\n- `getDefaultTheme(\"dark\")`\n- `getThemeById(id)`\n\nThe theme module also includes compile-time assertions around the default-theme indices so the expected built-in defaults cannot silently disappear.\n\n## Runtime Flow\n\nAt runtime, theme selection follows this path:\n\n1. the app renders inside `SambeeThemeProvider`\n2. the current theme ID is restored from persisted state when available\n3. built-in themes are resolved from code and combined with persisted custom themes\n4. `useSambeeTheme().setThemeById()` updates the active theme\n5. the selected theme is persisted\n6. the MUI theme instance updates and the UI re-renders\n\nThat is why a theme bug can look like a local component styling issue while actually being a context, persistence, or provider problem.\n\n## Theme Context Contract\n\n`useSambeeTheme()` is the main runtime entry point.\n\nContributors typically consume values such as:\n\n- `currentTheme`\n- `muiTheme`\n- `availableThemes`\n- `setThemeById`\n- `addCustomTheme`\n\nThe hook must be used inside `SambeeThemeProvider`. If you bypass that provider boundary, theme state becomes inconsistent immediately.\n\nRepresentative usage:\n\n```tsx\nimport { useSambeeTheme } from \"../theme\";\n\nfunction ThemeExample() {\n\tconst { currentTheme, setThemeById } = useSambeeTheme();\n\n\treturn (\n\t\t\u003cbutton onClick={() =\u003e setThemeById(\"sambee-dark\")}\u003e\n\t\t\tCurrent: {currentTheme.name}\n\t\t\u003c/button\u003e\n\t);\n}\n```\n\n## Theme Configuration Model\n\nThemes are expressed as typed configuration rather than ad hoc color overrides.\n\nThe palette surface includes areas such as:\n\n- `primary`\n- `secondary`\n- `background`\n- `text`\n- `action`\n\nCommon uses in the UI include:\n\n- directory emphasis and action colors from `primary`\n- page and surface backgrounds from `background`\n- readable foreground text from `text`\n- hover and selection states from `action`\n\nMaterial UI also derives additional palette values such as divider color when enough base information is present.\n\n## Built-In Theme Characteristics\n\nThe current built-ins intentionally align with Sambee's branding.\n\n### Sambee Light\n\n- ID: `sambee-light`\n- mode: light\n- branded golden primary palette\n- cream-toned background\n- dark secondary contrast surface\n\n### Sambee Dark\n\n- ID: `sambee-dark`\n- mode: dark\n- branded golden primary palette\n- dark background\n- light secondary contrast surface\n\nThe exact palette values live in `frontend/src/theme/themes.ts`. Keep the docs focused on architectural meaning rather than duplicating every color token when the code is already authoritative.\n\n## Theme Selector UI\n\nThe visible selection UI lives in `frontend/src/components/ThemeSelector.tsx`.\n\nThe selector:\n\n- opens a dialog listing available themes\n- shows a preview of theme colors\n- uses localized strings through `themeSelectorStrings.ts`\n- calls `setThemeById` when the user changes themes\n\nThe selector is already integrated into the file-browser toolbar, and the current preferences UI also consumes the same theme state.\n\n## Persistence Model\n\nTheme preferences are persisted in local storage.\n\nThe main keys are:\n\n- `theme-id-current`: the currently selected theme ID\n- `themes-builtin`: built-in themes as last synchronized from code\n- `themes-custom`: user-created custom themes\n\nThis matters for two reasons:\n\n- the selected theme survives reloads\n- built-in theme definitions can still be refreshed from code when the app updates\n\nThe system syncs built-in themes from code so users pick up reviewed built-in theme changes without losing their custom themes.\n\n## Custom Themes\n\nThe theme context supports custom themes in addition to the built-ins.\n\nThat means contributors should treat theme IDs, storage layout, and theme resolution as stable interfaces rather than temporary implementation details.\n\nWhen adding custom-theme features or editing persistence logic:\n\n- preserve separation between built-in and custom theme sets\n- keep the active theme valid even if a custom theme is removed\n- preserve a safe fallback to the default theme\n\nRepresentative pattern:\n\n```tsx\nimport { useSambeeTheme } from \"../theme\";\n\nfunction addExampleTheme() {\n\tconst { addCustomTheme } = useSambeeTheme();\n\n\taddCustomTheme({\n\t\tid: \"my-custom-theme\",\n\t\tname: \"My Custom Theme\",\n\t\tdescription: \"A unique theme\",\n\t\tmode: \"light\",\n\t\tprimary: { main: \"#ff6b6b\" },\n\t\tsecondary: { main: \"#4ecdc4\" },\n\t});\n}\n```\n\n## Theme Schema and Future Builder Support\n\n`frontend/src/theme/types.ts` also exports `THEME_SCHEMA`.\n\nThat schema is runtime-accessible metadata describing:\n\n- field types such as text, color, and select\n- labels and descriptions for UI\n- required versus optional fields\n- nested field definitions\n- select options such as `light` and `dark`\n\nIt exists so future theme-builder tooling can generate forms and validation from one typed source instead of re-encoding theme structure in multiple places.\n\n## Theme-Aware Component Rules\n\nWhen building UI components:\n\n- use the active MUI theme instead of hard-coded surface and text colors when the style belongs to the app theme\n- prefer `useTheme()` or the shared theme context rather than duplicating palette lookups manually\n- keep file-type icon colors and other intentionally non-theme registry colors separate from the app palette when they serve a different product purpose\n\nA theme-aware component typically reads from `theme.palette` and `theme.spacing` rather than introducing standalone constants.\n\n## Browser and PWA Integration\n\nThe theme system also updates the browser `theme-color` meta tag to match the selected theme's primary color.\n\nThat affects:\n\n- browser UI tinting on supported browsers\n- Android browser chrome behavior\n- installed PWA status-bar appearance\n\nIf a theme appears correct inside the app but wrong in browser chrome, check this integration path rather than only inspecting component styles.\n\n## Common Failure Modes\n\n- a component hard-codes colors that should come from the active theme\n- a new built-in theme is added without keeping default-theme helpers valid\n- theme state is read outside `SambeeThemeProvider`\n- a persistence change breaks fallback to the default theme\n- built-in theme updates and custom theme persistence start overwriting each other\n- contributors treat selector labels as static strings instead of localized UI copy\n\n## Validation Expectations\n\nWhen the theming system changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nPay particular attention to:\n\n- theme-provider tests under `frontend/src/theme/__tests__/`\n- built-in-theme and default-theme tests\n- `types.test.ts` coverage around `THEME_SCHEMA`\n- theme-selector tests under `frontend/src/components/__tests__/`\n- manual checks that text remains readable in both built-in themes\n\n## Where to Continue\n\n- [Frontend Overview](../frontend-overview/): broader browser-app structure and the place of theme behavior in the frontend\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): another shared frontend subsystem with central configuration and runtime binding\n- [Localization and Locale Behavior](../../cross-cutting-systems/localization-and-locale-behavior/): shared UI-system rules that often change alongside settings and preferences surfaces\n", "0.8": "+++\ntitle = \"Theming System and Theme Selection\"\n+++\n\nSambee's theming system is centralized. Theme configuration, runtime state, persistence, and selection UI are all treated as one frontend subsystem.\n\nUse this page when you are changing palette behavior, adding a built-in theme, wiring a theme-aware component, or debugging why a selected theme is not applied consistently.\n\n## Main Pieces\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/theme/types.ts` | TypeScript theme interfaces and theme configuration shape |\n| `frontend/src/theme/themes.ts` | built-in theme definitions plus default-theme helpers |\n| `frontend/src/theme/ThemeContext.tsx` | runtime theme state, persistence, and theme switching |\n| `frontend/src/theme/index.ts` | public theme exports for the rest of the app |\n| `frontend/src/components/ThemeSelector.tsx` | theme-selection UI and dialog |\n| `frontend/src/components/themeSelectorStrings.ts` | localized strings and built-in-theme labels for the selector |\n\nThese pieces matter together. Theme behavior is not just a palette file or just a toolbar widget.\n\n## What the System Supports\n\nThe theme model currently supports:\n\n- built-in light and dark themes\n- persistent theme preferences\n- custom theme storage and runtime selection\n- theme-aware MUI palette generation\n- one shared provider that updates the app when the theme changes\n\n## Built-In Themes\n\nThe built-in themes live in `builtInThemes` in `frontend/src/theme/themes.ts`.\n\nCurrent built-ins include:\n\n- `sambee-light`: the default light branded theme\n- `sambee-dark`: the default dark branded theme\n\nThe helper functions contributors use most are:\n\n- `getDefaultTheme()`\n- `getDefaultTheme(\"light\")`\n- `getDefaultTheme(\"dark\")`\n- `getThemeById(id)`\n\nThe theme module also includes compile-time assertions around the default-theme indices so the expected built-in defaults cannot silently disappear.\n\n## Runtime Flow\n\nAt runtime, theme selection follows this path:\n\n1. the app renders inside `SambeeThemeProvider`\n2. the current theme ID is restored from persisted state when available\n3. built-in themes are resolved from code and combined with persisted custom themes\n4. `useSambeeTheme().setThemeById()` updates the active theme\n5. the selected theme is persisted\n6. the MUI theme instance updates and the UI re-renders\n\nThat is why a theme bug can look like a local component styling issue while actually being a context, persistence, or provider problem.\n\n## Theme Context Contract\n\n`useSambeeTheme()` is the main runtime entry point.\n\nContributors typically consume values such as:\n\n- `currentTheme`\n- `muiTheme`\n- `availableThemes`\n- `setThemeById`\n- `addCustomTheme`\n\nThe hook must be used inside `SambeeThemeProvider`. If you bypass that provider boundary, theme state becomes inconsistent immediately.\n\nRepresentative usage:\n\n```tsx\nimport { useSambeeTheme } from \"../theme\";\n\nfunction ThemeExample() {\n\tconst { currentTheme, setThemeById } = useSambeeTheme();\n\n\treturn (\n\t\t\u003cbutton onClick={() =\u003e setThemeById(\"sambee-dark\")}\u003e\n\t\t\tCurrent: {currentTheme.name}\n\t\t\u003c/button\u003e\n\t);\n}\n```\n\n## Theme Configuration Model\n\nThemes are expressed as typed configuration rather than ad hoc color overrides.\n\nThe palette surface includes areas such as:\n\n- `primary`\n- `secondary`\n- `background`\n- `text`\n- `action`\n\nCommon uses in the UI include:\n\n- directory emphasis and action colors from `primary`\n- page and surface backgrounds from `background`\n- readable foreground text from `text`\n- hover and selection states from `action`\n\nMaterial UI also derives additional palette values such as divider color when enough base information is present.\n\n## Built-In Theme Characteristics\n\nThe current built-ins intentionally align with Sambee's branding.\n\n### Sambee Light\n\n- ID: `sambee-light`\n- mode: light\n- branded golden primary palette\n- cream-toned background\n- dark secondary contrast surface\n\n### Sambee Dark\n\n- ID: `sambee-dark`\n- mode: dark\n- branded golden primary palette\n- dark background\n- light secondary contrast surface\n\nThe exact palette values live in `frontend/src/theme/themes.ts`. Keep the docs focused on architectural meaning rather than duplicating every color token when the code is already authoritative.\n\n## Theme Selector UI\n\nThe visible selection UI lives in `frontend/src/components/ThemeSelector.tsx`.\n\nThe selector:\n\n- opens a dialog listing available themes\n- shows a preview of theme colors\n- uses localized strings through `themeSelectorStrings.ts`\n- calls `setThemeById` when the user changes themes\n\nThe selector is already integrated into the file-browser toolbar, and the current preferences UI also consumes the same theme state.\n\n## Persistence Model\n\nTheme preferences are persisted in local storage.\n\nThe main keys are:\n\n- `theme-id-current`: the currently selected theme ID\n- `themes-builtin`: built-in themes as last synchronized from code\n- `themes-custom`: user-created custom themes\n\nThis matters for two reasons:\n\n- the selected theme survives reloads\n- built-in theme definitions can still be refreshed from code when the app updates\n\nThe system syncs built-in themes from code so users pick up reviewed built-in theme changes without losing their custom themes.\n\n## Custom Themes\n\nThe theme context supports custom themes in addition to the built-ins.\n\nThat means contributors should treat theme IDs, storage layout, and theme resolution as stable interfaces rather than temporary implementation details.\n\nWhen adding custom-theme features or editing persistence logic:\n\n- preserve separation between built-in and custom theme sets\n- keep the active theme valid even if a custom theme is removed\n- preserve a safe fallback to the default theme\n\nRepresentative pattern:\n\n```tsx\nimport { useSambeeTheme } from \"../theme\";\n\nfunction addExampleTheme() {\n\tconst { addCustomTheme } = useSambeeTheme();\n\n\taddCustomTheme({\n\t\tid: \"my-custom-theme\",\n\t\tname: \"My Custom Theme\",\n\t\tdescription: \"A unique theme\",\n\t\tmode: \"light\",\n\t\tprimary: { main: \"#ff6b6b\" },\n\t\tsecondary: { main: \"#4ecdc4\" },\n\t});\n}\n```\n\n## Theme Schema and Future Builder Support\n\n`frontend/src/theme/types.ts` also exports `THEME_SCHEMA`.\n\nThat schema is runtime-accessible metadata describing:\n\n- field types such as text, color, and select\n- labels and descriptions for UI\n- required versus optional fields\n- nested field definitions\n- select options such as `light` and `dark`\n\nIt exists so future theme-builder tooling can generate forms and validation from one typed source instead of re-encoding theme structure in multiple places.\n\n## Theme-Aware Component Rules\n\nWhen building UI components:\n\n- use the active MUI theme instead of hard-coded surface and text colors when the style belongs to the app theme\n- prefer `useTheme()` or the shared theme context rather than duplicating palette lookups manually\n- keep file-type icon colors and other intentionally non-theme registry colors separate from the app palette when they serve a different product purpose\n\nA theme-aware component typically reads from `theme.palette` and `theme.spacing` rather than introducing standalone constants.\n\n## Browser and PWA Integration\n\nThe theme system also updates the browser `theme-color` meta tag to match the selected theme's primary color.\n\nThat affects:\n\n- browser UI tinting on supported browsers\n- Android browser chrome behavior\n- installed PWA status-bar appearance\n\nIf a theme appears correct inside the app but wrong in browser chrome, check this integration path rather than only inspecting component styles.\n\n## Common Failure Modes\n\n- a component hard-codes colors that should come from the active theme\n- a new built-in theme is added without keeping default-theme helpers valid\n- theme state is read outside `SambeeThemeProvider`\n- a persistence change breaks fallback to the default theme\n- built-in theme updates and custom theme persistence start overwriting each other\n- contributors treat selector labels as static strings instead of localized UI copy\n\n## Validation Expectations\n\nWhen the theming system changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nPay particular attention to:\n\n- theme-provider tests under `frontend/src/theme/__tests__/`\n- built-in-theme and default-theme tests\n- `types.test.ts` coverage around `THEME_SCHEMA`\n- theme-selector tests under `frontend/src/components/__tests__/`\n- manual checks that text remains readable in both built-in themes\n\n## Where to Continue\n\n- [Frontend Overview](../frontend-overview/): broader browser-app structure and the place of theme behavior in the frontend\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): another shared frontend subsystem with central configuration and runtime binding\n- [Localization and Locale Behavior](../../cross-cutting-systems/localization-and-locale-behavior/): shared UI-system rules that often change alongside settings and preferences surfaces\n", "0.9": "+++\ntitle = \"Theming System and Theme Selection\"\n+++\n\nSambee's theming system is centralized. Theme configuration, runtime state, persistence, and selection UI are all treated as one frontend subsystem.\n\nUse this page when you are changing palette behavior, adding a built-in theme, wiring a theme-aware component, or debugging why a selected theme is not applied consistently.\n\n## Main Pieces\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/theme/types.ts` | TypeScript theme interfaces and theme configuration shape |\n| `frontend/src/theme/themes.ts` | built-in theme definitions plus default-theme helpers |\n| `frontend/src/theme/ThemeContext.tsx` | runtime theme state, persistence, and theme switching |\n| `frontend/src/theme/index.ts` | public theme exports for the rest of the app |\n| `frontend/src/components/ThemeSelector.tsx` | theme-selection UI and dialog |\n| `frontend/src/components/themeSelectorStrings.ts` | localized strings and built-in-theme labels for the selector |\n\nThese pieces matter together. Theme behavior is not just a palette file or just a toolbar widget.\n\n## What the System Supports\n\nThe theme model currently supports:\n\n- built-in light and dark themes\n- persistent theme preferences\n- custom theme storage and runtime selection\n- theme-aware MUI palette generation\n- one shared provider that updates the app when the theme changes\n\n## Built-In Themes\n\nThe built-in themes live in `builtInThemes` in `frontend/src/theme/themes.ts`.\n\nCurrent built-ins include:\n\n- `sambee-light`: the default light branded theme\n- `sambee-dark`: the default dark branded theme\n\nThe helper functions contributors use most are:\n\n- `getDefaultTheme()`\n- `getDefaultTheme(\"light\")`\n- `getDefaultTheme(\"dark\")`\n- `getThemeById(id)`\n\nThe theme module also includes compile-time assertions around the default-theme indices so the expected built-in defaults cannot silently disappear.\n\n## Runtime Flow\n\nAt runtime, theme selection follows this path:\n\n1. the app renders inside `SambeeThemeProvider`\n2. the current theme ID is restored from persisted state when available\n3. built-in themes are resolved from code and combined with persisted custom themes\n4. `useSambeeTheme().setThemeById()` updates the active theme\n5. the selected theme is persisted\n6. the MUI theme instance updates and the UI re-renders\n\nThat is why a theme bug can look like a local component styling issue while actually being a context, persistence, or provider problem.\n\n## Theme Context Contract\n\n`useSambeeTheme()` is the main runtime entry point.\n\nContributors typically consume values such as:\n\n- `currentTheme`\n- `muiTheme`\n- `availableThemes`\n- `setThemeById`\n- `addCustomTheme`\n\nThe hook must be used inside `SambeeThemeProvider`. If you bypass that provider boundary, theme state becomes inconsistent immediately.\n\nRepresentative usage:\n\n```tsx\nimport { useSambeeTheme } from \"../theme\";\n\nfunction ThemeExample() {\n\tconst { currentTheme, setThemeById } = useSambeeTheme();\n\n\treturn (\n\t\t\u003cbutton onClick={() =\u003e setThemeById(\"sambee-dark\")}\u003e\n\t\t\tCurrent: {currentTheme.name}\n\t\t\u003c/button\u003e\n\t);\n}\n```\n\n## Theme Configuration Model\n\nThemes are expressed as typed configuration rather than ad hoc color overrides.\n\nThe palette surface includes areas such as:\n\n- `primary`\n- `secondary`\n- `background`\n- `text`\n- `action`\n\nCommon uses in the UI include:\n\n- default primary controls and selected navigation from `primary.main`\n- high-emphasis dark-mode states from `primary.light`\n- light-mode pressed and contrast-sensitive controls from `primary.dark`\n- page and standard application surfaces from `background.default`\n- readable foreground text from `text`\n- selection fills from `action.selected`\n\nMaterial UI also derives additional palette values such as divider color when enough base information is present.\n\n### Surface Policy\n\n`background.default` is the standard application surface. Use it for pages, standard dialogs, settings, and compact controls.\n\n`background.paper` remains populated at runtime because Material UI expects the token. Sambee normalizes it to `background.default`; application components should not select it as a separate surface.\n\nThe shared settings form surface is a deliberate derived exception: it darkens the default surface by 4% in light mode and lightens it by 8% in dark mode. Inside a dark dialog, it uses a 12% black mix of the actual dialog paper surface, preserving a warm but recessed form area; its outlined fields inherit the dialog paper surface to remain visually distinct from the surrounding form layer. Application chrome is another exception: light-mode AppBar and StatusBar use the primary color, while dark-mode chrome uses the shared opaque brown `#382c0a`. Standard Material UI Dialog papers and popup menus use that same opaque dark-mode color, preventing the backdrop from showing through. Fullscreen viewers retain their dedicated viewer surfaces. Dark dialog backdrops use a high-opacity neutral composite of `background.default`, preventing nested dialogs from tinting the surface behind them. Dialogs do not add an elevation shadow because the modal backdrop provides their separation. Menu selection, hover, and keyboard focus use `action.selected`.\n\nStandard Material UI Alerts use the theme's `components.alert` semantic colors for their info, success, warning, and error backgrounds, text, and icons. Apply alert semantics through the shared theme rather than per-component overrides.\n\n### Primary Palette Roles\n\n`primary.main` is the default primary control color. It should not be the brightest available shade in a dark theme, because Material UI applies it to contained buttons, radios, selected icons, and many other default controls.\n\nUse `primary.light` for brighter dark-mode hover and high-emphasis states. Use `primary.dark` for pressed and contrast-sensitive light-mode controls. Do not swap `main` and `dark` between modes: Material UI treats `dark` as the darker interaction shade.\n\nThe built-in dark theme uses a subdued golden `main`, a brighter golden `light`, and a darker pressed `dark` shade. The exact values live in `frontend/src/theme/themes.ts`.\n\n### Foreground Color Policy\n\nStandard application UI uses two base foreground roles:\n\n- `text.primary` is high-emphasis text: headings, selected or active labels, form values, selectable menu choices, file names, and information required to complete the current task.\n- `text.secondary` is the default supporting layer: descriptions, metadata, timestamps, helper copy, captions, inactive navigation icons, and other text that should be readable without competing with the task.\n\nThe built-in dark theme intentionally makes `text.secondary` a muted version of the warm primary text. This reduces glare during extended use while preserving a clear emphasis hierarchy. Use `text.disabled` for non-interactive content and dedicated palette roles such as `statusBar.textSecondary`, alert colors, and viewer toolbar colors when the surface has its own semantic contract.\n\nFor Material UI `Typography`, apply dotted palette roles through `sx`, for example `sx={{ color: \"text.secondary\" }}`. In this application's Material UI v9 configuration, `color=\"text.secondary\"` does not emit a palette color rule, so the element falls back to inherited text.\n\nIcons should inherit the role of their associated text. Use `currentColor` for adaptable inline SVG illustrations. Brand assets, file-type registry icons, document rendering, syntax highlighting, and semantic alerts are deliberate exceptions: their colors convey identity, content type, or state and should remain separately named rather than being forced into the general text palette.\n\n## Built-In Theme Characteristics\n\nThe current built-ins intentionally align with Sambee's branding.\n\n### Sambee Light\n\n- ID: `sambee-light`\n- mode: light\n- branded golden primary palette\n- cream-toned background\n- dark secondary contrast surface\n\n### Sambee Dark\n\n- ID: `sambee-dark`\n- mode: dark\n- branded golden primary palette\n- dark background\n- light secondary contrast surface\n\nThe exact palette values live in `frontend/src/theme/themes.ts`. Keep the docs focused on architectural meaning rather than duplicating every color token when the code is already authoritative.\n\n## Theme Selector UI\n\nThe visible selection UI lives in `frontend/src/components/ThemeSelector.tsx`.\n\nThe selector:\n\n- opens a dialog listing available themes\n- shows a preview of theme colors\n- uses localized strings through `themeSelectorStrings.ts`\n- calls `setThemeById` when the user changes themes\n\nThe selector is already integrated into the file-browser toolbar, and the current preferences UI also consumes the same theme state.\n\n## Persistence Model\n\nTheme preferences are persisted in local storage.\n\nThe main keys are:\n\n- `theme-id-current`: the currently selected theme ID\n- `themes-custom`: user-created custom themes\n\nThis matters for two reasons:\n\n- the selected theme survives reloads\n- built-in theme definitions can still be refreshed from code when the app updates\n\nThe system syncs built-in themes from code so users pick up reviewed built-in theme changes without losing their custom themes.\n\n## Custom Themes\n\nThe theme context supports custom themes in addition to the built-ins.\n\nThat means contributors should treat theme IDs, storage layout, and theme resolution as stable interfaces rather than temporary implementation details.\n\nWhen adding custom-theme features or editing persistence logic:\n\n- preserve separation between built-in and custom theme sets\n- keep the active theme valid even if a custom theme is removed\n- preserve a safe fallback to the default theme\n\nRepresentative pattern:\n\n```tsx\nimport { useSambeeTheme } from \"../theme\";\n\nfunction addExampleTheme() {\n\tconst { addCustomTheme } = useSambeeTheme();\n\n\taddCustomTheme({\n\t\tid: \"my-custom-theme\",\n\t\tname: \"My Custom Theme\",\n\t\tdescription: \"A unique theme\",\n\t\tmode: \"light\",\n\t\tprimary: { main: \"#ff6b6b\" },\n\t});\n}\n```\n\n## Theme Schema and Future Builder Support\n\n`frontend/src/theme/types.ts` also exports `THEME_SCHEMA`.\n\nThat schema is runtime-accessible metadata describing:\n\n- field types such as text, color, and select\n- labels and descriptions for UI\n- required versus optional fields\n- nested field definitions\n- select options such as `light` and `dark`\n\nNew custom themes should provide `primary.main` and may provide the other primary shades, background, text, and selection colors. The runtime resolver supplies stable mode-aware defaults for omitted optional fields so existing minimally configured themes remain valid.\n\n`action.focus`, `components.appBar`, and `components.statusBar` are honored for already persisted themes but are intentionally not exposed by `THEME_SCHEMA`. New themes derive those values from the palette contract.\n\nIt exists so future theme-builder tooling can generate forms and validation from one typed source instead of re-encoding theme structure in multiple places.\n\n## Theme-Aware Component Rules\n\nWhen building UI components:\n\n- use the active MUI theme instead of hard-coded surface and text colors when the style belongs to the app theme\n- use `text.primary` and `text.secondary` to establish normal UI hierarchy; do not recreate muted text with local opacity values\n- prefer `useTheme()` or the shared theme context rather than duplicating palette lookups manually\n- derive viewer toolbar borders, muted labels, disabled controls, and subtle fills from the configured toolbar text color\n- keep file-type icon colors and other intentionally non-theme registry colors separate from the app palette when they serve a different product purpose\n\nA theme-aware component typically reads from `theme.palette` and `theme.spacing` rather than introducing standalone constants.\n\n## Browser and PWA Integration\n\nThe theme system also updates the browser `theme-color` meta tag to match the selected theme's primary color.\n\nThat affects:\n\n- browser UI tinting on supported browsers\n- Android browser chrome behavior\n- installed PWA status-bar appearance\n\nIf a theme appears correct inside the app but wrong in browser chrome, check this integration path rather than only inspecting component styles.\n\n## Common Failure Modes\n\n- a component hard-codes colors that should come from the active theme\n- a new built-in theme is added without keeping default-theme helpers valid\n- theme state is read outside `SambeeThemeProvider`\n- a persistence change breaks fallback to the default theme\n- built-in theme updates and custom theme persistence start overwriting each other\n- contributors treat selector labels as static strings instead of localized UI copy\n\n## Validation Expectations\n\nWhen the theming system changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nPay particular attention to:\n\n- theme-provider tests under `frontend/src/theme/__tests__/`\n- built-in-theme and default-theme tests\n- `types.test.ts` coverage around `THEME_SCHEMA`\n- theme-selector tests under `frontend/src/components/__tests__/`\n- manual checks that text remains readable in both built-in themes\n\n## Where to Continue\n\n- [Frontend Overview](../frontend-overview/): broader browser-app structure and the place of theme behavior in the frontend\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): another shared frontend subsystem with central configuration and runtime binding\n- [Localization and Locale Behavior](../../cross-cutting-systems/localization-and-locale-behavior/): shared UI-system rules that often change alongside settings and preferences surfaces\n", "1.0": "+++\ntitle = \"Theming System and Theme Selection\"\n+++\n\nSambee's theming system is centralized. Theme configuration, runtime state, persistence, and selection UI are all treated as one frontend subsystem.\n\nUse this page when you are changing palette behavior, adding a built-in theme, wiring a theme-aware component, or debugging why a selected theme is not applied consistently.\n\n## Main Pieces\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/theme/types.ts` | TypeScript theme interfaces and theme configuration shape |\n| `frontend/src/theme/themes.ts` | built-in theme definitions plus default-theme helpers |\n| `frontend/src/theme/ThemeContext.tsx` | runtime theme state, persistence, and theme switching |\n| `frontend/src/theme/index.ts` | public theme exports for the rest of the app |\n| `frontend/src/components/ThemeSelector.tsx` | theme-selection UI and dialog |\n| `frontend/src/components/themeSelectorStrings.ts` | localized strings and built-in-theme labels for the selector |\n\nThese pieces matter together. Theme behavior is not just a palette file or just a toolbar widget.\n\n## What the System Supports\n\nThe theme model currently supports:\n\n- built-in light and dark themes\n- persistent theme preferences\n- custom theme storage and runtime selection\n- theme-aware MUI palette generation\n- one shared provider that updates the app when the theme changes\n\n## Built-In Themes\n\nThe built-in themes live in `builtInThemes` in `frontend/src/theme/themes.ts`.\n\nCurrent built-ins include:\n\n- `sambee-light`: the default light branded theme\n- `sambee-dark`: the default dark branded theme\n\nThe helper functions contributors use most are:\n\n- `getDefaultTheme()`\n- `getDefaultTheme(\"light\")`\n- `getDefaultTheme(\"dark\")`\n- `getThemeById(id)`\n\nThe theme module also includes compile-time assertions around the default-theme indices so the expected built-in defaults cannot silently disappear.\n\n## Runtime Flow\n\nAt runtime, theme selection follows this path:\n\n1. the app renders inside `SambeeThemeProvider`\n2. the current theme ID is restored from persisted state when available\n3. built-in themes are resolved from code and combined with persisted custom themes\n4. `useSambeeTheme().setThemeById()` updates the active theme\n5. the selected theme is persisted\n6. the MUI theme instance updates and the UI re-renders\n\nThat is why a theme bug can look like a local component styling issue while actually being a context, persistence, or provider problem.\n\n## Theme Context Contract\n\n`useSambeeTheme()` is the main runtime entry point.\n\nContributors typically consume values such as:\n\n- `currentTheme`\n- `muiTheme`\n- `availableThemes`\n- `setThemeById`\n- `addCustomTheme`\n\nThe hook must be used inside `SambeeThemeProvider`. If you bypass that provider boundary, theme state becomes inconsistent immediately.\n\nRepresentative usage:\n\n```tsx\nimport { useSambeeTheme } from \"../theme\";\n\nfunction ThemeExample() {\n\tconst { currentTheme, setThemeById } = useSambeeTheme();\n\n\treturn (\n\t\t\u003cbutton onClick={() =\u003e setThemeById(\"sambee-dark\")}\u003e\n\t\t\tCurrent: {currentTheme.name}\n\t\t\u003c/button\u003e\n\t);\n}\n```\n\n## Theme Configuration Model\n\nThemes are expressed as typed configuration rather than ad hoc color overrides.\n\nThe palette surface includes areas such as:\n\n- `primary`\n- `secondary`\n- `background`\n- `text`\n- `action`\n\nCommon uses in the UI include:\n\n- default primary controls and selected navigation from `primary.main`\n- high-emphasis dark-mode states from `primary.light`\n- light-mode pressed and contrast-sensitive controls from `primary.dark`\n- page and standard application surfaces from `background.default`\n- readable foreground text from `text`\n- selection fills from `action.selected`\n\nMaterial UI also derives additional palette values such as divider color when enough base information is present.\n\n### Surface Policy\n\n`background.default` is the standard application surface. Use it for pages, standard dialogs, settings, and compact controls.\n\n`background.paper` remains populated at runtime because Material UI expects the token. Sambee normalizes it to `background.default`; application components should not select it as a separate surface.\n\nThe shared settings form surface is a deliberate derived exception: it darkens the default surface by 4% in light mode and lightens it by 8% in dark mode. Inside a dark dialog, it uses a 12% black mix of the actual dialog paper surface, preserving a warm but recessed form area; its outlined fields inherit the dialog paper surface to remain visually distinct from the surrounding form layer. Application chrome is another exception: light-mode AppBar and StatusBar use the primary color, while dark-mode chrome uses the shared opaque brown `#382c0a`. Standard Material UI Dialog papers and popup menus use that same opaque dark-mode color, preventing the backdrop from showing through. Fullscreen viewers retain their dedicated viewer surfaces. Dark dialog backdrops use a high-opacity neutral composite of `background.default`, preventing nested dialogs from tinting the surface behind them. Dialogs do not add an elevation shadow because the modal backdrop provides their separation. Menu selection, hover, and keyboard focus use `action.selected`.\n\nStandard Material UI Alerts use the theme's `components.alert` semantic colors for their info, success, warning, and error backgrounds, text, and icons. Apply alert semantics through the shared theme rather than per-component overrides.\n\n### Primary Palette Roles\n\n`primary.main` is the default primary control color. It should not be the brightest available shade in a dark theme, because Material UI applies it to contained buttons, radios, selected icons, and many other default controls.\n\nUse `primary.light` for brighter dark-mode hover and high-emphasis states. Use `primary.dark` for pressed and contrast-sensitive light-mode controls. Do not swap `main` and `dark` between modes: Material UI treats `dark` as the darker interaction shade.\n\nThe built-in dark theme uses a subdued golden `main`, a brighter golden `light`, and a darker pressed `dark` shade. The exact values live in `frontend/src/theme/themes.ts`.\n\n### Foreground Color Policy\n\nStandard application UI uses two base foreground roles:\n\n- `text.primary` is high-emphasis text: headings, selected or active labels, form values, selectable menu choices, file names, and information required to complete the current task.\n- `text.secondary` is the default supporting layer: descriptions, metadata, timestamps, helper copy, captions, inactive navigation icons, and other text that should be readable without competing with the task.\n\nThe built-in dark theme intentionally makes `text.secondary` a muted version of the warm primary text. This reduces glare during extended use while preserving a clear emphasis hierarchy. Use `text.disabled` for non-interactive content and dedicated palette roles such as `statusBar.textSecondary`, alert colors, and viewer toolbar colors when the surface has its own semantic contract.\n\nFor Material UI `Typography`, apply dotted palette roles through `sx`, for example `sx={{ color: \"text.secondary\" }}`. In this application's Material UI v9 configuration, `color=\"text.secondary\"` does not emit a palette color rule, so the element falls back to inherited text.\n\nIcons should inherit the role of their associated text. Use `currentColor` for adaptable inline SVG illustrations. Brand assets, file-type registry icons, document rendering, syntax highlighting, and semantic alerts are deliberate exceptions: their colors convey identity, content type, or state and should remain separately named rather than being forced into the general text palette.\n\n## Built-In Theme Characteristics\n\nThe current built-ins intentionally align with Sambee's branding.\n\n### Sambee Light\n\n- ID: `sambee-light`\n- mode: light\n- branded golden primary palette\n- cream-toned background\n- dark secondary contrast surface\n\n### Sambee Dark\n\n- ID: `sambee-dark`\n- mode: dark\n- branded golden primary palette\n- dark background\n- light secondary contrast surface\n\nThe exact palette values live in `frontend/src/theme/themes.ts`. Keep the docs focused on architectural meaning rather than duplicating every color token when the code is already authoritative.\n\n## Theme Selector UI\n\nThe visible selection UI lives in `frontend/src/components/ThemeSelector.tsx`.\n\nThe selector:\n\n- opens a dialog listing available themes\n- shows a preview of theme colors\n- uses localized strings through `themeSelectorStrings.ts`\n- calls `setThemeById` when the user changes themes\n\nThe selector is already integrated into the file-browser toolbar, and the current preferences UI also consumes the same theme state.\n\n## Persistence Model\n\nTheme preferences are persisted in local storage.\n\nThe main keys are:\n\n- `theme-id-current`: the currently selected theme ID\n- `themes-custom`: user-created custom themes\n\nThis matters for two reasons:\n\n- the selected theme survives reloads\n- built-in theme definitions can still be refreshed from code when the app updates\n\nThe system syncs built-in themes from code so users pick up reviewed built-in theme changes without losing their custom themes.\n\n## Custom Themes\n\nThe theme context supports custom themes in addition to the built-ins.\n\nThat means contributors should treat theme IDs, storage layout, and theme resolution as stable interfaces rather than temporary implementation details.\n\nWhen adding custom-theme features or editing persistence logic:\n\n- preserve separation between built-in and custom theme sets\n- keep the active theme valid even if a custom theme is removed\n- preserve a safe fallback to the default theme\n\nRepresentative pattern:\n\n```tsx\nimport { useSambeeTheme } from \"../theme\";\n\nfunction addExampleTheme() {\n\tconst { addCustomTheme } = useSambeeTheme();\n\n\taddCustomTheme({\n\t\tid: \"my-custom-theme\",\n\t\tname: \"My Custom Theme\",\n\t\tdescription: \"A unique theme\",\n\t\tmode: \"light\",\n\t\tprimary: { main: \"#ff6b6b\" },\n\t});\n}\n```\n\n## Theme Schema and Future Builder Support\n\n`frontend/src/theme/types.ts` also exports `THEME_SCHEMA`.\n\nThat schema is runtime-accessible metadata describing:\n\n- field types such as text, color, and select\n- labels and descriptions for UI\n- required versus optional fields\n- nested field definitions\n- select options such as `light` and `dark`\n\nNew custom themes should provide `primary.main` and may provide the other primary shades, background, text, and selection colors. The runtime resolver supplies stable mode-aware defaults for omitted optional fields so existing minimally configured themes remain valid.\n\n`action.focus`, `components.appBar`, and `components.statusBar` are honored for already persisted themes but are intentionally not exposed by `THEME_SCHEMA`. New themes derive those values from the palette contract.\n\nIt exists so future theme-builder tooling can generate forms and validation from one typed source instead of re-encoding theme structure in multiple places.\n\n## Theme-Aware Component Rules\n\nWhen building UI components:\n\n- use the active MUI theme instead of hard-coded surface and text colors when the style belongs to the app theme\n- use `text.primary` and `text.secondary` to establish normal UI hierarchy; do not recreate muted text with local opacity values\n- prefer `useTheme()` or the shared theme context rather than duplicating palette lookups manually\n- derive viewer toolbar borders, muted labels, disabled controls, and subtle fills from the configured toolbar text color\n- keep file-type icon colors and other intentionally non-theme registry colors separate from the app palette when they serve a different product purpose\n\nA theme-aware component typically reads from `theme.palette` and `theme.spacing` rather than introducing standalone constants.\n\n## Browser and PWA Integration\n\nThe theme system also updates the browser `theme-color` meta tag to match the selected theme's primary color.\n\nThat affects:\n\n- browser UI tinting on supported browsers\n- Android browser chrome behavior\n- installed PWA status-bar appearance\n\nIf a theme appears correct inside the app but wrong in browser chrome, check this integration path rather than only inspecting component styles.\n\n## Common Failure Modes\n\n- a component hard-codes colors that should come from the active theme\n- a new built-in theme is added without keeping default-theme helpers valid\n- theme state is read outside `SambeeThemeProvider`\n- a persistence change breaks fallback to the default theme\n- built-in theme updates and custom theme persistence start overwriting each other\n- contributors treat selector labels as static strings instead of localized UI copy\n\n## Validation Expectations\n\nWhen the theming system changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nPay particular attention to:\n\n- theme-provider tests under `frontend/src/theme/__tests__/`\n- built-in-theme and default-theme tests\n- `types.test.ts` coverage around `THEME_SCHEMA`\n- theme-selector tests under `frontend/src/components/__tests__/`\n- manual checks that text remains readable in both built-in themes\n\n## Where to Continue\n\n- [Frontend Overview](../frontend-overview/): broader browser-app structure and the place of theme behavior in the frontend\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): another shared frontend subsystem with central configuration and runtime binding\n- [Localization and Locale Behavior](../../cross-cutting-systems/localization-and-locale-behavior/): shared UI-system rules that often change alongside settings and preferences surfaces\n", "2.0": "+++\ntitle = \"Theming System and Theme Selection\"\n+++\n\nSambee has two built-in themes (`sambee-light` and `sambee-dark`), user-owned themes, and administrator-managed site themes. Built-in IDs stay stable across upgrades, so updating their palettes doesn't change anyone's selection.\n\n## Theme Data\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/theme/types.ts` | Palette types and editor field labels |\n| `frontend/src/theme/themes.ts` | Built-in definitions with stable IDs |\n| `frontend/src/theme/themeDefinition.ts` | Editable color catalog, hex checks, and versioned import/export |\n| `frontend/src/theme/palette.ts` | Shared effective palette for the app |\n| `frontend/src/theme/viewerStyles.ts` | Viewer and Markdown document surfaces |\n| `frontend/src/theme/ThemeContext.tsx` | Registry refresh and Material UI theme |\n| `frontend/src/pages/PreferencesSettings.tsx` | Selection grid and selected-theme actions |\n| `frontend/src/components/Settings/ThemeEditorDialog.tsx` | Responsive theme editor |\n| `backend/app/api/themes.py` | Validated theme operations and site default |\n\nEach editable theme has its own server row with a globally unique ID, scope, owner (for user themes), and version. Built-in definitions remain in frontend code. A new theme ID is assigned by the server; an ID in an imported file does not claim or replace a stored theme.\n\nNew and imported themes must define every editable color role. Colors use `#RRGGBB` or `#RRGGBBAA`; the server normalizes valid hex to uppercase. The role catalog includes primary, backgrounds, text, selection, links, viewer surfaces, Markdown document surfaces, search highlights, and alerts. File-type icons and document syntax colors aren't theme roles. Derived colors such as scrollbar shades, focus rings, and `background.paper` compatibility aren't editor fields. Keyboard focus rings follow the theme's primary text color: 57% opacity in light mode and 94% in dark mode. Changing that text color changes the focus color too, including in copied themes; legacy saved focus colors are ignored. Choose primary text that remains readable against the theme's surfaces.\n\n## Selection And Defaults\n\n`SambeeThemeProvider` combines built-ins with the current user's themes and shared site themes from `GET /api/themes`. The per-user selection is saved separately through `appearance.theme_id` in `PUT /api/auth/me/settings`. The backend reports whether that value is an explicit override.\n\nA user without an override follows the site default (initially `sambee-light`). A user who explicitly chooses `sambee-light` keeps that ID even if an administrator changes the site default. The selected ID points at a theme definition, never at a frozen copy of a built-in. The provider refreshes shared themes, the default, and user settings on initial load, tab focus, visibility return, and local writes. It discards out-of-date responses when the account changes.\n\nAppearance settings display Your themes, Site themes, then Built-in themes. Clicking a tile or selecting its radio applies the theme and creates an explicit user override, even when it already matches the site default. Moving focus between radios doesn't change the applied theme or the target of Copy, Edit, Delete, and Set as default. The Default chip is distinct from the selected radio. Copy keeps writable themes in their group and copies read-only themes into Your themes without applying the copy. Editing read-only themes permits inspection and Save copy, but not Save. Only an administrator can save or delete site themes or make a built-in or site theme the default.\n\n## Editing And Persistence\n\nThe editor uses a responsive dialog with collapsible color groups. A swatch opens an alpha-aware picker and each color has an editable hex field. Invalid text stays in the field without changing the valid draft. Changes in the editor aren't applied to the app until Save succeeds; Cancel discards the draft. Import replaces only the draft after validating a versioned JSON definition, and Export writes the same format.\n\n`POST /api/themes` creates a theme. Save copy opens a destination menu with Your themes for everyone and Site themes for administrators. It always creates a new theme in the chosen group without changing the applied selection. If its name already exists in that group, the editor adds ` (copy)` or a numbered copy suffix. Save updates only the opened theme in its existing group and cannot create a copy. `PUT /api/themes/{id}` and `DELETE /api/themes/{id}?version=...` require the version read by the client; a stale version returns HTTP 409. The server checks ownership, admin permissions, names, IDs, and palette completeness before committing. Bulk writes to `appearance.custom_themes` are no longer supported. There is no migration of older custom themes or compatibility promise for older exports.\n\nDeleting a theme clears explicit selections referencing it. If it was the site default, that setting is cleared too; users without an override then fall back to Sambee light. An explicit selection of another theme is unaffected.\n\n## Component Guidance\n\nPrefer the effective colors in `resolveThemePalette` and the MUI palette to hard-coded surfaces. `background.default` is the normal application surface; `background.paper` resolves to the same value for MUI compatibility. Dark chrome and dialogs use the editable `background.chrome` role. Markdown code, tables, blockquotes, and heading borders use the built-in theme's explicit document colors.\n\nViewer toolbar foreground variants, scrollbars, and subdued states can still derive opacity-adjusted values from their source color. Keep fixed colors for assets, syntax/content rendering, and file-type icons separate from the editor palette.\n\n## Verification\n\nRun focused theme tests and the project checks after changing the palette, API, or editor:\n\n```bash\ncd frontend \u0026\u0026 npm run test -- src/theme/__tests__ src/pages/__tests__/PreferencesSettings.test.tsx\ncd frontend \u0026\u0026 npm run build \u0026\u0026 npm run lint\ncd backend \u0026\u0026 .venv/bin/python -m pytest tests/test_user_settings.py\n```\n\nCheck the Appearance grid and editor on a phone and desktop in both built-in modes. Verify selection and saved-theme refresh after focus, color picker keyboard use and placement, alpha values and export, Cancel without applying the draft, and stale-save feedback.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/frontend-architecture/file-browser-and-navigation-model", "parent_id": "section:developer-guide/frontend-architecture", "depth": 2, "kind": "page", "label": "file-browser-and-navigation-model", "title": "File Browser And Navigation Model", "path": "developer-guide/frontend-architecture/file-browser-and-navigation-model", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "branched", "source_version": "0.7", "diff_added": 71, "diff_removed": 20}}, "content_versions": {"0.7": "+++\ntitle = \"File Browser and Navigation Model\"\n+++\n\nThe file browser is the densest browser-side product surface in Sambee. It combines navigation, selection, editing entry points, viewer launch, keyboard behavior, and real-time directory refresh.\n\n## Core Component Split\n\nThe implementation is deliberately split between shared page logic and per-pane logic.\n\n| Area | Responsibility |\n|---|---|\n| `pages/FileBrowser.tsx` | owns shared browser-level concerns such as active pane routing, URL sync, WebSocket lifecycle, and global shortcut registration |\n| `pages/FileBrowser/useFileBrowserPane.ts` | owns per-pane state such as connection and path, selection, sorting, filtering, dialogs, viewer state, incremental search, and directory refresh handling |\n| `pages/FileBrowser/FileBrowserPane.tsx` | renders one pane's UI |\n| `components/FileBrowser/CopyMoveDialog.tsx` | manages copy and move confirmation flow |\n| `config/keyboardShortcuts.ts` | central shortcut definitions used across the browser |\n\nThis split matters because two visible panes still need one coherent browser workflow.\n\nThe parent-versus-hook split is intentional:\n\n- `FileBrowser.tsx` owns shared state such as the connections list, active-pane routing, responsive layout, WebSocket connection lifecycle, and browser-level shortcut registration\n- `useFileBrowserPane.ts` owns per-pane state such as file loading, sort and filter state, viewer and dialog state, focus handling, multi-select state, and pane-specific directory-change reactions\n\n## Pane Model\n\nSambee supports one-pane and two-pane browsing, but the two-pane implementation is intentional rather than conditional duplication.\n\n- the left pane is always active in routing terms\n- the right pane is still instantiated even when not visible, which keeps the hook model stable\n- the active pane decides which pane keyboard shortcuts and toolbar commands target\n- dual-pane mode is desktop-first and collapses to single-pane on compact layouts\n- dual-pane preference and active-pane preference are persisted so the browser can restore the user's working style\n- the viewer opens as a fullscreen overlay from whichever pane launched it rather than being constrained to one pane region\n\nVisual state also matters:\n\n- the active pane gets the stronger emphasis treatment\n- the inactive pane is visually de-emphasized rather than treated as a separate route or different screen\n\n## URL-Synced Navigation\n\nThe file browser preserves layout state in the URL.\n\n- the primary pane stays in the path\n- the right pane is represented by the `p2` query parameter\n- active pane state is represented by the `active` query parameter\n\nThat design means refresh and back-forward navigation preserve more than a single path string.\n\nRepresentative shape:\n\n```text\nSingle pane: /browse/my-server/documents/subfolder\nDual pane:   /browse/my-server/documents?p2=other-server/photos\u0026active=2\n```\n\nImportant behavior:\n\n- the presence of `p2` on initial load activates dual-pane mode automatically\n- back and forward navigation can add or remove the second pane without changing the route definition itself\n- single-pane mode produces a clean URL without stale dual-pane query state\n- invalid right-pane connection slugs are ignored rather than breaking the whole browser route\n- the encoding model preserves slash-separated paths while still percent-encoding the path segments safely\n\n## Keyboard and Command Model\n\nKeyboard behavior is part of the product contract, not just convenience.\n\n- pane switching, selection, copy, and move use centralized shortcut definitions\n- the quick bar supports smart navigation, command mode, and pane-local current-directory filtering\n- browser defaults that conflict with the product's navigation model are overridden intentionally\n- shortcuts are disabled when dialogs or viewer states would make them unsafe\n\nChanges here can easily affect power-user workflows, accessibility, and focus management all at once.\n\nUse [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for the central registry, command-palette rules, and quick-bar interaction details. This page focuses on how those rules shape the file-browser architecture.\n\n## Pane-Local Current-Directory Filtering\n\nCurrent-directory filtering is part of pane state, not just quick-bar UI state.\n\nThe important design choice is that the quick bar only supplies the input shell. The actual filter value and filtered list live in `useFileBrowserPane`.\n\n- each pane owns its own `currentDirectoryFilter`\n- the pane computes `sortedAndFilteredFiles` from the normal sorted list plus the active filter text\n- the filtered list is the same list used by the virtualizer, keyboard navigation, viewer launch, selection helpers, and status bar\n- the active filter is considered scoped to the pane's current `connectionId + path`\n\nThat arrangement is what makes the behavior consistent in both single-pane and dual-pane workflows.\n\n### Why the Filter Lives in the Pane Hook\n\nThe filter is not modeled as a dropdown provider result set.\n\n- smart navigation is a navigation surface that benefits from dropdown results\n- command mode is a command surface that benefits from dropdown results\n- current-directory filtering is a local transformation of the pane's main file list\n\nBecause the pane already owns the rendered list, focus state, virtualizer, and file actions, the filter belongs there as well.\n\n### User-Facing Behavior the Architecture Must Preserve\n\nThe implemented flow is:\n\n1. `Ctrl+Alt+F` opens filter mode for the active pane.\n2. The shared input shows that pane's current filter value.\n3. Typing immediately filters the pane's main file list.\n4. `ArrowDown` from the input focuses the filtered file list.\n5. Arrow keys, `Home`, `End`, `PageUp`, `PageDown`, `Enter`, and file actions operate on the filtered visible list.\n6. Pressing `Ctrl+Alt+F` again returns focus to the same pane's filter input without clearing the term.\n\nReset and persistence rules are equally important:\n\n- switching between smart navigation, command mode, and filter mode does not clear the active filter\n- changing directories clears the filter for the new path scope\n- changing the pane connection also clears the filter\n- dual-pane mode keeps filter state isolated per pane\n- browser recovery snapshots capture and restore the pane filter together with path, focused item, and selection state\n\n### Focus and Zero-Result Behavior\n\nFiltering changes focus semantics because it can remove rows from the visible list.\n\n- if the previously focused file still exists in the filtered list, focus stays on that file\n- if it disappears, focus clamps to the nearest valid visible item\n- if the filter produces zero visible files, focus remains in the filter input when possible\n\nThat is why the pane hook owns both the filtered list and the focus-adjustment logic.\n\n### Status Bar Visibility\n\nThe filter must remain visible even when the quick bar is no longer in filter mode.\n\n- the desktop status bar renders the active filter term whenever the pane has a non-empty filter\n- the status bar uses the filtered visible list for item counts and file metadata\n- this keeps the active filter visible while the user switches to smart navigation or command mode\n\nThe status bar indicator is part of the product contract, not just decorative UI. It is the persistent signal that the pane is still filtered.\n\n## Selection, Copy, and Move\n\nThe browser maintains explicit multi-select state per pane, but still supports a focused-item fallback when nothing is explicitly selected.\n\nIn practice, the pane computes an effective selection from either:\n\n- the explicit selected-file set\n- or the focused file when nothing has been explicitly selected\n\nSelection is pane-local and clears naturally when directory navigation changes the active file list.\n\nCopy and move behavior depends on:\n\n- the active pane as the source\n- the other pane as the destination in dual-pane workflows\n- backend or companion routing depending on which connection types are involved\n- conflict and validation behavior that still comes from the destination backend contract\n\nThe copy and move dialog is not just a confirmation prompt. It also:\n\n- shows the selected source files\n- pre-fills the destination from the other pane\n- lets the user adjust the destination before confirming\n- reports progress while multiple operations execute\n\nImportant contract details:\n\n- `F5` means copy in dual-pane mode, but remains refresh in single-pane mode\n- `F6` means move in dual-pane mode\n- cross-connection operations are not treated the same as same-share SMB operations\n- backend validation still decides whether same-path, self-copy, or conflicting operations are allowed\n\nFor same-connection SMB copy and move, the backend uses server-side operations rather than streaming all file bytes through the browser app.\n\n## Refresh and Live State\n\nDirectory freshness is coordinated through WebSocket subscriptions.\n\n- the browser subscribes to each visible pane's directory\n- directory-change messages are routed back to the matching pane\n- local-drive and SMB-backed directories can use different backends while still feeding one browser experience\n\nIn dual-pane mode, both panes are live participants in refresh behavior:\n\n- each pane can subscribe to a different directory\n- each pane re-subscribes when its own path changes\n- directory-change events are dispatched back to the pane that owns the matching path and connection context\n\nThis is why navigation and data freshness are coupled more tightly than they first appear.\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome file-browser behaviors are deliberate tradeoffs rather than incidental implementation detail.\n\n- the UI caps visible panes at two even though the query-key pattern could theoretically scale further\n- browser-default shortcuts such as tab switching are overridden when they conflict with the product's pane model\n- dual-pane mode is disabled on compact layouts instead of forcing a cramped mobile approximation\n- one pane can stay hidden while still existing in state so the hook model remains stable\n\n## Why This Page Matters\n\nFrontend changes in the file browser often look local, but they can break:\n\n- URL-restoration behavior\n- keyboard and focus contracts\n- copy and move flows\n- viewer launch behavior\n- local-drive versus SMB routing assumptions\n- refresh behavior across both panes\n\n## Where to Continue\n\n- Use [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for centralized shortcut definitions, command-palette behavior, and focus rules.\n- Use [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/) for preview and file-type behavior.\n- Use [Browser-to-Companion Trust Model](../../companion-architecture/browser-to-companion-trust-model/) when navigation or actions depend on paired local-drive access.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when changes cross backend, frontend, and companion boundaries.\n", "0.8": "+++\ntitle = \"File Browser and Navigation Model\"\n+++\n\nThe file browser is the densest browser-side product surface in Sambee. It combines navigation, selection, editing entry points, viewer launch, keyboard behavior, and real-time directory refresh.\n\n## Core Component Split\n\nThe implementation is deliberately split between shared page logic and per-pane logic.\n\n| Area | Responsibility |\n|---|---|\n| `pages/FileBrowser.tsx` | owns shared browser-level concerns such as active pane routing, URL sync, WebSocket lifecycle, and global shortcut registration |\n| `pages/FileBrowser/useFileBrowserPane.ts` | owns per-pane state such as connection and path, selection, sorting, filtering, dialogs, viewer state, incremental search, and directory refresh handling |\n| `pages/FileBrowser/FileBrowserPane.tsx` | renders one pane's UI |\n| `components/FileBrowser/CopyMoveDialog.tsx` | manages copy and move confirmation flow |\n| `config/keyboardShortcuts.ts` | central shortcut definitions used across the browser |\n\nThis split matters because two visible panes still need one coherent browser workflow.\n\nThe parent-versus-hook split is intentional:\n\n- `FileBrowser.tsx` owns shared state such as the connections list, active-pane routing, responsive layout, WebSocket connection lifecycle, and browser-level shortcut registration\n- `useFileBrowserPane.ts` owns per-pane state such as file loading, sort and filter state, viewer and dialog state, focus handling, multi-select state, and pane-specific directory-change reactions\n\n## Pane Model\n\nSambee supports one-pane and two-pane browsing, but the two-pane implementation is intentional rather than conditional duplication.\n\n- the left pane is always active in routing terms\n- the right pane is still instantiated even when not visible, which keeps the hook model stable\n- the active pane decides which pane keyboard shortcuts and toolbar commands target\n- dual-pane mode is desktop-first and collapses to single-pane on compact layouts\n- dual-pane preference and active-pane preference are persisted so the browser can restore the user's working style\n- the viewer opens as a fullscreen overlay from whichever pane launched it rather than being constrained to one pane region\n\nVisual state also matters:\n\n- the active pane gets the stronger emphasis treatment\n- the inactive pane is visually de-emphasized rather than treated as a separate route or different screen\n\n## URL-Synced Navigation\n\nThe file browser preserves layout state in the URL.\n\n- the primary pane stays in the path\n- the right pane is represented by the `p2` query parameter\n- active pane state is represented by the `active` query parameter\n\nThat design means refresh and back-forward navigation preserve more than a single path string.\n\nRepresentative shape:\n\n```text\nSingle pane: /browse/my-server/documents/subfolder\nDual pane:   /browse/my-server/documents?p2=other-server/photos\u0026active=2\n```\n\nImportant behavior:\n\n- the presence of `p2` on initial load activates dual-pane mode automatically\n- back and forward navigation can add or remove the second pane without changing the route definition itself\n- single-pane mode produces a clean URL without stale dual-pane query state\n- invalid right-pane connection slugs are ignored rather than breaking the whole browser route\n- the encoding model preserves slash-separated paths while still percent-encoding the path segments safely\n\n## Keyboard and Command Model\n\nKeyboard behavior is part of the product contract, not just convenience.\n\n- pane switching, selection, copy, and move use centralized shortcut definitions\n- the quick bar supports smart navigation, command mode, and pane-local current-directory filtering\n- browser defaults that conflict with the product's navigation model are overridden intentionally\n- shortcuts are disabled when dialogs or viewer states would make them unsafe\n\nChanges here can easily affect power-user workflows, accessibility, and focus management all at once.\n\nUse [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for the central registry, command-palette rules, and quick-bar interaction details. This page focuses on how those rules shape the file-browser architecture.\n\n## Pane-Local Current-Directory Filtering\n\nCurrent-directory filtering is part of pane state, not just quick-bar UI state.\n\nThe important design choice is that the quick bar only supplies the input shell. The actual filter value and filtered list live in `useFileBrowserPane`.\n\n- each pane owns its own `currentDirectoryFilter`\n- the pane computes `sortedAndFilteredFiles` from the normal sorted list plus the active filter text\n- the filtered list is the same list used by the virtualizer, keyboard navigation, viewer launch, selection helpers, and status bar\n- the active filter is considered scoped to the pane's current `connectionId + path`\n\nThat arrangement is what makes the behavior consistent in both single-pane and dual-pane workflows.\n\n### Why the Filter Lives in the Pane Hook\n\nThe filter is not modeled as a dropdown provider result set.\n\n- smart navigation is a navigation surface that benefits from dropdown results\n- command mode is a command surface that benefits from dropdown results\n- current-directory filtering is a local transformation of the pane's main file list\n\nBecause the pane already owns the rendered list, focus state, virtualizer, and file actions, the filter belongs there as well.\n\n### User-Facing Behavior the Architecture Must Preserve\n\nThe implemented flow is:\n\n1. `Ctrl+Alt+F` opens filter mode for the active pane.\n2. The shared input shows that pane's current filter value.\n3. Typing immediately filters the pane's main file list.\n4. `ArrowDown` from the input focuses the filtered file list.\n5. Arrow keys, `Home`, `End`, `PageUp`, `PageDown`, `Enter`, and file actions operate on the filtered visible list.\n6. Pressing `Ctrl+Alt+F` again returns focus to the same pane's filter input without clearing the term.\n\nReset and persistence rules are equally important:\n\n- switching between smart navigation, command mode, and filter mode does not clear the active filter\n- changing directories clears the filter for the new path scope\n- changing the pane connection also clears the filter\n- dual-pane mode keeps filter state isolated per pane\n- browser recovery snapshots capture and restore the pane filter together with path, focused item, and selection state\n\n### Focus and Zero-Result Behavior\n\nFiltering changes focus semantics because it can remove rows from the visible list.\n\n- if the previously focused file still exists in the filtered list, focus stays on that file\n- if it disappears, focus clamps to the nearest valid visible item\n- if the filter produces zero visible files, focus remains in the filter input when possible\n\nThat is why the pane hook owns both the filtered list and the focus-adjustment logic.\n\n### Status Bar Visibility\n\nThe filter must remain visible even when the quick bar is no longer in filter mode.\n\n- the desktop status bar renders the active filter term whenever the pane has a non-empty filter\n- the status bar uses the filtered visible list for item counts and file metadata\n- this keeps the active filter visible while the user switches to smart navigation or command mode\n\nThe status bar indicator is part of the product contract, not just decorative UI. It is the persistent signal that the pane is still filtered.\n\n## Selection, Copy, and Move\n\nThe browser maintains explicit multi-select state per pane, but still supports a focused-item fallback when nothing is explicitly selected.\n\nIn practice, the pane computes an effective selection from either:\n\n- the explicit selected-file set\n- or the focused file when nothing has been explicitly selected\n\nSelection is pane-local and clears naturally when directory navigation changes the active file list.\n\nCopy and move behavior depends on:\n\n- the active pane as the source\n- the other pane as the destination in dual-pane workflows\n- backend or companion routing depending on which connection types are involved\n- conflict and validation behavior that still comes from the destination backend contract\n\nThe copy and move dialog is not just a confirmation prompt. It also:\n\n- shows the selected source files\n- pre-fills the destination from the other pane\n- lets the user adjust the destination before confirming\n- reports progress while multiple operations execute\n\nImportant contract details:\n\n- `F5` means copy in dual-pane mode, but remains refresh in single-pane mode\n- `F6` means move in dual-pane mode\n- cross-connection operations are not treated the same as same-share SMB operations\n- backend validation still decides whether same-path, self-copy, or conflicting operations are allowed\n\nFor same-connection SMB copy and move, the backend uses server-side operations rather than streaming all file bytes through the browser app.\n\n## Refresh and Live State\n\nDirectory freshness is coordinated through WebSocket subscriptions.\n\n- the browser subscribes to each visible pane's directory\n- directory-change messages are routed back to the matching pane\n- local-drive and SMB-backed directories can use different backends while still feeding one browser experience\n\nIn dual-pane mode, both panes are live participants in refresh behavior:\n\n- each pane can subscribe to a different directory\n- each pane re-subscribes when its own path changes\n- directory-change events are dispatched back to the pane that owns the matching path and connection context\n\nThis is why navigation and data freshness are coupled more tightly than they first appear.\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome file-browser behaviors are deliberate tradeoffs rather than incidental implementation detail.\n\n- the UI caps visible panes at two even though the query-key pattern could theoretically scale further\n- browser-default shortcuts such as tab switching are overridden when they conflict with the product's pane model\n- dual-pane mode is disabled on compact layouts instead of forcing a cramped mobile approximation\n- one pane can stay hidden while still existing in state so the hook model remains stable\n\n## Why This Page Matters\n\nFrontend changes in the file browser often look local, but they can break:\n\n- URL-restoration behavior\n- keyboard and focus contracts\n- copy and move flows\n- viewer launch behavior\n- local-drive versus SMB routing assumptions\n- refresh behavior across both panes\n\n## Where to Continue\n\n- Use [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for centralized shortcut definitions, command-palette behavior, and focus rules.\n- Use [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/) for preview and file-type behavior.\n- Use [Browser-to-Companion Trust Model](../../companion-architecture/browser-to-companion-trust-model/) when navigation or actions depend on paired local-drive access.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when changes cross backend, frontend, and companion boundaries.\n", "0.9": "+++\ntitle = \"File Browser and Navigation Model\"\n+++\n\nThe file browser is the densest browser-side product surface in Sambee. It combines navigation, selection, editing entry points, viewer launch, keyboard behavior, and real-time directory refresh.\n\n## Core Component Split\n\nThe implementation is deliberately split between shared page logic and per-pane logic.\n\n| Area | Responsibility |\n|---|---|\n| `pages/FileBrowser.tsx` | owns shared browser-level concerns such as active pane routing, URL sync, WebSocket lifecycle, and global shortcut registration |\n| `pages/FileBrowser/useFileBrowserPane.ts` | owns per-pane state such as connection and path, selection, sorting, filtering, dialogs, viewer state, incremental search, and directory refresh handling |\n| `pages/FileBrowser/FileBrowserPane.tsx` | renders one pane's UI |\n| `components/FileBrowser/CopyMoveDialog.tsx` | manages copy and move confirmation flow |\n| `config/keyboardShortcuts.ts` | central shortcut definitions used across the browser |\n\nThis split matters because two visible panes still need one coherent browser workflow.\n\nThe parent-versus-hook split is intentional:\n\n- `FileBrowser.tsx` owns shared state such as the connections list, active-pane routing, responsive layout, WebSocket connection lifecycle, and browser-level shortcut registration\n- `useFileBrowserPane.ts` owns per-pane state such as file loading, sort and filter state, viewer and dialog state, focus handling, multi-select state, and pane-specific directory-change reactions\n\n## Pane Model\n\nSambee supports one-pane and two-pane browsing, but the two-pane implementation is intentional rather than conditional duplication.\n\n- the left pane is always active in routing terms\n- the right pane is still instantiated even when not visible, which keeps the hook model stable\n- the active pane decides which pane keyboard shortcuts and toolbar commands target\n- dual-pane mode is desktop-first and collapses to single-pane on compact layouts\n- dual-pane preference and active-pane preference are persisted so the browser can restore the user's working style\n- the viewer opens as a fullscreen overlay from whichever pane launched it rather than being constrained to one pane region\n\nVisual state also matters:\n\n- the active pane gets the stronger emphasis treatment\n- the inactive pane is visually de-emphasized rather than treated as a separate route or different screen\n\n## URL-Synced Navigation\n\nThe file browser preserves layout state in the URL.\n\n- the primary pane stays in the path\n- the right pane is represented by the `p2` query parameter\n- active pane state is represented by the `active` query parameter\n\nThat design means refresh and back-forward navigation preserve more than a single path string.\n\nRepresentative shape:\n\n```text\nSingle pane: /browse/my-server/documents/subfolder\nDual pane:   /browse/my-server/documents?p2=other-server/photos\u0026active=2\n```\n\nImportant behavior:\n\n- the presence of `p2` on initial load activates dual-pane mode automatically\n- back and forward navigation can add or remove the second pane without changing the route definition itself\n- single-pane mode produces a clean URL without stale dual-pane query state\n- invalid right-pane connection slugs are ignored rather than breaking the whole browser route\n- the encoding model preserves slash-separated paths while still percent-encoding the path segments safely\n\n## Keyboard and Command Model\n\nKeyboard behavior is part of the product contract, not just convenience.\n\n- pane switching, selection, copy, and move use centralized shortcut definitions\n- the quick bar supports smart navigation, command mode, and pane-local current-directory filtering\n- browser defaults that conflict with the product's navigation model are overridden intentionally\n- shortcuts are disabled when dialogs or viewer states would make them unsafe\n\nChanges here can easily affect power-user workflows, accessibility, and focus management all at once.\n\nUse [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for the central registry, command-palette rules, and quick-bar interaction details. This page focuses on how those rules shape the file-browser architecture.\n\n## Pane-Local Current-Directory Filtering\n\nCurrent-directory filtering is part of pane state, not just quick-bar UI state.\n\nThe important design choice is that the quick bar only supplies the input shell. The actual filter value and filtered list live in `useFileBrowserPane`.\n\n- each pane owns its own `currentDirectoryFilter`\n- the pane computes `sortedAndFilteredFiles` from the normal sorted list plus the active filter text\n- the filtered list is the same list used by the virtualizer, keyboard navigation, viewer launch, selection helpers, and status bar\n- the active filter is considered scoped to the pane's current `connectionId + path`\n\nThat arrangement is what makes the behavior consistent in both single-pane and dual-pane workflows.\n\n### Why the Filter Lives in the Pane Hook\n\nThe filter is not modeled as a dropdown provider result set.\n\n- smart navigation is a navigation surface that benefits from dropdown results\n- command mode is a command surface that benefits from dropdown results\n- current-directory filtering is a local transformation of the pane's main file list\n\nBecause the pane already owns the rendered list, focus state, virtualizer, and file actions, the filter belongs there as well.\n\n### User-Facing Behavior the Architecture Must Preserve\n\nThe implemented flow is:\n\n1. `Ctrl+Alt+F` opens filter mode for the active pane.\n2. The shared input shows that pane's current filter value.\n3. Typing immediately filters the pane's main file list.\n4. `ArrowDown` from the input focuses the filtered file list.\n5. Arrow keys, `Home`, `End`, `PageUp`, `PageDown`, `Enter`, and file actions operate on the filtered visible list.\n6. Pressing `Ctrl+Alt+F` again returns focus to the same pane's filter input without clearing the term.\n\nReset and persistence rules are equally important:\n\n- switching between smart navigation, command mode, and filter mode does not clear the active filter\n- changing directories clears the filter for the new path scope\n- changing the pane connection also clears the filter\n- dual-pane mode keeps filter state isolated per pane\n- browser recovery snapshots capture and restore the pane filter together with path, focused item, and selection state\n\n### Focus and Zero-Result Behavior\n\nFiltering changes focus semantics because it can remove rows from the visible list.\n\n- if the previously focused file still exists in the filtered list, focus stays on that file\n- if it disappears, focus clamps to the nearest valid visible item\n- if the filter produces zero visible files, focus remains in the filter input when possible\n\nThat is why the pane hook owns both the filtered list and the focus-adjustment logic.\n\n### Status Bar Visibility\n\nThe filter must remain visible even when the quick bar is no longer in filter mode.\n\n- the desktop status bar renders the active filter term whenever the pane has a non-empty filter\n- the status bar uses the filtered visible list for item counts and file metadata\n- this keeps the active filter visible while the user switches to smart navigation or command mode\n\nThe status bar indicator is part of the product contract, not just decorative UI. It is the persistent signal that the pane is still filtered.\n\n## Selection, Copy, and Move\n\nThe browser maintains explicit multi-select state per pane, but still supports a focused-item fallback when nothing is explicitly selected.\n\nIn practice, the pane computes an effective selection from either:\n\n- the explicit selected-file set\n- or the focused file when nothing has been explicitly selected\n\nSelection is pane-local and clears naturally when directory navigation changes the active file list.\n\nCopy and move behavior depends on:\n\n- the active pane as the source\n- the other pane as the destination in dual-pane workflows\n- backend or companion routing depending on which connection types are involved\n- conflict and validation behavior that still comes from the destination backend contract\n\nThe copy and move dialog is not just a confirmation prompt. It also:\n\n- shows the selected source files\n- pre-fills the destination from the other pane\n- lets the user adjust the destination before confirming\n- reports progress while multiple operations execute\n\nImportant contract details:\n\n- `F5` means copy in dual-pane mode, but remains refresh in single-pane mode\n- `F6` means move in dual-pane mode\n- cross-connection operations are not treated the same as same-share SMB operations\n- backend validation still decides whether same-path, self-copy, or conflicting operations are allowed\n\nFor same-connection SMB copy and move, the backend uses server-side operations rather than streaming all file bytes through the browser app.\n\n## Refresh and Live State\n\nDirectory freshness is coordinated through WebSocket subscriptions.\n\n- the browser subscribes to each visible pane's directory\n- directory-change messages are routed back to the matching pane\n- local-drive and SMB-backed directories can use different backends while still feeding one browser experience\n\nIn dual-pane mode, both panes are live participants in refresh behavior:\n\n- each pane can subscribe to a different directory\n- each pane re-subscribes when its own path changes\n- directory-change events are dispatched back to the pane that owns the matching path and connection context\n\nThis is why navigation and data freshness are coupled more tightly than they first appear.\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome file-browser behaviors are deliberate tradeoffs rather than incidental implementation detail.\n\n- the UI caps visible panes at two even though the query-key pattern could theoretically scale further\n- browser-default shortcuts such as tab switching are overridden when they conflict with the product's pane model\n- dual-pane mode is disabled on compact layouts instead of forcing a cramped mobile approximation\n- one pane can stay hidden while still existing in state so the hook model remains stable\n\n## Why This Page Matters\n\nFrontend changes in the file browser often look local, but they can break:\n\n- URL-restoration behavior\n- keyboard and focus contracts\n- copy and move flows\n- viewer launch behavior\n- local-drive versus SMB routing assumptions\n- refresh behavior across both panes\n\n## Where to Continue\n\n- Use [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for centralized shortcut definitions, command-palette behavior, and focus rules.\n- Use [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/) for preview and file-type behavior.\n- Use [Browser-to-Companion Trust Model](../../companion-architecture/browser-to-companion-trust-model/) when navigation or actions depend on paired local-drive access.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when changes cross backend, frontend, and companion boundaries.\n", "1.0": "+++\ntitle = \"File Browser and Navigation Model\"\n+++\n\nThe file browser is the densest browser-side product surface in Sambee. It combines navigation, selection, editing entry points, viewer launch, keyboard behavior, and real-time directory refresh.\n\n## Core Component Split\n\nThe implementation is deliberately split between shared page logic and per-pane logic.\n\n| Area | Responsibility |\n|---|---|\n| `pages/FileBrowser.tsx` | owns shared browser-level concerns such as active pane routing, URL sync, WebSocket lifecycle, and global shortcut registration |\n| `pages/FileBrowser/useFileBrowserPane.ts` | owns per-pane state such as connection and path, selection, sorting, filtering, dialogs, viewer state, incremental search, and directory refresh handling |\n| `pages/FileBrowser/FileBrowserPane.tsx` | renders one pane's UI |\n| `components/FileBrowser/CopyMoveDialog.tsx` | manages copy and move confirmation flow |\n| `config/keyboardShortcuts.ts` | central shortcut definitions used across the browser |\n\nThis split matters because two visible panes still need one coherent browser workflow.\n\nThe parent-versus-hook split is intentional:\n\n- `FileBrowser.tsx` owns shared state such as the connections list, active-pane routing, responsive layout, WebSocket connection lifecycle, and browser-level shortcut registration\n- `useFileBrowserPane.ts` owns per-pane state such as file loading, sort and filter state, viewer and dialog state, focus handling, multi-select state, and pane-specific directory-change reactions\n\n## Pane Model\n\nSambee supports one-pane and two-pane browsing, but the two-pane implementation is intentional rather than conditional duplication.\n\n- the left pane is always active in routing terms\n- the right pane is still instantiated even when not visible, which keeps the hook model stable\n- the active pane decides which pane keyboard shortcuts and toolbar commands target\n- dual-pane mode is desktop-first and collapses to single-pane on compact layouts\n- dual-pane preference and active-pane preference are persisted so the browser can restore the user's working style\n- the viewer opens as a fullscreen overlay from whichever pane launched it rather than being constrained to one pane region\n\nVisual state also matters:\n\n- the active pane gets the stronger emphasis treatment\n- the inactive pane is visually de-emphasized rather than treated as a separate route or different screen\n\n## URL-Synced Navigation\n\nThe file browser preserves layout state in the URL.\n\n- the primary pane stays in the path\n- the right pane is represented by the `p2` query parameter\n- active pane state is represented by the `active` query parameter\n\nThat design means refresh and back-forward navigation preserve more than a single path string.\n\nRepresentative shape:\n\n```text\nSingle pane: /browse/my-server/documents/subfolder\nDual pane:   /browse/my-server/documents?p2=other-server/photos\u0026active=2\n```\n\nImportant behavior:\n\n- the presence of `p2` on initial load activates dual-pane mode automatically\n- back and forward navigation can add or remove the second pane without changing the route definition itself\n- single-pane mode produces a clean URL without stale dual-pane query state\n- invalid right-pane connection slugs are ignored rather than breaking the whole browser route\n- the encoding model preserves slash-separated paths while still percent-encoding the path segments safely\n\n## Keyboard and Command Model\n\nKeyboard behavior is part of the product contract, not just convenience.\n\n- pane switching, selection, copy, and move use centralized shortcut definitions\n- the quick bar supports smart navigation, command mode, and pane-local current-directory filtering\n- browser defaults that conflict with the product's navigation model are overridden intentionally\n- shortcuts are disabled when dialogs or viewer states would make them unsafe\n\nChanges here can easily affect power-user workflows, accessibility, and focus management all at once.\n\nUse [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for the central registry, command-palette rules, and quick-bar interaction details. This page focuses on how those rules shape the file-browser architecture.\n\n## Pane-Local Current-Directory Filtering\n\nCurrent-directory filtering is part of pane state, not just quick-bar UI state.\n\nThe important design choice is that the quick bar only supplies the input shell. The actual filter value and filtered list live in `useFileBrowserPane`.\n\n- each pane owns its own `currentDirectoryFilter`\n- the pane computes `sortedAndFilteredFiles` from the normal sorted list plus the active filter text\n- the filtered list is the same list used by the virtualizer, keyboard navigation, viewer launch, selection helpers, and status bar\n- the active filter is considered scoped to the pane's current `connectionId + path`\n\nThat arrangement is what makes the behavior consistent in both single-pane and dual-pane workflows.\n\n### Why the Filter Lives in the Pane Hook\n\nThe filter is not modeled as a dropdown provider result set.\n\n- smart navigation is a navigation surface that benefits from dropdown results\n- command mode is a command surface that benefits from dropdown results\n- current-directory filtering is a local transformation of the pane's main file list\n\nBecause the pane already owns the rendered list, focus state, virtualizer, and file actions, the filter belongs there as well.\n\n### User-Facing Behavior the Architecture Must Preserve\n\nThe implemented flow is:\n\n1. `Ctrl+Alt+F` opens filter mode for the active pane.\n2. The shared input shows that pane's current filter value.\n3. Typing immediately filters the pane's main file list.\n4. `ArrowDown` from the input focuses the filtered file list.\n5. Arrow keys, `Home`, `End`, `PageUp`, `PageDown`, `Enter`, and file actions operate on the filtered visible list.\n6. Pressing `Ctrl+Alt+F` again returns focus to the same pane's filter input without clearing the term.\n\nReset and persistence rules are equally important:\n\n- switching between smart navigation, command mode, and filter mode does not clear the active filter\n- changing directories clears the filter for the new path scope\n- changing the pane connection also clears the filter\n- dual-pane mode keeps filter state isolated per pane\n- browser recovery snapshots capture and restore the pane filter together with path, focused item, and selection state\n\n### Focus and Zero-Result Behavior\n\nFiltering changes focus semantics because it can remove rows from the visible list.\n\n- if the previously focused file still exists in the filtered list, focus stays on that file\n- if it disappears, focus clamps to the nearest valid visible item\n- if the filter produces zero visible files, focus remains in the filter input when possible\n\nThat is why the pane hook owns both the filtered list and the focus-adjustment logic.\n\n### Status Bar Visibility\n\nThe filter must remain visible even when the quick bar is no longer in filter mode.\n\n- the desktop status bar renders the active filter term whenever the pane has a non-empty filter\n- the status bar uses the filtered visible list for item counts and file metadata\n- this keeps the active filter visible while the user switches to smart navigation or command mode\n\nThe status bar indicator is part of the product contract, not just decorative UI. It is the persistent signal that the pane is still filtered.\n\n## Selection, Copy, and Move\n\nThe browser maintains explicit multi-select state per pane, but still supports a focused-item fallback when nothing is explicitly selected.\n\nIn practice, the pane computes an effective selection from either:\n\n- the explicit selected-file set\n- or the focused file when nothing has been explicitly selected\n\nSelection is pane-local and clears naturally when directory navigation changes the active file list.\n\nCopy and move behavior depends on:\n\n- the active pane as the source\n- the other pane as the destination in dual-pane workflows\n- backend or companion routing depending on which connection types are involved\n- conflict and validation behavior that still comes from the destination backend contract\n\nThe copy and move dialog is not just a confirmation prompt. It also:\n\n- shows the selected source files\n- pre-fills the destination from the other pane\n- lets the user adjust the destination before confirming\n- reports progress while multiple operations execute\n\nImportant contract details:\n\n- `F5` means copy in dual-pane mode, but remains refresh in single-pane mode\n- `F6` means move in dual-pane mode\n- cross-connection operations are not treated the same as same-share SMB operations\n- backend validation still decides whether same-path, self-copy, or conflicting operations are allowed\n\nFor same-connection SMB copy and move, the backend uses server-side operations rather than streaming all file bytes through the browser app.\n\n## Refresh and Live State\n\nDirectory freshness is coordinated through WebSocket subscriptions.\n\n- the browser subscribes to each visible pane's directory\n- directory-change messages are routed back to the matching pane\n- local-drive and SMB-backed directories can use different backends while still feeding one browser experience\n\nIn dual-pane mode, both panes are live participants in refresh behavior:\n\n- each pane can subscribe to a different directory\n- each pane re-subscribes when its own path changes\n- directory-change events are dispatched back to the pane that owns the matching path and connection context\n\nThis is why navigation and data freshness are coupled more tightly than they first appear.\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome file-browser behaviors are deliberate tradeoffs rather than incidental implementation detail.\n\n- the UI caps visible panes at two even though the query-key pattern could theoretically scale further\n- browser-default shortcuts such as tab switching are overridden when they conflict with the product's pane model\n- dual-pane mode is disabled on compact layouts instead of forcing a cramped mobile approximation\n- one pane can stay hidden while still existing in state so the hook model remains stable\n\n## Why This Page Matters\n\nFrontend changes in the file browser often look local, but they can break:\n\n- URL-restoration behavior\n- keyboard and focus contracts\n- copy and move flows\n- viewer launch behavior\n- local-drive versus SMB routing assumptions\n- refresh behavior across both panes\n\n## Where to Continue\n\n- Use [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for centralized shortcut definitions, command-palette behavior, and focus rules.\n- Use [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/) for preview and file-type behavior.\n- Use [Browser-to-Companion Trust Model](../../companion-architecture/browser-to-companion-trust-model/) when navigation or actions depend on paired local-drive access.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when changes cross backend, frontend, and companion boundaries.\n", "2.0": "+++\ntitle = \"File Browser and Navigation Model\"\n+++\n\nThe file browser is the densest browser-side product surface in Sambee. It combines navigation, selection, editing entry points, viewer launch, keyboard behavior, and real-time directory refresh.\n\n## Core Component Split\n\nThe implementation is deliberately split between shared page logic and per-pane logic.\n\n| Area | Responsibility |\n|---|---|\n| `pages/FileBrowser.tsx` | owns shared browser-level concerns such as active pane routing, URL sync, WebSocket lifecycle, and global shortcut registration |\n| `pages/FileBrowser/useFileBrowserPane.ts` | owns per-pane state such as connection and path, selection, sorting, filtering, dialogs, viewer state, incremental search, and directory refresh handling |\n| `pages/FileBrowser/routing.ts` | parses and serializes typed directory, viewer, editor, and settings locations |\n| `pages/FileBrowser/useWorkspaceNavigation.ts` | resolves viewer targets and owns workspace navigation and safe overlay return entries |\n| `hooks/useRoutedViewerEditing.tsx` | connects the active editor's existing confirmation dialog to React Router navigation blocking |\n| `pages/FileBrowser/FileBrowserPane.tsx` | renders one pane's UI |\n| `components/FileBrowser/CopyMoveDialog.tsx` | manages copy and move confirmation flow |\n| `config/keyboardShortcuts.ts` | central shortcut definitions used across the browser |\n\nThis split matters because two visible panes still need one coherent browser workflow.\n\nThe parent-versus-hook split is intentional:\n\n- `FileBrowser.tsx` owns shared state such as the connections list, active-pane routing, responsive layout, WebSocket connection lifecycle, and browser-level shortcut registration\n- `useFileBrowserPane.ts` owns per-pane state such as file loading, sort and filter state, viewer and dialog state, focus handling, multi-select state, and pane-specific directory-change reactions\n\n## Pane Model\n\nSambee supports one-pane and two-pane browsing, but the two-pane implementation is intentional rather than conditional duplication.\n\n- the left pane is always active in routing terms\n- the right pane is still instantiated even when not visible, which keeps the hook model stable\n- the active pane decides which pane keyboard shortcuts and toolbar commands target\n- dual-pane mode is desktop-first and collapses to single-pane on compact layouts\n- dual-pane preference and active-pane preference are persisted so the browser can restore the user's working style\n- the viewer opens as a fullscreen overlay from whichever pane launched it rather than being constrained to one pane region\n\nVisual state also matters:\n\n- the active pane gets the stronger emphasis treatment\n- the inactive pane is visually de-emphasized rather than treated as a separate route or different screen\n\n## Real-Time Directory Refresh\n\nEach pane handles directory-change notifications independently. An automatic refresh keeps an already loaded physical-directory listing mounted, including an empty listing, so unchanged rows retain selection, keyboard focus, and scroll position. Initial loading and navigation without a usable snapshot still show loading feedback.\n\nNotifications don't cancel an active listing request. Instead, the pane remembers that another refresh is needed and starts one follow-up request after the active request finishes. Automatic refreshes start at most once per second. Further notifications don't move an existing deadline, so continuous writes still produce periodic updates. Navigation and unmount cancel queued work.\n\nA listing with unprocessed change notifications can remain visible, but it isn't cached as fresh. Deferred link-target metadata only updates cache entries that are still valid, so cancelling a follow-up refresh can't make an outdated snapshot reusable on return.\n\nSMB file-list subscriptions watch immediate children rather than the whole subtree. The separate backend directory-search cache retains recursive directory-name monitoring. See [SMB Change Notification and Directory Freshness](../../backend-architecture/smb-change-notification-and-directory-freshness/) for watcher ownership and lifecycle.\n\n## URL-Driven Workspace Navigation\n\nThe URL selects the directory, pane layout, viewer, editing intent, and settings view. The file browser stays mounted under overlays. Loaded content, drafts, locks, selection, scroll, search panels, and zoom remain runtime state.\n\n| Part | Meaning |\n|---|---|\n| `/browse/smb/\u003cslug\u003e/\u003cpath\u003e` | Primary SMB pane |\n| `/browse/local/\u003cdrive-id\u003e/\u003cpath\u003e` | Primary companion-drive pane |\n| `p2=\u003ckind\u003e/\u003ctarget\u003e/\u003cpath\u003e` | Right pane, enabled when present |\n| `active=2` | Right pane is active |\n| `file=\u003ckind\u003e/\u003ctarget\u003e/\u003cpath\u003e` | Viewer target, independent of the directory and active pane |\n| `viewer=image\\|markdown\\|pdf\\|text` | Requested browser viewer |\n| `mode=edit` | Editing intent for text or Markdown |\n| `pane=2` | Right pane owns the viewer; requires a right-pane target |\n| `virtual=\u003cJSON array\u003e` | Archive member descriptor: provider ID, source archive path, member path |\n| `settings=main\\|\u003ccategory\u003e` | Settings main view or category from the shared category registry |\n\nFor example:\n\n```text\n/browse/smb/my-server/documents\n/browse/smb/my-server/documents?p2=smb%2Fother-server%2Fphotos\u0026active=2\n/browse/smb/my-server/documents?file=smb%2Fmy-server%2Fdocuments%2Fnotes.md\u0026viewer=markdown\n/browse/smb/my-server/documents?file=smb%2Fmy-server%2Fdocuments%2Fnotes.md\u0026viewer=markdown\u0026mode=edit\n/browse/smb/my-server/documents?settings=account\n```\n\nUse the shared parser/serializer and `URLSearchParams`, not concatenated query strings. File descriptors encode target IDs and individual path segments before query serialization. The archive provider is currently `zip`. Runtime session IDs, file contents, MIME guesses, gallery arrays, credentials, and lock capabilities never belong in navigation state.\n\n### Navigation and Dismissal\n\nOpening or closing a viewer, entering or leaving editing, changing gallery images, opening or closing settings, and changing settings categories push history entries. Repeating the same location does nothing. Pane-focus updates, invalid-descriptor recovery, failed edit acquisition, and canonicalization replace the current entry. Unrelated query parameters and authentication fragments are preserved.\n\nBack and Forward follow actual history without adding entries. Explicit Close pushes the current workspace with the dismissed layer removed, including for direct links and refreshed viewers. For example, opening a directory, opening an image, and closing it produces directory, image, and directory entries; Back reopens the image before returning to the earlier directory entry. A new action after Back discards the old Forward branch, following normal browser behavior. Close doesn't depend on opening-entry metadata or `history.length`. Settings back controls traverse observed history; without an observed predecessor they replace the URL with an in-app parent.\n\nDesktop settings and the mobile drawer are controlled by the same category descriptor. `settings=main` displays the desktop default category or the mobile category list. Resizing changes presentation without navigation. Standalone `/settings/...` routes and their aliases use the same category content and authorization checks. User Management owns its query keys through React Router, merging them with workspace parameters.\n\n### Direct Links and Recovery\n\nViewer links resolve metadata through the storage registry or content provider, without simulated file-row clicks. Resolution is cancelled when its identity changes. Missing resources show Retry and Close actions. A viewer URL never falls back to opening a native application.\n\nThe incoming URL always wins over a browser recovery snapshot. Snapshot hydration matches each pane's resource identity, clears legacy viewer state, and ignores unmatched panes. A bare `/browse` uses normal default navigation. Captured snapshots use the current canonical workspace URL and contain neither callback fragments nor edit-session tokens.\n\n### Viewer Loading and Transitions\n\nLoading feedback belongs to the selected image, PDF, text, or Markdown viewer. Workspace metadata resolution and dynamic component imports do not show an intermediate full-screen loading dialog. On an initial opening, the browser remains visible until metadata and the viewer component are available; the viewer then displays its existing content-loading feedback.\n\nDuring file-to-file or history navigation, keep the outgoing viewer presentation mounted until the replacement metadata and component are ready. Do not expose the directory between viewers or pass the new target's props to the old viewer component. Outgoing controls and shortcuts are suspended during the handoff, while Escape can cancel the pending opening. The existing error dialogs retain Retry and Close actions. Cancellation rejects late results rather than reopening a dismissed viewer.\n\nOne dynamic viewer host serves both panes. An explicit viewer ID, not an image's changing MIME type, controls component loading. Text and Markdown still reset resource-local state when the actual file changes; mode-only and settings-only navigation do not restart the viewer.\n\n### Editing and Router Integrity\n\nThe app uses a data router (`createBrowserRouter` and `RouterProvider`) for supported `useBlocker` behavior. One guard owner delegates resource-leaving transitions to the active text or Markdown editor when its draft is dirty, a save is pending, or a session is being acquired. Clean editor Back and Forward navigate directly, avoiding the history reversal required by a blocked browser navigation. Cancel keeps the draft and lock; successful Save or Discard continues the original transition; failed Save keeps the editor open. Changes that retain the same edited resource and mode don't discard its draft. Dirty drafts also register `beforeunload` protection.\n\nEdit bookmarks and history navigation back into editing acquire a fresh edit session after content and permission checks. Navigating away during acquisition invalidates the attempt and releases any late lock. Leaving editing releases its session once. The outgoing editor is read-only during cleanup, and re-entry waits for that cleanup to finish so an old release can't clear a new session. History restores navigation intent, not old file contents, discarded drafts, or saved locks. An edit URL doesn't grant permission.\n\nFull page reloads, including F5 and the update prompt, can resume the same edit lock. The shared storage edit-session layer keeps lock credentials separately in tab-scoped session storage, keyed by user, connection, and file. On reload it validates those credentials with a heartbeat before reusing them. Only a structured lost-lock response permits fresh acquisition; network and permission failures don't trigger replacement. Credentials follow replacement locks and are removed on successful release or logout. Unsaved text still uses the existing draft-recovery flow.\n\nRecovery requires session storage and the browser Web Locks API, available in secure contexts such as HTTPS and localhost. An exclusive Web Lock prevents another tab from using copied recovery credentials, even if that tab reloads. Without those capabilities, editing still works, but a reload may need to wait for the abandoned server lock to expire. Fresh navigations and history entries don't resume saved credentials, and no credentials appear in the URL or workspace recovery snapshot.\n\nUse router navigation for all mounted-route URL writes, including authentication fragment cleanup. `useRemoveLocationFragment` replaces the entry, removes only consumed fragment keys, and preserves the full query and application state. Never clear router-managed history state with `replaceState(null, ...)`: doing so can disable POP blocking.\n\n## Keyboard and Command Model\n\nKeyboard behavior is part of the product contract, not just convenience.\n\n- pane switching, selection, copy, and move use centralized shortcut definitions\n- the quick bar supports smart navigation, command mode, and pane-local current-directory filtering\n- browser defaults that conflict with the product's navigation model are overridden intentionally\n- shortcuts are disabled when dialogs or viewer states would make them unsafe\n\nChanges here can easily affect power-user workflows, accessibility, and focus management all at once.\n\nUse [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for the central registry, command-palette rules, and quick-bar interaction details. This page focuses on how those rules shape the file-browser architecture.\n\n## Pane-Local Current-Directory Filtering\n\nCurrent-directory filtering is part of pane state, not just quick-bar UI state.\n\nThe important design choice is that the quick bar only supplies the input shell. The actual filter value and filtered list live in `useFileBrowserPane`.\n\n- each pane owns its own `currentDirectoryFilter`\n- the pane computes `sortedAndFilteredFiles` from the normal sorted list plus the active filter text\n- the filtered list is the same list used by the virtualizer, keyboard navigation, viewer launch, selection helpers, and status bar\n- the active filter is considered scoped to the pane's current `connectionId + path`\n\nThat arrangement is what makes the behavior consistent in both single-pane and dual-pane workflows.\n\n### Why the Filter Lives in the Pane Hook\n\nThe filter is not modeled as a dropdown provider result set.\n\n- smart navigation is a navigation surface that benefits from dropdown results\n- command mode is a command surface that benefits from dropdown results\n- current-directory filtering is a local transformation of the pane's main file list\n\nBecause the pane already owns the rendered list, focus state, virtualizer, and file actions, the filter belongs there as well.\n\n### User-Facing Behavior the Architecture Must Preserve\n\nThe implemented flow is:\n\n1. `Ctrl+Alt+F` opens filter mode for the active pane.\n2. The shared input shows that pane's current filter value.\n3. Typing immediately filters the pane's main file list.\n4. `ArrowDown` from the input focuses the filtered file list.\n5. Arrow keys, `Home`, `End`, `PageUp`, `PageDown`, `Enter`, and file actions operate on the filtered visible list.\n6. Pressing `Ctrl+Alt+F` again returns focus to the same pane's filter input without clearing the term.\n\nReset and persistence rules are equally important:\n\n- switching between smart navigation, command mode, and filter mode does not clear the active filter\n- changing directories clears the filter for the new path scope\n- changing the pane connection also clears the filter\n- dual-pane mode keeps filter state isolated per pane\n- browser recovery snapshots capture and restore the pane filter together with path, focused item, and selection state\n\n### Focus and Zero-Result Behavior\n\nFiltering changes focus semantics because it can remove rows from the visible list.\n\n- if the previously focused file still exists in the filtered list, focus stays on that file\n- if it disappears, focus clamps to the nearest valid visible item\n- if the filter produces zero visible files, focus remains in the filter input when possible\n\nThat is why the pane hook owns both the filtered list and the focus-adjustment logic.\n\n### Status Bar Visibility\n\nThe filter must remain visible even when the quick bar is no longer in filter mode.\n\n- the desktop status bar renders the active filter term whenever the pane has a non-empty filter\n- the status bar uses the filtered visible list for item counts and file metadata\n- this keeps the active filter visible while the user switches to smart navigation or command mode\n\nThe status bar indicator is part of the product contract, not just decorative UI. It is the persistent signal that the pane is still filtered.\n\n## Selection, Copy, and Move\n\nThe browser maintains explicit multi-select state per pane, but still supports a focused-item fallback when nothing is explicitly selected.\n\nIn practice, the pane computes an effective selection from either:\n\n- the explicit selected-file set\n- or the focused file when nothing has been explicitly selected\n\nSelection is pane-local and clears naturally when directory navigation changes the active file list.\n\nCopy and move behavior depends on:\n\n- the active pane as the source\n- the other pane as the destination in dual-pane workflows\n- backend or companion routing depending on which connection types are involved\n- conflict and validation behavior that still comes from the destination backend contract\n\nThe copy and move dialog is not just a confirmation prompt. It also:\n\n- shows the selected source files\n- pre-fills the destination from the other pane\n- lets the user adjust the destination before confirming\n- reports progress while multiple operations execute\n\nImportant contract details:\n\n- `F5` means copy in dual-pane mode, but remains refresh in single-pane mode\n- `F6` means move in dual-pane mode\n- cross-connection operations are not treated the same as same-share SMB operations\n- backend validation still decides whether same-path, self-copy, or conflicting operations are allowed\n\nFor same-connection SMB copy and move, the backend uses server-side operations rather than streaming all file bytes through the browser app.\n\n## Refresh and Live State\n\nDirectory freshness is coordinated through WebSocket subscriptions.\n\n- the browser subscribes to each visible pane's directory\n- directory-change messages are routed back to the matching pane\n- local-drive and SMB-backed directories can use different backends while still feeding one browser experience\n\nIn dual-pane mode, both panes are live participants in refresh behavior:\n\n- each pane can subscribe to a different directory\n- each pane re-subscribes when its own path changes\n- directory-change events are dispatched back to the pane that owns the matching path and connection context\n\nThis is why navigation and data freshness are coupled more tightly than they first appear.\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome file-browser behaviors are deliberate tradeoffs rather than incidental implementation detail.\n\n- the UI caps visible panes at two even though the query-key pattern could theoretically scale further\n- browser-default shortcuts such as tab switching are overridden when they conflict with the product's pane model\n- dual-pane mode is disabled on compact layouts instead of forcing a cramped mobile approximation\n- one pane can stay hidden while still existing in state so the hook model remains stable\n\n## Why This Page Matters\n\nFrontend changes in the file browser often look local, but they can break:\n\n- URL-restoration behavior\n- keyboard and focus contracts\n- copy and move flows\n- viewer launch behavior\n- local-drive versus SMB routing assumptions\n- refresh behavior across both panes\n\n## Where to Continue\n\n- Use [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for centralized shortcut definitions, command-palette behavior, and focus rules.\n- Use [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/) for preview and file-type behavior.\n- Use [Browser-to-Companion Trust Model](../../companion-architecture/browser-to-companion-trust-model/) when navigation or actions depend on paired local-drive access.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when changes cross backend, frontend, and companion boundaries.\n"}, "page_contents": {"0.7": "+++\ntitle = \"File Browser and Navigation Model\"\n+++\n\nThe file browser is the densest browser-side product surface in Sambee. It combines navigation, selection, editing entry points, viewer launch, keyboard behavior, and real-time directory refresh.\n\n## Core Component Split\n\nThe implementation is deliberately split between shared page logic and per-pane logic.\n\n| Area | Responsibility |\n|---|---|\n| `pages/FileBrowser.tsx` | owns shared browser-level concerns such as active pane routing, URL sync, WebSocket lifecycle, and global shortcut registration |\n| `pages/FileBrowser/useFileBrowserPane.ts` | owns per-pane state such as connection and path, selection, sorting, filtering, dialogs, viewer state, incremental search, and directory refresh handling |\n| `pages/FileBrowser/FileBrowserPane.tsx` | renders one pane's UI |\n| `components/FileBrowser/CopyMoveDialog.tsx` | manages copy and move confirmation flow |\n| `config/keyboardShortcuts.ts` | central shortcut definitions used across the browser |\n\nThis split matters because two visible panes still need one coherent browser workflow.\n\nThe parent-versus-hook split is intentional:\n\n- `FileBrowser.tsx` owns shared state such as the connections list, active-pane routing, responsive layout, WebSocket connection lifecycle, and browser-level shortcut registration\n- `useFileBrowserPane.ts` owns per-pane state such as file loading, sort and filter state, viewer and dialog state, focus handling, multi-select state, and pane-specific directory-change reactions\n\n## Pane Model\n\nSambee supports one-pane and two-pane browsing, but the two-pane implementation is intentional rather than conditional duplication.\n\n- the left pane is always active in routing terms\n- the right pane is still instantiated even when not visible, which keeps the hook model stable\n- the active pane decides which pane keyboard shortcuts and toolbar commands target\n- dual-pane mode is desktop-first and collapses to single-pane on compact layouts\n- dual-pane preference and active-pane preference are persisted so the browser can restore the user's working style\n- the viewer opens as a fullscreen overlay from whichever pane launched it rather than being constrained to one pane region\n\nVisual state also matters:\n\n- the active pane gets the stronger emphasis treatment\n- the inactive pane is visually de-emphasized rather than treated as a separate route or different screen\n\n## URL-Synced Navigation\n\nThe file browser preserves layout state in the URL.\n\n- the primary pane stays in the path\n- the right pane is represented by the `p2` query parameter\n- active pane state is represented by the `active` query parameter\n\nThat design means refresh and back-forward navigation preserve more than a single path string.\n\nRepresentative shape:\n\n```text\nSingle pane: /browse/my-server/documents/subfolder\nDual pane:   /browse/my-server/documents?p2=other-server/photos\u0026active=2\n```\n\nImportant behavior:\n\n- the presence of `p2` on initial load activates dual-pane mode automatically\n- back and forward navigation can add or remove the second pane without changing the route definition itself\n- single-pane mode produces a clean URL without stale dual-pane query state\n- invalid right-pane connection slugs are ignored rather than breaking the whole browser route\n- the encoding model preserves slash-separated paths while still percent-encoding the path segments safely\n\n## Keyboard and Command Model\n\nKeyboard behavior is part of the product contract, not just convenience.\n\n- pane switching, selection, copy, and move use centralized shortcut definitions\n- the quick bar supports smart navigation, command mode, and pane-local current-directory filtering\n- browser defaults that conflict with the product's navigation model are overridden intentionally\n- shortcuts are disabled when dialogs or viewer states would make them unsafe\n\nChanges here can easily affect power-user workflows, accessibility, and focus management all at once.\n\nUse [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for the central registry, command-palette rules, and quick-bar interaction details. This page focuses on how those rules shape the file-browser architecture.\n\n## Pane-Local Current-Directory Filtering\n\nCurrent-directory filtering is part of pane state, not just quick-bar UI state.\n\nThe important design choice is that the quick bar only supplies the input shell. The actual filter value and filtered list live in `useFileBrowserPane`.\n\n- each pane owns its own `currentDirectoryFilter`\n- the pane computes `sortedAndFilteredFiles` from the normal sorted list plus the active filter text\n- the filtered list is the same list used by the virtualizer, keyboard navigation, viewer launch, selection helpers, and status bar\n- the active filter is considered scoped to the pane's current `connectionId + path`\n\nThat arrangement is what makes the behavior consistent in both single-pane and dual-pane workflows.\n\n### Why the Filter Lives in the Pane Hook\n\nThe filter is not modeled as a dropdown provider result set.\n\n- smart navigation is a navigation surface that benefits from dropdown results\n- command mode is a command surface that benefits from dropdown results\n- current-directory filtering is a local transformation of the pane's main file list\n\nBecause the pane already owns the rendered list, focus state, virtualizer, and file actions, the filter belongs there as well.\n\n### User-Facing Behavior the Architecture Must Preserve\n\nThe implemented flow is:\n\n1. `Ctrl+Alt+F` opens filter mode for the active pane.\n2. The shared input shows that pane's current filter value.\n3. Typing immediately filters the pane's main file list.\n4. `ArrowDown` from the input focuses the filtered file list.\n5. Arrow keys, `Home`, `End`, `PageUp`, `PageDown`, `Enter`, and file actions operate on the filtered visible list.\n6. Pressing `Ctrl+Alt+F` again returns focus to the same pane's filter input without clearing the term.\n\nReset and persistence rules are equally important:\n\n- switching between smart navigation, command mode, and filter mode does not clear the active filter\n- changing directories clears the filter for the new path scope\n- changing the pane connection also clears the filter\n- dual-pane mode keeps filter state isolated per pane\n- browser recovery snapshots capture and restore the pane filter together with path, focused item, and selection state\n\n### Focus and Zero-Result Behavior\n\nFiltering changes focus semantics because it can remove rows from the visible list.\n\n- if the previously focused file still exists in the filtered list, focus stays on that file\n- if it disappears, focus clamps to the nearest valid visible item\n- if the filter produces zero visible files, focus remains in the filter input when possible\n\nThat is why the pane hook owns both the filtered list and the focus-adjustment logic.\n\n### Status Bar Visibility\n\nThe filter must remain visible even when the quick bar is no longer in filter mode.\n\n- the desktop status bar renders the active filter term whenever the pane has a non-empty filter\n- the status bar uses the filtered visible list for item counts and file metadata\n- this keeps the active filter visible while the user switches to smart navigation or command mode\n\nThe status bar indicator is part of the product contract, not just decorative UI. It is the persistent signal that the pane is still filtered.\n\n## Selection, Copy, and Move\n\nThe browser maintains explicit multi-select state per pane, but still supports a focused-item fallback when nothing is explicitly selected.\n\nIn practice, the pane computes an effective selection from either:\n\n- the explicit selected-file set\n- or the focused file when nothing has been explicitly selected\n\nSelection is pane-local and clears naturally when directory navigation changes the active file list.\n\nCopy and move behavior depends on:\n\n- the active pane as the source\n- the other pane as the destination in dual-pane workflows\n- backend or companion routing depending on which connection types are involved\n- conflict and validation behavior that still comes from the destination backend contract\n\nThe copy and move dialog is not just a confirmation prompt. It also:\n\n- shows the selected source files\n- pre-fills the destination from the other pane\n- lets the user adjust the destination before confirming\n- reports progress while multiple operations execute\n\nImportant contract details:\n\n- `F5` means copy in dual-pane mode, but remains refresh in single-pane mode\n- `F6` means move in dual-pane mode\n- cross-connection operations are not treated the same as same-share SMB operations\n- backend validation still decides whether same-path, self-copy, or conflicting operations are allowed\n\nFor same-connection SMB copy and move, the backend uses server-side operations rather than streaming all file bytes through the browser app.\n\n## Refresh and Live State\n\nDirectory freshness is coordinated through WebSocket subscriptions.\n\n- the browser subscribes to each visible pane's directory\n- directory-change messages are routed back to the matching pane\n- local-drive and SMB-backed directories can use different backends while still feeding one browser experience\n\nIn dual-pane mode, both panes are live participants in refresh behavior:\n\n- each pane can subscribe to a different directory\n- each pane re-subscribes when its own path changes\n- directory-change events are dispatched back to the pane that owns the matching path and connection context\n\nThis is why navigation and data freshness are coupled more tightly than they first appear.\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome file-browser behaviors are deliberate tradeoffs rather than incidental implementation detail.\n\n- the UI caps visible panes at two even though the query-key pattern could theoretically scale further\n- browser-default shortcuts such as tab switching are overridden when they conflict with the product's pane model\n- dual-pane mode is disabled on compact layouts instead of forcing a cramped mobile approximation\n- one pane can stay hidden while still existing in state so the hook model remains stable\n\n## Why This Page Matters\n\nFrontend changes in the file browser often look local, but they can break:\n\n- URL-restoration behavior\n- keyboard and focus contracts\n- copy and move flows\n- viewer launch behavior\n- local-drive versus SMB routing assumptions\n- refresh behavior across both panes\n\n## Where to Continue\n\n- Use [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for centralized shortcut definitions, command-palette behavior, and focus rules.\n- Use [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/) for preview and file-type behavior.\n- Use [Browser-to-Companion Trust Model](../../companion-architecture/browser-to-companion-trust-model/) when navigation or actions depend on paired local-drive access.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when changes cross backend, frontend, and companion boundaries.\n", "0.8": "+++\ntitle = \"File Browser and Navigation Model\"\n+++\n\nThe file browser is the densest browser-side product surface in Sambee. It combines navigation, selection, editing entry points, viewer launch, keyboard behavior, and real-time directory refresh.\n\n## Core Component Split\n\nThe implementation is deliberately split between shared page logic and per-pane logic.\n\n| Area | Responsibility |\n|---|---|\n| `pages/FileBrowser.tsx` | owns shared browser-level concerns such as active pane routing, URL sync, WebSocket lifecycle, and global shortcut registration |\n| `pages/FileBrowser/useFileBrowserPane.ts` | owns per-pane state such as connection and path, selection, sorting, filtering, dialogs, viewer state, incremental search, and directory refresh handling |\n| `pages/FileBrowser/FileBrowserPane.tsx` | renders one pane's UI |\n| `components/FileBrowser/CopyMoveDialog.tsx` | manages copy and move confirmation flow |\n| `config/keyboardShortcuts.ts` | central shortcut definitions used across the browser |\n\nThis split matters because two visible panes still need one coherent browser workflow.\n\nThe parent-versus-hook split is intentional:\n\n- `FileBrowser.tsx` owns shared state such as the connections list, active-pane routing, responsive layout, WebSocket connection lifecycle, and browser-level shortcut registration\n- `useFileBrowserPane.ts` owns per-pane state such as file loading, sort and filter state, viewer and dialog state, focus handling, multi-select state, and pane-specific directory-change reactions\n\n## Pane Model\n\nSambee supports one-pane and two-pane browsing, but the two-pane implementation is intentional rather than conditional duplication.\n\n- the left pane is always active in routing terms\n- the right pane is still instantiated even when not visible, which keeps the hook model stable\n- the active pane decides which pane keyboard shortcuts and toolbar commands target\n- dual-pane mode is desktop-first and collapses to single-pane on compact layouts\n- dual-pane preference and active-pane preference are persisted so the browser can restore the user's working style\n- the viewer opens as a fullscreen overlay from whichever pane launched it rather than being constrained to one pane region\n\nVisual state also matters:\n\n- the active pane gets the stronger emphasis treatment\n- the inactive pane is visually de-emphasized rather than treated as a separate route or different screen\n\n## URL-Synced Navigation\n\nThe file browser preserves layout state in the URL.\n\n- the primary pane stays in the path\n- the right pane is represented by the `p2` query parameter\n- active pane state is represented by the `active` query parameter\n\nThat design means refresh and back-forward navigation preserve more than a single path string.\n\nRepresentative shape:\n\n```text\nSingle pane: /browse/my-server/documents/subfolder\nDual pane:   /browse/my-server/documents?p2=other-server/photos\u0026active=2\n```\n\nImportant behavior:\n\n- the presence of `p2` on initial load activates dual-pane mode automatically\n- back and forward navigation can add or remove the second pane without changing the route definition itself\n- single-pane mode produces a clean URL without stale dual-pane query state\n- invalid right-pane connection slugs are ignored rather than breaking the whole browser route\n- the encoding model preserves slash-separated paths while still percent-encoding the path segments safely\n\n## Keyboard and Command Model\n\nKeyboard behavior is part of the product contract, not just convenience.\n\n- pane switching, selection, copy, and move use centralized shortcut definitions\n- the quick bar supports smart navigation, command mode, and pane-local current-directory filtering\n- browser defaults that conflict with the product's navigation model are overridden intentionally\n- shortcuts are disabled when dialogs or viewer states would make them unsafe\n\nChanges here can easily affect power-user workflows, accessibility, and focus management all at once.\n\nUse [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for the central registry, command-palette rules, and quick-bar interaction details. This page focuses on how those rules shape the file-browser architecture.\n\n## Pane-Local Current-Directory Filtering\n\nCurrent-directory filtering is part of pane state, not just quick-bar UI state.\n\nThe important design choice is that the quick bar only supplies the input shell. The actual filter value and filtered list live in `useFileBrowserPane`.\n\n- each pane owns its own `currentDirectoryFilter`\n- the pane computes `sortedAndFilteredFiles` from the normal sorted list plus the active filter text\n- the filtered list is the same list used by the virtualizer, keyboard navigation, viewer launch, selection helpers, and status bar\n- the active filter is considered scoped to the pane's current `connectionId + path`\n\nThat arrangement is what makes the behavior consistent in both single-pane and dual-pane workflows.\n\n### Why the Filter Lives in the Pane Hook\n\nThe filter is not modeled as a dropdown provider result set.\n\n- smart navigation is a navigation surface that benefits from dropdown results\n- command mode is a command surface that benefits from dropdown results\n- current-directory filtering is a local transformation of the pane's main file list\n\nBecause the pane already owns the rendered list, focus state, virtualizer, and file actions, the filter belongs there as well.\n\n### User-Facing Behavior the Architecture Must Preserve\n\nThe implemented flow is:\n\n1. `Ctrl+Alt+F` opens filter mode for the active pane.\n2. The shared input shows that pane's current filter value.\n3. Typing immediately filters the pane's main file list.\n4. `ArrowDown` from the input focuses the filtered file list.\n5. Arrow keys, `Home`, `End`, `PageUp`, `PageDown`, `Enter`, and file actions operate on the filtered visible list.\n6. Pressing `Ctrl+Alt+F` again returns focus to the same pane's filter input without clearing the term.\n\nReset and persistence rules are equally important:\n\n- switching between smart navigation, command mode, and filter mode does not clear the active filter\n- changing directories clears the filter for the new path scope\n- changing the pane connection also clears the filter\n- dual-pane mode keeps filter state isolated per pane\n- browser recovery snapshots capture and restore the pane filter together with path, focused item, and selection state\n\n### Focus and Zero-Result Behavior\n\nFiltering changes focus semantics because it can remove rows from the visible list.\n\n- if the previously focused file still exists in the filtered list, focus stays on that file\n- if it disappears, focus clamps to the nearest valid visible item\n- if the filter produces zero visible files, focus remains in the filter input when possible\n\nThat is why the pane hook owns both the filtered list and the focus-adjustment logic.\n\n### Status Bar Visibility\n\nThe filter must remain visible even when the quick bar is no longer in filter mode.\n\n- the desktop status bar renders the active filter term whenever the pane has a non-empty filter\n- the status bar uses the filtered visible list for item counts and file metadata\n- this keeps the active filter visible while the user switches to smart navigation or command mode\n\nThe status bar indicator is part of the product contract, not just decorative UI. It is the persistent signal that the pane is still filtered.\n\n## Selection, Copy, and Move\n\nThe browser maintains explicit multi-select state per pane, but still supports a focused-item fallback when nothing is explicitly selected.\n\nIn practice, the pane computes an effective selection from either:\n\n- the explicit selected-file set\n- or the focused file when nothing has been explicitly selected\n\nSelection is pane-local and clears naturally when directory navigation changes the active file list.\n\nCopy and move behavior depends on:\n\n- the active pane as the source\n- the other pane as the destination in dual-pane workflows\n- backend or companion routing depending on which connection types are involved\n- conflict and validation behavior that still comes from the destination backend contract\n\nThe copy and move dialog is not just a confirmation prompt. It also:\n\n- shows the selected source files\n- pre-fills the destination from the other pane\n- lets the user adjust the destination before confirming\n- reports progress while multiple operations execute\n\nImportant contract details:\n\n- `F5` means copy in dual-pane mode, but remains refresh in single-pane mode\n- `F6` means move in dual-pane mode\n- cross-connection operations are not treated the same as same-share SMB operations\n- backend validation still decides whether same-path, self-copy, or conflicting operations are allowed\n\nFor same-connection SMB copy and move, the backend uses server-side operations rather than streaming all file bytes through the browser app.\n\n## Refresh and Live State\n\nDirectory freshness is coordinated through WebSocket subscriptions.\n\n- the browser subscribes to each visible pane's directory\n- directory-change messages are routed back to the matching pane\n- local-drive and SMB-backed directories can use different backends while still feeding one browser experience\n\nIn dual-pane mode, both panes are live participants in refresh behavior:\n\n- each pane can subscribe to a different directory\n- each pane re-subscribes when its own path changes\n- directory-change events are dispatched back to the pane that owns the matching path and connection context\n\nThis is why navigation and data freshness are coupled more tightly than they first appear.\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome file-browser behaviors are deliberate tradeoffs rather than incidental implementation detail.\n\n- the UI caps visible panes at two even though the query-key pattern could theoretically scale further\n- browser-default shortcuts such as tab switching are overridden when they conflict with the product's pane model\n- dual-pane mode is disabled on compact layouts instead of forcing a cramped mobile approximation\n- one pane can stay hidden while still existing in state so the hook model remains stable\n\n## Why This Page Matters\n\nFrontend changes in the file browser often look local, but they can break:\n\n- URL-restoration behavior\n- keyboard and focus contracts\n- copy and move flows\n- viewer launch behavior\n- local-drive versus SMB routing assumptions\n- refresh behavior across both panes\n\n## Where to Continue\n\n- Use [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for centralized shortcut definitions, command-palette behavior, and focus rules.\n- Use [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/) for preview and file-type behavior.\n- Use [Browser-to-Companion Trust Model](../../companion-architecture/browser-to-companion-trust-model/) when navigation or actions depend on paired local-drive access.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when changes cross backend, frontend, and companion boundaries.\n", "0.9": "+++\ntitle = \"File Browser and Navigation Model\"\n+++\n\nThe file browser is the densest browser-side product surface in Sambee. It combines navigation, selection, editing entry points, viewer launch, keyboard behavior, and real-time directory refresh.\n\n## Core Component Split\n\nThe implementation is deliberately split between shared page logic and per-pane logic.\n\n| Area | Responsibility |\n|---|---|\n| `pages/FileBrowser.tsx` | owns shared browser-level concerns such as active pane routing, URL sync, WebSocket lifecycle, and global shortcut registration |\n| `pages/FileBrowser/useFileBrowserPane.ts` | owns per-pane state such as connection and path, selection, sorting, filtering, dialogs, viewer state, incremental search, and directory refresh handling |\n| `pages/FileBrowser/FileBrowserPane.tsx` | renders one pane's UI |\n| `components/FileBrowser/CopyMoveDialog.tsx` | manages copy and move confirmation flow |\n| `config/keyboardShortcuts.ts` | central shortcut definitions used across the browser |\n\nThis split matters because two visible panes still need one coherent browser workflow.\n\nThe parent-versus-hook split is intentional:\n\n- `FileBrowser.tsx` owns shared state such as the connections list, active-pane routing, responsive layout, WebSocket connection lifecycle, and browser-level shortcut registration\n- `useFileBrowserPane.ts` owns per-pane state such as file loading, sort and filter state, viewer and dialog state, focus handling, multi-select state, and pane-specific directory-change reactions\n\n## Pane Model\n\nSambee supports one-pane and two-pane browsing, but the two-pane implementation is intentional rather than conditional duplication.\n\n- the left pane is always active in routing terms\n- the right pane is still instantiated even when not visible, which keeps the hook model stable\n- the active pane decides which pane keyboard shortcuts and toolbar commands target\n- dual-pane mode is desktop-first and collapses to single-pane on compact layouts\n- dual-pane preference and active-pane preference are persisted so the browser can restore the user's working style\n- the viewer opens as a fullscreen overlay from whichever pane launched it rather than being constrained to one pane region\n\nVisual state also matters:\n\n- the active pane gets the stronger emphasis treatment\n- the inactive pane is visually de-emphasized rather than treated as a separate route or different screen\n\n## URL-Synced Navigation\n\nThe file browser preserves layout state in the URL.\n\n- the primary pane stays in the path\n- the right pane is represented by the `p2` query parameter\n- active pane state is represented by the `active` query parameter\n\nThat design means refresh and back-forward navigation preserve more than a single path string.\n\nRepresentative shape:\n\n```text\nSingle pane: /browse/my-server/documents/subfolder\nDual pane:   /browse/my-server/documents?p2=other-server/photos\u0026active=2\n```\n\nImportant behavior:\n\n- the presence of `p2` on initial load activates dual-pane mode automatically\n- back and forward navigation can add or remove the second pane without changing the route definition itself\n- single-pane mode produces a clean URL without stale dual-pane query state\n- invalid right-pane connection slugs are ignored rather than breaking the whole browser route\n- the encoding model preserves slash-separated paths while still percent-encoding the path segments safely\n\n## Keyboard and Command Model\n\nKeyboard behavior is part of the product contract, not just convenience.\n\n- pane switching, selection, copy, and move use centralized shortcut definitions\n- the quick bar supports smart navigation, command mode, and pane-local current-directory filtering\n- browser defaults that conflict with the product's navigation model are overridden intentionally\n- shortcuts are disabled when dialogs or viewer states would make them unsafe\n\nChanges here can easily affect power-user workflows, accessibility, and focus management all at once.\n\nUse [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for the central registry, command-palette rules, and quick-bar interaction details. This page focuses on how those rules shape the file-browser architecture.\n\n## Pane-Local Current-Directory Filtering\n\nCurrent-directory filtering is part of pane state, not just quick-bar UI state.\n\nThe important design choice is that the quick bar only supplies the input shell. The actual filter value and filtered list live in `useFileBrowserPane`.\n\n- each pane owns its own `currentDirectoryFilter`\n- the pane computes `sortedAndFilteredFiles` from the normal sorted list plus the active filter text\n- the filtered list is the same list used by the virtualizer, keyboard navigation, viewer launch, selection helpers, and status bar\n- the active filter is considered scoped to the pane's current `connectionId + path`\n\nThat arrangement is what makes the behavior consistent in both single-pane and dual-pane workflows.\n\n### Why the Filter Lives in the Pane Hook\n\nThe filter is not modeled as a dropdown provider result set.\n\n- smart navigation is a navigation surface that benefits from dropdown results\n- command mode is a command surface that benefits from dropdown results\n- current-directory filtering is a local transformation of the pane's main file list\n\nBecause the pane already owns the rendered list, focus state, virtualizer, and file actions, the filter belongs there as well.\n\n### User-Facing Behavior the Architecture Must Preserve\n\nThe implemented flow is:\n\n1. `Ctrl+Alt+F` opens filter mode for the active pane.\n2. The shared input shows that pane's current filter value.\n3. Typing immediately filters the pane's main file list.\n4. `ArrowDown` from the input focuses the filtered file list.\n5. Arrow keys, `Home`, `End`, `PageUp`, `PageDown`, `Enter`, and file actions operate on the filtered visible list.\n6. Pressing `Ctrl+Alt+F` again returns focus to the same pane's filter input without clearing the term.\n\nReset and persistence rules are equally important:\n\n- switching between smart navigation, command mode, and filter mode does not clear the active filter\n- changing directories clears the filter for the new path scope\n- changing the pane connection also clears the filter\n- dual-pane mode keeps filter state isolated per pane\n- browser recovery snapshots capture and restore the pane filter together with path, focused item, and selection state\n\n### Focus and Zero-Result Behavior\n\nFiltering changes focus semantics because it can remove rows from the visible list.\n\n- if the previously focused file still exists in the filtered list, focus stays on that file\n- if it disappears, focus clamps to the nearest valid visible item\n- if the filter produces zero visible files, focus remains in the filter input when possible\n\nThat is why the pane hook owns both the filtered list and the focus-adjustment logic.\n\n### Status Bar Visibility\n\nThe filter must remain visible even when the quick bar is no longer in filter mode.\n\n- the desktop status bar renders the active filter term whenever the pane has a non-empty filter\n- the status bar uses the filtered visible list for item counts and file metadata\n- this keeps the active filter visible while the user switches to smart navigation or command mode\n\nThe status bar indicator is part of the product contract, not just decorative UI. It is the persistent signal that the pane is still filtered.\n\n## Selection, Copy, and Move\n\nThe browser maintains explicit multi-select state per pane, but still supports a focused-item fallback when nothing is explicitly selected.\n\nIn practice, the pane computes an effective selection from either:\n\n- the explicit selected-file set\n- or the focused file when nothing has been explicitly selected\n\nSelection is pane-local and clears naturally when directory navigation changes the active file list.\n\nCopy and move behavior depends on:\n\n- the active pane as the source\n- the other pane as the destination in dual-pane workflows\n- backend or companion routing depending on which connection types are involved\n- conflict and validation behavior that still comes from the destination backend contract\n\nThe copy and move dialog is not just a confirmation prompt. It also:\n\n- shows the selected source files\n- pre-fills the destination from the other pane\n- lets the user adjust the destination before confirming\n- reports progress while multiple operations execute\n\nImportant contract details:\n\n- `F5` means copy in dual-pane mode, but remains refresh in single-pane mode\n- `F6` means move in dual-pane mode\n- cross-connection operations are not treated the same as same-share SMB operations\n- backend validation still decides whether same-path, self-copy, or conflicting operations are allowed\n\nFor same-connection SMB copy and move, the backend uses server-side operations rather than streaming all file bytes through the browser app.\n\n## Refresh and Live State\n\nDirectory freshness is coordinated through WebSocket subscriptions.\n\n- the browser subscribes to each visible pane's directory\n- directory-change messages are routed back to the matching pane\n- local-drive and SMB-backed directories can use different backends while still feeding one browser experience\n\nIn dual-pane mode, both panes are live participants in refresh behavior:\n\n- each pane can subscribe to a different directory\n- each pane re-subscribes when its own path changes\n- directory-change events are dispatched back to the pane that owns the matching path and connection context\n\nThis is why navigation and data freshness are coupled more tightly than they first appear.\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome file-browser behaviors are deliberate tradeoffs rather than incidental implementation detail.\n\n- the UI caps visible panes at two even though the query-key pattern could theoretically scale further\n- browser-default shortcuts such as tab switching are overridden when they conflict with the product's pane model\n- dual-pane mode is disabled on compact layouts instead of forcing a cramped mobile approximation\n- one pane can stay hidden while still existing in state so the hook model remains stable\n\n## Why This Page Matters\n\nFrontend changes in the file browser often look local, but they can break:\n\n- URL-restoration behavior\n- keyboard and focus contracts\n- copy and move flows\n- viewer launch behavior\n- local-drive versus SMB routing assumptions\n- refresh behavior across both panes\n\n## Where to Continue\n\n- Use [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for centralized shortcut definitions, command-palette behavior, and focus rules.\n- Use [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/) for preview and file-type behavior.\n- Use [Browser-to-Companion Trust Model](../../companion-architecture/browser-to-companion-trust-model/) when navigation or actions depend on paired local-drive access.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when changes cross backend, frontend, and companion boundaries.\n", "1.0": "+++\ntitle = \"File Browser and Navigation Model\"\n+++\n\nThe file browser is the densest browser-side product surface in Sambee. It combines navigation, selection, editing entry points, viewer launch, keyboard behavior, and real-time directory refresh.\n\n## Core Component Split\n\nThe implementation is deliberately split between shared page logic and per-pane logic.\n\n| Area | Responsibility |\n|---|---|\n| `pages/FileBrowser.tsx` | owns shared browser-level concerns such as active pane routing, URL sync, WebSocket lifecycle, and global shortcut registration |\n| `pages/FileBrowser/useFileBrowserPane.ts` | owns per-pane state such as connection and path, selection, sorting, filtering, dialogs, viewer state, incremental search, and directory refresh handling |\n| `pages/FileBrowser/FileBrowserPane.tsx` | renders one pane's UI |\n| `components/FileBrowser/CopyMoveDialog.tsx` | manages copy and move confirmation flow |\n| `config/keyboardShortcuts.ts` | central shortcut definitions used across the browser |\n\nThis split matters because two visible panes still need one coherent browser workflow.\n\nThe parent-versus-hook split is intentional:\n\n- `FileBrowser.tsx` owns shared state such as the connections list, active-pane routing, responsive layout, WebSocket connection lifecycle, and browser-level shortcut registration\n- `useFileBrowserPane.ts` owns per-pane state such as file loading, sort and filter state, viewer and dialog state, focus handling, multi-select state, and pane-specific directory-change reactions\n\n## Pane Model\n\nSambee supports one-pane and two-pane browsing, but the two-pane implementation is intentional rather than conditional duplication.\n\n- the left pane is always active in routing terms\n- the right pane is still instantiated even when not visible, which keeps the hook model stable\n- the active pane decides which pane keyboard shortcuts and toolbar commands target\n- dual-pane mode is desktop-first and collapses to single-pane on compact layouts\n- dual-pane preference and active-pane preference are persisted so the browser can restore the user's working style\n- the viewer opens as a fullscreen overlay from whichever pane launched it rather than being constrained to one pane region\n\nVisual state also matters:\n\n- the active pane gets the stronger emphasis treatment\n- the inactive pane is visually de-emphasized rather than treated as a separate route or different screen\n\n## URL-Synced Navigation\n\nThe file browser preserves layout state in the URL.\n\n- the primary pane stays in the path\n- the right pane is represented by the `p2` query parameter\n- active pane state is represented by the `active` query parameter\n\nThat design means refresh and back-forward navigation preserve more than a single path string.\n\nRepresentative shape:\n\n```text\nSingle pane: /browse/my-server/documents/subfolder\nDual pane:   /browse/my-server/documents?p2=other-server/photos\u0026active=2\n```\n\nImportant behavior:\n\n- the presence of `p2` on initial load activates dual-pane mode automatically\n- back and forward navigation can add or remove the second pane without changing the route definition itself\n- single-pane mode produces a clean URL without stale dual-pane query state\n- invalid right-pane connection slugs are ignored rather than breaking the whole browser route\n- the encoding model preserves slash-separated paths while still percent-encoding the path segments safely\n\n## Keyboard and Command Model\n\nKeyboard behavior is part of the product contract, not just convenience.\n\n- pane switching, selection, copy, and move use centralized shortcut definitions\n- the quick bar supports smart navigation, command mode, and pane-local current-directory filtering\n- browser defaults that conflict with the product's navigation model are overridden intentionally\n- shortcuts are disabled when dialogs or viewer states would make them unsafe\n\nChanges here can easily affect power-user workflows, accessibility, and focus management all at once.\n\nUse [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for the central registry, command-palette rules, and quick-bar interaction details. This page focuses on how those rules shape the file-browser architecture.\n\n## Pane-Local Current-Directory Filtering\n\nCurrent-directory filtering is part of pane state, not just quick-bar UI state.\n\nThe important design choice is that the quick bar only supplies the input shell. The actual filter value and filtered list live in `useFileBrowserPane`.\n\n- each pane owns its own `currentDirectoryFilter`\n- the pane computes `sortedAndFilteredFiles` from the normal sorted list plus the active filter text\n- the filtered list is the same list used by the virtualizer, keyboard navigation, viewer launch, selection helpers, and status bar\n- the active filter is considered scoped to the pane's current `connectionId + path`\n\nThat arrangement is what makes the behavior consistent in both single-pane and dual-pane workflows.\n\n### Why the Filter Lives in the Pane Hook\n\nThe filter is not modeled as a dropdown provider result set.\n\n- smart navigation is a navigation surface that benefits from dropdown results\n- command mode is a command surface that benefits from dropdown results\n- current-directory filtering is a local transformation of the pane's main file list\n\nBecause the pane already owns the rendered list, focus state, virtualizer, and file actions, the filter belongs there as well.\n\n### User-Facing Behavior the Architecture Must Preserve\n\nThe implemented flow is:\n\n1. `Ctrl+Alt+F` opens filter mode for the active pane.\n2. The shared input shows that pane's current filter value.\n3. Typing immediately filters the pane's main file list.\n4. `ArrowDown` from the input focuses the filtered file list.\n5. Arrow keys, `Home`, `End`, `PageUp`, `PageDown`, `Enter`, and file actions operate on the filtered visible list.\n6. Pressing `Ctrl+Alt+F` again returns focus to the same pane's filter input without clearing the term.\n\nReset and persistence rules are equally important:\n\n- switching between smart navigation, command mode, and filter mode does not clear the active filter\n- changing directories clears the filter for the new path scope\n- changing the pane connection also clears the filter\n- dual-pane mode keeps filter state isolated per pane\n- browser recovery snapshots capture and restore the pane filter together with path, focused item, and selection state\n\n### Focus and Zero-Result Behavior\n\nFiltering changes focus semantics because it can remove rows from the visible list.\n\n- if the previously focused file still exists in the filtered list, focus stays on that file\n- if it disappears, focus clamps to the nearest valid visible item\n- if the filter produces zero visible files, focus remains in the filter input when possible\n\nThat is why the pane hook owns both the filtered list and the focus-adjustment logic.\n\n### Status Bar Visibility\n\nThe filter must remain visible even when the quick bar is no longer in filter mode.\n\n- the desktop status bar renders the active filter term whenever the pane has a non-empty filter\n- the status bar uses the filtered visible list for item counts and file metadata\n- this keeps the active filter visible while the user switches to smart navigation or command mode\n\nThe status bar indicator is part of the product contract, not just decorative UI. It is the persistent signal that the pane is still filtered.\n\n## Selection, Copy, and Move\n\nThe browser maintains explicit multi-select state per pane, but still supports a focused-item fallback when nothing is explicitly selected.\n\nIn practice, the pane computes an effective selection from either:\n\n- the explicit selected-file set\n- or the focused file when nothing has been explicitly selected\n\nSelection is pane-local and clears naturally when directory navigation changes the active file list.\n\nCopy and move behavior depends on:\n\n- the active pane as the source\n- the other pane as the destination in dual-pane workflows\n- backend or companion routing depending on which connection types are involved\n- conflict and validation behavior that still comes from the destination backend contract\n\nThe copy and move dialog is not just a confirmation prompt. It also:\n\n- shows the selected source files\n- pre-fills the destination from the other pane\n- lets the user adjust the destination before confirming\n- reports progress while multiple operations execute\n\nImportant contract details:\n\n- `F5` means copy in dual-pane mode, but remains refresh in single-pane mode\n- `F6` means move in dual-pane mode\n- cross-connection operations are not treated the same as same-share SMB operations\n- backend validation still decides whether same-path, self-copy, or conflicting operations are allowed\n\nFor same-connection SMB copy and move, the backend uses server-side operations rather than streaming all file bytes through the browser app.\n\n## Refresh and Live State\n\nDirectory freshness is coordinated through WebSocket subscriptions.\n\n- the browser subscribes to each visible pane's directory\n- directory-change messages are routed back to the matching pane\n- local-drive and SMB-backed directories can use different backends while still feeding one browser experience\n\nIn dual-pane mode, both panes are live participants in refresh behavior:\n\n- each pane can subscribe to a different directory\n- each pane re-subscribes when its own path changes\n- directory-change events are dispatched back to the pane that owns the matching path and connection context\n\nThis is why navigation and data freshness are coupled more tightly than they first appear.\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome file-browser behaviors are deliberate tradeoffs rather than incidental implementation detail.\n\n- the UI caps visible panes at two even though the query-key pattern could theoretically scale further\n- browser-default shortcuts such as tab switching are overridden when they conflict with the product's pane model\n- dual-pane mode is disabled on compact layouts instead of forcing a cramped mobile approximation\n- one pane can stay hidden while still existing in state so the hook model remains stable\n\n## Why This Page Matters\n\nFrontend changes in the file browser often look local, but they can break:\n\n- URL-restoration behavior\n- keyboard and focus contracts\n- copy and move flows\n- viewer launch behavior\n- local-drive versus SMB routing assumptions\n- refresh behavior across both panes\n\n## Where to Continue\n\n- Use [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for centralized shortcut definitions, command-palette behavior, and focus rules.\n- Use [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/) for preview and file-type behavior.\n- Use [Browser-to-Companion Trust Model](../../companion-architecture/browser-to-companion-trust-model/) when navigation or actions depend on paired local-drive access.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when changes cross backend, frontend, and companion boundaries.\n", "2.0": "+++\ntitle = \"File Browser and Navigation Model\"\n+++\n\nThe file browser is the densest browser-side product surface in Sambee. It combines navigation, selection, editing entry points, viewer launch, keyboard behavior, and real-time directory refresh.\n\n## Core Component Split\n\nThe implementation is deliberately split between shared page logic and per-pane logic.\n\n| Area | Responsibility |\n|---|---|\n| `pages/FileBrowser.tsx` | owns shared browser-level concerns such as active pane routing, URL sync, WebSocket lifecycle, and global shortcut registration |\n| `pages/FileBrowser/useFileBrowserPane.ts` | owns per-pane state such as connection and path, selection, sorting, filtering, dialogs, viewer state, incremental search, and directory refresh handling |\n| `pages/FileBrowser/routing.ts` | parses and serializes typed directory, viewer, editor, and settings locations |\n| `pages/FileBrowser/useWorkspaceNavigation.ts` | resolves viewer targets and owns workspace navigation and safe overlay return entries |\n| `hooks/useRoutedViewerEditing.tsx` | connects the active editor's existing confirmation dialog to React Router navigation blocking |\n| `pages/FileBrowser/FileBrowserPane.tsx` | renders one pane's UI |\n| `components/FileBrowser/CopyMoveDialog.tsx` | manages copy and move confirmation flow |\n| `config/keyboardShortcuts.ts` | central shortcut definitions used across the browser |\n\nThis split matters because two visible panes still need one coherent browser workflow.\n\nThe parent-versus-hook split is intentional:\n\n- `FileBrowser.tsx` owns shared state such as the connections list, active-pane routing, responsive layout, WebSocket connection lifecycle, and browser-level shortcut registration\n- `useFileBrowserPane.ts` owns per-pane state such as file loading, sort and filter state, viewer and dialog state, focus handling, multi-select state, and pane-specific directory-change reactions\n\n## Pane Model\n\nSambee supports one-pane and two-pane browsing, but the two-pane implementation is intentional rather than conditional duplication.\n\n- the left pane is always active in routing terms\n- the right pane is still instantiated even when not visible, which keeps the hook model stable\n- the active pane decides which pane keyboard shortcuts and toolbar commands target\n- dual-pane mode is desktop-first and collapses to single-pane on compact layouts\n- dual-pane preference and active-pane preference are persisted so the browser can restore the user's working style\n- the viewer opens as a fullscreen overlay from whichever pane launched it rather than being constrained to one pane region\n\nVisual state also matters:\n\n- the active pane gets the stronger emphasis treatment\n- the inactive pane is visually de-emphasized rather than treated as a separate route or different screen\n\n## Real-Time Directory Refresh\n\nEach pane handles directory-change notifications independently. An automatic refresh keeps an already loaded physical-directory listing mounted, including an empty listing, so unchanged rows retain selection, keyboard focus, and scroll position. Initial loading and navigation without a usable snapshot still show loading feedback.\n\nNotifications don't cancel an active listing request. Instead, the pane remembers that another refresh is needed and starts one follow-up request after the active request finishes. Automatic refreshes start at most once per second. Further notifications don't move an existing deadline, so continuous writes still produce periodic updates. Navigation and unmount cancel queued work.\n\nA listing with unprocessed change notifications can remain visible, but it isn't cached as fresh. Deferred link-target metadata only updates cache entries that are still valid, so cancelling a follow-up refresh can't make an outdated snapshot reusable on return.\n\nSMB file-list subscriptions watch immediate children rather than the whole subtree. The separate backend directory-search cache retains recursive directory-name monitoring. See [SMB Change Notification and Directory Freshness](../../backend-architecture/smb-change-notification-and-directory-freshness/) for watcher ownership and lifecycle.\n\n## URL-Driven Workspace Navigation\n\nThe URL selects the directory, pane layout, viewer, editing intent, and settings view. The file browser stays mounted under overlays. Loaded content, drafts, locks, selection, scroll, search panels, and zoom remain runtime state.\n\n| Part | Meaning |\n|---|---|\n| `/browse/smb/\u003cslug\u003e/\u003cpath\u003e` | Primary SMB pane |\n| `/browse/local/\u003cdrive-id\u003e/\u003cpath\u003e` | Primary companion-drive pane |\n| `p2=\u003ckind\u003e/\u003ctarget\u003e/\u003cpath\u003e` | Right pane, enabled when present |\n| `active=2` | Right pane is active |\n| `file=\u003ckind\u003e/\u003ctarget\u003e/\u003cpath\u003e` | Viewer target, independent of the directory and active pane |\n| `viewer=image\\|markdown\\|pdf\\|text` | Requested browser viewer |\n| `mode=edit` | Editing intent for text or Markdown |\n| `pane=2` | Right pane owns the viewer; requires a right-pane target |\n| `virtual=\u003cJSON array\u003e` | Archive member descriptor: provider ID, source archive path, member path |\n| `settings=main\\|\u003ccategory\u003e` | Settings main view or category from the shared category registry |\n\nFor example:\n\n```text\n/browse/smb/my-server/documents\n/browse/smb/my-server/documents?p2=smb%2Fother-server%2Fphotos\u0026active=2\n/browse/smb/my-server/documents?file=smb%2Fmy-server%2Fdocuments%2Fnotes.md\u0026viewer=markdown\n/browse/smb/my-server/documents?file=smb%2Fmy-server%2Fdocuments%2Fnotes.md\u0026viewer=markdown\u0026mode=edit\n/browse/smb/my-server/documents?settings=account\n```\n\nUse the shared parser/serializer and `URLSearchParams`, not concatenated query strings. File descriptors encode target IDs and individual path segments before query serialization. The archive provider is currently `zip`. Runtime session IDs, file contents, MIME guesses, gallery arrays, credentials, and lock capabilities never belong in navigation state.\n\n### Navigation and Dismissal\n\nOpening or closing a viewer, entering or leaving editing, changing gallery images, opening or closing settings, and changing settings categories push history entries. Repeating the same location does nothing. Pane-focus updates, invalid-descriptor recovery, failed edit acquisition, and canonicalization replace the current entry. Unrelated query parameters and authentication fragments are preserved.\n\nBack and Forward follow actual history without adding entries. Explicit Close pushes the current workspace with the dismissed layer removed, including for direct links and refreshed viewers. For example, opening a directory, opening an image, and closing it produces directory, image, and directory entries; Back reopens the image before returning to the earlier directory entry. A new action after Back discards the old Forward branch, following normal browser behavior. Close doesn't depend on opening-entry metadata or `history.length`. Settings back controls traverse observed history; without an observed predecessor they replace the URL with an in-app parent.\n\nDesktop settings and the mobile drawer are controlled by the same category descriptor. `settings=main` displays the desktop default category or the mobile category list. Resizing changes presentation without navigation. Standalone `/settings/...` routes and their aliases use the same category content and authorization checks. User Management owns its query keys through React Router, merging them with workspace parameters.\n\n### Direct Links and Recovery\n\nViewer links resolve metadata through the storage registry or content provider, without simulated file-row clicks. Resolution is cancelled when its identity changes. Missing resources show Retry and Close actions. A viewer URL never falls back to opening a native application.\n\nThe incoming URL always wins over a browser recovery snapshot. Snapshot hydration matches each pane's resource identity, clears legacy viewer state, and ignores unmatched panes. A bare `/browse` uses normal default navigation. Captured snapshots use the current canonical workspace URL and contain neither callback fragments nor edit-session tokens.\n\n### Viewer Loading and Transitions\n\nLoading feedback belongs to the selected image, PDF, text, or Markdown viewer. Workspace metadata resolution and dynamic component imports do not show an intermediate full-screen loading dialog. On an initial opening, the browser remains visible until metadata and the viewer component are available; the viewer then displays its existing content-loading feedback.\n\nDuring file-to-file or history navigation, keep the outgoing viewer presentation mounted until the replacement metadata and component are ready. Do not expose the directory between viewers or pass the new target's props to the old viewer component. Outgoing controls and shortcuts are suspended during the handoff, while Escape can cancel the pending opening. The existing error dialogs retain Retry and Close actions. Cancellation rejects late results rather than reopening a dismissed viewer.\n\nOne dynamic viewer host serves both panes. An explicit viewer ID, not an image's changing MIME type, controls component loading. Text and Markdown still reset resource-local state when the actual file changes; mode-only and settings-only navigation do not restart the viewer.\n\n### Editing and Router Integrity\n\nThe app uses a data router (`createBrowserRouter` and `RouterProvider`) for supported `useBlocker` behavior. One guard owner delegates resource-leaving transitions to the active text or Markdown editor when its draft is dirty, a save is pending, or a session is being acquired. Clean editor Back and Forward navigate directly, avoiding the history reversal required by a blocked browser navigation. Cancel keeps the draft and lock; successful Save or Discard continues the original transition; failed Save keeps the editor open. Changes that retain the same edited resource and mode don't discard its draft. Dirty drafts also register `beforeunload` protection.\n\nEdit bookmarks and history navigation back into editing acquire a fresh edit session after content and permission checks. Navigating away during acquisition invalidates the attempt and releases any late lock. Leaving editing releases its session once. The outgoing editor is read-only during cleanup, and re-entry waits for that cleanup to finish so an old release can't clear a new session. History restores navigation intent, not old file contents, discarded drafts, or saved locks. An edit URL doesn't grant permission.\n\nFull page reloads, including F5 and the update prompt, can resume the same edit lock. The shared storage edit-session layer keeps lock credentials separately in tab-scoped session storage, keyed by user, connection, and file. On reload it validates those credentials with a heartbeat before reusing them. Only a structured lost-lock response permits fresh acquisition; network and permission failures don't trigger replacement. Credentials follow replacement locks and are removed on successful release or logout. Unsaved text still uses the existing draft-recovery flow.\n\nRecovery requires session storage and the browser Web Locks API, available in secure contexts such as HTTPS and localhost. An exclusive Web Lock prevents another tab from using copied recovery credentials, even if that tab reloads. Without those capabilities, editing still works, but a reload may need to wait for the abandoned server lock to expire. Fresh navigations and history entries don't resume saved credentials, and no credentials appear in the URL or workspace recovery snapshot.\n\nUse router navigation for all mounted-route URL writes, including authentication fragment cleanup. `useRemoveLocationFragment` replaces the entry, removes only consumed fragment keys, and preserves the full query and application state. Never clear router-managed history state with `replaceState(null, ...)`: doing so can disable POP blocking.\n\n## Keyboard and Command Model\n\nKeyboard behavior is part of the product contract, not just convenience.\n\n- pane switching, selection, copy, and move use centralized shortcut definitions\n- the quick bar supports smart navigation, command mode, and pane-local current-directory filtering\n- browser defaults that conflict with the product's navigation model are overridden intentionally\n- shortcuts are disabled when dialogs or viewer states would make them unsafe\n\nChanges here can easily affect power-user workflows, accessibility, and focus management all at once.\n\nUse [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for the central registry, command-palette rules, and quick-bar interaction details. This page focuses on how those rules shape the file-browser architecture.\n\n## Pane-Local Current-Directory Filtering\n\nCurrent-directory filtering is part of pane state, not just quick-bar UI state.\n\nThe important design choice is that the quick bar only supplies the input shell. The actual filter value and filtered list live in `useFileBrowserPane`.\n\n- each pane owns its own `currentDirectoryFilter`\n- the pane computes `sortedAndFilteredFiles` from the normal sorted list plus the active filter text\n- the filtered list is the same list used by the virtualizer, keyboard navigation, viewer launch, selection helpers, and status bar\n- the active filter is considered scoped to the pane's current `connectionId + path`\n\nThat arrangement is what makes the behavior consistent in both single-pane and dual-pane workflows.\n\n### Why the Filter Lives in the Pane Hook\n\nThe filter is not modeled as a dropdown provider result set.\n\n- smart navigation is a navigation surface that benefits from dropdown results\n- command mode is a command surface that benefits from dropdown results\n- current-directory filtering is a local transformation of the pane's main file list\n\nBecause the pane already owns the rendered list, focus state, virtualizer, and file actions, the filter belongs there as well.\n\n### User-Facing Behavior the Architecture Must Preserve\n\nThe implemented flow is:\n\n1. `Ctrl+Alt+F` opens filter mode for the active pane.\n2. The shared input shows that pane's current filter value.\n3. Typing immediately filters the pane's main file list.\n4. `ArrowDown` from the input focuses the filtered file list.\n5. Arrow keys, `Home`, `End`, `PageUp`, `PageDown`, `Enter`, and file actions operate on the filtered visible list.\n6. Pressing `Ctrl+Alt+F` again returns focus to the same pane's filter input without clearing the term.\n\nReset and persistence rules are equally important:\n\n- switching between smart navigation, command mode, and filter mode does not clear the active filter\n- changing directories clears the filter for the new path scope\n- changing the pane connection also clears the filter\n- dual-pane mode keeps filter state isolated per pane\n- browser recovery snapshots capture and restore the pane filter together with path, focused item, and selection state\n\n### Focus and Zero-Result Behavior\n\nFiltering changes focus semantics because it can remove rows from the visible list.\n\n- if the previously focused file still exists in the filtered list, focus stays on that file\n- if it disappears, focus clamps to the nearest valid visible item\n- if the filter produces zero visible files, focus remains in the filter input when possible\n\nThat is why the pane hook owns both the filtered list and the focus-adjustment logic.\n\n### Status Bar Visibility\n\nThe filter must remain visible even when the quick bar is no longer in filter mode.\n\n- the desktop status bar renders the active filter term whenever the pane has a non-empty filter\n- the status bar uses the filtered visible list for item counts and file metadata\n- this keeps the active filter visible while the user switches to smart navigation or command mode\n\nThe status bar indicator is part of the product contract, not just decorative UI. It is the persistent signal that the pane is still filtered.\n\n## Selection, Copy, and Move\n\nThe browser maintains explicit multi-select state per pane, but still supports a focused-item fallback when nothing is explicitly selected.\n\nIn practice, the pane computes an effective selection from either:\n\n- the explicit selected-file set\n- or the focused file when nothing has been explicitly selected\n\nSelection is pane-local and clears naturally when directory navigation changes the active file list.\n\nCopy and move behavior depends on:\n\n- the active pane as the source\n- the other pane as the destination in dual-pane workflows\n- backend or companion routing depending on which connection types are involved\n- conflict and validation behavior that still comes from the destination backend contract\n\nThe copy and move dialog is not just a confirmation prompt. It also:\n\n- shows the selected source files\n- pre-fills the destination from the other pane\n- lets the user adjust the destination before confirming\n- reports progress while multiple operations execute\n\nImportant contract details:\n\n- `F5` means copy in dual-pane mode, but remains refresh in single-pane mode\n- `F6` means move in dual-pane mode\n- cross-connection operations are not treated the same as same-share SMB operations\n- backend validation still decides whether same-path, self-copy, or conflicting operations are allowed\n\nFor same-connection SMB copy and move, the backend uses server-side operations rather than streaming all file bytes through the browser app.\n\n## Refresh and Live State\n\nDirectory freshness is coordinated through WebSocket subscriptions.\n\n- the browser subscribes to each visible pane's directory\n- directory-change messages are routed back to the matching pane\n- local-drive and SMB-backed directories can use different backends while still feeding one browser experience\n\nIn dual-pane mode, both panes are live participants in refresh behavior:\n\n- each pane can subscribe to a different directory\n- each pane re-subscribes when its own path changes\n- directory-change events are dispatched back to the pane that owns the matching path and connection context\n\nThis is why navigation and data freshness are coupled more tightly than they first appear.\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome file-browser behaviors are deliberate tradeoffs rather than incidental implementation detail.\n\n- the UI caps visible panes at two even though the query-key pattern could theoretically scale further\n- browser-default shortcuts such as tab switching are overridden when they conflict with the product's pane model\n- dual-pane mode is disabled on compact layouts instead of forcing a cramped mobile approximation\n- one pane can stay hidden while still existing in state so the hook model remains stable\n\n## Why This Page Matters\n\nFrontend changes in the file browser often look local, but they can break:\n\n- URL-restoration behavior\n- keyboard and focus contracts\n- copy and move flows\n- viewer launch behavior\n- local-drive versus SMB routing assumptions\n- refresh behavior across both panes\n\n## Where to Continue\n\n- Use [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for centralized shortcut definitions, command-palette behavior, and focus rules.\n- Use [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/) for preview and file-type behavior.\n- Use [Browser-to-Companion Trust Model](../../companion-architecture/browser-to-companion-trust-model/) when navigation or actions depend on paired local-drive access.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when changes cross backend, frontend, and companion boundaries.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/frontend-architecture/keyboard-shortcuts-and-command-model", "parent_id": "section:developer-guide/frontend-architecture", "depth": 2, "kind": "page", "label": "keyboard-shortcuts-and-command-model", "title": "Keyboard Shortcuts And Command Model", "path": "developer-guide/frontend-architecture/keyboard-shortcuts-and-command-model", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "branched", "source_version": "0.7", "diff_added": 14, "diff_removed": 6}, "2.0": {"state": "inherited", "source_version": "1.0"}}, "content_versions": {"0.7": "+++\ntitle = \"Keyboard Shortcuts and Command Model\"\n+++\n\nKeyboard behavior in Sambee is a shared frontend system, not a pile of local `keydown` handlers.\n\nThe product depends on contributors keeping shortcuts, command labels, viewer controls, and file-browser focus behavior aligned.\n\n## Core Pieces\n\nThese files define the keyboard and command model:\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/config/keyboardShortcuts.ts` | single source of truth for shortcut definitions and display labels |\n| `frontend/src/config/browserCommands.ts` | file-browser command registry for command-palette behavior |\n| `frontend/src/hooks/useKeyboardShortcuts.ts` | shared hook that binds shortcut definitions to runtime handlers |\n| `frontend/src/pages/FileBrowser.tsx` | registers browser-level shortcuts and routes command actions |\n| `frontend/src/components/Viewer/` | consumes shared shortcut definitions for viewer behavior and tooltip labels |\n\nThe system is intentionally split so shortcuts stay declarative while feature surfaces keep control of their own runtime behavior.\n\n## Why the Registry Exists\n\nBefore the centralized model, shortcut keys, tooltip labels, and component handlers drifted apart easily.\n\nThe current approach preserves these rules:\n\n- define shortcut keys and display intent once\n- reuse the same definition across viewers and file-browser surfaces\n- let components supply handlers without redefining labels and modifiers\n- keep file-browser actions discoverable even when users do not know the shortcut\n\n## Shortcut Definition Model\n\nShortcut definitions are grouped by scope, such as common viewer actions, PDF-specific actions, image-viewer actions, or browser actions.\n\nRepresentative structure:\n\n```typescript\nexport const COMMON_SHORTCUTS = {\n  CLOSE: {\n    id: \"close\",\n    keys: \"Escape\",\n    description: \"Close\",\n    label: \"Esc\",\n    allowInInput: true,\n  },\n  DOWNLOAD: {\n    id: \"download\",\n    keys: \"s\",\n    description: \"Download\",\n    label: \"Ctrl+S\",\n    ctrl: true,\n  },\n} as const;\n```\n\nCommon properties include:\n\n- `id`: stable identifier\n- `keys`: one key or multiple equivalent keys\n- `description`: human-readable intent\n- `label`: optional display label; if omitted, it can be generated from the config\n- `ctrl`, `shift`, `alt`: required modifiers\n- `allowInInput`: whether the shortcut still works while an input is focused\n- `priority`: ordering for overlapping shortcut candidates\n\n## Using the Shared Hook\n\nFeature components bind runtime behavior through `useKeyboardShortcuts` instead of duplicating event parsing logic.\n\nTypical usage:\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...COMMON_SHORTCUTS.CLOSE,\n      handler: onClose,\n    },\n    {\n      ...COMMON_SHORTCUTS.DOWNLOAD,\n      handler: handleDownload,\n    },\n    {\n      ...PDF_SHORTCUTS.SEARCH,\n      handler: handleOpenSearch,\n    },\n  ],\n});\n```\n\nThat split keeps the registry declarative and keeps feature logic in the feature component.\n\n## Labels and Tooltip Reuse\n\nViewer controls and similar UI surfaces should reuse the same shortcut definition instead of duplicating string formatting.\n\nThe shared formatter can turn a shortcut definition into a tooltip label such as `Download (Ctrl+S)`.\n\nThat matters because a changed shortcut should update viewer behavior and visible affordances together.\n\n## Browser Commands Versus Raw Shortcuts\n\nThe file browser uses both shortcut definitions and a command registry.\n\n- shortcut definitions remain centralized in `keyboardShortcuts.ts`\n- discoverable browser actions live in `browserCommands.ts`\n- command definitions point back to shortcut identifiers when a keyboard binding exists\n\nThis lets Sambee expose browser actions through the quick bar even when the user does not know the shortcut.\n\nEach browser command definition includes concepts such as:\n\n- a stable `id`\n- a user-facing `title`\n- a `category` for command grouping\n- linked shortcut identifiers\n- `isEnabled(context)` for context-aware availability\n- `run(context)` for execution\n- `selectionFocusTarget` for post-selection focus behavior\n\n## Quick-Bar Modes\n\nThe file browser quick bar is not just a text filter. It supports multiple modes with different intent.\n\n- `Ctrl+K`: open the smart navigation surface\n- `Ctrl+Alt+F`: open pane-local current-directory filter mode\n- `Ctrl+P` or `F1`: open command mode directly\n- typing `\u003e` as the first character switches the quick bar into command mode\n\nSmart navigation and command mode are dropdown-backed provider modes. Filter mode deliberately is not.\n\n- `smart` mode uses the search provider composition that merges directory navigation and command escape-hatch behavior\n- `commands` mode uses the browser command registry directly\n- `filter` mode uses the same input shell, but as a controlled pane-local filter box with dropdown rendering disabled\n\nThe quick bar captures the pane that opened it. In dual-pane mode, the active quick-bar pane stays fixed even if the other pane becomes active before selection.\n\nThat capture rule matters especially for filter mode, because the filter text belongs to the pane state, not to the shared quick-bar component.\n\n### Current-Directory Filter Mode\n\n`Ctrl+Alt+F` is now a real current-directory filter workflow, not a smart-navigation alias.\n\nThe implemented contract is:\n\n- the active pane opens the quick bar in `filter` mode\n- the quick bar shows that pane's `currentDirectoryFilter` as a controlled value\n- typing filters the pane's visible file list immediately\n- no dropdown results are shown in this mode\n- `ArrowDown` hands focus from the input into the pane's file list\n- `Escape` clears the filter first, then returns focus to the file list when the input is already empty\n\nThe filter state is pane-local and scoped to the current `connectionId + path`.\n\n- switching between `smart`, `commands`, and `filter` modes does not clear the current directory filter\n- navigating to a different directory clears the filter for the new scope\n- changing the pane's connection also clears the filter for the new scope\n- the status bar remains the persistent reminder that a filter is active even when the quick bar is in another mode\n\n## Current Browser-Level Shortcuts\n\nCurrent browser-level shortcuts include:\n\n- `Ctrl+K`: open smart navigation\n- `Ctrl+Alt+F`: focus current-directory filter mode for the active pane\n- `Ctrl+P`: show commands\n- `F1`: alternate binding for show commands\n- `Ctrl+,`: open settings\n- `?`: show keyboard shortcuts help\n- `Backspace`: go up one directory\n- `Ctrl+R`: refresh file list\n- `F2`: rename focused item\n- `Delete`: delete focused item\n- `F7`: create new directory\n- `Shift+F7`: create new file\n- `Ctrl+Enter`: open focused file in the companion app\n- `Ctrl+B`: toggle dual-pane view\n- `Ctrl+1`: focus left pane\n- `Ctrl+2`: focus right pane\n- `Tab`: switch active pane\n- `F5`: copy to the other pane\n- `F6`: move to the other pane\n\nWhen changing these, treat the behavior as product-level interaction design rather than local implementation detail.\n\n## Focus and Interaction Rules\n\nShortcut work often breaks focus behavior before it breaks functionality. Keep these rules intact:\n\n- opening the quick bar focuses its input immediately\n- selecting a navigation result returns focus to the relevant file list\n- selecting commands that switch quick-bar modes keeps focus inside the quick bar\n- `ArrowDown` from current-directory filter mode moves focus into the filtered file list\n- current-directory filter mode does not open a dropdown for local matches\n- `Escape` in filter mode clears the active filter before it hands focus back to the file list\n- commands that open dialogs or settings do not force focus back to the file list\n- pane-switching shortcuts do not fire while the quick-bar input is focused\n- shortcuts that should work during text entry must explicitly opt in with `allowInInput`\n- shortcuts should be disabled when dialog state or viewer state would make them unsafe\n\n## Context-Aware Shortcut Handling\n\nWhen one key needs different behavior depending on state, prefer one context-aware handler over overlapping registrations.\n\nFor example, `Escape` may close a search panel when that panel is open, but close the viewer when it is not.\n\nThat pattern is better than registering multiple conflicting `Escape` shortcuts because:\n\n- one shortcut definition stays authoritative\n- behavior remains explicit in the component state logic\n- conflicts are easier to reason about and test\n\n### Priority as an Escape Hatch\n\nIn rare cases, multiple handlers for one key are unavoidable. The system supports a `priority` field so higher-priority candidates are evaluated first.\n\nUse that sparingly. A context-aware handler is usually easier to understand and maintain than several competing registrations.\n\n## Adding New Shortcuts Safely\n\nWhen you add a shortcut, keep the workflow centralized.\n\n1. define the shortcut in `config/keyboardShortcuts.ts`\n2. bind it through `useKeyboardShortcuts` in the feature component\n3. reuse the same definition for tooltip or help-surface labels\n4. test both the runtime behavior and the visible affordance\n\nTypical sequence:\n\n```typescript\nexport const PDF_SHORTCUTS = {\n  PRINT: {\n    id: \"print\",\n    keys: \"p\",\n    description: \"Print\",\n    label: \"Ctrl+P\",\n    ctrl: true,\n  },\n} as const;\n```\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...PDF_SHORTCUTS.PRINT,\n      handler: handlePrint,\n    },\n  ],\n});\n```\n\n```typescript\ntitle={withShortcut(PDF_SHORTCUTS.PRINT)}\n```\n\nDo not add one-off tooltip strings or imperative event parsing when the shortcut belongs in the shared system.\n\n## Label Formatting Rules\n\nThe shortcut system also owns display formatting.\n\n- `ArrowRight` becomes `Right`\n- `ArrowLeft` becomes `Left`\n- `ArrowUp` becomes `Up`\n- `ArrowDown` becomes `Down`\n- `Escape` becomes `Esc`\n- space becomes `Space`\n- multiple equivalent keys are joined with ` / `\n- modifiers render as `Ctrl+`, `Shift+`, and `Alt+`\n\nThat formatting should come from the shared system, not from ad hoc component strings.\n\n## Common Failure Modes\n\n- shortcut keys and visible labels drift apart\n- a component registers imperative keyboard logic instead of using the shared hook\n- the browser command palette exposes actions that do not respect the current UI context\n- shortcuts fire while text input or dialog state should block them\n- quick-bar focus returns to the wrong pane in dual-pane workflows\n- multiple overlapping handlers compete for one key instead of using a context-aware handler\n\n## Validation Expectations\n\nWhen keyboard behavior changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change affects file-browser behavior, also test:\n\n- quick-bar navigation and command mode\n- pane switching in dual-pane and single-pane layouts\n- dialog safety for destructive shortcuts\n- viewer shortcut labels and matching runtime behavior\n\nFor new shortcut registrations, also verify:\n\n- the shared label matches the actual bound keys\n- `allowInInput` behavior matches the intended text-entry experience\n- priority and enabled-state logic do not create hidden overlaps\n\n## Where to Continue\n\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL sync, selection, and refresh behavior\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): viewer reuse, preview behavior, and file-type contracts\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): other shared frontend systems contributors should keep centralized\n", "0.8": "+++\ntitle = \"Keyboard Shortcuts and Command Model\"\n+++\n\nKeyboard behavior in Sambee is a shared frontend system, not a pile of local `keydown` handlers.\n\nThe product depends on contributors keeping shortcuts, command labels, viewer controls, and file-browser focus behavior aligned.\n\n## Core Pieces\n\nThese files define the keyboard and command model:\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/config/keyboardShortcuts.ts` | single source of truth for shortcut definitions and display labels |\n| `frontend/src/config/browserCommands.ts` | file-browser command registry for command-palette behavior |\n| `frontend/src/hooks/useKeyboardShortcuts.ts` | shared hook that binds shortcut definitions to runtime handlers |\n| `frontend/src/pages/FileBrowser.tsx` | registers browser-level shortcuts and routes command actions |\n| `frontend/src/components/Viewer/` | consumes shared shortcut definitions for viewer behavior and tooltip labels |\n\nThe system is intentionally split so shortcuts stay declarative while feature surfaces keep control of their own runtime behavior.\n\n## Why the Registry Exists\n\nBefore the centralized model, shortcut keys, tooltip labels, and component handlers drifted apart easily.\n\nThe current approach preserves these rules:\n\n- define shortcut keys and display intent once\n- reuse the same definition across viewers and file-browser surfaces\n- let components supply handlers without redefining labels and modifiers\n- keep file-browser actions discoverable even when users do not know the shortcut\n\n## Shortcut Definition Model\n\nShortcut definitions are grouped by scope, such as common viewer actions, PDF-specific actions, image-viewer actions, or browser actions.\n\nRepresentative structure:\n\n```typescript\nexport const COMMON_SHORTCUTS = {\n  CLOSE: {\n    id: \"close\",\n    keys: \"Escape\",\n    description: \"Close\",\n    label: \"Esc\",\n    allowInInput: true,\n  },\n  DOWNLOAD: {\n    id: \"download\",\n    keys: \"s\",\n    description: \"Download\",\n    label: \"Ctrl+S\",\n    ctrl: true,\n  },\n} as const;\n```\n\nCommon properties include:\n\n- `id`: stable identifier\n- `keys`: one key or multiple equivalent keys\n- `description`: human-readable intent\n- `label`: optional display label; if omitted, it can be generated from the config\n- `ctrl`, `shift`, `alt`: required modifiers\n- `allowInInput`: whether the shortcut still works while an input is focused\n- `priority`: ordering for overlapping shortcut candidates\n\n## Using the Shared Hook\n\nFeature components bind runtime behavior through `useKeyboardShortcuts` instead of duplicating event parsing logic.\n\nTypical usage:\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...COMMON_SHORTCUTS.CLOSE,\n      handler: onClose,\n    },\n    {\n      ...COMMON_SHORTCUTS.DOWNLOAD,\n      handler: handleDownload,\n    },\n    {\n      ...PDF_SHORTCUTS.SEARCH,\n      handler: handleOpenSearch,\n    },\n  ],\n});\n```\n\nThat split keeps the registry declarative and keeps feature logic in the feature component.\n\n## Labels and Tooltip Reuse\n\nViewer controls and similar UI surfaces should reuse the same shortcut definition instead of duplicating string formatting.\n\nThe shared formatter can turn a shortcut definition into a tooltip label such as `Download (Ctrl+S)`.\n\nThat matters because a changed shortcut should update viewer behavior and visible affordances together.\n\n## Browser Commands Versus Raw Shortcuts\n\nThe file browser uses both shortcut definitions and a command registry.\n\n- shortcut definitions remain centralized in `keyboardShortcuts.ts`\n- discoverable browser actions live in `browserCommands.ts`\n- command definitions point back to shortcut identifiers when a keyboard binding exists\n\nThis lets Sambee expose browser actions through the quick bar even when the user does not know the shortcut.\n\nEach browser command definition includes concepts such as:\n\n- a stable `id`\n- a user-facing `title`\n- a `category` for command grouping\n- linked shortcut identifiers\n- `isEnabled(context)` for context-aware availability\n- `run(context)` for execution\n- `selectionFocusTarget` for post-selection focus behavior\n\n## Quick-Bar Modes\n\nThe file browser quick bar is not just a text filter. It supports multiple modes with different intent.\n\n- `Ctrl+K`: open the smart navigation surface\n- `Ctrl+Alt+F`: open pane-local current-directory filter mode\n- `Ctrl+P` or `F1`: open command mode directly\n- typing `\u003e` as the first character switches the quick bar into command mode\n\nSmart navigation and command mode are dropdown-backed provider modes. Filter mode deliberately is not.\n\n- `smart` mode uses the search provider composition that merges directory navigation and command escape-hatch behavior\n- `commands` mode uses the browser command registry directly\n- `filter` mode uses the same input shell, but as a controlled pane-local filter box with dropdown rendering disabled\n\nThe quick bar captures the pane that opened it. In dual-pane mode, the active quick-bar pane stays fixed even if the other pane becomes active before selection.\n\nThat capture rule matters especially for filter mode, because the filter text belongs to the pane state, not to the shared quick-bar component.\n\n### Current-Directory Filter Mode\n\n`Ctrl+Alt+F` is now a real current-directory filter workflow, not a smart-navigation alias.\n\nThe implemented contract is:\n\n- the active pane opens the quick bar in `filter` mode\n- the quick bar shows that pane's `currentDirectoryFilter` as a controlled value\n- typing filters the pane's visible file list immediately\n- no dropdown results are shown in this mode\n- `ArrowDown` hands focus from the input into the pane's file list\n- `Escape` clears the filter first, then returns focus to the file list when the input is already empty\n\nThe filter state is pane-local and scoped to the current `connectionId + path`.\n\n- switching between `smart`, `commands`, and `filter` modes does not clear the current directory filter\n- navigating to a different directory clears the filter for the new scope\n- changing the pane's connection also clears the filter for the new scope\n- the status bar remains the persistent reminder that a filter is active even when the quick bar is in another mode\n\n## Current Browser-Level Shortcuts\n\nCurrent browser-level shortcuts include:\n\n- `Ctrl+K`: open smart navigation\n- `Ctrl+Alt+F`: focus current-directory filter mode for the active pane\n- `Ctrl+P`: show commands\n- `F1`: alternate binding for show commands\n- `Ctrl+,`: open settings\n- `?`: show keyboard shortcuts help\n- `Backspace`: go up one directory\n- `Ctrl+R`: refresh file list\n- `F2`: rename focused item\n- `Delete`: delete focused item\n- `F7`: create new directory\n- `Shift+F7`: create new file\n- `Ctrl+Enter`: open focused file in the companion app\n- `Ctrl+B`: toggle dual-pane view\n- `Ctrl+1`: focus left pane\n- `Ctrl+2`: focus right pane\n- `Tab`: switch active pane\n- `F5`: copy to the other pane\n- `F6`: move to the other pane\n\nWhen changing these, treat the behavior as product-level interaction design rather than local implementation detail.\n\n## Focus and Interaction Rules\n\nShortcut work often breaks focus behavior before it breaks functionality. Keep these rules intact:\n\n- opening the quick bar focuses its input immediately\n- selecting a navigation result returns focus to the relevant file list\n- selecting commands that switch quick-bar modes keeps focus inside the quick bar\n- `ArrowDown` from current-directory filter mode moves focus into the filtered file list\n- current-directory filter mode does not open a dropdown for local matches\n- `Escape` in filter mode clears the active filter before it hands focus back to the file list\n- commands that open dialogs or settings do not force focus back to the file list\n- pane-switching shortcuts do not fire while the quick-bar input is focused\n- shortcuts that should work during text entry must explicitly opt in with `allowInInput`\n- shortcuts should be disabled when dialog state or viewer state would make them unsafe\n\n## Context-Aware Shortcut Handling\n\nWhen one key needs different behavior depending on state, prefer one context-aware handler over overlapping registrations.\n\nFor example, `Escape` may close a search panel when that panel is open, but close the viewer when it is not.\n\nThat pattern is better than registering multiple conflicting `Escape` shortcuts because:\n\n- one shortcut definition stays authoritative\n- behavior remains explicit in the component state logic\n- conflicts are easier to reason about and test\n\n### Priority as an Escape Hatch\n\nIn rare cases, multiple handlers for one key are unavoidable. The system supports a `priority` field so higher-priority candidates are evaluated first.\n\nUse that sparingly. A context-aware handler is usually easier to understand and maintain than several competing registrations.\n\n## Adding New Shortcuts Safely\n\nWhen you add a shortcut, keep the workflow centralized.\n\n1. define the shortcut in `config/keyboardShortcuts.ts`\n2. bind it through `useKeyboardShortcuts` in the feature component\n3. reuse the same definition for tooltip or help-surface labels\n4. test both the runtime behavior and the visible affordance\n\nTypical sequence:\n\n```typescript\nexport const PDF_SHORTCUTS = {\n  PRINT: {\n    id: \"print\",\n    keys: \"p\",\n    description: \"Print\",\n    label: \"Ctrl+P\",\n    ctrl: true,\n  },\n} as const;\n```\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...PDF_SHORTCUTS.PRINT,\n      handler: handlePrint,\n    },\n  ],\n});\n```\n\n```typescript\ntitle={withShortcut(PDF_SHORTCUTS.PRINT)}\n```\n\nDo not add one-off tooltip strings or imperative event parsing when the shortcut belongs in the shared system.\n\n## Label Formatting Rules\n\nThe shortcut system also owns display formatting.\n\n- `ArrowRight` becomes `Right`\n- `ArrowLeft` becomes `Left`\n- `ArrowUp` becomes `Up`\n- `ArrowDown` becomes `Down`\n- `Escape` becomes `Esc`\n- space becomes `Space`\n- multiple equivalent keys are joined with ` / `\n- modifiers render as `Ctrl+`, `Shift+`, and `Alt+`\n\nThat formatting should come from the shared system, not from ad hoc component strings.\n\n## Common Failure Modes\n\n- shortcut keys and visible labels drift apart\n- a component registers imperative keyboard logic instead of using the shared hook\n- the browser command palette exposes actions that do not respect the current UI context\n- shortcuts fire while text input or dialog state should block them\n- quick-bar focus returns to the wrong pane in dual-pane workflows\n- multiple overlapping handlers compete for one key instead of using a context-aware handler\n\n## Validation Expectations\n\nWhen keyboard behavior changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change affects file-browser behavior, also test:\n\n- quick-bar navigation and command mode\n- pane switching in dual-pane and single-pane layouts\n- dialog safety for destructive shortcuts\n- viewer shortcut labels and matching runtime behavior\n\nFor new shortcut registrations, also verify:\n\n- the shared label matches the actual bound keys\n- `allowInInput` behavior matches the intended text-entry experience\n- priority and enabled-state logic do not create hidden overlaps\n\n## Where to Continue\n\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL sync, selection, and refresh behavior\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): viewer reuse, preview behavior, and file-type contracts\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): other shared frontend systems contributors should keep centralized\n", "0.9": "+++\ntitle = \"Keyboard Shortcuts and Command Model\"\n+++\n\nKeyboard behavior in Sambee is a shared frontend system, not a pile of local `keydown` handlers.\n\nThe product depends on contributors keeping shortcuts, command labels, viewer controls, and file-browser focus behavior aligned.\n\n## Core Pieces\n\nThese files define the keyboard and command model:\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/config/keyboardShortcuts.ts` | single source of truth for shortcut definitions and display labels |\n| `frontend/src/config/browserCommands.ts` | file-browser command registry for command-palette behavior |\n| `frontend/src/hooks/useKeyboardShortcuts.ts` | shared hook that binds shortcut definitions to runtime handlers |\n| `frontend/src/pages/FileBrowser.tsx` | registers browser-level shortcuts and routes command actions |\n| `frontend/src/components/Viewer/` | consumes shared shortcut definitions for viewer behavior and tooltip labels |\n\nThe system is intentionally split so shortcuts stay declarative while feature surfaces keep control of their own runtime behavior.\n\n## Why the Registry Exists\n\nBefore the centralized model, shortcut keys, tooltip labels, and component handlers drifted apart easily.\n\nThe current approach preserves these rules:\n\n- define shortcut keys and display intent once\n- reuse the same definition across viewers and file-browser surfaces\n- let components supply handlers without redefining labels and modifiers\n- keep file-browser actions discoverable even when users do not know the shortcut\n\n## Shortcut Definition Model\n\nShortcut definitions are grouped by scope, such as common viewer actions, PDF-specific actions, image-viewer actions, or browser actions.\n\nRepresentative structure:\n\n```typescript\nexport const COMMON_SHORTCUTS = {\n  CLOSE: {\n    id: \"close\",\n    keys: \"Escape\",\n    description: \"Close\",\n    label: \"Esc\",\n    allowInInput: true,\n  },\n  DOWNLOAD: {\n    id: \"download\",\n    keys: \"s\",\n    description: \"Download\",\n    label: \"Ctrl+S\",\n    ctrl: true,\n  },\n} as const;\n```\n\nCommon properties include:\n\n- `id`: stable identifier\n- `keys`: one key or multiple equivalent keys\n- `description`: human-readable intent\n- `label`: optional display label; if omitted, it can be generated from the config\n- `ctrl`, `shift`, `alt`: required modifiers\n- `allowInInput`: whether the shortcut still works while an input is focused\n- `priority`: ordering for overlapping shortcut candidates\n\n## Using the Shared Hook\n\nFeature components bind runtime behavior through `useKeyboardShortcuts` instead of duplicating event parsing logic.\n\nTypical usage:\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...COMMON_SHORTCUTS.CLOSE,\n      handler: onClose,\n    },\n    {\n      ...COMMON_SHORTCUTS.DOWNLOAD,\n      handler: handleDownload,\n    },\n    {\n      ...PDF_SHORTCUTS.SEARCH,\n      handler: handleOpenSearch,\n    },\n  ],\n});\n```\n\nThat split keeps the registry declarative and keeps feature logic in the feature component.\n\n## Labels and Tooltip Reuse\n\nViewer controls and similar UI surfaces should reuse the same shortcut definition instead of duplicating string formatting.\n\nThe shared formatter can turn a shortcut definition into a tooltip label such as `Download (Ctrl+S)`.\n\nThat matters because a changed shortcut should update viewer behavior and visible affordances together.\n\n## Browser Commands Versus Raw Shortcuts\n\nThe file browser uses both shortcut definitions and a command registry.\n\n- shortcut definitions remain centralized in `keyboardShortcuts.ts`\n- discoverable browser actions live in `browserCommands.ts`\n- command definitions point back to shortcut identifiers when a keyboard binding exists\n\nThis lets Sambee expose browser actions through the quick bar even when the user does not know the shortcut.\n\nEach browser command definition includes concepts such as:\n\n- a stable `id`\n- a user-facing `title`\n- a `category` for command grouping\n- linked shortcut identifiers\n- `isEnabled(context)` for context-aware availability\n- `run(context)` for execution\n- `selectionFocusTarget` for post-selection focus behavior\n\n## Quick-Bar Modes\n\nThe file browser quick bar is not just a text filter. It supports multiple modes with different intent.\n\n- `Ctrl+K`: open the smart navigation surface\n- `Ctrl+Alt+F`: open pane-local current-directory filter mode\n- `Ctrl+P` or `F1`: open command mode directly\n- typing `\u003e` as the first character switches the quick bar into command mode\n\nSmart navigation and command mode are dropdown-backed provider modes. Filter mode deliberately is not.\n\n- `smart` mode uses the search provider composition that merges directory navigation and command escape-hatch behavior\n- `commands` mode uses the browser command registry directly\n- `filter` mode uses the same input shell, but as a controlled pane-local filter box with dropdown rendering disabled\n\nThe quick bar captures the pane that opened it. In dual-pane mode, the active quick-bar pane stays fixed even if the other pane becomes active before selection.\n\nThat capture rule matters especially for filter mode, because the filter text belongs to the pane state, not to the shared quick-bar component.\n\n### Current-Directory Filter Mode\n\n`Ctrl+Alt+F` is now a real current-directory filter workflow, not a smart-navigation alias.\n\nThe implemented contract is:\n\n- the active pane opens the quick bar in `filter` mode\n- the quick bar shows that pane's `currentDirectoryFilter` as a controlled value\n- typing filters the pane's visible file list immediately\n- no dropdown results are shown in this mode\n- `ArrowDown` hands focus from the input into the pane's file list\n- `Escape` clears the filter first, then returns focus to the file list when the input is already empty\n\nThe filter state is pane-local and scoped to the current `connectionId + path`.\n\n- switching between `smart`, `commands`, and `filter` modes does not clear the current directory filter\n- navigating to a different directory clears the filter for the new scope\n- changing the pane's connection also clears the filter for the new scope\n- the status bar remains the persistent reminder that a filter is active even when the quick bar is in another mode\n\n## Current Browser-Level Shortcuts\n\nCurrent browser-level shortcuts include:\n\n- `Ctrl+K`: open smart navigation\n- `Ctrl+Alt+F`: focus current-directory filter mode for the active pane\n- `Ctrl+P`: show commands\n- `F1`: alternate binding for show commands\n- `Ctrl+,`: open settings\n- `?`: show keyboard shortcuts help\n- `Backspace`: go up one directory\n- `Ctrl+R`: refresh file list\n- `F2`: rename focused item\n- `Delete`: delete focused item\n- `F7`: create new directory\n- `Shift+F7`: create new file\n- `Ctrl+Enter`: open focused file in the companion app\n- `Ctrl+B`: toggle dual-pane view\n- `Ctrl+1`: focus left pane\n- `Ctrl+2`: focus right pane\n- `Tab`: switch active pane\n- `F5`: copy to the other pane\n- `F6`: move to the other pane\n\nWhen changing these, treat the behavior as product-level interaction design rather than local implementation detail.\n\n## Focus and Interaction Rules\n\nShortcut work often breaks focus behavior before it breaks functionality. Keep these rules intact:\n\n- opening the quick bar focuses its input immediately\n- selecting a navigation result returns focus to the relevant file list\n- selecting commands that switch quick-bar modes keeps focus inside the quick bar\n- `ArrowDown` from current-directory filter mode moves focus into the filtered file list\n- current-directory filter mode does not open a dropdown for local matches\n- `Escape` in filter mode clears the active filter before it hands focus back to the file list\n- commands that open dialogs or settings do not force focus back to the file list\n- pane-switching shortcuts do not fire while the quick-bar input is focused\n- shortcuts that should work during text entry must explicitly opt in with `allowInInput`\n- shortcuts should be disabled when dialog state or viewer state would make them unsafe\n\n## Context-Aware Shortcut Handling\n\nWhen one key needs different behavior depending on state, prefer one context-aware handler over overlapping registrations.\n\nFor example, `Escape` may close a search panel when that panel is open, but close the viewer when it is not.\n\nThat pattern is better than registering multiple conflicting `Escape` shortcuts because:\n\n- one shortcut definition stays authoritative\n- behavior remains explicit in the component state logic\n- conflicts are easier to reason about and test\n\n### Priority as an Escape Hatch\n\nIn rare cases, multiple handlers for one key are unavoidable. The system supports a `priority` field so higher-priority candidates are evaluated first.\n\nUse that sparingly. A context-aware handler is usually easier to understand and maintain than several competing registrations.\n\n## Adding New Shortcuts Safely\n\nWhen you add a shortcut, keep the workflow centralized.\n\n1. define the shortcut in `config/keyboardShortcuts.ts`\n2. bind it through `useKeyboardShortcuts` in the feature component\n3. reuse the same definition for tooltip or help-surface labels\n4. test both the runtime behavior and the visible affordance\n\nTypical sequence:\n\n```typescript\nexport const PDF_SHORTCUTS = {\n  PRINT: {\n    id: \"print\",\n    keys: \"p\",\n    description: \"Print\",\n    label: \"Ctrl+P\",\n    ctrl: true,\n  },\n} as const;\n```\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...PDF_SHORTCUTS.PRINT,\n      handler: handlePrint,\n    },\n  ],\n});\n```\n\n```typescript\ntitle={withShortcut(PDF_SHORTCUTS.PRINT)}\n```\n\nDo not add one-off tooltip strings or imperative event parsing when the shortcut belongs in the shared system.\n\n## Label Formatting Rules\n\nThe shortcut system also owns display formatting.\n\n- `ArrowRight` becomes `Right`\n- `ArrowLeft` becomes `Left`\n- `ArrowUp` becomes `Up`\n- `ArrowDown` becomes `Down`\n- `Escape` becomes `Esc`\n- space becomes `Space`\n- multiple equivalent keys are joined with ` / `\n- modifiers render as `Ctrl+`, `Shift+`, and `Alt+`\n\nThat formatting should come from the shared system, not from ad hoc component strings.\n\n## Common Failure Modes\n\n- shortcut keys and visible labels drift apart\n- a component registers imperative keyboard logic instead of using the shared hook\n- the browser command palette exposes actions that do not respect the current UI context\n- shortcuts fire while text input or dialog state should block them\n- quick-bar focus returns to the wrong pane in dual-pane workflows\n- multiple overlapping handlers compete for one key instead of using a context-aware handler\n\n## Validation Expectations\n\nWhen keyboard behavior changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change affects file-browser behavior, also test:\n\n- quick-bar navigation and command mode\n- pane switching in dual-pane and single-pane layouts\n- dialog safety for destructive shortcuts\n- viewer shortcut labels and matching runtime behavior\n\nFor new shortcut registrations, also verify:\n\n- the shared label matches the actual bound keys\n- `allowInInput` behavior matches the intended text-entry experience\n- priority and enabled-state logic do not create hidden overlaps\n\n## Where to Continue\n\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL sync, selection, and refresh behavior\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): viewer reuse, preview behavior, and file-type contracts\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): other shared frontend systems contributors should keep centralized\n", "1.0": "+++\ntitle = \"Keyboard Shortcuts and Command Model\"\n+++\n\nKeyboard behavior in Sambee is a shared frontend system, not a pile of local `keydown` handlers.\n\nThe product depends on contributors keeping shortcuts, command labels, viewer controls, and file-browser focus behavior aligned.\n\n## Core Pieces\n\nThese files define the keyboard and command model:\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/config/keyboardShortcuts.ts` | single source of truth for shortcut definitions and display labels |\n| `frontend/src/config/browserCommands.ts` | file-browser command registry for command-palette behavior |\n| `frontend/src/hooks/useKeyboardShortcuts.ts` | shared hook that binds shortcut definitions to runtime handlers |\n| `frontend/src/pages/FileBrowser.tsx` | registers browser-level shortcuts and routes command actions |\n| `frontend/src/components/Viewer/` | consumes shared shortcut definitions for viewer behavior and tooltip labels |\n| `frontend/src/components/Viewer/CodeMirrorFindReplacePopover.tsx` | shared compact find, match-option, and replacement controls for CodeMirror editors |\n\nThe system is intentionally split so shortcuts stay declarative while feature surfaces keep control of their own runtime behavior.\n\n## Why the Registry Exists\n\nBefore the centralized model, shortcut keys, tooltip labels, and component handlers drifted apart easily.\n\nThe current approach preserves these rules:\n\n- define shortcut keys and display intent once\n- reuse the same definition across viewers and file-browser surfaces\n- let components supply handlers without redefining labels and modifiers\n- keep file-browser actions discoverable even when users do not know the shortcut\n\n## Shortcut Definition Model\n\nShortcut definitions are grouped by scope, such as common viewer actions, PDF-specific actions, image-viewer actions, or browser actions.\n\nRepresentative structure:\n\n```typescript\nexport const COMMON_SHORTCUTS = {\n  CLOSE: {\n    id: \"close\",\n    keys: \"Escape\",\n    description: \"Close\",\n    label: \"Esc\",\n    allowInInput: true,\n  },\n  DOWNLOAD: {\n    id: \"download\",\n    keys: \"s\",\n    description: \"Download\",\n    label: \"Ctrl+S\",\n    ctrl: true,\n  },\n} as const;\n```\n\nCommon properties include:\n\n- `id`: stable identifier\n- `keys`: one key or multiple equivalent keys\n- `description`: human-readable intent\n- `label`: optional display label; if omitted, it can be generated from the config\n- `ctrl`, `shift`, `alt`: required modifiers\n- `allowInInput`: whether the shortcut still works while an input is focused\n- `priority`: ordering for overlapping shortcut candidates\n\n## Using the Shared Hook\n\nFeature components bind runtime behavior through `useKeyboardShortcuts` instead of duplicating event parsing logic.\n\nTypical usage:\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...COMMON_SHORTCUTS.CLOSE,\n      handler: onClose,\n    },\n    {\n      ...COMMON_SHORTCUTS.DOWNLOAD,\n      handler: handleDownload,\n    },\n    {\n      ...PDF_SHORTCUTS.SEARCH,\n      handler: handleOpenSearch,\n    },\n  ],\n});\n```\n\nThat split keeps the registry declarative and keeps feature logic in the feature component.\n\n## Labels and Tooltip Reuse\n\nViewer controls and similar UI surfaces should reuse the same shortcut definition instead of duplicating string formatting.\n\nThe shared formatter can turn a shortcut definition into a tooltip label such as `Download (Ctrl+S)`.\n\nThat matters because a changed shortcut should update viewer behavior and visible affordances together.\n\n## Browser Commands Versus Raw Shortcuts\n\nThe file browser uses both shortcut definitions and a command registry.\n\n- shortcut definitions remain centralized in `keyboardShortcuts.ts`\n- discoverable browser actions live in `browserCommands.ts`\n- command definitions point back to shortcut identifiers when a keyboard binding exists\n\nThis lets Sambee expose browser actions through the quick bar even when the user does not know the shortcut.\n\nEach browser command definition includes concepts such as:\n\n- a stable `id`\n- a user-facing `title`\n- a `category` for command grouping\n- linked shortcut identifiers\n- `isEnabled(context)` for context-aware availability\n- `run(context)` for execution\n- `selectionFocusTarget` for post-selection focus behavior\n\n## Quick-Bar Modes\n\nThe file browser quick bar is not just a text filter. It supports multiple modes with different intent.\n\n- `Ctrl+K`: open the smart navigation surface\n- `Ctrl+Alt+F`: open pane-local current-directory filter mode\n- `Ctrl+P`: open command mode directly\n- typing `\u003e` as the first character switches the quick bar into command mode\n\nSmart navigation and command mode are dropdown-backed provider modes. Filter mode deliberately is not.\n\n- `smart` mode uses the search provider composition that merges directory navigation and command escape-hatch behavior\n- `commands` mode uses the browser command registry directly\n- `filter` mode uses the same input shell, but as a controlled pane-local filter box with dropdown rendering disabled\n\nThe quick bar captures the pane that opened it. In dual-pane mode, the active quick-bar pane stays fixed even if the other pane becomes active before selection.\n\nThat capture rule matters especially for filter mode, because the filter text belongs to the pane state, not to the shared quick-bar component.\n\n### Current-Directory Filter Mode\n\n`Ctrl+Alt+F` is now a real current-directory filter workflow, not a smart-navigation alias.\n\nThe implemented contract is:\n\n- the active pane opens the quick bar in `filter` mode\n- the quick bar shows that pane's `currentDirectoryFilter` as a controlled value\n- typing filters the pane's visible file list immediately\n- no dropdown results are shown in this mode\n- `ArrowDown` hands focus from the input into the pane's file list\n- `Escape` clears the filter first, then returns focus to the file list when the input is already empty\n\nThe filter state is pane-local and scoped to the current `connectionId + path`.\n\n- switching between `smart`, `commands`, and `filter` modes does not clear the current directory filter\n- navigating to a different directory clears the filter for the new scope\n- changing the pane's connection also clears the filter for the new scope\n- the status bar remains the persistent reminder that a filter is active even when the quick bar is in another mode\n\n## Current Browser-Level Shortcuts\n\nCurrent browser-level shortcuts include:\n\n- `Ctrl+K`: open smart navigation\n- `Ctrl+Alt+F`: focus current-directory filter mode for the active pane\n- `Ctrl+P`: show commands\n- `Ctrl+,`: open settings\n- `?` or `F1`: show keyboard shortcuts help\n- `Backspace`: go up one directory\n- `Ctrl+R`: refresh file list\n- `F2`: rename focused item\n- `Delete`: delete focused item\n- `F7`: create new directory\n- `Shift+F7`: create new file\n- `Ctrl+Enter`: open focused file in the companion app\n- `Ctrl+B`: toggle dual-pane view\n- `Ctrl+1`: focus left pane\n- `Ctrl+2`: focus right pane\n- `Tab`: switch active pane\n- `F5`: copy to the other pane\n- `F6`: move to the other pane\n\nWhen changing these, treat the behavior as product-level interaction design rather than local implementation detail.\n\n## Focus and Interaction Rules\n\nShortcut work often breaks focus behavior before it breaks functionality. Keep these rules intact:\n\n- opening the quick bar focuses its input immediately\n- selecting a navigation result returns focus to the relevant file list\n- selecting commands that switch quick-bar modes keeps focus inside the quick bar\n- `ArrowDown` from current-directory filter mode moves focus into the filtered file list\n- current-directory filter mode does not open a dropdown for local matches\n- `Escape` in filter mode clears the active filter before it hands focus back to the file list\n- commands that open dialogs or settings do not force focus back to the file list\n- pane-switching shortcuts do not fire while the quick-bar input is focused\n- shortcuts that should work during text entry must explicitly opt in with `allowInInput`\n- shortcuts should be disabled when dialog state or viewer state would make them unsafe\n\n## Context-Aware Shortcut Handling\n\nWhen one key needs different behavior depending on state, prefer one context-aware handler over overlapping registrations.\n\nFor example, `Escape` may close a search panel when that panel is open, but close the viewer when it is not.\n\nThat pattern is better than registering multiple conflicting `Escape` shortcuts because:\n\n- one shortcut definition stays authoritative\n- behavior remains explicit in the component state logic\n- conflicts are easier to reason about and test\n\n### Priority as an Escape Hatch\n\nIn rare cases, multiple handlers for one key are unavoidable. The system supports a `priority` field so higher-priority candidates are evaluated first.\n\nUse that sparingly. A context-aware handler is usually easier to understand and maintain than several competing registrations.\n\n## Adding New Shortcuts Safely\n\nWhen you add a shortcut, keep the workflow centralized.\n\n1. define the shortcut in `config/keyboardShortcuts.ts`\n1. bind it through `useKeyboardShortcuts` in the feature component\n1. reuse the same definition for tooltip or help-surface labels\n1. test both the runtime behavior and the visible affordance\n\nTypical sequence:\n\n```typescript\nexport const PDF_SHORTCUTS = {\n  PRINT: {\n    id: \"print\",\n    keys: \"p\",\n    description: \"Print\",\n    label: \"Ctrl+P\",\n    ctrl: true,\n  },\n} as const;\n```\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...PDF_SHORTCUTS.PRINT,\n      handler: handlePrint,\n    },\n  ],\n});\n```\n\n```typescript\ntitle={withShortcut(PDF_SHORTCUTS.PRINT)}\n```\n\nDo not add one-off tooltip strings or imperative event parsing when the shortcut belongs in the shared system.\n\n## CodeMirror Find and Replace\n\nMarkdown and text editing keep find and replace in an editor-local fixed surface near the upper-right viewport edge, below the viewer toolbar, rather than in the shared viewer toolbar. `MarkdownViewer` and `TextViewer` own the surrounding viewer state and bind `Ctrl+H`, `Alt+C`, `Alt+W`, and `Alt+R` through `CODEMIRROR_EDITOR_SHORTCUTS`. The existing shared `F3` and `Shift+F3` registrations remain the navigation authority, including while a find or replace input has focus. `Enter` and `Ctrl+Alt+Enter` are also declared in that registry for replace-current and replace-all, but their `allowInInputWithin` scope limits them to the replacement field.\n\n`codeMirrorFindReplace.ts` owns the shared `SearchQuery` construction, validity-aware metrics, and auto-navigation logic. `MarkdownRichEditor` and `TextCodeEditor` map the controlled state to that API and use CodeMirror's native `replaceNext` and `replaceAll` commands. Keep replacement operations on those native commands so CodeMirror owns selection updates and undo transactions. Search metrics must check the query validity before creating a cursor because an invalid regular expression cannot produce one.\n\n`CodeMirrorFindReplacePopover` is intentionally non-modal so the editor remains visible and keyboard navigation remains continuous. Its Find and Replace inputs come first in DOM order to preserve the first two tab stops. The history affordance is supplied by the in-field `Search (\u21c5 for history)` and `Replace (\u21c5 for history)` placeholders; result count, match options, navigation, and close controls occupy the first row to the inputs' right. `codeMirrorFindReplaceHistory.ts` persists independent Find and Replace histories in local storage, safely tolerating unavailable or malformed storage and retaining only the ten newest unique non-empty values. Reuse dialog surface tokens for its paper, but do not use `ResponsiveFormDialog`: full-screen viewers retain their specialized focus and layout shell.\n\n## Label Formatting Rules\n\nThe shortcut system also owns display formatting.\n\n- `ArrowRight` becomes `Right`\n- `ArrowLeft` becomes `Left`\n- `ArrowUp` becomes `Up`\n- `ArrowDown` becomes `Down`\n- `Escape` becomes `Esc`\n- space becomes `Space`\n- multiple equivalent keys are joined with ` / `\n- modifiers render as `Ctrl+`, `Shift+`, and `Alt+`\n\nThat formatting should come from the shared system, not from ad hoc component strings.\n\n## Common Failure Modes\n\n- shortcut keys and visible labels drift apart\n- a component registers imperative keyboard logic instead of using the shared hook\n- the browser command palette exposes actions that do not respect the current UI context\n- shortcuts fire while text input or dialog state should block them\n- quick-bar focus returns to the wrong pane in dual-pane workflows\n- multiple overlapping handlers compete for one key instead of using a context-aware handler\n\n## Validation Expectations\n\nWhen keyboard behavior changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change affects file-browser behavior, also test:\n\n- quick-bar navigation and command mode\n- pane switching in dual-pane and single-pane layouts\n- dialog safety for destructive shortcuts\n- viewer shortcut labels and matching runtime behavior\n\nFor new shortcut registrations, also verify:\n\n- the shared label matches the actual bound keys\n- `allowInInput` behavior matches the intended text-entry experience\n- priority and enabled-state logic do not create hidden overlaps\n\n## Where to Continue\n\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL sync, selection, and refresh behavior\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): viewer reuse, preview behavior, and file-type contracts\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): other shared frontend systems contributors should keep centralized\n", "2.0": "+++\ntitle = \"Keyboard Shortcuts and Command Model\"\n+++\n\nKeyboard behavior in Sambee is a shared frontend system, not a pile of local `keydown` handlers.\n\nThe product depends on contributors keeping shortcuts, command labels, viewer controls, and file-browser focus behavior aligned.\n\n## Core Pieces\n\nThese files define the keyboard and command model:\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/config/keyboardShortcuts.ts` | single source of truth for shortcut definitions and display labels |\n| `frontend/src/config/browserCommands.ts` | file-browser command registry for command-palette behavior |\n| `frontend/src/hooks/useKeyboardShortcuts.ts` | shared hook that binds shortcut definitions to runtime handlers |\n| `frontend/src/pages/FileBrowser.tsx` | registers browser-level shortcuts and routes command actions |\n| `frontend/src/components/Viewer/` | consumes shared shortcut definitions for viewer behavior and tooltip labels |\n| `frontend/src/components/Viewer/CodeMirrorFindReplacePopover.tsx` | shared compact find, match-option, and replacement controls for CodeMirror editors |\n\nThe system is intentionally split so shortcuts stay declarative while feature surfaces keep control of their own runtime behavior.\n\n## Why the Registry Exists\n\nBefore the centralized model, shortcut keys, tooltip labels, and component handlers drifted apart easily.\n\nThe current approach preserves these rules:\n\n- define shortcut keys and display intent once\n- reuse the same definition across viewers and file-browser surfaces\n- let components supply handlers without redefining labels and modifiers\n- keep file-browser actions discoverable even when users do not know the shortcut\n\n## Shortcut Definition Model\n\nShortcut definitions are grouped by scope, such as common viewer actions, PDF-specific actions, image-viewer actions, or browser actions.\n\nRepresentative structure:\n\n```typescript\nexport const COMMON_SHORTCUTS = {\n  CLOSE: {\n    id: \"close\",\n    keys: \"Escape\",\n    description: \"Close\",\n    label: \"Esc\",\n    allowInInput: true,\n  },\n  DOWNLOAD: {\n    id: \"download\",\n    keys: \"s\",\n    description: \"Download\",\n    label: \"Ctrl+S\",\n    ctrl: true,\n  },\n} as const;\n```\n\nCommon properties include:\n\n- `id`: stable identifier\n- `keys`: one key or multiple equivalent keys\n- `description`: human-readable intent\n- `label`: optional display label; if omitted, it can be generated from the config\n- `ctrl`, `shift`, `alt`: required modifiers\n- `allowInInput`: whether the shortcut still works while an input is focused\n- `priority`: ordering for overlapping shortcut candidates\n\n## Using the Shared Hook\n\nFeature components bind runtime behavior through `useKeyboardShortcuts` instead of duplicating event parsing logic.\n\nTypical usage:\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...COMMON_SHORTCUTS.CLOSE,\n      handler: onClose,\n    },\n    {\n      ...COMMON_SHORTCUTS.DOWNLOAD,\n      handler: handleDownload,\n    },\n    {\n      ...PDF_SHORTCUTS.SEARCH,\n      handler: handleOpenSearch,\n    },\n  ],\n});\n```\n\nThat split keeps the registry declarative and keeps feature logic in the feature component.\n\n## Labels and Tooltip Reuse\n\nViewer controls and similar UI surfaces should reuse the same shortcut definition instead of duplicating string formatting.\n\nThe shared formatter can turn a shortcut definition into a tooltip label such as `Download (Ctrl+S)`.\n\nThat matters because a changed shortcut should update viewer behavior and visible affordances together.\n\n## Browser Commands Versus Raw Shortcuts\n\nThe file browser uses both shortcut definitions and a command registry.\n\n- shortcut definitions remain centralized in `keyboardShortcuts.ts`\n- discoverable browser actions live in `browserCommands.ts`\n- command definitions point back to shortcut identifiers when a keyboard binding exists\n\nThis lets Sambee expose browser actions through the quick bar even when the user does not know the shortcut.\n\nEach browser command definition includes concepts such as:\n\n- a stable `id`\n- a user-facing `title`\n- a `category` for command grouping\n- linked shortcut identifiers\n- `isEnabled(context)` for context-aware availability\n- `run(context)` for execution\n- `selectionFocusTarget` for post-selection focus behavior\n\n## Quick-Bar Modes\n\nThe file browser quick bar is not just a text filter. It supports multiple modes with different intent.\n\n- `Ctrl+K`: open the smart navigation surface\n- `Ctrl+Alt+F`: open pane-local current-directory filter mode\n- `Ctrl+P`: open command mode directly\n- typing `\u003e` as the first character switches the quick bar into command mode\n\nSmart navigation and command mode are dropdown-backed provider modes. Filter mode deliberately is not.\n\n- `smart` mode uses the search provider composition that merges directory navigation and command escape-hatch behavior\n- `commands` mode uses the browser command registry directly\n- `filter` mode uses the same input shell, but as a controlled pane-local filter box with dropdown rendering disabled\n\nThe quick bar captures the pane that opened it. In dual-pane mode, the active quick-bar pane stays fixed even if the other pane becomes active before selection.\n\nThat capture rule matters especially for filter mode, because the filter text belongs to the pane state, not to the shared quick-bar component.\n\n### Current-Directory Filter Mode\n\n`Ctrl+Alt+F` is now a real current-directory filter workflow, not a smart-navigation alias.\n\nThe implemented contract is:\n\n- the active pane opens the quick bar in `filter` mode\n- the quick bar shows that pane's `currentDirectoryFilter` as a controlled value\n- typing filters the pane's visible file list immediately\n- no dropdown results are shown in this mode\n- `ArrowDown` hands focus from the input into the pane's file list\n- `Escape` clears the filter first, then returns focus to the file list when the input is already empty\n\nThe filter state is pane-local and scoped to the current `connectionId + path`.\n\n- switching between `smart`, `commands`, and `filter` modes does not clear the current directory filter\n- navigating to a different directory clears the filter for the new scope\n- changing the pane's connection also clears the filter for the new scope\n- the status bar remains the persistent reminder that a filter is active even when the quick bar is in another mode\n\n## Current Browser-Level Shortcuts\n\nCurrent browser-level shortcuts include:\n\n- `Ctrl+K`: open smart navigation\n- `Ctrl+Alt+F`: focus current-directory filter mode for the active pane\n- `Ctrl+P`: show commands\n- `Ctrl+,`: open settings\n- `?` or `F1`: show keyboard shortcuts help\n- `Backspace`: go up one directory\n- `Ctrl+R`: refresh file list\n- `F2`: rename focused item\n- `Delete`: delete focused item\n- `F7`: create new directory\n- `Shift+F7`: create new file\n- `Ctrl+Enter`: open focused file in the companion app\n- `Ctrl+B`: toggle dual-pane view\n- `Ctrl+1`: focus left pane\n- `Ctrl+2`: focus right pane\n- `Tab`: switch active pane\n- `F5`: copy to the other pane\n- `F6`: move to the other pane\n\nWhen changing these, treat the behavior as product-level interaction design rather than local implementation detail.\n\n## Focus and Interaction Rules\n\nShortcut work often breaks focus behavior before it breaks functionality. Keep these rules intact:\n\n- opening the quick bar focuses its input immediately\n- selecting a navigation result returns focus to the relevant file list\n- selecting commands that switch quick-bar modes keeps focus inside the quick bar\n- `ArrowDown` from current-directory filter mode moves focus into the filtered file list\n- current-directory filter mode does not open a dropdown for local matches\n- `Escape` in filter mode clears the active filter before it hands focus back to the file list\n- commands that open dialogs or settings do not force focus back to the file list\n- pane-switching shortcuts do not fire while the quick-bar input is focused\n- shortcuts that should work during text entry must explicitly opt in with `allowInInput`\n- shortcuts should be disabled when dialog state or viewer state would make them unsafe\n\n## Context-Aware Shortcut Handling\n\nWhen one key needs different behavior depending on state, prefer one context-aware handler over overlapping registrations.\n\nFor example, `Escape` may close a search panel when that panel is open, but close the viewer when it is not.\n\nThat pattern is better than registering multiple conflicting `Escape` shortcuts because:\n\n- one shortcut definition stays authoritative\n- behavior remains explicit in the component state logic\n- conflicts are easier to reason about and test\n\n### Priority as an Escape Hatch\n\nIn rare cases, multiple handlers for one key are unavoidable. The system supports a `priority` field so higher-priority candidates are evaluated first.\n\nUse that sparingly. A context-aware handler is usually easier to understand and maintain than several competing registrations.\n\n## Adding New Shortcuts Safely\n\nWhen you add a shortcut, keep the workflow centralized.\n\n1. define the shortcut in `config/keyboardShortcuts.ts`\n1. bind it through `useKeyboardShortcuts` in the feature component\n1. reuse the same definition for tooltip or help-surface labels\n1. test both the runtime behavior and the visible affordance\n\nTypical sequence:\n\n```typescript\nexport const PDF_SHORTCUTS = {\n  PRINT: {\n    id: \"print\",\n    keys: \"p\",\n    description: \"Print\",\n    label: \"Ctrl+P\",\n    ctrl: true,\n  },\n} as const;\n```\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...PDF_SHORTCUTS.PRINT,\n      handler: handlePrint,\n    },\n  ],\n});\n```\n\n```typescript\ntitle={withShortcut(PDF_SHORTCUTS.PRINT)}\n```\n\nDo not add one-off tooltip strings or imperative event parsing when the shortcut belongs in the shared system.\n\n## CodeMirror Find and Replace\n\nMarkdown and text editing keep find and replace in an editor-local fixed surface near the upper-right viewport edge, below the viewer toolbar, rather than in the shared viewer toolbar. `MarkdownViewer` and `TextViewer` own the surrounding viewer state and bind `Ctrl+H`, `Alt+C`, `Alt+W`, and `Alt+R` through `CODEMIRROR_EDITOR_SHORTCUTS`. The existing shared `F3` and `Shift+F3` registrations remain the navigation authority, including while a find or replace input has focus. `Enter` and `Ctrl+Alt+Enter` are also declared in that registry for replace-current and replace-all, but their `allowInInputWithin` scope limits them to the replacement field.\n\n`codeMirrorFindReplace.ts` owns the shared `SearchQuery` construction, validity-aware metrics, and auto-navigation logic. `MarkdownRichEditor` and `TextCodeEditor` map the controlled state to that API and use CodeMirror's native `replaceNext` and `replaceAll` commands. Keep replacement operations on those native commands so CodeMirror owns selection updates and undo transactions. Search metrics must check the query validity before creating a cursor because an invalid regular expression cannot produce one.\n\n`CodeMirrorFindReplacePopover` is intentionally non-modal so the editor remains visible and keyboard navigation remains continuous. Its Find and Replace inputs come first in DOM order to preserve the first two tab stops. The history affordance is supplied by the in-field `Search (\u21c5 for history)` and `Replace (\u21c5 for history)` placeholders; result count, match options, navigation, and close controls occupy the first row to the inputs' right. `codeMirrorFindReplaceHistory.ts` persists independent Find and Replace histories in local storage, safely tolerating unavailable or malformed storage and retaining only the ten newest unique non-empty values. Reuse dialog surface tokens for its paper, but do not use `ResponsiveFormDialog`: full-screen viewers retain their specialized focus and layout shell.\n\n## Label Formatting Rules\n\nThe shortcut system also owns display formatting.\n\n- `ArrowRight` becomes `Right`\n- `ArrowLeft` becomes `Left`\n- `ArrowUp` becomes `Up`\n- `ArrowDown` becomes `Down`\n- `Escape` becomes `Esc`\n- space becomes `Space`\n- multiple equivalent keys are joined with ` / `\n- modifiers render as `Ctrl+`, `Shift+`, and `Alt+`\n\nThat formatting should come from the shared system, not from ad hoc component strings.\n\n## Common Failure Modes\n\n- shortcut keys and visible labels drift apart\n- a component registers imperative keyboard logic instead of using the shared hook\n- the browser command palette exposes actions that do not respect the current UI context\n- shortcuts fire while text input or dialog state should block them\n- quick-bar focus returns to the wrong pane in dual-pane workflows\n- multiple overlapping handlers compete for one key instead of using a context-aware handler\n\n## Validation Expectations\n\nWhen keyboard behavior changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change affects file-browser behavior, also test:\n\n- quick-bar navigation and command mode\n- pane switching in dual-pane and single-pane layouts\n- dialog safety for destructive shortcuts\n- viewer shortcut labels and matching runtime behavior\n\nFor new shortcut registrations, also verify:\n\n- the shared label matches the actual bound keys\n- `allowInInput` behavior matches the intended text-entry experience\n- priority and enabled-state logic do not create hidden overlaps\n\n## Where to Continue\n\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL sync, selection, and refresh behavior\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): viewer reuse, preview behavior, and file-type contracts\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): other shared frontend systems contributors should keep centralized\n"}, "page_contents": {"0.7": "+++\ntitle = \"Keyboard Shortcuts and Command Model\"\n+++\n\nKeyboard behavior in Sambee is a shared frontend system, not a pile of local `keydown` handlers.\n\nThe product depends on contributors keeping shortcuts, command labels, viewer controls, and file-browser focus behavior aligned.\n\n## Core Pieces\n\nThese files define the keyboard and command model:\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/config/keyboardShortcuts.ts` | single source of truth for shortcut definitions and display labels |\n| `frontend/src/config/browserCommands.ts` | file-browser command registry for command-palette behavior |\n| `frontend/src/hooks/useKeyboardShortcuts.ts` | shared hook that binds shortcut definitions to runtime handlers |\n| `frontend/src/pages/FileBrowser.tsx` | registers browser-level shortcuts and routes command actions |\n| `frontend/src/components/Viewer/` | consumes shared shortcut definitions for viewer behavior and tooltip labels |\n\nThe system is intentionally split so shortcuts stay declarative while feature surfaces keep control of their own runtime behavior.\n\n## Why the Registry Exists\n\nBefore the centralized model, shortcut keys, tooltip labels, and component handlers drifted apart easily.\n\nThe current approach preserves these rules:\n\n- define shortcut keys and display intent once\n- reuse the same definition across viewers and file-browser surfaces\n- let components supply handlers without redefining labels and modifiers\n- keep file-browser actions discoverable even when users do not know the shortcut\n\n## Shortcut Definition Model\n\nShortcut definitions are grouped by scope, such as common viewer actions, PDF-specific actions, image-viewer actions, or browser actions.\n\nRepresentative structure:\n\n```typescript\nexport const COMMON_SHORTCUTS = {\n  CLOSE: {\n    id: \"close\",\n    keys: \"Escape\",\n    description: \"Close\",\n    label: \"Esc\",\n    allowInInput: true,\n  },\n  DOWNLOAD: {\n    id: \"download\",\n    keys: \"s\",\n    description: \"Download\",\n    label: \"Ctrl+S\",\n    ctrl: true,\n  },\n} as const;\n```\n\nCommon properties include:\n\n- `id`: stable identifier\n- `keys`: one key or multiple equivalent keys\n- `description`: human-readable intent\n- `label`: optional display label; if omitted, it can be generated from the config\n- `ctrl`, `shift`, `alt`: required modifiers\n- `allowInInput`: whether the shortcut still works while an input is focused\n- `priority`: ordering for overlapping shortcut candidates\n\n## Using the Shared Hook\n\nFeature components bind runtime behavior through `useKeyboardShortcuts` instead of duplicating event parsing logic.\n\nTypical usage:\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...COMMON_SHORTCUTS.CLOSE,\n      handler: onClose,\n    },\n    {\n      ...COMMON_SHORTCUTS.DOWNLOAD,\n      handler: handleDownload,\n    },\n    {\n      ...PDF_SHORTCUTS.SEARCH,\n      handler: handleOpenSearch,\n    },\n  ],\n});\n```\n\nThat split keeps the registry declarative and keeps feature logic in the feature component.\n\n## Labels and Tooltip Reuse\n\nViewer controls and similar UI surfaces should reuse the same shortcut definition instead of duplicating string formatting.\n\nThe shared formatter can turn a shortcut definition into a tooltip label such as `Download (Ctrl+S)`.\n\nThat matters because a changed shortcut should update viewer behavior and visible affordances together.\n\n## Browser Commands Versus Raw Shortcuts\n\nThe file browser uses both shortcut definitions and a command registry.\n\n- shortcut definitions remain centralized in `keyboardShortcuts.ts`\n- discoverable browser actions live in `browserCommands.ts`\n- command definitions point back to shortcut identifiers when a keyboard binding exists\n\nThis lets Sambee expose browser actions through the quick bar even when the user does not know the shortcut.\n\nEach browser command definition includes concepts such as:\n\n- a stable `id`\n- a user-facing `title`\n- a `category` for command grouping\n- linked shortcut identifiers\n- `isEnabled(context)` for context-aware availability\n- `run(context)` for execution\n- `selectionFocusTarget` for post-selection focus behavior\n\n## Quick-Bar Modes\n\nThe file browser quick bar is not just a text filter. It supports multiple modes with different intent.\n\n- `Ctrl+K`: open the smart navigation surface\n- `Ctrl+Alt+F`: open pane-local current-directory filter mode\n- `Ctrl+P` or `F1`: open command mode directly\n- typing `\u003e` as the first character switches the quick bar into command mode\n\nSmart navigation and command mode are dropdown-backed provider modes. Filter mode deliberately is not.\n\n- `smart` mode uses the search provider composition that merges directory navigation and command escape-hatch behavior\n- `commands` mode uses the browser command registry directly\n- `filter` mode uses the same input shell, but as a controlled pane-local filter box with dropdown rendering disabled\n\nThe quick bar captures the pane that opened it. In dual-pane mode, the active quick-bar pane stays fixed even if the other pane becomes active before selection.\n\nThat capture rule matters especially for filter mode, because the filter text belongs to the pane state, not to the shared quick-bar component.\n\n### Current-Directory Filter Mode\n\n`Ctrl+Alt+F` is now a real current-directory filter workflow, not a smart-navigation alias.\n\nThe implemented contract is:\n\n- the active pane opens the quick bar in `filter` mode\n- the quick bar shows that pane's `currentDirectoryFilter` as a controlled value\n- typing filters the pane's visible file list immediately\n- no dropdown results are shown in this mode\n- `ArrowDown` hands focus from the input into the pane's file list\n- `Escape` clears the filter first, then returns focus to the file list when the input is already empty\n\nThe filter state is pane-local and scoped to the current `connectionId + path`.\n\n- switching between `smart`, `commands`, and `filter` modes does not clear the current directory filter\n- navigating to a different directory clears the filter for the new scope\n- changing the pane's connection also clears the filter for the new scope\n- the status bar remains the persistent reminder that a filter is active even when the quick bar is in another mode\n\n## Current Browser-Level Shortcuts\n\nCurrent browser-level shortcuts include:\n\n- `Ctrl+K`: open smart navigation\n- `Ctrl+Alt+F`: focus current-directory filter mode for the active pane\n- `Ctrl+P`: show commands\n- `F1`: alternate binding for show commands\n- `Ctrl+,`: open settings\n- `?`: show keyboard shortcuts help\n- `Backspace`: go up one directory\n- `Ctrl+R`: refresh file list\n- `F2`: rename focused item\n- `Delete`: delete focused item\n- `F7`: create new directory\n- `Shift+F7`: create new file\n- `Ctrl+Enter`: open focused file in the companion app\n- `Ctrl+B`: toggle dual-pane view\n- `Ctrl+1`: focus left pane\n- `Ctrl+2`: focus right pane\n- `Tab`: switch active pane\n- `F5`: copy to the other pane\n- `F6`: move to the other pane\n\nWhen changing these, treat the behavior as product-level interaction design rather than local implementation detail.\n\n## Focus and Interaction Rules\n\nShortcut work often breaks focus behavior before it breaks functionality. Keep these rules intact:\n\n- opening the quick bar focuses its input immediately\n- selecting a navigation result returns focus to the relevant file list\n- selecting commands that switch quick-bar modes keeps focus inside the quick bar\n- `ArrowDown` from current-directory filter mode moves focus into the filtered file list\n- current-directory filter mode does not open a dropdown for local matches\n- `Escape` in filter mode clears the active filter before it hands focus back to the file list\n- commands that open dialogs or settings do not force focus back to the file list\n- pane-switching shortcuts do not fire while the quick-bar input is focused\n- shortcuts that should work during text entry must explicitly opt in with `allowInInput`\n- shortcuts should be disabled when dialog state or viewer state would make them unsafe\n\n## Context-Aware Shortcut Handling\n\nWhen one key needs different behavior depending on state, prefer one context-aware handler over overlapping registrations.\n\nFor example, `Escape` may close a search panel when that panel is open, but close the viewer when it is not.\n\nThat pattern is better than registering multiple conflicting `Escape` shortcuts because:\n\n- one shortcut definition stays authoritative\n- behavior remains explicit in the component state logic\n- conflicts are easier to reason about and test\n\n### Priority as an Escape Hatch\n\nIn rare cases, multiple handlers for one key are unavoidable. The system supports a `priority` field so higher-priority candidates are evaluated first.\n\nUse that sparingly. A context-aware handler is usually easier to understand and maintain than several competing registrations.\n\n## Adding New Shortcuts Safely\n\nWhen you add a shortcut, keep the workflow centralized.\n\n1. define the shortcut in `config/keyboardShortcuts.ts`\n2. bind it through `useKeyboardShortcuts` in the feature component\n3. reuse the same definition for tooltip or help-surface labels\n4. test both the runtime behavior and the visible affordance\n\nTypical sequence:\n\n```typescript\nexport const PDF_SHORTCUTS = {\n  PRINT: {\n    id: \"print\",\n    keys: \"p\",\n    description: \"Print\",\n    label: \"Ctrl+P\",\n    ctrl: true,\n  },\n} as const;\n```\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...PDF_SHORTCUTS.PRINT,\n      handler: handlePrint,\n    },\n  ],\n});\n```\n\n```typescript\ntitle={withShortcut(PDF_SHORTCUTS.PRINT)}\n```\n\nDo not add one-off tooltip strings or imperative event parsing when the shortcut belongs in the shared system.\n\n## Label Formatting Rules\n\nThe shortcut system also owns display formatting.\n\n- `ArrowRight` becomes `Right`\n- `ArrowLeft` becomes `Left`\n- `ArrowUp` becomes `Up`\n- `ArrowDown` becomes `Down`\n- `Escape` becomes `Esc`\n- space becomes `Space`\n- multiple equivalent keys are joined with ` / `\n- modifiers render as `Ctrl+`, `Shift+`, and `Alt+`\n\nThat formatting should come from the shared system, not from ad hoc component strings.\n\n## Common Failure Modes\n\n- shortcut keys and visible labels drift apart\n- a component registers imperative keyboard logic instead of using the shared hook\n- the browser command palette exposes actions that do not respect the current UI context\n- shortcuts fire while text input or dialog state should block them\n- quick-bar focus returns to the wrong pane in dual-pane workflows\n- multiple overlapping handlers compete for one key instead of using a context-aware handler\n\n## Validation Expectations\n\nWhen keyboard behavior changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change affects file-browser behavior, also test:\n\n- quick-bar navigation and command mode\n- pane switching in dual-pane and single-pane layouts\n- dialog safety for destructive shortcuts\n- viewer shortcut labels and matching runtime behavior\n\nFor new shortcut registrations, also verify:\n\n- the shared label matches the actual bound keys\n- `allowInInput` behavior matches the intended text-entry experience\n- priority and enabled-state logic do not create hidden overlaps\n\n## Where to Continue\n\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL sync, selection, and refresh behavior\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): viewer reuse, preview behavior, and file-type contracts\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): other shared frontend systems contributors should keep centralized\n", "0.8": "+++\ntitle = \"Keyboard Shortcuts and Command Model\"\n+++\n\nKeyboard behavior in Sambee is a shared frontend system, not a pile of local `keydown` handlers.\n\nThe product depends on contributors keeping shortcuts, command labels, viewer controls, and file-browser focus behavior aligned.\n\n## Core Pieces\n\nThese files define the keyboard and command model:\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/config/keyboardShortcuts.ts` | single source of truth for shortcut definitions and display labels |\n| `frontend/src/config/browserCommands.ts` | file-browser command registry for command-palette behavior |\n| `frontend/src/hooks/useKeyboardShortcuts.ts` | shared hook that binds shortcut definitions to runtime handlers |\n| `frontend/src/pages/FileBrowser.tsx` | registers browser-level shortcuts and routes command actions |\n| `frontend/src/components/Viewer/` | consumes shared shortcut definitions for viewer behavior and tooltip labels |\n\nThe system is intentionally split so shortcuts stay declarative while feature surfaces keep control of their own runtime behavior.\n\n## Why the Registry Exists\n\nBefore the centralized model, shortcut keys, tooltip labels, and component handlers drifted apart easily.\n\nThe current approach preserves these rules:\n\n- define shortcut keys and display intent once\n- reuse the same definition across viewers and file-browser surfaces\n- let components supply handlers without redefining labels and modifiers\n- keep file-browser actions discoverable even when users do not know the shortcut\n\n## Shortcut Definition Model\n\nShortcut definitions are grouped by scope, such as common viewer actions, PDF-specific actions, image-viewer actions, or browser actions.\n\nRepresentative structure:\n\n```typescript\nexport const COMMON_SHORTCUTS = {\n  CLOSE: {\n    id: \"close\",\n    keys: \"Escape\",\n    description: \"Close\",\n    label: \"Esc\",\n    allowInInput: true,\n  },\n  DOWNLOAD: {\n    id: \"download\",\n    keys: \"s\",\n    description: \"Download\",\n    label: \"Ctrl+S\",\n    ctrl: true,\n  },\n} as const;\n```\n\nCommon properties include:\n\n- `id`: stable identifier\n- `keys`: one key or multiple equivalent keys\n- `description`: human-readable intent\n- `label`: optional display label; if omitted, it can be generated from the config\n- `ctrl`, `shift`, `alt`: required modifiers\n- `allowInInput`: whether the shortcut still works while an input is focused\n- `priority`: ordering for overlapping shortcut candidates\n\n## Using the Shared Hook\n\nFeature components bind runtime behavior through `useKeyboardShortcuts` instead of duplicating event parsing logic.\n\nTypical usage:\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...COMMON_SHORTCUTS.CLOSE,\n      handler: onClose,\n    },\n    {\n      ...COMMON_SHORTCUTS.DOWNLOAD,\n      handler: handleDownload,\n    },\n    {\n      ...PDF_SHORTCUTS.SEARCH,\n      handler: handleOpenSearch,\n    },\n  ],\n});\n```\n\nThat split keeps the registry declarative and keeps feature logic in the feature component.\n\n## Labels and Tooltip Reuse\n\nViewer controls and similar UI surfaces should reuse the same shortcut definition instead of duplicating string formatting.\n\nThe shared formatter can turn a shortcut definition into a tooltip label such as `Download (Ctrl+S)`.\n\nThat matters because a changed shortcut should update viewer behavior and visible affordances together.\n\n## Browser Commands Versus Raw Shortcuts\n\nThe file browser uses both shortcut definitions and a command registry.\n\n- shortcut definitions remain centralized in `keyboardShortcuts.ts`\n- discoverable browser actions live in `browserCommands.ts`\n- command definitions point back to shortcut identifiers when a keyboard binding exists\n\nThis lets Sambee expose browser actions through the quick bar even when the user does not know the shortcut.\n\nEach browser command definition includes concepts such as:\n\n- a stable `id`\n- a user-facing `title`\n- a `category` for command grouping\n- linked shortcut identifiers\n- `isEnabled(context)` for context-aware availability\n- `run(context)` for execution\n- `selectionFocusTarget` for post-selection focus behavior\n\n## Quick-Bar Modes\n\nThe file browser quick bar is not just a text filter. It supports multiple modes with different intent.\n\n- `Ctrl+K`: open the smart navigation surface\n- `Ctrl+Alt+F`: open pane-local current-directory filter mode\n- `Ctrl+P` or `F1`: open command mode directly\n- typing `\u003e` as the first character switches the quick bar into command mode\n\nSmart navigation and command mode are dropdown-backed provider modes. Filter mode deliberately is not.\n\n- `smart` mode uses the search provider composition that merges directory navigation and command escape-hatch behavior\n- `commands` mode uses the browser command registry directly\n- `filter` mode uses the same input shell, but as a controlled pane-local filter box with dropdown rendering disabled\n\nThe quick bar captures the pane that opened it. In dual-pane mode, the active quick-bar pane stays fixed even if the other pane becomes active before selection.\n\nThat capture rule matters especially for filter mode, because the filter text belongs to the pane state, not to the shared quick-bar component.\n\n### Current-Directory Filter Mode\n\n`Ctrl+Alt+F` is now a real current-directory filter workflow, not a smart-navigation alias.\n\nThe implemented contract is:\n\n- the active pane opens the quick bar in `filter` mode\n- the quick bar shows that pane's `currentDirectoryFilter` as a controlled value\n- typing filters the pane's visible file list immediately\n- no dropdown results are shown in this mode\n- `ArrowDown` hands focus from the input into the pane's file list\n- `Escape` clears the filter first, then returns focus to the file list when the input is already empty\n\nThe filter state is pane-local and scoped to the current `connectionId + path`.\n\n- switching between `smart`, `commands`, and `filter` modes does not clear the current directory filter\n- navigating to a different directory clears the filter for the new scope\n- changing the pane's connection also clears the filter for the new scope\n- the status bar remains the persistent reminder that a filter is active even when the quick bar is in another mode\n\n## Current Browser-Level Shortcuts\n\nCurrent browser-level shortcuts include:\n\n- `Ctrl+K`: open smart navigation\n- `Ctrl+Alt+F`: focus current-directory filter mode for the active pane\n- `Ctrl+P`: show commands\n- `F1`: alternate binding for show commands\n- `Ctrl+,`: open settings\n- `?`: show keyboard shortcuts help\n- `Backspace`: go up one directory\n- `Ctrl+R`: refresh file list\n- `F2`: rename focused item\n- `Delete`: delete focused item\n- `F7`: create new directory\n- `Shift+F7`: create new file\n- `Ctrl+Enter`: open focused file in the companion app\n- `Ctrl+B`: toggle dual-pane view\n- `Ctrl+1`: focus left pane\n- `Ctrl+2`: focus right pane\n- `Tab`: switch active pane\n- `F5`: copy to the other pane\n- `F6`: move to the other pane\n\nWhen changing these, treat the behavior as product-level interaction design rather than local implementation detail.\n\n## Focus and Interaction Rules\n\nShortcut work often breaks focus behavior before it breaks functionality. Keep these rules intact:\n\n- opening the quick bar focuses its input immediately\n- selecting a navigation result returns focus to the relevant file list\n- selecting commands that switch quick-bar modes keeps focus inside the quick bar\n- `ArrowDown` from current-directory filter mode moves focus into the filtered file list\n- current-directory filter mode does not open a dropdown for local matches\n- `Escape` in filter mode clears the active filter before it hands focus back to the file list\n- commands that open dialogs or settings do not force focus back to the file list\n- pane-switching shortcuts do not fire while the quick-bar input is focused\n- shortcuts that should work during text entry must explicitly opt in with `allowInInput`\n- shortcuts should be disabled when dialog state or viewer state would make them unsafe\n\n## Context-Aware Shortcut Handling\n\nWhen one key needs different behavior depending on state, prefer one context-aware handler over overlapping registrations.\n\nFor example, `Escape` may close a search panel when that panel is open, but close the viewer when it is not.\n\nThat pattern is better than registering multiple conflicting `Escape` shortcuts because:\n\n- one shortcut definition stays authoritative\n- behavior remains explicit in the component state logic\n- conflicts are easier to reason about and test\n\n### Priority as an Escape Hatch\n\nIn rare cases, multiple handlers for one key are unavoidable. The system supports a `priority` field so higher-priority candidates are evaluated first.\n\nUse that sparingly. A context-aware handler is usually easier to understand and maintain than several competing registrations.\n\n## Adding New Shortcuts Safely\n\nWhen you add a shortcut, keep the workflow centralized.\n\n1. define the shortcut in `config/keyboardShortcuts.ts`\n2. bind it through `useKeyboardShortcuts` in the feature component\n3. reuse the same definition for tooltip or help-surface labels\n4. test both the runtime behavior and the visible affordance\n\nTypical sequence:\n\n```typescript\nexport const PDF_SHORTCUTS = {\n  PRINT: {\n    id: \"print\",\n    keys: \"p\",\n    description: \"Print\",\n    label: \"Ctrl+P\",\n    ctrl: true,\n  },\n} as const;\n```\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...PDF_SHORTCUTS.PRINT,\n      handler: handlePrint,\n    },\n  ],\n});\n```\n\n```typescript\ntitle={withShortcut(PDF_SHORTCUTS.PRINT)}\n```\n\nDo not add one-off tooltip strings or imperative event parsing when the shortcut belongs in the shared system.\n\n## Label Formatting Rules\n\nThe shortcut system also owns display formatting.\n\n- `ArrowRight` becomes `Right`\n- `ArrowLeft` becomes `Left`\n- `ArrowUp` becomes `Up`\n- `ArrowDown` becomes `Down`\n- `Escape` becomes `Esc`\n- space becomes `Space`\n- multiple equivalent keys are joined with ` / `\n- modifiers render as `Ctrl+`, `Shift+`, and `Alt+`\n\nThat formatting should come from the shared system, not from ad hoc component strings.\n\n## Common Failure Modes\n\n- shortcut keys and visible labels drift apart\n- a component registers imperative keyboard logic instead of using the shared hook\n- the browser command palette exposes actions that do not respect the current UI context\n- shortcuts fire while text input or dialog state should block them\n- quick-bar focus returns to the wrong pane in dual-pane workflows\n- multiple overlapping handlers compete for one key instead of using a context-aware handler\n\n## Validation Expectations\n\nWhen keyboard behavior changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change affects file-browser behavior, also test:\n\n- quick-bar navigation and command mode\n- pane switching in dual-pane and single-pane layouts\n- dialog safety for destructive shortcuts\n- viewer shortcut labels and matching runtime behavior\n\nFor new shortcut registrations, also verify:\n\n- the shared label matches the actual bound keys\n- `allowInInput` behavior matches the intended text-entry experience\n- priority and enabled-state logic do not create hidden overlaps\n\n## Where to Continue\n\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL sync, selection, and refresh behavior\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): viewer reuse, preview behavior, and file-type contracts\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): other shared frontend systems contributors should keep centralized\n", "0.9": "+++\ntitle = \"Keyboard Shortcuts and Command Model\"\n+++\n\nKeyboard behavior in Sambee is a shared frontend system, not a pile of local `keydown` handlers.\n\nThe product depends on contributors keeping shortcuts, command labels, viewer controls, and file-browser focus behavior aligned.\n\n## Core Pieces\n\nThese files define the keyboard and command model:\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/config/keyboardShortcuts.ts` | single source of truth for shortcut definitions and display labels |\n| `frontend/src/config/browserCommands.ts` | file-browser command registry for command-palette behavior |\n| `frontend/src/hooks/useKeyboardShortcuts.ts` | shared hook that binds shortcut definitions to runtime handlers |\n| `frontend/src/pages/FileBrowser.tsx` | registers browser-level shortcuts and routes command actions |\n| `frontend/src/components/Viewer/` | consumes shared shortcut definitions for viewer behavior and tooltip labels |\n\nThe system is intentionally split so shortcuts stay declarative while feature surfaces keep control of their own runtime behavior.\n\n## Why the Registry Exists\n\nBefore the centralized model, shortcut keys, tooltip labels, and component handlers drifted apart easily.\n\nThe current approach preserves these rules:\n\n- define shortcut keys and display intent once\n- reuse the same definition across viewers and file-browser surfaces\n- let components supply handlers without redefining labels and modifiers\n- keep file-browser actions discoverable even when users do not know the shortcut\n\n## Shortcut Definition Model\n\nShortcut definitions are grouped by scope, such as common viewer actions, PDF-specific actions, image-viewer actions, or browser actions.\n\nRepresentative structure:\n\n```typescript\nexport const COMMON_SHORTCUTS = {\n  CLOSE: {\n    id: \"close\",\n    keys: \"Escape\",\n    description: \"Close\",\n    label: \"Esc\",\n    allowInInput: true,\n  },\n  DOWNLOAD: {\n    id: \"download\",\n    keys: \"s\",\n    description: \"Download\",\n    label: \"Ctrl+S\",\n    ctrl: true,\n  },\n} as const;\n```\n\nCommon properties include:\n\n- `id`: stable identifier\n- `keys`: one key or multiple equivalent keys\n- `description`: human-readable intent\n- `label`: optional display label; if omitted, it can be generated from the config\n- `ctrl`, `shift`, `alt`: required modifiers\n- `allowInInput`: whether the shortcut still works while an input is focused\n- `priority`: ordering for overlapping shortcut candidates\n\n## Using the Shared Hook\n\nFeature components bind runtime behavior through `useKeyboardShortcuts` instead of duplicating event parsing logic.\n\nTypical usage:\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...COMMON_SHORTCUTS.CLOSE,\n      handler: onClose,\n    },\n    {\n      ...COMMON_SHORTCUTS.DOWNLOAD,\n      handler: handleDownload,\n    },\n    {\n      ...PDF_SHORTCUTS.SEARCH,\n      handler: handleOpenSearch,\n    },\n  ],\n});\n```\n\nThat split keeps the registry declarative and keeps feature logic in the feature component.\n\n## Labels and Tooltip Reuse\n\nViewer controls and similar UI surfaces should reuse the same shortcut definition instead of duplicating string formatting.\n\nThe shared formatter can turn a shortcut definition into a tooltip label such as `Download (Ctrl+S)`.\n\nThat matters because a changed shortcut should update viewer behavior and visible affordances together.\n\n## Browser Commands Versus Raw Shortcuts\n\nThe file browser uses both shortcut definitions and a command registry.\n\n- shortcut definitions remain centralized in `keyboardShortcuts.ts`\n- discoverable browser actions live in `browserCommands.ts`\n- command definitions point back to shortcut identifiers when a keyboard binding exists\n\nThis lets Sambee expose browser actions through the quick bar even when the user does not know the shortcut.\n\nEach browser command definition includes concepts such as:\n\n- a stable `id`\n- a user-facing `title`\n- a `category` for command grouping\n- linked shortcut identifiers\n- `isEnabled(context)` for context-aware availability\n- `run(context)` for execution\n- `selectionFocusTarget` for post-selection focus behavior\n\n## Quick-Bar Modes\n\nThe file browser quick bar is not just a text filter. It supports multiple modes with different intent.\n\n- `Ctrl+K`: open the smart navigation surface\n- `Ctrl+Alt+F`: open pane-local current-directory filter mode\n- `Ctrl+P` or `F1`: open command mode directly\n- typing `\u003e` as the first character switches the quick bar into command mode\n\nSmart navigation and command mode are dropdown-backed provider modes. Filter mode deliberately is not.\n\n- `smart` mode uses the search provider composition that merges directory navigation and command escape-hatch behavior\n- `commands` mode uses the browser command registry directly\n- `filter` mode uses the same input shell, but as a controlled pane-local filter box with dropdown rendering disabled\n\nThe quick bar captures the pane that opened it. In dual-pane mode, the active quick-bar pane stays fixed even if the other pane becomes active before selection.\n\nThat capture rule matters especially for filter mode, because the filter text belongs to the pane state, not to the shared quick-bar component.\n\n### Current-Directory Filter Mode\n\n`Ctrl+Alt+F` is now a real current-directory filter workflow, not a smart-navigation alias.\n\nThe implemented contract is:\n\n- the active pane opens the quick bar in `filter` mode\n- the quick bar shows that pane's `currentDirectoryFilter` as a controlled value\n- typing filters the pane's visible file list immediately\n- no dropdown results are shown in this mode\n- `ArrowDown` hands focus from the input into the pane's file list\n- `Escape` clears the filter first, then returns focus to the file list when the input is already empty\n\nThe filter state is pane-local and scoped to the current `connectionId + path`.\n\n- switching between `smart`, `commands`, and `filter` modes does not clear the current directory filter\n- navigating to a different directory clears the filter for the new scope\n- changing the pane's connection also clears the filter for the new scope\n- the status bar remains the persistent reminder that a filter is active even when the quick bar is in another mode\n\n## Current Browser-Level Shortcuts\n\nCurrent browser-level shortcuts include:\n\n- `Ctrl+K`: open smart navigation\n- `Ctrl+Alt+F`: focus current-directory filter mode for the active pane\n- `Ctrl+P`: show commands\n- `F1`: alternate binding for show commands\n- `Ctrl+,`: open settings\n- `?`: show keyboard shortcuts help\n- `Backspace`: go up one directory\n- `Ctrl+R`: refresh file list\n- `F2`: rename focused item\n- `Delete`: delete focused item\n- `F7`: create new directory\n- `Shift+F7`: create new file\n- `Ctrl+Enter`: open focused file in the companion app\n- `Ctrl+B`: toggle dual-pane view\n- `Ctrl+1`: focus left pane\n- `Ctrl+2`: focus right pane\n- `Tab`: switch active pane\n- `F5`: copy to the other pane\n- `F6`: move to the other pane\n\nWhen changing these, treat the behavior as product-level interaction design rather than local implementation detail.\n\n## Focus and Interaction Rules\n\nShortcut work often breaks focus behavior before it breaks functionality. Keep these rules intact:\n\n- opening the quick bar focuses its input immediately\n- selecting a navigation result returns focus to the relevant file list\n- selecting commands that switch quick-bar modes keeps focus inside the quick bar\n- `ArrowDown` from current-directory filter mode moves focus into the filtered file list\n- current-directory filter mode does not open a dropdown for local matches\n- `Escape` in filter mode clears the active filter before it hands focus back to the file list\n- commands that open dialogs or settings do not force focus back to the file list\n- pane-switching shortcuts do not fire while the quick-bar input is focused\n- shortcuts that should work during text entry must explicitly opt in with `allowInInput`\n- shortcuts should be disabled when dialog state or viewer state would make them unsafe\n\n## Context-Aware Shortcut Handling\n\nWhen one key needs different behavior depending on state, prefer one context-aware handler over overlapping registrations.\n\nFor example, `Escape` may close a search panel when that panel is open, but close the viewer when it is not.\n\nThat pattern is better than registering multiple conflicting `Escape` shortcuts because:\n\n- one shortcut definition stays authoritative\n- behavior remains explicit in the component state logic\n- conflicts are easier to reason about and test\n\n### Priority as an Escape Hatch\n\nIn rare cases, multiple handlers for one key are unavoidable. The system supports a `priority` field so higher-priority candidates are evaluated first.\n\nUse that sparingly. A context-aware handler is usually easier to understand and maintain than several competing registrations.\n\n## Adding New Shortcuts Safely\n\nWhen you add a shortcut, keep the workflow centralized.\n\n1. define the shortcut in `config/keyboardShortcuts.ts`\n2. bind it through `useKeyboardShortcuts` in the feature component\n3. reuse the same definition for tooltip or help-surface labels\n4. test both the runtime behavior and the visible affordance\n\nTypical sequence:\n\n```typescript\nexport const PDF_SHORTCUTS = {\n  PRINT: {\n    id: \"print\",\n    keys: \"p\",\n    description: \"Print\",\n    label: \"Ctrl+P\",\n    ctrl: true,\n  },\n} as const;\n```\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...PDF_SHORTCUTS.PRINT,\n      handler: handlePrint,\n    },\n  ],\n});\n```\n\n```typescript\ntitle={withShortcut(PDF_SHORTCUTS.PRINT)}\n```\n\nDo not add one-off tooltip strings or imperative event parsing when the shortcut belongs in the shared system.\n\n## Label Formatting Rules\n\nThe shortcut system also owns display formatting.\n\n- `ArrowRight` becomes `Right`\n- `ArrowLeft` becomes `Left`\n- `ArrowUp` becomes `Up`\n- `ArrowDown` becomes `Down`\n- `Escape` becomes `Esc`\n- space becomes `Space`\n- multiple equivalent keys are joined with ` / `\n- modifiers render as `Ctrl+`, `Shift+`, and `Alt+`\n\nThat formatting should come from the shared system, not from ad hoc component strings.\n\n## Common Failure Modes\n\n- shortcut keys and visible labels drift apart\n- a component registers imperative keyboard logic instead of using the shared hook\n- the browser command palette exposes actions that do not respect the current UI context\n- shortcuts fire while text input or dialog state should block them\n- quick-bar focus returns to the wrong pane in dual-pane workflows\n- multiple overlapping handlers compete for one key instead of using a context-aware handler\n\n## Validation Expectations\n\nWhen keyboard behavior changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change affects file-browser behavior, also test:\n\n- quick-bar navigation and command mode\n- pane switching in dual-pane and single-pane layouts\n- dialog safety for destructive shortcuts\n- viewer shortcut labels and matching runtime behavior\n\nFor new shortcut registrations, also verify:\n\n- the shared label matches the actual bound keys\n- `allowInInput` behavior matches the intended text-entry experience\n- priority and enabled-state logic do not create hidden overlaps\n\n## Where to Continue\n\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL sync, selection, and refresh behavior\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): viewer reuse, preview behavior, and file-type contracts\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): other shared frontend systems contributors should keep centralized\n", "1.0": "+++\ntitle = \"Keyboard Shortcuts and Command Model\"\n+++\n\nKeyboard behavior in Sambee is a shared frontend system, not a pile of local `keydown` handlers.\n\nThe product depends on contributors keeping shortcuts, command labels, viewer controls, and file-browser focus behavior aligned.\n\n## Core Pieces\n\nThese files define the keyboard and command model:\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/config/keyboardShortcuts.ts` | single source of truth for shortcut definitions and display labels |\n| `frontend/src/config/browserCommands.ts` | file-browser command registry for command-palette behavior |\n| `frontend/src/hooks/useKeyboardShortcuts.ts` | shared hook that binds shortcut definitions to runtime handlers |\n| `frontend/src/pages/FileBrowser.tsx` | registers browser-level shortcuts and routes command actions |\n| `frontend/src/components/Viewer/` | consumes shared shortcut definitions for viewer behavior and tooltip labels |\n| `frontend/src/components/Viewer/CodeMirrorFindReplacePopover.tsx` | shared compact find, match-option, and replacement controls for CodeMirror editors |\n\nThe system is intentionally split so shortcuts stay declarative while feature surfaces keep control of their own runtime behavior.\n\n## Why the Registry Exists\n\nBefore the centralized model, shortcut keys, tooltip labels, and component handlers drifted apart easily.\n\nThe current approach preserves these rules:\n\n- define shortcut keys and display intent once\n- reuse the same definition across viewers and file-browser surfaces\n- let components supply handlers without redefining labels and modifiers\n- keep file-browser actions discoverable even when users do not know the shortcut\n\n## Shortcut Definition Model\n\nShortcut definitions are grouped by scope, such as common viewer actions, PDF-specific actions, image-viewer actions, or browser actions.\n\nRepresentative structure:\n\n```typescript\nexport const COMMON_SHORTCUTS = {\n  CLOSE: {\n    id: \"close\",\n    keys: \"Escape\",\n    description: \"Close\",\n    label: \"Esc\",\n    allowInInput: true,\n  },\n  DOWNLOAD: {\n    id: \"download\",\n    keys: \"s\",\n    description: \"Download\",\n    label: \"Ctrl+S\",\n    ctrl: true,\n  },\n} as const;\n```\n\nCommon properties include:\n\n- `id`: stable identifier\n- `keys`: one key or multiple equivalent keys\n- `description`: human-readable intent\n- `label`: optional display label; if omitted, it can be generated from the config\n- `ctrl`, `shift`, `alt`: required modifiers\n- `allowInInput`: whether the shortcut still works while an input is focused\n- `priority`: ordering for overlapping shortcut candidates\n\n## Using the Shared Hook\n\nFeature components bind runtime behavior through `useKeyboardShortcuts` instead of duplicating event parsing logic.\n\nTypical usage:\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...COMMON_SHORTCUTS.CLOSE,\n      handler: onClose,\n    },\n    {\n      ...COMMON_SHORTCUTS.DOWNLOAD,\n      handler: handleDownload,\n    },\n    {\n      ...PDF_SHORTCUTS.SEARCH,\n      handler: handleOpenSearch,\n    },\n  ],\n});\n```\n\nThat split keeps the registry declarative and keeps feature logic in the feature component.\n\n## Labels and Tooltip Reuse\n\nViewer controls and similar UI surfaces should reuse the same shortcut definition instead of duplicating string formatting.\n\nThe shared formatter can turn a shortcut definition into a tooltip label such as `Download (Ctrl+S)`.\n\nThat matters because a changed shortcut should update viewer behavior and visible affordances together.\n\n## Browser Commands Versus Raw Shortcuts\n\nThe file browser uses both shortcut definitions and a command registry.\n\n- shortcut definitions remain centralized in `keyboardShortcuts.ts`\n- discoverable browser actions live in `browserCommands.ts`\n- command definitions point back to shortcut identifiers when a keyboard binding exists\n\nThis lets Sambee expose browser actions through the quick bar even when the user does not know the shortcut.\n\nEach browser command definition includes concepts such as:\n\n- a stable `id`\n- a user-facing `title`\n- a `category` for command grouping\n- linked shortcut identifiers\n- `isEnabled(context)` for context-aware availability\n- `run(context)` for execution\n- `selectionFocusTarget` for post-selection focus behavior\n\n## Quick-Bar Modes\n\nThe file browser quick bar is not just a text filter. It supports multiple modes with different intent.\n\n- `Ctrl+K`: open the smart navigation surface\n- `Ctrl+Alt+F`: open pane-local current-directory filter mode\n- `Ctrl+P`: open command mode directly\n- typing `\u003e` as the first character switches the quick bar into command mode\n\nSmart navigation and command mode are dropdown-backed provider modes. Filter mode deliberately is not.\n\n- `smart` mode uses the search provider composition that merges directory navigation and command escape-hatch behavior\n- `commands` mode uses the browser command registry directly\n- `filter` mode uses the same input shell, but as a controlled pane-local filter box with dropdown rendering disabled\n\nThe quick bar captures the pane that opened it. In dual-pane mode, the active quick-bar pane stays fixed even if the other pane becomes active before selection.\n\nThat capture rule matters especially for filter mode, because the filter text belongs to the pane state, not to the shared quick-bar component.\n\n### Current-Directory Filter Mode\n\n`Ctrl+Alt+F` is now a real current-directory filter workflow, not a smart-navigation alias.\n\nThe implemented contract is:\n\n- the active pane opens the quick bar in `filter` mode\n- the quick bar shows that pane's `currentDirectoryFilter` as a controlled value\n- typing filters the pane's visible file list immediately\n- no dropdown results are shown in this mode\n- `ArrowDown` hands focus from the input into the pane's file list\n- `Escape` clears the filter first, then returns focus to the file list when the input is already empty\n\nThe filter state is pane-local and scoped to the current `connectionId + path`.\n\n- switching between `smart`, `commands`, and `filter` modes does not clear the current directory filter\n- navigating to a different directory clears the filter for the new scope\n- changing the pane's connection also clears the filter for the new scope\n- the status bar remains the persistent reminder that a filter is active even when the quick bar is in another mode\n\n## Current Browser-Level Shortcuts\n\nCurrent browser-level shortcuts include:\n\n- `Ctrl+K`: open smart navigation\n- `Ctrl+Alt+F`: focus current-directory filter mode for the active pane\n- `Ctrl+P`: show commands\n- `Ctrl+,`: open settings\n- `?` or `F1`: show keyboard shortcuts help\n- `Backspace`: go up one directory\n- `Ctrl+R`: refresh file list\n- `F2`: rename focused item\n- `Delete`: delete focused item\n- `F7`: create new directory\n- `Shift+F7`: create new file\n- `Ctrl+Enter`: open focused file in the companion app\n- `Ctrl+B`: toggle dual-pane view\n- `Ctrl+1`: focus left pane\n- `Ctrl+2`: focus right pane\n- `Tab`: switch active pane\n- `F5`: copy to the other pane\n- `F6`: move to the other pane\n\nWhen changing these, treat the behavior as product-level interaction design rather than local implementation detail.\n\n## Focus and Interaction Rules\n\nShortcut work often breaks focus behavior before it breaks functionality. Keep these rules intact:\n\n- opening the quick bar focuses its input immediately\n- selecting a navigation result returns focus to the relevant file list\n- selecting commands that switch quick-bar modes keeps focus inside the quick bar\n- `ArrowDown` from current-directory filter mode moves focus into the filtered file list\n- current-directory filter mode does not open a dropdown for local matches\n- `Escape` in filter mode clears the active filter before it hands focus back to the file list\n- commands that open dialogs or settings do not force focus back to the file list\n- pane-switching shortcuts do not fire while the quick-bar input is focused\n- shortcuts that should work during text entry must explicitly opt in with `allowInInput`\n- shortcuts should be disabled when dialog state or viewer state would make them unsafe\n\n## Context-Aware Shortcut Handling\n\nWhen one key needs different behavior depending on state, prefer one context-aware handler over overlapping registrations.\n\nFor example, `Escape` may close a search panel when that panel is open, but close the viewer when it is not.\n\nThat pattern is better than registering multiple conflicting `Escape` shortcuts because:\n\n- one shortcut definition stays authoritative\n- behavior remains explicit in the component state logic\n- conflicts are easier to reason about and test\n\n### Priority as an Escape Hatch\n\nIn rare cases, multiple handlers for one key are unavoidable. The system supports a `priority` field so higher-priority candidates are evaluated first.\n\nUse that sparingly. A context-aware handler is usually easier to understand and maintain than several competing registrations.\n\n## Adding New Shortcuts Safely\n\nWhen you add a shortcut, keep the workflow centralized.\n\n1. define the shortcut in `config/keyboardShortcuts.ts`\n1. bind it through `useKeyboardShortcuts` in the feature component\n1. reuse the same definition for tooltip or help-surface labels\n1. test both the runtime behavior and the visible affordance\n\nTypical sequence:\n\n```typescript\nexport const PDF_SHORTCUTS = {\n  PRINT: {\n    id: \"print\",\n    keys: \"p\",\n    description: \"Print\",\n    label: \"Ctrl+P\",\n    ctrl: true,\n  },\n} as const;\n```\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...PDF_SHORTCUTS.PRINT,\n      handler: handlePrint,\n    },\n  ],\n});\n```\n\n```typescript\ntitle={withShortcut(PDF_SHORTCUTS.PRINT)}\n```\n\nDo not add one-off tooltip strings or imperative event parsing when the shortcut belongs in the shared system.\n\n## CodeMirror Find and Replace\n\nMarkdown and text editing keep find and replace in an editor-local fixed surface near the upper-right viewport edge, below the viewer toolbar, rather than in the shared viewer toolbar. `MarkdownViewer` and `TextViewer` own the surrounding viewer state and bind `Ctrl+H`, `Alt+C`, `Alt+W`, and `Alt+R` through `CODEMIRROR_EDITOR_SHORTCUTS`. The existing shared `F3` and `Shift+F3` registrations remain the navigation authority, including while a find or replace input has focus. `Enter` and `Ctrl+Alt+Enter` are also declared in that registry for replace-current and replace-all, but their `allowInInputWithin` scope limits them to the replacement field.\n\n`codeMirrorFindReplace.ts` owns the shared `SearchQuery` construction, validity-aware metrics, and auto-navigation logic. `MarkdownRichEditor` and `TextCodeEditor` map the controlled state to that API and use CodeMirror's native `replaceNext` and `replaceAll` commands. Keep replacement operations on those native commands so CodeMirror owns selection updates and undo transactions. Search metrics must check the query validity before creating a cursor because an invalid regular expression cannot produce one.\n\n`CodeMirrorFindReplacePopover` is intentionally non-modal so the editor remains visible and keyboard navigation remains continuous. Its Find and Replace inputs come first in DOM order to preserve the first two tab stops. The history affordance is supplied by the in-field `Search (\u21c5 for history)` and `Replace (\u21c5 for history)` placeholders; result count, match options, navigation, and close controls occupy the first row to the inputs' right. `codeMirrorFindReplaceHistory.ts` persists independent Find and Replace histories in local storage, safely tolerating unavailable or malformed storage and retaining only the ten newest unique non-empty values. Reuse dialog surface tokens for its paper, but do not use `ResponsiveFormDialog`: full-screen viewers retain their specialized focus and layout shell.\n\n## Label Formatting Rules\n\nThe shortcut system also owns display formatting.\n\n- `ArrowRight` becomes `Right`\n- `ArrowLeft` becomes `Left`\n- `ArrowUp` becomes `Up`\n- `ArrowDown` becomes `Down`\n- `Escape` becomes `Esc`\n- space becomes `Space`\n- multiple equivalent keys are joined with ` / `\n- modifiers render as `Ctrl+`, `Shift+`, and `Alt+`\n\nThat formatting should come from the shared system, not from ad hoc component strings.\n\n## Common Failure Modes\n\n- shortcut keys and visible labels drift apart\n- a component registers imperative keyboard logic instead of using the shared hook\n- the browser command palette exposes actions that do not respect the current UI context\n- shortcuts fire while text input or dialog state should block them\n- quick-bar focus returns to the wrong pane in dual-pane workflows\n- multiple overlapping handlers compete for one key instead of using a context-aware handler\n\n## Validation Expectations\n\nWhen keyboard behavior changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change affects file-browser behavior, also test:\n\n- quick-bar navigation and command mode\n- pane switching in dual-pane and single-pane layouts\n- dialog safety for destructive shortcuts\n- viewer shortcut labels and matching runtime behavior\n\nFor new shortcut registrations, also verify:\n\n- the shared label matches the actual bound keys\n- `allowInInput` behavior matches the intended text-entry experience\n- priority and enabled-state logic do not create hidden overlaps\n\n## Where to Continue\n\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL sync, selection, and refresh behavior\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): viewer reuse, preview behavior, and file-type contracts\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): other shared frontend systems contributors should keep centralized\n", "2.0": "+++\ntitle = \"Keyboard Shortcuts and Command Model\"\n+++\n\nKeyboard behavior in Sambee is a shared frontend system, not a pile of local `keydown` handlers.\n\nThe product depends on contributors keeping shortcuts, command labels, viewer controls, and file-browser focus behavior aligned.\n\n## Core Pieces\n\nThese files define the keyboard and command model:\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/config/keyboardShortcuts.ts` | single source of truth for shortcut definitions and display labels |\n| `frontend/src/config/browserCommands.ts` | file-browser command registry for command-palette behavior |\n| `frontend/src/hooks/useKeyboardShortcuts.ts` | shared hook that binds shortcut definitions to runtime handlers |\n| `frontend/src/pages/FileBrowser.tsx` | registers browser-level shortcuts and routes command actions |\n| `frontend/src/components/Viewer/` | consumes shared shortcut definitions for viewer behavior and tooltip labels |\n| `frontend/src/components/Viewer/CodeMirrorFindReplacePopover.tsx` | shared compact find, match-option, and replacement controls for CodeMirror editors |\n\nThe system is intentionally split so shortcuts stay declarative while feature surfaces keep control of their own runtime behavior.\n\n## Why the Registry Exists\n\nBefore the centralized model, shortcut keys, tooltip labels, and component handlers drifted apart easily.\n\nThe current approach preserves these rules:\n\n- define shortcut keys and display intent once\n- reuse the same definition across viewers and file-browser surfaces\n- let components supply handlers without redefining labels and modifiers\n- keep file-browser actions discoverable even when users do not know the shortcut\n\n## Shortcut Definition Model\n\nShortcut definitions are grouped by scope, such as common viewer actions, PDF-specific actions, image-viewer actions, or browser actions.\n\nRepresentative structure:\n\n```typescript\nexport const COMMON_SHORTCUTS = {\n  CLOSE: {\n    id: \"close\",\n    keys: \"Escape\",\n    description: \"Close\",\n    label: \"Esc\",\n    allowInInput: true,\n  },\n  DOWNLOAD: {\n    id: \"download\",\n    keys: \"s\",\n    description: \"Download\",\n    label: \"Ctrl+S\",\n    ctrl: true,\n  },\n} as const;\n```\n\nCommon properties include:\n\n- `id`: stable identifier\n- `keys`: one key or multiple equivalent keys\n- `description`: human-readable intent\n- `label`: optional display label; if omitted, it can be generated from the config\n- `ctrl`, `shift`, `alt`: required modifiers\n- `allowInInput`: whether the shortcut still works while an input is focused\n- `priority`: ordering for overlapping shortcut candidates\n\n## Using the Shared Hook\n\nFeature components bind runtime behavior through `useKeyboardShortcuts` instead of duplicating event parsing logic.\n\nTypical usage:\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...COMMON_SHORTCUTS.CLOSE,\n      handler: onClose,\n    },\n    {\n      ...COMMON_SHORTCUTS.DOWNLOAD,\n      handler: handleDownload,\n    },\n    {\n      ...PDF_SHORTCUTS.SEARCH,\n      handler: handleOpenSearch,\n    },\n  ],\n});\n```\n\nThat split keeps the registry declarative and keeps feature logic in the feature component.\n\n## Labels and Tooltip Reuse\n\nViewer controls and similar UI surfaces should reuse the same shortcut definition instead of duplicating string formatting.\n\nThe shared formatter can turn a shortcut definition into a tooltip label such as `Download (Ctrl+S)`.\n\nThat matters because a changed shortcut should update viewer behavior and visible affordances together.\n\n## Browser Commands Versus Raw Shortcuts\n\nThe file browser uses both shortcut definitions and a command registry.\n\n- shortcut definitions remain centralized in `keyboardShortcuts.ts`\n- discoverable browser actions live in `browserCommands.ts`\n- command definitions point back to shortcut identifiers when a keyboard binding exists\n\nThis lets Sambee expose browser actions through the quick bar even when the user does not know the shortcut.\n\nEach browser command definition includes concepts such as:\n\n- a stable `id`\n- a user-facing `title`\n- a `category` for command grouping\n- linked shortcut identifiers\n- `isEnabled(context)` for context-aware availability\n- `run(context)` for execution\n- `selectionFocusTarget` for post-selection focus behavior\n\n## Quick-Bar Modes\n\nThe file browser quick bar is not just a text filter. It supports multiple modes with different intent.\n\n- `Ctrl+K`: open the smart navigation surface\n- `Ctrl+Alt+F`: open pane-local current-directory filter mode\n- `Ctrl+P`: open command mode directly\n- typing `\u003e` as the first character switches the quick bar into command mode\n\nSmart navigation and command mode are dropdown-backed provider modes. Filter mode deliberately is not.\n\n- `smart` mode uses the search provider composition that merges directory navigation and command escape-hatch behavior\n- `commands` mode uses the browser command registry directly\n- `filter` mode uses the same input shell, but as a controlled pane-local filter box with dropdown rendering disabled\n\nThe quick bar captures the pane that opened it. In dual-pane mode, the active quick-bar pane stays fixed even if the other pane becomes active before selection.\n\nThat capture rule matters especially for filter mode, because the filter text belongs to the pane state, not to the shared quick-bar component.\n\n### Current-Directory Filter Mode\n\n`Ctrl+Alt+F` is now a real current-directory filter workflow, not a smart-navigation alias.\n\nThe implemented contract is:\n\n- the active pane opens the quick bar in `filter` mode\n- the quick bar shows that pane's `currentDirectoryFilter` as a controlled value\n- typing filters the pane's visible file list immediately\n- no dropdown results are shown in this mode\n- `ArrowDown` hands focus from the input into the pane's file list\n- `Escape` clears the filter first, then returns focus to the file list when the input is already empty\n\nThe filter state is pane-local and scoped to the current `connectionId + path`.\n\n- switching between `smart`, `commands`, and `filter` modes does not clear the current directory filter\n- navigating to a different directory clears the filter for the new scope\n- changing the pane's connection also clears the filter for the new scope\n- the status bar remains the persistent reminder that a filter is active even when the quick bar is in another mode\n\n## Current Browser-Level Shortcuts\n\nCurrent browser-level shortcuts include:\n\n- `Ctrl+K`: open smart navigation\n- `Ctrl+Alt+F`: focus current-directory filter mode for the active pane\n- `Ctrl+P`: show commands\n- `Ctrl+,`: open settings\n- `?` or `F1`: show keyboard shortcuts help\n- `Backspace`: go up one directory\n- `Ctrl+R`: refresh file list\n- `F2`: rename focused item\n- `Delete`: delete focused item\n- `F7`: create new directory\n- `Shift+F7`: create new file\n- `Ctrl+Enter`: open focused file in the companion app\n- `Ctrl+B`: toggle dual-pane view\n- `Ctrl+1`: focus left pane\n- `Ctrl+2`: focus right pane\n- `Tab`: switch active pane\n- `F5`: copy to the other pane\n- `F6`: move to the other pane\n\nWhen changing these, treat the behavior as product-level interaction design rather than local implementation detail.\n\n## Focus and Interaction Rules\n\nShortcut work often breaks focus behavior before it breaks functionality. Keep these rules intact:\n\n- opening the quick bar focuses its input immediately\n- selecting a navigation result returns focus to the relevant file list\n- selecting commands that switch quick-bar modes keeps focus inside the quick bar\n- `ArrowDown` from current-directory filter mode moves focus into the filtered file list\n- current-directory filter mode does not open a dropdown for local matches\n- `Escape` in filter mode clears the active filter before it hands focus back to the file list\n- commands that open dialogs or settings do not force focus back to the file list\n- pane-switching shortcuts do not fire while the quick-bar input is focused\n- shortcuts that should work during text entry must explicitly opt in with `allowInInput`\n- shortcuts should be disabled when dialog state or viewer state would make them unsafe\n\n## Context-Aware Shortcut Handling\n\nWhen one key needs different behavior depending on state, prefer one context-aware handler over overlapping registrations.\n\nFor example, `Escape` may close a search panel when that panel is open, but close the viewer when it is not.\n\nThat pattern is better than registering multiple conflicting `Escape` shortcuts because:\n\n- one shortcut definition stays authoritative\n- behavior remains explicit in the component state logic\n- conflicts are easier to reason about and test\n\n### Priority as an Escape Hatch\n\nIn rare cases, multiple handlers for one key are unavoidable. The system supports a `priority` field so higher-priority candidates are evaluated first.\n\nUse that sparingly. A context-aware handler is usually easier to understand and maintain than several competing registrations.\n\n## Adding New Shortcuts Safely\n\nWhen you add a shortcut, keep the workflow centralized.\n\n1. define the shortcut in `config/keyboardShortcuts.ts`\n1. bind it through `useKeyboardShortcuts` in the feature component\n1. reuse the same definition for tooltip or help-surface labels\n1. test both the runtime behavior and the visible affordance\n\nTypical sequence:\n\n```typescript\nexport const PDF_SHORTCUTS = {\n  PRINT: {\n    id: \"print\",\n    keys: \"p\",\n    description: \"Print\",\n    label: \"Ctrl+P\",\n    ctrl: true,\n  },\n} as const;\n```\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...PDF_SHORTCUTS.PRINT,\n      handler: handlePrint,\n    },\n  ],\n});\n```\n\n```typescript\ntitle={withShortcut(PDF_SHORTCUTS.PRINT)}\n```\n\nDo not add one-off tooltip strings or imperative event parsing when the shortcut belongs in the shared system.\n\n## CodeMirror Find and Replace\n\nMarkdown and text editing keep find and replace in an editor-local fixed surface near the upper-right viewport edge, below the viewer toolbar, rather than in the shared viewer toolbar. `MarkdownViewer` and `TextViewer` own the surrounding viewer state and bind `Ctrl+H`, `Alt+C`, `Alt+W`, and `Alt+R` through `CODEMIRROR_EDITOR_SHORTCUTS`. The existing shared `F3` and `Shift+F3` registrations remain the navigation authority, including while a find or replace input has focus. `Enter` and `Ctrl+Alt+Enter` are also declared in that registry for replace-current and replace-all, but their `allowInInputWithin` scope limits them to the replacement field.\n\n`codeMirrorFindReplace.ts` owns the shared `SearchQuery` construction, validity-aware metrics, and auto-navigation logic. `MarkdownRichEditor` and `TextCodeEditor` map the controlled state to that API and use CodeMirror's native `replaceNext` and `replaceAll` commands. Keep replacement operations on those native commands so CodeMirror owns selection updates and undo transactions. Search metrics must check the query validity before creating a cursor because an invalid regular expression cannot produce one.\n\n`CodeMirrorFindReplacePopover` is intentionally non-modal so the editor remains visible and keyboard navigation remains continuous. Its Find and Replace inputs come first in DOM order to preserve the first two tab stops. The history affordance is supplied by the in-field `Search (\u21c5 for history)` and `Replace (\u21c5 for history)` placeholders; result count, match options, navigation, and close controls occupy the first row to the inputs' right. `codeMirrorFindReplaceHistory.ts` persists independent Find and Replace histories in local storage, safely tolerating unavailable or malformed storage and retaining only the ten newest unique non-empty values. Reuse dialog surface tokens for its paper, but do not use `ResponsiveFormDialog`: full-screen viewers retain their specialized focus and layout shell.\n\n## Label Formatting Rules\n\nThe shortcut system also owns display formatting.\n\n- `ArrowRight` becomes `Right`\n- `ArrowLeft` becomes `Left`\n- `ArrowUp` becomes `Up`\n- `ArrowDown` becomes `Down`\n- `Escape` becomes `Esc`\n- space becomes `Space`\n- multiple equivalent keys are joined with ` / `\n- modifiers render as `Ctrl+`, `Shift+`, and `Alt+`\n\nThat formatting should come from the shared system, not from ad hoc component strings.\n\n## Common Failure Modes\n\n- shortcut keys and visible labels drift apart\n- a component registers imperative keyboard logic instead of using the shared hook\n- the browser command palette exposes actions that do not respect the current UI context\n- shortcuts fire while text input or dialog state should block them\n- quick-bar focus returns to the wrong pane in dual-pane workflows\n- multiple overlapping handlers compete for one key instead of using a context-aware handler\n\n## Validation Expectations\n\nWhen keyboard behavior changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change affects file-browser behavior, also test:\n\n- quick-bar navigation and command mode\n- pane switching in dual-pane and single-pane layouts\n- dialog safety for destructive shortcuts\n- viewer shortcut labels and matching runtime behavior\n\nFor new shortcut registrations, also verify:\n\n- the shared label matches the actual bound keys\n- `allowInInput` behavior matches the intended text-entry experience\n- priority and enabled-state logic do not create hidden overlaps\n\n## Where to Continue\n\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL sync, selection, and refresh behavior\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): viewer reuse, preview behavior, and file-type contracts\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): other shared frontend systems contributors should keep centralized\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/frontend-architecture/viewer-architecture-and-preview-contracts", "parent_id": "section:developer-guide/frontend-architecture", "depth": 2, "kind": "page", "label": "viewer-architecture-and-preview-contracts", "title": "Viewer Architecture And Preview Contracts", "path": "developer-guide/frontend-architecture/viewer-architecture-and-preview-contracts", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Viewer Architecture and Preview Contracts\"\n+++\n\nPreview behavior in Sambee is a cross-boundary contract, not just a frontend component choice.\n\n## The Core Contract\n\nThe browser app decides how to render a file based on metadata and file-type information, but that depends on server-side classification staying aligned.\n\nThree rules matter most:\n\n- the backend and frontend file-type registries must describe the same extensions and MIME types\n- the backend decides whether an image format needs server-side conversion for browser compatibility\n- the frontend chooses the right viewer component and file icon based on the effective file type and MIME information it receives\n\n## Where the Main Decisions Live\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | backend source of truth for extensions, MIME types, categories, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | frontend source of truth for extensions, MIME types, categories, viewer components, icons, and colors |\n| `frontend/src/components/Viewer/` | viewer components and shared viewer UI |\n| `backend/app/services/image_converter.py` | server-side conversion for non-browser-native image formats |\n\n## Viewer Selection Model\n\nAt a high level, the preview pipeline works like this:\n\n1. the backend determines file category and MIME behavior\n2. the backend decides whether the file can stream as-is or needs image conversion\n3. the frontend maps the file type to the appropriate viewer component\n4. the shared viewer controls keep the toolbar and common behavior consistent across viewers\n\nThat is why a file-type change almost always touches both backend and frontend code.\n\n## Browser-Native Versus Server-Converted Images\n\nSambee supports both browser-native formats and formats that need server-side conversion.\n\n- browser-native formats can be sent to the viewer directly\n- non-browser-native image formats are converted on the server before the browser renders them\n- special cases such as transparency preservation can change the output format choice\n\nIf you change conversion rules, you are changing a product contract, not just an implementation detail.\n\n### Server-Side Conversion Contract\n\nThe conversion path is owned by `backend/app/services/image_converter.py` and is exercised through the viewer API.\n\nThe backend conversion service is responsible for:\n\n- deciding whether an image needs processing\n- converting unsupported or impractical browser formats into a viewer-safe output format\n- preserving transparency where the output contract requires it\n- applying optional downscaling so one preview request cannot explode memory usage casually\n- returning enough metadata for the viewer endpoint to send the correct MIME type back to the browser\n\nRepresentative service responsibilities include:\n\n- `needs_processing(filename)`\n- `convert_image_for_viewer(...)`\n- `is_image_file(filename)`\n- `get_image_info(...)`\n\nThe viewer endpoint then follows this rule:\n\n- if the image can stream safely as-is, return a streaming response\n- if it requires conversion, read it, convert it, and return the converted bytes with the converted MIME type\n\nThat means preview behavior for formats such as TIFF, HEIC, BMP, ICO, and similar formats depends on backend conversion policy, not just on frontend MIME recognition.\n\n### Local-Drive Preview Policy\n\nThe Companion serves local-drive files and archive members as raw bytes. It does not copy local content to the backend for processing and does not bundle the backend image or PDF processing stack.\n\n- Browser-native images, text files, and original PDFs can preview from their raw local bytes.\n- Image formats that require server-side conversion, such as TIFF, HEIC, PSD, JPEG XL, and scientific image formats, show an explicit preview-unavailable state for local drives.\n- Image resizing and PDF compatibility normalization are unavailable for local drives.\n- Downloading and opening the original file locally remain available when a local preview is unavailable.\n\nThe frontend resolves these capabilities before making a local viewer request. Local archive-member requests use the Companion's strict raw-stream contract, while SMB archive-member requests retain the full conversion and PDF-normalization request parameters.\n\n### Output Format Rules\n\nThe backend does not always convert everything to the same output type.\n\n- JPEG is the common output for opaque images\n- PNG remains important when transparency must be preserved\n- ICO-like transparency handling is therefore different from ordinary opaque-photo conversion\n- alpha-bearing formats converted to JPEG need explicit compositing behavior rather than silent accidental loss\n\nIf you change those rules, check both visual correctness and user-facing assumptions such as download behavior and gallery continuity.\n\n### Current Format-Specific Preview Semantics\n\nSeveral converted-image families have product-specific preview semantics that contributors should preserve unless the product intentionally changes.\n\n- multi-page TIFF currently previews the first page rather than exposing a document-style page stack\n- PSD and PSB preview the flattened composite instead of surfacing layer-edit semantics through the browser viewer\n- EPS and AI are rasterized through the preprocessing path at high quality, currently using the 300 DPI rendering baseline\n- HDR-oriented formats such as EXR and Radiance HDR are tone-mapped into ordinary browser-display output\n- whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF preview as an overview or first practical pyramid level rather than as a full pathology viewer\n- FITS and similar scientific-image formats apply visibility scaling so low-level pixel values become inspectable in a normal browser image surface\n\nThese are not accidental implementation details. They define what users should expect from preview and therefore belong to the product contract.\n\n### Resizing and Resource Limits\n\nServer-side conversion can consume significant memory because the file must be read, decoded, and re-encoded.\n\nThe current contract therefore includes:\n\n- configurable JPEG-quality behavior\n- maximum-dimension downscaling to avoid unbounded preview size\n- backend-side protection against excessive memory usage from large source images\n\nContributors should treat those limits as operational safety controls, not as arbitrary defaults.\n\n### Dependency and Environment Expectations\n\nThe conversion path depends on reviewed Python and system-image libraries.\n\nThat includes the normal image stack plus HEIC/HEIF support through the reviewed dependency chain and corresponding system libraries in the container or runtime image.\n\nWhen conversion support seems to disappear unexpectedly, check:\n\n- the backend Python dependency set\n- the container or host system-image libraries\n- whether the format-specific support was actually installed in the current environment\n\n### Preprocessor Registry for Exotic Formats\n\nSome formats need a preprocessing step before the normal conversion path can handle them at all.\n\nThat registry lives in:\n\n- `backend/app/services/preprocessor.py`\n\nIt is consumed by:\n\n- `backend/app/services/image_converter.py`\n\nThe preprocessor layer exists for formats that libvips should not or cannot decode directly for Sambee's preview contract.\n\nCurrent registered formats route through the ImageMagick-backed preprocessor:\n\n- `.psd`\n- `.psb`\n- `.eps`\n- `.ai`\n\nThe registry is the single source of truth for which extensions require preprocessing before the final viewer-safe conversion step.\n\nFor the backend service architecture behind that path, continue to [Image Preprocessing and Conversion Pipeline](../../backend-architecture/image-preprocessing-and-conversion-pipeline/).\n\nRepresentative registry operations include:\n\n- `PreprocessorRegistry.requires_preprocessing(extension)`\n- `PreprocessorRegistry.get_preprocessor_for_format(extension)`\n- `PreprocessorRegistry.get_supported_formats()`\n- `PreprocessorRegistry.register_format(extension, preprocessor_class)`\n\n### Preprocessor Design Rules\n\nThe preprocessor layer has its own constraints:\n\n- one registry entry per preprocessable extension\n- direct in-memory conversion to the final browser-ready format rather than chained intermediate formats\n- no shell-mediated fallback chain logic in the registry itself\n- input validation and timeout enforcement happen in the preprocessor layer\n- failures should surface as explicit preprocessing or conversion errors rather than silent format drift\n\nThe main abstraction is `PreprocessorInterface`, with `ImageMagickPreprocessor` as the current built-in implementation.\n\n### Adding a New Preprocessed Format\n\nIf a new format cannot be handled by the normal conversion stack directly:\n\n1. implement a `PreprocessorInterface` subclass if the existing preprocessor is not appropriate\n2. register the extension in `PreprocessorRegistry`\n3. add or update file-type metadata if the format becomes user-visible in preview flows\n4. add tests for format recognition, tool availability, validation, and successful conversion\n\nDo not treat preprocessable formats as ordinary file-type additions. They change the backend conversion pipeline itself.\n\n### Error Surface Contributors Must Preserve\n\nConversion failures are user-visible API behavior, not internal-only exceptions.\n\nTypical outcomes include:\n\n- not implemented when the current environment lacks support for a format family\n- unprocessable-content style failures when the file is corrupt or cannot be decoded\n- ordinary backend failures when an unexpected exception escapes the conversion path\n\nThat means error wording, status behavior, and frontend fallback behavior should be reviewed together.\n\n## Shared Viewer UI\n\nThe main viewer toolbar is intentionally centralized in `frontend/src/components/Viewer/ViewerControls.tsx`.\n\nThis is no longer just an image-and-PDF convenience component. It is the canonical control surface for the current full-screen image, PDF, and Markdown viewers.\n\n- shared toolbar layout, styling, keyboard-tooltip behavior, and responsive behavior live in `ViewerControls`\n- each viewer turns features on through configuration and passes only the state objects it needs\n- future viewers should reuse that control shell where possible instead of creating another top-level toolbar implementation\n\n### Control-Surface Model\n\n`ViewerControls` uses a feature-flag configuration plus typed state objects.\n\nThe configuration currently enables these capability groups:\n\n- `navigation` for gallery-style previous and next navigation\n- `pageNavigation` for PDF page input and page stepping\n- `zoom` for viewer-managed zoom actions\n- `rotation` for image and PDF rotation actions\n- `search` for the shared search row and match navigation affordances\n- `download` for explicit download actions\n- `share` for mobile-first share actions\n\nThe component then accepts matching state surfaces:\n\n- `NavigationState` for item index, total items, and next or previous handlers\n- `PageNavigationState` for current page, total pages, and page-change handling\n- `ZoomState` for zoom-in and zoom-out handlers\n- `RotationState` for rotate-left and rotate-right handlers\n- `SearchState` for search text, match counts, search-panel state, open or close callbacks, and viewer-specific search navigation\n\nThat split matters because `ViewerControls` owns the common UI, but it does not own viewer logic. It renders controls and delegates behavior back to the viewer that actually knows how to navigate pages, zoom, rotate, or search.\n\n### Current Consumers\n\nThe current shared-toolbar consumers are:\n\n- `ImageViewer`, which enables gallery navigation, zoom, rotation, download, and optional mobile share\n- `PDFViewer`, which enables page navigation, zoom, rotation, search, download, and optional mobile share\n- `MarkdownViewer`, which reuses the same shell for download, optional mobile share, shared search UI, and viewer-specific action buttons such as editing flows\n\n`ViewerControls` also supports generic toolbar actions through the `actions` prop, which can render either text buttons or icon buttons. That is what allows Markdown-specific actions to live inside the same shared toolbar instead of forcing a second toolbar implementation.\n\n### Search UI Versus Search Engine\n\nThe search row is shared, but the search backend is viewer-specific.\n\n- `PDFViewer` wires the search controls to PDF text extraction, page-aware match tracking, and PDF-specific next or previous navigation\n- rendered Markdown and other rendered text views can route search through the DOM text-search utility in `frontend/src/utils/domTextSearch.ts`\n- Markdown edit mode does not reuse the rendered-view DOM search implementation; it bridges the same outer toolbar UI into the editor-specific search state and commands instead\n\nThat separation is an important contract: contributors should reuse the shared search UI when possible, but should not assume every viewer can use the same search implementation under the hood.\n\n### Responsive and Accessibility Rules\n\nThe centralized toolbar also encodes product behavior that should stay consistent across viewers.\n\n- filename display, optional filename adornments, and close behavior are shared\n- mobile layout uses safe-area-aware spacing and smaller controls\n- gallery arrows and desktop zoom controls are intentionally reduced on mobile, where gesture-based interaction is preferred\n- share is exposed as a mobile-first affordance, with optional early-intent warming through `onShareIntent`\n- buttons use explicit `aria-label` values and shortcut-oriented `title` text so the control surface remains navigable and self-describing\n- the shared search row manages focus when it opens and preserves consistent close behavior for toggle and Escape-driven exits\n\n### Legacy Components and Contributor Guidance\n\nLegacy `ImageControls.tsx` and `PDFControls.tsx` files still exist in the frontend tree, but `ViewerControls` is the current architectural direction and the shared component used by the active image, PDF, and Markdown viewers.\n\nIf you add another viewer or extend an existing one:\n\n- prefer extending `ViewerControlsConfig`, the relevant state interfaces, or the generic `actions` surface\n- keep viewer-specific logic in the viewer component rather than teaching `ViewerControls` about file-format internals\n- preserve shared mobile, accessibility, and search-panel behavior unless the product intentionally changes that contract\n- add or update focused tests in `frontend/src/components/Viewer/__tests__/ViewerControls.test.tsx` when the shared toolbar contract changes\n\n## Adding a New File Type Safely\n\nFile-type support is registry-driven. The safest way to add a new type is to treat backend and frontend changes as one contract update.\n\n### Main Files to Change\n\n| Path | Why it changes |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | declare extensions, MIME types, category, description, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | declare extensions, MIME types, category, viewer component, icon, color, and description |\n| `frontend/src/components/Viewer/` | add or reuse a viewer component when the type needs a dedicated preview surface |\n\nIf a file type is user-visible, update the published support docs that describe what Sambee can preview.\n\n### Quick Start for a New Image Format\n\nFor an image format such as JPEG XL, the minimum workflow is:\n\n1. add a `FileTypeDefinition` entry to the backend registry\n2. add the matching entry to the frontend registry\n3. decide whether the image is browser-native or requires server-side conversion\n4. keep extensions and MIME types identical across both registries\n5. run the viewer and backend validation checks\n\nBackend example:\n\n```python\nFileTypeDefinition(\n\t\textensions=(\".jxl\",),\n\t\tmime_types=(\"image/jxl\",),\n\t\tcategory=FileCategory.IMAGE,\n\t\trequires_conversion=True,\n\t\tdescription=\"JPEG XL Image\",\n)\n```\n\nFrontend example:\n\n```typescript\n{\n\textensions: [\".jxl\"],\n\tmimeTypes: [\"image/jxl\"],\n\tcategory: \"image\",\n\tviewerComponent: () =\u003e import(\"../components/Viewer/ImageViewer\"),\n\ticon: \"image\",\n\tcolor: \"#a855f7\",\n\tdescription: \"JPEG XL Image\",\n}\n```\n\nThat registry update is what drives MIME matching, icon treatment, viewer routing, and image-gallery inclusion.\n\n### Backend Registry Rules\n\nBackend file-type definitions must stay explicit and type-safe.\n\n- `extensions` are tuples with a leading dot, such as `(\".jpg\", \".jpeg\")`\n- `mime_types` are tuples of standard MIME strings\n- `category` uses `FileCategory` values such as `IMAGE`, `DOCUMENT`, `TEXT`, `VIDEO`, `AUDIO`, `ARCHIVE`, `CODE`, `SPREADSHEET`, or `OTHER`\n- `requires_conversion` matters for image formats that cannot be rendered directly by the browser\n- `description` should be the human-readable label contributors and users would expect\n\nHow to decide `requires_conversion`:\n\n- set it to `False` for browser-native formats such as PNG, JPEG, GIF, WebP, SVG, and AVIF\n- set it to `True` for formats with limited browser support or formats that are not practical to render directly, such as TIFF, HEIC, BMP, JPEG 2000, or JPEG XL when browser support is not sufficient for the product baseline\n\n### Frontend Registry Rules\n\nFrontend file-type definitions control how the browser app presents the file.\n\n- keep `extensions` and `mimeTypes` aligned with the backend registry\n- set `viewerComponent` to the shared viewer that should render the type\n- choose an icon that matches the product language for that file category\n- choose a color that distinguishes the format without inventing a new palette on every addition\n\nFor image formats, reusing `ImageViewer` is usually enough. For non-image formats, you may need a dedicated viewer such as `PdfViewer`, `VideoViewer`, `AudioViewer`, or `TextViewer`.\n\n### Non-Image File Types\n\nThe overall process is the same for documents, video, audio, text, archives, and code files.\n\n1. add the backend registry entry\n2. add the frontend registry entry\n3. create or reuse the viewer component when preview support exists\n4. verify the file icon, viewer routing, and download behavior\n\nFor non-image files, `requires_conversion` is usually `False`. The main design question is whether the product has a viewer component for that category or should fall back to download-only behavior.\n\n### Integration Checklist\n\nUse this checklist before you consider the file type integrated:\n\n- backend registry entry added\n- frontend registry entry added\n- extensions and MIME types match exactly across both registries\n- browser-native versus converted-image behavior decided intentionally\n- viewer component chosen or added\n- icon and color treatment chosen\n- user-visible support docs updated if the file type changes what Sambee can preview\n\n### Testing Checklist\n\nAfter the registry change, verify:\n\n- icon display in the file browser\n- file opening in the expected viewer\n- shared toolbar behavior if the preview uses `ViewerControls`\n- conversion output if the format is server-converted\n- gallery inclusion for image formats\n- MIME type behavior across extension variants such as upper-case filenames\n- download behavior with the correct MIME type\n- mobile and tablet behavior when the preview is expected to work there\n\nFor server-converted formats, also verify:\n\n- the backend returns the converted MIME type you expect\n- transparency-sensitive formats still render correctly\n- resizing or quality settings do not degrade the preview contract unexpectedly\n- environment-specific format support failures surface in a controlled way\n\nFor preprocessable formats, also verify:\n\n- the registry recognizes the extension regardless of case and leading-dot differences\n- the expected preprocessor is selected for that format\n- missing external-tool support fails cleanly\n- validation and timeout rules behave as intended under bad inputs and slow conversions\n\n### Architecture Notes\n\nThese helper functions are the practical integration points contributors usually touch:\n\n- backend: `get_mime_type`, `needs_processing`, `is_image_file`, `get_file_type_by_extension`, `get_file_type_by_mime`\n- frontend: `getViewerComponent`, `isImageFile`, `getFileIcon`, `getFileTypeByExtension`, `getFileTypeByMime`\n\nAt runtime, the flow is:\n\n1. the backend lists files and assigns MIME information\n2. the frontend receives `FileInfo` data with that MIME information\n3. the frontend chooses icon treatment from filename and type rules\n4. the frontend selects the viewer from MIME and file-type data\n5. the backend routes convertible images through the image-conversion pipeline when needed\n\nThe frontend side still has work to do even when the backend owns the conversion:\n\n- viewer MIME recognition must include the input formats the backend classifies as previewable\n- file-type icon and color treatment must still reflect the original file type rather than the converted transport format\n- browser-side fallback MIME logic must not drift from the backend contract in ways that hide conversion bugs\n\n### Operational Characteristics\n\nServer-side conversion changes the runtime profile of preview requests.\n\n- large images can produce short CPU spikes during decode and encode\n- memory usage can rise well above compressed input size while the image is fully decoded\n- SMB-backed reads add their own latency before conversion even starts\n\nThat is why preview regressions for large HEIC or TIFF files often need both backend and user-facing verification.\n\n### Future Extension Points\n\nThe current conversion path leaves room for later enhancements such as:\n\n- caching converted preview outputs\n- queueing especially large conversions\n- dedicated thumbnail generation\n- richer multi-page image handling\n- conversion metrics for operational monitoring\n\nThose are extension points, not assumptions the current product already guarantees.\n\nThe highest-risk mistake is still registry drift. If the backend and frontend disagree about extensions or MIME types, preview behavior becomes unreliable in ways that are easy to miss until users hit them.\n\n## Common Failure Modes\n\n- backend and frontend MIME types do not match\n- a format is marked browser-native when it really needs conversion\n- a viewer component is not registered even though the type is recognized\n- a conversion change improves one format but breaks gallery behavior, download semantics, or mobile viewing\n\n## Validation Expectations\n\nWhen you change viewer or file-type behavior, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd backend \u0026\u0026 pytest -v\n```\n\nIf the change is image-conversion-specific, include the relevant backend tests around image conversion and preview behavior.\n", "0.8": "+++\ntitle = \"Viewer Architecture and Preview Contracts\"\n+++\n\nPreview behavior in Sambee is a cross-boundary contract, not just a frontend component choice.\n\n## The Core Contract\n\nThe browser app decides how to render a file based on metadata and file-type information, but that depends on server-side classification staying aligned.\n\nThree rules matter most:\n\n- the backend and frontend file-type registries must describe the same extensions and MIME types\n- the backend decides whether an image format needs server-side conversion for browser compatibility\n- the frontend chooses the right viewer component and file icon based on the effective file type and MIME information it receives\n\n## Where the Main Decisions Live\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | backend source of truth for extensions, MIME types, categories, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | frontend source of truth for extensions, MIME types, categories, viewer components, icons, and colors |\n| `frontend/src/components/Viewer/` | viewer components and shared viewer UI |\n| `backend/app/services/image_converter.py` | server-side conversion for non-browser-native image formats |\n\n## Viewer Selection Model\n\nAt a high level, the preview pipeline works like this:\n\n1. the backend determines file category and MIME behavior\n2. the backend decides whether the file can stream as-is or needs image conversion\n3. the frontend maps the file type to the appropriate viewer component\n4. the shared viewer controls keep the toolbar and common behavior consistent across viewers\n\nThat is why a file-type change almost always touches both backend and frontend code.\n\n## Browser-Native Versus Server-Converted Images\n\nSambee supports both browser-native formats and formats that need server-side conversion.\n\n- browser-native formats can be sent to the viewer directly\n- non-browser-native image formats are converted on the server before the browser renders them\n- special cases such as transparency preservation can change the output format choice\n\nIf you change conversion rules, you are changing a product contract, not just an implementation detail.\n\n### Server-Side Conversion Contract\n\nThe conversion path is owned by `backend/app/services/image_converter.py` and is exercised through the viewer API.\n\nThe backend conversion service is responsible for:\n\n- deciding whether an image needs processing\n- converting unsupported or impractical browser formats into a viewer-safe output format\n- preserving transparency where the output contract requires it\n- applying optional downscaling so one preview request cannot explode memory usage casually\n- returning enough metadata for the viewer endpoint to send the correct MIME type back to the browser\n\nRepresentative service responsibilities include:\n\n- `needs_processing(filename)`\n- `convert_image_for_viewer(...)`\n- `is_image_file(filename)`\n- `get_image_info(...)`\n\nThe viewer endpoint then follows this rule:\n\n- if the image can stream safely as-is, return a streaming response\n- if it requires conversion, read it, convert it, and return the converted bytes with the converted MIME type\n\nThat means preview behavior for formats such as TIFF, HEIC, BMP, ICO, and similar formats depends on backend conversion policy, not just on frontend MIME recognition.\n\n### Local-Drive Preview Policy\n\nThe Companion serves local-drive files and archive members as raw bytes. It does not copy local content to the backend for processing and does not bundle the backend image or PDF processing stack.\n\n- Browser-native images, text files, and original PDFs can preview from their raw local bytes.\n- Image formats that require server-side conversion, such as TIFF, HEIC, PSD, JPEG XL, and scientific image formats, show an explicit preview-unavailable state for local drives.\n- Image resizing and PDF compatibility normalization are unavailable for local drives.\n- Downloading and opening the original file locally remain available when a local preview is unavailable.\n\nThe frontend resolves these capabilities before making a local viewer request. Local archive-member requests use the Companion's strict raw-stream contract, while SMB archive-member requests retain the full conversion and PDF-normalization request parameters.\n\n### Output Format Rules\n\nThe backend does not always convert everything to the same output type.\n\n- JPEG is the common output for opaque images\n- PNG remains important when transparency must be preserved\n- ICO-like transparency handling is therefore different from ordinary opaque-photo conversion\n- alpha-bearing formats converted to JPEG need explicit compositing behavior rather than silent accidental loss\n\nIf you change those rules, check both visual correctness and user-facing assumptions such as download behavior and gallery continuity.\n\n### Current Format-Specific Preview Semantics\n\nSeveral converted-image families have product-specific preview semantics that contributors should preserve unless the product intentionally changes.\n\n- multi-page TIFF currently previews the first page rather than exposing a document-style page stack\n- PSD and PSB preview the flattened composite instead of surfacing layer-edit semantics through the browser viewer\n- EPS and AI are rasterized through the preprocessing path at high quality, currently using the 300 DPI rendering baseline\n- HDR-oriented formats such as EXR and Radiance HDR are tone-mapped into ordinary browser-display output\n- whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF preview as an overview or first practical pyramid level rather than as a full pathology viewer\n- FITS and similar scientific-image formats apply visibility scaling so low-level pixel values become inspectable in a normal browser image surface\n\nThese are not accidental implementation details. They define what users should expect from preview and therefore belong to the product contract.\n\n### Resizing and Resource Limits\n\nServer-side conversion can consume significant memory because the file must be read, decoded, and re-encoded.\n\nThe current contract therefore includes:\n\n- configurable JPEG-quality behavior\n- maximum-dimension downscaling to avoid unbounded preview size\n- backend-side protection against excessive memory usage from large source images\n\nContributors should treat those limits as operational safety controls, not as arbitrary defaults.\n\n### Dependency and Environment Expectations\n\nThe conversion path depends on reviewed Python and system-image libraries.\n\nThat includes the normal image stack plus HEIC/HEIF support through the reviewed dependency chain and corresponding system libraries in the container or runtime image.\n\nWhen conversion support seems to disappear unexpectedly, check:\n\n- the backend Python dependency set\n- the container or host system-image libraries\n- whether the format-specific support was actually installed in the current environment\n\n### Preprocessor Registry for Exotic Formats\n\nSome formats need a preprocessing step before the normal conversion path can handle them at all.\n\nThat registry lives in:\n\n- `backend/app/services/preprocessor.py`\n\nIt is consumed by:\n\n- `backend/app/services/image_converter.py`\n\nThe preprocessor layer exists for formats that libvips should not or cannot decode directly for Sambee's preview contract.\n\nCurrent registered formats route through the ImageMagick-backed preprocessor:\n\n- `.psd`\n- `.psb`\n- `.eps`\n- `.ai`\n\nThe registry is the single source of truth for which extensions require preprocessing before the final viewer-safe conversion step.\n\nFor the backend service architecture behind that path, continue to [Image Preprocessing and Conversion Pipeline](../../backend-architecture/image-preprocessing-and-conversion-pipeline/).\n\nRepresentative registry operations include:\n\n- `PreprocessorRegistry.requires_preprocessing(extension)`\n- `PreprocessorRegistry.get_preprocessor_for_format(extension)`\n- `PreprocessorRegistry.get_supported_formats()`\n- `PreprocessorRegistry.register_format(extension, preprocessor_class)`\n\n### Preprocessor Design Rules\n\nThe preprocessor layer has its own constraints:\n\n- one registry entry per preprocessable extension\n- direct in-memory conversion to the final browser-ready format rather than chained intermediate formats\n- no shell-mediated fallback chain logic in the registry itself\n- input validation and timeout enforcement happen in the preprocessor layer\n- failures should surface as explicit preprocessing or conversion errors rather than silent format drift\n\nThe main abstraction is `PreprocessorInterface`, with `ImageMagickPreprocessor` as the current built-in implementation.\n\n### Adding a New Preprocessed Format\n\nIf a new format cannot be handled by the normal conversion stack directly:\n\n1. implement a `PreprocessorInterface` subclass if the existing preprocessor is not appropriate\n2. register the extension in `PreprocessorRegistry`\n3. add or update file-type metadata if the format becomes user-visible in preview flows\n4. add tests for format recognition, tool availability, validation, and successful conversion\n\nDo not treat preprocessable formats as ordinary file-type additions. They change the backend conversion pipeline itself.\n\n### Error Surface Contributors Must Preserve\n\nConversion failures are user-visible API behavior, not internal-only exceptions.\n\nTypical outcomes include:\n\n- not implemented when the current environment lacks support for a format family\n- unprocessable-content style failures when the file is corrupt or cannot be decoded\n- ordinary backend failures when an unexpected exception escapes the conversion path\n\nThat means error wording, status behavior, and frontend fallback behavior should be reviewed together.\n\n## Shared Viewer UI\n\nThe main viewer toolbar is intentionally centralized in `frontend/src/components/Viewer/ViewerControls.tsx`.\n\nThis is no longer just an image-and-PDF convenience component. It is the canonical control surface for the current full-screen image, PDF, and Markdown viewers.\n\n- shared toolbar layout, styling, keyboard-tooltip behavior, and responsive behavior live in `ViewerControls`\n- each viewer turns features on through configuration and passes only the state objects it needs\n- future viewers should reuse that control shell where possible instead of creating another top-level toolbar implementation\n\n### Control-Surface Model\n\n`ViewerControls` uses a feature-flag configuration plus typed state objects.\n\nThe configuration currently enables these capability groups:\n\n- `navigation` for gallery-style previous and next navigation\n- `pageNavigation` for PDF page input and page stepping\n- `zoom` for viewer-managed zoom actions\n- `rotation` for image and PDF rotation actions\n- `search` for the shared search row and match navigation affordances\n- `download` for explicit download actions\n- `share` for mobile-first share actions\n\nThe component then accepts matching state surfaces:\n\n- `NavigationState` for item index, total items, and next or previous handlers\n- `PageNavigationState` for current page, total pages, and page-change handling\n- `ZoomState` for zoom-in and zoom-out handlers\n- `RotationState` for rotate-left and rotate-right handlers\n- `SearchState` for search text, match counts, search-panel state, open or close callbacks, and viewer-specific search navigation\n\nThat split matters because `ViewerControls` owns the common UI, but it does not own viewer logic. It renders controls and delegates behavior back to the viewer that actually knows how to navigate pages, zoom, rotate, or search.\n\n### Current Consumers\n\nThe current shared-toolbar consumers are:\n\n- `ImageViewer`, which enables gallery navigation, zoom, rotation, download, and optional mobile share\n- `PDFViewer`, which enables page navigation, zoom, rotation, search, download, and optional mobile share\n- `MarkdownViewer`, which reuses the same shell for download, optional mobile share, shared search UI, and viewer-specific action buttons such as editing flows\n\n`ViewerControls` also supports generic toolbar actions through the `actions` prop, which can render either text buttons or icon buttons. That is what allows Markdown-specific actions to live inside the same shared toolbar instead of forcing a second toolbar implementation.\n\n### Search UI Versus Search Engine\n\nThe search row is shared, but the search backend is viewer-specific.\n\n- `PDFViewer` wires the search controls to PDF text extraction, page-aware match tracking, and PDF-specific next or previous navigation\n- rendered Markdown and other rendered text views can route search through the DOM text-search utility in `frontend/src/utils/domTextSearch.ts`\n- Markdown edit mode does not reuse the rendered-view DOM search implementation; it bridges the same outer toolbar UI into the editor-specific search state and commands instead\n\nThat separation is an important contract: contributors should reuse the shared search UI when possible, but should not assume every viewer can use the same search implementation under the hood.\n\n### Responsive and Accessibility Rules\n\nThe centralized toolbar also encodes product behavior that should stay consistent across viewers.\n\n- filename display, optional filename adornments, and close behavior are shared\n- mobile layout uses safe-area-aware spacing and smaller controls\n- gallery arrows and desktop zoom controls are intentionally reduced on mobile, where gesture-based interaction is preferred\n- share is exposed as a mobile-first affordance, with optional early-intent warming through `onShareIntent`\n- buttons use explicit `aria-label` values and shortcut-oriented `title` text so the control surface remains navigable and self-describing\n- the shared search row manages focus when it opens and preserves consistent close behavior for toggle and Escape-driven exits\n\n### Legacy Components and Contributor Guidance\n\nLegacy `ImageControls.tsx` and `PDFControls.tsx` files still exist in the frontend tree, but `ViewerControls` is the current architectural direction and the shared component used by the active image, PDF, and Markdown viewers.\n\nIf you add another viewer or extend an existing one:\n\n- prefer extending `ViewerControlsConfig`, the relevant state interfaces, or the generic `actions` surface\n- keep viewer-specific logic in the viewer component rather than teaching `ViewerControls` about file-format internals\n- preserve shared mobile, accessibility, and search-panel behavior unless the product intentionally changes that contract\n- add or update focused tests in `frontend/src/components/Viewer/__tests__/ViewerControls.test.tsx` when the shared toolbar contract changes\n\n## Adding a New File Type Safely\n\nFile-type support is registry-driven. The safest way to add a new type is to treat backend and frontend changes as one contract update.\n\n### Main Files to Change\n\n| Path | Why it changes |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | declare extensions, MIME types, category, description, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | declare extensions, MIME types, category, viewer component, icon, color, and description |\n| `frontend/src/components/Viewer/` | add or reuse a viewer component when the type needs a dedicated preview surface |\n\nIf a file type is user-visible, update the published support docs that describe what Sambee can preview.\n\n### Quick Start for a New Image Format\n\nFor an image format such as JPEG XL, the minimum workflow is:\n\n1. add a `FileTypeDefinition` entry to the backend registry\n2. add the matching entry to the frontend registry\n3. decide whether the image is browser-native or requires server-side conversion\n4. keep extensions and MIME types identical across both registries\n5. run the viewer and backend validation checks\n\nBackend example:\n\n```python\nFileTypeDefinition(\n\t\textensions=(\".jxl\",),\n\t\tmime_types=(\"image/jxl\",),\n\t\tcategory=FileCategory.IMAGE,\n\t\trequires_conversion=True,\n\t\tdescription=\"JPEG XL Image\",\n)\n```\n\nFrontend example:\n\n```typescript\n{\n\textensions: [\".jxl\"],\n\tmimeTypes: [\"image/jxl\"],\n\tcategory: \"image\",\n\tviewerComponent: () =\u003e import(\"../components/Viewer/ImageViewer\"),\n\ticon: \"image\",\n\tcolor: \"#a855f7\",\n\tdescription: \"JPEG XL Image\",\n}\n```\n\nThat registry update is what drives MIME matching, icon treatment, viewer routing, and image-gallery inclusion.\n\n### Backend Registry Rules\n\nBackend file-type definitions must stay explicit and type-safe.\n\n- `extensions` are tuples with a leading dot, such as `(\".jpg\", \".jpeg\")`\n- `mime_types` are tuples of standard MIME strings\n- `category` uses `FileCategory` values such as `IMAGE`, `DOCUMENT`, `TEXT`, `VIDEO`, `AUDIO`, `ARCHIVE`, `CODE`, `SPREADSHEET`, or `OTHER`\n- `requires_conversion` matters for image formats that cannot be rendered directly by the browser\n- `description` should be the human-readable label contributors and users would expect\n\nHow to decide `requires_conversion`:\n\n- set it to `False` for browser-native formats such as PNG, JPEG, GIF, WebP, SVG, and AVIF\n- set it to `True` for formats with limited browser support or formats that are not practical to render directly, such as TIFF, HEIC, BMP, JPEG 2000, or JPEG XL when browser support is not sufficient for the product baseline\n\n### Frontend Registry Rules\n\nFrontend file-type definitions control how the browser app presents the file.\n\n- keep `extensions` and `mimeTypes` aligned with the backend registry\n- set `viewerComponent` to the shared viewer that should render the type\n- choose an icon that matches the product language for that file category\n- choose a color that distinguishes the format without inventing a new palette on every addition\n\nFor image formats, reusing `ImageViewer` is usually enough. For non-image formats, you may need a dedicated viewer such as `PdfViewer`, `VideoViewer`, `AudioViewer`, or `TextViewer`.\n\n### Non-Image File Types\n\nThe overall process is the same for documents, video, audio, text, archives, and code files.\n\n1. add the backend registry entry\n2. add the frontend registry entry\n3. create or reuse the viewer component when preview support exists\n4. verify the file icon, viewer routing, and download behavior\n\nFor non-image files, `requires_conversion` is usually `False`. The main design question is whether the product has a viewer component for that category or should fall back to download-only behavior.\n\n### Integration Checklist\n\nUse this checklist before you consider the file type integrated:\n\n- backend registry entry added\n- frontend registry entry added\n- extensions and MIME types match exactly across both registries\n- browser-native versus converted-image behavior decided intentionally\n- viewer component chosen or added\n- icon and color treatment chosen\n- user-visible support docs updated if the file type changes what Sambee can preview\n\n### Testing Checklist\n\nAfter the registry change, verify:\n\n- icon display in the file browser\n- file opening in the expected viewer\n- shared toolbar behavior if the preview uses `ViewerControls`\n- conversion output if the format is server-converted\n- gallery inclusion for image formats\n- MIME type behavior across extension variants such as upper-case filenames\n- download behavior with the correct MIME type\n- mobile and tablet behavior when the preview is expected to work there\n\nFor server-converted formats, also verify:\n\n- the backend returns the converted MIME type you expect\n- transparency-sensitive formats still render correctly\n- resizing or quality settings do not degrade the preview contract unexpectedly\n- environment-specific format support failures surface in a controlled way\n\nFor preprocessable formats, also verify:\n\n- the registry recognizes the extension regardless of case and leading-dot differences\n- the expected preprocessor is selected for that format\n- missing external-tool support fails cleanly\n- validation and timeout rules behave as intended under bad inputs and slow conversions\n\n### Architecture Notes\n\nThese helper functions are the practical integration points contributors usually touch:\n\n- backend: `get_mime_type`, `needs_processing`, `is_image_file`, `get_file_type_by_extension`, `get_file_type_by_mime`\n- frontend: `getViewerComponent`, `isImageFile`, `getFileIcon`, `getFileTypeByExtension`, `getFileTypeByMime`\n\nAt runtime, the flow is:\n\n1. the backend lists files and assigns MIME information\n2. the frontend receives `FileInfo` data with that MIME information\n3. the frontend chooses icon treatment from filename and type rules\n4. the frontend selects the viewer from MIME and file-type data\n5. the backend routes convertible images through the image-conversion pipeline when needed\n\nThe frontend side still has work to do even when the backend owns the conversion:\n\n- viewer MIME recognition must include the input formats the backend classifies as previewable\n- file-type icon and color treatment must still reflect the original file type rather than the converted transport format\n- browser-side fallback MIME logic must not drift from the backend contract in ways that hide conversion bugs\n\n### Operational Characteristics\n\nServer-side conversion changes the runtime profile of preview requests.\n\n- large images can produce short CPU spikes during decode and encode\n- memory usage can rise well above compressed input size while the image is fully decoded\n- SMB-backed reads add their own latency before conversion even starts\n\nThat is why preview regressions for large HEIC or TIFF files often need both backend and user-facing verification.\n\n### Future Extension Points\n\nThe current conversion path leaves room for later enhancements such as:\n\n- caching converted preview outputs\n- queueing especially large conversions\n- dedicated thumbnail generation\n- richer multi-page image handling\n- conversion metrics for operational monitoring\n\nThose are extension points, not assumptions the current product already guarantees.\n\nThe highest-risk mistake is still registry drift. If the backend and frontend disagree about extensions or MIME types, preview behavior becomes unreliable in ways that are easy to miss until users hit them.\n\n## Common Failure Modes\n\n- backend and frontend MIME types do not match\n- a format is marked browser-native when it really needs conversion\n- a viewer component is not registered even though the type is recognized\n- a conversion change improves one format but breaks gallery behavior, download semantics, or mobile viewing\n\n## Validation Expectations\n\nWhen you change viewer or file-type behavior, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd backend \u0026\u0026 pytest -v\n```\n\nIf the change is image-conversion-specific, include the relevant backend tests around image conversion and preview behavior.\n", "0.9": "+++\ntitle = \"Viewer Architecture and Preview Contracts\"\n+++\n\nPreview behavior in Sambee is a cross-boundary contract, not just a frontend component choice.\n\n## The Core Contract\n\nThe browser app decides how to render a file based on metadata and file-type information, but that depends on server-side classification staying aligned.\n\nThree rules matter most:\n\n- the backend and frontend file-type registries must describe the same extensions and MIME types\n- the backend decides whether an image format needs server-side conversion for browser compatibility\n- the frontend chooses the right viewer component and file icon based on the effective file type and MIME information it receives\n\n## Where the Main Decisions Live\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | backend source of truth for extensions, MIME types, categories, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | frontend source of truth for extensions, MIME types, categories, viewer components, icons, and colors |\n| `frontend/src/components/Viewer/` | viewer components and shared viewer UI |\n| `backend/app/services/image_converter.py` | server-side conversion for non-browser-native image formats |\n\n## Viewer Selection Model\n\nAt a high level, the preview pipeline works like this:\n\n1. the backend determines file category and MIME behavior\n2. the backend decides whether the file can stream as-is or needs image conversion\n3. the frontend maps the file type to the appropriate viewer component\n4. the shared viewer controls keep the toolbar and common behavior consistent across viewers\n\nThat is why a file-type change almost always touches both backend and frontend code.\n\n## Browser-Native Versus Server-Converted Images\n\nSambee supports both browser-native formats and formats that need server-side conversion.\n\n- browser-native formats can be sent to the viewer directly\n- non-browser-native image formats are converted on the server before the browser renders them\n- special cases such as transparency preservation can change the output format choice\n\nIf you change conversion rules, you are changing a product contract, not just an implementation detail.\n\n### Server-Side Conversion Contract\n\nThe conversion path is owned by `backend/app/services/image_converter.py` and is exercised through the viewer API.\n\nThe backend conversion service is responsible for:\n\n- deciding whether an image needs processing\n- converting unsupported or impractical browser formats into a viewer-safe output format\n- preserving transparency where the output contract requires it\n- applying optional downscaling so one preview request cannot explode memory usage casually\n- returning enough metadata for the viewer endpoint to send the correct MIME type back to the browser\n\nRepresentative service responsibilities include:\n\n- `needs_processing(filename)`\n- `convert_image_for_viewer(...)`\n- `is_image_file(filename)`\n- `get_image_info(...)`\n\nThe viewer endpoint then follows this rule:\n\n- if the image can stream safely as-is, return a streaming response\n- if it requires conversion, read it, convert it, and return the converted bytes with the converted MIME type\n\nThat means preview behavior for formats such as TIFF, HEIC, BMP, ICO, and similar formats depends on backend conversion policy, not just on frontend MIME recognition.\n\n### Local-Drive Preview Policy\n\nThe Companion serves local-drive files and archive members as raw bytes. It does not copy local content to the backend for processing and does not bundle the backend image or PDF processing stack.\n\n- Browser-native images, text files, and original PDFs can preview from their raw local bytes.\n- Image formats that require server-side conversion, such as TIFF, HEIC, PSD, JPEG XL, and scientific image formats, show an explicit preview-unavailable state for local drives.\n- Image resizing and PDF compatibility normalization are unavailable for local drives.\n- Downloading and opening the original file locally remain available when a local preview is unavailable.\n\nThe frontend resolves these capabilities before making a local viewer request. Local archive-member requests use the Companion's strict raw-stream contract, while SMB archive-member requests retain the full conversion and PDF-normalization request parameters.\n\n### Output Format Rules\n\nThe backend does not always convert everything to the same output type.\n\n- JPEG is the common output for opaque images\n- PNG remains important when transparency must be preserved\n- ICO-like transparency handling is therefore different from ordinary opaque-photo conversion\n- alpha-bearing formats converted to JPEG need explicit compositing behavior rather than silent accidental loss\n\nIf you change those rules, check both visual correctness and user-facing assumptions such as download behavior and gallery continuity.\n\n### Current Format-Specific Preview Semantics\n\nSeveral converted-image families have product-specific preview semantics that contributors should preserve unless the product intentionally changes.\n\n- multi-page TIFF currently previews the first page rather than exposing a document-style page stack\n- PSD and PSB preview the flattened composite instead of surfacing layer-edit semantics through the browser viewer\n- EPS and AI are rasterized through the preprocessing path at high quality, currently using the 300 DPI rendering baseline\n- HDR-oriented formats such as EXR and Radiance HDR are tone-mapped into ordinary browser-display output\n- whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF preview as an overview or first practical pyramid level rather than as a full pathology viewer\n- FITS and similar scientific-image formats apply visibility scaling so low-level pixel values become inspectable in a normal browser image surface\n\nThese are not accidental implementation details. They define what users should expect from preview and therefore belong to the product contract.\n\n### Resizing and Resource Limits\n\nServer-side conversion can consume significant memory because the file must be read, decoded, and re-encoded.\n\nThe current contract therefore includes:\n\n- configurable JPEG-quality behavior\n- maximum-dimension downscaling to avoid unbounded preview size\n- backend-side protection against excessive memory usage from large source images\n\nContributors should treat those limits as operational safety controls, not as arbitrary defaults.\n\n### Dependency and Environment Expectations\n\nThe conversion path depends on reviewed Python and system-image libraries.\n\nThat includes the normal image stack plus HEIC/HEIF support through the reviewed dependency chain and corresponding system libraries in the container or runtime image.\n\nWhen conversion support seems to disappear unexpectedly, check:\n\n- the backend Python dependency set\n- the container or host system-image libraries\n- whether the format-specific support was actually installed in the current environment\n\n### Preprocessor Registry for Exotic Formats\n\nSome formats need a preprocessing step before the normal conversion path can handle them at all.\n\nThat registry lives in:\n\n- `backend/app/services/preprocessor.py`\n\nIt is consumed by:\n\n- `backend/app/services/image_converter.py`\n\nThe preprocessor layer exists for formats that libvips should not or cannot decode directly for Sambee's preview contract.\n\nCurrent registered formats route through the ImageMagick-backed preprocessor:\n\n- `.psd`\n- `.psb`\n- `.eps`\n- `.ai`\n\nThe registry is the single source of truth for which extensions require preprocessing before the final viewer-safe conversion step.\n\nFor the backend service architecture behind that path, continue to [Image Preprocessing and Conversion Pipeline](../../backend-architecture/image-preprocessing-and-conversion-pipeline/).\n\nRepresentative registry operations include:\n\n- `PreprocessorRegistry.requires_preprocessing(extension)`\n- `PreprocessorRegistry.get_preprocessor_for_format(extension)`\n- `PreprocessorRegistry.get_supported_formats()`\n- `PreprocessorRegistry.register_format(extension, preprocessor_class)`\n\n### Preprocessor Design Rules\n\nThe preprocessor layer has its own constraints:\n\n- one registry entry per preprocessable extension\n- direct in-memory conversion to the final browser-ready format rather than chained intermediate formats\n- no shell-mediated fallback chain logic in the registry itself\n- input validation and timeout enforcement happen in the preprocessor layer\n- failures should surface as explicit preprocessing or conversion errors rather than silent format drift\n\nThe main abstraction is `PreprocessorInterface`, with `ImageMagickPreprocessor` as the current built-in implementation.\n\n### Adding a New Preprocessed Format\n\nIf a new format cannot be handled by the normal conversion stack directly:\n\n1. implement a `PreprocessorInterface` subclass if the existing preprocessor is not appropriate\n2. register the extension in `PreprocessorRegistry`\n3. add or update file-type metadata if the format becomes user-visible in preview flows\n4. add tests for format recognition, tool availability, validation, and successful conversion\n\nDo not treat preprocessable formats as ordinary file-type additions. They change the backend conversion pipeline itself.\n\n### Error Surface Contributors Must Preserve\n\nConversion failures are user-visible API behavior, not internal-only exceptions.\n\nTypical outcomes include:\n\n- not implemented when the current environment lacks support for a format family\n- unprocessable-content style failures when the file is corrupt or cannot be decoded\n- ordinary backend failures when an unexpected exception escapes the conversion path\n\nThat means error wording, status behavior, and frontend fallback behavior should be reviewed together.\n\n## Shared Viewer UI\n\nThe main viewer toolbar is intentionally centralized in `frontend/src/components/Viewer/ViewerControls.tsx`.\n\nThis is no longer just an image-and-PDF convenience component. It is the canonical control surface for the current full-screen image, PDF, and Markdown viewers.\n\n- shared toolbar layout, styling, keyboard-tooltip behavior, and responsive behavior live in `ViewerControls`\n- each viewer turns features on through configuration and passes only the state objects it needs\n- future viewers should reuse that control shell where possible instead of creating another top-level toolbar implementation\n\n### Control-Surface Model\n\n`ViewerControls` uses a feature-flag configuration plus typed state objects.\n\nThe configuration currently enables these capability groups:\n\n- `navigation` for gallery-style previous and next navigation\n- `pageNavigation` for PDF page input and page stepping\n- `zoom` for viewer-managed zoom actions\n- `rotation` for image and PDF rotation actions\n- `search` for the shared search row and match navigation affordances\n- `download` for explicit download actions\n- `share` for mobile-first share actions\n\nThe component then accepts matching state surfaces:\n\n- `NavigationState` for item index, total items, and next or previous handlers\n- `PageNavigationState` for current page, total pages, and page-change handling\n- `ZoomState` for zoom-in and zoom-out handlers\n- `RotationState` for rotate-left and rotate-right handlers\n- `SearchState` for search text, match counts, search-panel state, open or close callbacks, and viewer-specific search navigation\n\nThat split matters because `ViewerControls` owns the common UI, but it does not own viewer logic. It renders controls and delegates behavior back to the viewer that actually knows how to navigate pages, zoom, rotate, or search.\n\n### Current Consumers\n\nThe current shared-toolbar consumers are:\n\n- `ImageViewer`, which enables gallery navigation, zoom, rotation, download, and optional mobile share\n- `PDFViewer`, which enables page navigation, zoom, rotation, search, download, and optional mobile share\n- `MarkdownViewer`, which reuses the same shell for download, optional mobile share, shared search UI, and viewer-specific action buttons such as editing flows\n\n`ViewerControls` also supports generic toolbar actions through the `actions` prop, which can render either text buttons or icon buttons. That is what allows Markdown-specific actions to live inside the same shared toolbar instead of forcing a second toolbar implementation.\n\n### Search UI Versus Search Engine\n\nThe search row is shared, but the search backend is viewer-specific.\n\n- `PDFViewer` wires the search controls to PDF text extraction, page-aware match tracking, and PDF-specific next or previous navigation\n- rendered Markdown and other rendered text views can route search through the DOM text-search utility in `frontend/src/utils/domTextSearch.ts`\n- Markdown edit mode does not reuse the rendered-view DOM search implementation; it bridges the same outer toolbar UI into the editor-specific search state and commands instead\n\nThat separation is an important contract: contributors should reuse the shared search UI when possible, but should not assume every viewer can use the same search implementation under the hood.\n\n### Responsive and Accessibility Rules\n\nThe centralized toolbar also encodes product behavior that should stay consistent across viewers.\n\n- filename display, optional filename adornments, and close behavior are shared\n- mobile layout uses safe-area-aware spacing and smaller controls\n- gallery arrows and desktop zoom controls are intentionally reduced on mobile, where gesture-based interaction is preferred\n- share is exposed as a mobile-first affordance, with optional early-intent warming through `onShareIntent`\n- buttons use explicit `aria-label` values and shortcut-oriented `title` text so the control surface remains navigable and self-describing\n- the shared search row manages focus when it opens and preserves consistent close behavior for toggle and Escape-driven exits\n\n### Legacy Components and Contributor Guidance\n\nLegacy `ImageControls.tsx` and `PDFControls.tsx` files still exist in the frontend tree, but `ViewerControls` is the current architectural direction and the shared component used by the active image, PDF, and Markdown viewers.\n\nIf you add another viewer or extend an existing one:\n\n- prefer extending `ViewerControlsConfig`, the relevant state interfaces, or the generic `actions` surface\n- keep viewer-specific logic in the viewer component rather than teaching `ViewerControls` about file-format internals\n- preserve shared mobile, accessibility, and search-panel behavior unless the product intentionally changes that contract\n- add or update focused tests in `frontend/src/components/Viewer/__tests__/ViewerControls.test.tsx` when the shared toolbar contract changes\n\n## Adding a New File Type Safely\n\nFile-type support is registry-driven. The safest way to add a new type is to treat backend and frontend changes as one contract update.\n\n### Main Files to Change\n\n| Path | Why it changes |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | declare extensions, MIME types, category, description, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | declare extensions, MIME types, category, viewer component, icon, color, and description |\n| `frontend/src/components/Viewer/` | add or reuse a viewer component when the type needs a dedicated preview surface |\n\nIf a file type is user-visible, update the published support docs that describe what Sambee can preview.\n\n### Quick Start for a New Image Format\n\nFor an image format such as JPEG XL, the minimum workflow is:\n\n1. add a `FileTypeDefinition` entry to the backend registry\n2. add the matching entry to the frontend registry\n3. decide whether the image is browser-native or requires server-side conversion\n4. keep extensions and MIME types identical across both registries\n5. run the viewer and backend validation checks\n\nBackend example:\n\n```python\nFileTypeDefinition(\n\t\textensions=(\".jxl\",),\n\t\tmime_types=(\"image/jxl\",),\n\t\tcategory=FileCategory.IMAGE,\n\t\trequires_conversion=True,\n\t\tdescription=\"JPEG XL Image\",\n)\n```\n\nFrontend example:\n\n```typescript\n{\n\textensions: [\".jxl\"],\n\tmimeTypes: [\"image/jxl\"],\n\tcategory: \"image\",\n\tviewerComponent: () =\u003e import(\"../components/Viewer/ImageViewer\"),\n\ticon: \"image\",\n\tcolor: \"#a855f7\",\n\tdescription: \"JPEG XL Image\",\n}\n```\n\nThat registry update is what drives MIME matching, icon treatment, viewer routing, and image-gallery inclusion.\n\n### Backend Registry Rules\n\nBackend file-type definitions must stay explicit and type-safe.\n\n- `extensions` are tuples with a leading dot, such as `(\".jpg\", \".jpeg\")`\n- `mime_types` are tuples of standard MIME strings\n- `category` uses `FileCategory` values such as `IMAGE`, `DOCUMENT`, `TEXT`, `VIDEO`, `AUDIO`, `ARCHIVE`, `CODE`, `SPREADSHEET`, or `OTHER`\n- `requires_conversion` matters for image formats that cannot be rendered directly by the browser\n- `description` should be the human-readable label contributors and users would expect\n\nHow to decide `requires_conversion`:\n\n- set it to `False` for browser-native formats such as PNG, JPEG, GIF, WebP, SVG, and AVIF\n- set it to `True` for formats with limited browser support or formats that are not practical to render directly, such as TIFF, HEIC, BMP, JPEG 2000, or JPEG XL when browser support is not sufficient for the product baseline\n\n### Frontend Registry Rules\n\nFrontend file-type definitions control how the browser app presents the file.\n\n- keep `extensions` and `mimeTypes` aligned with the backend registry\n- set `viewerComponent` to the shared viewer that should render the type\n- choose an icon that matches the product language for that file category\n- choose a color that distinguishes the format without inventing a new palette on every addition\n\nFor image formats, reusing `ImageViewer` is usually enough. For non-image formats, you may need a dedicated viewer such as `PdfViewer`, `VideoViewer`, `AudioViewer`, or `TextViewer`.\n\n### Non-Image File Types\n\nThe overall process is the same for documents, video, audio, text, archives, and code files.\n\n1. add the backend registry entry\n2. add the frontend registry entry\n3. create or reuse the viewer component when preview support exists\n4. verify the file icon, viewer routing, and download behavior\n\nFor non-image files, `requires_conversion` is usually `False`. The main design question is whether the product has a viewer component for that category or should fall back to download-only behavior.\n\n### Integration Checklist\n\nUse this checklist before you consider the file type integrated:\n\n- backend registry entry added\n- frontend registry entry added\n- extensions and MIME types match exactly across both registries\n- browser-native versus converted-image behavior decided intentionally\n- viewer component chosen or added\n- icon and color treatment chosen\n- user-visible support docs updated if the file type changes what Sambee can preview\n\n### Testing Checklist\n\nAfter the registry change, verify:\n\n- icon display in the file browser\n- file opening in the expected viewer\n- shared toolbar behavior if the preview uses `ViewerControls`\n- conversion output if the format is server-converted\n- gallery inclusion for image formats\n- MIME type behavior across extension variants such as upper-case filenames\n- download behavior with the correct MIME type\n- mobile and tablet behavior when the preview is expected to work there\n\nFor server-converted formats, also verify:\n\n- the backend returns the converted MIME type you expect\n- transparency-sensitive formats still render correctly\n- resizing or quality settings do not degrade the preview contract unexpectedly\n- environment-specific format support failures surface in a controlled way\n\nFor preprocessable formats, also verify:\n\n- the registry recognizes the extension regardless of case and leading-dot differences\n- the expected preprocessor is selected for that format\n- missing external-tool support fails cleanly\n- validation and timeout rules behave as intended under bad inputs and slow conversions\n\n### Architecture Notes\n\nThese helper functions are the practical integration points contributors usually touch:\n\n- backend: `get_mime_type`, `needs_processing`, `is_image_file`, `get_file_type_by_extension`, `get_file_type_by_mime`\n- frontend: `getViewerComponent`, `isImageFile`, `getFileIcon`, `getFileTypeByExtension`, `getFileTypeByMime`\n\nAt runtime, the flow is:\n\n1. the backend lists files and assigns MIME information\n2. the frontend receives `FileInfo` data with that MIME information\n3. the frontend chooses icon treatment from filename and type rules\n4. the frontend selects the viewer from MIME and file-type data\n5. the backend routes convertible images through the image-conversion pipeline when needed\n\nThe frontend side still has work to do even when the backend owns the conversion:\n\n- viewer MIME recognition must include the input formats the backend classifies as previewable\n- file-type icon and color treatment must still reflect the original file type rather than the converted transport format\n- browser-side fallback MIME logic must not drift from the backend contract in ways that hide conversion bugs\n\n### Operational Characteristics\n\nServer-side conversion changes the runtime profile of preview requests.\n\n- large images can produce short CPU spikes during decode and encode\n- memory usage can rise well above compressed input size while the image is fully decoded\n- SMB-backed reads add their own latency before conversion even starts\n\nThat is why preview regressions for large HEIC or TIFF files often need both backend and user-facing verification.\n\n### Future Extension Points\n\nThe current conversion path leaves room for later enhancements such as:\n\n- caching converted preview outputs\n- queueing especially large conversions\n- dedicated thumbnail generation\n- richer multi-page image handling\n- conversion metrics for operational monitoring\n\nThose are extension points, not assumptions the current product already guarantees.\n\nThe highest-risk mistake is still registry drift. If the backend and frontend disagree about extensions or MIME types, preview behavior becomes unreliable in ways that are easy to miss until users hit them.\n\n## Common Failure Modes\n\n- backend and frontend MIME types do not match\n- a format is marked browser-native when it really needs conversion\n- a viewer component is not registered even though the type is recognized\n- a conversion change improves one format but breaks gallery behavior, download semantics, or mobile viewing\n\n## Validation Expectations\n\nWhen you change viewer or file-type behavior, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd backend \u0026\u0026 pytest -v\n```\n\nIf the change is image-conversion-specific, include the relevant backend tests around image conversion and preview behavior.\n", "1.0": "+++\ntitle = \"Viewer Architecture and Preview Contracts\"\n+++\n\nPreview behavior in Sambee is a cross-boundary contract, not just a frontend component choice.\n\n## The Core Contract\n\nThe browser app decides how to render a file based on metadata and file-type information, but that depends on server-side classification staying aligned.\n\nThree rules matter most:\n\n- the backend and frontend file-type registries must describe the same extensions and MIME types\n- the backend decides whether an image format needs server-side conversion for browser compatibility\n- the frontend chooses the right viewer component and file icon based on the effective file type and MIME information it receives\n\n## Where the Main Decisions Live\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | backend source of truth for extensions, MIME types, categories, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | frontend source of truth for extensions, MIME types, categories, viewer components, icons, and colors |\n| `frontend/src/components/Viewer/` | viewer components and shared viewer UI |\n| `backend/app/services/image_converter.py` | server-side conversion for non-browser-native image formats |\n\n## Viewer Selection Model\n\nAt a high level, the preview pipeline works like this:\n\n1. the backend determines file category and MIME behavior\n2. the backend decides whether the file can stream as-is or needs image conversion\n3. the frontend maps the file type to the appropriate viewer component\n4. the shared viewer controls keep the toolbar and common behavior consistent across viewers\n\nThat is why a file-type change almost always touches both backend and frontend code.\n\n## Browser-Native Versus Server-Converted Images\n\nSambee supports both browser-native formats and formats that need server-side conversion.\n\n- browser-native formats can be sent to the viewer directly\n- non-browser-native image formats are converted on the server before the browser renders them\n- special cases such as transparency preservation can change the output format choice\n\nIf you change conversion rules, you are changing a product contract, not just an implementation detail.\n\n### Server-Side Conversion Contract\n\nThe conversion path is owned by `backend/app/services/image_converter.py` and is exercised through the viewer API.\n\nThe backend conversion service is responsible for:\n\n- deciding whether an image needs processing\n- converting unsupported or impractical browser formats into a viewer-safe output format\n- preserving transparency where the output contract requires it\n- applying optional downscaling so one preview request cannot explode memory usage casually\n- returning enough metadata for the viewer endpoint to send the correct MIME type back to the browser\n\nRepresentative service responsibilities include:\n\n- `needs_processing(filename)`\n- `convert_image_for_viewer(...)`\n- `is_image_file(filename)`\n- `get_image_info(...)`\n\nThe viewer endpoint then follows this rule:\n\n- if the image can stream safely as-is, return a streaming response\n- if it requires conversion, read it, convert it, and return the converted bytes with the converted MIME type\n\nThat means preview behavior for formats such as TIFF, HEIC, BMP, ICO, and similar formats depends on backend conversion policy, not just on frontend MIME recognition.\n\n### Local-Drive Preview Policy\n\nThe Companion serves local-drive files and archive members as raw bytes. It does not copy local content to the backend for processing and does not bundle the backend image or PDF processing stack.\n\n- Browser-native images, text files, and original PDFs can preview from their raw local bytes.\n- Image formats that require server-side conversion, such as TIFF, HEIC, PSD, JPEG XL, and scientific image formats, show an explicit preview-unavailable state for local drives.\n- Image resizing and PDF compatibility normalization are unavailable for local drives.\n- Downloading and opening the original file locally remain available when a local preview is unavailable.\n\nThe frontend resolves these capabilities before making a local viewer request. Local archive-member requests use the Companion's strict raw-stream contract, while SMB archive-member requests retain the full conversion and PDF-normalization request parameters.\n\n### Output Format Rules\n\nThe backend does not always convert everything to the same output type.\n\n- JPEG is the common output for opaque images\n- PNG remains important when transparency must be preserved\n- ICO-like transparency handling is therefore different from ordinary opaque-photo conversion\n- alpha-bearing formats converted to JPEG need explicit compositing behavior rather than silent accidental loss\n\nIf you change those rules, check both visual correctness and user-facing assumptions such as download behavior and gallery continuity.\n\n### Current Format-Specific Preview Semantics\n\nSeveral converted-image families have product-specific preview semantics that contributors should preserve unless the product intentionally changes.\n\n- multi-page TIFF currently previews the first page rather than exposing a document-style page stack\n- PSD and PSB preview the flattened composite instead of surfacing layer-edit semantics through the browser viewer\n- EPS and AI are rasterized through the preprocessing path at high quality, currently using the 300 DPI rendering baseline\n- HDR-oriented formats such as EXR and Radiance HDR are tone-mapped into ordinary browser-display output\n- whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF preview as an overview or first practical pyramid level rather than as a full pathology viewer\n- FITS and similar scientific-image formats apply visibility scaling so low-level pixel values become inspectable in a normal browser image surface\n\nThese are not accidental implementation details. They define what users should expect from preview and therefore belong to the product contract.\n\n### Resizing and Resource Limits\n\nServer-side conversion can consume significant memory because the file must be read, decoded, and re-encoded.\n\nThe current contract therefore includes:\n\n- configurable JPEG-quality behavior\n- maximum-dimension downscaling to avoid unbounded preview size\n- backend-side protection against excessive memory usage from large source images\n\nContributors should treat those limits as operational safety controls, not as arbitrary defaults.\n\n### Dependency and Environment Expectations\n\nThe conversion path depends on reviewed Python and system-image libraries.\n\nThat includes the normal image stack plus HEIC/HEIF support through the reviewed dependency chain and corresponding system libraries in the container or runtime image.\n\nWhen conversion support seems to disappear unexpectedly, check:\n\n- the backend Python dependency set\n- the container or host system-image libraries\n- whether the format-specific support was actually installed in the current environment\n\n### Preprocessor Registry for Exotic Formats\n\nSome formats need a preprocessing step before the normal conversion path can handle them at all.\n\nThat registry lives in:\n\n- `backend/app/services/preprocessor.py`\n\nIt is consumed by:\n\n- `backend/app/services/image_converter.py`\n\nThe preprocessor layer exists for formats that libvips should not or cannot decode directly for Sambee's preview contract.\n\nCurrent registered formats route through the ImageMagick-backed preprocessor:\n\n- `.psd`\n- `.psb`\n- `.eps`\n- `.ai`\n\nThe registry is the single source of truth for which extensions require preprocessing before the final viewer-safe conversion step.\n\nFor the backend service architecture behind that path, continue to [Image Preprocessing and Conversion Pipeline](../../backend-architecture/image-preprocessing-and-conversion-pipeline/).\n\nRepresentative registry operations include:\n\n- `PreprocessorRegistry.requires_preprocessing(extension)`\n- `PreprocessorRegistry.get_preprocessor_for_format(extension)`\n- `PreprocessorRegistry.get_supported_formats()`\n- `PreprocessorRegistry.register_format(extension, preprocessor_class)`\n\n### Preprocessor Design Rules\n\nThe preprocessor layer has its own constraints:\n\n- one registry entry per preprocessable extension\n- direct in-memory conversion to the final browser-ready format rather than chained intermediate formats\n- no shell-mediated fallback chain logic in the registry itself\n- input validation and timeout enforcement happen in the preprocessor layer\n- failures should surface as explicit preprocessing or conversion errors rather than silent format drift\n\nThe main abstraction is `PreprocessorInterface`, with `ImageMagickPreprocessor` as the current built-in implementation.\n\n### Adding a New Preprocessed Format\n\nIf a new format cannot be handled by the normal conversion stack directly:\n\n1. implement a `PreprocessorInterface` subclass if the existing preprocessor is not appropriate\n2. register the extension in `PreprocessorRegistry`\n3. add or update file-type metadata if the format becomes user-visible in preview flows\n4. add tests for format recognition, tool availability, validation, and successful conversion\n\nDo not treat preprocessable formats as ordinary file-type additions. They change the backend conversion pipeline itself.\n\n### Error Surface Contributors Must Preserve\n\nConversion failures are user-visible API behavior, not internal-only exceptions.\n\nTypical outcomes include:\n\n- not implemented when the current environment lacks support for a format family\n- unprocessable-content style failures when the file is corrupt or cannot be decoded\n- ordinary backend failures when an unexpected exception escapes the conversion path\n\nThat means error wording, status behavior, and frontend fallback behavior should be reviewed together.\n\n## Shared Viewer UI\n\nThe main viewer toolbar is intentionally centralized in `frontend/src/components/Viewer/ViewerControls.tsx`.\n\nThis is no longer just an image-and-PDF convenience component. It is the canonical control surface for the current full-screen image, PDF, and Markdown viewers.\n\n- shared toolbar layout, styling, keyboard-tooltip behavior, and responsive behavior live in `ViewerControls`\n- each viewer turns features on through configuration and passes only the state objects it needs\n- future viewers should reuse that control shell where possible instead of creating another top-level toolbar implementation\n\n### Control-Surface Model\n\n`ViewerControls` uses a feature-flag configuration plus typed state objects.\n\nThe configuration currently enables these capability groups:\n\n- `navigation` for gallery-style previous and next navigation\n- `pageNavigation` for PDF page input and page stepping\n- `zoom` for viewer-managed zoom actions\n- `rotation` for image and PDF rotation actions\n- `search` for the shared search row and match navigation affordances\n- `download` for explicit download actions\n- `share` for mobile-first share actions\n\nThe component then accepts matching state surfaces:\n\n- `NavigationState` for item index, total items, and next or previous handlers\n- `PageNavigationState` for current page, total pages, and page-change handling\n- `ZoomState` for zoom-in and zoom-out handlers\n- `RotationState` for rotate-left and rotate-right handlers\n- `SearchState` for search text, match counts, search-panel state, open or close callbacks, and viewer-specific search navigation\n\nThat split matters because `ViewerControls` owns the common UI, but it does not own viewer logic. It renders controls and delegates behavior back to the viewer that actually knows how to navigate pages, zoom, rotate, or search.\n\n### Current Consumers\n\nThe current shared-toolbar consumers are:\n\n- `ImageViewer`, which enables gallery navigation, zoom, rotation, download, and optional mobile share\n- `PDFViewer`, which enables page navigation, zoom, rotation, search, download, and optional mobile share\n- `MarkdownViewer`, which reuses the same shell for download, optional mobile share, shared search UI, and viewer-specific action buttons such as editing flows\n\n`ViewerControls` also supports generic toolbar actions through the `actions` prop, which can render either text buttons or icon buttons. That is what allows Markdown-specific actions to live inside the same shared toolbar instead of forcing a second toolbar implementation.\n\n### Search UI Versus Search Engine\n\nThe search row is shared, but the search backend is viewer-specific.\n\n- `PDFViewer` wires the search controls to PDF text extraction, page-aware match tracking, and PDF-specific next or previous navigation\n- rendered Markdown and other rendered text views can route search through the DOM text-search utility in `frontend/src/utils/domTextSearch.ts`\n- Markdown edit mode does not reuse the rendered-view DOM search implementation; it bridges the same outer toolbar UI into the editor-specific search state and commands instead\n\nThat separation is an important contract: contributors should reuse the shared search UI when possible, but should not assume every viewer can use the same search implementation under the hood.\n\n### Responsive and Accessibility Rules\n\nThe centralized toolbar also encodes product behavior that should stay consistent across viewers.\n\n- filename display, optional filename adornments, and close behavior are shared\n- mobile layout uses safe-area-aware spacing and smaller controls\n- gallery arrows and desktop zoom controls are intentionally reduced on mobile, where gesture-based interaction is preferred\n- share is exposed as a mobile-first affordance, with optional early-intent warming through `onShareIntent`\n- buttons use explicit `aria-label` values and shortcut-oriented `title` text so the control surface remains navigable and self-describing\n- the shared search row manages focus when it opens and preserves consistent close behavior for toggle and Escape-driven exits\n\n### Legacy Components and Contributor Guidance\n\nLegacy `ImageControls.tsx` and `PDFControls.tsx` files still exist in the frontend tree, but `ViewerControls` is the current architectural direction and the shared component used by the active image, PDF, and Markdown viewers.\n\nIf you add another viewer or extend an existing one:\n\n- prefer extending `ViewerControlsConfig`, the relevant state interfaces, or the generic `actions` surface\n- keep viewer-specific logic in the viewer component rather than teaching `ViewerControls` about file-format internals\n- preserve shared mobile, accessibility, and search-panel behavior unless the product intentionally changes that contract\n- add or update focused tests in `frontend/src/components/Viewer/__tests__/ViewerControls.test.tsx` when the shared toolbar contract changes\n\n## Adding a New File Type Safely\n\nFile-type support is registry-driven. The safest way to add a new type is to treat backend and frontend changes as one contract update.\n\n### Main Files to Change\n\n| Path | Why it changes |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | declare extensions, MIME types, category, description, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | declare extensions, MIME types, category, viewer component, icon, color, and description |\n| `frontend/src/components/Viewer/` | add or reuse a viewer component when the type needs a dedicated preview surface |\n\nIf a file type is user-visible, update the published support docs that describe what Sambee can preview.\n\n### Quick Start for a New Image Format\n\nFor an image format such as JPEG XL, the minimum workflow is:\n\n1. add a `FileTypeDefinition` entry to the backend registry\n2. add the matching entry to the frontend registry\n3. decide whether the image is browser-native or requires server-side conversion\n4. keep extensions and MIME types identical across both registries\n5. run the viewer and backend validation checks\n\nBackend example:\n\n```python\nFileTypeDefinition(\n\t\textensions=(\".jxl\",),\n\t\tmime_types=(\"image/jxl\",),\n\t\tcategory=FileCategory.IMAGE,\n\t\trequires_conversion=True,\n\t\tdescription=\"JPEG XL Image\",\n)\n```\n\nFrontend example:\n\n```typescript\n{\n\textensions: [\".jxl\"],\n\tmimeTypes: [\"image/jxl\"],\n\tcategory: \"image\",\n\tviewerComponent: () =\u003e import(\"../components/Viewer/ImageViewer\"),\n\ticon: \"image\",\n\tcolor: \"#a855f7\",\n\tdescription: \"JPEG XL Image\",\n}\n```\n\nThat registry update is what drives MIME matching, icon treatment, viewer routing, and image-gallery inclusion.\n\n### Backend Registry Rules\n\nBackend file-type definitions must stay explicit and type-safe.\n\n- `extensions` are tuples with a leading dot, such as `(\".jpg\", \".jpeg\")`\n- `mime_types` are tuples of standard MIME strings\n- `category` uses `FileCategory` values such as `IMAGE`, `DOCUMENT`, `TEXT`, `VIDEO`, `AUDIO`, `ARCHIVE`, `CODE`, `SPREADSHEET`, or `OTHER`\n- `requires_conversion` matters for image formats that cannot be rendered directly by the browser\n- `description` should be the human-readable label contributors and users would expect\n\nHow to decide `requires_conversion`:\n\n- set it to `False` for browser-native formats such as PNG, JPEG, GIF, WebP, SVG, and AVIF\n- set it to `True` for formats with limited browser support or formats that are not practical to render directly, such as TIFF, HEIC, BMP, JPEG 2000, or JPEG XL when browser support is not sufficient for the product baseline\n\n### Frontend Registry Rules\n\nFrontend file-type definitions control how the browser app presents the file.\n\n- keep `extensions` and `mimeTypes` aligned with the backend registry\n- set `viewerComponent` to the shared viewer that should render the type\n- choose an icon that matches the product language for that file category\n- choose a color that distinguishes the format without inventing a new palette on every addition\n\nFor image formats, reusing `ImageViewer` is usually enough. For non-image formats, you may need a dedicated viewer such as `PdfViewer`, `VideoViewer`, `AudioViewer`, or `TextViewer`.\n\n### Non-Image File Types\n\nThe overall process is the same for documents, video, audio, text, archives, and code files.\n\n1. add the backend registry entry\n2. add the frontend registry entry\n3. create or reuse the viewer component when preview support exists\n4. verify the file icon, viewer routing, and download behavior\n\nFor non-image files, `requires_conversion` is usually `False`. The main design question is whether the product has a viewer component for that category or should fall back to download-only behavior.\n\n### Integration Checklist\n\nUse this checklist before you consider the file type integrated:\n\n- backend registry entry added\n- frontend registry entry added\n- extensions and MIME types match exactly across both registries\n- browser-native versus converted-image behavior decided intentionally\n- viewer component chosen or added\n- icon and color treatment chosen\n- user-visible support docs updated if the file type changes what Sambee can preview\n\n### Testing Checklist\n\nAfter the registry change, verify:\n\n- icon display in the file browser\n- file opening in the expected viewer\n- shared toolbar behavior if the preview uses `ViewerControls`\n- conversion output if the format is server-converted\n- gallery inclusion for image formats\n- MIME type behavior across extension variants such as upper-case filenames\n- download behavior with the correct MIME type\n- mobile and tablet behavior when the preview is expected to work there\n\nFor server-converted formats, also verify:\n\n- the backend returns the converted MIME type you expect\n- transparency-sensitive formats still render correctly\n- resizing or quality settings do not degrade the preview contract unexpectedly\n- environment-specific format support failures surface in a controlled way\n\nFor preprocessable formats, also verify:\n\n- the registry recognizes the extension regardless of case and leading-dot differences\n- the expected preprocessor is selected for that format\n- missing external-tool support fails cleanly\n- validation and timeout rules behave as intended under bad inputs and slow conversions\n\n### Architecture Notes\n\nThese helper functions are the practical integration points contributors usually touch:\n\n- backend: `get_mime_type`, `needs_processing`, `is_image_file`, `get_file_type_by_extension`, `get_file_type_by_mime`\n- frontend: `getViewerComponent`, `isImageFile`, `getFileIcon`, `getFileTypeByExtension`, `getFileTypeByMime`\n\nAt runtime, the flow is:\n\n1. the backend lists files and assigns MIME information\n2. the frontend receives `FileInfo` data with that MIME information\n3. the frontend chooses icon treatment from filename and type rules\n4. the frontend selects the viewer from MIME and file-type data\n5. the backend routes convertible images through the image-conversion pipeline when needed\n\nThe frontend side still has work to do even when the backend owns the conversion:\n\n- viewer MIME recognition must include the input formats the backend classifies as previewable\n- file-type icon and color treatment must still reflect the original file type rather than the converted transport format\n- browser-side fallback MIME logic must not drift from the backend contract in ways that hide conversion bugs\n\n### Operational Characteristics\n\nServer-side conversion changes the runtime profile of preview requests.\n\n- large images can produce short CPU spikes during decode and encode\n- memory usage can rise well above compressed input size while the image is fully decoded\n- SMB-backed reads add their own latency before conversion even starts\n\nThat is why preview regressions for large HEIC or TIFF files often need both backend and user-facing verification.\n\n### Future Extension Points\n\nThe current conversion path leaves room for later enhancements such as:\n\n- caching converted preview outputs\n- queueing especially large conversions\n- dedicated thumbnail generation\n- richer multi-page image handling\n- conversion metrics for operational monitoring\n\nThose are extension points, not assumptions the current product already guarantees.\n\nThe highest-risk mistake is still registry drift. If the backend and frontend disagree about extensions or MIME types, preview behavior becomes unreliable in ways that are easy to miss until users hit them.\n\n## Common Failure Modes\n\n- backend and frontend MIME types do not match\n- a format is marked browser-native when it really needs conversion\n- a viewer component is not registered even though the type is recognized\n- a conversion change improves one format but breaks gallery behavior, download semantics, or mobile viewing\n\n## Validation Expectations\n\nWhen you change viewer or file-type behavior, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd backend \u0026\u0026 pytest -v\n```\n\nIf the change is image-conversion-specific, include the relevant backend tests around image conversion and preview behavior.\n", "2.0": "+++\ntitle = \"Viewer Architecture and Preview Contracts\"\n+++\n\nPreview behavior in Sambee is a cross-boundary contract, not just a frontend component choice.\n\n## The Core Contract\n\nThe browser app decides how to render a file based on metadata and file-type information, but that depends on server-side classification staying aligned.\n\nThree rules matter most:\n\n- the backend and frontend file-type registries must describe the same extensions and MIME types\n- the backend decides whether an image format needs server-side conversion for browser compatibility\n- the frontend chooses the right viewer component and file icon based on the effective file type and MIME information it receives\n\n## Where the Main Decisions Live\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | backend source of truth for extensions, MIME types, categories, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | frontend source of truth for extensions, MIME types, categories, viewer components, icons, and colors |\n| `frontend/src/components/Viewer/` | viewer components and shared viewer UI |\n| `backend/app/services/image_converter.py` | server-side conversion for non-browser-native image formats |\n\n## Viewer Selection Model\n\nAt a high level, the preview pipeline works like this:\n\n1. the backend determines file category and MIME behavior\n2. the backend decides whether the file can stream as-is or needs image conversion\n3. the frontend maps the file type to the appropriate viewer component\n4. the shared viewer controls keep the toolbar and common behavior consistent across viewers\n\nThat is why a file-type change almost always touches both backend and frontend code.\n\n## Browser-Native Versus Server-Converted Images\n\nSambee supports both browser-native formats and formats that need server-side conversion.\n\n- browser-native formats can be sent to the viewer directly\n- non-browser-native image formats are converted on the server before the browser renders them\n- special cases such as transparency preservation can change the output format choice\n\nIf you change conversion rules, you are changing a product contract, not just an implementation detail.\n\n### Server-Side Conversion Contract\n\nThe conversion path is owned by `backend/app/services/image_converter.py` and is exercised through the viewer API.\n\nThe backend conversion service is responsible for:\n\n- deciding whether an image needs processing\n- converting unsupported or impractical browser formats into a viewer-safe output format\n- preserving transparency where the output contract requires it\n- applying optional downscaling so one preview request cannot explode memory usage casually\n- returning enough metadata for the viewer endpoint to send the correct MIME type back to the browser\n\nRepresentative service responsibilities include:\n\n- `needs_processing(filename)`\n- `convert_image_for_viewer(...)`\n- `is_image_file(filename)`\n- `get_image_info(...)`\n\nThe viewer endpoint then follows this rule:\n\n- if the image can stream safely as-is, return a streaming response\n- if it requires conversion, read it, convert it, and return the converted bytes with the converted MIME type\n\nThat means preview behavior for formats such as TIFF, HEIC, BMP, ICO, and similar formats depends on backend conversion policy, not just on frontend MIME recognition.\n\n### Local-Drive Preview Policy\n\nThe Companion serves local-drive files and archive members as raw bytes. It does not copy local content to the backend for processing and does not bundle the backend image or PDF processing stack.\n\n- Browser-native images, text files, and original PDFs can preview from their raw local bytes.\n- Image formats that require server-side conversion, such as TIFF, HEIC, PSD, JPEG XL, and scientific image formats, show an explicit preview-unavailable state for local drives.\n- Image resizing and PDF compatibility normalization are unavailable for local drives.\n- Downloading and opening the original file locally remain available when a local preview is unavailable.\n\nThe frontend resolves these capabilities before making a local viewer request. Local archive-member requests use the Companion's strict raw-stream contract, while SMB archive-member requests retain the full conversion and PDF-normalization request parameters.\n\n### Output Format Rules\n\nThe backend does not always convert everything to the same output type.\n\n- JPEG is the common output for opaque images\n- PNG remains important when transparency must be preserved\n- ICO-like transparency handling is therefore different from ordinary opaque-photo conversion\n- alpha-bearing formats converted to JPEG need explicit compositing behavior rather than silent accidental loss\n\nIf you change those rules, check both visual correctness and user-facing assumptions such as download behavior and gallery continuity.\n\n### Current Format-Specific Preview Semantics\n\nSeveral converted-image families have product-specific preview semantics that contributors should preserve unless the product intentionally changes.\n\n- multi-page TIFF currently previews the first page rather than exposing a document-style page stack\n- PSD and PSB preview the flattened composite instead of surfacing layer-edit semantics through the browser viewer\n- EPS and AI are rasterized through the preprocessing path at high quality, currently using the 300 DPI rendering baseline\n- HDR-oriented formats such as EXR and Radiance HDR are tone-mapped into ordinary browser-display output\n- whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF preview as an overview or first practical pyramid level rather than as a full pathology viewer\n- FITS and similar scientific-image formats apply visibility scaling so low-level pixel values become inspectable in a normal browser image surface\n\nThese are not accidental implementation details. They define what users should expect from preview and therefore belong to the product contract.\n\n### Resizing and Resource Limits\n\nServer-side conversion can consume significant memory because the file must be read, decoded, and re-encoded.\n\nThe current contract therefore includes:\n\n- configurable JPEG-quality behavior\n- maximum-dimension downscaling to avoid unbounded preview size\n- backend-side protection against excessive memory usage from large source images\n\nContributors should treat those limits as operational safety controls, not as arbitrary defaults.\n\n### Dependency and Environment Expectations\n\nThe conversion path depends on reviewed Python and system-image libraries.\n\nThat includes the normal image stack plus HEIC/HEIF support through the reviewed dependency chain and corresponding system libraries in the container or runtime image.\n\nWhen conversion support seems to disappear unexpectedly, check:\n\n- the backend Python dependency set\n- the container or host system-image libraries\n- whether the format-specific support was actually installed in the current environment\n\n### Preprocessor Registry for Exotic Formats\n\nSome formats need a preprocessing step before the normal conversion path can handle them at all.\n\nThat registry lives in:\n\n- `backend/app/services/preprocessor.py`\n\nIt is consumed by:\n\n- `backend/app/services/image_converter.py`\n\nThe preprocessor layer exists for formats that libvips should not or cannot decode directly for Sambee's preview contract.\n\nCurrent registered formats route through the ImageMagick-backed preprocessor:\n\n- `.psd`\n- `.psb`\n- `.eps`\n- `.ai`\n\nThe registry is the single source of truth for which extensions require preprocessing before the final viewer-safe conversion step.\n\nFor the backend service architecture behind that path, continue to [Image Preprocessing and Conversion Pipeline](../../backend-architecture/image-preprocessing-and-conversion-pipeline/).\n\nRepresentative registry operations include:\n\n- `PreprocessorRegistry.requires_preprocessing(extension)`\n- `PreprocessorRegistry.get_preprocessor_for_format(extension)`\n- `PreprocessorRegistry.get_supported_formats()`\n- `PreprocessorRegistry.register_format(extension, preprocessor_class)`\n\n### Preprocessor Design Rules\n\nThe preprocessor layer has its own constraints:\n\n- one registry entry per preprocessable extension\n- direct in-memory conversion to the final browser-ready format rather than chained intermediate formats\n- no shell-mediated fallback chain logic in the registry itself\n- input validation and timeout enforcement happen in the preprocessor layer\n- failures should surface as explicit preprocessing or conversion errors rather than silent format drift\n\nThe main abstraction is `PreprocessorInterface`, with `ImageMagickPreprocessor` as the current built-in implementation.\n\n### Adding a New Preprocessed Format\n\nIf a new format cannot be handled by the normal conversion stack directly:\n\n1. implement a `PreprocessorInterface` subclass if the existing preprocessor is not appropriate\n2. register the extension in `PreprocessorRegistry`\n3. add or update file-type metadata if the format becomes user-visible in preview flows\n4. add tests for format recognition, tool availability, validation, and successful conversion\n\nDo not treat preprocessable formats as ordinary file-type additions. They change the backend conversion pipeline itself.\n\n### Error Surface Contributors Must Preserve\n\nConversion failures are user-visible API behavior, not internal-only exceptions.\n\nTypical outcomes include:\n\n- not implemented when the current environment lacks support for a format family\n- unprocessable-content style failures when the file is corrupt or cannot be decoded\n- ordinary backend failures when an unexpected exception escapes the conversion path\n\nThat means error wording, status behavior, and frontend fallback behavior should be reviewed together.\n\n## Shared Viewer UI\n\nThe main viewer toolbar is intentionally centralized in `frontend/src/components/Viewer/ViewerControls.tsx`.\n\nThis is no longer just an image-and-PDF convenience component. It is the canonical control surface for the current full-screen image, PDF, and Markdown viewers.\n\n- shared toolbar layout, styling, keyboard-tooltip behavior, and responsive behavior live in `ViewerControls`\n- each viewer turns features on through configuration and passes only the state objects it needs\n- future viewers should reuse that control shell where possible instead of creating another top-level toolbar implementation\n\n### Control-Surface Model\n\n`ViewerControls` uses a feature-flag configuration plus typed state objects.\n\nThe configuration currently enables these capability groups:\n\n- `navigation` for gallery-style previous and next navigation\n- `pageNavigation` for PDF page input and page stepping\n- `zoom` for viewer-managed zoom actions\n- `rotation` for image and PDF rotation actions\n- `search` for the shared search row and match navigation affordances\n- `download` for explicit download actions\n- `share` for mobile-first share actions\n\nThe component then accepts matching state surfaces:\n\n- `NavigationState` for item index, total items, and next or previous handlers\n- `PageNavigationState` for current page, total pages, and page-change handling\n- `ZoomState` for zoom-in and zoom-out handlers\n- `RotationState` for rotate-left and rotate-right handlers\n- `SearchState` for search text, match counts, search-panel state, open or close callbacks, and viewer-specific search navigation\n\nThat split matters because `ViewerControls` owns the common UI, but it does not own viewer logic. It renders controls and delegates behavior back to the viewer that actually knows how to navigate pages, zoom, rotate, or search.\n\n### Current Consumers\n\nThe current shared-toolbar consumers are:\n\n- `ImageViewer`, which enables gallery navigation, zoom, rotation, download, and optional mobile share\n- `PDFViewer`, which enables page navigation, zoom, rotation, search, download, and optional mobile share\n- `MarkdownViewer`, which reuses the same shell for download, optional mobile share, shared search UI, and viewer-specific action buttons such as editing flows\n\n`ViewerControls` also supports generic toolbar actions through the `actions` prop, which can render either text buttons or icon buttons. That is what allows Markdown-specific actions to live inside the same shared toolbar instead of forcing a second toolbar implementation.\n\n### Search UI Versus Search Engine\n\nThe search row is shared, but the search backend is viewer-specific.\n\n- `PDFViewer` wires the search controls to PDF text extraction, page-aware match tracking, and PDF-specific next or previous navigation\n- rendered Markdown and other rendered text views can route search through the DOM text-search utility in `frontend/src/utils/domTextSearch.ts`\n- Markdown edit mode does not reuse the rendered-view DOM search implementation; it bridges the same outer toolbar UI into the editor-specific search state and commands instead\n\nThat separation is an important contract: contributors should reuse the shared search UI when possible, but should not assume every viewer can use the same search implementation under the hood.\n\n### Responsive and Accessibility Rules\n\nThe centralized toolbar also encodes product behavior that should stay consistent across viewers.\n\n- filename display, optional filename adornments, and close behavior are shared\n- mobile layout uses safe-area-aware spacing and smaller controls\n- gallery arrows and desktop zoom controls are intentionally reduced on mobile, where gesture-based interaction is preferred\n- share is exposed as a mobile-first affordance, with optional early-intent warming through `onShareIntent`\n- buttons use explicit `aria-label` values and shortcut-oriented `title` text so the control surface remains navigable and self-describing\n- the shared search row manages focus when it opens and preserves consistent close behavior for toggle and Escape-driven exits\n\n### Legacy Components and Contributor Guidance\n\nLegacy `ImageControls.tsx` and `PDFControls.tsx` files still exist in the frontend tree, but `ViewerControls` is the current architectural direction and the shared component used by the active image, PDF, and Markdown viewers.\n\nIf you add another viewer or extend an existing one:\n\n- prefer extending `ViewerControlsConfig`, the relevant state interfaces, or the generic `actions` surface\n- keep viewer-specific logic in the viewer component rather than teaching `ViewerControls` about file-format internals\n- preserve shared mobile, accessibility, and search-panel behavior unless the product intentionally changes that contract\n- add or update focused tests in `frontend/src/components/Viewer/__tests__/ViewerControls.test.tsx` when the shared toolbar contract changes\n\n## Adding a New File Type Safely\n\nFile-type support is registry-driven. The safest way to add a new type is to treat backend and frontend changes as one contract update.\n\n### Main Files to Change\n\n| Path | Why it changes |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | declare extensions, MIME types, category, description, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | declare extensions, MIME types, category, viewer component, icon, color, and description |\n| `frontend/src/components/Viewer/` | add or reuse a viewer component when the type needs a dedicated preview surface |\n\nIf a file type is user-visible, update the published support docs that describe what Sambee can preview.\n\n### Quick Start for a New Image Format\n\nFor an image format such as JPEG XL, the minimum workflow is:\n\n1. add a `FileTypeDefinition` entry to the backend registry\n2. add the matching entry to the frontend registry\n3. decide whether the image is browser-native or requires server-side conversion\n4. keep extensions and MIME types identical across both registries\n5. run the viewer and backend validation checks\n\nBackend example:\n\n```python\nFileTypeDefinition(\n\t\textensions=(\".jxl\",),\n\t\tmime_types=(\"image/jxl\",),\n\t\tcategory=FileCategory.IMAGE,\n\t\trequires_conversion=True,\n\t\tdescription=\"JPEG XL Image\",\n)\n```\n\nFrontend example:\n\n```typescript\n{\n\textensions: [\".jxl\"],\n\tmimeTypes: [\"image/jxl\"],\n\tcategory: \"image\",\n\tviewerComponent: () =\u003e import(\"../components/Viewer/ImageViewer\"),\n\ticon: \"image\",\n\tcolor: \"#a855f7\",\n\tdescription: \"JPEG XL Image\",\n}\n```\n\nThat registry update is what drives MIME matching, icon treatment, viewer routing, and image-gallery inclusion.\n\n### Backend Registry Rules\n\nBackend file-type definitions must stay explicit and type-safe.\n\n- `extensions` are tuples with a leading dot, such as `(\".jpg\", \".jpeg\")`\n- `mime_types` are tuples of standard MIME strings\n- `category` uses `FileCategory` values such as `IMAGE`, `DOCUMENT`, `TEXT`, `VIDEO`, `AUDIO`, `ARCHIVE`, `CODE`, `SPREADSHEET`, or `OTHER`\n- `requires_conversion` matters for image formats that cannot be rendered directly by the browser\n- `description` should be the human-readable label contributors and users would expect\n\nHow to decide `requires_conversion`:\n\n- set it to `False` for browser-native formats such as PNG, JPEG, GIF, WebP, SVG, and AVIF\n- set it to `True` for formats with limited browser support or formats that are not practical to render directly, such as TIFF, HEIC, BMP, JPEG 2000, or JPEG XL when browser support is not sufficient for the product baseline\n\n### Frontend Registry Rules\n\nFrontend file-type definitions control how the browser app presents the file.\n\n- keep `extensions` and `mimeTypes` aligned with the backend registry\n- set `viewerComponent` to the shared viewer that should render the type\n- choose an icon that matches the product language for that file category\n- choose a color that distinguishes the format without inventing a new palette on every addition\n\nFor image formats, reusing `ImageViewer` is usually enough. For non-image formats, you may need a dedicated viewer such as `PdfViewer`, `VideoViewer`, `AudioViewer`, or `TextViewer`.\n\n### Non-Image File Types\n\nThe overall process is the same for documents, video, audio, text, archives, and code files.\n\n1. add the backend registry entry\n2. add the frontend registry entry\n3. create or reuse the viewer component when preview support exists\n4. verify the file icon, viewer routing, and download behavior\n\nFor non-image files, `requires_conversion` is usually `False`. The main design question is whether the product has a viewer component for that category or should fall back to download-only behavior.\n\n### Integration Checklist\n\nUse this checklist before you consider the file type integrated:\n\n- backend registry entry added\n- frontend registry entry added\n- extensions and MIME types match exactly across both registries\n- browser-native versus converted-image behavior decided intentionally\n- viewer component chosen or added\n- icon and color treatment chosen\n- user-visible support docs updated if the file type changes what Sambee can preview\n\n### Testing Checklist\n\nAfter the registry change, verify:\n\n- icon display in the file browser\n- file opening in the expected viewer\n- shared toolbar behavior if the preview uses `ViewerControls`\n- conversion output if the format is server-converted\n- gallery inclusion for image formats\n- MIME type behavior across extension variants such as upper-case filenames\n- download behavior with the correct MIME type\n- mobile and tablet behavior when the preview is expected to work there\n\nFor server-converted formats, also verify:\n\n- the backend returns the converted MIME type you expect\n- transparency-sensitive formats still render correctly\n- resizing or quality settings do not degrade the preview contract unexpectedly\n- environment-specific format support failures surface in a controlled way\n\nFor preprocessable formats, also verify:\n\n- the registry recognizes the extension regardless of case and leading-dot differences\n- the expected preprocessor is selected for that format\n- missing external-tool support fails cleanly\n- validation and timeout rules behave as intended under bad inputs and slow conversions\n\n### Architecture Notes\n\nThese helper functions are the practical integration points contributors usually touch:\n\n- backend: `get_mime_type`, `needs_processing`, `is_image_file`, `get_file_type_by_extension`, `get_file_type_by_mime`\n- frontend: `getViewerComponent`, `isImageFile`, `getFileIcon`, `getFileTypeByExtension`, `getFileTypeByMime`\n\nAt runtime, the flow is:\n\n1. the backend lists files and assigns MIME information\n2. the frontend receives `FileInfo` data with that MIME information\n3. the frontend chooses icon treatment from filename and type rules\n4. the frontend selects the viewer from MIME and file-type data\n5. the backend routes convertible images through the image-conversion pipeline when needed\n\nThe frontend side still has work to do even when the backend owns the conversion:\n\n- viewer MIME recognition must include the input formats the backend classifies as previewable\n- file-type icon and color treatment must still reflect the original file type rather than the converted transport format\n- browser-side fallback MIME logic must not drift from the backend contract in ways that hide conversion bugs\n\n### Operational Characteristics\n\nServer-side conversion changes the runtime profile of preview requests.\n\n- large images can produce short CPU spikes during decode and encode\n- memory usage can rise well above compressed input size while the image is fully decoded\n- SMB-backed reads add their own latency before conversion even starts\n\nThat is why preview regressions for large HEIC or TIFF files often need both backend and user-facing verification.\n\n### Future Extension Points\n\nThe current conversion path leaves room for later enhancements such as:\n\n- caching converted preview outputs\n- queueing especially large conversions\n- dedicated thumbnail generation\n- richer multi-page image handling\n- conversion metrics for operational monitoring\n\nThose are extension points, not assumptions the current product already guarantees.\n\nThe highest-risk mistake is still registry drift. If the backend and frontend disagree about extensions or MIME types, preview behavior becomes unreliable in ways that are easy to miss until users hit them.\n\n## Common Failure Modes\n\n- backend and frontend MIME types do not match\n- a format is marked browser-native when it really needs conversion\n- a viewer component is not registered even though the type is recognized\n- a conversion change improves one format but breaks gallery behavior, download semantics, or mobile viewing\n\n## Validation Expectations\n\nWhen you change viewer or file-type behavior, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd backend \u0026\u0026 pytest -v\n```\n\nIf the change is image-conversion-specific, include the relevant backend tests around image conversion and preview behavior.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Viewer Architecture and Preview Contracts\"\n+++\n\nPreview behavior in Sambee is a cross-boundary contract, not just a frontend component choice.\n\n## The Core Contract\n\nThe browser app decides how to render a file based on metadata and file-type information, but that depends on server-side classification staying aligned.\n\nThree rules matter most:\n\n- the backend and frontend file-type registries must describe the same extensions and MIME types\n- the backend decides whether an image format needs server-side conversion for browser compatibility\n- the frontend chooses the right viewer component and file icon based on the effective file type and MIME information it receives\n\n## Where the Main Decisions Live\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | backend source of truth for extensions, MIME types, categories, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | frontend source of truth for extensions, MIME types, categories, viewer components, icons, and colors |\n| `frontend/src/components/Viewer/` | viewer components and shared viewer UI |\n| `backend/app/services/image_converter.py` | server-side conversion for non-browser-native image formats |\n\n## Viewer Selection Model\n\nAt a high level, the preview pipeline works like this:\n\n1. the backend determines file category and MIME behavior\n2. the backend decides whether the file can stream as-is or needs image conversion\n3. the frontend maps the file type to the appropriate viewer component\n4. the shared viewer controls keep the toolbar and common behavior consistent across viewers\n\nThat is why a file-type change almost always touches both backend and frontend code.\n\n## Browser-Native Versus Server-Converted Images\n\nSambee supports both browser-native formats and formats that need server-side conversion.\n\n- browser-native formats can be sent to the viewer directly\n- non-browser-native image formats are converted on the server before the browser renders them\n- special cases such as transparency preservation can change the output format choice\n\nIf you change conversion rules, you are changing a product contract, not just an implementation detail.\n\n### Server-Side Conversion Contract\n\nThe conversion path is owned by `backend/app/services/image_converter.py` and is exercised through the viewer API.\n\nThe backend conversion service is responsible for:\n\n- deciding whether an image needs processing\n- converting unsupported or impractical browser formats into a viewer-safe output format\n- preserving transparency where the output contract requires it\n- applying optional downscaling so one preview request cannot explode memory usage casually\n- returning enough metadata for the viewer endpoint to send the correct MIME type back to the browser\n\nRepresentative service responsibilities include:\n\n- `needs_processing(filename)`\n- `convert_image_for_viewer(...)`\n- `is_image_file(filename)`\n- `get_image_info(...)`\n\nThe viewer endpoint then follows this rule:\n\n- if the image can stream safely as-is, return a streaming response\n- if it requires conversion, read it, convert it, and return the converted bytes with the converted MIME type\n\nThat means preview behavior for formats such as TIFF, HEIC, BMP, ICO, and similar formats depends on backend conversion policy, not just on frontend MIME recognition.\n\n### Local-Drive Preview Policy\n\nThe Companion serves local-drive files and archive members as raw bytes. It does not copy local content to the backend for processing and does not bundle the backend image or PDF processing stack.\n\n- Browser-native images, text files, and original PDFs can preview from their raw local bytes.\n- Image formats that require server-side conversion, such as TIFF, HEIC, PSD, JPEG XL, and scientific image formats, show an explicit preview-unavailable state for local drives.\n- Image resizing and PDF compatibility normalization are unavailable for local drives.\n- Downloading and opening the original file locally remain available when a local preview is unavailable.\n\nThe frontend resolves these capabilities before making a local viewer request. Local archive-member requests use the Companion's strict raw-stream contract, while SMB archive-member requests retain the full conversion and PDF-normalization request parameters.\n\n### Output Format Rules\n\nThe backend does not always convert everything to the same output type.\n\n- JPEG is the common output for opaque images\n- PNG remains important when transparency must be preserved\n- ICO-like transparency handling is therefore different from ordinary opaque-photo conversion\n- alpha-bearing formats converted to JPEG need explicit compositing behavior rather than silent accidental loss\n\nIf you change those rules, check both visual correctness and user-facing assumptions such as download behavior and gallery continuity.\n\n### Current Format-Specific Preview Semantics\n\nSeveral converted-image families have product-specific preview semantics that contributors should preserve unless the product intentionally changes.\n\n- multi-page TIFF currently previews the first page rather than exposing a document-style page stack\n- PSD and PSB preview the flattened composite instead of surfacing layer-edit semantics through the browser viewer\n- EPS and AI are rasterized through the preprocessing path at high quality, currently using the 300 DPI rendering baseline\n- HDR-oriented formats such as EXR and Radiance HDR are tone-mapped into ordinary browser-display output\n- whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF preview as an overview or first practical pyramid level rather than as a full pathology viewer\n- FITS and similar scientific-image formats apply visibility scaling so low-level pixel values become inspectable in a normal browser image surface\n\nThese are not accidental implementation details. They define what users should expect from preview and therefore belong to the product contract.\n\n### Resizing and Resource Limits\n\nServer-side conversion can consume significant memory because the file must be read, decoded, and re-encoded.\n\nThe current contract therefore includes:\n\n- configurable JPEG-quality behavior\n- maximum-dimension downscaling to avoid unbounded preview size\n- backend-side protection against excessive memory usage from large source images\n\nContributors should treat those limits as operational safety controls, not as arbitrary defaults.\n\n### Dependency and Environment Expectations\n\nThe conversion path depends on reviewed Python and system-image libraries.\n\nThat includes the normal image stack plus HEIC/HEIF support through the reviewed dependency chain and corresponding system libraries in the container or runtime image.\n\nWhen conversion support seems to disappear unexpectedly, check:\n\n- the backend Python dependency set\n- the container or host system-image libraries\n- whether the format-specific support was actually installed in the current environment\n\n### Preprocessor Registry for Exotic Formats\n\nSome formats need a preprocessing step before the normal conversion path can handle them at all.\n\nThat registry lives in:\n\n- `backend/app/services/preprocessor.py`\n\nIt is consumed by:\n\n- `backend/app/services/image_converter.py`\n\nThe preprocessor layer exists for formats that libvips should not or cannot decode directly for Sambee's preview contract.\n\nCurrent registered formats route through the ImageMagick-backed preprocessor:\n\n- `.psd`\n- `.psb`\n- `.eps`\n- `.ai`\n\nThe registry is the single source of truth for which extensions require preprocessing before the final viewer-safe conversion step.\n\nFor the backend service architecture behind that path, continue to [Image Preprocessing and Conversion Pipeline](../../backend-architecture/image-preprocessing-and-conversion-pipeline/).\n\nRepresentative registry operations include:\n\n- `PreprocessorRegistry.requires_preprocessing(extension)`\n- `PreprocessorRegistry.get_preprocessor_for_format(extension)`\n- `PreprocessorRegistry.get_supported_formats()`\n- `PreprocessorRegistry.register_format(extension, preprocessor_class)`\n\n### Preprocessor Design Rules\n\nThe preprocessor layer has its own constraints:\n\n- one registry entry per preprocessable extension\n- direct in-memory conversion to the final browser-ready format rather than chained intermediate formats\n- no shell-mediated fallback chain logic in the registry itself\n- input validation and timeout enforcement happen in the preprocessor layer\n- failures should surface as explicit preprocessing or conversion errors rather than silent format drift\n\nThe main abstraction is `PreprocessorInterface`, with `ImageMagickPreprocessor` as the current built-in implementation.\n\n### Adding a New Preprocessed Format\n\nIf a new format cannot be handled by the normal conversion stack directly:\n\n1. implement a `PreprocessorInterface` subclass if the existing preprocessor is not appropriate\n2. register the extension in `PreprocessorRegistry`\n3. add or update file-type metadata if the format becomes user-visible in preview flows\n4. add tests for format recognition, tool availability, validation, and successful conversion\n\nDo not treat preprocessable formats as ordinary file-type additions. They change the backend conversion pipeline itself.\n\n### Error Surface Contributors Must Preserve\n\nConversion failures are user-visible API behavior, not internal-only exceptions.\n\nTypical outcomes include:\n\n- not implemented when the current environment lacks support for a format family\n- unprocessable-content style failures when the file is corrupt or cannot be decoded\n- ordinary backend failures when an unexpected exception escapes the conversion path\n\nThat means error wording, status behavior, and frontend fallback behavior should be reviewed together.\n\n## Shared Viewer UI\n\nThe main viewer toolbar is intentionally centralized in `frontend/src/components/Viewer/ViewerControls.tsx`.\n\nThis is no longer just an image-and-PDF convenience component. It is the canonical control surface for the current full-screen image, PDF, and Markdown viewers.\n\n- shared toolbar layout, styling, keyboard-tooltip behavior, and responsive behavior live in `ViewerControls`\n- each viewer turns features on through configuration and passes only the state objects it needs\n- future viewers should reuse that control shell where possible instead of creating another top-level toolbar implementation\n\n### Control-Surface Model\n\n`ViewerControls` uses a feature-flag configuration plus typed state objects.\n\nThe configuration currently enables these capability groups:\n\n- `navigation` for gallery-style previous and next navigation\n- `pageNavigation` for PDF page input and page stepping\n- `zoom` for viewer-managed zoom actions\n- `rotation` for image and PDF rotation actions\n- `search` for the shared search row and match navigation affordances\n- `download` for explicit download actions\n- `share` for mobile-first share actions\n\nThe component then accepts matching state surfaces:\n\n- `NavigationState` for item index, total items, and next or previous handlers\n- `PageNavigationState` for current page, total pages, and page-change handling\n- `ZoomState` for zoom-in and zoom-out handlers\n- `RotationState` for rotate-left and rotate-right handlers\n- `SearchState` for search text, match counts, search-panel state, open or close callbacks, and viewer-specific search navigation\n\nThat split matters because `ViewerControls` owns the common UI, but it does not own viewer logic. It renders controls and delegates behavior back to the viewer that actually knows how to navigate pages, zoom, rotate, or search.\n\n### Current Consumers\n\nThe current shared-toolbar consumers are:\n\n- `ImageViewer`, which enables gallery navigation, zoom, rotation, download, and optional mobile share\n- `PDFViewer`, which enables page navigation, zoom, rotation, search, download, and optional mobile share\n- `MarkdownViewer`, which reuses the same shell for download, optional mobile share, shared search UI, and viewer-specific action buttons such as editing flows\n\n`ViewerControls` also supports generic toolbar actions through the `actions` prop, which can render either text buttons or icon buttons. That is what allows Markdown-specific actions to live inside the same shared toolbar instead of forcing a second toolbar implementation.\n\n### Search UI Versus Search Engine\n\nThe search row is shared, but the search backend is viewer-specific.\n\n- `PDFViewer` wires the search controls to PDF text extraction, page-aware match tracking, and PDF-specific next or previous navigation\n- rendered Markdown and other rendered text views can route search through the DOM text-search utility in `frontend/src/utils/domTextSearch.ts`\n- Markdown edit mode does not reuse the rendered-view DOM search implementation; it bridges the same outer toolbar UI into the editor-specific search state and commands instead\n\nThat separation is an important contract: contributors should reuse the shared search UI when possible, but should not assume every viewer can use the same search implementation under the hood.\n\n### Responsive and Accessibility Rules\n\nThe centralized toolbar also encodes product behavior that should stay consistent across viewers.\n\n- filename display, optional filename adornments, and close behavior are shared\n- mobile layout uses safe-area-aware spacing and smaller controls\n- gallery arrows and desktop zoom controls are intentionally reduced on mobile, where gesture-based interaction is preferred\n- share is exposed as a mobile-first affordance, with optional early-intent warming through `onShareIntent`\n- buttons use explicit `aria-label` values and shortcut-oriented `title` text so the control surface remains navigable and self-describing\n- the shared search row manages focus when it opens and preserves consistent close behavior for toggle and Escape-driven exits\n\n### Legacy Components and Contributor Guidance\n\nLegacy `ImageControls.tsx` and `PDFControls.tsx` files still exist in the frontend tree, but `ViewerControls` is the current architectural direction and the shared component used by the active image, PDF, and Markdown viewers.\n\nIf you add another viewer or extend an existing one:\n\n- prefer extending `ViewerControlsConfig`, the relevant state interfaces, or the generic `actions` surface\n- keep viewer-specific logic in the viewer component rather than teaching `ViewerControls` about file-format internals\n- preserve shared mobile, accessibility, and search-panel behavior unless the product intentionally changes that contract\n- add or update focused tests in `frontend/src/components/Viewer/__tests__/ViewerControls.test.tsx` when the shared toolbar contract changes\n\n## Adding a New File Type Safely\n\nFile-type support is registry-driven. The safest way to add a new type is to treat backend and frontend changes as one contract update.\n\n### Main Files to Change\n\n| Path | Why it changes |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | declare extensions, MIME types, category, description, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | declare extensions, MIME types, category, viewer component, icon, color, and description |\n| `frontend/src/components/Viewer/` | add or reuse a viewer component when the type needs a dedicated preview surface |\n\nIf a file type is user-visible, update the published support docs that describe what Sambee can preview.\n\n### Quick Start for a New Image Format\n\nFor an image format such as JPEG XL, the minimum workflow is:\n\n1. add a `FileTypeDefinition` entry to the backend registry\n2. add the matching entry to the frontend registry\n3. decide whether the image is browser-native or requires server-side conversion\n4. keep extensions and MIME types identical across both registries\n5. run the viewer and backend validation checks\n\nBackend example:\n\n```python\nFileTypeDefinition(\n\t\textensions=(\".jxl\",),\n\t\tmime_types=(\"image/jxl\",),\n\t\tcategory=FileCategory.IMAGE,\n\t\trequires_conversion=True,\n\t\tdescription=\"JPEG XL Image\",\n)\n```\n\nFrontend example:\n\n```typescript\n{\n\textensions: [\".jxl\"],\n\tmimeTypes: [\"image/jxl\"],\n\tcategory: \"image\",\n\tviewerComponent: () =\u003e import(\"../components/Viewer/ImageViewer\"),\n\ticon: \"image\",\n\tcolor: \"#a855f7\",\n\tdescription: \"JPEG XL Image\",\n}\n```\n\nThat registry update is what drives MIME matching, icon treatment, viewer routing, and image-gallery inclusion.\n\n### Backend Registry Rules\n\nBackend file-type definitions must stay explicit and type-safe.\n\n- `extensions` are tuples with a leading dot, such as `(\".jpg\", \".jpeg\")`\n- `mime_types` are tuples of standard MIME strings\n- `category` uses `FileCategory` values such as `IMAGE`, `DOCUMENT`, `TEXT`, `VIDEO`, `AUDIO`, `ARCHIVE`, `CODE`, `SPREADSHEET`, or `OTHER`\n- `requires_conversion` matters for image formats that cannot be rendered directly by the browser\n- `description` should be the human-readable label contributors and users would expect\n\nHow to decide `requires_conversion`:\n\n- set it to `False` for browser-native formats such as PNG, JPEG, GIF, WebP, SVG, and AVIF\n- set it to `True` for formats with limited browser support or formats that are not practical to render directly, such as TIFF, HEIC, BMP, JPEG 2000, or JPEG XL when browser support is not sufficient for the product baseline\n\n### Frontend Registry Rules\n\nFrontend file-type definitions control how the browser app presents the file.\n\n- keep `extensions` and `mimeTypes` aligned with the backend registry\n- set `viewerComponent` to the shared viewer that should render the type\n- choose an icon that matches the product language for that file category\n- choose a color that distinguishes the format without inventing a new palette on every addition\n\nFor image formats, reusing `ImageViewer` is usually enough. For non-image formats, you may need a dedicated viewer such as `PdfViewer`, `VideoViewer`, `AudioViewer`, or `TextViewer`.\n\n### Non-Image File Types\n\nThe overall process is the same for documents, video, audio, text, archives, and code files.\n\n1. add the backend registry entry\n2. add the frontend registry entry\n3. create or reuse the viewer component when preview support exists\n4. verify the file icon, viewer routing, and download behavior\n\nFor non-image files, `requires_conversion` is usually `False`. The main design question is whether the product has a viewer component for that category or should fall back to download-only behavior.\n\n### Integration Checklist\n\nUse this checklist before you consider the file type integrated:\n\n- backend registry entry added\n- frontend registry entry added\n- extensions and MIME types match exactly across both registries\n- browser-native versus converted-image behavior decided intentionally\n- viewer component chosen or added\n- icon and color treatment chosen\n- user-visible support docs updated if the file type changes what Sambee can preview\n\n### Testing Checklist\n\nAfter the registry change, verify:\n\n- icon display in the file browser\n- file opening in the expected viewer\n- shared toolbar behavior if the preview uses `ViewerControls`\n- conversion output if the format is server-converted\n- gallery inclusion for image formats\n- MIME type behavior across extension variants such as upper-case filenames\n- download behavior with the correct MIME type\n- mobile and tablet behavior when the preview is expected to work there\n\nFor server-converted formats, also verify:\n\n- the backend returns the converted MIME type you expect\n- transparency-sensitive formats still render correctly\n- resizing or quality settings do not degrade the preview contract unexpectedly\n- environment-specific format support failures surface in a controlled way\n\nFor preprocessable formats, also verify:\n\n- the registry recognizes the extension regardless of case and leading-dot differences\n- the expected preprocessor is selected for that format\n- missing external-tool support fails cleanly\n- validation and timeout rules behave as intended under bad inputs and slow conversions\n\n### Architecture Notes\n\nThese helper functions are the practical integration points contributors usually touch:\n\n- backend: `get_mime_type`, `needs_processing`, `is_image_file`, `get_file_type_by_extension`, `get_file_type_by_mime`\n- frontend: `getViewerComponent`, `isImageFile`, `getFileIcon`, `getFileTypeByExtension`, `getFileTypeByMime`\n\nAt runtime, the flow is:\n\n1. the backend lists files and assigns MIME information\n2. the frontend receives `FileInfo` data with that MIME information\n3. the frontend chooses icon treatment from filename and type rules\n4. the frontend selects the viewer from MIME and file-type data\n5. the backend routes convertible images through the image-conversion pipeline when needed\n\nThe frontend side still has work to do even when the backend owns the conversion:\n\n- viewer MIME recognition must include the input formats the backend classifies as previewable\n- file-type icon and color treatment must still reflect the original file type rather than the converted transport format\n- browser-side fallback MIME logic must not drift from the backend contract in ways that hide conversion bugs\n\n### Operational Characteristics\n\nServer-side conversion changes the runtime profile of preview requests.\n\n- large images can produce short CPU spikes during decode and encode\n- memory usage can rise well above compressed input size while the image is fully decoded\n- SMB-backed reads add their own latency before conversion even starts\n\nThat is why preview regressions for large HEIC or TIFF files often need both backend and user-facing verification.\n\n### Future Extension Points\n\nThe current conversion path leaves room for later enhancements such as:\n\n- caching converted preview outputs\n- queueing especially large conversions\n- dedicated thumbnail generation\n- richer multi-page image handling\n- conversion metrics for operational monitoring\n\nThose are extension points, not assumptions the current product already guarantees.\n\nThe highest-risk mistake is still registry drift. If the backend and frontend disagree about extensions or MIME types, preview behavior becomes unreliable in ways that are easy to miss until users hit them.\n\n## Common Failure Modes\n\n- backend and frontend MIME types do not match\n- a format is marked browser-native when it really needs conversion\n- a viewer component is not registered even though the type is recognized\n- a conversion change improves one format but breaks gallery behavior, download semantics, or mobile viewing\n\n## Validation Expectations\n\nWhen you change viewer or file-type behavior, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd backend \u0026\u0026 pytest -v\n```\n\nIf the change is image-conversion-specific, include the relevant backend tests around image conversion and preview behavior.\n", "0.8": "+++\ntitle = \"Viewer Architecture and Preview Contracts\"\n+++\n\nPreview behavior in Sambee is a cross-boundary contract, not just a frontend component choice.\n\n## The Core Contract\n\nThe browser app decides how to render a file based on metadata and file-type information, but that depends on server-side classification staying aligned.\n\nThree rules matter most:\n\n- the backend and frontend file-type registries must describe the same extensions and MIME types\n- the backend decides whether an image format needs server-side conversion for browser compatibility\n- the frontend chooses the right viewer component and file icon based on the effective file type and MIME information it receives\n\n## Where the Main Decisions Live\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | backend source of truth for extensions, MIME types, categories, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | frontend source of truth for extensions, MIME types, categories, viewer components, icons, and colors |\n| `frontend/src/components/Viewer/` | viewer components and shared viewer UI |\n| `backend/app/services/image_converter.py` | server-side conversion for non-browser-native image formats |\n\n## Viewer Selection Model\n\nAt a high level, the preview pipeline works like this:\n\n1. the backend determines file category and MIME behavior\n2. the backend decides whether the file can stream as-is or needs image conversion\n3. the frontend maps the file type to the appropriate viewer component\n4. the shared viewer controls keep the toolbar and common behavior consistent across viewers\n\nThat is why a file-type change almost always touches both backend and frontend code.\n\n## Browser-Native Versus Server-Converted Images\n\nSambee supports both browser-native formats and formats that need server-side conversion.\n\n- browser-native formats can be sent to the viewer directly\n- non-browser-native image formats are converted on the server before the browser renders them\n- special cases such as transparency preservation can change the output format choice\n\nIf you change conversion rules, you are changing a product contract, not just an implementation detail.\n\n### Server-Side Conversion Contract\n\nThe conversion path is owned by `backend/app/services/image_converter.py` and is exercised through the viewer API.\n\nThe backend conversion service is responsible for:\n\n- deciding whether an image needs processing\n- converting unsupported or impractical browser formats into a viewer-safe output format\n- preserving transparency where the output contract requires it\n- applying optional downscaling so one preview request cannot explode memory usage casually\n- returning enough metadata for the viewer endpoint to send the correct MIME type back to the browser\n\nRepresentative service responsibilities include:\n\n- `needs_processing(filename)`\n- `convert_image_for_viewer(...)`\n- `is_image_file(filename)`\n- `get_image_info(...)`\n\nThe viewer endpoint then follows this rule:\n\n- if the image can stream safely as-is, return a streaming response\n- if it requires conversion, read it, convert it, and return the converted bytes with the converted MIME type\n\nThat means preview behavior for formats such as TIFF, HEIC, BMP, ICO, and similar formats depends on backend conversion policy, not just on frontend MIME recognition.\n\n### Local-Drive Preview Policy\n\nThe Companion serves local-drive files and archive members as raw bytes. It does not copy local content to the backend for processing and does not bundle the backend image or PDF processing stack.\n\n- Browser-native images, text files, and original PDFs can preview from their raw local bytes.\n- Image formats that require server-side conversion, such as TIFF, HEIC, PSD, JPEG XL, and scientific image formats, show an explicit preview-unavailable state for local drives.\n- Image resizing and PDF compatibility normalization are unavailable for local drives.\n- Downloading and opening the original file locally remain available when a local preview is unavailable.\n\nThe frontend resolves these capabilities before making a local viewer request. Local archive-member requests use the Companion's strict raw-stream contract, while SMB archive-member requests retain the full conversion and PDF-normalization request parameters.\n\n### Output Format Rules\n\nThe backend does not always convert everything to the same output type.\n\n- JPEG is the common output for opaque images\n- PNG remains important when transparency must be preserved\n- ICO-like transparency handling is therefore different from ordinary opaque-photo conversion\n- alpha-bearing formats converted to JPEG need explicit compositing behavior rather than silent accidental loss\n\nIf you change those rules, check both visual correctness and user-facing assumptions such as download behavior and gallery continuity.\n\n### Current Format-Specific Preview Semantics\n\nSeveral converted-image families have product-specific preview semantics that contributors should preserve unless the product intentionally changes.\n\n- multi-page TIFF currently previews the first page rather than exposing a document-style page stack\n- PSD and PSB preview the flattened composite instead of surfacing layer-edit semantics through the browser viewer\n- EPS and AI are rasterized through the preprocessing path at high quality, currently using the 300 DPI rendering baseline\n- HDR-oriented formats such as EXR and Radiance HDR are tone-mapped into ordinary browser-display output\n- whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF preview as an overview or first practical pyramid level rather than as a full pathology viewer\n- FITS and similar scientific-image formats apply visibility scaling so low-level pixel values become inspectable in a normal browser image surface\n\nThese are not accidental implementation details. They define what users should expect from preview and therefore belong to the product contract.\n\n### Resizing and Resource Limits\n\nServer-side conversion can consume significant memory because the file must be read, decoded, and re-encoded.\n\nThe current contract therefore includes:\n\n- configurable JPEG-quality behavior\n- maximum-dimension downscaling to avoid unbounded preview size\n- backend-side protection against excessive memory usage from large source images\n\nContributors should treat those limits as operational safety controls, not as arbitrary defaults.\n\n### Dependency and Environment Expectations\n\nThe conversion path depends on reviewed Python and system-image libraries.\n\nThat includes the normal image stack plus HEIC/HEIF support through the reviewed dependency chain and corresponding system libraries in the container or runtime image.\n\nWhen conversion support seems to disappear unexpectedly, check:\n\n- the backend Python dependency set\n- the container or host system-image libraries\n- whether the format-specific support was actually installed in the current environment\n\n### Preprocessor Registry for Exotic Formats\n\nSome formats need a preprocessing step before the normal conversion path can handle them at all.\n\nThat registry lives in:\n\n- `backend/app/services/preprocessor.py`\n\nIt is consumed by:\n\n- `backend/app/services/image_converter.py`\n\nThe preprocessor layer exists for formats that libvips should not or cannot decode directly for Sambee's preview contract.\n\nCurrent registered formats route through the ImageMagick-backed preprocessor:\n\n- `.psd`\n- `.psb`\n- `.eps`\n- `.ai`\n\nThe registry is the single source of truth for which extensions require preprocessing before the final viewer-safe conversion step.\n\nFor the backend service architecture behind that path, continue to [Image Preprocessing and Conversion Pipeline](../../backend-architecture/image-preprocessing-and-conversion-pipeline/).\n\nRepresentative registry operations include:\n\n- `PreprocessorRegistry.requires_preprocessing(extension)`\n- `PreprocessorRegistry.get_preprocessor_for_format(extension)`\n- `PreprocessorRegistry.get_supported_formats()`\n- `PreprocessorRegistry.register_format(extension, preprocessor_class)`\n\n### Preprocessor Design Rules\n\nThe preprocessor layer has its own constraints:\n\n- one registry entry per preprocessable extension\n- direct in-memory conversion to the final browser-ready format rather than chained intermediate formats\n- no shell-mediated fallback chain logic in the registry itself\n- input validation and timeout enforcement happen in the preprocessor layer\n- failures should surface as explicit preprocessing or conversion errors rather than silent format drift\n\nThe main abstraction is `PreprocessorInterface`, with `ImageMagickPreprocessor` as the current built-in implementation.\n\n### Adding a New Preprocessed Format\n\nIf a new format cannot be handled by the normal conversion stack directly:\n\n1. implement a `PreprocessorInterface` subclass if the existing preprocessor is not appropriate\n2. register the extension in `PreprocessorRegistry`\n3. add or update file-type metadata if the format becomes user-visible in preview flows\n4. add tests for format recognition, tool availability, validation, and successful conversion\n\nDo not treat preprocessable formats as ordinary file-type additions. They change the backend conversion pipeline itself.\n\n### Error Surface Contributors Must Preserve\n\nConversion failures are user-visible API behavior, not internal-only exceptions.\n\nTypical outcomes include:\n\n- not implemented when the current environment lacks support for a format family\n- unprocessable-content style failures when the file is corrupt or cannot be decoded\n- ordinary backend failures when an unexpected exception escapes the conversion path\n\nThat means error wording, status behavior, and frontend fallback behavior should be reviewed together.\n\n## Shared Viewer UI\n\nThe main viewer toolbar is intentionally centralized in `frontend/src/components/Viewer/ViewerControls.tsx`.\n\nThis is no longer just an image-and-PDF convenience component. It is the canonical control surface for the current full-screen image, PDF, and Markdown viewers.\n\n- shared toolbar layout, styling, keyboard-tooltip behavior, and responsive behavior live in `ViewerControls`\n- each viewer turns features on through configuration and passes only the state objects it needs\n- future viewers should reuse that control shell where possible instead of creating another top-level toolbar implementation\n\n### Control-Surface Model\n\n`ViewerControls` uses a feature-flag configuration plus typed state objects.\n\nThe configuration currently enables these capability groups:\n\n- `navigation` for gallery-style previous and next navigation\n- `pageNavigation` for PDF page input and page stepping\n- `zoom` for viewer-managed zoom actions\n- `rotation` for image and PDF rotation actions\n- `search` for the shared search row and match navigation affordances\n- `download` for explicit download actions\n- `share` for mobile-first share actions\n\nThe component then accepts matching state surfaces:\n\n- `NavigationState` for item index, total items, and next or previous handlers\n- `PageNavigationState` for current page, total pages, and page-change handling\n- `ZoomState` for zoom-in and zoom-out handlers\n- `RotationState` for rotate-left and rotate-right handlers\n- `SearchState` for search text, match counts, search-panel state, open or close callbacks, and viewer-specific search navigation\n\nThat split matters because `ViewerControls` owns the common UI, but it does not own viewer logic. It renders controls and delegates behavior back to the viewer that actually knows how to navigate pages, zoom, rotate, or search.\n\n### Current Consumers\n\nThe current shared-toolbar consumers are:\n\n- `ImageViewer`, which enables gallery navigation, zoom, rotation, download, and optional mobile share\n- `PDFViewer`, which enables page navigation, zoom, rotation, search, download, and optional mobile share\n- `MarkdownViewer`, which reuses the same shell for download, optional mobile share, shared search UI, and viewer-specific action buttons such as editing flows\n\n`ViewerControls` also supports generic toolbar actions through the `actions` prop, which can render either text buttons or icon buttons. That is what allows Markdown-specific actions to live inside the same shared toolbar instead of forcing a second toolbar implementation.\n\n### Search UI Versus Search Engine\n\nThe search row is shared, but the search backend is viewer-specific.\n\n- `PDFViewer` wires the search controls to PDF text extraction, page-aware match tracking, and PDF-specific next or previous navigation\n- rendered Markdown and other rendered text views can route search through the DOM text-search utility in `frontend/src/utils/domTextSearch.ts`\n- Markdown edit mode does not reuse the rendered-view DOM search implementation; it bridges the same outer toolbar UI into the editor-specific search state and commands instead\n\nThat separation is an important contract: contributors should reuse the shared search UI when possible, but should not assume every viewer can use the same search implementation under the hood.\n\n### Responsive and Accessibility Rules\n\nThe centralized toolbar also encodes product behavior that should stay consistent across viewers.\n\n- filename display, optional filename adornments, and close behavior are shared\n- mobile layout uses safe-area-aware spacing and smaller controls\n- gallery arrows and desktop zoom controls are intentionally reduced on mobile, where gesture-based interaction is preferred\n- share is exposed as a mobile-first affordance, with optional early-intent warming through `onShareIntent`\n- buttons use explicit `aria-label` values and shortcut-oriented `title` text so the control surface remains navigable and self-describing\n- the shared search row manages focus when it opens and preserves consistent close behavior for toggle and Escape-driven exits\n\n### Legacy Components and Contributor Guidance\n\nLegacy `ImageControls.tsx` and `PDFControls.tsx` files still exist in the frontend tree, but `ViewerControls` is the current architectural direction and the shared component used by the active image, PDF, and Markdown viewers.\n\nIf you add another viewer or extend an existing one:\n\n- prefer extending `ViewerControlsConfig`, the relevant state interfaces, or the generic `actions` surface\n- keep viewer-specific logic in the viewer component rather than teaching `ViewerControls` about file-format internals\n- preserve shared mobile, accessibility, and search-panel behavior unless the product intentionally changes that contract\n- add or update focused tests in `frontend/src/components/Viewer/__tests__/ViewerControls.test.tsx` when the shared toolbar contract changes\n\n## Adding a New File Type Safely\n\nFile-type support is registry-driven. The safest way to add a new type is to treat backend and frontend changes as one contract update.\n\n### Main Files to Change\n\n| Path | Why it changes |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | declare extensions, MIME types, category, description, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | declare extensions, MIME types, category, viewer component, icon, color, and description |\n| `frontend/src/components/Viewer/` | add or reuse a viewer component when the type needs a dedicated preview surface |\n\nIf a file type is user-visible, update the published support docs that describe what Sambee can preview.\n\n### Quick Start for a New Image Format\n\nFor an image format such as JPEG XL, the minimum workflow is:\n\n1. add a `FileTypeDefinition` entry to the backend registry\n2. add the matching entry to the frontend registry\n3. decide whether the image is browser-native or requires server-side conversion\n4. keep extensions and MIME types identical across both registries\n5. run the viewer and backend validation checks\n\nBackend example:\n\n```python\nFileTypeDefinition(\n\t\textensions=(\".jxl\",),\n\t\tmime_types=(\"image/jxl\",),\n\t\tcategory=FileCategory.IMAGE,\n\t\trequires_conversion=True,\n\t\tdescription=\"JPEG XL Image\",\n)\n```\n\nFrontend example:\n\n```typescript\n{\n\textensions: [\".jxl\"],\n\tmimeTypes: [\"image/jxl\"],\n\tcategory: \"image\",\n\tviewerComponent: () =\u003e import(\"../components/Viewer/ImageViewer\"),\n\ticon: \"image\",\n\tcolor: \"#a855f7\",\n\tdescription: \"JPEG XL Image\",\n}\n```\n\nThat registry update is what drives MIME matching, icon treatment, viewer routing, and image-gallery inclusion.\n\n### Backend Registry Rules\n\nBackend file-type definitions must stay explicit and type-safe.\n\n- `extensions` are tuples with a leading dot, such as `(\".jpg\", \".jpeg\")`\n- `mime_types` are tuples of standard MIME strings\n- `category` uses `FileCategory` values such as `IMAGE`, `DOCUMENT`, `TEXT`, `VIDEO`, `AUDIO`, `ARCHIVE`, `CODE`, `SPREADSHEET`, or `OTHER`\n- `requires_conversion` matters for image formats that cannot be rendered directly by the browser\n- `description` should be the human-readable label contributors and users would expect\n\nHow to decide `requires_conversion`:\n\n- set it to `False` for browser-native formats such as PNG, JPEG, GIF, WebP, SVG, and AVIF\n- set it to `True` for formats with limited browser support or formats that are not practical to render directly, such as TIFF, HEIC, BMP, JPEG 2000, or JPEG XL when browser support is not sufficient for the product baseline\n\n### Frontend Registry Rules\n\nFrontend file-type definitions control how the browser app presents the file.\n\n- keep `extensions` and `mimeTypes` aligned with the backend registry\n- set `viewerComponent` to the shared viewer that should render the type\n- choose an icon that matches the product language for that file category\n- choose a color that distinguishes the format without inventing a new palette on every addition\n\nFor image formats, reusing `ImageViewer` is usually enough. For non-image formats, you may need a dedicated viewer such as `PdfViewer`, `VideoViewer`, `AudioViewer`, or `TextViewer`.\n\n### Non-Image File Types\n\nThe overall process is the same for documents, video, audio, text, archives, and code files.\n\n1. add the backend registry entry\n2. add the frontend registry entry\n3. create or reuse the viewer component when preview support exists\n4. verify the file icon, viewer routing, and download behavior\n\nFor non-image files, `requires_conversion` is usually `False`. The main design question is whether the product has a viewer component for that category or should fall back to download-only behavior.\n\n### Integration Checklist\n\nUse this checklist before you consider the file type integrated:\n\n- backend registry entry added\n- frontend registry entry added\n- extensions and MIME types match exactly across both registries\n- browser-native versus converted-image behavior decided intentionally\n- viewer component chosen or added\n- icon and color treatment chosen\n- user-visible support docs updated if the file type changes what Sambee can preview\n\n### Testing Checklist\n\nAfter the registry change, verify:\n\n- icon display in the file browser\n- file opening in the expected viewer\n- shared toolbar behavior if the preview uses `ViewerControls`\n- conversion output if the format is server-converted\n- gallery inclusion for image formats\n- MIME type behavior across extension variants such as upper-case filenames\n- download behavior with the correct MIME type\n- mobile and tablet behavior when the preview is expected to work there\n\nFor server-converted formats, also verify:\n\n- the backend returns the converted MIME type you expect\n- transparency-sensitive formats still render correctly\n- resizing or quality settings do not degrade the preview contract unexpectedly\n- environment-specific format support failures surface in a controlled way\n\nFor preprocessable formats, also verify:\n\n- the registry recognizes the extension regardless of case and leading-dot differences\n- the expected preprocessor is selected for that format\n- missing external-tool support fails cleanly\n- validation and timeout rules behave as intended under bad inputs and slow conversions\n\n### Architecture Notes\n\nThese helper functions are the practical integration points contributors usually touch:\n\n- backend: `get_mime_type`, `needs_processing`, `is_image_file`, `get_file_type_by_extension`, `get_file_type_by_mime`\n- frontend: `getViewerComponent`, `isImageFile`, `getFileIcon`, `getFileTypeByExtension`, `getFileTypeByMime`\n\nAt runtime, the flow is:\n\n1. the backend lists files and assigns MIME information\n2. the frontend receives `FileInfo` data with that MIME information\n3. the frontend chooses icon treatment from filename and type rules\n4. the frontend selects the viewer from MIME and file-type data\n5. the backend routes convertible images through the image-conversion pipeline when needed\n\nThe frontend side still has work to do even when the backend owns the conversion:\n\n- viewer MIME recognition must include the input formats the backend classifies as previewable\n- file-type icon and color treatment must still reflect the original file type rather than the converted transport format\n- browser-side fallback MIME logic must not drift from the backend contract in ways that hide conversion bugs\n\n### Operational Characteristics\n\nServer-side conversion changes the runtime profile of preview requests.\n\n- large images can produce short CPU spikes during decode and encode\n- memory usage can rise well above compressed input size while the image is fully decoded\n- SMB-backed reads add their own latency before conversion even starts\n\nThat is why preview regressions for large HEIC or TIFF files often need both backend and user-facing verification.\n\n### Future Extension Points\n\nThe current conversion path leaves room for later enhancements such as:\n\n- caching converted preview outputs\n- queueing especially large conversions\n- dedicated thumbnail generation\n- richer multi-page image handling\n- conversion metrics for operational monitoring\n\nThose are extension points, not assumptions the current product already guarantees.\n\nThe highest-risk mistake is still registry drift. If the backend and frontend disagree about extensions or MIME types, preview behavior becomes unreliable in ways that are easy to miss until users hit them.\n\n## Common Failure Modes\n\n- backend and frontend MIME types do not match\n- a format is marked browser-native when it really needs conversion\n- a viewer component is not registered even though the type is recognized\n- a conversion change improves one format but breaks gallery behavior, download semantics, or mobile viewing\n\n## Validation Expectations\n\nWhen you change viewer or file-type behavior, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd backend \u0026\u0026 pytest -v\n```\n\nIf the change is image-conversion-specific, include the relevant backend tests around image conversion and preview behavior.\n", "0.9": "+++\ntitle = \"Viewer Architecture and Preview Contracts\"\n+++\n\nPreview behavior in Sambee is a cross-boundary contract, not just a frontend component choice.\n\n## The Core Contract\n\nThe browser app decides how to render a file based on metadata and file-type information, but that depends on server-side classification staying aligned.\n\nThree rules matter most:\n\n- the backend and frontend file-type registries must describe the same extensions and MIME types\n- the backend decides whether an image format needs server-side conversion for browser compatibility\n- the frontend chooses the right viewer component and file icon based on the effective file type and MIME information it receives\n\n## Where the Main Decisions Live\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | backend source of truth for extensions, MIME types, categories, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | frontend source of truth for extensions, MIME types, categories, viewer components, icons, and colors |\n| `frontend/src/components/Viewer/` | viewer components and shared viewer UI |\n| `backend/app/services/image_converter.py` | server-side conversion for non-browser-native image formats |\n\n## Viewer Selection Model\n\nAt a high level, the preview pipeline works like this:\n\n1. the backend determines file category and MIME behavior\n2. the backend decides whether the file can stream as-is or needs image conversion\n3. the frontend maps the file type to the appropriate viewer component\n4. the shared viewer controls keep the toolbar and common behavior consistent across viewers\n\nThat is why a file-type change almost always touches both backend and frontend code.\n\n## Browser-Native Versus Server-Converted Images\n\nSambee supports both browser-native formats and formats that need server-side conversion.\n\n- browser-native formats can be sent to the viewer directly\n- non-browser-native image formats are converted on the server before the browser renders them\n- special cases such as transparency preservation can change the output format choice\n\nIf you change conversion rules, you are changing a product contract, not just an implementation detail.\n\n### Server-Side Conversion Contract\n\nThe conversion path is owned by `backend/app/services/image_converter.py` and is exercised through the viewer API.\n\nThe backend conversion service is responsible for:\n\n- deciding whether an image needs processing\n- converting unsupported or impractical browser formats into a viewer-safe output format\n- preserving transparency where the output contract requires it\n- applying optional downscaling so one preview request cannot explode memory usage casually\n- returning enough metadata for the viewer endpoint to send the correct MIME type back to the browser\n\nRepresentative service responsibilities include:\n\n- `needs_processing(filename)`\n- `convert_image_for_viewer(...)`\n- `is_image_file(filename)`\n- `get_image_info(...)`\n\nThe viewer endpoint then follows this rule:\n\n- if the image can stream safely as-is, return a streaming response\n- if it requires conversion, read it, convert it, and return the converted bytes with the converted MIME type\n\nThat means preview behavior for formats such as TIFF, HEIC, BMP, ICO, and similar formats depends on backend conversion policy, not just on frontend MIME recognition.\n\n### Local-Drive Preview Policy\n\nThe Companion serves local-drive files and archive members as raw bytes. It does not copy local content to the backend for processing and does not bundle the backend image or PDF processing stack.\n\n- Browser-native images, text files, and original PDFs can preview from their raw local bytes.\n- Image formats that require server-side conversion, such as TIFF, HEIC, PSD, JPEG XL, and scientific image formats, show an explicit preview-unavailable state for local drives.\n- Image resizing and PDF compatibility normalization are unavailable for local drives.\n- Downloading and opening the original file locally remain available when a local preview is unavailable.\n\nThe frontend resolves these capabilities before making a local viewer request. Local archive-member requests use the Companion's strict raw-stream contract, while SMB archive-member requests retain the full conversion and PDF-normalization request parameters.\n\n### Output Format Rules\n\nThe backend does not always convert everything to the same output type.\n\n- JPEG is the common output for opaque images\n- PNG remains important when transparency must be preserved\n- ICO-like transparency handling is therefore different from ordinary opaque-photo conversion\n- alpha-bearing formats converted to JPEG need explicit compositing behavior rather than silent accidental loss\n\nIf you change those rules, check both visual correctness and user-facing assumptions such as download behavior and gallery continuity.\n\n### Current Format-Specific Preview Semantics\n\nSeveral converted-image families have product-specific preview semantics that contributors should preserve unless the product intentionally changes.\n\n- multi-page TIFF currently previews the first page rather than exposing a document-style page stack\n- PSD and PSB preview the flattened composite instead of surfacing layer-edit semantics through the browser viewer\n- EPS and AI are rasterized through the preprocessing path at high quality, currently using the 300 DPI rendering baseline\n- HDR-oriented formats such as EXR and Radiance HDR are tone-mapped into ordinary browser-display output\n- whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF preview as an overview or first practical pyramid level rather than as a full pathology viewer\n- FITS and similar scientific-image formats apply visibility scaling so low-level pixel values become inspectable in a normal browser image surface\n\nThese are not accidental implementation details. They define what users should expect from preview and therefore belong to the product contract.\n\n### Resizing and Resource Limits\n\nServer-side conversion can consume significant memory because the file must be read, decoded, and re-encoded.\n\nThe current contract therefore includes:\n\n- configurable JPEG-quality behavior\n- maximum-dimension downscaling to avoid unbounded preview size\n- backend-side protection against excessive memory usage from large source images\n\nContributors should treat those limits as operational safety controls, not as arbitrary defaults.\n\n### Dependency and Environment Expectations\n\nThe conversion path depends on reviewed Python and system-image libraries.\n\nThat includes the normal image stack plus HEIC/HEIF support through the reviewed dependency chain and corresponding system libraries in the container or runtime image.\n\nWhen conversion support seems to disappear unexpectedly, check:\n\n- the backend Python dependency set\n- the container or host system-image libraries\n- whether the format-specific support was actually installed in the current environment\n\n### Preprocessor Registry for Exotic Formats\n\nSome formats need a preprocessing step before the normal conversion path can handle them at all.\n\nThat registry lives in:\n\n- `backend/app/services/preprocessor.py`\n\nIt is consumed by:\n\n- `backend/app/services/image_converter.py`\n\nThe preprocessor layer exists for formats that libvips should not or cannot decode directly for Sambee's preview contract.\n\nCurrent registered formats route through the ImageMagick-backed preprocessor:\n\n- `.psd`\n- `.psb`\n- `.eps`\n- `.ai`\n\nThe registry is the single source of truth for which extensions require preprocessing before the final viewer-safe conversion step.\n\nFor the backend service architecture behind that path, continue to [Image Preprocessing and Conversion Pipeline](../../backend-architecture/image-preprocessing-and-conversion-pipeline/).\n\nRepresentative registry operations include:\n\n- `PreprocessorRegistry.requires_preprocessing(extension)`\n- `PreprocessorRegistry.get_preprocessor_for_format(extension)`\n- `PreprocessorRegistry.get_supported_formats()`\n- `PreprocessorRegistry.register_format(extension, preprocessor_class)`\n\n### Preprocessor Design Rules\n\nThe preprocessor layer has its own constraints:\n\n- one registry entry per preprocessable extension\n- direct in-memory conversion to the final browser-ready format rather than chained intermediate formats\n- no shell-mediated fallback chain logic in the registry itself\n- input validation and timeout enforcement happen in the preprocessor layer\n- failures should surface as explicit preprocessing or conversion errors rather than silent format drift\n\nThe main abstraction is `PreprocessorInterface`, with `ImageMagickPreprocessor` as the current built-in implementation.\n\n### Adding a New Preprocessed Format\n\nIf a new format cannot be handled by the normal conversion stack directly:\n\n1. implement a `PreprocessorInterface` subclass if the existing preprocessor is not appropriate\n2. register the extension in `PreprocessorRegistry`\n3. add or update file-type metadata if the format becomes user-visible in preview flows\n4. add tests for format recognition, tool availability, validation, and successful conversion\n\nDo not treat preprocessable formats as ordinary file-type additions. They change the backend conversion pipeline itself.\n\n### Error Surface Contributors Must Preserve\n\nConversion failures are user-visible API behavior, not internal-only exceptions.\n\nTypical outcomes include:\n\n- not implemented when the current environment lacks support for a format family\n- unprocessable-content style failures when the file is corrupt or cannot be decoded\n- ordinary backend failures when an unexpected exception escapes the conversion path\n\nThat means error wording, status behavior, and frontend fallback behavior should be reviewed together.\n\n## Shared Viewer UI\n\nThe main viewer toolbar is intentionally centralized in `frontend/src/components/Viewer/ViewerControls.tsx`.\n\nThis is no longer just an image-and-PDF convenience component. It is the canonical control surface for the current full-screen image, PDF, and Markdown viewers.\n\n- shared toolbar layout, styling, keyboard-tooltip behavior, and responsive behavior live in `ViewerControls`\n- each viewer turns features on through configuration and passes only the state objects it needs\n- future viewers should reuse that control shell where possible instead of creating another top-level toolbar implementation\n\n### Control-Surface Model\n\n`ViewerControls` uses a feature-flag configuration plus typed state objects.\n\nThe configuration currently enables these capability groups:\n\n- `navigation` for gallery-style previous and next navigation\n- `pageNavigation` for PDF page input and page stepping\n- `zoom` for viewer-managed zoom actions\n- `rotation` for image and PDF rotation actions\n- `search` for the shared search row and match navigation affordances\n- `download` for explicit download actions\n- `share` for mobile-first share actions\n\nThe component then accepts matching state surfaces:\n\n- `NavigationState` for item index, total items, and next or previous handlers\n- `PageNavigationState` for current page, total pages, and page-change handling\n- `ZoomState` for zoom-in and zoom-out handlers\n- `RotationState` for rotate-left and rotate-right handlers\n- `SearchState` for search text, match counts, search-panel state, open or close callbacks, and viewer-specific search navigation\n\nThat split matters because `ViewerControls` owns the common UI, but it does not own viewer logic. It renders controls and delegates behavior back to the viewer that actually knows how to navigate pages, zoom, rotate, or search.\n\n### Current Consumers\n\nThe current shared-toolbar consumers are:\n\n- `ImageViewer`, which enables gallery navigation, zoom, rotation, download, and optional mobile share\n- `PDFViewer`, which enables page navigation, zoom, rotation, search, download, and optional mobile share\n- `MarkdownViewer`, which reuses the same shell for download, optional mobile share, shared search UI, and viewer-specific action buttons such as editing flows\n\n`ViewerControls` also supports generic toolbar actions through the `actions` prop, which can render either text buttons or icon buttons. That is what allows Markdown-specific actions to live inside the same shared toolbar instead of forcing a second toolbar implementation.\n\n### Search UI Versus Search Engine\n\nThe search row is shared, but the search backend is viewer-specific.\n\n- `PDFViewer` wires the search controls to PDF text extraction, page-aware match tracking, and PDF-specific next or previous navigation\n- rendered Markdown and other rendered text views can route search through the DOM text-search utility in `frontend/src/utils/domTextSearch.ts`\n- Markdown edit mode does not reuse the rendered-view DOM search implementation; it bridges the same outer toolbar UI into the editor-specific search state and commands instead\n\nThat separation is an important contract: contributors should reuse the shared search UI when possible, but should not assume every viewer can use the same search implementation under the hood.\n\n### Responsive and Accessibility Rules\n\nThe centralized toolbar also encodes product behavior that should stay consistent across viewers.\n\n- filename display, optional filename adornments, and close behavior are shared\n- mobile layout uses safe-area-aware spacing and smaller controls\n- gallery arrows and desktop zoom controls are intentionally reduced on mobile, where gesture-based interaction is preferred\n- share is exposed as a mobile-first affordance, with optional early-intent warming through `onShareIntent`\n- buttons use explicit `aria-label` values and shortcut-oriented `title` text so the control surface remains navigable and self-describing\n- the shared search row manages focus when it opens and preserves consistent close behavior for toggle and Escape-driven exits\n\n### Legacy Components and Contributor Guidance\n\nLegacy `ImageControls.tsx` and `PDFControls.tsx` files still exist in the frontend tree, but `ViewerControls` is the current architectural direction and the shared component used by the active image, PDF, and Markdown viewers.\n\nIf you add another viewer or extend an existing one:\n\n- prefer extending `ViewerControlsConfig`, the relevant state interfaces, or the generic `actions` surface\n- keep viewer-specific logic in the viewer component rather than teaching `ViewerControls` about file-format internals\n- preserve shared mobile, accessibility, and search-panel behavior unless the product intentionally changes that contract\n- add or update focused tests in `frontend/src/components/Viewer/__tests__/ViewerControls.test.tsx` when the shared toolbar contract changes\n\n## Adding a New File Type Safely\n\nFile-type support is registry-driven. The safest way to add a new type is to treat backend and frontend changes as one contract update.\n\n### Main Files to Change\n\n| Path | Why it changes |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | declare extensions, MIME types, category, description, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | declare extensions, MIME types, category, viewer component, icon, color, and description |\n| `frontend/src/components/Viewer/` | add or reuse a viewer component when the type needs a dedicated preview surface |\n\nIf a file type is user-visible, update the published support docs that describe what Sambee can preview.\n\n### Quick Start for a New Image Format\n\nFor an image format such as JPEG XL, the minimum workflow is:\n\n1. add a `FileTypeDefinition` entry to the backend registry\n2. add the matching entry to the frontend registry\n3. decide whether the image is browser-native or requires server-side conversion\n4. keep extensions and MIME types identical across both registries\n5. run the viewer and backend validation checks\n\nBackend example:\n\n```python\nFileTypeDefinition(\n\t\textensions=(\".jxl\",),\n\t\tmime_types=(\"image/jxl\",),\n\t\tcategory=FileCategory.IMAGE,\n\t\trequires_conversion=True,\n\t\tdescription=\"JPEG XL Image\",\n)\n```\n\nFrontend example:\n\n```typescript\n{\n\textensions: [\".jxl\"],\n\tmimeTypes: [\"image/jxl\"],\n\tcategory: \"image\",\n\tviewerComponent: () =\u003e import(\"../components/Viewer/ImageViewer\"),\n\ticon: \"image\",\n\tcolor: \"#a855f7\",\n\tdescription: \"JPEG XL Image\",\n}\n```\n\nThat registry update is what drives MIME matching, icon treatment, viewer routing, and image-gallery inclusion.\n\n### Backend Registry Rules\n\nBackend file-type definitions must stay explicit and type-safe.\n\n- `extensions` are tuples with a leading dot, such as `(\".jpg\", \".jpeg\")`\n- `mime_types` are tuples of standard MIME strings\n- `category` uses `FileCategory` values such as `IMAGE`, `DOCUMENT`, `TEXT`, `VIDEO`, `AUDIO`, `ARCHIVE`, `CODE`, `SPREADSHEET`, or `OTHER`\n- `requires_conversion` matters for image formats that cannot be rendered directly by the browser\n- `description` should be the human-readable label contributors and users would expect\n\nHow to decide `requires_conversion`:\n\n- set it to `False` for browser-native formats such as PNG, JPEG, GIF, WebP, SVG, and AVIF\n- set it to `True` for formats with limited browser support or formats that are not practical to render directly, such as TIFF, HEIC, BMP, JPEG 2000, or JPEG XL when browser support is not sufficient for the product baseline\n\n### Frontend Registry Rules\n\nFrontend file-type definitions control how the browser app presents the file.\n\n- keep `extensions` and `mimeTypes` aligned with the backend registry\n- set `viewerComponent` to the shared viewer that should render the type\n- choose an icon that matches the product language for that file category\n- choose a color that distinguishes the format without inventing a new palette on every addition\n\nFor image formats, reusing `ImageViewer` is usually enough. For non-image formats, you may need a dedicated viewer such as `PdfViewer`, `VideoViewer`, `AudioViewer`, or `TextViewer`.\n\n### Non-Image File Types\n\nThe overall process is the same for documents, video, audio, text, archives, and code files.\n\n1. add the backend registry entry\n2. add the frontend registry entry\n3. create or reuse the viewer component when preview support exists\n4. verify the file icon, viewer routing, and download behavior\n\nFor non-image files, `requires_conversion` is usually `False`. The main design question is whether the product has a viewer component for that category or should fall back to download-only behavior.\n\n### Integration Checklist\n\nUse this checklist before you consider the file type integrated:\n\n- backend registry entry added\n- frontend registry entry added\n- extensions and MIME types match exactly across both registries\n- browser-native versus converted-image behavior decided intentionally\n- viewer component chosen or added\n- icon and color treatment chosen\n- user-visible support docs updated if the file type changes what Sambee can preview\n\n### Testing Checklist\n\nAfter the registry change, verify:\n\n- icon display in the file browser\n- file opening in the expected viewer\n- shared toolbar behavior if the preview uses `ViewerControls`\n- conversion output if the format is server-converted\n- gallery inclusion for image formats\n- MIME type behavior across extension variants such as upper-case filenames\n- download behavior with the correct MIME type\n- mobile and tablet behavior when the preview is expected to work there\n\nFor server-converted formats, also verify:\n\n- the backend returns the converted MIME type you expect\n- transparency-sensitive formats still render correctly\n- resizing or quality settings do not degrade the preview contract unexpectedly\n- environment-specific format support failures surface in a controlled way\n\nFor preprocessable formats, also verify:\n\n- the registry recognizes the extension regardless of case and leading-dot differences\n- the expected preprocessor is selected for that format\n- missing external-tool support fails cleanly\n- validation and timeout rules behave as intended under bad inputs and slow conversions\n\n### Architecture Notes\n\nThese helper functions are the practical integration points contributors usually touch:\n\n- backend: `get_mime_type`, `needs_processing`, `is_image_file`, `get_file_type_by_extension`, `get_file_type_by_mime`\n- frontend: `getViewerComponent`, `isImageFile`, `getFileIcon`, `getFileTypeByExtension`, `getFileTypeByMime`\n\nAt runtime, the flow is:\n\n1. the backend lists files and assigns MIME information\n2. the frontend receives `FileInfo` data with that MIME information\n3. the frontend chooses icon treatment from filename and type rules\n4. the frontend selects the viewer from MIME and file-type data\n5. the backend routes convertible images through the image-conversion pipeline when needed\n\nThe frontend side still has work to do even when the backend owns the conversion:\n\n- viewer MIME recognition must include the input formats the backend classifies as previewable\n- file-type icon and color treatment must still reflect the original file type rather than the converted transport format\n- browser-side fallback MIME logic must not drift from the backend contract in ways that hide conversion bugs\n\n### Operational Characteristics\n\nServer-side conversion changes the runtime profile of preview requests.\n\n- large images can produce short CPU spikes during decode and encode\n- memory usage can rise well above compressed input size while the image is fully decoded\n- SMB-backed reads add their own latency before conversion even starts\n\nThat is why preview regressions for large HEIC or TIFF files often need both backend and user-facing verification.\n\n### Future Extension Points\n\nThe current conversion path leaves room for later enhancements such as:\n\n- caching converted preview outputs\n- queueing especially large conversions\n- dedicated thumbnail generation\n- richer multi-page image handling\n- conversion metrics for operational monitoring\n\nThose are extension points, not assumptions the current product already guarantees.\n\nThe highest-risk mistake is still registry drift. If the backend and frontend disagree about extensions or MIME types, preview behavior becomes unreliable in ways that are easy to miss until users hit them.\n\n## Common Failure Modes\n\n- backend and frontend MIME types do not match\n- a format is marked browser-native when it really needs conversion\n- a viewer component is not registered even though the type is recognized\n- a conversion change improves one format but breaks gallery behavior, download semantics, or mobile viewing\n\n## Validation Expectations\n\nWhen you change viewer or file-type behavior, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd backend \u0026\u0026 pytest -v\n```\n\nIf the change is image-conversion-specific, include the relevant backend tests around image conversion and preview behavior.\n", "1.0": "+++\ntitle = \"Viewer Architecture and Preview Contracts\"\n+++\n\nPreview behavior in Sambee is a cross-boundary contract, not just a frontend component choice.\n\n## The Core Contract\n\nThe browser app decides how to render a file based on metadata and file-type information, but that depends on server-side classification staying aligned.\n\nThree rules matter most:\n\n- the backend and frontend file-type registries must describe the same extensions and MIME types\n- the backend decides whether an image format needs server-side conversion for browser compatibility\n- the frontend chooses the right viewer component and file icon based on the effective file type and MIME information it receives\n\n## Where the Main Decisions Live\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | backend source of truth for extensions, MIME types, categories, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | frontend source of truth for extensions, MIME types, categories, viewer components, icons, and colors |\n| `frontend/src/components/Viewer/` | viewer components and shared viewer UI |\n| `backend/app/services/image_converter.py` | server-side conversion for non-browser-native image formats |\n\n## Viewer Selection Model\n\nAt a high level, the preview pipeline works like this:\n\n1. the backend determines file category and MIME behavior\n2. the backend decides whether the file can stream as-is or needs image conversion\n3. the frontend maps the file type to the appropriate viewer component\n4. the shared viewer controls keep the toolbar and common behavior consistent across viewers\n\nThat is why a file-type change almost always touches both backend and frontend code.\n\n## Browser-Native Versus Server-Converted Images\n\nSambee supports both browser-native formats and formats that need server-side conversion.\n\n- browser-native formats can be sent to the viewer directly\n- non-browser-native image formats are converted on the server before the browser renders them\n- special cases such as transparency preservation can change the output format choice\n\nIf you change conversion rules, you are changing a product contract, not just an implementation detail.\n\n### Server-Side Conversion Contract\n\nThe conversion path is owned by `backend/app/services/image_converter.py` and is exercised through the viewer API.\n\nThe backend conversion service is responsible for:\n\n- deciding whether an image needs processing\n- converting unsupported or impractical browser formats into a viewer-safe output format\n- preserving transparency where the output contract requires it\n- applying optional downscaling so one preview request cannot explode memory usage casually\n- returning enough metadata for the viewer endpoint to send the correct MIME type back to the browser\n\nRepresentative service responsibilities include:\n\n- `needs_processing(filename)`\n- `convert_image_for_viewer(...)`\n- `is_image_file(filename)`\n- `get_image_info(...)`\n\nThe viewer endpoint then follows this rule:\n\n- if the image can stream safely as-is, return a streaming response\n- if it requires conversion, read it, convert it, and return the converted bytes with the converted MIME type\n\nThat means preview behavior for formats such as TIFF, HEIC, BMP, ICO, and similar formats depends on backend conversion policy, not just on frontend MIME recognition.\n\n### Local-Drive Preview Policy\n\nThe Companion serves local-drive files and archive members as raw bytes. It does not copy local content to the backend for processing and does not bundle the backend image or PDF processing stack.\n\n- Browser-native images, text files, and original PDFs can preview from their raw local bytes.\n- Image formats that require server-side conversion, such as TIFF, HEIC, PSD, JPEG XL, and scientific image formats, show an explicit preview-unavailable state for local drives.\n- Image resizing and PDF compatibility normalization are unavailable for local drives.\n- Downloading and opening the original file locally remain available when a local preview is unavailable.\n\nThe frontend resolves these capabilities before making a local viewer request. Local archive-member requests use the Companion's strict raw-stream contract, while SMB archive-member requests retain the full conversion and PDF-normalization request parameters.\n\n### Output Format Rules\n\nThe backend does not always convert everything to the same output type.\n\n- JPEG is the common output for opaque images\n- PNG remains important when transparency must be preserved\n- ICO-like transparency handling is therefore different from ordinary opaque-photo conversion\n- alpha-bearing formats converted to JPEG need explicit compositing behavior rather than silent accidental loss\n\nIf you change those rules, check both visual correctness and user-facing assumptions such as download behavior and gallery continuity.\n\n### Current Format-Specific Preview Semantics\n\nSeveral converted-image families have product-specific preview semantics that contributors should preserve unless the product intentionally changes.\n\n- multi-page TIFF currently previews the first page rather than exposing a document-style page stack\n- PSD and PSB preview the flattened composite instead of surfacing layer-edit semantics through the browser viewer\n- EPS and AI are rasterized through the preprocessing path at high quality, currently using the 300 DPI rendering baseline\n- HDR-oriented formats such as EXR and Radiance HDR are tone-mapped into ordinary browser-display output\n- whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF preview as an overview or first practical pyramid level rather than as a full pathology viewer\n- FITS and similar scientific-image formats apply visibility scaling so low-level pixel values become inspectable in a normal browser image surface\n\nThese are not accidental implementation details. They define what users should expect from preview and therefore belong to the product contract.\n\n### Resizing and Resource Limits\n\nServer-side conversion can consume significant memory because the file must be read, decoded, and re-encoded.\n\nThe current contract therefore includes:\n\n- configurable JPEG-quality behavior\n- maximum-dimension downscaling to avoid unbounded preview size\n- backend-side protection against excessive memory usage from large source images\n\nContributors should treat those limits as operational safety controls, not as arbitrary defaults.\n\n### Dependency and Environment Expectations\n\nThe conversion path depends on reviewed Python and system-image libraries.\n\nThat includes the normal image stack plus HEIC/HEIF support through the reviewed dependency chain and corresponding system libraries in the container or runtime image.\n\nWhen conversion support seems to disappear unexpectedly, check:\n\n- the backend Python dependency set\n- the container or host system-image libraries\n- whether the format-specific support was actually installed in the current environment\n\n### Preprocessor Registry for Exotic Formats\n\nSome formats need a preprocessing step before the normal conversion path can handle them at all.\n\nThat registry lives in:\n\n- `backend/app/services/preprocessor.py`\n\nIt is consumed by:\n\n- `backend/app/services/image_converter.py`\n\nThe preprocessor layer exists for formats that libvips should not or cannot decode directly for Sambee's preview contract.\n\nCurrent registered formats route through the ImageMagick-backed preprocessor:\n\n- `.psd`\n- `.psb`\n- `.eps`\n- `.ai`\n\nThe registry is the single source of truth for which extensions require preprocessing before the final viewer-safe conversion step.\n\nFor the backend service architecture behind that path, continue to [Image Preprocessing and Conversion Pipeline](../../backend-architecture/image-preprocessing-and-conversion-pipeline/).\n\nRepresentative registry operations include:\n\n- `PreprocessorRegistry.requires_preprocessing(extension)`\n- `PreprocessorRegistry.get_preprocessor_for_format(extension)`\n- `PreprocessorRegistry.get_supported_formats()`\n- `PreprocessorRegistry.register_format(extension, preprocessor_class)`\n\n### Preprocessor Design Rules\n\nThe preprocessor layer has its own constraints:\n\n- one registry entry per preprocessable extension\n- direct in-memory conversion to the final browser-ready format rather than chained intermediate formats\n- no shell-mediated fallback chain logic in the registry itself\n- input validation and timeout enforcement happen in the preprocessor layer\n- failures should surface as explicit preprocessing or conversion errors rather than silent format drift\n\nThe main abstraction is `PreprocessorInterface`, with `ImageMagickPreprocessor` as the current built-in implementation.\n\n### Adding a New Preprocessed Format\n\nIf a new format cannot be handled by the normal conversion stack directly:\n\n1. implement a `PreprocessorInterface` subclass if the existing preprocessor is not appropriate\n2. register the extension in `PreprocessorRegistry`\n3. add or update file-type metadata if the format becomes user-visible in preview flows\n4. add tests for format recognition, tool availability, validation, and successful conversion\n\nDo not treat preprocessable formats as ordinary file-type additions. They change the backend conversion pipeline itself.\n\n### Error Surface Contributors Must Preserve\n\nConversion failures are user-visible API behavior, not internal-only exceptions.\n\nTypical outcomes include:\n\n- not implemented when the current environment lacks support for a format family\n- unprocessable-content style failures when the file is corrupt or cannot be decoded\n- ordinary backend failures when an unexpected exception escapes the conversion path\n\nThat means error wording, status behavior, and frontend fallback behavior should be reviewed together.\n\n## Shared Viewer UI\n\nThe main viewer toolbar is intentionally centralized in `frontend/src/components/Viewer/ViewerControls.tsx`.\n\nThis is no longer just an image-and-PDF convenience component. It is the canonical control surface for the current full-screen image, PDF, and Markdown viewers.\n\n- shared toolbar layout, styling, keyboard-tooltip behavior, and responsive behavior live in `ViewerControls`\n- each viewer turns features on through configuration and passes only the state objects it needs\n- future viewers should reuse that control shell where possible instead of creating another top-level toolbar implementation\n\n### Control-Surface Model\n\n`ViewerControls` uses a feature-flag configuration plus typed state objects.\n\nThe configuration currently enables these capability groups:\n\n- `navigation` for gallery-style previous and next navigation\n- `pageNavigation` for PDF page input and page stepping\n- `zoom` for viewer-managed zoom actions\n- `rotation` for image and PDF rotation actions\n- `search` for the shared search row and match navigation affordances\n- `download` for explicit download actions\n- `share` for mobile-first share actions\n\nThe component then accepts matching state surfaces:\n\n- `NavigationState` for item index, total items, and next or previous handlers\n- `PageNavigationState` for current page, total pages, and page-change handling\n- `ZoomState` for zoom-in and zoom-out handlers\n- `RotationState` for rotate-left and rotate-right handlers\n- `SearchState` for search text, match counts, search-panel state, open or close callbacks, and viewer-specific search navigation\n\nThat split matters because `ViewerControls` owns the common UI, but it does not own viewer logic. It renders controls and delegates behavior back to the viewer that actually knows how to navigate pages, zoom, rotate, or search.\n\n### Current Consumers\n\nThe current shared-toolbar consumers are:\n\n- `ImageViewer`, which enables gallery navigation, zoom, rotation, download, and optional mobile share\n- `PDFViewer`, which enables page navigation, zoom, rotation, search, download, and optional mobile share\n- `MarkdownViewer`, which reuses the same shell for download, optional mobile share, shared search UI, and viewer-specific action buttons such as editing flows\n\n`ViewerControls` also supports generic toolbar actions through the `actions` prop, which can render either text buttons or icon buttons. That is what allows Markdown-specific actions to live inside the same shared toolbar instead of forcing a second toolbar implementation.\n\n### Search UI Versus Search Engine\n\nThe search row is shared, but the search backend is viewer-specific.\n\n- `PDFViewer` wires the search controls to PDF text extraction, page-aware match tracking, and PDF-specific next or previous navigation\n- rendered Markdown and other rendered text views can route search through the DOM text-search utility in `frontend/src/utils/domTextSearch.ts`\n- Markdown edit mode does not reuse the rendered-view DOM search implementation; it bridges the same outer toolbar UI into the editor-specific search state and commands instead\n\nThat separation is an important contract: contributors should reuse the shared search UI when possible, but should not assume every viewer can use the same search implementation under the hood.\n\n### Responsive and Accessibility Rules\n\nThe centralized toolbar also encodes product behavior that should stay consistent across viewers.\n\n- filename display, optional filename adornments, and close behavior are shared\n- mobile layout uses safe-area-aware spacing and smaller controls\n- gallery arrows and desktop zoom controls are intentionally reduced on mobile, where gesture-based interaction is preferred\n- share is exposed as a mobile-first affordance, with optional early-intent warming through `onShareIntent`\n- buttons use explicit `aria-label` values and shortcut-oriented `title` text so the control surface remains navigable and self-describing\n- the shared search row manages focus when it opens and preserves consistent close behavior for toggle and Escape-driven exits\n\n### Legacy Components and Contributor Guidance\n\nLegacy `ImageControls.tsx` and `PDFControls.tsx` files still exist in the frontend tree, but `ViewerControls` is the current architectural direction and the shared component used by the active image, PDF, and Markdown viewers.\n\nIf you add another viewer or extend an existing one:\n\n- prefer extending `ViewerControlsConfig`, the relevant state interfaces, or the generic `actions` surface\n- keep viewer-specific logic in the viewer component rather than teaching `ViewerControls` about file-format internals\n- preserve shared mobile, accessibility, and search-panel behavior unless the product intentionally changes that contract\n- add or update focused tests in `frontend/src/components/Viewer/__tests__/ViewerControls.test.tsx` when the shared toolbar contract changes\n\n## Adding a New File Type Safely\n\nFile-type support is registry-driven. The safest way to add a new type is to treat backend and frontend changes as one contract update.\n\n### Main Files to Change\n\n| Path | Why it changes |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | declare extensions, MIME types, category, description, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | declare extensions, MIME types, category, viewer component, icon, color, and description |\n| `frontend/src/components/Viewer/` | add or reuse a viewer component when the type needs a dedicated preview surface |\n\nIf a file type is user-visible, update the published support docs that describe what Sambee can preview.\n\n### Quick Start for a New Image Format\n\nFor an image format such as JPEG XL, the minimum workflow is:\n\n1. add a `FileTypeDefinition` entry to the backend registry\n2. add the matching entry to the frontend registry\n3. decide whether the image is browser-native or requires server-side conversion\n4. keep extensions and MIME types identical across both registries\n5. run the viewer and backend validation checks\n\nBackend example:\n\n```python\nFileTypeDefinition(\n\t\textensions=(\".jxl\",),\n\t\tmime_types=(\"image/jxl\",),\n\t\tcategory=FileCategory.IMAGE,\n\t\trequires_conversion=True,\n\t\tdescription=\"JPEG XL Image\",\n)\n```\n\nFrontend example:\n\n```typescript\n{\n\textensions: [\".jxl\"],\n\tmimeTypes: [\"image/jxl\"],\n\tcategory: \"image\",\n\tviewerComponent: () =\u003e import(\"../components/Viewer/ImageViewer\"),\n\ticon: \"image\",\n\tcolor: \"#a855f7\",\n\tdescription: \"JPEG XL Image\",\n}\n```\n\nThat registry update is what drives MIME matching, icon treatment, viewer routing, and image-gallery inclusion.\n\n### Backend Registry Rules\n\nBackend file-type definitions must stay explicit and type-safe.\n\n- `extensions` are tuples with a leading dot, such as `(\".jpg\", \".jpeg\")`\n- `mime_types` are tuples of standard MIME strings\n- `category` uses `FileCategory` values such as `IMAGE`, `DOCUMENT`, `TEXT`, `VIDEO`, `AUDIO`, `ARCHIVE`, `CODE`, `SPREADSHEET`, or `OTHER`\n- `requires_conversion` matters for image formats that cannot be rendered directly by the browser\n- `description` should be the human-readable label contributors and users would expect\n\nHow to decide `requires_conversion`:\n\n- set it to `False` for browser-native formats such as PNG, JPEG, GIF, WebP, SVG, and AVIF\n- set it to `True` for formats with limited browser support or formats that are not practical to render directly, such as TIFF, HEIC, BMP, JPEG 2000, or JPEG XL when browser support is not sufficient for the product baseline\n\n### Frontend Registry Rules\n\nFrontend file-type definitions control how the browser app presents the file.\n\n- keep `extensions` and `mimeTypes` aligned with the backend registry\n- set `viewerComponent` to the shared viewer that should render the type\n- choose an icon that matches the product language for that file category\n- choose a color that distinguishes the format without inventing a new palette on every addition\n\nFor image formats, reusing `ImageViewer` is usually enough. For non-image formats, you may need a dedicated viewer such as `PdfViewer`, `VideoViewer`, `AudioViewer`, or `TextViewer`.\n\n### Non-Image File Types\n\nThe overall process is the same for documents, video, audio, text, archives, and code files.\n\n1. add the backend registry entry\n2. add the frontend registry entry\n3. create or reuse the viewer component when preview support exists\n4. verify the file icon, viewer routing, and download behavior\n\nFor non-image files, `requires_conversion` is usually `False`. The main design question is whether the product has a viewer component for that category or should fall back to download-only behavior.\n\n### Integration Checklist\n\nUse this checklist before you consider the file type integrated:\n\n- backend registry entry added\n- frontend registry entry added\n- extensions and MIME types match exactly across both registries\n- browser-native versus converted-image behavior decided intentionally\n- viewer component chosen or added\n- icon and color treatment chosen\n- user-visible support docs updated if the file type changes what Sambee can preview\n\n### Testing Checklist\n\nAfter the registry change, verify:\n\n- icon display in the file browser\n- file opening in the expected viewer\n- shared toolbar behavior if the preview uses `ViewerControls`\n- conversion output if the format is server-converted\n- gallery inclusion for image formats\n- MIME type behavior across extension variants such as upper-case filenames\n- download behavior with the correct MIME type\n- mobile and tablet behavior when the preview is expected to work there\n\nFor server-converted formats, also verify:\n\n- the backend returns the converted MIME type you expect\n- transparency-sensitive formats still render correctly\n- resizing or quality settings do not degrade the preview contract unexpectedly\n- environment-specific format support failures surface in a controlled way\n\nFor preprocessable formats, also verify:\n\n- the registry recognizes the extension regardless of case and leading-dot differences\n- the expected preprocessor is selected for that format\n- missing external-tool support fails cleanly\n- validation and timeout rules behave as intended under bad inputs and slow conversions\n\n### Architecture Notes\n\nThese helper functions are the practical integration points contributors usually touch:\n\n- backend: `get_mime_type`, `needs_processing`, `is_image_file`, `get_file_type_by_extension`, `get_file_type_by_mime`\n- frontend: `getViewerComponent`, `isImageFile`, `getFileIcon`, `getFileTypeByExtension`, `getFileTypeByMime`\n\nAt runtime, the flow is:\n\n1. the backend lists files and assigns MIME information\n2. the frontend receives `FileInfo` data with that MIME information\n3. the frontend chooses icon treatment from filename and type rules\n4. the frontend selects the viewer from MIME and file-type data\n5. the backend routes convertible images through the image-conversion pipeline when needed\n\nThe frontend side still has work to do even when the backend owns the conversion:\n\n- viewer MIME recognition must include the input formats the backend classifies as previewable\n- file-type icon and color treatment must still reflect the original file type rather than the converted transport format\n- browser-side fallback MIME logic must not drift from the backend contract in ways that hide conversion bugs\n\n### Operational Characteristics\n\nServer-side conversion changes the runtime profile of preview requests.\n\n- large images can produce short CPU spikes during decode and encode\n- memory usage can rise well above compressed input size while the image is fully decoded\n- SMB-backed reads add their own latency before conversion even starts\n\nThat is why preview regressions for large HEIC or TIFF files often need both backend and user-facing verification.\n\n### Future Extension Points\n\nThe current conversion path leaves room for later enhancements such as:\n\n- caching converted preview outputs\n- queueing especially large conversions\n- dedicated thumbnail generation\n- richer multi-page image handling\n- conversion metrics for operational monitoring\n\nThose are extension points, not assumptions the current product already guarantees.\n\nThe highest-risk mistake is still registry drift. If the backend and frontend disagree about extensions or MIME types, preview behavior becomes unreliable in ways that are easy to miss until users hit them.\n\n## Common Failure Modes\n\n- backend and frontend MIME types do not match\n- a format is marked browser-native when it really needs conversion\n- a viewer component is not registered even though the type is recognized\n- a conversion change improves one format but breaks gallery behavior, download semantics, or mobile viewing\n\n## Validation Expectations\n\nWhen you change viewer or file-type behavior, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd backend \u0026\u0026 pytest -v\n```\n\nIf the change is image-conversion-specific, include the relevant backend tests around image conversion and preview behavior.\n", "2.0": "+++\ntitle = \"Viewer Architecture and Preview Contracts\"\n+++\n\nPreview behavior in Sambee is a cross-boundary contract, not just a frontend component choice.\n\n## The Core Contract\n\nThe browser app decides how to render a file based on metadata and file-type information, but that depends on server-side classification staying aligned.\n\nThree rules matter most:\n\n- the backend and frontend file-type registries must describe the same extensions and MIME types\n- the backend decides whether an image format needs server-side conversion for browser compatibility\n- the frontend chooses the right viewer component and file icon based on the effective file type and MIME information it receives\n\n## Where the Main Decisions Live\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | backend source of truth for extensions, MIME types, categories, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | frontend source of truth for extensions, MIME types, categories, viewer components, icons, and colors |\n| `frontend/src/components/Viewer/` | viewer components and shared viewer UI |\n| `backend/app/services/image_converter.py` | server-side conversion for non-browser-native image formats |\n\n## Viewer Selection Model\n\nAt a high level, the preview pipeline works like this:\n\n1. the backend determines file category and MIME behavior\n2. the backend decides whether the file can stream as-is or needs image conversion\n3. the frontend maps the file type to the appropriate viewer component\n4. the shared viewer controls keep the toolbar and common behavior consistent across viewers\n\nThat is why a file-type change almost always touches both backend and frontend code.\n\n## Browser-Native Versus Server-Converted Images\n\nSambee supports both browser-native formats and formats that need server-side conversion.\n\n- browser-native formats can be sent to the viewer directly\n- non-browser-native image formats are converted on the server before the browser renders them\n- special cases such as transparency preservation can change the output format choice\n\nIf you change conversion rules, you are changing a product contract, not just an implementation detail.\n\n### Server-Side Conversion Contract\n\nThe conversion path is owned by `backend/app/services/image_converter.py` and is exercised through the viewer API.\n\nThe backend conversion service is responsible for:\n\n- deciding whether an image needs processing\n- converting unsupported or impractical browser formats into a viewer-safe output format\n- preserving transparency where the output contract requires it\n- applying optional downscaling so one preview request cannot explode memory usage casually\n- returning enough metadata for the viewer endpoint to send the correct MIME type back to the browser\n\nRepresentative service responsibilities include:\n\n- `needs_processing(filename)`\n- `convert_image_for_viewer(...)`\n- `is_image_file(filename)`\n- `get_image_info(...)`\n\nThe viewer endpoint then follows this rule:\n\n- if the image can stream safely as-is, return a streaming response\n- if it requires conversion, read it, convert it, and return the converted bytes with the converted MIME type\n\nThat means preview behavior for formats such as TIFF, HEIC, BMP, ICO, and similar formats depends on backend conversion policy, not just on frontend MIME recognition.\n\n### Local-Drive Preview Policy\n\nThe Companion serves local-drive files and archive members as raw bytes. It does not copy local content to the backend for processing and does not bundle the backend image or PDF processing stack.\n\n- Browser-native images, text files, and original PDFs can preview from their raw local bytes.\n- Image formats that require server-side conversion, such as TIFF, HEIC, PSD, JPEG XL, and scientific image formats, show an explicit preview-unavailable state for local drives.\n- Image resizing and PDF compatibility normalization are unavailable for local drives.\n- Downloading and opening the original file locally remain available when a local preview is unavailable.\n\nThe frontend resolves these capabilities before making a local viewer request. Local archive-member requests use the Companion's strict raw-stream contract, while SMB archive-member requests retain the full conversion and PDF-normalization request parameters.\n\n### Output Format Rules\n\nThe backend does not always convert everything to the same output type.\n\n- JPEG is the common output for opaque images\n- PNG remains important when transparency must be preserved\n- ICO-like transparency handling is therefore different from ordinary opaque-photo conversion\n- alpha-bearing formats converted to JPEG need explicit compositing behavior rather than silent accidental loss\n\nIf you change those rules, check both visual correctness and user-facing assumptions such as download behavior and gallery continuity.\n\n### Current Format-Specific Preview Semantics\n\nSeveral converted-image families have product-specific preview semantics that contributors should preserve unless the product intentionally changes.\n\n- multi-page TIFF currently previews the first page rather than exposing a document-style page stack\n- PSD and PSB preview the flattened composite instead of surfacing layer-edit semantics through the browser viewer\n- EPS and AI are rasterized through the preprocessing path at high quality, currently using the 300 DPI rendering baseline\n- HDR-oriented formats such as EXR and Radiance HDR are tone-mapped into ordinary browser-display output\n- whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF preview as an overview or first practical pyramid level rather than as a full pathology viewer\n- FITS and similar scientific-image formats apply visibility scaling so low-level pixel values become inspectable in a normal browser image surface\n\nThese are not accidental implementation details. They define what users should expect from preview and therefore belong to the product contract.\n\n### Resizing and Resource Limits\n\nServer-side conversion can consume significant memory because the file must be read, decoded, and re-encoded.\n\nThe current contract therefore includes:\n\n- configurable JPEG-quality behavior\n- maximum-dimension downscaling to avoid unbounded preview size\n- backend-side protection against excessive memory usage from large source images\n\nContributors should treat those limits as operational safety controls, not as arbitrary defaults.\n\n### Dependency and Environment Expectations\n\nThe conversion path depends on reviewed Python and system-image libraries.\n\nThat includes the normal image stack plus HEIC/HEIF support through the reviewed dependency chain and corresponding system libraries in the container or runtime image.\n\nWhen conversion support seems to disappear unexpectedly, check:\n\n- the backend Python dependency set\n- the container or host system-image libraries\n- whether the format-specific support was actually installed in the current environment\n\n### Preprocessor Registry for Exotic Formats\n\nSome formats need a preprocessing step before the normal conversion path can handle them at all.\n\nThat registry lives in:\n\n- `backend/app/services/preprocessor.py`\n\nIt is consumed by:\n\n- `backend/app/services/image_converter.py`\n\nThe preprocessor layer exists for formats that libvips should not or cannot decode directly for Sambee's preview contract.\n\nCurrent registered formats route through the ImageMagick-backed preprocessor:\n\n- `.psd`\n- `.psb`\n- `.eps`\n- `.ai`\n\nThe registry is the single source of truth for which extensions require preprocessing before the final viewer-safe conversion step.\n\nFor the backend service architecture behind that path, continue to [Image Preprocessing and Conversion Pipeline](../../backend-architecture/image-preprocessing-and-conversion-pipeline/).\n\nRepresentative registry operations include:\n\n- `PreprocessorRegistry.requires_preprocessing(extension)`\n- `PreprocessorRegistry.get_preprocessor_for_format(extension)`\n- `PreprocessorRegistry.get_supported_formats()`\n- `PreprocessorRegistry.register_format(extension, preprocessor_class)`\n\n### Preprocessor Design Rules\n\nThe preprocessor layer has its own constraints:\n\n- one registry entry per preprocessable extension\n- direct in-memory conversion to the final browser-ready format rather than chained intermediate formats\n- no shell-mediated fallback chain logic in the registry itself\n- input validation and timeout enforcement happen in the preprocessor layer\n- failures should surface as explicit preprocessing or conversion errors rather than silent format drift\n\nThe main abstraction is `PreprocessorInterface`, with `ImageMagickPreprocessor` as the current built-in implementation.\n\n### Adding a New Preprocessed Format\n\nIf a new format cannot be handled by the normal conversion stack directly:\n\n1. implement a `PreprocessorInterface` subclass if the existing preprocessor is not appropriate\n2. register the extension in `PreprocessorRegistry`\n3. add or update file-type metadata if the format becomes user-visible in preview flows\n4. add tests for format recognition, tool availability, validation, and successful conversion\n\nDo not treat preprocessable formats as ordinary file-type additions. They change the backend conversion pipeline itself.\n\n### Error Surface Contributors Must Preserve\n\nConversion failures are user-visible API behavior, not internal-only exceptions.\n\nTypical outcomes include:\n\n- not implemented when the current environment lacks support for a format family\n- unprocessable-content style failures when the file is corrupt or cannot be decoded\n- ordinary backend failures when an unexpected exception escapes the conversion path\n\nThat means error wording, status behavior, and frontend fallback behavior should be reviewed together.\n\n## Shared Viewer UI\n\nThe main viewer toolbar is intentionally centralized in `frontend/src/components/Viewer/ViewerControls.tsx`.\n\nThis is no longer just an image-and-PDF convenience component. It is the canonical control surface for the current full-screen image, PDF, and Markdown viewers.\n\n- shared toolbar layout, styling, keyboard-tooltip behavior, and responsive behavior live in `ViewerControls`\n- each viewer turns features on through configuration and passes only the state objects it needs\n- future viewers should reuse that control shell where possible instead of creating another top-level toolbar implementation\n\n### Control-Surface Model\n\n`ViewerControls` uses a feature-flag configuration plus typed state objects.\n\nThe configuration currently enables these capability groups:\n\n- `navigation` for gallery-style previous and next navigation\n- `pageNavigation` for PDF page input and page stepping\n- `zoom` for viewer-managed zoom actions\n- `rotation` for image and PDF rotation actions\n- `search` for the shared search row and match navigation affordances\n- `download` for explicit download actions\n- `share` for mobile-first share actions\n\nThe component then accepts matching state surfaces:\n\n- `NavigationState` for item index, total items, and next or previous handlers\n- `PageNavigationState` for current page, total pages, and page-change handling\n- `ZoomState` for zoom-in and zoom-out handlers\n- `RotationState` for rotate-left and rotate-right handlers\n- `SearchState` for search text, match counts, search-panel state, open or close callbacks, and viewer-specific search navigation\n\nThat split matters because `ViewerControls` owns the common UI, but it does not own viewer logic. It renders controls and delegates behavior back to the viewer that actually knows how to navigate pages, zoom, rotate, or search.\n\n### Current Consumers\n\nThe current shared-toolbar consumers are:\n\n- `ImageViewer`, which enables gallery navigation, zoom, rotation, download, and optional mobile share\n- `PDFViewer`, which enables page navigation, zoom, rotation, search, download, and optional mobile share\n- `MarkdownViewer`, which reuses the same shell for download, optional mobile share, shared search UI, and viewer-specific action buttons such as editing flows\n\n`ViewerControls` also supports generic toolbar actions through the `actions` prop, which can render either text buttons or icon buttons. That is what allows Markdown-specific actions to live inside the same shared toolbar instead of forcing a second toolbar implementation.\n\n### Search UI Versus Search Engine\n\nThe search row is shared, but the search backend is viewer-specific.\n\n- `PDFViewer` wires the search controls to PDF text extraction, page-aware match tracking, and PDF-specific next or previous navigation\n- rendered Markdown and other rendered text views can route search through the DOM text-search utility in `frontend/src/utils/domTextSearch.ts`\n- Markdown edit mode does not reuse the rendered-view DOM search implementation; it bridges the same outer toolbar UI into the editor-specific search state and commands instead\n\nThat separation is an important contract: contributors should reuse the shared search UI when possible, but should not assume every viewer can use the same search implementation under the hood.\n\n### Responsive and Accessibility Rules\n\nThe centralized toolbar also encodes product behavior that should stay consistent across viewers.\n\n- filename display, optional filename adornments, and close behavior are shared\n- mobile layout uses safe-area-aware spacing and smaller controls\n- gallery arrows and desktop zoom controls are intentionally reduced on mobile, where gesture-based interaction is preferred\n- share is exposed as a mobile-first affordance, with optional early-intent warming through `onShareIntent`\n- buttons use explicit `aria-label` values and shortcut-oriented `title` text so the control surface remains navigable and self-describing\n- the shared search row manages focus when it opens and preserves consistent close behavior for toggle and Escape-driven exits\n\n### Legacy Components and Contributor Guidance\n\nLegacy `ImageControls.tsx` and `PDFControls.tsx` files still exist in the frontend tree, but `ViewerControls` is the current architectural direction and the shared component used by the active image, PDF, and Markdown viewers.\n\nIf you add another viewer or extend an existing one:\n\n- prefer extending `ViewerControlsConfig`, the relevant state interfaces, or the generic `actions` surface\n- keep viewer-specific logic in the viewer component rather than teaching `ViewerControls` about file-format internals\n- preserve shared mobile, accessibility, and search-panel behavior unless the product intentionally changes that contract\n- add or update focused tests in `frontend/src/components/Viewer/__tests__/ViewerControls.test.tsx` when the shared toolbar contract changes\n\n## Adding a New File Type Safely\n\nFile-type support is registry-driven. The safest way to add a new type is to treat backend and frontend changes as one contract update.\n\n### Main Files to Change\n\n| Path | Why it changes |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | declare extensions, MIME types, category, description, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | declare extensions, MIME types, category, viewer component, icon, color, and description |\n| `frontend/src/components/Viewer/` | add or reuse a viewer component when the type needs a dedicated preview surface |\n\nIf a file type is user-visible, update the published support docs that describe what Sambee can preview.\n\n### Quick Start for a New Image Format\n\nFor an image format such as JPEG XL, the minimum workflow is:\n\n1. add a `FileTypeDefinition` entry to the backend registry\n2. add the matching entry to the frontend registry\n3. decide whether the image is browser-native or requires server-side conversion\n4. keep extensions and MIME types identical across both registries\n5. run the viewer and backend validation checks\n\nBackend example:\n\n```python\nFileTypeDefinition(\n\t\textensions=(\".jxl\",),\n\t\tmime_types=(\"image/jxl\",),\n\t\tcategory=FileCategory.IMAGE,\n\t\trequires_conversion=True,\n\t\tdescription=\"JPEG XL Image\",\n)\n```\n\nFrontend example:\n\n```typescript\n{\n\textensions: [\".jxl\"],\n\tmimeTypes: [\"image/jxl\"],\n\tcategory: \"image\",\n\tviewerComponent: () =\u003e import(\"../components/Viewer/ImageViewer\"),\n\ticon: \"image\",\n\tcolor: \"#a855f7\",\n\tdescription: \"JPEG XL Image\",\n}\n```\n\nThat registry update is what drives MIME matching, icon treatment, viewer routing, and image-gallery inclusion.\n\n### Backend Registry Rules\n\nBackend file-type definitions must stay explicit and type-safe.\n\n- `extensions` are tuples with a leading dot, such as `(\".jpg\", \".jpeg\")`\n- `mime_types` are tuples of standard MIME strings\n- `category` uses `FileCategory` values such as `IMAGE`, `DOCUMENT`, `TEXT`, `VIDEO`, `AUDIO`, `ARCHIVE`, `CODE`, `SPREADSHEET`, or `OTHER`\n- `requires_conversion` matters for image formats that cannot be rendered directly by the browser\n- `description` should be the human-readable label contributors and users would expect\n\nHow to decide `requires_conversion`:\n\n- set it to `False` for browser-native formats such as PNG, JPEG, GIF, WebP, SVG, and AVIF\n- set it to `True` for formats with limited browser support or formats that are not practical to render directly, such as TIFF, HEIC, BMP, JPEG 2000, or JPEG XL when browser support is not sufficient for the product baseline\n\n### Frontend Registry Rules\n\nFrontend file-type definitions control how the browser app presents the file.\n\n- keep `extensions` and `mimeTypes` aligned with the backend registry\n- set `viewerComponent` to the shared viewer that should render the type\n- choose an icon that matches the product language for that file category\n- choose a color that distinguishes the format without inventing a new palette on every addition\n\nFor image formats, reusing `ImageViewer` is usually enough. For non-image formats, you may need a dedicated viewer such as `PdfViewer`, `VideoViewer`, `AudioViewer`, or `TextViewer`.\n\n### Non-Image File Types\n\nThe overall process is the same for documents, video, audio, text, archives, and code files.\n\n1. add the backend registry entry\n2. add the frontend registry entry\n3. create or reuse the viewer component when preview support exists\n4. verify the file icon, viewer routing, and download behavior\n\nFor non-image files, `requires_conversion` is usually `False`. The main design question is whether the product has a viewer component for that category or should fall back to download-only behavior.\n\n### Integration Checklist\n\nUse this checklist before you consider the file type integrated:\n\n- backend registry entry added\n- frontend registry entry added\n- extensions and MIME types match exactly across both registries\n- browser-native versus converted-image behavior decided intentionally\n- viewer component chosen or added\n- icon and color treatment chosen\n- user-visible support docs updated if the file type changes what Sambee can preview\n\n### Testing Checklist\n\nAfter the registry change, verify:\n\n- icon display in the file browser\n- file opening in the expected viewer\n- shared toolbar behavior if the preview uses `ViewerControls`\n- conversion output if the format is server-converted\n- gallery inclusion for image formats\n- MIME type behavior across extension variants such as upper-case filenames\n- download behavior with the correct MIME type\n- mobile and tablet behavior when the preview is expected to work there\n\nFor server-converted formats, also verify:\n\n- the backend returns the converted MIME type you expect\n- transparency-sensitive formats still render correctly\n- resizing or quality settings do not degrade the preview contract unexpectedly\n- environment-specific format support failures surface in a controlled way\n\nFor preprocessable formats, also verify:\n\n- the registry recognizes the extension regardless of case and leading-dot differences\n- the expected preprocessor is selected for that format\n- missing external-tool support fails cleanly\n- validation and timeout rules behave as intended under bad inputs and slow conversions\n\n### Architecture Notes\n\nThese helper functions are the practical integration points contributors usually touch:\n\n- backend: `get_mime_type`, `needs_processing`, `is_image_file`, `get_file_type_by_extension`, `get_file_type_by_mime`\n- frontend: `getViewerComponent`, `isImageFile`, `getFileIcon`, `getFileTypeByExtension`, `getFileTypeByMime`\n\nAt runtime, the flow is:\n\n1. the backend lists files and assigns MIME information\n2. the frontend receives `FileInfo` data with that MIME information\n3. the frontend chooses icon treatment from filename and type rules\n4. the frontend selects the viewer from MIME and file-type data\n5. the backend routes convertible images through the image-conversion pipeline when needed\n\nThe frontend side still has work to do even when the backend owns the conversion:\n\n- viewer MIME recognition must include the input formats the backend classifies as previewable\n- file-type icon and color treatment must still reflect the original file type rather than the converted transport format\n- browser-side fallback MIME logic must not drift from the backend contract in ways that hide conversion bugs\n\n### Operational Characteristics\n\nServer-side conversion changes the runtime profile of preview requests.\n\n- large images can produce short CPU spikes during decode and encode\n- memory usage can rise well above compressed input size while the image is fully decoded\n- SMB-backed reads add their own latency before conversion even starts\n\nThat is why preview regressions for large HEIC or TIFF files often need both backend and user-facing verification.\n\n### Future Extension Points\n\nThe current conversion path leaves room for later enhancements such as:\n\n- caching converted preview outputs\n- queueing especially large conversions\n- dedicated thumbnail generation\n- richer multi-page image handling\n- conversion metrics for operational monitoring\n\nThose are extension points, not assumptions the current product already guarantees.\n\nThe highest-risk mistake is still registry drift. If the backend and frontend disagree about extensions or MIME types, preview behavior becomes unreliable in ways that are easy to miss until users hit them.\n\n## Common Failure Modes\n\n- backend and frontend MIME types do not match\n- a format is marked browser-native when it really needs conversion\n- a viewer component is not registered even though the type is recognized\n- a conversion change improves one format but breaks gallery behavior, download semantics, or mobile viewing\n\n## Validation Expectations\n\nWhen you change viewer or file-type behavior, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd backend \u0026\u0026 pytest -v\n```\n\nIf the change is image-conversion-specific, include the relevant backend tests around image conversion and preview behavior.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/frontend-architecture/settings-form-dialog-pattern", "parent_id": "section:developer-guide/frontend-architecture", "depth": 2, "kind": "page", "label": "settings-form-dialog-pattern", "title": "Settings Form Dialog Pattern", "path": "developer-guide/frontend-architecture/settings-form-dialog-pattern", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "authored"}, "1.0": {"state": "branched", "source_version": "0.9", "diff_added": 56, "diff_removed": 26}, "2.0": {"state": "branched", "source_version": "1.0", "diff_added": 57, "diff_removed": 9}}, "content_versions": {"0.9": "+++\ntitle = \"Settings Form Dialog Pattern\"\n+++\n\nUse this pattern for stateful settings editors that create or update configuration. It keeps the same form behavior across a phone drawer, a narrow dialog, and a desktop dialog while avoiding separate mobile and desktop forms.\n\nThe reference implementation is `frontend/src/components/Admin/ConnectionDialog.tsx`.\n\n## When To Use It\n\nUse the pattern when a dialog edits several related settings and needs validation, field descriptions, or more than one action.\n\nDo not use it for a confirmation or destructive-action dialog. Those should continue to use `ResponsiveFormDialog` directly with focused content and actions.\n\n## Dialog Categories\n\nUse `ResponsiveFormDialog` as the shared shell for every ordinary application dialog. It provides the responsive Drawer and Dialog behavior, safe-area action area, dialog surface tokens, title and description relationships, close blocking, and focus restoration.\n\nSmall dialogs use traditional Cancel and confirmation actions; do not add a top-right close button.\n\nChoose the content pattern that matches the job:\n\n| Dialog type | Use | Examples |\n|---|---|---|\n| Multi-field editor | `ResponsiveFormDialog` with the settings form building blocks below. | Connections, users, OIDC configuration, copy or move. |\n| One- or two-field editor | `ResponsiveFormDialog` with a single-column settings surface. Keep the floating MUI label at every width. | Create, rename, copy, and move. |\n| Decision | `ResponsiveFormDialog` with compact content and actions. Do not add `SettingsFormSurface`. | Delete, overwrite conflict, application update, connection test result. |\n| Picker | `ResponsiveFormDialog` with a listbox or selection grid. Keep the picker\u2019s keyboard and selection semantics in the owning component. | Viewer and theme pickers. |\n| Short workflow | `ResponsiveFormDialog` with state-specific body and actions. | Companion pairing. |\n| Full-screen workspace | Keep the specialized full-screen viewer shell. Share only reusable behavior that does not interfere with the viewer\u2019s focus, toolbar, or third-party integration. | Image, PDF, Markdown, and text viewers. |\n\nThe desktop settings overlay and mobile settings drawer are navigation containers, not form dialogs. Keep their information architecture separate while composing settings-form pages inside them.\n\nFor safety-critical decisions, focus the least destructive action after opening. For input workflows, focus the first input. Do not make a destructive action the default Enter action unless the user has already focused it.\n\n## Shared Building Blocks\n\nImport the structural primitives and control styles from `frontend/src/components/Settings/SettingsFormLayout.tsx`.\n\n| Building block | Responsibility |\n|---|---|\n| `SettingsFormSurface` | Provides the muted, rounded background and shared interior padding. It darkens the default background by 4% in light mode and lightens it by 8% in dark mode. |\n| `SettingsFormGroup` | Groups related rows and adds row dividers only at the desktop breakpoint. |\n| `SettingsFormRow` | Uses one column below `md` and the two-column label/control grid at `md` and above. |\n| `SettingsFormFieldLabel` | Renders a desktop label with its description or validation error. |\n| `SettingsFormSection` | Separates groups with the standard settings heading, subdued divider, and spacing. |\n| `SettingsSelectMenuItem` | Renders a select option with a label and supporting description. |\n| `SettingsPasswordVisibilityToggle` | Renders the shared show/hide password adornment. The owning dialog keeps password visibility state and translated labels. |\n| `settingsFormFieldControlSx` | Aligns a control to the desktop control column. |\n| `settingsFormSelectControlSx` | Makes a desktop select content-width and right-aligned. |\n| `settingsFormOutlinedControlSx` | Applies the shared outlined-field, focus, error, and floating-label treatment. |\n| `settingsSelectSx` and `settingsSelectMenuProps` | Keep select values, icons, and options at the standard subdued text color. |\n\nKeep field state, API calls, validation rules, translations, and the concrete MUI controls in the owning dialog. The shared layer owns layout and presentation; it must not become a schema-driven form engine.\n\n## Responsive Contract\n\nMulti-field settings editors have exactly two form layouts. One- and two-field operation dialogs stay single-column at every width so long names and paths retain the available width.\n\n### Below `md`\n\nUse one column in both responsive shells.\n\n- Below `sm`, `ResponsiveFormDialog` renders the form in a Drawer.\n- From `sm` through `\u003cmd`, it renders the same form in a Dialog.\n- Use normal-height MUI outlined controls.\n- Keep MUI labels inside empty fields and floating in the outline after focus or entry.\n- Keep descriptions and validation errors directly below their controls as MUI helper text.\n- Use the grouped surface and section heading, but do not show individual field-row dividers.\n\n### At `md` And Above For Multi-Field Editors\n\nUse the two-column desktop layout.\n\n- Put labels and descriptions in the left column.\n- Put compact controls in the right column.\n- Use the compact MUI `size=\"small\"` variant only when a desktop field has an external label in the left column.\n- Replace the left-column description with the validation error instead of showing helper text below the input.\n- Keep full-width text inputs within the control column.\n- Use content-width, right-aligned selects when the selected option remains readable.\n- For checkboxes and switches, use the external label and description on the left, with the control in the right column. Keep the control label and helper text next to the control below `md`.\n- For boolean settings, use a `Switch` with a visible `On` or `Off` state label. Let Material UI apply its standard palette colors.\n- For native `datetime-local` inputs, preserve the MUI shrunk input label below `md`; use the external desktop label at `md` and above.\n- Show subdued dividers between rows in a group.\n\n## Control Conventions\n\nApply `settingsSelectSx` and `settingsSelectMenuProps` to every settings `Select`. Use `SettingsSelectMenuItem` when an option needs a short explanation below its label.\n\nUse `SettingsPasswordVisibilityToggle` as the end adornment for password fields. Keep its `visible` state, toggle handler, and localized show/hide labels in the owning dialog.\n\nUse `DialogReadOnlyField` for a name, path, connection, or other value that a dialog shows without allowing the user to change it. Give the field a specific label such as `Destination directory` or `File to delete`; do not recreate a styled text pill. Keep the normal MUI field height when its label is inside the outlined field. Use a subdued read-only surface while keeping long values selectable.\n\nWrite the dialog description as the outcome of the selected action. State what will be copied, moved, replaced, skipped, or deleted and name the source item for a single-item operation, then present the affected value in a labelled read-only field. Keep notices tied to their current condition: a no-op destination notice must disappear as soon as a renamed target makes the operation valid, without changing the dialog's layout.\n\n## Implementation Checklist\n\n1. Start with `ResponsiveFormDialog` for the responsive Drawer and Dialog shell.\n2. Wrap the fields in `SettingsFormSurface` and one or more `SettingsFormGroup` components.\n3. Put every field in `SettingsFormRow`.\n4. Use `SettingsFormFieldLabel` only for a multi-field editor at `md` or wider. Keep one- and two-field operation dialogs in a single column with floating MUI labels at every width.\n5. Keep the below-`md` MUI `label`, `InputLabel`, and `FormHelperText` props in the concrete control. Use normal field height for inline-labelled one- or two-field operation dialogs; reserve helper-text space when a field can show a validation error.\n6. Use `SettingsFormSection` between related groups instead of recreating section borders and title spacing locally.\n7. Reuse the shared action styles when the dialog has split or responsive actions.\n8. Render conditional fields or sections only when their state applies, while keeping each visible control in a `SettingsFormRow`.\n\nFor a non-form dialog, start with `ResponsiveFormDialog` and retain only the content, selection, workflow, and keyboard behavior specific to that dialog. Do not duplicate MUI `Dialog`, `Drawer`, sticky mobile actions, focus restoration, or dialog surface styling in the owning component.\n\n## Accessibility And Validation\n\nAssociate desktop controls with their external labels and descriptions using `htmlFor`, `labelId`, and `aria-describedby` as appropriate. Preserve a description ID when an error replaces the description so the relationship remains valid.\n\nAfter a failed save or test, focus the first invalid field. Do not remove normal MUI error states from controls; the desktop error text supplements them by making the issue readable in the label column.\n\nUse field-level errors for validation that the dialog can determine before submitting. Reserve one helper-text line, then replace it with the active error so the form does not shift. Do not repeat a field-owned error in a form-level alert. Error text must explain the cause and the corrective action, not only name a failed rule.\n\nPrefer a safe, valid default over presenting a predictable error when the dialog can infer the intended correction. For example, a one-item copy into its source directory should prefill an extension-aware name such as `report (copy).pdf`. Do not apply this pattern to a same-directory move: it is a rename operation, so the user must deliberately choose the new name.\n\nUse a stable form-level alert only when no editable field owns the remedy, such as a multi-item copy whose destination directory is also its source directory. Use error severity when the state blocks confirmation. Keep API failures in this form-level feedback region as well, above the form surface so they do not disrupt a desktop field row.\n\n## Testing And Review\n\nFor every dialog that adopts this pattern, cover all of the following:\n\n- The mobile Drawer and the `sm` through `\u003cmd` Dialog use the same single-column form semantics.\n- A populated narrow-screen field uses a floating MUI label, normal control height, and helper text below the field.\n- A multi-field editor retains external labels, compact controls, and desktop-only row dividers at `md` and above.\n- A one- or two-field operation dialog remains single-column and keeps floating labels at `md` and above.\n- Errors, focus-first-invalid behavior, keyboard handling, and pending action states still work.\n- The surface, controls, and helper text remain legible in both light and dark themes.\n\nFor every non-form dialog that adopts the shared shell, cover all of the following:\n\n- The phone Drawer has reachable actions above safe-area insets and does not obscure content in a short viewport.\n- Keyboard focus, Enter, Escape cancellation, and the dialog-specific safe default still work. Escape must always issue the dialog's cancellation request.\n- Picker and workflow state remains usable with a keyboard.\n- Dialog content and action states remain legible in light and dark themes.\n\nUse a live browser check at a phone width and a desktop width in addition to focused tests. Check a short viewport as well so the fixed mobile actions do not obscure the final control.\n\n", "1.0": "+++\ntitle = \"Settings Form Dialog Pattern\"\n+++\n\nUse this pattern for stateful settings editors that create or update configuration. It keeps the same form behavior across a phone drawer, a narrow dialog, and a desktop dialog while avoiding separate mobile and desktop forms.\n\nThe reference implementation is `frontend/src/components/Admin/ConnectionDialog.tsx`.\n\n## When To Use It\n\nUse the pattern when a dialog edits several related settings and needs validation, field descriptions, or more than one action.\n\nDo not use it for a confirmation or destructive-action dialog. Those should continue to use `ResponsiveDialogShell` directly with focused content and actions.\n\n## Dialog Categories\n\nUse `ResponsiveDialogShell` from `frontend/src/components/Dialog/ResponsiveDialogShell.tsx` as the shared shell for every ordinary application dialog. It provides responsive Drawer and Dialog behavior, safe-area actions, overlay/form surface tokens, title and description relationships, close blocking, and focus restoration.\n\nSmall dialogs use traditional Cancel and confirmation actions; do not add a top-right close button.\n\nChoose the content pattern that matches the job:\n\n| Dialog type | Use | Examples |\n|---|---|---|\n| Multi-field editor | `ResponsiveDialogShell` with the form building blocks below. | Connections, users, OIDC configuration, copy or move. |\n| One- or two-field editor | `ResponsiveDialogShell` with a single-column form surface. Keep the floating MUI label at every width. | Create, rename, copy, and move. |\n| Decision | `ResponsiveDialogShell` with compact content and actions. Do not add `FormSurface`. | Delete, overwrite conflict, application update, connection test result. |\n| Picker | `ResponsiveDialogShell` with a listbox or selection grid. Keep the picker\u2019s keyboard and selection semantics in the owning component. | Viewer and theme pickers. |\n| Short workflow | `ResponsiveDialogShell` with state-specific body and actions. | Companion pairing. |\n| Full-screen workspace | Keep the specialized full-screen viewer shell. Share only reusable behavior that does not interfere with the viewer\u2019s focus, toolbar, or third-party integration. | Image, PDF, Markdown, and text viewers. |\n\nThe desktop settings overlay and mobile settings drawer are navigation containers, not form dialogs. Keep their information architecture separate while composing settings-form pages inside them.\n\nFor safety-critical decisions, focus the least destructive action after opening. For input workflows, focus the first input. Do not make a destructive action the default Enter action unless the user has already focused it.\n\n## Shared Building Blocks\n\nImport reusable structural primitives and control styles from `frontend/src/components/Form/FormLayout.tsx`. Settings-only sections remain in `frontend/src/components/Settings/SettingsFormLayout.tsx`.\n\n| Building block | Responsibility |\n|---|---|\n| `FormSurface` | Provides the shared form-surface background and interior padding. |\n| `FormGroup` | Groups related rows and adds row dividers only at the desktop breakpoint. |\n| `FormRow` | Uses one column below `md` and the two-column label/control grid at `md` and above. |\n| `FormFieldLabel` | Renders a desktop label with its description or active error/warning. |\n| `SettingsFormSection` | Separates groups with the standard settings heading, subdued divider, and spacing. |\n| `SettingsSelectMenuItem` | Renders a select option with a label and supporting description. |\n| `SettingsPasswordVisibilityToggle` | Renders the shared show/hide password adornment. The owning dialog keeps password visibility state and translated labels. |\n| `formFieldControlSx` | Aligns a control to the desktop control column. |\n| `formSelectControlSx` | Makes a desktop select content-width and right-aligned. |\n| `formOutlinedControlSx` | Applies the shared outlined-field, focus, error, and floating-label treatment. |\n| `formSelectSx` and `formSelectMenuProps` | Keep select values, icons, and options at the standard subdued text color. |\n\nKeep field state, API calls, validation rules, translations, and the concrete MUI controls in the owning dialog. The shared layer owns layout and presentation; it must not become a schema-driven form engine.\n\n## Responsive Contract\n\nMulti-field settings editors have exactly two form layouts. One- and two-field operation dialogs stay single-column at every width so long names and paths retain the available width.\n\n### Below `md`\n\nUse one column in both responsive shells.\n\n- Below `sm`, `ResponsiveDialogShell` renders the form in a Drawer.\n- From `sm` through `\u003cmd`, it renders the same form in a Dialog.\n- Use normal-height MUI outlined controls.\n- Keep MUI labels inside empty fields and floating in the outline after focus or entry.\n- Keep descriptions and validation errors directly below their controls as MUI helper text.\n- Use the grouped surface and section heading, but do not show individual field-row dividers.\n\n### At `md` And Above For Multi-Field Editors\n\nUse the two-column desktop layout.\n\n- Put labels and descriptions in the left column.\n- Put compact controls in the right column.\n- Use the compact MUI `size=\"small\"` variant only when a desktop field has an external label in the left column.\n- Replace the left-column description with the validation error instead of showing helper text below the input.\n- Keep full-width text inputs within the control column.\n- Use content-width, right-aligned selects when the selected option remains readable.\n- For checkboxes and switches, use the external label and description on the left, with the control in the right column. Keep the control label and helper text next to the control below `md`.\n- For boolean settings, use a `Switch` with a visible `On` or `Off` state label. Let Material UI apply its standard palette colors.\n- For native `datetime-local` inputs, preserve the MUI shrunk input label below `md`; use the external desktop label at `md` and above.\n- Show subdued dividers between rows in a group.\n\n## Control Conventions\n\nApply `settingsSelectSx` and `settingsSelectMenuProps` to every settings `Select`. Use `SettingsSelectMenuItem` when an option needs a short explanation below its label.\n\nUse `SettingsPasswordVisibilityToggle` as the end adornment for password fields. Keep its `visible` state, toggle handler, and localized show/hide labels in the owning dialog.\n\nUse `DialogReadOnlyField` for a name, path, connection, or other value that a dialog shows without allowing the user to change it. Give the field a specific label such as `Destination directory` or `File to delete`; do not recreate a styled text pill. Keep the normal MUI field height when its label is inside the outlined field. Use a subdued read-only surface while keeping long values selectable.\n\nWrite the dialog description as the outcome of the selected action. State what will be copied, moved, replaced, skipped, or deleted and name the source item for a single-item operation, then present the affected value in a labelled read-only field. Keep notices tied to their current condition: a no-op destination notice must disappear as soon as a renamed target makes the operation valid, without changing the dialog's layout.\n\n## Operation Context\n\nOperation dialogs show their subject and destination independently of translated prose. This lets a translated description use its natural word order and keeps a long identifier from making the dialog hard to scan.\n\nUse `DialogOperationContext` for passive operation metadata. Each entry has a translated label and a value with either the `fileName` or `path` kind. The component renders a vertical definition list, so every filename and path occupies its own line and does not share that line with explanatory text.\n\n`OverwriteConflictDialog` is the deliberate exception. Its compact Existing item and Incoming item metadata grids remain intact because they support side-by-side conflict comparison. Use `DialogIdentifierDisplay` for each Path value in those grids, but do not replace the grids with `DialogOperationContext`.\n\nUse `DialogIdentifierDisplay` inside this context rather than truncating an identifier locally. It keeps the full value in the accessible name, applies bidi isolation with `bdi` and `dir=\"auto\"`, and abbreviates only the visual value when the available width requires it. A shortened value has a hover-only tooltip with its full value. Do not make the identifier focusable and do not reveal the tooltip on focus or touch.\n\nFile-name shortening preserves the extension where possible. Path shortening preserves useful leading and trailing segments. Both use grapheme-aware boundaries, so combining characters and emoji sequences are never split. Breadcrumb segment labels must use `truncateTextByGrapheme` from `utils/pathDisplay` for the same reason.\n\nUse outcome-only translation strings for the dialog description. Do not interpolate filenames or paths into `Trans` text. For example, a single-item copy describes copying the item to the destination directory, then context rows identify `Source item` and `Destination directory`.\n\n## Feedback And Persistence\n\nRender feedback only while it is active. Field errors and warnings belong to their control; use normal MUI helper text below `md`, and pass `FieldFeedback` to `FormFieldLabel` at `md` and above so it replaces the left-column description. Error feedback uses the normal MUI error state. Warning text starts with `Warning:` and uses the warning color. Do not reserve blank helper-text space, clip feedback to one line, or use a tooltip as the only way to read it.\n\nUse `DialogNotice` and `DialogNoticeRegion` from `frontend/src/components/Dialog/` for non-field notices. A contextual condition known when the dialog opens belongs in the shell's `contextualNotice` slot, after its description and before the body. A result caused by an action belongs in the `actionNotice` slot immediately above the actions. Idle notices render no alert. An error alert uses the default dynamic `role=\"alert\"`; a non-urgent warning uses `role=\"status\"`. Do not move focus to an alert.\n\nOrdinary settings persist a valid committed value immediately. Selects, toggles, and checkboxes commit on change. Text and numeric fields commit on blur or Enter after local validation succeeds. Keep invalid candidates locally and associate their error with the field. Each field has at most one in-flight request; disable every representation of that field while it is pending, but do not queue, debounce, batch, or serialize unrelated fields. Show a `role=\"status\"` saving indicator only while active, then a brief saved indicator. A failed write remains a readable field error until editing or a later success resolves it.\n\nEvery settings update uses exactly one discriminated `{ field, value }` request and receives the matching canonical pair. Apply a response only to its matching field. Complete settings state is read through `GET`; routine settings pages have no Save, reset, dirty-state, or success-alert workflow. File Search and SMB policy fields are independent persisted keys; the backend validates correlated aggregates transactionally. SMB policy writes retain their full post-commit runtime refresh lifecycle, while its read-chunk-size update does not trigger that lifecycle.\n\n`userSettingsStore` is the sole frontend boundary for `/auth/me/settings`. Components use its field selectors and `useCurrentUserSetting()` hook, retain only local drafts/previews, and never store server-backed user settings in local storage. The store hydrates for identity changes, rejects stale requests, allows one write per field, and refreshes other tabs from invalidation-only BroadcastChannel messages.\n\nDuring a cancellable operation, keep its cancellation action enabled unless the owner is already processing the cancellation request. Move focus to that action when the pending state starts. Keep the primary action disabled while the operation is active. Archive progress must report only data actually provided by the operation: archive creation shows an indeterminate status, and extraction may show its processed-member count without inventing byte totals or an item total.\n\n## Implementation Checklist\n\n1. Start with `ResponsiveDialogShell` for the responsive Drawer and Dialog shell.\n2. Wrap the fields in `FormSurface` and one or more `FormGroup` components.\n3. Put every field in `FormRow`.\n4. Use `FormFieldLabel` only for a multi-field editor at `md` or wider. Keep one- and two-field operation dialogs in a single column with floating MUI labels at every width.\n5. Keep the below-`md` MUI `label`, `InputLabel`, and active `FormHelperText` props in the concrete control. Use normal field height for inline-labelled one- or two-field operation dialogs; do not reserve helper-text space.\n6. Use `SettingsFormSection` between related groups instead of recreating section borders and title spacing locally.\n7. Reuse the shared action styles when the dialog has split or responsive actions.\n8. Render conditional fields or sections only when their state applies, while keeping each visible control in a `FormRow`.\n\nFor a non-form dialog, start with `ResponsiveDialogShell` and retain only the content, selection, workflow, and keyboard behavior specific to that dialog. Do not duplicate MUI `Dialog`, `Drawer`, sticky mobile actions, focus restoration, or dialog surface styling in the owning component.\n\n## Accessibility And Validation\n\nAssociate desktop controls with their external labels and descriptions using `htmlFor`, `labelId`, and `aria-describedby` as appropriate. Preserve a description ID when an error replaces the description so the relationship remains valid.\n\nAfter a failed save or test, focus the first invalid field. Do not remove normal MUI error states from controls; the desktop error text supplements them by making the issue readable in the label column.\n\nUse field-level errors for validation that the dialog can determine before submitting. Do not repeat a field-owned error in a form-level alert. Error text must explain the cause and the corrective action, not only name a failed rule. Bounded reflow when feedback appears is expected and preferred to hidden space.\n\nPrefer a safe, valid default over presenting a predictable error when the dialog can infer the intended correction. For example, a one-item copy into its source directory should prefill an extension-aware name such as `report (copy).pdf`. Do not apply this pattern to a same-directory move: it is a rename operation, so the user must deliberately choose the new name.\n\nUse a stable form-level alert only when no editable field owns the remedy, such as a multi-item copy whose destination directory is also its source directory. Use error severity when the state blocks confirmation. Keep API failures in this form-level feedback region as well, above the form surface so they do not disrupt a desktop field row.\n\n## Testing And Review\n\nFor every dialog that adopts this pattern, cover all of the following:\n\n- The mobile Drawer and the `sm` through `\u003cmd` Dialog use the same single-column form semantics.\n- A populated narrow-screen field uses a floating MUI label, normal control height, and helper text below the field.\n- A multi-field editor retains external labels, compact controls, and desktop-only row dividers at `md` and above.\n- A one- or two-field operation dialog remains single-column and keeps floating labels at `md` and above.\n- Errors, focus-first-invalid behavior, keyboard handling, and pending action states still work.\n- The surface, controls, and helper text remain legible in both light and dark themes.\n- Long filenames and paths remain one line at phone, tablet, and desktop widths; shortened values expose the complete identifier only on hover.\n- Identifier rendering remains correct for mixed left-to-right and right-to-left text, including after the available width changes.\n- A cancellable pending workflow focuses its cancellation action and does not submit a duplicate request.\n\nFor every non-form dialog that adopts the shared shell, cover all of the following:\n\n- The phone Drawer has reachable actions above safe-area insets and does not obscure content in a short viewport.\n- Keyboard focus, Enter, Escape cancellation, and the dialog-specific safe default still work. Escape must always issue the dialog's cancellation request.\n- Picker and workflow state remains usable with a keyboard.\n- Dialog content and action states remain legible in light and dark themes.\n\nUse a live browser check at a phone width and a desktop width in addition to focused tests. Check a short viewport as well so the fixed mobile actions do not obscure the final control.\n", "2.0": "+++\ntitle = \"Settings Forms and Actions\"\n+++\n\nUse these conventions for settings pages and stateful settings editors. Pages share section, surface, and action styles. Editors keep the same form behavior across a phone drawer, a narrow dialog, and a desktop dialog without separate mobile and desktop forms.\n\nThe page reference is `frontend/src/pages/LocalDrivesSettings.tsx`; the dialog reference is `frontend/src/components/Admin/ConnectionDialog.tsx`.\n\n## When To Use It\n\nUse the page conventions for settings content and actions. Use the dialog pattern when an editor changes several related settings and needs validation, field descriptions, or more than one action.\n\nDo not use the form pattern for a confirmation or destructive-action dialog. Those should continue to use `ResponsiveDialogShell` directly with focused content and actions.\n\n## Settings Page Layout and Actions\n\nCompose settings pages with `SettingsPage`, `SettingsSectionList`, and `SettingsGroup`. Use `FormSurface` for the subdued background of an action section, not an additional bordered card. For action sections, put the description or metadata on the left and controls on the right in a `FormRow`: the columns stack below `md` and share the row at `md` and above. Right-align actions on desktop, allow them to wrap, and keep result notices below the row. An informational section such as Local Drives' Current status can keep its own layout; don't force it into an action row.\n\nChoose button styling by the action's role, not by whether its MUI variant is `outlined` or `contained`:\n\n| Role | Treatment | Example |\n|---|---|---|\n| Regular or secondary | Neutral `settingsUtilityButtonSx`; on a grey `FormSurface`, use `settingsFormSurfaceUtilityButtonSx` so the overlay background shows through, as it does for dialog inputs. Keep the existing border, hover, and keyboard-focus treatment. | Account \u003e Change password; Local Drives \u003e Test Current Pairing. |\n| Danger or alert | Red-tinted `settingsDestructiveButtonSx` for settings-page actions. Use the dialog action rules below for the confirmation. | Local Drives \u003e Unpair This Browser. |\n| Main or default | Prominent `settingsPrimaryButtonSx` for the main action on a grey settings-page surface and for the main action in a page footer or dialog. Avoid giving several routine actions the same emphasis. | Authentication \u003e Configure OIDC; Local Drives \u003e Pair This Browser. |\n\nAdd a relevant `@mui/icons-material` icon with `startIcon` to labeled outlined or contained settings-page action buttons that lack one. Leave text-only buttons, including buttons without an explicit outlined or contained variant, without icons. Adding an icon must not change the button's variant, colors, label, or behavior.\n\n## User Directory Layout\n\nUser Management renders roles and statuses as ordinary text, with each simultaneous status on its own line. Summary counts and removable filters remain badges. Keep column headings and cell values readable: wrap headings, email addresses, usernames, provider names, and other long values without truncating their underlying text. Top-align row contents, and reserve space for sort icons and row actions.\n\nUse the settings content container's width to choose between the desktop grid and stacked records, with a shared 40rem breakpoint for the table and its toolbar. Changing selected columns must not change the layout breakpoint. A narrow settings overlay must stack even on a wide screen. Preserve every selected field when stacking; don't introduce horizontal scrolling or silently hide columns. Show timestamps as a short localized date and time on separate lines, retaining the full timestamp in a tooltip and the original value in a semantic `time` element.\n\nPlace the desktop column chooser icon at the far-right end of the table header, above the row actions. In stacked layouts, place the Columns control at the toolbar's right edge. Keep the toolbar control available while the directory is loading or empty. Anchor the menu to the visible control, reposition it when the settings container resizes, and return focus to the visible control when it closes.\n\nValidate the layout in a real browser with all columns enabled, long identifiers, multiple statuses, different regional formats, narrow containers, mobile widths, and zoom. Component tests don't measure text overlap or container-query behavior.\n\n## Dialog Categories\n\nUse `ResponsiveDialogShell` from `frontend/src/components/Dialog/ResponsiveDialogShell.tsx` as the shared shell for every ordinary application dialog. It provides responsive Drawer and Dialog behavior, safe-area actions, overlay/form surface tokens, title and description relationships, close blocking, and focus restoration.\n\nSmall dialogs use traditional Cancel and confirmation actions; do not add a top-right close button.\n\nChoose the content pattern that matches the job:\n\n| Dialog type | Use | Examples |\n|---|---|---|\n| Multi-field editor | `ResponsiveDialogShell` with the form building blocks below. | Connections, users, OIDC configuration, copy or move. |\n| One- or two-field editor | `ResponsiveDialogShell` with a single-column form surface. Keep the floating MUI label at every width. | Create, rename, copy, and move. |\n| Decision | `ResponsiveDialogShell` with compact content and actions. Do not add `FormSurface`. | Delete, overwrite conflict, application update, connection test result. |\n| Picker | `ResponsiveDialogShell` with a listbox or selection grid. Keep the picker\u2019s keyboard and selection semantics in the owning component. | Viewer and theme pickers. |\n| Short workflow | `ResponsiveDialogShell` with state-specific body and actions. | Companion pairing. |\n| Full-screen workspace | Keep the specialized full-screen viewer shell. Share only reusable behavior that does not interfere with the viewer\u2019s focus, toolbar, or third-party integration. | Image, PDF, Markdown, and text viewers. |\n\nThe desktop settings overlay and mobile settings drawer are navigation containers, not form dialogs. Keep their information architecture separate while composing settings-form pages inside them.\n\n## Keyboard Isolation\n\n`ResponsiveDialogShell` establishes a keyboard shortcut scope automatically for both its Drawer and Dialog layouts. While it's open, `useKeyboardShortcuts` ignores background registrations and lets the innermost open dialog own shortcuts, including when a control portals outside the dialog. The shell also stops key events from bubbling into parent workspace handlers. Closing the dialog releases its scope; normal shortcut handling resumes when focus returns to the workspace.\n\nDon't add dialog-specific flags to parent shortcut handlers to provide this isolation. Keep ordinary dialog keyboard behavior in the shell's `onKeyDown` or `onEscape` callbacks. If dialog content needs `useKeyboardShortcuts`, register it in a child component rendered inside the shell so it inherits the dialog's scope, not in the component that creates the shell. Existing focus trapping and interactive-control checks still apply.\n\nEscape dismissal goes through MUI's modal close callback, preserving its top-modal and IME process-key checks. `onEscape`, when supplied, replaces the normal Escape close action and runs once, even when `disableClose` blocks ordinary closing. Use it for cancellation requests during pending operations. Close buttons and backdrop requests still use `onClose` and respect `disableClose`. Don't add document-level Escape listeners or duplicate Escape closing in `onKeyDown`; the shared shell owns that behavior.\n\n## Dialog Action Buttons\n\nChoose each action's treatment by what it does, including in decisions embedded inside full-screen viewers. Keep the viewer workspace shell and toolbars separate from its decision dialogs.\n\n| Role | Treatment | Example |\n|---|---|---|\n| Destructive confirmation | MUI `variant=\"contained\" color=\"error\"`, as in the File delete dialog. Do not use the red-tinted settings-page `settingsDestructiveButtonSx` or introduce another red button style. | Delete, Discard unsaved changes, or Continue with overwrite selected. |\n| Main non-destructive action | MUI `variant=\"contained\"` in the theme's primary color. | Create directory, Save, Retry, or the sole Close action. |\n| Secondary or alternate action | MUI `variant=\"outlined\"` with the existing subdued utility fill and focus treatment. | Cancel, Later, Ignore, or Open without saving. |\n\nAn action's role can change with the selected option: a conflict dialog's Continue is destructive only when it will overwrite an existing item. When a decision offers both Save and Discard, distinguish the primary and destructive actions without changing what either one does. Do not restyle settings-page triggers when styling their confirmation dialogs.\n\nVisual priority does not determine Enter behavior. For safety-critical decisions, focus the least destructive action on opening; for input workflows, focus the first input. Never make a destructive action the default Enter action unless the user has already focused it. Keep cancellation available and focused during cancellable pending operations. Use `ResponsiveDialogShell` for application confirmations rather than native `window.confirm`, whose buttons cannot follow these styles.\n\n## Shared Building Blocks\n\nImport reusable structural primitives and control styles from `frontend/src/components/Form/FormLayout.tsx`. Settings-only sections remain in `frontend/src/components/Settings/SettingsFormLayout.tsx`.\n\n| Building block | Responsibility |\n|---|---|\n| `FormSurface` | Provides the shared form-surface background and interior padding. |\n| `FormGroup` | Groups related rows and adds row dividers only at the desktop breakpoint. |\n| `FormRow` | Uses one column below `md` and the two-column label/control grid at `md` and above. |\n| `FormFieldLabel` | Renders a desktop label with its description or active error/warning. |\n| `SettingsFormSection` | Separates groups with the standard settings heading, subdued divider, and spacing. |\n| `SettingsSelectMenuItem` | Renders a select option with a label and supporting description. |\n| `SettingsPasswordVisibilityToggle` | Renders the shared show/hide password adornment. The owning dialog keeps password visibility state and translated labels. |\n| `formFieldControlSx` | Aligns a control to the desktop control column. |\n| `formSelectControlSx` | Makes a desktop select content-width and right-aligned. |\n| `formOutlinedControlSx` | Applies the shared outlined-field, focus, error, and floating-label treatment. |\n| `formSelectSx` and `formSelectMenuProps` | Keep select values, icons, and options at the standard subdued text color. |\n\nKeep field state, API calls, validation rules, translations, and the concrete MUI controls in the owning dialog. The shared layer owns layout and presentation; it must not become a schema-driven form engine.\n\n## Responsive Contract\n\nMulti-field settings editors have exactly two form layouts. One- and two-field operation dialogs stay single-column at every width so long names and paths retain the available width.\n\n### Below `md`\n\nUse one column in both responsive shells.\n\n- Below `sm`, `ResponsiveDialogShell` renders the form in a Drawer.\n- From `sm` through `\u003cmd`, it renders the same form in a Dialog.\n- Use normal-height MUI outlined controls.\n- Keep MUI labels inside empty fields and floating in the outline after focus or entry.\n- Keep descriptions and validation errors directly below their controls as MUI helper text.\n- Use the grouped surface and section heading, but do not show individual field-row dividers.\n\n### At `md` And Above For Multi-Field Editors\n\nUse the two-column desktop layout.\n\n- Put labels and descriptions in the left column.\n- Put compact controls in the right column.\n- For text inputs and selects with an external label in the left column, use MUI `size=\"small\"` and omit the control's `label` or `InputLabel`. The left-column label is the only visible label; associate it with the control so it remains accessible. Below `md`, restore the control's floating label and normal height.\n- Replace the left-column description with the validation error instead of showing helper text below the input.\n- Keep full-width text inputs within the control column.\n- Use content-width, right-aligned selects when the selected option remains readable.\n- For checkboxes and switches, use the external label and description on the left, with the control in the right column. Keep the control label and helper text next to the control below `md`.\n- For boolean settings, use a `Switch` with a visible `On` or `Off` state label. Let Material UI apply its standard palette colors.\n- For native `datetime-local` inputs, preserve the MUI shrunk input label below `md`; use the external desktop label at `md` and above.\n- Show subdued dividers between rows in a group.\n\n## Control Conventions\n\nApply `settingsSelectSx` and `settingsSelectMenuProps` to every settings `Select`. Use `SettingsSelectMenuItem` when an option needs a short explanation below its label.\n\nUse `SettingsPasswordVisibilityToggle` as the end adornment for password fields. Keep its `visible` state, toggle handler, and localized show/hide labels in the owning dialog.\n\nUse `DialogReadOnlyField` for a name, path, connection, or other value that a dialog shows without allowing the user to change it. Give the field a specific label such as `Destination directory` or `File to delete`; do not recreate a styled text pill. Keep the normal MUI field height when its label is inside the outlined field. Use a subdued read-only surface while keeping long values selectable.\n\nWrite the dialog description as the outcome of the selected action. State what will be copied, moved, replaced, skipped, or deleted and name the source item for a single-item operation, then present the affected value in a labelled read-only field. Keep notices tied to their current condition: a no-op destination notice must disappear as soon as a renamed target makes the operation valid, without changing the dialog's layout.\n\n## Operation Context\n\nOperation dialogs show their subject and destination independently of translated prose. This lets a translated description use its natural word order and keeps a long identifier from making the dialog hard to scan.\n\nUse `DialogOperationContext` for passive operation metadata. Each entry has a translated label and a value with either the `fileName` or `path` kind. The component renders a vertical definition list, so every filename and path occupies its own line and does not share that line with explanatory text.\n\n`OverwriteConflictDialog` is the deliberate exception. Its compact Existing item and Incoming item metadata grids remain intact because they support side-by-side conflict comparison. Use `DialogIdentifierDisplay` for each Path value in those grids, but do not replace the grids with `DialogOperationContext`.\n\nUse `DialogIdentifierDisplay` inside this context rather than truncating an identifier locally. It keeps the full value in the accessible name, applies bidi isolation with `bdi` and `dir=\"auto\"`, and abbreviates only the visual value when the available width requires it. A shortened value has a hover-only tooltip with its full value. Do not make the identifier focusable and do not reveal the tooltip on focus or touch.\n\nFile-name shortening preserves the extension where possible. Path shortening preserves useful leading and trailing segments. Both use grapheme-aware boundaries, so combining characters and emoji sequences are never split. Breadcrumb segment labels must use `truncateTextByGrapheme` from `utils/pathDisplay` for the same reason.\n\nUse outcome-only translation strings for the dialog description. Do not interpolate filenames or paths into `Trans` text. For example, a single-item copy describes copying the item to the destination directory, then context rows identify `Source item` and `Destination directory`.\n\n## Feedback And Persistence\n\nRender feedback only while it is active. Field errors and warnings belong to their control; use normal MUI helper text below `md`, and pass `FieldFeedback` to `FormFieldLabel` at `md` and above so it replaces the left-column description. Error feedback uses the normal MUI error state. Warning text starts with `Warning:` and uses the warning color. Do not reserve blank helper-text space, clip feedback to one line, or use a tooltip as the only way to read it.\n\nUse `DialogNotice` and `DialogNoticeRegion` from `frontend/src/components/Dialog/` for non-field notices. A contextual condition known when the dialog opens belongs in the shell's `contextualNotice` slot, after its description and before the body. A result caused by an action belongs in the `actionNotice` slot immediately above the actions. Idle notices render no alert. An error alert uses the default dynamic `role=\"alert\"`; a non-urgent warning uses `role=\"status\"`. Do not move focus to an alert.\n\nOrdinary settings persist a valid committed value immediately. Selects, toggles, and checkboxes commit on change. Text and numeric fields commit on blur or Enter after local validation succeeds. Keep invalid candidates locally and associate their error with the field. Each field has at most one in-flight request; disable every representation of that field while it is pending, but do not queue, debounce, batch, or serialize unrelated fields. Show a `role=\"status\"` saving indicator only while active, then a brief saved indicator. A failed write remains a readable field error until editing or a later success resolves it.\n\nEvery settings update uses exactly one discriminated `{ field, value }` request and receives the matching canonical pair. Apply a response only to its matching field. Complete settings state is read through `GET`; routine settings pages have no Save, reset, dirty-state, or success-alert workflow. File Search and SMB policy fields are independent persisted keys; the backend validates correlated aggregates transactionally. SMB policy writes retain their full post-commit runtime refresh lifecycle, while its read-chunk-size update does not trigger that lifecycle.\n\n`userSettingsStore` is the sole frontend boundary for `/auth/me/settings`. Components use its field selectors and `useCurrentUserSetting()` hook, retain only local drafts/previews, and never store server-backed user settings in local storage. The store hydrates for identity changes, rejects stale requests, allows one write per field, and refreshes other tabs from invalidation-only BroadcastChannel messages.\n\nDuring a cancellable operation, keep its cancellation action enabled unless the owner is already processing the cancellation request. Move focus to that action when the pending state starts. Keep the primary action disabled while the operation is active. Archive progress must report only data actually provided by the operation: archive creation shows an indeterminate status, and extraction may show its processed-member count without inventing byte totals or an item total.\n\n## Implementation Checklist\n\n1. Start with `ResponsiveDialogShell` for the responsive Drawer and Dialog shell.\n2. Wrap the fields in `FormSurface` and one or more `FormGroup` components.\n3. Put every field in `FormRow`.\n4. Use `FormFieldLabel` only for a multi-field editor at `md` or wider. Keep one- and two-field operation dialogs in a single column with floating MUI labels at every width.\n5. Keep the below-`md` MUI `label`, `InputLabel`, and active `FormHelperText` props in the concrete control. Use normal field height for inline-labelled one- or two-field operation dialogs; do not reserve helper-text space.\n6. Use `SettingsFormSection` between related groups instead of recreating section borders and title spacing locally.\n7. Reuse the shared action styles when the dialog has split or responsive actions.\n8. Render conditional fields or sections only when their state applies, while keeping each visible control in a `FormRow`.\n\nFor a non-form dialog, start with `ResponsiveDialogShell` and retain only the content, selection, workflow, and keyboard behavior specific to that dialog. Do not duplicate MUI `Dialog`, `Drawer`, sticky mobile actions, focus restoration, or dialog surface styling in the owning component.\n\n## Accessibility And Validation\n\nAssociate desktop controls with their external labels and descriptions using `htmlFor`, `labelId`, and `aria-describedby` as appropriate. Preserve a description ID when an error replaces the description so the relationship remains valid.\n\nAfter a failed save or test, focus the first invalid field. Do not remove normal MUI error states from controls; the desktop error text supplements them by making the issue readable in the label column.\n\nUse field-level errors for validation that the dialog can determine before submitting. Do not repeat a field-owned error in a form-level alert. Error text must explain the cause and the corrective action, not only name a failed rule. Bounded reflow when feedback appears is expected and preferred to hidden space.\n\nPrefer a safe, valid default over presenting a predictable error when the dialog can infer the intended correction. For example, a one-item copy into its source directory should prefill an extension-aware name such as `report (copy).pdf`. Do not apply this pattern to a same-directory move: it is a rename operation, so the user must deliberately choose the new name.\n\nUse a stable form-level alert only when no editable field owns the remedy, such as a multi-item copy whose destination directory is also its source directory. Use error severity when the state blocks confirmation. Keep API failures in this form-level feedback region as well, above the form surface so they do not disrupt a desktop field row.\n\n## Testing And Review\n\nFor settings-page action sections, check the one-column layout below `md` and the two-column description/action layout at `md` and above. Check neutral-button contrast against grey form surfaces in light and dark themes, including hover and keyboard focus. Check that added icons do not change accessible names or cause button labels to overflow at phone widths. Keep informational sections readable without imposing the action-row grid, and verify that notices remain below the row.\n\nFor dialog actions, check contained error and primary buttons and outlined secondary buttons in light and dark themes, including hover and keyboard focus. Verify that option-dependent destructive actions change treatment without changing their safe initial focus or Enter behavior.\n\nFor every dialog that adopts this pattern, cover all of the following:\n\n- The mobile Drawer and the `sm` through `\u003cmd` Dialog use the same single-column form semantics.\n- A populated narrow-screen field uses a floating MUI label, normal control height, and helper text below the field.\n- A multi-field editor retains external labels, compact controls, and desktop-only row dividers at `md` and above.\n- A one- or two-field operation dialog remains single-column and keeps floating labels at `md` and above.\n- Errors, focus-first-invalid behavior, keyboard handling, and pending action states still work.\n- The surface, controls, and helper text remain legible in both light and dark themes.\n- Long filenames and paths remain one line at phone, tablet, and desktop widths; shortened values expose the complete identifier only on hover.\n- Identifier rendering remains correct for mixed left-to-right and right-to-left text, including after the available width changes.\n- A cancellable pending workflow focuses its cancellation action and does not submit a duplicate request.\n\nFor every non-form dialog that adopts the shared shell, cover all of the following:\n\n- The phone Drawer has reachable actions above safe-area insets and does not obscure content in a short viewport.\n- Keyboard focus, Enter, Escape cancellation, and the dialog-specific safe default still work. Escape must always issue the dialog's cancellation request.\n- Picker and workflow state remains usable with a keyboard.\n- Dialog content and action states remain legible in light and dark themes.\n\nUse a live browser check at a phone width and a desktop width in addition to focused tests. Check a short viewport as well so the fixed mobile actions do not obscure the final control.\n"}, "page_contents": {"0.9": "+++\ntitle = \"Settings Form Dialog Pattern\"\n+++\n\nUse this pattern for stateful settings editors that create or update configuration. It keeps the same form behavior across a phone drawer, a narrow dialog, and a desktop dialog while avoiding separate mobile and desktop forms.\n\nThe reference implementation is `frontend/src/components/Admin/ConnectionDialog.tsx`.\n\n## When To Use It\n\nUse the pattern when a dialog edits several related settings and needs validation, field descriptions, or more than one action.\n\nDo not use it for a confirmation or destructive-action dialog. Those should continue to use `ResponsiveFormDialog` directly with focused content and actions.\n\n## Dialog Categories\n\nUse `ResponsiveFormDialog` as the shared shell for every ordinary application dialog. It provides the responsive Drawer and Dialog behavior, safe-area action area, dialog surface tokens, title and description relationships, close blocking, and focus restoration.\n\nSmall dialogs use traditional Cancel and confirmation actions; do not add a top-right close button.\n\nChoose the content pattern that matches the job:\n\n| Dialog type | Use | Examples |\n|---|---|---|\n| Multi-field editor | `ResponsiveFormDialog` with the settings form building blocks below. | Connections, users, OIDC configuration, copy or move. |\n| One- or two-field editor | `ResponsiveFormDialog` with a single-column settings surface. Keep the floating MUI label at every width. | Create, rename, copy, and move. |\n| Decision | `ResponsiveFormDialog` with compact content and actions. Do not add `SettingsFormSurface`. | Delete, overwrite conflict, application update, connection test result. |\n| Picker | `ResponsiveFormDialog` with a listbox or selection grid. Keep the picker\u2019s keyboard and selection semantics in the owning component. | Viewer and theme pickers. |\n| Short workflow | `ResponsiveFormDialog` with state-specific body and actions. | Companion pairing. |\n| Full-screen workspace | Keep the specialized full-screen viewer shell. Share only reusable behavior that does not interfere with the viewer\u2019s focus, toolbar, or third-party integration. | Image, PDF, Markdown, and text viewers. |\n\nThe desktop settings overlay and mobile settings drawer are navigation containers, not form dialogs. Keep their information architecture separate while composing settings-form pages inside them.\n\nFor safety-critical decisions, focus the least destructive action after opening. For input workflows, focus the first input. Do not make a destructive action the default Enter action unless the user has already focused it.\n\n## Shared Building Blocks\n\nImport the structural primitives and control styles from `frontend/src/components/Settings/SettingsFormLayout.tsx`.\n\n| Building block | Responsibility |\n|---|---|\n| `SettingsFormSurface` | Provides the muted, rounded background and shared interior padding. It darkens the default background by 4% in light mode and lightens it by 8% in dark mode. |\n| `SettingsFormGroup` | Groups related rows and adds row dividers only at the desktop breakpoint. |\n| `SettingsFormRow` | Uses one column below `md` and the two-column label/control grid at `md` and above. |\n| `SettingsFormFieldLabel` | Renders a desktop label with its description or validation error. |\n| `SettingsFormSection` | Separates groups with the standard settings heading, subdued divider, and spacing. |\n| `SettingsSelectMenuItem` | Renders a select option with a label and supporting description. |\n| `SettingsPasswordVisibilityToggle` | Renders the shared show/hide password adornment. The owning dialog keeps password visibility state and translated labels. |\n| `settingsFormFieldControlSx` | Aligns a control to the desktop control column. |\n| `settingsFormSelectControlSx` | Makes a desktop select content-width and right-aligned. |\n| `settingsFormOutlinedControlSx` | Applies the shared outlined-field, focus, error, and floating-label treatment. |\n| `settingsSelectSx` and `settingsSelectMenuProps` | Keep select values, icons, and options at the standard subdued text color. |\n\nKeep field state, API calls, validation rules, translations, and the concrete MUI controls in the owning dialog. The shared layer owns layout and presentation; it must not become a schema-driven form engine.\n\n## Responsive Contract\n\nMulti-field settings editors have exactly two form layouts. One- and two-field operation dialogs stay single-column at every width so long names and paths retain the available width.\n\n### Below `md`\n\nUse one column in both responsive shells.\n\n- Below `sm`, `ResponsiveFormDialog` renders the form in a Drawer.\n- From `sm` through `\u003cmd`, it renders the same form in a Dialog.\n- Use normal-height MUI outlined controls.\n- Keep MUI labels inside empty fields and floating in the outline after focus or entry.\n- Keep descriptions and validation errors directly below their controls as MUI helper text.\n- Use the grouped surface and section heading, but do not show individual field-row dividers.\n\n### At `md` And Above For Multi-Field Editors\n\nUse the two-column desktop layout.\n\n- Put labels and descriptions in the left column.\n- Put compact controls in the right column.\n- Use the compact MUI `size=\"small\"` variant only when a desktop field has an external label in the left column.\n- Replace the left-column description with the validation error instead of showing helper text below the input.\n- Keep full-width text inputs within the control column.\n- Use content-width, right-aligned selects when the selected option remains readable.\n- For checkboxes and switches, use the external label and description on the left, with the control in the right column. Keep the control label and helper text next to the control below `md`.\n- For boolean settings, use a `Switch` with a visible `On` or `Off` state label. Let Material UI apply its standard palette colors.\n- For native `datetime-local` inputs, preserve the MUI shrunk input label below `md`; use the external desktop label at `md` and above.\n- Show subdued dividers between rows in a group.\n\n## Control Conventions\n\nApply `settingsSelectSx` and `settingsSelectMenuProps` to every settings `Select`. Use `SettingsSelectMenuItem` when an option needs a short explanation below its label.\n\nUse `SettingsPasswordVisibilityToggle` as the end adornment for password fields. Keep its `visible` state, toggle handler, and localized show/hide labels in the owning dialog.\n\nUse `DialogReadOnlyField` for a name, path, connection, or other value that a dialog shows without allowing the user to change it. Give the field a specific label such as `Destination directory` or `File to delete`; do not recreate a styled text pill. Keep the normal MUI field height when its label is inside the outlined field. Use a subdued read-only surface while keeping long values selectable.\n\nWrite the dialog description as the outcome of the selected action. State what will be copied, moved, replaced, skipped, or deleted and name the source item for a single-item operation, then present the affected value in a labelled read-only field. Keep notices tied to their current condition: a no-op destination notice must disappear as soon as a renamed target makes the operation valid, without changing the dialog's layout.\n\n## Implementation Checklist\n\n1. Start with `ResponsiveFormDialog` for the responsive Drawer and Dialog shell.\n2. Wrap the fields in `SettingsFormSurface` and one or more `SettingsFormGroup` components.\n3. Put every field in `SettingsFormRow`.\n4. Use `SettingsFormFieldLabel` only for a multi-field editor at `md` or wider. Keep one- and two-field operation dialogs in a single column with floating MUI labels at every width.\n5. Keep the below-`md` MUI `label`, `InputLabel`, and `FormHelperText` props in the concrete control. Use normal field height for inline-labelled one- or two-field operation dialogs; reserve helper-text space when a field can show a validation error.\n6. Use `SettingsFormSection` between related groups instead of recreating section borders and title spacing locally.\n7. Reuse the shared action styles when the dialog has split or responsive actions.\n8. Render conditional fields or sections only when their state applies, while keeping each visible control in a `SettingsFormRow`.\n\nFor a non-form dialog, start with `ResponsiveFormDialog` and retain only the content, selection, workflow, and keyboard behavior specific to that dialog. Do not duplicate MUI `Dialog`, `Drawer`, sticky mobile actions, focus restoration, or dialog surface styling in the owning component.\n\n## Accessibility And Validation\n\nAssociate desktop controls with their external labels and descriptions using `htmlFor`, `labelId`, and `aria-describedby` as appropriate. Preserve a description ID when an error replaces the description so the relationship remains valid.\n\nAfter a failed save or test, focus the first invalid field. Do not remove normal MUI error states from controls; the desktop error text supplements them by making the issue readable in the label column.\n\nUse field-level errors for validation that the dialog can determine before submitting. Reserve one helper-text line, then replace it with the active error so the form does not shift. Do not repeat a field-owned error in a form-level alert. Error text must explain the cause and the corrective action, not only name a failed rule.\n\nPrefer a safe, valid default over presenting a predictable error when the dialog can infer the intended correction. For example, a one-item copy into its source directory should prefill an extension-aware name such as `report (copy).pdf`. Do not apply this pattern to a same-directory move: it is a rename operation, so the user must deliberately choose the new name.\n\nUse a stable form-level alert only when no editable field owns the remedy, such as a multi-item copy whose destination directory is also its source directory. Use error severity when the state blocks confirmation. Keep API failures in this form-level feedback region as well, above the form surface so they do not disrupt a desktop field row.\n\n## Testing And Review\n\nFor every dialog that adopts this pattern, cover all of the following:\n\n- The mobile Drawer and the `sm` through `\u003cmd` Dialog use the same single-column form semantics.\n- A populated narrow-screen field uses a floating MUI label, normal control height, and helper text below the field.\n- A multi-field editor retains external labels, compact controls, and desktop-only row dividers at `md` and above.\n- A one- or two-field operation dialog remains single-column and keeps floating labels at `md` and above.\n- Errors, focus-first-invalid behavior, keyboard handling, and pending action states still work.\n- The surface, controls, and helper text remain legible in both light and dark themes.\n\nFor every non-form dialog that adopts the shared shell, cover all of the following:\n\n- The phone Drawer has reachable actions above safe-area insets and does not obscure content in a short viewport.\n- Keyboard focus, Enter, Escape cancellation, and the dialog-specific safe default still work. Escape must always issue the dialog's cancellation request.\n- Picker and workflow state remains usable with a keyboard.\n- Dialog content and action states remain legible in light and dark themes.\n\nUse a live browser check at a phone width and a desktop width in addition to focused tests. Check a short viewport as well so the fixed mobile actions do not obscure the final control.\n\n", "1.0": "+++\ntitle = \"Settings Form Dialog Pattern\"\n+++\n\nUse this pattern for stateful settings editors that create or update configuration. It keeps the same form behavior across a phone drawer, a narrow dialog, and a desktop dialog while avoiding separate mobile and desktop forms.\n\nThe reference implementation is `frontend/src/components/Admin/ConnectionDialog.tsx`.\n\n## When To Use It\n\nUse the pattern when a dialog edits several related settings and needs validation, field descriptions, or more than one action.\n\nDo not use it for a confirmation or destructive-action dialog. Those should continue to use `ResponsiveDialogShell` directly with focused content and actions.\n\n## Dialog Categories\n\nUse `ResponsiveDialogShell` from `frontend/src/components/Dialog/ResponsiveDialogShell.tsx` as the shared shell for every ordinary application dialog. It provides responsive Drawer and Dialog behavior, safe-area actions, overlay/form surface tokens, title and description relationships, close blocking, and focus restoration.\n\nSmall dialogs use traditional Cancel and confirmation actions; do not add a top-right close button.\n\nChoose the content pattern that matches the job:\n\n| Dialog type | Use | Examples |\n|---|---|---|\n| Multi-field editor | `ResponsiveDialogShell` with the form building blocks below. | Connections, users, OIDC configuration, copy or move. |\n| One- or two-field editor | `ResponsiveDialogShell` with a single-column form surface. Keep the floating MUI label at every width. | Create, rename, copy, and move. |\n| Decision | `ResponsiveDialogShell` with compact content and actions. Do not add `FormSurface`. | Delete, overwrite conflict, application update, connection test result. |\n| Picker | `ResponsiveDialogShell` with a listbox or selection grid. Keep the picker\u2019s keyboard and selection semantics in the owning component. | Viewer and theme pickers. |\n| Short workflow | `ResponsiveDialogShell` with state-specific body and actions. | Companion pairing. |\n| Full-screen workspace | Keep the specialized full-screen viewer shell. Share only reusable behavior that does not interfere with the viewer\u2019s focus, toolbar, or third-party integration. | Image, PDF, Markdown, and text viewers. |\n\nThe desktop settings overlay and mobile settings drawer are navigation containers, not form dialogs. Keep their information architecture separate while composing settings-form pages inside them.\n\nFor safety-critical decisions, focus the least destructive action after opening. For input workflows, focus the first input. Do not make a destructive action the default Enter action unless the user has already focused it.\n\n## Shared Building Blocks\n\nImport reusable structural primitives and control styles from `frontend/src/components/Form/FormLayout.tsx`. Settings-only sections remain in `frontend/src/components/Settings/SettingsFormLayout.tsx`.\n\n| Building block | Responsibility |\n|---|---|\n| `FormSurface` | Provides the shared form-surface background and interior padding. |\n| `FormGroup` | Groups related rows and adds row dividers only at the desktop breakpoint. |\n| `FormRow` | Uses one column below `md` and the two-column label/control grid at `md` and above. |\n| `FormFieldLabel` | Renders a desktop label with its description or active error/warning. |\n| `SettingsFormSection` | Separates groups with the standard settings heading, subdued divider, and spacing. |\n| `SettingsSelectMenuItem` | Renders a select option with a label and supporting description. |\n| `SettingsPasswordVisibilityToggle` | Renders the shared show/hide password adornment. The owning dialog keeps password visibility state and translated labels. |\n| `formFieldControlSx` | Aligns a control to the desktop control column. |\n| `formSelectControlSx` | Makes a desktop select content-width and right-aligned. |\n| `formOutlinedControlSx` | Applies the shared outlined-field, focus, error, and floating-label treatment. |\n| `formSelectSx` and `formSelectMenuProps` | Keep select values, icons, and options at the standard subdued text color. |\n\nKeep field state, API calls, validation rules, translations, and the concrete MUI controls in the owning dialog. The shared layer owns layout and presentation; it must not become a schema-driven form engine.\n\n## Responsive Contract\n\nMulti-field settings editors have exactly two form layouts. One- and two-field operation dialogs stay single-column at every width so long names and paths retain the available width.\n\n### Below `md`\n\nUse one column in both responsive shells.\n\n- Below `sm`, `ResponsiveDialogShell` renders the form in a Drawer.\n- From `sm` through `\u003cmd`, it renders the same form in a Dialog.\n- Use normal-height MUI outlined controls.\n- Keep MUI labels inside empty fields and floating in the outline after focus or entry.\n- Keep descriptions and validation errors directly below their controls as MUI helper text.\n- Use the grouped surface and section heading, but do not show individual field-row dividers.\n\n### At `md` And Above For Multi-Field Editors\n\nUse the two-column desktop layout.\n\n- Put labels and descriptions in the left column.\n- Put compact controls in the right column.\n- Use the compact MUI `size=\"small\"` variant only when a desktop field has an external label in the left column.\n- Replace the left-column description with the validation error instead of showing helper text below the input.\n- Keep full-width text inputs within the control column.\n- Use content-width, right-aligned selects when the selected option remains readable.\n- For checkboxes and switches, use the external label and description on the left, with the control in the right column. Keep the control label and helper text next to the control below `md`.\n- For boolean settings, use a `Switch` with a visible `On` or `Off` state label. Let Material UI apply its standard palette colors.\n- For native `datetime-local` inputs, preserve the MUI shrunk input label below `md`; use the external desktop label at `md` and above.\n- Show subdued dividers between rows in a group.\n\n## Control Conventions\n\nApply `settingsSelectSx` and `settingsSelectMenuProps` to every settings `Select`. Use `SettingsSelectMenuItem` when an option needs a short explanation below its label.\n\nUse `SettingsPasswordVisibilityToggle` as the end adornment for password fields. Keep its `visible` state, toggle handler, and localized show/hide labels in the owning dialog.\n\nUse `DialogReadOnlyField` for a name, path, connection, or other value that a dialog shows without allowing the user to change it. Give the field a specific label such as `Destination directory` or `File to delete`; do not recreate a styled text pill. Keep the normal MUI field height when its label is inside the outlined field. Use a subdued read-only surface while keeping long values selectable.\n\nWrite the dialog description as the outcome of the selected action. State what will be copied, moved, replaced, skipped, or deleted and name the source item for a single-item operation, then present the affected value in a labelled read-only field. Keep notices tied to their current condition: a no-op destination notice must disappear as soon as a renamed target makes the operation valid, without changing the dialog's layout.\n\n## Operation Context\n\nOperation dialogs show their subject and destination independently of translated prose. This lets a translated description use its natural word order and keeps a long identifier from making the dialog hard to scan.\n\nUse `DialogOperationContext` for passive operation metadata. Each entry has a translated label and a value with either the `fileName` or `path` kind. The component renders a vertical definition list, so every filename and path occupies its own line and does not share that line with explanatory text.\n\n`OverwriteConflictDialog` is the deliberate exception. Its compact Existing item and Incoming item metadata grids remain intact because they support side-by-side conflict comparison. Use `DialogIdentifierDisplay` for each Path value in those grids, but do not replace the grids with `DialogOperationContext`.\n\nUse `DialogIdentifierDisplay` inside this context rather than truncating an identifier locally. It keeps the full value in the accessible name, applies bidi isolation with `bdi` and `dir=\"auto\"`, and abbreviates only the visual value when the available width requires it. A shortened value has a hover-only tooltip with its full value. Do not make the identifier focusable and do not reveal the tooltip on focus or touch.\n\nFile-name shortening preserves the extension where possible. Path shortening preserves useful leading and trailing segments. Both use grapheme-aware boundaries, so combining characters and emoji sequences are never split. Breadcrumb segment labels must use `truncateTextByGrapheme` from `utils/pathDisplay` for the same reason.\n\nUse outcome-only translation strings for the dialog description. Do not interpolate filenames or paths into `Trans` text. For example, a single-item copy describes copying the item to the destination directory, then context rows identify `Source item` and `Destination directory`.\n\n## Feedback And Persistence\n\nRender feedback only while it is active. Field errors and warnings belong to their control; use normal MUI helper text below `md`, and pass `FieldFeedback` to `FormFieldLabel` at `md` and above so it replaces the left-column description. Error feedback uses the normal MUI error state. Warning text starts with `Warning:` and uses the warning color. Do not reserve blank helper-text space, clip feedback to one line, or use a tooltip as the only way to read it.\n\nUse `DialogNotice` and `DialogNoticeRegion` from `frontend/src/components/Dialog/` for non-field notices. A contextual condition known when the dialog opens belongs in the shell's `contextualNotice` slot, after its description and before the body. A result caused by an action belongs in the `actionNotice` slot immediately above the actions. Idle notices render no alert. An error alert uses the default dynamic `role=\"alert\"`; a non-urgent warning uses `role=\"status\"`. Do not move focus to an alert.\n\nOrdinary settings persist a valid committed value immediately. Selects, toggles, and checkboxes commit on change. Text and numeric fields commit on blur or Enter after local validation succeeds. Keep invalid candidates locally and associate their error with the field. Each field has at most one in-flight request; disable every representation of that field while it is pending, but do not queue, debounce, batch, or serialize unrelated fields. Show a `role=\"status\"` saving indicator only while active, then a brief saved indicator. A failed write remains a readable field error until editing or a later success resolves it.\n\nEvery settings update uses exactly one discriminated `{ field, value }` request and receives the matching canonical pair. Apply a response only to its matching field. Complete settings state is read through `GET`; routine settings pages have no Save, reset, dirty-state, or success-alert workflow. File Search and SMB policy fields are independent persisted keys; the backend validates correlated aggregates transactionally. SMB policy writes retain their full post-commit runtime refresh lifecycle, while its read-chunk-size update does not trigger that lifecycle.\n\n`userSettingsStore` is the sole frontend boundary for `/auth/me/settings`. Components use its field selectors and `useCurrentUserSetting()` hook, retain only local drafts/previews, and never store server-backed user settings in local storage. The store hydrates for identity changes, rejects stale requests, allows one write per field, and refreshes other tabs from invalidation-only BroadcastChannel messages.\n\nDuring a cancellable operation, keep its cancellation action enabled unless the owner is already processing the cancellation request. Move focus to that action when the pending state starts. Keep the primary action disabled while the operation is active. Archive progress must report only data actually provided by the operation: archive creation shows an indeterminate status, and extraction may show its processed-member count without inventing byte totals or an item total.\n\n## Implementation Checklist\n\n1. Start with `ResponsiveDialogShell` for the responsive Drawer and Dialog shell.\n2. Wrap the fields in `FormSurface` and one or more `FormGroup` components.\n3. Put every field in `FormRow`.\n4. Use `FormFieldLabel` only for a multi-field editor at `md` or wider. Keep one- and two-field operation dialogs in a single column with floating MUI labels at every width.\n5. Keep the below-`md` MUI `label`, `InputLabel`, and active `FormHelperText` props in the concrete control. Use normal field height for inline-labelled one- or two-field operation dialogs; do not reserve helper-text space.\n6. Use `SettingsFormSection` between related groups instead of recreating section borders and title spacing locally.\n7. Reuse the shared action styles when the dialog has split or responsive actions.\n8. Render conditional fields or sections only when their state applies, while keeping each visible control in a `FormRow`.\n\nFor a non-form dialog, start with `ResponsiveDialogShell` and retain only the content, selection, workflow, and keyboard behavior specific to that dialog. Do not duplicate MUI `Dialog`, `Drawer`, sticky mobile actions, focus restoration, or dialog surface styling in the owning component.\n\n## Accessibility And Validation\n\nAssociate desktop controls with their external labels and descriptions using `htmlFor`, `labelId`, and `aria-describedby` as appropriate. Preserve a description ID when an error replaces the description so the relationship remains valid.\n\nAfter a failed save or test, focus the first invalid field. Do not remove normal MUI error states from controls; the desktop error text supplements them by making the issue readable in the label column.\n\nUse field-level errors for validation that the dialog can determine before submitting. Do not repeat a field-owned error in a form-level alert. Error text must explain the cause and the corrective action, not only name a failed rule. Bounded reflow when feedback appears is expected and preferred to hidden space.\n\nPrefer a safe, valid default over presenting a predictable error when the dialog can infer the intended correction. For example, a one-item copy into its source directory should prefill an extension-aware name such as `report (copy).pdf`. Do not apply this pattern to a same-directory move: it is a rename operation, so the user must deliberately choose the new name.\n\nUse a stable form-level alert only when no editable field owns the remedy, such as a multi-item copy whose destination directory is also its source directory. Use error severity when the state blocks confirmation. Keep API failures in this form-level feedback region as well, above the form surface so they do not disrupt a desktop field row.\n\n## Testing And Review\n\nFor every dialog that adopts this pattern, cover all of the following:\n\n- The mobile Drawer and the `sm` through `\u003cmd` Dialog use the same single-column form semantics.\n- A populated narrow-screen field uses a floating MUI label, normal control height, and helper text below the field.\n- A multi-field editor retains external labels, compact controls, and desktop-only row dividers at `md` and above.\n- A one- or two-field operation dialog remains single-column and keeps floating labels at `md` and above.\n- Errors, focus-first-invalid behavior, keyboard handling, and pending action states still work.\n- The surface, controls, and helper text remain legible in both light and dark themes.\n- Long filenames and paths remain one line at phone, tablet, and desktop widths; shortened values expose the complete identifier only on hover.\n- Identifier rendering remains correct for mixed left-to-right and right-to-left text, including after the available width changes.\n- A cancellable pending workflow focuses its cancellation action and does not submit a duplicate request.\n\nFor every non-form dialog that adopts the shared shell, cover all of the following:\n\n- The phone Drawer has reachable actions above safe-area insets and does not obscure content in a short viewport.\n- Keyboard focus, Enter, Escape cancellation, and the dialog-specific safe default still work. Escape must always issue the dialog's cancellation request.\n- Picker and workflow state remains usable with a keyboard.\n- Dialog content and action states remain legible in light and dark themes.\n\nUse a live browser check at a phone width and a desktop width in addition to focused tests. Check a short viewport as well so the fixed mobile actions do not obscure the final control.\n", "2.0": "+++\ntitle = \"Settings Forms and Actions\"\n+++\n\nUse these conventions for settings pages and stateful settings editors. Pages share section, surface, and action styles. Editors keep the same form behavior across a phone drawer, a narrow dialog, and a desktop dialog without separate mobile and desktop forms.\n\nThe page reference is `frontend/src/pages/LocalDrivesSettings.tsx`; the dialog reference is `frontend/src/components/Admin/ConnectionDialog.tsx`.\n\n## When To Use It\n\nUse the page conventions for settings content and actions. Use the dialog pattern when an editor changes several related settings and needs validation, field descriptions, or more than one action.\n\nDo not use the form pattern for a confirmation or destructive-action dialog. Those should continue to use `ResponsiveDialogShell` directly with focused content and actions.\n\n## Settings Page Layout and Actions\n\nCompose settings pages with `SettingsPage`, `SettingsSectionList`, and `SettingsGroup`. Use `FormSurface` for the subdued background of an action section, not an additional bordered card. For action sections, put the description or metadata on the left and controls on the right in a `FormRow`: the columns stack below `md` and share the row at `md` and above. Right-align actions on desktop, allow them to wrap, and keep result notices below the row. An informational section such as Local Drives' Current status can keep its own layout; don't force it into an action row.\n\nChoose button styling by the action's role, not by whether its MUI variant is `outlined` or `contained`:\n\n| Role | Treatment | Example |\n|---|---|---|\n| Regular or secondary | Neutral `settingsUtilityButtonSx`; on a grey `FormSurface`, use `settingsFormSurfaceUtilityButtonSx` so the overlay background shows through, as it does for dialog inputs. Keep the existing border, hover, and keyboard-focus treatment. | Account \u003e Change password; Local Drives \u003e Test Current Pairing. |\n| Danger or alert | Red-tinted `settingsDestructiveButtonSx` for settings-page actions. Use the dialog action rules below for the confirmation. | Local Drives \u003e Unpair This Browser. |\n| Main or default | Prominent `settingsPrimaryButtonSx` for the main action on a grey settings-page surface and for the main action in a page footer or dialog. Avoid giving several routine actions the same emphasis. | Authentication \u003e Configure OIDC; Local Drives \u003e Pair This Browser. |\n\nAdd a relevant `@mui/icons-material` icon with `startIcon` to labeled outlined or contained settings-page action buttons that lack one. Leave text-only buttons, including buttons without an explicit outlined or contained variant, without icons. Adding an icon must not change the button's variant, colors, label, or behavior.\n\n## User Directory Layout\n\nUser Management renders roles and statuses as ordinary text, with each simultaneous status on its own line. Summary counts and removable filters remain badges. Keep column headings and cell values readable: wrap headings, email addresses, usernames, provider names, and other long values without truncating their underlying text. Top-align row contents, and reserve space for sort icons and row actions.\n\nUse the settings content container's width to choose between the desktop grid and stacked records, with a shared 40rem breakpoint for the table and its toolbar. Changing selected columns must not change the layout breakpoint. A narrow settings overlay must stack even on a wide screen. Preserve every selected field when stacking; don't introduce horizontal scrolling or silently hide columns. Show timestamps as a short localized date and time on separate lines, retaining the full timestamp in a tooltip and the original value in a semantic `time` element.\n\nPlace the desktop column chooser icon at the far-right end of the table header, above the row actions. In stacked layouts, place the Columns control at the toolbar's right edge. Keep the toolbar control available while the directory is loading or empty. Anchor the menu to the visible control, reposition it when the settings container resizes, and return focus to the visible control when it closes.\n\nValidate the layout in a real browser with all columns enabled, long identifiers, multiple statuses, different regional formats, narrow containers, mobile widths, and zoom. Component tests don't measure text overlap or container-query behavior.\n\n## Dialog Categories\n\nUse `ResponsiveDialogShell` from `frontend/src/components/Dialog/ResponsiveDialogShell.tsx` as the shared shell for every ordinary application dialog. It provides responsive Drawer and Dialog behavior, safe-area actions, overlay/form surface tokens, title and description relationships, close blocking, and focus restoration.\n\nSmall dialogs use traditional Cancel and confirmation actions; do not add a top-right close button.\n\nChoose the content pattern that matches the job:\n\n| Dialog type | Use | Examples |\n|---|---|---|\n| Multi-field editor | `ResponsiveDialogShell` with the form building blocks below. | Connections, users, OIDC configuration, copy or move. |\n| One- or two-field editor | `ResponsiveDialogShell` with a single-column form surface. Keep the floating MUI label at every width. | Create, rename, copy, and move. |\n| Decision | `ResponsiveDialogShell` with compact content and actions. Do not add `FormSurface`. | Delete, overwrite conflict, application update, connection test result. |\n| Picker | `ResponsiveDialogShell` with a listbox or selection grid. Keep the picker\u2019s keyboard and selection semantics in the owning component. | Viewer and theme pickers. |\n| Short workflow | `ResponsiveDialogShell` with state-specific body and actions. | Companion pairing. |\n| Full-screen workspace | Keep the specialized full-screen viewer shell. Share only reusable behavior that does not interfere with the viewer\u2019s focus, toolbar, or third-party integration. | Image, PDF, Markdown, and text viewers. |\n\nThe desktop settings overlay and mobile settings drawer are navigation containers, not form dialogs. Keep their information architecture separate while composing settings-form pages inside them.\n\n## Keyboard Isolation\n\n`ResponsiveDialogShell` establishes a keyboard shortcut scope automatically for both its Drawer and Dialog layouts. While it's open, `useKeyboardShortcuts` ignores background registrations and lets the innermost open dialog own shortcuts, including when a control portals outside the dialog. The shell also stops key events from bubbling into parent workspace handlers. Closing the dialog releases its scope; normal shortcut handling resumes when focus returns to the workspace.\n\nDon't add dialog-specific flags to parent shortcut handlers to provide this isolation. Keep ordinary dialog keyboard behavior in the shell's `onKeyDown` or `onEscape` callbacks. If dialog content needs `useKeyboardShortcuts`, register it in a child component rendered inside the shell so it inherits the dialog's scope, not in the component that creates the shell. Existing focus trapping and interactive-control checks still apply.\n\nEscape dismissal goes through MUI's modal close callback, preserving its top-modal and IME process-key checks. `onEscape`, when supplied, replaces the normal Escape close action and runs once, even when `disableClose` blocks ordinary closing. Use it for cancellation requests during pending operations. Close buttons and backdrop requests still use `onClose` and respect `disableClose`. Don't add document-level Escape listeners or duplicate Escape closing in `onKeyDown`; the shared shell owns that behavior.\n\n## Dialog Action Buttons\n\nChoose each action's treatment by what it does, including in decisions embedded inside full-screen viewers. Keep the viewer workspace shell and toolbars separate from its decision dialogs.\n\n| Role | Treatment | Example |\n|---|---|---|\n| Destructive confirmation | MUI `variant=\"contained\" color=\"error\"`, as in the File delete dialog. Do not use the red-tinted settings-page `settingsDestructiveButtonSx` or introduce another red button style. | Delete, Discard unsaved changes, or Continue with overwrite selected. |\n| Main non-destructive action | MUI `variant=\"contained\"` in the theme's primary color. | Create directory, Save, Retry, or the sole Close action. |\n| Secondary or alternate action | MUI `variant=\"outlined\"` with the existing subdued utility fill and focus treatment. | Cancel, Later, Ignore, or Open without saving. |\n\nAn action's role can change with the selected option: a conflict dialog's Continue is destructive only when it will overwrite an existing item. When a decision offers both Save and Discard, distinguish the primary and destructive actions without changing what either one does. Do not restyle settings-page triggers when styling their confirmation dialogs.\n\nVisual priority does not determine Enter behavior. For safety-critical decisions, focus the least destructive action on opening; for input workflows, focus the first input. Never make a destructive action the default Enter action unless the user has already focused it. Keep cancellation available and focused during cancellable pending operations. Use `ResponsiveDialogShell` for application confirmations rather than native `window.confirm`, whose buttons cannot follow these styles.\n\n## Shared Building Blocks\n\nImport reusable structural primitives and control styles from `frontend/src/components/Form/FormLayout.tsx`. Settings-only sections remain in `frontend/src/components/Settings/SettingsFormLayout.tsx`.\n\n| Building block | Responsibility |\n|---|---|\n| `FormSurface` | Provides the shared form-surface background and interior padding. |\n| `FormGroup` | Groups related rows and adds row dividers only at the desktop breakpoint. |\n| `FormRow` | Uses one column below `md` and the two-column label/control grid at `md` and above. |\n| `FormFieldLabel` | Renders a desktop label with its description or active error/warning. |\n| `SettingsFormSection` | Separates groups with the standard settings heading, subdued divider, and spacing. |\n| `SettingsSelectMenuItem` | Renders a select option with a label and supporting description. |\n| `SettingsPasswordVisibilityToggle` | Renders the shared show/hide password adornment. The owning dialog keeps password visibility state and translated labels. |\n| `formFieldControlSx` | Aligns a control to the desktop control column. |\n| `formSelectControlSx` | Makes a desktop select content-width and right-aligned. |\n| `formOutlinedControlSx` | Applies the shared outlined-field, focus, error, and floating-label treatment. |\n| `formSelectSx` and `formSelectMenuProps` | Keep select values, icons, and options at the standard subdued text color. |\n\nKeep field state, API calls, validation rules, translations, and the concrete MUI controls in the owning dialog. The shared layer owns layout and presentation; it must not become a schema-driven form engine.\n\n## Responsive Contract\n\nMulti-field settings editors have exactly two form layouts. One- and two-field operation dialogs stay single-column at every width so long names and paths retain the available width.\n\n### Below `md`\n\nUse one column in both responsive shells.\n\n- Below `sm`, `ResponsiveDialogShell` renders the form in a Drawer.\n- From `sm` through `\u003cmd`, it renders the same form in a Dialog.\n- Use normal-height MUI outlined controls.\n- Keep MUI labels inside empty fields and floating in the outline after focus or entry.\n- Keep descriptions and validation errors directly below their controls as MUI helper text.\n- Use the grouped surface and section heading, but do not show individual field-row dividers.\n\n### At `md` And Above For Multi-Field Editors\n\nUse the two-column desktop layout.\n\n- Put labels and descriptions in the left column.\n- Put compact controls in the right column.\n- For text inputs and selects with an external label in the left column, use MUI `size=\"small\"` and omit the control's `label` or `InputLabel`. The left-column label is the only visible label; associate it with the control so it remains accessible. Below `md`, restore the control's floating label and normal height.\n- Replace the left-column description with the validation error instead of showing helper text below the input.\n- Keep full-width text inputs within the control column.\n- Use content-width, right-aligned selects when the selected option remains readable.\n- For checkboxes and switches, use the external label and description on the left, with the control in the right column. Keep the control label and helper text next to the control below `md`.\n- For boolean settings, use a `Switch` with a visible `On` or `Off` state label. Let Material UI apply its standard palette colors.\n- For native `datetime-local` inputs, preserve the MUI shrunk input label below `md`; use the external desktop label at `md` and above.\n- Show subdued dividers between rows in a group.\n\n## Control Conventions\n\nApply `settingsSelectSx` and `settingsSelectMenuProps` to every settings `Select`. Use `SettingsSelectMenuItem` when an option needs a short explanation below its label.\n\nUse `SettingsPasswordVisibilityToggle` as the end adornment for password fields. Keep its `visible` state, toggle handler, and localized show/hide labels in the owning dialog.\n\nUse `DialogReadOnlyField` for a name, path, connection, or other value that a dialog shows without allowing the user to change it. Give the field a specific label such as `Destination directory` or `File to delete`; do not recreate a styled text pill. Keep the normal MUI field height when its label is inside the outlined field. Use a subdued read-only surface while keeping long values selectable.\n\nWrite the dialog description as the outcome of the selected action. State what will be copied, moved, replaced, skipped, or deleted and name the source item for a single-item operation, then present the affected value in a labelled read-only field. Keep notices tied to their current condition: a no-op destination notice must disappear as soon as a renamed target makes the operation valid, without changing the dialog's layout.\n\n## Operation Context\n\nOperation dialogs show their subject and destination independently of translated prose. This lets a translated description use its natural word order and keeps a long identifier from making the dialog hard to scan.\n\nUse `DialogOperationContext` for passive operation metadata. Each entry has a translated label and a value with either the `fileName` or `path` kind. The component renders a vertical definition list, so every filename and path occupies its own line and does not share that line with explanatory text.\n\n`OverwriteConflictDialog` is the deliberate exception. Its compact Existing item and Incoming item metadata grids remain intact because they support side-by-side conflict comparison. Use `DialogIdentifierDisplay` for each Path value in those grids, but do not replace the grids with `DialogOperationContext`.\n\nUse `DialogIdentifierDisplay` inside this context rather than truncating an identifier locally. It keeps the full value in the accessible name, applies bidi isolation with `bdi` and `dir=\"auto\"`, and abbreviates only the visual value when the available width requires it. A shortened value has a hover-only tooltip with its full value. Do not make the identifier focusable and do not reveal the tooltip on focus or touch.\n\nFile-name shortening preserves the extension where possible. Path shortening preserves useful leading and trailing segments. Both use grapheme-aware boundaries, so combining characters and emoji sequences are never split. Breadcrumb segment labels must use `truncateTextByGrapheme` from `utils/pathDisplay` for the same reason.\n\nUse outcome-only translation strings for the dialog description. Do not interpolate filenames or paths into `Trans` text. For example, a single-item copy describes copying the item to the destination directory, then context rows identify `Source item` and `Destination directory`.\n\n## Feedback And Persistence\n\nRender feedback only while it is active. Field errors and warnings belong to their control; use normal MUI helper text below `md`, and pass `FieldFeedback` to `FormFieldLabel` at `md` and above so it replaces the left-column description. Error feedback uses the normal MUI error state. Warning text starts with `Warning:` and uses the warning color. Do not reserve blank helper-text space, clip feedback to one line, or use a tooltip as the only way to read it.\n\nUse `DialogNotice` and `DialogNoticeRegion` from `frontend/src/components/Dialog/` for non-field notices. A contextual condition known when the dialog opens belongs in the shell's `contextualNotice` slot, after its description and before the body. A result caused by an action belongs in the `actionNotice` slot immediately above the actions. Idle notices render no alert. An error alert uses the default dynamic `role=\"alert\"`; a non-urgent warning uses `role=\"status\"`. Do not move focus to an alert.\n\nOrdinary settings persist a valid committed value immediately. Selects, toggles, and checkboxes commit on change. Text and numeric fields commit on blur or Enter after local validation succeeds. Keep invalid candidates locally and associate their error with the field. Each field has at most one in-flight request; disable every representation of that field while it is pending, but do not queue, debounce, batch, or serialize unrelated fields. Show a `role=\"status\"` saving indicator only while active, then a brief saved indicator. A failed write remains a readable field error until editing or a later success resolves it.\n\nEvery settings update uses exactly one discriminated `{ field, value }` request and receives the matching canonical pair. Apply a response only to its matching field. Complete settings state is read through `GET`; routine settings pages have no Save, reset, dirty-state, or success-alert workflow. File Search and SMB policy fields are independent persisted keys; the backend validates correlated aggregates transactionally. SMB policy writes retain their full post-commit runtime refresh lifecycle, while its read-chunk-size update does not trigger that lifecycle.\n\n`userSettingsStore` is the sole frontend boundary for `/auth/me/settings`. Components use its field selectors and `useCurrentUserSetting()` hook, retain only local drafts/previews, and never store server-backed user settings in local storage. The store hydrates for identity changes, rejects stale requests, allows one write per field, and refreshes other tabs from invalidation-only BroadcastChannel messages.\n\nDuring a cancellable operation, keep its cancellation action enabled unless the owner is already processing the cancellation request. Move focus to that action when the pending state starts. Keep the primary action disabled while the operation is active. Archive progress must report only data actually provided by the operation: archive creation shows an indeterminate status, and extraction may show its processed-member count without inventing byte totals or an item total.\n\n## Implementation Checklist\n\n1. Start with `ResponsiveDialogShell` for the responsive Drawer and Dialog shell.\n2. Wrap the fields in `FormSurface` and one or more `FormGroup` components.\n3. Put every field in `FormRow`.\n4. Use `FormFieldLabel` only for a multi-field editor at `md` or wider. Keep one- and two-field operation dialogs in a single column with floating MUI labels at every width.\n5. Keep the below-`md` MUI `label`, `InputLabel`, and active `FormHelperText` props in the concrete control. Use normal field height for inline-labelled one- or two-field operation dialogs; do not reserve helper-text space.\n6. Use `SettingsFormSection` between related groups instead of recreating section borders and title spacing locally.\n7. Reuse the shared action styles when the dialog has split or responsive actions.\n8. Render conditional fields or sections only when their state applies, while keeping each visible control in a `FormRow`.\n\nFor a non-form dialog, start with `ResponsiveDialogShell` and retain only the content, selection, workflow, and keyboard behavior specific to that dialog. Do not duplicate MUI `Dialog`, `Drawer`, sticky mobile actions, focus restoration, or dialog surface styling in the owning component.\n\n## Accessibility And Validation\n\nAssociate desktop controls with their external labels and descriptions using `htmlFor`, `labelId`, and `aria-describedby` as appropriate. Preserve a description ID when an error replaces the description so the relationship remains valid.\n\nAfter a failed save or test, focus the first invalid field. Do not remove normal MUI error states from controls; the desktop error text supplements them by making the issue readable in the label column.\n\nUse field-level errors for validation that the dialog can determine before submitting. Do not repeat a field-owned error in a form-level alert. Error text must explain the cause and the corrective action, not only name a failed rule. Bounded reflow when feedback appears is expected and preferred to hidden space.\n\nPrefer a safe, valid default over presenting a predictable error when the dialog can infer the intended correction. For example, a one-item copy into its source directory should prefill an extension-aware name such as `report (copy).pdf`. Do not apply this pattern to a same-directory move: it is a rename operation, so the user must deliberately choose the new name.\n\nUse a stable form-level alert only when no editable field owns the remedy, such as a multi-item copy whose destination directory is also its source directory. Use error severity when the state blocks confirmation. Keep API failures in this form-level feedback region as well, above the form surface so they do not disrupt a desktop field row.\n\n## Testing And Review\n\nFor settings-page action sections, check the one-column layout below `md` and the two-column description/action layout at `md` and above. Check neutral-button contrast against grey form surfaces in light and dark themes, including hover and keyboard focus. Check that added icons do not change accessible names or cause button labels to overflow at phone widths. Keep informational sections readable without imposing the action-row grid, and verify that notices remain below the row.\n\nFor dialog actions, check contained error and primary buttons and outlined secondary buttons in light and dark themes, including hover and keyboard focus. Verify that option-dependent destructive actions change treatment without changing their safe initial focus or Enter behavior.\n\nFor every dialog that adopts this pattern, cover all of the following:\n\n- The mobile Drawer and the `sm` through `\u003cmd` Dialog use the same single-column form semantics.\n- A populated narrow-screen field uses a floating MUI label, normal control height, and helper text below the field.\n- A multi-field editor retains external labels, compact controls, and desktop-only row dividers at `md` and above.\n- A one- or two-field operation dialog remains single-column and keeps floating labels at `md` and above.\n- Errors, focus-first-invalid behavior, keyboard handling, and pending action states still work.\n- The surface, controls, and helper text remain legible in both light and dark themes.\n- Long filenames and paths remain one line at phone, tablet, and desktop widths; shortened values expose the complete identifier only on hover.\n- Identifier rendering remains correct for mixed left-to-right and right-to-left text, including after the available width changes.\n- A cancellable pending workflow focuses its cancellation action and does not submit a duplicate request.\n\nFor every non-form dialog that adopts the shared shell, cover all of the following:\n\n- The phone Drawer has reachable actions above safe-area insets and does not obscure content in a short viewport.\n- Keyboard focus, Enter, Escape cancellation, and the dialog-specific safe default still work. Escape must always issue the dialog's cancellation request.\n- Picker and workflow state remains usable with a keyboard.\n- Dialog content and action states remain legible in light and dark themes.\n\nUse a live browser check at a phone width and a desktop width in addition to focused tests. Check a short viewport as well so the fixed mobile actions do not obscure the final control.\n"}, "flags": {"has_branched": true, "has_inherited": false, "has_structural": false, "has_invalid": false}}, {"id": "section:developer-guide/companion-architecture", "parent_id": "book:developer-guide", "depth": 1, "kind": "section", "label": "companion-architecture", "title": "Companion Architecture", "path": "developer-guide/companion-architecture", "has_children": true, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Companion Architecture\"\n+++\n\nThe companion exists because some valuable workflows cannot be delivered by the browser app alone.\n\nStart with:\n\n- [Companion Overview](./companion-overview/)\n- [Companion Runtime and Native-App Editing](./companion-runtime-and-native-app-editing/)\n- [Browser-to-Companion Trust Model](./browser-to-companion-trust-model/)\n- [Local-Drive and Save-Back Pipeline](./local-drive-and-save-back-pipeline/)\n\nUse this section when you are changing local-drive access, native-app editing, pairing, or desktop-side diagnostics.\n", "0.8": "+++\ntitle = \"Companion Architecture\"\n+++\n\nThe companion exists because some valuable workflows cannot be delivered by the browser app alone.\n\nStart with:\n\n- [Companion Overview](./companion-overview/)\n- [Companion Runtime and Native-App Editing](./companion-runtime-and-native-app-editing/)\n- [Browser-to-Companion Trust Model](./browser-to-companion-trust-model/)\n- [Local-Drive and Save-Back Pipeline](./local-drive-and-save-back-pipeline/)\n\nUse this section when you are changing local-drive access, native-app editing, pairing, or desktop-side diagnostics.\n", "0.9": "+++\ntitle = \"Companion Architecture\"\n+++\n\nThe companion exists because some valuable workflows cannot be delivered by the browser app alone.\n\nStart with:\n\n- [Companion Overview](./companion-overview/)\n- [Companion Runtime and Native-App Editing](./companion-runtime-and-native-app-editing/)\n- [Browser-to-Companion Trust Model](./browser-to-companion-trust-model/)\n- [Local-Drive and Save-Back Pipeline](./local-drive-and-save-back-pipeline/)\n\nUse this section when you are changing local-drive access, native-app editing, pairing, or desktop-side diagnostics.\n", "1.0": "+++\ntitle = \"Companion Architecture\"\n+++\n\nThe companion exists because some valuable workflows cannot be delivered by the browser app alone.\n\nStart with:\n\n- [Companion Overview](./companion-overview/)\n- [Companion Runtime and Native-App Editing](./companion-runtime-and-native-app-editing/)\n- [Browser-to-Companion Trust Model](./browser-to-companion-trust-model/)\n- [Local-Drive and Save-Back Pipeline](./local-drive-and-save-back-pipeline/)\n\nUse this section when you are changing local-drive access, native-app editing, pairing, or desktop-side diagnostics.\n", "2.0": "+++\ntitle = \"Companion Architecture\"\n+++\n\nThe companion exists because some valuable workflows cannot be delivered by the browser app alone.\n\nStart with:\n\n- [Companion Overview](./companion-overview/)\n- [Companion Runtime and Native-App Editing](./companion-runtime-and-native-app-editing/)\n- [Browser-to-Companion Trust Model](./browser-to-companion-trust-model/)\n- [Local-Drive and Save-Back Pipeline](./local-drive-and-save-back-pipeline/)\n\nUse this section when you are changing local-drive access, native-app editing, pairing, or desktop-side diagnostics.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/companion-architecture/companion-overview", "parent_id": "section:developer-guide/companion-architecture", "depth": 2, "kind": "page", "label": "companion-overview", "title": "Companion Overview", "path": "developer-guide/companion-architecture/companion-overview", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Companion Overview\"\n+++\n\nSambee Companion is a lightweight desktop application built with Tauri v2, a Preact UI, and a Rust backend.\n\nIt exists for two major reasons:\n\n- to enable native-app editing of files that originate in Sambee workflows\n- to provide a paired localhost API for local-drive access and browser-to-desktop integrations\n\n## The Two Main Capability Paths\n\n### Deep-Link Native-App Editing\n\nFor SMB-backed edit workflows:\n\n1. The browser starts the action.\n2. The OS launches or activates the companion through a `sambee://` deep link.\n3. The companion exchanges tokens, downloads the file, acquires an edit lock, and opens the file in a native app.\n4. The companion later uploads the result and releases the lock.\n\n### Paired Localhost API\n\nFor local-drive access and related desktop-side capabilities:\n\n1. The browser detects the companion on `127.0.0.1:21549`.\n2. Browser and companion perform an explicit pairing flow.\n3. The browser uses the authenticated localhost API to enumerate drives and perform local file operations.\n4. WebSocket notifications keep the browser updated when local directories change.\n\nFor the full desktop-side data path, continue to [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\nFor the deep-link runtime, native-app edit lifecycle, and operation recovery model, continue to [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/).\n\n## Why This Is a Separate App\n\nThe companion handles behavior the browser cannot safely or reliably do by itself.\n\n- launching installed native apps\n- accessing local drives on the user's computer\n- holding desktop-side state and recovery information\n- participating in OS-level integration such as deep-link registration and tray behavior\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/` | Preact UI, preferences, pairing windows, and desktop-facing interaction surfaces |\n| `companion/src-tauri/src/` | Rust backend for deep links, local API, file operations, logging, and integration with the OS |\n| `companion/src-tauri/src/server/` | localhost pairing, auth, drive enumeration, handlers, and watcher behavior |\n| `companion/src-tauri/src/commands/` | command handlers for file opening, upload, pairing, update, and related actions |\n\n## Trust and Safety Boundaries\n\nThe companion adds power, so it also adds security-sensitive behavior.\n\n- deep-link flows depend on short-lived tokens and server-side lock behavior\n- localhost API access is intentionally paired and authenticated\n- the app is single-instance so later deep links are routed to the running process\n- desktop-local behavior should not silently bypass the browser or backend contracts it depends on\n\n## What Usually Breaks When This Layer Changes\n\n- native-app editing lifecycle behavior\n- lock release or upload expectations after editing\n- browser pairing and local-drive discovery\n- localization sync or other browser-to-desktop coordination\n- platform-specific startup, packaging, or tray behavior\n\n## Go Deeper\n\n- [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/): deep-link ingress, app picker flow, operation persistence, recovery, and tray/window runtime behavior\n- [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/): deep links, pairing, localhost auth, and trust boundaries\n- [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/): how local-drive operations and SMB-backed native-app editing differ in practice\n\n## Validation Expectations\n\nWhen companion behavior changes, start with:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nThen add frontend or backend checks if the companion change alters a shared workflow contract.\n", "0.8": "+++\ntitle = \"Companion Overview\"\n+++\n\nSambee Companion is a lightweight desktop application built with Tauri v2, a Preact UI, and a Rust backend.\n\nIt exists for two major reasons:\n\n- to enable native-app editing of files that originate in Sambee workflows\n- to provide a paired localhost API for local-drive access and browser-to-desktop integrations\n\n## The Two Main Capability Paths\n\n### Deep-Link Native-App Editing\n\nFor SMB-backed edit workflows:\n\n1. The browser starts the action.\n2. The OS launches or activates the companion through a `sambee://` deep link.\n3. The companion exchanges tokens, downloads the file, acquires an edit lock, and opens the file in a native app.\n4. The companion later uploads the result and releases the lock.\n\n### Paired Localhost API\n\nFor local-drive access and related desktop-side capabilities:\n\n1. The browser detects the companion on `127.0.0.1:21549`.\n2. Browser and companion perform an explicit pairing flow.\n3. The browser uses the authenticated localhost API to enumerate drives and perform local file operations.\n4. WebSocket notifications keep the browser updated when local directories change.\n\nFor the full desktop-side data path, continue to [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\nFor the deep-link runtime, native-app edit lifecycle, and operation recovery model, continue to [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/).\n\n## Why This Is a Separate App\n\nThe companion handles behavior the browser cannot safely or reliably do by itself.\n\n- launching installed native apps\n- accessing local drives on the user's computer\n- holding desktop-side state and recovery information\n- participating in OS-level integration such as deep-link registration and tray behavior\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/` | Preact UI, preferences, pairing windows, and desktop-facing interaction surfaces |\n| `companion/src-tauri/src/` | Rust backend for deep links, local API, file operations, logging, and integration with the OS |\n| `companion/src-tauri/src/server/` | localhost pairing, auth, drive enumeration, handlers, and watcher behavior |\n| `companion/src-tauri/src/commands/` | command handlers for file opening, upload, pairing, update, and related actions |\n\n## Trust and Safety Boundaries\n\nThe companion adds power, so it also adds security-sensitive behavior.\n\n- deep-link flows depend on short-lived tokens and server-side lock behavior\n- localhost API access is intentionally paired and authenticated\n- the app is single-instance so later deep links are routed to the running process\n- desktop-local behavior should not silently bypass the browser or backend contracts it depends on\n\n## What Usually Breaks When This Layer Changes\n\n- native-app editing lifecycle behavior\n- lock release or upload expectations after editing\n- browser pairing and local-drive discovery\n- localization sync or other browser-to-desktop coordination\n- platform-specific startup, packaging, or tray behavior\n\n## Go Deeper\n\n- [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/): deep-link ingress, app picker flow, operation persistence, recovery, and tray/window runtime behavior\n- [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/): deep links, pairing, localhost auth, and trust boundaries\n- [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/): how local-drive operations and SMB-backed native-app editing differ in practice\n\n## Validation Expectations\n\nWhen companion behavior changes, start with:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nThen add frontend or backend checks if the companion change alters a shared workflow contract.\n", "0.9": "+++\ntitle = \"Companion Overview\"\n+++\n\nSambee Companion is a lightweight desktop application built with Tauri v2, a Preact UI, and a Rust backend.\n\nIt exists for two major reasons:\n\n- to enable native-app editing of files that originate in Sambee workflows\n- to provide a paired localhost API for local-drive access and browser-to-desktop integrations\n\n## The Two Main Capability Paths\n\n### Deep-Link Native-App Editing\n\nFor SMB-backed edit workflows:\n\n1. The browser starts the action.\n2. The OS launches or activates the companion through a `sambee://` deep link.\n3. The companion exchanges tokens, downloads the file, acquires an edit lock, and opens the file in a native app.\n4. The companion later uploads the result and releases the lock.\n\n### Paired Localhost API\n\nFor local-drive access and related desktop-side capabilities:\n\n1. The browser detects the companion on `127.0.0.1:21549`.\n2. Browser and companion perform an explicit pairing flow.\n3. The browser uses the authenticated localhost API to enumerate drives and perform local file operations.\n4. WebSocket notifications keep the browser updated when local directories change.\n\nFor the full desktop-side data path, continue to [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\nFor the deep-link runtime, native-app edit lifecycle, and operation recovery model, continue to [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/).\n\n## Why This Is a Separate App\n\nThe companion handles behavior the browser cannot safely or reliably do by itself.\n\n- launching installed native apps\n- accessing local drives on the user's computer\n- holding desktop-side state and recovery information\n- participating in OS-level integration such as deep-link registration and tray behavior\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/` | Preact UI, preferences, pairing windows, and desktop-facing interaction surfaces |\n| `companion/src-tauri/src/` | Rust backend for deep links, local API, file operations, logging, and integration with the OS |\n| `companion/src-tauri/src/server/` | localhost pairing, auth, drive enumeration, handlers, and watcher behavior |\n| `companion/src-tauri/src/commands/` | command handlers for file opening, upload, pairing, update, and related actions |\n\n## Trust and Safety Boundaries\n\nThe companion adds power, so it also adds security-sensitive behavior.\n\n- deep-link flows depend on short-lived tokens and server-side lock behavior\n- localhost API access is intentionally paired and authenticated\n- the app is single-instance so later deep links are routed to the running process\n- desktop-local behavior should not silently bypass the browser or backend contracts it depends on\n\n## What Usually Breaks When This Layer Changes\n\n- native-app editing lifecycle behavior\n- lock release or upload expectations after editing\n- browser pairing and local-drive discovery\n- localization sync or other browser-to-desktop coordination\n- platform-specific startup, packaging, or tray behavior\n\n## Go Deeper\n\n- [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/): deep-link ingress, app picker flow, operation persistence, recovery, and tray/window runtime behavior\n- [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/): deep links, pairing, localhost auth, and trust boundaries\n- [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/): how local-drive operations and SMB-backed native-app editing differ in practice\n\n## Validation Expectations\n\nWhen companion behavior changes, start with:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nThen add frontend or backend checks if the companion change alters a shared workflow contract.\n", "1.0": "+++\ntitle = \"Companion Overview\"\n+++\n\nSambee Companion is a lightweight desktop application built with Tauri v2, a Preact UI, and a Rust backend.\n\nIt exists for two major reasons:\n\n- to enable native-app editing of files that originate in Sambee workflows\n- to provide a paired localhost API for local-drive access and browser-to-desktop integrations\n\n## The Two Main Capability Paths\n\n### Deep-Link Native-App Editing\n\nFor SMB-backed edit workflows:\n\n1. The browser starts the action.\n2. The OS launches or activates the companion through a `sambee://` deep link.\n3. The companion exchanges tokens, downloads the file, acquires an edit lock, and opens the file in a native app.\n4. The companion later uploads the result and releases the lock.\n\n### Paired Localhost API\n\nFor local-drive access and related desktop-side capabilities:\n\n1. The browser detects the companion on `127.0.0.1:21549`.\n2. Browser and companion perform an explicit pairing flow.\n3. The browser uses the authenticated localhost API to enumerate drives and perform local file operations.\n4. WebSocket notifications keep the browser updated when local directories change.\n\nFor the full desktop-side data path, continue to [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\nFor the deep-link runtime, native-app edit lifecycle, and operation recovery model, continue to [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/).\n\n## Why This Is a Separate App\n\nThe companion handles behavior the browser cannot safely or reliably do by itself.\n\n- launching installed native apps\n- accessing local drives on the user's computer\n- holding desktop-side state and recovery information\n- participating in OS-level integration such as deep-link registration and tray behavior\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/` | Preact UI, preferences, pairing windows, and desktop-facing interaction surfaces |\n| `companion/src-tauri/src/` | Rust backend for deep links, local API, file operations, logging, and integration with the OS |\n| `companion/src-tauri/src/server/` | localhost pairing, auth, drive enumeration, handlers, and watcher behavior |\n| `companion/src-tauri/src/commands/` | command handlers for file opening, upload, pairing, update, and related actions |\n\n## Trust and Safety Boundaries\n\nThe companion adds power, so it also adds security-sensitive behavior.\n\n- deep-link flows depend on short-lived tokens and server-side lock behavior\n- localhost API access is intentionally paired and authenticated\n- the app is single-instance so later deep links are routed to the running process\n- desktop-local behavior should not silently bypass the browser or backend contracts it depends on\n\n## What Usually Breaks When This Layer Changes\n\n- native-app editing lifecycle behavior\n- lock release or upload expectations after editing\n- browser pairing and local-drive discovery\n- localization sync or other browser-to-desktop coordination\n- platform-specific startup, packaging, or tray behavior\n\n## Go Deeper\n\n- [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/): deep-link ingress, app picker flow, operation persistence, recovery, and tray/window runtime behavior\n- [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/): deep links, pairing, localhost auth, and trust boundaries\n- [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/): how local-drive operations and SMB-backed native-app editing differ in practice\n\n## Validation Expectations\n\nWhen companion behavior changes, start with:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nThen add frontend or backend checks if the companion change alters a shared workflow contract.\n", "2.0": "+++\ntitle = \"Companion Overview\"\n+++\n\nSambee Companion is a lightweight desktop application built with Tauri v2, a Preact UI, and a Rust backend.\n\nIt exists for two major reasons:\n\n- to enable native-app editing of files that originate in Sambee workflows\n- to provide a paired localhost API for local-drive access and browser-to-desktop integrations\n\n## The Two Main Capability Paths\n\n### Deep-Link Native-App Editing\n\nFor SMB-backed edit workflows:\n\n1. The browser starts the action.\n2. The OS launches or activates the companion through a `sambee://` deep link.\n3. The companion exchanges tokens, downloads the file, acquires an edit lock, and opens the file in a native app.\n4. The companion later uploads the result and releases the lock.\n\n### Paired Localhost API\n\nFor local-drive access and related desktop-side capabilities:\n\n1. The browser detects the companion on `127.0.0.1:21549`.\n2. Browser and companion perform an explicit pairing flow.\n3. The browser uses the authenticated localhost API to enumerate drives and perform local file operations.\n4. WebSocket notifications keep the browser updated when local directories change.\n\nFor the full desktop-side data path, continue to [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\nFor the deep-link runtime, native-app edit lifecycle, and operation recovery model, continue to [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/).\n\n## Why This Is a Separate App\n\nThe companion handles behavior the browser cannot safely or reliably do by itself.\n\n- launching installed native apps\n- accessing local drives on the user's computer\n- holding desktop-side state and recovery information\n- participating in OS-level integration such as deep-link registration and tray behavior\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/` | Preact UI, preferences, pairing windows, and desktop-facing interaction surfaces |\n| `companion/src-tauri/src/` | Rust backend for deep links, local API, file operations, logging, and integration with the OS |\n| `companion/src-tauri/src/server/` | localhost pairing, auth, drive enumeration, handlers, and watcher behavior |\n| `companion/src-tauri/src/commands/` | command handlers for file opening, upload, pairing, update, and related actions |\n\n## Trust and Safety Boundaries\n\nThe companion adds power, so it also adds security-sensitive behavior.\n\n- deep-link flows depend on short-lived tokens and server-side lock behavior\n- localhost API access is intentionally paired and authenticated\n- the app is single-instance so later deep links are routed to the running process\n- desktop-local behavior should not silently bypass the browser or backend contracts it depends on\n\n## What Usually Breaks When This Layer Changes\n\n- native-app editing lifecycle behavior\n- lock release or upload expectations after editing\n- browser pairing and local-drive discovery\n- localization sync or other browser-to-desktop coordination\n- platform-specific startup, packaging, or tray behavior\n\n## Go Deeper\n\n- [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/): deep-link ingress, app picker flow, operation persistence, recovery, and tray/window runtime behavior\n- [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/): deep links, pairing, localhost auth, and trust boundaries\n- [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/): how local-drive operations and SMB-backed native-app editing differ in practice\n\n## Validation Expectations\n\nWhen companion behavior changes, start with:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nThen add frontend or backend checks if the companion change alters a shared workflow contract.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Companion Overview\"\n+++\n\nSambee Companion is a lightweight desktop application built with Tauri v2, a Preact UI, and a Rust backend.\n\nIt exists for two major reasons:\n\n- to enable native-app editing of files that originate in Sambee workflows\n- to provide a paired localhost API for local-drive access and browser-to-desktop integrations\n\n## The Two Main Capability Paths\n\n### Deep-Link Native-App Editing\n\nFor SMB-backed edit workflows:\n\n1. The browser starts the action.\n2. The OS launches or activates the companion through a `sambee://` deep link.\n3. The companion exchanges tokens, downloads the file, acquires an edit lock, and opens the file in a native app.\n4. The companion later uploads the result and releases the lock.\n\n### Paired Localhost API\n\nFor local-drive access and related desktop-side capabilities:\n\n1. The browser detects the companion on `127.0.0.1:21549`.\n2. Browser and companion perform an explicit pairing flow.\n3. The browser uses the authenticated localhost API to enumerate drives and perform local file operations.\n4. WebSocket notifications keep the browser updated when local directories change.\n\nFor the full desktop-side data path, continue to [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\nFor the deep-link runtime, native-app edit lifecycle, and operation recovery model, continue to [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/).\n\n## Why This Is a Separate App\n\nThe companion handles behavior the browser cannot safely or reliably do by itself.\n\n- launching installed native apps\n- accessing local drives on the user's computer\n- holding desktop-side state and recovery information\n- participating in OS-level integration such as deep-link registration and tray behavior\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/` | Preact UI, preferences, pairing windows, and desktop-facing interaction surfaces |\n| `companion/src-tauri/src/` | Rust backend for deep links, local API, file operations, logging, and integration with the OS |\n| `companion/src-tauri/src/server/` | localhost pairing, auth, drive enumeration, handlers, and watcher behavior |\n| `companion/src-tauri/src/commands/` | command handlers for file opening, upload, pairing, update, and related actions |\n\n## Trust and Safety Boundaries\n\nThe companion adds power, so it also adds security-sensitive behavior.\n\n- deep-link flows depend on short-lived tokens and server-side lock behavior\n- localhost API access is intentionally paired and authenticated\n- the app is single-instance so later deep links are routed to the running process\n- desktop-local behavior should not silently bypass the browser or backend contracts it depends on\n\n## What Usually Breaks When This Layer Changes\n\n- native-app editing lifecycle behavior\n- lock release or upload expectations after editing\n- browser pairing and local-drive discovery\n- localization sync or other browser-to-desktop coordination\n- platform-specific startup, packaging, or tray behavior\n\n## Go Deeper\n\n- [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/): deep-link ingress, app picker flow, operation persistence, recovery, and tray/window runtime behavior\n- [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/): deep links, pairing, localhost auth, and trust boundaries\n- [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/): how local-drive operations and SMB-backed native-app editing differ in practice\n\n## Validation Expectations\n\nWhen companion behavior changes, start with:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nThen add frontend or backend checks if the companion change alters a shared workflow contract.\n", "0.8": "+++\ntitle = \"Companion Overview\"\n+++\n\nSambee Companion is a lightweight desktop application built with Tauri v2, a Preact UI, and a Rust backend.\n\nIt exists for two major reasons:\n\n- to enable native-app editing of files that originate in Sambee workflows\n- to provide a paired localhost API for local-drive access and browser-to-desktop integrations\n\n## The Two Main Capability Paths\n\n### Deep-Link Native-App Editing\n\nFor SMB-backed edit workflows:\n\n1. The browser starts the action.\n2. The OS launches or activates the companion through a `sambee://` deep link.\n3. The companion exchanges tokens, downloads the file, acquires an edit lock, and opens the file in a native app.\n4. The companion later uploads the result and releases the lock.\n\n### Paired Localhost API\n\nFor local-drive access and related desktop-side capabilities:\n\n1. The browser detects the companion on `127.0.0.1:21549`.\n2. Browser and companion perform an explicit pairing flow.\n3. The browser uses the authenticated localhost API to enumerate drives and perform local file operations.\n4. WebSocket notifications keep the browser updated when local directories change.\n\nFor the full desktop-side data path, continue to [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\nFor the deep-link runtime, native-app edit lifecycle, and operation recovery model, continue to [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/).\n\n## Why This Is a Separate App\n\nThe companion handles behavior the browser cannot safely or reliably do by itself.\n\n- launching installed native apps\n- accessing local drives on the user's computer\n- holding desktop-side state and recovery information\n- participating in OS-level integration such as deep-link registration and tray behavior\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/` | Preact UI, preferences, pairing windows, and desktop-facing interaction surfaces |\n| `companion/src-tauri/src/` | Rust backend for deep links, local API, file operations, logging, and integration with the OS |\n| `companion/src-tauri/src/server/` | localhost pairing, auth, drive enumeration, handlers, and watcher behavior |\n| `companion/src-tauri/src/commands/` | command handlers for file opening, upload, pairing, update, and related actions |\n\n## Trust and Safety Boundaries\n\nThe companion adds power, so it also adds security-sensitive behavior.\n\n- deep-link flows depend on short-lived tokens and server-side lock behavior\n- localhost API access is intentionally paired and authenticated\n- the app is single-instance so later deep links are routed to the running process\n- desktop-local behavior should not silently bypass the browser or backend contracts it depends on\n\n## What Usually Breaks When This Layer Changes\n\n- native-app editing lifecycle behavior\n- lock release or upload expectations after editing\n- browser pairing and local-drive discovery\n- localization sync or other browser-to-desktop coordination\n- platform-specific startup, packaging, or tray behavior\n\n## Go Deeper\n\n- [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/): deep-link ingress, app picker flow, operation persistence, recovery, and tray/window runtime behavior\n- [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/): deep links, pairing, localhost auth, and trust boundaries\n- [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/): how local-drive operations and SMB-backed native-app editing differ in practice\n\n## Validation Expectations\n\nWhen companion behavior changes, start with:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nThen add frontend or backend checks if the companion change alters a shared workflow contract.\n", "0.9": "+++\ntitle = \"Companion Overview\"\n+++\n\nSambee Companion is a lightweight desktop application built with Tauri v2, a Preact UI, and a Rust backend.\n\nIt exists for two major reasons:\n\n- to enable native-app editing of files that originate in Sambee workflows\n- to provide a paired localhost API for local-drive access and browser-to-desktop integrations\n\n## The Two Main Capability Paths\n\n### Deep-Link Native-App Editing\n\nFor SMB-backed edit workflows:\n\n1. The browser starts the action.\n2. The OS launches or activates the companion through a `sambee://` deep link.\n3. The companion exchanges tokens, downloads the file, acquires an edit lock, and opens the file in a native app.\n4. The companion later uploads the result and releases the lock.\n\n### Paired Localhost API\n\nFor local-drive access and related desktop-side capabilities:\n\n1. The browser detects the companion on `127.0.0.1:21549`.\n2. Browser and companion perform an explicit pairing flow.\n3. The browser uses the authenticated localhost API to enumerate drives and perform local file operations.\n4. WebSocket notifications keep the browser updated when local directories change.\n\nFor the full desktop-side data path, continue to [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\nFor the deep-link runtime, native-app edit lifecycle, and operation recovery model, continue to [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/).\n\n## Why This Is a Separate App\n\nThe companion handles behavior the browser cannot safely or reliably do by itself.\n\n- launching installed native apps\n- accessing local drives on the user's computer\n- holding desktop-side state and recovery information\n- participating in OS-level integration such as deep-link registration and tray behavior\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/` | Preact UI, preferences, pairing windows, and desktop-facing interaction surfaces |\n| `companion/src-tauri/src/` | Rust backend for deep links, local API, file operations, logging, and integration with the OS |\n| `companion/src-tauri/src/server/` | localhost pairing, auth, drive enumeration, handlers, and watcher behavior |\n| `companion/src-tauri/src/commands/` | command handlers for file opening, upload, pairing, update, and related actions |\n\n## Trust and Safety Boundaries\n\nThe companion adds power, so it also adds security-sensitive behavior.\n\n- deep-link flows depend on short-lived tokens and server-side lock behavior\n- localhost API access is intentionally paired and authenticated\n- the app is single-instance so later deep links are routed to the running process\n- desktop-local behavior should not silently bypass the browser or backend contracts it depends on\n\n## What Usually Breaks When This Layer Changes\n\n- native-app editing lifecycle behavior\n- lock release or upload expectations after editing\n- browser pairing and local-drive discovery\n- localization sync or other browser-to-desktop coordination\n- platform-specific startup, packaging, or tray behavior\n\n## Go Deeper\n\n- [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/): deep-link ingress, app picker flow, operation persistence, recovery, and tray/window runtime behavior\n- [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/): deep links, pairing, localhost auth, and trust boundaries\n- [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/): how local-drive operations and SMB-backed native-app editing differ in practice\n\n## Validation Expectations\n\nWhen companion behavior changes, start with:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nThen add frontend or backend checks if the companion change alters a shared workflow contract.\n", "1.0": "+++\ntitle = \"Companion Overview\"\n+++\n\nSambee Companion is a lightweight desktop application built with Tauri v2, a Preact UI, and a Rust backend.\n\nIt exists for two major reasons:\n\n- to enable native-app editing of files that originate in Sambee workflows\n- to provide a paired localhost API for local-drive access and browser-to-desktop integrations\n\n## The Two Main Capability Paths\n\n### Deep-Link Native-App Editing\n\nFor SMB-backed edit workflows:\n\n1. The browser starts the action.\n2. The OS launches or activates the companion through a `sambee://` deep link.\n3. The companion exchanges tokens, downloads the file, acquires an edit lock, and opens the file in a native app.\n4. The companion later uploads the result and releases the lock.\n\n### Paired Localhost API\n\nFor local-drive access and related desktop-side capabilities:\n\n1. The browser detects the companion on `127.0.0.1:21549`.\n2. Browser and companion perform an explicit pairing flow.\n3. The browser uses the authenticated localhost API to enumerate drives and perform local file operations.\n4. WebSocket notifications keep the browser updated when local directories change.\n\nFor the full desktop-side data path, continue to [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\nFor the deep-link runtime, native-app edit lifecycle, and operation recovery model, continue to [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/).\n\n## Why This Is a Separate App\n\nThe companion handles behavior the browser cannot safely or reliably do by itself.\n\n- launching installed native apps\n- accessing local drives on the user's computer\n- holding desktop-side state and recovery information\n- participating in OS-level integration such as deep-link registration and tray behavior\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/` | Preact UI, preferences, pairing windows, and desktop-facing interaction surfaces |\n| `companion/src-tauri/src/` | Rust backend for deep links, local API, file operations, logging, and integration with the OS |\n| `companion/src-tauri/src/server/` | localhost pairing, auth, drive enumeration, handlers, and watcher behavior |\n| `companion/src-tauri/src/commands/` | command handlers for file opening, upload, pairing, update, and related actions |\n\n## Trust and Safety Boundaries\n\nThe companion adds power, so it also adds security-sensitive behavior.\n\n- deep-link flows depend on short-lived tokens and server-side lock behavior\n- localhost API access is intentionally paired and authenticated\n- the app is single-instance so later deep links are routed to the running process\n- desktop-local behavior should not silently bypass the browser or backend contracts it depends on\n\n## What Usually Breaks When This Layer Changes\n\n- native-app editing lifecycle behavior\n- lock release or upload expectations after editing\n- browser pairing and local-drive discovery\n- localization sync or other browser-to-desktop coordination\n- platform-specific startup, packaging, or tray behavior\n\n## Go Deeper\n\n- [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/): deep-link ingress, app picker flow, operation persistence, recovery, and tray/window runtime behavior\n- [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/): deep links, pairing, localhost auth, and trust boundaries\n- [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/): how local-drive operations and SMB-backed native-app editing differ in practice\n\n## Validation Expectations\n\nWhen companion behavior changes, start with:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nThen add frontend or backend checks if the companion change alters a shared workflow contract.\n", "2.0": "+++\ntitle = \"Companion Overview\"\n+++\n\nSambee Companion is a lightweight desktop application built with Tauri v2, a Preact UI, and a Rust backend.\n\nIt exists for two major reasons:\n\n- to enable native-app editing of files that originate in Sambee workflows\n- to provide a paired localhost API for local-drive access and browser-to-desktop integrations\n\n## The Two Main Capability Paths\n\n### Deep-Link Native-App Editing\n\nFor SMB-backed edit workflows:\n\n1. The browser starts the action.\n2. The OS launches or activates the companion through a `sambee://` deep link.\n3. The companion exchanges tokens, downloads the file, acquires an edit lock, and opens the file in a native app.\n4. The companion later uploads the result and releases the lock.\n\n### Paired Localhost API\n\nFor local-drive access and related desktop-side capabilities:\n\n1. The browser detects the companion on `127.0.0.1:21549`.\n2. Browser and companion perform an explicit pairing flow.\n3. The browser uses the authenticated localhost API to enumerate drives and perform local file operations.\n4. WebSocket notifications keep the browser updated when local directories change.\n\nFor the full desktop-side data path, continue to [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\nFor the deep-link runtime, native-app edit lifecycle, and operation recovery model, continue to [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/).\n\n## Why This Is a Separate App\n\nThe companion handles behavior the browser cannot safely or reliably do by itself.\n\n- launching installed native apps\n- accessing local drives on the user's computer\n- holding desktop-side state and recovery information\n- participating in OS-level integration such as deep-link registration and tray behavior\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/` | Preact UI, preferences, pairing windows, and desktop-facing interaction surfaces |\n| `companion/src-tauri/src/` | Rust backend for deep links, local API, file operations, logging, and integration with the OS |\n| `companion/src-tauri/src/server/` | localhost pairing, auth, drive enumeration, handlers, and watcher behavior |\n| `companion/src-tauri/src/commands/` | command handlers for file opening, upload, pairing, update, and related actions |\n\n## Trust and Safety Boundaries\n\nThe companion adds power, so it also adds security-sensitive behavior.\n\n- deep-link flows depend on short-lived tokens and server-side lock behavior\n- localhost API access is intentionally paired and authenticated\n- the app is single-instance so later deep links are routed to the running process\n- desktop-local behavior should not silently bypass the browser or backend contracts it depends on\n\n## What Usually Breaks When This Layer Changes\n\n- native-app editing lifecycle behavior\n- lock release or upload expectations after editing\n- browser pairing and local-drive discovery\n- localization sync or other browser-to-desktop coordination\n- platform-specific startup, packaging, or tray behavior\n\n## Go Deeper\n\n- [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/): deep-link ingress, app picker flow, operation persistence, recovery, and tray/window runtime behavior\n- [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/): deep links, pairing, localhost auth, and trust boundaries\n- [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/): how local-drive operations and SMB-backed native-app editing differ in practice\n\n## Validation Expectations\n\nWhen companion behavior changes, start with:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nThen add frontend or backend checks if the companion change alters a shared workflow contract.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/companion-architecture/companion-runtime-and-native-app-editing", "parent_id": "section:developer-guide/companion-architecture", "depth": 2, "kind": "page", "label": "companion-runtime-and-native-app-editing", "title": "Companion Runtime And Native App Editing", "path": "developer-guide/companion-architecture/companion-runtime-and-native-app-editing", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Companion Runtime and Native-App Editing\"\n+++\n\nThis page covers the companion runtime that sits between the browser's deep-link request and the desktop user's native editing session.\n\nUse it when a change affects:\n\n- deep-link handling and single-instance behavior\n- app selection and native-app launching\n- operation persistence, recovery, and temp-file lifecycle\n- tray, app-picker, large-file, and \"Done Editing\" window behavior\n\nFor localhost pairing and local-drive behavior, continue to [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) and [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\n## Runtime Modes and UI Surfaces\n\nThe companion is not a traditional always-visible desktop app.\n\nIn normal use it shifts between a few runtime modes:\n\n- tray-oriented background state when no editing dialog is open\n- a reused main window for app picker, preferences, large-file confirmation, and recovery dialogs\n- a dedicated pairing window for browser-to-companion approval\n- one \"Done Editing\" window per active native-app edit session\n\nThat split is deliberate. The companion should stay lightweight when idle, but it still needs focused UI surfaces for edit coordination and pairing approval.\n\nBecause the companion is a tray-oriented app, closing the last transient webview must not implicitly terminate the process. The runtime intentionally prevents last-window destruction from exiting the app; explicit quit requests from the tray still exit normally.\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/App.tsx` | frontend view routing for idle, app picker, preferences, recovery, and large-file flows |\n| `companion/src/components/` | desktop-facing UI surfaces such as `AppPicker`, `DoneEditingWindow`, `RecoveryDialog`, and `Preferences` |\n| `companion/src/stores/` | persisted frontend preferences for app selection and companion settings |\n| `companion/src-tauri/src/lib.rs` | Tauri setup, plugin wiring, deep-link handling, window management, tray behavior, and lifecycle orchestration |\n| `companion/src-tauri/src/commands/` | commands for file info, download, upload, app selection, pairing, localization, and updates |\n| `companion/src-tauri/src/http_client.rs` | shared backend HTTP clients, reverse-proxy cookie jars, request diagnostics, and URL sanitization |\n| `companion/src-tauri/src/app_registry/` | platform-specific native-app discovery and launch integration |\n| `companion/src-tauri/src/sync/` | operation persistence, temp-file handling, recycle retention, and recovery helpers |\n| `companion/src-tauri/src/token/` and `uri/` | URI parsing and bootstrap-token exchange for deep-link editing |\n\n## Deep-Link Ingress\n\nNative-app editing starts from a `sambee://open?...` URI.\n\nThe runtime pieces involved are:\n\n- `tauri-plugin-deep-link` for receiving the URI\n- `tauri-plugin-single-instance` so later URIs are forwarded to the running instance instead of launching competing copies\n- `uri/mod.rs` for parsing required parameters such as `server`, `token`, `connId`, and `path`\n- `token/mod.rs` for exchanging the short-lived URI token for a companion bootstrap token\n\nThe deep link can also carry theme data so the companion UI matches the browser-side theme during the editing flow.\n\n## Reverse-Proxy Authentication Path\n\nNative editing supports reverse proxies and SSO layers that require interactive browser authentication before backend API requests are allowed through.\n\nThe implemented flow is:\n\n1. Companion tries the normal URI-token exchange.\n2. If token exchange is intercepted by a login redirect or HTML sign-in page, the companion opens a dedicated `Sambee Authentication` webview.\n3. The user signs in through that embedded webview.\n4. Companion reads backend-origin cookies from that same webview and seeds its shared Rust `reqwest` cookie jar.\n5. Token exchange and the rest of the native-edit lifecycle reuse that authenticated client state.\n\nThe HTTP client store is keyed by normalized server URL. For each server, it keeps a stable cookie jar plus default and no-redirect clients. The no-redirect client is used where redirect responses are diagnostic signals, such as URI-token exchange. The default client is reused for file-info lookup, lock acquisition, download, upload, lock release, and heartbeat requests.\n\nThis matters for the trust model:\n\n- Browser-to-companion localhost pairing remains separate from reverse-proxy authentication.\n- The Sambee bearer token remains separate from reverse-proxy cookies.\n- External browser cookies are not read or imported.\n- Reverse-proxy cookies stay inside the companion-owned webview and Rust HTTP client state.\n- Cookie values must not be logged.\n\nCompanion automatically retries idempotent backend calls such as file-info lookup, lock acquisition, download, lock release, and heartbeats after reauthentication. Non-idempotent uploads are not replayed automatically; the runtime instead asks the user to retry the action after authentication has been refreshed.\n\nFor reverse-proxy auth robustness, the shared Companion HTTP clients stay on HTTP/1.1 rather than enabling HTTP/2.\n\nRequest failures are logged with classified diagnostics such as timeout, connect, request, body, decode, and status. URLs and chained source errors are sanitized before logging so deep-link tokens, proxy sessions, and other sensitive query values do not appear in logs.\n\n## Native-App Edit Lifecycle\n\nThe implemented lifecycle in `lib.rs` is intentionally explicit.\n\nAt a high level it is:\n\n1. parse the deep link\n2. exchange the URI token for a companion bootstrap token\n3. fetch file metadata for file-size checks and conflict baseline\n4. optionally pause for a large-file confirmation dialog\n5. acquire the backend edit lock and receive operation-scoped lock context\n6. download the file into the companion temp area\n7. create a `FileOperation`, persist its sidecar, and add it to the in-memory store\n8. show the app picker and wait for user selection\n9. open the local file in the selected native application\n10. spawn a dedicated \"Done Editing\" window\n11. start background renewal, heartbeat, and file-status polling\n\nTwo rules matter here:\n\n- the backend lock is acquired before the edit session is allowed to proceed\n- the companion records local operation state before handing control to the native app\n\nThose decisions are what make recovery and conflict handling possible after crashes or interrupted sessions.\n\n## App Selection and Native Launching\n\nThe companion keeps platform-specific native-app discovery behind `app_registry/`.\n\nThat layer is responsible for:\n\n- listing handlers for a file extension\n- surfacing the default app first when possible\n- returning enough information for the UI to distinguish executable paths and handler identifiers\n- launching the chosen app or falling back to system-default open behavior when appropriate\n\nThe app picker flow is coordinated through Tauri events.\n\n- the Rust runtime emits `show-app-picker`\n- the frontend displays `AppPicker`\n- the user response is sent back through `respond_app_selection`\n\nStored per-extension app preferences live in `appPreferences.ts`, which is how repeated opens can bypass unnecessary picker friction.\n\nOn Windows, the launch path is more subtle than a simple `CreateProcess` call because packaged handlers and opaque shell associations may need Windows shell invocation rather than direct executable launching.\n\n## Operation Model, Temp Files, and Recovery\n\nDeep-link editing is tracked through `FileOperation` in `sync/operations.rs`.\n\nEach operation records:\n\n- server URL, connection, and remote path\n- local temp-file path\n- current status\n- original modification time\n- chosen app name\n- operation-scoped lock context and server-side last-modified baseline\n\nThe companion keeps this state in two places:\n\n- an in-memory `OperationStore` for active runtime coordination\n- a sidecar on disk so the session can be recovered after a restart or crash\n\nThat persistence model supports the recovery flow shown through `RecoveryDialog` when leftover operations are discovered at startup.\n\nThe temp-file lifecycle is also intentionally not just \"download and delete\":\n\n- active sessions live in a managed temp area\n- completed or discarded files move through recycle and retention logic\n- retention duration is user-configurable through preferences\n\n## \"Done Editing\" and Explicit Save-Back\n\nThe companion does not try to infer when a user is \"probably done\" in their native editor.\n\nInstead it keeps a dedicated \"Done Editing\" window open while:\n\n- file status polling checks whether the local temp file changed\n- renewal and heartbeat requests keep the edit session and backend lock alive\n\nWhen the user explicitly finishes or discards the session, the companion can:\n\n- upload the modified file\n- release the backend lock\n- recycle the temp copy\n- update the tray and operation state\n\nThat explicit-confirmation model is one of the core product decisions behind native-app editing, not a UI accident.\n\n## Conflict and Recovery Handling\n\nThe companion keeps enough state to detect overwrite-sensitive conflicts.\n\nBefore completing an upload-sensitive flow, it compares the current server-side state with the baseline captured earlier in the edit session. If those diverge, the conflict dialog path is used instead of silently overwriting the server copy.\n\nThis is also why recovery state is more than a cosmetic convenience feature. It protects the editing workflow from leaving users with stranded temp files and unclear lock state after interruption.\n\n## Preferences, Pairing UI, and Update Checks\n\nThe reused main window also hosts companion preferences.\n\nCurrent public settings include:\n\n- upload conflict behavior\n- auto-start at sign-in\n- desktop notifications\n- update channel selection\n- temp-file retention period\n- paired-origin management\n\nThe update path itself is channel-aware and lives in `commands/update.rs`, but detailed release-feed and packaging workflow belongs with companion distribution and update documentation rather than this runtime page.\n\nThe pairing window is a separate UI surface because browser-to-companion approval is part of the trust boundary, not just another generic settings dialog.\n\n## What Usually Breaks When This Layer Changes\n\n- deep links reach the app, but the running instance does not receive forwarded URIs correctly\n- lock acquisition or release gets out of sync with the visible edit lifecycle\n- picker cancellation or launch failure leaves behind stale temp files or sidecars\n- operation recovery loses enough metadata that interrupted edits become hard to resolve safely\n- tray and window state drift apart from the actual set of active operations\n\n## Where to Continue\n\n- Use [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) for pairing, localhost auth, deep-link trust boundaries, and origin scoping.\n- Use [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/) for the difference between local-drive access and SMB-backed save-back.\n- Use [Companion Release Overview](../../release-and-versioning/companion-release-overview/) when the change affects packaged releases or updater rollout rather than runtime behavior.\n\n## Validation Expectations\n\nWhen this runtime changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe frontend and backend checks matter whenever the companion change alters a shared workflow contract.\n", "0.8": "+++\ntitle = \"Companion Runtime and Native-App Editing\"\n+++\n\nThis page covers the companion runtime that sits between the browser's deep-link request and the desktop user's native editing session.\n\nUse it when a change affects:\n\n- deep-link handling and single-instance behavior\n- app selection and native-app launching\n- operation persistence, recovery, and temp-file lifecycle\n- tray, app-picker, large-file, and \"Done Editing\" window behavior\n\nFor localhost pairing and local-drive behavior, continue to [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) and [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\n## Runtime Modes and UI Surfaces\n\nThe companion is not a traditional always-visible desktop app.\n\nIn normal use it shifts between a few runtime modes:\n\n- tray-oriented background state when no editing dialog is open\n- a reused main window for app picker, preferences, large-file confirmation, and recovery dialogs\n- a dedicated pairing window for browser-to-companion approval\n- one \"Done Editing\" window per active native-app edit session\n\nThat split is deliberate. The companion should stay lightweight when idle, but it still needs focused UI surfaces for edit coordination and pairing approval.\n\nBecause the companion is a tray-oriented app, closing the last transient webview must not implicitly terminate the process. The runtime intentionally prevents last-window destruction from exiting the app; explicit quit requests from the tray still exit normally.\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/App.tsx` | frontend view routing for idle, app picker, preferences, recovery, and large-file flows |\n| `companion/src/components/` | desktop-facing UI surfaces such as `AppPicker`, `DoneEditingWindow`, `RecoveryDialog`, and `Preferences` |\n| `companion/src/stores/` | persisted frontend preferences for app selection and companion settings |\n| `companion/src-tauri/src/lib.rs` | Tauri setup, plugin wiring, deep-link handling, window management, tray behavior, and lifecycle orchestration |\n| `companion/src-tauri/src/commands/` | commands for file info, download, upload, app selection, pairing, localization, and updates |\n| `companion/src-tauri/src/http_client.rs` | shared backend HTTP clients, reverse-proxy cookie jars, request diagnostics, and URL sanitization |\n| `companion/src-tauri/src/app_registry/` | platform-specific native-app discovery and launch integration |\n| `companion/src-tauri/src/sync/` | operation persistence, temp-file handling, recycle retention, and recovery helpers |\n| `companion/src-tauri/src/token/` and `uri/` | URI parsing and bootstrap-token exchange for deep-link editing |\n\n## Deep-Link Ingress\n\nNative-app editing starts from a `sambee://open?...` URI.\n\nThe runtime pieces involved are:\n\n- `tauri-plugin-deep-link` for receiving the URI\n- `tauri-plugin-single-instance` so later URIs are forwarded to the running instance instead of launching competing copies\n- `uri/mod.rs` for parsing required parameters such as `server`, `token`, `connId`, and `path`\n- `token/mod.rs` for exchanging the short-lived URI token for a companion bootstrap token\n\nThe deep link can also carry theme data so the companion UI matches the browser-side theme during the editing flow.\n\n## Reverse-Proxy Authentication Path\n\nNative editing supports reverse proxies and SSO layers that require interactive browser authentication before backend API requests are allowed through.\n\nThe implemented flow is:\n\n1. Companion tries the normal URI-token exchange.\n2. If token exchange is intercepted by a login redirect or HTML sign-in page, the companion opens a dedicated `Sambee Authentication` webview.\n3. The user signs in through that embedded webview.\n4. Companion reads backend-origin cookies from that same webview and seeds its shared Rust `reqwest` cookie jar.\n5. Token exchange and the rest of the native-edit lifecycle reuse that authenticated client state.\n\nThe HTTP client store is keyed by normalized server URL. For each server, it keeps a stable cookie jar plus default and no-redirect clients. The no-redirect client is used where redirect responses are diagnostic signals, such as URI-token exchange. The default client is reused for file-info lookup, lock acquisition, download, upload, lock release, and heartbeat requests.\n\nThis matters for the trust model:\n\n- Browser-to-companion localhost pairing remains separate from reverse-proxy authentication.\n- The Sambee bearer token remains separate from reverse-proxy cookies.\n- External browser cookies are not read or imported.\n- Reverse-proxy cookies stay inside the companion-owned webview and Rust HTTP client state.\n- Cookie values must not be logged.\n\nCompanion automatically retries idempotent backend calls such as file-info lookup, lock acquisition, download, lock release, and heartbeats after reauthentication. Non-idempotent uploads are not replayed automatically; the runtime instead asks the user to retry the action after authentication has been refreshed.\n\nFor reverse-proxy auth robustness, the shared Companion HTTP clients stay on HTTP/1.1 rather than enabling HTTP/2.\n\nRequest failures are logged with classified diagnostics such as timeout, connect, request, body, decode, and status. URLs and chained source errors are sanitized before logging so deep-link tokens, proxy sessions, and other sensitive query values do not appear in logs.\n\n## Native-App Edit Lifecycle\n\nThe implemented lifecycle in `lib.rs` is intentionally explicit.\n\nAt a high level it is:\n\n1. parse the deep link\n2. exchange the URI token for a companion bootstrap token\n3. fetch file metadata for file-size checks and conflict baseline\n4. optionally pause for a large-file confirmation dialog\n5. acquire the backend edit lock and receive operation-scoped lock context\n6. download the file into the companion temp area\n7. create a `FileOperation`, persist its sidecar, and add it to the in-memory store\n8. show the app picker and wait for user selection\n9. open the local file in the selected native application\n10. spawn a dedicated \"Done Editing\" window\n11. start background renewal, heartbeat, and file-status polling\n\nTwo rules matter here:\n\n- the backend lock is acquired before the edit session is allowed to proceed\n- the companion records local operation state before handing control to the native app\n\nThose decisions are what make recovery and conflict handling possible after crashes or interrupted sessions.\n\n## App Selection and Native Launching\n\nThe companion keeps platform-specific native-app discovery behind `app_registry/`.\n\nThat layer is responsible for:\n\n- listing handlers for a file extension\n- surfacing the default app first when possible\n- returning enough information for the UI to distinguish executable paths and handler identifiers\n- launching the chosen app or falling back to system-default open behavior when appropriate\n\nThe app picker flow is coordinated through Tauri events.\n\n- the Rust runtime emits `show-app-picker`\n- the frontend displays `AppPicker`\n- the user response is sent back through `respond_app_selection`\n\nStored per-extension app preferences live in `appPreferences.ts`, which is how repeated opens can bypass unnecessary picker friction.\n\nOn Windows, the launch path is more subtle than a simple `CreateProcess` call because packaged handlers and opaque shell associations may need Windows shell invocation rather than direct executable launching.\n\n## Operation Model, Temp Files, and Recovery\n\nDeep-link editing is tracked through `FileOperation` in `sync/operations.rs`.\n\nEach operation records:\n\n- server URL, connection, and remote path\n- local temp-file path\n- current status\n- original modification time\n- chosen app name\n- operation-scoped lock context and server-side last-modified baseline\n\nThe companion keeps this state in two places:\n\n- an in-memory `OperationStore` for active runtime coordination\n- a sidecar on disk so the session can be recovered after a restart or crash\n\nThat persistence model supports the recovery flow shown through `RecoveryDialog` when leftover operations are discovered at startup.\n\nThe temp-file lifecycle is also intentionally not just \"download and delete\":\n\n- active sessions live in a managed temp area\n- completed or discarded files move through recycle and retention logic\n- retention duration is user-configurable through preferences\n\n## \"Done Editing\" and Explicit Save-Back\n\nThe companion does not try to infer when a user is \"probably done\" in their native editor.\n\nInstead it keeps a dedicated \"Done Editing\" window open while:\n\n- file status polling checks whether the local temp file changed\n- renewal and heartbeat requests keep the edit session and backend lock alive\n\nWhen the user explicitly finishes or discards the session, the companion can:\n\n- upload the modified file\n- release the backend lock\n- recycle the temp copy\n- update the tray and operation state\n\nThat explicit-confirmation model is one of the core product decisions behind native-app editing, not a UI accident.\n\n## Conflict and Recovery Handling\n\nThe companion keeps enough state to detect overwrite-sensitive conflicts.\n\nBefore completing an upload-sensitive flow, it compares the current server-side state with the baseline captured earlier in the edit session. If those diverge, the conflict dialog path is used instead of silently overwriting the server copy.\n\nThis is also why recovery state is more than a cosmetic convenience feature. It protects the editing workflow from leaving users with stranded temp files and unclear lock state after interruption.\n\n## Preferences, Pairing UI, and Update Checks\n\nThe reused main window also hosts companion preferences.\n\nCurrent public settings include:\n\n- upload conflict behavior\n- auto-start at sign-in\n- desktop notifications\n- update channel selection\n- temp-file retention period\n- paired-origin management\n\nThe update path itself is channel-aware and lives in `commands/update.rs`, but detailed release-feed and packaging workflow belongs with companion distribution and update documentation rather than this runtime page.\n\nThe pairing window is a separate UI surface because browser-to-companion approval is part of the trust boundary, not just another generic settings dialog.\n\n## What Usually Breaks When This Layer Changes\n\n- deep links reach the app, but the running instance does not receive forwarded URIs correctly\n- lock acquisition or release gets out of sync with the visible edit lifecycle\n- picker cancellation or launch failure leaves behind stale temp files or sidecars\n- operation recovery loses enough metadata that interrupted edits become hard to resolve safely\n- tray and window state drift apart from the actual set of active operations\n\n## Where to Continue\n\n- Use [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) for pairing, localhost auth, deep-link trust boundaries, and origin scoping.\n- Use [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/) for the difference between local-drive access and SMB-backed save-back.\n- Use [Companion Release Overview](../../release-and-versioning/companion-release-overview/) when the change affects packaged releases or updater rollout rather than runtime behavior.\n\n## Validation Expectations\n\nWhen this runtime changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe frontend and backend checks matter whenever the companion change alters a shared workflow contract.\n", "0.9": "+++\ntitle = \"Companion Runtime and Native-App Editing\"\n+++\n\nThis page covers the companion runtime that sits between the browser's deep-link request and the desktop user's native editing session.\n\nUse it when a change affects:\n\n- deep-link handling and single-instance behavior\n- app selection and native-app launching\n- operation persistence, recovery, and temp-file lifecycle\n- tray, app-picker, large-file, and \"Done Editing\" window behavior\n\nFor localhost pairing and local-drive behavior, continue to [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) and [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\n## Runtime Modes and UI Surfaces\n\nThe companion is not a traditional always-visible desktop app.\n\nIn normal use it shifts between a few runtime modes:\n\n- tray-oriented background state when no editing dialog is open\n- a reused main window for app picker, preferences, large-file confirmation, and recovery dialogs\n- a dedicated pairing window for browser-to-companion approval\n- one \"Done Editing\" window per active native-app edit session\n\nThat split is deliberate. The companion should stay lightweight when idle, but it still needs focused UI surfaces for edit coordination and pairing approval.\n\nBecause the companion is a tray-oriented app, closing the last transient webview must not implicitly terminate the process. The runtime intentionally prevents last-window destruction from exiting the app; explicit quit requests from the tray still exit normally.\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/App.tsx` | frontend view routing for idle, app picker, preferences, recovery, and large-file flows |\n| `companion/src/components/` | desktop-facing UI surfaces such as `AppPicker`, `DoneEditingWindow`, `RecoveryDialog`, and `Preferences` |\n| `companion/src/stores/` | persisted frontend preferences for app selection and companion settings |\n| `companion/src-tauri/src/lib.rs` | Tauri setup, plugin wiring, deep-link handling, window management, tray behavior, and lifecycle orchestration |\n| `companion/src-tauri/src/commands/` | commands for file info, download, upload, app selection, pairing, localization, and updates |\n| `companion/src-tauri/src/http_client.rs` | shared backend HTTP clients, reverse-proxy cookie jars, request diagnostics, and URL sanitization |\n| `companion/src-tauri/src/app_registry/` | platform-specific native-app discovery and launch integration |\n| `companion/src-tauri/src/sync/` | operation persistence, temp-file handling, recycle retention, and recovery helpers |\n| `companion/src-tauri/src/token/` and `uri/` | URI parsing and bootstrap-token exchange for deep-link editing |\n\n## Deep-Link Ingress\n\nNative-app editing starts from a `sambee://open?...` URI.\n\nThe runtime pieces involved are:\n\n- `tauri-plugin-deep-link` for receiving the URI\n- `tauri-plugin-single-instance` so later URIs are forwarded to the running instance instead of launching competing copies\n- `uri/mod.rs` for parsing required parameters such as `server`, `token`, `connId`, and `path`\n- `token/mod.rs` for exchanging the short-lived URI token for a companion bootstrap token\n\nThe deep link can also carry theme data so the companion UI matches the browser-side theme during the editing flow.\n\n## Reverse-Proxy Authentication Path\n\nNative editing supports reverse proxies and SSO layers that require interactive browser authentication before backend API requests are allowed through.\n\nThe implemented flow is:\n\n1. Companion tries the normal URI-token exchange.\n2. If token exchange is intercepted by a login redirect or HTML sign-in page, the companion opens a dedicated `Sambee Authentication` webview.\n3. The user signs in through that embedded webview.\n4. Companion reads backend-origin cookies from that same webview and seeds its shared Rust `reqwest` cookie jar.\n5. Token exchange and the rest of the native-edit lifecycle reuse that authenticated client state.\n\nThe HTTP client store is keyed by normalized server URL. For each server, it keeps a stable cookie jar plus default and no-redirect clients. The no-redirect client is used where redirect responses are diagnostic signals, such as URI-token exchange. The default client is reused for file-info lookup, lock acquisition, download, upload, lock release, and heartbeat requests.\n\nThis matters for the trust model:\n\n- Browser-to-companion localhost pairing remains separate from reverse-proxy authentication.\n- The Sambee bearer token remains separate from reverse-proxy cookies.\n- External browser cookies are not read or imported.\n- Reverse-proxy cookies stay inside the companion-owned webview and Rust HTTP client state.\n- Cookie values must not be logged.\n\nCompanion automatically retries idempotent backend calls such as file-info lookup, lock acquisition, download, lock release, and heartbeats after reauthentication. Non-idempotent uploads are not replayed automatically; the runtime instead asks the user to retry the action after authentication has been refreshed.\n\nFor reverse-proxy auth robustness, the shared Companion HTTP clients stay on HTTP/1.1 rather than enabling HTTP/2.\n\nRequest failures are logged with classified diagnostics such as timeout, connect, request, body, decode, and status. URLs and chained source errors are sanitized before logging so deep-link tokens, proxy sessions, and other sensitive query values do not appear in logs.\n\n## Native-App Edit Lifecycle\n\nThe implemented lifecycle in `lib.rs` is intentionally explicit.\n\nAt a high level it is:\n\n1. parse the deep link\n2. exchange the URI token for a companion bootstrap token\n3. fetch file metadata for file-size checks and conflict baseline\n4. optionally pause for a large-file confirmation dialog\n5. acquire the backend edit lock and receive operation-scoped lock context\n6. download the file into the companion temp area\n7. create a `FileOperation`, persist its sidecar, and add it to the in-memory store\n8. show the app picker and wait for user selection\n9. open the local file in the selected native application\n10. spawn a dedicated \"Done Editing\" window\n11. start background renewal, heartbeat, and file-status polling\n\nTwo rules matter here:\n\n- the backend lock is acquired before the edit session is allowed to proceed\n- the companion records local operation state before handing control to the native app\n\nThose decisions are what make recovery and conflict handling possible after crashes or interrupted sessions.\n\n## App Selection and Native Launching\n\nThe companion keeps platform-specific native-app discovery behind `app_registry/`.\n\nThat layer is responsible for:\n\n- listing handlers for a file extension\n- surfacing the default app first when possible\n- returning enough information for the UI to distinguish executable paths and handler identifiers\n- launching the chosen app or falling back to system-default open behavior when appropriate\n\nThe app picker flow is coordinated through Tauri events.\n\n- the Rust runtime emits `show-app-picker`\n- the frontend displays `AppPicker`\n- the user response is sent back through `respond_app_selection`\n\nStored per-extension app preferences live in `appPreferences.ts`, which is how repeated opens can bypass unnecessary picker friction.\n\nOn Windows, the launch path is more subtle than a simple `CreateProcess` call because packaged handlers and opaque shell associations may need Windows shell invocation rather than direct executable launching.\n\n## Operation Model, Temp Files, and Recovery\n\nDeep-link editing is tracked through `FileOperation` in `sync/operations.rs`.\n\nEach operation records:\n\n- server URL, connection, and remote path\n- local temp-file path\n- current status\n- original modification time\n- chosen app name\n- operation-scoped lock context and server-side last-modified baseline\n\nThe companion keeps this state in two places:\n\n- an in-memory `OperationStore` for active runtime coordination\n- a sidecar on disk so the session can be recovered after a restart or crash\n\nThat persistence model supports the recovery flow shown through `RecoveryDialog` when leftover operations are discovered at startup.\n\nThe temp-file lifecycle is also intentionally not just \"download and delete\":\n\n- active sessions live in a managed temp area\n- completed or discarded files move through recycle and retention logic\n- retention duration is user-configurable through preferences\n\n## \"Done Editing\" and Explicit Save-Back\n\nThe companion does not try to infer when a user is \"probably done\" in their native editor.\n\nInstead it keeps a dedicated \"Done Editing\" window open while:\n\n- file status polling checks whether the local temp file changed\n- renewal and heartbeat requests keep the edit session and backend lock alive\n\nWhen the user explicitly finishes or discards the session, the companion can:\n\n- upload the modified file\n- release the backend lock\n- recycle the temp copy\n- update the tray and operation state\n\nThat explicit-confirmation model is one of the core product decisions behind native-app editing, not a UI accident.\n\n## Conflict and Recovery Handling\n\nThe companion keeps enough state to detect overwrite-sensitive conflicts.\n\nBefore completing an upload-sensitive flow, it compares the current server-side state with the baseline captured earlier in the edit session. If those diverge, the conflict dialog path is used instead of silently overwriting the server copy.\n\nThis is also why recovery state is more than a cosmetic convenience feature. It protects the editing workflow from leaving users with stranded temp files and unclear lock state after interruption.\n\n## Preferences, Pairing UI, and Update Checks\n\nThe reused main window also hosts companion preferences.\n\nCurrent public settings include:\n\n- upload conflict behavior\n- auto-start at sign-in\n- desktop notifications\n- update channel selection\n- temp-file retention period\n- paired-origin management\n\nThe update path itself is channel-aware and lives in `commands/update.rs`, but detailed release-feed and packaging workflow belongs with companion distribution and update documentation rather than this runtime page.\n\nThe pairing window is a separate UI surface because browser-to-companion approval is part of the trust boundary, not just another generic settings dialog.\n\n## What Usually Breaks When This Layer Changes\n\n- deep links reach the app, but the running instance does not receive forwarded URIs correctly\n- lock acquisition or release gets out of sync with the visible edit lifecycle\n- picker cancellation or launch failure leaves behind stale temp files or sidecars\n- operation recovery loses enough metadata that interrupted edits become hard to resolve safely\n- tray and window state drift apart from the actual set of active operations\n\n## Where to Continue\n\n- Use [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) for pairing, localhost auth, deep-link trust boundaries, and origin scoping.\n- Use [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/) for the difference between local-drive access and SMB-backed save-back.\n- Use [Companion Release Overview](../../release-and-versioning/companion-release-overview/) when the change affects packaged releases or updater rollout rather than runtime behavior.\n\n## Validation Expectations\n\nWhen this runtime changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe frontend and backend checks matter whenever the companion change alters a shared workflow contract.\n", "1.0": "+++\ntitle = \"Companion Runtime and Native-App Editing\"\n+++\n\nThis page covers the companion runtime that sits between the browser's deep-link request and the desktop user's native editing session.\n\nUse it when a change affects:\n\n- deep-link handling and single-instance behavior\n- app selection and native-app launching\n- operation persistence, recovery, and temp-file lifecycle\n- tray, app-picker, large-file, and \"Done Editing\" window behavior\n\nFor localhost pairing and local-drive behavior, continue to [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) and [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\n## Runtime Modes and UI Surfaces\n\nThe companion is not a traditional always-visible desktop app.\n\nIn normal use it shifts between a few runtime modes:\n\n- tray-oriented background state when no editing dialog is open\n- a reused main window for app picker, preferences, large-file confirmation, and recovery dialogs\n- a dedicated pairing window for browser-to-companion approval\n- one \"Done Editing\" window per active native-app edit session\n\nThat split is deliberate. The companion should stay lightweight when idle, but it still needs focused UI surfaces for edit coordination and pairing approval.\n\nBecause the companion is a tray-oriented app, closing the last transient webview must not implicitly terminate the process. The runtime intentionally prevents last-window destruction from exiting the app; explicit quit requests from the tray still exit normally.\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/App.tsx` | frontend view routing for idle, app picker, preferences, recovery, and large-file flows |\n| `companion/src/components/` | desktop-facing UI surfaces such as `AppPicker`, `DoneEditingWindow`, `RecoveryDialog`, and `Preferences` |\n| `companion/src/stores/` | persisted frontend preferences for app selection and companion settings |\n| `companion/src-tauri/src/lib.rs` | Tauri setup, plugin wiring, deep-link handling, window management, tray behavior, and lifecycle orchestration |\n| `companion/src-tauri/src/commands/` | commands for file info, download, upload, app selection, pairing, localization, and updates |\n| `companion/src-tauri/src/http_client.rs` | shared backend HTTP clients, reverse-proxy cookie jars, request diagnostics, and URL sanitization |\n| `companion/src-tauri/src/app_registry/` | platform-specific native-app discovery and launch integration |\n| `companion/src-tauri/src/sync/` | operation persistence, temp-file handling, recycle retention, and recovery helpers |\n| `companion/src-tauri/src/token/` and `uri/` | URI parsing and bootstrap-token exchange for deep-link editing |\n\n## Deep-Link Ingress\n\nNative-app editing starts from a `sambee://open?...` URI.\n\nThe runtime pieces involved are:\n\n- `tauri-plugin-deep-link` for receiving the URI\n- `tauri-plugin-single-instance` so later URIs are forwarded to the running instance instead of launching competing copies\n- `uri/mod.rs` for parsing required parameters such as `server`, `token`, `connId`, and `path`\n- `token/mod.rs` for exchanging the short-lived URI token for a companion bootstrap token\n\nThe deep link can also carry theme data so the companion UI matches the browser-side theme during the editing flow.\n\n## Reverse-Proxy Authentication Path\n\nNative editing supports reverse proxies and SSO layers that require interactive browser authentication before backend API requests are allowed through.\n\nThe implemented flow is:\n\n1. Companion tries the normal URI-token exchange.\n2. If token exchange is intercepted by a login redirect or HTML sign-in page, the companion opens a dedicated `Sambee Authentication` webview.\n3. The user signs in through that embedded webview.\n4. Companion reads backend-origin cookies from that same webview and seeds its shared Rust `reqwest` cookie jar.\n5. Token exchange and the rest of the native-edit lifecycle reuse that authenticated client state.\n\nThe HTTP client store is keyed by normalized server URL. For each server, it keeps a stable cookie jar plus default and no-redirect clients. The no-redirect client is used where redirect responses are diagnostic signals, such as URI-token exchange. The default client is reused for file-info lookup, lock acquisition, download, upload, lock release, and heartbeat requests.\n\nThis matters for the trust model:\n\n- Browser-to-companion localhost pairing remains separate from reverse-proxy authentication.\n- The Sambee bearer token remains separate from reverse-proxy cookies.\n- External browser cookies are not read or imported.\n- Reverse-proxy cookies stay inside the companion-owned webview and Rust HTTP client state.\n- Cookie values must not be logged.\n\nCompanion automatically retries idempotent backend calls such as file-info lookup, lock acquisition, download, lock release, and heartbeats after reauthentication. Non-idempotent uploads are not replayed automatically; the runtime instead asks the user to retry the action after authentication has been refreshed.\n\nFor reverse-proxy auth robustness, the shared Companion HTTP clients stay on HTTP/1.1 rather than enabling HTTP/2.\n\nRequest failures are logged with classified diagnostics such as timeout, connect, request, body, decode, and status. URLs and chained source errors are sanitized before logging so deep-link tokens, proxy sessions, and other sensitive query values do not appear in logs.\n\n## Native-App Edit Lifecycle\n\nThe implemented lifecycle in `lib.rs` is intentionally explicit.\n\nAt a high level it is:\n\n1. parse the deep link\n2. exchange the URI token for a companion bootstrap token\n3. fetch file metadata for file-size checks and conflict baseline\n4. optionally pause for a large-file confirmation dialog\n5. acquire the backend edit lock and receive operation-scoped lock context\n6. download the file into the companion temp area\n7. create a `FileOperation`, persist its sidecar, and add it to the in-memory store\n8. show the app picker and wait for user selection\n9. open the local file in the selected native application\n10. spawn a dedicated \"Done Editing\" window\n11. start background renewal, heartbeat, and file-status polling\n\nTwo rules matter here:\n\n- the backend lock is acquired before the edit session is allowed to proceed\n- the companion records local operation state before handing control to the native app\n\nThose decisions are what make recovery and conflict handling possible after crashes or interrupted sessions.\n\n## App Selection and Native Launching\n\nThe companion keeps platform-specific native-app discovery behind `app_registry/`.\n\nThat layer is responsible for:\n\n- listing handlers for a file extension\n- surfacing the default app first when possible\n- returning enough information for the UI to distinguish executable paths and handler identifiers\n- launching the chosen app or falling back to system-default open behavior when appropriate\n\nThe app picker flow is coordinated through Tauri events.\n\n- the Rust runtime emits `show-app-picker`\n- the frontend displays `AppPicker`\n- the user response is sent back through `respond_app_selection`\n\nStored per-extension app preferences live in `appPreferences.ts`, which is how repeated opens can bypass unnecessary picker friction.\n\nOn Windows, the launch path is more subtle than a simple `CreateProcess` call because packaged handlers and opaque shell associations may need Windows shell invocation rather than direct executable launching.\n\n## Operation Model, Temp Files, and Recovery\n\nDeep-link editing is tracked through `FileOperation` in `sync/operations.rs`.\n\nEach operation records:\n\n- server URL, connection, and remote path\n- local temp-file path\n- current status\n- original modification time\n- chosen app name\n- operation-scoped lock context and server-side last-modified baseline\n\nThe companion keeps this state in two places:\n\n- an in-memory `OperationStore` for active runtime coordination\n- a sidecar on disk so the session can be recovered after a restart or crash\n\nThat persistence model supports the recovery flow shown through `RecoveryDialog` when leftover operations are discovered at startup.\n\nThe temp-file lifecycle is also intentionally not just \"download and delete\":\n\n- active sessions live in a managed temp area\n- completed or discarded files move through recycle and retention logic\n- retention duration is user-configurable through preferences\n\n## \"Done Editing\" and Explicit Save-Back\n\nThe companion does not try to infer when a user is \"probably done\" in their native editor.\n\nInstead it keeps a dedicated \"Done Editing\" window open while:\n\n- file status polling checks whether the local temp file changed\n- renewal and heartbeat requests keep the edit session and backend lock alive\n\nWhen the user explicitly finishes or discards the session, the companion can:\n\n- upload the modified file\n- release the backend lock\n- recycle the temp copy\n- update the tray and operation state\n\nThat explicit-confirmation model is one of the core product decisions behind native-app editing, not a UI accident.\n\n## Conflict and Recovery Handling\n\nThe companion keeps enough state to detect overwrite-sensitive conflicts.\n\nBefore completing an upload-sensitive flow, it compares the current server-side state with the baseline captured earlier in the edit session. If those diverge, the conflict dialog path is used instead of silently overwriting the server copy.\n\nThis is also why recovery state is more than a cosmetic convenience feature. It protects the editing workflow from leaving users with stranded temp files and unclear lock state after interruption.\n\n## Preferences, Pairing UI, and Update Checks\n\nThe reused main window also hosts companion preferences.\n\nCurrent public settings include:\n\n- upload conflict behavior\n- auto-start at sign-in\n- desktop notifications\n- update channel selection\n- temp-file retention period\n- paired-origin management\n\nThe update path itself is channel-aware and lives in `commands/update.rs`, but detailed release-feed and packaging workflow belongs with companion distribution and update documentation rather than this runtime page.\n\nThe pairing window is a separate UI surface because browser-to-companion approval is part of the trust boundary, not just another generic settings dialog.\n\n## What Usually Breaks When This Layer Changes\n\n- deep links reach the app, but the running instance does not receive forwarded URIs correctly\n- lock acquisition or release gets out of sync with the visible edit lifecycle\n- picker cancellation or launch failure leaves behind stale temp files or sidecars\n- operation recovery loses enough metadata that interrupted edits become hard to resolve safely\n- tray and window state drift apart from the actual set of active operations\n\n## Where to Continue\n\n- Use [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) for pairing, localhost auth, deep-link trust boundaries, and origin scoping.\n- Use [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/) for the difference between local-drive access and SMB-backed save-back.\n- Use [Companion Release Overview](../../release-and-versioning/companion-release-overview/) when the change affects packaged releases or updater rollout rather than runtime behavior.\n\n## Validation Expectations\n\nWhen this runtime changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe frontend and backend checks matter whenever the companion change alters a shared workflow contract.\n", "2.0": "+++\ntitle = \"Companion Runtime and Native-App Editing\"\n+++\n\nThis page covers the companion runtime that sits between the browser's deep-link request and the desktop user's native editing session.\n\nUse it when a change affects:\n\n- deep-link handling and single-instance behavior\n- app selection and native-app launching\n- operation persistence, recovery, and temp-file lifecycle\n- tray, app-picker, large-file, and \"Done Editing\" window behavior\n\nFor localhost pairing and local-drive behavior, continue to [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) and [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\n## Runtime Modes and UI Surfaces\n\nThe companion is not a traditional always-visible desktop app.\n\nIn normal use it shifts between a few runtime modes:\n\n- tray-oriented background state when no editing dialog is open\n- a reused main window for app picker, preferences, large-file confirmation, and recovery dialogs\n- a dedicated pairing window for browser-to-companion approval\n- one \"Done Editing\" window per active native-app edit session\n\nThat split is deliberate. The companion should stay lightweight when idle, but it still needs focused UI surfaces for edit coordination and pairing approval.\n\nBecause the companion is a tray-oriented app, closing the last transient webview must not implicitly terminate the process. The runtime intentionally prevents last-window destruction from exiting the app; explicit quit requests from the tray still exit normally.\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/App.tsx` | frontend view routing for idle, app picker, preferences, recovery, and large-file flows |\n| `companion/src/components/` | desktop-facing UI surfaces such as `AppPicker`, `DoneEditingWindow`, `RecoveryDialog`, and `Preferences` |\n| `companion/src/stores/` | persisted frontend preferences for app selection and companion settings |\n| `companion/src-tauri/src/lib.rs` | Tauri setup, plugin wiring, deep-link handling, window management, tray behavior, and lifecycle orchestration |\n| `companion/src-tauri/src/commands/` | commands for file info, download, upload, app selection, pairing, localization, and updates |\n| `companion/src-tauri/src/http_client.rs` | shared backend HTTP clients, reverse-proxy cookie jars, request diagnostics, and URL sanitization |\n| `companion/src-tauri/src/app_registry/` | platform-specific native-app discovery and launch integration |\n| `companion/src-tauri/src/sync/` | operation persistence, temp-file handling, recycle retention, and recovery helpers |\n| `companion/src-tauri/src/token/` and `uri/` | URI parsing and bootstrap-token exchange for deep-link editing |\n\n## Deep-Link Ingress\n\nNative-app editing starts from a `sambee://open?...` URI.\n\nThe runtime pieces involved are:\n\n- `tauri-plugin-deep-link` for receiving the URI\n- `tauri-plugin-single-instance` so later URIs are forwarded to the running instance instead of launching competing copies\n- `uri/mod.rs` for parsing required parameters such as `server`, `token`, `connId`, and `path`\n- `token/mod.rs` for exchanging the short-lived URI token for a companion bootstrap token\n\nThe deep link can also carry theme data so the companion UI matches the browser-side theme during the editing flow.\n\n## Reverse-Proxy Authentication Path\n\nNative editing supports reverse proxies and SSO layers that require interactive browser authentication before backend API requests are allowed through.\n\nThe implemented flow is:\n\n1. Companion tries the normal URI-token exchange.\n2. If token exchange is intercepted by a login redirect or HTML sign-in page, the companion opens a dedicated `Sambee Authentication` webview.\n3. The user signs in through that embedded webview.\n4. Companion reads backend-origin cookies from that same webview and seeds its shared Rust `reqwest` cookie jar.\n5. Token exchange and the rest of the native-edit lifecycle reuse that authenticated client state.\n\nThe HTTP client store is keyed by normalized server URL. For each server, it keeps a stable cookie jar plus default and no-redirect clients. The no-redirect client is used where redirect responses are diagnostic signals, such as URI-token exchange. The default client is reused for file-info lookup, lock acquisition, download, upload, lock release, and heartbeat requests.\n\nThis matters for the trust model:\n\n- Browser-to-companion localhost pairing remains separate from reverse-proxy authentication.\n- The Sambee bearer token remains separate from reverse-proxy cookies.\n- External browser cookies are not read or imported.\n- Reverse-proxy cookies stay inside the companion-owned webview and Rust HTTP client state.\n- Cookie values must not be logged.\n\nCompanion automatically retries idempotent backend calls such as file-info lookup, lock acquisition, download, lock release, and heartbeats after reauthentication. Non-idempotent uploads are not replayed automatically; the runtime instead asks the user to retry the action after authentication has been refreshed.\n\nFor reverse-proxy auth robustness, the shared Companion HTTP clients stay on HTTP/1.1 rather than enabling HTTP/2.\n\nRequest failures are logged with classified diagnostics such as timeout, connect, request, body, decode, and status. URLs and chained source errors are sanitized before logging so deep-link tokens, proxy sessions, and other sensitive query values do not appear in logs.\n\n## Native-App Edit Lifecycle\n\nThe implemented lifecycle in `lib.rs` is intentionally explicit.\n\nAt a high level it is:\n\n1. parse the deep link\n2. exchange the URI token for a companion bootstrap token\n3. fetch file metadata for file-size checks and conflict baseline\n4. optionally pause for a large-file confirmation dialog\n5. acquire the backend edit lock and receive operation-scoped lock context\n6. download the file into the companion temp area\n7. create a `FileOperation`, persist its sidecar, and add it to the in-memory store\n8. show the app picker and wait for user selection\n9. open the local file in the selected native application\n10. spawn a dedicated \"Done Editing\" window\n11. start background renewal, heartbeat, and file-status polling\n\nTwo rules matter here:\n\n- the backend lock is acquired before the edit session is allowed to proceed\n- the companion records local operation state before handing control to the native app\n\nThose decisions are what make recovery and conflict handling possible after crashes or interrupted sessions.\n\n## App Selection and Native Launching\n\nThe companion keeps platform-specific native-app discovery behind `app_registry/`.\n\nThat layer is responsible for:\n\n- listing handlers for a file extension\n- surfacing the default app first when possible\n- returning enough information for the UI to distinguish executable paths and handler identifiers\n- launching the chosen app or falling back to system-default open behavior when appropriate\n\nThe app picker flow is coordinated through Tauri events.\n\n- the Rust runtime emits `show-app-picker`\n- the frontend displays `AppPicker`\n- the user response is sent back through `respond_app_selection`\n\nStored per-extension app preferences live in `appPreferences.ts`, which is how repeated opens can bypass unnecessary picker friction.\n\nOn Windows, the launch path is more subtle than a simple `CreateProcess` call because packaged handlers and opaque shell associations may need Windows shell invocation rather than direct executable launching.\n\n## Operation Model, Temp Files, and Recovery\n\nDeep-link editing is tracked through `FileOperation` in `sync/operations.rs`.\n\nEach operation records:\n\n- server URL, connection, and remote path\n- local temp-file path\n- current status\n- original modification time\n- chosen app name\n- operation-scoped lock context and server-side last-modified baseline\n\nThe companion keeps this state in two places:\n\n- an in-memory `OperationStore` for active runtime coordination\n- a sidecar on disk so the session can be recovered after a restart or crash\n\nThat persistence model supports the recovery flow shown through `RecoveryDialog` when leftover operations are discovered at startup.\n\nThe temp-file lifecycle is also intentionally not just \"download and delete\":\n\n- active sessions live in a managed temp area\n- completed or discarded files move through recycle and retention logic\n- retention duration is user-configurable through preferences\n\n## \"Done Editing\" and Explicit Save-Back\n\nThe companion does not try to infer when a user is \"probably done\" in their native editor.\n\nInstead it keeps a dedicated \"Done Editing\" window open while:\n\n- file status polling checks whether the local temp file changed\n- renewal and heartbeat requests keep the edit session and backend lock alive\n\nWhen the user explicitly finishes or discards the session, the companion can:\n\n- upload the modified file\n- release the backend lock\n- recycle the temp copy\n- update the tray and operation state\n\nThat explicit-confirmation model is one of the core product decisions behind native-app editing, not a UI accident.\n\n## Conflict and Recovery Handling\n\nThe companion keeps enough state to detect overwrite-sensitive conflicts.\n\nBefore completing an upload-sensitive flow, it compares the current server-side state with the baseline captured earlier in the edit session. If those diverge, the conflict dialog path is used instead of silently overwriting the server copy.\n\nThis is also why recovery state is more than a cosmetic convenience feature. It protects the editing workflow from leaving users with stranded temp files and unclear lock state after interruption.\n\n## Preferences, Pairing UI, and Update Checks\n\nThe reused main window also hosts companion preferences.\n\nCurrent public settings include:\n\n- upload conflict behavior\n- auto-start at sign-in\n- desktop notifications\n- update channel selection\n- temp-file retention period\n- paired-origin management\n\nThe update path itself is channel-aware and lives in `commands/update.rs`, but detailed release-feed and packaging workflow belongs with companion distribution and update documentation rather than this runtime page.\n\nThe pairing window is a separate UI surface because browser-to-companion approval is part of the trust boundary, not just another generic settings dialog.\n\n## What Usually Breaks When This Layer Changes\n\n- deep links reach the app, but the running instance does not receive forwarded URIs correctly\n- lock acquisition or release gets out of sync with the visible edit lifecycle\n- picker cancellation or launch failure leaves behind stale temp files or sidecars\n- operation recovery loses enough metadata that interrupted edits become hard to resolve safely\n- tray and window state drift apart from the actual set of active operations\n\n## Where to Continue\n\n- Use [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) for pairing, localhost auth, deep-link trust boundaries, and origin scoping.\n- Use [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/) for the difference between local-drive access and SMB-backed save-back.\n- Use [Companion Release Overview](../../release-and-versioning/companion-release-overview/) when the change affects packaged releases or updater rollout rather than runtime behavior.\n\n## Validation Expectations\n\nWhen this runtime changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe frontend and backend checks matter whenever the companion change alters a shared workflow contract.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Companion Runtime and Native-App Editing\"\n+++\n\nThis page covers the companion runtime that sits between the browser's deep-link request and the desktop user's native editing session.\n\nUse it when a change affects:\n\n- deep-link handling and single-instance behavior\n- app selection and native-app launching\n- operation persistence, recovery, and temp-file lifecycle\n- tray, app-picker, large-file, and \"Done Editing\" window behavior\n\nFor localhost pairing and local-drive behavior, continue to [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) and [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\n## Runtime Modes and UI Surfaces\n\nThe companion is not a traditional always-visible desktop app.\n\nIn normal use it shifts between a few runtime modes:\n\n- tray-oriented background state when no editing dialog is open\n- a reused main window for app picker, preferences, large-file confirmation, and recovery dialogs\n- a dedicated pairing window for browser-to-companion approval\n- one \"Done Editing\" window per active native-app edit session\n\nThat split is deliberate. The companion should stay lightweight when idle, but it still needs focused UI surfaces for edit coordination and pairing approval.\n\nBecause the companion is a tray-oriented app, closing the last transient webview must not implicitly terminate the process. The runtime intentionally prevents last-window destruction from exiting the app; explicit quit requests from the tray still exit normally.\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/App.tsx` | frontend view routing for idle, app picker, preferences, recovery, and large-file flows |\n| `companion/src/components/` | desktop-facing UI surfaces such as `AppPicker`, `DoneEditingWindow`, `RecoveryDialog`, and `Preferences` |\n| `companion/src/stores/` | persisted frontend preferences for app selection and companion settings |\n| `companion/src-tauri/src/lib.rs` | Tauri setup, plugin wiring, deep-link handling, window management, tray behavior, and lifecycle orchestration |\n| `companion/src-tauri/src/commands/` | commands for file info, download, upload, app selection, pairing, localization, and updates |\n| `companion/src-tauri/src/http_client.rs` | shared backend HTTP clients, reverse-proxy cookie jars, request diagnostics, and URL sanitization |\n| `companion/src-tauri/src/app_registry/` | platform-specific native-app discovery and launch integration |\n| `companion/src-tauri/src/sync/` | operation persistence, temp-file handling, recycle retention, and recovery helpers |\n| `companion/src-tauri/src/token/` and `uri/` | URI parsing and bootstrap-token exchange for deep-link editing |\n\n## Deep-Link Ingress\n\nNative-app editing starts from a `sambee://open?...` URI.\n\nThe runtime pieces involved are:\n\n- `tauri-plugin-deep-link` for receiving the URI\n- `tauri-plugin-single-instance` so later URIs are forwarded to the running instance instead of launching competing copies\n- `uri/mod.rs` for parsing required parameters such as `server`, `token`, `connId`, and `path`\n- `token/mod.rs` for exchanging the short-lived URI token for a companion bootstrap token\n\nThe deep link can also carry theme data so the companion UI matches the browser-side theme during the editing flow.\n\n## Reverse-Proxy Authentication Path\n\nNative editing supports reverse proxies and SSO layers that require interactive browser authentication before backend API requests are allowed through.\n\nThe implemented flow is:\n\n1. Companion tries the normal URI-token exchange.\n2. If token exchange is intercepted by a login redirect or HTML sign-in page, the companion opens a dedicated `Sambee Authentication` webview.\n3. The user signs in through that embedded webview.\n4. Companion reads backend-origin cookies from that same webview and seeds its shared Rust `reqwest` cookie jar.\n5. Token exchange and the rest of the native-edit lifecycle reuse that authenticated client state.\n\nThe HTTP client store is keyed by normalized server URL. For each server, it keeps a stable cookie jar plus default and no-redirect clients. The no-redirect client is used where redirect responses are diagnostic signals, such as URI-token exchange. The default client is reused for file-info lookup, lock acquisition, download, upload, lock release, and heartbeat requests.\n\nThis matters for the trust model:\n\n- Browser-to-companion localhost pairing remains separate from reverse-proxy authentication.\n- The Sambee bearer token remains separate from reverse-proxy cookies.\n- External browser cookies are not read or imported.\n- Reverse-proxy cookies stay inside the companion-owned webview and Rust HTTP client state.\n- Cookie values must not be logged.\n\nCompanion automatically retries idempotent backend calls such as file-info lookup, lock acquisition, download, lock release, and heartbeats after reauthentication. Non-idempotent uploads are not replayed automatically; the runtime instead asks the user to retry the action after authentication has been refreshed.\n\nFor reverse-proxy auth robustness, the shared Companion HTTP clients stay on HTTP/1.1 rather than enabling HTTP/2.\n\nRequest failures are logged with classified diagnostics such as timeout, connect, request, body, decode, and status. URLs and chained source errors are sanitized before logging so deep-link tokens, proxy sessions, and other sensitive query values do not appear in logs.\n\n## Native-App Edit Lifecycle\n\nThe implemented lifecycle in `lib.rs` is intentionally explicit.\n\nAt a high level it is:\n\n1. parse the deep link\n2. exchange the URI token for a companion bootstrap token\n3. fetch file metadata for file-size checks and conflict baseline\n4. optionally pause for a large-file confirmation dialog\n5. acquire the backend edit lock and receive operation-scoped lock context\n6. download the file into the companion temp area\n7. create a `FileOperation`, persist its sidecar, and add it to the in-memory store\n8. show the app picker and wait for user selection\n9. open the local file in the selected native application\n10. spawn a dedicated \"Done Editing\" window\n11. start background renewal, heartbeat, and file-status polling\n\nTwo rules matter here:\n\n- the backend lock is acquired before the edit session is allowed to proceed\n- the companion records local operation state before handing control to the native app\n\nThose decisions are what make recovery and conflict handling possible after crashes or interrupted sessions.\n\n## App Selection and Native Launching\n\nThe companion keeps platform-specific native-app discovery behind `app_registry/`.\n\nThat layer is responsible for:\n\n- listing handlers for a file extension\n- surfacing the default app first when possible\n- returning enough information for the UI to distinguish executable paths and handler identifiers\n- launching the chosen app or falling back to system-default open behavior when appropriate\n\nThe app picker flow is coordinated through Tauri events.\n\n- the Rust runtime emits `show-app-picker`\n- the frontend displays `AppPicker`\n- the user response is sent back through `respond_app_selection`\n\nStored per-extension app preferences live in `appPreferences.ts`, which is how repeated opens can bypass unnecessary picker friction.\n\nOn Windows, the launch path is more subtle than a simple `CreateProcess` call because packaged handlers and opaque shell associations may need Windows shell invocation rather than direct executable launching.\n\n## Operation Model, Temp Files, and Recovery\n\nDeep-link editing is tracked through `FileOperation` in `sync/operations.rs`.\n\nEach operation records:\n\n- server URL, connection, and remote path\n- local temp-file path\n- current status\n- original modification time\n- chosen app name\n- operation-scoped lock context and server-side last-modified baseline\n\nThe companion keeps this state in two places:\n\n- an in-memory `OperationStore` for active runtime coordination\n- a sidecar on disk so the session can be recovered after a restart or crash\n\nThat persistence model supports the recovery flow shown through `RecoveryDialog` when leftover operations are discovered at startup.\n\nThe temp-file lifecycle is also intentionally not just \"download and delete\":\n\n- active sessions live in a managed temp area\n- completed or discarded files move through recycle and retention logic\n- retention duration is user-configurable through preferences\n\n## \"Done Editing\" and Explicit Save-Back\n\nThe companion does not try to infer when a user is \"probably done\" in their native editor.\n\nInstead it keeps a dedicated \"Done Editing\" window open while:\n\n- file status polling checks whether the local temp file changed\n- renewal and heartbeat requests keep the edit session and backend lock alive\n\nWhen the user explicitly finishes or discards the session, the companion can:\n\n- upload the modified file\n- release the backend lock\n- recycle the temp copy\n- update the tray and operation state\n\nThat explicit-confirmation model is one of the core product decisions behind native-app editing, not a UI accident.\n\n## Conflict and Recovery Handling\n\nThe companion keeps enough state to detect overwrite-sensitive conflicts.\n\nBefore completing an upload-sensitive flow, it compares the current server-side state with the baseline captured earlier in the edit session. If those diverge, the conflict dialog path is used instead of silently overwriting the server copy.\n\nThis is also why recovery state is more than a cosmetic convenience feature. It protects the editing workflow from leaving users with stranded temp files and unclear lock state after interruption.\n\n## Preferences, Pairing UI, and Update Checks\n\nThe reused main window also hosts companion preferences.\n\nCurrent public settings include:\n\n- upload conflict behavior\n- auto-start at sign-in\n- desktop notifications\n- update channel selection\n- temp-file retention period\n- paired-origin management\n\nThe update path itself is channel-aware and lives in `commands/update.rs`, but detailed release-feed and packaging workflow belongs with companion distribution and update documentation rather than this runtime page.\n\nThe pairing window is a separate UI surface because browser-to-companion approval is part of the trust boundary, not just another generic settings dialog.\n\n## What Usually Breaks When This Layer Changes\n\n- deep links reach the app, but the running instance does not receive forwarded URIs correctly\n- lock acquisition or release gets out of sync with the visible edit lifecycle\n- picker cancellation or launch failure leaves behind stale temp files or sidecars\n- operation recovery loses enough metadata that interrupted edits become hard to resolve safely\n- tray and window state drift apart from the actual set of active operations\n\n## Where to Continue\n\n- Use [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) for pairing, localhost auth, deep-link trust boundaries, and origin scoping.\n- Use [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/) for the difference between local-drive access and SMB-backed save-back.\n- Use [Companion Release Overview](../../release-and-versioning/companion-release-overview/) when the change affects packaged releases or updater rollout rather than runtime behavior.\n\n## Validation Expectations\n\nWhen this runtime changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe frontend and backend checks matter whenever the companion change alters a shared workflow contract.\n", "0.8": "+++\ntitle = \"Companion Runtime and Native-App Editing\"\n+++\n\nThis page covers the companion runtime that sits between the browser's deep-link request and the desktop user's native editing session.\n\nUse it when a change affects:\n\n- deep-link handling and single-instance behavior\n- app selection and native-app launching\n- operation persistence, recovery, and temp-file lifecycle\n- tray, app-picker, large-file, and \"Done Editing\" window behavior\n\nFor localhost pairing and local-drive behavior, continue to [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) and [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\n## Runtime Modes and UI Surfaces\n\nThe companion is not a traditional always-visible desktop app.\n\nIn normal use it shifts between a few runtime modes:\n\n- tray-oriented background state when no editing dialog is open\n- a reused main window for app picker, preferences, large-file confirmation, and recovery dialogs\n- a dedicated pairing window for browser-to-companion approval\n- one \"Done Editing\" window per active native-app edit session\n\nThat split is deliberate. The companion should stay lightweight when idle, but it still needs focused UI surfaces for edit coordination and pairing approval.\n\nBecause the companion is a tray-oriented app, closing the last transient webview must not implicitly terminate the process. The runtime intentionally prevents last-window destruction from exiting the app; explicit quit requests from the tray still exit normally.\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/App.tsx` | frontend view routing for idle, app picker, preferences, recovery, and large-file flows |\n| `companion/src/components/` | desktop-facing UI surfaces such as `AppPicker`, `DoneEditingWindow`, `RecoveryDialog`, and `Preferences` |\n| `companion/src/stores/` | persisted frontend preferences for app selection and companion settings |\n| `companion/src-tauri/src/lib.rs` | Tauri setup, plugin wiring, deep-link handling, window management, tray behavior, and lifecycle orchestration |\n| `companion/src-tauri/src/commands/` | commands for file info, download, upload, app selection, pairing, localization, and updates |\n| `companion/src-tauri/src/http_client.rs` | shared backend HTTP clients, reverse-proxy cookie jars, request diagnostics, and URL sanitization |\n| `companion/src-tauri/src/app_registry/` | platform-specific native-app discovery and launch integration |\n| `companion/src-tauri/src/sync/` | operation persistence, temp-file handling, recycle retention, and recovery helpers |\n| `companion/src-tauri/src/token/` and `uri/` | URI parsing and bootstrap-token exchange for deep-link editing |\n\n## Deep-Link Ingress\n\nNative-app editing starts from a `sambee://open?...` URI.\n\nThe runtime pieces involved are:\n\n- `tauri-plugin-deep-link` for receiving the URI\n- `tauri-plugin-single-instance` so later URIs are forwarded to the running instance instead of launching competing copies\n- `uri/mod.rs` for parsing required parameters such as `server`, `token`, `connId`, and `path`\n- `token/mod.rs` for exchanging the short-lived URI token for a companion bootstrap token\n\nThe deep link can also carry theme data so the companion UI matches the browser-side theme during the editing flow.\n\n## Reverse-Proxy Authentication Path\n\nNative editing supports reverse proxies and SSO layers that require interactive browser authentication before backend API requests are allowed through.\n\nThe implemented flow is:\n\n1. Companion tries the normal URI-token exchange.\n2. If token exchange is intercepted by a login redirect or HTML sign-in page, the companion opens a dedicated `Sambee Authentication` webview.\n3. The user signs in through that embedded webview.\n4. Companion reads backend-origin cookies from that same webview and seeds its shared Rust `reqwest` cookie jar.\n5. Token exchange and the rest of the native-edit lifecycle reuse that authenticated client state.\n\nThe HTTP client store is keyed by normalized server URL. For each server, it keeps a stable cookie jar plus default and no-redirect clients. The no-redirect client is used where redirect responses are diagnostic signals, such as URI-token exchange. The default client is reused for file-info lookup, lock acquisition, download, upload, lock release, and heartbeat requests.\n\nThis matters for the trust model:\n\n- Browser-to-companion localhost pairing remains separate from reverse-proxy authentication.\n- The Sambee bearer token remains separate from reverse-proxy cookies.\n- External browser cookies are not read or imported.\n- Reverse-proxy cookies stay inside the companion-owned webview and Rust HTTP client state.\n- Cookie values must not be logged.\n\nCompanion automatically retries idempotent backend calls such as file-info lookup, lock acquisition, download, lock release, and heartbeats after reauthentication. Non-idempotent uploads are not replayed automatically; the runtime instead asks the user to retry the action after authentication has been refreshed.\n\nFor reverse-proxy auth robustness, the shared Companion HTTP clients stay on HTTP/1.1 rather than enabling HTTP/2.\n\nRequest failures are logged with classified diagnostics such as timeout, connect, request, body, decode, and status. URLs and chained source errors are sanitized before logging so deep-link tokens, proxy sessions, and other sensitive query values do not appear in logs.\n\n## Native-App Edit Lifecycle\n\nThe implemented lifecycle in `lib.rs` is intentionally explicit.\n\nAt a high level it is:\n\n1. parse the deep link\n2. exchange the URI token for a companion bootstrap token\n3. fetch file metadata for file-size checks and conflict baseline\n4. optionally pause for a large-file confirmation dialog\n5. acquire the backend edit lock and receive operation-scoped lock context\n6. download the file into the companion temp area\n7. create a `FileOperation`, persist its sidecar, and add it to the in-memory store\n8. show the app picker and wait for user selection\n9. open the local file in the selected native application\n10. spawn a dedicated \"Done Editing\" window\n11. start background renewal, heartbeat, and file-status polling\n\nTwo rules matter here:\n\n- the backend lock is acquired before the edit session is allowed to proceed\n- the companion records local operation state before handing control to the native app\n\nThose decisions are what make recovery and conflict handling possible after crashes or interrupted sessions.\n\n## App Selection and Native Launching\n\nThe companion keeps platform-specific native-app discovery behind `app_registry/`.\n\nThat layer is responsible for:\n\n- listing handlers for a file extension\n- surfacing the default app first when possible\n- returning enough information for the UI to distinguish executable paths and handler identifiers\n- launching the chosen app or falling back to system-default open behavior when appropriate\n\nThe app picker flow is coordinated through Tauri events.\n\n- the Rust runtime emits `show-app-picker`\n- the frontend displays `AppPicker`\n- the user response is sent back through `respond_app_selection`\n\nStored per-extension app preferences live in `appPreferences.ts`, which is how repeated opens can bypass unnecessary picker friction.\n\nOn Windows, the launch path is more subtle than a simple `CreateProcess` call because packaged handlers and opaque shell associations may need Windows shell invocation rather than direct executable launching.\n\n## Operation Model, Temp Files, and Recovery\n\nDeep-link editing is tracked through `FileOperation` in `sync/operations.rs`.\n\nEach operation records:\n\n- server URL, connection, and remote path\n- local temp-file path\n- current status\n- original modification time\n- chosen app name\n- operation-scoped lock context and server-side last-modified baseline\n\nThe companion keeps this state in two places:\n\n- an in-memory `OperationStore` for active runtime coordination\n- a sidecar on disk so the session can be recovered after a restart or crash\n\nThat persistence model supports the recovery flow shown through `RecoveryDialog` when leftover operations are discovered at startup.\n\nThe temp-file lifecycle is also intentionally not just \"download and delete\":\n\n- active sessions live in a managed temp area\n- completed or discarded files move through recycle and retention logic\n- retention duration is user-configurable through preferences\n\n## \"Done Editing\" and Explicit Save-Back\n\nThe companion does not try to infer when a user is \"probably done\" in their native editor.\n\nInstead it keeps a dedicated \"Done Editing\" window open while:\n\n- file status polling checks whether the local temp file changed\n- renewal and heartbeat requests keep the edit session and backend lock alive\n\nWhen the user explicitly finishes or discards the session, the companion can:\n\n- upload the modified file\n- release the backend lock\n- recycle the temp copy\n- update the tray and operation state\n\nThat explicit-confirmation model is one of the core product decisions behind native-app editing, not a UI accident.\n\n## Conflict and Recovery Handling\n\nThe companion keeps enough state to detect overwrite-sensitive conflicts.\n\nBefore completing an upload-sensitive flow, it compares the current server-side state with the baseline captured earlier in the edit session. If those diverge, the conflict dialog path is used instead of silently overwriting the server copy.\n\nThis is also why recovery state is more than a cosmetic convenience feature. It protects the editing workflow from leaving users with stranded temp files and unclear lock state after interruption.\n\n## Preferences, Pairing UI, and Update Checks\n\nThe reused main window also hosts companion preferences.\n\nCurrent public settings include:\n\n- upload conflict behavior\n- auto-start at sign-in\n- desktop notifications\n- update channel selection\n- temp-file retention period\n- paired-origin management\n\nThe update path itself is channel-aware and lives in `commands/update.rs`, but detailed release-feed and packaging workflow belongs with companion distribution and update documentation rather than this runtime page.\n\nThe pairing window is a separate UI surface because browser-to-companion approval is part of the trust boundary, not just another generic settings dialog.\n\n## What Usually Breaks When This Layer Changes\n\n- deep links reach the app, but the running instance does not receive forwarded URIs correctly\n- lock acquisition or release gets out of sync with the visible edit lifecycle\n- picker cancellation or launch failure leaves behind stale temp files or sidecars\n- operation recovery loses enough metadata that interrupted edits become hard to resolve safely\n- tray and window state drift apart from the actual set of active operations\n\n## Where to Continue\n\n- Use [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) for pairing, localhost auth, deep-link trust boundaries, and origin scoping.\n- Use [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/) for the difference between local-drive access and SMB-backed save-back.\n- Use [Companion Release Overview](../../release-and-versioning/companion-release-overview/) when the change affects packaged releases or updater rollout rather than runtime behavior.\n\n## Validation Expectations\n\nWhen this runtime changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe frontend and backend checks matter whenever the companion change alters a shared workflow contract.\n", "0.9": "+++\ntitle = \"Companion Runtime and Native-App Editing\"\n+++\n\nThis page covers the companion runtime that sits between the browser's deep-link request and the desktop user's native editing session.\n\nUse it when a change affects:\n\n- deep-link handling and single-instance behavior\n- app selection and native-app launching\n- operation persistence, recovery, and temp-file lifecycle\n- tray, app-picker, large-file, and \"Done Editing\" window behavior\n\nFor localhost pairing and local-drive behavior, continue to [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) and [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\n## Runtime Modes and UI Surfaces\n\nThe companion is not a traditional always-visible desktop app.\n\nIn normal use it shifts between a few runtime modes:\n\n- tray-oriented background state when no editing dialog is open\n- a reused main window for app picker, preferences, large-file confirmation, and recovery dialogs\n- a dedicated pairing window for browser-to-companion approval\n- one \"Done Editing\" window per active native-app edit session\n\nThat split is deliberate. The companion should stay lightweight when idle, but it still needs focused UI surfaces for edit coordination and pairing approval.\n\nBecause the companion is a tray-oriented app, closing the last transient webview must not implicitly terminate the process. The runtime intentionally prevents last-window destruction from exiting the app; explicit quit requests from the tray still exit normally.\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/App.tsx` | frontend view routing for idle, app picker, preferences, recovery, and large-file flows |\n| `companion/src/components/` | desktop-facing UI surfaces such as `AppPicker`, `DoneEditingWindow`, `RecoveryDialog`, and `Preferences` |\n| `companion/src/stores/` | persisted frontend preferences for app selection and companion settings |\n| `companion/src-tauri/src/lib.rs` | Tauri setup, plugin wiring, deep-link handling, window management, tray behavior, and lifecycle orchestration |\n| `companion/src-tauri/src/commands/` | commands for file info, download, upload, app selection, pairing, localization, and updates |\n| `companion/src-tauri/src/http_client.rs` | shared backend HTTP clients, reverse-proxy cookie jars, request diagnostics, and URL sanitization |\n| `companion/src-tauri/src/app_registry/` | platform-specific native-app discovery and launch integration |\n| `companion/src-tauri/src/sync/` | operation persistence, temp-file handling, recycle retention, and recovery helpers |\n| `companion/src-tauri/src/token/` and `uri/` | URI parsing and bootstrap-token exchange for deep-link editing |\n\n## Deep-Link Ingress\n\nNative-app editing starts from a `sambee://open?...` URI.\n\nThe runtime pieces involved are:\n\n- `tauri-plugin-deep-link` for receiving the URI\n- `tauri-plugin-single-instance` so later URIs are forwarded to the running instance instead of launching competing copies\n- `uri/mod.rs` for parsing required parameters such as `server`, `token`, `connId`, and `path`\n- `token/mod.rs` for exchanging the short-lived URI token for a companion bootstrap token\n\nThe deep link can also carry theme data so the companion UI matches the browser-side theme during the editing flow.\n\n## Reverse-Proxy Authentication Path\n\nNative editing supports reverse proxies and SSO layers that require interactive browser authentication before backend API requests are allowed through.\n\nThe implemented flow is:\n\n1. Companion tries the normal URI-token exchange.\n2. If token exchange is intercepted by a login redirect or HTML sign-in page, the companion opens a dedicated `Sambee Authentication` webview.\n3. The user signs in through that embedded webview.\n4. Companion reads backend-origin cookies from that same webview and seeds its shared Rust `reqwest` cookie jar.\n5. Token exchange and the rest of the native-edit lifecycle reuse that authenticated client state.\n\nThe HTTP client store is keyed by normalized server URL. For each server, it keeps a stable cookie jar plus default and no-redirect clients. The no-redirect client is used where redirect responses are diagnostic signals, such as URI-token exchange. The default client is reused for file-info lookup, lock acquisition, download, upload, lock release, and heartbeat requests.\n\nThis matters for the trust model:\n\n- Browser-to-companion localhost pairing remains separate from reverse-proxy authentication.\n- The Sambee bearer token remains separate from reverse-proxy cookies.\n- External browser cookies are not read or imported.\n- Reverse-proxy cookies stay inside the companion-owned webview and Rust HTTP client state.\n- Cookie values must not be logged.\n\nCompanion automatically retries idempotent backend calls such as file-info lookup, lock acquisition, download, lock release, and heartbeats after reauthentication. Non-idempotent uploads are not replayed automatically; the runtime instead asks the user to retry the action after authentication has been refreshed.\n\nFor reverse-proxy auth robustness, the shared Companion HTTP clients stay on HTTP/1.1 rather than enabling HTTP/2.\n\nRequest failures are logged with classified diagnostics such as timeout, connect, request, body, decode, and status. URLs and chained source errors are sanitized before logging so deep-link tokens, proxy sessions, and other sensitive query values do not appear in logs.\n\n## Native-App Edit Lifecycle\n\nThe implemented lifecycle in `lib.rs` is intentionally explicit.\n\nAt a high level it is:\n\n1. parse the deep link\n2. exchange the URI token for a companion bootstrap token\n3. fetch file metadata for file-size checks and conflict baseline\n4. optionally pause for a large-file confirmation dialog\n5. acquire the backend edit lock and receive operation-scoped lock context\n6. download the file into the companion temp area\n7. create a `FileOperation`, persist its sidecar, and add it to the in-memory store\n8. show the app picker and wait for user selection\n9. open the local file in the selected native application\n10. spawn a dedicated \"Done Editing\" window\n11. start background renewal, heartbeat, and file-status polling\n\nTwo rules matter here:\n\n- the backend lock is acquired before the edit session is allowed to proceed\n- the companion records local operation state before handing control to the native app\n\nThose decisions are what make recovery and conflict handling possible after crashes or interrupted sessions.\n\n## App Selection and Native Launching\n\nThe companion keeps platform-specific native-app discovery behind `app_registry/`.\n\nThat layer is responsible for:\n\n- listing handlers for a file extension\n- surfacing the default app first when possible\n- returning enough information for the UI to distinguish executable paths and handler identifiers\n- launching the chosen app or falling back to system-default open behavior when appropriate\n\nThe app picker flow is coordinated through Tauri events.\n\n- the Rust runtime emits `show-app-picker`\n- the frontend displays `AppPicker`\n- the user response is sent back through `respond_app_selection`\n\nStored per-extension app preferences live in `appPreferences.ts`, which is how repeated opens can bypass unnecessary picker friction.\n\nOn Windows, the launch path is more subtle than a simple `CreateProcess` call because packaged handlers and opaque shell associations may need Windows shell invocation rather than direct executable launching.\n\n## Operation Model, Temp Files, and Recovery\n\nDeep-link editing is tracked through `FileOperation` in `sync/operations.rs`.\n\nEach operation records:\n\n- server URL, connection, and remote path\n- local temp-file path\n- current status\n- original modification time\n- chosen app name\n- operation-scoped lock context and server-side last-modified baseline\n\nThe companion keeps this state in two places:\n\n- an in-memory `OperationStore` for active runtime coordination\n- a sidecar on disk so the session can be recovered after a restart or crash\n\nThat persistence model supports the recovery flow shown through `RecoveryDialog` when leftover operations are discovered at startup.\n\nThe temp-file lifecycle is also intentionally not just \"download and delete\":\n\n- active sessions live in a managed temp area\n- completed or discarded files move through recycle and retention logic\n- retention duration is user-configurable through preferences\n\n## \"Done Editing\" and Explicit Save-Back\n\nThe companion does not try to infer when a user is \"probably done\" in their native editor.\n\nInstead it keeps a dedicated \"Done Editing\" window open while:\n\n- file status polling checks whether the local temp file changed\n- renewal and heartbeat requests keep the edit session and backend lock alive\n\nWhen the user explicitly finishes or discards the session, the companion can:\n\n- upload the modified file\n- release the backend lock\n- recycle the temp copy\n- update the tray and operation state\n\nThat explicit-confirmation model is one of the core product decisions behind native-app editing, not a UI accident.\n\n## Conflict and Recovery Handling\n\nThe companion keeps enough state to detect overwrite-sensitive conflicts.\n\nBefore completing an upload-sensitive flow, it compares the current server-side state with the baseline captured earlier in the edit session. If those diverge, the conflict dialog path is used instead of silently overwriting the server copy.\n\nThis is also why recovery state is more than a cosmetic convenience feature. It protects the editing workflow from leaving users with stranded temp files and unclear lock state after interruption.\n\n## Preferences, Pairing UI, and Update Checks\n\nThe reused main window also hosts companion preferences.\n\nCurrent public settings include:\n\n- upload conflict behavior\n- auto-start at sign-in\n- desktop notifications\n- update channel selection\n- temp-file retention period\n- paired-origin management\n\nThe update path itself is channel-aware and lives in `commands/update.rs`, but detailed release-feed and packaging workflow belongs with companion distribution and update documentation rather than this runtime page.\n\nThe pairing window is a separate UI surface because browser-to-companion approval is part of the trust boundary, not just another generic settings dialog.\n\n## What Usually Breaks When This Layer Changes\n\n- deep links reach the app, but the running instance does not receive forwarded URIs correctly\n- lock acquisition or release gets out of sync with the visible edit lifecycle\n- picker cancellation or launch failure leaves behind stale temp files or sidecars\n- operation recovery loses enough metadata that interrupted edits become hard to resolve safely\n- tray and window state drift apart from the actual set of active operations\n\n## Where to Continue\n\n- Use [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) for pairing, localhost auth, deep-link trust boundaries, and origin scoping.\n- Use [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/) for the difference between local-drive access and SMB-backed save-back.\n- Use [Companion Release Overview](../../release-and-versioning/companion-release-overview/) when the change affects packaged releases or updater rollout rather than runtime behavior.\n\n## Validation Expectations\n\nWhen this runtime changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe frontend and backend checks matter whenever the companion change alters a shared workflow contract.\n", "1.0": "+++\ntitle = \"Companion Runtime and Native-App Editing\"\n+++\n\nThis page covers the companion runtime that sits between the browser's deep-link request and the desktop user's native editing session.\n\nUse it when a change affects:\n\n- deep-link handling and single-instance behavior\n- app selection and native-app launching\n- operation persistence, recovery, and temp-file lifecycle\n- tray, app-picker, large-file, and \"Done Editing\" window behavior\n\nFor localhost pairing and local-drive behavior, continue to [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) and [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\n## Runtime Modes and UI Surfaces\n\nThe companion is not a traditional always-visible desktop app.\n\nIn normal use it shifts between a few runtime modes:\n\n- tray-oriented background state when no editing dialog is open\n- a reused main window for app picker, preferences, large-file confirmation, and recovery dialogs\n- a dedicated pairing window for browser-to-companion approval\n- one \"Done Editing\" window per active native-app edit session\n\nThat split is deliberate. The companion should stay lightweight when idle, but it still needs focused UI surfaces for edit coordination and pairing approval.\n\nBecause the companion is a tray-oriented app, closing the last transient webview must not implicitly terminate the process. The runtime intentionally prevents last-window destruction from exiting the app; explicit quit requests from the tray still exit normally.\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/App.tsx` | frontend view routing for idle, app picker, preferences, recovery, and large-file flows |\n| `companion/src/components/` | desktop-facing UI surfaces such as `AppPicker`, `DoneEditingWindow`, `RecoveryDialog`, and `Preferences` |\n| `companion/src/stores/` | persisted frontend preferences for app selection and companion settings |\n| `companion/src-tauri/src/lib.rs` | Tauri setup, plugin wiring, deep-link handling, window management, tray behavior, and lifecycle orchestration |\n| `companion/src-tauri/src/commands/` | commands for file info, download, upload, app selection, pairing, localization, and updates |\n| `companion/src-tauri/src/http_client.rs` | shared backend HTTP clients, reverse-proxy cookie jars, request diagnostics, and URL sanitization |\n| `companion/src-tauri/src/app_registry/` | platform-specific native-app discovery and launch integration |\n| `companion/src-tauri/src/sync/` | operation persistence, temp-file handling, recycle retention, and recovery helpers |\n| `companion/src-tauri/src/token/` and `uri/` | URI parsing and bootstrap-token exchange for deep-link editing |\n\n## Deep-Link Ingress\n\nNative-app editing starts from a `sambee://open?...` URI.\n\nThe runtime pieces involved are:\n\n- `tauri-plugin-deep-link` for receiving the URI\n- `tauri-plugin-single-instance` so later URIs are forwarded to the running instance instead of launching competing copies\n- `uri/mod.rs` for parsing required parameters such as `server`, `token`, `connId`, and `path`\n- `token/mod.rs` for exchanging the short-lived URI token for a companion bootstrap token\n\nThe deep link can also carry theme data so the companion UI matches the browser-side theme during the editing flow.\n\n## Reverse-Proxy Authentication Path\n\nNative editing supports reverse proxies and SSO layers that require interactive browser authentication before backend API requests are allowed through.\n\nThe implemented flow is:\n\n1. Companion tries the normal URI-token exchange.\n2. If token exchange is intercepted by a login redirect or HTML sign-in page, the companion opens a dedicated `Sambee Authentication` webview.\n3. The user signs in through that embedded webview.\n4. Companion reads backend-origin cookies from that same webview and seeds its shared Rust `reqwest` cookie jar.\n5. Token exchange and the rest of the native-edit lifecycle reuse that authenticated client state.\n\nThe HTTP client store is keyed by normalized server URL. For each server, it keeps a stable cookie jar plus default and no-redirect clients. The no-redirect client is used where redirect responses are diagnostic signals, such as URI-token exchange. The default client is reused for file-info lookup, lock acquisition, download, upload, lock release, and heartbeat requests.\n\nThis matters for the trust model:\n\n- Browser-to-companion localhost pairing remains separate from reverse-proxy authentication.\n- The Sambee bearer token remains separate from reverse-proxy cookies.\n- External browser cookies are not read or imported.\n- Reverse-proxy cookies stay inside the companion-owned webview and Rust HTTP client state.\n- Cookie values must not be logged.\n\nCompanion automatically retries idempotent backend calls such as file-info lookup, lock acquisition, download, lock release, and heartbeats after reauthentication. Non-idempotent uploads are not replayed automatically; the runtime instead asks the user to retry the action after authentication has been refreshed.\n\nFor reverse-proxy auth robustness, the shared Companion HTTP clients stay on HTTP/1.1 rather than enabling HTTP/2.\n\nRequest failures are logged with classified diagnostics such as timeout, connect, request, body, decode, and status. URLs and chained source errors are sanitized before logging so deep-link tokens, proxy sessions, and other sensitive query values do not appear in logs.\n\n## Native-App Edit Lifecycle\n\nThe implemented lifecycle in `lib.rs` is intentionally explicit.\n\nAt a high level it is:\n\n1. parse the deep link\n2. exchange the URI token for a companion bootstrap token\n3. fetch file metadata for file-size checks and conflict baseline\n4. optionally pause for a large-file confirmation dialog\n5. acquire the backend edit lock and receive operation-scoped lock context\n6. download the file into the companion temp area\n7. create a `FileOperation`, persist its sidecar, and add it to the in-memory store\n8. show the app picker and wait for user selection\n9. open the local file in the selected native application\n10. spawn a dedicated \"Done Editing\" window\n11. start background renewal, heartbeat, and file-status polling\n\nTwo rules matter here:\n\n- the backend lock is acquired before the edit session is allowed to proceed\n- the companion records local operation state before handing control to the native app\n\nThose decisions are what make recovery and conflict handling possible after crashes or interrupted sessions.\n\n## App Selection and Native Launching\n\nThe companion keeps platform-specific native-app discovery behind `app_registry/`.\n\nThat layer is responsible for:\n\n- listing handlers for a file extension\n- surfacing the default app first when possible\n- returning enough information for the UI to distinguish executable paths and handler identifiers\n- launching the chosen app or falling back to system-default open behavior when appropriate\n\nThe app picker flow is coordinated through Tauri events.\n\n- the Rust runtime emits `show-app-picker`\n- the frontend displays `AppPicker`\n- the user response is sent back through `respond_app_selection`\n\nStored per-extension app preferences live in `appPreferences.ts`, which is how repeated opens can bypass unnecessary picker friction.\n\nOn Windows, the launch path is more subtle than a simple `CreateProcess` call because packaged handlers and opaque shell associations may need Windows shell invocation rather than direct executable launching.\n\n## Operation Model, Temp Files, and Recovery\n\nDeep-link editing is tracked through `FileOperation` in `sync/operations.rs`.\n\nEach operation records:\n\n- server URL, connection, and remote path\n- local temp-file path\n- current status\n- original modification time\n- chosen app name\n- operation-scoped lock context and server-side last-modified baseline\n\nThe companion keeps this state in two places:\n\n- an in-memory `OperationStore` for active runtime coordination\n- a sidecar on disk so the session can be recovered after a restart or crash\n\nThat persistence model supports the recovery flow shown through `RecoveryDialog` when leftover operations are discovered at startup.\n\nThe temp-file lifecycle is also intentionally not just \"download and delete\":\n\n- active sessions live in a managed temp area\n- completed or discarded files move through recycle and retention logic\n- retention duration is user-configurable through preferences\n\n## \"Done Editing\" and Explicit Save-Back\n\nThe companion does not try to infer when a user is \"probably done\" in their native editor.\n\nInstead it keeps a dedicated \"Done Editing\" window open while:\n\n- file status polling checks whether the local temp file changed\n- renewal and heartbeat requests keep the edit session and backend lock alive\n\nWhen the user explicitly finishes or discards the session, the companion can:\n\n- upload the modified file\n- release the backend lock\n- recycle the temp copy\n- update the tray and operation state\n\nThat explicit-confirmation model is one of the core product decisions behind native-app editing, not a UI accident.\n\n## Conflict and Recovery Handling\n\nThe companion keeps enough state to detect overwrite-sensitive conflicts.\n\nBefore completing an upload-sensitive flow, it compares the current server-side state with the baseline captured earlier in the edit session. If those diverge, the conflict dialog path is used instead of silently overwriting the server copy.\n\nThis is also why recovery state is more than a cosmetic convenience feature. It protects the editing workflow from leaving users with stranded temp files and unclear lock state after interruption.\n\n## Preferences, Pairing UI, and Update Checks\n\nThe reused main window also hosts companion preferences.\n\nCurrent public settings include:\n\n- upload conflict behavior\n- auto-start at sign-in\n- desktop notifications\n- update channel selection\n- temp-file retention period\n- paired-origin management\n\nThe update path itself is channel-aware and lives in `commands/update.rs`, but detailed release-feed and packaging workflow belongs with companion distribution and update documentation rather than this runtime page.\n\nThe pairing window is a separate UI surface because browser-to-companion approval is part of the trust boundary, not just another generic settings dialog.\n\n## What Usually Breaks When This Layer Changes\n\n- deep links reach the app, but the running instance does not receive forwarded URIs correctly\n- lock acquisition or release gets out of sync with the visible edit lifecycle\n- picker cancellation or launch failure leaves behind stale temp files or sidecars\n- operation recovery loses enough metadata that interrupted edits become hard to resolve safely\n- tray and window state drift apart from the actual set of active operations\n\n## Where to Continue\n\n- Use [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) for pairing, localhost auth, deep-link trust boundaries, and origin scoping.\n- Use [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/) for the difference between local-drive access and SMB-backed save-back.\n- Use [Companion Release Overview](../../release-and-versioning/companion-release-overview/) when the change affects packaged releases or updater rollout rather than runtime behavior.\n\n## Validation Expectations\n\nWhen this runtime changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe frontend and backend checks matter whenever the companion change alters a shared workflow contract.\n", "2.0": "+++\ntitle = \"Companion Runtime and Native-App Editing\"\n+++\n\nThis page covers the companion runtime that sits between the browser's deep-link request and the desktop user's native editing session.\n\nUse it when a change affects:\n\n- deep-link handling and single-instance behavior\n- app selection and native-app launching\n- operation persistence, recovery, and temp-file lifecycle\n- tray, app-picker, large-file, and \"Done Editing\" window behavior\n\nFor localhost pairing and local-drive behavior, continue to [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) and [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\n## Runtime Modes and UI Surfaces\n\nThe companion is not a traditional always-visible desktop app.\n\nIn normal use it shifts between a few runtime modes:\n\n- tray-oriented background state when no editing dialog is open\n- a reused main window for app picker, preferences, large-file confirmation, and recovery dialogs\n- a dedicated pairing window for browser-to-companion approval\n- one \"Done Editing\" window per active native-app edit session\n\nThat split is deliberate. The companion should stay lightweight when idle, but it still needs focused UI surfaces for edit coordination and pairing approval.\n\nBecause the companion is a tray-oriented app, closing the last transient webview must not implicitly terminate the process. The runtime intentionally prevents last-window destruction from exiting the app; explicit quit requests from the tray still exit normally.\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/App.tsx` | frontend view routing for idle, app picker, preferences, recovery, and large-file flows |\n| `companion/src/components/` | desktop-facing UI surfaces such as `AppPicker`, `DoneEditingWindow`, `RecoveryDialog`, and `Preferences` |\n| `companion/src/stores/` | persisted frontend preferences for app selection and companion settings |\n| `companion/src-tauri/src/lib.rs` | Tauri setup, plugin wiring, deep-link handling, window management, tray behavior, and lifecycle orchestration |\n| `companion/src-tauri/src/commands/` | commands for file info, download, upload, app selection, pairing, localization, and updates |\n| `companion/src-tauri/src/http_client.rs` | shared backend HTTP clients, reverse-proxy cookie jars, request diagnostics, and URL sanitization |\n| `companion/src-tauri/src/app_registry/` | platform-specific native-app discovery and launch integration |\n| `companion/src-tauri/src/sync/` | operation persistence, temp-file handling, recycle retention, and recovery helpers |\n| `companion/src-tauri/src/token/` and `uri/` | URI parsing and bootstrap-token exchange for deep-link editing |\n\n## Deep-Link Ingress\n\nNative-app editing starts from a `sambee://open?...` URI.\n\nThe runtime pieces involved are:\n\n- `tauri-plugin-deep-link` for receiving the URI\n- `tauri-plugin-single-instance` so later URIs are forwarded to the running instance instead of launching competing copies\n- `uri/mod.rs` for parsing required parameters such as `server`, `token`, `connId`, and `path`\n- `token/mod.rs` for exchanging the short-lived URI token for a companion bootstrap token\n\nThe deep link can also carry theme data so the companion UI matches the browser-side theme during the editing flow.\n\n## Reverse-Proxy Authentication Path\n\nNative editing supports reverse proxies and SSO layers that require interactive browser authentication before backend API requests are allowed through.\n\nThe implemented flow is:\n\n1. Companion tries the normal URI-token exchange.\n2. If token exchange is intercepted by a login redirect or HTML sign-in page, the companion opens a dedicated `Sambee Authentication` webview.\n3. The user signs in through that embedded webview.\n4. Companion reads backend-origin cookies from that same webview and seeds its shared Rust `reqwest` cookie jar.\n5. Token exchange and the rest of the native-edit lifecycle reuse that authenticated client state.\n\nThe HTTP client store is keyed by normalized server URL. For each server, it keeps a stable cookie jar plus default and no-redirect clients. The no-redirect client is used where redirect responses are diagnostic signals, such as URI-token exchange. The default client is reused for file-info lookup, lock acquisition, download, upload, lock release, and heartbeat requests.\n\nThis matters for the trust model:\n\n- Browser-to-companion localhost pairing remains separate from reverse-proxy authentication.\n- The Sambee bearer token remains separate from reverse-proxy cookies.\n- External browser cookies are not read or imported.\n- Reverse-proxy cookies stay inside the companion-owned webview and Rust HTTP client state.\n- Cookie values must not be logged.\n\nCompanion automatically retries idempotent backend calls such as file-info lookup, lock acquisition, download, lock release, and heartbeats after reauthentication. Non-idempotent uploads are not replayed automatically; the runtime instead asks the user to retry the action after authentication has been refreshed.\n\nFor reverse-proxy auth robustness, the shared Companion HTTP clients stay on HTTP/1.1 rather than enabling HTTP/2.\n\nRequest failures are logged with classified diagnostics such as timeout, connect, request, body, decode, and status. URLs and chained source errors are sanitized before logging so deep-link tokens, proxy sessions, and other sensitive query values do not appear in logs.\n\n## Native-App Edit Lifecycle\n\nThe implemented lifecycle in `lib.rs` is intentionally explicit.\n\nAt a high level it is:\n\n1. parse the deep link\n2. exchange the URI token for a companion bootstrap token\n3. fetch file metadata for file-size checks and conflict baseline\n4. optionally pause for a large-file confirmation dialog\n5. acquire the backend edit lock and receive operation-scoped lock context\n6. download the file into the companion temp area\n7. create a `FileOperation`, persist its sidecar, and add it to the in-memory store\n8. show the app picker and wait for user selection\n9. open the local file in the selected native application\n10. spawn a dedicated \"Done Editing\" window\n11. start background renewal, heartbeat, and file-status polling\n\nTwo rules matter here:\n\n- the backend lock is acquired before the edit session is allowed to proceed\n- the companion records local operation state before handing control to the native app\n\nThose decisions are what make recovery and conflict handling possible after crashes or interrupted sessions.\n\n## App Selection and Native Launching\n\nThe companion keeps platform-specific native-app discovery behind `app_registry/`.\n\nThat layer is responsible for:\n\n- listing handlers for a file extension\n- surfacing the default app first when possible\n- returning enough information for the UI to distinguish executable paths and handler identifiers\n- launching the chosen app or falling back to system-default open behavior when appropriate\n\nThe app picker flow is coordinated through Tauri events.\n\n- the Rust runtime emits `show-app-picker`\n- the frontend displays `AppPicker`\n- the user response is sent back through `respond_app_selection`\n\nStored per-extension app preferences live in `appPreferences.ts`, which is how repeated opens can bypass unnecessary picker friction.\n\nOn Windows, the launch path is more subtle than a simple `CreateProcess` call because packaged handlers and opaque shell associations may need Windows shell invocation rather than direct executable launching.\n\n## Operation Model, Temp Files, and Recovery\n\nDeep-link editing is tracked through `FileOperation` in `sync/operations.rs`.\n\nEach operation records:\n\n- server URL, connection, and remote path\n- local temp-file path\n- current status\n- original modification time\n- chosen app name\n- operation-scoped lock context and server-side last-modified baseline\n\nThe companion keeps this state in two places:\n\n- an in-memory `OperationStore` for active runtime coordination\n- a sidecar on disk so the session can be recovered after a restart or crash\n\nThat persistence model supports the recovery flow shown through `RecoveryDialog` when leftover operations are discovered at startup.\n\nThe temp-file lifecycle is also intentionally not just \"download and delete\":\n\n- active sessions live in a managed temp area\n- completed or discarded files move through recycle and retention logic\n- retention duration is user-configurable through preferences\n\n## \"Done Editing\" and Explicit Save-Back\n\nThe companion does not try to infer when a user is \"probably done\" in their native editor.\n\nInstead it keeps a dedicated \"Done Editing\" window open while:\n\n- file status polling checks whether the local temp file changed\n- renewal and heartbeat requests keep the edit session and backend lock alive\n\nWhen the user explicitly finishes or discards the session, the companion can:\n\n- upload the modified file\n- release the backend lock\n- recycle the temp copy\n- update the tray and operation state\n\nThat explicit-confirmation model is one of the core product decisions behind native-app editing, not a UI accident.\n\n## Conflict and Recovery Handling\n\nThe companion keeps enough state to detect overwrite-sensitive conflicts.\n\nBefore completing an upload-sensitive flow, it compares the current server-side state with the baseline captured earlier in the edit session. If those diverge, the conflict dialog path is used instead of silently overwriting the server copy.\n\nThis is also why recovery state is more than a cosmetic convenience feature. It protects the editing workflow from leaving users with stranded temp files and unclear lock state after interruption.\n\n## Preferences, Pairing UI, and Update Checks\n\nThe reused main window also hosts companion preferences.\n\nCurrent public settings include:\n\n- upload conflict behavior\n- auto-start at sign-in\n- desktop notifications\n- update channel selection\n- temp-file retention period\n- paired-origin management\n\nThe update path itself is channel-aware and lives in `commands/update.rs`, but detailed release-feed and packaging workflow belongs with companion distribution and update documentation rather than this runtime page.\n\nThe pairing window is a separate UI surface because browser-to-companion approval is part of the trust boundary, not just another generic settings dialog.\n\n## What Usually Breaks When This Layer Changes\n\n- deep links reach the app, but the running instance does not receive forwarded URIs correctly\n- lock acquisition or release gets out of sync with the visible edit lifecycle\n- picker cancellation or launch failure leaves behind stale temp files or sidecars\n- operation recovery loses enough metadata that interrupted edits become hard to resolve safely\n- tray and window state drift apart from the actual set of active operations\n\n## Where to Continue\n\n- Use [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) for pairing, localhost auth, deep-link trust boundaries, and origin scoping.\n- Use [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/) for the difference between local-drive access and SMB-backed save-back.\n- Use [Companion Release Overview](../../release-and-versioning/companion-release-overview/) when the change affects packaged releases or updater rollout rather than runtime behavior.\n\n## Validation Expectations\n\nWhen this runtime changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe frontend and backend checks matter whenever the companion change alters a shared workflow contract.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/companion-architecture/browser-to-companion-trust-model", "parent_id": "section:developer-guide/companion-architecture", "depth": 2, "kind": "page", "label": "browser-to-companion-trust-model", "title": "Browser To Companion Trust Model", "path": "developer-guide/companion-architecture/browser-to-companion-trust-model", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "branched", "source_version": "0.7", "diff_added": 42, "diff_removed": 8}, "0.9": {"state": "inherited", "source_version": "0.8"}, "1.0": {"state": "inherited", "source_version": "0.8"}, "2.0": {"state": "inherited", "source_version": "0.8"}}, "content_versions": {"0.7": "+++\ntitle = \"Browser-to-Companion Trust Model\"\n+++\n\nThe browser-to-companion boundary is powerful because it crosses from the browser app into desktop-local capability. That makes it one of the most security-sensitive parts of Sambee.\n\n## Two Distinct Trust Paths\n\nSambee uses two browser-to-companion interaction models.\n\n### Deep-Link Editing Path\n\nThis path is used when the browser asks the companion to open an SMB-backed file in a native desktop app.\n\n1. The browser asks the backend for a short-lived URI token.\n1. The browser launches a `sambee://` deep link.\n1. Companion exchanges the one-time token for a companion bootstrap token.\n1. Companion uses that bootstrap token to look up file info, acquire the edit lock, receive an operation-scoped token plus lock context, and later upload or release through that narrower edit-session authority.\n\nCompanion sends the URI token to the backend token endpoint in a JSON request body. Do not reintroduce query-string token exchange compatibility; deep-link tokens are sensitive and should not be exposed in URLs, logs, proxy access logs, or browser history.\n\nThe deep-link token is not a general browser-to-companion credential. It is a short-lived bootstrap value for one native-editing handoff.\n\nAfter lock acquisition, the browser no longer carries the authority for that edit. The companion holds an operation-scoped backend token plus `operation_id`, `lock_id`, and `lock_capability` for the lifetime of the edit session.\n\n### Localhost API Path\n\nThis path is used for local-drive access and related browser-to-desktop features.\n\n1. the browser probes `http://localhost:21549/api/health`\n1. browser and companion perform an explicit pairing flow\n1. the browser uses authenticated localhost requests for local-drive operations\n1. the companion sends directory-change notifications over a paired WebSocket channel\n\n## Why Pairing Exists\n\nLocalhost alone is not a trust boundary.\n\nThe companion therefore requires explicit pairing and per-request authentication so that:\n\n- remote network clients cannot reach it\n- arbitrary websites cannot use it just because they run in the browser\n- local native processes do not gain the browser's paired privileges automatically\n\n## Pairing Model\n\nThe pairing flow is deliberately shaped like numeric-comparison pairing.\n\n- the browser and companion exchange nonces\n- both sides independently derive the same short pairing code\n- the user confirms the match in both places\n- the companion returns a shared secret only after dual confirmation succeeds\n\nThat dual confirmation step is what turns \u201csomething can reach localhost\u201d into \u201cthe user intentionally paired this browser origin with this desktop app.\u201d\n\n## Request Authentication after Pairing\n\nAfter pairing, companion-bound requests use HMAC-based authentication rather than the server's bearer-token flow.\n\n- localhost API requests carry an HMAC derived from the shared secret and a timestamp\n- the companion rejects requests outside the allowed clock window\n- pairing is tracked per browser origin, not as one global switch\n- the shared secret is stored in OS-protected credential storage on the companion side\n\n## Trust Boundaries Contributors Must Preserve\n\n- keep the companion bound to `127.0.0.1`\n- do not relax CORS rules casually\n- do not replace explicit pairing with silent trust-on-first-use behavior\n- keep browser-to-companion auth distinct from backend bearer-token auth\n- preserve the server-side edit-lock lifecycle for SMB-backed editing instead of letting the companion bypass it\n- keep reverse-proxy cookies distinct from Sambee bearer tokens and companion localhost pairing secrets\n- redact deep-link tokens, bootstrap tokens, operation tokens, cookies, authorization data, and other sensitive query values before logging\n\nReverse-proxy authentication is a separate trust path from localhost pairing. The companion may use cookies captured in its own backend-origin authentication webview for Rust-side backend requests, but it must not import cookies from the user's normal browser session.\n\n## What Changes Are High Risk\n\n- anything that alters token exchange or deep-link parsing\n- anything that changes pairing confirmation rules\n- anything that weakens HMAC validation, timestamp checking, or origin scoping\n- anything that blurs the distinction between local-drive workflows and SMB-backed edit workflows\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/auth.rs` | localhost API authentication |\n| `companion/src-tauri/src/server/pairing.rs` | pairing flow and secret lifecycle |\n| `companion/src-tauri/src/uri/` and `token/` | deep-link parsing and token exchange support |\n| `frontend/src/services/companion.ts` | browser-side pairing and companion communication |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion appropriately |\n\n## Validation Expectations\n\nWhen this trust model changes, do not validate only the companion.\n\nRun at least:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\n```\n\nIf the change alters SMB edit flows, add the relevant backend checks too.\n", "0.8": "+++\ntitle = \"Browser-to-Companion Trust Model\"\n+++\n\nThe browser-to-companion boundary is powerful because it crosses from the browser app into desktop-local capability. That makes it one of the most security-sensitive parts of Sambee.\n\n## Two Distinct Trust Paths\n\nSambee uses two browser-to-companion interaction models.\n\n### Deep-Link Editing Path\n\nThis path is used when the browser asks the companion to open an SMB-backed file in a native desktop app.\n\n1. The browser asks the backend for a short-lived URI token.\n1. The browser launches a `sambee://` deep link.\n1. Companion exchanges the one-time token for a session token.\n1. Companion downloads the file, acquires the edit lock, and later uploads the result.\n\nCompanion sends the URI token to the backend token endpoint in a JSON request body. Do not reintroduce query-string token exchange compatibility; deep-link tokens are sensitive and should not be exposed in URLs, logs, proxy access logs, or browser history.\n\nThe deep-link token is not a general browser-to-companion credential. It is a short-lived bootstrap value for one native-editing handoff.\n\n### Localhost API Path\n\nThis path is used for local-drive access and related browser-to-desktop features.\n\n1. the browser probes `http://localhost:21549/api/health`\n1. browser and companion perform an explicit pairing flow for the current browser origin\n1. the browser uses authenticated localhost requests for local-drive operations\n1. the companion sends directory-change notifications over a paired WebSocket channel\n\n## Why Pairing Exists\n\nLocalhost alone is not a trust boundary.\n\nThe companion therefore requires explicit pairing and per-request authentication so that:\n\n- remote network clients cannot reach it\n- arbitrary websites cannot use it just because they run in the browser\n- local native processes do not gain the browser's paired privileges automatically\n\n## Pairing Model\n\nThe pairing flow is deliberately shaped like numeric-comparison pairing, but the important trust decision is not just \u201cdo the codes match?\u201d It is \u201cdoes the user approve this exact browser origin on this computer?\u201d\n\n- the browser and companion exchange nonces\n- both sides independently derive the same short pairing code\n- the companion displays the exact requesting browser origin in a native approval window\n- the user confirms the match in both places\n- the companion returns a shared secret only after dual confirmation succeeds\n\nThat dual confirmation step is what turns \u201csomething can reach localhost\u201d into \u201cthe user intentionally paired this browser origin with this desktop app.\u201d\n\n### Production and Development Origin Rules\n\nIn production, Companion does not rely on a preconfigured list of Sambee frontend URLs.\n\n- any valid browser origin can request pairing\n- Companion normalizes that exact origin and shows it to the user for local approval\n- once approved, that exact origin becomes the paired browser origin for future authenticated localhost requests\n\nFor development, typical loopback browser origins such as `localhost`, `127.0.0.1`, and `::1` remain usable without manual per-port configuration.\n\nThis keeps development practical without weakening the production trust boundary into hostname heuristics or silent trust-on-first-use.\n\n## Request Authentication after Pairing\n\nAfter pairing, companion-bound requests use HMAC-based authentication rather than the server's bearer-token flow.\n\n- localhost API requests carry an HMAC derived from the shared secret and a timestamp\n- the companion rejects requests outside the allowed clock window\n- pairing is tracked per browser origin, not as one global switch\n- the shared secret is stored in OS-protected credential storage on the companion side\n\nBrowser-facing pairing state should also stay origin-scoped and typed.\n\nImportant browser-visible states include:\n\n- unavailable\n- unpaired\n- pending local approval\n- paired\n- repair required because the browser-side secret is missing or unusable\n\nThat state model matters because local trust problems should surface as explicit recovery states rather than as a misleading generic \u201cnot paired\u201d result.\n\n## Pairing Management and Cancellation\n\nPairing management is intentionally narrower than routine local-drive access.\n\n- the browser should only learn the status of its own current origin\n- browser-visible paired-origin enumeration is not part of the browser contract\n- browser-managed unpairing is limited to the current origin\n- closing either pairing UI path should cancel the pending request explicitly\n\nThat last point is part of the trust model, not just a UX detail. A dismissed pairing window should not leave behind a stale approval request that can still be completed later by accident.\n\n## Trust Boundaries Contributors Must Preserve\n\n- keep the companion bound to `127.0.0.1`\n- do not relax CORS rules casually\n- do not replace exact-origin approval with hostname heuristics or silent trust-on-first-use behavior\n- keep browser-to-companion auth distinct from backend bearer-token auth\n- preserve the server-side edit-lock lifecycle for SMB-backed editing instead of letting the companion bypass it\n- keep reverse-proxy cookies distinct from Sambee bearer tokens and companion localhost pairing secrets\n- redact deep-link tokens, sessions, cookies, authorization data, and other sensitive query values before logging\n\nReverse-proxy authentication is a separate trust path from localhost pairing. The companion may use cookies captured in its own backend-origin authentication webview for Rust-side backend requests, but it must not import cookies from the user's normal browser session.\n\n## What Changes Are High Risk\n\n- anything that alters token exchange or deep-link parsing\n- anything that changes pairing confirmation rules\n- anything that weakens HMAC validation, timestamp checking, or origin scoping\n- anything that blurs the distinction between local-drive workflows and SMB-backed edit workflows\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/auth.rs` | localhost API authentication |\n| `companion/src-tauri/src/server/pairing.rs` | pairing flow and secret lifecycle |\n| `companion/src-tauri/src/uri/` and `token/` | deep-link parsing and token exchange support |\n| `frontend/src/services/companion.ts` | browser-side pairing and companion communication |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion appropriately |\n\n## Validation Expectations\n\nWhen this trust model changes, do not validate only the companion.\n\nRun at least:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\n```\n\nIf the change alters SMB edit flows, add the relevant backend checks too.\n", "0.9": "+++\ntitle = \"Browser-to-Companion Trust Model\"\n+++\n\nThe browser-to-companion boundary is powerful because it crosses from the browser app into desktop-local capability. That makes it one of the most security-sensitive parts of Sambee.\n\n## Two Distinct Trust Paths\n\nSambee uses two browser-to-companion interaction models.\n\n### Deep-Link Editing Path\n\nThis path is used when the browser asks the companion to open an SMB-backed file in a native desktop app.\n\n1. The browser asks the backend for a short-lived URI token.\n1. The browser launches a `sambee://` deep link.\n1. Companion exchanges the one-time token for a session token.\n1. Companion downloads the file, acquires the edit lock, and later uploads the result.\n\nCompanion sends the URI token to the backend token endpoint in a JSON request body. Do not reintroduce query-string token exchange compatibility; deep-link tokens are sensitive and should not be exposed in URLs, logs, proxy access logs, or browser history.\n\nThe deep-link token is not a general browser-to-companion credential. It is a short-lived bootstrap value for one native-editing handoff.\n\n### Localhost API Path\n\nThis path is used for local-drive access and related browser-to-desktop features.\n\n1. the browser probes `http://localhost:21549/api/health`\n1. browser and companion perform an explicit pairing flow for the current browser origin\n1. the browser uses authenticated localhost requests for local-drive operations\n1. the companion sends directory-change notifications over a paired WebSocket channel\n\n## Why Pairing Exists\n\nLocalhost alone is not a trust boundary.\n\nThe companion therefore requires explicit pairing and per-request authentication so that:\n\n- remote network clients cannot reach it\n- arbitrary websites cannot use it just because they run in the browser\n- local native processes do not gain the browser's paired privileges automatically\n\n## Pairing Model\n\nThe pairing flow is deliberately shaped like numeric-comparison pairing, but the important trust decision is not just \u201cdo the codes match?\u201d It is \u201cdoes the user approve this exact browser origin on this computer?\u201d\n\n- the browser and companion exchange nonces\n- both sides independently derive the same short pairing code\n- the companion displays the exact requesting browser origin in a native approval window\n- the user confirms the match in both places\n- the companion returns a shared secret only after dual confirmation succeeds\n\nThat dual confirmation step is what turns \u201csomething can reach localhost\u201d into \u201cthe user intentionally paired this browser origin with this desktop app.\u201d\n\n### Production and Development Origin Rules\n\nIn production, Companion does not rely on a preconfigured list of Sambee frontend URLs.\n\n- any valid browser origin can request pairing\n- Companion normalizes that exact origin and shows it to the user for local approval\n- once approved, that exact origin becomes the paired browser origin for future authenticated localhost requests\n\nFor development, typical loopback browser origins such as `localhost`, `127.0.0.1`, and `::1` remain usable without manual per-port configuration.\n\nThis keeps development practical without weakening the production trust boundary into hostname heuristics or silent trust-on-first-use.\n\n## Request Authentication after Pairing\n\nAfter pairing, companion-bound requests use HMAC-based authentication rather than the server's bearer-token flow.\n\n- localhost API requests carry an HMAC derived from the shared secret and a timestamp\n- the companion rejects requests outside the allowed clock window\n- pairing is tracked per browser origin, not as one global switch\n- the shared secret is stored in OS-protected credential storage on the companion side\n\nBrowser-facing pairing state should also stay origin-scoped and typed.\n\nImportant browser-visible states include:\n\n- unavailable\n- unpaired\n- pending local approval\n- paired\n- repair required because the browser-side secret is missing or unusable\n\nThat state model matters because local trust problems should surface as explicit recovery states rather than as a misleading generic \u201cnot paired\u201d result.\n\n## Pairing Management and Cancellation\n\nPairing management is intentionally narrower than routine local-drive access.\n\n- the browser should only learn the status of its own current origin\n- browser-visible paired-origin enumeration is not part of the browser contract\n- browser-managed unpairing is limited to the current origin\n- closing either pairing UI path should cancel the pending request explicitly\n\nThat last point is part of the trust model, not just a UX detail. A dismissed pairing window should not leave behind a stale approval request that can still be completed later by accident.\n\n## Trust Boundaries Contributors Must Preserve\n\n- keep the companion bound to `127.0.0.1`\n- do not relax CORS rules casually\n- do not replace exact-origin approval with hostname heuristics or silent trust-on-first-use behavior\n- keep browser-to-companion auth distinct from backend bearer-token auth\n- preserve the server-side edit-lock lifecycle for SMB-backed editing instead of letting the companion bypass it\n- keep reverse-proxy cookies distinct from Sambee bearer tokens and companion localhost pairing secrets\n- redact deep-link tokens, sessions, cookies, authorization data, and other sensitive query values before logging\n\nReverse-proxy authentication is a separate trust path from localhost pairing. The companion may use cookies captured in its own backend-origin authentication webview for Rust-side backend requests, but it must not import cookies from the user's normal browser session.\n\n## What Changes Are High Risk\n\n- anything that alters token exchange or deep-link parsing\n- anything that changes pairing confirmation rules\n- anything that weakens HMAC validation, timestamp checking, or origin scoping\n- anything that blurs the distinction between local-drive workflows and SMB-backed edit workflows\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/auth.rs` | localhost API authentication |\n| `companion/src-tauri/src/server/pairing.rs` | pairing flow and secret lifecycle |\n| `companion/src-tauri/src/uri/` and `token/` | deep-link parsing and token exchange support |\n| `frontend/src/services/companion.ts` | browser-side pairing and companion communication |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion appropriately |\n\n## Validation Expectations\n\nWhen this trust model changes, do not validate only the companion.\n\nRun at least:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\n```\n\nIf the change alters SMB edit flows, add the relevant backend checks too.\n", "1.0": "+++\ntitle = \"Browser-to-Companion Trust Model\"\n+++\n\nThe browser-to-companion boundary is powerful because it crosses from the browser app into desktop-local capability. That makes it one of the most security-sensitive parts of Sambee.\n\n## Two Distinct Trust Paths\n\nSambee uses two browser-to-companion interaction models.\n\n### Deep-Link Editing Path\n\nThis path is used when the browser asks the companion to open an SMB-backed file in a native desktop app.\n\n1. The browser asks the backend for a short-lived URI token.\n1. The browser launches a `sambee://` deep link.\n1. Companion exchanges the one-time token for a session token.\n1. Companion downloads the file, acquires the edit lock, and later uploads the result.\n\nCompanion sends the URI token to the backend token endpoint in a JSON request body. Do not reintroduce query-string token exchange compatibility; deep-link tokens are sensitive and should not be exposed in URLs, logs, proxy access logs, or browser history.\n\nThe deep-link token is not a general browser-to-companion credential. It is a short-lived bootstrap value for one native-editing handoff.\n\n### Localhost API Path\n\nThis path is used for local-drive access and related browser-to-desktop features.\n\n1. the browser probes `http://localhost:21549/api/health`\n1. browser and companion perform an explicit pairing flow for the current browser origin\n1. the browser uses authenticated localhost requests for local-drive operations\n1. the companion sends directory-change notifications over a paired WebSocket channel\n\n## Why Pairing Exists\n\nLocalhost alone is not a trust boundary.\n\nThe companion therefore requires explicit pairing and per-request authentication so that:\n\n- remote network clients cannot reach it\n- arbitrary websites cannot use it just because they run in the browser\n- local native processes do not gain the browser's paired privileges automatically\n\n## Pairing Model\n\nThe pairing flow is deliberately shaped like numeric-comparison pairing, but the important trust decision is not just \u201cdo the codes match?\u201d It is \u201cdoes the user approve this exact browser origin on this computer?\u201d\n\n- the browser and companion exchange nonces\n- both sides independently derive the same short pairing code\n- the companion displays the exact requesting browser origin in a native approval window\n- the user confirms the match in both places\n- the companion returns a shared secret only after dual confirmation succeeds\n\nThat dual confirmation step is what turns \u201csomething can reach localhost\u201d into \u201cthe user intentionally paired this browser origin with this desktop app.\u201d\n\n### Production and Development Origin Rules\n\nIn production, Companion does not rely on a preconfigured list of Sambee frontend URLs.\n\n- any valid browser origin can request pairing\n- Companion normalizes that exact origin and shows it to the user for local approval\n- once approved, that exact origin becomes the paired browser origin for future authenticated localhost requests\n\nFor development, typical loopback browser origins such as `localhost`, `127.0.0.1`, and `::1` remain usable without manual per-port configuration.\n\nThis keeps development practical without weakening the production trust boundary into hostname heuristics or silent trust-on-first-use.\n\n## Request Authentication after Pairing\n\nAfter pairing, companion-bound requests use HMAC-based authentication rather than the server's bearer-token flow.\n\n- localhost API requests carry an HMAC derived from the shared secret and a timestamp\n- the companion rejects requests outside the allowed clock window\n- pairing is tracked per browser origin, not as one global switch\n- the shared secret is stored in OS-protected credential storage on the companion side\n\nBrowser-facing pairing state should also stay origin-scoped and typed.\n\nImportant browser-visible states include:\n\n- unavailable\n- unpaired\n- pending local approval\n- paired\n- repair required because the browser-side secret is missing or unusable\n\nThat state model matters because local trust problems should surface as explicit recovery states rather than as a misleading generic \u201cnot paired\u201d result.\n\n## Pairing Management and Cancellation\n\nPairing management is intentionally narrower than routine local-drive access.\n\n- the browser should only learn the status of its own current origin\n- browser-visible paired-origin enumeration is not part of the browser contract\n- browser-managed unpairing is limited to the current origin\n- closing either pairing UI path should cancel the pending request explicitly\n\nThat last point is part of the trust model, not just a UX detail. A dismissed pairing window should not leave behind a stale approval request that can still be completed later by accident.\n\n## Trust Boundaries Contributors Must Preserve\n\n- keep the companion bound to `127.0.0.1`\n- do not relax CORS rules casually\n- do not replace exact-origin approval with hostname heuristics or silent trust-on-first-use behavior\n- keep browser-to-companion auth distinct from backend bearer-token auth\n- preserve the server-side edit-lock lifecycle for SMB-backed editing instead of letting the companion bypass it\n- keep reverse-proxy cookies distinct from Sambee bearer tokens and companion localhost pairing secrets\n- redact deep-link tokens, sessions, cookies, authorization data, and other sensitive query values before logging\n\nReverse-proxy authentication is a separate trust path from localhost pairing. The companion may use cookies captured in its own backend-origin authentication webview for Rust-side backend requests, but it must not import cookies from the user's normal browser session.\n\n## What Changes Are High Risk\n\n- anything that alters token exchange or deep-link parsing\n- anything that changes pairing confirmation rules\n- anything that weakens HMAC validation, timestamp checking, or origin scoping\n- anything that blurs the distinction between local-drive workflows and SMB-backed edit workflows\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/auth.rs` | localhost API authentication |\n| `companion/src-tauri/src/server/pairing.rs` | pairing flow and secret lifecycle |\n| `companion/src-tauri/src/uri/` and `token/` | deep-link parsing and token exchange support |\n| `frontend/src/services/companion.ts` | browser-side pairing and companion communication |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion appropriately |\n\n## Validation Expectations\n\nWhen this trust model changes, do not validate only the companion.\n\nRun at least:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\n```\n\nIf the change alters SMB edit flows, add the relevant backend checks too.\n", "2.0": "+++\ntitle = \"Browser-to-Companion Trust Model\"\n+++\n\nThe browser-to-companion boundary is powerful because it crosses from the browser app into desktop-local capability. That makes it one of the most security-sensitive parts of Sambee.\n\n## Two Distinct Trust Paths\n\nSambee uses two browser-to-companion interaction models.\n\n### Deep-Link Editing Path\n\nThis path is used when the browser asks the companion to open an SMB-backed file in a native desktop app.\n\n1. The browser asks the backend for a short-lived URI token.\n1. The browser launches a `sambee://` deep link.\n1. Companion exchanges the one-time token for a session token.\n1. Companion downloads the file, acquires the edit lock, and later uploads the result.\n\nCompanion sends the URI token to the backend token endpoint in a JSON request body. Do not reintroduce query-string token exchange compatibility; deep-link tokens are sensitive and should not be exposed in URLs, logs, proxy access logs, or browser history.\n\nThe deep-link token is not a general browser-to-companion credential. It is a short-lived bootstrap value for one native-editing handoff.\n\n### Localhost API Path\n\nThis path is used for local-drive access and related browser-to-desktop features.\n\n1. the browser probes `http://localhost:21549/api/health`\n1. browser and companion perform an explicit pairing flow for the current browser origin\n1. the browser uses authenticated localhost requests for local-drive operations\n1. the companion sends directory-change notifications over a paired WebSocket channel\n\n## Why Pairing Exists\n\nLocalhost alone is not a trust boundary.\n\nThe companion therefore requires explicit pairing and per-request authentication so that:\n\n- remote network clients cannot reach it\n- arbitrary websites cannot use it just because they run in the browser\n- local native processes do not gain the browser's paired privileges automatically\n\n## Pairing Model\n\nThe pairing flow is deliberately shaped like numeric-comparison pairing, but the important trust decision is not just \u201cdo the codes match?\u201d It is \u201cdoes the user approve this exact browser origin on this computer?\u201d\n\n- the browser and companion exchange nonces\n- both sides independently derive the same short pairing code\n- the companion displays the exact requesting browser origin in a native approval window\n- the user confirms the match in both places\n- the companion returns a shared secret only after dual confirmation succeeds\n\nThat dual confirmation step is what turns \u201csomething can reach localhost\u201d into \u201cthe user intentionally paired this browser origin with this desktop app.\u201d\n\n### Production and Development Origin Rules\n\nIn production, Companion does not rely on a preconfigured list of Sambee frontend URLs.\n\n- any valid browser origin can request pairing\n- Companion normalizes that exact origin and shows it to the user for local approval\n- once approved, that exact origin becomes the paired browser origin for future authenticated localhost requests\n\nFor development, typical loopback browser origins such as `localhost`, `127.0.0.1`, and `::1` remain usable without manual per-port configuration.\n\nThis keeps development practical without weakening the production trust boundary into hostname heuristics or silent trust-on-first-use.\n\n## Request Authentication after Pairing\n\nAfter pairing, companion-bound requests use HMAC-based authentication rather than the server's bearer-token flow.\n\n- localhost API requests carry an HMAC derived from the shared secret and a timestamp\n- the companion rejects requests outside the allowed clock window\n- pairing is tracked per browser origin, not as one global switch\n- the shared secret is stored in OS-protected credential storage on the companion side\n\nBrowser-facing pairing state should also stay origin-scoped and typed.\n\nImportant browser-visible states include:\n\n- unavailable\n- unpaired\n- pending local approval\n- paired\n- repair required because the browser-side secret is missing or unusable\n\nThat state model matters because local trust problems should surface as explicit recovery states rather than as a misleading generic \u201cnot paired\u201d result.\n\n## Pairing Management and Cancellation\n\nPairing management is intentionally narrower than routine local-drive access.\n\n- the browser should only learn the status of its own current origin\n- browser-visible paired-origin enumeration is not part of the browser contract\n- browser-managed unpairing is limited to the current origin\n- closing either pairing UI path should cancel the pending request explicitly\n\nThat last point is part of the trust model, not just a UX detail. A dismissed pairing window should not leave behind a stale approval request that can still be completed later by accident.\n\n## Trust Boundaries Contributors Must Preserve\n\n- keep the companion bound to `127.0.0.1`\n- do not relax CORS rules casually\n- do not replace exact-origin approval with hostname heuristics or silent trust-on-first-use behavior\n- keep browser-to-companion auth distinct from backend bearer-token auth\n- preserve the server-side edit-lock lifecycle for SMB-backed editing instead of letting the companion bypass it\n- keep reverse-proxy cookies distinct from Sambee bearer tokens and companion localhost pairing secrets\n- redact deep-link tokens, sessions, cookies, authorization data, and other sensitive query values before logging\n\nReverse-proxy authentication is a separate trust path from localhost pairing. The companion may use cookies captured in its own backend-origin authentication webview for Rust-side backend requests, but it must not import cookies from the user's normal browser session.\n\n## What Changes Are High Risk\n\n- anything that alters token exchange or deep-link parsing\n- anything that changes pairing confirmation rules\n- anything that weakens HMAC validation, timestamp checking, or origin scoping\n- anything that blurs the distinction between local-drive workflows and SMB-backed edit workflows\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/auth.rs` | localhost API authentication |\n| `companion/src-tauri/src/server/pairing.rs` | pairing flow and secret lifecycle |\n| `companion/src-tauri/src/uri/` and `token/` | deep-link parsing and token exchange support |\n| `frontend/src/services/companion.ts` | browser-side pairing and companion communication |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion appropriately |\n\n## Validation Expectations\n\nWhen this trust model changes, do not validate only the companion.\n\nRun at least:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\n```\n\nIf the change alters SMB edit flows, add the relevant backend checks too.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Browser-to-Companion Trust Model\"\n+++\n\nThe browser-to-companion boundary is powerful because it crosses from the browser app into desktop-local capability. That makes it one of the most security-sensitive parts of Sambee.\n\n## Two Distinct Trust Paths\n\nSambee uses two browser-to-companion interaction models.\n\n### Deep-Link Editing Path\n\nThis path is used when the browser asks the companion to open an SMB-backed file in a native desktop app.\n\n1. The browser asks the backend for a short-lived URI token.\n1. The browser launches a `sambee://` deep link.\n1. Companion exchanges the one-time token for a companion bootstrap token.\n1. Companion uses that bootstrap token to look up file info, acquire the edit lock, receive an operation-scoped token plus lock context, and later upload or release through that narrower edit-session authority.\n\nCompanion sends the URI token to the backend token endpoint in a JSON request body. Do not reintroduce query-string token exchange compatibility; deep-link tokens are sensitive and should not be exposed in URLs, logs, proxy access logs, or browser history.\n\nThe deep-link token is not a general browser-to-companion credential. It is a short-lived bootstrap value for one native-editing handoff.\n\nAfter lock acquisition, the browser no longer carries the authority for that edit. The companion holds an operation-scoped backend token plus `operation_id`, `lock_id`, and `lock_capability` for the lifetime of the edit session.\n\n### Localhost API Path\n\nThis path is used for local-drive access and related browser-to-desktop features.\n\n1. the browser probes `http://localhost:21549/api/health`\n1. browser and companion perform an explicit pairing flow\n1. the browser uses authenticated localhost requests for local-drive operations\n1. the companion sends directory-change notifications over a paired WebSocket channel\n\n## Why Pairing Exists\n\nLocalhost alone is not a trust boundary.\n\nThe companion therefore requires explicit pairing and per-request authentication so that:\n\n- remote network clients cannot reach it\n- arbitrary websites cannot use it just because they run in the browser\n- local native processes do not gain the browser's paired privileges automatically\n\n## Pairing Model\n\nThe pairing flow is deliberately shaped like numeric-comparison pairing.\n\n- the browser and companion exchange nonces\n- both sides independently derive the same short pairing code\n- the user confirms the match in both places\n- the companion returns a shared secret only after dual confirmation succeeds\n\nThat dual confirmation step is what turns \u201csomething can reach localhost\u201d into \u201cthe user intentionally paired this browser origin with this desktop app.\u201d\n\n## Request Authentication after Pairing\n\nAfter pairing, companion-bound requests use HMAC-based authentication rather than the server's bearer-token flow.\n\n- localhost API requests carry an HMAC derived from the shared secret and a timestamp\n- the companion rejects requests outside the allowed clock window\n- pairing is tracked per browser origin, not as one global switch\n- the shared secret is stored in OS-protected credential storage on the companion side\n\n## Trust Boundaries Contributors Must Preserve\n\n- keep the companion bound to `127.0.0.1`\n- do not relax CORS rules casually\n- do not replace explicit pairing with silent trust-on-first-use behavior\n- keep browser-to-companion auth distinct from backend bearer-token auth\n- preserve the server-side edit-lock lifecycle for SMB-backed editing instead of letting the companion bypass it\n- keep reverse-proxy cookies distinct from Sambee bearer tokens and companion localhost pairing secrets\n- redact deep-link tokens, bootstrap tokens, operation tokens, cookies, authorization data, and other sensitive query values before logging\n\nReverse-proxy authentication is a separate trust path from localhost pairing. The companion may use cookies captured in its own backend-origin authentication webview for Rust-side backend requests, but it must not import cookies from the user's normal browser session.\n\n## What Changes Are High Risk\n\n- anything that alters token exchange or deep-link parsing\n- anything that changes pairing confirmation rules\n- anything that weakens HMAC validation, timestamp checking, or origin scoping\n- anything that blurs the distinction between local-drive workflows and SMB-backed edit workflows\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/auth.rs` | localhost API authentication |\n| `companion/src-tauri/src/server/pairing.rs` | pairing flow and secret lifecycle |\n| `companion/src-tauri/src/uri/` and `token/` | deep-link parsing and token exchange support |\n| `frontend/src/services/companion.ts` | browser-side pairing and companion communication |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion appropriately |\n\n## Validation Expectations\n\nWhen this trust model changes, do not validate only the companion.\n\nRun at least:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\n```\n\nIf the change alters SMB edit flows, add the relevant backend checks too.\n", "0.8": "+++\ntitle = \"Browser-to-Companion Trust Model\"\n+++\n\nThe browser-to-companion boundary is powerful because it crosses from the browser app into desktop-local capability. That makes it one of the most security-sensitive parts of Sambee.\n\n## Two Distinct Trust Paths\n\nSambee uses two browser-to-companion interaction models.\n\n### Deep-Link Editing Path\n\nThis path is used when the browser asks the companion to open an SMB-backed file in a native desktop app.\n\n1. The browser asks the backend for a short-lived URI token.\n1. The browser launches a `sambee://` deep link.\n1. Companion exchanges the one-time token for a session token.\n1. Companion downloads the file, acquires the edit lock, and later uploads the result.\n\nCompanion sends the URI token to the backend token endpoint in a JSON request body. Do not reintroduce query-string token exchange compatibility; deep-link tokens are sensitive and should not be exposed in URLs, logs, proxy access logs, or browser history.\n\nThe deep-link token is not a general browser-to-companion credential. It is a short-lived bootstrap value for one native-editing handoff.\n\n### Localhost API Path\n\nThis path is used for local-drive access and related browser-to-desktop features.\n\n1. the browser probes `http://localhost:21549/api/health`\n1. browser and companion perform an explicit pairing flow for the current browser origin\n1. the browser uses authenticated localhost requests for local-drive operations\n1. the companion sends directory-change notifications over a paired WebSocket channel\n\n## Why Pairing Exists\n\nLocalhost alone is not a trust boundary.\n\nThe companion therefore requires explicit pairing and per-request authentication so that:\n\n- remote network clients cannot reach it\n- arbitrary websites cannot use it just because they run in the browser\n- local native processes do not gain the browser's paired privileges automatically\n\n## Pairing Model\n\nThe pairing flow is deliberately shaped like numeric-comparison pairing, but the important trust decision is not just \u201cdo the codes match?\u201d It is \u201cdoes the user approve this exact browser origin on this computer?\u201d\n\n- the browser and companion exchange nonces\n- both sides independently derive the same short pairing code\n- the companion displays the exact requesting browser origin in a native approval window\n- the user confirms the match in both places\n- the companion returns a shared secret only after dual confirmation succeeds\n\nThat dual confirmation step is what turns \u201csomething can reach localhost\u201d into \u201cthe user intentionally paired this browser origin with this desktop app.\u201d\n\n### Production and Development Origin Rules\n\nIn production, Companion does not rely on a preconfigured list of Sambee frontend URLs.\n\n- any valid browser origin can request pairing\n- Companion normalizes that exact origin and shows it to the user for local approval\n- once approved, that exact origin becomes the paired browser origin for future authenticated localhost requests\n\nFor development, typical loopback browser origins such as `localhost`, `127.0.0.1`, and `::1` remain usable without manual per-port configuration.\n\nThis keeps development practical without weakening the production trust boundary into hostname heuristics or silent trust-on-first-use.\n\n## Request Authentication after Pairing\n\nAfter pairing, companion-bound requests use HMAC-based authentication rather than the server's bearer-token flow.\n\n- localhost API requests carry an HMAC derived from the shared secret and a timestamp\n- the companion rejects requests outside the allowed clock window\n- pairing is tracked per browser origin, not as one global switch\n- the shared secret is stored in OS-protected credential storage on the companion side\n\nBrowser-facing pairing state should also stay origin-scoped and typed.\n\nImportant browser-visible states include:\n\n- unavailable\n- unpaired\n- pending local approval\n- paired\n- repair required because the browser-side secret is missing or unusable\n\nThat state model matters because local trust problems should surface as explicit recovery states rather than as a misleading generic \u201cnot paired\u201d result.\n\n## Pairing Management and Cancellation\n\nPairing management is intentionally narrower than routine local-drive access.\n\n- the browser should only learn the status of its own current origin\n- browser-visible paired-origin enumeration is not part of the browser contract\n- browser-managed unpairing is limited to the current origin\n- closing either pairing UI path should cancel the pending request explicitly\n\nThat last point is part of the trust model, not just a UX detail. A dismissed pairing window should not leave behind a stale approval request that can still be completed later by accident.\n\n## Trust Boundaries Contributors Must Preserve\n\n- keep the companion bound to `127.0.0.1`\n- do not relax CORS rules casually\n- do not replace exact-origin approval with hostname heuristics or silent trust-on-first-use behavior\n- keep browser-to-companion auth distinct from backend bearer-token auth\n- preserve the server-side edit-lock lifecycle for SMB-backed editing instead of letting the companion bypass it\n- keep reverse-proxy cookies distinct from Sambee bearer tokens and companion localhost pairing secrets\n- redact deep-link tokens, sessions, cookies, authorization data, and other sensitive query values before logging\n\nReverse-proxy authentication is a separate trust path from localhost pairing. The companion may use cookies captured in its own backend-origin authentication webview for Rust-side backend requests, but it must not import cookies from the user's normal browser session.\n\n## What Changes Are High Risk\n\n- anything that alters token exchange or deep-link parsing\n- anything that changes pairing confirmation rules\n- anything that weakens HMAC validation, timestamp checking, or origin scoping\n- anything that blurs the distinction between local-drive workflows and SMB-backed edit workflows\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/auth.rs` | localhost API authentication |\n| `companion/src-tauri/src/server/pairing.rs` | pairing flow and secret lifecycle |\n| `companion/src-tauri/src/uri/` and `token/` | deep-link parsing and token exchange support |\n| `frontend/src/services/companion.ts` | browser-side pairing and companion communication |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion appropriately |\n\n## Validation Expectations\n\nWhen this trust model changes, do not validate only the companion.\n\nRun at least:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\n```\n\nIf the change alters SMB edit flows, add the relevant backend checks too.\n", "0.9": "+++\ntitle = \"Browser-to-Companion Trust Model\"\n+++\n\nThe browser-to-companion boundary is powerful because it crosses from the browser app into desktop-local capability. That makes it one of the most security-sensitive parts of Sambee.\n\n## Two Distinct Trust Paths\n\nSambee uses two browser-to-companion interaction models.\n\n### Deep-Link Editing Path\n\nThis path is used when the browser asks the companion to open an SMB-backed file in a native desktop app.\n\n1. The browser asks the backend for a short-lived URI token.\n1. The browser launches a `sambee://` deep link.\n1. Companion exchanges the one-time token for a session token.\n1. Companion downloads the file, acquires the edit lock, and later uploads the result.\n\nCompanion sends the URI token to the backend token endpoint in a JSON request body. Do not reintroduce query-string token exchange compatibility; deep-link tokens are sensitive and should not be exposed in URLs, logs, proxy access logs, or browser history.\n\nThe deep-link token is not a general browser-to-companion credential. It is a short-lived bootstrap value for one native-editing handoff.\n\n### Localhost API Path\n\nThis path is used for local-drive access and related browser-to-desktop features.\n\n1. the browser probes `http://localhost:21549/api/health`\n1. browser and companion perform an explicit pairing flow for the current browser origin\n1. the browser uses authenticated localhost requests for local-drive operations\n1. the companion sends directory-change notifications over a paired WebSocket channel\n\n## Why Pairing Exists\n\nLocalhost alone is not a trust boundary.\n\nThe companion therefore requires explicit pairing and per-request authentication so that:\n\n- remote network clients cannot reach it\n- arbitrary websites cannot use it just because they run in the browser\n- local native processes do not gain the browser's paired privileges automatically\n\n## Pairing Model\n\nThe pairing flow is deliberately shaped like numeric-comparison pairing, but the important trust decision is not just \u201cdo the codes match?\u201d It is \u201cdoes the user approve this exact browser origin on this computer?\u201d\n\n- the browser and companion exchange nonces\n- both sides independently derive the same short pairing code\n- the companion displays the exact requesting browser origin in a native approval window\n- the user confirms the match in both places\n- the companion returns a shared secret only after dual confirmation succeeds\n\nThat dual confirmation step is what turns \u201csomething can reach localhost\u201d into \u201cthe user intentionally paired this browser origin with this desktop app.\u201d\n\n### Production and Development Origin Rules\n\nIn production, Companion does not rely on a preconfigured list of Sambee frontend URLs.\n\n- any valid browser origin can request pairing\n- Companion normalizes that exact origin and shows it to the user for local approval\n- once approved, that exact origin becomes the paired browser origin for future authenticated localhost requests\n\nFor development, typical loopback browser origins such as `localhost`, `127.0.0.1`, and `::1` remain usable without manual per-port configuration.\n\nThis keeps development practical without weakening the production trust boundary into hostname heuristics or silent trust-on-first-use.\n\n## Request Authentication after Pairing\n\nAfter pairing, companion-bound requests use HMAC-based authentication rather than the server's bearer-token flow.\n\n- localhost API requests carry an HMAC derived from the shared secret and a timestamp\n- the companion rejects requests outside the allowed clock window\n- pairing is tracked per browser origin, not as one global switch\n- the shared secret is stored in OS-protected credential storage on the companion side\n\nBrowser-facing pairing state should also stay origin-scoped and typed.\n\nImportant browser-visible states include:\n\n- unavailable\n- unpaired\n- pending local approval\n- paired\n- repair required because the browser-side secret is missing or unusable\n\nThat state model matters because local trust problems should surface as explicit recovery states rather than as a misleading generic \u201cnot paired\u201d result.\n\n## Pairing Management and Cancellation\n\nPairing management is intentionally narrower than routine local-drive access.\n\n- the browser should only learn the status of its own current origin\n- browser-visible paired-origin enumeration is not part of the browser contract\n- browser-managed unpairing is limited to the current origin\n- closing either pairing UI path should cancel the pending request explicitly\n\nThat last point is part of the trust model, not just a UX detail. A dismissed pairing window should not leave behind a stale approval request that can still be completed later by accident.\n\n## Trust Boundaries Contributors Must Preserve\n\n- keep the companion bound to `127.0.0.1`\n- do not relax CORS rules casually\n- do not replace exact-origin approval with hostname heuristics or silent trust-on-first-use behavior\n- keep browser-to-companion auth distinct from backend bearer-token auth\n- preserve the server-side edit-lock lifecycle for SMB-backed editing instead of letting the companion bypass it\n- keep reverse-proxy cookies distinct from Sambee bearer tokens and companion localhost pairing secrets\n- redact deep-link tokens, sessions, cookies, authorization data, and other sensitive query values before logging\n\nReverse-proxy authentication is a separate trust path from localhost pairing. The companion may use cookies captured in its own backend-origin authentication webview for Rust-side backend requests, but it must not import cookies from the user's normal browser session.\n\n## What Changes Are High Risk\n\n- anything that alters token exchange or deep-link parsing\n- anything that changes pairing confirmation rules\n- anything that weakens HMAC validation, timestamp checking, or origin scoping\n- anything that blurs the distinction between local-drive workflows and SMB-backed edit workflows\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/auth.rs` | localhost API authentication |\n| `companion/src-tauri/src/server/pairing.rs` | pairing flow and secret lifecycle |\n| `companion/src-tauri/src/uri/` and `token/` | deep-link parsing and token exchange support |\n| `frontend/src/services/companion.ts` | browser-side pairing and companion communication |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion appropriately |\n\n## Validation Expectations\n\nWhen this trust model changes, do not validate only the companion.\n\nRun at least:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\n```\n\nIf the change alters SMB edit flows, add the relevant backend checks too.\n", "1.0": "+++\ntitle = \"Browser-to-Companion Trust Model\"\n+++\n\nThe browser-to-companion boundary is powerful because it crosses from the browser app into desktop-local capability. That makes it one of the most security-sensitive parts of Sambee.\n\n## Two Distinct Trust Paths\n\nSambee uses two browser-to-companion interaction models.\n\n### Deep-Link Editing Path\n\nThis path is used when the browser asks the companion to open an SMB-backed file in a native desktop app.\n\n1. The browser asks the backend for a short-lived URI token.\n1. The browser launches a `sambee://` deep link.\n1. Companion exchanges the one-time token for a session token.\n1. Companion downloads the file, acquires the edit lock, and later uploads the result.\n\nCompanion sends the URI token to the backend token endpoint in a JSON request body. Do not reintroduce query-string token exchange compatibility; deep-link tokens are sensitive and should not be exposed in URLs, logs, proxy access logs, or browser history.\n\nThe deep-link token is not a general browser-to-companion credential. It is a short-lived bootstrap value for one native-editing handoff.\n\n### Localhost API Path\n\nThis path is used for local-drive access and related browser-to-desktop features.\n\n1. the browser probes `http://localhost:21549/api/health`\n1. browser and companion perform an explicit pairing flow for the current browser origin\n1. the browser uses authenticated localhost requests for local-drive operations\n1. the companion sends directory-change notifications over a paired WebSocket channel\n\n## Why Pairing Exists\n\nLocalhost alone is not a trust boundary.\n\nThe companion therefore requires explicit pairing and per-request authentication so that:\n\n- remote network clients cannot reach it\n- arbitrary websites cannot use it just because they run in the browser\n- local native processes do not gain the browser's paired privileges automatically\n\n## Pairing Model\n\nThe pairing flow is deliberately shaped like numeric-comparison pairing, but the important trust decision is not just \u201cdo the codes match?\u201d It is \u201cdoes the user approve this exact browser origin on this computer?\u201d\n\n- the browser and companion exchange nonces\n- both sides independently derive the same short pairing code\n- the companion displays the exact requesting browser origin in a native approval window\n- the user confirms the match in both places\n- the companion returns a shared secret only after dual confirmation succeeds\n\nThat dual confirmation step is what turns \u201csomething can reach localhost\u201d into \u201cthe user intentionally paired this browser origin with this desktop app.\u201d\n\n### Production and Development Origin Rules\n\nIn production, Companion does not rely on a preconfigured list of Sambee frontend URLs.\n\n- any valid browser origin can request pairing\n- Companion normalizes that exact origin and shows it to the user for local approval\n- once approved, that exact origin becomes the paired browser origin for future authenticated localhost requests\n\nFor development, typical loopback browser origins such as `localhost`, `127.0.0.1`, and `::1` remain usable without manual per-port configuration.\n\nThis keeps development practical without weakening the production trust boundary into hostname heuristics or silent trust-on-first-use.\n\n## Request Authentication after Pairing\n\nAfter pairing, companion-bound requests use HMAC-based authentication rather than the server's bearer-token flow.\n\n- localhost API requests carry an HMAC derived from the shared secret and a timestamp\n- the companion rejects requests outside the allowed clock window\n- pairing is tracked per browser origin, not as one global switch\n- the shared secret is stored in OS-protected credential storage on the companion side\n\nBrowser-facing pairing state should also stay origin-scoped and typed.\n\nImportant browser-visible states include:\n\n- unavailable\n- unpaired\n- pending local approval\n- paired\n- repair required because the browser-side secret is missing or unusable\n\nThat state model matters because local trust problems should surface as explicit recovery states rather than as a misleading generic \u201cnot paired\u201d result.\n\n## Pairing Management and Cancellation\n\nPairing management is intentionally narrower than routine local-drive access.\n\n- the browser should only learn the status of its own current origin\n- browser-visible paired-origin enumeration is not part of the browser contract\n- browser-managed unpairing is limited to the current origin\n- closing either pairing UI path should cancel the pending request explicitly\n\nThat last point is part of the trust model, not just a UX detail. A dismissed pairing window should not leave behind a stale approval request that can still be completed later by accident.\n\n## Trust Boundaries Contributors Must Preserve\n\n- keep the companion bound to `127.0.0.1`\n- do not relax CORS rules casually\n- do not replace exact-origin approval with hostname heuristics or silent trust-on-first-use behavior\n- keep browser-to-companion auth distinct from backend bearer-token auth\n- preserve the server-side edit-lock lifecycle for SMB-backed editing instead of letting the companion bypass it\n- keep reverse-proxy cookies distinct from Sambee bearer tokens and companion localhost pairing secrets\n- redact deep-link tokens, sessions, cookies, authorization data, and other sensitive query values before logging\n\nReverse-proxy authentication is a separate trust path from localhost pairing. The companion may use cookies captured in its own backend-origin authentication webview for Rust-side backend requests, but it must not import cookies from the user's normal browser session.\n\n## What Changes Are High Risk\n\n- anything that alters token exchange or deep-link parsing\n- anything that changes pairing confirmation rules\n- anything that weakens HMAC validation, timestamp checking, or origin scoping\n- anything that blurs the distinction between local-drive workflows and SMB-backed edit workflows\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/auth.rs` | localhost API authentication |\n| `companion/src-tauri/src/server/pairing.rs` | pairing flow and secret lifecycle |\n| `companion/src-tauri/src/uri/` and `token/` | deep-link parsing and token exchange support |\n| `frontend/src/services/companion.ts` | browser-side pairing and companion communication |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion appropriately |\n\n## Validation Expectations\n\nWhen this trust model changes, do not validate only the companion.\n\nRun at least:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\n```\n\nIf the change alters SMB edit flows, add the relevant backend checks too.\n", "2.0": "+++\ntitle = \"Browser-to-Companion Trust Model\"\n+++\n\nThe browser-to-companion boundary is powerful because it crosses from the browser app into desktop-local capability. That makes it one of the most security-sensitive parts of Sambee.\n\n## Two Distinct Trust Paths\n\nSambee uses two browser-to-companion interaction models.\n\n### Deep-Link Editing Path\n\nThis path is used when the browser asks the companion to open an SMB-backed file in a native desktop app.\n\n1. The browser asks the backend for a short-lived URI token.\n1. The browser launches a `sambee://` deep link.\n1. Companion exchanges the one-time token for a session token.\n1. Companion downloads the file, acquires the edit lock, and later uploads the result.\n\nCompanion sends the URI token to the backend token endpoint in a JSON request body. Do not reintroduce query-string token exchange compatibility; deep-link tokens are sensitive and should not be exposed in URLs, logs, proxy access logs, or browser history.\n\nThe deep-link token is not a general browser-to-companion credential. It is a short-lived bootstrap value for one native-editing handoff.\n\n### Localhost API Path\n\nThis path is used for local-drive access and related browser-to-desktop features.\n\n1. the browser probes `http://localhost:21549/api/health`\n1. browser and companion perform an explicit pairing flow for the current browser origin\n1. the browser uses authenticated localhost requests for local-drive operations\n1. the companion sends directory-change notifications over a paired WebSocket channel\n\n## Why Pairing Exists\n\nLocalhost alone is not a trust boundary.\n\nThe companion therefore requires explicit pairing and per-request authentication so that:\n\n- remote network clients cannot reach it\n- arbitrary websites cannot use it just because they run in the browser\n- local native processes do not gain the browser's paired privileges automatically\n\n## Pairing Model\n\nThe pairing flow is deliberately shaped like numeric-comparison pairing, but the important trust decision is not just \u201cdo the codes match?\u201d It is \u201cdoes the user approve this exact browser origin on this computer?\u201d\n\n- the browser and companion exchange nonces\n- both sides independently derive the same short pairing code\n- the companion displays the exact requesting browser origin in a native approval window\n- the user confirms the match in both places\n- the companion returns a shared secret only after dual confirmation succeeds\n\nThat dual confirmation step is what turns \u201csomething can reach localhost\u201d into \u201cthe user intentionally paired this browser origin with this desktop app.\u201d\n\n### Production and Development Origin Rules\n\nIn production, Companion does not rely on a preconfigured list of Sambee frontend URLs.\n\n- any valid browser origin can request pairing\n- Companion normalizes that exact origin and shows it to the user for local approval\n- once approved, that exact origin becomes the paired browser origin for future authenticated localhost requests\n\nFor development, typical loopback browser origins such as `localhost`, `127.0.0.1`, and `::1` remain usable without manual per-port configuration.\n\nThis keeps development practical without weakening the production trust boundary into hostname heuristics or silent trust-on-first-use.\n\n## Request Authentication after Pairing\n\nAfter pairing, companion-bound requests use HMAC-based authentication rather than the server's bearer-token flow.\n\n- localhost API requests carry an HMAC derived from the shared secret and a timestamp\n- the companion rejects requests outside the allowed clock window\n- pairing is tracked per browser origin, not as one global switch\n- the shared secret is stored in OS-protected credential storage on the companion side\n\nBrowser-facing pairing state should also stay origin-scoped and typed.\n\nImportant browser-visible states include:\n\n- unavailable\n- unpaired\n- pending local approval\n- paired\n- repair required because the browser-side secret is missing or unusable\n\nThat state model matters because local trust problems should surface as explicit recovery states rather than as a misleading generic \u201cnot paired\u201d result.\n\n## Pairing Management and Cancellation\n\nPairing management is intentionally narrower than routine local-drive access.\n\n- the browser should only learn the status of its own current origin\n- browser-visible paired-origin enumeration is not part of the browser contract\n- browser-managed unpairing is limited to the current origin\n- closing either pairing UI path should cancel the pending request explicitly\n\nThat last point is part of the trust model, not just a UX detail. A dismissed pairing window should not leave behind a stale approval request that can still be completed later by accident.\n\n## Trust Boundaries Contributors Must Preserve\n\n- keep the companion bound to `127.0.0.1`\n- do not relax CORS rules casually\n- do not replace exact-origin approval with hostname heuristics or silent trust-on-first-use behavior\n- keep browser-to-companion auth distinct from backend bearer-token auth\n- preserve the server-side edit-lock lifecycle for SMB-backed editing instead of letting the companion bypass it\n- keep reverse-proxy cookies distinct from Sambee bearer tokens and companion localhost pairing secrets\n- redact deep-link tokens, sessions, cookies, authorization data, and other sensitive query values before logging\n\nReverse-proxy authentication is a separate trust path from localhost pairing. The companion may use cookies captured in its own backend-origin authentication webview for Rust-side backend requests, but it must not import cookies from the user's normal browser session.\n\n## What Changes Are High Risk\n\n- anything that alters token exchange or deep-link parsing\n- anything that changes pairing confirmation rules\n- anything that weakens HMAC validation, timestamp checking, or origin scoping\n- anything that blurs the distinction between local-drive workflows and SMB-backed edit workflows\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/auth.rs` | localhost API authentication |\n| `companion/src-tauri/src/server/pairing.rs` | pairing flow and secret lifecycle |\n| `companion/src-tauri/src/uri/` and `token/` | deep-link parsing and token exchange support |\n| `frontend/src/services/companion.ts` | browser-side pairing and companion communication |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion appropriately |\n\n## Validation Expectations\n\nWhen this trust model changes, do not validate only the companion.\n\nRun at least:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\n```\n\nIf the change alters SMB edit flows, add the relevant backend checks too.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/companion-architecture/local-drive-and-save-back-pipeline", "parent_id": "section:developer-guide/companion-architecture", "depth": 2, "kind": "page", "label": "local-drive-and-save-back-pipeline", "title": "Local Drive And Save Back Pipeline", "path": "developer-guide/companion-architecture/local-drive-and-save-back-pipeline", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "branched", "source_version": "0.7", "diff_added": 16, "diff_removed": 6}, "0.9": {"state": "inherited", "source_version": "0.8"}, "1.0": {"state": "inherited", "source_version": "0.8"}, "2.0": {"state": "inherited", "source_version": "0.8"}}, "content_versions": {"0.7": "+++\ntitle = \"Local-Drive and Save-Back Pipeline\"\n+++\n\nThe companion supports two different desktop-side data paths.\n\n- paired local-drive access through the localhost API\n- SMB-backed native-app editing with temp files, locks, and explicit save-back\n\nThey are related because the same desktop app participates in both, but they do not share the same trust or data lifecycle.\n\n## Local-Drive Access Pipeline\n\nFor local drives, the browser stays in control and the companion behaves like a desktop-local backend.\n\n1. the browser detects the companion through the localhost health endpoint\n2. browser and companion pair explicitly\n3. the browser requests available drives\n4. the browser routes local-drive browse, file, and file-management requests to the companion instead of the server backend\n5. a companion-side watcher and WebSocket channel keep local directory state fresh\n\nThis is why local drives can appear inside the same UI as SMB shares while still using a different execution path.\n\n## Localhost API Shape\n\nThe companion embeds a localhost HTTP server and mirrors the backend API contract closely enough that the frontend can stay mostly connection-type agnostic.\n\nThe server is bound to `127.0.0.1:21549` and exposes routes under `/api`.\n\nRepresentative endpoints include:\n\n- `GET /api/health`: companion availability and pairing state\n- `POST /api/pair/initiate`: begin pairing\n- `POST /api/pair/confirm`: finish pairing after dual confirmation\n- `GET /api/drives`: enumerate available local drives and volumes\n- `GET /api/browse/{drive}/list`: list a directory\n- `GET /api/browse/{drive}/info`: stat one file or directory\n- `GET /api/browse/{drive}/directories`: search directories recursively\n- `GET /api/viewer/{drive}/file`: stream a file for inline viewing\n- `GET /api/viewer/{drive}/download`: stream a file as a download\n- `POST /api/browse/{drive}/upload`: upload a file into the drive-backed path\n- `DELETE /api/browse/{drive}/item`: delete a file or directory\n- `POST /api/browse/{drive}/rename`: rename a path\n- `POST /api/browse/{drive}/create`: create a file or directory\n- `POST /api/browse/{drive}/copy`: copy within or across local drives\n- `POST /api/browse/{drive}/move`: move within or across local drives\n- `WS /api/ws`: companion-side directory change notifications\n\nResponse shapes intentionally follow the backend contract so the browser can reuse models such as directory listings and file info instead of maintaining a separate local-drive UI protocol.\n\n## Local-Drive Operation Rules\n\n- the companion mirrors the backend API contract closely so the frontend can stay mostly connection-type agnostic\n- local-drive operations use desktop filesystem primitives, not SMB semantics\n- local files opened directly through the companion can skip download, lock, upload, and the \"Done Editing\" flow entirely\n\nAdditional rules that matter in practice:\n\n- image conversion is not part of the companion local-drive path; raw local files are served directly\n- local-drive browsing has no SMB edit-lock semantics\n- same-drive copy and move use local filesystem operations directly\n- cross-backend transfers between SMB and local storage are browser-mediated rather than hidden inside the companion's direct-open flow\n\nThat direct local-open path is intentionally different from SMB-backed native-app editing.\n\n## Drive Enumeration Model\n\nThe companion discovers drives and mounted volumes automatically.\n\nPlatform-specific inputs differ, but the goal is the same: expose what the current desktop user can already access through the normal filesystem.\n\n- Windows: fixed drives, removable drives, mapped drives, and virtual drives exposed through the filesystem\n- macOS: mounted volumes under the normal desktop volume model\n- Linux: mounted filesystems that represent real file content rather than pseudo-filesystems\n\nThat includes cloud-backed or virtual drives when they appear through the OS filesystem layer.\n\nThe browser therefore does not need manual drive configuration. It asks the companion for the current drive list and renders those entries alongside SMB connections.\n\nThe companion should still filter out pseudo-filesystems and other non-file mounts that would only add noise or unsafe paths.\n\n## Browser Routing and Auth Behavior\n\nThe browser uses the same UI for SMB and local drives, but the request path changes underneath.\n\n- SMB-backed requests continue through the main Sambee backend\n- local-drive requests route to the companion localhost API instead\n- the browser detects the companion through the health endpoint\n- once paired, it requests drives and merges them into the connection list as local-drive entries\n\nAuthentication also changes:\n\n- backend requests use the normal server-side auth model\n- companion requests use the pairing-derived HMAC model described in [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/)\n\nThat distinction is critical. Local-drive access is not \"server auth pointed at localhost\". It is a separate authenticated browser-to-desktop channel.\n\n## Local-Drive Watching and WebSockets\n\nThe companion keeps local directory state fresh through its own watcher and WebSocket path.\n\n- the browser opens a companion WebSocket when local-drive behavior is active\n- subscriptions are tracked per directory\n- the companion shares watcher state when possible instead of creating wasteful duplicate watchers\n- local directory changes propagate back into the same browser refresh model used by the file browser\n\nThis is why local drives can participate in the same dual-pane and refresh workflows as SMB connections without pretending the transport is the same.\n\n## SMB-Backed Native-App Save-Back Pipeline\n\nFor SMB-backed native-app editing, the companion is not the source of truth. It is the desktop-side coordinator for a backend-governed editing lifecycle.\n\n1. the browser launches a `sambee://` deep link\n2. the companion exchanges the URI token for a bootstrap token\n3. it fetches metadata and conflict baseline information\n4. it acquires the backend edit lock and receives operation-scoped lock context\n5. it downloads the file to a temp directory\n5. it opens the file in the chosen native application\n6. a \"Done Editing\" window stays open while renewal, heartbeat, and file-status checks continue in the background\n7. on explicit user confirmation, the companion uploads the file or discards it\n8. the backend lock is released and the temp file is recycled\n\n## Why Save-Back Uses Explicit Confirmation\n\nThe save-back model uses explicit user action rather than automatic filesystem watching.\n\nThat avoids a harder class of problems around:\n\n- partial writes and atomic-save behavior\n- repeated intermediate uploads\n- uncertainty about when editing is truly finished\n\nThe hold-to-confirm interaction is therefore a product decision, not just a UI quirk.\n\n## Conflict and Recovery Behavior\n\nThe companion keeps operation state because desktop editing can outlive one clean process lifecycle.\n\n- operation state is persisted alongside temp files for recovery\n- server state is checked before overwrite-sensitive upload completes\n- when server state changed during editing, the user must resolve the conflict rather than silently replacing the file\n\n## Critical Distinction Contributors Must Preserve\n\n- local-drive workflows do not use backend SMB edit locks\n- SMB-backed native-app editing does use backend lock, heartbeat, and upload semantics\n- cross-backend transfers between SMB and local storage are their own browser-mediated flow, not a shortcut through the deep-link edit lifecycle\n- localhost API pairing and HMAC auth are part of the product contract, not replaceable convenience layers\n\nIf you blur these paths, you usually break either security assumptions or data-integrity guarantees.\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/` | localhost API, drive enumeration, auth, pairing, and watcher behavior |\n| `companion/src-tauri/src/commands/open_file.rs` | download and native-app open lifecycle |\n| `companion/src-tauri/src/commands/upload.rs` | upload, lock, and heartbeat support |\n| `companion/src-tauri/src/sync/operations.rs` | operation state and recovery tracking |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion based on connection type |\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome local-drive behavior is intentionally scoped rather than incomplete by accident.\n\n- local direct-open avoids the SMB save-back lifecycle on purpose\n- raw local files are served directly instead of bundling server-style image conversion into the companion path\n- drive scope follows what the current desktop user can already access rather than inventing a separate path-allowlist model by default\n- cross-backend file movement is a separate browser-mediated path because SMB and local-drive backends do not share one native transfer primitive\n\n## Validation Expectations\n\nWhen this pipeline changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe backend checks matter whenever the change touches SMB-backed save-back, lock, heartbeat, or upload behavior.\n", "0.8": "+++\ntitle = \"Local-Drive and Save-Back Pipeline\"\n+++\n\nThe companion supports two different desktop-side data paths.\n\n- paired local-drive access through the localhost API\n- SMB-backed native-app editing with temp files, locks, and explicit save-back\n\nThey are related because the same desktop app participates in both, but they do not share the same trust or data lifecycle.\n\n## Local-Drive Access Pipeline\n\nFor local drives, the browser stays in control and the companion behaves like a desktop-local backend.\n\n1. the browser detects the companion through the localhost health endpoint\n2. browser and companion pair explicitly\n3. the browser requests available drives\n4. the browser routes local-drive browse, file, and file-management requests to the companion instead of the server backend\n5. a companion-side watcher and WebSocket channel keep local directory state fresh\n\nThis is why local drives can appear inside the same UI as SMB shares while still using a different execution path.\n\n## Localhost API Shape\n\nThe companion embeds a localhost HTTP server and mirrors the backend API contract closely enough that the frontend can stay mostly connection-type agnostic.\n\nThe server is bound to `127.0.0.1:21549` and exposes routes under `/api`.\n\nRepresentative endpoints include:\n\n- `GET /api/health`: companion availability\n- `POST /api/pair/initiate`: begin pairing\n- `POST /api/pair/confirm`: finish pairing after dual confirmation\n- `GET /api/pair/status`: origin-scoped browser pairing status\n- `POST /api/pair/cancel`: cancel a pending pairing for the current browser origin\n- `DELETE /api/pair/current`: remove the current browser origin's pairing\n- `GET /api/drives`: enumerate available local drives and volumes\n- `GET /api/browse/{drive}/list`: list a directory\n- `GET /api/browse/{drive}/info`: stat one file or directory\n- `GET /api/browse/{drive}/directories`: search directories recursively\n- `GET /api/viewer/{drive}/file`: stream a file for inline viewing\n- `GET /api/viewer/{drive}/download`: stream a file as a download\n- `POST /api/browse/{drive}/upload`: upload a file into the drive-backed path\n- `DELETE /api/browse/{drive}/item`: delete a file or directory\n- `POST /api/browse/{drive}/rename`: rename a path\n- `POST /api/browse/{drive}/create`: create a file or directory\n- `POST /api/browse/{drive}/copy`: copy within or across local drives\n- `POST /api/browse/{drive}/move`: move within or across local drives\n- `WS /api/ws`: companion-side directory change notifications\n\nResponse shapes intentionally follow the backend contract so the browser can reuse models such as directory listings and file info instead of maintaining a separate local-drive UI protocol.\n\nThe important exception is pairing state: the browser-facing pairing contract is intentionally origin-scoped and typed, rather than exposing a global paired flag or browser-visible inventory of all trusted origins.\n\n## Local-Drive Operation Rules\n\n- the companion mirrors the backend API contract closely so the frontend can stay mostly connection-type agnostic\n- local-drive operations use desktop filesystem primitives, not SMB semantics\n- local files opened directly through the companion can skip download, lock, upload, and the \"Done Editing\" flow entirely\n\nAdditional rules that matter in practice:\n\n- image conversion is not part of the companion local-drive path; raw local files are served directly\n- local-drive browsing has no SMB edit-lock semantics\n- same-drive copy and move use local filesystem operations directly\n- cross-backend transfers between SMB and local storage are browser-mediated rather than hidden inside the companion's direct-open flow\n\nThat direct local-open path is intentionally different from SMB-backed native-app editing.\n\n## Drive Enumeration Model\n\nThe companion discovers drives and mounted volumes automatically.\n\nPlatform-specific inputs differ, but the goal is the same: expose what the current desktop user can already access through the normal filesystem.\n\n- Windows: fixed drives, removable drives, mapped drives, and virtual drives exposed through the filesystem\n- macOS: mounted volumes under the normal desktop volume model\n- Linux: mounted filesystems that represent real file content rather than pseudo-filesystems\n\nThat includes cloud-backed or virtual drives when they appear through the OS filesystem layer.\n\nThe browser therefore does not need manual drive configuration. It asks the companion for the current drive list and renders those entries alongside SMB connections.\n\nThe companion should still filter out pseudo-filesystems and other non-file mounts that would only add noise or unsafe paths.\n\n## Browser Routing and Auth Behavior\n\nThe browser uses the same UI for SMB and local drives, but the request path changes underneath.\n\n- SMB-backed requests continue through the main Sambee backend\n- local-drive requests route to the companion localhost API instead\n- the browser detects the companion through the health endpoint\n- once paired, it requests drives and merges them into the connection list as local-drive entries\n\nAuthentication also changes:\n\n- backend requests use the normal server-side auth model\n- companion requests use the pairing-derived HMAC model described in [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/)\n\nThe localhost bootstrap boundary also changed in an important way:\n\n- production trust is established by exact-origin approval during pairing\n- development remains practical through loopback-origin allowance\n- browser-facing pairing management is limited to the current origin rather than arbitrary origin inventory or deletion\n\nThat distinction is critical. Local-drive access is not \"server auth pointed at localhost\". It is a separate authenticated browser-to-desktop channel.\n\n## Local-Drive Watching and WebSockets\n\nThe companion keeps local directory state fresh through its own watcher and WebSocket path.\n\n- the browser opens a companion WebSocket when local-drive behavior is active\n- subscriptions are tracked per directory\n- the companion shares watcher state when possible instead of creating wasteful duplicate watchers\n- local directory changes propagate back into the same browser refresh model used by the file browser\n\nThis is why local drives can participate in the same dual-pane and refresh workflows as SMB connections without pretending the transport is the same.\n\n## SMB-Backed Native-App Save-Back Pipeline\n\nFor SMB-backed native-app editing, the companion is not the source of truth. It is the desktop-side coordinator for a backend-governed editing lifecycle.\n\n1. the browser launches a `sambee://` deep link\n2. the companion exchanges the URI token for an authenticated session\n3. it fetches metadata and downloads the file to a temp directory\n4. it acquires the backend edit lock\n5. it opens the file in the chosen native application\n6. a \"Done Editing\" window stays open while heartbeat and file-status checks continue in the background\n7. on explicit user confirmation, the companion uploads the file or discards it\n8. the backend lock is released and the temp file is recycled\n\n## Why Save-Back Uses Explicit Confirmation\n\nThe save-back model uses explicit user action rather than automatic filesystem watching.\n\nThat avoids a harder class of problems around:\n\n- partial writes and atomic-save behavior\n- repeated intermediate uploads\n- uncertainty about when editing is truly finished\n\nThe hold-to-confirm interaction is therefore a product decision, not just a UI quirk.\n\n## Conflict and Recovery Behavior\n\nThe companion keeps operation state because desktop editing can outlive one clean process lifecycle.\n\n- operation state is persisted alongside temp files for recovery\n- server state is checked before overwrite-sensitive upload completes\n- when server state changed during editing, the user must resolve the conflict rather than silently replacing the file\n\n## Critical Distinction Contributors Must Preserve\n\n- local-drive workflows do not use backend SMB edit locks\n- SMB-backed native-app editing does use backend lock, heartbeat, and upload semantics\n- cross-backend transfers between SMB and local storage are their own browser-mediated flow, not a shortcut through the deep-link edit lifecycle\n- localhost API pairing and HMAC auth are part of the product contract, not replaceable convenience layers\n\nIf you blur these paths, you usually break either security assumptions or data-integrity guarantees.\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/` | localhost API, drive enumeration, auth, pairing, and watcher behavior |\n| `companion/src-tauri/src/commands/open_file.rs` | download and native-app open lifecycle |\n| `companion/src-tauri/src/commands/upload.rs` | upload, lock, and heartbeat support |\n| `companion/src-tauri/src/sync/operations.rs` | operation state and recovery tracking |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion based on connection type |\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome local-drive behavior is intentionally scoped rather than incomplete by accident.\n\n- local direct-open avoids the SMB save-back lifecycle on purpose\n- raw local files are served directly instead of bundling server-style image conversion into the companion path\n- drive scope follows what the current desktop user can already access rather than inventing a separate path-allowlist model by default\n- cross-backend file movement is a separate browser-mediated path because SMB and local-drive backends do not share one native transfer primitive\n\n## Validation Expectations\n\nWhen this pipeline changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe backend checks matter whenever the change touches SMB-backed save-back, lock, heartbeat, or upload behavior.\n", "0.9": "+++\ntitle = \"Local-Drive and Save-Back Pipeline\"\n+++\n\nThe companion supports two different desktop-side data paths.\n\n- paired local-drive access through the localhost API\n- SMB-backed native-app editing with temp files, locks, and explicit save-back\n\nThey are related because the same desktop app participates in both, but they do not share the same trust or data lifecycle.\n\n## Local-Drive Access Pipeline\n\nFor local drives, the browser stays in control and the companion behaves like a desktop-local backend.\n\n1. the browser detects the companion through the localhost health endpoint\n2. browser and companion pair explicitly\n3. the browser requests available drives\n4. the browser routes local-drive browse, file, and file-management requests to the companion instead of the server backend\n5. a companion-side watcher and WebSocket channel keep local directory state fresh\n\nThis is why local drives can appear inside the same UI as SMB shares while still using a different execution path.\n\n## Localhost API Shape\n\nThe companion embeds a localhost HTTP server and mirrors the backend API contract closely enough that the frontend can stay mostly connection-type agnostic.\n\nThe server is bound to `127.0.0.1:21549` and exposes routes under `/api`.\n\nRepresentative endpoints include:\n\n- `GET /api/health`: companion availability\n- `POST /api/pair/initiate`: begin pairing\n- `POST /api/pair/confirm`: finish pairing after dual confirmation\n- `GET /api/pair/status`: origin-scoped browser pairing status\n- `POST /api/pair/cancel`: cancel a pending pairing for the current browser origin\n- `DELETE /api/pair/current`: remove the current browser origin's pairing\n- `GET /api/drives`: enumerate available local drives and volumes\n- `GET /api/browse/{drive}/list`: list a directory\n- `GET /api/browse/{drive}/info`: stat one file or directory\n- `GET /api/browse/{drive}/directories`: search directories recursively\n- `GET /api/viewer/{drive}/file`: stream a file for inline viewing\n- `GET /api/viewer/{drive}/download`: stream a file as a download\n- `POST /api/browse/{drive}/upload`: upload a file into the drive-backed path\n- `DELETE /api/browse/{drive}/item`: delete a file or directory\n- `POST /api/browse/{drive}/rename`: rename a path\n- `POST /api/browse/{drive}/create`: create a file or directory\n- `POST /api/browse/{drive}/copy`: copy within or across local drives\n- `POST /api/browse/{drive}/move`: move within or across local drives\n- `WS /api/ws`: companion-side directory change notifications\n\nResponse shapes intentionally follow the backend contract so the browser can reuse models such as directory listings and file info instead of maintaining a separate local-drive UI protocol.\n\nThe important exception is pairing state: the browser-facing pairing contract is intentionally origin-scoped and typed, rather than exposing a global paired flag or browser-visible inventory of all trusted origins.\n\n## Local-Drive Operation Rules\n\n- the companion mirrors the backend API contract closely so the frontend can stay mostly connection-type agnostic\n- local-drive operations use desktop filesystem primitives, not SMB semantics\n- local files opened directly through the companion can skip download, lock, upload, and the \"Done Editing\" flow entirely\n\nAdditional rules that matter in practice:\n\n- image conversion is not part of the companion local-drive path; raw local files are served directly\n- local-drive browsing has no SMB edit-lock semantics\n- same-drive copy and move use local filesystem operations directly\n- cross-backend transfers between SMB and local storage are browser-mediated rather than hidden inside the companion's direct-open flow\n\nThat direct local-open path is intentionally different from SMB-backed native-app editing.\n\n## Drive Enumeration Model\n\nThe companion discovers drives and mounted volumes automatically.\n\nPlatform-specific inputs differ, but the goal is the same: expose what the current desktop user can already access through the normal filesystem.\n\n- Windows: fixed drives, removable drives, mapped drives, and virtual drives exposed through the filesystem\n- macOS: mounted volumes under the normal desktop volume model\n- Linux: mounted filesystems that represent real file content rather than pseudo-filesystems\n\nThat includes cloud-backed or virtual drives when they appear through the OS filesystem layer.\n\nThe browser therefore does not need manual drive configuration. It asks the companion for the current drive list and renders those entries alongside SMB connections.\n\nThe companion should still filter out pseudo-filesystems and other non-file mounts that would only add noise or unsafe paths.\n\n## Browser Routing and Auth Behavior\n\nThe browser uses the same UI for SMB and local drives, but the request path changes underneath.\n\n- SMB-backed requests continue through the main Sambee backend\n- local-drive requests route to the companion localhost API instead\n- the browser detects the companion through the health endpoint\n- once paired, it requests drives and merges them into the connection list as local-drive entries\n\nAuthentication also changes:\n\n- backend requests use the normal server-side auth model\n- companion requests use the pairing-derived HMAC model described in [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/)\n\nThe localhost bootstrap boundary also changed in an important way:\n\n- production trust is established by exact-origin approval during pairing\n- development remains practical through loopback-origin allowance\n- browser-facing pairing management is limited to the current origin rather than arbitrary origin inventory or deletion\n\nThat distinction is critical. Local-drive access is not \"server auth pointed at localhost\". It is a separate authenticated browser-to-desktop channel.\n\n## Local-Drive Watching and WebSockets\n\nThe companion keeps local directory state fresh through its own watcher and WebSocket path.\n\n- the browser opens a companion WebSocket when local-drive behavior is active\n- subscriptions are tracked per directory\n- the companion shares watcher state when possible instead of creating wasteful duplicate watchers\n- local directory changes propagate back into the same browser refresh model used by the file browser\n\nThis is why local drives can participate in the same dual-pane and refresh workflows as SMB connections without pretending the transport is the same.\n\n## SMB-Backed Native-App Save-Back Pipeline\n\nFor SMB-backed native-app editing, the companion is not the source of truth. It is the desktop-side coordinator for a backend-governed editing lifecycle.\n\n1. the browser launches a `sambee://` deep link\n2. the companion exchanges the URI token for an authenticated session\n3. it fetches metadata and downloads the file to a temp directory\n4. it acquires the backend edit lock\n5. it opens the file in the chosen native application\n6. a \"Done Editing\" window stays open while heartbeat and file-status checks continue in the background\n7. on explicit user confirmation, the companion uploads the file or discards it\n8. the backend lock is released and the temp file is recycled\n\n## Why Save-Back Uses Explicit Confirmation\n\nThe save-back model uses explicit user action rather than automatic filesystem watching.\n\nThat avoids a harder class of problems around:\n\n- partial writes and atomic-save behavior\n- repeated intermediate uploads\n- uncertainty about when editing is truly finished\n\nThe hold-to-confirm interaction is therefore a product decision, not just a UI quirk.\n\n## Conflict and Recovery Behavior\n\nThe companion keeps operation state because desktop editing can outlive one clean process lifecycle.\n\n- operation state is persisted alongside temp files for recovery\n- server state is checked before overwrite-sensitive upload completes\n- when server state changed during editing, the user must resolve the conflict rather than silently replacing the file\n\n## Critical Distinction Contributors Must Preserve\n\n- local-drive workflows do not use backend SMB edit locks\n- SMB-backed native-app editing does use backend lock, heartbeat, and upload semantics\n- cross-backend transfers between SMB and local storage are their own browser-mediated flow, not a shortcut through the deep-link edit lifecycle\n- localhost API pairing and HMAC auth are part of the product contract, not replaceable convenience layers\n\nIf you blur these paths, you usually break either security assumptions or data-integrity guarantees.\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/` | localhost API, drive enumeration, auth, pairing, and watcher behavior |\n| `companion/src-tauri/src/commands/open_file.rs` | download and native-app open lifecycle |\n| `companion/src-tauri/src/commands/upload.rs` | upload, lock, and heartbeat support |\n| `companion/src-tauri/src/sync/operations.rs` | operation state and recovery tracking |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion based on connection type |\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome local-drive behavior is intentionally scoped rather than incomplete by accident.\n\n- local direct-open avoids the SMB save-back lifecycle on purpose\n- raw local files are served directly instead of bundling server-style image conversion into the companion path\n- drive scope follows what the current desktop user can already access rather than inventing a separate path-allowlist model by default\n- cross-backend file movement is a separate browser-mediated path because SMB and local-drive backends do not share one native transfer primitive\n\n## Validation Expectations\n\nWhen this pipeline changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe backend checks matter whenever the change touches SMB-backed save-back, lock, heartbeat, or upload behavior.\n", "1.0": "+++\ntitle = \"Local-Drive and Save-Back Pipeline\"\n+++\n\nThe companion supports two different desktop-side data paths.\n\n- paired local-drive access through the localhost API\n- SMB-backed native-app editing with temp files, locks, and explicit save-back\n\nThey are related because the same desktop app participates in both, but they do not share the same trust or data lifecycle.\n\n## Local-Drive Access Pipeline\n\nFor local drives, the browser stays in control and the companion behaves like a desktop-local backend.\n\n1. the browser detects the companion through the localhost health endpoint\n2. browser and companion pair explicitly\n3. the browser requests available drives\n4. the browser routes local-drive browse, file, and file-management requests to the companion instead of the server backend\n5. a companion-side watcher and WebSocket channel keep local directory state fresh\n\nThis is why local drives can appear inside the same UI as SMB shares while still using a different execution path.\n\n## Localhost API Shape\n\nThe companion embeds a localhost HTTP server and mirrors the backend API contract closely enough that the frontend can stay mostly connection-type agnostic.\n\nThe server is bound to `127.0.0.1:21549` and exposes routes under `/api`.\n\nRepresentative endpoints include:\n\n- `GET /api/health`: companion availability\n- `POST /api/pair/initiate`: begin pairing\n- `POST /api/pair/confirm`: finish pairing after dual confirmation\n- `GET /api/pair/status`: origin-scoped browser pairing status\n- `POST /api/pair/cancel`: cancel a pending pairing for the current browser origin\n- `DELETE /api/pair/current`: remove the current browser origin's pairing\n- `GET /api/drives`: enumerate available local drives and volumes\n- `GET /api/browse/{drive}/list`: list a directory\n- `GET /api/browse/{drive}/info`: stat one file or directory\n- `GET /api/browse/{drive}/directories`: search directories recursively\n- `GET /api/viewer/{drive}/file`: stream a file for inline viewing\n- `GET /api/viewer/{drive}/download`: stream a file as a download\n- `POST /api/browse/{drive}/upload`: upload a file into the drive-backed path\n- `DELETE /api/browse/{drive}/item`: delete a file or directory\n- `POST /api/browse/{drive}/rename`: rename a path\n- `POST /api/browse/{drive}/create`: create a file or directory\n- `POST /api/browse/{drive}/copy`: copy within or across local drives\n- `POST /api/browse/{drive}/move`: move within or across local drives\n- `WS /api/ws`: companion-side directory change notifications\n\nResponse shapes intentionally follow the backend contract so the browser can reuse models such as directory listings and file info instead of maintaining a separate local-drive UI protocol.\n\nThe important exception is pairing state: the browser-facing pairing contract is intentionally origin-scoped and typed, rather than exposing a global paired flag or browser-visible inventory of all trusted origins.\n\n## Local-Drive Operation Rules\n\n- the companion mirrors the backend API contract closely so the frontend can stay mostly connection-type agnostic\n- local-drive operations use desktop filesystem primitives, not SMB semantics\n- local files opened directly through the companion can skip download, lock, upload, and the \"Done Editing\" flow entirely\n\nAdditional rules that matter in practice:\n\n- image conversion is not part of the companion local-drive path; raw local files are served directly\n- local-drive browsing has no SMB edit-lock semantics\n- same-drive copy and move use local filesystem operations directly\n- cross-backend transfers between SMB and local storage are browser-mediated rather than hidden inside the companion's direct-open flow\n\nThat direct local-open path is intentionally different from SMB-backed native-app editing.\n\n## Drive Enumeration Model\n\nThe companion discovers drives and mounted volumes automatically.\n\nPlatform-specific inputs differ, but the goal is the same: expose what the current desktop user can already access through the normal filesystem.\n\n- Windows: fixed drives, removable drives, mapped drives, and virtual drives exposed through the filesystem\n- macOS: mounted volumes under the normal desktop volume model\n- Linux: mounted filesystems that represent real file content rather than pseudo-filesystems\n\nThat includes cloud-backed or virtual drives when they appear through the OS filesystem layer.\n\nThe browser therefore does not need manual drive configuration. It asks the companion for the current drive list and renders those entries alongside SMB connections.\n\nThe companion should still filter out pseudo-filesystems and other non-file mounts that would only add noise or unsafe paths.\n\n## Browser Routing and Auth Behavior\n\nThe browser uses the same UI for SMB and local drives, but the request path changes underneath.\n\n- SMB-backed requests continue through the main Sambee backend\n- local-drive requests route to the companion localhost API instead\n- the browser detects the companion through the health endpoint\n- once paired, it requests drives and merges them into the connection list as local-drive entries\n\nAuthentication also changes:\n\n- backend requests use the normal server-side auth model\n- companion requests use the pairing-derived HMAC model described in [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/)\n\nThe localhost bootstrap boundary also changed in an important way:\n\n- production trust is established by exact-origin approval during pairing\n- development remains practical through loopback-origin allowance\n- browser-facing pairing management is limited to the current origin rather than arbitrary origin inventory or deletion\n\nThat distinction is critical. Local-drive access is not \"server auth pointed at localhost\". It is a separate authenticated browser-to-desktop channel.\n\n## Local-Drive Watching and WebSockets\n\nThe companion keeps local directory state fresh through its own watcher and WebSocket path.\n\n- the browser opens a companion WebSocket when local-drive behavior is active\n- subscriptions are tracked per directory\n- the companion shares watcher state when possible instead of creating wasteful duplicate watchers\n- local directory changes propagate back into the same browser refresh model used by the file browser\n\nThis is why local drives can participate in the same dual-pane and refresh workflows as SMB connections without pretending the transport is the same.\n\n## SMB-Backed Native-App Save-Back Pipeline\n\nFor SMB-backed native-app editing, the companion is not the source of truth. It is the desktop-side coordinator for a backend-governed editing lifecycle.\n\n1. the browser launches a `sambee://` deep link\n2. the companion exchanges the URI token for an authenticated session\n3. it fetches metadata and downloads the file to a temp directory\n4. it acquires the backend edit lock\n5. it opens the file in the chosen native application\n6. a \"Done Editing\" window stays open while heartbeat and file-status checks continue in the background\n7. on explicit user confirmation, the companion uploads the file or discards it\n8. the backend lock is released and the temp file is recycled\n\n## Why Save-Back Uses Explicit Confirmation\n\nThe save-back model uses explicit user action rather than automatic filesystem watching.\n\nThat avoids a harder class of problems around:\n\n- partial writes and atomic-save behavior\n- repeated intermediate uploads\n- uncertainty about when editing is truly finished\n\nThe hold-to-confirm interaction is therefore a product decision, not just a UI quirk.\n\n## Conflict and Recovery Behavior\n\nThe companion keeps operation state because desktop editing can outlive one clean process lifecycle.\n\n- operation state is persisted alongside temp files for recovery\n- server state is checked before overwrite-sensitive upload completes\n- when server state changed during editing, the user must resolve the conflict rather than silently replacing the file\n\n## Critical Distinction Contributors Must Preserve\n\n- local-drive workflows do not use backend SMB edit locks\n- SMB-backed native-app editing does use backend lock, heartbeat, and upload semantics\n- cross-backend transfers between SMB and local storage are their own browser-mediated flow, not a shortcut through the deep-link edit lifecycle\n- localhost API pairing and HMAC auth are part of the product contract, not replaceable convenience layers\n\nIf you blur these paths, you usually break either security assumptions or data-integrity guarantees.\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/` | localhost API, drive enumeration, auth, pairing, and watcher behavior |\n| `companion/src-tauri/src/commands/open_file.rs` | download and native-app open lifecycle |\n| `companion/src-tauri/src/commands/upload.rs` | upload, lock, and heartbeat support |\n| `companion/src-tauri/src/sync/operations.rs` | operation state and recovery tracking |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion based on connection type |\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome local-drive behavior is intentionally scoped rather than incomplete by accident.\n\n- local direct-open avoids the SMB save-back lifecycle on purpose\n- raw local files are served directly instead of bundling server-style image conversion into the companion path\n- drive scope follows what the current desktop user can already access rather than inventing a separate path-allowlist model by default\n- cross-backend file movement is a separate browser-mediated path because SMB and local-drive backends do not share one native transfer primitive\n\n## Validation Expectations\n\nWhen this pipeline changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe backend checks matter whenever the change touches SMB-backed save-back, lock, heartbeat, or upload behavior.\n", "2.0": "+++\ntitle = \"Local-Drive and Save-Back Pipeline\"\n+++\n\nThe companion supports two different desktop-side data paths.\n\n- paired local-drive access through the localhost API\n- SMB-backed native-app editing with temp files, locks, and explicit save-back\n\nThey are related because the same desktop app participates in both, but they do not share the same trust or data lifecycle.\n\n## Local-Drive Access Pipeline\n\nFor local drives, the browser stays in control and the companion behaves like a desktop-local backend.\n\n1. the browser detects the companion through the localhost health endpoint\n2. browser and companion pair explicitly\n3. the browser requests available drives\n4. the browser routes local-drive browse, file, and file-management requests to the companion instead of the server backend\n5. a companion-side watcher and WebSocket channel keep local directory state fresh\n\nThis is why local drives can appear inside the same UI as SMB shares while still using a different execution path.\n\n## Localhost API Shape\n\nThe companion embeds a localhost HTTP server and mirrors the backend API contract closely enough that the frontend can stay mostly connection-type agnostic.\n\nThe server is bound to `127.0.0.1:21549` and exposes routes under `/api`.\n\nRepresentative endpoints include:\n\n- `GET /api/health`: companion availability\n- `POST /api/pair/initiate`: begin pairing\n- `POST /api/pair/confirm`: finish pairing after dual confirmation\n- `GET /api/pair/status`: origin-scoped browser pairing status\n- `POST /api/pair/cancel`: cancel a pending pairing for the current browser origin\n- `DELETE /api/pair/current`: remove the current browser origin's pairing\n- `GET /api/drives`: enumerate available local drives and volumes\n- `GET /api/browse/{drive}/list`: list a directory\n- `GET /api/browse/{drive}/info`: stat one file or directory\n- `GET /api/browse/{drive}/directories`: search directories recursively\n- `GET /api/viewer/{drive}/file`: stream a file for inline viewing\n- `GET /api/viewer/{drive}/download`: stream a file as a download\n- `POST /api/browse/{drive}/upload`: upload a file into the drive-backed path\n- `DELETE /api/browse/{drive}/item`: delete a file or directory\n- `POST /api/browse/{drive}/rename`: rename a path\n- `POST /api/browse/{drive}/create`: create a file or directory\n- `POST /api/browse/{drive}/copy`: copy within or across local drives\n- `POST /api/browse/{drive}/move`: move within or across local drives\n- `WS /api/ws`: companion-side directory change notifications\n\nResponse shapes intentionally follow the backend contract so the browser can reuse models such as directory listings and file info instead of maintaining a separate local-drive UI protocol.\n\nThe important exception is pairing state: the browser-facing pairing contract is intentionally origin-scoped and typed, rather than exposing a global paired flag or browser-visible inventory of all trusted origins.\n\n## Local-Drive Operation Rules\n\n- the companion mirrors the backend API contract closely so the frontend can stay mostly connection-type agnostic\n- local-drive operations use desktop filesystem primitives, not SMB semantics\n- local files opened directly through the companion can skip download, lock, upload, and the \"Done Editing\" flow entirely\n\nAdditional rules that matter in practice:\n\n- image conversion is not part of the companion local-drive path; raw local files are served directly\n- local-drive browsing has no SMB edit-lock semantics\n- same-drive copy and move use local filesystem operations directly\n- cross-backend transfers between SMB and local storage are browser-mediated rather than hidden inside the companion's direct-open flow\n\nThat direct local-open path is intentionally different from SMB-backed native-app editing.\n\n## Drive Enumeration Model\n\nThe companion discovers drives and mounted volumes automatically.\n\nPlatform-specific inputs differ, but the goal is the same: expose what the current desktop user can already access through the normal filesystem.\n\n- Windows: fixed drives, removable drives, mapped drives, and virtual drives exposed through the filesystem\n- macOS: mounted volumes under the normal desktop volume model\n- Linux: mounted filesystems that represent real file content rather than pseudo-filesystems\n\nThat includes cloud-backed or virtual drives when they appear through the OS filesystem layer.\n\nThe browser therefore does not need manual drive configuration. It asks the companion for the current drive list and renders those entries alongside SMB connections.\n\nThe companion should still filter out pseudo-filesystems and other non-file mounts that would only add noise or unsafe paths.\n\n## Browser Routing and Auth Behavior\n\nThe browser uses the same UI for SMB and local drives, but the request path changes underneath.\n\n- SMB-backed requests continue through the main Sambee backend\n- local-drive requests route to the companion localhost API instead\n- the browser detects the companion through the health endpoint\n- once paired, it requests drives and merges them into the connection list as local-drive entries\n\nAuthentication also changes:\n\n- backend requests use the normal server-side auth model\n- companion requests use the pairing-derived HMAC model described in [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/)\n\nThe localhost bootstrap boundary also changed in an important way:\n\n- production trust is established by exact-origin approval during pairing\n- development remains practical through loopback-origin allowance\n- browser-facing pairing management is limited to the current origin rather than arbitrary origin inventory or deletion\n\nThat distinction is critical. Local-drive access is not \"server auth pointed at localhost\". It is a separate authenticated browser-to-desktop channel.\n\n## Local-Drive Watching and WebSockets\n\nThe companion keeps local directory state fresh through its own watcher and WebSocket path.\n\n- the browser opens a companion WebSocket when local-drive behavior is active\n- subscriptions are tracked per directory\n- the companion shares watcher state when possible instead of creating wasteful duplicate watchers\n- local directory changes propagate back into the same browser refresh model used by the file browser\n\nThis is why local drives can participate in the same dual-pane and refresh workflows as SMB connections without pretending the transport is the same.\n\n## SMB-Backed Native-App Save-Back Pipeline\n\nFor SMB-backed native-app editing, the companion is not the source of truth. It is the desktop-side coordinator for a backend-governed editing lifecycle.\n\n1. the browser launches a `sambee://` deep link\n2. the companion exchanges the URI token for an authenticated session\n3. it fetches metadata and downloads the file to a temp directory\n4. it acquires the backend edit lock\n5. it opens the file in the chosen native application\n6. a \"Done Editing\" window stays open while heartbeat and file-status checks continue in the background\n7. on explicit user confirmation, the companion uploads the file or discards it\n8. the backend lock is released and the temp file is recycled\n\n## Why Save-Back Uses Explicit Confirmation\n\nThe save-back model uses explicit user action rather than automatic filesystem watching.\n\nThat avoids a harder class of problems around:\n\n- partial writes and atomic-save behavior\n- repeated intermediate uploads\n- uncertainty about when editing is truly finished\n\nThe hold-to-confirm interaction is therefore a product decision, not just a UI quirk.\n\n## Conflict and Recovery Behavior\n\nThe companion keeps operation state because desktop editing can outlive one clean process lifecycle.\n\n- operation state is persisted alongside temp files for recovery\n- server state is checked before overwrite-sensitive upload completes\n- when server state changed during editing, the user must resolve the conflict rather than silently replacing the file\n\n## Critical Distinction Contributors Must Preserve\n\n- local-drive workflows do not use backend SMB edit locks\n- SMB-backed native-app editing does use backend lock, heartbeat, and upload semantics\n- cross-backend transfers between SMB and local storage are their own browser-mediated flow, not a shortcut through the deep-link edit lifecycle\n- localhost API pairing and HMAC auth are part of the product contract, not replaceable convenience layers\n\nIf you blur these paths, you usually break either security assumptions or data-integrity guarantees.\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/` | localhost API, drive enumeration, auth, pairing, and watcher behavior |\n| `companion/src-tauri/src/commands/open_file.rs` | download and native-app open lifecycle |\n| `companion/src-tauri/src/commands/upload.rs` | upload, lock, and heartbeat support |\n| `companion/src-tauri/src/sync/operations.rs` | operation state and recovery tracking |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion based on connection type |\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome local-drive behavior is intentionally scoped rather than incomplete by accident.\n\n- local direct-open avoids the SMB save-back lifecycle on purpose\n- raw local files are served directly instead of bundling server-style image conversion into the companion path\n- drive scope follows what the current desktop user can already access rather than inventing a separate path-allowlist model by default\n- cross-backend file movement is a separate browser-mediated path because SMB and local-drive backends do not share one native transfer primitive\n\n## Validation Expectations\n\nWhen this pipeline changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe backend checks matter whenever the change touches SMB-backed save-back, lock, heartbeat, or upload behavior.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Local-Drive and Save-Back Pipeline\"\n+++\n\nThe companion supports two different desktop-side data paths.\n\n- paired local-drive access through the localhost API\n- SMB-backed native-app editing with temp files, locks, and explicit save-back\n\nThey are related because the same desktop app participates in both, but they do not share the same trust or data lifecycle.\n\n## Local-Drive Access Pipeline\n\nFor local drives, the browser stays in control and the companion behaves like a desktop-local backend.\n\n1. the browser detects the companion through the localhost health endpoint\n2. browser and companion pair explicitly\n3. the browser requests available drives\n4. the browser routes local-drive browse, file, and file-management requests to the companion instead of the server backend\n5. a companion-side watcher and WebSocket channel keep local directory state fresh\n\nThis is why local drives can appear inside the same UI as SMB shares while still using a different execution path.\n\n## Localhost API Shape\n\nThe companion embeds a localhost HTTP server and mirrors the backend API contract closely enough that the frontend can stay mostly connection-type agnostic.\n\nThe server is bound to `127.0.0.1:21549` and exposes routes under `/api`.\n\nRepresentative endpoints include:\n\n- `GET /api/health`: companion availability and pairing state\n- `POST /api/pair/initiate`: begin pairing\n- `POST /api/pair/confirm`: finish pairing after dual confirmation\n- `GET /api/drives`: enumerate available local drives and volumes\n- `GET /api/browse/{drive}/list`: list a directory\n- `GET /api/browse/{drive}/info`: stat one file or directory\n- `GET /api/browse/{drive}/directories`: search directories recursively\n- `GET /api/viewer/{drive}/file`: stream a file for inline viewing\n- `GET /api/viewer/{drive}/download`: stream a file as a download\n- `POST /api/browse/{drive}/upload`: upload a file into the drive-backed path\n- `DELETE /api/browse/{drive}/item`: delete a file or directory\n- `POST /api/browse/{drive}/rename`: rename a path\n- `POST /api/browse/{drive}/create`: create a file or directory\n- `POST /api/browse/{drive}/copy`: copy within or across local drives\n- `POST /api/browse/{drive}/move`: move within or across local drives\n- `WS /api/ws`: companion-side directory change notifications\n\nResponse shapes intentionally follow the backend contract so the browser can reuse models such as directory listings and file info instead of maintaining a separate local-drive UI protocol.\n\n## Local-Drive Operation Rules\n\n- the companion mirrors the backend API contract closely so the frontend can stay mostly connection-type agnostic\n- local-drive operations use desktop filesystem primitives, not SMB semantics\n- local files opened directly through the companion can skip download, lock, upload, and the \"Done Editing\" flow entirely\n\nAdditional rules that matter in practice:\n\n- image conversion is not part of the companion local-drive path; raw local files are served directly\n- local-drive browsing has no SMB edit-lock semantics\n- same-drive copy and move use local filesystem operations directly\n- cross-backend transfers between SMB and local storage are browser-mediated rather than hidden inside the companion's direct-open flow\n\nThat direct local-open path is intentionally different from SMB-backed native-app editing.\n\n## Drive Enumeration Model\n\nThe companion discovers drives and mounted volumes automatically.\n\nPlatform-specific inputs differ, but the goal is the same: expose what the current desktop user can already access through the normal filesystem.\n\n- Windows: fixed drives, removable drives, mapped drives, and virtual drives exposed through the filesystem\n- macOS: mounted volumes under the normal desktop volume model\n- Linux: mounted filesystems that represent real file content rather than pseudo-filesystems\n\nThat includes cloud-backed or virtual drives when they appear through the OS filesystem layer.\n\nThe browser therefore does not need manual drive configuration. It asks the companion for the current drive list and renders those entries alongside SMB connections.\n\nThe companion should still filter out pseudo-filesystems and other non-file mounts that would only add noise or unsafe paths.\n\n## Browser Routing and Auth Behavior\n\nThe browser uses the same UI for SMB and local drives, but the request path changes underneath.\n\n- SMB-backed requests continue through the main Sambee backend\n- local-drive requests route to the companion localhost API instead\n- the browser detects the companion through the health endpoint\n- once paired, it requests drives and merges them into the connection list as local-drive entries\n\nAuthentication also changes:\n\n- backend requests use the normal server-side auth model\n- companion requests use the pairing-derived HMAC model described in [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/)\n\nThat distinction is critical. Local-drive access is not \"server auth pointed at localhost\". It is a separate authenticated browser-to-desktop channel.\n\n## Local-Drive Watching and WebSockets\n\nThe companion keeps local directory state fresh through its own watcher and WebSocket path.\n\n- the browser opens a companion WebSocket when local-drive behavior is active\n- subscriptions are tracked per directory\n- the companion shares watcher state when possible instead of creating wasteful duplicate watchers\n- local directory changes propagate back into the same browser refresh model used by the file browser\n\nThis is why local drives can participate in the same dual-pane and refresh workflows as SMB connections without pretending the transport is the same.\n\n## SMB-Backed Native-App Save-Back Pipeline\n\nFor SMB-backed native-app editing, the companion is not the source of truth. It is the desktop-side coordinator for a backend-governed editing lifecycle.\n\n1. the browser launches a `sambee://` deep link\n2. the companion exchanges the URI token for a bootstrap token\n3. it fetches metadata and conflict baseline information\n4. it acquires the backend edit lock and receives operation-scoped lock context\n5. it downloads the file to a temp directory\n5. it opens the file in the chosen native application\n6. a \"Done Editing\" window stays open while renewal, heartbeat, and file-status checks continue in the background\n7. on explicit user confirmation, the companion uploads the file or discards it\n8. the backend lock is released and the temp file is recycled\n\n## Why Save-Back Uses Explicit Confirmation\n\nThe save-back model uses explicit user action rather than automatic filesystem watching.\n\nThat avoids a harder class of problems around:\n\n- partial writes and atomic-save behavior\n- repeated intermediate uploads\n- uncertainty about when editing is truly finished\n\nThe hold-to-confirm interaction is therefore a product decision, not just a UI quirk.\n\n## Conflict and Recovery Behavior\n\nThe companion keeps operation state because desktop editing can outlive one clean process lifecycle.\n\n- operation state is persisted alongside temp files for recovery\n- server state is checked before overwrite-sensitive upload completes\n- when server state changed during editing, the user must resolve the conflict rather than silently replacing the file\n\n## Critical Distinction Contributors Must Preserve\n\n- local-drive workflows do not use backend SMB edit locks\n- SMB-backed native-app editing does use backend lock, heartbeat, and upload semantics\n- cross-backend transfers between SMB and local storage are their own browser-mediated flow, not a shortcut through the deep-link edit lifecycle\n- localhost API pairing and HMAC auth are part of the product contract, not replaceable convenience layers\n\nIf you blur these paths, you usually break either security assumptions or data-integrity guarantees.\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/` | localhost API, drive enumeration, auth, pairing, and watcher behavior |\n| `companion/src-tauri/src/commands/open_file.rs` | download and native-app open lifecycle |\n| `companion/src-tauri/src/commands/upload.rs` | upload, lock, and heartbeat support |\n| `companion/src-tauri/src/sync/operations.rs` | operation state and recovery tracking |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion based on connection type |\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome local-drive behavior is intentionally scoped rather than incomplete by accident.\n\n- local direct-open avoids the SMB save-back lifecycle on purpose\n- raw local files are served directly instead of bundling server-style image conversion into the companion path\n- drive scope follows what the current desktop user can already access rather than inventing a separate path-allowlist model by default\n- cross-backend file movement is a separate browser-mediated path because SMB and local-drive backends do not share one native transfer primitive\n\n## Validation Expectations\n\nWhen this pipeline changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe backend checks matter whenever the change touches SMB-backed save-back, lock, heartbeat, or upload behavior.\n", "0.8": "+++\ntitle = \"Local-Drive and Save-Back Pipeline\"\n+++\n\nThe companion supports two different desktop-side data paths.\n\n- paired local-drive access through the localhost API\n- SMB-backed native-app editing with temp files, locks, and explicit save-back\n\nThey are related because the same desktop app participates in both, but they do not share the same trust or data lifecycle.\n\n## Local-Drive Access Pipeline\n\nFor local drives, the browser stays in control and the companion behaves like a desktop-local backend.\n\n1. the browser detects the companion through the localhost health endpoint\n2. browser and companion pair explicitly\n3. the browser requests available drives\n4. the browser routes local-drive browse, file, and file-management requests to the companion instead of the server backend\n5. a companion-side watcher and WebSocket channel keep local directory state fresh\n\nThis is why local drives can appear inside the same UI as SMB shares while still using a different execution path.\n\n## Localhost API Shape\n\nThe companion embeds a localhost HTTP server and mirrors the backend API contract closely enough that the frontend can stay mostly connection-type agnostic.\n\nThe server is bound to `127.0.0.1:21549` and exposes routes under `/api`.\n\nRepresentative endpoints include:\n\n- `GET /api/health`: companion availability\n- `POST /api/pair/initiate`: begin pairing\n- `POST /api/pair/confirm`: finish pairing after dual confirmation\n- `GET /api/pair/status`: origin-scoped browser pairing status\n- `POST /api/pair/cancel`: cancel a pending pairing for the current browser origin\n- `DELETE /api/pair/current`: remove the current browser origin's pairing\n- `GET /api/drives`: enumerate available local drives and volumes\n- `GET /api/browse/{drive}/list`: list a directory\n- `GET /api/browse/{drive}/info`: stat one file or directory\n- `GET /api/browse/{drive}/directories`: search directories recursively\n- `GET /api/viewer/{drive}/file`: stream a file for inline viewing\n- `GET /api/viewer/{drive}/download`: stream a file as a download\n- `POST /api/browse/{drive}/upload`: upload a file into the drive-backed path\n- `DELETE /api/browse/{drive}/item`: delete a file or directory\n- `POST /api/browse/{drive}/rename`: rename a path\n- `POST /api/browse/{drive}/create`: create a file or directory\n- `POST /api/browse/{drive}/copy`: copy within or across local drives\n- `POST /api/browse/{drive}/move`: move within or across local drives\n- `WS /api/ws`: companion-side directory change notifications\n\nResponse shapes intentionally follow the backend contract so the browser can reuse models such as directory listings and file info instead of maintaining a separate local-drive UI protocol.\n\nThe important exception is pairing state: the browser-facing pairing contract is intentionally origin-scoped and typed, rather than exposing a global paired flag or browser-visible inventory of all trusted origins.\n\n## Local-Drive Operation Rules\n\n- the companion mirrors the backend API contract closely so the frontend can stay mostly connection-type agnostic\n- local-drive operations use desktop filesystem primitives, not SMB semantics\n- local files opened directly through the companion can skip download, lock, upload, and the \"Done Editing\" flow entirely\n\nAdditional rules that matter in practice:\n\n- image conversion is not part of the companion local-drive path; raw local files are served directly\n- local-drive browsing has no SMB edit-lock semantics\n- same-drive copy and move use local filesystem operations directly\n- cross-backend transfers between SMB and local storage are browser-mediated rather than hidden inside the companion's direct-open flow\n\nThat direct local-open path is intentionally different from SMB-backed native-app editing.\n\n## Drive Enumeration Model\n\nThe companion discovers drives and mounted volumes automatically.\n\nPlatform-specific inputs differ, but the goal is the same: expose what the current desktop user can already access through the normal filesystem.\n\n- Windows: fixed drives, removable drives, mapped drives, and virtual drives exposed through the filesystem\n- macOS: mounted volumes under the normal desktop volume model\n- Linux: mounted filesystems that represent real file content rather than pseudo-filesystems\n\nThat includes cloud-backed or virtual drives when they appear through the OS filesystem layer.\n\nThe browser therefore does not need manual drive configuration. It asks the companion for the current drive list and renders those entries alongside SMB connections.\n\nThe companion should still filter out pseudo-filesystems and other non-file mounts that would only add noise or unsafe paths.\n\n## Browser Routing and Auth Behavior\n\nThe browser uses the same UI for SMB and local drives, but the request path changes underneath.\n\n- SMB-backed requests continue through the main Sambee backend\n- local-drive requests route to the companion localhost API instead\n- the browser detects the companion through the health endpoint\n- once paired, it requests drives and merges them into the connection list as local-drive entries\n\nAuthentication also changes:\n\n- backend requests use the normal server-side auth model\n- companion requests use the pairing-derived HMAC model described in [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/)\n\nThe localhost bootstrap boundary also changed in an important way:\n\n- production trust is established by exact-origin approval during pairing\n- development remains practical through loopback-origin allowance\n- browser-facing pairing management is limited to the current origin rather than arbitrary origin inventory or deletion\n\nThat distinction is critical. Local-drive access is not \"server auth pointed at localhost\". It is a separate authenticated browser-to-desktop channel.\n\n## Local-Drive Watching and WebSockets\n\nThe companion keeps local directory state fresh through its own watcher and WebSocket path.\n\n- the browser opens a companion WebSocket when local-drive behavior is active\n- subscriptions are tracked per directory\n- the companion shares watcher state when possible instead of creating wasteful duplicate watchers\n- local directory changes propagate back into the same browser refresh model used by the file browser\n\nThis is why local drives can participate in the same dual-pane and refresh workflows as SMB connections without pretending the transport is the same.\n\n## SMB-Backed Native-App Save-Back Pipeline\n\nFor SMB-backed native-app editing, the companion is not the source of truth. It is the desktop-side coordinator for a backend-governed editing lifecycle.\n\n1. the browser launches a `sambee://` deep link\n2. the companion exchanges the URI token for an authenticated session\n3. it fetches metadata and downloads the file to a temp directory\n4. it acquires the backend edit lock\n5. it opens the file in the chosen native application\n6. a \"Done Editing\" window stays open while heartbeat and file-status checks continue in the background\n7. on explicit user confirmation, the companion uploads the file or discards it\n8. the backend lock is released and the temp file is recycled\n\n## Why Save-Back Uses Explicit Confirmation\n\nThe save-back model uses explicit user action rather than automatic filesystem watching.\n\nThat avoids a harder class of problems around:\n\n- partial writes and atomic-save behavior\n- repeated intermediate uploads\n- uncertainty about when editing is truly finished\n\nThe hold-to-confirm interaction is therefore a product decision, not just a UI quirk.\n\n## Conflict and Recovery Behavior\n\nThe companion keeps operation state because desktop editing can outlive one clean process lifecycle.\n\n- operation state is persisted alongside temp files for recovery\n- server state is checked before overwrite-sensitive upload completes\n- when server state changed during editing, the user must resolve the conflict rather than silently replacing the file\n\n## Critical Distinction Contributors Must Preserve\n\n- local-drive workflows do not use backend SMB edit locks\n- SMB-backed native-app editing does use backend lock, heartbeat, and upload semantics\n- cross-backend transfers between SMB and local storage are their own browser-mediated flow, not a shortcut through the deep-link edit lifecycle\n- localhost API pairing and HMAC auth are part of the product contract, not replaceable convenience layers\n\nIf you blur these paths, you usually break either security assumptions or data-integrity guarantees.\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/` | localhost API, drive enumeration, auth, pairing, and watcher behavior |\n| `companion/src-tauri/src/commands/open_file.rs` | download and native-app open lifecycle |\n| `companion/src-tauri/src/commands/upload.rs` | upload, lock, and heartbeat support |\n| `companion/src-tauri/src/sync/operations.rs` | operation state and recovery tracking |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion based on connection type |\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome local-drive behavior is intentionally scoped rather than incomplete by accident.\n\n- local direct-open avoids the SMB save-back lifecycle on purpose\n- raw local files are served directly instead of bundling server-style image conversion into the companion path\n- drive scope follows what the current desktop user can already access rather than inventing a separate path-allowlist model by default\n- cross-backend file movement is a separate browser-mediated path because SMB and local-drive backends do not share one native transfer primitive\n\n## Validation Expectations\n\nWhen this pipeline changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe backend checks matter whenever the change touches SMB-backed save-back, lock, heartbeat, or upload behavior.\n", "0.9": "+++\ntitle = \"Local-Drive and Save-Back Pipeline\"\n+++\n\nThe companion supports two different desktop-side data paths.\n\n- paired local-drive access through the localhost API\n- SMB-backed native-app editing with temp files, locks, and explicit save-back\n\nThey are related because the same desktop app participates in both, but they do not share the same trust or data lifecycle.\n\n## Local-Drive Access Pipeline\n\nFor local drives, the browser stays in control and the companion behaves like a desktop-local backend.\n\n1. the browser detects the companion through the localhost health endpoint\n2. browser and companion pair explicitly\n3. the browser requests available drives\n4. the browser routes local-drive browse, file, and file-management requests to the companion instead of the server backend\n5. a companion-side watcher and WebSocket channel keep local directory state fresh\n\nThis is why local drives can appear inside the same UI as SMB shares while still using a different execution path.\n\n## Localhost API Shape\n\nThe companion embeds a localhost HTTP server and mirrors the backend API contract closely enough that the frontend can stay mostly connection-type agnostic.\n\nThe server is bound to `127.0.0.1:21549` and exposes routes under `/api`.\n\nRepresentative endpoints include:\n\n- `GET /api/health`: companion availability\n- `POST /api/pair/initiate`: begin pairing\n- `POST /api/pair/confirm`: finish pairing after dual confirmation\n- `GET /api/pair/status`: origin-scoped browser pairing status\n- `POST /api/pair/cancel`: cancel a pending pairing for the current browser origin\n- `DELETE /api/pair/current`: remove the current browser origin's pairing\n- `GET /api/drives`: enumerate available local drives and volumes\n- `GET /api/browse/{drive}/list`: list a directory\n- `GET /api/browse/{drive}/info`: stat one file or directory\n- `GET /api/browse/{drive}/directories`: search directories recursively\n- `GET /api/viewer/{drive}/file`: stream a file for inline viewing\n- `GET /api/viewer/{drive}/download`: stream a file as a download\n- `POST /api/browse/{drive}/upload`: upload a file into the drive-backed path\n- `DELETE /api/browse/{drive}/item`: delete a file or directory\n- `POST /api/browse/{drive}/rename`: rename a path\n- `POST /api/browse/{drive}/create`: create a file or directory\n- `POST /api/browse/{drive}/copy`: copy within or across local drives\n- `POST /api/browse/{drive}/move`: move within or across local drives\n- `WS /api/ws`: companion-side directory change notifications\n\nResponse shapes intentionally follow the backend contract so the browser can reuse models such as directory listings and file info instead of maintaining a separate local-drive UI protocol.\n\nThe important exception is pairing state: the browser-facing pairing contract is intentionally origin-scoped and typed, rather than exposing a global paired flag or browser-visible inventory of all trusted origins.\n\n## Local-Drive Operation Rules\n\n- the companion mirrors the backend API contract closely so the frontend can stay mostly connection-type agnostic\n- local-drive operations use desktop filesystem primitives, not SMB semantics\n- local files opened directly through the companion can skip download, lock, upload, and the \"Done Editing\" flow entirely\n\nAdditional rules that matter in practice:\n\n- image conversion is not part of the companion local-drive path; raw local files are served directly\n- local-drive browsing has no SMB edit-lock semantics\n- same-drive copy and move use local filesystem operations directly\n- cross-backend transfers between SMB and local storage are browser-mediated rather than hidden inside the companion's direct-open flow\n\nThat direct local-open path is intentionally different from SMB-backed native-app editing.\n\n## Drive Enumeration Model\n\nThe companion discovers drives and mounted volumes automatically.\n\nPlatform-specific inputs differ, but the goal is the same: expose what the current desktop user can already access through the normal filesystem.\n\n- Windows: fixed drives, removable drives, mapped drives, and virtual drives exposed through the filesystem\n- macOS: mounted volumes under the normal desktop volume model\n- Linux: mounted filesystems that represent real file content rather than pseudo-filesystems\n\nThat includes cloud-backed or virtual drives when they appear through the OS filesystem layer.\n\nThe browser therefore does not need manual drive configuration. It asks the companion for the current drive list and renders those entries alongside SMB connections.\n\nThe companion should still filter out pseudo-filesystems and other non-file mounts that would only add noise or unsafe paths.\n\n## Browser Routing and Auth Behavior\n\nThe browser uses the same UI for SMB and local drives, but the request path changes underneath.\n\n- SMB-backed requests continue through the main Sambee backend\n- local-drive requests route to the companion localhost API instead\n- the browser detects the companion through the health endpoint\n- once paired, it requests drives and merges them into the connection list as local-drive entries\n\nAuthentication also changes:\n\n- backend requests use the normal server-side auth model\n- companion requests use the pairing-derived HMAC model described in [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/)\n\nThe localhost bootstrap boundary also changed in an important way:\n\n- production trust is established by exact-origin approval during pairing\n- development remains practical through loopback-origin allowance\n- browser-facing pairing management is limited to the current origin rather than arbitrary origin inventory or deletion\n\nThat distinction is critical. Local-drive access is not \"server auth pointed at localhost\". It is a separate authenticated browser-to-desktop channel.\n\n## Local-Drive Watching and WebSockets\n\nThe companion keeps local directory state fresh through its own watcher and WebSocket path.\n\n- the browser opens a companion WebSocket when local-drive behavior is active\n- subscriptions are tracked per directory\n- the companion shares watcher state when possible instead of creating wasteful duplicate watchers\n- local directory changes propagate back into the same browser refresh model used by the file browser\n\nThis is why local drives can participate in the same dual-pane and refresh workflows as SMB connections without pretending the transport is the same.\n\n## SMB-Backed Native-App Save-Back Pipeline\n\nFor SMB-backed native-app editing, the companion is not the source of truth. It is the desktop-side coordinator for a backend-governed editing lifecycle.\n\n1. the browser launches a `sambee://` deep link\n2. the companion exchanges the URI token for an authenticated session\n3. it fetches metadata and downloads the file to a temp directory\n4. it acquires the backend edit lock\n5. it opens the file in the chosen native application\n6. a \"Done Editing\" window stays open while heartbeat and file-status checks continue in the background\n7. on explicit user confirmation, the companion uploads the file or discards it\n8. the backend lock is released and the temp file is recycled\n\n## Why Save-Back Uses Explicit Confirmation\n\nThe save-back model uses explicit user action rather than automatic filesystem watching.\n\nThat avoids a harder class of problems around:\n\n- partial writes and atomic-save behavior\n- repeated intermediate uploads\n- uncertainty about when editing is truly finished\n\nThe hold-to-confirm interaction is therefore a product decision, not just a UI quirk.\n\n## Conflict and Recovery Behavior\n\nThe companion keeps operation state because desktop editing can outlive one clean process lifecycle.\n\n- operation state is persisted alongside temp files for recovery\n- server state is checked before overwrite-sensitive upload completes\n- when server state changed during editing, the user must resolve the conflict rather than silently replacing the file\n\n## Critical Distinction Contributors Must Preserve\n\n- local-drive workflows do not use backend SMB edit locks\n- SMB-backed native-app editing does use backend lock, heartbeat, and upload semantics\n- cross-backend transfers between SMB and local storage are their own browser-mediated flow, not a shortcut through the deep-link edit lifecycle\n- localhost API pairing and HMAC auth are part of the product contract, not replaceable convenience layers\n\nIf you blur these paths, you usually break either security assumptions or data-integrity guarantees.\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/` | localhost API, drive enumeration, auth, pairing, and watcher behavior |\n| `companion/src-tauri/src/commands/open_file.rs` | download and native-app open lifecycle |\n| `companion/src-tauri/src/commands/upload.rs` | upload, lock, and heartbeat support |\n| `companion/src-tauri/src/sync/operations.rs` | operation state and recovery tracking |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion based on connection type |\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome local-drive behavior is intentionally scoped rather than incomplete by accident.\n\n- local direct-open avoids the SMB save-back lifecycle on purpose\n- raw local files are served directly instead of bundling server-style image conversion into the companion path\n- drive scope follows what the current desktop user can already access rather than inventing a separate path-allowlist model by default\n- cross-backend file movement is a separate browser-mediated path because SMB and local-drive backends do not share one native transfer primitive\n\n## Validation Expectations\n\nWhen this pipeline changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe backend checks matter whenever the change touches SMB-backed save-back, lock, heartbeat, or upload behavior.\n", "1.0": "+++\ntitle = \"Local-Drive and Save-Back Pipeline\"\n+++\n\nThe companion supports two different desktop-side data paths.\n\n- paired local-drive access through the localhost API\n- SMB-backed native-app editing with temp files, locks, and explicit save-back\n\nThey are related because the same desktop app participates in both, but they do not share the same trust or data lifecycle.\n\n## Local-Drive Access Pipeline\n\nFor local drives, the browser stays in control and the companion behaves like a desktop-local backend.\n\n1. the browser detects the companion through the localhost health endpoint\n2. browser and companion pair explicitly\n3. the browser requests available drives\n4. the browser routes local-drive browse, file, and file-management requests to the companion instead of the server backend\n5. a companion-side watcher and WebSocket channel keep local directory state fresh\n\nThis is why local drives can appear inside the same UI as SMB shares while still using a different execution path.\n\n## Localhost API Shape\n\nThe companion embeds a localhost HTTP server and mirrors the backend API contract closely enough that the frontend can stay mostly connection-type agnostic.\n\nThe server is bound to `127.0.0.1:21549` and exposes routes under `/api`.\n\nRepresentative endpoints include:\n\n- `GET /api/health`: companion availability\n- `POST /api/pair/initiate`: begin pairing\n- `POST /api/pair/confirm`: finish pairing after dual confirmation\n- `GET /api/pair/status`: origin-scoped browser pairing status\n- `POST /api/pair/cancel`: cancel a pending pairing for the current browser origin\n- `DELETE /api/pair/current`: remove the current browser origin's pairing\n- `GET /api/drives`: enumerate available local drives and volumes\n- `GET /api/browse/{drive}/list`: list a directory\n- `GET /api/browse/{drive}/info`: stat one file or directory\n- `GET /api/browse/{drive}/directories`: search directories recursively\n- `GET /api/viewer/{drive}/file`: stream a file for inline viewing\n- `GET /api/viewer/{drive}/download`: stream a file as a download\n- `POST /api/browse/{drive}/upload`: upload a file into the drive-backed path\n- `DELETE /api/browse/{drive}/item`: delete a file or directory\n- `POST /api/browse/{drive}/rename`: rename a path\n- `POST /api/browse/{drive}/create`: create a file or directory\n- `POST /api/browse/{drive}/copy`: copy within or across local drives\n- `POST /api/browse/{drive}/move`: move within or across local drives\n- `WS /api/ws`: companion-side directory change notifications\n\nResponse shapes intentionally follow the backend contract so the browser can reuse models such as directory listings and file info instead of maintaining a separate local-drive UI protocol.\n\nThe important exception is pairing state: the browser-facing pairing contract is intentionally origin-scoped and typed, rather than exposing a global paired flag or browser-visible inventory of all trusted origins.\n\n## Local-Drive Operation Rules\n\n- the companion mirrors the backend API contract closely so the frontend can stay mostly connection-type agnostic\n- local-drive operations use desktop filesystem primitives, not SMB semantics\n- local files opened directly through the companion can skip download, lock, upload, and the \"Done Editing\" flow entirely\n\nAdditional rules that matter in practice:\n\n- image conversion is not part of the companion local-drive path; raw local files are served directly\n- local-drive browsing has no SMB edit-lock semantics\n- same-drive copy and move use local filesystem operations directly\n- cross-backend transfers between SMB and local storage are browser-mediated rather than hidden inside the companion's direct-open flow\n\nThat direct local-open path is intentionally different from SMB-backed native-app editing.\n\n## Drive Enumeration Model\n\nThe companion discovers drives and mounted volumes automatically.\n\nPlatform-specific inputs differ, but the goal is the same: expose what the current desktop user can already access through the normal filesystem.\n\n- Windows: fixed drives, removable drives, mapped drives, and virtual drives exposed through the filesystem\n- macOS: mounted volumes under the normal desktop volume model\n- Linux: mounted filesystems that represent real file content rather than pseudo-filesystems\n\nThat includes cloud-backed or virtual drives when they appear through the OS filesystem layer.\n\nThe browser therefore does not need manual drive configuration. It asks the companion for the current drive list and renders those entries alongside SMB connections.\n\nThe companion should still filter out pseudo-filesystems and other non-file mounts that would only add noise or unsafe paths.\n\n## Browser Routing and Auth Behavior\n\nThe browser uses the same UI for SMB and local drives, but the request path changes underneath.\n\n- SMB-backed requests continue through the main Sambee backend\n- local-drive requests route to the companion localhost API instead\n- the browser detects the companion through the health endpoint\n- once paired, it requests drives and merges them into the connection list as local-drive entries\n\nAuthentication also changes:\n\n- backend requests use the normal server-side auth model\n- companion requests use the pairing-derived HMAC model described in [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/)\n\nThe localhost bootstrap boundary also changed in an important way:\n\n- production trust is established by exact-origin approval during pairing\n- development remains practical through loopback-origin allowance\n- browser-facing pairing management is limited to the current origin rather than arbitrary origin inventory or deletion\n\nThat distinction is critical. Local-drive access is not \"server auth pointed at localhost\". It is a separate authenticated browser-to-desktop channel.\n\n## Local-Drive Watching and WebSockets\n\nThe companion keeps local directory state fresh through its own watcher and WebSocket path.\n\n- the browser opens a companion WebSocket when local-drive behavior is active\n- subscriptions are tracked per directory\n- the companion shares watcher state when possible instead of creating wasteful duplicate watchers\n- local directory changes propagate back into the same browser refresh model used by the file browser\n\nThis is why local drives can participate in the same dual-pane and refresh workflows as SMB connections without pretending the transport is the same.\n\n## SMB-Backed Native-App Save-Back Pipeline\n\nFor SMB-backed native-app editing, the companion is not the source of truth. It is the desktop-side coordinator for a backend-governed editing lifecycle.\n\n1. the browser launches a `sambee://` deep link\n2. the companion exchanges the URI token for an authenticated session\n3. it fetches metadata and downloads the file to a temp directory\n4. it acquires the backend edit lock\n5. it opens the file in the chosen native application\n6. a \"Done Editing\" window stays open while heartbeat and file-status checks continue in the background\n7. on explicit user confirmation, the companion uploads the file or discards it\n8. the backend lock is released and the temp file is recycled\n\n## Why Save-Back Uses Explicit Confirmation\n\nThe save-back model uses explicit user action rather than automatic filesystem watching.\n\nThat avoids a harder class of problems around:\n\n- partial writes and atomic-save behavior\n- repeated intermediate uploads\n- uncertainty about when editing is truly finished\n\nThe hold-to-confirm interaction is therefore a product decision, not just a UI quirk.\n\n## Conflict and Recovery Behavior\n\nThe companion keeps operation state because desktop editing can outlive one clean process lifecycle.\n\n- operation state is persisted alongside temp files for recovery\n- server state is checked before overwrite-sensitive upload completes\n- when server state changed during editing, the user must resolve the conflict rather than silently replacing the file\n\n## Critical Distinction Contributors Must Preserve\n\n- local-drive workflows do not use backend SMB edit locks\n- SMB-backed native-app editing does use backend lock, heartbeat, and upload semantics\n- cross-backend transfers between SMB and local storage are their own browser-mediated flow, not a shortcut through the deep-link edit lifecycle\n- localhost API pairing and HMAC auth are part of the product contract, not replaceable convenience layers\n\nIf you blur these paths, you usually break either security assumptions or data-integrity guarantees.\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/` | localhost API, drive enumeration, auth, pairing, and watcher behavior |\n| `companion/src-tauri/src/commands/open_file.rs` | download and native-app open lifecycle |\n| `companion/src-tauri/src/commands/upload.rs` | upload, lock, and heartbeat support |\n| `companion/src-tauri/src/sync/operations.rs` | operation state and recovery tracking |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion based on connection type |\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome local-drive behavior is intentionally scoped rather than incomplete by accident.\n\n- local direct-open avoids the SMB save-back lifecycle on purpose\n- raw local files are served directly instead of bundling server-style image conversion into the companion path\n- drive scope follows what the current desktop user can already access rather than inventing a separate path-allowlist model by default\n- cross-backend file movement is a separate browser-mediated path because SMB and local-drive backends do not share one native transfer primitive\n\n## Validation Expectations\n\nWhen this pipeline changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe backend checks matter whenever the change touches SMB-backed save-back, lock, heartbeat, or upload behavior.\n", "2.0": "+++\ntitle = \"Local-Drive and Save-Back Pipeline\"\n+++\n\nThe companion supports two different desktop-side data paths.\n\n- paired local-drive access through the localhost API\n- SMB-backed native-app editing with temp files, locks, and explicit save-back\n\nThey are related because the same desktop app participates in both, but they do not share the same trust or data lifecycle.\n\n## Local-Drive Access Pipeline\n\nFor local drives, the browser stays in control and the companion behaves like a desktop-local backend.\n\n1. the browser detects the companion through the localhost health endpoint\n2. browser and companion pair explicitly\n3. the browser requests available drives\n4. the browser routes local-drive browse, file, and file-management requests to the companion instead of the server backend\n5. a companion-side watcher and WebSocket channel keep local directory state fresh\n\nThis is why local drives can appear inside the same UI as SMB shares while still using a different execution path.\n\n## Localhost API Shape\n\nThe companion embeds a localhost HTTP server and mirrors the backend API contract closely enough that the frontend can stay mostly connection-type agnostic.\n\nThe server is bound to `127.0.0.1:21549` and exposes routes under `/api`.\n\nRepresentative endpoints include:\n\n- `GET /api/health`: companion availability\n- `POST /api/pair/initiate`: begin pairing\n- `POST /api/pair/confirm`: finish pairing after dual confirmation\n- `GET /api/pair/status`: origin-scoped browser pairing status\n- `POST /api/pair/cancel`: cancel a pending pairing for the current browser origin\n- `DELETE /api/pair/current`: remove the current browser origin's pairing\n- `GET /api/drives`: enumerate available local drives and volumes\n- `GET /api/browse/{drive}/list`: list a directory\n- `GET /api/browse/{drive}/info`: stat one file or directory\n- `GET /api/browse/{drive}/directories`: search directories recursively\n- `GET /api/viewer/{drive}/file`: stream a file for inline viewing\n- `GET /api/viewer/{drive}/download`: stream a file as a download\n- `POST /api/browse/{drive}/upload`: upload a file into the drive-backed path\n- `DELETE /api/browse/{drive}/item`: delete a file or directory\n- `POST /api/browse/{drive}/rename`: rename a path\n- `POST /api/browse/{drive}/create`: create a file or directory\n- `POST /api/browse/{drive}/copy`: copy within or across local drives\n- `POST /api/browse/{drive}/move`: move within or across local drives\n- `WS /api/ws`: companion-side directory change notifications\n\nResponse shapes intentionally follow the backend contract so the browser can reuse models such as directory listings and file info instead of maintaining a separate local-drive UI protocol.\n\nThe important exception is pairing state: the browser-facing pairing contract is intentionally origin-scoped and typed, rather than exposing a global paired flag or browser-visible inventory of all trusted origins.\n\n## Local-Drive Operation Rules\n\n- the companion mirrors the backend API contract closely so the frontend can stay mostly connection-type agnostic\n- local-drive operations use desktop filesystem primitives, not SMB semantics\n- local files opened directly through the companion can skip download, lock, upload, and the \"Done Editing\" flow entirely\n\nAdditional rules that matter in practice:\n\n- image conversion is not part of the companion local-drive path; raw local files are served directly\n- local-drive browsing has no SMB edit-lock semantics\n- same-drive copy and move use local filesystem operations directly\n- cross-backend transfers between SMB and local storage are browser-mediated rather than hidden inside the companion's direct-open flow\n\nThat direct local-open path is intentionally different from SMB-backed native-app editing.\n\n## Drive Enumeration Model\n\nThe companion discovers drives and mounted volumes automatically.\n\nPlatform-specific inputs differ, but the goal is the same: expose what the current desktop user can already access through the normal filesystem.\n\n- Windows: fixed drives, removable drives, mapped drives, and virtual drives exposed through the filesystem\n- macOS: mounted volumes under the normal desktop volume model\n- Linux: mounted filesystems that represent real file content rather than pseudo-filesystems\n\nThat includes cloud-backed or virtual drives when they appear through the OS filesystem layer.\n\nThe browser therefore does not need manual drive configuration. It asks the companion for the current drive list and renders those entries alongside SMB connections.\n\nThe companion should still filter out pseudo-filesystems and other non-file mounts that would only add noise or unsafe paths.\n\n## Browser Routing and Auth Behavior\n\nThe browser uses the same UI for SMB and local drives, but the request path changes underneath.\n\n- SMB-backed requests continue through the main Sambee backend\n- local-drive requests route to the companion localhost API instead\n- the browser detects the companion through the health endpoint\n- once paired, it requests drives and merges them into the connection list as local-drive entries\n\nAuthentication also changes:\n\n- backend requests use the normal server-side auth model\n- companion requests use the pairing-derived HMAC model described in [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/)\n\nThe localhost bootstrap boundary also changed in an important way:\n\n- production trust is established by exact-origin approval during pairing\n- development remains practical through loopback-origin allowance\n- browser-facing pairing management is limited to the current origin rather than arbitrary origin inventory or deletion\n\nThat distinction is critical. Local-drive access is not \"server auth pointed at localhost\". It is a separate authenticated browser-to-desktop channel.\n\n## Local-Drive Watching and WebSockets\n\nThe companion keeps local directory state fresh through its own watcher and WebSocket path.\n\n- the browser opens a companion WebSocket when local-drive behavior is active\n- subscriptions are tracked per directory\n- the companion shares watcher state when possible instead of creating wasteful duplicate watchers\n- local directory changes propagate back into the same browser refresh model used by the file browser\n\nThis is why local drives can participate in the same dual-pane and refresh workflows as SMB connections without pretending the transport is the same.\n\n## SMB-Backed Native-App Save-Back Pipeline\n\nFor SMB-backed native-app editing, the companion is not the source of truth. It is the desktop-side coordinator for a backend-governed editing lifecycle.\n\n1. the browser launches a `sambee://` deep link\n2. the companion exchanges the URI token for an authenticated session\n3. it fetches metadata and downloads the file to a temp directory\n4. it acquires the backend edit lock\n5. it opens the file in the chosen native application\n6. a \"Done Editing\" window stays open while heartbeat and file-status checks continue in the background\n7. on explicit user confirmation, the companion uploads the file or discards it\n8. the backend lock is released and the temp file is recycled\n\n## Why Save-Back Uses Explicit Confirmation\n\nThe save-back model uses explicit user action rather than automatic filesystem watching.\n\nThat avoids a harder class of problems around:\n\n- partial writes and atomic-save behavior\n- repeated intermediate uploads\n- uncertainty about when editing is truly finished\n\nThe hold-to-confirm interaction is therefore a product decision, not just a UI quirk.\n\n## Conflict and Recovery Behavior\n\nThe companion keeps operation state because desktop editing can outlive one clean process lifecycle.\n\n- operation state is persisted alongside temp files for recovery\n- server state is checked before overwrite-sensitive upload completes\n- when server state changed during editing, the user must resolve the conflict rather than silently replacing the file\n\n## Critical Distinction Contributors Must Preserve\n\n- local-drive workflows do not use backend SMB edit locks\n- SMB-backed native-app editing does use backend lock, heartbeat, and upload semantics\n- cross-backend transfers between SMB and local storage are their own browser-mediated flow, not a shortcut through the deep-link edit lifecycle\n- localhost API pairing and HMAC auth are part of the product contract, not replaceable convenience layers\n\nIf you blur these paths, you usually break either security assumptions or data-integrity guarantees.\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/` | localhost API, drive enumeration, auth, pairing, and watcher behavior |\n| `companion/src-tauri/src/commands/open_file.rs` | download and native-app open lifecycle |\n| `companion/src-tauri/src/commands/upload.rs` | upload, lock, and heartbeat support |\n| `companion/src-tauri/src/sync/operations.rs` | operation state and recovery tracking |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion based on connection type |\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome local-drive behavior is intentionally scoped rather than incomplete by accident.\n\n- local direct-open avoids the SMB save-back lifecycle on purpose\n- raw local files are served directly instead of bundling server-style image conversion into the companion path\n- drive scope follows what the current desktop user can already access rather than inventing a separate path-allowlist model by default\n- cross-backend file movement is a separate browser-mediated path because SMB and local-drive backends do not share one native transfer primitive\n\n## Validation Expectations\n\nWhen this pipeline changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe backend checks matter whenever the change touches SMB-backed save-back, lock, heartbeat, or upload behavior.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:developer-guide/cross-cutting-systems", "parent_id": "book:developer-guide", "depth": 1, "kind": "section", "label": "cross-cutting-systems", "title": "Cross-Cutting Systems", "path": "developer-guide/cross-cutting-systems", "has_children": true, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Cross-Cutting Systems\"\n+++\n\nSome Sambee behaviors are shared systems rather than one-team implementation details.\n\nStart with:\n\n- [Logging and Localization](./logging-and-localization/)\n- [Localization and Locale Behavior](./localization-and-locale-behavior/)\n- [Frontend Logging and Tracing](./frontend-logging-and-tracing/)\n\nUse this section when a change spans the browser app, backend, or companion and you need one consistent rule set instead of app-by-app drift.\n", "0.8": "+++\ntitle = \"Cross-Cutting Systems\"\n+++\n\nSome Sambee behaviors are shared systems rather than one-team implementation details.\n\nStart with:\n\n- [Logging and Localization](./logging-and-localization/)\n- [Localization and Locale Behavior](./localization-and-locale-behavior/)\n- [Frontend Logging and Tracing](./frontend-logging-and-tracing/)\n\nUse this section when a change spans the browser app, backend, or companion and you need one consistent rule set instead of app-by-app drift.\n", "0.9": "+++\ntitle = \"Cross-Cutting Systems\"\n+++\n\nSome Sambee behaviors are shared systems rather than one-team implementation details.\n\nStart with:\n\n- [Logging and Localization](./logging-and-localization/)\n- [Localization and Locale Behavior](./localization-and-locale-behavior/)\n- [Frontend Logging and Tracing](./frontend-logging-and-tracing/)\n\nUse this section when a change spans the browser app, backend, or companion and you need one consistent rule set instead of app-by-app drift.\n", "1.0": "+++\ntitle = \"Cross-Cutting Systems\"\n+++\n\nSome Sambee behaviors are shared systems rather than one-team implementation details.\n\nStart with:\n\n- [Logging and Localization](./logging-and-localization/)\n- [Localization and Locale Behavior](./localization-and-locale-behavior/)\n- [Frontend Logging and Tracing](./frontend-logging-and-tracing/)\n\nUse this section when a change spans the browser app, backend, or companion and you need one consistent rule set instead of app-by-app drift.\n", "2.0": "+++\ntitle = \"Cross-Cutting Systems\"\n+++\n\nSome Sambee behaviors are shared systems rather than one-team implementation details.\n\nStart with:\n\n- [Logging and Localization](./logging-and-localization/)\n- [Localization and Locale Behavior](./localization-and-locale-behavior/)\n- [Frontend Logging and Tracing](./frontend-logging-and-tracing/)\n\nUse this section when a change spans the browser app, backend, or companion and you need one consistent rule set instead of app-by-app drift.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/cross-cutting-systems/logging-and-localization", "parent_id": "section:developer-guide/cross-cutting-systems", "depth": 2, "kind": "page", "label": "logging-and-localization", "title": "Logging And Localization", "path": "developer-guide/cross-cutting-systems/logging-and-localization", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "branched", "source_version": "0.7", "diff_added": 43, "diff_removed": 22}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "inherited", "source_version": "0.9"}}, "content_versions": {"0.7": "+++\ntitle = \"Logging and Localization\"\n+++\n\nLogging and localization are both cross-boundary product systems in Sambee.\n\n- logging affects local debugging, operator visibility, and backend trace collection\n- localization affects typed UI copy, locale behavior, browser formatting, and browser-to-companion sync\n\nTreat both as shared contracts rather than optional polish.\n\n## Logging Model\n\nSambee uses more than one logging surface, but the goal is still one coherent diagnostic story.\n\n### Browser App Logging\n\nThe browser app supports both:\n\n- console logging for local development and debugging\n- backend tracing for server-side log collection when production or mobile debugging needs it\n\nThat means a logging change can affect both developer ergonomics and support visibility.\n\n### Companion and Service-Side Logging\n\nThe companion has its own desktop-side logging path, and operational logs are still important on the backend and in local development scripts.\n\n- use the shared logging utilities where the app already has them\n- keep log messages specific enough to be actionable\n- avoid replacing structured or filtered logging with scattered ad hoc output\n\nFor local environment diagnosis, the repo also provides supported log and service-status scripts instead of relying entirely on manual process inspection.\n\n## Localization Model\n\nLocalization is a typed system, not just a string file.\n\n### Sources of Truth\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Typed wrappers | each app's `i18n/index.ts` layer |\n\nEnglish is the source locale, and the pseudo-locale is generated automatically from the English tree.\n\n### Contributor Rules\n\n- add new UI strings through the translation resources instead of hard-coding copy\n- keep translation keys type-safe instead of casting around the type system\n- preserve the distinction between UI language and regional formatting behavior\n- remember that the browser app can push its effective locale into the companion through the paired localhost API\n\n## What Contributors Must Preserve\n\n### Logging\n\n- browser app logging and backend tracing are related but separately configurable\n- logging changes should not silently remove trace visibility that support workflows depend on\n- diagnostics should stay specific and action-oriented\n\n### Localization\n\n- typed keys should remain enforced\n- browser-localization behavior and companion-localization sync should keep using effective locale values rather than raw unresolved preferences\n- app-owned UI text should stay translatable\n\nFor the concrete contributor workflow, continue to [Localization and Locale Behavior](../localization-and-locale-behavior/).\n\n## Common Failure Modes\n\n- adding UI text without a translation key\n- bypassing typed translation keys with casts\n- changing localization behavior in the browser app without checking companion sync effects\n- switching logging behavior in a way that helps local debugging but breaks backend tracing or support visibility\n- flooding logs with noisy messages that hide the actionable ones\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\n```\n\nFor higher-confidence changes, add the relevant frontend or companion tests, especially when localization sync or logging configuration behavior changes.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) to decide when those cross-boundary checks need to extend further.\n", "0.8": "+++\ntitle = \"Logging and Localization\"\n+++\n\nLogging and localization are both cross-boundary product systems in Sambee.\n\n- logging affects local debugging, operator visibility, and backend trace collection\n- localization affects typed UI copy, locale behavior, browser formatting, and browser-to-companion sync\n\nTreat both as shared contracts rather than optional polish.\n\n## Logging Model\n\nSambee uses more than one logging surface, but the goal is still one coherent diagnostic story.\n\n### Browser App Logging\n\nThe browser app supports both:\n\n- console logging for local development and debugging\n- backend tracing for server-side log collection when production or mobile debugging needs it\n\nThat means a logging change can affect both developer ergonomics and support visibility.\n\n### Companion and Service-Side Logging\n\nThe companion has its own desktop-side logging path, and operational logs are still important on the backend and in local development scripts.\n\n- use the shared logging utilities where the app already has them\n- keep log messages specific enough to be actionable\n- avoid replacing structured or filtered logging with scattered ad hoc output\n\nFor local environment diagnosis, the repo also provides supported log and service-status scripts instead of relying entirely on manual process inspection.\n\n## Localization Model\n\nLocalization is a typed system, not just a string file.\n\n### Sources of Truth\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Typed wrappers | each app's `i18n/index.ts` layer |\n\nEnglish is the source locale, and the pseudo-locale is generated automatically from the English tree.\n\n### Contributor Rules\n\n- add new UI strings through the translation resources instead of hard-coding copy\n- keep translation keys type-safe instead of casting around the type system\n- preserve the distinction between UI language and regional formatting behavior\n- remember that the browser app can push its effective locale into the companion through the paired localhost API\n\n## What Contributors Must Preserve\n\n### Logging\n\n- browser app logging and backend tracing are related but separately configurable\n- logging changes should not silently remove trace visibility that support workflows depend on\n- diagnostics should stay specific and action-oriented\n\n### Localization\n\n- typed keys should remain enforced\n- browser-localization behavior and companion-localization sync should keep using effective locale values rather than raw unresolved preferences\n- app-owned UI text should stay translatable\n\nFor the concrete contributor workflow, continue to [Localization and Locale Behavior](../localization-and-locale-behavior/).\n\n## Common Failure Modes\n\n- adding UI text without a translation key\n- bypassing typed translation keys with casts\n- changing localization behavior in the browser app without checking companion sync effects\n- switching logging behavior in a way that helps local debugging but breaks backend tracing or support visibility\n- flooding logs with noisy messages that hide the actionable ones\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\n```\n\nFor higher-confidence changes, add the relevant frontend or companion tests, especially when localization sync or logging configuration behavior changes.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) to decide when those cross-boundary checks need to extend further.\n", "0.9": "+++\ntitle = \"Logging and Localization\"\n+++\n\nLogging and localization are both cross-boundary product systems in Sambee.\n\n- Logging affects local debugging, operator visibility, and backend trace collection.\n- Localization affects typed UI copy, locale behavior, browser formatting, and browser-to-companion sync.\n\nTreat both as shared contracts rather than optional polish.\n\n## Logging Model\n\nSambee uses more than one logging surface, but the goal is still one coherent diagnostic story.\n\n### Backend Logging\n\nThe backend sends logs to standard output so they are available through Docker or the process supervisor. Configure the backend in the `[app]` section of `config.toml`:\n\n```toml\n[app]\nlog_level = \"INFO\"\naccess_log_level = \"WARNING\"\nprotocol_log_level = \"WARNING\"\n```\n\n| Key | Controls | Default |\n|---|---|---|\n| `log_level` | Application diagnostics and Uvicorn startup, shutdown, and error messages. | `INFO` |\n| `access_log_level` | Uvicorn HTTP request access records. | `WARNING` |\n| `protocol_log_level` | Uvicorn WebSocket connection, frame, and keepalive records. | `WARNING` |\n\nAll three settings accept `DEBUG`, `INFO`, `WARNING`, or `ERROR`, regardless of case. The default access and protocol levels keep successful requests, WebSocket payloads, and ping traffic out of normal operational logs while retaining application lifecycle and error messages.\n\nSet `access_log_level` to `INFO` when request auditing is needed. Set `protocol_log_level` to `DEBUG` only while diagnosing WebSocket communication; it includes sent and received frames as well as keepalive messages and can be very verbose.\n\n### Browser App Logging\n\nThe browser app supports both:\n\n- Console logging for local development and debugging.\n- Backend tracing for server-side log collection when production or mobile debugging needs it.\n\nThat means a logging change can affect both developer ergonomics and support visibility.\n\n### Companion and Service-Side Logging\n\nThe companion has its own desktop-side logging path, and operational logs are still important on the backend and in local development scripts.\n\n- Use the shared logging utilities where the app already has them.\n- Keep log messages specific enough to be actionable.\n- Avoid replacing structured or filtered logging with scattered ad hoc output.\n\nFor local environment diagnosis, the repo also provides supported log and service-status scripts instead of relying entirely on manual process inspection.\n\n## Localization Model\n\nLocalization is a typed system, not just a string file.\n\n### Sources of Truth\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Typed wrappers | each app's `i18n/index.ts` layer |\n\nEnglish is the source locale, and the pseudo-locale is generated automatically from the English tree.\n\n### Contributor Rules\n\n- Add new UI strings through the translation resources instead of hard-coding copy.\n- Keep translation keys type-safe instead of casting around the type system.\n- Preserve the distinction between UI language and regional formatting behavior.\n- Remember that the browser app can push its effective locale into the companion through the paired localhost API.\n\n## What Contributors Must Preserve\n\n### Logging\n\n- Browser app logging and backend tracing are related but separately configurable.\n- Logging changes should not silently remove trace visibility that support workflows depend on.\n- Diagnostics should stay specific and action-oriented.\n\n### Localization\n\n- Typed keys should remain enforced.\n- Browser-localization behavior and companion-localization sync should keep using effective locale values rather than raw unresolved preferences.\n- App-owned UI text should stay translatable.\n\nFor the concrete contributor workflow, continue to [Localization and Locale Behavior](../localization-and-locale-behavior/).\n\n## Common Failure Modes\n\n- Adding UI text without a translation key.\n- Bypassing typed translation keys with casts.\n- Changing localization behavior in the browser app without checking companion sync effects.\n- Switching logging behavior in a way that helps local debugging but breaks backend tracing or support visibility.\n- Flooding logs with noisy messages that hide the actionable ones.\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\n```\n\nFor higher-confidence changes, add the relevant frontend or companion tests, especially when localization sync or logging configuration behavior changes.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) to decide when those cross-boundary checks need to extend further.", "1.0": "+++\ntitle = \"Logging and Localization\"\n+++\n\nLogging and localization are both cross-boundary product systems in Sambee.\n\n- Logging affects local debugging, operator visibility, and backend trace collection.\n- Localization affects typed UI copy, locale behavior, browser formatting, and browser-to-companion sync.\n\nTreat both as shared contracts rather than optional polish.\n\n## Logging Model\n\nSambee uses more than one logging surface, but the goal is still one coherent diagnostic story.\n\n### Backend Logging\n\nThe backend sends logs to standard output so they are available through Docker or the process supervisor. Configure the backend in the `[app]` section of `config.toml`:\n\n```toml\n[app]\nlog_level = \"INFO\"\naccess_log_level = \"WARNING\"\nprotocol_log_level = \"WARNING\"\n```\n\n| Key | Controls | Default |\n|---|---|---|\n| `log_level` | Application diagnostics and Uvicorn startup, shutdown, and error messages. | `INFO` |\n| `access_log_level` | Uvicorn HTTP request access records. | `WARNING` |\n| `protocol_log_level` | Uvicorn WebSocket connection, frame, and keepalive records. | `WARNING` |\n\nAll three settings accept `DEBUG`, `INFO`, `WARNING`, or `ERROR`, regardless of case. The default access and protocol levels keep successful requests, WebSocket payloads, and ping traffic out of normal operational logs while retaining application lifecycle and error messages.\n\nSet `access_log_level` to `INFO` when request auditing is needed. Set `protocol_log_level` to `DEBUG` only while diagnosing WebSocket communication; it includes sent and received frames as well as keepalive messages and can be very verbose.\n\n### Browser App Logging\n\nThe browser app supports both:\n\n- Console logging for local development and debugging.\n- Backend tracing for server-side log collection when production or mobile debugging needs it.\n\nThat means a logging change can affect both developer ergonomics and support visibility.\n\n### Companion and Service-Side Logging\n\nThe companion has its own desktop-side logging path, and operational logs are still important on the backend and in local development scripts.\n\n- Use the shared logging utilities where the app already has them.\n- Keep log messages specific enough to be actionable.\n- Avoid replacing structured or filtered logging with scattered ad hoc output.\n\nFor local environment diagnosis, the repo also provides supported log and service-status scripts instead of relying entirely on manual process inspection.\n\n## Localization Model\n\nLocalization is a typed system, not just a string file.\n\n### Sources of Truth\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Typed wrappers | each app's `i18n/index.ts` layer |\n\nEnglish is the source locale, and the pseudo-locale is generated automatically from the English tree.\n\n### Contributor Rules\n\n- Add new UI strings through the translation resources instead of hard-coding copy.\n- Keep translation keys type-safe instead of casting around the type system.\n- Preserve the distinction between UI language and regional formatting behavior.\n- Remember that the browser app can push its effective locale into the companion through the paired localhost API.\n\n## What Contributors Must Preserve\n\n### Logging\n\n- Browser app logging and backend tracing are related but separately configurable.\n- Logging changes should not silently remove trace visibility that support workflows depend on.\n- Diagnostics should stay specific and action-oriented.\n\n### Localization\n\n- Typed keys should remain enforced.\n- Browser-localization behavior and companion-localization sync should keep using effective locale values rather than raw unresolved preferences.\n- App-owned UI text should stay translatable.\n\nFor the concrete contributor workflow, continue to [Localization and Locale Behavior](../localization-and-locale-behavior/).\n\n## Common Failure Modes\n\n- Adding UI text without a translation key.\n- Bypassing typed translation keys with casts.\n- Changing localization behavior in the browser app without checking companion sync effects.\n- Switching logging behavior in a way that helps local debugging but breaks backend tracing or support visibility.\n- Flooding logs with noisy messages that hide the actionable ones.\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\n```\n\nFor higher-confidence changes, add the relevant frontend or companion tests, especially when localization sync or logging configuration behavior changes.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) to decide when those cross-boundary checks need to extend further.", "2.0": "+++\ntitle = \"Logging and Localization\"\n+++\n\nLogging and localization are both cross-boundary product systems in Sambee.\n\n- Logging affects local debugging, operator visibility, and backend trace collection.\n- Localization affects typed UI copy, locale behavior, browser formatting, and browser-to-companion sync.\n\nTreat both as shared contracts rather than optional polish.\n\n## Logging Model\n\nSambee uses more than one logging surface, but the goal is still one coherent diagnostic story.\n\n### Backend Logging\n\nThe backend sends logs to standard output so they are available through Docker or the process supervisor. Configure the backend in the `[app]` section of `config.toml`:\n\n```toml\n[app]\nlog_level = \"INFO\"\naccess_log_level = \"WARNING\"\nprotocol_log_level = \"WARNING\"\n```\n\n| Key | Controls | Default |\n|---|---|---|\n| `log_level` | Application diagnostics and Uvicorn startup, shutdown, and error messages. | `INFO` |\n| `access_log_level` | Uvicorn HTTP request access records. | `WARNING` |\n| `protocol_log_level` | Uvicorn WebSocket connection, frame, and keepalive records. | `WARNING` |\n\nAll three settings accept `DEBUG`, `INFO`, `WARNING`, or `ERROR`, regardless of case. The default access and protocol levels keep successful requests, WebSocket payloads, and ping traffic out of normal operational logs while retaining application lifecycle and error messages.\n\nSet `access_log_level` to `INFO` when request auditing is needed. Set `protocol_log_level` to `DEBUG` only while diagnosing WebSocket communication; it includes sent and received frames as well as keepalive messages and can be very verbose.\n\n### Browser App Logging\n\nThe browser app supports both:\n\n- Console logging for local development and debugging.\n- Backend tracing for server-side log collection when production or mobile debugging needs it.\n\nThat means a logging change can affect both developer ergonomics and support visibility.\n\n### Companion and Service-Side Logging\n\nThe companion has its own desktop-side logging path, and operational logs are still important on the backend and in local development scripts.\n\n- Use the shared logging utilities where the app already has them.\n- Keep log messages specific enough to be actionable.\n- Avoid replacing structured or filtered logging with scattered ad hoc output.\n\nFor local environment diagnosis, the repo also provides supported log and service-status scripts instead of relying entirely on manual process inspection.\n\n## Localization Model\n\nLocalization is a typed system, not just a string file.\n\n### Sources of Truth\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Typed wrappers | each app's `i18n/index.ts` layer |\n\nEnglish is the source locale, and the pseudo-locale is generated automatically from the English tree.\n\n### Contributor Rules\n\n- Add new UI strings through the translation resources instead of hard-coding copy.\n- Keep translation keys type-safe instead of casting around the type system.\n- Preserve the distinction between UI language and regional formatting behavior.\n- Remember that the browser app can push its effective locale into the companion through the paired localhost API.\n\n## What Contributors Must Preserve\n\n### Logging\n\n- Browser app logging and backend tracing are related but separately configurable.\n- Logging changes should not silently remove trace visibility that support workflows depend on.\n- Diagnostics should stay specific and action-oriented.\n\n### Localization\n\n- Typed keys should remain enforced.\n- Browser-localization behavior and companion-localization sync should keep using effective locale values rather than raw unresolved preferences.\n- App-owned UI text should stay translatable.\n\nFor the concrete contributor workflow, continue to [Localization and Locale Behavior](../localization-and-locale-behavior/).\n\n## Common Failure Modes\n\n- Adding UI text without a translation key.\n- Bypassing typed translation keys with casts.\n- Changing localization behavior in the browser app without checking companion sync effects.\n- Switching logging behavior in a way that helps local debugging but breaks backend tracing or support visibility.\n- Flooding logs with noisy messages that hide the actionable ones.\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\n```\n\nFor higher-confidence changes, add the relevant frontend or companion tests, especially when localization sync or logging configuration behavior changes.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) to decide when those cross-boundary checks need to extend further."}, "page_contents": {"0.7": "+++\ntitle = \"Logging and Localization\"\n+++\n\nLogging and localization are both cross-boundary product systems in Sambee.\n\n- logging affects local debugging, operator visibility, and backend trace collection\n- localization affects typed UI copy, locale behavior, browser formatting, and browser-to-companion sync\n\nTreat both as shared contracts rather than optional polish.\n\n## Logging Model\n\nSambee uses more than one logging surface, but the goal is still one coherent diagnostic story.\n\n### Browser App Logging\n\nThe browser app supports both:\n\n- console logging for local development and debugging\n- backend tracing for server-side log collection when production or mobile debugging needs it\n\nThat means a logging change can affect both developer ergonomics and support visibility.\n\n### Companion and Service-Side Logging\n\nThe companion has its own desktop-side logging path, and operational logs are still important on the backend and in local development scripts.\n\n- use the shared logging utilities where the app already has them\n- keep log messages specific enough to be actionable\n- avoid replacing structured or filtered logging with scattered ad hoc output\n\nFor local environment diagnosis, the repo also provides supported log and service-status scripts instead of relying entirely on manual process inspection.\n\n## Localization Model\n\nLocalization is a typed system, not just a string file.\n\n### Sources of Truth\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Typed wrappers | each app's `i18n/index.ts` layer |\n\nEnglish is the source locale, and the pseudo-locale is generated automatically from the English tree.\n\n### Contributor Rules\n\n- add new UI strings through the translation resources instead of hard-coding copy\n- keep translation keys type-safe instead of casting around the type system\n- preserve the distinction between UI language and regional formatting behavior\n- remember that the browser app can push its effective locale into the companion through the paired localhost API\n\n## What Contributors Must Preserve\n\n### Logging\n\n- browser app logging and backend tracing are related but separately configurable\n- logging changes should not silently remove trace visibility that support workflows depend on\n- diagnostics should stay specific and action-oriented\n\n### Localization\n\n- typed keys should remain enforced\n- browser-localization behavior and companion-localization sync should keep using effective locale values rather than raw unresolved preferences\n- app-owned UI text should stay translatable\n\nFor the concrete contributor workflow, continue to [Localization and Locale Behavior](../localization-and-locale-behavior/).\n\n## Common Failure Modes\n\n- adding UI text without a translation key\n- bypassing typed translation keys with casts\n- changing localization behavior in the browser app without checking companion sync effects\n- switching logging behavior in a way that helps local debugging but breaks backend tracing or support visibility\n- flooding logs with noisy messages that hide the actionable ones\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\n```\n\nFor higher-confidence changes, add the relevant frontend or companion tests, especially when localization sync or logging configuration behavior changes.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) to decide when those cross-boundary checks need to extend further.\n", "0.8": "+++\ntitle = \"Logging and Localization\"\n+++\n\nLogging and localization are both cross-boundary product systems in Sambee.\n\n- logging affects local debugging, operator visibility, and backend trace collection\n- localization affects typed UI copy, locale behavior, browser formatting, and browser-to-companion sync\n\nTreat both as shared contracts rather than optional polish.\n\n## Logging Model\n\nSambee uses more than one logging surface, but the goal is still one coherent diagnostic story.\n\n### Browser App Logging\n\nThe browser app supports both:\n\n- console logging for local development and debugging\n- backend tracing for server-side log collection when production or mobile debugging needs it\n\nThat means a logging change can affect both developer ergonomics and support visibility.\n\n### Companion and Service-Side Logging\n\nThe companion has its own desktop-side logging path, and operational logs are still important on the backend and in local development scripts.\n\n- use the shared logging utilities where the app already has them\n- keep log messages specific enough to be actionable\n- avoid replacing structured or filtered logging with scattered ad hoc output\n\nFor local environment diagnosis, the repo also provides supported log and service-status scripts instead of relying entirely on manual process inspection.\n\n## Localization Model\n\nLocalization is a typed system, not just a string file.\n\n### Sources of Truth\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Typed wrappers | each app's `i18n/index.ts` layer |\n\nEnglish is the source locale, and the pseudo-locale is generated automatically from the English tree.\n\n### Contributor Rules\n\n- add new UI strings through the translation resources instead of hard-coding copy\n- keep translation keys type-safe instead of casting around the type system\n- preserve the distinction between UI language and regional formatting behavior\n- remember that the browser app can push its effective locale into the companion through the paired localhost API\n\n## What Contributors Must Preserve\n\n### Logging\n\n- browser app logging and backend tracing are related but separately configurable\n- logging changes should not silently remove trace visibility that support workflows depend on\n- diagnostics should stay specific and action-oriented\n\n### Localization\n\n- typed keys should remain enforced\n- browser-localization behavior and companion-localization sync should keep using effective locale values rather than raw unresolved preferences\n- app-owned UI text should stay translatable\n\nFor the concrete contributor workflow, continue to [Localization and Locale Behavior](../localization-and-locale-behavior/).\n\n## Common Failure Modes\n\n- adding UI text without a translation key\n- bypassing typed translation keys with casts\n- changing localization behavior in the browser app without checking companion sync effects\n- switching logging behavior in a way that helps local debugging but breaks backend tracing or support visibility\n- flooding logs with noisy messages that hide the actionable ones\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\n```\n\nFor higher-confidence changes, add the relevant frontend or companion tests, especially when localization sync or logging configuration behavior changes.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) to decide when those cross-boundary checks need to extend further.\n", "0.9": "+++\ntitle = \"Logging and Localization\"\n+++\n\nLogging and localization are both cross-boundary product systems in Sambee.\n\n- Logging affects local debugging, operator visibility, and backend trace collection.\n- Localization affects typed UI copy, locale behavior, browser formatting, and browser-to-companion sync.\n\nTreat both as shared contracts rather than optional polish.\n\n## Logging Model\n\nSambee uses more than one logging surface, but the goal is still one coherent diagnostic story.\n\n### Backend Logging\n\nThe backend sends logs to standard output so they are available through Docker or the process supervisor. Configure the backend in the `[app]` section of `config.toml`:\n\n```toml\n[app]\nlog_level = \"INFO\"\naccess_log_level = \"WARNING\"\nprotocol_log_level = \"WARNING\"\n```\n\n| Key | Controls | Default |\n|---|---|---|\n| `log_level` | Application diagnostics and Uvicorn startup, shutdown, and error messages. | `INFO` |\n| `access_log_level` | Uvicorn HTTP request access records. | `WARNING` |\n| `protocol_log_level` | Uvicorn WebSocket connection, frame, and keepalive records. | `WARNING` |\n\nAll three settings accept `DEBUG`, `INFO`, `WARNING`, or `ERROR`, regardless of case. The default access and protocol levels keep successful requests, WebSocket payloads, and ping traffic out of normal operational logs while retaining application lifecycle and error messages.\n\nSet `access_log_level` to `INFO` when request auditing is needed. Set `protocol_log_level` to `DEBUG` only while diagnosing WebSocket communication; it includes sent and received frames as well as keepalive messages and can be very verbose.\n\n### Browser App Logging\n\nThe browser app supports both:\n\n- Console logging for local development and debugging.\n- Backend tracing for server-side log collection when production or mobile debugging needs it.\n\nThat means a logging change can affect both developer ergonomics and support visibility.\n\n### Companion and Service-Side Logging\n\nThe companion has its own desktop-side logging path, and operational logs are still important on the backend and in local development scripts.\n\n- Use the shared logging utilities where the app already has them.\n- Keep log messages specific enough to be actionable.\n- Avoid replacing structured or filtered logging with scattered ad hoc output.\n\nFor local environment diagnosis, the repo also provides supported log and service-status scripts instead of relying entirely on manual process inspection.\n\n## Localization Model\n\nLocalization is a typed system, not just a string file.\n\n### Sources of Truth\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Typed wrappers | each app's `i18n/index.ts` layer |\n\nEnglish is the source locale, and the pseudo-locale is generated automatically from the English tree.\n\n### Contributor Rules\n\n- Add new UI strings through the translation resources instead of hard-coding copy.\n- Keep translation keys type-safe instead of casting around the type system.\n- Preserve the distinction between UI language and regional formatting behavior.\n- Remember that the browser app can push its effective locale into the companion through the paired localhost API.\n\n## What Contributors Must Preserve\n\n### Logging\n\n- Browser app logging and backend tracing are related but separately configurable.\n- Logging changes should not silently remove trace visibility that support workflows depend on.\n- Diagnostics should stay specific and action-oriented.\n\n### Localization\n\n- Typed keys should remain enforced.\n- Browser-localization behavior and companion-localization sync should keep using effective locale values rather than raw unresolved preferences.\n- App-owned UI text should stay translatable.\n\nFor the concrete contributor workflow, continue to [Localization and Locale Behavior](../localization-and-locale-behavior/).\n\n## Common Failure Modes\n\n- Adding UI text without a translation key.\n- Bypassing typed translation keys with casts.\n- Changing localization behavior in the browser app without checking companion sync effects.\n- Switching logging behavior in a way that helps local debugging but breaks backend tracing or support visibility.\n- Flooding logs with noisy messages that hide the actionable ones.\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\n```\n\nFor higher-confidence changes, add the relevant frontend or companion tests, especially when localization sync or logging configuration behavior changes.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) to decide when those cross-boundary checks need to extend further.", "1.0": "+++\ntitle = \"Logging and Localization\"\n+++\n\nLogging and localization are both cross-boundary product systems in Sambee.\n\n- Logging affects local debugging, operator visibility, and backend trace collection.\n- Localization affects typed UI copy, locale behavior, browser formatting, and browser-to-companion sync.\n\nTreat both as shared contracts rather than optional polish.\n\n## Logging Model\n\nSambee uses more than one logging surface, but the goal is still one coherent diagnostic story.\n\n### Backend Logging\n\nThe backend sends logs to standard output so they are available through Docker or the process supervisor. Configure the backend in the `[app]` section of `config.toml`:\n\n```toml\n[app]\nlog_level = \"INFO\"\naccess_log_level = \"WARNING\"\nprotocol_log_level = \"WARNING\"\n```\n\n| Key | Controls | Default |\n|---|---|---|\n| `log_level` | Application diagnostics and Uvicorn startup, shutdown, and error messages. | `INFO` |\n| `access_log_level` | Uvicorn HTTP request access records. | `WARNING` |\n| `protocol_log_level` | Uvicorn WebSocket connection, frame, and keepalive records. | `WARNING` |\n\nAll three settings accept `DEBUG`, `INFO`, `WARNING`, or `ERROR`, regardless of case. The default access and protocol levels keep successful requests, WebSocket payloads, and ping traffic out of normal operational logs while retaining application lifecycle and error messages.\n\nSet `access_log_level` to `INFO` when request auditing is needed. Set `protocol_log_level` to `DEBUG` only while diagnosing WebSocket communication; it includes sent and received frames as well as keepalive messages and can be very verbose.\n\n### Browser App Logging\n\nThe browser app supports both:\n\n- Console logging for local development and debugging.\n- Backend tracing for server-side log collection when production or mobile debugging needs it.\n\nThat means a logging change can affect both developer ergonomics and support visibility.\n\n### Companion and Service-Side Logging\n\nThe companion has its own desktop-side logging path, and operational logs are still important on the backend and in local development scripts.\n\n- Use the shared logging utilities where the app already has them.\n- Keep log messages specific enough to be actionable.\n- Avoid replacing structured or filtered logging with scattered ad hoc output.\n\nFor local environment diagnosis, the repo also provides supported log and service-status scripts instead of relying entirely on manual process inspection.\n\n## Localization Model\n\nLocalization is a typed system, not just a string file.\n\n### Sources of Truth\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Typed wrappers | each app's `i18n/index.ts` layer |\n\nEnglish is the source locale, and the pseudo-locale is generated automatically from the English tree.\n\n### Contributor Rules\n\n- Add new UI strings through the translation resources instead of hard-coding copy.\n- Keep translation keys type-safe instead of casting around the type system.\n- Preserve the distinction between UI language and regional formatting behavior.\n- Remember that the browser app can push its effective locale into the companion through the paired localhost API.\n\n## What Contributors Must Preserve\n\n### Logging\n\n- Browser app logging and backend tracing are related but separately configurable.\n- Logging changes should not silently remove trace visibility that support workflows depend on.\n- Diagnostics should stay specific and action-oriented.\n\n### Localization\n\n- Typed keys should remain enforced.\n- Browser-localization behavior and companion-localization sync should keep using effective locale values rather than raw unresolved preferences.\n- App-owned UI text should stay translatable.\n\nFor the concrete contributor workflow, continue to [Localization and Locale Behavior](../localization-and-locale-behavior/).\n\n## Common Failure Modes\n\n- Adding UI text without a translation key.\n- Bypassing typed translation keys with casts.\n- Changing localization behavior in the browser app without checking companion sync effects.\n- Switching logging behavior in a way that helps local debugging but breaks backend tracing or support visibility.\n- Flooding logs with noisy messages that hide the actionable ones.\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\n```\n\nFor higher-confidence changes, add the relevant frontend or companion tests, especially when localization sync or logging configuration behavior changes.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) to decide when those cross-boundary checks need to extend further.", "2.0": "+++\ntitle = \"Logging and Localization\"\n+++\n\nLogging and localization are both cross-boundary product systems in Sambee.\n\n- Logging affects local debugging, operator visibility, and backend trace collection.\n- Localization affects typed UI copy, locale behavior, browser formatting, and browser-to-companion sync.\n\nTreat both as shared contracts rather than optional polish.\n\n## Logging Model\n\nSambee uses more than one logging surface, but the goal is still one coherent diagnostic story.\n\n### Backend Logging\n\nThe backend sends logs to standard output so they are available through Docker or the process supervisor. Configure the backend in the `[app]` section of `config.toml`:\n\n```toml\n[app]\nlog_level = \"INFO\"\naccess_log_level = \"WARNING\"\nprotocol_log_level = \"WARNING\"\n```\n\n| Key | Controls | Default |\n|---|---|---|\n| `log_level` | Application diagnostics and Uvicorn startup, shutdown, and error messages. | `INFO` |\n| `access_log_level` | Uvicorn HTTP request access records. | `WARNING` |\n| `protocol_log_level` | Uvicorn WebSocket connection, frame, and keepalive records. | `WARNING` |\n\nAll three settings accept `DEBUG`, `INFO`, `WARNING`, or `ERROR`, regardless of case. The default access and protocol levels keep successful requests, WebSocket payloads, and ping traffic out of normal operational logs while retaining application lifecycle and error messages.\n\nSet `access_log_level` to `INFO` when request auditing is needed. Set `protocol_log_level` to `DEBUG` only while diagnosing WebSocket communication; it includes sent and received frames as well as keepalive messages and can be very verbose.\n\n### Browser App Logging\n\nThe browser app supports both:\n\n- Console logging for local development and debugging.\n- Backend tracing for server-side log collection when production or mobile debugging needs it.\n\nThat means a logging change can affect both developer ergonomics and support visibility.\n\n### Companion and Service-Side Logging\n\nThe companion has its own desktop-side logging path, and operational logs are still important on the backend and in local development scripts.\n\n- Use the shared logging utilities where the app already has them.\n- Keep log messages specific enough to be actionable.\n- Avoid replacing structured or filtered logging with scattered ad hoc output.\n\nFor local environment diagnosis, the repo also provides supported log and service-status scripts instead of relying entirely on manual process inspection.\n\n## Localization Model\n\nLocalization is a typed system, not just a string file.\n\n### Sources of Truth\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Typed wrappers | each app's `i18n/index.ts` layer |\n\nEnglish is the source locale, and the pseudo-locale is generated automatically from the English tree.\n\n### Contributor Rules\n\n- Add new UI strings through the translation resources instead of hard-coding copy.\n- Keep translation keys type-safe instead of casting around the type system.\n- Preserve the distinction between UI language and regional formatting behavior.\n- Remember that the browser app can push its effective locale into the companion through the paired localhost API.\n\n## What Contributors Must Preserve\n\n### Logging\n\n- Browser app logging and backend tracing are related but separately configurable.\n- Logging changes should not silently remove trace visibility that support workflows depend on.\n- Diagnostics should stay specific and action-oriented.\n\n### Localization\n\n- Typed keys should remain enforced.\n- Browser-localization behavior and companion-localization sync should keep using effective locale values rather than raw unresolved preferences.\n- App-owned UI text should stay translatable.\n\nFor the concrete contributor workflow, continue to [Localization and Locale Behavior](../localization-and-locale-behavior/).\n\n## Common Failure Modes\n\n- Adding UI text without a translation key.\n- Bypassing typed translation keys with casts.\n- Changing localization behavior in the browser app without checking companion sync effects.\n- Switching logging behavior in a way that helps local debugging but breaks backend tracing or support visibility.\n- Flooding logs with noisy messages that hide the actionable ones.\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\n```\n\nFor higher-confidence changes, add the relevant frontend or companion tests, especially when localization sync or logging configuration behavior changes.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) to decide when those cross-boundary checks need to extend further."}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/cross-cutting-systems/localization-and-locale-behavior", "parent_id": "section:developer-guide/cross-cutting-systems", "depth": 2, "kind": "page", "label": "localization-and-locale-behavior", "title": "Localization And Locale Behavior", "path": "developer-guide/cross-cutting-systems/localization-and-locale-behavior", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Localization and Locale Behavior\"\n+++\n\nLocalization in Sambee is a typed cross-app system. It affects UI copy, browser formatting, and browser-to-companion behavior.\n\nUse this page when you are adding copy, changing locale behavior, or touching browser-to-companion localization sync.\n\n## Sources of Truth\n\nThese files own the localization model:\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Browser app typed wrapper | `frontend/src/i18n/index.ts` |\n| Companion typed wrapper | `companion/src/i18n/index.ts` |\n\nEnglish is the source locale.\n\nThe pseudo-locale `en-XA` is generated from the English translation tree. Do not edit pseudo-locale strings manually.\n\n## Adding New UI Copy\n\nWhen you add new copy:\n\n1. add the English key to the relevant `EN_TRANSLATIONS` tree\n2. use that key from UI code instead of hard-coding a string\n3. use the existing translation access pattern for the surface you are editing\n4. add or extend tests when the copy sits in a reused or high-risk surface\n\nTypical access patterns are:\n\n- browser app React components: `useTranslation()`\n- browser app non-component helpers or config: `translate(...)`\n- companion components: `useI18n()` or `translate(...)`\n\n## Type-Safety Rules\n\nTyped translation keys are part of the contract.\n\n- translation keys are type-checked through the i18n type layer\n- invalid keys should fail TypeScript compilation\n- do not bypass that with casts to `string` or `any`\n- keep wrapper signatures typed instead of weakening them for convenience\n\nIf localization typing becomes optional, contributors lose one of the main protections against copy drift and key mismatches.\n\n## Compile-Time Guard Fixtures\n\nThese files exist specifically to catch regressions in localization typing:\n\n- `frontend/src/i18n/__tests__/typecheck.ts`\n- `companion/src/i18n/__tests__/typecheck.ts`\n\nThey intentionally include both:\n\n- valid translation calls that must compile\n- invalid keys marked with `@ts-expect-error` that must stay invalid\n\nIf a change weakens typed keys, these fixtures should fail type checking.\n\n## Language Versus Regional Formatting\n\nSambee separates UI language from regional formatting.\n\n- language decides which translated copy the UI shows\n- regional formatting decides how dates, numbers, and sorting behave\n\nThat split matters because users may want English UI with non-US formatting, or any other mixed combination the product supports.\n\n## Preference Storage Rules\n\nFrontend language and regional formatting preferences are stored separately.\n\n- language preference lives in `localization.language` in current-user settings and is mirrored in local storage under the app locale key\n- regional formatting preference lives in `localization.regional_locale` in current-user settings and is mirrored in local storage under `sambee.regional-locale`\n- `browser` is the default for both preferences\n\n`browser` means:\n\n- UI language resolves from the browser locale list against the supported translation set\n- regional formatting resolves from the browser locale while preserving variants such as `en-GB` versus `en-US`\n\n## Runtime Locale Behavior\n\nBoth apps keep document locale metadata aligned with the active locale.\n\n- `document.documentElement.lang` stays synchronized\n- text direction stays synchronized through `dir`\n\nFrontend date, number, and sorting behavior should use the locale-aware helpers instead of raw browser-default formatting.\n\nPrefer:\n\n- `frontend/src/utils/localeFormatting.ts`\n\nFrontend React trees that depend on localization preferences should be wrapped in:\n\n- `frontend/src/i18n/LocalePreferencesProvider.tsx`\n\nThe user-facing preferences UI lives in:\n\n- `frontend/src/pages/PreferencesSettings.tsx`\n\n## Browser-to-Companion Localization Sync\n\nWhen the browser is paired with Sambee Companion, the browser pushes its effective localization state to the companion over the authenticated localhost API.\n\nImportant rules:\n\n- sync uses concrete effective locale values, not unresolved `browser` preferences\n- the companion therefore receives resolved values such as `en` or `en-GB`\n- companion localization is persisted on the Rust side and mirrored into companion local storage for fast startup\n- synchronization is global within the desktop app\n- last-writer-wins behavior is based on the browser-provided `updated_at` timestamp\n- persisted companion state also records the source browser origin\n- open companion windows listen for localization update events and apply the new locale immediately\n\nIf you change the browser-side locale model, you must check the companion sync path too.\n\n## Scope Rules\n\n- translate app-owned UI strings\n- do not translate raw backend error payloads or third-party library messages unless Sambee wraps them in its own copy\n- decorative glyphs are fine when they are not the only user-facing label\n\n## Common Failure Modes\n\n- adding UI text without a translation key\n- weakening typed-key enforcement with casts\n- changing browser locale behavior without checking companion sync\n- treating language preference and formatting preference as the same value\n- using browser-default formatting instead of the shared locale-aware helpers\n\n## Validation Expectations\n\nFor routine localization changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nFor higher-confidence UI changes, also run the relevant frontend or companion tests.\n\nFor browser-to-companion localization sync changes, also validate:\n\n```bash\ncd frontend \u0026\u0026 npm test -- src/services/__tests__/companionService.test.ts\ncd companion \u0026\u0026 npm test -- src/i18n/__tests__/index.test.ts src/components/__tests__/Preferences.test.tsx\n```\n", "0.8": "+++\ntitle = \"Localization and Locale Behavior\"\n+++\n\nLocalization in Sambee is a typed cross-app system. It affects UI copy, browser formatting, and browser-to-companion behavior.\n\nUse this page when you are adding copy, changing locale behavior, or touching browser-to-companion localization sync.\n\n## Sources of Truth\n\nThese files own the localization model:\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Browser app typed wrapper | `frontend/src/i18n/index.ts` |\n| Companion typed wrapper | `companion/src/i18n/index.ts` |\n\nEnglish is the source locale.\n\nThe pseudo-locale `en-XA` is generated from the English translation tree. Do not edit pseudo-locale strings manually.\n\n## Adding New UI Copy\n\nWhen you add new copy:\n\n1. add the English key to the relevant `EN_TRANSLATIONS` tree\n2. use that key from UI code instead of hard-coding a string\n3. use the existing translation access pattern for the surface you are editing\n4. add or extend tests when the copy sits in a reused or high-risk surface\n\nTypical access patterns are:\n\n- browser app React components: `useTranslation()`\n- browser app non-component helpers or config: `translate(...)`\n- companion components: `useI18n()` or `translate(...)`\n\n## Type-Safety Rules\n\nTyped translation keys are part of the contract.\n\n- translation keys are type-checked through the i18n type layer\n- invalid keys should fail TypeScript compilation\n- do not bypass that with casts to `string` or `any`\n- keep wrapper signatures typed instead of weakening them for convenience\n\nIf localization typing becomes optional, contributors lose one of the main protections against copy drift and key mismatches.\n\n## Compile-Time Guard Fixtures\n\nThese files exist specifically to catch regressions in localization typing:\n\n- `frontend/src/i18n/__tests__/typecheck.ts`\n- `companion/src/i18n/__tests__/typecheck.ts`\n\nThey intentionally include both:\n\n- valid translation calls that must compile\n- invalid keys marked with `@ts-expect-error` that must stay invalid\n\nIf a change weakens typed keys, these fixtures should fail type checking.\n\n## Language Versus Regional Formatting\n\nSambee separates UI language from regional formatting.\n\n- language decides which translated copy the UI shows\n- regional formatting decides how dates, numbers, and sorting behave\n\nThat split matters because users may want English UI with non-US formatting, or any other mixed combination the product supports.\n\n## Preference Storage Rules\n\nFrontend language and regional formatting preferences are stored separately.\n\n- language preference lives in `localization.language` in current-user settings and is mirrored in local storage under the app locale key\n- regional formatting preference lives in `localization.regional_locale` in current-user settings and is mirrored in local storage under `sambee.regional-locale`\n- `browser` is the default for both preferences\n\n`browser` means:\n\n- UI language resolves from the browser locale list against the supported translation set\n- regional formatting resolves from the browser locale while preserving variants such as `en-GB` versus `en-US`\n\n## Runtime Locale Behavior\n\nBoth apps keep document locale metadata aligned with the active locale.\n\n- `document.documentElement.lang` stays synchronized\n- text direction stays synchronized through `dir`\n\nFrontend date, number, and sorting behavior should use the locale-aware helpers instead of raw browser-default formatting.\n\nPrefer:\n\n- `frontend/src/utils/localeFormatting.ts`\n\nFrontend React trees that depend on localization preferences should be wrapped in:\n\n- `frontend/src/i18n/LocalePreferencesProvider.tsx`\n\nThe user-facing preferences UI lives in:\n\n- `frontend/src/pages/PreferencesSettings.tsx`\n\n## Browser-to-Companion Localization Sync\n\nWhen the browser is paired with Sambee Companion, the browser pushes its effective localization state to the companion over the authenticated localhost API.\n\nImportant rules:\n\n- sync uses concrete effective locale values, not unresolved `browser` preferences\n- the companion therefore receives resolved values such as `en` or `en-GB`\n- companion localization is persisted on the Rust side and mirrored into companion local storage for fast startup\n- synchronization is global within the desktop app\n- last-writer-wins behavior is based on the browser-provided `updated_at` timestamp\n- persisted companion state also records the source browser origin\n- open companion windows listen for localization update events and apply the new locale immediately\n\nIf you change the browser-side locale model, you must check the companion sync path too.\n\n## Scope Rules\n\n- translate app-owned UI strings\n- do not translate raw backend error payloads or third-party library messages unless Sambee wraps them in its own copy\n- decorative glyphs are fine when they are not the only user-facing label\n\n## Common Failure Modes\n\n- adding UI text without a translation key\n- weakening typed-key enforcement with casts\n- changing browser locale behavior without checking companion sync\n- treating language preference and formatting preference as the same value\n- using browser-default formatting instead of the shared locale-aware helpers\n\n## Validation Expectations\n\nFor routine localization changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nFor higher-confidence UI changes, also run the relevant frontend or companion tests.\n\nFor browser-to-companion localization sync changes, also validate:\n\n```bash\ncd frontend \u0026\u0026 npm test -- src/services/__tests__/companionService.test.ts\ncd companion \u0026\u0026 npm test -- src/i18n/__tests__/index.test.ts src/components/__tests__/Preferences.test.tsx\n```\n", "0.9": "+++\ntitle = \"Localization and Locale Behavior\"\n+++\n\nLocalization in Sambee is a typed cross-app system. It affects UI copy, browser formatting, and browser-to-companion behavior.\n\nUse this page when you are adding copy, changing locale behavior, or touching browser-to-companion localization sync.\n\n## Sources of Truth\n\nThese files own the localization model:\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Browser app typed wrapper | `frontend/src/i18n/index.ts` |\n| Companion typed wrapper | `companion/src/i18n/index.ts` |\n\nEnglish is the source locale.\n\nThe pseudo-locale `en-XA` is generated from the English translation tree. Do not edit pseudo-locale strings manually.\n\n## Adding New UI Copy\n\nWhen you add new copy:\n\n1. add the English key to the relevant `EN_TRANSLATIONS` tree\n2. use that key from UI code instead of hard-coding a string\n3. use the existing translation access pattern for the surface you are editing\n4. add or extend tests when the copy sits in a reused or high-risk surface\n\nTypical access patterns are:\n\n- browser app React components: `useTranslation()`\n- browser app non-component helpers or config: `translate(...)`\n- companion components: `useI18n()` or `translate(...)`\n\n## Type-Safety Rules\n\nTyped translation keys are part of the contract.\n\n- translation keys are type-checked through the i18n type layer\n- invalid keys should fail TypeScript compilation\n- do not bypass that with casts to `string` or `any`\n- keep wrapper signatures typed instead of weakening them for convenience\n\nIf localization typing becomes optional, contributors lose one of the main protections against copy drift and key mismatches.\n\n## Compile-Time Guard Fixtures\n\nThese files exist specifically to catch regressions in localization typing:\n\n- `frontend/src/i18n/__tests__/typecheck.ts`\n- `companion/src/i18n/__tests__/typecheck.ts`\n\nThey intentionally include both:\n\n- valid translation calls that must compile\n- invalid keys marked with `@ts-expect-error` that must stay invalid\n\nIf a change weakens typed keys, these fixtures should fail type checking.\n\n## Language Versus Regional Formatting\n\nSambee separates UI language from regional formatting.\n\n- language decides which translated copy the UI shows\n- regional formatting decides how dates, numbers, and sorting behave\n\nThat split matters because users may want English UI with non-US formatting, or any other mixed combination the product supports.\n\n## Preference Storage Rules\n\nFrontend language and regional formatting preferences are stored separately.\n\n- language preference lives in `localization.language` in current-user settings and is mirrored in local storage under the app locale key\n- regional formatting preference lives in `localization.regional_locale` in current-user settings and is mirrored in local storage under `sambee.regional-locale`\n- `browser` is the default for both preferences\n\n`browser` means:\n\n- UI language resolves from the browser locale list against the supported translation set\n- regional formatting resolves from the browser locale while preserving variants such as `en-GB` versus `en-US`\n\n## Runtime Locale Behavior\n\nBoth apps keep document locale metadata aligned with the active locale.\n\n- `document.documentElement.lang` stays synchronized\n- text direction stays synchronized through `dir`\n\nFrontend date, number, and sorting behavior should use the locale-aware helpers instead of raw browser-default formatting.\n\nPrefer:\n\n- `frontend/src/utils/localeFormatting.ts`\n\nFrontend React trees that depend on localization preferences should be wrapped in:\n\n- `frontend/src/i18n/LocalePreferencesProvider.tsx`\n\nThe user-facing preferences UI lives in:\n\n- `frontend/src/pages/PreferencesSettings.tsx`\n\n## Browser-to-Companion Localization Sync\n\nWhen the browser is paired with Sambee Companion, the browser pushes its effective localization state to the companion over the authenticated localhost API.\n\nImportant rules:\n\n- sync uses concrete effective locale values, not unresolved `browser` preferences\n- the companion therefore receives resolved values such as `en` or `en-GB`\n- companion localization is persisted on the Rust side and mirrored into companion local storage for fast startup\n- synchronization is global within the desktop app\n- last-writer-wins behavior is based on the browser-provided `updated_at` timestamp\n- persisted companion state also records the source browser origin\n- open companion windows listen for localization update events and apply the new locale immediately\n\nIf you change the browser-side locale model, you must check the companion sync path too.\n\n## Scope Rules\n\n- translate app-owned UI strings\n- do not translate raw backend error payloads or third-party library messages unless Sambee wraps them in its own copy\n- decorative glyphs are fine when they are not the only user-facing label\n\n## Common Failure Modes\n\n- adding UI text without a translation key\n- weakening typed-key enforcement with casts\n- changing browser locale behavior without checking companion sync\n- treating language preference and formatting preference as the same value\n- using browser-default formatting instead of the shared locale-aware helpers\n\n## Validation Expectations\n\nFor routine localization changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nFor higher-confidence UI changes, also run the relevant frontend or companion tests.\n\nFor browser-to-companion localization sync changes, also validate:\n\n```bash\ncd frontend \u0026\u0026 npm test -- src/services/__tests__/companionService.test.ts\ncd companion \u0026\u0026 npm test -- src/i18n/__tests__/index.test.ts src/components/__tests__/Preferences.test.tsx\n```\n", "1.0": "+++\ntitle = \"Localization and Locale Behavior\"\n+++\n\nLocalization in Sambee is a typed cross-app system. It affects UI copy, browser formatting, and browser-to-companion behavior.\n\nUse this page when you are adding copy, changing locale behavior, or touching browser-to-companion localization sync.\n\n## Sources of Truth\n\nThese files own the localization model:\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Browser app typed wrapper | `frontend/src/i18n/index.ts` |\n| Companion typed wrapper | `companion/src/i18n/index.ts` |\n\nEnglish is the source locale.\n\nThe pseudo-locale `en-XA` is generated from the English translation tree. Do not edit pseudo-locale strings manually.\n\n## Adding New UI Copy\n\nWhen you add new copy:\n\n1. add the English key to the relevant `EN_TRANSLATIONS` tree\n2. use that key from UI code instead of hard-coding a string\n3. use the existing translation access pattern for the surface you are editing\n4. add or extend tests when the copy sits in a reused or high-risk surface\n\nTypical access patterns are:\n\n- browser app React components: `useTranslation()`\n- browser app non-component helpers or config: `translate(...)`\n- companion components: `useI18n()` or `translate(...)`\n\n## Type-Safety Rules\n\nTyped translation keys are part of the contract.\n\n- translation keys are type-checked through the i18n type layer\n- invalid keys should fail TypeScript compilation\n- do not bypass that with casts to `string` or `any`\n- keep wrapper signatures typed instead of weakening them for convenience\n\nIf localization typing becomes optional, contributors lose one of the main protections against copy drift and key mismatches.\n\n## Compile-Time Guard Fixtures\n\nThese files exist specifically to catch regressions in localization typing:\n\n- `frontend/src/i18n/__tests__/typecheck.ts`\n- `companion/src/i18n/__tests__/typecheck.ts`\n\nThey intentionally include both:\n\n- valid translation calls that must compile\n- invalid keys marked with `@ts-expect-error` that must stay invalid\n\nIf a change weakens typed keys, these fixtures should fail type checking.\n\n## Language Versus Regional Formatting\n\nSambee separates UI language from regional formatting.\n\n- language decides which translated copy the UI shows\n- regional formatting decides how dates, numbers, and sorting behave\n\nThat split matters because users may want English UI with non-US formatting, or any other mixed combination the product supports.\n\n## Preference Storage Rules\n\nFrontend language and regional formatting preferences are stored separately.\n\n- language preference lives in `localization.language` in current-user settings and is mirrored in local storage under the app locale key\n- regional formatting preference lives in `localization.regional_locale` in current-user settings and is mirrored in local storage under `sambee.regional-locale`\n- `browser` is the default for both preferences\n\n`browser` means:\n\n- UI language resolves from the browser locale list against the supported translation set\n- regional formatting resolves from the browser locale while preserving variants such as `en-GB` versus `en-US`\n\n## Runtime Locale Behavior\n\nBoth apps keep document locale metadata aligned with the active locale.\n\n- `document.documentElement.lang` stays synchronized\n- text direction stays synchronized through `dir`\n\nFrontend date, number, and sorting behavior should use the locale-aware helpers instead of raw browser-default formatting.\n\nPrefer:\n\n- `frontend/src/utils/localeFormatting.ts`\n\nFrontend React trees that depend on localization preferences should be wrapped in:\n\n- `frontend/src/i18n/LocalePreferencesProvider.tsx`\n\nThe user-facing preferences UI lives in:\n\n- `frontend/src/pages/PreferencesSettings.tsx`\n\n## Browser-to-Companion Localization Sync\n\nWhen the browser is paired with Sambee Companion, the browser pushes its effective localization state to the companion over the authenticated localhost API.\n\nImportant rules:\n\n- sync uses concrete effective locale values, not unresolved `browser` preferences\n- the companion therefore receives resolved values such as `en` or `en-GB`\n- companion localization is persisted on the Rust side and mirrored into companion local storage for fast startup\n- synchronization is global within the desktop app\n- last-writer-wins behavior is based on the browser-provided `updated_at` timestamp\n- persisted companion state also records the source browser origin\n- open companion windows listen for localization update events and apply the new locale immediately\n\nIf you change the browser-side locale model, you must check the companion sync path too.\n\n## Scope Rules\n\n- translate app-owned UI strings\n- do not translate raw backend error payloads or third-party library messages unless Sambee wraps them in its own copy\n- decorative glyphs are fine when they are not the only user-facing label\n\n## Common Failure Modes\n\n- adding UI text without a translation key\n- weakening typed-key enforcement with casts\n- changing browser locale behavior without checking companion sync\n- treating language preference and formatting preference as the same value\n- using browser-default formatting instead of the shared locale-aware helpers\n\n## Validation Expectations\n\nFor routine localization changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nFor higher-confidence UI changes, also run the relevant frontend or companion tests.\n\nFor browser-to-companion localization sync changes, also validate:\n\n```bash\ncd frontend \u0026\u0026 npm test -- src/services/__tests__/companionService.test.ts\ncd companion \u0026\u0026 npm test -- src/i18n/__tests__/index.test.ts src/components/__tests__/Preferences.test.tsx\n```\n", "2.0": "+++\ntitle = \"Localization and Locale Behavior\"\n+++\n\nLocalization in Sambee is a typed cross-app system. It affects UI copy, browser formatting, and browser-to-companion behavior.\n\nUse this page when you are adding copy, changing locale behavior, or touching browser-to-companion localization sync.\n\n## Sources of Truth\n\nThese files own the localization model:\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Browser app typed wrapper | `frontend/src/i18n/index.ts` |\n| Companion typed wrapper | `companion/src/i18n/index.ts` |\n\nEnglish is the source locale.\n\nThe pseudo-locale `en-XA` is generated from the English translation tree. Do not edit pseudo-locale strings manually.\n\n## Adding New UI Copy\n\nWhen you add new copy:\n\n1. add the English key to the relevant `EN_TRANSLATIONS` tree\n2. use that key from UI code instead of hard-coding a string\n3. use the existing translation access pattern for the surface you are editing\n4. add or extend tests when the copy sits in a reused or high-risk surface\n\nTypical access patterns are:\n\n- browser app React components: `useTranslation()`\n- browser app non-component helpers or config: `translate(...)`\n- companion components: `useI18n()` or `translate(...)`\n\n## Type-Safety Rules\n\nTyped translation keys are part of the contract.\n\n- translation keys are type-checked through the i18n type layer\n- invalid keys should fail TypeScript compilation\n- do not bypass that with casts to `string` or `any`\n- keep wrapper signatures typed instead of weakening them for convenience\n\nIf localization typing becomes optional, contributors lose one of the main protections against copy drift and key mismatches.\n\n## Compile-Time Guard Fixtures\n\nThese files exist specifically to catch regressions in localization typing:\n\n- `frontend/src/i18n/__tests__/typecheck.ts`\n- `companion/src/i18n/__tests__/typecheck.ts`\n\nThey intentionally include both:\n\n- valid translation calls that must compile\n- invalid keys marked with `@ts-expect-error` that must stay invalid\n\nIf a change weakens typed keys, these fixtures should fail type checking.\n\n## Language Versus Regional Formatting\n\nSambee separates UI language from regional formatting.\n\n- language decides which translated copy the UI shows\n- regional formatting decides how dates, numbers, and sorting behave\n\nThat split matters because users may want English UI with non-US formatting, or any other mixed combination the product supports.\n\n## Preference Storage Rules\n\nFrontend language and regional formatting preferences are stored separately.\n\n- language preference lives in `localization.language` in current-user settings and is mirrored in local storage under the app locale key\n- regional formatting preference lives in `localization.regional_locale` in current-user settings and is mirrored in local storage under `sambee.regional-locale`\n- `browser` is the default for both preferences\n\n`browser` means:\n\n- UI language resolves from the browser locale list against the supported translation set\n- regional formatting resolves from the browser locale while preserving variants such as `en-GB` versus `en-US`\n\n## Runtime Locale Behavior\n\nBoth apps keep document locale metadata aligned with the active locale.\n\n- `document.documentElement.lang` stays synchronized\n- text direction stays synchronized through `dir`\n\nFrontend date, number, and sorting behavior should use the locale-aware helpers instead of raw browser-default formatting.\n\nPrefer:\n\n- `frontend/src/utils/localeFormatting.ts`\n\nFrontend React trees that depend on localization preferences should be wrapped in:\n\n- `frontend/src/i18n/LocalePreferencesProvider.tsx`\n\nThe user-facing preferences UI lives in:\n\n- `frontend/src/pages/PreferencesSettings.tsx`\n\n## Browser-to-Companion Localization Sync\n\nWhen the browser is paired with Sambee Companion, the browser pushes its effective localization state to the companion over the authenticated localhost API.\n\nImportant rules:\n\n- sync uses concrete effective locale values, not unresolved `browser` preferences\n- the companion therefore receives resolved values such as `en` or `en-GB`\n- companion localization is persisted on the Rust side and mirrored into companion local storage for fast startup\n- synchronization is global within the desktop app\n- last-writer-wins behavior is based on the browser-provided `updated_at` timestamp\n- persisted companion state also records the source browser origin\n- open companion windows listen for localization update events and apply the new locale immediately\n\nIf you change the browser-side locale model, you must check the companion sync path too.\n\n## Scope Rules\n\n- translate app-owned UI strings\n- do not translate raw backend error payloads or third-party library messages unless Sambee wraps them in its own copy\n- decorative glyphs are fine when they are not the only user-facing label\n\n## Common Failure Modes\n\n- adding UI text without a translation key\n- weakening typed-key enforcement with casts\n- changing browser locale behavior without checking companion sync\n- treating language preference and formatting preference as the same value\n- using browser-default formatting instead of the shared locale-aware helpers\n\n## Validation Expectations\n\nFor routine localization changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nFor higher-confidence UI changes, also run the relevant frontend or companion tests.\n\nFor browser-to-companion localization sync changes, also validate:\n\n```bash\ncd frontend \u0026\u0026 npm test -- src/services/__tests__/companionService.test.ts\ncd companion \u0026\u0026 npm test -- src/i18n/__tests__/index.test.ts src/components/__tests__/Preferences.test.tsx\n```\n"}, "page_contents": {"0.7": "+++\ntitle = \"Localization and Locale Behavior\"\n+++\n\nLocalization in Sambee is a typed cross-app system. It affects UI copy, browser formatting, and browser-to-companion behavior.\n\nUse this page when you are adding copy, changing locale behavior, or touching browser-to-companion localization sync.\n\n## Sources of Truth\n\nThese files own the localization model:\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Browser app typed wrapper | `frontend/src/i18n/index.ts` |\n| Companion typed wrapper | `companion/src/i18n/index.ts` |\n\nEnglish is the source locale.\n\nThe pseudo-locale `en-XA` is generated from the English translation tree. Do not edit pseudo-locale strings manually.\n\n## Adding New UI Copy\n\nWhen you add new copy:\n\n1. add the English key to the relevant `EN_TRANSLATIONS` tree\n2. use that key from UI code instead of hard-coding a string\n3. use the existing translation access pattern for the surface you are editing\n4. add or extend tests when the copy sits in a reused or high-risk surface\n\nTypical access patterns are:\n\n- browser app React components: `useTranslation()`\n- browser app non-component helpers or config: `translate(...)`\n- companion components: `useI18n()` or `translate(...)`\n\n## Type-Safety Rules\n\nTyped translation keys are part of the contract.\n\n- translation keys are type-checked through the i18n type layer\n- invalid keys should fail TypeScript compilation\n- do not bypass that with casts to `string` or `any`\n- keep wrapper signatures typed instead of weakening them for convenience\n\nIf localization typing becomes optional, contributors lose one of the main protections against copy drift and key mismatches.\n\n## Compile-Time Guard Fixtures\n\nThese files exist specifically to catch regressions in localization typing:\n\n- `frontend/src/i18n/__tests__/typecheck.ts`\n- `companion/src/i18n/__tests__/typecheck.ts`\n\nThey intentionally include both:\n\n- valid translation calls that must compile\n- invalid keys marked with `@ts-expect-error` that must stay invalid\n\nIf a change weakens typed keys, these fixtures should fail type checking.\n\n## Language Versus Regional Formatting\n\nSambee separates UI language from regional formatting.\n\n- language decides which translated copy the UI shows\n- regional formatting decides how dates, numbers, and sorting behave\n\nThat split matters because users may want English UI with non-US formatting, or any other mixed combination the product supports.\n\n## Preference Storage Rules\n\nFrontend language and regional formatting preferences are stored separately.\n\n- language preference lives in `localization.language` in current-user settings and is mirrored in local storage under the app locale key\n- regional formatting preference lives in `localization.regional_locale` in current-user settings and is mirrored in local storage under `sambee.regional-locale`\n- `browser` is the default for both preferences\n\n`browser` means:\n\n- UI language resolves from the browser locale list against the supported translation set\n- regional formatting resolves from the browser locale while preserving variants such as `en-GB` versus `en-US`\n\n## Runtime Locale Behavior\n\nBoth apps keep document locale metadata aligned with the active locale.\n\n- `document.documentElement.lang` stays synchronized\n- text direction stays synchronized through `dir`\n\nFrontend date, number, and sorting behavior should use the locale-aware helpers instead of raw browser-default formatting.\n\nPrefer:\n\n- `frontend/src/utils/localeFormatting.ts`\n\nFrontend React trees that depend on localization preferences should be wrapped in:\n\n- `frontend/src/i18n/LocalePreferencesProvider.tsx`\n\nThe user-facing preferences UI lives in:\n\n- `frontend/src/pages/PreferencesSettings.tsx`\n\n## Browser-to-Companion Localization Sync\n\nWhen the browser is paired with Sambee Companion, the browser pushes its effective localization state to the companion over the authenticated localhost API.\n\nImportant rules:\n\n- sync uses concrete effective locale values, not unresolved `browser` preferences\n- the companion therefore receives resolved values such as `en` or `en-GB`\n- companion localization is persisted on the Rust side and mirrored into companion local storage for fast startup\n- synchronization is global within the desktop app\n- last-writer-wins behavior is based on the browser-provided `updated_at` timestamp\n- persisted companion state also records the source browser origin\n- open companion windows listen for localization update events and apply the new locale immediately\n\nIf you change the browser-side locale model, you must check the companion sync path too.\n\n## Scope Rules\n\n- translate app-owned UI strings\n- do not translate raw backend error payloads or third-party library messages unless Sambee wraps them in its own copy\n- decorative glyphs are fine when they are not the only user-facing label\n\n## Common Failure Modes\n\n- adding UI text without a translation key\n- weakening typed-key enforcement with casts\n- changing browser locale behavior without checking companion sync\n- treating language preference and formatting preference as the same value\n- using browser-default formatting instead of the shared locale-aware helpers\n\n## Validation Expectations\n\nFor routine localization changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nFor higher-confidence UI changes, also run the relevant frontend or companion tests.\n\nFor browser-to-companion localization sync changes, also validate:\n\n```bash\ncd frontend \u0026\u0026 npm test -- src/services/__tests__/companionService.test.ts\ncd companion \u0026\u0026 npm test -- src/i18n/__tests__/index.test.ts src/components/__tests__/Preferences.test.tsx\n```\n", "0.8": "+++\ntitle = \"Localization and Locale Behavior\"\n+++\n\nLocalization in Sambee is a typed cross-app system. It affects UI copy, browser formatting, and browser-to-companion behavior.\n\nUse this page when you are adding copy, changing locale behavior, or touching browser-to-companion localization sync.\n\n## Sources of Truth\n\nThese files own the localization model:\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Browser app typed wrapper | `frontend/src/i18n/index.ts` |\n| Companion typed wrapper | `companion/src/i18n/index.ts` |\n\nEnglish is the source locale.\n\nThe pseudo-locale `en-XA` is generated from the English translation tree. Do not edit pseudo-locale strings manually.\n\n## Adding New UI Copy\n\nWhen you add new copy:\n\n1. add the English key to the relevant `EN_TRANSLATIONS` tree\n2. use that key from UI code instead of hard-coding a string\n3. use the existing translation access pattern for the surface you are editing\n4. add or extend tests when the copy sits in a reused or high-risk surface\n\nTypical access patterns are:\n\n- browser app React components: `useTranslation()`\n- browser app non-component helpers or config: `translate(...)`\n- companion components: `useI18n()` or `translate(...)`\n\n## Type-Safety Rules\n\nTyped translation keys are part of the contract.\n\n- translation keys are type-checked through the i18n type layer\n- invalid keys should fail TypeScript compilation\n- do not bypass that with casts to `string` or `any`\n- keep wrapper signatures typed instead of weakening them for convenience\n\nIf localization typing becomes optional, contributors lose one of the main protections against copy drift and key mismatches.\n\n## Compile-Time Guard Fixtures\n\nThese files exist specifically to catch regressions in localization typing:\n\n- `frontend/src/i18n/__tests__/typecheck.ts`\n- `companion/src/i18n/__tests__/typecheck.ts`\n\nThey intentionally include both:\n\n- valid translation calls that must compile\n- invalid keys marked with `@ts-expect-error` that must stay invalid\n\nIf a change weakens typed keys, these fixtures should fail type checking.\n\n## Language Versus Regional Formatting\n\nSambee separates UI language from regional formatting.\n\n- language decides which translated copy the UI shows\n- regional formatting decides how dates, numbers, and sorting behave\n\nThat split matters because users may want English UI with non-US formatting, or any other mixed combination the product supports.\n\n## Preference Storage Rules\n\nFrontend language and regional formatting preferences are stored separately.\n\n- language preference lives in `localization.language` in current-user settings and is mirrored in local storage under the app locale key\n- regional formatting preference lives in `localization.regional_locale` in current-user settings and is mirrored in local storage under `sambee.regional-locale`\n- `browser` is the default for both preferences\n\n`browser` means:\n\n- UI language resolves from the browser locale list against the supported translation set\n- regional formatting resolves from the browser locale while preserving variants such as `en-GB` versus `en-US`\n\n## Runtime Locale Behavior\n\nBoth apps keep document locale metadata aligned with the active locale.\n\n- `document.documentElement.lang` stays synchronized\n- text direction stays synchronized through `dir`\n\nFrontend date, number, and sorting behavior should use the locale-aware helpers instead of raw browser-default formatting.\n\nPrefer:\n\n- `frontend/src/utils/localeFormatting.ts`\n\nFrontend React trees that depend on localization preferences should be wrapped in:\n\n- `frontend/src/i18n/LocalePreferencesProvider.tsx`\n\nThe user-facing preferences UI lives in:\n\n- `frontend/src/pages/PreferencesSettings.tsx`\n\n## Browser-to-Companion Localization Sync\n\nWhen the browser is paired with Sambee Companion, the browser pushes its effective localization state to the companion over the authenticated localhost API.\n\nImportant rules:\n\n- sync uses concrete effective locale values, not unresolved `browser` preferences\n- the companion therefore receives resolved values such as `en` or `en-GB`\n- companion localization is persisted on the Rust side and mirrored into companion local storage for fast startup\n- synchronization is global within the desktop app\n- last-writer-wins behavior is based on the browser-provided `updated_at` timestamp\n- persisted companion state also records the source browser origin\n- open companion windows listen for localization update events and apply the new locale immediately\n\nIf you change the browser-side locale model, you must check the companion sync path too.\n\n## Scope Rules\n\n- translate app-owned UI strings\n- do not translate raw backend error payloads or third-party library messages unless Sambee wraps them in its own copy\n- decorative glyphs are fine when they are not the only user-facing label\n\n## Common Failure Modes\n\n- adding UI text without a translation key\n- weakening typed-key enforcement with casts\n- changing browser locale behavior without checking companion sync\n- treating language preference and formatting preference as the same value\n- using browser-default formatting instead of the shared locale-aware helpers\n\n## Validation Expectations\n\nFor routine localization changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nFor higher-confidence UI changes, also run the relevant frontend or companion tests.\n\nFor browser-to-companion localization sync changes, also validate:\n\n```bash\ncd frontend \u0026\u0026 npm test -- src/services/__tests__/companionService.test.ts\ncd companion \u0026\u0026 npm test -- src/i18n/__tests__/index.test.ts src/components/__tests__/Preferences.test.tsx\n```\n", "0.9": "+++\ntitle = \"Localization and Locale Behavior\"\n+++\n\nLocalization in Sambee is a typed cross-app system. It affects UI copy, browser formatting, and browser-to-companion behavior.\n\nUse this page when you are adding copy, changing locale behavior, or touching browser-to-companion localization sync.\n\n## Sources of Truth\n\nThese files own the localization model:\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Browser app typed wrapper | `frontend/src/i18n/index.ts` |\n| Companion typed wrapper | `companion/src/i18n/index.ts` |\n\nEnglish is the source locale.\n\nThe pseudo-locale `en-XA` is generated from the English translation tree. Do not edit pseudo-locale strings manually.\n\n## Adding New UI Copy\n\nWhen you add new copy:\n\n1. add the English key to the relevant `EN_TRANSLATIONS` tree\n2. use that key from UI code instead of hard-coding a string\n3. use the existing translation access pattern for the surface you are editing\n4. add or extend tests when the copy sits in a reused or high-risk surface\n\nTypical access patterns are:\n\n- browser app React components: `useTranslation()`\n- browser app non-component helpers or config: `translate(...)`\n- companion components: `useI18n()` or `translate(...)`\n\n## Type-Safety Rules\n\nTyped translation keys are part of the contract.\n\n- translation keys are type-checked through the i18n type layer\n- invalid keys should fail TypeScript compilation\n- do not bypass that with casts to `string` or `any`\n- keep wrapper signatures typed instead of weakening them for convenience\n\nIf localization typing becomes optional, contributors lose one of the main protections against copy drift and key mismatches.\n\n## Compile-Time Guard Fixtures\n\nThese files exist specifically to catch regressions in localization typing:\n\n- `frontend/src/i18n/__tests__/typecheck.ts`\n- `companion/src/i18n/__tests__/typecheck.ts`\n\nThey intentionally include both:\n\n- valid translation calls that must compile\n- invalid keys marked with `@ts-expect-error` that must stay invalid\n\nIf a change weakens typed keys, these fixtures should fail type checking.\n\n## Language Versus Regional Formatting\n\nSambee separates UI language from regional formatting.\n\n- language decides which translated copy the UI shows\n- regional formatting decides how dates, numbers, and sorting behave\n\nThat split matters because users may want English UI with non-US formatting, or any other mixed combination the product supports.\n\n## Preference Storage Rules\n\nFrontend language and regional formatting preferences are stored separately.\n\n- language preference lives in `localization.language` in current-user settings and is mirrored in local storage under the app locale key\n- regional formatting preference lives in `localization.regional_locale` in current-user settings and is mirrored in local storage under `sambee.regional-locale`\n- `browser` is the default for both preferences\n\n`browser` means:\n\n- UI language resolves from the browser locale list against the supported translation set\n- regional formatting resolves from the browser locale while preserving variants such as `en-GB` versus `en-US`\n\n## Runtime Locale Behavior\n\nBoth apps keep document locale metadata aligned with the active locale.\n\n- `document.documentElement.lang` stays synchronized\n- text direction stays synchronized through `dir`\n\nFrontend date, number, and sorting behavior should use the locale-aware helpers instead of raw browser-default formatting.\n\nPrefer:\n\n- `frontend/src/utils/localeFormatting.ts`\n\nFrontend React trees that depend on localization preferences should be wrapped in:\n\n- `frontend/src/i18n/LocalePreferencesProvider.tsx`\n\nThe user-facing preferences UI lives in:\n\n- `frontend/src/pages/PreferencesSettings.tsx`\n\n## Browser-to-Companion Localization Sync\n\nWhen the browser is paired with Sambee Companion, the browser pushes its effective localization state to the companion over the authenticated localhost API.\n\nImportant rules:\n\n- sync uses concrete effective locale values, not unresolved `browser` preferences\n- the companion therefore receives resolved values such as `en` or `en-GB`\n- companion localization is persisted on the Rust side and mirrored into companion local storage for fast startup\n- synchronization is global within the desktop app\n- last-writer-wins behavior is based on the browser-provided `updated_at` timestamp\n- persisted companion state also records the source browser origin\n- open companion windows listen for localization update events and apply the new locale immediately\n\nIf you change the browser-side locale model, you must check the companion sync path too.\n\n## Scope Rules\n\n- translate app-owned UI strings\n- do not translate raw backend error payloads or third-party library messages unless Sambee wraps them in its own copy\n- decorative glyphs are fine when they are not the only user-facing label\n\n## Common Failure Modes\n\n- adding UI text without a translation key\n- weakening typed-key enforcement with casts\n- changing browser locale behavior without checking companion sync\n- treating language preference and formatting preference as the same value\n- using browser-default formatting instead of the shared locale-aware helpers\n\n## Validation Expectations\n\nFor routine localization changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nFor higher-confidence UI changes, also run the relevant frontend or companion tests.\n\nFor browser-to-companion localization sync changes, also validate:\n\n```bash\ncd frontend \u0026\u0026 npm test -- src/services/__tests__/companionService.test.ts\ncd companion \u0026\u0026 npm test -- src/i18n/__tests__/index.test.ts src/components/__tests__/Preferences.test.tsx\n```\n", "1.0": "+++\ntitle = \"Localization and Locale Behavior\"\n+++\n\nLocalization in Sambee is a typed cross-app system. It affects UI copy, browser formatting, and browser-to-companion behavior.\n\nUse this page when you are adding copy, changing locale behavior, or touching browser-to-companion localization sync.\n\n## Sources of Truth\n\nThese files own the localization model:\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Browser app typed wrapper | `frontend/src/i18n/index.ts` |\n| Companion typed wrapper | `companion/src/i18n/index.ts` |\n\nEnglish is the source locale.\n\nThe pseudo-locale `en-XA` is generated from the English translation tree. Do not edit pseudo-locale strings manually.\n\n## Adding New UI Copy\n\nWhen you add new copy:\n\n1. add the English key to the relevant `EN_TRANSLATIONS` tree\n2. use that key from UI code instead of hard-coding a string\n3. use the existing translation access pattern for the surface you are editing\n4. add or extend tests when the copy sits in a reused or high-risk surface\n\nTypical access patterns are:\n\n- browser app React components: `useTranslation()`\n- browser app non-component helpers or config: `translate(...)`\n- companion components: `useI18n()` or `translate(...)`\n\n## Type-Safety Rules\n\nTyped translation keys are part of the contract.\n\n- translation keys are type-checked through the i18n type layer\n- invalid keys should fail TypeScript compilation\n- do not bypass that with casts to `string` or `any`\n- keep wrapper signatures typed instead of weakening them for convenience\n\nIf localization typing becomes optional, contributors lose one of the main protections against copy drift and key mismatches.\n\n## Compile-Time Guard Fixtures\n\nThese files exist specifically to catch regressions in localization typing:\n\n- `frontend/src/i18n/__tests__/typecheck.ts`\n- `companion/src/i18n/__tests__/typecheck.ts`\n\nThey intentionally include both:\n\n- valid translation calls that must compile\n- invalid keys marked with `@ts-expect-error` that must stay invalid\n\nIf a change weakens typed keys, these fixtures should fail type checking.\n\n## Language Versus Regional Formatting\n\nSambee separates UI language from regional formatting.\n\n- language decides which translated copy the UI shows\n- regional formatting decides how dates, numbers, and sorting behave\n\nThat split matters because users may want English UI with non-US formatting, or any other mixed combination the product supports.\n\n## Preference Storage Rules\n\nFrontend language and regional formatting preferences are stored separately.\n\n- language preference lives in `localization.language` in current-user settings and is mirrored in local storage under the app locale key\n- regional formatting preference lives in `localization.regional_locale` in current-user settings and is mirrored in local storage under `sambee.regional-locale`\n- `browser` is the default for both preferences\n\n`browser` means:\n\n- UI language resolves from the browser locale list against the supported translation set\n- regional formatting resolves from the browser locale while preserving variants such as `en-GB` versus `en-US`\n\n## Runtime Locale Behavior\n\nBoth apps keep document locale metadata aligned with the active locale.\n\n- `document.documentElement.lang` stays synchronized\n- text direction stays synchronized through `dir`\n\nFrontend date, number, and sorting behavior should use the locale-aware helpers instead of raw browser-default formatting.\n\nPrefer:\n\n- `frontend/src/utils/localeFormatting.ts`\n\nFrontend React trees that depend on localization preferences should be wrapped in:\n\n- `frontend/src/i18n/LocalePreferencesProvider.tsx`\n\nThe user-facing preferences UI lives in:\n\n- `frontend/src/pages/PreferencesSettings.tsx`\n\n## Browser-to-Companion Localization Sync\n\nWhen the browser is paired with Sambee Companion, the browser pushes its effective localization state to the companion over the authenticated localhost API.\n\nImportant rules:\n\n- sync uses concrete effective locale values, not unresolved `browser` preferences\n- the companion therefore receives resolved values such as `en` or `en-GB`\n- companion localization is persisted on the Rust side and mirrored into companion local storage for fast startup\n- synchronization is global within the desktop app\n- last-writer-wins behavior is based on the browser-provided `updated_at` timestamp\n- persisted companion state also records the source browser origin\n- open companion windows listen for localization update events and apply the new locale immediately\n\nIf you change the browser-side locale model, you must check the companion sync path too.\n\n## Scope Rules\n\n- translate app-owned UI strings\n- do not translate raw backend error payloads or third-party library messages unless Sambee wraps them in its own copy\n- decorative glyphs are fine when they are not the only user-facing label\n\n## Common Failure Modes\n\n- adding UI text without a translation key\n- weakening typed-key enforcement with casts\n- changing browser locale behavior without checking companion sync\n- treating language preference and formatting preference as the same value\n- using browser-default formatting instead of the shared locale-aware helpers\n\n## Validation Expectations\n\nFor routine localization changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nFor higher-confidence UI changes, also run the relevant frontend or companion tests.\n\nFor browser-to-companion localization sync changes, also validate:\n\n```bash\ncd frontend \u0026\u0026 npm test -- src/services/__tests__/companionService.test.ts\ncd companion \u0026\u0026 npm test -- src/i18n/__tests__/index.test.ts src/components/__tests__/Preferences.test.tsx\n```\n", "2.0": "+++\ntitle = \"Localization and Locale Behavior\"\n+++\n\nLocalization in Sambee is a typed cross-app system. It affects UI copy, browser formatting, and browser-to-companion behavior.\n\nUse this page when you are adding copy, changing locale behavior, or touching browser-to-companion localization sync.\n\n## Sources of Truth\n\nThese files own the localization model:\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Browser app typed wrapper | `frontend/src/i18n/index.ts` |\n| Companion typed wrapper | `companion/src/i18n/index.ts` |\n\nEnglish is the source locale.\n\nThe pseudo-locale `en-XA` is generated from the English translation tree. Do not edit pseudo-locale strings manually.\n\n## Adding New UI Copy\n\nWhen you add new copy:\n\n1. add the English key to the relevant `EN_TRANSLATIONS` tree\n2. use that key from UI code instead of hard-coding a string\n3. use the existing translation access pattern for the surface you are editing\n4. add or extend tests when the copy sits in a reused or high-risk surface\n\nTypical access patterns are:\n\n- browser app React components: `useTranslation()`\n- browser app non-component helpers or config: `translate(...)`\n- companion components: `useI18n()` or `translate(...)`\n\n## Type-Safety Rules\n\nTyped translation keys are part of the contract.\n\n- translation keys are type-checked through the i18n type layer\n- invalid keys should fail TypeScript compilation\n- do not bypass that with casts to `string` or `any`\n- keep wrapper signatures typed instead of weakening them for convenience\n\nIf localization typing becomes optional, contributors lose one of the main protections against copy drift and key mismatches.\n\n## Compile-Time Guard Fixtures\n\nThese files exist specifically to catch regressions in localization typing:\n\n- `frontend/src/i18n/__tests__/typecheck.ts`\n- `companion/src/i18n/__tests__/typecheck.ts`\n\nThey intentionally include both:\n\n- valid translation calls that must compile\n- invalid keys marked with `@ts-expect-error` that must stay invalid\n\nIf a change weakens typed keys, these fixtures should fail type checking.\n\n## Language Versus Regional Formatting\n\nSambee separates UI language from regional formatting.\n\n- language decides which translated copy the UI shows\n- regional formatting decides how dates, numbers, and sorting behave\n\nThat split matters because users may want English UI with non-US formatting, or any other mixed combination the product supports.\n\n## Preference Storage Rules\n\nFrontend language and regional formatting preferences are stored separately.\n\n- language preference lives in `localization.language` in current-user settings and is mirrored in local storage under the app locale key\n- regional formatting preference lives in `localization.regional_locale` in current-user settings and is mirrored in local storage under `sambee.regional-locale`\n- `browser` is the default for both preferences\n\n`browser` means:\n\n- UI language resolves from the browser locale list against the supported translation set\n- regional formatting resolves from the browser locale while preserving variants such as `en-GB` versus `en-US`\n\n## Runtime Locale Behavior\n\nBoth apps keep document locale metadata aligned with the active locale.\n\n- `document.documentElement.lang` stays synchronized\n- text direction stays synchronized through `dir`\n\nFrontend date, number, and sorting behavior should use the locale-aware helpers instead of raw browser-default formatting.\n\nPrefer:\n\n- `frontend/src/utils/localeFormatting.ts`\n\nFrontend React trees that depend on localization preferences should be wrapped in:\n\n- `frontend/src/i18n/LocalePreferencesProvider.tsx`\n\nThe user-facing preferences UI lives in:\n\n- `frontend/src/pages/PreferencesSettings.tsx`\n\n## Browser-to-Companion Localization Sync\n\nWhen the browser is paired with Sambee Companion, the browser pushes its effective localization state to the companion over the authenticated localhost API.\n\nImportant rules:\n\n- sync uses concrete effective locale values, not unresolved `browser` preferences\n- the companion therefore receives resolved values such as `en` or `en-GB`\n- companion localization is persisted on the Rust side and mirrored into companion local storage for fast startup\n- synchronization is global within the desktop app\n- last-writer-wins behavior is based on the browser-provided `updated_at` timestamp\n- persisted companion state also records the source browser origin\n- open companion windows listen for localization update events and apply the new locale immediately\n\nIf you change the browser-side locale model, you must check the companion sync path too.\n\n## Scope Rules\n\n- translate app-owned UI strings\n- do not translate raw backend error payloads or third-party library messages unless Sambee wraps them in its own copy\n- decorative glyphs are fine when they are not the only user-facing label\n\n## Common Failure Modes\n\n- adding UI text without a translation key\n- weakening typed-key enforcement with casts\n- changing browser locale behavior without checking companion sync\n- treating language preference and formatting preference as the same value\n- using browser-default formatting instead of the shared locale-aware helpers\n\n## Validation Expectations\n\nFor routine localization changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nFor higher-confidence UI changes, also run the relevant frontend or companion tests.\n\nFor browser-to-companion localization sync changes, also validate:\n\n```bash\ncd frontend \u0026\u0026 npm test -- src/services/__tests__/companionService.test.ts\ncd companion \u0026\u0026 npm test -- src/i18n/__tests__/index.test.ts src/components/__tests__/Preferences.test.tsx\n```\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/cross-cutting-systems/frontend-logging-and-tracing", "parent_id": "section:developer-guide/cross-cutting-systems", "depth": 2, "kind": "page", "label": "frontend-logging-and-tracing", "title": "Frontend Logging And Tracing", "path": "developer-guide/cross-cutting-systems/frontend-logging-and-tracing", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Frontend Logging and Tracing\"\n+++\n\nThe browser app has one shared logging API, but it can feed two different diagnostic surfaces.\n\n- browser-console output for local development and interactive debugging\n- backend trace collection for support workflows and cases where direct console access is unavailable\n\nThat split matters because a small frontend logging change can improve one surface while degrading the other.\n\n## Main Implementation Files\n\n| File | Role |\n|---|---|\n| `frontend/src/services/logger.ts` | shared logging entry point and backend-tracing orchestration |\n| `frontend/src/services/loggingConfig.ts` | fetches and caches server logging config |\n| `frontend/src/services/logBuffer.ts` | buffers trace events before flush |\n| `frontend/src/services/logTransport.ts` | sends trace batches to `/api/logs/mobile` |\n| `backend/app/api/logs.py` | serves frontend logging config and accepts uploaded trace batches |\n| `backend/app/services/log_manager.py` | writes trace batches to JSONL files and cleans up retained logs |\n| `frontend/src/pages/Login.tsx` and `frontend/src/pages/FileBrowser.tsx` | initialize tracing after authenticated app startup |\n\n## Runtime Flow\n\n1. the authenticated browser app calls `logger.initializeBackendTracing()`\n2. the logger loads config through `loggingConfig.getConfig()`\n3. console logging level is updated from backend config when enabled\n4. backend tracing is enabled only when the server config allows it\n5. each logger call writes to the console if its level passes the console threshold\n6. the same call asynchronously checks trace level and component filters before buffering a backend trace entry\n7. the buffer flushes by size or interval and posts the batch to `/api/logs/mobile`\n\nThe log call is the single source of truth. Contributors should not have to choose between console visibility and trace collection by using different APIs.\n\n## Configuration Model\n\nThe frontend pulls logging state from the backend rather than hard-coding it in the browser app.\n\n- `logging_enabled` and `logging_level` control console output\n- `tracing_enabled`, `tracing_level`, and `tracing_components` control backend trace collection\n- `frontend_tracing_username_regex` on the backend can disable tracing for users who do not match the configured pattern\n- `loggingConfig` caches the fetched config in `localStorage` for five minutes to avoid repeated requests\n\nThe logger also keeps different local defaults before server config is loaded.\n\n- development builds default to verbose console logging\n- production builds default to warnings and errors\n- test runs skip backend tracing setup entirely\n\nThe current backend contract is exposed through `GET /api/logs/config` and returns:\n\n- `logging_enabled`\n- `logging_level`\n- `tracing_enabled`\n- `tracing_level`\n- `tracing_components`\n\n`loggingConfig` then adds a client-side timestamp when caching the response locally.\n\n### Level and Component Filtering\n\nConsole logging and backend tracing are independent.\n\n- console output is gated only by `logging_enabled` plus the effective console level\n- backend tracing is gated by `tracing_enabled`, `tracing_level`, and optional component matching\n- an empty `tracing_components` list means all components are accepted\n- component matching is exact string matching, so inconsistent tag names reduce the usefulness of filtered tracing quickly\n\nLevel filtering is threshold-based.\n\n- `DEBUG` allows everything\n- `INFO` suppresses only `DEBUG`\n- `WARNING` allows `WARNING` and `ERROR`\n- `ERROR` allows only `ERROR`\n\n## Buffering and Transport\n\nBackend tracing is buffered on purpose.\n\n- `LogBuffer` groups trace entries in memory instead of posting every log call immediately\n- each batch carries a generated session ID plus device information such as user agent, screen size, and touch capability\n- the default flush behavior is size-based or time-based, whichever happens first\n- failed flushes keep the buffered entries for retry on the next flush attempt\n\nThe current implementation details are worth preserving:\n\n- `LogBuffer` generates one session ID for the browser runtime that enabled tracing\n- the batch payload includes `userAgent`, screen size, `devicePixelRatio`, platform, and touch capability\n- `LogTransport` uses `fetch` directly instead of the shared API service to avoid circular dependencies in the logging stack\n- trace uploads include the bearer token when one is available\n- if repeated flush failures push the in-memory buffer above twice the configured size, the oldest entries are dropped to cap memory growth\n\nThis design keeps routine logging cheap while still giving the backend enough session context to debug real field problems.\n\n### Backend Receipt and Storage\n\nThe backend logging API is simple and file-backed.\n\n- `POST /api/logs/mobile` accepts a trace batch for the authenticated user\n- `GET /api/logs/config` serves the frontend logging configuration\n- `GET /api/logs/list` lists available uploaded mobile-log files\n- `GET /api/logs/download/{filename}` downloads a stored log file\n\nUploaded trace batches are written under `data/mobile_logs/` as JSONL files.\n\n- the first line is metadata, including session ID, device info, server timestamp, and request metadata such as client IP or user agent\n- subsequent lines are individual log entries\n- retention cleanup is handled by `MobileLogManager.cleanup_old_logs()` using the configured retention window\n\nThis is why frontend logging changes can affect both browser behavior and support-facing backend artifacts.\n\n## Component Tags and Taxonomy\n\nComponent tags are optional for console output but important for backend tracing.\n\nRepresentative tags currently used in the frontend include:\n\n- `api`\n- `auth`\n- `backend-recovery`\n- `browser`\n- `browser-perf`\n- `companion`\n- `config`\n- `directory-search-provider`\n- `file-browser`\n- `viewer`\n- `websocket`\n\nThese tags are not just naming style. They are the filter vocabulary for targeted trace collection.\n\nContributors should:\n\n- reuse an existing tag when the log belongs to an established subsystem\n- add a new tag only when it introduces a real new filter boundary\n- keep names stable once they appear in backend config or support playbooks\n\nOne log call still drives both surfaces. The component tag only changes backend-tracing selection behavior.\n\n## Error Context and Safety Rules\n\n`logger.error()` enriches the provided context when an `Error` object is passed.\n\n- `error.message`\n- `error.stack`\n- `error.name`\n\nThat gives support traces more useful failure context without forcing every caller to serialize errors manually.\n\nContributors still need to be selective.\n\n- include actionable IDs, paths, counts, durations, or status values\n- avoid passwords, tokens, private payloads, or large opaque objects\n- avoid high-volume logs inside tight loops or animation-heavy code paths\n\n## Contributor Rules\n\n- use the shared logger instead of scattering long-lived `console.*` calls through components and hooks\n- pass a component tag when backend trace filtering matters to the workflow you are changing\n- do not assume a visible console message also means backend tracing is enabled for that session\n- keep structured context specific and actionable instead of dumping large objects or noisy state snapshots\n- do not move tracing initialization earlier than authenticated startup without checking token and request-path assumptions\n\nThe supported call shape is:\n\n- `logger.debug(message, context?, component?)`\n- `logger.info(message, context?, component?)`\n- `logger.warn(message, context?, component?)`\n- `logger.error(message, context?, component?, error?)`\n\nParameter order matters. If a component tag is needed, it is the third argument for non-error calls and still the third argument for `logger.error()` before the optional `Error` object.\n\nThe older dedicated trace-only helpers are gone. Shared logger calls are the canonical path.\n\n## Test and Runtime Nuances\n\nThe logger deliberately behaves differently in tests.\n\n- test detection suppresses console output\n- backend tracing initialization is skipped in test environments\n- `loggingConfig` falls back to a disabled state when config loading fails\n\nThis is intentional defensive behavior, not a missing feature. It keeps tests quieter and prevents trace setup from leaking across environments.\n\n## Common Failure Modes\n\n- adding raw console logs that never reach backend trace collection\n- expecting a server-side logging-config change to apply instantly while a cached config is still valid\n- using inconsistent component names that make trace filtering unreliable\n- adding high-volume debug logs that drown out the actionable events\n- treating trace transport failures as if they were equivalent to application failures\n\nOther common mistakes include:\n\n- assuming the mobile-log download endpoint is `/api/logs/{filename}` instead of the current `/api/logs/download/{filename}` route\n- documenting stale field names such as `enabled` or `log_level` instead of the current `logging_*` and `tracing_*` contract\n- swapping the logger parameter order and accidentally passing the component tag as context\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nAdd or update targeted frontend tests when the change affects config caching, filtering behavior, startup initialization, or log transport.\n\nThe current targeted suites already cover the most important contracts:\n\n- `frontend/src/services/__tests__/loggingConfig.test.ts` for config shape, threshold logic, and disabled-state behavior\n- `frontend/src/services/__tests__/mobileLoggingApi.test.ts` for the mobile-log API payload and response contract\n\nIf the change touches backend receipt, storage, or filename behavior, pair the frontend checks with the relevant backend tests around `backend/app/api/logs.py` and `backend/tests/test_logging_config.py`.\n", "0.8": "+++\ntitle = \"Frontend Logging and Tracing\"\n+++\n\nThe browser app has one shared logging API, but it can feed two different diagnostic surfaces.\n\n- browser-console output for local development and interactive debugging\n- backend trace collection for support workflows and cases where direct console access is unavailable\n\nThat split matters because a small frontend logging change can improve one surface while degrading the other.\n\n## Main Implementation Files\n\n| File | Role |\n|---|---|\n| `frontend/src/services/logger.ts` | shared logging entry point and backend-tracing orchestration |\n| `frontend/src/services/loggingConfig.ts` | fetches and caches server logging config |\n| `frontend/src/services/logBuffer.ts` | buffers trace events before flush |\n| `frontend/src/services/logTransport.ts` | sends trace batches to `/api/logs/mobile` |\n| `backend/app/api/logs.py` | serves frontend logging config and accepts uploaded trace batches |\n| `backend/app/services/log_manager.py` | writes trace batches to JSONL files and cleans up retained logs |\n| `frontend/src/pages/Login.tsx` and `frontend/src/pages/FileBrowser.tsx` | initialize tracing after authenticated app startup |\n\n## Runtime Flow\n\n1. the authenticated browser app calls `logger.initializeBackendTracing()`\n2. the logger loads config through `loggingConfig.getConfig()`\n3. console logging level is updated from backend config when enabled\n4. backend tracing is enabled only when the server config allows it\n5. each logger call writes to the console if its level passes the console threshold\n6. the same call asynchronously checks trace level and component filters before buffering a backend trace entry\n7. the buffer flushes by size or interval and posts the batch to `/api/logs/mobile`\n\nThe log call is the single source of truth. Contributors should not have to choose between console visibility and trace collection by using different APIs.\n\n## Configuration Model\n\nThe frontend pulls logging state from the backend rather than hard-coding it in the browser app.\n\n- `logging_enabled` and `logging_level` control console output\n- `tracing_enabled`, `tracing_level`, and `tracing_components` control backend trace collection\n- `frontend_tracing_username_regex` on the backend can disable tracing for users who do not match the configured pattern\n- `loggingConfig` caches the fetched config in `localStorage` for five minutes to avoid repeated requests\n\nThe logger also keeps different local defaults before server config is loaded.\n\n- development builds default to verbose console logging\n- production builds default to warnings and errors\n- test runs skip backend tracing setup entirely\n\nThe current backend contract is exposed through `GET /api/logs/config` and returns:\n\n- `logging_enabled`\n- `logging_level`\n- `tracing_enabled`\n- `tracing_level`\n- `tracing_components`\n\n`loggingConfig` then adds a client-side timestamp when caching the response locally.\n\n### Level and Component Filtering\n\nConsole logging and backend tracing are independent.\n\n- console output is gated only by `logging_enabled` plus the effective console level\n- backend tracing is gated by `tracing_enabled`, `tracing_level`, and optional component matching\n- an empty `tracing_components` list means all components are accepted\n- component matching is exact string matching, so inconsistent tag names reduce the usefulness of filtered tracing quickly\n\nLevel filtering is threshold-based.\n\n- `DEBUG` allows everything\n- `INFO` suppresses only `DEBUG`\n- `WARNING` allows `WARNING` and `ERROR`\n- `ERROR` allows only `ERROR`\n\n## Buffering and Transport\n\nBackend tracing is buffered on purpose.\n\n- `LogBuffer` groups trace entries in memory instead of posting every log call immediately\n- each batch carries a generated session ID plus device information such as user agent, screen size, and touch capability\n- the default flush behavior is size-based or time-based, whichever happens first\n- failed flushes keep the buffered entries for retry on the next flush attempt\n\nThe current implementation details are worth preserving:\n\n- `LogBuffer` generates one session ID for the browser runtime that enabled tracing\n- the batch payload includes `userAgent`, screen size, `devicePixelRatio`, platform, and touch capability\n- `LogTransport` uses `fetch` directly instead of the shared API service to avoid circular dependencies in the logging stack\n- trace uploads include the bearer token when one is available\n- if repeated flush failures push the in-memory buffer above twice the configured size, the oldest entries are dropped to cap memory growth\n\nThis design keeps routine logging cheap while still giving the backend enough session context to debug real field problems.\n\n### Backend Receipt and Storage\n\nThe backend logging API is simple and file-backed.\n\n- `POST /api/logs/mobile` accepts a trace batch for the authenticated user\n- `GET /api/logs/config` serves the frontend logging configuration\n- `GET /api/logs/list` lists available uploaded mobile-log files\n- `GET /api/logs/download/{filename}` downloads a stored log file\n\nUploaded trace batches are written under `data/mobile_logs/` as JSONL files.\n\n- the first line is metadata, including session ID, device info, server timestamp, and request metadata such as client IP or user agent\n- subsequent lines are individual log entries\n- retention cleanup is handled by `MobileLogManager.cleanup_old_logs()` using the configured retention window\n\nThis is why frontend logging changes can affect both browser behavior and support-facing backend artifacts.\n\n## Component Tags and Taxonomy\n\nComponent tags are optional for console output but important for backend tracing.\n\nRepresentative tags currently used in the frontend include:\n\n- `api`\n- `auth`\n- `backend-recovery`\n- `browser`\n- `browser-perf`\n- `companion`\n- `config`\n- `directory-search-provider`\n- `file-browser`\n- `viewer`\n- `websocket`\n\nThese tags are not just naming style. They are the filter vocabulary for targeted trace collection.\n\nContributors should:\n\n- reuse an existing tag when the log belongs to an established subsystem\n- add a new tag only when it introduces a real new filter boundary\n- keep names stable once they appear in backend config or support playbooks\n\nOne log call still drives both surfaces. The component tag only changes backend-tracing selection behavior.\n\n## Error Context and Safety Rules\n\n`logger.error()` enriches the provided context when an `Error` object is passed.\n\n- `error.message`\n- `error.stack`\n- `error.name`\n\nThat gives support traces more useful failure context without forcing every caller to serialize errors manually.\n\nContributors still need to be selective.\n\n- include actionable IDs, paths, counts, durations, or status values\n- avoid passwords, tokens, private payloads, or large opaque objects\n- avoid high-volume logs inside tight loops or animation-heavy code paths\n\n## Contributor Rules\n\n- use the shared logger instead of scattering long-lived `console.*` calls through components and hooks\n- pass a component tag when backend trace filtering matters to the workflow you are changing\n- do not assume a visible console message also means backend tracing is enabled for that session\n- keep structured context specific and actionable instead of dumping large objects or noisy state snapshots\n- do not move tracing initialization earlier than authenticated startup without checking token and request-path assumptions\n\nThe supported call shape is:\n\n- `logger.debug(message, context?, component?)`\n- `logger.info(message, context?, component?)`\n- `logger.warn(message, context?, component?)`\n- `logger.error(message, context?, component?, error?)`\n\nParameter order matters. If a component tag is needed, it is the third argument for non-error calls and still the third argument for `logger.error()` before the optional `Error` object.\n\nThe older dedicated trace-only helpers are gone. Shared logger calls are the canonical path.\n\n## Test and Runtime Nuances\n\nThe logger deliberately behaves differently in tests.\n\n- test detection suppresses console output\n- backend tracing initialization is skipped in test environments\n- `loggingConfig` falls back to a disabled state when config loading fails\n\nThis is intentional defensive behavior, not a missing feature. It keeps tests quieter and prevents trace setup from leaking across environments.\n\n## Common Failure Modes\n\n- adding raw console logs that never reach backend trace collection\n- expecting a server-side logging-config change to apply instantly while a cached config is still valid\n- using inconsistent component names that make trace filtering unreliable\n- adding high-volume debug logs that drown out the actionable events\n- treating trace transport failures as if they were equivalent to application failures\n\nOther common mistakes include:\n\n- assuming the mobile-log download endpoint is `/api/logs/{filename}` instead of the current `/api/logs/download/{filename}` route\n- documenting stale field names such as `enabled` or `log_level` instead of the current `logging_*` and `tracing_*` contract\n- swapping the logger parameter order and accidentally passing the component tag as context\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nAdd or update targeted frontend tests when the change affects config caching, filtering behavior, startup initialization, or log transport.\n\nThe current targeted suites already cover the most important contracts:\n\n- `frontend/src/services/__tests__/loggingConfig.test.ts` for config shape, threshold logic, and disabled-state behavior\n- `frontend/src/services/__tests__/mobileLoggingApi.test.ts` for the mobile-log API payload and response contract\n\nIf the change touches backend receipt, storage, or filename behavior, pair the frontend checks with the relevant backend tests around `backend/app/api/logs.py` and `backend/tests/test_logging_config.py`.\n", "0.9": "+++\ntitle = \"Frontend Logging and Tracing\"\n+++\n\nThe browser app has one shared logging API, but it can feed two different diagnostic surfaces.\n\n- browser-console output for local development and interactive debugging\n- backend trace collection for support workflows and cases where direct console access is unavailable\n\nThat split matters because a small frontend logging change can improve one surface while degrading the other.\n\n## Main Implementation Files\n\n| File | Role |\n|---|---|\n| `frontend/src/services/logger.ts` | shared logging entry point and backend-tracing orchestration |\n| `frontend/src/services/loggingConfig.ts` | fetches and caches server logging config |\n| `frontend/src/services/logBuffer.ts` | buffers trace events before flush |\n| `frontend/src/services/logTransport.ts` | sends trace batches to `/api/logs/mobile` |\n| `backend/app/api/logs.py` | serves frontend logging config and accepts uploaded trace batches |\n| `backend/app/services/log_manager.py` | writes trace batches to JSONL files and cleans up retained logs |\n| `frontend/src/pages/Login.tsx` and `frontend/src/pages/FileBrowser.tsx` | initialize tracing after authenticated app startup |\n\n## Runtime Flow\n\n1. the authenticated browser app calls `logger.initializeBackendTracing()`\n2. the logger loads config through `loggingConfig.getConfig()`\n3. console logging level is updated from backend config when enabled\n4. backend tracing is enabled only when the server config allows it\n5. each logger call writes to the console if its level passes the console threshold\n6. the same call asynchronously checks trace level and component filters before buffering a backend trace entry\n7. the buffer flushes by size or interval and posts the batch to `/api/logs/mobile`\n\nThe log call is the single source of truth. Contributors should not have to choose between console visibility and trace collection by using different APIs.\n\n## Configuration Model\n\nThe frontend pulls logging state from the backend rather than hard-coding it in the browser app.\n\n- `logging_enabled` and `logging_level` control console output\n- `tracing_enabled`, `tracing_level`, and `tracing_components` control backend trace collection\n- `frontend_tracing_username_regex` on the backend can disable tracing for users who do not match the configured pattern\n- `loggingConfig` caches the fetched config in `localStorage` for five minutes to avoid repeated requests\n\nThe logger also keeps different local defaults before server config is loaded.\n\n- development builds default to verbose console logging\n- production builds default to warnings and errors\n- test runs skip backend tracing setup entirely\n\nThe current backend contract is exposed through `GET /api/logs/config` and returns:\n\n- `logging_enabled`\n- `logging_level`\n- `tracing_enabled`\n- `tracing_level`\n- `tracing_components`\n\n`loggingConfig` then adds a client-side timestamp when caching the response locally.\n\n### Level and Component Filtering\n\nConsole logging and backend tracing are independent.\n\n- console output is gated only by `logging_enabled` plus the effective console level\n- backend tracing is gated by `tracing_enabled`, `tracing_level`, and optional component matching\n- an empty `tracing_components` list means all components are accepted\n- component matching is exact string matching, so inconsistent tag names reduce the usefulness of filtered tracing quickly\n\nLevel filtering is threshold-based.\n\n- `DEBUG` allows everything\n- `INFO` suppresses only `DEBUG`\n- `WARNING` allows `WARNING` and `ERROR`\n- `ERROR` allows only `ERROR`\n\n## Buffering and Transport\n\nBackend tracing is buffered on purpose.\n\n- `LogBuffer` groups trace entries in memory instead of posting every log call immediately\n- each batch carries a generated session ID plus device information such as user agent, screen size, and touch capability\n- the default flush behavior is size-based or time-based, whichever happens first\n- failed flushes keep the buffered entries for retry on the next flush attempt\n\nThe current implementation details are worth preserving:\n\n- `LogBuffer` generates one session ID for the browser runtime that enabled tracing\n- the batch payload includes `userAgent`, screen size, `devicePixelRatio`, platform, and touch capability\n- `LogTransport` uses `fetch` directly instead of the shared API service to avoid circular dependencies in the logging stack\n- trace uploads include the bearer token when one is available\n- if repeated flush failures push the in-memory buffer above twice the configured size, the oldest entries are dropped to cap memory growth\n\nThis design keeps routine logging cheap while still giving the backend enough session context to debug real field problems.\n\n### Backend Receipt and Storage\n\nThe backend logging API is simple and file-backed.\n\n- `POST /api/logs/mobile` accepts a trace batch for the authenticated user\n- `GET /api/logs/config` serves the frontend logging configuration\n- `GET /api/logs/list` lists available uploaded mobile-log files\n- `GET /api/logs/download/{filename}` downloads a stored log file\n\nUploaded trace batches are written under `data/mobile_logs/` as JSONL files.\n\n- the first line is metadata, including session ID, device info, server timestamp, and request metadata such as client IP or user agent\n- subsequent lines are individual log entries\n- retention cleanup is handled by `MobileLogManager.cleanup_old_logs()` using the configured retention window\n\nThis is why frontend logging changes can affect both browser behavior and support-facing backend artifacts.\n\n## Component Tags and Taxonomy\n\nComponent tags are optional for console output but important for backend tracing.\n\nRepresentative tags currently used in the frontend include:\n\n- `api`\n- `auth`\n- `backend-recovery`\n- `browser`\n- `browser-perf`\n- `companion`\n- `config`\n- `directory-search-provider`\n- `file-browser`\n- `viewer`\n- `websocket`\n\nThese tags are not just naming style. They are the filter vocabulary for targeted trace collection.\n\nContributors should:\n\n- reuse an existing tag when the log belongs to an established subsystem\n- add a new tag only when it introduces a real new filter boundary\n- keep names stable once they appear in backend config or support playbooks\n\nOne log call still drives both surfaces. The component tag only changes backend-tracing selection behavior.\n\n## Error Context and Safety Rules\n\n`logger.error()` enriches the provided context when an `Error` object is passed.\n\n- `error.message`\n- `error.stack`\n- `error.name`\n\nThat gives support traces more useful failure context without forcing every caller to serialize errors manually.\n\nContributors still need to be selective.\n\n- include actionable IDs, paths, counts, durations, or status values\n- avoid passwords, tokens, private payloads, or large opaque objects\n- avoid high-volume logs inside tight loops or animation-heavy code paths\n\n## Contributor Rules\n\n- use the shared logger instead of scattering long-lived `console.*` calls through components and hooks\n- pass a component tag when backend trace filtering matters to the workflow you are changing\n- do not assume a visible console message also means backend tracing is enabled for that session\n- keep structured context specific and actionable instead of dumping large objects or noisy state snapshots\n- do not move tracing initialization earlier than authenticated startup without checking token and request-path assumptions\n\nThe supported call shape is:\n\n- `logger.debug(message, context?, component?)`\n- `logger.info(message, context?, component?)`\n- `logger.warn(message, context?, component?)`\n- `logger.error(message, context?, component?, error?)`\n\nParameter order matters. If a component tag is needed, it is the third argument for non-error calls and still the third argument for `logger.error()` before the optional `Error` object.\n\nThe older dedicated trace-only helpers are gone. Shared logger calls are the canonical path.\n\n## Test and Runtime Nuances\n\nThe logger deliberately behaves differently in tests.\n\n- test detection suppresses console output\n- backend tracing initialization is skipped in test environments\n- `loggingConfig` falls back to a disabled state when config loading fails\n\nThis is intentional defensive behavior, not a missing feature. It keeps tests quieter and prevents trace setup from leaking across environments.\n\n## Common Failure Modes\n\n- adding raw console logs that never reach backend trace collection\n- expecting a server-side logging-config change to apply instantly while a cached config is still valid\n- using inconsistent component names that make trace filtering unreliable\n- adding high-volume debug logs that drown out the actionable events\n- treating trace transport failures as if they were equivalent to application failures\n\nOther common mistakes include:\n\n- assuming the mobile-log download endpoint is `/api/logs/{filename}` instead of the current `/api/logs/download/{filename}` route\n- documenting stale field names such as `enabled` or `log_level` instead of the current `logging_*` and `tracing_*` contract\n- swapping the logger parameter order and accidentally passing the component tag as context\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nAdd or update targeted frontend tests when the change affects config caching, filtering behavior, startup initialization, or log transport.\n\nThe current targeted suites already cover the most important contracts:\n\n- `frontend/src/services/__tests__/loggingConfig.test.ts` for config shape, threshold logic, and disabled-state behavior\n- `frontend/src/services/__tests__/mobileLoggingApi.test.ts` for the mobile-log API payload and response contract\n\nIf the change touches backend receipt, storage, or filename behavior, pair the frontend checks with the relevant backend tests around `backend/app/api/logs.py` and `backend/tests/test_logging_config.py`.\n", "1.0": "+++\ntitle = \"Frontend Logging and Tracing\"\n+++\n\nThe browser app has one shared logging API, but it can feed two different diagnostic surfaces.\n\n- browser-console output for local development and interactive debugging\n- backend trace collection for support workflows and cases where direct console access is unavailable\n\nThat split matters because a small frontend logging change can improve one surface while degrading the other.\n\n## Main Implementation Files\n\n| File | Role |\n|---|---|\n| `frontend/src/services/logger.ts` | shared logging entry point and backend-tracing orchestration |\n| `frontend/src/services/loggingConfig.ts` | fetches and caches server logging config |\n| `frontend/src/services/logBuffer.ts` | buffers trace events before flush |\n| `frontend/src/services/logTransport.ts` | sends trace batches to `/api/logs/mobile` |\n| `backend/app/api/logs.py` | serves frontend logging config and accepts uploaded trace batches |\n| `backend/app/services/log_manager.py` | writes trace batches to JSONL files and cleans up retained logs |\n| `frontend/src/pages/Login.tsx` and `frontend/src/pages/FileBrowser.tsx` | initialize tracing after authenticated app startup |\n\n## Runtime Flow\n\n1. the authenticated browser app calls `logger.initializeBackendTracing()`\n2. the logger loads config through `loggingConfig.getConfig()`\n3. console logging level is updated from backend config when enabled\n4. backend tracing is enabled only when the server config allows it\n5. each logger call writes to the console if its level passes the console threshold\n6. the same call asynchronously checks trace level and component filters before buffering a backend trace entry\n7. the buffer flushes by size or interval and posts the batch to `/api/logs/mobile`\n\nThe log call is the single source of truth. Contributors should not have to choose between console visibility and trace collection by using different APIs.\n\n## Configuration Model\n\nThe frontend pulls logging state from the backend rather than hard-coding it in the browser app.\n\n- `logging_enabled` and `logging_level` control console output\n- `tracing_enabled`, `tracing_level`, and `tracing_components` control backend trace collection\n- `frontend_tracing_username_regex` on the backend can disable tracing for users who do not match the configured pattern\n- `loggingConfig` caches the fetched config in `localStorage` for five minutes to avoid repeated requests\n\nThe logger also keeps different local defaults before server config is loaded.\n\n- development builds default to verbose console logging\n- production builds default to warnings and errors\n- test runs skip backend tracing setup entirely\n\nThe current backend contract is exposed through `GET /api/logs/config` and returns:\n\n- `logging_enabled`\n- `logging_level`\n- `tracing_enabled`\n- `tracing_level`\n- `tracing_components`\n\n`loggingConfig` then adds a client-side timestamp when caching the response locally.\n\n### Level and Component Filtering\n\nConsole logging and backend tracing are independent.\n\n- console output is gated only by `logging_enabled` plus the effective console level\n- backend tracing is gated by `tracing_enabled`, `tracing_level`, and optional component matching\n- an empty `tracing_components` list means all components are accepted\n- component matching is exact string matching, so inconsistent tag names reduce the usefulness of filtered tracing quickly\n\nLevel filtering is threshold-based.\n\n- `DEBUG` allows everything\n- `INFO` suppresses only `DEBUG`\n- `WARNING` allows `WARNING` and `ERROR`\n- `ERROR` allows only `ERROR`\n\n## Buffering and Transport\n\nBackend tracing is buffered on purpose.\n\n- `LogBuffer` groups trace entries in memory instead of posting every log call immediately\n- each batch carries a generated session ID plus device information such as user agent, screen size, and touch capability\n- the default flush behavior is size-based or time-based, whichever happens first\n- failed flushes keep the buffered entries for retry on the next flush attempt\n\nThe current implementation details are worth preserving:\n\n- `LogBuffer` generates one session ID for the browser runtime that enabled tracing\n- the batch payload includes `userAgent`, screen size, `devicePixelRatio`, platform, and touch capability\n- `LogTransport` uses `fetch` directly instead of the shared API service to avoid circular dependencies in the logging stack\n- trace uploads include the bearer token when one is available\n- if repeated flush failures push the in-memory buffer above twice the configured size, the oldest entries are dropped to cap memory growth\n\nThis design keeps routine logging cheap while still giving the backend enough session context to debug real field problems.\n\n### Backend Receipt and Storage\n\nThe backend logging API is simple and file-backed.\n\n- `POST /api/logs/mobile` accepts a trace batch for the authenticated user\n- `GET /api/logs/config` serves the frontend logging configuration\n- `GET /api/logs/list` lists available uploaded mobile-log files\n- `GET /api/logs/download/{filename}` downloads a stored log file\n\nUploaded trace batches are written under `data/mobile_logs/` as JSONL files.\n\n- the first line is metadata, including session ID, device info, server timestamp, and request metadata such as client IP or user agent\n- subsequent lines are individual log entries\n- retention cleanup is handled by `MobileLogManager.cleanup_old_logs()` using the configured retention window\n\nThis is why frontend logging changes can affect both browser behavior and support-facing backend artifacts.\n\n## Component Tags and Taxonomy\n\nComponent tags are optional for console output but important for backend tracing.\n\nRepresentative tags currently used in the frontend include:\n\n- `api`\n- `auth`\n- `backend-recovery`\n- `browser`\n- `browser-perf`\n- `companion`\n- `config`\n- `directory-search-provider`\n- `file-browser`\n- `viewer`\n- `websocket`\n\nThese tags are not just naming style. They are the filter vocabulary for targeted trace collection.\n\nContributors should:\n\n- reuse an existing tag when the log belongs to an established subsystem\n- add a new tag only when it introduces a real new filter boundary\n- keep names stable once they appear in backend config or support playbooks\n\nOne log call still drives both surfaces. The component tag only changes backend-tracing selection behavior.\n\n## Error Context and Safety Rules\n\n`logger.error()` enriches the provided context when an `Error` object is passed.\n\n- `error.message`\n- `error.stack`\n- `error.name`\n\nThat gives support traces more useful failure context without forcing every caller to serialize errors manually.\n\nContributors still need to be selective.\n\n- include actionable IDs, paths, counts, durations, or status values\n- avoid passwords, tokens, private payloads, or large opaque objects\n- avoid high-volume logs inside tight loops or animation-heavy code paths\n\n## Contributor Rules\n\n- use the shared logger instead of scattering long-lived `console.*` calls through components and hooks\n- pass a component tag when backend trace filtering matters to the workflow you are changing\n- do not assume a visible console message also means backend tracing is enabled for that session\n- keep structured context specific and actionable instead of dumping large objects or noisy state snapshots\n- do not move tracing initialization earlier than authenticated startup without checking token and request-path assumptions\n\nThe supported call shape is:\n\n- `logger.debug(message, context?, component?)`\n- `logger.info(message, context?, component?)`\n- `logger.warn(message, context?, component?)`\n- `logger.error(message, context?, component?, error?)`\n\nParameter order matters. If a component tag is needed, it is the third argument for non-error calls and still the third argument for `logger.error()` before the optional `Error` object.\n\nThe older dedicated trace-only helpers are gone. Shared logger calls are the canonical path.\n\n## Test and Runtime Nuances\n\nThe logger deliberately behaves differently in tests.\n\n- test detection suppresses console output\n- backend tracing initialization is skipped in test environments\n- `loggingConfig` falls back to a disabled state when config loading fails\n\nThis is intentional defensive behavior, not a missing feature. It keeps tests quieter and prevents trace setup from leaking across environments.\n\n## Common Failure Modes\n\n- adding raw console logs that never reach backend trace collection\n- expecting a server-side logging-config change to apply instantly while a cached config is still valid\n- using inconsistent component names that make trace filtering unreliable\n- adding high-volume debug logs that drown out the actionable events\n- treating trace transport failures as if they were equivalent to application failures\n\nOther common mistakes include:\n\n- assuming the mobile-log download endpoint is `/api/logs/{filename}` instead of the current `/api/logs/download/{filename}` route\n- documenting stale field names such as `enabled` or `log_level` instead of the current `logging_*` and `tracing_*` contract\n- swapping the logger parameter order and accidentally passing the component tag as context\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nAdd or update targeted frontend tests when the change affects config caching, filtering behavior, startup initialization, or log transport.\n\nThe current targeted suites already cover the most important contracts:\n\n- `frontend/src/services/__tests__/loggingConfig.test.ts` for config shape, threshold logic, and disabled-state behavior\n- `frontend/src/services/__tests__/mobileLoggingApi.test.ts` for the mobile-log API payload and response contract\n\nIf the change touches backend receipt, storage, or filename behavior, pair the frontend checks with the relevant backend tests around `backend/app/api/logs.py` and `backend/tests/test_logging_config.py`.\n", "2.0": "+++\ntitle = \"Frontend Logging and Tracing\"\n+++\n\nThe browser app has one shared logging API, but it can feed two different diagnostic surfaces.\n\n- browser-console output for local development and interactive debugging\n- backend trace collection for support workflows and cases where direct console access is unavailable\n\nThat split matters because a small frontend logging change can improve one surface while degrading the other.\n\n## Main Implementation Files\n\n| File | Role |\n|---|---|\n| `frontend/src/services/logger.ts` | shared logging entry point and backend-tracing orchestration |\n| `frontend/src/services/loggingConfig.ts` | fetches and caches server logging config |\n| `frontend/src/services/logBuffer.ts` | buffers trace events before flush |\n| `frontend/src/services/logTransport.ts` | sends trace batches to `/api/logs/mobile` |\n| `backend/app/api/logs.py` | serves frontend logging config and accepts uploaded trace batches |\n| `backend/app/services/log_manager.py` | writes trace batches to JSONL files and cleans up retained logs |\n| `frontend/src/pages/Login.tsx` and `frontend/src/pages/FileBrowser.tsx` | initialize tracing after authenticated app startup |\n\n## Runtime Flow\n\n1. the authenticated browser app calls `logger.initializeBackendTracing()`\n2. the logger loads config through `loggingConfig.getConfig()`\n3. console logging level is updated from backend config when enabled\n4. backend tracing is enabled only when the server config allows it\n5. each logger call writes to the console if its level passes the console threshold\n6. the same call asynchronously checks trace level and component filters before buffering a backend trace entry\n7. the buffer flushes by size or interval and posts the batch to `/api/logs/mobile`\n\nThe log call is the single source of truth. Contributors should not have to choose between console visibility and trace collection by using different APIs.\n\n## Configuration Model\n\nThe frontend pulls logging state from the backend rather than hard-coding it in the browser app.\n\n- `logging_enabled` and `logging_level` control console output\n- `tracing_enabled`, `tracing_level`, and `tracing_components` control backend trace collection\n- `frontend_tracing_username_regex` on the backend can disable tracing for users who do not match the configured pattern\n- `loggingConfig` caches the fetched config in `localStorage` for five minutes to avoid repeated requests\n\nThe logger also keeps different local defaults before server config is loaded.\n\n- development builds default to verbose console logging\n- production builds default to warnings and errors\n- test runs skip backend tracing setup entirely\n\nThe current backend contract is exposed through `GET /api/logs/config` and returns:\n\n- `logging_enabled`\n- `logging_level`\n- `tracing_enabled`\n- `tracing_level`\n- `tracing_components`\n\n`loggingConfig` then adds a client-side timestamp when caching the response locally.\n\n### Level and Component Filtering\n\nConsole logging and backend tracing are independent.\n\n- console output is gated only by `logging_enabled` plus the effective console level\n- backend tracing is gated by `tracing_enabled`, `tracing_level`, and optional component matching\n- an empty `tracing_components` list means all components are accepted\n- component matching is exact string matching, so inconsistent tag names reduce the usefulness of filtered tracing quickly\n\nLevel filtering is threshold-based.\n\n- `DEBUG` allows everything\n- `INFO` suppresses only `DEBUG`\n- `WARNING` allows `WARNING` and `ERROR`\n- `ERROR` allows only `ERROR`\n\n## Buffering and Transport\n\nBackend tracing is buffered on purpose.\n\n- `LogBuffer` groups trace entries in memory instead of posting every log call immediately\n- each batch carries a generated session ID plus device information such as user agent, screen size, and touch capability\n- the default flush behavior is size-based or time-based, whichever happens first\n- failed flushes keep the buffered entries for retry on the next flush attempt\n\nThe current implementation details are worth preserving:\n\n- `LogBuffer` generates one session ID for the browser runtime that enabled tracing\n- the batch payload includes `userAgent`, screen size, `devicePixelRatio`, platform, and touch capability\n- `LogTransport` uses `fetch` directly instead of the shared API service to avoid circular dependencies in the logging stack\n- trace uploads include the bearer token when one is available\n- if repeated flush failures push the in-memory buffer above twice the configured size, the oldest entries are dropped to cap memory growth\n\nThis design keeps routine logging cheap while still giving the backend enough session context to debug real field problems.\n\n### Backend Receipt and Storage\n\nThe backend logging API is simple and file-backed.\n\n- `POST /api/logs/mobile` accepts a trace batch for the authenticated user\n- `GET /api/logs/config` serves the frontend logging configuration\n- `GET /api/logs/list` lists available uploaded mobile-log files\n- `GET /api/logs/download/{filename}` downloads a stored log file\n\nUploaded trace batches are written under `data/mobile_logs/` as JSONL files.\n\n- the first line is metadata, including session ID, device info, server timestamp, and request metadata such as client IP or user agent\n- subsequent lines are individual log entries\n- retention cleanup is handled by `MobileLogManager.cleanup_old_logs()` using the configured retention window\n\nThis is why frontend logging changes can affect both browser behavior and support-facing backend artifacts.\n\n## Component Tags and Taxonomy\n\nComponent tags are optional for console output but important for backend tracing.\n\nRepresentative tags currently used in the frontend include:\n\n- `api`\n- `auth`\n- `backend-recovery`\n- `browser`\n- `browser-perf`\n- `companion`\n- `config`\n- `directory-search-provider`\n- `file-browser`\n- `viewer`\n- `websocket`\n\nThese tags are not just naming style. They are the filter vocabulary for targeted trace collection.\n\nContributors should:\n\n- reuse an existing tag when the log belongs to an established subsystem\n- add a new tag only when it introduces a real new filter boundary\n- keep names stable once they appear in backend config or support playbooks\n\nOne log call still drives both surfaces. The component tag only changes backend-tracing selection behavior.\n\n## Error Context and Safety Rules\n\n`logger.error()` enriches the provided context when an `Error` object is passed.\n\n- `error.message`\n- `error.stack`\n- `error.name`\n\nThat gives support traces more useful failure context without forcing every caller to serialize errors manually.\n\nContributors still need to be selective.\n\n- include actionable IDs, paths, counts, durations, or status values\n- avoid passwords, tokens, private payloads, or large opaque objects\n- avoid high-volume logs inside tight loops or animation-heavy code paths\n\n## Contributor Rules\n\n- use the shared logger instead of scattering long-lived `console.*` calls through components and hooks\n- pass a component tag when backend trace filtering matters to the workflow you are changing\n- do not assume a visible console message also means backend tracing is enabled for that session\n- keep structured context specific and actionable instead of dumping large objects or noisy state snapshots\n- do not move tracing initialization earlier than authenticated startup without checking token and request-path assumptions\n\nThe supported call shape is:\n\n- `logger.debug(message, context?, component?)`\n- `logger.info(message, context?, component?)`\n- `logger.warn(message, context?, component?)`\n- `logger.error(message, context?, component?, error?)`\n\nParameter order matters. If a component tag is needed, it is the third argument for non-error calls and still the third argument for `logger.error()` before the optional `Error` object.\n\nThe older dedicated trace-only helpers are gone. Shared logger calls are the canonical path.\n\n## Test and Runtime Nuances\n\nThe logger deliberately behaves differently in tests.\n\n- test detection suppresses console output\n- backend tracing initialization is skipped in test environments\n- `loggingConfig` falls back to a disabled state when config loading fails\n\nThis is intentional defensive behavior, not a missing feature. It keeps tests quieter and prevents trace setup from leaking across environments.\n\n## Common Failure Modes\n\n- adding raw console logs that never reach backend trace collection\n- expecting a server-side logging-config change to apply instantly while a cached config is still valid\n- using inconsistent component names that make trace filtering unreliable\n- adding high-volume debug logs that drown out the actionable events\n- treating trace transport failures as if they were equivalent to application failures\n\nOther common mistakes include:\n\n- assuming the mobile-log download endpoint is `/api/logs/{filename}` instead of the current `/api/logs/download/{filename}` route\n- documenting stale field names such as `enabled` or `log_level` instead of the current `logging_*` and `tracing_*` contract\n- swapping the logger parameter order and accidentally passing the component tag as context\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nAdd or update targeted frontend tests when the change affects config caching, filtering behavior, startup initialization, or log transport.\n\nThe current targeted suites already cover the most important contracts:\n\n- `frontend/src/services/__tests__/loggingConfig.test.ts` for config shape, threshold logic, and disabled-state behavior\n- `frontend/src/services/__tests__/mobileLoggingApi.test.ts` for the mobile-log API payload and response contract\n\nIf the change touches backend receipt, storage, or filename behavior, pair the frontend checks with the relevant backend tests around `backend/app/api/logs.py` and `backend/tests/test_logging_config.py`.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Frontend Logging and Tracing\"\n+++\n\nThe browser app has one shared logging API, but it can feed two different diagnostic surfaces.\n\n- browser-console output for local development and interactive debugging\n- backend trace collection for support workflows and cases where direct console access is unavailable\n\nThat split matters because a small frontend logging change can improve one surface while degrading the other.\n\n## Main Implementation Files\n\n| File | Role |\n|---|---|\n| `frontend/src/services/logger.ts` | shared logging entry point and backend-tracing orchestration |\n| `frontend/src/services/loggingConfig.ts` | fetches and caches server logging config |\n| `frontend/src/services/logBuffer.ts` | buffers trace events before flush |\n| `frontend/src/services/logTransport.ts` | sends trace batches to `/api/logs/mobile` |\n| `backend/app/api/logs.py` | serves frontend logging config and accepts uploaded trace batches |\n| `backend/app/services/log_manager.py` | writes trace batches to JSONL files and cleans up retained logs |\n| `frontend/src/pages/Login.tsx` and `frontend/src/pages/FileBrowser.tsx` | initialize tracing after authenticated app startup |\n\n## Runtime Flow\n\n1. the authenticated browser app calls `logger.initializeBackendTracing()`\n2. the logger loads config through `loggingConfig.getConfig()`\n3. console logging level is updated from backend config when enabled\n4. backend tracing is enabled only when the server config allows it\n5. each logger call writes to the console if its level passes the console threshold\n6. the same call asynchronously checks trace level and component filters before buffering a backend trace entry\n7. the buffer flushes by size or interval and posts the batch to `/api/logs/mobile`\n\nThe log call is the single source of truth. Contributors should not have to choose between console visibility and trace collection by using different APIs.\n\n## Configuration Model\n\nThe frontend pulls logging state from the backend rather than hard-coding it in the browser app.\n\n- `logging_enabled` and `logging_level` control console output\n- `tracing_enabled`, `tracing_level`, and `tracing_components` control backend trace collection\n- `frontend_tracing_username_regex` on the backend can disable tracing for users who do not match the configured pattern\n- `loggingConfig` caches the fetched config in `localStorage` for five minutes to avoid repeated requests\n\nThe logger also keeps different local defaults before server config is loaded.\n\n- development builds default to verbose console logging\n- production builds default to warnings and errors\n- test runs skip backend tracing setup entirely\n\nThe current backend contract is exposed through `GET /api/logs/config` and returns:\n\n- `logging_enabled`\n- `logging_level`\n- `tracing_enabled`\n- `tracing_level`\n- `tracing_components`\n\n`loggingConfig` then adds a client-side timestamp when caching the response locally.\n\n### Level and Component Filtering\n\nConsole logging and backend tracing are independent.\n\n- console output is gated only by `logging_enabled` plus the effective console level\n- backend tracing is gated by `tracing_enabled`, `tracing_level`, and optional component matching\n- an empty `tracing_components` list means all components are accepted\n- component matching is exact string matching, so inconsistent tag names reduce the usefulness of filtered tracing quickly\n\nLevel filtering is threshold-based.\n\n- `DEBUG` allows everything\n- `INFO` suppresses only `DEBUG`\n- `WARNING` allows `WARNING` and `ERROR`\n- `ERROR` allows only `ERROR`\n\n## Buffering and Transport\n\nBackend tracing is buffered on purpose.\n\n- `LogBuffer` groups trace entries in memory instead of posting every log call immediately\n- each batch carries a generated session ID plus device information such as user agent, screen size, and touch capability\n- the default flush behavior is size-based or time-based, whichever happens first\n- failed flushes keep the buffered entries for retry on the next flush attempt\n\nThe current implementation details are worth preserving:\n\n- `LogBuffer` generates one session ID for the browser runtime that enabled tracing\n- the batch payload includes `userAgent`, screen size, `devicePixelRatio`, platform, and touch capability\n- `LogTransport` uses `fetch` directly instead of the shared API service to avoid circular dependencies in the logging stack\n- trace uploads include the bearer token when one is available\n- if repeated flush failures push the in-memory buffer above twice the configured size, the oldest entries are dropped to cap memory growth\n\nThis design keeps routine logging cheap while still giving the backend enough session context to debug real field problems.\n\n### Backend Receipt and Storage\n\nThe backend logging API is simple and file-backed.\n\n- `POST /api/logs/mobile` accepts a trace batch for the authenticated user\n- `GET /api/logs/config` serves the frontend logging configuration\n- `GET /api/logs/list` lists available uploaded mobile-log files\n- `GET /api/logs/download/{filename}` downloads a stored log file\n\nUploaded trace batches are written under `data/mobile_logs/` as JSONL files.\n\n- the first line is metadata, including session ID, device info, server timestamp, and request metadata such as client IP or user agent\n- subsequent lines are individual log entries\n- retention cleanup is handled by `MobileLogManager.cleanup_old_logs()` using the configured retention window\n\nThis is why frontend logging changes can affect both browser behavior and support-facing backend artifacts.\n\n## Component Tags and Taxonomy\n\nComponent tags are optional for console output but important for backend tracing.\n\nRepresentative tags currently used in the frontend include:\n\n- `api`\n- `auth`\n- `backend-recovery`\n- `browser`\n- `browser-perf`\n- `companion`\n- `config`\n- `directory-search-provider`\n- `file-browser`\n- `viewer`\n- `websocket`\n\nThese tags are not just naming style. They are the filter vocabulary for targeted trace collection.\n\nContributors should:\n\n- reuse an existing tag when the log belongs to an established subsystem\n- add a new tag only when it introduces a real new filter boundary\n- keep names stable once they appear in backend config or support playbooks\n\nOne log call still drives both surfaces. The component tag only changes backend-tracing selection behavior.\n\n## Error Context and Safety Rules\n\n`logger.error()` enriches the provided context when an `Error` object is passed.\n\n- `error.message`\n- `error.stack`\n- `error.name`\n\nThat gives support traces more useful failure context without forcing every caller to serialize errors manually.\n\nContributors still need to be selective.\n\n- include actionable IDs, paths, counts, durations, or status values\n- avoid passwords, tokens, private payloads, or large opaque objects\n- avoid high-volume logs inside tight loops or animation-heavy code paths\n\n## Contributor Rules\n\n- use the shared logger instead of scattering long-lived `console.*` calls through components and hooks\n- pass a component tag when backend trace filtering matters to the workflow you are changing\n- do not assume a visible console message also means backend tracing is enabled for that session\n- keep structured context specific and actionable instead of dumping large objects or noisy state snapshots\n- do not move tracing initialization earlier than authenticated startup without checking token and request-path assumptions\n\nThe supported call shape is:\n\n- `logger.debug(message, context?, component?)`\n- `logger.info(message, context?, component?)`\n- `logger.warn(message, context?, component?)`\n- `logger.error(message, context?, component?, error?)`\n\nParameter order matters. If a component tag is needed, it is the third argument for non-error calls and still the third argument for `logger.error()` before the optional `Error` object.\n\nThe older dedicated trace-only helpers are gone. Shared logger calls are the canonical path.\n\n## Test and Runtime Nuances\n\nThe logger deliberately behaves differently in tests.\n\n- test detection suppresses console output\n- backend tracing initialization is skipped in test environments\n- `loggingConfig` falls back to a disabled state when config loading fails\n\nThis is intentional defensive behavior, not a missing feature. It keeps tests quieter and prevents trace setup from leaking across environments.\n\n## Common Failure Modes\n\n- adding raw console logs that never reach backend trace collection\n- expecting a server-side logging-config change to apply instantly while a cached config is still valid\n- using inconsistent component names that make trace filtering unreliable\n- adding high-volume debug logs that drown out the actionable events\n- treating trace transport failures as if they were equivalent to application failures\n\nOther common mistakes include:\n\n- assuming the mobile-log download endpoint is `/api/logs/{filename}` instead of the current `/api/logs/download/{filename}` route\n- documenting stale field names such as `enabled` or `log_level` instead of the current `logging_*` and `tracing_*` contract\n- swapping the logger parameter order and accidentally passing the component tag as context\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nAdd or update targeted frontend tests when the change affects config caching, filtering behavior, startup initialization, or log transport.\n\nThe current targeted suites already cover the most important contracts:\n\n- `frontend/src/services/__tests__/loggingConfig.test.ts` for config shape, threshold logic, and disabled-state behavior\n- `frontend/src/services/__tests__/mobileLoggingApi.test.ts` for the mobile-log API payload and response contract\n\nIf the change touches backend receipt, storage, or filename behavior, pair the frontend checks with the relevant backend tests around `backend/app/api/logs.py` and `backend/tests/test_logging_config.py`.\n", "0.8": "+++\ntitle = \"Frontend Logging and Tracing\"\n+++\n\nThe browser app has one shared logging API, but it can feed two different diagnostic surfaces.\n\n- browser-console output for local development and interactive debugging\n- backend trace collection for support workflows and cases where direct console access is unavailable\n\nThat split matters because a small frontend logging change can improve one surface while degrading the other.\n\n## Main Implementation Files\n\n| File | Role |\n|---|---|\n| `frontend/src/services/logger.ts` | shared logging entry point and backend-tracing orchestration |\n| `frontend/src/services/loggingConfig.ts` | fetches and caches server logging config |\n| `frontend/src/services/logBuffer.ts` | buffers trace events before flush |\n| `frontend/src/services/logTransport.ts` | sends trace batches to `/api/logs/mobile` |\n| `backend/app/api/logs.py` | serves frontend logging config and accepts uploaded trace batches |\n| `backend/app/services/log_manager.py` | writes trace batches to JSONL files and cleans up retained logs |\n| `frontend/src/pages/Login.tsx` and `frontend/src/pages/FileBrowser.tsx` | initialize tracing after authenticated app startup |\n\n## Runtime Flow\n\n1. the authenticated browser app calls `logger.initializeBackendTracing()`\n2. the logger loads config through `loggingConfig.getConfig()`\n3. console logging level is updated from backend config when enabled\n4. backend tracing is enabled only when the server config allows it\n5. each logger call writes to the console if its level passes the console threshold\n6. the same call asynchronously checks trace level and component filters before buffering a backend trace entry\n7. the buffer flushes by size or interval and posts the batch to `/api/logs/mobile`\n\nThe log call is the single source of truth. Contributors should not have to choose between console visibility and trace collection by using different APIs.\n\n## Configuration Model\n\nThe frontend pulls logging state from the backend rather than hard-coding it in the browser app.\n\n- `logging_enabled` and `logging_level` control console output\n- `tracing_enabled`, `tracing_level`, and `tracing_components` control backend trace collection\n- `frontend_tracing_username_regex` on the backend can disable tracing for users who do not match the configured pattern\n- `loggingConfig` caches the fetched config in `localStorage` for five minutes to avoid repeated requests\n\nThe logger also keeps different local defaults before server config is loaded.\n\n- development builds default to verbose console logging\n- production builds default to warnings and errors\n- test runs skip backend tracing setup entirely\n\nThe current backend contract is exposed through `GET /api/logs/config` and returns:\n\n- `logging_enabled`\n- `logging_level`\n- `tracing_enabled`\n- `tracing_level`\n- `tracing_components`\n\n`loggingConfig` then adds a client-side timestamp when caching the response locally.\n\n### Level and Component Filtering\n\nConsole logging and backend tracing are independent.\n\n- console output is gated only by `logging_enabled` plus the effective console level\n- backend tracing is gated by `tracing_enabled`, `tracing_level`, and optional component matching\n- an empty `tracing_components` list means all components are accepted\n- component matching is exact string matching, so inconsistent tag names reduce the usefulness of filtered tracing quickly\n\nLevel filtering is threshold-based.\n\n- `DEBUG` allows everything\n- `INFO` suppresses only `DEBUG`\n- `WARNING` allows `WARNING` and `ERROR`\n- `ERROR` allows only `ERROR`\n\n## Buffering and Transport\n\nBackend tracing is buffered on purpose.\n\n- `LogBuffer` groups trace entries in memory instead of posting every log call immediately\n- each batch carries a generated session ID plus device information such as user agent, screen size, and touch capability\n- the default flush behavior is size-based or time-based, whichever happens first\n- failed flushes keep the buffered entries for retry on the next flush attempt\n\nThe current implementation details are worth preserving:\n\n- `LogBuffer` generates one session ID for the browser runtime that enabled tracing\n- the batch payload includes `userAgent`, screen size, `devicePixelRatio`, platform, and touch capability\n- `LogTransport` uses `fetch` directly instead of the shared API service to avoid circular dependencies in the logging stack\n- trace uploads include the bearer token when one is available\n- if repeated flush failures push the in-memory buffer above twice the configured size, the oldest entries are dropped to cap memory growth\n\nThis design keeps routine logging cheap while still giving the backend enough session context to debug real field problems.\n\n### Backend Receipt and Storage\n\nThe backend logging API is simple and file-backed.\n\n- `POST /api/logs/mobile` accepts a trace batch for the authenticated user\n- `GET /api/logs/config` serves the frontend logging configuration\n- `GET /api/logs/list` lists available uploaded mobile-log files\n- `GET /api/logs/download/{filename}` downloads a stored log file\n\nUploaded trace batches are written under `data/mobile_logs/` as JSONL files.\n\n- the first line is metadata, including session ID, device info, server timestamp, and request metadata such as client IP or user agent\n- subsequent lines are individual log entries\n- retention cleanup is handled by `MobileLogManager.cleanup_old_logs()` using the configured retention window\n\nThis is why frontend logging changes can affect both browser behavior and support-facing backend artifacts.\n\n## Component Tags and Taxonomy\n\nComponent tags are optional for console output but important for backend tracing.\n\nRepresentative tags currently used in the frontend include:\n\n- `api`\n- `auth`\n- `backend-recovery`\n- `browser`\n- `browser-perf`\n- `companion`\n- `config`\n- `directory-search-provider`\n- `file-browser`\n- `viewer`\n- `websocket`\n\nThese tags are not just naming style. They are the filter vocabulary for targeted trace collection.\n\nContributors should:\n\n- reuse an existing tag when the log belongs to an established subsystem\n- add a new tag only when it introduces a real new filter boundary\n- keep names stable once they appear in backend config or support playbooks\n\nOne log call still drives both surfaces. The component tag only changes backend-tracing selection behavior.\n\n## Error Context and Safety Rules\n\n`logger.error()` enriches the provided context when an `Error` object is passed.\n\n- `error.message`\n- `error.stack`\n- `error.name`\n\nThat gives support traces more useful failure context without forcing every caller to serialize errors manually.\n\nContributors still need to be selective.\n\n- include actionable IDs, paths, counts, durations, or status values\n- avoid passwords, tokens, private payloads, or large opaque objects\n- avoid high-volume logs inside tight loops or animation-heavy code paths\n\n## Contributor Rules\n\n- use the shared logger instead of scattering long-lived `console.*` calls through components and hooks\n- pass a component tag when backend trace filtering matters to the workflow you are changing\n- do not assume a visible console message also means backend tracing is enabled for that session\n- keep structured context specific and actionable instead of dumping large objects or noisy state snapshots\n- do not move tracing initialization earlier than authenticated startup without checking token and request-path assumptions\n\nThe supported call shape is:\n\n- `logger.debug(message, context?, component?)`\n- `logger.info(message, context?, component?)`\n- `logger.warn(message, context?, component?)`\n- `logger.error(message, context?, component?, error?)`\n\nParameter order matters. If a component tag is needed, it is the third argument for non-error calls and still the third argument for `logger.error()` before the optional `Error` object.\n\nThe older dedicated trace-only helpers are gone. Shared logger calls are the canonical path.\n\n## Test and Runtime Nuances\n\nThe logger deliberately behaves differently in tests.\n\n- test detection suppresses console output\n- backend tracing initialization is skipped in test environments\n- `loggingConfig` falls back to a disabled state when config loading fails\n\nThis is intentional defensive behavior, not a missing feature. It keeps tests quieter and prevents trace setup from leaking across environments.\n\n## Common Failure Modes\n\n- adding raw console logs that never reach backend trace collection\n- expecting a server-side logging-config change to apply instantly while a cached config is still valid\n- using inconsistent component names that make trace filtering unreliable\n- adding high-volume debug logs that drown out the actionable events\n- treating trace transport failures as if they were equivalent to application failures\n\nOther common mistakes include:\n\n- assuming the mobile-log download endpoint is `/api/logs/{filename}` instead of the current `/api/logs/download/{filename}` route\n- documenting stale field names such as `enabled` or `log_level` instead of the current `logging_*` and `tracing_*` contract\n- swapping the logger parameter order and accidentally passing the component tag as context\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nAdd or update targeted frontend tests when the change affects config caching, filtering behavior, startup initialization, or log transport.\n\nThe current targeted suites already cover the most important contracts:\n\n- `frontend/src/services/__tests__/loggingConfig.test.ts` for config shape, threshold logic, and disabled-state behavior\n- `frontend/src/services/__tests__/mobileLoggingApi.test.ts` for the mobile-log API payload and response contract\n\nIf the change touches backend receipt, storage, or filename behavior, pair the frontend checks with the relevant backend tests around `backend/app/api/logs.py` and `backend/tests/test_logging_config.py`.\n", "0.9": "+++\ntitle = \"Frontend Logging and Tracing\"\n+++\n\nThe browser app has one shared logging API, but it can feed two different diagnostic surfaces.\n\n- browser-console output for local development and interactive debugging\n- backend trace collection for support workflows and cases where direct console access is unavailable\n\nThat split matters because a small frontend logging change can improve one surface while degrading the other.\n\n## Main Implementation Files\n\n| File | Role |\n|---|---|\n| `frontend/src/services/logger.ts` | shared logging entry point and backend-tracing orchestration |\n| `frontend/src/services/loggingConfig.ts` | fetches and caches server logging config |\n| `frontend/src/services/logBuffer.ts` | buffers trace events before flush |\n| `frontend/src/services/logTransport.ts` | sends trace batches to `/api/logs/mobile` |\n| `backend/app/api/logs.py` | serves frontend logging config and accepts uploaded trace batches |\n| `backend/app/services/log_manager.py` | writes trace batches to JSONL files and cleans up retained logs |\n| `frontend/src/pages/Login.tsx` and `frontend/src/pages/FileBrowser.tsx` | initialize tracing after authenticated app startup |\n\n## Runtime Flow\n\n1. the authenticated browser app calls `logger.initializeBackendTracing()`\n2. the logger loads config through `loggingConfig.getConfig()`\n3. console logging level is updated from backend config when enabled\n4. backend tracing is enabled only when the server config allows it\n5. each logger call writes to the console if its level passes the console threshold\n6. the same call asynchronously checks trace level and component filters before buffering a backend trace entry\n7. the buffer flushes by size or interval and posts the batch to `/api/logs/mobile`\n\nThe log call is the single source of truth. Contributors should not have to choose between console visibility and trace collection by using different APIs.\n\n## Configuration Model\n\nThe frontend pulls logging state from the backend rather than hard-coding it in the browser app.\n\n- `logging_enabled` and `logging_level` control console output\n- `tracing_enabled`, `tracing_level`, and `tracing_components` control backend trace collection\n- `frontend_tracing_username_regex` on the backend can disable tracing for users who do not match the configured pattern\n- `loggingConfig` caches the fetched config in `localStorage` for five minutes to avoid repeated requests\n\nThe logger also keeps different local defaults before server config is loaded.\n\n- development builds default to verbose console logging\n- production builds default to warnings and errors\n- test runs skip backend tracing setup entirely\n\nThe current backend contract is exposed through `GET /api/logs/config` and returns:\n\n- `logging_enabled`\n- `logging_level`\n- `tracing_enabled`\n- `tracing_level`\n- `tracing_components`\n\n`loggingConfig` then adds a client-side timestamp when caching the response locally.\n\n### Level and Component Filtering\n\nConsole logging and backend tracing are independent.\n\n- console output is gated only by `logging_enabled` plus the effective console level\n- backend tracing is gated by `tracing_enabled`, `tracing_level`, and optional component matching\n- an empty `tracing_components` list means all components are accepted\n- component matching is exact string matching, so inconsistent tag names reduce the usefulness of filtered tracing quickly\n\nLevel filtering is threshold-based.\n\n- `DEBUG` allows everything\n- `INFO` suppresses only `DEBUG`\n- `WARNING` allows `WARNING` and `ERROR`\n- `ERROR` allows only `ERROR`\n\n## Buffering and Transport\n\nBackend tracing is buffered on purpose.\n\n- `LogBuffer` groups trace entries in memory instead of posting every log call immediately\n- each batch carries a generated session ID plus device information such as user agent, screen size, and touch capability\n- the default flush behavior is size-based or time-based, whichever happens first\n- failed flushes keep the buffered entries for retry on the next flush attempt\n\nThe current implementation details are worth preserving:\n\n- `LogBuffer` generates one session ID for the browser runtime that enabled tracing\n- the batch payload includes `userAgent`, screen size, `devicePixelRatio`, platform, and touch capability\n- `LogTransport` uses `fetch` directly instead of the shared API service to avoid circular dependencies in the logging stack\n- trace uploads include the bearer token when one is available\n- if repeated flush failures push the in-memory buffer above twice the configured size, the oldest entries are dropped to cap memory growth\n\nThis design keeps routine logging cheap while still giving the backend enough session context to debug real field problems.\n\n### Backend Receipt and Storage\n\nThe backend logging API is simple and file-backed.\n\n- `POST /api/logs/mobile` accepts a trace batch for the authenticated user\n- `GET /api/logs/config` serves the frontend logging configuration\n- `GET /api/logs/list` lists available uploaded mobile-log files\n- `GET /api/logs/download/{filename}` downloads a stored log file\n\nUploaded trace batches are written under `data/mobile_logs/` as JSONL files.\n\n- the first line is metadata, including session ID, device info, server timestamp, and request metadata such as client IP or user agent\n- subsequent lines are individual log entries\n- retention cleanup is handled by `MobileLogManager.cleanup_old_logs()` using the configured retention window\n\nThis is why frontend logging changes can affect both browser behavior and support-facing backend artifacts.\n\n## Component Tags and Taxonomy\n\nComponent tags are optional for console output but important for backend tracing.\n\nRepresentative tags currently used in the frontend include:\n\n- `api`\n- `auth`\n- `backend-recovery`\n- `browser`\n- `browser-perf`\n- `companion`\n- `config`\n- `directory-search-provider`\n- `file-browser`\n- `viewer`\n- `websocket`\n\nThese tags are not just naming style. They are the filter vocabulary for targeted trace collection.\n\nContributors should:\n\n- reuse an existing tag when the log belongs to an established subsystem\n- add a new tag only when it introduces a real new filter boundary\n- keep names stable once they appear in backend config or support playbooks\n\nOne log call still drives both surfaces. The component tag only changes backend-tracing selection behavior.\n\n## Error Context and Safety Rules\n\n`logger.error()` enriches the provided context when an `Error` object is passed.\n\n- `error.message`\n- `error.stack`\n- `error.name`\n\nThat gives support traces more useful failure context without forcing every caller to serialize errors manually.\n\nContributors still need to be selective.\n\n- include actionable IDs, paths, counts, durations, or status values\n- avoid passwords, tokens, private payloads, or large opaque objects\n- avoid high-volume logs inside tight loops or animation-heavy code paths\n\n## Contributor Rules\n\n- use the shared logger instead of scattering long-lived `console.*` calls through components and hooks\n- pass a component tag when backend trace filtering matters to the workflow you are changing\n- do not assume a visible console message also means backend tracing is enabled for that session\n- keep structured context specific and actionable instead of dumping large objects or noisy state snapshots\n- do not move tracing initialization earlier than authenticated startup without checking token and request-path assumptions\n\nThe supported call shape is:\n\n- `logger.debug(message, context?, component?)`\n- `logger.info(message, context?, component?)`\n- `logger.warn(message, context?, component?)`\n- `logger.error(message, context?, component?, error?)`\n\nParameter order matters. If a component tag is needed, it is the third argument for non-error calls and still the third argument for `logger.error()` before the optional `Error` object.\n\nThe older dedicated trace-only helpers are gone. Shared logger calls are the canonical path.\n\n## Test and Runtime Nuances\n\nThe logger deliberately behaves differently in tests.\n\n- test detection suppresses console output\n- backend tracing initialization is skipped in test environments\n- `loggingConfig` falls back to a disabled state when config loading fails\n\nThis is intentional defensive behavior, not a missing feature. It keeps tests quieter and prevents trace setup from leaking across environments.\n\n## Common Failure Modes\n\n- adding raw console logs that never reach backend trace collection\n- expecting a server-side logging-config change to apply instantly while a cached config is still valid\n- using inconsistent component names that make trace filtering unreliable\n- adding high-volume debug logs that drown out the actionable events\n- treating trace transport failures as if they were equivalent to application failures\n\nOther common mistakes include:\n\n- assuming the mobile-log download endpoint is `/api/logs/{filename}` instead of the current `/api/logs/download/{filename}` route\n- documenting stale field names such as `enabled` or `log_level` instead of the current `logging_*` and `tracing_*` contract\n- swapping the logger parameter order and accidentally passing the component tag as context\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nAdd or update targeted frontend tests when the change affects config caching, filtering behavior, startup initialization, or log transport.\n\nThe current targeted suites already cover the most important contracts:\n\n- `frontend/src/services/__tests__/loggingConfig.test.ts` for config shape, threshold logic, and disabled-state behavior\n- `frontend/src/services/__tests__/mobileLoggingApi.test.ts` for the mobile-log API payload and response contract\n\nIf the change touches backend receipt, storage, or filename behavior, pair the frontend checks with the relevant backend tests around `backend/app/api/logs.py` and `backend/tests/test_logging_config.py`.\n", "1.0": "+++\ntitle = \"Frontend Logging and Tracing\"\n+++\n\nThe browser app has one shared logging API, but it can feed two different diagnostic surfaces.\n\n- browser-console output for local development and interactive debugging\n- backend trace collection for support workflows and cases where direct console access is unavailable\n\nThat split matters because a small frontend logging change can improve one surface while degrading the other.\n\n## Main Implementation Files\n\n| File | Role |\n|---|---|\n| `frontend/src/services/logger.ts` | shared logging entry point and backend-tracing orchestration |\n| `frontend/src/services/loggingConfig.ts` | fetches and caches server logging config |\n| `frontend/src/services/logBuffer.ts` | buffers trace events before flush |\n| `frontend/src/services/logTransport.ts` | sends trace batches to `/api/logs/mobile` |\n| `backend/app/api/logs.py` | serves frontend logging config and accepts uploaded trace batches |\n| `backend/app/services/log_manager.py` | writes trace batches to JSONL files and cleans up retained logs |\n| `frontend/src/pages/Login.tsx` and `frontend/src/pages/FileBrowser.tsx` | initialize tracing after authenticated app startup |\n\n## Runtime Flow\n\n1. the authenticated browser app calls `logger.initializeBackendTracing()`\n2. the logger loads config through `loggingConfig.getConfig()`\n3. console logging level is updated from backend config when enabled\n4. backend tracing is enabled only when the server config allows it\n5. each logger call writes to the console if its level passes the console threshold\n6. the same call asynchronously checks trace level and component filters before buffering a backend trace entry\n7. the buffer flushes by size or interval and posts the batch to `/api/logs/mobile`\n\nThe log call is the single source of truth. Contributors should not have to choose between console visibility and trace collection by using different APIs.\n\n## Configuration Model\n\nThe frontend pulls logging state from the backend rather than hard-coding it in the browser app.\n\n- `logging_enabled` and `logging_level` control console output\n- `tracing_enabled`, `tracing_level`, and `tracing_components` control backend trace collection\n- `frontend_tracing_username_regex` on the backend can disable tracing for users who do not match the configured pattern\n- `loggingConfig` caches the fetched config in `localStorage` for five minutes to avoid repeated requests\n\nThe logger also keeps different local defaults before server config is loaded.\n\n- development builds default to verbose console logging\n- production builds default to warnings and errors\n- test runs skip backend tracing setup entirely\n\nThe current backend contract is exposed through `GET /api/logs/config` and returns:\n\n- `logging_enabled`\n- `logging_level`\n- `tracing_enabled`\n- `tracing_level`\n- `tracing_components`\n\n`loggingConfig` then adds a client-side timestamp when caching the response locally.\n\n### Level and Component Filtering\n\nConsole logging and backend tracing are independent.\n\n- console output is gated only by `logging_enabled` plus the effective console level\n- backend tracing is gated by `tracing_enabled`, `tracing_level`, and optional component matching\n- an empty `tracing_components` list means all components are accepted\n- component matching is exact string matching, so inconsistent tag names reduce the usefulness of filtered tracing quickly\n\nLevel filtering is threshold-based.\n\n- `DEBUG` allows everything\n- `INFO` suppresses only `DEBUG`\n- `WARNING` allows `WARNING` and `ERROR`\n- `ERROR` allows only `ERROR`\n\n## Buffering and Transport\n\nBackend tracing is buffered on purpose.\n\n- `LogBuffer` groups trace entries in memory instead of posting every log call immediately\n- each batch carries a generated session ID plus device information such as user agent, screen size, and touch capability\n- the default flush behavior is size-based or time-based, whichever happens first\n- failed flushes keep the buffered entries for retry on the next flush attempt\n\nThe current implementation details are worth preserving:\n\n- `LogBuffer` generates one session ID for the browser runtime that enabled tracing\n- the batch payload includes `userAgent`, screen size, `devicePixelRatio`, platform, and touch capability\n- `LogTransport` uses `fetch` directly instead of the shared API service to avoid circular dependencies in the logging stack\n- trace uploads include the bearer token when one is available\n- if repeated flush failures push the in-memory buffer above twice the configured size, the oldest entries are dropped to cap memory growth\n\nThis design keeps routine logging cheap while still giving the backend enough session context to debug real field problems.\n\n### Backend Receipt and Storage\n\nThe backend logging API is simple and file-backed.\n\n- `POST /api/logs/mobile` accepts a trace batch for the authenticated user\n- `GET /api/logs/config` serves the frontend logging configuration\n- `GET /api/logs/list` lists available uploaded mobile-log files\n- `GET /api/logs/download/{filename}` downloads a stored log file\n\nUploaded trace batches are written under `data/mobile_logs/` as JSONL files.\n\n- the first line is metadata, including session ID, device info, server timestamp, and request metadata such as client IP or user agent\n- subsequent lines are individual log entries\n- retention cleanup is handled by `MobileLogManager.cleanup_old_logs()` using the configured retention window\n\nThis is why frontend logging changes can affect both browser behavior and support-facing backend artifacts.\n\n## Component Tags and Taxonomy\n\nComponent tags are optional for console output but important for backend tracing.\n\nRepresentative tags currently used in the frontend include:\n\n- `api`\n- `auth`\n- `backend-recovery`\n- `browser`\n- `browser-perf`\n- `companion`\n- `config`\n- `directory-search-provider`\n- `file-browser`\n- `viewer`\n- `websocket`\n\nThese tags are not just naming style. They are the filter vocabulary for targeted trace collection.\n\nContributors should:\n\n- reuse an existing tag when the log belongs to an established subsystem\n- add a new tag only when it introduces a real new filter boundary\n- keep names stable once they appear in backend config or support playbooks\n\nOne log call still drives both surfaces. The component tag only changes backend-tracing selection behavior.\n\n## Error Context and Safety Rules\n\n`logger.error()` enriches the provided context when an `Error` object is passed.\n\n- `error.message`\n- `error.stack`\n- `error.name`\n\nThat gives support traces more useful failure context without forcing every caller to serialize errors manually.\n\nContributors still need to be selective.\n\n- include actionable IDs, paths, counts, durations, or status values\n- avoid passwords, tokens, private payloads, or large opaque objects\n- avoid high-volume logs inside tight loops or animation-heavy code paths\n\n## Contributor Rules\n\n- use the shared logger instead of scattering long-lived `console.*` calls through components and hooks\n- pass a component tag when backend trace filtering matters to the workflow you are changing\n- do not assume a visible console message also means backend tracing is enabled for that session\n- keep structured context specific and actionable instead of dumping large objects or noisy state snapshots\n- do not move tracing initialization earlier than authenticated startup without checking token and request-path assumptions\n\nThe supported call shape is:\n\n- `logger.debug(message, context?, component?)`\n- `logger.info(message, context?, component?)`\n- `logger.warn(message, context?, component?)`\n- `logger.error(message, context?, component?, error?)`\n\nParameter order matters. If a component tag is needed, it is the third argument for non-error calls and still the third argument for `logger.error()` before the optional `Error` object.\n\nThe older dedicated trace-only helpers are gone. Shared logger calls are the canonical path.\n\n## Test and Runtime Nuances\n\nThe logger deliberately behaves differently in tests.\n\n- test detection suppresses console output\n- backend tracing initialization is skipped in test environments\n- `loggingConfig` falls back to a disabled state when config loading fails\n\nThis is intentional defensive behavior, not a missing feature. It keeps tests quieter and prevents trace setup from leaking across environments.\n\n## Common Failure Modes\n\n- adding raw console logs that never reach backend trace collection\n- expecting a server-side logging-config change to apply instantly while a cached config is still valid\n- using inconsistent component names that make trace filtering unreliable\n- adding high-volume debug logs that drown out the actionable events\n- treating trace transport failures as if they were equivalent to application failures\n\nOther common mistakes include:\n\n- assuming the mobile-log download endpoint is `/api/logs/{filename}` instead of the current `/api/logs/download/{filename}` route\n- documenting stale field names such as `enabled` or `log_level` instead of the current `logging_*` and `tracing_*` contract\n- swapping the logger parameter order and accidentally passing the component tag as context\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nAdd or update targeted frontend tests when the change affects config caching, filtering behavior, startup initialization, or log transport.\n\nThe current targeted suites already cover the most important contracts:\n\n- `frontend/src/services/__tests__/loggingConfig.test.ts` for config shape, threshold logic, and disabled-state behavior\n- `frontend/src/services/__tests__/mobileLoggingApi.test.ts` for the mobile-log API payload and response contract\n\nIf the change touches backend receipt, storage, or filename behavior, pair the frontend checks with the relevant backend tests around `backend/app/api/logs.py` and `backend/tests/test_logging_config.py`.\n", "2.0": "+++\ntitle = \"Frontend Logging and Tracing\"\n+++\n\nThe browser app has one shared logging API, but it can feed two different diagnostic surfaces.\n\n- browser-console output for local development and interactive debugging\n- backend trace collection for support workflows and cases where direct console access is unavailable\n\nThat split matters because a small frontend logging change can improve one surface while degrading the other.\n\n## Main Implementation Files\n\n| File | Role |\n|---|---|\n| `frontend/src/services/logger.ts` | shared logging entry point and backend-tracing orchestration |\n| `frontend/src/services/loggingConfig.ts` | fetches and caches server logging config |\n| `frontend/src/services/logBuffer.ts` | buffers trace events before flush |\n| `frontend/src/services/logTransport.ts` | sends trace batches to `/api/logs/mobile` |\n| `backend/app/api/logs.py` | serves frontend logging config and accepts uploaded trace batches |\n| `backend/app/services/log_manager.py` | writes trace batches to JSONL files and cleans up retained logs |\n| `frontend/src/pages/Login.tsx` and `frontend/src/pages/FileBrowser.tsx` | initialize tracing after authenticated app startup |\n\n## Runtime Flow\n\n1. the authenticated browser app calls `logger.initializeBackendTracing()`\n2. the logger loads config through `loggingConfig.getConfig()`\n3. console logging level is updated from backend config when enabled\n4. backend tracing is enabled only when the server config allows it\n5. each logger call writes to the console if its level passes the console threshold\n6. the same call asynchronously checks trace level and component filters before buffering a backend trace entry\n7. the buffer flushes by size or interval and posts the batch to `/api/logs/mobile`\n\nThe log call is the single source of truth. Contributors should not have to choose between console visibility and trace collection by using different APIs.\n\n## Configuration Model\n\nThe frontend pulls logging state from the backend rather than hard-coding it in the browser app.\n\n- `logging_enabled` and `logging_level` control console output\n- `tracing_enabled`, `tracing_level`, and `tracing_components` control backend trace collection\n- `frontend_tracing_username_regex` on the backend can disable tracing for users who do not match the configured pattern\n- `loggingConfig` caches the fetched config in `localStorage` for five minutes to avoid repeated requests\n\nThe logger also keeps different local defaults before server config is loaded.\n\n- development builds default to verbose console logging\n- production builds default to warnings and errors\n- test runs skip backend tracing setup entirely\n\nThe current backend contract is exposed through `GET /api/logs/config` and returns:\n\n- `logging_enabled`\n- `logging_level`\n- `tracing_enabled`\n- `tracing_level`\n- `tracing_components`\n\n`loggingConfig` then adds a client-side timestamp when caching the response locally.\n\n### Level and Component Filtering\n\nConsole logging and backend tracing are independent.\n\n- console output is gated only by `logging_enabled` plus the effective console level\n- backend tracing is gated by `tracing_enabled`, `tracing_level`, and optional component matching\n- an empty `tracing_components` list means all components are accepted\n- component matching is exact string matching, so inconsistent tag names reduce the usefulness of filtered tracing quickly\n\nLevel filtering is threshold-based.\n\n- `DEBUG` allows everything\n- `INFO` suppresses only `DEBUG`\n- `WARNING` allows `WARNING` and `ERROR`\n- `ERROR` allows only `ERROR`\n\n## Buffering and Transport\n\nBackend tracing is buffered on purpose.\n\n- `LogBuffer` groups trace entries in memory instead of posting every log call immediately\n- each batch carries a generated session ID plus device information such as user agent, screen size, and touch capability\n- the default flush behavior is size-based or time-based, whichever happens first\n- failed flushes keep the buffered entries for retry on the next flush attempt\n\nThe current implementation details are worth preserving:\n\n- `LogBuffer` generates one session ID for the browser runtime that enabled tracing\n- the batch payload includes `userAgent`, screen size, `devicePixelRatio`, platform, and touch capability\n- `LogTransport` uses `fetch` directly instead of the shared API service to avoid circular dependencies in the logging stack\n- trace uploads include the bearer token when one is available\n- if repeated flush failures push the in-memory buffer above twice the configured size, the oldest entries are dropped to cap memory growth\n\nThis design keeps routine logging cheap while still giving the backend enough session context to debug real field problems.\n\n### Backend Receipt and Storage\n\nThe backend logging API is simple and file-backed.\n\n- `POST /api/logs/mobile` accepts a trace batch for the authenticated user\n- `GET /api/logs/config` serves the frontend logging configuration\n- `GET /api/logs/list` lists available uploaded mobile-log files\n- `GET /api/logs/download/{filename}` downloads a stored log file\n\nUploaded trace batches are written under `data/mobile_logs/` as JSONL files.\n\n- the first line is metadata, including session ID, device info, server timestamp, and request metadata such as client IP or user agent\n- subsequent lines are individual log entries\n- retention cleanup is handled by `MobileLogManager.cleanup_old_logs()` using the configured retention window\n\nThis is why frontend logging changes can affect both browser behavior and support-facing backend artifacts.\n\n## Component Tags and Taxonomy\n\nComponent tags are optional for console output but important for backend tracing.\n\nRepresentative tags currently used in the frontend include:\n\n- `api`\n- `auth`\n- `backend-recovery`\n- `browser`\n- `browser-perf`\n- `companion`\n- `config`\n- `directory-search-provider`\n- `file-browser`\n- `viewer`\n- `websocket`\n\nThese tags are not just naming style. They are the filter vocabulary for targeted trace collection.\n\nContributors should:\n\n- reuse an existing tag when the log belongs to an established subsystem\n- add a new tag only when it introduces a real new filter boundary\n- keep names stable once they appear in backend config or support playbooks\n\nOne log call still drives both surfaces. The component tag only changes backend-tracing selection behavior.\n\n## Error Context and Safety Rules\n\n`logger.error()` enriches the provided context when an `Error` object is passed.\n\n- `error.message`\n- `error.stack`\n- `error.name`\n\nThat gives support traces more useful failure context without forcing every caller to serialize errors manually.\n\nContributors still need to be selective.\n\n- include actionable IDs, paths, counts, durations, or status values\n- avoid passwords, tokens, private payloads, or large opaque objects\n- avoid high-volume logs inside tight loops or animation-heavy code paths\n\n## Contributor Rules\n\n- use the shared logger instead of scattering long-lived `console.*` calls through components and hooks\n- pass a component tag when backend trace filtering matters to the workflow you are changing\n- do not assume a visible console message also means backend tracing is enabled for that session\n- keep structured context specific and actionable instead of dumping large objects or noisy state snapshots\n- do not move tracing initialization earlier than authenticated startup without checking token and request-path assumptions\n\nThe supported call shape is:\n\n- `logger.debug(message, context?, component?)`\n- `logger.info(message, context?, component?)`\n- `logger.warn(message, context?, component?)`\n- `logger.error(message, context?, component?, error?)`\n\nParameter order matters. If a component tag is needed, it is the third argument for non-error calls and still the third argument for `logger.error()` before the optional `Error` object.\n\nThe older dedicated trace-only helpers are gone. Shared logger calls are the canonical path.\n\n## Test and Runtime Nuances\n\nThe logger deliberately behaves differently in tests.\n\n- test detection suppresses console output\n- backend tracing initialization is skipped in test environments\n- `loggingConfig` falls back to a disabled state when config loading fails\n\nThis is intentional defensive behavior, not a missing feature. It keeps tests quieter and prevents trace setup from leaking across environments.\n\n## Common Failure Modes\n\n- adding raw console logs that never reach backend trace collection\n- expecting a server-side logging-config change to apply instantly while a cached config is still valid\n- using inconsistent component names that make trace filtering unreliable\n- adding high-volume debug logs that drown out the actionable events\n- treating trace transport failures as if they were equivalent to application failures\n\nOther common mistakes include:\n\n- assuming the mobile-log download endpoint is `/api/logs/{filename}` instead of the current `/api/logs/download/{filename}` route\n- documenting stale field names such as `enabled` or `log_level` instead of the current `logging_*` and `tracing_*` contract\n- swapping the logger parameter order and accidentally passing the component tag as context\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nAdd or update targeted frontend tests when the change affects config caching, filtering behavior, startup initialization, or log transport.\n\nThe current targeted suites already cover the most important contracts:\n\n- `frontend/src/services/__tests__/loggingConfig.test.ts` for config shape, threshold logic, and disabled-state behavior\n- `frontend/src/services/__tests__/mobileLoggingApi.test.ts` for the mobile-log API payload and response contract\n\nIf the change touches backend receipt, storage, or filename behavior, pair the frontend checks with the relevant backend tests around `backend/app/api/logs.py` and `backend/tests/test_logging_config.py`.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:developer-guide/testing-and-quality-gates", "parent_id": "book:developer-guide", "depth": 1, "kind": "section", "label": "testing-and-quality-gates", "title": "Testing and Quality Gates", "path": "developer-guide/testing-and-quality-gates", "has_children": true, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Testing and Quality Gates\"\n+++\n\nThis section helps contributors choose the right validation depth instead of running either too little or everything all the time.\n\nStart with:\n\n- [Test Strategy Overview](./test-strategy-overview/)\n\nRelated supporting pages:\n\n- [CI Workflows and Repository Automation](./ci-workflows-and-repository-automation/)\n- [Logging and Localization](../cross-cutting-systems/logging-and-localization/)\n- [Dependency Update Workflow](../release-and-versioning/dependency-update-workflow/)\n\nUse this section before you finish a change that affects API behavior, UI behavior, or companion workflows.\n", "0.8": "+++\ntitle = \"Testing and Quality Gates\"\n+++\n\nThis section helps contributors choose the right validation depth instead of running either too little or everything all the time.\n\nStart with:\n\n- [Test Strategy Overview](./test-strategy-overview/)\n\nRelated supporting pages:\n\n- [CI Workflows and Repository Automation](./ci-workflows-and-repository-automation/)\n- [Logging and Localization](../cross-cutting-systems/logging-and-localization/)\n- [Dependency Update Workflow](../release-and-versioning/dependency-update-workflow/)\n\nUse this section before you finish a change that affects API behavior, UI behavior, or companion workflows.\n", "0.9": "+++\ntitle = \"Testing and Quality Gates\"\n+++\n\nThis section helps contributors choose the right validation depth instead of running either too little or everything all the time.\n\nStart with:\n\n- [Test Strategy Overview](./test-strategy-overview/)\n\nRelated supporting pages:\n\n- [CI Workflows and Repository Automation](./ci-workflows-and-repository-automation/)\n- [Logging and Localization](../cross-cutting-systems/logging-and-localization/)\n- [Dependency Update Workflow](../release-and-versioning/dependency-update-workflow/)\n\nUse this section before you finish a change that affects API behavior, UI behavior, or companion workflows.\n", "1.0": "+++\ntitle = \"Testing and Quality Gates\"\n+++\n\nThis section helps contributors choose the right validation depth instead of running either too little or everything all the time.\n\nStart with:\n\n- [Test Strategy Overview](./test-strategy-overview/)\n\nRelated supporting pages:\n\n- [CI Workflows and Repository Automation](./ci-workflows-and-repository-automation/)\n- [Logging and Localization](../cross-cutting-systems/logging-and-localization/)\n- [Dependency Update Workflow](../release-and-versioning/dependency-update-workflow/)\n\nUse this section before you finish a change that affects API behavior, UI behavior, or companion workflows.\n", "2.0": "+++\ntitle = \"Testing and Quality Gates\"\n+++\n\nThis section helps contributors choose the right validation depth instead of running either too little or everything all the time.\n\nStart with:\n\n- [Test Strategy Overview](./test-strategy-overview/)\n\nRelated supporting pages:\n\n- [CI Workflows and Repository Automation](./ci-workflows-and-repository-automation/)\n- [Logging and Localization](../cross-cutting-systems/logging-and-localization/)\n- [Dependency Update Workflow](../release-and-versioning/dependency-update-workflow/)\n\nUse this section before you finish a change that affects API behavior, UI behavior, or companion workflows.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/testing-and-quality-gates/test-strategy-overview", "parent_id": "section:developer-guide/testing-and-quality-gates", "depth": 2, "kind": "page", "label": "test-strategy-overview", "title": "Test Strategy Overview", "path": "developer-guide/testing-and-quality-gates/test-strategy-overview", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "branched", "source_version": "0.7", "diff_added": 29, "diff_removed": 4}, "0.9": {"state": "inherited", "source_version": "0.8"}, "1.0": {"state": "inherited", "source_version": "0.8"}, "2.0": {"state": "inherited", "source_version": "0.8"}}, "content_versions": {"0.7": "+++\ntitle = \"Test Strategy Overview\"\n+++\n\nSambee has multiple subsystems, so the right validation strategy depends on which contract you changed.\n\n## Start with the Smallest Relevant Set\n\nDo not default to either no validation or every possible check.\n\n- backend-only change with no shared contract impact: run backend tests and type checking\n- frontend-only change: run frontend tests, type check, and lint\n- companion-only change: run companion checks and Rust tests\n- shared workflow change: run every affected subsystem's checks\n\n## Recommended Checks by Change Area\n\n| Change area | Baseline checks |\n|---|---|\n| Backend behavior | `cd backend \u0026\u0026 pytest -m 'not performance' -v`, `cd backend \u0026\u0026 pytest -m performance -v`, `cd backend \u0026\u0026 mypy app` |\n| Frontend behavior | `cd frontend \u0026\u0026 npm test`, `cd frontend \u0026\u0026 npx tsc --noEmit`, `cd frontend \u0026\u0026 npm run lint` |\n| Companion behavior | `cd companion \u0026\u0026 npx tsc --noEmit`, `cd companion \u0026\u0026 npm run lint`, `cd companion/src-tauri \u0026\u0026 cargo test` |\n\nFor fast local iteration, `./scripts/test` runs the main backend, frontend, companion, and archive-topology suites together. It stops at the first failed check so you can fix that subsystem before spending time on later suites. The order is backend type checking and tests, frontend type checking, linting, and tests, companion checks and tests, then archive-specific topology verification. Its backend pass mirrors CI by running non-performance tests in parallel and `@performance` tests in a separate serial pass. Use `COVERAGE=1 ./scripts/test` when you want the broader CI-style coverage pass.\n\n## Cross-Boundary Changes Need Cross-Boundary Checks\n\nRun broader coverage when you change a shared contract, for example:\n\n- backend response shape that the frontend consumes\n- companion behavior that changes browser-facing pairing or editing flows\n- localization or logging behavior that spans more than one app\n\n## Contract-Sensitive Areas\n\n### API Contracts\n\nFrontend and backend compatibility depends on stable response shapes and matching types. Sambee currently protects that boundary primarily with frontend service contract tests plus backend endpoint tests for the same response families.\n\n#### Current Pattern in This Repository\n\nThe current API-contract pattern is broader than a single logging endpoint.\n\n- frontend contract suites live under `frontend/src/services/__tests__/`\n- those tests typically mock the HTTP client, call the real frontend service methods, and assert endpoint paths, request parameters, response shapes, field types, enum values, blob headers, and error handling\n- representative suites include `authApi.test.ts`, `connectionApi.test.ts`, `browseApi.test.ts`, `viewerApi.test.ts`, `mobileLoggingApi.test.ts`, and `loggingConfig.test.ts`\n- backend tests validate the corresponding FastAPI surface from the server side, for example `backend/tests/test_logging_config.py`\n\nThat means an API-shape change is not just a backend refactor. It is a cross-boundary behavior change that should update backend models, backend tests, frontend types, frontend service logic, and the contract tests that bind them together.\n\n#### What the Frontend Contract Tests Actually Check\n\nThe frontend service contract tests are not only smoke tests.\n\n- authentication and admin flows check required fields and value shapes for token, user, and connection payloads\n- browse tests check nested directory listings, `FileInfo` structure, enum values, optional metadata, and path handling\n- viewer tests check binary-response behavior such as `Blob` creation, `Content-Type` handling, viewport parameters, and download semantics\n- logging-config tests check the exact backend response shape and then verify behavior derived from it, such as level-threshold evaluation and disabled-state behavior\n\nThe useful rule is: test the response contract first, then test the frontend behavior that depends on that contract.\n\n#### Logging Configuration as a Concrete Example\n\nThe logging configuration tests are a good example because they show both sides of the boundary.\n\n- backend tests assert the `/api/logs/config` response contains `logging_enabled`, `logging_level`, `tracing_enabled`, `tracing_level`, and `tracing_components`\n- frontend tests in `loggingConfig.test.ts` consume that exact shape and then verify threshold and filtering behavior that would break if the backend fields drifted\n\nThis matters because an older or copied example that still expects fields like `enabled` or `log_level` would describe the wrong contract for the current codebase.\n\n#### When to Add or Update Contract Tests\n\nAdd or expand API contract coverage when:\n\n- you add a new frontend-consumed endpoint\n- you rename, remove, or add a response field\n- you change enum values or allowed string values\n- you change binary-response behavior such as MIME handling, blob creation, or download headers\n- you add frontend logic that derives behavior from backend configuration values rather than just displaying them\n\nFor those changes, update both ends together:\n\n1. backend response model or endpoint behavior\n2. backend tests for the server response\n3. frontend types and service methods\n4. frontend contract tests for the consumed shape\n5. frontend behavior tests for the logic built on top of that shape\n\n#### Practical Contract-Testing Checklist\n\nFor a new or changed endpoint, usually verify:\n\n- required fields exist\n- field types match the frontend types\n- optional fields behave correctly when present or absent\n- known enum or string-literal values are accepted intentionally\n- request parameters and path construction still match the backend route contract\n- error responses degrade in a controlled way\n- derived frontend behavior still works once the typed response is consumed\n\n#### OpenAPI as a Future Option\n\nSambee exposes and tests the backend OpenAPI schema, including `/openapi.json`, but TypeScript type generation from that schema is not part of the checked-in frontend workflow today.\n\nIf API surface area grows enough to justify generation, OpenAPI-driven types are a reasonable future option because the backend is already able to publish the schema. Treat that as an explicit workflow addition, not as something the repository already guarantees.\n\nPossible future additions include:\n\n- generating TypeScript types from the FastAPI schema in a reviewed frontend workflow\n- adding CI checks that detect generated-type drift\n- widening contract-style coverage for endpoints that still rely mostly on broader unit tests or integration tests\n\n### Localization\n\nLocalization is treated as typed product behavior, not just string replacement. If you touch translation wiring or browser-to-companion localization sync, validate the relevant frontend and companion checks.\n\n### Logging and Diagnostics\n\nLogging changes can affect both local debugging and backend trace collection. Validate the app surfaces that consume those logging contracts.\n\n## Practical Selection Rule\n\nUse this decision order:\n\n1. Identify which subsystem changed directly.\n2. Identify which other subsystem consumes the changed contract.\n3. Run baseline checks for the changed subsystem.\n4. Add checks for every subsystem whose contract might now be wrong.\n\n## When to Go beyond the Baseline\n\nRun deeper or wider validation when:\n\n- the change affects a high-risk workflow such as file editing, locking, upload, or pairing\n- you changed dependencies or version metadata\n- you changed typed API contracts\n- the change fixes a regression that previously escaped narrower coverage\n\nThe goal is not maximum command count. The goal is to prove the changed behavior still matches Sambee's cross-app contracts.\n\n## Backend Test Structure and Fixtures\n\nBackend tests live under `backend/tests/`.\n\nCommon files include:\n\n- `conftest.py`: shared fixtures and test wiring\n- `test_auth.py`: authentication and authorization behavior\n- `test_connections.py`: SMB connection management\n- `test_browser.py`: file-browsing behavior with mocked SMB backends\n\nCommon fixtures include:\n\n- `client`\n- `session`\n- `admin_user`, `regular_user`\n- `admin_token`, `user_token`\n- `auth_headers_admin`, `auth_headers_user`\n- `test_connection`\n- `multiple_connections`\n- `mock_smb_backend`\n\nUse the shared fixtures instead of rebuilding the same setup in each test file.\n\n## Performance Notes\n\n- backend tests use `pytest-xdist` for parallel execution in the normal workflow, but `@performance` tests run separately without xdist so timing assertions stay stable\n- coverage is intentionally optional during routine local work because it is slower\n- use deeper coverage when the change touches risky backend behavior or when CI-equivalent evidence matters\n\n## Go Deeper\n\n- [Image Conversion Test Assets](../image-conversion-test-assets/): generated fixtures, real colorspace assertions, and the backend integration suite for image-conversion regressions\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared cross-boundary rules that often expand the validation surface\n- [How to Plan and Review a Change](../../contribution-workflows/how-to-plan-and-review-a-change/): decide scope before choosing checks\n- [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/): use this when version metadata or reviewed dependency inputs are part of the change\n", "0.8": "+++\ntitle = \"Test Strategy Overview\"\n+++\n\nSambee has multiple subsystems, so the right validation strategy depends on which contract you changed.\n\n## Start with the Smallest Relevant Set\n\nDo not default to either no validation or every possible check.\n\n- backend-only change with no shared contract impact: run backend tests and type checking\n- frontend-only change: run frontend tests, type check, and lint\n- companion-only change: run companion checks, the Windows GNU cross-check, and Rust tests\n- shared workflow change: run every affected subsystem's checks\n\n## Recommended Checks by Change Area\n\n| Change area | Baseline checks |\n|---|---|\n| Backend behavior | `cd backend \u0026\u0026 pytest -m 'not performance' -v`, `cd backend \u0026\u0026 pytest -m performance -v`, `cd backend \u0026\u0026 mypy app` |\n| Frontend behavior | `cd frontend \u0026\u0026 npm test`, `cd frontend \u0026\u0026 npx tsc --noEmit`, `cd frontend \u0026\u0026 npm run lint` |\n| Companion behavior | `cd companion \u0026\u0026 npx tsc --noEmit`, `cd companion \u0026\u0026 npm run lint`, `cd companion \u0026\u0026 npm run check:rust:windows`, `cd companion/src-tauri \u0026\u0026 cargo test` |\n\nFor fast local iteration, `./scripts/test` runs the main backend, frontend, and companion suites together. Its backend pass mirrors CI by running non-performance tests in parallel and `@performance` tests in a separate serial pass. The local companion pass now also includes the Windows GNU target compatibility check when the toolchain is installed. Use `COVERAGE=1 ./scripts/test` when you want the broader CI-style coverage pass.\n\n### Frontend Browser-Test Layers\n\nKeep frontend browser coverage explicit instead of folding it into the default Vitest command.\n\n- `cd frontend \u0026\u0026 npm test` runs the default Vitest suite.\n- `cd frontend \u0026\u0026 npm run test:e2e` runs the default Playwright Chromium suite.\n- `cd frontend \u0026\u0026 npm run test:e2e:all` runs all configured Playwright browser projects.\n\nInstall Playwright browsers locally with `cd frontend \u0026\u0026 npm run test:e2e:install` when a fresh environment does not have the browser binaries yet.\n\n## Cross-Boundary Changes Need Cross-Boundary Checks\n\nRun broader coverage when you change a shared contract, for example:\n\n- backend response shape that the frontend consumes\n- companion behavior that changes browser-facing pairing or editing flows\n- localization or logging behavior that spans more than one app\n\n## Contract-Sensitive Areas\n\n### API Contracts\n\nFrontend and backend compatibility depends on stable response shapes and matching types. Sambee currently protects that boundary primarily with frontend service contract tests plus backend endpoint tests for the same response families.\n\n#### Current Pattern in This Repository\n\nThe current API-contract pattern is broader than a single logging endpoint.\n\n- frontend contract suites live under `frontend/src/services/__tests__/`\n- those tests typically mock the HTTP client, call the real frontend service methods, and assert endpoint paths, request parameters, response shapes, field types, enum values, blob headers, and error handling\n- representative suites include `authApi.test.ts`, `connectionApi.test.ts`, `browseApi.test.ts`, `viewerApi.test.ts`, `mobileLoggingApi.test.ts`, and `loggingConfig.test.ts`\n- backend tests validate the corresponding FastAPI surface from the server side, for example `backend/tests/test_logging_config.py`\n\nThat means an API-shape change is not just a backend refactor. It is a cross-boundary behavior change that should update backend models, backend tests, frontend types, frontend service logic, and the contract tests that bind them together.\n\n#### What the Frontend Contract Tests Actually Check\n\nThe frontend service contract tests are not only smoke tests.\n\n- authentication and admin flows check required fields and value shapes for token, user, and connection payloads\n- browse tests check nested directory listings, `FileInfo` structure, enum values, optional metadata, and path handling\n- viewer tests check binary-response behavior such as `Blob` creation, `Content-Type` handling, viewport parameters, and download semantics\n- logging-config tests check the exact backend response shape and then verify behavior derived from it, such as level-threshold evaluation and disabled-state behavior\n\nThe useful rule is: test the response contract first, then test the frontend behavior that depends on that contract.\n\n#### Logging Configuration as a Concrete Example\n\nThe logging configuration tests are a good example because they show both sides of the boundary.\n\n- backend tests assert the `/api/logs/config` response contains `logging_enabled`, `logging_level`, `tracing_enabled`, `tracing_level`, and `tracing_components`\n- frontend tests in `loggingConfig.test.ts` consume that exact shape and then verify threshold and filtering behavior that would break if the backend fields drifted\n\nThis matters because an older or copied example that still expects fields like `enabled` or `log_level` would describe the wrong contract for the current codebase.\n\n#### When to Add or Update Contract Tests\n\nAdd or expand API contract coverage when:\n\n- you add a new frontend-consumed endpoint\n- you rename, remove, or add a response field\n- you change enum values or allowed string values\n- you change binary-response behavior such as MIME handling, blob creation, or download headers\n- you add frontend logic that derives behavior from backend configuration values rather than just displaying them\n\nFor those changes, update both ends together:\n\n1. backend response model or endpoint behavior\n2. backend tests for the server response\n3. frontend types and service methods\n4. frontend contract tests for the consumed shape\n5. frontend behavior tests for the logic built on top of that shape\n\n#### Practical Contract-Testing Checklist\n\nFor a new or changed endpoint, usually verify:\n\n- required fields exist\n- field types match the frontend types\n- optional fields behave correctly when present or absent\n- known enum or string-literal values are accepted intentionally\n- request parameters and path construction still match the backend route contract\n- error responses degrade in a controlled way\n- derived frontend behavior still works once the typed response is consumed\n\n#### OpenAPI as a Future Option\n\nSambee exposes and tests the backend OpenAPI schema, including `/openapi.json`, but TypeScript type generation from that schema is not part of the checked-in frontend workflow today.\n\nIf API surface area grows enough to justify generation, OpenAPI-driven types are a reasonable future option because the backend is already able to publish the schema. Treat that as an explicit workflow addition, not as something the repository already guarantees.\n\nPossible future additions include:\n\n- generating TypeScript types from the FastAPI schema in a reviewed frontend workflow\n- adding CI checks that detect generated-type drift\n- widening contract-style coverage for endpoints that still rely mostly on broader unit tests or integration tests\n\n### Localization\n\nLocalization is treated as typed product behavior, not just string replacement. If you touch translation wiring or browser-to-companion localization sync, validate the relevant frontend and companion checks.\n\n### Companion Cross-Target Safety\n\nCompanion contributors now have a local Linux-hosted Windows-target safety check.\n\n- `npm run check:rust:windows` runs `cargo check` for `x86_64-pc-windows-gnu`.\n- In the devcontainer, the required Rust target and MinGW toolchain are preinstalled.\n- This check is for compatibility validation, not for producing release-ready Windows binaries.\n\nKeep the distinction clear:\n\n- local cross-check: prove the Windows target still compiles far enough for contract and dependency safety\n- release build: create the signed Windows installer and updater artifacts in CI on Windows runners\n\n### Logging and Diagnostics\n\nLogging changes can affect both local debugging and backend trace collection. Validate the app surfaces that consume those logging contracts.\n\n## Practical Selection Rule\n\nUse this decision order:\n\n1. Identify which subsystem changed directly.\n2. Identify which other subsystem consumes the changed contract.\n3. Run baseline checks for the changed subsystem.\n4. Add checks for every subsystem whose contract might now be wrong.\n\n## When to Go beyond the Baseline\n\nRun deeper or wider validation when:\n\n- the change affects a high-risk workflow such as file editing, locking, upload, or pairing\n- you changed dependencies or version metadata\n- you changed typed API contracts\n- you changed browser-sensitive editor behavior such as focus handoff, contenteditable selection, keyboard navigation, or decorator-backed editing flows\n- you changed companion native dependencies, Windows-specific crates, or Tauri integration\n- the change fixes a regression that previously escaped narrower coverage\n\nThe goal is not maximum command count. The goal is to prove the changed behavior still matches Sambee's cross-app contracts.\n\n## Backend Test Structure and Fixtures\n\nBackend tests live under `backend/tests/`.\n\nCommon files include:\n\n- `conftest.py`: shared fixtures and test wiring\n- `test_auth.py`: authentication and authorization behavior\n- `test_connections.py`: SMB connection management\n- `test_browser.py`: file-browsing behavior with mocked SMB backends\n\nCommon fixtures include:\n\n- `client`\n- `session`\n- `admin_user`, `regular_user`\n- `admin_token`, `user_token`\n- `auth_headers_admin`, `auth_headers_user`\n- `test_connection`\n- `multiple_connections`\n- `mock_smb_backend`\n\nUse the shared fixtures instead of rebuilding the same setup in each test file.\n\n## Performance Notes\n\n- backend tests use `pytest-xdist` for parallel execution in the normal workflow, but `@performance` tests run separately without xdist so timing assertions stay stable\n- coverage is intentionally optional during routine local work because it is slower\n- use deeper coverage when the change touches risky backend behavior or when CI-equivalent evidence matters\n\n## Go Deeper\n\n- [Image Conversion Test Assets](../image-conversion-test-assets/): generated fixtures, real colorspace assertions, and the backend integration suite for image-conversion regressions\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared cross-boundary rules that often expand the validation surface\n- [How to Plan and Review a Change](../../contribution-workflows/how-to-plan-and-review-a-change/): decide scope before choosing checks\n- [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/): use this when version metadata or reviewed dependency inputs are part of the change\n", "0.9": "+++\ntitle = \"Test Strategy Overview\"\n+++\n\nSambee has multiple subsystems, so the right validation strategy depends on which contract you changed.\n\n## Start with the Smallest Relevant Set\n\nDo not default to either no validation or every possible check.\n\n- backend-only change with no shared contract impact: run backend tests and type checking\n- frontend-only change: run frontend tests, type check, and lint\n- companion-only change: run companion checks, the Windows GNU cross-check, and Rust tests\n- shared workflow change: run every affected subsystem's checks\n\n## Recommended Checks by Change Area\n\n| Change area | Baseline checks |\n|---|---|\n| Backend behavior | `cd backend \u0026\u0026 pytest -m 'not performance' -v`, `cd backend \u0026\u0026 pytest -m performance -v`, `cd backend \u0026\u0026 mypy app` |\n| Frontend behavior | `cd frontend \u0026\u0026 npm test`, `cd frontend \u0026\u0026 npx tsc --noEmit`, `cd frontend \u0026\u0026 npm run lint` |\n| Companion behavior | `cd companion \u0026\u0026 npx tsc --noEmit`, `cd companion \u0026\u0026 npm run lint`, `cd companion \u0026\u0026 npm run check:rust:windows`, `cd companion/src-tauri \u0026\u0026 cargo test` |\n\nFor fast local iteration, `./scripts/test` runs the main backend, frontend, and companion suites together. Its backend pass mirrors CI by running non-performance tests in parallel and `@performance` tests in a separate serial pass. The local companion pass now also includes the Windows GNU target compatibility check when the toolchain is installed. Use `COVERAGE=1 ./scripts/test` when you want the broader CI-style coverage pass.\n\n### Frontend Browser-Test Layers\n\nKeep frontend browser coverage explicit instead of folding it into the default Vitest command.\n\n- `cd frontend \u0026\u0026 npm test` runs the default Vitest suite.\n- `cd frontend \u0026\u0026 npm run test:e2e` runs the default Playwright Chromium suite.\n- `cd frontend \u0026\u0026 npm run test:e2e:all` runs all configured Playwright browser projects.\n\nInstall Playwright browsers locally with `cd frontend \u0026\u0026 npm run test:e2e:install` when a fresh environment does not have the browser binaries yet.\n\n## Cross-Boundary Changes Need Cross-Boundary Checks\n\nRun broader coverage when you change a shared contract, for example:\n\n- backend response shape that the frontend consumes\n- companion behavior that changes browser-facing pairing or editing flows\n- localization or logging behavior that spans more than one app\n\n## Contract-Sensitive Areas\n\n### API Contracts\n\nFrontend and backend compatibility depends on stable response shapes and matching types. Sambee currently protects that boundary primarily with frontend service contract tests plus backend endpoint tests for the same response families.\n\n#### Current Pattern in This Repository\n\nThe current API-contract pattern is broader than a single logging endpoint.\n\n- frontend contract suites live under `frontend/src/services/__tests__/`\n- those tests typically mock the HTTP client, call the real frontend service methods, and assert endpoint paths, request parameters, response shapes, field types, enum values, blob headers, and error handling\n- representative suites include `authApi.test.ts`, `connectionApi.test.ts`, `browseApi.test.ts`, `viewerApi.test.ts`, `mobileLoggingApi.test.ts`, and `loggingConfig.test.ts`\n- backend tests validate the corresponding FastAPI surface from the server side, for example `backend/tests/test_logging_config.py`\n\nThat means an API-shape change is not just a backend refactor. It is a cross-boundary behavior change that should update backend models, backend tests, frontend types, frontend service logic, and the contract tests that bind them together.\n\n#### What the Frontend Contract Tests Actually Check\n\nThe frontend service contract tests are not only smoke tests.\n\n- authentication and admin flows check required fields and value shapes for token, user, and connection payloads\n- browse tests check nested directory listings, `FileInfo` structure, enum values, optional metadata, and path handling\n- viewer tests check binary-response behavior such as `Blob` creation, `Content-Type` handling, viewport parameters, and download semantics\n- logging-config tests check the exact backend response shape and then verify behavior derived from it, such as level-threshold evaluation and disabled-state behavior\n\nThe useful rule is: test the response contract first, then test the frontend behavior that depends on that contract.\n\n#### Logging Configuration as a Concrete Example\n\nThe logging configuration tests are a good example because they show both sides of the boundary.\n\n- backend tests assert the `/api/logs/config` response contains `logging_enabled`, `logging_level`, `tracing_enabled`, `tracing_level`, and `tracing_components`\n- frontend tests in `loggingConfig.test.ts` consume that exact shape and then verify threshold and filtering behavior that would break if the backend fields drifted\n\nThis matters because an older or copied example that still expects fields like `enabled` or `log_level` would describe the wrong contract for the current codebase.\n\n#### When to Add or Update Contract Tests\n\nAdd or expand API contract coverage when:\n\n- you add a new frontend-consumed endpoint\n- you rename, remove, or add a response field\n- you change enum values or allowed string values\n- you change binary-response behavior such as MIME handling, blob creation, or download headers\n- you add frontend logic that derives behavior from backend configuration values rather than just displaying them\n\nFor those changes, update both ends together:\n\n1. backend response model or endpoint behavior\n2. backend tests for the server response\n3. frontend types and service methods\n4. frontend contract tests for the consumed shape\n5. frontend behavior tests for the logic built on top of that shape\n\n#### Practical Contract-Testing Checklist\n\nFor a new or changed endpoint, usually verify:\n\n- required fields exist\n- field types match the frontend types\n- optional fields behave correctly when present or absent\n- known enum or string-literal values are accepted intentionally\n- request parameters and path construction still match the backend route contract\n- error responses degrade in a controlled way\n- derived frontend behavior still works once the typed response is consumed\n\n#### OpenAPI as a Future Option\n\nSambee exposes and tests the backend OpenAPI schema, including `/openapi.json`, but TypeScript type generation from that schema is not part of the checked-in frontend workflow today.\n\nIf API surface area grows enough to justify generation, OpenAPI-driven types are a reasonable future option because the backend is already able to publish the schema. Treat that as an explicit workflow addition, not as something the repository already guarantees.\n\nPossible future additions include:\n\n- generating TypeScript types from the FastAPI schema in a reviewed frontend workflow\n- adding CI checks that detect generated-type drift\n- widening contract-style coverage for endpoints that still rely mostly on broader unit tests or integration tests\n\n### Localization\n\nLocalization is treated as typed product behavior, not just string replacement. If you touch translation wiring or browser-to-companion localization sync, validate the relevant frontend and companion checks.\n\n### Companion Cross-Target Safety\n\nCompanion contributors now have a local Linux-hosted Windows-target safety check.\n\n- `npm run check:rust:windows` runs `cargo check` for `x86_64-pc-windows-gnu`.\n- In the devcontainer, the required Rust target and MinGW toolchain are preinstalled.\n- This check is for compatibility validation, not for producing release-ready Windows binaries.\n\nKeep the distinction clear:\n\n- local cross-check: prove the Windows target still compiles far enough for contract and dependency safety\n- release build: create the signed Windows installer and updater artifacts in CI on Windows runners\n\n### Logging and Diagnostics\n\nLogging changes can affect both local debugging and backend trace collection. Validate the app surfaces that consume those logging contracts.\n\n## Practical Selection Rule\n\nUse this decision order:\n\n1. Identify which subsystem changed directly.\n2. Identify which other subsystem consumes the changed contract.\n3. Run baseline checks for the changed subsystem.\n4. Add checks for every subsystem whose contract might now be wrong.\n\n## When to Go beyond the Baseline\n\nRun deeper or wider validation when:\n\n- the change affects a high-risk workflow such as file editing, locking, upload, or pairing\n- you changed dependencies or version metadata\n- you changed typed API contracts\n- you changed browser-sensitive editor behavior such as focus handoff, contenteditable selection, keyboard navigation, or decorator-backed editing flows\n- you changed companion native dependencies, Windows-specific crates, or Tauri integration\n- the change fixes a regression that previously escaped narrower coverage\n\nThe goal is not maximum command count. The goal is to prove the changed behavior still matches Sambee's cross-app contracts.\n\n## Backend Test Structure and Fixtures\n\nBackend tests live under `backend/tests/`.\n\nCommon files include:\n\n- `conftest.py`: shared fixtures and test wiring\n- `test_auth.py`: authentication and authorization behavior\n- `test_connections.py`: SMB connection management\n- `test_browser.py`: file-browsing behavior with mocked SMB backends\n\nCommon fixtures include:\n\n- `client`\n- `session`\n- `admin_user`, `regular_user`\n- `admin_token`, `user_token`\n- `auth_headers_admin`, `auth_headers_user`\n- `test_connection`\n- `multiple_connections`\n- `mock_smb_backend`\n\nUse the shared fixtures instead of rebuilding the same setup in each test file.\n\n## Performance Notes\n\n- backend tests use `pytest-xdist` for parallel execution in the normal workflow, but `@performance` tests run separately without xdist so timing assertions stay stable\n- coverage is intentionally optional during routine local work because it is slower\n- use deeper coverage when the change touches risky backend behavior or when CI-equivalent evidence matters\n\n## Go Deeper\n\n- [Image Conversion Test Assets](../image-conversion-test-assets/): generated fixtures, real colorspace assertions, and the backend integration suite for image-conversion regressions\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared cross-boundary rules that often expand the validation surface\n- [How to Plan and Review a Change](../../contribution-workflows/how-to-plan-and-review-a-change/): decide scope before choosing checks\n- [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/): use this when version metadata or reviewed dependency inputs are part of the change\n", "1.0": "+++\ntitle = \"Test Strategy Overview\"\n+++\n\nSambee has multiple subsystems, so the right validation strategy depends on which contract you changed.\n\n## Start with the Smallest Relevant Set\n\nDo not default to either no validation or every possible check.\n\n- backend-only change with no shared contract impact: run backend tests and type checking\n- frontend-only change: run frontend tests, type check, and lint\n- companion-only change: run companion checks, the Windows GNU cross-check, and Rust tests\n- shared workflow change: run every affected subsystem's checks\n\n## Recommended Checks by Change Area\n\n| Change area | Baseline checks |\n|---|---|\n| Backend behavior | `cd backend \u0026\u0026 pytest -m 'not performance' -v`, `cd backend \u0026\u0026 pytest -m performance -v`, `cd backend \u0026\u0026 mypy app` |\n| Frontend behavior | `cd frontend \u0026\u0026 npm test`, `cd frontend \u0026\u0026 npx tsc --noEmit`, `cd frontend \u0026\u0026 npm run lint` |\n| Companion behavior | `cd companion \u0026\u0026 npx tsc --noEmit`, `cd companion \u0026\u0026 npm run lint`, `cd companion \u0026\u0026 npm run check:rust:windows`, `cd companion/src-tauri \u0026\u0026 cargo test` |\n\nFor fast local iteration, `./scripts/test` runs the main backend, frontend, and companion suites together. Its backend pass mirrors CI by running non-performance tests in parallel and `@performance` tests in a separate serial pass. The local companion pass now also includes the Windows GNU target compatibility check when the toolchain is installed. Use `COVERAGE=1 ./scripts/test` when you want the broader CI-style coverage pass.\n\n### Frontend Browser-Test Layers\n\nKeep frontend browser coverage explicit instead of folding it into the default Vitest command.\n\n- `cd frontend \u0026\u0026 npm test` runs the default Vitest suite.\n- `cd frontend \u0026\u0026 npm run test:e2e` runs the default Playwright Chromium suite.\n- `cd frontend \u0026\u0026 npm run test:e2e:all` runs all configured Playwright browser projects.\n\nInstall Playwright browsers locally with `cd frontend \u0026\u0026 npm run test:e2e:install` when a fresh environment does not have the browser binaries yet.\n\n## Cross-Boundary Changes Need Cross-Boundary Checks\n\nRun broader coverage when you change a shared contract, for example:\n\n- backend response shape that the frontend consumes\n- companion behavior that changes browser-facing pairing or editing flows\n- localization or logging behavior that spans more than one app\n\n## Contract-Sensitive Areas\n\n### API Contracts\n\nFrontend and backend compatibility depends on stable response shapes and matching types. Sambee currently protects that boundary primarily with frontend service contract tests plus backend endpoint tests for the same response families.\n\n#### Current Pattern in This Repository\n\nThe current API-contract pattern is broader than a single logging endpoint.\n\n- frontend contract suites live under `frontend/src/services/__tests__/`\n- those tests typically mock the HTTP client, call the real frontend service methods, and assert endpoint paths, request parameters, response shapes, field types, enum values, blob headers, and error handling\n- representative suites include `authApi.test.ts`, `connectionApi.test.ts`, `browseApi.test.ts`, `viewerApi.test.ts`, `mobileLoggingApi.test.ts`, and `loggingConfig.test.ts`\n- backend tests validate the corresponding FastAPI surface from the server side, for example `backend/tests/test_logging_config.py`\n\nThat means an API-shape change is not just a backend refactor. It is a cross-boundary behavior change that should update backend models, backend tests, frontend types, frontend service logic, and the contract tests that bind them together.\n\n#### What the Frontend Contract Tests Actually Check\n\nThe frontend service contract tests are not only smoke tests.\n\n- authentication and admin flows check required fields and value shapes for token, user, and connection payloads\n- browse tests check nested directory listings, `FileInfo` structure, enum values, optional metadata, and path handling\n- viewer tests check binary-response behavior such as `Blob` creation, `Content-Type` handling, viewport parameters, and download semantics\n- logging-config tests check the exact backend response shape and then verify behavior derived from it, such as level-threshold evaluation and disabled-state behavior\n\nThe useful rule is: test the response contract first, then test the frontend behavior that depends on that contract.\n\n#### Logging Configuration as a Concrete Example\n\nThe logging configuration tests are a good example because they show both sides of the boundary.\n\n- backend tests assert the `/api/logs/config` response contains `logging_enabled`, `logging_level`, `tracing_enabled`, `tracing_level`, and `tracing_components`\n- frontend tests in `loggingConfig.test.ts` consume that exact shape and then verify threshold and filtering behavior that would break if the backend fields drifted\n\nThis matters because an older or copied example that still expects fields like `enabled` or `log_level` would describe the wrong contract for the current codebase.\n\n#### When to Add or Update Contract Tests\n\nAdd or expand API contract coverage when:\n\n- you add a new frontend-consumed endpoint\n- you rename, remove, or add a response field\n- you change enum values or allowed string values\n- you change binary-response behavior such as MIME handling, blob creation, or download headers\n- you add frontend logic that derives behavior from backend configuration values rather than just displaying them\n\nFor those changes, update both ends together:\n\n1. backend response model or endpoint behavior\n2. backend tests for the server response\n3. frontend types and service methods\n4. frontend contract tests for the consumed shape\n5. frontend behavior tests for the logic built on top of that shape\n\n#### Practical Contract-Testing Checklist\n\nFor a new or changed endpoint, usually verify:\n\n- required fields exist\n- field types match the frontend types\n- optional fields behave correctly when present or absent\n- known enum or string-literal values are accepted intentionally\n- request parameters and path construction still match the backend route contract\n- error responses degrade in a controlled way\n- derived frontend behavior still works once the typed response is consumed\n\n#### OpenAPI as a Future Option\n\nSambee exposes and tests the backend OpenAPI schema, including `/openapi.json`, but TypeScript type generation from that schema is not part of the checked-in frontend workflow today.\n\nIf API surface area grows enough to justify generation, OpenAPI-driven types are a reasonable future option because the backend is already able to publish the schema. Treat that as an explicit workflow addition, not as something the repository already guarantees.\n\nPossible future additions include:\n\n- generating TypeScript types from the FastAPI schema in a reviewed frontend workflow\n- adding CI checks that detect generated-type drift\n- widening contract-style coverage for endpoints that still rely mostly on broader unit tests or integration tests\n\n### Localization\n\nLocalization is treated as typed product behavior, not just string replacement. If you touch translation wiring or browser-to-companion localization sync, validate the relevant frontend and companion checks.\n\n### Companion Cross-Target Safety\n\nCompanion contributors now have a local Linux-hosted Windows-target safety check.\n\n- `npm run check:rust:windows` runs `cargo check` for `x86_64-pc-windows-gnu`.\n- In the devcontainer, the required Rust target and MinGW toolchain are preinstalled.\n- This check is for compatibility validation, not for producing release-ready Windows binaries.\n\nKeep the distinction clear:\n\n- local cross-check: prove the Windows target still compiles far enough for contract and dependency safety\n- release build: create the signed Windows installer and updater artifacts in CI on Windows runners\n\n### Logging and Diagnostics\n\nLogging changes can affect both local debugging and backend trace collection. Validate the app surfaces that consume those logging contracts.\n\n## Practical Selection Rule\n\nUse this decision order:\n\n1. Identify which subsystem changed directly.\n2. Identify which other subsystem consumes the changed contract.\n3. Run baseline checks for the changed subsystem.\n4. Add checks for every subsystem whose contract might now be wrong.\n\n## When to Go beyond the Baseline\n\nRun deeper or wider validation when:\n\n- the change affects a high-risk workflow such as file editing, locking, upload, or pairing\n- you changed dependencies or version metadata\n- you changed typed API contracts\n- you changed browser-sensitive editor behavior such as focus handoff, contenteditable selection, keyboard navigation, or decorator-backed editing flows\n- you changed companion native dependencies, Windows-specific crates, or Tauri integration\n- the change fixes a regression that previously escaped narrower coverage\n\nThe goal is not maximum command count. The goal is to prove the changed behavior still matches Sambee's cross-app contracts.\n\n## Backend Test Structure and Fixtures\n\nBackend tests live under `backend/tests/`.\n\nCommon files include:\n\n- `conftest.py`: shared fixtures and test wiring\n- `test_auth.py`: authentication and authorization behavior\n- `test_connections.py`: SMB connection management\n- `test_browser.py`: file-browsing behavior with mocked SMB backends\n\nCommon fixtures include:\n\n- `client`\n- `session`\n- `admin_user`, `regular_user`\n- `admin_token`, `user_token`\n- `auth_headers_admin`, `auth_headers_user`\n- `test_connection`\n- `multiple_connections`\n- `mock_smb_backend`\n\nUse the shared fixtures instead of rebuilding the same setup in each test file.\n\n## Performance Notes\n\n- backend tests use `pytest-xdist` for parallel execution in the normal workflow, but `@performance` tests run separately without xdist so timing assertions stay stable\n- coverage is intentionally optional during routine local work because it is slower\n- use deeper coverage when the change touches risky backend behavior or when CI-equivalent evidence matters\n\n## Go Deeper\n\n- [Image Conversion Test Assets](../image-conversion-test-assets/): generated fixtures, real colorspace assertions, and the backend integration suite for image-conversion regressions\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared cross-boundary rules that often expand the validation surface\n- [How to Plan and Review a Change](../../contribution-workflows/how-to-plan-and-review-a-change/): decide scope before choosing checks\n- [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/): use this when version metadata or reviewed dependency inputs are part of the change\n", "2.0": "+++\ntitle = \"Test Strategy Overview\"\n+++\n\nSambee has multiple subsystems, so the right validation strategy depends on which contract you changed.\n\n## Start with the Smallest Relevant Set\n\nDo not default to either no validation or every possible check.\n\n- backend-only change with no shared contract impact: run backend tests and type checking\n- frontend-only change: run frontend tests, type check, and lint\n- companion-only change: run companion checks, the Windows GNU cross-check, and Rust tests\n- shared workflow change: run every affected subsystem's checks\n\n## Recommended Checks by Change Area\n\n| Change area | Baseline checks |\n|---|---|\n| Backend behavior | `cd backend \u0026\u0026 pytest -m 'not performance' -v`, `cd backend \u0026\u0026 pytest -m performance -v`, `cd backend \u0026\u0026 mypy app` |\n| Frontend behavior | `cd frontend \u0026\u0026 npm test`, `cd frontend \u0026\u0026 npx tsc --noEmit`, `cd frontend \u0026\u0026 npm run lint` |\n| Companion behavior | `cd companion \u0026\u0026 npx tsc --noEmit`, `cd companion \u0026\u0026 npm run lint`, `cd companion \u0026\u0026 npm run check:rust:windows`, `cd companion/src-tauri \u0026\u0026 cargo test` |\n\nFor fast local iteration, `./scripts/test` runs the main backend, frontend, and companion suites together. Its backend pass mirrors CI by running non-performance tests in parallel and `@performance` tests in a separate serial pass. The local companion pass now also includes the Windows GNU target compatibility check when the toolchain is installed. Use `COVERAGE=1 ./scripts/test` when you want the broader CI-style coverage pass.\n\n### Frontend Browser-Test Layers\n\nKeep frontend browser coverage explicit instead of folding it into the default Vitest command.\n\n- `cd frontend \u0026\u0026 npm test` runs the default Vitest suite.\n- `cd frontend \u0026\u0026 npm run test:e2e` runs the default Playwright Chromium suite.\n- `cd frontend \u0026\u0026 npm run test:e2e:all` runs all configured Playwright browser projects.\n\nInstall Playwright browsers locally with `cd frontend \u0026\u0026 npm run test:e2e:install` when a fresh environment does not have the browser binaries yet.\n\n## Cross-Boundary Changes Need Cross-Boundary Checks\n\nRun broader coverage when you change a shared contract, for example:\n\n- backend response shape that the frontend consumes\n- companion behavior that changes browser-facing pairing or editing flows\n- localization or logging behavior that spans more than one app\n\n## Contract-Sensitive Areas\n\n### API Contracts\n\nFrontend and backend compatibility depends on stable response shapes and matching types. Sambee currently protects that boundary primarily with frontend service contract tests plus backend endpoint tests for the same response families.\n\n#### Current Pattern in This Repository\n\nThe current API-contract pattern is broader than a single logging endpoint.\n\n- frontend contract suites live under `frontend/src/services/__tests__/`\n- those tests typically mock the HTTP client, call the real frontend service methods, and assert endpoint paths, request parameters, response shapes, field types, enum values, blob headers, and error handling\n- representative suites include `authApi.test.ts`, `connectionApi.test.ts`, `browseApi.test.ts`, `viewerApi.test.ts`, `mobileLoggingApi.test.ts`, and `loggingConfig.test.ts`\n- backend tests validate the corresponding FastAPI surface from the server side, for example `backend/tests/test_logging_config.py`\n\nThat means an API-shape change is not just a backend refactor. It is a cross-boundary behavior change that should update backend models, backend tests, frontend types, frontend service logic, and the contract tests that bind them together.\n\n#### What the Frontend Contract Tests Actually Check\n\nThe frontend service contract tests are not only smoke tests.\n\n- authentication and admin flows check required fields and value shapes for token, user, and connection payloads\n- browse tests check nested directory listings, `FileInfo` structure, enum values, optional metadata, and path handling\n- viewer tests check binary-response behavior such as `Blob` creation, `Content-Type` handling, viewport parameters, and download semantics\n- logging-config tests check the exact backend response shape and then verify behavior derived from it, such as level-threshold evaluation and disabled-state behavior\n\nThe useful rule is: test the response contract first, then test the frontend behavior that depends on that contract.\n\n#### Logging Configuration as a Concrete Example\n\nThe logging configuration tests are a good example because they show both sides of the boundary.\n\n- backend tests assert the `/api/logs/config` response contains `logging_enabled`, `logging_level`, `tracing_enabled`, `tracing_level`, and `tracing_components`\n- frontend tests in `loggingConfig.test.ts` consume that exact shape and then verify threshold and filtering behavior that would break if the backend fields drifted\n\nThis matters because an older or copied example that still expects fields like `enabled` or `log_level` would describe the wrong contract for the current codebase.\n\n#### When to Add or Update Contract Tests\n\nAdd or expand API contract coverage when:\n\n- you add a new frontend-consumed endpoint\n- you rename, remove, or add a response field\n- you change enum values or allowed string values\n- you change binary-response behavior such as MIME handling, blob creation, or download headers\n- you add frontend logic that derives behavior from backend configuration values rather than just displaying them\n\nFor those changes, update both ends together:\n\n1. backend response model or endpoint behavior\n2. backend tests for the server response\n3. frontend types and service methods\n4. frontend contract tests for the consumed shape\n5. frontend behavior tests for the logic built on top of that shape\n\n#### Practical Contract-Testing Checklist\n\nFor a new or changed endpoint, usually verify:\n\n- required fields exist\n- field types match the frontend types\n- optional fields behave correctly when present or absent\n- known enum or string-literal values are accepted intentionally\n- request parameters and path construction still match the backend route contract\n- error responses degrade in a controlled way\n- derived frontend behavior still works once the typed response is consumed\n\n#### OpenAPI as a Future Option\n\nSambee exposes and tests the backend OpenAPI schema, including `/openapi.json`, but TypeScript type generation from that schema is not part of the checked-in frontend workflow today.\n\nIf API surface area grows enough to justify generation, OpenAPI-driven types are a reasonable future option because the backend is already able to publish the schema. Treat that as an explicit workflow addition, not as something the repository already guarantees.\n\nPossible future additions include:\n\n- generating TypeScript types from the FastAPI schema in a reviewed frontend workflow\n- adding CI checks that detect generated-type drift\n- widening contract-style coverage for endpoints that still rely mostly on broader unit tests or integration tests\n\n### Localization\n\nLocalization is treated as typed product behavior, not just string replacement. If you touch translation wiring or browser-to-companion localization sync, validate the relevant frontend and companion checks.\n\n### Companion Cross-Target Safety\n\nCompanion contributors now have a local Linux-hosted Windows-target safety check.\n\n- `npm run check:rust:windows` runs `cargo check` for `x86_64-pc-windows-gnu`.\n- In the devcontainer, the required Rust target and MinGW toolchain are preinstalled.\n- This check is for compatibility validation, not for producing release-ready Windows binaries.\n\nKeep the distinction clear:\n\n- local cross-check: prove the Windows target still compiles far enough for contract and dependency safety\n- release build: create the signed Windows installer and updater artifacts in CI on Windows runners\n\n### Logging and Diagnostics\n\nLogging changes can affect both local debugging and backend trace collection. Validate the app surfaces that consume those logging contracts.\n\n## Practical Selection Rule\n\nUse this decision order:\n\n1. Identify which subsystem changed directly.\n2. Identify which other subsystem consumes the changed contract.\n3. Run baseline checks for the changed subsystem.\n4. Add checks for every subsystem whose contract might now be wrong.\n\n## When to Go beyond the Baseline\n\nRun deeper or wider validation when:\n\n- the change affects a high-risk workflow such as file editing, locking, upload, or pairing\n- you changed dependencies or version metadata\n- you changed typed API contracts\n- you changed browser-sensitive editor behavior such as focus handoff, contenteditable selection, keyboard navigation, or decorator-backed editing flows\n- you changed companion native dependencies, Windows-specific crates, or Tauri integration\n- the change fixes a regression that previously escaped narrower coverage\n\nThe goal is not maximum command count. The goal is to prove the changed behavior still matches Sambee's cross-app contracts.\n\n## Backend Test Structure and Fixtures\n\nBackend tests live under `backend/tests/`.\n\nCommon files include:\n\n- `conftest.py`: shared fixtures and test wiring\n- `test_auth.py`: authentication and authorization behavior\n- `test_connections.py`: SMB connection management\n- `test_browser.py`: file-browsing behavior with mocked SMB backends\n\nCommon fixtures include:\n\n- `client`\n- `session`\n- `admin_user`, `regular_user`\n- `admin_token`, `user_token`\n- `auth_headers_admin`, `auth_headers_user`\n- `test_connection`\n- `multiple_connections`\n- `mock_smb_backend`\n\nUse the shared fixtures instead of rebuilding the same setup in each test file.\n\n## Performance Notes\n\n- backend tests use `pytest-xdist` for parallel execution in the normal workflow, but `@performance` tests run separately without xdist so timing assertions stay stable\n- coverage is intentionally optional during routine local work because it is slower\n- use deeper coverage when the change touches risky backend behavior or when CI-equivalent evidence matters\n\n## Go Deeper\n\n- [Image Conversion Test Assets](../image-conversion-test-assets/): generated fixtures, real colorspace assertions, and the backend integration suite for image-conversion regressions\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared cross-boundary rules that often expand the validation surface\n- [How to Plan and Review a Change](../../contribution-workflows/how-to-plan-and-review-a-change/): decide scope before choosing checks\n- [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/): use this when version metadata or reviewed dependency inputs are part of the change\n"}, "page_contents": {"0.7": "+++\ntitle = \"Test Strategy Overview\"\n+++\n\nSambee has multiple subsystems, so the right validation strategy depends on which contract you changed.\n\n## Start with the Smallest Relevant Set\n\nDo not default to either no validation or every possible check.\n\n- backend-only change with no shared contract impact: run backend tests and type checking\n- frontend-only change: run frontend tests, type check, and lint\n- companion-only change: run companion checks and Rust tests\n- shared workflow change: run every affected subsystem's checks\n\n## Recommended Checks by Change Area\n\n| Change area | Baseline checks |\n|---|---|\n| Backend behavior | `cd backend \u0026\u0026 pytest -m 'not performance' -v`, `cd backend \u0026\u0026 pytest -m performance -v`, `cd backend \u0026\u0026 mypy app` |\n| Frontend behavior | `cd frontend \u0026\u0026 npm test`, `cd frontend \u0026\u0026 npx tsc --noEmit`, `cd frontend \u0026\u0026 npm run lint` |\n| Companion behavior | `cd companion \u0026\u0026 npx tsc --noEmit`, `cd companion \u0026\u0026 npm run lint`, `cd companion/src-tauri \u0026\u0026 cargo test` |\n\nFor fast local iteration, `./scripts/test` runs the main backend, frontend, companion, and archive-topology suites together. It stops at the first failed check so you can fix that subsystem before spending time on later suites. The order is backend type checking and tests, frontend type checking, linting, and tests, companion checks and tests, then archive-specific topology verification. Its backend pass mirrors CI by running non-performance tests in parallel and `@performance` tests in a separate serial pass. Use `COVERAGE=1 ./scripts/test` when you want the broader CI-style coverage pass.\n\n## Cross-Boundary Changes Need Cross-Boundary Checks\n\nRun broader coverage when you change a shared contract, for example:\n\n- backend response shape that the frontend consumes\n- companion behavior that changes browser-facing pairing or editing flows\n- localization or logging behavior that spans more than one app\n\n## Contract-Sensitive Areas\n\n### API Contracts\n\nFrontend and backend compatibility depends on stable response shapes and matching types. Sambee currently protects that boundary primarily with frontend service contract tests plus backend endpoint tests for the same response families.\n\n#### Current Pattern in This Repository\n\nThe current API-contract pattern is broader than a single logging endpoint.\n\n- frontend contract suites live under `frontend/src/services/__tests__/`\n- those tests typically mock the HTTP client, call the real frontend service methods, and assert endpoint paths, request parameters, response shapes, field types, enum values, blob headers, and error handling\n- representative suites include `authApi.test.ts`, `connectionApi.test.ts`, `browseApi.test.ts`, `viewerApi.test.ts`, `mobileLoggingApi.test.ts`, and `loggingConfig.test.ts`\n- backend tests validate the corresponding FastAPI surface from the server side, for example `backend/tests/test_logging_config.py`\n\nThat means an API-shape change is not just a backend refactor. It is a cross-boundary behavior change that should update backend models, backend tests, frontend types, frontend service logic, and the contract tests that bind them together.\n\n#### What the Frontend Contract Tests Actually Check\n\nThe frontend service contract tests are not only smoke tests.\n\n- authentication and admin flows check required fields and value shapes for token, user, and connection payloads\n- browse tests check nested directory listings, `FileInfo` structure, enum values, optional metadata, and path handling\n- viewer tests check binary-response behavior such as `Blob` creation, `Content-Type` handling, viewport parameters, and download semantics\n- logging-config tests check the exact backend response shape and then verify behavior derived from it, such as level-threshold evaluation and disabled-state behavior\n\nThe useful rule is: test the response contract first, then test the frontend behavior that depends on that contract.\n\n#### Logging Configuration as a Concrete Example\n\nThe logging configuration tests are a good example because they show both sides of the boundary.\n\n- backend tests assert the `/api/logs/config` response contains `logging_enabled`, `logging_level`, `tracing_enabled`, `tracing_level`, and `tracing_components`\n- frontend tests in `loggingConfig.test.ts` consume that exact shape and then verify threshold and filtering behavior that would break if the backend fields drifted\n\nThis matters because an older or copied example that still expects fields like `enabled` or `log_level` would describe the wrong contract for the current codebase.\n\n#### When to Add or Update Contract Tests\n\nAdd or expand API contract coverage when:\n\n- you add a new frontend-consumed endpoint\n- you rename, remove, or add a response field\n- you change enum values or allowed string values\n- you change binary-response behavior such as MIME handling, blob creation, or download headers\n- you add frontend logic that derives behavior from backend configuration values rather than just displaying them\n\nFor those changes, update both ends together:\n\n1. backend response model or endpoint behavior\n2. backend tests for the server response\n3. frontend types and service methods\n4. frontend contract tests for the consumed shape\n5. frontend behavior tests for the logic built on top of that shape\n\n#### Practical Contract-Testing Checklist\n\nFor a new or changed endpoint, usually verify:\n\n- required fields exist\n- field types match the frontend types\n- optional fields behave correctly when present or absent\n- known enum or string-literal values are accepted intentionally\n- request parameters and path construction still match the backend route contract\n- error responses degrade in a controlled way\n- derived frontend behavior still works once the typed response is consumed\n\n#### OpenAPI as a Future Option\n\nSambee exposes and tests the backend OpenAPI schema, including `/openapi.json`, but TypeScript type generation from that schema is not part of the checked-in frontend workflow today.\n\nIf API surface area grows enough to justify generation, OpenAPI-driven types are a reasonable future option because the backend is already able to publish the schema. Treat that as an explicit workflow addition, not as something the repository already guarantees.\n\nPossible future additions include:\n\n- generating TypeScript types from the FastAPI schema in a reviewed frontend workflow\n- adding CI checks that detect generated-type drift\n- widening contract-style coverage for endpoints that still rely mostly on broader unit tests or integration tests\n\n### Localization\n\nLocalization is treated as typed product behavior, not just string replacement. If you touch translation wiring or browser-to-companion localization sync, validate the relevant frontend and companion checks.\n\n### Logging and Diagnostics\n\nLogging changes can affect both local debugging and backend trace collection. Validate the app surfaces that consume those logging contracts.\n\n## Practical Selection Rule\n\nUse this decision order:\n\n1. Identify which subsystem changed directly.\n2. Identify which other subsystem consumes the changed contract.\n3. Run baseline checks for the changed subsystem.\n4. Add checks for every subsystem whose contract might now be wrong.\n\n## When to Go beyond the Baseline\n\nRun deeper or wider validation when:\n\n- the change affects a high-risk workflow such as file editing, locking, upload, or pairing\n- you changed dependencies or version metadata\n- you changed typed API contracts\n- the change fixes a regression that previously escaped narrower coverage\n\nThe goal is not maximum command count. The goal is to prove the changed behavior still matches Sambee's cross-app contracts.\n\n## Backend Test Structure and Fixtures\n\nBackend tests live under `backend/tests/`.\n\nCommon files include:\n\n- `conftest.py`: shared fixtures and test wiring\n- `test_auth.py`: authentication and authorization behavior\n- `test_connections.py`: SMB connection management\n- `test_browser.py`: file-browsing behavior with mocked SMB backends\n\nCommon fixtures include:\n\n- `client`\n- `session`\n- `admin_user`, `regular_user`\n- `admin_token`, `user_token`\n- `auth_headers_admin`, `auth_headers_user`\n- `test_connection`\n- `multiple_connections`\n- `mock_smb_backend`\n\nUse the shared fixtures instead of rebuilding the same setup in each test file.\n\n## Performance Notes\n\n- backend tests use `pytest-xdist` for parallel execution in the normal workflow, but `@performance` tests run separately without xdist so timing assertions stay stable\n- coverage is intentionally optional during routine local work because it is slower\n- use deeper coverage when the change touches risky backend behavior or when CI-equivalent evidence matters\n\n## Go Deeper\n\n- [Image Conversion Test Assets](../image-conversion-test-assets/): generated fixtures, real colorspace assertions, and the backend integration suite for image-conversion regressions\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared cross-boundary rules that often expand the validation surface\n- [How to Plan and Review a Change](../../contribution-workflows/how-to-plan-and-review-a-change/): decide scope before choosing checks\n- [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/): use this when version metadata or reviewed dependency inputs are part of the change\n", "0.8": "+++\ntitle = \"Test Strategy Overview\"\n+++\n\nSambee has multiple subsystems, so the right validation strategy depends on which contract you changed.\n\n## Start with the Smallest Relevant Set\n\nDo not default to either no validation or every possible check.\n\n- backend-only change with no shared contract impact: run backend tests and type checking\n- frontend-only change: run frontend tests, type check, and lint\n- companion-only change: run companion checks, the Windows GNU cross-check, and Rust tests\n- shared workflow change: run every affected subsystem's checks\n\n## Recommended Checks by Change Area\n\n| Change area | Baseline checks |\n|---|---|\n| Backend behavior | `cd backend \u0026\u0026 pytest -m 'not performance' -v`, `cd backend \u0026\u0026 pytest -m performance -v`, `cd backend \u0026\u0026 mypy app` |\n| Frontend behavior | `cd frontend \u0026\u0026 npm test`, `cd frontend \u0026\u0026 npx tsc --noEmit`, `cd frontend \u0026\u0026 npm run lint` |\n| Companion behavior | `cd companion \u0026\u0026 npx tsc --noEmit`, `cd companion \u0026\u0026 npm run lint`, `cd companion \u0026\u0026 npm run check:rust:windows`, `cd companion/src-tauri \u0026\u0026 cargo test` |\n\nFor fast local iteration, `./scripts/test` runs the main backend, frontend, and companion suites together. Its backend pass mirrors CI by running non-performance tests in parallel and `@performance` tests in a separate serial pass. The local companion pass now also includes the Windows GNU target compatibility check when the toolchain is installed. Use `COVERAGE=1 ./scripts/test` when you want the broader CI-style coverage pass.\n\n### Frontend Browser-Test Layers\n\nKeep frontend browser coverage explicit instead of folding it into the default Vitest command.\n\n- `cd frontend \u0026\u0026 npm test` runs the default Vitest suite.\n- `cd frontend \u0026\u0026 npm run test:e2e` runs the default Playwright Chromium suite.\n- `cd frontend \u0026\u0026 npm run test:e2e:all` runs all configured Playwright browser projects.\n\nInstall Playwright browsers locally with `cd frontend \u0026\u0026 npm run test:e2e:install` when a fresh environment does not have the browser binaries yet.\n\n## Cross-Boundary Changes Need Cross-Boundary Checks\n\nRun broader coverage when you change a shared contract, for example:\n\n- backend response shape that the frontend consumes\n- companion behavior that changes browser-facing pairing or editing flows\n- localization or logging behavior that spans more than one app\n\n## Contract-Sensitive Areas\n\n### API Contracts\n\nFrontend and backend compatibility depends on stable response shapes and matching types. Sambee currently protects that boundary primarily with frontend service contract tests plus backend endpoint tests for the same response families.\n\n#### Current Pattern in This Repository\n\nThe current API-contract pattern is broader than a single logging endpoint.\n\n- frontend contract suites live under `frontend/src/services/__tests__/`\n- those tests typically mock the HTTP client, call the real frontend service methods, and assert endpoint paths, request parameters, response shapes, field types, enum values, blob headers, and error handling\n- representative suites include `authApi.test.ts`, `connectionApi.test.ts`, `browseApi.test.ts`, `viewerApi.test.ts`, `mobileLoggingApi.test.ts`, and `loggingConfig.test.ts`\n- backend tests validate the corresponding FastAPI surface from the server side, for example `backend/tests/test_logging_config.py`\n\nThat means an API-shape change is not just a backend refactor. It is a cross-boundary behavior change that should update backend models, backend tests, frontend types, frontend service logic, and the contract tests that bind them together.\n\n#### What the Frontend Contract Tests Actually Check\n\nThe frontend service contract tests are not only smoke tests.\n\n- authentication and admin flows check required fields and value shapes for token, user, and connection payloads\n- browse tests check nested directory listings, `FileInfo` structure, enum values, optional metadata, and path handling\n- viewer tests check binary-response behavior such as `Blob` creation, `Content-Type` handling, viewport parameters, and download semantics\n- logging-config tests check the exact backend response shape and then verify behavior derived from it, such as level-threshold evaluation and disabled-state behavior\n\nThe useful rule is: test the response contract first, then test the frontend behavior that depends on that contract.\n\n#### Logging Configuration as a Concrete Example\n\nThe logging configuration tests are a good example because they show both sides of the boundary.\n\n- backend tests assert the `/api/logs/config` response contains `logging_enabled`, `logging_level`, `tracing_enabled`, `tracing_level`, and `tracing_components`\n- frontend tests in `loggingConfig.test.ts` consume that exact shape and then verify threshold and filtering behavior that would break if the backend fields drifted\n\nThis matters because an older or copied example that still expects fields like `enabled` or `log_level` would describe the wrong contract for the current codebase.\n\n#### When to Add or Update Contract Tests\n\nAdd or expand API contract coverage when:\n\n- you add a new frontend-consumed endpoint\n- you rename, remove, or add a response field\n- you change enum values or allowed string values\n- you change binary-response behavior such as MIME handling, blob creation, or download headers\n- you add frontend logic that derives behavior from backend configuration values rather than just displaying them\n\nFor those changes, update both ends together:\n\n1. backend response model or endpoint behavior\n2. backend tests for the server response\n3. frontend types and service methods\n4. frontend contract tests for the consumed shape\n5. frontend behavior tests for the logic built on top of that shape\n\n#### Practical Contract-Testing Checklist\n\nFor a new or changed endpoint, usually verify:\n\n- required fields exist\n- field types match the frontend types\n- optional fields behave correctly when present or absent\n- known enum or string-literal values are accepted intentionally\n- request parameters and path construction still match the backend route contract\n- error responses degrade in a controlled way\n- derived frontend behavior still works once the typed response is consumed\n\n#### OpenAPI as a Future Option\n\nSambee exposes and tests the backend OpenAPI schema, including `/openapi.json`, but TypeScript type generation from that schema is not part of the checked-in frontend workflow today.\n\nIf API surface area grows enough to justify generation, OpenAPI-driven types are a reasonable future option because the backend is already able to publish the schema. Treat that as an explicit workflow addition, not as something the repository already guarantees.\n\nPossible future additions include:\n\n- generating TypeScript types from the FastAPI schema in a reviewed frontend workflow\n- adding CI checks that detect generated-type drift\n- widening contract-style coverage for endpoints that still rely mostly on broader unit tests or integration tests\n\n### Localization\n\nLocalization is treated as typed product behavior, not just string replacement. If you touch translation wiring or browser-to-companion localization sync, validate the relevant frontend and companion checks.\n\n### Companion Cross-Target Safety\n\nCompanion contributors now have a local Linux-hosted Windows-target safety check.\n\n- `npm run check:rust:windows` runs `cargo check` for `x86_64-pc-windows-gnu`.\n- In the devcontainer, the required Rust target and MinGW toolchain are preinstalled.\n- This check is for compatibility validation, not for producing release-ready Windows binaries.\n\nKeep the distinction clear:\n\n- local cross-check: prove the Windows target still compiles far enough for contract and dependency safety\n- release build: create the signed Windows installer and updater artifacts in CI on Windows runners\n\n### Logging and Diagnostics\n\nLogging changes can affect both local debugging and backend trace collection. Validate the app surfaces that consume those logging contracts.\n\n## Practical Selection Rule\n\nUse this decision order:\n\n1. Identify which subsystem changed directly.\n2. Identify which other subsystem consumes the changed contract.\n3. Run baseline checks for the changed subsystem.\n4. Add checks for every subsystem whose contract might now be wrong.\n\n## When to Go beyond the Baseline\n\nRun deeper or wider validation when:\n\n- the change affects a high-risk workflow such as file editing, locking, upload, or pairing\n- you changed dependencies or version metadata\n- you changed typed API contracts\n- you changed browser-sensitive editor behavior such as focus handoff, contenteditable selection, keyboard navigation, or decorator-backed editing flows\n- you changed companion native dependencies, Windows-specific crates, or Tauri integration\n- the change fixes a regression that previously escaped narrower coverage\n\nThe goal is not maximum command count. The goal is to prove the changed behavior still matches Sambee's cross-app contracts.\n\n## Backend Test Structure and Fixtures\n\nBackend tests live under `backend/tests/`.\n\nCommon files include:\n\n- `conftest.py`: shared fixtures and test wiring\n- `test_auth.py`: authentication and authorization behavior\n- `test_connections.py`: SMB connection management\n- `test_browser.py`: file-browsing behavior with mocked SMB backends\n\nCommon fixtures include:\n\n- `client`\n- `session`\n- `admin_user`, `regular_user`\n- `admin_token`, `user_token`\n- `auth_headers_admin`, `auth_headers_user`\n- `test_connection`\n- `multiple_connections`\n- `mock_smb_backend`\n\nUse the shared fixtures instead of rebuilding the same setup in each test file.\n\n## Performance Notes\n\n- backend tests use `pytest-xdist` for parallel execution in the normal workflow, but `@performance` tests run separately without xdist so timing assertions stay stable\n- coverage is intentionally optional during routine local work because it is slower\n- use deeper coverage when the change touches risky backend behavior or when CI-equivalent evidence matters\n\n## Go Deeper\n\n- [Image Conversion Test Assets](../image-conversion-test-assets/): generated fixtures, real colorspace assertions, and the backend integration suite for image-conversion regressions\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared cross-boundary rules that often expand the validation surface\n- [How to Plan and Review a Change](../../contribution-workflows/how-to-plan-and-review-a-change/): decide scope before choosing checks\n- [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/): use this when version metadata or reviewed dependency inputs are part of the change\n", "0.9": "+++\ntitle = \"Test Strategy Overview\"\n+++\n\nSambee has multiple subsystems, so the right validation strategy depends on which contract you changed.\n\n## Start with the Smallest Relevant Set\n\nDo not default to either no validation or every possible check.\n\n- backend-only change with no shared contract impact: run backend tests and type checking\n- frontend-only change: run frontend tests, type check, and lint\n- companion-only change: run companion checks, the Windows GNU cross-check, and Rust tests\n- shared workflow change: run every affected subsystem's checks\n\n## Recommended Checks by Change Area\n\n| Change area | Baseline checks |\n|---|---|\n| Backend behavior | `cd backend \u0026\u0026 pytest -m 'not performance' -v`, `cd backend \u0026\u0026 pytest -m performance -v`, `cd backend \u0026\u0026 mypy app` |\n| Frontend behavior | `cd frontend \u0026\u0026 npm test`, `cd frontend \u0026\u0026 npx tsc --noEmit`, `cd frontend \u0026\u0026 npm run lint` |\n| Companion behavior | `cd companion \u0026\u0026 npx tsc --noEmit`, `cd companion \u0026\u0026 npm run lint`, `cd companion \u0026\u0026 npm run check:rust:windows`, `cd companion/src-tauri \u0026\u0026 cargo test` |\n\nFor fast local iteration, `./scripts/test` runs the main backend, frontend, and companion suites together. Its backend pass mirrors CI by running non-performance tests in parallel and `@performance` tests in a separate serial pass. The local companion pass now also includes the Windows GNU target compatibility check when the toolchain is installed. Use `COVERAGE=1 ./scripts/test` when you want the broader CI-style coverage pass.\n\n### Frontend Browser-Test Layers\n\nKeep frontend browser coverage explicit instead of folding it into the default Vitest command.\n\n- `cd frontend \u0026\u0026 npm test` runs the default Vitest suite.\n- `cd frontend \u0026\u0026 npm run test:e2e` runs the default Playwright Chromium suite.\n- `cd frontend \u0026\u0026 npm run test:e2e:all` runs all configured Playwright browser projects.\n\nInstall Playwright browsers locally with `cd frontend \u0026\u0026 npm run test:e2e:install` when a fresh environment does not have the browser binaries yet.\n\n## Cross-Boundary Changes Need Cross-Boundary Checks\n\nRun broader coverage when you change a shared contract, for example:\n\n- backend response shape that the frontend consumes\n- companion behavior that changes browser-facing pairing or editing flows\n- localization or logging behavior that spans more than one app\n\n## Contract-Sensitive Areas\n\n### API Contracts\n\nFrontend and backend compatibility depends on stable response shapes and matching types. Sambee currently protects that boundary primarily with frontend service contract tests plus backend endpoint tests for the same response families.\n\n#### Current Pattern in This Repository\n\nThe current API-contract pattern is broader than a single logging endpoint.\n\n- frontend contract suites live under `frontend/src/services/__tests__/`\n- those tests typically mock the HTTP client, call the real frontend service methods, and assert endpoint paths, request parameters, response shapes, field types, enum values, blob headers, and error handling\n- representative suites include `authApi.test.ts`, `connectionApi.test.ts`, `browseApi.test.ts`, `viewerApi.test.ts`, `mobileLoggingApi.test.ts`, and `loggingConfig.test.ts`\n- backend tests validate the corresponding FastAPI surface from the server side, for example `backend/tests/test_logging_config.py`\n\nThat means an API-shape change is not just a backend refactor. It is a cross-boundary behavior change that should update backend models, backend tests, frontend types, frontend service logic, and the contract tests that bind them together.\n\n#### What the Frontend Contract Tests Actually Check\n\nThe frontend service contract tests are not only smoke tests.\n\n- authentication and admin flows check required fields and value shapes for token, user, and connection payloads\n- browse tests check nested directory listings, `FileInfo` structure, enum values, optional metadata, and path handling\n- viewer tests check binary-response behavior such as `Blob` creation, `Content-Type` handling, viewport parameters, and download semantics\n- logging-config tests check the exact backend response shape and then verify behavior derived from it, such as level-threshold evaluation and disabled-state behavior\n\nThe useful rule is: test the response contract first, then test the frontend behavior that depends on that contract.\n\n#### Logging Configuration as a Concrete Example\n\nThe logging configuration tests are a good example because they show both sides of the boundary.\n\n- backend tests assert the `/api/logs/config` response contains `logging_enabled`, `logging_level`, `tracing_enabled`, `tracing_level`, and `tracing_components`\n- frontend tests in `loggingConfig.test.ts` consume that exact shape and then verify threshold and filtering behavior that would break if the backend fields drifted\n\nThis matters because an older or copied example that still expects fields like `enabled` or `log_level` would describe the wrong contract for the current codebase.\n\n#### When to Add or Update Contract Tests\n\nAdd or expand API contract coverage when:\n\n- you add a new frontend-consumed endpoint\n- you rename, remove, or add a response field\n- you change enum values or allowed string values\n- you change binary-response behavior such as MIME handling, blob creation, or download headers\n- you add frontend logic that derives behavior from backend configuration values rather than just displaying them\n\nFor those changes, update both ends together:\n\n1. backend response model or endpoint behavior\n2. backend tests for the server response\n3. frontend types and service methods\n4. frontend contract tests for the consumed shape\n5. frontend behavior tests for the logic built on top of that shape\n\n#### Practical Contract-Testing Checklist\n\nFor a new or changed endpoint, usually verify:\n\n- required fields exist\n- field types match the frontend types\n- optional fields behave correctly when present or absent\n- known enum or string-literal values are accepted intentionally\n- request parameters and path construction still match the backend route contract\n- error responses degrade in a controlled way\n- derived frontend behavior still works once the typed response is consumed\n\n#### OpenAPI as a Future Option\n\nSambee exposes and tests the backend OpenAPI schema, including `/openapi.json`, but TypeScript type generation from that schema is not part of the checked-in frontend workflow today.\n\nIf API surface area grows enough to justify generation, OpenAPI-driven types are a reasonable future option because the backend is already able to publish the schema. Treat that as an explicit workflow addition, not as something the repository already guarantees.\n\nPossible future additions include:\n\n- generating TypeScript types from the FastAPI schema in a reviewed frontend workflow\n- adding CI checks that detect generated-type drift\n- widening contract-style coverage for endpoints that still rely mostly on broader unit tests or integration tests\n\n### Localization\n\nLocalization is treated as typed product behavior, not just string replacement. If you touch translation wiring or browser-to-companion localization sync, validate the relevant frontend and companion checks.\n\n### Companion Cross-Target Safety\n\nCompanion contributors now have a local Linux-hosted Windows-target safety check.\n\n- `npm run check:rust:windows` runs `cargo check` for `x86_64-pc-windows-gnu`.\n- In the devcontainer, the required Rust target and MinGW toolchain are preinstalled.\n- This check is for compatibility validation, not for producing release-ready Windows binaries.\n\nKeep the distinction clear:\n\n- local cross-check: prove the Windows target still compiles far enough for contract and dependency safety\n- release build: create the signed Windows installer and updater artifacts in CI on Windows runners\n\n### Logging and Diagnostics\n\nLogging changes can affect both local debugging and backend trace collection. Validate the app surfaces that consume those logging contracts.\n\n## Practical Selection Rule\n\nUse this decision order:\n\n1. Identify which subsystem changed directly.\n2. Identify which other subsystem consumes the changed contract.\n3. Run baseline checks for the changed subsystem.\n4. Add checks for every subsystem whose contract might now be wrong.\n\n## When to Go beyond the Baseline\n\nRun deeper or wider validation when:\n\n- the change affects a high-risk workflow such as file editing, locking, upload, or pairing\n- you changed dependencies or version metadata\n- you changed typed API contracts\n- you changed browser-sensitive editor behavior such as focus handoff, contenteditable selection, keyboard navigation, or decorator-backed editing flows\n- you changed companion native dependencies, Windows-specific crates, or Tauri integration\n- the change fixes a regression that previously escaped narrower coverage\n\nThe goal is not maximum command count. The goal is to prove the changed behavior still matches Sambee's cross-app contracts.\n\n## Backend Test Structure and Fixtures\n\nBackend tests live under `backend/tests/`.\n\nCommon files include:\n\n- `conftest.py`: shared fixtures and test wiring\n- `test_auth.py`: authentication and authorization behavior\n- `test_connections.py`: SMB connection management\n- `test_browser.py`: file-browsing behavior with mocked SMB backends\n\nCommon fixtures include:\n\n- `client`\n- `session`\n- `admin_user`, `regular_user`\n- `admin_token`, `user_token`\n- `auth_headers_admin`, `auth_headers_user`\n- `test_connection`\n- `multiple_connections`\n- `mock_smb_backend`\n\nUse the shared fixtures instead of rebuilding the same setup in each test file.\n\n## Performance Notes\n\n- backend tests use `pytest-xdist` for parallel execution in the normal workflow, but `@performance` tests run separately without xdist so timing assertions stay stable\n- coverage is intentionally optional during routine local work because it is slower\n- use deeper coverage when the change touches risky backend behavior or when CI-equivalent evidence matters\n\n## Go Deeper\n\n- [Image Conversion Test Assets](../image-conversion-test-assets/): generated fixtures, real colorspace assertions, and the backend integration suite for image-conversion regressions\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared cross-boundary rules that often expand the validation surface\n- [How to Plan and Review a Change](../../contribution-workflows/how-to-plan-and-review-a-change/): decide scope before choosing checks\n- [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/): use this when version metadata or reviewed dependency inputs are part of the change\n", "1.0": "+++\ntitle = \"Test Strategy Overview\"\n+++\n\nSambee has multiple subsystems, so the right validation strategy depends on which contract you changed.\n\n## Start with the Smallest Relevant Set\n\nDo not default to either no validation or every possible check.\n\n- backend-only change with no shared contract impact: run backend tests and type checking\n- frontend-only change: run frontend tests, type check, and lint\n- companion-only change: run companion checks, the Windows GNU cross-check, and Rust tests\n- shared workflow change: run every affected subsystem's checks\n\n## Recommended Checks by Change Area\n\n| Change area | Baseline checks |\n|---|---|\n| Backend behavior | `cd backend \u0026\u0026 pytest -m 'not performance' -v`, `cd backend \u0026\u0026 pytest -m performance -v`, `cd backend \u0026\u0026 mypy app` |\n| Frontend behavior | `cd frontend \u0026\u0026 npm test`, `cd frontend \u0026\u0026 npx tsc --noEmit`, `cd frontend \u0026\u0026 npm run lint` |\n| Companion behavior | `cd companion \u0026\u0026 npx tsc --noEmit`, `cd companion \u0026\u0026 npm run lint`, `cd companion \u0026\u0026 npm run check:rust:windows`, `cd companion/src-tauri \u0026\u0026 cargo test` |\n\nFor fast local iteration, `./scripts/test` runs the main backend, frontend, and companion suites together. Its backend pass mirrors CI by running non-performance tests in parallel and `@performance` tests in a separate serial pass. The local companion pass now also includes the Windows GNU target compatibility check when the toolchain is installed. Use `COVERAGE=1 ./scripts/test` when you want the broader CI-style coverage pass.\n\n### Frontend Browser-Test Layers\n\nKeep frontend browser coverage explicit instead of folding it into the default Vitest command.\n\n- `cd frontend \u0026\u0026 npm test` runs the default Vitest suite.\n- `cd frontend \u0026\u0026 npm run test:e2e` runs the default Playwright Chromium suite.\n- `cd frontend \u0026\u0026 npm run test:e2e:all` runs all configured Playwright browser projects.\n\nInstall Playwright browsers locally with `cd frontend \u0026\u0026 npm run test:e2e:install` when a fresh environment does not have the browser binaries yet.\n\n## Cross-Boundary Changes Need Cross-Boundary Checks\n\nRun broader coverage when you change a shared contract, for example:\n\n- backend response shape that the frontend consumes\n- companion behavior that changes browser-facing pairing or editing flows\n- localization or logging behavior that spans more than one app\n\n## Contract-Sensitive Areas\n\n### API Contracts\n\nFrontend and backend compatibility depends on stable response shapes and matching types. Sambee currently protects that boundary primarily with frontend service contract tests plus backend endpoint tests for the same response families.\n\n#### Current Pattern in This Repository\n\nThe current API-contract pattern is broader than a single logging endpoint.\n\n- frontend contract suites live under `frontend/src/services/__tests__/`\n- those tests typically mock the HTTP client, call the real frontend service methods, and assert endpoint paths, request parameters, response shapes, field types, enum values, blob headers, and error handling\n- representative suites include `authApi.test.ts`, `connectionApi.test.ts`, `browseApi.test.ts`, `viewerApi.test.ts`, `mobileLoggingApi.test.ts`, and `loggingConfig.test.ts`\n- backend tests validate the corresponding FastAPI surface from the server side, for example `backend/tests/test_logging_config.py`\n\nThat means an API-shape change is not just a backend refactor. It is a cross-boundary behavior change that should update backend models, backend tests, frontend types, frontend service logic, and the contract tests that bind them together.\n\n#### What the Frontend Contract Tests Actually Check\n\nThe frontend service contract tests are not only smoke tests.\n\n- authentication and admin flows check required fields and value shapes for token, user, and connection payloads\n- browse tests check nested directory listings, `FileInfo` structure, enum values, optional metadata, and path handling\n- viewer tests check binary-response behavior such as `Blob` creation, `Content-Type` handling, viewport parameters, and download semantics\n- logging-config tests check the exact backend response shape and then verify behavior derived from it, such as level-threshold evaluation and disabled-state behavior\n\nThe useful rule is: test the response contract first, then test the frontend behavior that depends on that contract.\n\n#### Logging Configuration as a Concrete Example\n\nThe logging configuration tests are a good example because they show both sides of the boundary.\n\n- backend tests assert the `/api/logs/config` response contains `logging_enabled`, `logging_level`, `tracing_enabled`, `tracing_level`, and `tracing_components`\n- frontend tests in `loggingConfig.test.ts` consume that exact shape and then verify threshold and filtering behavior that would break if the backend fields drifted\n\nThis matters because an older or copied example that still expects fields like `enabled` or `log_level` would describe the wrong contract for the current codebase.\n\n#### When to Add or Update Contract Tests\n\nAdd or expand API contract coverage when:\n\n- you add a new frontend-consumed endpoint\n- you rename, remove, or add a response field\n- you change enum values or allowed string values\n- you change binary-response behavior such as MIME handling, blob creation, or download headers\n- you add frontend logic that derives behavior from backend configuration values rather than just displaying them\n\nFor those changes, update both ends together:\n\n1. backend response model or endpoint behavior\n2. backend tests for the server response\n3. frontend types and service methods\n4. frontend contract tests for the consumed shape\n5. frontend behavior tests for the logic built on top of that shape\n\n#### Practical Contract-Testing Checklist\n\nFor a new or changed endpoint, usually verify:\n\n- required fields exist\n- field types match the frontend types\n- optional fields behave correctly when present or absent\n- known enum or string-literal values are accepted intentionally\n- request parameters and path construction still match the backend route contract\n- error responses degrade in a controlled way\n- derived frontend behavior still works once the typed response is consumed\n\n#### OpenAPI as a Future Option\n\nSambee exposes and tests the backend OpenAPI schema, including `/openapi.json`, but TypeScript type generation from that schema is not part of the checked-in frontend workflow today.\n\nIf API surface area grows enough to justify generation, OpenAPI-driven types are a reasonable future option because the backend is already able to publish the schema. Treat that as an explicit workflow addition, not as something the repository already guarantees.\n\nPossible future additions include:\n\n- generating TypeScript types from the FastAPI schema in a reviewed frontend workflow\n- adding CI checks that detect generated-type drift\n- widening contract-style coverage for endpoints that still rely mostly on broader unit tests or integration tests\n\n### Localization\n\nLocalization is treated as typed product behavior, not just string replacement. If you touch translation wiring or browser-to-companion localization sync, validate the relevant frontend and companion checks.\n\n### Companion Cross-Target Safety\n\nCompanion contributors now have a local Linux-hosted Windows-target safety check.\n\n- `npm run check:rust:windows` runs `cargo check` for `x86_64-pc-windows-gnu`.\n- In the devcontainer, the required Rust target and MinGW toolchain are preinstalled.\n- This check is for compatibility validation, not for producing release-ready Windows binaries.\n\nKeep the distinction clear:\n\n- local cross-check: prove the Windows target still compiles far enough for contract and dependency safety\n- release build: create the signed Windows installer and updater artifacts in CI on Windows runners\n\n### Logging and Diagnostics\n\nLogging changes can affect both local debugging and backend trace collection. Validate the app surfaces that consume those logging contracts.\n\n## Practical Selection Rule\n\nUse this decision order:\n\n1. Identify which subsystem changed directly.\n2. Identify which other subsystem consumes the changed contract.\n3. Run baseline checks for the changed subsystem.\n4. Add checks for every subsystem whose contract might now be wrong.\n\n## When to Go beyond the Baseline\n\nRun deeper or wider validation when:\n\n- the change affects a high-risk workflow such as file editing, locking, upload, or pairing\n- you changed dependencies or version metadata\n- you changed typed API contracts\n- you changed browser-sensitive editor behavior such as focus handoff, contenteditable selection, keyboard navigation, or decorator-backed editing flows\n- you changed companion native dependencies, Windows-specific crates, or Tauri integration\n- the change fixes a regression that previously escaped narrower coverage\n\nThe goal is not maximum command count. The goal is to prove the changed behavior still matches Sambee's cross-app contracts.\n\n## Backend Test Structure and Fixtures\n\nBackend tests live under `backend/tests/`.\n\nCommon files include:\n\n- `conftest.py`: shared fixtures and test wiring\n- `test_auth.py`: authentication and authorization behavior\n- `test_connections.py`: SMB connection management\n- `test_browser.py`: file-browsing behavior with mocked SMB backends\n\nCommon fixtures include:\n\n- `client`\n- `session`\n- `admin_user`, `regular_user`\n- `admin_token`, `user_token`\n- `auth_headers_admin`, `auth_headers_user`\n- `test_connection`\n- `multiple_connections`\n- `mock_smb_backend`\n\nUse the shared fixtures instead of rebuilding the same setup in each test file.\n\n## Performance Notes\n\n- backend tests use `pytest-xdist` for parallel execution in the normal workflow, but `@performance` tests run separately without xdist so timing assertions stay stable\n- coverage is intentionally optional during routine local work because it is slower\n- use deeper coverage when the change touches risky backend behavior or when CI-equivalent evidence matters\n\n## Go Deeper\n\n- [Image Conversion Test Assets](../image-conversion-test-assets/): generated fixtures, real colorspace assertions, and the backend integration suite for image-conversion regressions\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared cross-boundary rules that often expand the validation surface\n- [How to Plan and Review a Change](../../contribution-workflows/how-to-plan-and-review-a-change/): decide scope before choosing checks\n- [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/): use this when version metadata or reviewed dependency inputs are part of the change\n", "2.0": "+++\ntitle = \"Test Strategy Overview\"\n+++\n\nSambee has multiple subsystems, so the right validation strategy depends on which contract you changed.\n\n## Start with the Smallest Relevant Set\n\nDo not default to either no validation or every possible check.\n\n- backend-only change with no shared contract impact: run backend tests and type checking\n- frontend-only change: run frontend tests, type check, and lint\n- companion-only change: run companion checks, the Windows GNU cross-check, and Rust tests\n- shared workflow change: run every affected subsystem's checks\n\n## Recommended Checks by Change Area\n\n| Change area | Baseline checks |\n|---|---|\n| Backend behavior | `cd backend \u0026\u0026 pytest -m 'not performance' -v`, `cd backend \u0026\u0026 pytest -m performance -v`, `cd backend \u0026\u0026 mypy app` |\n| Frontend behavior | `cd frontend \u0026\u0026 npm test`, `cd frontend \u0026\u0026 npx tsc --noEmit`, `cd frontend \u0026\u0026 npm run lint` |\n| Companion behavior | `cd companion \u0026\u0026 npx tsc --noEmit`, `cd companion \u0026\u0026 npm run lint`, `cd companion \u0026\u0026 npm run check:rust:windows`, `cd companion/src-tauri \u0026\u0026 cargo test` |\n\nFor fast local iteration, `./scripts/test` runs the main backend, frontend, and companion suites together. Its backend pass mirrors CI by running non-performance tests in parallel and `@performance` tests in a separate serial pass. The local companion pass now also includes the Windows GNU target compatibility check when the toolchain is installed. Use `COVERAGE=1 ./scripts/test` when you want the broader CI-style coverage pass.\n\n### Frontend Browser-Test Layers\n\nKeep frontend browser coverage explicit instead of folding it into the default Vitest command.\n\n- `cd frontend \u0026\u0026 npm test` runs the default Vitest suite.\n- `cd frontend \u0026\u0026 npm run test:e2e` runs the default Playwright Chromium suite.\n- `cd frontend \u0026\u0026 npm run test:e2e:all` runs all configured Playwright browser projects.\n\nInstall Playwright browsers locally with `cd frontend \u0026\u0026 npm run test:e2e:install` when a fresh environment does not have the browser binaries yet.\n\n## Cross-Boundary Changes Need Cross-Boundary Checks\n\nRun broader coverage when you change a shared contract, for example:\n\n- backend response shape that the frontend consumes\n- companion behavior that changes browser-facing pairing or editing flows\n- localization or logging behavior that spans more than one app\n\n## Contract-Sensitive Areas\n\n### API Contracts\n\nFrontend and backend compatibility depends on stable response shapes and matching types. Sambee currently protects that boundary primarily with frontend service contract tests plus backend endpoint tests for the same response families.\n\n#### Current Pattern in This Repository\n\nThe current API-contract pattern is broader than a single logging endpoint.\n\n- frontend contract suites live under `frontend/src/services/__tests__/`\n- those tests typically mock the HTTP client, call the real frontend service methods, and assert endpoint paths, request parameters, response shapes, field types, enum values, blob headers, and error handling\n- representative suites include `authApi.test.ts`, `connectionApi.test.ts`, `browseApi.test.ts`, `viewerApi.test.ts`, `mobileLoggingApi.test.ts`, and `loggingConfig.test.ts`\n- backend tests validate the corresponding FastAPI surface from the server side, for example `backend/tests/test_logging_config.py`\n\nThat means an API-shape change is not just a backend refactor. It is a cross-boundary behavior change that should update backend models, backend tests, frontend types, frontend service logic, and the contract tests that bind them together.\n\n#### What the Frontend Contract Tests Actually Check\n\nThe frontend service contract tests are not only smoke tests.\n\n- authentication and admin flows check required fields and value shapes for token, user, and connection payloads\n- browse tests check nested directory listings, `FileInfo` structure, enum values, optional metadata, and path handling\n- viewer tests check binary-response behavior such as `Blob` creation, `Content-Type` handling, viewport parameters, and download semantics\n- logging-config tests check the exact backend response shape and then verify behavior derived from it, such as level-threshold evaluation and disabled-state behavior\n\nThe useful rule is: test the response contract first, then test the frontend behavior that depends on that contract.\n\n#### Logging Configuration as a Concrete Example\n\nThe logging configuration tests are a good example because they show both sides of the boundary.\n\n- backend tests assert the `/api/logs/config` response contains `logging_enabled`, `logging_level`, `tracing_enabled`, `tracing_level`, and `tracing_components`\n- frontend tests in `loggingConfig.test.ts` consume that exact shape and then verify threshold and filtering behavior that would break if the backend fields drifted\n\nThis matters because an older or copied example that still expects fields like `enabled` or `log_level` would describe the wrong contract for the current codebase.\n\n#### When to Add or Update Contract Tests\n\nAdd or expand API contract coverage when:\n\n- you add a new frontend-consumed endpoint\n- you rename, remove, or add a response field\n- you change enum values or allowed string values\n- you change binary-response behavior such as MIME handling, blob creation, or download headers\n- you add frontend logic that derives behavior from backend configuration values rather than just displaying them\n\nFor those changes, update both ends together:\n\n1. backend response model or endpoint behavior\n2. backend tests for the server response\n3. frontend types and service methods\n4. frontend contract tests for the consumed shape\n5. frontend behavior tests for the logic built on top of that shape\n\n#### Practical Contract-Testing Checklist\n\nFor a new or changed endpoint, usually verify:\n\n- required fields exist\n- field types match the frontend types\n- optional fields behave correctly when present or absent\n- known enum or string-literal values are accepted intentionally\n- request parameters and path construction still match the backend route contract\n- error responses degrade in a controlled way\n- derived frontend behavior still works once the typed response is consumed\n\n#### OpenAPI as a Future Option\n\nSambee exposes and tests the backend OpenAPI schema, including `/openapi.json`, but TypeScript type generation from that schema is not part of the checked-in frontend workflow today.\n\nIf API surface area grows enough to justify generation, OpenAPI-driven types are a reasonable future option because the backend is already able to publish the schema. Treat that as an explicit workflow addition, not as something the repository already guarantees.\n\nPossible future additions include:\n\n- generating TypeScript types from the FastAPI schema in a reviewed frontend workflow\n- adding CI checks that detect generated-type drift\n- widening contract-style coverage for endpoints that still rely mostly on broader unit tests or integration tests\n\n### Localization\n\nLocalization is treated as typed product behavior, not just string replacement. If you touch translation wiring or browser-to-companion localization sync, validate the relevant frontend and companion checks.\n\n### Companion Cross-Target Safety\n\nCompanion contributors now have a local Linux-hosted Windows-target safety check.\n\n- `npm run check:rust:windows` runs `cargo check` for `x86_64-pc-windows-gnu`.\n- In the devcontainer, the required Rust target and MinGW toolchain are preinstalled.\n- This check is for compatibility validation, not for producing release-ready Windows binaries.\n\nKeep the distinction clear:\n\n- local cross-check: prove the Windows target still compiles far enough for contract and dependency safety\n- release build: create the signed Windows installer and updater artifacts in CI on Windows runners\n\n### Logging and Diagnostics\n\nLogging changes can affect both local debugging and backend trace collection. Validate the app surfaces that consume those logging contracts.\n\n## Practical Selection Rule\n\nUse this decision order:\n\n1. Identify which subsystem changed directly.\n2. Identify which other subsystem consumes the changed contract.\n3. Run baseline checks for the changed subsystem.\n4. Add checks for every subsystem whose contract might now be wrong.\n\n## When to Go beyond the Baseline\n\nRun deeper or wider validation when:\n\n- the change affects a high-risk workflow such as file editing, locking, upload, or pairing\n- you changed dependencies or version metadata\n- you changed typed API contracts\n- you changed browser-sensitive editor behavior such as focus handoff, contenteditable selection, keyboard navigation, or decorator-backed editing flows\n- you changed companion native dependencies, Windows-specific crates, or Tauri integration\n- the change fixes a regression that previously escaped narrower coverage\n\nThe goal is not maximum command count. The goal is to prove the changed behavior still matches Sambee's cross-app contracts.\n\n## Backend Test Structure and Fixtures\n\nBackend tests live under `backend/tests/`.\n\nCommon files include:\n\n- `conftest.py`: shared fixtures and test wiring\n- `test_auth.py`: authentication and authorization behavior\n- `test_connections.py`: SMB connection management\n- `test_browser.py`: file-browsing behavior with mocked SMB backends\n\nCommon fixtures include:\n\n- `client`\n- `session`\n- `admin_user`, `regular_user`\n- `admin_token`, `user_token`\n- `auth_headers_admin`, `auth_headers_user`\n- `test_connection`\n- `multiple_connections`\n- `mock_smb_backend`\n\nUse the shared fixtures instead of rebuilding the same setup in each test file.\n\n## Performance Notes\n\n- backend tests use `pytest-xdist` for parallel execution in the normal workflow, but `@performance` tests run separately without xdist so timing assertions stay stable\n- coverage is intentionally optional during routine local work because it is slower\n- use deeper coverage when the change touches risky backend behavior or when CI-equivalent evidence matters\n\n## Go Deeper\n\n- [Image Conversion Test Assets](../image-conversion-test-assets/): generated fixtures, real colorspace assertions, and the backend integration suite for image-conversion regressions\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared cross-boundary rules that often expand the validation surface\n- [How to Plan and Review a Change](../../contribution-workflows/how-to-plan-and-review-a-change/): decide scope before choosing checks\n- [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/): use this when version metadata or reviewed dependency inputs are part of the change\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/testing-and-quality-gates/image-conversion-test-assets", "parent_id": "section:developer-guide/testing-and-quality-gates", "depth": 2, "kind": "page", "label": "image-conversion-test-assets", "title": "Image Conversion Test Assets", "path": "developer-guide/testing-and-quality-gates/image-conversion-test-assets", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Image Conversion Test Assets\"\n+++\n\nSambee uses generated image fixtures to test the image-conversion and preprocessing pipeline without bloating the repository with large checked-in binaries.\n\nThese fixtures exist to verify real conversion behavior, especially around colorspace handling where naive expectations are often wrong.\n\n## Why These Assets Exist\n\nThe backend conversion pipeline has to do more than just decode files successfully.\n\n- CMYK inputs must convert into browser-safe RGB output without silent inversion or broken ICC handling\n- RGB inputs should preserve color rather than drifting during conversion\n- preprocessable vector formats such as EPS and AI need realistic fixtures, not only mocked unit tests\n- grayscale and Lab examples protect less-common conversion paths\n\nThat is why the repo includes a generated fixture workflow instead of relying only on synthetic unit-level mocks.\n\n## Where the Generated Assets Live\n\nThe generation workflow populates `backend/tests/test_data/`.\n\nCurrent layout:\n\n- `backend/tests/test_data/images/cmyk/`\n- `backend/tests/test_data/images/rgb/`\n- `backend/tests/test_data/images/special/`\n- `backend/tests/test_data/expected/`\n- `backend/tests/test_data/metadata/manifest.json`\n- `backend/tests/test_data/.gitignore`\n\nThe generated image set is intentionally small.\n\n- 4 CMYK fixtures\n- 4 RGB fixtures\n- 2 special-colorspace fixtures\n\nThose ten files are enough to exercise the main conversion and preprocessing paths without turning the repo into an asset dump.\n\n## What the Current Fixture Set Covers\n\n### CMYK Fixtures\n\nThe CMYK set covers:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThese are the highest-value fixtures because CMYK conversion is where incorrect assumptions are most likely.\n\nImportant rule: CMYK inputs do not convert to the naive pure RGB values contributors often expect.\n\nExamples from the real tests:\n\n- CMYK cyan does not become pure `(0, 255, 255)`\n- CMYK magenta does not become pure `(255, 0, 255)`\n- CMYK yellow does not become pure `(255, 255, 0)`\n- CMYK black does not become pure `(0, 0, 0)`\n\nThe expected values in `backend/tests/test_image_conversion_real.py` reflect real ICC-profile conversion output, and those test expectations are the current source of truth for assertion behavior.\n\n### RGB Fixtures\n\nThe RGB set verifies that already-browser-friendly color inputs do not get unintentionally altered during conversion.\n\nThose fixtures cover:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThe expectation there is preservation rather than major transformation.\n\n### Special Colorspaces\n\nThe special set currently includes:\n\n- grayscale PSD\n- Lab TIFF\n\nThese protect lesser-used but still important conversion paths.\n\n## How the Assets Are Generated\n\nThe supported entry point is:\n\n```bash\n./scripts/setup-test-images\n```\n\nThat script:\n\n- creates the test-data directory structure\n- generates raster fixtures with ImageMagick\n- generates EPS and AI fixtures with hand-crafted PostScript instead of relying on ImageMagick to produce trustworthy CMYK vector output\n- writes `metadata/manifest.json`\n- writes `backend/tests/test_data/.gitignore` so the generated artifacts do not become repository noise\n\nThe vector-generation choice is deliberate. Hand-crafted PostScript gives the tests explicit `DeviceCMYK` or `DeviceRGB` behavior that is more reliable than hoping a generic export path preserves the intended colorspace semantics.\n\n## Manifest Versus Test Assertions\n\nTreat the manifest as generated inventory metadata, not as the sole assertion source for the image-conversion tests.\n\nThe real backend assertions currently live in `backend/tests/test_image_conversion_real.py`, including:\n\n- colorspace expectations\n- color-distance tolerances\n- converter-path expectations such as preprocessor usage\n\nThat distinction matters because fixture metadata can drift if contributors update the script but forget the test semantics, or vice versa.\n\n## How the Tests Use the Assets\n\nThe main integration coverage lives in `backend/tests/test_image_conversion_real.py`.\n\nThat file:\n\n- auto-generates the fixtures through an autouse module-scoped fixture when they are missing\n- loads the generated manifest for iteration over the asset set\n- uses `pyvips` to inspect colorspace and average color values\n- verifies conversion output from `convert_image_for_viewer(...)`\n- checks preprocessable formats through `PreprocessorRegistry`\n\nThe tests are marked as integration tests because they exercise real decoding and conversion behavior rather than only mocked internals.\n\n## Supported Commands\n\nTo generate the assets explicitly:\n\n```bash\n./scripts/setup-test-images\n```\n\nTo run the real image-conversion integration suite:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -v\n```\n\nTo focus on CMYK behavior:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -k cmyk -v\n```\n\nTo pair the tests with backend coverage for the conversion service:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py --cov=app/services/image_converter\n```\n\n## Tolerances and Performance Expectations\n\nThe current suite intentionally allows some color-distance tolerance.\n\n- CMYK conversion assertions allow wider tolerance because ICC-based conversion is not a byte-for-byte identity transform\n- RGB preservation assertions use tighter thresholds because the expected result is much closer to the source color intent\n\nThe same suite also keeps a simple performance guard so tiny generated fixtures do not regress into unexpectedly slow conversions.\n\n## When to Change the Fixture Set\n\nUpdate the generated assets when:\n\n- you add support for a new preprocessable format\n- you change CMYK or colorspace handling in a way that should be locked down by a real fixture\n- you discover a real-world conversion regression that a small generated file can reproduce reliably\n\nWhen you add or change assets, update all three layers together:\n\n1. `scripts/setup-test-images`\n2. `backend/tests/test_image_conversion_real.py`\n3. the generated manifest or any related inventory description that the script emits\n\nDo not treat the assets as static binaries that should be edited by hand.\n\n## Troubleshooting\n\n### Assets Missing\n\nIf the fixtures are missing, rerun:\n\n```bash\n./scripts/setup-test-images\n```\n\nThe test module can generate them automatically, but explicit generation is usually the fastest way to confirm the local environment is healthy.\n\n### Imagemagick Missing\n\nThe generator expects ImageMagick 7 with the supported wrapper path or binary on `PATH`.\n\nIf the script reports that `magick` is missing, run the repo's supported system-dependency setup first:\n\n```bash\n./scripts/install-system-deps\n```\n\n### Color Mismatches\n\nIf color assertions change unexpectedly:\n\n- verify that the local environment still has the expected ImageMagick and ICC-profile support\n- check whether the backend conversion path changed intentionally\n- compare the actual average color output from the failing test before changing tolerances or expected values\n\nDo not update expected colors casually. CMYK expectations in particular exist to catch exactly that sort of silent behavior drift.\n", "0.8": "+++\ntitle = \"Image Conversion Test Assets\"\n+++\n\nSambee uses generated image fixtures to test the image-conversion and preprocessing pipeline without bloating the repository with large checked-in binaries.\n\nThese fixtures exist to verify real conversion behavior, especially around colorspace handling where naive expectations are often wrong.\n\n## Why These Assets Exist\n\nThe backend conversion pipeline has to do more than just decode files successfully.\n\n- CMYK inputs must convert into browser-safe RGB output without silent inversion or broken ICC handling\n- RGB inputs should preserve color rather than drifting during conversion\n- preprocessable vector formats such as EPS and AI need realistic fixtures, not only mocked unit tests\n- grayscale and Lab examples protect less-common conversion paths\n\nThat is why the repo includes a generated fixture workflow instead of relying only on synthetic unit-level mocks.\n\n## Where the Generated Assets Live\n\nThe generation workflow populates `backend/tests/test_data/`.\n\nCurrent layout:\n\n- `backend/tests/test_data/images/cmyk/`\n- `backend/tests/test_data/images/rgb/`\n- `backend/tests/test_data/images/special/`\n- `backend/tests/test_data/expected/`\n- `backend/tests/test_data/metadata/manifest.json`\n- `backend/tests/test_data/.gitignore`\n\nThe generated image set is intentionally small.\n\n- 4 CMYK fixtures\n- 4 RGB fixtures\n- 2 special-colorspace fixtures\n\nThose ten files are enough to exercise the main conversion and preprocessing paths without turning the repo into an asset dump.\n\n## What the Current Fixture Set Covers\n\n### CMYK Fixtures\n\nThe CMYK set covers:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThese are the highest-value fixtures because CMYK conversion is where incorrect assumptions are most likely.\n\nImportant rule: CMYK inputs do not convert to the naive pure RGB values contributors often expect.\n\nExamples from the real tests:\n\n- CMYK cyan does not become pure `(0, 255, 255)`\n- CMYK magenta does not become pure `(255, 0, 255)`\n- CMYK yellow does not become pure `(255, 255, 0)`\n- CMYK black does not become pure `(0, 0, 0)`\n\nThe expected values in `backend/tests/test_image_conversion_real.py` reflect real ICC-profile conversion output, and those test expectations are the current source of truth for assertion behavior.\n\n### RGB Fixtures\n\nThe RGB set verifies that already-browser-friendly color inputs do not get unintentionally altered during conversion.\n\nThose fixtures cover:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThe expectation there is preservation rather than major transformation.\n\n### Special Colorspaces\n\nThe special set currently includes:\n\n- grayscale PSD\n- Lab TIFF\n\nThese protect lesser-used but still important conversion paths.\n\n## How the Assets Are Generated\n\nThe supported entry point is:\n\n```bash\n./scripts/setup-test-images\n```\n\nThat script:\n\n- creates the test-data directory structure\n- generates raster fixtures with ImageMagick\n- generates EPS and AI fixtures with hand-crafted PostScript instead of relying on ImageMagick to produce trustworthy CMYK vector output\n- writes `metadata/manifest.json`\n- writes `backend/tests/test_data/.gitignore` so the generated artifacts do not become repository noise\n\nThe vector-generation choice is deliberate. Hand-crafted PostScript gives the tests explicit `DeviceCMYK` or `DeviceRGB` behavior that is more reliable than hoping a generic export path preserves the intended colorspace semantics.\n\n## Manifest Versus Test Assertions\n\nTreat the manifest as generated inventory metadata, not as the sole assertion source for the image-conversion tests.\n\nThe real backend assertions currently live in `backend/tests/test_image_conversion_real.py`, including:\n\n- colorspace expectations\n- color-distance tolerances\n- converter-path expectations such as preprocessor usage\n\nThat distinction matters because fixture metadata can drift if contributors update the script but forget the test semantics, or vice versa.\n\n## How the Tests Use the Assets\n\nThe main integration coverage lives in `backend/tests/test_image_conversion_real.py`.\n\nThat file:\n\n- auto-generates the fixtures through an autouse module-scoped fixture when they are missing\n- loads the generated manifest for iteration over the asset set\n- uses `pyvips` to inspect colorspace and average color values\n- verifies conversion output from `convert_image_for_viewer(...)`\n- checks preprocessable formats through `PreprocessorRegistry`\n\nThe tests are marked as integration tests because they exercise real decoding and conversion behavior rather than only mocked internals.\n\n## Supported Commands\n\nTo generate the assets explicitly:\n\n```bash\n./scripts/setup-test-images\n```\n\nTo run the real image-conversion integration suite:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -v\n```\n\nTo focus on CMYK behavior:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -k cmyk -v\n```\n\nTo pair the tests with backend coverage for the conversion service:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py --cov=app/services/image_converter\n```\n\n## Tolerances and Performance Expectations\n\nThe current suite intentionally allows some color-distance tolerance.\n\n- CMYK conversion assertions allow wider tolerance because ICC-based conversion is not a byte-for-byte identity transform\n- RGB preservation assertions use tighter thresholds because the expected result is much closer to the source color intent\n\nThe same suite also keeps a simple performance guard so tiny generated fixtures do not regress into unexpectedly slow conversions.\n\n## When to Change the Fixture Set\n\nUpdate the generated assets when:\n\n- you add support for a new preprocessable format\n- you change CMYK or colorspace handling in a way that should be locked down by a real fixture\n- you discover a real-world conversion regression that a small generated file can reproduce reliably\n\nWhen you add or change assets, update all three layers together:\n\n1. `scripts/setup-test-images`\n2. `backend/tests/test_image_conversion_real.py`\n3. the generated manifest or any related inventory description that the script emits\n\nDo not treat the assets as static binaries that should be edited by hand.\n\n## Troubleshooting\n\n### Assets Missing\n\nIf the fixtures are missing, rerun:\n\n```bash\n./scripts/setup-test-images\n```\n\nThe test module can generate them automatically, but explicit generation is usually the fastest way to confirm the local environment is healthy.\n\n### Imagemagick Missing\n\nThe generator expects ImageMagick 7 with the supported wrapper path or binary on `PATH`.\n\nIf the script reports that `magick` is missing, run the repo's supported system-dependency setup first:\n\n```bash\n./scripts/install-system-deps\n```\n\n### Color Mismatches\n\nIf color assertions change unexpectedly:\n\n- verify that the local environment still has the expected ImageMagick and ICC-profile support\n- check whether the backend conversion path changed intentionally\n- compare the actual average color output from the failing test before changing tolerances or expected values\n\nDo not update expected colors casually. CMYK expectations in particular exist to catch exactly that sort of silent behavior drift.\n", "0.9": "+++\ntitle = \"Image Conversion Test Assets\"\n+++\n\nSambee uses generated image fixtures to test the image-conversion and preprocessing pipeline without bloating the repository with large checked-in binaries.\n\nThese fixtures exist to verify real conversion behavior, especially around colorspace handling where naive expectations are often wrong.\n\n## Why These Assets Exist\n\nThe backend conversion pipeline has to do more than just decode files successfully.\n\n- CMYK inputs must convert into browser-safe RGB output without silent inversion or broken ICC handling\n- RGB inputs should preserve color rather than drifting during conversion\n- preprocessable vector formats such as EPS and AI need realistic fixtures, not only mocked unit tests\n- grayscale and Lab examples protect less-common conversion paths\n\nThat is why the repo includes a generated fixture workflow instead of relying only on synthetic unit-level mocks.\n\n## Where the Generated Assets Live\n\nThe generation workflow populates `backend/tests/test_data/`.\n\nCurrent layout:\n\n- `backend/tests/test_data/images/cmyk/`\n- `backend/tests/test_data/images/rgb/`\n- `backend/tests/test_data/images/special/`\n- `backend/tests/test_data/expected/`\n- `backend/tests/test_data/metadata/manifest.json`\n- `backend/tests/test_data/.gitignore`\n\nThe generated image set is intentionally small.\n\n- 4 CMYK fixtures\n- 4 RGB fixtures\n- 2 special-colorspace fixtures\n\nThose ten files are enough to exercise the main conversion and preprocessing paths without turning the repo into an asset dump.\n\n## What the Current Fixture Set Covers\n\n### CMYK Fixtures\n\nThe CMYK set covers:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThese are the highest-value fixtures because CMYK conversion is where incorrect assumptions are most likely.\n\nImportant rule: CMYK inputs do not convert to the naive pure RGB values contributors often expect.\n\nExamples from the real tests:\n\n- CMYK cyan does not become pure `(0, 255, 255)`\n- CMYK magenta does not become pure `(255, 0, 255)`\n- CMYK yellow does not become pure `(255, 255, 0)`\n- CMYK black does not become pure `(0, 0, 0)`\n\nThe expected values in `backend/tests/test_image_conversion_real.py` reflect real ICC-profile conversion output, and those test expectations are the current source of truth for assertion behavior.\n\n### RGB Fixtures\n\nThe RGB set verifies that already-browser-friendly color inputs do not get unintentionally altered during conversion.\n\nThose fixtures cover:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThe expectation there is preservation rather than major transformation.\n\n### Special Colorspaces\n\nThe special set currently includes:\n\n- grayscale PSD\n- Lab TIFF\n\nThese protect lesser-used but still important conversion paths.\n\n## How the Assets Are Generated\n\nThe supported entry point is:\n\n```bash\n./scripts/setup-test-images\n```\n\nThat script:\n\n- creates the test-data directory structure\n- generates raster fixtures with ImageMagick\n- generates EPS and AI fixtures with hand-crafted PostScript instead of relying on ImageMagick to produce trustworthy CMYK vector output\n- writes `metadata/manifest.json`\n- writes `backend/tests/test_data/.gitignore` so the generated artifacts do not become repository noise\n\nThe vector-generation choice is deliberate. Hand-crafted PostScript gives the tests explicit `DeviceCMYK` or `DeviceRGB` behavior that is more reliable than hoping a generic export path preserves the intended colorspace semantics.\n\n## Manifest Versus Test Assertions\n\nTreat the manifest as generated inventory metadata, not as the sole assertion source for the image-conversion tests.\n\nThe real backend assertions currently live in `backend/tests/test_image_conversion_real.py`, including:\n\n- colorspace expectations\n- color-distance tolerances\n- converter-path expectations such as preprocessor usage\n\nThat distinction matters because fixture metadata can drift if contributors update the script but forget the test semantics, or vice versa.\n\n## How the Tests Use the Assets\n\nThe main integration coverage lives in `backend/tests/test_image_conversion_real.py`.\n\nThat file:\n\n- auto-generates the fixtures through an autouse module-scoped fixture when they are missing\n- loads the generated manifest for iteration over the asset set\n- uses `pyvips` to inspect colorspace and average color values\n- verifies conversion output from `convert_image_for_viewer(...)`\n- checks preprocessable formats through `PreprocessorRegistry`\n\nThe tests are marked as integration tests because they exercise real decoding and conversion behavior rather than only mocked internals.\n\n## Supported Commands\n\nTo generate the assets explicitly:\n\n```bash\n./scripts/setup-test-images\n```\n\nTo run the real image-conversion integration suite:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -v\n```\n\nTo focus on CMYK behavior:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -k cmyk -v\n```\n\nTo pair the tests with backend coverage for the conversion service:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py --cov=app/services/image_converter\n```\n\n## Tolerances and Performance Expectations\n\nThe current suite intentionally allows some color-distance tolerance.\n\n- CMYK conversion assertions allow wider tolerance because ICC-based conversion is not a byte-for-byte identity transform\n- RGB preservation assertions use tighter thresholds because the expected result is much closer to the source color intent\n\nThe same suite also keeps a simple performance guard so tiny generated fixtures do not regress into unexpectedly slow conversions.\n\n## When to Change the Fixture Set\n\nUpdate the generated assets when:\n\n- you add support for a new preprocessable format\n- you change CMYK or colorspace handling in a way that should be locked down by a real fixture\n- you discover a real-world conversion regression that a small generated file can reproduce reliably\n\nWhen you add or change assets, update all three layers together:\n\n1. `scripts/setup-test-images`\n2. `backend/tests/test_image_conversion_real.py`\n3. the generated manifest or any related inventory description that the script emits\n\nDo not treat the assets as static binaries that should be edited by hand.\n\n## Troubleshooting\n\n### Assets Missing\n\nIf the fixtures are missing, rerun:\n\n```bash\n./scripts/setup-test-images\n```\n\nThe test module can generate them automatically, but explicit generation is usually the fastest way to confirm the local environment is healthy.\n\n### Imagemagick Missing\n\nThe generator expects ImageMagick 7 with the supported wrapper path or binary on `PATH`.\n\nIf the script reports that `magick` is missing, run the repo's supported system-dependency setup first:\n\n```bash\n./scripts/install-system-deps\n```\n\n### Color Mismatches\n\nIf color assertions change unexpectedly:\n\n- verify that the local environment still has the expected ImageMagick and ICC-profile support\n- check whether the backend conversion path changed intentionally\n- compare the actual average color output from the failing test before changing tolerances or expected values\n\nDo not update expected colors casually. CMYK expectations in particular exist to catch exactly that sort of silent behavior drift.\n", "1.0": "+++\ntitle = \"Image Conversion Test Assets\"\n+++\n\nSambee uses generated image fixtures to test the image-conversion and preprocessing pipeline without bloating the repository with large checked-in binaries.\n\nThese fixtures exist to verify real conversion behavior, especially around colorspace handling where naive expectations are often wrong.\n\n## Why These Assets Exist\n\nThe backend conversion pipeline has to do more than just decode files successfully.\n\n- CMYK inputs must convert into browser-safe RGB output without silent inversion or broken ICC handling\n- RGB inputs should preserve color rather than drifting during conversion\n- preprocessable vector formats such as EPS and AI need realistic fixtures, not only mocked unit tests\n- grayscale and Lab examples protect less-common conversion paths\n\nThat is why the repo includes a generated fixture workflow instead of relying only on synthetic unit-level mocks.\n\n## Where the Generated Assets Live\n\nThe generation workflow populates `backend/tests/test_data/`.\n\nCurrent layout:\n\n- `backend/tests/test_data/images/cmyk/`\n- `backend/tests/test_data/images/rgb/`\n- `backend/tests/test_data/images/special/`\n- `backend/tests/test_data/expected/`\n- `backend/tests/test_data/metadata/manifest.json`\n- `backend/tests/test_data/.gitignore`\n\nThe generated image set is intentionally small.\n\n- 4 CMYK fixtures\n- 4 RGB fixtures\n- 2 special-colorspace fixtures\n\nThose ten files are enough to exercise the main conversion and preprocessing paths without turning the repo into an asset dump.\n\n## What the Current Fixture Set Covers\n\n### CMYK Fixtures\n\nThe CMYK set covers:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThese are the highest-value fixtures because CMYK conversion is where incorrect assumptions are most likely.\n\nImportant rule: CMYK inputs do not convert to the naive pure RGB values contributors often expect.\n\nExamples from the real tests:\n\n- CMYK cyan does not become pure `(0, 255, 255)`\n- CMYK magenta does not become pure `(255, 0, 255)`\n- CMYK yellow does not become pure `(255, 255, 0)`\n- CMYK black does not become pure `(0, 0, 0)`\n\nThe expected values in `backend/tests/test_image_conversion_real.py` reflect real ICC-profile conversion output, and those test expectations are the current source of truth for assertion behavior.\n\n### RGB Fixtures\n\nThe RGB set verifies that already-browser-friendly color inputs do not get unintentionally altered during conversion.\n\nThose fixtures cover:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThe expectation there is preservation rather than major transformation.\n\n### Special Colorspaces\n\nThe special set currently includes:\n\n- grayscale PSD\n- Lab TIFF\n\nThese protect lesser-used but still important conversion paths.\n\n## How the Assets Are Generated\n\nThe supported entry point is:\n\n```bash\n./scripts/setup-test-images\n```\n\nThat script:\n\n- creates the test-data directory structure\n- generates raster fixtures with ImageMagick\n- generates EPS and AI fixtures with hand-crafted PostScript instead of relying on ImageMagick to produce trustworthy CMYK vector output\n- writes `metadata/manifest.json`\n- writes `backend/tests/test_data/.gitignore` so the generated artifacts do not become repository noise\n\nThe vector-generation choice is deliberate. Hand-crafted PostScript gives the tests explicit `DeviceCMYK` or `DeviceRGB` behavior that is more reliable than hoping a generic export path preserves the intended colorspace semantics.\n\n## Manifest Versus Test Assertions\n\nTreat the manifest as generated inventory metadata, not as the sole assertion source for the image-conversion tests.\n\nThe real backend assertions currently live in `backend/tests/test_image_conversion_real.py`, including:\n\n- colorspace expectations\n- color-distance tolerances\n- converter-path expectations such as preprocessor usage\n\nThat distinction matters because fixture metadata can drift if contributors update the script but forget the test semantics, or vice versa.\n\n## How the Tests Use the Assets\n\nThe main integration coverage lives in `backend/tests/test_image_conversion_real.py`.\n\nThat file:\n\n- auto-generates the fixtures through an autouse module-scoped fixture when they are missing\n- loads the generated manifest for iteration over the asset set\n- uses `pyvips` to inspect colorspace and average color values\n- verifies conversion output from `convert_image_for_viewer(...)`\n- checks preprocessable formats through `PreprocessorRegistry`\n\nThe tests are marked as integration tests because they exercise real decoding and conversion behavior rather than only mocked internals.\n\n## Supported Commands\n\nTo generate the assets explicitly:\n\n```bash\n./scripts/setup-test-images\n```\n\nTo run the real image-conversion integration suite:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -v\n```\n\nTo focus on CMYK behavior:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -k cmyk -v\n```\n\nTo pair the tests with backend coverage for the conversion service:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py --cov=app/services/image_converter\n```\n\n## Tolerances and Performance Expectations\n\nThe current suite intentionally allows some color-distance tolerance.\n\n- CMYK conversion assertions allow wider tolerance because ICC-based conversion is not a byte-for-byte identity transform\n- RGB preservation assertions use tighter thresholds because the expected result is much closer to the source color intent\n\nThe same suite also keeps a simple performance guard so tiny generated fixtures do not regress into unexpectedly slow conversions.\n\n## When to Change the Fixture Set\n\nUpdate the generated assets when:\n\n- you add support for a new preprocessable format\n- you change CMYK or colorspace handling in a way that should be locked down by a real fixture\n- you discover a real-world conversion regression that a small generated file can reproduce reliably\n\nWhen you add or change assets, update all three layers together:\n\n1. `scripts/setup-test-images`\n2. `backend/tests/test_image_conversion_real.py`\n3. the generated manifest or any related inventory description that the script emits\n\nDo not treat the assets as static binaries that should be edited by hand.\n\n## Troubleshooting\n\n### Assets Missing\n\nIf the fixtures are missing, rerun:\n\n```bash\n./scripts/setup-test-images\n```\n\nThe test module can generate them automatically, but explicit generation is usually the fastest way to confirm the local environment is healthy.\n\n### Imagemagick Missing\n\nThe generator expects ImageMagick 7 with the supported wrapper path or binary on `PATH`.\n\nIf the script reports that `magick` is missing, run the repo's supported system-dependency setup first:\n\n```bash\n./scripts/install-system-deps\n```\n\n### Color Mismatches\n\nIf color assertions change unexpectedly:\n\n- verify that the local environment still has the expected ImageMagick and ICC-profile support\n- check whether the backend conversion path changed intentionally\n- compare the actual average color output from the failing test before changing tolerances or expected values\n\nDo not update expected colors casually. CMYK expectations in particular exist to catch exactly that sort of silent behavior drift.\n", "2.0": "+++\ntitle = \"Image Conversion Test Assets\"\n+++\n\nSambee uses generated image fixtures to test the image-conversion and preprocessing pipeline without bloating the repository with large checked-in binaries.\n\nThese fixtures exist to verify real conversion behavior, especially around colorspace handling where naive expectations are often wrong.\n\n## Why These Assets Exist\n\nThe backend conversion pipeline has to do more than just decode files successfully.\n\n- CMYK inputs must convert into browser-safe RGB output without silent inversion or broken ICC handling\n- RGB inputs should preserve color rather than drifting during conversion\n- preprocessable vector formats such as EPS and AI need realistic fixtures, not only mocked unit tests\n- grayscale and Lab examples protect less-common conversion paths\n\nThat is why the repo includes a generated fixture workflow instead of relying only on synthetic unit-level mocks.\n\n## Where the Generated Assets Live\n\nThe generation workflow populates `backend/tests/test_data/`.\n\nCurrent layout:\n\n- `backend/tests/test_data/images/cmyk/`\n- `backend/tests/test_data/images/rgb/`\n- `backend/tests/test_data/images/special/`\n- `backend/tests/test_data/expected/`\n- `backend/tests/test_data/metadata/manifest.json`\n- `backend/tests/test_data/.gitignore`\n\nThe generated image set is intentionally small.\n\n- 4 CMYK fixtures\n- 4 RGB fixtures\n- 2 special-colorspace fixtures\n\nThose ten files are enough to exercise the main conversion and preprocessing paths without turning the repo into an asset dump.\n\n## What the Current Fixture Set Covers\n\n### CMYK Fixtures\n\nThe CMYK set covers:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThese are the highest-value fixtures because CMYK conversion is where incorrect assumptions are most likely.\n\nImportant rule: CMYK inputs do not convert to the naive pure RGB values contributors often expect.\n\nExamples from the real tests:\n\n- CMYK cyan does not become pure `(0, 255, 255)`\n- CMYK magenta does not become pure `(255, 0, 255)`\n- CMYK yellow does not become pure `(255, 255, 0)`\n- CMYK black does not become pure `(0, 0, 0)`\n\nThe expected values in `backend/tests/test_image_conversion_real.py` reflect real ICC-profile conversion output, and those test expectations are the current source of truth for assertion behavior.\n\n### RGB Fixtures\n\nThe RGB set verifies that already-browser-friendly color inputs do not get unintentionally altered during conversion.\n\nThose fixtures cover:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThe expectation there is preservation rather than major transformation.\n\n### Special Colorspaces\n\nThe special set currently includes:\n\n- grayscale PSD\n- Lab TIFF\n\nThese protect lesser-used but still important conversion paths.\n\n## How the Assets Are Generated\n\nThe supported entry point is:\n\n```bash\n./scripts/setup-test-images\n```\n\nThat script:\n\n- creates the test-data directory structure\n- generates raster fixtures with ImageMagick\n- generates EPS and AI fixtures with hand-crafted PostScript instead of relying on ImageMagick to produce trustworthy CMYK vector output\n- writes `metadata/manifest.json`\n- writes `backend/tests/test_data/.gitignore` so the generated artifacts do not become repository noise\n\nThe vector-generation choice is deliberate. Hand-crafted PostScript gives the tests explicit `DeviceCMYK` or `DeviceRGB` behavior that is more reliable than hoping a generic export path preserves the intended colorspace semantics.\n\n## Manifest Versus Test Assertions\n\nTreat the manifest as generated inventory metadata, not as the sole assertion source for the image-conversion tests.\n\nThe real backend assertions currently live in `backend/tests/test_image_conversion_real.py`, including:\n\n- colorspace expectations\n- color-distance tolerances\n- converter-path expectations such as preprocessor usage\n\nThat distinction matters because fixture metadata can drift if contributors update the script but forget the test semantics, or vice versa.\n\n## How the Tests Use the Assets\n\nThe main integration coverage lives in `backend/tests/test_image_conversion_real.py`.\n\nThat file:\n\n- auto-generates the fixtures through an autouse module-scoped fixture when they are missing\n- loads the generated manifest for iteration over the asset set\n- uses `pyvips` to inspect colorspace and average color values\n- verifies conversion output from `convert_image_for_viewer(...)`\n- checks preprocessable formats through `PreprocessorRegistry`\n\nThe tests are marked as integration tests because they exercise real decoding and conversion behavior rather than only mocked internals.\n\n## Supported Commands\n\nTo generate the assets explicitly:\n\n```bash\n./scripts/setup-test-images\n```\n\nTo run the real image-conversion integration suite:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -v\n```\n\nTo focus on CMYK behavior:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -k cmyk -v\n```\n\nTo pair the tests with backend coverage for the conversion service:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py --cov=app/services/image_converter\n```\n\n## Tolerances and Performance Expectations\n\nThe current suite intentionally allows some color-distance tolerance.\n\n- CMYK conversion assertions allow wider tolerance because ICC-based conversion is not a byte-for-byte identity transform\n- RGB preservation assertions use tighter thresholds because the expected result is much closer to the source color intent\n\nThe same suite also keeps a simple performance guard so tiny generated fixtures do not regress into unexpectedly slow conversions.\n\n## When to Change the Fixture Set\n\nUpdate the generated assets when:\n\n- you add support for a new preprocessable format\n- you change CMYK or colorspace handling in a way that should be locked down by a real fixture\n- you discover a real-world conversion regression that a small generated file can reproduce reliably\n\nWhen you add or change assets, update all three layers together:\n\n1. `scripts/setup-test-images`\n2. `backend/tests/test_image_conversion_real.py`\n3. the generated manifest or any related inventory description that the script emits\n\nDo not treat the assets as static binaries that should be edited by hand.\n\n## Troubleshooting\n\n### Assets Missing\n\nIf the fixtures are missing, rerun:\n\n```bash\n./scripts/setup-test-images\n```\n\nThe test module can generate them automatically, but explicit generation is usually the fastest way to confirm the local environment is healthy.\n\n### Imagemagick Missing\n\nThe generator expects ImageMagick 7 with the supported wrapper path or binary on `PATH`.\n\nIf the script reports that `magick` is missing, run the repo's supported system-dependency setup first:\n\n```bash\n./scripts/install-system-deps\n```\n\n### Color Mismatches\n\nIf color assertions change unexpectedly:\n\n- verify that the local environment still has the expected ImageMagick and ICC-profile support\n- check whether the backend conversion path changed intentionally\n- compare the actual average color output from the failing test before changing tolerances or expected values\n\nDo not update expected colors casually. CMYK expectations in particular exist to catch exactly that sort of silent behavior drift.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Image Conversion Test Assets\"\n+++\n\nSambee uses generated image fixtures to test the image-conversion and preprocessing pipeline without bloating the repository with large checked-in binaries.\n\nThese fixtures exist to verify real conversion behavior, especially around colorspace handling where naive expectations are often wrong.\n\n## Why These Assets Exist\n\nThe backend conversion pipeline has to do more than just decode files successfully.\n\n- CMYK inputs must convert into browser-safe RGB output without silent inversion or broken ICC handling\n- RGB inputs should preserve color rather than drifting during conversion\n- preprocessable vector formats such as EPS and AI need realistic fixtures, not only mocked unit tests\n- grayscale and Lab examples protect less-common conversion paths\n\nThat is why the repo includes a generated fixture workflow instead of relying only on synthetic unit-level mocks.\n\n## Where the Generated Assets Live\n\nThe generation workflow populates `backend/tests/test_data/`.\n\nCurrent layout:\n\n- `backend/tests/test_data/images/cmyk/`\n- `backend/tests/test_data/images/rgb/`\n- `backend/tests/test_data/images/special/`\n- `backend/tests/test_data/expected/`\n- `backend/tests/test_data/metadata/manifest.json`\n- `backend/tests/test_data/.gitignore`\n\nThe generated image set is intentionally small.\n\n- 4 CMYK fixtures\n- 4 RGB fixtures\n- 2 special-colorspace fixtures\n\nThose ten files are enough to exercise the main conversion and preprocessing paths without turning the repo into an asset dump.\n\n## What the Current Fixture Set Covers\n\n### CMYK Fixtures\n\nThe CMYK set covers:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThese are the highest-value fixtures because CMYK conversion is where incorrect assumptions are most likely.\n\nImportant rule: CMYK inputs do not convert to the naive pure RGB values contributors often expect.\n\nExamples from the real tests:\n\n- CMYK cyan does not become pure `(0, 255, 255)`\n- CMYK magenta does not become pure `(255, 0, 255)`\n- CMYK yellow does not become pure `(255, 255, 0)`\n- CMYK black does not become pure `(0, 0, 0)`\n\nThe expected values in `backend/tests/test_image_conversion_real.py` reflect real ICC-profile conversion output, and those test expectations are the current source of truth for assertion behavior.\n\n### RGB Fixtures\n\nThe RGB set verifies that already-browser-friendly color inputs do not get unintentionally altered during conversion.\n\nThose fixtures cover:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThe expectation there is preservation rather than major transformation.\n\n### Special Colorspaces\n\nThe special set currently includes:\n\n- grayscale PSD\n- Lab TIFF\n\nThese protect lesser-used but still important conversion paths.\n\n## How the Assets Are Generated\n\nThe supported entry point is:\n\n```bash\n./scripts/setup-test-images\n```\n\nThat script:\n\n- creates the test-data directory structure\n- generates raster fixtures with ImageMagick\n- generates EPS and AI fixtures with hand-crafted PostScript instead of relying on ImageMagick to produce trustworthy CMYK vector output\n- writes `metadata/manifest.json`\n- writes `backend/tests/test_data/.gitignore` so the generated artifacts do not become repository noise\n\nThe vector-generation choice is deliberate. Hand-crafted PostScript gives the tests explicit `DeviceCMYK` or `DeviceRGB` behavior that is more reliable than hoping a generic export path preserves the intended colorspace semantics.\n\n## Manifest Versus Test Assertions\n\nTreat the manifest as generated inventory metadata, not as the sole assertion source for the image-conversion tests.\n\nThe real backend assertions currently live in `backend/tests/test_image_conversion_real.py`, including:\n\n- colorspace expectations\n- color-distance tolerances\n- converter-path expectations such as preprocessor usage\n\nThat distinction matters because fixture metadata can drift if contributors update the script but forget the test semantics, or vice versa.\n\n## How the Tests Use the Assets\n\nThe main integration coverage lives in `backend/tests/test_image_conversion_real.py`.\n\nThat file:\n\n- auto-generates the fixtures through an autouse module-scoped fixture when they are missing\n- loads the generated manifest for iteration over the asset set\n- uses `pyvips` to inspect colorspace and average color values\n- verifies conversion output from `convert_image_for_viewer(...)`\n- checks preprocessable formats through `PreprocessorRegistry`\n\nThe tests are marked as integration tests because they exercise real decoding and conversion behavior rather than only mocked internals.\n\n## Supported Commands\n\nTo generate the assets explicitly:\n\n```bash\n./scripts/setup-test-images\n```\n\nTo run the real image-conversion integration suite:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -v\n```\n\nTo focus on CMYK behavior:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -k cmyk -v\n```\n\nTo pair the tests with backend coverage for the conversion service:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py --cov=app/services/image_converter\n```\n\n## Tolerances and Performance Expectations\n\nThe current suite intentionally allows some color-distance tolerance.\n\n- CMYK conversion assertions allow wider tolerance because ICC-based conversion is not a byte-for-byte identity transform\n- RGB preservation assertions use tighter thresholds because the expected result is much closer to the source color intent\n\nThe same suite also keeps a simple performance guard so tiny generated fixtures do not regress into unexpectedly slow conversions.\n\n## When to Change the Fixture Set\n\nUpdate the generated assets when:\n\n- you add support for a new preprocessable format\n- you change CMYK or colorspace handling in a way that should be locked down by a real fixture\n- you discover a real-world conversion regression that a small generated file can reproduce reliably\n\nWhen you add or change assets, update all three layers together:\n\n1. `scripts/setup-test-images`\n2. `backend/tests/test_image_conversion_real.py`\n3. the generated manifest or any related inventory description that the script emits\n\nDo not treat the assets as static binaries that should be edited by hand.\n\n## Troubleshooting\n\n### Assets Missing\n\nIf the fixtures are missing, rerun:\n\n```bash\n./scripts/setup-test-images\n```\n\nThe test module can generate them automatically, but explicit generation is usually the fastest way to confirm the local environment is healthy.\n\n### Imagemagick Missing\n\nThe generator expects ImageMagick 7 with the supported wrapper path or binary on `PATH`.\n\nIf the script reports that `magick` is missing, run the repo's supported system-dependency setup first:\n\n```bash\n./scripts/install-system-deps\n```\n\n### Color Mismatches\n\nIf color assertions change unexpectedly:\n\n- verify that the local environment still has the expected ImageMagick and ICC-profile support\n- check whether the backend conversion path changed intentionally\n- compare the actual average color output from the failing test before changing tolerances or expected values\n\nDo not update expected colors casually. CMYK expectations in particular exist to catch exactly that sort of silent behavior drift.\n", "0.8": "+++\ntitle = \"Image Conversion Test Assets\"\n+++\n\nSambee uses generated image fixtures to test the image-conversion and preprocessing pipeline without bloating the repository with large checked-in binaries.\n\nThese fixtures exist to verify real conversion behavior, especially around colorspace handling where naive expectations are often wrong.\n\n## Why These Assets Exist\n\nThe backend conversion pipeline has to do more than just decode files successfully.\n\n- CMYK inputs must convert into browser-safe RGB output without silent inversion or broken ICC handling\n- RGB inputs should preserve color rather than drifting during conversion\n- preprocessable vector formats such as EPS and AI need realistic fixtures, not only mocked unit tests\n- grayscale and Lab examples protect less-common conversion paths\n\nThat is why the repo includes a generated fixture workflow instead of relying only on synthetic unit-level mocks.\n\n## Where the Generated Assets Live\n\nThe generation workflow populates `backend/tests/test_data/`.\n\nCurrent layout:\n\n- `backend/tests/test_data/images/cmyk/`\n- `backend/tests/test_data/images/rgb/`\n- `backend/tests/test_data/images/special/`\n- `backend/tests/test_data/expected/`\n- `backend/tests/test_data/metadata/manifest.json`\n- `backend/tests/test_data/.gitignore`\n\nThe generated image set is intentionally small.\n\n- 4 CMYK fixtures\n- 4 RGB fixtures\n- 2 special-colorspace fixtures\n\nThose ten files are enough to exercise the main conversion and preprocessing paths without turning the repo into an asset dump.\n\n## What the Current Fixture Set Covers\n\n### CMYK Fixtures\n\nThe CMYK set covers:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThese are the highest-value fixtures because CMYK conversion is where incorrect assumptions are most likely.\n\nImportant rule: CMYK inputs do not convert to the naive pure RGB values contributors often expect.\n\nExamples from the real tests:\n\n- CMYK cyan does not become pure `(0, 255, 255)`\n- CMYK magenta does not become pure `(255, 0, 255)`\n- CMYK yellow does not become pure `(255, 255, 0)`\n- CMYK black does not become pure `(0, 0, 0)`\n\nThe expected values in `backend/tests/test_image_conversion_real.py` reflect real ICC-profile conversion output, and those test expectations are the current source of truth for assertion behavior.\n\n### RGB Fixtures\n\nThe RGB set verifies that already-browser-friendly color inputs do not get unintentionally altered during conversion.\n\nThose fixtures cover:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThe expectation there is preservation rather than major transformation.\n\n### Special Colorspaces\n\nThe special set currently includes:\n\n- grayscale PSD\n- Lab TIFF\n\nThese protect lesser-used but still important conversion paths.\n\n## How the Assets Are Generated\n\nThe supported entry point is:\n\n```bash\n./scripts/setup-test-images\n```\n\nThat script:\n\n- creates the test-data directory structure\n- generates raster fixtures with ImageMagick\n- generates EPS and AI fixtures with hand-crafted PostScript instead of relying on ImageMagick to produce trustworthy CMYK vector output\n- writes `metadata/manifest.json`\n- writes `backend/tests/test_data/.gitignore` so the generated artifacts do not become repository noise\n\nThe vector-generation choice is deliberate. Hand-crafted PostScript gives the tests explicit `DeviceCMYK` or `DeviceRGB` behavior that is more reliable than hoping a generic export path preserves the intended colorspace semantics.\n\n## Manifest Versus Test Assertions\n\nTreat the manifest as generated inventory metadata, not as the sole assertion source for the image-conversion tests.\n\nThe real backend assertions currently live in `backend/tests/test_image_conversion_real.py`, including:\n\n- colorspace expectations\n- color-distance tolerances\n- converter-path expectations such as preprocessor usage\n\nThat distinction matters because fixture metadata can drift if contributors update the script but forget the test semantics, or vice versa.\n\n## How the Tests Use the Assets\n\nThe main integration coverage lives in `backend/tests/test_image_conversion_real.py`.\n\nThat file:\n\n- auto-generates the fixtures through an autouse module-scoped fixture when they are missing\n- loads the generated manifest for iteration over the asset set\n- uses `pyvips` to inspect colorspace and average color values\n- verifies conversion output from `convert_image_for_viewer(...)`\n- checks preprocessable formats through `PreprocessorRegistry`\n\nThe tests are marked as integration tests because they exercise real decoding and conversion behavior rather than only mocked internals.\n\n## Supported Commands\n\nTo generate the assets explicitly:\n\n```bash\n./scripts/setup-test-images\n```\n\nTo run the real image-conversion integration suite:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -v\n```\n\nTo focus on CMYK behavior:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -k cmyk -v\n```\n\nTo pair the tests with backend coverage for the conversion service:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py --cov=app/services/image_converter\n```\n\n## Tolerances and Performance Expectations\n\nThe current suite intentionally allows some color-distance tolerance.\n\n- CMYK conversion assertions allow wider tolerance because ICC-based conversion is not a byte-for-byte identity transform\n- RGB preservation assertions use tighter thresholds because the expected result is much closer to the source color intent\n\nThe same suite also keeps a simple performance guard so tiny generated fixtures do not regress into unexpectedly slow conversions.\n\n## When to Change the Fixture Set\n\nUpdate the generated assets when:\n\n- you add support for a new preprocessable format\n- you change CMYK or colorspace handling in a way that should be locked down by a real fixture\n- you discover a real-world conversion regression that a small generated file can reproduce reliably\n\nWhen you add or change assets, update all three layers together:\n\n1. `scripts/setup-test-images`\n2. `backend/tests/test_image_conversion_real.py`\n3. the generated manifest or any related inventory description that the script emits\n\nDo not treat the assets as static binaries that should be edited by hand.\n\n## Troubleshooting\n\n### Assets Missing\n\nIf the fixtures are missing, rerun:\n\n```bash\n./scripts/setup-test-images\n```\n\nThe test module can generate them automatically, but explicit generation is usually the fastest way to confirm the local environment is healthy.\n\n### Imagemagick Missing\n\nThe generator expects ImageMagick 7 with the supported wrapper path or binary on `PATH`.\n\nIf the script reports that `magick` is missing, run the repo's supported system-dependency setup first:\n\n```bash\n./scripts/install-system-deps\n```\n\n### Color Mismatches\n\nIf color assertions change unexpectedly:\n\n- verify that the local environment still has the expected ImageMagick and ICC-profile support\n- check whether the backend conversion path changed intentionally\n- compare the actual average color output from the failing test before changing tolerances or expected values\n\nDo not update expected colors casually. CMYK expectations in particular exist to catch exactly that sort of silent behavior drift.\n", "0.9": "+++\ntitle = \"Image Conversion Test Assets\"\n+++\n\nSambee uses generated image fixtures to test the image-conversion and preprocessing pipeline without bloating the repository with large checked-in binaries.\n\nThese fixtures exist to verify real conversion behavior, especially around colorspace handling where naive expectations are often wrong.\n\n## Why These Assets Exist\n\nThe backend conversion pipeline has to do more than just decode files successfully.\n\n- CMYK inputs must convert into browser-safe RGB output without silent inversion or broken ICC handling\n- RGB inputs should preserve color rather than drifting during conversion\n- preprocessable vector formats such as EPS and AI need realistic fixtures, not only mocked unit tests\n- grayscale and Lab examples protect less-common conversion paths\n\nThat is why the repo includes a generated fixture workflow instead of relying only on synthetic unit-level mocks.\n\n## Where the Generated Assets Live\n\nThe generation workflow populates `backend/tests/test_data/`.\n\nCurrent layout:\n\n- `backend/tests/test_data/images/cmyk/`\n- `backend/tests/test_data/images/rgb/`\n- `backend/tests/test_data/images/special/`\n- `backend/tests/test_data/expected/`\n- `backend/tests/test_data/metadata/manifest.json`\n- `backend/tests/test_data/.gitignore`\n\nThe generated image set is intentionally small.\n\n- 4 CMYK fixtures\n- 4 RGB fixtures\n- 2 special-colorspace fixtures\n\nThose ten files are enough to exercise the main conversion and preprocessing paths without turning the repo into an asset dump.\n\n## What the Current Fixture Set Covers\n\n### CMYK Fixtures\n\nThe CMYK set covers:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThese are the highest-value fixtures because CMYK conversion is where incorrect assumptions are most likely.\n\nImportant rule: CMYK inputs do not convert to the naive pure RGB values contributors often expect.\n\nExamples from the real tests:\n\n- CMYK cyan does not become pure `(0, 255, 255)`\n- CMYK magenta does not become pure `(255, 0, 255)`\n- CMYK yellow does not become pure `(255, 255, 0)`\n- CMYK black does not become pure `(0, 0, 0)`\n\nThe expected values in `backend/tests/test_image_conversion_real.py` reflect real ICC-profile conversion output, and those test expectations are the current source of truth for assertion behavior.\n\n### RGB Fixtures\n\nThe RGB set verifies that already-browser-friendly color inputs do not get unintentionally altered during conversion.\n\nThose fixtures cover:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThe expectation there is preservation rather than major transformation.\n\n### Special Colorspaces\n\nThe special set currently includes:\n\n- grayscale PSD\n- Lab TIFF\n\nThese protect lesser-used but still important conversion paths.\n\n## How the Assets Are Generated\n\nThe supported entry point is:\n\n```bash\n./scripts/setup-test-images\n```\n\nThat script:\n\n- creates the test-data directory structure\n- generates raster fixtures with ImageMagick\n- generates EPS and AI fixtures with hand-crafted PostScript instead of relying on ImageMagick to produce trustworthy CMYK vector output\n- writes `metadata/manifest.json`\n- writes `backend/tests/test_data/.gitignore` so the generated artifacts do not become repository noise\n\nThe vector-generation choice is deliberate. Hand-crafted PostScript gives the tests explicit `DeviceCMYK` or `DeviceRGB` behavior that is more reliable than hoping a generic export path preserves the intended colorspace semantics.\n\n## Manifest Versus Test Assertions\n\nTreat the manifest as generated inventory metadata, not as the sole assertion source for the image-conversion tests.\n\nThe real backend assertions currently live in `backend/tests/test_image_conversion_real.py`, including:\n\n- colorspace expectations\n- color-distance tolerances\n- converter-path expectations such as preprocessor usage\n\nThat distinction matters because fixture metadata can drift if contributors update the script but forget the test semantics, or vice versa.\n\n## How the Tests Use the Assets\n\nThe main integration coverage lives in `backend/tests/test_image_conversion_real.py`.\n\nThat file:\n\n- auto-generates the fixtures through an autouse module-scoped fixture when they are missing\n- loads the generated manifest for iteration over the asset set\n- uses `pyvips` to inspect colorspace and average color values\n- verifies conversion output from `convert_image_for_viewer(...)`\n- checks preprocessable formats through `PreprocessorRegistry`\n\nThe tests are marked as integration tests because they exercise real decoding and conversion behavior rather than only mocked internals.\n\n## Supported Commands\n\nTo generate the assets explicitly:\n\n```bash\n./scripts/setup-test-images\n```\n\nTo run the real image-conversion integration suite:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -v\n```\n\nTo focus on CMYK behavior:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -k cmyk -v\n```\n\nTo pair the tests with backend coverage for the conversion service:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py --cov=app/services/image_converter\n```\n\n## Tolerances and Performance Expectations\n\nThe current suite intentionally allows some color-distance tolerance.\n\n- CMYK conversion assertions allow wider tolerance because ICC-based conversion is not a byte-for-byte identity transform\n- RGB preservation assertions use tighter thresholds because the expected result is much closer to the source color intent\n\nThe same suite also keeps a simple performance guard so tiny generated fixtures do not regress into unexpectedly slow conversions.\n\n## When to Change the Fixture Set\n\nUpdate the generated assets when:\n\n- you add support for a new preprocessable format\n- you change CMYK or colorspace handling in a way that should be locked down by a real fixture\n- you discover a real-world conversion regression that a small generated file can reproduce reliably\n\nWhen you add or change assets, update all three layers together:\n\n1. `scripts/setup-test-images`\n2. `backend/tests/test_image_conversion_real.py`\n3. the generated manifest or any related inventory description that the script emits\n\nDo not treat the assets as static binaries that should be edited by hand.\n\n## Troubleshooting\n\n### Assets Missing\n\nIf the fixtures are missing, rerun:\n\n```bash\n./scripts/setup-test-images\n```\n\nThe test module can generate them automatically, but explicit generation is usually the fastest way to confirm the local environment is healthy.\n\n### Imagemagick Missing\n\nThe generator expects ImageMagick 7 with the supported wrapper path or binary on `PATH`.\n\nIf the script reports that `magick` is missing, run the repo's supported system-dependency setup first:\n\n```bash\n./scripts/install-system-deps\n```\n\n### Color Mismatches\n\nIf color assertions change unexpectedly:\n\n- verify that the local environment still has the expected ImageMagick and ICC-profile support\n- check whether the backend conversion path changed intentionally\n- compare the actual average color output from the failing test before changing tolerances or expected values\n\nDo not update expected colors casually. CMYK expectations in particular exist to catch exactly that sort of silent behavior drift.\n", "1.0": "+++\ntitle = \"Image Conversion Test Assets\"\n+++\n\nSambee uses generated image fixtures to test the image-conversion and preprocessing pipeline without bloating the repository with large checked-in binaries.\n\nThese fixtures exist to verify real conversion behavior, especially around colorspace handling where naive expectations are often wrong.\n\n## Why These Assets Exist\n\nThe backend conversion pipeline has to do more than just decode files successfully.\n\n- CMYK inputs must convert into browser-safe RGB output without silent inversion or broken ICC handling\n- RGB inputs should preserve color rather than drifting during conversion\n- preprocessable vector formats such as EPS and AI need realistic fixtures, not only mocked unit tests\n- grayscale and Lab examples protect less-common conversion paths\n\nThat is why the repo includes a generated fixture workflow instead of relying only on synthetic unit-level mocks.\n\n## Where the Generated Assets Live\n\nThe generation workflow populates `backend/tests/test_data/`.\n\nCurrent layout:\n\n- `backend/tests/test_data/images/cmyk/`\n- `backend/tests/test_data/images/rgb/`\n- `backend/tests/test_data/images/special/`\n- `backend/tests/test_data/expected/`\n- `backend/tests/test_data/metadata/manifest.json`\n- `backend/tests/test_data/.gitignore`\n\nThe generated image set is intentionally small.\n\n- 4 CMYK fixtures\n- 4 RGB fixtures\n- 2 special-colorspace fixtures\n\nThose ten files are enough to exercise the main conversion and preprocessing paths without turning the repo into an asset dump.\n\n## What the Current Fixture Set Covers\n\n### CMYK Fixtures\n\nThe CMYK set covers:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThese are the highest-value fixtures because CMYK conversion is where incorrect assumptions are most likely.\n\nImportant rule: CMYK inputs do not convert to the naive pure RGB values contributors often expect.\n\nExamples from the real tests:\n\n- CMYK cyan does not become pure `(0, 255, 255)`\n- CMYK magenta does not become pure `(255, 0, 255)`\n- CMYK yellow does not become pure `(255, 255, 0)`\n- CMYK black does not become pure `(0, 0, 0)`\n\nThe expected values in `backend/tests/test_image_conversion_real.py` reflect real ICC-profile conversion output, and those test expectations are the current source of truth for assertion behavior.\n\n### RGB Fixtures\n\nThe RGB set verifies that already-browser-friendly color inputs do not get unintentionally altered during conversion.\n\nThose fixtures cover:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThe expectation there is preservation rather than major transformation.\n\n### Special Colorspaces\n\nThe special set currently includes:\n\n- grayscale PSD\n- Lab TIFF\n\nThese protect lesser-used but still important conversion paths.\n\n## How the Assets Are Generated\n\nThe supported entry point is:\n\n```bash\n./scripts/setup-test-images\n```\n\nThat script:\n\n- creates the test-data directory structure\n- generates raster fixtures with ImageMagick\n- generates EPS and AI fixtures with hand-crafted PostScript instead of relying on ImageMagick to produce trustworthy CMYK vector output\n- writes `metadata/manifest.json`\n- writes `backend/tests/test_data/.gitignore` so the generated artifacts do not become repository noise\n\nThe vector-generation choice is deliberate. Hand-crafted PostScript gives the tests explicit `DeviceCMYK` or `DeviceRGB` behavior that is more reliable than hoping a generic export path preserves the intended colorspace semantics.\n\n## Manifest Versus Test Assertions\n\nTreat the manifest as generated inventory metadata, not as the sole assertion source for the image-conversion tests.\n\nThe real backend assertions currently live in `backend/tests/test_image_conversion_real.py`, including:\n\n- colorspace expectations\n- color-distance tolerances\n- converter-path expectations such as preprocessor usage\n\nThat distinction matters because fixture metadata can drift if contributors update the script but forget the test semantics, or vice versa.\n\n## How the Tests Use the Assets\n\nThe main integration coverage lives in `backend/tests/test_image_conversion_real.py`.\n\nThat file:\n\n- auto-generates the fixtures through an autouse module-scoped fixture when they are missing\n- loads the generated manifest for iteration over the asset set\n- uses `pyvips` to inspect colorspace and average color values\n- verifies conversion output from `convert_image_for_viewer(...)`\n- checks preprocessable formats through `PreprocessorRegistry`\n\nThe tests are marked as integration tests because they exercise real decoding and conversion behavior rather than only mocked internals.\n\n## Supported Commands\n\nTo generate the assets explicitly:\n\n```bash\n./scripts/setup-test-images\n```\n\nTo run the real image-conversion integration suite:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -v\n```\n\nTo focus on CMYK behavior:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -k cmyk -v\n```\n\nTo pair the tests with backend coverage for the conversion service:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py --cov=app/services/image_converter\n```\n\n## Tolerances and Performance Expectations\n\nThe current suite intentionally allows some color-distance tolerance.\n\n- CMYK conversion assertions allow wider tolerance because ICC-based conversion is not a byte-for-byte identity transform\n- RGB preservation assertions use tighter thresholds because the expected result is much closer to the source color intent\n\nThe same suite also keeps a simple performance guard so tiny generated fixtures do not regress into unexpectedly slow conversions.\n\n## When to Change the Fixture Set\n\nUpdate the generated assets when:\n\n- you add support for a new preprocessable format\n- you change CMYK or colorspace handling in a way that should be locked down by a real fixture\n- you discover a real-world conversion regression that a small generated file can reproduce reliably\n\nWhen you add or change assets, update all three layers together:\n\n1. `scripts/setup-test-images`\n2. `backend/tests/test_image_conversion_real.py`\n3. the generated manifest or any related inventory description that the script emits\n\nDo not treat the assets as static binaries that should be edited by hand.\n\n## Troubleshooting\n\n### Assets Missing\n\nIf the fixtures are missing, rerun:\n\n```bash\n./scripts/setup-test-images\n```\n\nThe test module can generate them automatically, but explicit generation is usually the fastest way to confirm the local environment is healthy.\n\n### Imagemagick Missing\n\nThe generator expects ImageMagick 7 with the supported wrapper path or binary on `PATH`.\n\nIf the script reports that `magick` is missing, run the repo's supported system-dependency setup first:\n\n```bash\n./scripts/install-system-deps\n```\n\n### Color Mismatches\n\nIf color assertions change unexpectedly:\n\n- verify that the local environment still has the expected ImageMagick and ICC-profile support\n- check whether the backend conversion path changed intentionally\n- compare the actual average color output from the failing test before changing tolerances or expected values\n\nDo not update expected colors casually. CMYK expectations in particular exist to catch exactly that sort of silent behavior drift.\n", "2.0": "+++\ntitle = \"Image Conversion Test Assets\"\n+++\n\nSambee uses generated image fixtures to test the image-conversion and preprocessing pipeline without bloating the repository with large checked-in binaries.\n\nThese fixtures exist to verify real conversion behavior, especially around colorspace handling where naive expectations are often wrong.\n\n## Why These Assets Exist\n\nThe backend conversion pipeline has to do more than just decode files successfully.\n\n- CMYK inputs must convert into browser-safe RGB output without silent inversion or broken ICC handling\n- RGB inputs should preserve color rather than drifting during conversion\n- preprocessable vector formats such as EPS and AI need realistic fixtures, not only mocked unit tests\n- grayscale and Lab examples protect less-common conversion paths\n\nThat is why the repo includes a generated fixture workflow instead of relying only on synthetic unit-level mocks.\n\n## Where the Generated Assets Live\n\nThe generation workflow populates `backend/tests/test_data/`.\n\nCurrent layout:\n\n- `backend/tests/test_data/images/cmyk/`\n- `backend/tests/test_data/images/rgb/`\n- `backend/tests/test_data/images/special/`\n- `backend/tests/test_data/expected/`\n- `backend/tests/test_data/metadata/manifest.json`\n- `backend/tests/test_data/.gitignore`\n\nThe generated image set is intentionally small.\n\n- 4 CMYK fixtures\n- 4 RGB fixtures\n- 2 special-colorspace fixtures\n\nThose ten files are enough to exercise the main conversion and preprocessing paths without turning the repo into an asset dump.\n\n## What the Current Fixture Set Covers\n\n### CMYK Fixtures\n\nThe CMYK set covers:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThese are the highest-value fixtures because CMYK conversion is where incorrect assumptions are most likely.\n\nImportant rule: CMYK inputs do not convert to the naive pure RGB values contributors often expect.\n\nExamples from the real tests:\n\n- CMYK cyan does not become pure `(0, 255, 255)`\n- CMYK magenta does not become pure `(255, 0, 255)`\n- CMYK yellow does not become pure `(255, 255, 0)`\n- CMYK black does not become pure `(0, 0, 0)`\n\nThe expected values in `backend/tests/test_image_conversion_real.py` reflect real ICC-profile conversion output, and those test expectations are the current source of truth for assertion behavior.\n\n### RGB Fixtures\n\nThe RGB set verifies that already-browser-friendly color inputs do not get unintentionally altered during conversion.\n\nThose fixtures cover:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThe expectation there is preservation rather than major transformation.\n\n### Special Colorspaces\n\nThe special set currently includes:\n\n- grayscale PSD\n- Lab TIFF\n\nThese protect lesser-used but still important conversion paths.\n\n## How the Assets Are Generated\n\nThe supported entry point is:\n\n```bash\n./scripts/setup-test-images\n```\n\nThat script:\n\n- creates the test-data directory structure\n- generates raster fixtures with ImageMagick\n- generates EPS and AI fixtures with hand-crafted PostScript instead of relying on ImageMagick to produce trustworthy CMYK vector output\n- writes `metadata/manifest.json`\n- writes `backend/tests/test_data/.gitignore` so the generated artifacts do not become repository noise\n\nThe vector-generation choice is deliberate. Hand-crafted PostScript gives the tests explicit `DeviceCMYK` or `DeviceRGB` behavior that is more reliable than hoping a generic export path preserves the intended colorspace semantics.\n\n## Manifest Versus Test Assertions\n\nTreat the manifest as generated inventory metadata, not as the sole assertion source for the image-conversion tests.\n\nThe real backend assertions currently live in `backend/tests/test_image_conversion_real.py`, including:\n\n- colorspace expectations\n- color-distance tolerances\n- converter-path expectations such as preprocessor usage\n\nThat distinction matters because fixture metadata can drift if contributors update the script but forget the test semantics, or vice versa.\n\n## How the Tests Use the Assets\n\nThe main integration coverage lives in `backend/tests/test_image_conversion_real.py`.\n\nThat file:\n\n- auto-generates the fixtures through an autouse module-scoped fixture when they are missing\n- loads the generated manifest for iteration over the asset set\n- uses `pyvips` to inspect colorspace and average color values\n- verifies conversion output from `convert_image_for_viewer(...)`\n- checks preprocessable formats through `PreprocessorRegistry`\n\nThe tests are marked as integration tests because they exercise real decoding and conversion behavior rather than only mocked internals.\n\n## Supported Commands\n\nTo generate the assets explicitly:\n\n```bash\n./scripts/setup-test-images\n```\n\nTo run the real image-conversion integration suite:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -v\n```\n\nTo focus on CMYK behavior:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -k cmyk -v\n```\n\nTo pair the tests with backend coverage for the conversion service:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py --cov=app/services/image_converter\n```\n\n## Tolerances and Performance Expectations\n\nThe current suite intentionally allows some color-distance tolerance.\n\n- CMYK conversion assertions allow wider tolerance because ICC-based conversion is not a byte-for-byte identity transform\n- RGB preservation assertions use tighter thresholds because the expected result is much closer to the source color intent\n\nThe same suite also keeps a simple performance guard so tiny generated fixtures do not regress into unexpectedly slow conversions.\n\n## When to Change the Fixture Set\n\nUpdate the generated assets when:\n\n- you add support for a new preprocessable format\n- you change CMYK or colorspace handling in a way that should be locked down by a real fixture\n- you discover a real-world conversion regression that a small generated file can reproduce reliably\n\nWhen you add or change assets, update all three layers together:\n\n1. `scripts/setup-test-images`\n2. `backend/tests/test_image_conversion_real.py`\n3. the generated manifest or any related inventory description that the script emits\n\nDo not treat the assets as static binaries that should be edited by hand.\n\n## Troubleshooting\n\n### Assets Missing\n\nIf the fixtures are missing, rerun:\n\n```bash\n./scripts/setup-test-images\n```\n\nThe test module can generate them automatically, but explicit generation is usually the fastest way to confirm the local environment is healthy.\n\n### Imagemagick Missing\n\nThe generator expects ImageMagick 7 with the supported wrapper path or binary on `PATH`.\n\nIf the script reports that `magick` is missing, run the repo's supported system-dependency setup first:\n\n```bash\n./scripts/install-system-deps\n```\n\n### Color Mismatches\n\nIf color assertions change unexpectedly:\n\n- verify that the local environment still has the expected ImageMagick and ICC-profile support\n- check whether the backend conversion path changed intentionally\n- compare the actual average color output from the failing test before changing tolerances or expected values\n\nDo not update expected colors casually. CMYK expectations in particular exist to catch exactly that sort of silent behavior drift.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/testing-and-quality-gates/ci-workflows-and-repository-automation", "parent_id": "section:developer-guide/testing-and-quality-gates", "depth": 2, "kind": "page", "label": "ci-workflows-and-repository-automation", "title": "Ci Workflows And Repository Automation", "path": "developer-guide/testing-and-quality-gates/ci-workflows-and-repository-automation", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "branched", "source_version": "0.7", "diff_added": 26, "diff_removed": 2}, "0.9": {"state": "branched", "source_version": "0.8", "diff_added": 15, "diff_removed": 1}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "branched", "source_version": "0.9", "diff_added": 10, "diff_removed": 0}}, "content_versions": {"0.7": "+++\ntitle = \"CI Workflows and Repository Automation\"\n+++\n\nUse this page to understand the GitHub Actions workflows contributors hit most often and to keep the workflow list grouped predictably in the GitHub UI.\n\n## Naming Convention\n\nGitHub lists workflows by the top-level `name` field.\n\nSambee groups workflow display names by operational purpose using `Area: Subject`.\n\nCurrent workflow groups are:\n\n- `CI`.\n- `Release`.\n- `Deploy`.\n- `Security`.\n- `Admin`.\n\nKeep new names short, stable, and grouped by what the workflow does rather than by how it is triggered.\n\n## Workflow Map\n\n| Display name | File | Role |\n|---|---|---|\n| `CI: Test` | `.github/workflows/test.yml` | Runs the main backend, frontend, and companion validation suites. |\n| `CI: Lint` | `.github/workflows/lint.yml` | Runs repository lint and formatting checks across backend, frontend, and companion. |\n| `CI: Check Backend Lockfiles` | `.github/workflows/check-backend-lockfiles.yml` | Verifies that committed backend lockfiles still match the reviewed requirement sources. |\n| `CI: Validate Docker Image` | `.github/workflows/docker-image-validate.yml` | Builds and smoke-tests the production container image on pull requests, pushes, and manual runs. |\n| `Release: Publish Docker Image` | `.github/workflows/docker-image-publish.yml` | Promotes an existing preview candidate onto release tags and the `stable` or `beta` channel, then signs the digest. |\n| `Release: Create Docker Image` | `.github/workflows/docker-image-preview-publish.yml` | Builds, validates, publishes, and signs a new preview image, forcing a fresh Debian package-layer rebuild for that run before moving the `test` channel tag. |\n| `Maintenance: Backfill Docker Release Tags` | `.github/workflows/docker-image-backfill.yml` | Reattaches release tags and release-channel aliases to an already published candidate digest for an existing release. |\n| `Maintenance: Clean Up Docker Package Versions` | `.github/workflows/docker-image-cleanup.yml` | Removes unprotected SHA-tagged preview GHCR package versions, prunes stale signature artifacts, and deletes unreferenced untagged package versions while preserving release-tagged and channel-protected versions including `test`. |\n| `Release: Build Companion Artifact` | `.github/workflows/build-companion.yml` | Builds companion release artifacts for a new unique version or prerelease candidate in the public distribution repository. |\n| `Release: Promote Companion Release` | `.github/workflows/promote-companion-release.yml` | Moves an existing companion release onto one or more update channels. |\n| `Deploy: Website` | `.github/workflows/website-deploy.yml` | Builds the website and deploys `website/public/` to Cloudflare Pages. |\n| `Security: Dependency Audit` | `.github/workflows/dependency-security.yml` | Runs scheduled and manual dependency vulnerability audits. |\n| `Security: Docker Image Scan` | `.github/workflows/docker-image-security-scan.yml` | Builds the current main image, forces a fresh Debian package-layer rebuild for that run, and scans it for newly disclosed vulnerabilities. |\n| `Admin: Sync Labels` | `.github/workflows/sync-labels.yml` | Synchronizes repository labels from `.github/labels.yml` without deleting unmanaged labels. |\n\nGitHub also shows repository-level features such as `Dependabot updates` and `Dependency graph`.\n\nThose are not repository workflows, so their display names are not controlled by these YAML files.\n\n## CI: Test\n\n`CI: Test` is the main validation workflow for pushes to `main`, pull requests against `main`, and manual dispatch.\n\nIt first detects which top-level product areas changed, then fans out only the relevant jobs for:\n\n- backend\n- frontend\n- companion\n\nManual dispatch runs all three areas.\n\nThe workflow ends with a single gate job so branch protection can depend on one stable required check instead of a changing set of per-area jobs.\n\nIn the backend job, regular tests run under `pytest-xdist` for throughput, while `@performance` tests run in a separate serial pass so wall-clock assertions are not distorted by parallel worker contention.\n\n### Caching Model\n\nThe test workflow uses layered caching to reduce repeated setup work while keeping dependency inputs explicit.\n\nCurrent cache layers include:\n\n- `backend/.venv` caching keyed by the resolved backend requirement files and Python version.\n- `backend/.mypy_cache` caching keyed by backend Python source changes.\n- `actions/setup-node` npm download caching for frontend and companion jobs.\n- `frontend/node_modules` caching keyed by `frontend/package-lock.json`.\n- Rust build caching for `companion/src-tauri`.\n\nTreat those cache keys as reviewed dependency inputs, not as disposable generated noise.\n\nWhen dependency manifests or lockfiles change, commit the corresponding lockfile updates in the same pull request so cache invalidation and dependency review stay aligned.\n\n### Local Parity\n\nFor fast local iteration, use `./scripts/test`.\n\nWhen you want a closer CI-style pass, run the per-subsystem checks from [Test Strategy Overview](../test-strategy-overview/) and keep lockfile-driven installs intact.\n\n## CI: Lint\n\n`CI: Lint` applies the same change-detection pattern, then runs the repository's static checks for only the affected areas.\n\nCurrent coverage includes:\n\n- backend Ruff checks and formatting validation.\n- frontend Biome validation.\n- companion Clippy, Rustfmt, and Biome validation.\n\nThe workflow also ends with one gate job so branch protection can depend on a stable result.\n\n## Runner Distro Policy\n\nSambee does not require every GitHub Actions job to run on the same base distro.\n\nInstead, the rule is:\n\n- jobs that validate production-like runtime behavior or install native runtime dependencies should follow the same Debian family used by the production image and the dev container\n- jobs that only run language-level checks, dependency audits, repository automation, or other host-agnostic validation can stay on `ubuntu-latest`\n\nCurrent Debian-family jobs include:\n\n- the backend job in `CI: Test`\n- the `validate-tests` job in `Release: Create Docker Image`\n\nThose jobs run inside the pinned `python:3.13.12-slim` container because `scripts/install-system-deps` now requires distro-provided ImageMagick 7, while the default Ubuntu GitHub-hosted runner image still resolves `imagemagick` to ImageMagick 6.\n\nCurrent jobs that intentionally remain on `ubuntu-latest` include:\n\n- change-detection, label-sync, and website deployment workflows\n- pure Python lint, lockfile freshness, and dependency-audit workflows\n- frontend-only and companion-only validation workflows\n- Docker build, smoke-test, and vulnerability-scan workflows, where the distro-sensitive logic runs inside the built image rather than on the host runner\n\nWhen adding or changing a workflow, treat runner distro as part of the test contract whenever a job installs OS packages or validates native behavior.\n\n## CI: Check Backend Lockfiles\n\n`CI: Check Backend Lockfiles` protects the reviewed Python dependency workflow.\n\nIt runs `scripts/refresh-backend-lockfiles --check` on pushes, pull requests, and manual runs that touch backend requirement inputs, generated lockfiles, or the refresh script itself.\n\nUse this as the fast failure signal when requirement files and generated lockfiles drift apart.\n\nFor the broader dependency-update workflow, use [Dependency Update Workflow](../release-and-versioning/dependency-update-workflow/).\n\n## Admin: Sync Labels\n\n`Admin: Sync Labels` keeps repository labels aligned with `.github/labels.yml`.\n\nIt is intentionally conservative.\n\n- Dependabot-related labels should stay declared in `.github/labels.yml`.\n- The workflow uses `skip-delete: true`, so labels not declared there are left alone.\n\nThat keeps automation-owned labels deterministic without forcing the repository to delete every manually created label.\n\n## Related Workflow Docs\n\nUse the more specific pages for the workflows that have dedicated operational guidance:\n\n- [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/)\n- [Docker Release Overview](../../release-and-versioning/docker-release-overview/)\n- [Companion Release Overview](../../release-and-versioning/companion-release-overview/)\n- [Set Up Cloudflare Pages Publishing](../../../website-dev-guide/setup-and-operations/set-up-cloudflare-pages-publishing/)\n\n", "0.8": "+++\ntitle = \"CI Workflows and Repository Automation\"\n+++\n\nUse this page to understand the GitHub Actions workflows contributors hit most often and to keep the workflow list grouped predictably in the GitHub UI.\n\n## Naming Convention\n\nGitHub lists workflows by the top-level `name` field.\n\nSambee groups workflow display names by operational purpose using `Area: Subject`.\n\nCurrent workflow groups are:\n\n- `CI`.\n- `Release`.\n- `Deploy`.\n- `Security`.\n- `Admin`.\n\nKeep new names short, stable, and grouped by what the workflow does rather than by how it is triggered.\n\n## Workflow Map\n\n| Display name | File | Role |\n|---|---|---|\n| `CI: Test` | `.github/workflows/test.yml` | Runs the main backend, frontend, and companion validation suites. |\n| `CI: Lint` | `.github/workflows/lint.yml` | Runs repository lint and formatting checks across backend, frontend, and companion. |\n| `CI: Check Backend Lockfiles` | `.github/workflows/check-backend-lockfiles.yml` | Verifies that committed backend lockfiles still match the reviewed requirement sources. |\n| `CI: Validate Docker Image` | `.github/workflows/docker-image-validate.yml` | Builds and smoke-tests the production container image on pull requests, pushes, and manual runs. |\n| `Release: Publish Docker Image` | `.github/workflows/docker-image-publish.yml` | Promotes an existing preview candidate onto release tags and the `stable` or `beta` channel, then signs the digest. |\n| `Release: Create Docker Image` | `.github/workflows/docker-image-preview-publish.yml` | Builds, validates, publishes, and signs a new preview image, forcing a fresh Debian package-layer rebuild for that run before moving the `test` channel tag. |\n| `Maintenance: Backfill Docker Release Tags` | `.github/workflows/docker-image-backfill.yml` | Reattaches release tags and release-channel aliases to an already published candidate digest for an existing release. |\n| `Maintenance: Clean Up Docker Package Versions` | `.github/workflows/docker-image-cleanup.yml` | Removes unprotected SHA-tagged preview GHCR package versions, prunes stale signature artifacts, and deletes unreferenced untagged package versions while preserving release-tagged and channel-protected versions including `test`. |\n| `Release: Build Companion Artifact` | `.github/workflows/build-companion.yml` | Builds companion release artifacts for a new unique version or prerelease candidate in the public distribution repository. |\n| `Release: Promote Companion Release` | `.github/workflows/promote-companion-release.yml` | Moves an existing companion release onto one or more update channels. |\n| `Deploy: Website` | `.github/workflows/website-deploy.yml` | Builds the website and deploys `website/public/` to Cloudflare Pages. |\n| `Security: Dependency Audit` | `.github/workflows/dependency-security.yml` | Runs scheduled and manual dependency vulnerability audits. |\n| `Security: Docker Image Scan` | `.github/workflows/docker-image-security-scan.yml` | Builds the current main image, forces a fresh Debian package-layer rebuild for that run, and scans it for newly disclosed vulnerabilities. |\n| `Admin: Sync Labels` | `.github/workflows/sync-labels.yml` | Synchronizes repository labels from `.github/labels.yml` without deleting unmanaged labels. |\n\nGitHub also shows repository-level features such as `Dependabot updates` and `Dependency graph`.\n\nThose are not repository workflows, so their display names are not controlled by these YAML files.\n\n## CI: Test\n\n`CI: Test` is the main validation workflow for pushes to `main`, pull requests against `main`, and manual dispatch.\n\nIt first detects which top-level product areas changed, then fans out only the relevant jobs for:\n\n- backend\n- frontend\n- frontend Playwright Chromium smoke\n- frontend Playwright Firefox markdown coverage on pushes to `main` and manual runs\n- companion\n\nManual dispatch runs all three areas.\n\nThe workflow ends with a single gate job so branch protection can depend on one stable required check instead of a changing set of per-area jobs.\n\nIn the backend job, regular tests run under `pytest-xdist` for throughput, while `@performance` tests run in a separate serial pass so wall-clock assertions are not distorted by parallel worker contention.\n\nFor frontend coverage, the workflow is intentionally layered:\n\n- the `frontend` job keeps the fast TypeScript, lint, and Vitest checks in the main PR path\n- the `frontend-e2e` job runs a bounded Playwright Chromium smoke slice on frontend changes\n- the `frontend-e2e-firefox` job runs the markdown editor Playwright slice only on pushes to `main` and manual dispatch\n\nThat split keeps pull-request runtime under control while still protecting the browser-sensitive editing workflows that unit tests do not cover.\n\nThe current companion test job does not call `./scripts/test`.\nIt runs explicit steps for Node install, companion TypeScript type checking, and `cargo test`.\nThat means the local Windows GNU cross-check in `./scripts/test` does not currently run in `CI: Test`.\n\n### Caching Model\n\nThe test workflow uses layered caching to reduce repeated setup work while keeping dependency inputs explicit.\n\nCurrent cache layers include:\n\n- `backend/.venv` caching keyed by the resolved backend requirement files and Python version.\n- `backend/.mypy_cache` caching keyed by backend Python source changes.\n- `actions/setup-node` npm download caching for frontend and companion jobs.\n- `frontend/node_modules` caching keyed by `frontend/package-lock.json`.\n- Rust build caching for `companion/src-tauri`.\n\nTreat those cache keys as reviewed dependency inputs, not as disposable generated noise.\n\nWhen dependency manifests or lockfiles change, commit the corresponding lockfile updates in the same pull request so cache invalidation and dependency review stay aligned.\n\n### Local Parity\n\nFor fast local iteration, use `./scripts/test`.\n\nWhen you want a closer CI-style pass, run the per-subsystem checks from [Test Strategy Overview](../test-strategy-overview/) and keep lockfile-driven installs intact.\n\nFor frontend work, that usually means:\n\n- `cd frontend \u0026\u0026 npm test` for the default Vitest suite\n- `cd frontend \u0026\u0026 npm run test:e2e` for the default Chromium browser pass\n\n`./scripts/test` now includes a local companion Windows GNU target compatibility check.\nThat check is intentionally a local validation aid, not part of the current `CI: Test` workflow contract.\n\n## CI: Lint\n\n`CI: Lint` applies the same change-detection pattern, then runs the repository's static checks for only the affected areas.\n\nCurrent coverage includes:\n\n- backend Ruff checks and formatting validation.\n- frontend Biome validation.\n- companion Clippy, Rustfmt, and Biome validation.\n\nThe lint workflow does not run the local companion Windows GNU cross-check either.\nThat cross-target validation is currently a local developer workflow check, while actual Windows artifact creation remains in the release workflow.\n\nThe workflow also ends with one gate job so branch protection can depend on a stable result.\n\n## Runner Distro Policy\n\nSambee does not require every GitHub Actions job to run on the same base distro.\n\nInstead, the rule is:\n\n- jobs that validate production-like runtime behavior or install native runtime dependencies should follow the same Debian family used by the production image and the dev container\n- jobs that only run language-level checks, dependency audits, repository automation, or other host-agnostic validation can stay on `ubuntu-latest`\n\nCurrent Debian-family jobs include:\n\n- the backend job in `CI: Test`\n- the `validate-tests` job in `Release: Create Docker Image`\n\nThose jobs run inside the pinned `python:3.13.12-slim` container because `scripts/install-system-deps` now requires distro-provided ImageMagick 7, while the default Ubuntu GitHub-hosted runner image still resolves `imagemagick` to ImageMagick 6.\n\nCurrent jobs that intentionally remain on `ubuntu-latest` include:\n\n- change-detection, label-sync, and website deployment workflows\n- pure Python lint, lockfile freshness, and dependency-audit workflows\n- frontend-only and companion-only validation workflows\n- Docker build, smoke-test, and vulnerability-scan workflows, where the distro-sensitive logic runs inside the built image rather than on the host runner\n\nWhen adding or changing a workflow, treat runner distro as part of the test contract whenever a job installs OS packages or validates native behavior.\n\n## CI: Check Backend Lockfiles\n\n`CI: Check Backend Lockfiles` protects the reviewed Python dependency workflow.\n\nIt runs `scripts/refresh-backend-lockfiles --check` on pushes, pull requests, and manual runs that touch backend requirement inputs, generated lockfiles, or the refresh script itself.\n\nUse this as the fast failure signal when requirement files and generated lockfiles drift apart.\n\nFor the broader dependency-update workflow, use [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/).\n\n## Admin: Sync Labels\n\n`Admin: Sync Labels` keeps repository labels aligned with `.github/labels.yml`.\n\nIt is intentionally conservative.\n\n- Dependabot-related labels should stay declared in `.github/labels.yml`.\n- The workflow uses `skip-delete: true`, so labels not declared there are left alone.\n\nThat keeps automation-owned labels deterministic without forcing the repository to delete every manually created label.\n\n## Related Workflow Docs\n\nUse the more specific pages for the workflows that have dedicated operational guidance:\n\n- [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/)\n- [Docker Release Overview](../../release-and-versioning/docker-release-overview/)\n- [Companion Release Overview](../../release-and-versioning/companion-release-overview/)\n- [Set Up Cloudflare Pages Publishing](../../../website-dev-guide/setup-and-operations/set-up-cloudflare-pages-publishing/)\n", "0.9": "+++\ntitle = \"CI Workflows and Repository Automation\"\n+++\n\nUse this page to understand the GitHub Actions workflows contributors hit most often and to keep the workflow list grouped predictably in the GitHub UI.\n\n## Naming Convention\n\nGitHub lists workflows by the top-level `name` field.\n\nSambee groups workflow display names by operational purpose using `Area: Subject`.\n\nCurrent workflow groups are:\n\n- `CI`.\n- `Release`.\n- `Deploy`.\n- `Security`.\n- `Admin`.\n\nKeep new names short, stable, and grouped by what the workflow does rather than by how it is triggered.\n\n## Workflow Map\n\n| Display name | File | Role |\n|---|---|---|\n| `CI: Test` | `.github/workflows/test.yml` | Runs the main backend, frontend, and companion validation suites. |\n| `CI: Lint` | `.github/workflows/lint.yml` | Runs repository lint and formatting checks across backend, frontend, and companion. |\n| `CI: Check Backend Lockfiles` | `.github/workflows/check-backend-lockfiles.yml` | Verifies that committed backend lockfiles still match the reviewed requirement sources. |\n| `CI: Validate Docker Image` | `.github/workflows/docker-image-validate.yml` | Builds and smoke-tests the production container image on pull requests, pushes, and manual runs. |\n| `Release: Publish Docker Image` | `.github/workflows/docker-image-publish.yml` | Promotes an existing preview candidate onto release tags and the `stable` or `beta` channel, then signs the digest. |\n| `Release: Create Docker Image` | `.github/workflows/docker-image-preview-publish.yml` | Builds, validates, publishes, and signs a new preview image, forcing a fresh Debian package-layer rebuild for that run before moving the `test` channel tag. |\n| `Maintenance: Backfill Docker Release Tags` | `.github/workflows/docker-image-backfill.yml` | Reattaches release tags and release-channel aliases to an already published candidate digest for an existing release. |\n| `Maintenance: Clean Up Docker Package Versions` | `.github/workflows/docker-image-cleanup.yml` | Removes unprotected SHA-tagged preview GHCR package versions, prunes stale signature artifacts, and deletes unreferenced untagged package versions while preserving release-tagged and channel-protected versions including `test`. |\n| `Release: Build Companion Artifact` | `.github/workflows/build-companion.yml` | Builds companion release artifacts for a new unique version or prerelease candidate in the public distribution repository. |\n| `Release: Promote Companion Release` | `.github/workflows/promote-companion-release.yml` | Moves an existing companion release onto one or more update channels. |\n| `Deploy: Website` | `.github/workflows/website-deploy.yml` | Builds the website and deploys `website/public/` to Cloudflare Pages. |\n| `Security: Dependency Audit` | `.github/workflows/dependency-security.yml` | Runs scheduled and manual dependency vulnerability audits. |\n| `Security: Docker Image Scan` | `.github/workflows/docker-image-security-scan.yml` | Builds the current main image, forces a fresh Debian package-layer rebuild for that run, and scans it for newly disclosed vulnerabilities. |\n| `Admin: Sync Labels` | `.github/workflows/sync-labels.yml` | Synchronizes repository labels from `.github/labels.yml` without deleting unmanaged labels. |\n\nGitHub also shows repository-level features such as `Dependabot updates` and `Dependency graph`.\n\nThose are not repository workflows, so their display names are not controlled by these YAML files.\n\n## CI: Test\n\n`CI: Test` is the main validation workflow for pushes to `main`, pull requests against `main`, and manual dispatch.\n\nIt first detects which top-level product areas changed, then fans out only the relevant jobs for:\n\n- backend\n- frontend\n- frontend Playwright Chromium smoke\n- frontend Playwright Firefox markdown coverage on pushes to `main` and manual runs\n- companion\n\nManual dispatch runs all three areas.\n\nThe workflow ends with a single gate job so branch protection can depend on one stable required check instead of a changing set of per-area jobs.\n\nIn the backend job, regular tests run under `pytest-xdist` for throughput, while `@performance` tests run in a separate serial pass so wall-clock assertions are not distorted by parallel worker contention.\n\nFor frontend coverage, the workflow is intentionally layered:\n\n- the `frontend` job keeps the fast TypeScript, lint, and Vitest checks in the main PR path\n- the `frontend-e2e` job runs a bounded Playwright Chromium smoke slice on frontend changes\n- the `frontend-e2e-firefox` job runs the markdown editor Playwright slice only on pushes to `main` and manual dispatch\n\nThat split keeps pull-request runtime under control while still protecting the browser-sensitive editing workflows that unit tests do not cover.\n\nThe current companion test job does not call `./scripts/test`.\nIt runs explicit steps for Node install, companion TypeScript type checking, and `cargo test`.\nThat means the local Windows GNU cross-check in `./scripts/test` does not currently run in `CI: Test`.\n\n### Caching Model\n\nThe test workflow uses layered caching to reduce repeated setup work while keeping dependency inputs explicit.\n\nCurrent cache layers include:\n\n- `backend/.venv` caching keyed by the resolved backend requirement files and Python version.\n- `backend/.mypy_cache` caching keyed by backend Python source changes.\n- `actions/setup-node` npm download caching for frontend and companion jobs.\n- `frontend/node_modules` caching keyed by `frontend/package-lock.json`.\n- Rust build caching for `companion/src-tauri`.\n\nTreat those cache keys as reviewed dependency inputs, not as disposable generated noise.\n\nWhen dependency manifests or lockfiles change, commit the corresponding lockfile updates in the same pull request so cache invalidation and dependency review stay aligned.\n\n### Local Parity\n\nFor fast local iteration, use `./scripts/test`.\n\nWhen you want a closer CI-style pass, run the per-subsystem checks from [Test Strategy Overview](../test-strategy-overview/) and keep lockfile-driven installs intact.\n\nFor frontend work, that usually means:\n\n- `cd frontend \u0026\u0026 npm test` for the default Vitest suite\n- `cd frontend \u0026\u0026 npm run test:e2e` for the default Chromium browser pass\n\n`./scripts/test` now includes a local companion Windows GNU target compatibility check.\nThat check is intentionally a local validation aid, not part of the current `CI: Test` workflow contract.\n\n## CI: Lint\n\n`CI: Lint` applies the same change-detection pattern, then runs the repository's static checks for only the affected areas.\n\nCurrent coverage includes:\n\n- backend Ruff checks and formatting validation.\n- frontend Biome validation.\n- companion Clippy, Rustfmt, and Biome validation.\n\nThe lint workflow does not run the local companion Windows GNU cross-check either.\nThat cross-target validation is currently a local developer workflow check, while actual Windows artifact creation remains in the release workflow.\n\nThe workflow also ends with one gate job so branch protection can depend on a stable result.\n\n## Runner Distro Policy\n\nSambee does not require every GitHub Actions job to run on the same base distro.\n\nInstead, the rule is:\n\n- jobs that validate production-like runtime behavior or install native runtime dependencies should follow the same Debian family used by the production image and the dev container\n- jobs that only run language-level checks, dependency audits, repository automation, or other host-agnostic validation can stay on `ubuntu-latest`\n\nCurrent Debian-family jobs include:\n\n- the backend job in `CI: Test`\n- the `validate-tests` job in `Release: Create Docker Image`\n\nThe backend job builds the `backend-test` Docker target, which inherits the same runtime base as production. It runs mypy and the backend test suites inside that target, including when a Python image or other runtime input changes. The release validation job uses the pinned Debian-based Python container because `scripts/install-system-deps` requires distro-provided ImageMagick 7, while the default Ubuntu GitHub-hosted runner image still resolves `imagemagick` to ImageMagick 6.\n\n## Shared Runtime Targets\n\nThe root `Dockerfile` defines a shared `runtime-base` target. Production and the VS Code dev container both inherit that target, so they use the same pinned Python image and shared runtime package-installation policy.\n\nBefore building targets, Docker validation confirms that every Python image reference in the Dockerfile uses the same tag and digest. This keeps the native wheel-builder aligned with the shared runtime when Dependabot updates the Python image.\n\n`CI: Validate Docker Image` builds and reports the following values for the production target on each supported image platform and for the devcontainer target on Linux AMD64:\n\n- Python version.\n- `sqlite3` module version.\n- Debian `libsqlite3-0` package version.\n\nThe workflow passes a unique APT refresh key to each build, which intentionally refreshes Debian packages instead of reusing an older cached upgrade layer. The reported versions are evidence of the resolved native runtime; they are not required to match across images built at different times.\n\nCurrent jobs that intentionally remain on `ubuntu-latest` include:\n\n- change-detection, label-sync, and website deployment workflows\n- pure Python lint, lockfile freshness, and dependency-audit workflows\n- frontend-only and companion-only validation workflows\n- Docker build, smoke-test, and vulnerability-scan workflows, where the distro-sensitive logic runs inside the built image rather than on the host runner\n\nWhen adding or changing a workflow, treat runner distro as part of the test contract whenever a job installs OS packages or validates native behavior.\n\n## CI: Check Backend Lockfiles\n\n`CI: Check Backend Lockfiles` protects the reviewed Python dependency workflow.\n\nIt runs `scripts/refresh-backend-lockfiles --check` on pushes, pull requests, and manual runs that touch backend requirement inputs, generated lockfiles, or the refresh script itself.\n\nUse this as the fast failure signal when requirement files and generated lockfiles drift apart.\n\nFor the broader dependency-update workflow, use [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/).\n\n## Admin: Sync Labels\n\n`Admin: Sync Labels` keeps repository labels aligned with `.github/labels.yml`.\n\nIt is intentionally conservative.\n\n- Dependabot-related labels should stay declared in `.github/labels.yml`.\n- The workflow uses `skip-delete: true`, so labels not declared there are left alone.\n\nThat keeps automation-owned labels deterministic without forcing the repository to delete every manually created label.\n\n## Related Workflow Docs\n\nUse the more specific pages for the workflows that have dedicated operational guidance:\n\n- [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/)\n- [Docker Release Overview](../../release-and-versioning/docker-release-overview/)\n- [Companion Release Overview](../../release-and-versioning/companion-release-overview/)\n- [Set Up Cloudflare Pages Publishing](../../../website-dev-guide/setup-and-operations/set-up-cloudflare-pages-publishing/)\n", "1.0": "+++\ntitle = \"CI Workflows and Repository Automation\"\n+++\n\nUse this page to understand the GitHub Actions workflows contributors hit most often and to keep the workflow list grouped predictably in the GitHub UI.\n\n## Naming Convention\n\nGitHub lists workflows by the top-level `name` field.\n\nSambee groups workflow display names by operational purpose using `Area: Subject`.\n\nCurrent workflow groups are:\n\n- `CI`.\n- `Release`.\n- `Deploy`.\n- `Security`.\n- `Admin`.\n\nKeep new names short, stable, and grouped by what the workflow does rather than by how it is triggered.\n\n## Workflow Map\n\n| Display name | File | Role |\n|---|---|---|\n| `CI: Test` | `.github/workflows/test.yml` | Runs the main backend, frontend, and companion validation suites. |\n| `CI: Lint` | `.github/workflows/lint.yml` | Runs repository lint and formatting checks across backend, frontend, and companion. |\n| `CI: Check Backend Lockfiles` | `.github/workflows/check-backend-lockfiles.yml` | Verifies that committed backend lockfiles still match the reviewed requirement sources. |\n| `CI: Validate Docker Image` | `.github/workflows/docker-image-validate.yml` | Builds and smoke-tests the production container image on pull requests, pushes, and manual runs. |\n| `Release: Publish Docker Image` | `.github/workflows/docker-image-publish.yml` | Promotes an existing preview candidate onto release tags and the `stable` or `beta` channel, then signs the digest. |\n| `Release: Create Docker Image` | `.github/workflows/docker-image-preview-publish.yml` | Builds, validates, publishes, and signs a new preview image, forcing a fresh Debian package-layer rebuild for that run before moving the `test` channel tag. |\n| `Maintenance: Backfill Docker Release Tags` | `.github/workflows/docker-image-backfill.yml` | Reattaches release tags and release-channel aliases to an already published candidate digest for an existing release. |\n| `Maintenance: Clean Up Docker Package Versions` | `.github/workflows/docker-image-cleanup.yml` | Removes unprotected SHA-tagged preview GHCR package versions, prunes stale signature artifacts, and deletes unreferenced untagged package versions while preserving release-tagged and channel-protected versions including `test`. |\n| `Release: Build Companion Artifact` | `.github/workflows/build-companion.yml` | Builds companion release artifacts for a new unique version or prerelease candidate in the public distribution repository. |\n| `Release: Promote Companion Release` | `.github/workflows/promote-companion-release.yml` | Moves an existing companion release onto one or more update channels. |\n| `Deploy: Website` | `.github/workflows/website-deploy.yml` | Builds the website and deploys `website/public/` to Cloudflare Pages. |\n| `Security: Dependency Audit` | `.github/workflows/dependency-security.yml` | Runs scheduled and manual dependency vulnerability audits. |\n| `Security: Docker Image Scan` | `.github/workflows/docker-image-security-scan.yml` | Builds the current main image, forces a fresh Debian package-layer rebuild for that run, and scans it for newly disclosed vulnerabilities. |\n| `Admin: Sync Labels` | `.github/workflows/sync-labels.yml` | Synchronizes repository labels from `.github/labels.yml` without deleting unmanaged labels. |\n\nGitHub also shows repository-level features such as `Dependabot updates` and `Dependency graph`.\n\nThose are not repository workflows, so their display names are not controlled by these YAML files.\n\n## CI: Test\n\n`CI: Test` is the main validation workflow for pushes to `main`, pull requests against `main`, and manual dispatch.\n\nIt first detects which top-level product areas changed, then fans out only the relevant jobs for:\n\n- backend\n- frontend\n- frontend Playwright Chromium smoke\n- frontend Playwright Firefox markdown coverage on pushes to `main` and manual runs\n- companion\n\nManual dispatch runs all three areas.\n\nThe workflow ends with a single gate job so branch protection can depend on one stable required check instead of a changing set of per-area jobs.\n\nIn the backend job, regular tests run under `pytest-xdist` for throughput, while `@performance` tests run in a separate serial pass so wall-clock assertions are not distorted by parallel worker contention.\n\nFor frontend coverage, the workflow is intentionally layered:\n\n- the `frontend` job keeps the fast TypeScript, lint, and Vitest checks in the main PR path\n- the `frontend-e2e` job runs a bounded Playwright Chromium smoke slice on frontend changes\n- the `frontend-e2e-firefox` job runs the markdown editor Playwright slice only on pushes to `main` and manual dispatch\n\nThat split keeps pull-request runtime under control while still protecting the browser-sensitive editing workflows that unit tests do not cover.\n\nThe current companion test job does not call `./scripts/test`.\nIt runs explicit steps for Node install, companion TypeScript type checking, and `cargo test`.\nThat means the local Windows GNU cross-check in `./scripts/test` does not currently run in `CI: Test`.\n\n### Caching Model\n\nThe test workflow uses layered caching to reduce repeated setup work while keeping dependency inputs explicit.\n\nCurrent cache layers include:\n\n- `backend/.venv` caching keyed by the resolved backend requirement files and Python version.\n- `backend/.mypy_cache` caching keyed by backend Python source changes.\n- `actions/setup-node` npm download caching for frontend and companion jobs.\n- `frontend/node_modules` caching keyed by `frontend/package-lock.json`.\n- Rust build caching for `companion/src-tauri`.\n\nTreat those cache keys as reviewed dependency inputs, not as disposable generated noise.\n\nWhen dependency manifests or lockfiles change, commit the corresponding lockfile updates in the same pull request so cache invalidation and dependency review stay aligned.\n\n### Local Parity\n\nFor fast local iteration, use `./scripts/test`.\n\nWhen you want a closer CI-style pass, run the per-subsystem checks from [Test Strategy Overview](../test-strategy-overview/) and keep lockfile-driven installs intact.\n\nFor frontend work, that usually means:\n\n- `cd frontend \u0026\u0026 npm test` for the default Vitest suite\n- `cd frontend \u0026\u0026 npm run test:e2e` for the default Chromium browser pass\n\n`./scripts/test` now includes a local companion Windows GNU target compatibility check.\nThat check is intentionally a local validation aid, not part of the current `CI: Test` workflow contract.\n\n## CI: Lint\n\n`CI: Lint` applies the same change-detection pattern, then runs the repository's static checks for only the affected areas.\n\nCurrent coverage includes:\n\n- backend Ruff checks and formatting validation.\n- frontend Biome validation.\n- companion Clippy, Rustfmt, and Biome validation.\n\nThe lint workflow does not run the local companion Windows GNU cross-check either.\nThat cross-target validation is currently a local developer workflow check, while actual Windows artifact creation remains in the release workflow.\n\nThe workflow also ends with one gate job so branch protection can depend on a stable result.\n\n## Runner Distro Policy\n\nSambee does not require every GitHub Actions job to run on the same base distro.\n\nInstead, the rule is:\n\n- jobs that validate production-like runtime behavior or install native runtime dependencies should follow the same Debian family used by the production image and the dev container\n- jobs that only run language-level checks, dependency audits, repository automation, or other host-agnostic validation can stay on `ubuntu-latest`\n\nCurrent Debian-family jobs include:\n\n- the backend job in `CI: Test`\n- the `validate-tests` job in `Release: Create Docker Image`\n\nThe backend job builds the `backend-test` Docker target, which inherits the same runtime base as production. It runs mypy and the backend test suites inside that target, including when a Python image or other runtime input changes. The release validation job uses the pinned Debian-based Python container because `scripts/install-system-deps` requires distro-provided ImageMagick 7, while the default Ubuntu GitHub-hosted runner image still resolves `imagemagick` to ImageMagick 6.\n\n## Shared Runtime Targets\n\nThe root `Dockerfile` defines a shared `runtime-base` target. Production and the VS Code dev container both inherit that target, so they use the same pinned Python image and shared runtime package-installation policy.\n\nBefore building targets, Docker validation confirms that every Python image reference in the Dockerfile uses the same tag and digest. This keeps the native wheel-builder aligned with the shared runtime when Dependabot updates the Python image.\n\n`CI: Validate Docker Image` builds and reports the following values for the production target on each supported image platform and for the devcontainer target on Linux AMD64:\n\n- Python version.\n- `sqlite3` module version.\n- Debian `libsqlite3-0` package version.\n\nThe workflow passes a unique APT refresh key to each build, which intentionally refreshes Debian packages instead of reusing an older cached upgrade layer. The reported versions are evidence of the resolved native runtime; they are not required to match across images built at different times.\n\nCurrent jobs that intentionally remain on `ubuntu-latest` include:\n\n- change-detection, label-sync, and website deployment workflows\n- pure Python lint, lockfile freshness, and dependency-audit workflows\n- frontend-only and companion-only validation workflows\n- Docker build, smoke-test, and vulnerability-scan workflows, where the distro-sensitive logic runs inside the built image rather than on the host runner\n\nWhen adding or changing a workflow, treat runner distro as part of the test contract whenever a job installs OS packages or validates native behavior.\n\n## CI: Check Backend Lockfiles\n\n`CI: Check Backend Lockfiles` protects the reviewed Python dependency workflow.\n\nIt runs `scripts/refresh-backend-lockfiles --check` on pushes, pull requests, and manual runs that touch backend requirement inputs, generated lockfiles, or the refresh script itself.\n\nUse this as the fast failure signal when requirement files and generated lockfiles drift apart.\n\nFor the broader dependency-update workflow, use [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/).\n\n## Admin: Sync Labels\n\n`Admin: Sync Labels` keeps repository labels aligned with `.github/labels.yml`.\n\nIt is intentionally conservative.\n\n- Dependabot-related labels should stay declared in `.github/labels.yml`.\n- The workflow uses `skip-delete: true`, so labels not declared there are left alone.\n\nThat keeps automation-owned labels deterministic without forcing the repository to delete every manually created label.\n\n## Related Workflow Docs\n\nUse the more specific pages for the workflows that have dedicated operational guidance:\n\n- [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/)\n- [Docker Release Overview](../../release-and-versioning/docker-release-overview/)\n- [Companion Release Overview](../../release-and-versioning/companion-release-overview/)\n- [Set Up Cloudflare Pages Publishing](../../../website-dev-guide/setup-and-operations/set-up-cloudflare-pages-publishing/)\n", "2.0": "+++\ntitle = \"CI Workflows and Repository Automation\"\n+++\n\nUse this page to understand the GitHub Actions workflows contributors hit most often and to keep the workflow list grouped predictably in the GitHub UI.\n\n## Naming Convention\n\nGitHub lists workflows by the top-level `name` field.\n\nSambee groups workflow display names by operational purpose using `Area: Subject`.\n\nCurrent workflow groups are:\n\n- `CI`.\n- `Release`.\n- `Deploy`.\n- `Security`.\n- `Admin`.\n\nKeep new names short, stable, and grouped by what the workflow does rather than by how it is triggered.\n\n## Workflow Map\n\n| Display name | File | Role |\n|---|---|---|\n| `CI: Test` | `.github/workflows/test.yml` | Runs the main backend, frontend, and companion validation suites. |\n| `CI: Lint` | `.github/workflows/lint.yml` | Runs repository lint and formatting checks across backend, frontend, and companion. |\n| `CI: Check Backend Lockfiles` | `.github/workflows/check-backend-lockfiles.yml` | Verifies that committed backend lockfiles still match the reviewed requirement sources. |\n| `CI: Validate Docker Image` | `.github/workflows/docker-image-validate.yml` | Builds and smoke-tests the production container image on pull requests, pushes, and manual runs. |\n| `Release: Publish Docker Image` | `.github/workflows/docker-image-publish.yml` | Promotes an existing preview candidate onto release tags and the `stable` or `beta` channel, then signs the digest. |\n| `Release: Create Docker Image` | `.github/workflows/docker-image-preview-publish.yml` | Builds, validates, publishes, and signs a new preview image, forcing a fresh Debian package-layer rebuild for that run before moving the `test` channel tag. |\n| `Maintenance: Backfill Docker Release Tags` | `.github/workflows/docker-image-backfill.yml` | Reattaches release tags and release-channel aliases to an already published candidate digest for an existing release. |\n| `Maintenance: Clean Up Docker Package Versions` | `.github/workflows/docker-image-cleanup.yml` | Removes unprotected SHA-tagged preview GHCR package versions, prunes stale signature artifacts, and deletes unreferenced untagged package versions while preserving release-tagged and channel-protected versions including `test`. |\n| `Maintenance: Clean Up Actions Caches` | `.github/workflows/cleanup-actions-caches.yml` | Removes closed-PR caches and superseded known cache keys without disabling warm caches for active builds. |\n| `Maintenance: Signal Closed PR Cache Cleanup` | `.github/workflows/signal-closed-pr-cache-cleanup.yml` | Triggers cache cleanup after a pull request closes without granting the pull request write access. |\n| `Release: Build Companion Artifact` | `.github/workflows/build-companion.yml` | Builds companion release artifacts for a new unique version or prerelease candidate in the public distribution repository. |\n| `Release: Promote Companion Release` | `.github/workflows/promote-companion-release.yml` | Moves an existing companion release onto one or more update channels. |\n| `Deploy: Website` | `.github/workflows/website-deploy.yml` | Builds the website and deploys `website/public/` to Cloudflare Pages. |\n| `Security: Dependency Audit` | `.github/workflows/dependency-security.yml` | Runs scheduled and manual dependency vulnerability audits. |\n| `Security: Docker Image Scan` | `.github/workflows/docker-image-security-scan.yml` | Builds the current main image, forces a fresh Debian package-layer rebuild for that run, and scans it for newly disclosed vulnerabilities. |\n| `Admin: Sync Labels` | `.github/workflows/sync-labels.yml` | Synchronizes repository labels from `.github/labels.yml` without deleting unmanaged labels. |\n\nGitHub also shows repository-level features such as `Dependabot updates` and `Dependency graph`.\n\nThose are not repository workflows, so their display names are not controlled by these YAML files.\n\n## CI: Test\n\n`CI: Test` is the main validation workflow for pushes to `main`, pull requests against `main`, and manual dispatch.\n\nIt first detects which top-level product areas changed, then fans out only the relevant jobs for:\n\n- backend\n- frontend\n- frontend Playwright Chromium smoke\n- frontend Playwright Firefox markdown coverage on pushes to `main` and manual runs\n- companion\n\nManual dispatch runs all three areas.\n\nThe workflow ends with a single gate job so branch protection can depend on one stable required check instead of a changing set of per-area jobs.\n\nIn the backend job, regular tests run under `pytest-xdist` for throughput, while `@performance` tests run in a separate serial pass so wall-clock assertions are not distorted by parallel worker contention.\n\nFor frontend coverage, the workflow is intentionally layered:\n\n- the `frontend` job keeps the fast TypeScript, lint, and Vitest checks in the main PR path\n- the `frontend-e2e` job runs a bounded Playwright Chromium smoke slice on frontend changes\n- the `frontend-e2e-firefox` job runs the markdown editor Playwright slice only on pushes to `main` and manual dispatch\n\nThat split keeps pull-request runtime under control while still protecting the browser-sensitive editing workflows that unit tests do not cover.\n\nThe current companion test job does not call `./scripts/test`.\nIt runs explicit steps for Node install, companion TypeScript type checking, and `cargo test`.\nThat means the local Windows GNU cross-check in `./scripts/test` does not currently run in `CI: Test`.\n\n### Caching Model\n\nThe test workflow uses layered caching to reduce repeated setup work while keeping dependency inputs explicit.\n\nCurrent cache layers include:\n\n- `backend/.venv` caching keyed by the resolved backend requirement files and Python version.\n- `backend/.mypy_cache` caching keyed by backend Python source changes.\n- `actions/setup-node` npm download caching for frontend and companion jobs.\n- `frontend/node_modules` caching keyed by `frontend/package-lock.json`.\n- Rust build caching for `companion/src-tauri`.\n\nTreat those cache keys as reviewed dependency inputs, not as disposable generated noise.\n\nWhen dependency manifests or lockfiles change, commit the corresponding lockfile updates in the same pull request so cache invalidation and dependency review stay aligned.\n\n### Cache Retention\n\n`Maintenance: Clean Up Actions Caches` runs after cache-producing workflows finish and daily as a fallback. When a pull request closes, an unprivileged signal workflow runs first; its completion triggers the same cleanup. A manual run defaults to a dry run; select **Delete eligible caches** to apply the policy. Its run summary lists selected entries and the amount of storage reclaimed. The cleanup reads only trusted code from `main`, and does not run pull-request code with cache-deletion permissions.\n\nThe policy keeps the newest known cache family on `main` and each open pull request. It removes superseded Rust and website cache keys, and deletes all caches for a closed pull request after its builds finish. It skips refs with active builds and leaves unrecognized keys, including individual BuildKit blobs on active refs, alone. GitHub's normal expiration still applies to those unclassified entries. The job deletes caches by ID so a pull request's copy cannot inadvertently delete an identically keyed cache on `main`.\n\nReview the dry-run report before changing cache-family rules. If active caches alone approach the repository storage limit, raise the limit or accept more cache misses: deleting their newest copies would make CI slower. Cleanup happens after cache uploads, so it cannot prevent a full repository from evicting caches during an upload.\n\n### Local Parity\n\nFor fast local iteration, use `./scripts/test`.\n\nWhen you want a closer CI-style pass, run the per-subsystem checks from [Test Strategy Overview](../test-strategy-overview/) and keep lockfile-driven installs intact.\n\nFor frontend work, that usually means:\n\n- `cd frontend \u0026\u0026 npm test` for the default Vitest suite\n- `cd frontend \u0026\u0026 npm run test:e2e` for the default Chromium browser pass\n\n`./scripts/test` now includes a local companion Windows GNU target compatibility check.\nThat check is intentionally a local validation aid, not part of the current `CI: Test` workflow contract.\n\n## CI: Lint\n\n`CI: Lint` applies the same change-detection pattern, then runs the repository's static checks for only the affected areas.\n\nCurrent coverage includes:\n\n- backend Ruff checks and formatting validation.\n- frontend Biome validation.\n- companion Clippy, Rustfmt, and Biome validation.\n\nThe lint workflow does not run the local companion Windows GNU cross-check either.\nThat cross-target validation is currently a local developer workflow check, while actual Windows artifact creation remains in the release workflow.\n\nThe workflow also ends with one gate job so branch protection can depend on a stable result.\n\n## Runner Distro Policy\n\nSambee does not require every GitHub Actions job to run on the same base distro.\n\nInstead, the rule is:\n\n- jobs that validate production-like runtime behavior or install native runtime dependencies should follow the same Debian family used by the production image and the dev container\n- jobs that only run language-level checks, dependency audits, repository automation, or other host-agnostic validation can stay on `ubuntu-latest`\n\nCurrent Debian-family jobs include:\n\n- the backend job in `CI: Test`\n- the `validate-tests` job in `Release: Create Docker Image`\n\nThe backend job builds the `backend-test` Docker target, which inherits the same runtime base as production. It runs mypy and the backend test suites inside that target, including when a Python image or other runtime input changes. The release validation job uses the pinned Debian-based Python container because `scripts/install-system-deps` requires distro-provided ImageMagick 7, while the default Ubuntu GitHub-hosted runner image still resolves `imagemagick` to ImageMagick 6.\n\n## Shared Runtime Targets\n\nThe root `Dockerfile` defines a shared `runtime-base` target. Production and the VS Code dev container both inherit that target, so they use the same pinned Python image and shared runtime package-installation policy.\n\nBefore building targets, Docker validation confirms that every Python image reference in the Dockerfile uses the same tag and digest. This keeps the native wheel-builder aligned with the shared runtime when Dependabot updates the Python image.\n\n`CI: Validate Docker Image` builds and reports the following values for the production target on each supported image platform and for the devcontainer target on Linux AMD64:\n\n- Python version.\n- `sqlite3` module version.\n- Debian `libsqlite3-0` package version.\n\nThe workflow passes a unique APT refresh key to each build, which intentionally refreshes Debian packages instead of reusing an older cached upgrade layer. The reported versions are evidence of the resolved native runtime; they are not required to match across images built at different times.\n\nCurrent jobs that intentionally remain on `ubuntu-latest` include:\n\n- change-detection, label-sync, and website deployment workflows\n- pure Python lint, lockfile freshness, and dependency-audit workflows\n- frontend-only and companion-only validation workflows\n- Docker build, smoke-test, and vulnerability-scan workflows, where the distro-sensitive logic runs inside the built image rather than on the host runner\n\nWhen adding or changing a workflow, treat runner distro as part of the test contract whenever a job installs OS packages or validates native behavior.\n\n## CI: Check Backend Lockfiles\n\n`CI: Check Backend Lockfiles` protects the reviewed Python dependency workflow.\n\nIt runs `scripts/refresh-backend-lockfiles --check` on pushes, pull requests, and manual runs that touch backend requirement inputs, generated lockfiles, or the refresh script itself.\n\nUse this as the fast failure signal when requirement files and generated lockfiles drift apart.\n\nFor the broader dependency-update workflow, use [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/).\n\n## Admin: Sync Labels\n\n`Admin: Sync Labels` keeps repository labels aligned with `.github/labels.yml`.\n\nIt is intentionally conservative.\n\n- Dependabot-related labels should stay declared in `.github/labels.yml`.\n- The workflow uses `skip-delete: true`, so labels not declared there are left alone.\n\nThat keeps automation-owned labels deterministic without forcing the repository to delete every manually created label.\n\n## Related Workflow Docs\n\nUse the more specific pages for the workflows that have dedicated operational guidance:\n\n- [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/)\n- [Docker Release Overview](../../release-and-versioning/docker-release-overview/)\n- [Companion Release Overview](../../release-and-versioning/companion-release-overview/)\n- [Set Up Cloudflare Pages Publishing](../../../website-dev-guide/setup-and-operations/set-up-cloudflare-pages-publishing/)\n"}, "page_contents": {"0.7": "+++\ntitle = \"CI Workflows and Repository Automation\"\n+++\n\nUse this page to understand the GitHub Actions workflows contributors hit most often and to keep the workflow list grouped predictably in the GitHub UI.\n\n## Naming Convention\n\nGitHub lists workflows by the top-level `name` field.\n\nSambee groups workflow display names by operational purpose using `Area: Subject`.\n\nCurrent workflow groups are:\n\n- `CI`.\n- `Release`.\n- `Deploy`.\n- `Security`.\n- `Admin`.\n\nKeep new names short, stable, and grouped by what the workflow does rather than by how it is triggered.\n\n## Workflow Map\n\n| Display name | File | Role |\n|---|---|---|\n| `CI: Test` | `.github/workflows/test.yml` | Runs the main backend, frontend, and companion validation suites. |\n| `CI: Lint` | `.github/workflows/lint.yml` | Runs repository lint and formatting checks across backend, frontend, and companion. |\n| `CI: Check Backend Lockfiles` | `.github/workflows/check-backend-lockfiles.yml` | Verifies that committed backend lockfiles still match the reviewed requirement sources. |\n| `CI: Validate Docker Image` | `.github/workflows/docker-image-validate.yml` | Builds and smoke-tests the production container image on pull requests, pushes, and manual runs. |\n| `Release: Publish Docker Image` | `.github/workflows/docker-image-publish.yml` | Promotes an existing preview candidate onto release tags and the `stable` or `beta` channel, then signs the digest. |\n| `Release: Create Docker Image` | `.github/workflows/docker-image-preview-publish.yml` | Builds, validates, publishes, and signs a new preview image, forcing a fresh Debian package-layer rebuild for that run before moving the `test` channel tag. |\n| `Maintenance: Backfill Docker Release Tags` | `.github/workflows/docker-image-backfill.yml` | Reattaches release tags and release-channel aliases to an already published candidate digest for an existing release. |\n| `Maintenance: Clean Up Docker Package Versions` | `.github/workflows/docker-image-cleanup.yml` | Removes unprotected SHA-tagged preview GHCR package versions, prunes stale signature artifacts, and deletes unreferenced untagged package versions while preserving release-tagged and channel-protected versions including `test`. |\n| `Release: Build Companion Artifact` | `.github/workflows/build-companion.yml` | Builds companion release artifacts for a new unique version or prerelease candidate in the public distribution repository. |\n| `Release: Promote Companion Release` | `.github/workflows/promote-companion-release.yml` | Moves an existing companion release onto one or more update channels. |\n| `Deploy: Website` | `.github/workflows/website-deploy.yml` | Builds the website and deploys `website/public/` to Cloudflare Pages. |\n| `Security: Dependency Audit` | `.github/workflows/dependency-security.yml` | Runs scheduled and manual dependency vulnerability audits. |\n| `Security: Docker Image Scan` | `.github/workflows/docker-image-security-scan.yml` | Builds the current main image, forces a fresh Debian package-layer rebuild for that run, and scans it for newly disclosed vulnerabilities. |\n| `Admin: Sync Labels` | `.github/workflows/sync-labels.yml` | Synchronizes repository labels from `.github/labels.yml` without deleting unmanaged labels. |\n\nGitHub also shows repository-level features such as `Dependabot updates` and `Dependency graph`.\n\nThose are not repository workflows, so their display names are not controlled by these YAML files.\n\n## CI: Test\n\n`CI: Test` is the main validation workflow for pushes to `main`, pull requests against `main`, and manual dispatch.\n\nIt first detects which top-level product areas changed, then fans out only the relevant jobs for:\n\n- backend\n- frontend\n- companion\n\nManual dispatch runs all three areas.\n\nThe workflow ends with a single gate job so branch protection can depend on one stable required check instead of a changing set of per-area jobs.\n\nIn the backend job, regular tests run under `pytest-xdist` for throughput, while `@performance` tests run in a separate serial pass so wall-clock assertions are not distorted by parallel worker contention.\n\n### Caching Model\n\nThe test workflow uses layered caching to reduce repeated setup work while keeping dependency inputs explicit.\n\nCurrent cache layers include:\n\n- `backend/.venv` caching keyed by the resolved backend requirement files and Python version.\n- `backend/.mypy_cache` caching keyed by backend Python source changes.\n- `actions/setup-node` npm download caching for frontend and companion jobs.\n- `frontend/node_modules` caching keyed by `frontend/package-lock.json`.\n- Rust build caching for `companion/src-tauri`.\n\nTreat those cache keys as reviewed dependency inputs, not as disposable generated noise.\n\nWhen dependency manifests or lockfiles change, commit the corresponding lockfile updates in the same pull request so cache invalidation and dependency review stay aligned.\n\n### Local Parity\n\nFor fast local iteration, use `./scripts/test`.\n\nWhen you want a closer CI-style pass, run the per-subsystem checks from [Test Strategy Overview](../test-strategy-overview/) and keep lockfile-driven installs intact.\n\n## CI: Lint\n\n`CI: Lint` applies the same change-detection pattern, then runs the repository's static checks for only the affected areas.\n\nCurrent coverage includes:\n\n- backend Ruff checks and formatting validation.\n- frontend Biome validation.\n- companion Clippy, Rustfmt, and Biome validation.\n\nThe workflow also ends with one gate job so branch protection can depend on a stable result.\n\n## Runner Distro Policy\n\nSambee does not require every GitHub Actions job to run on the same base distro.\n\nInstead, the rule is:\n\n- jobs that validate production-like runtime behavior or install native runtime dependencies should follow the same Debian family used by the production image and the dev container\n- jobs that only run language-level checks, dependency audits, repository automation, or other host-agnostic validation can stay on `ubuntu-latest`\n\nCurrent Debian-family jobs include:\n\n- the backend job in `CI: Test`\n- the `validate-tests` job in `Release: Create Docker Image`\n\nThose jobs run inside the pinned `python:3.13.12-slim` container because `scripts/install-system-deps` now requires distro-provided ImageMagick 7, while the default Ubuntu GitHub-hosted runner image still resolves `imagemagick` to ImageMagick 6.\n\nCurrent jobs that intentionally remain on `ubuntu-latest` include:\n\n- change-detection, label-sync, and website deployment workflows\n- pure Python lint, lockfile freshness, and dependency-audit workflows\n- frontend-only and companion-only validation workflows\n- Docker build, smoke-test, and vulnerability-scan workflows, where the distro-sensitive logic runs inside the built image rather than on the host runner\n\nWhen adding or changing a workflow, treat runner distro as part of the test contract whenever a job installs OS packages or validates native behavior.\n\n## CI: Check Backend Lockfiles\n\n`CI: Check Backend Lockfiles` protects the reviewed Python dependency workflow.\n\nIt runs `scripts/refresh-backend-lockfiles --check` on pushes, pull requests, and manual runs that touch backend requirement inputs, generated lockfiles, or the refresh script itself.\n\nUse this as the fast failure signal when requirement files and generated lockfiles drift apart.\n\nFor the broader dependency-update workflow, use [Dependency Update Workflow](../release-and-versioning/dependency-update-workflow/).\n\n## Admin: Sync Labels\n\n`Admin: Sync Labels` keeps repository labels aligned with `.github/labels.yml`.\n\nIt is intentionally conservative.\n\n- Dependabot-related labels should stay declared in `.github/labels.yml`.\n- The workflow uses `skip-delete: true`, so labels not declared there are left alone.\n\nThat keeps automation-owned labels deterministic without forcing the repository to delete every manually created label.\n\n## Related Workflow Docs\n\nUse the more specific pages for the workflows that have dedicated operational guidance:\n\n- [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/)\n- [Docker Release Overview](../../release-and-versioning/docker-release-overview/)\n- [Companion Release Overview](../../release-and-versioning/companion-release-overview/)\n- [Set Up Cloudflare Pages Publishing](../../../website-dev-guide/setup-and-operations/set-up-cloudflare-pages-publishing/)\n\n", "0.8": "+++\ntitle = \"CI Workflows and Repository Automation\"\n+++\n\nUse this page to understand the GitHub Actions workflows contributors hit most often and to keep the workflow list grouped predictably in the GitHub UI.\n\n## Naming Convention\n\nGitHub lists workflows by the top-level `name` field.\n\nSambee groups workflow display names by operational purpose using `Area: Subject`.\n\nCurrent workflow groups are:\n\n- `CI`.\n- `Release`.\n- `Deploy`.\n- `Security`.\n- `Admin`.\n\nKeep new names short, stable, and grouped by what the workflow does rather than by how it is triggered.\n\n## Workflow Map\n\n| Display name | File | Role |\n|---|---|---|\n| `CI: Test` | `.github/workflows/test.yml` | Runs the main backend, frontend, and companion validation suites. |\n| `CI: Lint` | `.github/workflows/lint.yml` | Runs repository lint and formatting checks across backend, frontend, and companion. |\n| `CI: Check Backend Lockfiles` | `.github/workflows/check-backend-lockfiles.yml` | Verifies that committed backend lockfiles still match the reviewed requirement sources. |\n| `CI: Validate Docker Image` | `.github/workflows/docker-image-validate.yml` | Builds and smoke-tests the production container image on pull requests, pushes, and manual runs. |\n| `Release: Publish Docker Image` | `.github/workflows/docker-image-publish.yml` | Promotes an existing preview candidate onto release tags and the `stable` or `beta` channel, then signs the digest. |\n| `Release: Create Docker Image` | `.github/workflows/docker-image-preview-publish.yml` | Builds, validates, publishes, and signs a new preview image, forcing a fresh Debian package-layer rebuild for that run before moving the `test` channel tag. |\n| `Maintenance: Backfill Docker Release Tags` | `.github/workflows/docker-image-backfill.yml` | Reattaches release tags and release-channel aliases to an already published candidate digest for an existing release. |\n| `Maintenance: Clean Up Docker Package Versions` | `.github/workflows/docker-image-cleanup.yml` | Removes unprotected SHA-tagged preview GHCR package versions, prunes stale signature artifacts, and deletes unreferenced untagged package versions while preserving release-tagged and channel-protected versions including `test`. |\n| `Release: Build Companion Artifact` | `.github/workflows/build-companion.yml` | Builds companion release artifacts for a new unique version or prerelease candidate in the public distribution repository. |\n| `Release: Promote Companion Release` | `.github/workflows/promote-companion-release.yml` | Moves an existing companion release onto one or more update channels. |\n| `Deploy: Website` | `.github/workflows/website-deploy.yml` | Builds the website and deploys `website/public/` to Cloudflare Pages. |\n| `Security: Dependency Audit` | `.github/workflows/dependency-security.yml` | Runs scheduled and manual dependency vulnerability audits. |\n| `Security: Docker Image Scan` | `.github/workflows/docker-image-security-scan.yml` | Builds the current main image, forces a fresh Debian package-layer rebuild for that run, and scans it for newly disclosed vulnerabilities. |\n| `Admin: Sync Labels` | `.github/workflows/sync-labels.yml` | Synchronizes repository labels from `.github/labels.yml` without deleting unmanaged labels. |\n\nGitHub also shows repository-level features such as `Dependabot updates` and `Dependency graph`.\n\nThose are not repository workflows, so their display names are not controlled by these YAML files.\n\n## CI: Test\n\n`CI: Test` is the main validation workflow for pushes to `main`, pull requests against `main`, and manual dispatch.\n\nIt first detects which top-level product areas changed, then fans out only the relevant jobs for:\n\n- backend\n- frontend\n- frontend Playwright Chromium smoke\n- frontend Playwright Firefox markdown coverage on pushes to `main` and manual runs\n- companion\n\nManual dispatch runs all three areas.\n\nThe workflow ends with a single gate job so branch protection can depend on one stable required check instead of a changing set of per-area jobs.\n\nIn the backend job, regular tests run under `pytest-xdist` for throughput, while `@performance` tests run in a separate serial pass so wall-clock assertions are not distorted by parallel worker contention.\n\nFor frontend coverage, the workflow is intentionally layered:\n\n- the `frontend` job keeps the fast TypeScript, lint, and Vitest checks in the main PR path\n- the `frontend-e2e` job runs a bounded Playwright Chromium smoke slice on frontend changes\n- the `frontend-e2e-firefox` job runs the markdown editor Playwright slice only on pushes to `main` and manual dispatch\n\nThat split keeps pull-request runtime under control while still protecting the browser-sensitive editing workflows that unit tests do not cover.\n\nThe current companion test job does not call `./scripts/test`.\nIt runs explicit steps for Node install, companion TypeScript type checking, and `cargo test`.\nThat means the local Windows GNU cross-check in `./scripts/test` does not currently run in `CI: Test`.\n\n### Caching Model\n\nThe test workflow uses layered caching to reduce repeated setup work while keeping dependency inputs explicit.\n\nCurrent cache layers include:\n\n- `backend/.venv` caching keyed by the resolved backend requirement files and Python version.\n- `backend/.mypy_cache` caching keyed by backend Python source changes.\n- `actions/setup-node` npm download caching for frontend and companion jobs.\n- `frontend/node_modules` caching keyed by `frontend/package-lock.json`.\n- Rust build caching for `companion/src-tauri`.\n\nTreat those cache keys as reviewed dependency inputs, not as disposable generated noise.\n\nWhen dependency manifests or lockfiles change, commit the corresponding lockfile updates in the same pull request so cache invalidation and dependency review stay aligned.\n\n### Local Parity\n\nFor fast local iteration, use `./scripts/test`.\n\nWhen you want a closer CI-style pass, run the per-subsystem checks from [Test Strategy Overview](../test-strategy-overview/) and keep lockfile-driven installs intact.\n\nFor frontend work, that usually means:\n\n- `cd frontend \u0026\u0026 npm test` for the default Vitest suite\n- `cd frontend \u0026\u0026 npm run test:e2e` for the default Chromium browser pass\n\n`./scripts/test` now includes a local companion Windows GNU target compatibility check.\nThat check is intentionally a local validation aid, not part of the current `CI: Test` workflow contract.\n\n## CI: Lint\n\n`CI: Lint` applies the same change-detection pattern, then runs the repository's static checks for only the affected areas.\n\nCurrent coverage includes:\n\n- backend Ruff checks and formatting validation.\n- frontend Biome validation.\n- companion Clippy, Rustfmt, and Biome validation.\n\nThe lint workflow does not run the local companion Windows GNU cross-check either.\nThat cross-target validation is currently a local developer workflow check, while actual Windows artifact creation remains in the release workflow.\n\nThe workflow also ends with one gate job so branch protection can depend on a stable result.\n\n## Runner Distro Policy\n\nSambee does not require every GitHub Actions job to run on the same base distro.\n\nInstead, the rule is:\n\n- jobs that validate production-like runtime behavior or install native runtime dependencies should follow the same Debian family used by the production image and the dev container\n- jobs that only run language-level checks, dependency audits, repository automation, or other host-agnostic validation can stay on `ubuntu-latest`\n\nCurrent Debian-family jobs include:\n\n- the backend job in `CI: Test`\n- the `validate-tests` job in `Release: Create Docker Image`\n\nThose jobs run inside the pinned `python:3.13.12-slim` container because `scripts/install-system-deps` now requires distro-provided ImageMagick 7, while the default Ubuntu GitHub-hosted runner image still resolves `imagemagick` to ImageMagick 6.\n\nCurrent jobs that intentionally remain on `ubuntu-latest` include:\n\n- change-detection, label-sync, and website deployment workflows\n- pure Python lint, lockfile freshness, and dependency-audit workflows\n- frontend-only and companion-only validation workflows\n- Docker build, smoke-test, and vulnerability-scan workflows, where the distro-sensitive logic runs inside the built image rather than on the host runner\n\nWhen adding or changing a workflow, treat runner distro as part of the test contract whenever a job installs OS packages or validates native behavior.\n\n## CI: Check Backend Lockfiles\n\n`CI: Check Backend Lockfiles` protects the reviewed Python dependency workflow.\n\nIt runs `scripts/refresh-backend-lockfiles --check` on pushes, pull requests, and manual runs that touch backend requirement inputs, generated lockfiles, or the refresh script itself.\n\nUse this as the fast failure signal when requirement files and generated lockfiles drift apart.\n\nFor the broader dependency-update workflow, use [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/).\n\n## Admin: Sync Labels\n\n`Admin: Sync Labels` keeps repository labels aligned with `.github/labels.yml`.\n\nIt is intentionally conservative.\n\n- Dependabot-related labels should stay declared in `.github/labels.yml`.\n- The workflow uses `skip-delete: true`, so labels not declared there are left alone.\n\nThat keeps automation-owned labels deterministic without forcing the repository to delete every manually created label.\n\n## Related Workflow Docs\n\nUse the more specific pages for the workflows that have dedicated operational guidance:\n\n- [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/)\n- [Docker Release Overview](../../release-and-versioning/docker-release-overview/)\n- [Companion Release Overview](../../release-and-versioning/companion-release-overview/)\n- [Set Up Cloudflare Pages Publishing](../../../website-dev-guide/setup-and-operations/set-up-cloudflare-pages-publishing/)\n", "0.9": "+++\ntitle = \"CI Workflows and Repository Automation\"\n+++\n\nUse this page to understand the GitHub Actions workflows contributors hit most often and to keep the workflow list grouped predictably in the GitHub UI.\n\n## Naming Convention\n\nGitHub lists workflows by the top-level `name` field.\n\nSambee groups workflow display names by operational purpose using `Area: Subject`.\n\nCurrent workflow groups are:\n\n- `CI`.\n- `Release`.\n- `Deploy`.\n- `Security`.\n- `Admin`.\n\nKeep new names short, stable, and grouped by what the workflow does rather than by how it is triggered.\n\n## Workflow Map\n\n| Display name | File | Role |\n|---|---|---|\n| `CI: Test` | `.github/workflows/test.yml` | Runs the main backend, frontend, and companion validation suites. |\n| `CI: Lint` | `.github/workflows/lint.yml` | Runs repository lint and formatting checks across backend, frontend, and companion. |\n| `CI: Check Backend Lockfiles` | `.github/workflows/check-backend-lockfiles.yml` | Verifies that committed backend lockfiles still match the reviewed requirement sources. |\n| `CI: Validate Docker Image` | `.github/workflows/docker-image-validate.yml` | Builds and smoke-tests the production container image on pull requests, pushes, and manual runs. |\n| `Release: Publish Docker Image` | `.github/workflows/docker-image-publish.yml` | Promotes an existing preview candidate onto release tags and the `stable` or `beta` channel, then signs the digest. |\n| `Release: Create Docker Image` | `.github/workflows/docker-image-preview-publish.yml` | Builds, validates, publishes, and signs a new preview image, forcing a fresh Debian package-layer rebuild for that run before moving the `test` channel tag. |\n| `Maintenance: Backfill Docker Release Tags` | `.github/workflows/docker-image-backfill.yml` | Reattaches release tags and release-channel aliases to an already published candidate digest for an existing release. |\n| `Maintenance: Clean Up Docker Package Versions` | `.github/workflows/docker-image-cleanup.yml` | Removes unprotected SHA-tagged preview GHCR package versions, prunes stale signature artifacts, and deletes unreferenced untagged package versions while preserving release-tagged and channel-protected versions including `test`. |\n| `Release: Build Companion Artifact` | `.github/workflows/build-companion.yml` | Builds companion release artifacts for a new unique version or prerelease candidate in the public distribution repository. |\n| `Release: Promote Companion Release` | `.github/workflows/promote-companion-release.yml` | Moves an existing companion release onto one or more update channels. |\n| `Deploy: Website` | `.github/workflows/website-deploy.yml` | Builds the website and deploys `website/public/` to Cloudflare Pages. |\n| `Security: Dependency Audit` | `.github/workflows/dependency-security.yml` | Runs scheduled and manual dependency vulnerability audits. |\n| `Security: Docker Image Scan` | `.github/workflows/docker-image-security-scan.yml` | Builds the current main image, forces a fresh Debian package-layer rebuild for that run, and scans it for newly disclosed vulnerabilities. |\n| `Admin: Sync Labels` | `.github/workflows/sync-labels.yml` | Synchronizes repository labels from `.github/labels.yml` without deleting unmanaged labels. |\n\nGitHub also shows repository-level features such as `Dependabot updates` and `Dependency graph`.\n\nThose are not repository workflows, so their display names are not controlled by these YAML files.\n\n## CI: Test\n\n`CI: Test` is the main validation workflow for pushes to `main`, pull requests against `main`, and manual dispatch.\n\nIt first detects which top-level product areas changed, then fans out only the relevant jobs for:\n\n- backend\n- frontend\n- frontend Playwright Chromium smoke\n- frontend Playwright Firefox markdown coverage on pushes to `main` and manual runs\n- companion\n\nManual dispatch runs all three areas.\n\nThe workflow ends with a single gate job so branch protection can depend on one stable required check instead of a changing set of per-area jobs.\n\nIn the backend job, regular tests run under `pytest-xdist` for throughput, while `@performance` tests run in a separate serial pass so wall-clock assertions are not distorted by parallel worker contention.\n\nFor frontend coverage, the workflow is intentionally layered:\n\n- the `frontend` job keeps the fast TypeScript, lint, and Vitest checks in the main PR path\n- the `frontend-e2e` job runs a bounded Playwright Chromium smoke slice on frontend changes\n- the `frontend-e2e-firefox` job runs the markdown editor Playwright slice only on pushes to `main` and manual dispatch\n\nThat split keeps pull-request runtime under control while still protecting the browser-sensitive editing workflows that unit tests do not cover.\n\nThe current companion test job does not call `./scripts/test`.\nIt runs explicit steps for Node install, companion TypeScript type checking, and `cargo test`.\nThat means the local Windows GNU cross-check in `./scripts/test` does not currently run in `CI: Test`.\n\n### Caching Model\n\nThe test workflow uses layered caching to reduce repeated setup work while keeping dependency inputs explicit.\n\nCurrent cache layers include:\n\n- `backend/.venv` caching keyed by the resolved backend requirement files and Python version.\n- `backend/.mypy_cache` caching keyed by backend Python source changes.\n- `actions/setup-node` npm download caching for frontend and companion jobs.\n- `frontend/node_modules` caching keyed by `frontend/package-lock.json`.\n- Rust build caching for `companion/src-tauri`.\n\nTreat those cache keys as reviewed dependency inputs, not as disposable generated noise.\n\nWhen dependency manifests or lockfiles change, commit the corresponding lockfile updates in the same pull request so cache invalidation and dependency review stay aligned.\n\n### Local Parity\n\nFor fast local iteration, use `./scripts/test`.\n\nWhen you want a closer CI-style pass, run the per-subsystem checks from [Test Strategy Overview](../test-strategy-overview/) and keep lockfile-driven installs intact.\n\nFor frontend work, that usually means:\n\n- `cd frontend \u0026\u0026 npm test` for the default Vitest suite\n- `cd frontend \u0026\u0026 npm run test:e2e` for the default Chromium browser pass\n\n`./scripts/test` now includes a local companion Windows GNU target compatibility check.\nThat check is intentionally a local validation aid, not part of the current `CI: Test` workflow contract.\n\n## CI: Lint\n\n`CI: Lint` applies the same change-detection pattern, then runs the repository's static checks for only the affected areas.\n\nCurrent coverage includes:\n\n- backend Ruff checks and formatting validation.\n- frontend Biome validation.\n- companion Clippy, Rustfmt, and Biome validation.\n\nThe lint workflow does not run the local companion Windows GNU cross-check either.\nThat cross-target validation is currently a local developer workflow check, while actual Windows artifact creation remains in the release workflow.\n\nThe workflow also ends with one gate job so branch protection can depend on a stable result.\n\n## Runner Distro Policy\n\nSambee does not require every GitHub Actions job to run on the same base distro.\n\nInstead, the rule is:\n\n- jobs that validate production-like runtime behavior or install native runtime dependencies should follow the same Debian family used by the production image and the dev container\n- jobs that only run language-level checks, dependency audits, repository automation, or other host-agnostic validation can stay on `ubuntu-latest`\n\nCurrent Debian-family jobs include:\n\n- the backend job in `CI: Test`\n- the `validate-tests` job in `Release: Create Docker Image`\n\nThe backend job builds the `backend-test` Docker target, which inherits the same runtime base as production. It runs mypy and the backend test suites inside that target, including when a Python image or other runtime input changes. The release validation job uses the pinned Debian-based Python container because `scripts/install-system-deps` requires distro-provided ImageMagick 7, while the default Ubuntu GitHub-hosted runner image still resolves `imagemagick` to ImageMagick 6.\n\n## Shared Runtime Targets\n\nThe root `Dockerfile` defines a shared `runtime-base` target. Production and the VS Code dev container both inherit that target, so they use the same pinned Python image and shared runtime package-installation policy.\n\nBefore building targets, Docker validation confirms that every Python image reference in the Dockerfile uses the same tag and digest. This keeps the native wheel-builder aligned with the shared runtime when Dependabot updates the Python image.\n\n`CI: Validate Docker Image` builds and reports the following values for the production target on each supported image platform and for the devcontainer target on Linux AMD64:\n\n- Python version.\n- `sqlite3` module version.\n- Debian `libsqlite3-0` package version.\n\nThe workflow passes a unique APT refresh key to each build, which intentionally refreshes Debian packages instead of reusing an older cached upgrade layer. The reported versions are evidence of the resolved native runtime; they are not required to match across images built at different times.\n\nCurrent jobs that intentionally remain on `ubuntu-latest` include:\n\n- change-detection, label-sync, and website deployment workflows\n- pure Python lint, lockfile freshness, and dependency-audit workflows\n- frontend-only and companion-only validation workflows\n- Docker build, smoke-test, and vulnerability-scan workflows, where the distro-sensitive logic runs inside the built image rather than on the host runner\n\nWhen adding or changing a workflow, treat runner distro as part of the test contract whenever a job installs OS packages or validates native behavior.\n\n## CI: Check Backend Lockfiles\n\n`CI: Check Backend Lockfiles` protects the reviewed Python dependency workflow.\n\nIt runs `scripts/refresh-backend-lockfiles --check` on pushes, pull requests, and manual runs that touch backend requirement inputs, generated lockfiles, or the refresh script itself.\n\nUse this as the fast failure signal when requirement files and generated lockfiles drift apart.\n\nFor the broader dependency-update workflow, use [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/).\n\n## Admin: Sync Labels\n\n`Admin: Sync Labels` keeps repository labels aligned with `.github/labels.yml`.\n\nIt is intentionally conservative.\n\n- Dependabot-related labels should stay declared in `.github/labels.yml`.\n- The workflow uses `skip-delete: true`, so labels not declared there are left alone.\n\nThat keeps automation-owned labels deterministic without forcing the repository to delete every manually created label.\n\n## Related Workflow Docs\n\nUse the more specific pages for the workflows that have dedicated operational guidance:\n\n- [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/)\n- [Docker Release Overview](../../release-and-versioning/docker-release-overview/)\n- [Companion Release Overview](../../release-and-versioning/companion-release-overview/)\n- [Set Up Cloudflare Pages Publishing](../../../website-dev-guide/setup-and-operations/set-up-cloudflare-pages-publishing/)\n", "1.0": "+++\ntitle = \"CI Workflows and Repository Automation\"\n+++\n\nUse this page to understand the GitHub Actions workflows contributors hit most often and to keep the workflow list grouped predictably in the GitHub UI.\n\n## Naming Convention\n\nGitHub lists workflows by the top-level `name` field.\n\nSambee groups workflow display names by operational purpose using `Area: Subject`.\n\nCurrent workflow groups are:\n\n- `CI`.\n- `Release`.\n- `Deploy`.\n- `Security`.\n- `Admin`.\n\nKeep new names short, stable, and grouped by what the workflow does rather than by how it is triggered.\n\n## Workflow Map\n\n| Display name | File | Role |\n|---|---|---|\n| `CI: Test` | `.github/workflows/test.yml` | Runs the main backend, frontend, and companion validation suites. |\n| `CI: Lint` | `.github/workflows/lint.yml` | Runs repository lint and formatting checks across backend, frontend, and companion. |\n| `CI: Check Backend Lockfiles` | `.github/workflows/check-backend-lockfiles.yml` | Verifies that committed backend lockfiles still match the reviewed requirement sources. |\n| `CI: Validate Docker Image` | `.github/workflows/docker-image-validate.yml` | Builds and smoke-tests the production container image on pull requests, pushes, and manual runs. |\n| `Release: Publish Docker Image` | `.github/workflows/docker-image-publish.yml` | Promotes an existing preview candidate onto release tags and the `stable` or `beta` channel, then signs the digest. |\n| `Release: Create Docker Image` | `.github/workflows/docker-image-preview-publish.yml` | Builds, validates, publishes, and signs a new preview image, forcing a fresh Debian package-layer rebuild for that run before moving the `test` channel tag. |\n| `Maintenance: Backfill Docker Release Tags` | `.github/workflows/docker-image-backfill.yml` | Reattaches release tags and release-channel aliases to an already published candidate digest for an existing release. |\n| `Maintenance: Clean Up Docker Package Versions` | `.github/workflows/docker-image-cleanup.yml` | Removes unprotected SHA-tagged preview GHCR package versions, prunes stale signature artifacts, and deletes unreferenced untagged package versions while preserving release-tagged and channel-protected versions including `test`. |\n| `Release: Build Companion Artifact` | `.github/workflows/build-companion.yml` | Builds companion release artifacts for a new unique version or prerelease candidate in the public distribution repository. |\n| `Release: Promote Companion Release` | `.github/workflows/promote-companion-release.yml` | Moves an existing companion release onto one or more update channels. |\n| `Deploy: Website` | `.github/workflows/website-deploy.yml` | Builds the website and deploys `website/public/` to Cloudflare Pages. |\n| `Security: Dependency Audit` | `.github/workflows/dependency-security.yml` | Runs scheduled and manual dependency vulnerability audits. |\n| `Security: Docker Image Scan` | `.github/workflows/docker-image-security-scan.yml` | Builds the current main image, forces a fresh Debian package-layer rebuild for that run, and scans it for newly disclosed vulnerabilities. |\n| `Admin: Sync Labels` | `.github/workflows/sync-labels.yml` | Synchronizes repository labels from `.github/labels.yml` without deleting unmanaged labels. |\n\nGitHub also shows repository-level features such as `Dependabot updates` and `Dependency graph`.\n\nThose are not repository workflows, so their display names are not controlled by these YAML files.\n\n## CI: Test\n\n`CI: Test` is the main validation workflow for pushes to `main`, pull requests against `main`, and manual dispatch.\n\nIt first detects which top-level product areas changed, then fans out only the relevant jobs for:\n\n- backend\n- frontend\n- frontend Playwright Chromium smoke\n- frontend Playwright Firefox markdown coverage on pushes to `main` and manual runs\n- companion\n\nManual dispatch runs all three areas.\n\nThe workflow ends with a single gate job so branch protection can depend on one stable required check instead of a changing set of per-area jobs.\n\nIn the backend job, regular tests run under `pytest-xdist` for throughput, while `@performance` tests run in a separate serial pass so wall-clock assertions are not distorted by parallel worker contention.\n\nFor frontend coverage, the workflow is intentionally layered:\n\n- the `frontend` job keeps the fast TypeScript, lint, and Vitest checks in the main PR path\n- the `frontend-e2e` job runs a bounded Playwright Chromium smoke slice on frontend changes\n- the `frontend-e2e-firefox` job runs the markdown editor Playwright slice only on pushes to `main` and manual dispatch\n\nThat split keeps pull-request runtime under control while still protecting the browser-sensitive editing workflows that unit tests do not cover.\n\nThe current companion test job does not call `./scripts/test`.\nIt runs explicit steps for Node install, companion TypeScript type checking, and `cargo test`.\nThat means the local Windows GNU cross-check in `./scripts/test` does not currently run in `CI: Test`.\n\n### Caching Model\n\nThe test workflow uses layered caching to reduce repeated setup work while keeping dependency inputs explicit.\n\nCurrent cache layers include:\n\n- `backend/.venv` caching keyed by the resolved backend requirement files and Python version.\n- `backend/.mypy_cache` caching keyed by backend Python source changes.\n- `actions/setup-node` npm download caching for frontend and companion jobs.\n- `frontend/node_modules` caching keyed by `frontend/package-lock.json`.\n- Rust build caching for `companion/src-tauri`.\n\nTreat those cache keys as reviewed dependency inputs, not as disposable generated noise.\n\nWhen dependency manifests or lockfiles change, commit the corresponding lockfile updates in the same pull request so cache invalidation and dependency review stay aligned.\n\n### Local Parity\n\nFor fast local iteration, use `./scripts/test`.\n\nWhen you want a closer CI-style pass, run the per-subsystem checks from [Test Strategy Overview](../test-strategy-overview/) and keep lockfile-driven installs intact.\n\nFor frontend work, that usually means:\n\n- `cd frontend \u0026\u0026 npm test` for the default Vitest suite\n- `cd frontend \u0026\u0026 npm run test:e2e` for the default Chromium browser pass\n\n`./scripts/test` now includes a local companion Windows GNU target compatibility check.\nThat check is intentionally a local validation aid, not part of the current `CI: Test` workflow contract.\n\n## CI: Lint\n\n`CI: Lint` applies the same change-detection pattern, then runs the repository's static checks for only the affected areas.\n\nCurrent coverage includes:\n\n- backend Ruff checks and formatting validation.\n- frontend Biome validation.\n- companion Clippy, Rustfmt, and Biome validation.\n\nThe lint workflow does not run the local companion Windows GNU cross-check either.\nThat cross-target validation is currently a local developer workflow check, while actual Windows artifact creation remains in the release workflow.\n\nThe workflow also ends with one gate job so branch protection can depend on a stable result.\n\n## Runner Distro Policy\n\nSambee does not require every GitHub Actions job to run on the same base distro.\n\nInstead, the rule is:\n\n- jobs that validate production-like runtime behavior or install native runtime dependencies should follow the same Debian family used by the production image and the dev container\n- jobs that only run language-level checks, dependency audits, repository automation, or other host-agnostic validation can stay on `ubuntu-latest`\n\nCurrent Debian-family jobs include:\n\n- the backend job in `CI: Test`\n- the `validate-tests` job in `Release: Create Docker Image`\n\nThe backend job builds the `backend-test` Docker target, which inherits the same runtime base as production. It runs mypy and the backend test suites inside that target, including when a Python image or other runtime input changes. The release validation job uses the pinned Debian-based Python container because `scripts/install-system-deps` requires distro-provided ImageMagick 7, while the default Ubuntu GitHub-hosted runner image still resolves `imagemagick` to ImageMagick 6.\n\n## Shared Runtime Targets\n\nThe root `Dockerfile` defines a shared `runtime-base` target. Production and the VS Code dev container both inherit that target, so they use the same pinned Python image and shared runtime package-installation policy.\n\nBefore building targets, Docker validation confirms that every Python image reference in the Dockerfile uses the same tag and digest. This keeps the native wheel-builder aligned with the shared runtime when Dependabot updates the Python image.\n\n`CI: Validate Docker Image` builds and reports the following values for the production target on each supported image platform and for the devcontainer target on Linux AMD64:\n\n- Python version.\n- `sqlite3` module version.\n- Debian `libsqlite3-0` package version.\n\nThe workflow passes a unique APT refresh key to each build, which intentionally refreshes Debian packages instead of reusing an older cached upgrade layer. The reported versions are evidence of the resolved native runtime; they are not required to match across images built at different times.\n\nCurrent jobs that intentionally remain on `ubuntu-latest` include:\n\n- change-detection, label-sync, and website deployment workflows\n- pure Python lint, lockfile freshness, and dependency-audit workflows\n- frontend-only and companion-only validation workflows\n- Docker build, smoke-test, and vulnerability-scan workflows, where the distro-sensitive logic runs inside the built image rather than on the host runner\n\nWhen adding or changing a workflow, treat runner distro as part of the test contract whenever a job installs OS packages or validates native behavior.\n\n## CI: Check Backend Lockfiles\n\n`CI: Check Backend Lockfiles` protects the reviewed Python dependency workflow.\n\nIt runs `scripts/refresh-backend-lockfiles --check` on pushes, pull requests, and manual runs that touch backend requirement inputs, generated lockfiles, or the refresh script itself.\n\nUse this as the fast failure signal when requirement files and generated lockfiles drift apart.\n\nFor the broader dependency-update workflow, use [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/).\n\n## Admin: Sync Labels\n\n`Admin: Sync Labels` keeps repository labels aligned with `.github/labels.yml`.\n\nIt is intentionally conservative.\n\n- Dependabot-related labels should stay declared in `.github/labels.yml`.\n- The workflow uses `skip-delete: true`, so labels not declared there are left alone.\n\nThat keeps automation-owned labels deterministic without forcing the repository to delete every manually created label.\n\n## Related Workflow Docs\n\nUse the more specific pages for the workflows that have dedicated operational guidance:\n\n- [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/)\n- [Docker Release Overview](../../release-and-versioning/docker-release-overview/)\n- [Companion Release Overview](../../release-and-versioning/companion-release-overview/)\n- [Set Up Cloudflare Pages Publishing](../../../website-dev-guide/setup-and-operations/set-up-cloudflare-pages-publishing/)\n", "2.0": "+++\ntitle = \"CI Workflows and Repository Automation\"\n+++\n\nUse this page to understand the GitHub Actions workflows contributors hit most often and to keep the workflow list grouped predictably in the GitHub UI.\n\n## Naming Convention\n\nGitHub lists workflows by the top-level `name` field.\n\nSambee groups workflow display names by operational purpose using `Area: Subject`.\n\nCurrent workflow groups are:\n\n- `CI`.\n- `Release`.\n- `Deploy`.\n- `Security`.\n- `Admin`.\n\nKeep new names short, stable, and grouped by what the workflow does rather than by how it is triggered.\n\n## Workflow Map\n\n| Display name | File | Role |\n|---|---|---|\n| `CI: Test` | `.github/workflows/test.yml` | Runs the main backend, frontend, and companion validation suites. |\n| `CI: Lint` | `.github/workflows/lint.yml` | Runs repository lint and formatting checks across backend, frontend, and companion. |\n| `CI: Check Backend Lockfiles` | `.github/workflows/check-backend-lockfiles.yml` | Verifies that committed backend lockfiles still match the reviewed requirement sources. |\n| `CI: Validate Docker Image` | `.github/workflows/docker-image-validate.yml` | Builds and smoke-tests the production container image on pull requests, pushes, and manual runs. |\n| `Release: Publish Docker Image` | `.github/workflows/docker-image-publish.yml` | Promotes an existing preview candidate onto release tags and the `stable` or `beta` channel, then signs the digest. |\n| `Release: Create Docker Image` | `.github/workflows/docker-image-preview-publish.yml` | Builds, validates, publishes, and signs a new preview image, forcing a fresh Debian package-layer rebuild for that run before moving the `test` channel tag. |\n| `Maintenance: Backfill Docker Release Tags` | `.github/workflows/docker-image-backfill.yml` | Reattaches release tags and release-channel aliases to an already published candidate digest for an existing release. |\n| `Maintenance: Clean Up Docker Package Versions` | `.github/workflows/docker-image-cleanup.yml` | Removes unprotected SHA-tagged preview GHCR package versions, prunes stale signature artifacts, and deletes unreferenced untagged package versions while preserving release-tagged and channel-protected versions including `test`. |\n| `Maintenance: Clean Up Actions Caches` | `.github/workflows/cleanup-actions-caches.yml` | Removes closed-PR caches and superseded known cache keys without disabling warm caches for active builds. |\n| `Maintenance: Signal Closed PR Cache Cleanup` | `.github/workflows/signal-closed-pr-cache-cleanup.yml` | Triggers cache cleanup after a pull request closes without granting the pull request write access. |\n| `Release: Build Companion Artifact` | `.github/workflows/build-companion.yml` | Builds companion release artifacts for a new unique version or prerelease candidate in the public distribution repository. |\n| `Release: Promote Companion Release` | `.github/workflows/promote-companion-release.yml` | Moves an existing companion release onto one or more update channels. |\n| `Deploy: Website` | `.github/workflows/website-deploy.yml` | Builds the website and deploys `website/public/` to Cloudflare Pages. |\n| `Security: Dependency Audit` | `.github/workflows/dependency-security.yml` | Runs scheduled and manual dependency vulnerability audits. |\n| `Security: Docker Image Scan` | `.github/workflows/docker-image-security-scan.yml` | Builds the current main image, forces a fresh Debian package-layer rebuild for that run, and scans it for newly disclosed vulnerabilities. |\n| `Admin: Sync Labels` | `.github/workflows/sync-labels.yml` | Synchronizes repository labels from `.github/labels.yml` without deleting unmanaged labels. |\n\nGitHub also shows repository-level features such as `Dependabot updates` and `Dependency graph`.\n\nThose are not repository workflows, so their display names are not controlled by these YAML files.\n\n## CI: Test\n\n`CI: Test` is the main validation workflow for pushes to `main`, pull requests against `main`, and manual dispatch.\n\nIt first detects which top-level product areas changed, then fans out only the relevant jobs for:\n\n- backend\n- frontend\n- frontend Playwright Chromium smoke\n- frontend Playwright Firefox markdown coverage on pushes to `main` and manual runs\n- companion\n\nManual dispatch runs all three areas.\n\nThe workflow ends with a single gate job so branch protection can depend on one stable required check instead of a changing set of per-area jobs.\n\nIn the backend job, regular tests run under `pytest-xdist` for throughput, while `@performance` tests run in a separate serial pass so wall-clock assertions are not distorted by parallel worker contention.\n\nFor frontend coverage, the workflow is intentionally layered:\n\n- the `frontend` job keeps the fast TypeScript, lint, and Vitest checks in the main PR path\n- the `frontend-e2e` job runs a bounded Playwright Chromium smoke slice on frontend changes\n- the `frontend-e2e-firefox` job runs the markdown editor Playwright slice only on pushes to `main` and manual dispatch\n\nThat split keeps pull-request runtime under control while still protecting the browser-sensitive editing workflows that unit tests do not cover.\n\nThe current companion test job does not call `./scripts/test`.\nIt runs explicit steps for Node install, companion TypeScript type checking, and `cargo test`.\nThat means the local Windows GNU cross-check in `./scripts/test` does not currently run in `CI: Test`.\n\n### Caching Model\n\nThe test workflow uses layered caching to reduce repeated setup work while keeping dependency inputs explicit.\n\nCurrent cache layers include:\n\n- `backend/.venv` caching keyed by the resolved backend requirement files and Python version.\n- `backend/.mypy_cache` caching keyed by backend Python source changes.\n- `actions/setup-node` npm download caching for frontend and companion jobs.\n- `frontend/node_modules` caching keyed by `frontend/package-lock.json`.\n- Rust build caching for `companion/src-tauri`.\n\nTreat those cache keys as reviewed dependency inputs, not as disposable generated noise.\n\nWhen dependency manifests or lockfiles change, commit the corresponding lockfile updates in the same pull request so cache invalidation and dependency review stay aligned.\n\n### Cache Retention\n\n`Maintenance: Clean Up Actions Caches` runs after cache-producing workflows finish and daily as a fallback. When a pull request closes, an unprivileged signal workflow runs first; its completion triggers the same cleanup. A manual run defaults to a dry run; select **Delete eligible caches** to apply the policy. Its run summary lists selected entries and the amount of storage reclaimed. The cleanup reads only trusted code from `main`, and does not run pull-request code with cache-deletion permissions.\n\nThe policy keeps the newest known cache family on `main` and each open pull request. It removes superseded Rust and website cache keys, and deletes all caches for a closed pull request after its builds finish. It skips refs with active builds and leaves unrecognized keys, including individual BuildKit blobs on active refs, alone. GitHub's normal expiration still applies to those unclassified entries. The job deletes caches by ID so a pull request's copy cannot inadvertently delete an identically keyed cache on `main`.\n\nReview the dry-run report before changing cache-family rules. If active caches alone approach the repository storage limit, raise the limit or accept more cache misses: deleting their newest copies would make CI slower. Cleanup happens after cache uploads, so it cannot prevent a full repository from evicting caches during an upload.\n\n### Local Parity\n\nFor fast local iteration, use `./scripts/test`.\n\nWhen you want a closer CI-style pass, run the per-subsystem checks from [Test Strategy Overview](../test-strategy-overview/) and keep lockfile-driven installs intact.\n\nFor frontend work, that usually means:\n\n- `cd frontend \u0026\u0026 npm test` for the default Vitest suite\n- `cd frontend \u0026\u0026 npm run test:e2e` for the default Chromium browser pass\n\n`./scripts/test` now includes a local companion Windows GNU target compatibility check.\nThat check is intentionally a local validation aid, not part of the current `CI: Test` workflow contract.\n\n## CI: Lint\n\n`CI: Lint` applies the same change-detection pattern, then runs the repository's static checks for only the affected areas.\n\nCurrent coverage includes:\n\n- backend Ruff checks and formatting validation.\n- frontend Biome validation.\n- companion Clippy, Rustfmt, and Biome validation.\n\nThe lint workflow does not run the local companion Windows GNU cross-check either.\nThat cross-target validation is currently a local developer workflow check, while actual Windows artifact creation remains in the release workflow.\n\nThe workflow also ends with one gate job so branch protection can depend on a stable result.\n\n## Runner Distro Policy\n\nSambee does not require every GitHub Actions job to run on the same base distro.\n\nInstead, the rule is:\n\n- jobs that validate production-like runtime behavior or install native runtime dependencies should follow the same Debian family used by the production image and the dev container\n- jobs that only run language-level checks, dependency audits, repository automation, or other host-agnostic validation can stay on `ubuntu-latest`\n\nCurrent Debian-family jobs include:\n\n- the backend job in `CI: Test`\n- the `validate-tests` job in `Release: Create Docker Image`\n\nThe backend job builds the `backend-test` Docker target, which inherits the same runtime base as production. It runs mypy and the backend test suites inside that target, including when a Python image or other runtime input changes. The release validation job uses the pinned Debian-based Python container because `scripts/install-system-deps` requires distro-provided ImageMagick 7, while the default Ubuntu GitHub-hosted runner image still resolves `imagemagick` to ImageMagick 6.\n\n## Shared Runtime Targets\n\nThe root `Dockerfile` defines a shared `runtime-base` target. Production and the VS Code dev container both inherit that target, so they use the same pinned Python image and shared runtime package-installation policy.\n\nBefore building targets, Docker validation confirms that every Python image reference in the Dockerfile uses the same tag and digest. This keeps the native wheel-builder aligned with the shared runtime when Dependabot updates the Python image.\n\n`CI: Validate Docker Image` builds and reports the following values for the production target on each supported image platform and for the devcontainer target on Linux AMD64:\n\n- Python version.\n- `sqlite3` module version.\n- Debian `libsqlite3-0` package version.\n\nThe workflow passes a unique APT refresh key to each build, which intentionally refreshes Debian packages instead of reusing an older cached upgrade layer. The reported versions are evidence of the resolved native runtime; they are not required to match across images built at different times.\n\nCurrent jobs that intentionally remain on `ubuntu-latest` include:\n\n- change-detection, label-sync, and website deployment workflows\n- pure Python lint, lockfile freshness, and dependency-audit workflows\n- frontend-only and companion-only validation workflows\n- Docker build, smoke-test, and vulnerability-scan workflows, where the distro-sensitive logic runs inside the built image rather than on the host runner\n\nWhen adding or changing a workflow, treat runner distro as part of the test contract whenever a job installs OS packages or validates native behavior.\n\n## CI: Check Backend Lockfiles\n\n`CI: Check Backend Lockfiles` protects the reviewed Python dependency workflow.\n\nIt runs `scripts/refresh-backend-lockfiles --check` on pushes, pull requests, and manual runs that touch backend requirement inputs, generated lockfiles, or the refresh script itself.\n\nUse this as the fast failure signal when requirement files and generated lockfiles drift apart.\n\nFor the broader dependency-update workflow, use [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/).\n\n## Admin: Sync Labels\n\n`Admin: Sync Labels` keeps repository labels aligned with `.github/labels.yml`.\n\nIt is intentionally conservative.\n\n- Dependabot-related labels should stay declared in `.github/labels.yml`.\n- The workflow uses `skip-delete: true`, so labels not declared there are left alone.\n\nThat keeps automation-owned labels deterministic without forcing the repository to delete every manually created label.\n\n## Related Workflow Docs\n\nUse the more specific pages for the workflows that have dedicated operational guidance:\n\n- [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/)\n- [Docker Release Overview](../../release-and-versioning/docker-release-overview/)\n- [Companion Release Overview](../../release-and-versioning/companion-release-overview/)\n- [Set Up Cloudflare Pages Publishing](../../../website-dev-guide/setup-and-operations/set-up-cloudflare-pages-publishing/)\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:developer-guide/contribution-workflows", "parent_id": "book:developer-guide", "depth": 1, "kind": "section", "label": "contribution-workflows", "title": "Contribution Workflows", "path": "developer-guide/contribution-workflows", "has_children": true, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Contribution Workflows\"\n+++\n\nThis section is about how to approach a Sambee change before it becomes a pile of disconnected file edits.\n\nStart with:\n\n- [How to Plan and Review a Change](./how-to-plan-and-review-a-change/)\n\nUse this section when you are scoping work, preparing a review, or deciding whether a change also needs wider testing or version-sensitive follow-up.\n", "0.8": "+++\ntitle = \"Contribution Workflows\"\n+++\n\nThis section is about how to approach a Sambee change before it becomes a pile of disconnected file edits.\n\nStart with:\n\n- [How to Plan and Review a Change](./how-to-plan-and-review-a-change/)\n\nUse this section when you are scoping work, preparing a review, or deciding whether a change also needs wider testing or version-sensitive follow-up.\n", "0.9": "+++\ntitle = \"Contribution Workflows\"\n+++\n\nThis section is about how to approach a Sambee change before it becomes a pile of disconnected file edits.\n\nStart with:\n\n- [How to Plan and Review a Change](./how-to-plan-and-review-a-change/)\n\nUse this section when you are scoping work, preparing a review, or deciding whether a change also needs wider testing or version-sensitive follow-up.\n", "1.0": "+++\ntitle = \"Contribution Workflows\"\n+++\n\nThis section is about how to approach a Sambee change before it becomes a pile of disconnected file edits.\n\nStart with:\n\n- [How to Plan and Review a Change](./how-to-plan-and-review-a-change/)\n\nUse this section when you are scoping work, preparing a review, or deciding whether a change also needs wider testing or version-sensitive follow-up.\n", "2.0": "+++\ntitle = \"Contribution Workflows\"\n+++\n\nThis section is about how to approach a Sambee change before it becomes a pile of disconnected file edits.\n\nStart with:\n\n- [How to Plan and Review a Change](./how-to-plan-and-review-a-change/)\n\nUse this section when you are scoping work, preparing a review, or deciding whether a change also needs wider testing or version-sensitive follow-up.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/contribution-workflows/how-to-plan-and-review-a-change", "parent_id": "section:developer-guide/contribution-workflows", "depth": 2, "kind": "page", "label": "how-to-plan-and-review-a-change", "title": "How To Plan And Review A Change", "path": "developer-guide/contribution-workflows/how-to-plan-and-review-a-change", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"How to Plan and Review a Change\"\n+++\n\nThe safest Sambee changes start from the contract that is changing, not from the first file you happened to open.\n\n## Start with the Contract\n\nAsk which part of the system's behavior is actually moving.\n\n- browser app workflow\n- backend API or SMB behavior\n- companion trust, local-drive, or native-app editing behavior\n- release-sensitive metadata or dependency policy\n\nThat answer tells you which subsystems might need to move together.\n\n## Scope the Change by Boundary\n\nBefore you implement anything, identify:\n\n1. which subsystem changes directly\n2. which other subsystem consumes the changed contract\n\nFor example:\n\n- a backend response-shape change usually also needs frontend service updates and matching validation\n- a companion pairing change may affect browser app behavior and tests in more than one project\n\n## Prefer the Smallest Change That Fixes the Right Problem\n\n- fix the root cause instead of layering extra workarounds on top\n- avoid mixing unrelated refactors into a behavior change unless they are required for correctness\n- do not treat lockfiles, version metadata, or generated navigation inputs as incidental noise when they are part of the reviewed workflow\n\n## Review with Regression Risk in Mind\n\nThe highest-value review questions are usually:\n\n- did the changed contract stay coherent across browser app, backend, and companion?\n- are new or changed validation checks proportional to the risk?\n- did a version-sensitive or dependency-sensitive workflow change without the matching metadata review?\n\n## Typical Review Checklist\n\n- the change goal is stated in terms of behavior, not just files touched\n- cross-boundary contracts were updated together\n- validation covers the actual risk surface\n- release-sensitive files were reviewed intentionally when touched\n", "0.8": "+++\ntitle = \"How to Plan and Review a Change\"\n+++\n\nThe safest Sambee changes start from the contract that is changing, not from the first file you happened to open.\n\n## Start with the Contract\n\nAsk which part of the system's behavior is actually moving.\n\n- browser app workflow\n- backend API or SMB behavior\n- companion trust, local-drive, or native-app editing behavior\n- release-sensitive metadata or dependency policy\n\nThat answer tells you which subsystems might need to move together.\n\n## Scope the Change by Boundary\n\nBefore you implement anything, identify:\n\n1. which subsystem changes directly\n2. which other subsystem consumes the changed contract\n\nFor example:\n\n- a backend response-shape change usually also needs frontend service updates and matching validation\n- a companion pairing change may affect browser app behavior and tests in more than one project\n\n## Prefer the Smallest Change That Fixes the Right Problem\n\n- fix the root cause instead of layering extra workarounds on top\n- avoid mixing unrelated refactors into a behavior change unless they are required for correctness\n- do not treat lockfiles, version metadata, or generated navigation inputs as incidental noise when they are part of the reviewed workflow\n\n## Review with Regression Risk in Mind\n\nThe highest-value review questions are usually:\n\n- did the changed contract stay coherent across browser app, backend, and companion?\n- are new or changed validation checks proportional to the risk?\n- did a version-sensitive or dependency-sensitive workflow change without the matching metadata review?\n\n## Typical Review Checklist\n\n- the change goal is stated in terms of behavior, not just files touched\n- cross-boundary contracts were updated together\n- validation covers the actual risk surface\n- release-sensitive files were reviewed intentionally when touched\n", "0.9": "+++\ntitle = \"How to Plan and Review a Change\"\n+++\n\nThe safest Sambee changes start from the contract that is changing, not from the first file you happened to open.\n\n## Start with the Contract\n\nAsk which part of the system's behavior is actually moving.\n\n- browser app workflow\n- backend API or SMB behavior\n- companion trust, local-drive, or native-app editing behavior\n- release-sensitive metadata or dependency policy\n\nThat answer tells you which subsystems might need to move together.\n\n## Scope the Change by Boundary\n\nBefore you implement anything, identify:\n\n1. which subsystem changes directly\n2. which other subsystem consumes the changed contract\n\nFor example:\n\n- a backend response-shape change usually also needs frontend service updates and matching validation\n- a companion pairing change may affect browser app behavior and tests in more than one project\n\n## Prefer the Smallest Change That Fixes the Right Problem\n\n- fix the root cause instead of layering extra workarounds on top\n- avoid mixing unrelated refactors into a behavior change unless they are required for correctness\n- do not treat lockfiles, version metadata, or generated navigation inputs as incidental noise when they are part of the reviewed workflow\n\n## Review with Regression Risk in Mind\n\nThe highest-value review questions are usually:\n\n- did the changed contract stay coherent across browser app, backend, and companion?\n- are new or changed validation checks proportional to the risk?\n- did a version-sensitive or dependency-sensitive workflow change without the matching metadata review?\n\n## Typical Review Checklist\n\n- the change goal is stated in terms of behavior, not just files touched\n- cross-boundary contracts were updated together\n- validation covers the actual risk surface\n- release-sensitive files were reviewed intentionally when touched\n", "1.0": "+++\ntitle = \"How to Plan and Review a Change\"\n+++\n\nThe safest Sambee changes start from the contract that is changing, not from the first file you happened to open.\n\n## Start with the Contract\n\nAsk which part of the system's behavior is actually moving.\n\n- browser app workflow\n- backend API or SMB behavior\n- companion trust, local-drive, or native-app editing behavior\n- release-sensitive metadata or dependency policy\n\nThat answer tells you which subsystems might need to move together.\n\n## Scope the Change by Boundary\n\nBefore you implement anything, identify:\n\n1. which subsystem changes directly\n2. which other subsystem consumes the changed contract\n\nFor example:\n\n- a backend response-shape change usually also needs frontend service updates and matching validation\n- a companion pairing change may affect browser app behavior and tests in more than one project\n\n## Prefer the Smallest Change That Fixes the Right Problem\n\n- fix the root cause instead of layering extra workarounds on top\n- avoid mixing unrelated refactors into a behavior change unless they are required for correctness\n- do not treat lockfiles, version metadata, or generated navigation inputs as incidental noise when they are part of the reviewed workflow\n\n## Review with Regression Risk in Mind\n\nThe highest-value review questions are usually:\n\n- did the changed contract stay coherent across browser app, backend, and companion?\n- are new or changed validation checks proportional to the risk?\n- did a version-sensitive or dependency-sensitive workflow change without the matching metadata review?\n\n## Typical Review Checklist\n\n- the change goal is stated in terms of behavior, not just files touched\n- cross-boundary contracts were updated together\n- validation covers the actual risk surface\n- release-sensitive files were reviewed intentionally when touched\n", "2.0": "+++\ntitle = \"How to Plan and Review a Change\"\n+++\n\nThe safest Sambee changes start from the contract that is changing, not from the first file you happened to open.\n\n## Start with the Contract\n\nAsk which part of the system's behavior is actually moving.\n\n- browser app workflow\n- backend API or SMB behavior\n- companion trust, local-drive, or native-app editing behavior\n- release-sensitive metadata or dependency policy\n\nThat answer tells you which subsystems might need to move together.\n\n## Scope the Change by Boundary\n\nBefore you implement anything, identify:\n\n1. which subsystem changes directly\n2. which other subsystem consumes the changed contract\n\nFor example:\n\n- a backend response-shape change usually also needs frontend service updates and matching validation\n- a companion pairing change may affect browser app behavior and tests in more than one project\n\n## Prefer the Smallest Change That Fixes the Right Problem\n\n- fix the root cause instead of layering extra workarounds on top\n- avoid mixing unrelated refactors into a behavior change unless they are required for correctness\n- do not treat lockfiles, version metadata, or generated navigation inputs as incidental noise when they are part of the reviewed workflow\n\n## Review with Regression Risk in Mind\n\nThe highest-value review questions are usually:\n\n- did the changed contract stay coherent across browser app, backend, and companion?\n- are new or changed validation checks proportional to the risk?\n- did a version-sensitive or dependency-sensitive workflow change without the matching metadata review?\n\n## Typical Review Checklist\n\n- the change goal is stated in terms of behavior, not just files touched\n- cross-boundary contracts were updated together\n- validation covers the actual risk surface\n- release-sensitive files were reviewed intentionally when touched\n"}, "page_contents": {"0.7": "+++\ntitle = \"How to Plan and Review a Change\"\n+++\n\nThe safest Sambee changes start from the contract that is changing, not from the first file you happened to open.\n\n## Start with the Contract\n\nAsk which part of the system's behavior is actually moving.\n\n- browser app workflow\n- backend API or SMB behavior\n- companion trust, local-drive, or native-app editing behavior\n- release-sensitive metadata or dependency policy\n\nThat answer tells you which subsystems might need to move together.\n\n## Scope the Change by Boundary\n\nBefore you implement anything, identify:\n\n1. which subsystem changes directly\n2. which other subsystem consumes the changed contract\n\nFor example:\n\n- a backend response-shape change usually also needs frontend service updates and matching validation\n- a companion pairing change may affect browser app behavior and tests in more than one project\n\n## Prefer the Smallest Change That Fixes the Right Problem\n\n- fix the root cause instead of layering extra workarounds on top\n- avoid mixing unrelated refactors into a behavior change unless they are required for correctness\n- do not treat lockfiles, version metadata, or generated navigation inputs as incidental noise when they are part of the reviewed workflow\n\n## Review with Regression Risk in Mind\n\nThe highest-value review questions are usually:\n\n- did the changed contract stay coherent across browser app, backend, and companion?\n- are new or changed validation checks proportional to the risk?\n- did a version-sensitive or dependency-sensitive workflow change without the matching metadata review?\n\n## Typical Review Checklist\n\n- the change goal is stated in terms of behavior, not just files touched\n- cross-boundary contracts were updated together\n- validation covers the actual risk surface\n- release-sensitive files were reviewed intentionally when touched\n", "0.8": "+++\ntitle = \"How to Plan and Review a Change\"\n+++\n\nThe safest Sambee changes start from the contract that is changing, not from the first file you happened to open.\n\n## Start with the Contract\n\nAsk which part of the system's behavior is actually moving.\n\n- browser app workflow\n- backend API or SMB behavior\n- companion trust, local-drive, or native-app editing behavior\n- release-sensitive metadata or dependency policy\n\nThat answer tells you which subsystems might need to move together.\n\n## Scope the Change by Boundary\n\nBefore you implement anything, identify:\n\n1. which subsystem changes directly\n2. which other subsystem consumes the changed contract\n\nFor example:\n\n- a backend response-shape change usually also needs frontend service updates and matching validation\n- a companion pairing change may affect browser app behavior and tests in more than one project\n\n## Prefer the Smallest Change That Fixes the Right Problem\n\n- fix the root cause instead of layering extra workarounds on top\n- avoid mixing unrelated refactors into a behavior change unless they are required for correctness\n- do not treat lockfiles, version metadata, or generated navigation inputs as incidental noise when they are part of the reviewed workflow\n\n## Review with Regression Risk in Mind\n\nThe highest-value review questions are usually:\n\n- did the changed contract stay coherent across browser app, backend, and companion?\n- are new or changed validation checks proportional to the risk?\n- did a version-sensitive or dependency-sensitive workflow change without the matching metadata review?\n\n## Typical Review Checklist\n\n- the change goal is stated in terms of behavior, not just files touched\n- cross-boundary contracts were updated together\n- validation covers the actual risk surface\n- release-sensitive files were reviewed intentionally when touched\n", "0.9": "+++\ntitle = \"How to Plan and Review a Change\"\n+++\n\nThe safest Sambee changes start from the contract that is changing, not from the first file you happened to open.\n\n## Start with the Contract\n\nAsk which part of the system's behavior is actually moving.\n\n- browser app workflow\n- backend API or SMB behavior\n- companion trust, local-drive, or native-app editing behavior\n- release-sensitive metadata or dependency policy\n\nThat answer tells you which subsystems might need to move together.\n\n## Scope the Change by Boundary\n\nBefore you implement anything, identify:\n\n1. which subsystem changes directly\n2. which other subsystem consumes the changed contract\n\nFor example:\n\n- a backend response-shape change usually also needs frontend service updates and matching validation\n- a companion pairing change may affect browser app behavior and tests in more than one project\n\n## Prefer the Smallest Change That Fixes the Right Problem\n\n- fix the root cause instead of layering extra workarounds on top\n- avoid mixing unrelated refactors into a behavior change unless they are required for correctness\n- do not treat lockfiles, version metadata, or generated navigation inputs as incidental noise when they are part of the reviewed workflow\n\n## Review with Regression Risk in Mind\n\nThe highest-value review questions are usually:\n\n- did the changed contract stay coherent across browser app, backend, and companion?\n- are new or changed validation checks proportional to the risk?\n- did a version-sensitive or dependency-sensitive workflow change without the matching metadata review?\n\n## Typical Review Checklist\n\n- the change goal is stated in terms of behavior, not just files touched\n- cross-boundary contracts were updated together\n- validation covers the actual risk surface\n- release-sensitive files were reviewed intentionally when touched\n", "1.0": "+++\ntitle = \"How to Plan and Review a Change\"\n+++\n\nThe safest Sambee changes start from the contract that is changing, not from the first file you happened to open.\n\n## Start with the Contract\n\nAsk which part of the system's behavior is actually moving.\n\n- browser app workflow\n- backend API or SMB behavior\n- companion trust, local-drive, or native-app editing behavior\n- release-sensitive metadata or dependency policy\n\nThat answer tells you which subsystems might need to move together.\n\n## Scope the Change by Boundary\n\nBefore you implement anything, identify:\n\n1. which subsystem changes directly\n2. which other subsystem consumes the changed contract\n\nFor example:\n\n- a backend response-shape change usually also needs frontend service updates and matching validation\n- a companion pairing change may affect browser app behavior and tests in more than one project\n\n## Prefer the Smallest Change That Fixes the Right Problem\n\n- fix the root cause instead of layering extra workarounds on top\n- avoid mixing unrelated refactors into a behavior change unless they are required for correctness\n- do not treat lockfiles, version metadata, or generated navigation inputs as incidental noise when they are part of the reviewed workflow\n\n## Review with Regression Risk in Mind\n\nThe highest-value review questions are usually:\n\n- did the changed contract stay coherent across browser app, backend, and companion?\n- are new or changed validation checks proportional to the risk?\n- did a version-sensitive or dependency-sensitive workflow change without the matching metadata review?\n\n## Typical Review Checklist\n\n- the change goal is stated in terms of behavior, not just files touched\n- cross-boundary contracts were updated together\n- validation covers the actual risk surface\n- release-sensitive files were reviewed intentionally when touched\n", "2.0": "+++\ntitle = \"How to Plan and Review a Change\"\n+++\n\nThe safest Sambee changes start from the contract that is changing, not from the first file you happened to open.\n\n## Start with the Contract\n\nAsk which part of the system's behavior is actually moving.\n\n- browser app workflow\n- backend API or SMB behavior\n- companion trust, local-drive, or native-app editing behavior\n- release-sensitive metadata or dependency policy\n\nThat answer tells you which subsystems might need to move together.\n\n## Scope the Change by Boundary\n\nBefore you implement anything, identify:\n\n1. which subsystem changes directly\n2. which other subsystem consumes the changed contract\n\nFor example:\n\n- a backend response-shape change usually also needs frontend service updates and matching validation\n- a companion pairing change may affect browser app behavior and tests in more than one project\n\n## Prefer the Smallest Change That Fixes the Right Problem\n\n- fix the root cause instead of layering extra workarounds on top\n- avoid mixing unrelated refactors into a behavior change unless they are required for correctness\n- do not treat lockfiles, version metadata, or generated navigation inputs as incidental noise when they are part of the reviewed workflow\n\n## Review with Regression Risk in Mind\n\nThe highest-value review questions are usually:\n\n- did the changed contract stay coherent across browser app, backend, and companion?\n- are new or changed validation checks proportional to the risk?\n- did a version-sensitive or dependency-sensitive workflow change without the matching metadata review?\n\n## Typical Review Checklist\n\n- the change goal is stated in terms of behavior, not just files touched\n- cross-boundary contracts were updated together\n- validation covers the actual risk surface\n- release-sensitive files were reviewed intentionally when touched\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:developer-guide/security", "parent_id": "book:developer-guide", "depth": 1, "kind": "section", "label": "security", "title": "Security", "path": "developer-guide/security", "has_children": true, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Security\"\n+++\n\nUse this section when the next question is about dependency intake, vulnerability scanning, or release-artifact trust.\n\nStart with:\n\n- [Dependency Security and Dependabot](./dependency-security-and-dependabot/)\n- [Container Image Security and Artifact Integrity](./container-image-security-and-artifact-integrity/)\n\nThis section focuses on supply-chain and release-security automation.\n\nFor product-boundary security design inside the app itself, keep using the architecture pages that document the backend preview pipeline, browser-to-companion trust model, and other security-sensitive subsystems.\n\n", "0.8": "+++\ntitle = \"Security\"\n+++\n\nUse this section when the next question is about dependency intake, vulnerability scanning, or release-artifact trust.\n\nStart with:\n\n- [Dependency Security and Dependabot](./dependency-security-and-dependabot/)\n- [Container Image Security and Artifact Integrity](./container-image-security-and-artifact-integrity/)\n\nThis section focuses on supply-chain and release-security automation.\n\nFor product-boundary security design inside the app itself, keep using the architecture pages that document the backend preview pipeline, browser-to-companion trust model, and other security-sensitive subsystems.\n\n", "0.9": "+++\ntitle = \"Security\"\n+++\n\nUse this section when the next question is about dependency intake, vulnerability scanning, or release-artifact trust.\n\nStart with:\n\n- [Dependency Security and Dependabot](./dependency-security-and-dependabot/)\n- [Container Image Security and Artifact Integrity](./container-image-security-and-artifact-integrity/)\n\nThis section focuses on supply-chain and release-security automation.\n\nFor product-boundary security design inside the app itself, keep using the architecture pages that document the backend preview pipeline, browser-to-companion trust model, and other security-sensitive subsystems.\n\n", "1.0": "+++\ntitle = \"Security\"\n+++\n\nUse this section when the next question is about dependency intake, vulnerability scanning, or release-artifact trust.\n\nStart with:\n\n- [Dependency Security and Dependabot](./dependency-security-and-dependabot/)\n- [Container Image Security and Artifact Integrity](./container-image-security-and-artifact-integrity/)\n\nThis section focuses on supply-chain and release-security automation.\n\nFor product-boundary security design inside the app itself, keep using the architecture pages that document the backend preview pipeline, browser-to-companion trust model, and other security-sensitive subsystems.\n\n", "2.0": "+++\ntitle = \"Security\"\n+++\n\nUse this section when the next question is about dependency intake, vulnerability scanning, or release-artifact trust.\n\nStart with:\n\n- [Dependency Security and Dependabot](./dependency-security-and-dependabot/)\n- [Container Image Security and Artifact Integrity](./container-image-security-and-artifact-integrity/)\n\nThis section focuses on supply-chain and release-security automation.\n\nFor product-boundary security design inside the app itself, keep using the architecture pages that document the backend preview pipeline, browser-to-companion trust model, and other security-sensitive subsystems.\n\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/security/dependency-security-and-dependabot", "parent_id": "section:developer-guide/security", "depth": 2, "kind": "page", "label": "dependency-security-and-dependabot", "title": "Dependency Security And Dependabot", "path": "developer-guide/security/dependency-security-and-dependabot", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "branched", "source_version": "0.7", "diff_added": 15, "diff_removed": 2}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "branched", "source_version": "0.9", "diff_added": 3, "diff_removed": 2}}, "content_versions": {"0.7": "+++\ntitle = \"Dependency Security and Dependabot\"\n+++\n\nSambee treats dependency intake and dependency vulnerability audits as separate workflows.\n\nDependabot helps bring reviewed update proposals into the repository.\n\nThe dependency audit workflow checks the current manifests and lockfiles for known published vulnerabilities.\n\nIn GitHub Actions, the repository-defined audit workflow appears as `Security: Dependency Audit`.\n\nDependabot activity still appears under GitHub-managed `Dependabot updates`, which is not renamed from this repository.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/dependabot.yml` | schedules and groups automated dependency update pull requests |\n| `.github/workflows/dependency-security.yml` | runs scheduled and manual dependency vulnerability audits |\n| local dev container setup | installs the same core audit tools used in CI for local verification |\n\n## Dependabot Setup\n\nDependabot is configured in `.github/dependabot.yml`.\n\nCurrent coverage includes:\n\n- GitHub Actions dependencies.\n- Backend Python dependencies under `backend/`.\n- Frontend npm dependencies under `frontend/`.\n- Companion npm dependencies under `companion/`.\n- Companion Rust dependencies under `companion/src-tauri/`.\n- Docker image dependencies from the repository root.\n\nThe configuration is intentionally grouped and filtered instead of allowing every update to arrive as an isolated pull request.\n\nExamples:\n\n- Backend Python updates split higher-risk areas such as `smbprotocol` and `pyvips` away from routine development-tool bumps.\n- Frontend major upgrades for React, MUI, Vite, TypeScript, routing, localization, and related runtime-critical packages stay manual.\n- Companion Tauri JavaScript and Rust updates are coordinated through a multi-ecosystem group.\n- Root Docker dependency updates are allowed, but Node and Python base-image version changes stay manual so they can be coordinated across Docker, CI, local development, and docs.\n\nThat split keeps routine maintenance moving while preserving deliberate review for dependency changes that can affect runtime compatibility, release behavior, or user workflows.\n\n## Dependency Vulnerability Audits\n\nThe dependency audit workflow lives in `.github/workflows/dependency-security.yml`.\n\nGitHub Actions displays that workflow as `Security: Dependency Audit`.\n\nIt runs weekly and on manual dispatch.\n\nCurrent checks are:\n\n- backend: `pip-audit -r backend/requirements-dev.lock.txt`\n- frontend: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion npm: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion Rust: `cargo audit`\n\nUse this workflow to catch known issues in the dependency manifests and lockfiles that the repository owns directly.\n\nInside the dev container, `pip-audit` and `cargo-audit` are installed during setup with the same pinned versions used in CI, so local verification can match the workflow behavior closely.\n\n## How This Fits with Release Work\n\nThese checks support release safety, but they are not the same as release publication controls.\n\nUse [Container Image Security and Artifact Integrity](../container-image-security-and-artifact-integrity/) for the Trivy image scans, `.trivyignore.yaml` policy, SBOM emission, provenance, and image signing workflow.\n\n", "0.8": "+++\ntitle = \"Dependency Security and Dependabot\"\n+++\n\nSambee treats dependency intake and dependency vulnerability audits as separate workflows.\n\nDependabot helps bring reviewed update proposals into the repository.\n\nThe dependency audit workflow checks the current manifests and lockfiles for known published vulnerabilities.\n\nIn GitHub Actions, the repository-defined audit workflow appears as `Security: Dependency Audit`.\n\nDependabot activity still appears under GitHub-managed `Dependabot updates`, which is not renamed from this repository.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/dependabot.yml` | schedules and groups automated dependency update pull requests |\n| `.github/workflows/dependency-security.yml` | runs scheduled and manual dependency vulnerability audits |\n| local dev container setup | installs the same core audit tools used in CI for local verification |\n\n## Dependabot Setup\n\nDependabot is configured in `.github/dependabot.yml`.\n\nCurrent coverage includes:\n\n- GitHub Actions dependencies.\n- Backend Python dependencies under `backend/`.\n- Frontend npm dependencies under `frontend/`.\n- Companion npm dependencies under `companion/`.\n- Companion Rust dependencies under `companion/src-tauri/`.\n- Docker image dependencies from the repository root.\n\nThe configuration is intentionally grouped and filtered instead of allowing every update to arrive as an isolated pull request.\n\nExamples:\n\n- Backend Python updates split higher-risk areas such as `smbprotocol` and `pyvips` away from routine development-tool bumps.\n- Frontend major upgrades for React, MUI, Vite, TypeScript, routing, localization, and related runtime-critical packages stay manual.\n- Companion Tauri JavaScript and Rust updates are coordinated through a multi-ecosystem group.\n- Root Docker dependency updates are allowed, but Node and Python base-image version changes stay manual so they can be coordinated across Docker, CI, local development, and docs.\n\nThat split keeps routine maintenance moving while preserving deliberate review for dependency changes that can affect runtime compatibility, release behavior, or user workflows.\n\n## Dependency Vulnerability Audits\n\nThe dependency audit workflow lives in `.github/workflows/dependency-security.yml`.\n\nGitHub Actions displays that workflow as `Security: Dependency Audit`.\n\nIt runs weekly and on manual dispatch.\n\nCurrent checks are:\n\n- backend: `pip-audit -r backend/requirements-dev.lock.txt`\n- frontend: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion npm: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion Rust: `cargo audit`\n\nUse this workflow to catch known issues in the dependency manifests and lockfiles that the repository owns directly.\n\nInside the dev container, `pip-audit` and `cargo-audit` are installed during setup with the same pinned versions used in CI, so local verification can match the workflow behavior closely.\n\n## How This Fits with Release Work\n\nThese checks support release safety, but they are not the same as release publication controls.\n\nUse [Container Image Security and Artifact Integrity](../container-image-security-and-artifact-integrity/) for the Trivy image scans, `.trivyignore.yaml` policy, SBOM emission, provenance, and image signing workflow.\n\n", "0.9": "+++\ntitle = \"Dependency Security and Dependabot\"\n+++\n\nSambee treats dependency intake and dependency vulnerability audits as separate workflows.\n\nDependabot helps bring reviewed update proposals into the repository.\n\nThe dependency audit workflow checks the current manifests and lockfiles for known published vulnerabilities.\n\nIn GitHub Actions, the repository-defined audit workflow appears as `Security: Dependency Audit`.\n\nDependabot activity still appears under GitHub-managed `Dependabot updates`, which is not renamed from this repository.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/dependabot.yml` | schedules and groups automated dependency update pull requests |\n| `.github/workflows/dependency-security.yml` | runs scheduled and manual dependency vulnerability audits |\n| local dev container setup | installs the same core audit tools used in CI for local verification |\n\n## Dependabot Setup\n\nDependabot is configured in `.github/dependabot.yml`.\n\nDependabot commit messages and ungrouped pull request titles use Conventional\nCommit-style prefixes. Ecosystem updates use `deps(npm)`, `deps(pip)`,\n`deps(cargo)`, or `deps(docker)`; GitHub Actions and CI-only tools use\n`deps(ci)`. Development dependencies use the matching `deps-dev(...)` prefix\nwhere Dependabot supports dependency groups.\n\nDependabot generates grouped pull request titles from the group identifier,\nwhich bypasses its configured prefix. The `Format Dependabot PR Title` workflow\nadds the matching prefix when Dependabot opens a grouped pull request. The\nmulti-ecosystem Companion group uses `deps(companion)` because it combines npm\nand Cargo updates.\n\nCurrent coverage includes:\n\n- GitHub Actions dependencies.\n- Backend Python dependencies under `backend/`.\n- Frontend npm dependencies under `frontend/`.\n- Companion npm dependencies under `companion/`.\n- Companion Rust dependencies under `companion/src-tauri/`.\n- Docker image dependencies from the repository root.\n\nThe configuration is intentionally grouped and filtered instead of allowing every update to arrive as an isolated pull request.\n\nExamples:\n\n- Backend Python updates split higher-risk areas such as `smbprotocol` and `pyvips` away from routine development-tool bumps.\n- Frontend major upgrades for React, MUI, Vite, TypeScript, routing, localization, and related runtime-critical packages stay manual.\n- Companion Tauri JavaScript and Rust updates are coordinated through a multi-ecosystem group.\n- Root Docker dependency updates include the shared Python runtime base. Dependabot proposes these updates, and Docker target validation reports the resolved Python and SQLite runtime versions before review.\n- Node base-image version changes stay manual because they affect both frontend and companion toolchains.\n\nThat split keeps routine maintenance moving while preserving deliberate review for dependency changes that can affect runtime compatibility, release behavior, or user workflows. Dependabot pull requests for the Python runtime must not be auto-merged: review the Docker validation, backend validation, image scan, and release-impacting changes before merging.\n\n## Dependency Vulnerability Audits\n\nThe dependency audit workflow lives in `.github/workflows/dependency-security.yml`.\n\nGitHub Actions displays that workflow as `Security: Dependency Audit`.\n\nIt runs weekly and on manual dispatch.\n\nCurrent checks are:\n\n- backend: `pip-audit -r backend/requirements-dev.lock.txt`\n- frontend: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion npm: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion Rust: `cargo audit`\n\nUse this workflow to catch known issues in the dependency manifests and lockfiles that the repository owns directly.\n\nInside the dev container, `pip-audit` and `cargo-audit` are installed during setup with the same pinned versions used in CI, so local verification can match the workflow behavior closely.\n\n## How This Fits with Release Work\n\nThese checks support release safety, but they are not the same as release publication controls.\n\nUse [Container Image Security and Artifact Integrity](../container-image-security-and-artifact-integrity/) for the Trivy image scans, `.trivyignore.yaml` policy, SBOM emission, provenance, and image signing workflow.\n\n", "1.0": "+++\ntitle = \"Dependency Security and Dependabot\"\n+++\n\nSambee treats dependency intake and dependency vulnerability audits as separate workflows.\n\nDependabot helps bring reviewed update proposals into the repository.\n\nThe dependency audit workflow checks the current manifests and lockfiles for known published vulnerabilities.\n\nIn GitHub Actions, the repository-defined audit workflow appears as `Security: Dependency Audit`.\n\nDependabot activity still appears under GitHub-managed `Dependabot updates`, which is not renamed from this repository.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/dependabot.yml` | schedules and groups automated dependency update pull requests |\n| `.github/workflows/dependency-security.yml` | runs scheduled and manual dependency vulnerability audits |\n| local dev container setup | installs the same core audit tools used in CI for local verification |\n\n## Dependabot Setup\n\nDependabot is configured in `.github/dependabot.yml`.\n\nDependabot commit messages and ungrouped pull request titles use Conventional\nCommit-style prefixes. Ecosystem updates use `deps(npm)`, `deps(pip)`,\n`deps(cargo)`, or `deps(docker)`; GitHub Actions and CI-only tools use\n`deps(ci)`. Development dependencies use the matching `deps-dev(...)` prefix\nwhere Dependabot supports dependency groups.\n\nDependabot generates grouped pull request titles from the group identifier,\nwhich bypasses its configured prefix. The `Format Dependabot PR Title` workflow\nadds the matching prefix when Dependabot opens a grouped pull request. The\nmulti-ecosystem Companion group uses `deps(companion)` because it combines npm\nand Cargo updates.\n\nCurrent coverage includes:\n\n- GitHub Actions dependencies.\n- Backend Python dependencies under `backend/`.\n- Frontend npm dependencies under `frontend/`.\n- Companion npm dependencies under `companion/`.\n- Companion Rust dependencies under `companion/src-tauri/`.\n- Docker image dependencies from the repository root.\n\nThe configuration is intentionally grouped and filtered instead of allowing every update to arrive as an isolated pull request.\n\nExamples:\n\n- Backend Python updates split higher-risk areas such as `smbprotocol` and `pyvips` away from routine development-tool bumps.\n- Frontend major upgrades for React, MUI, Vite, TypeScript, routing, localization, and related runtime-critical packages stay manual.\n- Companion Tauri JavaScript and Rust updates are coordinated through a multi-ecosystem group.\n- Root Docker dependency updates include the shared Python runtime base. Dependabot proposes these updates, and Docker target validation reports the resolved Python and SQLite runtime versions before review.\n- Node base-image version changes stay manual because they affect both frontend and companion toolchains.\n\nThat split keeps routine maintenance moving while preserving deliberate review for dependency changes that can affect runtime compatibility, release behavior, or user workflows. Dependabot pull requests for the Python runtime must not be auto-merged: review the Docker validation, backend validation, image scan, and release-impacting changes before merging.\n\n## Dependency Vulnerability Audits\n\nThe dependency audit workflow lives in `.github/workflows/dependency-security.yml`.\n\nGitHub Actions displays that workflow as `Security: Dependency Audit`.\n\nIt runs weekly and on manual dispatch.\n\nCurrent checks are:\n\n- backend: `pip-audit -r backend/requirements-dev.lock.txt`\n- frontend: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion npm: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion Rust: `cargo audit`\n\nUse this workflow to catch known issues in the dependency manifests and lockfiles that the repository owns directly.\n\nInside the dev container, `pip-audit` and `cargo-audit` are installed during setup with the same pinned versions used in CI, so local verification can match the workflow behavior closely.\n\n## How This Fits with Release Work\n\nThese checks support release safety, but they are not the same as release publication controls.\n\nUse [Container Image Security and Artifact Integrity](../container-image-security-and-artifact-integrity/) for the Trivy image scans, `.trivyignore.yaml` policy, SBOM emission, provenance, and image signing workflow.\n\n", "2.0": "+++\ntitle = \"Dependency Security and Dependabot\"\n+++\n\nSambee treats dependency intake and dependency vulnerability audits as separate workflows.\n\nDependabot helps bring reviewed update proposals into the repository.\n\nThe dependency audit workflow checks the current manifests and lockfiles for known published vulnerabilities.\n\nIn GitHub Actions, the repository-defined audit workflow appears as `Security: Dependency Audit`.\n\nDependabot activity still appears under GitHub-managed `Dependabot updates`, which is not renamed from this repository.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/dependabot.yml` | schedules and groups automated dependency update pull requests |\n| `.github/workflows/format-dependabot-pr-title.yml` | prefixes Dependabot pull request titles when configured group names omit them |\n| `.github/workflows/dependency-security.yml` | runs scheduled and manual dependency vulnerability audits |\n| local dev container setup | installs the same core audit tools used in CI for local verification |\n\n## Dependabot Setup\n\nDependabot is configured in `.github/dependabot.yml`.\n\nDependabot commit messages and ungrouped pull request titles use Conventional\nCommit-style prefixes. Ecosystem updates use `deps(npm)`, `deps(pip)`,\n`deps(cargo)`, or `deps(docker)`; GitHub Actions and CI-only tools use\n`deps(ci)`. Development dependencies use the matching `deps-dev(...)` prefix\nwhere Dependabot supports dependency groups.\n\nDependabot generates grouped pull request titles from the group identifier,\nwhich bypasses its configured prefix. The `Format Dependabot PR Title` workflow\nchecks open Dependabot pull requests when a `CI: Test` run triggered by\nDependabot starts and finishes, and adds the matching prefix where needed. It runs trusted workflow code with pull-request write access, without using `pull_request_target` or checking out pull-request code. Run it manually to retry title formatting if a CI run did not trigger it. The\nmulti-ecosystem Companion group uses `deps(companion)` because it combines npm\nand Cargo updates.\n\nCurrent coverage includes:\n\n- GitHub Actions dependencies.\n- Backend Python dependencies under `backend/`.\n- Frontend npm dependencies under `frontend/`.\n- Companion npm dependencies under `companion/`.\n- Companion Rust dependencies under `companion/src-tauri/`.\n- Docker image dependencies from the repository root.\n\nThe configuration is intentionally grouped and filtered instead of allowing every update to arrive as an isolated pull request.\n\nExamples:\n\n- Backend Python updates split higher-risk areas such as `smbprotocol` and `pyvips` away from routine development-tool bumps.\n- Frontend major upgrades for React, MUI, Vite, TypeScript, routing, localization, and related runtime-critical packages stay manual.\n- Companion Tauri JavaScript and Rust updates are coordinated through a multi-ecosystem group.\n- Root Docker dependency updates include the shared Python runtime base. Dependabot proposes these updates, and Docker target validation reports the resolved Python and SQLite runtime versions before review.\n- Node base-image version changes stay manual because they affect both frontend and companion toolchains.\n\nThat split keeps routine maintenance moving while preserving deliberate review for dependency changes that can affect runtime compatibility, release behavior, or user workflows. Dependabot pull requests for the Python runtime must not be auto-merged: review the Docker validation, backend validation, image scan, and release-impacting changes before merging.\n\n## Dependency Vulnerability Audits\n\nThe dependency audit workflow lives in `.github/workflows/dependency-security.yml`.\n\nGitHub Actions displays that workflow as `Security: Dependency Audit`.\n\nIt runs weekly and on manual dispatch.\n\nCurrent checks are:\n\n- backend: `pip-audit -r backend/requirements-dev.lock.txt`\n- frontend: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion npm: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion Rust: `cargo audit`\n\nUse this workflow to catch known issues in the dependency manifests and lockfiles that the repository owns directly.\n\nInside the dev container, `pip-audit` and `cargo-audit` are installed during setup with the same pinned versions used in CI, so local verification can match the workflow behavior closely.\n\n## How This Fits with Release Work\n\nThese checks support release safety, but they are not the same as release publication controls.\n\nUse [Container Image Security and Artifact Integrity](../container-image-security-and-artifact-integrity/) for the Trivy image scans, `.trivyignore.yaml` policy, SBOM emission, provenance, and image signing workflow.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Dependency Security and Dependabot\"\n+++\n\nSambee treats dependency intake and dependency vulnerability audits as separate workflows.\n\nDependabot helps bring reviewed update proposals into the repository.\n\nThe dependency audit workflow checks the current manifests and lockfiles for known published vulnerabilities.\n\nIn GitHub Actions, the repository-defined audit workflow appears as `Security: Dependency Audit`.\n\nDependabot activity still appears under GitHub-managed `Dependabot updates`, which is not renamed from this repository.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/dependabot.yml` | schedules and groups automated dependency update pull requests |\n| `.github/workflows/dependency-security.yml` | runs scheduled and manual dependency vulnerability audits |\n| local dev container setup | installs the same core audit tools used in CI for local verification |\n\n## Dependabot Setup\n\nDependabot is configured in `.github/dependabot.yml`.\n\nCurrent coverage includes:\n\n- GitHub Actions dependencies.\n- Backend Python dependencies under `backend/`.\n- Frontend npm dependencies under `frontend/`.\n- Companion npm dependencies under `companion/`.\n- Companion Rust dependencies under `companion/src-tauri/`.\n- Docker image dependencies from the repository root.\n\nThe configuration is intentionally grouped and filtered instead of allowing every update to arrive as an isolated pull request.\n\nExamples:\n\n- Backend Python updates split higher-risk areas such as `smbprotocol` and `pyvips` away from routine development-tool bumps.\n- Frontend major upgrades for React, MUI, Vite, TypeScript, routing, localization, and related runtime-critical packages stay manual.\n- Companion Tauri JavaScript and Rust updates are coordinated through a multi-ecosystem group.\n- Root Docker dependency updates are allowed, but Node and Python base-image version changes stay manual so they can be coordinated across Docker, CI, local development, and docs.\n\nThat split keeps routine maintenance moving while preserving deliberate review for dependency changes that can affect runtime compatibility, release behavior, or user workflows.\n\n## Dependency Vulnerability Audits\n\nThe dependency audit workflow lives in `.github/workflows/dependency-security.yml`.\n\nGitHub Actions displays that workflow as `Security: Dependency Audit`.\n\nIt runs weekly and on manual dispatch.\n\nCurrent checks are:\n\n- backend: `pip-audit -r backend/requirements-dev.lock.txt`\n- frontend: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion npm: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion Rust: `cargo audit`\n\nUse this workflow to catch known issues in the dependency manifests and lockfiles that the repository owns directly.\n\nInside the dev container, `pip-audit` and `cargo-audit` are installed during setup with the same pinned versions used in CI, so local verification can match the workflow behavior closely.\n\n## How This Fits with Release Work\n\nThese checks support release safety, but they are not the same as release publication controls.\n\nUse [Container Image Security and Artifact Integrity](../container-image-security-and-artifact-integrity/) for the Trivy image scans, `.trivyignore.yaml` policy, SBOM emission, provenance, and image signing workflow.\n\n", "0.8": "+++\ntitle = \"Dependency Security and Dependabot\"\n+++\n\nSambee treats dependency intake and dependency vulnerability audits as separate workflows.\n\nDependabot helps bring reviewed update proposals into the repository.\n\nThe dependency audit workflow checks the current manifests and lockfiles for known published vulnerabilities.\n\nIn GitHub Actions, the repository-defined audit workflow appears as `Security: Dependency Audit`.\n\nDependabot activity still appears under GitHub-managed `Dependabot updates`, which is not renamed from this repository.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/dependabot.yml` | schedules and groups automated dependency update pull requests |\n| `.github/workflows/dependency-security.yml` | runs scheduled and manual dependency vulnerability audits |\n| local dev container setup | installs the same core audit tools used in CI for local verification |\n\n## Dependabot Setup\n\nDependabot is configured in `.github/dependabot.yml`.\n\nCurrent coverage includes:\n\n- GitHub Actions dependencies.\n- Backend Python dependencies under `backend/`.\n- Frontend npm dependencies under `frontend/`.\n- Companion npm dependencies under `companion/`.\n- Companion Rust dependencies under `companion/src-tauri/`.\n- Docker image dependencies from the repository root.\n\nThe configuration is intentionally grouped and filtered instead of allowing every update to arrive as an isolated pull request.\n\nExamples:\n\n- Backend Python updates split higher-risk areas such as `smbprotocol` and `pyvips` away from routine development-tool bumps.\n- Frontend major upgrades for React, MUI, Vite, TypeScript, routing, localization, and related runtime-critical packages stay manual.\n- Companion Tauri JavaScript and Rust updates are coordinated through a multi-ecosystem group.\n- Root Docker dependency updates are allowed, but Node and Python base-image version changes stay manual so they can be coordinated across Docker, CI, local development, and docs.\n\nThat split keeps routine maintenance moving while preserving deliberate review for dependency changes that can affect runtime compatibility, release behavior, or user workflows.\n\n## Dependency Vulnerability Audits\n\nThe dependency audit workflow lives in `.github/workflows/dependency-security.yml`.\n\nGitHub Actions displays that workflow as `Security: Dependency Audit`.\n\nIt runs weekly and on manual dispatch.\n\nCurrent checks are:\n\n- backend: `pip-audit -r backend/requirements-dev.lock.txt`\n- frontend: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion npm: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion Rust: `cargo audit`\n\nUse this workflow to catch known issues in the dependency manifests and lockfiles that the repository owns directly.\n\nInside the dev container, `pip-audit` and `cargo-audit` are installed during setup with the same pinned versions used in CI, so local verification can match the workflow behavior closely.\n\n## How This Fits with Release Work\n\nThese checks support release safety, but they are not the same as release publication controls.\n\nUse [Container Image Security and Artifact Integrity](../container-image-security-and-artifact-integrity/) for the Trivy image scans, `.trivyignore.yaml` policy, SBOM emission, provenance, and image signing workflow.\n\n", "0.9": "+++\ntitle = \"Dependency Security and Dependabot\"\n+++\n\nSambee treats dependency intake and dependency vulnerability audits as separate workflows.\n\nDependabot helps bring reviewed update proposals into the repository.\n\nThe dependency audit workflow checks the current manifests and lockfiles for known published vulnerabilities.\n\nIn GitHub Actions, the repository-defined audit workflow appears as `Security: Dependency Audit`.\n\nDependabot activity still appears under GitHub-managed `Dependabot updates`, which is not renamed from this repository.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/dependabot.yml` | schedules and groups automated dependency update pull requests |\n| `.github/workflows/dependency-security.yml` | runs scheduled and manual dependency vulnerability audits |\n| local dev container setup | installs the same core audit tools used in CI for local verification |\n\n## Dependabot Setup\n\nDependabot is configured in `.github/dependabot.yml`.\n\nDependabot commit messages and ungrouped pull request titles use Conventional\nCommit-style prefixes. Ecosystem updates use `deps(npm)`, `deps(pip)`,\n`deps(cargo)`, or `deps(docker)`; GitHub Actions and CI-only tools use\n`deps(ci)`. Development dependencies use the matching `deps-dev(...)` prefix\nwhere Dependabot supports dependency groups.\n\nDependabot generates grouped pull request titles from the group identifier,\nwhich bypasses its configured prefix. The `Format Dependabot PR Title` workflow\nadds the matching prefix when Dependabot opens a grouped pull request. The\nmulti-ecosystem Companion group uses `deps(companion)` because it combines npm\nand Cargo updates.\n\nCurrent coverage includes:\n\n- GitHub Actions dependencies.\n- Backend Python dependencies under `backend/`.\n- Frontend npm dependencies under `frontend/`.\n- Companion npm dependencies under `companion/`.\n- Companion Rust dependencies under `companion/src-tauri/`.\n- Docker image dependencies from the repository root.\n\nThe configuration is intentionally grouped and filtered instead of allowing every update to arrive as an isolated pull request.\n\nExamples:\n\n- Backend Python updates split higher-risk areas such as `smbprotocol` and `pyvips` away from routine development-tool bumps.\n- Frontend major upgrades for React, MUI, Vite, TypeScript, routing, localization, and related runtime-critical packages stay manual.\n- Companion Tauri JavaScript and Rust updates are coordinated through a multi-ecosystem group.\n- Root Docker dependency updates include the shared Python runtime base. Dependabot proposes these updates, and Docker target validation reports the resolved Python and SQLite runtime versions before review.\n- Node base-image version changes stay manual because they affect both frontend and companion toolchains.\n\nThat split keeps routine maintenance moving while preserving deliberate review for dependency changes that can affect runtime compatibility, release behavior, or user workflows. Dependabot pull requests for the Python runtime must not be auto-merged: review the Docker validation, backend validation, image scan, and release-impacting changes before merging.\n\n## Dependency Vulnerability Audits\n\nThe dependency audit workflow lives in `.github/workflows/dependency-security.yml`.\n\nGitHub Actions displays that workflow as `Security: Dependency Audit`.\n\nIt runs weekly and on manual dispatch.\n\nCurrent checks are:\n\n- backend: `pip-audit -r backend/requirements-dev.lock.txt`\n- frontend: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion npm: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion Rust: `cargo audit`\n\nUse this workflow to catch known issues in the dependency manifests and lockfiles that the repository owns directly.\n\nInside the dev container, `pip-audit` and `cargo-audit` are installed during setup with the same pinned versions used in CI, so local verification can match the workflow behavior closely.\n\n## How This Fits with Release Work\n\nThese checks support release safety, but they are not the same as release publication controls.\n\nUse [Container Image Security and Artifact Integrity](../container-image-security-and-artifact-integrity/) for the Trivy image scans, `.trivyignore.yaml` policy, SBOM emission, provenance, and image signing workflow.\n\n", "1.0": "+++\ntitle = \"Dependency Security and Dependabot\"\n+++\n\nSambee treats dependency intake and dependency vulnerability audits as separate workflows.\n\nDependabot helps bring reviewed update proposals into the repository.\n\nThe dependency audit workflow checks the current manifests and lockfiles for known published vulnerabilities.\n\nIn GitHub Actions, the repository-defined audit workflow appears as `Security: Dependency Audit`.\n\nDependabot activity still appears under GitHub-managed `Dependabot updates`, which is not renamed from this repository.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/dependabot.yml` | schedules and groups automated dependency update pull requests |\n| `.github/workflows/dependency-security.yml` | runs scheduled and manual dependency vulnerability audits |\n| local dev container setup | installs the same core audit tools used in CI for local verification |\n\n## Dependabot Setup\n\nDependabot is configured in `.github/dependabot.yml`.\n\nDependabot commit messages and ungrouped pull request titles use Conventional\nCommit-style prefixes. Ecosystem updates use `deps(npm)`, `deps(pip)`,\n`deps(cargo)`, or `deps(docker)`; GitHub Actions and CI-only tools use\n`deps(ci)`. Development dependencies use the matching `deps-dev(...)` prefix\nwhere Dependabot supports dependency groups.\n\nDependabot generates grouped pull request titles from the group identifier,\nwhich bypasses its configured prefix. The `Format Dependabot PR Title` workflow\nadds the matching prefix when Dependabot opens a grouped pull request. The\nmulti-ecosystem Companion group uses `deps(companion)` because it combines npm\nand Cargo updates.\n\nCurrent coverage includes:\n\n- GitHub Actions dependencies.\n- Backend Python dependencies under `backend/`.\n- Frontend npm dependencies under `frontend/`.\n- Companion npm dependencies under `companion/`.\n- Companion Rust dependencies under `companion/src-tauri/`.\n- Docker image dependencies from the repository root.\n\nThe configuration is intentionally grouped and filtered instead of allowing every update to arrive as an isolated pull request.\n\nExamples:\n\n- Backend Python updates split higher-risk areas such as `smbprotocol` and `pyvips` away from routine development-tool bumps.\n- Frontend major upgrades for React, MUI, Vite, TypeScript, routing, localization, and related runtime-critical packages stay manual.\n- Companion Tauri JavaScript and Rust updates are coordinated through a multi-ecosystem group.\n- Root Docker dependency updates include the shared Python runtime base. Dependabot proposes these updates, and Docker target validation reports the resolved Python and SQLite runtime versions before review.\n- Node base-image version changes stay manual because they affect both frontend and companion toolchains.\n\nThat split keeps routine maintenance moving while preserving deliberate review for dependency changes that can affect runtime compatibility, release behavior, or user workflows. Dependabot pull requests for the Python runtime must not be auto-merged: review the Docker validation, backend validation, image scan, and release-impacting changes before merging.\n\n## Dependency Vulnerability Audits\n\nThe dependency audit workflow lives in `.github/workflows/dependency-security.yml`.\n\nGitHub Actions displays that workflow as `Security: Dependency Audit`.\n\nIt runs weekly and on manual dispatch.\n\nCurrent checks are:\n\n- backend: `pip-audit -r backend/requirements-dev.lock.txt`\n- frontend: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion npm: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion Rust: `cargo audit`\n\nUse this workflow to catch known issues in the dependency manifests and lockfiles that the repository owns directly.\n\nInside the dev container, `pip-audit` and `cargo-audit` are installed during setup with the same pinned versions used in CI, so local verification can match the workflow behavior closely.\n\n## How This Fits with Release Work\n\nThese checks support release safety, but they are not the same as release publication controls.\n\nUse [Container Image Security and Artifact Integrity](../container-image-security-and-artifact-integrity/) for the Trivy image scans, `.trivyignore.yaml` policy, SBOM emission, provenance, and image signing workflow.\n\n", "2.0": "+++\ntitle = \"Dependency Security and Dependabot\"\n+++\n\nSambee treats dependency intake and dependency vulnerability audits as separate workflows.\n\nDependabot helps bring reviewed update proposals into the repository.\n\nThe dependency audit workflow checks the current manifests and lockfiles for known published vulnerabilities.\n\nIn GitHub Actions, the repository-defined audit workflow appears as `Security: Dependency Audit`.\n\nDependabot activity still appears under GitHub-managed `Dependabot updates`, which is not renamed from this repository.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/dependabot.yml` | schedules and groups automated dependency update pull requests |\n| `.github/workflows/format-dependabot-pr-title.yml` | prefixes Dependabot pull request titles when configured group names omit them |\n| `.github/workflows/dependency-security.yml` | runs scheduled and manual dependency vulnerability audits |\n| local dev container setup | installs the same core audit tools used in CI for local verification |\n\n## Dependabot Setup\n\nDependabot is configured in `.github/dependabot.yml`.\n\nDependabot commit messages and ungrouped pull request titles use Conventional\nCommit-style prefixes. Ecosystem updates use `deps(npm)`, `deps(pip)`,\n`deps(cargo)`, or `deps(docker)`; GitHub Actions and CI-only tools use\n`deps(ci)`. Development dependencies use the matching `deps-dev(...)` prefix\nwhere Dependabot supports dependency groups.\n\nDependabot generates grouped pull request titles from the group identifier,\nwhich bypasses its configured prefix. The `Format Dependabot PR Title` workflow\nchecks open Dependabot pull requests when a `CI: Test` run triggered by\nDependabot starts and finishes, and adds the matching prefix where needed. It runs trusted workflow code with pull-request write access, without using `pull_request_target` or checking out pull-request code. Run it manually to retry title formatting if a CI run did not trigger it. The\nmulti-ecosystem Companion group uses `deps(companion)` because it combines npm\nand Cargo updates.\n\nCurrent coverage includes:\n\n- GitHub Actions dependencies.\n- Backend Python dependencies under `backend/`.\n- Frontend npm dependencies under `frontend/`.\n- Companion npm dependencies under `companion/`.\n- Companion Rust dependencies under `companion/src-tauri/`.\n- Docker image dependencies from the repository root.\n\nThe configuration is intentionally grouped and filtered instead of allowing every update to arrive as an isolated pull request.\n\nExamples:\n\n- Backend Python updates split higher-risk areas such as `smbprotocol` and `pyvips` away from routine development-tool bumps.\n- Frontend major upgrades for React, MUI, Vite, TypeScript, routing, localization, and related runtime-critical packages stay manual.\n- Companion Tauri JavaScript and Rust updates are coordinated through a multi-ecosystem group.\n- Root Docker dependency updates include the shared Python runtime base. Dependabot proposes these updates, and Docker target validation reports the resolved Python and SQLite runtime versions before review.\n- Node base-image version changes stay manual because they affect both frontend and companion toolchains.\n\nThat split keeps routine maintenance moving while preserving deliberate review for dependency changes that can affect runtime compatibility, release behavior, or user workflows. Dependabot pull requests for the Python runtime must not be auto-merged: review the Docker validation, backend validation, image scan, and release-impacting changes before merging.\n\n## Dependency Vulnerability Audits\n\nThe dependency audit workflow lives in `.github/workflows/dependency-security.yml`.\n\nGitHub Actions displays that workflow as `Security: Dependency Audit`.\n\nIt runs weekly and on manual dispatch.\n\nCurrent checks are:\n\n- backend: `pip-audit -r backend/requirements-dev.lock.txt`\n- frontend: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion npm: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion Rust: `cargo audit`\n\nUse this workflow to catch known issues in the dependency manifests and lockfiles that the repository owns directly.\n\nInside the dev container, `pip-audit` and `cargo-audit` are installed during setup with the same pinned versions used in CI, so local verification can match the workflow behavior closely.\n\n## How This Fits with Release Work\n\nThese checks support release safety, but they are not the same as release publication controls.\n\nUse [Container Image Security and Artifact Integrity](../container-image-security-and-artifact-integrity/) for the Trivy image scans, `.trivyignore.yaml` policy, SBOM emission, provenance, and image signing workflow.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/security/container-image-security-and-artifact-integrity", "parent_id": "section:developer-guide/security", "depth": 2, "kind": "page", "label": "container-image-security-and-artifact-integrity", "title": "Container Image Security And Artifact Integrity", "path": "developer-guide/security/container-image-security-and-artifact-integrity", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Container Image Security and Artifact Integrity\"\n+++\n\nContainer-image security answers a different question than dependency-manifest auditing.\n\nSambee uses Trivy and release-artifact integrity controls to validate the final published container image, not just the repository dependency files.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/docker-image-security-scan.yml` | builds the current `main` image and runs the weekly Trivy scan |\n| `.github/workflows/docker-image-preview-publish.yml` | runs the preview-candidate Trivy scan before publishing to the `test` channel |\n| `.github/workflows/docker-image-publish.yml` | promotes a verified candidate digest onto release tags after checking image metadata and the published metadata bundle |\n| `.github/scripts/verify_candidate_metadata_bundle.sh` | verifies that the preview-built SBOM and provenance bundle exists under the expected digest-derived metadata tag |\n| `.github/tools/trivy/Dockerfile` | pins the Trivy container image version that both scan workflows use |\n| `.trivyignore.yaml` | holds reviewed Trivy suppressions for the image scans |\n| `Dockerfile` | defines the runtime artifact that is actually scanned and published |\n\n## Why Trivy Exists Alongside Dependency Audits\n\nDependency audits help with application dependency drift.\n\nTrivy adds coverage for the built runtime artifact itself, especially:\n\n- vulnerabilities inherited from the pinned base image\n- vulnerabilities in OS packages installed during the Docker build\n- the final package set that actually ships in the container\n\nThat matters for Sambee because the final image includes native tooling and runtime libraries that are outside the normal `pip`, `npm`, and `cargo` manifest audits.\n\n## Trivy Setup\n\nSambee currently uses Trivy in two places.\n\nBoth workflows resolve the Trivy runtime image from `.github/tools/trivy/Dockerfile`, so the pin is reviewed once and Dependabot can update it through the `docker` ecosystem.\n\nBoth workflows also force a fresh rebuild of the Dockerfile layer that installs Debian packages.\n\nThey do that with a workflow-provided refresh key passed into the image build, so `apt-get update`, `apt-get upgrade`, and package installation rerun against the latest repository state available at build time while the rest of the image can still benefit from BuildKit caching.\n\n### Weekly Image Scan on `main`\n\n`.github/workflows/docker-image-security-scan.yml` builds the current production image from `main` and scans it once per week.\n\nThe scan currently:\n\n- builds and scans the supported `linux/amd64` and `linux/arm64` image variants separately\n- forces a fresh rebuild of the Debian package-install layer for each workflow run\n- uses `.trivyignore.yaml` as the reviewed suppression file\n- shows suppressed findings in the output\n- checks OS packages and application libraries\n- considers only `HIGH` and `CRITICAL` vulnerabilities\n- ignores unfixed vulnerabilities\n- fails the workflow when matching fixed vulnerabilities remain after suppression\n\nThis is the workflow that tells you a shipped runtime stack has picked up a newly disclosed issue even when no new Sambee release is in progress.\n\n### Preview Publish Scan\n\n`.github/workflows/docker-image-preview-publish.yml` runs Trivy against each pushed preview platform image before those platform manifests are assembled into the preview candidate index.\n\nCurrent preview behavior is intentionally advisory:\n\n- the preview build forces a fresh rebuild of the Debian package-install layer before Trivy runs and before the candidate is published\n- Trivy scans the same pushed platform digests that are later assembled into the final preview candidate\n- preview publishes still show matching `HIGH` or `CRITICAL` findings\n- the findings do not block publication to the `test` channel\n\nThat keeps the newest preview candidate available for validation while still surfacing image risk clearly in CI.\n\n## Trivy Ignore Policy\n\nThe repository-root `.trivyignore.yaml` file is the shared suppression file for both Trivy workflows.\n\nKeep entries narrow and reviewable.\n\nEach suppression should include:\n\n- the finding ID\n- a short statement describing why the risk is accepted temporarily\n- an `expired_at` date so the exception must be revisited explicitly\n\nThat keeps long-lived silent exceptions from accumulating in the image-security workflows.\n\n## Artifact Integrity\n\nThe preview publish and release promotion workflows enable:\n\n- SBOM and provenance bundle publication in a dedicated metadata repository\n- Cosign signing of the pushed image digest through GitHub Actions OIDC\n\nRelease promotion also verifies that the preview-built metadata bundle matches the candidate digest before channel tags are moved.\n\nRelease and backfill workflows mirror the exact metadata bundle files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in GHCR remains the canonical store.\n\nCosign signatures are stored in a dedicated GHCR repository instead of the main image repository.\n\nCurrent split:\n\n- deployable images and multi-arch manifests stay under `ghcr.io/\u003cowner\u003e/sambee`\n- SBOM and provenance metadata bundles and Cosign signature artifacts are written under `ghcr.io/\u003cowner\u003e/sambee-signatures`\n\nFor Cosign-managed signatures, GHCR can display a digest-derived tagged signature artifact together with an untagged referenced bundle manifest for the same retained image digest.\n\nThat keeps the main package page focused on deployable image versions instead of showing non-runnable attestation content there.\n\nThose controls do not replace vulnerability scanning.\n\nThey answer a different question: whether a published artifact can be traced and verified after it is built.\n\n## Workflow Pinning Discipline\n\nSecurity-relevant GitHub Actions in this repository are pinned by commit SHA rather than floating major tags.\n\nThat reduces uncontrolled workflow drift in the automation layer itself.\n\nTreat action-version changes in these workflows as reviewed dependency changes, not as incidental cleanup.\n\n## How This Fits with Dependency Security\n\nUse [Dependency Security and Dependabot](../dependency-security-and-dependabot/) for the repository's dependency intake rules, Dependabot grouping, and scheduled dependency vulnerability audits.\n\n", "0.8": "+++\ntitle = \"Container Image Security and Artifact Integrity\"\n+++\n\nContainer-image security answers a different question than dependency-manifest auditing.\n\nSambee uses Trivy and release-artifact integrity controls to validate the final published container image, not just the repository dependency files.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/docker-image-security-scan.yml` | builds the current `main` image and runs the weekly Trivy scan |\n| `.github/workflows/docker-image-preview-publish.yml` | runs the preview-candidate Trivy scan before publishing to the `test` channel |\n| `.github/workflows/docker-image-publish.yml` | promotes a verified candidate digest onto release tags after checking image metadata and the published metadata bundle |\n| `.github/scripts/verify_candidate_metadata_bundle.sh` | verifies that the preview-built SBOM and provenance bundle exists under the expected digest-derived metadata tag |\n| `.github/tools/trivy/Dockerfile` | pins the Trivy container image version that both scan workflows use |\n| `.trivyignore.yaml` | holds reviewed Trivy suppressions for the image scans |\n| `Dockerfile` | defines the runtime artifact that is actually scanned and published |\n\n## Why Trivy Exists Alongside Dependency Audits\n\nDependency audits help with application dependency drift.\n\nTrivy adds coverage for the built runtime artifact itself, especially:\n\n- vulnerabilities inherited from the pinned base image\n- vulnerabilities in OS packages installed during the Docker build\n- the final package set that actually ships in the container\n\nThat matters for Sambee because the final image includes native tooling and runtime libraries that are outside the normal `pip`, `npm`, and `cargo` manifest audits.\n\n## Trivy Setup\n\nSambee currently uses Trivy in two places.\n\nBoth workflows resolve the Trivy runtime image from `.github/tools/trivy/Dockerfile`, so the pin is reviewed once and Dependabot can update it through the `docker` ecosystem.\n\nBoth workflows also force a fresh rebuild of the Dockerfile layer that installs Debian packages.\n\nThey do that with a workflow-provided refresh key passed into the image build, so `apt-get update`, `apt-get upgrade`, and package installation rerun against the latest repository state available at build time while the rest of the image can still benefit from BuildKit caching.\n\n### Weekly Image Scan on `main`\n\n`.github/workflows/docker-image-security-scan.yml` builds the current production image from `main` and scans it once per week.\n\nThe scan currently:\n\n- builds and scans the supported `linux/amd64` and `linux/arm64` image variants separately\n- forces a fresh rebuild of the Debian package-install layer for each workflow run\n- uses `.trivyignore.yaml` as the reviewed suppression file\n- shows suppressed findings in the output\n- checks OS packages and application libraries\n- considers only `HIGH` and `CRITICAL` vulnerabilities\n- ignores unfixed vulnerabilities\n- fails the workflow when matching fixed vulnerabilities remain after suppression\n\nThis is the workflow that tells you a shipped runtime stack has picked up a newly disclosed issue even when no new Sambee release is in progress.\n\n### Preview Publish Scan\n\n`.github/workflows/docker-image-preview-publish.yml` runs Trivy against each pushed preview platform image before those platform manifests are assembled into the preview candidate index.\n\nCurrent preview behavior is intentionally advisory:\n\n- the preview build forces a fresh rebuild of the Debian package-install layer before Trivy runs and before the candidate is published\n- Trivy scans the same pushed platform digests that are later assembled into the final preview candidate\n- preview publishes still show matching `HIGH` or `CRITICAL` findings\n- the findings do not block publication to the `test` channel\n\nThat keeps the newest preview candidate available for validation while still surfacing image risk clearly in CI.\n\n## Trivy Ignore Policy\n\nThe repository-root `.trivyignore.yaml` file is the shared suppression file for both Trivy workflows.\n\nKeep entries narrow and reviewable.\n\nEach suppression should include:\n\n- the finding ID\n- a short statement describing why the risk is accepted temporarily\n- an `expired_at` date so the exception must be revisited explicitly\n\nThat keeps long-lived silent exceptions from accumulating in the image-security workflows.\n\n## Artifact Integrity\n\nThe preview publish and release promotion workflows enable:\n\n- SBOM and provenance bundle publication in a dedicated metadata repository\n- Cosign signing of the pushed image digest through GitHub Actions OIDC\n\nRelease promotion also verifies that the preview-built metadata bundle matches the candidate digest before channel tags are moved.\n\nRelease and backfill workflows mirror the exact metadata bundle files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in GHCR remains the canonical store.\n\nCosign signatures are stored in a dedicated GHCR repository instead of the main image repository.\n\nCurrent split:\n\n- deployable images and multi-arch manifests stay under `ghcr.io/\u003cowner\u003e/sambee`\n- SBOM and provenance metadata bundles and Cosign signature artifacts are written under `ghcr.io/\u003cowner\u003e/sambee-signatures`\n\nFor Cosign-managed signatures, GHCR can display a digest-derived tagged signature artifact together with an untagged referenced bundle manifest for the same retained image digest.\n\nThat keeps the main package page focused on deployable image versions instead of showing non-runnable attestation content there.\n\nThose controls do not replace vulnerability scanning.\n\nThey answer a different question: whether a published artifact can be traced and verified after it is built.\n\n## Workflow Pinning Discipline\n\nSecurity-relevant GitHub Actions in this repository are pinned by commit SHA rather than floating major tags.\n\nThat reduces uncontrolled workflow drift in the automation layer itself.\n\nTreat action-version changes in these workflows as reviewed dependency changes, not as incidental cleanup.\n\n## How This Fits with Dependency Security\n\nUse [Dependency Security and Dependabot](../dependency-security-and-dependabot/) for the repository's dependency intake rules, Dependabot grouping, and scheduled dependency vulnerability audits.\n\n", "0.9": "+++\ntitle = \"Container Image Security and Artifact Integrity\"\n+++\n\nContainer-image security answers a different question than dependency-manifest auditing.\n\nSambee uses Trivy and release-artifact integrity controls to validate the final published container image, not just the repository dependency files.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/docker-image-security-scan.yml` | builds the current `main` image and runs the weekly Trivy scan |\n| `.github/workflows/docker-image-preview-publish.yml` | runs the preview-candidate Trivy scan before publishing to the `test` channel |\n| `.github/workflows/docker-image-publish.yml` | promotes a verified candidate digest onto release tags after checking image metadata and the published metadata bundle |\n| `.github/scripts/verify_candidate_metadata_bundle.sh` | verifies that the preview-built SBOM and provenance bundle exists under the expected digest-derived metadata tag |\n| `.github/tools/trivy/Dockerfile` | pins the Trivy container image version that both scan workflows use |\n| `.trivyignore.yaml` | holds reviewed Trivy suppressions for the image scans |\n| `Dockerfile` | defines the runtime artifact that is actually scanned and published |\n\n## Why Trivy Exists Alongside Dependency Audits\n\nDependency audits help with application dependency drift.\n\nTrivy adds coverage for the built runtime artifact itself, especially:\n\n- vulnerabilities inherited from the pinned base image\n- vulnerabilities in OS packages installed during the Docker build\n- the final package set that actually ships in the container\n\nThat matters for Sambee because the final image includes native tooling and runtime libraries that are outside the normal `pip`, `npm`, and `cargo` manifest audits.\n\n## Trivy Setup\n\nSambee currently uses Trivy in two places.\n\nBoth workflows resolve the Trivy runtime image from `.github/tools/trivy/Dockerfile`, so the pin is reviewed once and Dependabot can update it through the `docker` ecosystem.\n\nBoth workflows also force a fresh rebuild of the Dockerfile layer that installs Debian packages.\n\nThey do that with a workflow-provided refresh key passed into the image build, so `apt-get update`, `apt-get upgrade`, and package installation rerun against the latest repository state available at build time while the rest of the image can still benefit from BuildKit caching.\n\n### Weekly Image Scan on `main`\n\n`.github/workflows/docker-image-security-scan.yml` builds the current production image from `main` and scans it once per week.\n\nThe scan currently:\n\n- builds and scans the supported `linux/amd64` and `linux/arm64` image variants separately\n- forces a fresh rebuild of the Debian package-install layer for each workflow run\n- uses `.trivyignore.yaml` as the reviewed suppression file\n- shows suppressed findings in the output\n- checks OS packages and application libraries\n- considers only `HIGH` and `CRITICAL` vulnerabilities\n- ignores unfixed vulnerabilities\n- fails the workflow when matching fixed vulnerabilities remain after suppression\n\nThis is the workflow that tells you a shipped runtime stack has picked up a newly disclosed issue even when no new Sambee release is in progress.\n\n### Preview Publish Scan\n\n`.github/workflows/docker-image-preview-publish.yml` runs Trivy against each pushed preview platform image before those platform manifests are assembled into the preview candidate index.\n\nCurrent preview behavior is intentionally advisory:\n\n- the preview build forces a fresh rebuild of the Debian package-install layer before Trivy runs and before the candidate is published\n- Trivy scans the same pushed platform digests that are later assembled into the final preview candidate\n- preview publishes still show matching `HIGH` or `CRITICAL` findings\n- the findings do not block publication to the `test` channel\n\nThat keeps the newest preview candidate available for validation while still surfacing image risk clearly in CI.\n\n## Trivy Ignore Policy\n\nThe repository-root `.trivyignore.yaml` file is the shared suppression file for both Trivy workflows.\n\nKeep entries narrow and reviewable.\n\nEach suppression should include:\n\n- the finding ID\n- a short statement describing why the risk is accepted temporarily\n- an `expired_at` date so the exception must be revisited explicitly\n\nThat keeps long-lived silent exceptions from accumulating in the image-security workflows.\n\n## Artifact Integrity\n\nThe preview publish and release promotion workflows enable:\n\n- SBOM and provenance bundle publication in a dedicated metadata repository\n- Cosign signing of the pushed image digest through GitHub Actions OIDC\n\nRelease promotion also verifies that the preview-built metadata bundle matches the candidate digest before channel tags are moved.\n\nRelease and backfill workflows mirror the exact metadata bundle files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in GHCR remains the canonical store.\n\nCosign signatures are stored in a dedicated GHCR repository instead of the main image repository.\n\nCurrent split:\n\n- deployable images and multi-arch manifests stay under `ghcr.io/\u003cowner\u003e/sambee`\n- SBOM and provenance metadata bundles and Cosign signature artifacts are written under `ghcr.io/\u003cowner\u003e/sambee-signatures`\n\nFor Cosign-managed signatures, GHCR can display a digest-derived tagged signature artifact together with an untagged referenced bundle manifest for the same retained image digest.\n\nThat keeps the main package page focused on deployable image versions instead of showing non-runnable attestation content there.\n\nThose controls do not replace vulnerability scanning.\n\nThey answer a different question: whether a published artifact can be traced and verified after it is built.\n\n## Workflow Pinning Discipline\n\nSecurity-relevant GitHub Actions in this repository are pinned by commit SHA rather than floating major tags.\n\nThat reduces uncontrolled workflow drift in the automation layer itself.\n\nTreat action-version changes in these workflows as reviewed dependency changes, not as incidental cleanup.\n\n## How This Fits with Dependency Security\n\nUse [Dependency Security and Dependabot](../dependency-security-and-dependabot/) for the repository's dependency intake rules, Dependabot grouping, and scheduled dependency vulnerability audits.\n\n", "1.0": "+++\ntitle = \"Container Image Security and Artifact Integrity\"\n+++\n\nContainer-image security answers a different question than dependency-manifest auditing.\n\nSambee uses Trivy and release-artifact integrity controls to validate the final published container image, not just the repository dependency files.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/docker-image-security-scan.yml` | builds the current `main` image and runs the weekly Trivy scan |\n| `.github/workflows/docker-image-preview-publish.yml` | runs the preview-candidate Trivy scan before publishing to the `test` channel |\n| `.github/workflows/docker-image-publish.yml` | promotes a verified candidate digest onto release tags after checking image metadata and the published metadata bundle |\n| `.github/scripts/verify_candidate_metadata_bundle.sh` | verifies that the preview-built SBOM and provenance bundle exists under the expected digest-derived metadata tag |\n| `.github/tools/trivy/Dockerfile` | pins the Trivy container image version that both scan workflows use |\n| `.trivyignore.yaml` | holds reviewed Trivy suppressions for the image scans |\n| `Dockerfile` | defines the runtime artifact that is actually scanned and published |\n\n## Why Trivy Exists Alongside Dependency Audits\n\nDependency audits help with application dependency drift.\n\nTrivy adds coverage for the built runtime artifact itself, especially:\n\n- vulnerabilities inherited from the pinned base image\n- vulnerabilities in OS packages installed during the Docker build\n- the final package set that actually ships in the container\n\nThat matters for Sambee because the final image includes native tooling and runtime libraries that are outside the normal `pip`, `npm`, and `cargo` manifest audits.\n\n## Trivy Setup\n\nSambee currently uses Trivy in two places.\n\nBoth workflows resolve the Trivy runtime image from `.github/tools/trivy/Dockerfile`, so the pin is reviewed once and Dependabot can update it through the `docker` ecosystem.\n\nBoth workflows also force a fresh rebuild of the Dockerfile layer that installs Debian packages.\n\nThey do that with a workflow-provided refresh key passed into the image build, so `apt-get update`, `apt-get upgrade`, and package installation rerun against the latest repository state available at build time while the rest of the image can still benefit from BuildKit caching.\n\n### Weekly Image Scan on `main`\n\n`.github/workflows/docker-image-security-scan.yml` builds the current production image from `main` and scans it once per week.\n\nThe scan currently:\n\n- builds and scans the supported `linux/amd64` and `linux/arm64` image variants separately\n- forces a fresh rebuild of the Debian package-install layer for each workflow run\n- uses `.trivyignore.yaml` as the reviewed suppression file\n- shows suppressed findings in the output\n- checks OS packages and application libraries\n- considers only `HIGH` and `CRITICAL` vulnerabilities\n- ignores unfixed vulnerabilities\n- fails the workflow when matching fixed vulnerabilities remain after suppression\n\nThis is the workflow that tells you a shipped runtime stack has picked up a newly disclosed issue even when no new Sambee release is in progress.\n\n### Preview Publish Scan\n\n`.github/workflows/docker-image-preview-publish.yml` runs Trivy against each pushed preview platform image before those platform manifests are assembled into the preview candidate index.\n\nCurrent preview behavior is intentionally advisory:\n\n- the preview build forces a fresh rebuild of the Debian package-install layer before Trivy runs and before the candidate is published\n- Trivy scans the same pushed platform digests that are later assembled into the final preview candidate\n- preview publishes still show matching `HIGH` or `CRITICAL` findings\n- the findings do not block publication to the `test` channel\n\nThat keeps the newest preview candidate available for validation while still surfacing image risk clearly in CI.\n\n## Trivy Ignore Policy\n\nThe repository-root `.trivyignore.yaml` file is the shared suppression file for both Trivy workflows.\n\nKeep entries narrow and reviewable.\n\nEach suppression should include:\n\n- the finding ID\n- a short statement describing why the risk is accepted temporarily\n- an `expired_at` date so the exception must be revisited explicitly\n\nThat keeps long-lived silent exceptions from accumulating in the image-security workflows.\n\n## Artifact Integrity\n\nThe preview publish and release promotion workflows enable:\n\n- SBOM and provenance bundle publication in a dedicated metadata repository\n- Cosign signing of the pushed image digest through GitHub Actions OIDC\n\nRelease promotion also verifies that the preview-built metadata bundle matches the candidate digest before channel tags are moved.\n\nRelease and backfill workflows mirror the exact metadata bundle files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in GHCR remains the canonical store.\n\nCosign signatures are stored in a dedicated GHCR repository instead of the main image repository.\n\nCurrent split:\n\n- deployable images and multi-arch manifests stay under `ghcr.io/\u003cowner\u003e/sambee`\n- SBOM and provenance metadata bundles and Cosign signature artifacts are written under `ghcr.io/\u003cowner\u003e/sambee-signatures`\n\nFor Cosign-managed signatures, GHCR can display a digest-derived tagged signature artifact together with an untagged referenced bundle manifest for the same retained image digest.\n\nThat keeps the main package page focused on deployable image versions instead of showing non-runnable attestation content there.\n\nThose controls do not replace vulnerability scanning.\n\nThey answer a different question: whether a published artifact can be traced and verified after it is built.\n\n## Workflow Pinning Discipline\n\nSecurity-relevant GitHub Actions in this repository are pinned by commit SHA rather than floating major tags.\n\nThat reduces uncontrolled workflow drift in the automation layer itself.\n\nTreat action-version changes in these workflows as reviewed dependency changes, not as incidental cleanup.\n\n## How This Fits with Dependency Security\n\nUse [Dependency Security and Dependabot](../dependency-security-and-dependabot/) for the repository's dependency intake rules, Dependabot grouping, and scheduled dependency vulnerability audits.\n\n", "2.0": "+++\ntitle = \"Container Image Security and Artifact Integrity\"\n+++\n\nContainer-image security answers a different question than dependency-manifest auditing.\n\nSambee uses Trivy and release-artifact integrity controls to validate the final published container image, not just the repository dependency files.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/docker-image-security-scan.yml` | builds the current `main` image and runs the weekly Trivy scan |\n| `.github/workflows/docker-image-preview-publish.yml` | runs the preview-candidate Trivy scan before publishing to the `test` channel |\n| `.github/workflows/docker-image-publish.yml` | promotes a verified candidate digest onto release tags after checking image metadata and the published metadata bundle |\n| `.github/scripts/verify_candidate_metadata_bundle.sh` | verifies that the preview-built SBOM and provenance bundle exists under the expected digest-derived metadata tag |\n| `.github/tools/trivy/Dockerfile` | pins the Trivy container image version that both scan workflows use |\n| `.trivyignore.yaml` | holds reviewed Trivy suppressions for the image scans |\n| `Dockerfile` | defines the runtime artifact that is actually scanned and published |\n\n## Why Trivy Exists Alongside Dependency Audits\n\nDependency audits help with application dependency drift.\n\nTrivy adds coverage for the built runtime artifact itself, especially:\n\n- vulnerabilities inherited from the pinned base image\n- vulnerabilities in OS packages installed during the Docker build\n- the final package set that actually ships in the container\n\nThat matters for Sambee because the final image includes native tooling and runtime libraries that are outside the normal `pip`, `npm`, and `cargo` manifest audits.\n\n## Trivy Setup\n\nSambee currently uses Trivy in two places.\n\nBoth workflows resolve the Trivy runtime image from `.github/tools/trivy/Dockerfile`, so the pin is reviewed once and Dependabot can update it through the `docker` ecosystem.\n\nBoth workflows also force a fresh rebuild of the Dockerfile layer that installs Debian packages.\n\nThey do that with a workflow-provided refresh key passed into the image build, so `apt-get update`, `apt-get upgrade`, and package installation rerun against the latest repository state available at build time while the rest of the image can still benefit from BuildKit caching.\n\n### Weekly Image Scan on `main`\n\n`.github/workflows/docker-image-security-scan.yml` builds the current production image from `main` and scans it once per week.\n\nThe scan currently:\n\n- builds and scans the supported `linux/amd64` and `linux/arm64` image variants separately\n- forces a fresh rebuild of the Debian package-install layer for each workflow run\n- uses `.trivyignore.yaml` as the reviewed suppression file\n- shows suppressed findings in the output\n- checks OS packages and application libraries\n- considers only `HIGH` and `CRITICAL` vulnerabilities\n- ignores unfixed vulnerabilities\n- fails the workflow when matching fixed vulnerabilities remain after suppression\n\nThis is the workflow that tells you a shipped runtime stack has picked up a newly disclosed issue even when no new Sambee release is in progress.\n\n### Preview Publish Scan\n\n`.github/workflows/docker-image-preview-publish.yml` runs Trivy against each pushed preview platform image before those platform manifests are assembled into the preview candidate index.\n\nCurrent preview behavior is intentionally advisory:\n\n- the preview build forces a fresh rebuild of the Debian package-install layer before Trivy runs and before the candidate is published\n- Trivy scans the same pushed platform digests that are later assembled into the final preview candidate\n- preview publishes still show matching `HIGH` or `CRITICAL` findings\n- the findings do not block publication to the `test` channel\n\nThat keeps the newest preview candidate available for validation while still surfacing image risk clearly in CI.\n\n## Trivy Ignore Policy\n\nThe repository-root `.trivyignore.yaml` file is the shared suppression file for both Trivy workflows.\n\nKeep entries narrow and reviewable.\n\nEach suppression should include:\n\n- the finding ID\n- a short statement describing why the risk is accepted temporarily\n- an `expired_at` date so the exception must be revisited explicitly\n\nThat keeps long-lived silent exceptions from accumulating in the image-security workflows.\n\n## Artifact Integrity\n\nThe preview publish and release promotion workflows enable:\n\n- SBOM and provenance bundle publication in a dedicated metadata repository\n- Cosign signing of the pushed image digest through GitHub Actions OIDC\n\nRelease promotion also verifies that the preview-built metadata bundle matches the candidate digest before channel tags are moved.\n\nRelease and backfill workflows mirror the exact metadata bundle files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in GHCR remains the canonical store.\n\nCosign signatures are stored in a dedicated GHCR repository instead of the main image repository.\n\nCurrent split:\n\n- deployable images and multi-arch manifests stay under `ghcr.io/\u003cowner\u003e/sambee`\n- SBOM and provenance metadata bundles and Cosign signature artifacts are written under `ghcr.io/\u003cowner\u003e/sambee-signatures`\n\nFor Cosign-managed signatures, GHCR can display a digest-derived tagged signature artifact together with an untagged referenced bundle manifest for the same retained image digest.\n\nThat keeps the main package page focused on deployable image versions instead of showing non-runnable attestation content there.\n\nThose controls do not replace vulnerability scanning.\n\nThey answer a different question: whether a published artifact can be traced and verified after it is built.\n\n## Workflow Pinning Discipline\n\nSecurity-relevant GitHub Actions in this repository are pinned by commit SHA rather than floating major tags.\n\nThat reduces uncontrolled workflow drift in the automation layer itself.\n\nTreat action-version changes in these workflows as reviewed dependency changes, not as incidental cleanup.\n\n## How This Fits with Dependency Security\n\nUse [Dependency Security and Dependabot](../dependency-security-and-dependabot/) for the repository's dependency intake rules, Dependabot grouping, and scheduled dependency vulnerability audits.\n\n"}, "page_contents": {"0.7": "+++\ntitle = \"Container Image Security and Artifact Integrity\"\n+++\n\nContainer-image security answers a different question than dependency-manifest auditing.\n\nSambee uses Trivy and release-artifact integrity controls to validate the final published container image, not just the repository dependency files.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/docker-image-security-scan.yml` | builds the current `main` image and runs the weekly Trivy scan |\n| `.github/workflows/docker-image-preview-publish.yml` | runs the preview-candidate Trivy scan before publishing to the `test` channel |\n| `.github/workflows/docker-image-publish.yml` | promotes a verified candidate digest onto release tags after checking image metadata and the published metadata bundle |\n| `.github/scripts/verify_candidate_metadata_bundle.sh` | verifies that the preview-built SBOM and provenance bundle exists under the expected digest-derived metadata tag |\n| `.github/tools/trivy/Dockerfile` | pins the Trivy container image version that both scan workflows use |\n| `.trivyignore.yaml` | holds reviewed Trivy suppressions for the image scans |\n| `Dockerfile` | defines the runtime artifact that is actually scanned and published |\n\n## Why Trivy Exists Alongside Dependency Audits\n\nDependency audits help with application dependency drift.\n\nTrivy adds coverage for the built runtime artifact itself, especially:\n\n- vulnerabilities inherited from the pinned base image\n- vulnerabilities in OS packages installed during the Docker build\n- the final package set that actually ships in the container\n\nThat matters for Sambee because the final image includes native tooling and runtime libraries that are outside the normal `pip`, `npm`, and `cargo` manifest audits.\n\n## Trivy Setup\n\nSambee currently uses Trivy in two places.\n\nBoth workflows resolve the Trivy runtime image from `.github/tools/trivy/Dockerfile`, so the pin is reviewed once and Dependabot can update it through the `docker` ecosystem.\n\nBoth workflows also force a fresh rebuild of the Dockerfile layer that installs Debian packages.\n\nThey do that with a workflow-provided refresh key passed into the image build, so `apt-get update`, `apt-get upgrade`, and package installation rerun against the latest repository state available at build time while the rest of the image can still benefit from BuildKit caching.\n\n### Weekly Image Scan on `main`\n\n`.github/workflows/docker-image-security-scan.yml` builds the current production image from `main` and scans it once per week.\n\nThe scan currently:\n\n- builds and scans the supported `linux/amd64` and `linux/arm64` image variants separately\n- forces a fresh rebuild of the Debian package-install layer for each workflow run\n- uses `.trivyignore.yaml` as the reviewed suppression file\n- shows suppressed findings in the output\n- checks OS packages and application libraries\n- considers only `HIGH` and `CRITICAL` vulnerabilities\n- ignores unfixed vulnerabilities\n- fails the workflow when matching fixed vulnerabilities remain after suppression\n\nThis is the workflow that tells you a shipped runtime stack has picked up a newly disclosed issue even when no new Sambee release is in progress.\n\n### Preview Publish Scan\n\n`.github/workflows/docker-image-preview-publish.yml` runs Trivy against each pushed preview platform image before those platform manifests are assembled into the preview candidate index.\n\nCurrent preview behavior is intentionally advisory:\n\n- the preview build forces a fresh rebuild of the Debian package-install layer before Trivy runs and before the candidate is published\n- Trivy scans the same pushed platform digests that are later assembled into the final preview candidate\n- preview publishes still show matching `HIGH` or `CRITICAL` findings\n- the findings do not block publication to the `test` channel\n\nThat keeps the newest preview candidate available for validation while still surfacing image risk clearly in CI.\n\n## Trivy Ignore Policy\n\nThe repository-root `.trivyignore.yaml` file is the shared suppression file for both Trivy workflows.\n\nKeep entries narrow and reviewable.\n\nEach suppression should include:\n\n- the finding ID\n- a short statement describing why the risk is accepted temporarily\n- an `expired_at` date so the exception must be revisited explicitly\n\nThat keeps long-lived silent exceptions from accumulating in the image-security workflows.\n\n## Artifact Integrity\n\nThe preview publish and release promotion workflows enable:\n\n- SBOM and provenance bundle publication in a dedicated metadata repository\n- Cosign signing of the pushed image digest through GitHub Actions OIDC\n\nRelease promotion also verifies that the preview-built metadata bundle matches the candidate digest before channel tags are moved.\n\nRelease and backfill workflows mirror the exact metadata bundle files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in GHCR remains the canonical store.\n\nCosign signatures are stored in a dedicated GHCR repository instead of the main image repository.\n\nCurrent split:\n\n- deployable images and multi-arch manifests stay under `ghcr.io/\u003cowner\u003e/sambee`\n- SBOM and provenance metadata bundles and Cosign signature artifacts are written under `ghcr.io/\u003cowner\u003e/sambee-signatures`\n\nFor Cosign-managed signatures, GHCR can display a digest-derived tagged signature artifact together with an untagged referenced bundle manifest for the same retained image digest.\n\nThat keeps the main package page focused on deployable image versions instead of showing non-runnable attestation content there.\n\nThose controls do not replace vulnerability scanning.\n\nThey answer a different question: whether a published artifact can be traced and verified after it is built.\n\n## Workflow Pinning Discipline\n\nSecurity-relevant GitHub Actions in this repository are pinned by commit SHA rather than floating major tags.\n\nThat reduces uncontrolled workflow drift in the automation layer itself.\n\nTreat action-version changes in these workflows as reviewed dependency changes, not as incidental cleanup.\n\n## How This Fits with Dependency Security\n\nUse [Dependency Security and Dependabot](../dependency-security-and-dependabot/) for the repository's dependency intake rules, Dependabot grouping, and scheduled dependency vulnerability audits.\n\n", "0.8": "+++\ntitle = \"Container Image Security and Artifact Integrity\"\n+++\n\nContainer-image security answers a different question than dependency-manifest auditing.\n\nSambee uses Trivy and release-artifact integrity controls to validate the final published container image, not just the repository dependency files.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/docker-image-security-scan.yml` | builds the current `main` image and runs the weekly Trivy scan |\n| `.github/workflows/docker-image-preview-publish.yml` | runs the preview-candidate Trivy scan before publishing to the `test` channel |\n| `.github/workflows/docker-image-publish.yml` | promotes a verified candidate digest onto release tags after checking image metadata and the published metadata bundle |\n| `.github/scripts/verify_candidate_metadata_bundle.sh` | verifies that the preview-built SBOM and provenance bundle exists under the expected digest-derived metadata tag |\n| `.github/tools/trivy/Dockerfile` | pins the Trivy container image version that both scan workflows use |\n| `.trivyignore.yaml` | holds reviewed Trivy suppressions for the image scans |\n| `Dockerfile` | defines the runtime artifact that is actually scanned and published |\n\n## Why Trivy Exists Alongside Dependency Audits\n\nDependency audits help with application dependency drift.\n\nTrivy adds coverage for the built runtime artifact itself, especially:\n\n- vulnerabilities inherited from the pinned base image\n- vulnerabilities in OS packages installed during the Docker build\n- the final package set that actually ships in the container\n\nThat matters for Sambee because the final image includes native tooling and runtime libraries that are outside the normal `pip`, `npm`, and `cargo` manifest audits.\n\n## Trivy Setup\n\nSambee currently uses Trivy in two places.\n\nBoth workflows resolve the Trivy runtime image from `.github/tools/trivy/Dockerfile`, so the pin is reviewed once and Dependabot can update it through the `docker` ecosystem.\n\nBoth workflows also force a fresh rebuild of the Dockerfile layer that installs Debian packages.\n\nThey do that with a workflow-provided refresh key passed into the image build, so `apt-get update`, `apt-get upgrade`, and package installation rerun against the latest repository state available at build time while the rest of the image can still benefit from BuildKit caching.\n\n### Weekly Image Scan on `main`\n\n`.github/workflows/docker-image-security-scan.yml` builds the current production image from `main` and scans it once per week.\n\nThe scan currently:\n\n- builds and scans the supported `linux/amd64` and `linux/arm64` image variants separately\n- forces a fresh rebuild of the Debian package-install layer for each workflow run\n- uses `.trivyignore.yaml` as the reviewed suppression file\n- shows suppressed findings in the output\n- checks OS packages and application libraries\n- considers only `HIGH` and `CRITICAL` vulnerabilities\n- ignores unfixed vulnerabilities\n- fails the workflow when matching fixed vulnerabilities remain after suppression\n\nThis is the workflow that tells you a shipped runtime stack has picked up a newly disclosed issue even when no new Sambee release is in progress.\n\n### Preview Publish Scan\n\n`.github/workflows/docker-image-preview-publish.yml` runs Trivy against each pushed preview platform image before those platform manifests are assembled into the preview candidate index.\n\nCurrent preview behavior is intentionally advisory:\n\n- the preview build forces a fresh rebuild of the Debian package-install layer before Trivy runs and before the candidate is published\n- Trivy scans the same pushed platform digests that are later assembled into the final preview candidate\n- preview publishes still show matching `HIGH` or `CRITICAL` findings\n- the findings do not block publication to the `test` channel\n\nThat keeps the newest preview candidate available for validation while still surfacing image risk clearly in CI.\n\n## Trivy Ignore Policy\n\nThe repository-root `.trivyignore.yaml` file is the shared suppression file for both Trivy workflows.\n\nKeep entries narrow and reviewable.\n\nEach suppression should include:\n\n- the finding ID\n- a short statement describing why the risk is accepted temporarily\n- an `expired_at` date so the exception must be revisited explicitly\n\nThat keeps long-lived silent exceptions from accumulating in the image-security workflows.\n\n## Artifact Integrity\n\nThe preview publish and release promotion workflows enable:\n\n- SBOM and provenance bundle publication in a dedicated metadata repository\n- Cosign signing of the pushed image digest through GitHub Actions OIDC\n\nRelease promotion also verifies that the preview-built metadata bundle matches the candidate digest before channel tags are moved.\n\nRelease and backfill workflows mirror the exact metadata bundle files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in GHCR remains the canonical store.\n\nCosign signatures are stored in a dedicated GHCR repository instead of the main image repository.\n\nCurrent split:\n\n- deployable images and multi-arch manifests stay under `ghcr.io/\u003cowner\u003e/sambee`\n- SBOM and provenance metadata bundles and Cosign signature artifacts are written under `ghcr.io/\u003cowner\u003e/sambee-signatures`\n\nFor Cosign-managed signatures, GHCR can display a digest-derived tagged signature artifact together with an untagged referenced bundle manifest for the same retained image digest.\n\nThat keeps the main package page focused on deployable image versions instead of showing non-runnable attestation content there.\n\nThose controls do not replace vulnerability scanning.\n\nThey answer a different question: whether a published artifact can be traced and verified after it is built.\n\n## Workflow Pinning Discipline\n\nSecurity-relevant GitHub Actions in this repository are pinned by commit SHA rather than floating major tags.\n\nThat reduces uncontrolled workflow drift in the automation layer itself.\n\nTreat action-version changes in these workflows as reviewed dependency changes, not as incidental cleanup.\n\n## How This Fits with Dependency Security\n\nUse [Dependency Security and Dependabot](../dependency-security-and-dependabot/) for the repository's dependency intake rules, Dependabot grouping, and scheduled dependency vulnerability audits.\n\n", "0.9": "+++\ntitle = \"Container Image Security and Artifact Integrity\"\n+++\n\nContainer-image security answers a different question than dependency-manifest auditing.\n\nSambee uses Trivy and release-artifact integrity controls to validate the final published container image, not just the repository dependency files.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/docker-image-security-scan.yml` | builds the current `main` image and runs the weekly Trivy scan |\n| `.github/workflows/docker-image-preview-publish.yml` | runs the preview-candidate Trivy scan before publishing to the `test` channel |\n| `.github/workflows/docker-image-publish.yml` | promotes a verified candidate digest onto release tags after checking image metadata and the published metadata bundle |\n| `.github/scripts/verify_candidate_metadata_bundle.sh` | verifies that the preview-built SBOM and provenance bundle exists under the expected digest-derived metadata tag |\n| `.github/tools/trivy/Dockerfile` | pins the Trivy container image version that both scan workflows use |\n| `.trivyignore.yaml` | holds reviewed Trivy suppressions for the image scans |\n| `Dockerfile` | defines the runtime artifact that is actually scanned and published |\n\n## Why Trivy Exists Alongside Dependency Audits\n\nDependency audits help with application dependency drift.\n\nTrivy adds coverage for the built runtime artifact itself, especially:\n\n- vulnerabilities inherited from the pinned base image\n- vulnerabilities in OS packages installed during the Docker build\n- the final package set that actually ships in the container\n\nThat matters for Sambee because the final image includes native tooling and runtime libraries that are outside the normal `pip`, `npm`, and `cargo` manifest audits.\n\n## Trivy Setup\n\nSambee currently uses Trivy in two places.\n\nBoth workflows resolve the Trivy runtime image from `.github/tools/trivy/Dockerfile`, so the pin is reviewed once and Dependabot can update it through the `docker` ecosystem.\n\nBoth workflows also force a fresh rebuild of the Dockerfile layer that installs Debian packages.\n\nThey do that with a workflow-provided refresh key passed into the image build, so `apt-get update`, `apt-get upgrade`, and package installation rerun against the latest repository state available at build time while the rest of the image can still benefit from BuildKit caching.\n\n### Weekly Image Scan on `main`\n\n`.github/workflows/docker-image-security-scan.yml` builds the current production image from `main` and scans it once per week.\n\nThe scan currently:\n\n- builds and scans the supported `linux/amd64` and `linux/arm64` image variants separately\n- forces a fresh rebuild of the Debian package-install layer for each workflow run\n- uses `.trivyignore.yaml` as the reviewed suppression file\n- shows suppressed findings in the output\n- checks OS packages and application libraries\n- considers only `HIGH` and `CRITICAL` vulnerabilities\n- ignores unfixed vulnerabilities\n- fails the workflow when matching fixed vulnerabilities remain after suppression\n\nThis is the workflow that tells you a shipped runtime stack has picked up a newly disclosed issue even when no new Sambee release is in progress.\n\n### Preview Publish Scan\n\n`.github/workflows/docker-image-preview-publish.yml` runs Trivy against each pushed preview platform image before those platform manifests are assembled into the preview candidate index.\n\nCurrent preview behavior is intentionally advisory:\n\n- the preview build forces a fresh rebuild of the Debian package-install layer before Trivy runs and before the candidate is published\n- Trivy scans the same pushed platform digests that are later assembled into the final preview candidate\n- preview publishes still show matching `HIGH` or `CRITICAL` findings\n- the findings do not block publication to the `test` channel\n\nThat keeps the newest preview candidate available for validation while still surfacing image risk clearly in CI.\n\n## Trivy Ignore Policy\n\nThe repository-root `.trivyignore.yaml` file is the shared suppression file for both Trivy workflows.\n\nKeep entries narrow and reviewable.\n\nEach suppression should include:\n\n- the finding ID\n- a short statement describing why the risk is accepted temporarily\n- an `expired_at` date so the exception must be revisited explicitly\n\nThat keeps long-lived silent exceptions from accumulating in the image-security workflows.\n\n## Artifact Integrity\n\nThe preview publish and release promotion workflows enable:\n\n- SBOM and provenance bundle publication in a dedicated metadata repository\n- Cosign signing of the pushed image digest through GitHub Actions OIDC\n\nRelease promotion also verifies that the preview-built metadata bundle matches the candidate digest before channel tags are moved.\n\nRelease and backfill workflows mirror the exact metadata bundle files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in GHCR remains the canonical store.\n\nCosign signatures are stored in a dedicated GHCR repository instead of the main image repository.\n\nCurrent split:\n\n- deployable images and multi-arch manifests stay under `ghcr.io/\u003cowner\u003e/sambee`\n- SBOM and provenance metadata bundles and Cosign signature artifacts are written under `ghcr.io/\u003cowner\u003e/sambee-signatures`\n\nFor Cosign-managed signatures, GHCR can display a digest-derived tagged signature artifact together with an untagged referenced bundle manifest for the same retained image digest.\n\nThat keeps the main package page focused on deployable image versions instead of showing non-runnable attestation content there.\n\nThose controls do not replace vulnerability scanning.\n\nThey answer a different question: whether a published artifact can be traced and verified after it is built.\n\n## Workflow Pinning Discipline\n\nSecurity-relevant GitHub Actions in this repository are pinned by commit SHA rather than floating major tags.\n\nThat reduces uncontrolled workflow drift in the automation layer itself.\n\nTreat action-version changes in these workflows as reviewed dependency changes, not as incidental cleanup.\n\n## How This Fits with Dependency Security\n\nUse [Dependency Security and Dependabot](../dependency-security-and-dependabot/) for the repository's dependency intake rules, Dependabot grouping, and scheduled dependency vulnerability audits.\n\n", "1.0": "+++\ntitle = \"Container Image Security and Artifact Integrity\"\n+++\n\nContainer-image security answers a different question than dependency-manifest auditing.\n\nSambee uses Trivy and release-artifact integrity controls to validate the final published container image, not just the repository dependency files.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/docker-image-security-scan.yml` | builds the current `main` image and runs the weekly Trivy scan |\n| `.github/workflows/docker-image-preview-publish.yml` | runs the preview-candidate Trivy scan before publishing to the `test` channel |\n| `.github/workflows/docker-image-publish.yml` | promotes a verified candidate digest onto release tags after checking image metadata and the published metadata bundle |\n| `.github/scripts/verify_candidate_metadata_bundle.sh` | verifies that the preview-built SBOM and provenance bundle exists under the expected digest-derived metadata tag |\n| `.github/tools/trivy/Dockerfile` | pins the Trivy container image version that both scan workflows use |\n| `.trivyignore.yaml` | holds reviewed Trivy suppressions for the image scans |\n| `Dockerfile` | defines the runtime artifact that is actually scanned and published |\n\n## Why Trivy Exists Alongside Dependency Audits\n\nDependency audits help with application dependency drift.\n\nTrivy adds coverage for the built runtime artifact itself, especially:\n\n- vulnerabilities inherited from the pinned base image\n- vulnerabilities in OS packages installed during the Docker build\n- the final package set that actually ships in the container\n\nThat matters for Sambee because the final image includes native tooling and runtime libraries that are outside the normal `pip`, `npm`, and `cargo` manifest audits.\n\n## Trivy Setup\n\nSambee currently uses Trivy in two places.\n\nBoth workflows resolve the Trivy runtime image from `.github/tools/trivy/Dockerfile`, so the pin is reviewed once and Dependabot can update it through the `docker` ecosystem.\n\nBoth workflows also force a fresh rebuild of the Dockerfile layer that installs Debian packages.\n\nThey do that with a workflow-provided refresh key passed into the image build, so `apt-get update`, `apt-get upgrade`, and package installation rerun against the latest repository state available at build time while the rest of the image can still benefit from BuildKit caching.\n\n### Weekly Image Scan on `main`\n\n`.github/workflows/docker-image-security-scan.yml` builds the current production image from `main` and scans it once per week.\n\nThe scan currently:\n\n- builds and scans the supported `linux/amd64` and `linux/arm64` image variants separately\n- forces a fresh rebuild of the Debian package-install layer for each workflow run\n- uses `.trivyignore.yaml` as the reviewed suppression file\n- shows suppressed findings in the output\n- checks OS packages and application libraries\n- considers only `HIGH` and `CRITICAL` vulnerabilities\n- ignores unfixed vulnerabilities\n- fails the workflow when matching fixed vulnerabilities remain after suppression\n\nThis is the workflow that tells you a shipped runtime stack has picked up a newly disclosed issue even when no new Sambee release is in progress.\n\n### Preview Publish Scan\n\n`.github/workflows/docker-image-preview-publish.yml` runs Trivy against each pushed preview platform image before those platform manifests are assembled into the preview candidate index.\n\nCurrent preview behavior is intentionally advisory:\n\n- the preview build forces a fresh rebuild of the Debian package-install layer before Trivy runs and before the candidate is published\n- Trivy scans the same pushed platform digests that are later assembled into the final preview candidate\n- preview publishes still show matching `HIGH` or `CRITICAL` findings\n- the findings do not block publication to the `test` channel\n\nThat keeps the newest preview candidate available for validation while still surfacing image risk clearly in CI.\n\n## Trivy Ignore Policy\n\nThe repository-root `.trivyignore.yaml` file is the shared suppression file for both Trivy workflows.\n\nKeep entries narrow and reviewable.\n\nEach suppression should include:\n\n- the finding ID\n- a short statement describing why the risk is accepted temporarily\n- an `expired_at` date so the exception must be revisited explicitly\n\nThat keeps long-lived silent exceptions from accumulating in the image-security workflows.\n\n## Artifact Integrity\n\nThe preview publish and release promotion workflows enable:\n\n- SBOM and provenance bundle publication in a dedicated metadata repository\n- Cosign signing of the pushed image digest through GitHub Actions OIDC\n\nRelease promotion also verifies that the preview-built metadata bundle matches the candidate digest before channel tags are moved.\n\nRelease and backfill workflows mirror the exact metadata bundle files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in GHCR remains the canonical store.\n\nCosign signatures are stored in a dedicated GHCR repository instead of the main image repository.\n\nCurrent split:\n\n- deployable images and multi-arch manifests stay under `ghcr.io/\u003cowner\u003e/sambee`\n- SBOM and provenance metadata bundles and Cosign signature artifacts are written under `ghcr.io/\u003cowner\u003e/sambee-signatures`\n\nFor Cosign-managed signatures, GHCR can display a digest-derived tagged signature artifact together with an untagged referenced bundle manifest for the same retained image digest.\n\nThat keeps the main package page focused on deployable image versions instead of showing non-runnable attestation content there.\n\nThose controls do not replace vulnerability scanning.\n\nThey answer a different question: whether a published artifact can be traced and verified after it is built.\n\n## Workflow Pinning Discipline\n\nSecurity-relevant GitHub Actions in this repository are pinned by commit SHA rather than floating major tags.\n\nThat reduces uncontrolled workflow drift in the automation layer itself.\n\nTreat action-version changes in these workflows as reviewed dependency changes, not as incidental cleanup.\n\n## How This Fits with Dependency Security\n\nUse [Dependency Security and Dependabot](../dependency-security-and-dependabot/) for the repository's dependency intake rules, Dependabot grouping, and scheduled dependency vulnerability audits.\n\n", "2.0": "+++\ntitle = \"Container Image Security and Artifact Integrity\"\n+++\n\nContainer-image security answers a different question than dependency-manifest auditing.\n\nSambee uses Trivy and release-artifact integrity controls to validate the final published container image, not just the repository dependency files.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/docker-image-security-scan.yml` | builds the current `main` image and runs the weekly Trivy scan |\n| `.github/workflows/docker-image-preview-publish.yml` | runs the preview-candidate Trivy scan before publishing to the `test` channel |\n| `.github/workflows/docker-image-publish.yml` | promotes a verified candidate digest onto release tags after checking image metadata and the published metadata bundle |\n| `.github/scripts/verify_candidate_metadata_bundle.sh` | verifies that the preview-built SBOM and provenance bundle exists under the expected digest-derived metadata tag |\n| `.github/tools/trivy/Dockerfile` | pins the Trivy container image version that both scan workflows use |\n| `.trivyignore.yaml` | holds reviewed Trivy suppressions for the image scans |\n| `Dockerfile` | defines the runtime artifact that is actually scanned and published |\n\n## Why Trivy Exists Alongside Dependency Audits\n\nDependency audits help with application dependency drift.\n\nTrivy adds coverage for the built runtime artifact itself, especially:\n\n- vulnerabilities inherited from the pinned base image\n- vulnerabilities in OS packages installed during the Docker build\n- the final package set that actually ships in the container\n\nThat matters for Sambee because the final image includes native tooling and runtime libraries that are outside the normal `pip`, `npm`, and `cargo` manifest audits.\n\n## Trivy Setup\n\nSambee currently uses Trivy in two places.\n\nBoth workflows resolve the Trivy runtime image from `.github/tools/trivy/Dockerfile`, so the pin is reviewed once and Dependabot can update it through the `docker` ecosystem.\n\nBoth workflows also force a fresh rebuild of the Dockerfile layer that installs Debian packages.\n\nThey do that with a workflow-provided refresh key passed into the image build, so `apt-get update`, `apt-get upgrade`, and package installation rerun against the latest repository state available at build time while the rest of the image can still benefit from BuildKit caching.\n\n### Weekly Image Scan on `main`\n\n`.github/workflows/docker-image-security-scan.yml` builds the current production image from `main` and scans it once per week.\n\nThe scan currently:\n\n- builds and scans the supported `linux/amd64` and `linux/arm64` image variants separately\n- forces a fresh rebuild of the Debian package-install layer for each workflow run\n- uses `.trivyignore.yaml` as the reviewed suppression file\n- shows suppressed findings in the output\n- checks OS packages and application libraries\n- considers only `HIGH` and `CRITICAL` vulnerabilities\n- ignores unfixed vulnerabilities\n- fails the workflow when matching fixed vulnerabilities remain after suppression\n\nThis is the workflow that tells you a shipped runtime stack has picked up a newly disclosed issue even when no new Sambee release is in progress.\n\n### Preview Publish Scan\n\n`.github/workflows/docker-image-preview-publish.yml` runs Trivy against each pushed preview platform image before those platform manifests are assembled into the preview candidate index.\n\nCurrent preview behavior is intentionally advisory:\n\n- the preview build forces a fresh rebuild of the Debian package-install layer before Trivy runs and before the candidate is published\n- Trivy scans the same pushed platform digests that are later assembled into the final preview candidate\n- preview publishes still show matching `HIGH` or `CRITICAL` findings\n- the findings do not block publication to the `test` channel\n\nThat keeps the newest preview candidate available for validation while still surfacing image risk clearly in CI.\n\n## Trivy Ignore Policy\n\nThe repository-root `.trivyignore.yaml` file is the shared suppression file for both Trivy workflows.\n\nKeep entries narrow and reviewable.\n\nEach suppression should include:\n\n- the finding ID\n- a short statement describing why the risk is accepted temporarily\n- an `expired_at` date so the exception must be revisited explicitly\n\nThat keeps long-lived silent exceptions from accumulating in the image-security workflows.\n\n## Artifact Integrity\n\nThe preview publish and release promotion workflows enable:\n\n- SBOM and provenance bundle publication in a dedicated metadata repository\n- Cosign signing of the pushed image digest through GitHub Actions OIDC\n\nRelease promotion also verifies that the preview-built metadata bundle matches the candidate digest before channel tags are moved.\n\nRelease and backfill workflows mirror the exact metadata bundle files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in GHCR remains the canonical store.\n\nCosign signatures are stored in a dedicated GHCR repository instead of the main image repository.\n\nCurrent split:\n\n- deployable images and multi-arch manifests stay under `ghcr.io/\u003cowner\u003e/sambee`\n- SBOM and provenance metadata bundles and Cosign signature artifacts are written under `ghcr.io/\u003cowner\u003e/sambee-signatures`\n\nFor Cosign-managed signatures, GHCR can display a digest-derived tagged signature artifact together with an untagged referenced bundle manifest for the same retained image digest.\n\nThat keeps the main package page focused on deployable image versions instead of showing non-runnable attestation content there.\n\nThose controls do not replace vulnerability scanning.\n\nThey answer a different question: whether a published artifact can be traced and verified after it is built.\n\n## Workflow Pinning Discipline\n\nSecurity-relevant GitHub Actions in this repository are pinned by commit SHA rather than floating major tags.\n\nThat reduces uncontrolled workflow drift in the automation layer itself.\n\nTreat action-version changes in these workflows as reviewed dependency changes, not as incidental cleanup.\n\n## How This Fits with Dependency Security\n\nUse [Dependency Security and Dependabot](../dependency-security-and-dependabot/) for the repository's dependency intake rules, Dependabot grouping, and scheduled dependency vulnerability audits.\n\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:developer-guide/release-and-versioning", "parent_id": "book:developer-guide", "depth": 1, "kind": "section", "label": "release-and-versioning", "title": "Release and Versioning", "path": "developer-guide/release-and-versioning", "has_children": true, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "branched", "source_version": "0.7", "diff_added": 2, "diff_removed": 6}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "inherited", "source_version": "0.9"}}, "content_versions": {"0.7": "+++\ntitle = \"Release and Versioning\"\n+++\n\nThis section covers the workflows where a small metadata mistake can create cross-boundary drift.\n\nFor a complete Sambee product release, start here:\n\n- [Release Checklist](./release-checklist/)\n- [Product Versioning](./product-versioning/)\n\nFor dependency changes, use:\n\n- [Dependency Update Workflow](./dependency-update-workflow/)\n\nFor Sambee Docker image releases, read these pages in order:\n\n- [Docker Release Overview](./docker-release-overview/)\n- [Build Docker Image](./build-docker-image/)\n- [Promote Docker Image](./promote-docker-image/)\n- [Docker Backfill And Cleanup](./docker-backfill-and-cleanup/)\n\nUse these pages when the goal is to take one reviewed commit all the way to `stable` without rebuilding at release time.\n\nFor Companion release distribution, read these pages in order:\n\n- [Companion Release Overview](./companion-release-overview/)\n- [Build Companion Release](./build-companion-release/)\n- [Promote Companion Release](./promote-companion-release/)\n- [Companion Channels, Feeds, And Downloads](./companion-channels-feeds-and-downloads/)\n\nUse this section when you are changing version numbers, updating reviewed dependencies, or publishing a product release.\n", "0.8": "+++\ntitle = \"Release and Versioning\"\n+++\n\nThis section covers the workflows where a small metadata mistake can create cross-boundary drift.\n\nFor a complete Sambee product release, start here:\n\n- [Release Checklist](./release-checklist/)\n- [Product Versioning](./product-versioning/)\n\nFor dependency changes, use:\n\n- [Dependency Update Workflow](./dependency-update-workflow/)\n\nFor Sambee Docker image releases, read these pages in order:\n\n- [Docker Release Overview](./docker-release-overview/)\n- [Build Docker Image](./build-docker-image/)\n- [Promote Docker Image](./promote-docker-image/)\n- [Docker Backfill And Cleanup](./docker-backfill-and-cleanup/)\n\nUse these pages when the goal is to take one reviewed commit all the way to `stable` without rebuilding at release time.\n\nFor Companion release distribution, read these pages in order:\n\n- [Companion Release Overview](./companion-release-overview/)\n- [Build Companion Release](./build-companion-release/)\n- [Promote Companion Release](./promote-companion-release/)\n- [Companion Channels, Feeds, And Downloads](./companion-channels-feeds-and-downloads/)\n\nUse this section when you are changing version numbers, updating reviewed dependencies, or publishing a product release.\n", "0.9": "+++\ntitle = \"Release and Versioning\"\n+++\n\nThis section covers the process of publishing new versions of the Docker image and the Companion app.\n\nFor a complete Sambee product release, start here:\n\n- [Release Overview](./release-overview/)\n- [Product Versioning](./product-versioning/)\n\nFor dependency changes, use:\n\n- [Dependency Update Workflow](./dependency-update-workflow/)\n\nFor Sambee Docker image releases, read these pages in order:\n\n- [Docker Release Overview](./docker-release-overview/)\n- [Build Docker Image](./build-docker-image/)\n- [Promote Docker Image](./promote-docker-image/)\n- [Docker Backfill And Cleanup](./docker-backfill-and-cleanup/)\n\nFor Companion release distribution, read these pages in order:\n\n- [Companion Release Overview](./companion-release-overview/)\n- [Build Companion Release](./build-companion-release/)\n- [Promote Companion Release](./promote-companion-release/)\n- [Companion Channels, Feeds, And Downloads](./companion-channels-feeds-and-downloads/)\n", "1.0": "+++\ntitle = \"Release and Versioning\"\n+++\n\nThis section covers the process of publishing new versions of the Docker image and the Companion app.\n\nFor a complete Sambee product release, start here:\n\n- [Release Overview](./release-overview/)\n- [Product Versioning](./product-versioning/)\n\nFor dependency changes, use:\n\n- [Dependency Update Workflow](./dependency-update-workflow/)\n\nFor Sambee Docker image releases, read these pages in order:\n\n- [Docker Release Overview](./docker-release-overview/)\n- [Build Docker Image](./build-docker-image/)\n- [Promote Docker Image](./promote-docker-image/)\n- [Docker Backfill And Cleanup](./docker-backfill-and-cleanup/)\n\nFor Companion release distribution, read these pages in order:\n\n- [Companion Release Overview](./companion-release-overview/)\n- [Build Companion Release](./build-companion-release/)\n- [Promote Companion Release](./promote-companion-release/)\n- [Companion Channels, Feeds, And Downloads](./companion-channels-feeds-and-downloads/)\n", "2.0": "+++\ntitle = \"Release and Versioning\"\n+++\n\nThis section covers the process of publishing new versions of the Docker image and the Companion app.\n\nFor a complete Sambee product release, start here:\n\n- [Release Overview](./release-overview/)\n- [Product Versioning](./product-versioning/)\n\nFor dependency changes, use:\n\n- [Dependency Update Workflow](./dependency-update-workflow/)\n\nFor Sambee Docker image releases, read these pages in order:\n\n- [Docker Release Overview](./docker-release-overview/)\n- [Build Docker Image](./build-docker-image/)\n- [Promote Docker Image](./promote-docker-image/)\n- [Docker Backfill And Cleanup](./docker-backfill-and-cleanup/)\n\nFor Companion release distribution, read these pages in order:\n\n- [Companion Release Overview](./companion-release-overview/)\n- [Build Companion Release](./build-companion-release/)\n- [Promote Companion Release](./promote-companion-release/)\n- [Companion Channels, Feeds, And Downloads](./companion-channels-feeds-and-downloads/)\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/release-and-versioning/dependency-update-workflow", "parent_id": "section:developer-guide/release-and-versioning", "depth": 2, "kind": "page", "label": "dependency-update-workflow", "title": "Dependency Update Workflow", "path": "developer-guide/release-and-versioning/dependency-update-workflow", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "branched", "source_version": "0.7", "diff_added": 3, "diff_removed": 2}, "1.0": {"state": "branched", "source_version": "0.9", "diff_added": 12, "diff_removed": 14}, "2.0": {"state": "branched", "source_version": "1.0", "diff_added": 31, "diff_removed": 0}}, "content_versions": {"0.7": "+++\ntitle = \"Dependency Update Workflow\"\n+++\n\nUse this page for routine dependency updates and dependency-related release preparation. Use [Product Versioning](../product-versioning/) when changing the Sambee version, and [Release Checklist](../release-checklist/) when preparing a complete product release.\n\n## Dependency Update Rules\n\nRoutine install behavior and actual dependency changes are different workflows.\n\n- use `npm ci` for routine installs in `frontend/` and `companion/`\n- use the hashed backend lockfiles for routine Python installs\n- do not hand-edit generated lockfile details when the repository already provides a regeneration workflow\n\n### Backend Dependency Updates\n\nFor backend dependency changes:\n\n- update the reviewed top-level requirement files first\n- regenerate backend lockfiles with the supported refresh script\n- use `scripts/refresh-backend-lockfiles --check` for a read-only freshness check when needed\n- validate with backend tests and type checking\n\nThat keeps direct requirements, transitive dependencies, and hashes aligned.\n\nMore specifically:\n\n- change `requirements.txt` and `requirements-dev.txt`, not only the generated lockfiles\n- regenerate `requirements.lock.txt` and `requirements-dev.lock.txt` through `scripts/refresh-backend-lockfiles`\n- treat resolver conflicts as real compatibility constraints instead of forcing transitive pins by hand\n- avoid hand-editing lockfile hashes except as a last resort\n\nFor an already-open backend dependency-update PR:\n\n- review the direct requirement changes first\n- run `scripts/refresh-backend-lockfiles --check` if you want a quick stale-lockfile check before editing\n- regenerate the lockfiles from the reviewed sources\n- validate with at least `pytest -v` and `mypy app`\n- commit regenerated lockfiles back to the update branch instead of patching transitive entries manually\n\n### High-Risk Dependency Areas\n\nSome ecosystems are intentionally treated as coordinated manual changes rather than casual bumps.\n\n- Python runtime version\n- high-risk frontend packages such as React, Vite, TypeScript, and MUI\n- companion Tauri package and crate alignment\n- backend packages with higher behavioral risk such as `smbprotocol` and `pyvips`\n\nAdditional contributor rules in those areas:\n\n- keep companion Tauri JavaScript packages and Rust crates on matching major.minor versions\n- validate companion Tauri alignment with `scripts/check_tauri_version_alignment.py` when those dependencies move\n- treat Python runtime upgrades as coordinated manual changes across production Docker, the devcontainer, and CI\n- prefer committed scripts and lockfiles over one-off installers or floating `npx` downloads\n\n## Dependency Security Audits\n\nThe audit workflow and Dependabot configuration now live in the Developer Guide security section.\n\nUse [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/) for:\n\n- Dependabot grouping and ignore rules\n- scheduled dependency audit coverage\n\nUse [Container Image Security and Artifact Integrity](../../security/container-image-security-and-artifact-integrity/) for:\n\n- container-image vulnerability scanning\n- Trivy suppression policy\n- image signing, SBOM, and provenance controls\n\nKeep this page focused on dependency inputs, generated lockfiles, and dependency-specific validation.\n\n## Validation Expectations\n\nAt minimum, run the checks for the subsystem whose release-sensitive files changed.\n\nCommon examples:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nChoose the relevant subset based on the dependencies that changed.\n", "0.8": "+++\ntitle = \"Dependency Update Workflow\"\n+++\n\nUse this page for routine dependency updates and dependency-related release preparation. Use [Product Versioning](../product-versioning/) when changing the Sambee version, and [Release Checklist](../release-checklist/) when preparing a complete product release.\n\n## Dependency Update Rules\n\nRoutine install behavior and actual dependency changes are different workflows.\n\n- use `npm ci` for routine installs in `frontend/` and `companion/`\n- use the hashed backend lockfiles for routine Python installs\n- do not hand-edit generated lockfile details when the repository already provides a regeneration workflow\n\n### Backend Dependency Updates\n\nFor backend dependency changes:\n\n- update the reviewed top-level requirement files first\n- regenerate backend lockfiles with the supported refresh script\n- use `scripts/refresh-backend-lockfiles --check` for a read-only freshness check when needed\n- validate with backend tests and type checking\n\nThat keeps direct requirements, transitive dependencies, and hashes aligned.\n\nMore specifically:\n\n- change `requirements.txt` and `requirements-dev.txt`, not only the generated lockfiles\n- regenerate `requirements.lock.txt` and `requirements-dev.lock.txt` through `scripts/refresh-backend-lockfiles`\n- treat resolver conflicts as real compatibility constraints instead of forcing transitive pins by hand\n- avoid hand-editing lockfile hashes except as a last resort\n\nFor an already-open backend dependency-update PR:\n\n- review the direct requirement changes first\n- run `scripts/refresh-backend-lockfiles --check` if you want a quick stale-lockfile check before editing\n- regenerate the lockfiles from the reviewed sources\n- validate with at least `pytest -v` and `mypy app`\n- commit regenerated lockfiles back to the update branch instead of patching transitive entries manually\n\n### High-Risk Dependency Areas\n\nSome ecosystems are intentionally treated as coordinated manual changes rather than casual bumps.\n\n- Python runtime version\n- high-risk frontend packages such as React, Vite, TypeScript, and MUI\n- companion Tauri package and crate alignment\n- backend packages with higher behavioral risk such as `smbprotocol` and `pyvips`\n\nAdditional contributor rules in those areas:\n\n- keep companion Tauri JavaScript packages and Rust crates on matching major.minor versions\n- validate companion Tauri alignment with `scripts/check_tauri_version_alignment.py` when those dependencies move\n- treat Python runtime upgrades as coordinated manual changes across production Docker, the devcontainer, and CI\n- prefer committed scripts and lockfiles over one-off installers or floating `npx` downloads\n\n## Dependency Security Audits\n\nThe audit workflow and Dependabot configuration now live in the Developer Guide security section.\n\nUse [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/) for:\n\n- Dependabot grouping and ignore rules\n- scheduled dependency audit coverage\n\nUse [Container Image Security and Artifact Integrity](../../security/container-image-security-and-artifact-integrity/) for:\n\n- container-image vulnerability scanning\n- Trivy suppression policy\n- image signing, SBOM, and provenance controls\n\nKeep this page focused on dependency inputs, generated lockfiles, and dependency-specific validation.\n\n## Validation Expectations\n\nAt minimum, run the checks for the subsystem whose release-sensitive files changed.\n\nCommon examples:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nChoose the relevant subset based on the dependencies that changed.\n", "0.9": "+++\ntitle = \"Dependency Update Workflow\"\n+++\n\nUse this page for routine dependency updates and dependency-related release preparation. Use [Product Versioning](../product-versioning/) when changing the Sambee version, and [Release Checklist](../release-checklist/) when preparing a complete product release.\n\n## Dependency Update Rules\n\nRoutine install behavior and actual dependency changes are different workflows.\n\n- use `npm ci` for routine installs in `frontend/` and `companion/`\n- use the hashed backend lockfiles for routine Python installs\n- do not hand-edit generated lockfile details when the repository already provides a regeneration workflow\n\n### Backend Dependency Updates\n\nFor backend dependency changes:\n\n- update the reviewed top-level requirement files first\n- regenerate backend lockfiles with the supported refresh script\n- use `scripts/refresh-backend-lockfiles --check` for a read-only freshness check when needed\n- validate with backend tests and type checking\n\nThat keeps direct requirements, transitive dependencies, and hashes aligned.\n\nMore specifically:\n\n- change `requirements.txt` and `requirements-dev.txt`, not only the generated lockfiles\n- regenerate `requirements.lock.txt` and `requirements-dev.lock.txt` through `scripts/refresh-backend-lockfiles`\n- treat resolver conflicts as real compatibility constraints instead of forcing transitive pins by hand\n- avoid hand-editing lockfile hashes except as a last resort\n\nFor an already-open backend dependency-update PR:\n\n- review the direct requirement changes first\n- run `scripts/refresh-backend-lockfiles --check` if you want a quick stale-lockfile check before editing\n- regenerate the lockfiles from the reviewed sources\n- validate with at least `pytest -v` and `mypy app`\n- commit regenerated lockfiles back to the update branch instead of patching transitive entries manually\n\n### High-Risk Dependency Areas\n\nSome ecosystems are intentionally treated as coordinated manual changes rather than casual bumps.\n\n- high-risk frontend packages such as React, Vite, TypeScript, and MUI\n- companion Tauri package and crate alignment\n- backend packages with higher behavioral risk such as `smbprotocol` and `pyvips`\n\nAdditional contributor rules in those areas:\n\n- keep companion Tauri JavaScript packages and Rust crates on matching major.minor versions\n- validate companion Tauri alignment with `scripts/check_tauri_version_alignment.py` when those dependencies move\n- review Dependabot proposals for the shared Python runtime base as container-runtime changes\n- confirm Docker target validation reports the expected Python and SQLite versions before merging a Python runtime update\n- expect Debian packages to refresh during cache-busted image builds; do not hand-pin individual APT packages unless reproducibility requirements change\n- prefer committed scripts and lockfiles over one-off installers or floating `npx` downloads\n\n## Dependency Security Audits\n\nThe audit workflow and Dependabot configuration now live in the Developer Guide security section.\n\nUse [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/) for:\n\n- Dependabot grouping and ignore rules\n- scheduled dependency audit coverage\n\nUse [Container Image Security and Artifact Integrity](../../security/container-image-security-and-artifact-integrity/) for:\n\n- container-image vulnerability scanning\n- Trivy suppression policy\n- image signing, SBOM, and provenance controls\n\nKeep this page focused on dependency inputs, generated lockfiles, and dependency-specific validation.\n\n## Validation Expectations\n\nAt minimum, run the checks for the subsystem whose release-sensitive files changed.\n\nCommon examples:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nChoose the relevant subset based on the dependencies that changed.\n", "1.0": "+++\ntitle = \"Dependency Update Workflow\"\n+++\n\nUse this page for routine dependency updates and dependency-related release preparation. Use [Product Versioning](../product-versioning/) when changing the Sambee version, and [Release Checklist](../release-checklist/) when preparing a complete product release.\n\n## Dependency Update Rules\n\nRoutine install behavior and actual dependency changes are different workflows.\n\n- use `npm ci` for routine installs in `frontend/` and `companion/`\n- use the hashed backend lockfiles for routine Python installs\n- do not hand-edit generated lockfile details when the repository already provides a regeneration workflow\n- accept Dependabot updates to backend requirements and pip-compile lockfiles when CI validation passes\n\n### Backend Dependency Updates\n\nFor routine Dependabot backend dependency-update pull requests:\n\n- review the direct requirement and generated lockfile changes\n- do not rerun the backend lockfile refresh script only to satisfy CI\n- validate with backend tests and type checking\n\nCI verifies that direct source pins match both generated lockfiles. The backend\ntest image and production Docker image validate hash-enforced installations.\n\nFor manual backend dependency changes or an intentional full transitive refresh:\n\n- update `requirements.txt` and `requirements-dev.txt` first\n- regenerate `requirements.lock.txt` and `requirements-dev.lock.txt` through `scripts/refresh-backend-lockfiles`\n- treat resolver conflicts as real compatibility constraints instead of forcing transitive pins by hand\n- avoid hand-editing lockfile hashes except as a last resort\n\nUse `scripts/refresh-backend-lockfiles --check` when you deliberately want to\ncompare the committed locks with a new clean dependency resolution. It is an\noptional maintenance check, not a required step for routine Dependabot pull\nrequests.\n\n### High-Risk Dependency Areas\n\nSome ecosystems are intentionally treated as coordinated manual changes rather than casual bumps.\n\n- high-risk frontend packages such as React, Vite, TypeScript, and MUI\n- companion Tauri package and crate alignment\n- backend packages with higher behavioral risk such as `smbprotocol` and `pyvips`\n\nAdditional contributor rules in those areas:\n\n- keep companion Tauri JavaScript packages and Rust crates on matching major.minor versions\n- validate companion Tauri alignment with `scripts/check_tauri_version_alignment.py` when those dependencies move\n- review Dependabot proposals for the shared Python runtime base as container-runtime changes\n- confirm Docker target validation reports the expected Python and SQLite versions before merging a Python runtime update\n- expect Debian packages to refresh during cache-busted image builds; do not hand-pin individual APT packages unless reproducibility requirements change\n- prefer committed scripts and lockfiles over one-off installers or floating `npx` downloads\n\n## Dependency Security Audits\n\nThe audit workflow and Dependabot configuration now live in the Developer Guide security section.\n\nUse [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/) for:\n\n- Dependabot grouping and ignore rules\n- scheduled dependency audit coverage\n\nUse [Container Image Security and Artifact Integrity](../../security/container-image-security-and-artifact-integrity/) for:\n\n- container-image vulnerability scanning\n- Trivy suppression policy\n- image signing, SBOM, and provenance controls\n\nKeep this page focused on dependency inputs, generated lockfiles, and dependency-specific validation.\n\n## Validation Expectations\n\nAt minimum, run the checks for the subsystem whose release-sensitive files changed.\n\nCommon examples:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nChoose the relevant subset based on the dependencies that changed.\n", "2.0": "+++\ntitle = \"Dependency Update Workflow\"\n+++\n\nUse this page for routine dependency updates and dependency-related release preparation. Use [Product Versioning](../product-versioning/) when changing the Sambee version, and [Release Checklist](../release-checklist/) when preparing a complete product release.\n\n## Dependency Update Rules\n\nRoutine install behavior and actual dependency changes are different workflows.\n\n- use `npm ci` for routine installs in `frontend/` and `companion/`\n- use the hashed backend lockfiles for routine Python installs\n- do not hand-edit generated lockfile details when the repository already provides a regeneration workflow\n- accept Dependabot updates to backend requirements and pip-compile lockfiles when CI validation passes\n\n### Frontend Install Freshness\n\n`./scripts/test` checks frontend dependency freshness before generating test\nfixtures or running backend tests. It stops if the install stamp is missing or\ndoesn't match the current `frontend/package.json` and\n`frontend/package-lock.json`. It doesn't install dependencies automatically or\nrequire network access for the check.\n\nTo restore the frontend environment, run this from the repository root:\n\n```bash\ncd frontend \u0026\u0026 npm ci\n```\n\nThe install lifecycle clears any previous stamp before setup and writes a SHA-256\nhash to `frontend/node_modules/.dependencies.sha256` only after the existing\npostinstall setup succeeds. The stamp is local to the installed environment and\nisn't committed. Existing installations need one successful `npm ci` to create\nit. Installations using `--ignore-scripts` won't create the stamp.\n\nTo check the environment separately, run:\n\n```bash\ncd frontend \u0026\u0026 npm run check:dependencies\n```\n\nThe hash covers both files in full, so metadata-only changes also require a fresh\ninstall. This check detects changed dependency inputs, not arbitrary damage to\ninstalled packages. If individual packages are missing despite a matching stamp,\nrun `npm ci` again.\n\n### Backend Dependency Updates\n\nFor routine Dependabot backend dependency-update pull requests:\n\n- review the direct requirement and generated lockfile changes\n- do not rerun the backend lockfile refresh script only to satisfy CI\n- validate with backend tests and type checking\n\nCI verifies that direct source pins match both generated lockfiles. The backend\ntest image and production Docker image validate hash-enforced installations.\n\nFor manual backend dependency changes or an intentional full transitive refresh:\n\n- update `requirements.txt` and `requirements-dev.txt` first\n- regenerate `requirements.lock.txt` and `requirements-dev.lock.txt` through `scripts/refresh-backend-lockfiles`\n- treat resolver conflicts as real compatibility constraints instead of forcing transitive pins by hand\n- avoid hand-editing lockfile hashes except as a last resort\n\nUse `scripts/refresh-backend-lockfiles --check` when you deliberately want to\ncompare the committed locks with a new clean dependency resolution. It is an\noptional maintenance check, not a required step for routine Dependabot pull\nrequests.\n\n### High-Risk Dependency Areas\n\nSome ecosystems are intentionally treated as coordinated manual changes rather than casual bumps.\n\n- high-risk frontend packages such as React, Vite, TypeScript, and MUI\n- companion Tauri package and crate alignment\n- backend packages with higher behavioral risk such as `smbprotocol` and `pyvips`\n\nAdditional contributor rules in those areas:\n\n- keep companion Tauri JavaScript packages and Rust crates on matching major.minor versions\n- validate companion Tauri alignment with `scripts/check_tauri_version_alignment.py` when those dependencies move\n- review Dependabot proposals for the shared Python runtime base as container-runtime changes\n- confirm Docker target validation reports the expected Python and SQLite versions before merging a Python runtime update\n- expect Debian packages to refresh during cache-busted image builds; do not hand-pin individual APT packages unless reproducibility requirements change\n- prefer committed scripts and lockfiles over one-off installers or floating `npx` downloads\n\n## Dependency Security Audits\n\nThe audit workflow and Dependabot configuration now live in the Developer Guide security section.\n\nUse [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/) for:\n\n- Dependabot grouping and ignore rules\n- scheduled dependency audit coverage\n\nUse [Container Image Security and Artifact Integrity](../../security/container-image-security-and-artifact-integrity/) for:\n\n- container-image vulnerability scanning\n- Trivy suppression policy\n- image signing, SBOM, and provenance controls\n\nKeep this page focused on dependency inputs, generated lockfiles, and dependency-specific validation.\n\n## Validation Expectations\n\nAt minimum, run the checks for the subsystem whose release-sensitive files changed.\n\nCommon examples:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nChoose the relevant subset based on the dependencies that changed.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Dependency Update Workflow\"\n+++\n\nUse this page for routine dependency updates and dependency-related release preparation. Use [Product Versioning](../product-versioning/) when changing the Sambee version, and [Release Checklist](../release-checklist/) when preparing a complete product release.\n\n## Dependency Update Rules\n\nRoutine install behavior and actual dependency changes are different workflows.\n\n- use `npm ci` for routine installs in `frontend/` and `companion/`\n- use the hashed backend lockfiles for routine Python installs\n- do not hand-edit generated lockfile details when the repository already provides a regeneration workflow\n\n### Backend Dependency Updates\n\nFor backend dependency changes:\n\n- update the reviewed top-level requirement files first\n- regenerate backend lockfiles with the supported refresh script\n- use `scripts/refresh-backend-lockfiles --check` for a read-only freshness check when needed\n- validate with backend tests and type checking\n\nThat keeps direct requirements, transitive dependencies, and hashes aligned.\n\nMore specifically:\n\n- change `requirements.txt` and `requirements-dev.txt`, not only the generated lockfiles\n- regenerate `requirements.lock.txt` and `requirements-dev.lock.txt` through `scripts/refresh-backend-lockfiles`\n- treat resolver conflicts as real compatibility constraints instead of forcing transitive pins by hand\n- avoid hand-editing lockfile hashes except as a last resort\n\nFor an already-open backend dependency-update PR:\n\n- review the direct requirement changes first\n- run `scripts/refresh-backend-lockfiles --check` if you want a quick stale-lockfile check before editing\n- regenerate the lockfiles from the reviewed sources\n- validate with at least `pytest -v` and `mypy app`\n- commit regenerated lockfiles back to the update branch instead of patching transitive entries manually\n\n### High-Risk Dependency Areas\n\nSome ecosystems are intentionally treated as coordinated manual changes rather than casual bumps.\n\n- Python runtime version\n- high-risk frontend packages such as React, Vite, TypeScript, and MUI\n- companion Tauri package and crate alignment\n- backend packages with higher behavioral risk such as `smbprotocol` and `pyvips`\n\nAdditional contributor rules in those areas:\n\n- keep companion Tauri JavaScript packages and Rust crates on matching major.minor versions\n- validate companion Tauri alignment with `scripts/check_tauri_version_alignment.py` when those dependencies move\n- treat Python runtime upgrades as coordinated manual changes across production Docker, the devcontainer, and CI\n- prefer committed scripts and lockfiles over one-off installers or floating `npx` downloads\n\n## Dependency Security Audits\n\nThe audit workflow and Dependabot configuration now live in the Developer Guide security section.\n\nUse [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/) for:\n\n- Dependabot grouping and ignore rules\n- scheduled dependency audit coverage\n\nUse [Container Image Security and Artifact Integrity](../../security/container-image-security-and-artifact-integrity/) for:\n\n- container-image vulnerability scanning\n- Trivy suppression policy\n- image signing, SBOM, and provenance controls\n\nKeep this page focused on dependency inputs, generated lockfiles, and dependency-specific validation.\n\n## Validation Expectations\n\nAt minimum, run the checks for the subsystem whose release-sensitive files changed.\n\nCommon examples:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nChoose the relevant subset based on the dependencies that changed.\n", "0.8": "+++\ntitle = \"Dependency Update Workflow\"\n+++\n\nUse this page for routine dependency updates and dependency-related release preparation. Use [Product Versioning](../product-versioning/) when changing the Sambee version, and [Release Checklist](../release-checklist/) when preparing a complete product release.\n\n## Dependency Update Rules\n\nRoutine install behavior and actual dependency changes are different workflows.\n\n- use `npm ci` for routine installs in `frontend/` and `companion/`\n- use the hashed backend lockfiles for routine Python installs\n- do not hand-edit generated lockfile details when the repository already provides a regeneration workflow\n\n### Backend Dependency Updates\n\nFor backend dependency changes:\n\n- update the reviewed top-level requirement files first\n- regenerate backend lockfiles with the supported refresh script\n- use `scripts/refresh-backend-lockfiles --check` for a read-only freshness check when needed\n- validate with backend tests and type checking\n\nThat keeps direct requirements, transitive dependencies, and hashes aligned.\n\nMore specifically:\n\n- change `requirements.txt` and `requirements-dev.txt`, not only the generated lockfiles\n- regenerate `requirements.lock.txt` and `requirements-dev.lock.txt` through `scripts/refresh-backend-lockfiles`\n- treat resolver conflicts as real compatibility constraints instead of forcing transitive pins by hand\n- avoid hand-editing lockfile hashes except as a last resort\n\nFor an already-open backend dependency-update PR:\n\n- review the direct requirement changes first\n- run `scripts/refresh-backend-lockfiles --check` if you want a quick stale-lockfile check before editing\n- regenerate the lockfiles from the reviewed sources\n- validate with at least `pytest -v` and `mypy app`\n- commit regenerated lockfiles back to the update branch instead of patching transitive entries manually\n\n### High-Risk Dependency Areas\n\nSome ecosystems are intentionally treated as coordinated manual changes rather than casual bumps.\n\n- Python runtime version\n- high-risk frontend packages such as React, Vite, TypeScript, and MUI\n- companion Tauri package and crate alignment\n- backend packages with higher behavioral risk such as `smbprotocol` and `pyvips`\n\nAdditional contributor rules in those areas:\n\n- keep companion Tauri JavaScript packages and Rust crates on matching major.minor versions\n- validate companion Tauri alignment with `scripts/check_tauri_version_alignment.py` when those dependencies move\n- treat Python runtime upgrades as coordinated manual changes across production Docker, the devcontainer, and CI\n- prefer committed scripts and lockfiles over one-off installers or floating `npx` downloads\n\n## Dependency Security Audits\n\nThe audit workflow and Dependabot configuration now live in the Developer Guide security section.\n\nUse [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/) for:\n\n- Dependabot grouping and ignore rules\n- scheduled dependency audit coverage\n\nUse [Container Image Security and Artifact Integrity](../../security/container-image-security-and-artifact-integrity/) for:\n\n- container-image vulnerability scanning\n- Trivy suppression policy\n- image signing, SBOM, and provenance controls\n\nKeep this page focused on dependency inputs, generated lockfiles, and dependency-specific validation.\n\n## Validation Expectations\n\nAt minimum, run the checks for the subsystem whose release-sensitive files changed.\n\nCommon examples:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nChoose the relevant subset based on the dependencies that changed.\n", "0.9": "+++\ntitle = \"Dependency Update Workflow\"\n+++\n\nUse this page for routine dependency updates and dependency-related release preparation. Use [Product Versioning](../product-versioning/) when changing the Sambee version, and [Release Checklist](../release-checklist/) when preparing a complete product release.\n\n## Dependency Update Rules\n\nRoutine install behavior and actual dependency changes are different workflows.\n\n- use `npm ci` for routine installs in `frontend/` and `companion/`\n- use the hashed backend lockfiles for routine Python installs\n- do not hand-edit generated lockfile details when the repository already provides a regeneration workflow\n\n### Backend Dependency Updates\n\nFor backend dependency changes:\n\n- update the reviewed top-level requirement files first\n- regenerate backend lockfiles with the supported refresh script\n- use `scripts/refresh-backend-lockfiles --check` for a read-only freshness check when needed\n- validate with backend tests and type checking\n\nThat keeps direct requirements, transitive dependencies, and hashes aligned.\n\nMore specifically:\n\n- change `requirements.txt` and `requirements-dev.txt`, not only the generated lockfiles\n- regenerate `requirements.lock.txt` and `requirements-dev.lock.txt` through `scripts/refresh-backend-lockfiles`\n- treat resolver conflicts as real compatibility constraints instead of forcing transitive pins by hand\n- avoid hand-editing lockfile hashes except as a last resort\n\nFor an already-open backend dependency-update PR:\n\n- review the direct requirement changes first\n- run `scripts/refresh-backend-lockfiles --check` if you want a quick stale-lockfile check before editing\n- regenerate the lockfiles from the reviewed sources\n- validate with at least `pytest -v` and `mypy app`\n- commit regenerated lockfiles back to the update branch instead of patching transitive entries manually\n\n### High-Risk Dependency Areas\n\nSome ecosystems are intentionally treated as coordinated manual changes rather than casual bumps.\n\n- high-risk frontend packages such as React, Vite, TypeScript, and MUI\n- companion Tauri package and crate alignment\n- backend packages with higher behavioral risk such as `smbprotocol` and `pyvips`\n\nAdditional contributor rules in those areas:\n\n- keep companion Tauri JavaScript packages and Rust crates on matching major.minor versions\n- validate companion Tauri alignment with `scripts/check_tauri_version_alignment.py` when those dependencies move\n- review Dependabot proposals for the shared Python runtime base as container-runtime changes\n- confirm Docker target validation reports the expected Python and SQLite versions before merging a Python runtime update\n- expect Debian packages to refresh during cache-busted image builds; do not hand-pin individual APT packages unless reproducibility requirements change\n- prefer committed scripts and lockfiles over one-off installers or floating `npx` downloads\n\n## Dependency Security Audits\n\nThe audit workflow and Dependabot configuration now live in the Developer Guide security section.\n\nUse [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/) for:\n\n- Dependabot grouping and ignore rules\n- scheduled dependency audit coverage\n\nUse [Container Image Security and Artifact Integrity](../../security/container-image-security-and-artifact-integrity/) for:\n\n- container-image vulnerability scanning\n- Trivy suppression policy\n- image signing, SBOM, and provenance controls\n\nKeep this page focused on dependency inputs, generated lockfiles, and dependency-specific validation.\n\n## Validation Expectations\n\nAt minimum, run the checks for the subsystem whose release-sensitive files changed.\n\nCommon examples:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nChoose the relevant subset based on the dependencies that changed.\n", "1.0": "+++\ntitle = \"Dependency Update Workflow\"\n+++\n\nUse this page for routine dependency updates and dependency-related release preparation. Use [Product Versioning](../product-versioning/) when changing the Sambee version, and [Release Checklist](../release-checklist/) when preparing a complete product release.\n\n## Dependency Update Rules\n\nRoutine install behavior and actual dependency changes are different workflows.\n\n- use `npm ci` for routine installs in `frontend/` and `companion/`\n- use the hashed backend lockfiles for routine Python installs\n- do not hand-edit generated lockfile details when the repository already provides a regeneration workflow\n- accept Dependabot updates to backend requirements and pip-compile lockfiles when CI validation passes\n\n### Backend Dependency Updates\n\nFor routine Dependabot backend dependency-update pull requests:\n\n- review the direct requirement and generated lockfile changes\n- do not rerun the backend lockfile refresh script only to satisfy CI\n- validate with backend tests and type checking\n\nCI verifies that direct source pins match both generated lockfiles. The backend\ntest image and production Docker image validate hash-enforced installations.\n\nFor manual backend dependency changes or an intentional full transitive refresh:\n\n- update `requirements.txt` and `requirements-dev.txt` first\n- regenerate `requirements.lock.txt` and `requirements-dev.lock.txt` through `scripts/refresh-backend-lockfiles`\n- treat resolver conflicts as real compatibility constraints instead of forcing transitive pins by hand\n- avoid hand-editing lockfile hashes except as a last resort\n\nUse `scripts/refresh-backend-lockfiles --check` when you deliberately want to\ncompare the committed locks with a new clean dependency resolution. It is an\noptional maintenance check, not a required step for routine Dependabot pull\nrequests.\n\n### High-Risk Dependency Areas\n\nSome ecosystems are intentionally treated as coordinated manual changes rather than casual bumps.\n\n- high-risk frontend packages such as React, Vite, TypeScript, and MUI\n- companion Tauri package and crate alignment\n- backend packages with higher behavioral risk such as `smbprotocol` and `pyvips`\n\nAdditional contributor rules in those areas:\n\n- keep companion Tauri JavaScript packages and Rust crates on matching major.minor versions\n- validate companion Tauri alignment with `scripts/check_tauri_version_alignment.py` when those dependencies move\n- review Dependabot proposals for the shared Python runtime base as container-runtime changes\n- confirm Docker target validation reports the expected Python and SQLite versions before merging a Python runtime update\n- expect Debian packages to refresh during cache-busted image builds; do not hand-pin individual APT packages unless reproducibility requirements change\n- prefer committed scripts and lockfiles over one-off installers or floating `npx` downloads\n\n## Dependency Security Audits\n\nThe audit workflow and Dependabot configuration now live in the Developer Guide security section.\n\nUse [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/) for:\n\n- Dependabot grouping and ignore rules\n- scheduled dependency audit coverage\n\nUse [Container Image Security and Artifact Integrity](../../security/container-image-security-and-artifact-integrity/) for:\n\n- container-image vulnerability scanning\n- Trivy suppression policy\n- image signing, SBOM, and provenance controls\n\nKeep this page focused on dependency inputs, generated lockfiles, and dependency-specific validation.\n\n## Validation Expectations\n\nAt minimum, run the checks for the subsystem whose release-sensitive files changed.\n\nCommon examples:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nChoose the relevant subset based on the dependencies that changed.\n", "2.0": "+++\ntitle = \"Dependency Update Workflow\"\n+++\n\nUse this page for routine dependency updates and dependency-related release preparation. Use [Product Versioning](../product-versioning/) when changing the Sambee version, and [Release Checklist](../release-checklist/) when preparing a complete product release.\n\n## Dependency Update Rules\n\nRoutine install behavior and actual dependency changes are different workflows.\n\n- use `npm ci` for routine installs in `frontend/` and `companion/`\n- use the hashed backend lockfiles for routine Python installs\n- do not hand-edit generated lockfile details when the repository already provides a regeneration workflow\n- accept Dependabot updates to backend requirements and pip-compile lockfiles when CI validation passes\n\n### Frontend Install Freshness\n\n`./scripts/test` checks frontend dependency freshness before generating test\nfixtures or running backend tests. It stops if the install stamp is missing or\ndoesn't match the current `frontend/package.json` and\n`frontend/package-lock.json`. It doesn't install dependencies automatically or\nrequire network access for the check.\n\nTo restore the frontend environment, run this from the repository root:\n\n```bash\ncd frontend \u0026\u0026 npm ci\n```\n\nThe install lifecycle clears any previous stamp before setup and writes a SHA-256\nhash to `frontend/node_modules/.dependencies.sha256` only after the existing\npostinstall setup succeeds. The stamp is local to the installed environment and\nisn't committed. Existing installations need one successful `npm ci` to create\nit. Installations using `--ignore-scripts` won't create the stamp.\n\nTo check the environment separately, run:\n\n```bash\ncd frontend \u0026\u0026 npm run check:dependencies\n```\n\nThe hash covers both files in full, so metadata-only changes also require a fresh\ninstall. This check detects changed dependency inputs, not arbitrary damage to\ninstalled packages. If individual packages are missing despite a matching stamp,\nrun `npm ci` again.\n\n### Backend Dependency Updates\n\nFor routine Dependabot backend dependency-update pull requests:\n\n- review the direct requirement and generated lockfile changes\n- do not rerun the backend lockfile refresh script only to satisfy CI\n- validate with backend tests and type checking\n\nCI verifies that direct source pins match both generated lockfiles. The backend\ntest image and production Docker image validate hash-enforced installations.\n\nFor manual backend dependency changes or an intentional full transitive refresh:\n\n- update `requirements.txt` and `requirements-dev.txt` first\n- regenerate `requirements.lock.txt` and `requirements-dev.lock.txt` through `scripts/refresh-backend-lockfiles`\n- treat resolver conflicts as real compatibility constraints instead of forcing transitive pins by hand\n- avoid hand-editing lockfile hashes except as a last resort\n\nUse `scripts/refresh-backend-lockfiles --check` when you deliberately want to\ncompare the committed locks with a new clean dependency resolution. It is an\noptional maintenance check, not a required step for routine Dependabot pull\nrequests.\n\n### High-Risk Dependency Areas\n\nSome ecosystems are intentionally treated as coordinated manual changes rather than casual bumps.\n\n- high-risk frontend packages such as React, Vite, TypeScript, and MUI\n- companion Tauri package and crate alignment\n- backend packages with higher behavioral risk such as `smbprotocol` and `pyvips`\n\nAdditional contributor rules in those areas:\n\n- keep companion Tauri JavaScript packages and Rust crates on matching major.minor versions\n- validate companion Tauri alignment with `scripts/check_tauri_version_alignment.py` when those dependencies move\n- review Dependabot proposals for the shared Python runtime base as container-runtime changes\n- confirm Docker target validation reports the expected Python and SQLite versions before merging a Python runtime update\n- expect Debian packages to refresh during cache-busted image builds; do not hand-pin individual APT packages unless reproducibility requirements change\n- prefer committed scripts and lockfiles over one-off installers or floating `npx` downloads\n\n## Dependency Security Audits\n\nThe audit workflow and Dependabot configuration now live in the Developer Guide security section.\n\nUse [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/) for:\n\n- Dependabot grouping and ignore rules\n- scheduled dependency audit coverage\n\nUse [Container Image Security and Artifact Integrity](../../security/container-image-security-and-artifact-integrity/) for:\n\n- container-image vulnerability scanning\n- Trivy suppression policy\n- image signing, SBOM, and provenance controls\n\nKeep this page focused on dependency inputs, generated lockfiles, and dependency-specific validation.\n\n## Validation Expectations\n\nAt minimum, run the checks for the subsystem whose release-sensitive files changed.\n\nCommon examples:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nChoose the relevant subset based on the dependencies that changed.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/release-and-versioning/product-versioning", "parent_id": "section:developer-guide/release-and-versioning", "depth": 2, "kind": "page", "label": "product-versioning", "title": "Product Versioning", "path": "developer-guide/release-and-versioning/product-versioning", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "branched", "source_version": "0.7", "diff_added": 13, "diff_removed": 18}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "inherited", "source_version": "0.9"}}, "content_versions": {"0.7": "+++\ntitle = \"Product Versioning\"\n+++\n\nThe Sambee product version has one source of truth. Use this page whenever you change the product version, whether for a prerelease or a stable release.\n\n## Product Version Source of Truth\n\nThe application version lives in:\n\n- `VERSION`\n\nWhen the product version changes:\n\n1. Update `VERSION`.\n1. Run `./scripts/sync-version`.\n1. Review all resulting metadata changes together.\n\nThe sync step updates version-bearing frontend and Companion files so they do not drift away from the root version.\n\n## Files That Move with Product Version Changes\n\nThe sync workflow updates files such as:\n\n- `frontend/package.json`\n- `frontend/package-lock.json`\n- `companion/package.json`\n- `companion/package-lock.json`\n- `companion/src-tauri/Cargo.toml`\n- `companion/src-tauri/tauri.conf.json`\n- `companion/src-tauri/Cargo.lock`\n\nTreat those edits as release metadata, not as noise to separate later.\n\n## Validation\n\nRun the version sync before validating the affected release surfaces. At minimum, review the generated metadata and run the checks required by the changed subsystem.\n\nCommon examples:\n\n```bash\n./scripts/sync-version\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nUse [Release Checklist](../release-checklist/) for the complete product-release sequence.\n\n", "0.8": "+++\ntitle = \"Product Versioning\"\n+++\n\nThe Sambee product version has one source of truth. Use this page whenever you change the product version, whether for a prerelease or a stable release.\n\n## Product Version Source of Truth\n\nThe application version lives in:\n\n- `VERSION`\n\nWhen the product version changes:\n\n1. Update `VERSION`.\n1. Run `./scripts/sync-version`.\n1. Review all resulting metadata changes together.\n\nThe sync step updates version-bearing frontend and Companion files so they do not drift away from the root version.\n\n## Files That Move with Product Version Changes\n\nThe sync workflow updates files such as:\n\n- `frontend/package.json`\n- `frontend/package-lock.json`\n- `companion/package.json`\n- `companion/package-lock.json`\n- `companion/src-tauri/Cargo.toml`\n- `companion/src-tauri/tauri.conf.json`\n- `companion/src-tauri/Cargo.lock`\n\nTreat those edits as release metadata, not as noise to separate later.\n\n## Validation\n\nRun the version sync before validating the affected release surfaces. At minimum, review the generated metadata and run the checks required by the changed subsystem.\n\nCommon examples:\n\n```bash\n./scripts/sync-version\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nUse [Release Checklist](../release-checklist/) for the complete product-release sequence.\n\n", "0.9": "+++\ntitle = \"Product Versioning\"\n+++\n\n## Product Version Source of Truth\n\nThe application version lives in:\n\n- `VERSION`\n\nWhen the product version changes:\n\n1. Update `VERSION`.\n1. Run `./scripts/sync-version`.\n\nThe sync step updates relevant frontend and Companion files.\n\n### Files That Move with Product Version Changes\n\nThe sync workflow updates files such as:\n\n- `frontend/package.json`\n- `frontend/package-lock.json`\n- `companion/package.json`\n- `companion/package-lock.json`\n- `companion/src-tauri/Cargo.toml`\n- `companion/src-tauri/tauri.conf.json`\n- `companion/src-tauri/Cargo.lock`\n\n## Publishable Build Policy\n\nSambee uses a `X.Y.Z` versionining scheme where the components have the following meanings:\n\n- `X` is the major version number.\n- `Y` is the minor version number:\n   - `0` for regular releases.\n   - `1` ... `n` for maintenance releases.\n- `Z` is the immutable publishable build sequence within `X.Y`:\n   - Each new `X.Y` branch starts at `Z == 0`.\n\nPublishable versions contain only non-negative numeric components. Prerelease suffixes and build metadata are not publishable because they do not support a single monotonic update path for Companion users.\n\n### Git Build Tags\n\nWhen a release workflow starts from `main`, it reserves the annotated Git tag `build-vX.Y.Z` for that exact source commit. Reusing an existing build selects that tag and checks out its immutable commit. Never move or recreate a `build-v...` tag.\n", "1.0": "+++\ntitle = \"Product Versioning\"\n+++\n\n## Product Version Source of Truth\n\nThe application version lives in:\n\n- `VERSION`\n\nWhen the product version changes:\n\n1. Update `VERSION`.\n1. Run `./scripts/sync-version`.\n\nThe sync step updates relevant frontend and Companion files.\n\n### Files That Move with Product Version Changes\n\nThe sync workflow updates files such as:\n\n- `frontend/package.json`\n- `frontend/package-lock.json`\n- `companion/package.json`\n- `companion/package-lock.json`\n- `companion/src-tauri/Cargo.toml`\n- `companion/src-tauri/tauri.conf.json`\n- `companion/src-tauri/Cargo.lock`\n\n## Publishable Build Policy\n\nSambee uses a `X.Y.Z` versionining scheme where the components have the following meanings:\n\n- `X` is the major version number.\n- `Y` is the minor version number:\n   - `0` for regular releases.\n   - `1` ... `n` for maintenance releases.\n- `Z` is the immutable publishable build sequence within `X.Y`:\n   - Each new `X.Y` branch starts at `Z == 0`.\n\nPublishable versions contain only non-negative numeric components. Prerelease suffixes and build metadata are not publishable because they do not support a single monotonic update path for Companion users.\n\n### Git Build Tags\n\nWhen a release workflow starts from `main`, it reserves the annotated Git tag `build-vX.Y.Z` for that exact source commit. Reusing an existing build selects that tag and checks out its immutable commit. Never move or recreate a `build-v...` tag.\n", "2.0": "+++\ntitle = \"Product Versioning\"\n+++\n\n## Product Version Source of Truth\n\nThe application version lives in:\n\n- `VERSION`\n\nWhen the product version changes:\n\n1. Update `VERSION`.\n1. Run `./scripts/sync-version`.\n\nThe sync step updates relevant frontend and Companion files.\n\n### Files That Move with Product Version Changes\n\nThe sync workflow updates files such as:\n\n- `frontend/package.json`\n- `frontend/package-lock.json`\n- `companion/package.json`\n- `companion/package-lock.json`\n- `companion/src-tauri/Cargo.toml`\n- `companion/src-tauri/tauri.conf.json`\n- `companion/src-tauri/Cargo.lock`\n\n## Publishable Build Policy\n\nSambee uses a `X.Y.Z` versionining scheme where the components have the following meanings:\n\n- `X` is the major version number.\n- `Y` is the minor version number:\n   - `0` for regular releases.\n   - `1` ... `n` for maintenance releases.\n- `Z` is the immutable publishable build sequence within `X.Y`:\n   - Each new `X.Y` branch starts at `Z == 0`.\n\nPublishable versions contain only non-negative numeric components. Prerelease suffixes and build metadata are not publishable because they do not support a single monotonic update path for Companion users.\n\n### Git Build Tags\n\nWhen a release workflow starts from `main`, it reserves the annotated Git tag `build-vX.Y.Z` for that exact source commit. Reusing an existing build selects that tag and checks out its immutable commit. Never move or recreate a `build-v...` tag.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Product Versioning\"\n+++\n\nThe Sambee product version has one source of truth. Use this page whenever you change the product version, whether for a prerelease or a stable release.\n\n## Product Version Source of Truth\n\nThe application version lives in:\n\n- `VERSION`\n\nWhen the product version changes:\n\n1. Update `VERSION`.\n1. Run `./scripts/sync-version`.\n1. Review all resulting metadata changes together.\n\nThe sync step updates version-bearing frontend and Companion files so they do not drift away from the root version.\n\n## Files That Move with Product Version Changes\n\nThe sync workflow updates files such as:\n\n- `frontend/package.json`\n- `frontend/package-lock.json`\n- `companion/package.json`\n- `companion/package-lock.json`\n- `companion/src-tauri/Cargo.toml`\n- `companion/src-tauri/tauri.conf.json`\n- `companion/src-tauri/Cargo.lock`\n\nTreat those edits as release metadata, not as noise to separate later.\n\n## Validation\n\nRun the version sync before validating the affected release surfaces. At minimum, review the generated metadata and run the checks required by the changed subsystem.\n\nCommon examples:\n\n```bash\n./scripts/sync-version\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nUse [Release Checklist](../release-checklist/) for the complete product-release sequence.\n\n", "0.8": "+++\ntitle = \"Product Versioning\"\n+++\n\nThe Sambee product version has one source of truth. Use this page whenever you change the product version, whether for a prerelease or a stable release.\n\n## Product Version Source of Truth\n\nThe application version lives in:\n\n- `VERSION`\n\nWhen the product version changes:\n\n1. Update `VERSION`.\n1. Run `./scripts/sync-version`.\n1. Review all resulting metadata changes together.\n\nThe sync step updates version-bearing frontend and Companion files so they do not drift away from the root version.\n\n## Files That Move with Product Version Changes\n\nThe sync workflow updates files such as:\n\n- `frontend/package.json`\n- `frontend/package-lock.json`\n- `companion/package.json`\n- `companion/package-lock.json`\n- `companion/src-tauri/Cargo.toml`\n- `companion/src-tauri/tauri.conf.json`\n- `companion/src-tauri/Cargo.lock`\n\nTreat those edits as release metadata, not as noise to separate later.\n\n## Validation\n\nRun the version sync before validating the affected release surfaces. At minimum, review the generated metadata and run the checks required by the changed subsystem.\n\nCommon examples:\n\n```bash\n./scripts/sync-version\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nUse [Release Checklist](../release-checklist/) for the complete product-release sequence.\n\n", "0.9": "+++\ntitle = \"Product Versioning\"\n+++\n\n## Product Version Source of Truth\n\nThe application version lives in:\n\n- `VERSION`\n\nWhen the product version changes:\n\n1. Update `VERSION`.\n1. Run `./scripts/sync-version`.\n\nThe sync step updates relevant frontend and Companion files.\n\n### Files That Move with Product Version Changes\n\nThe sync workflow updates files such as:\n\n- `frontend/package.json`\n- `frontend/package-lock.json`\n- `companion/package.json`\n- `companion/package-lock.json`\n- `companion/src-tauri/Cargo.toml`\n- `companion/src-tauri/tauri.conf.json`\n- `companion/src-tauri/Cargo.lock`\n\n## Publishable Build Policy\n\nSambee uses a `X.Y.Z` versionining scheme where the components have the following meanings:\n\n- `X` is the major version number.\n- `Y` is the minor version number:\n   - `0` for regular releases.\n   - `1` ... `n` for maintenance releases.\n- `Z` is the immutable publishable build sequence within `X.Y`:\n   - Each new `X.Y` branch starts at `Z == 0`.\n\nPublishable versions contain only non-negative numeric components. Prerelease suffixes and build metadata are not publishable because they do not support a single monotonic update path for Companion users.\n\n### Git Build Tags\n\nWhen a release workflow starts from `main`, it reserves the annotated Git tag `build-vX.Y.Z` for that exact source commit. Reusing an existing build selects that tag and checks out its immutable commit. Never move or recreate a `build-v...` tag.\n", "1.0": "+++\ntitle = \"Product Versioning\"\n+++\n\n## Product Version Source of Truth\n\nThe application version lives in:\n\n- `VERSION`\n\nWhen the product version changes:\n\n1. Update `VERSION`.\n1. Run `./scripts/sync-version`.\n\nThe sync step updates relevant frontend and Companion files.\n\n### Files That Move with Product Version Changes\n\nThe sync workflow updates files such as:\n\n- `frontend/package.json`\n- `frontend/package-lock.json`\n- `companion/package.json`\n- `companion/package-lock.json`\n- `companion/src-tauri/Cargo.toml`\n- `companion/src-tauri/tauri.conf.json`\n- `companion/src-tauri/Cargo.lock`\n\n## Publishable Build Policy\n\nSambee uses a `X.Y.Z` versionining scheme where the components have the following meanings:\n\n- `X` is the major version number.\n- `Y` is the minor version number:\n   - `0` for regular releases.\n   - `1` ... `n` for maintenance releases.\n- `Z` is the immutable publishable build sequence within `X.Y`:\n   - Each new `X.Y` branch starts at `Z == 0`.\n\nPublishable versions contain only non-negative numeric components. Prerelease suffixes and build metadata are not publishable because they do not support a single monotonic update path for Companion users.\n\n### Git Build Tags\n\nWhen a release workflow starts from `main`, it reserves the annotated Git tag `build-vX.Y.Z` for that exact source commit. Reusing an existing build selects that tag and checks out its immutable commit. Never move or recreate a `build-v...` tag.\n", "2.0": "+++\ntitle = \"Product Versioning\"\n+++\n\n## Product Version Source of Truth\n\nThe application version lives in:\n\n- `VERSION`\n\nWhen the product version changes:\n\n1. Update `VERSION`.\n1. Run `./scripts/sync-version`.\n\nThe sync step updates relevant frontend and Companion files.\n\n### Files That Move with Product Version Changes\n\nThe sync workflow updates files such as:\n\n- `frontend/package.json`\n- `frontend/package-lock.json`\n- `companion/package.json`\n- `companion/package-lock.json`\n- `companion/src-tauri/Cargo.toml`\n- `companion/src-tauri/tauri.conf.json`\n- `companion/src-tauri/Cargo.lock`\n\n## Publishable Build Policy\n\nSambee uses a `X.Y.Z` versionining scheme where the components have the following meanings:\n\n- `X` is the major version number.\n- `Y` is the minor version number:\n   - `0` for regular releases.\n   - `1` ... `n` for maintenance releases.\n- `Z` is the immutable publishable build sequence within `X.Y`:\n   - Each new `X.Y` branch starts at `Z == 0`.\n\nPublishable versions contain only non-negative numeric components. Prerelease suffixes and build metadata are not publishable because they do not support a single monotonic update path for Companion users.\n\n### Git Build Tags\n\nWhen a release workflow starts from `main`, it reserves the annotated Git tag `build-vX.Y.Z` for that exact source commit. Reusing an existing build selects that tag and checks out its immutable commit. Never move or recreate a `build-v...` tag.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/release-and-versioning/release-checklist", "parent_id": "section:developer-guide/release-and-versioning", "depth": 2, "kind": "page", "label": "release-checklist", "title": "Release Checklist", "path": "developer-guide/release-and-versioning/release-checklist", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "missing"}, "0.9": {"state": "missing"}, "1.0": {"state": "missing"}, "2.0": {"state": "missing"}}, "content_versions": {"0.7": "+++\ntitle = \"Release Checklist\"\n+++\n\n## Preparation\n\n1. Update the product **version** ([details](../product-versioning/)). Ensure it's at the version you want to release.\n\n## Build and Test the Docker Image\n\nSee [Overview](../docker-release-overview/).\n\n1. Run the CI workflow [Release: Create Docker Image](../build-docker-image/) to **build** the Docker image and move the `test` tag to it.\n   - Don't override the product version in the CI workflow.\n1. **Test** the newly built image (pull it via the `test` tag).\n\n## Documentation\n\n1. Review the **homepage** content and update it where necessary.\n1. **Docs:**\n   - Verify [Supported File Formats](../../../user-guide/reference/supported-file-formats/) and update as necessary.\n   - Finalize the target release's [What's New](/release-info/news-and-changes/whats-new/) page.\n   - Mark the target version as current in `website/data/docs-versions.toml`.\n   - Run the VS Code task **Website: Refresh Docs Derived Artifacts**.\n   - Review the Docs Structure Report this creates in `/workspace/website-meta/docs-reports/docs-structure-report.html`.\n1. Git merge all changes.\n\n## Publish the Docker Image\n\nSee [Overview](../docker-release-overview/).\n\n1. Create a Git tag on the commit the tested image was built from.\n1. Publish a GitHub release from that tag.\n   - Release publication triggers [Release: Publish Docker Image](../promote-docker-image/), which tags the image built earlier as `beta` (prereleases) or `stable` and adds version tags for stable releases.\n\n## Publish the Companion\n\nSee [Overview](../companion-release-overview/)\n\n1. Run [Release: Build Companion Artifact](../build-companion-release/) to build Companion for the target platforms.\n   - Publish the Companion GitHub Release created by the workflow.\n1. Run [Release: Promote Companion Release](../promote-companion-release/) to promote the release to the `test`, `beta`, and/or `stable` update channels and to update the Sambee download-metadata feed.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Release Checklist\"\n+++\n\n## Preparation\n\n1. Update the product **version** ([details](../product-versioning/)). Ensure it's at the version you want to release.\n\n## Build and Test the Docker Image\n\nSee [Overview](../docker-release-overview/).\n\n1. Run the CI workflow [Release: Create Docker Image](../build-docker-image/) to **build** the Docker image and move the `test` tag to it.\n   - Don't override the product version in the CI workflow.\n1. **Test** the newly built image (pull it via the `test` tag).\n\n## Documentation\n\n1. Review the **homepage** content and update it where necessary.\n1. **Docs:**\n   - Verify [Supported File Formats](../../../user-guide/reference/supported-file-formats/) and update as necessary.\n   - Finalize the target release's [What's New](/release-info/news-and-changes/whats-new/) page.\n   - Mark the target version as current in `website/data/docs-versions.toml`.\n   - Run the VS Code task **Website: Refresh Docs Derived Artifacts**.\n   - Review the Docs Structure Report this creates in `/workspace/website-meta/docs-reports/docs-structure-report.html`.\n1. Git merge all changes.\n\n## Publish the Docker Image\n\nSee [Overview](../docker-release-overview/).\n\n1. Create a Git tag on the commit the tested image was built from.\n1. Publish a GitHub release from that tag.\n   - Release publication triggers [Release: Publish Docker Image](../promote-docker-image/), which tags the image built earlier as `beta` (prereleases) or `stable` and adds version tags for stable releases.\n\n## Publish the Companion\n\nSee [Overview](../companion-release-overview/)\n\n1. Run [Release: Build Companion Artifact](../build-companion-release/) to build Companion for the target platforms.\n   - Publish the Companion GitHub Release created by the workflow.\n1. Run [Release: Promote Companion Release](../promote-companion-release/) to promote the release to the `test`, `beta`, and/or `stable` update channels and to update the Sambee download-metadata feed.\n"}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/release-and-versioning/docker-release-overview", "parent_id": "section:developer-guide/release-and-versioning", "depth": 2, "kind": "page", "label": "docker-release-overview", "title": "Docker Release Overview", "path": "developer-guide/release-and-versioning/docker-release-overview", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "branched", "source_version": "0.7", "diff_added": 30, "diff_removed": 45}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "inherited", "source_version": "0.9"}}, "content_versions": {"0.7": "+++\ntitle = \"Docker Release Overview\"\n+++\n\nSambee ships one production container image built from the repository-root Dockerfile.\n\nThe release flow builds a candidate once, validates it, and later promotes that same digest to `stable` or `beta`.\n\nUse this page as the entry point for the Docker release path.\n\n## Summary\n\nIf you want to publish a new Docker image:\n\n1. Update `VERSION` and run `./scripts/sync-version`.\n   - Git merge the reviewed `version-sync` changes.\n1. Run `Release: Create Docker Image` for the commit you want to ship.\n   - This creates a new Docker image in GHCR and moves the `test` tag to it.\n1. Test and validate the new image.\n1. Create and push the real release Git tag on that same commit.\n   - Use:\n      - `git tag -a vX.Y.Z-beta.N \u003ccommit\u003e -m \"Sambee X.Y.Z beta N\"` for prereleases\n      - `git tag -a vX.Y.Z \u003ccommit\u003e -m \"Sambee X.Y.Z\"` for stable releases\n   - Push the tag with `git push origin \u003ctag\u003e`.\n1. Publish a GitHub Release from that existing tag.\n1. Release publication triggers `Release: Publish Docker Image`, which tags the image built earlier as `beta` (prereleases) or `stable` and adds version tags for stable releases.\n   - Stable publication also moves `beta` forward unless `beta` already points to a higher semver release.\n\nRead the detailed pages in this order:\n\n1. [Build Docker Image](../build-docker-image/)\n2. [Promote Docker Image](../promote-docker-image/)\n3. [Docker Backfill And Cleanup](../docker-backfill-and-cleanup/)\n\n## Workflow Map\n\n| Workflow | When to use it | Result |\n|---|---|---|\n| `CI: Validate Docker Image` | Any pull request, push to `main`, or manual smoke-test run. | Proves the production image still builds and starts, but does not publish anything. |\n| `Release: Create Docker Image` | You want a real candidate image for a specific commit or tag. | Builds, validates, publishes the metadata bundle, marks that digest as the current `test` image, and signs the digest. |\n| `Release: Publish Docker Image` | A Git tag was pushed and the matching GitHub Release was published from an approved candidate commit. | Verifies the existing preview-built digest, then attaches release tags, moves `stable` or `beta`, and catches `beta` up during stable publication unless `beta` already points to a higher semver release. |\n| `Maintenance: Backfill Docker Release Tags` | You need to restore or attach release tags for an already approved GitHub Release. | Reapplies release tags and channel aliases to an existing digest without publishing a new runtime image. |\n| `Maintenance: Clean Up Docker Package Versions` | Preview history and unreferenced GHCR artifacts need cleanup. | Deletes unprotected SHA-tagged preview GHCR versions, prunes stale signature artifacts, and removes unreferenced untagged package versions while preserving release-tagged artifacts and protected aliases including `test`. |\n\n## Channels And Tags\n\nSambee publishes three moving channel tags:\n\n- `stable` for the current non-prerelease line.\n- `beta` for the current prerelease line, or for the newest stable line when `beta` is not already ahead on a higher semver prerelease path.\n- `test` for the newest manually published preview candidate.\n\nEach preview publish also creates an immutable lookup tag in the `sha-\u003cfull-commit-sha\u003e` form.\n\nDuring publication, the workflow pushes native platform manifests by digest before it assembles the final multi-platform index.\nThose digest-only platform pushes are implementation details of the publish workflow and are not user-facing tags.\n\nRelease workflows resolve that immutable candidate tag first and then attach the appropriate release tags to the same digest.\n\n`latest` is intentionally not published.\n\n## Published Artifact\n\nThe published container artifact is a multi-platform image index in GitHub Container Registry for:\n\n- `linux/amd64`.\n- `linux/arm64`.\n\nThe repository name is `ghcr.io/\u003cowner\u003e/sambee`.\n\nEach platform variant comes from the same Dockerfile, is built and validated on a native runner, and is assembled into the same candidate index digest.\n\nCosign signatures for that image digest are stored in a dedicated GHCR signature repository rather than in the main image repository.\nCosign manages its own digest-derived signature artifact layout in that repository, so GHCR may show both tagged signature entries and referenced untagged bundle manifests for a retained image digest.\n\nSBOM and provenance data for that digest are extracted per platform on native runners, assembled into one metadata bundle, and published in the dedicated `ghcr.io/\u003cowner\u003e/sambee-signatures` repository under a digest-derived `.meta` tag.\n\nRelease and backfill workflows also upload the exact bundle files to the GitHub Release as convenience assets. The GHCR `.meta` artifact remains the canonical metadata bundle.\n\n## Security Model\n\nPreview publication is the only workflow that builds and pushes a new image.\n\nThat preview build also forces a fresh rebuild of the Dockerfile layer that installs Debian packages for the workflow run, so release candidates pick up the latest Debian package fixes available at build time instead of relying only on a previously cached OS-package layer.\n\nIt also:\n\n- publishes an SBOM and provenance metadata bundle under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n- signs the digest with Cosign using GitHub Actions OIDC.\n\nRelease promotion does not rebuild the image. It verifies candidate image metadata and the published metadata bundle first, then promotes the existing digest.\n\nUse [Build Docker Image](../build-docker-image/) for the build-and-publish flow.\n\nUse [Promote Docker Image](../promote-docker-image/) for the release path.\n\nUse [Docker Backfill And Cleanup](../docker-backfill-and-cleanup/) for recovery, backfill, and cleanup.\n\nUse [Container Image Security and Artifact Integrity](../../security/container-image-security-and-artifact-integrity/) for the deeper signing, SBOM, provenance, and vulnerability-scanning details.\n\nUse [Deploy Sambee with Docker](../../../admin-guide/installation-and-deployment/deploy-sambee-with-docker/) for operator-facing deployment guidance.\n", "0.8": "+++\ntitle = \"Docker Release Overview\"\n+++\n\nSambee ships one production container image built from the repository-root Dockerfile.\n\nThe release flow builds a candidate once, validates it, and later promotes that same digest to `stable` or `beta`.\n\nUse this page as the entry point for the Docker release path.\n\n## Summary\n\nIf you want to publish a new Docker image:\n\n1. Update `VERSION` and run `./scripts/sync-version`.\n   - Git merge the reviewed `version-sync` changes.\n1. Run `Release: Create Docker Image` for the commit you want to ship.\n   - This creates a new Docker image in GHCR and moves the `test` tag to it.\n1. Test and validate the new image.\n1. Create and push the real release Git tag on that same commit.\n   - Use:\n      - `git tag -a vX.Y.Z-beta.N \u003ccommit\u003e -m \"Sambee X.Y.Z beta N\"` for prereleases\n      - `git tag -a vX.Y.Z \u003ccommit\u003e -m \"Sambee X.Y.Z\"` for stable releases\n   - Push the tag with `git push origin \u003ctag\u003e`.\n1. Publish a GitHub Release from that existing tag.\n1. Release publication triggers `Release: Publish Docker Image`, which tags the image built earlier as `beta` (prereleases) or `stable` and adds version tags for stable releases.\n   - Stable publication also moves `beta` forward unless `beta` already points to a higher semver release.\n\nRead the detailed pages in this order:\n\n1. [Build Docker Image](../build-docker-image/)\n2. [Promote Docker Image](../promote-docker-image/)\n3. [Docker Backfill And Cleanup](../docker-backfill-and-cleanup/)\n\n## Workflow Map\n\n| Workflow | When to use it | Result |\n|---|---|---|\n| `CI: Validate Docker Image` | Any pull request, push to `main`, or manual smoke-test run. | Proves the production image still builds and starts, but does not publish anything. |\n| `Release: Create Docker Image` | You want a real candidate image for a specific commit or tag. | Builds, validates, publishes the metadata bundle, marks that digest as the current `test` image, and signs the digest. |\n| `Release: Publish Docker Image` | A Git tag was pushed and the matching GitHub Release was published from an approved candidate commit. | Verifies the existing preview-built digest, then attaches release tags, moves `stable` or `beta`, and catches `beta` up during stable publication unless `beta` already points to a higher semver release. |\n| `Maintenance: Backfill Docker Release Tags` | You need to restore or attach release tags for an already approved GitHub Release. | Reapplies release tags and channel aliases to an existing digest without publishing a new runtime image. |\n| `Maintenance: Clean Up Docker Package Versions` | Preview history and unreferenced GHCR artifacts need cleanup. | Deletes unprotected SHA-tagged preview GHCR versions, prunes stale signature artifacts, and removes unreferenced untagged package versions while preserving release-tagged artifacts and protected aliases including `test`. |\n\n## Channels And Tags\n\nSambee publishes three moving channel tags:\n\n- `stable` for the current non-prerelease line.\n- `beta` for the current prerelease line, or for the newest stable line when `beta` is not already ahead on a higher semver prerelease path.\n- `test` for the newest manually published preview candidate.\n\nEach preview publish also creates an immutable lookup tag in the `sha-\u003cfull-commit-sha\u003e` form.\n\nDuring publication, the workflow pushes native platform manifests by digest before it assembles the final multi-platform index.\nThose digest-only platform pushes are implementation details of the publish workflow and are not user-facing tags.\n\nRelease workflows resolve that immutable candidate tag first and then attach the appropriate release tags to the same digest.\n\n`latest` is intentionally not published.\n\n## Published Artifact\n\nThe published container artifact is a multi-platform image index in GitHub Container Registry for:\n\n- `linux/amd64`.\n- `linux/arm64`.\n\nThe repository name is `ghcr.io/\u003cowner\u003e/sambee`.\n\nEach platform variant comes from the same Dockerfile, is built and validated on a native runner, and is assembled into the same candidate index digest.\n\nCosign signatures for that image digest are stored in a dedicated GHCR signature repository rather than in the main image repository.\nCosign manages its own digest-derived signature artifact layout in that repository, so GHCR may show both tagged signature entries and referenced untagged bundle manifests for a retained image digest.\n\nSBOM and provenance data for that digest are extracted per platform on native runners, assembled into one metadata bundle, and published in the dedicated `ghcr.io/\u003cowner\u003e/sambee-signatures` repository under a digest-derived `.meta` tag.\n\nRelease and backfill workflows also upload the exact bundle files to the GitHub Release as convenience assets. The GHCR `.meta` artifact remains the canonical metadata bundle.\n\n## Security Model\n\nPreview publication is the only workflow that builds and pushes a new image.\n\nThat preview build also forces a fresh rebuild of the Dockerfile layer that installs Debian packages for the workflow run, so release candidates pick up the latest Debian package fixes available at build time instead of relying only on a previously cached OS-package layer.\n\nIt also:\n\n- publishes an SBOM and provenance metadata bundle under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n- signs the digest with Cosign using GitHub Actions OIDC.\n\nRelease promotion does not rebuild the image. It verifies candidate image metadata and the published metadata bundle first, then promotes the existing digest.\n\nUse [Build Docker Image](../build-docker-image/) for the build-and-publish flow.\n\nUse [Promote Docker Image](../promote-docker-image/) for the release path.\n\nUse [Docker Backfill And Cleanup](../docker-backfill-and-cleanup/) for recovery, backfill, and cleanup.\n\nUse [Container Image Security and Artifact Integrity](../../security/container-image-security-and-artifact-integrity/) for the deeper signing, SBOM, provenance, and vulnerability-scanning details.\n\nUse [Deploy Sambee with Docker](../../../admin-guide/installation-and-deployment/deploy-sambee-with-docker/) for operator-facing deployment guidance.\n", "0.9": "+++\ntitle = \"Docker Release Overview\"\n+++\n\nSambee ships one production container image built from the repository-root Dockerfile.\n\nThe release flow builds a candidate image once, validates it, and later promotes that same image to `stable` or `beta`.\n\n## Summary\n\nIf you want to publish a new Docker image:\n\n1. Increment `VERSION` to the next `X.Y.Z` value and run `./scripts/sync-version`.\n1. Run `Release: Create Docker Image`.\n   - If the workflow's source version field is left blank, the image is built from the current commit in `main` and the Git tag `build-vX.Y.Z` is created to reserve the version for the commit the image is built from.\n   - If a source version field is specified, the workflow verifies and repairs the image associated with the version via the Git tag used for reservation.\n1. The workflow:\n   - assures concurrency via unique `stage-\u003crun\u003e-\u003cattempt\u003e-\u003cplatform\u003e` Docker tags in the internal staging repository\n   - builds the image\n   - validates and signs the image\n   - creates immutable `build-vX.Y.Z` Git commit and Docker image tags\n   - moves the `test` Docker tag to the newly built image\n1. Test the new image via the `test` Docker image tag.\n1. To move the `beta` Docker tag to the newly built image, run `Release: Publish Docker Image` manually.\n1. To publish the newly built image as `stable`, run `Release: Create Public Sambee Release` publish the resulting GitHub release.\n   - Release publication verifies the existing signed candidate and moves only the authorized mutable aliases. It never rebuilds an image.\n\nRead the detailed pages in this order:\n\n1. [Build Docker Image](../build-docker-image/)\n2. [Promote Docker Image](../promote-docker-image/)\n3. [Docker Backfill And Cleanup](../docker-backfill-and-cleanup/)\n\n## Workflow Map\n\n| Workflow | When to use it | Result |\n|---|---|---|\n| `CI: Validate Docker Image` | Any pull request, push to `main`, or manual smoke-test run. | Proves the production image still builds and starts, but does not publish anything. |\n| `Release: Create Docker Image` | To create an image for the current `main` commit or to verify/repair an image for an commit identified by its version tag. | Builds, validates, publishes the metadata bundle, marks that image as the current `test` image, and signs it. |\n| `Release: Publish Docker Image` | Run manually: to promote an image to `beta`.\u003cbr /\u003eIs run automatically when publishing a GitHub Release to promote an image to `stable`. | Verifies the existing preview-built image. Manual beta promotion moves only `beta`; public-release promotion moves `stable`, the minor-series tag, and catches `beta` up unless it already points to a higher version. |\n| `Maintenance: Backfill Docker Release Tags` | You need to restore or attach release tags for an already approved GitHub Release. | Reapplies release tags and channel aliases to an existing image without publishing a new runtime image. |\n| `Maintenance: Clean Up Docker Package Versions` | Clean up Docker image tag history and remove unreferenced GHCR artifacts. | Deletes unprotected SHA-tagged preview GHCR versions, prunes stale signature artifacts, and removes unreferenced untagged package versions while preserving release-tagged artifacts and protected aliases including `test`. |\n\n## Channels And Tags\n\nSambee publishes three moving channel tags:\n\n- `stable` for the approved production image.\n- `beta` for the approved preview image.\n- `test` for the most recently verified candidate image.\n\nEach candidate creates immutable tags:\n- Git: `build-vX.Y.Z`\n- Docker: `build-vX.Y.Z`, `X.Y.Z`, and `sha-\u003cfull-commit-sha\u003e`\n\nDuring publication, the workflow pushes native platform manifests by digest and assembles a multi-platform index in `ghcr.io/\u003cowner\u003e/sambee-staging`. It verifies metadata and signatures there, then copies the verified index by digest to the final immutable marker in `ghcr.io/\u003cowner\u003e/sambee`. Staging references are implementation details and are not user-facing tags.\n\nRelease workflows identify the target image by resolving the immutable Docker tag and attaching the appropriate release tags to the same image.\n\n`latest` is intentionally not published.\n\n## Published Artifact\n\nThe published container artifact is a multi-platform image index in GitHub Container Registry (GHCR) for:\n\n- `linux/amd64`.\n- `linux/arm64`.\n\nThe repository name is `ghcr.io/\u003cowner\u003e/sambee`.\n\nEach platform variant comes from the same Dockerfile, is built and validated on a native runner, and is assembled into the same candidate index digest.\n\nCosign signatures for that image digest are stored in a dedicated GHCR signature repository rather than in the main image repository. Cosign manages its own digest-derived signature artifact layout in that repository, so GHCR may show both tagged signature entries and referenced untagged bundle manifests for a retained image digest.\n\nSBOM and provenance data for that digest are extracted per platform on native runners, assembled into one metadata bundle, and published in the dedicated `ghcr.io/\u003cowner\u003e/sambee-signatures` repository under a digest-derived `.meta` tag.\n\nRelease and backfill workflows also upload the exact bundle files to the GitHub Release as convenience assets. The GHCR `.meta` artifact remains the canonical metadata bundle.\n\n## Security Model\n\nA new Docker build forces a fresh rebuild of the Dockerfile layer that installs Debian packages for the workflow run, so release candidates pick up the latest Debian package fixes available at build time instead of relying only on a previously cached OS-package layer.\n\nIt also:\n\n- publishes an SBOM and provenance metadata bundle under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n- signs the digest with Cosign using GitHub Actions OIDC.\n", "1.0": "+++\ntitle = \"Docker Release Overview\"\n+++\n\nSambee ships one production container image built from the repository-root Dockerfile.\n\nThe release flow builds a candidate image once, validates it, and later promotes that same image to `stable` or `beta`.\n\n## Summary\n\nIf you want to publish a new Docker image:\n\n1. Increment `VERSION` to the next `X.Y.Z` value and run `./scripts/sync-version`.\n1. Run `Release: Create Docker Image`.\n   - If the workflow's source version field is left blank, the image is built from the current commit in `main` and the Git tag `build-vX.Y.Z` is created to reserve the version for the commit the image is built from.\n   - If a source version field is specified, the workflow verifies and repairs the image associated with the version via the Git tag used for reservation.\n1. The workflow:\n   - assures concurrency via unique `stage-\u003crun\u003e-\u003cattempt\u003e-\u003cplatform\u003e` Docker tags in the internal staging repository\n   - builds the image\n   - validates and signs the image\n   - creates immutable `build-vX.Y.Z` Git commit and Docker image tags\n   - moves the `test` Docker tag to the newly built image\n1. Test the new image via the `test` Docker image tag.\n1. To move the `beta` Docker tag to the newly built image, run `Release: Publish Docker Image` manually.\n1. To publish the newly built image as `stable`, run `Release: Create Public Sambee Release` publish the resulting GitHub release.\n   - Release publication verifies the existing signed candidate and moves only the authorized mutable aliases. It never rebuilds an image.\n\nRead the detailed pages in this order:\n\n1. [Build Docker Image](../build-docker-image/)\n2. [Promote Docker Image](../promote-docker-image/)\n3. [Docker Backfill And Cleanup](../docker-backfill-and-cleanup/)\n\n## Workflow Map\n\n| Workflow | When to use it | Result |\n|---|---|---|\n| `CI: Validate Docker Image` | Any pull request, push to `main`, or manual smoke-test run. | Proves the production image still builds and starts, but does not publish anything. |\n| `Release: Create Docker Image` | To create an image for the current `main` commit or to verify/repair an image for an commit identified by its version tag. | Builds, validates, publishes the metadata bundle, marks that image as the current `test` image, and signs it. |\n| `Release: Publish Docker Image` | Run manually: to promote an image to `beta`.\u003cbr /\u003eIs run automatically when publishing a GitHub Release to promote an image to `stable`. | Verifies the existing preview-built image. Manual beta promotion moves only `beta`; public-release promotion moves `stable`, the minor-series tag, and catches `beta` up unless it already points to a higher version. |\n| `Maintenance: Backfill Docker Release Tags` | You need to restore or attach release tags for an already approved GitHub Release. | Reapplies release tags and channel aliases to an existing image without publishing a new runtime image. |\n| `Maintenance: Clean Up Docker Package Versions` | Clean up Docker image tag history and remove unreferenced GHCR artifacts. | Deletes unprotected SHA-tagged preview GHCR versions, prunes stale signature artifacts, and removes unreferenced untagged package versions while preserving release-tagged artifacts and protected aliases including `test`. |\n\n## Channels And Tags\n\nSambee publishes three moving channel tags:\n\n- `stable` for the approved production image.\n- `beta` for the approved preview image.\n- `test` for the most recently verified candidate image.\n\nEach candidate creates immutable tags:\n- Git: `build-vX.Y.Z`\n- Docker: `build-vX.Y.Z`, `X.Y.Z`, and `sha-\u003cfull-commit-sha\u003e`\n\nDuring publication, the workflow pushes native platform manifests by digest and assembles a multi-platform index in `ghcr.io/\u003cowner\u003e/sambee-staging`. It verifies metadata and signatures there, then copies the verified index by digest to the final immutable marker in `ghcr.io/\u003cowner\u003e/sambee`. Staging references are implementation details and are not user-facing tags.\n\nRelease workflows identify the target image by resolving the immutable Docker tag and attaching the appropriate release tags to the same image.\n\n`latest` is intentionally not published.\n\n## Published Artifact\n\nThe published container artifact is a multi-platform image index in GitHub Container Registry (GHCR) for:\n\n- `linux/amd64`.\n- `linux/arm64`.\n\nThe repository name is `ghcr.io/\u003cowner\u003e/sambee`.\n\nEach platform variant comes from the same Dockerfile, is built and validated on a native runner, and is assembled into the same candidate index digest.\n\nCosign signatures for that image digest are stored in a dedicated GHCR signature repository rather than in the main image repository. Cosign manages its own digest-derived signature artifact layout in that repository, so GHCR may show both tagged signature entries and referenced untagged bundle manifests for a retained image digest.\n\nSBOM and provenance data for that digest are extracted per platform on native runners, assembled into one metadata bundle, and published in the dedicated `ghcr.io/\u003cowner\u003e/sambee-signatures` repository under a digest-derived `.meta` tag.\n\nRelease and backfill workflows also upload the exact bundle files to the GitHub Release as convenience assets. The GHCR `.meta` artifact remains the canonical metadata bundle.\n\n## Security Model\n\nA new Docker build forces a fresh rebuild of the Dockerfile layer that installs Debian packages for the workflow run, so release candidates pick up the latest Debian package fixes available at build time instead of relying only on a previously cached OS-package layer.\n\nIt also:\n\n- publishes an SBOM and provenance metadata bundle under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n- signs the digest with Cosign using GitHub Actions OIDC.\n", "2.0": "+++\ntitle = \"Docker Release Overview\"\n+++\n\nSambee ships one production container image built from the repository-root Dockerfile.\n\nThe release flow builds a candidate image once, validates it, and later promotes that same image to `stable` or `beta`.\n\n## Summary\n\nIf you want to publish a new Docker image:\n\n1. Increment `VERSION` to the next `X.Y.Z` value and run `./scripts/sync-version`.\n1. Run `Release: Create Docker Image`.\n   - If the workflow's source version field is left blank, the image is built from the current commit in `main` and the Git tag `build-vX.Y.Z` is created to reserve the version for the commit the image is built from.\n   - If a source version field is specified, the workflow verifies and repairs the image associated with the version via the Git tag used for reservation.\n1. The workflow:\n   - assures concurrency via unique `stage-\u003crun\u003e-\u003cattempt\u003e-\u003cplatform\u003e` Docker tags in the internal staging repository\n   - builds the image\n   - validates and signs the image\n   - creates immutable `build-vX.Y.Z` Git commit and Docker image tags\n   - moves the `test` Docker tag to the newly built image\n1. Test the new image via the `test` Docker image tag.\n1. To move the `beta` Docker tag to the newly built image, run `Release: Publish Docker Image` manually.\n1. To publish the newly built image as `stable`, run `Release: Create Public Sambee Release` publish the resulting GitHub release.\n   - Release publication verifies the existing signed candidate and moves only the authorized mutable aliases. It never rebuilds an image.\n\nRead the detailed pages in this order:\n\n1. [Build Docker Image](../build-docker-image/)\n2. [Promote Docker Image](../promote-docker-image/)\n3. [Docker Backfill And Cleanup](../docker-backfill-and-cleanup/)\n\n## Workflow Map\n\n| Workflow | When to use it | Result |\n|---|---|---|\n| `CI: Validate Docker Image` | Any pull request, push to `main`, or manual smoke-test run. | Proves the production image still builds and starts, but does not publish anything. |\n| `Release: Create Docker Image` | To create an image for the current `main` commit or to verify/repair an image for an commit identified by its version tag. | Builds, validates, publishes the metadata bundle, marks that image as the current `test` image, and signs it. |\n| `Release: Publish Docker Image` | Run manually: to promote an image to `beta`.\u003cbr /\u003eIs run automatically when publishing a GitHub Release to promote an image to `stable`. | Verifies the existing preview-built image. Manual beta promotion moves only `beta`; public-release promotion moves `stable`, the minor-series tag, and catches `beta` up unless it already points to a higher version. |\n| `Maintenance: Backfill Docker Release Tags` | You need to restore or attach release tags for an already approved GitHub Release. | Reapplies release tags and channel aliases to an existing image without publishing a new runtime image. |\n| `Maintenance: Clean Up Docker Package Versions` | Clean up Docker image tag history and remove unreferenced GHCR artifacts. | Deletes unprotected SHA-tagged preview GHCR versions, prunes stale signature artifacts, and removes unreferenced untagged package versions while preserving release-tagged artifacts and protected aliases including `test`. |\n\n## Channels And Tags\n\nSambee publishes three moving channel tags:\n\n- `stable` for the approved production image.\n- `beta` for the approved preview image.\n- `test` for the most recently verified candidate image.\n\nEach candidate creates immutable tags:\n- Git: `build-vX.Y.Z`\n- Docker: `build-vX.Y.Z`, `X.Y.Z`, and `sha-\u003cfull-commit-sha\u003e`\n\nDuring publication, the workflow pushes native platform manifests by digest and assembles a multi-platform index in `ghcr.io/\u003cowner\u003e/sambee-staging`. It verifies metadata and signatures there, then copies the verified index by digest to the final immutable marker in `ghcr.io/\u003cowner\u003e/sambee`. Staging references are implementation details and are not user-facing tags.\n\nRelease workflows identify the target image by resolving the immutable Docker tag and attaching the appropriate release tags to the same image.\n\n`latest` is intentionally not published.\n\n## Published Artifact\n\nThe published container artifact is a multi-platform image index in GitHub Container Registry (GHCR) for:\n\n- `linux/amd64`.\n- `linux/arm64`.\n\nThe repository name is `ghcr.io/\u003cowner\u003e/sambee`.\n\nEach platform variant comes from the same Dockerfile, is built and validated on a native runner, and is assembled into the same candidate index digest.\n\nCosign signatures for that image digest are stored in a dedicated GHCR signature repository rather than in the main image repository. Cosign manages its own digest-derived signature artifact layout in that repository, so GHCR may show both tagged signature entries and referenced untagged bundle manifests for a retained image digest.\n\nSBOM and provenance data for that digest are extracted per platform on native runners, assembled into one metadata bundle, and published in the dedicated `ghcr.io/\u003cowner\u003e/sambee-signatures` repository under a digest-derived `.meta` tag.\n\nRelease and backfill workflows also upload the exact bundle files to the GitHub Release as convenience assets. The GHCR `.meta` artifact remains the canonical metadata bundle.\n\n## Security Model\n\nA new Docker build forces a fresh rebuild of the Dockerfile layer that installs Debian packages for the workflow run, so release candidates pick up the latest Debian package fixes available at build time instead of relying only on a previously cached OS-package layer.\n\nIt also:\n\n- publishes an SBOM and provenance metadata bundle under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n- signs the digest with Cosign using GitHub Actions OIDC.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Docker Release Overview\"\n+++\n\nSambee ships one production container image built from the repository-root Dockerfile.\n\nThe release flow builds a candidate once, validates it, and later promotes that same digest to `stable` or `beta`.\n\nUse this page as the entry point for the Docker release path.\n\n## Summary\n\nIf you want to publish a new Docker image:\n\n1. Update `VERSION` and run `./scripts/sync-version`.\n   - Git merge the reviewed `version-sync` changes.\n1. Run `Release: Create Docker Image` for the commit you want to ship.\n   - This creates a new Docker image in GHCR and moves the `test` tag to it.\n1. Test and validate the new image.\n1. Create and push the real release Git tag on that same commit.\n   - Use:\n      - `git tag -a vX.Y.Z-beta.N \u003ccommit\u003e -m \"Sambee X.Y.Z beta N\"` for prereleases\n      - `git tag -a vX.Y.Z \u003ccommit\u003e -m \"Sambee X.Y.Z\"` for stable releases\n   - Push the tag with `git push origin \u003ctag\u003e`.\n1. Publish a GitHub Release from that existing tag.\n1. Release publication triggers `Release: Publish Docker Image`, which tags the image built earlier as `beta` (prereleases) or `stable` and adds version tags for stable releases.\n   - Stable publication also moves `beta` forward unless `beta` already points to a higher semver release.\n\nRead the detailed pages in this order:\n\n1. [Build Docker Image](../build-docker-image/)\n2. [Promote Docker Image](../promote-docker-image/)\n3. [Docker Backfill And Cleanup](../docker-backfill-and-cleanup/)\n\n## Workflow Map\n\n| Workflow | When to use it | Result |\n|---|---|---|\n| `CI: Validate Docker Image` | Any pull request, push to `main`, or manual smoke-test run. | Proves the production image still builds and starts, but does not publish anything. |\n| `Release: Create Docker Image` | You want a real candidate image for a specific commit or tag. | Builds, validates, publishes the metadata bundle, marks that digest as the current `test` image, and signs the digest. |\n| `Release: Publish Docker Image` | A Git tag was pushed and the matching GitHub Release was published from an approved candidate commit. | Verifies the existing preview-built digest, then attaches release tags, moves `stable` or `beta`, and catches `beta` up during stable publication unless `beta` already points to a higher semver release. |\n| `Maintenance: Backfill Docker Release Tags` | You need to restore or attach release tags for an already approved GitHub Release. | Reapplies release tags and channel aliases to an existing digest without publishing a new runtime image. |\n| `Maintenance: Clean Up Docker Package Versions` | Preview history and unreferenced GHCR artifacts need cleanup. | Deletes unprotected SHA-tagged preview GHCR versions, prunes stale signature artifacts, and removes unreferenced untagged package versions while preserving release-tagged artifacts and protected aliases including `test`. |\n\n## Channels And Tags\n\nSambee publishes three moving channel tags:\n\n- `stable` for the current non-prerelease line.\n- `beta` for the current prerelease line, or for the newest stable line when `beta` is not already ahead on a higher semver prerelease path.\n- `test` for the newest manually published preview candidate.\n\nEach preview publish also creates an immutable lookup tag in the `sha-\u003cfull-commit-sha\u003e` form.\n\nDuring publication, the workflow pushes native platform manifests by digest before it assembles the final multi-platform index.\nThose digest-only platform pushes are implementation details of the publish workflow and are not user-facing tags.\n\nRelease workflows resolve that immutable candidate tag first and then attach the appropriate release tags to the same digest.\n\n`latest` is intentionally not published.\n\n## Published Artifact\n\nThe published container artifact is a multi-platform image index in GitHub Container Registry for:\n\n- `linux/amd64`.\n- `linux/arm64`.\n\nThe repository name is `ghcr.io/\u003cowner\u003e/sambee`.\n\nEach platform variant comes from the same Dockerfile, is built and validated on a native runner, and is assembled into the same candidate index digest.\n\nCosign signatures for that image digest are stored in a dedicated GHCR signature repository rather than in the main image repository.\nCosign manages its own digest-derived signature artifact layout in that repository, so GHCR may show both tagged signature entries and referenced untagged bundle manifests for a retained image digest.\n\nSBOM and provenance data for that digest are extracted per platform on native runners, assembled into one metadata bundle, and published in the dedicated `ghcr.io/\u003cowner\u003e/sambee-signatures` repository under a digest-derived `.meta` tag.\n\nRelease and backfill workflows also upload the exact bundle files to the GitHub Release as convenience assets. The GHCR `.meta` artifact remains the canonical metadata bundle.\n\n## Security Model\n\nPreview publication is the only workflow that builds and pushes a new image.\n\nThat preview build also forces a fresh rebuild of the Dockerfile layer that installs Debian packages for the workflow run, so release candidates pick up the latest Debian package fixes available at build time instead of relying only on a previously cached OS-package layer.\n\nIt also:\n\n- publishes an SBOM and provenance metadata bundle under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n- signs the digest with Cosign using GitHub Actions OIDC.\n\nRelease promotion does not rebuild the image. It verifies candidate image metadata and the published metadata bundle first, then promotes the existing digest.\n\nUse [Build Docker Image](../build-docker-image/) for the build-and-publish flow.\n\nUse [Promote Docker Image](../promote-docker-image/) for the release path.\n\nUse [Docker Backfill And Cleanup](../docker-backfill-and-cleanup/) for recovery, backfill, and cleanup.\n\nUse [Container Image Security and Artifact Integrity](../../security/container-image-security-and-artifact-integrity/) for the deeper signing, SBOM, provenance, and vulnerability-scanning details.\n\nUse [Deploy Sambee with Docker](../../../admin-guide/installation-and-deployment/deploy-sambee-with-docker/) for operator-facing deployment guidance.\n", "0.8": "+++\ntitle = \"Docker Release Overview\"\n+++\n\nSambee ships one production container image built from the repository-root Dockerfile.\n\nThe release flow builds a candidate once, validates it, and later promotes that same digest to `stable` or `beta`.\n\nUse this page as the entry point for the Docker release path.\n\n## Summary\n\nIf you want to publish a new Docker image:\n\n1. Update `VERSION` and run `./scripts/sync-version`.\n   - Git merge the reviewed `version-sync` changes.\n1. Run `Release: Create Docker Image` for the commit you want to ship.\n   - This creates a new Docker image in GHCR and moves the `test` tag to it.\n1. Test and validate the new image.\n1. Create and push the real release Git tag on that same commit.\n   - Use:\n      - `git tag -a vX.Y.Z-beta.N \u003ccommit\u003e -m \"Sambee X.Y.Z beta N\"` for prereleases\n      - `git tag -a vX.Y.Z \u003ccommit\u003e -m \"Sambee X.Y.Z\"` for stable releases\n   - Push the tag with `git push origin \u003ctag\u003e`.\n1. Publish a GitHub Release from that existing tag.\n1. Release publication triggers `Release: Publish Docker Image`, which tags the image built earlier as `beta` (prereleases) or `stable` and adds version tags for stable releases.\n   - Stable publication also moves `beta` forward unless `beta` already points to a higher semver release.\n\nRead the detailed pages in this order:\n\n1. [Build Docker Image](../build-docker-image/)\n2. [Promote Docker Image](../promote-docker-image/)\n3. [Docker Backfill And Cleanup](../docker-backfill-and-cleanup/)\n\n## Workflow Map\n\n| Workflow | When to use it | Result |\n|---|---|---|\n| `CI: Validate Docker Image` | Any pull request, push to `main`, or manual smoke-test run. | Proves the production image still builds and starts, but does not publish anything. |\n| `Release: Create Docker Image` | You want a real candidate image for a specific commit or tag. | Builds, validates, publishes the metadata bundle, marks that digest as the current `test` image, and signs the digest. |\n| `Release: Publish Docker Image` | A Git tag was pushed and the matching GitHub Release was published from an approved candidate commit. | Verifies the existing preview-built digest, then attaches release tags, moves `stable` or `beta`, and catches `beta` up during stable publication unless `beta` already points to a higher semver release. |\n| `Maintenance: Backfill Docker Release Tags` | You need to restore or attach release tags for an already approved GitHub Release. | Reapplies release tags and channel aliases to an existing digest without publishing a new runtime image. |\n| `Maintenance: Clean Up Docker Package Versions` | Preview history and unreferenced GHCR artifacts need cleanup. | Deletes unprotected SHA-tagged preview GHCR versions, prunes stale signature artifacts, and removes unreferenced untagged package versions while preserving release-tagged artifacts and protected aliases including `test`. |\n\n## Channels And Tags\n\nSambee publishes three moving channel tags:\n\n- `stable` for the current non-prerelease line.\n- `beta` for the current prerelease line, or for the newest stable line when `beta` is not already ahead on a higher semver prerelease path.\n- `test` for the newest manually published preview candidate.\n\nEach preview publish also creates an immutable lookup tag in the `sha-\u003cfull-commit-sha\u003e` form.\n\nDuring publication, the workflow pushes native platform manifests by digest before it assembles the final multi-platform index.\nThose digest-only platform pushes are implementation details of the publish workflow and are not user-facing tags.\n\nRelease workflows resolve that immutable candidate tag first and then attach the appropriate release tags to the same digest.\n\n`latest` is intentionally not published.\n\n## Published Artifact\n\nThe published container artifact is a multi-platform image index in GitHub Container Registry for:\n\n- `linux/amd64`.\n- `linux/arm64`.\n\nThe repository name is `ghcr.io/\u003cowner\u003e/sambee`.\n\nEach platform variant comes from the same Dockerfile, is built and validated on a native runner, and is assembled into the same candidate index digest.\n\nCosign signatures for that image digest are stored in a dedicated GHCR signature repository rather than in the main image repository.\nCosign manages its own digest-derived signature artifact layout in that repository, so GHCR may show both tagged signature entries and referenced untagged bundle manifests for a retained image digest.\n\nSBOM and provenance data for that digest are extracted per platform on native runners, assembled into one metadata bundle, and published in the dedicated `ghcr.io/\u003cowner\u003e/sambee-signatures` repository under a digest-derived `.meta` tag.\n\nRelease and backfill workflows also upload the exact bundle files to the GitHub Release as convenience assets. The GHCR `.meta` artifact remains the canonical metadata bundle.\n\n## Security Model\n\nPreview publication is the only workflow that builds and pushes a new image.\n\nThat preview build also forces a fresh rebuild of the Dockerfile layer that installs Debian packages for the workflow run, so release candidates pick up the latest Debian package fixes available at build time instead of relying only on a previously cached OS-package layer.\n\nIt also:\n\n- publishes an SBOM and provenance metadata bundle under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n- signs the digest with Cosign using GitHub Actions OIDC.\n\nRelease promotion does not rebuild the image. It verifies candidate image metadata and the published metadata bundle first, then promotes the existing digest.\n\nUse [Build Docker Image](../build-docker-image/) for the build-and-publish flow.\n\nUse [Promote Docker Image](../promote-docker-image/) for the release path.\n\nUse [Docker Backfill And Cleanup](../docker-backfill-and-cleanup/) for recovery, backfill, and cleanup.\n\nUse [Container Image Security and Artifact Integrity](../../security/container-image-security-and-artifact-integrity/) for the deeper signing, SBOM, provenance, and vulnerability-scanning details.\n\nUse [Deploy Sambee with Docker](../../../admin-guide/installation-and-deployment/deploy-sambee-with-docker/) for operator-facing deployment guidance.\n", "0.9": "+++\ntitle = \"Docker Release Overview\"\n+++\n\nSambee ships one production container image built from the repository-root Dockerfile.\n\nThe release flow builds a candidate image once, validates it, and later promotes that same image to `stable` or `beta`.\n\n## Summary\n\nIf you want to publish a new Docker image:\n\n1. Increment `VERSION` to the next `X.Y.Z` value and run `./scripts/sync-version`.\n1. Run `Release: Create Docker Image`.\n   - If the workflow's source version field is left blank, the image is built from the current commit in `main` and the Git tag `build-vX.Y.Z` is created to reserve the version for the commit the image is built from.\n   - If a source version field is specified, the workflow verifies and repairs the image associated with the version via the Git tag used for reservation.\n1. The workflow:\n   - assures concurrency via unique `stage-\u003crun\u003e-\u003cattempt\u003e-\u003cplatform\u003e` Docker tags in the internal staging repository\n   - builds the image\n   - validates and signs the image\n   - creates immutable `build-vX.Y.Z` Git commit and Docker image tags\n   - moves the `test` Docker tag to the newly built image\n1. Test the new image via the `test` Docker image tag.\n1. To move the `beta` Docker tag to the newly built image, run `Release: Publish Docker Image` manually.\n1. To publish the newly built image as `stable`, run `Release: Create Public Sambee Release` publish the resulting GitHub release.\n   - Release publication verifies the existing signed candidate and moves only the authorized mutable aliases. It never rebuilds an image.\n\nRead the detailed pages in this order:\n\n1. [Build Docker Image](../build-docker-image/)\n2. [Promote Docker Image](../promote-docker-image/)\n3. [Docker Backfill And Cleanup](../docker-backfill-and-cleanup/)\n\n## Workflow Map\n\n| Workflow | When to use it | Result |\n|---|---|---|\n| `CI: Validate Docker Image` | Any pull request, push to `main`, or manual smoke-test run. | Proves the production image still builds and starts, but does not publish anything. |\n| `Release: Create Docker Image` | To create an image for the current `main` commit or to verify/repair an image for an commit identified by its version tag. | Builds, validates, publishes the metadata bundle, marks that image as the current `test` image, and signs it. |\n| `Release: Publish Docker Image` | Run manually: to promote an image to `beta`.\u003cbr /\u003eIs run automatically when publishing a GitHub Release to promote an image to `stable`. | Verifies the existing preview-built image. Manual beta promotion moves only `beta`; public-release promotion moves `stable`, the minor-series tag, and catches `beta` up unless it already points to a higher version. |\n| `Maintenance: Backfill Docker Release Tags` | You need to restore or attach release tags for an already approved GitHub Release. | Reapplies release tags and channel aliases to an existing image without publishing a new runtime image. |\n| `Maintenance: Clean Up Docker Package Versions` | Clean up Docker image tag history and remove unreferenced GHCR artifacts. | Deletes unprotected SHA-tagged preview GHCR versions, prunes stale signature artifacts, and removes unreferenced untagged package versions while preserving release-tagged artifacts and protected aliases including `test`. |\n\n## Channels And Tags\n\nSambee publishes three moving channel tags:\n\n- `stable` for the approved production image.\n- `beta` for the approved preview image.\n- `test` for the most recently verified candidate image.\n\nEach candidate creates immutable tags:\n- Git: `build-vX.Y.Z`\n- Docker: `build-vX.Y.Z`, `X.Y.Z`, and `sha-\u003cfull-commit-sha\u003e`\n\nDuring publication, the workflow pushes native platform manifests by digest and assembles a multi-platform index in `ghcr.io/\u003cowner\u003e/sambee-staging`. It verifies metadata and signatures there, then copies the verified index by digest to the final immutable marker in `ghcr.io/\u003cowner\u003e/sambee`. Staging references are implementation details and are not user-facing tags.\n\nRelease workflows identify the target image by resolving the immutable Docker tag and attaching the appropriate release tags to the same image.\n\n`latest` is intentionally not published.\n\n## Published Artifact\n\nThe published container artifact is a multi-platform image index in GitHub Container Registry (GHCR) for:\n\n- `linux/amd64`.\n- `linux/arm64`.\n\nThe repository name is `ghcr.io/\u003cowner\u003e/sambee`.\n\nEach platform variant comes from the same Dockerfile, is built and validated on a native runner, and is assembled into the same candidate index digest.\n\nCosign signatures for that image digest are stored in a dedicated GHCR signature repository rather than in the main image repository. Cosign manages its own digest-derived signature artifact layout in that repository, so GHCR may show both tagged signature entries and referenced untagged bundle manifests for a retained image digest.\n\nSBOM and provenance data for that digest are extracted per platform on native runners, assembled into one metadata bundle, and published in the dedicated `ghcr.io/\u003cowner\u003e/sambee-signatures` repository under a digest-derived `.meta` tag.\n\nRelease and backfill workflows also upload the exact bundle files to the GitHub Release as convenience assets. The GHCR `.meta` artifact remains the canonical metadata bundle.\n\n## Security Model\n\nA new Docker build forces a fresh rebuild of the Dockerfile layer that installs Debian packages for the workflow run, so release candidates pick up the latest Debian package fixes available at build time instead of relying only on a previously cached OS-package layer.\n\nIt also:\n\n- publishes an SBOM and provenance metadata bundle under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n- signs the digest with Cosign using GitHub Actions OIDC.\n", "1.0": "+++\ntitle = \"Docker Release Overview\"\n+++\n\nSambee ships one production container image built from the repository-root Dockerfile.\n\nThe release flow builds a candidate image once, validates it, and later promotes that same image to `stable` or `beta`.\n\n## Summary\n\nIf you want to publish a new Docker image:\n\n1. Increment `VERSION` to the next `X.Y.Z` value and run `./scripts/sync-version`.\n1. Run `Release: Create Docker Image`.\n   - If the workflow's source version field is left blank, the image is built from the current commit in `main` and the Git tag `build-vX.Y.Z` is created to reserve the version for the commit the image is built from.\n   - If a source version field is specified, the workflow verifies and repairs the image associated with the version via the Git tag used for reservation.\n1. The workflow:\n   - assures concurrency via unique `stage-\u003crun\u003e-\u003cattempt\u003e-\u003cplatform\u003e` Docker tags in the internal staging repository\n   - builds the image\n   - validates and signs the image\n   - creates immutable `build-vX.Y.Z` Git commit and Docker image tags\n   - moves the `test` Docker tag to the newly built image\n1. Test the new image via the `test` Docker image tag.\n1. To move the `beta` Docker tag to the newly built image, run `Release: Publish Docker Image` manually.\n1. To publish the newly built image as `stable`, run `Release: Create Public Sambee Release` publish the resulting GitHub release.\n   - Release publication verifies the existing signed candidate and moves only the authorized mutable aliases. It never rebuilds an image.\n\nRead the detailed pages in this order:\n\n1. [Build Docker Image](../build-docker-image/)\n2. [Promote Docker Image](../promote-docker-image/)\n3. [Docker Backfill And Cleanup](../docker-backfill-and-cleanup/)\n\n## Workflow Map\n\n| Workflow | When to use it | Result |\n|---|---|---|\n| `CI: Validate Docker Image` | Any pull request, push to `main`, or manual smoke-test run. | Proves the production image still builds and starts, but does not publish anything. |\n| `Release: Create Docker Image` | To create an image for the current `main` commit or to verify/repair an image for an commit identified by its version tag. | Builds, validates, publishes the metadata bundle, marks that image as the current `test` image, and signs it. |\n| `Release: Publish Docker Image` | Run manually: to promote an image to `beta`.\u003cbr /\u003eIs run automatically when publishing a GitHub Release to promote an image to `stable`. | Verifies the existing preview-built image. Manual beta promotion moves only `beta`; public-release promotion moves `stable`, the minor-series tag, and catches `beta` up unless it already points to a higher version. |\n| `Maintenance: Backfill Docker Release Tags` | You need to restore or attach release tags for an already approved GitHub Release. | Reapplies release tags and channel aliases to an existing image without publishing a new runtime image. |\n| `Maintenance: Clean Up Docker Package Versions` | Clean up Docker image tag history and remove unreferenced GHCR artifacts. | Deletes unprotected SHA-tagged preview GHCR versions, prunes stale signature artifacts, and removes unreferenced untagged package versions while preserving release-tagged artifacts and protected aliases including `test`. |\n\n## Channels And Tags\n\nSambee publishes three moving channel tags:\n\n- `stable` for the approved production image.\n- `beta` for the approved preview image.\n- `test` for the most recently verified candidate image.\n\nEach candidate creates immutable tags:\n- Git: `build-vX.Y.Z`\n- Docker: `build-vX.Y.Z`, `X.Y.Z`, and `sha-\u003cfull-commit-sha\u003e`\n\nDuring publication, the workflow pushes native platform manifests by digest and assembles a multi-platform index in `ghcr.io/\u003cowner\u003e/sambee-staging`. It verifies metadata and signatures there, then copies the verified index by digest to the final immutable marker in `ghcr.io/\u003cowner\u003e/sambee`. Staging references are implementation details and are not user-facing tags.\n\nRelease workflows identify the target image by resolving the immutable Docker tag and attaching the appropriate release tags to the same image.\n\n`latest` is intentionally not published.\n\n## Published Artifact\n\nThe published container artifact is a multi-platform image index in GitHub Container Registry (GHCR) for:\n\n- `linux/amd64`.\n- `linux/arm64`.\n\nThe repository name is `ghcr.io/\u003cowner\u003e/sambee`.\n\nEach platform variant comes from the same Dockerfile, is built and validated on a native runner, and is assembled into the same candidate index digest.\n\nCosign signatures for that image digest are stored in a dedicated GHCR signature repository rather than in the main image repository. Cosign manages its own digest-derived signature artifact layout in that repository, so GHCR may show both tagged signature entries and referenced untagged bundle manifests for a retained image digest.\n\nSBOM and provenance data for that digest are extracted per platform on native runners, assembled into one metadata bundle, and published in the dedicated `ghcr.io/\u003cowner\u003e/sambee-signatures` repository under a digest-derived `.meta` tag.\n\nRelease and backfill workflows also upload the exact bundle files to the GitHub Release as convenience assets. The GHCR `.meta` artifact remains the canonical metadata bundle.\n\n## Security Model\n\nA new Docker build forces a fresh rebuild of the Dockerfile layer that installs Debian packages for the workflow run, so release candidates pick up the latest Debian package fixes available at build time instead of relying only on a previously cached OS-package layer.\n\nIt also:\n\n- publishes an SBOM and provenance metadata bundle under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n- signs the digest with Cosign using GitHub Actions OIDC.\n", "2.0": "+++\ntitle = \"Docker Release Overview\"\n+++\n\nSambee ships one production container image built from the repository-root Dockerfile.\n\nThe release flow builds a candidate image once, validates it, and later promotes that same image to `stable` or `beta`.\n\n## Summary\n\nIf you want to publish a new Docker image:\n\n1. Increment `VERSION` to the next `X.Y.Z` value and run `./scripts/sync-version`.\n1. Run `Release: Create Docker Image`.\n   - If the workflow's source version field is left blank, the image is built from the current commit in `main` and the Git tag `build-vX.Y.Z` is created to reserve the version for the commit the image is built from.\n   - If a source version field is specified, the workflow verifies and repairs the image associated with the version via the Git tag used for reservation.\n1. The workflow:\n   - assures concurrency via unique `stage-\u003crun\u003e-\u003cattempt\u003e-\u003cplatform\u003e` Docker tags in the internal staging repository\n   - builds the image\n   - validates and signs the image\n   - creates immutable `build-vX.Y.Z` Git commit and Docker image tags\n   - moves the `test` Docker tag to the newly built image\n1. Test the new image via the `test` Docker image tag.\n1. To move the `beta` Docker tag to the newly built image, run `Release: Publish Docker Image` manually.\n1. To publish the newly built image as `stable`, run `Release: Create Public Sambee Release` publish the resulting GitHub release.\n   - Release publication verifies the existing signed candidate and moves only the authorized mutable aliases. It never rebuilds an image.\n\nRead the detailed pages in this order:\n\n1. [Build Docker Image](../build-docker-image/)\n2. [Promote Docker Image](../promote-docker-image/)\n3. [Docker Backfill And Cleanup](../docker-backfill-and-cleanup/)\n\n## Workflow Map\n\n| Workflow | When to use it | Result |\n|---|---|---|\n| `CI: Validate Docker Image` | Any pull request, push to `main`, or manual smoke-test run. | Proves the production image still builds and starts, but does not publish anything. |\n| `Release: Create Docker Image` | To create an image for the current `main` commit or to verify/repair an image for an commit identified by its version tag. | Builds, validates, publishes the metadata bundle, marks that image as the current `test` image, and signs it. |\n| `Release: Publish Docker Image` | Run manually: to promote an image to `beta`.\u003cbr /\u003eIs run automatically when publishing a GitHub Release to promote an image to `stable`. | Verifies the existing preview-built image. Manual beta promotion moves only `beta`; public-release promotion moves `stable`, the minor-series tag, and catches `beta` up unless it already points to a higher version. |\n| `Maintenance: Backfill Docker Release Tags` | You need to restore or attach release tags for an already approved GitHub Release. | Reapplies release tags and channel aliases to an existing image without publishing a new runtime image. |\n| `Maintenance: Clean Up Docker Package Versions` | Clean up Docker image tag history and remove unreferenced GHCR artifacts. | Deletes unprotected SHA-tagged preview GHCR versions, prunes stale signature artifacts, and removes unreferenced untagged package versions while preserving release-tagged artifacts and protected aliases including `test`. |\n\n## Channels And Tags\n\nSambee publishes three moving channel tags:\n\n- `stable` for the approved production image.\n- `beta` for the approved preview image.\n- `test` for the most recently verified candidate image.\n\nEach candidate creates immutable tags:\n- Git: `build-vX.Y.Z`\n- Docker: `build-vX.Y.Z`, `X.Y.Z`, and `sha-\u003cfull-commit-sha\u003e`\n\nDuring publication, the workflow pushes native platform manifests by digest and assembles a multi-platform index in `ghcr.io/\u003cowner\u003e/sambee-staging`. It verifies metadata and signatures there, then copies the verified index by digest to the final immutable marker in `ghcr.io/\u003cowner\u003e/sambee`. Staging references are implementation details and are not user-facing tags.\n\nRelease workflows identify the target image by resolving the immutable Docker tag and attaching the appropriate release tags to the same image.\n\n`latest` is intentionally not published.\n\n## Published Artifact\n\nThe published container artifact is a multi-platform image index in GitHub Container Registry (GHCR) for:\n\n- `linux/amd64`.\n- `linux/arm64`.\n\nThe repository name is `ghcr.io/\u003cowner\u003e/sambee`.\n\nEach platform variant comes from the same Dockerfile, is built and validated on a native runner, and is assembled into the same candidate index digest.\n\nCosign signatures for that image digest are stored in a dedicated GHCR signature repository rather than in the main image repository. Cosign manages its own digest-derived signature artifact layout in that repository, so GHCR may show both tagged signature entries and referenced untagged bundle manifests for a retained image digest.\n\nSBOM and provenance data for that digest are extracted per platform on native runners, assembled into one metadata bundle, and published in the dedicated `ghcr.io/\u003cowner\u003e/sambee-signatures` repository under a digest-derived `.meta` tag.\n\nRelease and backfill workflows also upload the exact bundle files to the GitHub Release as convenience assets. The GHCR `.meta` artifact remains the canonical metadata bundle.\n\n## Security Model\n\nA new Docker build forces a fresh rebuild of the Dockerfile layer that installs Debian packages for the workflow run, so release candidates pick up the latest Debian package fixes available at build time instead of relying only on a previously cached OS-package layer.\n\nIt also:\n\n- publishes an SBOM and provenance metadata bundle under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n- signs the digest with Cosign using GitHub Actions OIDC.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/release-and-versioning/build-docker-image", "parent_id": "section:developer-guide/release-and-versioning", "depth": 2, "kind": "page", "label": "build-docker-image", "title": "Build Docker Image", "path": "developer-guide/release-and-versioning/build-docker-image", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "branched", "source_version": "0.7", "diff_added": 23, "diff_removed": 28}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "branched", "source_version": "0.9", "diff_added": 3, "diff_removed": 1}}, "content_versions": {"0.7": "+++\ntitle = \"Build Docker Image\"\n+++\n\nThis is step 1 of the Docker release flow.\n\nUse this `Release: Create Docker Image` workflow to create a deployable Docker image from a specific commit. It is the only workflow that builds and pushes a new Sambee image to GitHub Container Registry.\n\nThis workflow does not create a Git tag, does not publish a GitHub Release, and does not move anything to `stable` or `beta`. It builds a candidate image, validates it, publishes it under an immutable `sha-\u003cfull-commit-sha\u003e` tag, and moves the `test` tag to that same digest.\n\n## Summary\n\nUse this order when you are preparing a release candidate (RC) Docker image:\n\n1. Merge the commit you may want to ship.\n1. Start `Release: Create Docker Image` from that exact commit.\n   - Leave `source_ref` empty unless you deliberately need another immutable ref.\n   - Leave `publish_version_override` empty unless this is a preview-only label.\n1. Wait for the workflow to publish a new Docker image in GHCR tagged `sha-\u003cfull-commit-sha\u003e` and `test`.\n\n## Inputs\n\nThe manual workflow accepts these inputs:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `source_ref` | Which code to build. Use a commit SHA or tag. | Leave empty to build from the latest commit of the branch you selected when starting the run. Set it only when you need to point the run at a different commit. |\n| `publish_version_override` | Which version label to bake into the image. This is **not** the image tag used by Docker Compose. If you leave it empty, the workflow uses the checked-in `VERSION` value. | Use it for preview-only labels such as `0.8.0-test.1`. Leave it empty for a normal release candidate. |\n\nIf `publish_version_override` is set, CI rewrites `VERSION` for that run only and reruns `./scripts/sync-version` before building.\n\nThat version value is written into the image metadata and the generated metadata bundle. It is not the main preview lookup tag. The candidate is still published under `sha-\u003cfull-commit-sha\u003e` and then exposed through the moving `test` tag.\n\n## Validation\n\nBefore it publishes anything, the workflow runs the following validation checks:\n\n- Backend type checks must pass.\n- Backend tests must pass.\n- Frontend type checks must pass.\n- Frontend tests must pass.\n- Each supported platform image must build, publish by digest, and start successfully.\n\nThe workflow forces a fresh rebuild of the Dockerfile layer that installs Debian packages for that run. That keeps preview candidates aligned with the latest package fixes available from the Debian repositories at build time while still letting the rest of the image reuse BuildKit cache.\n\n## Published Output\n\nAfter validation, the workflow:\n\n1. Builds and pushes native `linux/amd64` and `linux/arm64` platform manifests.\n2. Starts those same images and waits for the health endpoint to succeed.\n3. Scans those same images with Trivy.\n4. Assembles the platform manifests into one multi-platform candidate index.\n5. Publishes that candidate index under `sha-\u003cfull-commit-sha\u003e`.\n6. Extracts per-platform SBOM and provenance payloads on native runners, then assembles and publishes the metadata bundle under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n7. Moves the `test` tag onto that same digest after metadata bundle publication succeeds.\n8. Signs the digest with Cosign using GitHub Actions OIDC.\n\nThe digest is the real artifact identity. The `test` tag is only a moving alias.\n\nLater promotion may move `stable`, `beta`, or both channel aliases to that same digest, depending on the release type and the current `beta` version.\n\nThe workflow uses digest-only platform pushes while assembling the final candidate index. Treat those platform manifests as internal publish artifacts, not release candidates.\n\nCosign writes the signature artifact into a dedicated signature repository so the main `sambee` package page stays centered on deployable image versions.\nThat signature repository can still show both digest-derived signature tags and referenced untagged bundle manifests, which are part of Cosign's current storage model rather than extra preview image variants.\n\n## Security Scan Behavior\n\nThe preview workflow runs Trivy before publish.\n\nFor preview publishing, Trivy findings are advisory rather than blocking. That keeps the newest candidate available for testing while still surfacing risk clearly in the workflow output.\n\nThe preview scan runs against the same pushed platform digests that are later assembled into the published candidate index, so validation and publication use the same platform manifests.\n\nThose manifests use the same OS-package refresh policy, so the candidate that gets published is rebuilt against current Debian package metadata for that workflow run.\n\n## Metadata\n\nThe published image includes OCI labels for the source repository, source ref name, git revision, version, creation time, and license.\n\nThe workflow also generates `GIT_COMMIT` in CI before building because GitHub-hosted runners do not run the local git hooks that usually keep that file current. That keeps frontend and backend build metadata aligned inside the container image.\n", "0.8": "+++\ntitle = \"Build Docker Image\"\n+++\n\nThis is step 1 of the Docker release flow.\n\nUse this `Release: Create Docker Image` workflow to create a deployable Docker image from a specific commit. It is the only workflow that builds and pushes a new Sambee image to GitHub Container Registry.\n\nThis workflow does not create a Git tag, does not publish a GitHub Release, and does not move anything to `stable` or `beta`. It builds a candidate image, validates it, publishes it under an immutable `sha-\u003cfull-commit-sha\u003e` tag, and moves the `test` tag to that same digest.\n\n## Summary\n\nUse this order when you are preparing a release candidate (RC) Docker image:\n\n1. Merge the commit you may want to ship.\n1. Start `Release: Create Docker Image` from that exact commit.\n   - Leave `source_ref` empty unless you deliberately need another immutable ref.\n   - Leave `publish_version_override` empty unless this is a preview-only label.\n1. Wait for the workflow to publish a new Docker image in GHCR tagged `sha-\u003cfull-commit-sha\u003e` and `test`.\n\n## Inputs\n\nThe manual workflow accepts these inputs:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `source_ref` | Which code to build. Use a commit SHA or tag. | Leave empty to build from the latest commit of the branch you selected when starting the run. Set it only when you need to point the run at a different commit. |\n| `publish_version_override` | Which version label to bake into the image. This is **not** the image tag used by Docker Compose. If you leave it empty, the workflow uses the checked-in `VERSION` value. | Use it for preview-only labels such as `0.8.0-test.1`. Leave it empty for a normal release candidate. |\n\nIf `publish_version_override` is set, CI rewrites `VERSION` for that run only and reruns `./scripts/sync-version` before building.\n\nThat version value is written into the image metadata and the generated metadata bundle. It is not the main preview lookup tag. The candidate is still published under `sha-\u003cfull-commit-sha\u003e` and then exposed through the moving `test` tag.\n\n## Validation\n\nBefore it publishes anything, the workflow runs the following validation checks:\n\n- Backend type checks must pass.\n- Backend tests must pass.\n- Frontend type checks must pass.\n- Frontend tests must pass.\n- Each supported platform image must build, publish by digest, and start successfully.\n\nThe workflow forces a fresh rebuild of the Dockerfile layer that installs Debian packages for that run. That keeps preview candidates aligned with the latest package fixes available from the Debian repositories at build time while still letting the rest of the image reuse BuildKit cache.\n\n## Published Output\n\nAfter validation, the workflow:\n\n1. Builds and pushes native `linux/amd64` and `linux/arm64` platform manifests.\n2. Starts those same images and waits for the health endpoint to succeed.\n3. Scans those same images with Trivy.\n4. Assembles the platform manifests into one multi-platform candidate index.\n5. Publishes that candidate index under `sha-\u003cfull-commit-sha\u003e`.\n6. Extracts per-platform SBOM and provenance payloads on native runners, then assembles and publishes the metadata bundle under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n7. Moves the `test` tag onto that same digest after metadata bundle publication succeeds.\n8. Signs the digest with Cosign using GitHub Actions OIDC.\n\nThe digest is the real artifact identity. The `test` tag is only a moving alias.\n\nLater promotion may move `stable`, `beta`, or both channel aliases to that same digest, depending on the release type and the current `beta` version.\n\nThe workflow uses digest-only platform pushes while assembling the final candidate index. Treat those platform manifests as internal publish artifacts, not release candidates.\n\nCosign writes the signature artifact into a dedicated signature repository so the main `sambee` package page stays centered on deployable image versions.\nThat signature repository can still show both digest-derived signature tags and referenced untagged bundle manifests, which are part of Cosign's current storage model rather than extra preview image variants.\n\n## Security Scan Behavior\n\nThe preview workflow runs Trivy before publish.\n\nFor preview publishing, Trivy findings are advisory rather than blocking. That keeps the newest candidate available for testing while still surfacing risk clearly in the workflow output.\n\nThe preview scan runs against the same pushed platform digests that are later assembled into the published candidate index, so validation and publication use the same platform manifests.\n\nThose manifests use the same OS-package refresh policy, so the candidate that gets published is rebuilt against current Debian package metadata for that workflow run.\n\n## Metadata\n\nThe published image includes OCI labels for the source repository, source ref name, git revision, version, creation time, and license.\n\nThe workflow also generates `GIT_COMMIT` in CI before building because GitHub-hosted runners do not run the local git hooks that usually keep that file current. That keeps frontend and backend build metadata aligned inside the container image.\n", "0.9": "+++\ntitle = \"Build Docker Image\"\n+++\n\nThis is step 1 of the Docker release flow ([overview](../docker-release-overview/)).\n\nUse `Release: Create Docker Image` to build one immutable Docker candidate from `main`. It is the only workflow that builds and pushes a new Sambee image to GitHub Container Registry (GHCR).\n\nThe workflow reserves the annotated canonical Git tag `build-vX.Y.Z` for the committed, synchronized `VERSION` source. It does not publish a GitHub Release or move `stable` or `beta`.\n\n## Inputs\n\nThe workflow accepts only an optional existing candidate selector:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `build_version` | Reuse an existing immutable `X.Y.Z` candidate. | Leave empty for a new candidate. Use an existing value only to verify or repair its immutable aliases. |\n\nThe workflow rejects arbitrary source refs, source SHAs, and temporary version overrides. The checked-in, synchronized plain numeric `VERSION` is the only publishable version source.\n\n## Validation\n\nBefore it publishes anything, the workflow runs the following validation checks:\n\n- Backend type checks must pass.\n- Backend tests must pass.\n- Frontend type checks must pass.\n- Frontend tests must pass.\n- Each supported platform image must build, publish by digest, and start successfully.\n\nThe workflow forces a fresh rebuild of the Dockerfile layer that installs Debian packages for that run. That keeps preview candidates aligned with the latest package fixes available from the Debian repositories at build time while still letting the rest of the image reuse BuildKit cache.\n\n## Published Output\n\nAfter validation, the workflow:\n\n1. Builds and pushes native `linux/amd64` and `linux/arm64` platform manifests to the internal `ghcr.io/\u003cowner\u003e/sambee-staging` repository.\n2. Starts those same images and waits for the health endpoint to succeed.\n3. Scans those same images with Trivy.\n4. Assembles the platform manifests into one multi-platform staging index and verifies its image labels.\n5. Extracts per-platform SBOM and provenance payloads on native runners, then assembles and publishes a metadata bundle that names the final `sambee` image identity under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n6. Signs and verifies the staging digest with Cosign using GitHub Actions OIDC.\n7. Copies the verified multi-platform index by digest to the immutable `sambee:build-vX.Y.Z` marker, then verifies the final image, metadata bundle, and signature again.\n8. Creates immutable `X.Y.Z` and `sha-\u003cfull-commit-sha\u003e` aliases and moves `test` to that same verified image.\n\nThe digest is the real artifact identity. The canonical `build-vX.Y.Z` tag is the candidate source of truth; `test` is only a moving alias.\n\nLater promotion may move `stable`, `beta`, or both channel aliases to that same image, depending on the release type and the current `beta` version.\n\nThe workflow uses digest-only platform pushes and run-scoped `stage-\u003crun\u003e-\u003cattempt\u003e-*` tags in `sambee-staging`. Treat them as internal transport artifacts, not release candidates.\n\nCosign writes the signature artifact into a dedicated signature repository so the main `sambee` package page stays centered on deployable image versions.\nThat signature repository can still show both digest-derived signature tags and referenced untagged bundle manifests, which are part of Cosign's current storage model rather than extra preview image variants.\n\n## Retry Behavior\n\nBefore the late candidate marker is written, a failed run may be retried with the same `Z` version. The run uses a unique `stage-\u003crun\u003e-\u003cattempt\u003e-\u003cplatform\u003e` tag in `sambee-staging` and cleans up its staging versions after promotion or failure. That package can also contain untagged digest-only platform manifests. The Docker publication lock serializes candidate and maintenance cleanup, so the cleanup may delete the whole isolated package when every tagged version is a staging tag; GHCR requires that package-level operation when the last tagged version remains. Scheduled cleanup reclaims stale staging artifacts and unreferenced signature and metadata artifacts.\n\nAfter a valid candidate marker exists, a matching dispatch takes the repair-only path. It verifies the signed digest and restores only missing matching immutable aliases or the `test` pointer; it does not rebuild the image. A conflicting immutable marker requires incrementing `Z` and publishing a new candidate.\n\nGitHub Actions concurrency is mutual exclusion, not a FIFO queue: only one pending run is retained for the publication lock. Avoid stacking dispatches. A superseded pending dispatch is safe to submit again because it did not reach a publication step.\n\n## Security Scan Behavior\n\nThe preview workflow runs Trivy before publish.\n\nFor preview publishing, Trivy findings are advisory rather than blocking. That keeps the newest candidate available for testing while still surfacing risk clearly in the workflow output.\n\nThe preview scan runs against the same pushed platform digests that are later assembled into the published candidate index, so validation and publication use the same platform manifests.\n\nThose manifests use the same OS-package refresh policy, so the candidate that gets published is rebuilt against current Debian package metadata for that workflow run.\n\n## Metadata\n\nThe published image includes OCI labels for the source repository, source ref name, git revision, version, creation time, and license.\n\nThe workflow also generates `GIT_COMMIT` in CI before building because GitHub-hosted runners do not run the local git hooks that usually keep that file current. That keeps frontend and backend build metadata aligned inside the container image.\n", "1.0": "+++\ntitle = \"Build Docker Image\"\n+++\n\nThis is step 1 of the Docker release flow ([overview](../docker-release-overview/)).\n\nUse `Release: Create Docker Image` to build one immutable Docker candidate from `main`. It is the only workflow that builds and pushes a new Sambee image to GitHub Container Registry (GHCR).\n\nThe workflow reserves the annotated canonical Git tag `build-vX.Y.Z` for the committed, synchronized `VERSION` source. It does not publish a GitHub Release or move `stable` or `beta`.\n\n## Inputs\n\nThe workflow accepts only an optional existing candidate selector:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `build_version` | Reuse an existing immutable `X.Y.Z` candidate. | Leave empty for a new candidate. Use an existing value only to verify or repair its immutable aliases. |\n\nThe workflow rejects arbitrary source refs, source SHAs, and temporary version overrides. The checked-in, synchronized plain numeric `VERSION` is the only publishable version source.\n\n## Validation\n\nBefore it publishes anything, the workflow runs the following validation checks:\n\n- Backend type checks must pass.\n- Backend tests must pass.\n- Frontend type checks must pass.\n- Frontend tests must pass.\n- Each supported platform image must build, publish by digest, and start successfully.\n\nThe workflow forces a fresh rebuild of the Dockerfile layer that installs Debian packages for that run. That keeps preview candidates aligned with the latest package fixes available from the Debian repositories at build time while still letting the rest of the image reuse BuildKit cache.\n\n## Published Output\n\nAfter validation, the workflow:\n\n1. Builds and pushes native `linux/amd64` and `linux/arm64` platform manifests to the internal `ghcr.io/\u003cowner\u003e/sambee-staging` repository.\n2. Starts those same images and waits for the health endpoint to succeed.\n3. Scans those same images with Trivy.\n4. Assembles the platform manifests into one multi-platform staging index and verifies its image labels.\n5. Extracts per-platform SBOM and provenance payloads on native runners, then assembles and publishes a metadata bundle that names the final `sambee` image identity under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n6. Signs and verifies the staging digest with Cosign using GitHub Actions OIDC.\n7. Copies the verified multi-platform index by digest to the immutable `sambee:build-vX.Y.Z` marker, then verifies the final image, metadata bundle, and signature again.\n8. Creates immutable `X.Y.Z` and `sha-\u003cfull-commit-sha\u003e` aliases and moves `test` to that same verified image.\n\nThe digest is the real artifact identity. The canonical `build-vX.Y.Z` tag is the candidate source of truth; `test` is only a moving alias.\n\nLater promotion may move `stable`, `beta`, or both channel aliases to that same image, depending on the release type and the current `beta` version.\n\nThe workflow uses digest-only platform pushes and run-scoped `stage-\u003crun\u003e-\u003cattempt\u003e-*` tags in `sambee-staging`. Treat them as internal transport artifacts, not release candidates.\n\nCosign writes the signature artifact into a dedicated signature repository so the main `sambee` package page stays centered on deployable image versions.\nThat signature repository can still show both digest-derived signature tags and referenced untagged bundle manifests, which are part of Cosign's current storage model rather than extra preview image variants.\n\n## Retry Behavior\n\nBefore the late candidate marker is written, a failed run may be retried with the same `Z` version. The run uses a unique `stage-\u003crun\u003e-\u003cattempt\u003e-\u003cplatform\u003e` tag in `sambee-staging` and cleans up its staging versions after promotion or failure. That package can also contain untagged digest-only platform manifests. The Docker publication lock serializes candidate and maintenance cleanup, so the cleanup may delete the whole isolated package when every tagged version is a staging tag; GHCR requires that package-level operation when the last tagged version remains. Scheduled cleanup reclaims stale staging artifacts and unreferenced signature and metadata artifacts.\n\nAfter a valid candidate marker exists, a matching dispatch takes the repair-only path. It verifies the signed digest and restores only missing matching immutable aliases or the `test` pointer; it does not rebuild the image. A conflicting immutable marker requires incrementing `Z` and publishing a new candidate.\n\nGitHub Actions concurrency is mutual exclusion, not a FIFO queue: only one pending run is retained for the publication lock. Avoid stacking dispatches. A superseded pending dispatch is safe to submit again because it did not reach a publication step.\n\n## Security Scan Behavior\n\nThe preview workflow runs Trivy before publish.\n\nFor preview publishing, Trivy findings are advisory rather than blocking. That keeps the newest candidate available for testing while still surfacing risk clearly in the workflow output.\n\nThe preview scan runs against the same pushed platform digests that are later assembled into the published candidate index, so validation and publication use the same platform manifests.\n\nThose manifests use the same OS-package refresh policy, so the candidate that gets published is rebuilt against current Debian package metadata for that workflow run.\n\n## Metadata\n\nThe published image includes OCI labels for the source repository, source ref name, git revision, version, creation time, and license.\n\nThe workflow also generates `GIT_COMMIT` in CI before building because GitHub-hosted runners do not run the local git hooks that usually keep that file current. That keeps frontend and backend build metadata aligned inside the container image.\n", "2.0": "+++\ntitle = \"Build Docker Image\"\n+++\n\nThis is step 1 of the Docker release flow ([overview](../docker-release-overview/)).\n\nUse `Release: Create Docker Image` to build one immutable Docker candidate from `main`. It is the only workflow that builds and pushes a new Sambee image to GitHub Container Registry (GHCR).\n\nThe workflow reserves the annotated canonical Git tag `build-vX.Y.Z` for the committed, synchronized `VERSION` source. It does not publish a GitHub Release or move `stable` or `beta`.\n\n## Inputs\n\nThe workflow accepts only an optional existing candidate selector:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `build_version` | Reuse an existing immutable `X.Y.Z` candidate. | Leave empty for a new candidate. Use an existing value only to verify or repair its immutable aliases. |\n\nThe workflow rejects arbitrary source refs, source SHAs, and temporary version overrides. The checked-in, synchronized plain numeric `VERSION` is the only publishable version source.\n\n## Validation\n\nBefore it publishes anything, the workflow requires the following validation checks:\n\n- Backend type checks must pass.\n- Backend tests must pass.\n- Frontend type checks must pass.\n- Frontend tests must pass.\n- Each supported platform image must build, publish by digest, and start successfully.\n\nFor source checks, the workflow reuses successful backend and frontend jobs from `CI: Test` only when they ran on a push to `main` for the exact candidate commit. It checks each job separately. If a job was skipped, is still running, or its result cannot be verified, the release workflow runs that area's checks itself. PR checks alone do not qualify because they may test a different merge commit. Platform image builds and startup checks always run for a new candidate.\n\nThe workflow forces a fresh rebuild of the Dockerfile layer that installs Debian packages for that run. That keeps preview candidates aligned with the latest package fixes available from the Debian repositories at build time while still letting the rest of the image reuse BuildKit cache.\n\n## Published Output\n\nAfter validation, the workflow:\n\n1. Builds and pushes native `linux/amd64` and `linux/arm64` platform manifests to the internal `ghcr.io/\u003cowner\u003e/sambee-staging` repository.\n2. Starts those same images and waits for the health endpoint to succeed.\n3. Scans those same images with Trivy.\n4. Assembles the platform manifests into one multi-platform staging index and verifies its image labels.\n5. Extracts per-platform SBOM and provenance payloads on native runners, then assembles and publishes a metadata bundle that names the final `sambee` image identity under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n6. Signs and verifies the staging digest with Cosign using GitHub Actions OIDC.\n7. Copies the verified multi-platform index by digest to the immutable `sambee:build-vX.Y.Z` marker, then verifies the final image, metadata bundle, and signature again.\n8. Creates immutable `X.Y.Z` and `sha-\u003cfull-commit-sha\u003e` aliases and moves `test` to that same verified image.\n\nThe digest is the real artifact identity. The canonical `build-vX.Y.Z` tag is the candidate source of truth; `test` is only a moving alias.\n\nLater promotion may move `stable`, `beta`, or both channel aliases to that same image, depending on the release type and the current `beta` version.\n\nThe workflow uses digest-only platform pushes and run-scoped `stage-\u003crun\u003e-\u003cattempt\u003e-*` tags in `sambee-staging`. Treat them as internal transport artifacts, not release candidates.\n\nCosign writes the signature artifact into a dedicated signature repository so the main `sambee` package page stays centered on deployable image versions.\nThat signature repository can still show both digest-derived signature tags and referenced untagged bundle manifests, which are part of Cosign's current storage model rather than extra preview image variants.\n\n## Retry Behavior\n\nBefore the late candidate marker is written, a failed run may be retried with the same `Z` version. The run uses a unique `stage-\u003crun\u003e-\u003cattempt\u003e-\u003cplatform\u003e` tag in `sambee-staging` and cleans up its staging versions after promotion or failure. That package can also contain untagged digest-only platform manifests. The Docker publication lock serializes candidate and maintenance cleanup, so the cleanup may delete the whole isolated package when every tagged version is a staging tag; GHCR requires that package-level operation when the last tagged version remains. Scheduled cleanup reclaims stale staging artifacts and unreferenced signature and metadata artifacts.\n\nAfter a valid candidate marker exists, a matching dispatch takes the repair-only path. It verifies the signed digest and restores only missing matching immutable aliases or the `test` pointer; it does not rebuild the image. A conflicting immutable marker requires incrementing `Z` and publishing a new candidate.\n\nGitHub Actions concurrency is mutual exclusion, not a FIFO queue: only one pending run is retained for the publication lock. Avoid stacking dispatches. A superseded pending dispatch is safe to submit again because it did not reach a publication step.\n\n## Security Scan Behavior\n\nThe preview workflow runs Trivy before publish.\n\nFor preview publishing, Trivy findings are advisory rather than blocking. That keeps the newest candidate available for testing while still surfacing risk clearly in the workflow output.\n\nThe preview scan runs against the same pushed platform digests that are later assembled into the published candidate index, so validation and publication use the same platform manifests.\n\nThose manifests use the same OS-package refresh policy, so the candidate that gets published is rebuilt against current Debian package metadata for that workflow run.\n\n## Metadata\n\nThe published image includes OCI labels for the source repository, source ref name, git revision, version, creation time, and license.\n\nThe workflow also generates `GIT_COMMIT` in CI before building because GitHub-hosted runners do not run the local git hooks that usually keep that file current. That keeps frontend and backend build metadata aligned inside the container image.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Build Docker Image\"\n+++\n\nThis is step 1 of the Docker release flow.\n\nUse this `Release: Create Docker Image` workflow to create a deployable Docker image from a specific commit. It is the only workflow that builds and pushes a new Sambee image to GitHub Container Registry.\n\nThis workflow does not create a Git tag, does not publish a GitHub Release, and does not move anything to `stable` or `beta`. It builds a candidate image, validates it, publishes it under an immutable `sha-\u003cfull-commit-sha\u003e` tag, and moves the `test` tag to that same digest.\n\n## Summary\n\nUse this order when you are preparing a release candidate (RC) Docker image:\n\n1. Merge the commit you may want to ship.\n1. Start `Release: Create Docker Image` from that exact commit.\n   - Leave `source_ref` empty unless you deliberately need another immutable ref.\n   - Leave `publish_version_override` empty unless this is a preview-only label.\n1. Wait for the workflow to publish a new Docker image in GHCR tagged `sha-\u003cfull-commit-sha\u003e` and `test`.\n\n## Inputs\n\nThe manual workflow accepts these inputs:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `source_ref` | Which code to build. Use a commit SHA or tag. | Leave empty to build from the latest commit of the branch you selected when starting the run. Set it only when you need to point the run at a different commit. |\n| `publish_version_override` | Which version label to bake into the image. This is **not** the image tag used by Docker Compose. If you leave it empty, the workflow uses the checked-in `VERSION` value. | Use it for preview-only labels such as `0.8.0-test.1`. Leave it empty for a normal release candidate. |\n\nIf `publish_version_override` is set, CI rewrites `VERSION` for that run only and reruns `./scripts/sync-version` before building.\n\nThat version value is written into the image metadata and the generated metadata bundle. It is not the main preview lookup tag. The candidate is still published under `sha-\u003cfull-commit-sha\u003e` and then exposed through the moving `test` tag.\n\n## Validation\n\nBefore it publishes anything, the workflow runs the following validation checks:\n\n- Backend type checks must pass.\n- Backend tests must pass.\n- Frontend type checks must pass.\n- Frontend tests must pass.\n- Each supported platform image must build, publish by digest, and start successfully.\n\nThe workflow forces a fresh rebuild of the Dockerfile layer that installs Debian packages for that run. That keeps preview candidates aligned with the latest package fixes available from the Debian repositories at build time while still letting the rest of the image reuse BuildKit cache.\n\n## Published Output\n\nAfter validation, the workflow:\n\n1. Builds and pushes native `linux/amd64` and `linux/arm64` platform manifests.\n2. Starts those same images and waits for the health endpoint to succeed.\n3. Scans those same images with Trivy.\n4. Assembles the platform manifests into one multi-platform candidate index.\n5. Publishes that candidate index under `sha-\u003cfull-commit-sha\u003e`.\n6. Extracts per-platform SBOM and provenance payloads on native runners, then assembles and publishes the metadata bundle under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n7. Moves the `test` tag onto that same digest after metadata bundle publication succeeds.\n8. Signs the digest with Cosign using GitHub Actions OIDC.\n\nThe digest is the real artifact identity. The `test` tag is only a moving alias.\n\nLater promotion may move `stable`, `beta`, or both channel aliases to that same digest, depending on the release type and the current `beta` version.\n\nThe workflow uses digest-only platform pushes while assembling the final candidate index. Treat those platform manifests as internal publish artifacts, not release candidates.\n\nCosign writes the signature artifact into a dedicated signature repository so the main `sambee` package page stays centered on deployable image versions.\nThat signature repository can still show both digest-derived signature tags and referenced untagged bundle manifests, which are part of Cosign's current storage model rather than extra preview image variants.\n\n## Security Scan Behavior\n\nThe preview workflow runs Trivy before publish.\n\nFor preview publishing, Trivy findings are advisory rather than blocking. That keeps the newest candidate available for testing while still surfacing risk clearly in the workflow output.\n\nThe preview scan runs against the same pushed platform digests that are later assembled into the published candidate index, so validation and publication use the same platform manifests.\n\nThose manifests use the same OS-package refresh policy, so the candidate that gets published is rebuilt against current Debian package metadata for that workflow run.\n\n## Metadata\n\nThe published image includes OCI labels for the source repository, source ref name, git revision, version, creation time, and license.\n\nThe workflow also generates `GIT_COMMIT` in CI before building because GitHub-hosted runners do not run the local git hooks that usually keep that file current. That keeps frontend and backend build metadata aligned inside the container image.\n", "0.8": "+++\ntitle = \"Build Docker Image\"\n+++\n\nThis is step 1 of the Docker release flow.\n\nUse this `Release: Create Docker Image` workflow to create a deployable Docker image from a specific commit. It is the only workflow that builds and pushes a new Sambee image to GitHub Container Registry.\n\nThis workflow does not create a Git tag, does not publish a GitHub Release, and does not move anything to `stable` or `beta`. It builds a candidate image, validates it, publishes it under an immutable `sha-\u003cfull-commit-sha\u003e` tag, and moves the `test` tag to that same digest.\n\n## Summary\n\nUse this order when you are preparing a release candidate (RC) Docker image:\n\n1. Merge the commit you may want to ship.\n1. Start `Release: Create Docker Image` from that exact commit.\n   - Leave `source_ref` empty unless you deliberately need another immutable ref.\n   - Leave `publish_version_override` empty unless this is a preview-only label.\n1. Wait for the workflow to publish a new Docker image in GHCR tagged `sha-\u003cfull-commit-sha\u003e` and `test`.\n\n## Inputs\n\nThe manual workflow accepts these inputs:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `source_ref` | Which code to build. Use a commit SHA or tag. | Leave empty to build from the latest commit of the branch you selected when starting the run. Set it only when you need to point the run at a different commit. |\n| `publish_version_override` | Which version label to bake into the image. This is **not** the image tag used by Docker Compose. If you leave it empty, the workflow uses the checked-in `VERSION` value. | Use it for preview-only labels such as `0.8.0-test.1`. Leave it empty for a normal release candidate. |\n\nIf `publish_version_override` is set, CI rewrites `VERSION` for that run only and reruns `./scripts/sync-version` before building.\n\nThat version value is written into the image metadata and the generated metadata bundle. It is not the main preview lookup tag. The candidate is still published under `sha-\u003cfull-commit-sha\u003e` and then exposed through the moving `test` tag.\n\n## Validation\n\nBefore it publishes anything, the workflow runs the following validation checks:\n\n- Backend type checks must pass.\n- Backend tests must pass.\n- Frontend type checks must pass.\n- Frontend tests must pass.\n- Each supported platform image must build, publish by digest, and start successfully.\n\nThe workflow forces a fresh rebuild of the Dockerfile layer that installs Debian packages for that run. That keeps preview candidates aligned with the latest package fixes available from the Debian repositories at build time while still letting the rest of the image reuse BuildKit cache.\n\n## Published Output\n\nAfter validation, the workflow:\n\n1. Builds and pushes native `linux/amd64` and `linux/arm64` platform manifests.\n2. Starts those same images and waits for the health endpoint to succeed.\n3. Scans those same images with Trivy.\n4. Assembles the platform manifests into one multi-platform candidate index.\n5. Publishes that candidate index under `sha-\u003cfull-commit-sha\u003e`.\n6. Extracts per-platform SBOM and provenance payloads on native runners, then assembles and publishes the metadata bundle under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n7. Moves the `test` tag onto that same digest after metadata bundle publication succeeds.\n8. Signs the digest with Cosign using GitHub Actions OIDC.\n\nThe digest is the real artifact identity. The `test` tag is only a moving alias.\n\nLater promotion may move `stable`, `beta`, or both channel aliases to that same digest, depending on the release type and the current `beta` version.\n\nThe workflow uses digest-only platform pushes while assembling the final candidate index. Treat those platform manifests as internal publish artifacts, not release candidates.\n\nCosign writes the signature artifact into a dedicated signature repository so the main `sambee` package page stays centered on deployable image versions.\nThat signature repository can still show both digest-derived signature tags and referenced untagged bundle manifests, which are part of Cosign's current storage model rather than extra preview image variants.\n\n## Security Scan Behavior\n\nThe preview workflow runs Trivy before publish.\n\nFor preview publishing, Trivy findings are advisory rather than blocking. That keeps the newest candidate available for testing while still surfacing risk clearly in the workflow output.\n\nThe preview scan runs against the same pushed platform digests that are later assembled into the published candidate index, so validation and publication use the same platform manifests.\n\nThose manifests use the same OS-package refresh policy, so the candidate that gets published is rebuilt against current Debian package metadata for that workflow run.\n\n## Metadata\n\nThe published image includes OCI labels for the source repository, source ref name, git revision, version, creation time, and license.\n\nThe workflow also generates `GIT_COMMIT` in CI before building because GitHub-hosted runners do not run the local git hooks that usually keep that file current. That keeps frontend and backend build metadata aligned inside the container image.\n", "0.9": "+++\ntitle = \"Build Docker Image\"\n+++\n\nThis is step 1 of the Docker release flow ([overview](../docker-release-overview/)).\n\nUse `Release: Create Docker Image` to build one immutable Docker candidate from `main`. It is the only workflow that builds and pushes a new Sambee image to GitHub Container Registry (GHCR).\n\nThe workflow reserves the annotated canonical Git tag `build-vX.Y.Z` for the committed, synchronized `VERSION` source. It does not publish a GitHub Release or move `stable` or `beta`.\n\n## Inputs\n\nThe workflow accepts only an optional existing candidate selector:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `build_version` | Reuse an existing immutable `X.Y.Z` candidate. | Leave empty for a new candidate. Use an existing value only to verify or repair its immutable aliases. |\n\nThe workflow rejects arbitrary source refs, source SHAs, and temporary version overrides. The checked-in, synchronized plain numeric `VERSION` is the only publishable version source.\n\n## Validation\n\nBefore it publishes anything, the workflow runs the following validation checks:\n\n- Backend type checks must pass.\n- Backend tests must pass.\n- Frontend type checks must pass.\n- Frontend tests must pass.\n- Each supported platform image must build, publish by digest, and start successfully.\n\nThe workflow forces a fresh rebuild of the Dockerfile layer that installs Debian packages for that run. That keeps preview candidates aligned with the latest package fixes available from the Debian repositories at build time while still letting the rest of the image reuse BuildKit cache.\n\n## Published Output\n\nAfter validation, the workflow:\n\n1. Builds and pushes native `linux/amd64` and `linux/arm64` platform manifests to the internal `ghcr.io/\u003cowner\u003e/sambee-staging` repository.\n2. Starts those same images and waits for the health endpoint to succeed.\n3. Scans those same images with Trivy.\n4. Assembles the platform manifests into one multi-platform staging index and verifies its image labels.\n5. Extracts per-platform SBOM and provenance payloads on native runners, then assembles and publishes a metadata bundle that names the final `sambee` image identity under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n6. Signs and verifies the staging digest with Cosign using GitHub Actions OIDC.\n7. Copies the verified multi-platform index by digest to the immutable `sambee:build-vX.Y.Z` marker, then verifies the final image, metadata bundle, and signature again.\n8. Creates immutable `X.Y.Z` and `sha-\u003cfull-commit-sha\u003e` aliases and moves `test` to that same verified image.\n\nThe digest is the real artifact identity. The canonical `build-vX.Y.Z` tag is the candidate source of truth; `test` is only a moving alias.\n\nLater promotion may move `stable`, `beta`, or both channel aliases to that same image, depending on the release type and the current `beta` version.\n\nThe workflow uses digest-only platform pushes and run-scoped `stage-\u003crun\u003e-\u003cattempt\u003e-*` tags in `sambee-staging`. Treat them as internal transport artifacts, not release candidates.\n\nCosign writes the signature artifact into a dedicated signature repository so the main `sambee` package page stays centered on deployable image versions.\nThat signature repository can still show both digest-derived signature tags and referenced untagged bundle manifests, which are part of Cosign's current storage model rather than extra preview image variants.\n\n## Retry Behavior\n\nBefore the late candidate marker is written, a failed run may be retried with the same `Z` version. The run uses a unique `stage-\u003crun\u003e-\u003cattempt\u003e-\u003cplatform\u003e` tag in `sambee-staging` and cleans up its staging versions after promotion or failure. That package can also contain untagged digest-only platform manifests. The Docker publication lock serializes candidate and maintenance cleanup, so the cleanup may delete the whole isolated package when every tagged version is a staging tag; GHCR requires that package-level operation when the last tagged version remains. Scheduled cleanup reclaims stale staging artifacts and unreferenced signature and metadata artifacts.\n\nAfter a valid candidate marker exists, a matching dispatch takes the repair-only path. It verifies the signed digest and restores only missing matching immutable aliases or the `test` pointer; it does not rebuild the image. A conflicting immutable marker requires incrementing `Z` and publishing a new candidate.\n\nGitHub Actions concurrency is mutual exclusion, not a FIFO queue: only one pending run is retained for the publication lock. Avoid stacking dispatches. A superseded pending dispatch is safe to submit again because it did not reach a publication step.\n\n## Security Scan Behavior\n\nThe preview workflow runs Trivy before publish.\n\nFor preview publishing, Trivy findings are advisory rather than blocking. That keeps the newest candidate available for testing while still surfacing risk clearly in the workflow output.\n\nThe preview scan runs against the same pushed platform digests that are later assembled into the published candidate index, so validation and publication use the same platform manifests.\n\nThose manifests use the same OS-package refresh policy, so the candidate that gets published is rebuilt against current Debian package metadata for that workflow run.\n\n## Metadata\n\nThe published image includes OCI labels for the source repository, source ref name, git revision, version, creation time, and license.\n\nThe workflow also generates `GIT_COMMIT` in CI before building because GitHub-hosted runners do not run the local git hooks that usually keep that file current. That keeps frontend and backend build metadata aligned inside the container image.\n", "1.0": "+++\ntitle = \"Build Docker Image\"\n+++\n\nThis is step 1 of the Docker release flow ([overview](../docker-release-overview/)).\n\nUse `Release: Create Docker Image` to build one immutable Docker candidate from `main`. It is the only workflow that builds and pushes a new Sambee image to GitHub Container Registry (GHCR).\n\nThe workflow reserves the annotated canonical Git tag `build-vX.Y.Z` for the committed, synchronized `VERSION` source. It does not publish a GitHub Release or move `stable` or `beta`.\n\n## Inputs\n\nThe workflow accepts only an optional existing candidate selector:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `build_version` | Reuse an existing immutable `X.Y.Z` candidate. | Leave empty for a new candidate. Use an existing value only to verify or repair its immutable aliases. |\n\nThe workflow rejects arbitrary source refs, source SHAs, and temporary version overrides. The checked-in, synchronized plain numeric `VERSION` is the only publishable version source.\n\n## Validation\n\nBefore it publishes anything, the workflow runs the following validation checks:\n\n- Backend type checks must pass.\n- Backend tests must pass.\n- Frontend type checks must pass.\n- Frontend tests must pass.\n- Each supported platform image must build, publish by digest, and start successfully.\n\nThe workflow forces a fresh rebuild of the Dockerfile layer that installs Debian packages for that run. That keeps preview candidates aligned with the latest package fixes available from the Debian repositories at build time while still letting the rest of the image reuse BuildKit cache.\n\n## Published Output\n\nAfter validation, the workflow:\n\n1. Builds and pushes native `linux/amd64` and `linux/arm64` platform manifests to the internal `ghcr.io/\u003cowner\u003e/sambee-staging` repository.\n2. Starts those same images and waits for the health endpoint to succeed.\n3. Scans those same images with Trivy.\n4. Assembles the platform manifests into one multi-platform staging index and verifies its image labels.\n5. Extracts per-platform SBOM and provenance payloads on native runners, then assembles and publishes a metadata bundle that names the final `sambee` image identity under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n6. Signs and verifies the staging digest with Cosign using GitHub Actions OIDC.\n7. Copies the verified multi-platform index by digest to the immutable `sambee:build-vX.Y.Z` marker, then verifies the final image, metadata bundle, and signature again.\n8. Creates immutable `X.Y.Z` and `sha-\u003cfull-commit-sha\u003e` aliases and moves `test` to that same verified image.\n\nThe digest is the real artifact identity. The canonical `build-vX.Y.Z` tag is the candidate source of truth; `test` is only a moving alias.\n\nLater promotion may move `stable`, `beta`, or both channel aliases to that same image, depending on the release type and the current `beta` version.\n\nThe workflow uses digest-only platform pushes and run-scoped `stage-\u003crun\u003e-\u003cattempt\u003e-*` tags in `sambee-staging`. Treat them as internal transport artifacts, not release candidates.\n\nCosign writes the signature artifact into a dedicated signature repository so the main `sambee` package page stays centered on deployable image versions.\nThat signature repository can still show both digest-derived signature tags and referenced untagged bundle manifests, which are part of Cosign's current storage model rather than extra preview image variants.\n\n## Retry Behavior\n\nBefore the late candidate marker is written, a failed run may be retried with the same `Z` version. The run uses a unique `stage-\u003crun\u003e-\u003cattempt\u003e-\u003cplatform\u003e` tag in `sambee-staging` and cleans up its staging versions after promotion or failure. That package can also contain untagged digest-only platform manifests. The Docker publication lock serializes candidate and maintenance cleanup, so the cleanup may delete the whole isolated package when every tagged version is a staging tag; GHCR requires that package-level operation when the last tagged version remains. Scheduled cleanup reclaims stale staging artifacts and unreferenced signature and metadata artifacts.\n\nAfter a valid candidate marker exists, a matching dispatch takes the repair-only path. It verifies the signed digest and restores only missing matching immutable aliases or the `test` pointer; it does not rebuild the image. A conflicting immutable marker requires incrementing `Z` and publishing a new candidate.\n\nGitHub Actions concurrency is mutual exclusion, not a FIFO queue: only one pending run is retained for the publication lock. Avoid stacking dispatches. A superseded pending dispatch is safe to submit again because it did not reach a publication step.\n\n## Security Scan Behavior\n\nThe preview workflow runs Trivy before publish.\n\nFor preview publishing, Trivy findings are advisory rather than blocking. That keeps the newest candidate available for testing while still surfacing risk clearly in the workflow output.\n\nThe preview scan runs against the same pushed platform digests that are later assembled into the published candidate index, so validation and publication use the same platform manifests.\n\nThose manifests use the same OS-package refresh policy, so the candidate that gets published is rebuilt against current Debian package metadata for that workflow run.\n\n## Metadata\n\nThe published image includes OCI labels for the source repository, source ref name, git revision, version, creation time, and license.\n\nThe workflow also generates `GIT_COMMIT` in CI before building because GitHub-hosted runners do not run the local git hooks that usually keep that file current. That keeps frontend and backend build metadata aligned inside the container image.\n", "2.0": "+++\ntitle = \"Build Docker Image\"\n+++\n\nThis is step 1 of the Docker release flow ([overview](../docker-release-overview/)).\n\nUse `Release: Create Docker Image` to build one immutable Docker candidate from `main`. It is the only workflow that builds and pushes a new Sambee image to GitHub Container Registry (GHCR).\n\nThe workflow reserves the annotated canonical Git tag `build-vX.Y.Z` for the committed, synchronized `VERSION` source. It does not publish a GitHub Release or move `stable` or `beta`.\n\n## Inputs\n\nThe workflow accepts only an optional existing candidate selector:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `build_version` | Reuse an existing immutable `X.Y.Z` candidate. | Leave empty for a new candidate. Use an existing value only to verify or repair its immutable aliases. |\n\nThe workflow rejects arbitrary source refs, source SHAs, and temporary version overrides. The checked-in, synchronized plain numeric `VERSION` is the only publishable version source.\n\n## Validation\n\nBefore it publishes anything, the workflow requires the following validation checks:\n\n- Backend type checks must pass.\n- Backend tests must pass.\n- Frontend type checks must pass.\n- Frontend tests must pass.\n- Each supported platform image must build, publish by digest, and start successfully.\n\nFor source checks, the workflow reuses successful backend and frontend jobs from `CI: Test` only when they ran on a push to `main` for the exact candidate commit. It checks each job separately. If a job was skipped, is still running, or its result cannot be verified, the release workflow runs that area's checks itself. PR checks alone do not qualify because they may test a different merge commit. Platform image builds and startup checks always run for a new candidate.\n\nThe workflow forces a fresh rebuild of the Dockerfile layer that installs Debian packages for that run. That keeps preview candidates aligned with the latest package fixes available from the Debian repositories at build time while still letting the rest of the image reuse BuildKit cache.\n\n## Published Output\n\nAfter validation, the workflow:\n\n1. Builds and pushes native `linux/amd64` and `linux/arm64` platform manifests to the internal `ghcr.io/\u003cowner\u003e/sambee-staging` repository.\n2. Starts those same images and waits for the health endpoint to succeed.\n3. Scans those same images with Trivy.\n4. Assembles the platform manifests into one multi-platform staging index and verifies its image labels.\n5. Extracts per-platform SBOM and provenance payloads on native runners, then assembles and publishes a metadata bundle that names the final `sambee` image identity under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n6. Signs and verifies the staging digest with Cosign using GitHub Actions OIDC.\n7. Copies the verified multi-platform index by digest to the immutable `sambee:build-vX.Y.Z` marker, then verifies the final image, metadata bundle, and signature again.\n8. Creates immutable `X.Y.Z` and `sha-\u003cfull-commit-sha\u003e` aliases and moves `test` to that same verified image.\n\nThe digest is the real artifact identity. The canonical `build-vX.Y.Z` tag is the candidate source of truth; `test` is only a moving alias.\n\nLater promotion may move `stable`, `beta`, or both channel aliases to that same image, depending on the release type and the current `beta` version.\n\nThe workflow uses digest-only platform pushes and run-scoped `stage-\u003crun\u003e-\u003cattempt\u003e-*` tags in `sambee-staging`. Treat them as internal transport artifacts, not release candidates.\n\nCosign writes the signature artifact into a dedicated signature repository so the main `sambee` package page stays centered on deployable image versions.\nThat signature repository can still show both digest-derived signature tags and referenced untagged bundle manifests, which are part of Cosign's current storage model rather than extra preview image variants.\n\n## Retry Behavior\n\nBefore the late candidate marker is written, a failed run may be retried with the same `Z` version. The run uses a unique `stage-\u003crun\u003e-\u003cattempt\u003e-\u003cplatform\u003e` tag in `sambee-staging` and cleans up its staging versions after promotion or failure. That package can also contain untagged digest-only platform manifests. The Docker publication lock serializes candidate and maintenance cleanup, so the cleanup may delete the whole isolated package when every tagged version is a staging tag; GHCR requires that package-level operation when the last tagged version remains. Scheduled cleanup reclaims stale staging artifacts and unreferenced signature and metadata artifacts.\n\nAfter a valid candidate marker exists, a matching dispatch takes the repair-only path. It verifies the signed digest and restores only missing matching immutable aliases or the `test` pointer; it does not rebuild the image. A conflicting immutable marker requires incrementing `Z` and publishing a new candidate.\n\nGitHub Actions concurrency is mutual exclusion, not a FIFO queue: only one pending run is retained for the publication lock. Avoid stacking dispatches. A superseded pending dispatch is safe to submit again because it did not reach a publication step.\n\n## Security Scan Behavior\n\nThe preview workflow runs Trivy before publish.\n\nFor preview publishing, Trivy findings are advisory rather than blocking. That keeps the newest candidate available for testing while still surfacing risk clearly in the workflow output.\n\nThe preview scan runs against the same pushed platform digests that are later assembled into the published candidate index, so validation and publication use the same platform manifests.\n\nThose manifests use the same OS-package refresh policy, so the candidate that gets published is rebuilt against current Debian package metadata for that workflow run.\n\n## Metadata\n\nThe published image includes OCI labels for the source repository, source ref name, git revision, version, creation time, and license.\n\nThe workflow also generates `GIT_COMMIT` in CI before building because GitHub-hosted runners do not run the local git hooks that usually keep that file current. That keeps frontend and backend build metadata aligned inside the container image.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/release-and-versioning/promote-docker-image", "parent_id": "section:developer-guide/release-and-versioning", "depth": 2, "kind": "page", "label": "promote-docker-image", "title": "Promote Docker Image", "path": "developer-guide/release-and-versioning/promote-docker-image", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "branched", "source_version": "0.7", "diff_added": 42, "diff_removed": 32}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "inherited", "source_version": "0.9"}}, "content_versions": {"0.7": "+++\ntitle = \"Promote Docker Image\"\n+++\n\nThis is step 2 of the Docker release flow.\n\nUse this `Release: Publish Docker Image` workflow to move the `beta` or `stable` tags to an existing Docker image, and to apply version tags to the image (stable releases only).\n\n## How To Trigger the Workflow\n\nUse this order:\n\n1. Identify the commit whose preview image you validated from the tag on the GHCR Docker image (`sha-\u003ccommit\u003e`).\n1. Create the release Git tag on that exact commit.\n1. Push the tag to GitHub.\n1. Publish the GitHub Release from that tag.\n\nFor example, if the approved commit is `89378a28b18ba6532571e62734a6a9aefac6c99a` and `VERSION` is `0.7.0`:\n\n### Beta Example\n\n```bash\ngit tag -a v0.7.0-beta.1 89378a28b18ba6532571e62734a6a9aefac6c99a -m \"Sambee 0.7.0 beta 1\"\ngit push origin v0.7.0-beta.1\n```\n\n### Stable Example\n\n```bash\ngit tag -a v0.7.0 89378a28b18ba6532571e62734a6a9aefac6c99a -m \"Sambee 0.7.0\"\ngit push origin v0.7.0\n```\n\nIn the GitHub web UI, create a release from the existing tag. Avoid the branch selection.\n\n## Validation\n\nBefore promotion, the workflow checks all of the following:\n\n1. Stable releases must use the tag `v$(cat VERSION)`. Prereleases must start with that same base version and add a prerelease suffix, for example `v0.8.0-beta.1`.\n1. The corresponding immutable preview candidate tag `sha-\u003cfull-commit-sha\u003e` exists in GitHub Container Registry.\n1. The candidate image labels match the expected revision, checked-in product version, and source repository.\n1. The preview-built SBOM and provenance metadata bundle exists under the expected digest-derived `.meta` tag and matches the candidate digest.\n\nIf any of those checks fail, promotion stops.\n\n## Published Tags\n\nStable releases publish:\n\n- The full version tag, such as `0.7.0`.\n- The moving minor-series tag, such as `0.7`.\n- The moving channel tag `stable`.\n- The moving channel tag `beta`, unless `beta` already points to a higher semver release.\n\nPrereleases publish:\n\n- The moving channel tag `beta`.\n\nThat stable-release `beta` catch-up rule uses standard semver precedence. Build metadata does not make a version newer for ordering purposes.\n\nAfter the tag-promotion steps finish, the workflow uploads `metadata.json`, `provenance/intoto.jsonl`, and the platform SPDX SBOM files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in `ghcr.io/\u003cowner\u003e/sambee-signatures` remains the canonical metadata bundle.\n\nThe workflow then signs the promoted digest with Cosign. That signing step covers the same image digest that was validated and promoted.\n\n## Why No Rebuild\n\nThis model avoids rebuilding at release time.\n\nThe image tested as a preview candidate is therefore the exact same image that later becomes `stable` or `beta`. The preview-generated SBOM and provenance bundle is also verified against that same digest during promotion.\n\n## Tag Contract\n\nDocker image promotion expects release tags to use the checked-in base version from `VERSION`.\n\nExamples:\n\n- `VERSION` contains `0.7.0`.\n- A stable Git tag and GitHub Release must be `v0.7.0`.\n- A prerelease Git tag and GitHub Release may be `v0.7.0-beta.1`.\n\nIf those values drift apart, promotion fails.\n", "0.8": "+++\ntitle = \"Promote Docker Image\"\n+++\n\nThis is step 2 of the Docker release flow.\n\nUse this `Release: Publish Docker Image` workflow to move the `beta` or `stable` tags to an existing Docker image, and to apply version tags to the image (stable releases only).\n\n## How To Trigger the Workflow\n\nUse this order:\n\n1. Identify the commit whose preview image you validated from the tag on the GHCR Docker image (`sha-\u003ccommit\u003e`).\n1. Create the release Git tag on that exact commit.\n1. Push the tag to GitHub.\n1. Publish the GitHub Release from that tag.\n\nFor example, if the approved commit is `89378a28b18ba6532571e62734a6a9aefac6c99a` and `VERSION` is `0.7.0`:\n\n### Beta Example\n\n```bash\ngit tag -a v0.7.0-beta.1 89378a28b18ba6532571e62734a6a9aefac6c99a -m \"Sambee 0.7.0 beta 1\"\ngit push origin v0.7.0-beta.1\n```\n\n### Stable Example\n\n```bash\ngit tag -a v0.7.0 89378a28b18ba6532571e62734a6a9aefac6c99a -m \"Sambee 0.7.0\"\ngit push origin v0.7.0\n```\n\nIn the GitHub web UI, create a release from the existing tag. Avoid the branch selection.\n\n## Validation\n\nBefore promotion, the workflow checks all of the following:\n\n1. Stable releases must use the tag `v$(cat VERSION)`. Prereleases must start with that same base version and add a prerelease suffix, for example `v0.8.0-beta.1`.\n1. The corresponding immutable preview candidate tag `sha-\u003cfull-commit-sha\u003e` exists in GitHub Container Registry.\n1. The candidate image labels match the expected revision, checked-in product version, and source repository.\n1. The preview-built SBOM and provenance metadata bundle exists under the expected digest-derived `.meta` tag and matches the candidate digest.\n\nIf any of those checks fail, promotion stops.\n\n## Published Tags\n\nStable releases publish:\n\n- The full version tag, such as `0.7.0`.\n- The moving minor-series tag, such as `0.7`.\n- The moving channel tag `stable`.\n- The moving channel tag `beta`, unless `beta` already points to a higher semver release.\n\nPrereleases publish:\n\n- The moving channel tag `beta`.\n\nThat stable-release `beta` catch-up rule uses standard semver precedence. Build metadata does not make a version newer for ordering purposes.\n\nAfter the tag-promotion steps finish, the workflow uploads `metadata.json`, `provenance/intoto.jsonl`, and the platform SPDX SBOM files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in `ghcr.io/\u003cowner\u003e/sambee-signatures` remains the canonical metadata bundle.\n\nThe workflow then signs the promoted digest with Cosign. That signing step covers the same image digest that was validated and promoted.\n\n## Why No Rebuild\n\nThis model avoids rebuilding at release time.\n\nThe image tested as a preview candidate is therefore the exact same image that later becomes `stable` or `beta`. The preview-generated SBOM and provenance bundle is also verified against that same digest during promotion.\n\n## Tag Contract\n\nDocker image promotion expects release tags to use the checked-in base version from `VERSION`.\n\nExamples:\n\n- `VERSION` contains `0.7.0`.\n- A stable Git tag and GitHub Release must be `v0.7.0`.\n- A prerelease Git tag and GitHub Release may be `v0.7.0-beta.1`.\n\nIf those values drift apart, promotion fails.\n", "0.9": "+++\ntitle = \"Promote Docker Image\"\n+++\n\nThis is step 2 of the Docker release flow ([overview](../docker-release-overview/)).\n\nUse this `Release: Publish Docker Image` workflow to move Docker channel pointers to an already signed, immutable build. It has separate beta and stable paths.\n\n## How To Trigger the Workflow\n\n### Promote Beta\n\nTo promote an approved candidate to `beta`, run the workflow manually from `main` and enter its canonical build version, `X.Y.Z`.\n\nThe workflow resolves and verifies `build-vX.Y.Z`, then moves only the `beta` pointer. It does not create a public Git tag or GitHub Release, move `stable`, or add a minor-series tag. Normal beta promotion never moves the channel to an older version.\n\n### Promote Stable\n\nUse this order to promote a candidate to `stable`:\n\n1. Identify the approved canonical build tag, `build-vX.Y.Z`.\n1. Create the public Git tag `vX.Y.Z` on that same commit.\n1. Add `sambee-release.json` to the draft public release with `schema_version`, `version`, `build_tag`, `source_sha`, and `component_scope`.\n1. Set `component_scope` to `docker` or `both`, then publish the GitHub Release.\n\nFor example, if the approved commit is `89378a28b18ba6532571e62734a6a9aefac6c99a` and `VERSION` is `0.7.0`:\n\n```bash\ngit tag -a v0.7.0 89378a28b18ba6532571e62734a6a9aefac6c99a -m \"Sambee 0.7.0\"\ngit push origin v0.7.0\n```\n\nIn the GitHub web UI, create a release from the existing tag. Avoid the branch selection.\n\n## Validation\n\n### Beta Validation\n\nBefore beta promotion, the workflow checks all of the following:\n\n1. The workflow was dispatched from `main` with a plain numeric `X.Y.Z` build version.\n1. The corresponding `build-v\u003cversion\u003e` Git tag exists, is reachable from `main`, and identifies a source whose checked-in `VERSION` matches the requested version.\n\n### Stable Validation\n\nBefore stable promotion, the workflow checks all of the following:\n\n1. The release tag is exactly `v$(cat VERSION)` and is not a prerelease.\n1. The corresponding `build-v\u003cversion\u003e` Git and GHCR markers identify the same source and image.\n1. `sambee-release.json` authorizes Docker or both components and matches the version, build tag, and source SHA.\n\n### Common Validation\n\nBoth promotion paths check all of the following:\n\n1. The candidate image labels match the expected revision, checked-in product version, and source repository.\n1. The preview-built SBOM and provenance metadata bundle exists under the expected digest-derived `.meta` tag and matches the candidate digest.\n1. The candidate digest has the expected Cosign signature from the preview-build workflow.\n\nIf any of those checks fail, promotion stops.\n\n## Published Tags\n\nBeta promotion moves only the `beta` pointer.\n\nStable promotion moves these mutable pointers:\n\n- The moving minor-series tag, such as `0.7`.\n- The moving channel tag `stable`.\n- The `beta` tag when it is absent or does not point to a higher version.\n\nThe exact `X.Y.Z`, source-SHA, and `build-vX.Y.Z` tags were created by the build workflow and are immutable.\n\nAfter the tag-promotion steps finish, the workflow uploads `metadata.json`, `provenance/intoto.jsonl`, and the platform SPDX SBOM files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in `ghcr.io/\u003cowner\u003e/sambee-signatures` remains the canonical metadata bundle.\n\nThe build workflow signs the digest with Cosign before it assigns immutable registry markers. Promotion only moves pointers after verifying that published artifact.\n\n## Why No Rebuild\n\nThis model avoids rebuilding at release time.\n\nThe image tested as a preview candidate is therefore the exact same image that later becomes `stable` or `beta`. The preview-generated SBOM and provenance bundle is also verified against that same image during promotion.\n\n## Tag Contract\n\nDocker image promotion expects a plain release tag matching the checked-in version from `VERSION`.\n\nExamples:\n\n- `VERSION` contains `0.7.0`.\n- A stable Git tag and GitHub Release must be `v0.7.0`.\nIf those values drift apart, promotion fails.\n", "1.0": "+++\ntitle = \"Promote Docker Image\"\n+++\n\nThis is step 2 of the Docker release flow ([overview](../docker-release-overview/)).\n\nUse this `Release: Publish Docker Image` workflow to move Docker channel pointers to an already signed, immutable build. It has separate beta and stable paths.\n\n## How To Trigger the Workflow\n\n### Promote Beta\n\nTo promote an approved candidate to `beta`, run the workflow manually from `main` and enter its canonical build version, `X.Y.Z`.\n\nThe workflow resolves and verifies `build-vX.Y.Z`, then moves only the `beta` pointer. It does not create a public Git tag or GitHub Release, move `stable`, or add a minor-series tag. Normal beta promotion never moves the channel to an older version.\n\n### Promote Stable\n\nUse this order to promote a candidate to `stable`:\n\n1. Identify the approved canonical build tag, `build-vX.Y.Z`.\n1. Create the public Git tag `vX.Y.Z` on that same commit.\n1. Add `sambee-release.json` to the draft public release with `schema_version`, `version`, `build_tag`, `source_sha`, and `component_scope`.\n1. Set `component_scope` to `docker` or `both`, then publish the GitHub Release.\n\nFor example, if the approved commit is `89378a28b18ba6532571e62734a6a9aefac6c99a` and `VERSION` is `0.7.0`:\n\n```bash\ngit tag -a v0.7.0 89378a28b18ba6532571e62734a6a9aefac6c99a -m \"Sambee 0.7.0\"\ngit push origin v0.7.0\n```\n\nIn the GitHub web UI, create a release from the existing tag. Avoid the branch selection.\n\n## Validation\n\n### Beta Validation\n\nBefore beta promotion, the workflow checks all of the following:\n\n1. The workflow was dispatched from `main` with a plain numeric `X.Y.Z` build version.\n1. The corresponding `build-v\u003cversion\u003e` Git tag exists, is reachable from `main`, and identifies a source whose checked-in `VERSION` matches the requested version.\n\n### Stable Validation\n\nBefore stable promotion, the workflow checks all of the following:\n\n1. The release tag is exactly `v$(cat VERSION)` and is not a prerelease.\n1. The corresponding `build-v\u003cversion\u003e` Git and GHCR markers identify the same source and image.\n1. `sambee-release.json` authorizes Docker or both components and matches the version, build tag, and source SHA.\n\n### Common Validation\n\nBoth promotion paths check all of the following:\n\n1. The candidate image labels match the expected revision, checked-in product version, and source repository.\n1. The preview-built SBOM and provenance metadata bundle exists under the expected digest-derived `.meta` tag and matches the candidate digest.\n1. The candidate digest has the expected Cosign signature from the preview-build workflow.\n\nIf any of those checks fail, promotion stops.\n\n## Published Tags\n\nBeta promotion moves only the `beta` pointer.\n\nStable promotion moves these mutable pointers:\n\n- The moving minor-series tag, such as `0.7`.\n- The moving channel tag `stable`.\n- The `beta` tag when it is absent or does not point to a higher version.\n\nThe exact `X.Y.Z`, source-SHA, and `build-vX.Y.Z` tags were created by the build workflow and are immutable.\n\nAfter the tag-promotion steps finish, the workflow uploads `metadata.json`, `provenance/intoto.jsonl`, and the platform SPDX SBOM files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in `ghcr.io/\u003cowner\u003e/sambee-signatures` remains the canonical metadata bundle.\n\nThe build workflow signs the digest with Cosign before it assigns immutable registry markers. Promotion only moves pointers after verifying that published artifact.\n\n## Why No Rebuild\n\nThis model avoids rebuilding at release time.\n\nThe image tested as a preview candidate is therefore the exact same image that later becomes `stable` or `beta`. The preview-generated SBOM and provenance bundle is also verified against that same image during promotion.\n\n## Tag Contract\n\nDocker image promotion expects a plain release tag matching the checked-in version from `VERSION`.\n\nExamples:\n\n- `VERSION` contains `0.7.0`.\n- A stable Git tag and GitHub Release must be `v0.7.0`.\nIf those values drift apart, promotion fails.\n", "2.0": "+++\ntitle = \"Promote Docker Image\"\n+++\n\nThis is step 2 of the Docker release flow ([overview](../docker-release-overview/)).\n\nUse this `Release: Publish Docker Image` workflow to move Docker channel pointers to an already signed, immutable build. It has separate beta and stable paths.\n\n## How To Trigger the Workflow\n\n### Promote Beta\n\nTo promote an approved candidate to `beta`, run the workflow manually from `main` and enter its canonical build version, `X.Y.Z`.\n\nThe workflow resolves and verifies `build-vX.Y.Z`, then moves only the `beta` pointer. It does not create a public Git tag or GitHub Release, move `stable`, or add a minor-series tag. Normal beta promotion never moves the channel to an older version.\n\n### Promote Stable\n\nUse this order to promote a candidate to `stable`:\n\n1. Identify the approved canonical build tag, `build-vX.Y.Z`.\n1. Create the public Git tag `vX.Y.Z` on that same commit.\n1. Add `sambee-release.json` to the draft public release with `schema_version`, `version`, `build_tag`, `source_sha`, and `component_scope`.\n1. Set `component_scope` to `docker` or `both`, then publish the GitHub Release.\n\nFor example, if the approved commit is `89378a28b18ba6532571e62734a6a9aefac6c99a` and `VERSION` is `0.7.0`:\n\n```bash\ngit tag -a v0.7.0 89378a28b18ba6532571e62734a6a9aefac6c99a -m \"Sambee 0.7.0\"\ngit push origin v0.7.0\n```\n\nIn the GitHub web UI, create a release from the existing tag. Avoid the branch selection.\n\n## Validation\n\n### Beta Validation\n\nBefore beta promotion, the workflow checks all of the following:\n\n1. The workflow was dispatched from `main` with a plain numeric `X.Y.Z` build version.\n1. The corresponding `build-v\u003cversion\u003e` Git tag exists, is reachable from `main`, and identifies a source whose checked-in `VERSION` matches the requested version.\n\n### Stable Validation\n\nBefore stable promotion, the workflow checks all of the following:\n\n1. The release tag is exactly `v$(cat VERSION)` and is not a prerelease.\n1. The corresponding `build-v\u003cversion\u003e` Git and GHCR markers identify the same source and image.\n1. `sambee-release.json` authorizes Docker or both components and matches the version, build tag, and source SHA.\n\n### Common Validation\n\nBoth promotion paths check all of the following:\n\n1. The candidate image labels match the expected revision, checked-in product version, and source repository.\n1. The preview-built SBOM and provenance metadata bundle exists under the expected digest-derived `.meta` tag and matches the candidate digest.\n1. The candidate digest has the expected Cosign signature from the preview-build workflow.\n\nIf any of those checks fail, promotion stops.\n\n## Published Tags\n\nBeta promotion moves only the `beta` pointer.\n\nStable promotion moves these mutable pointers:\n\n- The moving minor-series tag, such as `0.7`.\n- The moving channel tag `stable`.\n- The `beta` tag when it is absent or does not point to a higher version.\n\nThe exact `X.Y.Z`, source-SHA, and `build-vX.Y.Z` tags were created by the build workflow and are immutable.\n\nAfter the tag-promotion steps finish, the workflow uploads `metadata.json`, `provenance/intoto.jsonl`, and the platform SPDX SBOM files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in `ghcr.io/\u003cowner\u003e/sambee-signatures` remains the canonical metadata bundle.\n\nThe build workflow signs the digest with Cosign before it assigns immutable registry markers. Promotion only moves pointers after verifying that published artifact.\n\n## Why No Rebuild\n\nThis model avoids rebuilding at release time.\n\nThe image tested as a preview candidate is therefore the exact same image that later becomes `stable` or `beta`. The preview-generated SBOM and provenance bundle is also verified against that same image during promotion.\n\n## Tag Contract\n\nDocker image promotion expects a plain release tag matching the checked-in version from `VERSION`.\n\nExamples:\n\n- `VERSION` contains `0.7.0`.\n- A stable Git tag and GitHub Release must be `v0.7.0`.\nIf those values drift apart, promotion fails.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Promote Docker Image\"\n+++\n\nThis is step 2 of the Docker release flow.\n\nUse this `Release: Publish Docker Image` workflow to move the `beta` or `stable` tags to an existing Docker image, and to apply version tags to the image (stable releases only).\n\n## How To Trigger the Workflow\n\nUse this order:\n\n1. Identify the commit whose preview image you validated from the tag on the GHCR Docker image (`sha-\u003ccommit\u003e`).\n1. Create the release Git tag on that exact commit.\n1. Push the tag to GitHub.\n1. Publish the GitHub Release from that tag.\n\nFor example, if the approved commit is `89378a28b18ba6532571e62734a6a9aefac6c99a` and `VERSION` is `0.7.0`:\n\n### Beta Example\n\n```bash\ngit tag -a v0.7.0-beta.1 89378a28b18ba6532571e62734a6a9aefac6c99a -m \"Sambee 0.7.0 beta 1\"\ngit push origin v0.7.0-beta.1\n```\n\n### Stable Example\n\n```bash\ngit tag -a v0.7.0 89378a28b18ba6532571e62734a6a9aefac6c99a -m \"Sambee 0.7.0\"\ngit push origin v0.7.0\n```\n\nIn the GitHub web UI, create a release from the existing tag. Avoid the branch selection.\n\n## Validation\n\nBefore promotion, the workflow checks all of the following:\n\n1. Stable releases must use the tag `v$(cat VERSION)`. Prereleases must start with that same base version and add a prerelease suffix, for example `v0.8.0-beta.1`.\n1. The corresponding immutable preview candidate tag `sha-\u003cfull-commit-sha\u003e` exists in GitHub Container Registry.\n1. The candidate image labels match the expected revision, checked-in product version, and source repository.\n1. The preview-built SBOM and provenance metadata bundle exists under the expected digest-derived `.meta` tag and matches the candidate digest.\n\nIf any of those checks fail, promotion stops.\n\n## Published Tags\n\nStable releases publish:\n\n- The full version tag, such as `0.7.0`.\n- The moving minor-series tag, such as `0.7`.\n- The moving channel tag `stable`.\n- The moving channel tag `beta`, unless `beta` already points to a higher semver release.\n\nPrereleases publish:\n\n- The moving channel tag `beta`.\n\nThat stable-release `beta` catch-up rule uses standard semver precedence. Build metadata does not make a version newer for ordering purposes.\n\nAfter the tag-promotion steps finish, the workflow uploads `metadata.json`, `provenance/intoto.jsonl`, and the platform SPDX SBOM files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in `ghcr.io/\u003cowner\u003e/sambee-signatures` remains the canonical metadata bundle.\n\nThe workflow then signs the promoted digest with Cosign. That signing step covers the same image digest that was validated and promoted.\n\n## Why No Rebuild\n\nThis model avoids rebuilding at release time.\n\nThe image tested as a preview candidate is therefore the exact same image that later becomes `stable` or `beta`. The preview-generated SBOM and provenance bundle is also verified against that same digest during promotion.\n\n## Tag Contract\n\nDocker image promotion expects release tags to use the checked-in base version from `VERSION`.\n\nExamples:\n\n- `VERSION` contains `0.7.0`.\n- A stable Git tag and GitHub Release must be `v0.7.0`.\n- A prerelease Git tag and GitHub Release may be `v0.7.0-beta.1`.\n\nIf those values drift apart, promotion fails.\n", "0.8": "+++\ntitle = \"Promote Docker Image\"\n+++\n\nThis is step 2 of the Docker release flow.\n\nUse this `Release: Publish Docker Image` workflow to move the `beta` or `stable` tags to an existing Docker image, and to apply version tags to the image (stable releases only).\n\n## How To Trigger the Workflow\n\nUse this order:\n\n1. Identify the commit whose preview image you validated from the tag on the GHCR Docker image (`sha-\u003ccommit\u003e`).\n1. Create the release Git tag on that exact commit.\n1. Push the tag to GitHub.\n1. Publish the GitHub Release from that tag.\n\nFor example, if the approved commit is `89378a28b18ba6532571e62734a6a9aefac6c99a` and `VERSION` is `0.7.0`:\n\n### Beta Example\n\n```bash\ngit tag -a v0.7.0-beta.1 89378a28b18ba6532571e62734a6a9aefac6c99a -m \"Sambee 0.7.0 beta 1\"\ngit push origin v0.7.0-beta.1\n```\n\n### Stable Example\n\n```bash\ngit tag -a v0.7.0 89378a28b18ba6532571e62734a6a9aefac6c99a -m \"Sambee 0.7.0\"\ngit push origin v0.7.0\n```\n\nIn the GitHub web UI, create a release from the existing tag. Avoid the branch selection.\n\n## Validation\n\nBefore promotion, the workflow checks all of the following:\n\n1. Stable releases must use the tag `v$(cat VERSION)`. Prereleases must start with that same base version and add a prerelease suffix, for example `v0.8.0-beta.1`.\n1. The corresponding immutable preview candidate tag `sha-\u003cfull-commit-sha\u003e` exists in GitHub Container Registry.\n1. The candidate image labels match the expected revision, checked-in product version, and source repository.\n1. The preview-built SBOM and provenance metadata bundle exists under the expected digest-derived `.meta` tag and matches the candidate digest.\n\nIf any of those checks fail, promotion stops.\n\n## Published Tags\n\nStable releases publish:\n\n- The full version tag, such as `0.7.0`.\n- The moving minor-series tag, such as `0.7`.\n- The moving channel tag `stable`.\n- The moving channel tag `beta`, unless `beta` already points to a higher semver release.\n\nPrereleases publish:\n\n- The moving channel tag `beta`.\n\nThat stable-release `beta` catch-up rule uses standard semver precedence. Build metadata does not make a version newer for ordering purposes.\n\nAfter the tag-promotion steps finish, the workflow uploads `metadata.json`, `provenance/intoto.jsonl`, and the platform SPDX SBOM files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in `ghcr.io/\u003cowner\u003e/sambee-signatures` remains the canonical metadata bundle.\n\nThe workflow then signs the promoted digest with Cosign. That signing step covers the same image digest that was validated and promoted.\n\n## Why No Rebuild\n\nThis model avoids rebuilding at release time.\n\nThe image tested as a preview candidate is therefore the exact same image that later becomes `stable` or `beta`. The preview-generated SBOM and provenance bundle is also verified against that same digest during promotion.\n\n## Tag Contract\n\nDocker image promotion expects release tags to use the checked-in base version from `VERSION`.\n\nExamples:\n\n- `VERSION` contains `0.7.0`.\n- A stable Git tag and GitHub Release must be `v0.7.0`.\n- A prerelease Git tag and GitHub Release may be `v0.7.0-beta.1`.\n\nIf those values drift apart, promotion fails.\n", "0.9": "+++\ntitle = \"Promote Docker Image\"\n+++\n\nThis is step 2 of the Docker release flow ([overview](../docker-release-overview/)).\n\nUse this `Release: Publish Docker Image` workflow to move Docker channel pointers to an already signed, immutable build. It has separate beta and stable paths.\n\n## How To Trigger the Workflow\n\n### Promote Beta\n\nTo promote an approved candidate to `beta`, run the workflow manually from `main` and enter its canonical build version, `X.Y.Z`.\n\nThe workflow resolves and verifies `build-vX.Y.Z`, then moves only the `beta` pointer. It does not create a public Git tag or GitHub Release, move `stable`, or add a minor-series tag. Normal beta promotion never moves the channel to an older version.\n\n### Promote Stable\n\nUse this order to promote a candidate to `stable`:\n\n1. Identify the approved canonical build tag, `build-vX.Y.Z`.\n1. Create the public Git tag `vX.Y.Z` on that same commit.\n1. Add `sambee-release.json` to the draft public release with `schema_version`, `version`, `build_tag`, `source_sha`, and `component_scope`.\n1. Set `component_scope` to `docker` or `both`, then publish the GitHub Release.\n\nFor example, if the approved commit is `89378a28b18ba6532571e62734a6a9aefac6c99a` and `VERSION` is `0.7.0`:\n\n```bash\ngit tag -a v0.7.0 89378a28b18ba6532571e62734a6a9aefac6c99a -m \"Sambee 0.7.0\"\ngit push origin v0.7.0\n```\n\nIn the GitHub web UI, create a release from the existing tag. Avoid the branch selection.\n\n## Validation\n\n### Beta Validation\n\nBefore beta promotion, the workflow checks all of the following:\n\n1. The workflow was dispatched from `main` with a plain numeric `X.Y.Z` build version.\n1. The corresponding `build-v\u003cversion\u003e` Git tag exists, is reachable from `main`, and identifies a source whose checked-in `VERSION` matches the requested version.\n\n### Stable Validation\n\nBefore stable promotion, the workflow checks all of the following:\n\n1. The release tag is exactly `v$(cat VERSION)` and is not a prerelease.\n1. The corresponding `build-v\u003cversion\u003e` Git and GHCR markers identify the same source and image.\n1. `sambee-release.json` authorizes Docker or both components and matches the version, build tag, and source SHA.\n\n### Common Validation\n\nBoth promotion paths check all of the following:\n\n1. The candidate image labels match the expected revision, checked-in product version, and source repository.\n1. The preview-built SBOM and provenance metadata bundle exists under the expected digest-derived `.meta` tag and matches the candidate digest.\n1. The candidate digest has the expected Cosign signature from the preview-build workflow.\n\nIf any of those checks fail, promotion stops.\n\n## Published Tags\n\nBeta promotion moves only the `beta` pointer.\n\nStable promotion moves these mutable pointers:\n\n- The moving minor-series tag, such as `0.7`.\n- The moving channel tag `stable`.\n- The `beta` tag when it is absent or does not point to a higher version.\n\nThe exact `X.Y.Z`, source-SHA, and `build-vX.Y.Z` tags were created by the build workflow and are immutable.\n\nAfter the tag-promotion steps finish, the workflow uploads `metadata.json`, `provenance/intoto.jsonl`, and the platform SPDX SBOM files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in `ghcr.io/\u003cowner\u003e/sambee-signatures` remains the canonical metadata bundle.\n\nThe build workflow signs the digest with Cosign before it assigns immutable registry markers. Promotion only moves pointers after verifying that published artifact.\n\n## Why No Rebuild\n\nThis model avoids rebuilding at release time.\n\nThe image tested as a preview candidate is therefore the exact same image that later becomes `stable` or `beta`. The preview-generated SBOM and provenance bundle is also verified against that same image during promotion.\n\n## Tag Contract\n\nDocker image promotion expects a plain release tag matching the checked-in version from `VERSION`.\n\nExamples:\n\n- `VERSION` contains `0.7.0`.\n- A stable Git tag and GitHub Release must be `v0.7.0`.\nIf those values drift apart, promotion fails.\n", "1.0": "+++\ntitle = \"Promote Docker Image\"\n+++\n\nThis is step 2 of the Docker release flow ([overview](../docker-release-overview/)).\n\nUse this `Release: Publish Docker Image` workflow to move Docker channel pointers to an already signed, immutable build. It has separate beta and stable paths.\n\n## How To Trigger the Workflow\n\n### Promote Beta\n\nTo promote an approved candidate to `beta`, run the workflow manually from `main` and enter its canonical build version, `X.Y.Z`.\n\nThe workflow resolves and verifies `build-vX.Y.Z`, then moves only the `beta` pointer. It does not create a public Git tag or GitHub Release, move `stable`, or add a minor-series tag. Normal beta promotion never moves the channel to an older version.\n\n### Promote Stable\n\nUse this order to promote a candidate to `stable`:\n\n1. Identify the approved canonical build tag, `build-vX.Y.Z`.\n1. Create the public Git tag `vX.Y.Z` on that same commit.\n1. Add `sambee-release.json` to the draft public release with `schema_version`, `version`, `build_tag`, `source_sha`, and `component_scope`.\n1. Set `component_scope` to `docker` or `both`, then publish the GitHub Release.\n\nFor example, if the approved commit is `89378a28b18ba6532571e62734a6a9aefac6c99a` and `VERSION` is `0.7.0`:\n\n```bash\ngit tag -a v0.7.0 89378a28b18ba6532571e62734a6a9aefac6c99a -m \"Sambee 0.7.0\"\ngit push origin v0.7.0\n```\n\nIn the GitHub web UI, create a release from the existing tag. Avoid the branch selection.\n\n## Validation\n\n### Beta Validation\n\nBefore beta promotion, the workflow checks all of the following:\n\n1. The workflow was dispatched from `main` with a plain numeric `X.Y.Z` build version.\n1. The corresponding `build-v\u003cversion\u003e` Git tag exists, is reachable from `main`, and identifies a source whose checked-in `VERSION` matches the requested version.\n\n### Stable Validation\n\nBefore stable promotion, the workflow checks all of the following:\n\n1. The release tag is exactly `v$(cat VERSION)` and is not a prerelease.\n1. The corresponding `build-v\u003cversion\u003e` Git and GHCR markers identify the same source and image.\n1. `sambee-release.json` authorizes Docker or both components and matches the version, build tag, and source SHA.\n\n### Common Validation\n\nBoth promotion paths check all of the following:\n\n1. The candidate image labels match the expected revision, checked-in product version, and source repository.\n1. The preview-built SBOM and provenance metadata bundle exists under the expected digest-derived `.meta` tag and matches the candidate digest.\n1. The candidate digest has the expected Cosign signature from the preview-build workflow.\n\nIf any of those checks fail, promotion stops.\n\n## Published Tags\n\nBeta promotion moves only the `beta` pointer.\n\nStable promotion moves these mutable pointers:\n\n- The moving minor-series tag, such as `0.7`.\n- The moving channel tag `stable`.\n- The `beta` tag when it is absent or does not point to a higher version.\n\nThe exact `X.Y.Z`, source-SHA, and `build-vX.Y.Z` tags were created by the build workflow and are immutable.\n\nAfter the tag-promotion steps finish, the workflow uploads `metadata.json`, `provenance/intoto.jsonl`, and the platform SPDX SBOM files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in `ghcr.io/\u003cowner\u003e/sambee-signatures` remains the canonical metadata bundle.\n\nThe build workflow signs the digest with Cosign before it assigns immutable registry markers. Promotion only moves pointers after verifying that published artifact.\n\n## Why No Rebuild\n\nThis model avoids rebuilding at release time.\n\nThe image tested as a preview candidate is therefore the exact same image that later becomes `stable` or `beta`. The preview-generated SBOM and provenance bundle is also verified against that same image during promotion.\n\n## Tag Contract\n\nDocker image promotion expects a plain release tag matching the checked-in version from `VERSION`.\n\nExamples:\n\n- `VERSION` contains `0.7.0`.\n- A stable Git tag and GitHub Release must be `v0.7.0`.\nIf those values drift apart, promotion fails.\n", "2.0": "+++\ntitle = \"Promote Docker Image\"\n+++\n\nThis is step 2 of the Docker release flow ([overview](../docker-release-overview/)).\n\nUse this `Release: Publish Docker Image` workflow to move Docker channel pointers to an already signed, immutable build. It has separate beta and stable paths.\n\n## How To Trigger the Workflow\n\n### Promote Beta\n\nTo promote an approved candidate to `beta`, run the workflow manually from `main` and enter its canonical build version, `X.Y.Z`.\n\nThe workflow resolves and verifies `build-vX.Y.Z`, then moves only the `beta` pointer. It does not create a public Git tag or GitHub Release, move `stable`, or add a minor-series tag. Normal beta promotion never moves the channel to an older version.\n\n### Promote Stable\n\nUse this order to promote a candidate to `stable`:\n\n1. Identify the approved canonical build tag, `build-vX.Y.Z`.\n1. Create the public Git tag `vX.Y.Z` on that same commit.\n1. Add `sambee-release.json` to the draft public release with `schema_version`, `version`, `build_tag`, `source_sha`, and `component_scope`.\n1. Set `component_scope` to `docker` or `both`, then publish the GitHub Release.\n\nFor example, if the approved commit is `89378a28b18ba6532571e62734a6a9aefac6c99a` and `VERSION` is `0.7.0`:\n\n```bash\ngit tag -a v0.7.0 89378a28b18ba6532571e62734a6a9aefac6c99a -m \"Sambee 0.7.0\"\ngit push origin v0.7.0\n```\n\nIn the GitHub web UI, create a release from the existing tag. Avoid the branch selection.\n\n## Validation\n\n### Beta Validation\n\nBefore beta promotion, the workflow checks all of the following:\n\n1. The workflow was dispatched from `main` with a plain numeric `X.Y.Z` build version.\n1. The corresponding `build-v\u003cversion\u003e` Git tag exists, is reachable from `main`, and identifies a source whose checked-in `VERSION` matches the requested version.\n\n### Stable Validation\n\nBefore stable promotion, the workflow checks all of the following:\n\n1. The release tag is exactly `v$(cat VERSION)` and is not a prerelease.\n1. The corresponding `build-v\u003cversion\u003e` Git and GHCR markers identify the same source and image.\n1. `sambee-release.json` authorizes Docker or both components and matches the version, build tag, and source SHA.\n\n### Common Validation\n\nBoth promotion paths check all of the following:\n\n1. The candidate image labels match the expected revision, checked-in product version, and source repository.\n1. The preview-built SBOM and provenance metadata bundle exists under the expected digest-derived `.meta` tag and matches the candidate digest.\n1. The candidate digest has the expected Cosign signature from the preview-build workflow.\n\nIf any of those checks fail, promotion stops.\n\n## Published Tags\n\nBeta promotion moves only the `beta` pointer.\n\nStable promotion moves these mutable pointers:\n\n- The moving minor-series tag, such as `0.7`.\n- The moving channel tag `stable`.\n- The `beta` tag when it is absent or does not point to a higher version.\n\nThe exact `X.Y.Z`, source-SHA, and `build-vX.Y.Z` tags were created by the build workflow and are immutable.\n\nAfter the tag-promotion steps finish, the workflow uploads `metadata.json`, `provenance/intoto.jsonl`, and the platform SPDX SBOM files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in `ghcr.io/\u003cowner\u003e/sambee-signatures` remains the canonical metadata bundle.\n\nThe build workflow signs the digest with Cosign before it assigns immutable registry markers. Promotion only moves pointers after verifying that published artifact.\n\n## Why No Rebuild\n\nThis model avoids rebuilding at release time.\n\nThe image tested as a preview candidate is therefore the exact same image that later becomes `stable` or `beta`. The preview-generated SBOM and provenance bundle is also verified against that same image during promotion.\n\n## Tag Contract\n\nDocker image promotion expects a plain release tag matching the checked-in version from `VERSION`.\n\nExamples:\n\n- `VERSION` contains `0.7.0`.\n- A stable Git tag and GitHub Release must be `v0.7.0`.\nIf those values drift apart, promotion fails.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/release-and-versioning/docker-backfill-and-cleanup", "parent_id": "section:developer-guide/release-and-versioning", "depth": 2, "kind": "page", "label": "docker-backfill-and-cleanup", "title": "Docker Backfill And Cleanup", "path": "developer-guide/release-and-versioning/docker-backfill-and-cleanup", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Docker Backfill And Cleanup\"\n+++\n\nThis is the maintenance page for the Docker release flow.\n\nUse these maintenance workflows when you need to repair tags, backfill an older approved release, or keep preview history under control.\n\n## Summary\n\nUse this page when you are not publishing a new Docker image, but instead need to maintain existing release artifacts in GitHub Container Registry.\n\n| Workflow | What it does | Required input | Use it when... |\n|---|---|---|---|\n| `Maintenance: Backfill Docker Release Tags` | Reattaches release tags and channel aliases to an already approved digest and republishes missing metadata bundle assets when needed. | One existing Git tag in release form, such as `v0.7.0` or `v0.7.0-beta.1`. | A release already exists, but its GHCR tags or release assets are missing, wrong, or need to be reconstructed without building a new image. |\n| `Maintenance: Clean Up Docker Package Versions` | Deletes unprotected preview versions, stale signature artifacts, and unreferenced untagged GHCR package versions. | None. | Preview history and dangling GHCR artifacts have accumulated and you want the repository cleaned up without touching protected release artifacts. |\n\n## Backfill Docker Release Tags\n\nGitHub Actions displays the recovery workflow as `Maintenance: Backfill Docker Release Tags`.\n\n### What it does\n\nUse it to repair or reconstruct the publish side of an already approved Docker release without publishing a new runtime image.\n\nThe workflow:\n\n- resolves the digest that already belongs to the approved release\n- verifies image metadata\n- verifies the preview-built metadata bundle, generating and publishing it first if an older release does not have one yet\n- reapplies the expected release tags to that same digest\n- updates channel aliases with the same semver rules as normal promotion\n- uploads the metadata bundle files to the GitHub Release as convenience assets\n\nFor stable releases, that means backfill also moves `beta` forward unless `beta` already points to the same digest or to a higher semver release line.\n\n### Required input\n\nThe workflow takes one manual input:\n\n| Input | What it means | Required |\n|---|---|---|\n| `release_tag` | An existing immutable Git tag for the approved release, for example `v0.7.0` or `v0.7.0-beta.1`. The tag must match the checked-in `VERSION` value for that tagged commit. | Yes |\n\n### When to use it\n\nUse backfill in specific repair scenarios such as:\n\n- The GitHub Release exists, but the expected GHCR release tags were not attached.\n- A stable release was approved earlier, and you need to restore `stable`, version tags, or `beta` catch-up behavior to the correct existing digest.\n- A prerelease was approved earlier, and you need to restore the `beta` alias to the already approved digest.\n- A transient runner or registry failure interrupted release publication after the candidate image had already been built successfully.\n- An older approved release predates the current metadata-bundle flow, and you need to reconstruct the release assets without rebuilding the runtime image.\n\nDo not use backfill when you want to ship a new candidate commit. In that case, go back to [Build Docker Image](../build-docker-image/) and then [Promote Docker Image](../promote-docker-image/).\n\n### Tag requirements\n\nThe release tag can be either a stable tag such as `v0.7.0` or a prerelease tag such as `vX.Y.Z-beta.N`, as long as it matches the checked-in base `VERSION` for that release commit.\n\nWhen an older release does not have the new metadata bundle yet, backfill may create a local attested OCI export from the tagged source to recover SBOM and provenance files. That export is used only to publish the missing metadata bundle; the runtime image digest being promoted does not change.\n\nUse backfill only for already approved releases. It is not an alternate way to publish a new image.\n\n## Clean Up Docker Package Versions\n\nGitHub Actions displays the retention workflow as `Maintenance: Clean Up Docker Package Versions`.\n\n### What it does\n\nThis workflow removes disposable GHCR history while preserving artifacts that are still in use.\n\nIt:\n\n- deletes unprotected preview package versions\n- prunes stale metadata and Cosign signature artifacts\n- removes unreferenced untagged package versions\n- preserves release-tagged versions, protected channel aliases, and graph-referenced child manifests\n\n### Required input\n\nThis workflow has no manual inputs.\n\nIt runs automatically after successful preview publication, on a schedule, or manually when you want to force a cleanup pass.\n\n### When to use it\n\nUse cleanup in specific maintenance scenarios such as:\n\n- Preview publishing has created many old `sha-\u003cfull-commit-sha\u003e` versions that are no longer needed.\n- GHCR package pages have accumulated stale signature or metadata artifacts from deleted image digests.\n- You want to verify that retention behavior is working after changes to release-tagging or cleanup logic.\n- You want an immediate cleanup run instead of waiting for the next scheduled pass.\n\nDo not use cleanup to repair a missing release tag or channel alias. Use `Maintenance: Backfill Docker Release Tags` for that.\n\n### What cleanup preserves\n\nThis workflow periodically deletes unprotected preview and unreferenced GitHub Container Registry versions while preserving:\n\n- release-tagged versions.\n- `stable`, `beta`, `test`, and stable minor-series tags.\n\nThe moving `test` tag is protected like the other channel aliases.\nImmutable `sha-\u003cfull-commit-sha\u003e` preview tags are deleted when they are no longer protected by another retained tag.\nUntagged child manifests referenced by retained multi-platform indexes are protected before stale untagged versions are deleted.\nThe cleanup also prunes stale `ghcr.io/\u003cowner\u003e/sambee-signatures` metadata and Cosign signature tags after their corresponding `sambee` image digest is no longer retained.\nThe same reference-aware untagged cleanup runs for `sambee-signatures`, where it keeps Cosign signature bundle children referenced by retained signature indexes.\n\nThat keeps the `test` channel usable while aggressively removing disposable preview history.\n\n## Cleanup Rules\n\nUse this quick reference when deciding what the cleanup workflow will keep versus delete.\n\n| If a package version is... | Cleanup action |\n|---|---|\n| Tagged with a release tag, whether stable or prerelease | Keep |\n| Tagged with a protected channel or series tag such as `stable`, `beta`, `test`, or `0.7` | Keep |\n| Tagged only with an immutable preview tag such as `sha-\u003cfull-commit-sha\u003e` | Delete |\n| Untagged but still referenced by a retained multi-platform image index | Keep |\n| Untagged and not referenced by any retained index | Delete |\n| A signature or metadata artifact for a retained image digest | Keep |\n| A signature or metadata artifact for a deleted image digest | Delete |\n\nThere is no retention count anymore. The workflow deletes every package version that is not protected by tags or by graph references.\n\n## Examples\n\n- `ghcr.io/\u003cowner\u003e/sambee:test` stays because `test` is a protected channel tag.\n- `ghcr.io/\u003cowner\u003e/sambee:sha-\u003cfull-commit-sha\u003e` is deleted if that digest is not also kept by another protected tag.\n- An untagged platform manifest stays if a retained multi-platform index still points to it.\n- A stale `ghcr.io/\u003cowner\u003e/sambee-signatures` artifact is deleted after its corresponding image digest is no longer retained.\n\n## Boundaries\n\n- Do not publish a replacement runtime image in backfill. Recovery should point tags back at an existing digest.\n- Do not treat immutable `sha-\u003cfull-commit-sha\u003e` preview tags as permanent history. The cleanup workflow is expected to prune them.\n- Do not use moving tags such as `stable`, `beta`, or `test` as the only source of deployment truth when a digest is available.\n\nIf you are starting from a new candidate commit rather than repairing an existing release path, go back to [Build Docker Image](../build-docker-image/) or [Promote Docker Image](../promote-docker-image/).\n", "0.8": "+++\ntitle = \"Docker Backfill And Cleanup\"\n+++\n\nThis is the maintenance page for the Docker release flow.\n\nUse these maintenance workflows when you need to repair tags, backfill an older approved release, or keep preview history under control.\n\n## Summary\n\nUse this page when you are not publishing a new Docker image, but instead need to maintain existing release artifacts in GitHub Container Registry.\n\n| Workflow | What it does | Required input | Use it when... |\n|---|---|---|---|\n| `Maintenance: Backfill Docker Release Tags` | Reattaches release tags and channel aliases to an already approved digest and republishes missing metadata bundle assets when needed. | One existing Git tag in release form, such as `v0.7.0` or `v0.7.0-beta.1`. | A release already exists, but its GHCR tags or release assets are missing, wrong, or need to be reconstructed without building a new image. |\n| `Maintenance: Clean Up Docker Package Versions` | Deletes unprotected preview versions, stale signature artifacts, and unreferenced untagged GHCR package versions. | None. | Preview history and dangling GHCR artifacts have accumulated and you want the repository cleaned up without touching protected release artifacts. |\n\n## Backfill Docker Release Tags\n\nGitHub Actions displays the recovery workflow as `Maintenance: Backfill Docker Release Tags`.\n\n### What it does\n\nUse it to repair or reconstruct the publish side of an already approved Docker release without publishing a new runtime image.\n\nThe workflow:\n\n- resolves the digest that already belongs to the approved release\n- verifies image metadata\n- verifies the preview-built metadata bundle, generating and publishing it first if an older release does not have one yet\n- reapplies the expected release tags to that same digest\n- updates channel aliases with the same semver rules as normal promotion\n- uploads the metadata bundle files to the GitHub Release as convenience assets\n\nFor stable releases, that means backfill also moves `beta` forward unless `beta` already points to the same digest or to a higher semver release line.\n\n### Required input\n\nThe workflow takes one manual input:\n\n| Input | What it means | Required |\n|---|---|---|\n| `release_tag` | An existing immutable Git tag for the approved release, for example `v0.7.0` or `v0.7.0-beta.1`. The tag must match the checked-in `VERSION` value for that tagged commit. | Yes |\n\n### When to use it\n\nUse backfill in specific repair scenarios such as:\n\n- The GitHub Release exists, but the expected GHCR release tags were not attached.\n- A stable release was approved earlier, and you need to restore `stable`, version tags, or `beta` catch-up behavior to the correct existing digest.\n- A prerelease was approved earlier, and you need to restore the `beta` alias to the already approved digest.\n- A transient runner or registry failure interrupted release publication after the candidate image had already been built successfully.\n- An older approved release predates the current metadata-bundle flow, and you need to reconstruct the release assets without rebuilding the runtime image.\n\nDo not use backfill when you want to ship a new candidate commit. In that case, go back to [Build Docker Image](../build-docker-image/) and then [Promote Docker Image](../promote-docker-image/).\n\n### Tag requirements\n\nThe release tag can be either a stable tag such as `v0.7.0` or a prerelease tag such as `vX.Y.Z-beta.N`, as long as it matches the checked-in base `VERSION` for that release commit.\n\nWhen an older release does not have the new metadata bundle yet, backfill may create a local attested OCI export from the tagged source to recover SBOM and provenance files. That export is used only to publish the missing metadata bundle; the runtime image digest being promoted does not change.\n\nUse backfill only for already approved releases. It is not an alternate way to publish a new image.\n\n## Clean Up Docker Package Versions\n\nGitHub Actions displays the retention workflow as `Maintenance: Clean Up Docker Package Versions`.\n\n### What it does\n\nThis workflow removes disposable GHCR history while preserving artifacts that are still in use.\n\nIt:\n\n- deletes unprotected preview package versions\n- prunes stale metadata and Cosign signature artifacts\n- removes unreferenced untagged package versions\n- preserves release-tagged versions, protected channel aliases, and graph-referenced child manifests\n\n### Required input\n\nThis workflow has no manual inputs.\n\nIt runs automatically after successful preview publication, on a schedule, or manually when you want to force a cleanup pass.\n\n### When to use it\n\nUse cleanup in specific maintenance scenarios such as:\n\n- Preview publishing has created many old `sha-\u003cfull-commit-sha\u003e` versions that are no longer needed.\n- GHCR package pages have accumulated stale signature or metadata artifacts from deleted image digests.\n- You want to verify that retention behavior is working after changes to release-tagging or cleanup logic.\n- You want an immediate cleanup run instead of waiting for the next scheduled pass.\n\nDo not use cleanup to repair a missing release tag or channel alias. Use `Maintenance: Backfill Docker Release Tags` for that.\n\n### What cleanup preserves\n\nThis workflow periodically deletes unprotected preview and unreferenced GitHub Container Registry versions while preserving:\n\n- release-tagged versions.\n- `stable`, `beta`, `test`, and stable minor-series tags.\n\nThe moving `test` tag is protected like the other channel aliases.\nImmutable `sha-\u003cfull-commit-sha\u003e` preview tags are deleted when they are no longer protected by another retained tag.\nUntagged child manifests referenced by retained multi-platform indexes are protected before stale untagged versions are deleted.\nThe cleanup also prunes stale `ghcr.io/\u003cowner\u003e/sambee-signatures` metadata and Cosign signature tags after their corresponding `sambee` image digest is no longer retained.\nThe same reference-aware untagged cleanup runs for `sambee-signatures`, where it keeps Cosign signature bundle children referenced by retained signature indexes.\n\nThat keeps the `test` channel usable while aggressively removing disposable preview history.\n\n## Cleanup Rules\n\nUse this quick reference when deciding what the cleanup workflow will keep versus delete.\n\n| If a package version is... | Cleanup action |\n|---|---|\n| Tagged with a release tag, whether stable or prerelease | Keep |\n| Tagged with a protected channel or series tag such as `stable`, `beta`, `test`, or `0.7` | Keep |\n| Tagged only with an immutable preview tag such as `sha-\u003cfull-commit-sha\u003e` | Delete |\n| Untagged but still referenced by a retained multi-platform image index | Keep |\n| Untagged and not referenced by any retained index | Delete |\n| A signature or metadata artifact for a retained image digest | Keep |\n| A signature or metadata artifact for a deleted image digest | Delete |\n\nThere is no retention count anymore. The workflow deletes every package version that is not protected by tags or by graph references.\n\n## Examples\n\n- `ghcr.io/\u003cowner\u003e/sambee:test` stays because `test` is a protected channel tag.\n- `ghcr.io/\u003cowner\u003e/sambee:sha-\u003cfull-commit-sha\u003e` is deleted if that digest is not also kept by another protected tag.\n- An untagged platform manifest stays if a retained multi-platform index still points to it.\n- A stale `ghcr.io/\u003cowner\u003e/sambee-signatures` artifact is deleted after its corresponding image digest is no longer retained.\n\n## Boundaries\n\n- Do not publish a replacement runtime image in backfill. Recovery should point tags back at an existing digest.\n- Do not treat immutable `sha-\u003cfull-commit-sha\u003e` preview tags as permanent history. The cleanup workflow is expected to prune them.\n- Do not use moving tags such as `stable`, `beta`, or `test` as the only source of deployment truth when a digest is available.\n\nIf you are starting from a new candidate commit rather than repairing an existing release path, go back to [Build Docker Image](../build-docker-image/) or [Promote Docker Image](../promote-docker-image/).\n", "0.9": "+++\ntitle = \"Docker Backfill And Cleanup\"\n+++\n\nThis is the maintenance page for the Docker release flow.\n\nUse these maintenance workflows when you need to repair tags, backfill an older approved release, or keep preview history under control.\n\n## Summary\n\nUse this page when you are not publishing a new Docker image, but instead need to maintain existing release artifacts in GitHub Container Registry.\n\n| Workflow | What it does | Required input | Use it when... |\n|---|---|---|---|\n| `Maintenance: Backfill Docker Release Tags` | Reattaches release tags and channel aliases to an already approved digest and republishes missing metadata bundle assets when needed. | One existing Git tag in release form, such as `v0.7.0` or `v0.7.0-beta.1`. | A release already exists, but its GHCR tags or release assets are missing, wrong, or need to be reconstructed without building a new image. |\n| `Maintenance: Clean Up Docker Package Versions` | Deletes unprotected preview versions, stale signature artifacts, and unreferenced untagged GHCR package versions. | None. | Preview history and dangling GHCR artifacts have accumulated and you want the repository cleaned up without touching protected release artifacts. |\n\n## Backfill Docker Release Tags\n\nGitHub Actions displays the recovery workflow as `Maintenance: Backfill Docker Release Tags`.\n\n### What it does\n\nUse it to repair or reconstruct the publish side of an already approved Docker release without publishing a new runtime image.\n\nThe workflow:\n\n- resolves the digest that already belongs to the approved release\n- verifies image metadata\n- verifies the preview-built metadata bundle, generating and publishing it first if an older release does not have one yet\n- reapplies the expected release tags to that same digest\n- updates channel aliases with the same semver rules as normal promotion\n- uploads the metadata bundle files to the GitHub Release as convenience assets\n\nFor stable releases, that means backfill also moves `beta` forward unless `beta` already points to the same digest or to a higher semver release line.\n\n### Required input\n\nThe workflow takes one manual input:\n\n| Input | What it means | Required |\n|---|---|---|\n| `release_tag` | An existing immutable Git tag for the approved release, for example `v0.7.0` or `v0.7.0-beta.1`. The tag must match the checked-in `VERSION` value for that tagged commit. | Yes |\n\n### When to use it\n\nUse backfill in specific repair scenarios such as:\n\n- The GitHub Release exists, but the expected GHCR release tags were not attached.\n- A stable release was approved earlier, and you need to restore `stable`, version tags, or `beta` catch-up behavior to the correct existing digest.\n- A prerelease was approved earlier, and you need to restore the `beta` alias to the already approved digest.\n- A transient runner or registry failure interrupted release publication after the candidate image had already been built successfully.\n- An older approved release predates the current metadata-bundle flow, and you need to reconstruct the release assets without rebuilding the runtime image.\n\nDo not use backfill when you want to ship a new candidate commit. In that case, go back to [Build Docker Image](../build-docker-image/) and then [Promote Docker Image](../promote-docker-image/).\n\n### Tag requirements\n\nThe release tag can be either a stable tag such as `v0.7.0` or a prerelease tag such as `vX.Y.Z-beta.N`, as long as it matches the checked-in base `VERSION` for that release commit.\n\nWhen an older release does not have the new metadata bundle yet, backfill may create a local attested OCI export from the tagged source to recover SBOM and provenance files. That export is used only to publish the missing metadata bundle; the runtime image digest being promoted does not change.\n\nUse backfill only for already approved releases. It is not an alternate way to publish a new image.\n\n## Clean Up Docker Package Versions\n\nGitHub Actions displays the retention workflow as `Maintenance: Clean Up Docker Package Versions`.\n\n### What it does\n\nThis workflow removes disposable GHCR history while preserving artifacts that are still in use.\n\nIt:\n\n- deletes unprotected preview package versions\n- prunes stale metadata and Cosign signature artifacts\n- removes unreferenced untagged package versions\n- preserves release-tagged versions, protected channel aliases, and graph-referenced child manifests\n\n### Required input\n\nThis workflow has no manual inputs.\n\nIt runs automatically after successful preview publication, on a schedule, or manually when you want to force a cleanup pass.\n\n### When to use it\n\nUse cleanup in specific maintenance scenarios such as:\n\n- Preview publishing has created many old `sha-\u003cfull-commit-sha\u003e` versions that are no longer needed.\n- GHCR package pages have accumulated stale signature or metadata artifacts from deleted image digests.\n- You want to verify that retention behavior is working after changes to release-tagging or cleanup logic.\n- You want an immediate cleanup run instead of waiting for the next scheduled pass.\n\nDo not use cleanup to repair a missing release tag or channel alias. Use `Maintenance: Backfill Docker Release Tags` for that.\n\n### What cleanup preserves\n\nThis workflow periodically deletes unprotected preview and unreferenced GitHub Container Registry versions while preserving:\n\n- release-tagged versions.\n- `stable`, `beta`, `test`, and stable minor-series tags.\n\nThe moving `test` tag is protected like the other channel aliases.\nImmutable `sha-\u003cfull-commit-sha\u003e` preview tags are deleted when they are no longer protected by another retained tag.\nUntagged child manifests referenced by retained multi-platform indexes are protected before stale untagged versions are deleted.\nThe cleanup also prunes stale `ghcr.io/\u003cowner\u003e/sambee-signatures` metadata and Cosign signature tags after their corresponding `sambee` image digest is no longer retained.\nThe same reference-aware untagged cleanup runs for `sambee-signatures`, where it keeps Cosign signature bundle children referenced by retained signature indexes.\n\nThat keeps the `test` channel usable while aggressively removing disposable preview history.\n\n## Cleanup Rules\n\nUse this quick reference when deciding what the cleanup workflow will keep versus delete.\n\n| If a package version is... | Cleanup action |\n|---|---|\n| Tagged with a release tag, whether stable or prerelease | Keep |\n| Tagged with a protected channel or series tag such as `stable`, `beta`, `test`, or `0.7` | Keep |\n| Tagged only with an immutable preview tag such as `sha-\u003cfull-commit-sha\u003e` | Delete |\n| Untagged but still referenced by a retained multi-platform image index | Keep |\n| Untagged and not referenced by any retained index | Delete |\n| A signature or metadata artifact for a retained image digest | Keep |\n| A signature or metadata artifact for a deleted image digest | Delete |\n\nThere is no retention count anymore. The workflow deletes every package version that is not protected by tags or by graph references.\n\n## Examples\n\n- `ghcr.io/\u003cowner\u003e/sambee:test` stays because `test` is a protected channel tag.\n- `ghcr.io/\u003cowner\u003e/sambee:sha-\u003cfull-commit-sha\u003e` is deleted if that digest is not also kept by another protected tag.\n- An untagged platform manifest stays if a retained multi-platform index still points to it.\n- A stale `ghcr.io/\u003cowner\u003e/sambee-signatures` artifact is deleted after its corresponding image digest is no longer retained.\n\n## Boundaries\n\n- Do not publish a replacement runtime image in backfill. Recovery should point tags back at an existing digest.\n- Do not treat immutable `sha-\u003cfull-commit-sha\u003e` preview tags as permanent history. The cleanup workflow is expected to prune them.\n- Do not use moving tags such as `stable`, `beta`, or `test` as the only source of deployment truth when a digest is available.\n\nIf you are starting from a new candidate commit rather than repairing an existing release path, go back to [Build Docker Image](../build-docker-image/) or [Promote Docker Image](../promote-docker-image/).\n", "1.0": "+++\ntitle = \"Docker Backfill And Cleanup\"\n+++\n\nThis is the maintenance page for the Docker release flow.\n\nUse these maintenance workflows when you need to repair tags, backfill an older approved release, or keep preview history under control.\n\n## Summary\n\nUse this page when you are not publishing a new Docker image, but instead need to maintain existing release artifacts in GitHub Container Registry.\n\n| Workflow | What it does | Required input | Use it when... |\n|---|---|---|---|\n| `Maintenance: Backfill Docker Release Tags` | Reattaches release tags and channel aliases to an already approved digest and republishes missing metadata bundle assets when needed. | One existing Git tag in release form, such as `v0.7.0` or `v0.7.0-beta.1`. | A release already exists, but its GHCR tags or release assets are missing, wrong, or need to be reconstructed without building a new image. |\n| `Maintenance: Clean Up Docker Package Versions` | Deletes unprotected preview versions, stale signature artifacts, and unreferenced untagged GHCR package versions. | None. | Preview history and dangling GHCR artifacts have accumulated and you want the repository cleaned up without touching protected release artifacts. |\n\n## Backfill Docker Release Tags\n\nGitHub Actions displays the recovery workflow as `Maintenance: Backfill Docker Release Tags`.\n\n### What it does\n\nUse it to repair or reconstruct the publish side of an already approved Docker release without publishing a new runtime image.\n\nThe workflow:\n\n- resolves the digest that already belongs to the approved release\n- verifies image metadata\n- verifies the preview-built metadata bundle, generating and publishing it first if an older release does not have one yet\n- reapplies the expected release tags to that same digest\n- updates channel aliases with the same semver rules as normal promotion\n- uploads the metadata bundle files to the GitHub Release as convenience assets\n\nFor stable releases, that means backfill also moves `beta` forward unless `beta` already points to the same digest or to a higher semver release line.\n\n### Required input\n\nThe workflow takes one manual input:\n\n| Input | What it means | Required |\n|---|---|---|\n| `release_tag` | An existing immutable Git tag for the approved release, for example `v0.7.0` or `v0.7.0-beta.1`. The tag must match the checked-in `VERSION` value for that tagged commit. | Yes |\n\n### When to use it\n\nUse backfill in specific repair scenarios such as:\n\n- The GitHub Release exists, but the expected GHCR release tags were not attached.\n- A stable release was approved earlier, and you need to restore `stable`, version tags, or `beta` catch-up behavior to the correct existing digest.\n- A prerelease was approved earlier, and you need to restore the `beta` alias to the already approved digest.\n- A transient runner or registry failure interrupted release publication after the candidate image had already been built successfully.\n- An older approved release predates the current metadata-bundle flow, and you need to reconstruct the release assets without rebuilding the runtime image.\n\nDo not use backfill when you want to ship a new candidate commit. In that case, go back to [Build Docker Image](../build-docker-image/) and then [Promote Docker Image](../promote-docker-image/).\n\n### Tag requirements\n\nThe release tag can be either a stable tag such as `v0.7.0` or a prerelease tag such as `vX.Y.Z-beta.N`, as long as it matches the checked-in base `VERSION` for that release commit.\n\nWhen an older release does not have the new metadata bundle yet, backfill may create a local attested OCI export from the tagged source to recover SBOM and provenance files. That export is used only to publish the missing metadata bundle; the runtime image digest being promoted does not change.\n\nUse backfill only for already approved releases. It is not an alternate way to publish a new image.\n\n## Clean Up Docker Package Versions\n\nGitHub Actions displays the retention workflow as `Maintenance: Clean Up Docker Package Versions`.\n\n### What it does\n\nThis workflow removes disposable GHCR history while preserving artifacts that are still in use.\n\nIt:\n\n- deletes unprotected preview package versions\n- prunes stale metadata and Cosign signature artifacts\n- removes unreferenced untagged package versions\n- preserves release-tagged versions, protected channel aliases, and graph-referenced child manifests\n\n### Required input\n\nThis workflow has no manual inputs.\n\nIt runs automatically after successful preview publication, on a schedule, or manually when you want to force a cleanup pass.\n\n### When to use it\n\nUse cleanup in specific maintenance scenarios such as:\n\n- Preview publishing has created many old `sha-\u003cfull-commit-sha\u003e` versions that are no longer needed.\n- GHCR package pages have accumulated stale signature or metadata artifacts from deleted image digests.\n- You want to verify that retention behavior is working after changes to release-tagging or cleanup logic.\n- You want an immediate cleanup run instead of waiting for the next scheduled pass.\n\nDo not use cleanup to repair a missing release tag or channel alias. Use `Maintenance: Backfill Docker Release Tags` for that.\n\n### What cleanup preserves\n\nThis workflow periodically deletes unprotected preview and unreferenced GitHub Container Registry versions while preserving:\n\n- release-tagged versions.\n- `stable`, `beta`, `test`, and stable minor-series tags.\n\nThe moving `test` tag is protected like the other channel aliases.\nImmutable `sha-\u003cfull-commit-sha\u003e` preview tags are deleted when they are no longer protected by another retained tag.\nUntagged child manifests referenced by retained multi-platform indexes are protected before stale untagged versions are deleted.\nThe cleanup also prunes stale `ghcr.io/\u003cowner\u003e/sambee-signatures` metadata and Cosign signature tags after their corresponding `sambee` image digest is no longer retained.\nThe same reference-aware untagged cleanup runs for `sambee-signatures`, where it keeps Cosign signature bundle children referenced by retained signature indexes.\n\nThat keeps the `test` channel usable while aggressively removing disposable preview history.\n\n## Cleanup Rules\n\nUse this quick reference when deciding what the cleanup workflow will keep versus delete.\n\n| If a package version is... | Cleanup action |\n|---|---|\n| Tagged with a release tag, whether stable or prerelease | Keep |\n| Tagged with a protected channel or series tag such as `stable`, `beta`, `test`, or `0.7` | Keep |\n| Tagged only with an immutable preview tag such as `sha-\u003cfull-commit-sha\u003e` | Delete |\n| Untagged but still referenced by a retained multi-platform image index | Keep |\n| Untagged and not referenced by any retained index | Delete |\n| A signature or metadata artifact for a retained image digest | Keep |\n| A signature or metadata artifact for a deleted image digest | Delete |\n\nThere is no retention count anymore. The workflow deletes every package version that is not protected by tags or by graph references.\n\n## Examples\n\n- `ghcr.io/\u003cowner\u003e/sambee:test` stays because `test` is a protected channel tag.\n- `ghcr.io/\u003cowner\u003e/sambee:sha-\u003cfull-commit-sha\u003e` is deleted if that digest is not also kept by another protected tag.\n- An untagged platform manifest stays if a retained multi-platform index still points to it.\n- A stale `ghcr.io/\u003cowner\u003e/sambee-signatures` artifact is deleted after its corresponding image digest is no longer retained.\n\n## Boundaries\n\n- Do not publish a replacement runtime image in backfill. Recovery should point tags back at an existing digest.\n- Do not treat immutable `sha-\u003cfull-commit-sha\u003e` preview tags as permanent history. The cleanup workflow is expected to prune them.\n- Do not use moving tags such as `stable`, `beta`, or `test` as the only source of deployment truth when a digest is available.\n\nIf you are starting from a new candidate commit rather than repairing an existing release path, go back to [Build Docker Image](../build-docker-image/) or [Promote Docker Image](../promote-docker-image/).\n", "2.0": "+++\ntitle = \"Docker Backfill And Cleanup\"\n+++\n\nThis is the maintenance page for the Docker release flow.\n\nUse these maintenance workflows when you need to repair tags, backfill an older approved release, or keep preview history under control.\n\n## Summary\n\nUse this page when you are not publishing a new Docker image, but instead need to maintain existing release artifacts in GitHub Container Registry.\n\n| Workflow | What it does | Required input | Use it when... |\n|---|---|---|---|\n| `Maintenance: Backfill Docker Release Tags` | Reattaches release tags and channel aliases to an already approved digest and republishes missing metadata bundle assets when needed. | One existing Git tag in release form, such as `v0.7.0` or `v0.7.0-beta.1`. | A release already exists, but its GHCR tags or release assets are missing, wrong, or need to be reconstructed without building a new image. |\n| `Maintenance: Clean Up Docker Package Versions` | Deletes unprotected preview versions, stale signature artifacts, and unreferenced untagged GHCR package versions. | None. | Preview history and dangling GHCR artifacts have accumulated and you want the repository cleaned up without touching protected release artifacts. |\n\n## Backfill Docker Release Tags\n\nGitHub Actions displays the recovery workflow as `Maintenance: Backfill Docker Release Tags`.\n\n### What it does\n\nUse it to repair or reconstruct the publish side of an already approved Docker release without publishing a new runtime image.\n\nThe workflow:\n\n- resolves the digest that already belongs to the approved release\n- verifies image metadata\n- verifies the preview-built metadata bundle, generating and publishing it first if an older release does not have one yet\n- reapplies the expected release tags to that same digest\n- updates channel aliases with the same semver rules as normal promotion\n- uploads the metadata bundle files to the GitHub Release as convenience assets\n\nFor stable releases, that means backfill also moves `beta` forward unless `beta` already points to the same digest or to a higher semver release line.\n\n### Required input\n\nThe workflow takes one manual input:\n\n| Input | What it means | Required |\n|---|---|---|\n| `release_tag` | An existing immutable Git tag for the approved release, for example `v0.7.0` or `v0.7.0-beta.1`. The tag must match the checked-in `VERSION` value for that tagged commit. | Yes |\n\n### When to use it\n\nUse backfill in specific repair scenarios such as:\n\n- The GitHub Release exists, but the expected GHCR release tags were not attached.\n- A stable release was approved earlier, and you need to restore `stable`, version tags, or `beta` catch-up behavior to the correct existing digest.\n- A prerelease was approved earlier, and you need to restore the `beta` alias to the already approved digest.\n- A transient runner or registry failure interrupted release publication after the candidate image had already been built successfully.\n- An older approved release predates the current metadata-bundle flow, and you need to reconstruct the release assets without rebuilding the runtime image.\n\nDo not use backfill when you want to ship a new candidate commit. In that case, go back to [Build Docker Image](../build-docker-image/) and then [Promote Docker Image](../promote-docker-image/).\n\n### Tag requirements\n\nThe release tag can be either a stable tag such as `v0.7.0` or a prerelease tag such as `vX.Y.Z-beta.N`, as long as it matches the checked-in base `VERSION` for that release commit.\n\nWhen an older release does not have the new metadata bundle yet, backfill may create a local attested OCI export from the tagged source to recover SBOM and provenance files. That export is used only to publish the missing metadata bundle; the runtime image digest being promoted does not change.\n\nUse backfill only for already approved releases. It is not an alternate way to publish a new image.\n\n## Clean Up Docker Package Versions\n\nGitHub Actions displays the retention workflow as `Maintenance: Clean Up Docker Package Versions`.\n\n### What it does\n\nThis workflow removes disposable GHCR history while preserving artifacts that are still in use.\n\nIt:\n\n- deletes unprotected preview package versions\n- prunes stale metadata and Cosign signature artifacts\n- removes unreferenced untagged package versions\n- preserves release-tagged versions, protected channel aliases, and graph-referenced child manifests\n\n### Required input\n\nThis workflow has no manual inputs.\n\nIt runs automatically after successful preview publication, on a schedule, or manually when you want to force a cleanup pass.\n\n### When to use it\n\nUse cleanup in specific maintenance scenarios such as:\n\n- Preview publishing has created many old `sha-\u003cfull-commit-sha\u003e` versions that are no longer needed.\n- GHCR package pages have accumulated stale signature or metadata artifacts from deleted image digests.\n- You want to verify that retention behavior is working after changes to release-tagging or cleanup logic.\n- You want an immediate cleanup run instead of waiting for the next scheduled pass.\n\nDo not use cleanup to repair a missing release tag or channel alias. Use `Maintenance: Backfill Docker Release Tags` for that.\n\n### What cleanup preserves\n\nThis workflow periodically deletes unprotected preview and unreferenced GitHub Container Registry versions while preserving:\n\n- release-tagged versions.\n- `stable`, `beta`, `test`, and stable minor-series tags.\n\nThe moving `test` tag is protected like the other channel aliases.\nImmutable `sha-\u003cfull-commit-sha\u003e` preview tags are deleted when they are no longer protected by another retained tag.\nUntagged child manifests referenced by retained multi-platform indexes are protected before stale untagged versions are deleted.\nThe cleanup also prunes stale `ghcr.io/\u003cowner\u003e/sambee-signatures` metadata and Cosign signature tags after their corresponding `sambee` image digest is no longer retained.\nThe same reference-aware untagged cleanup runs for `sambee-signatures`, where it keeps Cosign signature bundle children referenced by retained signature indexes.\n\nThat keeps the `test` channel usable while aggressively removing disposable preview history.\n\n## Cleanup Rules\n\nUse this quick reference when deciding what the cleanup workflow will keep versus delete.\n\n| If a package version is... | Cleanup action |\n|---|---|\n| Tagged with a release tag, whether stable or prerelease | Keep |\n| Tagged with a protected channel or series tag such as `stable`, `beta`, `test`, or `0.7` | Keep |\n| Tagged only with an immutable preview tag such as `sha-\u003cfull-commit-sha\u003e` | Delete |\n| Untagged but still referenced by a retained multi-platform image index | Keep |\n| Untagged and not referenced by any retained index | Delete |\n| A signature or metadata artifact for a retained image digest | Keep |\n| A signature or metadata artifact for a deleted image digest | Delete |\n\nThere is no retention count anymore. The workflow deletes every package version that is not protected by tags or by graph references.\n\n## Examples\n\n- `ghcr.io/\u003cowner\u003e/sambee:test` stays because `test` is a protected channel tag.\n- `ghcr.io/\u003cowner\u003e/sambee:sha-\u003cfull-commit-sha\u003e` is deleted if that digest is not also kept by another protected tag.\n- An untagged platform manifest stays if a retained multi-platform index still points to it.\n- A stale `ghcr.io/\u003cowner\u003e/sambee-signatures` artifact is deleted after its corresponding image digest is no longer retained.\n\n## Boundaries\n\n- Do not publish a replacement runtime image in backfill. Recovery should point tags back at an existing digest.\n- Do not treat immutable `sha-\u003cfull-commit-sha\u003e` preview tags as permanent history. The cleanup workflow is expected to prune them.\n- Do not use moving tags such as `stable`, `beta`, or `test` as the only source of deployment truth when a digest is available.\n\nIf you are starting from a new candidate commit rather than repairing an existing release path, go back to [Build Docker Image](../build-docker-image/) or [Promote Docker Image](../promote-docker-image/).\n"}, "page_contents": {"0.7": "+++\ntitle = \"Docker Backfill And Cleanup\"\n+++\n\nThis is the maintenance page for the Docker release flow.\n\nUse these maintenance workflows when you need to repair tags, backfill an older approved release, or keep preview history under control.\n\n## Summary\n\nUse this page when you are not publishing a new Docker image, but instead need to maintain existing release artifacts in GitHub Container Registry.\n\n| Workflow | What it does | Required input | Use it when... |\n|---|---|---|---|\n| `Maintenance: Backfill Docker Release Tags` | Reattaches release tags and channel aliases to an already approved digest and republishes missing metadata bundle assets when needed. | One existing Git tag in release form, such as `v0.7.0` or `v0.7.0-beta.1`. | A release already exists, but its GHCR tags or release assets are missing, wrong, or need to be reconstructed without building a new image. |\n| `Maintenance: Clean Up Docker Package Versions` | Deletes unprotected preview versions, stale signature artifacts, and unreferenced untagged GHCR package versions. | None. | Preview history and dangling GHCR artifacts have accumulated and you want the repository cleaned up without touching protected release artifacts. |\n\n## Backfill Docker Release Tags\n\nGitHub Actions displays the recovery workflow as `Maintenance: Backfill Docker Release Tags`.\n\n### What it does\n\nUse it to repair or reconstruct the publish side of an already approved Docker release without publishing a new runtime image.\n\nThe workflow:\n\n- resolves the digest that already belongs to the approved release\n- verifies image metadata\n- verifies the preview-built metadata bundle, generating and publishing it first if an older release does not have one yet\n- reapplies the expected release tags to that same digest\n- updates channel aliases with the same semver rules as normal promotion\n- uploads the metadata bundle files to the GitHub Release as convenience assets\n\nFor stable releases, that means backfill also moves `beta` forward unless `beta` already points to the same digest or to a higher semver release line.\n\n### Required input\n\nThe workflow takes one manual input:\n\n| Input | What it means | Required |\n|---|---|---|\n| `release_tag` | An existing immutable Git tag for the approved release, for example `v0.7.0` or `v0.7.0-beta.1`. The tag must match the checked-in `VERSION` value for that tagged commit. | Yes |\n\n### When to use it\n\nUse backfill in specific repair scenarios such as:\n\n- The GitHub Release exists, but the expected GHCR release tags were not attached.\n- A stable release was approved earlier, and you need to restore `stable`, version tags, or `beta` catch-up behavior to the correct existing digest.\n- A prerelease was approved earlier, and you need to restore the `beta` alias to the already approved digest.\n- A transient runner or registry failure interrupted release publication after the candidate image had already been built successfully.\n- An older approved release predates the current metadata-bundle flow, and you need to reconstruct the release assets without rebuilding the runtime image.\n\nDo not use backfill when you want to ship a new candidate commit. In that case, go back to [Build Docker Image](../build-docker-image/) and then [Promote Docker Image](../promote-docker-image/).\n\n### Tag requirements\n\nThe release tag can be either a stable tag such as `v0.7.0` or a prerelease tag such as `vX.Y.Z-beta.N`, as long as it matches the checked-in base `VERSION` for that release commit.\n\nWhen an older release does not have the new metadata bundle yet, backfill may create a local attested OCI export from the tagged source to recover SBOM and provenance files. That export is used only to publish the missing metadata bundle; the runtime image digest being promoted does not change.\n\nUse backfill only for already approved releases. It is not an alternate way to publish a new image.\n\n## Clean Up Docker Package Versions\n\nGitHub Actions displays the retention workflow as `Maintenance: Clean Up Docker Package Versions`.\n\n### What it does\n\nThis workflow removes disposable GHCR history while preserving artifacts that are still in use.\n\nIt:\n\n- deletes unprotected preview package versions\n- prunes stale metadata and Cosign signature artifacts\n- removes unreferenced untagged package versions\n- preserves release-tagged versions, protected channel aliases, and graph-referenced child manifests\n\n### Required input\n\nThis workflow has no manual inputs.\n\nIt runs automatically after successful preview publication, on a schedule, or manually when you want to force a cleanup pass.\n\n### When to use it\n\nUse cleanup in specific maintenance scenarios such as:\n\n- Preview publishing has created many old `sha-\u003cfull-commit-sha\u003e` versions that are no longer needed.\n- GHCR package pages have accumulated stale signature or metadata artifacts from deleted image digests.\n- You want to verify that retention behavior is working after changes to release-tagging or cleanup logic.\n- You want an immediate cleanup run instead of waiting for the next scheduled pass.\n\nDo not use cleanup to repair a missing release tag or channel alias. Use `Maintenance: Backfill Docker Release Tags` for that.\n\n### What cleanup preserves\n\nThis workflow periodically deletes unprotected preview and unreferenced GitHub Container Registry versions while preserving:\n\n- release-tagged versions.\n- `stable`, `beta`, `test`, and stable minor-series tags.\n\nThe moving `test` tag is protected like the other channel aliases.\nImmutable `sha-\u003cfull-commit-sha\u003e` preview tags are deleted when they are no longer protected by another retained tag.\nUntagged child manifests referenced by retained multi-platform indexes are protected before stale untagged versions are deleted.\nThe cleanup also prunes stale `ghcr.io/\u003cowner\u003e/sambee-signatures` metadata and Cosign signature tags after their corresponding `sambee` image digest is no longer retained.\nThe same reference-aware untagged cleanup runs for `sambee-signatures`, where it keeps Cosign signature bundle children referenced by retained signature indexes.\n\nThat keeps the `test` channel usable while aggressively removing disposable preview history.\n\n## Cleanup Rules\n\nUse this quick reference when deciding what the cleanup workflow will keep versus delete.\n\n| If a package version is... | Cleanup action |\n|---|---|\n| Tagged with a release tag, whether stable or prerelease | Keep |\n| Tagged with a protected channel or series tag such as `stable`, `beta`, `test`, or `0.7` | Keep |\n| Tagged only with an immutable preview tag such as `sha-\u003cfull-commit-sha\u003e` | Delete |\n| Untagged but still referenced by a retained multi-platform image index | Keep |\n| Untagged and not referenced by any retained index | Delete |\n| A signature or metadata artifact for a retained image digest | Keep |\n| A signature or metadata artifact for a deleted image digest | Delete |\n\nThere is no retention count anymore. The workflow deletes every package version that is not protected by tags or by graph references.\n\n## Examples\n\n- `ghcr.io/\u003cowner\u003e/sambee:test` stays because `test` is a protected channel tag.\n- `ghcr.io/\u003cowner\u003e/sambee:sha-\u003cfull-commit-sha\u003e` is deleted if that digest is not also kept by another protected tag.\n- An untagged platform manifest stays if a retained multi-platform index still points to it.\n- A stale `ghcr.io/\u003cowner\u003e/sambee-signatures` artifact is deleted after its corresponding image digest is no longer retained.\n\n## Boundaries\n\n- Do not publish a replacement runtime image in backfill. Recovery should point tags back at an existing digest.\n- Do not treat immutable `sha-\u003cfull-commit-sha\u003e` preview tags as permanent history. The cleanup workflow is expected to prune them.\n- Do not use moving tags such as `stable`, `beta`, or `test` as the only source of deployment truth when a digest is available.\n\nIf you are starting from a new candidate commit rather than repairing an existing release path, go back to [Build Docker Image](../build-docker-image/) or [Promote Docker Image](../promote-docker-image/).\n", "0.8": "+++\ntitle = \"Docker Backfill And Cleanup\"\n+++\n\nThis is the maintenance page for the Docker release flow.\n\nUse these maintenance workflows when you need to repair tags, backfill an older approved release, or keep preview history under control.\n\n## Summary\n\nUse this page when you are not publishing a new Docker image, but instead need to maintain existing release artifacts in GitHub Container Registry.\n\n| Workflow | What it does | Required input | Use it when... |\n|---|---|---|---|\n| `Maintenance: Backfill Docker Release Tags` | Reattaches release tags and channel aliases to an already approved digest and republishes missing metadata bundle assets when needed. | One existing Git tag in release form, such as `v0.7.0` or `v0.7.0-beta.1`. | A release already exists, but its GHCR tags or release assets are missing, wrong, or need to be reconstructed without building a new image. |\n| `Maintenance: Clean Up Docker Package Versions` | Deletes unprotected preview versions, stale signature artifacts, and unreferenced untagged GHCR package versions. | None. | Preview history and dangling GHCR artifacts have accumulated and you want the repository cleaned up without touching protected release artifacts. |\n\n## Backfill Docker Release Tags\n\nGitHub Actions displays the recovery workflow as `Maintenance: Backfill Docker Release Tags`.\n\n### What it does\n\nUse it to repair or reconstruct the publish side of an already approved Docker release without publishing a new runtime image.\n\nThe workflow:\n\n- resolves the digest that already belongs to the approved release\n- verifies image metadata\n- verifies the preview-built metadata bundle, generating and publishing it first if an older release does not have one yet\n- reapplies the expected release tags to that same digest\n- updates channel aliases with the same semver rules as normal promotion\n- uploads the metadata bundle files to the GitHub Release as convenience assets\n\nFor stable releases, that means backfill also moves `beta` forward unless `beta` already points to the same digest or to a higher semver release line.\n\n### Required input\n\nThe workflow takes one manual input:\n\n| Input | What it means | Required |\n|---|---|---|\n| `release_tag` | An existing immutable Git tag for the approved release, for example `v0.7.0` or `v0.7.0-beta.1`. The tag must match the checked-in `VERSION` value for that tagged commit. | Yes |\n\n### When to use it\n\nUse backfill in specific repair scenarios such as:\n\n- The GitHub Release exists, but the expected GHCR release tags were not attached.\n- A stable release was approved earlier, and you need to restore `stable`, version tags, or `beta` catch-up behavior to the correct existing digest.\n- A prerelease was approved earlier, and you need to restore the `beta` alias to the already approved digest.\n- A transient runner or registry failure interrupted release publication after the candidate image had already been built successfully.\n- An older approved release predates the current metadata-bundle flow, and you need to reconstruct the release assets without rebuilding the runtime image.\n\nDo not use backfill when you want to ship a new candidate commit. In that case, go back to [Build Docker Image](../build-docker-image/) and then [Promote Docker Image](../promote-docker-image/).\n\n### Tag requirements\n\nThe release tag can be either a stable tag such as `v0.7.0` or a prerelease tag such as `vX.Y.Z-beta.N`, as long as it matches the checked-in base `VERSION` for that release commit.\n\nWhen an older release does not have the new metadata bundle yet, backfill may create a local attested OCI export from the tagged source to recover SBOM and provenance files. That export is used only to publish the missing metadata bundle; the runtime image digest being promoted does not change.\n\nUse backfill only for already approved releases. It is not an alternate way to publish a new image.\n\n## Clean Up Docker Package Versions\n\nGitHub Actions displays the retention workflow as `Maintenance: Clean Up Docker Package Versions`.\n\n### What it does\n\nThis workflow removes disposable GHCR history while preserving artifacts that are still in use.\n\nIt:\n\n- deletes unprotected preview package versions\n- prunes stale metadata and Cosign signature artifacts\n- removes unreferenced untagged package versions\n- preserves release-tagged versions, protected channel aliases, and graph-referenced child manifests\n\n### Required input\n\nThis workflow has no manual inputs.\n\nIt runs automatically after successful preview publication, on a schedule, or manually when you want to force a cleanup pass.\n\n### When to use it\n\nUse cleanup in specific maintenance scenarios such as:\n\n- Preview publishing has created many old `sha-\u003cfull-commit-sha\u003e` versions that are no longer needed.\n- GHCR package pages have accumulated stale signature or metadata artifacts from deleted image digests.\n- You want to verify that retention behavior is working after changes to release-tagging or cleanup logic.\n- You want an immediate cleanup run instead of waiting for the next scheduled pass.\n\nDo not use cleanup to repair a missing release tag or channel alias. Use `Maintenance: Backfill Docker Release Tags` for that.\n\n### What cleanup preserves\n\nThis workflow periodically deletes unprotected preview and unreferenced GitHub Container Registry versions while preserving:\n\n- release-tagged versions.\n- `stable`, `beta`, `test`, and stable minor-series tags.\n\nThe moving `test` tag is protected like the other channel aliases.\nImmutable `sha-\u003cfull-commit-sha\u003e` preview tags are deleted when they are no longer protected by another retained tag.\nUntagged child manifests referenced by retained multi-platform indexes are protected before stale untagged versions are deleted.\nThe cleanup also prunes stale `ghcr.io/\u003cowner\u003e/sambee-signatures` metadata and Cosign signature tags after their corresponding `sambee` image digest is no longer retained.\nThe same reference-aware untagged cleanup runs for `sambee-signatures`, where it keeps Cosign signature bundle children referenced by retained signature indexes.\n\nThat keeps the `test` channel usable while aggressively removing disposable preview history.\n\n## Cleanup Rules\n\nUse this quick reference when deciding what the cleanup workflow will keep versus delete.\n\n| If a package version is... | Cleanup action |\n|---|---|\n| Tagged with a release tag, whether stable or prerelease | Keep |\n| Tagged with a protected channel or series tag such as `stable`, `beta`, `test`, or `0.7` | Keep |\n| Tagged only with an immutable preview tag such as `sha-\u003cfull-commit-sha\u003e` | Delete |\n| Untagged but still referenced by a retained multi-platform image index | Keep |\n| Untagged and not referenced by any retained index | Delete |\n| A signature or metadata artifact for a retained image digest | Keep |\n| A signature or metadata artifact for a deleted image digest | Delete |\n\nThere is no retention count anymore. The workflow deletes every package version that is not protected by tags or by graph references.\n\n## Examples\n\n- `ghcr.io/\u003cowner\u003e/sambee:test` stays because `test` is a protected channel tag.\n- `ghcr.io/\u003cowner\u003e/sambee:sha-\u003cfull-commit-sha\u003e` is deleted if that digest is not also kept by another protected tag.\n- An untagged platform manifest stays if a retained multi-platform index still points to it.\n- A stale `ghcr.io/\u003cowner\u003e/sambee-signatures` artifact is deleted after its corresponding image digest is no longer retained.\n\n## Boundaries\n\n- Do not publish a replacement runtime image in backfill. Recovery should point tags back at an existing digest.\n- Do not treat immutable `sha-\u003cfull-commit-sha\u003e` preview tags as permanent history. The cleanup workflow is expected to prune them.\n- Do not use moving tags such as `stable`, `beta`, or `test` as the only source of deployment truth when a digest is available.\n\nIf you are starting from a new candidate commit rather than repairing an existing release path, go back to [Build Docker Image](../build-docker-image/) or [Promote Docker Image](../promote-docker-image/).\n", "0.9": "+++\ntitle = \"Docker Backfill And Cleanup\"\n+++\n\nThis is the maintenance page for the Docker release flow.\n\nUse these maintenance workflows when you need to repair tags, backfill an older approved release, or keep preview history under control.\n\n## Summary\n\nUse this page when you are not publishing a new Docker image, but instead need to maintain existing release artifacts in GitHub Container Registry.\n\n| Workflow | What it does | Required input | Use it when... |\n|---|---|---|---|\n| `Maintenance: Backfill Docker Release Tags` | Reattaches release tags and channel aliases to an already approved digest and republishes missing metadata bundle assets when needed. | One existing Git tag in release form, such as `v0.7.0` or `v0.7.0-beta.1`. | A release already exists, but its GHCR tags or release assets are missing, wrong, or need to be reconstructed without building a new image. |\n| `Maintenance: Clean Up Docker Package Versions` | Deletes unprotected preview versions, stale signature artifacts, and unreferenced untagged GHCR package versions. | None. | Preview history and dangling GHCR artifacts have accumulated and you want the repository cleaned up without touching protected release artifacts. |\n\n## Backfill Docker Release Tags\n\nGitHub Actions displays the recovery workflow as `Maintenance: Backfill Docker Release Tags`.\n\n### What it does\n\nUse it to repair or reconstruct the publish side of an already approved Docker release without publishing a new runtime image.\n\nThe workflow:\n\n- resolves the digest that already belongs to the approved release\n- verifies image metadata\n- verifies the preview-built metadata bundle, generating and publishing it first if an older release does not have one yet\n- reapplies the expected release tags to that same digest\n- updates channel aliases with the same semver rules as normal promotion\n- uploads the metadata bundle files to the GitHub Release as convenience assets\n\nFor stable releases, that means backfill also moves `beta` forward unless `beta` already points to the same digest or to a higher semver release line.\n\n### Required input\n\nThe workflow takes one manual input:\n\n| Input | What it means | Required |\n|---|---|---|\n| `release_tag` | An existing immutable Git tag for the approved release, for example `v0.7.0` or `v0.7.0-beta.1`. The tag must match the checked-in `VERSION` value for that tagged commit. | Yes |\n\n### When to use it\n\nUse backfill in specific repair scenarios such as:\n\n- The GitHub Release exists, but the expected GHCR release tags were not attached.\n- A stable release was approved earlier, and you need to restore `stable`, version tags, or `beta` catch-up behavior to the correct existing digest.\n- A prerelease was approved earlier, and you need to restore the `beta` alias to the already approved digest.\n- A transient runner or registry failure interrupted release publication after the candidate image had already been built successfully.\n- An older approved release predates the current metadata-bundle flow, and you need to reconstruct the release assets without rebuilding the runtime image.\n\nDo not use backfill when you want to ship a new candidate commit. In that case, go back to [Build Docker Image](../build-docker-image/) and then [Promote Docker Image](../promote-docker-image/).\n\n### Tag requirements\n\nThe release tag can be either a stable tag such as `v0.7.0` or a prerelease tag such as `vX.Y.Z-beta.N`, as long as it matches the checked-in base `VERSION` for that release commit.\n\nWhen an older release does not have the new metadata bundle yet, backfill may create a local attested OCI export from the tagged source to recover SBOM and provenance files. That export is used only to publish the missing metadata bundle; the runtime image digest being promoted does not change.\n\nUse backfill only for already approved releases. It is not an alternate way to publish a new image.\n\n## Clean Up Docker Package Versions\n\nGitHub Actions displays the retention workflow as `Maintenance: Clean Up Docker Package Versions`.\n\n### What it does\n\nThis workflow removes disposable GHCR history while preserving artifacts that are still in use.\n\nIt:\n\n- deletes unprotected preview package versions\n- prunes stale metadata and Cosign signature artifacts\n- removes unreferenced untagged package versions\n- preserves release-tagged versions, protected channel aliases, and graph-referenced child manifests\n\n### Required input\n\nThis workflow has no manual inputs.\n\nIt runs automatically after successful preview publication, on a schedule, or manually when you want to force a cleanup pass.\n\n### When to use it\n\nUse cleanup in specific maintenance scenarios such as:\n\n- Preview publishing has created many old `sha-\u003cfull-commit-sha\u003e` versions that are no longer needed.\n- GHCR package pages have accumulated stale signature or metadata artifacts from deleted image digests.\n- You want to verify that retention behavior is working after changes to release-tagging or cleanup logic.\n- You want an immediate cleanup run instead of waiting for the next scheduled pass.\n\nDo not use cleanup to repair a missing release tag or channel alias. Use `Maintenance: Backfill Docker Release Tags` for that.\n\n### What cleanup preserves\n\nThis workflow periodically deletes unprotected preview and unreferenced GitHub Container Registry versions while preserving:\n\n- release-tagged versions.\n- `stable`, `beta`, `test`, and stable minor-series tags.\n\nThe moving `test` tag is protected like the other channel aliases.\nImmutable `sha-\u003cfull-commit-sha\u003e` preview tags are deleted when they are no longer protected by another retained tag.\nUntagged child manifests referenced by retained multi-platform indexes are protected before stale untagged versions are deleted.\nThe cleanup also prunes stale `ghcr.io/\u003cowner\u003e/sambee-signatures` metadata and Cosign signature tags after their corresponding `sambee` image digest is no longer retained.\nThe same reference-aware untagged cleanup runs for `sambee-signatures`, where it keeps Cosign signature bundle children referenced by retained signature indexes.\n\nThat keeps the `test` channel usable while aggressively removing disposable preview history.\n\n## Cleanup Rules\n\nUse this quick reference when deciding what the cleanup workflow will keep versus delete.\n\n| If a package version is... | Cleanup action |\n|---|---|\n| Tagged with a release tag, whether stable or prerelease | Keep |\n| Tagged with a protected channel or series tag such as `stable`, `beta`, `test`, or `0.7` | Keep |\n| Tagged only with an immutable preview tag such as `sha-\u003cfull-commit-sha\u003e` | Delete |\n| Untagged but still referenced by a retained multi-platform image index | Keep |\n| Untagged and not referenced by any retained index | Delete |\n| A signature or metadata artifact for a retained image digest | Keep |\n| A signature or metadata artifact for a deleted image digest | Delete |\n\nThere is no retention count anymore. The workflow deletes every package version that is not protected by tags or by graph references.\n\n## Examples\n\n- `ghcr.io/\u003cowner\u003e/sambee:test` stays because `test` is a protected channel tag.\n- `ghcr.io/\u003cowner\u003e/sambee:sha-\u003cfull-commit-sha\u003e` is deleted if that digest is not also kept by another protected tag.\n- An untagged platform manifest stays if a retained multi-platform index still points to it.\n- A stale `ghcr.io/\u003cowner\u003e/sambee-signatures` artifact is deleted after its corresponding image digest is no longer retained.\n\n## Boundaries\n\n- Do not publish a replacement runtime image in backfill. Recovery should point tags back at an existing digest.\n- Do not treat immutable `sha-\u003cfull-commit-sha\u003e` preview tags as permanent history. The cleanup workflow is expected to prune them.\n- Do not use moving tags such as `stable`, `beta`, or `test` as the only source of deployment truth when a digest is available.\n\nIf you are starting from a new candidate commit rather than repairing an existing release path, go back to [Build Docker Image](../build-docker-image/) or [Promote Docker Image](../promote-docker-image/).\n", "1.0": "+++\ntitle = \"Docker Backfill And Cleanup\"\n+++\n\nThis is the maintenance page for the Docker release flow.\n\nUse these maintenance workflows when you need to repair tags, backfill an older approved release, or keep preview history under control.\n\n## Summary\n\nUse this page when you are not publishing a new Docker image, but instead need to maintain existing release artifacts in GitHub Container Registry.\n\n| Workflow | What it does | Required input | Use it when... |\n|---|---|---|---|\n| `Maintenance: Backfill Docker Release Tags` | Reattaches release tags and channel aliases to an already approved digest and republishes missing metadata bundle assets when needed. | One existing Git tag in release form, such as `v0.7.0` or `v0.7.0-beta.1`. | A release already exists, but its GHCR tags or release assets are missing, wrong, or need to be reconstructed without building a new image. |\n| `Maintenance: Clean Up Docker Package Versions` | Deletes unprotected preview versions, stale signature artifacts, and unreferenced untagged GHCR package versions. | None. | Preview history and dangling GHCR artifacts have accumulated and you want the repository cleaned up without touching protected release artifacts. |\n\n## Backfill Docker Release Tags\n\nGitHub Actions displays the recovery workflow as `Maintenance: Backfill Docker Release Tags`.\n\n### What it does\n\nUse it to repair or reconstruct the publish side of an already approved Docker release without publishing a new runtime image.\n\nThe workflow:\n\n- resolves the digest that already belongs to the approved release\n- verifies image metadata\n- verifies the preview-built metadata bundle, generating and publishing it first if an older release does not have one yet\n- reapplies the expected release tags to that same digest\n- updates channel aliases with the same semver rules as normal promotion\n- uploads the metadata bundle files to the GitHub Release as convenience assets\n\nFor stable releases, that means backfill also moves `beta` forward unless `beta` already points to the same digest or to a higher semver release line.\n\n### Required input\n\nThe workflow takes one manual input:\n\n| Input | What it means | Required |\n|---|---|---|\n| `release_tag` | An existing immutable Git tag for the approved release, for example `v0.7.0` or `v0.7.0-beta.1`. The tag must match the checked-in `VERSION` value for that tagged commit. | Yes |\n\n### When to use it\n\nUse backfill in specific repair scenarios such as:\n\n- The GitHub Release exists, but the expected GHCR release tags were not attached.\n- A stable release was approved earlier, and you need to restore `stable`, version tags, or `beta` catch-up behavior to the correct existing digest.\n- A prerelease was approved earlier, and you need to restore the `beta` alias to the already approved digest.\n- A transient runner or registry failure interrupted release publication after the candidate image had already been built successfully.\n- An older approved release predates the current metadata-bundle flow, and you need to reconstruct the release assets without rebuilding the runtime image.\n\nDo not use backfill when you want to ship a new candidate commit. In that case, go back to [Build Docker Image](../build-docker-image/) and then [Promote Docker Image](../promote-docker-image/).\n\n### Tag requirements\n\nThe release tag can be either a stable tag such as `v0.7.0` or a prerelease tag such as `vX.Y.Z-beta.N`, as long as it matches the checked-in base `VERSION` for that release commit.\n\nWhen an older release does not have the new metadata bundle yet, backfill may create a local attested OCI export from the tagged source to recover SBOM and provenance files. That export is used only to publish the missing metadata bundle; the runtime image digest being promoted does not change.\n\nUse backfill only for already approved releases. It is not an alternate way to publish a new image.\n\n## Clean Up Docker Package Versions\n\nGitHub Actions displays the retention workflow as `Maintenance: Clean Up Docker Package Versions`.\n\n### What it does\n\nThis workflow removes disposable GHCR history while preserving artifacts that are still in use.\n\nIt:\n\n- deletes unprotected preview package versions\n- prunes stale metadata and Cosign signature artifacts\n- removes unreferenced untagged package versions\n- preserves release-tagged versions, protected channel aliases, and graph-referenced child manifests\n\n### Required input\n\nThis workflow has no manual inputs.\n\nIt runs automatically after successful preview publication, on a schedule, or manually when you want to force a cleanup pass.\n\n### When to use it\n\nUse cleanup in specific maintenance scenarios such as:\n\n- Preview publishing has created many old `sha-\u003cfull-commit-sha\u003e` versions that are no longer needed.\n- GHCR package pages have accumulated stale signature or metadata artifacts from deleted image digests.\n- You want to verify that retention behavior is working after changes to release-tagging or cleanup logic.\n- You want an immediate cleanup run instead of waiting for the next scheduled pass.\n\nDo not use cleanup to repair a missing release tag or channel alias. Use `Maintenance: Backfill Docker Release Tags` for that.\n\n### What cleanup preserves\n\nThis workflow periodically deletes unprotected preview and unreferenced GitHub Container Registry versions while preserving:\n\n- release-tagged versions.\n- `stable`, `beta`, `test`, and stable minor-series tags.\n\nThe moving `test` tag is protected like the other channel aliases.\nImmutable `sha-\u003cfull-commit-sha\u003e` preview tags are deleted when they are no longer protected by another retained tag.\nUntagged child manifests referenced by retained multi-platform indexes are protected before stale untagged versions are deleted.\nThe cleanup also prunes stale `ghcr.io/\u003cowner\u003e/sambee-signatures` metadata and Cosign signature tags after their corresponding `sambee` image digest is no longer retained.\nThe same reference-aware untagged cleanup runs for `sambee-signatures`, where it keeps Cosign signature bundle children referenced by retained signature indexes.\n\nThat keeps the `test` channel usable while aggressively removing disposable preview history.\n\n## Cleanup Rules\n\nUse this quick reference when deciding what the cleanup workflow will keep versus delete.\n\n| If a package version is... | Cleanup action |\n|---|---|\n| Tagged with a release tag, whether stable or prerelease | Keep |\n| Tagged with a protected channel or series tag such as `stable`, `beta`, `test`, or `0.7` | Keep |\n| Tagged only with an immutable preview tag such as `sha-\u003cfull-commit-sha\u003e` | Delete |\n| Untagged but still referenced by a retained multi-platform image index | Keep |\n| Untagged and not referenced by any retained index | Delete |\n| A signature or metadata artifact for a retained image digest | Keep |\n| A signature or metadata artifact for a deleted image digest | Delete |\n\nThere is no retention count anymore. The workflow deletes every package version that is not protected by tags or by graph references.\n\n## Examples\n\n- `ghcr.io/\u003cowner\u003e/sambee:test` stays because `test` is a protected channel tag.\n- `ghcr.io/\u003cowner\u003e/sambee:sha-\u003cfull-commit-sha\u003e` is deleted if that digest is not also kept by another protected tag.\n- An untagged platform manifest stays if a retained multi-platform index still points to it.\n- A stale `ghcr.io/\u003cowner\u003e/sambee-signatures` artifact is deleted after its corresponding image digest is no longer retained.\n\n## Boundaries\n\n- Do not publish a replacement runtime image in backfill. Recovery should point tags back at an existing digest.\n- Do not treat immutable `sha-\u003cfull-commit-sha\u003e` preview tags as permanent history. The cleanup workflow is expected to prune them.\n- Do not use moving tags such as `stable`, `beta`, or `test` as the only source of deployment truth when a digest is available.\n\nIf you are starting from a new candidate commit rather than repairing an existing release path, go back to [Build Docker Image](../build-docker-image/) or [Promote Docker Image](../promote-docker-image/).\n", "2.0": "+++\ntitle = \"Docker Backfill And Cleanup\"\n+++\n\nThis is the maintenance page for the Docker release flow.\n\nUse these maintenance workflows when you need to repair tags, backfill an older approved release, or keep preview history under control.\n\n## Summary\n\nUse this page when you are not publishing a new Docker image, but instead need to maintain existing release artifacts in GitHub Container Registry.\n\n| Workflow | What it does | Required input | Use it when... |\n|---|---|---|---|\n| `Maintenance: Backfill Docker Release Tags` | Reattaches release tags and channel aliases to an already approved digest and republishes missing metadata bundle assets when needed. | One existing Git tag in release form, such as `v0.7.0` or `v0.7.0-beta.1`. | A release already exists, but its GHCR tags or release assets are missing, wrong, or need to be reconstructed without building a new image. |\n| `Maintenance: Clean Up Docker Package Versions` | Deletes unprotected preview versions, stale signature artifacts, and unreferenced untagged GHCR package versions. | None. | Preview history and dangling GHCR artifacts have accumulated and you want the repository cleaned up without touching protected release artifacts. |\n\n## Backfill Docker Release Tags\n\nGitHub Actions displays the recovery workflow as `Maintenance: Backfill Docker Release Tags`.\n\n### What it does\n\nUse it to repair or reconstruct the publish side of an already approved Docker release without publishing a new runtime image.\n\nThe workflow:\n\n- resolves the digest that already belongs to the approved release\n- verifies image metadata\n- verifies the preview-built metadata bundle, generating and publishing it first if an older release does not have one yet\n- reapplies the expected release tags to that same digest\n- updates channel aliases with the same semver rules as normal promotion\n- uploads the metadata bundle files to the GitHub Release as convenience assets\n\nFor stable releases, that means backfill also moves `beta` forward unless `beta` already points to the same digest or to a higher semver release line.\n\n### Required input\n\nThe workflow takes one manual input:\n\n| Input | What it means | Required |\n|---|---|---|\n| `release_tag` | An existing immutable Git tag for the approved release, for example `v0.7.0` or `v0.7.0-beta.1`. The tag must match the checked-in `VERSION` value for that tagged commit. | Yes |\n\n### When to use it\n\nUse backfill in specific repair scenarios such as:\n\n- The GitHub Release exists, but the expected GHCR release tags were not attached.\n- A stable release was approved earlier, and you need to restore `stable`, version tags, or `beta` catch-up behavior to the correct existing digest.\n- A prerelease was approved earlier, and you need to restore the `beta` alias to the already approved digest.\n- A transient runner or registry failure interrupted release publication after the candidate image had already been built successfully.\n- An older approved release predates the current metadata-bundle flow, and you need to reconstruct the release assets without rebuilding the runtime image.\n\nDo not use backfill when you want to ship a new candidate commit. In that case, go back to [Build Docker Image](../build-docker-image/) and then [Promote Docker Image](../promote-docker-image/).\n\n### Tag requirements\n\nThe release tag can be either a stable tag such as `v0.7.0` or a prerelease tag such as `vX.Y.Z-beta.N`, as long as it matches the checked-in base `VERSION` for that release commit.\n\nWhen an older release does not have the new metadata bundle yet, backfill may create a local attested OCI export from the tagged source to recover SBOM and provenance files. That export is used only to publish the missing metadata bundle; the runtime image digest being promoted does not change.\n\nUse backfill only for already approved releases. It is not an alternate way to publish a new image.\n\n## Clean Up Docker Package Versions\n\nGitHub Actions displays the retention workflow as `Maintenance: Clean Up Docker Package Versions`.\n\n### What it does\n\nThis workflow removes disposable GHCR history while preserving artifacts that are still in use.\n\nIt:\n\n- deletes unprotected preview package versions\n- prunes stale metadata and Cosign signature artifacts\n- removes unreferenced untagged package versions\n- preserves release-tagged versions, protected channel aliases, and graph-referenced child manifests\n\n### Required input\n\nThis workflow has no manual inputs.\n\nIt runs automatically after successful preview publication, on a schedule, or manually when you want to force a cleanup pass.\n\n### When to use it\n\nUse cleanup in specific maintenance scenarios such as:\n\n- Preview publishing has created many old `sha-\u003cfull-commit-sha\u003e` versions that are no longer needed.\n- GHCR package pages have accumulated stale signature or metadata artifacts from deleted image digests.\n- You want to verify that retention behavior is working after changes to release-tagging or cleanup logic.\n- You want an immediate cleanup run instead of waiting for the next scheduled pass.\n\nDo not use cleanup to repair a missing release tag or channel alias. Use `Maintenance: Backfill Docker Release Tags` for that.\n\n### What cleanup preserves\n\nThis workflow periodically deletes unprotected preview and unreferenced GitHub Container Registry versions while preserving:\n\n- release-tagged versions.\n- `stable`, `beta`, `test`, and stable minor-series tags.\n\nThe moving `test` tag is protected like the other channel aliases.\nImmutable `sha-\u003cfull-commit-sha\u003e` preview tags are deleted when they are no longer protected by another retained tag.\nUntagged child manifests referenced by retained multi-platform indexes are protected before stale untagged versions are deleted.\nThe cleanup also prunes stale `ghcr.io/\u003cowner\u003e/sambee-signatures` metadata and Cosign signature tags after their corresponding `sambee` image digest is no longer retained.\nThe same reference-aware untagged cleanup runs for `sambee-signatures`, where it keeps Cosign signature bundle children referenced by retained signature indexes.\n\nThat keeps the `test` channel usable while aggressively removing disposable preview history.\n\n## Cleanup Rules\n\nUse this quick reference when deciding what the cleanup workflow will keep versus delete.\n\n| If a package version is... | Cleanup action |\n|---|---|\n| Tagged with a release tag, whether stable or prerelease | Keep |\n| Tagged with a protected channel or series tag such as `stable`, `beta`, `test`, or `0.7` | Keep |\n| Tagged only with an immutable preview tag such as `sha-\u003cfull-commit-sha\u003e` | Delete |\n| Untagged but still referenced by a retained multi-platform image index | Keep |\n| Untagged and not referenced by any retained index | Delete |\n| A signature or metadata artifact for a retained image digest | Keep |\n| A signature or metadata artifact for a deleted image digest | Delete |\n\nThere is no retention count anymore. The workflow deletes every package version that is not protected by tags or by graph references.\n\n## Examples\n\n- `ghcr.io/\u003cowner\u003e/sambee:test` stays because `test` is a protected channel tag.\n- `ghcr.io/\u003cowner\u003e/sambee:sha-\u003cfull-commit-sha\u003e` is deleted if that digest is not also kept by another protected tag.\n- An untagged platform manifest stays if a retained multi-platform index still points to it.\n- A stale `ghcr.io/\u003cowner\u003e/sambee-signatures` artifact is deleted after its corresponding image digest is no longer retained.\n\n## Boundaries\n\n- Do not publish a replacement runtime image in backfill. Recovery should point tags back at an existing digest.\n- Do not treat immutable `sha-\u003cfull-commit-sha\u003e` preview tags as permanent history. The cleanup workflow is expected to prune them.\n- Do not use moving tags such as `stable`, `beta`, or `test` as the only source of deployment truth when a digest is available.\n\nIf you are starting from a new candidate commit rather than repairing an existing release path, go back to [Build Docker Image](../build-docker-image/) or [Promote Docker Image](../promote-docker-image/).\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/release-and-versioning/companion-release-overview", "parent_id": "section:developer-guide/release-and-versioning", "depth": 2, "kind": "page", "label": "companion-release-overview", "title": "Companion Release Overview", "path": "developer-guide/release-and-versioning/companion-release-overview", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "branched", "source_version": "0.7", "diff_added": 4, "diff_removed": 0}, "0.9": {"state": "branched", "source_version": "0.8", "diff_added": 25, "diff_removed": 20}, "1.0": {"state": "branched", "source_version": "0.9", "diff_added": 14, "diff_removed": 47}, "2.0": {"state": "branched", "source_version": "1.0", "diff_added": 3, "diff_removed": 3}}, "content_versions": {"0.7": "+++\ntitle = \"Companion Release Overview\"\n+++\n\nSambee Companion releases are built and published once, and later promoted across update channels by changing public feed files.\n\nKey differences between the Companion and Docker release paths:\n\n- Docker releases promote an already published container digest.\n- Companion releases promote an already published GitHub Release by rewriting feeds read by Companion's auto-updater and by the Sambee frontend.\n\n## Summary\n\nIf you want to take a new Companion version to the `stable` update channel, follow this order:\n\n1. Update `VERSION` and run `./scripts/sync-version`.\n   - Git merge the reviewed `version-sync` changes.\n1. If you need a prerelease or test build before the official version, choose a distinct override version such as `0.8.0-beta.1` or `0.8.0-rc.1`.\n1. Run `Release: Build Companion Artifact` and select the target platforms.\n   - Leave `publish_version_override` empty for the checked-in version, or set it to the temporary prerelease version for this run.\n   - This creates draft release in the GitHub repo `helgeklein/sambee-companion`.\n1. Test the draft release.\n   - Download the installer from the releases artifacts, install and test.\n1. Publish the draft release.\n1. Run `Release: Promote Companion Release` for `test`.\n   - Validate both update behavior and direct-download metadata against the promoted feeds.\n1. Rerun `Release: Promote Companion Release` for `beta`, `stable`, and Sambee download metadata.\n\nCompanion release tags follow the `companion-v\u003cversion\u003e` pattern.\n\nThe build workflow refuses to reuse an existing Companion release tag, whether that release is still a draft or already published.\nWhen you need another pre-release candidate, assign a distinct suffix instead of rebuilding the same tag.\n\nOne published release can move from `test` to `beta` to `stable` without rebuilding binaries.\n\nRead the detailed pages in this order:\n\n1. [Build Companion Release](../build-companion-release/)\n1. [Promote Companion Release](../promote-companion-release/)\n1. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/)\n\n## Workflow Map\n\n| Workflow or system | When to use it | Result |\n|---|---|---|\n| `Release: Build Companion Artifact` | You want to create release assets for one new Companion version or prerelease candidate. | Builds the selected platform set and creates a draft GitHub Release in `helgeklein/sambee-companion`, failing early if that tag already exists. |\n| `Release: Promote Companion Release` | A published Companion release is approved for one or more channels or for Sambee download metadata. | Rewrites the selected feed files in `docs/feeds` of the release repository. |\n| `helgeklein/sambee-companion` | You need the release repository that owns public Companion release artifacts. | Hosts immutable GitHub Release assets and stores the committed feed files under `docs/feeds` to be served by GitHub Pages. |\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/build-companion.yml` | Builds platform artifacts, supports a one-run version override, and creates a draft release for a unique tag. |\n| `.github/workflows/promote-companion-release.yml` | Promotes one published release to selected public feeds. |\n| `.github/scripts/promote_companion_release.py` | Resolves release assets and writes the feed JSON files. |\n| `helgeklein/sambee-companion` | Dedicated public release repository for Companion GitHub Releases and committed feed source files. |\n| `release-repo/docs/feeds` | Source-controlled feed JSON files that promotion updates and commits. |\n\n## Channels And Consumers\n\nCompanion does not use separate binaries per channel. It uses one published release plus multiple mutable feed pointers.\n\nFor the public feed host, exact feed locations, and consumer-specific behavior, see [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/).\n\n## Published Artifact\n\nPublished Companion releases live in `helgeklein/sambee-companion` as GitHub Releases.\n\nEach release may contain:\n\n- Installer assets.\n- Tauri updater bundles.\n- `.sig` files for updater verification.\n- Release notes.\n\nRelease tags do not encode a channel.\nChannel visibility is decided only by the promoted feed files.\n\n## Operating Rules\n\n- Do not treat update channels as different binaries.\n- Do not patch broken published assets in place.\n- Build and publish a new release instead of replacing assets on an existing tag.\n- Assign a distinct prerelease suffix when you need another build before the official release.\n- Review whether you are changing Companion updater visibility, Sambee download visibility, or both.\n\nUse [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) for the system model behind those rules.\n", "0.8": "+++\ntitle = \"Companion Release Overview\"\n+++\n\nSambee Companion releases are built and published once, and later promoted across update channels by changing public feed files.\n\nKey differences between the Companion and Docker release paths:\n\n- Docker releases promote an already published container digest.\n- Companion releases promote an already published GitHub Release by rewriting feeds read by Companion's auto-updater and by the Sambee frontend.\n- Local Linux-hosted cross-checks can validate Windows-target compatibility, but they do not replace the Windows CI release build.\n\n## Summary\n\nIf you want to take a new Companion version to the `stable` update channel, follow this order:\n\n1. Update `VERSION` and run `./scripts/sync-version`.\n   - Git merge the reviewed `version-sync` changes.\n1. If you need a prerelease or test build before the official version, choose a distinct override version such as `0.8.0-beta.1` or `0.8.0-rc.1`.\n1. Run `Release: Build Companion Artifact` and select the target platforms.\n   - Leave `publish_version_override` empty for the checked-in version, or set it to the temporary prerelease version for this run.\n   - This creates draft release in the GitHub repo `helgeklein/sambee-companion`.\n1. Test the draft release.\n   - Download the installer from the releases artifacts, install and test.\n1. Publish the draft release.\n1. Run `Release: Promote Companion Release` for `test`.\n   - Validate both update behavior and direct-download metadata against the promoted feeds.\n1. Rerun `Release: Promote Companion Release` for `beta`, `stable`, and Sambee download metadata.\n\nCompanion release tags follow the `companion-v\u003cversion\u003e` pattern.\n\nThe build workflow refuses to reuse an existing Companion release tag, whether that release is still a draft or already published.\nWhen you need another pre-release candidate, assign a distinct suffix instead of rebuilding the same tag.\n\nOne published release can move from `test` to `beta` to `stable` without rebuilding binaries.\n\nRead the detailed pages in this order:\n\n1. [Build Companion Release](../build-companion-release/)\n1. [Promote Companion Release](../promote-companion-release/)\n1. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/)\n\n## Workflow Map\n\n| Workflow or system | When to use it | Result |\n|---|---|---|\n| Local `npm run check:rust:windows` | You want an early local Windows-target compatibility signal while working in Linux or the devcontainer. | Runs a Windows GNU target `cargo check` only. It does not create signed release assets. |\n| `Release: Build Companion Artifact` | You want to create release assets for one new Companion version or prerelease candidate. | Builds the selected platform set and creates a draft GitHub Release in `helgeklein/sambee-companion`, failing early if that tag already exists. |\n| `Release: Promote Companion Release` | A published Companion release is approved for one or more channels or for Sambee download metadata. | Rewrites the selected feed files in `docs/feeds` of the release repository. |\n| `helgeklein/sambee-companion` | You need the release repository that owns public Companion release artifacts. | Hosts immutable GitHub Release assets and stores the committed feed files under `docs/feeds` to be served by GitHub Pages. |\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/build-companion.yml` | Builds platform artifacts, supports a one-run version override, and creates a draft release for a unique tag. |\n| `.github/workflows/promote-companion-release.yml` | Promotes one published release to selected public feeds. |\n| `.github/scripts/promote_companion_release.py` | Resolves release assets and writes the feed JSON files. |\n| `helgeklein/sambee-companion` | Dedicated public release repository for Companion GitHub Releases and committed feed source files. |\n| `release-repo/docs/feeds` | Source-controlled feed JSON files that promotion updates and commits. |\n\n## Channels And Consumers\n\nCompanion does not use separate binaries per channel. It uses one published release plus multiple mutable feed pointers.\n\nFor the public feed host, exact feed locations, and consumer-specific behavior, see [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/).\n\n## Published Artifact\n\nPublished Companion releases live in `helgeklein/sambee-companion` as GitHub Releases.\n\nEach release may contain:\n\n- Installer assets.\n- Tauri updater bundles.\n- `.sig` files for updater verification.\n- Release notes.\n\nRelease tags do not encode a channel.\nChannel visibility is decided only by the promoted feed files.\n\n## Operating Rules\n\n- Do not treat update channels as different binaries.\n- Do not patch broken published assets in place.\n- Build and publish a new release instead of replacing assets on an existing tag.\n- Assign a distinct prerelease suffix when you need another build before the official release.\n- Review whether you are changing Companion updater visibility, Sambee download visibility, or both.\n- Treat local Windows GNU cross-checks as compatibility validation only.\n- Keep actual Windows artifact creation and signing in the CI release workflow.\n\nUse [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) for the system model behind those rules.\n", "0.9": "+++\ntitle = \"Companion Release Overview\"\n+++\n\nSambee Companion releases are built and published once, and later promoted across update channels by changing public feed files.\n\nKey differences between the Companion and Docker release paths:\n\n- Docker releases promote an already published container image.\n- Companion releases promote an already published GitHub Release by rewriting feeds read by Companion's auto-updater and by the Sambee frontend.\n- Docker images are available for Linux only, whereas Companion is a native app for Windows, Linux, and macOS. Each platform binary needs to be built on the respective OS.\n\n## Summary\n\nIf you want to take a new Companion version to the `stable` update channel, follow this order:\n\n1. Increment `VERSION` to the next `X.Y.Z` value and run `./scripts/sync-version`.\n1. Run `Release: Build Companion Artifact`:\n   - Select target platforms\n   - If the workflow's source version field is left blank, the artifact is built from the current commit in `main`, and the Git tag `build-vX.Y.Z` is created to reserve the version for the commit the artifact is built from.\n   - If a source version field is specified, the workflow verifies and repairs the artifact associated with the version via the Git tag used for reservation.\n1. The workflow:\n   - builds Companion\n   - signs the build artifacts\n   - creates one immutable draft release in in the [Companion GitHub repo](https://github.com/helgeklein/sambee-companion/releases).\n   - assigns a `companion-vX.Y.Z` tag to the draft release.\n1. Test the draft release.\n   - Download the installer from the release's artifacts, install and test.\n1. Publish the draft release. This:\n   - Makes the release eligible for promotion to the `test`, `beta`, and `stable` channels.\n   - Prevents additional build workflow runs changing the published Companion release.\n1. Ensure that a matching published public Sambee release `vX.Y.Z` exists.\n   - This authorizes the Companion workflow to promote a release.\n1. To promote the release to the update channels, run `Release: Promote Companion Release`:\n   - Select the channels: `test`, `beta`, and/or `stable`.\n   - Select whether to update the Sambee download metadata.\n\nThe workflow uses `build`, `recover-finalizer`, and `complete` states. A matching incomplete draft resumes only from recorded retained Actions artifacts; a complete draft or published release is not rebuilt. When a replacement is needed, increment `Z`, synchronize, commit on `main`, and build a new candidate.\n\nOne published release can move from `test` to `beta` to `stable` without rebuilding binaries.\n\nRead the detailed pages in this order:\n\n1. [Build Companion Release](../build-companion-release/)\n1. [Promote Companion Release](../promote-companion-release/)\n1. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/)\n\n## Workflow Map\n\n| Workflow or system | When to use it | Result |\n|---|---|---|\n| Local `npm run check:rust:windows` | You want an early local Windows-target compatibility signal while working in Linux or the devcontainer. | Runs a Windows GNU target `cargo check` only. It does not create signed release assets. |\n| `Release: Build Companion Artifact` | You want to create release assets for one canonical version. | Builds the selected platform set and creates, resumes, or reports the immutable draft GitHub Release in `helgeklein/sambee-companion`. |\n| `Release: Promote Companion Release` | A published Companion release is approved for one or more channels or for Sambee download metadata. | Rewrites the selected feed files in `docs/feeds` of the release repository. |\n| `helgeklein/sambee-companion` | You need the release repository that owns public Companion release artifacts. | Hosts immutable GitHub Release assets and stores the committed feed files under `docs/feeds` to be served by GitHub Pages. |\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/build-companion.yml` | Builds platform artifacts from a canonical source and creates or resumes one draft release for its immutable tag. |\n| `.github/workflows/promote-companion-release.yml` | Promotes one published release to selected public feeds. |\n| `.github/scripts/promote_companion_release.py` | Resolves release assets and writes the feed JSON files. |\n| `helgeklein/sambee-companion` | Dedicated public release repository for Companion GitHub Releases and committed feed source files. |\n| `release-repo/docs/feeds` | Source-controlled feed JSON files that promotion updates and commits. |\n\n## Channels And Consumers\n\nCompanion does not use separate binaries per channel. It uses one published release plus multiple mutable feed pointers.\n\nFor the public feed host, exact feed locations, and consumer-specific behavior, see [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/).\n\n## Published Artifact\n\nPublished Companion releases live in `helgeklein/sambee-companion` as GitHub Releases.\n\nEach release may contain:\n\n- Installer assets.\n- Tauri updater bundles.\n- `.sig` files for updater verification.\n- Release notes.\n\nRelease tags do not encode a channel.\nChannel visibility is decided only by the promoted feed files.\n\n## Operating Rules\n\n- Do not treat update channels as different binaries.\n- Do not patch broken published assets in place.\n- Build and publish a new release instead of replacing assets on an existing tag.\n- Increment the `Z` build sequence when you need another candidate.\n- Review whether you are changing Companion updater visibility, Sambee download visibility, or both.\n- Treat local Windows GNU cross-checks as compatibility validation only.\n- Keep actual Windows artifact creation and signing in the CI release workflow.\n\nUse [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) for the system model behind those rules.\n", "1.0": "+++\ntitle = \"Companion Release Overview\"\n+++\n\nSambee Companion releases are built and published once. A successful build automatically promotes the release to `test`; later channel promotion rewrites public feed files without rebuilding binaries.\n\nKey differences between the Companion and Docker release paths:\n\n- Docker releases promote an already published container image.\n- Companion releases promote an already published GitHub Release by rewriting feeds read by Companion's auto-updater and by the Sambee frontend.\n- Docker images are available for Linux only, whereas Companion is a native app for Windows, Linux, and macOS. Each platform binary needs to be built on the respective OS.\n\n## Summary\n\nIf you want to take a new Companion version to `stable`, follow this order:\n\n1. Increment `VERSION` to the next `X.Y.Z` value and run `./scripts/sync-version`.\n1. Run `Release: Build Companion Artifact`:\n   - Select target platforms\n   - If the workflow's source version field is left blank, the artifact is built from the current commit in `main`, and the Git tag `build-vX.Y.Z` is created to reserve the version for the commit the artifact is built from.\n   - If a source version field is specified, the workflow verifies and repairs the artifact associated with the version via the Git tag used for reservation.\n1. The workflow builds and signs Companion, publishes the verified immutable release in the [Companion GitHub repo](https://github.com/helgeklein/sambee-companion/releases), promotes it to `test`, and cleans up obsolete releases.\n1. Test the published release through the `test` channel or by installing its release assets.\n1. Run `Release: Promote Companion Release` when the release is approved for `beta`, `stable`, or Sambee download metadata.\n\nOne published release can move from `test` to `beta` to `stable` without rebuilding binaries.\n\nRead the detailed pages in this order:\n\n1. [Build Companion Release](../build-companion-release/)\n1. [Promote Companion Release](../promote-companion-release/)\n1. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/)\n1. [Companion Release Cleanup](../companion-release-cleanup/)\n\n## Workflow Map\n\n| Workflow | When to use it | Result |\n|---|---|---|\n| Local `npm run check:rust:windows` | You want an early local Windows-target compatibility signal while working in Linux or the devcontainer. | Runs a Windows GNU target `cargo check` only. It does not create signed release assets. |\n| `Release: Build Companion Artifact` | You want to create release assets for one canonical version. | Builds the selected platform set, publishes the verified immutable GitHub Release, promotes only `test`, and cleans up obsolete releases. |\n| `Release: Promote Companion Release` | A published Companion release is approved for one or more channels or for Sambee download metadata. | Rewrites the selected feed files in `docs/feeds` of the release repository. |\n| `Maintenance: Clean Up Companion Releases` | You want to reconcile release retention outside a promotion run. | Validates the feed markers and deletes obsolete GitHub Releases. |\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/build-companion.yml` | Builds platform artifacts from a canonical source, publishes the verified release, promotes `test`, and runs cleanup. |\n| `.github/workflows/promote-companion-release.yml` | Promotes one published release to selected public feeds. |\n| `.github/scripts/promote_companion_release.py` | Resolves release assets and writes the feed JSON files. |\n| `.github/scripts/cleanup_companion_releases.py` | Validates feed references and applies Companion release retention. |\n| [helgeklein/sambee-companion](https://github.com/helgeklein/sambee-companion/) | Dedicated public release repository for Companion GitHub Releases and committed feed source files. |\n| `release-repo/docs/feeds` | Source-controlled feed JSON files that promotion updates and commits ([docs](../companion-channels-feeds-and-downloads/)). |\n\n## Published Artifact\n\nPublished Companion releases live in [helgeklein/sambee-companion](https://github.com/helgeklein/sambee-companion/) as GitHub Releases.\n\nEach release may contain:\n\n- Installer assets.\n- Tauri updater bundles.\n- `.sig` files for updater verification.\n- Release notes.\n", "2.0": "+++\ntitle = \"Companion Release Overview\"\n+++\n\nSambee Companion releases are built and published once. A successful build automatically promotes the release to `test`; later channel promotion rewrites public feed files without rebuilding binaries.\n\nKey differences between the Companion and Docker release paths:\n\n- Docker releases promote an already published container image.\n- Companion releases promote an already published GitHub Release by rewriting feeds read by Companion's auto-updater and by the Sambee frontend.\n- Docker images are available for Linux only, whereas Companion is a native app for Windows, Linux, and macOS. Each platform binary needs to be built on the respective OS.\n\n## Summary\n\nIf you want to take a new Companion version to `stable`, follow this order:\n\n1. Increment `VERSION` to the next `X.Y.Z` value and run `./scripts/sync-version`.\n1. Run `Release: Build Companion Artifact`:\n   - Select target platforms\n   - If the workflow's source version field is left blank, the artifact is built from the current commit in `main`, and the Git tag `build-vX.Y.Z` is created to reserve the version for the commit the artifact is built from.\n   - If a source version field is specified, the workflow verifies and repairs the artifact associated with the version via the Git tag used for reservation.\n1. The workflow builds and signs Companion, publishes the verified immutable release in the [Companion GitHub repo](https://github.com/sambee-app/sambee-companion/releases), promotes it to `test`, and cleans up obsolete releases.\n1. Test the published release through the `test` channel or by installing its release assets.\n1. Run `Release: Promote Companion Release` when the release is approved for `beta`, `stable`, or Sambee download metadata.\n\nOne published release can move from `test` to `beta` to `stable` without rebuilding binaries.\n\nRead the detailed pages in this order:\n\n1. [Build Companion Release](../build-companion-release/)\n1. [Promote Companion Release](../promote-companion-release/)\n1. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/)\n1. [Companion Release Cleanup](../companion-release-cleanup/)\n\n## Workflow Map\n\n| Workflow | When to use it | Result |\n|---|---|---|\n| Local `npm run check:rust:windows` | You want an early local Windows-target compatibility signal while working in Linux or the devcontainer. | Runs a Windows GNU target `cargo check` only. It does not create signed release assets. |\n| `Release: Build Companion Artifact` | You want to create release assets for one canonical version. | Builds the selected platform set, publishes the verified immutable GitHub Release, promotes only `test`, and cleans up obsolete releases. |\n| `Release: Promote Companion Release` | A published Companion release is approved for one or more channels or for Sambee download metadata. | Rewrites the selected feed files in `docs/feeds` of the release repository. |\n| `Maintenance: Clean Up Companion Releases` | You want to reconcile release retention outside a promotion run. | Validates the feed markers and deletes obsolete GitHub Releases. |\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/build-companion.yml` | Builds platform artifacts from a canonical source, publishes the verified release, promotes `test`, and runs cleanup. |\n| `.github/workflows/promote-companion-release.yml` | Promotes one published release to selected public feeds. |\n| `.github/scripts/promote_companion_release.py` | Resolves release assets and writes the feed JSON files. |\n| `.github/scripts/cleanup_companion_releases.py` | Validates feed references and applies Companion release retention. |\n| [sambee-app/sambee-companion](https://github.com/sambee-app/sambee-companion/) | Dedicated public release repository for Companion GitHub Releases and committed feed source files. |\n| `release-repo/docs/feeds` | Source-controlled feed JSON files that promotion updates and commits ([docs](../companion-channels-feeds-and-downloads/)). |\n\n## Published Artifact\n\nPublished Companion releases live in [sambee-app/sambee-companion](https://github.com/sambee-app/sambee-companion/) as GitHub Releases.\n\nEach release may contain:\n\n- Installer assets.\n- Tauri updater bundles.\n- `.sig` files for updater verification.\n- Release notes.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Companion Release Overview\"\n+++\n\nSambee Companion releases are built and published once, and later promoted across update channels by changing public feed files.\n\nKey differences between the Companion and Docker release paths:\n\n- Docker releases promote an already published container digest.\n- Companion releases promote an already published GitHub Release by rewriting feeds read by Companion's auto-updater and by the Sambee frontend.\n\n## Summary\n\nIf you want to take a new Companion version to the `stable` update channel, follow this order:\n\n1. Update `VERSION` and run `./scripts/sync-version`.\n   - Git merge the reviewed `version-sync` changes.\n1. If you need a prerelease or test build before the official version, choose a distinct override version such as `0.8.0-beta.1` or `0.8.0-rc.1`.\n1. Run `Release: Build Companion Artifact` and select the target platforms.\n   - Leave `publish_version_override` empty for the checked-in version, or set it to the temporary prerelease version for this run.\n   - This creates draft release in the GitHub repo `helgeklein/sambee-companion`.\n1. Test the draft release.\n   - Download the installer from the releases artifacts, install and test.\n1. Publish the draft release.\n1. Run `Release: Promote Companion Release` for `test`.\n   - Validate both update behavior and direct-download metadata against the promoted feeds.\n1. Rerun `Release: Promote Companion Release` for `beta`, `stable`, and Sambee download metadata.\n\nCompanion release tags follow the `companion-v\u003cversion\u003e` pattern.\n\nThe build workflow refuses to reuse an existing Companion release tag, whether that release is still a draft or already published.\nWhen you need another pre-release candidate, assign a distinct suffix instead of rebuilding the same tag.\n\nOne published release can move from `test` to `beta` to `stable` without rebuilding binaries.\n\nRead the detailed pages in this order:\n\n1. [Build Companion Release](../build-companion-release/)\n1. [Promote Companion Release](../promote-companion-release/)\n1. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/)\n\n## Workflow Map\n\n| Workflow or system | When to use it | Result |\n|---|---|---|\n| `Release: Build Companion Artifact` | You want to create release assets for one new Companion version or prerelease candidate. | Builds the selected platform set and creates a draft GitHub Release in `helgeklein/sambee-companion`, failing early if that tag already exists. |\n| `Release: Promote Companion Release` | A published Companion release is approved for one or more channels or for Sambee download metadata. | Rewrites the selected feed files in `docs/feeds` of the release repository. |\n| `helgeklein/sambee-companion` | You need the release repository that owns public Companion release artifacts. | Hosts immutable GitHub Release assets and stores the committed feed files under `docs/feeds` to be served by GitHub Pages. |\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/build-companion.yml` | Builds platform artifacts, supports a one-run version override, and creates a draft release for a unique tag. |\n| `.github/workflows/promote-companion-release.yml` | Promotes one published release to selected public feeds. |\n| `.github/scripts/promote_companion_release.py` | Resolves release assets and writes the feed JSON files. |\n| `helgeklein/sambee-companion` | Dedicated public release repository for Companion GitHub Releases and committed feed source files. |\n| `release-repo/docs/feeds` | Source-controlled feed JSON files that promotion updates and commits. |\n\n## Channels And Consumers\n\nCompanion does not use separate binaries per channel. It uses one published release plus multiple mutable feed pointers.\n\nFor the public feed host, exact feed locations, and consumer-specific behavior, see [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/).\n\n## Published Artifact\n\nPublished Companion releases live in `helgeklein/sambee-companion` as GitHub Releases.\n\nEach release may contain:\n\n- Installer assets.\n- Tauri updater bundles.\n- `.sig` files for updater verification.\n- Release notes.\n\nRelease tags do not encode a channel.\nChannel visibility is decided only by the promoted feed files.\n\n## Operating Rules\n\n- Do not treat update channels as different binaries.\n- Do not patch broken published assets in place.\n- Build and publish a new release instead of replacing assets on an existing tag.\n- Assign a distinct prerelease suffix when you need another build before the official release.\n- Review whether you are changing Companion updater visibility, Sambee download visibility, or both.\n\nUse [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) for the system model behind those rules.\n", "0.8": "+++\ntitle = \"Companion Release Overview\"\n+++\n\nSambee Companion releases are built and published once, and later promoted across update channels by changing public feed files.\n\nKey differences between the Companion and Docker release paths:\n\n- Docker releases promote an already published container digest.\n- Companion releases promote an already published GitHub Release by rewriting feeds read by Companion's auto-updater and by the Sambee frontend.\n- Local Linux-hosted cross-checks can validate Windows-target compatibility, but they do not replace the Windows CI release build.\n\n## Summary\n\nIf you want to take a new Companion version to the `stable` update channel, follow this order:\n\n1. Update `VERSION` and run `./scripts/sync-version`.\n   - Git merge the reviewed `version-sync` changes.\n1. If you need a prerelease or test build before the official version, choose a distinct override version such as `0.8.0-beta.1` or `0.8.0-rc.1`.\n1. Run `Release: Build Companion Artifact` and select the target platforms.\n   - Leave `publish_version_override` empty for the checked-in version, or set it to the temporary prerelease version for this run.\n   - This creates draft release in the GitHub repo `helgeklein/sambee-companion`.\n1. Test the draft release.\n   - Download the installer from the releases artifacts, install and test.\n1. Publish the draft release.\n1. Run `Release: Promote Companion Release` for `test`.\n   - Validate both update behavior and direct-download metadata against the promoted feeds.\n1. Rerun `Release: Promote Companion Release` for `beta`, `stable`, and Sambee download metadata.\n\nCompanion release tags follow the `companion-v\u003cversion\u003e` pattern.\n\nThe build workflow refuses to reuse an existing Companion release tag, whether that release is still a draft or already published.\nWhen you need another pre-release candidate, assign a distinct suffix instead of rebuilding the same tag.\n\nOne published release can move from `test` to `beta` to `stable` without rebuilding binaries.\n\nRead the detailed pages in this order:\n\n1. [Build Companion Release](../build-companion-release/)\n1. [Promote Companion Release](../promote-companion-release/)\n1. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/)\n\n## Workflow Map\n\n| Workflow or system | When to use it | Result |\n|---|---|---|\n| Local `npm run check:rust:windows` | You want an early local Windows-target compatibility signal while working in Linux or the devcontainer. | Runs a Windows GNU target `cargo check` only. It does not create signed release assets. |\n| `Release: Build Companion Artifact` | You want to create release assets for one new Companion version or prerelease candidate. | Builds the selected platform set and creates a draft GitHub Release in `helgeklein/sambee-companion`, failing early if that tag already exists. |\n| `Release: Promote Companion Release` | A published Companion release is approved for one or more channels or for Sambee download metadata. | Rewrites the selected feed files in `docs/feeds` of the release repository. |\n| `helgeklein/sambee-companion` | You need the release repository that owns public Companion release artifacts. | Hosts immutable GitHub Release assets and stores the committed feed files under `docs/feeds` to be served by GitHub Pages. |\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/build-companion.yml` | Builds platform artifacts, supports a one-run version override, and creates a draft release for a unique tag. |\n| `.github/workflows/promote-companion-release.yml` | Promotes one published release to selected public feeds. |\n| `.github/scripts/promote_companion_release.py` | Resolves release assets and writes the feed JSON files. |\n| `helgeklein/sambee-companion` | Dedicated public release repository for Companion GitHub Releases and committed feed source files. |\n| `release-repo/docs/feeds` | Source-controlled feed JSON files that promotion updates and commits. |\n\n## Channels And Consumers\n\nCompanion does not use separate binaries per channel. It uses one published release plus multiple mutable feed pointers.\n\nFor the public feed host, exact feed locations, and consumer-specific behavior, see [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/).\n\n## Published Artifact\n\nPublished Companion releases live in `helgeklein/sambee-companion` as GitHub Releases.\n\nEach release may contain:\n\n- Installer assets.\n- Tauri updater bundles.\n- `.sig` files for updater verification.\n- Release notes.\n\nRelease tags do not encode a channel.\nChannel visibility is decided only by the promoted feed files.\n\n## Operating Rules\n\n- Do not treat update channels as different binaries.\n- Do not patch broken published assets in place.\n- Build and publish a new release instead of replacing assets on an existing tag.\n- Assign a distinct prerelease suffix when you need another build before the official release.\n- Review whether you are changing Companion updater visibility, Sambee download visibility, or both.\n- Treat local Windows GNU cross-checks as compatibility validation only.\n- Keep actual Windows artifact creation and signing in the CI release workflow.\n\nUse [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) for the system model behind those rules.\n", "0.9": "+++\ntitle = \"Companion Release Overview\"\n+++\n\nSambee Companion releases are built and published once, and later promoted across update channels by changing public feed files.\n\nKey differences between the Companion and Docker release paths:\n\n- Docker releases promote an already published container image.\n- Companion releases promote an already published GitHub Release by rewriting feeds read by Companion's auto-updater and by the Sambee frontend.\n- Docker images are available for Linux only, whereas Companion is a native app for Windows, Linux, and macOS. Each platform binary needs to be built on the respective OS.\n\n## Summary\n\nIf you want to take a new Companion version to the `stable` update channel, follow this order:\n\n1. Increment `VERSION` to the next `X.Y.Z` value and run `./scripts/sync-version`.\n1. Run `Release: Build Companion Artifact`:\n   - Select target platforms\n   - If the workflow's source version field is left blank, the artifact is built from the current commit in `main`, and the Git tag `build-vX.Y.Z` is created to reserve the version for the commit the artifact is built from.\n   - If a source version field is specified, the workflow verifies and repairs the artifact associated with the version via the Git tag used for reservation.\n1. The workflow:\n   - builds Companion\n   - signs the build artifacts\n   - creates one immutable draft release in in the [Companion GitHub repo](https://github.com/helgeklein/sambee-companion/releases).\n   - assigns a `companion-vX.Y.Z` tag to the draft release.\n1. Test the draft release.\n   - Download the installer from the release's artifacts, install and test.\n1. Publish the draft release. This:\n   - Makes the release eligible for promotion to the `test`, `beta`, and `stable` channels.\n   - Prevents additional build workflow runs changing the published Companion release.\n1. Ensure that a matching published public Sambee release `vX.Y.Z` exists.\n   - This authorizes the Companion workflow to promote a release.\n1. To promote the release to the update channels, run `Release: Promote Companion Release`:\n   - Select the channels: `test`, `beta`, and/or `stable`.\n   - Select whether to update the Sambee download metadata.\n\nThe workflow uses `build`, `recover-finalizer`, and `complete` states. A matching incomplete draft resumes only from recorded retained Actions artifacts; a complete draft or published release is not rebuilt. When a replacement is needed, increment `Z`, synchronize, commit on `main`, and build a new candidate.\n\nOne published release can move from `test` to `beta` to `stable` without rebuilding binaries.\n\nRead the detailed pages in this order:\n\n1. [Build Companion Release](../build-companion-release/)\n1. [Promote Companion Release](../promote-companion-release/)\n1. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/)\n\n## Workflow Map\n\n| Workflow or system | When to use it | Result |\n|---|---|---|\n| Local `npm run check:rust:windows` | You want an early local Windows-target compatibility signal while working in Linux or the devcontainer. | Runs a Windows GNU target `cargo check` only. It does not create signed release assets. |\n| `Release: Build Companion Artifact` | You want to create release assets for one canonical version. | Builds the selected platform set and creates, resumes, or reports the immutable draft GitHub Release in `helgeklein/sambee-companion`. |\n| `Release: Promote Companion Release` | A published Companion release is approved for one or more channels or for Sambee download metadata. | Rewrites the selected feed files in `docs/feeds` of the release repository. |\n| `helgeklein/sambee-companion` | You need the release repository that owns public Companion release artifacts. | Hosts immutable GitHub Release assets and stores the committed feed files under `docs/feeds` to be served by GitHub Pages. |\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/build-companion.yml` | Builds platform artifacts from a canonical source and creates or resumes one draft release for its immutable tag. |\n| `.github/workflows/promote-companion-release.yml` | Promotes one published release to selected public feeds. |\n| `.github/scripts/promote_companion_release.py` | Resolves release assets and writes the feed JSON files. |\n| `helgeklein/sambee-companion` | Dedicated public release repository for Companion GitHub Releases and committed feed source files. |\n| `release-repo/docs/feeds` | Source-controlled feed JSON files that promotion updates and commits. |\n\n## Channels And Consumers\n\nCompanion does not use separate binaries per channel. It uses one published release plus multiple mutable feed pointers.\n\nFor the public feed host, exact feed locations, and consumer-specific behavior, see [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/).\n\n## Published Artifact\n\nPublished Companion releases live in `helgeklein/sambee-companion` as GitHub Releases.\n\nEach release may contain:\n\n- Installer assets.\n- Tauri updater bundles.\n- `.sig` files for updater verification.\n- Release notes.\n\nRelease tags do not encode a channel.\nChannel visibility is decided only by the promoted feed files.\n\n## Operating Rules\n\n- Do not treat update channels as different binaries.\n- Do not patch broken published assets in place.\n- Build and publish a new release instead of replacing assets on an existing tag.\n- Increment the `Z` build sequence when you need another candidate.\n- Review whether you are changing Companion updater visibility, Sambee download visibility, or both.\n- Treat local Windows GNU cross-checks as compatibility validation only.\n- Keep actual Windows artifact creation and signing in the CI release workflow.\n\nUse [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) for the system model behind those rules.\n", "1.0": "+++\ntitle = \"Companion Release Overview\"\n+++\n\nSambee Companion releases are built and published once. A successful build automatically promotes the release to `test`; later channel promotion rewrites public feed files without rebuilding binaries.\n\nKey differences between the Companion and Docker release paths:\n\n- Docker releases promote an already published container image.\n- Companion releases promote an already published GitHub Release by rewriting feeds read by Companion's auto-updater and by the Sambee frontend.\n- Docker images are available for Linux only, whereas Companion is a native app for Windows, Linux, and macOS. Each platform binary needs to be built on the respective OS.\n\n## Summary\n\nIf you want to take a new Companion version to `stable`, follow this order:\n\n1. Increment `VERSION` to the next `X.Y.Z` value and run `./scripts/sync-version`.\n1. Run `Release: Build Companion Artifact`:\n   - Select target platforms\n   - If the workflow's source version field is left blank, the artifact is built from the current commit in `main`, and the Git tag `build-vX.Y.Z` is created to reserve the version for the commit the artifact is built from.\n   - If a source version field is specified, the workflow verifies and repairs the artifact associated with the version via the Git tag used for reservation.\n1. The workflow builds and signs Companion, publishes the verified immutable release in the [Companion GitHub repo](https://github.com/helgeklein/sambee-companion/releases), promotes it to `test`, and cleans up obsolete releases.\n1. Test the published release through the `test` channel or by installing its release assets.\n1. Run `Release: Promote Companion Release` when the release is approved for `beta`, `stable`, or Sambee download metadata.\n\nOne published release can move from `test` to `beta` to `stable` without rebuilding binaries.\n\nRead the detailed pages in this order:\n\n1. [Build Companion Release](../build-companion-release/)\n1. [Promote Companion Release](../promote-companion-release/)\n1. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/)\n1. [Companion Release Cleanup](../companion-release-cleanup/)\n\n## Workflow Map\n\n| Workflow | When to use it | Result |\n|---|---|---|\n| Local `npm run check:rust:windows` | You want an early local Windows-target compatibility signal while working in Linux or the devcontainer. | Runs a Windows GNU target `cargo check` only. It does not create signed release assets. |\n| `Release: Build Companion Artifact` | You want to create release assets for one canonical version. | Builds the selected platform set, publishes the verified immutable GitHub Release, promotes only `test`, and cleans up obsolete releases. |\n| `Release: Promote Companion Release` | A published Companion release is approved for one or more channels or for Sambee download metadata. | Rewrites the selected feed files in `docs/feeds` of the release repository. |\n| `Maintenance: Clean Up Companion Releases` | You want to reconcile release retention outside a promotion run. | Validates the feed markers and deletes obsolete GitHub Releases. |\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/build-companion.yml` | Builds platform artifacts from a canonical source, publishes the verified release, promotes `test`, and runs cleanup. |\n| `.github/workflows/promote-companion-release.yml` | Promotes one published release to selected public feeds. |\n| `.github/scripts/promote_companion_release.py` | Resolves release assets and writes the feed JSON files. |\n| `.github/scripts/cleanup_companion_releases.py` | Validates feed references and applies Companion release retention. |\n| [helgeklein/sambee-companion](https://github.com/helgeklein/sambee-companion/) | Dedicated public release repository for Companion GitHub Releases and committed feed source files. |\n| `release-repo/docs/feeds` | Source-controlled feed JSON files that promotion updates and commits ([docs](../companion-channels-feeds-and-downloads/)). |\n\n## Published Artifact\n\nPublished Companion releases live in [helgeklein/sambee-companion](https://github.com/helgeklein/sambee-companion/) as GitHub Releases.\n\nEach release may contain:\n\n- Installer assets.\n- Tauri updater bundles.\n- `.sig` files for updater verification.\n- Release notes.\n", "2.0": "+++\ntitle = \"Companion Release Overview\"\n+++\n\nSambee Companion releases are built and published once. A successful build automatically promotes the release to `test`; later channel promotion rewrites public feed files without rebuilding binaries.\n\nKey differences between the Companion and Docker release paths:\n\n- Docker releases promote an already published container image.\n- Companion releases promote an already published GitHub Release by rewriting feeds read by Companion's auto-updater and by the Sambee frontend.\n- Docker images are available for Linux only, whereas Companion is a native app for Windows, Linux, and macOS. Each platform binary needs to be built on the respective OS.\n\n## Summary\n\nIf you want to take a new Companion version to `stable`, follow this order:\n\n1. Increment `VERSION` to the next `X.Y.Z` value and run `./scripts/sync-version`.\n1. Run `Release: Build Companion Artifact`:\n   - Select target platforms\n   - If the workflow's source version field is left blank, the artifact is built from the current commit in `main`, and the Git tag `build-vX.Y.Z` is created to reserve the version for the commit the artifact is built from.\n   - If a source version field is specified, the workflow verifies and repairs the artifact associated with the version via the Git tag used for reservation.\n1. The workflow builds and signs Companion, publishes the verified immutable release in the [Companion GitHub repo](https://github.com/sambee-app/sambee-companion/releases), promotes it to `test`, and cleans up obsolete releases.\n1. Test the published release through the `test` channel or by installing its release assets.\n1. Run `Release: Promote Companion Release` when the release is approved for `beta`, `stable`, or Sambee download metadata.\n\nOne published release can move from `test` to `beta` to `stable` without rebuilding binaries.\n\nRead the detailed pages in this order:\n\n1. [Build Companion Release](../build-companion-release/)\n1. [Promote Companion Release](../promote-companion-release/)\n1. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/)\n1. [Companion Release Cleanup](../companion-release-cleanup/)\n\n## Workflow Map\n\n| Workflow | When to use it | Result |\n|---|---|---|\n| Local `npm run check:rust:windows` | You want an early local Windows-target compatibility signal while working in Linux or the devcontainer. | Runs a Windows GNU target `cargo check` only. It does not create signed release assets. |\n| `Release: Build Companion Artifact` | You want to create release assets for one canonical version. | Builds the selected platform set, publishes the verified immutable GitHub Release, promotes only `test`, and cleans up obsolete releases. |\n| `Release: Promote Companion Release` | A published Companion release is approved for one or more channels or for Sambee download metadata. | Rewrites the selected feed files in `docs/feeds` of the release repository. |\n| `Maintenance: Clean Up Companion Releases` | You want to reconcile release retention outside a promotion run. | Validates the feed markers and deletes obsolete GitHub Releases. |\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/build-companion.yml` | Builds platform artifacts from a canonical source, publishes the verified release, promotes `test`, and runs cleanup. |\n| `.github/workflows/promote-companion-release.yml` | Promotes one published release to selected public feeds. |\n| `.github/scripts/promote_companion_release.py` | Resolves release assets and writes the feed JSON files. |\n| `.github/scripts/cleanup_companion_releases.py` | Validates feed references and applies Companion release retention. |\n| [sambee-app/sambee-companion](https://github.com/sambee-app/sambee-companion/) | Dedicated public release repository for Companion GitHub Releases and committed feed source files. |\n| `release-repo/docs/feeds` | Source-controlled feed JSON files that promotion updates and commits ([docs](../companion-channels-feeds-and-downloads/)). |\n\n## Published Artifact\n\nPublished Companion releases live in [sambee-app/sambee-companion](https://github.com/sambee-app/sambee-companion/) as GitHub Releases.\n\nEach release may contain:\n\n- Installer assets.\n- Tauri updater bundles.\n- `.sig` files for updater verification.\n- Release notes.\n"}, "flags": {"has_branched": true, "has_inherited": false, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/release-and-versioning/build-companion-release", "parent_id": "section:developer-guide/release-and-versioning", "depth": 2, "kind": "page", "label": "build-companion-release", "title": "Build Companion Release", "path": "developer-guide/release-and-versioning/build-companion-release", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "branched", "source_version": "0.7", "diff_added": 27, "diff_removed": 83}, "1.0": {"state": "branched", "source_version": "0.9", "diff_added": 25, "diff_removed": 39}, "2.0": {"state": "inherited", "source_version": "1.0"}}, "content_versions": {"0.7": "+++\ntitle = \"Build Companion Release\"\n+++\n\nThis is step 1 of the Companion release flow.\n\nUse this workflow to create the published Companion release assets for one version. GitHub Actions displays this workflow as `Release: Build Companion Artifact`. It builds release artifacts and creates a draft GitHub Release for a new, unique Companion tag, but it does not decide which update channels see that release.\n\n## Use It When\n\nRun the build workflow when:\n\n- You want to publish a new Companion version.\n- You want fresh installer and updater artifacts in the public Companion release repository.\n- You are preparing a release that may later be promoted to `test`, `beta`, `stable`, or Sambee download metadata.\n\nDo not use this workflow to change channel visibility.\nThat is the job of `Release: Promote Companion Release`.\n\n## Input\n\nThe manual workflow exposes one optional version override plus one checkbox per platform:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `publish_version_override` | Use a temporary version for this run instead of the checked-in `VERSION` value. Enter `major.minor.patch` with an optional prerelease suffix and optional build metadata. | Set it for prerelease, beta, rc, or test builds such as `0.8.0-beta.1` without changing the repository version. |\n| `build_all_platforms` | Include every supported platform in one run. | Check it for a normal full release. |\n| `build_linux_x64` | Include the Linux x64 build. | Check it when you need Linux release assets. |\n| `build_macos_arm64` | Include the macOS ARM64 build. | Check it when you need Apple Silicon macOS release assets. |\n| `build_windows_x64` | Include the Windows x64 build. | Check it when you need the standard Windows desktop release assets. |\n| `build_windows_arm64` | Include the Windows ARM64 build. | Check it when you need Windows on ARM release assets. |\n\nCurrent platform checkboxes are:\n\n- `build_all_platforms`\n- `build_linux_x64`\n- `build_macos_arm64`\n- `build_windows_x64`\n- `build_windows_arm64`\n\nIf you leave `publish_version_override` empty, the workflow uses the checked-in `VERSION` value and verifies that all synced metadata files are already committed.\nIf you set `publish_version_override`, the workflow writes that value into the synced Companion metadata files for this run only.\n\nUse the same version shape you would expect from a release tag:\n\n- `0.8.0` for a plain release version\n- `0.8.0-beta.1` or `0.8.0-rc.1` for prerelease candidates\n- `0.8.0-test.1` for temporary test builds\n- `0.8.0-beta.1+build.5` if you need build metadata\n\nIn other words, the accepted structure is `major.minor.patch`, optionally followed by `-prerelease` and then `+build-metadata`.\n\nThe workflow fails early if the resulting release tag already exists in `helgeklein/sambee-companion`, whether that release is still a draft or already published.\nChoose a distinct prerelease suffix such as `-beta.1` or `-rc.1` when you need another build before the official release.\n\nIf you check `build_all_platforms`, the workflow builds the full matrix and ignores the per-platform checkboxes.\nIf you leave every checkbox cleared, the workflow does not build anything.\nCheck only the platforms you want when you deliberately need a partial release.\n\n## What It Does\n\nBefore packaging, the workflow:\n\n1. Checks out the main repository.\n2. Resolves the effective Companion version from either the checked-in `VERSION` file or `publish_version_override`.\n3. Fails early if the resulting release tag already exists in `helgeklein/sambee-companion` as either a draft or a published release.\n4. Either runs version-sync verification or applies the temporary override version for this run.\n5. Builds the platform matrix derived from the checked boxes.\n6. Uses Tauri packaging to upload assets into a draft release in `helgeklein/sambee-companion`.\n\nThe build matrix is currently configured for:\n\n- Linux x64.\n- macOS ARM64.\n- Windows x64.\n- Windows ARM64.\n\nIf you build only a subset, the resulting release exposes only that subset.\nPromotion works from the assets actually present in the published release, not from an assumed full matrix.\n\n## Published Output\n\nThe workflow publishes assets into a draft GitHub Release in `helgeklein/sambee-companion`.\n\nThat release can contain:\n\n- Installer assets.\n- Tauri updater bundles.\n- `.sig` files for updater verification.\n- Release notes.\n\nThe workflow uses the tag format `companion-v\u003ceffective-version\u003e`.\n\nThat means an override such as `0.8.0-beta.1` produces the tag `companion-v0.8.0-beta.1`.\n\nChannel visibility is still unset at this stage.\nThe build is only a published candidate until a later promotion updates the feed files.\n\n## Review Before Publish\n\nBefore you publish the draft release, verify:\n\n- The version metadata is correct.\n- The release tag is the distinct version you intended to publish.\n- The expected platform assets are present.\n- The updater bundle and `.sig` pairs look complete for the platforms you expect to promote.\n- The release notes are acceptable for public distribution.\n\nIf the draft contents are wrong, fix the release process and produce a new release instead of trying to patch channel metadata around a bad artifact set.\n\n## Run the Workflow\n\nUse this order when you are preparing a Companion release:\n\n1. For an official release, merge the version-sync changes for the checked-in version you want to ship.\n2. For a prerelease or test build, decide the distinct override version you want to use for this run, for example `0.8.0-beta.1`.\n3. Start `Release: Build Companion Artifact` from the commit you want to release.\n4. Leave `publish_version_override` empty for the checked-in version, or set it to the temporary prerelease version you want for this run.\n5. Check `build_all_platforms` for a normal full release, or check only the specific platform boxes you want for a partial release. If you leave all boxes cleared, the workflow skips artifact builds.\n6. Wait for the workflow to create the draft release in `helgeklein/sambee-companion`.\n7. Review the uploaded assets and publish the draft release.\n8. Continue with [Promote Companion Release](../promote-companion-release/).\n", "0.8": "+++\ntitle = \"Build Companion Release\"\n+++\n\nThis is step 1 of the Companion release flow.\n\nUse this workflow to create the published Companion release assets for one version. GitHub Actions displays this workflow as `Release: Build Companion Artifact`. It builds release artifacts and creates a draft GitHub Release for a new, unique Companion tag, but it does not decide which update channels see that release.\n\n## Use It When\n\nRun the build workflow when:\n\n- You want to publish a new Companion version.\n- You want fresh installer and updater artifacts in the public Companion release repository.\n- You are preparing a release that may later be promoted to `test`, `beta`, `stable`, or Sambee download metadata.\n\nDo not use this workflow to change channel visibility.\nThat is the job of `Release: Promote Companion Release`.\n\n## Input\n\nThe manual workflow exposes one optional version override plus one checkbox per platform:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `publish_version_override` | Use a temporary version for this run instead of the checked-in `VERSION` value. Enter `major.minor.patch` with an optional prerelease suffix and optional build metadata. | Set it for prerelease, beta, rc, or test builds such as `0.8.0-beta.1` without changing the repository version. |\n| `build_all_platforms` | Include every supported platform in one run. | Check it for a normal full release. |\n| `build_linux_x64` | Include the Linux x64 build. | Check it when you need Linux release assets. |\n| `build_macos_arm64` | Include the macOS ARM64 build. | Check it when you need Apple Silicon macOS release assets. |\n| `build_windows_x64` | Include the Windows x64 build. | Check it when you need the standard Windows desktop release assets. |\n| `build_windows_arm64` | Include the Windows ARM64 build. | Check it when you need Windows on ARM release assets. |\n\nCurrent platform checkboxes are:\n\n- `build_all_platforms`\n- `build_linux_x64`\n- `build_macos_arm64`\n- `build_windows_x64`\n- `build_windows_arm64`\n\nIf you leave `publish_version_override` empty, the workflow uses the checked-in `VERSION` value and verifies that all synced metadata files are already committed.\nIf you set `publish_version_override`, the workflow writes that value into the synced Companion metadata files for this run only.\n\nUse the same version shape you would expect from a release tag:\n\n- `0.8.0` for a plain release version\n- `0.8.0-beta.1` or `0.8.0-rc.1` for prerelease candidates\n- `0.8.0-test.1` for temporary test builds\n- `0.8.0-beta.1+build.5` if you need build metadata\n\nIn other words, the accepted structure is `major.minor.patch`, optionally followed by `-prerelease` and then `+build-metadata`.\n\nThe workflow fails early if the resulting release tag already exists in `helgeklein/sambee-companion`, whether that release is still a draft or already published.\nChoose a distinct prerelease suffix such as `-beta.1` or `-rc.1` when you need another build before the official release.\n\nIf you check `build_all_platforms`, the workflow builds the full matrix and ignores the per-platform checkboxes.\nIf you leave every checkbox cleared, the workflow does not build anything.\nCheck only the platforms you want when you deliberately need a partial release.\n\n## What It Does\n\nBefore packaging, the workflow:\n\n1. Checks out the main repository.\n2. Resolves the effective Companion version from either the checked-in `VERSION` file or `publish_version_override`.\n3. Fails early if the resulting release tag already exists in `helgeklein/sambee-companion` as either a draft or a published release.\n4. Either runs version-sync verification or applies the temporary override version for this run.\n5. Builds the platform matrix derived from the checked boxes.\n6. Uses Tauri packaging to upload assets into a draft release in `helgeklein/sambee-companion`.\n\nThe build matrix is currently configured for:\n\n- Linux x64.\n- macOS ARM64.\n- Windows x64.\n- Windows ARM64.\n\nIf you build only a subset, the resulting release exposes only that subset.\nPromotion works from the assets actually present in the published release, not from an assumed full matrix.\n\n## Published Output\n\nThe workflow publishes assets into a draft GitHub Release in `helgeklein/sambee-companion`.\n\nThat release can contain:\n\n- Installer assets.\n- Tauri updater bundles.\n- `.sig` files for updater verification.\n- Release notes.\n\nThe workflow uses the tag format `companion-v\u003ceffective-version\u003e`.\n\nThat means an override such as `0.8.0-beta.1` produces the tag `companion-v0.8.0-beta.1`.\n\nChannel visibility is still unset at this stage.\nThe build is only a published candidate until a later promotion updates the feed files.\n\n## Review Before Publish\n\nBefore you publish the draft release, verify:\n\n- The version metadata is correct.\n- The release tag is the distinct version you intended to publish.\n- The expected platform assets are present.\n- The updater bundle and `.sig` pairs look complete for the platforms you expect to promote.\n- The release notes are acceptable for public distribution.\n\nIf the draft contents are wrong, fix the release process and produce a new release instead of trying to patch channel metadata around a bad artifact set.\n\n## Run the Workflow\n\nUse this order when you are preparing a Companion release:\n\n1. For an official release, merge the version-sync changes for the checked-in version you want to ship.\n2. For a prerelease or test build, decide the distinct override version you want to use for this run, for example `0.8.0-beta.1`.\n3. Start `Release: Build Companion Artifact` from the commit you want to release.\n4. Leave `publish_version_override` empty for the checked-in version, or set it to the temporary prerelease version you want for this run.\n5. Check `build_all_platforms` for a normal full release, or check only the specific platform boxes you want for a partial release. If you leave all boxes cleared, the workflow skips artifact builds.\n6. Wait for the workflow to create the draft release in `helgeklein/sambee-companion`.\n7. Review the uploaded assets and publish the draft release.\n8. Continue with [Promote Companion Release](../promote-companion-release/).\n", "0.9": "+++\ntitle = \"Build Companion Release\"\n+++\n\nThis is step 1 of the Companion release flow.\n\nUse this workflow to create Companion release assets for one immutable build version. GitHub Actions displays this workflow as `Release: Build Companion Artifact`. It creates builds for the selected platforms, which are then uploaded to the GitHub draft release by a finalizer.\n\n## Input\n\nThe manual workflow exposes an optional existing build-version selector plus one checkbox per platform:\n\n| Input | What it means |\n|---|---|\n| `build_version` | Build the commit with the `build-vX.Y.Z` tag. Leave empty to build the latest commit and set the `build-vX.Y.Z` tag on that commit. |\n| `build_all_platforms` | Include every supported platform in one run. |\n| `build_linux_x64` | Include the Linux x64 build. |\n| `build_macos_arm64` | Include the macOS ARM64 build. |\n| `build_windows_x64` | Include the Windows x64 build. |\n| `build_windows_arm64` | Include the Windows ARM64 build. |\n\nNew builds must be dispatched from `main`. The workflow verifies synchronized metadata, reserves `build-vX.Y.Z` for the exact source commit, and rejects any version that is not plain numeric `X.Y.Z`. It never changes an existing build tag.\n\nIf you check `build_all_platforms`, the workflow builds the full matrix and ignores the per-platform checkboxes.\nIf you leave every checkbox cleared, the workflow does not build anything.\nCheck only the platforms you want when you deliberately need a partial release.\n\n## What It Does\n\nBefore packaging, the workflow:\n\n1. Checks out the main repository.\n2. Resolves the canonical `build-vX.Y.Z` source commit or assigns it to the latest commit.\n3. Verifies synchronized version metadata.\n4. Builds the platform matrix derived from the checked boxes.\n5. Writes a per-platform artifact manifest with package names, SHA-256 checksums, installer/updater/signature roles, platform, and target; then uploads uniquely named private Actions artifacts.\n6. The finalizer downloads every retained artifact, verifies the manifests and complete package sets, writes a public aggregate manifest, provenance, and completion marker, then creates or resumes the external draft release.\n\nIf you build only a subset, the resulting release exposes only that subset.\nPromotion works from the assets actually present in the published release, not from an assumed full matrix.\n\n## Build Output\n\nThe finalizer uploads assets into a draft GitHub Release in `helgeklein/sambee-companion`.\n\nThat release can contain:\n\n- Installer assets.\n- Tauri updater bundles.\n- `.sig` files for updater verification.\n- A public aggregate artifact manifest, uploaded before all package assets.\n- Release provenance and a completion marker binding the release tag, aggregate-manifest digest, provenance digest, and exact expected assets.\n\n### Recovery And Immutability\n\nThe draft GitHub release is immutable once any asset is present: the finalizer uploads a missing asset or accepts an existing byte-identical asset, and rejects a conflicting replacement.\n\nIf a finalizer is interrupted, a later run uses the exact retained Actions artifact IDs, digests, originating run ID, run attempt, platform, and target recorded in draft provenance. It does not rebuild matrix artifacts. Expired, missing, ambiguous, or mismatched retained artifacts require a new `Z` candidate.\n\nGitHub Actions concurrency is mutual exclusion, not a FIFO queue: only one pending run is retained for the `companion-release-publication` lock. Avoid stacking dispatches. A superseded pending dispatch is safe to submit again because it never reached a publication step.\n\n## Review and Publish\n\nReview the draft GitHub release created or updated by this workflow. Then publish it.\n\nPublishing assigns the tag `companion-vX.Y.Z`.\n", "1.0": "+++\ntitle = \"Build Companion Release\"\n+++\n\nThis is step 1 of the Companion release flow.\n\nUse `Release: Build Companion Artifact` to create one immutable Companion release from a canonical build version. The workflow builds the selected platforms, verifies their manifests, publishes the GitHub Release automatically, promotes it to the `test` updater channel, and removes obsolete releases.\n\n## Input\n\nThe workflow accepts an optional existing build version and platform checkboxes.\n\n| Input | What it means |\n|---|---|\n| `build_version` | Build the commit reserved by `build-vX.Y.Z`. Leave it empty to reserve the current `main` commit. |\n| `build_all_platforms` | Include every supported platform. |\n| Platform checkboxes | Build only the selected platforms. |\n\nNew builds must start from `main`. The workflow verifies synchronized version metadata, reserves the exact source commit, and accepts only plain numeric `X.Y.Z` versions. It never changes an existing build tag.\n\nIf no platform is selected, the workflow does not create or promote a release.\n\n## What It Does\n\nThe workflow:\n\n1. Resolves the canonical `build-vX.Y.Z` source commit.\n1. Builds, signs, and records a manifest for every selected platform.\n1. Downloads and verifies the retained build artifacts in the finalizer.\n1. Creates a private provisional GitHub Release while assets are uploaded.\n1. Verifies the aggregate manifest, provenance, completion marker, and every release asset.\n1. Publishes `companion-vX.Y.Z` automatically after verification succeeds.\n1. Promotes only the Companion `test` updater feed to the published release.\n1. Cleans up obsolete Companion GitHub Releases.\n\nThe temporary draft is an upload and recovery boundary, not a review step. A release becomes public only after its complete verified asset set is present.\n\n## Recovery And Immutability\n\nOnce an asset is present, the provisional release accepts only a missing asset or an existing byte-identical asset. A conflicting replacement fails.\n\nIf finalization is interrupted, a later run uses the exact retained Actions artifact IDs, digests, run ID, attempt, platform, and target recorded in provenance. It does not rebuild the artifact matrix. Expired, missing, ambiguous, or mismatched retained artifacts require a new `Z` candidate.\n\nIf publication succeeds but the `test` feed push fails, rerun the build workflow with the same build version. It verifies the already published immutable release and retries promotion without rebuilding binaries.\n\nGitHub Actions concurrency is mutual exclusion, not a FIFO queue: only one pending run is retained for `companion-release-publication`. Avoid stacking dispatches.\n\n## What Happens Next\n\nThe automatic flow changes only `test`. Use [Promote Companion Release](../promote-companion-release/) later when the same published release is approved for `beta`, `stable`, or Sambee download metadata.\n\nSee [Companion Release Cleanup](../companion-release-cleanup/) for the retention policy.", "2.0": "+++\ntitle = \"Build Companion Release\"\n+++\n\nThis is step 1 of the Companion release flow.\n\nUse `Release: Build Companion Artifact` to create one immutable Companion release from a canonical build version. The workflow builds the selected platforms, verifies their manifests, publishes the GitHub Release automatically, promotes it to the `test` updater channel, and removes obsolete releases.\n\n## Input\n\nThe workflow accepts an optional existing build version and platform checkboxes.\n\n| Input | What it means |\n|---|---|\n| `build_version` | Build the commit reserved by `build-vX.Y.Z`. Leave it empty to reserve the current `main` commit. |\n| `build_all_platforms` | Include every supported platform. |\n| Platform checkboxes | Build only the selected platforms. |\n\nNew builds must start from `main`. The workflow verifies synchronized version metadata, reserves the exact source commit, and accepts only plain numeric `X.Y.Z` versions. It never changes an existing build tag.\n\nIf no platform is selected, the workflow does not create or promote a release.\n\n## What It Does\n\nThe workflow:\n\n1. Resolves the canonical `build-vX.Y.Z` source commit.\n1. Builds, signs, and records a manifest for every selected platform.\n1. Downloads and verifies the retained build artifacts in the finalizer.\n1. Creates a private provisional GitHub Release while assets are uploaded.\n1. Verifies the aggregate manifest, provenance, completion marker, and every release asset.\n1. Publishes `companion-vX.Y.Z` automatically after verification succeeds.\n1. Promotes only the Companion `test` updater feed to the published release.\n1. Cleans up obsolete Companion GitHub Releases.\n\nThe temporary draft is an upload and recovery boundary, not a review step. A release becomes public only after its complete verified asset set is present.\n\n## Recovery And Immutability\n\nOnce an asset is present, the provisional release accepts only a missing asset or an existing byte-identical asset. A conflicting replacement fails.\n\nIf finalization is interrupted, a later run uses the exact retained Actions artifact IDs, digests, run ID, attempt, platform, and target recorded in provenance. It does not rebuild the artifact matrix. Expired, missing, ambiguous, or mismatched retained artifacts require a new `Z` candidate.\n\nIf publication succeeds but the `test` feed push fails, rerun the build workflow with the same build version. It verifies the already published immutable release and retries promotion without rebuilding binaries.\n\nGitHub Actions concurrency is mutual exclusion, not a FIFO queue: only one pending run is retained for `companion-release-publication`. Avoid stacking dispatches.\n\n## What Happens Next\n\nThe automatic flow changes only `test`. Use [Promote Companion Release](../promote-companion-release/) later when the same published release is approved for `beta`, `stable`, or Sambee download metadata.\n\nSee [Companion Release Cleanup](../companion-release-cleanup/) for the retention policy."}, "page_contents": {"0.7": "+++\ntitle = \"Build Companion Release\"\n+++\n\nThis is step 1 of the Companion release flow.\n\nUse this workflow to create the published Companion release assets for one version. GitHub Actions displays this workflow as `Release: Build Companion Artifact`. It builds release artifacts and creates a draft GitHub Release for a new, unique Companion tag, but it does not decide which update channels see that release.\n\n## Use It When\n\nRun the build workflow when:\n\n- You want to publish a new Companion version.\n- You want fresh installer and updater artifacts in the public Companion release repository.\n- You are preparing a release that may later be promoted to `test`, `beta`, `stable`, or Sambee download metadata.\n\nDo not use this workflow to change channel visibility.\nThat is the job of `Release: Promote Companion Release`.\n\n## Input\n\nThe manual workflow exposes one optional version override plus one checkbox per platform:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `publish_version_override` | Use a temporary version for this run instead of the checked-in `VERSION` value. Enter `major.minor.patch` with an optional prerelease suffix and optional build metadata. | Set it for prerelease, beta, rc, or test builds such as `0.8.0-beta.1` without changing the repository version. |\n| `build_all_platforms` | Include every supported platform in one run. | Check it for a normal full release. |\n| `build_linux_x64` | Include the Linux x64 build. | Check it when you need Linux release assets. |\n| `build_macos_arm64` | Include the macOS ARM64 build. | Check it when you need Apple Silicon macOS release assets. |\n| `build_windows_x64` | Include the Windows x64 build. | Check it when you need the standard Windows desktop release assets. |\n| `build_windows_arm64` | Include the Windows ARM64 build. | Check it when you need Windows on ARM release assets. |\n\nCurrent platform checkboxes are:\n\n- `build_all_platforms`\n- `build_linux_x64`\n- `build_macos_arm64`\n- `build_windows_x64`\n- `build_windows_arm64`\n\nIf you leave `publish_version_override` empty, the workflow uses the checked-in `VERSION` value and verifies that all synced metadata files are already committed.\nIf you set `publish_version_override`, the workflow writes that value into the synced Companion metadata files for this run only.\n\nUse the same version shape you would expect from a release tag:\n\n- `0.8.0` for a plain release version\n- `0.8.0-beta.1` or `0.8.0-rc.1` for prerelease candidates\n- `0.8.0-test.1` for temporary test builds\n- `0.8.0-beta.1+build.5` if you need build metadata\n\nIn other words, the accepted structure is `major.minor.patch`, optionally followed by `-prerelease` and then `+build-metadata`.\n\nThe workflow fails early if the resulting release tag already exists in `helgeklein/sambee-companion`, whether that release is still a draft or already published.\nChoose a distinct prerelease suffix such as `-beta.1` or `-rc.1` when you need another build before the official release.\n\nIf you check `build_all_platforms`, the workflow builds the full matrix and ignores the per-platform checkboxes.\nIf you leave every checkbox cleared, the workflow does not build anything.\nCheck only the platforms you want when you deliberately need a partial release.\n\n## What It Does\n\nBefore packaging, the workflow:\n\n1. Checks out the main repository.\n2. Resolves the effective Companion version from either the checked-in `VERSION` file or `publish_version_override`.\n3. Fails early if the resulting release tag already exists in `helgeklein/sambee-companion` as either a draft or a published release.\n4. Either runs version-sync verification or applies the temporary override version for this run.\n5. Builds the platform matrix derived from the checked boxes.\n6. Uses Tauri packaging to upload assets into a draft release in `helgeklein/sambee-companion`.\n\nThe build matrix is currently configured for:\n\n- Linux x64.\n- macOS ARM64.\n- Windows x64.\n- Windows ARM64.\n\nIf you build only a subset, the resulting release exposes only that subset.\nPromotion works from the assets actually present in the published release, not from an assumed full matrix.\n\n## Published Output\n\nThe workflow publishes assets into a draft GitHub Release in `helgeklein/sambee-companion`.\n\nThat release can contain:\n\n- Installer assets.\n- Tauri updater bundles.\n- `.sig` files for updater verification.\n- Release notes.\n\nThe workflow uses the tag format `companion-v\u003ceffective-version\u003e`.\n\nThat means an override such as `0.8.0-beta.1` produces the tag `companion-v0.8.0-beta.1`.\n\nChannel visibility is still unset at this stage.\nThe build is only a published candidate until a later promotion updates the feed files.\n\n## Review Before Publish\n\nBefore you publish the draft release, verify:\n\n- The version metadata is correct.\n- The release tag is the distinct version you intended to publish.\n- The expected platform assets are present.\n- The updater bundle and `.sig` pairs look complete for the platforms you expect to promote.\n- The release notes are acceptable for public distribution.\n\nIf the draft contents are wrong, fix the release process and produce a new release instead of trying to patch channel metadata around a bad artifact set.\n\n## Run the Workflow\n\nUse this order when you are preparing a Companion release:\n\n1. For an official release, merge the version-sync changes for the checked-in version you want to ship.\n2. For a prerelease or test build, decide the distinct override version you want to use for this run, for example `0.8.0-beta.1`.\n3. Start `Release: Build Companion Artifact` from the commit you want to release.\n4. Leave `publish_version_override` empty for the checked-in version, or set it to the temporary prerelease version you want for this run.\n5. Check `build_all_platforms` for a normal full release, or check only the specific platform boxes you want for a partial release. If you leave all boxes cleared, the workflow skips artifact builds.\n6. Wait for the workflow to create the draft release in `helgeklein/sambee-companion`.\n7. Review the uploaded assets and publish the draft release.\n8. Continue with [Promote Companion Release](../promote-companion-release/).\n", "0.8": "+++\ntitle = \"Build Companion Release\"\n+++\n\nThis is step 1 of the Companion release flow.\n\nUse this workflow to create the published Companion release assets for one version. GitHub Actions displays this workflow as `Release: Build Companion Artifact`. It builds release artifacts and creates a draft GitHub Release for a new, unique Companion tag, but it does not decide which update channels see that release.\n\n## Use It When\n\nRun the build workflow when:\n\n- You want to publish a new Companion version.\n- You want fresh installer and updater artifacts in the public Companion release repository.\n- You are preparing a release that may later be promoted to `test`, `beta`, `stable`, or Sambee download metadata.\n\nDo not use this workflow to change channel visibility.\nThat is the job of `Release: Promote Companion Release`.\n\n## Input\n\nThe manual workflow exposes one optional version override plus one checkbox per platform:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `publish_version_override` | Use a temporary version for this run instead of the checked-in `VERSION` value. Enter `major.minor.patch` with an optional prerelease suffix and optional build metadata. | Set it for prerelease, beta, rc, or test builds such as `0.8.0-beta.1` without changing the repository version. |\n| `build_all_platforms` | Include every supported platform in one run. | Check it for a normal full release. |\n| `build_linux_x64` | Include the Linux x64 build. | Check it when you need Linux release assets. |\n| `build_macos_arm64` | Include the macOS ARM64 build. | Check it when you need Apple Silicon macOS release assets. |\n| `build_windows_x64` | Include the Windows x64 build. | Check it when you need the standard Windows desktop release assets. |\n| `build_windows_arm64` | Include the Windows ARM64 build. | Check it when you need Windows on ARM release assets. |\n\nCurrent platform checkboxes are:\n\n- `build_all_platforms`\n- `build_linux_x64`\n- `build_macos_arm64`\n- `build_windows_x64`\n- `build_windows_arm64`\n\nIf you leave `publish_version_override` empty, the workflow uses the checked-in `VERSION` value and verifies that all synced metadata files are already committed.\nIf you set `publish_version_override`, the workflow writes that value into the synced Companion metadata files for this run only.\n\nUse the same version shape you would expect from a release tag:\n\n- `0.8.0` for a plain release version\n- `0.8.0-beta.1` or `0.8.0-rc.1` for prerelease candidates\n- `0.8.0-test.1` for temporary test builds\n- `0.8.0-beta.1+build.5` if you need build metadata\n\nIn other words, the accepted structure is `major.minor.patch`, optionally followed by `-prerelease` and then `+build-metadata`.\n\nThe workflow fails early if the resulting release tag already exists in `helgeklein/sambee-companion`, whether that release is still a draft or already published.\nChoose a distinct prerelease suffix such as `-beta.1` or `-rc.1` when you need another build before the official release.\n\nIf you check `build_all_platforms`, the workflow builds the full matrix and ignores the per-platform checkboxes.\nIf you leave every checkbox cleared, the workflow does not build anything.\nCheck only the platforms you want when you deliberately need a partial release.\n\n## What It Does\n\nBefore packaging, the workflow:\n\n1. Checks out the main repository.\n2. Resolves the effective Companion version from either the checked-in `VERSION` file or `publish_version_override`.\n3. Fails early if the resulting release tag already exists in `helgeklein/sambee-companion` as either a draft or a published release.\n4. Either runs version-sync verification or applies the temporary override version for this run.\n5. Builds the platform matrix derived from the checked boxes.\n6. Uses Tauri packaging to upload assets into a draft release in `helgeklein/sambee-companion`.\n\nThe build matrix is currently configured for:\n\n- Linux x64.\n- macOS ARM64.\n- Windows x64.\n- Windows ARM64.\n\nIf you build only a subset, the resulting release exposes only that subset.\nPromotion works from the assets actually present in the published release, not from an assumed full matrix.\n\n## Published Output\n\nThe workflow publishes assets into a draft GitHub Release in `helgeklein/sambee-companion`.\n\nThat release can contain:\n\n- Installer assets.\n- Tauri updater bundles.\n- `.sig` files for updater verification.\n- Release notes.\n\nThe workflow uses the tag format `companion-v\u003ceffective-version\u003e`.\n\nThat means an override such as `0.8.0-beta.1` produces the tag `companion-v0.8.0-beta.1`.\n\nChannel visibility is still unset at this stage.\nThe build is only a published candidate until a later promotion updates the feed files.\n\n## Review Before Publish\n\nBefore you publish the draft release, verify:\n\n- The version metadata is correct.\n- The release tag is the distinct version you intended to publish.\n- The expected platform assets are present.\n- The updater bundle and `.sig` pairs look complete for the platforms you expect to promote.\n- The release notes are acceptable for public distribution.\n\nIf the draft contents are wrong, fix the release process and produce a new release instead of trying to patch channel metadata around a bad artifact set.\n\n## Run the Workflow\n\nUse this order when you are preparing a Companion release:\n\n1. For an official release, merge the version-sync changes for the checked-in version you want to ship.\n2. For a prerelease or test build, decide the distinct override version you want to use for this run, for example `0.8.0-beta.1`.\n3. Start `Release: Build Companion Artifact` from the commit you want to release.\n4. Leave `publish_version_override` empty for the checked-in version, or set it to the temporary prerelease version you want for this run.\n5. Check `build_all_platforms` for a normal full release, or check only the specific platform boxes you want for a partial release. If you leave all boxes cleared, the workflow skips artifact builds.\n6. Wait for the workflow to create the draft release in `helgeklein/sambee-companion`.\n7. Review the uploaded assets and publish the draft release.\n8. Continue with [Promote Companion Release](../promote-companion-release/).\n", "0.9": "+++\ntitle = \"Build Companion Release\"\n+++\n\nThis is step 1 of the Companion release flow.\n\nUse this workflow to create Companion release assets for one immutable build version. GitHub Actions displays this workflow as `Release: Build Companion Artifact`. It creates builds for the selected platforms, which are then uploaded to the GitHub draft release by a finalizer.\n\n## Input\n\nThe manual workflow exposes an optional existing build-version selector plus one checkbox per platform:\n\n| Input | What it means |\n|---|---|\n| `build_version` | Build the commit with the `build-vX.Y.Z` tag. Leave empty to build the latest commit and set the `build-vX.Y.Z` tag on that commit. |\n| `build_all_platforms` | Include every supported platform in one run. |\n| `build_linux_x64` | Include the Linux x64 build. |\n| `build_macos_arm64` | Include the macOS ARM64 build. |\n| `build_windows_x64` | Include the Windows x64 build. |\n| `build_windows_arm64` | Include the Windows ARM64 build. |\n\nNew builds must be dispatched from `main`. The workflow verifies synchronized metadata, reserves `build-vX.Y.Z` for the exact source commit, and rejects any version that is not plain numeric `X.Y.Z`. It never changes an existing build tag.\n\nIf you check `build_all_platforms`, the workflow builds the full matrix and ignores the per-platform checkboxes.\nIf you leave every checkbox cleared, the workflow does not build anything.\nCheck only the platforms you want when you deliberately need a partial release.\n\n## What It Does\n\nBefore packaging, the workflow:\n\n1. Checks out the main repository.\n2. Resolves the canonical `build-vX.Y.Z` source commit or assigns it to the latest commit.\n3. Verifies synchronized version metadata.\n4. Builds the platform matrix derived from the checked boxes.\n5. Writes a per-platform artifact manifest with package names, SHA-256 checksums, installer/updater/signature roles, platform, and target; then uploads uniquely named private Actions artifacts.\n6. The finalizer downloads every retained artifact, verifies the manifests and complete package sets, writes a public aggregate manifest, provenance, and completion marker, then creates or resumes the external draft release.\n\nIf you build only a subset, the resulting release exposes only that subset.\nPromotion works from the assets actually present in the published release, not from an assumed full matrix.\n\n## Build Output\n\nThe finalizer uploads assets into a draft GitHub Release in `helgeklein/sambee-companion`.\n\nThat release can contain:\n\n- Installer assets.\n- Tauri updater bundles.\n- `.sig` files for updater verification.\n- A public aggregate artifact manifest, uploaded before all package assets.\n- Release provenance and a completion marker binding the release tag, aggregate-manifest digest, provenance digest, and exact expected assets.\n\n### Recovery And Immutability\n\nThe draft GitHub release is immutable once any asset is present: the finalizer uploads a missing asset or accepts an existing byte-identical asset, and rejects a conflicting replacement.\n\nIf a finalizer is interrupted, a later run uses the exact retained Actions artifact IDs, digests, originating run ID, run attempt, platform, and target recorded in draft provenance. It does not rebuild matrix artifacts. Expired, missing, ambiguous, or mismatched retained artifacts require a new `Z` candidate.\n\nGitHub Actions concurrency is mutual exclusion, not a FIFO queue: only one pending run is retained for the `companion-release-publication` lock. Avoid stacking dispatches. A superseded pending dispatch is safe to submit again because it never reached a publication step.\n\n## Review and Publish\n\nReview the draft GitHub release created or updated by this workflow. Then publish it.\n\nPublishing assigns the tag `companion-vX.Y.Z`.\n", "1.0": "+++\ntitle = \"Build Companion Release\"\n+++\n\nThis is step 1 of the Companion release flow.\n\nUse `Release: Build Companion Artifact` to create one immutable Companion release from a canonical build version. The workflow builds the selected platforms, verifies their manifests, publishes the GitHub Release automatically, promotes it to the `test` updater channel, and removes obsolete releases.\n\n## Input\n\nThe workflow accepts an optional existing build version and platform checkboxes.\n\n| Input | What it means |\n|---|---|\n| `build_version` | Build the commit reserved by `build-vX.Y.Z`. Leave it empty to reserve the current `main` commit. |\n| `build_all_platforms` | Include every supported platform. |\n| Platform checkboxes | Build only the selected platforms. |\n\nNew builds must start from `main`. The workflow verifies synchronized version metadata, reserves the exact source commit, and accepts only plain numeric `X.Y.Z` versions. It never changes an existing build tag.\n\nIf no platform is selected, the workflow does not create or promote a release.\n\n## What It Does\n\nThe workflow:\n\n1. Resolves the canonical `build-vX.Y.Z` source commit.\n1. Builds, signs, and records a manifest for every selected platform.\n1. Downloads and verifies the retained build artifacts in the finalizer.\n1. Creates a private provisional GitHub Release while assets are uploaded.\n1. Verifies the aggregate manifest, provenance, completion marker, and every release asset.\n1. Publishes `companion-vX.Y.Z` automatically after verification succeeds.\n1. Promotes only the Companion `test` updater feed to the published release.\n1. Cleans up obsolete Companion GitHub Releases.\n\nThe temporary draft is an upload and recovery boundary, not a review step. A release becomes public only after its complete verified asset set is present.\n\n## Recovery And Immutability\n\nOnce an asset is present, the provisional release accepts only a missing asset or an existing byte-identical asset. A conflicting replacement fails.\n\nIf finalization is interrupted, a later run uses the exact retained Actions artifact IDs, digests, run ID, attempt, platform, and target recorded in provenance. It does not rebuild the artifact matrix. Expired, missing, ambiguous, or mismatched retained artifacts require a new `Z` candidate.\n\nIf publication succeeds but the `test` feed push fails, rerun the build workflow with the same build version. It verifies the already published immutable release and retries promotion without rebuilding binaries.\n\nGitHub Actions concurrency is mutual exclusion, not a FIFO queue: only one pending run is retained for `companion-release-publication`. Avoid stacking dispatches.\n\n## What Happens Next\n\nThe automatic flow changes only `test`. Use [Promote Companion Release](../promote-companion-release/) later when the same published release is approved for `beta`, `stable`, or Sambee download metadata.\n\nSee [Companion Release Cleanup](../companion-release-cleanup/) for the retention policy.", "2.0": "+++\ntitle = \"Build Companion Release\"\n+++\n\nThis is step 1 of the Companion release flow.\n\nUse `Release: Build Companion Artifact` to create one immutable Companion release from a canonical build version. The workflow builds the selected platforms, verifies their manifests, publishes the GitHub Release automatically, promotes it to the `test` updater channel, and removes obsolete releases.\n\n## Input\n\nThe workflow accepts an optional existing build version and platform checkboxes.\n\n| Input | What it means |\n|---|---|\n| `build_version` | Build the commit reserved by `build-vX.Y.Z`. Leave it empty to reserve the current `main` commit. |\n| `build_all_platforms` | Include every supported platform. |\n| Platform checkboxes | Build only the selected platforms. |\n\nNew builds must start from `main`. The workflow verifies synchronized version metadata, reserves the exact source commit, and accepts only plain numeric `X.Y.Z` versions. It never changes an existing build tag.\n\nIf no platform is selected, the workflow does not create or promote a release.\n\n## What It Does\n\nThe workflow:\n\n1. Resolves the canonical `build-vX.Y.Z` source commit.\n1. Builds, signs, and records a manifest for every selected platform.\n1. Downloads and verifies the retained build artifacts in the finalizer.\n1. Creates a private provisional GitHub Release while assets are uploaded.\n1. Verifies the aggregate manifest, provenance, completion marker, and every release asset.\n1. Publishes `companion-vX.Y.Z` automatically after verification succeeds.\n1. Promotes only the Companion `test` updater feed to the published release.\n1. Cleans up obsolete Companion GitHub Releases.\n\nThe temporary draft is an upload and recovery boundary, not a review step. A release becomes public only after its complete verified asset set is present.\n\n## Recovery And Immutability\n\nOnce an asset is present, the provisional release accepts only a missing asset or an existing byte-identical asset. A conflicting replacement fails.\n\nIf finalization is interrupted, a later run uses the exact retained Actions artifact IDs, digests, run ID, attempt, platform, and target recorded in provenance. It does not rebuild the artifact matrix. Expired, missing, ambiguous, or mismatched retained artifacts require a new `Z` candidate.\n\nIf publication succeeds but the `test` feed push fails, rerun the build workflow with the same build version. It verifies the already published immutable release and retries promotion without rebuilding binaries.\n\nGitHub Actions concurrency is mutual exclusion, not a FIFO queue: only one pending run is retained for `companion-release-publication`. Avoid stacking dispatches.\n\n## What Happens Next\n\nThe automatic flow changes only `test`. Use [Promote Companion Release](../promote-companion-release/) later when the same published release is approved for `beta`, `stable`, or Sambee download metadata.\n\nSee [Companion Release Cleanup](../companion-release-cleanup/) for the retention policy."}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/release-and-versioning/promote-companion-release", "parent_id": "section:developer-guide/release-and-versioning", "depth": 2, "kind": "page", "label": "promote-companion-release", "title": "Promote Companion Release", "path": "developer-guide/release-and-versioning/promote-companion-release", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "branched", "source_version": "0.7", "diff_added": 5, "diff_removed": 1}, "1.0": {"state": "branched", "source_version": "0.9", "diff_added": 18, "diff_removed": 16}, "2.0": {"state": "branched", "source_version": "1.0", "diff_added": 2, "diff_removed": 3}}, "content_versions": {"0.7": "+++\ntitle = \"Promote Companion Release\"\n+++\n\nThis is step 2 of the Companion release flow.\n\nUse this workflow to point one or more public feeds at an already published Companion release. GitHub Actions displays this workflow as `Release: Promote Companion Release`.\n\nThis workflow does not rebuild binaries. It rewrites feed files in the public release repository and commits those pointer changes. See [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) for the public feed layout and serving model.\n\n## Use It When\n\nRun the promotion workflow when:\n\n- A published Companion release should become visible on `test`, `beta`, or `stable`.\n- Sambee should start offering direct downloads for that same published release.\n- You want to move an already published release from one visibility level to another without rebuilding it.\n\nDo not use this workflow for draft releases.\nPromotion should target a published release only.\n\n## Inputs\n\nThe manual workflow accepts these inputs:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `release_ref` | The release to promote. | Use the Companion tag for the clearest intent, for example `companion-v0.6.0`. |\n| `companion_channel_test` | Update the Companion `test` updater feed. | Use when installed test-channel builds should see this release. |\n| `companion_channel_beta` | Update the Companion `beta` updater feed. | Use when prerelease users should see this release. |\n| `companion_channel_stable` | Update the Companion `stable` updater feed. | Use when the release is approved for normal users. |\n| `sambee` | Update the Sambee Companion download-metadata feed. | Use when Sambee should offer this release for direct download. |\n\n`release_ref` can be:\n\n- A Companion tag such as `companion-v0.6.0`.\n- A GitHub release URL.\n- A numeric GitHub release ID.\n\nAt least one target must be selected.\n\n## What It Updates\n\nThe workflow checks out both repositories, resolves the release, and rewrites only the selected feed files in `helgeklein/sambee-companion`.\n\nSelected Companion channel targets update the appropriate updater manifest. The Sambee target updates the direct-download metadata document. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) defines those files and their consumers.\n\nAfter rewriting the files, the workflow commits and pushes the feed updates to the release repository, where they become available to their consumers.\n\n## Validation Rules\n\nPromotion is intentionally strict.\n\nIt fails when:\n\n- No promotion target was selected.\n- The referenced release is still a draft.\n- The release has no assets.\n- A selected Tauri feed target lacks a required bundle-and-signature pair for an included platform.\n- The Sambee metadata target would have no usable downloadable installer assets.\n\nA release does not need every supported platform to be promotable.\nIt only needs complete assets for the platforms that are actually included in the selected feed output.\n\n## Promotion Targets Mean Different Things\n\nCompanion updater feeds and Sambee download metadata are separate surfaces.\n\n- Promote a Companion channel when installed desktop apps should see the release through self-update.\n- Promote Sambee metadata when the product UI should offer the release as a direct download.\n- Select both when you want both outcomes from the same published release.\n\nUse [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) when you need the underlying model.\n\n## Run the Workflow\n\nUse this order when you are promoting a Companion release:\n\n1. Publish the reviewed draft release in `helgeklein/sambee-companion`.\n2. Start `Release: Promote Companion Release`.\n3. Set `release_ref` to the exact published release you want to expose.\n4. Select only the feed targets you intend to change.\n5. Let the workflow update and push the selected feed files.\n6. Validate the affected updater channel or Sambee download surface.\n7. Rerun the same workflow later if that same release should move from `test` to `beta` or `stable`.\n\n", "0.8": "+++\ntitle = \"Promote Companion Release\"\n+++\n\nThis is step 2 of the Companion release flow.\n\nUse this workflow to point one or more public feeds at an already published Companion release. GitHub Actions displays this workflow as `Release: Promote Companion Release`.\n\nThis workflow does not rebuild binaries. It rewrites feed files in the public release repository and commits those pointer changes. See [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) for the public feed layout and serving model.\n\n## Use It When\n\nRun the promotion workflow when:\n\n- A published Companion release should become visible on `test`, `beta`, or `stable`.\n- Sambee should start offering direct downloads for that same published release.\n- You want to move an already published release from one visibility level to another without rebuilding it.\n\nDo not use this workflow for draft releases.\nPromotion should target a published release only.\n\n## Inputs\n\nThe manual workflow accepts these inputs:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `release_ref` | The release to promote. | Use the Companion tag for the clearest intent, for example `companion-v0.6.0`. |\n| `companion_channel_test` | Update the Companion `test` updater feed. | Use when installed test-channel builds should see this release. |\n| `companion_channel_beta` | Update the Companion `beta` updater feed. | Use when prerelease users should see this release. |\n| `companion_channel_stable` | Update the Companion `stable` updater feed. | Use when the release is approved for normal users. |\n| `sambee` | Update the Sambee Companion download-metadata feed. | Use when Sambee should offer this release for direct download. |\n\n`release_ref` can be:\n\n- A Companion tag such as `companion-v0.6.0`.\n- A GitHub release URL.\n- A numeric GitHub release ID.\n\nAt least one target must be selected.\n\n## What It Updates\n\nThe workflow checks out both repositories, resolves the release, and rewrites only the selected feed files in `helgeklein/sambee-companion`.\n\nSelected Companion channel targets update the appropriate updater manifest. The Sambee target updates the direct-download metadata document. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) defines those files and their consumers.\n\nAfter rewriting the files, the workflow commits and pushes the feed updates to the release repository, where they become available to their consumers.\n\n## Validation Rules\n\nPromotion is intentionally strict.\n\nIt fails when:\n\n- No promotion target was selected.\n- The referenced release is still a draft.\n- The release has no assets.\n- A selected Tauri feed target lacks a required bundle-and-signature pair for an included platform.\n- The Sambee metadata target would have no usable downloadable installer assets.\n\nA release does not need every supported platform to be promotable.\nIt only needs complete assets for the platforms that are actually included in the selected feed output.\n\n## Promotion Targets Mean Different Things\n\nCompanion updater feeds and Sambee download metadata are separate surfaces.\n\n- Promote a Companion channel when installed desktop apps should see the release through self-update.\n- Promote Sambee metadata when the product UI should offer the release as a direct download.\n- Select both when you want both outcomes from the same published release.\n\nUse [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) when you need the underlying model.\n\n## Run the Workflow\n\nUse this order when you are promoting a Companion release:\n\n1. Publish the reviewed draft release in `helgeklein/sambee-companion`.\n2. Start `Release: Promote Companion Release`.\n3. Set `release_ref` to the exact published release you want to expose.\n4. Select only the feed targets you intend to change.\n5. Let the workflow update and push the selected feed files.\n6. Validate the affected updater channel or Sambee download surface.\n7. Rerun the same workflow later if that same release should move from `test` to `beta` or `stable`.\n\n", "0.9": "+++\ntitle = \"Promote Companion Release\"\n+++\n\nThis is step 2 of the Companion release flow.\n\nUse this workflow to point one or more public feeds at an already published Companion release. GitHub Actions displays this workflow as `Release: Promote Companion Release`.\n\nThis workflow does not rebuild binaries. It rewrites feed files in the public release repository and commits those pointer changes. See [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) for the public feed layout and serving model.\n\n## Use It When\n\nRun the promotion workflow when:\n\n- A published Companion release should become visible on `test`, `beta`, or `stable`.\n- Sambee should start offering direct downloads for that same published release.\n- You want to move an already published release from one visibility level to another without rebuilding it.\n\nDo not use this workflow for draft releases.\nPromotion should target a published release only.\n\n## Inputs\n\nThe manual workflow accepts these inputs:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `release_ref` | The release to promote. | Use the Companion tag for the clearest intent, for example `companion-v0.6.0`. |\n| `companion_channel_test` | Update the Companion `test` updater feed. | Use when installed test-channel builds should see this release. |\n| `companion_channel_beta` | Update the Companion `beta` updater feed. | Use when prerelease users should see this release. |\n| `companion_channel_stable` | Update the Companion `stable` updater feed. | Use when the release is approved for normal users. |\n| `sambee` | Update the Sambee Companion download-metadata feed. | Use when Sambee should offer this release for direct download. |\n\n`release_ref` can be:\n\n- A Companion tag such as `companion-v0.6.0`.\n- A GitHub release URL.\n- A numeric GitHub release ID.\n\nThe workflow reads the selected release's immutable provenance and derives the required public Sambee authorization tag as `vX.Y.Z`. That public release must contain `sambee-release.json` with a matching version, build tag, source SHA, and Companion-compatible scope.\n\nAt least one target must be selected.\n\n## What It Updates\n\nThe workflow checks out both repositories, resolves the release, and rewrites only the selected feed files in `helgeklein/sambee-companion`.\n\nSelected Companion channel targets update the appropriate updater manifest. The Sambee target updates the direct-download metadata document. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) defines those files and their consumers.\n\nAfter rewriting the files, the workflow commits and pushes the feed updates to the release repository, where they become available to their consumers.\n\n## Validation Rules\n\nPromotion is intentionally strict.\n\nIt fails when:\n\n- No promotion target was selected.\n- The referenced release is still a draft.\n- The release has no assets.\n- The external release provenance or completion marker does not exactly match its assets and checksums.\n- The public `sambee-release.json` does not authorize `companion` or `both`, or its version, build tag, or source SHA differs from the Companion provenance.\n- A selected Tauri feed target lacks a required bundle-and-signature pair for an included platform.\n- The Sambee metadata target would have no usable downloadable installer assets.\n\nA release does not need every supported platform to be promotable.\nIt only needs complete assets for the platforms that are actually included in the selected feed output.\n\n## Promotion Targets Mean Different Things\n\nCompanion updater feeds and Sambee download metadata are separate surfaces.\n\n- Promote a Companion channel when installed desktop apps should see the release through self-update.\n- Promote Sambee metadata when the product UI should offer the release as a direct download.\n- Select both when you want both outcomes from the same published release.\n\nUse [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) when you need the underlying model.\n\n## Run the Workflow\n\nUse this order when you are promoting a Companion release:\n\n1. Publish the reviewed draft release in `helgeklein/sambee-companion`.\n2. Start `Release: Promote Companion Release`.\n3. Set `release_ref` to the exact published release you want to expose.\n4. Select only the feed targets you intend to change.\n5. Let the workflow derive the matching public Sambee release, then update and push the selected feed files.\n6. Validate the affected updater channel or Sambee download surface.\n7. Rerun the same workflow later if that same release should move from `test` to `beta` or `stable`.\n\n", "1.0": "+++\ntitle = \"Promote Companion Release\"\n+++\n\nThis is the manual promotion step of the Companion release flow.\n\nUse this workflow to point one or more public feeds at an already published Companion release. GitHub Actions displays this workflow as `Release: Promote Companion Release`.\n\nThis workflow does not rebuild binaries. It rewrites feed files in the public release repository and commits those pointer changes. See [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) for the public feed layout and serving model.\n\n## Use It When\n\nRun the promotion workflow when:\n\n- A published Companion release should become visible on `beta` or `stable`.\n- Sambee should start offering direct downloads for that same published release.\n- You want to move an already published release from one visibility level to another without rebuilding it.\n\nNew builds already promote their verified published release to `test` automatically. You can still select `test` manually when you need to repair or deliberately move that feed.\n\nDo not use this workflow for draft or GitHub prerelease releases.\nPromotion should target a published, non-prerelease release only.\n\n## Inputs\n\nThe manual workflow accepts these inputs:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `release_ref` | The release to promote. | Use the Companion tag for the clearest intent, for example `companion-v0.6.0`. |\n| `companion_channel_test` | Update the Companion `test` updater feed. | Use when installed test-channel builds should see this release. |\n| `companion_channel_beta` | Update the Companion `beta` updater feed. | Use when installed beta-channel builds should see this release. |\n| `companion_channel_stable` | Update the Companion `stable` updater feed. | Use when the release is approved for normal users. |\n| `sambee` | Update the Sambee Companion download-metadata feed. | Use when Sambee should offer this release for direct download. |\n\n`release_ref` can be:\n\n- A Companion tag such as `companion-v0.6.0`.\n- A GitHub release URL for `helgeklein/sambee-companion`, such as `https://github.com/helgeklein/sambee-companion/releases/tag/companion-v0.6.0`.\n- A numeric GitHub release ID.\n\nBefore updating feeds, the workflow verifies that the selected release's immutable provenance refers to a canonical build tag at the recorded source commit. A matching public Sambee release or Docker image is not required.\n\nAt least one target must be selected.\n\n## What It Updates\n\nThe workflow checks out both repositories, resolves the release, and rewrites only the selected feed files in `helgeklein/sambee-companion`.\n\nSelected Companion channel targets update the appropriate updater manifest. The Sambee target updates the direct-download metadata document. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) defines those files and their consumers.\n\nAfter rewriting the files, the workflow commits and pushes the feed updates to the release repository, where they become available to their consumers. A successful promotion then runs the same release cleanup used by new builds.\n\n## Validation Rules\n\nPromotion is intentionally strict.\n\nIt fails when:\n\n- No promotion target was selected.\n- The referenced release is still a draft.\n- The referenced release is a GitHub prerelease.\n- The release has no assets.\n- The external release provenance or completion marker does not exactly match its assets and checksums.\n- The Companion provenance build tag does not resolve to the recorded source commit.\n- A selected Tauri feed target lacks a required bundle-and-signature pair for an included platform.\n- The Sambee metadata target would have no usable downloadable installer assets.\n\nA release does not need every supported platform to be promotable.\nIt only needs complete assets for the platforms that are actually included in the selected feed output.\n\n## Promotion Targets Mean Different Things\n\nCompanion updater feeds and Sambee download metadata are separate surfaces.\n\n- Promote a Companion channel when installed desktop apps should see the release through self-update.\n- Promote Sambee metadata when the product UI should offer the release as a direct download.\n- Select both when you want both outcomes from the same published release.\n\nUse [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) when you need the underlying model.\n\n## Run the Workflow\n\nUse this order when you are promoting a Companion release:\n\n1. Start `Release: Promote Companion Release`.\n1. Set `release_ref` to the exact published release you want to expose.\n1. Select only the feed targets you intend to change.\n1. Let the workflow verify the Companion provenance, then update and push the selected feed files.\n1. Validate the affected updater channel or Sambee download surface.\n1. Rerun the same workflow later if that same release should move from `test` to `beta` or `stable`.\n\n", "2.0": "+++\ntitle = \"Promote Companion Release\"\n+++\n\nThis is the manual promotion step of the Companion release flow.\n\nUse this workflow to point one or more public feeds at an already published Companion release. GitHub Actions displays this workflow as `Release: Promote Companion Release`.\n\nThis workflow does not rebuild binaries. It rewrites feed files in the public release repository and commits those pointer changes. See [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) for the public feed layout and serving model.\n\n## Use It When\n\nRun the promotion workflow when:\n\n- A published Companion release should become visible on `beta` or `stable`.\n- Sambee should start offering direct downloads for that same published release.\n- You want to move an already published release from one visibility level to another without rebuilding it.\n\nNew builds already promote their verified published release to `test` automatically. You can still select `test` manually when you need to repair or deliberately move that feed.\n\nDo not use this workflow for draft or GitHub prerelease releases.\nPromotion should target a published, non-prerelease release only.\n\n## Inputs\n\nThe manual workflow accepts these inputs:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `release_ref` | The release to promote. | Use the Companion tag for the clearest intent, for example `companion-v0.6.0`. |\n| `companion_channel_test` | Update the Companion `test` updater feed. | Use when installed test-channel builds should see this release. |\n| `companion_channel_beta` | Update the Companion `beta` updater feed. | Use when installed beta-channel builds should see this release. |\n| `companion_channel_stable` | Update the Companion `stable` updater feed. | Use when the release is approved for normal users. |\n| `sambee` | Update the Sambee Companion download-metadata feed. | Use when Sambee should offer this release for direct download. |\n\n`release_ref` can be:\n\n- A Companion tag such as `companion-v0.6.0`.\n- A GitHub release URL for `sambee-app/sambee-companion`, such as `https://github.com/sambee-app/sambee-companion/releases/tag/companion-v0.6.0`.\n- A numeric GitHub release ID.\n\nBefore updating feeds, the workflow verifies that the selected release's immutable provenance refers to a canonical build tag at the recorded source commit. A matching public Sambee release or Docker image is not required.\n\nAt least one target must be selected.\n\n## What It Updates\n\nThe workflow checks out both repositories, resolves the release, and rewrites only the selected feed files in `sambee-app/sambee-companion`.\n\nSelected Companion channel targets update the appropriate updater manifest. The Sambee target updates the direct-download metadata document. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) defines those files and their consumers.\n\nAfter rewriting the files, the workflow commits and pushes the feed updates to the release repository, where they become available to their consumers. A successful promotion then runs the same release cleanup used by new builds.\n\n## Validation Rules\n\nPromotion is intentionally strict.\n\nIt fails when:\n\n- No promotion target was selected.\n- The referenced release is still a draft.\n- The referenced release is a GitHub prerelease.\n- The release has no assets.\n- The external release provenance or completion marker does not exactly match its assets and checksums.\n- The Companion provenance build tag does not resolve to the recorded source commit.\n- A selected Tauri feed target lacks a required bundle-and-signature pair for an included platform.\n- The Sambee metadata target would have no usable downloadable installer assets.\n\nA release does not need every supported platform to be promotable.\nIt only needs complete assets for the platforms that are actually included in the selected feed output.\n\n## Promotion Targets Mean Different Things\n\nCompanion updater feeds and Sambee download metadata are separate surfaces.\n\n- Promote a Companion channel when installed desktop apps should see the release through self-update.\n- Promote Sambee metadata when the product UI should offer the release as a direct download.\n- Select both when you want both outcomes from the same published release.\n\nUse [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) when you need the underlying model.\n\n## Run the Workflow\n\nUse this order when you are promoting a Companion release:\n\n1. Start `Release: Promote Companion Release`.\n1. Set `release_ref` to the exact published release you want to expose.\n1. Select only the feed targets you intend to change.\n1. Let the workflow verify the Companion provenance, then update and push the selected feed files.\n1. Validate the affected updater channel or Sambee download surface.\n1. Rerun the same workflow later if that same release should move from `test` to `beta` or `stable`.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Promote Companion Release\"\n+++\n\nThis is step 2 of the Companion release flow.\n\nUse this workflow to point one or more public feeds at an already published Companion release. GitHub Actions displays this workflow as `Release: Promote Companion Release`.\n\nThis workflow does not rebuild binaries. It rewrites feed files in the public release repository and commits those pointer changes. See [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) for the public feed layout and serving model.\n\n## Use It When\n\nRun the promotion workflow when:\n\n- A published Companion release should become visible on `test`, `beta`, or `stable`.\n- Sambee should start offering direct downloads for that same published release.\n- You want to move an already published release from one visibility level to another without rebuilding it.\n\nDo not use this workflow for draft releases.\nPromotion should target a published release only.\n\n## Inputs\n\nThe manual workflow accepts these inputs:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `release_ref` | The release to promote. | Use the Companion tag for the clearest intent, for example `companion-v0.6.0`. |\n| `companion_channel_test` | Update the Companion `test` updater feed. | Use when installed test-channel builds should see this release. |\n| `companion_channel_beta` | Update the Companion `beta` updater feed. | Use when prerelease users should see this release. |\n| `companion_channel_stable` | Update the Companion `stable` updater feed. | Use when the release is approved for normal users. |\n| `sambee` | Update the Sambee Companion download-metadata feed. | Use when Sambee should offer this release for direct download. |\n\n`release_ref` can be:\n\n- A Companion tag such as `companion-v0.6.0`.\n- A GitHub release URL.\n- A numeric GitHub release ID.\n\nAt least one target must be selected.\n\n## What It Updates\n\nThe workflow checks out both repositories, resolves the release, and rewrites only the selected feed files in `helgeklein/sambee-companion`.\n\nSelected Companion channel targets update the appropriate updater manifest. The Sambee target updates the direct-download metadata document. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) defines those files and their consumers.\n\nAfter rewriting the files, the workflow commits and pushes the feed updates to the release repository, where they become available to their consumers.\n\n## Validation Rules\n\nPromotion is intentionally strict.\n\nIt fails when:\n\n- No promotion target was selected.\n- The referenced release is still a draft.\n- The release has no assets.\n- A selected Tauri feed target lacks a required bundle-and-signature pair for an included platform.\n- The Sambee metadata target would have no usable downloadable installer assets.\n\nA release does not need every supported platform to be promotable.\nIt only needs complete assets for the platforms that are actually included in the selected feed output.\n\n## Promotion Targets Mean Different Things\n\nCompanion updater feeds and Sambee download metadata are separate surfaces.\n\n- Promote a Companion channel when installed desktop apps should see the release through self-update.\n- Promote Sambee metadata when the product UI should offer the release as a direct download.\n- Select both when you want both outcomes from the same published release.\n\nUse [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) when you need the underlying model.\n\n## Run the Workflow\n\nUse this order when you are promoting a Companion release:\n\n1. Publish the reviewed draft release in `helgeklein/sambee-companion`.\n2. Start `Release: Promote Companion Release`.\n3. Set `release_ref` to the exact published release you want to expose.\n4. Select only the feed targets you intend to change.\n5. Let the workflow update and push the selected feed files.\n6. Validate the affected updater channel or Sambee download surface.\n7. Rerun the same workflow later if that same release should move from `test` to `beta` or `stable`.\n\n", "0.8": "+++\ntitle = \"Promote Companion Release\"\n+++\n\nThis is step 2 of the Companion release flow.\n\nUse this workflow to point one or more public feeds at an already published Companion release. GitHub Actions displays this workflow as `Release: Promote Companion Release`.\n\nThis workflow does not rebuild binaries. It rewrites feed files in the public release repository and commits those pointer changes. See [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) for the public feed layout and serving model.\n\n## Use It When\n\nRun the promotion workflow when:\n\n- A published Companion release should become visible on `test`, `beta`, or `stable`.\n- Sambee should start offering direct downloads for that same published release.\n- You want to move an already published release from one visibility level to another without rebuilding it.\n\nDo not use this workflow for draft releases.\nPromotion should target a published release only.\n\n## Inputs\n\nThe manual workflow accepts these inputs:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `release_ref` | The release to promote. | Use the Companion tag for the clearest intent, for example `companion-v0.6.0`. |\n| `companion_channel_test` | Update the Companion `test` updater feed. | Use when installed test-channel builds should see this release. |\n| `companion_channel_beta` | Update the Companion `beta` updater feed. | Use when prerelease users should see this release. |\n| `companion_channel_stable` | Update the Companion `stable` updater feed. | Use when the release is approved for normal users. |\n| `sambee` | Update the Sambee Companion download-metadata feed. | Use when Sambee should offer this release for direct download. |\n\n`release_ref` can be:\n\n- A Companion tag such as `companion-v0.6.0`.\n- A GitHub release URL.\n- A numeric GitHub release ID.\n\nAt least one target must be selected.\n\n## What It Updates\n\nThe workflow checks out both repositories, resolves the release, and rewrites only the selected feed files in `helgeklein/sambee-companion`.\n\nSelected Companion channel targets update the appropriate updater manifest. The Sambee target updates the direct-download metadata document. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) defines those files and their consumers.\n\nAfter rewriting the files, the workflow commits and pushes the feed updates to the release repository, where they become available to their consumers.\n\n## Validation Rules\n\nPromotion is intentionally strict.\n\nIt fails when:\n\n- No promotion target was selected.\n- The referenced release is still a draft.\n- The release has no assets.\n- A selected Tauri feed target lacks a required bundle-and-signature pair for an included platform.\n- The Sambee metadata target would have no usable downloadable installer assets.\n\nA release does not need every supported platform to be promotable.\nIt only needs complete assets for the platforms that are actually included in the selected feed output.\n\n## Promotion Targets Mean Different Things\n\nCompanion updater feeds and Sambee download metadata are separate surfaces.\n\n- Promote a Companion channel when installed desktop apps should see the release through self-update.\n- Promote Sambee metadata when the product UI should offer the release as a direct download.\n- Select both when you want both outcomes from the same published release.\n\nUse [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) when you need the underlying model.\n\n## Run the Workflow\n\nUse this order when you are promoting a Companion release:\n\n1. Publish the reviewed draft release in `helgeklein/sambee-companion`.\n2. Start `Release: Promote Companion Release`.\n3. Set `release_ref` to the exact published release you want to expose.\n4. Select only the feed targets you intend to change.\n5. Let the workflow update and push the selected feed files.\n6. Validate the affected updater channel or Sambee download surface.\n7. Rerun the same workflow later if that same release should move from `test` to `beta` or `stable`.\n\n", "0.9": "+++\ntitle = \"Promote Companion Release\"\n+++\n\nThis is step 2 of the Companion release flow.\n\nUse this workflow to point one or more public feeds at an already published Companion release. GitHub Actions displays this workflow as `Release: Promote Companion Release`.\n\nThis workflow does not rebuild binaries. It rewrites feed files in the public release repository and commits those pointer changes. See [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) for the public feed layout and serving model.\n\n## Use It When\n\nRun the promotion workflow when:\n\n- A published Companion release should become visible on `test`, `beta`, or `stable`.\n- Sambee should start offering direct downloads for that same published release.\n- You want to move an already published release from one visibility level to another without rebuilding it.\n\nDo not use this workflow for draft releases.\nPromotion should target a published release only.\n\n## Inputs\n\nThe manual workflow accepts these inputs:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `release_ref` | The release to promote. | Use the Companion tag for the clearest intent, for example `companion-v0.6.0`. |\n| `companion_channel_test` | Update the Companion `test` updater feed. | Use when installed test-channel builds should see this release. |\n| `companion_channel_beta` | Update the Companion `beta` updater feed. | Use when prerelease users should see this release. |\n| `companion_channel_stable` | Update the Companion `stable` updater feed. | Use when the release is approved for normal users. |\n| `sambee` | Update the Sambee Companion download-metadata feed. | Use when Sambee should offer this release for direct download. |\n\n`release_ref` can be:\n\n- A Companion tag such as `companion-v0.6.0`.\n- A GitHub release URL.\n- A numeric GitHub release ID.\n\nThe workflow reads the selected release's immutable provenance and derives the required public Sambee authorization tag as `vX.Y.Z`. That public release must contain `sambee-release.json` with a matching version, build tag, source SHA, and Companion-compatible scope.\n\nAt least one target must be selected.\n\n## What It Updates\n\nThe workflow checks out both repositories, resolves the release, and rewrites only the selected feed files in `helgeklein/sambee-companion`.\n\nSelected Companion channel targets update the appropriate updater manifest. The Sambee target updates the direct-download metadata document. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) defines those files and their consumers.\n\nAfter rewriting the files, the workflow commits and pushes the feed updates to the release repository, where they become available to their consumers.\n\n## Validation Rules\n\nPromotion is intentionally strict.\n\nIt fails when:\n\n- No promotion target was selected.\n- The referenced release is still a draft.\n- The release has no assets.\n- The external release provenance or completion marker does not exactly match its assets and checksums.\n- The public `sambee-release.json` does not authorize `companion` or `both`, or its version, build tag, or source SHA differs from the Companion provenance.\n- A selected Tauri feed target lacks a required bundle-and-signature pair for an included platform.\n- The Sambee metadata target would have no usable downloadable installer assets.\n\nA release does not need every supported platform to be promotable.\nIt only needs complete assets for the platforms that are actually included in the selected feed output.\n\n## Promotion Targets Mean Different Things\n\nCompanion updater feeds and Sambee download metadata are separate surfaces.\n\n- Promote a Companion channel when installed desktop apps should see the release through self-update.\n- Promote Sambee metadata when the product UI should offer the release as a direct download.\n- Select both when you want both outcomes from the same published release.\n\nUse [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) when you need the underlying model.\n\n## Run the Workflow\n\nUse this order when you are promoting a Companion release:\n\n1. Publish the reviewed draft release in `helgeklein/sambee-companion`.\n2. Start `Release: Promote Companion Release`.\n3. Set `release_ref` to the exact published release you want to expose.\n4. Select only the feed targets you intend to change.\n5. Let the workflow derive the matching public Sambee release, then update and push the selected feed files.\n6. Validate the affected updater channel or Sambee download surface.\n7. Rerun the same workflow later if that same release should move from `test` to `beta` or `stable`.\n\n", "1.0": "+++\ntitle = \"Promote Companion Release\"\n+++\n\nThis is the manual promotion step of the Companion release flow.\n\nUse this workflow to point one or more public feeds at an already published Companion release. GitHub Actions displays this workflow as `Release: Promote Companion Release`.\n\nThis workflow does not rebuild binaries. It rewrites feed files in the public release repository and commits those pointer changes. See [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) for the public feed layout and serving model.\n\n## Use It When\n\nRun the promotion workflow when:\n\n- A published Companion release should become visible on `beta` or `stable`.\n- Sambee should start offering direct downloads for that same published release.\n- You want to move an already published release from one visibility level to another without rebuilding it.\n\nNew builds already promote their verified published release to `test` automatically. You can still select `test` manually when you need to repair or deliberately move that feed.\n\nDo not use this workflow for draft or GitHub prerelease releases.\nPromotion should target a published, non-prerelease release only.\n\n## Inputs\n\nThe manual workflow accepts these inputs:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `release_ref` | The release to promote. | Use the Companion tag for the clearest intent, for example `companion-v0.6.0`. |\n| `companion_channel_test` | Update the Companion `test` updater feed. | Use when installed test-channel builds should see this release. |\n| `companion_channel_beta` | Update the Companion `beta` updater feed. | Use when installed beta-channel builds should see this release. |\n| `companion_channel_stable` | Update the Companion `stable` updater feed. | Use when the release is approved for normal users. |\n| `sambee` | Update the Sambee Companion download-metadata feed. | Use when Sambee should offer this release for direct download. |\n\n`release_ref` can be:\n\n- A Companion tag such as `companion-v0.6.0`.\n- A GitHub release URL for `helgeklein/sambee-companion`, such as `https://github.com/helgeklein/sambee-companion/releases/tag/companion-v0.6.0`.\n- A numeric GitHub release ID.\n\nBefore updating feeds, the workflow verifies that the selected release's immutable provenance refers to a canonical build tag at the recorded source commit. A matching public Sambee release or Docker image is not required.\n\nAt least one target must be selected.\n\n## What It Updates\n\nThe workflow checks out both repositories, resolves the release, and rewrites only the selected feed files in `helgeklein/sambee-companion`.\n\nSelected Companion channel targets update the appropriate updater manifest. The Sambee target updates the direct-download metadata document. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) defines those files and their consumers.\n\nAfter rewriting the files, the workflow commits and pushes the feed updates to the release repository, where they become available to their consumers. A successful promotion then runs the same release cleanup used by new builds.\n\n## Validation Rules\n\nPromotion is intentionally strict.\n\nIt fails when:\n\n- No promotion target was selected.\n- The referenced release is still a draft.\n- The referenced release is a GitHub prerelease.\n- The release has no assets.\n- The external release provenance or completion marker does not exactly match its assets and checksums.\n- The Companion provenance build tag does not resolve to the recorded source commit.\n- A selected Tauri feed target lacks a required bundle-and-signature pair for an included platform.\n- The Sambee metadata target would have no usable downloadable installer assets.\n\nA release does not need every supported platform to be promotable.\nIt only needs complete assets for the platforms that are actually included in the selected feed output.\n\n## Promotion Targets Mean Different Things\n\nCompanion updater feeds and Sambee download metadata are separate surfaces.\n\n- Promote a Companion channel when installed desktop apps should see the release through self-update.\n- Promote Sambee metadata when the product UI should offer the release as a direct download.\n- Select both when you want both outcomes from the same published release.\n\nUse [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) when you need the underlying model.\n\n## Run the Workflow\n\nUse this order when you are promoting a Companion release:\n\n1. Start `Release: Promote Companion Release`.\n1. Set `release_ref` to the exact published release you want to expose.\n1. Select only the feed targets you intend to change.\n1. Let the workflow verify the Companion provenance, then update and push the selected feed files.\n1. Validate the affected updater channel or Sambee download surface.\n1. Rerun the same workflow later if that same release should move from `test` to `beta` or `stable`.\n\n", "2.0": "+++\ntitle = \"Promote Companion Release\"\n+++\n\nThis is the manual promotion step of the Companion release flow.\n\nUse this workflow to point one or more public feeds at an already published Companion release. GitHub Actions displays this workflow as `Release: Promote Companion Release`.\n\nThis workflow does not rebuild binaries. It rewrites feed files in the public release repository and commits those pointer changes. See [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) for the public feed layout and serving model.\n\n## Use It When\n\nRun the promotion workflow when:\n\n- A published Companion release should become visible on `beta` or `stable`.\n- Sambee should start offering direct downloads for that same published release.\n- You want to move an already published release from one visibility level to another without rebuilding it.\n\nNew builds already promote their verified published release to `test` automatically. You can still select `test` manually when you need to repair or deliberately move that feed.\n\nDo not use this workflow for draft or GitHub prerelease releases.\nPromotion should target a published, non-prerelease release only.\n\n## Inputs\n\nThe manual workflow accepts these inputs:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `release_ref` | The release to promote. | Use the Companion tag for the clearest intent, for example `companion-v0.6.0`. |\n| `companion_channel_test` | Update the Companion `test` updater feed. | Use when installed test-channel builds should see this release. |\n| `companion_channel_beta` | Update the Companion `beta` updater feed. | Use when installed beta-channel builds should see this release. |\n| `companion_channel_stable` | Update the Companion `stable` updater feed. | Use when the release is approved for normal users. |\n| `sambee` | Update the Sambee Companion download-metadata feed. | Use when Sambee should offer this release for direct download. |\n\n`release_ref` can be:\n\n- A Companion tag such as `companion-v0.6.0`.\n- A GitHub release URL for `sambee-app/sambee-companion`, such as `https://github.com/sambee-app/sambee-companion/releases/tag/companion-v0.6.0`.\n- A numeric GitHub release ID.\n\nBefore updating feeds, the workflow verifies that the selected release's immutable provenance refers to a canonical build tag at the recorded source commit. A matching public Sambee release or Docker image is not required.\n\nAt least one target must be selected.\n\n## What It Updates\n\nThe workflow checks out both repositories, resolves the release, and rewrites only the selected feed files in `sambee-app/sambee-companion`.\n\nSelected Companion channel targets update the appropriate updater manifest. The Sambee target updates the direct-download metadata document. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) defines those files and their consumers.\n\nAfter rewriting the files, the workflow commits and pushes the feed updates to the release repository, where they become available to their consumers. A successful promotion then runs the same release cleanup used by new builds.\n\n## Validation Rules\n\nPromotion is intentionally strict.\n\nIt fails when:\n\n- No promotion target was selected.\n- The referenced release is still a draft.\n- The referenced release is a GitHub prerelease.\n- The release has no assets.\n- The external release provenance or completion marker does not exactly match its assets and checksums.\n- The Companion provenance build tag does not resolve to the recorded source commit.\n- A selected Tauri feed target lacks a required bundle-and-signature pair for an included platform.\n- The Sambee metadata target would have no usable downloadable installer assets.\n\nA release does not need every supported platform to be promotable.\nIt only needs complete assets for the platforms that are actually included in the selected feed output.\n\n## Promotion Targets Mean Different Things\n\nCompanion updater feeds and Sambee download metadata are separate surfaces.\n\n- Promote a Companion channel when installed desktop apps should see the release through self-update.\n- Promote Sambee metadata when the product UI should offer the release as a direct download.\n- Select both when you want both outcomes from the same published release.\n\nUse [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) when you need the underlying model.\n\n## Run the Workflow\n\nUse this order when you are promoting a Companion release:\n\n1. Start `Release: Promote Companion Release`.\n1. Set `release_ref` to the exact published release you want to expose.\n1. Select only the feed targets you intend to change.\n1. Let the workflow verify the Companion provenance, then update and push the selected feed files.\n1. Validate the affected updater channel or Sambee download surface.\n1. Rerun the same workflow later if that same release should move from `test` to `beta` or `stable`.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/release-and-versioning/companion-channels-feeds-and-downloads", "parent_id": "section:developer-guide/release-and-versioning", "depth": 2, "kind": "page", "label": "companion-channels-feeds-and-downloads", "title": "Companion Channels Feeds And Downloads", "path": "developer-guide/release-and-versioning/companion-channels-feeds-and-downloads", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "branched", "source_version": "0.7", "diff_added": 3, "diff_removed": 1}, "1.0": {"state": "branched", "source_version": "0.9", "diff_added": 6, "diff_removed": 11}, "2.0": {"state": "branched", "source_version": "1.0", "diff_added": 1, "diff_removed": 1}}, "content_versions": {"0.7": "+++\ntitle = \"Companion Channels, Feeds, And Downloads\"\n+++\n\nUse this page when you need the system model behind Companion release promotion.\n\nIt explains which public files exist, who reads them, and why channel promotion does not require rebuilding binaries.\n\n## Core Model\n\nCompanion release distribution is intentionally split between build control in the main repository, release assets in a dedicated release repository, and public feed serving from a separate feed host.\n\nThat split keeps Companion binaries out of normal Sambee deployments while still letting:\n\n- Sambee render Companion download links.\n- Installed Companion builds fetch updates.\n\nThe current model uses four moving parts:\n\n1. The main `sambee` repository builds Companion releases.\n2. The dedicated `sambee-companion` repository hosts immutable GitHub Release assets and stores the committed feed files under `docs/feeds`.\n3. The separate host `https://release-feeds.sambee.net` serves those committed feed files publicly.\n4. Channel manifests under `stable`, `beta`, and `test` decide which published release installed Companion builds see.\n5. A separate Sambee download-metadata file decides which installer links Sambee renders in the product UI.\n\nThe important consequence is simple: channels are feed pointers, not separate binaries.\n\n## Public Distribution Surface\n\nPublished Companion releases live in `helgeklein/sambee-companion` as GitHub Releases.\n\nThe public feed host is:\n\n- `https://release-feeds.sambee.net`\n\nThat host is separate from the main `sambee.net` website deployment in this repository.\nThe website workflow here deploys `website/public` to Cloudflare Pages for `sambee.net`, while the live feed host currently responds separately.\n\nThe current public layout is:\n\n```text\nfeeds/companion/tauri/stable/latest.json\nfeeds/companion/tauri/beta/latest.json\nfeeds/companion/tauri/test/latest.json\nfeeds/sambee/companion/latest.json\n```\n\nInside the release repository, those files are committed under `docs/feeds/`.\nThat repository path is the source of the published feed JSON, not the same thing as the main website source tree in this repository.\n\n## Who Reads What\n\n| Consumer | Public file | Format | Purpose |\n|---|---|---|---|\n| Installed Companion builds | `feeds/companion/tauri/\u003cchannel\u003e/latest.json` | Tauri updater JSON | Exposes the published release visible to the selected update channel. |\n| Sambee backend | `feeds/sambee/companion/latest.json` | Sambee-specific download metadata | Exposes version, notes, and installer URLs for the product UI. |\n\nSambee and Companion do not read the same feed.\n\n- Promoting a Companion channel changes auto-update visibility for installed desktop apps.\n- Promoting the Sambee metadata feed changes which direct downloads the product surfaces.\n- The same published release can move across `test`, `beta`, and `stable` over time.\n\n## Feed Rules\n\nInstalled Companion builds consume standard Tauri updater JSON.\n\nImportant behavior:\n\n- Each channel manifest points to immutable release assets in `sambee-companion`.\n- Feed files can move between releases over time, but published asset URLs should not be patched in place.\n- The promotion script includes every platform for which it finds a complete bundle-and-signature pair.\n- A release does not need every platform to be promotable.\n\nSambee uses a different JSON document.\n\nImportant behavior:\n\n- It contains only what Sambee needs to render download UI.\n- The asset map can contain any supported subset of discovered installers.\n- Sambee does not read the Tauri channel manifests directly.\n\n## Runtime Behavior\n\nCompanion uses `tauri-plugin-updater` for self-update checks.\n\nThe runtime updater is channel-aware:\n\n- The Rust update commands build the updater URL from the selected channel at runtime.\n- The frontend stores the local preference as `companionUpdateChannel`.\n- Allowed channel values are `stable`, `beta`, and `test`.\n- The default channel is `stable`.\n\nIn practice, that means the same installed app can see different releases over time based on the local channel setting and the currently promoted feed file.\n\n## Sambee Integration\n\nSambee does not bundle Companion binaries.\n\nBy default, the backend resolves Companion download metadata from `https://release-feeds.sambee.net/feeds/sambee/companion/latest.json`.\n\nThe backend then:\n\n- Fetches the hosted Companion download metadata.\n- Normalizes and validates installer URLs.\n- Exposes the result through the backend API to the frontend.\n\nSambee also supports a deterministic pin override in configuration.\n\nWhen a pin is configured, the backend stops using the hosted feed for Companion download links and serves the pinned version, notes, and installer URLs instead.\n\n## App Identity And Signing\n\nCompanion uses one app identity across all update channels.\n\nChannel separation comes from feed selection, not from separate binaries or per-channel app identifiers.\n\nCompanion also uses one Tauri updater signing key across all channels.\n\n- Updater artifacts are signed during release builds.\n- Installed Companion builds verify updates using the embedded updater public key.\n- Platform-specific installer signing is separate from the Tauri updater signature.\n\n## Contributor Rules\n\n- Do not treat update channels as different binaries.\n- Do not patch broken published assets in place.\n- Build and publish a new release instead.\n- Review whether you are changing Companion updater visibility, Sambee download visibility, or both.\n- Keep release automation aligned with asset naming conventions, because promotion depends on asset-pattern matching.\n\n", "0.8": "+++\ntitle = \"Companion Channels, Feeds, And Downloads\"\n+++\n\nUse this page when you need the system model behind Companion release promotion.\n\nIt explains which public files exist, who reads them, and why channel promotion does not require rebuilding binaries.\n\n## Core Model\n\nCompanion release distribution is intentionally split between build control in the main repository, release assets in a dedicated release repository, and public feed serving from a separate feed host.\n\nThat split keeps Companion binaries out of normal Sambee deployments while still letting:\n\n- Sambee render Companion download links.\n- Installed Companion builds fetch updates.\n\nThe current model uses four moving parts:\n\n1. The main `sambee` repository builds Companion releases.\n2. The dedicated `sambee-companion` repository hosts immutable GitHub Release assets and stores the committed feed files under `docs/feeds`.\n3. The separate host `https://release-feeds.sambee.net` serves those committed feed files publicly.\n4. Channel manifests under `stable`, `beta`, and `test` decide which published release installed Companion builds see.\n5. A separate Sambee download-metadata file decides which installer links Sambee renders in the product UI.\n\nThe important consequence is simple: channels are feed pointers, not separate binaries.\n\n## Public Distribution Surface\n\nPublished Companion releases live in `helgeklein/sambee-companion` as GitHub Releases.\n\nThe public feed host is:\n\n- `https://release-feeds.sambee.net`\n\nThat host is separate from the main `sambee.net` website deployment in this repository.\nThe website workflow here deploys `website/public` to Cloudflare Pages for `sambee.net`, while the live feed host currently responds separately.\n\nThe current public layout is:\n\n```text\nfeeds/companion/tauri/stable/latest.json\nfeeds/companion/tauri/beta/latest.json\nfeeds/companion/tauri/test/latest.json\nfeeds/sambee/companion/latest.json\n```\n\nInside the release repository, those files are committed under `docs/feeds/`.\nThat repository path is the source of the published feed JSON, not the same thing as the main website source tree in this repository.\n\n## Who Reads What\n\n| Consumer | Public file | Format | Purpose |\n|---|---|---|---|\n| Installed Companion builds | `feeds/companion/tauri/\u003cchannel\u003e/latest.json` | Tauri updater JSON | Exposes the published release visible to the selected update channel. |\n| Sambee backend | `feeds/sambee/companion/latest.json` | Sambee-specific download metadata | Exposes version, notes, and installer URLs for the product UI. |\n\nSambee and Companion do not read the same feed.\n\n- Promoting a Companion channel changes auto-update visibility for installed desktop apps.\n- Promoting the Sambee metadata feed changes which direct downloads the product surfaces.\n- The same published release can move across `test`, `beta`, and `stable` over time.\n\n## Feed Rules\n\nInstalled Companion builds consume standard Tauri updater JSON.\n\nImportant behavior:\n\n- Each channel manifest points to immutable release assets in `sambee-companion`.\n- Feed files can move between releases over time, but published asset URLs should not be patched in place.\n- The promotion script includes every platform for which it finds a complete bundle-and-signature pair.\n- A release does not need every platform to be promotable.\n\nSambee uses a different JSON document.\n\nImportant behavior:\n\n- It contains only what Sambee needs to render download UI.\n- The asset map can contain any supported subset of discovered installers.\n- Sambee does not read the Tauri channel manifests directly.\n\n## Runtime Behavior\n\nCompanion uses `tauri-plugin-updater` for self-update checks.\n\nThe runtime updater is channel-aware:\n\n- The Rust update commands build the updater URL from the selected channel at runtime.\n- The frontend stores the local preference as `companionUpdateChannel`.\n- Allowed channel values are `stable`, `beta`, and `test`.\n- The default channel is `stable`.\n\nIn practice, that means the same installed app can see different releases over time based on the local channel setting and the currently promoted feed file.\n\n## Sambee Integration\n\nSambee does not bundle Companion binaries.\n\nBy default, the backend resolves Companion download metadata from `https://release-feeds.sambee.net/feeds/sambee/companion/latest.json`.\n\nThe backend then:\n\n- Fetches the hosted Companion download metadata.\n- Normalizes and validates installer URLs.\n- Exposes the result through the backend API to the frontend.\n\nSambee also supports a deterministic pin override in configuration.\n\nWhen a pin is configured, the backend stops using the hosted feed for Companion download links and serves the pinned version, notes, and installer URLs instead.\n\n## App Identity And Signing\n\nCompanion uses one app identity across all update channels.\n\nChannel separation comes from feed selection, not from separate binaries or per-channel app identifiers.\n\nCompanion also uses one Tauri updater signing key across all channels.\n\n- Updater artifacts are signed during release builds.\n- Installed Companion builds verify updates using the embedded updater public key.\n- Platform-specific installer signing is separate from the Tauri updater signature.\n\n## Contributor Rules\n\n- Do not treat update channels as different binaries.\n- Do not patch broken published assets in place.\n- Build and publish a new release instead.\n- Review whether you are changing Companion updater visibility, Sambee download visibility, or both.\n- Keep release automation aligned with asset naming conventions, because promotion depends on asset-pattern matching.\n\n", "0.9": "+++\ntitle = \"Companion Channels, Feeds, And Downloads\"\n+++\n\nUse this page when you need the system model behind Companion release promotion.\n\nIt explains which public files exist, who reads them, and why channel promotion does not require rebuilding binaries.\n\n## Core Model\n\nCompanion release distribution is intentionally split between build control in the main repository, release assets in a dedicated release repository, and public feed serving from a separate feed host.\n\nThat split keeps Companion binaries out of normal Sambee deployments while still letting:\n\n- Sambee render Companion download links.\n- Installed Companion builds fetch updates.\n\nThe current model uses four moving parts:\n\n1. The main `sambee` repository builds Companion releases.\n2. The dedicated `sambee-companion` repository hosts immutable GitHub Release assets and stores the committed feed files under `docs/feeds`.\n3. The separate host `https://release-feeds.sambee.net` serves those committed feed files publicly.\n4. Channel manifests under `stable`, `beta`, and `test` decide which published release installed Companion builds see.\n5. A separate Sambee download-metadata file decides which installer links Sambee renders in the product UI.\n\nThe important consequence is simple: channels are feed pointers, not separate binaries.\n\n## Public Distribution Surface\n\nPublished Companion releases live in `helgeklein/sambee-companion` as GitHub Releases.\n\nThe public feed host is:\n\n- `https://release-feeds.sambee.net`\n\nThat host is separate from the main `sambee.net` website deployment in this repository.\nThe website workflow here deploys `website/public` to Cloudflare Pages for `sambee.net`, while the live feed host currently responds separately.\n\nThe current public layout is:\n\n```text\nfeeds/companion/tauri/stable/latest.json\nfeeds/companion/tauri/beta/latest.json\nfeeds/companion/tauri/test/latest.json\nfeeds/sambee/companion/latest.json\n```\n\nInside the release repository, those files are committed under `docs/feeds/`.\nThat repository path is the source of the published feed JSON, not the same thing as the main website source tree in this repository.\n\n## Who Reads What\n\n| Consumer | Public file | Format | Purpose |\n|---|---|---|---|\n| Installed Companion builds | `feeds/companion/tauri/\u003cchannel\u003e/latest.json` | Tauri updater JSON | Exposes the published release visible to the selected update channel. |\n| Sambee backend | `feeds/sambee/companion/latest.json` | Sambee-specific download metadata | Exposes version, notes, and installer URLs for the product UI. |\n\nSambee and Companion do not read the same feed.\n\n- Promoting a Companion channel changes auto-update visibility for installed desktop apps.\n- Promoting the Sambee metadata feed changes which direct downloads the product surfaces.\n- The same published release can move across `test`, `beta`, and `stable` over time.\n\n## Feed Rules\n\nInstalled Companion builds consume standard Tauri updater JSON.\n\nImportant behavior:\n\n- Each channel manifest points to immutable release assets in `sambee-companion`.\n- Feed files can move between releases over time, but published asset URLs should not be patched in place.\n- Each publishable release uses a new plain numeric `X.Y.Z` version. Tauri offers an update only when the later version is greater; publishing replacement bytes under an equal version is unsupported.\n- The promotion script includes every platform for which it finds a complete bundle-and-signature pair.\n- A release does not need every platform to be promotable.\n\nSambee uses a different JSON document.\n\nImportant behavior:\n\n- It contains only what Sambee needs to render download UI.\n- The asset map can contain any supported subset of discovered installers.\n- Sambee does not read the Tauri channel manifests directly.\n\n## Runtime Behavior\n\nCompanion uses `tauri-plugin-updater` for self-update checks.\n\nThe runtime updater is channel-aware:\n\n- The Rust update commands build the updater URL from the selected channel at runtime.\n- The frontend stores the local preference as `companionUpdateChannel`.\n- Allowed channel values are `stable`, `beta`, and `test`.\n- The default channel is `stable`.\n\nIn practice, that means the same installed app can see different releases over time based on the local channel setting and the currently promoted feed file.\n\n## Sambee Integration\n\nSambee does not bundle Companion binaries.\n\nBy default, the backend resolves Companion download metadata from `https://release-feeds.sambee.net/feeds/sambee/companion/latest.json`.\n\nThe backend then:\n\n- Fetches the hosted Companion download metadata.\n- Normalizes and validates installer URLs.\n- Exposes the result through the backend API to the frontend.\n\nSambee also supports a deterministic pin override in configuration.\n\nWhen a pin is configured, the backend stops using the hosted feed for Companion download links and serves the pinned version, notes, and installer URLs instead.\n\n## App Identity And Signing\n\nCompanion uses one app identity across all update channels.\n\nChannel separation comes from feed selection, not from separate binaries or per-channel app identifiers.\n\nCompanion also uses one Tauri updater signing key across all channels.\n\n- Updater artifacts are signed during release builds.\n- Installed Companion builds verify updates using the embedded updater public key.\n- Platform-specific installer signing is separate from the Tauri updater signature.\n\n## Contributor Rules\n\n- Do not treat update channels as different binaries.\n- Do not patch broken published assets in place.\n- Build and publish a new `Z` version instead.\n- Treat `test`, `beta`, and `stable` as visibility pointers, never as different binaries or version suffixes.\n- Review whether you are changing Companion updater visibility, Sambee download visibility, or both.\n- Keep release automation aligned with asset naming conventions, because promotion depends on asset-pattern matching.\n\n", "1.0": "+++\ntitle = \"Companion Channels, Feeds \u0026 Downloads\"\n+++\n\nUse this page when you need the system model behind Companion release promotion.\n\nIt explains which public files exist, who reads them, and why channel promotion does not require rebuilding binaries.\n\n{{\u003c companion-promotion-overview \u003e}}\n\n## Core Model\n\nCompanion release distribution is intentionally split between build control in the main repository, release assets in a dedicated release repository, and public feed serving from a separate feed host.\n\nThat split keeps Companion binaries out of normal Sambee deployments while still letting:\n\n- Sambee render Companion download links.\n- Installed Companion builds fetch updates.\n\nThe current model uses four moving parts:\n\n1. The main `sambee` repository builds Companion releases.\n2. The dedicated `sambee-companion` repository hosts immutable GitHub Release assets and stores the committed feed files under `docs/feeds`.\n3. The separate host `https://release-feeds.sambee.net` serves those committed feed files publicly.\n4. Channel manifests under `stable`, `beta`, and `test` decide which published release installed Companion builds see.\n5. A separate Sambee download-metadata file decides which installer links Sambee renders in the product UI.\n\nThe important consequence is simple: channels are feed pointers, not separate binaries.\n\nEvery successful Companion build moves only the `test` updater feed. It does not change `beta`, `stable`, or the Sambee download-metadata feed.\n\n## Public Distribution Surface\n\nPublished Companion releases live in `helgeklein/sambee-companion` as GitHub Releases.\n\nThe public feed host is:\n\n- `https://release-feeds.sambee.net`\n\nThat host is separate from the main `sambee.net` website deployment in this repository.\nThe website workflow here deploys `website/public` to Cloudflare Pages for `sambee.net`, while the live feed host currently responds separately.\n\nThe current public layout is:\n\n```text\nfeeds/companion/tauri/stable/latest.json\nfeeds/companion/tauri/beta/latest.json\nfeeds/companion/tauri/test/latest.json\nfeeds/sambee/companion/latest.json\n```\n\nInside the release repository, those files are committed under `docs/feeds/`.\nThat repository path is the source of the published feed JSON, not the same thing as the main website source tree in this repository.\n\n## Who Reads What\n\n| Consumer | Public file | Format | Purpose |\n|---|---|---|---|\n| Installed Companion builds | `feeds/companion/tauri/\u003cchannel\u003e/latest.json` | Tauri updater JSON | Exposes the published release visible to the selected update channel. |\n| Sambee backend | `feeds/sambee/companion/latest.json` | Sambee-specific download metadata | Exposes version, notes, and installer URLs for the product UI. |\n\nSambee and Companion do not read the same feed.\n\n- Promoting a Companion channel changes auto-update visibility for installed desktop apps.\n- Promoting the Sambee metadata feed changes which direct downloads the product surfaces.\n- The same published release can move across `test`, `beta`, and `stable` over time.\n- The build workflow promotes `test` automatically; later promotion targets remain manual.\n\n## Feed Rules\n\nInstalled Companion builds consume standard Tauri updater JSON.\n\nImportant behavior:\n\n- Each channel manifest points to immutable release assets in `sambee-companion`.\n- Feed files can move between releases over time, but published asset URLs should not be patched in place.\n- Each publishable release uses a new plain numeric `X.Y.Z` version. Tauri offers an update only when the later version is greater; publishing replacement bytes under an equal version is unsupported.\n- The promotion script includes every platform for which it finds a complete bundle-and-signature pair.\n- A release does not need every platform to be promotable.\n\nSambee uses a different JSON document.\n\nImportant behavior:\n\n- It contains only what Sambee needs to render download UI.\n- The asset map can contain any supported subset of discovered installers.\n- Sambee does not read the Tauri channel manifests directly.\n\n## Runtime Behavior\n\nCompanion uses `tauri-plugin-updater` for self-update checks.\n\nThe runtime updater is channel-aware:\n\n- The Rust update commands build the updater URL from the selected channel at runtime.\n- The frontend stores the local preference as `companionUpdateChannel`.\n- Allowed channel values are `stable`, `beta`, and `test`.\n- The default channel is `stable`.\n\nIn practice, that means the same installed app can see different releases over time based on the local channel setting and the currently promoted feed file.\n\n## Sambee Integration\n\nSambee does not bundle Companion binaries.\n\nBy default, the backend resolves Companion download metadata from `https://release-feeds.sambee.net/feeds/sambee/companion/latest.json`.\n\nThe backend then:\n\n- Fetches the hosted Companion download metadata.\n- Normalizes and validates installer URLs.\n- Exposes the result through the backend API to the frontend.\n\nSambee also supports a deterministic pin override in configuration.\n\nWhen a pin is configured, the backend stops using the hosted feed for Companion download links and serves the pinned version, notes, and installer URLs instead.\n\n## App Identity And Signing\n\nCompanion uses one app identity across all update channels.\n\nChannel separation comes from feed selection, not from separate binaries or per-channel app identifiers.\n\nCompanion also uses one Tauri updater signing key across all channels.\n\n- Updater artifacts are signed during release builds.\n- Installed Companion builds verify updates using the embedded updater public key.\n- Platform-specific installer signing is separate from the Tauri updater signature.\n", "2.0": "+++\ntitle = \"Companion Channels, Feeds \u0026 Downloads\"\n+++\n\nUse this page when you need the system model behind Companion release promotion.\n\nIt explains which public files exist, who reads them, and why channel promotion does not require rebuilding binaries.\n\n{{\u003c companion-promotion-overview \u003e}}\n\n## Core Model\n\nCompanion release distribution is intentionally split between build control in the main repository, release assets in a dedicated release repository, and public feed serving from a separate feed host.\n\nThat split keeps Companion binaries out of normal Sambee deployments while still letting:\n\n- Sambee render Companion download links.\n- Installed Companion builds fetch updates.\n\nThe current model uses four moving parts:\n\n1. The main `sambee` repository builds Companion releases.\n2. The dedicated `sambee-companion` repository hosts immutable GitHub Release assets and stores the committed feed files under `docs/feeds`.\n3. The separate host `https://release-feeds.sambee.net` serves those committed feed files publicly.\n4. Channel manifests under `stable`, `beta`, and `test` decide which published release installed Companion builds see.\n5. A separate Sambee download-metadata file decides which installer links Sambee renders in the product UI.\n\nThe important consequence is simple: channels are feed pointers, not separate binaries.\n\nEvery successful Companion build moves only the `test` updater feed. It does not change `beta`, `stable`, or the Sambee download-metadata feed.\n\n## Public Distribution Surface\n\nPublished Companion releases live in `sambee-app/sambee-companion` as GitHub Releases.\n\nThe public feed host is:\n\n- `https://release-feeds.sambee.net`\n\nThat host is separate from the main `sambee.net` website deployment in this repository.\nThe website workflow here deploys `website/public` to Cloudflare Pages for `sambee.net`, while the live feed host currently responds separately.\n\nThe current public layout is:\n\n```text\nfeeds/companion/tauri/stable/latest.json\nfeeds/companion/tauri/beta/latest.json\nfeeds/companion/tauri/test/latest.json\nfeeds/sambee/companion/latest.json\n```\n\nInside the release repository, those files are committed under `docs/feeds/`.\nThat repository path is the source of the published feed JSON, not the same thing as the main website source tree in this repository.\n\n## Who Reads What\n\n| Consumer | Public file | Format | Purpose |\n|---|---|---|---|\n| Installed Companion builds | `feeds/companion/tauri/\u003cchannel\u003e/latest.json` | Tauri updater JSON | Exposes the published release visible to the selected update channel. |\n| Sambee backend | `feeds/sambee/companion/latest.json` | Sambee-specific download metadata | Exposes version, notes, and installer URLs for the product UI. |\n\nSambee and Companion do not read the same feed.\n\n- Promoting a Companion channel changes auto-update visibility for installed desktop apps.\n- Promoting the Sambee metadata feed changes which direct downloads the product surfaces.\n- The same published release can move across `test`, `beta`, and `stable` over time.\n- The build workflow promotes `test` automatically; later promotion targets remain manual.\n\n## Feed Rules\n\nInstalled Companion builds consume standard Tauri updater JSON.\n\nImportant behavior:\n\n- Each channel manifest points to immutable release assets in `sambee-companion`.\n- Feed files can move between releases over time, but published asset URLs should not be patched in place.\n- Each publishable release uses a new plain numeric `X.Y.Z` version. Tauri offers an update only when the later version is greater; publishing replacement bytes under an equal version is unsupported.\n- The promotion script includes every platform for which it finds a complete bundle-and-signature pair.\n- A release does not need every platform to be promotable.\n\nSambee uses a different JSON document.\n\nImportant behavior:\n\n- It contains only what Sambee needs to render download UI.\n- The asset map can contain any supported subset of discovered installers.\n- Sambee does not read the Tauri channel manifests directly.\n\n## Runtime Behavior\n\nCompanion uses `tauri-plugin-updater` for self-update checks.\n\nThe runtime updater is channel-aware:\n\n- The Rust update commands build the updater URL from the selected channel at runtime.\n- The frontend stores the local preference as `companionUpdateChannel`.\n- Allowed channel values are `stable`, `beta`, and `test`.\n- The default channel is `stable`.\n\nIn practice, that means the same installed app can see different releases over time based on the local channel setting and the currently promoted feed file.\n\n## Sambee Integration\n\nSambee does not bundle Companion binaries.\n\nBy default, the backend resolves Companion download metadata from `https://release-feeds.sambee.net/feeds/sambee/companion/latest.json`.\n\nThe backend then:\n\n- Fetches the hosted Companion download metadata.\n- Normalizes and validates installer URLs.\n- Exposes the result through the backend API to the frontend.\n\nSambee also supports a deterministic pin override in configuration.\n\nWhen a pin is configured, the backend stops using the hosted feed for Companion download links and serves the pinned version, notes, and installer URLs instead.\n\n## App Identity And Signing\n\nCompanion uses one app identity across all update channels.\n\nChannel separation comes from feed selection, not from separate binaries or per-channel app identifiers.\n\nCompanion also uses one Tauri updater signing key across all channels.\n\n- Updater artifacts are signed during release builds.\n- Installed Companion builds verify updates using the embedded updater public key.\n- Platform-specific installer signing is separate from the Tauri updater signature.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Companion Channels, Feeds, And Downloads\"\n+++\n\nUse this page when you need the system model behind Companion release promotion.\n\nIt explains which public files exist, who reads them, and why channel promotion does not require rebuilding binaries.\n\n## Core Model\n\nCompanion release distribution is intentionally split between build control in the main repository, release assets in a dedicated release repository, and public feed serving from a separate feed host.\n\nThat split keeps Companion binaries out of normal Sambee deployments while still letting:\n\n- Sambee render Companion download links.\n- Installed Companion builds fetch updates.\n\nThe current model uses four moving parts:\n\n1. The main `sambee` repository builds Companion releases.\n2. The dedicated `sambee-companion` repository hosts immutable GitHub Release assets and stores the committed feed files under `docs/feeds`.\n3. The separate host `https://release-feeds.sambee.net` serves those committed feed files publicly.\n4. Channel manifests under `stable`, `beta`, and `test` decide which published release installed Companion builds see.\n5. A separate Sambee download-metadata file decides which installer links Sambee renders in the product UI.\n\nThe important consequence is simple: channels are feed pointers, not separate binaries.\n\n## Public Distribution Surface\n\nPublished Companion releases live in `helgeklein/sambee-companion` as GitHub Releases.\n\nThe public feed host is:\n\n- `https://release-feeds.sambee.net`\n\nThat host is separate from the main `sambee.net` website deployment in this repository.\nThe website workflow here deploys `website/public` to Cloudflare Pages for `sambee.net`, while the live feed host currently responds separately.\n\nThe current public layout is:\n\n```text\nfeeds/companion/tauri/stable/latest.json\nfeeds/companion/tauri/beta/latest.json\nfeeds/companion/tauri/test/latest.json\nfeeds/sambee/companion/latest.json\n```\n\nInside the release repository, those files are committed under `docs/feeds/`.\nThat repository path is the source of the published feed JSON, not the same thing as the main website source tree in this repository.\n\n## Who Reads What\n\n| Consumer | Public file | Format | Purpose |\n|---|---|---|---|\n| Installed Companion builds | `feeds/companion/tauri/\u003cchannel\u003e/latest.json` | Tauri updater JSON | Exposes the published release visible to the selected update channel. |\n| Sambee backend | `feeds/sambee/companion/latest.json` | Sambee-specific download metadata | Exposes version, notes, and installer URLs for the product UI. |\n\nSambee and Companion do not read the same feed.\n\n- Promoting a Companion channel changes auto-update visibility for installed desktop apps.\n- Promoting the Sambee metadata feed changes which direct downloads the product surfaces.\n- The same published release can move across `test`, `beta`, and `stable` over time.\n\n## Feed Rules\n\nInstalled Companion builds consume standard Tauri updater JSON.\n\nImportant behavior:\n\n- Each channel manifest points to immutable release assets in `sambee-companion`.\n- Feed files can move between releases over time, but published asset URLs should not be patched in place.\n- The promotion script includes every platform for which it finds a complete bundle-and-signature pair.\n- A release does not need every platform to be promotable.\n\nSambee uses a different JSON document.\n\nImportant behavior:\n\n- It contains only what Sambee needs to render download UI.\n- The asset map can contain any supported subset of discovered installers.\n- Sambee does not read the Tauri channel manifests directly.\n\n## Runtime Behavior\n\nCompanion uses `tauri-plugin-updater` for self-update checks.\n\nThe runtime updater is channel-aware:\n\n- The Rust update commands build the updater URL from the selected channel at runtime.\n- The frontend stores the local preference as `companionUpdateChannel`.\n- Allowed channel values are `stable`, `beta`, and `test`.\n- The default channel is `stable`.\n\nIn practice, that means the same installed app can see different releases over time based on the local channel setting and the currently promoted feed file.\n\n## Sambee Integration\n\nSambee does not bundle Companion binaries.\n\nBy default, the backend resolves Companion download metadata from `https://release-feeds.sambee.net/feeds/sambee/companion/latest.json`.\n\nThe backend then:\n\n- Fetches the hosted Companion download metadata.\n- Normalizes and validates installer URLs.\n- Exposes the result through the backend API to the frontend.\n\nSambee also supports a deterministic pin override in configuration.\n\nWhen a pin is configured, the backend stops using the hosted feed for Companion download links and serves the pinned version, notes, and installer URLs instead.\n\n## App Identity And Signing\n\nCompanion uses one app identity across all update channels.\n\nChannel separation comes from feed selection, not from separate binaries or per-channel app identifiers.\n\nCompanion also uses one Tauri updater signing key across all channels.\n\n- Updater artifacts are signed during release builds.\n- Installed Companion builds verify updates using the embedded updater public key.\n- Platform-specific installer signing is separate from the Tauri updater signature.\n\n## Contributor Rules\n\n- Do not treat update channels as different binaries.\n- Do not patch broken published assets in place.\n- Build and publish a new release instead.\n- Review whether you are changing Companion updater visibility, Sambee download visibility, or both.\n- Keep release automation aligned with asset naming conventions, because promotion depends on asset-pattern matching.\n\n", "0.8": "+++\ntitle = \"Companion Channels, Feeds, And Downloads\"\n+++\n\nUse this page when you need the system model behind Companion release promotion.\n\nIt explains which public files exist, who reads them, and why channel promotion does not require rebuilding binaries.\n\n## Core Model\n\nCompanion release distribution is intentionally split between build control in the main repository, release assets in a dedicated release repository, and public feed serving from a separate feed host.\n\nThat split keeps Companion binaries out of normal Sambee deployments while still letting:\n\n- Sambee render Companion download links.\n- Installed Companion builds fetch updates.\n\nThe current model uses four moving parts:\n\n1. The main `sambee` repository builds Companion releases.\n2. The dedicated `sambee-companion` repository hosts immutable GitHub Release assets and stores the committed feed files under `docs/feeds`.\n3. The separate host `https://release-feeds.sambee.net` serves those committed feed files publicly.\n4. Channel manifests under `stable`, `beta`, and `test` decide which published release installed Companion builds see.\n5. A separate Sambee download-metadata file decides which installer links Sambee renders in the product UI.\n\nThe important consequence is simple: channels are feed pointers, not separate binaries.\n\n## Public Distribution Surface\n\nPublished Companion releases live in `helgeklein/sambee-companion` as GitHub Releases.\n\nThe public feed host is:\n\n- `https://release-feeds.sambee.net`\n\nThat host is separate from the main `sambee.net` website deployment in this repository.\nThe website workflow here deploys `website/public` to Cloudflare Pages for `sambee.net`, while the live feed host currently responds separately.\n\nThe current public layout is:\n\n```text\nfeeds/companion/tauri/stable/latest.json\nfeeds/companion/tauri/beta/latest.json\nfeeds/companion/tauri/test/latest.json\nfeeds/sambee/companion/latest.json\n```\n\nInside the release repository, those files are committed under `docs/feeds/`.\nThat repository path is the source of the published feed JSON, not the same thing as the main website source tree in this repository.\n\n## Who Reads What\n\n| Consumer | Public file | Format | Purpose |\n|---|---|---|---|\n| Installed Companion builds | `feeds/companion/tauri/\u003cchannel\u003e/latest.json` | Tauri updater JSON | Exposes the published release visible to the selected update channel. |\n| Sambee backend | `feeds/sambee/companion/latest.json` | Sambee-specific download metadata | Exposes version, notes, and installer URLs for the product UI. |\n\nSambee and Companion do not read the same feed.\n\n- Promoting a Companion channel changes auto-update visibility for installed desktop apps.\n- Promoting the Sambee metadata feed changes which direct downloads the product surfaces.\n- The same published release can move across `test`, `beta`, and `stable` over time.\n\n## Feed Rules\n\nInstalled Companion builds consume standard Tauri updater JSON.\n\nImportant behavior:\n\n- Each channel manifest points to immutable release assets in `sambee-companion`.\n- Feed files can move between releases over time, but published asset URLs should not be patched in place.\n- The promotion script includes every platform for which it finds a complete bundle-and-signature pair.\n- A release does not need every platform to be promotable.\n\nSambee uses a different JSON document.\n\nImportant behavior:\n\n- It contains only what Sambee needs to render download UI.\n- The asset map can contain any supported subset of discovered installers.\n- Sambee does not read the Tauri channel manifests directly.\n\n## Runtime Behavior\n\nCompanion uses `tauri-plugin-updater` for self-update checks.\n\nThe runtime updater is channel-aware:\n\n- The Rust update commands build the updater URL from the selected channel at runtime.\n- The frontend stores the local preference as `companionUpdateChannel`.\n- Allowed channel values are `stable`, `beta`, and `test`.\n- The default channel is `stable`.\n\nIn practice, that means the same installed app can see different releases over time based on the local channel setting and the currently promoted feed file.\n\n## Sambee Integration\n\nSambee does not bundle Companion binaries.\n\nBy default, the backend resolves Companion download metadata from `https://release-feeds.sambee.net/feeds/sambee/companion/latest.json`.\n\nThe backend then:\n\n- Fetches the hosted Companion download metadata.\n- Normalizes and validates installer URLs.\n- Exposes the result through the backend API to the frontend.\n\nSambee also supports a deterministic pin override in configuration.\n\nWhen a pin is configured, the backend stops using the hosted feed for Companion download links and serves the pinned version, notes, and installer URLs instead.\n\n## App Identity And Signing\n\nCompanion uses one app identity across all update channels.\n\nChannel separation comes from feed selection, not from separate binaries or per-channel app identifiers.\n\nCompanion also uses one Tauri updater signing key across all channels.\n\n- Updater artifacts are signed during release builds.\n- Installed Companion builds verify updates using the embedded updater public key.\n- Platform-specific installer signing is separate from the Tauri updater signature.\n\n## Contributor Rules\n\n- Do not treat update channels as different binaries.\n- Do not patch broken published assets in place.\n- Build and publish a new release instead.\n- Review whether you are changing Companion updater visibility, Sambee download visibility, or both.\n- Keep release automation aligned with asset naming conventions, because promotion depends on asset-pattern matching.\n\n", "0.9": "+++\ntitle = \"Companion Channels, Feeds, And Downloads\"\n+++\n\nUse this page when you need the system model behind Companion release promotion.\n\nIt explains which public files exist, who reads them, and why channel promotion does not require rebuilding binaries.\n\n## Core Model\n\nCompanion release distribution is intentionally split between build control in the main repository, release assets in a dedicated release repository, and public feed serving from a separate feed host.\n\nThat split keeps Companion binaries out of normal Sambee deployments while still letting:\n\n- Sambee render Companion download links.\n- Installed Companion builds fetch updates.\n\nThe current model uses four moving parts:\n\n1. The main `sambee` repository builds Companion releases.\n2. The dedicated `sambee-companion` repository hosts immutable GitHub Release assets and stores the committed feed files under `docs/feeds`.\n3. The separate host `https://release-feeds.sambee.net` serves those committed feed files publicly.\n4. Channel manifests under `stable`, `beta`, and `test` decide which published release installed Companion builds see.\n5. A separate Sambee download-metadata file decides which installer links Sambee renders in the product UI.\n\nThe important consequence is simple: channels are feed pointers, not separate binaries.\n\n## Public Distribution Surface\n\nPublished Companion releases live in `helgeklein/sambee-companion` as GitHub Releases.\n\nThe public feed host is:\n\n- `https://release-feeds.sambee.net`\n\nThat host is separate from the main `sambee.net` website deployment in this repository.\nThe website workflow here deploys `website/public` to Cloudflare Pages for `sambee.net`, while the live feed host currently responds separately.\n\nThe current public layout is:\n\n```text\nfeeds/companion/tauri/stable/latest.json\nfeeds/companion/tauri/beta/latest.json\nfeeds/companion/tauri/test/latest.json\nfeeds/sambee/companion/latest.json\n```\n\nInside the release repository, those files are committed under `docs/feeds/`.\nThat repository path is the source of the published feed JSON, not the same thing as the main website source tree in this repository.\n\n## Who Reads What\n\n| Consumer | Public file | Format | Purpose |\n|---|---|---|---|\n| Installed Companion builds | `feeds/companion/tauri/\u003cchannel\u003e/latest.json` | Tauri updater JSON | Exposes the published release visible to the selected update channel. |\n| Sambee backend | `feeds/sambee/companion/latest.json` | Sambee-specific download metadata | Exposes version, notes, and installer URLs for the product UI. |\n\nSambee and Companion do not read the same feed.\n\n- Promoting a Companion channel changes auto-update visibility for installed desktop apps.\n- Promoting the Sambee metadata feed changes which direct downloads the product surfaces.\n- The same published release can move across `test`, `beta`, and `stable` over time.\n\n## Feed Rules\n\nInstalled Companion builds consume standard Tauri updater JSON.\n\nImportant behavior:\n\n- Each channel manifest points to immutable release assets in `sambee-companion`.\n- Feed files can move between releases over time, but published asset URLs should not be patched in place.\n- Each publishable release uses a new plain numeric `X.Y.Z` version. Tauri offers an update only when the later version is greater; publishing replacement bytes under an equal version is unsupported.\n- The promotion script includes every platform for which it finds a complete bundle-and-signature pair.\n- A release does not need every platform to be promotable.\n\nSambee uses a different JSON document.\n\nImportant behavior:\n\n- It contains only what Sambee needs to render download UI.\n- The asset map can contain any supported subset of discovered installers.\n- Sambee does not read the Tauri channel manifests directly.\n\n## Runtime Behavior\n\nCompanion uses `tauri-plugin-updater` for self-update checks.\n\nThe runtime updater is channel-aware:\n\n- The Rust update commands build the updater URL from the selected channel at runtime.\n- The frontend stores the local preference as `companionUpdateChannel`.\n- Allowed channel values are `stable`, `beta`, and `test`.\n- The default channel is `stable`.\n\nIn practice, that means the same installed app can see different releases over time based on the local channel setting and the currently promoted feed file.\n\n## Sambee Integration\n\nSambee does not bundle Companion binaries.\n\nBy default, the backend resolves Companion download metadata from `https://release-feeds.sambee.net/feeds/sambee/companion/latest.json`.\n\nThe backend then:\n\n- Fetches the hosted Companion download metadata.\n- Normalizes and validates installer URLs.\n- Exposes the result through the backend API to the frontend.\n\nSambee also supports a deterministic pin override in configuration.\n\nWhen a pin is configured, the backend stops using the hosted feed for Companion download links and serves the pinned version, notes, and installer URLs instead.\n\n## App Identity And Signing\n\nCompanion uses one app identity across all update channels.\n\nChannel separation comes from feed selection, not from separate binaries or per-channel app identifiers.\n\nCompanion also uses one Tauri updater signing key across all channels.\n\n- Updater artifacts are signed during release builds.\n- Installed Companion builds verify updates using the embedded updater public key.\n- Platform-specific installer signing is separate from the Tauri updater signature.\n\n## Contributor Rules\n\n- Do not treat update channels as different binaries.\n- Do not patch broken published assets in place.\n- Build and publish a new `Z` version instead.\n- Treat `test`, `beta`, and `stable` as visibility pointers, never as different binaries or version suffixes.\n- Review whether you are changing Companion updater visibility, Sambee download visibility, or both.\n- Keep release automation aligned with asset naming conventions, because promotion depends on asset-pattern matching.\n\n", "1.0": "+++\ntitle = \"Companion Channels, Feeds \u0026 Downloads\"\n+++\n\nUse this page when you need the system model behind Companion release promotion.\n\nIt explains which public files exist, who reads them, and why channel promotion does not require rebuilding binaries.\n\n{{\u003c companion-promotion-overview \u003e}}\n\n## Core Model\n\nCompanion release distribution is intentionally split between build control in the main repository, release assets in a dedicated release repository, and public feed serving from a separate feed host.\n\nThat split keeps Companion binaries out of normal Sambee deployments while still letting:\n\n- Sambee render Companion download links.\n- Installed Companion builds fetch updates.\n\nThe current model uses four moving parts:\n\n1. The main `sambee` repository builds Companion releases.\n2. The dedicated `sambee-companion` repository hosts immutable GitHub Release assets and stores the committed feed files under `docs/feeds`.\n3. The separate host `https://release-feeds.sambee.net` serves those committed feed files publicly.\n4. Channel manifests under `stable`, `beta`, and `test` decide which published release installed Companion builds see.\n5. A separate Sambee download-metadata file decides which installer links Sambee renders in the product UI.\n\nThe important consequence is simple: channels are feed pointers, not separate binaries.\n\nEvery successful Companion build moves only the `test` updater feed. It does not change `beta`, `stable`, or the Sambee download-metadata feed.\n\n## Public Distribution Surface\n\nPublished Companion releases live in `helgeklein/sambee-companion` as GitHub Releases.\n\nThe public feed host is:\n\n- `https://release-feeds.sambee.net`\n\nThat host is separate from the main `sambee.net` website deployment in this repository.\nThe website workflow here deploys `website/public` to Cloudflare Pages for `sambee.net`, while the live feed host currently responds separately.\n\nThe current public layout is:\n\n```text\nfeeds/companion/tauri/stable/latest.json\nfeeds/companion/tauri/beta/latest.json\nfeeds/companion/tauri/test/latest.json\nfeeds/sambee/companion/latest.json\n```\n\nInside the release repository, those files are committed under `docs/feeds/`.\nThat repository path is the source of the published feed JSON, not the same thing as the main website source tree in this repository.\n\n## Who Reads What\n\n| Consumer | Public file | Format | Purpose |\n|---|---|---|---|\n| Installed Companion builds | `feeds/companion/tauri/\u003cchannel\u003e/latest.json` | Tauri updater JSON | Exposes the published release visible to the selected update channel. |\n| Sambee backend | `feeds/sambee/companion/latest.json` | Sambee-specific download metadata | Exposes version, notes, and installer URLs for the product UI. |\n\nSambee and Companion do not read the same feed.\n\n- Promoting a Companion channel changes auto-update visibility for installed desktop apps.\n- Promoting the Sambee metadata feed changes which direct downloads the product surfaces.\n- The same published release can move across `test`, `beta`, and `stable` over time.\n- The build workflow promotes `test` automatically; later promotion targets remain manual.\n\n## Feed Rules\n\nInstalled Companion builds consume standard Tauri updater JSON.\n\nImportant behavior:\n\n- Each channel manifest points to immutable release assets in `sambee-companion`.\n- Feed files can move between releases over time, but published asset URLs should not be patched in place.\n- Each publishable release uses a new plain numeric `X.Y.Z` version. Tauri offers an update only when the later version is greater; publishing replacement bytes under an equal version is unsupported.\n- The promotion script includes every platform for which it finds a complete bundle-and-signature pair.\n- A release does not need every platform to be promotable.\n\nSambee uses a different JSON document.\n\nImportant behavior:\n\n- It contains only what Sambee needs to render download UI.\n- The asset map can contain any supported subset of discovered installers.\n- Sambee does not read the Tauri channel manifests directly.\n\n## Runtime Behavior\n\nCompanion uses `tauri-plugin-updater` for self-update checks.\n\nThe runtime updater is channel-aware:\n\n- The Rust update commands build the updater URL from the selected channel at runtime.\n- The frontend stores the local preference as `companionUpdateChannel`.\n- Allowed channel values are `stable`, `beta`, and `test`.\n- The default channel is `stable`.\n\nIn practice, that means the same installed app can see different releases over time based on the local channel setting and the currently promoted feed file.\n\n## Sambee Integration\n\nSambee does not bundle Companion binaries.\n\nBy default, the backend resolves Companion download metadata from `https://release-feeds.sambee.net/feeds/sambee/companion/latest.json`.\n\nThe backend then:\n\n- Fetches the hosted Companion download metadata.\n- Normalizes and validates installer URLs.\n- Exposes the result through the backend API to the frontend.\n\nSambee also supports a deterministic pin override in configuration.\n\nWhen a pin is configured, the backend stops using the hosted feed for Companion download links and serves the pinned version, notes, and installer URLs instead.\n\n## App Identity And Signing\n\nCompanion uses one app identity across all update channels.\n\nChannel separation comes from feed selection, not from separate binaries or per-channel app identifiers.\n\nCompanion also uses one Tauri updater signing key across all channels.\n\n- Updater artifacts are signed during release builds.\n- Installed Companion builds verify updates using the embedded updater public key.\n- Platform-specific installer signing is separate from the Tauri updater signature.\n", "2.0": "+++\ntitle = \"Companion Channels, Feeds \u0026 Downloads\"\n+++\n\nUse this page when you need the system model behind Companion release promotion.\n\nIt explains which public files exist, who reads them, and why channel promotion does not require rebuilding binaries.\n\n{{\u003c companion-promotion-overview \u003e}}\n\n## Core Model\n\nCompanion release distribution is intentionally split between build control in the main repository, release assets in a dedicated release repository, and public feed serving from a separate feed host.\n\nThat split keeps Companion binaries out of normal Sambee deployments while still letting:\n\n- Sambee render Companion download links.\n- Installed Companion builds fetch updates.\n\nThe current model uses four moving parts:\n\n1. The main `sambee` repository builds Companion releases.\n2. The dedicated `sambee-companion` repository hosts immutable GitHub Release assets and stores the committed feed files under `docs/feeds`.\n3. The separate host `https://release-feeds.sambee.net` serves those committed feed files publicly.\n4. Channel manifests under `stable`, `beta`, and `test` decide which published release installed Companion builds see.\n5. A separate Sambee download-metadata file decides which installer links Sambee renders in the product UI.\n\nThe important consequence is simple: channels are feed pointers, not separate binaries.\n\nEvery successful Companion build moves only the `test` updater feed. It does not change `beta`, `stable`, or the Sambee download-metadata feed.\n\n## Public Distribution Surface\n\nPublished Companion releases live in `sambee-app/sambee-companion` as GitHub Releases.\n\nThe public feed host is:\n\n- `https://release-feeds.sambee.net`\n\nThat host is separate from the main `sambee.net` website deployment in this repository.\nThe website workflow here deploys `website/public` to Cloudflare Pages for `sambee.net`, while the live feed host currently responds separately.\n\nThe current public layout is:\n\n```text\nfeeds/companion/tauri/stable/latest.json\nfeeds/companion/tauri/beta/latest.json\nfeeds/companion/tauri/test/latest.json\nfeeds/sambee/companion/latest.json\n```\n\nInside the release repository, those files are committed under `docs/feeds/`.\nThat repository path is the source of the published feed JSON, not the same thing as the main website source tree in this repository.\n\n## Who Reads What\n\n| Consumer | Public file | Format | Purpose |\n|---|---|---|---|\n| Installed Companion builds | `feeds/companion/tauri/\u003cchannel\u003e/latest.json` | Tauri updater JSON | Exposes the published release visible to the selected update channel. |\n| Sambee backend | `feeds/sambee/companion/latest.json` | Sambee-specific download metadata | Exposes version, notes, and installer URLs for the product UI. |\n\nSambee and Companion do not read the same feed.\n\n- Promoting a Companion channel changes auto-update visibility for installed desktop apps.\n- Promoting the Sambee metadata feed changes which direct downloads the product surfaces.\n- The same published release can move across `test`, `beta`, and `stable` over time.\n- The build workflow promotes `test` automatically; later promotion targets remain manual.\n\n## Feed Rules\n\nInstalled Companion builds consume standard Tauri updater JSON.\n\nImportant behavior:\n\n- Each channel manifest points to immutable release assets in `sambee-companion`.\n- Feed files can move between releases over time, but published asset URLs should not be patched in place.\n- Each publishable release uses a new plain numeric `X.Y.Z` version. Tauri offers an update only when the later version is greater; publishing replacement bytes under an equal version is unsupported.\n- The promotion script includes every platform for which it finds a complete bundle-and-signature pair.\n- A release does not need every platform to be promotable.\n\nSambee uses a different JSON document.\n\nImportant behavior:\n\n- It contains only what Sambee needs to render download UI.\n- The asset map can contain any supported subset of discovered installers.\n- Sambee does not read the Tauri channel manifests directly.\n\n## Runtime Behavior\n\nCompanion uses `tauri-plugin-updater` for self-update checks.\n\nThe runtime updater is channel-aware:\n\n- The Rust update commands build the updater URL from the selected channel at runtime.\n- The frontend stores the local preference as `companionUpdateChannel`.\n- Allowed channel values are `stable`, `beta`, and `test`.\n- The default channel is `stable`.\n\nIn practice, that means the same installed app can see different releases over time based on the local channel setting and the currently promoted feed file.\n\n## Sambee Integration\n\nSambee does not bundle Companion binaries.\n\nBy default, the backend resolves Companion download metadata from `https://release-feeds.sambee.net/feeds/sambee/companion/latest.json`.\n\nThe backend then:\n\n- Fetches the hosted Companion download metadata.\n- Normalizes and validates installer URLs.\n- Exposes the result through the backend API to the frontend.\n\nSambee also supports a deterministic pin override in configuration.\n\nWhen a pin is configured, the backend stops using the hosted feed for Companion download links and serves the pinned version, notes, and installer URLs instead.\n\n## App Identity And Signing\n\nCompanion uses one app identity across all update channels.\n\nChannel separation comes from feed selection, not from separate binaries or per-channel app identifiers.\n\nCompanion also uses one Tauri updater signing key across all channels.\n\n- Updater artifacts are signed during release builds.\n- Installed Companion builds verify updates using the embedded updater public key.\n- Platform-specific installer signing is separate from the Tauri updater signature.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/release-and-versioning/release-overview", "parent_id": "section:developer-guide/release-and-versioning", "depth": 2, "kind": "page", "label": "release-overview", "title": "Release Overview", "path": "developer-guide/release-and-versioning/release-overview", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "authored"}, "0.9": {"state": "branched", "source_version": "0.8", "diff_added": 58, "diff_removed": 21}, "1.0": {"state": "branched", "source_version": "0.9", "diff_added": 20, "diff_removed": 13}, "2.0": {"state": "branched", "source_version": "1.0", "diff_added": 2, "diff_removed": 2}}, "content_versions": {"0.8": "+++\ntitle = \"Release Overview\"\n+++\n\n## Preparation\n\n1. Update the product **version** ([details](../product-versioning/)). Ensure it's at the version you want to release.\n\n## Build and Test the Docker Image\n\nSee [Overview](../docker-release-overview/).\n\n1. Run the CI workflow [Release: Create Docker Image](../build-docker-image/) to **build** the Docker image and move the `test` tag to it.\n   - Don't override the product version in the CI workflow.\n1. **Test** the newly built image (pull it via the `test` tag).\n\n## Documentation\n\n1. Review the **homepage** content and update it where necessary.\n1. **Docs:**\n   - Verify [Supported File Formats](../../../user-guide/reference/supported-file-formats/) and update as necessary.\n   - Finalize the target release's [What's New](/release-info/news-and-changes/whats-new/) page.\n   - Mark the target version as current in `website/data/docs-versions.toml`.\n   - Run the VS Code task **Website: Refresh Docs Derived Artifacts**.\n   - Review the Docs Structure Report this creates in `/workspace/website-meta/docs-reports/docs-structure-report.html`.\n1. Git merge all changes.\n\n## Publish the Docker Image\n\nSee [Overview](../docker-release-overview/).\n\n1. Create a Git tag on the commit the tested image was built from.\n1. Publish a GitHub release from that tag.\n   - Release publication triggers [Release: Publish Docker Image](../promote-docker-image/), which tags the image built earlier as `beta` (prereleases) or `stable` and adds version tags for stable releases.\n\n## Publish the Companion\n\nSee [Overview](../companion-release-overview/)\n\n1. Run [Release: Build Companion Artifact](../build-companion-release/) to build Companion for the target platforms.\n   - Publish the Companion GitHub Release created by the workflow.\n1. Run [Release: Promote Companion Release](../promote-companion-release/) to promote the release to the `test`, `beta`, and/or `stable` update channels and to update the Sambee download-metadata feed.\n", "0.9": "+++\ntitle = \"Release Overview\"\n+++\n\n## Principles\n\n- The version number source of truth is the `VERSION` file in the repository.\n- Every built artifact gets a unique version number.\n- Each version is built only once.\n- Releases happen without rebuilds but by applying tags to existing builds (Docker image) or updating channel pointers (Companion app).\n\n## Process Overview for Test and Preview Candidates\n\n1. Update `VERSION` to the next plain numeric `X.Y.Z` build sequence ([details](../product-versioning/)).\n   - Run `./scripts/sync-version`.\n   - Commit the synchronized metadata on `main`.\n1. Build the affected component (see below for details).\n   - Build workflows reserve the current `VERSION` by adding a Git tag when building from the latest commit.\n   - Alternatively, select an existing `build-vX.Y.Z` Git tag to build from.\n1. Test the resulting build.\n   - Docker: Through the `test` tag.\n   - Companion: Through the Companion draft release assets. Promote them to the Companion `test` feed as needed.\n1. Repeat the loop with a new `Z` value when a new candidate is required. Never rebuild or replace a published artifact under the same version.\n\nNotes:\n\n- Docker and Companion candidates may be built independently.\n\n## Component Build \u0026 Release Process\n\n### Update Documentation\n\n1. Review the homepage content and update it where necessary.\n1. Docs:\n   - Verify [Supported File Formats](../../../user-guide/reference/supported-file-formats/) and update as necessary.\n   - Finalize the target release's [What's New](/release-info/news-and-changes/whats-new/) page.\n   - Mark the target version as current in `website/data/docs-versions.toml`.\n   - Run the VS Code task `Website: Refresh Docs Derived Artifacts`.\n   - Review the Docs Structure Report this creates in `/workspace/website-meta/docs-reports/docs-structure-report.html`.\n1. Git merge all changes.\n\n### Build Docker Image\n\nSee this [Overview](../docker-release-overview/). In short:\n\n1. Run [Release: Create Docker Image](../build-docker-image/)\n   - The workflow:\n      - Builds the [Docker image](https://github.com/helgeklein/sambee/pkgs/container/sambee/versions).\n      - Moves the `test` tag to it.\n      - Adds the `X.Y.Z` version tag.\n1. To also move the `beta` tag to the newly built image, run [Release: Publish Docker Image](../promote-docker-image/) manually.\n\n### Build Companion\n\nSee this [Overview](../companion-release-overview/). In short:\n\n1. Run [Release: Build Companion Artifact](../build-companion-release/).\n   - The workflow creates a draft release in the [Companion GitHub repo](https://github.com/helgeklein/sambee-companion/releases).\n   - Publish it.\n\n### Publish a Build\n\nTo publish a candidate build after testing and validation, complete the following steps.\n\n1. Run `Release: Create Public Sambee Release`. Specify:\n   - the validated canonical build version.\n   - the intended scope: `docker`, `companion`, or `both`.\n1. The workflow creates or verifies a draft release in the Sambee GitHub repo.\n1. Review and edit the draft release's changelog, then publish it manually.\n\nIf you selected `docker` or `both`:\n\n- Publishing the reviewed draft triggers [Release: Publish Docker Image](../promote-docker-image/) through the GitHub Release event.\n   - The workflow tags the image built earlier as `beta` (if not ahead) and `stable`, and adds `X.Y` a version tag.\n\nIf you selected `companion` or `both`:\n\n1. Run [Release: Promote Companion Release](../promote-companion-release/).\n   - The workflow promotes the release to the `test`, `beta`, and/or `stable` update channels and updates the Sambee download-metadata feed.\n", "1.0": "+++\ntitle = \"Release Overview\"\n+++\n\n## Principles\n\n- The version number source of truth is the `VERSION` file in the repository.\n- Every built artifact gets a unique version number.\n- Each version is built only once.\n- Releases happen without rebuilds but by applying tags to existing builds (Docker image) or updating channel pointers (Companion app).\n\n## Process Overview for Test and Preview Candidates\n\n1. Update `VERSION` to the next plain numeric `X.Y.Z` build sequence ([details](../product-versioning/)).\n   - Run `./scripts/sync-version`.\n   - Commit the synchronized metadata on `main`.\n1. Build the affected component (see below for details).\n   - Build workflows reserve the current `VERSION` by adding a Git tag when building from the latest commit.\n   - Alternatively, select an existing `build-vX.Y.Z` Git tag to build from.\n1. Test the resulting build.\n   - Docker: Through the `test` tag.\n   - Companion: Through the Companion draft release assets. Promote them to the Companion `test` feed as needed.\n1. Repeat the loop with a new `Z` value when a new candidate is required. Never rebuild or replace a published artifact under the same version.\n\nNotes:\n\n- Docker and Companion candidates may be built independently.\n\n## Release Process \u0026 Checklist\n\n### Update Website\n\n1. Review the homepage content and update it where necessary.\n\n### Update Documentation\n\n1. Verify [Supported File Formats](../../../user-guide/reference/supported-file-formats/) and update as necessary.\n1. Finalize the target release's [What's New](/release-info/news-and-changes/whats-new/) page.\n1. Mark the target version as current in `website/data/docs-versions.toml`:\n   - Update the top-level `current` key, e.g.: `current = \"1.0\"`\n   - Update the `[[versions]]` sections of the previous and the new current version\n1. Run the VS Code task `Website: Refresh Docs Derived Artifacts`.\n1. Review the Docs Structure Report this creates in `/workspace/website-meta/docs-reports/docs-structure-report.html`.\n\nGit merge all changes.\n\n### Build Docker Image\n\nSee this [Overview](../docker-release-overview/). In short:\n\n1. Run [Release: Create Docker Image](../build-docker-image/)\n   - The workflow:\n      - Builds the [Docker image](https://github.com/helgeklein/sambee/pkgs/container/sambee/versions).\n      - Moves the `test` tag to it.\n      - Adds the `X.Y.Z` version tag.\n1. To also move the `beta` tag to the newly built image, run [Release: Publish Docker Image](../promote-docker-image/) manually.\n\n### Build Companion\n\nSee this [Overview](../companion-release-overview/). In short:\n\n1. Run [Release: Build Companion Artifact](../build-companion-release/).\n   - The workflow:\n      - Creates and publishes a [Companion release](https://github.com/helgeklein/sambee-companion/releases)\n      - Moves the `test` tag to it.\n      - Adds the `X.Y.Z` version tag.\n\n### Publish a Build\n\nTo publish a candidate build after testing and validation, complete the following steps.\n\n1. Run `Release: Create Public Sambee Release`. Specify:\n   - the validated canonical build version.\n   - the intended scope: `docker`, `companion`, or `both`.\n1. The workflow creates or verifies a draft release in the Sambee GitHub repo.\n1. Review and edit the draft release's changelog, then publish it manually.\n\nIf you selected `docker` or `both`:\n\n- Publishing the reviewed draft triggers [Release: Publish Docker Image](../promote-docker-image/) through the GitHub Release event.\n   - The workflow tags the image built earlier as `beta` (if not ahead) and `stable`, and adds a `X.Y` version tag.\n\nIf you selected `companion` or `both`:\n\n1. Run [Release: Promote Companion Release](../promote-companion-release/).\n   - The workflow promotes the release to the `beta`, and/or `stable` update channels and updates the Sambee download-metadata feed.\n", "2.0": "+++\ntitle = \"Release Overview\"\n+++\n\n## Principles\n\n- The version number source of truth is the `VERSION` file in the repository.\n- Every built artifact gets a unique version number.\n- Each version is built only once.\n- Releases happen without rebuilds but by applying tags to existing builds (Docker image) or updating channel pointers (Companion app).\n\n## Process Overview for Test and Preview Candidates\n\n1. Update `VERSION` to the next plain numeric `X.Y.Z` build sequence ([details](../product-versioning/)).\n   - Run `./scripts/sync-version`.\n   - Commit the synchronized metadata on `main`.\n1. Build the affected component (see below for details).\n   - Build workflows reserve the current `VERSION` by adding a Git tag when building from the latest commit.\n   - Alternatively, select an existing `build-vX.Y.Z` Git tag to build from.\n1. Test the resulting build.\n   - Docker: Through the `test` tag.\n   - Companion: Through the Companion draft release assets. Promote them to the Companion `test` feed as needed.\n1. Repeat the loop with a new `Z` value when a new candidate is required. Never rebuild or replace a published artifact under the same version.\n\nNotes:\n\n- Docker and Companion candidates may be built independently.\n\n## Release Process \u0026 Checklist\n\n### Update Website\n\n1. Review the homepage content and update it where necessary.\n\n### Update Documentation\n\n1. Verify [Supported File Formats](../../../user-guide/reference/supported-file-formats/) and update as necessary.\n1. Finalize the target release's [What's New](/release-info/news-and-changes/whats-new/) page.\n1. Mark the target version as current in `website/data/docs-versions.toml`:\n   - Update the top-level `current` key, e.g.: `current = \"1.0\"`\n   - Update the `[[versions]]` sections of the previous and the new current version\n1. Run the VS Code task `Website: Refresh Docs Derived Artifacts`.\n1. Review the Docs Structure Report this creates in `/workspace/website-meta/docs-reports/docs-structure-report.html`.\n\nGit merge all changes.\n\n### Build Docker Image\n\nSee this [Overview](../docker-release-overview/). In short:\n\n1. Run [Release: Create Docker Image](../build-docker-image/)\n   - The workflow:\n      - Builds the [Docker image](https://github.com/sambee-app/sambee/pkgs/container/sambee/versions).\n      - Moves the `test` tag to it.\n      - Adds the `X.Y.Z` version tag.\n1. To also move the `beta` tag to the newly built image, run [Release: Publish Docker Image](../promote-docker-image/) manually.\n\n### Build Companion\n\nSee this [Overview](../companion-release-overview/). In short:\n\n1. Run [Release: Build Companion Artifact](../build-companion-release/).\n   - The workflow:\n      - Creates and publishes a [Companion release](https://github.com/sambee-app/sambee-companion/releases)\n      - Moves the `test` tag to it.\n      - Adds the `X.Y.Z` version tag.\n\n### Publish a Build\n\nTo publish a candidate build after testing and validation, complete the following steps.\n\n1. Run `Release: Create Public Sambee Release`. Specify:\n   - the validated canonical build version.\n   - the intended scope: `docker`, `companion`, or `both`.\n1. The workflow creates or verifies a draft release in the Sambee GitHub repo.\n1. Review and edit the draft release's changelog, then publish it manually.\n\nIf you selected `docker` or `both`:\n\n- Publishing the reviewed draft triggers [Release: Publish Docker Image](../promote-docker-image/) through the GitHub Release event.\n   - The workflow tags the image built earlier as `beta` (if not ahead) and `stable`, and adds a `X.Y` version tag.\n\nIf you selected `companion` or `both`:\n\n1. Run [Release: Promote Companion Release](../promote-companion-release/).\n   - The workflow promotes the release to the `beta`, and/or `stable` update channels and updates the Sambee download-metadata feed.\n"}, "page_contents": {"0.8": "+++\ntitle = \"Release Overview\"\n+++\n\n## Preparation\n\n1. Update the product **version** ([details](../product-versioning/)). Ensure it's at the version you want to release.\n\n## Build and Test the Docker Image\n\nSee [Overview](../docker-release-overview/).\n\n1. Run the CI workflow [Release: Create Docker Image](../build-docker-image/) to **build** the Docker image and move the `test` tag to it.\n   - Don't override the product version in the CI workflow.\n1. **Test** the newly built image (pull it via the `test` tag).\n\n## Documentation\n\n1. Review the **homepage** content and update it where necessary.\n1. **Docs:**\n   - Verify [Supported File Formats](../../../user-guide/reference/supported-file-formats/) and update as necessary.\n   - Finalize the target release's [What's New](/release-info/news-and-changes/whats-new/) page.\n   - Mark the target version as current in `website/data/docs-versions.toml`.\n   - Run the VS Code task **Website: Refresh Docs Derived Artifacts**.\n   - Review the Docs Structure Report this creates in `/workspace/website-meta/docs-reports/docs-structure-report.html`.\n1. Git merge all changes.\n\n## Publish the Docker Image\n\nSee [Overview](../docker-release-overview/).\n\n1. Create a Git tag on the commit the tested image was built from.\n1. Publish a GitHub release from that tag.\n   - Release publication triggers [Release: Publish Docker Image](../promote-docker-image/), which tags the image built earlier as `beta` (prereleases) or `stable` and adds version tags for stable releases.\n\n## Publish the Companion\n\nSee [Overview](../companion-release-overview/)\n\n1. Run [Release: Build Companion Artifact](../build-companion-release/) to build Companion for the target platforms.\n   - Publish the Companion GitHub Release created by the workflow.\n1. Run [Release: Promote Companion Release](../promote-companion-release/) to promote the release to the `test`, `beta`, and/or `stable` update channels and to update the Sambee download-metadata feed.\n", "0.9": "+++\ntitle = \"Release Overview\"\n+++\n\n## Principles\n\n- The version number source of truth is the `VERSION` file in the repository.\n- Every built artifact gets a unique version number.\n- Each version is built only once.\n- Releases happen without rebuilds but by applying tags to existing builds (Docker image) or updating channel pointers (Companion app).\n\n## Process Overview for Test and Preview Candidates\n\n1. Update `VERSION` to the next plain numeric `X.Y.Z` build sequence ([details](../product-versioning/)).\n   - Run `./scripts/sync-version`.\n   - Commit the synchronized metadata on `main`.\n1. Build the affected component (see below for details).\n   - Build workflows reserve the current `VERSION` by adding a Git tag when building from the latest commit.\n   - Alternatively, select an existing `build-vX.Y.Z` Git tag to build from.\n1. Test the resulting build.\n   - Docker: Through the `test` tag.\n   - Companion: Through the Companion draft release assets. Promote them to the Companion `test` feed as needed.\n1. Repeat the loop with a new `Z` value when a new candidate is required. Never rebuild or replace a published artifact under the same version.\n\nNotes:\n\n- Docker and Companion candidates may be built independently.\n\n## Component Build \u0026 Release Process\n\n### Update Documentation\n\n1. Review the homepage content and update it where necessary.\n1. Docs:\n   - Verify [Supported File Formats](../../../user-guide/reference/supported-file-formats/) and update as necessary.\n   - Finalize the target release's [What's New](/release-info/news-and-changes/whats-new/) page.\n   - Mark the target version as current in `website/data/docs-versions.toml`.\n   - Run the VS Code task `Website: Refresh Docs Derived Artifacts`.\n   - Review the Docs Structure Report this creates in `/workspace/website-meta/docs-reports/docs-structure-report.html`.\n1. Git merge all changes.\n\n### Build Docker Image\n\nSee this [Overview](../docker-release-overview/). In short:\n\n1. Run [Release: Create Docker Image](../build-docker-image/)\n   - The workflow:\n      - Builds the [Docker image](https://github.com/helgeklein/sambee/pkgs/container/sambee/versions).\n      - Moves the `test` tag to it.\n      - Adds the `X.Y.Z` version tag.\n1. To also move the `beta` tag to the newly built image, run [Release: Publish Docker Image](../promote-docker-image/) manually.\n\n### Build Companion\n\nSee this [Overview](../companion-release-overview/). In short:\n\n1. Run [Release: Build Companion Artifact](../build-companion-release/).\n   - The workflow creates a draft release in the [Companion GitHub repo](https://github.com/helgeklein/sambee-companion/releases).\n   - Publish it.\n\n### Publish a Build\n\nTo publish a candidate build after testing and validation, complete the following steps.\n\n1. Run `Release: Create Public Sambee Release`. Specify:\n   - the validated canonical build version.\n   - the intended scope: `docker`, `companion`, or `both`.\n1. The workflow creates or verifies a draft release in the Sambee GitHub repo.\n1. Review and edit the draft release's changelog, then publish it manually.\n\nIf you selected `docker` or `both`:\n\n- Publishing the reviewed draft triggers [Release: Publish Docker Image](../promote-docker-image/) through the GitHub Release event.\n   - The workflow tags the image built earlier as `beta` (if not ahead) and `stable`, and adds `X.Y` a version tag.\n\nIf you selected `companion` or `both`:\n\n1. Run [Release: Promote Companion Release](../promote-companion-release/).\n   - The workflow promotes the release to the `test`, `beta`, and/or `stable` update channels and updates the Sambee download-metadata feed.\n", "1.0": "+++\ntitle = \"Release Overview\"\n+++\n\n## Principles\n\n- The version number source of truth is the `VERSION` file in the repository.\n- Every built artifact gets a unique version number.\n- Each version is built only once.\n- Releases happen without rebuilds but by applying tags to existing builds (Docker image) or updating channel pointers (Companion app).\n\n## Process Overview for Test and Preview Candidates\n\n1. Update `VERSION` to the next plain numeric `X.Y.Z` build sequence ([details](../product-versioning/)).\n   - Run `./scripts/sync-version`.\n   - Commit the synchronized metadata on `main`.\n1. Build the affected component (see below for details).\n   - Build workflows reserve the current `VERSION` by adding a Git tag when building from the latest commit.\n   - Alternatively, select an existing `build-vX.Y.Z` Git tag to build from.\n1. Test the resulting build.\n   - Docker: Through the `test` tag.\n   - Companion: Through the Companion draft release assets. Promote them to the Companion `test` feed as needed.\n1. Repeat the loop with a new `Z` value when a new candidate is required. Never rebuild or replace a published artifact under the same version.\n\nNotes:\n\n- Docker and Companion candidates may be built independently.\n\n## Release Process \u0026 Checklist\n\n### Update Website\n\n1. Review the homepage content and update it where necessary.\n\n### Update Documentation\n\n1. Verify [Supported File Formats](../../../user-guide/reference/supported-file-formats/) and update as necessary.\n1. Finalize the target release's [What's New](/release-info/news-and-changes/whats-new/) page.\n1. Mark the target version as current in `website/data/docs-versions.toml`:\n   - Update the top-level `current` key, e.g.: `current = \"1.0\"`\n   - Update the `[[versions]]` sections of the previous and the new current version\n1. Run the VS Code task `Website: Refresh Docs Derived Artifacts`.\n1. Review the Docs Structure Report this creates in `/workspace/website-meta/docs-reports/docs-structure-report.html`.\n\nGit merge all changes.\n\n### Build Docker Image\n\nSee this [Overview](../docker-release-overview/). In short:\n\n1. Run [Release: Create Docker Image](../build-docker-image/)\n   - The workflow:\n      - Builds the [Docker image](https://github.com/helgeklein/sambee/pkgs/container/sambee/versions).\n      - Moves the `test` tag to it.\n      - Adds the `X.Y.Z` version tag.\n1. To also move the `beta` tag to the newly built image, run [Release: Publish Docker Image](../promote-docker-image/) manually.\n\n### Build Companion\n\nSee this [Overview](../companion-release-overview/). In short:\n\n1. Run [Release: Build Companion Artifact](../build-companion-release/).\n   - The workflow:\n      - Creates and publishes a [Companion release](https://github.com/helgeklein/sambee-companion/releases)\n      - Moves the `test` tag to it.\n      - Adds the `X.Y.Z` version tag.\n\n### Publish a Build\n\nTo publish a candidate build after testing and validation, complete the following steps.\n\n1. Run `Release: Create Public Sambee Release`. Specify:\n   - the validated canonical build version.\n   - the intended scope: `docker`, `companion`, or `both`.\n1. The workflow creates or verifies a draft release in the Sambee GitHub repo.\n1. Review and edit the draft release's changelog, then publish it manually.\n\nIf you selected `docker` or `both`:\n\n- Publishing the reviewed draft triggers [Release: Publish Docker Image](../promote-docker-image/) through the GitHub Release event.\n   - The workflow tags the image built earlier as `beta` (if not ahead) and `stable`, and adds a `X.Y` version tag.\n\nIf you selected `companion` or `both`:\n\n1. Run [Release: Promote Companion Release](../promote-companion-release/).\n   - The workflow promotes the release to the `beta`, and/or `stable` update channels and updates the Sambee download-metadata feed.\n", "2.0": "+++\ntitle = \"Release Overview\"\n+++\n\n## Principles\n\n- The version number source of truth is the `VERSION` file in the repository.\n- Every built artifact gets a unique version number.\n- Each version is built only once.\n- Releases happen without rebuilds but by applying tags to existing builds (Docker image) or updating channel pointers (Companion app).\n\n## Process Overview for Test and Preview Candidates\n\n1. Update `VERSION` to the next plain numeric `X.Y.Z` build sequence ([details](../product-versioning/)).\n   - Run `./scripts/sync-version`.\n   - Commit the synchronized metadata on `main`.\n1. Build the affected component (see below for details).\n   - Build workflows reserve the current `VERSION` by adding a Git tag when building from the latest commit.\n   - Alternatively, select an existing `build-vX.Y.Z` Git tag to build from.\n1. Test the resulting build.\n   - Docker: Through the `test` tag.\n   - Companion: Through the Companion draft release assets. Promote them to the Companion `test` feed as needed.\n1. Repeat the loop with a new `Z` value when a new candidate is required. Never rebuild or replace a published artifact under the same version.\n\nNotes:\n\n- Docker and Companion candidates may be built independently.\n\n## Release Process \u0026 Checklist\n\n### Update Website\n\n1. Review the homepage content and update it where necessary.\n\n### Update Documentation\n\n1. Verify [Supported File Formats](../../../user-guide/reference/supported-file-formats/) and update as necessary.\n1. Finalize the target release's [What's New](/release-info/news-and-changes/whats-new/) page.\n1. Mark the target version as current in `website/data/docs-versions.toml`:\n   - Update the top-level `current` key, e.g.: `current = \"1.0\"`\n   - Update the `[[versions]]` sections of the previous and the new current version\n1. Run the VS Code task `Website: Refresh Docs Derived Artifacts`.\n1. Review the Docs Structure Report this creates in `/workspace/website-meta/docs-reports/docs-structure-report.html`.\n\nGit merge all changes.\n\n### Build Docker Image\n\nSee this [Overview](../docker-release-overview/). In short:\n\n1. Run [Release: Create Docker Image](../build-docker-image/)\n   - The workflow:\n      - Builds the [Docker image](https://github.com/sambee-app/sambee/pkgs/container/sambee/versions).\n      - Moves the `test` tag to it.\n      - Adds the `X.Y.Z` version tag.\n1. To also move the `beta` tag to the newly built image, run [Release: Publish Docker Image](../promote-docker-image/) manually.\n\n### Build Companion\n\nSee this [Overview](../companion-release-overview/). In short:\n\n1. Run [Release: Build Companion Artifact](../build-companion-release/).\n   - The workflow:\n      - Creates and publishes a [Companion release](https://github.com/sambee-app/sambee-companion/releases)\n      - Moves the `test` tag to it.\n      - Adds the `X.Y.Z` version tag.\n\n### Publish a Build\n\nTo publish a candidate build after testing and validation, complete the following steps.\n\n1. Run `Release: Create Public Sambee Release`. Specify:\n   - the validated canonical build version.\n   - the intended scope: `docker`, `companion`, or `both`.\n1. The workflow creates or verifies a draft release in the Sambee GitHub repo.\n1. Review and edit the draft release's changelog, then publish it manually.\n\nIf you selected `docker` or `both`:\n\n- Publishing the reviewed draft triggers [Release: Publish Docker Image](../promote-docker-image/) through the GitHub Release event.\n   - The workflow tags the image built earlier as `beta` (if not ahead) and `stable`, and adds a `X.Y` version tag.\n\nIf you selected `companion` or `both`:\n\n1. Run [Release: Promote Companion Release](../promote-companion-release/).\n   - The workflow promotes the release to the `beta`, and/or `stable` update channels and updates the Sambee download-metadata feed.\n"}, "flags": {"has_branched": true, "has_inherited": false, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/release-and-versioning/companion-release-cleanup", "parent_id": "section:developer-guide/release-and-versioning", "depth": 2, "kind": "page", "label": "companion-release-cleanup", "title": "Companion Release Cleanup", "path": "developer-guide/release-and-versioning/companion-release-cleanup", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "missing"}, "1.0": {"state": "authored"}, "2.0": {"state": "branched", "source_version": "1.0", "diff_added": 1, "diff_removed": 2}}, "content_versions": {"1.0": "+++\ntitle = \"Companion Release Cleanup\"\n+++\n\nCompanion cleanup removes obsolete GitHub Releases after a successful feed promotion. It also runs on a schedule and can be started manually as `Maintenance: Clean Up Companion Releases`.\n\n## Retention Rules\n\nCleanup keeps:\n\n- Every published, non-prerelease release referenced by a `test`, `beta`, `stable`, or Sambee feed marker.\n- The latest published, non-prerelease `companion-vX.Y.Z` release in every `X.Y` series.\n\nFor example, it keeps `companion-v8.0.13` and deletes `companion-v8.0.12` unless a feed still points to the older release.\n\nCleanup deletes every other GitHub Release, including obsolete drafts, GitHub prereleases, and noncanonical legacy releases. It does not delete Git tags.\n\n## Safety Checks\n\nBefore deleting anything, cleanup reads the committed feed files in `sambee-companion` and validates every referenced release asset.\n\nFor each present marker, it requires:\n\n- A plain numeric `X.Y.Z` version.\n- Asset URLs for `helgeklein/sambee-companion` release downloads.\n- One canonical `companion-vX.Y.Z` release tag for every asset in the marker.\n- A marker version that matches that tag.\n- A published, non-prerelease release containing every referenced asset.\n\nMissing marker files represent an unpromoted channel and do not protect a release. A malformed present marker, inconsistent asset URL, missing asset, ambiguous release, or GitHub API failure stops cleanup before deletion.\n\nThe `companion-release-publication` concurrency group prevents cleanup from overlapping an active provisional release upload.\n\n## When It Runs\n\nCleanup runs after automatic `test` promotion from `Release: Build Companion Artifact` and after successful manual `Release: Promote Companion Release` runs. Use the maintenance workflow when you need an additional reconciliation pass.\n\n", "2.0": "+++\ntitle = \"Companion Release Cleanup\"\n+++\n\nCompanion cleanup removes obsolete GitHub Releases after a successful feed promotion. It also runs on a schedule and can be started manually as `Maintenance: Clean Up Companion Releases`.\n\n## Retention Rules\n\nCleanup keeps:\n\n- Every published, non-prerelease release referenced by a `test`, `beta`, `stable`, or Sambee feed marker.\n- The latest published, non-prerelease `companion-vX.Y.Z` release in every `X.Y` series.\n\nFor example, it keeps `companion-v8.0.13` and deletes `companion-v8.0.12` unless a feed still points to the older release.\n\nCleanup deletes every other GitHub Release, including obsolete drafts, GitHub prereleases, and noncanonical legacy releases. It does not delete Git tags.\n\n## Safety Checks\n\nBefore deleting anything, cleanup reads the committed feed files in `sambee-companion` and validates every referenced release asset.\n\nFor each present marker, it requires:\n\n- A plain numeric `X.Y.Z` version.\n- Asset URLs for `sambee-app/sambee-companion` release downloads.\n- One canonical `companion-vX.Y.Z` release tag for every asset in the marker.\n- A marker version that matches that tag.\n- A published, non-prerelease release containing every referenced asset.\n\nMissing marker files represent an unpromoted channel and do not protect a release. A malformed present marker, inconsistent asset URL, missing asset, ambiguous release, or GitHub API failure stops cleanup before deletion.\n\nThe `companion-release-publication` concurrency group prevents cleanup from overlapping an active provisional release upload.\n\n## When It Runs\n\nCleanup runs after automatic `test` promotion from `Release: Build Companion Artifact` and after successful manual `Release: Promote Companion Release` runs. Use the maintenance workflow when you need an additional reconciliation pass.\n"}, "page_contents": {"1.0": "+++\ntitle = \"Companion Release Cleanup\"\n+++\n\nCompanion cleanup removes obsolete GitHub Releases after a successful feed promotion. It also runs on a schedule and can be started manually as `Maintenance: Clean Up Companion Releases`.\n\n## Retention Rules\n\nCleanup keeps:\n\n- Every published, non-prerelease release referenced by a `test`, `beta`, `stable`, or Sambee feed marker.\n- The latest published, non-prerelease `companion-vX.Y.Z` release in every `X.Y` series.\n\nFor example, it keeps `companion-v8.0.13` and deletes `companion-v8.0.12` unless a feed still points to the older release.\n\nCleanup deletes every other GitHub Release, including obsolete drafts, GitHub prereleases, and noncanonical legacy releases. It does not delete Git tags.\n\n## Safety Checks\n\nBefore deleting anything, cleanup reads the committed feed files in `sambee-companion` and validates every referenced release asset.\n\nFor each present marker, it requires:\n\n- A plain numeric `X.Y.Z` version.\n- Asset URLs for `helgeklein/sambee-companion` release downloads.\n- One canonical `companion-vX.Y.Z` release tag for every asset in the marker.\n- A marker version that matches that tag.\n- A published, non-prerelease release containing every referenced asset.\n\nMissing marker files represent an unpromoted channel and do not protect a release. A malformed present marker, inconsistent asset URL, missing asset, ambiguous release, or GitHub API failure stops cleanup before deletion.\n\nThe `companion-release-publication` concurrency group prevents cleanup from overlapping an active provisional release upload.\n\n## When It Runs\n\nCleanup runs after automatic `test` promotion from `Release: Build Companion Artifact` and after successful manual `Release: Promote Companion Release` runs. Use the maintenance workflow when you need an additional reconciliation pass.\n\n", "2.0": "+++\ntitle = \"Companion Release Cleanup\"\n+++\n\nCompanion cleanup removes obsolete GitHub Releases after a successful feed promotion. It also runs on a schedule and can be started manually as `Maintenance: Clean Up Companion Releases`.\n\n## Retention Rules\n\nCleanup keeps:\n\n- Every published, non-prerelease release referenced by a `test`, `beta`, `stable`, or Sambee feed marker.\n- The latest published, non-prerelease `companion-vX.Y.Z` release in every `X.Y` series.\n\nFor example, it keeps `companion-v8.0.13` and deletes `companion-v8.0.12` unless a feed still points to the older release.\n\nCleanup deletes every other GitHub Release, including obsolete drafts, GitHub prereleases, and noncanonical legacy releases. It does not delete Git tags.\n\n## Safety Checks\n\nBefore deleting anything, cleanup reads the committed feed files in `sambee-companion` and validates every referenced release asset.\n\nFor each present marker, it requires:\n\n- A plain numeric `X.Y.Z` version.\n- Asset URLs for `sambee-app/sambee-companion` release downloads.\n- One canonical `companion-vX.Y.Z` release tag for every asset in the marker.\n- A marker version that matches that tag.\n- A published, non-prerelease release containing every referenced asset.\n\nMissing marker files represent an unpromoted channel and do not protect a release. A malformed present marker, inconsistent asset URL, missing asset, ambiguous release, or GitHub API failure stops cleanup before deletion.\n\nThe `companion-release-publication` concurrency group prevents cleanup from overlapping an active provisional release upload.\n\n## When It Runs\n\nCleanup runs after automatic `test` promotion from `Release: Build Companion Artifact` and after successful manual `Release: Promote Companion Release` runs. Use the maintenance workflow when you need an additional reconciliation pass.\n"}, "flags": {"has_branched": true, "has_inherited": false, "has_structural": false, "has_invalid": false}}, {"id": "book:website-dev-guide", "parent_id": null, "depth": 0, "kind": "book", "label": "website-dev-guide", "title": "Website Dev Guide", "path": "website-dev-guide", "has_children": true, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "branched", "source_version": "0.7", "diff_added": 0, "diff_removed": 0}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "inherited", "source_version": "0.9"}}, "content_versions": {"0.7": "+++\ntitle = \"Website Dev Guide\"\n+++\n\nUse this guide to edit and publish website and docs content, understand how the Hugo site and versioned docs system work, use the docs editor safely, and change shared website systems such as media and typography.\n\n## Start Here if You Want To\n\n- Add or revise published website or docs content.\n- Understand the website build pipeline and versioned docs model.\n- Update docs navigation, versions, or inheritance behavior safely.\n- Use the docs editor for structural docs changes.\n- Change shared website theme systems such as media handling or typography.\n- Prepare or maintain the website publishing environment.\n\n## In This Guide\n\n- [Docs Platform](./docs-platform/website-and-docs-architecture-overview/): Understand what lives in `website/`, how docs routing works, and how versioned docs content is resolved.\n- [Authoring and Tooling](./authoring-and-tooling/docs-authoring-workflow/): Write published content, update navigation, and use the docs editor safely.\n- [Site Systems](./site-systems/media-publishing-workflow/): Preserve the media and typography contracts used by the public site.\n- [Setup and Operations](./setup-and-operations/set-up-cloudflare-pages-publishing/): Configure publishing infrastructure such as Cloudflare Pages and understand what the current website workflow actually deploys.\n\n## Use the Right Guide\n\n- Use this Website Dev Guide for website editing, docs authoring, Hugo theme work, docs tooling, shared website system changes, and website publishing infrastructure.\n- Use the [Developer Guide](../developer-guide/) when the work is primarily on the backend, frontend app, companion, or cross-application runtime behavior.\n- Use the [Admin Guide](../admin-guide/) when the next step is deployment, configuration, operations, or troubleshooting a running service.\n- Use the [User Guide](../user-guide/) when the next step belongs to someone using Sambee in normal product workflows.\n", "0.8": "+++\ntitle = \"Website Dev Guide\"\n+++\n\nUse this guide to edit and publish website and docs content, understand how the Hugo site and versioned docs system work, use the docs editor safely, and change shared website systems such as media and typography.\n\n## Start Here if You Want To\n\n- Add or revise published website or docs content.\n- Understand the website build pipeline and versioned docs model.\n- Update docs navigation, versions, or inheritance behavior safely.\n- Use the docs editor for structural docs changes.\n- Change shared website theme systems such as media handling or typography.\n- Prepare or maintain the website publishing environment.\n\n## In This Guide\n\n- [Docs Platform](./docs-platform/website-and-docs-architecture-overview/): Understand what lives in `website/`, how docs routing works, and how versioned docs content is resolved.\n- [Authoring and Tooling](./authoring-and-tooling/docs-authoring-workflow/): Write published content, update navigation, and use the docs editor safely.\n- [Site Systems](./site-systems/media-publishing-workflow/): Preserve the media and typography contracts used by the public site.\n- [Setup and Operations](./setup-and-operations/set-up-cloudflare-pages-publishing/): Configure publishing infrastructure such as Cloudflare Pages and understand what the current website workflow actually deploys.\n\n## Use the Right Guide\n\n- Use this Website Dev Guide for website editing, docs authoring, Hugo theme work, docs tooling, shared website system changes, and website publishing infrastructure.\n- Use the [Developer Guide](../developer-guide/) when the work is primarily on the backend, frontend app, companion, or cross-application runtime behavior.\n- Use the [Admin Guide](../admin-guide/) when the next step is deployment, configuration, operations, or troubleshooting a running service.\n- Use the [User Guide](../user-guide/) when the next step belongs to someone using Sambee in normal product workflows.\n", "0.9": "+++\ntitle = \"Website Dev Guide\"\n+++\n\nUse this guide to edit and publish website and docs content, understand how the Hugo site and versioned docs system work, use the docs editor safely, and change shared website systems such as media and typography.\n\n## Start Here if You Want To\n\n- Add or revise published website or docs content.\n- Understand the website build pipeline and versioned docs model.\n- Update docs navigation, versions, or inheritance behavior safely.\n- Use the docs editor for structural docs changes.\n- Change shared website theme systems such as media handling or typography.\n- Prepare or maintain the website publishing environment.\n\n## In This Guide\n\n- [Docs Platform](./docs-platform/website-and-docs-architecture-overview/): Understand what lives in `website/`, how docs routing works, and how versioned docs content is resolved.\n- [Authoring and Tooling](./authoring-and-tooling/docs-authoring-workflow/): Write published content, update navigation, and use the docs editor safely.\n- [Site Systems](./site-systems/media-publishing-workflow/): Preserve the media and typography contracts used by the public site.\n- [Setup and Operations](./setup-and-operations/set-up-cloudflare-pages-publishing/): Configure publishing infrastructure such as Cloudflare Pages and understand what the current website workflow actually deploys.\n\n## Use the Right Guide\n\n- Use this Website Dev Guide for website editing, docs authoring, Hugo theme work, docs tooling, shared website system changes, and website publishing infrastructure.\n- Use the [Developer Guide](../developer-guide/) when the work is primarily on the backend, frontend app, companion, or cross-application runtime behavior.\n- Use the [Admin Guide](../admin-guide/) when the next step is deployment, configuration, operations, or troubleshooting a running service.\n- Use the [User Guide](../user-guide/) when the next step belongs to someone using Sambee in normal product workflows.\n", "1.0": "+++\ntitle = \"Website Dev Guide\"\n+++\n\nUse this guide to edit and publish website and docs content, understand how the Hugo site and versioned docs system work, use the docs editor safely, and change shared website systems such as media and typography.\n\n## Start Here if You Want To\n\n- Add or revise published website or docs content.\n- Understand the website build pipeline and versioned docs model.\n- Update docs navigation, versions, or inheritance behavior safely.\n- Use the docs editor for structural docs changes.\n- Change shared website theme systems such as media handling or typography.\n- Prepare or maintain the website publishing environment.\n\n## In This Guide\n\n- [Docs Platform](./docs-platform/website-and-docs-architecture-overview/): Understand what lives in `website/`, how docs routing works, and how versioned docs content is resolved.\n- [Authoring and Tooling](./authoring-and-tooling/docs-authoring-workflow/): Write published content, update navigation, and use the docs editor safely.\n- [Site Systems](./site-systems/media-publishing-workflow/): Preserve the media and typography contracts used by the public site.\n- [Setup and Operations](./setup-and-operations/set-up-cloudflare-pages-publishing/): Configure publishing infrastructure such as Cloudflare Pages and understand what the current website workflow actually deploys.\n\n## Use the Right Guide\n\n- Use this Website Dev Guide for website editing, docs authoring, Hugo theme work, docs tooling, shared website system changes, and website publishing infrastructure.\n- Use the [Developer Guide](../developer-guide/) when the work is primarily on the backend, frontend app, companion, or cross-application runtime behavior.\n- Use the [Admin Guide](../admin-guide/) when the next step is deployment, configuration, operations, or troubleshooting a running service.\n- Use the [User Guide](../user-guide/) when the next step belongs to someone using Sambee in normal product workflows.\n", "2.0": "+++\ntitle = \"Website Dev Guide\"\n+++\n\nUse this guide to edit and publish website and docs content, understand how the Hugo site and versioned docs system work, use the docs editor safely, and change shared website systems such as media and typography.\n\n## Start Here if You Want To\n\n- Add or revise published website or docs content.\n- Understand the website build pipeline and versioned docs model.\n- Update docs navigation, versions, or inheritance behavior safely.\n- Use the docs editor for structural docs changes.\n- Change shared website theme systems such as media handling or typography.\n- Prepare or maintain the website publishing environment.\n\n## In This Guide\n\n- [Docs Platform](./docs-platform/website-and-docs-architecture-overview/): Understand what lives in `website/`, how docs routing works, and how versioned docs content is resolved.\n- [Authoring and Tooling](./authoring-and-tooling/docs-authoring-workflow/): Write published content, update navigation, and use the docs editor safely.\n- [Site Systems](./site-systems/media-publishing-workflow/): Preserve the media and typography contracts used by the public site.\n- [Setup and Operations](./setup-and-operations/set-up-cloudflare-pages-publishing/): Configure publishing infrastructure such as Cloudflare Pages and understand what the current website workflow actually deploys.\n\n## Use the Right Guide\n\n- Use this Website Dev Guide for website editing, docs authoring, Hugo theme work, docs tooling, shared website system changes, and website publishing infrastructure.\n- Use the [Developer Guide](../developer-guide/) when the work is primarily on the backend, frontend app, companion, or cross-application runtime behavior.\n- Use the [Admin Guide](../admin-guide/) when the next step is deployment, configuration, operations, or troubleshooting a running service.\n- Use the [User Guide](../user-guide/) when the next step belongs to someone using Sambee in normal product workflows.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:website-dev-guide/docs-platform", "parent_id": "book:website-dev-guide", "depth": 1, "kind": "section", "label": "docs-platform", "title": "Docs Platform", "path": "website-dev-guide/docs-platform", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:website-dev-guide/docs-platform/website-and-docs-architecture-overview", "parent_id": "section:website-dev-guide/docs-platform", "depth": 2, "kind": "page", "label": "website-and-docs-architecture-overview", "title": "Website And Docs Architecture Overview", "path": "website-dev-guide/docs-platform/website-and-docs-architecture-overview", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Website and Docs Architecture Overview\"\n+++\n\n## What Lives In `website/`\n\nThe public site lives under `website/`. The important areas are:\n\n```text\nwebsite/\n  content/\n    docs/\n  data/\n    docs-nav/\n    docs-versions.toml\n  scripts/\n  themes/sambee/\n  assets/\n  static/\n```\n\nIn practice:\n\n- `content/` holds the authored website pages and docs pages.\n- `content/docs/` holds the published versioned docs books.\n- `data/docs-versions.toml` declares the canonical docs version order and the current version.\n- `data/docs-nav/\u003cversion\u003e.toml` declares book, section, and page ordering for one version.\n- `scripts/` holds build helpers, docs validation, docs materialization, and docs editor automation.\n- `themes/sambee/` holds the Hugo layouts, partials, CSS, and JS for the public site.\n- `assets/` and `static/` hold source media, generated media, and static files.\n\n## How Docs Routing Works\n\nDocs content is versioned in the content tree:\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe current docs version also publishes stable unversioned routes:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nArchived or explicit versioned routes remain available at:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/...`\n\nThe routing rules, inheritance markers, and stable-current behavior are covered in more detail in [Docs Content Model, Navigation, and Inheritance](../docs-content-model-navigation-and-inheritance/).\n\n## Build and Preview Pipeline\n\nThe website build is more than a plain Hugo render.\n\nThe normal production-style build is:\n\n```bash\ncd website\nnpm run build\n```\n\nThat command runs:\n\n1. theme generation\n2. docs validation\n3. inherited-doc materialization\n4. Hugo site build\n5. homepage CTA validation\n\nFor local development, use:\n\n```bash\n./scripts/start-website\n```\n\nOr run the website dev workflow directly:\n\n```bash\ncd website\nnpm run dev\n```\n\nThat dev workflow also keeps search indexing and WebP generation in sync while you iterate. Its transient output is written to `website/public-dev/`, so production-style builds can safely continue to use `website/public/` without disrupting the running preview.\n", "0.8": "+++\ntitle = \"Website and Docs Architecture Overview\"\n+++\n\n## What Lives In `website/`\n\nThe public site lives under `website/`. The important areas are:\n\n```text\nwebsite/\n  content/\n    docs/\n  data/\n    docs-nav/\n    docs-versions.toml\n  scripts/\n  themes/sambee/\n  assets/\n  static/\n```\n\nIn practice:\n\n- `content/` holds the authored website pages and docs pages.\n- `content/docs/` holds the published versioned docs books.\n- `data/docs-versions.toml` declares the canonical docs version order and the current version.\n- `data/docs-nav/\u003cversion\u003e.toml` declares book, section, and page ordering for one version.\n- `scripts/` holds build helpers, docs validation, docs materialization, and docs editor automation.\n- `themes/sambee/` holds the Hugo layouts, partials, CSS, and JS for the public site.\n- `assets/` and `static/` hold source media, generated media, and static files.\n\n## How Docs Routing Works\n\nDocs content is versioned in the content tree:\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe current docs version also publishes stable unversioned routes:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nArchived or explicit versioned routes remain available at:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/...`\n\nThe routing rules, inheritance markers, and stable-current behavior are covered in more detail in [Docs Content Model, Navigation, and Inheritance](../docs-content-model-navigation-and-inheritance/).\n\n## Build and Preview Pipeline\n\nThe website build is more than a plain Hugo render.\n\nThe normal production-style build is:\n\n```bash\ncd website\nnpm run build\n```\n\nThat command runs:\n\n1. theme generation\n2. docs validation\n3. inherited-doc materialization\n4. Hugo site build\n5. homepage CTA validation\n\nFor local development, use:\n\n```bash\n./scripts/start-website\n```\n\nOr run the website dev workflow directly:\n\n```bash\ncd website\nnpm run dev\n```\n\nThat dev workflow also keeps search indexing and WebP generation in sync while you iterate. Its transient output is written to `website/public-dev/`, so production-style builds can safely continue to use `website/public/` without disrupting the running preview.\n", "0.9": "+++\ntitle = \"Website and Docs Architecture Overview\"\n+++\n\n## What Lives In `website/`\n\nThe public site lives under `website/`. The important areas are:\n\n```text\nwebsite/\n  content/\n    docs/\n  data/\n    docs-nav/\n    docs-versions.toml\n  scripts/\n  themes/sambee/\n  assets/\n  static/\n```\n\nIn practice:\n\n- `content/` holds the authored website pages and docs pages.\n- `content/docs/` holds the published versioned docs books.\n- `data/docs-versions.toml` declares the canonical docs version order and the current version.\n- `data/docs-nav/\u003cversion\u003e.toml` declares book, section, and page ordering for one version.\n- `scripts/` holds build helpers, docs validation, docs materialization, and docs editor automation.\n- `themes/sambee/` holds the Hugo layouts, partials, CSS, and JS for the public site.\n- `assets/` and `static/` hold source media, generated media, and static files.\n\n## How Docs Routing Works\n\nDocs content is versioned in the content tree:\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe current docs version also publishes stable unversioned routes:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nArchived or explicit versioned routes remain available at:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/...`\n\nThe routing rules, inheritance markers, and stable-current behavior are covered in more detail in [Docs Content Model, Navigation, and Inheritance](../docs-content-model-navigation-and-inheritance/).\n\n## Build and Preview Pipeline\n\nThe website build is more than a plain Hugo render.\n\nThe normal production-style build is:\n\n```bash\ncd website\nnpm run build\n```\n\nThat command runs:\n\n1. theme generation\n2. docs validation\n3. inherited-doc materialization\n4. Hugo site build\n5. homepage CTA validation\n\nFor local development, use:\n\n```bash\n./scripts/start-website\n```\n\nOr run the website dev workflow directly:\n\n```bash\ncd website\nnpm run dev\n```\n\nThat dev workflow also keeps search indexing and WebP generation in sync while you iterate. Its transient output is written to `website/public-dev/`, so production-style builds can safely continue to use `website/public/` without disrupting the running preview.\n", "1.0": "+++\ntitle = \"Website and Docs Architecture Overview\"\n+++\n\n## What Lives In `website/`\n\nThe public site lives under `website/`. The important areas are:\n\n```text\nwebsite/\n  content/\n    docs/\n  data/\n    docs-nav/\n    docs-versions.toml\n  scripts/\n  themes/sambee/\n  assets/\n  static/\n```\n\nIn practice:\n\n- `content/` holds the authored website pages and docs pages.\n- `content/docs/` holds the published versioned docs books.\n- `data/docs-versions.toml` declares the canonical docs version order and the current version.\n- `data/docs-nav/\u003cversion\u003e.toml` declares book, section, and page ordering for one version.\n- `scripts/` holds build helpers, docs validation, docs materialization, and docs editor automation.\n- `themes/sambee/` holds the Hugo layouts, partials, CSS, and JS for the public site.\n- `assets/` and `static/` hold source media, generated media, and static files.\n\n## How Docs Routing Works\n\nDocs content is versioned in the content tree:\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe current docs version also publishes stable unversioned routes:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nArchived or explicit versioned routes remain available at:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/...`\n\nThe routing rules, inheritance markers, and stable-current behavior are covered in more detail in [Docs Content Model, Navigation, and Inheritance](../docs-content-model-navigation-and-inheritance/).\n\n## Build and Preview Pipeline\n\nThe website build is more than a plain Hugo render.\n\nThe normal production-style build is:\n\n```bash\ncd website\nnpm run build\n```\n\nThat command runs:\n\n1. theme generation\n2. docs validation\n3. inherited-doc materialization\n4. Hugo site build\n5. homepage CTA validation\n\nFor local development, use:\n\n```bash\n./scripts/start-website\n```\n\nOr run the website dev workflow directly:\n\n```bash\ncd website\nnpm run dev\n```\n\nThat dev workflow also keeps search indexing and WebP generation in sync while you iterate. Its transient output is written to `website/public-dev/`, so production-style builds can safely continue to use `website/public/` without disrupting the running preview.\n", "2.0": "+++\ntitle = \"Website and Docs Architecture Overview\"\n+++\n\n## What Lives In `website/`\n\nThe public site lives under `website/`. The important areas are:\n\n```text\nwebsite/\n  content/\n    docs/\n  data/\n    docs-nav/\n    docs-versions.toml\n  scripts/\n  themes/sambee/\n  assets/\n  static/\n```\n\nIn practice:\n\n- `content/` holds the authored website pages and docs pages.\n- `content/docs/` holds the published versioned docs books.\n- `data/docs-versions.toml` declares the canonical docs version order and the current version.\n- `data/docs-nav/\u003cversion\u003e.toml` declares book, section, and page ordering for one version.\n- `scripts/` holds build helpers, docs validation, docs materialization, and docs editor automation.\n- `themes/sambee/` holds the Hugo layouts, partials, CSS, and JS for the public site.\n- `assets/` and `static/` hold source media, generated media, and static files.\n\n## How Docs Routing Works\n\nDocs content is versioned in the content tree:\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe current docs version also publishes stable unversioned routes:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nArchived or explicit versioned routes remain available at:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/...`\n\nThe routing rules, inheritance markers, and stable-current behavior are covered in more detail in [Docs Content Model, Navigation, and Inheritance](../docs-content-model-navigation-and-inheritance/).\n\n## Build and Preview Pipeline\n\nThe website build is more than a plain Hugo render.\n\nThe normal production-style build is:\n\n```bash\ncd website\nnpm run build\n```\n\nThat command runs:\n\n1. theme generation\n2. docs validation\n3. inherited-doc materialization\n4. Hugo site build\n5. homepage CTA validation\n\nFor local development, use:\n\n```bash\n./scripts/start-website\n```\n\nOr run the website dev workflow directly:\n\n```bash\ncd website\nnpm run dev\n```\n\nThat dev workflow also keeps search indexing and WebP generation in sync while you iterate. Its transient output is written to `website/public-dev/`, so production-style builds can safely continue to use `website/public/` without disrupting the running preview.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Website and Docs Architecture Overview\"\n+++\n\n## What Lives In `website/`\n\nThe public site lives under `website/`. The important areas are:\n\n```text\nwebsite/\n  content/\n    docs/\n  data/\n    docs-nav/\n    docs-versions.toml\n  scripts/\n  themes/sambee/\n  assets/\n  static/\n```\n\nIn practice:\n\n- `content/` holds the authored website pages and docs pages.\n- `content/docs/` holds the published versioned docs books.\n- `data/docs-versions.toml` declares the canonical docs version order and the current version.\n- `data/docs-nav/\u003cversion\u003e.toml` declares book, section, and page ordering for one version.\n- `scripts/` holds build helpers, docs validation, docs materialization, and docs editor automation.\n- `themes/sambee/` holds the Hugo layouts, partials, CSS, and JS for the public site.\n- `assets/` and `static/` hold source media, generated media, and static files.\n\n## How Docs Routing Works\n\nDocs content is versioned in the content tree:\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe current docs version also publishes stable unversioned routes:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nArchived or explicit versioned routes remain available at:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/...`\n\nThe routing rules, inheritance markers, and stable-current behavior are covered in more detail in [Docs Content Model, Navigation, and Inheritance](../docs-content-model-navigation-and-inheritance/).\n\n## Build and Preview Pipeline\n\nThe website build is more than a plain Hugo render.\n\nThe normal production-style build is:\n\n```bash\ncd website\nnpm run build\n```\n\nThat command runs:\n\n1. theme generation\n2. docs validation\n3. inherited-doc materialization\n4. Hugo site build\n5. homepage CTA validation\n\nFor local development, use:\n\n```bash\n./scripts/start-website\n```\n\nOr run the website dev workflow directly:\n\n```bash\ncd website\nnpm run dev\n```\n\nThat dev workflow also keeps search indexing and WebP generation in sync while you iterate. Its transient output is written to `website/public-dev/`, so production-style builds can safely continue to use `website/public/` without disrupting the running preview.\n", "0.8": "+++\ntitle = \"Website and Docs Architecture Overview\"\n+++\n\n## What Lives In `website/`\n\nThe public site lives under `website/`. The important areas are:\n\n```text\nwebsite/\n  content/\n    docs/\n  data/\n    docs-nav/\n    docs-versions.toml\n  scripts/\n  themes/sambee/\n  assets/\n  static/\n```\n\nIn practice:\n\n- `content/` holds the authored website pages and docs pages.\n- `content/docs/` holds the published versioned docs books.\n- `data/docs-versions.toml` declares the canonical docs version order and the current version.\n- `data/docs-nav/\u003cversion\u003e.toml` declares book, section, and page ordering for one version.\n- `scripts/` holds build helpers, docs validation, docs materialization, and docs editor automation.\n- `themes/sambee/` holds the Hugo layouts, partials, CSS, and JS for the public site.\n- `assets/` and `static/` hold source media, generated media, and static files.\n\n## How Docs Routing Works\n\nDocs content is versioned in the content tree:\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe current docs version also publishes stable unversioned routes:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nArchived or explicit versioned routes remain available at:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/...`\n\nThe routing rules, inheritance markers, and stable-current behavior are covered in more detail in [Docs Content Model, Navigation, and Inheritance](../docs-content-model-navigation-and-inheritance/).\n\n## Build and Preview Pipeline\n\nThe website build is more than a plain Hugo render.\n\nThe normal production-style build is:\n\n```bash\ncd website\nnpm run build\n```\n\nThat command runs:\n\n1. theme generation\n2. docs validation\n3. inherited-doc materialization\n4. Hugo site build\n5. homepage CTA validation\n\nFor local development, use:\n\n```bash\n./scripts/start-website\n```\n\nOr run the website dev workflow directly:\n\n```bash\ncd website\nnpm run dev\n```\n\nThat dev workflow also keeps search indexing and WebP generation in sync while you iterate. Its transient output is written to `website/public-dev/`, so production-style builds can safely continue to use `website/public/` without disrupting the running preview.\n", "0.9": "+++\ntitle = \"Website and Docs Architecture Overview\"\n+++\n\n## What Lives In `website/`\n\nThe public site lives under `website/`. The important areas are:\n\n```text\nwebsite/\n  content/\n    docs/\n  data/\n    docs-nav/\n    docs-versions.toml\n  scripts/\n  themes/sambee/\n  assets/\n  static/\n```\n\nIn practice:\n\n- `content/` holds the authored website pages and docs pages.\n- `content/docs/` holds the published versioned docs books.\n- `data/docs-versions.toml` declares the canonical docs version order and the current version.\n- `data/docs-nav/\u003cversion\u003e.toml` declares book, section, and page ordering for one version.\n- `scripts/` holds build helpers, docs validation, docs materialization, and docs editor automation.\n- `themes/sambee/` holds the Hugo layouts, partials, CSS, and JS for the public site.\n- `assets/` and `static/` hold source media, generated media, and static files.\n\n## How Docs Routing Works\n\nDocs content is versioned in the content tree:\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe current docs version also publishes stable unversioned routes:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nArchived or explicit versioned routes remain available at:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/...`\n\nThe routing rules, inheritance markers, and stable-current behavior are covered in more detail in [Docs Content Model, Navigation, and Inheritance](../docs-content-model-navigation-and-inheritance/).\n\n## Build and Preview Pipeline\n\nThe website build is more than a plain Hugo render.\n\nThe normal production-style build is:\n\n```bash\ncd website\nnpm run build\n```\n\nThat command runs:\n\n1. theme generation\n2. docs validation\n3. inherited-doc materialization\n4. Hugo site build\n5. homepage CTA validation\n\nFor local development, use:\n\n```bash\n./scripts/start-website\n```\n\nOr run the website dev workflow directly:\n\n```bash\ncd website\nnpm run dev\n```\n\nThat dev workflow also keeps search indexing and WebP generation in sync while you iterate. Its transient output is written to `website/public-dev/`, so production-style builds can safely continue to use `website/public/` without disrupting the running preview.\n", "1.0": "+++\ntitle = \"Website and Docs Architecture Overview\"\n+++\n\n## What Lives In `website/`\n\nThe public site lives under `website/`. The important areas are:\n\n```text\nwebsite/\n  content/\n    docs/\n  data/\n    docs-nav/\n    docs-versions.toml\n  scripts/\n  themes/sambee/\n  assets/\n  static/\n```\n\nIn practice:\n\n- `content/` holds the authored website pages and docs pages.\n- `content/docs/` holds the published versioned docs books.\n- `data/docs-versions.toml` declares the canonical docs version order and the current version.\n- `data/docs-nav/\u003cversion\u003e.toml` declares book, section, and page ordering for one version.\n- `scripts/` holds build helpers, docs validation, docs materialization, and docs editor automation.\n- `themes/sambee/` holds the Hugo layouts, partials, CSS, and JS for the public site.\n- `assets/` and `static/` hold source media, generated media, and static files.\n\n## How Docs Routing Works\n\nDocs content is versioned in the content tree:\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe current docs version also publishes stable unversioned routes:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nArchived or explicit versioned routes remain available at:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/...`\n\nThe routing rules, inheritance markers, and stable-current behavior are covered in more detail in [Docs Content Model, Navigation, and Inheritance](../docs-content-model-navigation-and-inheritance/).\n\n## Build and Preview Pipeline\n\nThe website build is more than a plain Hugo render.\n\nThe normal production-style build is:\n\n```bash\ncd website\nnpm run build\n```\n\nThat command runs:\n\n1. theme generation\n2. docs validation\n3. inherited-doc materialization\n4. Hugo site build\n5. homepage CTA validation\n\nFor local development, use:\n\n```bash\n./scripts/start-website\n```\n\nOr run the website dev workflow directly:\n\n```bash\ncd website\nnpm run dev\n```\n\nThat dev workflow also keeps search indexing and WebP generation in sync while you iterate. Its transient output is written to `website/public-dev/`, so production-style builds can safely continue to use `website/public/` without disrupting the running preview.\n", "2.0": "+++\ntitle = \"Website and Docs Architecture Overview\"\n+++\n\n## What Lives In `website/`\n\nThe public site lives under `website/`. The important areas are:\n\n```text\nwebsite/\n  content/\n    docs/\n  data/\n    docs-nav/\n    docs-versions.toml\n  scripts/\n  themes/sambee/\n  assets/\n  static/\n```\n\nIn practice:\n\n- `content/` holds the authored website pages and docs pages.\n- `content/docs/` holds the published versioned docs books.\n- `data/docs-versions.toml` declares the canonical docs version order and the current version.\n- `data/docs-nav/\u003cversion\u003e.toml` declares book, section, and page ordering for one version.\n- `scripts/` holds build helpers, docs validation, docs materialization, and docs editor automation.\n- `themes/sambee/` holds the Hugo layouts, partials, CSS, and JS for the public site.\n- `assets/` and `static/` hold source media, generated media, and static files.\n\n## How Docs Routing Works\n\nDocs content is versioned in the content tree:\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe current docs version also publishes stable unversioned routes:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nArchived or explicit versioned routes remain available at:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/...`\n\nThe routing rules, inheritance markers, and stable-current behavior are covered in more detail in [Docs Content Model, Navigation, and Inheritance](../docs-content-model-navigation-and-inheritance/).\n\n## Build and Preview Pipeline\n\nThe website build is more than a plain Hugo render.\n\nThe normal production-style build is:\n\n```bash\ncd website\nnpm run build\n```\n\nThat command runs:\n\n1. theme generation\n2. docs validation\n3. inherited-doc materialization\n4. Hugo site build\n5. homepage CTA validation\n\nFor local development, use:\n\n```bash\n./scripts/start-website\n```\n\nOr run the website dev workflow directly:\n\n```bash\ncd website\nnpm run dev\n```\n\nThat dev workflow also keeps search indexing and WebP generation in sync while you iterate. Its transient output is written to `website/public-dev/`, so production-style builds can safely continue to use `website/public/` without disrupting the running preview.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:website-dev-guide/docs-platform/docs-content-model-navigation-and-inheritance", "parent_id": "section:website-dev-guide/docs-platform", "depth": 2, "kind": "page", "label": "docs-content-model-navigation-and-inheritance", "title": "Docs Content Model Navigation And Inheritance", "path": "website-dev-guide/docs-platform/docs-content-model-navigation-and-inheritance", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Docs Content Model, Navigation, and Inheritance\"\n+++\n\nSambee's docs system is intentionally strict. That is a feature, not incidental complexity.\n\nThe strict rules keep URLs, page identity, navigation, inheritance, and render-time resolution aligned.\n\n## Core Model\n\nDocs identity is path-derived under `website/content/docs/`.\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe path itself defines the docs identity:\n\n- version slug: `content/docs/\u003cversion\u003e/`\n- book slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- section slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- page slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Public URL Contract\n\nFor the docs version marked as current, the canonical public routes are stable and unversioned:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nExplicit versioned routes are available for each existing version:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Filesystem Contract\n\nThe docs system allows real authored content and inheritance markers. The allowed combinations are strict.\n\n### Page Folders\n\nA page folder under `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/` must contain exactly one of:\n\n- `index.md`: real page content\n- `inherit.md`: empty inheritance marker\n\nDo not keep both files in the same page folder.\n\n### Version Folders\n\nA version folder must contain exactly one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\n### Book and Section Folders\n\nA book folder or section folder may contain zero or one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\nIf neither file exists, the folder is structural only and has no content or public landing route of its own.\n\n## Marker Files Are Markers Only\n\nInheritance markers do not carry content or override metadata.\n\n- `inherit.md` and `_inherit.md` must be empty and have no front matter.\n\nIf a newer version needs different content, replace the marker with real content.\n\n## Navigation Data Contract\n\nNavigation data lives in `website/data/docs-nav/\u003cversion\u003e.toml`.\n\nThese files define ordering only.\n\n- `books` orders books\n- `[[sections.\u003cbook\u003e.items]]` orders sections and gives each section a displayed title\n- `[pages.\u003cbook\u003e.\u003csection\u003e].items` orders pages inside one section\n\nExample:\n\n```toml\nbooks = [\n  \"user-guide\",\n  \"admin-guide\",\n  \"developer-guide\",\n  \"website-dev-guide\",\n]\n\n[[sections.website-dev-guide.items]]\nslug = \"authoring-and-tooling\"\ntitle = \"Authoring and Tooling\"\n\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n]\n```\n\nNavigation data does not define:\n\n- URLs\n- page titles\n- page existence\n- inheritance behavior\n\nThose come from the content tree and the effective-page resolver.\n\n## Version Order and Current Version\n\nVersion metadata lives in `website/data/docs-versions.toml`.\n\nImportant rules:\n\n- versions are listed in ascending release order, oldest to newest\n- that declaration order is canonical\n- inheritance only walks backward through that order\n- the `current` key defines the version that publishes at stable unversioned routes\n\nDo not infer chronology from the version slug string itself. Use the declared order.\n\n### Inheritance Resolution\n\nWhen Hugo renders a docs URL for a version, the system checks the requested version first and then walks backward through earlier versions until it finds real content.\n\nFor article pages, the resolution order is:\n\n1. check `index.md` at the requested path\n   - if present, use it\n   - otherwise, if `inherit.md` exists, move to the previous declared version and check the same path\n   - if neither file exists, validation should fail\n1. if the backward scan ends without finding real content, validation should fail\n\nLanding-page resolution follows the same pattern with `_index.md` and `_inherit.md`.\n\nExample:\n\n```text\ncontent/docs/0.7/website-dev-guide/docs-platform/website-and-docs-architecture-overview/index.md\ncontent/docs/0.8/website-dev-guide/docs-platform/website-and-docs-architecture-overview/inherit.md\n```\n\nIn that case, the `0.8` route remains routable, but the content comes from the `0.7` authored page until `0.8` diverges.\n\n## Safe Change Checklist\n\nWhen changing docs content, navigation, or routing behavior:\n\n- keep the filesystem path aligned with the intended public URL\n- update `docs-nav/\u003cversion\u003e.toml` when section or page ordering changes\n- treat slug changes as URL changes, not cosmetic edits\n- keep marker files empty\n- preserve the expected file combinations for pages, books, and sections\n- run the website build before finishing\n\n## Common Failure Modes\n\n- adding a page without adding the corresponding nav entry\n- changing a slug in content but not in nav data\n- leaving both `index.md` and `inherit.md` in one page folder\n- adding content or front matter to `inherit.md` or `_inherit.md`\n- putting published content into a source-material folder and assuming it is live docs\n- changing template or script behavior without preserving the same docs path contract\n", "0.8": "+++\ntitle = \"Docs Content Model, Navigation, and Inheritance\"\n+++\n\nSambee's docs system is intentionally strict. That is a feature, not incidental complexity.\n\nThe strict rules keep URLs, page identity, navigation, inheritance, and render-time resolution aligned.\n\n## Core Model\n\nDocs identity is path-derived under `website/content/docs/`.\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe path itself defines the docs identity:\n\n- version slug: `content/docs/\u003cversion\u003e/`\n- book slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- section slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- page slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Public URL Contract\n\nFor the docs version marked as current, the canonical public routes are stable and unversioned:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nExplicit versioned routes are available for each existing version:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Filesystem Contract\n\nThe docs system allows real authored content and inheritance markers. The allowed combinations are strict.\n\n### Page Folders\n\nA page folder under `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/` must contain exactly one of:\n\n- `index.md`: real page content\n- `inherit.md`: empty inheritance marker\n\nDo not keep both files in the same page folder.\n\n### Version Folders\n\nA version folder must contain exactly one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\n### Book and Section Folders\n\nA book folder or section folder may contain zero or one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\nIf neither file exists, the folder is structural only and has no content or public landing route of its own.\n\n## Marker Files Are Markers Only\n\nInheritance markers do not carry content or override metadata.\n\n- `inherit.md` and `_inherit.md` must be empty and have no front matter.\n\nIf a newer version needs different content, replace the marker with real content.\n\n## Navigation Data Contract\n\nNavigation data lives in `website/data/docs-nav/\u003cversion\u003e.toml`.\n\nThese files define ordering only.\n\n- `books` orders books\n- `[[sections.\u003cbook\u003e.items]]` orders sections and gives each section a displayed title\n- `[pages.\u003cbook\u003e.\u003csection\u003e].items` orders pages inside one section\n\nExample:\n\n```toml\nbooks = [\n  \"user-guide\",\n  \"admin-guide\",\n  \"developer-guide\",\n  \"website-dev-guide\",\n]\n\n[[sections.website-dev-guide.items]]\nslug = \"authoring-and-tooling\"\ntitle = \"Authoring and Tooling\"\n\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n]\n```\n\nNavigation data does not define:\n\n- URLs\n- page titles\n- page existence\n- inheritance behavior\n\nThose come from the content tree and the effective-page resolver.\n\n## Version Order and Current Version\n\nVersion metadata lives in `website/data/docs-versions.toml`.\n\nImportant rules:\n\n- versions are listed in ascending release order, oldest to newest\n- that declaration order is canonical\n- inheritance only walks backward through that order\n- the `current` key defines the version that publishes at stable unversioned routes\n\nDo not infer chronology from the version slug string itself. Use the declared order.\n\n### Inheritance Resolution\n\nWhen Hugo renders a docs URL for a version, the system checks the requested version first and then walks backward through earlier versions until it finds real content.\n\nFor article pages, the resolution order is:\n\n1. check `index.md` at the requested path\n   - if present, use it\n   - otherwise, if `inherit.md` exists, move to the previous declared version and check the same path\n   - if neither file exists, validation should fail\n1. if the backward scan ends without finding real content, validation should fail\n\nLanding-page resolution follows the same pattern with `_index.md` and `_inherit.md`.\n\nExample:\n\n```text\ncontent/docs/0.7/website-dev-guide/docs-platform/website-and-docs-architecture-overview/index.md\ncontent/docs/0.8/website-dev-guide/docs-platform/website-and-docs-architecture-overview/inherit.md\n```\n\nIn that case, the `0.8` route remains routable, but the content comes from the `0.7` authored page until `0.8` diverges.\n\n## Safe Change Checklist\n\nWhen changing docs content, navigation, or routing behavior:\n\n- keep the filesystem path aligned with the intended public URL\n- update `docs-nav/\u003cversion\u003e.toml` when section or page ordering changes\n- treat slug changes as URL changes, not cosmetic edits\n- keep marker files empty\n- preserve the expected file combinations for pages, books, and sections\n- run the website build before finishing\n\n## Common Failure Modes\n\n- adding a page without adding the corresponding nav entry\n- changing a slug in content but not in nav data\n- leaving both `index.md` and `inherit.md` in one page folder\n- adding content or front matter to `inherit.md` or `_inherit.md`\n- putting published content into a source-material folder and assuming it is live docs\n- changing template or script behavior without preserving the same docs path contract\n", "0.9": "+++\ntitle = \"Docs Content Model, Navigation, and Inheritance\"\n+++\n\nSambee's docs system is intentionally strict. That is a feature, not incidental complexity.\n\nThe strict rules keep URLs, page identity, navigation, inheritance, and render-time resolution aligned.\n\n## Core Model\n\nDocs identity is path-derived under `website/content/docs/`.\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe path itself defines the docs identity:\n\n- version slug: `content/docs/\u003cversion\u003e/`\n- book slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- section slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- page slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Public URL Contract\n\nFor the docs version marked as current, the canonical public routes are stable and unversioned:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nExplicit versioned routes are available for each existing version:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Filesystem Contract\n\nThe docs system allows real authored content and inheritance markers. The allowed combinations are strict.\n\n### Page Folders\n\nA page folder under `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/` must contain exactly one of:\n\n- `index.md`: real page content\n- `inherit.md`: empty inheritance marker\n\nDo not keep both files in the same page folder.\n\n### Version Folders\n\nA version folder must contain exactly one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\n### Book and Section Folders\n\nA book folder or section folder may contain zero or one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\nIf neither file exists, the folder is structural only and has no content or public landing route of its own.\n\n## Marker Files Are Markers Only\n\nInheritance markers do not carry content or override metadata.\n\n- `inherit.md` and `_inherit.md` must be empty and have no front matter.\n\nIf a newer version needs different content, replace the marker with real content.\n\n## Navigation Data Contract\n\nNavigation data lives in `website/data/docs-nav/\u003cversion\u003e.toml`.\n\nThese files define ordering only.\n\n- `books` orders books\n- `[[sections.\u003cbook\u003e.items]]` orders sections and gives each section a displayed title\n- `[pages.\u003cbook\u003e.\u003csection\u003e].items` orders pages inside one section\n\nExample:\n\n```toml\nbooks = [\n  \"user-guide\",\n  \"admin-guide\",\n  \"developer-guide\",\n  \"website-dev-guide\",\n]\n\n[[sections.website-dev-guide.items]]\nslug = \"authoring-and-tooling\"\ntitle = \"Authoring and Tooling\"\n\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n]\n```\n\nNavigation data does not define:\n\n- URLs\n- page titles\n- page existence\n- inheritance behavior\n\nThose come from the content tree and the effective-page resolver.\n\n## Version Order and Current Version\n\nVersion metadata lives in `website/data/docs-versions.toml`.\n\nImportant rules:\n\n- versions are listed in ascending release order, oldest to newest\n- that declaration order is canonical\n- inheritance only walks backward through that order\n- the `current` key defines the version that publishes at stable unversioned routes\n\nDo not infer chronology from the version slug string itself. Use the declared order.\n\n### Inheritance Resolution\n\nWhen Hugo renders a docs URL for a version, the system checks the requested version first and then walks backward through earlier versions until it finds real content.\n\nFor article pages, the resolution order is:\n\n1. check `index.md` at the requested path\n   - if present, use it\n   - otherwise, if `inherit.md` exists, move to the previous declared version and check the same path\n   - if neither file exists, validation should fail\n1. if the backward scan ends without finding real content, validation should fail\n\nLanding-page resolution follows the same pattern with `_index.md` and `_inherit.md`.\n\nExample:\n\n```text\ncontent/docs/0.7/website-dev-guide/docs-platform/website-and-docs-architecture-overview/index.md\ncontent/docs/0.8/website-dev-guide/docs-platform/website-and-docs-architecture-overview/inherit.md\n```\n\nIn that case, the `0.8` route remains routable, but the content comes from the `0.7` authored page until `0.8` diverges.\n\n## Safe Change Checklist\n\nWhen changing docs content, navigation, or routing behavior:\n\n- keep the filesystem path aligned with the intended public URL\n- update `docs-nav/\u003cversion\u003e.toml` when section or page ordering changes\n- treat slug changes as URL changes, not cosmetic edits\n- keep marker files empty\n- preserve the expected file combinations for pages, books, and sections\n- run the website build before finishing\n\n## Common Failure Modes\n\n- adding a page without adding the corresponding nav entry\n- changing a slug in content but not in nav data\n- leaving both `index.md` and `inherit.md` in one page folder\n- adding content or front matter to `inherit.md` or `_inherit.md`\n- putting published content into a source-material folder and assuming it is live docs\n- changing template or script behavior without preserving the same docs path contract\n", "1.0": "+++\ntitle = \"Docs Content Model, Navigation, and Inheritance\"\n+++\n\nSambee's docs system is intentionally strict. That is a feature, not incidental complexity.\n\nThe strict rules keep URLs, page identity, navigation, inheritance, and render-time resolution aligned.\n\n## Core Model\n\nDocs identity is path-derived under `website/content/docs/`.\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe path itself defines the docs identity:\n\n- version slug: `content/docs/\u003cversion\u003e/`\n- book slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- section slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- page slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Public URL Contract\n\nFor the docs version marked as current, the canonical public routes are stable and unversioned:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nExplicit versioned routes are available for each existing version:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Filesystem Contract\n\nThe docs system allows real authored content and inheritance markers. The allowed combinations are strict.\n\n### Page Folders\n\nA page folder under `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/` must contain exactly one of:\n\n- `index.md`: real page content\n- `inherit.md`: empty inheritance marker\n\nDo not keep both files in the same page folder.\n\n### Version Folders\n\nA version folder must contain exactly one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\n### Book and Section Folders\n\nA book folder or section folder may contain zero or one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\nIf neither file exists, the folder is structural only and has no content or public landing route of its own.\n\n## Marker Files Are Markers Only\n\nInheritance markers do not carry content or override metadata.\n\n- `inherit.md` and `_inherit.md` must be empty and have no front matter.\n\nIf a newer version needs different content, replace the marker with real content.\n\n## Navigation Data Contract\n\nNavigation data lives in `website/data/docs-nav/\u003cversion\u003e.toml`.\n\nThese files define ordering only.\n\n- `books` orders books\n- `[[sections.\u003cbook\u003e.items]]` orders sections and gives each section a displayed title\n- `[pages.\u003cbook\u003e.\u003csection\u003e].items` orders pages inside one section\n\nExample:\n\n```toml\nbooks = [\n  \"user-guide\",\n  \"admin-guide\",\n  \"developer-guide\",\n  \"website-dev-guide\",\n]\n\n[[sections.website-dev-guide.items]]\nslug = \"authoring-and-tooling\"\ntitle = \"Authoring and Tooling\"\n\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n]\n```\n\nNavigation data does not define:\n\n- URLs\n- page titles\n- page existence\n- inheritance behavior\n\nThose come from the content tree and the effective-page resolver.\n\n## Version Order and Current Version\n\nVersion metadata lives in `website/data/docs-versions.toml`.\n\nImportant rules:\n\n- versions are listed in ascending release order, oldest to newest\n- that declaration order is canonical\n- inheritance only walks backward through that order\n- the `current` key defines the version that publishes at stable unversioned routes\n\nDo not infer chronology from the version slug string itself. Use the declared order.\n\n### Inheritance Resolution\n\nWhen Hugo renders a docs URL for a version, the system checks the requested version first and then walks backward through earlier versions until it finds real content.\n\nFor article pages, the resolution order is:\n\n1. check `index.md` at the requested path\n   - if present, use it\n   - otherwise, if `inherit.md` exists, move to the previous declared version and check the same path\n   - if neither file exists, validation should fail\n1. if the backward scan ends without finding real content, validation should fail\n\nLanding-page resolution follows the same pattern with `_index.md` and `_inherit.md`.\n\nExample:\n\n```text\ncontent/docs/0.7/website-dev-guide/docs-platform/website-and-docs-architecture-overview/index.md\ncontent/docs/0.8/website-dev-guide/docs-platform/website-and-docs-architecture-overview/inherit.md\n```\n\nIn that case, the `0.8` route remains routable, but the content comes from the `0.7` authored page until `0.8` diverges.\n\n## Safe Change Checklist\n\nWhen changing docs content, navigation, or routing behavior:\n\n- keep the filesystem path aligned with the intended public URL\n- update `docs-nav/\u003cversion\u003e.toml` when section or page ordering changes\n- treat slug changes as URL changes, not cosmetic edits\n- keep marker files empty\n- preserve the expected file combinations for pages, books, and sections\n- run the website build before finishing\n\n## Common Failure Modes\n\n- adding a page without adding the corresponding nav entry\n- changing a slug in content but not in nav data\n- leaving both `index.md` and `inherit.md` in one page folder\n- adding content or front matter to `inherit.md` or `_inherit.md`\n- putting published content into a source-material folder and assuming it is live docs\n- changing template or script behavior without preserving the same docs path contract\n", "2.0": "+++\ntitle = \"Docs Content Model, Navigation, and Inheritance\"\n+++\n\nSambee's docs system is intentionally strict. That is a feature, not incidental complexity.\n\nThe strict rules keep URLs, page identity, navigation, inheritance, and render-time resolution aligned.\n\n## Core Model\n\nDocs identity is path-derived under `website/content/docs/`.\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe path itself defines the docs identity:\n\n- version slug: `content/docs/\u003cversion\u003e/`\n- book slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- section slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- page slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Public URL Contract\n\nFor the docs version marked as current, the canonical public routes are stable and unversioned:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nExplicit versioned routes are available for each existing version:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Filesystem Contract\n\nThe docs system allows real authored content and inheritance markers. The allowed combinations are strict.\n\n### Page Folders\n\nA page folder under `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/` must contain exactly one of:\n\n- `index.md`: real page content\n- `inherit.md`: empty inheritance marker\n\nDo not keep both files in the same page folder.\n\n### Version Folders\n\nA version folder must contain exactly one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\n### Book and Section Folders\n\nA book folder or section folder may contain zero or one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\nIf neither file exists, the folder is structural only and has no content or public landing route of its own.\n\n## Marker Files Are Markers Only\n\nInheritance markers do not carry content or override metadata.\n\n- `inherit.md` and `_inherit.md` must be empty and have no front matter.\n\nIf a newer version needs different content, replace the marker with real content.\n\n## Navigation Data Contract\n\nNavigation data lives in `website/data/docs-nav/\u003cversion\u003e.toml`.\n\nThese files define ordering only.\n\n- `books` orders books\n- `[[sections.\u003cbook\u003e.items]]` orders sections and gives each section a displayed title\n- `[pages.\u003cbook\u003e.\u003csection\u003e].items` orders pages inside one section\n\nExample:\n\n```toml\nbooks = [\n  \"user-guide\",\n  \"admin-guide\",\n  \"developer-guide\",\n  \"website-dev-guide\",\n]\n\n[[sections.website-dev-guide.items]]\nslug = \"authoring-and-tooling\"\ntitle = \"Authoring and Tooling\"\n\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n]\n```\n\nNavigation data does not define:\n\n- URLs\n- page titles\n- page existence\n- inheritance behavior\n\nThose come from the content tree and the effective-page resolver.\n\n## Version Order and Current Version\n\nVersion metadata lives in `website/data/docs-versions.toml`.\n\nImportant rules:\n\n- versions are listed in ascending release order, oldest to newest\n- that declaration order is canonical\n- inheritance only walks backward through that order\n- the `current` key defines the version that publishes at stable unversioned routes\n\nDo not infer chronology from the version slug string itself. Use the declared order.\n\n### Inheritance Resolution\n\nWhen Hugo renders a docs URL for a version, the system checks the requested version first and then walks backward through earlier versions until it finds real content.\n\nFor article pages, the resolution order is:\n\n1. check `index.md` at the requested path\n   - if present, use it\n   - otherwise, if `inherit.md` exists, move to the previous declared version and check the same path\n   - if neither file exists, validation should fail\n1. if the backward scan ends without finding real content, validation should fail\n\nLanding-page resolution follows the same pattern with `_index.md` and `_inherit.md`.\n\nExample:\n\n```text\ncontent/docs/0.7/website-dev-guide/docs-platform/website-and-docs-architecture-overview/index.md\ncontent/docs/0.8/website-dev-guide/docs-platform/website-and-docs-architecture-overview/inherit.md\n```\n\nIn that case, the `0.8` route remains routable, but the content comes from the `0.7` authored page until `0.8` diverges.\n\n## Safe Change Checklist\n\nWhen changing docs content, navigation, or routing behavior:\n\n- keep the filesystem path aligned with the intended public URL\n- update `docs-nav/\u003cversion\u003e.toml` when section or page ordering changes\n- treat slug changes as URL changes, not cosmetic edits\n- keep marker files empty\n- preserve the expected file combinations for pages, books, and sections\n- run the website build before finishing\n\n## Common Failure Modes\n\n- adding a page without adding the corresponding nav entry\n- changing a slug in content but not in nav data\n- leaving both `index.md` and `inherit.md` in one page folder\n- adding content or front matter to `inherit.md` or `_inherit.md`\n- putting published content into a source-material folder and assuming it is live docs\n- changing template or script behavior without preserving the same docs path contract\n"}, "page_contents": {"0.7": "+++\ntitle = \"Docs Content Model, Navigation, and Inheritance\"\n+++\n\nSambee's docs system is intentionally strict. That is a feature, not incidental complexity.\n\nThe strict rules keep URLs, page identity, navigation, inheritance, and render-time resolution aligned.\n\n## Core Model\n\nDocs identity is path-derived under `website/content/docs/`.\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe path itself defines the docs identity:\n\n- version slug: `content/docs/\u003cversion\u003e/`\n- book slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- section slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- page slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Public URL Contract\n\nFor the docs version marked as current, the canonical public routes are stable and unversioned:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nExplicit versioned routes are available for each existing version:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Filesystem Contract\n\nThe docs system allows real authored content and inheritance markers. The allowed combinations are strict.\n\n### Page Folders\n\nA page folder under `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/` must contain exactly one of:\n\n- `index.md`: real page content\n- `inherit.md`: empty inheritance marker\n\nDo not keep both files in the same page folder.\n\n### Version Folders\n\nA version folder must contain exactly one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\n### Book and Section Folders\n\nA book folder or section folder may contain zero or one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\nIf neither file exists, the folder is structural only and has no content or public landing route of its own.\n\n## Marker Files Are Markers Only\n\nInheritance markers do not carry content or override metadata.\n\n- `inherit.md` and `_inherit.md` must be empty and have no front matter.\n\nIf a newer version needs different content, replace the marker with real content.\n\n## Navigation Data Contract\n\nNavigation data lives in `website/data/docs-nav/\u003cversion\u003e.toml`.\n\nThese files define ordering only.\n\n- `books` orders books\n- `[[sections.\u003cbook\u003e.items]]` orders sections and gives each section a displayed title\n- `[pages.\u003cbook\u003e.\u003csection\u003e].items` orders pages inside one section\n\nExample:\n\n```toml\nbooks = [\n  \"user-guide\",\n  \"admin-guide\",\n  \"developer-guide\",\n  \"website-dev-guide\",\n]\n\n[[sections.website-dev-guide.items]]\nslug = \"authoring-and-tooling\"\ntitle = \"Authoring and Tooling\"\n\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n]\n```\n\nNavigation data does not define:\n\n- URLs\n- page titles\n- page existence\n- inheritance behavior\n\nThose come from the content tree and the effective-page resolver.\n\n## Version Order and Current Version\n\nVersion metadata lives in `website/data/docs-versions.toml`.\n\nImportant rules:\n\n- versions are listed in ascending release order, oldest to newest\n- that declaration order is canonical\n- inheritance only walks backward through that order\n- the `current` key defines the version that publishes at stable unversioned routes\n\nDo not infer chronology from the version slug string itself. Use the declared order.\n\n### Inheritance Resolution\n\nWhen Hugo renders a docs URL for a version, the system checks the requested version first and then walks backward through earlier versions until it finds real content.\n\nFor article pages, the resolution order is:\n\n1. check `index.md` at the requested path\n   - if present, use it\n   - otherwise, if `inherit.md` exists, move to the previous declared version and check the same path\n   - if neither file exists, validation should fail\n1. if the backward scan ends without finding real content, validation should fail\n\nLanding-page resolution follows the same pattern with `_index.md` and `_inherit.md`.\n\nExample:\n\n```text\ncontent/docs/0.7/website-dev-guide/docs-platform/website-and-docs-architecture-overview/index.md\ncontent/docs/0.8/website-dev-guide/docs-platform/website-and-docs-architecture-overview/inherit.md\n```\n\nIn that case, the `0.8` route remains routable, but the content comes from the `0.7` authored page until `0.8` diverges.\n\n## Safe Change Checklist\n\nWhen changing docs content, navigation, or routing behavior:\n\n- keep the filesystem path aligned with the intended public URL\n- update `docs-nav/\u003cversion\u003e.toml` when section or page ordering changes\n- treat slug changes as URL changes, not cosmetic edits\n- keep marker files empty\n- preserve the expected file combinations for pages, books, and sections\n- run the website build before finishing\n\n## Common Failure Modes\n\n- adding a page without adding the corresponding nav entry\n- changing a slug in content but not in nav data\n- leaving both `index.md` and `inherit.md` in one page folder\n- adding content or front matter to `inherit.md` or `_inherit.md`\n- putting published content into a source-material folder and assuming it is live docs\n- changing template or script behavior without preserving the same docs path contract\n", "0.8": "+++\ntitle = \"Docs Content Model, Navigation, and Inheritance\"\n+++\n\nSambee's docs system is intentionally strict. That is a feature, not incidental complexity.\n\nThe strict rules keep URLs, page identity, navigation, inheritance, and render-time resolution aligned.\n\n## Core Model\n\nDocs identity is path-derived under `website/content/docs/`.\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe path itself defines the docs identity:\n\n- version slug: `content/docs/\u003cversion\u003e/`\n- book slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- section slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- page slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Public URL Contract\n\nFor the docs version marked as current, the canonical public routes are stable and unversioned:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nExplicit versioned routes are available for each existing version:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Filesystem Contract\n\nThe docs system allows real authored content and inheritance markers. The allowed combinations are strict.\n\n### Page Folders\n\nA page folder under `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/` must contain exactly one of:\n\n- `index.md`: real page content\n- `inherit.md`: empty inheritance marker\n\nDo not keep both files in the same page folder.\n\n### Version Folders\n\nA version folder must contain exactly one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\n### Book and Section Folders\n\nA book folder or section folder may contain zero or one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\nIf neither file exists, the folder is structural only and has no content or public landing route of its own.\n\n## Marker Files Are Markers Only\n\nInheritance markers do not carry content or override metadata.\n\n- `inherit.md` and `_inherit.md` must be empty and have no front matter.\n\nIf a newer version needs different content, replace the marker with real content.\n\n## Navigation Data Contract\n\nNavigation data lives in `website/data/docs-nav/\u003cversion\u003e.toml`.\n\nThese files define ordering only.\n\n- `books` orders books\n- `[[sections.\u003cbook\u003e.items]]` orders sections and gives each section a displayed title\n- `[pages.\u003cbook\u003e.\u003csection\u003e].items` orders pages inside one section\n\nExample:\n\n```toml\nbooks = [\n  \"user-guide\",\n  \"admin-guide\",\n  \"developer-guide\",\n  \"website-dev-guide\",\n]\n\n[[sections.website-dev-guide.items]]\nslug = \"authoring-and-tooling\"\ntitle = \"Authoring and Tooling\"\n\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n]\n```\n\nNavigation data does not define:\n\n- URLs\n- page titles\n- page existence\n- inheritance behavior\n\nThose come from the content tree and the effective-page resolver.\n\n## Version Order and Current Version\n\nVersion metadata lives in `website/data/docs-versions.toml`.\n\nImportant rules:\n\n- versions are listed in ascending release order, oldest to newest\n- that declaration order is canonical\n- inheritance only walks backward through that order\n- the `current` key defines the version that publishes at stable unversioned routes\n\nDo not infer chronology from the version slug string itself. Use the declared order.\n\n### Inheritance Resolution\n\nWhen Hugo renders a docs URL for a version, the system checks the requested version first and then walks backward through earlier versions until it finds real content.\n\nFor article pages, the resolution order is:\n\n1. check `index.md` at the requested path\n   - if present, use it\n   - otherwise, if `inherit.md` exists, move to the previous declared version and check the same path\n   - if neither file exists, validation should fail\n1. if the backward scan ends without finding real content, validation should fail\n\nLanding-page resolution follows the same pattern with `_index.md` and `_inherit.md`.\n\nExample:\n\n```text\ncontent/docs/0.7/website-dev-guide/docs-platform/website-and-docs-architecture-overview/index.md\ncontent/docs/0.8/website-dev-guide/docs-platform/website-and-docs-architecture-overview/inherit.md\n```\n\nIn that case, the `0.8` route remains routable, but the content comes from the `0.7` authored page until `0.8` diverges.\n\n## Safe Change Checklist\n\nWhen changing docs content, navigation, or routing behavior:\n\n- keep the filesystem path aligned with the intended public URL\n- update `docs-nav/\u003cversion\u003e.toml` when section or page ordering changes\n- treat slug changes as URL changes, not cosmetic edits\n- keep marker files empty\n- preserve the expected file combinations for pages, books, and sections\n- run the website build before finishing\n\n## Common Failure Modes\n\n- adding a page without adding the corresponding nav entry\n- changing a slug in content but not in nav data\n- leaving both `index.md` and `inherit.md` in one page folder\n- adding content or front matter to `inherit.md` or `_inherit.md`\n- putting published content into a source-material folder and assuming it is live docs\n- changing template or script behavior without preserving the same docs path contract\n", "0.9": "+++\ntitle = \"Docs Content Model, Navigation, and Inheritance\"\n+++\n\nSambee's docs system is intentionally strict. That is a feature, not incidental complexity.\n\nThe strict rules keep URLs, page identity, navigation, inheritance, and render-time resolution aligned.\n\n## Core Model\n\nDocs identity is path-derived under `website/content/docs/`.\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe path itself defines the docs identity:\n\n- version slug: `content/docs/\u003cversion\u003e/`\n- book slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- section slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- page slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Public URL Contract\n\nFor the docs version marked as current, the canonical public routes are stable and unversioned:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nExplicit versioned routes are available for each existing version:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Filesystem Contract\n\nThe docs system allows real authored content and inheritance markers. The allowed combinations are strict.\n\n### Page Folders\n\nA page folder under `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/` must contain exactly one of:\n\n- `index.md`: real page content\n- `inherit.md`: empty inheritance marker\n\nDo not keep both files in the same page folder.\n\n### Version Folders\n\nA version folder must contain exactly one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\n### Book and Section Folders\n\nA book folder or section folder may contain zero or one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\nIf neither file exists, the folder is structural only and has no content or public landing route of its own.\n\n## Marker Files Are Markers Only\n\nInheritance markers do not carry content or override metadata.\n\n- `inherit.md` and `_inherit.md` must be empty and have no front matter.\n\nIf a newer version needs different content, replace the marker with real content.\n\n## Navigation Data Contract\n\nNavigation data lives in `website/data/docs-nav/\u003cversion\u003e.toml`.\n\nThese files define ordering only.\n\n- `books` orders books\n- `[[sections.\u003cbook\u003e.items]]` orders sections and gives each section a displayed title\n- `[pages.\u003cbook\u003e.\u003csection\u003e].items` orders pages inside one section\n\nExample:\n\n```toml\nbooks = [\n  \"user-guide\",\n  \"admin-guide\",\n  \"developer-guide\",\n  \"website-dev-guide\",\n]\n\n[[sections.website-dev-guide.items]]\nslug = \"authoring-and-tooling\"\ntitle = \"Authoring and Tooling\"\n\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n]\n```\n\nNavigation data does not define:\n\n- URLs\n- page titles\n- page existence\n- inheritance behavior\n\nThose come from the content tree and the effective-page resolver.\n\n## Version Order and Current Version\n\nVersion metadata lives in `website/data/docs-versions.toml`.\n\nImportant rules:\n\n- versions are listed in ascending release order, oldest to newest\n- that declaration order is canonical\n- inheritance only walks backward through that order\n- the `current` key defines the version that publishes at stable unversioned routes\n\nDo not infer chronology from the version slug string itself. Use the declared order.\n\n### Inheritance Resolution\n\nWhen Hugo renders a docs URL for a version, the system checks the requested version first and then walks backward through earlier versions until it finds real content.\n\nFor article pages, the resolution order is:\n\n1. check `index.md` at the requested path\n   - if present, use it\n   - otherwise, if `inherit.md` exists, move to the previous declared version and check the same path\n   - if neither file exists, validation should fail\n1. if the backward scan ends without finding real content, validation should fail\n\nLanding-page resolution follows the same pattern with `_index.md` and `_inherit.md`.\n\nExample:\n\n```text\ncontent/docs/0.7/website-dev-guide/docs-platform/website-and-docs-architecture-overview/index.md\ncontent/docs/0.8/website-dev-guide/docs-platform/website-and-docs-architecture-overview/inherit.md\n```\n\nIn that case, the `0.8` route remains routable, but the content comes from the `0.7` authored page until `0.8` diverges.\n\n## Safe Change Checklist\n\nWhen changing docs content, navigation, or routing behavior:\n\n- keep the filesystem path aligned with the intended public URL\n- update `docs-nav/\u003cversion\u003e.toml` when section or page ordering changes\n- treat slug changes as URL changes, not cosmetic edits\n- keep marker files empty\n- preserve the expected file combinations for pages, books, and sections\n- run the website build before finishing\n\n## Common Failure Modes\n\n- adding a page without adding the corresponding nav entry\n- changing a slug in content but not in nav data\n- leaving both `index.md` and `inherit.md` in one page folder\n- adding content or front matter to `inherit.md` or `_inherit.md`\n- putting published content into a source-material folder and assuming it is live docs\n- changing template or script behavior without preserving the same docs path contract\n", "1.0": "+++\ntitle = \"Docs Content Model, Navigation, and Inheritance\"\n+++\n\nSambee's docs system is intentionally strict. That is a feature, not incidental complexity.\n\nThe strict rules keep URLs, page identity, navigation, inheritance, and render-time resolution aligned.\n\n## Core Model\n\nDocs identity is path-derived under `website/content/docs/`.\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe path itself defines the docs identity:\n\n- version slug: `content/docs/\u003cversion\u003e/`\n- book slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- section slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- page slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Public URL Contract\n\nFor the docs version marked as current, the canonical public routes are stable and unversioned:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nExplicit versioned routes are available for each existing version:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Filesystem Contract\n\nThe docs system allows real authored content and inheritance markers. The allowed combinations are strict.\n\n### Page Folders\n\nA page folder under `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/` must contain exactly one of:\n\n- `index.md`: real page content\n- `inherit.md`: empty inheritance marker\n\nDo not keep both files in the same page folder.\n\n### Version Folders\n\nA version folder must contain exactly one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\n### Book and Section Folders\n\nA book folder or section folder may contain zero or one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\nIf neither file exists, the folder is structural only and has no content or public landing route of its own.\n\n## Marker Files Are Markers Only\n\nInheritance markers do not carry content or override metadata.\n\n- `inherit.md` and `_inherit.md` must be empty and have no front matter.\n\nIf a newer version needs different content, replace the marker with real content.\n\n## Navigation Data Contract\n\nNavigation data lives in `website/data/docs-nav/\u003cversion\u003e.toml`.\n\nThese files define ordering only.\n\n- `books` orders books\n- `[[sections.\u003cbook\u003e.items]]` orders sections and gives each section a displayed title\n- `[pages.\u003cbook\u003e.\u003csection\u003e].items` orders pages inside one section\n\nExample:\n\n```toml\nbooks = [\n  \"user-guide\",\n  \"admin-guide\",\n  \"developer-guide\",\n  \"website-dev-guide\",\n]\n\n[[sections.website-dev-guide.items]]\nslug = \"authoring-and-tooling\"\ntitle = \"Authoring and Tooling\"\n\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n]\n```\n\nNavigation data does not define:\n\n- URLs\n- page titles\n- page existence\n- inheritance behavior\n\nThose come from the content tree and the effective-page resolver.\n\n## Version Order and Current Version\n\nVersion metadata lives in `website/data/docs-versions.toml`.\n\nImportant rules:\n\n- versions are listed in ascending release order, oldest to newest\n- that declaration order is canonical\n- inheritance only walks backward through that order\n- the `current` key defines the version that publishes at stable unversioned routes\n\nDo not infer chronology from the version slug string itself. Use the declared order.\n\n### Inheritance Resolution\n\nWhen Hugo renders a docs URL for a version, the system checks the requested version first and then walks backward through earlier versions until it finds real content.\n\nFor article pages, the resolution order is:\n\n1. check `index.md` at the requested path\n   - if present, use it\n   - otherwise, if `inherit.md` exists, move to the previous declared version and check the same path\n   - if neither file exists, validation should fail\n1. if the backward scan ends without finding real content, validation should fail\n\nLanding-page resolution follows the same pattern with `_index.md` and `_inherit.md`.\n\nExample:\n\n```text\ncontent/docs/0.7/website-dev-guide/docs-platform/website-and-docs-architecture-overview/index.md\ncontent/docs/0.8/website-dev-guide/docs-platform/website-and-docs-architecture-overview/inherit.md\n```\n\nIn that case, the `0.8` route remains routable, but the content comes from the `0.7` authored page until `0.8` diverges.\n\n## Safe Change Checklist\n\nWhen changing docs content, navigation, or routing behavior:\n\n- keep the filesystem path aligned with the intended public URL\n- update `docs-nav/\u003cversion\u003e.toml` when section or page ordering changes\n- treat slug changes as URL changes, not cosmetic edits\n- keep marker files empty\n- preserve the expected file combinations for pages, books, and sections\n- run the website build before finishing\n\n## Common Failure Modes\n\n- adding a page without adding the corresponding nav entry\n- changing a slug in content but not in nav data\n- leaving both `index.md` and `inherit.md` in one page folder\n- adding content or front matter to `inherit.md` or `_inherit.md`\n- putting published content into a source-material folder and assuming it is live docs\n- changing template or script behavior without preserving the same docs path contract\n", "2.0": "+++\ntitle = \"Docs Content Model, Navigation, and Inheritance\"\n+++\n\nSambee's docs system is intentionally strict. That is a feature, not incidental complexity.\n\nThe strict rules keep URLs, page identity, navigation, inheritance, and render-time resolution aligned.\n\n## Core Model\n\nDocs identity is path-derived under `website/content/docs/`.\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe path itself defines the docs identity:\n\n- version slug: `content/docs/\u003cversion\u003e/`\n- book slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- section slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- page slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Public URL Contract\n\nFor the docs version marked as current, the canonical public routes are stable and unversioned:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nExplicit versioned routes are available for each existing version:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Filesystem Contract\n\nThe docs system allows real authored content and inheritance markers. The allowed combinations are strict.\n\n### Page Folders\n\nA page folder under `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/` must contain exactly one of:\n\n- `index.md`: real page content\n- `inherit.md`: empty inheritance marker\n\nDo not keep both files in the same page folder.\n\n### Version Folders\n\nA version folder must contain exactly one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\n### Book and Section Folders\n\nA book folder or section folder may contain zero or one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\nIf neither file exists, the folder is structural only and has no content or public landing route of its own.\n\n## Marker Files Are Markers Only\n\nInheritance markers do not carry content or override metadata.\n\n- `inherit.md` and `_inherit.md` must be empty and have no front matter.\n\nIf a newer version needs different content, replace the marker with real content.\n\n## Navigation Data Contract\n\nNavigation data lives in `website/data/docs-nav/\u003cversion\u003e.toml`.\n\nThese files define ordering only.\n\n- `books` orders books\n- `[[sections.\u003cbook\u003e.items]]` orders sections and gives each section a displayed title\n- `[pages.\u003cbook\u003e.\u003csection\u003e].items` orders pages inside one section\n\nExample:\n\n```toml\nbooks = [\n  \"user-guide\",\n  \"admin-guide\",\n  \"developer-guide\",\n  \"website-dev-guide\",\n]\n\n[[sections.website-dev-guide.items]]\nslug = \"authoring-and-tooling\"\ntitle = \"Authoring and Tooling\"\n\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n]\n```\n\nNavigation data does not define:\n\n- URLs\n- page titles\n- page existence\n- inheritance behavior\n\nThose come from the content tree and the effective-page resolver.\n\n## Version Order and Current Version\n\nVersion metadata lives in `website/data/docs-versions.toml`.\n\nImportant rules:\n\n- versions are listed in ascending release order, oldest to newest\n- that declaration order is canonical\n- inheritance only walks backward through that order\n- the `current` key defines the version that publishes at stable unversioned routes\n\nDo not infer chronology from the version slug string itself. Use the declared order.\n\n### Inheritance Resolution\n\nWhen Hugo renders a docs URL for a version, the system checks the requested version first and then walks backward through earlier versions until it finds real content.\n\nFor article pages, the resolution order is:\n\n1. check `index.md` at the requested path\n   - if present, use it\n   - otherwise, if `inherit.md` exists, move to the previous declared version and check the same path\n   - if neither file exists, validation should fail\n1. if the backward scan ends without finding real content, validation should fail\n\nLanding-page resolution follows the same pattern with `_index.md` and `_inherit.md`.\n\nExample:\n\n```text\ncontent/docs/0.7/website-dev-guide/docs-platform/website-and-docs-architecture-overview/index.md\ncontent/docs/0.8/website-dev-guide/docs-platform/website-and-docs-architecture-overview/inherit.md\n```\n\nIn that case, the `0.8` route remains routable, but the content comes from the `0.7` authored page until `0.8` diverges.\n\n## Safe Change Checklist\n\nWhen changing docs content, navigation, or routing behavior:\n\n- keep the filesystem path aligned with the intended public URL\n- update `docs-nav/\u003cversion\u003e.toml` when section or page ordering changes\n- treat slug changes as URL changes, not cosmetic edits\n- keep marker files empty\n- preserve the expected file combinations for pages, books, and sections\n- run the website build before finishing\n\n## Common Failure Modes\n\n- adding a page without adding the corresponding nav entry\n- changing a slug in content but not in nav data\n- leaving both `index.md` and `inherit.md` in one page folder\n- adding content or front matter to `inherit.md` or `_inherit.md`\n- putting published content into a source-material folder and assuming it is live docs\n- changing template or script behavior without preserving the same docs path contract\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:website-dev-guide/docs-platform/docs-runtime-and-route-resolution", "parent_id": "section:website-dev-guide/docs-platform", "depth": 2, "kind": "page", "label": "docs-runtime-and-route-resolution", "title": "Docs Runtime And Route Resolution", "path": "website-dev-guide/docs-platform/docs-runtime-and-route-resolution", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Docs Runtime and Route Resolution\"\n+++\n\nThis page covers the implementation-facing side of docs routing.\n\nUse it when you need to answer questions such as:\n\n- which files own docs route resolution\n- how stable current routes differ from explicit versioned routes\n- how inherited pages become routable\n- how version switching and docs search stay version-aware\n\n## Runtime Map\n\nEditors usually work in content and nav files. Web developers also need to know which files own version metadata, build-time validation, and runtime route resolution.\n\n### Content and Navigation Sources\n\nThese files define what the docs tree is supposed to be:\n\n- `website/data/docs-versions.toml`: canonical docs version metadata\n- `website/data/docs-nav/\u003cversion\u003e.toml`: ordered books, sections, and pages\n\nIf the docs UI order looks wrong, or a page exists on disk but not in navigation, these are the first files to check.\n\n### Build and Tooling Scripts\n\nThese scripts keep the docs tree valid and routable:\n\n- `website/scripts/validate-docs-content.py`: validates docs structure, markers, and nav integrity\n- `website/scripts/materialize-inherited-docs.py`: generates transient routable anchors for inherited docs and stable current routes\n- `website/scripts/docs-editor.py`: CLI for creating, deleting, and renaming docs versions, books, sections, and pages safely\n\nIn practice:\n\n- use the validator when you need to confirm content-tree and nav consistency\n- use materialization when testing inheritance or stable-current route behavior\n- use the docs editor for structural changes instead of hand-editing multiple files\n\n### Runtime Template Layer\n\nThese files turn the requested docs URL into the page the user actually sees:\n\n- `website/themes/sambee/layouts/partials/docs/context.html`: derives docs path context from the requested route\n- `website/themes/sambee/layouts/partials/docs/page-path.html`: builds docs content paths with stable-current routing support\n- `website/themes/sambee/layouts/partials/docs/page-url.html`: resolves navigable docs URLs\n- `website/themes/sambee/layouts/partials/docs/source-page.html`: resolves the explicit versioned source page behind stable current routes\n- `website/themes/sambee/layouts/partials/docs/effective-page.html`: resolves the authored page that supplies body content and metadata\n- `website/themes/sambee/layouts/partials/docs/render-data.html`: prepares shared docs render data, including redirect and indexing state\n- `website/themes/sambee/layouts/partials/docs/article-shell.html`: renders the shared docs article shell\n- `website/themes/sambee/layouts/partials/docs/redirect-target.html`: resolves docs entry redirects\n- `website/themes/sambee/layouts/partials/docs/nav-tree.html`: resolves navigation targets and displayed titles\n- `website/themes/sambee/layouts/partials/docs/version-target-url.html`: resolves cross-version switch targets\n- `website/themes/sambee/layouts/partials/search-modal.html`: applies docs-version-aware search behavior\n- `website/themes/sambee/layouts/docs/list.html` and `website/themes/sambee/layouts/docs/single.html`: route docs list and page rendering through the shared shell\n\n### Theme Assets\n\nThese assets shape the visible docs experience once the route and content have been resolved:\n\n- `website/themes/sambee/assets/css/`: shared theme CSS, including docs UI and typography\n\n## Requested Route Versus Effective Page\n\nThe docs runtime keeps requested-path context separate from effective-content resolution.\n\n### Requested Route Context\n\n`website/themes/sambee/layouts/partials/docs/context.html` derives path context from the requested route and returns values including:\n\n- `isDocs`\n- `version`\n- `book`\n- `section`\n- `page`\n- `kind`\n- `currentVersion`\n- `isExplicitVersion`\n- `isCurrentRoute`\n- `isCurrentVersion`\n- convenience booleans: `isDocsRoot`, `isVersion`, `isBook`, `isSection`, and `isPage`\n\nInterpretation rules that matter when changing templates:\n\n- stable current routes such as `/docs/website-dev-guide/...` still resolve to the current version even though the version slug is omitted\n- explicit current-version routes such as `/docs/0.7/...` are compatibility routes and should redirect to stable current routes\n- archived explicit version routes stay routable and render as full docs pages\n\n### Effective Content Resolution\n\n`website/themes/sambee/layouts/partials/docs/effective-page.html` then resolves the authored content source and returns values including:\n\n- `page`: the authored page that should supply title, description, TOC, and body content\n- `requestedPage`: the Hugo page for the requested route\n- `requestedVersion`: the version derived from the route\n- `resolvedVersion`: the version that supplied the effective content\n- `isInherited`: whether the route resolved through inheritance\n\nTemplates should render article content and metadata from `page`, while navigation state, breadcrumbs, and version-switcher state stay tied to the requested route context.\n\n## Why Materialization Exists\n\nHugo needs a concrete page object at the requested path. Raw marker files alone are not enough.\n\nThe build therefore materializes transient route anchors under `.generated/content/docs` so Hugo can route inherited pages and stable current routes without publishing broken `/inherit/` or `/_inherit/` URLs.\n\nFrom Hugo's perspective, `inherit.md` and `_inherit.md` are ordinary content files. If the site consumed them directly, Hugo would try to publish the wrong public URLs.\n\nExample:\n\n- `content/docs/1.1/end-user/getting-started/install/inherit.md` would naturally publish at `/docs/1.1/end-user/getting-started/install/inherit/`\n- `content/docs/1.1/_inherit.md` would naturally publish at `/docs/1.1/_inherit/`\n\nThose are invalid for this docs model. The canonical public URLs must stay attached to the folder path itself:\n\n- `/docs/1.1/end-user/getting-started/install/`\n- `/docs/1.1/`\n\nThat creates a routing gap:\n\n- raw marker files must not become public pages\n- Hugo still needs a real page or section node at the requested folder path so templates can run and the resolver can supply inherited content\n\nThe moving pieces are:\n\n- `website/hugo.toml` ignores raw marker files as direct public pages\n- `website/scripts/materialize-inherited-docs.py` generates transient anchors at the canonical folder paths\n- `website/config/_default/module.toml` mounts `.generated/content` into Hugo's content tree\n- `website/themes/sambee/layouts/partials/docs/effective-page.html` resolves the real authored page that should supply the body, title, description, and TOC\n\nDuring the build, `materialize-inherited-docs.py` does this work:\n\n1. deletes stale generated docs anchors under `website/.generated/content/docs/`\n2. scans `website/content/docs/` for `inherit.md` and `_inherit.md`\n3. generates transient `index.md` or `_index.md` anchors at the matching canonical folder paths under `website/.generated/content/docs/`\n4. generates transient anchors for the declared current version at stable routes under `website/.generated/content/docs/\u003cbook\u003e/...`\n5. marks inherited-route anchors with `inherit = true`\n6. marks stable current-route anchors with `current_route = true` and `source_docs_path = \"/docs/\u003ccurrent\u003e/...\"`\n\nOperational notes:\n\n- `website/.generated/` is build output and is ignored by Git\n- Hugo mounts `.generated/content` into the site content tree during the build\n- Hugo is configured to ignore raw `inherit.md` and `_inherit.md` files\n\nWithout this script, the project would be stuck with two bad options:\n\n- keep raw marker files visible to Hugo and accept broken `/inherit/` and `/_inherit/` URLs\n- ignore marker files and lose the routable page nodes needed to render inherited docs at canonical folder URLs\n\n## Version Switcher Fallback Order\n\nWhen a reader switches from one docs version to another, the target lookup order is:\n\n1. the same page path\n2. the same section landing path\n3. the same book landing path\n4. the target version landing path\n\n## Search Behavior\n\nDocs search is intentionally version-aware.\n\n- Pagefind indexes stable current docs URLs, not explicit current-version compatibility routes\n- current docs search results therefore keep stable unversioned URLs\n- explicit versioned docs pages are excluded from the current-version search index\n- on non-docs pages, the UI defaults docs search filters to the `current` version from `website/data/docs-versions.toml`\n- versions with `searchable = false` are excluded from docs search indexing\n\n## Commands for Runtime Changes\n\nThe most relevant commands when you are changing docs runtime behavior are:\n\n- `npm run docs:validate`: validate docs content, nav data, markers, and inheritance rules\n- The validator checks for:\n\t- both `index.md` and `inherit.md` in the same page folder\n\t- both `_index.md` and `_inherit.md` in the same version, book, or section folder\n\t- missing required page markers in page folders\n\t- missing required `_index.md` or `_inherit.md` in version or book folders\n\t- invalid non-empty inheritance marker files\n\t- inheritance chains that never resolve to real content\n\t- nav entries that point to missing version, book, section, or page paths\n\t- duplicate nav slugs in books, sections, or pages\n\t- legacy identity metadata such as `doc_id` and `product_version`\n\t- disallowed docs front matter such as `aliases`\n- `npm run docs:materialize-inherited`: regenerate transient inherited-route and stable current-route anchors\n- `npm run build`: generate theme assets, validate docs, materialize docs route anchors, and build the site\n- `npm run build:search`: run the full build and then generate the Pagefind search index\n", "0.8": "+++\ntitle = \"Docs Runtime and Route Resolution\"\n+++\n\nThis page covers the implementation-facing side of docs routing.\n\nUse it when you need to answer questions such as:\n\n- which files own docs route resolution\n- how stable current routes differ from explicit versioned routes\n- how inherited pages become routable\n- how version switching and docs search stay version-aware\n\n## Runtime Map\n\nEditors usually work in content and nav files. Web developers also need to know which files own version metadata, build-time validation, and runtime route resolution.\n\n### Content and Navigation Sources\n\nThese files define what the docs tree is supposed to be:\n\n- `website/data/docs-versions.toml`: canonical docs version metadata\n- `website/data/docs-nav/\u003cversion\u003e.toml`: ordered books, sections, and pages\n\nIf the docs UI order looks wrong, or a page exists on disk but not in navigation, these are the first files to check.\n\n### Build and Tooling Scripts\n\nThese scripts keep the docs tree valid and routable:\n\n- `website/scripts/validate-docs-content.py`: validates docs structure, markers, and nav integrity\n- `website/scripts/materialize-inherited-docs.py`: generates transient routable anchors for inherited docs and stable current routes\n- `website/scripts/docs-editor.py`: CLI for creating, deleting, and renaming docs versions, books, sections, and pages safely\n\nIn practice:\n\n- use the validator when you need to confirm content-tree and nav consistency\n- use materialization when testing inheritance or stable-current route behavior\n- use the docs editor for structural changes instead of hand-editing multiple files\n\n### Runtime Template Layer\n\nThese files turn the requested docs URL into the page the user actually sees:\n\n- `website/themes/sambee/layouts/partials/docs/context.html`: derives docs path context from the requested route\n- `website/themes/sambee/layouts/partials/docs/page-path.html`: builds docs content paths with stable-current routing support\n- `website/themes/sambee/layouts/partials/docs/page-url.html`: resolves navigable docs URLs\n- `website/themes/sambee/layouts/partials/docs/source-page.html`: resolves the explicit versioned source page behind stable current routes\n- `website/themes/sambee/layouts/partials/docs/effective-page.html`: resolves the authored page that supplies body content and metadata\n- `website/themes/sambee/layouts/partials/docs/render-data.html`: prepares shared docs render data, including redirect and indexing state\n- `website/themes/sambee/layouts/partials/docs/article-shell.html`: renders the shared docs article shell\n- `website/themes/sambee/layouts/partials/docs/redirect-target.html`: resolves docs entry redirects\n- `website/themes/sambee/layouts/partials/docs/nav-tree.html`: resolves navigation targets and displayed titles\n- `website/themes/sambee/layouts/partials/docs/version-target-url.html`: resolves cross-version switch targets\n- `website/themes/sambee/layouts/partials/search-modal.html`: applies docs-version-aware search behavior\n- `website/themes/sambee/layouts/docs/list.html` and `website/themes/sambee/layouts/docs/single.html`: route docs list and page rendering through the shared shell\n\n### Theme Assets\n\nThese assets shape the visible docs experience once the route and content have been resolved:\n\n- `website/themes/sambee/assets/css/`: shared theme CSS, including docs UI and typography\n\n## Requested Route Versus Effective Page\n\nThe docs runtime keeps requested-path context separate from effective-content resolution.\n\n### Requested Route Context\n\n`website/themes/sambee/layouts/partials/docs/context.html` derives path context from the requested route and returns values including:\n\n- `isDocs`\n- `version`\n- `book`\n- `section`\n- `page`\n- `kind`\n- `currentVersion`\n- `isExplicitVersion`\n- `isCurrentRoute`\n- `isCurrentVersion`\n- convenience booleans: `isDocsRoot`, `isVersion`, `isBook`, `isSection`, and `isPage`\n\nInterpretation rules that matter when changing templates:\n\n- stable current routes such as `/docs/website-dev-guide/...` still resolve to the current version even though the version slug is omitted\n- explicit current-version routes such as `/docs/0.7/...` are compatibility routes and should redirect to stable current routes\n- archived explicit version routes stay routable and render as full docs pages\n\n### Effective Content Resolution\n\n`website/themes/sambee/layouts/partials/docs/effective-page.html` then resolves the authored content source and returns values including:\n\n- `page`: the authored page that should supply title, description, TOC, and body content\n- `requestedPage`: the Hugo page for the requested route\n- `requestedVersion`: the version derived from the route\n- `resolvedVersion`: the version that supplied the effective content\n- `isInherited`: whether the route resolved through inheritance\n\nTemplates should render article content and metadata from `page`, while navigation state, breadcrumbs, and version-switcher state stay tied to the requested route context.\n\n## Why Materialization Exists\n\nHugo needs a concrete page object at the requested path. Raw marker files alone are not enough.\n\nThe build therefore materializes transient route anchors under `.generated/content/docs` so Hugo can route inherited pages and stable current routes without publishing broken `/inherit/` or `/_inherit/` URLs.\n\nFrom Hugo's perspective, `inherit.md` and `_inherit.md` are ordinary content files. If the site consumed them directly, Hugo would try to publish the wrong public URLs.\n\nExample:\n\n- `content/docs/1.1/end-user/getting-started/install/inherit.md` would naturally publish at `/docs/1.1/end-user/getting-started/install/inherit/`\n- `content/docs/1.1/_inherit.md` would naturally publish at `/docs/1.1/_inherit/`\n\nThose are invalid for this docs model. The canonical public URLs must stay attached to the folder path itself:\n\n- `/docs/1.1/end-user/getting-started/install/`\n- `/docs/1.1/`\n\nThat creates a routing gap:\n\n- raw marker files must not become public pages\n- Hugo still needs a real page or section node at the requested folder path so templates can run and the resolver can supply inherited content\n\nThe moving pieces are:\n\n- `website/hugo.toml` ignores raw marker files as direct public pages\n- `website/scripts/materialize-inherited-docs.py` generates transient anchors at the canonical folder paths\n- `website/config/_default/module.toml` mounts `.generated/content` into Hugo's content tree\n- `website/themes/sambee/layouts/partials/docs/effective-page.html` resolves the real authored page that should supply the body, title, description, and TOC\n\nDuring the build, `materialize-inherited-docs.py` does this work:\n\n1. deletes stale generated docs anchors under `website/.generated/content/docs/`\n2. scans `website/content/docs/` for `inherit.md` and `_inherit.md`\n3. generates transient `index.md` or `_index.md` anchors at the matching canonical folder paths under `website/.generated/content/docs/`\n4. generates transient anchors for the declared current version at stable routes under `website/.generated/content/docs/\u003cbook\u003e/...`\n5. marks inherited-route anchors with `inherit = true`\n6. marks stable current-route anchors with `current_route = true` and `source_docs_path = \"/docs/\u003ccurrent\u003e/...\"`\n\nOperational notes:\n\n- `website/.generated/` is build output and is ignored by Git\n- Hugo mounts `.generated/content` into the site content tree during the build\n- Hugo is configured to ignore raw `inherit.md` and `_inherit.md` files\n\nWithout this script, the project would be stuck with two bad options:\n\n- keep raw marker files visible to Hugo and accept broken `/inherit/` and `/_inherit/` URLs\n- ignore marker files and lose the routable page nodes needed to render inherited docs at canonical folder URLs\n\n## Version Switcher Fallback Order\n\nWhen a reader switches from one docs version to another, the target lookup order is:\n\n1. the same page path\n2. the same section landing path\n3. the same book landing path\n4. the target version landing path\n\n## Search Behavior\n\nDocs search is intentionally version-aware.\n\n- Pagefind indexes stable current docs URLs, not explicit current-version compatibility routes\n- current docs search results therefore keep stable unversioned URLs\n- explicit versioned docs pages are excluded from the current-version search index\n- on non-docs pages, the UI defaults docs search filters to the `current` version from `website/data/docs-versions.toml`\n- versions with `searchable = false` are excluded from docs search indexing\n\n## Commands for Runtime Changes\n\nThe most relevant commands when you are changing docs runtime behavior are:\n\n- `npm run docs:validate`: validate docs content, nav data, markers, and inheritance rules\n- The validator checks for:\n\t- both `index.md` and `inherit.md` in the same page folder\n\t- both `_index.md` and `_inherit.md` in the same version, book, or section folder\n\t- missing required page markers in page folders\n\t- missing required `_index.md` or `_inherit.md` in version or book folders\n\t- invalid non-empty inheritance marker files\n\t- inheritance chains that never resolve to real content\n\t- nav entries that point to missing version, book, section, or page paths\n\t- duplicate nav slugs in books, sections, or pages\n\t- legacy identity metadata such as `doc_id` and `product_version`\n\t- disallowed docs front matter such as `aliases`\n- `npm run docs:materialize-inherited`: regenerate transient inherited-route and stable current-route anchors\n- `npm run build`: generate theme assets, validate docs, materialize docs route anchors, and build the site\n- `npm run build:search`: run the full build and then generate the Pagefind search index\n", "0.9": "+++\ntitle = \"Docs Runtime and Route Resolution\"\n+++\n\nThis page covers the implementation-facing side of docs routing.\n\nUse it when you need to answer questions such as:\n\n- which files own docs route resolution\n- how stable current routes differ from explicit versioned routes\n- how inherited pages become routable\n- how version switching and docs search stay version-aware\n\n## Runtime Map\n\nEditors usually work in content and nav files. Web developers also need to know which files own version metadata, build-time validation, and runtime route resolution.\n\n### Content and Navigation Sources\n\nThese files define what the docs tree is supposed to be:\n\n- `website/data/docs-versions.toml`: canonical docs version metadata\n- `website/data/docs-nav/\u003cversion\u003e.toml`: ordered books, sections, and pages\n\nIf the docs UI order looks wrong, or a page exists on disk but not in navigation, these are the first files to check.\n\n### Build and Tooling Scripts\n\nThese scripts keep the docs tree valid and routable:\n\n- `website/scripts/validate-docs-content.py`: validates docs structure, markers, and nav integrity\n- `website/scripts/materialize-inherited-docs.py`: generates transient routable anchors for inherited docs and stable current routes\n- `website/scripts/docs-editor.py`: CLI for creating, deleting, and renaming docs versions, books, sections, and pages safely\n\nIn practice:\n\n- use the validator when you need to confirm content-tree and nav consistency\n- use materialization when testing inheritance or stable-current route behavior\n- use the docs editor for structural changes instead of hand-editing multiple files\n\n### Runtime Template Layer\n\nThese files turn the requested docs URL into the page the user actually sees:\n\n- `website/themes/sambee/layouts/partials/docs/context.html`: derives docs path context from the requested route\n- `website/themes/sambee/layouts/partials/docs/page-path.html`: builds docs content paths with stable-current routing support\n- `website/themes/sambee/layouts/partials/docs/page-url.html`: resolves navigable docs URLs\n- `website/themes/sambee/layouts/partials/docs/source-page.html`: resolves the explicit versioned source page behind stable current routes\n- `website/themes/sambee/layouts/partials/docs/effective-page.html`: resolves the authored page that supplies body content and metadata\n- `website/themes/sambee/layouts/partials/docs/render-data.html`: prepares shared docs render data, including redirect and indexing state\n- `website/themes/sambee/layouts/partials/docs/article-shell.html`: renders the shared docs article shell\n- `website/themes/sambee/layouts/partials/docs/redirect-target.html`: resolves docs entry redirects\n- `website/themes/sambee/layouts/partials/docs/nav-tree.html`: resolves navigation targets and displayed titles\n- `website/themes/sambee/layouts/partials/docs/version-target-url.html`: resolves cross-version switch targets\n- `website/themes/sambee/layouts/partials/search-modal.html`: applies docs-version-aware search behavior\n- `website/themes/sambee/layouts/docs/list.html` and `website/themes/sambee/layouts/docs/single.html`: route docs list and page rendering through the shared shell\n\n### Theme Assets\n\nThese assets shape the visible docs experience once the route and content have been resolved:\n\n- `website/themes/sambee/assets/css/`: shared theme CSS, including docs UI and typography\n\n## Requested Route Versus Effective Page\n\nThe docs runtime keeps requested-path context separate from effective-content resolution.\n\n### Requested Route Context\n\n`website/themes/sambee/layouts/partials/docs/context.html` derives path context from the requested route and returns values including:\n\n- `isDocs`\n- `version`\n- `book`\n- `section`\n- `page`\n- `kind`\n- `currentVersion`\n- `isExplicitVersion`\n- `isCurrentRoute`\n- `isCurrentVersion`\n- convenience booleans: `isDocsRoot`, `isVersion`, `isBook`, `isSection`, and `isPage`\n\nInterpretation rules that matter when changing templates:\n\n- stable current routes such as `/docs/website-dev-guide/...` still resolve to the current version even though the version slug is omitted\n- explicit current-version routes such as `/docs/0.7/...` are compatibility routes and should redirect to stable current routes\n- archived explicit version routes stay routable and render as full docs pages\n\n### Effective Content Resolution\n\n`website/themes/sambee/layouts/partials/docs/effective-page.html` then resolves the authored content source and returns values including:\n\n- `page`: the authored page that should supply title, description, TOC, and body content\n- `requestedPage`: the Hugo page for the requested route\n- `requestedVersion`: the version derived from the route\n- `resolvedVersion`: the version that supplied the effective content\n- `isInherited`: whether the route resolved through inheritance\n\nTemplates should render article content and metadata from `page`, while navigation state, breadcrumbs, and version-switcher state stay tied to the requested route context.\n\n## Why Materialization Exists\n\nHugo needs a concrete page object at the requested path. Raw marker files alone are not enough.\n\nThe build therefore materializes transient route anchors under `.generated/content/docs` so Hugo can route inherited pages and stable current routes without publishing broken `/inherit/` or `/_inherit/` URLs.\n\nFrom Hugo's perspective, `inherit.md` and `_inherit.md` are ordinary content files. If the site consumed them directly, Hugo would try to publish the wrong public URLs.\n\nExample:\n\n- `content/docs/1.1/end-user/getting-started/install/inherit.md` would naturally publish at `/docs/1.1/end-user/getting-started/install/inherit/`\n- `content/docs/1.1/_inherit.md` would naturally publish at `/docs/1.1/_inherit/`\n\nThose are invalid for this docs model. The canonical public URLs must stay attached to the folder path itself:\n\n- `/docs/1.1/end-user/getting-started/install/`\n- `/docs/1.1/`\n\nThat creates a routing gap:\n\n- raw marker files must not become public pages\n- Hugo still needs a real page or section node at the requested folder path so templates can run and the resolver can supply inherited content\n\nThe moving pieces are:\n\n- `website/hugo.toml` ignores raw marker files as direct public pages\n- `website/scripts/materialize-inherited-docs.py` generates transient anchors at the canonical folder paths\n- `website/config/_default/module.toml` mounts `.generated/content` into Hugo's content tree\n- `website/themes/sambee/layouts/partials/docs/effective-page.html` resolves the real authored page that should supply the body, title, description, and TOC\n\nDuring the build, `materialize-inherited-docs.py` does this work:\n\n1. deletes stale generated docs anchors under `website/.generated/content/docs/`\n2. scans `website/content/docs/` for `inherit.md` and `_inherit.md`\n3. generates transient `index.md` or `_index.md` anchors at the matching canonical folder paths under `website/.generated/content/docs/`\n4. generates transient anchors for the declared current version at stable routes under `website/.generated/content/docs/\u003cbook\u003e/...`\n5. marks inherited-route anchors with `inherit = true`\n6. marks stable current-route anchors with `current_route = true` and `source_docs_path = \"/docs/\u003ccurrent\u003e/...\"`\n\nOperational notes:\n\n- `website/.generated/` is build output and is ignored by Git\n- Hugo mounts `.generated/content` into the site content tree during the build\n- Hugo is configured to ignore raw `inherit.md` and `_inherit.md` files\n\nWithout this script, the project would be stuck with two bad options:\n\n- keep raw marker files visible to Hugo and accept broken `/inherit/` and `/_inherit/` URLs\n- ignore marker files and lose the routable page nodes needed to render inherited docs at canonical folder URLs\n\n## Version Switcher Fallback Order\n\nWhen a reader switches from one docs version to another, the target lookup order is:\n\n1. the same page path\n2. the same section landing path\n3. the same book landing path\n4. the target version landing path\n\n## Search Behavior\n\nDocs search is intentionally version-aware.\n\n- Pagefind indexes stable current docs URLs, not explicit current-version compatibility routes\n- current docs search results therefore keep stable unversioned URLs\n- explicit versioned docs pages are excluded from the current-version search index\n- on non-docs pages, the UI defaults docs search filters to the `current` version from `website/data/docs-versions.toml`\n- versions with `searchable = false` are excluded from docs search indexing\n\n## Commands for Runtime Changes\n\nThe most relevant commands when you are changing docs runtime behavior are:\n\n- `npm run docs:validate`: validate docs content, nav data, markers, and inheritance rules\n- The validator checks for:\n\t- both `index.md` and `inherit.md` in the same page folder\n\t- both `_index.md` and `_inherit.md` in the same version, book, or section folder\n\t- missing required page markers in page folders\n\t- missing required `_index.md` or `_inherit.md` in version or book folders\n\t- invalid non-empty inheritance marker files\n\t- inheritance chains that never resolve to real content\n\t- nav entries that point to missing version, book, section, or page paths\n\t- duplicate nav slugs in books, sections, or pages\n\t- legacy identity metadata such as `doc_id` and `product_version`\n\t- disallowed docs front matter such as `aliases`\n- `npm run docs:materialize-inherited`: regenerate transient inherited-route and stable current-route anchors\n- `npm run build`: generate theme assets, validate docs, materialize docs route anchors, and build the site\n- `npm run build:search`: run the full build and then generate the Pagefind search index\n", "1.0": "+++\ntitle = \"Docs Runtime and Route Resolution\"\n+++\n\nThis page covers the implementation-facing side of docs routing.\n\nUse it when you need to answer questions such as:\n\n- which files own docs route resolution\n- how stable current routes differ from explicit versioned routes\n- how inherited pages become routable\n- how version switching and docs search stay version-aware\n\n## Runtime Map\n\nEditors usually work in content and nav files. Web developers also need to know which files own version metadata, build-time validation, and runtime route resolution.\n\n### Content and Navigation Sources\n\nThese files define what the docs tree is supposed to be:\n\n- `website/data/docs-versions.toml`: canonical docs version metadata\n- `website/data/docs-nav/\u003cversion\u003e.toml`: ordered books, sections, and pages\n\nIf the docs UI order looks wrong, or a page exists on disk but not in navigation, these are the first files to check.\n\n### Build and Tooling Scripts\n\nThese scripts keep the docs tree valid and routable:\n\n- `website/scripts/validate-docs-content.py`: validates docs structure, markers, and nav integrity\n- `website/scripts/materialize-inherited-docs.py`: generates transient routable anchors for inherited docs and stable current routes\n- `website/scripts/docs-editor.py`: CLI for creating, deleting, and renaming docs versions, books, sections, and pages safely\n\nIn practice:\n\n- use the validator when you need to confirm content-tree and nav consistency\n- use materialization when testing inheritance or stable-current route behavior\n- use the docs editor for structural changes instead of hand-editing multiple files\n\n### Runtime Template Layer\n\nThese files turn the requested docs URL into the page the user actually sees:\n\n- `website/themes/sambee/layouts/partials/docs/context.html`: derives docs path context from the requested route\n- `website/themes/sambee/layouts/partials/docs/page-path.html`: builds docs content paths with stable-current routing support\n- `website/themes/sambee/layouts/partials/docs/page-url.html`: resolves navigable docs URLs\n- `website/themes/sambee/layouts/partials/docs/source-page.html`: resolves the explicit versioned source page behind stable current routes\n- `website/themes/sambee/layouts/partials/docs/effective-page.html`: resolves the authored page that supplies body content and metadata\n- `website/themes/sambee/layouts/partials/docs/render-data.html`: prepares shared docs render data, including redirect and indexing state\n- `website/themes/sambee/layouts/partials/docs/article-shell.html`: renders the shared docs article shell\n- `website/themes/sambee/layouts/partials/docs/redirect-target.html`: resolves docs entry redirects\n- `website/themes/sambee/layouts/partials/docs/nav-tree.html`: resolves navigation targets and displayed titles\n- `website/themes/sambee/layouts/partials/docs/version-target-url.html`: resolves cross-version switch targets\n- `website/themes/sambee/layouts/partials/search-modal.html`: applies docs-version-aware search behavior\n- `website/themes/sambee/layouts/docs/list.html` and `website/themes/sambee/layouts/docs/single.html`: route docs list and page rendering through the shared shell\n\n### Theme Assets\n\nThese assets shape the visible docs experience once the route and content have been resolved:\n\n- `website/themes/sambee/assets/css/`: shared theme CSS, including docs UI and typography\n\n## Requested Route Versus Effective Page\n\nThe docs runtime keeps requested-path context separate from effective-content resolution.\n\n### Requested Route Context\n\n`website/themes/sambee/layouts/partials/docs/context.html` derives path context from the requested route and returns values including:\n\n- `isDocs`\n- `version`\n- `book`\n- `section`\n- `page`\n- `kind`\n- `currentVersion`\n- `isExplicitVersion`\n- `isCurrentRoute`\n- `isCurrentVersion`\n- convenience booleans: `isDocsRoot`, `isVersion`, `isBook`, `isSection`, and `isPage`\n\nInterpretation rules that matter when changing templates:\n\n- stable current routes such as `/docs/website-dev-guide/...` still resolve to the current version even though the version slug is omitted\n- explicit current-version routes such as `/docs/0.7/...` are compatibility routes and should redirect to stable current routes\n- archived explicit version routes stay routable and render as full docs pages\n\n### Effective Content Resolution\n\n`website/themes/sambee/layouts/partials/docs/effective-page.html` then resolves the authored content source and returns values including:\n\n- `page`: the authored page that should supply title, description, TOC, and body content\n- `requestedPage`: the Hugo page for the requested route\n- `requestedVersion`: the version derived from the route\n- `resolvedVersion`: the version that supplied the effective content\n- `isInherited`: whether the route resolved through inheritance\n\nTemplates should render article content and metadata from `page`, while navigation state, breadcrumbs, and version-switcher state stay tied to the requested route context.\n\n## Why Materialization Exists\n\nHugo needs a concrete page object at the requested path. Raw marker files alone are not enough.\n\nThe build therefore materializes transient route anchors under `.generated/content/docs` so Hugo can route inherited pages and stable current routes without publishing broken `/inherit/` or `/_inherit/` URLs.\n\nFrom Hugo's perspective, `inherit.md` and `_inherit.md` are ordinary content files. If the site consumed them directly, Hugo would try to publish the wrong public URLs.\n\nExample:\n\n- `content/docs/1.1/end-user/getting-started/install/inherit.md` would naturally publish at `/docs/1.1/end-user/getting-started/install/inherit/`\n- `content/docs/1.1/_inherit.md` would naturally publish at `/docs/1.1/_inherit/`\n\nThose are invalid for this docs model. The canonical public URLs must stay attached to the folder path itself:\n\n- `/docs/1.1/end-user/getting-started/install/`\n- `/docs/1.1/`\n\nThat creates a routing gap:\n\n- raw marker files must not become public pages\n- Hugo still needs a real page or section node at the requested folder path so templates can run and the resolver can supply inherited content\n\nThe moving pieces are:\n\n- `website/hugo.toml` ignores raw marker files as direct public pages\n- `website/scripts/materialize-inherited-docs.py` generates transient anchors at the canonical folder paths\n- `website/config/_default/module.toml` mounts `.generated/content` into Hugo's content tree\n- `website/themes/sambee/layouts/partials/docs/effective-page.html` resolves the real authored page that should supply the body, title, description, and TOC\n\nDuring the build, `materialize-inherited-docs.py` does this work:\n\n1. deletes stale generated docs anchors under `website/.generated/content/docs/`\n2. scans `website/content/docs/` for `inherit.md` and `_inherit.md`\n3. generates transient `index.md` or `_index.md` anchors at the matching canonical folder paths under `website/.generated/content/docs/`\n4. generates transient anchors for the declared current version at stable routes under `website/.generated/content/docs/\u003cbook\u003e/...`\n5. marks inherited-route anchors with `inherit = true`\n6. marks stable current-route anchors with `current_route = true` and `source_docs_path = \"/docs/\u003ccurrent\u003e/...\"`\n\nOperational notes:\n\n- `website/.generated/` is build output and is ignored by Git\n- Hugo mounts `.generated/content` into the site content tree during the build\n- Hugo is configured to ignore raw `inherit.md` and `_inherit.md` files\n\nWithout this script, the project would be stuck with two bad options:\n\n- keep raw marker files visible to Hugo and accept broken `/inherit/` and `/_inherit/` URLs\n- ignore marker files and lose the routable page nodes needed to render inherited docs at canonical folder URLs\n\n## Version Switcher Fallback Order\n\nWhen a reader switches from one docs version to another, the target lookup order is:\n\n1. the same page path\n2. the same section landing path\n3. the same book landing path\n4. the target version landing path\n\n## Search Behavior\n\nDocs search is intentionally version-aware.\n\n- Pagefind indexes stable current docs URLs, not explicit current-version compatibility routes\n- current docs search results therefore keep stable unversioned URLs\n- explicit versioned docs pages are excluded from the current-version search index\n- on non-docs pages, the UI defaults docs search filters to the `current` version from `website/data/docs-versions.toml`\n- versions with `searchable = false` are excluded from docs search indexing\n\n## Commands for Runtime Changes\n\nThe most relevant commands when you are changing docs runtime behavior are:\n\n- `npm run docs:validate`: validate docs content, nav data, markers, and inheritance rules\n- The validator checks for:\n\t- both `index.md` and `inherit.md` in the same page folder\n\t- both `_index.md` and `_inherit.md` in the same version, book, or section folder\n\t- missing required page markers in page folders\n\t- missing required `_index.md` or `_inherit.md` in version or book folders\n\t- invalid non-empty inheritance marker files\n\t- inheritance chains that never resolve to real content\n\t- nav entries that point to missing version, book, section, or page paths\n\t- duplicate nav slugs in books, sections, or pages\n\t- legacy identity metadata such as `doc_id` and `product_version`\n\t- disallowed docs front matter such as `aliases`\n- `npm run docs:materialize-inherited`: regenerate transient inherited-route and stable current-route anchors\n- `npm run build`: generate theme assets, validate docs, materialize docs route anchors, and build the site\n- `npm run build:search`: run the full build and then generate the Pagefind search index\n", "2.0": "+++\ntitle = \"Docs Runtime and Route Resolution\"\n+++\n\nThis page covers the implementation-facing side of docs routing.\n\nUse it when you need to answer questions such as:\n\n- which files own docs route resolution\n- how stable current routes differ from explicit versioned routes\n- how inherited pages become routable\n- how version switching and docs search stay version-aware\n\n## Runtime Map\n\nEditors usually work in content and nav files. Web developers also need to know which files own version metadata, build-time validation, and runtime route resolution.\n\n### Content and Navigation Sources\n\nThese files define what the docs tree is supposed to be:\n\n- `website/data/docs-versions.toml`: canonical docs version metadata\n- `website/data/docs-nav/\u003cversion\u003e.toml`: ordered books, sections, and pages\n\nIf the docs UI order looks wrong, or a page exists on disk but not in navigation, these are the first files to check.\n\n### Build and Tooling Scripts\n\nThese scripts keep the docs tree valid and routable:\n\n- `website/scripts/validate-docs-content.py`: validates docs structure, markers, and nav integrity\n- `website/scripts/materialize-inherited-docs.py`: generates transient routable anchors for inherited docs and stable current routes\n- `website/scripts/docs-editor.py`: CLI for creating, deleting, and renaming docs versions, books, sections, and pages safely\n\nIn practice:\n\n- use the validator when you need to confirm content-tree and nav consistency\n- use materialization when testing inheritance or stable-current route behavior\n- use the docs editor for structural changes instead of hand-editing multiple files\n\n### Runtime Template Layer\n\nThese files turn the requested docs URL into the page the user actually sees:\n\n- `website/themes/sambee/layouts/partials/docs/context.html`: derives docs path context from the requested route\n- `website/themes/sambee/layouts/partials/docs/page-path.html`: builds docs content paths with stable-current routing support\n- `website/themes/sambee/layouts/partials/docs/page-url.html`: resolves navigable docs URLs\n- `website/themes/sambee/layouts/partials/docs/source-page.html`: resolves the explicit versioned source page behind stable current routes\n- `website/themes/sambee/layouts/partials/docs/effective-page.html`: resolves the authored page that supplies body content and metadata\n- `website/themes/sambee/layouts/partials/docs/render-data.html`: prepares shared docs render data, including redirect and indexing state\n- `website/themes/sambee/layouts/partials/docs/article-shell.html`: renders the shared docs article shell\n- `website/themes/sambee/layouts/partials/docs/redirect-target.html`: resolves docs entry redirects\n- `website/themes/sambee/layouts/partials/docs/nav-tree.html`: resolves navigation targets and displayed titles\n- `website/themes/sambee/layouts/partials/docs/version-target-url.html`: resolves cross-version switch targets\n- `website/themes/sambee/layouts/partials/search-modal.html`: applies docs-version-aware search behavior\n- `website/themes/sambee/layouts/docs/list.html` and `website/themes/sambee/layouts/docs/single.html`: route docs list and page rendering through the shared shell\n\n### Theme Assets\n\nThese assets shape the visible docs experience once the route and content have been resolved:\n\n- `website/themes/sambee/assets/css/`: shared theme CSS, including docs UI and typography\n\n## Requested Route Versus Effective Page\n\nThe docs runtime keeps requested-path context separate from effective-content resolution.\n\n### Requested Route Context\n\n`website/themes/sambee/layouts/partials/docs/context.html` derives path context from the requested route and returns values including:\n\n- `isDocs`\n- `version`\n- `book`\n- `section`\n- `page`\n- `kind`\n- `currentVersion`\n- `isExplicitVersion`\n- `isCurrentRoute`\n- `isCurrentVersion`\n- convenience booleans: `isDocsRoot`, `isVersion`, `isBook`, `isSection`, and `isPage`\n\nInterpretation rules that matter when changing templates:\n\n- stable current routes such as `/docs/website-dev-guide/...` still resolve to the current version even though the version slug is omitted\n- explicit current-version routes such as `/docs/0.7/...` are compatibility routes and should redirect to stable current routes\n- archived explicit version routes stay routable and render as full docs pages\n\n### Effective Content Resolution\n\n`website/themes/sambee/layouts/partials/docs/effective-page.html` then resolves the authored content source and returns values including:\n\n- `page`: the authored page that should supply title, description, TOC, and body content\n- `requestedPage`: the Hugo page for the requested route\n- `requestedVersion`: the version derived from the route\n- `resolvedVersion`: the version that supplied the effective content\n- `isInherited`: whether the route resolved through inheritance\n\nTemplates should render article content and metadata from `page`, while navigation state, breadcrumbs, and version-switcher state stay tied to the requested route context.\n\n## Why Materialization Exists\n\nHugo needs a concrete page object at the requested path. Raw marker files alone are not enough.\n\nThe build therefore materializes transient route anchors under `.generated/content/docs` so Hugo can route inherited pages and stable current routes without publishing broken `/inherit/` or `/_inherit/` URLs.\n\nFrom Hugo's perspective, `inherit.md` and `_inherit.md` are ordinary content files. If the site consumed them directly, Hugo would try to publish the wrong public URLs.\n\nExample:\n\n- `content/docs/1.1/end-user/getting-started/install/inherit.md` would naturally publish at `/docs/1.1/end-user/getting-started/install/inherit/`\n- `content/docs/1.1/_inherit.md` would naturally publish at `/docs/1.1/_inherit/`\n\nThose are invalid for this docs model. The canonical public URLs must stay attached to the folder path itself:\n\n- `/docs/1.1/end-user/getting-started/install/`\n- `/docs/1.1/`\n\nThat creates a routing gap:\n\n- raw marker files must not become public pages\n- Hugo still needs a real page or section node at the requested folder path so templates can run and the resolver can supply inherited content\n\nThe moving pieces are:\n\n- `website/hugo.toml` ignores raw marker files as direct public pages\n- `website/scripts/materialize-inherited-docs.py` generates transient anchors at the canonical folder paths\n- `website/config/_default/module.toml` mounts `.generated/content` into Hugo's content tree\n- `website/themes/sambee/layouts/partials/docs/effective-page.html` resolves the real authored page that should supply the body, title, description, and TOC\n\nDuring the build, `materialize-inherited-docs.py` does this work:\n\n1. deletes stale generated docs anchors under `website/.generated/content/docs/`\n2. scans `website/content/docs/` for `inherit.md` and `_inherit.md`\n3. generates transient `index.md` or `_index.md` anchors at the matching canonical folder paths under `website/.generated/content/docs/`\n4. generates transient anchors for the declared current version at stable routes under `website/.generated/content/docs/\u003cbook\u003e/...`\n5. marks inherited-route anchors with `inherit = true`\n6. marks stable current-route anchors with `current_route = true` and `source_docs_path = \"/docs/\u003ccurrent\u003e/...\"`\n\nOperational notes:\n\n- `website/.generated/` is build output and is ignored by Git\n- Hugo mounts `.generated/content` into the site content tree during the build\n- Hugo is configured to ignore raw `inherit.md` and `_inherit.md` files\n\nWithout this script, the project would be stuck with two bad options:\n\n- keep raw marker files visible to Hugo and accept broken `/inherit/` and `/_inherit/` URLs\n- ignore marker files and lose the routable page nodes needed to render inherited docs at canonical folder URLs\n\n## Version Switcher Fallback Order\n\nWhen a reader switches from one docs version to another, the target lookup order is:\n\n1. the same page path\n2. the same section landing path\n3. the same book landing path\n4. the target version landing path\n\n## Search Behavior\n\nDocs search is intentionally version-aware.\n\n- Pagefind indexes stable current docs URLs, not explicit current-version compatibility routes\n- current docs search results therefore keep stable unversioned URLs\n- explicit versioned docs pages are excluded from the current-version search index\n- on non-docs pages, the UI defaults docs search filters to the `current` version from `website/data/docs-versions.toml`\n- versions with `searchable = false` are excluded from docs search indexing\n\n## Commands for Runtime Changes\n\nThe most relevant commands when you are changing docs runtime behavior are:\n\n- `npm run docs:validate`: validate docs content, nav data, markers, and inheritance rules\n- The validator checks for:\n\t- both `index.md` and `inherit.md` in the same page folder\n\t- both `_index.md` and `_inherit.md` in the same version, book, or section folder\n\t- missing required page markers in page folders\n\t- missing required `_index.md` or `_inherit.md` in version or book folders\n\t- invalid non-empty inheritance marker files\n\t- inheritance chains that never resolve to real content\n\t- nav entries that point to missing version, book, section, or page paths\n\t- duplicate nav slugs in books, sections, or pages\n\t- legacy identity metadata such as `doc_id` and `product_version`\n\t- disallowed docs front matter such as `aliases`\n- `npm run docs:materialize-inherited`: regenerate transient inherited-route and stable current-route anchors\n- `npm run build`: generate theme assets, validate docs, materialize docs route anchors, and build the site\n- `npm run build:search`: run the full build and then generate the Pagefind search index\n"}, "page_contents": {"0.7": "+++\ntitle = \"Docs Runtime and Route Resolution\"\n+++\n\nThis page covers the implementation-facing side of docs routing.\n\nUse it when you need to answer questions such as:\n\n- which files own docs route resolution\n- how stable current routes differ from explicit versioned routes\n- how inherited pages become routable\n- how version switching and docs search stay version-aware\n\n## Runtime Map\n\nEditors usually work in content and nav files. Web developers also need to know which files own version metadata, build-time validation, and runtime route resolution.\n\n### Content and Navigation Sources\n\nThese files define what the docs tree is supposed to be:\n\n- `website/data/docs-versions.toml`: canonical docs version metadata\n- `website/data/docs-nav/\u003cversion\u003e.toml`: ordered books, sections, and pages\n\nIf the docs UI order looks wrong, or a page exists on disk but not in navigation, these are the first files to check.\n\n### Build and Tooling Scripts\n\nThese scripts keep the docs tree valid and routable:\n\n- `website/scripts/validate-docs-content.py`: validates docs structure, markers, and nav integrity\n- `website/scripts/materialize-inherited-docs.py`: generates transient routable anchors for inherited docs and stable current routes\n- `website/scripts/docs-editor.py`: CLI for creating, deleting, and renaming docs versions, books, sections, and pages safely\n\nIn practice:\n\n- use the validator when you need to confirm content-tree and nav consistency\n- use materialization when testing inheritance or stable-current route behavior\n- use the docs editor for structural changes instead of hand-editing multiple files\n\n### Runtime Template Layer\n\nThese files turn the requested docs URL into the page the user actually sees:\n\n- `website/themes/sambee/layouts/partials/docs/context.html`: derives docs path context from the requested route\n- `website/themes/sambee/layouts/partials/docs/page-path.html`: builds docs content paths with stable-current routing support\n- `website/themes/sambee/layouts/partials/docs/page-url.html`: resolves navigable docs URLs\n- `website/themes/sambee/layouts/partials/docs/source-page.html`: resolves the explicit versioned source page behind stable current routes\n- `website/themes/sambee/layouts/partials/docs/effective-page.html`: resolves the authored page that supplies body content and metadata\n- `website/themes/sambee/layouts/partials/docs/render-data.html`: prepares shared docs render data, including redirect and indexing state\n- `website/themes/sambee/layouts/partials/docs/article-shell.html`: renders the shared docs article shell\n- `website/themes/sambee/layouts/partials/docs/redirect-target.html`: resolves docs entry redirects\n- `website/themes/sambee/layouts/partials/docs/nav-tree.html`: resolves navigation targets and displayed titles\n- `website/themes/sambee/layouts/partials/docs/version-target-url.html`: resolves cross-version switch targets\n- `website/themes/sambee/layouts/partials/search-modal.html`: applies docs-version-aware search behavior\n- `website/themes/sambee/layouts/docs/list.html` and `website/themes/sambee/layouts/docs/single.html`: route docs list and page rendering through the shared shell\n\n### Theme Assets\n\nThese assets shape the visible docs experience once the route and content have been resolved:\n\n- `website/themes/sambee/assets/css/`: shared theme CSS, including docs UI and typography\n\n## Requested Route Versus Effective Page\n\nThe docs runtime keeps requested-path context separate from effective-content resolution.\n\n### Requested Route Context\n\n`website/themes/sambee/layouts/partials/docs/context.html` derives path context from the requested route and returns values including:\n\n- `isDocs`\n- `version`\n- `book`\n- `section`\n- `page`\n- `kind`\n- `currentVersion`\n- `isExplicitVersion`\n- `isCurrentRoute`\n- `isCurrentVersion`\n- convenience booleans: `isDocsRoot`, `isVersion`, `isBook`, `isSection`, and `isPage`\n\nInterpretation rules that matter when changing templates:\n\n- stable current routes such as `/docs/website-dev-guide/...` still resolve to the current version even though the version slug is omitted\n- explicit current-version routes such as `/docs/0.7/...` are compatibility routes and should redirect to stable current routes\n- archived explicit version routes stay routable and render as full docs pages\n\n### Effective Content Resolution\n\n`website/themes/sambee/layouts/partials/docs/effective-page.html` then resolves the authored content source and returns values including:\n\n- `page`: the authored page that should supply title, description, TOC, and body content\n- `requestedPage`: the Hugo page for the requested route\n- `requestedVersion`: the version derived from the route\n- `resolvedVersion`: the version that supplied the effective content\n- `isInherited`: whether the route resolved through inheritance\n\nTemplates should render article content and metadata from `page`, while navigation state, breadcrumbs, and version-switcher state stay tied to the requested route context.\n\n## Why Materialization Exists\n\nHugo needs a concrete page object at the requested path. Raw marker files alone are not enough.\n\nThe build therefore materializes transient route anchors under `.generated/content/docs` so Hugo can route inherited pages and stable current routes without publishing broken `/inherit/` or `/_inherit/` URLs.\n\nFrom Hugo's perspective, `inherit.md` and `_inherit.md` are ordinary content files. If the site consumed them directly, Hugo would try to publish the wrong public URLs.\n\nExample:\n\n- `content/docs/1.1/end-user/getting-started/install/inherit.md` would naturally publish at `/docs/1.1/end-user/getting-started/install/inherit/`\n- `content/docs/1.1/_inherit.md` would naturally publish at `/docs/1.1/_inherit/`\n\nThose are invalid for this docs model. The canonical public URLs must stay attached to the folder path itself:\n\n- `/docs/1.1/end-user/getting-started/install/`\n- `/docs/1.1/`\n\nThat creates a routing gap:\n\n- raw marker files must not become public pages\n- Hugo still needs a real page or section node at the requested folder path so templates can run and the resolver can supply inherited content\n\nThe moving pieces are:\n\n- `website/hugo.toml` ignores raw marker files as direct public pages\n- `website/scripts/materialize-inherited-docs.py` generates transient anchors at the canonical folder paths\n- `website/config/_default/module.toml` mounts `.generated/content` into Hugo's content tree\n- `website/themes/sambee/layouts/partials/docs/effective-page.html` resolves the real authored page that should supply the body, title, description, and TOC\n\nDuring the build, `materialize-inherited-docs.py` does this work:\n\n1. deletes stale generated docs anchors under `website/.generated/content/docs/`\n2. scans `website/content/docs/` for `inherit.md` and `_inherit.md`\n3. generates transient `index.md` or `_index.md` anchors at the matching canonical folder paths under `website/.generated/content/docs/`\n4. generates transient anchors for the declared current version at stable routes under `website/.generated/content/docs/\u003cbook\u003e/...`\n5. marks inherited-route anchors with `inherit = true`\n6. marks stable current-route anchors with `current_route = true` and `source_docs_path = \"/docs/\u003ccurrent\u003e/...\"`\n\nOperational notes:\n\n- `website/.generated/` is build output and is ignored by Git\n- Hugo mounts `.generated/content` into the site content tree during the build\n- Hugo is configured to ignore raw `inherit.md` and `_inherit.md` files\n\nWithout this script, the project would be stuck with two bad options:\n\n- keep raw marker files visible to Hugo and accept broken `/inherit/` and `/_inherit/` URLs\n- ignore marker files and lose the routable page nodes needed to render inherited docs at canonical folder URLs\n\n## Version Switcher Fallback Order\n\nWhen a reader switches from one docs version to another, the target lookup order is:\n\n1. the same page path\n2. the same section landing path\n3. the same book landing path\n4. the target version landing path\n\n## Search Behavior\n\nDocs search is intentionally version-aware.\n\n- Pagefind indexes stable current docs URLs, not explicit current-version compatibility routes\n- current docs search results therefore keep stable unversioned URLs\n- explicit versioned docs pages are excluded from the current-version search index\n- on non-docs pages, the UI defaults docs search filters to the `current` version from `website/data/docs-versions.toml`\n- versions with `searchable = false` are excluded from docs search indexing\n\n## Commands for Runtime Changes\n\nThe most relevant commands when you are changing docs runtime behavior are:\n\n- `npm run docs:validate`: validate docs content, nav data, markers, and inheritance rules\n- The validator checks for:\n\t- both `index.md` and `inherit.md` in the same page folder\n\t- both `_index.md` and `_inherit.md` in the same version, book, or section folder\n\t- missing required page markers in page folders\n\t- missing required `_index.md` or `_inherit.md` in version or book folders\n\t- invalid non-empty inheritance marker files\n\t- inheritance chains that never resolve to real content\n\t- nav entries that point to missing version, book, section, or page paths\n\t- duplicate nav slugs in books, sections, or pages\n\t- legacy identity metadata such as `doc_id` and `product_version`\n\t- disallowed docs front matter such as `aliases`\n- `npm run docs:materialize-inherited`: regenerate transient inherited-route and stable current-route anchors\n- `npm run build`: generate theme assets, validate docs, materialize docs route anchors, and build the site\n- `npm run build:search`: run the full build and then generate the Pagefind search index\n", "0.8": "+++\ntitle = \"Docs Runtime and Route Resolution\"\n+++\n\nThis page covers the implementation-facing side of docs routing.\n\nUse it when you need to answer questions such as:\n\n- which files own docs route resolution\n- how stable current routes differ from explicit versioned routes\n- how inherited pages become routable\n- how version switching and docs search stay version-aware\n\n## Runtime Map\n\nEditors usually work in content and nav files. Web developers also need to know which files own version metadata, build-time validation, and runtime route resolution.\n\n### Content and Navigation Sources\n\nThese files define what the docs tree is supposed to be:\n\n- `website/data/docs-versions.toml`: canonical docs version metadata\n- `website/data/docs-nav/\u003cversion\u003e.toml`: ordered books, sections, and pages\n\nIf the docs UI order looks wrong, or a page exists on disk but not in navigation, these are the first files to check.\n\n### Build and Tooling Scripts\n\nThese scripts keep the docs tree valid and routable:\n\n- `website/scripts/validate-docs-content.py`: validates docs structure, markers, and nav integrity\n- `website/scripts/materialize-inherited-docs.py`: generates transient routable anchors for inherited docs and stable current routes\n- `website/scripts/docs-editor.py`: CLI for creating, deleting, and renaming docs versions, books, sections, and pages safely\n\nIn practice:\n\n- use the validator when you need to confirm content-tree and nav consistency\n- use materialization when testing inheritance or stable-current route behavior\n- use the docs editor for structural changes instead of hand-editing multiple files\n\n### Runtime Template Layer\n\nThese files turn the requested docs URL into the page the user actually sees:\n\n- `website/themes/sambee/layouts/partials/docs/context.html`: derives docs path context from the requested route\n- `website/themes/sambee/layouts/partials/docs/page-path.html`: builds docs content paths with stable-current routing support\n- `website/themes/sambee/layouts/partials/docs/page-url.html`: resolves navigable docs URLs\n- `website/themes/sambee/layouts/partials/docs/source-page.html`: resolves the explicit versioned source page behind stable current routes\n- `website/themes/sambee/layouts/partials/docs/effective-page.html`: resolves the authored page that supplies body content and metadata\n- `website/themes/sambee/layouts/partials/docs/render-data.html`: prepares shared docs render data, including redirect and indexing state\n- `website/themes/sambee/layouts/partials/docs/article-shell.html`: renders the shared docs article shell\n- `website/themes/sambee/layouts/partials/docs/redirect-target.html`: resolves docs entry redirects\n- `website/themes/sambee/layouts/partials/docs/nav-tree.html`: resolves navigation targets and displayed titles\n- `website/themes/sambee/layouts/partials/docs/version-target-url.html`: resolves cross-version switch targets\n- `website/themes/sambee/layouts/partials/search-modal.html`: applies docs-version-aware search behavior\n- `website/themes/sambee/layouts/docs/list.html` and `website/themes/sambee/layouts/docs/single.html`: route docs list and page rendering through the shared shell\n\n### Theme Assets\n\nThese assets shape the visible docs experience once the route and content have been resolved:\n\n- `website/themes/sambee/assets/css/`: shared theme CSS, including docs UI and typography\n\n## Requested Route Versus Effective Page\n\nThe docs runtime keeps requested-path context separate from effective-content resolution.\n\n### Requested Route Context\n\n`website/themes/sambee/layouts/partials/docs/context.html` derives path context from the requested route and returns values including:\n\n- `isDocs`\n- `version`\n- `book`\n- `section`\n- `page`\n- `kind`\n- `currentVersion`\n- `isExplicitVersion`\n- `isCurrentRoute`\n- `isCurrentVersion`\n- convenience booleans: `isDocsRoot`, `isVersion`, `isBook`, `isSection`, and `isPage`\n\nInterpretation rules that matter when changing templates:\n\n- stable current routes such as `/docs/website-dev-guide/...` still resolve to the current version even though the version slug is omitted\n- explicit current-version routes such as `/docs/0.7/...` are compatibility routes and should redirect to stable current routes\n- archived explicit version routes stay routable and render as full docs pages\n\n### Effective Content Resolution\n\n`website/themes/sambee/layouts/partials/docs/effective-page.html` then resolves the authored content source and returns values including:\n\n- `page`: the authored page that should supply title, description, TOC, and body content\n- `requestedPage`: the Hugo page for the requested route\n- `requestedVersion`: the version derived from the route\n- `resolvedVersion`: the version that supplied the effective content\n- `isInherited`: whether the route resolved through inheritance\n\nTemplates should render article content and metadata from `page`, while navigation state, breadcrumbs, and version-switcher state stay tied to the requested route context.\n\n## Why Materialization Exists\n\nHugo needs a concrete page object at the requested path. Raw marker files alone are not enough.\n\nThe build therefore materializes transient route anchors under `.generated/content/docs` so Hugo can route inherited pages and stable current routes without publishing broken `/inherit/` or `/_inherit/` URLs.\n\nFrom Hugo's perspective, `inherit.md` and `_inherit.md` are ordinary content files. If the site consumed them directly, Hugo would try to publish the wrong public URLs.\n\nExample:\n\n- `content/docs/1.1/end-user/getting-started/install/inherit.md` would naturally publish at `/docs/1.1/end-user/getting-started/install/inherit/`\n- `content/docs/1.1/_inherit.md` would naturally publish at `/docs/1.1/_inherit/`\n\nThose are invalid for this docs model. The canonical public URLs must stay attached to the folder path itself:\n\n- `/docs/1.1/end-user/getting-started/install/`\n- `/docs/1.1/`\n\nThat creates a routing gap:\n\n- raw marker files must not become public pages\n- Hugo still needs a real page or section node at the requested folder path so templates can run and the resolver can supply inherited content\n\nThe moving pieces are:\n\n- `website/hugo.toml` ignores raw marker files as direct public pages\n- `website/scripts/materialize-inherited-docs.py` generates transient anchors at the canonical folder paths\n- `website/config/_default/module.toml` mounts `.generated/content` into Hugo's content tree\n- `website/themes/sambee/layouts/partials/docs/effective-page.html` resolves the real authored page that should supply the body, title, description, and TOC\n\nDuring the build, `materialize-inherited-docs.py` does this work:\n\n1. deletes stale generated docs anchors under `website/.generated/content/docs/`\n2. scans `website/content/docs/` for `inherit.md` and `_inherit.md`\n3. generates transient `index.md` or `_index.md` anchors at the matching canonical folder paths under `website/.generated/content/docs/`\n4. generates transient anchors for the declared current version at stable routes under `website/.generated/content/docs/\u003cbook\u003e/...`\n5. marks inherited-route anchors with `inherit = true`\n6. marks stable current-route anchors with `current_route = true` and `source_docs_path = \"/docs/\u003ccurrent\u003e/...\"`\n\nOperational notes:\n\n- `website/.generated/` is build output and is ignored by Git\n- Hugo mounts `.generated/content` into the site content tree during the build\n- Hugo is configured to ignore raw `inherit.md` and `_inherit.md` files\n\nWithout this script, the project would be stuck with two bad options:\n\n- keep raw marker files visible to Hugo and accept broken `/inherit/` and `/_inherit/` URLs\n- ignore marker files and lose the routable page nodes needed to render inherited docs at canonical folder URLs\n\n## Version Switcher Fallback Order\n\nWhen a reader switches from one docs version to another, the target lookup order is:\n\n1. the same page path\n2. the same section landing path\n3. the same book landing path\n4. the target version landing path\n\n## Search Behavior\n\nDocs search is intentionally version-aware.\n\n- Pagefind indexes stable current docs URLs, not explicit current-version compatibility routes\n- current docs search results therefore keep stable unversioned URLs\n- explicit versioned docs pages are excluded from the current-version search index\n- on non-docs pages, the UI defaults docs search filters to the `current` version from `website/data/docs-versions.toml`\n- versions with `searchable = false` are excluded from docs search indexing\n\n## Commands for Runtime Changes\n\nThe most relevant commands when you are changing docs runtime behavior are:\n\n- `npm run docs:validate`: validate docs content, nav data, markers, and inheritance rules\n- The validator checks for:\n\t- both `index.md` and `inherit.md` in the same page folder\n\t- both `_index.md` and `_inherit.md` in the same version, book, or section folder\n\t- missing required page markers in page folders\n\t- missing required `_index.md` or `_inherit.md` in version or book folders\n\t- invalid non-empty inheritance marker files\n\t- inheritance chains that never resolve to real content\n\t- nav entries that point to missing version, book, section, or page paths\n\t- duplicate nav slugs in books, sections, or pages\n\t- legacy identity metadata such as `doc_id` and `product_version`\n\t- disallowed docs front matter such as `aliases`\n- `npm run docs:materialize-inherited`: regenerate transient inherited-route and stable current-route anchors\n- `npm run build`: generate theme assets, validate docs, materialize docs route anchors, and build the site\n- `npm run build:search`: run the full build and then generate the Pagefind search index\n", "0.9": "+++\ntitle = \"Docs Runtime and Route Resolution\"\n+++\n\nThis page covers the implementation-facing side of docs routing.\n\nUse it when you need to answer questions such as:\n\n- which files own docs route resolution\n- how stable current routes differ from explicit versioned routes\n- how inherited pages become routable\n- how version switching and docs search stay version-aware\n\n## Runtime Map\n\nEditors usually work in content and nav files. Web developers also need to know which files own version metadata, build-time validation, and runtime route resolution.\n\n### Content and Navigation Sources\n\nThese files define what the docs tree is supposed to be:\n\n- `website/data/docs-versions.toml`: canonical docs version metadata\n- `website/data/docs-nav/\u003cversion\u003e.toml`: ordered books, sections, and pages\n\nIf the docs UI order looks wrong, or a page exists on disk but not in navigation, these are the first files to check.\n\n### Build and Tooling Scripts\n\nThese scripts keep the docs tree valid and routable:\n\n- `website/scripts/validate-docs-content.py`: validates docs structure, markers, and nav integrity\n- `website/scripts/materialize-inherited-docs.py`: generates transient routable anchors for inherited docs and stable current routes\n- `website/scripts/docs-editor.py`: CLI for creating, deleting, and renaming docs versions, books, sections, and pages safely\n\nIn practice:\n\n- use the validator when you need to confirm content-tree and nav consistency\n- use materialization when testing inheritance or stable-current route behavior\n- use the docs editor for structural changes instead of hand-editing multiple files\n\n### Runtime Template Layer\n\nThese files turn the requested docs URL into the page the user actually sees:\n\n- `website/themes/sambee/layouts/partials/docs/context.html`: derives docs path context from the requested route\n- `website/themes/sambee/layouts/partials/docs/page-path.html`: builds docs content paths with stable-current routing support\n- `website/themes/sambee/layouts/partials/docs/page-url.html`: resolves navigable docs URLs\n- `website/themes/sambee/layouts/partials/docs/source-page.html`: resolves the explicit versioned source page behind stable current routes\n- `website/themes/sambee/layouts/partials/docs/effective-page.html`: resolves the authored page that supplies body content and metadata\n- `website/themes/sambee/layouts/partials/docs/render-data.html`: prepares shared docs render data, including redirect and indexing state\n- `website/themes/sambee/layouts/partials/docs/article-shell.html`: renders the shared docs article shell\n- `website/themes/sambee/layouts/partials/docs/redirect-target.html`: resolves docs entry redirects\n- `website/themes/sambee/layouts/partials/docs/nav-tree.html`: resolves navigation targets and displayed titles\n- `website/themes/sambee/layouts/partials/docs/version-target-url.html`: resolves cross-version switch targets\n- `website/themes/sambee/layouts/partials/search-modal.html`: applies docs-version-aware search behavior\n- `website/themes/sambee/layouts/docs/list.html` and `website/themes/sambee/layouts/docs/single.html`: route docs list and page rendering through the shared shell\n\n### Theme Assets\n\nThese assets shape the visible docs experience once the route and content have been resolved:\n\n- `website/themes/sambee/assets/css/`: shared theme CSS, including docs UI and typography\n\n## Requested Route Versus Effective Page\n\nThe docs runtime keeps requested-path context separate from effective-content resolution.\n\n### Requested Route Context\n\n`website/themes/sambee/layouts/partials/docs/context.html` derives path context from the requested route and returns values including:\n\n- `isDocs`\n- `version`\n- `book`\n- `section`\n- `page`\n- `kind`\n- `currentVersion`\n- `isExplicitVersion`\n- `isCurrentRoute`\n- `isCurrentVersion`\n- convenience booleans: `isDocsRoot`, `isVersion`, `isBook`, `isSection`, and `isPage`\n\nInterpretation rules that matter when changing templates:\n\n- stable current routes such as `/docs/website-dev-guide/...` still resolve to the current version even though the version slug is omitted\n- explicit current-version routes such as `/docs/0.7/...` are compatibility routes and should redirect to stable current routes\n- archived explicit version routes stay routable and render as full docs pages\n\n### Effective Content Resolution\n\n`website/themes/sambee/layouts/partials/docs/effective-page.html` then resolves the authored content source and returns values including:\n\n- `page`: the authored page that should supply title, description, TOC, and body content\n- `requestedPage`: the Hugo page for the requested route\n- `requestedVersion`: the version derived from the route\n- `resolvedVersion`: the version that supplied the effective content\n- `isInherited`: whether the route resolved through inheritance\n\nTemplates should render article content and metadata from `page`, while navigation state, breadcrumbs, and version-switcher state stay tied to the requested route context.\n\n## Why Materialization Exists\n\nHugo needs a concrete page object at the requested path. Raw marker files alone are not enough.\n\nThe build therefore materializes transient route anchors under `.generated/content/docs` so Hugo can route inherited pages and stable current routes without publishing broken `/inherit/` or `/_inherit/` URLs.\n\nFrom Hugo's perspective, `inherit.md` and `_inherit.md` are ordinary content files. If the site consumed them directly, Hugo would try to publish the wrong public URLs.\n\nExample:\n\n- `content/docs/1.1/end-user/getting-started/install/inherit.md` would naturally publish at `/docs/1.1/end-user/getting-started/install/inherit/`\n- `content/docs/1.1/_inherit.md` would naturally publish at `/docs/1.1/_inherit/`\n\nThose are invalid for this docs model. The canonical public URLs must stay attached to the folder path itself:\n\n- `/docs/1.1/end-user/getting-started/install/`\n- `/docs/1.1/`\n\nThat creates a routing gap:\n\n- raw marker files must not become public pages\n- Hugo still needs a real page or section node at the requested folder path so templates can run and the resolver can supply inherited content\n\nThe moving pieces are:\n\n- `website/hugo.toml` ignores raw marker files as direct public pages\n- `website/scripts/materialize-inherited-docs.py` generates transient anchors at the canonical folder paths\n- `website/config/_default/module.toml` mounts `.generated/content` into Hugo's content tree\n- `website/themes/sambee/layouts/partials/docs/effective-page.html` resolves the real authored page that should supply the body, title, description, and TOC\n\nDuring the build, `materialize-inherited-docs.py` does this work:\n\n1. deletes stale generated docs anchors under `website/.generated/content/docs/`\n2. scans `website/content/docs/` for `inherit.md` and `_inherit.md`\n3. generates transient `index.md` or `_index.md` anchors at the matching canonical folder paths under `website/.generated/content/docs/`\n4. generates transient anchors for the declared current version at stable routes under `website/.generated/content/docs/\u003cbook\u003e/...`\n5. marks inherited-route anchors with `inherit = true`\n6. marks stable current-route anchors with `current_route = true` and `source_docs_path = \"/docs/\u003ccurrent\u003e/...\"`\n\nOperational notes:\n\n- `website/.generated/` is build output and is ignored by Git\n- Hugo mounts `.generated/content` into the site content tree during the build\n- Hugo is configured to ignore raw `inherit.md` and `_inherit.md` files\n\nWithout this script, the project would be stuck with two bad options:\n\n- keep raw marker files visible to Hugo and accept broken `/inherit/` and `/_inherit/` URLs\n- ignore marker files and lose the routable page nodes needed to render inherited docs at canonical folder URLs\n\n## Version Switcher Fallback Order\n\nWhen a reader switches from one docs version to another, the target lookup order is:\n\n1. the same page path\n2. the same section landing path\n3. the same book landing path\n4. the target version landing path\n\n## Search Behavior\n\nDocs search is intentionally version-aware.\n\n- Pagefind indexes stable current docs URLs, not explicit current-version compatibility routes\n- current docs search results therefore keep stable unversioned URLs\n- explicit versioned docs pages are excluded from the current-version search index\n- on non-docs pages, the UI defaults docs search filters to the `current` version from `website/data/docs-versions.toml`\n- versions with `searchable = false` are excluded from docs search indexing\n\n## Commands for Runtime Changes\n\nThe most relevant commands when you are changing docs runtime behavior are:\n\n- `npm run docs:validate`: validate docs content, nav data, markers, and inheritance rules\n- The validator checks for:\n\t- both `index.md` and `inherit.md` in the same page folder\n\t- both `_index.md` and `_inherit.md` in the same version, book, or section folder\n\t- missing required page markers in page folders\n\t- missing required `_index.md` or `_inherit.md` in version or book folders\n\t- invalid non-empty inheritance marker files\n\t- inheritance chains that never resolve to real content\n\t- nav entries that point to missing version, book, section, or page paths\n\t- duplicate nav slugs in books, sections, or pages\n\t- legacy identity metadata such as `doc_id` and `product_version`\n\t- disallowed docs front matter such as `aliases`\n- `npm run docs:materialize-inherited`: regenerate transient inherited-route and stable current-route anchors\n- `npm run build`: generate theme assets, validate docs, materialize docs route anchors, and build the site\n- `npm run build:search`: run the full build and then generate the Pagefind search index\n", "1.0": "+++\ntitle = \"Docs Runtime and Route Resolution\"\n+++\n\nThis page covers the implementation-facing side of docs routing.\n\nUse it when you need to answer questions such as:\n\n- which files own docs route resolution\n- how stable current routes differ from explicit versioned routes\n- how inherited pages become routable\n- how version switching and docs search stay version-aware\n\n## Runtime Map\n\nEditors usually work in content and nav files. Web developers also need to know which files own version metadata, build-time validation, and runtime route resolution.\n\n### Content and Navigation Sources\n\nThese files define what the docs tree is supposed to be:\n\n- `website/data/docs-versions.toml`: canonical docs version metadata\n- `website/data/docs-nav/\u003cversion\u003e.toml`: ordered books, sections, and pages\n\nIf the docs UI order looks wrong, or a page exists on disk but not in navigation, these are the first files to check.\n\n### Build and Tooling Scripts\n\nThese scripts keep the docs tree valid and routable:\n\n- `website/scripts/validate-docs-content.py`: validates docs structure, markers, and nav integrity\n- `website/scripts/materialize-inherited-docs.py`: generates transient routable anchors for inherited docs and stable current routes\n- `website/scripts/docs-editor.py`: CLI for creating, deleting, and renaming docs versions, books, sections, and pages safely\n\nIn practice:\n\n- use the validator when you need to confirm content-tree and nav consistency\n- use materialization when testing inheritance or stable-current route behavior\n- use the docs editor for structural changes instead of hand-editing multiple files\n\n### Runtime Template Layer\n\nThese files turn the requested docs URL into the page the user actually sees:\n\n- `website/themes/sambee/layouts/partials/docs/context.html`: derives docs path context from the requested route\n- `website/themes/sambee/layouts/partials/docs/page-path.html`: builds docs content paths with stable-current routing support\n- `website/themes/sambee/layouts/partials/docs/page-url.html`: resolves navigable docs URLs\n- `website/themes/sambee/layouts/partials/docs/source-page.html`: resolves the explicit versioned source page behind stable current routes\n- `website/themes/sambee/layouts/partials/docs/effective-page.html`: resolves the authored page that supplies body content and metadata\n- `website/themes/sambee/layouts/partials/docs/render-data.html`: prepares shared docs render data, including redirect and indexing state\n- `website/themes/sambee/layouts/partials/docs/article-shell.html`: renders the shared docs article shell\n- `website/themes/sambee/layouts/partials/docs/redirect-target.html`: resolves docs entry redirects\n- `website/themes/sambee/layouts/partials/docs/nav-tree.html`: resolves navigation targets and displayed titles\n- `website/themes/sambee/layouts/partials/docs/version-target-url.html`: resolves cross-version switch targets\n- `website/themes/sambee/layouts/partials/search-modal.html`: applies docs-version-aware search behavior\n- `website/themes/sambee/layouts/docs/list.html` and `website/themes/sambee/layouts/docs/single.html`: route docs list and page rendering through the shared shell\n\n### Theme Assets\n\nThese assets shape the visible docs experience once the route and content have been resolved:\n\n- `website/themes/sambee/assets/css/`: shared theme CSS, including docs UI and typography\n\n## Requested Route Versus Effective Page\n\nThe docs runtime keeps requested-path context separate from effective-content resolution.\n\n### Requested Route Context\n\n`website/themes/sambee/layouts/partials/docs/context.html` derives path context from the requested route and returns values including:\n\n- `isDocs`\n- `version`\n- `book`\n- `section`\n- `page`\n- `kind`\n- `currentVersion`\n- `isExplicitVersion`\n- `isCurrentRoute`\n- `isCurrentVersion`\n- convenience booleans: `isDocsRoot`, `isVersion`, `isBook`, `isSection`, and `isPage`\n\nInterpretation rules that matter when changing templates:\n\n- stable current routes such as `/docs/website-dev-guide/...` still resolve to the current version even though the version slug is omitted\n- explicit current-version routes such as `/docs/0.7/...` are compatibility routes and should redirect to stable current routes\n- archived explicit version routes stay routable and render as full docs pages\n\n### Effective Content Resolution\n\n`website/themes/sambee/layouts/partials/docs/effective-page.html` then resolves the authored content source and returns values including:\n\n- `page`: the authored page that should supply title, description, TOC, and body content\n- `requestedPage`: the Hugo page for the requested route\n- `requestedVersion`: the version derived from the route\n- `resolvedVersion`: the version that supplied the effective content\n- `isInherited`: whether the route resolved through inheritance\n\nTemplates should render article content and metadata from `page`, while navigation state, breadcrumbs, and version-switcher state stay tied to the requested route context.\n\n## Why Materialization Exists\n\nHugo needs a concrete page object at the requested path. Raw marker files alone are not enough.\n\nThe build therefore materializes transient route anchors under `.generated/content/docs` so Hugo can route inherited pages and stable current routes without publishing broken `/inherit/` or `/_inherit/` URLs.\n\nFrom Hugo's perspective, `inherit.md` and `_inherit.md` are ordinary content files. If the site consumed them directly, Hugo would try to publish the wrong public URLs.\n\nExample:\n\n- `content/docs/1.1/end-user/getting-started/install/inherit.md` would naturally publish at `/docs/1.1/end-user/getting-started/install/inherit/`\n- `content/docs/1.1/_inherit.md` would naturally publish at `/docs/1.1/_inherit/`\n\nThose are invalid for this docs model. The canonical public URLs must stay attached to the folder path itself:\n\n- `/docs/1.1/end-user/getting-started/install/`\n- `/docs/1.1/`\n\nThat creates a routing gap:\n\n- raw marker files must not become public pages\n- Hugo still needs a real page or section node at the requested folder path so templates can run and the resolver can supply inherited content\n\nThe moving pieces are:\n\n- `website/hugo.toml` ignores raw marker files as direct public pages\n- `website/scripts/materialize-inherited-docs.py` generates transient anchors at the canonical folder paths\n- `website/config/_default/module.toml` mounts `.generated/content` into Hugo's content tree\n- `website/themes/sambee/layouts/partials/docs/effective-page.html` resolves the real authored page that should supply the body, title, description, and TOC\n\nDuring the build, `materialize-inherited-docs.py` does this work:\n\n1. deletes stale generated docs anchors under `website/.generated/content/docs/`\n2. scans `website/content/docs/` for `inherit.md` and `_inherit.md`\n3. generates transient `index.md` or `_index.md` anchors at the matching canonical folder paths under `website/.generated/content/docs/`\n4. generates transient anchors for the declared current version at stable routes under `website/.generated/content/docs/\u003cbook\u003e/...`\n5. marks inherited-route anchors with `inherit = true`\n6. marks stable current-route anchors with `current_route = true` and `source_docs_path = \"/docs/\u003ccurrent\u003e/...\"`\n\nOperational notes:\n\n- `website/.generated/` is build output and is ignored by Git\n- Hugo mounts `.generated/content` into the site content tree during the build\n- Hugo is configured to ignore raw `inherit.md` and `_inherit.md` files\n\nWithout this script, the project would be stuck with two bad options:\n\n- keep raw marker files visible to Hugo and accept broken `/inherit/` and `/_inherit/` URLs\n- ignore marker files and lose the routable page nodes needed to render inherited docs at canonical folder URLs\n\n## Version Switcher Fallback Order\n\nWhen a reader switches from one docs version to another, the target lookup order is:\n\n1. the same page path\n2. the same section landing path\n3. the same book landing path\n4. the target version landing path\n\n## Search Behavior\n\nDocs search is intentionally version-aware.\n\n- Pagefind indexes stable current docs URLs, not explicit current-version compatibility routes\n- current docs search results therefore keep stable unversioned URLs\n- explicit versioned docs pages are excluded from the current-version search index\n- on non-docs pages, the UI defaults docs search filters to the `current` version from `website/data/docs-versions.toml`\n- versions with `searchable = false` are excluded from docs search indexing\n\n## Commands for Runtime Changes\n\nThe most relevant commands when you are changing docs runtime behavior are:\n\n- `npm run docs:validate`: validate docs content, nav data, markers, and inheritance rules\n- The validator checks for:\n\t- both `index.md` and `inherit.md` in the same page folder\n\t- both `_index.md` and `_inherit.md` in the same version, book, or section folder\n\t- missing required page markers in page folders\n\t- missing required `_index.md` or `_inherit.md` in version or book folders\n\t- invalid non-empty inheritance marker files\n\t- inheritance chains that never resolve to real content\n\t- nav entries that point to missing version, book, section, or page paths\n\t- duplicate nav slugs in books, sections, or pages\n\t- legacy identity metadata such as `doc_id` and `product_version`\n\t- disallowed docs front matter such as `aliases`\n- `npm run docs:materialize-inherited`: regenerate transient inherited-route and stable current-route anchors\n- `npm run build`: generate theme assets, validate docs, materialize docs route anchors, and build the site\n- `npm run build:search`: run the full build and then generate the Pagefind search index\n", "2.0": "+++\ntitle = \"Docs Runtime and Route Resolution\"\n+++\n\nThis page covers the implementation-facing side of docs routing.\n\nUse it when you need to answer questions such as:\n\n- which files own docs route resolution\n- how stable current routes differ from explicit versioned routes\n- how inherited pages become routable\n- how version switching and docs search stay version-aware\n\n## Runtime Map\n\nEditors usually work in content and nav files. Web developers also need to know which files own version metadata, build-time validation, and runtime route resolution.\n\n### Content and Navigation Sources\n\nThese files define what the docs tree is supposed to be:\n\n- `website/data/docs-versions.toml`: canonical docs version metadata\n- `website/data/docs-nav/\u003cversion\u003e.toml`: ordered books, sections, and pages\n\nIf the docs UI order looks wrong, or a page exists on disk but not in navigation, these are the first files to check.\n\n### Build and Tooling Scripts\n\nThese scripts keep the docs tree valid and routable:\n\n- `website/scripts/validate-docs-content.py`: validates docs structure, markers, and nav integrity\n- `website/scripts/materialize-inherited-docs.py`: generates transient routable anchors for inherited docs and stable current routes\n- `website/scripts/docs-editor.py`: CLI for creating, deleting, and renaming docs versions, books, sections, and pages safely\n\nIn practice:\n\n- use the validator when you need to confirm content-tree and nav consistency\n- use materialization when testing inheritance or stable-current route behavior\n- use the docs editor for structural changes instead of hand-editing multiple files\n\n### Runtime Template Layer\n\nThese files turn the requested docs URL into the page the user actually sees:\n\n- `website/themes/sambee/layouts/partials/docs/context.html`: derives docs path context from the requested route\n- `website/themes/sambee/layouts/partials/docs/page-path.html`: builds docs content paths with stable-current routing support\n- `website/themes/sambee/layouts/partials/docs/page-url.html`: resolves navigable docs URLs\n- `website/themes/sambee/layouts/partials/docs/source-page.html`: resolves the explicit versioned source page behind stable current routes\n- `website/themes/sambee/layouts/partials/docs/effective-page.html`: resolves the authored page that supplies body content and metadata\n- `website/themes/sambee/layouts/partials/docs/render-data.html`: prepares shared docs render data, including redirect and indexing state\n- `website/themes/sambee/layouts/partials/docs/article-shell.html`: renders the shared docs article shell\n- `website/themes/sambee/layouts/partials/docs/redirect-target.html`: resolves docs entry redirects\n- `website/themes/sambee/layouts/partials/docs/nav-tree.html`: resolves navigation targets and displayed titles\n- `website/themes/sambee/layouts/partials/docs/version-target-url.html`: resolves cross-version switch targets\n- `website/themes/sambee/layouts/partials/search-modal.html`: applies docs-version-aware search behavior\n- `website/themes/sambee/layouts/docs/list.html` and `website/themes/sambee/layouts/docs/single.html`: route docs list and page rendering through the shared shell\n\n### Theme Assets\n\nThese assets shape the visible docs experience once the route and content have been resolved:\n\n- `website/themes/sambee/assets/css/`: shared theme CSS, including docs UI and typography\n\n## Requested Route Versus Effective Page\n\nThe docs runtime keeps requested-path context separate from effective-content resolution.\n\n### Requested Route Context\n\n`website/themes/sambee/layouts/partials/docs/context.html` derives path context from the requested route and returns values including:\n\n- `isDocs`\n- `version`\n- `book`\n- `section`\n- `page`\n- `kind`\n- `currentVersion`\n- `isExplicitVersion`\n- `isCurrentRoute`\n- `isCurrentVersion`\n- convenience booleans: `isDocsRoot`, `isVersion`, `isBook`, `isSection`, and `isPage`\n\nInterpretation rules that matter when changing templates:\n\n- stable current routes such as `/docs/website-dev-guide/...` still resolve to the current version even though the version slug is omitted\n- explicit current-version routes such as `/docs/0.7/...` are compatibility routes and should redirect to stable current routes\n- archived explicit version routes stay routable and render as full docs pages\n\n### Effective Content Resolution\n\n`website/themes/sambee/layouts/partials/docs/effective-page.html` then resolves the authored content source and returns values including:\n\n- `page`: the authored page that should supply title, description, TOC, and body content\n- `requestedPage`: the Hugo page for the requested route\n- `requestedVersion`: the version derived from the route\n- `resolvedVersion`: the version that supplied the effective content\n- `isInherited`: whether the route resolved through inheritance\n\nTemplates should render article content and metadata from `page`, while navigation state, breadcrumbs, and version-switcher state stay tied to the requested route context.\n\n## Why Materialization Exists\n\nHugo needs a concrete page object at the requested path. Raw marker files alone are not enough.\n\nThe build therefore materializes transient route anchors under `.generated/content/docs` so Hugo can route inherited pages and stable current routes without publishing broken `/inherit/` or `/_inherit/` URLs.\n\nFrom Hugo's perspective, `inherit.md` and `_inherit.md` are ordinary content files. If the site consumed them directly, Hugo would try to publish the wrong public URLs.\n\nExample:\n\n- `content/docs/1.1/end-user/getting-started/install/inherit.md` would naturally publish at `/docs/1.1/end-user/getting-started/install/inherit/`\n- `content/docs/1.1/_inherit.md` would naturally publish at `/docs/1.1/_inherit/`\n\nThose are invalid for this docs model. The canonical public URLs must stay attached to the folder path itself:\n\n- `/docs/1.1/end-user/getting-started/install/`\n- `/docs/1.1/`\n\nThat creates a routing gap:\n\n- raw marker files must not become public pages\n- Hugo still needs a real page or section node at the requested folder path so templates can run and the resolver can supply inherited content\n\nThe moving pieces are:\n\n- `website/hugo.toml` ignores raw marker files as direct public pages\n- `website/scripts/materialize-inherited-docs.py` generates transient anchors at the canonical folder paths\n- `website/config/_default/module.toml` mounts `.generated/content` into Hugo's content tree\n- `website/themes/sambee/layouts/partials/docs/effective-page.html` resolves the real authored page that should supply the body, title, description, and TOC\n\nDuring the build, `materialize-inherited-docs.py` does this work:\n\n1. deletes stale generated docs anchors under `website/.generated/content/docs/`\n2. scans `website/content/docs/` for `inherit.md` and `_inherit.md`\n3. generates transient `index.md` or `_index.md` anchors at the matching canonical folder paths under `website/.generated/content/docs/`\n4. generates transient anchors for the declared current version at stable routes under `website/.generated/content/docs/\u003cbook\u003e/...`\n5. marks inherited-route anchors with `inherit = true`\n6. marks stable current-route anchors with `current_route = true` and `source_docs_path = \"/docs/\u003ccurrent\u003e/...\"`\n\nOperational notes:\n\n- `website/.generated/` is build output and is ignored by Git\n- Hugo mounts `.generated/content` into the site content tree during the build\n- Hugo is configured to ignore raw `inherit.md` and `_inherit.md` files\n\nWithout this script, the project would be stuck with two bad options:\n\n- keep raw marker files visible to Hugo and accept broken `/inherit/` and `/_inherit/` URLs\n- ignore marker files and lose the routable page nodes needed to render inherited docs at canonical folder URLs\n\n## Version Switcher Fallback Order\n\nWhen a reader switches from one docs version to another, the target lookup order is:\n\n1. the same page path\n2. the same section landing path\n3. the same book landing path\n4. the target version landing path\n\n## Search Behavior\n\nDocs search is intentionally version-aware.\n\n- Pagefind indexes stable current docs URLs, not explicit current-version compatibility routes\n- current docs search results therefore keep stable unversioned URLs\n- explicit versioned docs pages are excluded from the current-version search index\n- on non-docs pages, the UI defaults docs search filters to the `current` version from `website/data/docs-versions.toml`\n- versions with `searchable = false` are excluded from docs search indexing\n\n## Commands for Runtime Changes\n\nThe most relevant commands when you are changing docs runtime behavior are:\n\n- `npm run docs:validate`: validate docs content, nav data, markers, and inheritance rules\n- The validator checks for:\n\t- both `index.md` and `inherit.md` in the same page folder\n\t- both `_index.md` and `_inherit.md` in the same version, book, or section folder\n\t- missing required page markers in page folders\n\t- missing required `_index.md` or `_inherit.md` in version or book folders\n\t- invalid non-empty inheritance marker files\n\t- inheritance chains that never resolve to real content\n\t- nav entries that point to missing version, book, section, or page paths\n\t- duplicate nav slugs in books, sections, or pages\n\t- legacy identity metadata such as `doc_id` and `product_version`\n\t- disallowed docs front matter such as `aliases`\n- `npm run docs:materialize-inherited`: regenerate transient inherited-route and stable current-route anchors\n- `npm run build`: generate theme assets, validate docs, materialize docs route anchors, and build the site\n- `npm run build:search`: run the full build and then generate the Pagefind search index\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:website-dev-guide/authoring-and-tooling", "parent_id": "book:website-dev-guide", "depth": 1, "kind": "section", "label": "authoring-and-tooling", "title": "Authoring and Tooling", "path": "website-dev-guide/authoring-and-tooling", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:website-dev-guide/authoring-and-tooling/docs-authoring-workflow", "parent_id": "section:website-dev-guide/authoring-and-tooling", "depth": 2, "kind": "page", "label": "docs-authoring-workflow", "title": "Docs Authoring Workflow", "path": "website-dev-guide/authoring-and-tooling/docs-authoring-workflow", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "Book and section landing pages are optional. Either may be structural only, with no `_index.md` and no `_inherit.md`. A structural node remains in navigation but has no public landing route. This Website Dev Guide uses structural-only sections.\n+++\ntitle = \"Docs Authoring Workflow\"\n+++\n\nFor wording, list punctuation, and capitalization conventions, use the [Docs Style Guide](../docs-style-guide/).\n\n## Content Structure Rules\n\nThe docs system is path-derived.\n\n- book landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/_index.md`\n- section landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/_index.md`\n- article page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md`\n\nSection landing pages are optional. A section may be structural only, with no `_index.md` and no `_inherit.md`. This Website Dev Guide uses structural-only sections.\n\n## Example: Add a New Page\n\nSuppose you want a new page under `website-dev-guide/authoring-and-tooling/`.\n\nCreate the content bundle:\n\n```text\nwebsite/content/docs/0.7/website-dev-guide/authoring-and-tooling/new-page/index.md\n```\n\nThen add the page slug to the matching nav section:\n\n```toml\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n  \"new-page\",\n]\n```\n\nWithout the nav update, the page may exist on disk but stay absent from generated navigation.\n\n## Example: Reuse an Older Page without Copying the Content\n\nWhen a newer version should reuse the same page unchanged:\n\n1. create the same page folder in the newer version\n2. add an empty `inherit.md`\n3. keep the corresponding path in an older version with real `index.md` content\n\nExample:\n\n```text\nwebsite/content/docs/0.8/website-dev-guide/site-systems/media-publishing-workflow/inherit.md\n```\n\nDo not put front matter or body content into `inherit.md`.\n\n## Example: Diverge in a Newer Version\n\nIf a newer version needs different content, replace the marker with a real page:\n\n1. remove `inherit.md`\n2. create `index.md`\n3. write the new content for that version\n\nThat keeps the inheritance chain explicit and avoids template-side special cases.\n\n## Navigation Rules\n\nNavigation data controls order, not content. Keep these rules in mind:\n\n- slugs in the nav file must match the folder names on disk\n- changing a slug changes the public URL\n- page titles come from the page's own front matter, not from the nav file\n- section titles come from `docs-nav/\u003cversion\u003e.toml`\n\n## When to Use the Docs Editor Instead of Manual File Edits\n\nManual edits are normal for copy changes inside an existing page.\n\nUse the docs editor when the change is structural, for example:\n\n- creating a new book\n- creating, deleting, or renaming a section\n- creating, deleting, or renaming a page\n- changing docs structure across inherited versions\n\nThe docs editor keeps content paths and nav data in sync and refuses destructive changes that would silently overwrite newer authored content.\n\n## Validation\n\nFor docs and website changes, run:\n\n```bash\ncd website\nnpm run build\n```\n\nThat is the minimum meaningful verification because it runs theme generation, docs validation, inherited-doc materialization, Hugo rendering, and homepage CTA validation.\n", "0.8": "Book and section landing pages are optional. Either may be structural only, with no `_index.md` and no `_inherit.md`. A structural node remains in navigation but has no public landing route. This Website Dev Guide uses structural-only sections.\n+++\ntitle = \"Docs Authoring Workflow\"\n+++\n\nFor wording, list punctuation, and capitalization conventions, use the [Docs Style Guide](../docs-style-guide/).\n\n## Content Structure Rules\n\nThe docs system is path-derived.\n\n- book landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/_index.md`\n- section landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/_index.md`\n- article page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md`\n\nSection landing pages are optional. A section may be structural only, with no `_index.md` and no `_inherit.md`. This Website Dev Guide uses structural-only sections.\n\n## Example: Add a New Page\n\nSuppose you want a new page under `website-dev-guide/authoring-and-tooling/`.\n\nCreate the content bundle:\n\n```text\nwebsite/content/docs/0.7/website-dev-guide/authoring-and-tooling/new-page/index.md\n```\n\nThen add the page slug to the matching nav section:\n\n```toml\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n  \"new-page\",\n]\n```\n\nWithout the nav update, the page may exist on disk but stay absent from generated navigation.\n\n## Example: Reuse an Older Page without Copying the Content\n\nWhen a newer version should reuse the same page unchanged:\n\n1. create the same page folder in the newer version\n2. add an empty `inherit.md`\n3. keep the corresponding path in an older version with real `index.md` content\n\nExample:\n\n```text\nwebsite/content/docs/0.8/website-dev-guide/site-systems/media-publishing-workflow/inherit.md\n```\n\nDo not put front matter or body content into `inherit.md`.\n\n## Example: Diverge in a Newer Version\n\nIf a newer version needs different content, replace the marker with a real page:\n\n1. remove `inherit.md`\n2. create `index.md`\n3. write the new content for that version\n\nThat keeps the inheritance chain explicit and avoids template-side special cases.\n\n## Navigation Rules\n\nNavigation data controls order, not content. Keep these rules in mind:\n\n- slugs in the nav file must match the folder names on disk\n- changing a slug changes the public URL\n- page titles come from the page's own front matter, not from the nav file\n- section titles come from `docs-nav/\u003cversion\u003e.toml`\n\n## When to Use the Docs Editor Instead of Manual File Edits\n\nManual edits are normal for copy changes inside an existing page.\n\nUse the docs editor when the change is structural, for example:\n\n- creating a new book\n- creating, deleting, or renaming a section\n- creating, deleting, or renaming a page\n- changing docs structure across inherited versions\n\nThe docs editor keeps content paths and nav data in sync and refuses destructive changes that would silently overwrite newer authored content.\n\n## Validation\n\nFor docs and website changes, run:\n\n```bash\ncd website\nnpm run build\n```\n\nThat is the minimum meaningful verification because it runs theme generation, docs validation, inherited-doc materialization, Hugo rendering, and homepage CTA validation.\n", "0.9": "Book and section landing pages are optional. Either may be structural only, with no `_index.md` and no `_inherit.md`. A structural node remains in navigation but has no public landing route. This Website Dev Guide uses structural-only sections.\n+++\ntitle = \"Docs Authoring Workflow\"\n+++\n\nFor wording, list punctuation, and capitalization conventions, use the [Docs Style Guide](../docs-style-guide/).\n\n## Content Structure Rules\n\nThe docs system is path-derived.\n\n- book landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/_index.md`\n- section landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/_index.md`\n- article page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md`\n\nSection landing pages are optional. A section may be structural only, with no `_index.md` and no `_inherit.md`. This Website Dev Guide uses structural-only sections.\n\n## Example: Add a New Page\n\nSuppose you want a new page under `website-dev-guide/authoring-and-tooling/`.\n\nCreate the content bundle:\n\n```text\nwebsite/content/docs/0.7/website-dev-guide/authoring-and-tooling/new-page/index.md\n```\n\nThen add the page slug to the matching nav section:\n\n```toml\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n  \"new-page\",\n]\n```\n\nWithout the nav update, the page may exist on disk but stay absent from generated navigation.\n\n## Example: Reuse an Older Page without Copying the Content\n\nWhen a newer version should reuse the same page unchanged:\n\n1. create the same page folder in the newer version\n2. add an empty `inherit.md`\n3. keep the corresponding path in an older version with real `index.md` content\n\nExample:\n\n```text\nwebsite/content/docs/0.8/website-dev-guide/site-systems/media-publishing-workflow/inherit.md\n```\n\nDo not put front matter or body content into `inherit.md`.\n\n## Example: Diverge in a Newer Version\n\nIf a newer version needs different content, replace the marker with a real page:\n\n1. remove `inherit.md`\n2. create `index.md`\n3. write the new content for that version\n\nThat keeps the inheritance chain explicit and avoids template-side special cases.\n\n## Navigation Rules\n\nNavigation data controls order, not content. Keep these rules in mind:\n\n- slugs in the nav file must match the folder names on disk\n- changing a slug changes the public URL\n- page titles come from the page's own front matter, not from the nav file\n- section titles come from `docs-nav/\u003cversion\u003e.toml`\n\n## When to Use the Docs Editor Instead of Manual File Edits\n\nManual edits are normal for copy changes inside an existing page.\n\nUse the docs editor when the change is structural, for example:\n\n- creating a new book\n- creating, deleting, or renaming a section\n- creating, deleting, or renaming a page\n- changing docs structure across inherited versions\n\nThe docs editor keeps content paths and nav data in sync and refuses destructive changes that would silently overwrite newer authored content.\n\n## Validation\n\nFor docs and website changes, run:\n\n```bash\ncd website\nnpm run build\n```\n\nThat is the minimum meaningful verification because it runs theme generation, docs validation, inherited-doc materialization, Hugo rendering, and homepage CTA validation.\n", "1.0": "Book and section landing pages are optional. Either may be structural only, with no `_index.md` and no `_inherit.md`. A structural node remains in navigation but has no public landing route. This Website Dev Guide uses structural-only sections.\n+++\ntitle = \"Docs Authoring Workflow\"\n+++\n\nFor wording, list punctuation, and capitalization conventions, use the [Docs Style Guide](../docs-style-guide/).\n\n## Content Structure Rules\n\nThe docs system is path-derived.\n\n- book landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/_index.md`\n- section landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/_index.md`\n- article page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md`\n\nSection landing pages are optional. A section may be structural only, with no `_index.md` and no `_inherit.md`. This Website Dev Guide uses structural-only sections.\n\n## Example: Add a New Page\n\nSuppose you want a new page under `website-dev-guide/authoring-and-tooling/`.\n\nCreate the content bundle:\n\n```text\nwebsite/content/docs/0.7/website-dev-guide/authoring-and-tooling/new-page/index.md\n```\n\nThen add the page slug to the matching nav section:\n\n```toml\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n  \"new-page\",\n]\n```\n\nWithout the nav update, the page may exist on disk but stay absent from generated navigation.\n\n## Example: Reuse an Older Page without Copying the Content\n\nWhen a newer version should reuse the same page unchanged:\n\n1. create the same page folder in the newer version\n2. add an empty `inherit.md`\n3. keep the corresponding path in an older version with real `index.md` content\n\nExample:\n\n```text\nwebsite/content/docs/0.8/website-dev-guide/site-systems/media-publishing-workflow/inherit.md\n```\n\nDo not put front matter or body content into `inherit.md`.\n\n## Example: Diverge in a Newer Version\n\nIf a newer version needs different content, replace the marker with a real page:\n\n1. remove `inherit.md`\n2. create `index.md`\n3. write the new content for that version\n\nThat keeps the inheritance chain explicit and avoids template-side special cases.\n\n## Navigation Rules\n\nNavigation data controls order, not content. Keep these rules in mind:\n\n- slugs in the nav file must match the folder names on disk\n- changing a slug changes the public URL\n- page titles come from the page's own front matter, not from the nav file\n- section titles come from `docs-nav/\u003cversion\u003e.toml`\n\n## When to Use the Docs Editor Instead of Manual File Edits\n\nManual edits are normal for copy changes inside an existing page.\n\nUse the docs editor when the change is structural, for example:\n\n- creating a new book\n- creating, deleting, or renaming a section\n- creating, deleting, or renaming a page\n- changing docs structure across inherited versions\n\nThe docs editor keeps content paths and nav data in sync and refuses destructive changes that would silently overwrite newer authored content.\n\n## Validation\n\nFor docs and website changes, run:\n\n```bash\ncd website\nnpm run build\n```\n\nThat is the minimum meaningful verification because it runs theme generation, docs validation, inherited-doc materialization, Hugo rendering, and homepage CTA validation.\n", "2.0": "Book and section landing pages are optional. Either may be structural only, with no `_index.md` and no `_inherit.md`. A structural node remains in navigation but has no public landing route. This Website Dev Guide uses structural-only sections.\n+++\ntitle = \"Docs Authoring Workflow\"\n+++\n\nFor wording, list punctuation, and capitalization conventions, use the [Docs Style Guide](../docs-style-guide/).\n\n## Content Structure Rules\n\nThe docs system is path-derived.\n\n- book landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/_index.md`\n- section landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/_index.md`\n- article page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md`\n\nSection landing pages are optional. A section may be structural only, with no `_index.md` and no `_inherit.md`. This Website Dev Guide uses structural-only sections.\n\n## Example: Add a New Page\n\nSuppose you want a new page under `website-dev-guide/authoring-and-tooling/`.\n\nCreate the content bundle:\n\n```text\nwebsite/content/docs/0.7/website-dev-guide/authoring-and-tooling/new-page/index.md\n```\n\nThen add the page slug to the matching nav section:\n\n```toml\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n  \"new-page\",\n]\n```\n\nWithout the nav update, the page may exist on disk but stay absent from generated navigation.\n\n## Example: Reuse an Older Page without Copying the Content\n\nWhen a newer version should reuse the same page unchanged:\n\n1. create the same page folder in the newer version\n2. add an empty `inherit.md`\n3. keep the corresponding path in an older version with real `index.md` content\n\nExample:\n\n```text\nwebsite/content/docs/0.8/website-dev-guide/site-systems/media-publishing-workflow/inherit.md\n```\n\nDo not put front matter or body content into `inherit.md`.\n\n## Example: Diverge in a Newer Version\n\nIf a newer version needs different content, replace the marker with a real page:\n\n1. remove `inherit.md`\n2. create `index.md`\n3. write the new content for that version\n\nThat keeps the inheritance chain explicit and avoids template-side special cases.\n\n## Navigation Rules\n\nNavigation data controls order, not content. Keep these rules in mind:\n\n- slugs in the nav file must match the folder names on disk\n- changing a slug changes the public URL\n- page titles come from the page's own front matter, not from the nav file\n- section titles come from `docs-nav/\u003cversion\u003e.toml`\n\n## When to Use the Docs Editor Instead of Manual File Edits\n\nManual edits are normal for copy changes inside an existing page.\n\nUse the docs editor when the change is structural, for example:\n\n- creating a new book\n- creating, deleting, or renaming a section\n- creating, deleting, or renaming a page\n- changing docs structure across inherited versions\n\nThe docs editor keeps content paths and nav data in sync and refuses destructive changes that would silently overwrite newer authored content.\n\n## Validation\n\nFor docs and website changes, run:\n\n```bash\ncd website\nnpm run build\n```\n\nThat is the minimum meaningful verification because it runs theme generation, docs validation, inherited-doc materialization, Hugo rendering, and homepage CTA validation.\n"}, "page_contents": {"0.7": "Book and section landing pages are optional. Either may be structural only, with no `_index.md` and no `_inherit.md`. A structural node remains in navigation but has no public landing route. This Website Dev Guide uses structural-only sections.\n+++\ntitle = \"Docs Authoring Workflow\"\n+++\n\nFor wording, list punctuation, and capitalization conventions, use the [Docs Style Guide](../docs-style-guide/).\n\n## Content Structure Rules\n\nThe docs system is path-derived.\n\n- book landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/_index.md`\n- section landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/_index.md`\n- article page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md`\n\nSection landing pages are optional. A section may be structural only, with no `_index.md` and no `_inherit.md`. This Website Dev Guide uses structural-only sections.\n\n## Example: Add a New Page\n\nSuppose you want a new page under `website-dev-guide/authoring-and-tooling/`.\n\nCreate the content bundle:\n\n```text\nwebsite/content/docs/0.7/website-dev-guide/authoring-and-tooling/new-page/index.md\n```\n\nThen add the page slug to the matching nav section:\n\n```toml\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n  \"new-page\",\n]\n```\n\nWithout the nav update, the page may exist on disk but stay absent from generated navigation.\n\n## Example: Reuse an Older Page without Copying the Content\n\nWhen a newer version should reuse the same page unchanged:\n\n1. create the same page folder in the newer version\n2. add an empty `inherit.md`\n3. keep the corresponding path in an older version with real `index.md` content\n\nExample:\n\n```text\nwebsite/content/docs/0.8/website-dev-guide/site-systems/media-publishing-workflow/inherit.md\n```\n\nDo not put front matter or body content into `inherit.md`.\n\n## Example: Diverge in a Newer Version\n\nIf a newer version needs different content, replace the marker with a real page:\n\n1. remove `inherit.md`\n2. create `index.md`\n3. write the new content for that version\n\nThat keeps the inheritance chain explicit and avoids template-side special cases.\n\n## Navigation Rules\n\nNavigation data controls order, not content. Keep these rules in mind:\n\n- slugs in the nav file must match the folder names on disk\n- changing a slug changes the public URL\n- page titles come from the page's own front matter, not from the nav file\n- section titles come from `docs-nav/\u003cversion\u003e.toml`\n\n## When to Use the Docs Editor Instead of Manual File Edits\n\nManual edits are normal for copy changes inside an existing page.\n\nUse the docs editor when the change is structural, for example:\n\n- creating a new book\n- creating, deleting, or renaming a section\n- creating, deleting, or renaming a page\n- changing docs structure across inherited versions\n\nThe docs editor keeps content paths and nav data in sync and refuses destructive changes that would silently overwrite newer authored content.\n\n## Validation\n\nFor docs and website changes, run:\n\n```bash\ncd website\nnpm run build\n```\n\nThat is the minimum meaningful verification because it runs theme generation, docs validation, inherited-doc materialization, Hugo rendering, and homepage CTA validation.\n", "0.8": "Book and section landing pages are optional. Either may be structural only, with no `_index.md` and no `_inherit.md`. A structural node remains in navigation but has no public landing route. This Website Dev Guide uses structural-only sections.\n+++\ntitle = \"Docs Authoring Workflow\"\n+++\n\nFor wording, list punctuation, and capitalization conventions, use the [Docs Style Guide](../docs-style-guide/).\n\n## Content Structure Rules\n\nThe docs system is path-derived.\n\n- book landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/_index.md`\n- section landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/_index.md`\n- article page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md`\n\nSection landing pages are optional. A section may be structural only, with no `_index.md` and no `_inherit.md`. This Website Dev Guide uses structural-only sections.\n\n## Example: Add a New Page\n\nSuppose you want a new page under `website-dev-guide/authoring-and-tooling/`.\n\nCreate the content bundle:\n\n```text\nwebsite/content/docs/0.7/website-dev-guide/authoring-and-tooling/new-page/index.md\n```\n\nThen add the page slug to the matching nav section:\n\n```toml\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n  \"new-page\",\n]\n```\n\nWithout the nav update, the page may exist on disk but stay absent from generated navigation.\n\n## Example: Reuse an Older Page without Copying the Content\n\nWhen a newer version should reuse the same page unchanged:\n\n1. create the same page folder in the newer version\n2. add an empty `inherit.md`\n3. keep the corresponding path in an older version with real `index.md` content\n\nExample:\n\n```text\nwebsite/content/docs/0.8/website-dev-guide/site-systems/media-publishing-workflow/inherit.md\n```\n\nDo not put front matter or body content into `inherit.md`.\n\n## Example: Diverge in a Newer Version\n\nIf a newer version needs different content, replace the marker with a real page:\n\n1. remove `inherit.md`\n2. create `index.md`\n3. write the new content for that version\n\nThat keeps the inheritance chain explicit and avoids template-side special cases.\n\n## Navigation Rules\n\nNavigation data controls order, not content. Keep these rules in mind:\n\n- slugs in the nav file must match the folder names on disk\n- changing a slug changes the public URL\n- page titles come from the page's own front matter, not from the nav file\n- section titles come from `docs-nav/\u003cversion\u003e.toml`\n\n## When to Use the Docs Editor Instead of Manual File Edits\n\nManual edits are normal for copy changes inside an existing page.\n\nUse the docs editor when the change is structural, for example:\n\n- creating a new book\n- creating, deleting, or renaming a section\n- creating, deleting, or renaming a page\n- changing docs structure across inherited versions\n\nThe docs editor keeps content paths and nav data in sync and refuses destructive changes that would silently overwrite newer authored content.\n\n## Validation\n\nFor docs and website changes, run:\n\n```bash\ncd website\nnpm run build\n```\n\nThat is the minimum meaningful verification because it runs theme generation, docs validation, inherited-doc materialization, Hugo rendering, and homepage CTA validation.\n", "0.9": "Book and section landing pages are optional. Either may be structural only, with no `_index.md` and no `_inherit.md`. A structural node remains in navigation but has no public landing route. This Website Dev Guide uses structural-only sections.\n+++\ntitle = \"Docs Authoring Workflow\"\n+++\n\nFor wording, list punctuation, and capitalization conventions, use the [Docs Style Guide](../docs-style-guide/).\n\n## Content Structure Rules\n\nThe docs system is path-derived.\n\n- book landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/_index.md`\n- section landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/_index.md`\n- article page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md`\n\nSection landing pages are optional. A section may be structural only, with no `_index.md` and no `_inherit.md`. This Website Dev Guide uses structural-only sections.\n\n## Example: Add a New Page\n\nSuppose you want a new page under `website-dev-guide/authoring-and-tooling/`.\n\nCreate the content bundle:\n\n```text\nwebsite/content/docs/0.7/website-dev-guide/authoring-and-tooling/new-page/index.md\n```\n\nThen add the page slug to the matching nav section:\n\n```toml\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n  \"new-page\",\n]\n```\n\nWithout the nav update, the page may exist on disk but stay absent from generated navigation.\n\n## Example: Reuse an Older Page without Copying the Content\n\nWhen a newer version should reuse the same page unchanged:\n\n1. create the same page folder in the newer version\n2. add an empty `inherit.md`\n3. keep the corresponding path in an older version with real `index.md` content\n\nExample:\n\n```text\nwebsite/content/docs/0.8/website-dev-guide/site-systems/media-publishing-workflow/inherit.md\n```\n\nDo not put front matter or body content into `inherit.md`.\n\n## Example: Diverge in a Newer Version\n\nIf a newer version needs different content, replace the marker with a real page:\n\n1. remove `inherit.md`\n2. create `index.md`\n3. write the new content for that version\n\nThat keeps the inheritance chain explicit and avoids template-side special cases.\n\n## Navigation Rules\n\nNavigation data controls order, not content. Keep these rules in mind:\n\n- slugs in the nav file must match the folder names on disk\n- changing a slug changes the public URL\n- page titles come from the page's own front matter, not from the nav file\n- section titles come from `docs-nav/\u003cversion\u003e.toml`\n\n## When to Use the Docs Editor Instead of Manual File Edits\n\nManual edits are normal for copy changes inside an existing page.\n\nUse the docs editor when the change is structural, for example:\n\n- creating a new book\n- creating, deleting, or renaming a section\n- creating, deleting, or renaming a page\n- changing docs structure across inherited versions\n\nThe docs editor keeps content paths and nav data in sync and refuses destructive changes that would silently overwrite newer authored content.\n\n## Validation\n\nFor docs and website changes, run:\n\n```bash\ncd website\nnpm run build\n```\n\nThat is the minimum meaningful verification because it runs theme generation, docs validation, inherited-doc materialization, Hugo rendering, and homepage CTA validation.\n", "1.0": "Book and section landing pages are optional. Either may be structural only, with no `_index.md` and no `_inherit.md`. A structural node remains in navigation but has no public landing route. This Website Dev Guide uses structural-only sections.\n+++\ntitle = \"Docs Authoring Workflow\"\n+++\n\nFor wording, list punctuation, and capitalization conventions, use the [Docs Style Guide](../docs-style-guide/).\n\n## Content Structure Rules\n\nThe docs system is path-derived.\n\n- book landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/_index.md`\n- section landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/_index.md`\n- article page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md`\n\nSection landing pages are optional. A section may be structural only, with no `_index.md` and no `_inherit.md`. This Website Dev Guide uses structural-only sections.\n\n## Example: Add a New Page\n\nSuppose you want a new page under `website-dev-guide/authoring-and-tooling/`.\n\nCreate the content bundle:\n\n```text\nwebsite/content/docs/0.7/website-dev-guide/authoring-and-tooling/new-page/index.md\n```\n\nThen add the page slug to the matching nav section:\n\n```toml\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n  \"new-page\",\n]\n```\n\nWithout the nav update, the page may exist on disk but stay absent from generated navigation.\n\n## Example: Reuse an Older Page without Copying the Content\n\nWhen a newer version should reuse the same page unchanged:\n\n1. create the same page folder in the newer version\n2. add an empty `inherit.md`\n3. keep the corresponding path in an older version with real `index.md` content\n\nExample:\n\n```text\nwebsite/content/docs/0.8/website-dev-guide/site-systems/media-publishing-workflow/inherit.md\n```\n\nDo not put front matter or body content into `inherit.md`.\n\n## Example: Diverge in a Newer Version\n\nIf a newer version needs different content, replace the marker with a real page:\n\n1. remove `inherit.md`\n2. create `index.md`\n3. write the new content for that version\n\nThat keeps the inheritance chain explicit and avoids template-side special cases.\n\n## Navigation Rules\n\nNavigation data controls order, not content. Keep these rules in mind:\n\n- slugs in the nav file must match the folder names on disk\n- changing a slug changes the public URL\n- page titles come from the page's own front matter, not from the nav file\n- section titles come from `docs-nav/\u003cversion\u003e.toml`\n\n## When to Use the Docs Editor Instead of Manual File Edits\n\nManual edits are normal for copy changes inside an existing page.\n\nUse the docs editor when the change is structural, for example:\n\n- creating a new book\n- creating, deleting, or renaming a section\n- creating, deleting, or renaming a page\n- changing docs structure across inherited versions\n\nThe docs editor keeps content paths and nav data in sync and refuses destructive changes that would silently overwrite newer authored content.\n\n## Validation\n\nFor docs and website changes, run:\n\n```bash\ncd website\nnpm run build\n```\n\nThat is the minimum meaningful verification because it runs theme generation, docs validation, inherited-doc materialization, Hugo rendering, and homepage CTA validation.\n", "2.0": "Book and section landing pages are optional. Either may be structural only, with no `_index.md` and no `_inherit.md`. A structural node remains in navigation but has no public landing route. This Website Dev Guide uses structural-only sections.\n+++\ntitle = \"Docs Authoring Workflow\"\n+++\n\nFor wording, list punctuation, and capitalization conventions, use the [Docs Style Guide](../docs-style-guide/).\n\n## Content Structure Rules\n\nThe docs system is path-derived.\n\n- book landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/_index.md`\n- section landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/_index.md`\n- article page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md`\n\nSection landing pages are optional. A section may be structural only, with no `_index.md` and no `_inherit.md`. This Website Dev Guide uses structural-only sections.\n\n## Example: Add a New Page\n\nSuppose you want a new page under `website-dev-guide/authoring-and-tooling/`.\n\nCreate the content bundle:\n\n```text\nwebsite/content/docs/0.7/website-dev-guide/authoring-and-tooling/new-page/index.md\n```\n\nThen add the page slug to the matching nav section:\n\n```toml\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n  \"new-page\",\n]\n```\n\nWithout the nav update, the page may exist on disk but stay absent from generated navigation.\n\n## Example: Reuse an Older Page without Copying the Content\n\nWhen a newer version should reuse the same page unchanged:\n\n1. create the same page folder in the newer version\n2. add an empty `inherit.md`\n3. keep the corresponding path in an older version with real `index.md` content\n\nExample:\n\n```text\nwebsite/content/docs/0.8/website-dev-guide/site-systems/media-publishing-workflow/inherit.md\n```\n\nDo not put front matter or body content into `inherit.md`.\n\n## Example: Diverge in a Newer Version\n\nIf a newer version needs different content, replace the marker with a real page:\n\n1. remove `inherit.md`\n2. create `index.md`\n3. write the new content for that version\n\nThat keeps the inheritance chain explicit and avoids template-side special cases.\n\n## Navigation Rules\n\nNavigation data controls order, not content. Keep these rules in mind:\n\n- slugs in the nav file must match the folder names on disk\n- changing a slug changes the public URL\n- page titles come from the page's own front matter, not from the nav file\n- section titles come from `docs-nav/\u003cversion\u003e.toml`\n\n## When to Use the Docs Editor Instead of Manual File Edits\n\nManual edits are normal for copy changes inside an existing page.\n\nUse the docs editor when the change is structural, for example:\n\n- creating a new book\n- creating, deleting, or renaming a section\n- creating, deleting, or renaming a page\n- changing docs structure across inherited versions\n\nThe docs editor keeps content paths and nav data in sync and refuses destructive changes that would silently overwrite newer authored content.\n\n## Validation\n\nFor docs and website changes, run:\n\n```bash\ncd website\nnpm run build\n```\n\nThat is the minimum meaningful verification because it runs theme generation, docs validation, inherited-doc materialization, Hugo rendering, and homepage CTA validation.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:website-dev-guide/authoring-and-tooling/docs-style-guide", "parent_id": "section:website-dev-guide/authoring-and-tooling", "depth": 2, "kind": "page", "label": "docs-style-guide", "title": "Docs Style Guide", "path": "website-dev-guide/authoring-and-tooling/docs-style-guide", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Docs Style Guide\"\n+++\n\nUse this page as the canonical copy style reference for published docs.\n\n## Language and Writing Style\n\n- Clarity and readability are paramount.\n- Use simple but correct language.\n- Don't be nitpicky or wordy.\n- Use contracted instead of expanded forms, e.g. `we're` instead of `we are`.\n- Explain (as appropriate) the following:\n  - why things are the way they are\n  - how to use things\n  - when to use things\n\n## Lists\n\n### Sentence Style\n\nUse one list style per list. Do not mix sentence bullets and fragment bullets.\n\n- Sentence lists use complete sentences.\n   - Sentence bullets start with a capital letter and end with a full stop.\n   - After a colon, capitalize the next word when what follows is a sentence.\n- Fragment lists use short labels, file names, commands, paths, shortcuts, or other bare literals.\n   - Fragment bullets preserve literal casing and usually do not take a full stop.\n   - Prefer short, parallel labels for control or feature lists, for example `Zoom`, `Pan`, `Rotate`.\n   - If a fragment needs explanation, rewrite it as a sentence bullet or use a table.\n\nPreferred sentence list:\n\n```markdown\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n```\n\nValid fragment list:\n\n```markdown\n- `config.toml`\n- `website/content/docs/`\n- `Ctrl` + `K`\n```\n\n### List Structure\n\n- Make use of multiple hierarchies to structure content.\n- Mixing ordered and unordered lists is allowed.\n\n### Ordered Lists\n\n- Don't number ordered lists consecutively, use `1.` for all items. Let the Markdown renderer do the numbering.\n\n## Headings\n\n- Use multiple heading levels to logically group and structure content. Don't limit yourself to h2.\n\n## More Information\n\nSee [Docs Authoring Workflow](../docs-authoring-workflow/) for where copy edits fit into the docs workflow, and [Docs Editor Tool](../docs-editor-tool/) for structural docs changes.\n", "0.8": "+++\ntitle = \"Docs Style Guide\"\n+++\n\nUse this page as the canonical copy style reference for published docs.\n\n## Language and Writing Style\n\n- Clarity and readability are paramount.\n- Use simple but correct language.\n- Don't be nitpicky or wordy.\n- Use contracted instead of expanded forms, e.g. `we're` instead of `we are`.\n- Explain (as appropriate) the following:\n  - why things are the way they are\n  - how to use things\n  - when to use things\n\n## Lists\n\n### Sentence Style\n\nUse one list style per list. Do not mix sentence bullets and fragment bullets.\n\n- Sentence lists use complete sentences.\n   - Sentence bullets start with a capital letter and end with a full stop.\n   - After a colon, capitalize the next word when what follows is a sentence.\n- Fragment lists use short labels, file names, commands, paths, shortcuts, or other bare literals.\n   - Fragment bullets preserve literal casing and usually do not take a full stop.\n   - Prefer short, parallel labels for control or feature lists, for example `Zoom`, `Pan`, `Rotate`.\n   - If a fragment needs explanation, rewrite it as a sentence bullet or use a table.\n\nPreferred sentence list:\n\n```markdown\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n```\n\nValid fragment list:\n\n```markdown\n- `config.toml`\n- `website/content/docs/`\n- `Ctrl` + `K`\n```\n\n### List Structure\n\n- Make use of multiple hierarchies to structure content.\n- Mixing ordered and unordered lists is allowed.\n\n### Ordered Lists\n\n- Don't number ordered lists consecutively, use `1.` for all items. Let the Markdown renderer do the numbering.\n\n## Headings\n\n- Use multiple heading levels to logically group and structure content. Don't limit yourself to h2.\n\n## More Information\n\nSee [Docs Authoring Workflow](../docs-authoring-workflow/) for where copy edits fit into the docs workflow, and [Docs Editor Tool](../docs-editor-tool/) for structural docs changes.\n", "0.9": "+++\ntitle = \"Docs Style Guide\"\n+++\n\nUse this page as the canonical copy style reference for published docs.\n\n## Language and Writing Style\n\n- Clarity and readability are paramount.\n- Use simple but correct language.\n- Don't be nitpicky or wordy.\n- Use contracted instead of expanded forms, e.g. `we're` instead of `we are`.\n- Explain (as appropriate) the following:\n  - why things are the way they are\n  - how to use things\n  - when to use things\n\n## Lists\n\n### Sentence Style\n\nUse one list style per list. Do not mix sentence bullets and fragment bullets.\n\n- Sentence lists use complete sentences.\n   - Sentence bullets start with a capital letter and end with a full stop.\n   - After a colon, capitalize the next word when what follows is a sentence.\n- Fragment lists use short labels, file names, commands, paths, shortcuts, or other bare literals.\n   - Fragment bullets preserve literal casing and usually do not take a full stop.\n   - Prefer short, parallel labels for control or feature lists, for example `Zoom`, `Pan`, `Rotate`.\n   - If a fragment needs explanation, rewrite it as a sentence bullet or use a table.\n\nPreferred sentence list:\n\n```markdown\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n```\n\nValid fragment list:\n\n```markdown\n- `config.toml`\n- `website/content/docs/`\n- `Ctrl` + `K`\n```\n\n### List Structure\n\n- Make use of multiple hierarchies to structure content.\n- Mixing ordered and unordered lists is allowed.\n\n### Ordered Lists\n\n- Don't number ordered lists consecutively, use `1.` for all items. Let the Markdown renderer do the numbering.\n\n## Headings\n\n- Use multiple heading levels to logically group and structure content. Don't limit yourself to h2.\n\n## More Information\n\nSee [Docs Authoring Workflow](../docs-authoring-workflow/) for where copy edits fit into the docs workflow, and [Docs Editor Tool](../docs-editor-tool/) for structural docs changes.\n", "1.0": "+++\ntitle = \"Docs Style Guide\"\n+++\n\nUse this page as the canonical copy style reference for published docs.\n\n## Language and Writing Style\n\n- Clarity and readability are paramount.\n- Use simple but correct language.\n- Don't be nitpicky or wordy.\n- Use contracted instead of expanded forms, e.g. `we're` instead of `we are`.\n- Explain (as appropriate) the following:\n  - why things are the way they are\n  - how to use things\n  - when to use things\n\n## Lists\n\n### Sentence Style\n\nUse one list style per list. Do not mix sentence bullets and fragment bullets.\n\n- Sentence lists use complete sentences.\n   - Sentence bullets start with a capital letter and end with a full stop.\n   - After a colon, capitalize the next word when what follows is a sentence.\n- Fragment lists use short labels, file names, commands, paths, shortcuts, or other bare literals.\n   - Fragment bullets preserve literal casing and usually do not take a full stop.\n   - Prefer short, parallel labels for control or feature lists, for example `Zoom`, `Pan`, `Rotate`.\n   - If a fragment needs explanation, rewrite it as a sentence bullet or use a table.\n\nPreferred sentence list:\n\n```markdown\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n```\n\nValid fragment list:\n\n```markdown\n- `config.toml`\n- `website/content/docs/`\n- `Ctrl` + `K`\n```\n\n### List Structure\n\n- Make use of multiple hierarchies to structure content.\n- Mixing ordered and unordered lists is allowed.\n\n### Ordered Lists\n\n- Don't number ordered lists consecutively, use `1.` for all items. Let the Markdown renderer do the numbering.\n\n## Headings\n\n- Use multiple heading levels to logically group and structure content. Don't limit yourself to h2.\n\n## More Information\n\nSee [Docs Authoring Workflow](../docs-authoring-workflow/) for where copy edits fit into the docs workflow, and [Docs Editor Tool](../docs-editor-tool/) for structural docs changes.\n", "2.0": "+++\ntitle = \"Docs Style Guide\"\n+++\n\nUse this page as the canonical copy style reference for published docs.\n\n## Language and Writing Style\n\n- Clarity and readability are paramount.\n- Use simple but correct language.\n- Don't be nitpicky or wordy.\n- Use contracted instead of expanded forms, e.g. `we're` instead of `we are`.\n- Explain (as appropriate) the following:\n  - why things are the way they are\n  - how to use things\n  - when to use things\n\n## Lists\n\n### Sentence Style\n\nUse one list style per list. Do not mix sentence bullets and fragment bullets.\n\n- Sentence lists use complete sentences.\n   - Sentence bullets start with a capital letter and end with a full stop.\n   - After a colon, capitalize the next word when what follows is a sentence.\n- Fragment lists use short labels, file names, commands, paths, shortcuts, or other bare literals.\n   - Fragment bullets preserve literal casing and usually do not take a full stop.\n   - Prefer short, parallel labels for control or feature lists, for example `Zoom`, `Pan`, `Rotate`.\n   - If a fragment needs explanation, rewrite it as a sentence bullet or use a table.\n\nPreferred sentence list:\n\n```markdown\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n```\n\nValid fragment list:\n\n```markdown\n- `config.toml`\n- `website/content/docs/`\n- `Ctrl` + `K`\n```\n\n### List Structure\n\n- Make use of multiple hierarchies to structure content.\n- Mixing ordered and unordered lists is allowed.\n\n### Ordered Lists\n\n- Don't number ordered lists consecutively, use `1.` for all items. Let the Markdown renderer do the numbering.\n\n## Headings\n\n- Use multiple heading levels to logically group and structure content. Don't limit yourself to h2.\n\n## More Information\n\nSee [Docs Authoring Workflow](../docs-authoring-workflow/) for where copy edits fit into the docs workflow, and [Docs Editor Tool](../docs-editor-tool/) for structural docs changes.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Docs Style Guide\"\n+++\n\nUse this page as the canonical copy style reference for published docs.\n\n## Language and Writing Style\n\n- Clarity and readability are paramount.\n- Use simple but correct language.\n- Don't be nitpicky or wordy.\n- Use contracted instead of expanded forms, e.g. `we're` instead of `we are`.\n- Explain (as appropriate) the following:\n  - why things are the way they are\n  - how to use things\n  - when to use things\n\n## Lists\n\n### Sentence Style\n\nUse one list style per list. Do not mix sentence bullets and fragment bullets.\n\n- Sentence lists use complete sentences.\n   - Sentence bullets start with a capital letter and end with a full stop.\n   - After a colon, capitalize the next word when what follows is a sentence.\n- Fragment lists use short labels, file names, commands, paths, shortcuts, or other bare literals.\n   - Fragment bullets preserve literal casing and usually do not take a full stop.\n   - Prefer short, parallel labels for control or feature lists, for example `Zoom`, `Pan`, `Rotate`.\n   - If a fragment needs explanation, rewrite it as a sentence bullet or use a table.\n\nPreferred sentence list:\n\n```markdown\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n```\n\nValid fragment list:\n\n```markdown\n- `config.toml`\n- `website/content/docs/`\n- `Ctrl` + `K`\n```\n\n### List Structure\n\n- Make use of multiple hierarchies to structure content.\n- Mixing ordered and unordered lists is allowed.\n\n### Ordered Lists\n\n- Don't number ordered lists consecutively, use `1.` for all items. Let the Markdown renderer do the numbering.\n\n## Headings\n\n- Use multiple heading levels to logically group and structure content. Don't limit yourself to h2.\n\n## More Information\n\nSee [Docs Authoring Workflow](../docs-authoring-workflow/) for where copy edits fit into the docs workflow, and [Docs Editor Tool](../docs-editor-tool/) for structural docs changes.\n", "0.8": "+++\ntitle = \"Docs Style Guide\"\n+++\n\nUse this page as the canonical copy style reference for published docs.\n\n## Language and Writing Style\n\n- Clarity and readability are paramount.\n- Use simple but correct language.\n- Don't be nitpicky or wordy.\n- Use contracted instead of expanded forms, e.g. `we're` instead of `we are`.\n- Explain (as appropriate) the following:\n  - why things are the way they are\n  - how to use things\n  - when to use things\n\n## Lists\n\n### Sentence Style\n\nUse one list style per list. Do not mix sentence bullets and fragment bullets.\n\n- Sentence lists use complete sentences.\n   - Sentence bullets start with a capital letter and end with a full stop.\n   - After a colon, capitalize the next word when what follows is a sentence.\n- Fragment lists use short labels, file names, commands, paths, shortcuts, or other bare literals.\n   - Fragment bullets preserve literal casing and usually do not take a full stop.\n   - Prefer short, parallel labels for control or feature lists, for example `Zoom`, `Pan`, `Rotate`.\n   - If a fragment needs explanation, rewrite it as a sentence bullet or use a table.\n\nPreferred sentence list:\n\n```markdown\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n```\n\nValid fragment list:\n\n```markdown\n- `config.toml`\n- `website/content/docs/`\n- `Ctrl` + `K`\n```\n\n### List Structure\n\n- Make use of multiple hierarchies to structure content.\n- Mixing ordered and unordered lists is allowed.\n\n### Ordered Lists\n\n- Don't number ordered lists consecutively, use `1.` for all items. Let the Markdown renderer do the numbering.\n\n## Headings\n\n- Use multiple heading levels to logically group and structure content. Don't limit yourself to h2.\n\n## More Information\n\nSee [Docs Authoring Workflow](../docs-authoring-workflow/) for where copy edits fit into the docs workflow, and [Docs Editor Tool](../docs-editor-tool/) for structural docs changes.\n", "0.9": "+++\ntitle = \"Docs Style Guide\"\n+++\n\nUse this page as the canonical copy style reference for published docs.\n\n## Language and Writing Style\n\n- Clarity and readability are paramount.\n- Use simple but correct language.\n- Don't be nitpicky or wordy.\n- Use contracted instead of expanded forms, e.g. `we're` instead of `we are`.\n- Explain (as appropriate) the following:\n  - why things are the way they are\n  - how to use things\n  - when to use things\n\n## Lists\n\n### Sentence Style\n\nUse one list style per list. Do not mix sentence bullets and fragment bullets.\n\n- Sentence lists use complete sentences.\n   - Sentence bullets start with a capital letter and end with a full stop.\n   - After a colon, capitalize the next word when what follows is a sentence.\n- Fragment lists use short labels, file names, commands, paths, shortcuts, or other bare literals.\n   - Fragment bullets preserve literal casing and usually do not take a full stop.\n   - Prefer short, parallel labels for control or feature lists, for example `Zoom`, `Pan`, `Rotate`.\n   - If a fragment needs explanation, rewrite it as a sentence bullet or use a table.\n\nPreferred sentence list:\n\n```markdown\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n```\n\nValid fragment list:\n\n```markdown\n- `config.toml`\n- `website/content/docs/`\n- `Ctrl` + `K`\n```\n\n### List Structure\n\n- Make use of multiple hierarchies to structure content.\n- Mixing ordered and unordered lists is allowed.\n\n### Ordered Lists\n\n- Don't number ordered lists consecutively, use `1.` for all items. Let the Markdown renderer do the numbering.\n\n## Headings\n\n- Use multiple heading levels to logically group and structure content. Don't limit yourself to h2.\n\n## More Information\n\nSee [Docs Authoring Workflow](../docs-authoring-workflow/) for where copy edits fit into the docs workflow, and [Docs Editor Tool](../docs-editor-tool/) for structural docs changes.\n", "1.0": "+++\ntitle = \"Docs Style Guide\"\n+++\n\nUse this page as the canonical copy style reference for published docs.\n\n## Language and Writing Style\n\n- Clarity and readability are paramount.\n- Use simple but correct language.\n- Don't be nitpicky or wordy.\n- Use contracted instead of expanded forms, e.g. `we're` instead of `we are`.\n- Explain (as appropriate) the following:\n  - why things are the way they are\n  - how to use things\n  - when to use things\n\n## Lists\n\n### Sentence Style\n\nUse one list style per list. Do not mix sentence bullets and fragment bullets.\n\n- Sentence lists use complete sentences.\n   - Sentence bullets start with a capital letter and end with a full stop.\n   - After a colon, capitalize the next word when what follows is a sentence.\n- Fragment lists use short labels, file names, commands, paths, shortcuts, or other bare literals.\n   - Fragment bullets preserve literal casing and usually do not take a full stop.\n   - Prefer short, parallel labels for control or feature lists, for example `Zoom`, `Pan`, `Rotate`.\n   - If a fragment needs explanation, rewrite it as a sentence bullet or use a table.\n\nPreferred sentence list:\n\n```markdown\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n```\n\nValid fragment list:\n\n```markdown\n- `config.toml`\n- `website/content/docs/`\n- `Ctrl` + `K`\n```\n\n### List Structure\n\n- Make use of multiple hierarchies to structure content.\n- Mixing ordered and unordered lists is allowed.\n\n### Ordered Lists\n\n- Don't number ordered lists consecutively, use `1.` for all items. Let the Markdown renderer do the numbering.\n\n## Headings\n\n- Use multiple heading levels to logically group and structure content. Don't limit yourself to h2.\n\n## More Information\n\nSee [Docs Authoring Workflow](../docs-authoring-workflow/) for where copy edits fit into the docs workflow, and [Docs Editor Tool](../docs-editor-tool/) for structural docs changes.\n", "2.0": "+++\ntitle = \"Docs Style Guide\"\n+++\n\nUse this page as the canonical copy style reference for published docs.\n\n## Language and Writing Style\n\n- Clarity and readability are paramount.\n- Use simple but correct language.\n- Don't be nitpicky or wordy.\n- Use contracted instead of expanded forms, e.g. `we're` instead of `we are`.\n- Explain (as appropriate) the following:\n  - why things are the way they are\n  - how to use things\n  - when to use things\n\n## Lists\n\n### Sentence Style\n\nUse one list style per list. Do not mix sentence bullets and fragment bullets.\n\n- Sentence lists use complete sentences.\n   - Sentence bullets start with a capital letter and end with a full stop.\n   - After a colon, capitalize the next word when what follows is a sentence.\n- Fragment lists use short labels, file names, commands, paths, shortcuts, or other bare literals.\n   - Fragment bullets preserve literal casing and usually do not take a full stop.\n   - Prefer short, parallel labels for control or feature lists, for example `Zoom`, `Pan`, `Rotate`.\n   - If a fragment needs explanation, rewrite it as a sentence bullet or use a table.\n\nPreferred sentence list:\n\n```markdown\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n```\n\nValid fragment list:\n\n```markdown\n- `config.toml`\n- `website/content/docs/`\n- `Ctrl` + `K`\n```\n\n### List Structure\n\n- Make use of multiple hierarchies to structure content.\n- Mixing ordered and unordered lists is allowed.\n\n### Ordered Lists\n\n- Don't number ordered lists consecutively, use `1.` for all items. Let the Markdown renderer do the numbering.\n\n## Headings\n\n- Use multiple heading levels to logically group and structure content. Don't limit yourself to h2.\n\n## More Information\n\nSee [Docs Authoring Workflow](../docs-authoring-workflow/) for where copy edits fit into the docs workflow, and [Docs Editor Tool](../docs-editor-tool/) for structural docs changes.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:website-dev-guide/authoring-and-tooling/docs-shortcodes", "parent_id": "section:website-dev-guide/authoring-and-tooling", "depth": 2, "kind": "page", "label": "docs-shortcodes", "title": "Docs Shortcodes", "path": "website-dev-guide/authoring-and-tooling/docs-shortcodes", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Docs Shortcodes\"\n+++\n\nUse this page when you need a docs-only Hugo shortcode in published documentation content.\n\n## Current Shortcodes\n\nThe website currently exposes one docs shortcode for normal content authors:\n\n- `admonition`: render a styled callout block for notes, tips, warnings, and similar emphasis\n\n## Admonition Shortcode\n\nUse the `admonition` shortcode for highlighted callout content inside a docs page.\n\nBasic form:\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Info\" */\u003e}}\nThis is an informational callout.\n{{\u003c/* /admonition */\u003e}}\n```\n\nThe body is rendered as normal Markdown, so links, emphasis, lists, and other inline formatting work inside the block.\n\n### Supported Types\n\nThe shortcode supports these `type` values:\n\n- `note`\n- `tip`\n- `info`\n- `warning`\n- `danger`\n\nIf `type` is omitted or invalid, it defaults to `note`.\n\n### Title Behavior\n\nThe `title` parameter is optional.\n\n- If you provide a non-empty title, the admonition renders a title line.\n- If you omit `title`, no title line is rendered.\n\n### Examples\n\n#### Note Callout\n\n```md\n{{\u003c/* admonition type=\"note\" */\u003e}}\nThis is a note without a title.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"note\" \u003e}}\nThis is a note without a title.\n{{\u003c /admonition \u003e}}\n\n#### Tip Callout\n\n```md\n{{\u003c/* admonition type=\"tip\" title=\"Tip\" */\u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"tip\" title=\"Tip\" \u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c /admonition \u003e}}\n\n#### Informational Callout\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Background\" */\u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"info\" title=\"Background\" \u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c /admonition \u003e}}\n\n#### Warning Callout\n\n```md\n{{\u003c/* admonition type=\"warning\" title=\"Do Not Edit Marker Files\" */\u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"warning\" title=\"Do Not Edit Marker Files\" \u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c /admonition \u003e}}\n\n#### Danger Callout\n\n```md\n{{\u003c/* admonition type=\"danger\" title=\"Destructive Change\" */\u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"danger\" title=\"Destructive Change\" \u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c /admonition \u003e}}\n\n### Implementation Reference\n\nThe shortcode implementation lives in `themes/sambee/layouts/shortcodes/admonition.html`.\n\nThe styling for the rendered admonition variants lives in `themes/sambee/assets/css/content.css`.\n", "0.8": "+++\ntitle = \"Docs Shortcodes\"\n+++\n\nUse this page when you need a docs-only Hugo shortcode in published documentation content.\n\n## Current Shortcodes\n\nThe website currently exposes one docs shortcode for normal content authors:\n\n- `admonition`: render a styled callout block for notes, tips, warnings, and similar emphasis\n\n## Admonition Shortcode\n\nUse the `admonition` shortcode for highlighted callout content inside a docs page.\n\nBasic form:\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Info\" */\u003e}}\nThis is an informational callout.\n{{\u003c/* /admonition */\u003e}}\n```\n\nThe body is rendered as normal Markdown, so links, emphasis, lists, and other inline formatting work inside the block.\n\n### Supported Types\n\nThe shortcode supports these `type` values:\n\n- `note`\n- `tip`\n- `info`\n- `warning`\n- `danger`\n\nIf `type` is omitted or invalid, it defaults to `note`.\n\n### Title Behavior\n\nThe `title` parameter is optional.\n\n- If you provide a non-empty title, the admonition renders a title line.\n- If you omit `title`, no title line is rendered.\n\n### Examples\n\n#### Note Callout\n\n```md\n{{\u003c/* admonition type=\"note\" */\u003e}}\nThis is a note without a title.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"note\" \u003e}}\nThis is a note without a title.\n{{\u003c /admonition \u003e}}\n\n#### Tip Callout\n\n```md\n{{\u003c/* admonition type=\"tip\" title=\"Tip\" */\u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"tip\" title=\"Tip\" \u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c /admonition \u003e}}\n\n#### Informational Callout\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Background\" */\u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"info\" title=\"Background\" \u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c /admonition \u003e}}\n\n#### Warning Callout\n\n```md\n{{\u003c/* admonition type=\"warning\" title=\"Do Not Edit Marker Files\" */\u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"warning\" title=\"Do Not Edit Marker Files\" \u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c /admonition \u003e}}\n\n#### Danger Callout\n\n```md\n{{\u003c/* admonition type=\"danger\" title=\"Destructive Change\" */\u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"danger\" title=\"Destructive Change\" \u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c /admonition \u003e}}\n\n### Implementation Reference\n\nThe shortcode implementation lives in `themes/sambee/layouts/shortcodes/admonition.html`.\n\nThe styling for the rendered admonition variants lives in `themes/sambee/assets/css/content.css`.\n", "0.9": "+++\ntitle = \"Docs Shortcodes\"\n+++\n\nUse this page when you need a docs-only Hugo shortcode in published documentation content.\n\n## Current Shortcodes\n\nThe website currently exposes one docs shortcode for normal content authors:\n\n- `admonition`: render a styled callout block for notes, tips, warnings, and similar emphasis\n\n## Admonition Shortcode\n\nUse the `admonition` shortcode for highlighted callout content inside a docs page.\n\nBasic form:\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Info\" */\u003e}}\nThis is an informational callout.\n{{\u003c/* /admonition */\u003e}}\n```\n\nThe body is rendered as normal Markdown, so links, emphasis, lists, and other inline formatting work inside the block.\n\n### Supported Types\n\nThe shortcode supports these `type` values:\n\n- `note`\n- `tip`\n- `info`\n- `warning`\n- `danger`\n\nIf `type` is omitted or invalid, it defaults to `note`.\n\n### Title Behavior\n\nThe `title` parameter is optional.\n\n- If you provide a non-empty title, the admonition renders a title line.\n- If you omit `title`, no title line is rendered.\n\n### Examples\n\n#### Note Callout\n\n```md\n{{\u003c/* admonition type=\"note\" */\u003e}}\nThis is a note without a title.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"note\" \u003e}}\nThis is a note without a title.\n{{\u003c /admonition \u003e}}\n\n#### Tip Callout\n\n```md\n{{\u003c/* admonition type=\"tip\" title=\"Tip\" */\u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"tip\" title=\"Tip\" \u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c /admonition \u003e}}\n\n#### Informational Callout\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Background\" */\u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"info\" title=\"Background\" \u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c /admonition \u003e}}\n\n#### Warning Callout\n\n```md\n{{\u003c/* admonition type=\"warning\" title=\"Do Not Edit Marker Files\" */\u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"warning\" title=\"Do Not Edit Marker Files\" \u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c /admonition \u003e}}\n\n#### Danger Callout\n\n```md\n{{\u003c/* admonition type=\"danger\" title=\"Destructive Change\" */\u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"danger\" title=\"Destructive Change\" \u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c /admonition \u003e}}\n\n### Implementation Reference\n\nThe shortcode implementation lives in `themes/sambee/layouts/shortcodes/admonition.html`.\n\nThe styling for the rendered admonition variants lives in `themes/sambee/assets/css/content.css`.\n", "1.0": "+++\ntitle = \"Docs Shortcodes\"\n+++\n\nUse this page when you need a docs-only Hugo shortcode in published documentation content.\n\n## Current Shortcodes\n\nThe website currently exposes one docs shortcode for normal content authors:\n\n- `admonition`: render a styled callout block for notes, tips, warnings, and similar emphasis\n\n## Admonition Shortcode\n\nUse the `admonition` shortcode for highlighted callout content inside a docs page.\n\nBasic form:\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Info\" */\u003e}}\nThis is an informational callout.\n{{\u003c/* /admonition */\u003e}}\n```\n\nThe body is rendered as normal Markdown, so links, emphasis, lists, and other inline formatting work inside the block.\n\n### Supported Types\n\nThe shortcode supports these `type` values:\n\n- `note`\n- `tip`\n- `info`\n- `warning`\n- `danger`\n\nIf `type` is omitted or invalid, it defaults to `note`.\n\n### Title Behavior\n\nThe `title` parameter is optional.\n\n- If you provide a non-empty title, the admonition renders a title line.\n- If you omit `title`, no title line is rendered.\n\n### Examples\n\n#### Note Callout\n\n```md\n{{\u003c/* admonition type=\"note\" */\u003e}}\nThis is a note without a title.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"note\" \u003e}}\nThis is a note without a title.\n{{\u003c /admonition \u003e}}\n\n#### Tip Callout\n\n```md\n{{\u003c/* admonition type=\"tip\" title=\"Tip\" */\u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"tip\" title=\"Tip\" \u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c /admonition \u003e}}\n\n#### Informational Callout\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Background\" */\u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"info\" title=\"Background\" \u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c /admonition \u003e}}\n\n#### Warning Callout\n\n```md\n{{\u003c/* admonition type=\"warning\" title=\"Do Not Edit Marker Files\" */\u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"warning\" title=\"Do Not Edit Marker Files\" \u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c /admonition \u003e}}\n\n#### Danger Callout\n\n```md\n{{\u003c/* admonition type=\"danger\" title=\"Destructive Change\" */\u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"danger\" title=\"Destructive Change\" \u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c /admonition \u003e}}\n\n### Implementation Reference\n\nThe shortcode implementation lives in `themes/sambee/layouts/shortcodes/admonition.html`.\n\nThe styling for the rendered admonition variants lives in `themes/sambee/assets/css/content.css`.\n", "2.0": "+++\ntitle = \"Docs Shortcodes\"\n+++\n\nUse this page when you need a docs-only Hugo shortcode in published documentation content.\n\n## Current Shortcodes\n\nThe website currently exposes one docs shortcode for normal content authors:\n\n- `admonition`: render a styled callout block for notes, tips, warnings, and similar emphasis\n\n## Admonition Shortcode\n\nUse the `admonition` shortcode for highlighted callout content inside a docs page.\n\nBasic form:\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Info\" */\u003e}}\nThis is an informational callout.\n{{\u003c/* /admonition */\u003e}}\n```\n\nThe body is rendered as normal Markdown, so links, emphasis, lists, and other inline formatting work inside the block.\n\n### Supported Types\n\nThe shortcode supports these `type` values:\n\n- `note`\n- `tip`\n- `info`\n- `warning`\n- `danger`\n\nIf `type` is omitted or invalid, it defaults to `note`.\n\n### Title Behavior\n\nThe `title` parameter is optional.\n\n- If you provide a non-empty title, the admonition renders a title line.\n- If you omit `title`, no title line is rendered.\n\n### Examples\n\n#### Note Callout\n\n```md\n{{\u003c/* admonition type=\"note\" */\u003e}}\nThis is a note without a title.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"note\" \u003e}}\nThis is a note without a title.\n{{\u003c /admonition \u003e}}\n\n#### Tip Callout\n\n```md\n{{\u003c/* admonition type=\"tip\" title=\"Tip\" */\u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"tip\" title=\"Tip\" \u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c /admonition \u003e}}\n\n#### Informational Callout\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Background\" */\u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"info\" title=\"Background\" \u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c /admonition \u003e}}\n\n#### Warning Callout\n\n```md\n{{\u003c/* admonition type=\"warning\" title=\"Do Not Edit Marker Files\" */\u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"warning\" title=\"Do Not Edit Marker Files\" \u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c /admonition \u003e}}\n\n#### Danger Callout\n\n```md\n{{\u003c/* admonition type=\"danger\" title=\"Destructive Change\" */\u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"danger\" title=\"Destructive Change\" \u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c /admonition \u003e}}\n\n### Implementation Reference\n\nThe shortcode implementation lives in `themes/sambee/layouts/shortcodes/admonition.html`.\n\nThe styling for the rendered admonition variants lives in `themes/sambee/assets/css/content.css`.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Docs Shortcodes\"\n+++\n\nUse this page when you need a docs-only Hugo shortcode in published documentation content.\n\n## Current Shortcodes\n\nThe website currently exposes one docs shortcode for normal content authors:\n\n- `admonition`: render a styled callout block for notes, tips, warnings, and similar emphasis\n\n## Admonition Shortcode\n\nUse the `admonition` shortcode for highlighted callout content inside a docs page.\n\nBasic form:\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Info\" */\u003e}}\nThis is an informational callout.\n{{\u003c/* /admonition */\u003e}}\n```\n\nThe body is rendered as normal Markdown, so links, emphasis, lists, and other inline formatting work inside the block.\n\n### Supported Types\n\nThe shortcode supports these `type` values:\n\n- `note`\n- `tip`\n- `info`\n- `warning`\n- `danger`\n\nIf `type` is omitted or invalid, it defaults to `note`.\n\n### Title Behavior\n\nThe `title` parameter is optional.\n\n- If you provide a non-empty title, the admonition renders a title line.\n- If you omit `title`, no title line is rendered.\n\n### Examples\n\n#### Note Callout\n\n```md\n{{\u003c/* admonition type=\"note\" */\u003e}}\nThis is a note without a title.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"note\" \u003e}}\nThis is a note without a title.\n{{\u003c /admonition \u003e}}\n\n#### Tip Callout\n\n```md\n{{\u003c/* admonition type=\"tip\" title=\"Tip\" */\u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"tip\" title=\"Tip\" \u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c /admonition \u003e}}\n\n#### Informational Callout\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Background\" */\u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"info\" title=\"Background\" \u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c /admonition \u003e}}\n\n#### Warning Callout\n\n```md\n{{\u003c/* admonition type=\"warning\" title=\"Do Not Edit Marker Files\" */\u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"warning\" title=\"Do Not Edit Marker Files\" \u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c /admonition \u003e}}\n\n#### Danger Callout\n\n```md\n{{\u003c/* admonition type=\"danger\" title=\"Destructive Change\" */\u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"danger\" title=\"Destructive Change\" \u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c /admonition \u003e}}\n\n### Implementation Reference\n\nThe shortcode implementation lives in `themes/sambee/layouts/shortcodes/admonition.html`.\n\nThe styling for the rendered admonition variants lives in `themes/sambee/assets/css/content.css`.\n", "0.8": "+++\ntitle = \"Docs Shortcodes\"\n+++\n\nUse this page when you need a docs-only Hugo shortcode in published documentation content.\n\n## Current Shortcodes\n\nThe website currently exposes one docs shortcode for normal content authors:\n\n- `admonition`: render a styled callout block for notes, tips, warnings, and similar emphasis\n\n## Admonition Shortcode\n\nUse the `admonition` shortcode for highlighted callout content inside a docs page.\n\nBasic form:\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Info\" */\u003e}}\nThis is an informational callout.\n{{\u003c/* /admonition */\u003e}}\n```\n\nThe body is rendered as normal Markdown, so links, emphasis, lists, and other inline formatting work inside the block.\n\n### Supported Types\n\nThe shortcode supports these `type` values:\n\n- `note`\n- `tip`\n- `info`\n- `warning`\n- `danger`\n\nIf `type` is omitted or invalid, it defaults to `note`.\n\n### Title Behavior\n\nThe `title` parameter is optional.\n\n- If you provide a non-empty title, the admonition renders a title line.\n- If you omit `title`, no title line is rendered.\n\n### Examples\n\n#### Note Callout\n\n```md\n{{\u003c/* admonition type=\"note\" */\u003e}}\nThis is a note without a title.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"note\" \u003e}}\nThis is a note without a title.\n{{\u003c /admonition \u003e}}\n\n#### Tip Callout\n\n```md\n{{\u003c/* admonition type=\"tip\" title=\"Tip\" */\u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"tip\" title=\"Tip\" \u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c /admonition \u003e}}\n\n#### Informational Callout\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Background\" */\u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"info\" title=\"Background\" \u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c /admonition \u003e}}\n\n#### Warning Callout\n\n```md\n{{\u003c/* admonition type=\"warning\" title=\"Do Not Edit Marker Files\" */\u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"warning\" title=\"Do Not Edit Marker Files\" \u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c /admonition \u003e}}\n\n#### Danger Callout\n\n```md\n{{\u003c/* admonition type=\"danger\" title=\"Destructive Change\" */\u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"danger\" title=\"Destructive Change\" \u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c /admonition \u003e}}\n\n### Implementation Reference\n\nThe shortcode implementation lives in `themes/sambee/layouts/shortcodes/admonition.html`.\n\nThe styling for the rendered admonition variants lives in `themes/sambee/assets/css/content.css`.\n", "0.9": "+++\ntitle = \"Docs Shortcodes\"\n+++\n\nUse this page when you need a docs-only Hugo shortcode in published documentation content.\n\n## Current Shortcodes\n\nThe website currently exposes one docs shortcode for normal content authors:\n\n- `admonition`: render a styled callout block for notes, tips, warnings, and similar emphasis\n\n## Admonition Shortcode\n\nUse the `admonition` shortcode for highlighted callout content inside a docs page.\n\nBasic form:\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Info\" */\u003e}}\nThis is an informational callout.\n{{\u003c/* /admonition */\u003e}}\n```\n\nThe body is rendered as normal Markdown, so links, emphasis, lists, and other inline formatting work inside the block.\n\n### Supported Types\n\nThe shortcode supports these `type` values:\n\n- `note`\n- `tip`\n- `info`\n- `warning`\n- `danger`\n\nIf `type` is omitted or invalid, it defaults to `note`.\n\n### Title Behavior\n\nThe `title` parameter is optional.\n\n- If you provide a non-empty title, the admonition renders a title line.\n- If you omit `title`, no title line is rendered.\n\n### Examples\n\n#### Note Callout\n\n```md\n{{\u003c/* admonition type=\"note\" */\u003e}}\nThis is a note without a title.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"note\" \u003e}}\nThis is a note without a title.\n{{\u003c /admonition \u003e}}\n\n#### Tip Callout\n\n```md\n{{\u003c/* admonition type=\"tip\" title=\"Tip\" */\u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"tip\" title=\"Tip\" \u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c /admonition \u003e}}\n\n#### Informational Callout\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Background\" */\u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"info\" title=\"Background\" \u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c /admonition \u003e}}\n\n#### Warning Callout\n\n```md\n{{\u003c/* admonition type=\"warning\" title=\"Do Not Edit Marker Files\" */\u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"warning\" title=\"Do Not Edit Marker Files\" \u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c /admonition \u003e}}\n\n#### Danger Callout\n\n```md\n{{\u003c/* admonition type=\"danger\" title=\"Destructive Change\" */\u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"danger\" title=\"Destructive Change\" \u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c /admonition \u003e}}\n\n### Implementation Reference\n\nThe shortcode implementation lives in `themes/sambee/layouts/shortcodes/admonition.html`.\n\nThe styling for the rendered admonition variants lives in `themes/sambee/assets/css/content.css`.\n", "1.0": "+++\ntitle = \"Docs Shortcodes\"\n+++\n\nUse this page when you need a docs-only Hugo shortcode in published documentation content.\n\n## Current Shortcodes\n\nThe website currently exposes one docs shortcode for normal content authors:\n\n- `admonition`: render a styled callout block for notes, tips, warnings, and similar emphasis\n\n## Admonition Shortcode\n\nUse the `admonition` shortcode for highlighted callout content inside a docs page.\n\nBasic form:\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Info\" */\u003e}}\nThis is an informational callout.\n{{\u003c/* /admonition */\u003e}}\n```\n\nThe body is rendered as normal Markdown, so links, emphasis, lists, and other inline formatting work inside the block.\n\n### Supported Types\n\nThe shortcode supports these `type` values:\n\n- `note`\n- `tip`\n- `info`\n- `warning`\n- `danger`\n\nIf `type` is omitted or invalid, it defaults to `note`.\n\n### Title Behavior\n\nThe `title` parameter is optional.\n\n- If you provide a non-empty title, the admonition renders a title line.\n- If you omit `title`, no title line is rendered.\n\n### Examples\n\n#### Note Callout\n\n```md\n{{\u003c/* admonition type=\"note\" */\u003e}}\nThis is a note without a title.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"note\" \u003e}}\nThis is a note without a title.\n{{\u003c /admonition \u003e}}\n\n#### Tip Callout\n\n```md\n{{\u003c/* admonition type=\"tip\" title=\"Tip\" */\u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"tip\" title=\"Tip\" \u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c /admonition \u003e}}\n\n#### Informational Callout\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Background\" */\u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"info\" title=\"Background\" \u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c /admonition \u003e}}\n\n#### Warning Callout\n\n```md\n{{\u003c/* admonition type=\"warning\" title=\"Do Not Edit Marker Files\" */\u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"warning\" title=\"Do Not Edit Marker Files\" \u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c /admonition \u003e}}\n\n#### Danger Callout\n\n```md\n{{\u003c/* admonition type=\"danger\" title=\"Destructive Change\" */\u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"danger\" title=\"Destructive Change\" \u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c /admonition \u003e}}\n\n### Implementation Reference\n\nThe shortcode implementation lives in `themes/sambee/layouts/shortcodes/admonition.html`.\n\nThe styling for the rendered admonition variants lives in `themes/sambee/assets/css/content.css`.\n", "2.0": "+++\ntitle = \"Docs Shortcodes\"\n+++\n\nUse this page when you need a docs-only Hugo shortcode in published documentation content.\n\n## Current Shortcodes\n\nThe website currently exposes one docs shortcode for normal content authors:\n\n- `admonition`: render a styled callout block for notes, tips, warnings, and similar emphasis\n\n## Admonition Shortcode\n\nUse the `admonition` shortcode for highlighted callout content inside a docs page.\n\nBasic form:\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Info\" */\u003e}}\nThis is an informational callout.\n{{\u003c/* /admonition */\u003e}}\n```\n\nThe body is rendered as normal Markdown, so links, emphasis, lists, and other inline formatting work inside the block.\n\n### Supported Types\n\nThe shortcode supports these `type` values:\n\n- `note`\n- `tip`\n- `info`\n- `warning`\n- `danger`\n\nIf `type` is omitted or invalid, it defaults to `note`.\n\n### Title Behavior\n\nThe `title` parameter is optional.\n\n- If you provide a non-empty title, the admonition renders a title line.\n- If you omit `title`, no title line is rendered.\n\n### Examples\n\n#### Note Callout\n\n```md\n{{\u003c/* admonition type=\"note\" */\u003e}}\nThis is a note without a title.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"note\" \u003e}}\nThis is a note without a title.\n{{\u003c /admonition \u003e}}\n\n#### Tip Callout\n\n```md\n{{\u003c/* admonition type=\"tip\" title=\"Tip\" */\u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"tip\" title=\"Tip\" \u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c /admonition \u003e}}\n\n#### Informational Callout\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Background\" */\u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"info\" title=\"Background\" \u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c /admonition \u003e}}\n\n#### Warning Callout\n\n```md\n{{\u003c/* admonition type=\"warning\" title=\"Do Not Edit Marker Files\" */\u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"warning\" title=\"Do Not Edit Marker Files\" \u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c /admonition \u003e}}\n\n#### Danger Callout\n\n```md\n{{\u003c/* admonition type=\"danger\" title=\"Destructive Change\" */\u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"danger\" title=\"Destructive Change\" \u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c /admonition \u003e}}\n\n### Implementation Reference\n\nThe shortcode implementation lives in `themes/sambee/layouts/shortcodes/admonition.html`.\n\nThe styling for the rendered admonition variants lives in `themes/sambee/assets/css/content.css`.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:website-dev-guide/authoring-and-tooling/docs-editor-tool", "parent_id": "section:website-dev-guide/authoring-and-tooling", "depth": 2, "kind": "page", "label": "docs-editor-tool", "title": "Docs Editor Tool", "path": "website-dev-guide/authoring-and-tooling/docs-editor-tool", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "branched", "source_version": "0.7", "diff_added": 109, "diff_removed": 17}, "0.9": {"state": "branched", "source_version": "0.8", "diff_added": 37, "diff_removed": 0}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "inherited", "source_version": "0.9"}}, "content_versions": {"0.7": "+++\ntitle = \"Docs Editor Tool\"\n+++\n\nThe docs editor CLI manages structural website docs changes safely and consistently. For ordinary copy edits inside an existing page, edit the Markdown file directly instead.\n\nPreview is the default mode. Run a command once to inspect the plan, then rerun it with `--apply` when the preview matches what you want.\n\n## Tool Location\n\nThe CLI lives at `website/scripts/docs-editor.py`.\n\nRun it from the `website/` directory:\n\n```bash\ncd website\npython3 scripts/docs-editor.py [global-options] \u003centity\u003e \u003coperation\u003e [operation-options]\n```\n\n## Normal Workflow\n\nUse the tool in this order:\n\n1. run the command in preview mode first\n2. review the planned metadata and file changes\n3. rerun the command with `--apply` when the plan is correct\n4. add `--yes` for destructive apply operations in non-interactive shells\n\nAfter a successful apply, the tool runs docs validation automatically.\n\nThe human-readable preview now shows:\n\n- the operation summary\n- the key metadata for the operation\n- the planned file and nav changes\n\n## What the Tool Handles\n\nThe docs editor supports four entity types:\n\n- versions\n- books\n- sections\n- pages\n\nSupported structural operations include:\n\n- creating\n- deleting\n- renaming\n\n## Common Tasks\n\nUse the built-in help when you know the action but not the exact flags:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --help\npython3 scripts/docs-editor.py page create --help\n```\n\nUse these commands as a starting point for the most common workflows:\n\n- add a new page\n- rename a page or section\n- create a new docs version that inherits from the latest one\n\n## Example: Create a New Version\n\nThis example:\n\n- creates `0.8` as a new version\n- adds it as to the end of the version list as the newest version (`--latest`)\n- adds the status label `preview` (which is shown in the UI)\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\n## Example: Create a New Book\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\n## Example: Create a Structural-Only Book\n\nUse this when a book is only a navigation container and should not have a landing page of its own.\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create \\\n  --version 0.7 \\\n  --book release-info \\\n  --position start \\\n  --structural-only\n```\n\nThat creates the book directory and nav entry without `_index.md` or `_inherit.md`.\n\n## Example: Create a Structural-Only Section\n\nThis is useful when you want a navigation group without a section landing page.\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --title \"Authoring And Tooling\" \\\n  --position end \\\n  --structural-only\n```\n\nThat creates the section directory and nav entry without `_index.md` or `_inherit.md`.\n\n## Example: Create a New Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\n## Example: Rename a Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --from website-and-docs-architecture-overview \\\n  --to website-and-docs-system-overview \\\n  --title \"Website And Docs System Overview\"\n```\n\nThat preview is especially useful when a rename may propagate into inherited descendants, because the metadata section shows which later inherited versions will follow the rename.\n\n## Convert an Inherited Page to Real Content\n\nSometimes a later version already has the page path and nav entry, but the page itself is still inherited through an empty `inherit.md` marker.\n\nIn that case, do not use `page create`. The page already exists structurally.\n\nInstead:\n\n1. Identify the inherited source page you want to override.\n1. Copy that page's current content into the later version as a starting point.\n1. Replace the later version's empty `inherit.md` with a real `index.md`.\n1. Edit the new `index.md` for the version-specific behavior.\n\nThis is a manual content-materialization step, not a page-creation step. The docs editor currently manages page identity and nav structure, but it does not provide a dedicated command that turns an existing inherited page marker into authored page content.\n\nIf a position selector fails, the CLI also reports the valid sibling slugs so you can retry without opening the nav file first.\n\n## Safety Model\n\nThe docs editor is deliberately conservative.\n\n- preview is the default\n- no files are written unless you pass `--apply`\n- destructive operations require confirmation unless you pass `--yes`\n- docs validation runs automatically after a successful apply\n\n### Refusal Semantics\n\nThe tool refuses destructive operations when they would silently rewrite newer authored content.\n\nTypical refusal case:\n\n- an older version rename would force changes into a later version that already has real content at the affected path\n\nIn that case, the CLI exits non-zero, reports the refusal reason, and leaves the docs tree unchanged.\n\n## Detailed Reference\n\nThe full CLI reference now lives on a separate page so this overview can stay task-focused.\n\nUse [Docs Editor Operation Reference](../docs-editor-operation-reference/) when you need:\n\n- the full global option list\n- forward-impact analysis rules\n- content invariants preserved by the tool\n- real-content stub and inherited-marker behavior\n- preview output details\n- per-entity create, delete, and rename reference behavior\n", "0.8": "+++\ntitle = \"Docs Editor Tool\"\n+++\n\nThe docs editor CLI manages structural website docs changes safely and consistently. For ordinary copy edits inside an existing page, edit the Markdown file directly instead.\n\nPreview is the default mode. Run a command once to inspect the plan, then rerun it with `--apply` when the preview matches what you want.\n\n## Tool Location\n\nThe CLI lives at `website/scripts/docs-editor.py`.\n\nRun it from the `website/` directory:\n\n```bash\ncd website\npython3 scripts/docs-editor.py [global-options] \u003centity\u003e \u003coperation\u003e [operation-options]\n```\n\n## Normal Workflow\n\nUse the tool in this order:\n\n1. run the command in preview mode first\n2. review the planned metadata and file changes\n3. rerun the command with `--apply` when the plan is correct\n4. add `--yes` for destructive apply operations in non-interactive shells\n\nAfter a successful apply, the tool runs docs validation automatically.\n\nThe human-readable preview now shows:\n\n- the operation summary\n- the key metadata for the operation\n- the planned file and nav changes\n\n## What the Tool Handles\n\nThe docs editor supports four entity types:\n\n- versions\n- books\n- sections\n- pages\n\nSupported structural operations include:\n\n- creating\n- deleting\n- renaming\n\nThe docs editor package also includes a standalone visualization report generator for the docs tree.\n\n## Common Tasks\n\nUse the built-in help when you know the action but not the exact flags:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --help\npython3 scripts/docs-editor.py page create --help\n```\n\nUse these commands as a starting point for the most common workflows:\n\n- add a new page\n- rename a page or section\n- create a new docs version that inherits from the latest one\n\n## Example: Create a New Version\n\nThis example:\n\n- creates `0.8` as a new version\n- adds it as to the end of the version list as the newest version (`--latest`)\n- adds the status label `preview` (which is shown in the UI)\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\n## Example: Create a New Book\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\n## Example: Create a Structural-Only Section\n\nThis is useful when you want a navigation group without a section landing page.\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --title \"Authoring And Tooling\" \\\n  --position end \\\n  --structural-only\n```\n\nThat creates the section directory and nav entry without `_index.md` or `_inherit.md`.\n\n## Example: Create a New Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\n## Example: Rename a Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --from website-and-docs-architecture-overview \\\n  --to website-and-docs-system-overview \\\n  --title \"Website And Docs System Overview\"\n```\n\nThat preview is especially useful when a rename may propagate into inherited descendants, because the metadata section shows which later inherited versions will follow the rename.\n\n## Convert an Inherited Page to Real Content\n\nSometimes a later version already has the page path and nav entry, but the page itself is still inherited through an empty `inherit.md` marker.\n\nIn that case, do not use `page create`. The page already exists structurally.\n\nUse `page materialize`:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page materialize \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page materialize \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nThat command:\n\n- removes the empty `inherit.md` marker in that version\n- copies the currently resolved inherited `index.md` content into the page directory\n- lets you optionally replace the page title with `--title`\n\nAfter that, edit the new `index.md` for the version-specific behavior.\n\n## Convert Real Page Content Back to Inherited Content\n\nIf you no longer need a version-specific page override, you can convert the page back to an inherited marker.\n\nUse `page inherit`:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page inherit \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply --yes page inherit \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nThis is destructive because it removes that version's real `index.md` and replaces it with `inherit.md`.\n\nThe command refuses when no earlier version provides real page content for the same path.\n\nManual fallback if you need finer control:\n\n1. Identify the inherited source page you want to override.\n1. Copy that page's current content into the later version as a starting point.\n1. Replace the later version's empty `inherit.md` with a real `index.md`.\n1. Edit the new `index.md` for the version-specific behavior.\n\nThis is still not a page-creation step. The page identity and nav structure already exist; `page materialize` only turns the inherited marker into authored page content in the selected version.\n\nIf a position selector fails, the CLI also reports the valid sibling slugs so you can retry without opening the nav file first.\n\n## Safety Model\n\nThe docs editor is deliberately conservative.\n\n- preview is the default\n- no files are written unless you pass `--apply`\n- destructive operations require confirmation unless you pass `--yes`\n- docs validation runs automatically after a successful apply\n\n### Refusal Semantics\n\nThe tool refuses destructive operations when they would silently rewrite newer authored content.\n\nTypical refusal case:\n\n- an older version rename would force changes into a later version that already has real content at the affected path\n\nIn that case, the CLI exits non-zero, reports the refusal reason, and leaves the docs tree unchanged.\n\n## Generate a Docs Structure Report\n\nThe docs editor package also includes a standalone report generator for exploring the docs tree across versions.\n\nUse it when you want a repo-local HTML view of:\n\n- books, sections, and pages in one expandable tree-table\n- current-version metadata and version status labels\n- inherited versus authored versus branched page states\n- diff counts for branched pages relative to the earlier authored version\n- per-page version comparison in the side panel\n\nThe wrapper script lives at `website/scripts/docs-report.py`.\n\nFor normal contributor workflow, prefer the repo helper:\n\n```bash\ncd /workspace\npython3 scripts/update-docs-derived-artifacts.py\n```\n\nThat helper centralizes the repo-local behavior around derived docs artifacts.\n\n- the pre-commit hook calls it automatically when staged docs inputs can stale the committed report\n- it stages the refreshed report for you in that hook-driven path\n- the VS Code workspace task `Website: Refresh Docs Derived Artifacts` runs the same helper manually\n\nGenerate the report into the committed output path:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py\n```\n\nThat writes `website-meta/docs-reports/docs-structure-report.html`.\n\nUse check mode in CI or before opening a pull request:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py --check\n```\n\nThat exits non-zero when the committed HTML report is stale.\n\n## Detailed Reference\n\nThe full CLI reference now lives on a separate page so this overview can stay task-focused.\n\nUse [Docs Editor Operation Reference](../docs-editor-operation-reference/) when you need:\n\n- the full global option list\n- forward-impact analysis rules\n- content invariants preserved by the tool\n- real-content stub and inherited-marker behavior\n- preview output details\n- per-entity create, delete, and rename reference behavior\n", "0.9": "+++\ntitle = \"Docs Editor Tool\"\n+++\n\nThe docs editor CLI manages structural website docs changes safely and consistently. For ordinary copy edits inside an existing page, edit the Markdown file directly instead.\n\nPreview is the default mode. Run a command once to inspect the plan, then rerun it with `--apply` when the preview matches what you want.\n\n## Tool Location\n\nThe CLI lives at `website/scripts/docs-editor.py`.\n\nRun it from the `website/` directory:\n\n```bash\ncd website\npython3 scripts/docs-editor.py [global-options] \u003centity\u003e \u003coperation\u003e [operation-options]\n```\n\n## Normal Workflow\n\nUse the tool in this order:\n\n1. run the command in preview mode first\n2. review the planned metadata and file changes\n3. rerun the command with `--apply` when the plan is correct\n4. add `--yes` for destructive apply operations in non-interactive shells\n\nAfter a successful apply, the tool runs docs validation automatically.\n\nThe human-readable preview now shows:\n\n- the operation summary\n- the key metadata for the operation\n- the planned file and nav changes\n\n## What the Tool Handles\n\nThe docs editor supports four entity types:\n\n- versions\n- books\n- sections\n- pages\n\nSupported structural operations include:\n\n- creating\n- deleting\n- materializing inherited landing content\n- moving pages between sections\n- renaming\n\nThe docs editor package also includes a standalone visualization report generator for the docs tree.\n\n## Common Tasks\n\nUse the built-in help when you know the action but not the exact flags:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --help\npython3 scripts/docs-editor.py page create --help\n```\n\nUse these commands as a starting point for the most common workflows:\n\n- add a new page\n- materialize an inherited book landing page\n- move a page to another section\n- rename a page or section\n- create a new docs version that inherits from the latest one\n\n## Example: Create a New Version\n\nThis example:\n\n- creates `0.8` as a new version\n- adds it as to the end of the version list as the newest version (`--latest`)\n- adds the status label `preview` (which is shown in the UI)\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\n## Example: Create a New Book\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\n## Example: Create a Structural-Only Section\n\nThis is useful when you want a navigation group without a section landing page.\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --title \"Authoring And Tooling\" \\\n  --position end \\\n  --structural-only\n```\n\nThat creates the section directory and nav entry without `_index.md` or `_inherit.md`.\n\n## Example: Create a New Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\n## Example: Rename a Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --from website-and-docs-architecture-overview \\\n  --to website-and-docs-system-overview \\\n  --title \"Website And Docs System Overview\"\n```\n\nThat preview is especially useful when a rename may propagate into inherited descendants, because the metadata section shows which later inherited versions will follow the rename.\n\n## Convert an Inherited Page to Real Content\n\nSometimes a later version already has the page path and nav entry, but the page itself is still inherited through an empty `inherit.md` marker.\n\nIn that case, do not use `page create`. The page already exists structurally.\n\nUse `page materialize`:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page materialize \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page materialize \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nThat command:\n\n- removes the empty `inherit.md` marker in that version\n- copies the currently resolved inherited `index.md` content into the page directory\n- lets you optionally replace the page title with `--title`\n\nAfter that, edit the new `index.md` for the version-specific behavior.\n\n## Convert an Inherited Book Landing Page to Real Content\n\nUse `book materialize` when a version inherits a book landing page through `_inherit.md` and needs version-specific copy:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply book materialize \\\n  --version 0.9 \\\n  --book admin-guide\n```\n\nThe command replaces `_inherit.md` with the currently resolved `_index.md` content. Use `--title` to replace its title while materializing.\n\n## Move a Page Between Sections\n\nUse `page move` to move a page within one book while preserving its body content:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page move \\\n  --version 0.9 \\\n  --book admin-guide \\\n  --from-section configuration \\\n  --to-section reference \\\n  --page configuration-key-reference \\\n  --to-page configuration-file-reference \\\n  --position start\n```\n\nThe tool updates both page lists, creates real content at the destination, and removes the source directory. `--to-page` is optional and defaults to the source page slug. `--position` applies to the selected version's destination section.\n\nLater inherited-only versions follow the move automatically. The tool refuses when the destination exists, a later version has authored source content, or a later version lacks the destination section. Update Markdown links and managed redirects separately.\n\n## Convert Real Page Content Back to Inherited Content\n\nIf you no longer need a version-specific page override, you can convert the page back to an inherited marker.\n\nUse `page inherit`:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page inherit \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply --yes page inherit \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nThis is destructive because it removes that version's real `index.md` and replaces it with `inherit.md`.\n\nThe command refuses when no earlier version provides real page content for the same path.\n\nManual fallback if you need finer control:\n\n1. Identify the inherited source page you want to override.\n1. Copy that page's current content into the later version as a starting point.\n1. Replace the later version's empty `inherit.md` with a real `index.md`.\n1. Edit the new `index.md` for the version-specific behavior.\n\nThis is still not a page-creation step. The page identity and nav structure already exist; `page materialize` only turns the inherited marker into authored page content in the selected version.\n\nIf a position selector fails, the CLI also reports the valid sibling slugs so you can retry without opening the nav file first.\n\n## Safety Model\n\nThe docs editor is deliberately conservative.\n\n- preview is the default\n- no files are written unless you pass `--apply`\n- destructive operations require confirmation unless you pass `--yes`\n- docs validation runs automatically after a successful apply\n\n### Refusal Semantics\n\nThe tool refuses destructive operations when they would silently rewrite newer authored content.\n\nTypical refusal case:\n\n- an older version rename would force changes into a later version that already has real content at the affected path\n\nIn that case, the CLI exits non-zero, reports the refusal reason, and leaves the docs tree unchanged.\n\n## Generate a Docs Structure Report\n\nThe docs editor package also includes a standalone report generator for exploring the docs tree across versions.\n\nUse it when you want a repo-local HTML view of:\n\n- books, sections, and pages in one expandable tree-table\n- current-version metadata and version status labels\n- inherited versus authored versus branched page states\n- diff counts for branched pages relative to the earlier authored version\n- per-page version comparison in the side panel\n\nThe wrapper script lives at `website/scripts/docs-report.py`.\n\nFor normal contributor workflow, prefer the repo helper:\n\n```bash\ncd /workspace\npython3 scripts/update-docs-derived-artifacts.py\n```\n\nThat helper centralizes the repo-local behavior around derived docs artifacts.\n\n- the pre-commit hook calls it automatically when staged docs inputs can stale the committed report\n- it stages the refreshed report for you in that hook-driven path\n- the VS Code workspace task `Website: Refresh Docs Derived Artifacts` runs the same helper manually\n\nGenerate the report into the committed output path:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py\n```\n\nThat writes `website-meta/docs-reports/docs-structure-report.html`.\n\nUse check mode in CI or before opening a pull request:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py --check\n```\n\nThat exits non-zero when the committed HTML report is stale.\n\n## Detailed Reference\n\nThe full CLI reference now lives on a separate page so this overview can stay task-focused.\n\nUse [Docs Editor Operation Reference](../docs-editor-operation-reference/) when you need:\n\n- the full global option list\n- forward-impact analysis rules\n- content invariants preserved by the tool\n- real-content stub and inherited-marker behavior\n- preview output details\n- per-entity create, delete, and rename reference behavior\n", "1.0": "+++\ntitle = \"Docs Editor Tool\"\n+++\n\nThe docs editor CLI manages structural website docs changes safely and consistently. For ordinary copy edits inside an existing page, edit the Markdown file directly instead.\n\nPreview is the default mode. Run a command once to inspect the plan, then rerun it with `--apply` when the preview matches what you want.\n\n## Tool Location\n\nThe CLI lives at `website/scripts/docs-editor.py`.\n\nRun it from the `website/` directory:\n\n```bash\ncd website\npython3 scripts/docs-editor.py [global-options] \u003centity\u003e \u003coperation\u003e [operation-options]\n```\n\n## Normal Workflow\n\nUse the tool in this order:\n\n1. run the command in preview mode first\n2. review the planned metadata and file changes\n3. rerun the command with `--apply` when the plan is correct\n4. add `--yes` for destructive apply operations in non-interactive shells\n\nAfter a successful apply, the tool runs docs validation automatically.\n\nThe human-readable preview now shows:\n\n- the operation summary\n- the key metadata for the operation\n- the planned file and nav changes\n\n## What the Tool Handles\n\nThe docs editor supports four entity types:\n\n- versions\n- books\n- sections\n- pages\n\nSupported structural operations include:\n\n- creating\n- deleting\n- materializing inherited landing content\n- moving pages between sections\n- renaming\n\nThe docs editor package also includes a standalone visualization report generator for the docs tree.\n\n## Common Tasks\n\nUse the built-in help when you know the action but not the exact flags:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --help\npython3 scripts/docs-editor.py page create --help\n```\n\nUse these commands as a starting point for the most common workflows:\n\n- add a new page\n- materialize an inherited book landing page\n- move a page to another section\n- rename a page or section\n- create a new docs version that inherits from the latest one\n\n## Example: Create a New Version\n\nThis example:\n\n- creates `0.8` as a new version\n- adds it as to the end of the version list as the newest version (`--latest`)\n- adds the status label `preview` (which is shown in the UI)\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\n## Example: Create a New Book\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\n## Example: Create a Structural-Only Section\n\nThis is useful when you want a navigation group without a section landing page.\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --title \"Authoring And Tooling\" \\\n  --position end \\\n  --structural-only\n```\n\nThat creates the section directory and nav entry without `_index.md` or `_inherit.md`.\n\n## Example: Create a New Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\n## Example: Rename a Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --from website-and-docs-architecture-overview \\\n  --to website-and-docs-system-overview \\\n  --title \"Website And Docs System Overview\"\n```\n\nThat preview is especially useful when a rename may propagate into inherited descendants, because the metadata section shows which later inherited versions will follow the rename.\n\n## Convert an Inherited Page to Real Content\n\nSometimes a later version already has the page path and nav entry, but the page itself is still inherited through an empty `inherit.md` marker.\n\nIn that case, do not use `page create`. The page already exists structurally.\n\nUse `page materialize`:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page materialize \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page materialize \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nThat command:\n\n- removes the empty `inherit.md` marker in that version\n- copies the currently resolved inherited `index.md` content into the page directory\n- lets you optionally replace the page title with `--title`\n\nAfter that, edit the new `index.md` for the version-specific behavior.\n\n## Convert an Inherited Book Landing Page to Real Content\n\nUse `book materialize` when a version inherits a book landing page through `_inherit.md` and needs version-specific copy:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply book materialize \\\n  --version 0.9 \\\n  --book admin-guide\n```\n\nThe command replaces `_inherit.md` with the currently resolved `_index.md` content. Use `--title` to replace its title while materializing.\n\n## Move a Page Between Sections\n\nUse `page move` to move a page within one book while preserving its body content:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page move \\\n  --version 0.9 \\\n  --book admin-guide \\\n  --from-section configuration \\\n  --to-section reference \\\n  --page configuration-key-reference \\\n  --to-page configuration-file-reference \\\n  --position start\n```\n\nThe tool updates both page lists, creates real content at the destination, and removes the source directory. `--to-page` is optional and defaults to the source page slug. `--position` applies to the selected version's destination section.\n\nLater inherited-only versions follow the move automatically. The tool refuses when the destination exists, a later version has authored source content, or a later version lacks the destination section. Update Markdown links and managed redirects separately.\n\n## Convert Real Page Content Back to Inherited Content\n\nIf you no longer need a version-specific page override, you can convert the page back to an inherited marker.\n\nUse `page inherit`:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page inherit \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply --yes page inherit \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nThis is destructive because it removes that version's real `index.md` and replaces it with `inherit.md`.\n\nThe command refuses when no earlier version provides real page content for the same path.\n\nManual fallback if you need finer control:\n\n1. Identify the inherited source page you want to override.\n1. Copy that page's current content into the later version as a starting point.\n1. Replace the later version's empty `inherit.md` with a real `index.md`.\n1. Edit the new `index.md` for the version-specific behavior.\n\nThis is still not a page-creation step. The page identity and nav structure already exist; `page materialize` only turns the inherited marker into authored page content in the selected version.\n\nIf a position selector fails, the CLI also reports the valid sibling slugs so you can retry without opening the nav file first.\n\n## Safety Model\n\nThe docs editor is deliberately conservative.\n\n- preview is the default\n- no files are written unless you pass `--apply`\n- destructive operations require confirmation unless you pass `--yes`\n- docs validation runs automatically after a successful apply\n\n### Refusal Semantics\n\nThe tool refuses destructive operations when they would silently rewrite newer authored content.\n\nTypical refusal case:\n\n- an older version rename would force changes into a later version that already has real content at the affected path\n\nIn that case, the CLI exits non-zero, reports the refusal reason, and leaves the docs tree unchanged.\n\n## Generate a Docs Structure Report\n\nThe docs editor package also includes a standalone report generator for exploring the docs tree across versions.\n\nUse it when you want a repo-local HTML view of:\n\n- books, sections, and pages in one expandable tree-table\n- current-version metadata and version status labels\n- inherited versus authored versus branched page states\n- diff counts for branched pages relative to the earlier authored version\n- per-page version comparison in the side panel\n\nThe wrapper script lives at `website/scripts/docs-report.py`.\n\nFor normal contributor workflow, prefer the repo helper:\n\n```bash\ncd /workspace\npython3 scripts/update-docs-derived-artifacts.py\n```\n\nThat helper centralizes the repo-local behavior around derived docs artifacts.\n\n- the pre-commit hook calls it automatically when staged docs inputs can stale the committed report\n- it stages the refreshed report for you in that hook-driven path\n- the VS Code workspace task `Website: Refresh Docs Derived Artifacts` runs the same helper manually\n\nGenerate the report into the committed output path:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py\n```\n\nThat writes `website-meta/docs-reports/docs-structure-report.html`.\n\nUse check mode in CI or before opening a pull request:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py --check\n```\n\nThat exits non-zero when the committed HTML report is stale.\n\n## Detailed Reference\n\nThe full CLI reference now lives on a separate page so this overview can stay task-focused.\n\nUse [Docs Editor Operation Reference](../docs-editor-operation-reference/) when you need:\n\n- the full global option list\n- forward-impact analysis rules\n- content invariants preserved by the tool\n- real-content stub and inherited-marker behavior\n- preview output details\n- per-entity create, delete, and rename reference behavior\n", "2.0": "+++\ntitle = \"Docs Editor Tool\"\n+++\n\nThe docs editor CLI manages structural website docs changes safely and consistently. For ordinary copy edits inside an existing page, edit the Markdown file directly instead.\n\nPreview is the default mode. Run a command once to inspect the plan, then rerun it with `--apply` when the preview matches what you want.\n\n## Tool Location\n\nThe CLI lives at `website/scripts/docs-editor.py`.\n\nRun it from the `website/` directory:\n\n```bash\ncd website\npython3 scripts/docs-editor.py [global-options] \u003centity\u003e \u003coperation\u003e [operation-options]\n```\n\n## Normal Workflow\n\nUse the tool in this order:\n\n1. run the command in preview mode first\n2. review the planned metadata and file changes\n3. rerun the command with `--apply` when the plan is correct\n4. add `--yes` for destructive apply operations in non-interactive shells\n\nAfter a successful apply, the tool runs docs validation automatically.\n\nThe human-readable preview now shows:\n\n- the operation summary\n- the key metadata for the operation\n- the planned file and nav changes\n\n## What the Tool Handles\n\nThe docs editor supports four entity types:\n\n- versions\n- books\n- sections\n- pages\n\nSupported structural operations include:\n\n- creating\n- deleting\n- materializing inherited landing content\n- moving pages between sections\n- renaming\n\nThe docs editor package also includes a standalone visualization report generator for the docs tree.\n\n## Common Tasks\n\nUse the built-in help when you know the action but not the exact flags:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --help\npython3 scripts/docs-editor.py page create --help\n```\n\nUse these commands as a starting point for the most common workflows:\n\n- add a new page\n- materialize an inherited book landing page\n- move a page to another section\n- rename a page or section\n- create a new docs version that inherits from the latest one\n\n## Example: Create a New Version\n\nThis example:\n\n- creates `0.8` as a new version\n- adds it as to the end of the version list as the newest version (`--latest`)\n- adds the status label `preview` (which is shown in the UI)\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\n## Example: Create a New Book\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\n## Example: Create a Structural-Only Section\n\nThis is useful when you want a navigation group without a section landing page.\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --title \"Authoring And Tooling\" \\\n  --position end \\\n  --structural-only\n```\n\nThat creates the section directory and nav entry without `_index.md` or `_inherit.md`.\n\n## Example: Create a New Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\n## Example: Rename a Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --from website-and-docs-architecture-overview \\\n  --to website-and-docs-system-overview \\\n  --title \"Website And Docs System Overview\"\n```\n\nThat preview is especially useful when a rename may propagate into inherited descendants, because the metadata section shows which later inherited versions will follow the rename.\n\n## Convert an Inherited Page to Real Content\n\nSometimes a later version already has the page path and nav entry, but the page itself is still inherited through an empty `inherit.md` marker.\n\nIn that case, do not use `page create`. The page already exists structurally.\n\nUse `page materialize`:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page materialize \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page materialize \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nThat command:\n\n- removes the empty `inherit.md` marker in that version\n- copies the currently resolved inherited `index.md` content into the page directory\n- lets you optionally replace the page title with `--title`\n\nAfter that, edit the new `index.md` for the version-specific behavior.\n\n## Convert an Inherited Book Landing Page to Real Content\n\nUse `book materialize` when a version inherits a book landing page through `_inherit.md` and needs version-specific copy:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply book materialize \\\n  --version 0.9 \\\n  --book admin-guide\n```\n\nThe command replaces `_inherit.md` with the currently resolved `_index.md` content. Use `--title` to replace its title while materializing.\n\n## Move a Page Between Sections\n\nUse `page move` to move a page within one book while preserving its body content:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page move \\\n  --version 0.9 \\\n  --book admin-guide \\\n  --from-section configuration \\\n  --to-section reference \\\n  --page configuration-key-reference \\\n  --to-page configuration-file-reference \\\n  --position start\n```\n\nThe tool updates both page lists, creates real content at the destination, and removes the source directory. `--to-page` is optional and defaults to the source page slug. `--position` applies to the selected version's destination section.\n\nLater inherited-only versions follow the move automatically. The tool refuses when the destination exists, a later version has authored source content, or a later version lacks the destination section. Update Markdown links and managed redirects separately.\n\n## Convert Real Page Content Back to Inherited Content\n\nIf you no longer need a version-specific page override, you can convert the page back to an inherited marker.\n\nUse `page inherit`:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page inherit \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply --yes page inherit \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nThis is destructive because it removes that version's real `index.md` and replaces it with `inherit.md`.\n\nThe command refuses when no earlier version provides real page content for the same path.\n\nManual fallback if you need finer control:\n\n1. Identify the inherited source page you want to override.\n1. Copy that page's current content into the later version as a starting point.\n1. Replace the later version's empty `inherit.md` with a real `index.md`.\n1. Edit the new `index.md` for the version-specific behavior.\n\nThis is still not a page-creation step. The page identity and nav structure already exist; `page materialize` only turns the inherited marker into authored page content in the selected version.\n\nIf a position selector fails, the CLI also reports the valid sibling slugs so you can retry without opening the nav file first.\n\n## Safety Model\n\nThe docs editor is deliberately conservative.\n\n- preview is the default\n- no files are written unless you pass `--apply`\n- destructive operations require confirmation unless you pass `--yes`\n- docs validation runs automatically after a successful apply\n\n### Refusal Semantics\n\nThe tool refuses destructive operations when they would silently rewrite newer authored content.\n\nTypical refusal case:\n\n- an older version rename would force changes into a later version that already has real content at the affected path\n\nIn that case, the CLI exits non-zero, reports the refusal reason, and leaves the docs tree unchanged.\n\n## Generate a Docs Structure Report\n\nThe docs editor package also includes a standalone report generator for exploring the docs tree across versions.\n\nUse it when you want a repo-local HTML view of:\n\n- books, sections, and pages in one expandable tree-table\n- current-version metadata and version status labels\n- inherited versus authored versus branched page states\n- diff counts for branched pages relative to the earlier authored version\n- per-page version comparison in the side panel\n\nThe wrapper script lives at `website/scripts/docs-report.py`.\n\nFor normal contributor workflow, prefer the repo helper:\n\n```bash\ncd /workspace\npython3 scripts/update-docs-derived-artifacts.py\n```\n\nThat helper centralizes the repo-local behavior around derived docs artifacts.\n\n- the pre-commit hook calls it automatically when staged docs inputs can stale the committed report\n- it stages the refreshed report for you in that hook-driven path\n- the VS Code workspace task `Website: Refresh Docs Derived Artifacts` runs the same helper manually\n\nGenerate the report into the committed output path:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py\n```\n\nThat writes `website-meta/docs-reports/docs-structure-report.html`.\n\nUse check mode in CI or before opening a pull request:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py --check\n```\n\nThat exits non-zero when the committed HTML report is stale.\n\n## Detailed Reference\n\nThe full CLI reference now lives on a separate page so this overview can stay task-focused.\n\nUse [Docs Editor Operation Reference](../docs-editor-operation-reference/) when you need:\n\n- the full global option list\n- forward-impact analysis rules\n- content invariants preserved by the tool\n- real-content stub and inherited-marker behavior\n- preview output details\n- per-entity create, delete, and rename reference behavior\n"}, "page_contents": {"0.7": "+++\ntitle = \"Docs Editor Tool\"\n+++\n\nThe docs editor CLI manages structural website docs changes safely and consistently. For ordinary copy edits inside an existing page, edit the Markdown file directly instead.\n\nPreview is the default mode. Run a command once to inspect the plan, then rerun it with `--apply` when the preview matches what you want.\n\n## Tool Location\n\nThe CLI lives at `website/scripts/docs-editor.py`.\n\nRun it from the `website/` directory:\n\n```bash\ncd website\npython3 scripts/docs-editor.py [global-options] \u003centity\u003e \u003coperation\u003e [operation-options]\n```\n\n## Normal Workflow\n\nUse the tool in this order:\n\n1. run the command in preview mode first\n2. review the planned metadata and file changes\n3. rerun the command with `--apply` when the plan is correct\n4. add `--yes` for destructive apply operations in non-interactive shells\n\nAfter a successful apply, the tool runs docs validation automatically.\n\nThe human-readable preview now shows:\n\n- the operation summary\n- the key metadata for the operation\n- the planned file and nav changes\n\n## What the Tool Handles\n\nThe docs editor supports four entity types:\n\n- versions\n- books\n- sections\n- pages\n\nSupported structural operations include:\n\n- creating\n- deleting\n- renaming\n\n## Common Tasks\n\nUse the built-in help when you know the action but not the exact flags:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --help\npython3 scripts/docs-editor.py page create --help\n```\n\nUse these commands as a starting point for the most common workflows:\n\n- add a new page\n- rename a page or section\n- create a new docs version that inherits from the latest one\n\n## Example: Create a New Version\n\nThis example:\n\n- creates `0.8` as a new version\n- adds it as to the end of the version list as the newest version (`--latest`)\n- adds the status label `preview` (which is shown in the UI)\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\n## Example: Create a New Book\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\n## Example: Create a Structural-Only Book\n\nUse this when a book is only a navigation container and should not have a landing page of its own.\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create \\\n  --version 0.7 \\\n  --book release-info \\\n  --position start \\\n  --structural-only\n```\n\nThat creates the book directory and nav entry without `_index.md` or `_inherit.md`.\n\n## Example: Create a Structural-Only Section\n\nThis is useful when you want a navigation group without a section landing page.\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --title \"Authoring And Tooling\" \\\n  --position end \\\n  --structural-only\n```\n\nThat creates the section directory and nav entry without `_index.md` or `_inherit.md`.\n\n## Example: Create a New Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\n## Example: Rename a Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --from website-and-docs-architecture-overview \\\n  --to website-and-docs-system-overview \\\n  --title \"Website And Docs System Overview\"\n```\n\nThat preview is especially useful when a rename may propagate into inherited descendants, because the metadata section shows which later inherited versions will follow the rename.\n\n## Convert an Inherited Page to Real Content\n\nSometimes a later version already has the page path and nav entry, but the page itself is still inherited through an empty `inherit.md` marker.\n\nIn that case, do not use `page create`. The page already exists structurally.\n\nInstead:\n\n1. Identify the inherited source page you want to override.\n1. Copy that page's current content into the later version as a starting point.\n1. Replace the later version's empty `inherit.md` with a real `index.md`.\n1. Edit the new `index.md` for the version-specific behavior.\n\nThis is a manual content-materialization step, not a page-creation step. The docs editor currently manages page identity and nav structure, but it does not provide a dedicated command that turns an existing inherited page marker into authored page content.\n\nIf a position selector fails, the CLI also reports the valid sibling slugs so you can retry without opening the nav file first.\n\n## Safety Model\n\nThe docs editor is deliberately conservative.\n\n- preview is the default\n- no files are written unless you pass `--apply`\n- destructive operations require confirmation unless you pass `--yes`\n- docs validation runs automatically after a successful apply\n\n### Refusal Semantics\n\nThe tool refuses destructive operations when they would silently rewrite newer authored content.\n\nTypical refusal case:\n\n- an older version rename would force changes into a later version that already has real content at the affected path\n\nIn that case, the CLI exits non-zero, reports the refusal reason, and leaves the docs tree unchanged.\n\n## Detailed Reference\n\nThe full CLI reference now lives on a separate page so this overview can stay task-focused.\n\nUse [Docs Editor Operation Reference](../docs-editor-operation-reference/) when you need:\n\n- the full global option list\n- forward-impact analysis rules\n- content invariants preserved by the tool\n- real-content stub and inherited-marker behavior\n- preview output details\n- per-entity create, delete, and rename reference behavior\n", "0.8": "+++\ntitle = \"Docs Editor Tool\"\n+++\n\nThe docs editor CLI manages structural website docs changes safely and consistently. For ordinary copy edits inside an existing page, edit the Markdown file directly instead.\n\nPreview is the default mode. Run a command once to inspect the plan, then rerun it with `--apply` when the preview matches what you want.\n\n## Tool Location\n\nThe CLI lives at `website/scripts/docs-editor.py`.\n\nRun it from the `website/` directory:\n\n```bash\ncd website\npython3 scripts/docs-editor.py [global-options] \u003centity\u003e \u003coperation\u003e [operation-options]\n```\n\n## Normal Workflow\n\nUse the tool in this order:\n\n1. run the command in preview mode first\n2. review the planned metadata and file changes\n3. rerun the command with `--apply` when the plan is correct\n4. add `--yes` for destructive apply operations in non-interactive shells\n\nAfter a successful apply, the tool runs docs validation automatically.\n\nThe human-readable preview now shows:\n\n- the operation summary\n- the key metadata for the operation\n- the planned file and nav changes\n\n## What the Tool Handles\n\nThe docs editor supports four entity types:\n\n- versions\n- books\n- sections\n- pages\n\nSupported structural operations include:\n\n- creating\n- deleting\n- renaming\n\nThe docs editor package also includes a standalone visualization report generator for the docs tree.\n\n## Common Tasks\n\nUse the built-in help when you know the action but not the exact flags:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --help\npython3 scripts/docs-editor.py page create --help\n```\n\nUse these commands as a starting point for the most common workflows:\n\n- add a new page\n- rename a page or section\n- create a new docs version that inherits from the latest one\n\n## Example: Create a New Version\n\nThis example:\n\n- creates `0.8` as a new version\n- adds it as to the end of the version list as the newest version (`--latest`)\n- adds the status label `preview` (which is shown in the UI)\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\n## Example: Create a New Book\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\n## Example: Create a Structural-Only Section\n\nThis is useful when you want a navigation group without a section landing page.\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --title \"Authoring And Tooling\" \\\n  --position end \\\n  --structural-only\n```\n\nThat creates the section directory and nav entry without `_index.md` or `_inherit.md`.\n\n## Example: Create a New Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\n## Example: Rename a Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --from website-and-docs-architecture-overview \\\n  --to website-and-docs-system-overview \\\n  --title \"Website And Docs System Overview\"\n```\n\nThat preview is especially useful when a rename may propagate into inherited descendants, because the metadata section shows which later inherited versions will follow the rename.\n\n## Convert an Inherited Page to Real Content\n\nSometimes a later version already has the page path and nav entry, but the page itself is still inherited through an empty `inherit.md` marker.\n\nIn that case, do not use `page create`. The page already exists structurally.\n\nUse `page materialize`:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page materialize \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page materialize \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nThat command:\n\n- removes the empty `inherit.md` marker in that version\n- copies the currently resolved inherited `index.md` content into the page directory\n- lets you optionally replace the page title with `--title`\n\nAfter that, edit the new `index.md` for the version-specific behavior.\n\n## Convert Real Page Content Back to Inherited Content\n\nIf you no longer need a version-specific page override, you can convert the page back to an inherited marker.\n\nUse `page inherit`:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page inherit \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply --yes page inherit \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nThis is destructive because it removes that version's real `index.md` and replaces it with `inherit.md`.\n\nThe command refuses when no earlier version provides real page content for the same path.\n\nManual fallback if you need finer control:\n\n1. Identify the inherited source page you want to override.\n1. Copy that page's current content into the later version as a starting point.\n1. Replace the later version's empty `inherit.md` with a real `index.md`.\n1. Edit the new `index.md` for the version-specific behavior.\n\nThis is still not a page-creation step. The page identity and nav structure already exist; `page materialize` only turns the inherited marker into authored page content in the selected version.\n\nIf a position selector fails, the CLI also reports the valid sibling slugs so you can retry without opening the nav file first.\n\n## Safety Model\n\nThe docs editor is deliberately conservative.\n\n- preview is the default\n- no files are written unless you pass `--apply`\n- destructive operations require confirmation unless you pass `--yes`\n- docs validation runs automatically after a successful apply\n\n### Refusal Semantics\n\nThe tool refuses destructive operations when they would silently rewrite newer authored content.\n\nTypical refusal case:\n\n- an older version rename would force changes into a later version that already has real content at the affected path\n\nIn that case, the CLI exits non-zero, reports the refusal reason, and leaves the docs tree unchanged.\n\n## Generate a Docs Structure Report\n\nThe docs editor package also includes a standalone report generator for exploring the docs tree across versions.\n\nUse it when you want a repo-local HTML view of:\n\n- books, sections, and pages in one expandable tree-table\n- current-version metadata and version status labels\n- inherited versus authored versus branched page states\n- diff counts for branched pages relative to the earlier authored version\n- per-page version comparison in the side panel\n\nThe wrapper script lives at `website/scripts/docs-report.py`.\n\nFor normal contributor workflow, prefer the repo helper:\n\n```bash\ncd /workspace\npython3 scripts/update-docs-derived-artifacts.py\n```\n\nThat helper centralizes the repo-local behavior around derived docs artifacts.\n\n- the pre-commit hook calls it automatically when staged docs inputs can stale the committed report\n- it stages the refreshed report for you in that hook-driven path\n- the VS Code workspace task `Website: Refresh Docs Derived Artifacts` runs the same helper manually\n\nGenerate the report into the committed output path:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py\n```\n\nThat writes `website-meta/docs-reports/docs-structure-report.html`.\n\nUse check mode in CI or before opening a pull request:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py --check\n```\n\nThat exits non-zero when the committed HTML report is stale.\n\n## Detailed Reference\n\nThe full CLI reference now lives on a separate page so this overview can stay task-focused.\n\nUse [Docs Editor Operation Reference](../docs-editor-operation-reference/) when you need:\n\n- the full global option list\n- forward-impact analysis rules\n- content invariants preserved by the tool\n- real-content stub and inherited-marker behavior\n- preview output details\n- per-entity create, delete, and rename reference behavior\n", "0.9": "+++\ntitle = \"Docs Editor Tool\"\n+++\n\nThe docs editor CLI manages structural website docs changes safely and consistently. For ordinary copy edits inside an existing page, edit the Markdown file directly instead.\n\nPreview is the default mode. Run a command once to inspect the plan, then rerun it with `--apply` when the preview matches what you want.\n\n## Tool Location\n\nThe CLI lives at `website/scripts/docs-editor.py`.\n\nRun it from the `website/` directory:\n\n```bash\ncd website\npython3 scripts/docs-editor.py [global-options] \u003centity\u003e \u003coperation\u003e [operation-options]\n```\n\n## Normal Workflow\n\nUse the tool in this order:\n\n1. run the command in preview mode first\n2. review the planned metadata and file changes\n3. rerun the command with `--apply` when the plan is correct\n4. add `--yes` for destructive apply operations in non-interactive shells\n\nAfter a successful apply, the tool runs docs validation automatically.\n\nThe human-readable preview now shows:\n\n- the operation summary\n- the key metadata for the operation\n- the planned file and nav changes\n\n## What the Tool Handles\n\nThe docs editor supports four entity types:\n\n- versions\n- books\n- sections\n- pages\n\nSupported structural operations include:\n\n- creating\n- deleting\n- materializing inherited landing content\n- moving pages between sections\n- renaming\n\nThe docs editor package also includes a standalone visualization report generator for the docs tree.\n\n## Common Tasks\n\nUse the built-in help when you know the action but not the exact flags:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --help\npython3 scripts/docs-editor.py page create --help\n```\n\nUse these commands as a starting point for the most common workflows:\n\n- add a new page\n- materialize an inherited book landing page\n- move a page to another section\n- rename a page or section\n- create a new docs version that inherits from the latest one\n\n## Example: Create a New Version\n\nThis example:\n\n- creates `0.8` as a new version\n- adds it as to the end of the version list as the newest version (`--latest`)\n- adds the status label `preview` (which is shown in the UI)\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\n## Example: Create a New Book\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\n## Example: Create a Structural-Only Section\n\nThis is useful when you want a navigation group without a section landing page.\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --title \"Authoring And Tooling\" \\\n  --position end \\\n  --structural-only\n```\n\nThat creates the section directory and nav entry without `_index.md` or `_inherit.md`.\n\n## Example: Create a New Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\n## Example: Rename a Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --from website-and-docs-architecture-overview \\\n  --to website-and-docs-system-overview \\\n  --title \"Website And Docs System Overview\"\n```\n\nThat preview is especially useful when a rename may propagate into inherited descendants, because the metadata section shows which later inherited versions will follow the rename.\n\n## Convert an Inherited Page to Real Content\n\nSometimes a later version already has the page path and nav entry, but the page itself is still inherited through an empty `inherit.md` marker.\n\nIn that case, do not use `page create`. The page already exists structurally.\n\nUse `page materialize`:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page materialize \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page materialize \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nThat command:\n\n- removes the empty `inherit.md` marker in that version\n- copies the currently resolved inherited `index.md` content into the page directory\n- lets you optionally replace the page title with `--title`\n\nAfter that, edit the new `index.md` for the version-specific behavior.\n\n## Convert an Inherited Book Landing Page to Real Content\n\nUse `book materialize` when a version inherits a book landing page through `_inherit.md` and needs version-specific copy:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply book materialize \\\n  --version 0.9 \\\n  --book admin-guide\n```\n\nThe command replaces `_inherit.md` with the currently resolved `_index.md` content. Use `--title` to replace its title while materializing.\n\n## Move a Page Between Sections\n\nUse `page move` to move a page within one book while preserving its body content:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page move \\\n  --version 0.9 \\\n  --book admin-guide \\\n  --from-section configuration \\\n  --to-section reference \\\n  --page configuration-key-reference \\\n  --to-page configuration-file-reference \\\n  --position start\n```\n\nThe tool updates both page lists, creates real content at the destination, and removes the source directory. `--to-page` is optional and defaults to the source page slug. `--position` applies to the selected version's destination section.\n\nLater inherited-only versions follow the move automatically. The tool refuses when the destination exists, a later version has authored source content, or a later version lacks the destination section. Update Markdown links and managed redirects separately.\n\n## Convert Real Page Content Back to Inherited Content\n\nIf you no longer need a version-specific page override, you can convert the page back to an inherited marker.\n\nUse `page inherit`:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page inherit \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply --yes page inherit \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nThis is destructive because it removes that version's real `index.md` and replaces it with `inherit.md`.\n\nThe command refuses when no earlier version provides real page content for the same path.\n\nManual fallback if you need finer control:\n\n1. Identify the inherited source page you want to override.\n1. Copy that page's current content into the later version as a starting point.\n1. Replace the later version's empty `inherit.md` with a real `index.md`.\n1. Edit the new `index.md` for the version-specific behavior.\n\nThis is still not a page-creation step. The page identity and nav structure already exist; `page materialize` only turns the inherited marker into authored page content in the selected version.\n\nIf a position selector fails, the CLI also reports the valid sibling slugs so you can retry without opening the nav file first.\n\n## Safety Model\n\nThe docs editor is deliberately conservative.\n\n- preview is the default\n- no files are written unless you pass `--apply`\n- destructive operations require confirmation unless you pass `--yes`\n- docs validation runs automatically after a successful apply\n\n### Refusal Semantics\n\nThe tool refuses destructive operations when they would silently rewrite newer authored content.\n\nTypical refusal case:\n\n- an older version rename would force changes into a later version that already has real content at the affected path\n\nIn that case, the CLI exits non-zero, reports the refusal reason, and leaves the docs tree unchanged.\n\n## Generate a Docs Structure Report\n\nThe docs editor package also includes a standalone report generator for exploring the docs tree across versions.\n\nUse it when you want a repo-local HTML view of:\n\n- books, sections, and pages in one expandable tree-table\n- current-version metadata and version status labels\n- inherited versus authored versus branched page states\n- diff counts for branched pages relative to the earlier authored version\n- per-page version comparison in the side panel\n\nThe wrapper script lives at `website/scripts/docs-report.py`.\n\nFor normal contributor workflow, prefer the repo helper:\n\n```bash\ncd /workspace\npython3 scripts/update-docs-derived-artifacts.py\n```\n\nThat helper centralizes the repo-local behavior around derived docs artifacts.\n\n- the pre-commit hook calls it automatically when staged docs inputs can stale the committed report\n- it stages the refreshed report for you in that hook-driven path\n- the VS Code workspace task `Website: Refresh Docs Derived Artifacts` runs the same helper manually\n\nGenerate the report into the committed output path:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py\n```\n\nThat writes `website-meta/docs-reports/docs-structure-report.html`.\n\nUse check mode in CI or before opening a pull request:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py --check\n```\n\nThat exits non-zero when the committed HTML report is stale.\n\n## Detailed Reference\n\nThe full CLI reference now lives on a separate page so this overview can stay task-focused.\n\nUse [Docs Editor Operation Reference](../docs-editor-operation-reference/) when you need:\n\n- the full global option list\n- forward-impact analysis rules\n- content invariants preserved by the tool\n- real-content stub and inherited-marker behavior\n- preview output details\n- per-entity create, delete, and rename reference behavior\n", "1.0": "+++\ntitle = \"Docs Editor Tool\"\n+++\n\nThe docs editor CLI manages structural website docs changes safely and consistently. For ordinary copy edits inside an existing page, edit the Markdown file directly instead.\n\nPreview is the default mode. Run a command once to inspect the plan, then rerun it with `--apply` when the preview matches what you want.\n\n## Tool Location\n\nThe CLI lives at `website/scripts/docs-editor.py`.\n\nRun it from the `website/` directory:\n\n```bash\ncd website\npython3 scripts/docs-editor.py [global-options] \u003centity\u003e \u003coperation\u003e [operation-options]\n```\n\n## Normal Workflow\n\nUse the tool in this order:\n\n1. run the command in preview mode first\n2. review the planned metadata and file changes\n3. rerun the command with `--apply` when the plan is correct\n4. add `--yes` for destructive apply operations in non-interactive shells\n\nAfter a successful apply, the tool runs docs validation automatically.\n\nThe human-readable preview now shows:\n\n- the operation summary\n- the key metadata for the operation\n- the planned file and nav changes\n\n## What the Tool Handles\n\nThe docs editor supports four entity types:\n\n- versions\n- books\n- sections\n- pages\n\nSupported structural operations include:\n\n- creating\n- deleting\n- materializing inherited landing content\n- moving pages between sections\n- renaming\n\nThe docs editor package also includes a standalone visualization report generator for the docs tree.\n\n## Common Tasks\n\nUse the built-in help when you know the action but not the exact flags:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --help\npython3 scripts/docs-editor.py page create --help\n```\n\nUse these commands as a starting point for the most common workflows:\n\n- add a new page\n- materialize an inherited book landing page\n- move a page to another section\n- rename a page or section\n- create a new docs version that inherits from the latest one\n\n## Example: Create a New Version\n\nThis example:\n\n- creates `0.8` as a new version\n- adds it as to the end of the version list as the newest version (`--latest`)\n- adds the status label `preview` (which is shown in the UI)\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\n## Example: Create a New Book\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\n## Example: Create a Structural-Only Section\n\nThis is useful when you want a navigation group without a section landing page.\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --title \"Authoring And Tooling\" \\\n  --position end \\\n  --structural-only\n```\n\nThat creates the section directory and nav entry without `_index.md` or `_inherit.md`.\n\n## Example: Create a New Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\n## Example: Rename a Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --from website-and-docs-architecture-overview \\\n  --to website-and-docs-system-overview \\\n  --title \"Website And Docs System Overview\"\n```\n\nThat preview is especially useful when a rename may propagate into inherited descendants, because the metadata section shows which later inherited versions will follow the rename.\n\n## Convert an Inherited Page to Real Content\n\nSometimes a later version already has the page path and nav entry, but the page itself is still inherited through an empty `inherit.md` marker.\n\nIn that case, do not use `page create`. The page already exists structurally.\n\nUse `page materialize`:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page materialize \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page materialize \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nThat command:\n\n- removes the empty `inherit.md` marker in that version\n- copies the currently resolved inherited `index.md` content into the page directory\n- lets you optionally replace the page title with `--title`\n\nAfter that, edit the new `index.md` for the version-specific behavior.\n\n## Convert an Inherited Book Landing Page to Real Content\n\nUse `book materialize` when a version inherits a book landing page through `_inherit.md` and needs version-specific copy:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply book materialize \\\n  --version 0.9 \\\n  --book admin-guide\n```\n\nThe command replaces `_inherit.md` with the currently resolved `_index.md` content. Use `--title` to replace its title while materializing.\n\n## Move a Page Between Sections\n\nUse `page move` to move a page within one book while preserving its body content:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page move \\\n  --version 0.9 \\\n  --book admin-guide \\\n  --from-section configuration \\\n  --to-section reference \\\n  --page configuration-key-reference \\\n  --to-page configuration-file-reference \\\n  --position start\n```\n\nThe tool updates both page lists, creates real content at the destination, and removes the source directory. `--to-page` is optional and defaults to the source page slug. `--position` applies to the selected version's destination section.\n\nLater inherited-only versions follow the move automatically. The tool refuses when the destination exists, a later version has authored source content, or a later version lacks the destination section. Update Markdown links and managed redirects separately.\n\n## Convert Real Page Content Back to Inherited Content\n\nIf you no longer need a version-specific page override, you can convert the page back to an inherited marker.\n\nUse `page inherit`:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page inherit \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply --yes page inherit \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nThis is destructive because it removes that version's real `index.md` and replaces it with `inherit.md`.\n\nThe command refuses when no earlier version provides real page content for the same path.\n\nManual fallback if you need finer control:\n\n1. Identify the inherited source page you want to override.\n1. Copy that page's current content into the later version as a starting point.\n1. Replace the later version's empty `inherit.md` with a real `index.md`.\n1. Edit the new `index.md` for the version-specific behavior.\n\nThis is still not a page-creation step. The page identity and nav structure already exist; `page materialize` only turns the inherited marker into authored page content in the selected version.\n\nIf a position selector fails, the CLI also reports the valid sibling slugs so you can retry without opening the nav file first.\n\n## Safety Model\n\nThe docs editor is deliberately conservative.\n\n- preview is the default\n- no files are written unless you pass `--apply`\n- destructive operations require confirmation unless you pass `--yes`\n- docs validation runs automatically after a successful apply\n\n### Refusal Semantics\n\nThe tool refuses destructive operations when they would silently rewrite newer authored content.\n\nTypical refusal case:\n\n- an older version rename would force changes into a later version that already has real content at the affected path\n\nIn that case, the CLI exits non-zero, reports the refusal reason, and leaves the docs tree unchanged.\n\n## Generate a Docs Structure Report\n\nThe docs editor package also includes a standalone report generator for exploring the docs tree across versions.\n\nUse it when you want a repo-local HTML view of:\n\n- books, sections, and pages in one expandable tree-table\n- current-version metadata and version status labels\n- inherited versus authored versus branched page states\n- diff counts for branched pages relative to the earlier authored version\n- per-page version comparison in the side panel\n\nThe wrapper script lives at `website/scripts/docs-report.py`.\n\nFor normal contributor workflow, prefer the repo helper:\n\n```bash\ncd /workspace\npython3 scripts/update-docs-derived-artifacts.py\n```\n\nThat helper centralizes the repo-local behavior around derived docs artifacts.\n\n- the pre-commit hook calls it automatically when staged docs inputs can stale the committed report\n- it stages the refreshed report for you in that hook-driven path\n- the VS Code workspace task `Website: Refresh Docs Derived Artifacts` runs the same helper manually\n\nGenerate the report into the committed output path:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py\n```\n\nThat writes `website-meta/docs-reports/docs-structure-report.html`.\n\nUse check mode in CI or before opening a pull request:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py --check\n```\n\nThat exits non-zero when the committed HTML report is stale.\n\n## Detailed Reference\n\nThe full CLI reference now lives on a separate page so this overview can stay task-focused.\n\nUse [Docs Editor Operation Reference](../docs-editor-operation-reference/) when you need:\n\n- the full global option list\n- forward-impact analysis rules\n- content invariants preserved by the tool\n- real-content stub and inherited-marker behavior\n- preview output details\n- per-entity create, delete, and rename reference behavior\n", "2.0": "+++\ntitle = \"Docs Editor Tool\"\n+++\n\nThe docs editor CLI manages structural website docs changes safely and consistently. For ordinary copy edits inside an existing page, edit the Markdown file directly instead.\n\nPreview is the default mode. Run a command once to inspect the plan, then rerun it with `--apply` when the preview matches what you want.\n\n## Tool Location\n\nThe CLI lives at `website/scripts/docs-editor.py`.\n\nRun it from the `website/` directory:\n\n```bash\ncd website\npython3 scripts/docs-editor.py [global-options] \u003centity\u003e \u003coperation\u003e [operation-options]\n```\n\n## Normal Workflow\n\nUse the tool in this order:\n\n1. run the command in preview mode first\n2. review the planned metadata and file changes\n3. rerun the command with `--apply` when the plan is correct\n4. add `--yes` for destructive apply operations in non-interactive shells\n\nAfter a successful apply, the tool runs docs validation automatically.\n\nThe human-readable preview now shows:\n\n- the operation summary\n- the key metadata for the operation\n- the planned file and nav changes\n\n## What the Tool Handles\n\nThe docs editor supports four entity types:\n\n- versions\n- books\n- sections\n- pages\n\nSupported structural operations include:\n\n- creating\n- deleting\n- materializing inherited landing content\n- moving pages between sections\n- renaming\n\nThe docs editor package also includes a standalone visualization report generator for the docs tree.\n\n## Common Tasks\n\nUse the built-in help when you know the action but not the exact flags:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --help\npython3 scripts/docs-editor.py page create --help\n```\n\nUse these commands as a starting point for the most common workflows:\n\n- add a new page\n- materialize an inherited book landing page\n- move a page to another section\n- rename a page or section\n- create a new docs version that inherits from the latest one\n\n## Example: Create a New Version\n\nThis example:\n\n- creates `0.8` as a new version\n- adds it as to the end of the version list as the newest version (`--latest`)\n- adds the status label `preview` (which is shown in the UI)\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\n## Example: Create a New Book\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\n## Example: Create a Structural-Only Section\n\nThis is useful when you want a navigation group without a section landing page.\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --title \"Authoring And Tooling\" \\\n  --position end \\\n  --structural-only\n```\n\nThat creates the section directory and nav entry without `_index.md` or `_inherit.md`.\n\n## Example: Create a New Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\n## Example: Rename a Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --from website-and-docs-architecture-overview \\\n  --to website-and-docs-system-overview \\\n  --title \"Website And Docs System Overview\"\n```\n\nThat preview is especially useful when a rename may propagate into inherited descendants, because the metadata section shows which later inherited versions will follow the rename.\n\n## Convert an Inherited Page to Real Content\n\nSometimes a later version already has the page path and nav entry, but the page itself is still inherited through an empty `inherit.md` marker.\n\nIn that case, do not use `page create`. The page already exists structurally.\n\nUse `page materialize`:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page materialize \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page materialize \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nThat command:\n\n- removes the empty `inherit.md` marker in that version\n- copies the currently resolved inherited `index.md` content into the page directory\n- lets you optionally replace the page title with `--title`\n\nAfter that, edit the new `index.md` for the version-specific behavior.\n\n## Convert an Inherited Book Landing Page to Real Content\n\nUse `book materialize` when a version inherits a book landing page through `_inherit.md` and needs version-specific copy:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply book materialize \\\n  --version 0.9 \\\n  --book admin-guide\n```\n\nThe command replaces `_inherit.md` with the currently resolved `_index.md` content. Use `--title` to replace its title while materializing.\n\n## Move a Page Between Sections\n\nUse `page move` to move a page within one book while preserving its body content:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page move \\\n  --version 0.9 \\\n  --book admin-guide \\\n  --from-section configuration \\\n  --to-section reference \\\n  --page configuration-key-reference \\\n  --to-page configuration-file-reference \\\n  --position start\n```\n\nThe tool updates both page lists, creates real content at the destination, and removes the source directory. `--to-page` is optional and defaults to the source page slug. `--position` applies to the selected version's destination section.\n\nLater inherited-only versions follow the move automatically. The tool refuses when the destination exists, a later version has authored source content, or a later version lacks the destination section. Update Markdown links and managed redirects separately.\n\n## Convert Real Page Content Back to Inherited Content\n\nIf you no longer need a version-specific page override, you can convert the page back to an inherited marker.\n\nUse `page inherit`:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page inherit \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply --yes page inherit \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nThis is destructive because it removes that version's real `index.md` and replaces it with `inherit.md`.\n\nThe command refuses when no earlier version provides real page content for the same path.\n\nManual fallback if you need finer control:\n\n1. Identify the inherited source page you want to override.\n1. Copy that page's current content into the later version as a starting point.\n1. Replace the later version's empty `inherit.md` with a real `index.md`.\n1. Edit the new `index.md` for the version-specific behavior.\n\nThis is still not a page-creation step. The page identity and nav structure already exist; `page materialize` only turns the inherited marker into authored page content in the selected version.\n\nIf a position selector fails, the CLI also reports the valid sibling slugs so you can retry without opening the nav file first.\n\n## Safety Model\n\nThe docs editor is deliberately conservative.\n\n- preview is the default\n- no files are written unless you pass `--apply`\n- destructive operations require confirmation unless you pass `--yes`\n- docs validation runs automatically after a successful apply\n\n### Refusal Semantics\n\nThe tool refuses destructive operations when they would silently rewrite newer authored content.\n\nTypical refusal case:\n\n- an older version rename would force changes into a later version that already has real content at the affected path\n\nIn that case, the CLI exits non-zero, reports the refusal reason, and leaves the docs tree unchanged.\n\n## Generate a Docs Structure Report\n\nThe docs editor package also includes a standalone report generator for exploring the docs tree across versions.\n\nUse it when you want a repo-local HTML view of:\n\n- books, sections, and pages in one expandable tree-table\n- current-version metadata and version status labels\n- inherited versus authored versus branched page states\n- diff counts for branched pages relative to the earlier authored version\n- per-page version comparison in the side panel\n\nThe wrapper script lives at `website/scripts/docs-report.py`.\n\nFor normal contributor workflow, prefer the repo helper:\n\n```bash\ncd /workspace\npython3 scripts/update-docs-derived-artifacts.py\n```\n\nThat helper centralizes the repo-local behavior around derived docs artifacts.\n\n- the pre-commit hook calls it automatically when staged docs inputs can stale the committed report\n- it stages the refreshed report for you in that hook-driven path\n- the VS Code workspace task `Website: Refresh Docs Derived Artifacts` runs the same helper manually\n\nGenerate the report into the committed output path:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py\n```\n\nThat writes `website-meta/docs-reports/docs-structure-report.html`.\n\nUse check mode in CI or before opening a pull request:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py --check\n```\n\nThat exits non-zero when the committed HTML report is stale.\n\n## Detailed Reference\n\nThe full CLI reference now lives on a separate page so this overview can stay task-focused.\n\nUse [Docs Editor Operation Reference](../docs-editor-operation-reference/) when you need:\n\n- the full global option list\n- forward-impact analysis rules\n- content invariants preserved by the tool\n- real-content stub and inherited-marker behavior\n- preview output details\n- per-entity create, delete, and rename reference behavior\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:website-dev-guide/authoring-and-tooling/docs-editor-operation-reference", "parent_id": "section:website-dev-guide/authoring-and-tooling", "depth": 2, "kind": "page", "label": "docs-editor-operation-reference", "title": "Docs Editor Operation Reference", "path": "website-dev-guide/authoring-and-tooling/docs-editor-operation-reference", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "branched", "source_version": "0.7", "diff_added": 60, "diff_removed": 4}, "0.9": {"state": "branched", "source_version": "0.8", "diff_added": 29, "diff_removed": 5}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "inherited", "source_version": "0.9"}}, "content_versions": {"0.7": "`book create` creates a book folder, writes `_index.md` by default or `_inherit.md` with `--inherit`, and inserts the book into the version nav file. With `--structural-only`, it creates no landing file. `--structural-only` cannot be combined with `--inherit` or `--title`.\n`book rename` renames the book directory, updates `books` ordering plus the associated `sections` and `pages` tables, and propagates inherited-only descendants when allowed. It preserves a structural-only book as structural-only; `--title` is not valid when renaming such a book.\n+++\ntitle = \"Docs Editor Operation Reference\"\n+++\n\nUse this page when you already know you need the docs editor and want the detailed reference behavior.\n\n## Position Selectors\n\nOperations that insert books, sections, or pages use the same position syntax:\n\n- `\u003cindex\u003e`: insert at a zero-based numeric index\n- `before:\u003cslug\u003e`: insert immediately before the existing item\n- `after:\u003cslug\u003e`: insert immediately after the existing item\n- `start`: insert at the beginning\n- `end`: insert at the end\n\nIf the requested selector does not resolve cleanly in the target nav list, the operation refuses instead of guessing.\n\n## Global Options\n\nThe CLI supports these global options:\n\n- `--apply`: write changes to disk instead of previewing them\n- `--yes`: skip confirmation for destructive apply operations\n- `--json`: emit machine-readable preview or result output\n- `--quiet`: reduce non-error output\n- `--verbose`: reserved for future detailed output\n\n## Forward-Impact Analysis\n\nChanges in an older version can affect newer versions that still resolve through the same path. The tool analyzes that forward impact before destructive rename and delete operations.\n\nAffected newer versions fall into these categories:\n\n- inherited-only descendants: newer versions that contain only marker files for the affected path\n- structural descendants: newer versions that keep the path only as structure, without landing-page content\n- modified descendants: newer versions that contain real `_index.md` or `index.md` content at the affected path\n\nDefault behavior:\n\n- inherited-only descendants are updated automatically in apply mode\n- structural descendants are preserved where the operation allows it\n- modified descendants block destructive rename and delete operations\n\n## Content Rules the Tool Preserves\n\nThe docs editor preserves these invariants:\n\n- docs identity remains path-derived\n- `doc_id`, `product_version`, and `aliases` are not introduced\n- page folders contain exactly one of `index.md` or `inherit.md`\n- version and book folders contain exactly one of `_index.md` or `_inherit.md`\n- section folders contain zero or one of `_index.md` or `_inherit.md`\n- `inherit.md` and `_inherit.md` remain empty marker files\n- version order in `website/data/docs-versions.toml` stays canonical\n- nav data remains ordering-only metadata\n\n## Real Content Stubs\n\nWhen the tool creates real content, it writes a minimal front matter stub.\n\nDefaults:\n\n- page `index.md`: `title` defaults to a humanized page slug unless `--title` is provided\n- section `_index.md`: `title` defaults to the section title from nav data unless `--title` is provided\n- book `_index.md`: `title` defaults to a humanized book slug unless `--title` is provided\n- version `_index.md`: `title` defaults to the version label unless `--title` is provided\n\n## Inherited Markers\n\nWhen the tool creates inherited content, it writes:\n\n- empty `inherit.md` files for pages\n- empty `_inherit.md` files for version, book, and section landing pages\n\nNo front matter or body content is written into marker files.\n\n## Output Formats\n\nHuman-readable preview output shows the operation, the target path or version, the planned file changes, and the metadata changes that will be made on apply.\n\nJSON preview output includes:\n\n- `result`\n- `destructive`\n- `apply`\n- `metadata`\n- `changes`\n\nFor propagated destructive operations, `metadata` includes `propagated_versions` when later inherited-only versions will follow the change.\n\n## Operation Reference\n\n### Version Operations\n\n`version create` adds a new docs version, creates the matching content tree, initializes the new version to inherit from the previous version, and creates a matching nav file.\n\nRequired input:\n\n- new version slug\n- one insertion selector: `--after \u003cexisting-version\u003e` or `--latest`\n\nOptional input:\n\n- `--label \u003clabel\u003e`\n- `--status \u003cstatus\u003e`: optional UI label appended in parentheses after the version label, for example `preview` or `current`\n- `--visible true|false`\n- `--searchable true|false`\n- `--set-current`\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 1.2 --after 1.1 --label \"1.2\"\n```\n\nBehavior:\n\n1. inserts the new version into `website/data/docs-versions.toml`\n2. creates `website/content/docs/\u003cnew-version\u003e/`\n3. creates `website/data/docs-nav/\u003cnew-version\u003e.toml` from the previous version's nav data\n4. mirrors the previous version's docs tree shape\n5. creates inherited markers instead of copying authored content\n\nBootstrap behavior:\n\n- if `docs-versions.toml` has no declared versions, `--latest` bootstraps the first version instead of inheriting from a base version\n- in that case, the tool creates an authored version root with `_index.md`, creates an empty nav file, and sets the new version as `current`\n- this bootstrap path only works for a truly empty docs workspace; if version directories or version nav files still exist on disk, reconcile or remove them first\n\nImportant details:\n\n- the new version slug must not collide with an existing version\n- the reference version must exist\n- `status` is display metadata only; it does not decide which version is current\n- the actual current docs version is controlled by the top-level `current = \"\u003cslug\u003e\"` entry in `website/data/docs-versions.toml`\n- the current docs version changes only when `--set-current` is passed\n- `searchable` defaults to `false` unless explicitly set otherwise\n\n`version delete` removes a version entry, its nav file, and its content directory.\n\nRequired input:\n\n- version slug\n\nOptional input:\n\n- `--new-current \u003cversion\u003e` when deleting the current version\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version delete 1.1\n```\n\nBehavior:\n\n1. removes the version from `website/data/docs-versions.toml`\n2. removes `website/data/docs-nav/\u003cversion\u003e.toml`\n3. removes `website/content/docs/\u003cversion\u003e/`\n4. revalidates inheritance resolution across remaining versions\n\nRefusal cases:\n\n- the version does not exist\n- the version is current and `--new-current` was not supplied\n- `--new-current` points to the deleted version\n- `--new-current` does not exist after deletion\n- `--new-current` was supplied while deleting a non-current version\n\n### Book Operations\n\n`book create` creates a book folder, writes `_index.md` by default or `_inherit.md` with `--inherit`, and inserts the book into the version nav file.\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create --version 1.1 --book tutorials --title \"Tutorials\" --position end\n```\n\n`book delete` removes the book folder, the book entry in nav data, and the matching `sections.\u003cbook\u003e` and `pages.\u003cbook\u003e` data.\n\n`book rename` renames the book directory, updates `books` ordering plus the associated `sections` and `pages` tables, and propagates inherited-only descendants when allowed.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book rename --version 1.1 --from end-user --to user-guide --title \"User Guide\"\n```\n\n### Section Operations\n\n`section create` creates a section directory, adds a section entry in nav data, and initializes an empty `pages.\u003cbook\u003e.\u003csection\u003e.items` array.\n\nBy default it creates `_index.md`. With `--inherit`, it creates `_inherit.md`. With `--structural-only`, it creates no landing file. Optional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create --version 1.1 --book admin --section authentication --title \"Authentication\" --position end\n```\n\n`section delete` removes the section directory, its nav entry, and the matching `pages.\u003cbook\u003e.\u003csection\u003e` table.\n\n`section rename` renames the section directory, updates `sections.\u003cbook\u003e.items`, moves the matching `pages.\u003cbook\u003e.\u003csection\u003e` table to the new key, and preserves structural-only descendants as structural-only when no landing file exists at the renamed path.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section rename --version 1.1 --book admin --from configuration --to authentication --title \"Authentication\"\n```\n\n### Page Operations\n\n`page create` creates the page directory, writes `index.md` by default or `inherit.md` with `--inherit`, and adds the page slug to `pages.\u003cbook\u003e.\u003csection\u003e.items`.\n\nUse `page create` only when the page does not already exist in that version.\n\nIf the page already exists as an inherited page marker:\n\n- the directory already exists\n- the nav entry already exists\n- the page folder contains an empty `inherit.md`\n\nThen the correct workflow is to materialize real content manually:\n\n1. remove the inherited marker\n1. add `index.md`\n1. copy the inherited page body as the starting point\n1. edit that authored copy for the version-specific behavior\n\nThis is intentionally outside the scope of `page create`, because the page identity and nav structure already exist.\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create --version 1.1 --book developer --section architecture --page overview --title \"Architecture Overview\"\n```\n\n`page delete` removes the page directory and the matching page slug from nav data.\n\n`page rename` renames the page directory, updates `pages.\u003cbook\u003e.\u003csection\u003e.items`, and propagates inherited-only descendants when allowed.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename --version 1.1 --book end-user --section getting-started --from install --to setup --title \"Setup Sambee\"\n```\n\n## Notes\n\n- the tool does not edit `website/.generated/` directly\n- the tool does not run `materialize-inherited-docs.py` for you\n- the tool does not edit page body content or offer free-form front matter editing\n", "0.8": "+++\ntitle = \"Docs Editor Operation Reference\"\n+++\n\nUse this page when you already know you need the docs editor and want the detailed reference behavior.\n\n## Position Selectors\n\nOperations that insert books, sections, or pages use the same position syntax:\n\n- `\u003cindex\u003e`: insert at a zero-based numeric index\n- `before:\u003cslug\u003e`: insert immediately before the existing item\n- `after:\u003cslug\u003e`: insert immediately after the existing item\n- `start`: insert at the beginning\n- `end`: insert at the end\n\nIf the requested selector does not resolve cleanly in the target nav list, the operation refuses instead of guessing.\n\n## Global Options\n\nThe CLI supports these global options:\n\n- `--apply`: write changes to disk instead of previewing them\n- `--yes`: skip confirmation for destructive apply operations\n- `--json`: emit machine-readable preview or result output\n- `--quiet`: reduce non-error output\n- `--verbose`: reserved for future detailed output\n\n## Forward-Impact Analysis\n\nChanges in an older version can affect newer versions that still resolve through the same path. The tool analyzes that forward impact before destructive rename and delete operations.\n\nAffected newer versions fall into these categories:\n\n- inherited-only descendants: newer versions that contain only marker files for the affected path\n- structural descendants: newer versions that keep the path only as structure, without landing-page content\n- modified descendants: newer versions that contain real `_index.md` or `index.md` content at the affected path\n\nDefault behavior:\n\n- inherited-only descendants are updated automatically in apply mode\n- structural descendants are preserved where the operation allows it\n- modified descendants block destructive rename and delete operations\n\n## Content Rules the Tool Preserves\n\nThe docs editor preserves these invariants:\n\n- docs identity remains path-derived\n- `doc_id`, `product_version`, and `aliases` are not introduced\n- page folders contain exactly one of `index.md` or `inherit.md`\n- version and book folders contain exactly one of `_index.md` or `_inherit.md`\n- section folders contain zero or one of `_index.md` or `_inherit.md`\n- `inherit.md` and `_inherit.md` remain empty marker files\n- version order in `website/data/docs-versions.toml` stays canonical\n- nav data remains ordering-only metadata\n\n## Real Content Stubs\n\nWhen the tool creates real content, it writes a minimal front matter stub.\n\nDefaults:\n\n- page `index.md`: `title` defaults to a humanized page slug unless `--title` is provided\n- section `_index.md`: `title` defaults to the section title from nav data unless `--title` is provided\n- book `_index.md`: `title` defaults to a humanized book slug unless `--title` is provided\n- version `_index.md`: `title` defaults to the version label unless `--title` is provided\n\n## Inherited Markers\n\nWhen the tool creates inherited content, it writes:\n\n- empty `inherit.md` files for pages\n- empty `_inherit.md` files for version, book, and section landing pages\n\nNo front matter or body content is written into marker files.\n\n## Output Formats\n\nHuman-readable preview output shows the operation, the target path or version, the planned file changes, and the metadata changes that will be made on apply.\n\nJSON preview output includes:\n\n- `result`\n- `destructive`\n- `apply`\n- `metadata`\n- `changes`\n\nFor propagated destructive operations, `metadata` includes `propagated_versions` when later inherited-only versions will follow the change.\n\n## Standalone Report Generator\n\nUse [Docs Editor Tool](../docs-editor-tool/) for the high-level explanation of when to use the report and what it shows.\n\nThis reference section keeps only the CLI-specific behavior.\n\nThe report generator command is `website/scripts/docs-report.py`.\n\nBehavior:\n\n1. reads version metadata, nav files, and docs content directly from the repository\n2. writes `website-meta/docs-reports/docs-structure-report.html` by default\n3. embeds the report data, CSS, and JavaScript into one standalone HTML file\n\nExample:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py\n```\n\nCheck mode compares the current repository state against the committed HTML report and exits non-zero when the report needs regeneration:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py --check\n```\n\n## Operation Reference\n\n### Version Operations\n\n`version create` adds a new docs version, creates the matching content tree, initializes the new version to inherit from the previous version, and creates a matching nav file.\n\nRequired input:\n\n- new version slug\n- one insertion selector: `--after \u003cexisting-version\u003e` or `--latest`\n\nOptional input:\n\n- `--label \u003clabel\u003e`\n- `--status \u003cstatus\u003e`: optional UI label appended in parentheses after the version label, for example `preview` or `current`\n- `--visible true|false`\n- `--searchable true|false`\n- `--set-current`\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 1.2 --after 1.1 --label \"1.2\"\n```\n\nBehavior:\n\n1. inserts the new version into `website/data/docs-versions.toml`\n2. creates `website/content/docs/\u003cnew-version\u003e/`\n3. creates `website/data/docs-nav/\u003cnew-version\u003e.toml` from the previous version's nav data\n4. mirrors the previous version's docs tree shape\n5. creates inherited markers instead of copying authored content\n\nBootstrap behavior:\n\n- if `docs-versions.toml` has no declared versions, `--latest` bootstraps the first version instead of inheriting from a base version\n- in that case, the tool creates an authored version root with `_index.md`, creates an empty nav file, and sets the new version as `current`\n- this bootstrap path only works for a truly empty docs workspace; if version directories or version nav files still exist on disk, reconcile or remove them first\n\nImportant details:\n\n- the new version slug must not collide with an existing version\n- the reference version must exist\n- `status` is display metadata only; it does not decide which version is current\n- the actual current docs version is controlled by the top-level `current = \"\u003cslug\u003e\"` entry in `website/data/docs-versions.toml`\n- the current docs version changes only when `--set-current` is passed\n- `searchable` defaults to `false` unless explicitly set otherwise\n\n`version delete` removes a version entry, its nav file, and its content directory.\n\nRequired input:\n\n- version slug\n\nOptional input:\n\n- `--new-current \u003cversion\u003e` when deleting the current version\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version delete 1.1\n```\n\nBehavior:\n\n1. removes the version from `website/data/docs-versions.toml`\n2. removes `website/data/docs-nav/\u003cversion\u003e.toml`\n3. removes `website/content/docs/\u003cversion\u003e/`\n4. revalidates inheritance resolution across remaining versions\n\nRefusal cases:\n\n- the version does not exist\n- the version is current and `--new-current` was not supplied\n- `--new-current` points to the deleted version\n- `--new-current` does not exist after deletion\n- `--new-current` was supplied while deleting a non-current version\n\n### Book Operations\n\n`book create` creates a book folder, writes `_index.md` by default or `_inherit.md` with `--inherit`, and inserts the book into the version nav file.\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create --version 1.1 --book tutorials --title \"Tutorials\" --position end\n```\n\n`book delete` removes the book folder, the book entry in nav data, and the matching `sections.\u003cbook\u003e` and `pages.\u003cbook\u003e` data.\n\n`book rename` renames the book directory, updates `books` ordering plus the associated `sections` and `pages` tables, and propagates inherited-only descendants when allowed.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book rename --version 1.1 --from end-user --to user-guide --title \"User Guide\"\n```\n\n### Section Operations\n\n`section create` creates a section directory, adds a section entry in nav data, and initializes an empty `pages.\u003cbook\u003e.\u003csection\u003e.items` array.\n\nBy default it creates `_index.md`. With `--inherit`, it creates `_inherit.md`. With `--structural-only`, it creates no landing file. Optional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create --version 1.1 --book admin --section authentication --title \"Authentication\" --position end\n```\n\n`section delete` removes the section directory, its nav entry, and the matching `pages.\u003cbook\u003e.\u003csection\u003e` table.\n\n`section rename` renames the section directory, updates `sections.\u003cbook\u003e.items`, moves the matching `pages.\u003cbook\u003e.\u003csection\u003e` table to the new key, and preserves structural-only descendants as structural-only when no landing file exists at the renamed path.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section rename --version 1.1 --book admin --from configuration --to authentication --title \"Authentication\"\n```\n\n### Page Operations\n\n`page create` creates the page directory, writes `index.md` by default or `inherit.md` with `--inherit`, and adds the page slug to `pages.\u003cbook\u003e.\u003csection\u003e.items`.\n\nUse `page create` only when the page does not already exist in that version.\n\nIf the page already exists as an inherited page marker:\n\n- the directory already exists\n- the nav entry already exists\n- the page folder contains an empty `inherit.md`\n\nThen use `page materialize` instead of `page create`.\n\n`page materialize` replaces `inherit.md` with a real `index.md`, using the currently resolved inherited page content as the starting point.\n\nOptional input:\n\n- `--title \u003ctitle\u003e`: replace the inherited page title while materializing the real content\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page materialize --version 0.8 --book website-dev-guide --section docs-platform --page website-and-docs-architecture-overview\n```\n\nManual fallback if you need to control the copy step yourself:\n\n1. remove the inherited marker\n1. add `index.md`\n1. copy the inherited page body as the starting point\n1. edit that authored copy for the version-specific behavior\n\nThis remains outside the scope of `page create`, because the page identity and nav structure already exist.\n\n`page inherit` does the reverse: it replaces a real `index.md` in the selected version with `inherit.md` so the page resolves from an earlier authored version again.\n\nImportant details:\n\n- it is destructive because it removes that version's authored page content\n- apply mode requires `--yes` in non-interactive shells\n- it refuses when no earlier version resolves the same path to real `index.md` content\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply --yes page inherit --version 0.8 --book website-dev-guide --section docs-platform --page website-and-docs-architecture-overview\n```\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create --version 1.1 --book developer --section architecture --page overview --title \"Architecture Overview\"\n```\n\n`page delete` removes the page directory and the matching page slug from nav data.\n\n`page rename` renames the page directory, updates `pages.\u003cbook\u003e.\u003csection\u003e.items`, and propagates inherited-only descendants when allowed.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename --version 1.1 --book end-user --section getting-started --from install --to setup --title \"Setup Sambee\"\n```\n\n## Notes\n\n- the tool does not edit `website/.generated/` directly\n- the tool does not run `materialize-inherited-docs.py` for you\n- the tool does not edit page body content or offer free-form front matter editing\n", "0.9": "+++\ntitle = \"Docs Editor Operation Reference\"\n+++\n\nUse this page when you already know you need the docs editor and want the detailed reference behavior.\n\n## Position Selectors\n\nOperations that insert books, sections, or pages use the same position syntax:\n\n- `\u003cindex\u003e`: insert at a zero-based numeric index\n- `before:\u003cslug\u003e`: insert immediately before the existing item\n- `after:\u003cslug\u003e`: insert immediately after the existing item\n- `start`: insert at the beginning\n- `end`: insert at the end\n\nIf the requested selector does not resolve cleanly in the target nav list, the operation refuses instead of guessing.\n\n## Global Options\n\nThe CLI supports these global options:\n\n- `--apply`: write changes to disk instead of previewing them\n- `--yes`: skip confirmation for destructive apply operations\n- `--json`: emit machine-readable preview or result output\n- `--quiet`: reduce non-error output\n- `--verbose`: reserved for future detailed output\n\n## Forward-Impact Analysis\n\nChanges in an older version can affect newer versions that still resolve through the same path. The tool analyzes that forward impact before destructive rename and delete operations.\n\nAffected newer versions fall into these categories:\n\n- inherited-only descendants: newer versions that contain only marker files for the affected path\n- structural descendants: newer versions that keep the path only as structure, without landing-page content\n- modified descendants: newer versions that contain real `_index.md` or `index.md` content at the affected path\n\nDefault behavior:\n\n- inherited-only descendants are updated automatically in apply mode\n- structural descendants are preserved where the operation allows it\n- modified descendants block destructive rename and delete operations\n\n## Content Rules the Tool Preserves\n\nThe docs editor preserves these invariants:\n\n- docs identity remains path-derived\n- `doc_id`, `product_version`, and `aliases` are not introduced\n- page folders contain exactly one of `index.md` or `inherit.md`\n- version and book folders contain exactly one of `_index.md` or `_inherit.md`\n- section folders contain zero or one of `_index.md` or `_inherit.md`\n- `inherit.md` and `_inherit.md` remain empty marker files\n- version order in `website/data/docs-versions.toml` stays canonical\n- nav data remains ordering-only metadata\n\n## Real Content Stubs\n\nWhen the tool creates real content, it writes a minimal front matter stub.\n\nDefaults:\n\n- page `index.md`: `title` defaults to a humanized page slug unless `--title` is provided\n- section `_index.md`: `title` defaults to the section title from nav data unless `--title` is provided\n- book `_index.md`: `title` defaults to a humanized book slug unless `--title` is provided\n- version `_index.md`: `title` defaults to the version label unless `--title` is provided\n\n## Inherited Markers\n\nWhen the tool creates inherited content, it writes:\n\n- empty `inherit.md` files for pages\n- empty `_inherit.md` files for version, book, and section landing pages\n\nNo front matter or body content is written into marker files.\n\n## Output Formats\n\nHuman-readable preview output shows the operation, the target path or version, the planned file changes, and the metadata changes that will be made on apply.\n\nJSON preview output includes:\n\n- `result`\n- `destructive`\n- `apply`\n- `metadata`\n- `changes`\n\nFor propagated destructive operations, `metadata` includes `propagated_versions` when later inherited-only versions will follow the change.\n\n## Standalone Report Generator\n\nUse [Docs Editor Tool](../docs-editor-tool/) for the high-level explanation of when to use the report and what it shows.\n\nThis reference section keeps only the CLI-specific behavior.\n\nThe report generator command is `website/scripts/docs-report.py`.\n\nBehavior:\n\n1. reads version metadata, nav files, and docs content directly from the repository\n2. writes `website-meta/docs-reports/docs-structure-report.html` by default\n3. embeds the report data, CSS, and JavaScript into one standalone HTML file\n\nExample:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py\n```\n\nCheck mode compares the current repository state against the committed HTML report and exits non-zero when the report needs regeneration:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py --check\n```\n\n## Operation Reference\n\n### Version Operations\n\n`version create` adds a new docs version, creates the matching content tree, initializes the new version to inherit from the previous version, and creates a matching nav file.\n\nRequired input:\n\n- new version slug\n- one insertion selector: `--after \u003cexisting-version\u003e` or `--latest`\n\nOptional input:\n\n- `--label \u003clabel\u003e`\n- `--status \u003cstatus\u003e`: optional UI label appended in parentheses after the version label, for example `preview` or `current`\n- `--visible true|false`\n- `--searchable true|false`\n- `--set-current`\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 1.2 --after 1.1 --label \"1.2\"\n```\n\nBehavior:\n\n1. inserts the new version into `website/data/docs-versions.toml`\n2. creates `website/content/docs/\u003cnew-version\u003e/`\n3. creates `website/data/docs-nav/\u003cnew-version\u003e.toml` from the previous version's nav data\n4. mirrors the previous version's docs tree shape\n5. creates inherited markers instead of copying authored content\n\nBootstrap behavior:\n\n- if `docs-versions.toml` has no declared versions, `--latest` bootstraps the first version instead of inheriting from a base version\n- in that case, the tool creates an authored version root with `_index.md`, creates an empty nav file, and sets the new version as `current`\n- this bootstrap path only works for a truly empty docs workspace; if version directories or version nav files still exist on disk, reconcile or remove them first\n\nImportant details:\n\n- the new version slug must not collide with an existing version\n- the reference version must exist\n- `status` is display metadata only; it does not decide which version is current\n- the actual current docs version is controlled by the top-level `current = \"\u003cslug\u003e\"` entry in `website/data/docs-versions.toml`\n- the current docs version changes only when `--set-current` is passed\n- `searchable` defaults to `false` unless explicitly set otherwise\n\n`version delete` removes a version entry, its nav file, and its content directory.\n\nRequired input:\n\n- version slug\n\nOptional input:\n\n- `--new-current \u003cversion\u003e` when deleting the current version\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version delete 1.1\n```\n\nBehavior:\n\n1. removes the version from `website/data/docs-versions.toml`\n2. removes `website/data/docs-nav/\u003cversion\u003e.toml`\n3. removes `website/content/docs/\u003cversion\u003e/`\n4. revalidates inheritance resolution across remaining versions\n\nRefusal cases:\n\n- the version does not exist\n- the version is current and `--new-current` was not supplied\n- `--new-current` points to the deleted version\n- `--new-current` does not exist after deletion\n- `--new-current` was supplied while deleting a non-current version\n\n### Book Operations\n\n`book create` creates a book folder, writes `_index.md` by default or `_inherit.md` with `--inherit`, and inserts the book into the version nav file.\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create --version 1.1 --book tutorials --title \"Tutorials\" --position end\n```\n\n`book delete` removes the book folder, the book entry in nav data, and the matching `sections.\u003cbook\u003e` and `pages.\u003cbook\u003e` data.\n\n`book rename` renames the book directory, updates `books` ordering plus the associated `sections` and `pages` tables, and propagates inherited-only descendants when allowed.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book rename --version 1.1 --from end-user --to user-guide --title \"User Guide\"\n```\n\n`book materialize` replaces an inherited book `_inherit.md` marker with a real `_index.md` using the currently resolved landing-page content. Use `--title` to replace the title while materializing.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book materialize --version 0.9 --book admin-guide\n```\n\n### Section Operations\n\n`section create` creates a section directory, adds a section entry in nav data, and initializes an empty `pages.\u003cbook\u003e.\u003csection\u003e.items` array.\n\nBy default it creates `_index.md`. With `--inherit`, it creates `_inherit.md`. With `--structural-only`, it creates no landing file. Optional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create --version 1.1 --book admin --section authentication --title \"Authentication\" --position end\n```\n\n`section delete` removes the section directory, its nav entry, and the matching `pages.\u003cbook\u003e.\u003csection\u003e` table.\n\n`section rename` renames the section directory, updates `sections.\u003cbook\u003e.items`, moves the matching `pages.\u003cbook\u003e.\u003csection\u003e` table to the new key, and preserves structural-only descendants as structural-only when no landing file exists at the renamed path.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section rename --version 1.1 --book admin --from configuration --to authentication --title \"Authentication\"\n```\n\n### Page Operations\n\n`page create` creates the page directory, writes `index.md` by default or `inherit.md` with `--inherit`, and adds the page slug to `pages.\u003cbook\u003e.\u003csection\u003e.items`.\n\nUse `page create` only when the page does not already exist in that version.\n\nIf the page already exists as an inherited page marker:\n\n- the directory already exists\n- the nav entry already exists\n- the page folder contains an empty `inherit.md`\n\nThen use `page materialize` instead of `page create`.\n\n`page materialize` replaces `inherit.md` with a real `index.md`, using the currently resolved inherited page content as the starting point.\n\nOptional input:\n\n- `--title \u003ctitle\u003e`: replace the inherited page title while materializing the real content\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page materialize --version 0.8 --book website-dev-guide --section docs-platform --page website-and-docs-architecture-overview\n```\n\nManual fallback if you need to control the copy step yourself:\n\n1. remove the inherited marker\n1. add `index.md`\n1. copy the inherited page body as the starting point\n1. edit that authored copy for the version-specific behavior\n\nThis remains outside the scope of `page create`, because the page identity and nav structure already exist.\n\n`page inherit` does the reverse: it replaces a real `index.md` in the selected version with `inherit.md` so the page resolves from an earlier authored version again.\n\nImportant details:\n\n- it is destructive because it removes that version's authored page content\n- apply mode requires `--yes` in non-interactive shells\n- it refuses when no earlier version resolves the same path to real `index.md` content\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply --yes page inherit --version 0.8 --book website-dev-guide --section docs-platform --page website-and-docs-architecture-overview\n```\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create --version 1.1 --book developer --section architecture --page overview --title \"Architecture Overview\"\n```\n\n`page delete` removes the page directory and the matching page slug from nav data.\n\n`page rename` renames the page directory, updates `pages.\u003cbook\u003e.\u003csection\u003e.items`, and propagates inherited-only descendants when allowed.\n\nWhen a later version has independently authored the page, include it with `--also-version` to rename both versions in one atomic operation. Repeat the option for each independently authored version. The tool continues to move inherited-only versions automatically.\n\nA later version may already use the destination slug when it no longer contains the old slug. The tool refuses a version that contains both slugs, because that is an ambiguous page collision.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename --version 1.1 --also-version 1.3 --book end-user --section getting-started --from install --to setup --title \"Setup Sambee\"\n```\n\n`page move` moves a page to another section in the same book. It updates both page lists, materializes the selected version's destination page, and removes the source directory. `--to-page` optionally changes the slug; otherwise the source slug is retained. `--position` controls the destination order in the selected version.\n\nInherited-only descendants move automatically. The operation refuses if the destination exists, a later source page has real content, or a later version lacks the destination section. Links and managed redirects remain explicit content or deployment changes.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page move --version 0.9 --book admin-guide --from-section configuration --to-section reference --page configuration-key-reference --to-page configuration-file-reference --position start\n```\n\n## Notes\n\n- the tool does not edit `website/.generated/` directly\n- the tool does not run `materialize-inherited-docs.py` for you\n- the tool does not edit page body content or offer free-form front matter editing\n", "1.0": "+++\ntitle = \"Docs Editor Operation Reference\"\n+++\n\nUse this page when you already know you need the docs editor and want the detailed reference behavior.\n\n## Position Selectors\n\nOperations that insert books, sections, or pages use the same position syntax:\n\n- `\u003cindex\u003e`: insert at a zero-based numeric index\n- `before:\u003cslug\u003e`: insert immediately before the existing item\n- `after:\u003cslug\u003e`: insert immediately after the existing item\n- `start`: insert at the beginning\n- `end`: insert at the end\n\nIf the requested selector does not resolve cleanly in the target nav list, the operation refuses instead of guessing.\n\n## Global Options\n\nThe CLI supports these global options:\n\n- `--apply`: write changes to disk instead of previewing them\n- `--yes`: skip confirmation for destructive apply operations\n- `--json`: emit machine-readable preview or result output\n- `--quiet`: reduce non-error output\n- `--verbose`: reserved for future detailed output\n\n## Forward-Impact Analysis\n\nChanges in an older version can affect newer versions that still resolve through the same path. The tool analyzes that forward impact before destructive rename and delete operations.\n\nAffected newer versions fall into these categories:\n\n- inherited-only descendants: newer versions that contain only marker files for the affected path\n- structural descendants: newer versions that keep the path only as structure, without landing-page content\n- modified descendants: newer versions that contain real `_index.md` or `index.md` content at the affected path\n\nDefault behavior:\n\n- inherited-only descendants are updated automatically in apply mode\n- structural descendants are preserved where the operation allows it\n- modified descendants block destructive rename and delete operations\n\n## Content Rules the Tool Preserves\n\nThe docs editor preserves these invariants:\n\n- docs identity remains path-derived\n- `doc_id`, `product_version`, and `aliases` are not introduced\n- page folders contain exactly one of `index.md` or `inherit.md`\n- version and book folders contain exactly one of `_index.md` or `_inherit.md`\n- section folders contain zero or one of `_index.md` or `_inherit.md`\n- `inherit.md` and `_inherit.md` remain empty marker files\n- version order in `website/data/docs-versions.toml` stays canonical\n- nav data remains ordering-only metadata\n\n## Real Content Stubs\n\nWhen the tool creates real content, it writes a minimal front matter stub.\n\nDefaults:\n\n- page `index.md`: `title` defaults to a humanized page slug unless `--title` is provided\n- section `_index.md`: `title` defaults to the section title from nav data unless `--title` is provided\n- book `_index.md`: `title` defaults to a humanized book slug unless `--title` is provided\n- version `_index.md`: `title` defaults to the version label unless `--title` is provided\n\n## Inherited Markers\n\nWhen the tool creates inherited content, it writes:\n\n- empty `inherit.md` files for pages\n- empty `_inherit.md` files for version, book, and section landing pages\n\nNo front matter or body content is written into marker files.\n\n## Output Formats\n\nHuman-readable preview output shows the operation, the target path or version, the planned file changes, and the metadata changes that will be made on apply.\n\nJSON preview output includes:\n\n- `result`\n- `destructive`\n- `apply`\n- `metadata`\n- `changes`\n\nFor propagated destructive operations, `metadata` includes `propagated_versions` when later inherited-only versions will follow the change.\n\n## Standalone Report Generator\n\nUse [Docs Editor Tool](../docs-editor-tool/) for the high-level explanation of when to use the report and what it shows.\n\nThis reference section keeps only the CLI-specific behavior.\n\nThe report generator command is `website/scripts/docs-report.py`.\n\nBehavior:\n\n1. reads version metadata, nav files, and docs content directly from the repository\n2. writes `website-meta/docs-reports/docs-structure-report.html` by default\n3. embeds the report data, CSS, and JavaScript into one standalone HTML file\n\nExample:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py\n```\n\nCheck mode compares the current repository state against the committed HTML report and exits non-zero when the report needs regeneration:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py --check\n```\n\n## Operation Reference\n\n### Version Operations\n\n`version create` adds a new docs version, creates the matching content tree, initializes the new version to inherit from the previous version, and creates a matching nav file.\n\nRequired input:\n\n- new version slug\n- one insertion selector: `--after \u003cexisting-version\u003e` or `--latest`\n\nOptional input:\n\n- `--label \u003clabel\u003e`\n- `--status \u003cstatus\u003e`: optional UI label appended in parentheses after the version label, for example `preview` or `current`\n- `--visible true|false`\n- `--searchable true|false`\n- `--set-current`\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 1.2 --after 1.1 --label \"1.2\"\n```\n\nBehavior:\n\n1. inserts the new version into `website/data/docs-versions.toml`\n2. creates `website/content/docs/\u003cnew-version\u003e/`\n3. creates `website/data/docs-nav/\u003cnew-version\u003e.toml` from the previous version's nav data\n4. mirrors the previous version's docs tree shape\n5. creates inherited markers instead of copying authored content\n\nBootstrap behavior:\n\n- if `docs-versions.toml` has no declared versions, `--latest` bootstraps the first version instead of inheriting from a base version\n- in that case, the tool creates an authored version root with `_index.md`, creates an empty nav file, and sets the new version as `current`\n- this bootstrap path only works for a truly empty docs workspace; if version directories or version nav files still exist on disk, reconcile or remove them first\n\nImportant details:\n\n- the new version slug must not collide with an existing version\n- the reference version must exist\n- `status` is display metadata only; it does not decide which version is current\n- the actual current docs version is controlled by the top-level `current = \"\u003cslug\u003e\"` entry in `website/data/docs-versions.toml`\n- the current docs version changes only when `--set-current` is passed\n- `searchable` defaults to `false` unless explicitly set otherwise\n\n`version delete` removes a version entry, its nav file, and its content directory.\n\nRequired input:\n\n- version slug\n\nOptional input:\n\n- `--new-current \u003cversion\u003e` when deleting the current version\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version delete 1.1\n```\n\nBehavior:\n\n1. removes the version from `website/data/docs-versions.toml`\n2. removes `website/data/docs-nav/\u003cversion\u003e.toml`\n3. removes `website/content/docs/\u003cversion\u003e/`\n4. revalidates inheritance resolution across remaining versions\n\nRefusal cases:\n\n- the version does not exist\n- the version is current and `--new-current` was not supplied\n- `--new-current` points to the deleted version\n- `--new-current` does not exist after deletion\n- `--new-current` was supplied while deleting a non-current version\n\n### Book Operations\n\n`book create` creates a book folder, writes `_index.md` by default or `_inherit.md` with `--inherit`, and inserts the book into the version nav file.\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create --version 1.1 --book tutorials --title \"Tutorials\" --position end\n```\n\n`book delete` removes the book folder, the book entry in nav data, and the matching `sections.\u003cbook\u003e` and `pages.\u003cbook\u003e` data.\n\n`book rename` renames the book directory, updates `books` ordering plus the associated `sections` and `pages` tables, and propagates inherited-only descendants when allowed.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book rename --version 1.1 --from end-user --to user-guide --title \"User Guide\"\n```\n\n`book materialize` replaces an inherited book `_inherit.md` marker with a real `_index.md` using the currently resolved landing-page content. Use `--title` to replace the title while materializing.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book materialize --version 0.9 --book admin-guide\n```\n\n### Section Operations\n\n`section create` creates a section directory, adds a section entry in nav data, and initializes an empty `pages.\u003cbook\u003e.\u003csection\u003e.items` array.\n\nBy default it creates `_index.md`. With `--inherit`, it creates `_inherit.md`. With `--structural-only`, it creates no landing file. Optional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create --version 1.1 --book admin --section authentication --title \"Authentication\" --position end\n```\n\n`section delete` removes the section directory, its nav entry, and the matching `pages.\u003cbook\u003e.\u003csection\u003e` table.\n\n`section rename` renames the section directory, updates `sections.\u003cbook\u003e.items`, moves the matching `pages.\u003cbook\u003e.\u003csection\u003e` table to the new key, and preserves structural-only descendants as structural-only when no landing file exists at the renamed path.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section rename --version 1.1 --book admin --from configuration --to authentication --title \"Authentication\"\n```\n\n### Page Operations\n\n`page create` creates the page directory, writes `index.md` by default or `inherit.md` with `--inherit`, and adds the page slug to `pages.\u003cbook\u003e.\u003csection\u003e.items`.\n\nUse `page create` only when the page does not already exist in that version.\n\nIf the page already exists as an inherited page marker:\n\n- the directory already exists\n- the nav entry already exists\n- the page folder contains an empty `inherit.md`\n\nThen use `page materialize` instead of `page create`.\n\n`page materialize` replaces `inherit.md` with a real `index.md`, using the currently resolved inherited page content as the starting point.\n\nOptional input:\n\n- `--title \u003ctitle\u003e`: replace the inherited page title while materializing the real content\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page materialize --version 0.8 --book website-dev-guide --section docs-platform --page website-and-docs-architecture-overview\n```\n\nManual fallback if you need to control the copy step yourself:\n\n1. remove the inherited marker\n1. add `index.md`\n1. copy the inherited page body as the starting point\n1. edit that authored copy for the version-specific behavior\n\nThis remains outside the scope of `page create`, because the page identity and nav structure already exist.\n\n`page inherit` does the reverse: it replaces a real `index.md` in the selected version with `inherit.md` so the page resolves from an earlier authored version again.\n\nImportant details:\n\n- it is destructive because it removes that version's authored page content\n- apply mode requires `--yes` in non-interactive shells\n- it refuses when no earlier version resolves the same path to real `index.md` content\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply --yes page inherit --version 0.8 --book website-dev-guide --section docs-platform --page website-and-docs-architecture-overview\n```\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create --version 1.1 --book developer --section architecture --page overview --title \"Architecture Overview\"\n```\n\n`page delete` removes the page directory and the matching page slug from nav data.\n\n`page rename` renames the page directory, updates `pages.\u003cbook\u003e.\u003csection\u003e.items`, and propagates inherited-only descendants when allowed.\n\nWhen a later version has independently authored the page, include it with `--also-version` to rename both versions in one atomic operation. Repeat the option for each independently authored version. The tool continues to move inherited-only versions automatically.\n\nA later version may already use the destination slug when it no longer contains the old slug. The tool refuses a version that contains both slugs, because that is an ambiguous page collision.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename --version 1.1 --also-version 1.3 --book end-user --section getting-started --from install --to setup --title \"Setup Sambee\"\n```\n\n`page move` moves a page to another section in the same book. It updates both page lists, materializes the selected version's destination page, and removes the source directory. `--to-page` optionally changes the slug; otherwise the source slug is retained. `--position` controls the destination order in the selected version.\n\nInherited-only descendants move automatically. The operation refuses if the destination exists, a later source page has real content, or a later version lacks the destination section. Links and managed redirects remain explicit content or deployment changes.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page move --version 0.9 --book admin-guide --from-section configuration --to-section reference --page configuration-key-reference --to-page configuration-file-reference --position start\n```\n\n## Notes\n\n- the tool does not edit `website/.generated/` directly\n- the tool does not run `materialize-inherited-docs.py` for you\n- the tool does not edit page body content or offer free-form front matter editing\n", "2.0": "+++\ntitle = \"Docs Editor Operation Reference\"\n+++\n\nUse this page when you already know you need the docs editor and want the detailed reference behavior.\n\n## Position Selectors\n\nOperations that insert books, sections, or pages use the same position syntax:\n\n- `\u003cindex\u003e`: insert at a zero-based numeric index\n- `before:\u003cslug\u003e`: insert immediately before the existing item\n- `after:\u003cslug\u003e`: insert immediately after the existing item\n- `start`: insert at the beginning\n- `end`: insert at the end\n\nIf the requested selector does not resolve cleanly in the target nav list, the operation refuses instead of guessing.\n\n## Global Options\n\nThe CLI supports these global options:\n\n- `--apply`: write changes to disk instead of previewing them\n- `--yes`: skip confirmation for destructive apply operations\n- `--json`: emit machine-readable preview or result output\n- `--quiet`: reduce non-error output\n- `--verbose`: reserved for future detailed output\n\n## Forward-Impact Analysis\n\nChanges in an older version can affect newer versions that still resolve through the same path. The tool analyzes that forward impact before destructive rename and delete operations.\n\nAffected newer versions fall into these categories:\n\n- inherited-only descendants: newer versions that contain only marker files for the affected path\n- structural descendants: newer versions that keep the path only as structure, without landing-page content\n- modified descendants: newer versions that contain real `_index.md` or `index.md` content at the affected path\n\nDefault behavior:\n\n- inherited-only descendants are updated automatically in apply mode\n- structural descendants are preserved where the operation allows it\n- modified descendants block destructive rename and delete operations\n\n## Content Rules the Tool Preserves\n\nThe docs editor preserves these invariants:\n\n- docs identity remains path-derived\n- `doc_id`, `product_version`, and `aliases` are not introduced\n- page folders contain exactly one of `index.md` or `inherit.md`\n- version and book folders contain exactly one of `_index.md` or `_inherit.md`\n- section folders contain zero or one of `_index.md` or `_inherit.md`\n- `inherit.md` and `_inherit.md` remain empty marker files\n- version order in `website/data/docs-versions.toml` stays canonical\n- nav data remains ordering-only metadata\n\n## Real Content Stubs\n\nWhen the tool creates real content, it writes a minimal front matter stub.\n\nDefaults:\n\n- page `index.md`: `title` defaults to a humanized page slug unless `--title` is provided\n- section `_index.md`: `title` defaults to the section title from nav data unless `--title` is provided\n- book `_index.md`: `title` defaults to a humanized book slug unless `--title` is provided\n- version `_index.md`: `title` defaults to the version label unless `--title` is provided\n\n## Inherited Markers\n\nWhen the tool creates inherited content, it writes:\n\n- empty `inherit.md` files for pages\n- empty `_inherit.md` files for version, book, and section landing pages\n\nNo front matter or body content is written into marker files.\n\n## Output Formats\n\nHuman-readable preview output shows the operation, the target path or version, the planned file changes, and the metadata changes that will be made on apply.\n\nJSON preview output includes:\n\n- `result`\n- `destructive`\n- `apply`\n- `metadata`\n- `changes`\n\nFor propagated destructive operations, `metadata` includes `propagated_versions` when later inherited-only versions will follow the change.\n\n## Standalone Report Generator\n\nUse [Docs Editor Tool](../docs-editor-tool/) for the high-level explanation of when to use the report and what it shows.\n\nThis reference section keeps only the CLI-specific behavior.\n\nThe report generator command is `website/scripts/docs-report.py`.\n\nBehavior:\n\n1. reads version metadata, nav files, and docs content directly from the repository\n2. writes `website-meta/docs-reports/docs-structure-report.html` by default\n3. embeds the report data, CSS, and JavaScript into one standalone HTML file\n\nExample:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py\n```\n\nCheck mode compares the current repository state against the committed HTML report and exits non-zero when the report needs regeneration:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py --check\n```\n\n## Operation Reference\n\n### Version Operations\n\n`version create` adds a new docs version, creates the matching content tree, initializes the new version to inherit from the previous version, and creates a matching nav file.\n\nRequired input:\n\n- new version slug\n- one insertion selector: `--after \u003cexisting-version\u003e` or `--latest`\n\nOptional input:\n\n- `--label \u003clabel\u003e`\n- `--status \u003cstatus\u003e`: optional UI label appended in parentheses after the version label, for example `preview` or `current`\n- `--visible true|false`\n- `--searchable true|false`\n- `--set-current`\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 1.2 --after 1.1 --label \"1.2\"\n```\n\nBehavior:\n\n1. inserts the new version into `website/data/docs-versions.toml`\n2. creates `website/content/docs/\u003cnew-version\u003e/`\n3. creates `website/data/docs-nav/\u003cnew-version\u003e.toml` from the previous version's nav data\n4. mirrors the previous version's docs tree shape\n5. creates inherited markers instead of copying authored content\n\nBootstrap behavior:\n\n- if `docs-versions.toml` has no declared versions, `--latest` bootstraps the first version instead of inheriting from a base version\n- in that case, the tool creates an authored version root with `_index.md`, creates an empty nav file, and sets the new version as `current`\n- this bootstrap path only works for a truly empty docs workspace; if version directories or version nav files still exist on disk, reconcile or remove them first\n\nImportant details:\n\n- the new version slug must not collide with an existing version\n- the reference version must exist\n- `status` is display metadata only; it does not decide which version is current\n- the actual current docs version is controlled by the top-level `current = \"\u003cslug\u003e\"` entry in `website/data/docs-versions.toml`\n- the current docs version changes only when `--set-current` is passed\n- `searchable` defaults to `false` unless explicitly set otherwise\n\n`version delete` removes a version entry, its nav file, and its content directory.\n\nRequired input:\n\n- version slug\n\nOptional input:\n\n- `--new-current \u003cversion\u003e` when deleting the current version\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version delete 1.1\n```\n\nBehavior:\n\n1. removes the version from `website/data/docs-versions.toml`\n2. removes `website/data/docs-nav/\u003cversion\u003e.toml`\n3. removes `website/content/docs/\u003cversion\u003e/`\n4. revalidates inheritance resolution across remaining versions\n\nRefusal cases:\n\n- the version does not exist\n- the version is current and `--new-current` was not supplied\n- `--new-current` points to the deleted version\n- `--new-current` does not exist after deletion\n- `--new-current` was supplied while deleting a non-current version\n\n### Book Operations\n\n`book create` creates a book folder, writes `_index.md` by default or `_inherit.md` with `--inherit`, and inserts the book into the version nav file.\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create --version 1.1 --book tutorials --title \"Tutorials\" --position end\n```\n\n`book delete` removes the book folder, the book entry in nav data, and the matching `sections.\u003cbook\u003e` and `pages.\u003cbook\u003e` data.\n\n`book rename` renames the book directory, updates `books` ordering plus the associated `sections` and `pages` tables, and propagates inherited-only descendants when allowed.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book rename --version 1.1 --from end-user --to user-guide --title \"User Guide\"\n```\n\n`book materialize` replaces an inherited book `_inherit.md` marker with a real `_index.md` using the currently resolved landing-page content. Use `--title` to replace the title while materializing.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book materialize --version 0.9 --book admin-guide\n```\n\n### Section Operations\n\n`section create` creates a section directory, adds a section entry in nav data, and initializes an empty `pages.\u003cbook\u003e.\u003csection\u003e.items` array.\n\nBy default it creates `_index.md`. With `--inherit`, it creates `_inherit.md`. With `--structural-only`, it creates no landing file. Optional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create --version 1.1 --book admin --section authentication --title \"Authentication\" --position end\n```\n\n`section delete` removes the section directory, its nav entry, and the matching `pages.\u003cbook\u003e.\u003csection\u003e` table.\n\n`section rename` renames the section directory, updates `sections.\u003cbook\u003e.items`, moves the matching `pages.\u003cbook\u003e.\u003csection\u003e` table to the new key, and preserves structural-only descendants as structural-only when no landing file exists at the renamed path.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section rename --version 1.1 --book admin --from configuration --to authentication --title \"Authentication\"\n```\n\n### Page Operations\n\n`page create` creates the page directory, writes `index.md` by default or `inherit.md` with `--inherit`, and adds the page slug to `pages.\u003cbook\u003e.\u003csection\u003e.items`.\n\nUse `page create` only when the page does not already exist in that version.\n\nIf the page already exists as an inherited page marker:\n\n- the directory already exists\n- the nav entry already exists\n- the page folder contains an empty `inherit.md`\n\nThen use `page materialize` instead of `page create`.\n\n`page materialize` replaces `inherit.md` with a real `index.md`, using the currently resolved inherited page content as the starting point.\n\nOptional input:\n\n- `--title \u003ctitle\u003e`: replace the inherited page title while materializing the real content\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page materialize --version 0.8 --book website-dev-guide --section docs-platform --page website-and-docs-architecture-overview\n```\n\nManual fallback if you need to control the copy step yourself:\n\n1. remove the inherited marker\n1. add `index.md`\n1. copy the inherited page body as the starting point\n1. edit that authored copy for the version-specific behavior\n\nThis remains outside the scope of `page create`, because the page identity and nav structure already exist.\n\n`page inherit` does the reverse: it replaces a real `index.md` in the selected version with `inherit.md` so the page resolves from an earlier authored version again.\n\nImportant details:\n\n- it is destructive because it removes that version's authored page content\n- apply mode requires `--yes` in non-interactive shells\n- it refuses when no earlier version resolves the same path to real `index.md` content\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply --yes page inherit --version 0.8 --book website-dev-guide --section docs-platform --page website-and-docs-architecture-overview\n```\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create --version 1.1 --book developer --section architecture --page overview --title \"Architecture Overview\"\n```\n\n`page delete` removes the page directory and the matching page slug from nav data.\n\n`page rename` renames the page directory, updates `pages.\u003cbook\u003e.\u003csection\u003e.items`, and propagates inherited-only descendants when allowed.\n\nWhen a later version has independently authored the page, include it with `--also-version` to rename both versions in one atomic operation. Repeat the option for each independently authored version. The tool continues to move inherited-only versions automatically.\n\nA later version may already use the destination slug when it no longer contains the old slug. The tool refuses a version that contains both slugs, because that is an ambiguous page collision.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename --version 1.1 --also-version 1.3 --book end-user --section getting-started --from install --to setup --title \"Setup Sambee\"\n```\n\n`page move` moves a page to another section in the same book. It updates both page lists, materializes the selected version's destination page, and removes the source directory. `--to-page` optionally changes the slug; otherwise the source slug is retained. `--position` controls the destination order in the selected version.\n\nInherited-only descendants move automatically. The operation refuses if the destination exists, a later source page has real content, or a later version lacks the destination section. Links and managed redirects remain explicit content or deployment changes.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page move --version 0.9 --book admin-guide --from-section configuration --to-section reference --page configuration-key-reference --to-page configuration-file-reference --position start\n```\n\n## Notes\n\n- the tool does not edit `website/.generated/` directly\n- the tool does not run `materialize-inherited-docs.py` for you\n- the tool does not edit page body content or offer free-form front matter editing\n"}, "page_contents": {"0.7": "`book create` creates a book folder, writes `_index.md` by default or `_inherit.md` with `--inherit`, and inserts the book into the version nav file. With `--structural-only`, it creates no landing file. `--structural-only` cannot be combined with `--inherit` or `--title`.\n`book rename` renames the book directory, updates `books` ordering plus the associated `sections` and `pages` tables, and propagates inherited-only descendants when allowed. It preserves a structural-only book as structural-only; `--title` is not valid when renaming such a book.\n+++\ntitle = \"Docs Editor Operation Reference\"\n+++\n\nUse this page when you already know you need the docs editor and want the detailed reference behavior.\n\n## Position Selectors\n\nOperations that insert books, sections, or pages use the same position syntax:\n\n- `\u003cindex\u003e`: insert at a zero-based numeric index\n- `before:\u003cslug\u003e`: insert immediately before the existing item\n- `after:\u003cslug\u003e`: insert immediately after the existing item\n- `start`: insert at the beginning\n- `end`: insert at the end\n\nIf the requested selector does not resolve cleanly in the target nav list, the operation refuses instead of guessing.\n\n## Global Options\n\nThe CLI supports these global options:\n\n- `--apply`: write changes to disk instead of previewing them\n- `--yes`: skip confirmation for destructive apply operations\n- `--json`: emit machine-readable preview or result output\n- `--quiet`: reduce non-error output\n- `--verbose`: reserved for future detailed output\n\n## Forward-Impact Analysis\n\nChanges in an older version can affect newer versions that still resolve through the same path. The tool analyzes that forward impact before destructive rename and delete operations.\n\nAffected newer versions fall into these categories:\n\n- inherited-only descendants: newer versions that contain only marker files for the affected path\n- structural descendants: newer versions that keep the path only as structure, without landing-page content\n- modified descendants: newer versions that contain real `_index.md` or `index.md` content at the affected path\n\nDefault behavior:\n\n- inherited-only descendants are updated automatically in apply mode\n- structural descendants are preserved where the operation allows it\n- modified descendants block destructive rename and delete operations\n\n## Content Rules the Tool Preserves\n\nThe docs editor preserves these invariants:\n\n- docs identity remains path-derived\n- `doc_id`, `product_version`, and `aliases` are not introduced\n- page folders contain exactly one of `index.md` or `inherit.md`\n- version and book folders contain exactly one of `_index.md` or `_inherit.md`\n- section folders contain zero or one of `_index.md` or `_inherit.md`\n- `inherit.md` and `_inherit.md` remain empty marker files\n- version order in `website/data/docs-versions.toml` stays canonical\n- nav data remains ordering-only metadata\n\n## Real Content Stubs\n\nWhen the tool creates real content, it writes a minimal front matter stub.\n\nDefaults:\n\n- page `index.md`: `title` defaults to a humanized page slug unless `--title` is provided\n- section `_index.md`: `title` defaults to the section title from nav data unless `--title` is provided\n- book `_index.md`: `title` defaults to a humanized book slug unless `--title` is provided\n- version `_index.md`: `title` defaults to the version label unless `--title` is provided\n\n## Inherited Markers\n\nWhen the tool creates inherited content, it writes:\n\n- empty `inherit.md` files for pages\n- empty `_inherit.md` files for version, book, and section landing pages\n\nNo front matter or body content is written into marker files.\n\n## Output Formats\n\nHuman-readable preview output shows the operation, the target path or version, the planned file changes, and the metadata changes that will be made on apply.\n\nJSON preview output includes:\n\n- `result`\n- `destructive`\n- `apply`\n- `metadata`\n- `changes`\n\nFor propagated destructive operations, `metadata` includes `propagated_versions` when later inherited-only versions will follow the change.\n\n## Operation Reference\n\n### Version Operations\n\n`version create` adds a new docs version, creates the matching content tree, initializes the new version to inherit from the previous version, and creates a matching nav file.\n\nRequired input:\n\n- new version slug\n- one insertion selector: `--after \u003cexisting-version\u003e` or `--latest`\n\nOptional input:\n\n- `--label \u003clabel\u003e`\n- `--status \u003cstatus\u003e`: optional UI label appended in parentheses after the version label, for example `preview` or `current`\n- `--visible true|false`\n- `--searchable true|false`\n- `--set-current`\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 1.2 --after 1.1 --label \"1.2\"\n```\n\nBehavior:\n\n1. inserts the new version into `website/data/docs-versions.toml`\n2. creates `website/content/docs/\u003cnew-version\u003e/`\n3. creates `website/data/docs-nav/\u003cnew-version\u003e.toml` from the previous version's nav data\n4. mirrors the previous version's docs tree shape\n5. creates inherited markers instead of copying authored content\n\nBootstrap behavior:\n\n- if `docs-versions.toml` has no declared versions, `--latest` bootstraps the first version instead of inheriting from a base version\n- in that case, the tool creates an authored version root with `_index.md`, creates an empty nav file, and sets the new version as `current`\n- this bootstrap path only works for a truly empty docs workspace; if version directories or version nav files still exist on disk, reconcile or remove them first\n\nImportant details:\n\n- the new version slug must not collide with an existing version\n- the reference version must exist\n- `status` is display metadata only; it does not decide which version is current\n- the actual current docs version is controlled by the top-level `current = \"\u003cslug\u003e\"` entry in `website/data/docs-versions.toml`\n- the current docs version changes only when `--set-current` is passed\n- `searchable` defaults to `false` unless explicitly set otherwise\n\n`version delete` removes a version entry, its nav file, and its content directory.\n\nRequired input:\n\n- version slug\n\nOptional input:\n\n- `--new-current \u003cversion\u003e` when deleting the current version\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version delete 1.1\n```\n\nBehavior:\n\n1. removes the version from `website/data/docs-versions.toml`\n2. removes `website/data/docs-nav/\u003cversion\u003e.toml`\n3. removes `website/content/docs/\u003cversion\u003e/`\n4. revalidates inheritance resolution across remaining versions\n\nRefusal cases:\n\n- the version does not exist\n- the version is current and `--new-current` was not supplied\n- `--new-current` points to the deleted version\n- `--new-current` does not exist after deletion\n- `--new-current` was supplied while deleting a non-current version\n\n### Book Operations\n\n`book create` creates a book folder, writes `_index.md` by default or `_inherit.md` with `--inherit`, and inserts the book into the version nav file.\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create --version 1.1 --book tutorials --title \"Tutorials\" --position end\n```\n\n`book delete` removes the book folder, the book entry in nav data, and the matching `sections.\u003cbook\u003e` and `pages.\u003cbook\u003e` data.\n\n`book rename` renames the book directory, updates `books` ordering plus the associated `sections` and `pages` tables, and propagates inherited-only descendants when allowed.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book rename --version 1.1 --from end-user --to user-guide --title \"User Guide\"\n```\n\n### Section Operations\n\n`section create` creates a section directory, adds a section entry in nav data, and initializes an empty `pages.\u003cbook\u003e.\u003csection\u003e.items` array.\n\nBy default it creates `_index.md`. With `--inherit`, it creates `_inherit.md`. With `--structural-only`, it creates no landing file. Optional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create --version 1.1 --book admin --section authentication --title \"Authentication\" --position end\n```\n\n`section delete` removes the section directory, its nav entry, and the matching `pages.\u003cbook\u003e.\u003csection\u003e` table.\n\n`section rename` renames the section directory, updates `sections.\u003cbook\u003e.items`, moves the matching `pages.\u003cbook\u003e.\u003csection\u003e` table to the new key, and preserves structural-only descendants as structural-only when no landing file exists at the renamed path.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section rename --version 1.1 --book admin --from configuration --to authentication --title \"Authentication\"\n```\n\n### Page Operations\n\n`page create` creates the page directory, writes `index.md` by default or `inherit.md` with `--inherit`, and adds the page slug to `pages.\u003cbook\u003e.\u003csection\u003e.items`.\n\nUse `page create` only when the page does not already exist in that version.\n\nIf the page already exists as an inherited page marker:\n\n- the directory already exists\n- the nav entry already exists\n- the page folder contains an empty `inherit.md`\n\nThen the correct workflow is to materialize real content manually:\n\n1. remove the inherited marker\n1. add `index.md`\n1. copy the inherited page body as the starting point\n1. edit that authored copy for the version-specific behavior\n\nThis is intentionally outside the scope of `page create`, because the page identity and nav structure already exist.\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create --version 1.1 --book developer --section architecture --page overview --title \"Architecture Overview\"\n```\n\n`page delete` removes the page directory and the matching page slug from nav data.\n\n`page rename` renames the page directory, updates `pages.\u003cbook\u003e.\u003csection\u003e.items`, and propagates inherited-only descendants when allowed.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename --version 1.1 --book end-user --section getting-started --from install --to setup --title \"Setup Sambee\"\n```\n\n## Notes\n\n- the tool does not edit `website/.generated/` directly\n- the tool does not run `materialize-inherited-docs.py` for you\n- the tool does not edit page body content or offer free-form front matter editing\n", "0.8": "+++\ntitle = \"Docs Editor Operation Reference\"\n+++\n\nUse this page when you already know you need the docs editor and want the detailed reference behavior.\n\n## Position Selectors\n\nOperations that insert books, sections, or pages use the same position syntax:\n\n- `\u003cindex\u003e`: insert at a zero-based numeric index\n- `before:\u003cslug\u003e`: insert immediately before the existing item\n- `after:\u003cslug\u003e`: insert immediately after the existing item\n- `start`: insert at the beginning\n- `end`: insert at the end\n\nIf the requested selector does not resolve cleanly in the target nav list, the operation refuses instead of guessing.\n\n## Global Options\n\nThe CLI supports these global options:\n\n- `--apply`: write changes to disk instead of previewing them\n- `--yes`: skip confirmation for destructive apply operations\n- `--json`: emit machine-readable preview or result output\n- `--quiet`: reduce non-error output\n- `--verbose`: reserved for future detailed output\n\n## Forward-Impact Analysis\n\nChanges in an older version can affect newer versions that still resolve through the same path. The tool analyzes that forward impact before destructive rename and delete operations.\n\nAffected newer versions fall into these categories:\n\n- inherited-only descendants: newer versions that contain only marker files for the affected path\n- structural descendants: newer versions that keep the path only as structure, without landing-page content\n- modified descendants: newer versions that contain real `_index.md` or `index.md` content at the affected path\n\nDefault behavior:\n\n- inherited-only descendants are updated automatically in apply mode\n- structural descendants are preserved where the operation allows it\n- modified descendants block destructive rename and delete operations\n\n## Content Rules the Tool Preserves\n\nThe docs editor preserves these invariants:\n\n- docs identity remains path-derived\n- `doc_id`, `product_version`, and `aliases` are not introduced\n- page folders contain exactly one of `index.md` or `inherit.md`\n- version and book folders contain exactly one of `_index.md` or `_inherit.md`\n- section folders contain zero or one of `_index.md` or `_inherit.md`\n- `inherit.md` and `_inherit.md` remain empty marker files\n- version order in `website/data/docs-versions.toml` stays canonical\n- nav data remains ordering-only metadata\n\n## Real Content Stubs\n\nWhen the tool creates real content, it writes a minimal front matter stub.\n\nDefaults:\n\n- page `index.md`: `title` defaults to a humanized page slug unless `--title` is provided\n- section `_index.md`: `title` defaults to the section title from nav data unless `--title` is provided\n- book `_index.md`: `title` defaults to a humanized book slug unless `--title` is provided\n- version `_index.md`: `title` defaults to the version label unless `--title` is provided\n\n## Inherited Markers\n\nWhen the tool creates inherited content, it writes:\n\n- empty `inherit.md` files for pages\n- empty `_inherit.md` files for version, book, and section landing pages\n\nNo front matter or body content is written into marker files.\n\n## Output Formats\n\nHuman-readable preview output shows the operation, the target path or version, the planned file changes, and the metadata changes that will be made on apply.\n\nJSON preview output includes:\n\n- `result`\n- `destructive`\n- `apply`\n- `metadata`\n- `changes`\n\nFor propagated destructive operations, `metadata` includes `propagated_versions` when later inherited-only versions will follow the change.\n\n## Standalone Report Generator\n\nUse [Docs Editor Tool](../docs-editor-tool/) for the high-level explanation of when to use the report and what it shows.\n\nThis reference section keeps only the CLI-specific behavior.\n\nThe report generator command is `website/scripts/docs-report.py`.\n\nBehavior:\n\n1. reads version metadata, nav files, and docs content directly from the repository\n2. writes `website-meta/docs-reports/docs-structure-report.html` by default\n3. embeds the report data, CSS, and JavaScript into one standalone HTML file\n\nExample:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py\n```\n\nCheck mode compares the current repository state against the committed HTML report and exits non-zero when the report needs regeneration:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py --check\n```\n\n## Operation Reference\n\n### Version Operations\n\n`version create` adds a new docs version, creates the matching content tree, initializes the new version to inherit from the previous version, and creates a matching nav file.\n\nRequired input:\n\n- new version slug\n- one insertion selector: `--after \u003cexisting-version\u003e` or `--latest`\n\nOptional input:\n\n- `--label \u003clabel\u003e`\n- `--status \u003cstatus\u003e`: optional UI label appended in parentheses after the version label, for example `preview` or `current`\n- `--visible true|false`\n- `--searchable true|false`\n- `--set-current`\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 1.2 --after 1.1 --label \"1.2\"\n```\n\nBehavior:\n\n1. inserts the new version into `website/data/docs-versions.toml`\n2. creates `website/content/docs/\u003cnew-version\u003e/`\n3. creates `website/data/docs-nav/\u003cnew-version\u003e.toml` from the previous version's nav data\n4. mirrors the previous version's docs tree shape\n5. creates inherited markers instead of copying authored content\n\nBootstrap behavior:\n\n- if `docs-versions.toml` has no declared versions, `--latest` bootstraps the first version instead of inheriting from a base version\n- in that case, the tool creates an authored version root with `_index.md`, creates an empty nav file, and sets the new version as `current`\n- this bootstrap path only works for a truly empty docs workspace; if version directories or version nav files still exist on disk, reconcile or remove them first\n\nImportant details:\n\n- the new version slug must not collide with an existing version\n- the reference version must exist\n- `status` is display metadata only; it does not decide which version is current\n- the actual current docs version is controlled by the top-level `current = \"\u003cslug\u003e\"` entry in `website/data/docs-versions.toml`\n- the current docs version changes only when `--set-current` is passed\n- `searchable` defaults to `false` unless explicitly set otherwise\n\n`version delete` removes a version entry, its nav file, and its content directory.\n\nRequired input:\n\n- version slug\n\nOptional input:\n\n- `--new-current \u003cversion\u003e` when deleting the current version\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version delete 1.1\n```\n\nBehavior:\n\n1. removes the version from `website/data/docs-versions.toml`\n2. removes `website/data/docs-nav/\u003cversion\u003e.toml`\n3. removes `website/content/docs/\u003cversion\u003e/`\n4. revalidates inheritance resolution across remaining versions\n\nRefusal cases:\n\n- the version does not exist\n- the version is current and `--new-current` was not supplied\n- `--new-current` points to the deleted version\n- `--new-current` does not exist after deletion\n- `--new-current` was supplied while deleting a non-current version\n\n### Book Operations\n\n`book create` creates a book folder, writes `_index.md` by default or `_inherit.md` with `--inherit`, and inserts the book into the version nav file.\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create --version 1.1 --book tutorials --title \"Tutorials\" --position end\n```\n\n`book delete` removes the book folder, the book entry in nav data, and the matching `sections.\u003cbook\u003e` and `pages.\u003cbook\u003e` data.\n\n`book rename` renames the book directory, updates `books` ordering plus the associated `sections` and `pages` tables, and propagates inherited-only descendants when allowed.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book rename --version 1.1 --from end-user --to user-guide --title \"User Guide\"\n```\n\n### Section Operations\n\n`section create` creates a section directory, adds a section entry in nav data, and initializes an empty `pages.\u003cbook\u003e.\u003csection\u003e.items` array.\n\nBy default it creates `_index.md`. With `--inherit`, it creates `_inherit.md`. With `--structural-only`, it creates no landing file. Optional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create --version 1.1 --book admin --section authentication --title \"Authentication\" --position end\n```\n\n`section delete` removes the section directory, its nav entry, and the matching `pages.\u003cbook\u003e.\u003csection\u003e` table.\n\n`section rename` renames the section directory, updates `sections.\u003cbook\u003e.items`, moves the matching `pages.\u003cbook\u003e.\u003csection\u003e` table to the new key, and preserves structural-only descendants as structural-only when no landing file exists at the renamed path.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section rename --version 1.1 --book admin --from configuration --to authentication --title \"Authentication\"\n```\n\n### Page Operations\n\n`page create` creates the page directory, writes `index.md` by default or `inherit.md` with `--inherit`, and adds the page slug to `pages.\u003cbook\u003e.\u003csection\u003e.items`.\n\nUse `page create` only when the page does not already exist in that version.\n\nIf the page already exists as an inherited page marker:\n\n- the directory already exists\n- the nav entry already exists\n- the page folder contains an empty `inherit.md`\n\nThen use `page materialize` instead of `page create`.\n\n`page materialize` replaces `inherit.md` with a real `index.md`, using the currently resolved inherited page content as the starting point.\n\nOptional input:\n\n- `--title \u003ctitle\u003e`: replace the inherited page title while materializing the real content\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page materialize --version 0.8 --book website-dev-guide --section docs-platform --page website-and-docs-architecture-overview\n```\n\nManual fallback if you need to control the copy step yourself:\n\n1. remove the inherited marker\n1. add `index.md`\n1. copy the inherited page body as the starting point\n1. edit that authored copy for the version-specific behavior\n\nThis remains outside the scope of `page create`, because the page identity and nav structure already exist.\n\n`page inherit` does the reverse: it replaces a real `index.md` in the selected version with `inherit.md` so the page resolves from an earlier authored version again.\n\nImportant details:\n\n- it is destructive because it removes that version's authored page content\n- apply mode requires `--yes` in non-interactive shells\n- it refuses when no earlier version resolves the same path to real `index.md` content\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply --yes page inherit --version 0.8 --book website-dev-guide --section docs-platform --page website-and-docs-architecture-overview\n```\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create --version 1.1 --book developer --section architecture --page overview --title \"Architecture Overview\"\n```\n\n`page delete` removes the page directory and the matching page slug from nav data.\n\n`page rename` renames the page directory, updates `pages.\u003cbook\u003e.\u003csection\u003e.items`, and propagates inherited-only descendants when allowed.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename --version 1.1 --book end-user --section getting-started --from install --to setup --title \"Setup Sambee\"\n```\n\n## Notes\n\n- the tool does not edit `website/.generated/` directly\n- the tool does not run `materialize-inherited-docs.py` for you\n- the tool does not edit page body content or offer free-form front matter editing\n", "0.9": "+++\ntitle = \"Docs Editor Operation Reference\"\n+++\n\nUse this page when you already know you need the docs editor and want the detailed reference behavior.\n\n## Position Selectors\n\nOperations that insert books, sections, or pages use the same position syntax:\n\n- `\u003cindex\u003e`: insert at a zero-based numeric index\n- `before:\u003cslug\u003e`: insert immediately before the existing item\n- `after:\u003cslug\u003e`: insert immediately after the existing item\n- `start`: insert at the beginning\n- `end`: insert at the end\n\nIf the requested selector does not resolve cleanly in the target nav list, the operation refuses instead of guessing.\n\n## Global Options\n\nThe CLI supports these global options:\n\n- `--apply`: write changes to disk instead of previewing them\n- `--yes`: skip confirmation for destructive apply operations\n- `--json`: emit machine-readable preview or result output\n- `--quiet`: reduce non-error output\n- `--verbose`: reserved for future detailed output\n\n## Forward-Impact Analysis\n\nChanges in an older version can affect newer versions that still resolve through the same path. The tool analyzes that forward impact before destructive rename and delete operations.\n\nAffected newer versions fall into these categories:\n\n- inherited-only descendants: newer versions that contain only marker files for the affected path\n- structural descendants: newer versions that keep the path only as structure, without landing-page content\n- modified descendants: newer versions that contain real `_index.md` or `index.md` content at the affected path\n\nDefault behavior:\n\n- inherited-only descendants are updated automatically in apply mode\n- structural descendants are preserved where the operation allows it\n- modified descendants block destructive rename and delete operations\n\n## Content Rules the Tool Preserves\n\nThe docs editor preserves these invariants:\n\n- docs identity remains path-derived\n- `doc_id`, `product_version`, and `aliases` are not introduced\n- page folders contain exactly one of `index.md` or `inherit.md`\n- version and book folders contain exactly one of `_index.md` or `_inherit.md`\n- section folders contain zero or one of `_index.md` or `_inherit.md`\n- `inherit.md` and `_inherit.md` remain empty marker files\n- version order in `website/data/docs-versions.toml` stays canonical\n- nav data remains ordering-only metadata\n\n## Real Content Stubs\n\nWhen the tool creates real content, it writes a minimal front matter stub.\n\nDefaults:\n\n- page `index.md`: `title` defaults to a humanized page slug unless `--title` is provided\n- section `_index.md`: `title` defaults to the section title from nav data unless `--title` is provided\n- book `_index.md`: `title` defaults to a humanized book slug unless `--title` is provided\n- version `_index.md`: `title` defaults to the version label unless `--title` is provided\n\n## Inherited Markers\n\nWhen the tool creates inherited content, it writes:\n\n- empty `inherit.md` files for pages\n- empty `_inherit.md` files for version, book, and section landing pages\n\nNo front matter or body content is written into marker files.\n\n## Output Formats\n\nHuman-readable preview output shows the operation, the target path or version, the planned file changes, and the metadata changes that will be made on apply.\n\nJSON preview output includes:\n\n- `result`\n- `destructive`\n- `apply`\n- `metadata`\n- `changes`\n\nFor propagated destructive operations, `metadata` includes `propagated_versions` when later inherited-only versions will follow the change.\n\n## Standalone Report Generator\n\nUse [Docs Editor Tool](../docs-editor-tool/) for the high-level explanation of when to use the report and what it shows.\n\nThis reference section keeps only the CLI-specific behavior.\n\nThe report generator command is `website/scripts/docs-report.py`.\n\nBehavior:\n\n1. reads version metadata, nav files, and docs content directly from the repository\n2. writes `website-meta/docs-reports/docs-structure-report.html` by default\n3. embeds the report data, CSS, and JavaScript into one standalone HTML file\n\nExample:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py\n```\n\nCheck mode compares the current repository state against the committed HTML report and exits non-zero when the report needs regeneration:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py --check\n```\n\n## Operation Reference\n\n### Version Operations\n\n`version create` adds a new docs version, creates the matching content tree, initializes the new version to inherit from the previous version, and creates a matching nav file.\n\nRequired input:\n\n- new version slug\n- one insertion selector: `--after \u003cexisting-version\u003e` or `--latest`\n\nOptional input:\n\n- `--label \u003clabel\u003e`\n- `--status \u003cstatus\u003e`: optional UI label appended in parentheses after the version label, for example `preview` or `current`\n- `--visible true|false`\n- `--searchable true|false`\n- `--set-current`\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 1.2 --after 1.1 --label \"1.2\"\n```\n\nBehavior:\n\n1. inserts the new version into `website/data/docs-versions.toml`\n2. creates `website/content/docs/\u003cnew-version\u003e/`\n3. creates `website/data/docs-nav/\u003cnew-version\u003e.toml` from the previous version's nav data\n4. mirrors the previous version's docs tree shape\n5. creates inherited markers instead of copying authored content\n\nBootstrap behavior:\n\n- if `docs-versions.toml` has no declared versions, `--latest` bootstraps the first version instead of inheriting from a base version\n- in that case, the tool creates an authored version root with `_index.md`, creates an empty nav file, and sets the new version as `current`\n- this bootstrap path only works for a truly empty docs workspace; if version directories or version nav files still exist on disk, reconcile or remove them first\n\nImportant details:\n\n- the new version slug must not collide with an existing version\n- the reference version must exist\n- `status` is display metadata only; it does not decide which version is current\n- the actual current docs version is controlled by the top-level `current = \"\u003cslug\u003e\"` entry in `website/data/docs-versions.toml`\n- the current docs version changes only when `--set-current` is passed\n- `searchable` defaults to `false` unless explicitly set otherwise\n\n`version delete` removes a version entry, its nav file, and its content directory.\n\nRequired input:\n\n- version slug\n\nOptional input:\n\n- `--new-current \u003cversion\u003e` when deleting the current version\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version delete 1.1\n```\n\nBehavior:\n\n1. removes the version from `website/data/docs-versions.toml`\n2. removes `website/data/docs-nav/\u003cversion\u003e.toml`\n3. removes `website/content/docs/\u003cversion\u003e/`\n4. revalidates inheritance resolution across remaining versions\n\nRefusal cases:\n\n- the version does not exist\n- the version is current and `--new-current` was not supplied\n- `--new-current` points to the deleted version\n- `--new-current` does not exist after deletion\n- `--new-current` was supplied while deleting a non-current version\n\n### Book Operations\n\n`book create` creates a book folder, writes `_index.md` by default or `_inherit.md` with `--inherit`, and inserts the book into the version nav file.\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create --version 1.1 --book tutorials --title \"Tutorials\" --position end\n```\n\n`book delete` removes the book folder, the book entry in nav data, and the matching `sections.\u003cbook\u003e` and `pages.\u003cbook\u003e` data.\n\n`book rename` renames the book directory, updates `books` ordering plus the associated `sections` and `pages` tables, and propagates inherited-only descendants when allowed.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book rename --version 1.1 --from end-user --to user-guide --title \"User Guide\"\n```\n\n`book materialize` replaces an inherited book `_inherit.md` marker with a real `_index.md` using the currently resolved landing-page content. Use `--title` to replace the title while materializing.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book materialize --version 0.9 --book admin-guide\n```\n\n### Section Operations\n\n`section create` creates a section directory, adds a section entry in nav data, and initializes an empty `pages.\u003cbook\u003e.\u003csection\u003e.items` array.\n\nBy default it creates `_index.md`. With `--inherit`, it creates `_inherit.md`. With `--structural-only`, it creates no landing file. Optional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create --version 1.1 --book admin --section authentication --title \"Authentication\" --position end\n```\n\n`section delete` removes the section directory, its nav entry, and the matching `pages.\u003cbook\u003e.\u003csection\u003e` table.\n\n`section rename` renames the section directory, updates `sections.\u003cbook\u003e.items`, moves the matching `pages.\u003cbook\u003e.\u003csection\u003e` table to the new key, and preserves structural-only descendants as structural-only when no landing file exists at the renamed path.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section rename --version 1.1 --book admin --from configuration --to authentication --title \"Authentication\"\n```\n\n### Page Operations\n\n`page create` creates the page directory, writes `index.md` by default or `inherit.md` with `--inherit`, and adds the page slug to `pages.\u003cbook\u003e.\u003csection\u003e.items`.\n\nUse `page create` only when the page does not already exist in that version.\n\nIf the page already exists as an inherited page marker:\n\n- the directory already exists\n- the nav entry already exists\n- the page folder contains an empty `inherit.md`\n\nThen use `page materialize` instead of `page create`.\n\n`page materialize` replaces `inherit.md` with a real `index.md`, using the currently resolved inherited page content as the starting point.\n\nOptional input:\n\n- `--title \u003ctitle\u003e`: replace the inherited page title while materializing the real content\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page materialize --version 0.8 --book website-dev-guide --section docs-platform --page website-and-docs-architecture-overview\n```\n\nManual fallback if you need to control the copy step yourself:\n\n1. remove the inherited marker\n1. add `index.md`\n1. copy the inherited page body as the starting point\n1. edit that authored copy for the version-specific behavior\n\nThis remains outside the scope of `page create`, because the page identity and nav structure already exist.\n\n`page inherit` does the reverse: it replaces a real `index.md` in the selected version with `inherit.md` so the page resolves from an earlier authored version again.\n\nImportant details:\n\n- it is destructive because it removes that version's authored page content\n- apply mode requires `--yes` in non-interactive shells\n- it refuses when no earlier version resolves the same path to real `index.md` content\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply --yes page inherit --version 0.8 --book website-dev-guide --section docs-platform --page website-and-docs-architecture-overview\n```\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create --version 1.1 --book developer --section architecture --page overview --title \"Architecture Overview\"\n```\n\n`page delete` removes the page directory and the matching page slug from nav data.\n\n`page rename` renames the page directory, updates `pages.\u003cbook\u003e.\u003csection\u003e.items`, and propagates inherited-only descendants when allowed.\n\nWhen a later version has independently authored the page, include it with `--also-version` to rename both versions in one atomic operation. Repeat the option for each independently authored version. The tool continues to move inherited-only versions automatically.\n\nA later version may already use the destination slug when it no longer contains the old slug. The tool refuses a version that contains both slugs, because that is an ambiguous page collision.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename --version 1.1 --also-version 1.3 --book end-user --section getting-started --from install --to setup --title \"Setup Sambee\"\n```\n\n`page move` moves a page to another section in the same book. It updates both page lists, materializes the selected version's destination page, and removes the source directory. `--to-page` optionally changes the slug; otherwise the source slug is retained. `--position` controls the destination order in the selected version.\n\nInherited-only descendants move automatically. The operation refuses if the destination exists, a later source page has real content, or a later version lacks the destination section. Links and managed redirects remain explicit content or deployment changes.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page move --version 0.9 --book admin-guide --from-section configuration --to-section reference --page configuration-key-reference --to-page configuration-file-reference --position start\n```\n\n## Notes\n\n- the tool does not edit `website/.generated/` directly\n- the tool does not run `materialize-inherited-docs.py` for you\n- the tool does not edit page body content or offer free-form front matter editing\n", "1.0": "+++\ntitle = \"Docs Editor Operation Reference\"\n+++\n\nUse this page when you already know you need the docs editor and want the detailed reference behavior.\n\n## Position Selectors\n\nOperations that insert books, sections, or pages use the same position syntax:\n\n- `\u003cindex\u003e`: insert at a zero-based numeric index\n- `before:\u003cslug\u003e`: insert immediately before the existing item\n- `after:\u003cslug\u003e`: insert immediately after the existing item\n- `start`: insert at the beginning\n- `end`: insert at the end\n\nIf the requested selector does not resolve cleanly in the target nav list, the operation refuses instead of guessing.\n\n## Global Options\n\nThe CLI supports these global options:\n\n- `--apply`: write changes to disk instead of previewing them\n- `--yes`: skip confirmation for destructive apply operations\n- `--json`: emit machine-readable preview or result output\n- `--quiet`: reduce non-error output\n- `--verbose`: reserved for future detailed output\n\n## Forward-Impact Analysis\n\nChanges in an older version can affect newer versions that still resolve through the same path. The tool analyzes that forward impact before destructive rename and delete operations.\n\nAffected newer versions fall into these categories:\n\n- inherited-only descendants: newer versions that contain only marker files for the affected path\n- structural descendants: newer versions that keep the path only as structure, without landing-page content\n- modified descendants: newer versions that contain real `_index.md` or `index.md` content at the affected path\n\nDefault behavior:\n\n- inherited-only descendants are updated automatically in apply mode\n- structural descendants are preserved where the operation allows it\n- modified descendants block destructive rename and delete operations\n\n## Content Rules the Tool Preserves\n\nThe docs editor preserves these invariants:\n\n- docs identity remains path-derived\n- `doc_id`, `product_version`, and `aliases` are not introduced\n- page folders contain exactly one of `index.md` or `inherit.md`\n- version and book folders contain exactly one of `_index.md` or `_inherit.md`\n- section folders contain zero or one of `_index.md` or `_inherit.md`\n- `inherit.md` and `_inherit.md` remain empty marker files\n- version order in `website/data/docs-versions.toml` stays canonical\n- nav data remains ordering-only metadata\n\n## Real Content Stubs\n\nWhen the tool creates real content, it writes a minimal front matter stub.\n\nDefaults:\n\n- page `index.md`: `title` defaults to a humanized page slug unless `--title` is provided\n- section `_index.md`: `title` defaults to the section title from nav data unless `--title` is provided\n- book `_index.md`: `title` defaults to a humanized book slug unless `--title` is provided\n- version `_index.md`: `title` defaults to the version label unless `--title` is provided\n\n## Inherited Markers\n\nWhen the tool creates inherited content, it writes:\n\n- empty `inherit.md` files for pages\n- empty `_inherit.md` files for version, book, and section landing pages\n\nNo front matter or body content is written into marker files.\n\n## Output Formats\n\nHuman-readable preview output shows the operation, the target path or version, the planned file changes, and the metadata changes that will be made on apply.\n\nJSON preview output includes:\n\n- `result`\n- `destructive`\n- `apply`\n- `metadata`\n- `changes`\n\nFor propagated destructive operations, `metadata` includes `propagated_versions` when later inherited-only versions will follow the change.\n\n## Standalone Report Generator\n\nUse [Docs Editor Tool](../docs-editor-tool/) for the high-level explanation of when to use the report and what it shows.\n\nThis reference section keeps only the CLI-specific behavior.\n\nThe report generator command is `website/scripts/docs-report.py`.\n\nBehavior:\n\n1. reads version metadata, nav files, and docs content directly from the repository\n2. writes `website-meta/docs-reports/docs-structure-report.html` by default\n3. embeds the report data, CSS, and JavaScript into one standalone HTML file\n\nExample:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py\n```\n\nCheck mode compares the current repository state against the committed HTML report and exits non-zero when the report needs regeneration:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py --check\n```\n\n## Operation Reference\n\n### Version Operations\n\n`version create` adds a new docs version, creates the matching content tree, initializes the new version to inherit from the previous version, and creates a matching nav file.\n\nRequired input:\n\n- new version slug\n- one insertion selector: `--after \u003cexisting-version\u003e` or `--latest`\n\nOptional input:\n\n- `--label \u003clabel\u003e`\n- `--status \u003cstatus\u003e`: optional UI label appended in parentheses after the version label, for example `preview` or `current`\n- `--visible true|false`\n- `--searchable true|false`\n- `--set-current`\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 1.2 --after 1.1 --label \"1.2\"\n```\n\nBehavior:\n\n1. inserts the new version into `website/data/docs-versions.toml`\n2. creates `website/content/docs/\u003cnew-version\u003e/`\n3. creates `website/data/docs-nav/\u003cnew-version\u003e.toml` from the previous version's nav data\n4. mirrors the previous version's docs tree shape\n5. creates inherited markers instead of copying authored content\n\nBootstrap behavior:\n\n- if `docs-versions.toml` has no declared versions, `--latest` bootstraps the first version instead of inheriting from a base version\n- in that case, the tool creates an authored version root with `_index.md`, creates an empty nav file, and sets the new version as `current`\n- this bootstrap path only works for a truly empty docs workspace; if version directories or version nav files still exist on disk, reconcile or remove them first\n\nImportant details:\n\n- the new version slug must not collide with an existing version\n- the reference version must exist\n- `status` is display metadata only; it does not decide which version is current\n- the actual current docs version is controlled by the top-level `current = \"\u003cslug\u003e\"` entry in `website/data/docs-versions.toml`\n- the current docs version changes only when `--set-current` is passed\n- `searchable` defaults to `false` unless explicitly set otherwise\n\n`version delete` removes a version entry, its nav file, and its content directory.\n\nRequired input:\n\n- version slug\n\nOptional input:\n\n- `--new-current \u003cversion\u003e` when deleting the current version\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version delete 1.1\n```\n\nBehavior:\n\n1. removes the version from `website/data/docs-versions.toml`\n2. removes `website/data/docs-nav/\u003cversion\u003e.toml`\n3. removes `website/content/docs/\u003cversion\u003e/`\n4. revalidates inheritance resolution across remaining versions\n\nRefusal cases:\n\n- the version does not exist\n- the version is current and `--new-current` was not supplied\n- `--new-current` points to the deleted version\n- `--new-current` does not exist after deletion\n- `--new-current` was supplied while deleting a non-current version\n\n### Book Operations\n\n`book create` creates a book folder, writes `_index.md` by default or `_inherit.md` with `--inherit`, and inserts the book into the version nav file.\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create --version 1.1 --book tutorials --title \"Tutorials\" --position end\n```\n\n`book delete` removes the book folder, the book entry in nav data, and the matching `sections.\u003cbook\u003e` and `pages.\u003cbook\u003e` data.\n\n`book rename` renames the book directory, updates `books` ordering plus the associated `sections` and `pages` tables, and propagates inherited-only descendants when allowed.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book rename --version 1.1 --from end-user --to user-guide --title \"User Guide\"\n```\n\n`book materialize` replaces an inherited book `_inherit.md` marker with a real `_index.md` using the currently resolved landing-page content. Use `--title` to replace the title while materializing.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book materialize --version 0.9 --book admin-guide\n```\n\n### Section Operations\n\n`section create` creates a section directory, adds a section entry in nav data, and initializes an empty `pages.\u003cbook\u003e.\u003csection\u003e.items` array.\n\nBy default it creates `_index.md`. With `--inherit`, it creates `_inherit.md`. With `--structural-only`, it creates no landing file. Optional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create --version 1.1 --book admin --section authentication --title \"Authentication\" --position end\n```\n\n`section delete` removes the section directory, its nav entry, and the matching `pages.\u003cbook\u003e.\u003csection\u003e` table.\n\n`section rename` renames the section directory, updates `sections.\u003cbook\u003e.items`, moves the matching `pages.\u003cbook\u003e.\u003csection\u003e` table to the new key, and preserves structural-only descendants as structural-only when no landing file exists at the renamed path.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section rename --version 1.1 --book admin --from configuration --to authentication --title \"Authentication\"\n```\n\n### Page Operations\n\n`page create` creates the page directory, writes `index.md` by default or `inherit.md` with `--inherit`, and adds the page slug to `pages.\u003cbook\u003e.\u003csection\u003e.items`.\n\nUse `page create` only when the page does not already exist in that version.\n\nIf the page already exists as an inherited page marker:\n\n- the directory already exists\n- the nav entry already exists\n- the page folder contains an empty `inherit.md`\n\nThen use `page materialize` instead of `page create`.\n\n`page materialize` replaces `inherit.md` with a real `index.md`, using the currently resolved inherited page content as the starting point.\n\nOptional input:\n\n- `--title \u003ctitle\u003e`: replace the inherited page title while materializing the real content\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page materialize --version 0.8 --book website-dev-guide --section docs-platform --page website-and-docs-architecture-overview\n```\n\nManual fallback if you need to control the copy step yourself:\n\n1. remove the inherited marker\n1. add `index.md`\n1. copy the inherited page body as the starting point\n1. edit that authored copy for the version-specific behavior\n\nThis remains outside the scope of `page create`, because the page identity and nav structure already exist.\n\n`page inherit` does the reverse: it replaces a real `index.md` in the selected version with `inherit.md` so the page resolves from an earlier authored version again.\n\nImportant details:\n\n- it is destructive because it removes that version's authored page content\n- apply mode requires `--yes` in non-interactive shells\n- it refuses when no earlier version resolves the same path to real `index.md` content\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply --yes page inherit --version 0.8 --book website-dev-guide --section docs-platform --page website-and-docs-architecture-overview\n```\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create --version 1.1 --book developer --section architecture --page overview --title \"Architecture Overview\"\n```\n\n`page delete` removes the page directory and the matching page slug from nav data.\n\n`page rename` renames the page directory, updates `pages.\u003cbook\u003e.\u003csection\u003e.items`, and propagates inherited-only descendants when allowed.\n\nWhen a later version has independently authored the page, include it with `--also-version` to rename both versions in one atomic operation. Repeat the option for each independently authored version. The tool continues to move inherited-only versions automatically.\n\nA later version may already use the destination slug when it no longer contains the old slug. The tool refuses a version that contains both slugs, because that is an ambiguous page collision.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename --version 1.1 --also-version 1.3 --book end-user --section getting-started --from install --to setup --title \"Setup Sambee\"\n```\n\n`page move` moves a page to another section in the same book. It updates both page lists, materializes the selected version's destination page, and removes the source directory. `--to-page` optionally changes the slug; otherwise the source slug is retained. `--position` controls the destination order in the selected version.\n\nInherited-only descendants move automatically. The operation refuses if the destination exists, a later source page has real content, or a later version lacks the destination section. Links and managed redirects remain explicit content or deployment changes.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page move --version 0.9 --book admin-guide --from-section configuration --to-section reference --page configuration-key-reference --to-page configuration-file-reference --position start\n```\n\n## Notes\n\n- the tool does not edit `website/.generated/` directly\n- the tool does not run `materialize-inherited-docs.py` for you\n- the tool does not edit page body content or offer free-form front matter editing\n", "2.0": "+++\ntitle = \"Docs Editor Operation Reference\"\n+++\n\nUse this page when you already know you need the docs editor and want the detailed reference behavior.\n\n## Position Selectors\n\nOperations that insert books, sections, or pages use the same position syntax:\n\n- `\u003cindex\u003e`: insert at a zero-based numeric index\n- `before:\u003cslug\u003e`: insert immediately before the existing item\n- `after:\u003cslug\u003e`: insert immediately after the existing item\n- `start`: insert at the beginning\n- `end`: insert at the end\n\nIf the requested selector does not resolve cleanly in the target nav list, the operation refuses instead of guessing.\n\n## Global Options\n\nThe CLI supports these global options:\n\n- `--apply`: write changes to disk instead of previewing them\n- `--yes`: skip confirmation for destructive apply operations\n- `--json`: emit machine-readable preview or result output\n- `--quiet`: reduce non-error output\n- `--verbose`: reserved for future detailed output\n\n## Forward-Impact Analysis\n\nChanges in an older version can affect newer versions that still resolve through the same path. The tool analyzes that forward impact before destructive rename and delete operations.\n\nAffected newer versions fall into these categories:\n\n- inherited-only descendants: newer versions that contain only marker files for the affected path\n- structural descendants: newer versions that keep the path only as structure, without landing-page content\n- modified descendants: newer versions that contain real `_index.md` or `index.md` content at the affected path\n\nDefault behavior:\n\n- inherited-only descendants are updated automatically in apply mode\n- structural descendants are preserved where the operation allows it\n- modified descendants block destructive rename and delete operations\n\n## Content Rules the Tool Preserves\n\nThe docs editor preserves these invariants:\n\n- docs identity remains path-derived\n- `doc_id`, `product_version`, and `aliases` are not introduced\n- page folders contain exactly one of `index.md` or `inherit.md`\n- version and book folders contain exactly one of `_index.md` or `_inherit.md`\n- section folders contain zero or one of `_index.md` or `_inherit.md`\n- `inherit.md` and `_inherit.md` remain empty marker files\n- version order in `website/data/docs-versions.toml` stays canonical\n- nav data remains ordering-only metadata\n\n## Real Content Stubs\n\nWhen the tool creates real content, it writes a minimal front matter stub.\n\nDefaults:\n\n- page `index.md`: `title` defaults to a humanized page slug unless `--title` is provided\n- section `_index.md`: `title` defaults to the section title from nav data unless `--title` is provided\n- book `_index.md`: `title` defaults to a humanized book slug unless `--title` is provided\n- version `_index.md`: `title` defaults to the version label unless `--title` is provided\n\n## Inherited Markers\n\nWhen the tool creates inherited content, it writes:\n\n- empty `inherit.md` files for pages\n- empty `_inherit.md` files for version, book, and section landing pages\n\nNo front matter or body content is written into marker files.\n\n## Output Formats\n\nHuman-readable preview output shows the operation, the target path or version, the planned file changes, and the metadata changes that will be made on apply.\n\nJSON preview output includes:\n\n- `result`\n- `destructive`\n- `apply`\n- `metadata`\n- `changes`\n\nFor propagated destructive operations, `metadata` includes `propagated_versions` when later inherited-only versions will follow the change.\n\n## Standalone Report Generator\n\nUse [Docs Editor Tool](../docs-editor-tool/) for the high-level explanation of when to use the report and what it shows.\n\nThis reference section keeps only the CLI-specific behavior.\n\nThe report generator command is `website/scripts/docs-report.py`.\n\nBehavior:\n\n1. reads version metadata, nav files, and docs content directly from the repository\n2. writes `website-meta/docs-reports/docs-structure-report.html` by default\n3. embeds the report data, CSS, and JavaScript into one standalone HTML file\n\nExample:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py\n```\n\nCheck mode compares the current repository state against the committed HTML report and exits non-zero when the report needs regeneration:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py --check\n```\n\n## Operation Reference\n\n### Version Operations\n\n`version create` adds a new docs version, creates the matching content tree, initializes the new version to inherit from the previous version, and creates a matching nav file.\n\nRequired input:\n\n- new version slug\n- one insertion selector: `--after \u003cexisting-version\u003e` or `--latest`\n\nOptional input:\n\n- `--label \u003clabel\u003e`\n- `--status \u003cstatus\u003e`: optional UI label appended in parentheses after the version label, for example `preview` or `current`\n- `--visible true|false`\n- `--searchable true|false`\n- `--set-current`\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 1.2 --after 1.1 --label \"1.2\"\n```\n\nBehavior:\n\n1. inserts the new version into `website/data/docs-versions.toml`\n2. creates `website/content/docs/\u003cnew-version\u003e/`\n3. creates `website/data/docs-nav/\u003cnew-version\u003e.toml` from the previous version's nav data\n4. mirrors the previous version's docs tree shape\n5. creates inherited markers instead of copying authored content\n\nBootstrap behavior:\n\n- if `docs-versions.toml` has no declared versions, `--latest` bootstraps the first version instead of inheriting from a base version\n- in that case, the tool creates an authored version root with `_index.md`, creates an empty nav file, and sets the new version as `current`\n- this bootstrap path only works for a truly empty docs workspace; if version directories or version nav files still exist on disk, reconcile or remove them first\n\nImportant details:\n\n- the new version slug must not collide with an existing version\n- the reference version must exist\n- `status` is display metadata only; it does not decide which version is current\n- the actual current docs version is controlled by the top-level `current = \"\u003cslug\u003e\"` entry in `website/data/docs-versions.toml`\n- the current docs version changes only when `--set-current` is passed\n- `searchable` defaults to `false` unless explicitly set otherwise\n\n`version delete` removes a version entry, its nav file, and its content directory.\n\nRequired input:\n\n- version slug\n\nOptional input:\n\n- `--new-current \u003cversion\u003e` when deleting the current version\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version delete 1.1\n```\n\nBehavior:\n\n1. removes the version from `website/data/docs-versions.toml`\n2. removes `website/data/docs-nav/\u003cversion\u003e.toml`\n3. removes `website/content/docs/\u003cversion\u003e/`\n4. revalidates inheritance resolution across remaining versions\n\nRefusal cases:\n\n- the version does not exist\n- the version is current and `--new-current` was not supplied\n- `--new-current` points to the deleted version\n- `--new-current` does not exist after deletion\n- `--new-current` was supplied while deleting a non-current version\n\n### Book Operations\n\n`book create` creates a book folder, writes `_index.md` by default or `_inherit.md` with `--inherit`, and inserts the book into the version nav file.\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create --version 1.1 --book tutorials --title \"Tutorials\" --position end\n```\n\n`book delete` removes the book folder, the book entry in nav data, and the matching `sections.\u003cbook\u003e` and `pages.\u003cbook\u003e` data.\n\n`book rename` renames the book directory, updates `books` ordering plus the associated `sections` and `pages` tables, and propagates inherited-only descendants when allowed.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book rename --version 1.1 --from end-user --to user-guide --title \"User Guide\"\n```\n\n`book materialize` replaces an inherited book `_inherit.md` marker with a real `_index.md` using the currently resolved landing-page content. Use `--title` to replace the title while materializing.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book materialize --version 0.9 --book admin-guide\n```\n\n### Section Operations\n\n`section create` creates a section directory, adds a section entry in nav data, and initializes an empty `pages.\u003cbook\u003e.\u003csection\u003e.items` array.\n\nBy default it creates `_index.md`. With `--inherit`, it creates `_inherit.md`. With `--structural-only`, it creates no landing file. Optional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create --version 1.1 --book admin --section authentication --title \"Authentication\" --position end\n```\n\n`section delete` removes the section directory, its nav entry, and the matching `pages.\u003cbook\u003e.\u003csection\u003e` table.\n\n`section rename` renames the section directory, updates `sections.\u003cbook\u003e.items`, moves the matching `pages.\u003cbook\u003e.\u003csection\u003e` table to the new key, and preserves structural-only descendants as structural-only when no landing file exists at the renamed path.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section rename --version 1.1 --book admin --from configuration --to authentication --title \"Authentication\"\n```\n\n### Page Operations\n\n`page create` creates the page directory, writes `index.md` by default or `inherit.md` with `--inherit`, and adds the page slug to `pages.\u003cbook\u003e.\u003csection\u003e.items`.\n\nUse `page create` only when the page does not already exist in that version.\n\nIf the page already exists as an inherited page marker:\n\n- the directory already exists\n- the nav entry already exists\n- the page folder contains an empty `inherit.md`\n\nThen use `page materialize` instead of `page create`.\n\n`page materialize` replaces `inherit.md` with a real `index.md`, using the currently resolved inherited page content as the starting point.\n\nOptional input:\n\n- `--title \u003ctitle\u003e`: replace the inherited page title while materializing the real content\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page materialize --version 0.8 --book website-dev-guide --section docs-platform --page website-and-docs-architecture-overview\n```\n\nManual fallback if you need to control the copy step yourself:\n\n1. remove the inherited marker\n1. add `index.md`\n1. copy the inherited page body as the starting point\n1. edit that authored copy for the version-specific behavior\n\nThis remains outside the scope of `page create`, because the page identity and nav structure already exist.\n\n`page inherit` does the reverse: it replaces a real `index.md` in the selected version with `inherit.md` so the page resolves from an earlier authored version again.\n\nImportant details:\n\n- it is destructive because it removes that version's authored page content\n- apply mode requires `--yes` in non-interactive shells\n- it refuses when no earlier version resolves the same path to real `index.md` content\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply --yes page inherit --version 0.8 --book website-dev-guide --section docs-platform --page website-and-docs-architecture-overview\n```\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create --version 1.1 --book developer --section architecture --page overview --title \"Architecture Overview\"\n```\n\n`page delete` removes the page directory and the matching page slug from nav data.\n\n`page rename` renames the page directory, updates `pages.\u003cbook\u003e.\u003csection\u003e.items`, and propagates inherited-only descendants when allowed.\n\nWhen a later version has independently authored the page, include it with `--also-version` to rename both versions in one atomic operation. Repeat the option for each independently authored version. The tool continues to move inherited-only versions automatically.\n\nA later version may already use the destination slug when it no longer contains the old slug. The tool refuses a version that contains both slugs, because that is an ambiguous page collision.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename --version 1.1 --also-version 1.3 --book end-user --section getting-started --from install --to setup --title \"Setup Sambee\"\n```\n\n`page move` moves a page to another section in the same book. It updates both page lists, materializes the selected version's destination page, and removes the source directory. `--to-page` optionally changes the slug; otherwise the source slug is retained. `--position` controls the destination order in the selected version.\n\nInherited-only descendants move automatically. The operation refuses if the destination exists, a later source page has real content, or a later version lacks the destination section. Links and managed redirects remain explicit content or deployment changes.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page move --version 0.9 --book admin-guide --from-section configuration --to-section reference --page configuration-key-reference --to-page configuration-file-reference --position start\n```\n\n## Notes\n\n- the tool does not edit `website/.generated/` directly\n- the tool does not run `materialize-inherited-docs.py` for you\n- the tool does not edit page body content or offer free-form front matter editing\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:website-dev-guide/site-systems", "parent_id": "book:website-dev-guide", "depth": 1, "kind": "section", "label": "site-systems", "title": "Site Systems", "path": "website-dev-guide/site-systems", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:website-dev-guide/site-systems/media-publishing-workflow", "parent_id": "section:website-dev-guide/site-systems", "depth": 2, "kind": "page", "label": "media-publishing-workflow", "title": "Media Publishing Workflow", "path": "website-dev-guide/site-systems/media-publishing-workflow", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Media Publishing Workflow\"\n+++\n\nThe website media workflow is repository-driven. The source files and the generated derivatives both belong in the repo.\n\n## Goals\n\n- Source images are committed in the repository.\n- Pre-generated WebP derivatives are committed in the repository.\n- The committed social preview PNG is generated locally and committed in the repository.\n- Source images and generated derivatives are tracked with Git LFS.\n- Every raster source image has generated WebP derivatives.\n- Local development and CI pull media from Git LFS before building.\n- CI publishes built media from `website/public` rather than generating missing derivatives during deployment.\n\n## Required Tools\n\nYou need:\n\n- `git-lfs`\n- ImageMagick's `magick` command when generating derivatives locally\n\nAfter cloning, pull LFS objects before you work on the site:\n\n```bash\ngit lfs pull\n```\n\nIf the LFS objects are missing, a site build may appear to work while still producing broken image references or missing derivatives.\n\n## Source of Truth\n\nThe source of truth for website media is the checked-in asset tree:\n\n- `website/assets/images/` for source images and generated WebPs\n- `website/assets/images/` for source images and committed generated derivatives, including WebPs and the social preview PNG\n- `website/static/files/` for downloadable files\n\nHugo's cached outputs under `website/resources/_gen/images/` are build artifacts, not source content and not committed media.\n\nGenerated derivatives live in a sibling `generated/` directory next to the source image.\n\nExample:\n\n```text\nwebsite/assets/images/home/companion-screenshot.png\nwebsite/assets/images/home/generated/companion-screenshot_372w.webp\nwebsite/assets/images/home/generated/companion-screenshot_500w.webp\nwebsite/assets/images/home/generated/sambee-screenshot_1200w.png\n```\n\n## Authoring Workflow\n\nWhen you add or change a raster image:\n\n1. Add or update the source file under `website/assets/images/`.\n2. Start the website preview task or run `npm run dev`.\n3. Let the local watcher regenerate missing derivatives automatically, or generate them manually.\n4. Review the generated files in the matching `generated/` directory.\n5. Commit the source image and the generated derivatives together.\n\nThe local watcher covers two cases:\n\n- For ordinary raster images, it regenerates the matching WebP derivatives.\n- For `website/assets/images/home/sambee-screenshot.png`, it also regenerates the committed social preview PNG at `website/assets/images/home/generated/sambee-screenshot_1200w.png`.\n\nManual batch generation:\n\n```bash\ncd website\nnpm run images:generate\n```\n\nManual social preview generation:\n\n```bash\ncd website\nnpm run social:generate\n```\n\nDo not rely on CI to create missing derivatives. Missing generated media is a defect.\n\n## Build and Publish Expectations\n\nThe website build and deployment flow is set up around this behavior:\n\n- Local development pulls Git LFS objects before serving the site.\n- The local dev workflow runs the image watcher during `npm run dev`.\n- CI restores and pulls Git LFS objects before building the site.\n- CI validates that raster source images have generated WebP derivatives.\n- The shared head template fails the Hugo build if the committed social preview PNG is missing or is not `1200x630`.\n- CI uploads `website/public` as a short-lived artifact after the build.\n- The deploy job publishes `website/public` to Cloudflare Pages.\n\nThe project scripts that matter most here are:\n\n- `npm run images:generate`\n- `npm run images:validate`\n- `npm run social:generate`\n- `npm run build`\n\nThe workflow lives in `.github/workflows/website-deploy.yml`. The important steps include:\n\n- restore `.git/lfs` cache and run `git lfs pull`\n- restore `website/resources/_gen` cache for faster rebuilds\n- validate generated WebP coverage\n- build the Hugo site and Pagefind index inside `website/`\n- upload `website/public` as a short-lived artifact\n- deploy the built site from `website/public`\n\nFor the Cloudflare-side setup, GitHub Actions secrets, and deployment branch rules, see [Set Up Cloudflare Pages Publishing](../../setup-and-operations/set-up-cloudflare-pages-publishing/).\n", "0.8": "+++\ntitle = \"Media Publishing Workflow\"\n+++\n\nThe website media workflow is repository-driven. The source files and the generated derivatives both belong in the repo.\n\n## Goals\n\n- Source images are committed in the repository.\n- Pre-generated WebP derivatives are committed in the repository.\n- The committed social preview PNG is generated locally and committed in the repository.\n- Source images and generated derivatives are tracked with Git LFS.\n- Every raster source image has generated WebP derivatives.\n- Local development and CI pull media from Git LFS before building.\n- CI publishes built media from `website/public` rather than generating missing derivatives during deployment.\n\n## Required Tools\n\nYou need:\n\n- `git-lfs`\n- ImageMagick's `magick` command when generating derivatives locally\n\nAfter cloning, pull LFS objects before you work on the site:\n\n```bash\ngit lfs pull\n```\n\nIf the LFS objects are missing, a site build may appear to work while still producing broken image references or missing derivatives.\n\n## Source of Truth\n\nThe source of truth for website media is the checked-in asset tree:\n\n- `website/assets/images/` for source images and generated WebPs\n- `website/assets/images/` for source images and committed generated derivatives, including WebPs and the social preview PNG\n- `website/static/files/` for downloadable files\n\nHugo's cached outputs under `website/resources/_gen/images/` are build artifacts, not source content and not committed media.\n\nGenerated derivatives live in a sibling `generated/` directory next to the source image.\n\nExample:\n\n```text\nwebsite/assets/images/home/companion-screenshot.png\nwebsite/assets/images/home/generated/companion-screenshot_372w.webp\nwebsite/assets/images/home/generated/companion-screenshot_500w.webp\nwebsite/assets/images/home/generated/sambee-screenshot_1200w.png\n```\n\n## Authoring Workflow\n\nWhen you add or change a raster image:\n\n1. Add or update the source file under `website/assets/images/`.\n2. Start the website preview task or run `npm run dev`.\n3. Let the local watcher regenerate missing derivatives automatically, or generate them manually.\n4. Review the generated files in the matching `generated/` directory.\n5. Commit the source image and the generated derivatives together.\n\nThe local watcher covers two cases:\n\n- For ordinary raster images, it regenerates the matching WebP derivatives.\n- For `website/assets/images/home/sambee-screenshot.png`, it also regenerates the committed social preview PNG at `website/assets/images/home/generated/sambee-screenshot_1200w.png`.\n\nManual batch generation:\n\n```bash\ncd website\nnpm run images:generate\n```\n\nManual social preview generation:\n\n```bash\ncd website\nnpm run social:generate\n```\n\nDo not rely on CI to create missing derivatives. Missing generated media is a defect.\n\n## Build and Publish Expectations\n\nThe website build and deployment flow is set up around this behavior:\n\n- Local development pulls Git LFS objects before serving the site.\n- The local dev workflow runs the image watcher during `npm run dev`.\n- CI restores and pulls Git LFS objects before building the site.\n- CI validates that raster source images have generated WebP derivatives.\n- The shared head template fails the Hugo build if the committed social preview PNG is missing or is not `1200x630`.\n- CI uploads `website/public` as a short-lived artifact after the build.\n- The deploy job publishes `website/public` to Cloudflare Pages.\n\nThe project scripts that matter most here are:\n\n- `npm run images:generate`\n- `npm run images:validate`\n- `npm run social:generate`\n- `npm run build`\n\nThe workflow lives in `.github/workflows/website-deploy.yml`. The important steps include:\n\n- restore `.git/lfs` cache and run `git lfs pull`\n- restore `website/resources/_gen` cache for faster rebuilds\n- validate generated WebP coverage\n- build the Hugo site and Pagefind index inside `website/`\n- upload `website/public` as a short-lived artifact\n- deploy the built site from `website/public`\n\nFor the Cloudflare-side setup, GitHub Actions secrets, and deployment branch rules, see [Set Up Cloudflare Pages Publishing](../../setup-and-operations/set-up-cloudflare-pages-publishing/).\n", "0.9": "+++\ntitle = \"Media Publishing Workflow\"\n+++\n\nThe website media workflow is repository-driven. The source files and the generated derivatives both belong in the repo.\n\n## Goals\n\n- Source images are committed in the repository.\n- Pre-generated WebP derivatives are committed in the repository.\n- The committed social preview PNG is generated locally and committed in the repository.\n- Source images and generated derivatives are tracked with Git LFS.\n- Every raster source image has generated WebP derivatives.\n- Local development and CI pull media from Git LFS before building.\n- CI publishes built media from `website/public` rather than generating missing derivatives during deployment.\n\n## Required Tools\n\nYou need:\n\n- `git-lfs`\n- ImageMagick's `magick` command when generating derivatives locally\n\nAfter cloning, pull LFS objects before you work on the site:\n\n```bash\ngit lfs pull\n```\n\nIf the LFS objects are missing, a site build may appear to work while still producing broken image references or missing derivatives.\n\n## Source of Truth\n\nThe source of truth for website media is the checked-in asset tree:\n\n- `website/assets/images/` for source images and generated WebPs\n- `website/assets/images/` for source images and committed generated derivatives, including WebPs and the social preview PNG\n- `website/static/files/` for downloadable files\n\nHugo's cached outputs under `website/resources/_gen/images/` are build artifacts, not source content and not committed media.\n\nGenerated derivatives live in a sibling `generated/` directory next to the source image.\n\nExample:\n\n```text\nwebsite/assets/images/home/companion-screenshot.png\nwebsite/assets/images/home/generated/companion-screenshot_372w.webp\nwebsite/assets/images/home/generated/companion-screenshot_500w.webp\nwebsite/assets/images/home/generated/sambee-screenshot_1200w.png\n```\n\n## Authoring Workflow\n\nWhen you add or change a raster image:\n\n1. Add or update the source file under `website/assets/images/`.\n2. Start the website preview task or run `npm run dev`.\n3. Let the local watcher regenerate missing derivatives automatically, or generate them manually.\n4. Review the generated files in the matching `generated/` directory.\n5. Commit the source image and the generated derivatives together.\n\nThe local watcher covers two cases:\n\n- For ordinary raster images, it regenerates the matching WebP derivatives.\n- For `website/assets/images/home/sambee-screenshot.png`, it also regenerates the committed social preview PNG at `website/assets/images/home/generated/sambee-screenshot_1200w.png`.\n\nManual batch generation:\n\n```bash\ncd website\nnpm run images:generate\n```\n\nManual social preview generation:\n\n```bash\ncd website\nnpm run social:generate\n```\n\nDo not rely on CI to create missing derivatives. Missing generated media is a defect.\n\n## Build and Publish Expectations\n\nThe website build and deployment flow is set up around this behavior:\n\n- Local development pulls Git LFS objects before serving the site.\n- The local dev workflow runs the image watcher during `npm run dev`.\n- CI restores and pulls Git LFS objects before building the site.\n- CI validates that raster source images have generated WebP derivatives.\n- The shared head template fails the Hugo build if the committed social preview PNG is missing or is not `1200x630`.\n- CI uploads `website/public` as a short-lived artifact after the build.\n- The deploy job publishes `website/public` to Cloudflare Pages.\n\nThe project scripts that matter most here are:\n\n- `npm run images:generate`\n- `npm run images:validate`\n- `npm run social:generate`\n- `npm run build`\n\nThe workflow lives in `.github/workflows/website-deploy.yml`. The important steps include:\n\n- restore `.git/lfs` cache and run `git lfs pull`\n- restore `website/resources/_gen` cache for faster rebuilds\n- validate generated WebP coverage\n- build the Hugo site and Pagefind index inside `website/`\n- upload `website/public` as a short-lived artifact\n- deploy the built site from `website/public`\n\nFor the Cloudflare-side setup, GitHub Actions secrets, and deployment branch rules, see [Set Up Cloudflare Pages Publishing](../../setup-and-operations/set-up-cloudflare-pages-publishing/).\n", "1.0": "+++\ntitle = \"Media Publishing Workflow\"\n+++\n\nThe website media workflow is repository-driven. The source files and the generated derivatives both belong in the repo.\n\n## Goals\n\n- Source images are committed in the repository.\n- Pre-generated WebP derivatives are committed in the repository.\n- The committed social preview PNG is generated locally and committed in the repository.\n- Source images and generated derivatives are tracked with Git LFS.\n- Every raster source image has generated WebP derivatives.\n- Local development and CI pull media from Git LFS before building.\n- CI publishes built media from `website/public` rather than generating missing derivatives during deployment.\n\n## Required Tools\n\nYou need:\n\n- `git-lfs`\n- ImageMagick's `magick` command when generating derivatives locally\n\nAfter cloning, pull LFS objects before you work on the site:\n\n```bash\ngit lfs pull\n```\n\nIf the LFS objects are missing, a site build may appear to work while still producing broken image references or missing derivatives.\n\n## Source of Truth\n\nThe source of truth for website media is the checked-in asset tree:\n\n- `website/assets/images/` for source images and generated WebPs\n- `website/assets/images/` for source images and committed generated derivatives, including WebPs and the social preview PNG\n- `website/static/files/` for downloadable files\n\nHugo's cached outputs under `website/resources/_gen/images/` are build artifacts, not source content and not committed media.\n\nGenerated derivatives live in a sibling `generated/` directory next to the source image.\n\nExample:\n\n```text\nwebsite/assets/images/home/companion-screenshot.png\nwebsite/assets/images/home/generated/companion-screenshot_372w.webp\nwebsite/assets/images/home/generated/companion-screenshot_500w.webp\nwebsite/assets/images/home/generated/sambee-screenshot_1200w.png\n```\n\n## Authoring Workflow\n\nWhen you add or change a raster image:\n\n1. Add or update the source file under `website/assets/images/`.\n2. Start the website preview task or run `npm run dev`.\n3. Let the local watcher regenerate missing derivatives automatically, or generate them manually.\n4. Review the generated files in the matching `generated/` directory.\n5. Commit the source image and the generated derivatives together.\n\nThe local watcher covers two cases:\n\n- For ordinary raster images, it regenerates the matching WebP derivatives.\n- For `website/assets/images/home/sambee-screenshot.png`, it also regenerates the committed social preview PNG at `website/assets/images/home/generated/sambee-screenshot_1200w.png`.\n\nManual batch generation:\n\n```bash\ncd website\nnpm run images:generate\n```\n\nManual social preview generation:\n\n```bash\ncd website\nnpm run social:generate\n```\n\nDo not rely on CI to create missing derivatives. Missing generated media is a defect.\n\n## Build and Publish Expectations\n\nThe website build and deployment flow is set up around this behavior:\n\n- Local development pulls Git LFS objects before serving the site.\n- The local dev workflow runs the image watcher during `npm run dev`.\n- CI restores and pulls Git LFS objects before building the site.\n- CI validates that raster source images have generated WebP derivatives.\n- The shared head template fails the Hugo build if the committed social preview PNG is missing or is not `1200x630`.\n- CI uploads `website/public` as a short-lived artifact after the build.\n- The deploy job publishes `website/public` to Cloudflare Pages.\n\nThe project scripts that matter most here are:\n\n- `npm run images:generate`\n- `npm run images:validate`\n- `npm run social:generate`\n- `npm run build`\n\nThe workflow lives in `.github/workflows/website-deploy.yml`. The important steps include:\n\n- restore `.git/lfs` cache and run `git lfs pull`\n- restore `website/resources/_gen` cache for faster rebuilds\n- validate generated WebP coverage\n- build the Hugo site and Pagefind index inside `website/`\n- upload `website/public` as a short-lived artifact\n- deploy the built site from `website/public`\n\nFor the Cloudflare-side setup, GitHub Actions secrets, and deployment branch rules, see [Set Up Cloudflare Pages Publishing](../../setup-and-operations/set-up-cloudflare-pages-publishing/).\n", "2.0": "+++\ntitle = \"Media Publishing Workflow\"\n+++\n\nThe website media workflow is repository-driven. The source files and the generated derivatives both belong in the repo.\n\n## Goals\n\n- Source images are committed in the repository.\n- Pre-generated WebP derivatives are committed in the repository.\n- The committed social preview PNG is generated locally and committed in the repository.\n- Source images and generated derivatives are tracked with Git LFS.\n- Every raster source image has generated WebP derivatives.\n- Local development and CI pull media from Git LFS before building.\n- CI publishes built media from `website/public` rather than generating missing derivatives during deployment.\n\n## Required Tools\n\nYou need:\n\n- `git-lfs`\n- ImageMagick's `magick` command when generating derivatives locally\n\nAfter cloning, pull LFS objects before you work on the site:\n\n```bash\ngit lfs pull\n```\n\nIf the LFS objects are missing, a site build may appear to work while still producing broken image references or missing derivatives.\n\n## Source of Truth\n\nThe source of truth for website media is the checked-in asset tree:\n\n- `website/assets/images/` for source images and generated WebPs\n- `website/assets/images/` for source images and committed generated derivatives, including WebPs and the social preview PNG\n- `website/static/files/` for downloadable files\n\nHugo's cached outputs under `website/resources/_gen/images/` are build artifacts, not source content and not committed media.\n\nGenerated derivatives live in a sibling `generated/` directory next to the source image.\n\nExample:\n\n```text\nwebsite/assets/images/home/companion-screenshot.png\nwebsite/assets/images/home/generated/companion-screenshot_372w.webp\nwebsite/assets/images/home/generated/companion-screenshot_500w.webp\nwebsite/assets/images/home/generated/sambee-screenshot_1200w.png\n```\n\n## Authoring Workflow\n\nWhen you add or change a raster image:\n\n1. Add or update the source file under `website/assets/images/`.\n2. Start the website preview task or run `npm run dev`.\n3. Let the local watcher regenerate missing derivatives automatically, or generate them manually.\n4. Review the generated files in the matching `generated/` directory.\n5. Commit the source image and the generated derivatives together.\n\nThe local watcher covers two cases:\n\n- For ordinary raster images, it regenerates the matching WebP derivatives.\n- For `website/assets/images/home/sambee-screenshot.png`, it also regenerates the committed social preview PNG at `website/assets/images/home/generated/sambee-screenshot_1200w.png`.\n\nManual batch generation:\n\n```bash\ncd website\nnpm run images:generate\n```\n\nManual social preview generation:\n\n```bash\ncd website\nnpm run social:generate\n```\n\nDo not rely on CI to create missing derivatives. Missing generated media is a defect.\n\n## Build and Publish Expectations\n\nThe website build and deployment flow is set up around this behavior:\n\n- Local development pulls Git LFS objects before serving the site.\n- The local dev workflow runs the image watcher during `npm run dev`.\n- CI restores and pulls Git LFS objects before building the site.\n- CI validates that raster source images have generated WebP derivatives.\n- The shared head template fails the Hugo build if the committed social preview PNG is missing or is not `1200x630`.\n- CI uploads `website/public` as a short-lived artifact after the build.\n- The deploy job publishes `website/public` to Cloudflare Pages.\n\nThe project scripts that matter most here are:\n\n- `npm run images:generate`\n- `npm run images:validate`\n- `npm run social:generate`\n- `npm run build`\n\nThe workflow lives in `.github/workflows/website-deploy.yml`. The important steps include:\n\n- restore `.git/lfs` cache and run `git lfs pull`\n- restore `website/resources/_gen` cache for faster rebuilds\n- validate generated WebP coverage\n- build the Hugo site and Pagefind index inside `website/`\n- upload `website/public` as a short-lived artifact\n- deploy the built site from `website/public`\n\nFor the Cloudflare-side setup, GitHub Actions secrets, and deployment branch rules, see [Set Up Cloudflare Pages Publishing](../../setup-and-operations/set-up-cloudflare-pages-publishing/).\n"}, "page_contents": {"0.7": "+++\ntitle = \"Media Publishing Workflow\"\n+++\n\nThe website media workflow is repository-driven. The source files and the generated derivatives both belong in the repo.\n\n## Goals\n\n- Source images are committed in the repository.\n- Pre-generated WebP derivatives are committed in the repository.\n- The committed social preview PNG is generated locally and committed in the repository.\n- Source images and generated derivatives are tracked with Git LFS.\n- Every raster source image has generated WebP derivatives.\n- Local development and CI pull media from Git LFS before building.\n- CI publishes built media from `website/public` rather than generating missing derivatives during deployment.\n\n## Required Tools\n\nYou need:\n\n- `git-lfs`\n- ImageMagick's `magick` command when generating derivatives locally\n\nAfter cloning, pull LFS objects before you work on the site:\n\n```bash\ngit lfs pull\n```\n\nIf the LFS objects are missing, a site build may appear to work while still producing broken image references or missing derivatives.\n\n## Source of Truth\n\nThe source of truth for website media is the checked-in asset tree:\n\n- `website/assets/images/` for source images and generated WebPs\n- `website/assets/images/` for source images and committed generated derivatives, including WebPs and the social preview PNG\n- `website/static/files/` for downloadable files\n\nHugo's cached outputs under `website/resources/_gen/images/` are build artifacts, not source content and not committed media.\n\nGenerated derivatives live in a sibling `generated/` directory next to the source image.\n\nExample:\n\n```text\nwebsite/assets/images/home/companion-screenshot.png\nwebsite/assets/images/home/generated/companion-screenshot_372w.webp\nwebsite/assets/images/home/generated/companion-screenshot_500w.webp\nwebsite/assets/images/home/generated/sambee-screenshot_1200w.png\n```\n\n## Authoring Workflow\n\nWhen you add or change a raster image:\n\n1. Add or update the source file under `website/assets/images/`.\n2. Start the website preview task or run `npm run dev`.\n3. Let the local watcher regenerate missing derivatives automatically, or generate them manually.\n4. Review the generated files in the matching `generated/` directory.\n5. Commit the source image and the generated derivatives together.\n\nThe local watcher covers two cases:\n\n- For ordinary raster images, it regenerates the matching WebP derivatives.\n- For `website/assets/images/home/sambee-screenshot.png`, it also regenerates the committed social preview PNG at `website/assets/images/home/generated/sambee-screenshot_1200w.png`.\n\nManual batch generation:\n\n```bash\ncd website\nnpm run images:generate\n```\n\nManual social preview generation:\n\n```bash\ncd website\nnpm run social:generate\n```\n\nDo not rely on CI to create missing derivatives. Missing generated media is a defect.\n\n## Build and Publish Expectations\n\nThe website build and deployment flow is set up around this behavior:\n\n- Local development pulls Git LFS objects before serving the site.\n- The local dev workflow runs the image watcher during `npm run dev`.\n- CI restores and pulls Git LFS objects before building the site.\n- CI validates that raster source images have generated WebP derivatives.\n- The shared head template fails the Hugo build if the committed social preview PNG is missing or is not `1200x630`.\n- CI uploads `website/public` as a short-lived artifact after the build.\n- The deploy job publishes `website/public` to Cloudflare Pages.\n\nThe project scripts that matter most here are:\n\n- `npm run images:generate`\n- `npm run images:validate`\n- `npm run social:generate`\n- `npm run build`\n\nThe workflow lives in `.github/workflows/website-deploy.yml`. The important steps include:\n\n- restore `.git/lfs` cache and run `git lfs pull`\n- restore `website/resources/_gen` cache for faster rebuilds\n- validate generated WebP coverage\n- build the Hugo site and Pagefind index inside `website/`\n- upload `website/public` as a short-lived artifact\n- deploy the built site from `website/public`\n\nFor the Cloudflare-side setup, GitHub Actions secrets, and deployment branch rules, see [Set Up Cloudflare Pages Publishing](../../setup-and-operations/set-up-cloudflare-pages-publishing/).\n", "0.8": "+++\ntitle = \"Media Publishing Workflow\"\n+++\n\nThe website media workflow is repository-driven. The source files and the generated derivatives both belong in the repo.\n\n## Goals\n\n- Source images are committed in the repository.\n- Pre-generated WebP derivatives are committed in the repository.\n- The committed social preview PNG is generated locally and committed in the repository.\n- Source images and generated derivatives are tracked with Git LFS.\n- Every raster source image has generated WebP derivatives.\n- Local development and CI pull media from Git LFS before building.\n- CI publishes built media from `website/public` rather than generating missing derivatives during deployment.\n\n## Required Tools\n\nYou need:\n\n- `git-lfs`\n- ImageMagick's `magick` command when generating derivatives locally\n\nAfter cloning, pull LFS objects before you work on the site:\n\n```bash\ngit lfs pull\n```\n\nIf the LFS objects are missing, a site build may appear to work while still producing broken image references or missing derivatives.\n\n## Source of Truth\n\nThe source of truth for website media is the checked-in asset tree:\n\n- `website/assets/images/` for source images and generated WebPs\n- `website/assets/images/` for source images and committed generated derivatives, including WebPs and the social preview PNG\n- `website/static/files/` for downloadable files\n\nHugo's cached outputs under `website/resources/_gen/images/` are build artifacts, not source content and not committed media.\n\nGenerated derivatives live in a sibling `generated/` directory next to the source image.\n\nExample:\n\n```text\nwebsite/assets/images/home/companion-screenshot.png\nwebsite/assets/images/home/generated/companion-screenshot_372w.webp\nwebsite/assets/images/home/generated/companion-screenshot_500w.webp\nwebsite/assets/images/home/generated/sambee-screenshot_1200w.png\n```\n\n## Authoring Workflow\n\nWhen you add or change a raster image:\n\n1. Add or update the source file under `website/assets/images/`.\n2. Start the website preview task or run `npm run dev`.\n3. Let the local watcher regenerate missing derivatives automatically, or generate them manually.\n4. Review the generated files in the matching `generated/` directory.\n5. Commit the source image and the generated derivatives together.\n\nThe local watcher covers two cases:\n\n- For ordinary raster images, it regenerates the matching WebP derivatives.\n- For `website/assets/images/home/sambee-screenshot.png`, it also regenerates the committed social preview PNG at `website/assets/images/home/generated/sambee-screenshot_1200w.png`.\n\nManual batch generation:\n\n```bash\ncd website\nnpm run images:generate\n```\n\nManual social preview generation:\n\n```bash\ncd website\nnpm run social:generate\n```\n\nDo not rely on CI to create missing derivatives. Missing generated media is a defect.\n\n## Build and Publish Expectations\n\nThe website build and deployment flow is set up around this behavior:\n\n- Local development pulls Git LFS objects before serving the site.\n- The local dev workflow runs the image watcher during `npm run dev`.\n- CI restores and pulls Git LFS objects before building the site.\n- CI validates that raster source images have generated WebP derivatives.\n- The shared head template fails the Hugo build if the committed social preview PNG is missing or is not `1200x630`.\n- CI uploads `website/public` as a short-lived artifact after the build.\n- The deploy job publishes `website/public` to Cloudflare Pages.\n\nThe project scripts that matter most here are:\n\n- `npm run images:generate`\n- `npm run images:validate`\n- `npm run social:generate`\n- `npm run build`\n\nThe workflow lives in `.github/workflows/website-deploy.yml`. The important steps include:\n\n- restore `.git/lfs` cache and run `git lfs pull`\n- restore `website/resources/_gen` cache for faster rebuilds\n- validate generated WebP coverage\n- build the Hugo site and Pagefind index inside `website/`\n- upload `website/public` as a short-lived artifact\n- deploy the built site from `website/public`\n\nFor the Cloudflare-side setup, GitHub Actions secrets, and deployment branch rules, see [Set Up Cloudflare Pages Publishing](../../setup-and-operations/set-up-cloudflare-pages-publishing/).\n", "0.9": "+++\ntitle = \"Media Publishing Workflow\"\n+++\n\nThe website media workflow is repository-driven. The source files and the generated derivatives both belong in the repo.\n\n## Goals\n\n- Source images are committed in the repository.\n- Pre-generated WebP derivatives are committed in the repository.\n- The committed social preview PNG is generated locally and committed in the repository.\n- Source images and generated derivatives are tracked with Git LFS.\n- Every raster source image has generated WebP derivatives.\n- Local development and CI pull media from Git LFS before building.\n- CI publishes built media from `website/public` rather than generating missing derivatives during deployment.\n\n## Required Tools\n\nYou need:\n\n- `git-lfs`\n- ImageMagick's `magick` command when generating derivatives locally\n\nAfter cloning, pull LFS objects before you work on the site:\n\n```bash\ngit lfs pull\n```\n\nIf the LFS objects are missing, a site build may appear to work while still producing broken image references or missing derivatives.\n\n## Source of Truth\n\nThe source of truth for website media is the checked-in asset tree:\n\n- `website/assets/images/` for source images and generated WebPs\n- `website/assets/images/` for source images and committed generated derivatives, including WebPs and the social preview PNG\n- `website/static/files/` for downloadable files\n\nHugo's cached outputs under `website/resources/_gen/images/` are build artifacts, not source content and not committed media.\n\nGenerated derivatives live in a sibling `generated/` directory next to the source image.\n\nExample:\n\n```text\nwebsite/assets/images/home/companion-screenshot.png\nwebsite/assets/images/home/generated/companion-screenshot_372w.webp\nwebsite/assets/images/home/generated/companion-screenshot_500w.webp\nwebsite/assets/images/home/generated/sambee-screenshot_1200w.png\n```\n\n## Authoring Workflow\n\nWhen you add or change a raster image:\n\n1. Add or update the source file under `website/assets/images/`.\n2. Start the website preview task or run `npm run dev`.\n3. Let the local watcher regenerate missing derivatives automatically, or generate them manually.\n4. Review the generated files in the matching `generated/` directory.\n5. Commit the source image and the generated derivatives together.\n\nThe local watcher covers two cases:\n\n- For ordinary raster images, it regenerates the matching WebP derivatives.\n- For `website/assets/images/home/sambee-screenshot.png`, it also regenerates the committed social preview PNG at `website/assets/images/home/generated/sambee-screenshot_1200w.png`.\n\nManual batch generation:\n\n```bash\ncd website\nnpm run images:generate\n```\n\nManual social preview generation:\n\n```bash\ncd website\nnpm run social:generate\n```\n\nDo not rely on CI to create missing derivatives. Missing generated media is a defect.\n\n## Build and Publish Expectations\n\nThe website build and deployment flow is set up around this behavior:\n\n- Local development pulls Git LFS objects before serving the site.\n- The local dev workflow runs the image watcher during `npm run dev`.\n- CI restores and pulls Git LFS objects before building the site.\n- CI validates that raster source images have generated WebP derivatives.\n- The shared head template fails the Hugo build if the committed social preview PNG is missing or is not `1200x630`.\n- CI uploads `website/public` as a short-lived artifact after the build.\n- The deploy job publishes `website/public` to Cloudflare Pages.\n\nThe project scripts that matter most here are:\n\n- `npm run images:generate`\n- `npm run images:validate`\n- `npm run social:generate`\n- `npm run build`\n\nThe workflow lives in `.github/workflows/website-deploy.yml`. The important steps include:\n\n- restore `.git/lfs` cache and run `git lfs pull`\n- restore `website/resources/_gen` cache for faster rebuilds\n- validate generated WebP coverage\n- build the Hugo site and Pagefind index inside `website/`\n- upload `website/public` as a short-lived artifact\n- deploy the built site from `website/public`\n\nFor the Cloudflare-side setup, GitHub Actions secrets, and deployment branch rules, see [Set Up Cloudflare Pages Publishing](../../setup-and-operations/set-up-cloudflare-pages-publishing/).\n", "1.0": "+++\ntitle = \"Media Publishing Workflow\"\n+++\n\nThe website media workflow is repository-driven. The source files and the generated derivatives both belong in the repo.\n\n## Goals\n\n- Source images are committed in the repository.\n- Pre-generated WebP derivatives are committed in the repository.\n- The committed social preview PNG is generated locally and committed in the repository.\n- Source images and generated derivatives are tracked with Git LFS.\n- Every raster source image has generated WebP derivatives.\n- Local development and CI pull media from Git LFS before building.\n- CI publishes built media from `website/public` rather than generating missing derivatives during deployment.\n\n## Required Tools\n\nYou need:\n\n- `git-lfs`\n- ImageMagick's `magick` command when generating derivatives locally\n\nAfter cloning, pull LFS objects before you work on the site:\n\n```bash\ngit lfs pull\n```\n\nIf the LFS objects are missing, a site build may appear to work while still producing broken image references or missing derivatives.\n\n## Source of Truth\n\nThe source of truth for website media is the checked-in asset tree:\n\n- `website/assets/images/` for source images and generated WebPs\n- `website/assets/images/` for source images and committed generated derivatives, including WebPs and the social preview PNG\n- `website/static/files/` for downloadable files\n\nHugo's cached outputs under `website/resources/_gen/images/` are build artifacts, not source content and not committed media.\n\nGenerated derivatives live in a sibling `generated/` directory next to the source image.\n\nExample:\n\n```text\nwebsite/assets/images/home/companion-screenshot.png\nwebsite/assets/images/home/generated/companion-screenshot_372w.webp\nwebsite/assets/images/home/generated/companion-screenshot_500w.webp\nwebsite/assets/images/home/generated/sambee-screenshot_1200w.png\n```\n\n## Authoring Workflow\n\nWhen you add or change a raster image:\n\n1. Add or update the source file under `website/assets/images/`.\n2. Start the website preview task or run `npm run dev`.\n3. Let the local watcher regenerate missing derivatives automatically, or generate them manually.\n4. Review the generated files in the matching `generated/` directory.\n5. Commit the source image and the generated derivatives together.\n\nThe local watcher covers two cases:\n\n- For ordinary raster images, it regenerates the matching WebP derivatives.\n- For `website/assets/images/home/sambee-screenshot.png`, it also regenerates the committed social preview PNG at `website/assets/images/home/generated/sambee-screenshot_1200w.png`.\n\nManual batch generation:\n\n```bash\ncd website\nnpm run images:generate\n```\n\nManual social preview generation:\n\n```bash\ncd website\nnpm run social:generate\n```\n\nDo not rely on CI to create missing derivatives. Missing generated media is a defect.\n\n## Build and Publish Expectations\n\nThe website build and deployment flow is set up around this behavior:\n\n- Local development pulls Git LFS objects before serving the site.\n- The local dev workflow runs the image watcher during `npm run dev`.\n- CI restores and pulls Git LFS objects before building the site.\n- CI validates that raster source images have generated WebP derivatives.\n- The shared head template fails the Hugo build if the committed social preview PNG is missing or is not `1200x630`.\n- CI uploads `website/public` as a short-lived artifact after the build.\n- The deploy job publishes `website/public` to Cloudflare Pages.\n\nThe project scripts that matter most here are:\n\n- `npm run images:generate`\n- `npm run images:validate`\n- `npm run social:generate`\n- `npm run build`\n\nThe workflow lives in `.github/workflows/website-deploy.yml`. The important steps include:\n\n- restore `.git/lfs` cache and run `git lfs pull`\n- restore `website/resources/_gen` cache for faster rebuilds\n- validate generated WebP coverage\n- build the Hugo site and Pagefind index inside `website/`\n- upload `website/public` as a short-lived artifact\n- deploy the built site from `website/public`\n\nFor the Cloudflare-side setup, GitHub Actions secrets, and deployment branch rules, see [Set Up Cloudflare Pages Publishing](../../setup-and-operations/set-up-cloudflare-pages-publishing/).\n", "2.0": "+++\ntitle = \"Media Publishing Workflow\"\n+++\n\nThe website media workflow is repository-driven. The source files and the generated derivatives both belong in the repo.\n\n## Goals\n\n- Source images are committed in the repository.\n- Pre-generated WebP derivatives are committed in the repository.\n- The committed social preview PNG is generated locally and committed in the repository.\n- Source images and generated derivatives are tracked with Git LFS.\n- Every raster source image has generated WebP derivatives.\n- Local development and CI pull media from Git LFS before building.\n- CI publishes built media from `website/public` rather than generating missing derivatives during deployment.\n\n## Required Tools\n\nYou need:\n\n- `git-lfs`\n- ImageMagick's `magick` command when generating derivatives locally\n\nAfter cloning, pull LFS objects before you work on the site:\n\n```bash\ngit lfs pull\n```\n\nIf the LFS objects are missing, a site build may appear to work while still producing broken image references or missing derivatives.\n\n## Source of Truth\n\nThe source of truth for website media is the checked-in asset tree:\n\n- `website/assets/images/` for source images and generated WebPs\n- `website/assets/images/` for source images and committed generated derivatives, including WebPs and the social preview PNG\n- `website/static/files/` for downloadable files\n\nHugo's cached outputs under `website/resources/_gen/images/` are build artifacts, not source content and not committed media.\n\nGenerated derivatives live in a sibling `generated/` directory next to the source image.\n\nExample:\n\n```text\nwebsite/assets/images/home/companion-screenshot.png\nwebsite/assets/images/home/generated/companion-screenshot_372w.webp\nwebsite/assets/images/home/generated/companion-screenshot_500w.webp\nwebsite/assets/images/home/generated/sambee-screenshot_1200w.png\n```\n\n## Authoring Workflow\n\nWhen you add or change a raster image:\n\n1. Add or update the source file under `website/assets/images/`.\n2. Start the website preview task or run `npm run dev`.\n3. Let the local watcher regenerate missing derivatives automatically, or generate them manually.\n4. Review the generated files in the matching `generated/` directory.\n5. Commit the source image and the generated derivatives together.\n\nThe local watcher covers two cases:\n\n- For ordinary raster images, it regenerates the matching WebP derivatives.\n- For `website/assets/images/home/sambee-screenshot.png`, it also regenerates the committed social preview PNG at `website/assets/images/home/generated/sambee-screenshot_1200w.png`.\n\nManual batch generation:\n\n```bash\ncd website\nnpm run images:generate\n```\n\nManual social preview generation:\n\n```bash\ncd website\nnpm run social:generate\n```\n\nDo not rely on CI to create missing derivatives. Missing generated media is a defect.\n\n## Build and Publish Expectations\n\nThe website build and deployment flow is set up around this behavior:\n\n- Local development pulls Git LFS objects before serving the site.\n- The local dev workflow runs the image watcher during `npm run dev`.\n- CI restores and pulls Git LFS objects before building the site.\n- CI validates that raster source images have generated WebP derivatives.\n- The shared head template fails the Hugo build if the committed social preview PNG is missing or is not `1200x630`.\n- CI uploads `website/public` as a short-lived artifact after the build.\n- The deploy job publishes `website/public` to Cloudflare Pages.\n\nThe project scripts that matter most here are:\n\n- `npm run images:generate`\n- `npm run images:validate`\n- `npm run social:generate`\n- `npm run build`\n\nThe workflow lives in `.github/workflows/website-deploy.yml`. The important steps include:\n\n- restore `.git/lfs` cache and run `git lfs pull`\n- restore `website/resources/_gen` cache for faster rebuilds\n- validate generated WebP coverage\n- build the Hugo site and Pagefind index inside `website/`\n- upload `website/public` as a short-lived artifact\n- deploy the built site from `website/public`\n\nFor the Cloudflare-side setup, GitHub Actions secrets, and deployment branch rules, see [Set Up Cloudflare Pages Publishing](../../setup-and-operations/set-up-cloudflare-pages-publishing/).\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:website-dev-guide/site-systems/typography-system", "parent_id": "section:website-dev-guide/site-systems", "depth": 2, "kind": "page", "label": "typography-system", "title": "Typography System", "path": "website-dev-guide/site-systems/typography-system", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Typography System\"\n+++\n\nThis page documents the current typography architecture for the Hugo website theme under `website/themes/sambee`.\n\nIt is a reference for the live system, not a planning note.\n\n## Current Architecture\n\nThe shared typography system has two layers:\n\n1. a token layer in `@theme` in `website/themes/sambee/assets/css/main.css`\n2. a recipe layer in `@utility` in `website/themes/sambee/assets/css/shared.css`\n\nRules of the current implementation:\n\n- `@theme` owns reusable type scale, tracking, and leading values that should be available as Tailwind-native tokens\n- `@utility` owns repeated semantic text roles used across templates\n- each semantic recipe is complete on its own\n- templates apply one semantic `type-*` utility per text role\n- color, spacing, layout, and interaction state remain separate concerns\n- component-local CSS may keep typography local when the role is specific to one component, but it should consume shared tokens where that keeps the site scale aligned\n\n## Shared Token Layer\n\nThe current shared typography token block in `website/themes/sambee/assets/css/main.css` is:\n\n```css\n@theme {\n  --text-copy: var(--font-size-copy-base);\n  --text-label-xs: var(--font-size-label-xs);\n  --text-label-sm: var(--font-size-label-sm);\n  --text-list-item-label: var(--font-size-label-sm);\n  --text-list-index: var(--font-size-copy-sm);\n  --text-list-item-title: var(--font-size-copy-sm);\n  --text-docs-nav: var(--font-size-copy-sm);\n  --text-title-sm: 1.125rem;\n  --text-title-md: 1.5rem;\n  --text-title-xl: 2rem;\n  --text-hero-subtitle: 1.6rem;\n  --text-hero-sm: 2.85rem;\n  --text-hero-md: 3.55rem;\n\n  --tracking-label: 0.1em;\n  --tracking-label-strong: 0.14em;\n  --tracking-eyebrow: 0.22em;\n  --tracking-eyebrow-strong: 0.18em;\n  --tracking-list-item-label: 0.1em;\n  --tracking-hero-subtitle: -0.1rem;\n\n  --leading-copy: 1.625rem;\n  --leading-docs-nav: 1.375;\n  --leading-eyebrow: 1;\n  --leading-title-md: 1.2;\n}\n```\n\nSupporting primitives still come from the shared base and generated theme layers, including:\n\n- `--font-primary`, `--font-secondary`, and `--font-tertiary`\n- `--line-height-heading-tight`\n- `--line-height-copy-base`\n- `--tracking-tight`\n- `--text-4xl`, `--text-5xl`, and `--text-7xl`\n\nNotes:\n\n- `--text-docs-nav` and `--leading-docs-nav` are part of the shared scale because the docs interface reuses the same text role in multiple places\n- hero sizing still combines local tokens with the larger text tokens already exposed by the theme\n- values belong in `@theme` only when they are part of the shared site scale or reused across roles\n\n## Shared Recipe Layer\n\nThe current shared semantic typography utilities are:\n\n- `type-section-title`\n- `type-copy`\n- `type-label-sm`\n- `type-label-strong`\n- `type-label-eyebrow`\n- `type-label-eyebrow-strong`\n- `type-label-xs`\n- `type-list-item-label`\n- `type-list-item-title`\n- `type-docs-nav`\n- `type-hero`\n- `type-title-xl`\n- `type-hero-subtitle`\n- `type-title-md`\n- `type-title-md-tight`\n- `type-title-sm-tight`\n- `type-list-index`\n\nThese utilities are intended to be complete on their own. Do not stack two semantic typography utilities that both set font metrics.\n\nThe current system intentionally does not include:\n\n- `type-label` as a partial base class\n- `type-docs-nav-strong` as a separate semantic utility\n\nDocs current-item emphasis is handled by `type-docs-nav` plus local state styling such as color, weight, and surface treatment.\n\n## Usage and Boundaries\n\nThe detailed usage examples, intentionally absent patterns, and component-boundary rules now live on a separate page so this overview can stay focused on the shared system itself.\n\nContinue to [Typography Usage and Boundaries](../typography-usage-and-boundaries/) for:\n\n- representative `@utility` definitions\n- template usage examples\n- current-item emphasis rules for docs navigation\n- component-local versus shared typography boundaries\n- intentionally absent patterns that should not be reintroduced\n\n## Guardrails\n\nUse these rules for future typography work:\n\n1. use plain Tailwind utilities for one-off cases\n2. add a shared `type-*` utility only when the same semantic role appears in multiple templates\n3. keep each shared utility complete on its own\n4. keep layout, spacing, color, and interaction state outside the semantic typography utility unless the role truly requires them\n5. when a component-local class needs a shared scale value, consume the shared tokens instead of copying magic numbers\n", "0.8": "+++\ntitle = \"Typography System\"\n+++\n\nThis page documents the current typography architecture for the Hugo website theme under `website/themes/sambee`.\n\nIt is a reference for the live system, not a planning note.\n\n## Current Architecture\n\nThe shared typography system has two layers:\n\n1. a token layer in `@theme` in `website/themes/sambee/assets/css/main.css`\n2. a recipe layer in `@utility` in `website/themes/sambee/assets/css/shared.css`\n\nRules of the current implementation:\n\n- `@theme` owns reusable type scale, tracking, and leading values that should be available as Tailwind-native tokens\n- `@utility` owns repeated semantic text roles used across templates\n- each semantic recipe is complete on its own\n- templates apply one semantic `type-*` utility per text role\n- color, spacing, layout, and interaction state remain separate concerns\n- component-local CSS may keep typography local when the role is specific to one component, but it should consume shared tokens where that keeps the site scale aligned\n\n## Shared Token Layer\n\nThe current shared typography token block in `website/themes/sambee/assets/css/main.css` is:\n\n```css\n@theme {\n  --text-copy: var(--font-size-copy-base);\n  --text-label-xs: var(--font-size-label-xs);\n  --text-label-sm: var(--font-size-label-sm);\n  --text-list-item-label: var(--font-size-label-sm);\n  --text-list-index: var(--font-size-copy-sm);\n  --text-list-item-title: var(--font-size-copy-sm);\n  --text-docs-nav: var(--font-size-copy-sm);\n  --text-title-sm: 1.125rem;\n  --text-title-md: 1.5rem;\n  --text-title-xl: 2rem;\n  --text-hero-subtitle: 1.6rem;\n  --text-hero-sm: 2.85rem;\n  --text-hero-md: 3.55rem;\n\n  --tracking-label: 0.1em;\n  --tracking-label-strong: 0.14em;\n  --tracking-eyebrow: 0.22em;\n  --tracking-eyebrow-strong: 0.18em;\n  --tracking-list-item-label: 0.1em;\n  --tracking-hero-subtitle: -0.1rem;\n\n  --leading-copy: 1.625rem;\n  --leading-docs-nav: 1.375;\n  --leading-eyebrow: 1;\n  --leading-title-md: 1.2;\n}\n```\n\nSupporting primitives still come from the shared base and generated theme layers, including:\n\n- `--font-primary`, `--font-secondary`, and `--font-tertiary`\n- `--line-height-heading-tight`\n- `--line-height-copy-base`\n- `--tracking-tight`\n- `--text-4xl`, `--text-5xl`, and `--text-7xl`\n\nNotes:\n\n- `--text-docs-nav` and `--leading-docs-nav` are part of the shared scale because the docs interface reuses the same text role in multiple places\n- hero sizing still combines local tokens with the larger text tokens already exposed by the theme\n- values belong in `@theme` only when they are part of the shared site scale or reused across roles\n\n## Shared Recipe Layer\n\nThe current shared semantic typography utilities are:\n\n- `type-section-title`\n- `type-copy`\n- `type-label-sm`\n- `type-label-strong`\n- `type-label-eyebrow`\n- `type-label-eyebrow-strong`\n- `type-label-xs`\n- `type-list-item-label`\n- `type-list-item-title`\n- `type-docs-nav`\n- `type-hero`\n- `type-title-xl`\n- `type-hero-subtitle`\n- `type-title-md`\n- `type-title-md-tight`\n- `type-title-sm-tight`\n- `type-list-index`\n\nThese utilities are intended to be complete on their own. Do not stack two semantic typography utilities that both set font metrics.\n\nThe current system intentionally does not include:\n\n- `type-label` as a partial base class\n- `type-docs-nav-strong` as a separate semantic utility\n\nDocs current-item emphasis is handled by `type-docs-nav` plus local state styling such as color, weight, and surface treatment.\n\n## Usage and Boundaries\n\nThe detailed usage examples, intentionally absent patterns, and component-boundary rules now live on a separate page so this overview can stay focused on the shared system itself.\n\nContinue to [Typography Usage and Boundaries](../typography-usage-and-boundaries/) for:\n\n- representative `@utility` definitions\n- template usage examples\n- current-item emphasis rules for docs navigation\n- component-local versus shared typography boundaries\n- intentionally absent patterns that should not be reintroduced\n\n## Guardrails\n\nUse these rules for future typography work:\n\n1. use plain Tailwind utilities for one-off cases\n2. add a shared `type-*` utility only when the same semantic role appears in multiple templates\n3. keep each shared utility complete on its own\n4. keep layout, spacing, color, and interaction state outside the semantic typography utility unless the role truly requires them\n5. when a component-local class needs a shared scale value, consume the shared tokens instead of copying magic numbers\n", "0.9": "+++\ntitle = \"Typography System\"\n+++\n\nThis page documents the current typography architecture for the Hugo website theme under `website/themes/sambee`.\n\nIt is a reference for the live system, not a planning note.\n\n## Current Architecture\n\nThe shared typography system has two layers:\n\n1. a token layer in `@theme` in `website/themes/sambee/assets/css/main.css`\n2. a recipe layer in `@utility` in `website/themes/sambee/assets/css/shared.css`\n\nRules of the current implementation:\n\n- `@theme` owns reusable type scale, tracking, and leading values that should be available as Tailwind-native tokens\n- `@utility` owns repeated semantic text roles used across templates\n- each semantic recipe is complete on its own\n- templates apply one semantic `type-*` utility per text role\n- color, spacing, layout, and interaction state remain separate concerns\n- component-local CSS may keep typography local when the role is specific to one component, but it should consume shared tokens where that keeps the site scale aligned\n\n## Shared Token Layer\n\nThe current shared typography token block in `website/themes/sambee/assets/css/main.css` is:\n\n```css\n@theme {\n  --text-copy: var(--font-size-copy-base);\n  --text-label-xs: var(--font-size-label-xs);\n  --text-label-sm: var(--font-size-label-sm);\n  --text-list-item-label: var(--font-size-label-sm);\n  --text-list-index: var(--font-size-copy-sm);\n  --text-list-item-title: var(--font-size-copy-sm);\n  --text-docs-nav: var(--font-size-copy-sm);\n  --text-title-sm: 1.125rem;\n  --text-title-md: 1.5rem;\n  --text-title-xl: 2rem;\n  --text-hero-subtitle: 1.6rem;\n  --text-hero-sm: 2.85rem;\n  --text-hero-md: 3.55rem;\n\n  --tracking-label: 0.1em;\n  --tracking-label-strong: 0.14em;\n  --tracking-eyebrow: 0.22em;\n  --tracking-eyebrow-strong: 0.18em;\n  --tracking-list-item-label: 0.1em;\n  --tracking-hero-subtitle: -0.1rem;\n\n  --leading-copy: 1.625rem;\n  --leading-docs-nav: 1.375;\n  --leading-eyebrow: 1;\n  --leading-title-md: 1.2;\n}\n```\n\nSupporting primitives still come from the shared base and generated theme layers, including:\n\n- `--font-primary`, `--font-secondary`, and `--font-tertiary`\n- `--line-height-heading-tight`\n- `--line-height-copy-base`\n- `--tracking-tight`\n- `--text-4xl`, `--text-5xl`, and `--text-7xl`\n\nNotes:\n\n- `--text-docs-nav` and `--leading-docs-nav` are part of the shared scale because the docs interface reuses the same text role in multiple places\n- hero sizing still combines local tokens with the larger text tokens already exposed by the theme\n- values belong in `@theme` only when they are part of the shared site scale or reused across roles\n\n## Shared Recipe Layer\n\nThe current shared semantic typography utilities are:\n\n- `type-section-title`\n- `type-copy`\n- `type-label-sm`\n- `type-label-strong`\n- `type-label-eyebrow`\n- `type-label-eyebrow-strong`\n- `type-label-xs`\n- `type-list-item-label`\n- `type-list-item-title`\n- `type-docs-nav`\n- `type-hero`\n- `type-title-xl`\n- `type-hero-subtitle`\n- `type-title-md`\n- `type-title-md-tight`\n- `type-title-sm-tight`\n- `type-list-index`\n\nThese utilities are intended to be complete on their own. Do not stack two semantic typography utilities that both set font metrics.\n\nThe current system intentionally does not include:\n\n- `type-label` as a partial base class\n- `type-docs-nav-strong` as a separate semantic utility\n\nDocs current-item emphasis is handled by `type-docs-nav` plus local state styling such as color, weight, and surface treatment.\n\n## Usage and Boundaries\n\nThe detailed usage examples, intentionally absent patterns, and component-boundary rules now live on a separate page so this overview can stay focused on the shared system itself.\n\nContinue to [Typography Usage and Boundaries](../typography-usage-and-boundaries/) for:\n\n- representative `@utility` definitions\n- template usage examples\n- current-item emphasis rules for docs navigation\n- component-local versus shared typography boundaries\n- intentionally absent patterns that should not be reintroduced\n\n## Guardrails\n\nUse these rules for future typography work:\n\n1. use plain Tailwind utilities for one-off cases\n2. add a shared `type-*` utility only when the same semantic role appears in multiple templates\n3. keep each shared utility complete on its own\n4. keep layout, spacing, color, and interaction state outside the semantic typography utility unless the role truly requires them\n5. when a component-local class needs a shared scale value, consume the shared tokens instead of copying magic numbers\n", "1.0": "+++\ntitle = \"Typography System\"\n+++\n\nThis page documents the current typography architecture for the Hugo website theme under `website/themes/sambee`.\n\nIt is a reference for the live system, not a planning note.\n\n## Current Architecture\n\nThe shared typography system has two layers:\n\n1. a token layer in `@theme` in `website/themes/sambee/assets/css/main.css`\n2. a recipe layer in `@utility` in `website/themes/sambee/assets/css/shared.css`\n\nRules of the current implementation:\n\n- `@theme` owns reusable type scale, tracking, and leading values that should be available as Tailwind-native tokens\n- `@utility` owns repeated semantic text roles used across templates\n- each semantic recipe is complete on its own\n- templates apply one semantic `type-*` utility per text role\n- color, spacing, layout, and interaction state remain separate concerns\n- component-local CSS may keep typography local when the role is specific to one component, but it should consume shared tokens where that keeps the site scale aligned\n\n## Shared Token Layer\n\nThe current shared typography token block in `website/themes/sambee/assets/css/main.css` is:\n\n```css\n@theme {\n  --text-copy: var(--font-size-copy-base);\n  --text-label-xs: var(--font-size-label-xs);\n  --text-label-sm: var(--font-size-label-sm);\n  --text-list-item-label: var(--font-size-label-sm);\n  --text-list-index: var(--font-size-copy-sm);\n  --text-list-item-title: var(--font-size-copy-sm);\n  --text-docs-nav: var(--font-size-copy-sm);\n  --text-title-sm: 1.125rem;\n  --text-title-md: 1.5rem;\n  --text-title-xl: 2rem;\n  --text-hero-subtitle: 1.6rem;\n  --text-hero-sm: 2.85rem;\n  --text-hero-md: 3.55rem;\n\n  --tracking-label: 0.1em;\n  --tracking-label-strong: 0.14em;\n  --tracking-eyebrow: 0.22em;\n  --tracking-eyebrow-strong: 0.18em;\n  --tracking-list-item-label: 0.1em;\n  --tracking-hero-subtitle: -0.1rem;\n\n  --leading-copy: 1.625rem;\n  --leading-docs-nav: 1.375;\n  --leading-eyebrow: 1;\n  --leading-title-md: 1.2;\n}\n```\n\nSupporting primitives still come from the shared base and generated theme layers, including:\n\n- `--font-primary`, `--font-secondary`, and `--font-tertiary`\n- `--line-height-heading-tight`\n- `--line-height-copy-base`\n- `--tracking-tight`\n- `--text-4xl`, `--text-5xl`, and `--text-7xl`\n\nNotes:\n\n- `--text-docs-nav` and `--leading-docs-nav` are part of the shared scale because the docs interface reuses the same text role in multiple places\n- hero sizing still combines local tokens with the larger text tokens already exposed by the theme\n- values belong in `@theme` only when they are part of the shared site scale or reused across roles\n\n## Shared Recipe Layer\n\nThe current shared semantic typography utilities are:\n\n- `type-section-title`\n- `type-copy`\n- `type-label-sm`\n- `type-label-strong`\n- `type-label-eyebrow`\n- `type-label-eyebrow-strong`\n- `type-label-xs`\n- `type-list-item-label`\n- `type-list-item-title`\n- `type-docs-nav`\n- `type-hero`\n- `type-title-xl`\n- `type-hero-subtitle`\n- `type-title-md`\n- `type-title-md-tight`\n- `type-title-sm-tight`\n- `type-list-index`\n\nThese utilities are intended to be complete on their own. Do not stack two semantic typography utilities that both set font metrics.\n\nThe current system intentionally does not include:\n\n- `type-label` as a partial base class\n- `type-docs-nav-strong` as a separate semantic utility\n\nDocs current-item emphasis is handled by `type-docs-nav` plus local state styling such as color, weight, and surface treatment.\n\n## Usage and Boundaries\n\nThe detailed usage examples, intentionally absent patterns, and component-boundary rules now live on a separate page so this overview can stay focused on the shared system itself.\n\nContinue to [Typography Usage and Boundaries](../typography-usage-and-boundaries/) for:\n\n- representative `@utility` definitions\n- template usage examples\n- current-item emphasis rules for docs navigation\n- component-local versus shared typography boundaries\n- intentionally absent patterns that should not be reintroduced\n\n## Guardrails\n\nUse these rules for future typography work:\n\n1. use plain Tailwind utilities for one-off cases\n2. add a shared `type-*` utility only when the same semantic role appears in multiple templates\n3. keep each shared utility complete on its own\n4. keep layout, spacing, color, and interaction state outside the semantic typography utility unless the role truly requires them\n5. when a component-local class needs a shared scale value, consume the shared tokens instead of copying magic numbers\n", "2.0": "+++\ntitle = \"Typography System\"\n+++\n\nThis page documents the current typography architecture for the Hugo website theme under `website/themes/sambee`.\n\nIt is a reference for the live system, not a planning note.\n\n## Current Architecture\n\nThe shared typography system has two layers:\n\n1. a token layer in `@theme` in `website/themes/sambee/assets/css/main.css`\n2. a recipe layer in `@utility` in `website/themes/sambee/assets/css/shared.css`\n\nRules of the current implementation:\n\n- `@theme` owns reusable type scale, tracking, and leading values that should be available as Tailwind-native tokens\n- `@utility` owns repeated semantic text roles used across templates\n- each semantic recipe is complete on its own\n- templates apply one semantic `type-*` utility per text role\n- color, spacing, layout, and interaction state remain separate concerns\n- component-local CSS may keep typography local when the role is specific to one component, but it should consume shared tokens where that keeps the site scale aligned\n\n## Shared Token Layer\n\nThe current shared typography token block in `website/themes/sambee/assets/css/main.css` is:\n\n```css\n@theme {\n  --text-copy: var(--font-size-copy-base);\n  --text-label-xs: var(--font-size-label-xs);\n  --text-label-sm: var(--font-size-label-sm);\n  --text-list-item-label: var(--font-size-label-sm);\n  --text-list-index: var(--font-size-copy-sm);\n  --text-list-item-title: var(--font-size-copy-sm);\n  --text-docs-nav: var(--font-size-copy-sm);\n  --text-title-sm: 1.125rem;\n  --text-title-md: 1.5rem;\n  --text-title-xl: 2rem;\n  --text-hero-subtitle: 1.6rem;\n  --text-hero-sm: 2.85rem;\n  --text-hero-md: 3.55rem;\n\n  --tracking-label: 0.1em;\n  --tracking-label-strong: 0.14em;\n  --tracking-eyebrow: 0.22em;\n  --tracking-eyebrow-strong: 0.18em;\n  --tracking-list-item-label: 0.1em;\n  --tracking-hero-subtitle: -0.1rem;\n\n  --leading-copy: 1.625rem;\n  --leading-docs-nav: 1.375;\n  --leading-eyebrow: 1;\n  --leading-title-md: 1.2;\n}\n```\n\nSupporting primitives still come from the shared base and generated theme layers, including:\n\n- `--font-primary`, `--font-secondary`, and `--font-tertiary`\n- `--line-height-heading-tight`\n- `--line-height-copy-base`\n- `--tracking-tight`\n- `--text-4xl`, `--text-5xl`, and `--text-7xl`\n\nNotes:\n\n- `--text-docs-nav` and `--leading-docs-nav` are part of the shared scale because the docs interface reuses the same text role in multiple places\n- hero sizing still combines local tokens with the larger text tokens already exposed by the theme\n- values belong in `@theme` only when they are part of the shared site scale or reused across roles\n\n## Shared Recipe Layer\n\nThe current shared semantic typography utilities are:\n\n- `type-section-title`\n- `type-copy`\n- `type-label-sm`\n- `type-label-strong`\n- `type-label-eyebrow`\n- `type-label-eyebrow-strong`\n- `type-label-xs`\n- `type-list-item-label`\n- `type-list-item-title`\n- `type-docs-nav`\n- `type-hero`\n- `type-title-xl`\n- `type-hero-subtitle`\n- `type-title-md`\n- `type-title-md-tight`\n- `type-title-sm-tight`\n- `type-list-index`\n\nThese utilities are intended to be complete on their own. Do not stack two semantic typography utilities that both set font metrics.\n\nThe current system intentionally does not include:\n\n- `type-label` as a partial base class\n- `type-docs-nav-strong` as a separate semantic utility\n\nDocs current-item emphasis is handled by `type-docs-nav` plus local state styling such as color, weight, and surface treatment.\n\n## Usage and Boundaries\n\nThe detailed usage examples, intentionally absent patterns, and component-boundary rules now live on a separate page so this overview can stay focused on the shared system itself.\n\nContinue to [Typography Usage and Boundaries](../typography-usage-and-boundaries/) for:\n\n- representative `@utility` definitions\n- template usage examples\n- current-item emphasis rules for docs navigation\n- component-local versus shared typography boundaries\n- intentionally absent patterns that should not be reintroduced\n\n## Guardrails\n\nUse these rules for future typography work:\n\n1. use plain Tailwind utilities for one-off cases\n2. add a shared `type-*` utility only when the same semantic role appears in multiple templates\n3. keep each shared utility complete on its own\n4. keep layout, spacing, color, and interaction state outside the semantic typography utility unless the role truly requires them\n5. when a component-local class needs a shared scale value, consume the shared tokens instead of copying magic numbers\n"}, "page_contents": {"0.7": "+++\ntitle = \"Typography System\"\n+++\n\nThis page documents the current typography architecture for the Hugo website theme under `website/themes/sambee`.\n\nIt is a reference for the live system, not a planning note.\n\n## Current Architecture\n\nThe shared typography system has two layers:\n\n1. a token layer in `@theme` in `website/themes/sambee/assets/css/main.css`\n2. a recipe layer in `@utility` in `website/themes/sambee/assets/css/shared.css`\n\nRules of the current implementation:\n\n- `@theme` owns reusable type scale, tracking, and leading values that should be available as Tailwind-native tokens\n- `@utility` owns repeated semantic text roles used across templates\n- each semantic recipe is complete on its own\n- templates apply one semantic `type-*` utility per text role\n- color, spacing, layout, and interaction state remain separate concerns\n- component-local CSS may keep typography local when the role is specific to one component, but it should consume shared tokens where that keeps the site scale aligned\n\n## Shared Token Layer\n\nThe current shared typography token block in `website/themes/sambee/assets/css/main.css` is:\n\n```css\n@theme {\n  --text-copy: var(--font-size-copy-base);\n  --text-label-xs: var(--font-size-label-xs);\n  --text-label-sm: var(--font-size-label-sm);\n  --text-list-item-label: var(--font-size-label-sm);\n  --text-list-index: var(--font-size-copy-sm);\n  --text-list-item-title: var(--font-size-copy-sm);\n  --text-docs-nav: var(--font-size-copy-sm);\n  --text-title-sm: 1.125rem;\n  --text-title-md: 1.5rem;\n  --text-title-xl: 2rem;\n  --text-hero-subtitle: 1.6rem;\n  --text-hero-sm: 2.85rem;\n  --text-hero-md: 3.55rem;\n\n  --tracking-label: 0.1em;\n  --tracking-label-strong: 0.14em;\n  --tracking-eyebrow: 0.22em;\n  --tracking-eyebrow-strong: 0.18em;\n  --tracking-list-item-label: 0.1em;\n  --tracking-hero-subtitle: -0.1rem;\n\n  --leading-copy: 1.625rem;\n  --leading-docs-nav: 1.375;\n  --leading-eyebrow: 1;\n  --leading-title-md: 1.2;\n}\n```\n\nSupporting primitives still come from the shared base and generated theme layers, including:\n\n- `--font-primary`, `--font-secondary`, and `--font-tertiary`\n- `--line-height-heading-tight`\n- `--line-height-copy-base`\n- `--tracking-tight`\n- `--text-4xl`, `--text-5xl`, and `--text-7xl`\n\nNotes:\n\n- `--text-docs-nav` and `--leading-docs-nav` are part of the shared scale because the docs interface reuses the same text role in multiple places\n- hero sizing still combines local tokens with the larger text tokens already exposed by the theme\n- values belong in `@theme` only when they are part of the shared site scale or reused across roles\n\n## Shared Recipe Layer\n\nThe current shared semantic typography utilities are:\n\n- `type-section-title`\n- `type-copy`\n- `type-label-sm`\n- `type-label-strong`\n- `type-label-eyebrow`\n- `type-label-eyebrow-strong`\n- `type-label-xs`\n- `type-list-item-label`\n- `type-list-item-title`\n- `type-docs-nav`\n- `type-hero`\n- `type-title-xl`\n- `type-hero-subtitle`\n- `type-title-md`\n- `type-title-md-tight`\n- `type-title-sm-tight`\n- `type-list-index`\n\nThese utilities are intended to be complete on their own. Do not stack two semantic typography utilities that both set font metrics.\n\nThe current system intentionally does not include:\n\n- `type-label` as a partial base class\n- `type-docs-nav-strong` as a separate semantic utility\n\nDocs current-item emphasis is handled by `type-docs-nav` plus local state styling such as color, weight, and surface treatment.\n\n## Usage and Boundaries\n\nThe detailed usage examples, intentionally absent patterns, and component-boundary rules now live on a separate page so this overview can stay focused on the shared system itself.\n\nContinue to [Typography Usage and Boundaries](../typography-usage-and-boundaries/) for:\n\n- representative `@utility` definitions\n- template usage examples\n- current-item emphasis rules for docs navigation\n- component-local versus shared typography boundaries\n- intentionally absent patterns that should not be reintroduced\n\n## Guardrails\n\nUse these rules for future typography work:\n\n1. use plain Tailwind utilities for one-off cases\n2. add a shared `type-*` utility only when the same semantic role appears in multiple templates\n3. keep each shared utility complete on its own\n4. keep layout, spacing, color, and interaction state outside the semantic typography utility unless the role truly requires them\n5. when a component-local class needs a shared scale value, consume the shared tokens instead of copying magic numbers\n", "0.8": "+++\ntitle = \"Typography System\"\n+++\n\nThis page documents the current typography architecture for the Hugo website theme under `website/themes/sambee`.\n\nIt is a reference for the live system, not a planning note.\n\n## Current Architecture\n\nThe shared typography system has two layers:\n\n1. a token layer in `@theme` in `website/themes/sambee/assets/css/main.css`\n2. a recipe layer in `@utility` in `website/themes/sambee/assets/css/shared.css`\n\nRules of the current implementation:\n\n- `@theme` owns reusable type scale, tracking, and leading values that should be available as Tailwind-native tokens\n- `@utility` owns repeated semantic text roles used across templates\n- each semantic recipe is complete on its own\n- templates apply one semantic `type-*` utility per text role\n- color, spacing, layout, and interaction state remain separate concerns\n- component-local CSS may keep typography local when the role is specific to one component, but it should consume shared tokens where that keeps the site scale aligned\n\n## Shared Token Layer\n\nThe current shared typography token block in `website/themes/sambee/assets/css/main.css` is:\n\n```css\n@theme {\n  --text-copy: var(--font-size-copy-base);\n  --text-label-xs: var(--font-size-label-xs);\n  --text-label-sm: var(--font-size-label-sm);\n  --text-list-item-label: var(--font-size-label-sm);\n  --text-list-index: var(--font-size-copy-sm);\n  --text-list-item-title: var(--font-size-copy-sm);\n  --text-docs-nav: var(--font-size-copy-sm);\n  --text-title-sm: 1.125rem;\n  --text-title-md: 1.5rem;\n  --text-title-xl: 2rem;\n  --text-hero-subtitle: 1.6rem;\n  --text-hero-sm: 2.85rem;\n  --text-hero-md: 3.55rem;\n\n  --tracking-label: 0.1em;\n  --tracking-label-strong: 0.14em;\n  --tracking-eyebrow: 0.22em;\n  --tracking-eyebrow-strong: 0.18em;\n  --tracking-list-item-label: 0.1em;\n  --tracking-hero-subtitle: -0.1rem;\n\n  --leading-copy: 1.625rem;\n  --leading-docs-nav: 1.375;\n  --leading-eyebrow: 1;\n  --leading-title-md: 1.2;\n}\n```\n\nSupporting primitives still come from the shared base and generated theme layers, including:\n\n- `--font-primary`, `--font-secondary`, and `--font-tertiary`\n- `--line-height-heading-tight`\n- `--line-height-copy-base`\n- `--tracking-tight`\n- `--text-4xl`, `--text-5xl`, and `--text-7xl`\n\nNotes:\n\n- `--text-docs-nav` and `--leading-docs-nav` are part of the shared scale because the docs interface reuses the same text role in multiple places\n- hero sizing still combines local tokens with the larger text tokens already exposed by the theme\n- values belong in `@theme` only when they are part of the shared site scale or reused across roles\n\n## Shared Recipe Layer\n\nThe current shared semantic typography utilities are:\n\n- `type-section-title`\n- `type-copy`\n- `type-label-sm`\n- `type-label-strong`\n- `type-label-eyebrow`\n- `type-label-eyebrow-strong`\n- `type-label-xs`\n- `type-list-item-label`\n- `type-list-item-title`\n- `type-docs-nav`\n- `type-hero`\n- `type-title-xl`\n- `type-hero-subtitle`\n- `type-title-md`\n- `type-title-md-tight`\n- `type-title-sm-tight`\n- `type-list-index`\n\nThese utilities are intended to be complete on their own. Do not stack two semantic typography utilities that both set font metrics.\n\nThe current system intentionally does not include:\n\n- `type-label` as a partial base class\n- `type-docs-nav-strong` as a separate semantic utility\n\nDocs current-item emphasis is handled by `type-docs-nav` plus local state styling such as color, weight, and surface treatment.\n\n## Usage and Boundaries\n\nThe detailed usage examples, intentionally absent patterns, and component-boundary rules now live on a separate page so this overview can stay focused on the shared system itself.\n\nContinue to [Typography Usage and Boundaries](../typography-usage-and-boundaries/) for:\n\n- representative `@utility` definitions\n- template usage examples\n- current-item emphasis rules for docs navigation\n- component-local versus shared typography boundaries\n- intentionally absent patterns that should not be reintroduced\n\n## Guardrails\n\nUse these rules for future typography work:\n\n1. use plain Tailwind utilities for one-off cases\n2. add a shared `type-*` utility only when the same semantic role appears in multiple templates\n3. keep each shared utility complete on its own\n4. keep layout, spacing, color, and interaction state outside the semantic typography utility unless the role truly requires them\n5. when a component-local class needs a shared scale value, consume the shared tokens instead of copying magic numbers\n", "0.9": "+++\ntitle = \"Typography System\"\n+++\n\nThis page documents the current typography architecture for the Hugo website theme under `website/themes/sambee`.\n\nIt is a reference for the live system, not a planning note.\n\n## Current Architecture\n\nThe shared typography system has two layers:\n\n1. a token layer in `@theme` in `website/themes/sambee/assets/css/main.css`\n2. a recipe layer in `@utility` in `website/themes/sambee/assets/css/shared.css`\n\nRules of the current implementation:\n\n- `@theme` owns reusable type scale, tracking, and leading values that should be available as Tailwind-native tokens\n- `@utility` owns repeated semantic text roles used across templates\n- each semantic recipe is complete on its own\n- templates apply one semantic `type-*` utility per text role\n- color, spacing, layout, and interaction state remain separate concerns\n- component-local CSS may keep typography local when the role is specific to one component, but it should consume shared tokens where that keeps the site scale aligned\n\n## Shared Token Layer\n\nThe current shared typography token block in `website/themes/sambee/assets/css/main.css` is:\n\n```css\n@theme {\n  --text-copy: var(--font-size-copy-base);\n  --text-label-xs: var(--font-size-label-xs);\n  --text-label-sm: var(--font-size-label-sm);\n  --text-list-item-label: var(--font-size-label-sm);\n  --text-list-index: var(--font-size-copy-sm);\n  --text-list-item-title: var(--font-size-copy-sm);\n  --text-docs-nav: var(--font-size-copy-sm);\n  --text-title-sm: 1.125rem;\n  --text-title-md: 1.5rem;\n  --text-title-xl: 2rem;\n  --text-hero-subtitle: 1.6rem;\n  --text-hero-sm: 2.85rem;\n  --text-hero-md: 3.55rem;\n\n  --tracking-label: 0.1em;\n  --tracking-label-strong: 0.14em;\n  --tracking-eyebrow: 0.22em;\n  --tracking-eyebrow-strong: 0.18em;\n  --tracking-list-item-label: 0.1em;\n  --tracking-hero-subtitle: -0.1rem;\n\n  --leading-copy: 1.625rem;\n  --leading-docs-nav: 1.375;\n  --leading-eyebrow: 1;\n  --leading-title-md: 1.2;\n}\n```\n\nSupporting primitives still come from the shared base and generated theme layers, including:\n\n- `--font-primary`, `--font-secondary`, and `--font-tertiary`\n- `--line-height-heading-tight`\n- `--line-height-copy-base`\n- `--tracking-tight`\n- `--text-4xl`, `--text-5xl`, and `--text-7xl`\n\nNotes:\n\n- `--text-docs-nav` and `--leading-docs-nav` are part of the shared scale because the docs interface reuses the same text role in multiple places\n- hero sizing still combines local tokens with the larger text tokens already exposed by the theme\n- values belong in `@theme` only when they are part of the shared site scale or reused across roles\n\n## Shared Recipe Layer\n\nThe current shared semantic typography utilities are:\n\n- `type-section-title`\n- `type-copy`\n- `type-label-sm`\n- `type-label-strong`\n- `type-label-eyebrow`\n- `type-label-eyebrow-strong`\n- `type-label-xs`\n- `type-list-item-label`\n- `type-list-item-title`\n- `type-docs-nav`\n- `type-hero`\n- `type-title-xl`\n- `type-hero-subtitle`\n- `type-title-md`\n- `type-title-md-tight`\n- `type-title-sm-tight`\n- `type-list-index`\n\nThese utilities are intended to be complete on their own. Do not stack two semantic typography utilities that both set font metrics.\n\nThe current system intentionally does not include:\n\n- `type-label` as a partial base class\n- `type-docs-nav-strong` as a separate semantic utility\n\nDocs current-item emphasis is handled by `type-docs-nav` plus local state styling such as color, weight, and surface treatment.\n\n## Usage and Boundaries\n\nThe detailed usage examples, intentionally absent patterns, and component-boundary rules now live on a separate page so this overview can stay focused on the shared system itself.\n\nContinue to [Typography Usage and Boundaries](../typography-usage-and-boundaries/) for:\n\n- representative `@utility` definitions\n- template usage examples\n- current-item emphasis rules for docs navigation\n- component-local versus shared typography boundaries\n- intentionally absent patterns that should not be reintroduced\n\n## Guardrails\n\nUse these rules for future typography work:\n\n1. use plain Tailwind utilities for one-off cases\n2. add a shared `type-*` utility only when the same semantic role appears in multiple templates\n3. keep each shared utility complete on its own\n4. keep layout, spacing, color, and interaction state outside the semantic typography utility unless the role truly requires them\n5. when a component-local class needs a shared scale value, consume the shared tokens instead of copying magic numbers\n", "1.0": "+++\ntitle = \"Typography System\"\n+++\n\nThis page documents the current typography architecture for the Hugo website theme under `website/themes/sambee`.\n\nIt is a reference for the live system, not a planning note.\n\n## Current Architecture\n\nThe shared typography system has two layers:\n\n1. a token layer in `@theme` in `website/themes/sambee/assets/css/main.css`\n2. a recipe layer in `@utility` in `website/themes/sambee/assets/css/shared.css`\n\nRules of the current implementation:\n\n- `@theme` owns reusable type scale, tracking, and leading values that should be available as Tailwind-native tokens\n- `@utility` owns repeated semantic text roles used across templates\n- each semantic recipe is complete on its own\n- templates apply one semantic `type-*` utility per text role\n- color, spacing, layout, and interaction state remain separate concerns\n- component-local CSS may keep typography local when the role is specific to one component, but it should consume shared tokens where that keeps the site scale aligned\n\n## Shared Token Layer\n\nThe current shared typography token block in `website/themes/sambee/assets/css/main.css` is:\n\n```css\n@theme {\n  --text-copy: var(--font-size-copy-base);\n  --text-label-xs: var(--font-size-label-xs);\n  --text-label-sm: var(--font-size-label-sm);\n  --text-list-item-label: var(--font-size-label-sm);\n  --text-list-index: var(--font-size-copy-sm);\n  --text-list-item-title: var(--font-size-copy-sm);\n  --text-docs-nav: var(--font-size-copy-sm);\n  --text-title-sm: 1.125rem;\n  --text-title-md: 1.5rem;\n  --text-title-xl: 2rem;\n  --text-hero-subtitle: 1.6rem;\n  --text-hero-sm: 2.85rem;\n  --text-hero-md: 3.55rem;\n\n  --tracking-label: 0.1em;\n  --tracking-label-strong: 0.14em;\n  --tracking-eyebrow: 0.22em;\n  --tracking-eyebrow-strong: 0.18em;\n  --tracking-list-item-label: 0.1em;\n  --tracking-hero-subtitle: -0.1rem;\n\n  --leading-copy: 1.625rem;\n  --leading-docs-nav: 1.375;\n  --leading-eyebrow: 1;\n  --leading-title-md: 1.2;\n}\n```\n\nSupporting primitives still come from the shared base and generated theme layers, including:\n\n- `--font-primary`, `--font-secondary`, and `--font-tertiary`\n- `--line-height-heading-tight`\n- `--line-height-copy-base`\n- `--tracking-tight`\n- `--text-4xl`, `--text-5xl`, and `--text-7xl`\n\nNotes:\n\n- `--text-docs-nav` and `--leading-docs-nav` are part of the shared scale because the docs interface reuses the same text role in multiple places\n- hero sizing still combines local tokens with the larger text tokens already exposed by the theme\n- values belong in `@theme` only when they are part of the shared site scale or reused across roles\n\n## Shared Recipe Layer\n\nThe current shared semantic typography utilities are:\n\n- `type-section-title`\n- `type-copy`\n- `type-label-sm`\n- `type-label-strong`\n- `type-label-eyebrow`\n- `type-label-eyebrow-strong`\n- `type-label-xs`\n- `type-list-item-label`\n- `type-list-item-title`\n- `type-docs-nav`\n- `type-hero`\n- `type-title-xl`\n- `type-hero-subtitle`\n- `type-title-md`\n- `type-title-md-tight`\n- `type-title-sm-tight`\n- `type-list-index`\n\nThese utilities are intended to be complete on their own. Do not stack two semantic typography utilities that both set font metrics.\n\nThe current system intentionally does not include:\n\n- `type-label` as a partial base class\n- `type-docs-nav-strong` as a separate semantic utility\n\nDocs current-item emphasis is handled by `type-docs-nav` plus local state styling such as color, weight, and surface treatment.\n\n## Usage and Boundaries\n\nThe detailed usage examples, intentionally absent patterns, and component-boundary rules now live on a separate page so this overview can stay focused on the shared system itself.\n\nContinue to [Typography Usage and Boundaries](../typography-usage-and-boundaries/) for:\n\n- representative `@utility` definitions\n- template usage examples\n- current-item emphasis rules for docs navigation\n- component-local versus shared typography boundaries\n- intentionally absent patterns that should not be reintroduced\n\n## Guardrails\n\nUse these rules for future typography work:\n\n1. use plain Tailwind utilities for one-off cases\n2. add a shared `type-*` utility only when the same semantic role appears in multiple templates\n3. keep each shared utility complete on its own\n4. keep layout, spacing, color, and interaction state outside the semantic typography utility unless the role truly requires them\n5. when a component-local class needs a shared scale value, consume the shared tokens instead of copying magic numbers\n", "2.0": "+++\ntitle = \"Typography System\"\n+++\n\nThis page documents the current typography architecture for the Hugo website theme under `website/themes/sambee`.\n\nIt is a reference for the live system, not a planning note.\n\n## Current Architecture\n\nThe shared typography system has two layers:\n\n1. a token layer in `@theme` in `website/themes/sambee/assets/css/main.css`\n2. a recipe layer in `@utility` in `website/themes/sambee/assets/css/shared.css`\n\nRules of the current implementation:\n\n- `@theme` owns reusable type scale, tracking, and leading values that should be available as Tailwind-native tokens\n- `@utility` owns repeated semantic text roles used across templates\n- each semantic recipe is complete on its own\n- templates apply one semantic `type-*` utility per text role\n- color, spacing, layout, and interaction state remain separate concerns\n- component-local CSS may keep typography local when the role is specific to one component, but it should consume shared tokens where that keeps the site scale aligned\n\n## Shared Token Layer\n\nThe current shared typography token block in `website/themes/sambee/assets/css/main.css` is:\n\n```css\n@theme {\n  --text-copy: var(--font-size-copy-base);\n  --text-label-xs: var(--font-size-label-xs);\n  --text-label-sm: var(--font-size-label-sm);\n  --text-list-item-label: var(--font-size-label-sm);\n  --text-list-index: var(--font-size-copy-sm);\n  --text-list-item-title: var(--font-size-copy-sm);\n  --text-docs-nav: var(--font-size-copy-sm);\n  --text-title-sm: 1.125rem;\n  --text-title-md: 1.5rem;\n  --text-title-xl: 2rem;\n  --text-hero-subtitle: 1.6rem;\n  --text-hero-sm: 2.85rem;\n  --text-hero-md: 3.55rem;\n\n  --tracking-label: 0.1em;\n  --tracking-label-strong: 0.14em;\n  --tracking-eyebrow: 0.22em;\n  --tracking-eyebrow-strong: 0.18em;\n  --tracking-list-item-label: 0.1em;\n  --tracking-hero-subtitle: -0.1rem;\n\n  --leading-copy: 1.625rem;\n  --leading-docs-nav: 1.375;\n  --leading-eyebrow: 1;\n  --leading-title-md: 1.2;\n}\n```\n\nSupporting primitives still come from the shared base and generated theme layers, including:\n\n- `--font-primary`, `--font-secondary`, and `--font-tertiary`\n- `--line-height-heading-tight`\n- `--line-height-copy-base`\n- `--tracking-tight`\n- `--text-4xl`, `--text-5xl`, and `--text-7xl`\n\nNotes:\n\n- `--text-docs-nav` and `--leading-docs-nav` are part of the shared scale because the docs interface reuses the same text role in multiple places\n- hero sizing still combines local tokens with the larger text tokens already exposed by the theme\n- values belong in `@theme` only when they are part of the shared site scale or reused across roles\n\n## Shared Recipe Layer\n\nThe current shared semantic typography utilities are:\n\n- `type-section-title`\n- `type-copy`\n- `type-label-sm`\n- `type-label-strong`\n- `type-label-eyebrow`\n- `type-label-eyebrow-strong`\n- `type-label-xs`\n- `type-list-item-label`\n- `type-list-item-title`\n- `type-docs-nav`\n- `type-hero`\n- `type-title-xl`\n- `type-hero-subtitle`\n- `type-title-md`\n- `type-title-md-tight`\n- `type-title-sm-tight`\n- `type-list-index`\n\nThese utilities are intended to be complete on their own. Do not stack two semantic typography utilities that both set font metrics.\n\nThe current system intentionally does not include:\n\n- `type-label` as a partial base class\n- `type-docs-nav-strong` as a separate semantic utility\n\nDocs current-item emphasis is handled by `type-docs-nav` plus local state styling such as color, weight, and surface treatment.\n\n## Usage and Boundaries\n\nThe detailed usage examples, intentionally absent patterns, and component-boundary rules now live on a separate page so this overview can stay focused on the shared system itself.\n\nContinue to [Typography Usage and Boundaries](../typography-usage-and-boundaries/) for:\n\n- representative `@utility` definitions\n- template usage examples\n- current-item emphasis rules for docs navigation\n- component-local versus shared typography boundaries\n- intentionally absent patterns that should not be reintroduced\n\n## Guardrails\n\nUse these rules for future typography work:\n\n1. use plain Tailwind utilities for one-off cases\n2. add a shared `type-*` utility only when the same semantic role appears in multiple templates\n3. keep each shared utility complete on its own\n4. keep layout, spacing, color, and interaction state outside the semantic typography utility unless the role truly requires them\n5. when a component-local class needs a shared scale value, consume the shared tokens instead of copying magic numbers\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:website-dev-guide/site-systems/typography-usage-and-boundaries", "parent_id": "section:website-dev-guide/site-systems", "depth": 2, "kind": "page", "label": "typography-usage-and-boundaries", "title": "Typography Usage And Boundaries", "path": "website-dev-guide/site-systems/typography-usage-and-boundaries", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Typography Usage and Boundaries\"\n+++\n\nThis page covers the applied side of the website typography system.\n\nUse it when you need examples, implementation patterns, or boundary rules for deciding whether typography belongs in a shared utility or in component-local CSS.\n\n## Representative Definitions\n\nRepresentative implementations from `website/themes/sambee/assets/css/shared.css`:\n\n```css\n@utility type-copy {\n  font-family: var(--font-primary);\n  font-size: var(--text-copy);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-copy);\n}\n\n@utility type-label-sm {\n  font-family: var(--font-tertiary);\n  font-size: var(--text-label-sm);\n  font-weight: 400;\n  font-style: normal;\n  text-transform: uppercase;\n  letter-spacing: var(--tracking-label);\n}\n\n@utility type-docs-nav {\n  font-family: var(--font-primary);\n  font-size: var(--text-docs-nav);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-docs-nav);\n}\n\n@utility type-title-md {\n  font-family: var(--font-secondary);\n  font-size: var(--text-title-md);\n  font-weight: 700;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-title-md);\n}\n```\n\n## Template Usage Rules\n\nTemplates should apply one semantic typography utility per text role and then combine it with separate classes for color, layout, and interaction state.\n\nExamples from the live theme:\n\n```html\n\u003cspan class=\"type-label-eyebrow type-color-accent eyebrow-stack\"\u003eDocumentation\u003c/span\u003e\n\u003ch2 class=\"type-section-title type-color-ink\"\u003eFast local-first preview\u003c/h2\u003e\n\u003cspan class=\"docs-sidebar-link docs-sidebar-link-current type-docs-nav type-color-ink ui-current-primary-inset\"\u003eCurrent page\u003c/span\u003e\n\u003ca class=\"docs-sidebar-link type-docs-nav type-color-muted ui-transition-color type-hover-ink ui-hover-surface-mid\" href=\"/docs/\"\u003eDocumentation\u003c/a\u003e\n```\n\nCurrent usage rules:\n\n- apply exactly one semantic `type-*` utility to a text element\n- combine it with color helpers, layout helpers, and component-specific state classes as needed\n- do not stack two `type-*` utilities that both set size, weight, letter-spacing, line-height, or transform\n- do not reintroduce a partial base class such as `type-label`\n\nPatterns intentionally absent from the current theme include:\n\n```html\n\u003cspan class=\"type-label type-label-strong\"\u003e...\u003c/span\u003e\n\u003cspan class=\"type-label type-label-xs\"\u003e...\u003c/span\u003e\n\u003cli class=\"type-label type-list-item-label\"\u003e...\u003c/li\u003e\n```\n\n## Local Typography Boundaries\n\nNot every text treatment is shared.\n\n### Docs UI\n\n`website/themes/sambee/assets/css/docs.css` uses the shared `type-docs-nav` role for repeated documentation navigation text, including:\n\n- table of contents links\n- version switcher labels and options\n- nav tree links and current items\n- sequential navigation labels and titles\n\nLocal docs classes still own padding, indentation, and current-item state. For example, `.docs-sidebar-link-current` adds the stronger weight for the active item instead of relying on a separate semantic utility.\n\n### Navigation\n\n`website/themes/sambee/assets/css/navigation.css` keeps `.nav-link` as a component-local role. It consumes shared tracking values so the navigation remains aligned with the site-wide label scale.\n\n### Buttons\n\n`website/themes/sambee/assets/css/buttons.css` keeps `.btn` and `.btn-sm` as local button primitives. They consume shared typography tokens where it makes sense, but buttons are not modeled as shared text-role utilities.\n\n### Footer\n\nFooter layout classes remain local in `website/themes/sambee/assets/css/footer.css`. Shared typography utilities still supply the text role where that role is reused across templates.\n\n### Content-Specific Typography\n\nArticle-content semantics such as table headers, `figcaption`, `dt`, and admonition titles remain local to `content.css`. They belong to the content domain, not to shared site-wide text roles.\n", "0.8": "+++\ntitle = \"Typography Usage and Boundaries\"\n+++\n\nThis page covers the applied side of the website typography system.\n\nUse it when you need examples, implementation patterns, or boundary rules for deciding whether typography belongs in a shared utility or in component-local CSS.\n\n## Representative Definitions\n\nRepresentative implementations from `website/themes/sambee/assets/css/shared.css`:\n\n```css\n@utility type-copy {\n  font-family: var(--font-primary);\n  font-size: var(--text-copy);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-copy);\n}\n\n@utility type-label-sm {\n  font-family: var(--font-tertiary);\n  font-size: var(--text-label-sm);\n  font-weight: 400;\n  font-style: normal;\n  text-transform: uppercase;\n  letter-spacing: var(--tracking-label);\n}\n\n@utility type-docs-nav {\n  font-family: var(--font-primary);\n  font-size: var(--text-docs-nav);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-docs-nav);\n}\n\n@utility type-title-md {\n  font-family: var(--font-secondary);\n  font-size: var(--text-title-md);\n  font-weight: 700;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-title-md);\n}\n```\n\n## Template Usage Rules\n\nTemplates should apply one semantic typography utility per text role and then combine it with separate classes for color, layout, and interaction state.\n\nExamples from the live theme:\n\n```html\n\u003cspan class=\"type-label-eyebrow type-color-accent eyebrow-stack\"\u003eDocumentation\u003c/span\u003e\n\u003ch2 class=\"type-section-title type-color-ink\"\u003eFast local-first preview\u003c/h2\u003e\n\u003cspan class=\"docs-sidebar-link docs-sidebar-link-current type-docs-nav type-color-ink ui-current-primary-inset\"\u003eCurrent page\u003c/span\u003e\n\u003ca class=\"docs-sidebar-link type-docs-nav type-color-muted ui-transition-color type-hover-ink ui-hover-surface-mid\" href=\"/docs/\"\u003eDocumentation\u003c/a\u003e\n```\n\nCurrent usage rules:\n\n- apply exactly one semantic `type-*` utility to a text element\n- combine it with color helpers, layout helpers, and component-specific state classes as needed\n- do not stack two `type-*` utilities that both set size, weight, letter-spacing, line-height, or transform\n- do not reintroduce a partial base class such as `type-label`\n\nPatterns intentionally absent from the current theme include:\n\n```html\n\u003cspan class=\"type-label type-label-strong\"\u003e...\u003c/span\u003e\n\u003cspan class=\"type-label type-label-xs\"\u003e...\u003c/span\u003e\n\u003cli class=\"type-label type-list-item-label\"\u003e...\u003c/li\u003e\n```\n\n## Local Typography Boundaries\n\nNot every text treatment is shared.\n\n### Docs UI\n\n`website/themes/sambee/assets/css/docs.css` uses the shared `type-docs-nav` role for repeated documentation navigation text, including:\n\n- table of contents links\n- version switcher labels and options\n- nav tree links and current items\n- sequential navigation labels and titles\n\nLocal docs classes still own padding, indentation, and current-item state. For example, `.docs-sidebar-link-current` adds the stronger weight for the active item instead of relying on a separate semantic utility.\n\n### Navigation\n\n`website/themes/sambee/assets/css/navigation.css` keeps `.nav-link` as a component-local role. It consumes shared tracking values so the navigation remains aligned with the site-wide label scale.\n\n### Buttons\n\n`website/themes/sambee/assets/css/buttons.css` keeps `.btn` and `.btn-sm` as local button primitives. They consume shared typography tokens where it makes sense, but buttons are not modeled as shared text-role utilities.\n\n### Footer\n\nFooter layout classes remain local in `website/themes/sambee/assets/css/footer.css`. Shared typography utilities still supply the text role where that role is reused across templates.\n\n### Content-Specific Typography\n\nArticle-content semantics such as table headers, `figcaption`, `dt`, and admonition titles remain local to `content.css`. They belong to the content domain, not to shared site-wide text roles.\n", "0.9": "+++\ntitle = \"Typography Usage and Boundaries\"\n+++\n\nThis page covers the applied side of the website typography system.\n\nUse it when you need examples, implementation patterns, or boundary rules for deciding whether typography belongs in a shared utility or in component-local CSS.\n\n## Representative Definitions\n\nRepresentative implementations from `website/themes/sambee/assets/css/shared.css`:\n\n```css\n@utility type-copy {\n  font-family: var(--font-primary);\n  font-size: var(--text-copy);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-copy);\n}\n\n@utility type-label-sm {\n  font-family: var(--font-tertiary);\n  font-size: var(--text-label-sm);\n  font-weight: 400;\n  font-style: normal;\n  text-transform: uppercase;\n  letter-spacing: var(--tracking-label);\n}\n\n@utility type-docs-nav {\n  font-family: var(--font-primary);\n  font-size: var(--text-docs-nav);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-docs-nav);\n}\n\n@utility type-title-md {\n  font-family: var(--font-secondary);\n  font-size: var(--text-title-md);\n  font-weight: 700;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-title-md);\n}\n```\n\n## Template Usage Rules\n\nTemplates should apply one semantic typography utility per text role and then combine it with separate classes for color, layout, and interaction state.\n\nExamples from the live theme:\n\n```html\n\u003cspan class=\"type-label-eyebrow type-color-accent eyebrow-stack\"\u003eDocumentation\u003c/span\u003e\n\u003ch2 class=\"type-section-title type-color-ink\"\u003eFast local-first preview\u003c/h2\u003e\n\u003cspan class=\"docs-sidebar-link docs-sidebar-link-current type-docs-nav type-color-ink ui-current-primary-inset\"\u003eCurrent page\u003c/span\u003e\n\u003ca class=\"docs-sidebar-link type-docs-nav type-color-muted ui-transition-color type-hover-ink ui-hover-surface-mid\" href=\"/docs/\"\u003eDocumentation\u003c/a\u003e\n```\n\nCurrent usage rules:\n\n- apply exactly one semantic `type-*` utility to a text element\n- combine it with color helpers, layout helpers, and component-specific state classes as needed\n- do not stack two `type-*` utilities that both set size, weight, letter-spacing, line-height, or transform\n- do not reintroduce a partial base class such as `type-label`\n\nPatterns intentionally absent from the current theme include:\n\n```html\n\u003cspan class=\"type-label type-label-strong\"\u003e...\u003c/span\u003e\n\u003cspan class=\"type-label type-label-xs\"\u003e...\u003c/span\u003e\n\u003cli class=\"type-label type-list-item-label\"\u003e...\u003c/li\u003e\n```\n\n## Local Typography Boundaries\n\nNot every text treatment is shared.\n\n### Docs UI\n\n`website/themes/sambee/assets/css/docs.css` uses the shared `type-docs-nav` role for repeated documentation navigation text, including:\n\n- table of contents links\n- version switcher labels and options\n- nav tree links and current items\n- sequential navigation labels and titles\n\nLocal docs classes still own padding, indentation, and current-item state. For example, `.docs-sidebar-link-current` adds the stronger weight for the active item instead of relying on a separate semantic utility.\n\n### Navigation\n\n`website/themes/sambee/assets/css/navigation.css` keeps `.nav-link` as a component-local role. It consumes shared tracking values so the navigation remains aligned with the site-wide label scale.\n\n### Buttons\n\n`website/themes/sambee/assets/css/buttons.css` keeps `.btn` and `.btn-sm` as local button primitives. They consume shared typography tokens where it makes sense, but buttons are not modeled as shared text-role utilities.\n\n### Footer\n\nFooter layout classes remain local in `website/themes/sambee/assets/css/footer.css`. Shared typography utilities still supply the text role where that role is reused across templates.\n\n### Content-Specific Typography\n\nArticle-content semantics such as table headers, `figcaption`, `dt`, and admonition titles remain local to `content.css`. They belong to the content domain, not to shared site-wide text roles.\n", "1.0": "+++\ntitle = \"Typography Usage and Boundaries\"\n+++\n\nThis page covers the applied side of the website typography system.\n\nUse it when you need examples, implementation patterns, or boundary rules for deciding whether typography belongs in a shared utility or in component-local CSS.\n\n## Representative Definitions\n\nRepresentative implementations from `website/themes/sambee/assets/css/shared.css`:\n\n```css\n@utility type-copy {\n  font-family: var(--font-primary);\n  font-size: var(--text-copy);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-copy);\n}\n\n@utility type-label-sm {\n  font-family: var(--font-tertiary);\n  font-size: var(--text-label-sm);\n  font-weight: 400;\n  font-style: normal;\n  text-transform: uppercase;\n  letter-spacing: var(--tracking-label);\n}\n\n@utility type-docs-nav {\n  font-family: var(--font-primary);\n  font-size: var(--text-docs-nav);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-docs-nav);\n}\n\n@utility type-title-md {\n  font-family: var(--font-secondary);\n  font-size: var(--text-title-md);\n  font-weight: 700;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-title-md);\n}\n```\n\n## Template Usage Rules\n\nTemplates should apply one semantic typography utility per text role and then combine it with separate classes for color, layout, and interaction state.\n\nExamples from the live theme:\n\n```html\n\u003cspan class=\"type-label-eyebrow type-color-accent eyebrow-stack\"\u003eDocumentation\u003c/span\u003e\n\u003ch2 class=\"type-section-title type-color-ink\"\u003eFast local-first preview\u003c/h2\u003e\n\u003cspan class=\"docs-sidebar-link docs-sidebar-link-current type-docs-nav type-color-ink ui-current-primary-inset\"\u003eCurrent page\u003c/span\u003e\n\u003ca class=\"docs-sidebar-link type-docs-nav type-color-muted ui-transition-color type-hover-ink ui-hover-surface-mid\" href=\"/docs/\"\u003eDocumentation\u003c/a\u003e\n```\n\nCurrent usage rules:\n\n- apply exactly one semantic `type-*` utility to a text element\n- combine it with color helpers, layout helpers, and component-specific state classes as needed\n- do not stack two `type-*` utilities that both set size, weight, letter-spacing, line-height, or transform\n- do not reintroduce a partial base class such as `type-label`\n\nPatterns intentionally absent from the current theme include:\n\n```html\n\u003cspan class=\"type-label type-label-strong\"\u003e...\u003c/span\u003e\n\u003cspan class=\"type-label type-label-xs\"\u003e...\u003c/span\u003e\n\u003cli class=\"type-label type-list-item-label\"\u003e...\u003c/li\u003e\n```\n\n## Local Typography Boundaries\n\nNot every text treatment is shared.\n\n### Docs UI\n\n`website/themes/sambee/assets/css/docs.css` uses the shared `type-docs-nav` role for repeated documentation navigation text, including:\n\n- table of contents links\n- version switcher labels and options\n- nav tree links and current items\n- sequential navigation labels and titles\n\nLocal docs classes still own padding, indentation, and current-item state. For example, `.docs-sidebar-link-current` adds the stronger weight for the active item instead of relying on a separate semantic utility.\n\n### Navigation\n\n`website/themes/sambee/assets/css/navigation.css` keeps `.nav-link` as a component-local role. It consumes shared tracking values so the navigation remains aligned with the site-wide label scale.\n\n### Buttons\n\n`website/themes/sambee/assets/css/buttons.css` keeps `.btn` and `.btn-sm` as local button primitives. They consume shared typography tokens where it makes sense, but buttons are not modeled as shared text-role utilities.\n\n### Footer\n\nFooter layout classes remain local in `website/themes/sambee/assets/css/footer.css`. Shared typography utilities still supply the text role where that role is reused across templates.\n\n### Content-Specific Typography\n\nArticle-content semantics such as table headers, `figcaption`, `dt`, and admonition titles remain local to `content.css`. They belong to the content domain, not to shared site-wide text roles.\n", "2.0": "+++\ntitle = \"Typography Usage and Boundaries\"\n+++\n\nThis page covers the applied side of the website typography system.\n\nUse it when you need examples, implementation patterns, or boundary rules for deciding whether typography belongs in a shared utility or in component-local CSS.\n\n## Representative Definitions\n\nRepresentative implementations from `website/themes/sambee/assets/css/shared.css`:\n\n```css\n@utility type-copy {\n  font-family: var(--font-primary);\n  font-size: var(--text-copy);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-copy);\n}\n\n@utility type-label-sm {\n  font-family: var(--font-tertiary);\n  font-size: var(--text-label-sm);\n  font-weight: 400;\n  font-style: normal;\n  text-transform: uppercase;\n  letter-spacing: var(--tracking-label);\n}\n\n@utility type-docs-nav {\n  font-family: var(--font-primary);\n  font-size: var(--text-docs-nav);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-docs-nav);\n}\n\n@utility type-title-md {\n  font-family: var(--font-secondary);\n  font-size: var(--text-title-md);\n  font-weight: 700;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-title-md);\n}\n```\n\n## Template Usage Rules\n\nTemplates should apply one semantic typography utility per text role and then combine it with separate classes for color, layout, and interaction state.\n\nExamples from the live theme:\n\n```html\n\u003cspan class=\"type-label-eyebrow type-color-accent eyebrow-stack\"\u003eDocumentation\u003c/span\u003e\n\u003ch2 class=\"type-section-title type-color-ink\"\u003eFast local-first preview\u003c/h2\u003e\n\u003cspan class=\"docs-sidebar-link docs-sidebar-link-current type-docs-nav type-color-ink ui-current-primary-inset\"\u003eCurrent page\u003c/span\u003e\n\u003ca class=\"docs-sidebar-link type-docs-nav type-color-muted ui-transition-color type-hover-ink ui-hover-surface-mid\" href=\"/docs/\"\u003eDocumentation\u003c/a\u003e\n```\n\nCurrent usage rules:\n\n- apply exactly one semantic `type-*` utility to a text element\n- combine it with color helpers, layout helpers, and component-specific state classes as needed\n- do not stack two `type-*` utilities that both set size, weight, letter-spacing, line-height, or transform\n- do not reintroduce a partial base class such as `type-label`\n\nPatterns intentionally absent from the current theme include:\n\n```html\n\u003cspan class=\"type-label type-label-strong\"\u003e...\u003c/span\u003e\n\u003cspan class=\"type-label type-label-xs\"\u003e...\u003c/span\u003e\n\u003cli class=\"type-label type-list-item-label\"\u003e...\u003c/li\u003e\n```\n\n## Local Typography Boundaries\n\nNot every text treatment is shared.\n\n### Docs UI\n\n`website/themes/sambee/assets/css/docs.css` uses the shared `type-docs-nav` role for repeated documentation navigation text, including:\n\n- table of contents links\n- version switcher labels and options\n- nav tree links and current items\n- sequential navigation labels and titles\n\nLocal docs classes still own padding, indentation, and current-item state. For example, `.docs-sidebar-link-current` adds the stronger weight for the active item instead of relying on a separate semantic utility.\n\n### Navigation\n\n`website/themes/sambee/assets/css/navigation.css` keeps `.nav-link` as a component-local role. It consumes shared tracking values so the navigation remains aligned with the site-wide label scale.\n\n### Buttons\n\n`website/themes/sambee/assets/css/buttons.css` keeps `.btn` and `.btn-sm` as local button primitives. They consume shared typography tokens where it makes sense, but buttons are not modeled as shared text-role utilities.\n\n### Footer\n\nFooter layout classes remain local in `website/themes/sambee/assets/css/footer.css`. Shared typography utilities still supply the text role where that role is reused across templates.\n\n### Content-Specific Typography\n\nArticle-content semantics such as table headers, `figcaption`, `dt`, and admonition titles remain local to `content.css`. They belong to the content domain, not to shared site-wide text roles.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Typography Usage and Boundaries\"\n+++\n\nThis page covers the applied side of the website typography system.\n\nUse it when you need examples, implementation patterns, or boundary rules for deciding whether typography belongs in a shared utility or in component-local CSS.\n\n## Representative Definitions\n\nRepresentative implementations from `website/themes/sambee/assets/css/shared.css`:\n\n```css\n@utility type-copy {\n  font-family: var(--font-primary);\n  font-size: var(--text-copy);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-copy);\n}\n\n@utility type-label-sm {\n  font-family: var(--font-tertiary);\n  font-size: var(--text-label-sm);\n  font-weight: 400;\n  font-style: normal;\n  text-transform: uppercase;\n  letter-spacing: var(--tracking-label);\n}\n\n@utility type-docs-nav {\n  font-family: var(--font-primary);\n  font-size: var(--text-docs-nav);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-docs-nav);\n}\n\n@utility type-title-md {\n  font-family: var(--font-secondary);\n  font-size: var(--text-title-md);\n  font-weight: 700;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-title-md);\n}\n```\n\n## Template Usage Rules\n\nTemplates should apply one semantic typography utility per text role and then combine it with separate classes for color, layout, and interaction state.\n\nExamples from the live theme:\n\n```html\n\u003cspan class=\"type-label-eyebrow type-color-accent eyebrow-stack\"\u003eDocumentation\u003c/span\u003e\n\u003ch2 class=\"type-section-title type-color-ink\"\u003eFast local-first preview\u003c/h2\u003e\n\u003cspan class=\"docs-sidebar-link docs-sidebar-link-current type-docs-nav type-color-ink ui-current-primary-inset\"\u003eCurrent page\u003c/span\u003e\n\u003ca class=\"docs-sidebar-link type-docs-nav type-color-muted ui-transition-color type-hover-ink ui-hover-surface-mid\" href=\"/docs/\"\u003eDocumentation\u003c/a\u003e\n```\n\nCurrent usage rules:\n\n- apply exactly one semantic `type-*` utility to a text element\n- combine it with color helpers, layout helpers, and component-specific state classes as needed\n- do not stack two `type-*` utilities that both set size, weight, letter-spacing, line-height, or transform\n- do not reintroduce a partial base class such as `type-label`\n\nPatterns intentionally absent from the current theme include:\n\n```html\n\u003cspan class=\"type-label type-label-strong\"\u003e...\u003c/span\u003e\n\u003cspan class=\"type-label type-label-xs\"\u003e...\u003c/span\u003e\n\u003cli class=\"type-label type-list-item-label\"\u003e...\u003c/li\u003e\n```\n\n## Local Typography Boundaries\n\nNot every text treatment is shared.\n\n### Docs UI\n\n`website/themes/sambee/assets/css/docs.css` uses the shared `type-docs-nav` role for repeated documentation navigation text, including:\n\n- table of contents links\n- version switcher labels and options\n- nav tree links and current items\n- sequential navigation labels and titles\n\nLocal docs classes still own padding, indentation, and current-item state. For example, `.docs-sidebar-link-current` adds the stronger weight for the active item instead of relying on a separate semantic utility.\n\n### Navigation\n\n`website/themes/sambee/assets/css/navigation.css` keeps `.nav-link` as a component-local role. It consumes shared tracking values so the navigation remains aligned with the site-wide label scale.\n\n### Buttons\n\n`website/themes/sambee/assets/css/buttons.css` keeps `.btn` and `.btn-sm` as local button primitives. They consume shared typography tokens where it makes sense, but buttons are not modeled as shared text-role utilities.\n\n### Footer\n\nFooter layout classes remain local in `website/themes/sambee/assets/css/footer.css`. Shared typography utilities still supply the text role where that role is reused across templates.\n\n### Content-Specific Typography\n\nArticle-content semantics such as table headers, `figcaption`, `dt`, and admonition titles remain local to `content.css`. They belong to the content domain, not to shared site-wide text roles.\n", "0.8": "+++\ntitle = \"Typography Usage and Boundaries\"\n+++\n\nThis page covers the applied side of the website typography system.\n\nUse it when you need examples, implementation patterns, or boundary rules for deciding whether typography belongs in a shared utility or in component-local CSS.\n\n## Representative Definitions\n\nRepresentative implementations from `website/themes/sambee/assets/css/shared.css`:\n\n```css\n@utility type-copy {\n  font-family: var(--font-primary);\n  font-size: var(--text-copy);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-copy);\n}\n\n@utility type-label-sm {\n  font-family: var(--font-tertiary);\n  font-size: var(--text-label-sm);\n  font-weight: 400;\n  font-style: normal;\n  text-transform: uppercase;\n  letter-spacing: var(--tracking-label);\n}\n\n@utility type-docs-nav {\n  font-family: var(--font-primary);\n  font-size: var(--text-docs-nav);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-docs-nav);\n}\n\n@utility type-title-md {\n  font-family: var(--font-secondary);\n  font-size: var(--text-title-md);\n  font-weight: 700;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-title-md);\n}\n```\n\n## Template Usage Rules\n\nTemplates should apply one semantic typography utility per text role and then combine it with separate classes for color, layout, and interaction state.\n\nExamples from the live theme:\n\n```html\n\u003cspan class=\"type-label-eyebrow type-color-accent eyebrow-stack\"\u003eDocumentation\u003c/span\u003e\n\u003ch2 class=\"type-section-title type-color-ink\"\u003eFast local-first preview\u003c/h2\u003e\n\u003cspan class=\"docs-sidebar-link docs-sidebar-link-current type-docs-nav type-color-ink ui-current-primary-inset\"\u003eCurrent page\u003c/span\u003e\n\u003ca class=\"docs-sidebar-link type-docs-nav type-color-muted ui-transition-color type-hover-ink ui-hover-surface-mid\" href=\"/docs/\"\u003eDocumentation\u003c/a\u003e\n```\n\nCurrent usage rules:\n\n- apply exactly one semantic `type-*` utility to a text element\n- combine it with color helpers, layout helpers, and component-specific state classes as needed\n- do not stack two `type-*` utilities that both set size, weight, letter-spacing, line-height, or transform\n- do not reintroduce a partial base class such as `type-label`\n\nPatterns intentionally absent from the current theme include:\n\n```html\n\u003cspan class=\"type-label type-label-strong\"\u003e...\u003c/span\u003e\n\u003cspan class=\"type-label type-label-xs\"\u003e...\u003c/span\u003e\n\u003cli class=\"type-label type-list-item-label\"\u003e...\u003c/li\u003e\n```\n\n## Local Typography Boundaries\n\nNot every text treatment is shared.\n\n### Docs UI\n\n`website/themes/sambee/assets/css/docs.css` uses the shared `type-docs-nav` role for repeated documentation navigation text, including:\n\n- table of contents links\n- version switcher labels and options\n- nav tree links and current items\n- sequential navigation labels and titles\n\nLocal docs classes still own padding, indentation, and current-item state. For example, `.docs-sidebar-link-current` adds the stronger weight for the active item instead of relying on a separate semantic utility.\n\n### Navigation\n\n`website/themes/sambee/assets/css/navigation.css` keeps `.nav-link` as a component-local role. It consumes shared tracking values so the navigation remains aligned with the site-wide label scale.\n\n### Buttons\n\n`website/themes/sambee/assets/css/buttons.css` keeps `.btn` and `.btn-sm` as local button primitives. They consume shared typography tokens where it makes sense, but buttons are not modeled as shared text-role utilities.\n\n### Footer\n\nFooter layout classes remain local in `website/themes/sambee/assets/css/footer.css`. Shared typography utilities still supply the text role where that role is reused across templates.\n\n### Content-Specific Typography\n\nArticle-content semantics such as table headers, `figcaption`, `dt`, and admonition titles remain local to `content.css`. They belong to the content domain, not to shared site-wide text roles.\n", "0.9": "+++\ntitle = \"Typography Usage and Boundaries\"\n+++\n\nThis page covers the applied side of the website typography system.\n\nUse it when you need examples, implementation patterns, or boundary rules for deciding whether typography belongs in a shared utility or in component-local CSS.\n\n## Representative Definitions\n\nRepresentative implementations from `website/themes/sambee/assets/css/shared.css`:\n\n```css\n@utility type-copy {\n  font-family: var(--font-primary);\n  font-size: var(--text-copy);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-copy);\n}\n\n@utility type-label-sm {\n  font-family: var(--font-tertiary);\n  font-size: var(--text-label-sm);\n  font-weight: 400;\n  font-style: normal;\n  text-transform: uppercase;\n  letter-spacing: var(--tracking-label);\n}\n\n@utility type-docs-nav {\n  font-family: var(--font-primary);\n  font-size: var(--text-docs-nav);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-docs-nav);\n}\n\n@utility type-title-md {\n  font-family: var(--font-secondary);\n  font-size: var(--text-title-md);\n  font-weight: 700;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-title-md);\n}\n```\n\n## Template Usage Rules\n\nTemplates should apply one semantic typography utility per text role and then combine it with separate classes for color, layout, and interaction state.\n\nExamples from the live theme:\n\n```html\n\u003cspan class=\"type-label-eyebrow type-color-accent eyebrow-stack\"\u003eDocumentation\u003c/span\u003e\n\u003ch2 class=\"type-section-title type-color-ink\"\u003eFast local-first preview\u003c/h2\u003e\n\u003cspan class=\"docs-sidebar-link docs-sidebar-link-current type-docs-nav type-color-ink ui-current-primary-inset\"\u003eCurrent page\u003c/span\u003e\n\u003ca class=\"docs-sidebar-link type-docs-nav type-color-muted ui-transition-color type-hover-ink ui-hover-surface-mid\" href=\"/docs/\"\u003eDocumentation\u003c/a\u003e\n```\n\nCurrent usage rules:\n\n- apply exactly one semantic `type-*` utility to a text element\n- combine it with color helpers, layout helpers, and component-specific state classes as needed\n- do not stack two `type-*` utilities that both set size, weight, letter-spacing, line-height, or transform\n- do not reintroduce a partial base class such as `type-label`\n\nPatterns intentionally absent from the current theme include:\n\n```html\n\u003cspan class=\"type-label type-label-strong\"\u003e...\u003c/span\u003e\n\u003cspan class=\"type-label type-label-xs\"\u003e...\u003c/span\u003e\n\u003cli class=\"type-label type-list-item-label\"\u003e...\u003c/li\u003e\n```\n\n## Local Typography Boundaries\n\nNot every text treatment is shared.\n\n### Docs UI\n\n`website/themes/sambee/assets/css/docs.css` uses the shared `type-docs-nav` role for repeated documentation navigation text, including:\n\n- table of contents links\n- version switcher labels and options\n- nav tree links and current items\n- sequential navigation labels and titles\n\nLocal docs classes still own padding, indentation, and current-item state. For example, `.docs-sidebar-link-current` adds the stronger weight for the active item instead of relying on a separate semantic utility.\n\n### Navigation\n\n`website/themes/sambee/assets/css/navigation.css` keeps `.nav-link` as a component-local role. It consumes shared tracking values so the navigation remains aligned with the site-wide label scale.\n\n### Buttons\n\n`website/themes/sambee/assets/css/buttons.css` keeps `.btn` and `.btn-sm` as local button primitives. They consume shared typography tokens where it makes sense, but buttons are not modeled as shared text-role utilities.\n\n### Footer\n\nFooter layout classes remain local in `website/themes/sambee/assets/css/footer.css`. Shared typography utilities still supply the text role where that role is reused across templates.\n\n### Content-Specific Typography\n\nArticle-content semantics such as table headers, `figcaption`, `dt`, and admonition titles remain local to `content.css`. They belong to the content domain, not to shared site-wide text roles.\n", "1.0": "+++\ntitle = \"Typography Usage and Boundaries\"\n+++\n\nThis page covers the applied side of the website typography system.\n\nUse it when you need examples, implementation patterns, or boundary rules for deciding whether typography belongs in a shared utility or in component-local CSS.\n\n## Representative Definitions\n\nRepresentative implementations from `website/themes/sambee/assets/css/shared.css`:\n\n```css\n@utility type-copy {\n  font-family: var(--font-primary);\n  font-size: var(--text-copy);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-copy);\n}\n\n@utility type-label-sm {\n  font-family: var(--font-tertiary);\n  font-size: var(--text-label-sm);\n  font-weight: 400;\n  font-style: normal;\n  text-transform: uppercase;\n  letter-spacing: var(--tracking-label);\n}\n\n@utility type-docs-nav {\n  font-family: var(--font-primary);\n  font-size: var(--text-docs-nav);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-docs-nav);\n}\n\n@utility type-title-md {\n  font-family: var(--font-secondary);\n  font-size: var(--text-title-md);\n  font-weight: 700;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-title-md);\n}\n```\n\n## Template Usage Rules\n\nTemplates should apply one semantic typography utility per text role and then combine it with separate classes for color, layout, and interaction state.\n\nExamples from the live theme:\n\n```html\n\u003cspan class=\"type-label-eyebrow type-color-accent eyebrow-stack\"\u003eDocumentation\u003c/span\u003e\n\u003ch2 class=\"type-section-title type-color-ink\"\u003eFast local-first preview\u003c/h2\u003e\n\u003cspan class=\"docs-sidebar-link docs-sidebar-link-current type-docs-nav type-color-ink ui-current-primary-inset\"\u003eCurrent page\u003c/span\u003e\n\u003ca class=\"docs-sidebar-link type-docs-nav type-color-muted ui-transition-color type-hover-ink ui-hover-surface-mid\" href=\"/docs/\"\u003eDocumentation\u003c/a\u003e\n```\n\nCurrent usage rules:\n\n- apply exactly one semantic `type-*` utility to a text element\n- combine it with color helpers, layout helpers, and component-specific state classes as needed\n- do not stack two `type-*` utilities that both set size, weight, letter-spacing, line-height, or transform\n- do not reintroduce a partial base class such as `type-label`\n\nPatterns intentionally absent from the current theme include:\n\n```html\n\u003cspan class=\"type-label type-label-strong\"\u003e...\u003c/span\u003e\n\u003cspan class=\"type-label type-label-xs\"\u003e...\u003c/span\u003e\n\u003cli class=\"type-label type-list-item-label\"\u003e...\u003c/li\u003e\n```\n\n## Local Typography Boundaries\n\nNot every text treatment is shared.\n\n### Docs UI\n\n`website/themes/sambee/assets/css/docs.css` uses the shared `type-docs-nav` role for repeated documentation navigation text, including:\n\n- table of contents links\n- version switcher labels and options\n- nav tree links and current items\n- sequential navigation labels and titles\n\nLocal docs classes still own padding, indentation, and current-item state. For example, `.docs-sidebar-link-current` adds the stronger weight for the active item instead of relying on a separate semantic utility.\n\n### Navigation\n\n`website/themes/sambee/assets/css/navigation.css` keeps `.nav-link` as a component-local role. It consumes shared tracking values so the navigation remains aligned with the site-wide label scale.\n\n### Buttons\n\n`website/themes/sambee/assets/css/buttons.css` keeps `.btn` and `.btn-sm` as local button primitives. They consume shared typography tokens where it makes sense, but buttons are not modeled as shared text-role utilities.\n\n### Footer\n\nFooter layout classes remain local in `website/themes/sambee/assets/css/footer.css`. Shared typography utilities still supply the text role where that role is reused across templates.\n\n### Content-Specific Typography\n\nArticle-content semantics such as table headers, `figcaption`, `dt`, and admonition titles remain local to `content.css`. They belong to the content domain, not to shared site-wide text roles.\n", "2.0": "+++\ntitle = \"Typography Usage and Boundaries\"\n+++\n\nThis page covers the applied side of the website typography system.\n\nUse it when you need examples, implementation patterns, or boundary rules for deciding whether typography belongs in a shared utility or in component-local CSS.\n\n## Representative Definitions\n\nRepresentative implementations from `website/themes/sambee/assets/css/shared.css`:\n\n```css\n@utility type-copy {\n  font-family: var(--font-primary);\n  font-size: var(--text-copy);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-copy);\n}\n\n@utility type-label-sm {\n  font-family: var(--font-tertiary);\n  font-size: var(--text-label-sm);\n  font-weight: 400;\n  font-style: normal;\n  text-transform: uppercase;\n  letter-spacing: var(--tracking-label);\n}\n\n@utility type-docs-nav {\n  font-family: var(--font-primary);\n  font-size: var(--text-docs-nav);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-docs-nav);\n}\n\n@utility type-title-md {\n  font-family: var(--font-secondary);\n  font-size: var(--text-title-md);\n  font-weight: 700;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-title-md);\n}\n```\n\n## Template Usage Rules\n\nTemplates should apply one semantic typography utility per text role and then combine it with separate classes for color, layout, and interaction state.\n\nExamples from the live theme:\n\n```html\n\u003cspan class=\"type-label-eyebrow type-color-accent eyebrow-stack\"\u003eDocumentation\u003c/span\u003e\n\u003ch2 class=\"type-section-title type-color-ink\"\u003eFast local-first preview\u003c/h2\u003e\n\u003cspan class=\"docs-sidebar-link docs-sidebar-link-current type-docs-nav type-color-ink ui-current-primary-inset\"\u003eCurrent page\u003c/span\u003e\n\u003ca class=\"docs-sidebar-link type-docs-nav type-color-muted ui-transition-color type-hover-ink ui-hover-surface-mid\" href=\"/docs/\"\u003eDocumentation\u003c/a\u003e\n```\n\nCurrent usage rules:\n\n- apply exactly one semantic `type-*` utility to a text element\n- combine it with color helpers, layout helpers, and component-specific state classes as needed\n- do not stack two `type-*` utilities that both set size, weight, letter-spacing, line-height, or transform\n- do not reintroduce a partial base class such as `type-label`\n\nPatterns intentionally absent from the current theme include:\n\n```html\n\u003cspan class=\"type-label type-label-strong\"\u003e...\u003c/span\u003e\n\u003cspan class=\"type-label type-label-xs\"\u003e...\u003c/span\u003e\n\u003cli class=\"type-label type-list-item-label\"\u003e...\u003c/li\u003e\n```\n\n## Local Typography Boundaries\n\nNot every text treatment is shared.\n\n### Docs UI\n\n`website/themes/sambee/assets/css/docs.css` uses the shared `type-docs-nav` role for repeated documentation navigation text, including:\n\n- table of contents links\n- version switcher labels and options\n- nav tree links and current items\n- sequential navigation labels and titles\n\nLocal docs classes still own padding, indentation, and current-item state. For example, `.docs-sidebar-link-current` adds the stronger weight for the active item instead of relying on a separate semantic utility.\n\n### Navigation\n\n`website/themes/sambee/assets/css/navigation.css` keeps `.nav-link` as a component-local role. It consumes shared tracking values so the navigation remains aligned with the site-wide label scale.\n\n### Buttons\n\n`website/themes/sambee/assets/css/buttons.css` keeps `.btn` and `.btn-sm` as local button primitives. They consume shared typography tokens where it makes sense, but buttons are not modeled as shared text-role utilities.\n\n### Footer\n\nFooter layout classes remain local in `website/themes/sambee/assets/css/footer.css`. Shared typography utilities still supply the text role where that role is reused across templates.\n\n### Content-Specific Typography\n\nArticle-content semantics such as table headers, `figcaption`, `dt`, and admonition titles remain local to `content.css`. They belong to the content domain, not to shared site-wide text roles.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:website-dev-guide/site-systems/managed-redirects", "parent_id": "section:website-dev-guide/site-systems", "depth": 2, "kind": "page", "label": "managed-redirects", "title": "Managed Redirects", "path": "website-dev-guide/site-systems/managed-redirects", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "authored"}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "inherited", "source_version": "0.9"}}, "content_versions": {"0.9": "+++\ntitle = \"Managed Redirects\"\n+++\n\nManaged redirects provide stable `sambee.net` URLs for the product while allowing their destinations to change in a website deployment.\n\n## When To Use A Managed Redirect\n\nUse a managed redirect when product code, documentation, or external communication needs a durable public link whose destination may change. Product code should use a URL under `/mr/`, such as:\n\n```text\nhttps://sambee.net/mr/help-oidc-setup\n```\n\nDo not use a managed redirect for ordinary website navigation or a link whose destination is already a stable public contract.\n\n## Source Path Contract\n\nThe source path is immutable after release. Treat it as a public API:\n\n- Add a new path for each new long-lived product link.\n- Do not rename, remove, or reuse a released `/mr/` path.\n- Change the destination by updating its `target` value and deploying the website.\n\nManaged redirects use HTTP `302`, not `301`. This prevents browsers and intermediaries from permanently caching an old destination after the target changes.\n\n## Add A Redirect\n\nAdd an entry to `website/data/managed-redirects.toml`:\n\n```toml\n[[redirects]]\nid = \"help-oidc-setup\"\nsource = \"/mr/help-oidc-setup\"\ntarget = \"https://sambee.net/docs/admin-guide/authentication/openid-connect-authentication-setup/\"\n```\n\nEach entry requires:\n\n- A unique `id` for review and maintenance.\n- A unique literal `source` that starts with `/mr/` and has no trailing slash, query, fragment, or wildcard.\n- An absolute HTTPS `target` without credentials.\n\nThe source path is the immutable contract. Only `target` is expected to change after release.\n\n## Build Behavior\n\n`npm run redirects:generate` validates the registry and appends managed rules to the built `public/_redirects` artifact. The generator leaves `website/static/_redirects` unchanged because that file remains the source of legacy documentation redirects.\n\nThe normal website build and deployment workflow runs the generator automatically. To check the generated rules locally after a Hugo build, run:\n\n```bash\ncd website\nnpm run redirects:generate\n```\n\nThe generator fails the build when an entry is malformed, duplicates an ID or source path, or conflicts with an existing legacy redirect rule.\n\n", "1.0": "+++\ntitle = \"Managed Redirects\"\n+++\n\nManaged redirects provide stable `sambee.net` URLs for the product while allowing their destinations to change in a website deployment.\n\n## When To Use A Managed Redirect\n\nUse a managed redirect when product code, documentation, or external communication needs a durable public link whose destination may change. Product code should use a URL under `/mr/`, such as:\n\n```text\nhttps://sambee.net/mr/help-oidc-setup\n```\n\nDo not use a managed redirect for ordinary website navigation or a link whose destination is already a stable public contract.\n\n## Source Path Contract\n\nThe source path is immutable after release. Treat it as a public API:\n\n- Add a new path for each new long-lived product link.\n- Do not rename, remove, or reuse a released `/mr/` path.\n- Change the destination by updating its `target` value and deploying the website.\n\nManaged redirects use HTTP `302`, not `301`. This prevents browsers and intermediaries from permanently caching an old destination after the target changes.\n\n## Add A Redirect\n\nAdd an entry to `website/data/managed-redirects.toml`:\n\n```toml\n[[redirects]]\nid = \"help-oidc-setup\"\nsource = \"/mr/help-oidc-setup\"\ntarget = \"https://sambee.net/docs/admin-guide/authentication/openid-connect-authentication-setup/\"\n```\n\nEach entry requires:\n\n- A unique `id` for review and maintenance.\n- A unique literal `source` that starts with `/mr/` and has no trailing slash, query, fragment, or wildcard.\n- An absolute HTTPS `target` without credentials.\n\nThe source path is the immutable contract. Only `target` is expected to change after release.\n\n## Build Behavior\n\n`npm run redirects:generate` validates the registry and appends managed rules to the built `public/_redirects` artifact. The generator leaves `website/static/_redirects` unchanged because that file remains the source of legacy documentation redirects.\n\nThe normal website build and deployment workflow runs the generator automatically. To check the generated rules locally after a Hugo build, run:\n\n```bash\ncd website\nnpm run redirects:generate\n```\n\nThe generator fails the build when an entry is malformed, duplicates an ID or source path, or conflicts with an existing legacy redirect rule.\n\n", "2.0": "+++\ntitle = \"Managed Redirects\"\n+++\n\nManaged redirects provide stable `sambee.net` URLs for the product while allowing their destinations to change in a website deployment.\n\n## When To Use A Managed Redirect\n\nUse a managed redirect when product code, documentation, or external communication needs a durable public link whose destination may change. Product code should use a URL under `/mr/`, such as:\n\n```text\nhttps://sambee.net/mr/help-oidc-setup\n```\n\nDo not use a managed redirect for ordinary website navigation or a link whose destination is already a stable public contract.\n\n## Source Path Contract\n\nThe source path is immutable after release. Treat it as a public API:\n\n- Add a new path for each new long-lived product link.\n- Do not rename, remove, or reuse a released `/mr/` path.\n- Change the destination by updating its `target` value and deploying the website.\n\nManaged redirects use HTTP `302`, not `301`. This prevents browsers and intermediaries from permanently caching an old destination after the target changes.\n\n## Add A Redirect\n\nAdd an entry to `website/data/managed-redirects.toml`:\n\n```toml\n[[redirects]]\nid = \"help-oidc-setup\"\nsource = \"/mr/help-oidc-setup\"\ntarget = \"https://sambee.net/docs/admin-guide/authentication/openid-connect-authentication-setup/\"\n```\n\nEach entry requires:\n\n- A unique `id` for review and maintenance.\n- A unique literal `source` that starts with `/mr/` and has no trailing slash, query, fragment, or wildcard.\n- An absolute HTTPS `target` without credentials.\n\nThe source path is the immutable contract. Only `target` is expected to change after release.\n\n## Build Behavior\n\n`npm run redirects:generate` validates the registry and appends managed rules to the built `public/_redirects` artifact. The generator leaves `website/static/_redirects` unchanged because that file remains the source of legacy documentation redirects.\n\nThe normal website build and deployment workflow runs the generator automatically. To check the generated rules locally after a Hugo build, run:\n\n```bash\ncd website\nnpm run redirects:generate\n```\n\nThe generator fails the build when an entry is malformed, duplicates an ID or source path, or conflicts with an existing legacy redirect rule.\n\n"}, "page_contents": {"0.9": "+++\ntitle = \"Managed Redirects\"\n+++\n\nManaged redirects provide stable `sambee.net` URLs for the product while allowing their destinations to change in a website deployment.\n\n## When To Use A Managed Redirect\n\nUse a managed redirect when product code, documentation, or external communication needs a durable public link whose destination may change. Product code should use a URL under `/mr/`, such as:\n\n```text\nhttps://sambee.net/mr/help-oidc-setup\n```\n\nDo not use a managed redirect for ordinary website navigation or a link whose destination is already a stable public contract.\n\n## Source Path Contract\n\nThe source path is immutable after release. Treat it as a public API:\n\n- Add a new path for each new long-lived product link.\n- Do not rename, remove, or reuse a released `/mr/` path.\n- Change the destination by updating its `target` value and deploying the website.\n\nManaged redirects use HTTP `302`, not `301`. This prevents browsers and intermediaries from permanently caching an old destination after the target changes.\n\n## Add A Redirect\n\nAdd an entry to `website/data/managed-redirects.toml`:\n\n```toml\n[[redirects]]\nid = \"help-oidc-setup\"\nsource = \"/mr/help-oidc-setup\"\ntarget = \"https://sambee.net/docs/admin-guide/authentication/openid-connect-authentication-setup/\"\n```\n\nEach entry requires:\n\n- A unique `id` for review and maintenance.\n- A unique literal `source` that starts with `/mr/` and has no trailing slash, query, fragment, or wildcard.\n- An absolute HTTPS `target` without credentials.\n\nThe source path is the immutable contract. Only `target` is expected to change after release.\n\n## Build Behavior\n\n`npm run redirects:generate` validates the registry and appends managed rules to the built `public/_redirects` artifact. The generator leaves `website/static/_redirects` unchanged because that file remains the source of legacy documentation redirects.\n\nThe normal website build and deployment workflow runs the generator automatically. To check the generated rules locally after a Hugo build, run:\n\n```bash\ncd website\nnpm run redirects:generate\n```\n\nThe generator fails the build when an entry is malformed, duplicates an ID or source path, or conflicts with an existing legacy redirect rule.\n\n", "1.0": "+++\ntitle = \"Managed Redirects\"\n+++\n\nManaged redirects provide stable `sambee.net` URLs for the product while allowing their destinations to change in a website deployment.\n\n## When To Use A Managed Redirect\n\nUse a managed redirect when product code, documentation, or external communication needs a durable public link whose destination may change. Product code should use a URL under `/mr/`, such as:\n\n```text\nhttps://sambee.net/mr/help-oidc-setup\n```\n\nDo not use a managed redirect for ordinary website navigation or a link whose destination is already a stable public contract.\n\n## Source Path Contract\n\nThe source path is immutable after release. Treat it as a public API:\n\n- Add a new path for each new long-lived product link.\n- Do not rename, remove, or reuse a released `/mr/` path.\n- Change the destination by updating its `target` value and deploying the website.\n\nManaged redirects use HTTP `302`, not `301`. This prevents browsers and intermediaries from permanently caching an old destination after the target changes.\n\n## Add A Redirect\n\nAdd an entry to `website/data/managed-redirects.toml`:\n\n```toml\n[[redirects]]\nid = \"help-oidc-setup\"\nsource = \"/mr/help-oidc-setup\"\ntarget = \"https://sambee.net/docs/admin-guide/authentication/openid-connect-authentication-setup/\"\n```\n\nEach entry requires:\n\n- A unique `id` for review and maintenance.\n- A unique literal `source` that starts with `/mr/` and has no trailing slash, query, fragment, or wildcard.\n- An absolute HTTPS `target` without credentials.\n\nThe source path is the immutable contract. Only `target` is expected to change after release.\n\n## Build Behavior\n\n`npm run redirects:generate` validates the registry and appends managed rules to the built `public/_redirects` artifact. The generator leaves `website/static/_redirects` unchanged because that file remains the source of legacy documentation redirects.\n\nThe normal website build and deployment workflow runs the generator automatically. To check the generated rules locally after a Hugo build, run:\n\n```bash\ncd website\nnpm run redirects:generate\n```\n\nThe generator fails the build when an entry is malformed, duplicates an ID or source path, or conflicts with an existing legacy redirect rule.\n\n", "2.0": "+++\ntitle = \"Managed Redirects\"\n+++\n\nManaged redirects provide stable `sambee.net` URLs for the product while allowing their destinations to change in a website deployment.\n\n## When To Use A Managed Redirect\n\nUse a managed redirect when product code, documentation, or external communication needs a durable public link whose destination may change. Product code should use a URL under `/mr/`, such as:\n\n```text\nhttps://sambee.net/mr/help-oidc-setup\n```\n\nDo not use a managed redirect for ordinary website navigation or a link whose destination is already a stable public contract.\n\n## Source Path Contract\n\nThe source path is immutable after release. Treat it as a public API:\n\n- Add a new path for each new long-lived product link.\n- Do not rename, remove, or reuse a released `/mr/` path.\n- Change the destination by updating its `target` value and deploying the website.\n\nManaged redirects use HTTP `302`, not `301`. This prevents browsers and intermediaries from permanently caching an old destination after the target changes.\n\n## Add A Redirect\n\nAdd an entry to `website/data/managed-redirects.toml`:\n\n```toml\n[[redirects]]\nid = \"help-oidc-setup\"\nsource = \"/mr/help-oidc-setup\"\ntarget = \"https://sambee.net/docs/admin-guide/authentication/openid-connect-authentication-setup/\"\n```\n\nEach entry requires:\n\n- A unique `id` for review and maintenance.\n- A unique literal `source` that starts with `/mr/` and has no trailing slash, query, fragment, or wildcard.\n- An absolute HTTPS `target` without credentials.\n\nThe source path is the immutable contract. Only `target` is expected to change after release.\n\n## Build Behavior\n\n`npm run redirects:generate` validates the registry and appends managed rules to the built `public/_redirects` artifact. The generator leaves `website/static/_redirects` unchanged because that file remains the source of legacy documentation redirects.\n\nThe normal website build and deployment workflow runs the generator automatically. To check the generated rules locally after a Hugo build, run:\n\n```bash\ncd website\nnpm run redirects:generate\n```\n\nThe generator fails the build when an entry is malformed, duplicates an ID or source path, or conflicts with an existing legacy redirect rule.\n\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:website-dev-guide/setup-and-operations", "parent_id": "book:website-dev-guide", "depth": 1, "kind": "section", "label": "setup-and-operations", "title": "Setup and Operations", "path": "website-dev-guide/setup-and-operations", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:website-dev-guide/setup-and-operations/set-up-cloudflare-pages-publishing", "parent_id": "section:website-dev-guide/setup-and-operations", "depth": 2, "kind": "page", "label": "set-up-cloudflare-pages-publishing", "title": "Set Up Cloudflare Pages Publishing", "path": "website-dev-guide/setup-and-operations/set-up-cloudflare-pages-publishing", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Set Up Cloudflare Pages Publishing\"\n+++\n\nUse this page to set up and maintain the website deployment workflow that publishes built website assets to Cloudflare Pages.\n\n## Overview\n\nThe repository uses a split deployment model:\n\n- Hugo builds the site into `website/public/`.\n- Built assets are published from there to Cloudflare Pages.\n- Source images and generated WebP derivatives remain in Git LFS.\n\nThe workflow builds on pull requests and pushes to `main`. The deploy job runs only on `main`.\n\n## Prepare Cloudflare\n\nComplete these Cloudflare steps first, then add the collected values to GitHub in the next section.\n\n1. Create a Cloudflare Pages project to receive the built HTML from `website/public/`:\n   - Go to **Workers \u0026 Pages** \u003e **Create application**\n   - Select **Looking to deploy Pages? Get started** \u003e **Drag and drop your files - Get started**\n   - Project name: `sambee-net` (to be stored in `CLOUDFLARE_PAGES_PROJECT`)\n   - Select **Create project**\n1. Go to the Pages project properties and set up a custom domain.\n1. In **My Profile** \u003e **API Tokens**, create a separate Cloudflare API token for the Pages deployment step:\n   - Name: `GitHub Actions - deploy Pages - sambee.net`\n   - Permissions: Account, Cloudflare Pages, edit\n1. Save that Pages API token for `CLOUDFLARE_API_TOKEN`\n1. Extract the Cloudflare account ID for the account that owns the Pages project from the URL: `https://dash.cloudflare.com/ACCOUNT_ID/home/overview`\n\n## Add GitHub Secrets\n\nAfter Cloudflare is ready, open the GitHub repository settings, go to **Secrets and variables** \u003e **Actions**, and add these repository secrets:\n\n- `CLOUDFLARE_API_TOKEN` for the Cloudflare API token used by the Pages deploy step.\n- `CLOUDFLARE_ACCOUNT_ID` for the Cloudflare account that owns the Pages project.\n- `CLOUDFLARE_PAGES_PROJECT` for the Cloudflare Pages project name passed to `wrangler pages deploy`.\n\n## CI Deploy\n\nThe deploy job publishes `website/public` to Cloudflare Pages from the `main` branch.\n\n## Repository Preconditions\n\nBefore deployment can publish correct media:\n\n- Source images live under `website/assets/images/`.\n- Generated WebP derivatives are committed in sibling `generated/` directories.\n- Downloadable files live under `website/static/files/`.\n- `npm run images:validate` passes.\n- The site build produces `website/public/images/` and `website/public/files/`.\n\nFor local verification:\n\n```bash\ncd website\ngit lfs pull\nnpm ci\nnpm run build\n```\n\n## Current Asset Behavior\n\nThe generated site still uses site-relative asset paths such as `/images/...` and `/files/...`.\n\nThat means this workflow deploys the website to Cloudflare Pages, but it does not rewrite asset URLs to a separate CDN hostname.\n", "0.8": "+++\ntitle = \"Set Up Cloudflare Pages Publishing\"\n+++\n\nUse this page to set up and maintain the website deployment workflow that publishes built website assets to Cloudflare Pages.\n\n## Overview\n\nThe repository uses a split deployment model:\n\n- Hugo builds the site into `website/public/`.\n- Built assets are published from there to Cloudflare Pages.\n- Source images and generated WebP derivatives remain in Git LFS.\n\nThe workflow builds on pull requests and pushes to `main`. The deploy job runs only on `main`.\n\n## Prepare Cloudflare\n\nComplete these Cloudflare steps first, then add the collected values to GitHub in the next section.\n\n1. Create a Cloudflare Pages project to receive the built HTML from `website/public/`:\n   - Go to **Workers \u0026 Pages** \u003e **Create application**\n   - Select **Looking to deploy Pages? Get started** \u003e **Drag and drop your files - Get started**\n   - Project name: `sambee-net` (to be stored in `CLOUDFLARE_PAGES_PROJECT`)\n   - Select **Create project**\n1. Go to the Pages project properties and set up a custom domain.\n1. In **My Profile** \u003e **API Tokens**, create a separate Cloudflare API token for the Pages deployment step:\n   - Name: `GitHub Actions - deploy Pages - sambee.net`\n   - Permissions: Account, Cloudflare Pages, edit\n1. Save that Pages API token for `CLOUDFLARE_API_TOKEN`\n1. Extract the Cloudflare account ID for the account that owns the Pages project from the URL: `https://dash.cloudflare.com/ACCOUNT_ID/home/overview`\n\n## Add GitHub Secrets\n\nAfter Cloudflare is ready, open the GitHub repository settings, go to **Secrets and variables** \u003e **Actions**, and add these repository secrets:\n\n- `CLOUDFLARE_API_TOKEN` for the Cloudflare API token used by the Pages deploy step.\n- `CLOUDFLARE_ACCOUNT_ID` for the Cloudflare account that owns the Pages project.\n- `CLOUDFLARE_PAGES_PROJECT` for the Cloudflare Pages project name passed to `wrangler pages deploy`.\n\n## CI Deploy\n\nThe deploy job publishes `website/public` to Cloudflare Pages from the `main` branch.\n\n## Repository Preconditions\n\nBefore deployment can publish correct media:\n\n- Source images live under `website/assets/images/`.\n- Generated WebP derivatives are committed in sibling `generated/` directories.\n- Downloadable files live under `website/static/files/`.\n- `npm run images:validate` passes.\n- The site build produces `website/public/images/` and `website/public/files/`.\n\nFor local verification:\n\n```bash\ncd website\ngit lfs pull\nnpm ci\nnpm run build\n```\n\n## Current Asset Behavior\n\nThe generated site still uses site-relative asset paths such as `/images/...` and `/files/...`.\n\nThat means this workflow deploys the website to Cloudflare Pages, but it does not rewrite asset URLs to a separate CDN hostname.\n", "0.9": "+++\ntitle = \"Set Up Cloudflare Pages Publishing\"\n+++\n\nUse this page to set up and maintain the website deployment workflow that publishes built website assets to Cloudflare Pages.\n\n## Overview\n\nThe repository uses a split deployment model:\n\n- Hugo builds the site into `website/public/`.\n- Built assets are published from there to Cloudflare Pages.\n- Source images and generated WebP derivatives remain in Git LFS.\n\nThe workflow builds on pull requests and pushes to `main`. The deploy job runs only on `main`.\n\n## Prepare Cloudflare\n\nComplete these Cloudflare steps first, then add the collected values to GitHub in the next section.\n\n1. Create a Cloudflare Pages project to receive the built HTML from `website/public/`:\n   - Go to **Workers \u0026 Pages** \u003e **Create application**\n   - Select **Looking to deploy Pages? Get started** \u003e **Drag and drop your files - Get started**\n   - Project name: `sambee-net` (to be stored in `CLOUDFLARE_PAGES_PROJECT`)\n   - Select **Create project**\n1. Go to the Pages project properties and set up a custom domain.\n1. In **My Profile** \u003e **API Tokens**, create a separate Cloudflare API token for the Pages deployment step:\n   - Name: `GitHub Actions - deploy Pages - sambee.net`\n   - Permissions: Account, Cloudflare Pages, edit\n1. Save that Pages API token for `CLOUDFLARE_API_TOKEN`\n1. Extract the Cloudflare account ID for the account that owns the Pages project from the URL: `https://dash.cloudflare.com/ACCOUNT_ID/home/overview`\n\n## Add GitHub Secrets\n\nAfter Cloudflare is ready, open the GitHub repository settings, go to **Secrets and variables** \u003e **Actions**, and add these repository secrets:\n\n- `CLOUDFLARE_API_TOKEN` for the Cloudflare API token used by the Pages deploy step.\n- `CLOUDFLARE_ACCOUNT_ID` for the Cloudflare account that owns the Pages project.\n- `CLOUDFLARE_PAGES_PROJECT` for the Cloudflare Pages project name passed to `wrangler pages deploy`.\n\n## CI Deploy\n\nThe deploy job publishes `website/public` to Cloudflare Pages from the `main` branch.\n\n## Repository Preconditions\n\nBefore deployment can publish correct media:\n\n- Source images live under `website/assets/images/`.\n- Generated WebP derivatives are committed in sibling `generated/` directories.\n- Downloadable files live under `website/static/files/`.\n- `npm run images:validate` passes.\n- The site build produces `website/public/images/` and `website/public/files/`.\n\nFor local verification:\n\n```bash\ncd website\ngit lfs pull\nnpm ci\nnpm run build\n```\n\n## Current Asset Behavior\n\nThe generated site still uses site-relative asset paths such as `/images/...` and `/files/...`.\n\nThat means this workflow deploys the website to Cloudflare Pages, but it does not rewrite asset URLs to a separate CDN hostname.\n", "1.0": "+++\ntitle = \"Set Up Cloudflare Pages Publishing\"\n+++\n\nUse this page to set up and maintain the website deployment workflow that publishes built website assets to Cloudflare Pages.\n\n## Overview\n\nThe repository uses a split deployment model:\n\n- Hugo builds the site into `website/public/`.\n- Built assets are published from there to Cloudflare Pages.\n- Source images and generated WebP derivatives remain in Git LFS.\n\nThe workflow builds on pull requests and pushes to `main`. The deploy job runs only on `main`.\n\n## Prepare Cloudflare\n\nComplete these Cloudflare steps first, then add the collected values to GitHub in the next section.\n\n1. Create a Cloudflare Pages project to receive the built HTML from `website/public/`:\n   - Go to **Workers \u0026 Pages** \u003e **Create application**\n   - Select **Looking to deploy Pages? Get started** \u003e **Drag and drop your files - Get started**\n   - Project name: `sambee-net` (to be stored in `CLOUDFLARE_PAGES_PROJECT`)\n   - Select **Create project**\n1. Go to the Pages project properties and set up a custom domain.\n1. In **My Profile** \u003e **API Tokens**, create a separate Cloudflare API token for the Pages deployment step:\n   - Name: `GitHub Actions - deploy Pages - sambee.net`\n   - Permissions: Account, Cloudflare Pages, edit\n1. Save that Pages API token for `CLOUDFLARE_API_TOKEN`\n1. Extract the Cloudflare account ID for the account that owns the Pages project from the URL: `https://dash.cloudflare.com/ACCOUNT_ID/home/overview`\n\n## Add GitHub Secrets\n\nAfter Cloudflare is ready, open the GitHub repository settings, go to **Secrets and variables** \u003e **Actions**, and add these repository secrets:\n\n- `CLOUDFLARE_API_TOKEN` for the Cloudflare API token used by the Pages deploy step.\n- `CLOUDFLARE_ACCOUNT_ID` for the Cloudflare account that owns the Pages project.\n- `CLOUDFLARE_PAGES_PROJECT` for the Cloudflare Pages project name passed to `wrangler pages deploy`.\n\n## CI Deploy\n\nThe deploy job publishes `website/public` to Cloudflare Pages from the `main` branch.\n\n## Repository Preconditions\n\nBefore deployment can publish correct media:\n\n- Source images live under `website/assets/images/`.\n- Generated WebP derivatives are committed in sibling `generated/` directories.\n- Downloadable files live under `website/static/files/`.\n- `npm run images:validate` passes.\n- The site build produces `website/public/images/` and `website/public/files/`.\n\nFor local verification:\n\n```bash\ncd website\ngit lfs pull\nnpm ci\nnpm run build\n```\n\n## Current Asset Behavior\n\nThe generated site still uses site-relative asset paths such as `/images/...` and `/files/...`.\n\nThat means this workflow deploys the website to Cloudflare Pages, but it does not rewrite asset URLs to a separate CDN hostname.\n", "2.0": "+++\ntitle = \"Set Up Cloudflare Pages Publishing\"\n+++\n\nUse this page to set up and maintain the website deployment workflow that publishes built website assets to Cloudflare Pages.\n\n## Overview\n\nThe repository uses a split deployment model:\n\n- Hugo builds the site into `website/public/`.\n- Built assets are published from there to Cloudflare Pages.\n- Source images and generated WebP derivatives remain in Git LFS.\n\nThe workflow builds on pull requests and pushes to `main`. The deploy job runs only on `main`.\n\n## Prepare Cloudflare\n\nComplete these Cloudflare steps first, then add the collected values to GitHub in the next section.\n\n1. Create a Cloudflare Pages project to receive the built HTML from `website/public/`:\n   - Go to **Workers \u0026 Pages** \u003e **Create application**\n   - Select **Looking to deploy Pages? Get started** \u003e **Drag and drop your files - Get started**\n   - Project name: `sambee-net` (to be stored in `CLOUDFLARE_PAGES_PROJECT`)\n   - Select **Create project**\n1. Go to the Pages project properties and set up a custom domain.\n1. In **My Profile** \u003e **API Tokens**, create a separate Cloudflare API token for the Pages deployment step:\n   - Name: `GitHub Actions - deploy Pages - sambee.net`\n   - Permissions: Account, Cloudflare Pages, edit\n1. Save that Pages API token for `CLOUDFLARE_API_TOKEN`\n1. Extract the Cloudflare account ID for the account that owns the Pages project from the URL: `https://dash.cloudflare.com/ACCOUNT_ID/home/overview`\n\n## Add GitHub Secrets\n\nAfter Cloudflare is ready, open the GitHub repository settings, go to **Secrets and variables** \u003e **Actions**, and add these repository secrets:\n\n- `CLOUDFLARE_API_TOKEN` for the Cloudflare API token used by the Pages deploy step.\n- `CLOUDFLARE_ACCOUNT_ID` for the Cloudflare account that owns the Pages project.\n- `CLOUDFLARE_PAGES_PROJECT` for the Cloudflare Pages project name passed to `wrangler pages deploy`.\n\n## CI Deploy\n\nThe deploy job publishes `website/public` to Cloudflare Pages from the `main` branch.\n\n## Repository Preconditions\n\nBefore deployment can publish correct media:\n\n- Source images live under `website/assets/images/`.\n- Generated WebP derivatives are committed in sibling `generated/` directories.\n- Downloadable files live under `website/static/files/`.\n- `npm run images:validate` passes.\n- The site build produces `website/public/images/` and `website/public/files/`.\n\nFor local verification:\n\n```bash\ncd website\ngit lfs pull\nnpm ci\nnpm run build\n```\n\n## Current Asset Behavior\n\nThe generated site still uses site-relative asset paths such as `/images/...` and `/files/...`.\n\nThat means this workflow deploys the website to Cloudflare Pages, but it does not rewrite asset URLs to a separate CDN hostname.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Set Up Cloudflare Pages Publishing\"\n+++\n\nUse this page to set up and maintain the website deployment workflow that publishes built website assets to Cloudflare Pages.\n\n## Overview\n\nThe repository uses a split deployment model:\n\n- Hugo builds the site into `website/public/`.\n- Built assets are published from there to Cloudflare Pages.\n- Source images and generated WebP derivatives remain in Git LFS.\n\nThe workflow builds on pull requests and pushes to `main`. The deploy job runs only on `main`.\n\n## Prepare Cloudflare\n\nComplete these Cloudflare steps first, then add the collected values to GitHub in the next section.\n\n1. Create a Cloudflare Pages project to receive the built HTML from `website/public/`:\n   - Go to **Workers \u0026 Pages** \u003e **Create application**\n   - Select **Looking to deploy Pages? Get started** \u003e **Drag and drop your files - Get started**\n   - Project name: `sambee-net` (to be stored in `CLOUDFLARE_PAGES_PROJECT`)\n   - Select **Create project**\n1. Go to the Pages project properties and set up a custom domain.\n1. In **My Profile** \u003e **API Tokens**, create a separate Cloudflare API token for the Pages deployment step:\n   - Name: `GitHub Actions - deploy Pages - sambee.net`\n   - Permissions: Account, Cloudflare Pages, edit\n1. Save that Pages API token for `CLOUDFLARE_API_TOKEN`\n1. Extract the Cloudflare account ID for the account that owns the Pages project from the URL: `https://dash.cloudflare.com/ACCOUNT_ID/home/overview`\n\n## Add GitHub Secrets\n\nAfter Cloudflare is ready, open the GitHub repository settings, go to **Secrets and variables** \u003e **Actions**, and add these repository secrets:\n\n- `CLOUDFLARE_API_TOKEN` for the Cloudflare API token used by the Pages deploy step.\n- `CLOUDFLARE_ACCOUNT_ID` for the Cloudflare account that owns the Pages project.\n- `CLOUDFLARE_PAGES_PROJECT` for the Cloudflare Pages project name passed to `wrangler pages deploy`.\n\n## CI Deploy\n\nThe deploy job publishes `website/public` to Cloudflare Pages from the `main` branch.\n\n## Repository Preconditions\n\nBefore deployment can publish correct media:\n\n- Source images live under `website/assets/images/`.\n- Generated WebP derivatives are committed in sibling `generated/` directories.\n- Downloadable files live under `website/static/files/`.\n- `npm run images:validate` passes.\n- The site build produces `website/public/images/` and `website/public/files/`.\n\nFor local verification:\n\n```bash\ncd website\ngit lfs pull\nnpm ci\nnpm run build\n```\n\n## Current Asset Behavior\n\nThe generated site still uses site-relative asset paths such as `/images/...` and `/files/...`.\n\nThat means this workflow deploys the website to Cloudflare Pages, but it does not rewrite asset URLs to a separate CDN hostname.\n", "0.8": "+++\ntitle = \"Set Up Cloudflare Pages Publishing\"\n+++\n\nUse this page to set up and maintain the website deployment workflow that publishes built website assets to Cloudflare Pages.\n\n## Overview\n\nThe repository uses a split deployment model:\n\n- Hugo builds the site into `website/public/`.\n- Built assets are published from there to Cloudflare Pages.\n- Source images and generated WebP derivatives remain in Git LFS.\n\nThe workflow builds on pull requests and pushes to `main`. The deploy job runs only on `main`.\n\n## Prepare Cloudflare\n\nComplete these Cloudflare steps first, then add the collected values to GitHub in the next section.\n\n1. Create a Cloudflare Pages project to receive the built HTML from `website/public/`:\n   - Go to **Workers \u0026 Pages** \u003e **Create application**\n   - Select **Looking to deploy Pages? Get started** \u003e **Drag and drop your files - Get started**\n   - Project name: `sambee-net` (to be stored in `CLOUDFLARE_PAGES_PROJECT`)\n   - Select **Create project**\n1. Go to the Pages project properties and set up a custom domain.\n1. In **My Profile** \u003e **API Tokens**, create a separate Cloudflare API token for the Pages deployment step:\n   - Name: `GitHub Actions - deploy Pages - sambee.net`\n   - Permissions: Account, Cloudflare Pages, edit\n1. Save that Pages API token for `CLOUDFLARE_API_TOKEN`\n1. Extract the Cloudflare account ID for the account that owns the Pages project from the URL: `https://dash.cloudflare.com/ACCOUNT_ID/home/overview`\n\n## Add GitHub Secrets\n\nAfter Cloudflare is ready, open the GitHub repository settings, go to **Secrets and variables** \u003e **Actions**, and add these repository secrets:\n\n- `CLOUDFLARE_API_TOKEN` for the Cloudflare API token used by the Pages deploy step.\n- `CLOUDFLARE_ACCOUNT_ID` for the Cloudflare account that owns the Pages project.\n- `CLOUDFLARE_PAGES_PROJECT` for the Cloudflare Pages project name passed to `wrangler pages deploy`.\n\n## CI Deploy\n\nThe deploy job publishes `website/public` to Cloudflare Pages from the `main` branch.\n\n## Repository Preconditions\n\nBefore deployment can publish correct media:\n\n- Source images live under `website/assets/images/`.\n- Generated WebP derivatives are committed in sibling `generated/` directories.\n- Downloadable files live under `website/static/files/`.\n- `npm run images:validate` passes.\n- The site build produces `website/public/images/` and `website/public/files/`.\n\nFor local verification:\n\n```bash\ncd website\ngit lfs pull\nnpm ci\nnpm run build\n```\n\n## Current Asset Behavior\n\nThe generated site still uses site-relative asset paths such as `/images/...` and `/files/...`.\n\nThat means this workflow deploys the website to Cloudflare Pages, but it does not rewrite asset URLs to a separate CDN hostname.\n", "0.9": "+++\ntitle = \"Set Up Cloudflare Pages Publishing\"\n+++\n\nUse this page to set up and maintain the website deployment workflow that publishes built website assets to Cloudflare Pages.\n\n## Overview\n\nThe repository uses a split deployment model:\n\n- Hugo builds the site into `website/public/`.\n- Built assets are published from there to Cloudflare Pages.\n- Source images and generated WebP derivatives remain in Git LFS.\n\nThe workflow builds on pull requests and pushes to `main`. The deploy job runs only on `main`.\n\n## Prepare Cloudflare\n\nComplete these Cloudflare steps first, then add the collected values to GitHub in the next section.\n\n1. Create a Cloudflare Pages project to receive the built HTML from `website/public/`:\n   - Go to **Workers \u0026 Pages** \u003e **Create application**\n   - Select **Looking to deploy Pages? Get started** \u003e **Drag and drop your files - Get started**\n   - Project name: `sambee-net` (to be stored in `CLOUDFLARE_PAGES_PROJECT`)\n   - Select **Create project**\n1. Go to the Pages project properties and set up a custom domain.\n1. In **My Profile** \u003e **API Tokens**, create a separate Cloudflare API token for the Pages deployment step:\n   - Name: `GitHub Actions - deploy Pages - sambee.net`\n   - Permissions: Account, Cloudflare Pages, edit\n1. Save that Pages API token for `CLOUDFLARE_API_TOKEN`\n1. Extract the Cloudflare account ID for the account that owns the Pages project from the URL: `https://dash.cloudflare.com/ACCOUNT_ID/home/overview`\n\n## Add GitHub Secrets\n\nAfter Cloudflare is ready, open the GitHub repository settings, go to **Secrets and variables** \u003e **Actions**, and add these repository secrets:\n\n- `CLOUDFLARE_API_TOKEN` for the Cloudflare API token used by the Pages deploy step.\n- `CLOUDFLARE_ACCOUNT_ID` for the Cloudflare account that owns the Pages project.\n- `CLOUDFLARE_PAGES_PROJECT` for the Cloudflare Pages project name passed to `wrangler pages deploy`.\n\n## CI Deploy\n\nThe deploy job publishes `website/public` to Cloudflare Pages from the `main` branch.\n\n## Repository Preconditions\n\nBefore deployment can publish correct media:\n\n- Source images live under `website/assets/images/`.\n- Generated WebP derivatives are committed in sibling `generated/` directories.\n- Downloadable files live under `website/static/files/`.\n- `npm run images:validate` passes.\n- The site build produces `website/public/images/` and `website/public/files/`.\n\nFor local verification:\n\n```bash\ncd website\ngit lfs pull\nnpm ci\nnpm run build\n```\n\n## Current Asset Behavior\n\nThe generated site still uses site-relative asset paths such as `/images/...` and `/files/...`.\n\nThat means this workflow deploys the website to Cloudflare Pages, but it does not rewrite asset URLs to a separate CDN hostname.\n", "1.0": "+++\ntitle = \"Set Up Cloudflare Pages Publishing\"\n+++\n\nUse this page to set up and maintain the website deployment workflow that publishes built website assets to Cloudflare Pages.\n\n## Overview\n\nThe repository uses a split deployment model:\n\n- Hugo builds the site into `website/public/`.\n- Built assets are published from there to Cloudflare Pages.\n- Source images and generated WebP derivatives remain in Git LFS.\n\nThe workflow builds on pull requests and pushes to `main`. The deploy job runs only on `main`.\n\n## Prepare Cloudflare\n\nComplete these Cloudflare steps first, then add the collected values to GitHub in the next section.\n\n1. Create a Cloudflare Pages project to receive the built HTML from `website/public/`:\n   - Go to **Workers \u0026 Pages** \u003e **Create application**\n   - Select **Looking to deploy Pages? Get started** \u003e **Drag and drop your files - Get started**\n   - Project name: `sambee-net` (to be stored in `CLOUDFLARE_PAGES_PROJECT`)\n   - Select **Create project**\n1. Go to the Pages project properties and set up a custom domain.\n1. In **My Profile** \u003e **API Tokens**, create a separate Cloudflare API token for the Pages deployment step:\n   - Name: `GitHub Actions - deploy Pages - sambee.net`\n   - Permissions: Account, Cloudflare Pages, edit\n1. Save that Pages API token for `CLOUDFLARE_API_TOKEN`\n1. Extract the Cloudflare account ID for the account that owns the Pages project from the URL: `https://dash.cloudflare.com/ACCOUNT_ID/home/overview`\n\n## Add GitHub Secrets\n\nAfter Cloudflare is ready, open the GitHub repository settings, go to **Secrets and variables** \u003e **Actions**, and add these repository secrets:\n\n- `CLOUDFLARE_API_TOKEN` for the Cloudflare API token used by the Pages deploy step.\n- `CLOUDFLARE_ACCOUNT_ID` for the Cloudflare account that owns the Pages project.\n- `CLOUDFLARE_PAGES_PROJECT` for the Cloudflare Pages project name passed to `wrangler pages deploy`.\n\n## CI Deploy\n\nThe deploy job publishes `website/public` to Cloudflare Pages from the `main` branch.\n\n## Repository Preconditions\n\nBefore deployment can publish correct media:\n\n- Source images live under `website/assets/images/`.\n- Generated WebP derivatives are committed in sibling `generated/` directories.\n- Downloadable files live under `website/static/files/`.\n- `npm run images:validate` passes.\n- The site build produces `website/public/images/` and `website/public/files/`.\n\nFor local verification:\n\n```bash\ncd website\ngit lfs pull\nnpm ci\nnpm run build\n```\n\n## Current Asset Behavior\n\nThe generated site still uses site-relative asset paths such as `/images/...` and `/files/...`.\n\nThat means this workflow deploys the website to Cloudflare Pages, but it does not rewrite asset URLs to a separate CDN hostname.\n", "2.0": "+++\ntitle = \"Set Up Cloudflare Pages Publishing\"\n+++\n\nUse this page to set up and maintain the website deployment workflow that publishes built website assets to Cloudflare Pages.\n\n## Overview\n\nThe repository uses a split deployment model:\n\n- Hugo builds the site into `website/public/`.\n- Built assets are published from there to Cloudflare Pages.\n- Source images and generated WebP derivatives remain in Git LFS.\n\nThe workflow builds on pull requests and pushes to `main`. The deploy job runs only on `main`.\n\n## Prepare Cloudflare\n\nComplete these Cloudflare steps first, then add the collected values to GitHub in the next section.\n\n1. Create a Cloudflare Pages project to receive the built HTML from `website/public/`:\n   - Go to **Workers \u0026 Pages** \u003e **Create application**\n   - Select **Looking to deploy Pages? Get started** \u003e **Drag and drop your files - Get started**\n   - Project name: `sambee-net` (to be stored in `CLOUDFLARE_PAGES_PROJECT`)\n   - Select **Create project**\n1. Go to the Pages project properties and set up a custom domain.\n1. In **My Profile** \u003e **API Tokens**, create a separate Cloudflare API token for the Pages deployment step:\n   - Name: `GitHub Actions - deploy Pages - sambee.net`\n   - Permissions: Account, Cloudflare Pages, edit\n1. Save that Pages API token for `CLOUDFLARE_API_TOKEN`\n1. Extract the Cloudflare account ID for the account that owns the Pages project from the URL: `https://dash.cloudflare.com/ACCOUNT_ID/home/overview`\n\n## Add GitHub Secrets\n\nAfter Cloudflare is ready, open the GitHub repository settings, go to **Secrets and variables** \u003e **Actions**, and add these repository secrets:\n\n- `CLOUDFLARE_API_TOKEN` for the Cloudflare API token used by the Pages deploy step.\n- `CLOUDFLARE_ACCOUNT_ID` for the Cloudflare account that owns the Pages project.\n- `CLOUDFLARE_PAGES_PROJECT` for the Cloudflare Pages project name passed to `wrangler pages deploy`.\n\n## CI Deploy\n\nThe deploy job publishes `website/public` to Cloudflare Pages from the `main` branch.\n\n## Repository Preconditions\n\nBefore deployment can publish correct media:\n\n- Source images live under `website/assets/images/`.\n- Generated WebP derivatives are committed in sibling `generated/` directories.\n- Downloadable files live under `website/static/files/`.\n- `npm run images:validate` passes.\n- The site build produces `website/public/images/` and `website/public/files/`.\n\nFor local verification:\n\n```bash\ncd website\ngit lfs pull\nnpm ci\nnpm run build\n```\n\n## Current Asset Behavior\n\nThe generated site still uses site-relative asset paths such as `/images/...` and `/files/...`.\n\nThat means this workflow deploys the website to Cloudflare Pages, but it does not rewrite asset URLs to a separate CDN hostname.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "book:release-info", "parent_id": null, "depth": 0, "kind": "book", "label": "release-info", "title": "Release Info", "path": "release-info", "has_children": true, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "section:release-info/news-and-changes", "parent_id": "book:release-info", "depth": 1, "kind": "section", "label": "news-and-changes", "title": "News and Changes", "path": "release-info/news-and-changes", "has_children": true, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:release-info/news-and-changes/whats-new", "parent_id": "section:release-info/news-and-changes", "depth": 2, "kind": "page", "label": "whats-new", "title": "Whats New", "path": "release-info/news-and-changes/whats-new", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "authored"}, "0.9": {"state": "branched", "source_version": "0.8", "diff_added": 47, "diff_removed": 46}, "1.0": {"state": "branched", "source_version": "0.9", "diff_added": 113, "diff_removed": 46}, "2.0": {"state": "branched", "source_version": "1.0", "diff_added": 126, "diff_removed": 120}}, "content_versions": {"0.8": "+++\ntitle = \"What's New\"\n+++\n\n## Quick Bar: UX\n\nThe [quick bar](../../../user-guide/browsing-and-navigation/smart-navigation-and-the-quick-bar/) is Sambee's main navigation element. It sits in the top bar above the file list and is designed to be the single point of control for directory navigation, file list filtering, and command lookup and execution.\n\nPreviously, those three functions were not clearly distinguished. The three modes are now separated more distinctly, and the current mode is shown directly in the quick bar through a dedicated button. This makes the feature easier to discover and also allows users to switch modes with the mouse or by touch (in addition to the existing keyboard shortcuts).\n\nIn addition, several bugs were fixed to improve the overall experience.\n\n## Companion: More Secure Pairing \u0026 Communication Flows\n\nThis release makes Sambee Companion connections more secure, from the first pairing step through ongoing communication during local-drive access and desktop editing.\n\n**Pairing** is now tracked per Sambee site instead of through one global paired state. Pending approvals can be cancelled cleanly, and the browser now shows clearer states when Companion is unavailable, waiting for local approval, needs repair, or has lost its editing session.\n\nSambee also now trusts only the specific Sambee site you approved, limits what the local Companion service exposes, and uses narrower one-task-at-a-time edit credentials behind the scenes.\n\n**Native editing** is also more resilient. Sambee now uses tighter, task-specific edit permissions, renews long-running edit sessions when needed, and returns you to the browser with a clearer next step if sign-in, lock ownership, or recovery fails, instead of leaving you stuck with a vague error.\n\n## File Opening: Speed \u0026 Flexibility\n\nWhen opening files for previewing or editing, you want quick previews, but you also want the ability to choose which app a file is opened in. Both paths are now efficiently available:\n\nOpen files in Sambee's browser-based viewers:\n\n- Click a file or press \u003ckbd\u003eEnter\u003c/kbd\u003e to open it in Sambee's associated viewer.\n- If no associated viewer exists, or if you press \u003ckbd\u003eShift + Enter\u003c/kbd\u003e, a viewer picker dialog appears.\n   - The picker lets you choose a Sambee browser viewer or a native app.\n\nOpen files in natively installed apps:\n\n- Press \u003ckbd\u003eCtrl + Enter\u003c/kbd\u003e to open a file in its associated native app, or right-click it and select **Open in Native App**.\n- If no associated native app has been chosen, or if you press \u003ckbd\u003eCtrl + Alt + Enter\u003c/kbd\u003e, an app picker dialog appears.\n\n## Markdown Editor: Strategy Change\n\nThe WYSIWYG Markdown editor is gone for a simple reason: UX. There is no open-source rich-text (WYSIWYG) Markdown editor that provides a great user experience. The previous editor was not up to the task.\n\nThe better option is CodeMirror, one of the best available editors, configured for Markdown. It provides a first-rate editing experience and battle-tested add-ons for many of the quality-of-life features people have come to expect from modern editors.\n\n### Interactive Markdown Table Editing\n\nEditing Markdown in a text editor works well for headings and lists, but tables are different. Markdown table syntax is unwieldy, especially when inserting a column in the middle, and the source is difficult to scan. Tables need an interactive WYSIWYG interface that looks and feels like a spreadsheet application. Sambee provides exactly that.\n\n## Text File Viewer and Editor\n\nSince we already have an excellent text editor (see the Markdown Editor note), we might as well put it to good use as a generic text file editor. Sambee can now open, display, and edit any kind of text-based file, with all the bells and whistles of a first-rate editor, for example syntax highlighting.\n\n## Miscellaneous\n\n### Home Screen\n\n- Added a help button next to the settings (gear) icon.\n\n### File List\n\n- Increased the font size on mobile.\n\n### PDF Viewer\n\n- Intra-document links now work correctly, e.g. from a table of contents.\n\n### Under the Hood\n\n- Major dependency upgrades across the board, including React 19 and MUI 9.\n- Improved suspend, resume, and reload resilience.\n\n## Internals\n\n### Documentation System\n\nSambee has a best-in-class documentation system that deduplicates content, inheriting unchanged text copy through versions. This enables us to provide complete and accurate docs for each product version while minimizing maintenance effort.\n\nThis release adds a docs reporting and visualization tool that creates an HTML report of every docs book, section, and page, including its properties, such as whether it is inherited or branched. The report also has a diff view that highlights changes between any two document versions.\n\nDocs editor tool improvements include:\n\n- UI improvements, including better help output.\n- New commands to convert pages between inherited and independent: `page materialize` and `page inherit`.\n- A test and validation suite that also runs in CI.\n", "0.9": "+++\ntitle = \"What's New\"\n+++\n\n## OpenID Connect (OIDC) Authentication and Single Sign-On (SSO)\n\nSingle sign-on was on my list of essential features from the very beginning. Having one source of truth for authentication and authorization is of great benefit even in the smallest networks with single-digit user counts.\n\nSambee includes a secure and comprehensive implementation of OpenID Connect for authentication through IAM servers such as Authelia or Keycloak. If OIDC is configured as the only authentication method, SSO happens behind the scenes and is fully transparent to users who are already logged in to the IAM server. Otherwise, users trying to access Sambee are redirected to the IAM server to authenticate. Once that has happened, they're redirected back to Sambee.\n\nSambee's [OIDC implementation](../../../admin-guide/authentication/openid-connect-authentication-setup/) comes with auto-provisioning, which creates Sambee user accounts automatically after successful OIDC authentication. This can (and often should) be gated by group membership so that only members of a specific group are allowed access to Sambee. Similarly, Sambee's user roles are assigned depending on group membership. This makes it possible to centrally manage access to Sambee's user roles (e.g., admin) in your IAM system.\n\n### Authentication Configuration Change\n\nAuthentication mode is selected only in **Settings** \u003e **Administration** \u003e **Authentication** and defaults to **Password only** for a new installation. The configuration file can only disable enforcement temporarily with `[auth] disable_enforcement = true`; the stored UI mode remains unchanged.\n\nThis is a breaking configuration change. `auth_method` is rejected in both `[auth]` and `[security]`, and existing installations are not migrated automatically. Remove the retired key before upgrading.\n\n## Settings \u0026 Dialogs Overhaul\n\nThe settings got a good UX overhaul that should make them consistent, accessible and, hopefully, much nicer to look at. They're fully responsive, of course, adapting flexibly to phone and desktop screen dimensions. They're also very optimized for efficient keyboard usage while offering touch-friendly sizing on mobile devices.\n\n### New Settings\n\nThe settings also gained several new category pages:\n\n- New personal **Account** settings page\n- New admin **About** settings page\n- New admin **Authentication** settings page\n- New admin **Network** settings page\n- New admin **SMB** settings page\n\nThe about page comes with a feature that may come in handy: creating a **support report** with redacted diagnostic information that's safe to post online.\n\n### User Management Page: Visibility Update\n\nThe user management page in settings was reimplemented to provide significantly better visibility through search, filtering, sorting, summary shortcuts, and a more compact presentation.\n\n### Dialog Look \u0026 Feel\n\nThe refreshed and improved look and feel from settings was applied to the various dialogs that are shown when you copy, move, create, or delete files and/or directories. These dialogs now convey more information in a better way than before.\n\n## Dark Theme Polishing\n\nThe dark theme got a good new coat of paint. The colors of all elements, including backgrounds, text, menus, and dialogs, were tweaked to ensure visual clarity and eye-soothing contrasts.\n\n## Markdown Editor Improvements\n\n- Lists are normalized (formatted) when saved, using `-` for unordered lists and `1.` for every ordered-list item.\n- The editor updates to display the normalized Markdown written to disk after a successful save.\n- Unsaved edits are stored in the browser's local storage so they're not lost when re-authenticating, for example.\n\n## SMB Hardening\n\nTaking a client session isolation bug as a cue, SMB connection handling has been thoroughly hardened. New settings let administrators require Kerberos authentication and SMB 3+ transport encryption. SMBv1 remains disabled and SMB signing is required for every connection.\n\n## Miscellaneous\n\n- **Deleting multiple files** works correctly.\n- The keyboard **shortcuts help** dialog is searchable and resizable.\n\n## Under the Hood\n\n- Security: updated all **dependencies** with known vulnerabilities to fixed versions\n- Docker container **logging**: severity reclassification\n\n## Internals\n\n### Release Workflow v2: Docker \u0026 Companion Version Lockstep\n\nSambee has a sophisticated build and release system (see the public [docs](../../../developer-guide/release-and-versioning/release-overview/)). Previously, releases and version numbers of the Docker image and the Companion app were deliberately independent. However, it turned out that it's more efficient and natural to increment the versions of both components in sync.\n\nThis led to a significant architectural change that started with a redefinition of the version number ([details](../../../developer-guide/release-and-versioning/product-versioning/)), followed by a second step in which the release processes were reworked to follow a straightforward pattern:\n\n 1. Increment the version number.\n 1. Create a build with that version (Docker image and/or Companion app).\n 1. Promote that build to the `test` channel and test.\n 1. Promote the build to the `beta` and/or `stable` channels.\n\n Crucially, in this new model a build is created only once. Releases happen through promoting existing builds. This guarantees that the version that was tested is exactly what is released later on.\n\n### Docker Dev/Prod Images: Shared Runtime Base Architecture\n\nThe development (devcontainer) and production Docker images are built off a common shared runtime base. This facilitates maintenance and ensures that the shipped image is identical to the environment the developer tested in.\n", "1.0": "+++\ntitle = \"What's New\"\n+++\n\n## Quick Bar\n\n### File Search\n\nWith the addition of file search (keyboard shortcut: \u003ckbd\u003e/\u003c/kbd\u003e), Sambee's quick bar is becoming a universal search and navigation tool.\n\nFile search complements the existing directory navigation (keyboard shortcut: \u003ckbd\u003eCtrl+K\u003c/kbd\u003e) by providing instant access to recently opened files across directories. File search supersedes file filtering mode, which was removed.\n\n### Directory Navigation History\n\nDirectory navigation now has a history. When you're looking for something, just open the quick bar in directory nav mode and it'll probably already be there. If not, typing a few characters of the name should bring it up in milliseconds.\n\n### Other Changes\n\n- Changed \u003ckbd\u003eF1\u003c/kbd\u003e to consistently invoke keyboard shortcuts help\n\n## Text and Markdown Editors\n\n### Search and Replace\n\nIn any editor, search and replace are essential functions that need to work efficiently while providing granular control. The text and the Markdown editors got just that: compact search and replace popouts with history, regex support and full keyboard usability.\n\n### Other Changes\n\n- Added keyboard shortcuts help\n- Added word wrap (toggled by keyboard shortcut \u003ckbd\u003eAlt+Z\u003c/kbd\u003e)\n- Added viewport scrolling (keyboard shortcut \u003ckbd\u003eCtrl+Arrow up/down\u003c/kbd\u003e)\n- Fixed text selection highlighting\n- Fixed `lock not found or expired` when saving\n\n### Markdown Editor\n\n- Added \u003ckbd\u003eCtrl+B\u003c/kbd\u003e and \u003ckbd\u003eCtrl+I\u003c/kbd\u003e keyboard shortcuts for bold and italic formatting\n\n## PDF Viewer\n\n### More Speed and Higher Fidelity: New Approach to Normalization\n\nEarlier versions normalized every PDF with Ghostscript. This introduced occasional issues and slowed down the viewer. Sambee now opens PDFs in their original form first. When a PDF cannot be displayed because its internal structure is incompatible with the viewer, Sambee can create a separate normalized version for viewing; the original file is never modified. Compatibility processing is limited by file size, processing time, memory, and temporary storage, and each normalized PDF is checked before use.\n\n### Other Changes\n\n- Mobile: swipe to move between pages\n- Encrypted PDFs: the user is now asked to enter a password\n- Large PDFs: better user feedback while loading\n- Color rendering: support for ICC profiles and CMYK\n- Image codecs: support for JPEG 2000 (JXL)\n- Bugfix: geometry changes between pages, e.g., from portrait to landscape, would create endless \"flicker loop\"\n- Bugfix: page rotation commands in the file were not honored\n\n## File List\n\n### ZIP Archive Creation, Inspection, and Extraction\n\nSambee lets you navigate seamlessly into ZIP archives the same way you'd navigate into subdirectories to explore their contents. The UX is instantaneous - only the relevant parts of the ZIP file are decoded. When extracting or compressing, the archive is streamed directly from source to target to minimize CPU, memory, and disk utilization. ZIP operations, like any other, are fully supported across backend boundaries, i.e., between SMB connections and local drives.\n\nThe addition of ZIP archive inspection was the right opportunity to implement storage and content provider abstraction layers. These new abstractions centralize knowledge of storage backends (e.g., SMB, Companion) and how to work with the data on the storage (e.g., regular files, archives), respectively. Introducing these abstractions significantly improves the product's architecture and will greatly simplify adding additional backends or container file types in the future.\n\n### Upload \u0026 Download\n\nA product like Sambee needs efficient ways to get files and folders in and out of the system. To upload files or folders to SMB or local drive destinations, either drag them to Sambee's file browser or select the **Upload** (\u003ckbd\u003eCtrl+U\u003c/kbd\u003e) command in the bottom toolbar. To download files or folders, choose files and/or folders and select the **Download** (\u003ckbd\u003eCtrl+D\u003c/kbd\u003e) command in the bottom toolbar.\n\nDownloading creates a temporary ZIP archive from the selected files and folders, which is then streamed to the browser and subsequently deleted. Sambee allows downloading from all locations: from SMB connections, from local drives, and even from inside ZIP archives.\n\n### Local Drives: Resolve .LNK Files\n\nShortcuts (`.lnk` files), symlinks, and junctions on local drives now show the target path in the status bar. The target information is pulled in asynchronously after the directory list has loaded - we don't want to give up on that snappy UI, after all. Paths are sensibly shortened to fit the available row width.\n\nWhen activated, file targets are opened whereas directory targets are navigated to.\n\n### File Copy and Move: Overwrite Options\n\nCopy and move operations can now overwrite an existing file or replace it only when the source is newer. The same choices work for batches and apply to all supported local and SMB transfers. Directories with the same name are merged safely, preserving destination-only content and resolving only conflicting files.\n\n### Command Toolbar (Desktop) \u0026 Per-Row Actions (Mobile)\n\nA new toolbar at the bottom of the file list makes available commands discoverable. On small screens, typical mobile controls are used instead: a \"+\" icon to create new files or directories and per-row action menus to access commands that operate on individual files or folders.\n\n### Item Selection on Small Screens (Mobile)\n\nOn phones and other small screen devices, files and folders can be selected either through a long press or via the item action menu. Once one item is selected, Sambee switches to multi-selection mode where additional items can be selected through a single tap. An action bar at the bottom of the screen provides access to commands.\n\n### File Metadata on Small Screens (Mobile)\n\nOn phones and other small screen devices, file size and modification time are now displayed in a two-line layout.\n\n### Other Changes\n\n- Added a toolbar button to switch between single-pane and dual-pane modes.\n- When keyboard shortcuts are ignored (because inapplicable in the current situation), Sambee now shows a toast message to make the user unobtrusively aware of the fact.\n- Keyboard navigation: removed delay after entering a new directory.\n- Typeahead buffer: cleared when \u003ckbd\u003eEsc\u003c/kbd\u003e is pressed.\n- The status bar is now always shown.\n\n## Settings\n\n### No More Save Button\n\nClicking a save button at the bottom of the page after adjusting some configuration settings is easily forgotten. So best get rid of that pesky save button altogether. Modern UIs like Sambee's are clever enough to apply config changes automatically and show the user that saving happened through subtle visual cues.\n\n### New Settings\n\nThe settings gained a new category page:\n\n- New admin settings page: **File Search**\n\nFile browser settings:\n\n- **Touch-friendly file selection:** controls how mobile-style file selection is enabled (auto, always on, off).\n\nSystem settings:\n\n- **Temporary archive download size limit:** sets the maximum size of the temporary ZIP archive created when multiple items are downloaded.\n\n### Other Changes\n\n- Localization: Timestamps weren't properly localized in some settings pages (account, user management).\n\n## Image Viewer\n\n- Large images: better user feedback while loading\n\n## Miscellaneous\n\n- Mobile UI: text size increase to improve readability\n- PWA on Chrome on Android: changed the system status bar color from the default blue to gold, matching Sambee's top bar\n- OIDC configuration fields now accept multiple group names as advertised\n- Bugfix: Concurrent OIDC token refreshes would cause SQLite database lock errors.\n- Unicode: file and directory names are normalized to Unicode NFC (single characters) when renamed or created/copied/moved.\n\n## Under the Hood\n\n- Frontend: improved recovery after network unavailability (e.g., after suspend/resume)\n- Security: updated all **dependencies** with known vulnerabilities to fixed versions\n\n## Internals\n\n### Release Workflow: Companion Alignment with Docker Image\n\nCompanion's release process has been simplified and aligned to match the Docker image workflow:\n\n1. When a new Companion build is created, its GitHub release is published automatically and promoted to the `test` channel.\n1. Interim Companion GitHub releases are deleted automatically when they're no longer needed.\n\n### Other Changes\n\n- Dependency security: The backend's lockfile update process was simplified so that Dependabot can now update lockfiles, too. This removes the need to check out Dependabot PRs locally just to run a lockfile update script.\n", "2.0": "+++\ntitle = \"What's New\"\n+++\n\n## \u26a0\ufe0f Action Required\n\nSambee's GitHub repository was moved to an organization account. This makes it necessary that you update the Docker Compose image URL to `ghcr.io/sambee-app/sambee` in your Docker Compose file (see the [Docker deployment docs](../../../admin-guide/installation-and-deployment/deploy-sambee-with-docker/) for details).\n\n## Theme Editor\n\nUI themes are an integral part of an app's visual presentation. As so often, flexibility is key. Some like it dark, others colorful, some require high-contrast, others prefer muted colors.\n\nSambee now has a multi-layer theme system. It differentiates between built-in themes, site-wide themes which only admins can manage, and users' personal themes. Any user can modify existing themes for their own use; admins can also provide themes for other users on the same Sambee server and designate a default theme for new users.\n\nWith Sambee's new theme editor, users can change all theme colors via hex values or the integrated RGBA color picker (which covers transparency in addition to color). Themes can be imported and exported, too.\n\n## File List\n\n### Mouse Selection on Desktop\n\nPrevious versions of Sambee introduced multi-selection for mobile users and keyboard aficionados on desktop. Mouse coverage was lacking. That has been rectified now: Selecting multiple files with a mouse is now straightforward. Click a file or folder icon to select it, then Shift-click another icon to add everything in between without losing your earlier selections. The pane's status bar keeps the count in view.\n\n### Other Changes\n\n- Native mobile sharing is now available for single or multiple files from the file list.\n- Single-file downloads are now streamed directly without buffering in memory. This speeds up downloads and effectively removes limits imposed by file size.\n- Item selection keyboard shortcuts now include \u003ckbd\u003eShift+Home\u003c/kbd\u003e and \u003ckbd\u003eShift+End\u003c/kbd\u003e.\n\n### Bugfixes\n\n#### File Copy/Move Fixes\n\n- Uploads and copy or move operations no longer interfere with each other's conflict decisions.\n- Moving files between SMB connections no longer leaves the original in place when it should have been deleted.\n- SMB moves now protect the source from concurrent edits and renames, preventing deletion of changes that weren't copied.\n- Overwriting an existing SMB file now replaces it atomically instead of failing.\n- Cancelling a move after copying finishes, but before source deletion starts, now correctly reports that both copies were kept.\n- Transfer results now show when a file was copied or replaced, even if removing or checking the original fails.\n- When transferring a folder, a problem with one file no longer hides files already copied, moved, or replaced from the summary.\n- Interrupted SMB moves now release files safely, without leaving them open or interrupting work still in progress.\n- Pressing Enter after a transfer finishes no longer starts the same transfer again.\n\n#### SMB Change Monitoring Fixes\n\nFile list:\n\n- File-list monitoring now watches only immediate children, so changes deeper in a folder don't trigger unnecessary refreshes.\n- When changes happen, the file list is now refreshed in the background.\n- File list refreshes are now coalesced and rate-limited.\n\nDirectory cache for instant navigation:\n\n- Quick directory navigation keeps its existing index when a background scan times out or fails.\n- Background scans keep the live directory index when a removal or rename overlaps a read, including when its notification arrives late. This prevents changes from being applied twice when a folder's name is reused.\n- Changing a connection's target or sign-in details no longer reuses directory suggestions from its old configuration.\n- Directory junctions remain searchable but are no longer followed recursively, preventing indexing loops. DFS referrals are still followed, keeping their subfolders searchable.\n- Startup verification and scheduled directory scans now stop cleanly when their cache is removed.\n\n#### Other Fixes\n\n- Invalid file browser URLs no longer break the page or prevent the other pane from loading.\n- Overlapping download requests were allowed.\n- A failed background connection refresh no longer hides a recovered file listing.\n- Renaming a file to a name that differed by case only failed on local drive connections.\n\n## OpenID Connect (OIDC)\n\n### Refresh Token \u0026 `offline_access` Are Now Optional\n\nMany identity providers require the `offline_access` scope to issue refresh tokens, but some (like OneLogin) rejects that scope in the authorization code flow and can issue a refresh token without it when refresh tokens are enabled for the app.\n\nSambee uses a provider refresh token when one is returned, whether or not `offline_access` was requested. If no refresh token is returned, Sambee can continue issuing short-lived API tokens from the browser session for up to 8 hours by default (configurable from 1 to 24 hours). After Sambee's user session expires, the user must sign in through the identity provider again.\n\n### Other Changes\n\n- When an OIDC login is necessary, all Sambee browser tabs switch to the login page. After a successful login in one tab, that tab now broadcasts a login complete hint. When other tabs on the login page receive that hint, they return to their respectice previous URLs.\n\n### Bugfixes\n\n- OIDC login failures after password reset: OIDC login now completes reliably after an administrator resets the account\u2019s password. Sambee ignores responses from the previous browser session while the new login finishes, reloads the user\u2019s themes and settings, and returns to the file browser instead of the login page.\n\n## Miscellaneous\n\n### Native Mobile Sharing\n\nConsolidated the native mobile sharing implementation across the file list and image, PDF, text, and Markdown viewers and editors. When sharing fails, a dialog with details can be invoked to facilitate issue reporting.\n\nText and Markdown viewers/editors now have an option to share the current content as text as an alternative to sharing the stored file. This helps circumvent Chrome restrictions that prevent sharing file types such as Markdown.\n\nImage and PDF viewers alway share the displayed content, which may have been normalized for viewing in the browser.\n\n### Full Browser History Navigation\n\nEvery navigation step is now encoded in the URL and recorded in browser history. This enables browser back/forward navigation across the entire Sambee workspace, including the file list, viewers, and editors.\n\n### Local Drive Acess\n\nSambee now checks local-drive access before saying the browser is ready to use Companion. If the check fails, Local Drives settings distinguish between an outdated Companion, an outdated Sambee page, and a pairing that needs to be restored.\n\nWhen Companion rejects a request while browsing a local drive, the file list points to the affected pane and offers a way to reload Sambee or open Local Drives, depending on what went wrong.\n\n### Unencrypted HTTP Support\n\nSambee now deals with unencrypted HTTP explicitly:\n\n- Companion pairing and operations are unavailable.\n- File copying caused a `crypto.randomUUID` error. This has been fixed by implementing a fallback.\n- File uploading would show `outcome uncertain` and not upload files on HTTP/1.1 connections (even over HTTPS). This has been fixed by sending files directly instead of using a streamed request body, so uploads work on HTTP/1.1 while still showing progress.\n- Copying to the clipboard (used in Settings) is now disabled.\n\nHTTP for development on `localhost` is treated as secure by browsers and continues to be supported by Sambee.\n\n### Supported Browser Detection\n\nIf your browser is too old or lacks features Sambee needs, you'll now see a clear message instead of a blank page. The message identifies missing capabilities and links to the browser requirements so you can choose a supported browser.\n\n### Text and Markdown Editors\n\n- Closing the editor by clicking the X now works in the same way as pressing \u003ckbd\u003eEsc\u003c/kbd\u003e: it returns to the viewer. From there, another click returns to the file list.\n- When reloading a browser tab with an editor, Sambee now recovers the file lock. This prevents the error `Unable to enter edit mode. File is locked for editing by \u003cusername\u003e`.\n\n### Password Login\n\n- When an admin configures a user to require a password change, that change is now enforced upon the next password login.\n- Local usernames are now evaluated case-insensitively.\n- The password field got an option to reveal the password.\n\n### Settings\n\n- User Management: Table column content could overflow into the next row. This was fixes with a comprehensive layout revision.\n\n## Under the Hood\n\n### Security Review\n\n- OIDC login now binds the callback and login grant to the browser that started the login flow, preventing a grant from being redeemed in another browser.\n- Only admins can list and download uploaded mobile logs; signed-in users can still upload logs for troubleshooting.\n- Companion requests now use signatures tied to the HTTP method and requested URL, so a signature can't be reused for another request.\n- Mobile log uploads have a size limit, and stored logs are pruned when they exceed the storage budget.\n- HTML, XHTML, and SVG files, including archive members, download instead of running as active content in the viewer.\n\n### Other Changes\n\n- The backend's Python environment was upgraded from 3.13 to 3.14.\n- Fixed the container startup warning: `AuthlibDeprecationWarning: The httpx module is deprecated; please use httpx2 instead.`\n\n### Dependency Security\n\n- Updated all **dependencies** with known issues or vulnerabilities to fixed versions.\n- Pinned all third-party GitHub Actions workflows to commit SHAs.\n- Frontend: removed `patch-package` to get rid of vulnerable transisitve dependency `braces`.\n\n## Internals\n\n- Companion build for Windows: Authenticode signing was removed from PR check builds and only remains on release workflows.\n- GitHub Actions: replaced `pull_request_target` as it will be removed on public repositories by default in November.\n- GitHub Actions: cache retention optimization.\n"}, "page_contents": {"0.8": "+++\ntitle = \"What's New\"\n+++\n\n## Quick Bar: UX\n\nThe [quick bar](../../../user-guide/browsing-and-navigation/smart-navigation-and-the-quick-bar/) is Sambee's main navigation element. It sits in the top bar above the file list and is designed to be the single point of control for directory navigation, file list filtering, and command lookup and execution.\n\nPreviously, those three functions were not clearly distinguished. The three modes are now separated more distinctly, and the current mode is shown directly in the quick bar through a dedicated button. This makes the feature easier to discover and also allows users to switch modes with the mouse or by touch (in addition to the existing keyboard shortcuts).\n\nIn addition, several bugs were fixed to improve the overall experience.\n\n## Companion: More Secure Pairing \u0026 Communication Flows\n\nThis release makes Sambee Companion connections more secure, from the first pairing step through ongoing communication during local-drive access and desktop editing.\n\n**Pairing** is now tracked per Sambee site instead of through one global paired state. Pending approvals can be cancelled cleanly, and the browser now shows clearer states when Companion is unavailable, waiting for local approval, needs repair, or has lost its editing session.\n\nSambee also now trusts only the specific Sambee site you approved, limits what the local Companion service exposes, and uses narrower one-task-at-a-time edit credentials behind the scenes.\n\n**Native editing** is also more resilient. Sambee now uses tighter, task-specific edit permissions, renews long-running edit sessions when needed, and returns you to the browser with a clearer next step if sign-in, lock ownership, or recovery fails, instead of leaving you stuck with a vague error.\n\n## File Opening: Speed \u0026 Flexibility\n\nWhen opening files for previewing or editing, you want quick previews, but you also want the ability to choose which app a file is opened in. Both paths are now efficiently available:\n\nOpen files in Sambee's browser-based viewers:\n\n- Click a file or press \u003ckbd\u003eEnter\u003c/kbd\u003e to open it in Sambee's associated viewer.\n- If no associated viewer exists, or if you press \u003ckbd\u003eShift + Enter\u003c/kbd\u003e, a viewer picker dialog appears.\n   - The picker lets you choose a Sambee browser viewer or a native app.\n\nOpen files in natively installed apps:\n\n- Press \u003ckbd\u003eCtrl + Enter\u003c/kbd\u003e to open a file in its associated native app, or right-click it and select **Open in Native App**.\n- If no associated native app has been chosen, or if you press \u003ckbd\u003eCtrl + Alt + Enter\u003c/kbd\u003e, an app picker dialog appears.\n\n## Markdown Editor: Strategy Change\n\nThe WYSIWYG Markdown editor is gone for a simple reason: UX. There is no open-source rich-text (WYSIWYG) Markdown editor that provides a great user experience. The previous editor was not up to the task.\n\nThe better option is CodeMirror, one of the best available editors, configured for Markdown. It provides a first-rate editing experience and battle-tested add-ons for many of the quality-of-life features people have come to expect from modern editors.\n\n### Interactive Markdown Table Editing\n\nEditing Markdown in a text editor works well for headings and lists, but tables are different. Markdown table syntax is unwieldy, especially when inserting a column in the middle, and the source is difficult to scan. Tables need an interactive WYSIWYG interface that looks and feels like a spreadsheet application. Sambee provides exactly that.\n\n## Text File Viewer and Editor\n\nSince we already have an excellent text editor (see the Markdown Editor note), we might as well put it to good use as a generic text file editor. Sambee can now open, display, and edit any kind of text-based file, with all the bells and whistles of a first-rate editor, for example syntax highlighting.\n\n## Miscellaneous\n\n### Home Screen\n\n- Added a help button next to the settings (gear) icon.\n\n### File List\n\n- Increased the font size on mobile.\n\n### PDF Viewer\n\n- Intra-document links now work correctly, e.g. from a table of contents.\n\n### Under the Hood\n\n- Major dependency upgrades across the board, including React 19 and MUI 9.\n- Improved suspend, resume, and reload resilience.\n\n## Internals\n\n### Documentation System\n\nSambee has a best-in-class documentation system that deduplicates content, inheriting unchanged text copy through versions. This enables us to provide complete and accurate docs for each product version while minimizing maintenance effort.\n\nThis release adds a docs reporting and visualization tool that creates an HTML report of every docs book, section, and page, including its properties, such as whether it is inherited or branched. The report also has a diff view that highlights changes between any two document versions.\n\nDocs editor tool improvements include:\n\n- UI improvements, including better help output.\n- New commands to convert pages between inherited and independent: `page materialize` and `page inherit`.\n- A test and validation suite that also runs in CI.\n", "0.9": "+++\ntitle = \"What's New\"\n+++\n\n## OpenID Connect (OIDC) Authentication and Single Sign-On (SSO)\n\nSingle sign-on was on my list of essential features from the very beginning. Having one source of truth for authentication and authorization is of great benefit even in the smallest networks with single-digit user counts.\n\nSambee includes a secure and comprehensive implementation of OpenID Connect for authentication through IAM servers such as Authelia or Keycloak. If OIDC is configured as the only authentication method, SSO happens behind the scenes and is fully transparent to users who are already logged in to the IAM server. Otherwise, users trying to access Sambee are redirected to the IAM server to authenticate. Once that has happened, they're redirected back to Sambee.\n\nSambee's [OIDC implementation](../../../admin-guide/authentication/openid-connect-authentication-setup/) comes with auto-provisioning, which creates Sambee user accounts automatically after successful OIDC authentication. This can (and often should) be gated by group membership so that only members of a specific group are allowed access to Sambee. Similarly, Sambee's user roles are assigned depending on group membership. This makes it possible to centrally manage access to Sambee's user roles (e.g., admin) in your IAM system.\n\n### Authentication Configuration Change\n\nAuthentication mode is selected only in **Settings** \u003e **Administration** \u003e **Authentication** and defaults to **Password only** for a new installation. The configuration file can only disable enforcement temporarily with `[auth] disable_enforcement = true`; the stored UI mode remains unchanged.\n\nThis is a breaking configuration change. `auth_method` is rejected in both `[auth]` and `[security]`, and existing installations are not migrated automatically. Remove the retired key before upgrading.\n\n## Settings \u0026 Dialogs Overhaul\n\nThe settings got a good UX overhaul that should make them consistent, accessible and, hopefully, much nicer to look at. They're fully responsive, of course, adapting flexibly to phone and desktop screen dimensions. They're also very optimized for efficient keyboard usage while offering touch-friendly sizing on mobile devices.\n\n### New Settings\n\nThe settings also gained several new category pages:\n\n- New personal **Account** settings page\n- New admin **About** settings page\n- New admin **Authentication** settings page\n- New admin **Network** settings page\n- New admin **SMB** settings page\n\nThe about page comes with a feature that may come in handy: creating a **support report** with redacted diagnostic information that's safe to post online.\n\n### User Management Page: Visibility Update\n\nThe user management page in settings was reimplemented to provide significantly better visibility through search, filtering, sorting, summary shortcuts, and a more compact presentation.\n\n### Dialog Look \u0026 Feel\n\nThe refreshed and improved look and feel from settings was applied to the various dialogs that are shown when you copy, move, create, or delete files and/or directories. These dialogs now convey more information in a better way than before.\n\n## Dark Theme Polishing\n\nThe dark theme got a good new coat of paint. The colors of all elements, including backgrounds, text, menus, and dialogs, were tweaked to ensure visual clarity and eye-soothing contrasts.\n\n## Markdown Editor Improvements\n\n- Lists are normalized (formatted) when saved, using `-` for unordered lists and `1.` for every ordered-list item.\n- The editor updates to display the normalized Markdown written to disk after a successful save.\n- Unsaved edits are stored in the browser's local storage so they're not lost when re-authenticating, for example.\n\n## SMB Hardening\n\nTaking a client session isolation bug as a cue, SMB connection handling has been thoroughly hardened. New settings let administrators require Kerberos authentication and SMB 3+ transport encryption. SMBv1 remains disabled and SMB signing is required for every connection.\n\n## Miscellaneous\n\n- **Deleting multiple files** works correctly.\n- The keyboard **shortcuts help** dialog is searchable and resizable.\n\n## Under the Hood\n\n- Security: updated all **dependencies** with known vulnerabilities to fixed versions\n- Docker container **logging**: severity reclassification\n\n## Internals\n\n### Release Workflow v2: Docker \u0026 Companion Version Lockstep\n\nSambee has a sophisticated build and release system (see the public [docs](../../../developer-guide/release-and-versioning/release-overview/)). Previously, releases and version numbers of the Docker image and the Companion app were deliberately independent. However, it turned out that it's more efficient and natural to increment the versions of both components in sync.\n\nThis led to a significant architectural change that started with a redefinition of the version number ([details](../../../developer-guide/release-and-versioning/product-versioning/)), followed by a second step in which the release processes were reworked to follow a straightforward pattern:\n\n 1. Increment the version number.\n 1. Create a build with that version (Docker image and/or Companion app).\n 1. Promote that build to the `test` channel and test.\n 1. Promote the build to the `beta` and/or `stable` channels.\n\n Crucially, in this new model a build is created only once. Releases happen through promoting existing builds. This guarantees that the version that was tested is exactly what is released later on.\n\n### Docker Dev/Prod Images: Shared Runtime Base Architecture\n\nThe development (devcontainer) and production Docker images are built off a common shared runtime base. This facilitates maintenance and ensures that the shipped image is identical to the environment the developer tested in.\n", "1.0": "+++\ntitle = \"What's New\"\n+++\n\n## Quick Bar\n\n### File Search\n\nWith the addition of file search (keyboard shortcut: \u003ckbd\u003e/\u003c/kbd\u003e), Sambee's quick bar is becoming a universal search and navigation tool.\n\nFile search complements the existing directory navigation (keyboard shortcut: \u003ckbd\u003eCtrl+K\u003c/kbd\u003e) by providing instant access to recently opened files across directories. File search supersedes file filtering mode, which was removed.\n\n### Directory Navigation History\n\nDirectory navigation now has a history. When you're looking for something, just open the quick bar in directory nav mode and it'll probably already be there. If not, typing a few characters of the name should bring it up in milliseconds.\n\n### Other Changes\n\n- Changed \u003ckbd\u003eF1\u003c/kbd\u003e to consistently invoke keyboard shortcuts help\n\n## Text and Markdown Editors\n\n### Search and Replace\n\nIn any editor, search and replace are essential functions that need to work efficiently while providing granular control. The text and the Markdown editors got just that: compact search and replace popouts with history, regex support and full keyboard usability.\n\n### Other Changes\n\n- Added keyboard shortcuts help\n- Added word wrap (toggled by keyboard shortcut \u003ckbd\u003eAlt+Z\u003c/kbd\u003e)\n- Added viewport scrolling (keyboard shortcut \u003ckbd\u003eCtrl+Arrow up/down\u003c/kbd\u003e)\n- Fixed text selection highlighting\n- Fixed `lock not found or expired` when saving\n\n### Markdown Editor\n\n- Added \u003ckbd\u003eCtrl+B\u003c/kbd\u003e and \u003ckbd\u003eCtrl+I\u003c/kbd\u003e keyboard shortcuts for bold and italic formatting\n\n## PDF Viewer\n\n### More Speed and Higher Fidelity: New Approach to Normalization\n\nEarlier versions normalized every PDF with Ghostscript. This introduced occasional issues and slowed down the viewer. Sambee now opens PDFs in their original form first. When a PDF cannot be displayed because its internal structure is incompatible with the viewer, Sambee can create a separate normalized version for viewing; the original file is never modified. Compatibility processing is limited by file size, processing time, memory, and temporary storage, and each normalized PDF is checked before use.\n\n### Other Changes\n\n- Mobile: swipe to move between pages\n- Encrypted PDFs: the user is now asked to enter a password\n- Large PDFs: better user feedback while loading\n- Color rendering: support for ICC profiles and CMYK\n- Image codecs: support for JPEG 2000 (JXL)\n- Bugfix: geometry changes between pages, e.g., from portrait to landscape, would create endless \"flicker loop\"\n- Bugfix: page rotation commands in the file were not honored\n\n## File List\n\n### ZIP Archive Creation, Inspection, and Extraction\n\nSambee lets you navigate seamlessly into ZIP archives the same way you'd navigate into subdirectories to explore their contents. The UX is instantaneous - only the relevant parts of the ZIP file are decoded. When extracting or compressing, the archive is streamed directly from source to target to minimize CPU, memory, and disk utilization. ZIP operations, like any other, are fully supported across backend boundaries, i.e., between SMB connections and local drives.\n\nThe addition of ZIP archive inspection was the right opportunity to implement storage and content provider abstraction layers. These new abstractions centralize knowledge of storage backends (e.g., SMB, Companion) and how to work with the data on the storage (e.g., regular files, archives), respectively. Introducing these abstractions significantly improves the product's architecture and will greatly simplify adding additional backends or container file types in the future.\n\n### Upload \u0026 Download\n\nA product like Sambee needs efficient ways to get files and folders in and out of the system. To upload files or folders to SMB or local drive destinations, either drag them to Sambee's file browser or select the **Upload** (\u003ckbd\u003eCtrl+U\u003c/kbd\u003e) command in the bottom toolbar. To download files or folders, choose files and/or folders and select the **Download** (\u003ckbd\u003eCtrl+D\u003c/kbd\u003e) command in the bottom toolbar.\n\nDownloading creates a temporary ZIP archive from the selected files and folders, which is then streamed to the browser and subsequently deleted. Sambee allows downloading from all locations: from SMB connections, from local drives, and even from inside ZIP archives.\n\n### Local Drives: Resolve .LNK Files\n\nShortcuts (`.lnk` files), symlinks, and junctions on local drives now show the target path in the status bar. The target information is pulled in asynchronously after the directory list has loaded - we don't want to give up on that snappy UI, after all. Paths are sensibly shortened to fit the available row width.\n\nWhen activated, file targets are opened whereas directory targets are navigated to.\n\n### File Copy and Move: Overwrite Options\n\nCopy and move operations can now overwrite an existing file or replace it only when the source is newer. The same choices work for batches and apply to all supported local and SMB transfers. Directories with the same name are merged safely, preserving destination-only content and resolving only conflicting files.\n\n### Command Toolbar (Desktop) \u0026 Per-Row Actions (Mobile)\n\nA new toolbar at the bottom of the file list makes available commands discoverable. On small screens, typical mobile controls are used instead: a \"+\" icon to create new files or directories and per-row action menus to access commands that operate on individual files or folders.\n\n### Item Selection on Small Screens (Mobile)\n\nOn phones and other small screen devices, files and folders can be selected either through a long press or via the item action menu. Once one item is selected, Sambee switches to multi-selection mode where additional items can be selected through a single tap. An action bar at the bottom of the screen provides access to commands.\n\n### File Metadata on Small Screens (Mobile)\n\nOn phones and other small screen devices, file size and modification time are now displayed in a two-line layout.\n\n### Other Changes\n\n- Added a toolbar button to switch between single-pane and dual-pane modes.\n- When keyboard shortcuts are ignored (because inapplicable in the current situation), Sambee now shows a toast message to make the user unobtrusively aware of the fact.\n- Keyboard navigation: removed delay after entering a new directory.\n- Typeahead buffer: cleared when \u003ckbd\u003eEsc\u003c/kbd\u003e is pressed.\n- The status bar is now always shown.\n\n## Settings\n\n### No More Save Button\n\nClicking a save button at the bottom of the page after adjusting some configuration settings is easily forgotten. So best get rid of that pesky save button altogether. Modern UIs like Sambee's are clever enough to apply config changes automatically and show the user that saving happened through subtle visual cues.\n\n### New Settings\n\nThe settings gained a new category page:\n\n- New admin settings page: **File Search**\n\nFile browser settings:\n\n- **Touch-friendly file selection:** controls how mobile-style file selection is enabled (auto, always on, off).\n\nSystem settings:\n\n- **Temporary archive download size limit:** sets the maximum size of the temporary ZIP archive created when multiple items are downloaded.\n\n### Other Changes\n\n- Localization: Timestamps weren't properly localized in some settings pages (account, user management).\n\n## Image Viewer\n\n- Large images: better user feedback while loading\n\n## Miscellaneous\n\n- Mobile UI: text size increase to improve readability\n- PWA on Chrome on Android: changed the system status bar color from the default blue to gold, matching Sambee's top bar\n- OIDC configuration fields now accept multiple group names as advertised\n- Bugfix: Concurrent OIDC token refreshes would cause SQLite database lock errors.\n- Unicode: file and directory names are normalized to Unicode NFC (single characters) when renamed or created/copied/moved.\n\n## Under the Hood\n\n- Frontend: improved recovery after network unavailability (e.g., after suspend/resume)\n- Security: updated all **dependencies** with known vulnerabilities to fixed versions\n\n## Internals\n\n### Release Workflow: Companion Alignment with Docker Image\n\nCompanion's release process has been simplified and aligned to match the Docker image workflow:\n\n1. When a new Companion build is created, its GitHub release is published automatically and promoted to the `test` channel.\n1. Interim Companion GitHub releases are deleted automatically when they're no longer needed.\n\n### Other Changes\n\n- Dependency security: The backend's lockfile update process was simplified so that Dependabot can now update lockfiles, too. This removes the need to check out Dependabot PRs locally just to run a lockfile update script.\n", "2.0": "+++\ntitle = \"What's New\"\n+++\n\n## \u26a0\ufe0f Action Required\n\nSambee's GitHub repository was moved to an organization account. This makes it necessary that you update the Docker Compose image URL to `ghcr.io/sambee-app/sambee` in your Docker Compose file (see the [Docker deployment docs](../../../admin-guide/installation-and-deployment/deploy-sambee-with-docker/) for details).\n\n## Theme Editor\n\nUI themes are an integral part of an app's visual presentation. As so often, flexibility is key. Some like it dark, others colorful, some require high-contrast, others prefer muted colors.\n\nSambee now has a multi-layer theme system. It differentiates between built-in themes, site-wide themes which only admins can manage, and users' personal themes. Any user can modify existing themes for their own use; admins can also provide themes for other users on the same Sambee server and designate a default theme for new users.\n\nWith Sambee's new theme editor, users can change all theme colors via hex values or the integrated RGBA color picker (which covers transparency in addition to color). Themes can be imported and exported, too.\n\n## File List\n\n### Mouse Selection on Desktop\n\nPrevious versions of Sambee introduced multi-selection for mobile users and keyboard aficionados on desktop. Mouse coverage was lacking. That has been rectified now: Selecting multiple files with a mouse is now straightforward. Click a file or folder icon to select it, then Shift-click another icon to add everything in between without losing your earlier selections. The pane's status bar keeps the count in view.\n\n### Other Changes\n\n- Native mobile sharing is now available for single or multiple files from the file list.\n- Single-file downloads are now streamed directly without buffering in memory. This speeds up downloads and effectively removes limits imposed by file size.\n- Item selection keyboard shortcuts now include \u003ckbd\u003eShift+Home\u003c/kbd\u003e and \u003ckbd\u003eShift+End\u003c/kbd\u003e.\n\n### Bugfixes\n\n#### File Copy/Move Fixes\n\n- Uploads and copy or move operations no longer interfere with each other's conflict decisions.\n- Moving files between SMB connections no longer leaves the original in place when it should have been deleted.\n- SMB moves now protect the source from concurrent edits and renames, preventing deletion of changes that weren't copied.\n- Overwriting an existing SMB file now replaces it atomically instead of failing.\n- Cancelling a move after copying finishes, but before source deletion starts, now correctly reports that both copies were kept.\n- Transfer results now show when a file was copied or replaced, even if removing or checking the original fails.\n- When transferring a folder, a problem with one file no longer hides files already copied, moved, or replaced from the summary.\n- Interrupted SMB moves now release files safely, without leaving them open or interrupting work still in progress.\n- Pressing Enter after a transfer finishes no longer starts the same transfer again.\n\n#### SMB Change Monitoring Fixes\n\nFile list:\n\n- File-list monitoring now watches only immediate children, so changes deeper in a folder don't trigger unnecessary refreshes.\n- When changes happen, the file list is now refreshed in the background.\n- File list refreshes are now coalesced and rate-limited.\n\nDirectory cache for instant navigation:\n\n- Quick directory navigation keeps its existing index when a background scan times out or fails.\n- Background scans keep the live directory index when a removal or rename overlaps a read, including when its notification arrives late. This prevents changes from being applied twice when a folder's name is reused.\n- Changing a connection's target or sign-in details no longer reuses directory suggestions from its old configuration.\n- Directory junctions remain searchable but are no longer followed recursively, preventing indexing loops. DFS referrals are still followed, keeping their subfolders searchable.\n- Startup verification and scheduled directory scans now stop cleanly when their cache is removed.\n\n#### Other Fixes\n\n- Invalid file browser URLs no longer break the page or prevent the other pane from loading.\n- Overlapping download requests were allowed.\n- A failed background connection refresh no longer hides a recovered file listing.\n- Renaming a file to a name that differed by case only failed on local drive connections.\n\n## OpenID Connect (OIDC)\n\n### Refresh Token \u0026 `offline_access` Are Now Optional\n\nMany identity providers require the `offline_access` scope to issue refresh tokens, but some (like OneLogin) rejects that scope in the authorization code flow and can issue a refresh token without it when refresh tokens are enabled for the app.\n\nSambee uses a provider refresh token when one is returned, whether or not `offline_access` was requested. If no refresh token is returned, Sambee can continue issuing short-lived API tokens from the browser session for up to 8 hours by default (configurable from 1 to 24 hours). After Sambee's user session expires, the user must sign in through the identity provider again.\n\n### Other Changes\n\n- When an OIDC login is necessary, all Sambee browser tabs switch to the login page. After a successful login in one tab, that tab now broadcasts a login complete hint. When other tabs on the login page receive that hint, they return to their respectice previous URLs.\n\n### Bugfixes\n\n- OIDC login failures after password reset: OIDC login now completes reliably after an administrator resets the account\u2019s password. Sambee ignores responses from the previous browser session while the new login finishes, reloads the user\u2019s themes and settings, and returns to the file browser instead of the login page.\n\n## Miscellaneous\n\n### Native Mobile Sharing\n\nConsolidated the native mobile sharing implementation across the file list and image, PDF, text, and Markdown viewers and editors. When sharing fails, a dialog with details can be invoked to facilitate issue reporting.\n\nText and Markdown viewers/editors now have an option to share the current content as text as an alternative to sharing the stored file. This helps circumvent Chrome restrictions that prevent sharing file types such as Markdown.\n\nImage and PDF viewers alway share the displayed content, which may have been normalized for viewing in the browser.\n\n### Full Browser History Navigation\n\nEvery navigation step is now encoded in the URL and recorded in browser history. This enables browser back/forward navigation across the entire Sambee workspace, including the file list, viewers, and editors.\n\n### Local Drive Acess\n\nSambee now checks local-drive access before saying the browser is ready to use Companion. If the check fails, Local Drives settings distinguish between an outdated Companion, an outdated Sambee page, and a pairing that needs to be restored.\n\nWhen Companion rejects a request while browsing a local drive, the file list points to the affected pane and offers a way to reload Sambee or open Local Drives, depending on what went wrong.\n\n### Unencrypted HTTP Support\n\nSambee now deals with unencrypted HTTP explicitly:\n\n- Companion pairing and operations are unavailable.\n- File copying caused a `crypto.randomUUID` error. This has been fixed by implementing a fallback.\n- File uploading would show `outcome uncertain` and not upload files on HTTP/1.1 connections (even over HTTPS). This has been fixed by sending files directly instead of using a streamed request body, so uploads work on HTTP/1.1 while still showing progress.\n- Copying to the clipboard (used in Settings) is now disabled.\n\nHTTP for development on `localhost` is treated as secure by browsers and continues to be supported by Sambee.\n\n### Supported Browser Detection\n\nIf your browser is too old or lacks features Sambee needs, you'll now see a clear message instead of a blank page. The message identifies missing capabilities and links to the browser requirements so you can choose a supported browser.\n\n### Text and Markdown Editors\n\n- Closing the editor by clicking the X now works in the same way as pressing \u003ckbd\u003eEsc\u003c/kbd\u003e: it returns to the viewer. From there, another click returns to the file list.\n- When reloading a browser tab with an editor, Sambee now recovers the file lock. This prevents the error `Unable to enter edit mode. File is locked for editing by \u003cusername\u003e`.\n\n### Password Login\n\n- When an admin configures a user to require a password change, that change is now enforced upon the next password login.\n- Local usernames are now evaluated case-insensitively.\n- The password field got an option to reveal the password.\n\n### Settings\n\n- User Management: Table column content could overflow into the next row. This was fixes with a comprehensive layout revision.\n\n## Under the Hood\n\n### Security Review\n\n- OIDC login now binds the callback and login grant to the browser that started the login flow, preventing a grant from being redeemed in another browser.\n- Only admins can list and download uploaded mobile logs; signed-in users can still upload logs for troubleshooting.\n- Companion requests now use signatures tied to the HTTP method and requested URL, so a signature can't be reused for another request.\n- Mobile log uploads have a size limit, and stored logs are pruned when they exceed the storage budget.\n- HTML, XHTML, and SVG files, including archive members, download instead of running as active content in the viewer.\n\n### Other Changes\n\n- The backend's Python environment was upgraded from 3.13 to 3.14.\n- Fixed the container startup warning: `AuthlibDeprecationWarning: The httpx module is deprecated; please use httpx2 instead.`\n\n### Dependency Security\n\n- Updated all **dependencies** with known issues or vulnerabilities to fixed versions.\n- Pinned all third-party GitHub Actions workflows to commit SHAs.\n- Frontend: removed `patch-package` to get rid of vulnerable transisitve dependency `braces`.\n\n## Internals\n\n- Companion build for Windows: Authenticode signing was removed from PR check builds and only remains on release workflows.\n- GitHub Actions: replaced `pull_request_target` as it will be removed on public repositories by default in November.\n- GitHub Actions: cache retention optimization.\n"}, "flags": {"has_branched": true, "has_inherited": false, "has_structural": false, "has_invalid": false}}, {"id": "section:release-info/system-requirements", "parent_id": "book:release-info", "depth": 1, "kind": "section", "label": "system-requirements", "title": "System Requirements", "path": "release-info/system-requirements", "has_children": true, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "missing"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:release-info/system-requirements/requirements", "parent_id": "section:release-info/system-requirements", "depth": 2, "kind": "page", "label": "requirements", "title": "Requirements", "path": "release-info/system-requirements/requirements", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "missing"}, "1.0": {"state": "authored"}, "2.0": {"state": "branched", "source_version": "1.0", "diff_added": 6, "diff_removed": 2}}, "content_versions": {"1.0": "+++\ntitle = \"System Requirements\"\n+++\n\n## Frontend\n\n### Web Browsers\n\nSambee's frontend supports the latest versions of desktop and mobile browsers, including:\n\n- Google Chrome (and derivatives)\n- Mozilla Firefox\n- Apple Safari\n\n### HTTPS\n\n**Accessing Sambee over HTTPS is very much recommended.** Typically, a reverse proxy such as Caddy is used for that purpose. See the [reverse proxy docs](https://sambee.net/docs/admin-guide/network-and-reverse-proxy/put-sambee-behind-a-reverse-proxy/) for more information, and [this blog post by Helge Klein](https://helgeklein.com/blog/automatic-https-certificates-for-services-on-internal-home-network-without-opening-firewall-port/) for a detailed configuration guide.\n\nCompanion pairing and operations are only available over HTTPS (or `http://localhost`, for local development).\n\n## Sambee Companion\n\nSambee Companion is available for Windows 11 on x64 and ARM64.\n", "2.0": "+++\ntitle = \"System Requirements\"\n+++\n\n## Frontend\n\n### Web Browsers\n\nSambee's frontend supports the latest versions of desktop and mobile browsers, including:\n\n- Google Chrome (and derivates)\n- Mozilla Firefox\n- Apple Safari\n\nIf a browser lacks a required modern capability, Sambee shows a browser compatibility message instead of loading the app. This checks a few key capabilities, not every feature Sambee uses.\n\nTo preview this message on the development server, open `http://localhost:3000/browse/smb/demo?simulateUnsupportedBrowser`. Remove the query parameter to load the app normally. This flag has no effect in production builds.\n\n### HTTPS\n\n**Accessing Sambee over HTTPS is very much recommended.** Typically, a reverse proxy such as Caddy is used for that purpose. See the [reverse proxy docs](https://sambee.net/docs/admin-guide/network-and-reverse-proxy/put-sambee-behind-a-reverse-proxy/) for more information, and [this blog post by Helge Klein](https://helgeklein.com/blog/automatic-https-certificates-for-services-on-internal-home-network-without-opening-firewall-port/) for a detailed configuration guide.\n\nCompanion pairing and operations are only available over HTTPS (or `http://localhost`, for local development).\n\n## Sambee Companion\n\nSambee Companion is currently available for Windows 11 on x64 and ARM64.\n"}, "page_contents": {"1.0": "+++\ntitle = \"System Requirements\"\n+++\n\n## Frontend\n\n### Web Browsers\n\nSambee's frontend supports the latest versions of desktop and mobile browsers, including:\n\n- Google Chrome (and derivatives)\n- Mozilla Firefox\n- Apple Safari\n\n### HTTPS\n\n**Accessing Sambee over HTTPS is very much recommended.** Typically, a reverse proxy such as Caddy is used for that purpose. See the [reverse proxy docs](https://sambee.net/docs/admin-guide/network-and-reverse-proxy/put-sambee-behind-a-reverse-proxy/) for more information, and [this blog post by Helge Klein](https://helgeklein.com/blog/automatic-https-certificates-for-services-on-internal-home-network-without-opening-firewall-port/) for a detailed configuration guide.\n\nCompanion pairing and operations are only available over HTTPS (or `http://localhost`, for local development).\n\n## Sambee Companion\n\nSambee Companion is available for Windows 11 on x64 and ARM64.\n", "2.0": "+++\ntitle = \"System Requirements\"\n+++\n\n## Frontend\n\n### Web Browsers\n\nSambee's frontend supports the latest versions of desktop and mobile browsers, including:\n\n- Google Chrome (and derivates)\n- Mozilla Firefox\n- Apple Safari\n\nIf a browser lacks a required modern capability, Sambee shows a browser compatibility message instead of loading the app. This checks a few key capabilities, not every feature Sambee uses.\n\nTo preview this message on the development server, open `http://localhost:3000/browse/smb/demo?simulateUnsupportedBrowser`. Remove the query parameter to load the app normally. This flag has no effect in production builds.\n\n### HTTPS\n\n**Accessing Sambee over HTTPS is very much recommended.** Typically, a reverse proxy such as Caddy is used for that purpose. See the [reverse proxy docs](https://sambee.net/docs/admin-guide/network-and-reverse-proxy/put-sambee-behind-a-reverse-proxy/) for more information, and [this blog post by Helge Klein](https://helgeklein.com/blog/automatic-https-certificates-for-services-on-internal-home-network-without-opening-firewall-port/) for a detailed configuration guide.\n\nCompanion pairing and operations are only available over HTTPS (or `http://localhost`, for local development).\n\n## Sambee Companion\n\nSambee Companion is currently available for Windows 11 on x64 and ARM64.\n"}, "flags": {"has_branched": true, "has_inherited": false, "has_structural": false, "has_invalid": false}}]}</script>
+  <script id="report-data" type="application/json">{"meta": {"title": "Docs Structure Report", "current_version": "1.0", "report_output": "website-meta/docs-reports/docs-structure-report.html"}, "versions": [{"slug": "0.7", "label": "0.7", "status": null, "visible": true, "searchable": false, "is_current": false}, {"slug": "0.8", "label": "0.8", "status": null, "visible": true, "searchable": false, "is_current": false}, {"slug": "0.9", "label": "0.9", "status": null, "visible": true, "searchable": false, "is_current": false}, {"slug": "1.0", "label": "1.0", "status": "current", "visible": true, "searchable": true, "is_current": true}, {"slug": "2.0", "label": "2.0", "status": "preview", "visible": true, "searchable": false, "is_current": false}], "warnings": [], "rows": [{"id": "book:user-guide", "parent_id": null, "depth": 0, "kind": "book", "label": "user-guide", "title": "User Guide", "path": "user-guide", "has_children": true, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"User Guide\"\n+++\n\nUse this guide to access files on network shares, explore files on your computer, view files in the browser, edit Markdown in the browser, or open files in desktop apps and upload your changes back.\n\n## Start Here If You Want To\n\n- Find out what Sambee is.\n- Understand what Sambee helps you do.\n- Learn how to use Sambee.\n\n## In This Guide\n\n- [Getting Started](./getting-started/what-is-sambee/): Understand what Sambee is.\n- [Accessing Files](./accessing-files/connect-to-an-smb-share/): Connect to SMB shares and access local drives from your computer.\n- [Browsing and Navigation](./browsing-and-navigation/dual-pane-mode/): Move through folders efficiently on desktop or mobile.\n- [Viewing \u0026 Editing Files](./viewing-and-editing-files/view-images-and-read-documents/): View images, read documents, edit Markdown in the browser, or continue in desktop apps.\n- [Companion App](./companion-app/install-and-pair-the-companion-app/): Install Companion and manage desktop-app behavior.\n- [Troubleshooting](./troubleshooting/common-user-problems/): Solve common user problems before escalating.\n- [Reference](./reference/supported-file-formats/): Check supported file formats.\n\n## Use the Right Guide\n\n- Use this User Guide for everyday tasks in Sambee.\n- Use the [Admin Guide](../admin-guide/) when the question is really about provisioning, deployment, service health, or environment policy.\n- Use the [Developer Guide](../developer-guide/) when the question becomes implementation-facing.\n\n", "0.8": "+++\ntitle = \"User Guide\"\n+++\n\nUse this guide to access files on network shares, explore files on your computer, view files in the browser, edit Markdown in the browser, or open files in desktop apps and upload your changes back.\n\n## Start Here If You Want To\n\n- Find out what Sambee is.\n- Understand what Sambee helps you do.\n- Learn how to use Sambee.\n\n## In This Guide\n\n- [Getting Started](./getting-started/what-is-sambee/): Understand what Sambee is.\n- [Accessing Files](./accessing-files/connect-to-an-smb-share/): Connect to SMB shares and access local drives from your computer.\n- [Browsing and Navigation](./browsing-and-navigation/dual-pane-mode/): Move through folders efficiently on desktop or mobile.\n- [Viewing \u0026 Editing Files](./viewing-and-editing-files/view-images-and-read-documents/): View images, read documents, edit Markdown in the browser, or continue in desktop apps.\n- [Companion App](./companion-app/install-and-pair-the-companion-app/): Install Companion and manage desktop-app behavior.\n- [Troubleshooting](./troubleshooting/common-user-problems/): Solve common user problems before escalating.\n- [Reference](./reference/supported-file-formats/): Check supported file formats.\n\n## Use the Right Guide\n\n- Use this User Guide for everyday tasks in Sambee.\n- Use the [Admin Guide](../admin-guide/) when the question is really about provisioning, deployment, service health, or environment policy.\n- Use the [Developer Guide](../developer-guide/) when the question becomes implementation-facing.\n\n", "0.9": "+++\ntitle = \"User Guide\"\n+++\n\nUse this guide to access files on network shares, explore files on your computer, view files in the browser, edit Markdown in the browser, or open files in desktop apps and upload your changes back.\n\n## Start Here If You Want To\n\n- Find out what Sambee is.\n- Understand what Sambee helps you do.\n- Learn how to use Sambee.\n\n## In This Guide\n\n- [Getting Started](./getting-started/what-is-sambee/): Understand what Sambee is.\n- [Accessing Files](./accessing-files/connect-to-an-smb-share/): Connect to SMB shares and access local drives from your computer.\n- [Browsing and Navigation](./browsing-and-navigation/dual-pane-mode/): Move through folders efficiently on desktop or mobile.\n- [Viewing \u0026 Editing Files](./viewing-and-editing-files/view-images-and-read-documents/): View images, read documents, edit Markdown in the browser, or continue in desktop apps.\n- [Companion App](./companion-app/install-and-pair-the-companion-app/): Install Companion and manage desktop-app behavior.\n- [Troubleshooting](./troubleshooting/common-user-problems/): Solve common user problems before escalating.\n- [Reference](./reference/supported-file-formats/): Check supported file formats.\n\n## Use the Right Guide\n\n- Use this User Guide for everyday tasks in Sambee.\n- Use the [Admin Guide](../admin-guide/) when the question is really about provisioning, deployment, service health, or environment policy.\n- Use the [Developer Guide](../developer-guide/) when the question becomes implementation-facing.\n\n", "1.0": "+++\ntitle = \"User Guide\"\n+++\n\nUse this guide to access files on network shares, explore files on your computer, view files in the browser, edit Markdown in the browser, or open files in desktop apps and upload your changes back.\n\n## Start Here If You Want To\n\n- Find out what Sambee is.\n- Understand what Sambee helps you do.\n- Learn how to use Sambee.\n\n## In This Guide\n\n- [Getting Started](./getting-started/what-is-sambee/): Understand what Sambee is.\n- [Accessing Files](./accessing-files/connect-to-an-smb-share/): Connect to SMB shares and access local drives from your computer.\n- [Browsing and Navigation](./browsing-and-navigation/dual-pane-mode/): Move through folders efficiently on desktop or mobile.\n- [Viewing \u0026 Editing Files](./viewing-and-editing-files/view-images-and-read-documents/): View images, read documents, edit Markdown in the browser, or continue in desktop apps.\n- [Companion App](./companion-app/install-and-pair-the-companion-app/): Install Companion and manage desktop-app behavior.\n- [Troubleshooting](./troubleshooting/common-user-problems/): Solve common user problems before escalating.\n- [Reference](./reference/supported-file-formats/): Check supported file formats.\n\n## Use the Right Guide\n\n- Use this User Guide for everyday tasks in Sambee.\n- Use the [Admin Guide](../admin-guide/) when the question is really about provisioning, deployment, service health, or environment policy.\n- Use the [Developer Guide](../developer-guide/) when the question becomes implementation-facing.\n\n", "2.0": "+++\ntitle = \"User Guide\"\n+++\n\nUse this guide to access files on network shares, explore files on your computer, view files in the browser, edit Markdown in the browser, or open files in desktop apps and upload your changes back.\n\n## Start Here If You Want To\n\n- Find out what Sambee is.\n- Understand what Sambee helps you do.\n- Learn how to use Sambee.\n\n## In This Guide\n\n- [Getting Started](./getting-started/what-is-sambee/): Understand what Sambee is.\n- [Accessing Files](./accessing-files/connect-to-an-smb-share/): Connect to SMB shares and access local drives from your computer.\n- [Browsing and Navigation](./browsing-and-navigation/dual-pane-mode/): Move through folders efficiently on desktop or mobile.\n- [Viewing \u0026 Editing Files](./viewing-and-editing-files/view-images-and-read-documents/): View images, read documents, edit Markdown in the browser, or continue in desktop apps.\n- [Companion App](./companion-app/install-and-pair-the-companion-app/): Install Companion and manage desktop-app behavior.\n- [Troubleshooting](./troubleshooting/common-user-problems/): Solve common user problems before escalating.\n- [Reference](./reference/supported-file-formats/): Check supported file formats.\n\n## Use the Right Guide\n\n- Use this User Guide for everyday tasks in Sambee.\n- Use the [Admin Guide](../admin-guide/) when the question is really about provisioning, deployment, service health, or environment policy.\n- Use the [Developer Guide](../developer-guide/) when the question becomes implementation-facing.\n\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:user-guide/getting-started", "parent_id": "book:user-guide", "depth": 1, "kind": "section", "label": "getting-started", "title": "Getting Started", "path": "user-guide/getting-started", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:user-guide/getting-started/what-is-sambee", "parent_id": "section:user-guide/getting-started", "depth": 2, "kind": "page", "label": "what-is-sambee", "title": "What Is Sambee", "path": "user-guide/getting-started/what-is-sambee", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "branched", "source_version": "0.7", "diff_added": 26, "diff_removed": 6}, "2.0": {"state": "inherited", "source_version": "1.0"}}, "content_versions": {"0.7": "+++\ntitle = \"What Is Sambee?\"\n+++\n\n## Browser-Based File Manager\n\nSambee is a browser-based viewer and manager for files on SMB network shares and on your computer's local drives. It supports single-pane and dual-pane views and can replace Total Commander-style tools in your browser and on your phone.\n\n### Supports SMB Shares and Local Drives\n\nSMB shares are accessed through Sambee's server component, which translates between HTTP(S), which your browser understands, and SMB, which a file server understands. Local drive access is provided by Sambee Companion, a helper app that can be installed on your computer and acts as a small service your browser can talk to.\n\nAll of this means that Sambee brings your files and folders into the browser and makes them accessible from your phone in much the same way as from your PC or Mac.\n\n## Image and PDF Viewer, Markdown Editor\n\nSambee is more than a file manager. It is built for speed and includes a fast image browser with broad file type support, a Markdown editor, and a PDF viewer. All of these work directly in the browser and do not require additional software, except Companion for local-drive access.\n\n## Desktop App Integration\n\nSambee also bridges the gap between the browser and the apps installed on your computer. It lets you open a file in its traditional desktop app directly from the browser. In other words, you can open Word, Excel, or Photoshop files in their respective native apps. When you are done editing, your changes are uploaded back to the original storage location, such as a file share. All of this happens through a smooth, browser-based workflow.\n", "0.8": "+++\ntitle = \"What Is Sambee?\"\n+++\n\n## Browser-Based File Manager\n\nSambee is a browser-based viewer and manager for files on SMB network shares and on your computer's local drives. It supports single-pane and dual-pane views and can replace Total Commander-style tools in your browser and on your phone.\n\n### Supports SMB Shares and Local Drives\n\nSMB shares are accessed through Sambee's server component, which translates between HTTP(S), which your browser understands, and SMB, which a file server understands. Local drive access is provided by Sambee Companion, a helper app that can be installed on your computer and acts as a small service your browser can talk to.\n\nAll of this means that Sambee brings your files and folders into the browser and makes them accessible from your phone in much the same way as from your PC or Mac.\n\n## Image and PDF Viewer, Markdown Editor\n\nSambee is more than a file manager. It is built for speed and includes a fast image browser with broad file type support, a Markdown editor, and a PDF viewer. All of these work directly in the browser and do not require additional software, except Companion for local-drive access.\n\n## Desktop App Integration\n\nSambee also bridges the gap between the browser and the apps installed on your computer. It lets you open a file in its traditional desktop app directly from the browser. In other words, you can open Word, Excel, or Photoshop files in their respective native apps. When you are done editing, your changes are uploaded back to the original storage location, such as a file share. All of this happens through a smooth, browser-based workflow.\n", "0.9": "+++\ntitle = \"What Is Sambee?\"\n+++\n\n## Browser-Based File Manager\n\nSambee is a browser-based viewer and manager for files on SMB network shares and on your computer's local drives. It supports single-pane and dual-pane views and can replace Total Commander-style tools in your browser and on your phone.\n\n### Supports SMB Shares and Local Drives\n\nSMB shares are accessed through Sambee's server component, which translates between HTTP(S), which your browser understands, and SMB, which a file server understands. Local drive access is provided by Sambee Companion, a helper app that can be installed on your computer and acts as a small service your browser can talk to.\n\nAll of this means that Sambee brings your files and folders into the browser and makes them accessible from your phone in much the same way as from your PC or Mac.\n\n## Image and PDF Viewer, Markdown Editor\n\nSambee is more than a file manager. It is built for speed and includes a fast image browser with broad file type support, a Markdown editor, and a PDF viewer. All of these work directly in the browser and do not require additional software, except Companion for local-drive access.\n\n## Desktop App Integration\n\nSambee also bridges the gap between the browser and the apps installed on your computer. It lets you open a file in its traditional desktop app directly from the browser. In other words, you can open Word, Excel, or Photoshop files in their respective native apps. When you are done editing, your changes are uploaded back to the original storage location, such as a file share. All of this happens through a smooth, browser-based workflow.\n", "1.0": "+++\ntitle = \"What Is Sambee?\"\n+++\n\n## Sambee Turns Your Storage Into a Modern Workspace\n\nSambee gives organizations and individuals a self-hosted, browser-based workspace for files on existing **SMB shares** and **local drives**. Users can browse, view, and edit files from PCs, phones, and tablets, or open and edit them in desktop apps with changes uploaded back to their original location.\n\n## Browser-Based File Manager\n\nSambee can replace traditional tools like Windows File Explorer.\n\n### Works on PCs, Phones, and Tablets\n\nSambee is optimized for large screens as well as for compact mobile devices.\n\n### Supports SMB Shares and Local Drives\n\nSMB shares are accessed through Sambee's server component, which translates between HTTP(S), which your browser understands, and SMB, which a file server understands.\n\nLocal drive access is provided by Sambee Companion, a helper app that can be installed on your computer and acts as a small service your browser can talk to.\n\n## View and Edit Files\n\n### Image \u0026 PDF Viewers\n\nSambee is much more than a file manager. It includes a fast image browser with broad file type support, and a robust PDF viewer that opens even problematic PDFs. All of these work directly in the browser and do not require additional software.\n\n### Markdown \u0026 Text Editors\n\nMarkdown files are rendered with rich formatting and can be modified efficiently with user-friendly WYSIWYG editing of Markdown tables.\n\nText files of any kind can be viewed and edited in the built-in text editor, complete with syntax highlighting and search \u0026 replace.\n\n### Desktop App Integration\n\nSambee also bridges the gap between the browser and the apps installed on your computer. It lets you open a file in its traditional desktop app directly from the browser. In other words, you can open Word, Excel, or Photoshop files in their respective native apps. When you are done editing, your changes are uploaded back to the original storage location, such as a file share. All of this happens through a smooth, browser-based workflow.\n\n## Free \u0026 Open Source\n\nSambee is free and open source software designed for self-hosting as a Docker container.\n", "2.0": "+++\ntitle = \"What Is Sambee?\"\n+++\n\n## Sambee Turns Your Storage Into a Modern Workspace\n\nSambee gives organizations and individuals a self-hosted, browser-based workspace for files on existing **SMB shares** and **local drives**. Users can browse, view, and edit files from PCs, phones, and tablets, or open and edit them in desktop apps with changes uploaded back to their original location.\n\n## Browser-Based File Manager\n\nSambee can replace traditional tools like Windows File Explorer.\n\n### Works on PCs, Phones, and Tablets\n\nSambee is optimized for large screens as well as for compact mobile devices.\n\n### Supports SMB Shares and Local Drives\n\nSMB shares are accessed through Sambee's server component, which translates between HTTP(S), which your browser understands, and SMB, which a file server understands.\n\nLocal drive access is provided by Sambee Companion, a helper app that can be installed on your computer and acts as a small service your browser can talk to.\n\n## View and Edit Files\n\n### Image \u0026 PDF Viewers\n\nSambee is much more than a file manager. It includes a fast image browser with broad file type support, and a robust PDF viewer that opens even problematic PDFs. All of these work directly in the browser and do not require additional software.\n\n### Markdown \u0026 Text Editors\n\nMarkdown files are rendered with rich formatting and can be modified efficiently with user-friendly WYSIWYG editing of Markdown tables.\n\nText files of any kind can be viewed and edited in the built-in text editor, complete with syntax highlighting and search \u0026 replace.\n\n### Desktop App Integration\n\nSambee also bridges the gap between the browser and the apps installed on your computer. It lets you open a file in its traditional desktop app directly from the browser. In other words, you can open Word, Excel, or Photoshop files in their respective native apps. When you are done editing, your changes are uploaded back to the original storage location, such as a file share. All of this happens through a smooth, browser-based workflow.\n\n## Free \u0026 Open Source\n\nSambee is free and open source software designed for self-hosting as a Docker container.\n"}, "page_contents": {"0.7": "+++\ntitle = \"What Is Sambee?\"\n+++\n\n## Browser-Based File Manager\n\nSambee is a browser-based viewer and manager for files on SMB network shares and on your computer's local drives. It supports single-pane and dual-pane views and can replace Total Commander-style tools in your browser and on your phone.\n\n### Supports SMB Shares and Local Drives\n\nSMB shares are accessed through Sambee's server component, which translates between HTTP(S), which your browser understands, and SMB, which a file server understands. Local drive access is provided by Sambee Companion, a helper app that can be installed on your computer and acts as a small service your browser can talk to.\n\nAll of this means that Sambee brings your files and folders into the browser and makes them accessible from your phone in much the same way as from your PC or Mac.\n\n## Image and PDF Viewer, Markdown Editor\n\nSambee is more than a file manager. It is built for speed and includes a fast image browser with broad file type support, a Markdown editor, and a PDF viewer. All of these work directly in the browser and do not require additional software, except Companion for local-drive access.\n\n## Desktop App Integration\n\nSambee also bridges the gap between the browser and the apps installed on your computer. It lets you open a file in its traditional desktop app directly from the browser. In other words, you can open Word, Excel, or Photoshop files in their respective native apps. When you are done editing, your changes are uploaded back to the original storage location, such as a file share. All of this happens through a smooth, browser-based workflow.\n", "0.8": "+++\ntitle = \"What Is Sambee?\"\n+++\n\n## Browser-Based File Manager\n\nSambee is a browser-based viewer and manager for files on SMB network shares and on your computer's local drives. It supports single-pane and dual-pane views and can replace Total Commander-style tools in your browser and on your phone.\n\n### Supports SMB Shares and Local Drives\n\nSMB shares are accessed through Sambee's server component, which translates between HTTP(S), which your browser understands, and SMB, which a file server understands. Local drive access is provided by Sambee Companion, a helper app that can be installed on your computer and acts as a small service your browser can talk to.\n\nAll of this means that Sambee brings your files and folders into the browser and makes them accessible from your phone in much the same way as from your PC or Mac.\n\n## Image and PDF Viewer, Markdown Editor\n\nSambee is more than a file manager. It is built for speed and includes a fast image browser with broad file type support, a Markdown editor, and a PDF viewer. All of these work directly in the browser and do not require additional software, except Companion for local-drive access.\n\n## Desktop App Integration\n\nSambee also bridges the gap between the browser and the apps installed on your computer. It lets you open a file in its traditional desktop app directly from the browser. In other words, you can open Word, Excel, or Photoshop files in their respective native apps. When you are done editing, your changes are uploaded back to the original storage location, such as a file share. All of this happens through a smooth, browser-based workflow.\n", "0.9": "+++\ntitle = \"What Is Sambee?\"\n+++\n\n## Browser-Based File Manager\n\nSambee is a browser-based viewer and manager for files on SMB network shares and on your computer's local drives. It supports single-pane and dual-pane views and can replace Total Commander-style tools in your browser and on your phone.\n\n### Supports SMB Shares and Local Drives\n\nSMB shares are accessed through Sambee's server component, which translates between HTTP(S), which your browser understands, and SMB, which a file server understands. Local drive access is provided by Sambee Companion, a helper app that can be installed on your computer and acts as a small service your browser can talk to.\n\nAll of this means that Sambee brings your files and folders into the browser and makes them accessible from your phone in much the same way as from your PC or Mac.\n\n## Image and PDF Viewer, Markdown Editor\n\nSambee is more than a file manager. It is built for speed and includes a fast image browser with broad file type support, a Markdown editor, and a PDF viewer. All of these work directly in the browser and do not require additional software, except Companion for local-drive access.\n\n## Desktop App Integration\n\nSambee also bridges the gap between the browser and the apps installed on your computer. It lets you open a file in its traditional desktop app directly from the browser. In other words, you can open Word, Excel, or Photoshop files in their respective native apps. When you are done editing, your changes are uploaded back to the original storage location, such as a file share. All of this happens through a smooth, browser-based workflow.\n", "1.0": "+++\ntitle = \"What Is Sambee?\"\n+++\n\n## Sambee Turns Your Storage Into a Modern Workspace\n\nSambee gives organizations and individuals a self-hosted, browser-based workspace for files on existing **SMB shares** and **local drives**. Users can browse, view, and edit files from PCs, phones, and tablets, or open and edit them in desktop apps with changes uploaded back to their original location.\n\n## Browser-Based File Manager\n\nSambee can replace traditional tools like Windows File Explorer.\n\n### Works on PCs, Phones, and Tablets\n\nSambee is optimized for large screens as well as for compact mobile devices.\n\n### Supports SMB Shares and Local Drives\n\nSMB shares are accessed through Sambee's server component, which translates between HTTP(S), which your browser understands, and SMB, which a file server understands.\n\nLocal drive access is provided by Sambee Companion, a helper app that can be installed on your computer and acts as a small service your browser can talk to.\n\n## View and Edit Files\n\n### Image \u0026 PDF Viewers\n\nSambee is much more than a file manager. It includes a fast image browser with broad file type support, and a robust PDF viewer that opens even problematic PDFs. All of these work directly in the browser and do not require additional software.\n\n### Markdown \u0026 Text Editors\n\nMarkdown files are rendered with rich formatting and can be modified efficiently with user-friendly WYSIWYG editing of Markdown tables.\n\nText files of any kind can be viewed and edited in the built-in text editor, complete with syntax highlighting and search \u0026 replace.\n\n### Desktop App Integration\n\nSambee also bridges the gap between the browser and the apps installed on your computer. It lets you open a file in its traditional desktop app directly from the browser. In other words, you can open Word, Excel, or Photoshop files in their respective native apps. When you are done editing, your changes are uploaded back to the original storage location, such as a file share. All of this happens through a smooth, browser-based workflow.\n\n## Free \u0026 Open Source\n\nSambee is free and open source software designed for self-hosting as a Docker container.\n", "2.0": "+++\ntitle = \"What Is Sambee?\"\n+++\n\n## Sambee Turns Your Storage Into a Modern Workspace\n\nSambee gives organizations and individuals a self-hosted, browser-based workspace for files on existing **SMB shares** and **local drives**. Users can browse, view, and edit files from PCs, phones, and tablets, or open and edit them in desktop apps with changes uploaded back to their original location.\n\n## Browser-Based File Manager\n\nSambee can replace traditional tools like Windows File Explorer.\n\n### Works on PCs, Phones, and Tablets\n\nSambee is optimized for large screens as well as for compact mobile devices.\n\n### Supports SMB Shares and Local Drives\n\nSMB shares are accessed through Sambee's server component, which translates between HTTP(S), which your browser understands, and SMB, which a file server understands.\n\nLocal drive access is provided by Sambee Companion, a helper app that can be installed on your computer and acts as a small service your browser can talk to.\n\n## View and Edit Files\n\n### Image \u0026 PDF Viewers\n\nSambee is much more than a file manager. It includes a fast image browser with broad file type support, and a robust PDF viewer that opens even problematic PDFs. All of these work directly in the browser and do not require additional software.\n\n### Markdown \u0026 Text Editors\n\nMarkdown files are rendered with rich formatting and can be modified efficiently with user-friendly WYSIWYG editing of Markdown tables.\n\nText files of any kind can be viewed and edited in the built-in text editor, complete with syntax highlighting and search \u0026 replace.\n\n### Desktop App Integration\n\nSambee also bridges the gap between the browser and the apps installed on your computer. It lets you open a file in its traditional desktop app directly from the browser. In other words, you can open Word, Excel, or Photoshop files in their respective native apps. When you are done editing, your changes are uploaded back to the original storage location, such as a file share. All of this happens through a smooth, browser-based workflow.\n\n## Free \u0026 Open Source\n\nSambee is free and open source software designed for self-hosting as a Docker container.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:user-guide/getting-started/manage-your-account", "parent_id": "section:user-guide/getting-started", "depth": 2, "kind": "page", "label": "manage-your-account", "title": "Manage Your Account", "path": "user-guide/getting-started/manage-your-account", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "authored"}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "branched", "source_version": "0.9", "diff_added": 6, "diff_removed": 0}}, "content_versions": {"0.9": "+++\ntitle = \"Manage Your Account\"\n+++\n\nOpen **Settings** \u003e **Account** to review the identity Sambee uses for your current sign-in, including your username, optional name and email, and assigned role.\n\n## Sign Out\n\nSelect **Sign out** next to **This browser** in **Sessions** to return to the sign-in page. For OIDC, this also revokes the current OIDC browser session. For a password sign-in, Sambee clears the current browser's local access token; password sessions are not stored as server-side browser sessions.\n\n## Change a Local Password\n\nThe **Password** section appears when local password sign-in is configured and your account has a local password. It remains available when runtime authentication enforcement is temporarily bypassed. Enter your current password, then enter and confirm a new password. Sambee signs out the current browser after a successful change; sign in again with the new password.\n\nWhen your organization uses **OIDC only**, the Password section is unavailable because local passwords cannot be used to sign in.\n\n## Manage Sessions\n\nThe **Sessions** section separates **This browser** from **Other sessions**. It always shows the current browser when authentication is enforced. A password sign-in can show its sign-in type, but it has no server-side session ID, browser label, sign-in time, or activity history.\n\nOther sessions are active OIDC browser sessions. They show when each session was created and last active. For newly created sessions, Sambee can also show a coarse browser and operating-system label, such as **Firefox on Linux**. These labels do not identify a device or host, and older sessions might not have one.\n\n- Select **Sign out** next to the current browser to revoke its OIDC browser session and return to the sign-in page.\n- Select **Revoke** to end another browser session.\n\nRevoking a browser session immediately invalidates its Sambee API tokens. It does not sign the user out of the identity provider itself. See [OpenID Connect Authentication Operations](../../../admin-guide/authentication/openid-connect-authentication-operations/) for session lifecycle details.\n\nWhen authentication is not enforced, Sambee cannot identify or end a browser session. The **Sessions** section shows this status without a session entry or sign-out action.\n", "1.0": "+++\ntitle = \"Manage Your Account\"\n+++\n\nOpen **Settings** \u003e **Account** to review the identity Sambee uses for your current sign-in, including your username, optional name and email, and assigned role.\n\n## Sign Out\n\nSelect **Sign out** next to **This browser** in **Sessions** to return to the sign-in page. For OIDC, this also revokes the current OIDC browser session. For a password sign-in, Sambee clears the current browser's local access token; password sessions are not stored as server-side browser sessions.\n\n## Change a Local Password\n\nThe **Password** section appears when local password sign-in is configured and your account has a local password. It remains available when runtime authentication enforcement is temporarily bypassed. Enter your current password, then enter and confirm a new password. Sambee signs out the current browser after a successful change; sign in again with the new password.\n\nWhen your organization uses **OIDC only**, the Password section is unavailable because local passwords cannot be used to sign in.\n\n## Manage Sessions\n\nThe **Sessions** section separates **This browser** from **Other sessions**. It always shows the current browser when authentication is enforced. A password sign-in can show its sign-in type, but it has no server-side session ID, browser label, sign-in time, or activity history.\n\nOther sessions are active OIDC browser sessions. They show when each session was created and last active. For newly created sessions, Sambee can also show a coarse browser and operating-system label, such as **Firefox on Linux**. These labels do not identify a device or host, and older sessions might not have one.\n\n- Select **Sign out** next to the current browser to revoke its OIDC browser session and return to the sign-in page.\n- Select **Revoke** to end another browser session.\n\nRevoking a browser session immediately invalidates its Sambee API tokens. It does not sign the user out of the identity provider itself. See [OpenID Connect Authentication Operations](../../../admin-guide/authentication/openid-connect-authentication-operations/) for session lifecycle details.\n\nWhen authentication is not enforced, Sambee cannot identify or end a browser session. The **Sessions** section shows this status without a session entry or sign-out action.\n", "2.0": "+++\ntitle = \"Manage Your Account\"\n+++\n\nOpen **Settings** \u003e **Account** to review the identity Sambee uses for your current sign-in, including your username, optional name and email, and assigned role.\n\n## Sign In With A Local Password\n\nUsernames aren't case-sensitive: `Testuser` and `testuser` sign in to the same account. Leading and trailing username whitespace is ignored. Passwords remain case-sensitive and aren't trimmed. Use **Show password** beside the password field to reveal what you've entered, and **Hide password** to conceal it again.\n\nIf an older installation already contains accounts whose usernames differ only by case, those accounts temporarily require their exact username spelling. Ask an administrator to resolve the conflicting names. Once the conflict is resolved, capitalization no longer matters.\n\n## Sign Out\n\nSelect **Sign out** next to **This browser** in **Sessions** to return to the sign-in page. For OIDC, this also revokes the current OIDC browser session. For a password sign-in, Sambee clears the current browser's local access token; password sessions are not stored as server-side browser sessions.\n\n## Change a Local Password\n\nThe **Password** section appears when local password sign-in is configured and your account has a local password. It remains available when runtime authentication enforcement is temporarily bypassed. Enter your current password, then enter and confirm a new password. Sambee signs out the current browser after a successful change; sign in again with the new password.\n\nWhen your organization uses **OIDC only**, the Password section is unavailable because local passwords cannot be used to sign in.\n\n## Manage Sessions\n\nThe **Sessions** section separates **This browser** from **Other sessions**. It always shows the current browser when authentication is enforced. A password sign-in can show its sign-in type, but it has no server-side session ID, browser label, sign-in time, or activity history.\n\nOther sessions are active OIDC browser sessions. They show when each session was created and last active. For newly created sessions, Sambee can also show a coarse browser and operating-system label, such as **Firefox on Linux**. These labels do not identify a device or host, and older sessions might not have one.\n\n- Select **Sign out** next to the current browser to revoke its OIDC browser session and return to the sign-in page.\n- Select **Revoke** to end another browser session.\n\nRevoking a browser session immediately invalidates its Sambee API tokens. It does not sign the user out of the identity provider itself. See [OpenID Connect Authentication Operations](../../../admin-guide/authentication/openid-connect-authentication-operations/) for session lifecycle details.\n\nWhen authentication is not enforced, Sambee cannot identify or end a browser session. The **Sessions** section shows this status without a session entry or sign-out action.\n"}, "page_contents": {"0.9": "+++\ntitle = \"Manage Your Account\"\n+++\n\nOpen **Settings** \u003e **Account** to review the identity Sambee uses for your current sign-in, including your username, optional name and email, and assigned role.\n\n## Sign Out\n\nSelect **Sign out** next to **This browser** in **Sessions** to return to the sign-in page. For OIDC, this also revokes the current OIDC browser session. For a password sign-in, Sambee clears the current browser's local access token; password sessions are not stored as server-side browser sessions.\n\n## Change a Local Password\n\nThe **Password** section appears when local password sign-in is configured and your account has a local password. It remains available when runtime authentication enforcement is temporarily bypassed. Enter your current password, then enter and confirm a new password. Sambee signs out the current browser after a successful change; sign in again with the new password.\n\nWhen your organization uses **OIDC only**, the Password section is unavailable because local passwords cannot be used to sign in.\n\n## Manage Sessions\n\nThe **Sessions** section separates **This browser** from **Other sessions**. It always shows the current browser when authentication is enforced. A password sign-in can show its sign-in type, but it has no server-side session ID, browser label, sign-in time, or activity history.\n\nOther sessions are active OIDC browser sessions. They show when each session was created and last active. For newly created sessions, Sambee can also show a coarse browser and operating-system label, such as **Firefox on Linux**. These labels do not identify a device or host, and older sessions might not have one.\n\n- Select **Sign out** next to the current browser to revoke its OIDC browser session and return to the sign-in page.\n- Select **Revoke** to end another browser session.\n\nRevoking a browser session immediately invalidates its Sambee API tokens. It does not sign the user out of the identity provider itself. See [OpenID Connect Authentication Operations](../../../admin-guide/authentication/openid-connect-authentication-operations/) for session lifecycle details.\n\nWhen authentication is not enforced, Sambee cannot identify or end a browser session. The **Sessions** section shows this status without a session entry or sign-out action.\n", "1.0": "+++\ntitle = \"Manage Your Account\"\n+++\n\nOpen **Settings** \u003e **Account** to review the identity Sambee uses for your current sign-in, including your username, optional name and email, and assigned role.\n\n## Sign Out\n\nSelect **Sign out** next to **This browser** in **Sessions** to return to the sign-in page. For OIDC, this also revokes the current OIDC browser session. For a password sign-in, Sambee clears the current browser's local access token; password sessions are not stored as server-side browser sessions.\n\n## Change a Local Password\n\nThe **Password** section appears when local password sign-in is configured and your account has a local password. It remains available when runtime authentication enforcement is temporarily bypassed. Enter your current password, then enter and confirm a new password. Sambee signs out the current browser after a successful change; sign in again with the new password.\n\nWhen your organization uses **OIDC only**, the Password section is unavailable because local passwords cannot be used to sign in.\n\n## Manage Sessions\n\nThe **Sessions** section separates **This browser** from **Other sessions**. It always shows the current browser when authentication is enforced. A password sign-in can show its sign-in type, but it has no server-side session ID, browser label, sign-in time, or activity history.\n\nOther sessions are active OIDC browser sessions. They show when each session was created and last active. For newly created sessions, Sambee can also show a coarse browser and operating-system label, such as **Firefox on Linux**. These labels do not identify a device or host, and older sessions might not have one.\n\n- Select **Sign out** next to the current browser to revoke its OIDC browser session and return to the sign-in page.\n- Select **Revoke** to end another browser session.\n\nRevoking a browser session immediately invalidates its Sambee API tokens. It does not sign the user out of the identity provider itself. See [OpenID Connect Authentication Operations](../../../admin-guide/authentication/openid-connect-authentication-operations/) for session lifecycle details.\n\nWhen authentication is not enforced, Sambee cannot identify or end a browser session. The **Sessions** section shows this status without a session entry or sign-out action.\n", "2.0": "+++\ntitle = \"Manage Your Account\"\n+++\n\nOpen **Settings** \u003e **Account** to review the identity Sambee uses for your current sign-in, including your username, optional name and email, and assigned role.\n\n## Sign In With A Local Password\n\nUsernames aren't case-sensitive: `Testuser` and `testuser` sign in to the same account. Leading and trailing username whitespace is ignored. Passwords remain case-sensitive and aren't trimmed. Use **Show password** beside the password field to reveal what you've entered, and **Hide password** to conceal it again.\n\nIf an older installation already contains accounts whose usernames differ only by case, those accounts temporarily require their exact username spelling. Ask an administrator to resolve the conflicting names. Once the conflict is resolved, capitalization no longer matters.\n\n## Sign Out\n\nSelect **Sign out** next to **This browser** in **Sessions** to return to the sign-in page. For OIDC, this also revokes the current OIDC browser session. For a password sign-in, Sambee clears the current browser's local access token; password sessions are not stored as server-side browser sessions.\n\n## Change a Local Password\n\nThe **Password** section appears when local password sign-in is configured and your account has a local password. It remains available when runtime authentication enforcement is temporarily bypassed. Enter your current password, then enter and confirm a new password. Sambee signs out the current browser after a successful change; sign in again with the new password.\n\nWhen your organization uses **OIDC only**, the Password section is unavailable because local passwords cannot be used to sign in.\n\n## Manage Sessions\n\nThe **Sessions** section separates **This browser** from **Other sessions**. It always shows the current browser when authentication is enforced. A password sign-in can show its sign-in type, but it has no server-side session ID, browser label, sign-in time, or activity history.\n\nOther sessions are active OIDC browser sessions. They show when each session was created and last active. For newly created sessions, Sambee can also show a coarse browser and operating-system label, such as **Firefox on Linux**. These labels do not identify a device or host, and older sessions might not have one.\n\n- Select **Sign out** next to the current browser to revoke its OIDC browser session and return to the sign-in page.\n- Select **Revoke** to end another browser session.\n\nRevoking a browser session immediately invalidates its Sambee API tokens. It does not sign the user out of the identity provider itself. See [OpenID Connect Authentication Operations](../../../admin-guide/authentication/openid-connect-authentication-operations/) for session lifecycle details.\n\nWhen authentication is not enforced, Sambee cannot identify or end a browser session. The **Sessions** section shows this status without a session entry or sign-out action.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:user-guide/accessing-files", "parent_id": "book:user-guide", "depth": 1, "kind": "section", "label": "accessing-files", "title": "Accessing Files", "path": "user-guide/accessing-files", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:user-guide/accessing-files/connect-to-an-smb-share", "parent_id": "section:user-guide/accessing-files", "depth": 2, "kind": "page", "label": "connect-to-an-smb-share", "title": "Connect To An Smb Share", "path": "user-guide/accessing-files/connect-to-an-smb-share", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Connect to an SMB Share\"\n+++\n\nSMB connections are managed in Sambee's settings, which you can open via the gear icon or with the keyboard shortcut \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e,\u003c/kbd\u003e.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nConnecting to SMB shares does not require the Sambee Companion app. Companion is only for local-drive access and desktop-app integration.\n{{\u003c /admonition \u003e}}\n\n## Add a New Connection\n\nNavigate to **Settings** \u003e **Connections**, select **Add Connection**, and fill out the form.\n\nHints and tips:\n\n- **Connection name:** This is the display name for the connection in Sambee's UI.\n- **Path prefix:** If you specify a subdirectory in the share, Sambee's connection root will start in that subdirectory.\n- **Visibility:** Connections can be for your account only or for all users on the Sambee server.\n- **Access mode:** If you want to prevent modifications to the data on the share, set this to **read only**.\n\n## Explore Files of a Connection\n\nTo explore the files and folders in an SMB connection, locate the **Connection List** in the main UI and select the connection you want to open (keyboard shortcut: \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e).\n", "0.8": "+++\ntitle = \"Connect to an SMB Share\"\n+++\n\nSMB connections are managed in Sambee's settings, which you can open via the gear icon or with the keyboard shortcut \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e,\u003c/kbd\u003e.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nConnecting to SMB shares does not require the Sambee Companion app. Companion is only for local-drive access and desktop-app integration.\n{{\u003c /admonition \u003e}}\n\n## Add a New Connection\n\nNavigate to **Settings** \u003e **Connections**, select **Add Connection**, and fill out the form.\n\nHints and tips:\n\n- **Connection name:** This is the display name for the connection in Sambee's UI.\n- **Path prefix:** If you specify a subdirectory in the share, Sambee's connection root will start in that subdirectory.\n- **Visibility:** Connections can be for your account only or for all users on the Sambee server.\n- **Access mode:** If you want to prevent modifications to the data on the share, set this to **read only**.\n\n## Explore Files of a Connection\n\nTo explore the files and folders in an SMB connection, locate the **Connection List** in the main UI and select the connection you want to open (keyboard shortcut: \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e).\n", "0.9": "+++\ntitle = \"Connect to an SMB Share\"\n+++\n\nSMB connections are managed in Sambee's settings, which you can open via the gear icon or with the keyboard shortcut \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e,\u003c/kbd\u003e.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nConnecting to SMB shares does not require the Sambee Companion app. Companion is only for local-drive access and desktop-app integration.\n{{\u003c /admonition \u003e}}\n\n## Add a New Connection\n\nNavigate to **Settings** \u003e **Connections**, select **Add Connection**, and fill out the form.\n\nHints and tips:\n\n- **Connection name:** This is the display name for the connection in Sambee's UI.\n- **Path prefix:** If you specify a subdirectory in the share, Sambee's connection root will start in that subdirectory.\n- **Visibility:** Connections can be for your account only or for all users on the Sambee server.\n- **Access mode:** If you want to prevent modifications to the data on the share, set this to **read only**.\n\n## Explore Files of a Connection\n\nTo explore the files and folders in an SMB connection, locate the **Connection List** in the main UI and select the connection you want to open (keyboard shortcut: \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e).\n", "1.0": "+++\ntitle = \"Connect to an SMB Share\"\n+++\n\nSMB connections are managed in Sambee's settings, which you can open via the gear icon or with the keyboard shortcut \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e,\u003c/kbd\u003e.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nConnecting to SMB shares does not require the Sambee Companion app. Companion is only for local-drive access and desktop-app integration.\n{{\u003c /admonition \u003e}}\n\n## Add a New Connection\n\nNavigate to **Settings** \u003e **Connections**, select **Add Connection**, and fill out the form.\n\nHints and tips:\n\n- **Connection name:** This is the display name for the connection in Sambee's UI.\n- **Path prefix:** If you specify a subdirectory in the share, Sambee's connection root will start in that subdirectory.\n- **Visibility:** Connections can be for your account only or for all users on the Sambee server.\n- **Access mode:** If you want to prevent modifications to the data on the share, set this to **read only**.\n\n## Explore Files of a Connection\n\nTo explore the files and folders in an SMB connection, locate the **Connection List** in the main UI and select the connection you want to open (keyboard shortcut: \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e).\n", "2.0": "+++\ntitle = \"Connect to an SMB Share\"\n+++\n\nSMB connections are managed in Sambee's settings, which you can open via the gear icon or with the keyboard shortcut \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e,\u003c/kbd\u003e.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nConnecting to SMB shares does not require the Sambee Companion app. Companion is only for local-drive access and desktop-app integration.\n{{\u003c /admonition \u003e}}\n\n## Add a New Connection\n\nNavigate to **Settings** \u003e **Connections**, select **Add Connection**, and fill out the form.\n\nHints and tips:\n\n- **Connection name:** This is the display name for the connection in Sambee's UI.\n- **Path prefix:** If you specify a subdirectory in the share, Sambee's connection root will start in that subdirectory.\n- **Visibility:** Connections can be for your account only or for all users on the Sambee server.\n- **Access mode:** If you want to prevent modifications to the data on the share, set this to **read only**.\n\n## Explore Files of a Connection\n\nTo explore the files and folders in an SMB connection, locate the **Connection List** in the main UI and select the connection you want to open (keyboard shortcut: \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e).\n"}, "page_contents": {"0.7": "+++\ntitle = \"Connect to an SMB Share\"\n+++\n\nSMB connections are managed in Sambee's settings, which you can open via the gear icon or with the keyboard shortcut \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e,\u003c/kbd\u003e.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nConnecting to SMB shares does not require the Sambee Companion app. Companion is only for local-drive access and desktop-app integration.\n{{\u003c /admonition \u003e}}\n\n## Add a New Connection\n\nNavigate to **Settings** \u003e **Connections**, select **Add Connection**, and fill out the form.\n\nHints and tips:\n\n- **Connection name:** This is the display name for the connection in Sambee's UI.\n- **Path prefix:** If you specify a subdirectory in the share, Sambee's connection root will start in that subdirectory.\n- **Visibility:** Connections can be for your account only or for all users on the Sambee server.\n- **Access mode:** If you want to prevent modifications to the data on the share, set this to **read only**.\n\n## Explore Files of a Connection\n\nTo explore the files and folders in an SMB connection, locate the **Connection List** in the main UI and select the connection you want to open (keyboard shortcut: \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e).\n", "0.8": "+++\ntitle = \"Connect to an SMB Share\"\n+++\n\nSMB connections are managed in Sambee's settings, which you can open via the gear icon or with the keyboard shortcut \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e,\u003c/kbd\u003e.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nConnecting to SMB shares does not require the Sambee Companion app. Companion is only for local-drive access and desktop-app integration.\n{{\u003c /admonition \u003e}}\n\n## Add a New Connection\n\nNavigate to **Settings** \u003e **Connections**, select **Add Connection**, and fill out the form.\n\nHints and tips:\n\n- **Connection name:** This is the display name for the connection in Sambee's UI.\n- **Path prefix:** If you specify a subdirectory in the share, Sambee's connection root will start in that subdirectory.\n- **Visibility:** Connections can be for your account only or for all users on the Sambee server.\n- **Access mode:** If you want to prevent modifications to the data on the share, set this to **read only**.\n\n## Explore Files of a Connection\n\nTo explore the files and folders in an SMB connection, locate the **Connection List** in the main UI and select the connection you want to open (keyboard shortcut: \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e).\n", "0.9": "+++\ntitle = \"Connect to an SMB Share\"\n+++\n\nSMB connections are managed in Sambee's settings, which you can open via the gear icon or with the keyboard shortcut \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e,\u003c/kbd\u003e.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nConnecting to SMB shares does not require the Sambee Companion app. Companion is only for local-drive access and desktop-app integration.\n{{\u003c /admonition \u003e}}\n\n## Add a New Connection\n\nNavigate to **Settings** \u003e **Connections**, select **Add Connection**, and fill out the form.\n\nHints and tips:\n\n- **Connection name:** This is the display name for the connection in Sambee's UI.\n- **Path prefix:** If you specify a subdirectory in the share, Sambee's connection root will start in that subdirectory.\n- **Visibility:** Connections can be for your account only or for all users on the Sambee server.\n- **Access mode:** If you want to prevent modifications to the data on the share, set this to **read only**.\n\n## Explore Files of a Connection\n\nTo explore the files and folders in an SMB connection, locate the **Connection List** in the main UI and select the connection you want to open (keyboard shortcut: \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e).\n", "1.0": "+++\ntitle = \"Connect to an SMB Share\"\n+++\n\nSMB connections are managed in Sambee's settings, which you can open via the gear icon or with the keyboard shortcut \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e,\u003c/kbd\u003e.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nConnecting to SMB shares does not require the Sambee Companion app. Companion is only for local-drive access and desktop-app integration.\n{{\u003c /admonition \u003e}}\n\n## Add a New Connection\n\nNavigate to **Settings** \u003e **Connections**, select **Add Connection**, and fill out the form.\n\nHints and tips:\n\n- **Connection name:** This is the display name for the connection in Sambee's UI.\n- **Path prefix:** If you specify a subdirectory in the share, Sambee's connection root will start in that subdirectory.\n- **Visibility:** Connections can be for your account only or for all users on the Sambee server.\n- **Access mode:** If you want to prevent modifications to the data on the share, set this to **read only**.\n\n## Explore Files of a Connection\n\nTo explore the files and folders in an SMB connection, locate the **Connection List** in the main UI and select the connection you want to open (keyboard shortcut: \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e).\n", "2.0": "+++\ntitle = \"Connect to an SMB Share\"\n+++\n\nSMB connections are managed in Sambee's settings, which you can open via the gear icon or with the keyboard shortcut \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e,\u003c/kbd\u003e.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nConnecting to SMB shares does not require the Sambee Companion app. Companion is only for local-drive access and desktop-app integration.\n{{\u003c /admonition \u003e}}\n\n## Add a New Connection\n\nNavigate to **Settings** \u003e **Connections**, select **Add Connection**, and fill out the form.\n\nHints and tips:\n\n- **Connection name:** This is the display name for the connection in Sambee's UI.\n- **Path prefix:** If you specify a subdirectory in the share, Sambee's connection root will start in that subdirectory.\n- **Visibility:** Connections can be for your account only or for all users on the Sambee server.\n- **Access mode:** If you want to prevent modifications to the data on the share, set this to **read only**.\n\n## Explore Files of a Connection\n\nTo explore the files and folders in an SMB connection, locate the **Connection List** in the main UI and select the connection you want to open (keyboard shortcut: \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e).\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:user-guide/accessing-files/access-local-drives", "parent_id": "section:user-guide/accessing-files", "depth": 2, "kind": "page", "label": "access-local-drives", "title": "Access Local Drives", "path": "user-guide/accessing-files/access-local-drives", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Access Local Drives\"\n+++\n\nLocal-drive access is available after Sambee Companion is [installed and paired](../../companion-app/install-and-pair-the-companion-app/).\n\n## Before You Start\n\nLocal drives in the browser require all of the following:\n\n- a desktop browser\n- Sambee Companion installed and running on the same computer\n- a completed trust approval for this browser\n\nIf any of those pieces is missing, continue with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/).\n\n## Explore Local Drives\n\nWhen Companion is running and this browser is paired, local drives appear in the **Connection List** next to SMB connections (keyboard shortcut: \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e).\n\nThe list reflects the drives and mounted volumes that the current desktop user can already access through the operating system. Typical examples include:\n\n- **Disks**, e.g., `C:\\`\n- **Removable drives**, such as USB storage.\n- **Mapped network drives**, e.g., SMB connections mounted by the operating system.\n- **Virtual or cloud-backed drives**, e.g., from Google Drive, OneDrive, or Dropbox.\n\nSambee asks Companion for the current drive list when needed. You do not need to configure local drives manually in the browser.\n\n## If Local Drives Do Not Appear\n\nOpen **Settings** \u003e **Local Drives** and check the current status.\n\n- If Companion is not running, start it and refresh the page.\n- If the browser is not paired, pair this browser with Companion.\n- If Local Drives reports that pairing needs repair, reapprove this browser so Sambee can store a fresh local browser secret.\n\nFor a step-by-step recovery checklist, continue with [Common User Problems](../../troubleshooting/common-user-problems/).\n", "0.8": "+++\ntitle = \"Access Local Drives\"\n+++\n\nLocal-drive access is available after Sambee Companion is [installed and paired](../../companion-app/install-and-pair-the-companion-app/).\n\n## Before You Start\n\nLocal drives in the browser require all of the following:\n\n- a desktop browser\n- Sambee Companion installed and running on the same computer\n- a completed trust approval for this browser\n\nIf any of those pieces is missing, continue with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/).\n\n## Explore Local Drives\n\nWhen Companion is running and this browser is paired, local drives appear in the **Connection List** next to SMB connections (keyboard shortcut: \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e).\n\nThe list reflects the drives and mounted volumes that the current desktop user can already access through the operating system. Typical examples include:\n\n- **Disks**, e.g., `C:\\`\n- **Removable drives**, such as USB storage.\n- **Mapped network drives**, e.g., SMB connections mounted by the operating system.\n- **Virtual or cloud-backed drives**, e.g., from Google Drive, OneDrive, or Dropbox.\n\nSambee asks Companion for the current drive list when needed. You do not need to configure local drives manually in the browser.\n\n## If Local Drives Do Not Appear\n\nOpen **Settings** \u003e **Local Drives** and check the current status.\n\n- If Companion is not running, start it and refresh the page.\n- If the browser is not paired, pair this browser with Companion.\n- If Local Drives reports that pairing needs repair, reapprove this browser so Sambee can store a fresh local browser secret.\n\nFor a step-by-step recovery checklist, continue with [Common User Problems](../../troubleshooting/common-user-problems/).\n", "0.9": "+++\ntitle = \"Access Local Drives\"\n+++\n\nLocal-drive access is available after Sambee Companion is [installed and paired](../../companion-app/install-and-pair-the-companion-app/).\n\n## Before You Start\n\nLocal drives in the browser require all of the following:\n\n- a desktop browser\n- Sambee Companion installed and running on the same computer\n- a completed trust approval for this browser\n\nIf any of those pieces is missing, continue with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/).\n\n## Explore Local Drives\n\nWhen Companion is running and this browser is paired, local drives appear in the **Connection List** next to SMB connections (keyboard shortcut: \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e).\n\nThe list reflects the drives and mounted volumes that the current desktop user can already access through the operating system. Typical examples include:\n\n- **Disks**, e.g., `C:\\`\n- **Removable drives**, such as USB storage.\n- **Mapped network drives**, e.g., SMB connections mounted by the operating system.\n- **Virtual or cloud-backed drives**, e.g., from Google Drive, OneDrive, or Dropbox.\n\nSambee asks Companion for the current drive list when needed. You do not need to configure local drives manually in the browser.\n\n## If Local Drives Do Not Appear\n\nOpen **Settings** \u003e **Local Drives** and check the current status.\n\n- If Companion is not running, start it and refresh the page.\n- If the browser is not paired, pair this browser with Companion.\n- If Local Drives reports that pairing needs repair, reapprove this browser so Sambee can store a fresh local browser secret.\n\nFor a step-by-step recovery checklist, continue with [Common User Problems](../../troubleshooting/common-user-problems/).\n", "1.0": "+++\ntitle = \"Access Local Drives\"\n+++\n\nLocal-drive access is available after Sambee Companion is [installed and paired](../../companion-app/install-and-pair-the-companion-app/).\n\n## Before You Start\n\nLocal drives in the browser require all of the following:\n\n- a desktop browser\n- Sambee Companion installed and running on the same computer\n- a completed trust approval for this browser\n\nIf any of those pieces is missing, continue with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/).\n\n## Explore Local Drives\n\nWhen Companion is running and this browser is paired, local drives appear in the **Connection List** next to SMB connections (keyboard shortcut: \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e).\n\nThe list reflects the drives and mounted volumes that the current desktop user can already access through the operating system. Typical examples include:\n\n- **Disks**, e.g., `C:\\`\n- **Removable drives**, such as USB storage.\n- **Mapped network drives**, e.g., SMB connections mounted by the operating system.\n- **Virtual or cloud-backed drives**, e.g., from Google Drive, OneDrive, or Dropbox.\n\nSambee asks Companion for the current drive list when needed. You do not need to configure local drives manually in the browser.\n\n## If Local Drives Do Not Appear\n\nOpen **Settings** \u003e **Local Drives** and check the current status.\n\n- If Companion is not running, start it and refresh the page.\n- If the browser is not paired, pair this browser with Companion.\n- If Local Drives reports that pairing needs repair, reapprove this browser so Sambee can store a fresh local browser secret.\n\nFor a step-by-step recovery checklist, continue with [Common User Problems](../../troubleshooting/common-user-problems/).\n", "2.0": "+++\ntitle = \"Access Local Drives\"\n+++\n\nLocal-drive access is available after Sambee Companion is [installed and paired](../../companion-app/install-and-pair-the-companion-app/).\n\n## Before You Start\n\nLocal drives in the browser require all of the following:\n\n- a desktop browser\n- Sambee Companion installed and running on the same computer\n- a completed trust approval for this browser\n\nIf any of those pieces is missing, continue with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/).\n\n## Explore Local Drives\n\nWhen Companion is running and this browser is paired, local drives appear in the **Connection List** next to SMB connections (keyboard shortcut: \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e).\n\nThe list reflects the drives and mounted volumes that the current desktop user can already access through the operating system. Typical examples include:\n\n- **Disks**, e.g., `C:\\`\n- **Removable drives**, such as USB storage.\n- **Mapped network drives**, e.g., SMB connections mounted by the operating system.\n- **Virtual or cloud-backed drives**, e.g., from Google Drive, OneDrive, or Dropbox.\n\nSambee asks Companion for the current drive list when needed. You do not need to configure local drives manually in the browser.\n\n## If Local Drives Do Not Appear\n\nOpen **Settings** \u003e **Local Drives** and check the current status.\n\n- If Companion is not running, start it and refresh the page.\n- If the browser is not paired, pair this browser with Companion.\n- If Local Drives reports that pairing needs repair, reapprove this browser so Sambee can store a fresh local browser secret.\n\nFor a step-by-step recovery checklist, continue with [Common User Problems](../../troubleshooting/common-user-problems/).\n"}, "page_contents": {"0.7": "+++\ntitle = \"Access Local Drives\"\n+++\n\nLocal-drive access is available after Sambee Companion is [installed and paired](../../companion-app/install-and-pair-the-companion-app/).\n\n## Before You Start\n\nLocal drives in the browser require all of the following:\n\n- a desktop browser\n- Sambee Companion installed and running on the same computer\n- a completed trust approval for this browser\n\nIf any of those pieces is missing, continue with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/).\n\n## Explore Local Drives\n\nWhen Companion is running and this browser is paired, local drives appear in the **Connection List** next to SMB connections (keyboard shortcut: \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e).\n\nThe list reflects the drives and mounted volumes that the current desktop user can already access through the operating system. Typical examples include:\n\n- **Disks**, e.g., `C:\\`\n- **Removable drives**, such as USB storage.\n- **Mapped network drives**, e.g., SMB connections mounted by the operating system.\n- **Virtual or cloud-backed drives**, e.g., from Google Drive, OneDrive, or Dropbox.\n\nSambee asks Companion for the current drive list when needed. You do not need to configure local drives manually in the browser.\n\n## If Local Drives Do Not Appear\n\nOpen **Settings** \u003e **Local Drives** and check the current status.\n\n- If Companion is not running, start it and refresh the page.\n- If the browser is not paired, pair this browser with Companion.\n- If Local Drives reports that pairing needs repair, reapprove this browser so Sambee can store a fresh local browser secret.\n\nFor a step-by-step recovery checklist, continue with [Common User Problems](../../troubleshooting/common-user-problems/).\n", "0.8": "+++\ntitle = \"Access Local Drives\"\n+++\n\nLocal-drive access is available after Sambee Companion is [installed and paired](../../companion-app/install-and-pair-the-companion-app/).\n\n## Before You Start\n\nLocal drives in the browser require all of the following:\n\n- a desktop browser\n- Sambee Companion installed and running on the same computer\n- a completed trust approval for this browser\n\nIf any of those pieces is missing, continue with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/).\n\n## Explore Local Drives\n\nWhen Companion is running and this browser is paired, local drives appear in the **Connection List** next to SMB connections (keyboard shortcut: \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e).\n\nThe list reflects the drives and mounted volumes that the current desktop user can already access through the operating system. Typical examples include:\n\n- **Disks**, e.g., `C:\\`\n- **Removable drives**, such as USB storage.\n- **Mapped network drives**, e.g., SMB connections mounted by the operating system.\n- **Virtual or cloud-backed drives**, e.g., from Google Drive, OneDrive, or Dropbox.\n\nSambee asks Companion for the current drive list when needed. You do not need to configure local drives manually in the browser.\n\n## If Local Drives Do Not Appear\n\nOpen **Settings** \u003e **Local Drives** and check the current status.\n\n- If Companion is not running, start it and refresh the page.\n- If the browser is not paired, pair this browser with Companion.\n- If Local Drives reports that pairing needs repair, reapprove this browser so Sambee can store a fresh local browser secret.\n\nFor a step-by-step recovery checklist, continue with [Common User Problems](../../troubleshooting/common-user-problems/).\n", "0.9": "+++\ntitle = \"Access Local Drives\"\n+++\n\nLocal-drive access is available after Sambee Companion is [installed and paired](../../companion-app/install-and-pair-the-companion-app/).\n\n## Before You Start\n\nLocal drives in the browser require all of the following:\n\n- a desktop browser\n- Sambee Companion installed and running on the same computer\n- a completed trust approval for this browser\n\nIf any of those pieces is missing, continue with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/).\n\n## Explore Local Drives\n\nWhen Companion is running and this browser is paired, local drives appear in the **Connection List** next to SMB connections (keyboard shortcut: \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e).\n\nThe list reflects the drives and mounted volumes that the current desktop user can already access through the operating system. Typical examples include:\n\n- **Disks**, e.g., `C:\\`\n- **Removable drives**, such as USB storage.\n- **Mapped network drives**, e.g., SMB connections mounted by the operating system.\n- **Virtual or cloud-backed drives**, e.g., from Google Drive, OneDrive, or Dropbox.\n\nSambee asks Companion for the current drive list when needed. You do not need to configure local drives manually in the browser.\n\n## If Local Drives Do Not Appear\n\nOpen **Settings** \u003e **Local Drives** and check the current status.\n\n- If Companion is not running, start it and refresh the page.\n- If the browser is not paired, pair this browser with Companion.\n- If Local Drives reports that pairing needs repair, reapprove this browser so Sambee can store a fresh local browser secret.\n\nFor a step-by-step recovery checklist, continue with [Common User Problems](../../troubleshooting/common-user-problems/).\n", "1.0": "+++\ntitle = \"Access Local Drives\"\n+++\n\nLocal-drive access is available after Sambee Companion is [installed and paired](../../companion-app/install-and-pair-the-companion-app/).\n\n## Before You Start\n\nLocal drives in the browser require all of the following:\n\n- a desktop browser\n- Sambee Companion installed and running on the same computer\n- a completed trust approval for this browser\n\nIf any of those pieces is missing, continue with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/).\n\n## Explore Local Drives\n\nWhen Companion is running and this browser is paired, local drives appear in the **Connection List** next to SMB connections (keyboard shortcut: \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e).\n\nThe list reflects the drives and mounted volumes that the current desktop user can already access through the operating system. Typical examples include:\n\n- **Disks**, e.g., `C:\\`\n- **Removable drives**, such as USB storage.\n- **Mapped network drives**, e.g., SMB connections mounted by the operating system.\n- **Virtual or cloud-backed drives**, e.g., from Google Drive, OneDrive, or Dropbox.\n\nSambee asks Companion for the current drive list when needed. You do not need to configure local drives manually in the browser.\n\n## If Local Drives Do Not Appear\n\nOpen **Settings** \u003e **Local Drives** and check the current status.\n\n- If Companion is not running, start it and refresh the page.\n- If the browser is not paired, pair this browser with Companion.\n- If Local Drives reports that pairing needs repair, reapprove this browser so Sambee can store a fresh local browser secret.\n\nFor a step-by-step recovery checklist, continue with [Common User Problems](../../troubleshooting/common-user-problems/).\n", "2.0": "+++\ntitle = \"Access Local Drives\"\n+++\n\nLocal-drive access is available after Sambee Companion is [installed and paired](../../companion-app/install-and-pair-the-companion-app/).\n\n## Before You Start\n\nLocal drives in the browser require all of the following:\n\n- a desktop browser\n- Sambee Companion installed and running on the same computer\n- a completed trust approval for this browser\n\nIf any of those pieces is missing, continue with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/).\n\n## Explore Local Drives\n\nWhen Companion is running and this browser is paired, local drives appear in the **Connection List** next to SMB connections (keyboard shortcut: \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e).\n\nThe list reflects the drives and mounted volumes that the current desktop user can already access through the operating system. Typical examples include:\n\n- **Disks**, e.g., `C:\\`\n- **Removable drives**, such as USB storage.\n- **Mapped network drives**, e.g., SMB connections mounted by the operating system.\n- **Virtual or cloud-backed drives**, e.g., from Google Drive, OneDrive, or Dropbox.\n\nSambee asks Companion for the current drive list when needed. You do not need to configure local drives manually in the browser.\n\n## If Local Drives Do Not Appear\n\nOpen **Settings** \u003e **Local Drives** and check the current status.\n\n- If Companion is not running, start it and refresh the page.\n- If the browser is not paired, pair this browser with Companion.\n- If Local Drives reports that pairing needs repair, reapprove this browser so Sambee can store a fresh local browser secret.\n\nFor a step-by-step recovery checklist, continue with [Common User Problems](../../troubleshooting/common-user-problems/).\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:user-guide/browsing-and-navigation", "parent_id": "book:user-guide", "depth": 1, "kind": "section", "label": "browsing-and-navigation", "title": "Browsing and Navigation", "path": "user-guide/browsing-and-navigation", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:user-guide/browsing-and-navigation/smart-navigation-and-the-quick-bar", "parent_id": "section:user-guide/browsing-and-navigation", "depth": 2, "kind": "page", "label": "smart-navigation-and-the-quick-bar", "title": "Smart Navigation And The Quick Bar", "path": "user-guide/browsing-and-navigation/smart-navigation-and-the-quick-bar", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "branched", "source_version": "0.7", "diff_added": 57, "diff_removed": 15}, "2.0": {"state": "branched", "source_version": "1.0", "diff_added": 6, "diff_removed": 0}}, "content_versions": {"0.7": "+++\ntitle = \"Smart Navigation and the Quick Bar\"\n+++\n\nThe quick bar is one of Sambee's core navigation features.\n\nIf you have used Visual Studio Code, the interaction model will feel familiar: one shared bar helps you navigate, filter, and run commands quickly.\n\nThe quick bar has multiple modes:\n\n- Smart navigation with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e\n- File list filtering with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e\n- Command mode with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e or \u003ckbd\u003eF1\u003c/kbd\u003e\n\n## Jump to Any Directory with Smart Navigation\n\n1. Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e to open smart navigation.\n1. Type part of a directory name.\n1. Sambee lists all matches across the current connection.\n1. Choose the match you want to jump to and open that directory immediately.\n\n## Filter Files in the Current Directory\n\n1. Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e to open the quick bar in file list filtering mode.\n1. Type part of a file or directory name.\n1. Sambee filters the file list to only those items matching your search term.\n\n## Locate and Run Any Command\n\n1. Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e or \u003ckbd\u003eF1\u003c/kbd\u003e to open the quick bar in command mode.\n1. Type part of the name of a command.\n1. Sambee lists all matching commands.\n1. Choose the command you want to run.\n", "0.8": "+++\ntitle = \"Smart Navigation and the Quick Bar\"\n+++\n\nThe quick bar is one of Sambee's core navigation features.\n\nIf you have used Visual Studio Code, the interaction model will feel familiar: one shared bar helps you navigate, filter, and run commands quickly.\n\nThe quick bar has multiple modes:\n\n- Smart navigation with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e\n- File list filtering with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e\n- Command mode with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e or \u003ckbd\u003eF1\u003c/kbd\u003e\n\n## Jump to Any Directory with Smart Navigation\n\n1. Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e to open smart navigation.\n1. Type part of a directory name.\n1. Sambee lists all matches across the current connection.\n1. Choose the match you want to jump to and open that directory immediately.\n\n## Filter Files in the Current Directory\n\n1. Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e to open the quick bar in file list filtering mode.\n1. Type part of a file or directory name.\n1. Sambee filters the file list to only those items matching your search term.\n\n## Locate and Run Any Command\n\n1. Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e or \u003ckbd\u003eF1\u003c/kbd\u003e to open the quick bar in command mode.\n1. Type part of the name of a command.\n1. Sambee lists all matching commands.\n1. Choose the command you want to run.\n", "0.9": "+++\ntitle = \"Smart Navigation and the Quick Bar\"\n+++\n\nThe quick bar is one of Sambee's core navigation features.\n\nIf you have used Visual Studio Code, the interaction model will feel familiar: one shared bar helps you navigate, filter, and run commands quickly.\n\nThe quick bar has multiple modes:\n\n- Smart navigation with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e\n- File list filtering with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e\n- Command mode with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e or \u003ckbd\u003eF1\u003c/kbd\u003e\n\n## Jump to Any Directory with Smart Navigation\n\n1. Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e to open smart navigation.\n1. Type part of a directory name.\n1. Sambee lists all matches across the current connection.\n1. Choose the match you want to jump to and open that directory immediately.\n\n## Filter Files in the Current Directory\n\n1. Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e to open the quick bar in file list filtering mode.\n1. Type part of a file or directory name.\n1. Sambee filters the file list to only those items matching your search term.\n\n## Locate and Run Any Command\n\n1. Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e or \u003ckbd\u003eF1\u003c/kbd\u003e to open the quick bar in command mode.\n1. Type part of the name of a command.\n1. Sambee lists all matching commands.\n1. Choose the command you want to run.\n", "1.0": "+++\ntitle = \"Smart Navigation and the Quick Bar\"\n+++\n\nThe quick bar provides fast navigation, File Search, and commands from one shared control.\n\nThe quick bar has multiple modes:\n\n- Smart navigation with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e\n- File Search with \u003ckbd\u003e/\u003c/kbd\u003e\n- Command mode with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e\n\n## Jump to Any Directory with Smart Navigation\n\n1. Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e to open smart navigation.\n1. Type part of a directory name.\n1. Sambee lists matches across the current connection.\n1. Choose a match to open that directory.\n\n### Recent Directory History\n\nRecent directories appear before cache-based directory matches, including when the search box is empty. Choose a recent directory to switch to its connection and open the saved location. A directory that is both recent and present in the active connection's cache is shown once in Recent directories.\n\nTo remove only the selected item from Recent directories, press \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDelete\u003c/kbd\u003e. This removes history metadata; it never deletes the underlying directory or its contents.\n\nSambee records a directory after it opens successfully. History is private to your account. You can clear your directory history from **Settings** \u003e **File Browser** \u003e **Directory Navigation**.\n\n## Find Files with File Search\n\n1. Press \u003ckbd\u003e/\u003c/kbd\u003e when the file browser has keyboard focus.\n1. Type part of a filename.\n1. Review the separate Recent files and Current directory groups.\n1. Select a file and press \u003ckbd\u003eEnter\u003c/kbd\u003e to open it.\n\nFile Search doesn't build a global file index. It searches the files currently loaded in the active directory and your per-user recent-file history. A file that appears in both places is shown once in Recent files.\n\nUse modifiers with \u003ckbd\u003eEnter\u003c/kbd\u003e or a result click to choose how to open the selected file:\n\n- \u003ckbd\u003eCtrl\u003c/kbd\u003e opens it in the associated native application.\n- \u003ckbd\u003eShift\u003c/kbd\u003e opens the browser viewer picker.\n- \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e opens the native application picker.\n\nTo remove only a selected item from Recent files, press \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDelete\u003c/kbd\u003e. This removes history metadata; it never deletes the underlying file.\n\nRecent files are recorded when you attempt to open a regular file. History is private to your account and follows the configured retention and exclusion policy. The system verifies remote SMB targets and local Companion targets as regular files before keeping a history record.\n\nThe File Search settings show whether Sambee is using the built-in defaults or an administrator's saved system override. Administrators can reset an override to the built-in defaults. Lowering retention removes the oldest records immediately, and setting retention to zero clears history and prevents new records. Image, temporary, backup, and configured extension exclusions apply before a record is stored.\n\nIf a recent remote file no longer exists, Sambee removes its stale history entry after confirming that state. For local drives, Companion distinguishes a missing or no-longer-regular file from an unavailable drive; confirmed stale targets are removed, while unavailable, unpaired, or temporarily failing local drives keep their history for a later retry.\n\nYou can clear your own history from **Settings** \u003e **File Browser** \u003e **File Search**. Administrators can set retention, per-group result limits, and exclusion rules in **Settings** \u003e **File Search**. Add each extension exclusion as one literal extension; Sambee normalizes it, such as `TMP` to `.tmp`, and lets you remove it from the exclusion list.\n\n## Quick Bar Shortcut Hints\n\nChoose when shortcut hints appear in **Settings** \u003e **File Browser** \u003e **Shortcut hints**:\n\n- **Auto** shows hints on larger layouts and after you use a keyboard in the current compact-layout session.\n- **Always** shows hints in every layout.\n- **Never** hides the shortcut labels while keeping Quick Bar status information visible.\n\n## Touch-Friendly File Selection\n\nChoose when touch-friendly file selection is available in **Settings** \u003e **File Browser** \u003e **File selection**. This keeps the desktop layout and toolbar on larger devices while making row selection easier to use by touch.\n\n- **Automatic** enables touch selection when the browser reports a coarse primary pointer, which is typical for a tablet.\n- **Always on** enables touch selection in every larger layout.\n- **Off** leaves touch selection disabled in larger layouts.\n\nPhone layouts always provide touch selection. When touch selection is available, select an item from its More actions menu or touch and hold its row. Tap additional rows to add or remove them from the selection, then use the selection controls at the bottom of the pane for bulk actions.\n\n## Locate and Run Any Command\n\n1. Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e to open command mode.\n1. Type part of a command name.\n1. Choose the command to run.\n", "2.0": "+++\ntitle = \"Smart Navigation and the Quick Bar\"\n+++\n\nThe quick bar provides fast navigation, File Search, and commands from one shared control.\n\nThe quick bar has multiple modes:\n\n- Smart navigation with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e\n- File Search with \u003ckbd\u003e/\u003c/kbd\u003e\n- Command mode with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e\n\n## Jump to Any Directory with Smart Navigation\n\n1. Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e to open smart navigation.\n1. Type part of a directory name.\n1. Sambee lists matches across the current connection.\n1. Choose a match to open that directory.\n\n### Recent Directory History\n\nRecent directories appear before cache-based directory matches, including when the search box is empty. Choose a recent directory to switch to its connection and open the saved location. A directory that is both recent and present in the active connection's cache is shown once in Recent directories.\n\nTo remove only the selected item from Recent directories, press \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDelete\u003c/kbd\u003e. This removes history metadata; it never deletes the underlying directory or its contents.\n\nSambee records a directory after it opens successfully. History is private to your account. You can clear your directory history from **Settings** \u003e **File Browser** \u003e **Directory Navigation**.\n\n## Find Files with File Search\n\n1. Press \u003ckbd\u003e/\u003c/kbd\u003e when the file browser has keyboard focus.\n1. Type part of a filename.\n1. Review the separate Recent files and Current directory groups.\n1. Select a file and press \u003ckbd\u003eEnter\u003c/kbd\u003e to open it.\n\nFile Search doesn't build a global file index. It searches the files currently loaded in the active directory and your per-user recent-file history. A file that appears in both places is shown once in Recent files.\n\nUse modifiers with \u003ckbd\u003eEnter\u003c/kbd\u003e or a result click to choose how to open the selected file:\n\n- \u003ckbd\u003eCtrl\u003c/kbd\u003e opens it in the associated native application.\n- \u003ckbd\u003eShift\u003c/kbd\u003e opens the browser viewer picker.\n- \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e opens the native application picker.\n\nTo remove only a selected item from Recent files, press \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDelete\u003c/kbd\u003e. This removes history metadata; it never deletes the underlying file.\n\nRecent files are recorded when you attempt to open a regular file. History is private to your account and follows the configured retention and exclusion policy. The system verifies remote SMB targets and local Companion targets as regular files before keeping a history record.\n\nThe File Search settings show whether Sambee is using the built-in defaults or an administrator's saved system override. Administrators can reset an override to the built-in defaults. Lowering retention removes the oldest records immediately, and setting retention to zero clears history and prevents new records. Image, temporary, backup, and configured extension exclusions apply before a record is stored.\n\nIf a recent remote file no longer exists, Sambee removes its stale history entry after confirming that state. For local drives, Companion distinguishes a missing or no-longer-regular file from an unavailable drive; confirmed stale targets are removed, while unavailable, unpaired, or temporarily failing local drives keep their history for a later retry.\n\nYou can clear your own history from **Settings** \u003e **File Browser** \u003e **File Search**. Administrators can set retention, per-group result limits, and exclusion rules in **Settings** \u003e **File Search**. Add each extension exclusion as one literal extension; Sambee normalizes it, such as `TMP` to `.tmp`, and lets you remove it from the exclusion list.\n\n## Quick Bar Shortcut Hints\n\nChoose when shortcut hints appear in **Settings** \u003e **File Browser** \u003e **Shortcut hints**:\n\n- **Auto** shows hints on larger layouts and after you use a keyboard in the current compact-layout session.\n- **Always** shows hints in every layout.\n- **Never** hides the shortcut labels while keeping Quick Bar status information visible.\n\n## Desktop Mouse Selection\n\nOn desktop with touch selection off, click a file or folder name to open it, or click its icon to select it. Once an item is selected, the icons become selection controls and the pane's status bar shows the selected count. Click more icons to add or remove items. \u003ckbd\u003eShift\u003c/kbd\u003e-click an icon to add a range from the last selected item without losing earlier selections. \u003ckbd\u003eCtrl\u003c/kbd\u003e or \u003ckbd\u003eCmd\u003c/kbd\u003e with \u003ckbd\u003eShift\u003c/kbd\u003e also adds a range. Keyboard selection and icon selection share the same range anchor.\n\nClick a row outside its icon, click empty list space, or press \u003ckbd\u003eEscape\u003c/kbd\u003e to clear selection. The click that clears selection doesn't open a file; click again to open it. Sorting or starting File Search clears that pane's selection. Each pane keeps its own selection when you switch panes. Bulk actions use the selected items, while a focused item alone is not a selection.\n\n## Touch-Friendly File Selection\n\nChoose when touch-friendly file selection is available in **Settings** \u003e **File Browser** \u003e **File selection**. This keeps the desktop layout and toolbar on larger devices while making row selection easier to use by touch.\n\n- **Automatic** enables touch selection when the browser reports a coarse primary pointer, which is typical for a tablet.\n- **Always on** enables touch selection in every larger layout.\n- **Off** leaves touch selection disabled in larger layouts.\n\nPhone layouts always provide touch selection. When touch selection is available, select an item from its More actions menu or touch and hold its row. Tap additional rows to add or remove them from the selection, then use the selection controls at the bottom of the pane for bulk actions.\n\n## Locate and Run Any Command\n\n1. Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e to open command mode.\n1. Type part of a command name.\n1. Choose the command to run.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Smart Navigation and the Quick Bar\"\n+++\n\nThe quick bar is one of Sambee's core navigation features.\n\nIf you have used Visual Studio Code, the interaction model will feel familiar: one shared bar helps you navigate, filter, and run commands quickly.\n\nThe quick bar has multiple modes:\n\n- Smart navigation with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e\n- File list filtering with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e\n- Command mode with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e or \u003ckbd\u003eF1\u003c/kbd\u003e\n\n## Jump to Any Directory with Smart Navigation\n\n1. Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e to open smart navigation.\n1. Type part of a directory name.\n1. Sambee lists all matches across the current connection.\n1. Choose the match you want to jump to and open that directory immediately.\n\n## Filter Files in the Current Directory\n\n1. Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e to open the quick bar in file list filtering mode.\n1. Type part of a file or directory name.\n1. Sambee filters the file list to only those items matching your search term.\n\n## Locate and Run Any Command\n\n1. Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e or \u003ckbd\u003eF1\u003c/kbd\u003e to open the quick bar in command mode.\n1. Type part of the name of a command.\n1. Sambee lists all matching commands.\n1. Choose the command you want to run.\n", "0.8": "+++\ntitle = \"Smart Navigation and the Quick Bar\"\n+++\n\nThe quick bar is one of Sambee's core navigation features.\n\nIf you have used Visual Studio Code, the interaction model will feel familiar: one shared bar helps you navigate, filter, and run commands quickly.\n\nThe quick bar has multiple modes:\n\n- Smart navigation with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e\n- File list filtering with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e\n- Command mode with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e or \u003ckbd\u003eF1\u003c/kbd\u003e\n\n## Jump to Any Directory with Smart Navigation\n\n1. Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e to open smart navigation.\n1. Type part of a directory name.\n1. Sambee lists all matches across the current connection.\n1. Choose the match you want to jump to and open that directory immediately.\n\n## Filter Files in the Current Directory\n\n1. Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e to open the quick bar in file list filtering mode.\n1. Type part of a file or directory name.\n1. Sambee filters the file list to only those items matching your search term.\n\n## Locate and Run Any Command\n\n1. Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e or \u003ckbd\u003eF1\u003c/kbd\u003e to open the quick bar in command mode.\n1. Type part of the name of a command.\n1. Sambee lists all matching commands.\n1. Choose the command you want to run.\n", "0.9": "+++\ntitle = \"Smart Navigation and the Quick Bar\"\n+++\n\nThe quick bar is one of Sambee's core navigation features.\n\nIf you have used Visual Studio Code, the interaction model will feel familiar: one shared bar helps you navigate, filter, and run commands quickly.\n\nThe quick bar has multiple modes:\n\n- Smart navigation with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e\n- File list filtering with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e\n- Command mode with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e or \u003ckbd\u003eF1\u003c/kbd\u003e\n\n## Jump to Any Directory with Smart Navigation\n\n1. Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e to open smart navigation.\n1. Type part of a directory name.\n1. Sambee lists all matches across the current connection.\n1. Choose the match you want to jump to and open that directory immediately.\n\n## Filter Files in the Current Directory\n\n1. Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e to open the quick bar in file list filtering mode.\n1. Type part of a file or directory name.\n1. Sambee filters the file list to only those items matching your search term.\n\n## Locate and Run Any Command\n\n1. Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e or \u003ckbd\u003eF1\u003c/kbd\u003e to open the quick bar in command mode.\n1. Type part of the name of a command.\n1. Sambee lists all matching commands.\n1. Choose the command you want to run.\n", "1.0": "+++\ntitle = \"Smart Navigation and the Quick Bar\"\n+++\n\nThe quick bar provides fast navigation, File Search, and commands from one shared control.\n\nThe quick bar has multiple modes:\n\n- Smart navigation with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e\n- File Search with \u003ckbd\u003e/\u003c/kbd\u003e\n- Command mode with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e\n\n## Jump to Any Directory with Smart Navigation\n\n1. Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e to open smart navigation.\n1. Type part of a directory name.\n1. Sambee lists matches across the current connection.\n1. Choose a match to open that directory.\n\n### Recent Directory History\n\nRecent directories appear before cache-based directory matches, including when the search box is empty. Choose a recent directory to switch to its connection and open the saved location. A directory that is both recent and present in the active connection's cache is shown once in Recent directories.\n\nTo remove only the selected item from Recent directories, press \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDelete\u003c/kbd\u003e. This removes history metadata; it never deletes the underlying directory or its contents.\n\nSambee records a directory after it opens successfully. History is private to your account. You can clear your directory history from **Settings** \u003e **File Browser** \u003e **Directory Navigation**.\n\n## Find Files with File Search\n\n1. Press \u003ckbd\u003e/\u003c/kbd\u003e when the file browser has keyboard focus.\n1. Type part of a filename.\n1. Review the separate Recent files and Current directory groups.\n1. Select a file and press \u003ckbd\u003eEnter\u003c/kbd\u003e to open it.\n\nFile Search doesn't build a global file index. It searches the files currently loaded in the active directory and your per-user recent-file history. A file that appears in both places is shown once in Recent files.\n\nUse modifiers with \u003ckbd\u003eEnter\u003c/kbd\u003e or a result click to choose how to open the selected file:\n\n- \u003ckbd\u003eCtrl\u003c/kbd\u003e opens it in the associated native application.\n- \u003ckbd\u003eShift\u003c/kbd\u003e opens the browser viewer picker.\n- \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e opens the native application picker.\n\nTo remove only a selected item from Recent files, press \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDelete\u003c/kbd\u003e. This removes history metadata; it never deletes the underlying file.\n\nRecent files are recorded when you attempt to open a regular file. History is private to your account and follows the configured retention and exclusion policy. The system verifies remote SMB targets and local Companion targets as regular files before keeping a history record.\n\nThe File Search settings show whether Sambee is using the built-in defaults or an administrator's saved system override. Administrators can reset an override to the built-in defaults. Lowering retention removes the oldest records immediately, and setting retention to zero clears history and prevents new records. Image, temporary, backup, and configured extension exclusions apply before a record is stored.\n\nIf a recent remote file no longer exists, Sambee removes its stale history entry after confirming that state. For local drives, Companion distinguishes a missing or no-longer-regular file from an unavailable drive; confirmed stale targets are removed, while unavailable, unpaired, or temporarily failing local drives keep their history for a later retry.\n\nYou can clear your own history from **Settings** \u003e **File Browser** \u003e **File Search**. Administrators can set retention, per-group result limits, and exclusion rules in **Settings** \u003e **File Search**. Add each extension exclusion as one literal extension; Sambee normalizes it, such as `TMP` to `.tmp`, and lets you remove it from the exclusion list.\n\n## Quick Bar Shortcut Hints\n\nChoose when shortcut hints appear in **Settings** \u003e **File Browser** \u003e **Shortcut hints**:\n\n- **Auto** shows hints on larger layouts and after you use a keyboard in the current compact-layout session.\n- **Always** shows hints in every layout.\n- **Never** hides the shortcut labels while keeping Quick Bar status information visible.\n\n## Touch-Friendly File Selection\n\nChoose when touch-friendly file selection is available in **Settings** \u003e **File Browser** \u003e **File selection**. This keeps the desktop layout and toolbar on larger devices while making row selection easier to use by touch.\n\n- **Automatic** enables touch selection when the browser reports a coarse primary pointer, which is typical for a tablet.\n- **Always on** enables touch selection in every larger layout.\n- **Off** leaves touch selection disabled in larger layouts.\n\nPhone layouts always provide touch selection. When touch selection is available, select an item from its More actions menu or touch and hold its row. Tap additional rows to add or remove them from the selection, then use the selection controls at the bottom of the pane for bulk actions.\n\n## Locate and Run Any Command\n\n1. Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e to open command mode.\n1. Type part of a command name.\n1. Choose the command to run.\n", "2.0": "+++\ntitle = \"Smart Navigation and the Quick Bar\"\n+++\n\nThe quick bar provides fast navigation, File Search, and commands from one shared control.\n\nThe quick bar has multiple modes:\n\n- Smart navigation with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e\n- File Search with \u003ckbd\u003e/\u003c/kbd\u003e\n- Command mode with \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e\n\n## Jump to Any Directory with Smart Navigation\n\n1. Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e to open smart navigation.\n1. Type part of a directory name.\n1. Sambee lists matches across the current connection.\n1. Choose a match to open that directory.\n\n### Recent Directory History\n\nRecent directories appear before cache-based directory matches, including when the search box is empty. Choose a recent directory to switch to its connection and open the saved location. A directory that is both recent and present in the active connection's cache is shown once in Recent directories.\n\nTo remove only the selected item from Recent directories, press \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDelete\u003c/kbd\u003e. This removes history metadata; it never deletes the underlying directory or its contents.\n\nSambee records a directory after it opens successfully. History is private to your account. You can clear your directory history from **Settings** \u003e **File Browser** \u003e **Directory Navigation**.\n\n## Find Files with File Search\n\n1. Press \u003ckbd\u003e/\u003c/kbd\u003e when the file browser has keyboard focus.\n1. Type part of a filename.\n1. Review the separate Recent files and Current directory groups.\n1. Select a file and press \u003ckbd\u003eEnter\u003c/kbd\u003e to open it.\n\nFile Search doesn't build a global file index. It searches the files currently loaded in the active directory and your per-user recent-file history. A file that appears in both places is shown once in Recent files.\n\nUse modifiers with \u003ckbd\u003eEnter\u003c/kbd\u003e or a result click to choose how to open the selected file:\n\n- \u003ckbd\u003eCtrl\u003c/kbd\u003e opens it in the associated native application.\n- \u003ckbd\u003eShift\u003c/kbd\u003e opens the browser viewer picker.\n- \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e opens the native application picker.\n\nTo remove only a selected item from Recent files, press \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDelete\u003c/kbd\u003e. This removes history metadata; it never deletes the underlying file.\n\nRecent files are recorded when you attempt to open a regular file. History is private to your account and follows the configured retention and exclusion policy. The system verifies remote SMB targets and local Companion targets as regular files before keeping a history record.\n\nThe File Search settings show whether Sambee is using the built-in defaults or an administrator's saved system override. Administrators can reset an override to the built-in defaults. Lowering retention removes the oldest records immediately, and setting retention to zero clears history and prevents new records. Image, temporary, backup, and configured extension exclusions apply before a record is stored.\n\nIf a recent remote file no longer exists, Sambee removes its stale history entry after confirming that state. For local drives, Companion distinguishes a missing or no-longer-regular file from an unavailable drive; confirmed stale targets are removed, while unavailable, unpaired, or temporarily failing local drives keep their history for a later retry.\n\nYou can clear your own history from **Settings** \u003e **File Browser** \u003e **File Search**. Administrators can set retention, per-group result limits, and exclusion rules in **Settings** \u003e **File Search**. Add each extension exclusion as one literal extension; Sambee normalizes it, such as `TMP` to `.tmp`, and lets you remove it from the exclusion list.\n\n## Quick Bar Shortcut Hints\n\nChoose when shortcut hints appear in **Settings** \u003e **File Browser** \u003e **Shortcut hints**:\n\n- **Auto** shows hints on larger layouts and after you use a keyboard in the current compact-layout session.\n- **Always** shows hints in every layout.\n- **Never** hides the shortcut labels while keeping Quick Bar status information visible.\n\n## Desktop Mouse Selection\n\nOn desktop with touch selection off, click a file or folder name to open it, or click its icon to select it. Once an item is selected, the icons become selection controls and the pane's status bar shows the selected count. Click more icons to add or remove items. \u003ckbd\u003eShift\u003c/kbd\u003e-click an icon to add a range from the last selected item without losing earlier selections. \u003ckbd\u003eCtrl\u003c/kbd\u003e or \u003ckbd\u003eCmd\u003c/kbd\u003e with \u003ckbd\u003eShift\u003c/kbd\u003e also adds a range. Keyboard selection and icon selection share the same range anchor.\n\nClick a row outside its icon, click empty list space, or press \u003ckbd\u003eEscape\u003c/kbd\u003e to clear selection. The click that clears selection doesn't open a file; click again to open it. Sorting or starting File Search clears that pane's selection. Each pane keeps its own selection when you switch panes. Bulk actions use the selected items, while a focused item alone is not a selection.\n\n## Touch-Friendly File Selection\n\nChoose when touch-friendly file selection is available in **Settings** \u003e **File Browser** \u003e **File selection**. This keeps the desktop layout and toolbar on larger devices while making row selection easier to use by touch.\n\n- **Automatic** enables touch selection when the browser reports a coarse primary pointer, which is typical for a tablet.\n- **Always on** enables touch selection in every larger layout.\n- **Off** leaves touch selection disabled in larger layouts.\n\nPhone layouts always provide touch selection. When touch selection is available, select an item from its More actions menu or touch and hold its row. Tap additional rows to add or remove them from the selection, then use the selection controls at the bottom of the pane for bulk actions.\n\n## Locate and Run Any Command\n\n1. Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e to open command mode.\n1. Type part of a command name.\n1. Choose the command to run.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:user-guide/browsing-and-navigation/dual-pane-mode", "parent_id": "section:user-guide/browsing-and-navigation", "depth": 2, "kind": "page", "label": "dual-pane-mode", "title": "Dual Pane Mode", "path": "user-guide/browsing-and-navigation/dual-pane-mode", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "branched", "source_version": "0.7", "diff_added": 5, "diff_removed": 1}, "2.0": {"state": "branched", "source_version": "1.0", "diff_added": 13, "diff_removed": 2}}, "content_versions": {"0.7": "+++\ntitle = \"Dual-Pane Mode\"\n+++\n\nSambee's dual-pane mode shows the contents of two directories next to each other. This layout was popularized by Norton Commander and later Total Commander. It makes it easier to move or copy files between directories and to compare two directories visually.\n\n## Work in Dual-Pane Mode\n\nTo switch between single-pane and dual-pane mode:\n\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e to switch from single-pane to dual-pane mode and back.\n\nTo move focus between the left and right panes:\n\n- Use \u003ckbd\u003eTab\u003c/kbd\u003e to move the input focus between the left and right pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e to focus the left pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e to focus the right pane.\n\nTo copy or move files and directories:\n\n- Press \u003ckbd\u003eF5\u003c/kbd\u003e to copy the currently selected items in the active pane to the location in the inactive pane.\n- Press \u003ckbd\u003eF6\u003c/kbd\u003e to move instead of copying.\n\n{{\u003c admonition type=\"note\" \u003e}}\nCopying files and directories between different SMB connections, different local drives, and SMB connections and local drives is supported. For a move across those boundaries, Sambee creates the destination but retains the source when it cannot safely verify and delete that source. Check both panes before deleting a retained source yourself.\n{{\u003c /admonition \u003e}}\n\n## Extract Selected ZIP Members\n\nWhen the active pane shows a ZIP archive, select the files or directories to extract and press \u003ckbd\u003eF5\u003c/kbd\u003e. Sambee extracts the selected members into the physical location in the inactive pane. Selecting a directory extracts all of its contents, including empty directories.\n\nArchive members can't be moved. \u003ckbd\u003eF6\u003c/kbd\u003e stays unavailable in a ZIP archive pane and doesn't modify the archive.\n\n## Requirements\n\n- Dual-pane mode is currently a desktop-only feature (i.e., not available on mobile due to screen size limitations).\n", "0.8": "+++\ntitle = \"Dual-Pane Mode\"\n+++\n\nSambee's dual-pane mode shows the contents of two directories next to each other. This layout was popularized by Norton Commander and later Total Commander. It makes it easier to move or copy files between directories and to compare two directories visually.\n\n## Work in Dual-Pane Mode\n\nTo switch between single-pane and dual-pane mode:\n\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e to switch from single-pane to dual-pane mode and back.\n\nTo move focus between the left and right panes:\n\n- Use \u003ckbd\u003eTab\u003c/kbd\u003e to move the input focus between the left and right pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e to focus the left pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e to focus the right pane.\n\nTo copy or move files and directories:\n\n- Press \u003ckbd\u003eF5\u003c/kbd\u003e to copy the currently selected items in the active pane to the location in the inactive pane.\n- Press \u003ckbd\u003eF6\u003c/kbd\u003e to move instead of copying.\n\n{{\u003c admonition type=\"note\" \u003e}}\nCopying files and directories between different SMB connections, different local drives, and SMB connections and local drives is supported. For a move across those boundaries, Sambee creates the destination but retains the source when it cannot safely verify and delete that source. Check both panes before deleting a retained source yourself.\n{{\u003c /admonition \u003e}}\n\n## Extract Selected ZIP Members\n\nWhen the active pane shows a ZIP archive, select the files or directories to extract and press \u003ckbd\u003eF5\u003c/kbd\u003e. Sambee extracts the selected members into the physical location in the inactive pane. Selecting a directory extracts all of its contents, including empty directories.\n\nArchive members can't be moved. \u003ckbd\u003eF6\u003c/kbd\u003e stays unavailable in a ZIP archive pane and doesn't modify the archive.\n\n## Requirements\n\n- Dual-pane mode is currently a desktop-only feature (i.e., not available on mobile due to screen size limitations).\n", "0.9": "+++\ntitle = \"Dual-Pane Mode\"\n+++\n\nSambee's dual-pane mode shows the contents of two directories next to each other. This layout was popularized by Norton Commander and later Total Commander. It makes it easier to move or copy files between directories and to compare two directories visually.\n\n## Work in Dual-Pane Mode\n\nTo switch between single-pane and dual-pane mode:\n\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e to switch from single-pane to dual-pane mode and back.\n\nTo move focus between the left and right panes:\n\n- Use \u003ckbd\u003eTab\u003c/kbd\u003e to move the input focus between the left and right pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e to focus the left pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e to focus the right pane.\n\nTo copy or move files and directories:\n\n- Press \u003ckbd\u003eF5\u003c/kbd\u003e to copy the currently selected items in the active pane to the location in the inactive pane.\n- Press \u003ckbd\u003eF6\u003c/kbd\u003e to move instead of copying.\n\n{{\u003c admonition type=\"note\" \u003e}}\nCopying files and directories between different SMB connections, different local drives, and SMB connections and local drives is supported. For a move across those boundaries, Sambee creates the destination but retains the source when it cannot safely verify and delete that source. Check both panes before deleting a retained source yourself.\n{{\u003c /admonition \u003e}}\n\n## Extract Selected ZIP Members\n\nWhen the active pane shows a ZIP archive, select the files or directories to extract and press \u003ckbd\u003eF5\u003c/kbd\u003e. Sambee extracts the selected members into the physical location in the inactive pane. Selecting a directory extracts all of its contents, including empty directories.\n\nArchive members can't be moved. \u003ckbd\u003eF6\u003c/kbd\u003e stays unavailable in a ZIP archive pane and doesn't modify the archive.\n\n## Requirements\n\n- Dual-pane mode is currently a desktop-only feature (i.e., not available on mobile due to screen size limitations).\n", "1.0": "+++\ntitle = \"Dual-Pane Mode\"\n+++\n\nSambee's dual-pane mode shows the contents of two directories next to each other. This layout was popularized by Norton Commander and later Total Commander. It makes it easier to move or copy files between directories and to compare two directories visually.\n\n## Work in Dual-Pane Mode\n\nTo switch between single-pane and dual-pane mode:\n\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e to switch from single-pane to dual-pane mode and back.\n\nTo move focus between the left and right panes:\n\n- Use \u003ckbd\u003eTab\u003c/kbd\u003e to move the input focus between the left and right pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e to focus the left pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e to focus the right pane.\n\nTo copy or move files and directories:\n\n- Press \u003ckbd\u003eF5\u003c/kbd\u003e to copy the currently selected items in the active pane to the location in the inactive pane.\n- Press \u003ckbd\u003eF6\u003c/kbd\u003e to move instead of copying.\n\n{{\u003c admonition type=\"note\" \u003e}}\nYou can copy and move files and directories between different SMB connections, different local drives, and SMB connections and local drives. Sambee completes the destination copy before it removes the original during a move.\n{{\u003c /admonition \u003e}}\n\nWhile a copy or move is in progress, the dialog shows its progress. Select Cancel to stop an active transfer. If a destination item already exists, use the Target already exists dialog to skip it or choose a different name.\n\nIf Sambee creates the destination for a move but can't remove the original, it reports the partial move and keeps the original in place. Review both panes before trying the move again.\n\n## Extract Selected ZIP Members\n\nWhen the active pane shows a ZIP archive, select the files or directories to extract and press \u003ckbd\u003eF5\u003c/kbd\u003e. Sambee extracts the selected members into the physical location in the inactive pane. Selecting a directory extracts all of its contents, including empty directories.\n\nArchive members can't be moved. \u003ckbd\u003eF6\u003c/kbd\u003e stays unavailable in a ZIP archive pane and doesn't modify the archive.\n\n## Requirements\n\n- Dual-pane mode is currently a desktop-only feature (i.e., not available on mobile due to screen size limitations).\n", "2.0": "+++\ntitle = \"Dual-Pane Mode\"\n+++\n\nSambee's dual-pane mode shows the contents of two directories next to each other. This layout was popularized by Norton Commander and later Total Commander. It makes it easier to move or copy files between directories and to compare two directories visually.\n\n## Work in Dual-Pane Mode\n\nTo switch between single-pane and dual-pane mode:\n\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e to switch from single-pane to dual-pane mode and back.\n\nTo move focus between the left and right panes:\n\n- Use \u003ckbd\u003eTab\u003c/kbd\u003e to move the input focus between the left and right pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e to focus the left pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e to focus the right pane.\n\nTo copy or move files and directories:\n\n- Press \u003ckbd\u003eF5\u003c/kbd\u003e to copy the currently selected items in the active pane to the location in the inactive pane.\n- Press \u003ckbd\u003eF6\u003c/kbd\u003e to move instead of copying.\n\n{{\u003c admonition type=\"note\" \u003e}}\nYou can copy and move files and directories between different SMB connections, different local drives, and SMB connections and local drives. Sambee completes the destination copy before it removes the original during a move.\n{{\u003c /admonition \u003e}}\n\nWhile a copy or move is in progress, the dialog shows its progress. Select Cancel to stop an active transfer. If a destination file already exists, use the Target already exists dialog to skip it, overwrite it, overwrite it only when the source is newer, or choose a different name. Apply the choice to remaining conflicts when appropriate. Directories with the same name are merged without removing destination-only entries. A file can't replace a directory or vice versa.\n\n### Partial Moves and Cancellation\n\nTransfers between SMB connections publish a complete destination file before removing the source. An authorized overwrite replaces the destination atomically, without first deleting the visible file. During a move, Sambee protects the opened source from concurrent writes and renames; an incompatible open writer can prevent the transfer from starting.\n\n- Cancelling before publication leaves both locations unchanged for that file.\n- Cancelling after publication but before source deletion keeps the destination and reports that the source was retained.\n- A rejected source deletion also keeps the destination and reports the retained source.\n- If a deletion acknowledgement or final close is lost, Sambee reports uncertainty about the source while retaining the confirmed destination. Cancellation after deletion has started can't guarantee that the source remains.\n\nSambee refreshes both panes after a batch. A directory can be partially moved even when its overall result is cancelled, failed, or uncertain. Earlier completed files and confirmed replacements aren't rolled back. An uncertain child stops the remaining batch; a retained-source warning can allow later items to continue. Each selected directory keeps the destination parent captured when the confirmation dialog opened.\n\nAfter a partial or uncertain move, inspect both locations before starting another operation. Don't assume the source was retained when its deletion couldn't be confirmed. The completed dialog offers Close rather than repeating the batch. If source validation fails after a copy was published, the destination remains and Sambee reports the validation failure.\n\n## Extract Selected ZIP Members\n\nWhen the active pane shows a ZIP archive, select the files or directories to extract and press \u003ckbd\u003eF5\u003c/kbd\u003e. Sambee extracts the selected members into the physical location in the inactive pane. Selecting a directory extracts all of its contents, including empty directories.\n\nArchive members can't be moved. \u003ckbd\u003eF6\u003c/kbd\u003e stays unavailable in a ZIP archive pane and doesn't modify the archive.\n\n## Requirements\n\n- Dual-pane mode is currently a desktop-only feature (i.e., not available on mobile due to screen size limitations).\n"}, "page_contents": {"0.7": "+++\ntitle = \"Dual-Pane Mode\"\n+++\n\nSambee's dual-pane mode shows the contents of two directories next to each other. This layout was popularized by Norton Commander and later Total Commander. It makes it easier to move or copy files between directories and to compare two directories visually.\n\n## Work in Dual-Pane Mode\n\nTo switch between single-pane and dual-pane mode:\n\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e to switch from single-pane to dual-pane mode and back.\n\nTo move focus between the left and right panes:\n\n- Use \u003ckbd\u003eTab\u003c/kbd\u003e to move the input focus between the left and right pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e to focus the left pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e to focus the right pane.\n\nTo copy or move files and directories:\n\n- Press \u003ckbd\u003eF5\u003c/kbd\u003e to copy the currently selected items in the active pane to the location in the inactive pane.\n- Press \u003ckbd\u003eF6\u003c/kbd\u003e to move instead of copying.\n\n{{\u003c admonition type=\"note\" \u003e}}\nCopying files and directories between different SMB connections, different local drives, and SMB connections and local drives is supported. For a move across those boundaries, Sambee creates the destination but retains the source when it cannot safely verify and delete that source. Check both panes before deleting a retained source yourself.\n{{\u003c /admonition \u003e}}\n\n## Extract Selected ZIP Members\n\nWhen the active pane shows a ZIP archive, select the files or directories to extract and press \u003ckbd\u003eF5\u003c/kbd\u003e. Sambee extracts the selected members into the physical location in the inactive pane. Selecting a directory extracts all of its contents, including empty directories.\n\nArchive members can't be moved. \u003ckbd\u003eF6\u003c/kbd\u003e stays unavailable in a ZIP archive pane and doesn't modify the archive.\n\n## Requirements\n\n- Dual-pane mode is currently a desktop-only feature (i.e., not available on mobile due to screen size limitations).\n", "0.8": "+++\ntitle = \"Dual-Pane Mode\"\n+++\n\nSambee's dual-pane mode shows the contents of two directories next to each other. This layout was popularized by Norton Commander and later Total Commander. It makes it easier to move or copy files between directories and to compare two directories visually.\n\n## Work in Dual-Pane Mode\n\nTo switch between single-pane and dual-pane mode:\n\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e to switch from single-pane to dual-pane mode and back.\n\nTo move focus between the left and right panes:\n\n- Use \u003ckbd\u003eTab\u003c/kbd\u003e to move the input focus between the left and right pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e to focus the left pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e to focus the right pane.\n\nTo copy or move files and directories:\n\n- Press \u003ckbd\u003eF5\u003c/kbd\u003e to copy the currently selected items in the active pane to the location in the inactive pane.\n- Press \u003ckbd\u003eF6\u003c/kbd\u003e to move instead of copying.\n\n{{\u003c admonition type=\"note\" \u003e}}\nCopying files and directories between different SMB connections, different local drives, and SMB connections and local drives is supported. For a move across those boundaries, Sambee creates the destination but retains the source when it cannot safely verify and delete that source. Check both panes before deleting a retained source yourself.\n{{\u003c /admonition \u003e}}\n\n## Extract Selected ZIP Members\n\nWhen the active pane shows a ZIP archive, select the files or directories to extract and press \u003ckbd\u003eF5\u003c/kbd\u003e. Sambee extracts the selected members into the physical location in the inactive pane. Selecting a directory extracts all of its contents, including empty directories.\n\nArchive members can't be moved. \u003ckbd\u003eF6\u003c/kbd\u003e stays unavailable in a ZIP archive pane and doesn't modify the archive.\n\n## Requirements\n\n- Dual-pane mode is currently a desktop-only feature (i.e., not available on mobile due to screen size limitations).\n", "0.9": "+++\ntitle = \"Dual-Pane Mode\"\n+++\n\nSambee's dual-pane mode shows the contents of two directories next to each other. This layout was popularized by Norton Commander and later Total Commander. It makes it easier to move or copy files between directories and to compare two directories visually.\n\n## Work in Dual-Pane Mode\n\nTo switch between single-pane and dual-pane mode:\n\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e to switch from single-pane to dual-pane mode and back.\n\nTo move focus between the left and right panes:\n\n- Use \u003ckbd\u003eTab\u003c/kbd\u003e to move the input focus between the left and right pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e to focus the left pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e to focus the right pane.\n\nTo copy or move files and directories:\n\n- Press \u003ckbd\u003eF5\u003c/kbd\u003e to copy the currently selected items in the active pane to the location in the inactive pane.\n- Press \u003ckbd\u003eF6\u003c/kbd\u003e to move instead of copying.\n\n{{\u003c admonition type=\"note\" \u003e}}\nCopying files and directories between different SMB connections, different local drives, and SMB connections and local drives is supported. For a move across those boundaries, Sambee creates the destination but retains the source when it cannot safely verify and delete that source. Check both panes before deleting a retained source yourself.\n{{\u003c /admonition \u003e}}\n\n## Extract Selected ZIP Members\n\nWhen the active pane shows a ZIP archive, select the files or directories to extract and press \u003ckbd\u003eF5\u003c/kbd\u003e. Sambee extracts the selected members into the physical location in the inactive pane. Selecting a directory extracts all of its contents, including empty directories.\n\nArchive members can't be moved. \u003ckbd\u003eF6\u003c/kbd\u003e stays unavailable in a ZIP archive pane and doesn't modify the archive.\n\n## Requirements\n\n- Dual-pane mode is currently a desktop-only feature (i.e., not available on mobile due to screen size limitations).\n", "1.0": "+++\ntitle = \"Dual-Pane Mode\"\n+++\n\nSambee's dual-pane mode shows the contents of two directories next to each other. This layout was popularized by Norton Commander and later Total Commander. It makes it easier to move or copy files between directories and to compare two directories visually.\n\n## Work in Dual-Pane Mode\n\nTo switch between single-pane and dual-pane mode:\n\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e to switch from single-pane to dual-pane mode and back.\n\nTo move focus between the left and right panes:\n\n- Use \u003ckbd\u003eTab\u003c/kbd\u003e to move the input focus between the left and right pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e to focus the left pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e to focus the right pane.\n\nTo copy or move files and directories:\n\n- Press \u003ckbd\u003eF5\u003c/kbd\u003e to copy the currently selected items in the active pane to the location in the inactive pane.\n- Press \u003ckbd\u003eF6\u003c/kbd\u003e to move instead of copying.\n\n{{\u003c admonition type=\"note\" \u003e}}\nYou can copy and move files and directories between different SMB connections, different local drives, and SMB connections and local drives. Sambee completes the destination copy before it removes the original during a move.\n{{\u003c /admonition \u003e}}\n\nWhile a copy or move is in progress, the dialog shows its progress. Select Cancel to stop an active transfer. If a destination item already exists, use the Target already exists dialog to skip it or choose a different name.\n\nIf Sambee creates the destination for a move but can't remove the original, it reports the partial move and keeps the original in place. Review both panes before trying the move again.\n\n## Extract Selected ZIP Members\n\nWhen the active pane shows a ZIP archive, select the files or directories to extract and press \u003ckbd\u003eF5\u003c/kbd\u003e. Sambee extracts the selected members into the physical location in the inactive pane. Selecting a directory extracts all of its contents, including empty directories.\n\nArchive members can't be moved. \u003ckbd\u003eF6\u003c/kbd\u003e stays unavailable in a ZIP archive pane and doesn't modify the archive.\n\n## Requirements\n\n- Dual-pane mode is currently a desktop-only feature (i.e., not available on mobile due to screen size limitations).\n", "2.0": "+++\ntitle = \"Dual-Pane Mode\"\n+++\n\nSambee's dual-pane mode shows the contents of two directories next to each other. This layout was popularized by Norton Commander and later Total Commander. It makes it easier to move or copy files between directories and to compare two directories visually.\n\n## Work in Dual-Pane Mode\n\nTo switch between single-pane and dual-pane mode:\n\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e to switch from single-pane to dual-pane mode and back.\n\nTo move focus between the left and right panes:\n\n- Use \u003ckbd\u003eTab\u003c/kbd\u003e to move the input focus between the left and right pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e to focus the left pane.\n- Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e to focus the right pane.\n\nTo copy or move files and directories:\n\n- Press \u003ckbd\u003eF5\u003c/kbd\u003e to copy the currently selected items in the active pane to the location in the inactive pane.\n- Press \u003ckbd\u003eF6\u003c/kbd\u003e to move instead of copying.\n\n{{\u003c admonition type=\"note\" \u003e}}\nYou can copy and move files and directories between different SMB connections, different local drives, and SMB connections and local drives. Sambee completes the destination copy before it removes the original during a move.\n{{\u003c /admonition \u003e}}\n\nWhile a copy or move is in progress, the dialog shows its progress. Select Cancel to stop an active transfer. If a destination file already exists, use the Target already exists dialog to skip it, overwrite it, overwrite it only when the source is newer, or choose a different name. Apply the choice to remaining conflicts when appropriate. Directories with the same name are merged without removing destination-only entries. A file can't replace a directory or vice versa.\n\n### Partial Moves and Cancellation\n\nTransfers between SMB connections publish a complete destination file before removing the source. An authorized overwrite replaces the destination atomically, without first deleting the visible file. During a move, Sambee protects the opened source from concurrent writes and renames; an incompatible open writer can prevent the transfer from starting.\n\n- Cancelling before publication leaves both locations unchanged for that file.\n- Cancelling after publication but before source deletion keeps the destination and reports that the source was retained.\n- A rejected source deletion also keeps the destination and reports the retained source.\n- If a deletion acknowledgement or final close is lost, Sambee reports uncertainty about the source while retaining the confirmed destination. Cancellation after deletion has started can't guarantee that the source remains.\n\nSambee refreshes both panes after a batch. A directory can be partially moved even when its overall result is cancelled, failed, or uncertain. Earlier completed files and confirmed replacements aren't rolled back. An uncertain child stops the remaining batch; a retained-source warning can allow later items to continue. Each selected directory keeps the destination parent captured when the confirmation dialog opened.\n\nAfter a partial or uncertain move, inspect both locations before starting another operation. Don't assume the source was retained when its deletion couldn't be confirmed. The completed dialog offers Close rather than repeating the batch. If source validation fails after a copy was published, the destination remains and Sambee reports the validation failure.\n\n## Extract Selected ZIP Members\n\nWhen the active pane shows a ZIP archive, select the files or directories to extract and press \u003ckbd\u003eF5\u003c/kbd\u003e. Sambee extracts the selected members into the physical location in the inactive pane. Selecting a directory extracts all of its contents, including empty directories.\n\nArchive members can't be moved. \u003ckbd\u003eF6\u003c/kbd\u003e stays unavailable in a ZIP archive pane and doesn't modify the archive.\n\n## Requirements\n\n- Dual-pane mode is currently a desktop-only feature (i.e., not available on mobile due to screen size limitations).\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:user-guide/browsing-and-navigation/keyboard-navigation-and-shortcuts", "parent_id": "section:user-guide/browsing-and-navigation", "depth": 2, "kind": "page", "label": "keyboard-navigation-and-shortcuts", "title": "Keyboard Navigation And Shortcuts", "path": "user-guide/browsing-and-navigation/keyboard-navigation-and-shortcuts", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "branched", "source_version": "0.7", "diff_added": 37, "diff_removed": 4}, "2.0": {"state": "inherited", "source_version": "1.0"}}, "content_versions": {"0.7": "+++\ntitle = \"Keyboard Navigation and Shortcuts\"\n+++\n\nKeyboard navigation is a first-class part of Sambee.\n\n## Keyboard-First Principles\n\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many file browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n- Safety still wins: Shortcuts that would be unsafe in text fields, dialogs, or incompatible states are intentionally blocked.\n\nIf you want the live in-app list, press \u003ckbd\u003e?\u003c/kbd\u003e while using Sambee.\n\n## File List and Main UI\n\nUse these shortcuts when the main file list or browser shell has focus.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eDown\u003c/kbd\u003e | Move to the previous or next row in the current file list |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last visible item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move up or down by a page in the current list |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file or enter the focused directory |\n| \u003ckbd\u003eBackspace\u003c/kbd\u003e | Go up to the parent directory |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Open the connection selector |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Open smart navigation |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Filter the current directory in the active pane |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e / \u003ckbd\u003eF1\u003c/kbd\u003e | Open commands |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e,\u003c/kbd\u003e | Open settings |\n| \u003ckbd\u003e?\u003c/kbd\u003e | Show keyboard shortcuts help |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Refresh the current file list |\n| \u003ckbd\u003eF2\u003c/kbd\u003e | Rename the focused item |\n| \u003ckbd\u003eDel\u003c/kbd\u003e | Delete the focused item |\n| \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new directory |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file in the companion app |\n\n## Selection and Dual-Pane Workflows\n\nThese shortcuts matter most when you are working keyboard-first across one or two panes.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eIns\u003c/kbd\u003e or \u003ckbd\u003eSpace\u003c/kbd\u003e | Toggle selection on the focused item and move down |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Extend selection upward or downward |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eA\u003c/kbd\u003e | Select all items in the current list |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e | Toggle dual-pane mode |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e / \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e | Focus the left or right pane |\n| \u003ckbd\u003eTab\u003c/kbd\u003e | Move focus to the other pane |\n| \u003ckbd\u003eF5\u003c/kbd\u003e / \u003ckbd\u003eF6\u003c/kbd\u003e | Copy or move selected items to the other pane |\n\n## Viewers\n\nViewers share a common keyboard model for closing, searching, paging, and visual controls.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the viewer |\n| \u003ckbd\u003eD\u003c/kbd\u003e | Download the current file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search inside supported viewers |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last page or item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move to the previous or next page |\n| \u003ckbd\u003eLeft\u003c/kbd\u003e / \u003ckbd\u003eRight\u003c/kbd\u003e | Move to the previous or next page or item |\n| \u003ckbd\u003e+\u003c/kbd\u003e / \u003ckbd\u003e-\u003c/kbd\u003e | Zoom in or out |\n| \u003ckbd\u003e0\u003c/kbd\u003e | Reset zoom |\n| \u003ckbd\u003eR\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Rotate right or left |\n| \u003ckbd\u003eF\u003c/kbd\u003e | Toggle fullscreen |\n\nSome viewer shortcuts depend on the file type. For example, search applies to searchable viewers, and page navigation applies to paged or gallery-style viewers.\n\n## Markdown Editor\n\nMarkdown files build on the shared viewer shortcuts and add editor-specific formatting actions.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eE\u003c/kbd\u003e | Switch a Markdown file from viewing to editing |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e | Save the current Markdown file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search in the current Markdown content |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Create a link |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eT\u003c/kbd\u003e | Insert a table |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Insert a thematic break |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Apply inline code |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Insert a code block |\n| \u003ckbd\u003eF\u003c/kbd\u003e | Toggle fullscreen in the Markdown viewer |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the Markdown viewer |\n\n## When to Use the Built-In Shortcut Help\n\nThis page summarizes the most useful keyboard shortcuts by UI area.\n\nUse the built-in shortcuts help when you want the live in-app list for your current screen, or when you want a quick reminder without leaving the file browser.\n", "0.8": "+++\ntitle = \"Keyboard Navigation and Shortcuts\"\n+++\n\nKeyboard navigation is a first-class part of Sambee.\n\n## Keyboard-First Principles\n\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many file browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n- Safety still wins: Shortcuts that would be unsafe in text fields, dialogs, or incompatible states are intentionally blocked.\n\nIf you want the live in-app list, press \u003ckbd\u003e?\u003c/kbd\u003e while using Sambee.\n\n## File List and Main UI\n\nUse these shortcuts when the main file list or browser shell has focus.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eDown\u003c/kbd\u003e | Move to the previous or next row in the current file list |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last visible item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move up or down by a page in the current list |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file or enter the focused directory |\n| \u003ckbd\u003eBackspace\u003c/kbd\u003e | Go up to the parent directory |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Open the connection selector |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Open smart navigation |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Filter the current directory in the active pane |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e / \u003ckbd\u003eF1\u003c/kbd\u003e | Open commands |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e,\u003c/kbd\u003e | Open settings |\n| \u003ckbd\u003e?\u003c/kbd\u003e | Show keyboard shortcuts help |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Refresh the current file list |\n| \u003ckbd\u003eF2\u003c/kbd\u003e | Rename the focused item |\n| \u003ckbd\u003eDel\u003c/kbd\u003e | Delete the focused item |\n| \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new directory |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file in the companion app |\n\n## Selection and Dual-Pane Workflows\n\nThese shortcuts matter most when you are working keyboard-first across one or two panes.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eIns\u003c/kbd\u003e or \u003ckbd\u003eSpace\u003c/kbd\u003e | Toggle selection on the focused item and move down |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Extend selection upward or downward |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eA\u003c/kbd\u003e | Select all items in the current list |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e | Toggle dual-pane mode |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e / \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e | Focus the left or right pane |\n| \u003ckbd\u003eTab\u003c/kbd\u003e | Move focus to the other pane |\n| \u003ckbd\u003eF5\u003c/kbd\u003e / \u003ckbd\u003eF6\u003c/kbd\u003e | Copy or move selected items to the other pane |\n\n## Viewers\n\nViewers share a common keyboard model for closing, searching, paging, and visual controls.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the viewer |\n| \u003ckbd\u003eD\u003c/kbd\u003e | Download the current file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search inside supported viewers |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last page or item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move to the previous or next page |\n| \u003ckbd\u003eLeft\u003c/kbd\u003e / \u003ckbd\u003eRight\u003c/kbd\u003e | Move to the previous or next page or item |\n| \u003ckbd\u003e+\u003c/kbd\u003e / \u003ckbd\u003e-\u003c/kbd\u003e | Zoom in or out |\n| \u003ckbd\u003e0\u003c/kbd\u003e | Reset zoom |\n| \u003ckbd\u003eR\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Rotate right or left |\n| \u003ckbd\u003eF\u003c/kbd\u003e | Toggle fullscreen |\n\nSome viewer shortcuts depend on the file type. For example, search applies to searchable viewers, and page navigation applies to paged or gallery-style viewers.\n\n## Markdown Editor\n\nMarkdown files build on the shared viewer shortcuts and add editor-specific formatting actions.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eE\u003c/kbd\u003e | Switch a Markdown file from viewing to editing |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e | Save the current Markdown file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search in the current Markdown content |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Create a link |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eT\u003c/kbd\u003e | Insert a table |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Insert a thematic break |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Apply inline code |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Insert a code block |\n| \u003ckbd\u003eF\u003c/kbd\u003e | Toggle fullscreen in the Markdown viewer |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the Markdown viewer |\n\n## When to Use the Built-In Shortcut Help\n\nThis page summarizes the most useful keyboard shortcuts by UI area.\n\nUse the built-in shortcuts help when you want the live in-app list for your current screen, or when you want a quick reminder without leaving the file browser.\n", "0.9": "+++\ntitle = \"Keyboard Navigation and Shortcuts\"\n+++\n\nKeyboard navigation is a first-class part of Sambee.\n\n## Keyboard-First Principles\n\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many file browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n- Safety still wins: Shortcuts that would be unsafe in text fields, dialogs, or incompatible states are intentionally blocked.\n\nIf you want the live in-app list, press \u003ckbd\u003e?\u003c/kbd\u003e while using Sambee.\n\n## File List and Main UI\n\nUse these shortcuts when the main file list or browser shell has focus.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eDown\u003c/kbd\u003e | Move to the previous or next row in the current file list |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last visible item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move up or down by a page in the current list |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file or enter the focused directory |\n| \u003ckbd\u003eBackspace\u003c/kbd\u003e | Go up to the parent directory |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Open the connection selector |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Open smart navigation |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Filter the current directory in the active pane |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e / \u003ckbd\u003eF1\u003c/kbd\u003e | Open commands |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e,\u003c/kbd\u003e | Open settings |\n| \u003ckbd\u003e?\u003c/kbd\u003e | Show keyboard shortcuts help |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Refresh the current file list |\n| \u003ckbd\u003eF2\u003c/kbd\u003e | Rename the focused item |\n| \u003ckbd\u003eDel\u003c/kbd\u003e | Delete the focused item |\n| \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new directory |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file in the companion app |\n\n## Selection and Dual-Pane Workflows\n\nThese shortcuts matter most when you are working keyboard-first across one or two panes.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eIns\u003c/kbd\u003e or \u003ckbd\u003eSpace\u003c/kbd\u003e | Toggle selection on the focused item and move down |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Extend selection upward or downward |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eA\u003c/kbd\u003e | Select all items in the current list |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e | Toggle dual-pane mode |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e / \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e | Focus the left or right pane |\n| \u003ckbd\u003eTab\u003c/kbd\u003e | Move focus to the other pane |\n| \u003ckbd\u003eF5\u003c/kbd\u003e / \u003ckbd\u003eF6\u003c/kbd\u003e | Copy or move selected items to the other pane |\n\n## Viewers\n\nViewers share a common keyboard model for closing, searching, paging, and visual controls.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the viewer |\n| \u003ckbd\u003eD\u003c/kbd\u003e | Download the current file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search inside supported viewers |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last page or item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move to the previous or next page |\n| \u003ckbd\u003eLeft\u003c/kbd\u003e / \u003ckbd\u003eRight\u003c/kbd\u003e | Move to the previous or next page or item |\n| \u003ckbd\u003e+\u003c/kbd\u003e / \u003ckbd\u003e-\u003c/kbd\u003e | Zoom in or out |\n| \u003ckbd\u003e0\u003c/kbd\u003e | Reset zoom |\n| \u003ckbd\u003eR\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Rotate right or left |\n| \u003ckbd\u003eF\u003c/kbd\u003e | Toggle fullscreen |\n\nSome viewer shortcuts depend on the file type. For example, search applies to searchable viewers, and page navigation applies to paged or gallery-style viewers.\n\n## Markdown Editor\n\nMarkdown files build on the shared viewer shortcuts and add editor-specific formatting actions.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eE\u003c/kbd\u003e | Switch a Markdown file from viewing to editing |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e | Save the current Markdown file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search in the current Markdown content |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Create a link |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eT\u003c/kbd\u003e | Insert a table |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Insert a thematic break |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Apply inline code |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Insert a code block |\n| \u003ckbd\u003eF\u003c/kbd\u003e | Toggle fullscreen in the Markdown viewer |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the Markdown viewer |\n\n## When to Use the Built-In Shortcut Help\n\nThis page summarizes the most useful keyboard shortcuts by UI area.\n\nUse the built-in shortcuts help when you want the live in-app list for your current screen, or when you want a quick reminder without leaving the file browser.\n", "1.0": "+++\ntitle = \"Keyboard Navigation and Shortcuts\"\n+++\n\nKeyboard navigation is a first-class part of Sambee.\n\n## Keyboard-First Principles\n\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many file browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n- Safety still wins: Shortcuts that would be unsafe in text fields, dialogs, or incompatible states are intentionally blocked.\n\nIf you want the live in-app list, press \u003ckbd\u003e?\u003c/kbd\u003e or \u003ckbd\u003eF1\u003c/kbd\u003e. While editing Markdown or text, use \u003ckbd\u003eF1\u003c/kbd\u003e so you can type question marks normally.\n\n## File List and Main UI\n\nUse these shortcuts when the main file list or browser shell has focus.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eDown\u003c/kbd\u003e | Move to the previous or next row in the current file list |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last visible item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move up or down by a page in the current list |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file or enter the focused directory |\n| \u003ckbd\u003eBackspace\u003c/kbd\u003e | Go up to the parent directory |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Open the connection selector |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Open smart navigation |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Filter the current directory in the active pane |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e | Open commands |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e,\u003c/kbd\u003e | Open settings |\n| \u003ckbd\u003e?\u003c/kbd\u003e / \u003ckbd\u003eF1\u003c/kbd\u003e | Show keyboard shortcuts help |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Refresh the current file list |\n| \u003ckbd\u003eF2\u003c/kbd\u003e | Rename the focused item |\n| \u003ckbd\u003eDel\u003c/kbd\u003e | Delete the focused item |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eD\u003c/kbd\u003e | Download the selected items, or the focused item if nothing is selected |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eU\u003c/kbd\u003e | Upload files to the current writable folder |\n| \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new directory |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file in the companion app |\n\nWhen the focused item is a local shortcut or filesystem link, Sambee resolves its target before activating it. A directory target opens in its drive and directory, including a different local drive. A file target follows the same behavior as opening that file directly: \u003ckbd\u003eEnter\u003c/kbd\u003e uses the selected viewer, while \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e opens it in the companion app. If the target is missing or inaccessible, Sambee shows an error instead of opening the link itself.\n\n## Selection and Dual-Pane Workflows\n\nThese shortcuts matter most when you are working keyboard-first across one or two panes.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eIns\u003c/kbd\u003e or \u003ckbd\u003eSpace\u003c/kbd\u003e | Toggle selection on the focused item and move down |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Extend selection upward or downward |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eA\u003c/kbd\u003e | Select all items in the current list |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e | Toggle dual-pane mode |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e / \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e | Focus the left or right pane |\n| \u003ckbd\u003eTab\u003c/kbd\u003e | Move focus to the other pane |\n| \u003ckbd\u003eF5\u003c/kbd\u003e / \u003ckbd\u003eF6\u003c/kbd\u003e | Copy or move selected items to the other pane |\n\n## Viewers\n\nViewers share a common keyboard model for closing, searching, paging, and visual controls.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the viewer |\n| \u003ckbd\u003eD\u003c/kbd\u003e | Download the current file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search inside supported viewers |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last page or item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move to the previous or next page |\n| \u003ckbd\u003eLeft\u003c/kbd\u003e / \u003ckbd\u003eRight\u003c/kbd\u003e | Move to the previous or next page or item |\n| \u003ckbd\u003e+\u003c/kbd\u003e / \u003ckbd\u003e-\u003c/kbd\u003e | Zoom in or out |\n| \u003ckbd\u003e0\u003c/kbd\u003e | Reset zoom |\n| \u003ckbd\u003eR\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Rotate right or left |\n| \u003ckbd\u003eF\u003c/kbd\u003e | Toggle fullscreen |\n| \u003ckbd\u003e?\u003c/kbd\u003e / \u003ckbd\u003eF1\u003c/kbd\u003e | Show keyboard shortcuts help |\n\nSome viewer shortcuts depend on the file type. For example, search applies to searchable viewers, and page navigation applies to paged or gallery-style viewers.\n\n## Markdown Editor\n\nMarkdown files build on the shared viewer shortcuts and add editor-specific formatting actions.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eE\u003c/kbd\u003e | Switch a Markdown file from viewing to editing |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e | Save the current Markdown file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e | Toggle bold text |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eI\u003c/kbd\u003e | Toggle italic text |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search in the current Markdown content |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Open find and replace for the current Markdown content |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e in the Replace field | Replace the current match |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e in the Replace field | Replace all matches |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eC\u003c/kbd\u003e | Toggle case-sensitive matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eW\u003c/kbd\u003e | Toggle whole-word matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Toggle regular-expression matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eZ\u003c/kbd\u003e | Toggle word wrap |\n| \u003ckbd\u003eF1\u003c/kbd\u003e | Show Text editor shortcuts |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Create a link |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eT\u003c/kbd\u003e | Insert a table |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Insert a thematic break |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Apply inline code |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Insert a code block |\n| \u003ckbd\u003eF1\u003c/kbd\u003e | Show Markdown editor shortcuts |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the Markdown viewer |\n\nFind and replace opens as a compact panel in the upper-right of the viewer, with a small margin below the toolbar. It shows the current match and total result count. Use the visible previous, next, replace, and replace-all controls after entering a search. The fields display `Search (\u21c5 for history)` and `Replace (\u21c5 for history)` until you type; each keeps up to ten recent values locally, available with \u003ckbd\u003eUp\u003c/kbd\u003e and \u003ckbd\u003eDown\u003c/kbd\u003e. Invalid regular expressions are reported without changing the document.\n\n## Text Editor\n\nText files use the same CodeMirror find controls as the Markdown editor. Find is available while viewing or editing a supported text file; replace is available while editing.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search in the current text content |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Open find and replace while editing |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e in the Replace field | Replace the current match |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e in the Replace field | Replace all matches |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eC\u003c/kbd\u003e | Toggle case-sensitive matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eW\u003c/kbd\u003e | Toggle whole-word matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Toggle regular-expression matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eZ\u003c/kbd\u003e | Toggle word wrap |\n\n## When to Use the Built-In Shortcut Help\n\nThis page summarizes the most useful keyboard shortcuts by UI area.\n\nUse the built-in shortcuts help when you want the live in-app list for your current screen, or when you want a quick reminder without leaving the file browser.\n", "2.0": "+++\ntitle = \"Keyboard Navigation and Shortcuts\"\n+++\n\nKeyboard navigation is a first-class part of Sambee.\n\n## Keyboard-First Principles\n\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many file browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n- Safety still wins: Shortcuts that would be unsafe in text fields, dialogs, or incompatible states are intentionally blocked.\n\nIf you want the live in-app list, press \u003ckbd\u003e?\u003c/kbd\u003e or \u003ckbd\u003eF1\u003c/kbd\u003e. While editing Markdown or text, use \u003ckbd\u003eF1\u003c/kbd\u003e so you can type question marks normally.\n\n## File List and Main UI\n\nUse these shortcuts when the main file list or browser shell has focus.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eDown\u003c/kbd\u003e | Move to the previous or next row in the current file list |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last visible item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move up or down by a page in the current list |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file or enter the focused directory |\n| \u003ckbd\u003eBackspace\u003c/kbd\u003e | Go up to the parent directory |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Open the connection selector |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Open smart navigation |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Filter the current directory in the active pane |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e | Open commands |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e,\u003c/kbd\u003e | Open settings |\n| \u003ckbd\u003e?\u003c/kbd\u003e / \u003ckbd\u003eF1\u003c/kbd\u003e | Show keyboard shortcuts help |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Refresh the current file list |\n| \u003ckbd\u003eF2\u003c/kbd\u003e | Rename the focused item |\n| \u003ckbd\u003eDel\u003c/kbd\u003e | Delete the focused item |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eD\u003c/kbd\u003e | Download the selected items, or the focused item if nothing is selected |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eU\u003c/kbd\u003e | Upload files to the current writable folder |\n| \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new directory |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file in the companion app |\n\nWhen the focused item is a local shortcut or filesystem link, Sambee resolves its target before activating it. A directory target opens in its drive and directory, including a different local drive. A file target follows the same behavior as opening that file directly: \u003ckbd\u003eEnter\u003c/kbd\u003e uses the selected viewer, while \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e opens it in the companion app. If the target is missing or inaccessible, Sambee shows an error instead of opening the link itself.\n\n## Selection and Dual-Pane Workflows\n\nThese shortcuts matter most when you are working keyboard-first across one or two panes.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eIns\u003c/kbd\u003e or \u003ckbd\u003eSpace\u003c/kbd\u003e | Toggle selection on the focused item and move down |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Extend selection upward or downward |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eA\u003c/kbd\u003e | Select all items in the current list |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e | Toggle dual-pane mode |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e / \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e | Focus the left or right pane |\n| \u003ckbd\u003eTab\u003c/kbd\u003e | Move focus to the other pane |\n| \u003ckbd\u003eF5\u003c/kbd\u003e / \u003ckbd\u003eF6\u003c/kbd\u003e | Copy or move selected items to the other pane |\n\n## Viewers\n\nViewers share a common keyboard model for closing, searching, paging, and visual controls.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the viewer |\n| \u003ckbd\u003eD\u003c/kbd\u003e | Download the current file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search inside supported viewers |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last page or item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move to the previous or next page |\n| \u003ckbd\u003eLeft\u003c/kbd\u003e / \u003ckbd\u003eRight\u003c/kbd\u003e | Move to the previous or next page or item |\n| \u003ckbd\u003e+\u003c/kbd\u003e / \u003ckbd\u003e-\u003c/kbd\u003e | Zoom in or out |\n| \u003ckbd\u003e0\u003c/kbd\u003e | Reset zoom |\n| \u003ckbd\u003eR\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Rotate right or left |\n| \u003ckbd\u003eF\u003c/kbd\u003e | Toggle fullscreen |\n| \u003ckbd\u003e?\u003c/kbd\u003e / \u003ckbd\u003eF1\u003c/kbd\u003e | Show keyboard shortcuts help |\n\nSome viewer shortcuts depend on the file type. For example, search applies to searchable viewers, and page navigation applies to paged or gallery-style viewers.\n\n## Markdown Editor\n\nMarkdown files build on the shared viewer shortcuts and add editor-specific formatting actions.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eE\u003c/kbd\u003e | Switch a Markdown file from viewing to editing |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e | Save the current Markdown file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e | Toggle bold text |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eI\u003c/kbd\u003e | Toggle italic text |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search in the current Markdown content |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Open find and replace for the current Markdown content |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e in the Replace field | Replace the current match |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e in the Replace field | Replace all matches |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eC\u003c/kbd\u003e | Toggle case-sensitive matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eW\u003c/kbd\u003e | Toggle whole-word matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Toggle regular-expression matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eZ\u003c/kbd\u003e | Toggle word wrap |\n| \u003ckbd\u003eF1\u003c/kbd\u003e | Show Text editor shortcuts |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Create a link |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eT\u003c/kbd\u003e | Insert a table |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Insert a thematic break |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Apply inline code |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Insert a code block |\n| \u003ckbd\u003eF1\u003c/kbd\u003e | Show Markdown editor shortcuts |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the Markdown viewer |\n\nFind and replace opens as a compact panel in the upper-right of the viewer, with a small margin below the toolbar. It shows the current match and total result count. Use the visible previous, next, replace, and replace-all controls after entering a search. The fields display `Search (\u21c5 for history)` and `Replace (\u21c5 for history)` until you type; each keeps up to ten recent values locally, available with \u003ckbd\u003eUp\u003c/kbd\u003e and \u003ckbd\u003eDown\u003c/kbd\u003e. Invalid regular expressions are reported without changing the document.\n\n## Text Editor\n\nText files use the same CodeMirror find controls as the Markdown editor. Find is available while viewing or editing a supported text file; replace is available while editing.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search in the current text content |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Open find and replace while editing |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e in the Replace field | Replace the current match |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e in the Replace field | Replace all matches |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eC\u003c/kbd\u003e | Toggle case-sensitive matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eW\u003c/kbd\u003e | Toggle whole-word matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Toggle regular-expression matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eZ\u003c/kbd\u003e | Toggle word wrap |\n\n## When to Use the Built-In Shortcut Help\n\nThis page summarizes the most useful keyboard shortcuts by UI area.\n\nUse the built-in shortcuts help when you want the live in-app list for your current screen, or when you want a quick reminder without leaving the file browser.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Keyboard Navigation and Shortcuts\"\n+++\n\nKeyboard navigation is a first-class part of Sambee.\n\n## Keyboard-First Principles\n\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many file browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n- Safety still wins: Shortcuts that would be unsafe in text fields, dialogs, or incompatible states are intentionally blocked.\n\nIf you want the live in-app list, press \u003ckbd\u003e?\u003c/kbd\u003e while using Sambee.\n\n## File List and Main UI\n\nUse these shortcuts when the main file list or browser shell has focus.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eDown\u003c/kbd\u003e | Move to the previous or next row in the current file list |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last visible item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move up or down by a page in the current list |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file or enter the focused directory |\n| \u003ckbd\u003eBackspace\u003c/kbd\u003e | Go up to the parent directory |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Open the connection selector |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Open smart navigation |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Filter the current directory in the active pane |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e / \u003ckbd\u003eF1\u003c/kbd\u003e | Open commands |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e,\u003c/kbd\u003e | Open settings |\n| \u003ckbd\u003e?\u003c/kbd\u003e | Show keyboard shortcuts help |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Refresh the current file list |\n| \u003ckbd\u003eF2\u003c/kbd\u003e | Rename the focused item |\n| \u003ckbd\u003eDel\u003c/kbd\u003e | Delete the focused item |\n| \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new directory |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file in the companion app |\n\n## Selection and Dual-Pane Workflows\n\nThese shortcuts matter most when you are working keyboard-first across one or two panes.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eIns\u003c/kbd\u003e or \u003ckbd\u003eSpace\u003c/kbd\u003e | Toggle selection on the focused item and move down |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Extend selection upward or downward |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eA\u003c/kbd\u003e | Select all items in the current list |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e | Toggle dual-pane mode |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e / \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e | Focus the left or right pane |\n| \u003ckbd\u003eTab\u003c/kbd\u003e | Move focus to the other pane |\n| \u003ckbd\u003eF5\u003c/kbd\u003e / \u003ckbd\u003eF6\u003c/kbd\u003e | Copy or move selected items to the other pane |\n\n## Viewers\n\nViewers share a common keyboard model for closing, searching, paging, and visual controls.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the viewer |\n| \u003ckbd\u003eD\u003c/kbd\u003e | Download the current file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search inside supported viewers |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last page or item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move to the previous or next page |\n| \u003ckbd\u003eLeft\u003c/kbd\u003e / \u003ckbd\u003eRight\u003c/kbd\u003e | Move to the previous or next page or item |\n| \u003ckbd\u003e+\u003c/kbd\u003e / \u003ckbd\u003e-\u003c/kbd\u003e | Zoom in or out |\n| \u003ckbd\u003e0\u003c/kbd\u003e | Reset zoom |\n| \u003ckbd\u003eR\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Rotate right or left |\n| \u003ckbd\u003eF\u003c/kbd\u003e | Toggle fullscreen |\n\nSome viewer shortcuts depend on the file type. For example, search applies to searchable viewers, and page navigation applies to paged or gallery-style viewers.\n\n## Markdown Editor\n\nMarkdown files build on the shared viewer shortcuts and add editor-specific formatting actions.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eE\u003c/kbd\u003e | Switch a Markdown file from viewing to editing |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e | Save the current Markdown file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search in the current Markdown content |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Create a link |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eT\u003c/kbd\u003e | Insert a table |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Insert a thematic break |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Apply inline code |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Insert a code block |\n| \u003ckbd\u003eF\u003c/kbd\u003e | Toggle fullscreen in the Markdown viewer |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the Markdown viewer |\n\n## When to Use the Built-In Shortcut Help\n\nThis page summarizes the most useful keyboard shortcuts by UI area.\n\nUse the built-in shortcuts help when you want the live in-app list for your current screen, or when you want a quick reminder without leaving the file browser.\n", "0.8": "+++\ntitle = \"Keyboard Navigation and Shortcuts\"\n+++\n\nKeyboard navigation is a first-class part of Sambee.\n\n## Keyboard-First Principles\n\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many file browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n- Safety still wins: Shortcuts that would be unsafe in text fields, dialogs, or incompatible states are intentionally blocked.\n\nIf you want the live in-app list, press \u003ckbd\u003e?\u003c/kbd\u003e while using Sambee.\n\n## File List and Main UI\n\nUse these shortcuts when the main file list or browser shell has focus.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eDown\u003c/kbd\u003e | Move to the previous or next row in the current file list |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last visible item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move up or down by a page in the current list |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file or enter the focused directory |\n| \u003ckbd\u003eBackspace\u003c/kbd\u003e | Go up to the parent directory |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Open the connection selector |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Open smart navigation |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Filter the current directory in the active pane |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e / \u003ckbd\u003eF1\u003c/kbd\u003e | Open commands |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e,\u003c/kbd\u003e | Open settings |\n| \u003ckbd\u003e?\u003c/kbd\u003e | Show keyboard shortcuts help |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Refresh the current file list |\n| \u003ckbd\u003eF2\u003c/kbd\u003e | Rename the focused item |\n| \u003ckbd\u003eDel\u003c/kbd\u003e | Delete the focused item |\n| \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new directory |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file in the companion app |\n\n## Selection and Dual-Pane Workflows\n\nThese shortcuts matter most when you are working keyboard-first across one or two panes.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eIns\u003c/kbd\u003e or \u003ckbd\u003eSpace\u003c/kbd\u003e | Toggle selection on the focused item and move down |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Extend selection upward or downward |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eA\u003c/kbd\u003e | Select all items in the current list |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e | Toggle dual-pane mode |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e / \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e | Focus the left or right pane |\n| \u003ckbd\u003eTab\u003c/kbd\u003e | Move focus to the other pane |\n| \u003ckbd\u003eF5\u003c/kbd\u003e / \u003ckbd\u003eF6\u003c/kbd\u003e | Copy or move selected items to the other pane |\n\n## Viewers\n\nViewers share a common keyboard model for closing, searching, paging, and visual controls.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the viewer |\n| \u003ckbd\u003eD\u003c/kbd\u003e | Download the current file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search inside supported viewers |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last page or item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move to the previous or next page |\n| \u003ckbd\u003eLeft\u003c/kbd\u003e / \u003ckbd\u003eRight\u003c/kbd\u003e | Move to the previous or next page or item |\n| \u003ckbd\u003e+\u003c/kbd\u003e / \u003ckbd\u003e-\u003c/kbd\u003e | Zoom in or out |\n| \u003ckbd\u003e0\u003c/kbd\u003e | Reset zoom |\n| \u003ckbd\u003eR\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Rotate right or left |\n| \u003ckbd\u003eF\u003c/kbd\u003e | Toggle fullscreen |\n\nSome viewer shortcuts depend on the file type. For example, search applies to searchable viewers, and page navigation applies to paged or gallery-style viewers.\n\n## Markdown Editor\n\nMarkdown files build on the shared viewer shortcuts and add editor-specific formatting actions.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eE\u003c/kbd\u003e | Switch a Markdown file from viewing to editing |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e | Save the current Markdown file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search in the current Markdown content |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Create a link |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eT\u003c/kbd\u003e | Insert a table |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Insert a thematic break |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Apply inline code |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Insert a code block |\n| \u003ckbd\u003eF\u003c/kbd\u003e | Toggle fullscreen in the Markdown viewer |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the Markdown viewer |\n\n## When to Use the Built-In Shortcut Help\n\nThis page summarizes the most useful keyboard shortcuts by UI area.\n\nUse the built-in shortcuts help when you want the live in-app list for your current screen, or when you want a quick reminder without leaving the file browser.\n", "0.9": "+++\ntitle = \"Keyboard Navigation and Shortcuts\"\n+++\n\nKeyboard navigation is a first-class part of Sambee.\n\n## Keyboard-First Principles\n\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many file browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n- Safety still wins: Shortcuts that would be unsafe in text fields, dialogs, or incompatible states are intentionally blocked.\n\nIf you want the live in-app list, press \u003ckbd\u003e?\u003c/kbd\u003e while using Sambee.\n\n## File List and Main UI\n\nUse these shortcuts when the main file list or browser shell has focus.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eDown\u003c/kbd\u003e | Move to the previous or next row in the current file list |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last visible item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move up or down by a page in the current list |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file or enter the focused directory |\n| \u003ckbd\u003eBackspace\u003c/kbd\u003e | Go up to the parent directory |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Open the connection selector |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Open smart navigation |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Filter the current directory in the active pane |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e / \u003ckbd\u003eF1\u003c/kbd\u003e | Open commands |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e,\u003c/kbd\u003e | Open settings |\n| \u003ckbd\u003e?\u003c/kbd\u003e | Show keyboard shortcuts help |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Refresh the current file list |\n| \u003ckbd\u003eF2\u003c/kbd\u003e | Rename the focused item |\n| \u003ckbd\u003eDel\u003c/kbd\u003e | Delete the focused item |\n| \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new directory |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file in the companion app |\n\n## Selection and Dual-Pane Workflows\n\nThese shortcuts matter most when you are working keyboard-first across one or two panes.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eIns\u003c/kbd\u003e or \u003ckbd\u003eSpace\u003c/kbd\u003e | Toggle selection on the focused item and move down |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Extend selection upward or downward |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eA\u003c/kbd\u003e | Select all items in the current list |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e | Toggle dual-pane mode |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e / \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e | Focus the left or right pane |\n| \u003ckbd\u003eTab\u003c/kbd\u003e | Move focus to the other pane |\n| \u003ckbd\u003eF5\u003c/kbd\u003e / \u003ckbd\u003eF6\u003c/kbd\u003e | Copy or move selected items to the other pane |\n\n## Viewers\n\nViewers share a common keyboard model for closing, searching, paging, and visual controls.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the viewer |\n| \u003ckbd\u003eD\u003c/kbd\u003e | Download the current file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search inside supported viewers |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last page or item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move to the previous or next page |\n| \u003ckbd\u003eLeft\u003c/kbd\u003e / \u003ckbd\u003eRight\u003c/kbd\u003e | Move to the previous or next page or item |\n| \u003ckbd\u003e+\u003c/kbd\u003e / \u003ckbd\u003e-\u003c/kbd\u003e | Zoom in or out |\n| \u003ckbd\u003e0\u003c/kbd\u003e | Reset zoom |\n| \u003ckbd\u003eR\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Rotate right or left |\n| \u003ckbd\u003eF\u003c/kbd\u003e | Toggle fullscreen |\n\nSome viewer shortcuts depend on the file type. For example, search applies to searchable viewers, and page navigation applies to paged or gallery-style viewers.\n\n## Markdown Editor\n\nMarkdown files build on the shared viewer shortcuts and add editor-specific formatting actions.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eE\u003c/kbd\u003e | Switch a Markdown file from viewing to editing |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e | Save the current Markdown file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search in the current Markdown content |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Create a link |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eT\u003c/kbd\u003e | Insert a table |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Insert a thematic break |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Apply inline code |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Insert a code block |\n| \u003ckbd\u003eF\u003c/kbd\u003e | Toggle fullscreen in the Markdown viewer |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the Markdown viewer |\n\n## When to Use the Built-In Shortcut Help\n\nThis page summarizes the most useful keyboard shortcuts by UI area.\n\nUse the built-in shortcuts help when you want the live in-app list for your current screen, or when you want a quick reminder without leaving the file browser.\n", "1.0": "+++\ntitle = \"Keyboard Navigation and Shortcuts\"\n+++\n\nKeyboard navigation is a first-class part of Sambee.\n\n## Keyboard-First Principles\n\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many file browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n- Safety still wins: Shortcuts that would be unsafe in text fields, dialogs, or incompatible states are intentionally blocked.\n\nIf you want the live in-app list, press \u003ckbd\u003e?\u003c/kbd\u003e or \u003ckbd\u003eF1\u003c/kbd\u003e. While editing Markdown or text, use \u003ckbd\u003eF1\u003c/kbd\u003e so you can type question marks normally.\n\n## File List and Main UI\n\nUse these shortcuts when the main file list or browser shell has focus.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eDown\u003c/kbd\u003e | Move to the previous or next row in the current file list |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last visible item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move up or down by a page in the current list |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file or enter the focused directory |\n| \u003ckbd\u003eBackspace\u003c/kbd\u003e | Go up to the parent directory |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Open the connection selector |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Open smart navigation |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Filter the current directory in the active pane |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e | Open commands |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e,\u003c/kbd\u003e | Open settings |\n| \u003ckbd\u003e?\u003c/kbd\u003e / \u003ckbd\u003eF1\u003c/kbd\u003e | Show keyboard shortcuts help |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Refresh the current file list |\n| \u003ckbd\u003eF2\u003c/kbd\u003e | Rename the focused item |\n| \u003ckbd\u003eDel\u003c/kbd\u003e | Delete the focused item |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eD\u003c/kbd\u003e | Download the selected items, or the focused item if nothing is selected |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eU\u003c/kbd\u003e | Upload files to the current writable folder |\n| \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new directory |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file in the companion app |\n\nWhen the focused item is a local shortcut or filesystem link, Sambee resolves its target before activating it. A directory target opens in its drive and directory, including a different local drive. A file target follows the same behavior as opening that file directly: \u003ckbd\u003eEnter\u003c/kbd\u003e uses the selected viewer, while \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e opens it in the companion app. If the target is missing or inaccessible, Sambee shows an error instead of opening the link itself.\n\n## Selection and Dual-Pane Workflows\n\nThese shortcuts matter most when you are working keyboard-first across one or two panes.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eIns\u003c/kbd\u003e or \u003ckbd\u003eSpace\u003c/kbd\u003e | Toggle selection on the focused item and move down |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Extend selection upward or downward |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eA\u003c/kbd\u003e | Select all items in the current list |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e | Toggle dual-pane mode |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e / \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e | Focus the left or right pane |\n| \u003ckbd\u003eTab\u003c/kbd\u003e | Move focus to the other pane |\n| \u003ckbd\u003eF5\u003c/kbd\u003e / \u003ckbd\u003eF6\u003c/kbd\u003e | Copy or move selected items to the other pane |\n\n## Viewers\n\nViewers share a common keyboard model for closing, searching, paging, and visual controls.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the viewer |\n| \u003ckbd\u003eD\u003c/kbd\u003e | Download the current file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search inside supported viewers |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last page or item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move to the previous or next page |\n| \u003ckbd\u003eLeft\u003c/kbd\u003e / \u003ckbd\u003eRight\u003c/kbd\u003e | Move to the previous or next page or item |\n| \u003ckbd\u003e+\u003c/kbd\u003e / \u003ckbd\u003e-\u003c/kbd\u003e | Zoom in or out |\n| \u003ckbd\u003e0\u003c/kbd\u003e | Reset zoom |\n| \u003ckbd\u003eR\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Rotate right or left |\n| \u003ckbd\u003eF\u003c/kbd\u003e | Toggle fullscreen |\n| \u003ckbd\u003e?\u003c/kbd\u003e / \u003ckbd\u003eF1\u003c/kbd\u003e | Show keyboard shortcuts help |\n\nSome viewer shortcuts depend on the file type. For example, search applies to searchable viewers, and page navigation applies to paged or gallery-style viewers.\n\n## Markdown Editor\n\nMarkdown files build on the shared viewer shortcuts and add editor-specific formatting actions.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eE\u003c/kbd\u003e | Switch a Markdown file from viewing to editing |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e | Save the current Markdown file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e | Toggle bold text |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eI\u003c/kbd\u003e | Toggle italic text |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search in the current Markdown content |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Open find and replace for the current Markdown content |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e in the Replace field | Replace the current match |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e in the Replace field | Replace all matches |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eC\u003c/kbd\u003e | Toggle case-sensitive matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eW\u003c/kbd\u003e | Toggle whole-word matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Toggle regular-expression matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eZ\u003c/kbd\u003e | Toggle word wrap |\n| \u003ckbd\u003eF1\u003c/kbd\u003e | Show Text editor shortcuts |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Create a link |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eT\u003c/kbd\u003e | Insert a table |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Insert a thematic break |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Apply inline code |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Insert a code block |\n| \u003ckbd\u003eF1\u003c/kbd\u003e | Show Markdown editor shortcuts |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the Markdown viewer |\n\nFind and replace opens as a compact panel in the upper-right of the viewer, with a small margin below the toolbar. It shows the current match and total result count. Use the visible previous, next, replace, and replace-all controls after entering a search. The fields display `Search (\u21c5 for history)` and `Replace (\u21c5 for history)` until you type; each keeps up to ten recent values locally, available with \u003ckbd\u003eUp\u003c/kbd\u003e and \u003ckbd\u003eDown\u003c/kbd\u003e. Invalid regular expressions are reported without changing the document.\n\n## Text Editor\n\nText files use the same CodeMirror find controls as the Markdown editor. Find is available while viewing or editing a supported text file; replace is available while editing.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search in the current text content |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Open find and replace while editing |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e in the Replace field | Replace the current match |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e in the Replace field | Replace all matches |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eC\u003c/kbd\u003e | Toggle case-sensitive matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eW\u003c/kbd\u003e | Toggle whole-word matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Toggle regular-expression matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eZ\u003c/kbd\u003e | Toggle word wrap |\n\n## When to Use the Built-In Shortcut Help\n\nThis page summarizes the most useful keyboard shortcuts by UI area.\n\nUse the built-in shortcuts help when you want the live in-app list for your current screen, or when you want a quick reminder without leaving the file browser.\n", "2.0": "+++\ntitle = \"Keyboard Navigation and Shortcuts\"\n+++\n\nKeyboard navigation is a first-class part of Sambee.\n\n## Keyboard-First Principles\n\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many file browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n- Safety still wins: Shortcuts that would be unsafe in text fields, dialogs, or incompatible states are intentionally blocked.\n\nIf you want the live in-app list, press \u003ckbd\u003e?\u003c/kbd\u003e or \u003ckbd\u003eF1\u003c/kbd\u003e. While editing Markdown or text, use \u003ckbd\u003eF1\u003c/kbd\u003e so you can type question marks normally.\n\n## File List and Main UI\n\nUse these shortcuts when the main file list or browser shell has focus.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eDown\u003c/kbd\u003e | Move to the previous or next row in the current file list |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last visible item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move up or down by a page in the current list |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file or enter the focused directory |\n| \u003ckbd\u003eBackspace\u003c/kbd\u003e | Go up to the parent directory |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Open the connection selector |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Open smart navigation |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Filter the current directory in the active pane |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eP\u003c/kbd\u003e | Open commands |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e,\u003c/kbd\u003e | Open settings |\n| \u003ckbd\u003e?\u003c/kbd\u003e / \u003ckbd\u003eF1\u003c/kbd\u003e | Show keyboard shortcuts help |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Refresh the current file list |\n| \u003ckbd\u003eF2\u003c/kbd\u003e | Rename the focused item |\n| \u003ckbd\u003eDel\u003c/kbd\u003e | Delete the focused item |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eD\u003c/kbd\u003e | Download the selected items, or the focused item if nothing is selected |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eU\u003c/kbd\u003e | Upload files to the current writable folder |\n| \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new directory |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF7\u003c/kbd\u003e | Create a new file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e | Open the focused file in the companion app |\n\nWhen the focused item is a local shortcut or filesystem link, Sambee resolves its target before activating it. A directory target opens in its drive and directory, including a different local drive. A file target follows the same behavior as opening that file directly: \u003ckbd\u003eEnter\u003c/kbd\u003e uses the selected viewer, while \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e opens it in the companion app. If the target is missing or inaccessible, Sambee shows an error instead of opening the link itself.\n\n## Selection and Dual-Pane Workflows\n\nThese shortcuts matter most when you are working keyboard-first across one or two panes.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eIns\u003c/kbd\u003e or \u003ckbd\u003eSpace\u003c/kbd\u003e | Toggle selection on the focused item and move down |\n| \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eUp\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eDown\u003c/kbd\u003e | Extend selection upward or downward |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eA\u003c/kbd\u003e | Select all items in the current list |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e | Toggle dual-pane mode |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e1\u003c/kbd\u003e / \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003e2\u003c/kbd\u003e | Focus the left or right pane |\n| \u003ckbd\u003eTab\u003c/kbd\u003e | Move focus to the other pane |\n| \u003ckbd\u003eF5\u003c/kbd\u003e / \u003ckbd\u003eF6\u003c/kbd\u003e | Copy or move selected items to the other pane |\n\n## Viewers\n\nViewers share a common keyboard model for closing, searching, paging, and visual controls.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the viewer |\n| \u003ckbd\u003eD\u003c/kbd\u003e | Download the current file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search inside supported viewers |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eHome\u003c/kbd\u003e / \u003ckbd\u003eEnd\u003c/kbd\u003e | Jump to the first or last page or item |\n| \u003ckbd\u003ePage Up\u003c/kbd\u003e / \u003ckbd\u003ePage Down\u003c/kbd\u003e | Move to the previous or next page |\n| \u003ckbd\u003eLeft\u003c/kbd\u003e / \u003ckbd\u003eRight\u003c/kbd\u003e | Move to the previous or next page or item |\n| \u003ckbd\u003e+\u003c/kbd\u003e / \u003ckbd\u003e-\u003c/kbd\u003e | Zoom in or out |\n| \u003ckbd\u003e0\u003c/kbd\u003e | Reset zoom |\n| \u003ckbd\u003eR\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Rotate right or left |\n| \u003ckbd\u003eF\u003c/kbd\u003e | Toggle fullscreen |\n| \u003ckbd\u003e?\u003c/kbd\u003e / \u003ckbd\u003eF1\u003c/kbd\u003e | Show keyboard shortcuts help |\n\nSome viewer shortcuts depend on the file type. For example, search applies to searchable viewers, and page navigation applies to paged or gallery-style viewers.\n\n## Markdown Editor\n\nMarkdown files build on the shared viewer shortcuts and add editor-specific formatting actions.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eE\u003c/kbd\u003e | Switch a Markdown file from viewing to editing |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e | Save the current Markdown file |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eB\u003c/kbd\u003e | Toggle bold text |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eI\u003c/kbd\u003e | Toggle italic text |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search in the current Markdown content |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Open find and replace for the current Markdown content |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e in the Replace field | Replace the current match |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e in the Replace field | Replace all matches |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eC\u003c/kbd\u003e | Toggle case-sensitive matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eW\u003c/kbd\u003e | Toggle whole-word matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Toggle regular-expression matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eZ\u003c/kbd\u003e | Toggle word wrap |\n| \u003ckbd\u003eF1\u003c/kbd\u003e | Show Text editor shortcuts |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eK\u003c/kbd\u003e | Create a link |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eT\u003c/kbd\u003e | Insert a table |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Insert a thematic break |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Apply inline code |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eE\u003c/kbd\u003e | Insert a code block |\n| \u003ckbd\u003eF1\u003c/kbd\u003e | Show Markdown editor shortcuts |\n| \u003ckbd\u003eEsc\u003c/kbd\u003e | Close the Markdown viewer |\n\nFind and replace opens as a compact panel in the upper-right of the viewer, with a small margin below the toolbar. It shows the current match and total result count. Use the visible previous, next, replace, and replace-all controls after entering a search. The fields display `Search (\u21c5 for history)` and `Replace (\u21c5 for history)` until you type; each keeps up to ten recent values locally, available with \u003ckbd\u003eUp\u003c/kbd\u003e and \u003ckbd\u003eDown\u003c/kbd\u003e. Invalid regular expressions are reported without changing the document.\n\n## Text Editor\n\nText files use the same CodeMirror find controls as the Markdown editor. Find is available while viewing or editing a supported text file; replace is available while editing.\n\n| Shortcut | What it does |\n| --- | --- |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e | Search in the current text content |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eH\u003c/kbd\u003e | Open find and replace while editing |\n| \u003ckbd\u003eF3\u003c/kbd\u003e / \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eF3\u003c/kbd\u003e | Jump to the next or previous search result |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e in the Replace field | Replace the current match |\n| \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e in the Replace field | Replace all matches |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eC\u003c/kbd\u003e | Toggle case-sensitive matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eW\u003c/kbd\u003e | Toggle whole-word matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eR\u003c/kbd\u003e | Toggle regular-expression matching while the find panel is open |\n| \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eZ\u003c/kbd\u003e | Toggle word wrap |\n\n## When to Use the Built-In Shortcut Help\n\nThis page summarizes the most useful keyboard shortcuts by UI area.\n\nUse the built-in shortcuts help when you want the live in-app list for your current screen, or when you want a quick reminder without leaving the file browser.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:user-guide/browsing-and-navigation/mobile-navigation", "parent_id": "section:user-guide/browsing-and-navigation", "depth": 2, "kind": "page", "label": "mobile-navigation", "title": "Mobile Navigation", "path": "user-guide/browsing-and-navigation/mobile-navigation", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "branched", "source_version": "0.7", "diff_added": 35, "diff_removed": 0}}, "content_versions": {"0.7": "+++\ntitle = \"Mobile Navigation\"\n+++\n\nSambee is designed and optimized for phones and tablets as well as for desktops. Because each platform has different strengths, the mobile experience differs from the desktop experience in some cases.\n\n## Where Mobile Excels\n\nMobile is a good fit when you want to:\n\n- Explore network shares made available through Sambee.\n- View images, read PDFs, and edit Markdown files.\n- Share content from file servers on mobile platforms.\n\n## What Changes on Mobile\n\nCompared with desktop, mobile navigation is more compact:\n\n- The interface focuses on single-pane navigation.\n- Toolbar space is tighter.\n- Some desktop-oriented browser controls are simplified or moved behind menus.\n- Opening files in natively installed apps is not available.\n- Local drive access is not available.\n", "0.8": "+++\ntitle = \"Mobile Navigation\"\n+++\n\nSambee is designed and optimized for phones and tablets as well as for desktops. Because each platform has different strengths, the mobile experience differs from the desktop experience in some cases.\n\n## Where Mobile Excels\n\nMobile is a good fit when you want to:\n\n- Explore network shares made available through Sambee.\n- View images, read PDFs, and edit Markdown files.\n- Share content from file servers on mobile platforms.\n\n## What Changes on Mobile\n\nCompared with desktop, mobile navigation is more compact:\n\n- The interface focuses on single-pane navigation.\n- Toolbar space is tighter.\n- Some desktop-oriented browser controls are simplified or moved behind menus.\n- Opening files in natively installed apps is not available.\n- Local drive access is not available.\n", "0.9": "+++\ntitle = \"Mobile Navigation\"\n+++\n\nSambee is designed and optimized for phones and tablets as well as for desktops. Because each platform has different strengths, the mobile experience differs from the desktop experience in some cases.\n\n## Where Mobile Excels\n\nMobile is a good fit when you want to:\n\n- Explore network shares made available through Sambee.\n- View images, read PDFs, and edit Markdown files.\n- Share content from file servers on mobile platforms.\n\n## What Changes on Mobile\n\nCompared with desktop, mobile navigation is more compact:\n\n- The interface focuses on single-pane navigation.\n- Toolbar space is tighter.\n- Some desktop-oriented browser controls are simplified or moved behind menus.\n- Opening files in natively installed apps is not available.\n- Local drive access is not available.\n", "1.0": "+++\ntitle = \"Mobile Navigation\"\n+++\n\nSambee is designed and optimized for phones and tablets as well as for desktops. Because each platform has different strengths, the mobile experience differs from the desktop experience in some cases.\n\n## Where Mobile Excels\n\nMobile is a good fit when you want to:\n\n- Explore network shares made available through Sambee.\n- View images, read PDFs, and edit Markdown files.\n- Share content from file servers on mobile platforms.\n\n## What Changes on Mobile\n\nCompared with desktop, mobile navigation is more compact:\n\n- The interface focuses on single-pane navigation.\n- Toolbar space is tighter.\n- Some desktop-oriented browser controls are simplified or moved behind menus.\n- Opening files in natively installed apps is not available.\n- Local drive access is not available.\n", "2.0": "+++\ntitle = \"Mobile Navigation\"\n+++\n\nSambee is designed and optimized for phones and tablets as well as for desktops. Because each platform has different strengths, the mobile experience differs from the desktop experience in some cases.\n\n## Where Mobile Excels\n\nMobile is a good fit when you want to:\n\n- Explore network shares made available through Sambee.\n- View images, read PDFs, and edit Markdown files.\n- Share content from file servers on mobile platforms.\n\n## What Changes on Mobile\n\nCompared with desktop, mobile navigation is more compact:\n\n- The interface focuses on single-pane navigation.\n- Toolbar space is tighter.\n- Some desktop-oriented browser controls are simplified or moved behind menus.\n- Opening files in natively installed apps is not available.\n- Local drive access is not available.\n\n## Back, Forward, and Bookmarks\n\nOpening or closing a file, entering or leaving its editor, moving between gallery images, and navigating or closing settings update the browser address and add history entries. You can bookmark or share that address on desktop or mobile. The recipient still needs access to the connection and file; local-drive links also need a paired companion with that drive available.\n\nUse browser Back to retrace your navigation steps. If you open an image and close it, Back reopens that image; another Back returns to the file list from before you opened it. Forward follows those same locations in the other direction. Reopening an editor checks access and obtains a new edit lock. History doesn't undo saved file changes or restore discarded edits. Starting a new navigation after Back replaces the old Forward branch.\n\nIf you have unsaved edits, Back or another navigation asks you to **Save**, **Discard**, or **Cancel**. Cancel keeps your draft and current location. A failed save keeps you in the editor. Your browser can also warn before reloading or closing a tab with unsaved edits.\n\nSettings **Close** reveals the underlying workspace and adds a history entry, so browser Back reopens the last settings category. Closing a directly opened viewer or settings bookmark also adds an entry without sending you to an unrelated page. The mobile settings back arrow follows your history; without an earlier location observed in this workspace, it uses an in-app parent. Resizing between phone and desktop layouts keeps the selected settings category.\n\nRefreshing a bookmark restores its requested location, not a different workspace saved earlier in the tab. A missing file or unavailable connection offers recovery actions rather than silently opening another file.\n\n## Share Files and Text\n\nOn a phone, use **Share** in a file's action menu, or select several files and choose **Share** from the selection menu. Sambee prepares the stored files first. When they're ready, tap **Share** to open your device's share sheet. Multiple files are submitted together; Sambee doesn't silently drop files or retry a smaller selection.\n\nImage and PDF viewers have a sharing icon in the top bar. They share the resource you're viewing, including a compatible converted image or normalized PDF when needed. An image's extension matches the shared format. PDF sharing includes the whole displayed document, not just the visible page. Sharing from the file list instead uses the stored files without viewer conversions.\n\nIn text and Markdown viewers and editors, the same sharing icon opens two choices:\n\n- **Share as file** shares the saved file without saving your edits first.\n- **Share as text** shares the loaded text or your current editor contents, including unsaved changes. Markdown is shared as source text, not rendered HTML.\n\nThe file choice shows a preparation indicator while its attachment loads. You can still share text independently of that preparation.\n\nSharing availability and accepted attachment types depend on your browser and device. A browser can reject an attachment even after its capability check succeeds. Sambee won't silently replace a rejected attachment with text; choose **Share as text** explicitly where available.\n\n### If Sharing Fails\n\nWhen a prepared attachment can't be shared, use **Download** and try sharing it from your device's Files app. For failed image/PDF viewer sharing, this recovery download uses the same displayed resource. Ordinary download controls keep their existing behavior. For several files, download each prepared file in turn. If attachment preparation fails, text and Markdown viewers offer **Retry** without automatically opening the share sheet.\n\nChoose **Details** in sharing-failure feedback to open a diagnostic report. The copy icon copies the report; if clipboard access isn't available, select the report to copy it manually. The report excludes file names, paths, shared text, file contents, and credentials. Sambee doesn't upload it automatically. Closing Details keeps the failure feedback and its recovery actions available.\n\nCancelling the native share sheet doesn't show an error. Completion of the browser's share request doesn't confirm what a receiving app received.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Mobile Navigation\"\n+++\n\nSambee is designed and optimized for phones and tablets as well as for desktops. Because each platform has different strengths, the mobile experience differs from the desktop experience in some cases.\n\n## Where Mobile Excels\n\nMobile is a good fit when you want to:\n\n- Explore network shares made available through Sambee.\n- View images, read PDFs, and edit Markdown files.\n- Share content from file servers on mobile platforms.\n\n## What Changes on Mobile\n\nCompared with desktop, mobile navigation is more compact:\n\n- The interface focuses on single-pane navigation.\n- Toolbar space is tighter.\n- Some desktop-oriented browser controls are simplified or moved behind menus.\n- Opening files in natively installed apps is not available.\n- Local drive access is not available.\n", "0.8": "+++\ntitle = \"Mobile Navigation\"\n+++\n\nSambee is designed and optimized for phones and tablets as well as for desktops. Because each platform has different strengths, the mobile experience differs from the desktop experience in some cases.\n\n## Where Mobile Excels\n\nMobile is a good fit when you want to:\n\n- Explore network shares made available through Sambee.\n- View images, read PDFs, and edit Markdown files.\n- Share content from file servers on mobile platforms.\n\n## What Changes on Mobile\n\nCompared with desktop, mobile navigation is more compact:\n\n- The interface focuses on single-pane navigation.\n- Toolbar space is tighter.\n- Some desktop-oriented browser controls are simplified or moved behind menus.\n- Opening files in natively installed apps is not available.\n- Local drive access is not available.\n", "0.9": "+++\ntitle = \"Mobile Navigation\"\n+++\n\nSambee is designed and optimized for phones and tablets as well as for desktops. Because each platform has different strengths, the mobile experience differs from the desktop experience in some cases.\n\n## Where Mobile Excels\n\nMobile is a good fit when you want to:\n\n- Explore network shares made available through Sambee.\n- View images, read PDFs, and edit Markdown files.\n- Share content from file servers on mobile platforms.\n\n## What Changes on Mobile\n\nCompared with desktop, mobile navigation is more compact:\n\n- The interface focuses on single-pane navigation.\n- Toolbar space is tighter.\n- Some desktop-oriented browser controls are simplified or moved behind menus.\n- Opening files in natively installed apps is not available.\n- Local drive access is not available.\n", "1.0": "+++\ntitle = \"Mobile Navigation\"\n+++\n\nSambee is designed and optimized for phones and tablets as well as for desktops. Because each platform has different strengths, the mobile experience differs from the desktop experience in some cases.\n\n## Where Mobile Excels\n\nMobile is a good fit when you want to:\n\n- Explore network shares made available through Sambee.\n- View images, read PDFs, and edit Markdown files.\n- Share content from file servers on mobile platforms.\n\n## What Changes on Mobile\n\nCompared with desktop, mobile navigation is more compact:\n\n- The interface focuses on single-pane navigation.\n- Toolbar space is tighter.\n- Some desktop-oriented browser controls are simplified or moved behind menus.\n- Opening files in natively installed apps is not available.\n- Local drive access is not available.\n", "2.0": "+++\ntitle = \"Mobile Navigation\"\n+++\n\nSambee is designed and optimized for phones and tablets as well as for desktops. Because each platform has different strengths, the mobile experience differs from the desktop experience in some cases.\n\n## Where Mobile Excels\n\nMobile is a good fit when you want to:\n\n- Explore network shares made available through Sambee.\n- View images, read PDFs, and edit Markdown files.\n- Share content from file servers on mobile platforms.\n\n## What Changes on Mobile\n\nCompared with desktop, mobile navigation is more compact:\n\n- The interface focuses on single-pane navigation.\n- Toolbar space is tighter.\n- Some desktop-oriented browser controls are simplified or moved behind menus.\n- Opening files in natively installed apps is not available.\n- Local drive access is not available.\n\n## Back, Forward, and Bookmarks\n\nOpening or closing a file, entering or leaving its editor, moving between gallery images, and navigating or closing settings update the browser address and add history entries. You can bookmark or share that address on desktop or mobile. The recipient still needs access to the connection and file; local-drive links also need a paired companion with that drive available.\n\nUse browser Back to retrace your navigation steps. If you open an image and close it, Back reopens that image; another Back returns to the file list from before you opened it. Forward follows those same locations in the other direction. Reopening an editor checks access and obtains a new edit lock. History doesn't undo saved file changes or restore discarded edits. Starting a new navigation after Back replaces the old Forward branch.\n\nIf you have unsaved edits, Back or another navigation asks you to **Save**, **Discard**, or **Cancel**. Cancel keeps your draft and current location. A failed save keeps you in the editor. Your browser can also warn before reloading or closing a tab with unsaved edits.\n\nSettings **Close** reveals the underlying workspace and adds a history entry, so browser Back reopens the last settings category. Closing a directly opened viewer or settings bookmark also adds an entry without sending you to an unrelated page. The mobile settings back arrow follows your history; without an earlier location observed in this workspace, it uses an in-app parent. Resizing between phone and desktop layouts keeps the selected settings category.\n\nRefreshing a bookmark restores its requested location, not a different workspace saved earlier in the tab. A missing file or unavailable connection offers recovery actions rather than silently opening another file.\n\n## Share Files and Text\n\nOn a phone, use **Share** in a file's action menu, or select several files and choose **Share** from the selection menu. Sambee prepares the stored files first. When they're ready, tap **Share** to open your device's share sheet. Multiple files are submitted together; Sambee doesn't silently drop files or retry a smaller selection.\n\nImage and PDF viewers have a sharing icon in the top bar. They share the resource you're viewing, including a compatible converted image or normalized PDF when needed. An image's extension matches the shared format. PDF sharing includes the whole displayed document, not just the visible page. Sharing from the file list instead uses the stored files without viewer conversions.\n\nIn text and Markdown viewers and editors, the same sharing icon opens two choices:\n\n- **Share as file** shares the saved file without saving your edits first.\n- **Share as text** shares the loaded text or your current editor contents, including unsaved changes. Markdown is shared as source text, not rendered HTML.\n\nThe file choice shows a preparation indicator while its attachment loads. You can still share text independently of that preparation.\n\nSharing availability and accepted attachment types depend on your browser and device. A browser can reject an attachment even after its capability check succeeds. Sambee won't silently replace a rejected attachment with text; choose **Share as text** explicitly where available.\n\n### If Sharing Fails\n\nWhen a prepared attachment can't be shared, use **Download** and try sharing it from your device's Files app. For failed image/PDF viewer sharing, this recovery download uses the same displayed resource. Ordinary download controls keep their existing behavior. For several files, download each prepared file in turn. If attachment preparation fails, text and Markdown viewers offer **Retry** without automatically opening the share sheet.\n\nChoose **Details** in sharing-failure feedback to open a diagnostic report. The copy icon copies the report; if clipboard access isn't available, select the report to copy it manually. The report excludes file names, paths, shared text, file contents, and credentials. Sambee doesn't upload it automatically. Closing Details keeps the failure feedback and its recovery actions available.\n\nCancelling the native share sheet doesn't show an error. Completion of the browser's share request doesn't confirm what a receiving app received.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:user-guide/viewing-and-editing-files", "parent_id": "book:user-guide", "depth": 1, "kind": "section", "label": "viewing-and-editing-files", "title": "Viewing \u0026 Editing Files", "path": "user-guide/viewing-and-editing-files", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:user-guide/viewing-and-editing-files/view-images-and-read-documents", "parent_id": "section:user-guide/viewing-and-editing-files", "depth": 2, "kind": "page", "label": "view-images-and-read-documents", "title": "View Images And Read Documents", "path": "user-guide/viewing-and-editing-files/view-images-and-read-documents", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"View Images \u0026 Read Documents\"\n+++\n\nSambee can display many types of files directly in the browser.\n\n## Images\n\nThe image viewer is optimized for speed and efficiency, making it possible to browse even large collections of high-resolution images smoothly.\n\nWhen possible, Sambee passes images through unchanged from storage to the browser. This happens when the file size is not too large and the image format is natively supported by browsers. In all other cases, images are converted on the fly on the server. This typically takes only a few hundred milliseconds and enables Sambee to support a [wide range of image formats](../../reference/supported-file-formats/).\n\nSambee's image viewer comes with controls such as:\n\n- Zoom\n- Pan\n- Rotate\n- Full-screen\n- Previous/next\n- Download\n\nWhile the image viewer optimizes images for display in the browser, downloaded images are always the unaltered original.\n\n## PDFs\n\nPDF files are preprocessed on the server to maximize compatibility and potentially reduce file size.\n\nSambee's PDF viewer comes with controls such as:\n\n- Search\n- Zoom\n- Pan\n- Rotate\n- Full-screen\n- Previous/next\n- Download\n\nPDF search works in any PDF document that has a text layer.\n\nWhile the PDF viewer optimizes documents for display in the browser, downloaded files are always the unaltered original.\n\n## Markdown\n\nMarkdown files are shown fully rendered for easier reading rather than as raw source code.\n\nSambee's Markdown viewer comes with controls such as:\n\n- Search\n- Full-screen\n- Previous/next\n- Download\n\nMarkdown editing is covered separately in [Edit Markdown](../edit-markdown/).\n\n## Full List of Supported File Types\n\nSee [Supported File Formats](../../reference/supported-file-formats/) for a complete list of supported file types.\n", "0.8": "+++\ntitle = \"View Images \u0026 Read Documents\"\n+++\n\nSambee can display many types of files directly in the browser.\n\n## Images\n\nThe image viewer is optimized for speed and efficiency, making it possible to browse even large collections of high-resolution images smoothly.\n\nWhen possible, Sambee passes images through unchanged from storage to the browser. This happens when the file size is not too large and the image format is natively supported by browsers. In all other cases, images are converted on the fly on the server. This typically takes only a few hundred milliseconds and enables Sambee to support a [wide range of image formats](../../reference/supported-file-formats/).\n\nSambee's image viewer comes with controls such as:\n\n- Zoom\n- Pan\n- Rotate\n- Full-screen\n- Previous/next\n- Download\n\nWhile the image viewer optimizes images for display in the browser, downloaded images are always the unaltered original.\n\n## PDFs\n\nPDF files are preprocessed on the server to maximize compatibility and potentially reduce file size.\n\nSambee's PDF viewer comes with controls such as:\n\n- Search\n- Zoom\n- Pan\n- Rotate\n- Full-screen\n- Previous/next\n- Download\n\nPDF search works in any PDF document that has a text layer.\n\nWhile the PDF viewer optimizes documents for display in the browser, downloaded files are always the unaltered original.\n\n## Markdown\n\nMarkdown files are shown fully rendered for easier reading rather than as raw source code.\n\nSambee's Markdown viewer comes with controls such as:\n\n- Search\n- Full-screen\n- Previous/next\n- Download\n\nMarkdown editing is covered separately in [Edit Markdown](../edit-markdown/).\n\n## Full List of Supported File Types\n\nSee [Supported File Formats](../../reference/supported-file-formats/) for a complete list of supported file types.\n", "0.9": "+++\ntitle = \"View Images \u0026 Read Documents\"\n+++\n\nSambee can display many types of files directly in the browser.\n\n## Images\n\nThe image viewer is optimized for speed and efficiency, making it possible to browse even large collections of high-resolution images smoothly.\n\nWhen possible, Sambee passes images through unchanged from storage to the browser. This happens when the file size is not too large and the image format is natively supported by browsers. In all other cases, images are converted on the fly on the server. This typically takes only a few hundred milliseconds and enables Sambee to support a [wide range of image formats](../../reference/supported-file-formats/).\n\nSambee's image viewer comes with controls such as:\n\n- Zoom\n- Pan\n- Rotate\n- Full-screen\n- Previous/next\n- Download\n\nWhile the image viewer optimizes images for display in the browser, downloaded images are always the unaltered original.\n\n## PDFs\n\nPDF files are preprocessed on the server to maximize compatibility and potentially reduce file size.\n\nSambee's PDF viewer comes with controls such as:\n\n- Search\n- Zoom\n- Pan\n- Rotate\n- Full-screen\n- Previous/next\n- Download\n\nPDF search works in any PDF document that has a text layer.\n\nWhile the PDF viewer optimizes documents for display in the browser, downloaded files are always the unaltered original.\n\n## Markdown\n\nMarkdown files are shown fully rendered for easier reading rather than as raw source code.\n\nSambee's Markdown viewer comes with controls such as:\n\n- Search\n- Full-screen\n- Previous/next\n- Download\n\nMarkdown editing is covered separately in [Edit Markdown](../edit-markdown/).\n\n## Full List of Supported File Types\n\nSee [Supported File Formats](../../reference/supported-file-formats/) for a complete list of supported file types.\n", "1.0": "+++\ntitle = \"View Images \u0026 Read Documents\"\n+++\n\nSambee can display many types of files directly in the browser.\n\n## Images\n\nThe image viewer is optimized for speed and efficiency, making it possible to browse even large collections of high-resolution images smoothly.\n\nWhen possible, Sambee passes images through unchanged from storage to the browser. This happens when the file size is not too large and the image format is natively supported by browsers. In all other cases, images are converted on the fly on the server. This typically takes only a few hundred milliseconds and enables Sambee to support a [wide range of image formats](../../reference/supported-file-formats/).\n\nSambee's image viewer comes with controls such as:\n\n- Zoom\n- Pan\n- Rotate\n- Full-screen\n- Previous/next\n- Download\n\nWhile the image viewer optimizes images for display in the browser, downloaded images are always the unaltered original.\n\n## PDFs\n\nPDF files are preprocessed on the server to maximize compatibility and potentially reduce file size.\n\nSambee's PDF viewer comes with controls such as:\n\n- Search\n- Zoom\n- Pan\n- Rotate\n- Full-screen\n- Previous/next\n- Download\n\nPDF search works in any PDF document that has a text layer.\n\nWhile the PDF viewer optimizes documents for display in the browser, downloaded files are always the unaltered original.\n\n## Markdown\n\nMarkdown files are shown fully rendered for easier reading rather than as raw source code.\n\nSambee's Markdown viewer comes with controls such as:\n\n- Search\n- Full-screen\n- Previous/next\n- Download\n\nMarkdown editing is covered separately in [Edit Markdown](../edit-markdown/).\n\n## Full List of Supported File Types\n\nSee [Supported File Formats](../../reference/supported-file-formats/) for a complete list of supported file types.\n", "2.0": "+++\ntitle = \"View Images \u0026 Read Documents\"\n+++\n\nSambee can display many types of files directly in the browser.\n\n## Images\n\nThe image viewer is optimized for speed and efficiency, making it possible to browse even large collections of high-resolution images smoothly.\n\nWhen possible, Sambee passes images through unchanged from storage to the browser. This happens when the file size is not too large and the image format is natively supported by browsers. In all other cases, images are converted on the fly on the server. This typically takes only a few hundred milliseconds and enables Sambee to support a [wide range of image formats](../../reference/supported-file-formats/).\n\nSambee's image viewer comes with controls such as:\n\n- Zoom\n- Pan\n- Rotate\n- Full-screen\n- Previous/next\n- Download\n\nWhile the image viewer optimizes images for display in the browser, downloaded images are always the unaltered original.\n\n## PDFs\n\nPDF files are preprocessed on the server to maximize compatibility and potentially reduce file size.\n\nSambee's PDF viewer comes with controls such as:\n\n- Search\n- Zoom\n- Pan\n- Rotate\n- Full-screen\n- Previous/next\n- Download\n\nPDF search works in any PDF document that has a text layer.\n\nWhile the PDF viewer optimizes documents for display in the browser, downloaded files are always the unaltered original.\n\n## Markdown\n\nMarkdown files are shown fully rendered for easier reading rather than as raw source code.\n\nSambee's Markdown viewer comes with controls such as:\n\n- Search\n- Full-screen\n- Previous/next\n- Download\n\nMarkdown editing is covered separately in [Edit Markdown](../edit-markdown/).\n\n## Full List of Supported File Types\n\nSee [Supported File Formats](../../reference/supported-file-formats/) for a complete list of supported file types.\n"}, "page_contents": {"0.7": "+++\ntitle = \"View Images \u0026 Read Documents\"\n+++\n\nSambee can display many types of files directly in the browser.\n\n## Images\n\nThe image viewer is optimized for speed and efficiency, making it possible to browse even large collections of high-resolution images smoothly.\n\nWhen possible, Sambee passes images through unchanged from storage to the browser. This happens when the file size is not too large and the image format is natively supported by browsers. In all other cases, images are converted on the fly on the server. This typically takes only a few hundred milliseconds and enables Sambee to support a [wide range of image formats](../../reference/supported-file-formats/).\n\nSambee's image viewer comes with controls such as:\n\n- Zoom\n- Pan\n- Rotate\n- Full-screen\n- Previous/next\n- Download\n\nWhile the image viewer optimizes images for display in the browser, downloaded images are always the unaltered original.\n\n## PDFs\n\nPDF files are preprocessed on the server to maximize compatibility and potentially reduce file size.\n\nSambee's PDF viewer comes with controls such as:\n\n- Search\n- Zoom\n- Pan\n- Rotate\n- Full-screen\n- Previous/next\n- Download\n\nPDF search works in any PDF document that has a text layer.\n\nWhile the PDF viewer optimizes documents for display in the browser, downloaded files are always the unaltered original.\n\n## Markdown\n\nMarkdown files are shown fully rendered for easier reading rather than as raw source code.\n\nSambee's Markdown viewer comes with controls such as:\n\n- Search\n- Full-screen\n- Previous/next\n- Download\n\nMarkdown editing is covered separately in [Edit Markdown](../edit-markdown/).\n\n## Full List of Supported File Types\n\nSee [Supported File Formats](../../reference/supported-file-formats/) for a complete list of supported file types.\n", "0.8": "+++\ntitle = \"View Images \u0026 Read Documents\"\n+++\n\nSambee can display many types of files directly in the browser.\n\n## Images\n\nThe image viewer is optimized for speed and efficiency, making it possible to browse even large collections of high-resolution images smoothly.\n\nWhen possible, Sambee passes images through unchanged from storage to the browser. This happens when the file size is not too large and the image format is natively supported by browsers. In all other cases, images are converted on the fly on the server. This typically takes only a few hundred milliseconds and enables Sambee to support a [wide range of image formats](../../reference/supported-file-formats/).\n\nSambee's image viewer comes with controls such as:\n\n- Zoom\n- Pan\n- Rotate\n- Full-screen\n- Previous/next\n- Download\n\nWhile the image viewer optimizes images for display in the browser, downloaded images are always the unaltered original.\n\n## PDFs\n\nPDF files are preprocessed on the server to maximize compatibility and potentially reduce file size.\n\nSambee's PDF viewer comes with controls such as:\n\n- Search\n- Zoom\n- Pan\n- Rotate\n- Full-screen\n- Previous/next\n- Download\n\nPDF search works in any PDF document that has a text layer.\n\nWhile the PDF viewer optimizes documents for display in the browser, downloaded files are always the unaltered original.\n\n## Markdown\n\nMarkdown files are shown fully rendered for easier reading rather than as raw source code.\n\nSambee's Markdown viewer comes with controls such as:\n\n- Search\n- Full-screen\n- Previous/next\n- Download\n\nMarkdown editing is covered separately in [Edit Markdown](../edit-markdown/).\n\n## Full List of Supported File Types\n\nSee [Supported File Formats](../../reference/supported-file-formats/) for a complete list of supported file types.\n", "0.9": "+++\ntitle = \"View Images \u0026 Read Documents\"\n+++\n\nSambee can display many types of files directly in the browser.\n\n## Images\n\nThe image viewer is optimized for speed and efficiency, making it possible to browse even large collections of high-resolution images smoothly.\n\nWhen possible, Sambee passes images through unchanged from storage to the browser. This happens when the file size is not too large and the image format is natively supported by browsers. In all other cases, images are converted on the fly on the server. This typically takes only a few hundred milliseconds and enables Sambee to support a [wide range of image formats](../../reference/supported-file-formats/).\n\nSambee's image viewer comes with controls such as:\n\n- Zoom\n- Pan\n- Rotate\n- Full-screen\n- Previous/next\n- Download\n\nWhile the image viewer optimizes images for display in the browser, downloaded images are always the unaltered original.\n\n## PDFs\n\nPDF files are preprocessed on the server to maximize compatibility and potentially reduce file size.\n\nSambee's PDF viewer comes with controls such as:\n\n- Search\n- Zoom\n- Pan\n- Rotate\n- Full-screen\n- Previous/next\n- Download\n\nPDF search works in any PDF document that has a text layer.\n\nWhile the PDF viewer optimizes documents for display in the browser, downloaded files are always the unaltered original.\n\n## Markdown\n\nMarkdown files are shown fully rendered for easier reading rather than as raw source code.\n\nSambee's Markdown viewer comes with controls such as:\n\n- Search\n- Full-screen\n- Previous/next\n- Download\n\nMarkdown editing is covered separately in [Edit Markdown](../edit-markdown/).\n\n## Full List of Supported File Types\n\nSee [Supported File Formats](../../reference/supported-file-formats/) for a complete list of supported file types.\n", "1.0": "+++\ntitle = \"View Images \u0026 Read Documents\"\n+++\n\nSambee can display many types of files directly in the browser.\n\n## Images\n\nThe image viewer is optimized for speed and efficiency, making it possible to browse even large collections of high-resolution images smoothly.\n\nWhen possible, Sambee passes images through unchanged from storage to the browser. This happens when the file size is not too large and the image format is natively supported by browsers. In all other cases, images are converted on the fly on the server. This typically takes only a few hundred milliseconds and enables Sambee to support a [wide range of image formats](../../reference/supported-file-formats/).\n\nSambee's image viewer comes with controls such as:\n\n- Zoom\n- Pan\n- Rotate\n- Full-screen\n- Previous/next\n- Download\n\nWhile the image viewer optimizes images for display in the browser, downloaded images are always the unaltered original.\n\n## PDFs\n\nPDF files are preprocessed on the server to maximize compatibility and potentially reduce file size.\n\nSambee's PDF viewer comes with controls such as:\n\n- Search\n- Zoom\n- Pan\n- Rotate\n- Full-screen\n- Previous/next\n- Download\n\nPDF search works in any PDF document that has a text layer.\n\nWhile the PDF viewer optimizes documents for display in the browser, downloaded files are always the unaltered original.\n\n## Markdown\n\nMarkdown files are shown fully rendered for easier reading rather than as raw source code.\n\nSambee's Markdown viewer comes with controls such as:\n\n- Search\n- Full-screen\n- Previous/next\n- Download\n\nMarkdown editing is covered separately in [Edit Markdown](../edit-markdown/).\n\n## Full List of Supported File Types\n\nSee [Supported File Formats](../../reference/supported-file-formats/) for a complete list of supported file types.\n", "2.0": "+++\ntitle = \"View Images \u0026 Read Documents\"\n+++\n\nSambee can display many types of files directly in the browser.\n\n## Images\n\nThe image viewer is optimized for speed and efficiency, making it possible to browse even large collections of high-resolution images smoothly.\n\nWhen possible, Sambee passes images through unchanged from storage to the browser. This happens when the file size is not too large and the image format is natively supported by browsers. In all other cases, images are converted on the fly on the server. This typically takes only a few hundred milliseconds and enables Sambee to support a [wide range of image formats](../../reference/supported-file-formats/).\n\nSambee's image viewer comes with controls such as:\n\n- Zoom\n- Pan\n- Rotate\n- Full-screen\n- Previous/next\n- Download\n\nWhile the image viewer optimizes images for display in the browser, downloaded images are always the unaltered original.\n\n## PDFs\n\nPDF files are preprocessed on the server to maximize compatibility and potentially reduce file size.\n\nSambee's PDF viewer comes with controls such as:\n\n- Search\n- Zoom\n- Pan\n- Rotate\n- Full-screen\n- Previous/next\n- Download\n\nPDF search works in any PDF document that has a text layer.\n\nWhile the PDF viewer optimizes documents for display in the browser, downloaded files are always the unaltered original.\n\n## Markdown\n\nMarkdown files are shown fully rendered for easier reading rather than as raw source code.\n\nSambee's Markdown viewer comes with controls such as:\n\n- Search\n- Full-screen\n- Previous/next\n- Download\n\nMarkdown editing is covered separately in [Edit Markdown](../edit-markdown/).\n\n## Full List of Supported File Types\n\nSee [Supported File Formats](../../reference/supported-file-formats/) for a complete list of supported file types.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:user-guide/viewing-and-editing-files/edit-markdown", "parent_id": "section:user-guide/viewing-and-editing-files", "depth": 2, "kind": "page", "label": "edit-markdown", "title": "Edit Markdown", "path": "user-guide/viewing-and-editing-files/edit-markdown", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "branched", "source_version": "0.7", "diff_added": 2, "diff_removed": 0}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "branched", "source_version": "0.9", "diff_added": 30, "diff_removed": 2}}, "content_versions": {"0.7": "+++\ntitle = \"Edit Markdown\"\n+++\n\nMarkdown files are opened in Sambee's [Markdown viewer](../view-images-and-read-documents/). From there, you can seamlessly switch to a full-fledged Markdown editor.\n\n## Entering Edit Mode\n\nIn the Markdown viewer's toolbar, click the edit icon or press \u003ckbd\u003eE\u003c/kbd\u003e to switch to the Markdown editor. It opens in rich-text mode, but you can switch to source mode if you prefer to edit raw Markdown.\n\n## Saving Changes\n\nA small indicator next to the file name shows whether the document has unsaved changes. Click the save icon or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e at any time to save the current state of the document.\n\n## Leaving Edit Mode\n\nClick the X icon or press \u003ckbd\u003eEsc\u003c/kbd\u003e to leave the Markdown editor. If there are unsaved changes, you are asked whether to save them.\n", "0.8": "+++\ntitle = \"Edit Markdown\"\n+++\n\nMarkdown files are opened in Sambee's [Markdown viewer](../view-images-and-read-documents/). From there, you can seamlessly switch to a full-fledged Markdown editor.\n\n## Entering Edit Mode\n\nIn the Markdown viewer's toolbar, click the edit icon or press \u003ckbd\u003eE\u003c/kbd\u003e to switch to the Markdown editor. It opens in rich-text mode, but you can switch to source mode if you prefer to edit raw Markdown.\n\n## Saving Changes\n\nA small indicator next to the file name shows whether the document has unsaved changes. Click the save icon or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e at any time to save the current state of the document.\n\n## Leaving Edit Mode\n\nClick the X icon or press \u003ckbd\u003eEsc\u003c/kbd\u003e to leave the Markdown editor. If there are unsaved changes, you are asked whether to save them.\n", "0.9": "+++\ntitle = \"Edit Markdown\"\n+++\n\nMarkdown files are opened in Sambee's [Markdown viewer](../view-images-and-read-documents/). From there, you can seamlessly switch to a full-fledged Markdown editor.\n\n## Entering Edit Mode\n\nIn the Markdown viewer's toolbar, click the edit icon or press \u003ckbd\u003eE\u003c/kbd\u003e to switch to the Markdown editor. It opens in rich-text mode, but you can switch to source mode if you prefer to edit raw Markdown.\n\n## Saving Changes\n\nA small indicator next to the file name shows whether the document has unsaved changes. Click the save icon or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e at any time to save the current state of the document.\n\nIf Sambee must send you through OIDC sign-in while you are editing, it saves an eligible unsaved Markdown draft in this browser tab before leaving the page. See [Recover Unsaved In-Browser Edits](../recover-unsaved-edits/) for how recovery works.\n\n## Leaving Edit Mode\n\nClick the X icon or press \u003ckbd\u003eEsc\u003c/kbd\u003e to leave the Markdown editor. If there are unsaved changes, you are asked whether to save them.\n", "1.0": "+++\ntitle = \"Edit Markdown\"\n+++\n\nMarkdown files are opened in Sambee's [Markdown viewer](../view-images-and-read-documents/). From there, you can seamlessly switch to a full-fledged Markdown editor.\n\n## Entering Edit Mode\n\nIn the Markdown viewer's toolbar, click the edit icon or press \u003ckbd\u003eE\u003c/kbd\u003e to switch to the Markdown editor. It opens in rich-text mode, but you can switch to source mode if you prefer to edit raw Markdown.\n\n## Saving Changes\n\nA small indicator next to the file name shows whether the document has unsaved changes. Click the save icon or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e at any time to save the current state of the document.\n\nIf Sambee must send you through OIDC sign-in while you are editing, it saves an eligible unsaved Markdown draft in this browser tab before leaving the page. See [Recover Unsaved In-Browser Edits](../recover-unsaved-edits/) for how recovery works.\n\n## Leaving Edit Mode\n\nClick the X icon or press \u003ckbd\u003eEsc\u003c/kbd\u003e to leave the Markdown editor. If there are unsaved changes, you are asked whether to save them.\n", "2.0": "+++\ntitle = \"Edit Markdown\"\n+++\n\nMarkdown files are opened in Sambee's [Markdown viewer](../view-images-and-read-documents/). From there, you can seamlessly switch to a full-fledged Markdown editor.\n\n## Entering Edit Mode\n\nIn the Markdown viewer's toolbar, click the edit icon or press \u003ckbd\u003eE\u003c/kbd\u003e to switch to the Markdown editor. You edit Markdown source directly, with highlighted structure and fenced code. Highlighting doesn't change your source text or line layout.\n\n## Code Colors\n\nCode blocks use the same language highlighting as the text viewer and editor. A fence's language label selects its grammar; unknown or unlabelled blocks remain plain text. Preview highlighting loads in the background and waits while you're selecting preview text. Code text, whitespace, copying, and search remain unchanged.\n\nIn **Settings** \u003e **Appearance**, edit or copy a theme and open **Syntax** to adjust the shared keyword, string, number, comment, type, function, operator, and punctuation colors. The palette applies to text viewing/editing and Markdown source/code blocks. Identifiers keep the existing code text color. Changes stay local to the theme draft until saved; Cancel doesn't apply them. Only administrators can save site themes.\n\nExisting complete themes without a Syntax group use the built-in palette matching their light or dark mode. Saving or exporting includes the resolved colors. Updated Sambee versions can import those legacy version-1 exports, but older releases may reject exports containing the new roles. Very large code blocks can remain plain text without truncating their contents.\n\n## Large Documents\n\nLarge Markdown previews appear progressively. You can read the text already displayed or close the viewer while loading continues. Search, editing, heading links and the toolbar's Print action become available when the complete document is ready. Printing from the browser menu before then shows a loading notice instead of an incomplete document.\n\nLarge previews can briefly pause while loading, and code colors can arrive after the text. Large Replace All operations show busy feedback before applying the complete replacement, but the editor and indicator can pause during that step. Editing very large tables can also be slow. These limitations don't shorten the document or split a replacement into separate undo steps.\n\n## Saving Changes\n\nA small indicator next to the file name shows whether the document has unsaved changes. Click the save icon or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e at any time to save the current state of the document.\n\nFinish any input-method composition before saving. Sambee waits for table-cell edits to reach the document before capturing the saved text. If that can't finish, the editor stays open with your changes rather than saving an incomplete cell. Retry Save after the edit finishes.\n\nYou can keep editing during an ordinary Save. Save writes the revision it captured; edits made afterward remain unsaved. If preparation or writing fails, your changes remain available in the editor.\n\nIf Sambee must send you through OIDC sign-in while you are editing, it saves an eligible unsaved Markdown draft in this browser tab before leaving the page. See [Recover Unsaved In-Browser Edits](../recover-unsaved-edits/) for how recovery works.\n\n## Leaving Edit Mode\n\nClick the X icon or press \u003ckbd\u003eEsc\u003c/kbd\u003e to leave the Markdown editor and return to the viewer. If there are unsaved changes, choose **Save** to save them and return to the viewer, **Discard** to return without saving, or **Cancel** to keep editing. If saving fails, the editor stays open with your changes.\n\nFrom the viewer, click the X icon again to return to the file list. The text editor uses the same two-step close sequence.\n\n## Print Or Save As PDF\n\nIn the Markdown viewer, click the printer icon to open your browser's print dialog. Choose a printer or **Save as PDF** if your browser offers it. You can also use **Print** from the browser menu. Paper size, margins and headers/footers are controlled by that dialog.\n\nThe output contains the rendered document, without Sambee's toolbar or file browser. Text prints black on white in both themes. Long code lines and table cells wrap to fit the page, and images are included. Printing doesn't modify the Markdown file.\n\nPrint is available in the viewer, not the editor. To print your latest changes, save them and return to the viewer first. Closing or cancelling the print dialog leaves the viewer open.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Edit Markdown\"\n+++\n\nMarkdown files are opened in Sambee's [Markdown viewer](../view-images-and-read-documents/). From there, you can seamlessly switch to a full-fledged Markdown editor.\n\n## Entering Edit Mode\n\nIn the Markdown viewer's toolbar, click the edit icon or press \u003ckbd\u003eE\u003c/kbd\u003e to switch to the Markdown editor. It opens in rich-text mode, but you can switch to source mode if you prefer to edit raw Markdown.\n\n## Saving Changes\n\nA small indicator next to the file name shows whether the document has unsaved changes. Click the save icon or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e at any time to save the current state of the document.\n\n## Leaving Edit Mode\n\nClick the X icon or press \u003ckbd\u003eEsc\u003c/kbd\u003e to leave the Markdown editor. If there are unsaved changes, you are asked whether to save them.\n", "0.8": "+++\ntitle = \"Edit Markdown\"\n+++\n\nMarkdown files are opened in Sambee's [Markdown viewer](../view-images-and-read-documents/). From there, you can seamlessly switch to a full-fledged Markdown editor.\n\n## Entering Edit Mode\n\nIn the Markdown viewer's toolbar, click the edit icon or press \u003ckbd\u003eE\u003c/kbd\u003e to switch to the Markdown editor. It opens in rich-text mode, but you can switch to source mode if you prefer to edit raw Markdown.\n\n## Saving Changes\n\nA small indicator next to the file name shows whether the document has unsaved changes. Click the save icon or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e at any time to save the current state of the document.\n\n## Leaving Edit Mode\n\nClick the X icon or press \u003ckbd\u003eEsc\u003c/kbd\u003e to leave the Markdown editor. If there are unsaved changes, you are asked whether to save them.\n", "0.9": "+++\ntitle = \"Edit Markdown\"\n+++\n\nMarkdown files are opened in Sambee's [Markdown viewer](../view-images-and-read-documents/). From there, you can seamlessly switch to a full-fledged Markdown editor.\n\n## Entering Edit Mode\n\nIn the Markdown viewer's toolbar, click the edit icon or press \u003ckbd\u003eE\u003c/kbd\u003e to switch to the Markdown editor. It opens in rich-text mode, but you can switch to source mode if you prefer to edit raw Markdown.\n\n## Saving Changes\n\nA small indicator next to the file name shows whether the document has unsaved changes. Click the save icon or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e at any time to save the current state of the document.\n\nIf Sambee must send you through OIDC sign-in while you are editing, it saves an eligible unsaved Markdown draft in this browser tab before leaving the page. See [Recover Unsaved In-Browser Edits](../recover-unsaved-edits/) for how recovery works.\n\n## Leaving Edit Mode\n\nClick the X icon or press \u003ckbd\u003eEsc\u003c/kbd\u003e to leave the Markdown editor. If there are unsaved changes, you are asked whether to save them.\n", "1.0": "+++\ntitle = \"Edit Markdown\"\n+++\n\nMarkdown files are opened in Sambee's [Markdown viewer](../view-images-and-read-documents/). From there, you can seamlessly switch to a full-fledged Markdown editor.\n\n## Entering Edit Mode\n\nIn the Markdown viewer's toolbar, click the edit icon or press \u003ckbd\u003eE\u003c/kbd\u003e to switch to the Markdown editor. It opens in rich-text mode, but you can switch to source mode if you prefer to edit raw Markdown.\n\n## Saving Changes\n\nA small indicator next to the file name shows whether the document has unsaved changes. Click the save icon or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e at any time to save the current state of the document.\n\nIf Sambee must send you through OIDC sign-in while you are editing, it saves an eligible unsaved Markdown draft in this browser tab before leaving the page. See [Recover Unsaved In-Browser Edits](../recover-unsaved-edits/) for how recovery works.\n\n## Leaving Edit Mode\n\nClick the X icon or press \u003ckbd\u003eEsc\u003c/kbd\u003e to leave the Markdown editor. If there are unsaved changes, you are asked whether to save them.\n", "2.0": "+++\ntitle = \"Edit Markdown\"\n+++\n\nMarkdown files are opened in Sambee's [Markdown viewer](../view-images-and-read-documents/). From there, you can seamlessly switch to a full-fledged Markdown editor.\n\n## Entering Edit Mode\n\nIn the Markdown viewer's toolbar, click the edit icon or press \u003ckbd\u003eE\u003c/kbd\u003e to switch to the Markdown editor. You edit Markdown source directly, with highlighted structure and fenced code. Highlighting doesn't change your source text or line layout.\n\n## Code Colors\n\nCode blocks use the same language highlighting as the text viewer and editor. A fence's language label selects its grammar; unknown or unlabelled blocks remain plain text. Preview highlighting loads in the background and waits while you're selecting preview text. Code text, whitespace, copying, and search remain unchanged.\n\nIn **Settings** \u003e **Appearance**, edit or copy a theme and open **Syntax** to adjust the shared keyword, string, number, comment, type, function, operator, and punctuation colors. The palette applies to text viewing/editing and Markdown source/code blocks. Identifiers keep the existing code text color. Changes stay local to the theme draft until saved; Cancel doesn't apply them. Only administrators can save site themes.\n\nExisting complete themes without a Syntax group use the built-in palette matching their light or dark mode. Saving or exporting includes the resolved colors. Updated Sambee versions can import those legacy version-1 exports, but older releases may reject exports containing the new roles. Very large code blocks can remain plain text without truncating their contents.\n\n## Large Documents\n\nLarge Markdown previews appear progressively. You can read the text already displayed or close the viewer while loading continues. Search, editing, heading links and the toolbar's Print action become available when the complete document is ready. Printing from the browser menu before then shows a loading notice instead of an incomplete document.\n\nLarge previews can briefly pause while loading, and code colors can arrive after the text. Large Replace All operations show busy feedback before applying the complete replacement, but the editor and indicator can pause during that step. Editing very large tables can also be slow. These limitations don't shorten the document or split a replacement into separate undo steps.\n\n## Saving Changes\n\nA small indicator next to the file name shows whether the document has unsaved changes. Click the save icon or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e at any time to save the current state of the document.\n\nFinish any input-method composition before saving. Sambee waits for table-cell edits to reach the document before capturing the saved text. If that can't finish, the editor stays open with your changes rather than saving an incomplete cell. Retry Save after the edit finishes.\n\nYou can keep editing during an ordinary Save. Save writes the revision it captured; edits made afterward remain unsaved. If preparation or writing fails, your changes remain available in the editor.\n\nIf Sambee must send you through OIDC sign-in while you are editing, it saves an eligible unsaved Markdown draft in this browser tab before leaving the page. See [Recover Unsaved In-Browser Edits](../recover-unsaved-edits/) for how recovery works.\n\n## Leaving Edit Mode\n\nClick the X icon or press \u003ckbd\u003eEsc\u003c/kbd\u003e to leave the Markdown editor and return to the viewer. If there are unsaved changes, choose **Save** to save them and return to the viewer, **Discard** to return without saving, or **Cancel** to keep editing. If saving fails, the editor stays open with your changes.\n\nFrom the viewer, click the X icon again to return to the file list. The text editor uses the same two-step close sequence.\n\n## Print Or Save As PDF\n\nIn the Markdown viewer, click the printer icon to open your browser's print dialog. Choose a printer or **Save as PDF** if your browser offers it. You can also use **Print** from the browser menu. Paper size, margins and headers/footers are controlled by that dialog.\n\nThe output contains the rendered document, without Sambee's toolbar or file browser. Text prints black on white in both themes. Long code lines and table cells wrap to fit the page, and images are included. Printing doesn't modify the Markdown file.\n\nPrint is available in the viewer, not the editor. To print your latest changes, save them and return to the viewer first. Closing or cancelling the print dialog leaves the viewer open.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:user-guide/viewing-and-editing-files/edit-files-in-desktop-apps", "parent_id": "section:user-guide/viewing-and-editing-files", "depth": 2, "kind": "page", "label": "edit-files-in-desktop-apps", "title": "Edit Files In Desktop Apps", "path": "user-guide/viewing-and-editing-files/edit-files-in-desktop-apps", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Edit Files in Desktop Apps\"\n+++\n\nSambee can open files in installed desktop apps through its Companion helper. If the file is on a local drive, the desktop app can access it directly. In that case, Companion opens the app with the original file path.\n\nIf the file is on one of Sambee's SMB connections, the desktop app cannot access it directly. In that case, Companion opens a temporary local copy in the desktop app and synchronizes your changes back to the original location.\n\nThe remainder of this page describes the second case.\n\n## Before You Begin\n\nYou need:\n\n- Sambee Companion installed and running on your computer.\n- A desktop app that can open the file type you want to edit.\n\nNeed Companion first? Start with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/).\n\n## Start the Editing Workflow\n\nIn Sambee, right-click the file and choose **Open in companion app**, or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nSambee hands the request to Companion through a `sambee://` link. When your browser asks whether to allow that link to open, choose **yes**.\n{{\u003c /admonition \u003e}}\n\n{{\u003c admonition type=\"note\" \u003e}}\nIf your Sambee site is behind a proxy server, Companion may show a separate **Sambee Authentication** window before opening the file. Sign in there and then continue the desktop-editing workflow.\n{{\u003c /admonition \u003e}}\n\n### What Happens Under the Hood\n\nCompanion handles the rest of the edit session:\n\n- It acquires an edit lock for the file on the file share.\n- It downloads the file and stores a temporary local copy.\n- If needed, it asks you which desktop app should open the file.\n- It opens the local copy in that app.\n- It shows a **Done Editing** window, which you use to upload the modified local copy when you are done.\n\n## Choose an App to Open the File\n\nThe first time you open a file type, Companion may show an app picker listing the installed apps available for that file type. Choose an app from the list for that extension and optionally remember that choice for later. For app-selection help, use [Desktop App Picker](../../companion-app/desktop-app-picker/).\n\n## Finish the Editing Session\n\nClosing the desktop app by itself does not upload the file and does not finish the session. Uploading is initiated in the **Done Editing** window.\n\n- Changed file: use **Done Editing \u2014 Hold to Upload**.\n- Unchanged file: use **Done Editing \u2014 Hold to Close**.\n- Do not want to keep the local changes: use **Discard Changes \u2014 Hold**.\n\nIf the **Done Editing** window tells you that the session expired, authentication failed, the lock was lost, or recovery is required, reopen the file from Sambee instead of retrying the old desktop-editing session indefinitely. That starts a fresh authenticated edit session with a new server-side lock.\n", "0.8": "+++\ntitle = \"Edit Files in Desktop Apps\"\n+++\n\nSambee can open files in installed desktop apps through its Companion helper. If the file is on a local drive, the desktop app can access it directly. In that case, Companion opens the app with the original file path.\n\nIf the file is on one of Sambee's SMB connections, the desktop app cannot access it directly. In that case, Companion opens a temporary local copy in the desktop app and synchronizes your changes back to the original location.\n\nThe remainder of this page describes the second case.\n\n## Before You Begin\n\nYou need:\n\n- Sambee Companion installed and running on your computer.\n- A desktop app that can open the file type you want to edit.\n\nNeed Companion first? Start with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/).\n\n## Start the Editing Workflow\n\nIn Sambee, right-click the file and choose **Open in companion app**, or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nSambee hands the request to Companion through a `sambee://` link. When your browser asks whether to allow that link to open, choose **yes**.\n{{\u003c /admonition \u003e}}\n\n{{\u003c admonition type=\"note\" \u003e}}\nIf your Sambee site is behind a proxy server, Companion may show a separate **Sambee Authentication** window before opening the file. Sign in there and then continue the desktop-editing workflow.\n{{\u003c /admonition \u003e}}\n\n### What Happens Under the Hood\n\nCompanion handles the rest of the edit session:\n\n- It acquires an edit lock for the file on the file share.\n- It downloads the file and stores a temporary local copy.\n- If needed, it asks you which desktop app should open the file.\n- It opens the local copy in that app.\n- It shows a **Done Editing** window, which you use to upload the modified local copy when you are done.\n\n## Choose an App to Open the File\n\nThe first time you open a file type, Companion may show an app picker listing the installed apps available for that file type. Choose an app from the list for that extension and optionally remember that choice for later. For app-selection help, use [Desktop App Picker](../../companion-app/desktop-app-picker/).\n\n## Finish the Editing Session\n\nClosing the desktop app by itself does not upload the file and does not finish the session. Uploading is initiated in the **Done Editing** window.\n\n- Changed file: use **Done Editing \u2014 Hold to Upload**.\n- Unchanged file: use **Done Editing \u2014 Hold to Close**.\n- Do not want to keep the local changes: use **Discard Changes \u2014 Hold**.\n\nIf the **Done Editing** window tells you that the session expired, authentication failed, the lock was lost, or recovery is required, reopen the file from Sambee instead of retrying the old desktop-editing session indefinitely. That starts a fresh authenticated edit session with a new server-side lock.\n", "0.9": "+++\ntitle = \"Edit Files in Desktop Apps\"\n+++\n\nSambee can open files in installed desktop apps through its Companion helper. If the file is on a local drive, the desktop app can access it directly. In that case, Companion opens the app with the original file path.\n\nIf the file is on one of Sambee's SMB connections, the desktop app cannot access it directly. In that case, Companion opens a temporary local copy in the desktop app and synchronizes your changes back to the original location.\n\nThe remainder of this page describes the second case.\n\n## Before You Begin\n\nYou need:\n\n- Sambee Companion installed and running on your computer.\n- A desktop app that can open the file type you want to edit.\n\nNeed Companion first? Start with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/).\n\n## Start the Editing Workflow\n\nIn Sambee, right-click the file and choose **Open in companion app**, or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nSambee hands the request to Companion through a `sambee://` link. When your browser asks whether to allow that link to open, choose **yes**.\n{{\u003c /admonition \u003e}}\n\n{{\u003c admonition type=\"note\" \u003e}}\nIf your Sambee site is behind a proxy server, Companion may show a separate **Sambee Authentication** window before opening the file. Sign in there and then continue the desktop-editing workflow.\n{{\u003c /admonition \u003e}}\n\n### What Happens Under the Hood\n\nCompanion handles the rest of the edit session:\n\n- It acquires an edit lock for the file on the file share.\n- It downloads the file and stores a temporary local copy.\n- If needed, it asks you which desktop app should open the file.\n- It opens the local copy in that app.\n- It shows a **Done Editing** window, which you use to upload the modified local copy when you are done.\n\n## Choose an App to Open the File\n\nThe first time you open a file type, Companion may show an app picker listing the installed apps available for that file type. Choose an app from the list for that extension and optionally remember that choice for later. For app-selection help, use [Desktop App Picker](../../companion-app/desktop-app-picker/).\n\n## Finish the Editing Session\n\nClosing the desktop app by itself does not upload the file and does not finish the session. Uploading is initiated in the **Done Editing** window.\n\n- Changed file: use **Done Editing \u2014 Hold to Upload**.\n- Unchanged file: use **Done Editing \u2014 Hold to Close**.\n- Do not want to keep the local changes: use **Discard Changes \u2014 Hold**.\n\nIf the **Done Editing** window tells you that the session expired, authentication failed, the lock was lost, or recovery is required, reopen the file from Sambee instead of retrying the old desktop-editing session indefinitely. That starts a fresh authenticated edit session with a new server-side lock.\n", "1.0": "+++\ntitle = \"Edit Files in Desktop Apps\"\n+++\n\nSambee can open files in installed desktop apps through its Companion helper. If the file is on a local drive, the desktop app can access it directly. In that case, Companion opens the app with the original file path.\n\nIf the file is on one of Sambee's SMB connections, the desktop app cannot access it directly. In that case, Companion opens a temporary local copy in the desktop app and synchronizes your changes back to the original location.\n\nThe remainder of this page describes the second case.\n\n## Before You Begin\n\nYou need:\n\n- Sambee Companion installed and running on your computer.\n- A desktop app that can open the file type you want to edit.\n\nNeed Companion first? Start with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/).\n\n## Start the Editing Workflow\n\nIn Sambee, right-click the file and choose **Open in companion app**, or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nSambee hands the request to Companion through a `sambee://` link. When your browser asks whether to allow that link to open, choose **yes**.\n{{\u003c /admonition \u003e}}\n\n{{\u003c admonition type=\"note\" \u003e}}\nIf your Sambee site is behind a proxy server, Companion may show a separate **Sambee Authentication** window before opening the file. Sign in there and then continue the desktop-editing workflow.\n{{\u003c /admonition \u003e}}\n\n### What Happens Under the Hood\n\nCompanion handles the rest of the edit session:\n\n- It acquires an edit lock for the file on the file share.\n- It downloads the file and stores a temporary local copy.\n- If needed, it asks you which desktop app should open the file.\n- It opens the local copy in that app.\n- It shows a **Done Editing** window, which you use to upload the modified local copy when you are done.\n\n## Choose an App to Open the File\n\nThe first time you open a file type, Companion may show an app picker listing the installed apps available for that file type. Choose an app from the list for that extension and optionally remember that choice for later. For app-selection help, use [Desktop App Picker](../../companion-app/desktop-app-picker/).\n\n## Finish the Editing Session\n\nClosing the desktop app by itself does not upload the file and does not finish the session. Uploading is initiated in the **Done Editing** window.\n\n- Changed file: use **Done Editing \u2014 Hold to Upload**.\n- Unchanged file: use **Done Editing \u2014 Hold to Close**.\n- Do not want to keep the local changes: use **Discard Changes \u2014 Hold**.\n\nIf the **Done Editing** window tells you that the session expired, authentication failed, the lock was lost, or recovery is required, reopen the file from Sambee instead of retrying the old desktop-editing session indefinitely. That starts a fresh authenticated edit session with a new server-side lock.\n", "2.0": "+++\ntitle = \"Edit Files in Desktop Apps\"\n+++\n\nSambee can open files in installed desktop apps through its Companion helper. If the file is on a local drive, the desktop app can access it directly. In that case, Companion opens the app with the original file path.\n\nIf the file is on one of Sambee's SMB connections, the desktop app cannot access it directly. In that case, Companion opens a temporary local copy in the desktop app and synchronizes your changes back to the original location.\n\nThe remainder of this page describes the second case.\n\n## Before You Begin\n\nYou need:\n\n- Sambee Companion installed and running on your computer.\n- A desktop app that can open the file type you want to edit.\n\nNeed Companion first? Start with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/).\n\n## Start the Editing Workflow\n\nIn Sambee, right-click the file and choose **Open in companion app**, or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nSambee hands the request to Companion through a `sambee://` link. When your browser asks whether to allow that link to open, choose **yes**.\n{{\u003c /admonition \u003e}}\n\n{{\u003c admonition type=\"note\" \u003e}}\nIf your Sambee site is behind a proxy server, Companion may show a separate **Sambee Authentication** window before opening the file. Sign in there and then continue the desktop-editing workflow.\n{{\u003c /admonition \u003e}}\n\n### What Happens Under the Hood\n\nCompanion handles the rest of the edit session:\n\n- It acquires an edit lock for the file on the file share.\n- It downloads the file and stores a temporary local copy.\n- If needed, it asks you which desktop app should open the file.\n- It opens the local copy in that app.\n- It shows a **Done Editing** window, which you use to upload the modified local copy when you are done.\n\n## Choose an App to Open the File\n\nThe first time you open a file type, Companion may show an app picker listing the installed apps available for that file type. Choose an app from the list for that extension and optionally remember that choice for later. For app-selection help, use [Desktop App Picker](../../companion-app/desktop-app-picker/).\n\n## Finish the Editing Session\n\nClosing the desktop app by itself does not upload the file and does not finish the session. Uploading is initiated in the **Done Editing** window.\n\n- Changed file: use **Done Editing \u2014 Hold to Upload**.\n- Unchanged file: use **Done Editing \u2014 Hold to Close**.\n- Do not want to keep the local changes: use **Discard Changes \u2014 Hold**.\n\nIf the **Done Editing** window tells you that the session expired, authentication failed, the lock was lost, or recovery is required, reopen the file from Sambee instead of retrying the old desktop-editing session indefinitely. That starts a fresh authenticated edit session with a new server-side lock.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Edit Files in Desktop Apps\"\n+++\n\nSambee can open files in installed desktop apps through its Companion helper. If the file is on a local drive, the desktop app can access it directly. In that case, Companion opens the app with the original file path.\n\nIf the file is on one of Sambee's SMB connections, the desktop app cannot access it directly. In that case, Companion opens a temporary local copy in the desktop app and synchronizes your changes back to the original location.\n\nThe remainder of this page describes the second case.\n\n## Before You Begin\n\nYou need:\n\n- Sambee Companion installed and running on your computer.\n- A desktop app that can open the file type you want to edit.\n\nNeed Companion first? Start with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/).\n\n## Start the Editing Workflow\n\nIn Sambee, right-click the file and choose **Open in companion app**, or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nSambee hands the request to Companion through a `sambee://` link. When your browser asks whether to allow that link to open, choose **yes**.\n{{\u003c /admonition \u003e}}\n\n{{\u003c admonition type=\"note\" \u003e}}\nIf your Sambee site is behind a proxy server, Companion may show a separate **Sambee Authentication** window before opening the file. Sign in there and then continue the desktop-editing workflow.\n{{\u003c /admonition \u003e}}\n\n### What Happens Under the Hood\n\nCompanion handles the rest of the edit session:\n\n- It acquires an edit lock for the file on the file share.\n- It downloads the file and stores a temporary local copy.\n- If needed, it asks you which desktop app should open the file.\n- It opens the local copy in that app.\n- It shows a **Done Editing** window, which you use to upload the modified local copy when you are done.\n\n## Choose an App to Open the File\n\nThe first time you open a file type, Companion may show an app picker listing the installed apps available for that file type. Choose an app from the list for that extension and optionally remember that choice for later. For app-selection help, use [Desktop App Picker](../../companion-app/desktop-app-picker/).\n\n## Finish the Editing Session\n\nClosing the desktop app by itself does not upload the file and does not finish the session. Uploading is initiated in the **Done Editing** window.\n\n- Changed file: use **Done Editing \u2014 Hold to Upload**.\n- Unchanged file: use **Done Editing \u2014 Hold to Close**.\n- Do not want to keep the local changes: use **Discard Changes \u2014 Hold**.\n\nIf the **Done Editing** window tells you that the session expired, authentication failed, the lock was lost, or recovery is required, reopen the file from Sambee instead of retrying the old desktop-editing session indefinitely. That starts a fresh authenticated edit session with a new server-side lock.\n", "0.8": "+++\ntitle = \"Edit Files in Desktop Apps\"\n+++\n\nSambee can open files in installed desktop apps through its Companion helper. If the file is on a local drive, the desktop app can access it directly. In that case, Companion opens the app with the original file path.\n\nIf the file is on one of Sambee's SMB connections, the desktop app cannot access it directly. In that case, Companion opens a temporary local copy in the desktop app and synchronizes your changes back to the original location.\n\nThe remainder of this page describes the second case.\n\n## Before You Begin\n\nYou need:\n\n- Sambee Companion installed and running on your computer.\n- A desktop app that can open the file type you want to edit.\n\nNeed Companion first? Start with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/).\n\n## Start the Editing Workflow\n\nIn Sambee, right-click the file and choose **Open in companion app**, or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nSambee hands the request to Companion through a `sambee://` link. When your browser asks whether to allow that link to open, choose **yes**.\n{{\u003c /admonition \u003e}}\n\n{{\u003c admonition type=\"note\" \u003e}}\nIf your Sambee site is behind a proxy server, Companion may show a separate **Sambee Authentication** window before opening the file. Sign in there and then continue the desktop-editing workflow.\n{{\u003c /admonition \u003e}}\n\n### What Happens Under the Hood\n\nCompanion handles the rest of the edit session:\n\n- It acquires an edit lock for the file on the file share.\n- It downloads the file and stores a temporary local copy.\n- If needed, it asks you which desktop app should open the file.\n- It opens the local copy in that app.\n- It shows a **Done Editing** window, which you use to upload the modified local copy when you are done.\n\n## Choose an App to Open the File\n\nThe first time you open a file type, Companion may show an app picker listing the installed apps available for that file type. Choose an app from the list for that extension and optionally remember that choice for later. For app-selection help, use [Desktop App Picker](../../companion-app/desktop-app-picker/).\n\n## Finish the Editing Session\n\nClosing the desktop app by itself does not upload the file and does not finish the session. Uploading is initiated in the **Done Editing** window.\n\n- Changed file: use **Done Editing \u2014 Hold to Upload**.\n- Unchanged file: use **Done Editing \u2014 Hold to Close**.\n- Do not want to keep the local changes: use **Discard Changes \u2014 Hold**.\n\nIf the **Done Editing** window tells you that the session expired, authentication failed, the lock was lost, or recovery is required, reopen the file from Sambee instead of retrying the old desktop-editing session indefinitely. That starts a fresh authenticated edit session with a new server-side lock.\n", "0.9": "+++\ntitle = \"Edit Files in Desktop Apps\"\n+++\n\nSambee can open files in installed desktop apps through its Companion helper. If the file is on a local drive, the desktop app can access it directly. In that case, Companion opens the app with the original file path.\n\nIf the file is on one of Sambee's SMB connections, the desktop app cannot access it directly. In that case, Companion opens a temporary local copy in the desktop app and synchronizes your changes back to the original location.\n\nThe remainder of this page describes the second case.\n\n## Before You Begin\n\nYou need:\n\n- Sambee Companion installed and running on your computer.\n- A desktop app that can open the file type you want to edit.\n\nNeed Companion first? Start with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/).\n\n## Start the Editing Workflow\n\nIn Sambee, right-click the file and choose **Open in companion app**, or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nSambee hands the request to Companion through a `sambee://` link. When your browser asks whether to allow that link to open, choose **yes**.\n{{\u003c /admonition \u003e}}\n\n{{\u003c admonition type=\"note\" \u003e}}\nIf your Sambee site is behind a proxy server, Companion may show a separate **Sambee Authentication** window before opening the file. Sign in there and then continue the desktop-editing workflow.\n{{\u003c /admonition \u003e}}\n\n### What Happens Under the Hood\n\nCompanion handles the rest of the edit session:\n\n- It acquires an edit lock for the file on the file share.\n- It downloads the file and stores a temporary local copy.\n- If needed, it asks you which desktop app should open the file.\n- It opens the local copy in that app.\n- It shows a **Done Editing** window, which you use to upload the modified local copy when you are done.\n\n## Choose an App to Open the File\n\nThe first time you open a file type, Companion may show an app picker listing the installed apps available for that file type. Choose an app from the list for that extension and optionally remember that choice for later. For app-selection help, use [Desktop App Picker](../../companion-app/desktop-app-picker/).\n\n## Finish the Editing Session\n\nClosing the desktop app by itself does not upload the file and does not finish the session. Uploading is initiated in the **Done Editing** window.\n\n- Changed file: use **Done Editing \u2014 Hold to Upload**.\n- Unchanged file: use **Done Editing \u2014 Hold to Close**.\n- Do not want to keep the local changes: use **Discard Changes \u2014 Hold**.\n\nIf the **Done Editing** window tells you that the session expired, authentication failed, the lock was lost, or recovery is required, reopen the file from Sambee instead of retrying the old desktop-editing session indefinitely. That starts a fresh authenticated edit session with a new server-side lock.\n", "1.0": "+++\ntitle = \"Edit Files in Desktop Apps\"\n+++\n\nSambee can open files in installed desktop apps through its Companion helper. If the file is on a local drive, the desktop app can access it directly. In that case, Companion opens the app with the original file path.\n\nIf the file is on one of Sambee's SMB connections, the desktop app cannot access it directly. In that case, Companion opens a temporary local copy in the desktop app and synchronizes your changes back to the original location.\n\nThe remainder of this page describes the second case.\n\n## Before You Begin\n\nYou need:\n\n- Sambee Companion installed and running on your computer.\n- A desktop app that can open the file type you want to edit.\n\nNeed Companion first? Start with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/).\n\n## Start the Editing Workflow\n\nIn Sambee, right-click the file and choose **Open in companion app**, or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nSambee hands the request to Companion through a `sambee://` link. When your browser asks whether to allow that link to open, choose **yes**.\n{{\u003c /admonition \u003e}}\n\n{{\u003c admonition type=\"note\" \u003e}}\nIf your Sambee site is behind a proxy server, Companion may show a separate **Sambee Authentication** window before opening the file. Sign in there and then continue the desktop-editing workflow.\n{{\u003c /admonition \u003e}}\n\n### What Happens Under the Hood\n\nCompanion handles the rest of the edit session:\n\n- It acquires an edit lock for the file on the file share.\n- It downloads the file and stores a temporary local copy.\n- If needed, it asks you which desktop app should open the file.\n- It opens the local copy in that app.\n- It shows a **Done Editing** window, which you use to upload the modified local copy when you are done.\n\n## Choose an App to Open the File\n\nThe first time you open a file type, Companion may show an app picker listing the installed apps available for that file type. Choose an app from the list for that extension and optionally remember that choice for later. For app-selection help, use [Desktop App Picker](../../companion-app/desktop-app-picker/).\n\n## Finish the Editing Session\n\nClosing the desktop app by itself does not upload the file and does not finish the session. Uploading is initiated in the **Done Editing** window.\n\n- Changed file: use **Done Editing \u2014 Hold to Upload**.\n- Unchanged file: use **Done Editing \u2014 Hold to Close**.\n- Do not want to keep the local changes: use **Discard Changes \u2014 Hold**.\n\nIf the **Done Editing** window tells you that the session expired, authentication failed, the lock was lost, or recovery is required, reopen the file from Sambee instead of retrying the old desktop-editing session indefinitely. That starts a fresh authenticated edit session with a new server-side lock.\n", "2.0": "+++\ntitle = \"Edit Files in Desktop Apps\"\n+++\n\nSambee can open files in installed desktop apps through its Companion helper. If the file is on a local drive, the desktop app can access it directly. In that case, Companion opens the app with the original file path.\n\nIf the file is on one of Sambee's SMB connections, the desktop app cannot access it directly. In that case, Companion opens a temporary local copy in the desktop app and synchronizes your changes back to the original location.\n\nThe remainder of this page describes the second case.\n\n## Before You Begin\n\nYou need:\n\n- Sambee Companion installed and running on your computer.\n- A desktop app that can open the file type you want to edit.\n\nNeed Companion first? Start with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/).\n\n## Start the Editing Workflow\n\nIn Sambee, right-click the file and choose **Open in companion app**, or press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eEnter\u003c/kbd\u003e.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nSambee hands the request to Companion through a `sambee://` link. When your browser asks whether to allow that link to open, choose **yes**.\n{{\u003c /admonition \u003e}}\n\n{{\u003c admonition type=\"note\" \u003e}}\nIf your Sambee site is behind a proxy server, Companion may show a separate **Sambee Authentication** window before opening the file. Sign in there and then continue the desktop-editing workflow.\n{{\u003c /admonition \u003e}}\n\n### What Happens Under the Hood\n\nCompanion handles the rest of the edit session:\n\n- It acquires an edit lock for the file on the file share.\n- It downloads the file and stores a temporary local copy.\n- If needed, it asks you which desktop app should open the file.\n- It opens the local copy in that app.\n- It shows a **Done Editing** window, which you use to upload the modified local copy when you are done.\n\n## Choose an App to Open the File\n\nThe first time you open a file type, Companion may show an app picker listing the installed apps available for that file type. Choose an app from the list for that extension and optionally remember that choice for later. For app-selection help, use [Desktop App Picker](../../companion-app/desktop-app-picker/).\n\n## Finish the Editing Session\n\nClosing the desktop app by itself does not upload the file and does not finish the session. Uploading is initiated in the **Done Editing** window.\n\n- Changed file: use **Done Editing \u2014 Hold to Upload**.\n- Unchanged file: use **Done Editing \u2014 Hold to Close**.\n- Do not want to keep the local changes: use **Discard Changes \u2014 Hold**.\n\nIf the **Done Editing** window tells you that the session expired, authentication failed, the lock was lost, or recovery is required, reopen the file from Sambee instead of retrying the old desktop-editing session indefinitely. That starts a fresh authenticated edit session with a new server-side lock.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:user-guide/viewing-and-editing-files/file-locking-and-conflict-resolution", "parent_id": "section:user-guide/viewing-and-editing-files", "depth": 2, "kind": "page", "label": "file-locking-and-conflict-resolution", "title": "File Locking And Conflict Resolution", "path": "user-guide/viewing-and-editing-files/file-locking-and-conflict-resolution", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"File Locking \u0026 Conflict Resolution\"\n+++\n\nSambee uses two protections that are easy to confuse:\n\n- **Edit locks** stop a file from being edited simultaneously in two places.\n- **Conflict resolution** happens later when Companion tries to upload a desktop-edited file back to the server and notices the server-side copy was changed, too.\n\n## Edit Locks\n\nSambee uses edit locks on SMB connections to prevent other users from editing a file at the same time as you do.\n\n### Markdown Editing\n\nSambee acquires an edit lock before it opens the Markdown editor. Sambee releases the lock when you leave the editor.\n\nIf the file is already locked by another user, Sambee does not enter edit mode. Instead, it keeps the file in the read-only viewer and shows an error explaining that the file is already locked for editing.\n\n### Desktop Editing\n\nCompanion acquires an edit lock before downloading the temporary local copy.\n\nIf another user already holds that lock, the desktop-editing workflow cannot start.\n\nWhen you upload, discard changes, or finish an unchanged session, Companion releases that lock.\n\n## Conflict Resolution after Desktop Editing\n\nBefore uploading, Companion checks whether the server copy changed after the local copy was downloaded.\n\nIf it did, the **Done Editing** window switches to a conflict resolution dialog.\n\nThe choices are:\n\n- **Overwrite Server Version**: replace the current server copy with your edited version\n- **Save as Copy**: upload your changes as a separate `(conflict copy)` file\n- **Cancel**: go back without uploading yet\n\n## If a Desktop Editing Session is Interrupted\n\nIf Companion is closed during an editing session, it shows an **Unsaved Files Found** recovery dialog the next time it starts.\n\nThe choices are:\n\n- **Upload**: send the saved local edits back to the server\n- **Discard**: throw the temporary copy away\n- **Later**: keep the session for later recovery\n", "0.8": "+++\ntitle = \"File Locking \u0026 Conflict Resolution\"\n+++\n\nSambee uses two protections that are easy to confuse:\n\n- **Edit locks** stop a file from being edited simultaneously in two places.\n- **Conflict resolution** happens later when Companion tries to upload a desktop-edited file back to the server and notices the server-side copy was changed, too.\n\n## Edit Locks\n\nSambee uses edit locks on SMB connections to prevent other users from editing a file at the same time as you do.\n\n### Markdown Editing\n\nSambee acquires an edit lock before it opens the Markdown editor. Sambee releases the lock when you leave the editor.\n\nIf the file is already locked by another user, Sambee does not enter edit mode. Instead, it keeps the file in the read-only viewer and shows an error explaining that the file is already locked for editing.\n\n### Desktop Editing\n\nCompanion acquires an edit lock before downloading the temporary local copy.\n\nIf another user already holds that lock, the desktop-editing workflow cannot start.\n\nWhen you upload, discard changes, or finish an unchanged session, Companion releases that lock.\n\n## Conflict Resolution after Desktop Editing\n\nBefore uploading, Companion checks whether the server copy changed after the local copy was downloaded.\n\nIf it did, the **Done Editing** window switches to a conflict resolution dialog.\n\nThe choices are:\n\n- **Overwrite Server Version**: replace the current server copy with your edited version\n- **Save as Copy**: upload your changes as a separate `(conflict copy)` file\n- **Cancel**: go back without uploading yet\n\n## If a Desktop Editing Session is Interrupted\n\nIf Companion is closed during an editing session, it shows an **Unsaved Files Found** recovery dialog the next time it starts.\n\nThe choices are:\n\n- **Upload**: send the saved local edits back to the server\n- **Discard**: throw the temporary copy away\n- **Later**: keep the session for later recovery\n", "0.9": "+++\ntitle = \"File Locking \u0026 Conflict Resolution\"\n+++\n\nSambee uses two protections that are easy to confuse:\n\n- **Edit locks** stop a file from being edited simultaneously in two places.\n- **Conflict resolution** happens later when Companion tries to upload a desktop-edited file back to the server and notices the server-side copy was changed, too.\n\n## Edit Locks\n\nSambee uses edit locks on SMB connections to prevent other users from editing a file at the same time as you do.\n\n### Markdown Editing\n\nSambee acquires an edit lock before it opens the Markdown editor. Sambee releases the lock when you leave the editor.\n\nIf the file is already locked by another user, Sambee does not enter edit mode. Instead, it keeps the file in the read-only viewer and shows an error explaining that the file is already locked for editing.\n\n### Desktop Editing\n\nCompanion acquires an edit lock before downloading the temporary local copy.\n\nIf another user already holds that lock, the desktop-editing workflow cannot start.\n\nWhen you upload, discard changes, or finish an unchanged session, Companion releases that lock.\n\n## Conflict Resolution after Desktop Editing\n\nBefore uploading, Companion checks whether the server copy changed after the local copy was downloaded.\n\nIf it did, the **Done Editing** window switches to a conflict resolution dialog.\n\nThe choices are:\n\n- **Overwrite Server Version**: replace the current server copy with your edited version\n- **Save as Copy**: upload your changes as a separate `(conflict copy)` file\n- **Cancel**: go back without uploading yet\n\n## If a Desktop Editing Session is Interrupted\n\nIf Companion is closed during an editing session, it shows an **Unsaved Files Found** recovery dialog the next time it starts.\n\nThe choices are:\n\n- **Upload**: send the saved local edits back to the server\n- **Discard**: throw the temporary copy away\n- **Later**: keep the session for later recovery\n", "1.0": "+++\ntitle = \"File Locking \u0026 Conflict Resolution\"\n+++\n\nSambee uses two protections that are easy to confuse:\n\n- **Edit locks** stop a file from being edited simultaneously in two places.\n- **Conflict resolution** happens later when Companion tries to upload a desktop-edited file back to the server and notices the server-side copy was changed, too.\n\n## Edit Locks\n\nSambee uses edit locks on SMB connections to prevent other users from editing a file at the same time as you do.\n\n### Markdown Editing\n\nSambee acquires an edit lock before it opens the Markdown editor. Sambee releases the lock when you leave the editor.\n\nIf the file is already locked by another user, Sambee does not enter edit mode. Instead, it keeps the file in the read-only viewer and shows an error explaining that the file is already locked for editing.\n\n### Desktop Editing\n\nCompanion acquires an edit lock before downloading the temporary local copy.\n\nIf another user already holds that lock, the desktop-editing workflow cannot start.\n\nWhen you upload, discard changes, or finish an unchanged session, Companion releases that lock.\n\n## Conflict Resolution after Desktop Editing\n\nBefore uploading, Companion checks whether the server copy changed after the local copy was downloaded.\n\nIf it did, the **Done Editing** window switches to a conflict resolution dialog.\n\nThe choices are:\n\n- **Overwrite Server Version**: replace the current server copy with your edited version\n- **Save as Copy**: upload your changes as a separate `(conflict copy)` file\n- **Cancel**: go back without uploading yet\n\n## If a Desktop Editing Session is Interrupted\n\nIf Companion is closed during an editing session, it shows an **Unsaved Files Found** recovery dialog the next time it starts.\n\nThe choices are:\n\n- **Upload**: send the saved local edits back to the server\n- **Discard**: throw the temporary copy away\n- **Later**: keep the session for later recovery\n", "2.0": "+++\ntitle = \"File Locking \u0026 Conflict Resolution\"\n+++\n\nSambee uses two protections that are easy to confuse:\n\n- **Edit locks** stop a file from being edited simultaneously in two places.\n- **Conflict resolution** happens later when Companion tries to upload a desktop-edited file back to the server and notices the server-side copy was changed, too.\n\n## Edit Locks\n\nSambee uses edit locks on SMB connections to prevent other users from editing a file at the same time as you do.\n\n### Markdown Editing\n\nSambee acquires an edit lock before it opens the Markdown editor. Sambee releases the lock when you leave the editor.\n\nIf the file is already locked by another user, Sambee does not enter edit mode. Instead, it keeps the file in the read-only viewer and shows an error explaining that the file is already locked for editing.\n\n### Desktop Editing\n\nCompanion acquires an edit lock before downloading the temporary local copy.\n\nIf another user already holds that lock, the desktop-editing workflow cannot start.\n\nWhen you upload, discard changes, or finish an unchanged session, Companion releases that lock.\n\n## Conflict Resolution after Desktop Editing\n\nBefore uploading, Companion checks whether the server copy changed after the local copy was downloaded.\n\nIf it did, the **Done Editing** window switches to a conflict resolution dialog.\n\nThe choices are:\n\n- **Overwrite Server Version**: replace the current server copy with your edited version\n- **Save as Copy**: upload your changes as a separate `(conflict copy)` file\n- **Cancel**: go back without uploading yet\n\n## If a Desktop Editing Session is Interrupted\n\nIf Companion is closed during an editing session, it shows an **Unsaved Files Found** recovery dialog the next time it starts.\n\nThe choices are:\n\n- **Upload**: send the saved local edits back to the server\n- **Discard**: throw the temporary copy away\n- **Later**: keep the session for later recovery\n"}, "page_contents": {"0.7": "+++\ntitle = \"File Locking \u0026 Conflict Resolution\"\n+++\n\nSambee uses two protections that are easy to confuse:\n\n- **Edit locks** stop a file from being edited simultaneously in two places.\n- **Conflict resolution** happens later when Companion tries to upload a desktop-edited file back to the server and notices the server-side copy was changed, too.\n\n## Edit Locks\n\nSambee uses edit locks on SMB connections to prevent other users from editing a file at the same time as you do.\n\n### Markdown Editing\n\nSambee acquires an edit lock before it opens the Markdown editor. Sambee releases the lock when you leave the editor.\n\nIf the file is already locked by another user, Sambee does not enter edit mode. Instead, it keeps the file in the read-only viewer and shows an error explaining that the file is already locked for editing.\n\n### Desktop Editing\n\nCompanion acquires an edit lock before downloading the temporary local copy.\n\nIf another user already holds that lock, the desktop-editing workflow cannot start.\n\nWhen you upload, discard changes, or finish an unchanged session, Companion releases that lock.\n\n## Conflict Resolution after Desktop Editing\n\nBefore uploading, Companion checks whether the server copy changed after the local copy was downloaded.\n\nIf it did, the **Done Editing** window switches to a conflict resolution dialog.\n\nThe choices are:\n\n- **Overwrite Server Version**: replace the current server copy with your edited version\n- **Save as Copy**: upload your changes as a separate `(conflict copy)` file\n- **Cancel**: go back without uploading yet\n\n## If a Desktop Editing Session is Interrupted\n\nIf Companion is closed during an editing session, it shows an **Unsaved Files Found** recovery dialog the next time it starts.\n\nThe choices are:\n\n- **Upload**: send the saved local edits back to the server\n- **Discard**: throw the temporary copy away\n- **Later**: keep the session for later recovery\n", "0.8": "+++\ntitle = \"File Locking \u0026 Conflict Resolution\"\n+++\n\nSambee uses two protections that are easy to confuse:\n\n- **Edit locks** stop a file from being edited simultaneously in two places.\n- **Conflict resolution** happens later when Companion tries to upload a desktop-edited file back to the server and notices the server-side copy was changed, too.\n\n## Edit Locks\n\nSambee uses edit locks on SMB connections to prevent other users from editing a file at the same time as you do.\n\n### Markdown Editing\n\nSambee acquires an edit lock before it opens the Markdown editor. Sambee releases the lock when you leave the editor.\n\nIf the file is already locked by another user, Sambee does not enter edit mode. Instead, it keeps the file in the read-only viewer and shows an error explaining that the file is already locked for editing.\n\n### Desktop Editing\n\nCompanion acquires an edit lock before downloading the temporary local copy.\n\nIf another user already holds that lock, the desktop-editing workflow cannot start.\n\nWhen you upload, discard changes, or finish an unchanged session, Companion releases that lock.\n\n## Conflict Resolution after Desktop Editing\n\nBefore uploading, Companion checks whether the server copy changed after the local copy was downloaded.\n\nIf it did, the **Done Editing** window switches to a conflict resolution dialog.\n\nThe choices are:\n\n- **Overwrite Server Version**: replace the current server copy with your edited version\n- **Save as Copy**: upload your changes as a separate `(conflict copy)` file\n- **Cancel**: go back without uploading yet\n\n## If a Desktop Editing Session is Interrupted\n\nIf Companion is closed during an editing session, it shows an **Unsaved Files Found** recovery dialog the next time it starts.\n\nThe choices are:\n\n- **Upload**: send the saved local edits back to the server\n- **Discard**: throw the temporary copy away\n- **Later**: keep the session for later recovery\n", "0.9": "+++\ntitle = \"File Locking \u0026 Conflict Resolution\"\n+++\n\nSambee uses two protections that are easy to confuse:\n\n- **Edit locks** stop a file from being edited simultaneously in two places.\n- **Conflict resolution** happens later when Companion tries to upload a desktop-edited file back to the server and notices the server-side copy was changed, too.\n\n## Edit Locks\n\nSambee uses edit locks on SMB connections to prevent other users from editing a file at the same time as you do.\n\n### Markdown Editing\n\nSambee acquires an edit lock before it opens the Markdown editor. Sambee releases the lock when you leave the editor.\n\nIf the file is already locked by another user, Sambee does not enter edit mode. Instead, it keeps the file in the read-only viewer and shows an error explaining that the file is already locked for editing.\n\n### Desktop Editing\n\nCompanion acquires an edit lock before downloading the temporary local copy.\n\nIf another user already holds that lock, the desktop-editing workflow cannot start.\n\nWhen you upload, discard changes, or finish an unchanged session, Companion releases that lock.\n\n## Conflict Resolution after Desktop Editing\n\nBefore uploading, Companion checks whether the server copy changed after the local copy was downloaded.\n\nIf it did, the **Done Editing** window switches to a conflict resolution dialog.\n\nThe choices are:\n\n- **Overwrite Server Version**: replace the current server copy with your edited version\n- **Save as Copy**: upload your changes as a separate `(conflict copy)` file\n- **Cancel**: go back without uploading yet\n\n## If a Desktop Editing Session is Interrupted\n\nIf Companion is closed during an editing session, it shows an **Unsaved Files Found** recovery dialog the next time it starts.\n\nThe choices are:\n\n- **Upload**: send the saved local edits back to the server\n- **Discard**: throw the temporary copy away\n- **Later**: keep the session for later recovery\n", "1.0": "+++\ntitle = \"File Locking \u0026 Conflict Resolution\"\n+++\n\nSambee uses two protections that are easy to confuse:\n\n- **Edit locks** stop a file from being edited simultaneously in two places.\n- **Conflict resolution** happens later when Companion tries to upload a desktop-edited file back to the server and notices the server-side copy was changed, too.\n\n## Edit Locks\n\nSambee uses edit locks on SMB connections to prevent other users from editing a file at the same time as you do.\n\n### Markdown Editing\n\nSambee acquires an edit lock before it opens the Markdown editor. Sambee releases the lock when you leave the editor.\n\nIf the file is already locked by another user, Sambee does not enter edit mode. Instead, it keeps the file in the read-only viewer and shows an error explaining that the file is already locked for editing.\n\n### Desktop Editing\n\nCompanion acquires an edit lock before downloading the temporary local copy.\n\nIf another user already holds that lock, the desktop-editing workflow cannot start.\n\nWhen you upload, discard changes, or finish an unchanged session, Companion releases that lock.\n\n## Conflict Resolution after Desktop Editing\n\nBefore uploading, Companion checks whether the server copy changed after the local copy was downloaded.\n\nIf it did, the **Done Editing** window switches to a conflict resolution dialog.\n\nThe choices are:\n\n- **Overwrite Server Version**: replace the current server copy with your edited version\n- **Save as Copy**: upload your changes as a separate `(conflict copy)` file\n- **Cancel**: go back without uploading yet\n\n## If a Desktop Editing Session is Interrupted\n\nIf Companion is closed during an editing session, it shows an **Unsaved Files Found** recovery dialog the next time it starts.\n\nThe choices are:\n\n- **Upload**: send the saved local edits back to the server\n- **Discard**: throw the temporary copy away\n- **Later**: keep the session for later recovery\n", "2.0": "+++\ntitle = \"File Locking \u0026 Conflict Resolution\"\n+++\n\nSambee uses two protections that are easy to confuse:\n\n- **Edit locks** stop a file from being edited simultaneously in two places.\n- **Conflict resolution** happens later when Companion tries to upload a desktop-edited file back to the server and notices the server-side copy was changed, too.\n\n## Edit Locks\n\nSambee uses edit locks on SMB connections to prevent other users from editing a file at the same time as you do.\n\n### Markdown Editing\n\nSambee acquires an edit lock before it opens the Markdown editor. Sambee releases the lock when you leave the editor.\n\nIf the file is already locked by another user, Sambee does not enter edit mode. Instead, it keeps the file in the read-only viewer and shows an error explaining that the file is already locked for editing.\n\n### Desktop Editing\n\nCompanion acquires an edit lock before downloading the temporary local copy.\n\nIf another user already holds that lock, the desktop-editing workflow cannot start.\n\nWhen you upload, discard changes, or finish an unchanged session, Companion releases that lock.\n\n## Conflict Resolution after Desktop Editing\n\nBefore uploading, Companion checks whether the server copy changed after the local copy was downloaded.\n\nIf it did, the **Done Editing** window switches to a conflict resolution dialog.\n\nThe choices are:\n\n- **Overwrite Server Version**: replace the current server copy with your edited version\n- **Save as Copy**: upload your changes as a separate `(conflict copy)` file\n- **Cancel**: go back without uploading yet\n\n## If a Desktop Editing Session is Interrupted\n\nIf Companion is closed during an editing session, it shows an **Unsaved Files Found** recovery dialog the next time it starts.\n\nThe choices are:\n\n- **Upload**: send the saved local edits back to the server\n- **Discard**: throw the temporary copy away\n- **Later**: keep the session for later recovery\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:user-guide/viewing-and-editing-files/recover-unsaved-edits", "parent_id": "section:user-guide/viewing-and-editing-files", "depth": 2, "kind": "page", "label": "recover-unsaved-edits", "title": "Recover Unsaved Edits", "path": "user-guide/viewing-and-editing-files/recover-unsaved-edits", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "authored"}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "branched", "source_version": "0.9", "diff_added": 6, "diff_removed": 3}}, "content_versions": {"0.9": "+++\ntitle = \"Recover Unsaved In-Browser Edits\"\n+++\n\nSambee can preserve eligible unsaved Markdown and plain-text edits when a required OIDC sign-in takes you away from the editor.\n\n## When Sambee Saves A Draft\n\nSambee saves a tab-scoped recovery draft before a controlled sign-in redirect and while you continue editing. This protects work when the browser session expires, an administrator revokes the session, or the identity provider requires you to sign in again.\n\nDrafts stay in the current browser tab. They are not uploaded to Sambee, shared with another browser, or shown after you sign in as a different account.\n\n## Return To Your Edit\n\nAfter you finish signing in, Sambee returns you to the file you were editing.\n\n- If the remote file has not changed, Sambee restores your unsaved draft in the editor.\n- If the remote file changed, Sambee shows a recovery choice and does not overwrite the remote version automatically.\n- Save the restored draft when you are ready. Sambee removes its recovery copy after a successful save or when you deliberately discard it.\n\n## Recovery Limits\n\nDraft recovery depends on browser tab storage. Sambee keeps recovery drafts only for a limited time and displays a warning when a draft is too large or the browser cannot store it. Save important work regularly; do not rely on draft recovery as a replacement for saving.\n\nClosing the tab, explicitly discarding the draft, or signing out can remove the recovery copy.\n\n", "1.0": "+++\ntitle = \"Recover Unsaved In-Browser Edits\"\n+++\n\nSambee can preserve eligible unsaved Markdown and plain-text edits when a required OIDC sign-in takes you away from the editor.\n\n## When Sambee Saves A Draft\n\nSambee saves a tab-scoped recovery draft before a controlled sign-in redirect and while you continue editing. This protects work when the browser session expires, an administrator revokes the session, or the identity provider requires you to sign in again.\n\nDrafts stay in the current browser tab. They are not uploaded to Sambee, shared with another browser, or shown after you sign in as a different account.\n\n## Return To Your Edit\n\nAfter you finish signing in, Sambee returns you to the file you were editing.\n\n- If the remote file has not changed, Sambee restores your unsaved draft in the editor.\n- If the remote file changed, Sambee shows a recovery choice and does not overwrite the remote version automatically.\n- Save the restored draft when you are ready. Sambee removes its recovery copy after a successful save or when you deliberately discard it.\n\n## Recovery Limits\n\nDraft recovery depends on browser tab storage. Sambee keeps recovery drafts only for a limited time and displays a warning when a draft is too large or the browser cannot store it. Save important work regularly; do not rely on draft recovery as a replacement for saving.\n\nClosing the tab, explicitly discarding the draft, or signing out can remove the recovery copy.\n\n", "2.0": "+++\ntitle = \"Recover Unsaved In-Browser Edits\"\n+++\n\nSambee can preserve eligible unsaved Markdown and plain-text edits when a required OIDC sign-in takes you away from the editor.\n\n## When Sambee Saves A Draft\n\nSambee saves a tab-scoped recovery draft before a controlled sign-in redirect and while you continue editing. This protects work when the browser session expires, an administrator revokes the session, or the identity provider requires you to sign in again.\n\nDrafts stay in the current browser tab. They are not uploaded to Sambee, shared with another browser, or shown after you sign in as a different account.\n\nThe pre-sign-in snapshot is a best-effort attempt. Sign-in continues even if a draft cannot be stored; it does not wait for unfinished editor input or save the file. Save important work regularly.\n\n## Return To Your Edit\n\nAfter you finish signing in, Sambee returns you to the file you were editing.\n\n- When Sambee offers an unsaved local draft, choose **Resume editing** to return to it, or **Discard draft** to keep the saved file.\n- If the remote file changed, review the recovery choice carefully. Sambee doesn't overwrite the remote version automatically.\n- Save the restored draft when you're ready. Sambee removes its recovery copy once the current draft is saved or when you deliberately discard it. Edits made while an earlier save is still in progress remain unsaved.\n\n## Recovery Limits\n\nDraft recovery depends on browser tab storage. Sambee keeps recovery drafts only for a limited time and displays a warning when a draft is too large or the browser cannot store it. Save important work regularly; do not rely on draft recovery as a replacement for saving.\n\nClosing the tab, explicitly discarding the draft, or signing out can remove the recovery copy.\n\nAn unfinished edit may not be recoverable when the browser suspends or terminates the page. A successful recovery checkpoint isn't a file save or a guarantee that the draft will survive closing the tab.\n"}, "page_contents": {"0.9": "+++\ntitle = \"Recover Unsaved In-Browser Edits\"\n+++\n\nSambee can preserve eligible unsaved Markdown and plain-text edits when a required OIDC sign-in takes you away from the editor.\n\n## When Sambee Saves A Draft\n\nSambee saves a tab-scoped recovery draft before a controlled sign-in redirect and while you continue editing. This protects work when the browser session expires, an administrator revokes the session, or the identity provider requires you to sign in again.\n\nDrafts stay in the current browser tab. They are not uploaded to Sambee, shared with another browser, or shown after you sign in as a different account.\n\n## Return To Your Edit\n\nAfter you finish signing in, Sambee returns you to the file you were editing.\n\n- If the remote file has not changed, Sambee restores your unsaved draft in the editor.\n- If the remote file changed, Sambee shows a recovery choice and does not overwrite the remote version automatically.\n- Save the restored draft when you are ready. Sambee removes its recovery copy after a successful save or when you deliberately discard it.\n\n## Recovery Limits\n\nDraft recovery depends on browser tab storage. Sambee keeps recovery drafts only for a limited time and displays a warning when a draft is too large or the browser cannot store it. Save important work regularly; do not rely on draft recovery as a replacement for saving.\n\nClosing the tab, explicitly discarding the draft, or signing out can remove the recovery copy.\n\n", "1.0": "+++\ntitle = \"Recover Unsaved In-Browser Edits\"\n+++\n\nSambee can preserve eligible unsaved Markdown and plain-text edits when a required OIDC sign-in takes you away from the editor.\n\n## When Sambee Saves A Draft\n\nSambee saves a tab-scoped recovery draft before a controlled sign-in redirect and while you continue editing. This protects work when the browser session expires, an administrator revokes the session, or the identity provider requires you to sign in again.\n\nDrafts stay in the current browser tab. They are not uploaded to Sambee, shared with another browser, or shown after you sign in as a different account.\n\n## Return To Your Edit\n\nAfter you finish signing in, Sambee returns you to the file you were editing.\n\n- If the remote file has not changed, Sambee restores your unsaved draft in the editor.\n- If the remote file changed, Sambee shows a recovery choice and does not overwrite the remote version automatically.\n- Save the restored draft when you are ready. Sambee removes its recovery copy after a successful save or when you deliberately discard it.\n\n## Recovery Limits\n\nDraft recovery depends on browser tab storage. Sambee keeps recovery drafts only for a limited time and displays a warning when a draft is too large or the browser cannot store it. Save important work regularly; do not rely on draft recovery as a replacement for saving.\n\nClosing the tab, explicitly discarding the draft, or signing out can remove the recovery copy.\n\n", "2.0": "+++\ntitle = \"Recover Unsaved In-Browser Edits\"\n+++\n\nSambee can preserve eligible unsaved Markdown and plain-text edits when a required OIDC sign-in takes you away from the editor.\n\n## When Sambee Saves A Draft\n\nSambee saves a tab-scoped recovery draft before a controlled sign-in redirect and while you continue editing. This protects work when the browser session expires, an administrator revokes the session, or the identity provider requires you to sign in again.\n\nDrafts stay in the current browser tab. They are not uploaded to Sambee, shared with another browser, or shown after you sign in as a different account.\n\nThe pre-sign-in snapshot is a best-effort attempt. Sign-in continues even if a draft cannot be stored; it does not wait for unfinished editor input or save the file. Save important work regularly.\n\n## Return To Your Edit\n\nAfter you finish signing in, Sambee returns you to the file you were editing.\n\n- When Sambee offers an unsaved local draft, choose **Resume editing** to return to it, or **Discard draft** to keep the saved file.\n- If the remote file changed, review the recovery choice carefully. Sambee doesn't overwrite the remote version automatically.\n- Save the restored draft when you're ready. Sambee removes its recovery copy once the current draft is saved or when you deliberately discard it. Edits made while an earlier save is still in progress remain unsaved.\n\n## Recovery Limits\n\nDraft recovery depends on browser tab storage. Sambee keeps recovery drafts only for a limited time and displays a warning when a draft is too large or the browser cannot store it. Save important work regularly; do not rely on draft recovery as a replacement for saving.\n\nClosing the tab, explicitly discarding the draft, or signing out can remove the recovery copy.\n\nAn unfinished edit may not be recoverable when the browser suspends or terminates the page. A successful recovery checkpoint isn't a file save or a guarantee that the draft will survive closing the tab.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:user-guide/viewing-and-editing-files/download-and-upload-files", "parent_id": "section:user-guide/viewing-and-editing-files", "depth": 2, "kind": "page", "label": "download-and-upload-files", "title": "Download And Upload Files", "path": "user-guide/viewing-and-editing-files/download-and-upload-files", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "missing"}, "1.0": {"state": "authored"}, "2.0": {"state": "inherited", "source_version": "1.0"}}, "content_versions": {"1.0": "+++\ntitle = \"Download and Upload Files\"\n+++\n\nUse **Download** to save a file to your computer. Select a folder or several items in the same directory to download them together as `Sambee-download.zip`. The ZIP preserves the selected folders and their contents. Downloads don't create a ZIP in the source share or drive.\n\nDownload is available from the file browser toolbar and the compact item or selection menu. You can also select members or folders inside a ZIP stored on an SMB share or a paired local drive and download them as a new ZIP.\n\nTo keep a new archive in an SMB share instead, open a ZIP in one pane and a writable folder on the same SMB connection in the other pane. Select files or folders inside the ZIP, then choose **Create archive**. Unlike **Download**, this writes a persistent ZIP to the destination folder. Creating an archive from ZIP members isn't available for local-drive or mixed-connection destinations.\n\n## Upload Files and Folders\n\nOpen a writable folder in an SMB share or paired local drive. On desktop, choose **Upload** (or press `Ctrl` + `U`), then choose **Files** for one or more files or **Folder** for one folder. On a compact screen, use the **+** menu to choose **Upload files** or **Upload folder** directly. Folder selection depends on your browser; when it isn't supported, **Upload files** remains available. A folder picker may not return an empty folder, but dragging that folder into the browser can preserve it in supported browsers.\n\nYou can also drag files and folders from your computer onto a file list. The drop cue names the connection and current folder receiving them. In dual-pane mode, drop onto the pane you want; dropping on a file or folder row still targets that pane's current folder, not the row. If drops aren't supported by your browser or the destination isn't writable, use the upload picker instead.\n\nUploaded folders keep their names and internal structure. If a folder with the same name already exists, Sambee merges into it without removing files already there. If a file blocks a folder, or a folder blocks a file, you can skip or rename the incoming item; a folder isn't overwritten. Individual file conflicts can be skipped, renamed, or replaced.\n\nFiles upload one at a time. The progress notice shows the current file and path, and the final notice reports completed, skipped, failed, or uncertain results and folder counts. Cancelling or failing partway through doesn't undo files or folders already created. If a folder upload has an uncertain outcome, Sambee stops the remaining transfers; inspect the destination before trying again.\n\n## Download Limits\n\nSelected-item ZIPs are prepared in private temporary storage and removed after the download finishes or is cancelled. The default ZIP size limit is 250 MiB; administrators can change it in Advanced Settings. Local ZIP-member downloads also require the selected members' uncompressed data to fit this limit. A download exceeding the limit fails without leaving a partial ZIP in your share or drive. Single-file downloads are separate from this ZIP limit.\n", "2.0": "+++\ntitle = \"Download and Upload Files\"\n+++\n\nUse **Download** to save a file to your computer. Select a folder or several items in the same directory to download them together as `Sambee-download.zip`. The ZIP preserves the selected folders and their contents. Downloads don't create a ZIP in the source share or drive.\n\nDownload is available from the file browser toolbar and the compact item or selection menu. You can also select members or folders inside a ZIP stored on an SMB share or a paired local drive and download them as a new ZIP.\n\nTo keep a new archive in an SMB share instead, open a ZIP in one pane and a writable folder on the same SMB connection in the other pane. Select files or folders inside the ZIP, then choose **Create archive**. Unlike **Download**, this writes a persistent ZIP to the destination folder. Creating an archive from ZIP members isn't available for local-drive or mixed-connection destinations.\n\n## Upload Files and Folders\n\nOpen a writable folder in an SMB share or paired local drive. On desktop, choose **Upload** (or press `Ctrl` + `U`), then choose **Files** for one or more files or **Folder** for one folder. On a compact screen, use the **+** menu to choose **Upload files** or **Upload folder** directly. Folder selection depends on your browser; when it isn't supported, **Upload files** remains available. A folder picker may not return an empty folder, but dragging that folder into the browser can preserve it in supported browsers.\n\nYou can also drag files and folders from your computer onto a file list. The drop cue names the connection and current folder receiving them. In dual-pane mode, drop onto the pane you want; dropping on a file or folder row still targets that pane's current folder, not the row. If drops aren't supported by your browser or the destination isn't writable, use the upload picker instead.\n\nUploaded folders keep their names and internal structure. If a folder with the same name already exists, Sambee merges into it without removing files already there. If a file blocks a folder, or a folder blocks a file, you can skip or rename the incoming item; a folder isn't overwritten. Individual file conflicts can be skipped, renamed, or replaced.\n\nFiles upload one at a time. The progress notice shows the current file and path, and the final notice reports completed, skipped, failed, or uncertain results and folder counts. Cancelling or failing partway through doesn't undo files or folders already created. If a folder upload has an uncertain outcome, Sambee stops the remaining transfers; inspect the destination before trying again.\n\n## Download Limits\n\nSelected-item ZIPs are prepared in private temporary storage and removed after the download finishes or is cancelled. The default ZIP size limit is 250 MiB; administrators can change it in Advanced Settings. Local ZIP-member downloads also require the selected members' uncompressed data to fit this limit. A download exceeding the limit fails without leaving a partial ZIP in your share or drive. Single-file downloads are separate from this ZIP limit.\n"}, "page_contents": {"1.0": "+++\ntitle = \"Download and Upload Files\"\n+++\n\nUse **Download** to save a file to your computer. Select a folder or several items in the same directory to download them together as `Sambee-download.zip`. The ZIP preserves the selected folders and their contents. Downloads don't create a ZIP in the source share or drive.\n\nDownload is available from the file browser toolbar and the compact item or selection menu. You can also select members or folders inside a ZIP stored on an SMB share or a paired local drive and download them as a new ZIP.\n\nTo keep a new archive in an SMB share instead, open a ZIP in one pane and a writable folder on the same SMB connection in the other pane. Select files or folders inside the ZIP, then choose **Create archive**. Unlike **Download**, this writes a persistent ZIP to the destination folder. Creating an archive from ZIP members isn't available for local-drive or mixed-connection destinations.\n\n## Upload Files and Folders\n\nOpen a writable folder in an SMB share or paired local drive. On desktop, choose **Upload** (or press `Ctrl` + `U`), then choose **Files** for one or more files or **Folder** for one folder. On a compact screen, use the **+** menu to choose **Upload files** or **Upload folder** directly. Folder selection depends on your browser; when it isn't supported, **Upload files** remains available. A folder picker may not return an empty folder, but dragging that folder into the browser can preserve it in supported browsers.\n\nYou can also drag files and folders from your computer onto a file list. The drop cue names the connection and current folder receiving them. In dual-pane mode, drop onto the pane you want; dropping on a file or folder row still targets that pane's current folder, not the row. If drops aren't supported by your browser or the destination isn't writable, use the upload picker instead.\n\nUploaded folders keep their names and internal structure. If a folder with the same name already exists, Sambee merges into it without removing files already there. If a file blocks a folder, or a folder blocks a file, you can skip or rename the incoming item; a folder isn't overwritten. Individual file conflicts can be skipped, renamed, or replaced.\n\nFiles upload one at a time. The progress notice shows the current file and path, and the final notice reports completed, skipped, failed, or uncertain results and folder counts. Cancelling or failing partway through doesn't undo files or folders already created. If a folder upload has an uncertain outcome, Sambee stops the remaining transfers; inspect the destination before trying again.\n\n## Download Limits\n\nSelected-item ZIPs are prepared in private temporary storage and removed after the download finishes or is cancelled. The default ZIP size limit is 250 MiB; administrators can change it in Advanced Settings. Local ZIP-member downloads also require the selected members' uncompressed data to fit this limit. A download exceeding the limit fails without leaving a partial ZIP in your share or drive. Single-file downloads are separate from this ZIP limit.\n", "2.0": "+++\ntitle = \"Download and Upload Files\"\n+++\n\nUse **Download** to save a file to your computer. Select a folder or several items in the same directory to download them together as `Sambee-download.zip`. The ZIP preserves the selected folders and their contents. Downloads don't create a ZIP in the source share or drive.\n\nDownload is available from the file browser toolbar and the compact item or selection menu. You can also select members or folders inside a ZIP stored on an SMB share or a paired local drive and download them as a new ZIP.\n\nTo keep a new archive in an SMB share instead, open a ZIP in one pane and a writable folder on the same SMB connection in the other pane. Select files or folders inside the ZIP, then choose **Create archive**. Unlike **Download**, this writes a persistent ZIP to the destination folder. Creating an archive from ZIP members isn't available for local-drive or mixed-connection destinations.\n\n## Upload Files and Folders\n\nOpen a writable folder in an SMB share or paired local drive. On desktop, choose **Upload** (or press `Ctrl` + `U`), then choose **Files** for one or more files or **Folder** for one folder. On a compact screen, use the **+** menu to choose **Upload files** or **Upload folder** directly. Folder selection depends on your browser; when it isn't supported, **Upload files** remains available. A folder picker may not return an empty folder, but dragging that folder into the browser can preserve it in supported browsers.\n\nYou can also drag files and folders from your computer onto a file list. The drop cue names the connection and current folder receiving them. In dual-pane mode, drop onto the pane you want; dropping on a file or folder row still targets that pane's current folder, not the row. If drops aren't supported by your browser or the destination isn't writable, use the upload picker instead.\n\nUploaded folders keep their names and internal structure. If a folder with the same name already exists, Sambee merges into it without removing files already there. If a file blocks a folder, or a folder blocks a file, you can skip or rename the incoming item; a folder isn't overwritten. Individual file conflicts can be skipped, renamed, or replaced.\n\nFiles upload one at a time. The progress notice shows the current file and path, and the final notice reports completed, skipped, failed, or uncertain results and folder counts. Cancelling or failing partway through doesn't undo files or folders already created. If a folder upload has an uncertain outcome, Sambee stops the remaining transfers; inspect the destination before trying again.\n\n## Download Limits\n\nSelected-item ZIPs are prepared in private temporary storage and removed after the download finishes or is cancelled. The default ZIP size limit is 250 MiB; administrators can change it in Advanced Settings. Local ZIP-member downloads also require the selected members' uncompressed data to fit this limit. A download exceeding the limit fails without leaving a partial ZIP in your share or drive. Single-file downloads are separate from this ZIP limit.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:user-guide/companion-app", "parent_id": "book:user-guide", "depth": 1, "kind": "section", "label": "companion-app", "title": "Companion App", "path": "user-guide/companion-app", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:user-guide/companion-app/install-and-pair-the-companion-app", "parent_id": "section:user-guide/companion-app", "depth": 2, "kind": "page", "label": "install-and-pair-the-companion-app", "title": "Install And Pair The Companion App", "path": "user-guide/companion-app/install-and-pair-the-companion-app", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "branched", "source_version": "0.7", "diff_added": 17, "diff_removed": 4}, "0.9": {"state": "inherited", "source_version": "0.8"}, "1.0": {"state": "inherited", "source_version": "0.8"}, "2.0": {"state": "branched", "source_version": "0.8", "diff_added": 15, "diff_removed": 2}}, "content_versions": {"0.7": "+++\ntitle = \"Install and Pair the Companion App\"\n+++\n\nSambee Companion is a desktop helper app that enables Sambee to connect from the browser to local drives on your computer and to open files in natively installed desktop apps.\n\nYou do not need Companion for accessing SMB shares from the browser.\n\n## Install Companion\n\n1. Open **Settings** \u003e **Local Drives** and select **Download for this computer** to download the Companion installer.\n1. Run the installer and follow the prompts. Make sure to enable auto-starting Companion.\n1. Once the installer is completed, Companion should be running.\n1. You can find the Companion icon in the system tray (Linux, Windows) or the menu bar (macOS).\n\n## Pair This Browser With Companion\n\n{{\u003c admonition type=\"note\" title=\"\" \u003e}}\nDuring pairing, Sambee and Companion exchange data that is needed to establish a secure connection. The concept is similar in nature to Bluetooth pairing.\n{{\u003c /admonition \u003e}}\n\nOpen **Settings** \u003e **Local Drives**. Sambee checks whether it can find the Companion app. You should see a check mark next to **Companion app is running**.\n\nSelect **Pair this browser**. Sambee and Companion both display a verification code. Confirm that both codes match, then finish pairing. Sambee should now show a check mark next to **This browser is paired**.\n\nPairing is scoped to the current browser origin and browser profile, not to the whole computer. If you use Sambee from a different browser, a different browser profile, or a different Sambee site origin, approve that browser separately.\n\nOnce this browser is paired with Companion, local drives on your computer appear in Sambee's connection list.\n", "0.8": "+++\ntitle = \"Install and Pair the Companion App\"\n+++\n\nSambee Companion is a desktop helper app that enables Sambee to connect from the browser to local drives on your computer and to open files in natively installed desktop apps.\n\nYou do not need Companion for accessing SMB shares from the browser.\n\n## Install Companion\n\n1. Open **Settings** \u003e **Local Drives** and select **Download for this computer** to download the Companion installer.\n1. Run the installer and follow the prompts. Make sure to enable auto-starting Companion.\n1. Once the installer is completed, Companion should be running.\n1. You can find the Companion icon in the system tray (Linux, Windows) or the menu bar (macOS).\n\n## Pair Sambee With Companion\n\n{{\u003c admonition type=\"note\" title=\"\" \u003e}}\nDuring pairing, Sambee and Companion exchange data that is needed to establish a secure connection. The concept is similar in nature to Bluetooth pairing.\n{{\u003c /admonition \u003e}}\n\nOpen **Settings** \u003e **Local Drives**. Sambee checks whether it can find the Companion app. You should see a check mark next to **Companion app is running**.\n\nSelect **Pair this browser**. Sambee starts a pairing request for the exact site you are currently using, and Companion opens a native approval window that shows both:\n\n- the requesting browser origin\n- a short verification code\n\nSambee shows the same verification code in the browser. Confirm the pairing only when both codes match and the origin shown in Companion is the Sambee site you expect.\n\nAfter you approve the request in Companion and confirm it in the browser, Sambee should show a check mark next to **This browser is paired**.\n\nOnce Sambee is paired with Companion, local drives on your computer appear in Sambee's connection list.\n\n## What to Expect Later\n\nPairing is specific to the current browser origin.\n\n- If you use Sambee from a different site or port, that browser origin may need its own pairing.\n- If you close the pairing dialog before finishing, the request is cancelled instead of staying pending silently.\n- If Sambee later reports that the browser needs repair, start pairing again from **Settings** \u003e **Local Drives** to restore the browser-side secret.\n", "0.9": "+++\ntitle = \"Install and Pair the Companion App\"\n+++\n\nSambee Companion is a desktop helper app that enables Sambee to connect from the browser to local drives on your computer and to open files in natively installed desktop apps.\n\nYou do not need Companion for accessing SMB shares from the browser.\n\n## Install Companion\n\n1. Open **Settings** \u003e **Local Drives** and select **Download for this computer** to download the Companion installer.\n1. Run the installer and follow the prompts. Make sure to enable auto-starting Companion.\n1. Once the installer is completed, Companion should be running.\n1. You can find the Companion icon in the system tray (Linux, Windows) or the menu bar (macOS).\n\n## Pair Sambee With Companion\n\n{{\u003c admonition type=\"note\" title=\"\" \u003e}}\nDuring pairing, Sambee and Companion exchange data that is needed to establish a secure connection. The concept is similar in nature to Bluetooth pairing.\n{{\u003c /admonition \u003e}}\n\nOpen **Settings** \u003e **Local Drives**. Sambee checks whether it can find the Companion app. You should see a check mark next to **Companion app is running**.\n\nSelect **Pair this browser**. Sambee starts a pairing request for the exact site you are currently using, and Companion opens a native approval window that shows both:\n\n- the requesting browser origin\n- a short verification code\n\nSambee shows the same verification code in the browser. Confirm the pairing only when both codes match and the origin shown in Companion is the Sambee site you expect.\n\nAfter you approve the request in Companion and confirm it in the browser, Sambee should show a check mark next to **This browser is paired**.\n\nOnce Sambee is paired with Companion, local drives on your computer appear in Sambee's connection list.\n\n## What to Expect Later\n\nPairing is specific to the current browser origin.\n\n- If you use Sambee from a different site or port, that browser origin may need its own pairing.\n- If you close the pairing dialog before finishing, the request is cancelled instead of staying pending silently.\n- If Sambee later reports that the browser needs repair, start pairing again from **Settings** \u003e **Local Drives** to restore the browser-side secret.\n", "1.0": "+++\ntitle = \"Install and Pair the Companion App\"\n+++\n\nSambee Companion is a desktop helper app that enables Sambee to connect from the browser to local drives on your computer and to open files in natively installed desktop apps.\n\nYou do not need Companion for accessing SMB shares from the browser.\n\n## Install Companion\n\n1. Open **Settings** \u003e **Local Drives** and select **Download for this computer** to download the Companion installer.\n1. Run the installer and follow the prompts. Make sure to enable auto-starting Companion.\n1. Once the installer is completed, Companion should be running.\n1. You can find the Companion icon in the system tray (Linux, Windows) or the menu bar (macOS).\n\n## Pair Sambee With Companion\n\n{{\u003c admonition type=\"note\" title=\"\" \u003e}}\nDuring pairing, Sambee and Companion exchange data that is needed to establish a secure connection. The concept is similar in nature to Bluetooth pairing.\n{{\u003c /admonition \u003e}}\n\nOpen **Settings** \u003e **Local Drives**. Sambee checks whether it can find the Companion app. You should see a check mark next to **Companion app is running**.\n\nSelect **Pair this browser**. Sambee starts a pairing request for the exact site you are currently using, and Companion opens a native approval window that shows both:\n\n- the requesting browser origin\n- a short verification code\n\nSambee shows the same verification code in the browser. Confirm the pairing only when both codes match and the origin shown in Companion is the Sambee site you expect.\n\nAfter you approve the request in Companion and confirm it in the browser, Sambee should show a check mark next to **This browser is paired**.\n\nOnce Sambee is paired with Companion, local drives on your computer appear in Sambee's connection list.\n\n## What to Expect Later\n\nPairing is specific to the current browser origin.\n\n- If you use Sambee from a different site or port, that browser origin may need its own pairing.\n- If you close the pairing dialog before finishing, the request is cancelled instead of staying pending silently.\n- If Sambee later reports that the browser needs repair, start pairing again from **Settings** \u003e **Local Drives** to restore the browser-side secret.\n", "2.0": "+++\ntitle = \"Install and Pair the Companion App\"\n+++\n\nSambee Companion is a desktop helper app that enables Sambee to connect from the browser to local drives on your computer and to open files in natively installed desktop apps.\n\nYou do not need Companion for accessing SMB shares from the browser.\n\n## Install Companion\n\n1. Open **Settings** \u003e **Local Drives** and select **Download for this computer** to download the Companion installer.\n1. Run the installer and follow the prompts. Make sure to enable auto-starting Companion.\n1. Once the installer is completed, Companion should be running.\n1. You can find the Companion icon in the system tray (Linux, Windows) or the menu bar (macOS).\n\n## Pair Sambee With Companion\n\nOpen Sambee over HTTPS before pairing from another computer or a network address. Browsers don't provide the cryptographic APIs needed by Companion on ordinary HTTP sites. Local development on `http://localhost` is an exception. If **Local Drives** warns that a secure browser context with Web Crypto support is unavailable, use HTTPS; if you're already using HTTPS, check that your browser supports and permits Web Crypto. You don't need HTTPS to download the Companion installer.\n\n{{\u003c admonition type=\"note\" title=\"\" \u003e}}\nDuring pairing, Sambee and Companion exchange data that is needed to establish a secure connection. The concept is similar in nature to Bluetooth pairing.\n{{\u003c /admonition \u003e}}\n\nOpen **Settings** \u003e **Local Drives**. Sambee checks whether it can find the Companion app. You should see a check mark next to **Companion app is running**.\n\nSelect **Pair this browser**. Sambee starts a pairing request for the exact site you are currently using, and Companion opens a native approval window that shows both:\n\n- the requesting browser origin\n- a short verification code\n\nSambee shows the same verification code in the browser. Confirm the pairing only when both codes match and the origin shown in Companion is the Sambee site you expect.\n\nAfter you approve the request in Companion and confirm it in the browser, Sambee verifies local access and shows a check mark next to **This browser is paired**.\n\nOnce Sambee is paired with Companion, local drives on your computer appear in Sambee's connection list.\n\n## What to Expect Later\n\nPairing is specific to the current browser origin.\n\n- If you use Sambee from a different site or port, that browser origin may need its own pairing.\n- If you close the pairing dialog before finishing, the request is cancelled instead of staying pending silently.\n\n## Restore Local-Drive Access\n\nIf a local drive reports a pairing error, open **Settings** \u003e **Local Drives** from the file-list alert. **Ready** means the browser has passed an authenticated pairing check; having a stored pairing alone is not enough.\n\n1. If Companion needs an update, install the available version, restart Companion, and reload the Sambee page. Re-pairing will not resolve an incompatible version.\n1. If Sambee needs an update, reload the page. If the version mismatch remains, update Sambee. Updating Companion or re-pairing will not fix a newer Companion protocol.\n1. If the file-list alert says this browser isn't paired, open **Local Drives** and select **Pair This Browser**. Reloading alone won't restore a missing or removed pairing.\n1. If Companion rejects the browser's signature, reload the Sambee page first. A page left open across an update may still use the previous authentication protocol.\n1. Run **Test Current Pairing**. If it still fails with a signature error after reloading, use **Pair This Browser** and approve the new code in Companion.\n\nIf Sambee cannot check the pairing status, select **Retry**. Wait for a confirmed status before starting a new pairing. Companion pairing secrets do not expire on a 30-day timer. An unavailable Companion or a temporary failed check does not mean you need to re-pair.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Install and Pair the Companion App\"\n+++\n\nSambee Companion is a desktop helper app that enables Sambee to connect from the browser to local drives on your computer and to open files in natively installed desktop apps.\n\nYou do not need Companion for accessing SMB shares from the browser.\n\n## Install Companion\n\n1. Open **Settings** \u003e **Local Drives** and select **Download for this computer** to download the Companion installer.\n1. Run the installer and follow the prompts. Make sure to enable auto-starting Companion.\n1. Once the installer is completed, Companion should be running.\n1. You can find the Companion icon in the system tray (Linux, Windows) or the menu bar (macOS).\n\n## Pair This Browser With Companion\n\n{{\u003c admonition type=\"note\" title=\"\" \u003e}}\nDuring pairing, Sambee and Companion exchange data that is needed to establish a secure connection. The concept is similar in nature to Bluetooth pairing.\n{{\u003c /admonition \u003e}}\n\nOpen **Settings** \u003e **Local Drives**. Sambee checks whether it can find the Companion app. You should see a check mark next to **Companion app is running**.\n\nSelect **Pair this browser**. Sambee and Companion both display a verification code. Confirm that both codes match, then finish pairing. Sambee should now show a check mark next to **This browser is paired**.\n\nPairing is scoped to the current browser origin and browser profile, not to the whole computer. If you use Sambee from a different browser, a different browser profile, or a different Sambee site origin, approve that browser separately.\n\nOnce this browser is paired with Companion, local drives on your computer appear in Sambee's connection list.\n", "0.8": "+++\ntitle = \"Install and Pair the Companion App\"\n+++\n\nSambee Companion is a desktop helper app that enables Sambee to connect from the browser to local drives on your computer and to open files in natively installed desktop apps.\n\nYou do not need Companion for accessing SMB shares from the browser.\n\n## Install Companion\n\n1. Open **Settings** \u003e **Local Drives** and select **Download for this computer** to download the Companion installer.\n1. Run the installer and follow the prompts. Make sure to enable auto-starting Companion.\n1. Once the installer is completed, Companion should be running.\n1. You can find the Companion icon in the system tray (Linux, Windows) or the menu bar (macOS).\n\n## Pair Sambee With Companion\n\n{{\u003c admonition type=\"note\" title=\"\" \u003e}}\nDuring pairing, Sambee and Companion exchange data that is needed to establish a secure connection. The concept is similar in nature to Bluetooth pairing.\n{{\u003c /admonition \u003e}}\n\nOpen **Settings** \u003e **Local Drives**. Sambee checks whether it can find the Companion app. You should see a check mark next to **Companion app is running**.\n\nSelect **Pair this browser**. Sambee starts a pairing request for the exact site you are currently using, and Companion opens a native approval window that shows both:\n\n- the requesting browser origin\n- a short verification code\n\nSambee shows the same verification code in the browser. Confirm the pairing only when both codes match and the origin shown in Companion is the Sambee site you expect.\n\nAfter you approve the request in Companion and confirm it in the browser, Sambee should show a check mark next to **This browser is paired**.\n\nOnce Sambee is paired with Companion, local drives on your computer appear in Sambee's connection list.\n\n## What to Expect Later\n\nPairing is specific to the current browser origin.\n\n- If you use Sambee from a different site or port, that browser origin may need its own pairing.\n- If you close the pairing dialog before finishing, the request is cancelled instead of staying pending silently.\n- If Sambee later reports that the browser needs repair, start pairing again from **Settings** \u003e **Local Drives** to restore the browser-side secret.\n", "0.9": "+++\ntitle = \"Install and Pair the Companion App\"\n+++\n\nSambee Companion is a desktop helper app that enables Sambee to connect from the browser to local drives on your computer and to open files in natively installed desktop apps.\n\nYou do not need Companion for accessing SMB shares from the browser.\n\n## Install Companion\n\n1. Open **Settings** \u003e **Local Drives** and select **Download for this computer** to download the Companion installer.\n1. Run the installer and follow the prompts. Make sure to enable auto-starting Companion.\n1. Once the installer is completed, Companion should be running.\n1. You can find the Companion icon in the system tray (Linux, Windows) or the menu bar (macOS).\n\n## Pair Sambee With Companion\n\n{{\u003c admonition type=\"note\" title=\"\" \u003e}}\nDuring pairing, Sambee and Companion exchange data that is needed to establish a secure connection. The concept is similar in nature to Bluetooth pairing.\n{{\u003c /admonition \u003e}}\n\nOpen **Settings** \u003e **Local Drives**. Sambee checks whether it can find the Companion app. You should see a check mark next to **Companion app is running**.\n\nSelect **Pair this browser**. Sambee starts a pairing request for the exact site you are currently using, and Companion opens a native approval window that shows both:\n\n- the requesting browser origin\n- a short verification code\n\nSambee shows the same verification code in the browser. Confirm the pairing only when both codes match and the origin shown in Companion is the Sambee site you expect.\n\nAfter you approve the request in Companion and confirm it in the browser, Sambee should show a check mark next to **This browser is paired**.\n\nOnce Sambee is paired with Companion, local drives on your computer appear in Sambee's connection list.\n\n## What to Expect Later\n\nPairing is specific to the current browser origin.\n\n- If you use Sambee from a different site or port, that browser origin may need its own pairing.\n- If you close the pairing dialog before finishing, the request is cancelled instead of staying pending silently.\n- If Sambee later reports that the browser needs repair, start pairing again from **Settings** \u003e **Local Drives** to restore the browser-side secret.\n", "1.0": "+++\ntitle = \"Install and Pair the Companion App\"\n+++\n\nSambee Companion is a desktop helper app that enables Sambee to connect from the browser to local drives on your computer and to open files in natively installed desktop apps.\n\nYou do not need Companion for accessing SMB shares from the browser.\n\n## Install Companion\n\n1. Open **Settings** \u003e **Local Drives** and select **Download for this computer** to download the Companion installer.\n1. Run the installer and follow the prompts. Make sure to enable auto-starting Companion.\n1. Once the installer is completed, Companion should be running.\n1. You can find the Companion icon in the system tray (Linux, Windows) or the menu bar (macOS).\n\n## Pair Sambee With Companion\n\n{{\u003c admonition type=\"note\" title=\"\" \u003e}}\nDuring pairing, Sambee and Companion exchange data that is needed to establish a secure connection. The concept is similar in nature to Bluetooth pairing.\n{{\u003c /admonition \u003e}}\n\nOpen **Settings** \u003e **Local Drives**. Sambee checks whether it can find the Companion app. You should see a check mark next to **Companion app is running**.\n\nSelect **Pair this browser**. Sambee starts a pairing request for the exact site you are currently using, and Companion opens a native approval window that shows both:\n\n- the requesting browser origin\n- a short verification code\n\nSambee shows the same verification code in the browser. Confirm the pairing only when both codes match and the origin shown in Companion is the Sambee site you expect.\n\nAfter you approve the request in Companion and confirm it in the browser, Sambee should show a check mark next to **This browser is paired**.\n\nOnce Sambee is paired with Companion, local drives on your computer appear in Sambee's connection list.\n\n## What to Expect Later\n\nPairing is specific to the current browser origin.\n\n- If you use Sambee from a different site or port, that browser origin may need its own pairing.\n- If you close the pairing dialog before finishing, the request is cancelled instead of staying pending silently.\n- If Sambee later reports that the browser needs repair, start pairing again from **Settings** \u003e **Local Drives** to restore the browser-side secret.\n", "2.0": "+++\ntitle = \"Install and Pair the Companion App\"\n+++\n\nSambee Companion is a desktop helper app that enables Sambee to connect from the browser to local drives on your computer and to open files in natively installed desktop apps.\n\nYou do not need Companion for accessing SMB shares from the browser.\n\n## Install Companion\n\n1. Open **Settings** \u003e **Local Drives** and select **Download for this computer** to download the Companion installer.\n1. Run the installer and follow the prompts. Make sure to enable auto-starting Companion.\n1. Once the installer is completed, Companion should be running.\n1. You can find the Companion icon in the system tray (Linux, Windows) or the menu bar (macOS).\n\n## Pair Sambee With Companion\n\nOpen Sambee over HTTPS before pairing from another computer or a network address. Browsers don't provide the cryptographic APIs needed by Companion on ordinary HTTP sites. Local development on `http://localhost` is an exception. If **Local Drives** warns that a secure browser context with Web Crypto support is unavailable, use HTTPS; if you're already using HTTPS, check that your browser supports and permits Web Crypto. You don't need HTTPS to download the Companion installer.\n\n{{\u003c admonition type=\"note\" title=\"\" \u003e}}\nDuring pairing, Sambee and Companion exchange data that is needed to establish a secure connection. The concept is similar in nature to Bluetooth pairing.\n{{\u003c /admonition \u003e}}\n\nOpen **Settings** \u003e **Local Drives**. Sambee checks whether it can find the Companion app. You should see a check mark next to **Companion app is running**.\n\nSelect **Pair this browser**. Sambee starts a pairing request for the exact site you are currently using, and Companion opens a native approval window that shows both:\n\n- the requesting browser origin\n- a short verification code\n\nSambee shows the same verification code in the browser. Confirm the pairing only when both codes match and the origin shown in Companion is the Sambee site you expect.\n\nAfter you approve the request in Companion and confirm it in the browser, Sambee verifies local access and shows a check mark next to **This browser is paired**.\n\nOnce Sambee is paired with Companion, local drives on your computer appear in Sambee's connection list.\n\n## What to Expect Later\n\nPairing is specific to the current browser origin.\n\n- If you use Sambee from a different site or port, that browser origin may need its own pairing.\n- If you close the pairing dialog before finishing, the request is cancelled instead of staying pending silently.\n\n## Restore Local-Drive Access\n\nIf a local drive reports a pairing error, open **Settings** \u003e **Local Drives** from the file-list alert. **Ready** means the browser has passed an authenticated pairing check; having a stored pairing alone is not enough.\n\n1. If Companion needs an update, install the available version, restart Companion, and reload the Sambee page. Re-pairing will not resolve an incompatible version.\n1. If Sambee needs an update, reload the page. If the version mismatch remains, update Sambee. Updating Companion or re-pairing will not fix a newer Companion protocol.\n1. If the file-list alert says this browser isn't paired, open **Local Drives** and select **Pair This Browser**. Reloading alone won't restore a missing or removed pairing.\n1. If Companion rejects the browser's signature, reload the Sambee page first. A page left open across an update may still use the previous authentication protocol.\n1. Run **Test Current Pairing**. If it still fails with a signature error after reloading, use **Pair This Browser** and approve the new code in Companion.\n\nIf Sambee cannot check the pairing status, select **Retry**. Wait for a confirmed status before starting a new pairing. Companion pairing secrets do not expire on a 30-day timer. An unavailable Companion or a temporary failed check does not mean you need to re-pair.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:user-guide/companion-app/desktop-app-picker", "parent_id": "section:user-guide/companion-app", "depth": 2, "kind": "page", "label": "desktop-app-picker", "title": "Desktop App Picker", "path": "user-guide/companion-app/desktop-app-picker", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Desktop App Picker\"\n+++\n\nThe app picker lets you choose which installed desktop app should open a file.\n\n## The App Picker\n\nWhen you use **Open in companion app**, Sambee hands the request to Companion. Companion then opens an app picker dialog that lists the installed apps registered for the selected file type.\n\nThe picker groups apps into these sections:\n\n- **Default**\n- **Suggested apps**\n- **More options**\n\n### Choose or Change the App\n\nTo continue:\n\n- Select the app you want.\n- Choose **Open**.\n\nYou can also use **Choose another app** to browse to a specific executable.\n\n### Remember the Selection\n\nIf you turn on **Always use this app** for a file type, Companion saves that executable as the preferred app for that extension.\n\nOn later opens, Companion still shows the picker, but it preselects the saved app for you. It does not silently skip the picker.\n\nIf you want to replace the remembered app for an extension, choose a different app and leave **Always use this app** turned on when you open it.\n", "0.8": "+++\ntitle = \"Desktop App Picker\"\n+++\n\nThe app picker lets you choose which installed desktop app should open a file.\n\n## The App Picker\n\nWhen you use **Open in companion app**, Sambee hands the request to Companion. Companion then opens an app picker dialog that lists the installed apps registered for the selected file type.\n\nThe picker groups apps into these sections:\n\n- **Default**\n- **Suggested apps**\n- **More options**\n\n### Choose or Change the App\n\nTo continue:\n\n- Select the app you want.\n- Choose **Open**.\n\nYou can also use **Choose another app** to browse to a specific executable.\n\n### Remember the Selection\n\nIf you turn on **Always use this app** for a file type, Companion saves that executable as the preferred app for that extension.\n\nOn later opens, Companion still shows the picker, but it preselects the saved app for you. It does not silently skip the picker.\n\nIf you want to replace the remembered app for an extension, choose a different app and leave **Always use this app** turned on when you open it.\n", "0.9": "+++\ntitle = \"Desktop App Picker\"\n+++\n\nThe app picker lets you choose which installed desktop app should open a file.\n\n## The App Picker\n\nWhen you use **Open in companion app**, Sambee hands the request to Companion. Companion then opens an app picker dialog that lists the installed apps registered for the selected file type.\n\nThe picker groups apps into these sections:\n\n- **Default**\n- **Suggested apps**\n- **More options**\n\n### Choose or Change the App\n\nTo continue:\n\n- Select the app you want.\n- Choose **Open**.\n\nYou can also use **Choose another app** to browse to a specific executable.\n\n### Remember the Selection\n\nIf you turn on **Always use this app** for a file type, Companion saves that executable as the preferred app for that extension.\n\nOn later opens, Companion still shows the picker, but it preselects the saved app for you. It does not silently skip the picker.\n\nIf you want to replace the remembered app for an extension, choose a different app and leave **Always use this app** turned on when you open it.\n", "1.0": "+++\ntitle = \"Desktop App Picker\"\n+++\n\nThe app picker lets you choose which installed desktop app should open a file.\n\n## The App Picker\n\nWhen you use **Open in companion app**, Sambee hands the request to Companion. Companion then opens an app picker dialog that lists the installed apps registered for the selected file type.\n\nThe picker groups apps into these sections:\n\n- **Default**\n- **Suggested apps**\n- **More options**\n\n### Choose or Change the App\n\nTo continue:\n\n- Select the app you want.\n- Choose **Open**.\n\nYou can also use **Choose another app** to browse to a specific executable.\n\n### Remember the Selection\n\nIf you turn on **Always use this app** for a file type, Companion saves that executable as the preferred app for that extension.\n\nOn later opens, Companion still shows the picker, but it preselects the saved app for you. It does not silently skip the picker.\n\nIf you want to replace the remembered app for an extension, choose a different app and leave **Always use this app** turned on when you open it.\n", "2.0": "+++\ntitle = \"Desktop App Picker\"\n+++\n\nThe app picker lets you choose which installed desktop app should open a file.\n\n## The App Picker\n\nWhen you use **Open in companion app**, Sambee hands the request to Companion. Companion then opens an app picker dialog that lists the installed apps registered for the selected file type.\n\nThe picker groups apps into these sections:\n\n- **Default**\n- **Suggested apps**\n- **More options**\n\n### Choose or Change the App\n\nTo continue:\n\n- Select the app you want.\n- Choose **Open**.\n\nYou can also use **Choose another app** to browse to a specific executable.\n\n### Remember the Selection\n\nIf you turn on **Always use this app** for a file type, Companion saves that executable as the preferred app for that extension.\n\nOn later opens, Companion still shows the picker, but it preselects the saved app for you. It does not silently skip the picker.\n\nIf you want to replace the remembered app for an extension, choose a different app and leave **Always use this app** turned on when you open it.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Desktop App Picker\"\n+++\n\nThe app picker lets you choose which installed desktop app should open a file.\n\n## The App Picker\n\nWhen you use **Open in companion app**, Sambee hands the request to Companion. Companion then opens an app picker dialog that lists the installed apps registered for the selected file type.\n\nThe picker groups apps into these sections:\n\n- **Default**\n- **Suggested apps**\n- **More options**\n\n### Choose or Change the App\n\nTo continue:\n\n- Select the app you want.\n- Choose **Open**.\n\nYou can also use **Choose another app** to browse to a specific executable.\n\n### Remember the Selection\n\nIf you turn on **Always use this app** for a file type, Companion saves that executable as the preferred app for that extension.\n\nOn later opens, Companion still shows the picker, but it preselects the saved app for you. It does not silently skip the picker.\n\nIf you want to replace the remembered app for an extension, choose a different app and leave **Always use this app** turned on when you open it.\n", "0.8": "+++\ntitle = \"Desktop App Picker\"\n+++\n\nThe app picker lets you choose which installed desktop app should open a file.\n\n## The App Picker\n\nWhen you use **Open in companion app**, Sambee hands the request to Companion. Companion then opens an app picker dialog that lists the installed apps registered for the selected file type.\n\nThe picker groups apps into these sections:\n\n- **Default**\n- **Suggested apps**\n- **More options**\n\n### Choose or Change the App\n\nTo continue:\n\n- Select the app you want.\n- Choose **Open**.\n\nYou can also use **Choose another app** to browse to a specific executable.\n\n### Remember the Selection\n\nIf you turn on **Always use this app** for a file type, Companion saves that executable as the preferred app for that extension.\n\nOn later opens, Companion still shows the picker, but it preselects the saved app for you. It does not silently skip the picker.\n\nIf you want to replace the remembered app for an extension, choose a different app and leave **Always use this app** turned on when you open it.\n", "0.9": "+++\ntitle = \"Desktop App Picker\"\n+++\n\nThe app picker lets you choose which installed desktop app should open a file.\n\n## The App Picker\n\nWhen you use **Open in companion app**, Sambee hands the request to Companion. Companion then opens an app picker dialog that lists the installed apps registered for the selected file type.\n\nThe picker groups apps into these sections:\n\n- **Default**\n- **Suggested apps**\n- **More options**\n\n### Choose or Change the App\n\nTo continue:\n\n- Select the app you want.\n- Choose **Open**.\n\nYou can also use **Choose another app** to browse to a specific executable.\n\n### Remember the Selection\n\nIf you turn on **Always use this app** for a file type, Companion saves that executable as the preferred app for that extension.\n\nOn later opens, Companion still shows the picker, but it preselects the saved app for you. It does not silently skip the picker.\n\nIf you want to replace the remembered app for an extension, choose a different app and leave **Always use this app** turned on when you open it.\n", "1.0": "+++\ntitle = \"Desktop App Picker\"\n+++\n\nThe app picker lets you choose which installed desktop app should open a file.\n\n## The App Picker\n\nWhen you use **Open in companion app**, Sambee hands the request to Companion. Companion then opens an app picker dialog that lists the installed apps registered for the selected file type.\n\nThe picker groups apps into these sections:\n\n- **Default**\n- **Suggested apps**\n- **More options**\n\n### Choose or Change the App\n\nTo continue:\n\n- Select the app you want.\n- Choose **Open**.\n\nYou can also use **Choose another app** to browse to a specific executable.\n\n### Remember the Selection\n\nIf you turn on **Always use this app** for a file type, Companion saves that executable as the preferred app for that extension.\n\nOn later opens, Companion still shows the picker, but it preselects the saved app for you. It does not silently skip the picker.\n\nIf you want to replace the remembered app for an extension, choose a different app and leave **Always use this app** turned on when you open it.\n", "2.0": "+++\ntitle = \"Desktop App Picker\"\n+++\n\nThe app picker lets you choose which installed desktop app should open a file.\n\n## The App Picker\n\nWhen you use **Open in companion app**, Sambee hands the request to Companion. Companion then opens an app picker dialog that lists the installed apps registered for the selected file type.\n\nThe picker groups apps into these sections:\n\n- **Default**\n- **Suggested apps**\n- **More options**\n\n### Choose or Change the App\n\nTo continue:\n\n- Select the app you want.\n- Choose **Open**.\n\nYou can also use **Choose another app** to browse to a specific executable.\n\n### Remember the Selection\n\nIf you turn on **Always use this app** for a file type, Companion saves that executable as the preferred app for that extension.\n\nOn later opens, Companion still shows the picker, but it preselects the saved app for you. It does not silently skip the picker.\n\nIf you want to replace the remembered app for an extension, choose a different app and leave **Always use this app** turned on when you open it.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:user-guide/troubleshooting", "parent_id": "book:user-guide", "depth": 1, "kind": "section", "label": "troubleshooting", "title": "Troubleshooting", "path": "user-guide/troubleshooting", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:user-guide/troubleshooting/common-user-problems", "parent_id": "section:user-guide/troubleshooting", "depth": 2, "kind": "page", "label": "common-user-problems", "title": "Common User Problems", "path": "user-guide/troubleshooting/common-user-problems", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "branched", "source_version": "0.7", "diff_added": 5, "diff_removed": 8}, "0.9": {"state": "inherited", "source_version": "0.8"}, "1.0": {"state": "inherited", "source_version": "0.8"}, "2.0": {"state": "inherited", "source_version": "0.8"}}, "content_versions": {"0.7": "+++\ntitle = \"Common User Problems\"\n+++\n\n## Local Drives Are Not Available\n\nLocal drives in the browser require a desktop browser, Sambee Companion, and a working browser pairing for the current browser profile.\n\nWork through this checklist:\n\n1. Confirm that you are using a desktop browser. Local-drive access is not available on iPhone, iPad, or Android browsers.\n1. Confirm that Sambee Companion is installed and running on the same computer as the browser.\n1. Open **Settings** \u003e **Local Drives** and check the current status.\n1. If the browser is not paired, start pairing again for this browser.\n1. If Local Drives reports that pairing needs repair, repair the pairing so Sambee can store a fresh browser-side secret.\n\nIf you still need the full setup flow, continue with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/) and [Access Local Drives](../../accessing-files/access-local-drives/).\n\n## Open in Desktop App Does Nothing\n\nThis usually means Sambee Companion is not running, or the browser blocked the handoff to the helper app.\n\nCheck these first:\n\n- Confirm that Sambee Companion is running on your computer.\n- Allow the browser to open the `sambee://` link if the browser asks for permission.\n- On Linux, confirm that the deep-link handler is registered with `xdg-mime query default x-scheme-handler/sambee`.\n\nStart with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/) if Companion may not be installed or running yet.\n\nNormal desktop-editing workflow: [Edit Files in Desktop Apps](../../viewing-and-editing-files/edit-files-in-desktop-apps/).\n\n## Changes Do Not Upload Back after Editing\n\nThe desktop-editing session may have expired or been interrupted.\n\nTypical signs are that the **Done Editing** window says the session expired, authentication failed, the lock was lost, or recovery is required.\n\nStart by reopening the file from Sambee so Companion can establish a fresh edit session and lock context.\n\nSee: [File Locking \u0026 Conflict Resolution](../../viewing-and-editing-files/file-locking-and-conflict-resolution/).\n", "0.8": "+++\ntitle = \"Common User Problems\"\n+++\n\n## Local Drives Are Not Available\n\nLocal drives in the browser require a desktop browser, Sambee Companion, and a working browser pairing.\n\nWork through this checklist:\n\n1. Confirm that you are using a desktop browser. Local-drive access is not available on iPhone, iPad, or Android browsers.\n1. Confirm that Sambee Companion is installed and running on the same computer as the browser.\n1. Open **Settings** \u003e **Local Drives** and check the current status.\n1. If Sambee shows **Waiting for approval**, finish or reject the request in the Companion pairing window.\n1. If Sambee shows that this browser needs repair, start pairing again to restore the browser-side secret.\n1. If you closed the pairing dialog earlier, start a new pairing request. Pending requests are cancelled when either side closes the pairing UI.\n\nIf you still need the full setup flow, continue with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/) and [Access Local Drives](../../accessing-files/access-local-drives/).\n\n## Open in Desktop App Does Nothing\n\nThis usually means Sambee Companion is not running, or the browser blocked the handoff to the helper app.\n\nCheck these first:\n\n- Confirm that Sambee Companion is running on your computer.\n- Allow the browser to open the `sambee://` link if the browser asks for permission.\n- On Linux, confirm that the deep-link handler is registered with `xdg-mime query default x-scheme-handler/sambee`.\n\nStart with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/) if Companion may not be installed or running yet.\n\nNormal desktop-editing workflow: [Edit Files in Desktop Apps](../../viewing-and-editing-files/edit-files-in-desktop-apps/).\n\n## Changes Do Not Upload Back after Editing\n\nThe Companion session may have been interrupted.\n\nSee: [File Locking \u0026 Conflict Resolution](../../viewing-and-editing-files/file-locking-and-conflict-resolution/).\n", "0.9": "+++\ntitle = \"Common User Problems\"\n+++\n\n## Local Drives Are Not Available\n\nLocal drives in the browser require a desktop browser, Sambee Companion, and a working browser pairing.\n\nWork through this checklist:\n\n1. Confirm that you are using a desktop browser. Local-drive access is not available on iPhone, iPad, or Android browsers.\n1. Confirm that Sambee Companion is installed and running on the same computer as the browser.\n1. Open **Settings** \u003e **Local Drives** and check the current status.\n1. If Sambee shows **Waiting for approval**, finish or reject the request in the Companion pairing window.\n1. If Sambee shows that this browser needs repair, start pairing again to restore the browser-side secret.\n1. If you closed the pairing dialog earlier, start a new pairing request. Pending requests are cancelled when either side closes the pairing UI.\n\nIf you still need the full setup flow, continue with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/) and [Access Local Drives](../../accessing-files/access-local-drives/).\n\n## Open in Desktop App Does Nothing\n\nThis usually means Sambee Companion is not running, or the browser blocked the handoff to the helper app.\n\nCheck these first:\n\n- Confirm that Sambee Companion is running on your computer.\n- Allow the browser to open the `sambee://` link if the browser asks for permission.\n- On Linux, confirm that the deep-link handler is registered with `xdg-mime query default x-scheme-handler/sambee`.\n\nStart with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/) if Companion may not be installed or running yet.\n\nNormal desktop-editing workflow: [Edit Files in Desktop Apps](../../viewing-and-editing-files/edit-files-in-desktop-apps/).\n\n## Changes Do Not Upload Back after Editing\n\nThe Companion session may have been interrupted.\n\nSee: [File Locking \u0026 Conflict Resolution](../../viewing-and-editing-files/file-locking-and-conflict-resolution/).\n", "1.0": "+++\ntitle = \"Common User Problems\"\n+++\n\n## Local Drives Are Not Available\n\nLocal drives in the browser require a desktop browser, Sambee Companion, and a working browser pairing.\n\nWork through this checklist:\n\n1. Confirm that you are using a desktop browser. Local-drive access is not available on iPhone, iPad, or Android browsers.\n1. Confirm that Sambee Companion is installed and running on the same computer as the browser.\n1. Open **Settings** \u003e **Local Drives** and check the current status.\n1. If Sambee shows **Waiting for approval**, finish or reject the request in the Companion pairing window.\n1. If Sambee shows that this browser needs repair, start pairing again to restore the browser-side secret.\n1. If you closed the pairing dialog earlier, start a new pairing request. Pending requests are cancelled when either side closes the pairing UI.\n\nIf you still need the full setup flow, continue with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/) and [Access Local Drives](../../accessing-files/access-local-drives/).\n\n## Open in Desktop App Does Nothing\n\nThis usually means Sambee Companion is not running, or the browser blocked the handoff to the helper app.\n\nCheck these first:\n\n- Confirm that Sambee Companion is running on your computer.\n- Allow the browser to open the `sambee://` link if the browser asks for permission.\n- On Linux, confirm that the deep-link handler is registered with `xdg-mime query default x-scheme-handler/sambee`.\n\nStart with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/) if Companion may not be installed or running yet.\n\nNormal desktop-editing workflow: [Edit Files in Desktop Apps](../../viewing-and-editing-files/edit-files-in-desktop-apps/).\n\n## Changes Do Not Upload Back after Editing\n\nThe Companion session may have been interrupted.\n\nSee: [File Locking \u0026 Conflict Resolution](../../viewing-and-editing-files/file-locking-and-conflict-resolution/).\n", "2.0": "+++\ntitle = \"Common User Problems\"\n+++\n\n## Local Drives Are Not Available\n\nLocal drives in the browser require a desktop browser, Sambee Companion, and a working browser pairing.\n\nWork through this checklist:\n\n1. Confirm that you are using a desktop browser. Local-drive access is not available on iPhone, iPad, or Android browsers.\n1. Confirm that Sambee Companion is installed and running on the same computer as the browser.\n1. Open **Settings** \u003e **Local Drives** and check the current status.\n1. If Sambee shows **Waiting for approval**, finish or reject the request in the Companion pairing window.\n1. If Sambee shows that this browser needs repair, start pairing again to restore the browser-side secret.\n1. If you closed the pairing dialog earlier, start a new pairing request. Pending requests are cancelled when either side closes the pairing UI.\n\nIf you still need the full setup flow, continue with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/) and [Access Local Drives](../../accessing-files/access-local-drives/).\n\n## Open in Desktop App Does Nothing\n\nThis usually means Sambee Companion is not running, or the browser blocked the handoff to the helper app.\n\nCheck these first:\n\n- Confirm that Sambee Companion is running on your computer.\n- Allow the browser to open the `sambee://` link if the browser asks for permission.\n- On Linux, confirm that the deep-link handler is registered with `xdg-mime query default x-scheme-handler/sambee`.\n\nStart with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/) if Companion may not be installed or running yet.\n\nNormal desktop-editing workflow: [Edit Files in Desktop Apps](../../viewing-and-editing-files/edit-files-in-desktop-apps/).\n\n## Changes Do Not Upload Back after Editing\n\nThe Companion session may have been interrupted.\n\nSee: [File Locking \u0026 Conflict Resolution](../../viewing-and-editing-files/file-locking-and-conflict-resolution/).\n"}, "page_contents": {"0.7": "+++\ntitle = \"Common User Problems\"\n+++\n\n## Local Drives Are Not Available\n\nLocal drives in the browser require a desktop browser, Sambee Companion, and a working browser pairing for the current browser profile.\n\nWork through this checklist:\n\n1. Confirm that you are using a desktop browser. Local-drive access is not available on iPhone, iPad, or Android browsers.\n1. Confirm that Sambee Companion is installed and running on the same computer as the browser.\n1. Open **Settings** \u003e **Local Drives** and check the current status.\n1. If the browser is not paired, start pairing again for this browser.\n1. If Local Drives reports that pairing needs repair, repair the pairing so Sambee can store a fresh browser-side secret.\n\nIf you still need the full setup flow, continue with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/) and [Access Local Drives](../../accessing-files/access-local-drives/).\n\n## Open in Desktop App Does Nothing\n\nThis usually means Sambee Companion is not running, or the browser blocked the handoff to the helper app.\n\nCheck these first:\n\n- Confirm that Sambee Companion is running on your computer.\n- Allow the browser to open the `sambee://` link if the browser asks for permission.\n- On Linux, confirm that the deep-link handler is registered with `xdg-mime query default x-scheme-handler/sambee`.\n\nStart with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/) if Companion may not be installed or running yet.\n\nNormal desktop-editing workflow: [Edit Files in Desktop Apps](../../viewing-and-editing-files/edit-files-in-desktop-apps/).\n\n## Changes Do Not Upload Back after Editing\n\nThe desktop-editing session may have expired or been interrupted.\n\nTypical signs are that the **Done Editing** window says the session expired, authentication failed, the lock was lost, or recovery is required.\n\nStart by reopening the file from Sambee so Companion can establish a fresh edit session and lock context.\n\nSee: [File Locking \u0026 Conflict Resolution](../../viewing-and-editing-files/file-locking-and-conflict-resolution/).\n", "0.8": "+++\ntitle = \"Common User Problems\"\n+++\n\n## Local Drives Are Not Available\n\nLocal drives in the browser require a desktop browser, Sambee Companion, and a working browser pairing.\n\nWork through this checklist:\n\n1. Confirm that you are using a desktop browser. Local-drive access is not available on iPhone, iPad, or Android browsers.\n1. Confirm that Sambee Companion is installed and running on the same computer as the browser.\n1. Open **Settings** \u003e **Local Drives** and check the current status.\n1. If Sambee shows **Waiting for approval**, finish or reject the request in the Companion pairing window.\n1. If Sambee shows that this browser needs repair, start pairing again to restore the browser-side secret.\n1. If you closed the pairing dialog earlier, start a new pairing request. Pending requests are cancelled when either side closes the pairing UI.\n\nIf you still need the full setup flow, continue with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/) and [Access Local Drives](../../accessing-files/access-local-drives/).\n\n## Open in Desktop App Does Nothing\n\nThis usually means Sambee Companion is not running, or the browser blocked the handoff to the helper app.\n\nCheck these first:\n\n- Confirm that Sambee Companion is running on your computer.\n- Allow the browser to open the `sambee://` link if the browser asks for permission.\n- On Linux, confirm that the deep-link handler is registered with `xdg-mime query default x-scheme-handler/sambee`.\n\nStart with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/) if Companion may not be installed or running yet.\n\nNormal desktop-editing workflow: [Edit Files in Desktop Apps](../../viewing-and-editing-files/edit-files-in-desktop-apps/).\n\n## Changes Do Not Upload Back after Editing\n\nThe Companion session may have been interrupted.\n\nSee: [File Locking \u0026 Conflict Resolution](../../viewing-and-editing-files/file-locking-and-conflict-resolution/).\n", "0.9": "+++\ntitle = \"Common User Problems\"\n+++\n\n## Local Drives Are Not Available\n\nLocal drives in the browser require a desktop browser, Sambee Companion, and a working browser pairing.\n\nWork through this checklist:\n\n1. Confirm that you are using a desktop browser. Local-drive access is not available on iPhone, iPad, or Android browsers.\n1. Confirm that Sambee Companion is installed and running on the same computer as the browser.\n1. Open **Settings** \u003e **Local Drives** and check the current status.\n1. If Sambee shows **Waiting for approval**, finish or reject the request in the Companion pairing window.\n1. If Sambee shows that this browser needs repair, start pairing again to restore the browser-side secret.\n1. If you closed the pairing dialog earlier, start a new pairing request. Pending requests are cancelled when either side closes the pairing UI.\n\nIf you still need the full setup flow, continue with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/) and [Access Local Drives](../../accessing-files/access-local-drives/).\n\n## Open in Desktop App Does Nothing\n\nThis usually means Sambee Companion is not running, or the browser blocked the handoff to the helper app.\n\nCheck these first:\n\n- Confirm that Sambee Companion is running on your computer.\n- Allow the browser to open the `sambee://` link if the browser asks for permission.\n- On Linux, confirm that the deep-link handler is registered with `xdg-mime query default x-scheme-handler/sambee`.\n\nStart with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/) if Companion may not be installed or running yet.\n\nNormal desktop-editing workflow: [Edit Files in Desktop Apps](../../viewing-and-editing-files/edit-files-in-desktop-apps/).\n\n## Changes Do Not Upload Back after Editing\n\nThe Companion session may have been interrupted.\n\nSee: [File Locking \u0026 Conflict Resolution](../../viewing-and-editing-files/file-locking-and-conflict-resolution/).\n", "1.0": "+++\ntitle = \"Common User Problems\"\n+++\n\n## Local Drives Are Not Available\n\nLocal drives in the browser require a desktop browser, Sambee Companion, and a working browser pairing.\n\nWork through this checklist:\n\n1. Confirm that you are using a desktop browser. Local-drive access is not available on iPhone, iPad, or Android browsers.\n1. Confirm that Sambee Companion is installed and running on the same computer as the browser.\n1. Open **Settings** \u003e **Local Drives** and check the current status.\n1. If Sambee shows **Waiting for approval**, finish or reject the request in the Companion pairing window.\n1. If Sambee shows that this browser needs repair, start pairing again to restore the browser-side secret.\n1. If you closed the pairing dialog earlier, start a new pairing request. Pending requests are cancelled when either side closes the pairing UI.\n\nIf you still need the full setup flow, continue with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/) and [Access Local Drives](../../accessing-files/access-local-drives/).\n\n## Open in Desktop App Does Nothing\n\nThis usually means Sambee Companion is not running, or the browser blocked the handoff to the helper app.\n\nCheck these first:\n\n- Confirm that Sambee Companion is running on your computer.\n- Allow the browser to open the `sambee://` link if the browser asks for permission.\n- On Linux, confirm that the deep-link handler is registered with `xdg-mime query default x-scheme-handler/sambee`.\n\nStart with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/) if Companion may not be installed or running yet.\n\nNormal desktop-editing workflow: [Edit Files in Desktop Apps](../../viewing-and-editing-files/edit-files-in-desktop-apps/).\n\n## Changes Do Not Upload Back after Editing\n\nThe Companion session may have been interrupted.\n\nSee: [File Locking \u0026 Conflict Resolution](../../viewing-and-editing-files/file-locking-and-conflict-resolution/).\n", "2.0": "+++\ntitle = \"Common User Problems\"\n+++\n\n## Local Drives Are Not Available\n\nLocal drives in the browser require a desktop browser, Sambee Companion, and a working browser pairing.\n\nWork through this checklist:\n\n1. Confirm that you are using a desktop browser. Local-drive access is not available on iPhone, iPad, or Android browsers.\n1. Confirm that Sambee Companion is installed and running on the same computer as the browser.\n1. Open **Settings** \u003e **Local Drives** and check the current status.\n1. If Sambee shows **Waiting for approval**, finish or reject the request in the Companion pairing window.\n1. If Sambee shows that this browser needs repair, start pairing again to restore the browser-side secret.\n1. If you closed the pairing dialog earlier, start a new pairing request. Pending requests are cancelled when either side closes the pairing UI.\n\nIf you still need the full setup flow, continue with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/) and [Access Local Drives](../../accessing-files/access-local-drives/).\n\n## Open in Desktop App Does Nothing\n\nThis usually means Sambee Companion is not running, or the browser blocked the handoff to the helper app.\n\nCheck these first:\n\n- Confirm that Sambee Companion is running on your computer.\n- Allow the browser to open the `sambee://` link if the browser asks for permission.\n- On Linux, confirm that the deep-link handler is registered with `xdg-mime query default x-scheme-handler/sambee`.\n\nStart with [Install and Pair the Companion App](../../companion-app/install-and-pair-the-companion-app/) if Companion may not be installed or running yet.\n\nNormal desktop-editing workflow: [Edit Files in Desktop Apps](../../viewing-and-editing-files/edit-files-in-desktop-apps/).\n\n## Changes Do Not Upload Back after Editing\n\nThe Companion session may have been interrupted.\n\nSee: [File Locking \u0026 Conflict Resolution](../../viewing-and-editing-files/file-locking-and-conflict-resolution/).\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:user-guide/reference", "parent_id": "book:user-guide", "depth": 1, "kind": "section", "label": "reference", "title": "Reference", "path": "user-guide/reference", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:user-guide/reference/supported-file-formats", "parent_id": "section:user-guide/reference", "depth": 2, "kind": "page", "label": "supported-file-formats", "title": "Supported File Formats", "path": "user-guide/reference/supported-file-formats", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "branched", "source_version": "0.7", "diff_added": 2, "diff_removed": 0}, "0.9": {"state": "inherited", "source_version": "0.8"}, "1.0": {"state": "branched", "source_version": "0.8", "diff_added": 11, "diff_removed": 3}, "2.0": {"state": "inherited", "source_version": "1.0"}}, "content_versions": {"0.7": "+++\ntitle = \"Supported File Formats\"\n+++\n\nThis page lists the file types Sambee can open in its viewers in the browser.\n\n## Overview\n\n| Category | Extensions | What to expect |\n|---|---|---|\n| Common browser image formats | `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`, `.svg`, `.avif` | Open in the image viewer with zoom, pan, and related controls. |\n| Converted image formats | `.tif`, `.tiff`, `.heic`, `.heif`, `.bmp`, `.dib`, `.ico`, `.cur`, `.pcx`, `.tga`, `.ppm`, `.pgm`, `.pbm`, `.pnm`, `.xbm`, `.xpm`, `.psd`, `.psb`, `.eps`, `.ai`, `.jp2`, `.j2k`, `.jpt`, `.j2c`, `.jpc`, `.jxl`, `.exr`, `.hdr`, `.fits`, `.fit`, `.fts`, `.svs`, `.ndpi`, `.scn`, `.mrxs`, `.vms`, `.vmu`, `.bif`, `.img`, `.mat` | Sambee converts the file into a browser-ready image before opening it in the image viewer. |\n| PDF | `.pdf` | Open in the PDF viewer with page navigation, search, zoom, and download support. |\n| Markdown | `.md`, `.markdown` | Open in a rendered Markdown view with an optional edit path. |\n\n## Format-Specific Notes\n\nSome converted image formats have specific behavior that is useful to know ahead of time.\n\n- CMYK images are converted to browser-safe sRGB.\n- Multi-page TIFF files open with the first page rather than every page in the source file.\n- PSD and PSB files show the flattened composite view, not interactive layer editing.\n- EPS and AI files are rendered into a high-quality raster image for viewing in the browser.\n- HDR formats such as EXR and Radiance HDR are tone-mapped for ordinary browser display.\n- Whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF open as an overview or first practical level rather than as a full microscopy workstation.\n- FITS and similar scientific-image files use visibility scaling so the content is inspectable in the browser.\n\n## When a File Type Is Not Supported or You Need the Original\n\nIf a file type is not supported by Sambee's viewers, or if you need the original editing experience, use one of the following:\n\n- Download the file.\n- Open it in a desktop app through Companion.\n\nFor the broader workflow explanation, see [View Images \u0026 Read Documents](../../viewing-and-editing-files/view-images-and-read-documents/).\n", "0.8": "+++\ntitle = \"Supported File Formats\"\n+++\n\nThis page lists the file types Sambee can open in its viewers in the browser.\n\n## Overview\n\n| Category | Extensions | What to expect |\n|---|---|---|\n| Common browser image formats | `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`, `.svg`, `.avif` | Open in the image viewer with zoom, pan, and related controls. |\n| Converted image formats | `.tif`, `.tiff`, `.heic`, `.heif`, `.bmp`, `.dib`, `.ico`, `.cur`, `.pcx`, `.tga`, `.ppm`, `.pgm`, `.pbm`, `.pnm`, `.xbm`, `.xpm`, `.psd`, `.psb`, `.eps`, `.ai`, `.jp2`, `.j2k`, `.jpt`, `.j2c`, `.jpc`, `.jxl`, `.exr`, `.hdr`, `.fits`, `.fit`, `.fts`, `.svs`, `.ndpi`, `.scn`, `.mrxs`, `.vms`, `.vmu`, `.bif`, `.img`, `.mat` | Sambee converts the file into a browser-ready image before opening it in the image viewer. |\n| PDF | `.pdf` | Open in the PDF viewer with page navigation, search, zoom, and download support. |\n| Markdown | `.md`, `.markdown` | Open in a rendered Markdown view with an optional edit path. |\n| Text and code with syntax highlighting | `.js`, `.mjs`, `.jsx`, `.ts`, `.tsx`, `.py`, `.java`, `.rb`, `.php`, `.go`, `.rs`, `.c`, `.h`, `.cpp`, `.cc`, `.cxx`, `.hpp`, `.cs`, `.html`, `.htm`, `.css`, `.scss`, `.sass`, `.json`, `.xml`, `.yaml`, `.yml`, `.toml`, `.ini`, `.sql`, `.sh`, `.bash`, `.ps1` | Open in the CodeMirror-based source editor with syntax highlighting. |\n| Text and code without syntax highlighting | `.txt`, `.conf`, `.log`, `.env`, `.bat`, `.cmd` | Open in the CodeMirror-based source editor as plain text. |\n\n## Format-Specific Notes\n\nSome converted image formats have specific behavior that is useful to know ahead of time.\n\n- CMYK images are converted to browser-safe sRGB.\n- Multi-page TIFF files open with the first page rather than every page in the source file.\n- PSD and PSB files show the flattened composite view, not interactive layer editing.\n- EPS and AI files are rendered into a high-quality raster image for viewing in the browser.\n- HDR formats such as EXR and Radiance HDR are tone-mapped for ordinary browser display.\n- Whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF open as an overview or first practical level rather than as a full microscopy workstation.\n- FITS and similar scientific-image files use visibility scaling so the content is inspectable in the browser.\n\n## When a File Type Is Not Supported or You Need the Original\n\nIf a file type is not supported by Sambee's viewers, or if you need the original editing experience, use one of the following:\n\n- Download the file.\n- Open it in a desktop app through Companion.\n\nFor the broader workflow explanation, see [View Images \u0026 Read Documents](../../viewing-and-editing-files/view-images-and-read-documents/).\n", "0.9": "+++\ntitle = \"Supported File Formats\"\n+++\n\nThis page lists the file types Sambee can open in its viewers in the browser.\n\n## Overview\n\n| Category | Extensions | What to expect |\n|---|---|---|\n| Common browser image formats | `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`, `.svg`, `.avif` | Open in the image viewer with zoom, pan, and related controls. |\n| Converted image formats | `.tif`, `.tiff`, `.heic`, `.heif`, `.bmp`, `.dib`, `.ico`, `.cur`, `.pcx`, `.tga`, `.ppm`, `.pgm`, `.pbm`, `.pnm`, `.xbm`, `.xpm`, `.psd`, `.psb`, `.eps`, `.ai`, `.jp2`, `.j2k`, `.jpt`, `.j2c`, `.jpc`, `.jxl`, `.exr`, `.hdr`, `.fits`, `.fit`, `.fts`, `.svs`, `.ndpi`, `.scn`, `.mrxs`, `.vms`, `.vmu`, `.bif`, `.img`, `.mat` | Sambee converts the file into a browser-ready image before opening it in the image viewer. |\n| PDF | `.pdf` | Open in the PDF viewer with page navigation, search, zoom, and download support. |\n| Markdown | `.md`, `.markdown` | Open in a rendered Markdown view with an optional edit path. |\n| Text and code with syntax highlighting | `.js`, `.mjs`, `.jsx`, `.ts`, `.tsx`, `.py`, `.java`, `.rb`, `.php`, `.go`, `.rs`, `.c`, `.h`, `.cpp`, `.cc`, `.cxx`, `.hpp`, `.cs`, `.html`, `.htm`, `.css`, `.scss`, `.sass`, `.json`, `.xml`, `.yaml`, `.yml`, `.toml`, `.ini`, `.sql`, `.sh`, `.bash`, `.ps1` | Open in the CodeMirror-based source editor with syntax highlighting. |\n| Text and code without syntax highlighting | `.txt`, `.conf`, `.log`, `.env`, `.bat`, `.cmd` | Open in the CodeMirror-based source editor as plain text. |\n\n## Format-Specific Notes\n\nSome converted image formats have specific behavior that is useful to know ahead of time.\n\n- CMYK images are converted to browser-safe sRGB.\n- Multi-page TIFF files open with the first page rather than every page in the source file.\n- PSD and PSB files show the flattened composite view, not interactive layer editing.\n- EPS and AI files are rendered into a high-quality raster image for viewing in the browser.\n- HDR formats such as EXR and Radiance HDR are tone-mapped for ordinary browser display.\n- Whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF open as an overview or first practical level rather than as a full microscopy workstation.\n- FITS and similar scientific-image files use visibility scaling so the content is inspectable in the browser.\n\n## When a File Type Is Not Supported or You Need the Original\n\nIf a file type is not supported by Sambee's viewers, or if you need the original editing experience, use one of the following:\n\n- Download the file.\n- Open it in a desktop app through Companion.\n\nFor the broader workflow explanation, see [View Images \u0026 Read Documents](../../viewing-and-editing-files/view-images-and-read-documents/).\n", "1.0": "+++\ntitle = \"Supported File Formats\"\n+++\n\nThis page lists the file types Sambee can process, open or edit in its browser-based UI.\n\n## Viewers and Editors\n\n| Category | Extensions | What to expect |\n|---|---|---|\n| Common browser image formats | `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`, `.svg`, `.avif` | Open in the image viewer with zoom, pan, and related controls. |\n| Converted image formats | `.tif`, `.tiff`, `.heic`, `.heif`, `.bmp`, `.dib`, `.ico`, `.cur`, `.pcx`, `.tga`, `.ppm`, `.pgm`, `.pbm`, `.pnm`, `.xbm`, `.xpm`, `.psd`, `.psb`, `.eps`, `.ai`, `.jp2`, `.j2k`, `.jpt`, `.j2c`, `.jpc`, `.jxl`, `.exr`, `.hdr`, `.fits`, `.fit`, `.fts`, `.svs`, `.ndpi`, `.scn`, `.mrxs`, `.vms`, `.vmu`, `.bif`, `.img`, `.mat` | Sambee converts the file into a browser-ready image before opening it in the image viewer. |\n| PDF | `.pdf` | Open in the PDF viewer with page navigation, search, zoom, and download support. |\n| Markdown | `.md`, `.markdown` | Open in a rendered Markdown view with an optional edit path. |\n| Text and code with syntax highlighting | `.js`, `.mjs`, `.jsx`, `.ts`, `.tsx`, `.py`, `.java`, `.rb`, `.php`, `.go`, `.rs`, `.c`, `.h`, `.cpp`, `.cc`, `.cxx`, `.hpp`, `.cs`, `.html`, `.htm`, `.css`, `.scss`, `.sass`, `.json`, `.xml`, `.yaml`, `.yml`, `.toml`, `.ini`, `.sql`, `.sh`, `.bash`, `.ps1` | Open in the CodeMirror-based source editor with syntax highlighting. |\n| Text and code without syntax highlighting | `.txt`, `.conf`, `.log`, `.env`, `.bat`, `.cmd` | Open in the CodeMirror-based source editor as plain text. |\n\n### Format-Specific Notes\n\nSome converted image formats have specific behavior that is useful to know ahead of time.\n\n- CMYK images are converted to browser-safe sRGB.\n- Multi-page TIFF files open with the first page rather than every page in the source file.\n- PSD and PSB files show the flattened composite view, not interactive layer editing.\n- EPS and AI files are rendered into a high-quality raster image for viewing in the browser.\n- HDR formats such as EXR and Radiance HDR are tone-mapped for ordinary browser display.\n- Whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF open as an overview or first practical level rather than as a full microscopy workstation.\n- FITS and similar scientific-image files use visibility scaling so the content is inspectable in the browser.\n\n## Archive Formats\n\nSambee can browse and extract `.zip` archives.\n\n| Archive format | Supported compression methods | Notes |\n|---|---|---|\n| ZIP | Stored, Deflate, BZIP2 | ZIP64 archives are supported. Entries that use other compression methods can't be opened or extracted. |\n\n## When a File Type Is Not Supported or You Need the Original\n\nIf a file type is not supported by Sambee's viewers, or if you need the original editing experience, use one of the following:\n\n- Download the file.\n- Open it in a desktop app through Companion.\n\nFor the broader workflow explanation, see [View Images \u0026 Read Documents](../../viewing-and-editing-files/view-images-and-read-documents/).\n", "2.0": "+++\ntitle = \"Supported File Formats\"\n+++\n\nThis page lists the file types Sambee can process, open or edit in its browser-based UI.\n\n## Viewers and Editors\n\n| Category | Extensions | What to expect |\n|---|---|---|\n| Common browser image formats | `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`, `.svg`, `.avif` | Open in the image viewer with zoom, pan, and related controls. |\n| Converted image formats | `.tif`, `.tiff`, `.heic`, `.heif`, `.bmp`, `.dib`, `.ico`, `.cur`, `.pcx`, `.tga`, `.ppm`, `.pgm`, `.pbm`, `.pnm`, `.xbm`, `.xpm`, `.psd`, `.psb`, `.eps`, `.ai`, `.jp2`, `.j2k`, `.jpt`, `.j2c`, `.jpc`, `.jxl`, `.exr`, `.hdr`, `.fits`, `.fit`, `.fts`, `.svs`, `.ndpi`, `.scn`, `.mrxs`, `.vms`, `.vmu`, `.bif`, `.img`, `.mat` | Sambee converts the file into a browser-ready image before opening it in the image viewer. |\n| PDF | `.pdf` | Open in the PDF viewer with page navigation, search, zoom, and download support. |\n| Markdown | `.md`, `.markdown` | Open in a rendered Markdown view with an optional edit path. |\n| Text and code with syntax highlighting | `.js`, `.mjs`, `.jsx`, `.ts`, `.tsx`, `.py`, `.java`, `.rb`, `.php`, `.go`, `.rs`, `.c`, `.h`, `.cpp`, `.cc`, `.cxx`, `.hpp`, `.cs`, `.html`, `.htm`, `.css`, `.scss`, `.sass`, `.json`, `.xml`, `.yaml`, `.yml`, `.toml`, `.ini`, `.sql`, `.sh`, `.bash`, `.ps1` | Open in the CodeMirror-based source editor with syntax highlighting. |\n| Text and code without syntax highlighting | `.txt`, `.conf`, `.log`, `.env`, `.bat`, `.cmd` | Open in the CodeMirror-based source editor as plain text. |\n\n### Format-Specific Notes\n\nSome converted image formats have specific behavior that is useful to know ahead of time.\n\n- CMYK images are converted to browser-safe sRGB.\n- Multi-page TIFF files open with the first page rather than every page in the source file.\n- PSD and PSB files show the flattened composite view, not interactive layer editing.\n- EPS and AI files are rendered into a high-quality raster image for viewing in the browser.\n- HDR formats such as EXR and Radiance HDR are tone-mapped for ordinary browser display.\n- Whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF open as an overview or first practical level rather than as a full microscopy workstation.\n- FITS and similar scientific-image files use visibility scaling so the content is inspectable in the browser.\n\n## Archive Formats\n\nSambee can browse and extract `.zip` archives.\n\n| Archive format | Supported compression methods | Notes |\n|---|---|---|\n| ZIP | Stored, Deflate, BZIP2 | ZIP64 archives are supported. Entries that use other compression methods can't be opened or extracted. |\n\n## When a File Type Is Not Supported or You Need the Original\n\nIf a file type is not supported by Sambee's viewers, or if you need the original editing experience, use one of the following:\n\n- Download the file.\n- Open it in a desktop app through Companion.\n\nFor the broader workflow explanation, see [View Images \u0026 Read Documents](../../viewing-and-editing-files/view-images-and-read-documents/).\n"}, "page_contents": {"0.7": "+++\ntitle = \"Supported File Formats\"\n+++\n\nThis page lists the file types Sambee can open in its viewers in the browser.\n\n## Overview\n\n| Category | Extensions | What to expect |\n|---|---|---|\n| Common browser image formats | `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`, `.svg`, `.avif` | Open in the image viewer with zoom, pan, and related controls. |\n| Converted image formats | `.tif`, `.tiff`, `.heic`, `.heif`, `.bmp`, `.dib`, `.ico`, `.cur`, `.pcx`, `.tga`, `.ppm`, `.pgm`, `.pbm`, `.pnm`, `.xbm`, `.xpm`, `.psd`, `.psb`, `.eps`, `.ai`, `.jp2`, `.j2k`, `.jpt`, `.j2c`, `.jpc`, `.jxl`, `.exr`, `.hdr`, `.fits`, `.fit`, `.fts`, `.svs`, `.ndpi`, `.scn`, `.mrxs`, `.vms`, `.vmu`, `.bif`, `.img`, `.mat` | Sambee converts the file into a browser-ready image before opening it in the image viewer. |\n| PDF | `.pdf` | Open in the PDF viewer with page navigation, search, zoom, and download support. |\n| Markdown | `.md`, `.markdown` | Open in a rendered Markdown view with an optional edit path. |\n\n## Format-Specific Notes\n\nSome converted image formats have specific behavior that is useful to know ahead of time.\n\n- CMYK images are converted to browser-safe sRGB.\n- Multi-page TIFF files open with the first page rather than every page in the source file.\n- PSD and PSB files show the flattened composite view, not interactive layer editing.\n- EPS and AI files are rendered into a high-quality raster image for viewing in the browser.\n- HDR formats such as EXR and Radiance HDR are tone-mapped for ordinary browser display.\n- Whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF open as an overview or first practical level rather than as a full microscopy workstation.\n- FITS and similar scientific-image files use visibility scaling so the content is inspectable in the browser.\n\n## When a File Type Is Not Supported or You Need the Original\n\nIf a file type is not supported by Sambee's viewers, or if you need the original editing experience, use one of the following:\n\n- Download the file.\n- Open it in a desktop app through Companion.\n\nFor the broader workflow explanation, see [View Images \u0026 Read Documents](../../viewing-and-editing-files/view-images-and-read-documents/).\n", "0.8": "+++\ntitle = \"Supported File Formats\"\n+++\n\nThis page lists the file types Sambee can open in its viewers in the browser.\n\n## Overview\n\n| Category | Extensions | What to expect |\n|---|---|---|\n| Common browser image formats | `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`, `.svg`, `.avif` | Open in the image viewer with zoom, pan, and related controls. |\n| Converted image formats | `.tif`, `.tiff`, `.heic`, `.heif`, `.bmp`, `.dib`, `.ico`, `.cur`, `.pcx`, `.tga`, `.ppm`, `.pgm`, `.pbm`, `.pnm`, `.xbm`, `.xpm`, `.psd`, `.psb`, `.eps`, `.ai`, `.jp2`, `.j2k`, `.jpt`, `.j2c`, `.jpc`, `.jxl`, `.exr`, `.hdr`, `.fits`, `.fit`, `.fts`, `.svs`, `.ndpi`, `.scn`, `.mrxs`, `.vms`, `.vmu`, `.bif`, `.img`, `.mat` | Sambee converts the file into a browser-ready image before opening it in the image viewer. |\n| PDF | `.pdf` | Open in the PDF viewer with page navigation, search, zoom, and download support. |\n| Markdown | `.md`, `.markdown` | Open in a rendered Markdown view with an optional edit path. |\n| Text and code with syntax highlighting | `.js`, `.mjs`, `.jsx`, `.ts`, `.tsx`, `.py`, `.java`, `.rb`, `.php`, `.go`, `.rs`, `.c`, `.h`, `.cpp`, `.cc`, `.cxx`, `.hpp`, `.cs`, `.html`, `.htm`, `.css`, `.scss`, `.sass`, `.json`, `.xml`, `.yaml`, `.yml`, `.toml`, `.ini`, `.sql`, `.sh`, `.bash`, `.ps1` | Open in the CodeMirror-based source editor with syntax highlighting. |\n| Text and code without syntax highlighting | `.txt`, `.conf`, `.log`, `.env`, `.bat`, `.cmd` | Open in the CodeMirror-based source editor as plain text. |\n\n## Format-Specific Notes\n\nSome converted image formats have specific behavior that is useful to know ahead of time.\n\n- CMYK images are converted to browser-safe sRGB.\n- Multi-page TIFF files open with the first page rather than every page in the source file.\n- PSD and PSB files show the flattened composite view, not interactive layer editing.\n- EPS and AI files are rendered into a high-quality raster image for viewing in the browser.\n- HDR formats such as EXR and Radiance HDR are tone-mapped for ordinary browser display.\n- Whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF open as an overview or first practical level rather than as a full microscopy workstation.\n- FITS and similar scientific-image files use visibility scaling so the content is inspectable in the browser.\n\n## When a File Type Is Not Supported or You Need the Original\n\nIf a file type is not supported by Sambee's viewers, or if you need the original editing experience, use one of the following:\n\n- Download the file.\n- Open it in a desktop app through Companion.\n\nFor the broader workflow explanation, see [View Images \u0026 Read Documents](../../viewing-and-editing-files/view-images-and-read-documents/).\n", "0.9": "+++\ntitle = \"Supported File Formats\"\n+++\n\nThis page lists the file types Sambee can open in its viewers in the browser.\n\n## Overview\n\n| Category | Extensions | What to expect |\n|---|---|---|\n| Common browser image formats | `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`, `.svg`, `.avif` | Open in the image viewer with zoom, pan, and related controls. |\n| Converted image formats | `.tif`, `.tiff`, `.heic`, `.heif`, `.bmp`, `.dib`, `.ico`, `.cur`, `.pcx`, `.tga`, `.ppm`, `.pgm`, `.pbm`, `.pnm`, `.xbm`, `.xpm`, `.psd`, `.psb`, `.eps`, `.ai`, `.jp2`, `.j2k`, `.jpt`, `.j2c`, `.jpc`, `.jxl`, `.exr`, `.hdr`, `.fits`, `.fit`, `.fts`, `.svs`, `.ndpi`, `.scn`, `.mrxs`, `.vms`, `.vmu`, `.bif`, `.img`, `.mat` | Sambee converts the file into a browser-ready image before opening it in the image viewer. |\n| PDF | `.pdf` | Open in the PDF viewer with page navigation, search, zoom, and download support. |\n| Markdown | `.md`, `.markdown` | Open in a rendered Markdown view with an optional edit path. |\n| Text and code with syntax highlighting | `.js`, `.mjs`, `.jsx`, `.ts`, `.tsx`, `.py`, `.java`, `.rb`, `.php`, `.go`, `.rs`, `.c`, `.h`, `.cpp`, `.cc`, `.cxx`, `.hpp`, `.cs`, `.html`, `.htm`, `.css`, `.scss`, `.sass`, `.json`, `.xml`, `.yaml`, `.yml`, `.toml`, `.ini`, `.sql`, `.sh`, `.bash`, `.ps1` | Open in the CodeMirror-based source editor with syntax highlighting. |\n| Text and code without syntax highlighting | `.txt`, `.conf`, `.log`, `.env`, `.bat`, `.cmd` | Open in the CodeMirror-based source editor as plain text. |\n\n## Format-Specific Notes\n\nSome converted image formats have specific behavior that is useful to know ahead of time.\n\n- CMYK images are converted to browser-safe sRGB.\n- Multi-page TIFF files open with the first page rather than every page in the source file.\n- PSD and PSB files show the flattened composite view, not interactive layer editing.\n- EPS and AI files are rendered into a high-quality raster image for viewing in the browser.\n- HDR formats such as EXR and Radiance HDR are tone-mapped for ordinary browser display.\n- Whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF open as an overview or first practical level rather than as a full microscopy workstation.\n- FITS and similar scientific-image files use visibility scaling so the content is inspectable in the browser.\n\n## When a File Type Is Not Supported or You Need the Original\n\nIf a file type is not supported by Sambee's viewers, or if you need the original editing experience, use one of the following:\n\n- Download the file.\n- Open it in a desktop app through Companion.\n\nFor the broader workflow explanation, see [View Images \u0026 Read Documents](../../viewing-and-editing-files/view-images-and-read-documents/).\n", "1.0": "+++\ntitle = \"Supported File Formats\"\n+++\n\nThis page lists the file types Sambee can process, open or edit in its browser-based UI.\n\n## Viewers and Editors\n\n| Category | Extensions | What to expect |\n|---|---|---|\n| Common browser image formats | `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`, `.svg`, `.avif` | Open in the image viewer with zoom, pan, and related controls. |\n| Converted image formats | `.tif`, `.tiff`, `.heic`, `.heif`, `.bmp`, `.dib`, `.ico`, `.cur`, `.pcx`, `.tga`, `.ppm`, `.pgm`, `.pbm`, `.pnm`, `.xbm`, `.xpm`, `.psd`, `.psb`, `.eps`, `.ai`, `.jp2`, `.j2k`, `.jpt`, `.j2c`, `.jpc`, `.jxl`, `.exr`, `.hdr`, `.fits`, `.fit`, `.fts`, `.svs`, `.ndpi`, `.scn`, `.mrxs`, `.vms`, `.vmu`, `.bif`, `.img`, `.mat` | Sambee converts the file into a browser-ready image before opening it in the image viewer. |\n| PDF | `.pdf` | Open in the PDF viewer with page navigation, search, zoom, and download support. |\n| Markdown | `.md`, `.markdown` | Open in a rendered Markdown view with an optional edit path. |\n| Text and code with syntax highlighting | `.js`, `.mjs`, `.jsx`, `.ts`, `.tsx`, `.py`, `.java`, `.rb`, `.php`, `.go`, `.rs`, `.c`, `.h`, `.cpp`, `.cc`, `.cxx`, `.hpp`, `.cs`, `.html`, `.htm`, `.css`, `.scss`, `.sass`, `.json`, `.xml`, `.yaml`, `.yml`, `.toml`, `.ini`, `.sql`, `.sh`, `.bash`, `.ps1` | Open in the CodeMirror-based source editor with syntax highlighting. |\n| Text and code without syntax highlighting | `.txt`, `.conf`, `.log`, `.env`, `.bat`, `.cmd` | Open in the CodeMirror-based source editor as plain text. |\n\n### Format-Specific Notes\n\nSome converted image formats have specific behavior that is useful to know ahead of time.\n\n- CMYK images are converted to browser-safe sRGB.\n- Multi-page TIFF files open with the first page rather than every page in the source file.\n- PSD and PSB files show the flattened composite view, not interactive layer editing.\n- EPS and AI files are rendered into a high-quality raster image for viewing in the browser.\n- HDR formats such as EXR and Radiance HDR are tone-mapped for ordinary browser display.\n- Whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF open as an overview or first practical level rather than as a full microscopy workstation.\n- FITS and similar scientific-image files use visibility scaling so the content is inspectable in the browser.\n\n## Archive Formats\n\nSambee can browse and extract `.zip` archives.\n\n| Archive format | Supported compression methods | Notes |\n|---|---|---|\n| ZIP | Stored, Deflate, BZIP2 | ZIP64 archives are supported. Entries that use other compression methods can't be opened or extracted. |\n\n## When a File Type Is Not Supported or You Need the Original\n\nIf a file type is not supported by Sambee's viewers, or if you need the original editing experience, use one of the following:\n\n- Download the file.\n- Open it in a desktop app through Companion.\n\nFor the broader workflow explanation, see [View Images \u0026 Read Documents](../../viewing-and-editing-files/view-images-and-read-documents/).\n", "2.0": "+++\ntitle = \"Supported File Formats\"\n+++\n\nThis page lists the file types Sambee can process, open or edit in its browser-based UI.\n\n## Viewers and Editors\n\n| Category | Extensions | What to expect |\n|---|---|---|\n| Common browser image formats | `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`, `.svg`, `.avif` | Open in the image viewer with zoom, pan, and related controls. |\n| Converted image formats | `.tif`, `.tiff`, `.heic`, `.heif`, `.bmp`, `.dib`, `.ico`, `.cur`, `.pcx`, `.tga`, `.ppm`, `.pgm`, `.pbm`, `.pnm`, `.xbm`, `.xpm`, `.psd`, `.psb`, `.eps`, `.ai`, `.jp2`, `.j2k`, `.jpt`, `.j2c`, `.jpc`, `.jxl`, `.exr`, `.hdr`, `.fits`, `.fit`, `.fts`, `.svs`, `.ndpi`, `.scn`, `.mrxs`, `.vms`, `.vmu`, `.bif`, `.img`, `.mat` | Sambee converts the file into a browser-ready image before opening it in the image viewer. |\n| PDF | `.pdf` | Open in the PDF viewer with page navigation, search, zoom, and download support. |\n| Markdown | `.md`, `.markdown` | Open in a rendered Markdown view with an optional edit path. |\n| Text and code with syntax highlighting | `.js`, `.mjs`, `.jsx`, `.ts`, `.tsx`, `.py`, `.java`, `.rb`, `.php`, `.go`, `.rs`, `.c`, `.h`, `.cpp`, `.cc`, `.cxx`, `.hpp`, `.cs`, `.html`, `.htm`, `.css`, `.scss`, `.sass`, `.json`, `.xml`, `.yaml`, `.yml`, `.toml`, `.ini`, `.sql`, `.sh`, `.bash`, `.ps1` | Open in the CodeMirror-based source editor with syntax highlighting. |\n| Text and code without syntax highlighting | `.txt`, `.conf`, `.log`, `.env`, `.bat`, `.cmd` | Open in the CodeMirror-based source editor as plain text. |\n\n### Format-Specific Notes\n\nSome converted image formats have specific behavior that is useful to know ahead of time.\n\n- CMYK images are converted to browser-safe sRGB.\n- Multi-page TIFF files open with the first page rather than every page in the source file.\n- PSD and PSB files show the flattened composite view, not interactive layer editing.\n- EPS and AI files are rendered into a high-quality raster image for viewing in the browser.\n- HDR formats such as EXR and Radiance HDR are tone-mapped for ordinary browser display.\n- Whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF open as an overview or first practical level rather than as a full microscopy workstation.\n- FITS and similar scientific-image files use visibility scaling so the content is inspectable in the browser.\n\n## Archive Formats\n\nSambee can browse and extract `.zip` archives.\n\n| Archive format | Supported compression methods | Notes |\n|---|---|---|\n| ZIP | Stored, Deflate, BZIP2 | ZIP64 archives are supported. Entries that use other compression methods can't be opened or extracted. |\n\n## When a File Type Is Not Supported or You Need the Original\n\nIf a file type is not supported by Sambee's viewers, or if you need the original editing experience, use one of the following:\n\n- Download the file.\n- Open it in a desktop app through Companion.\n\nFor the broader workflow explanation, see [View Images \u0026 Read Documents](../../viewing-and-editing-files/view-images-and-read-documents/).\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "book:admin-guide", "parent_id": null, "depth": 0, "kind": "book", "label": "admin-guide", "title": "Admin Guide", "path": "admin-guide", "has_children": true, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "branched", "source_version": "0.7", "diff_added": 1, "diff_removed": 1}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "inherited", "source_version": "0.9"}}, "content_versions": {"0.7": "+++\ntitle = \"Admin Guide\"\n+++\n\nUse this guide to plan and deploy a Sambee service, configure storage, networking, and persistence, maintain it, and recover the deployment.\n\n## Start Here if You Want To\n\n- Understand what Sambee needs in order to run.\n- Deploy Sambee with Docker and persistent storage.\n- Place Sambee behind a reverse proxy for HTTPS or hostname-based access.\n- Handle routine operations such as logs, restarts, upgrades, and backups.\n\n## In This Guide\n\n- [Architecture Overview](./overview-and-planning/architecture-overview/): Understand how Sambee fits into your environment and what the deployment model looks like.\n- [Installation and Deployment](./installation-and-deployment/deploy-sambee-with-docker/): Follow the shortest path to a working deployment and first admin sign-in.\n- [Network and Reverse Proxy](./network-and-reverse-proxy/put-sambee-behind-a-reverse-proxy/): Configure HTTPS, hostnames, and reverse-proxy setup.\n- [Configuration](./configuration/configuration-key-reference/): Review the config keys admins most often change and follow the related path and persistence references.\n- [Operations and Maintenance](./operations-and-maintenance/view-logs-and-restart-services/): Handle logs, restarts, routine checks, upgrades, and backups.\n- [Reference](./reference/port-and-path-reference/): Check ports, paths, and companion-support lookup material.\n\n## Use the Right Guide\n\n- Use this Admin Guide for deployment, configuration, operations, and service recovery work.\n- Use the [User Guide](../user-guide/) when the next step belongs to the person using Sambee day to day.\n- Use the [Developer Guide](../developer-guide/) when the question becomes implementation-facing.\n\n", "0.8": "+++\ntitle = \"Admin Guide\"\n+++\n\nUse this guide to plan and deploy a Sambee service, configure storage, networking, and persistence, maintain it, and recover the deployment.\n\n## Start Here if You Want To\n\n- Understand what Sambee needs in order to run.\n- Deploy Sambee with Docker and persistent storage.\n- Place Sambee behind a reverse proxy for HTTPS or hostname-based access.\n- Handle routine operations such as logs, restarts, upgrades, and backups.\n\n## In This Guide\n\n- [Architecture Overview](./overview-and-planning/architecture-overview/): Understand how Sambee fits into your environment and what the deployment model looks like.\n- [Installation and Deployment](./installation-and-deployment/deploy-sambee-with-docker/): Follow the shortest path to a working deployment and first admin sign-in.\n- [Network and Reverse Proxy](./network-and-reverse-proxy/put-sambee-behind-a-reverse-proxy/): Configure HTTPS, hostnames, and reverse-proxy setup.\n- [Configuration](./configuration/configuration-key-reference/): Review the config keys admins most often change and follow the related path and persistence references.\n- [Operations and Maintenance](./operations-and-maintenance/view-logs-and-restart-services/): Handle logs, restarts, routine checks, upgrades, and backups.\n- [Reference](./reference/port-and-path-reference/): Check ports, paths, and companion-support lookup material.\n\n## Use the Right Guide\n\n- Use this Admin Guide for deployment, configuration, operations, and service recovery work.\n- Use the [User Guide](../user-guide/) when the next step belongs to the person using Sambee day to day.\n- Use the [Developer Guide](../developer-guide/) when the question becomes implementation-facing.\n\n", "0.9": "+++\ntitle = \"Admin Guide\"\n+++\n\nUse this guide to plan and deploy a Sambee service, configure storage, networking, and persistence, maintain it, and recover the deployment.\n\n## Start Here if You Want To\n\n- Understand what Sambee needs in order to run.\n- Deploy Sambee with Docker and persistent storage.\n- Place Sambee behind a reverse proxy for HTTPS or hostname-based access.\n- Handle routine operations such as logs, restarts, upgrades, and backups.\n\n## In This Guide\n\n- [Architecture Overview](./overview-and-planning/architecture-overview/): Understand how Sambee fits into your environment and what the deployment model looks like.\n- [Installation and Deployment](./installation-and-deployment/deploy-sambee-with-docker/): Follow the shortest path to a working deployment and first admin sign-in.\n- [Network and Reverse Proxy](./network-and-reverse-proxy/put-sambee-behind-a-reverse-proxy/): Configure HTTPS, hostnames, and reverse-proxy setup.\n- [Authentication](./authentication/authentication-overview/): Choose and operate local-password, OpenID Connect, or perimeter-trust access.\n- [Operations and Maintenance](./operations-and-maintenance/view-logs-and-restart-services/): Handle logs, restarts, routine checks, upgrades, and backups.\n- [Reference](./reference/port-and-path-reference/): Check ports, paths, and companion-support lookup material.\n\n## Use the Right Guide\n\n- Use this Admin Guide for deployment, configuration, operations, and service recovery work.\n- Use the [User Guide](../user-guide/) when the next step belongs to the person using Sambee day to day.\n- Use the [Developer Guide](../developer-guide/) when the question becomes implementation-facing.\n\n", "1.0": "+++\ntitle = \"Admin Guide\"\n+++\n\nUse this guide to plan and deploy a Sambee service, configure storage, networking, and persistence, maintain it, and recover the deployment.\n\n## Start Here if You Want To\n\n- Understand what Sambee needs in order to run.\n- Deploy Sambee with Docker and persistent storage.\n- Place Sambee behind a reverse proxy for HTTPS or hostname-based access.\n- Handle routine operations such as logs, restarts, upgrades, and backups.\n\n## In This Guide\n\n- [Architecture Overview](./overview-and-planning/architecture-overview/): Understand how Sambee fits into your environment and what the deployment model looks like.\n- [Installation and Deployment](./installation-and-deployment/deploy-sambee-with-docker/): Follow the shortest path to a working deployment and first admin sign-in.\n- [Network and Reverse Proxy](./network-and-reverse-proxy/put-sambee-behind-a-reverse-proxy/): Configure HTTPS, hostnames, and reverse-proxy setup.\n- [Authentication](./authentication/authentication-overview/): Choose and operate local-password, OpenID Connect, or perimeter-trust access.\n- [Operations and Maintenance](./operations-and-maintenance/view-logs-and-restart-services/): Handle logs, restarts, routine checks, upgrades, and backups.\n- [Reference](./reference/port-and-path-reference/): Check ports, paths, and companion-support lookup material.\n\n## Use the Right Guide\n\n- Use this Admin Guide for deployment, configuration, operations, and service recovery work.\n- Use the [User Guide](../user-guide/) when the next step belongs to the person using Sambee day to day.\n- Use the [Developer Guide](../developer-guide/) when the question becomes implementation-facing.\n\n", "2.0": "+++\ntitle = \"Admin Guide\"\n+++\n\nUse this guide to plan and deploy a Sambee service, configure storage, networking, and persistence, maintain it, and recover the deployment.\n\n## Start Here if You Want To\n\n- Understand what Sambee needs in order to run.\n- Deploy Sambee with Docker and persistent storage.\n- Place Sambee behind a reverse proxy for HTTPS or hostname-based access.\n- Handle routine operations such as logs, restarts, upgrades, and backups.\n\n## In This Guide\n\n- [Architecture Overview](./overview-and-planning/architecture-overview/): Understand how Sambee fits into your environment and what the deployment model looks like.\n- [Installation and Deployment](./installation-and-deployment/deploy-sambee-with-docker/): Follow the shortest path to a working deployment and first admin sign-in.\n- [Network and Reverse Proxy](./network-and-reverse-proxy/put-sambee-behind-a-reverse-proxy/): Configure HTTPS, hostnames, and reverse-proxy setup.\n- [Authentication](./authentication/authentication-overview/): Choose and operate local-password, OpenID Connect, or perimeter-trust access.\n- [Operations and Maintenance](./operations-and-maintenance/view-logs-and-restart-services/): Handle logs, restarts, routine checks, upgrades, and backups.\n- [Reference](./reference/port-and-path-reference/): Check ports, paths, and companion-support lookup material.\n\n## Use the Right Guide\n\n- Use this Admin Guide for deployment, configuration, operations, and service recovery work.\n- Use the [User Guide](../user-guide/) when the next step belongs to the person using Sambee day to day.\n- Use the [Developer Guide](../developer-guide/) when the question becomes implementation-facing.\n\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:admin-guide/overview-and-planning", "parent_id": "book:admin-guide", "depth": 1, "kind": "section", "label": "overview-and-planning", "title": "Overview and Planning", "path": "admin-guide/overview-and-planning", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:admin-guide/overview-and-planning/architecture-overview", "parent_id": "section:admin-guide/overview-and-planning", "depth": 2, "kind": "page", "label": "architecture-overview", "title": "Architecture Overview", "path": "admin-guide/overview-and-planning/architecture-overview", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Architecture Overview\"\n+++\n\nSambee has a deliberately simple architecture: a single container contains everything that is needed, plus - optionally - a reverse proxy.\n\n## Single Docker Container\n\nAt the center of a Sambee deployment is:\n\n- A container running the Sambee backend and serving the frontend via HTTP.\n- A local data directory holding the SQLite database and other persistent application state.\n- Network connectivity from the Sambee backend to the SMB shares you want to access through Sambee.\n\nBrowsers connect to Sambee either directly or through a reverse proxy.\n\n## What Is Required and What Is Optional\n\n| Component or concern | Required | Notes |\n|---|---|---|\n| Sambee application container | Yes | This is the web application users open in their browsers. |\n| Local persistent data directory | Yes | Stores the SQLite database and other data Sambee must keep across restarts. |\n| SMB connectivity | Yes | Sambee must be able to reach the SMB storage it presents to users. |\n| Reverse proxy | No | Add one when you need HTTPS, hostname routing, or controlled external access. |\n| Companion app on user desktops | No | Needed only for local-drive access and desktop-app editing workflows.\n", "0.8": "+++\ntitle = \"Architecture Overview\"\n+++\n\nSambee has a deliberately simple architecture: a single container contains everything that is needed, plus - optionally - a reverse proxy.\n\n## Single Docker Container\n\nAt the center of a Sambee deployment is:\n\n- A container running the Sambee backend and serving the frontend via HTTP.\n- A local data directory holding the SQLite database and other persistent application state.\n- Network connectivity from the Sambee backend to the SMB shares you want to access through Sambee.\n\nBrowsers connect to Sambee either directly or through a reverse proxy.\n\n## What Is Required and What Is Optional\n\n| Component or concern | Required | Notes |\n|---|---|---|\n| Sambee application container | Yes | This is the web application users open in their browsers. |\n| Local persistent data directory | Yes | Stores the SQLite database and other data Sambee must keep across restarts. |\n| SMB connectivity | Yes | Sambee must be able to reach the SMB storage it presents to users. |\n| Reverse proxy | No | Add one when you need HTTPS, hostname routing, or controlled external access. |\n| Companion app on user desktops | No | Needed only for local-drive access and desktop-app editing workflows.\n", "0.9": "+++\ntitle = \"Architecture Overview\"\n+++\n\nSambee has a deliberately simple architecture: a single container contains everything that is needed, plus - optionally - a reverse proxy.\n\n## Single Docker Container\n\nAt the center of a Sambee deployment is:\n\n- A container running the Sambee backend and serving the frontend via HTTP.\n- A local data directory holding the SQLite database and other persistent application state.\n- Network connectivity from the Sambee backend to the SMB shares you want to access through Sambee.\n\nBrowsers connect to Sambee either directly or through a reverse proxy.\n\n## What Is Required and What Is Optional\n\n| Component or concern | Required | Notes |\n|---|---|---|\n| Sambee application container | Yes | This is the web application users open in their browsers. |\n| Local persistent data directory | Yes | Stores the SQLite database and other data Sambee must keep across restarts. |\n| SMB connectivity | Yes | Sambee must be able to reach the SMB storage it presents to users. |\n| Reverse proxy | No | Add one when you need HTTPS, hostname routing, or controlled external access. |\n| Companion app on user desktops | No | Needed only for local-drive access and desktop-app editing workflows.\n", "1.0": "+++\ntitle = \"Architecture Overview\"\n+++\n\nSambee has a deliberately simple architecture: a single container contains everything that is needed, plus - optionally - a reverse proxy.\n\n## Single Docker Container\n\nAt the center of a Sambee deployment is:\n\n- A container running the Sambee backend and serving the frontend via HTTP.\n- A local data directory holding the SQLite database and other persistent application state.\n- Network connectivity from the Sambee backend to the SMB shares you want to access through Sambee.\n\nBrowsers connect to Sambee either directly or through a reverse proxy.\n\n## What Is Required and What Is Optional\n\n| Component or concern | Required | Notes |\n|---|---|---|\n| Sambee application container | Yes | This is the web application users open in their browsers. |\n| Local persistent data directory | Yes | Stores the SQLite database and other data Sambee must keep across restarts. |\n| SMB connectivity | Yes | Sambee must be able to reach the SMB storage it presents to users. |\n| Reverse proxy | No | Add one when you need HTTPS, hostname routing, or controlled external access. |\n| Companion app on user desktops | No | Needed only for local-drive access and desktop-app editing workflows.\n", "2.0": "+++\ntitle = \"Architecture Overview\"\n+++\n\nSambee has a deliberately simple architecture: a single container contains everything that is needed, plus - optionally - a reverse proxy.\n\n## Single Docker Container\n\nAt the center of a Sambee deployment is:\n\n- A container running the Sambee backend and serving the frontend via HTTP.\n- A local data directory holding the SQLite database and other persistent application state.\n- Network connectivity from the Sambee backend to the SMB shares you want to access through Sambee.\n\nBrowsers connect to Sambee either directly or through a reverse proxy.\n\n## What Is Required and What Is Optional\n\n| Component or concern | Required | Notes |\n|---|---|---|\n| Sambee application container | Yes | This is the web application users open in their browsers. |\n| Local persistent data directory | Yes | Stores the SQLite database and other data Sambee must keep across restarts. |\n| SMB connectivity | Yes | Sambee must be able to reach the SMB storage it presents to users. |\n| Reverse proxy | No | Add one when you need HTTPS, hostname routing, or controlled external access. |\n| Companion app on user desktops | No | Needed only for local-drive access and desktop-app editing workflows.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Architecture Overview\"\n+++\n\nSambee has a deliberately simple architecture: a single container contains everything that is needed, plus - optionally - a reverse proxy.\n\n## Single Docker Container\n\nAt the center of a Sambee deployment is:\n\n- A container running the Sambee backend and serving the frontend via HTTP.\n- A local data directory holding the SQLite database and other persistent application state.\n- Network connectivity from the Sambee backend to the SMB shares you want to access through Sambee.\n\nBrowsers connect to Sambee either directly or through a reverse proxy.\n\n## What Is Required and What Is Optional\n\n| Component or concern | Required | Notes |\n|---|---|---|\n| Sambee application container | Yes | This is the web application users open in their browsers. |\n| Local persistent data directory | Yes | Stores the SQLite database and other data Sambee must keep across restarts. |\n| SMB connectivity | Yes | Sambee must be able to reach the SMB storage it presents to users. |\n| Reverse proxy | No | Add one when you need HTTPS, hostname routing, or controlled external access. |\n| Companion app on user desktops | No | Needed only for local-drive access and desktop-app editing workflows.\n", "0.8": "+++\ntitle = \"Architecture Overview\"\n+++\n\nSambee has a deliberately simple architecture: a single container contains everything that is needed, plus - optionally - a reverse proxy.\n\n## Single Docker Container\n\nAt the center of a Sambee deployment is:\n\n- A container running the Sambee backend and serving the frontend via HTTP.\n- A local data directory holding the SQLite database and other persistent application state.\n- Network connectivity from the Sambee backend to the SMB shares you want to access through Sambee.\n\nBrowsers connect to Sambee either directly or through a reverse proxy.\n\n## What Is Required and What Is Optional\n\n| Component or concern | Required | Notes |\n|---|---|---|\n| Sambee application container | Yes | This is the web application users open in their browsers. |\n| Local persistent data directory | Yes | Stores the SQLite database and other data Sambee must keep across restarts. |\n| SMB connectivity | Yes | Sambee must be able to reach the SMB storage it presents to users. |\n| Reverse proxy | No | Add one when you need HTTPS, hostname routing, or controlled external access. |\n| Companion app on user desktops | No | Needed only for local-drive access and desktop-app editing workflows.\n", "0.9": "+++\ntitle = \"Architecture Overview\"\n+++\n\nSambee has a deliberately simple architecture: a single container contains everything that is needed, plus - optionally - a reverse proxy.\n\n## Single Docker Container\n\nAt the center of a Sambee deployment is:\n\n- A container running the Sambee backend and serving the frontend via HTTP.\n- A local data directory holding the SQLite database and other persistent application state.\n- Network connectivity from the Sambee backend to the SMB shares you want to access through Sambee.\n\nBrowsers connect to Sambee either directly or through a reverse proxy.\n\n## What Is Required and What Is Optional\n\n| Component or concern | Required | Notes |\n|---|---|---|\n| Sambee application container | Yes | This is the web application users open in their browsers. |\n| Local persistent data directory | Yes | Stores the SQLite database and other data Sambee must keep across restarts. |\n| SMB connectivity | Yes | Sambee must be able to reach the SMB storage it presents to users. |\n| Reverse proxy | No | Add one when you need HTTPS, hostname routing, or controlled external access. |\n| Companion app on user desktops | No | Needed only for local-drive access and desktop-app editing workflows.\n", "1.0": "+++\ntitle = \"Architecture Overview\"\n+++\n\nSambee has a deliberately simple architecture: a single container contains everything that is needed, plus - optionally - a reverse proxy.\n\n## Single Docker Container\n\nAt the center of a Sambee deployment is:\n\n- A container running the Sambee backend and serving the frontend via HTTP.\n- A local data directory holding the SQLite database and other persistent application state.\n- Network connectivity from the Sambee backend to the SMB shares you want to access through Sambee.\n\nBrowsers connect to Sambee either directly or through a reverse proxy.\n\n## What Is Required and What Is Optional\n\n| Component or concern | Required | Notes |\n|---|---|---|\n| Sambee application container | Yes | This is the web application users open in their browsers. |\n| Local persistent data directory | Yes | Stores the SQLite database and other data Sambee must keep across restarts. |\n| SMB connectivity | Yes | Sambee must be able to reach the SMB storage it presents to users. |\n| Reverse proxy | No | Add one when you need HTTPS, hostname routing, or controlled external access. |\n| Companion app on user desktops | No | Needed only for local-drive access and desktop-app editing workflows.\n", "2.0": "+++\ntitle = \"Architecture Overview\"\n+++\n\nSambee has a deliberately simple architecture: a single container contains everything that is needed, plus - optionally - a reverse proxy.\n\n## Single Docker Container\n\nAt the center of a Sambee deployment is:\n\n- A container running the Sambee backend and serving the frontend via HTTP.\n- A local data directory holding the SQLite database and other persistent application state.\n- Network connectivity from the Sambee backend to the SMB shares you want to access through Sambee.\n\nBrowsers connect to Sambee either directly or through a reverse proxy.\n\n## What Is Required and What Is Optional\n\n| Component or concern | Required | Notes |\n|---|---|---|\n| Sambee application container | Yes | This is the web application users open in their browsers. |\n| Local persistent data directory | Yes | Stores the SQLite database and other data Sambee must keep across restarts. |\n| SMB connectivity | Yes | Sambee must be able to reach the SMB storage it presents to users. |\n| Reverse proxy | No | Add one when you need HTTPS, hostname routing, or controlled external access. |\n| Companion app on user desktops | No | Needed only for local-drive access and desktop-app editing workflows.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:admin-guide/installation-and-deployment", "parent_id": "book:admin-guide", "depth": 1, "kind": "section", "label": "installation-and-deployment", "title": "Installation and Deployment", "path": "admin-guide/installation-and-deployment", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:admin-guide/installation-and-deployment/deploy-sambee-with-docker", "parent_id": "section:admin-guide/installation-and-deployment", "depth": 2, "kind": "page", "label": "deploy-sambee-with-docker", "title": "Deploy Sambee With Docker", "path": "admin-guide/installation-and-deployment/deploy-sambee-with-docker", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "branched", "source_version": "0.7", "diff_added": 1, "diff_removed": 8}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "branched", "source_version": "0.9", "diff_added": 1, "diff_removed": 1}}, "content_versions": {"0.7": "+++\ntitle = \"Deploy Sambee with Docker\"\n+++\n\n## Before You Start\n\nYou need:\n\n- Docker and `docker compose` installed.\n- A host that can reach the SMB file servers Sambee will use.\n- A deployment directory where you can keep local files such as `docker-compose.yml`, optional `config.toml`, and the persistent `data/` directory.\n\nYou do not need to clone the repository or build Sambee locally for a normal Docker deployment. Sambee publishes ready-to-run container images to GitHub Container Registry.\n\n## 1. Create a Deployment Directory\n\nCreate a dedicated directory for your local deployment files and move into it:\n\n```bash\nmkdir -p sambee\ncd sambee\n```\n\nThis directory will hold your Compose file, optional configuration file, and persistent application data.\n\n## 2. Prepare Persistent Storage\n\nCreate the local data directory and set ownership to user and group ID `1000`, which the containerized application uses:\n\n```bash\nmkdir -p ./data\nchown -Rfv 1000:1000 ./data\n```\n\nThis directory contains the Sambee database and other state that must survive restarts, rebuilds, and host reboots.\n\n## 3. Create the Compose File\n\nCreate `docker-compose.yml` with this content:\n\n```yaml\nservices:\n\tsambee:\n\t\timage: ghcr.io/helgeklein/sambee:stable\n\t\trestart: unless-stopped\n\t\tvolumes:\n\t\t\t- ./data:/app/data\n\t\t\t# Optional: uncomment when you create config.toml locally.\n\t\t\t# - ./config.toml:/app/config.toml:ro\n\t\tports:\n\t\t\t- 8000:8000\n```\n\n#### Select a Release Channel\n\nSambee has three different release channels. You select which to follow via the Docker image tag:\n\n- `stable` for the production channel.\n- `beta` for prerelease builds.\n- `test` for preview builds.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nWhile Sambee is in beta, the `stable` tag may not be available yet.\n{{\u003c /admonition \u003e}}\n\n## 4. Optional: Create a Local Configuration File\n\nYou do not need `config.toml` for a basic deployment. Create it only if you need to override defaults such as authentication, logging, or Companion download settings.\n\nCreate `config.toml` with only the settings you want to change. For example:\n\n```toml\n[app]\nlog_level = \"INFO\"\n\n[security]\nauth_method = \"password\"\n\n[admin]\nusername = \"admin\"\n```\n\nIf you create `config.toml`, uncomment the read-only bind mount in `docker-compose.yml`.\n\nKeep this file local. In production, mount it read-only.\n\n## 5. Pull and Start Sambee\n\nPull the configured image:\n\n```bash\ndocker compose pull\n```\n\nThen start the application:\n\n```bash\ndocker compose up -d\n```\n\nBy default, the service is available at:\n\n- Frontend: `http://localhost:8000`\n- Backend API: `http://localhost:8000/api`\n- API docs: `http://localhost:8000/docs`\n\n## Verify the Deployment\n\nBefore moving on, confirm that the deployment really came up cleanly.\n\n- The `docker compose ps` output shows the `sambee` service running.\n- The frontend URL responds on the expected host port.\n- The startup logs do not show an obvious failure loop.\n\nFor a quick log review:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\nOnce the deployment is healthy, continue with the first login procedure on the next page.\n", "0.8": "+++\ntitle = \"Deploy Sambee with Docker\"\n+++\n\n## Before You Start\n\nYou need:\n\n- Docker and `docker compose` installed.\n- A host that can reach the SMB file servers Sambee will use.\n- A deployment directory where you can keep local files such as `docker-compose.yml`, optional `config.toml`, and the persistent `data/` directory.\n\nYou do not need to clone the repository or build Sambee locally for a normal Docker deployment. Sambee publishes ready-to-run container images to GitHub Container Registry.\n\n## 1. Create a Deployment Directory\n\nCreate a dedicated directory for your local deployment files and move into it:\n\n```bash\nmkdir -p sambee\ncd sambee\n```\n\nThis directory will hold your Compose file, optional configuration file, and persistent application data.\n\n## 2. Prepare Persistent Storage\n\nCreate the local data directory and set ownership to user and group ID `1000`, which the containerized application uses:\n\n```bash\nmkdir -p ./data\nchown -Rfv 1000:1000 ./data\n```\n\nThis directory contains the Sambee database and other state that must survive restarts, rebuilds, and host reboots.\n\n## 3. Create the Compose File\n\nCreate `docker-compose.yml` with this content:\n\n```yaml\nservices:\n\tsambee:\n\t\timage: ghcr.io/helgeklein/sambee:stable\n\t\trestart: unless-stopped\n\t\tvolumes:\n\t\t\t- ./data:/app/data\n\t\t\t# Optional: uncomment when you create config.toml locally.\n\t\t\t# - ./config.toml:/app/config.toml:ro\n\t\tports:\n\t\t\t- 8000:8000\n```\n\n#### Select a Release Channel\n\nSambee has three different release channels. You select which to follow via the Docker image tag:\n\n- `stable` for the production channel.\n- `beta` for prerelease builds.\n- `test` for preview builds.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nWhile Sambee is in beta, the `stable` tag may not be available yet.\n{{\u003c /admonition \u003e}}\n\n## 4. Optional: Create a Local Configuration File\n\nYou do not need `config.toml` for a basic deployment. Create it only if you need to override defaults such as authentication, logging, or Companion download settings.\n\nCreate `config.toml` with only the settings you want to change. For example:\n\n```toml\n[app]\nlog_level = \"INFO\"\n\n[security]\nauth_method = \"password\"\n\n[admin]\nusername = \"admin\"\n```\n\nIf you create `config.toml`, uncomment the read-only bind mount in `docker-compose.yml`.\n\nKeep this file local. In production, mount it read-only.\n\n## 5. Pull and Start Sambee\n\nPull the configured image:\n\n```bash\ndocker compose pull\n```\n\nThen start the application:\n\n```bash\ndocker compose up -d\n```\n\nBy default, the service is available at:\n\n- Frontend: `http://localhost:8000`\n- Backend API: `http://localhost:8000/api`\n- API docs: `http://localhost:8000/docs`\n\n## Verify the Deployment\n\nBefore moving on, confirm that the deployment really came up cleanly.\n\n- The `docker compose ps` output shows the `sambee` service running.\n- The frontend URL responds on the expected host port.\n- The startup logs do not show an obvious failure loop.\n\nFor a quick log review:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\nOnce the deployment is healthy, continue with the first login procedure on the next page.\n", "0.9": "+++\ntitle = \"Deploy Sambee with Docker\"\n+++\n\n## Before You Start\n\nYou need:\n\n- Docker and `docker compose` installed.\n- A host that can reach the SMB file servers Sambee will use.\n- A deployment directory where you can keep local files such as `docker-compose.yml`, optional `config.toml`, and the persistent `data/` directory.\n\nYou do not need to clone the repository or build Sambee locally for a normal Docker deployment. Sambee publishes ready-to-run container images to GitHub Container Registry.\n\n## 1. Create a Deployment Directory\n\nCreate a dedicated directory for your local deployment files and move into it:\n\n```bash\nmkdir -p sambee\ncd sambee\n```\n\nThis directory will hold your Compose file, optional configuration file, and persistent application data.\n\n## 2. Prepare Persistent Storage\n\nCreate the local data directory and set ownership to user and group ID `1000`, which the containerized application uses:\n\n```bash\nmkdir -p ./data\nchown -Rfv 1000:1000 ./data\n```\n\nThis directory contains the Sambee database and other state that must survive restarts, rebuilds, and host reboots.\n\n## 3. Create the Compose File\n\nCreate `docker-compose.yml` with this content:\n\n```yaml\nservices:\n\tsambee:\n\t\timage: ghcr.io/helgeklein/sambee:stable\n\t\trestart: unless-stopped\n\t\tvolumes:\n\t\t\t- ./data:/app/data\n\t\t\t# Optional: uncomment when you create config.toml locally.\n\t\t\t# - ./config.toml:/app/config.toml:ro\n\t\tports:\n\t\t\t- 8000:8000\n```\n\n#### Select a Release Channel\n\nSambee has three different release channels. You select which to follow via the Docker image tag:\n\n- `stable` for the production channel.\n- `beta` for prerelease builds.\n- `test` for preview builds.\n\n## 4. Optional: Create a Local Configuration File\n\nYou do not need `config.toml` for a basic deployment. Create it only if you need to override defaults such as logging or Companion download settings. Configure the authentication mode in **Settings** \u003e **Administration** \u003e **Authentication** after signing in.\n\nCreate `config.toml` with only the settings you want to change. For example:\n\n```toml\n[app]\nlog_level = \"INFO\"\n\n[admin]\nusername = \"admin\"\n```\n\nIf you create `config.toml`, uncomment the read-only bind mount in `docker-compose.yml`.\n\nKeep this file local. In production, mount it read-only.\n\n## 5. Pull and Start Sambee\n\nPull the configured image:\n\n```bash\ndocker compose pull\n```\n\nThen start the application:\n\n```bash\ndocker compose up -d\n```\n\nBy default, the service is available at:\n\n- Frontend: `http://localhost:8000`\n- Backend API: `http://localhost:8000/api`\n- API docs: `http://localhost:8000/docs`\n\n## Verify the Deployment\n\nBefore moving on, confirm that the deployment really came up cleanly.\n\n- The `docker compose ps` output shows the `sambee` service running.\n- The frontend URL responds on the expected host port.\n- The startup logs do not show an obvious failure loop.\n\nFor a quick log review:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\nOnce the deployment is healthy, continue with the first login procedure on the next page.\n", "1.0": "+++\ntitle = \"Deploy Sambee with Docker\"\n+++\n\n## Before You Start\n\nYou need:\n\n- Docker and `docker compose` installed.\n- A host that can reach the SMB file servers Sambee will use.\n- A deployment directory where you can keep local files such as `docker-compose.yml`, optional `config.toml`, and the persistent `data/` directory.\n\nYou do not need to clone the repository or build Sambee locally for a normal Docker deployment. Sambee publishes ready-to-run container images to GitHub Container Registry.\n\n## 1. Create a Deployment Directory\n\nCreate a dedicated directory for your local deployment files and move into it:\n\n```bash\nmkdir -p sambee\ncd sambee\n```\n\nThis directory will hold your Compose file, optional configuration file, and persistent application data.\n\n## 2. Prepare Persistent Storage\n\nCreate the local data directory and set ownership to user and group ID `1000`, which the containerized application uses:\n\n```bash\nmkdir -p ./data\nchown -Rfv 1000:1000 ./data\n```\n\nThis directory contains the Sambee database and other state that must survive restarts, rebuilds, and host reboots.\n\n## 3. Create the Compose File\n\nCreate `docker-compose.yml` with this content:\n\n```yaml\nservices:\n\tsambee:\n\t\timage: ghcr.io/helgeklein/sambee:stable\n\t\trestart: unless-stopped\n\t\tvolumes:\n\t\t\t- ./data:/app/data\n\t\t\t# Optional: uncomment when you create config.toml locally.\n\t\t\t# - ./config.toml:/app/config.toml:ro\n\t\tports:\n\t\t\t- 8000:8000\n```\n\n#### Select a Release Channel\n\nSambee has three different release channels. You select which to follow via the Docker image tag:\n\n- `stable` for the production channel.\n- `beta` for prerelease builds.\n- `test` for preview builds.\n\n## 4. Optional: Create a Local Configuration File\n\nYou do not need `config.toml` for a basic deployment. Create it only if you need to override defaults such as logging or Companion download settings. Configure the authentication mode in **Settings** \u003e **Administration** \u003e **Authentication** after signing in.\n\nCreate `config.toml` with only the settings you want to change. For example:\n\n```toml\n[app]\nlog_level = \"INFO\"\n\n[admin]\nusername = \"admin\"\n```\n\nIf you create `config.toml`, uncomment the read-only bind mount in `docker-compose.yml`.\n\nKeep this file local. In production, mount it read-only.\n\n## 5. Pull and Start Sambee\n\nPull the configured image:\n\n```bash\ndocker compose pull\n```\n\nThen start the application:\n\n```bash\ndocker compose up -d\n```\n\nBy default, the service is available at:\n\n- Frontend: `http://localhost:8000`\n- Backend API: `http://localhost:8000/api`\n- API docs: `http://localhost:8000/docs`\n\n## Verify the Deployment\n\nBefore moving on, confirm that the deployment really came up cleanly.\n\n- The `docker compose ps` output shows the `sambee` service running.\n- The frontend URL responds on the expected host port.\n- The startup logs do not show an obvious failure loop.\n\nFor a quick log review:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\nOnce the deployment is healthy, continue with the first login procedure on the next page.\n", "2.0": "+++\ntitle = \"Deploy Sambee with Docker\"\n+++\n\n## Before You Start\n\nYou need:\n\n- Docker and `docker compose` installed.\n- A host that can reach the SMB file servers Sambee will use.\n- A deployment directory where you can keep local files such as `docker-compose.yml`, optional `config.toml`, and the persistent `data/` directory.\n\nYou do not need to clone the repository or build Sambee locally for a normal Docker deployment. Sambee publishes ready-to-run container images to GitHub Container Registry.\n\n## 1. Create a Deployment Directory\n\nCreate a dedicated directory for your local deployment files and move into it:\n\n```bash\nmkdir -p sambee\ncd sambee\n```\n\nThis directory will hold your Compose file, optional configuration file, and persistent application data.\n\n## 2. Prepare Persistent Storage\n\nCreate the local data directory and set ownership to user and group ID `1000`, which the containerized application uses:\n\n```bash\nmkdir -p ./data\nchown -Rfv 1000:1000 ./data\n```\n\nThis directory contains the Sambee database and other state that must survive restarts, rebuilds, and host reboots.\n\n## 3. Create the Compose File\n\nCreate `docker-compose.yml` with this content:\n\n```yaml\nservices:\n\tsambee:\n\t\timage: ghcr.io/sambee-app/sambee:stable\n\t\trestart: unless-stopped\n\t\tvolumes:\n\t\t\t- ./data:/app/data\n\t\t\t# Optional: uncomment when you create config.toml locally.\n\t\t\t# - ./config.toml:/app/config.toml:ro\n\t\tports:\n\t\t\t- 8000:8000\n```\n\n#### Select a Release Channel\n\nSambee has three different release channels. You select which to follow via the Docker image tag:\n\n- `stable` for the production channel.\n- `beta` for prerelease builds.\n- `test` for preview builds.\n\n## 4. Optional: Create a Local Configuration File\n\nYou do not need `config.toml` for a basic deployment. Create it only if you need to override defaults such as logging or Companion download settings. Configure the authentication mode in **Settings** \u003e **Administration** \u003e **Authentication** after signing in.\n\nCreate `config.toml` with only the settings you want to change. For example:\n\n```toml\n[app]\nlog_level = \"INFO\"\n\n[admin]\nusername = \"admin\"\n```\n\nIf you create `config.toml`, uncomment the read-only bind mount in `docker-compose.yml`.\n\nKeep this file local. In production, mount it read-only.\n\n## 5. Pull and Start Sambee\n\nPull the configured image:\n\n```bash\ndocker compose pull\n```\n\nThen start the application:\n\n```bash\ndocker compose up -d\n```\n\nBy default, the service is available at:\n\n- Frontend: `http://localhost:8000`\n- Backend API: `http://localhost:8000/api`\n- API docs: `http://localhost:8000/docs`\n\n## Verify the Deployment\n\nBefore moving on, confirm that the deployment really came up cleanly.\n\n- The `docker compose ps` output shows the `sambee` service running.\n- The frontend URL responds on the expected host port.\n- The startup logs do not show an obvious failure loop.\n\nFor a quick log review:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\nOnce the deployment is healthy, continue with the first login procedure on the next page.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Deploy Sambee with Docker\"\n+++\n\n## Before You Start\n\nYou need:\n\n- Docker and `docker compose` installed.\n- A host that can reach the SMB file servers Sambee will use.\n- A deployment directory where you can keep local files such as `docker-compose.yml`, optional `config.toml`, and the persistent `data/` directory.\n\nYou do not need to clone the repository or build Sambee locally for a normal Docker deployment. Sambee publishes ready-to-run container images to GitHub Container Registry.\n\n## 1. Create a Deployment Directory\n\nCreate a dedicated directory for your local deployment files and move into it:\n\n```bash\nmkdir -p sambee\ncd sambee\n```\n\nThis directory will hold your Compose file, optional configuration file, and persistent application data.\n\n## 2. Prepare Persistent Storage\n\nCreate the local data directory and set ownership to user and group ID `1000`, which the containerized application uses:\n\n```bash\nmkdir -p ./data\nchown -Rfv 1000:1000 ./data\n```\n\nThis directory contains the Sambee database and other state that must survive restarts, rebuilds, and host reboots.\n\n## 3. Create the Compose File\n\nCreate `docker-compose.yml` with this content:\n\n```yaml\nservices:\n\tsambee:\n\t\timage: ghcr.io/helgeklein/sambee:stable\n\t\trestart: unless-stopped\n\t\tvolumes:\n\t\t\t- ./data:/app/data\n\t\t\t# Optional: uncomment when you create config.toml locally.\n\t\t\t# - ./config.toml:/app/config.toml:ro\n\t\tports:\n\t\t\t- 8000:8000\n```\n\n#### Select a Release Channel\n\nSambee has three different release channels. You select which to follow via the Docker image tag:\n\n- `stable` for the production channel.\n- `beta` for prerelease builds.\n- `test` for preview builds.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nWhile Sambee is in beta, the `stable` tag may not be available yet.\n{{\u003c /admonition \u003e}}\n\n## 4. Optional: Create a Local Configuration File\n\nYou do not need `config.toml` for a basic deployment. Create it only if you need to override defaults such as authentication, logging, or Companion download settings.\n\nCreate `config.toml` with only the settings you want to change. For example:\n\n```toml\n[app]\nlog_level = \"INFO\"\n\n[security]\nauth_method = \"password\"\n\n[admin]\nusername = \"admin\"\n```\n\nIf you create `config.toml`, uncomment the read-only bind mount in `docker-compose.yml`.\n\nKeep this file local. In production, mount it read-only.\n\n## 5. Pull and Start Sambee\n\nPull the configured image:\n\n```bash\ndocker compose pull\n```\n\nThen start the application:\n\n```bash\ndocker compose up -d\n```\n\nBy default, the service is available at:\n\n- Frontend: `http://localhost:8000`\n- Backend API: `http://localhost:8000/api`\n- API docs: `http://localhost:8000/docs`\n\n## Verify the Deployment\n\nBefore moving on, confirm that the deployment really came up cleanly.\n\n- The `docker compose ps` output shows the `sambee` service running.\n- The frontend URL responds on the expected host port.\n- The startup logs do not show an obvious failure loop.\n\nFor a quick log review:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\nOnce the deployment is healthy, continue with the first login procedure on the next page.\n", "0.8": "+++\ntitle = \"Deploy Sambee with Docker\"\n+++\n\n## Before You Start\n\nYou need:\n\n- Docker and `docker compose` installed.\n- A host that can reach the SMB file servers Sambee will use.\n- A deployment directory where you can keep local files such as `docker-compose.yml`, optional `config.toml`, and the persistent `data/` directory.\n\nYou do not need to clone the repository or build Sambee locally for a normal Docker deployment. Sambee publishes ready-to-run container images to GitHub Container Registry.\n\n## 1. Create a Deployment Directory\n\nCreate a dedicated directory for your local deployment files and move into it:\n\n```bash\nmkdir -p sambee\ncd sambee\n```\n\nThis directory will hold your Compose file, optional configuration file, and persistent application data.\n\n## 2. Prepare Persistent Storage\n\nCreate the local data directory and set ownership to user and group ID `1000`, which the containerized application uses:\n\n```bash\nmkdir -p ./data\nchown -Rfv 1000:1000 ./data\n```\n\nThis directory contains the Sambee database and other state that must survive restarts, rebuilds, and host reboots.\n\n## 3. Create the Compose File\n\nCreate `docker-compose.yml` with this content:\n\n```yaml\nservices:\n\tsambee:\n\t\timage: ghcr.io/helgeklein/sambee:stable\n\t\trestart: unless-stopped\n\t\tvolumes:\n\t\t\t- ./data:/app/data\n\t\t\t# Optional: uncomment when you create config.toml locally.\n\t\t\t# - ./config.toml:/app/config.toml:ro\n\t\tports:\n\t\t\t- 8000:8000\n```\n\n#### Select a Release Channel\n\nSambee has three different release channels. You select which to follow via the Docker image tag:\n\n- `stable` for the production channel.\n- `beta` for prerelease builds.\n- `test` for preview builds.\n\n{{\u003c admonition type=\"tip\" \u003e}}\nWhile Sambee is in beta, the `stable` tag may not be available yet.\n{{\u003c /admonition \u003e}}\n\n## 4. Optional: Create a Local Configuration File\n\nYou do not need `config.toml` for a basic deployment. Create it only if you need to override defaults such as authentication, logging, or Companion download settings.\n\nCreate `config.toml` with only the settings you want to change. For example:\n\n```toml\n[app]\nlog_level = \"INFO\"\n\n[security]\nauth_method = \"password\"\n\n[admin]\nusername = \"admin\"\n```\n\nIf you create `config.toml`, uncomment the read-only bind mount in `docker-compose.yml`.\n\nKeep this file local. In production, mount it read-only.\n\n## 5. Pull and Start Sambee\n\nPull the configured image:\n\n```bash\ndocker compose pull\n```\n\nThen start the application:\n\n```bash\ndocker compose up -d\n```\n\nBy default, the service is available at:\n\n- Frontend: `http://localhost:8000`\n- Backend API: `http://localhost:8000/api`\n- API docs: `http://localhost:8000/docs`\n\n## Verify the Deployment\n\nBefore moving on, confirm that the deployment really came up cleanly.\n\n- The `docker compose ps` output shows the `sambee` service running.\n- The frontend URL responds on the expected host port.\n- The startup logs do not show an obvious failure loop.\n\nFor a quick log review:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\nOnce the deployment is healthy, continue with the first login procedure on the next page.\n", "0.9": "+++\ntitle = \"Deploy Sambee with Docker\"\n+++\n\n## Before You Start\n\nYou need:\n\n- Docker and `docker compose` installed.\n- A host that can reach the SMB file servers Sambee will use.\n- A deployment directory where you can keep local files such as `docker-compose.yml`, optional `config.toml`, and the persistent `data/` directory.\n\nYou do not need to clone the repository or build Sambee locally for a normal Docker deployment. Sambee publishes ready-to-run container images to GitHub Container Registry.\n\n## 1. Create a Deployment Directory\n\nCreate a dedicated directory for your local deployment files and move into it:\n\n```bash\nmkdir -p sambee\ncd sambee\n```\n\nThis directory will hold your Compose file, optional configuration file, and persistent application data.\n\n## 2. Prepare Persistent Storage\n\nCreate the local data directory and set ownership to user and group ID `1000`, which the containerized application uses:\n\n```bash\nmkdir -p ./data\nchown -Rfv 1000:1000 ./data\n```\n\nThis directory contains the Sambee database and other state that must survive restarts, rebuilds, and host reboots.\n\n## 3. Create the Compose File\n\nCreate `docker-compose.yml` with this content:\n\n```yaml\nservices:\n\tsambee:\n\t\timage: ghcr.io/helgeklein/sambee:stable\n\t\trestart: unless-stopped\n\t\tvolumes:\n\t\t\t- ./data:/app/data\n\t\t\t# Optional: uncomment when you create config.toml locally.\n\t\t\t# - ./config.toml:/app/config.toml:ro\n\t\tports:\n\t\t\t- 8000:8000\n```\n\n#### Select a Release Channel\n\nSambee has three different release channels. You select which to follow via the Docker image tag:\n\n- `stable` for the production channel.\n- `beta` for prerelease builds.\n- `test` for preview builds.\n\n## 4. Optional: Create a Local Configuration File\n\nYou do not need `config.toml` for a basic deployment. Create it only if you need to override defaults such as logging or Companion download settings. Configure the authentication mode in **Settings** \u003e **Administration** \u003e **Authentication** after signing in.\n\nCreate `config.toml` with only the settings you want to change. For example:\n\n```toml\n[app]\nlog_level = \"INFO\"\n\n[admin]\nusername = \"admin\"\n```\n\nIf you create `config.toml`, uncomment the read-only bind mount in `docker-compose.yml`.\n\nKeep this file local. In production, mount it read-only.\n\n## 5. Pull and Start Sambee\n\nPull the configured image:\n\n```bash\ndocker compose pull\n```\n\nThen start the application:\n\n```bash\ndocker compose up -d\n```\n\nBy default, the service is available at:\n\n- Frontend: `http://localhost:8000`\n- Backend API: `http://localhost:8000/api`\n- API docs: `http://localhost:8000/docs`\n\n## Verify the Deployment\n\nBefore moving on, confirm that the deployment really came up cleanly.\n\n- The `docker compose ps` output shows the `sambee` service running.\n- The frontend URL responds on the expected host port.\n- The startup logs do not show an obvious failure loop.\n\nFor a quick log review:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\nOnce the deployment is healthy, continue with the first login procedure on the next page.\n", "1.0": "+++\ntitle = \"Deploy Sambee with Docker\"\n+++\n\n## Before You Start\n\nYou need:\n\n- Docker and `docker compose` installed.\n- A host that can reach the SMB file servers Sambee will use.\n- A deployment directory where you can keep local files such as `docker-compose.yml`, optional `config.toml`, and the persistent `data/` directory.\n\nYou do not need to clone the repository or build Sambee locally for a normal Docker deployment. Sambee publishes ready-to-run container images to GitHub Container Registry.\n\n## 1. Create a Deployment Directory\n\nCreate a dedicated directory for your local deployment files and move into it:\n\n```bash\nmkdir -p sambee\ncd sambee\n```\n\nThis directory will hold your Compose file, optional configuration file, and persistent application data.\n\n## 2. Prepare Persistent Storage\n\nCreate the local data directory and set ownership to user and group ID `1000`, which the containerized application uses:\n\n```bash\nmkdir -p ./data\nchown -Rfv 1000:1000 ./data\n```\n\nThis directory contains the Sambee database and other state that must survive restarts, rebuilds, and host reboots.\n\n## 3. Create the Compose File\n\nCreate `docker-compose.yml` with this content:\n\n```yaml\nservices:\n\tsambee:\n\t\timage: ghcr.io/helgeklein/sambee:stable\n\t\trestart: unless-stopped\n\t\tvolumes:\n\t\t\t- ./data:/app/data\n\t\t\t# Optional: uncomment when you create config.toml locally.\n\t\t\t# - ./config.toml:/app/config.toml:ro\n\t\tports:\n\t\t\t- 8000:8000\n```\n\n#### Select a Release Channel\n\nSambee has three different release channels. You select which to follow via the Docker image tag:\n\n- `stable` for the production channel.\n- `beta` for prerelease builds.\n- `test` for preview builds.\n\n## 4. Optional: Create a Local Configuration File\n\nYou do not need `config.toml` for a basic deployment. Create it only if you need to override defaults such as logging or Companion download settings. Configure the authentication mode in **Settings** \u003e **Administration** \u003e **Authentication** after signing in.\n\nCreate `config.toml` with only the settings you want to change. For example:\n\n```toml\n[app]\nlog_level = \"INFO\"\n\n[admin]\nusername = \"admin\"\n```\n\nIf you create `config.toml`, uncomment the read-only bind mount in `docker-compose.yml`.\n\nKeep this file local. In production, mount it read-only.\n\n## 5. Pull and Start Sambee\n\nPull the configured image:\n\n```bash\ndocker compose pull\n```\n\nThen start the application:\n\n```bash\ndocker compose up -d\n```\n\nBy default, the service is available at:\n\n- Frontend: `http://localhost:8000`\n- Backend API: `http://localhost:8000/api`\n- API docs: `http://localhost:8000/docs`\n\n## Verify the Deployment\n\nBefore moving on, confirm that the deployment really came up cleanly.\n\n- The `docker compose ps` output shows the `sambee` service running.\n- The frontend URL responds on the expected host port.\n- The startup logs do not show an obvious failure loop.\n\nFor a quick log review:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\nOnce the deployment is healthy, continue with the first login procedure on the next page.\n", "2.0": "+++\ntitle = \"Deploy Sambee with Docker\"\n+++\n\n## Before You Start\n\nYou need:\n\n- Docker and `docker compose` installed.\n- A host that can reach the SMB file servers Sambee will use.\n- A deployment directory where you can keep local files such as `docker-compose.yml`, optional `config.toml`, and the persistent `data/` directory.\n\nYou do not need to clone the repository or build Sambee locally for a normal Docker deployment. Sambee publishes ready-to-run container images to GitHub Container Registry.\n\n## 1. Create a Deployment Directory\n\nCreate a dedicated directory for your local deployment files and move into it:\n\n```bash\nmkdir -p sambee\ncd sambee\n```\n\nThis directory will hold your Compose file, optional configuration file, and persistent application data.\n\n## 2. Prepare Persistent Storage\n\nCreate the local data directory and set ownership to user and group ID `1000`, which the containerized application uses:\n\n```bash\nmkdir -p ./data\nchown -Rfv 1000:1000 ./data\n```\n\nThis directory contains the Sambee database and other state that must survive restarts, rebuilds, and host reboots.\n\n## 3. Create the Compose File\n\nCreate `docker-compose.yml` with this content:\n\n```yaml\nservices:\n\tsambee:\n\t\timage: ghcr.io/sambee-app/sambee:stable\n\t\trestart: unless-stopped\n\t\tvolumes:\n\t\t\t- ./data:/app/data\n\t\t\t# Optional: uncomment when you create config.toml locally.\n\t\t\t# - ./config.toml:/app/config.toml:ro\n\t\tports:\n\t\t\t- 8000:8000\n```\n\n#### Select a Release Channel\n\nSambee has three different release channels. You select which to follow via the Docker image tag:\n\n- `stable` for the production channel.\n- `beta` for prerelease builds.\n- `test` for preview builds.\n\n## 4. Optional: Create a Local Configuration File\n\nYou do not need `config.toml` for a basic deployment. Create it only if you need to override defaults such as logging or Companion download settings. Configure the authentication mode in **Settings** \u003e **Administration** \u003e **Authentication** after signing in.\n\nCreate `config.toml` with only the settings you want to change. For example:\n\n```toml\n[app]\nlog_level = \"INFO\"\n\n[admin]\nusername = \"admin\"\n```\n\nIf you create `config.toml`, uncomment the read-only bind mount in `docker-compose.yml`.\n\nKeep this file local. In production, mount it read-only.\n\n## 5. Pull and Start Sambee\n\nPull the configured image:\n\n```bash\ndocker compose pull\n```\n\nThen start the application:\n\n```bash\ndocker compose up -d\n```\n\nBy default, the service is available at:\n\n- Frontend: `http://localhost:8000`\n- Backend API: `http://localhost:8000/api`\n- API docs: `http://localhost:8000/docs`\n\n## Verify the Deployment\n\nBefore moving on, confirm that the deployment really came up cleanly.\n\n- The `docker compose ps` output shows the `sambee` service running.\n- The frontend URL responds on the expected host port.\n- The startup logs do not show an obvious failure loop.\n\nFor a quick log review:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\nOnce the deployment is healthy, continue with the first login procedure on the next page.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:admin-guide/installation-and-deployment/first-startup-and-first-admin-login", "parent_id": "section:admin-guide/installation-and-deployment", "depth": 2, "kind": "page", "label": "first-startup-and-first-admin-login", "title": "First Startup And First Admin Login", "path": "admin-guide/installation-and-deployment/first-startup-and-first-admin-login", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"First Startup and First Admin Login\"\n+++\n\nOnce the container is up, retrieve the initial credentials and confirm that you can sign in as the first administrator.\n\n## Retrieve the Initial Admin Password\n\nGet the first-time admin password from the logs:\n\n```bash\ndocker compose logs sambee --tail 100 | grep -A 5 \"FIRST-TIME SETUP\"\n```\n\nYou are looking for a log block labeled `FIRST-TIME SETUP - SAVE THESE CREDENTIALS` with lines for the username and password.\n\nYou will need:\n\n- Username: `admin`, unless you changed it through configuration.\n- Password: The generated password from the logs.\n\n## Sign In\n\nOpen Sambee in the browser at the frontend URL for your deployment and sign in with the initial admin credentials.\n\nThis first sign-in confirms that:\n\n- The service is reachable.\n- The frontend is loading.\n- The backend startup completed far enough to expose the first-time setup information.\n", "0.8": "+++\ntitle = \"First Startup and First Admin Login\"\n+++\n\nOnce the container is up, retrieve the initial credentials and confirm that you can sign in as the first administrator.\n\n## Retrieve the Initial Admin Password\n\nGet the first-time admin password from the logs:\n\n```bash\ndocker compose logs sambee --tail 100 | grep -A 5 \"FIRST-TIME SETUP\"\n```\n\nYou are looking for a log block labeled `FIRST-TIME SETUP - SAVE THESE CREDENTIALS` with lines for the username and password.\n\nYou will need:\n\n- Username: `admin`, unless you changed it through configuration.\n- Password: The generated password from the logs.\n\n## Sign In\n\nOpen Sambee in the browser at the frontend URL for your deployment and sign in with the initial admin credentials.\n\nThis first sign-in confirms that:\n\n- The service is reachable.\n- The frontend is loading.\n- The backend startup completed far enough to expose the first-time setup information.\n", "0.9": "+++\ntitle = \"First Startup and First Admin Login\"\n+++\n\nOnce the container is up, retrieve the initial credentials and confirm that you can sign in as the first administrator.\n\n## Retrieve the Initial Admin Password\n\nGet the first-time admin password from the logs:\n\n```bash\ndocker compose logs sambee --tail 100 | grep -A 5 \"FIRST-TIME SETUP\"\n```\n\nYou are looking for a log block labeled `FIRST-TIME SETUP - SAVE THESE CREDENTIALS` with lines for the username and password.\n\nYou will need:\n\n- Username: `admin`, unless you changed it through configuration.\n- Password: The generated password from the logs.\n\n## Sign In\n\nOpen Sambee in the browser at the frontend URL for your deployment and sign in with the initial admin credentials.\n\nThis first sign-in confirms that:\n\n- The service is reachable.\n- The frontend is loading.\n- The backend startup completed far enough to expose the first-time setup information.\n", "1.0": "+++\ntitle = \"First Startup and First Admin Login\"\n+++\n\nOnce the container is up, retrieve the initial credentials and confirm that you can sign in as the first administrator.\n\n## Retrieve the Initial Admin Password\n\nGet the first-time admin password from the logs:\n\n```bash\ndocker compose logs sambee --tail 100 | grep -A 5 \"FIRST-TIME SETUP\"\n```\n\nYou are looking for a log block labeled `FIRST-TIME SETUP - SAVE THESE CREDENTIALS` with lines for the username and password.\n\nYou will need:\n\n- Username: `admin`, unless you changed it through configuration.\n- Password: The generated password from the logs.\n\n## Sign In\n\nOpen Sambee in the browser at the frontend URL for your deployment and sign in with the initial admin credentials.\n\nThis first sign-in confirms that:\n\n- The service is reachable.\n- The frontend is loading.\n- The backend startup completed far enough to expose the first-time setup information.\n", "2.0": "+++\ntitle = \"First Startup and First Admin Login\"\n+++\n\nOnce the container is up, retrieve the initial credentials and confirm that you can sign in as the first administrator.\n\n## Retrieve the Initial Admin Password\n\nGet the first-time admin password from the logs:\n\n```bash\ndocker compose logs sambee --tail 100 | grep -A 5 \"FIRST-TIME SETUP\"\n```\n\nYou are looking for a log block labeled `FIRST-TIME SETUP - SAVE THESE CREDENTIALS` with lines for the username and password.\n\nYou will need:\n\n- Username: `admin`, unless you changed it through configuration.\n- Password: The generated password from the logs.\n\n## Sign In\n\nOpen Sambee in the browser at the frontend URL for your deployment and sign in with the initial admin credentials.\n\nThis first sign-in confirms that:\n\n- The service is reachable.\n- The frontend is loading.\n- The backend startup completed far enough to expose the first-time setup information.\n"}, "page_contents": {"0.7": "+++\ntitle = \"First Startup and First Admin Login\"\n+++\n\nOnce the container is up, retrieve the initial credentials and confirm that you can sign in as the first administrator.\n\n## Retrieve the Initial Admin Password\n\nGet the first-time admin password from the logs:\n\n```bash\ndocker compose logs sambee --tail 100 | grep -A 5 \"FIRST-TIME SETUP\"\n```\n\nYou are looking for a log block labeled `FIRST-TIME SETUP - SAVE THESE CREDENTIALS` with lines for the username and password.\n\nYou will need:\n\n- Username: `admin`, unless you changed it through configuration.\n- Password: The generated password from the logs.\n\n## Sign In\n\nOpen Sambee in the browser at the frontend URL for your deployment and sign in with the initial admin credentials.\n\nThis first sign-in confirms that:\n\n- The service is reachable.\n- The frontend is loading.\n- The backend startup completed far enough to expose the first-time setup information.\n", "0.8": "+++\ntitle = \"First Startup and First Admin Login\"\n+++\n\nOnce the container is up, retrieve the initial credentials and confirm that you can sign in as the first administrator.\n\n## Retrieve the Initial Admin Password\n\nGet the first-time admin password from the logs:\n\n```bash\ndocker compose logs sambee --tail 100 | grep -A 5 \"FIRST-TIME SETUP\"\n```\n\nYou are looking for a log block labeled `FIRST-TIME SETUP - SAVE THESE CREDENTIALS` with lines for the username and password.\n\nYou will need:\n\n- Username: `admin`, unless you changed it through configuration.\n- Password: The generated password from the logs.\n\n## Sign In\n\nOpen Sambee in the browser at the frontend URL for your deployment and sign in with the initial admin credentials.\n\nThis first sign-in confirms that:\n\n- The service is reachable.\n- The frontend is loading.\n- The backend startup completed far enough to expose the first-time setup information.\n", "0.9": "+++\ntitle = \"First Startup and First Admin Login\"\n+++\n\nOnce the container is up, retrieve the initial credentials and confirm that you can sign in as the first administrator.\n\n## Retrieve the Initial Admin Password\n\nGet the first-time admin password from the logs:\n\n```bash\ndocker compose logs sambee --tail 100 | grep -A 5 \"FIRST-TIME SETUP\"\n```\n\nYou are looking for a log block labeled `FIRST-TIME SETUP - SAVE THESE CREDENTIALS` with lines for the username and password.\n\nYou will need:\n\n- Username: `admin`, unless you changed it through configuration.\n- Password: The generated password from the logs.\n\n## Sign In\n\nOpen Sambee in the browser at the frontend URL for your deployment and sign in with the initial admin credentials.\n\nThis first sign-in confirms that:\n\n- The service is reachable.\n- The frontend is loading.\n- The backend startup completed far enough to expose the first-time setup information.\n", "1.0": "+++\ntitle = \"First Startup and First Admin Login\"\n+++\n\nOnce the container is up, retrieve the initial credentials and confirm that you can sign in as the first administrator.\n\n## Retrieve the Initial Admin Password\n\nGet the first-time admin password from the logs:\n\n```bash\ndocker compose logs sambee --tail 100 | grep -A 5 \"FIRST-TIME SETUP\"\n```\n\nYou are looking for a log block labeled `FIRST-TIME SETUP - SAVE THESE CREDENTIALS` with lines for the username and password.\n\nYou will need:\n\n- Username: `admin`, unless you changed it through configuration.\n- Password: The generated password from the logs.\n\n## Sign In\n\nOpen Sambee in the browser at the frontend URL for your deployment and sign in with the initial admin credentials.\n\nThis first sign-in confirms that:\n\n- The service is reachable.\n- The frontend is loading.\n- The backend startup completed far enough to expose the first-time setup information.\n", "2.0": "+++\ntitle = \"First Startup and First Admin Login\"\n+++\n\nOnce the container is up, retrieve the initial credentials and confirm that you can sign in as the first administrator.\n\n## Retrieve the Initial Admin Password\n\nGet the first-time admin password from the logs:\n\n```bash\ndocker compose logs sambee --tail 100 | grep -A 5 \"FIRST-TIME SETUP\"\n```\n\nYou are looking for a log block labeled `FIRST-TIME SETUP - SAVE THESE CREDENTIALS` with lines for the username and password.\n\nYou will need:\n\n- Username: `admin`, unless you changed it through configuration.\n- Password: The generated password from the logs.\n\n## Sign In\n\nOpen Sambee in the browser at the frontend URL for your deployment and sign in with the initial admin credentials.\n\nThis first sign-in confirms that:\n\n- The service is reachable.\n- The frontend is loading.\n- The backend startup completed far enough to expose the first-time setup information.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:admin-guide/network-and-reverse-proxy", "parent_id": "book:admin-guide", "depth": 1, "kind": "section", "label": "network-and-reverse-proxy", "title": "Network and Reverse Proxy", "path": "admin-guide/network-and-reverse-proxy", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:admin-guide/network-and-reverse-proxy/put-sambee-behind-a-reverse-proxy", "parent_id": "section:admin-guide/network-and-reverse-proxy", "depth": 2, "kind": "page", "label": "put-sambee-behind-a-reverse-proxy", "title": "Put Sambee Behind A Reverse Proxy", "path": "admin-guide/network-and-reverse-proxy/put-sambee-behind-a-reverse-proxy", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Put Sambee behind a Reverse Proxy\"\n+++\n\nFor production-style deployments, place a reverse proxy in front of Sambee to handle HTTPS.\n\n## Why Use a Reverse Proxy\n\nA reverse proxy gives you a cleaner operational model for:\n\n- HTTPS and certificate management\n- A stable hostname and routing layer in front of the container\n\n## Caddy Example\n\nIf you already run a dockerized Caddy environment, the Sambee service can be connected to that network with a compose layout like this:\n\n```yaml\nservices:\n  sambee:\n    container_name: sambee\n    hostname: sambee\n    build: .\n    restart: unless-stopped\n    networks:\n      - caddy_caddynet\n    expose:\n      - \"8000\"\n    volumes:\n      - ./data:/app/data\n      # Optional:\n      # - ./config.toml:/app/config.toml:ro\n\nnetworks:\n  caddy_caddynet:\n    external: true\n```\n\nHere, `expose` makes Sambee's port `8000` available to other containers on the same Docker network without publishing it directly to the host.\n\nThe important point is that Sambee serves plain HTTP to the reverse proxy and does not act as the HTTPS edge itself.\n\n## Companion Native Editing Behind Interactive Auth\n\nIf your reverse proxy protects the Sambee backend with an interactive login flow, Companion native editing can still work, but the proxy setup has to satisfy a few constraints.\n\nThe Companion runtime opens its own `Sambee Authentication` webview when reverse-proxy auth intercepts backend API calls. After the user signs in there, Companion reuses backend-origin cookies from that embedded webview for its Rust-side API requests.\n\nFor that to work reliably:\n\n- The reverse-proxy cookie must be valid for the Sambee backend origin that Companion calls.\n- The login flow must work inside the system webview used by Tauri on the target desktop platform.\n- The proxy must not depend on browser features that are unavailable in that embedded webview.\n- The proxy must allow authenticated requests to the Companion backend endpoints after the embedded webview has established the proxy session.\n\n{{\u003c admonition type=\"note\" \u003e}}\nCompanion does not and cannot read cookies from the user\u2019s Sambee frontend browser session.\n{{\u003c /admonition \u003e}}\n\nOperationally, that means you should test both the browser UI and a real Companion native-edit session when introducing or changing proxy auth. A useful native-edit test signs in through the Companion authentication window, opens an SMB-backed file in a desktop app, uploads or closes the edit session, and confirms that lock release works without a second unexpected login prompt.\n", "0.8": "+++\ntitle = \"Put Sambee behind a Reverse Proxy\"\n+++\n\nFor production-style deployments, place a reverse proxy in front of Sambee to handle HTTPS.\n\n## Why Use a Reverse Proxy\n\nA reverse proxy gives you a cleaner operational model for:\n\n- HTTPS and certificate management\n- A stable hostname and routing layer in front of the container\n\n## Caddy Example\n\nIf you already run a dockerized Caddy environment, the Sambee service can be connected to that network with a compose layout like this:\n\n```yaml\nservices:\n  sambee:\n    container_name: sambee\n    hostname: sambee\n    build: .\n    restart: unless-stopped\n    networks:\n      - caddy_caddynet\n    expose:\n      - \"8000\"\n    volumes:\n      - ./data:/app/data\n      # Optional:\n      # - ./config.toml:/app/config.toml:ro\n\nnetworks:\n  caddy_caddynet:\n    external: true\n```\n\nHere, `expose` makes Sambee's port `8000` available to other containers on the same Docker network without publishing it directly to the host.\n\nThe important point is that Sambee serves plain HTTP to the reverse proxy and does not act as the HTTPS edge itself.\n\n## Companion Native Editing Behind Interactive Auth\n\nIf your reverse proxy protects the Sambee backend with an interactive login flow, Companion native editing can still work, but the proxy setup has to satisfy a few constraints.\n\nThe Companion runtime opens its own `Sambee Authentication` webview when reverse-proxy auth intercepts backend API calls. After the user signs in there, Companion reuses backend-origin cookies from that embedded webview for its Rust-side API requests.\n\nFor that to work reliably:\n\n- The reverse-proxy cookie must be valid for the Sambee backend origin that Companion calls.\n- The login flow must work inside the system webview used by Tauri on the target desktop platform.\n- The proxy must not depend on browser features that are unavailable in that embedded webview.\n- The proxy must allow authenticated requests to the Companion backend endpoints after the embedded webview has established the proxy session.\n\n{{\u003c admonition type=\"note\" \u003e}}\nCompanion does not and cannot read cookies from the user\u2019s Sambee frontend browser session.\n{{\u003c /admonition \u003e}}\n\nOperationally, that means you should test both the browser UI and a real Companion native-edit session when introducing or changing proxy auth. A useful native-edit test signs in through the Companion authentication window, opens an SMB-backed file in a desktop app, uploads or closes the edit session, and confirms that lock release works without a second unexpected login prompt.\n", "0.9": "+++\ntitle = \"Put Sambee behind a Reverse Proxy\"\n+++\n\nFor production-style deployments, place a reverse proxy in front of Sambee to handle HTTPS.\n\n## Why Use a Reverse Proxy\n\nA reverse proxy gives you a cleaner operational model for:\n\n- HTTPS and certificate management\n- A stable hostname and routing layer in front of the container\n\n## Caddy Example\n\nIf you already run a dockerized Caddy environment, the Sambee service can be connected to that network with a compose layout like this:\n\n```yaml\nservices:\n  sambee:\n    container_name: sambee\n    hostname: sambee\n    build: .\n    restart: unless-stopped\n    networks:\n      - caddy_caddynet\n    expose:\n      - \"8000\"\n    volumes:\n      - ./data:/app/data\n      # Optional:\n      # - ./config.toml:/app/config.toml:ro\n\nnetworks:\n  caddy_caddynet:\n    external: true\n```\n\nHere, `expose` makes Sambee's port `8000` available to other containers on the same Docker network without publishing it directly to the host.\n\nThe important point is that Sambee serves plain HTTP to the reverse proxy and does not act as the HTTPS edge itself.\n\n## Companion Native Editing Behind Interactive Auth\n\nIf your reverse proxy protects the Sambee backend with an interactive login flow, Companion native editing can still work, but the proxy setup has to satisfy a few constraints.\n\nThe Companion runtime opens its own `Sambee Authentication` webview when reverse-proxy auth intercepts backend API calls. After the user signs in there, Companion reuses backend-origin cookies from that embedded webview for its Rust-side API requests.\n\nFor that to work reliably:\n\n- The reverse-proxy cookie must be valid for the Sambee backend origin that Companion calls.\n- The login flow must work inside the system webview used by Tauri on the target desktop platform.\n- The proxy must not depend on browser features that are unavailable in that embedded webview.\n- The proxy must allow authenticated requests to the Companion backend endpoints after the embedded webview has established the proxy session.\n\n{{\u003c admonition type=\"note\" \u003e}}\nCompanion does not and cannot read cookies from the user\u2019s Sambee frontend browser session.\n{{\u003c /admonition \u003e}}\n\nOperationally, that means you should test both the browser UI and a real Companion native-edit session when introducing or changing proxy auth. A useful native-edit test signs in through the Companion authentication window, opens an SMB-backed file in a desktop app, uploads or closes the edit session, and confirms that lock release works without a second unexpected login prompt.\n", "1.0": "+++\ntitle = \"Put Sambee behind a Reverse Proxy\"\n+++\n\nFor production-style deployments, place a reverse proxy in front of Sambee to handle HTTPS.\n\n## Why Use a Reverse Proxy\n\nA reverse proxy gives you a cleaner operational model for:\n\n- HTTPS and certificate management\n- A stable hostname and routing layer in front of the container\n\n## Caddy Example\n\nIf you already run a dockerized Caddy environment, the Sambee service can be connected to that network with a compose layout like this:\n\n```yaml\nservices:\n  sambee:\n    container_name: sambee\n    hostname: sambee\n    build: .\n    restart: unless-stopped\n    networks:\n      - caddy_caddynet\n    expose:\n      - \"8000\"\n    volumes:\n      - ./data:/app/data\n      # Optional:\n      # - ./config.toml:/app/config.toml:ro\n\nnetworks:\n  caddy_caddynet:\n    external: true\n```\n\nHere, `expose` makes Sambee's port `8000` available to other containers on the same Docker network without publishing it directly to the host.\n\nThe important point is that Sambee serves plain HTTP to the reverse proxy and does not act as the HTTPS edge itself.\n\n## Companion Native Editing Behind Interactive Auth\n\nIf your reverse proxy protects the Sambee backend with an interactive login flow, Companion native editing can still work, but the proxy setup has to satisfy a few constraints.\n\nThe Companion runtime opens its own `Sambee Authentication` webview when reverse-proxy auth intercepts backend API calls. After the user signs in there, Companion reuses backend-origin cookies from that embedded webview for its Rust-side API requests.\n\nFor that to work reliably:\n\n- The reverse-proxy cookie must be valid for the Sambee backend origin that Companion calls.\n- The login flow must work inside the system webview used by Tauri on the target desktop platform.\n- The proxy must not depend on browser features that are unavailable in that embedded webview.\n- The proxy must allow authenticated requests to the Companion backend endpoints after the embedded webview has established the proxy session.\n\n{{\u003c admonition type=\"note\" \u003e}}\nCompanion does not and cannot read cookies from the user\u2019s Sambee frontend browser session.\n{{\u003c /admonition \u003e}}\n\nOperationally, that means you should test both the browser UI and a real Companion native-edit session when introducing or changing proxy auth. A useful native-edit test signs in through the Companion authentication window, opens an SMB-backed file in a desktop app, uploads or closes the edit session, and confirms that lock release works without a second unexpected login prompt.\n", "2.0": "+++\ntitle = \"Put Sambee behind a Reverse Proxy\"\n+++\n\nFor production-style deployments, place a reverse proxy in front of Sambee to handle HTTPS.\n\n## Why Use a Reverse Proxy\n\nA reverse proxy gives you a cleaner operational model for:\n\n- HTTPS and certificate management\n- A stable hostname and routing layer in front of the container\n\n## Caddy Example\n\nIf you already run a dockerized Caddy environment, the Sambee service can be connected to that network with a compose layout like this:\n\n```yaml\nservices:\n  sambee:\n    container_name: sambee\n    hostname: sambee\n    build: .\n    restart: unless-stopped\n    networks:\n      - caddy_caddynet\n    expose:\n      - \"8000\"\n    volumes:\n      - ./data:/app/data\n      # Optional:\n      # - ./config.toml:/app/config.toml:ro\n\nnetworks:\n  caddy_caddynet:\n    external: true\n```\n\nHere, `expose` makes Sambee's port `8000` available to other containers on the same Docker network without publishing it directly to the host.\n\nThe important point is that Sambee serves plain HTTP to the reverse proxy and does not act as the HTTPS edge itself.\n\n## Companion Native Editing Behind Interactive Auth\n\nIf your reverse proxy protects the Sambee backend with an interactive login flow, Companion native editing can still work, but the proxy setup has to satisfy a few constraints.\n\nThe Companion runtime opens its own `Sambee Authentication` webview when reverse-proxy auth intercepts backend API calls. After the user signs in there, Companion reuses backend-origin cookies from that embedded webview for its Rust-side API requests.\n\nFor that to work reliably:\n\n- The reverse-proxy cookie must be valid for the Sambee backend origin that Companion calls.\n- The login flow must work inside the system webview used by Tauri on the target desktop platform.\n- The proxy must not depend on browser features that are unavailable in that embedded webview.\n- The proxy must allow authenticated requests to the Companion backend endpoints after the embedded webview has established the proxy session.\n\n{{\u003c admonition type=\"note\" \u003e}}\nCompanion does not and cannot read cookies from the user\u2019s Sambee frontend browser session.\n{{\u003c /admonition \u003e}}\n\nOperationally, that means you should test both the browser UI and a real Companion native-edit session when introducing or changing proxy auth. A useful native-edit test signs in through the Companion authentication window, opens an SMB-backed file in a desktop app, uploads or closes the edit session, and confirms that lock release works without a second unexpected login prompt.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Put Sambee behind a Reverse Proxy\"\n+++\n\nFor production-style deployments, place a reverse proxy in front of Sambee to handle HTTPS.\n\n## Why Use a Reverse Proxy\n\nA reverse proxy gives you a cleaner operational model for:\n\n- HTTPS and certificate management\n- A stable hostname and routing layer in front of the container\n\n## Caddy Example\n\nIf you already run a dockerized Caddy environment, the Sambee service can be connected to that network with a compose layout like this:\n\n```yaml\nservices:\n  sambee:\n    container_name: sambee\n    hostname: sambee\n    build: .\n    restart: unless-stopped\n    networks:\n      - caddy_caddynet\n    expose:\n      - \"8000\"\n    volumes:\n      - ./data:/app/data\n      # Optional:\n      # - ./config.toml:/app/config.toml:ro\n\nnetworks:\n  caddy_caddynet:\n    external: true\n```\n\nHere, `expose` makes Sambee's port `8000` available to other containers on the same Docker network without publishing it directly to the host.\n\nThe important point is that Sambee serves plain HTTP to the reverse proxy and does not act as the HTTPS edge itself.\n\n## Companion Native Editing Behind Interactive Auth\n\nIf your reverse proxy protects the Sambee backend with an interactive login flow, Companion native editing can still work, but the proxy setup has to satisfy a few constraints.\n\nThe Companion runtime opens its own `Sambee Authentication` webview when reverse-proxy auth intercepts backend API calls. After the user signs in there, Companion reuses backend-origin cookies from that embedded webview for its Rust-side API requests.\n\nFor that to work reliably:\n\n- The reverse-proxy cookie must be valid for the Sambee backend origin that Companion calls.\n- The login flow must work inside the system webview used by Tauri on the target desktop platform.\n- The proxy must not depend on browser features that are unavailable in that embedded webview.\n- The proxy must allow authenticated requests to the Companion backend endpoints after the embedded webview has established the proxy session.\n\n{{\u003c admonition type=\"note\" \u003e}}\nCompanion does not and cannot read cookies from the user\u2019s Sambee frontend browser session.\n{{\u003c /admonition \u003e}}\n\nOperationally, that means you should test both the browser UI and a real Companion native-edit session when introducing or changing proxy auth. A useful native-edit test signs in through the Companion authentication window, opens an SMB-backed file in a desktop app, uploads or closes the edit session, and confirms that lock release works without a second unexpected login prompt.\n", "0.8": "+++\ntitle = \"Put Sambee behind a Reverse Proxy\"\n+++\n\nFor production-style deployments, place a reverse proxy in front of Sambee to handle HTTPS.\n\n## Why Use a Reverse Proxy\n\nA reverse proxy gives you a cleaner operational model for:\n\n- HTTPS and certificate management\n- A stable hostname and routing layer in front of the container\n\n## Caddy Example\n\nIf you already run a dockerized Caddy environment, the Sambee service can be connected to that network with a compose layout like this:\n\n```yaml\nservices:\n  sambee:\n    container_name: sambee\n    hostname: sambee\n    build: .\n    restart: unless-stopped\n    networks:\n      - caddy_caddynet\n    expose:\n      - \"8000\"\n    volumes:\n      - ./data:/app/data\n      # Optional:\n      # - ./config.toml:/app/config.toml:ro\n\nnetworks:\n  caddy_caddynet:\n    external: true\n```\n\nHere, `expose` makes Sambee's port `8000` available to other containers on the same Docker network without publishing it directly to the host.\n\nThe important point is that Sambee serves plain HTTP to the reverse proxy and does not act as the HTTPS edge itself.\n\n## Companion Native Editing Behind Interactive Auth\n\nIf your reverse proxy protects the Sambee backend with an interactive login flow, Companion native editing can still work, but the proxy setup has to satisfy a few constraints.\n\nThe Companion runtime opens its own `Sambee Authentication` webview when reverse-proxy auth intercepts backend API calls. After the user signs in there, Companion reuses backend-origin cookies from that embedded webview for its Rust-side API requests.\n\nFor that to work reliably:\n\n- The reverse-proxy cookie must be valid for the Sambee backend origin that Companion calls.\n- The login flow must work inside the system webview used by Tauri on the target desktop platform.\n- The proxy must not depend on browser features that are unavailable in that embedded webview.\n- The proxy must allow authenticated requests to the Companion backend endpoints after the embedded webview has established the proxy session.\n\n{{\u003c admonition type=\"note\" \u003e}}\nCompanion does not and cannot read cookies from the user\u2019s Sambee frontend browser session.\n{{\u003c /admonition \u003e}}\n\nOperationally, that means you should test both the browser UI and a real Companion native-edit session when introducing or changing proxy auth. A useful native-edit test signs in through the Companion authentication window, opens an SMB-backed file in a desktop app, uploads or closes the edit session, and confirms that lock release works without a second unexpected login prompt.\n", "0.9": "+++\ntitle = \"Put Sambee behind a Reverse Proxy\"\n+++\n\nFor production-style deployments, place a reverse proxy in front of Sambee to handle HTTPS.\n\n## Why Use a Reverse Proxy\n\nA reverse proxy gives you a cleaner operational model for:\n\n- HTTPS and certificate management\n- A stable hostname and routing layer in front of the container\n\n## Caddy Example\n\nIf you already run a dockerized Caddy environment, the Sambee service can be connected to that network with a compose layout like this:\n\n```yaml\nservices:\n  sambee:\n    container_name: sambee\n    hostname: sambee\n    build: .\n    restart: unless-stopped\n    networks:\n      - caddy_caddynet\n    expose:\n      - \"8000\"\n    volumes:\n      - ./data:/app/data\n      # Optional:\n      # - ./config.toml:/app/config.toml:ro\n\nnetworks:\n  caddy_caddynet:\n    external: true\n```\n\nHere, `expose` makes Sambee's port `8000` available to other containers on the same Docker network without publishing it directly to the host.\n\nThe important point is that Sambee serves plain HTTP to the reverse proxy and does not act as the HTTPS edge itself.\n\n## Companion Native Editing Behind Interactive Auth\n\nIf your reverse proxy protects the Sambee backend with an interactive login flow, Companion native editing can still work, but the proxy setup has to satisfy a few constraints.\n\nThe Companion runtime opens its own `Sambee Authentication` webview when reverse-proxy auth intercepts backend API calls. After the user signs in there, Companion reuses backend-origin cookies from that embedded webview for its Rust-side API requests.\n\nFor that to work reliably:\n\n- The reverse-proxy cookie must be valid for the Sambee backend origin that Companion calls.\n- The login flow must work inside the system webview used by Tauri on the target desktop platform.\n- The proxy must not depend on browser features that are unavailable in that embedded webview.\n- The proxy must allow authenticated requests to the Companion backend endpoints after the embedded webview has established the proxy session.\n\n{{\u003c admonition type=\"note\" \u003e}}\nCompanion does not and cannot read cookies from the user\u2019s Sambee frontend browser session.\n{{\u003c /admonition \u003e}}\n\nOperationally, that means you should test both the browser UI and a real Companion native-edit session when introducing or changing proxy auth. A useful native-edit test signs in through the Companion authentication window, opens an SMB-backed file in a desktop app, uploads or closes the edit session, and confirms that lock release works without a second unexpected login prompt.\n", "1.0": "+++\ntitle = \"Put Sambee behind a Reverse Proxy\"\n+++\n\nFor production-style deployments, place a reverse proxy in front of Sambee to handle HTTPS.\n\n## Why Use a Reverse Proxy\n\nA reverse proxy gives you a cleaner operational model for:\n\n- HTTPS and certificate management\n- A stable hostname and routing layer in front of the container\n\n## Caddy Example\n\nIf you already run a dockerized Caddy environment, the Sambee service can be connected to that network with a compose layout like this:\n\n```yaml\nservices:\n  sambee:\n    container_name: sambee\n    hostname: sambee\n    build: .\n    restart: unless-stopped\n    networks:\n      - caddy_caddynet\n    expose:\n      - \"8000\"\n    volumes:\n      - ./data:/app/data\n      # Optional:\n      # - ./config.toml:/app/config.toml:ro\n\nnetworks:\n  caddy_caddynet:\n    external: true\n```\n\nHere, `expose` makes Sambee's port `8000` available to other containers on the same Docker network without publishing it directly to the host.\n\nThe important point is that Sambee serves plain HTTP to the reverse proxy and does not act as the HTTPS edge itself.\n\n## Companion Native Editing Behind Interactive Auth\n\nIf your reverse proxy protects the Sambee backend with an interactive login flow, Companion native editing can still work, but the proxy setup has to satisfy a few constraints.\n\nThe Companion runtime opens its own `Sambee Authentication` webview when reverse-proxy auth intercepts backend API calls. After the user signs in there, Companion reuses backend-origin cookies from that embedded webview for its Rust-side API requests.\n\nFor that to work reliably:\n\n- The reverse-proxy cookie must be valid for the Sambee backend origin that Companion calls.\n- The login flow must work inside the system webview used by Tauri on the target desktop platform.\n- The proxy must not depend on browser features that are unavailable in that embedded webview.\n- The proxy must allow authenticated requests to the Companion backend endpoints after the embedded webview has established the proxy session.\n\n{{\u003c admonition type=\"note\" \u003e}}\nCompanion does not and cannot read cookies from the user\u2019s Sambee frontend browser session.\n{{\u003c /admonition \u003e}}\n\nOperationally, that means you should test both the browser UI and a real Companion native-edit session when introducing or changing proxy auth. A useful native-edit test signs in through the Companion authentication window, opens an SMB-backed file in a desktop app, uploads or closes the edit session, and confirms that lock release works without a second unexpected login prompt.\n", "2.0": "+++\ntitle = \"Put Sambee behind a Reverse Proxy\"\n+++\n\nFor production-style deployments, place a reverse proxy in front of Sambee to handle HTTPS.\n\n## Why Use a Reverse Proxy\n\nA reverse proxy gives you a cleaner operational model for:\n\n- HTTPS and certificate management\n- A stable hostname and routing layer in front of the container\n\n## Caddy Example\n\nIf you already run a dockerized Caddy environment, the Sambee service can be connected to that network with a compose layout like this:\n\n```yaml\nservices:\n  sambee:\n    container_name: sambee\n    hostname: sambee\n    build: .\n    restart: unless-stopped\n    networks:\n      - caddy_caddynet\n    expose:\n      - \"8000\"\n    volumes:\n      - ./data:/app/data\n      # Optional:\n      # - ./config.toml:/app/config.toml:ro\n\nnetworks:\n  caddy_caddynet:\n    external: true\n```\n\nHere, `expose` makes Sambee's port `8000` available to other containers on the same Docker network without publishing it directly to the host.\n\nThe important point is that Sambee serves plain HTTP to the reverse proxy and does not act as the HTTPS edge itself.\n\n## Companion Native Editing Behind Interactive Auth\n\nIf your reverse proxy protects the Sambee backend with an interactive login flow, Companion native editing can still work, but the proxy setup has to satisfy a few constraints.\n\nThe Companion runtime opens its own `Sambee Authentication` webview when reverse-proxy auth intercepts backend API calls. After the user signs in there, Companion reuses backend-origin cookies from that embedded webview for its Rust-side API requests.\n\nFor that to work reliably:\n\n- The reverse-proxy cookie must be valid for the Sambee backend origin that Companion calls.\n- The login flow must work inside the system webview used by Tauri on the target desktop platform.\n- The proxy must not depend on browser features that are unavailable in that embedded webview.\n- The proxy must allow authenticated requests to the Companion backend endpoints after the embedded webview has established the proxy session.\n\n{{\u003c admonition type=\"note\" \u003e}}\nCompanion does not and cannot read cookies from the user\u2019s Sambee frontend browser session.\n{{\u003c /admonition \u003e}}\n\nOperationally, that means you should test both the browser UI and a real Companion native-edit session when introducing or changing proxy auth. A useful native-edit test signs in through the Companion authentication window, opens an SMB-backed file in a desktop app, uploads or closes the edit session, and confirms that lock release works without a second unexpected login prompt.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:admin-guide/network-and-reverse-proxy/network-settings", "parent_id": "section:admin-guide/network-and-reverse-proxy", "depth": 2, "kind": "page", "label": "network-settings", "title": "Network Settings", "path": "admin-guide/network-and-reverse-proxy/network-settings", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "authored"}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "inherited", "source_version": "0.9"}}, "content_versions": {"0.9": "+++\ntitle = \"Network Settings\"\n+++\n\nOpen **Settings** \u003e **Administration** \u003e **Network** to configure the settings Sambee uses for external URLs and reverse-proxy client addresses.\n\n## Public URL\n\nSet **Public URL** to Sambee's externally reachable HTTPS origin, for example:\n\n```text\nhttps://files.example.com\n```\n\nDo not include a path. Changing the public URL cancels incomplete OIDC sign-ins and tests.\n\n## Trusted Reverse Proxy CIDRs\n\nConfigure **Trusted reverse proxy CIDRs** only when all of the following is true:\n\n- A reverse proxy sits in front of Sambee.\n- The proxy forwards the original visitor IP address.\n- You want Sambee to use that address for authentication request limits.\n\nEnter the IP addresses or network ranges of the proxies that connect directly to Sambee. Do not enter end-user networks or arbitrary private ranges.\n\n### Example\n\nIf Nginx at `10.20.30.15` is the only server that can reach Sambee and it forwards `X-Forwarded-For`, enter `10.20.30.15/32`.\n\n", "1.0": "+++\ntitle = \"Network Settings\"\n+++\n\nOpen **Settings** \u003e **Administration** \u003e **Network** to configure the settings Sambee uses for external URLs and reverse-proxy client addresses.\n\n## Public URL\n\nSet **Public URL** to Sambee's externally reachable HTTPS origin, for example:\n\n```text\nhttps://files.example.com\n```\n\nDo not include a path. Changing the public URL cancels incomplete OIDC sign-ins and tests.\n\n## Trusted Reverse Proxy CIDRs\n\nConfigure **Trusted reverse proxy CIDRs** only when all of the following is true:\n\n- A reverse proxy sits in front of Sambee.\n- The proxy forwards the original visitor IP address.\n- You want Sambee to use that address for authentication request limits.\n\nEnter the IP addresses or network ranges of the proxies that connect directly to Sambee. Do not enter end-user networks or arbitrary private ranges.\n\n### Example\n\nIf Nginx at `10.20.30.15` is the only server that can reach Sambee and it forwards `X-Forwarded-For`, enter `10.20.30.15/32`.\n\n", "2.0": "+++\ntitle = \"Network Settings\"\n+++\n\nOpen **Settings** \u003e **Administration** \u003e **Network** to configure the settings Sambee uses for external URLs and reverse-proxy client addresses.\n\n## Public URL\n\nSet **Public URL** to Sambee's externally reachable HTTPS origin, for example:\n\n```text\nhttps://files.example.com\n```\n\nDo not include a path. Changing the public URL cancels incomplete OIDC sign-ins and tests.\n\n## Trusted Reverse Proxy CIDRs\n\nConfigure **Trusted reverse proxy CIDRs** only when all of the following is true:\n\n- A reverse proxy sits in front of Sambee.\n- The proxy forwards the original visitor IP address.\n- You want Sambee to use that address for authentication request limits.\n\nEnter the IP addresses or network ranges of the proxies that connect directly to Sambee. Do not enter end-user networks or arbitrary private ranges.\n\n### Example\n\nIf Nginx at `10.20.30.15` is the only server that can reach Sambee and it forwards `X-Forwarded-For`, enter `10.20.30.15/32`.\n\n"}, "page_contents": {"0.9": "+++\ntitle = \"Network Settings\"\n+++\n\nOpen **Settings** \u003e **Administration** \u003e **Network** to configure the settings Sambee uses for external URLs and reverse-proxy client addresses.\n\n## Public URL\n\nSet **Public URL** to Sambee's externally reachable HTTPS origin, for example:\n\n```text\nhttps://files.example.com\n```\n\nDo not include a path. Changing the public URL cancels incomplete OIDC sign-ins and tests.\n\n## Trusted Reverse Proxy CIDRs\n\nConfigure **Trusted reverse proxy CIDRs** only when all of the following is true:\n\n- A reverse proxy sits in front of Sambee.\n- The proxy forwards the original visitor IP address.\n- You want Sambee to use that address for authentication request limits.\n\nEnter the IP addresses or network ranges of the proxies that connect directly to Sambee. Do not enter end-user networks or arbitrary private ranges.\n\n### Example\n\nIf Nginx at `10.20.30.15` is the only server that can reach Sambee and it forwards `X-Forwarded-For`, enter `10.20.30.15/32`.\n\n", "1.0": "+++\ntitle = \"Network Settings\"\n+++\n\nOpen **Settings** \u003e **Administration** \u003e **Network** to configure the settings Sambee uses for external URLs and reverse-proxy client addresses.\n\n## Public URL\n\nSet **Public URL** to Sambee's externally reachable HTTPS origin, for example:\n\n```text\nhttps://files.example.com\n```\n\nDo not include a path. Changing the public URL cancels incomplete OIDC sign-ins and tests.\n\n## Trusted Reverse Proxy CIDRs\n\nConfigure **Trusted reverse proxy CIDRs** only when all of the following is true:\n\n- A reverse proxy sits in front of Sambee.\n- The proxy forwards the original visitor IP address.\n- You want Sambee to use that address for authentication request limits.\n\nEnter the IP addresses or network ranges of the proxies that connect directly to Sambee. Do not enter end-user networks or arbitrary private ranges.\n\n### Example\n\nIf Nginx at `10.20.30.15` is the only server that can reach Sambee and it forwards `X-Forwarded-For`, enter `10.20.30.15/32`.\n\n", "2.0": "+++\ntitle = \"Network Settings\"\n+++\n\nOpen **Settings** \u003e **Administration** \u003e **Network** to configure the settings Sambee uses for external URLs and reverse-proxy client addresses.\n\n## Public URL\n\nSet **Public URL** to Sambee's externally reachable HTTPS origin, for example:\n\n```text\nhttps://files.example.com\n```\n\nDo not include a path. Changing the public URL cancels incomplete OIDC sign-ins and tests.\n\n## Trusted Reverse Proxy CIDRs\n\nConfigure **Trusted reverse proxy CIDRs** only when all of the following is true:\n\n- A reverse proxy sits in front of Sambee.\n- The proxy forwards the original visitor IP address.\n- You want Sambee to use that address for authentication request limits.\n\nEnter the IP addresses or network ranges of the proxies that connect directly to Sambee. Do not enter end-user networks or arbitrary private ranges.\n\n### Example\n\nIf Nginx at `10.20.30.15` is the only server that can reach Sambee and it forwards `X-Forwarded-For`, enter `10.20.30.15/32`.\n\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:admin-guide/configuration", "parent_id": "book:admin-guide", "depth": 1, "kind": "section", "label": "configuration", "title": "Configuration", "path": "admin-guide/configuration", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "missing"}, "1.0": {"state": "missing"}, "2.0": {"state": "missing"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:admin-guide/configuration/configuration-key-reference", "parent_id": "section:admin-guide/configuration", "depth": 2, "kind": "page", "label": "configuration-key-reference", "title": "Configuration Key Reference", "path": "admin-guide/configuration/configuration-key-reference", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "missing"}, "1.0": {"state": "missing"}, "2.0": {"state": "missing"}}, "content_versions": {"0.7": "+++\ntitle = \"Configuration Key Reference\"\n+++\n\nThis page is a compact map of the optional `config.toml` file.\n\nUse `config.example.toml` as the source of truth for supported keys. This page explains the sections that matter most in day-to-day administration.\n\n## How to Use This Reference\n\n- Copy only the keys you actually need into the local `config.toml`.\n- Keep the file local to the deployment and mount it read-only in production.\n- Treat commented defaults in `config.example.toml` as the baseline behavior unless you override them intentionally.\n- Expect most basic deployments to use only a small subset of these keys.\n\n## High-Value Sections and Keys\n\n| Section | Key | Operational effect |\n|---|---|---|\n| `[app]` | `log_level` | Sets backend log verbosity |\n| `[security]` | `auth_method` | Chooses between built-in password auth and proxy-managed auth |\n| `[security]` | `access_token_expire_minutes` | Changes session-token lifetime |\n| `[admin]` | `username` | Sets the initial administrator username |\n| `[image_viewer]` | `conv_size_thresh` | Controls when large images are always converted for viewing |\n| `[frontend_logging]` | `logging_enabled`, `log_level` | Controls browser-console logging behavior |\n| `[frontend_logging]` | `tracing_enabled`, `tracing_level`, `tracing_retention_hours` | Controls backend trace collection for frontend logging |\n| `[frontend_logging]` | `tracing_components`, `tracing_username_regex` | Restricts tracing by component or user scope |\n| `[directory_cache]` | `location`, `coalesce_interval_seconds`, `max_staleness_minutes` | Controls the saved directory index Sambee keeps to make browsing and search recover faster after restarts |\n| `[smb]` | `read_chunk_size_bytes` | Changes SMB read chunk size |\n| `[preprocessors.imagemagick]` | `max_file_size_bytes`, `timeout_seconds` | Sets conversion limits for ImageMagick preprocessing |\n| `[companion_downloads]` | `metadata_feed_url` | Changes where Sambee resolves Companion download metadata |\n| `[companion_downloads.pin]` | `version`, `published_at`, `notes`, asset URLs | Pins Companion download links to a specific published release instead of following the promoted feed |\n\n## Keys That Deserve Extra Care\n\nThese areas have the highest operational impact:\n\n- `auth_method`: Can change who is responsible for authentication at the deployment boundary.\n- Frontend logging and tracing keys: Can change both local debugging visibility and backend trace collection volume.\n- `directory_cache.location`: Changes where the saved SMB directory index lives on disk.\n- Companion download keys: Change what download links Sambee presents to users.\n", "0.8": "+++\ntitle = \"Configuration Key Reference\"\n+++\n\nThis page is a compact map of the optional `config.toml` file.\n\nUse `config.example.toml` as the source of truth for supported keys. This page explains the sections that matter most in day-to-day administration.\n\n## How to Use This Reference\n\n- Copy only the keys you actually need into the local `config.toml`.\n- Keep the file local to the deployment and mount it read-only in production.\n- Treat commented defaults in `config.example.toml` as the baseline behavior unless you override them intentionally.\n- Expect most basic deployments to use only a small subset of these keys.\n\n## High-Value Sections and Keys\n\n| Section | Key | Operational effect |\n|---|---|---|\n| `[app]` | `log_level` | Sets backend log verbosity |\n| `[security]` | `auth_method` | Chooses between built-in password auth and proxy-managed auth |\n| `[security]` | `access_token_expire_minutes` | Changes session-token lifetime |\n| `[admin]` | `username` | Sets the initial administrator username |\n| `[image_viewer]` | `conv_size_thresh` | Controls when large images are always converted for viewing |\n| `[frontend_logging]` | `logging_enabled`, `log_level` | Controls browser-console logging behavior |\n| `[frontend_logging]` | `tracing_enabled`, `tracing_level`, `tracing_retention_hours` | Controls backend trace collection for frontend logging |\n| `[frontend_logging]` | `tracing_components`, `tracing_username_regex` | Restricts tracing by component or user scope |\n| `[directory_cache]` | `location`, `coalesce_interval_seconds`, `max_staleness_minutes` | Controls the saved directory index Sambee keeps to make browsing and search recover faster after restarts |\n| `[smb]` | `read_chunk_size_bytes` | Changes SMB read chunk size |\n| `[preprocessors.imagemagick]` | `max_file_size_bytes`, `timeout_seconds` | Sets conversion limits for ImageMagick preprocessing |\n| `[companion_downloads]` | `metadata_feed_url` | Changes where Sambee resolves Companion download metadata |\n| `[companion_downloads.pin]` | `version`, `published_at`, `notes`, asset URLs | Pins Companion download links to a specific published release instead of following the promoted feed |\n\n## Keys That Deserve Extra Care\n\nThese areas have the highest operational impact:\n\n- `auth_method`: Can change who is responsible for authentication at the deployment boundary.\n- Frontend logging and tracing keys: Can change both local debugging visibility and backend trace collection volume.\n- `directory_cache.location`: Changes where the saved SMB directory index lives on disk.\n- Companion download keys: Change what download links Sambee presents to users.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Configuration Key Reference\"\n+++\n\nThis page is a compact map of the optional `config.toml` file.\n\nUse `config.example.toml` as the source of truth for supported keys. This page explains the sections that matter most in day-to-day administration.\n\n## How to Use This Reference\n\n- Copy only the keys you actually need into the local `config.toml`.\n- Keep the file local to the deployment and mount it read-only in production.\n- Treat commented defaults in `config.example.toml` as the baseline behavior unless you override them intentionally.\n- Expect most basic deployments to use only a small subset of these keys.\n\n## High-Value Sections and Keys\n\n| Section | Key | Operational effect |\n|---|---|---|\n| `[app]` | `log_level` | Sets backend log verbosity |\n| `[security]` | `auth_method` | Chooses between built-in password auth and proxy-managed auth |\n| `[security]` | `access_token_expire_minutes` | Changes session-token lifetime |\n| `[admin]` | `username` | Sets the initial administrator username |\n| `[image_viewer]` | `conv_size_thresh` | Controls when large images are always converted for viewing |\n| `[frontend_logging]` | `logging_enabled`, `log_level` | Controls browser-console logging behavior |\n| `[frontend_logging]` | `tracing_enabled`, `tracing_level`, `tracing_retention_hours` | Controls backend trace collection for frontend logging |\n| `[frontend_logging]` | `tracing_components`, `tracing_username_regex` | Restricts tracing by component or user scope |\n| `[directory_cache]` | `location`, `coalesce_interval_seconds`, `max_staleness_minutes` | Controls the saved directory index Sambee keeps to make browsing and search recover faster after restarts |\n| `[smb]` | `read_chunk_size_bytes` | Changes SMB read chunk size |\n| `[preprocessors.imagemagick]` | `max_file_size_bytes`, `timeout_seconds` | Sets conversion limits for ImageMagick preprocessing |\n| `[companion_downloads]` | `metadata_feed_url` | Changes where Sambee resolves Companion download metadata |\n| `[companion_downloads.pin]` | `version`, `published_at`, `notes`, asset URLs | Pins Companion download links to a specific published release instead of following the promoted feed |\n\n## Keys That Deserve Extra Care\n\nThese areas have the highest operational impact:\n\n- `auth_method`: Can change who is responsible for authentication at the deployment boundary.\n- Frontend logging and tracing keys: Can change both local debugging visibility and backend trace collection volume.\n- `directory_cache.location`: Changes where the saved SMB directory index lives on disk.\n- Companion download keys: Change what download links Sambee presents to users.\n", "0.8": "+++\ntitle = \"Configuration Key Reference\"\n+++\n\nThis page is a compact map of the optional `config.toml` file.\n\nUse `config.example.toml` as the source of truth for supported keys. This page explains the sections that matter most in day-to-day administration.\n\n## How to Use This Reference\n\n- Copy only the keys you actually need into the local `config.toml`.\n- Keep the file local to the deployment and mount it read-only in production.\n- Treat commented defaults in `config.example.toml` as the baseline behavior unless you override them intentionally.\n- Expect most basic deployments to use only a small subset of these keys.\n\n## High-Value Sections and Keys\n\n| Section | Key | Operational effect |\n|---|---|---|\n| `[app]` | `log_level` | Sets backend log verbosity |\n| `[security]` | `auth_method` | Chooses between built-in password auth and proxy-managed auth |\n| `[security]` | `access_token_expire_minutes` | Changes session-token lifetime |\n| `[admin]` | `username` | Sets the initial administrator username |\n| `[image_viewer]` | `conv_size_thresh` | Controls when large images are always converted for viewing |\n| `[frontend_logging]` | `logging_enabled`, `log_level` | Controls browser-console logging behavior |\n| `[frontend_logging]` | `tracing_enabled`, `tracing_level`, `tracing_retention_hours` | Controls backend trace collection for frontend logging |\n| `[frontend_logging]` | `tracing_components`, `tracing_username_regex` | Restricts tracing by component or user scope |\n| `[directory_cache]` | `location`, `coalesce_interval_seconds`, `max_staleness_minutes` | Controls the saved directory index Sambee keeps to make browsing and search recover faster after restarts |\n| `[smb]` | `read_chunk_size_bytes` | Changes SMB read chunk size |\n| `[preprocessors.imagemagick]` | `max_file_size_bytes`, `timeout_seconds` | Sets conversion limits for ImageMagick preprocessing |\n| `[companion_downloads]` | `metadata_feed_url` | Changes where Sambee resolves Companion download metadata |\n| `[companion_downloads.pin]` | `version`, `published_at`, `notes`, asset URLs | Pins Companion download links to a specific published release instead of following the promoted feed |\n\n## Keys That Deserve Extra Care\n\nThese areas have the highest operational impact:\n\n- `auth_method`: Can change who is responsible for authentication at the deployment boundary.\n- Frontend logging and tracing keys: Can change both local debugging visibility and backend trace collection volume.\n- `directory_cache.location`: Changes where the saved SMB directory index lives on disk.\n- Companion download keys: Change what download links Sambee presents to users.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:admin-guide/operations-and-maintenance", "parent_id": "book:admin-guide", "depth": 1, "kind": "section", "label": "operations-and-maintenance", "title": "Operations and Maintenance", "path": "admin-guide/operations-and-maintenance", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:admin-guide/operations-and-maintenance/view-logs-and-restart-services", "parent_id": "section:admin-guide/operations-and-maintenance", "depth": 2, "kind": "page", "label": "view-logs-and-restart-services", "title": "View Logs And Restart Services", "path": "admin-guide/operations-and-maintenance/view-logs-and-restart-services", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"View Logs and Restart Services\"\n+++\n\nOnce Sambee is in service, logs and controlled restarts are the core day-to-day admin tools.\n\n## View Logs\n\nTo follow logs for all services:\n\n```bash\ndocker compose logs -f\n```\n\nTo focus on the Sambee service only:\n\n```bash\ndocker compose logs -f sambee\n```\n\nUse the service-specific view first when the issue is clearly about the application itself.\n\nIf you only need recent startup output, use:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\n## Stop the Deployment\n\nTo stop the services:\n\n```bash\ndocker compose down\n```\n\nUse a full stop when you need to perform controlled maintenance, rebuild the image, or restore deployment files.\n\n## Restart as Part of Operations\n\nRoutine restarts are not a substitute for troubleshooting, but they are a legitimate step when:\n\n- You just changed deployment files.\n- You rebuilt the image.\n- You completed a controlled maintenance step.\n\nTo restart only the Sambee service:\n\n```bash\ndocker compose restart sambee\n```\n\nIf you restart repeatedly without understanding the failure, stop restarting and inspect the logs, deployment files, proxy path, and persistent data assumptions directly.\n", "0.8": "+++\ntitle = \"View Logs and Restart Services\"\n+++\n\nOnce Sambee is in service, logs and controlled restarts are the core day-to-day admin tools.\n\n## View Logs\n\nTo follow logs for all services:\n\n```bash\ndocker compose logs -f\n```\n\nTo focus on the Sambee service only:\n\n```bash\ndocker compose logs -f sambee\n```\n\nUse the service-specific view first when the issue is clearly about the application itself.\n\nIf you only need recent startup output, use:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\n## Stop the Deployment\n\nTo stop the services:\n\n```bash\ndocker compose down\n```\n\nUse a full stop when you need to perform controlled maintenance, rebuild the image, or restore deployment files.\n\n## Restart as Part of Operations\n\nRoutine restarts are not a substitute for troubleshooting, but they are a legitimate step when:\n\n- You just changed deployment files.\n- You rebuilt the image.\n- You completed a controlled maintenance step.\n\nTo restart only the Sambee service:\n\n```bash\ndocker compose restart sambee\n```\n\nIf you restart repeatedly without understanding the failure, stop restarting and inspect the logs, deployment files, proxy path, and persistent data assumptions directly.\n", "0.9": "+++\ntitle = \"View Logs and Restart Services\"\n+++\n\nOnce Sambee is in service, logs and controlled restarts are the core day-to-day admin tools.\n\n## View Logs\n\nTo follow logs for all services:\n\n```bash\ndocker compose logs -f\n```\n\nTo focus on the Sambee service only:\n\n```bash\ndocker compose logs -f sambee\n```\n\nUse the service-specific view first when the issue is clearly about the application itself.\n\nIf you only need recent startup output, use:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\n## Stop the Deployment\n\nTo stop the services:\n\n```bash\ndocker compose down\n```\n\nUse a full stop when you need to perform controlled maintenance, rebuild the image, or restore deployment files.\n\n## Restart as Part of Operations\n\nRoutine restarts are not a substitute for troubleshooting, but they are a legitimate step when:\n\n- You just changed deployment files.\n- You rebuilt the image.\n- You completed a controlled maintenance step.\n\nTo restart only the Sambee service:\n\n```bash\ndocker compose restart sambee\n```\n\nIf you restart repeatedly without understanding the failure, stop restarting and inspect the logs, deployment files, proxy path, and persistent data assumptions directly.\n", "1.0": "+++\ntitle = \"View Logs and Restart Services\"\n+++\n\nOnce Sambee is in service, logs and controlled restarts are the core day-to-day admin tools.\n\n## View Logs\n\nTo follow logs for all services:\n\n```bash\ndocker compose logs -f\n```\n\nTo focus on the Sambee service only:\n\n```bash\ndocker compose logs -f sambee\n```\n\nUse the service-specific view first when the issue is clearly about the application itself.\n\nIf you only need recent startup output, use:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\n## Stop the Deployment\n\nTo stop the services:\n\n```bash\ndocker compose down\n```\n\nUse a full stop when you need to perform controlled maintenance, rebuild the image, or restore deployment files.\n\n## Restart as Part of Operations\n\nRoutine restarts are not a substitute for troubleshooting, but they are a legitimate step when:\n\n- You just changed deployment files.\n- You rebuilt the image.\n- You completed a controlled maintenance step.\n\nTo restart only the Sambee service:\n\n```bash\ndocker compose restart sambee\n```\n\nIf you restart repeatedly without understanding the failure, stop restarting and inspect the logs, deployment files, proxy path, and persistent data assumptions directly.\n", "2.0": "+++\ntitle = \"View Logs and Restart Services\"\n+++\n\nOnce Sambee is in service, logs and controlled restarts are the core day-to-day admin tools.\n\n## View Logs\n\nTo follow logs for all services:\n\n```bash\ndocker compose logs -f\n```\n\nTo focus on the Sambee service only:\n\n```bash\ndocker compose logs -f sambee\n```\n\nUse the service-specific view first when the issue is clearly about the application itself.\n\nIf you only need recent startup output, use:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\n## Stop the Deployment\n\nTo stop the services:\n\n```bash\ndocker compose down\n```\n\nUse a full stop when you need to perform controlled maintenance, rebuild the image, or restore deployment files.\n\n## Restart as Part of Operations\n\nRoutine restarts are not a substitute for troubleshooting, but they are a legitimate step when:\n\n- You just changed deployment files.\n- You rebuilt the image.\n- You completed a controlled maintenance step.\n\nTo restart only the Sambee service:\n\n```bash\ndocker compose restart sambee\n```\n\nIf you restart repeatedly without understanding the failure, stop restarting and inspect the logs, deployment files, proxy path, and persistent data assumptions directly.\n"}, "page_contents": {"0.7": "+++\ntitle = \"View Logs and Restart Services\"\n+++\n\nOnce Sambee is in service, logs and controlled restarts are the core day-to-day admin tools.\n\n## View Logs\n\nTo follow logs for all services:\n\n```bash\ndocker compose logs -f\n```\n\nTo focus on the Sambee service only:\n\n```bash\ndocker compose logs -f sambee\n```\n\nUse the service-specific view first when the issue is clearly about the application itself.\n\nIf you only need recent startup output, use:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\n## Stop the Deployment\n\nTo stop the services:\n\n```bash\ndocker compose down\n```\n\nUse a full stop when you need to perform controlled maintenance, rebuild the image, or restore deployment files.\n\n## Restart as Part of Operations\n\nRoutine restarts are not a substitute for troubleshooting, but they are a legitimate step when:\n\n- You just changed deployment files.\n- You rebuilt the image.\n- You completed a controlled maintenance step.\n\nTo restart only the Sambee service:\n\n```bash\ndocker compose restart sambee\n```\n\nIf you restart repeatedly without understanding the failure, stop restarting and inspect the logs, deployment files, proxy path, and persistent data assumptions directly.\n", "0.8": "+++\ntitle = \"View Logs and Restart Services\"\n+++\n\nOnce Sambee is in service, logs and controlled restarts are the core day-to-day admin tools.\n\n## View Logs\n\nTo follow logs for all services:\n\n```bash\ndocker compose logs -f\n```\n\nTo focus on the Sambee service only:\n\n```bash\ndocker compose logs -f sambee\n```\n\nUse the service-specific view first when the issue is clearly about the application itself.\n\nIf you only need recent startup output, use:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\n## Stop the Deployment\n\nTo stop the services:\n\n```bash\ndocker compose down\n```\n\nUse a full stop when you need to perform controlled maintenance, rebuild the image, or restore deployment files.\n\n## Restart as Part of Operations\n\nRoutine restarts are not a substitute for troubleshooting, but they are a legitimate step when:\n\n- You just changed deployment files.\n- You rebuilt the image.\n- You completed a controlled maintenance step.\n\nTo restart only the Sambee service:\n\n```bash\ndocker compose restart sambee\n```\n\nIf you restart repeatedly without understanding the failure, stop restarting and inspect the logs, deployment files, proxy path, and persistent data assumptions directly.\n", "0.9": "+++\ntitle = \"View Logs and Restart Services\"\n+++\n\nOnce Sambee is in service, logs and controlled restarts are the core day-to-day admin tools.\n\n## View Logs\n\nTo follow logs for all services:\n\n```bash\ndocker compose logs -f\n```\n\nTo focus on the Sambee service only:\n\n```bash\ndocker compose logs -f sambee\n```\n\nUse the service-specific view first when the issue is clearly about the application itself.\n\nIf you only need recent startup output, use:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\n## Stop the Deployment\n\nTo stop the services:\n\n```bash\ndocker compose down\n```\n\nUse a full stop when you need to perform controlled maintenance, rebuild the image, or restore deployment files.\n\n## Restart as Part of Operations\n\nRoutine restarts are not a substitute for troubleshooting, but they are a legitimate step when:\n\n- You just changed deployment files.\n- You rebuilt the image.\n- You completed a controlled maintenance step.\n\nTo restart only the Sambee service:\n\n```bash\ndocker compose restart sambee\n```\n\nIf you restart repeatedly without understanding the failure, stop restarting and inspect the logs, deployment files, proxy path, and persistent data assumptions directly.\n", "1.0": "+++\ntitle = \"View Logs and Restart Services\"\n+++\n\nOnce Sambee is in service, logs and controlled restarts are the core day-to-day admin tools.\n\n## View Logs\n\nTo follow logs for all services:\n\n```bash\ndocker compose logs -f\n```\n\nTo focus on the Sambee service only:\n\n```bash\ndocker compose logs -f sambee\n```\n\nUse the service-specific view first when the issue is clearly about the application itself.\n\nIf you only need recent startup output, use:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\n## Stop the Deployment\n\nTo stop the services:\n\n```bash\ndocker compose down\n```\n\nUse a full stop when you need to perform controlled maintenance, rebuild the image, or restore deployment files.\n\n## Restart as Part of Operations\n\nRoutine restarts are not a substitute for troubleshooting, but they are a legitimate step when:\n\n- You just changed deployment files.\n- You rebuilt the image.\n- You completed a controlled maintenance step.\n\nTo restart only the Sambee service:\n\n```bash\ndocker compose restart sambee\n```\n\nIf you restart repeatedly without understanding the failure, stop restarting and inspect the logs, deployment files, proxy path, and persistent data assumptions directly.\n", "2.0": "+++\ntitle = \"View Logs and Restart Services\"\n+++\n\nOnce Sambee is in service, logs and controlled restarts are the core day-to-day admin tools.\n\n## View Logs\n\nTo follow logs for all services:\n\n```bash\ndocker compose logs -f\n```\n\nTo focus on the Sambee service only:\n\n```bash\ndocker compose logs -f sambee\n```\n\nUse the service-specific view first when the issue is clearly about the application itself.\n\nIf you only need recent startup output, use:\n\n```bash\ndocker compose logs sambee --tail 100\n```\n\n## Stop the Deployment\n\nTo stop the services:\n\n```bash\ndocker compose down\n```\n\nUse a full stop when you need to perform controlled maintenance, rebuild the image, or restore deployment files.\n\n## Restart as Part of Operations\n\nRoutine restarts are not a substitute for troubleshooting, but they are a legitimate step when:\n\n- You just changed deployment files.\n- You rebuilt the image.\n- You completed a controlled maintenance step.\n\nTo restart only the Sambee service:\n\n```bash\ndocker compose restart sambee\n```\n\nIf you restart repeatedly without understanding the failure, stop restarting and inspect the logs, deployment files, proxy path, and persistent data assumptions directly.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:admin-guide/operations-and-maintenance/update-sambee-safely", "parent_id": "section:admin-guide/operations-and-maintenance", "depth": 2, "kind": "page", "label": "update-sambee-safely", "title": "Update Sambee Safely", "path": "admin-guide/operations-and-maintenance/update-sambee-safely", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "branched", "source_version": "0.7", "diff_added": 24, "diff_removed": 0}, "2.0": {"state": "inherited", "source_version": "1.0"}}, "content_versions": {"0.7": "+++\ntitle = \"Update Sambee Safely\"\n+++\n\nUpdates should be deliberate. Do not upgrade production from the current branch tip.\n\n## Recommended Update Flow\n\nFetch the available tags and move to the release you intend to deploy:\n\n```bash\ngit fetch --tags\ngit checkout \u003crelease-tag\u003e\ndocker compose down\ndocker compose build --pull --no-cache\ndocker compose up -d\n```\n\n## Why This Flow Matters\n\nThis sequence makes the deployed version explicit and avoids drifting forward to whatever changed upstream most recently.\n\nIt also gives you a clean rebuild point instead of assuming the currently cached image still matches your operational intent.\n\n## Before You Upgrade\n\nBefore performing an update, confirm:\n\n- You know exactly which version you are moving to.\n- Your backup posture is acceptable.\n- Any local deployment files such as `docker-compose.yml` and optional `config.toml` are in the state you expect.\n\n## After You Upgrade\n\nAfter the new version is up:\n\n- Confirm that the frontend loads.\n- Confirm that you can sign in as expected.\n- Confirm that key SMB workflows still work.\n- Check logs for obvious startup regressions.\n\n## Verify the Upgraded Deployment\n\nTreat upgrade verification as part of the upgrade, not as optional follow-up.\n\nAt minimum, confirm:\n\n- You are on the intended release tag or commit.\n- The `docker compose ps` output shows the service healthy.\n- The frontend and sign-in path still work.\n- Key SMB workflows still behave as expected.\n- The recent logs do not show an obvious startup or migration regression.\n\nIf the service does not return cleanly after the update, stop changing versions and inspect the deployment state, recent logs, proxy path, and persistent data assumptions before proceeding.\n", "0.8": "+++\ntitle = \"Update Sambee Safely\"\n+++\n\nUpdates should be deliberate. Do not upgrade production from the current branch tip.\n\n## Recommended Update Flow\n\nFetch the available tags and move to the release you intend to deploy:\n\n```bash\ngit fetch --tags\ngit checkout \u003crelease-tag\u003e\ndocker compose down\ndocker compose build --pull --no-cache\ndocker compose up -d\n```\n\n## Why This Flow Matters\n\nThis sequence makes the deployed version explicit and avoids drifting forward to whatever changed upstream most recently.\n\nIt also gives you a clean rebuild point instead of assuming the currently cached image still matches your operational intent.\n\n## Before You Upgrade\n\nBefore performing an update, confirm:\n\n- You know exactly which version you are moving to.\n- Your backup posture is acceptable.\n- Any local deployment files such as `docker-compose.yml` and optional `config.toml` are in the state you expect.\n\n## After You Upgrade\n\nAfter the new version is up:\n\n- Confirm that the frontend loads.\n- Confirm that you can sign in as expected.\n- Confirm that key SMB workflows still work.\n- Check logs for obvious startup regressions.\n\n## Verify the Upgraded Deployment\n\nTreat upgrade verification as part of the upgrade, not as optional follow-up.\n\nAt minimum, confirm:\n\n- You are on the intended release tag or commit.\n- The `docker compose ps` output shows the service healthy.\n- The frontend and sign-in path still work.\n- Key SMB workflows still behave as expected.\n- The recent logs do not show an obvious startup or migration regression.\n\nIf the service does not return cleanly after the update, stop changing versions and inspect the deployment state, recent logs, proxy path, and persistent data assumptions before proceeding.\n", "0.9": "+++\ntitle = \"Update Sambee Safely\"\n+++\n\nUpdates should be deliberate. Do not upgrade production from the current branch tip.\n\n## Recommended Update Flow\n\nFetch the available tags and move to the release you intend to deploy:\n\n```bash\ngit fetch --tags\ngit checkout \u003crelease-tag\u003e\ndocker compose down\ndocker compose build --pull --no-cache\ndocker compose up -d\n```\n\n## Why This Flow Matters\n\nThis sequence makes the deployed version explicit and avoids drifting forward to whatever changed upstream most recently.\n\nIt also gives you a clean rebuild point instead of assuming the currently cached image still matches your operational intent.\n\n## Before You Upgrade\n\nBefore performing an update, confirm:\n\n- You know exactly which version you are moving to.\n- Your backup posture is acceptable.\n- Any local deployment files such as `docker-compose.yml` and optional `config.toml` are in the state you expect.\n\n## After You Upgrade\n\nAfter the new version is up:\n\n- Confirm that the frontend loads.\n- Confirm that you can sign in as expected.\n- Confirm that key SMB workflows still work.\n- Check logs for obvious startup regressions.\n\n## Verify the Upgraded Deployment\n\nTreat upgrade verification as part of the upgrade, not as optional follow-up.\n\nAt minimum, confirm:\n\n- You are on the intended release tag or commit.\n- The `docker compose ps` output shows the service healthy.\n- The frontend and sign-in path still work.\n- Key SMB workflows still behave as expected.\n- The recent logs do not show an obvious startup or migration regression.\n\nIf the service does not return cleanly after the update, stop changing versions and inspect the deployment state, recent logs, proxy path, and persistent data assumptions before proceeding.\n", "1.0": "+++\ntitle = \"Update Sambee Safely\"\n+++\n\nUpdates should be deliberate. Do not upgrade production from the current branch tip.\n\n## Recommended Update Flow\n\nFetch the available tags and move to the release you intend to deploy:\n\n```bash\ngit fetch --tags\ngit checkout \u003crelease-tag\u003e\ndocker compose down\ndocker compose build --pull --no-cache\ndocker compose up -d\n```\n\n## Archive V2 Cutover\n\nThe Archive V2 release does not retain interrupted Archive V1 work. Complete this one-time procedure before starting the new image when the preflight reports legacy archive operations.\n\n1. Stop Sambee and make a cold backup of `data/`, `docker-compose.yml`, and `config.toml` if you use one.\n1. Run the V2 preflight against the deployment's mounted database:\n\n   ```bash\n   docker compose run --rm --entrypoint /app/scripts/preflight-archive-v2-cutover sambee\n   ```\n\n1. If the preflight lists legacy operations, review the output. Those operations cannot be resumed after the cutover.\n1. Explicitly discard only the listed legacy archive operations:\n\n   ```bash\n   docker compose run --rm --entrypoint /app/scripts/reset-archive-v2-cutover-state sambee \\\n     --confirm-discard-legacy-archive-state\n   ```\n\n1. Run the preflight again. Continue only when it reports `\"ready\": true`.\n1. Start the new image with `docker compose up -d`. Startup runs the preflight again before applying database migrations.\n\nDo not run the reset command while an older Sambee backend can still create archive operations. The command affects only legacy archive-operation state; it does not reset users, connections, or other application data.\n\n## Why This Flow Matters\n\nThis sequence makes the deployed version explicit and avoids drifting forward to whatever changed upstream most recently.\n\nIt also gives you a clean rebuild point instead of assuming the currently cached image still matches your operational intent.\n\n## Before You Upgrade\n\nBefore performing an update, confirm:\n\n- You know exactly which version you are moving to.\n- Your backup posture is acceptable.\n- Any local deployment files such as `docker-compose.yml` and optional `config.toml` are in the state you expect.\n\n## After You Upgrade\n\nAfter the new version is up:\n\n- Confirm that the frontend loads.\n- Confirm that you can sign in as expected.\n- Confirm that key SMB workflows still work.\n- Check logs for obvious startup regressions.\n\n## Verify the Upgraded Deployment\n\nTreat upgrade verification as part of the upgrade, not as optional follow-up.\n\nAt minimum, confirm:\n\n- You are on the intended release tag or commit.\n- The `docker compose ps` output shows the service healthy.\n- The frontend and sign-in path still work.\n- Key SMB workflows still behave as expected.\n- The recent logs do not show an obvious startup or migration regression.\n\nIf the service does not return cleanly after the update, stop changing versions and inspect the deployment state, recent logs, proxy path, and persistent data assumptions before proceeding.", "2.0": "+++\ntitle = \"Update Sambee Safely\"\n+++\n\nUpdates should be deliberate. Do not upgrade production from the current branch tip.\n\n## Recommended Update Flow\n\nFetch the available tags and move to the release you intend to deploy:\n\n```bash\ngit fetch --tags\ngit checkout \u003crelease-tag\u003e\ndocker compose down\ndocker compose build --pull --no-cache\ndocker compose up -d\n```\n\n## Archive V2 Cutover\n\nThe Archive V2 release does not retain interrupted Archive V1 work. Complete this one-time procedure before starting the new image when the preflight reports legacy archive operations.\n\n1. Stop Sambee and make a cold backup of `data/`, `docker-compose.yml`, and `config.toml` if you use one.\n1. Run the V2 preflight against the deployment's mounted database:\n\n   ```bash\n   docker compose run --rm --entrypoint /app/scripts/preflight-archive-v2-cutover sambee\n   ```\n\n1. If the preflight lists legacy operations, review the output. Those operations cannot be resumed after the cutover.\n1. Explicitly discard only the listed legacy archive operations:\n\n   ```bash\n   docker compose run --rm --entrypoint /app/scripts/reset-archive-v2-cutover-state sambee \\\n     --confirm-discard-legacy-archive-state\n   ```\n\n1. Run the preflight again. Continue only when it reports `\"ready\": true`.\n1. Start the new image with `docker compose up -d`. Startup runs the preflight again before applying database migrations.\n\nDo not run the reset command while an older Sambee backend can still create archive operations. The command affects only legacy archive-operation state; it does not reset users, connections, or other application data.\n\n## Why This Flow Matters\n\nThis sequence makes the deployed version explicit and avoids drifting forward to whatever changed upstream most recently.\n\nIt also gives you a clean rebuild point instead of assuming the currently cached image still matches your operational intent.\n\n## Before You Upgrade\n\nBefore performing an update, confirm:\n\n- You know exactly which version you are moving to.\n- Your backup posture is acceptable.\n- Any local deployment files such as `docker-compose.yml` and optional `config.toml` are in the state you expect.\n\n## After You Upgrade\n\nAfter the new version is up:\n\n- Confirm that the frontend loads.\n- Confirm that you can sign in as expected.\n- Confirm that key SMB workflows still work.\n- Check logs for obvious startup regressions.\n\n## Verify the Upgraded Deployment\n\nTreat upgrade verification as part of the upgrade, not as optional follow-up.\n\nAt minimum, confirm:\n\n- You are on the intended release tag or commit.\n- The `docker compose ps` output shows the service healthy.\n- The frontend and sign-in path still work.\n- Key SMB workflows still behave as expected.\n- The recent logs do not show an obvious startup or migration regression.\n\nIf the service does not return cleanly after the update, stop changing versions and inspect the deployment state, recent logs, proxy path, and persistent data assumptions before proceeding."}, "page_contents": {"0.7": "+++\ntitle = \"Update Sambee Safely\"\n+++\n\nUpdates should be deliberate. Do not upgrade production from the current branch tip.\n\n## Recommended Update Flow\n\nFetch the available tags and move to the release you intend to deploy:\n\n```bash\ngit fetch --tags\ngit checkout \u003crelease-tag\u003e\ndocker compose down\ndocker compose build --pull --no-cache\ndocker compose up -d\n```\n\n## Why This Flow Matters\n\nThis sequence makes the deployed version explicit and avoids drifting forward to whatever changed upstream most recently.\n\nIt also gives you a clean rebuild point instead of assuming the currently cached image still matches your operational intent.\n\n## Before You Upgrade\n\nBefore performing an update, confirm:\n\n- You know exactly which version you are moving to.\n- Your backup posture is acceptable.\n- Any local deployment files such as `docker-compose.yml` and optional `config.toml` are in the state you expect.\n\n## After You Upgrade\n\nAfter the new version is up:\n\n- Confirm that the frontend loads.\n- Confirm that you can sign in as expected.\n- Confirm that key SMB workflows still work.\n- Check logs for obvious startup regressions.\n\n## Verify the Upgraded Deployment\n\nTreat upgrade verification as part of the upgrade, not as optional follow-up.\n\nAt minimum, confirm:\n\n- You are on the intended release tag or commit.\n- The `docker compose ps` output shows the service healthy.\n- The frontend and sign-in path still work.\n- Key SMB workflows still behave as expected.\n- The recent logs do not show an obvious startup or migration regression.\n\nIf the service does not return cleanly after the update, stop changing versions and inspect the deployment state, recent logs, proxy path, and persistent data assumptions before proceeding.\n", "0.8": "+++\ntitle = \"Update Sambee Safely\"\n+++\n\nUpdates should be deliberate. Do not upgrade production from the current branch tip.\n\n## Recommended Update Flow\n\nFetch the available tags and move to the release you intend to deploy:\n\n```bash\ngit fetch --tags\ngit checkout \u003crelease-tag\u003e\ndocker compose down\ndocker compose build --pull --no-cache\ndocker compose up -d\n```\n\n## Why This Flow Matters\n\nThis sequence makes the deployed version explicit and avoids drifting forward to whatever changed upstream most recently.\n\nIt also gives you a clean rebuild point instead of assuming the currently cached image still matches your operational intent.\n\n## Before You Upgrade\n\nBefore performing an update, confirm:\n\n- You know exactly which version you are moving to.\n- Your backup posture is acceptable.\n- Any local deployment files such as `docker-compose.yml` and optional `config.toml` are in the state you expect.\n\n## After You Upgrade\n\nAfter the new version is up:\n\n- Confirm that the frontend loads.\n- Confirm that you can sign in as expected.\n- Confirm that key SMB workflows still work.\n- Check logs for obvious startup regressions.\n\n## Verify the Upgraded Deployment\n\nTreat upgrade verification as part of the upgrade, not as optional follow-up.\n\nAt minimum, confirm:\n\n- You are on the intended release tag or commit.\n- The `docker compose ps` output shows the service healthy.\n- The frontend and sign-in path still work.\n- Key SMB workflows still behave as expected.\n- The recent logs do not show an obvious startup or migration regression.\n\nIf the service does not return cleanly after the update, stop changing versions and inspect the deployment state, recent logs, proxy path, and persistent data assumptions before proceeding.\n", "0.9": "+++\ntitle = \"Update Sambee Safely\"\n+++\n\nUpdates should be deliberate. Do not upgrade production from the current branch tip.\n\n## Recommended Update Flow\n\nFetch the available tags and move to the release you intend to deploy:\n\n```bash\ngit fetch --tags\ngit checkout \u003crelease-tag\u003e\ndocker compose down\ndocker compose build --pull --no-cache\ndocker compose up -d\n```\n\n## Why This Flow Matters\n\nThis sequence makes the deployed version explicit and avoids drifting forward to whatever changed upstream most recently.\n\nIt also gives you a clean rebuild point instead of assuming the currently cached image still matches your operational intent.\n\n## Before You Upgrade\n\nBefore performing an update, confirm:\n\n- You know exactly which version you are moving to.\n- Your backup posture is acceptable.\n- Any local deployment files such as `docker-compose.yml` and optional `config.toml` are in the state you expect.\n\n## After You Upgrade\n\nAfter the new version is up:\n\n- Confirm that the frontend loads.\n- Confirm that you can sign in as expected.\n- Confirm that key SMB workflows still work.\n- Check logs for obvious startup regressions.\n\n## Verify the Upgraded Deployment\n\nTreat upgrade verification as part of the upgrade, not as optional follow-up.\n\nAt minimum, confirm:\n\n- You are on the intended release tag or commit.\n- The `docker compose ps` output shows the service healthy.\n- The frontend and sign-in path still work.\n- Key SMB workflows still behave as expected.\n- The recent logs do not show an obvious startup or migration regression.\n\nIf the service does not return cleanly after the update, stop changing versions and inspect the deployment state, recent logs, proxy path, and persistent data assumptions before proceeding.\n", "1.0": "+++\ntitle = \"Update Sambee Safely\"\n+++\n\nUpdates should be deliberate. Do not upgrade production from the current branch tip.\n\n## Recommended Update Flow\n\nFetch the available tags and move to the release you intend to deploy:\n\n```bash\ngit fetch --tags\ngit checkout \u003crelease-tag\u003e\ndocker compose down\ndocker compose build --pull --no-cache\ndocker compose up -d\n```\n\n## Archive V2 Cutover\n\nThe Archive V2 release does not retain interrupted Archive V1 work. Complete this one-time procedure before starting the new image when the preflight reports legacy archive operations.\n\n1. Stop Sambee and make a cold backup of `data/`, `docker-compose.yml`, and `config.toml` if you use one.\n1. Run the V2 preflight against the deployment's mounted database:\n\n   ```bash\n   docker compose run --rm --entrypoint /app/scripts/preflight-archive-v2-cutover sambee\n   ```\n\n1. If the preflight lists legacy operations, review the output. Those operations cannot be resumed after the cutover.\n1. Explicitly discard only the listed legacy archive operations:\n\n   ```bash\n   docker compose run --rm --entrypoint /app/scripts/reset-archive-v2-cutover-state sambee \\\n     --confirm-discard-legacy-archive-state\n   ```\n\n1. Run the preflight again. Continue only when it reports `\"ready\": true`.\n1. Start the new image with `docker compose up -d`. Startup runs the preflight again before applying database migrations.\n\nDo not run the reset command while an older Sambee backend can still create archive operations. The command affects only legacy archive-operation state; it does not reset users, connections, or other application data.\n\n## Why This Flow Matters\n\nThis sequence makes the deployed version explicit and avoids drifting forward to whatever changed upstream most recently.\n\nIt also gives you a clean rebuild point instead of assuming the currently cached image still matches your operational intent.\n\n## Before You Upgrade\n\nBefore performing an update, confirm:\n\n- You know exactly which version you are moving to.\n- Your backup posture is acceptable.\n- Any local deployment files such as `docker-compose.yml` and optional `config.toml` are in the state you expect.\n\n## After You Upgrade\n\nAfter the new version is up:\n\n- Confirm that the frontend loads.\n- Confirm that you can sign in as expected.\n- Confirm that key SMB workflows still work.\n- Check logs for obvious startup regressions.\n\n## Verify the Upgraded Deployment\n\nTreat upgrade verification as part of the upgrade, not as optional follow-up.\n\nAt minimum, confirm:\n\n- You are on the intended release tag or commit.\n- The `docker compose ps` output shows the service healthy.\n- The frontend and sign-in path still work.\n- Key SMB workflows still behave as expected.\n- The recent logs do not show an obvious startup or migration regression.\n\nIf the service does not return cleanly after the update, stop changing versions and inspect the deployment state, recent logs, proxy path, and persistent data assumptions before proceeding.", "2.0": "+++\ntitle = \"Update Sambee Safely\"\n+++\n\nUpdates should be deliberate. Do not upgrade production from the current branch tip.\n\n## Recommended Update Flow\n\nFetch the available tags and move to the release you intend to deploy:\n\n```bash\ngit fetch --tags\ngit checkout \u003crelease-tag\u003e\ndocker compose down\ndocker compose build --pull --no-cache\ndocker compose up -d\n```\n\n## Archive V2 Cutover\n\nThe Archive V2 release does not retain interrupted Archive V1 work. Complete this one-time procedure before starting the new image when the preflight reports legacy archive operations.\n\n1. Stop Sambee and make a cold backup of `data/`, `docker-compose.yml`, and `config.toml` if you use one.\n1. Run the V2 preflight against the deployment's mounted database:\n\n   ```bash\n   docker compose run --rm --entrypoint /app/scripts/preflight-archive-v2-cutover sambee\n   ```\n\n1. If the preflight lists legacy operations, review the output. Those operations cannot be resumed after the cutover.\n1. Explicitly discard only the listed legacy archive operations:\n\n   ```bash\n   docker compose run --rm --entrypoint /app/scripts/reset-archive-v2-cutover-state sambee \\\n     --confirm-discard-legacy-archive-state\n   ```\n\n1. Run the preflight again. Continue only when it reports `\"ready\": true`.\n1. Start the new image with `docker compose up -d`. Startup runs the preflight again before applying database migrations.\n\nDo not run the reset command while an older Sambee backend can still create archive operations. The command affects only legacy archive-operation state; it does not reset users, connections, or other application data.\n\n## Why This Flow Matters\n\nThis sequence makes the deployed version explicit and avoids drifting forward to whatever changed upstream most recently.\n\nIt also gives you a clean rebuild point instead of assuming the currently cached image still matches your operational intent.\n\n## Before You Upgrade\n\nBefore performing an update, confirm:\n\n- You know exactly which version you are moving to.\n- Your backup posture is acceptable.\n- Any local deployment files such as `docker-compose.yml` and optional `config.toml` are in the state you expect.\n\n## After You Upgrade\n\nAfter the new version is up:\n\n- Confirm that the frontend loads.\n- Confirm that you can sign in as expected.\n- Confirm that key SMB workflows still work.\n- Check logs for obvious startup regressions.\n\n## Verify the Upgraded Deployment\n\nTreat upgrade verification as part of the upgrade, not as optional follow-up.\n\nAt minimum, confirm:\n\n- You are on the intended release tag or commit.\n- The `docker compose ps` output shows the service healthy.\n- The frontend and sign-in path still work.\n- Key SMB workflows still behave as expected.\n- The recent logs do not show an obvious startup or migration regression.\n\nIf the service does not return cleanly after the update, stop changing versions and inspect the deployment state, recent logs, proxy path, and persistent data assumptions before proceeding."}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:admin-guide/operations-and-maintenance/backup-and-restore-planning", "parent_id": "section:admin-guide/operations-and-maintenance", "depth": 2, "kind": "page", "label": "backup-and-restore-planning", "title": "Backup And Restore Planning", "path": "admin-guide/operations-and-maintenance/backup-and-restore-planning", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Backup and Restore Planning\"\n+++\n\nBackup planning for Sambee is mainly about preserving the deployment state that the service cannot recreate on its own.\n\n## What Must Be Protected\n\nAt minimum, protect:\n\n- `data/sambee.db`\n- your local `docker-compose.yml`\n- your local `config.toml`, if you use one\n\nThe database is the most important part because it contains users, connections, security keys, and encrypted passwords.\n\n## Simple Backup Pattern\n\nThe simplest safe backup is a cold backup:\n\n1. Stop the Sambee service.\n2. Copy `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Store the backup on different storage from the Sambee host.\n\nExample:\n\n```bash\ndocker compose stop sambee\ncp -a data docker-compose.yml /path/to/backup/\n# If You Use Config.toml, Back It up Too.\n# Cp -a Config.toml /Path/to/backup/\ndocker compose up -d sambee\n```\n\nIf you do not use `config.toml`, skip that copy step.\n\n## Basic Restore Flow\n\nAt minimum, a restore should look like this:\n\n1. Recreate the deployment directory on the replacement host.\n2. Restore `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Restore ownership on `data/` if needed so the container can write to it.\n4. Start Sambee with `docker compose up -d`.\n5. Confirm sign-in, logs, and a basic SMB workflow.\n", "0.8": "+++\ntitle = \"Backup and Restore Planning\"\n+++\n\nBackup planning for Sambee is mainly about preserving the deployment state that the service cannot recreate on its own.\n\n## What Must Be Protected\n\nAt minimum, protect:\n\n- `data/sambee.db`\n- your local `docker-compose.yml`\n- your local `config.toml`, if you use one\n\nThe database is the most important part because it contains users, connections, security keys, and encrypted passwords.\n\n## Simple Backup Pattern\n\nThe simplest safe backup is a cold backup:\n\n1. Stop the Sambee service.\n2. Copy `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Store the backup on different storage from the Sambee host.\n\nExample:\n\n```bash\ndocker compose stop sambee\ncp -a data docker-compose.yml /path/to/backup/\n# If You Use Config.toml, Back It up Too.\n# Cp -a Config.toml /Path/to/backup/\ndocker compose up -d sambee\n```\n\nIf you do not use `config.toml`, skip that copy step.\n\n## Basic Restore Flow\n\nAt minimum, a restore should look like this:\n\n1. Recreate the deployment directory on the replacement host.\n2. Restore `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Restore ownership on `data/` if needed so the container can write to it.\n4. Start Sambee with `docker compose up -d`.\n5. Confirm sign-in, logs, and a basic SMB workflow.\n", "0.9": "+++\ntitle = \"Backup and Restore Planning\"\n+++\n\nBackup planning for Sambee is mainly about preserving the deployment state that the service cannot recreate on its own.\n\n## What Must Be Protected\n\nAt minimum, protect:\n\n- `data/sambee.db`\n- your local `docker-compose.yml`\n- your local `config.toml`, if you use one\n\nThe database is the most important part because it contains users, connections, security keys, and encrypted passwords.\n\n## Simple Backup Pattern\n\nThe simplest safe backup is a cold backup:\n\n1. Stop the Sambee service.\n2. Copy `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Store the backup on different storage from the Sambee host.\n\nExample:\n\n```bash\ndocker compose stop sambee\ncp -a data docker-compose.yml /path/to/backup/\n# If You Use Config.toml, Back It up Too.\n# Cp -a Config.toml /Path/to/backup/\ndocker compose up -d sambee\n```\n\nIf you do not use `config.toml`, skip that copy step.\n\n## Basic Restore Flow\n\nAt minimum, a restore should look like this:\n\n1. Recreate the deployment directory on the replacement host.\n2. Restore `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Restore ownership on `data/` if needed so the container can write to it.\n4. Start Sambee with `docker compose up -d`.\n5. Confirm sign-in, logs, and a basic SMB workflow.\n", "1.0": "+++\ntitle = \"Backup and Restore Planning\"\n+++\n\nBackup planning for Sambee is mainly about preserving the deployment state that the service cannot recreate on its own.\n\n## What Must Be Protected\n\nAt minimum, protect:\n\n- `data/sambee.db`\n- your local `docker-compose.yml`\n- your local `config.toml`, if you use one\n\nThe database is the most important part because it contains users, connections, security keys, and encrypted passwords.\n\n## Simple Backup Pattern\n\nThe simplest safe backup is a cold backup:\n\n1. Stop the Sambee service.\n2. Copy `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Store the backup on different storage from the Sambee host.\n\nExample:\n\n```bash\ndocker compose stop sambee\ncp -a data docker-compose.yml /path/to/backup/\n# If You Use Config.toml, Back It up Too.\n# Cp -a Config.toml /Path/to/backup/\ndocker compose up -d sambee\n```\n\nIf you do not use `config.toml`, skip that copy step.\n\n## Basic Restore Flow\n\nAt minimum, a restore should look like this:\n\n1. Recreate the deployment directory on the replacement host.\n2. Restore `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Restore ownership on `data/` if needed so the container can write to it.\n4. Start Sambee with `docker compose up -d`.\n5. Confirm sign-in, logs, and a basic SMB workflow.\n", "2.0": "+++\ntitle = \"Backup and Restore Planning\"\n+++\n\nBackup planning for Sambee is mainly about preserving the deployment state that the service cannot recreate on its own.\n\n## What Must Be Protected\n\nAt minimum, protect:\n\n- `data/sambee.db`\n- your local `docker-compose.yml`\n- your local `config.toml`, if you use one\n\nThe database is the most important part because it contains users, connections, security keys, and encrypted passwords.\n\n## Simple Backup Pattern\n\nThe simplest safe backup is a cold backup:\n\n1. Stop the Sambee service.\n2. Copy `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Store the backup on different storage from the Sambee host.\n\nExample:\n\n```bash\ndocker compose stop sambee\ncp -a data docker-compose.yml /path/to/backup/\n# If You Use Config.toml, Back It up Too.\n# Cp -a Config.toml /Path/to/backup/\ndocker compose up -d sambee\n```\n\nIf you do not use `config.toml`, skip that copy step.\n\n## Basic Restore Flow\n\nAt minimum, a restore should look like this:\n\n1. Recreate the deployment directory on the replacement host.\n2. Restore `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Restore ownership on `data/` if needed so the container can write to it.\n4. Start Sambee with `docker compose up -d`.\n5. Confirm sign-in, logs, and a basic SMB workflow.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Backup and Restore Planning\"\n+++\n\nBackup planning for Sambee is mainly about preserving the deployment state that the service cannot recreate on its own.\n\n## What Must Be Protected\n\nAt minimum, protect:\n\n- `data/sambee.db`\n- your local `docker-compose.yml`\n- your local `config.toml`, if you use one\n\nThe database is the most important part because it contains users, connections, security keys, and encrypted passwords.\n\n## Simple Backup Pattern\n\nThe simplest safe backup is a cold backup:\n\n1. Stop the Sambee service.\n2. Copy `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Store the backup on different storage from the Sambee host.\n\nExample:\n\n```bash\ndocker compose stop sambee\ncp -a data docker-compose.yml /path/to/backup/\n# If You Use Config.toml, Back It up Too.\n# Cp -a Config.toml /Path/to/backup/\ndocker compose up -d sambee\n```\n\nIf you do not use `config.toml`, skip that copy step.\n\n## Basic Restore Flow\n\nAt minimum, a restore should look like this:\n\n1. Recreate the deployment directory on the replacement host.\n2. Restore `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Restore ownership on `data/` if needed so the container can write to it.\n4. Start Sambee with `docker compose up -d`.\n5. Confirm sign-in, logs, and a basic SMB workflow.\n", "0.8": "+++\ntitle = \"Backup and Restore Planning\"\n+++\n\nBackup planning for Sambee is mainly about preserving the deployment state that the service cannot recreate on its own.\n\n## What Must Be Protected\n\nAt minimum, protect:\n\n- `data/sambee.db`\n- your local `docker-compose.yml`\n- your local `config.toml`, if you use one\n\nThe database is the most important part because it contains users, connections, security keys, and encrypted passwords.\n\n## Simple Backup Pattern\n\nThe simplest safe backup is a cold backup:\n\n1. Stop the Sambee service.\n2. Copy `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Store the backup on different storage from the Sambee host.\n\nExample:\n\n```bash\ndocker compose stop sambee\ncp -a data docker-compose.yml /path/to/backup/\n# If You Use Config.toml, Back It up Too.\n# Cp -a Config.toml /Path/to/backup/\ndocker compose up -d sambee\n```\n\nIf you do not use `config.toml`, skip that copy step.\n\n## Basic Restore Flow\n\nAt minimum, a restore should look like this:\n\n1. Recreate the deployment directory on the replacement host.\n2. Restore `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Restore ownership on `data/` if needed so the container can write to it.\n4. Start Sambee with `docker compose up -d`.\n5. Confirm sign-in, logs, and a basic SMB workflow.\n", "0.9": "+++\ntitle = \"Backup and Restore Planning\"\n+++\n\nBackup planning for Sambee is mainly about preserving the deployment state that the service cannot recreate on its own.\n\n## What Must Be Protected\n\nAt minimum, protect:\n\n- `data/sambee.db`\n- your local `docker-compose.yml`\n- your local `config.toml`, if you use one\n\nThe database is the most important part because it contains users, connections, security keys, and encrypted passwords.\n\n## Simple Backup Pattern\n\nThe simplest safe backup is a cold backup:\n\n1. Stop the Sambee service.\n2. Copy `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Store the backup on different storage from the Sambee host.\n\nExample:\n\n```bash\ndocker compose stop sambee\ncp -a data docker-compose.yml /path/to/backup/\n# If You Use Config.toml, Back It up Too.\n# Cp -a Config.toml /Path/to/backup/\ndocker compose up -d sambee\n```\n\nIf you do not use `config.toml`, skip that copy step.\n\n## Basic Restore Flow\n\nAt minimum, a restore should look like this:\n\n1. Recreate the deployment directory on the replacement host.\n2. Restore `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Restore ownership on `data/` if needed so the container can write to it.\n4. Start Sambee with `docker compose up -d`.\n5. Confirm sign-in, logs, and a basic SMB workflow.\n", "1.0": "+++\ntitle = \"Backup and Restore Planning\"\n+++\n\nBackup planning for Sambee is mainly about preserving the deployment state that the service cannot recreate on its own.\n\n## What Must Be Protected\n\nAt minimum, protect:\n\n- `data/sambee.db`\n- your local `docker-compose.yml`\n- your local `config.toml`, if you use one\n\nThe database is the most important part because it contains users, connections, security keys, and encrypted passwords.\n\n## Simple Backup Pattern\n\nThe simplest safe backup is a cold backup:\n\n1. Stop the Sambee service.\n2. Copy `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Store the backup on different storage from the Sambee host.\n\nExample:\n\n```bash\ndocker compose stop sambee\ncp -a data docker-compose.yml /path/to/backup/\n# If You Use Config.toml, Back It up Too.\n# Cp -a Config.toml /Path/to/backup/\ndocker compose up -d sambee\n```\n\nIf you do not use `config.toml`, skip that copy step.\n\n## Basic Restore Flow\n\nAt minimum, a restore should look like this:\n\n1. Recreate the deployment directory on the replacement host.\n2. Restore `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Restore ownership on `data/` if needed so the container can write to it.\n4. Start Sambee with `docker compose up -d`.\n5. Confirm sign-in, logs, and a basic SMB workflow.\n", "2.0": "+++\ntitle = \"Backup and Restore Planning\"\n+++\n\nBackup planning for Sambee is mainly about preserving the deployment state that the service cannot recreate on its own.\n\n## What Must Be Protected\n\nAt minimum, protect:\n\n- `data/sambee.db`\n- your local `docker-compose.yml`\n- your local `config.toml`, if you use one\n\nThe database is the most important part because it contains users, connections, security keys, and encrypted passwords.\n\n## Simple Backup Pattern\n\nThe simplest safe backup is a cold backup:\n\n1. Stop the Sambee service.\n2. Copy `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Store the backup on different storage from the Sambee host.\n\nExample:\n\n```bash\ndocker compose stop sambee\ncp -a data docker-compose.yml /path/to/backup/\n# If You Use Config.toml, Back It up Too.\n# Cp -a Config.toml /Path/to/backup/\ndocker compose up -d sambee\n```\n\nIf you do not use `config.toml`, skip that copy step.\n\n## Basic Restore Flow\n\nAt minimum, a restore should look like this:\n\n1. Recreate the deployment directory on the replacement host.\n2. Restore `data/`, `docker-compose.yml`, and `config.toml` if you use it.\n3. Restore ownership on `data/` if needed so the container can write to it.\n4. Start Sambee with `docker compose up -d`.\n5. Confirm sign-in, logs, and a basic SMB workflow.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:admin-guide/reference", "parent_id": "book:admin-guide", "depth": 1, "kind": "section", "label": "reference", "title": "Reference", "path": "admin-guide/reference", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:admin-guide/reference/port-and-path-reference", "parent_id": "section:admin-guide/reference", "depth": 2, "kind": "page", "label": "port-and-path-reference", "title": "Port And Path Reference", "path": "admin-guide/reference/port-and-path-reference", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Port and Path Reference\"\n+++\n\nThis is the main lookup page for Sambee service ports, deployment files, persistent paths, and container-side paths.\n\n## Service Ports and URLs\n\n| Item | Default value | Notes |\n|---|---|---|\n| Sambee application port | `8000` | Default application port in the sample deployment |\n| Frontend URL | `http://localhost:8000` | Default direct-access frontend URL |\n| Backend API | `http://localhost:8000/api` | Default API path |\n| API docs | `http://localhost:8000/docs` | Default API documentation path |\n\n## Deployment Files and Paths\n\n| Path | Purpose |\n|---|---|\n| `docker-compose.yml` | Local deployment definition |\n| `config.toml` | Optional local configuration file |\n| `data/` | Persistent application data directory that must be backed up |\n| `data/sambee.db` | SQLite database containing users, connections, security keys, and encrypted passwords |\n| `data/directory_cache/` | Default location for Sambee's saved directory index when the relative cache setting is used |\n\n## Container-Side Paths\n\n| Path | Purpose |\n|---|---|\n| `/app/data` | Container-side mount point for persistent data |\n| `/app/data/sambee.db` | Container-side database path |\n| `/app/config.toml` | Container-side path for the optional mounted config file |\n| `/app/data/directory_cache/` | Default container-side location for the saved directory index |\n\n## Host-to-Container Mapping\n\n- Host-side `./data` becomes `/app/data` in the container.\n- Host-side `./config.toml` can be mounted read-only as `/app/config.toml`.\n- Deleting or replacing files under `data/` changes persistent deployment state, not just temporary cache files.\n", "0.8": "+++\ntitle = \"Port and Path Reference\"\n+++\n\nThis is the main lookup page for Sambee service ports, deployment files, persistent paths, and container-side paths.\n\n## Service Ports and URLs\n\n| Item | Default value | Notes |\n|---|---|---|\n| Sambee application port | `8000` | Default application port in the sample deployment |\n| Frontend URL | `http://localhost:8000` | Default direct-access frontend URL |\n| Backend API | `http://localhost:8000/api` | Default API path |\n| API docs | `http://localhost:8000/docs` | Default API documentation path |\n\n## Deployment Files and Paths\n\n| Path | Purpose |\n|---|---|\n| `docker-compose.yml` | Local deployment definition |\n| `config.toml` | Optional local configuration file |\n| `data/` | Persistent application data directory that must be backed up |\n| `data/sambee.db` | SQLite database containing users, connections, security keys, and encrypted passwords |\n| `data/directory_cache/` | Default location for Sambee's saved directory index when the relative cache setting is used |\n\n## Container-Side Paths\n\n| Path | Purpose |\n|---|---|\n| `/app/data` | Container-side mount point for persistent data |\n| `/app/data/sambee.db` | Container-side database path |\n| `/app/config.toml` | Container-side path for the optional mounted config file |\n| `/app/data/directory_cache/` | Default container-side location for the saved directory index |\n\n## Host-to-Container Mapping\n\n- Host-side `./data` becomes `/app/data` in the container.\n- Host-side `./config.toml` can be mounted read-only as `/app/config.toml`.\n- Deleting or replacing files under `data/` changes persistent deployment state, not just temporary cache files.\n", "0.9": "+++\ntitle = \"Port and Path Reference\"\n+++\n\nThis is the main lookup page for Sambee service ports, deployment files, persistent paths, and container-side paths.\n\n## Service Ports and URLs\n\n| Item | Default value | Notes |\n|---|---|---|\n| Sambee application port | `8000` | Default application port in the sample deployment |\n| Frontend URL | `http://localhost:8000` | Default direct-access frontend URL |\n| Backend API | `http://localhost:8000/api` | Default API path |\n| API docs | `http://localhost:8000/docs` | Default API documentation path |\n\n## Deployment Files and Paths\n\n| Path | Purpose |\n|---|---|\n| `docker-compose.yml` | Local deployment definition |\n| `config.toml` | Optional local configuration file |\n| `data/` | Persistent application data directory that must be backed up |\n| `data/sambee.db` | SQLite database containing users, connections, security keys, and encrypted passwords |\n| `data/directory_cache/` | Default location for Sambee's saved directory index when the relative cache setting is used |\n\n## Container-Side Paths\n\n| Path | Purpose |\n|---|---|\n| `/app/data` | Container-side mount point for persistent data |\n| `/app/data/sambee.db` | Container-side database path |\n| `/app/config.toml` | Container-side path for the optional mounted config file |\n| `/app/data/directory_cache/` | Default container-side location for the saved directory index |\n\n## Host-to-Container Mapping\n\n- Host-side `./data` becomes `/app/data` in the container.\n- Host-side `./config.toml` can be mounted read-only as `/app/config.toml`.\n- Deleting or replacing files under `data/` changes persistent deployment state, not just temporary cache files.\n", "1.0": "+++\ntitle = \"Port and Path Reference\"\n+++\n\nThis is the main lookup page for Sambee service ports, deployment files, persistent paths, and container-side paths.\n\n## Service Ports and URLs\n\n| Item | Default value | Notes |\n|---|---|---|\n| Sambee application port | `8000` | Default application port in the sample deployment |\n| Frontend URL | `http://localhost:8000` | Default direct-access frontend URL |\n| Backend API | `http://localhost:8000/api` | Default API path |\n| API docs | `http://localhost:8000/docs` | Default API documentation path |\n\n## Deployment Files and Paths\n\n| Path | Purpose |\n|---|---|\n| `docker-compose.yml` | Local deployment definition |\n| `config.toml` | Optional local configuration file |\n| `data/` | Persistent application data directory that must be backed up |\n| `data/sambee.db` | SQLite database containing users, connections, security keys, and encrypted passwords |\n| `data/directory_cache/` | Default location for Sambee's saved directory index when the relative cache setting is used |\n\n## Container-Side Paths\n\n| Path | Purpose |\n|---|---|\n| `/app/data` | Container-side mount point for persistent data |\n| `/app/data/sambee.db` | Container-side database path |\n| `/app/config.toml` | Container-side path for the optional mounted config file |\n| `/app/data/directory_cache/` | Default container-side location for the saved directory index |\n\n## Host-to-Container Mapping\n\n- Host-side `./data` becomes `/app/data` in the container.\n- Host-side `./config.toml` can be mounted read-only as `/app/config.toml`.\n- Deleting or replacing files under `data/` changes persistent deployment state, not just temporary cache files.\n", "2.0": "+++\ntitle = \"Port and Path Reference\"\n+++\n\nThis is the main lookup page for Sambee service ports, deployment files, persistent paths, and container-side paths.\n\n## Service Ports and URLs\n\n| Item | Default value | Notes |\n|---|---|---|\n| Sambee application port | `8000` | Default application port in the sample deployment |\n| Frontend URL | `http://localhost:8000` | Default direct-access frontend URL |\n| Backend API | `http://localhost:8000/api` | Default API path |\n| API docs | `http://localhost:8000/docs` | Default API documentation path |\n\n## Deployment Files and Paths\n\n| Path | Purpose |\n|---|---|\n| `docker-compose.yml` | Local deployment definition |\n| `config.toml` | Optional local configuration file |\n| `data/` | Persistent application data directory that must be backed up |\n| `data/sambee.db` | SQLite database containing users, connections, security keys, and encrypted passwords |\n| `data/directory_cache/` | Default location for Sambee's saved directory index when the relative cache setting is used |\n\n## Container-Side Paths\n\n| Path | Purpose |\n|---|---|\n| `/app/data` | Container-side mount point for persistent data |\n| `/app/data/sambee.db` | Container-side database path |\n| `/app/config.toml` | Container-side path for the optional mounted config file |\n| `/app/data/directory_cache/` | Default container-side location for the saved directory index |\n\n## Host-to-Container Mapping\n\n- Host-side `./data` becomes `/app/data` in the container.\n- Host-side `./config.toml` can be mounted read-only as `/app/config.toml`.\n- Deleting or replacing files under `data/` changes persistent deployment state, not just temporary cache files.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Port and Path Reference\"\n+++\n\nThis is the main lookup page for Sambee service ports, deployment files, persistent paths, and container-side paths.\n\n## Service Ports and URLs\n\n| Item | Default value | Notes |\n|---|---|---|\n| Sambee application port | `8000` | Default application port in the sample deployment |\n| Frontend URL | `http://localhost:8000` | Default direct-access frontend URL |\n| Backend API | `http://localhost:8000/api` | Default API path |\n| API docs | `http://localhost:8000/docs` | Default API documentation path |\n\n## Deployment Files and Paths\n\n| Path | Purpose |\n|---|---|\n| `docker-compose.yml` | Local deployment definition |\n| `config.toml` | Optional local configuration file |\n| `data/` | Persistent application data directory that must be backed up |\n| `data/sambee.db` | SQLite database containing users, connections, security keys, and encrypted passwords |\n| `data/directory_cache/` | Default location for Sambee's saved directory index when the relative cache setting is used |\n\n## Container-Side Paths\n\n| Path | Purpose |\n|---|---|\n| `/app/data` | Container-side mount point for persistent data |\n| `/app/data/sambee.db` | Container-side database path |\n| `/app/config.toml` | Container-side path for the optional mounted config file |\n| `/app/data/directory_cache/` | Default container-side location for the saved directory index |\n\n## Host-to-Container Mapping\n\n- Host-side `./data` becomes `/app/data` in the container.\n- Host-side `./config.toml` can be mounted read-only as `/app/config.toml`.\n- Deleting or replacing files under `data/` changes persistent deployment state, not just temporary cache files.\n", "0.8": "+++\ntitle = \"Port and Path Reference\"\n+++\n\nThis is the main lookup page for Sambee service ports, deployment files, persistent paths, and container-side paths.\n\n## Service Ports and URLs\n\n| Item | Default value | Notes |\n|---|---|---|\n| Sambee application port | `8000` | Default application port in the sample deployment |\n| Frontend URL | `http://localhost:8000` | Default direct-access frontend URL |\n| Backend API | `http://localhost:8000/api` | Default API path |\n| API docs | `http://localhost:8000/docs` | Default API documentation path |\n\n## Deployment Files and Paths\n\n| Path | Purpose |\n|---|---|\n| `docker-compose.yml` | Local deployment definition |\n| `config.toml` | Optional local configuration file |\n| `data/` | Persistent application data directory that must be backed up |\n| `data/sambee.db` | SQLite database containing users, connections, security keys, and encrypted passwords |\n| `data/directory_cache/` | Default location for Sambee's saved directory index when the relative cache setting is used |\n\n## Container-Side Paths\n\n| Path | Purpose |\n|---|---|\n| `/app/data` | Container-side mount point for persistent data |\n| `/app/data/sambee.db` | Container-side database path |\n| `/app/config.toml` | Container-side path for the optional mounted config file |\n| `/app/data/directory_cache/` | Default container-side location for the saved directory index |\n\n## Host-to-Container Mapping\n\n- Host-side `./data` becomes `/app/data` in the container.\n- Host-side `./config.toml` can be mounted read-only as `/app/config.toml`.\n- Deleting or replacing files under `data/` changes persistent deployment state, not just temporary cache files.\n", "0.9": "+++\ntitle = \"Port and Path Reference\"\n+++\n\nThis is the main lookup page for Sambee service ports, deployment files, persistent paths, and container-side paths.\n\n## Service Ports and URLs\n\n| Item | Default value | Notes |\n|---|---|---|\n| Sambee application port | `8000` | Default application port in the sample deployment |\n| Frontend URL | `http://localhost:8000` | Default direct-access frontend URL |\n| Backend API | `http://localhost:8000/api` | Default API path |\n| API docs | `http://localhost:8000/docs` | Default API documentation path |\n\n## Deployment Files and Paths\n\n| Path | Purpose |\n|---|---|\n| `docker-compose.yml` | Local deployment definition |\n| `config.toml` | Optional local configuration file |\n| `data/` | Persistent application data directory that must be backed up |\n| `data/sambee.db` | SQLite database containing users, connections, security keys, and encrypted passwords |\n| `data/directory_cache/` | Default location for Sambee's saved directory index when the relative cache setting is used |\n\n## Container-Side Paths\n\n| Path | Purpose |\n|---|---|\n| `/app/data` | Container-side mount point for persistent data |\n| `/app/data/sambee.db` | Container-side database path |\n| `/app/config.toml` | Container-side path for the optional mounted config file |\n| `/app/data/directory_cache/` | Default container-side location for the saved directory index |\n\n## Host-to-Container Mapping\n\n- Host-side `./data` becomes `/app/data` in the container.\n- Host-side `./config.toml` can be mounted read-only as `/app/config.toml`.\n- Deleting or replacing files under `data/` changes persistent deployment state, not just temporary cache files.\n", "1.0": "+++\ntitle = \"Port and Path Reference\"\n+++\n\nThis is the main lookup page for Sambee service ports, deployment files, persistent paths, and container-side paths.\n\n## Service Ports and URLs\n\n| Item | Default value | Notes |\n|---|---|---|\n| Sambee application port | `8000` | Default application port in the sample deployment |\n| Frontend URL | `http://localhost:8000` | Default direct-access frontend URL |\n| Backend API | `http://localhost:8000/api` | Default API path |\n| API docs | `http://localhost:8000/docs` | Default API documentation path |\n\n## Deployment Files and Paths\n\n| Path | Purpose |\n|---|---|\n| `docker-compose.yml` | Local deployment definition |\n| `config.toml` | Optional local configuration file |\n| `data/` | Persistent application data directory that must be backed up |\n| `data/sambee.db` | SQLite database containing users, connections, security keys, and encrypted passwords |\n| `data/directory_cache/` | Default location for Sambee's saved directory index when the relative cache setting is used |\n\n## Container-Side Paths\n\n| Path | Purpose |\n|---|---|\n| `/app/data` | Container-side mount point for persistent data |\n| `/app/data/sambee.db` | Container-side database path |\n| `/app/config.toml` | Container-side path for the optional mounted config file |\n| `/app/data/directory_cache/` | Default container-side location for the saved directory index |\n\n## Host-to-Container Mapping\n\n- Host-side `./data` becomes `/app/data` in the container.\n- Host-side `./config.toml` can be mounted read-only as `/app/config.toml`.\n- Deleting or replacing files under `data/` changes persistent deployment state, not just temporary cache files.\n", "2.0": "+++\ntitle = \"Port and Path Reference\"\n+++\n\nThis is the main lookup page for Sambee service ports, deployment files, persistent paths, and container-side paths.\n\n## Service Ports and URLs\n\n| Item | Default value | Notes |\n|---|---|---|\n| Sambee application port | `8000` | Default application port in the sample deployment |\n| Frontend URL | `http://localhost:8000` | Default direct-access frontend URL |\n| Backend API | `http://localhost:8000/api` | Default API path |\n| API docs | `http://localhost:8000/docs` | Default API documentation path |\n\n## Deployment Files and Paths\n\n| Path | Purpose |\n|---|---|\n| `docker-compose.yml` | Local deployment definition |\n| `config.toml` | Optional local configuration file |\n| `data/` | Persistent application data directory that must be backed up |\n| `data/sambee.db` | SQLite database containing users, connections, security keys, and encrypted passwords |\n| `data/directory_cache/` | Default location for Sambee's saved directory index when the relative cache setting is used |\n\n## Container-Side Paths\n\n| Path | Purpose |\n|---|---|\n| `/app/data` | Container-side mount point for persistent data |\n| `/app/data/sambee.db` | Container-side database path |\n| `/app/config.toml` | Container-side path for the optional mounted config file |\n| `/app/data/directory_cache/` | Default container-side location for the saved directory index |\n\n## Host-to-Container Mapping\n\n- Host-side `./data` becomes `/app/data` in the container.\n- Host-side `./config.toml` can be mounted read-only as `/app/config.toml`.\n- Deleting or replacing files under `data/` changes persistent deployment state, not just temporary cache files.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:admin-guide/reference/companion-support-reference", "parent_id": "section:admin-guide/reference", "depth": 2, "kind": "page", "label": "companion-support-reference", "title": "Companion Support Reference", "path": "admin-guide/reference/companion-support-reference", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Companion Support Reference\"\n+++\n\n## Communication and Security Model\n\nSambee uses two different browser-to-companion paths, depending on the workflow.\n\n- Local-drive browsing uses the companion's localhost API on `127.0.0.1:21549`.\n- Real-time local directory updates use a localhost WebSocket on the same port.\n- Desktop-app opening uses the `sambee://` custom URI scheme.\n\nThe localhost API is bound to the local machine only. It is not meant for remote network access.\n\nLocalhost traffic is authenticated after pairing, but it is not transport-encrypted.\n\n- HTTP requests use an HMAC derived from a shared secret and a current timestamp.\n- WebSocket and browser resource URLs use the same HMAC model through query parameters because browsers cannot attach custom headers in those cases.\n- The companion rejects requests outside the allowed clock-skew window.\n- Pairing is scoped to the browser origin, not just to the machine as a whole.\n\nThe shared secret is created only after the user confirms the same pairing code in both the browser and the companion. The companion stores its copy in the OS credential store. The browser stores its copy locally for that paired browser profile at that Sambee origin.\n\nIf you need contributor-level implementation detail, continue to the developer guide page [Browser-to-Companion Trust Model](../../../../0.7/developer-guide/companion-architecture/browser-to-companion-trust-model/).\n\n## Preference Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%APPDATA%\\app.sambee.companion\\` |\n| macOS | `~/Library/Application Support/app.sambee.companion/` |\n| Linux | `~/.local/share/app.sambee.companion/` |\n\nDeleting `user-preferences.json` and `app-preferences.json` resets companion settings.\n\n## Log Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%LOCALAPPDATA%\\Sambee\\Companion\\logs\\sambee-companion.log` |\n| macOS | `~/Library/Application Support/app.sambee.companion/logs/sambee-companion.log` |\n| Linux | `~/.local/share/sambee-companion/logs/sambee-companion.log` |\n\nThe companion writes both Rust-backend messages and TypeScript-frontend messages into the same rotating log file.\n\n## Log Levels\n\n| Level | When captured | Typical use |\n|---|---|---|\n| `error` | Always | failures that stop an operation from completing |\n| `warn` | Always | degraded but non-fatal behavior |\n| `info` | Verbose mode only | lifecycle steps and state transitions |\n| `debug` | Verbose mode only for Sambee app and frontend logs | detailed diagnostic context |\n\nErrors and warnings are always written, even when verbose logging is off. That keeps production incidents diagnosable without requiring the user to reproduce them in a special logging mode.\n\nNormal verbose logging keeps dependency transport logs quiet. HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls` are enabled separately because they can be very noisy.\n\n## Logging Controls\n\nLogging settings are read once at startup, so restart the companion after changing logging registry values or logging environment variables.\n\nTwo logging toggles are available:\n\n| Setting | Purpose |\n|---|---|\n| `VerboseLogging` | Enables verbose Sambee app and frontend logs. |\n| `TransportLogging` | Enables HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls`. |\n\n### Windows Registry Values\n\nOn Windows, configure logging through registry values under:\n\n```text\nHKEY_CURRENT_USER\\Software\\Sambee\\Companion\n```\n\nUse type `REG_DWORD`. A non-zero value enables the setting. A missing value or `0` leaves the setting disabled.\n\nTo enable verbose Sambee app and frontend logs:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 1 /f\n```\n\nTo enable HTTP transport diagnostics:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 1 /f\n```\n\nTo disable them again:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 0 /f\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 0 /f\n```\n\nRestart Companion after changing either registry value.\n\n### Linux and macOS Environment Variables\n\nOn Linux and macOS, launch the companion with environment variables for the logging modes you need.\n\nVerbose Sambee app and frontend logs:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 ./sambee-companion\n```\n\nHTTP transport diagnostics:\n\n```bash\nSAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nYou can combine both logging modes:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 SAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nThe environment variables are also available on Windows for one-off terminal-launched debugging and take precedence over the registry values. Use `0` or `false` to force a setting off for that launch.\n\nUse verbose logging when the normal log file does not explain why startup, local-drive access, or file-return workflows are failing. Add transport diagnostics when you need HTTP, TLS, proxy, or HTTP/2 details.\n\n## Support Log Checklist\n\nWhen collecting Companion logs for a native-editing issue, include:\n\n- Whether the `Sambee Authentication` window appeared.\n- Whether the failure happened during token exchange, file-info lookup, lock acquisition, download, upload, lock release, or heartbeat.\n- Whether Companion reported a lifecycle state such as renewal required, authentication failed, lock lost, or recovery required.\n- The reverse proxy or SSO product in front of Sambee, if one is used.\n- The Companion log file from the affected desktop.\n\nWhen verbose logging is enabled, include any operation or lock identifiers shown near the failing step. Those identifiers help correlate token exchange, lock acquisition, renewal, upload, and release events without exposing the secret material itself.\n\nCompanion sanitizes URLs before writing request diagnostics. Sensitive query values such as tokens, secrets, passwords, cookies, authorization data, sessions, keys, and theme payloads should not appear in support logs.\n\n## Log Rotation\n\nThe companion rotates logs automatically to avoid unbounded disk growth.\n\n- Maximum file size: 5 MB per log file.\n- Maximum files: 3 total, including the active file.\n- Worst-case disk usage: About 15 MB.\n\nRotation uses the usual numbered-copy scheme: the active `.log` becomes `.log.1`, the previous `.log.1` becomes `.log.2`, and the oldest rotated file is removed.\n\n## Log Format\n\nEach line follows this structure:\n\n```text\nYYYY-MM-DDThh:mm:ss.mmmZ LEVEL [module] message\n```\n\nExample:\n\n```text\n2026-02-17T14:30:45.123Z INFO  [sambee_companion_lib] Step 1: Exchanging URI token...\n2026-02-17T14:30:45.456Z ERROR [frontend] Upload failed: network timeout\n2026-02-17T14:30:46.789Z WARN  [sambee_companion_lib::commands::upload] Upload attempt 1/3 failed: connection refused\n```\n\nFrontend messages use the module target `frontend` so you can distinguish browser-side UI logging from Rust-side command and backend behavior.\n\n## How Logging Reaches the File\n\nThe companion uses one unified file-log pipeline.\n\n### Rust Side\n\nThe Rust logging module in `companion/src-tauri/src/logging.rs` implements the `log::Log` trait. Existing Rust-side `info!()`, `warn!()`, `error!()`, and `debug!()` calls therefore write into the same rotating companion log file.\n\nIf file logging initialization fails, the app falls back to stderr logging so startup can still proceed and terminal-launched sessions still have diagnostic output.\n\n### Frontend Side\n\nThe frontend logger in `companion/src/lib/logger.ts` writes to both:\n\n- The browser console for local developer-tools visibility.\n- The Rust backend through the `log_from_frontend` Tauri command so the same message lands in the file log.\n\nThat means support logs can contain both frontend and backend events in one timeline.\n\nThe frontend logger is fire-and-forget. Logging should never block the UI or surface a user-facing error because the log write itself failed.\n\n## Windows Webview2 Runtime Data\n\nOn Windows, the embedded WebView2 runtime stores its data at:\n\n- `%LOCALAPPDATA%\\app.sambee.companion\\EBWebView\\`\n\nThis directory is runtime-managed and is recreated automatically if removed.\n", "0.8": "+++\ntitle = \"Companion Support Reference\"\n+++\n\n## Communication and Security Model\n\nSambee uses two different browser-to-companion paths, depending on the workflow.\n\n- Local-drive browsing uses the companion's localhost API on `127.0.0.1:21549`.\n- Real-time local directory updates use a localhost WebSocket on the same port.\n- Desktop-app opening uses the `sambee://` custom URI scheme.\n\nThe localhost API is bound to the local machine only. It is not meant for remote network access.\n\nLocalhost traffic is authenticated after pairing, but it is not transport-encrypted.\n\n- HTTP requests use an HMAC derived from a shared secret and a current timestamp.\n- WebSocket and browser resource URLs use the same HMAC model through query parameters because browsers cannot attach custom headers in those cases.\n- The companion rejects requests outside the allowed clock-skew window.\n- Pairing is scoped to the browser origin, not just to the machine as a whole.\n\nThe shared secret is created only after the user confirms the same pairing code in both the browser and the companion. The companion stores its copy in the OS credential store. The browser stores its copy locally for that paired browser profile at that Sambee origin.\n\nIf you need contributor-level implementation detail, continue to the developer guide page [Browser-to-Companion Trust Model](../../../../0.7/developer-guide/companion-architecture/browser-to-companion-trust-model/).\n\n## Preference Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%APPDATA%\\app.sambee.companion\\` |\n| macOS | `~/Library/Application Support/app.sambee.companion/` |\n| Linux | `~/.local/share/app.sambee.companion/` |\n\nDeleting `user-preferences.json` and `app-preferences.json` resets companion settings.\n\n## Log Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%LOCALAPPDATA%\\Sambee\\Companion\\logs\\sambee-companion.log` |\n| macOS | `~/Library/Application Support/app.sambee.companion/logs/sambee-companion.log` |\n| Linux | `~/.local/share/sambee-companion/logs/sambee-companion.log` |\n\nThe companion writes both Rust-backend messages and TypeScript-frontend messages into the same rotating log file.\n\n## Log Levels\n\n| Level | When captured | Typical use |\n|---|---|---|\n| `error` | Always | failures that stop an operation from completing |\n| `warn` | Always | degraded but non-fatal behavior |\n| `info` | Verbose mode only | lifecycle steps and state transitions |\n| `debug` | Verbose mode only for Sambee app and frontend logs | detailed diagnostic context |\n\nErrors and warnings are always written, even when verbose logging is off. That keeps production incidents diagnosable without requiring the user to reproduce them in a special logging mode.\n\nNormal verbose logging keeps dependency transport logs quiet. HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls` are enabled separately because they can be very noisy.\n\n## Logging Controls\n\nLogging settings are read once at startup, so restart the companion after changing logging registry values or logging environment variables.\n\nTwo logging toggles are available:\n\n| Setting | Purpose |\n|---|---|\n| `VerboseLogging` | Enables verbose Sambee app and frontend logs. |\n| `TransportLogging` | Enables HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls`. |\n\n### Windows Registry Values\n\nOn Windows, configure logging through registry values under:\n\n```text\nHKEY_CURRENT_USER\\Software\\Sambee\\Companion\n```\n\nUse type `REG_DWORD`. A non-zero value enables the setting. A missing value or `0` leaves the setting disabled.\n\nTo enable verbose Sambee app and frontend logs:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 1 /f\n```\n\nTo enable HTTP transport diagnostics:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 1 /f\n```\n\nTo disable them again:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 0 /f\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 0 /f\n```\n\nRestart Companion after changing either registry value.\n\n### Linux and macOS Environment Variables\n\nOn Linux and macOS, launch the companion with environment variables for the logging modes you need.\n\nVerbose Sambee app and frontend logs:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 ./sambee-companion\n```\n\nHTTP transport diagnostics:\n\n```bash\nSAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nYou can combine both logging modes:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 SAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nThe environment variables are also available on Windows for one-off terminal-launched debugging and take precedence over the registry values. Use `0` or `false` to force a setting off for that launch.\n\nUse verbose logging when the normal log file does not explain why startup, local-drive access, or file-return workflows are failing. Add transport diagnostics when you need HTTP, TLS, proxy, or HTTP/2 details.\n\n## Support Log Checklist\n\nWhen collecting Companion logs for a native-editing issue, include:\n\n- Whether the `Sambee Authentication` window appeared.\n- Whether the failure happened during token exchange, file-info lookup, lock acquisition, download, upload, lock release, or heartbeat.\n- Whether Companion reported a lifecycle state such as renewal required, authentication failed, lock lost, or recovery required.\n- The reverse proxy or SSO product in front of Sambee, if one is used.\n- The Companion log file from the affected desktop.\n\nWhen verbose logging is enabled, include any operation or lock identifiers shown near the failing step. Those identifiers help correlate token exchange, lock acquisition, renewal, upload, and release events without exposing the secret material itself.\n\nCompanion sanitizes URLs before writing request diagnostics. Sensitive query values such as tokens, secrets, passwords, cookies, authorization data, sessions, keys, and theme payloads should not appear in support logs.\n\n## Log Rotation\n\nThe companion rotates logs automatically to avoid unbounded disk growth.\n\n- Maximum file size: 5 MB per log file.\n- Maximum files: 3 total, including the active file.\n- Worst-case disk usage: About 15 MB.\n\nRotation uses the usual numbered-copy scheme: the active `.log` becomes `.log.1`, the previous `.log.1` becomes `.log.2`, and the oldest rotated file is removed.\n\n## Log Format\n\nEach line follows this structure:\n\n```text\nYYYY-MM-DDThh:mm:ss.mmmZ LEVEL [module] message\n```\n\nExample:\n\n```text\n2026-02-17T14:30:45.123Z INFO  [sambee_companion_lib] Step 1: Exchanging URI token...\n2026-02-17T14:30:45.456Z ERROR [frontend] Upload failed: network timeout\n2026-02-17T14:30:46.789Z WARN  [sambee_companion_lib::commands::upload] Upload attempt 1/3 failed: connection refused\n```\n\nFrontend messages use the module target `frontend` so you can distinguish browser-side UI logging from Rust-side command and backend behavior.\n\n## How Logging Reaches the File\n\nThe companion uses one unified file-log pipeline.\n\n### Rust Side\n\nThe Rust logging module in `companion/src-tauri/src/logging.rs` implements the `log::Log` trait. Existing Rust-side `info!()`, `warn!()`, `error!()`, and `debug!()` calls therefore write into the same rotating companion log file.\n\nIf file logging initialization fails, the app falls back to stderr logging so startup can still proceed and terminal-launched sessions still have diagnostic output.\n\n### Frontend Side\n\nThe frontend logger in `companion/src/lib/logger.ts` writes to both:\n\n- The browser console for local developer-tools visibility.\n- The Rust backend through the `log_from_frontend` Tauri command so the same message lands in the file log.\n\nThat means support logs can contain both frontend and backend events in one timeline.\n\nThe frontend logger is fire-and-forget. Logging should never block the UI or surface a user-facing error because the log write itself failed.\n\n## Windows Webview2 Runtime Data\n\nOn Windows, the embedded WebView2 runtime stores its data at:\n\n- `%LOCALAPPDATA%\\app.sambee.companion\\EBWebView\\`\n\nThis directory is runtime-managed and is recreated automatically if removed.\n", "0.9": "+++\ntitle = \"Companion Support Reference\"\n+++\n\n## Communication and Security Model\n\nSambee uses two different browser-to-companion paths, depending on the workflow.\n\n- Local-drive browsing uses the companion's localhost API on `127.0.0.1:21549`.\n- Real-time local directory updates use a localhost WebSocket on the same port.\n- Desktop-app opening uses the `sambee://` custom URI scheme.\n\nThe localhost API is bound to the local machine only. It is not meant for remote network access.\n\nLocalhost traffic is authenticated after pairing, but it is not transport-encrypted.\n\n- HTTP requests use an HMAC derived from a shared secret and a current timestamp.\n- WebSocket and browser resource URLs use the same HMAC model through query parameters because browsers cannot attach custom headers in those cases.\n- The companion rejects requests outside the allowed clock-skew window.\n- Pairing is scoped to the browser origin, not just to the machine as a whole.\n\nThe shared secret is created only after the user confirms the same pairing code in both the browser and the companion. The companion stores its copy in the OS credential store. The browser stores its copy locally for that paired browser profile at that Sambee origin.\n\nIf you need contributor-level implementation detail, continue to the developer guide page [Browser-to-Companion Trust Model](../../../../0.7/developer-guide/companion-architecture/browser-to-companion-trust-model/).\n\n## Preference Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%APPDATA%\\app.sambee.companion\\` |\n| macOS | `~/Library/Application Support/app.sambee.companion/` |\n| Linux | `~/.local/share/app.sambee.companion/` |\n\nDeleting `user-preferences.json` and `app-preferences.json` resets companion settings.\n\n## Log Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%LOCALAPPDATA%\\Sambee\\Companion\\logs\\sambee-companion.log` |\n| macOS | `~/Library/Application Support/app.sambee.companion/logs/sambee-companion.log` |\n| Linux | `~/.local/share/sambee-companion/logs/sambee-companion.log` |\n\nThe companion writes both Rust-backend messages and TypeScript-frontend messages into the same rotating log file.\n\n## Log Levels\n\n| Level | When captured | Typical use |\n|---|---|---|\n| `error` | Always | failures that stop an operation from completing |\n| `warn` | Always | degraded but non-fatal behavior |\n| `info` | Verbose mode only | lifecycle steps and state transitions |\n| `debug` | Verbose mode only for Sambee app and frontend logs | detailed diagnostic context |\n\nErrors and warnings are always written, even when verbose logging is off. That keeps production incidents diagnosable without requiring the user to reproduce them in a special logging mode.\n\nNormal verbose logging keeps dependency transport logs quiet. HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls` are enabled separately because they can be very noisy.\n\n## Logging Controls\n\nLogging settings are read once at startup, so restart the companion after changing logging registry values or logging environment variables.\n\nTwo logging toggles are available:\n\n| Setting | Purpose |\n|---|---|\n| `VerboseLogging` | Enables verbose Sambee app and frontend logs. |\n| `TransportLogging` | Enables HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls`. |\n\n### Windows Registry Values\n\nOn Windows, configure logging through registry values under:\n\n```text\nHKEY_CURRENT_USER\\Software\\Sambee\\Companion\n```\n\nUse type `REG_DWORD`. A non-zero value enables the setting. A missing value or `0` leaves the setting disabled.\n\nTo enable verbose Sambee app and frontend logs:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 1 /f\n```\n\nTo enable HTTP transport diagnostics:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 1 /f\n```\n\nTo disable them again:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 0 /f\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 0 /f\n```\n\nRestart Companion after changing either registry value.\n\n### Linux and macOS Environment Variables\n\nOn Linux and macOS, launch the companion with environment variables for the logging modes you need.\n\nVerbose Sambee app and frontend logs:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 ./sambee-companion\n```\n\nHTTP transport diagnostics:\n\n```bash\nSAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nYou can combine both logging modes:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 SAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nThe environment variables are also available on Windows for one-off terminal-launched debugging and take precedence over the registry values. Use `0` or `false` to force a setting off for that launch.\n\nUse verbose logging when the normal log file does not explain why startup, local-drive access, or file-return workflows are failing. Add transport diagnostics when you need HTTP, TLS, proxy, or HTTP/2 details.\n\n## Support Log Checklist\n\nWhen collecting Companion logs for a native-editing issue, include:\n\n- Whether the `Sambee Authentication` window appeared.\n- Whether the failure happened during token exchange, file-info lookup, lock acquisition, download, upload, lock release, or heartbeat.\n- Whether Companion reported a lifecycle state such as renewal required, authentication failed, lock lost, or recovery required.\n- The reverse proxy or SSO product in front of Sambee, if one is used.\n- The Companion log file from the affected desktop.\n\nWhen verbose logging is enabled, include any operation or lock identifiers shown near the failing step. Those identifiers help correlate token exchange, lock acquisition, renewal, upload, and release events without exposing the secret material itself.\n\nCompanion sanitizes URLs before writing request diagnostics. Sensitive query values such as tokens, secrets, passwords, cookies, authorization data, sessions, keys, and theme payloads should not appear in support logs.\n\n## Log Rotation\n\nThe companion rotates logs automatically to avoid unbounded disk growth.\n\n- Maximum file size: 5 MB per log file.\n- Maximum files: 3 total, including the active file.\n- Worst-case disk usage: About 15 MB.\n\nRotation uses the usual numbered-copy scheme: the active `.log` becomes `.log.1`, the previous `.log.1` becomes `.log.2`, and the oldest rotated file is removed.\n\n## Log Format\n\nEach line follows this structure:\n\n```text\nYYYY-MM-DDThh:mm:ss.mmmZ LEVEL [module] message\n```\n\nExample:\n\n```text\n2026-02-17T14:30:45.123Z INFO  [sambee_companion_lib] Step 1: Exchanging URI token...\n2026-02-17T14:30:45.456Z ERROR [frontend] Upload failed: network timeout\n2026-02-17T14:30:46.789Z WARN  [sambee_companion_lib::commands::upload] Upload attempt 1/3 failed: connection refused\n```\n\nFrontend messages use the module target `frontend` so you can distinguish browser-side UI logging from Rust-side command and backend behavior.\n\n## How Logging Reaches the File\n\nThe companion uses one unified file-log pipeline.\n\n### Rust Side\n\nThe Rust logging module in `companion/src-tauri/src/logging.rs` implements the `log::Log` trait. Existing Rust-side `info!()`, `warn!()`, `error!()`, and `debug!()` calls therefore write into the same rotating companion log file.\n\nIf file logging initialization fails, the app falls back to stderr logging so startup can still proceed and terminal-launched sessions still have diagnostic output.\n\n### Frontend Side\n\nThe frontend logger in `companion/src/lib/logger.ts` writes to both:\n\n- The browser console for local developer-tools visibility.\n- The Rust backend through the `log_from_frontend` Tauri command so the same message lands in the file log.\n\nThat means support logs can contain both frontend and backend events in one timeline.\n\nThe frontend logger is fire-and-forget. Logging should never block the UI or surface a user-facing error because the log write itself failed.\n\n## Windows Webview2 Runtime Data\n\nOn Windows, the embedded WebView2 runtime stores its data at:\n\n- `%LOCALAPPDATA%\\app.sambee.companion\\EBWebView\\`\n\nThis directory is runtime-managed and is recreated automatically if removed.\n", "1.0": "+++\ntitle = \"Companion Support Reference\"\n+++\n\n## Communication and Security Model\n\nSambee uses two different browser-to-companion paths, depending on the workflow.\n\n- Local-drive browsing uses the companion's localhost API on `127.0.0.1:21549`.\n- Real-time local directory updates use a localhost WebSocket on the same port.\n- Desktop-app opening uses the `sambee://` custom URI scheme.\n\nThe localhost API is bound to the local machine only. It is not meant for remote network access.\n\nLocalhost traffic is authenticated after pairing, but it is not transport-encrypted.\n\n- HTTP requests use an HMAC derived from a shared secret and a current timestamp.\n- WebSocket and browser resource URLs use the same HMAC model through query parameters because browsers cannot attach custom headers in those cases.\n- The companion rejects requests outside the allowed clock-skew window.\n- Pairing is scoped to the browser origin, not just to the machine as a whole.\n\nThe shared secret is created only after the user confirms the same pairing code in both the browser and the companion. The companion stores its copy in the OS credential store. The browser stores its copy locally for that paired browser profile at that Sambee origin.\n\nIf you need contributor-level implementation detail, continue to the developer guide page [Browser-to-Companion Trust Model](../../../../0.7/developer-guide/companion-architecture/browser-to-companion-trust-model/).\n\n## Preference Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%APPDATA%\\app.sambee.companion\\` |\n| macOS | `~/Library/Application Support/app.sambee.companion/` |\n| Linux | `~/.local/share/app.sambee.companion/` |\n\nDeleting `user-preferences.json` and `app-preferences.json` resets companion settings.\n\n## Log Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%LOCALAPPDATA%\\Sambee\\Companion\\logs\\sambee-companion.log` |\n| macOS | `~/Library/Application Support/app.sambee.companion/logs/sambee-companion.log` |\n| Linux | `~/.local/share/sambee-companion/logs/sambee-companion.log` |\n\nThe companion writes both Rust-backend messages and TypeScript-frontend messages into the same rotating log file.\n\n## Log Levels\n\n| Level | When captured | Typical use |\n|---|---|---|\n| `error` | Always | failures that stop an operation from completing |\n| `warn` | Always | degraded but non-fatal behavior |\n| `info` | Verbose mode only | lifecycle steps and state transitions |\n| `debug` | Verbose mode only for Sambee app and frontend logs | detailed diagnostic context |\n\nErrors and warnings are always written, even when verbose logging is off. That keeps production incidents diagnosable without requiring the user to reproduce them in a special logging mode.\n\nNormal verbose logging keeps dependency transport logs quiet. HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls` are enabled separately because they can be very noisy.\n\n## Logging Controls\n\nLogging settings are read once at startup, so restart the companion after changing logging registry values or logging environment variables.\n\nTwo logging toggles are available:\n\n| Setting | Purpose |\n|---|---|\n| `VerboseLogging` | Enables verbose Sambee app and frontend logs. |\n| `TransportLogging` | Enables HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls`. |\n\n### Windows Registry Values\n\nOn Windows, configure logging through registry values under:\n\n```text\nHKEY_CURRENT_USER\\Software\\Sambee\\Companion\n```\n\nUse type `REG_DWORD`. A non-zero value enables the setting. A missing value or `0` leaves the setting disabled.\n\nTo enable verbose Sambee app and frontend logs:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 1 /f\n```\n\nTo enable HTTP transport diagnostics:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 1 /f\n```\n\nTo disable them again:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 0 /f\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 0 /f\n```\n\nRestart Companion after changing either registry value.\n\n### Linux and macOS Environment Variables\n\nOn Linux and macOS, launch the companion with environment variables for the logging modes you need.\n\nVerbose Sambee app and frontend logs:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 ./sambee-companion\n```\n\nHTTP transport diagnostics:\n\n```bash\nSAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nYou can combine both logging modes:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 SAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nThe environment variables are also available on Windows for one-off terminal-launched debugging and take precedence over the registry values. Use `0` or `false` to force a setting off for that launch.\n\nUse verbose logging when the normal log file does not explain why startup, local-drive access, or file-return workflows are failing. Add transport diagnostics when you need HTTP, TLS, proxy, or HTTP/2 details.\n\n## Support Log Checklist\n\nWhen collecting Companion logs for a native-editing issue, include:\n\n- Whether the `Sambee Authentication` window appeared.\n- Whether the failure happened during token exchange, file-info lookup, lock acquisition, download, upload, lock release, or heartbeat.\n- Whether Companion reported a lifecycle state such as renewal required, authentication failed, lock lost, or recovery required.\n- The reverse proxy or SSO product in front of Sambee, if one is used.\n- The Companion log file from the affected desktop.\n\nWhen verbose logging is enabled, include any operation or lock identifiers shown near the failing step. Those identifiers help correlate token exchange, lock acquisition, renewal, upload, and release events without exposing the secret material itself.\n\nCompanion sanitizes URLs before writing request diagnostics. Sensitive query values such as tokens, secrets, passwords, cookies, authorization data, sessions, keys, and theme payloads should not appear in support logs.\n\n## Log Rotation\n\nThe companion rotates logs automatically to avoid unbounded disk growth.\n\n- Maximum file size: 5 MB per log file.\n- Maximum files: 3 total, including the active file.\n- Worst-case disk usage: About 15 MB.\n\nRotation uses the usual numbered-copy scheme: the active `.log` becomes `.log.1`, the previous `.log.1` becomes `.log.2`, and the oldest rotated file is removed.\n\n## Log Format\n\nEach line follows this structure:\n\n```text\nYYYY-MM-DDThh:mm:ss.mmmZ LEVEL [module] message\n```\n\nExample:\n\n```text\n2026-02-17T14:30:45.123Z INFO  [sambee_companion_lib] Step 1: Exchanging URI token...\n2026-02-17T14:30:45.456Z ERROR [frontend] Upload failed: network timeout\n2026-02-17T14:30:46.789Z WARN  [sambee_companion_lib::commands::upload] Upload attempt 1/3 failed: connection refused\n```\n\nFrontend messages use the module target `frontend` so you can distinguish browser-side UI logging from Rust-side command and backend behavior.\n\n## How Logging Reaches the File\n\nThe companion uses one unified file-log pipeline.\n\n### Rust Side\n\nThe Rust logging module in `companion/src-tauri/src/logging.rs` implements the `log::Log` trait. Existing Rust-side `info!()`, `warn!()`, `error!()`, and `debug!()` calls therefore write into the same rotating companion log file.\n\nIf file logging initialization fails, the app falls back to stderr logging so startup can still proceed and terminal-launched sessions still have diagnostic output.\n\n### Frontend Side\n\nThe frontend logger in `companion/src/lib/logger.ts` writes to both:\n\n- The browser console for local developer-tools visibility.\n- The Rust backend through the `log_from_frontend` Tauri command so the same message lands in the file log.\n\nThat means support logs can contain both frontend and backend events in one timeline.\n\nThe frontend logger is fire-and-forget. Logging should never block the UI or surface a user-facing error because the log write itself failed.\n\n## Windows Webview2 Runtime Data\n\nOn Windows, the embedded WebView2 runtime stores its data at:\n\n- `%LOCALAPPDATA%\\app.sambee.companion\\EBWebView\\`\n\nThis directory is runtime-managed and is recreated automatically if removed.\n", "2.0": "+++\ntitle = \"Companion Support Reference\"\n+++\n\n## Communication and Security Model\n\nSambee uses two different browser-to-companion paths, depending on the workflow.\n\n- Local-drive browsing uses the companion's localhost API on `127.0.0.1:21549`.\n- Real-time local directory updates use a localhost WebSocket on the same port.\n- Desktop-app opening uses the `sambee://` custom URI scheme.\n\nThe localhost API is bound to the local machine only. It is not meant for remote network access.\n\nLocalhost traffic is authenticated after pairing, but it is not transport-encrypted.\n\n- HTTP requests use an HMAC derived from a shared secret and a current timestamp.\n- WebSocket and browser resource URLs use the same HMAC model through query parameters because browsers cannot attach custom headers in those cases.\n- The companion rejects requests outside the allowed clock-skew window.\n- Pairing is scoped to the browser origin, not just to the machine as a whole.\n\nThe shared secret is created only after the user confirms the same pairing code in both the browser and the companion. The companion stores its copy in the OS credential store. The browser stores its copy locally for that paired browser profile at that Sambee origin.\n\nIf you need contributor-level implementation detail, continue to the developer guide page [Browser-to-Companion Trust Model](../../../../0.7/developer-guide/companion-architecture/browser-to-companion-trust-model/).\n\n## Preference Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%APPDATA%\\app.sambee.companion\\` |\n| macOS | `~/Library/Application Support/app.sambee.companion/` |\n| Linux | `~/.local/share/app.sambee.companion/` |\n\nDeleting `user-preferences.json` and `app-preferences.json` resets companion settings.\n\n## Log Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%LOCALAPPDATA%\\Sambee\\Companion\\logs\\sambee-companion.log` |\n| macOS | `~/Library/Application Support/app.sambee.companion/logs/sambee-companion.log` |\n| Linux | `~/.local/share/sambee-companion/logs/sambee-companion.log` |\n\nThe companion writes both Rust-backend messages and TypeScript-frontend messages into the same rotating log file.\n\n## Log Levels\n\n| Level | When captured | Typical use |\n|---|---|---|\n| `error` | Always | failures that stop an operation from completing |\n| `warn` | Always | degraded but non-fatal behavior |\n| `info` | Verbose mode only | lifecycle steps and state transitions |\n| `debug` | Verbose mode only for Sambee app and frontend logs | detailed diagnostic context |\n\nErrors and warnings are always written, even when verbose logging is off. That keeps production incidents diagnosable without requiring the user to reproduce them in a special logging mode.\n\nNormal verbose logging keeps dependency transport logs quiet. HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls` are enabled separately because they can be very noisy.\n\n## Logging Controls\n\nLogging settings are read once at startup, so restart the companion after changing logging registry values or logging environment variables.\n\nTwo logging toggles are available:\n\n| Setting | Purpose |\n|---|---|\n| `VerboseLogging` | Enables verbose Sambee app and frontend logs. |\n| `TransportLogging` | Enables HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls`. |\n\n### Windows Registry Values\n\nOn Windows, configure logging through registry values under:\n\n```text\nHKEY_CURRENT_USER\\Software\\Sambee\\Companion\n```\n\nUse type `REG_DWORD`. A non-zero value enables the setting. A missing value or `0` leaves the setting disabled.\n\nTo enable verbose Sambee app and frontend logs:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 1 /f\n```\n\nTo enable HTTP transport diagnostics:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 1 /f\n```\n\nTo disable them again:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 0 /f\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 0 /f\n```\n\nRestart Companion after changing either registry value.\n\n### Linux and macOS Environment Variables\n\nOn Linux and macOS, launch the companion with environment variables for the logging modes you need.\n\nVerbose Sambee app and frontend logs:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 ./sambee-companion\n```\n\nHTTP transport diagnostics:\n\n```bash\nSAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nYou can combine both logging modes:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 SAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nThe environment variables are also available on Windows for one-off terminal-launched debugging and take precedence over the registry values. Use `0` or `false` to force a setting off for that launch.\n\nUse verbose logging when the normal log file does not explain why startup, local-drive access, or file-return workflows are failing. Add transport diagnostics when you need HTTP, TLS, proxy, or HTTP/2 details.\n\n## Support Log Checklist\n\nWhen collecting Companion logs for a native-editing issue, include:\n\n- Whether the `Sambee Authentication` window appeared.\n- Whether the failure happened during token exchange, file-info lookup, lock acquisition, download, upload, lock release, or heartbeat.\n- Whether Companion reported a lifecycle state such as renewal required, authentication failed, lock lost, or recovery required.\n- The reverse proxy or SSO product in front of Sambee, if one is used.\n- The Companion log file from the affected desktop.\n\nWhen verbose logging is enabled, include any operation or lock identifiers shown near the failing step. Those identifiers help correlate token exchange, lock acquisition, renewal, upload, and release events without exposing the secret material itself.\n\nCompanion sanitizes URLs before writing request diagnostics. Sensitive query values such as tokens, secrets, passwords, cookies, authorization data, sessions, keys, and theme payloads should not appear in support logs.\n\n## Log Rotation\n\nThe companion rotates logs automatically to avoid unbounded disk growth.\n\n- Maximum file size: 5 MB per log file.\n- Maximum files: 3 total, including the active file.\n- Worst-case disk usage: About 15 MB.\n\nRotation uses the usual numbered-copy scheme: the active `.log` becomes `.log.1`, the previous `.log.1` becomes `.log.2`, and the oldest rotated file is removed.\n\n## Log Format\n\nEach line follows this structure:\n\n```text\nYYYY-MM-DDThh:mm:ss.mmmZ LEVEL [module] message\n```\n\nExample:\n\n```text\n2026-02-17T14:30:45.123Z INFO  [sambee_companion_lib] Step 1: Exchanging URI token...\n2026-02-17T14:30:45.456Z ERROR [frontend] Upload failed: network timeout\n2026-02-17T14:30:46.789Z WARN  [sambee_companion_lib::commands::upload] Upload attempt 1/3 failed: connection refused\n```\n\nFrontend messages use the module target `frontend` so you can distinguish browser-side UI logging from Rust-side command and backend behavior.\n\n## How Logging Reaches the File\n\nThe companion uses one unified file-log pipeline.\n\n### Rust Side\n\nThe Rust logging module in `companion/src-tauri/src/logging.rs` implements the `log::Log` trait. Existing Rust-side `info!()`, `warn!()`, `error!()`, and `debug!()` calls therefore write into the same rotating companion log file.\n\nIf file logging initialization fails, the app falls back to stderr logging so startup can still proceed and terminal-launched sessions still have diagnostic output.\n\n### Frontend Side\n\nThe frontend logger in `companion/src/lib/logger.ts` writes to both:\n\n- The browser console for local developer-tools visibility.\n- The Rust backend through the `log_from_frontend` Tauri command so the same message lands in the file log.\n\nThat means support logs can contain both frontend and backend events in one timeline.\n\nThe frontend logger is fire-and-forget. Logging should never block the UI or surface a user-facing error because the log write itself failed.\n\n## Windows Webview2 Runtime Data\n\nOn Windows, the embedded WebView2 runtime stores its data at:\n\n- `%LOCALAPPDATA%\\app.sambee.companion\\EBWebView\\`\n\nThis directory is runtime-managed and is recreated automatically if removed.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Companion Support Reference\"\n+++\n\n## Communication and Security Model\n\nSambee uses two different browser-to-companion paths, depending on the workflow.\n\n- Local-drive browsing uses the companion's localhost API on `127.0.0.1:21549`.\n- Real-time local directory updates use a localhost WebSocket on the same port.\n- Desktop-app opening uses the `sambee://` custom URI scheme.\n\nThe localhost API is bound to the local machine only. It is not meant for remote network access.\n\nLocalhost traffic is authenticated after pairing, but it is not transport-encrypted.\n\n- HTTP requests use an HMAC derived from a shared secret and a current timestamp.\n- WebSocket and browser resource URLs use the same HMAC model through query parameters because browsers cannot attach custom headers in those cases.\n- The companion rejects requests outside the allowed clock-skew window.\n- Pairing is scoped to the browser origin, not just to the machine as a whole.\n\nThe shared secret is created only after the user confirms the same pairing code in both the browser and the companion. The companion stores its copy in the OS credential store. The browser stores its copy locally for that paired browser profile at that Sambee origin.\n\nIf you need contributor-level implementation detail, continue to the developer guide page [Browser-to-Companion Trust Model](../../../../0.7/developer-guide/companion-architecture/browser-to-companion-trust-model/).\n\n## Preference Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%APPDATA%\\app.sambee.companion\\` |\n| macOS | `~/Library/Application Support/app.sambee.companion/` |\n| Linux | `~/.local/share/app.sambee.companion/` |\n\nDeleting `user-preferences.json` and `app-preferences.json` resets companion settings.\n\n## Log Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%LOCALAPPDATA%\\Sambee\\Companion\\logs\\sambee-companion.log` |\n| macOS | `~/Library/Application Support/app.sambee.companion/logs/sambee-companion.log` |\n| Linux | `~/.local/share/sambee-companion/logs/sambee-companion.log` |\n\nThe companion writes both Rust-backend messages and TypeScript-frontend messages into the same rotating log file.\n\n## Log Levels\n\n| Level | When captured | Typical use |\n|---|---|---|\n| `error` | Always | failures that stop an operation from completing |\n| `warn` | Always | degraded but non-fatal behavior |\n| `info` | Verbose mode only | lifecycle steps and state transitions |\n| `debug` | Verbose mode only for Sambee app and frontend logs | detailed diagnostic context |\n\nErrors and warnings are always written, even when verbose logging is off. That keeps production incidents diagnosable without requiring the user to reproduce them in a special logging mode.\n\nNormal verbose logging keeps dependency transport logs quiet. HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls` are enabled separately because they can be very noisy.\n\n## Logging Controls\n\nLogging settings are read once at startup, so restart the companion after changing logging registry values or logging environment variables.\n\nTwo logging toggles are available:\n\n| Setting | Purpose |\n|---|---|\n| `VerboseLogging` | Enables verbose Sambee app and frontend logs. |\n| `TransportLogging` | Enables HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls`. |\n\n### Windows Registry Values\n\nOn Windows, configure logging through registry values under:\n\n```text\nHKEY_CURRENT_USER\\Software\\Sambee\\Companion\n```\n\nUse type `REG_DWORD`. A non-zero value enables the setting. A missing value or `0` leaves the setting disabled.\n\nTo enable verbose Sambee app and frontend logs:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 1 /f\n```\n\nTo enable HTTP transport diagnostics:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 1 /f\n```\n\nTo disable them again:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 0 /f\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 0 /f\n```\n\nRestart Companion after changing either registry value.\n\n### Linux and macOS Environment Variables\n\nOn Linux and macOS, launch the companion with environment variables for the logging modes you need.\n\nVerbose Sambee app and frontend logs:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 ./sambee-companion\n```\n\nHTTP transport diagnostics:\n\n```bash\nSAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nYou can combine both logging modes:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 SAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nThe environment variables are also available on Windows for one-off terminal-launched debugging and take precedence over the registry values. Use `0` or `false` to force a setting off for that launch.\n\nUse verbose logging when the normal log file does not explain why startup, local-drive access, or file-return workflows are failing. Add transport diagnostics when you need HTTP, TLS, proxy, or HTTP/2 details.\n\n## Support Log Checklist\n\nWhen collecting Companion logs for a native-editing issue, include:\n\n- Whether the `Sambee Authentication` window appeared.\n- Whether the failure happened during token exchange, file-info lookup, lock acquisition, download, upload, lock release, or heartbeat.\n- Whether Companion reported a lifecycle state such as renewal required, authentication failed, lock lost, or recovery required.\n- The reverse proxy or SSO product in front of Sambee, if one is used.\n- The Companion log file from the affected desktop.\n\nWhen verbose logging is enabled, include any operation or lock identifiers shown near the failing step. Those identifiers help correlate token exchange, lock acquisition, renewal, upload, and release events without exposing the secret material itself.\n\nCompanion sanitizes URLs before writing request diagnostics. Sensitive query values such as tokens, secrets, passwords, cookies, authorization data, sessions, keys, and theme payloads should not appear in support logs.\n\n## Log Rotation\n\nThe companion rotates logs automatically to avoid unbounded disk growth.\n\n- Maximum file size: 5 MB per log file.\n- Maximum files: 3 total, including the active file.\n- Worst-case disk usage: About 15 MB.\n\nRotation uses the usual numbered-copy scheme: the active `.log` becomes `.log.1`, the previous `.log.1` becomes `.log.2`, and the oldest rotated file is removed.\n\n## Log Format\n\nEach line follows this structure:\n\n```text\nYYYY-MM-DDThh:mm:ss.mmmZ LEVEL [module] message\n```\n\nExample:\n\n```text\n2026-02-17T14:30:45.123Z INFO  [sambee_companion_lib] Step 1: Exchanging URI token...\n2026-02-17T14:30:45.456Z ERROR [frontend] Upload failed: network timeout\n2026-02-17T14:30:46.789Z WARN  [sambee_companion_lib::commands::upload] Upload attempt 1/3 failed: connection refused\n```\n\nFrontend messages use the module target `frontend` so you can distinguish browser-side UI logging from Rust-side command and backend behavior.\n\n## How Logging Reaches the File\n\nThe companion uses one unified file-log pipeline.\n\n### Rust Side\n\nThe Rust logging module in `companion/src-tauri/src/logging.rs` implements the `log::Log` trait. Existing Rust-side `info!()`, `warn!()`, `error!()`, and `debug!()` calls therefore write into the same rotating companion log file.\n\nIf file logging initialization fails, the app falls back to stderr logging so startup can still proceed and terminal-launched sessions still have diagnostic output.\n\n### Frontend Side\n\nThe frontend logger in `companion/src/lib/logger.ts` writes to both:\n\n- The browser console for local developer-tools visibility.\n- The Rust backend through the `log_from_frontend` Tauri command so the same message lands in the file log.\n\nThat means support logs can contain both frontend and backend events in one timeline.\n\nThe frontend logger is fire-and-forget. Logging should never block the UI or surface a user-facing error because the log write itself failed.\n\n## Windows Webview2 Runtime Data\n\nOn Windows, the embedded WebView2 runtime stores its data at:\n\n- `%LOCALAPPDATA%\\app.sambee.companion\\EBWebView\\`\n\nThis directory is runtime-managed and is recreated automatically if removed.\n", "0.8": "+++\ntitle = \"Companion Support Reference\"\n+++\n\n## Communication and Security Model\n\nSambee uses two different browser-to-companion paths, depending on the workflow.\n\n- Local-drive browsing uses the companion's localhost API on `127.0.0.1:21549`.\n- Real-time local directory updates use a localhost WebSocket on the same port.\n- Desktop-app opening uses the `sambee://` custom URI scheme.\n\nThe localhost API is bound to the local machine only. It is not meant for remote network access.\n\nLocalhost traffic is authenticated after pairing, but it is not transport-encrypted.\n\n- HTTP requests use an HMAC derived from a shared secret and a current timestamp.\n- WebSocket and browser resource URLs use the same HMAC model through query parameters because browsers cannot attach custom headers in those cases.\n- The companion rejects requests outside the allowed clock-skew window.\n- Pairing is scoped to the browser origin, not just to the machine as a whole.\n\nThe shared secret is created only after the user confirms the same pairing code in both the browser and the companion. The companion stores its copy in the OS credential store. The browser stores its copy locally for that paired browser profile at that Sambee origin.\n\nIf you need contributor-level implementation detail, continue to the developer guide page [Browser-to-Companion Trust Model](../../../../0.7/developer-guide/companion-architecture/browser-to-companion-trust-model/).\n\n## Preference Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%APPDATA%\\app.sambee.companion\\` |\n| macOS | `~/Library/Application Support/app.sambee.companion/` |\n| Linux | `~/.local/share/app.sambee.companion/` |\n\nDeleting `user-preferences.json` and `app-preferences.json` resets companion settings.\n\n## Log Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%LOCALAPPDATA%\\Sambee\\Companion\\logs\\sambee-companion.log` |\n| macOS | `~/Library/Application Support/app.sambee.companion/logs/sambee-companion.log` |\n| Linux | `~/.local/share/sambee-companion/logs/sambee-companion.log` |\n\nThe companion writes both Rust-backend messages and TypeScript-frontend messages into the same rotating log file.\n\n## Log Levels\n\n| Level | When captured | Typical use |\n|---|---|---|\n| `error` | Always | failures that stop an operation from completing |\n| `warn` | Always | degraded but non-fatal behavior |\n| `info` | Verbose mode only | lifecycle steps and state transitions |\n| `debug` | Verbose mode only for Sambee app and frontend logs | detailed diagnostic context |\n\nErrors and warnings are always written, even when verbose logging is off. That keeps production incidents diagnosable without requiring the user to reproduce them in a special logging mode.\n\nNormal verbose logging keeps dependency transport logs quiet. HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls` are enabled separately because they can be very noisy.\n\n## Logging Controls\n\nLogging settings are read once at startup, so restart the companion after changing logging registry values or logging environment variables.\n\nTwo logging toggles are available:\n\n| Setting | Purpose |\n|---|---|\n| `VerboseLogging` | Enables verbose Sambee app and frontend logs. |\n| `TransportLogging` | Enables HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls`. |\n\n### Windows Registry Values\n\nOn Windows, configure logging through registry values under:\n\n```text\nHKEY_CURRENT_USER\\Software\\Sambee\\Companion\n```\n\nUse type `REG_DWORD`. A non-zero value enables the setting. A missing value or `0` leaves the setting disabled.\n\nTo enable verbose Sambee app and frontend logs:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 1 /f\n```\n\nTo enable HTTP transport diagnostics:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 1 /f\n```\n\nTo disable them again:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 0 /f\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 0 /f\n```\n\nRestart Companion after changing either registry value.\n\n### Linux and macOS Environment Variables\n\nOn Linux and macOS, launch the companion with environment variables for the logging modes you need.\n\nVerbose Sambee app and frontend logs:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 ./sambee-companion\n```\n\nHTTP transport diagnostics:\n\n```bash\nSAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nYou can combine both logging modes:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 SAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nThe environment variables are also available on Windows for one-off terminal-launched debugging and take precedence over the registry values. Use `0` or `false` to force a setting off for that launch.\n\nUse verbose logging when the normal log file does not explain why startup, local-drive access, or file-return workflows are failing. Add transport diagnostics when you need HTTP, TLS, proxy, or HTTP/2 details.\n\n## Support Log Checklist\n\nWhen collecting Companion logs for a native-editing issue, include:\n\n- Whether the `Sambee Authentication` window appeared.\n- Whether the failure happened during token exchange, file-info lookup, lock acquisition, download, upload, lock release, or heartbeat.\n- Whether Companion reported a lifecycle state such as renewal required, authentication failed, lock lost, or recovery required.\n- The reverse proxy or SSO product in front of Sambee, if one is used.\n- The Companion log file from the affected desktop.\n\nWhen verbose logging is enabled, include any operation or lock identifiers shown near the failing step. Those identifiers help correlate token exchange, lock acquisition, renewal, upload, and release events without exposing the secret material itself.\n\nCompanion sanitizes URLs before writing request diagnostics. Sensitive query values such as tokens, secrets, passwords, cookies, authorization data, sessions, keys, and theme payloads should not appear in support logs.\n\n## Log Rotation\n\nThe companion rotates logs automatically to avoid unbounded disk growth.\n\n- Maximum file size: 5 MB per log file.\n- Maximum files: 3 total, including the active file.\n- Worst-case disk usage: About 15 MB.\n\nRotation uses the usual numbered-copy scheme: the active `.log` becomes `.log.1`, the previous `.log.1` becomes `.log.2`, and the oldest rotated file is removed.\n\n## Log Format\n\nEach line follows this structure:\n\n```text\nYYYY-MM-DDThh:mm:ss.mmmZ LEVEL [module] message\n```\n\nExample:\n\n```text\n2026-02-17T14:30:45.123Z INFO  [sambee_companion_lib] Step 1: Exchanging URI token...\n2026-02-17T14:30:45.456Z ERROR [frontend] Upload failed: network timeout\n2026-02-17T14:30:46.789Z WARN  [sambee_companion_lib::commands::upload] Upload attempt 1/3 failed: connection refused\n```\n\nFrontend messages use the module target `frontend` so you can distinguish browser-side UI logging from Rust-side command and backend behavior.\n\n## How Logging Reaches the File\n\nThe companion uses one unified file-log pipeline.\n\n### Rust Side\n\nThe Rust logging module in `companion/src-tauri/src/logging.rs` implements the `log::Log` trait. Existing Rust-side `info!()`, `warn!()`, `error!()`, and `debug!()` calls therefore write into the same rotating companion log file.\n\nIf file logging initialization fails, the app falls back to stderr logging so startup can still proceed and terminal-launched sessions still have diagnostic output.\n\n### Frontend Side\n\nThe frontend logger in `companion/src/lib/logger.ts` writes to both:\n\n- The browser console for local developer-tools visibility.\n- The Rust backend through the `log_from_frontend` Tauri command so the same message lands in the file log.\n\nThat means support logs can contain both frontend and backend events in one timeline.\n\nThe frontend logger is fire-and-forget. Logging should never block the UI or surface a user-facing error because the log write itself failed.\n\n## Windows Webview2 Runtime Data\n\nOn Windows, the embedded WebView2 runtime stores its data at:\n\n- `%LOCALAPPDATA%\\app.sambee.companion\\EBWebView\\`\n\nThis directory is runtime-managed and is recreated automatically if removed.\n", "0.9": "+++\ntitle = \"Companion Support Reference\"\n+++\n\n## Communication and Security Model\n\nSambee uses two different browser-to-companion paths, depending on the workflow.\n\n- Local-drive browsing uses the companion's localhost API on `127.0.0.1:21549`.\n- Real-time local directory updates use a localhost WebSocket on the same port.\n- Desktop-app opening uses the `sambee://` custom URI scheme.\n\nThe localhost API is bound to the local machine only. It is not meant for remote network access.\n\nLocalhost traffic is authenticated after pairing, but it is not transport-encrypted.\n\n- HTTP requests use an HMAC derived from a shared secret and a current timestamp.\n- WebSocket and browser resource URLs use the same HMAC model through query parameters because browsers cannot attach custom headers in those cases.\n- The companion rejects requests outside the allowed clock-skew window.\n- Pairing is scoped to the browser origin, not just to the machine as a whole.\n\nThe shared secret is created only after the user confirms the same pairing code in both the browser and the companion. The companion stores its copy in the OS credential store. The browser stores its copy locally for that paired browser profile at that Sambee origin.\n\nIf you need contributor-level implementation detail, continue to the developer guide page [Browser-to-Companion Trust Model](../../../../0.7/developer-guide/companion-architecture/browser-to-companion-trust-model/).\n\n## Preference Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%APPDATA%\\app.sambee.companion\\` |\n| macOS | `~/Library/Application Support/app.sambee.companion/` |\n| Linux | `~/.local/share/app.sambee.companion/` |\n\nDeleting `user-preferences.json` and `app-preferences.json` resets companion settings.\n\n## Log Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%LOCALAPPDATA%\\Sambee\\Companion\\logs\\sambee-companion.log` |\n| macOS | `~/Library/Application Support/app.sambee.companion/logs/sambee-companion.log` |\n| Linux | `~/.local/share/sambee-companion/logs/sambee-companion.log` |\n\nThe companion writes both Rust-backend messages and TypeScript-frontend messages into the same rotating log file.\n\n## Log Levels\n\n| Level | When captured | Typical use |\n|---|---|---|\n| `error` | Always | failures that stop an operation from completing |\n| `warn` | Always | degraded but non-fatal behavior |\n| `info` | Verbose mode only | lifecycle steps and state transitions |\n| `debug` | Verbose mode only for Sambee app and frontend logs | detailed diagnostic context |\n\nErrors and warnings are always written, even when verbose logging is off. That keeps production incidents diagnosable without requiring the user to reproduce them in a special logging mode.\n\nNormal verbose logging keeps dependency transport logs quiet. HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls` are enabled separately because they can be very noisy.\n\n## Logging Controls\n\nLogging settings are read once at startup, so restart the companion after changing logging registry values or logging environment variables.\n\nTwo logging toggles are available:\n\n| Setting | Purpose |\n|---|---|\n| `VerboseLogging` | Enables verbose Sambee app and frontend logs. |\n| `TransportLogging` | Enables HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls`. |\n\n### Windows Registry Values\n\nOn Windows, configure logging through registry values under:\n\n```text\nHKEY_CURRENT_USER\\Software\\Sambee\\Companion\n```\n\nUse type `REG_DWORD`. A non-zero value enables the setting. A missing value or `0` leaves the setting disabled.\n\nTo enable verbose Sambee app and frontend logs:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 1 /f\n```\n\nTo enable HTTP transport diagnostics:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 1 /f\n```\n\nTo disable them again:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 0 /f\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 0 /f\n```\n\nRestart Companion after changing either registry value.\n\n### Linux and macOS Environment Variables\n\nOn Linux and macOS, launch the companion with environment variables for the logging modes you need.\n\nVerbose Sambee app and frontend logs:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 ./sambee-companion\n```\n\nHTTP transport diagnostics:\n\n```bash\nSAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nYou can combine both logging modes:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 SAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nThe environment variables are also available on Windows for one-off terminal-launched debugging and take precedence over the registry values. Use `0` or `false` to force a setting off for that launch.\n\nUse verbose logging when the normal log file does not explain why startup, local-drive access, or file-return workflows are failing. Add transport diagnostics when you need HTTP, TLS, proxy, or HTTP/2 details.\n\n## Support Log Checklist\n\nWhen collecting Companion logs for a native-editing issue, include:\n\n- Whether the `Sambee Authentication` window appeared.\n- Whether the failure happened during token exchange, file-info lookup, lock acquisition, download, upload, lock release, or heartbeat.\n- Whether Companion reported a lifecycle state such as renewal required, authentication failed, lock lost, or recovery required.\n- The reverse proxy or SSO product in front of Sambee, if one is used.\n- The Companion log file from the affected desktop.\n\nWhen verbose logging is enabled, include any operation or lock identifiers shown near the failing step. Those identifiers help correlate token exchange, lock acquisition, renewal, upload, and release events without exposing the secret material itself.\n\nCompanion sanitizes URLs before writing request diagnostics. Sensitive query values such as tokens, secrets, passwords, cookies, authorization data, sessions, keys, and theme payloads should not appear in support logs.\n\n## Log Rotation\n\nThe companion rotates logs automatically to avoid unbounded disk growth.\n\n- Maximum file size: 5 MB per log file.\n- Maximum files: 3 total, including the active file.\n- Worst-case disk usage: About 15 MB.\n\nRotation uses the usual numbered-copy scheme: the active `.log` becomes `.log.1`, the previous `.log.1` becomes `.log.2`, and the oldest rotated file is removed.\n\n## Log Format\n\nEach line follows this structure:\n\n```text\nYYYY-MM-DDThh:mm:ss.mmmZ LEVEL [module] message\n```\n\nExample:\n\n```text\n2026-02-17T14:30:45.123Z INFO  [sambee_companion_lib] Step 1: Exchanging URI token...\n2026-02-17T14:30:45.456Z ERROR [frontend] Upload failed: network timeout\n2026-02-17T14:30:46.789Z WARN  [sambee_companion_lib::commands::upload] Upload attempt 1/3 failed: connection refused\n```\n\nFrontend messages use the module target `frontend` so you can distinguish browser-side UI logging from Rust-side command and backend behavior.\n\n## How Logging Reaches the File\n\nThe companion uses one unified file-log pipeline.\n\n### Rust Side\n\nThe Rust logging module in `companion/src-tauri/src/logging.rs` implements the `log::Log` trait. Existing Rust-side `info!()`, `warn!()`, `error!()`, and `debug!()` calls therefore write into the same rotating companion log file.\n\nIf file logging initialization fails, the app falls back to stderr logging so startup can still proceed and terminal-launched sessions still have diagnostic output.\n\n### Frontend Side\n\nThe frontend logger in `companion/src/lib/logger.ts` writes to both:\n\n- The browser console for local developer-tools visibility.\n- The Rust backend through the `log_from_frontend` Tauri command so the same message lands in the file log.\n\nThat means support logs can contain both frontend and backend events in one timeline.\n\nThe frontend logger is fire-and-forget. Logging should never block the UI or surface a user-facing error because the log write itself failed.\n\n## Windows Webview2 Runtime Data\n\nOn Windows, the embedded WebView2 runtime stores its data at:\n\n- `%LOCALAPPDATA%\\app.sambee.companion\\EBWebView\\`\n\nThis directory is runtime-managed and is recreated automatically if removed.\n", "1.0": "+++\ntitle = \"Companion Support Reference\"\n+++\n\n## Communication and Security Model\n\nSambee uses two different browser-to-companion paths, depending on the workflow.\n\n- Local-drive browsing uses the companion's localhost API on `127.0.0.1:21549`.\n- Real-time local directory updates use a localhost WebSocket on the same port.\n- Desktop-app opening uses the `sambee://` custom URI scheme.\n\nThe localhost API is bound to the local machine only. It is not meant for remote network access.\n\nLocalhost traffic is authenticated after pairing, but it is not transport-encrypted.\n\n- HTTP requests use an HMAC derived from a shared secret and a current timestamp.\n- WebSocket and browser resource URLs use the same HMAC model through query parameters because browsers cannot attach custom headers in those cases.\n- The companion rejects requests outside the allowed clock-skew window.\n- Pairing is scoped to the browser origin, not just to the machine as a whole.\n\nThe shared secret is created only after the user confirms the same pairing code in both the browser and the companion. The companion stores its copy in the OS credential store. The browser stores its copy locally for that paired browser profile at that Sambee origin.\n\nIf you need contributor-level implementation detail, continue to the developer guide page [Browser-to-Companion Trust Model](../../../../0.7/developer-guide/companion-architecture/browser-to-companion-trust-model/).\n\n## Preference Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%APPDATA%\\app.sambee.companion\\` |\n| macOS | `~/Library/Application Support/app.sambee.companion/` |\n| Linux | `~/.local/share/app.sambee.companion/` |\n\nDeleting `user-preferences.json` and `app-preferences.json` resets companion settings.\n\n## Log Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%LOCALAPPDATA%\\Sambee\\Companion\\logs\\sambee-companion.log` |\n| macOS | `~/Library/Application Support/app.sambee.companion/logs/sambee-companion.log` |\n| Linux | `~/.local/share/sambee-companion/logs/sambee-companion.log` |\n\nThe companion writes both Rust-backend messages and TypeScript-frontend messages into the same rotating log file.\n\n## Log Levels\n\n| Level | When captured | Typical use |\n|---|---|---|\n| `error` | Always | failures that stop an operation from completing |\n| `warn` | Always | degraded but non-fatal behavior |\n| `info` | Verbose mode only | lifecycle steps and state transitions |\n| `debug` | Verbose mode only for Sambee app and frontend logs | detailed diagnostic context |\n\nErrors and warnings are always written, even when verbose logging is off. That keeps production incidents diagnosable without requiring the user to reproduce them in a special logging mode.\n\nNormal verbose logging keeps dependency transport logs quiet. HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls` are enabled separately because they can be very noisy.\n\n## Logging Controls\n\nLogging settings are read once at startup, so restart the companion after changing logging registry values or logging environment variables.\n\nTwo logging toggles are available:\n\n| Setting | Purpose |\n|---|---|\n| `VerboseLogging` | Enables verbose Sambee app and frontend logs. |\n| `TransportLogging` | Enables HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls`. |\n\n### Windows Registry Values\n\nOn Windows, configure logging through registry values under:\n\n```text\nHKEY_CURRENT_USER\\Software\\Sambee\\Companion\n```\n\nUse type `REG_DWORD`. A non-zero value enables the setting. A missing value or `0` leaves the setting disabled.\n\nTo enable verbose Sambee app and frontend logs:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 1 /f\n```\n\nTo enable HTTP transport diagnostics:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 1 /f\n```\n\nTo disable them again:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 0 /f\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 0 /f\n```\n\nRestart Companion after changing either registry value.\n\n### Linux and macOS Environment Variables\n\nOn Linux and macOS, launch the companion with environment variables for the logging modes you need.\n\nVerbose Sambee app and frontend logs:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 ./sambee-companion\n```\n\nHTTP transport diagnostics:\n\n```bash\nSAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nYou can combine both logging modes:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 SAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nThe environment variables are also available on Windows for one-off terminal-launched debugging and take precedence over the registry values. Use `0` or `false` to force a setting off for that launch.\n\nUse verbose logging when the normal log file does not explain why startup, local-drive access, or file-return workflows are failing. Add transport diagnostics when you need HTTP, TLS, proxy, or HTTP/2 details.\n\n## Support Log Checklist\n\nWhen collecting Companion logs for a native-editing issue, include:\n\n- Whether the `Sambee Authentication` window appeared.\n- Whether the failure happened during token exchange, file-info lookup, lock acquisition, download, upload, lock release, or heartbeat.\n- Whether Companion reported a lifecycle state such as renewal required, authentication failed, lock lost, or recovery required.\n- The reverse proxy or SSO product in front of Sambee, if one is used.\n- The Companion log file from the affected desktop.\n\nWhen verbose logging is enabled, include any operation or lock identifiers shown near the failing step. Those identifiers help correlate token exchange, lock acquisition, renewal, upload, and release events without exposing the secret material itself.\n\nCompanion sanitizes URLs before writing request diagnostics. Sensitive query values such as tokens, secrets, passwords, cookies, authorization data, sessions, keys, and theme payloads should not appear in support logs.\n\n## Log Rotation\n\nThe companion rotates logs automatically to avoid unbounded disk growth.\n\n- Maximum file size: 5 MB per log file.\n- Maximum files: 3 total, including the active file.\n- Worst-case disk usage: About 15 MB.\n\nRotation uses the usual numbered-copy scheme: the active `.log` becomes `.log.1`, the previous `.log.1` becomes `.log.2`, and the oldest rotated file is removed.\n\n## Log Format\n\nEach line follows this structure:\n\n```text\nYYYY-MM-DDThh:mm:ss.mmmZ LEVEL [module] message\n```\n\nExample:\n\n```text\n2026-02-17T14:30:45.123Z INFO  [sambee_companion_lib] Step 1: Exchanging URI token...\n2026-02-17T14:30:45.456Z ERROR [frontend] Upload failed: network timeout\n2026-02-17T14:30:46.789Z WARN  [sambee_companion_lib::commands::upload] Upload attempt 1/3 failed: connection refused\n```\n\nFrontend messages use the module target `frontend` so you can distinguish browser-side UI logging from Rust-side command and backend behavior.\n\n## How Logging Reaches the File\n\nThe companion uses one unified file-log pipeline.\n\n### Rust Side\n\nThe Rust logging module in `companion/src-tauri/src/logging.rs` implements the `log::Log` trait. Existing Rust-side `info!()`, `warn!()`, `error!()`, and `debug!()` calls therefore write into the same rotating companion log file.\n\nIf file logging initialization fails, the app falls back to stderr logging so startup can still proceed and terminal-launched sessions still have diagnostic output.\n\n### Frontend Side\n\nThe frontend logger in `companion/src/lib/logger.ts` writes to both:\n\n- The browser console for local developer-tools visibility.\n- The Rust backend through the `log_from_frontend` Tauri command so the same message lands in the file log.\n\nThat means support logs can contain both frontend and backend events in one timeline.\n\nThe frontend logger is fire-and-forget. Logging should never block the UI or surface a user-facing error because the log write itself failed.\n\n## Windows Webview2 Runtime Data\n\nOn Windows, the embedded WebView2 runtime stores its data at:\n\n- `%LOCALAPPDATA%\\app.sambee.companion\\EBWebView\\`\n\nThis directory is runtime-managed and is recreated automatically if removed.\n", "2.0": "+++\ntitle = \"Companion Support Reference\"\n+++\n\n## Communication and Security Model\n\nSambee uses two different browser-to-companion paths, depending on the workflow.\n\n- Local-drive browsing uses the companion's localhost API on `127.0.0.1:21549`.\n- Real-time local directory updates use a localhost WebSocket on the same port.\n- Desktop-app opening uses the `sambee://` custom URI scheme.\n\nThe localhost API is bound to the local machine only. It is not meant for remote network access.\n\nLocalhost traffic is authenticated after pairing, but it is not transport-encrypted.\n\n- HTTP requests use an HMAC derived from a shared secret and a current timestamp.\n- WebSocket and browser resource URLs use the same HMAC model through query parameters because browsers cannot attach custom headers in those cases.\n- The companion rejects requests outside the allowed clock-skew window.\n- Pairing is scoped to the browser origin, not just to the machine as a whole.\n\nThe shared secret is created only after the user confirms the same pairing code in both the browser and the companion. The companion stores its copy in the OS credential store. The browser stores its copy locally for that paired browser profile at that Sambee origin.\n\nIf you need contributor-level implementation detail, continue to the developer guide page [Browser-to-Companion Trust Model](../../../../0.7/developer-guide/companion-architecture/browser-to-companion-trust-model/).\n\n## Preference Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%APPDATA%\\app.sambee.companion\\` |\n| macOS | `~/Library/Application Support/app.sambee.companion/` |\n| Linux | `~/.local/share/app.sambee.companion/` |\n\nDeleting `user-preferences.json` and `app-preferences.json` resets companion settings.\n\n## Log Files\n\n| Platform | Location |\n|---|---|\n| Windows | `%LOCALAPPDATA%\\Sambee\\Companion\\logs\\sambee-companion.log` |\n| macOS | `~/Library/Application Support/app.sambee.companion/logs/sambee-companion.log` |\n| Linux | `~/.local/share/sambee-companion/logs/sambee-companion.log` |\n\nThe companion writes both Rust-backend messages and TypeScript-frontend messages into the same rotating log file.\n\n## Log Levels\n\n| Level | When captured | Typical use |\n|---|---|---|\n| `error` | Always | failures that stop an operation from completing |\n| `warn` | Always | degraded but non-fatal behavior |\n| `info` | Verbose mode only | lifecycle steps and state transitions |\n| `debug` | Verbose mode only for Sambee app and frontend logs | detailed diagnostic context |\n\nErrors and warnings are always written, even when verbose logging is off. That keeps production incidents diagnosable without requiring the user to reproduce them in a special logging mode.\n\nNormal verbose logging keeps dependency transport logs quiet. HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls` are enabled separately because they can be very noisy.\n\n## Logging Controls\n\nLogging settings are read once at startup, so restart the companion after changing logging registry values or logging environment variables.\n\nTwo logging toggles are available:\n\n| Setting | Purpose |\n|---|---|\n| `VerboseLogging` | Enables verbose Sambee app and frontend logs. |\n| `TransportLogging` | Enables HTTP transport diagnostics for `reqwest`, `hyper`, `hyper_util`, `h2`, `rustls`, and `tokio_rustls`. |\n\n### Windows Registry Values\n\nOn Windows, configure logging through registry values under:\n\n```text\nHKEY_CURRENT_USER\\Software\\Sambee\\Companion\n```\n\nUse type `REG_DWORD`. A non-zero value enables the setting. A missing value or `0` leaves the setting disabled.\n\nTo enable verbose Sambee app and frontend logs:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 1 /f\n```\n\nTo enable HTTP transport diagnostics:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 1 /f\n```\n\nTo disable them again:\n\n```cmd\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v VerboseLogging /t REG_DWORD /d 0 /f\nreg add \"HKCU\\Software\\Sambee\\Companion\" /v TransportLogging /t REG_DWORD /d 0 /f\n```\n\nRestart Companion after changing either registry value.\n\n### Linux and macOS Environment Variables\n\nOn Linux and macOS, launch the companion with environment variables for the logging modes you need.\n\nVerbose Sambee app and frontend logs:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 ./sambee-companion\n```\n\nHTTP transport diagnostics:\n\n```bash\nSAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nYou can combine both logging modes:\n\n```bash\nSAMBEE_LOG_VERBOSE=1 SAMBEE_LOG_TRANSPORT=1 ./sambee-companion\n```\n\nThe environment variables are also available on Windows for one-off terminal-launched debugging and take precedence over the registry values. Use `0` or `false` to force a setting off for that launch.\n\nUse verbose logging when the normal log file does not explain why startup, local-drive access, or file-return workflows are failing. Add transport diagnostics when you need HTTP, TLS, proxy, or HTTP/2 details.\n\n## Support Log Checklist\n\nWhen collecting Companion logs for a native-editing issue, include:\n\n- Whether the `Sambee Authentication` window appeared.\n- Whether the failure happened during token exchange, file-info lookup, lock acquisition, download, upload, lock release, or heartbeat.\n- Whether Companion reported a lifecycle state such as renewal required, authentication failed, lock lost, or recovery required.\n- The reverse proxy or SSO product in front of Sambee, if one is used.\n- The Companion log file from the affected desktop.\n\nWhen verbose logging is enabled, include any operation or lock identifiers shown near the failing step. Those identifiers help correlate token exchange, lock acquisition, renewal, upload, and release events without exposing the secret material itself.\n\nCompanion sanitizes URLs before writing request diagnostics. Sensitive query values such as tokens, secrets, passwords, cookies, authorization data, sessions, keys, and theme payloads should not appear in support logs.\n\n## Log Rotation\n\nThe companion rotates logs automatically to avoid unbounded disk growth.\n\n- Maximum file size: 5 MB per log file.\n- Maximum files: 3 total, including the active file.\n- Worst-case disk usage: About 15 MB.\n\nRotation uses the usual numbered-copy scheme: the active `.log` becomes `.log.1`, the previous `.log.1` becomes `.log.2`, and the oldest rotated file is removed.\n\n## Log Format\n\nEach line follows this structure:\n\n```text\nYYYY-MM-DDThh:mm:ss.mmmZ LEVEL [module] message\n```\n\nExample:\n\n```text\n2026-02-17T14:30:45.123Z INFO  [sambee_companion_lib] Step 1: Exchanging URI token...\n2026-02-17T14:30:45.456Z ERROR [frontend] Upload failed: network timeout\n2026-02-17T14:30:46.789Z WARN  [sambee_companion_lib::commands::upload] Upload attempt 1/3 failed: connection refused\n```\n\nFrontend messages use the module target `frontend` so you can distinguish browser-side UI logging from Rust-side command and backend behavior.\n\n## How Logging Reaches the File\n\nThe companion uses one unified file-log pipeline.\n\n### Rust Side\n\nThe Rust logging module in `companion/src-tauri/src/logging.rs` implements the `log::Log` trait. Existing Rust-side `info!()`, `warn!()`, `error!()`, and `debug!()` calls therefore write into the same rotating companion log file.\n\nIf file logging initialization fails, the app falls back to stderr logging so startup can still proceed and terminal-launched sessions still have diagnostic output.\n\n### Frontend Side\n\nThe frontend logger in `companion/src/lib/logger.ts` writes to both:\n\n- The browser console for local developer-tools visibility.\n- The Rust backend through the `log_from_frontend` Tauri command so the same message lands in the file log.\n\nThat means support logs can contain both frontend and backend events in one timeline.\n\nThe frontend logger is fire-and-forget. Logging should never block the UI or surface a user-facing error because the log write itself failed.\n\n## Windows Webview2 Runtime Data\n\nOn Windows, the embedded WebView2 runtime stores its data at:\n\n- `%LOCALAPPDATA%\\app.sambee.companion\\EBWebView\\`\n\nThis directory is runtime-managed and is recreated automatically if removed.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:admin-guide/reference/configuration-file-reference", "parent_id": "section:admin-guide/reference", "depth": 2, "kind": "page", "label": "configuration-file-reference", "title": "Configuration File Reference", "path": "admin-guide/reference/configuration-file-reference", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "authored"}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "inherited", "source_version": "0.9"}}, "content_versions": {"0.9": "+++\ntitle = \"Configuration File Reference\"\n+++\n\nThis page is a compact map of the optional `config.toml` file.\n\nUse `config.example.toml` as the source of truth for supported keys. This page explains the sections that matter most in day-to-day administration.\n\n## How to Use This Reference\n\n- Copy only the keys you actually need into the local `config.toml`.\n- Keep the file local to the deployment and mount it read-only in production.\n- Treat commented defaults in `config.example.toml` as the baseline behavior unless you override them intentionally.\n- Expect most basic deployments to use only a small subset of these keys.\n\n## High-Value Sections and Keys\n\n| Section | Key | Operational effect |\n|---|---|---|\n| `[app]` | `log_level` | Sets application diagnostic verbosity and Uvicorn lifecycle logging. |\n| `[app]` | `access_log_level` | Sets Uvicorn HTTP request access-log verbosity. |\n| `[app]` | `protocol_log_level` | Sets Uvicorn WebSocket connection, frame, and keepalive log verbosity. |\n| `[auth]` | `disable_enforcement` | Temporarily bypasses all Sambee authentication enforcement at runtime. |\n| `[security]` | `access_token_expire_minutes` | Changes the short-lived API-token lifetime. OIDC sessions refresh this token in the background; configure the OIDC interactive sign-in interval separately in Authentication settings. |\n| `[admin]` | `username` | Sets the initial administrator username. |\n| `[image_viewer]` | `conv_size_thresh` | Controls when large images are always converted for viewing. |\n| `[frontend_logging]` | `logging_enabled`, `log_level` | Controls browser-console logging behavior. |\n| `[frontend_logging]` | `tracing_enabled`, `tracing_level`, `tracing_retention_hours` | Controls backend trace collection for frontend logging. |\n| `[frontend_logging]` | `tracing_components`, `tracing_username_regex` | Restricts tracing by component or user scope. |\n| `[directory_cache]` | `location`, `coalesce_interval_seconds`, `max_staleness_minutes` | Controls the saved directory index Sambee keeps to make browsing and search recover faster after restarts. |\n| `[preprocessors.imagemagick]` | `max_file_size_bytes`, `timeout_seconds` | Sets conversion limits for ImageMagick preprocessing. |\n| `[companion_downloads]` | `metadata_feed_url` | Changes where Sambee resolves Companion download metadata. |\n| `[companion_downloads.pin]` | `version`, `published_at`, `notes`, asset URLs | Pins Companion download links to a specific published release instead of following the promoted feed. |\n\n## Backend Logging Levels\n\nThe `[app]` logging keys accept `DEBUG`, `INFO`, `WARNING`, or `ERROR`, regardless of case.\n\n```toml\n[app]\nlog_level = \"INFO\"\naccess_log_level = \"WARNING\"\nprotocol_log_level = \"WARNING\"\n```\n\n`log_level` defaults to `INFO`. `access_log_level` and `protocol_log_level` default to `WARNING`, which keeps routine successful HTTP requests and verbose WebSocket frames or pings out of normal logs. Raise either setting only for focused diagnosis. Uvicorn startup, shutdown, and error messages continue to use `log_level`.\n\n## Keys That Deserve Extra Care\n\nThese areas have the highest operational impact:\n\n- `[auth].disable_enforcement`: Bypasses all Sambee authentication enforcement. Use it only with a trusted reverse proxy or network perimeter that already enforces access control. It does not change the mode selected in Authentication settings and requires a restart after removal. The retired `auth_method` key is rejected at startup.\n- Backend logging keys: Can significantly increase log volume, particularly `protocol_log_level = \"DEBUG\"`.\n- Frontend logging and tracing keys: Can change both local debugging visibility and backend trace collection volume.\n- `directory_cache.location`: Changes where the saved SMB directory index lives on disk.\n- Companion download keys: Change what download links Sambee presents to users.\n", "1.0": "+++\ntitle = \"Configuration File Reference\"\n+++\n\nThis page is a compact map of the optional `config.toml` file.\n\nUse `config.example.toml` as the source of truth for supported keys. This page explains the sections that matter most in day-to-day administration.\n\n## How to Use This Reference\n\n- Copy only the keys you actually need into the local `config.toml`.\n- Keep the file local to the deployment and mount it read-only in production.\n- Treat commented defaults in `config.example.toml` as the baseline behavior unless you override them intentionally.\n- Expect most basic deployments to use only a small subset of these keys.\n\n## High-Value Sections and Keys\n\n| Section | Key | Operational effect |\n|---|---|---|\n| `[app]` | `log_level` | Sets application diagnostic verbosity and Uvicorn lifecycle logging. |\n| `[app]` | `access_log_level` | Sets Uvicorn HTTP request access-log verbosity. |\n| `[app]` | `protocol_log_level` | Sets Uvicorn WebSocket connection, frame, and keepalive log verbosity. |\n| `[auth]` | `disable_enforcement` | Temporarily bypasses all Sambee authentication enforcement at runtime. |\n| `[security]` | `access_token_expire_minutes` | Changes the short-lived API-token lifetime. OIDC sessions refresh this token in the background; configure the OIDC interactive sign-in interval separately in Authentication settings. |\n| `[admin]` | `username` | Sets the initial administrator username. |\n| `[image_viewer]` | `conv_size_thresh` | Controls when large images are always converted for viewing. |\n| `[frontend_logging]` | `logging_enabled`, `log_level` | Controls browser-console logging behavior. |\n| `[frontend_logging]` | `tracing_enabled`, `tracing_level`, `tracing_retention_hours` | Controls backend trace collection for frontend logging. |\n| `[frontend_logging]` | `tracing_components`, `tracing_username_regex` | Restricts tracing by component or user scope. |\n| `[directory_cache]` | `location`, `coalesce_interval_seconds`, `max_staleness_minutes` | Controls the saved directory index Sambee keeps to make browsing and search recover faster after restarts. |\n| `[preprocessors.imagemagick]` | `max_file_size_bytes`, `timeout_seconds` | Sets conversion limits for ImageMagick preprocessing. |\n| `[companion_downloads]` | `metadata_feed_url` | Changes where Sambee resolves Companion download metadata. |\n| `[companion_downloads.pin]` | `version`, `published_at`, `notes`, asset URLs | Pins Companion download links to a specific published release instead of following the promoted feed. |\n\n## Backend Logging Levels\n\nThe `[app]` logging keys accept `DEBUG`, `INFO`, `WARNING`, or `ERROR`, regardless of case.\n\n```toml\n[app]\nlog_level = \"INFO\"\naccess_log_level = \"WARNING\"\nprotocol_log_level = \"WARNING\"\n```\n\n`log_level` defaults to `INFO`. `access_log_level` and `protocol_log_level` default to `WARNING`, which keeps routine successful HTTP requests and verbose WebSocket frames or pings out of normal logs. Raise either setting only for focused diagnosis. Uvicorn startup, shutdown, and error messages continue to use `log_level`.\n\n## Keys That Deserve Extra Care\n\nThese areas have the highest operational impact:\n\n- `[auth].disable_enforcement`: Bypasses all Sambee authentication enforcement. Use it only with a trusted reverse proxy or network perimeter that already enforces access control. It does not change the mode selected in Authentication settings and requires a restart after removal. The retired `auth_method` key is rejected at startup.\n- Backend logging keys: Can significantly increase log volume, particularly `protocol_log_level = \"DEBUG\"`.\n- Frontend logging and tracing keys: Can change both local debugging visibility and backend trace collection volume.\n- `directory_cache.location`: Changes where the saved SMB directory index lives on disk.\n- Companion download keys: Change what download links Sambee presents to users.\n", "2.0": "+++\ntitle = \"Configuration File Reference\"\n+++\n\nThis page is a compact map of the optional `config.toml` file.\n\nUse `config.example.toml` as the source of truth for supported keys. This page explains the sections that matter most in day-to-day administration.\n\n## How to Use This Reference\n\n- Copy only the keys you actually need into the local `config.toml`.\n- Keep the file local to the deployment and mount it read-only in production.\n- Treat commented defaults in `config.example.toml` as the baseline behavior unless you override them intentionally.\n- Expect most basic deployments to use only a small subset of these keys.\n\n## High-Value Sections and Keys\n\n| Section | Key | Operational effect |\n|---|---|---|\n| `[app]` | `log_level` | Sets application diagnostic verbosity and Uvicorn lifecycle logging. |\n| `[app]` | `access_log_level` | Sets Uvicorn HTTP request access-log verbosity. |\n| `[app]` | `protocol_log_level` | Sets Uvicorn WebSocket connection, frame, and keepalive log verbosity. |\n| `[auth]` | `disable_enforcement` | Temporarily bypasses all Sambee authentication enforcement at runtime. |\n| `[security]` | `access_token_expire_minutes` | Changes the short-lived API-token lifetime. OIDC sessions refresh this token in the background; configure the OIDC interactive sign-in interval separately in Authentication settings. |\n| `[admin]` | `username` | Sets the initial administrator username. |\n| `[image_viewer]` | `conv_size_thresh` | Controls when large images are always converted for viewing. |\n| `[frontend_logging]` | `logging_enabled`, `log_level` | Controls browser-console logging behavior. |\n| `[frontend_logging]` | `tracing_enabled`, `tracing_level`, `tracing_retention_hours` | Controls backend trace collection for frontend logging. |\n| `[frontend_logging]` | `tracing_components`, `tracing_username_regex` | Restricts tracing by component or user scope. |\n| `[directory_cache]` | `location`, `coalesce_interval_seconds`, `max_staleness_minutes` | Controls the saved directory index Sambee keeps to make browsing and search recover faster after restarts. |\n| `[preprocessors.imagemagick]` | `max_file_size_bytes`, `timeout_seconds` | Sets conversion limits for ImageMagick preprocessing. |\n| `[companion_downloads]` | `metadata_feed_url` | Changes where Sambee resolves Companion download metadata. |\n| `[companion_downloads.pin]` | `version`, `published_at`, `notes`, asset URLs | Pins Companion download links to a specific published release instead of following the promoted feed. |\n\n## Backend Logging Levels\n\nThe `[app]` logging keys accept `DEBUG`, `INFO`, `WARNING`, or `ERROR`, regardless of case.\n\n```toml\n[app]\nlog_level = \"INFO\"\naccess_log_level = \"WARNING\"\nprotocol_log_level = \"WARNING\"\n```\n\n`log_level` defaults to `INFO`. `access_log_level` and `protocol_log_level` default to `WARNING`, which keeps routine successful HTTP requests and verbose WebSocket frames or pings out of normal logs. Raise either setting only for focused diagnosis. Uvicorn startup, shutdown, and error messages continue to use `log_level`.\n\n## Keys That Deserve Extra Care\n\nThese areas have the highest operational impact:\n\n- `[auth].disable_enforcement`: Bypasses all Sambee authentication enforcement. Use it only with a trusted reverse proxy or network perimeter that already enforces access control. It does not change the mode selected in Authentication settings and requires a restart after removal. The retired `auth_method` key is rejected at startup.\n- Backend logging keys: Can significantly increase log volume, particularly `protocol_log_level = \"DEBUG\"`.\n- Frontend logging and tracing keys: Can change both local debugging visibility and backend trace collection volume.\n- `directory_cache.location`: Changes where the saved SMB directory index lives on disk.\n- Companion download keys: Change what download links Sambee presents to users.\n"}, "page_contents": {"0.9": "+++\ntitle = \"Configuration File Reference\"\n+++\n\nThis page is a compact map of the optional `config.toml` file.\n\nUse `config.example.toml` as the source of truth for supported keys. This page explains the sections that matter most in day-to-day administration.\n\n## How to Use This Reference\n\n- Copy only the keys you actually need into the local `config.toml`.\n- Keep the file local to the deployment and mount it read-only in production.\n- Treat commented defaults in `config.example.toml` as the baseline behavior unless you override them intentionally.\n- Expect most basic deployments to use only a small subset of these keys.\n\n## High-Value Sections and Keys\n\n| Section | Key | Operational effect |\n|---|---|---|\n| `[app]` | `log_level` | Sets application diagnostic verbosity and Uvicorn lifecycle logging. |\n| `[app]` | `access_log_level` | Sets Uvicorn HTTP request access-log verbosity. |\n| `[app]` | `protocol_log_level` | Sets Uvicorn WebSocket connection, frame, and keepalive log verbosity. |\n| `[auth]` | `disable_enforcement` | Temporarily bypasses all Sambee authentication enforcement at runtime. |\n| `[security]` | `access_token_expire_minutes` | Changes the short-lived API-token lifetime. OIDC sessions refresh this token in the background; configure the OIDC interactive sign-in interval separately in Authentication settings. |\n| `[admin]` | `username` | Sets the initial administrator username. |\n| `[image_viewer]` | `conv_size_thresh` | Controls when large images are always converted for viewing. |\n| `[frontend_logging]` | `logging_enabled`, `log_level` | Controls browser-console logging behavior. |\n| `[frontend_logging]` | `tracing_enabled`, `tracing_level`, `tracing_retention_hours` | Controls backend trace collection for frontend logging. |\n| `[frontend_logging]` | `tracing_components`, `tracing_username_regex` | Restricts tracing by component or user scope. |\n| `[directory_cache]` | `location`, `coalesce_interval_seconds`, `max_staleness_minutes` | Controls the saved directory index Sambee keeps to make browsing and search recover faster after restarts. |\n| `[preprocessors.imagemagick]` | `max_file_size_bytes`, `timeout_seconds` | Sets conversion limits for ImageMagick preprocessing. |\n| `[companion_downloads]` | `metadata_feed_url` | Changes where Sambee resolves Companion download metadata. |\n| `[companion_downloads.pin]` | `version`, `published_at`, `notes`, asset URLs | Pins Companion download links to a specific published release instead of following the promoted feed. |\n\n## Backend Logging Levels\n\nThe `[app]` logging keys accept `DEBUG`, `INFO`, `WARNING`, or `ERROR`, regardless of case.\n\n```toml\n[app]\nlog_level = \"INFO\"\naccess_log_level = \"WARNING\"\nprotocol_log_level = \"WARNING\"\n```\n\n`log_level` defaults to `INFO`. `access_log_level` and `protocol_log_level` default to `WARNING`, which keeps routine successful HTTP requests and verbose WebSocket frames or pings out of normal logs. Raise either setting only for focused diagnosis. Uvicorn startup, shutdown, and error messages continue to use `log_level`.\n\n## Keys That Deserve Extra Care\n\nThese areas have the highest operational impact:\n\n- `[auth].disable_enforcement`: Bypasses all Sambee authentication enforcement. Use it only with a trusted reverse proxy or network perimeter that already enforces access control. It does not change the mode selected in Authentication settings and requires a restart after removal. The retired `auth_method` key is rejected at startup.\n- Backend logging keys: Can significantly increase log volume, particularly `protocol_log_level = \"DEBUG\"`.\n- Frontend logging and tracing keys: Can change both local debugging visibility and backend trace collection volume.\n- `directory_cache.location`: Changes where the saved SMB directory index lives on disk.\n- Companion download keys: Change what download links Sambee presents to users.\n", "1.0": "+++\ntitle = \"Configuration File Reference\"\n+++\n\nThis page is a compact map of the optional `config.toml` file.\n\nUse `config.example.toml` as the source of truth for supported keys. This page explains the sections that matter most in day-to-day administration.\n\n## How to Use This Reference\n\n- Copy only the keys you actually need into the local `config.toml`.\n- Keep the file local to the deployment and mount it read-only in production.\n- Treat commented defaults in `config.example.toml` as the baseline behavior unless you override them intentionally.\n- Expect most basic deployments to use only a small subset of these keys.\n\n## High-Value Sections and Keys\n\n| Section | Key | Operational effect |\n|---|---|---|\n| `[app]` | `log_level` | Sets application diagnostic verbosity and Uvicorn lifecycle logging. |\n| `[app]` | `access_log_level` | Sets Uvicorn HTTP request access-log verbosity. |\n| `[app]` | `protocol_log_level` | Sets Uvicorn WebSocket connection, frame, and keepalive log verbosity. |\n| `[auth]` | `disable_enforcement` | Temporarily bypasses all Sambee authentication enforcement at runtime. |\n| `[security]` | `access_token_expire_minutes` | Changes the short-lived API-token lifetime. OIDC sessions refresh this token in the background; configure the OIDC interactive sign-in interval separately in Authentication settings. |\n| `[admin]` | `username` | Sets the initial administrator username. |\n| `[image_viewer]` | `conv_size_thresh` | Controls when large images are always converted for viewing. |\n| `[frontend_logging]` | `logging_enabled`, `log_level` | Controls browser-console logging behavior. |\n| `[frontend_logging]` | `tracing_enabled`, `tracing_level`, `tracing_retention_hours` | Controls backend trace collection for frontend logging. |\n| `[frontend_logging]` | `tracing_components`, `tracing_username_regex` | Restricts tracing by component or user scope. |\n| `[directory_cache]` | `location`, `coalesce_interval_seconds`, `max_staleness_minutes` | Controls the saved directory index Sambee keeps to make browsing and search recover faster after restarts. |\n| `[preprocessors.imagemagick]` | `max_file_size_bytes`, `timeout_seconds` | Sets conversion limits for ImageMagick preprocessing. |\n| `[companion_downloads]` | `metadata_feed_url` | Changes where Sambee resolves Companion download metadata. |\n| `[companion_downloads.pin]` | `version`, `published_at`, `notes`, asset URLs | Pins Companion download links to a specific published release instead of following the promoted feed. |\n\n## Backend Logging Levels\n\nThe `[app]` logging keys accept `DEBUG`, `INFO`, `WARNING`, or `ERROR`, regardless of case.\n\n```toml\n[app]\nlog_level = \"INFO\"\naccess_log_level = \"WARNING\"\nprotocol_log_level = \"WARNING\"\n```\n\n`log_level` defaults to `INFO`. `access_log_level` and `protocol_log_level` default to `WARNING`, which keeps routine successful HTTP requests and verbose WebSocket frames or pings out of normal logs. Raise either setting only for focused diagnosis. Uvicorn startup, shutdown, and error messages continue to use `log_level`.\n\n## Keys That Deserve Extra Care\n\nThese areas have the highest operational impact:\n\n- `[auth].disable_enforcement`: Bypasses all Sambee authentication enforcement. Use it only with a trusted reverse proxy or network perimeter that already enforces access control. It does not change the mode selected in Authentication settings and requires a restart after removal. The retired `auth_method` key is rejected at startup.\n- Backend logging keys: Can significantly increase log volume, particularly `protocol_log_level = \"DEBUG\"`.\n- Frontend logging and tracing keys: Can change both local debugging visibility and backend trace collection volume.\n- `directory_cache.location`: Changes where the saved SMB directory index lives on disk.\n- Companion download keys: Change what download links Sambee presents to users.\n", "2.0": "+++\ntitle = \"Configuration File Reference\"\n+++\n\nThis page is a compact map of the optional `config.toml` file.\n\nUse `config.example.toml` as the source of truth for supported keys. This page explains the sections that matter most in day-to-day administration.\n\n## How to Use This Reference\n\n- Copy only the keys you actually need into the local `config.toml`.\n- Keep the file local to the deployment and mount it read-only in production.\n- Treat commented defaults in `config.example.toml` as the baseline behavior unless you override them intentionally.\n- Expect most basic deployments to use only a small subset of these keys.\n\n## High-Value Sections and Keys\n\n| Section | Key | Operational effect |\n|---|---|---|\n| `[app]` | `log_level` | Sets application diagnostic verbosity and Uvicorn lifecycle logging. |\n| `[app]` | `access_log_level` | Sets Uvicorn HTTP request access-log verbosity. |\n| `[app]` | `protocol_log_level` | Sets Uvicorn WebSocket connection, frame, and keepalive log verbosity. |\n| `[auth]` | `disable_enforcement` | Temporarily bypasses all Sambee authentication enforcement at runtime. |\n| `[security]` | `access_token_expire_minutes` | Changes the short-lived API-token lifetime. OIDC sessions refresh this token in the background; configure the OIDC interactive sign-in interval separately in Authentication settings. |\n| `[admin]` | `username` | Sets the initial administrator username. |\n| `[image_viewer]` | `conv_size_thresh` | Controls when large images are always converted for viewing. |\n| `[frontend_logging]` | `logging_enabled`, `log_level` | Controls browser-console logging behavior. |\n| `[frontend_logging]` | `tracing_enabled`, `tracing_level`, `tracing_retention_hours` | Controls backend trace collection for frontend logging. |\n| `[frontend_logging]` | `tracing_components`, `tracing_username_regex` | Restricts tracing by component or user scope. |\n| `[directory_cache]` | `location`, `coalesce_interval_seconds`, `max_staleness_minutes` | Controls the saved directory index Sambee keeps to make browsing and search recover faster after restarts. |\n| `[preprocessors.imagemagick]` | `max_file_size_bytes`, `timeout_seconds` | Sets conversion limits for ImageMagick preprocessing. |\n| `[companion_downloads]` | `metadata_feed_url` | Changes where Sambee resolves Companion download metadata. |\n| `[companion_downloads.pin]` | `version`, `published_at`, `notes`, asset URLs | Pins Companion download links to a specific published release instead of following the promoted feed. |\n\n## Backend Logging Levels\n\nThe `[app]` logging keys accept `DEBUG`, `INFO`, `WARNING`, or `ERROR`, regardless of case.\n\n```toml\n[app]\nlog_level = \"INFO\"\naccess_log_level = \"WARNING\"\nprotocol_log_level = \"WARNING\"\n```\n\n`log_level` defaults to `INFO`. `access_log_level` and `protocol_log_level` default to `WARNING`, which keeps routine successful HTTP requests and verbose WebSocket frames or pings out of normal logs. Raise either setting only for focused diagnosis. Uvicorn startup, shutdown, and error messages continue to use `log_level`.\n\n## Keys That Deserve Extra Care\n\nThese areas have the highest operational impact:\n\n- `[auth].disable_enforcement`: Bypasses all Sambee authentication enforcement. Use it only with a trusted reverse proxy or network perimeter that already enforces access control. It does not change the mode selected in Authentication settings and requires a restart after removal. The retired `auth_method` key is rejected at startup.\n- Backend logging keys: Can significantly increase log volume, particularly `protocol_log_level = \"DEBUG\"`.\n- Frontend logging and tracing keys: Can change both local debugging visibility and backend trace collection volume.\n- `directory_cache.location`: Changes where the saved SMB directory index lives on disk.\n- Companion download keys: Change what download links Sambee presents to users.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:admin-guide/reference/smb-settings", "parent_id": "section:admin-guide/reference", "depth": 2, "kind": "page", "label": "smb-settings", "title": "Smb Settings", "path": "admin-guide/reference/smb-settings", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "authored"}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "inherited", "source_version": "0.9"}}, "content_versions": {"0.9": "+++\ntitle = \"SMB Settings\"\n+++\n\nAdministrators configure Sambee's runtime SMB behavior in **Settings** \u003e **Administration** \u003e **SMB**. These controls apply to every configured SMB connection.\n\n## Protection\n\n### Authentication Mode\n\n- **Automatic (Kerberos or NTLM)** uses Kerberos when available and otherwise falls back to NTLM. This is the practical option for compatible domain and NAS environments.\n- **Kerberos required** blocks NTLM fallback. Choose it when every SMB server is correctly configured for Kerberos authentication.\n\n### Transport Protection\n\nSMB signing is always required by Sambee. It verifies that SMB messages have not been altered in transit.\n\n- **Signing only (SMB 2 compatible)** is the default. It permits signed, unencrypted SMB 2 connections for trusted home and small-organization networks. File contents, names, and metadata are visible to network observers in this mode.\n- **Signing and encryption (SMB 3+)** requires encrypted SMB traffic. Choose it for shared or untrusted networks that need confidentiality. This blocks SMB 2-only servers because SMB encryption requires SMB 3 or later.\n\n## Connection Behavior\n\nSet the SMB connection timeout to limit how long Sambee waits to establish a transport connection.\n\n## File Streaming\n\nSet the SMB read chunk size to control how much file data Sambee reads per streaming operation. The setting is stored as an administrator setting and is not available in `config.toml`.\n\n", "1.0": "+++\ntitle = \"SMB Settings\"\n+++\n\nAdministrators configure Sambee's runtime SMB behavior in **Settings** \u003e **Administration** \u003e **SMB**. These controls apply to every configured SMB connection.\n\n## Protection\n\n### Authentication Mode\n\n- **Automatic (Kerberos or NTLM)** uses Kerberos when available and otherwise falls back to NTLM. This is the practical option for compatible domain and NAS environments.\n- **Kerberos required** blocks NTLM fallback. Choose it when every SMB server is correctly configured for Kerberos authentication.\n\n### Transport Protection\n\nSMB signing is always required by Sambee. It verifies that SMB messages have not been altered in transit.\n\n- **Signing only (SMB 2 compatible)** is the default. It permits signed, unencrypted SMB 2 connections for trusted home and small-organization networks. File contents, names, and metadata are visible to network observers in this mode.\n- **Signing and encryption (SMB 3+)** requires encrypted SMB traffic. Choose it for shared or untrusted networks that need confidentiality. This blocks SMB 2-only servers because SMB encryption requires SMB 3 or later.\n\n## Connection Behavior\n\nSet the SMB connection timeout to limit how long Sambee waits to establish a transport connection.\n\n## File Streaming\n\nSet the SMB read chunk size to control how much file data Sambee reads per streaming operation. The setting is stored as an administrator setting and is not available in `config.toml`.\n\n", "2.0": "+++\ntitle = \"SMB Settings\"\n+++\n\nAdministrators configure Sambee's runtime SMB behavior in **Settings** \u003e **Administration** \u003e **SMB**. These controls apply to every configured SMB connection.\n\n## Protection\n\n### Authentication Mode\n\n- **Automatic (Kerberos or NTLM)** uses Kerberos when available and otherwise falls back to NTLM. This is the practical option for compatible domain and NAS environments.\n- **Kerberos required** blocks NTLM fallback. Choose it when every SMB server is correctly configured for Kerberos authentication.\n\n### Transport Protection\n\nSMB signing is always required by Sambee. It verifies that SMB messages have not been altered in transit.\n\n- **Signing only (SMB 2 compatible)** is the default. It permits signed, unencrypted SMB 2 connections for trusted home and small-organization networks. File contents, names, and metadata are visible to network observers in this mode.\n- **Signing and encryption (SMB 3+)** requires encrypted SMB traffic. Choose it for shared or untrusted networks that need confidentiality. This blocks SMB 2-only servers because SMB encryption requires SMB 3 or later.\n\n## Connection Behavior\n\nSet the SMB connection timeout to limit how long Sambee waits to establish a transport connection.\n\n## File Streaming\n\nSet the SMB read chunk size to control how much file data Sambee reads per streaming operation. The setting is stored as an administrator setting and is not available in `config.toml`.\n\n"}, "page_contents": {"0.9": "+++\ntitle = \"SMB Settings\"\n+++\n\nAdministrators configure Sambee's runtime SMB behavior in **Settings** \u003e **Administration** \u003e **SMB**. These controls apply to every configured SMB connection.\n\n## Protection\n\n### Authentication Mode\n\n- **Automatic (Kerberos or NTLM)** uses Kerberos when available and otherwise falls back to NTLM. This is the practical option for compatible domain and NAS environments.\n- **Kerberos required** blocks NTLM fallback. Choose it when every SMB server is correctly configured for Kerberos authentication.\n\n### Transport Protection\n\nSMB signing is always required by Sambee. It verifies that SMB messages have not been altered in transit.\n\n- **Signing only (SMB 2 compatible)** is the default. It permits signed, unencrypted SMB 2 connections for trusted home and small-organization networks. File contents, names, and metadata are visible to network observers in this mode.\n- **Signing and encryption (SMB 3+)** requires encrypted SMB traffic. Choose it for shared or untrusted networks that need confidentiality. This blocks SMB 2-only servers because SMB encryption requires SMB 3 or later.\n\n## Connection Behavior\n\nSet the SMB connection timeout to limit how long Sambee waits to establish a transport connection.\n\n## File Streaming\n\nSet the SMB read chunk size to control how much file data Sambee reads per streaming operation. The setting is stored as an administrator setting and is not available in `config.toml`.\n\n", "1.0": "+++\ntitle = \"SMB Settings\"\n+++\n\nAdministrators configure Sambee's runtime SMB behavior in **Settings** \u003e **Administration** \u003e **SMB**. These controls apply to every configured SMB connection.\n\n## Protection\n\n### Authentication Mode\n\n- **Automatic (Kerberos or NTLM)** uses Kerberos when available and otherwise falls back to NTLM. This is the practical option for compatible domain and NAS environments.\n- **Kerberos required** blocks NTLM fallback. Choose it when every SMB server is correctly configured for Kerberos authentication.\n\n### Transport Protection\n\nSMB signing is always required by Sambee. It verifies that SMB messages have not been altered in transit.\n\n- **Signing only (SMB 2 compatible)** is the default. It permits signed, unencrypted SMB 2 connections for trusted home and small-organization networks. File contents, names, and metadata are visible to network observers in this mode.\n- **Signing and encryption (SMB 3+)** requires encrypted SMB traffic. Choose it for shared or untrusted networks that need confidentiality. This blocks SMB 2-only servers because SMB encryption requires SMB 3 or later.\n\n## Connection Behavior\n\nSet the SMB connection timeout to limit how long Sambee waits to establish a transport connection.\n\n## File Streaming\n\nSet the SMB read chunk size to control how much file data Sambee reads per streaming operation. The setting is stored as an administrator setting and is not available in `config.toml`.\n\n", "2.0": "+++\ntitle = \"SMB Settings\"\n+++\n\nAdministrators configure Sambee's runtime SMB behavior in **Settings** \u003e **Administration** \u003e **SMB**. These controls apply to every configured SMB connection.\n\n## Protection\n\n### Authentication Mode\n\n- **Automatic (Kerberos or NTLM)** uses Kerberos when available and otherwise falls back to NTLM. This is the practical option for compatible domain and NAS environments.\n- **Kerberos required** blocks NTLM fallback. Choose it when every SMB server is correctly configured for Kerberos authentication.\n\n### Transport Protection\n\nSMB signing is always required by Sambee. It verifies that SMB messages have not been altered in transit.\n\n- **Signing only (SMB 2 compatible)** is the default. It permits signed, unencrypted SMB 2 connections for trusted home and small-organization networks. File contents, names, and metadata are visible to network observers in this mode.\n- **Signing and encryption (SMB 3+)** requires encrypted SMB traffic. Choose it for shared or untrusted networks that need confidentiality. This blocks SMB 2-only servers because SMB encryption requires SMB 3 or later.\n\n## Connection Behavior\n\nSet the SMB connection timeout to limit how long Sambee waits to establish a transport connection.\n\n## File Streaming\n\nSet the SMB read chunk size to control how much file data Sambee reads per streaming operation. The setting is stored as an administrator setting and is not available in `config.toml`.\n\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:admin-guide/authentication", "parent_id": "book:admin-guide", "depth": 1, "kind": "section", "label": "authentication", "title": "Authentication", "path": "admin-guide/authentication", "has_children": true, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:admin-guide/authentication/authentication-overview", "parent_id": "section:admin-guide/authentication", "depth": 2, "kind": "page", "label": "authentication-overview", "title": "Authentication Overview", "path": "admin-guide/authentication/authentication-overview", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "authored"}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "inherited", "source_version": "0.9"}}, "content_versions": {"0.9": "+++\ntitle = \"Authentication Overview\"\n+++\n\nSambee supports multiple authentication modes: OpenID Connect (OIDC), local passwords, and no authentication (perimeter-trust mode).\n\nTo configure Sambee authenticaion, open **Settings** \u003e **Administration** \u003e **Authentication**.\n\n## Choose an Authentication Mode\n\n| Mode | Login behavior | User management |\n|---|---|---|\n| No authentication | Sambee does not authenticate users. Use this only when a trusted reverse proxy or network perimeter controls all access to Sambee. | Creating users and managing local passwords are unavailable. |\n| Password only (default) | Shows the local username and password form. | Administrators can create users and set or reset local passwords. |\n| OIDC or password | Shows the OIDC login and local username/password fields on the same page. | Administrators can create local-password users. OIDC also provisions passwordless users after an admitted sign-in. |\n| OIDC only | Starts the OIDC login transparently. | Sambee provisions passwordless users after their first admitted OIDC sign-in. Manual user creation and local-password management are unavailable. |\n\nUse **OIDC or password** while introducing OIDC. Switch to **OIDC only** only after an administrator has completed the interactive test and verified the recovery procedure. Select **Password only** when local credentials should be the only sign-in method.\n\nFor local-password setup and recovery, see [Password Authentication](../password-authentication/). For provider setup, see [OpenID Connect Authentication Setup](../openid-connect-authentication-setup/).\n\n## Authentication Configuration\n\nSambee stores the selected authentication mode in its database. New installations default to **Password only** until an administrator selects another mode in **Settings** \u003e **Administration** \u003e **Authentication**.\n\nThe [configuration file](../../reference/configuration-file-reference) has one authentication-related runtime override: it bypasses authentication enforcement without changing the mode saved in the UI. This override is useful mainly during development.\n\n## No Authentication\n\n**No authentication** is a perimeter-trust mode. Sambee does not validate a user identity, consume reverse-proxy identity headers, or enforce a proxy-specific authorization policy. It assumes that every request reaching Sambee was already authorized by infrastructure you operate.\n\nBefore activation, the UI requires an explicit acknowledgement and revokes all active Sambee sessions. Do not enable this mode on a directly reachable service or behind a proxy that does not enforce authentication and access control.\n\nSambee keeps existing user records and local password hashes when you select this mode, but does not use them for authentication. User Management does not offer manual user creation or local-password resets until you select a password-capable mode.\n\n", "1.0": "+++\ntitle = \"Authentication Overview\"\n+++\n\nSambee supports multiple authentication modes: OpenID Connect (OIDC), local passwords, and no authentication (perimeter-trust mode).\n\nTo configure Sambee authenticaion, open **Settings** \u003e **Administration** \u003e **Authentication**.\n\n## Choose an Authentication Mode\n\n| Mode | Login behavior | User management |\n|---|---|---|\n| No authentication | Sambee does not authenticate users. Use this only when a trusted reverse proxy or network perimeter controls all access to Sambee. | Creating users and managing local passwords are unavailable. |\n| Password only (default) | Shows the local username and password form. | Administrators can create users and set or reset local passwords. |\n| OIDC or password | Shows the OIDC login and local username/password fields on the same page. | Administrators can create local-password users. OIDC also provisions passwordless users after an admitted sign-in. |\n| OIDC only | Starts the OIDC login transparently. | Sambee provisions passwordless users after their first admitted OIDC sign-in. Manual user creation and local-password management are unavailable. |\n\nUse **OIDC or password** while introducing OIDC. Switch to **OIDC only** only after an administrator has completed the interactive test and verified the recovery procedure. Select **Password only** when local credentials should be the only sign-in method.\n\nFor local-password setup and recovery, see [Password Authentication](../password-authentication/). For provider setup, see [OpenID Connect Authentication Setup](../openid-connect-authentication-setup/).\n\n## Authentication Configuration\n\nSambee stores the selected authentication mode in its database. New installations default to **Password only** until an administrator selects another mode in **Settings** \u003e **Administration** \u003e **Authentication**.\n\nThe [configuration file](../../reference/configuration-file-reference) has one authentication-related runtime override: it bypasses authentication enforcement without changing the mode saved in the UI. This override is useful mainly during development.\n\n## No Authentication\n\n**No authentication** is a perimeter-trust mode. Sambee does not validate a user identity, consume reverse-proxy identity headers, or enforce a proxy-specific authorization policy. It assumes that every request reaching Sambee was already authorized by infrastructure you operate.\n\nBefore activation, the UI requires an explicit acknowledgement and revokes all active Sambee sessions. Do not enable this mode on a directly reachable service or behind a proxy that does not enforce authentication and access control.\n\nSambee keeps existing user records and local password hashes when you select this mode, but does not use them for authentication. User Management does not offer manual user creation or local-password resets until you select a password-capable mode.\n\n", "2.0": "+++\ntitle = \"Authentication Overview\"\n+++\n\nSambee supports multiple authentication modes: OpenID Connect (OIDC), local passwords, and no authentication (perimeter-trust mode).\n\nTo configure Sambee authenticaion, open **Settings** \u003e **Administration** \u003e **Authentication**.\n\n## Choose an Authentication Mode\n\n| Mode | Login behavior | User management |\n|---|---|---|\n| No authentication | Sambee does not authenticate users. Use this only when a trusted reverse proxy or network perimeter controls all access to Sambee. | Creating users and managing local passwords are unavailable. |\n| Password only (default) | Shows the local username and password form. | Administrators can create users and set or reset local passwords. |\n| OIDC or password | Shows the OIDC login and local username/password fields on the same page. | Administrators can create local-password users. OIDC also provisions passwordless users after an admitted sign-in. |\n| OIDC only | Starts the OIDC login transparently. | Sambee provisions passwordless users after their first admitted OIDC sign-in. Manual user creation and local-password management are unavailable. |\n\nUse **OIDC or password** while introducing OIDC. Switch to **OIDC only** only after an administrator has completed the interactive test and verified the recovery procedure. Select **Password only** when local credentials should be the only sign-in method.\n\nFor local-password setup and recovery, see [Password Authentication](../password-authentication/). For provider setup, see [OpenID Connect Authentication Setup](../openid-connect-authentication-setup/).\n\n## Authentication Configuration\n\nSambee stores the selected authentication mode in its database. New installations default to **Password only** until an administrator selects another mode in **Settings** \u003e **Administration** \u003e **Authentication**.\n\nThe [configuration file](../../reference/configuration-file-reference) has one authentication-related runtime override: it bypasses authentication enforcement without changing the mode saved in the UI. This override is useful mainly during development.\n\n## No Authentication\n\n**No authentication** is a perimeter-trust mode. Sambee does not validate a user identity, consume reverse-proxy identity headers, or enforce a proxy-specific authorization policy. It assumes that every request reaching Sambee was already authorized by infrastructure you operate.\n\nBefore activation, the UI requires an explicit acknowledgement and revokes all active Sambee sessions. Do not enable this mode on a directly reachable service or behind a proxy that does not enforce authentication and access control.\n\nSambee keeps existing user records and local password hashes when you select this mode, but does not use them for authentication. User Management does not offer manual user creation or local-password resets until you select a password-capable mode.\n\n"}, "page_contents": {"0.9": "+++\ntitle = \"Authentication Overview\"\n+++\n\nSambee supports multiple authentication modes: OpenID Connect (OIDC), local passwords, and no authentication (perimeter-trust mode).\n\nTo configure Sambee authenticaion, open **Settings** \u003e **Administration** \u003e **Authentication**.\n\n## Choose an Authentication Mode\n\n| Mode | Login behavior | User management |\n|---|---|---|\n| No authentication | Sambee does not authenticate users. Use this only when a trusted reverse proxy or network perimeter controls all access to Sambee. | Creating users and managing local passwords are unavailable. |\n| Password only (default) | Shows the local username and password form. | Administrators can create users and set or reset local passwords. |\n| OIDC or password | Shows the OIDC login and local username/password fields on the same page. | Administrators can create local-password users. OIDC also provisions passwordless users after an admitted sign-in. |\n| OIDC only | Starts the OIDC login transparently. | Sambee provisions passwordless users after their first admitted OIDC sign-in. Manual user creation and local-password management are unavailable. |\n\nUse **OIDC or password** while introducing OIDC. Switch to **OIDC only** only after an administrator has completed the interactive test and verified the recovery procedure. Select **Password only** when local credentials should be the only sign-in method.\n\nFor local-password setup and recovery, see [Password Authentication](../password-authentication/). For provider setup, see [OpenID Connect Authentication Setup](../openid-connect-authentication-setup/).\n\n## Authentication Configuration\n\nSambee stores the selected authentication mode in its database. New installations default to **Password only** until an administrator selects another mode in **Settings** \u003e **Administration** \u003e **Authentication**.\n\nThe [configuration file](../../reference/configuration-file-reference) has one authentication-related runtime override: it bypasses authentication enforcement without changing the mode saved in the UI. This override is useful mainly during development.\n\n## No Authentication\n\n**No authentication** is a perimeter-trust mode. Sambee does not validate a user identity, consume reverse-proxy identity headers, or enforce a proxy-specific authorization policy. It assumes that every request reaching Sambee was already authorized by infrastructure you operate.\n\nBefore activation, the UI requires an explicit acknowledgement and revokes all active Sambee sessions. Do not enable this mode on a directly reachable service or behind a proxy that does not enforce authentication and access control.\n\nSambee keeps existing user records and local password hashes when you select this mode, but does not use them for authentication. User Management does not offer manual user creation or local-password resets until you select a password-capable mode.\n\n", "1.0": "+++\ntitle = \"Authentication Overview\"\n+++\n\nSambee supports multiple authentication modes: OpenID Connect (OIDC), local passwords, and no authentication (perimeter-trust mode).\n\nTo configure Sambee authenticaion, open **Settings** \u003e **Administration** \u003e **Authentication**.\n\n## Choose an Authentication Mode\n\n| Mode | Login behavior | User management |\n|---|---|---|\n| No authentication | Sambee does not authenticate users. Use this only when a trusted reverse proxy or network perimeter controls all access to Sambee. | Creating users and managing local passwords are unavailable. |\n| Password only (default) | Shows the local username and password form. | Administrators can create users and set or reset local passwords. |\n| OIDC or password | Shows the OIDC login and local username/password fields on the same page. | Administrators can create local-password users. OIDC also provisions passwordless users after an admitted sign-in. |\n| OIDC only | Starts the OIDC login transparently. | Sambee provisions passwordless users after their first admitted OIDC sign-in. Manual user creation and local-password management are unavailable. |\n\nUse **OIDC or password** while introducing OIDC. Switch to **OIDC only** only after an administrator has completed the interactive test and verified the recovery procedure. Select **Password only** when local credentials should be the only sign-in method.\n\nFor local-password setup and recovery, see [Password Authentication](../password-authentication/). For provider setup, see [OpenID Connect Authentication Setup](../openid-connect-authentication-setup/).\n\n## Authentication Configuration\n\nSambee stores the selected authentication mode in its database. New installations default to **Password only** until an administrator selects another mode in **Settings** \u003e **Administration** \u003e **Authentication**.\n\nThe [configuration file](../../reference/configuration-file-reference) has one authentication-related runtime override: it bypasses authentication enforcement without changing the mode saved in the UI. This override is useful mainly during development.\n\n## No Authentication\n\n**No authentication** is a perimeter-trust mode. Sambee does not validate a user identity, consume reverse-proxy identity headers, or enforce a proxy-specific authorization policy. It assumes that every request reaching Sambee was already authorized by infrastructure you operate.\n\nBefore activation, the UI requires an explicit acknowledgement and revokes all active Sambee sessions. Do not enable this mode on a directly reachable service or behind a proxy that does not enforce authentication and access control.\n\nSambee keeps existing user records and local password hashes when you select this mode, but does not use them for authentication. User Management does not offer manual user creation or local-password resets until you select a password-capable mode.\n\n", "2.0": "+++\ntitle = \"Authentication Overview\"\n+++\n\nSambee supports multiple authentication modes: OpenID Connect (OIDC), local passwords, and no authentication (perimeter-trust mode).\n\nTo configure Sambee authenticaion, open **Settings** \u003e **Administration** \u003e **Authentication**.\n\n## Choose an Authentication Mode\n\n| Mode | Login behavior | User management |\n|---|---|---|\n| No authentication | Sambee does not authenticate users. Use this only when a trusted reverse proxy or network perimeter controls all access to Sambee. | Creating users and managing local passwords are unavailable. |\n| Password only (default) | Shows the local username and password form. | Administrators can create users and set or reset local passwords. |\n| OIDC or password | Shows the OIDC login and local username/password fields on the same page. | Administrators can create local-password users. OIDC also provisions passwordless users after an admitted sign-in. |\n| OIDC only | Starts the OIDC login transparently. | Sambee provisions passwordless users after their first admitted OIDC sign-in. Manual user creation and local-password management are unavailable. |\n\nUse **OIDC or password** while introducing OIDC. Switch to **OIDC only** only after an administrator has completed the interactive test and verified the recovery procedure. Select **Password only** when local credentials should be the only sign-in method.\n\nFor local-password setup and recovery, see [Password Authentication](../password-authentication/). For provider setup, see [OpenID Connect Authentication Setup](../openid-connect-authentication-setup/).\n\n## Authentication Configuration\n\nSambee stores the selected authentication mode in its database. New installations default to **Password only** until an administrator selects another mode in **Settings** \u003e **Administration** \u003e **Authentication**.\n\nThe [configuration file](../../reference/configuration-file-reference) has one authentication-related runtime override: it bypasses authentication enforcement without changing the mode saved in the UI. This override is useful mainly during development.\n\n## No Authentication\n\n**No authentication** is a perimeter-trust mode. Sambee does not validate a user identity, consume reverse-proxy identity headers, or enforce a proxy-specific authorization policy. It assumes that every request reaching Sambee was already authorized by infrastructure you operate.\n\nBefore activation, the UI requires an explicit acknowledgement and revokes all active Sambee sessions. Do not enable this mode on a directly reachable service or behind a proxy that does not enforce authentication and access control.\n\nSambee keeps existing user records and local password hashes when you select this mode, but does not use them for authentication. User Management does not offer manual user creation or local-password resets until you select a password-capable mode.\n\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:admin-guide/authentication/password-authentication", "parent_id": "section:admin-guide/authentication", "depth": 2, "kind": "page", "label": "password-authentication", "title": "Password Authentication", "path": "admin-guide/authentication/password-authentication", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "authored"}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "inherited", "source_version": "0.9"}}, "content_versions": {"0.9": "+++\ntitle = \"Password Authentication\"\n+++\n\nPassword authentication uses Sambee's local username and password form. Select **Password only** in **Settings** \u003e **Administration** \u003e **Authentication** when local credentials should be the only sign-in method.\n\nSee [Authentication Overview](../authentication-overview/) to compare all authentication modes.\n\nAdministrators can create users and set or reset local passwords in **Password only** and **OIDC or password** modes. Sambee retains existing password hashes when local-password sign-in is disabled, but User Management cannot create or reset local passwords until a password-capable mode is active again.\n\n## Switch to Password-Only Access\n\nThe web activation requires at least one active, unexpired administrator with a local password. Before confirmation, Sambee shows how many active, unexpired accounts have no local password and requires explicit acknowledgement that they will lose sign-in access.\n\nSambee revokes all current sessions only when the configuration and displayed account count are still current. If either changes, Authentication settings reloads the current impact and requires confirmation again.\n\n## Recover From an OIDC Failure\n\nIf OIDC prevents web access, run the backend CLI from the application environment:\n\n```bash\ncd backend\npython -m app.oidc_admin set-mode password-only\n```\n\nFor Docker Compose, run the same module inside the backend container. The command displays the number of active local-password administrators and active passwordless accounts that will lose access. Review those counts, then type `password-only` exactly to confirm. Sambee rechecks the configuration and both counts before applying the change; if they changed, rerun the command and review the new impact.\n\nThe command refuses to proceed if no active local-password administrator exists. For deliberate containment of a compromised identity provider, `set-mode password-only --force` permits the switch after an explicit warning and confirmation. This leaves no usable administrator and is not a credential-reset or login-bypass mechanism. `--force` is rejected when a usable local administrator exists.\n\n", "1.0": "+++\ntitle = \"Password Authentication\"\n+++\n\nPassword authentication uses Sambee's local username and password form. Select **Password only** in **Settings** \u003e **Administration** \u003e **Authentication** when local credentials should be the only sign-in method.\n\nSee [Authentication Overview](../authentication-overview/) to compare all authentication modes.\n\nAdministrators can create users and set or reset local passwords in **Password only** and **OIDC or password** modes. Sambee retains existing password hashes when local-password sign-in is disabled, but User Management cannot create or reset local passwords until a password-capable mode is active again.\n\n## Switch to Password-Only Access\n\nThe web activation requires at least one active, unexpired administrator with a local password. Before confirmation, Sambee shows how many active, unexpired accounts have no local password and requires explicit acknowledgement that they will lose sign-in access.\n\nSambee revokes all current sessions only when the configuration and displayed account count are still current. If either changes, Authentication settings reloads the current impact and requires confirmation again.\n\n## Recover From an OIDC Failure\n\nIf OIDC prevents web access, run the backend CLI from the application environment:\n\n```bash\ncd backend\npython -m app.oidc_admin set-mode password-only\n```\n\nFor Docker Compose, run the same module inside the backend container. The command displays the number of active local-password administrators and active passwordless accounts that will lose access. Review those counts, then type `password-only` exactly to confirm. Sambee rechecks the configuration and both counts before applying the change; if they changed, rerun the command and review the new impact.\n\nThe command refuses to proceed if no active local-password administrator exists. For deliberate containment of a compromised identity provider, `set-mode password-only --force` permits the switch after an explicit warning and confirmation. This leaves no usable administrator and is not a credential-reset or login-bypass mechanism. `--force` is rejected when a usable local administrator exists.\n\n", "2.0": "+++\ntitle = \"Password Authentication\"\n+++\n\nPassword authentication uses Sambee's local username and password form. Select **Password only** in **Settings** \u003e **Administration** \u003e **Authentication** when local credentials should be the only sign-in method.\n\nSee [Authentication Overview](../authentication-overview/) to compare all authentication modes.\n\nAdministrators can create users and set or reset local passwords in **Password only** and **OIDC or password** modes. Sambee retains existing password hashes when local-password sign-in is disabled, but User Management cannot create or reset local passwords until a password-capable mode is active again.\n\n## Switch to Password-Only Access\n\nThe web activation requires at least one active, unexpired administrator with a local password. Before confirmation, Sambee shows how many active, unexpired accounts have no local password and requires explicit acknowledgement that they will lose sign-in access.\n\nSambee revokes all current sessions only when the configuration and displayed account count are still current. If either changes, Authentication settings reloads the current impact and requires confirmation again.\n\n## Recover From an OIDC Failure\n\nIf OIDC prevents web access, run the backend CLI from the application environment:\n\n```bash\ncd backend\npython -m app.oidc_admin set-mode password-only\n```\n\nFor Docker Compose, run the same module inside the backend container. The command displays the number of active local-password administrators and active passwordless accounts that will lose access. Review those counts, then type `password-only` exactly to confirm. Sambee rechecks the configuration and both counts before applying the change; if they changed, rerun the command and review the new impact.\n\nThe command refuses to proceed if no active local-password administrator exists. For deliberate containment of a compromised identity provider, `set-mode password-only --force` permits the switch after an explicit warning and confirmation. This leaves no usable administrator and is not a credential-reset or login-bypass mechanism. `--force` is rejected when a usable local administrator exists.\n\n"}, "page_contents": {"0.9": "+++\ntitle = \"Password Authentication\"\n+++\n\nPassword authentication uses Sambee's local username and password form. Select **Password only** in **Settings** \u003e **Administration** \u003e **Authentication** when local credentials should be the only sign-in method.\n\nSee [Authentication Overview](../authentication-overview/) to compare all authentication modes.\n\nAdministrators can create users and set or reset local passwords in **Password only** and **OIDC or password** modes. Sambee retains existing password hashes when local-password sign-in is disabled, but User Management cannot create or reset local passwords until a password-capable mode is active again.\n\n## Switch to Password-Only Access\n\nThe web activation requires at least one active, unexpired administrator with a local password. Before confirmation, Sambee shows how many active, unexpired accounts have no local password and requires explicit acknowledgement that they will lose sign-in access.\n\nSambee revokes all current sessions only when the configuration and displayed account count are still current. If either changes, Authentication settings reloads the current impact and requires confirmation again.\n\n## Recover From an OIDC Failure\n\nIf OIDC prevents web access, run the backend CLI from the application environment:\n\n```bash\ncd backend\npython -m app.oidc_admin set-mode password-only\n```\n\nFor Docker Compose, run the same module inside the backend container. The command displays the number of active local-password administrators and active passwordless accounts that will lose access. Review those counts, then type `password-only` exactly to confirm. Sambee rechecks the configuration and both counts before applying the change; if they changed, rerun the command and review the new impact.\n\nThe command refuses to proceed if no active local-password administrator exists. For deliberate containment of a compromised identity provider, `set-mode password-only --force` permits the switch after an explicit warning and confirmation. This leaves no usable administrator and is not a credential-reset or login-bypass mechanism. `--force` is rejected when a usable local administrator exists.\n\n", "1.0": "+++\ntitle = \"Password Authentication\"\n+++\n\nPassword authentication uses Sambee's local username and password form. Select **Password only** in **Settings** \u003e **Administration** \u003e **Authentication** when local credentials should be the only sign-in method.\n\nSee [Authentication Overview](../authentication-overview/) to compare all authentication modes.\n\nAdministrators can create users and set or reset local passwords in **Password only** and **OIDC or password** modes. Sambee retains existing password hashes when local-password sign-in is disabled, but User Management cannot create or reset local passwords until a password-capable mode is active again.\n\n## Switch to Password-Only Access\n\nThe web activation requires at least one active, unexpired administrator with a local password. Before confirmation, Sambee shows how many active, unexpired accounts have no local password and requires explicit acknowledgement that they will lose sign-in access.\n\nSambee revokes all current sessions only when the configuration and displayed account count are still current. If either changes, Authentication settings reloads the current impact and requires confirmation again.\n\n## Recover From an OIDC Failure\n\nIf OIDC prevents web access, run the backend CLI from the application environment:\n\n```bash\ncd backend\npython -m app.oidc_admin set-mode password-only\n```\n\nFor Docker Compose, run the same module inside the backend container. The command displays the number of active local-password administrators and active passwordless accounts that will lose access. Review those counts, then type `password-only` exactly to confirm. Sambee rechecks the configuration and both counts before applying the change; if they changed, rerun the command and review the new impact.\n\nThe command refuses to proceed if no active local-password administrator exists. For deliberate containment of a compromised identity provider, `set-mode password-only --force` permits the switch after an explicit warning and confirmation. This leaves no usable administrator and is not a credential-reset or login-bypass mechanism. `--force` is rejected when a usable local administrator exists.\n\n", "2.0": "+++\ntitle = \"Password Authentication\"\n+++\n\nPassword authentication uses Sambee's local username and password form. Select **Password only** in **Settings** \u003e **Administration** \u003e **Authentication** when local credentials should be the only sign-in method.\n\nSee [Authentication Overview](../authentication-overview/) to compare all authentication modes.\n\nAdministrators can create users and set or reset local passwords in **Password only** and **OIDC or password** modes. Sambee retains existing password hashes when local-password sign-in is disabled, but User Management cannot create or reset local passwords until a password-capable mode is active again.\n\n## Switch to Password-Only Access\n\nThe web activation requires at least one active, unexpired administrator with a local password. Before confirmation, Sambee shows how many active, unexpired accounts have no local password and requires explicit acknowledgement that they will lose sign-in access.\n\nSambee revokes all current sessions only when the configuration and displayed account count are still current. If either changes, Authentication settings reloads the current impact and requires confirmation again.\n\n## Recover From an OIDC Failure\n\nIf OIDC prevents web access, run the backend CLI from the application environment:\n\n```bash\ncd backend\npython -m app.oidc_admin set-mode password-only\n```\n\nFor Docker Compose, run the same module inside the backend container. The command displays the number of active local-password administrators and active passwordless accounts that will lose access. Review those counts, then type `password-only` exactly to confirm. Sambee rechecks the configuration and both counts before applying the change; if they changed, rerun the command and review the new impact.\n\nThe command refuses to proceed if no active local-password administrator exists. For deliberate containment of a compromised identity provider, `set-mode password-only --force` permits the switch after an explicit warning and confirmation. This leaves no usable administrator and is not a credential-reset or login-bypass mechanism. `--force` is rejected when a usable local administrator exists.\n\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:admin-guide/authentication/openid-connect-authentication-setup", "parent_id": "section:admin-guide/authentication", "depth": 2, "kind": "page", "label": "openid-connect-authentication-setup", "title": "Openid Connect Authentication Setup", "path": "admin-guide/authentication/openid-connect-authentication-setup", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "authored"}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "branched", "source_version": "0.9", "diff_added": 23, "diff_removed": 7}}, "content_versions": {"0.9": "+++\ntitle = \"OpenID Connect Authentication Setup\"\n+++\n\nOpenID Connect (OIDC) is Sambee's preferred authentication method.\n\n## Preparation\n\n### Copy OIDC Callback URI\n\nOpen **Settings** \u003e **Administration** \u003e **Authentication** and select an OIDC authentication mode. Select **Configure OIDC** and copy the OIDC callback URI from the dialog that opens. You need the URI in the next step. It has the following format:\n\n```text\nhttps://files.example.com/api/auth/oidc/callback\n```\n\n## Configure the OpenID Connect Identity Provider (IdP)\n\n### Provider Properties\n\nIn your identity provider, create a new OpenID Connect IdP with the following properties:\n\n- Confidential web client\n- Authorization code flow\n- PKCE with `S256`\n- `client_secret_basic` token endpoint authentication\n- `RS256`-signed ID tokens\n- Sambee's callback URI (see above)\n- The scopes `openid`, `profile`, `email`, and `offline_access`\n   - Add `groups` only when using group admission or group-based role mappings\n- Authorization-code and refresh-token grants\n\nConfigure token lifetimes:\n\n- Refresh token:\n   - A shorter lifetime requires users to sign in again sooner.\n   - A longer lifetime increases the impact period if the token is compromised.\n   - Maximum useful length: slightly longer than Sambee's interactive sign-in interval (default: 30 days).\n- Access token and ID token:\n   - Lifetimes should be short, e.g., 1 hour.\n\n### Verify the Username Claim\n\nSambee needs to match OIDC provider usernames to its own usernames. Many OIDC providers return a username in the field `preferred_username` when the `profile` scope is enabled. To ensure that username claim is suitable, verify the following with your OIDC provider:\n\n- How to enable returning the username claim (typically through the `profile` scope).\n- The field name of the username claim (typically `preferred_username`).\n- The username claim is present for every person who can sign in, stable for that person, and unique across all provider users.\n\n### Authelia Example\n\nThe relevant Authelia client entry can look like this:\n\n```yaml\nidentity_providers:\n  oidc:\n    lifespans:\n      custom:\n        sambee:\n          # Maximum useful length: Sambee's interactive sign-in interval + 1 day\n          refresh_token: '31d'\n    clients:\n      - client_id: sambee\n        client_name: Sambee\n        client_secret: '$pbkdf2-sha512$replace-with-a-hashed-random-secret'\n        redirect_uris:\n          - https://files.example.com/api/auth/oidc/callback\n        grant_types:\n          - authorization_code\n          - refresh_token\n        response_types:\n          - code\n        lifespan: sambee\n        scopes:\n          - openid\n          - profile\n          - email\n          - offline_access\n          # Add groups when using group admission or group-based role mappings.\n          - groups\n```\n\nNotes:\n\n- See Authelia's instructions for generating a [hashed client secret](https://www.authelia.com/integration/openid-connect/frequently-asked-questions/#how-do-i-generate-a-client-identifier-or-client-secret).\n- Use your own values for the following fields: `redirect_uris`.\n- The `profile` scope makes Authelia's `preferred_username` claim available from the username used to sign in, which is exactly what Sambee expects in its default OIDC settings (see below).\n- See the [Authelia documentation](https://www.authelia.com/configuration/identity-providers/openid-connect/clients/) more details and default values.\n\n## Configure Sambee\n\nOpen **Settings** \u003e **Administration** \u003e **Authentication**.\n\n### 1. Choose the Sign-In Mode\n\nSelect one of these values in **Authentication mode**:\n\n- **OIDC or password**\n- **OIDC only**\n\nThe **Access** panel shows whether OIDC is configured and healthy. Select **Configure OIDC** to enter or change the provider settings.\n\n### 2. Enter Provider Details\n\nIn the setup dialog, complete these fields in the **Provider** section:\n\n| Sambee field | Value to enter |\n|---|---|\n| **Provider name** | A recognizable name for the provider, such as `Authelia` or `Microsoft Entra ID`. |\n| **Issuer URL** | The provider's HTTPS issuer URL. For Authelia, this is normally the externally reachable URL of the Authelia portal, such as `https://auth.example.com`. \u003cbr /\u003eOpen `https://auth.example.com/.well-known/openid-configuration` and enter the exact value of its `issuer` field. |\n| **Client ID** | The client ID configured in the OIDC IdP. |\n| **Client secret** | The matching client secret as plain text (unhashed).\u003cbr /\u003eOn later changes, leave this blank to retain the stored secret. \u003cbr /\u003eThe visibility button only reveals the value currently typed in the browser; Sambee never returns the stored secret. |\n| **Scopes** | A comma-separated list. Include `openid`, `offline_access`, and every scope required to return the claims configured below, such as `profile` and `email`. Add `groups` when using group admission or group-based role mappings. |\n\n### 3. Configure Session Policy\n\nSet **Interactive sign-in interval (days)** to control how long a verified IdP sign-in can be renewed in the background. The default is 30 days.\n\nDuring this interval, Sambee refreshes its short-lived API token in the background. At the interval deadline, Sambee requires a fresh interactive IdP sign-in.\n\n### 4. Configure Access\n\nComplete these fields in the **Access** section:\n\n| Sambee field | Value to enter |\n|---|---|\n| **Admission** | **All authenticated users** is the default. Select **Only selected groups** to require membership in named groups before Sambee evaluates the person's role. |\n| **Admission groups** | When **Admission** is **Only selected groups**, enter the exact identity-provider groups that may sign in, separated by commas. |\n\n### 5. Configure Role Assignment\n\nChoose how Sambee assigns roles after an identity passes the admission policy:\n\n| Role assignment | Behavior |\n|---|---|\n| **All users are assigned to the same role** | Select **Administrator**, **Editor** (default), or **Viewer**. Every admitted user receives that role unless they have an individual assignment. This is the simplest choice for smaller environments. |\n| **Group-based** | Enter exact identity-provider groups for **Administrator**, **Editor**, and **Viewer**. A person without an individual assignment must match a configured group; otherwise Sambee denies access. |\n\nIn group-based mode, a group can appear in only one role mapping. When a person matches multiple mappings, Sambee grants the highest role: Administrator, then Editor, then Viewer.\n\nDuring activation (see below), Sambee gives the administrator completing the test an individual **Administrator** assignment. Individual assignments for linked or pending accounts always take precedence over the configured role assignment.\n\n### 6. Advanced Claims\n\nThe default claim names work with most OpenID Connect providers. Expand **Advanced claims** only when the provider returns different claim names.\n\n#### Claims\n\n| Sambee field | Value to enter |\n|---|---|\n| **Username claim** | The stable, unique claim used to identify a person, commonly `preferred_username`. |\n| **Name claim** | Optional claim containing the person's display name, commonly `name`. |\n| **Email claim** | Optional claim containing the person's email address, commonly `email`. |\n| **Groups claim** | Optional claim containing group membership, commonly `groups`. Required only for selected-group admission or group-based role assignment. |\n\nSambee records the OIDC issuer and subject for each linked account. By default, Sambee also treats the configured IdP as authoritative for usernames: when an admitted IdP user has the same username as a local account, Sambee links that identity to the local account. This also updates an existing link when an IdP migration changes the issuer or subject. Keep **Automatically link OIDC identities to local accounts by username** enabled unless you need to resolve username matches manually.\n\n### 7. Connect and Test\n\nSelect **Connect and test** in the setup dialog. Sambee redirects you to the provider and returns to the dialog for review. This verifies that:\n\n- Signing in via the specified OIDC configuration succeeds.\n- Sambee can read and evaluate the resulting OIDC user identity.\n- The tested identity passes the selected admission rule, so the current administrator can keep administrator access after activation.\n\nReview the resulting identity before activation:\n\n- **Username**, **Email**, and **Groups** show the claims Sambee received.\n- **Admission** and **Matching admission group** show whether the tested identity passes the admission rule.\n\nOIDC activation remains unavailable unless the tested OIDC identity passes the admission rule to prevent the local admin making the changes from locking themselves out.\n\n### 8. Review and Activate\n\nSelect **Activate configuration** when the review is complete. The administrator who started the setup is linked to the tested provider identity automatically.\n\nWhen OIDC is active, users sign in normally after an IdP migration or subject reset. With automatic username linking enabled, Sambee updates their stored OIDC link during their next admitted sign-in and signs out existing Sambee sessions for that account. Until then, their existing OIDC link and IdP-managed full name and email remain read-only in User Management.\n\nAfter activation, see [OpenID Connect Authentication Operations](../openid-connect-authentication-operations/) for session, account-mapping, auditing, and request-limit administration.\n", "1.0": "+++\ntitle = \"OpenID Connect Authentication Setup\"\n+++\n\nOpenID Connect (OIDC) is Sambee's preferred authentication method.\n\n## Preparation\n\n### Copy OIDC Callback URI\n\nOpen **Settings** \u003e **Administration** \u003e **Authentication** and select an OIDC authentication mode. Select **Configure OIDC** and copy the OIDC callback URI from the dialog that opens. You need the URI in the next step. It has the following format:\n\n```text\nhttps://files.example.com/api/auth/oidc/callback\n```\n\n## Configure the OpenID Connect Identity Provider (IdP)\n\n### Provider Properties\n\nIn your identity provider, create a new OpenID Connect IdP with the following properties:\n\n- Confidential web client\n- Authorization code flow\n- PKCE with `S256`\n- `client_secret_basic` token endpoint authentication\n- `RS256`-signed ID tokens\n- Sambee's callback URI (see above)\n- The scopes `openid`, `profile`, `email`, and `offline_access`\n   - Add `groups` only when using group admission or group-based role mappings\n- Authorization-code and refresh-token grants\n\nConfigure token lifetimes:\n\n- Refresh token:\n   - A shorter lifetime requires users to sign in again sooner.\n   - A longer lifetime increases the impact period if the token is compromised.\n   - Maximum useful length: slightly longer than Sambee's interactive sign-in interval (default: 30 days).\n- Access token and ID token:\n   - Lifetimes should be short, e.g., 1 hour.\n\n### Verify the Username Claim\n\nSambee needs to match OIDC provider usernames to its own usernames. Many OIDC providers return a username in the field `preferred_username` when the `profile` scope is enabled. To ensure that username claim is suitable, verify the following with your OIDC provider:\n\n- How to enable returning the username claim (typically through the `profile` scope).\n- The field name of the username claim (typically `preferred_username`).\n- The username claim is present for every person who can sign in, stable for that person, and unique across all provider users.\n\n### Authelia Example\n\nThe relevant Authelia client entry can look like this:\n\n```yaml\nidentity_providers:\n  oidc:\n    lifespans:\n      custom:\n        sambee:\n          # Maximum useful length: Sambee's interactive sign-in interval + 1 day\n          refresh_token: '31d'\n    clients:\n      - client_id: sambee\n        client_name: Sambee\n        client_secret: '$pbkdf2-sha512$replace-with-a-hashed-random-secret'\n        redirect_uris:\n          - https://files.example.com/api/auth/oidc/callback\n        grant_types:\n          - authorization_code\n          - refresh_token\n        response_types:\n          - code\n        lifespan: sambee\n        scopes:\n          - openid\n          - profile\n          - email\n          - offline_access\n          # Add groups when using group admission or group-based role mappings.\n          - groups\n```\n\nNotes:\n\n- See Authelia's instructions for generating a [hashed client secret](https://www.authelia.com/integration/openid-connect/frequently-asked-questions/#how-do-i-generate-a-client-identifier-or-client-secret).\n- Use your own values for the following fields: `redirect_uris`.\n- The `profile` scope makes Authelia's `preferred_username` claim available from the username used to sign in, which is exactly what Sambee expects in its default OIDC settings (see below).\n- See the [Authelia documentation](https://www.authelia.com/configuration/identity-providers/openid-connect/clients/) more details and default values.\n\n## Configure Sambee\n\nOpen **Settings** \u003e **Administration** \u003e **Authentication**.\n\n### 1. Choose the Sign-In Mode\n\nSelect one of these values in **Authentication mode**:\n\n- **OIDC or password**\n- **OIDC only**\n\nThe **Access** panel shows whether OIDC is configured and healthy. Select **Configure OIDC** to enter or change the provider settings.\n\n### 2. Enter Provider Details\n\nIn the setup dialog, complete these fields in the **Provider** section:\n\n| Sambee field | Value to enter |\n|---|---|\n| **Provider name** | A recognizable name for the provider, such as `Authelia` or `Microsoft Entra ID`. |\n| **Issuer URL** | The provider's HTTPS issuer URL. For Authelia, this is normally the externally reachable URL of the Authelia portal, such as `https://auth.example.com`. \u003cbr /\u003eOpen `https://auth.example.com/.well-known/openid-configuration` and enter the exact value of its `issuer` field. |\n| **Client ID** | The client ID configured in the OIDC IdP. |\n| **Client secret** | The matching client secret as plain text (unhashed).\u003cbr /\u003eOn later changes, leave this blank to retain the stored secret. \u003cbr /\u003eThe visibility button only reveals the value currently typed in the browser; Sambee never returns the stored secret. |\n| **Scopes** | A comma-separated list. Include `openid`, `offline_access`, and every scope required to return the claims configured below, such as `profile` and `email`. Add `groups` when using group admission or group-based role mappings. |\n\n### 3. Configure Session Policy\n\nSet **Interactive sign-in interval (days)** to control how long a verified IdP sign-in can be renewed in the background. The default is 30 days.\n\nDuring this interval, Sambee refreshes its short-lived API token in the background. At the interval deadline, Sambee requires a fresh interactive IdP sign-in.\n\n### 4. Configure Access\n\nComplete these fields in the **Access** section:\n\n| Sambee field | Value to enter |\n|---|---|\n| **Admission** | **All authenticated users** is the default. Select **Only selected groups** to require membership in named groups before Sambee evaluates the person's role. |\n| **Admission groups** | When **Admission** is **Only selected groups**, enter the exact identity-provider groups that may sign in, separated by commas. |\n\n### 5. Configure Role Assignment\n\nChoose how Sambee assigns roles after an identity passes the admission policy:\n\n| Role assignment | Behavior |\n|---|---|\n| **All users are assigned to the same role** | Select **Administrator**, **Editor** (default), or **Viewer**. Every admitted user receives that role unless they have an individual assignment. This is the simplest choice for smaller environments. |\n| **Group-based** | Enter exact identity-provider groups for **Administrator**, **Editor**, and **Viewer**. A person without an individual assignment must match a configured group; otherwise Sambee denies access. |\n\nIn group-based mode, a group can appear in only one role mapping. When a person matches multiple mappings, Sambee grants the highest role: Administrator, then Editor, then Viewer.\n\nDuring activation (see below), Sambee gives the administrator completing the test an individual **Administrator** assignment. Individual assignments for linked or pending accounts always take precedence over the configured role assignment.\n\n### 6. Advanced Claims\n\nThe default claim names work with most OpenID Connect providers. Expand **Advanced claims** only when the provider returns different claim names.\n\n#### Claims\n\n| Sambee field | Value to enter |\n|---|---|\n| **Username claim** | The stable, unique claim used to identify a person, commonly `preferred_username`. |\n| **Name claim** | Optional claim containing the person's display name, commonly `name`. |\n| **Email claim** | Optional claim containing the person's email address, commonly `email`. |\n| **Groups claim** | Optional claim containing group membership, commonly `groups`. Required only for selected-group admission or group-based role assignment. |\n\nSambee records the OIDC issuer and subject for each linked account. By default, Sambee also treats the configured IdP as authoritative for usernames: when an admitted IdP user has the same username as a local account, Sambee links that identity to the local account. This also updates an existing link when an IdP migration changes the issuer or subject. Keep **Automatically link OIDC identities to local accounts by username** enabled unless you need to resolve username matches manually.\n\n### 7. Connect and Test\n\nSelect **Connect and test** in the setup dialog. Sambee redirects you to the provider and returns to the dialog for review. This verifies that:\n\n- Signing in via the specified OIDC configuration succeeds.\n- Sambee can read and evaluate the resulting OIDC user identity.\n- The tested identity passes the selected admission rule, so the current administrator can keep administrator access after activation.\n\nReview the resulting identity before activation:\n\n- **Username**, **Email**, and **Groups** show the claims Sambee received.\n- **Admission** and **Matching admission group** show whether the tested identity passes the admission rule.\n\nOIDC activation remains unavailable unless the tested OIDC identity passes the admission rule to prevent the local admin making the changes from locking themselves out.\n\n### 8. Review and Activate\n\nSelect **Activate configuration** when the review is complete. The administrator who started the setup is linked to the tested provider identity automatically.\n\nWhen OIDC is active, users sign in normally after an IdP migration or subject reset. With automatic username linking enabled, Sambee updates their stored OIDC link during their next admitted sign-in and signs out existing Sambee sessions for that account. Until then, their existing OIDC link and IdP-managed full name and email remain read-only in User Management.\n\nAfter activation, see [OpenID Connect Authentication Operations](../openid-connect-authentication-operations/) for session, account-mapping, auditing, and request-limit administration.\n", "2.0": "+++\ntitle = \"OpenID Connect Authentication Setup\"\n+++\n\nOpenID Connect (OIDC) is Sambee's preferred authentication method.\n\n## Preparation\n\n### Copy OIDC Callback URI\n\nOpen **Settings** \u003e **Administration** \u003e **Authentication** and select an OIDC authentication mode. Select **Configure OIDC** and copy the OIDC callback URI from the dialog that opens. You need the URI in the next step. It has the following format:\n\n```text\nhttps://files.example.com/api/auth/oidc/callback\n```\n\n## Configure the OpenID Connect Identity Provider (IdP)\n\n### Provider Properties\n\nIn your identity provider, create a new OpenID Connect IdP with the following properties:\n\n- Confidential web client\n- Authorization code flow\n- PKCE with `S256`\n- `client_secret_basic` token endpoint authentication\n- `RS256`-signed ID tokens\n- Sambee's callback URI (see above)\n- Scopes:\n   - `openid`: required\n   - `profile`: often necessary for the provider to return `preferred_username`, which Sambee requires\n   - `email`: optional\n   - `groups`: required when using group admission or group-based role mappings\n   - `offline_access`: may be required for refresh tokens, depending on the provider\n- Authorization code grant\n- Refresh token grant: optional\n\n#### Token Lifetimes\n\nConfigure token lifetimes:\n\n- Refresh token, if the provider issues one:\n   - A shorter lifetime requires users to sign in again sooner.\n   - A longer lifetime increases the impact period if the token is compromised.\n   - Maximum useful length: slightly longer than Sambee's interactive sign-in interval (default: 30 days).\n- Access token and ID token:\n   - Lifetimes should be short, e.g., 1 hour.\n\n#### Refresh Tokens\n\nHaving the provider issue refresh tokens is recommended as that enables background session renewal without user interaction.\n\nProviders that don't issue refresh tokens can still be used with Sambee. They must return an ID token with a valid `auth_time` claim when Sambee requests `max_age`.\n\n### Verify the Username Claim\n\nSambee needs to match OIDC provider usernames to its own usernames. Many OIDC providers return a username in the field `preferred_username` when the `profile` scope is enabled. To ensure that username claim is suitable, verify the following with your OIDC provider:\n\n- How to enable returning the username claim (typically through the `profile` scope).\n- The field name of the username claim (typically `preferred_username`).\n- The username claim is present for every person who can sign in, stable for that person, and unique across all provider users.\n\n### Authelia Example\n\nThe relevant Authelia client entry can look like this:\n\n```yaml\nidentity_providers:\n  oidc:\n    lifespans:\n      custom:\n        sambee:\n          # Maximum useful length: Sambee's interactive sign-in interval + 1 day\n          refresh_token: '31d'\n    clients:\n      - client_id: sambee\n        client_name: Sambee\n        client_secret: '$pbkdf2-sha512$replace-with-a-hashed-random-secret'\n        redirect_uris:\n          - https://files.example.com/api/auth/oidc/callback\n        grant_types:\n          - authorization_code\n          - refresh_token\n        response_types:\n          - code\n        lifespan: sambee\n        scopes:\n          - openid\n          - profile\n          - email\n          - offline_access\n          # Add groups when using group admission or group-based role mappings.\n          - groups\n```\n\nNotes:\n\n- See Authelia's instructions for generating a [hashed client secret](https://www.authelia.com/integration/openid-connect/frequently-asked-questions/#how-do-i-generate-a-client-identifier-or-client-secret).\n- Use your own values for the following fields: `redirect_uris`.\n- The `profile` scope makes Authelia's `preferred_username` claim available from the username used to sign in, which is exactly what Sambee expects in its default OIDC settings (see below).\n- See the [Authelia documentation](https://www.authelia.com/configuration/identity-providers/openid-connect/clients/) more details and default values.\n\n## Configure Sambee\n\nOpen **Settings** \u003e **Administration** \u003e **Authentication**.\n\n### 1. Choose the Sign-In Mode\n\nSelect one of these values in **Authentication mode**:\n\n- **OIDC or password**\n- **OIDC only**\n\nThe **Access** panel shows whether OIDC is configured and healthy. Select **Configure OIDC** to enter or change the provider settings.\n\n### 2. Enter Provider Details\n\nIn the setup dialog, complete these fields in the **Provider** section:\n\n| Sambee field | Value to enter |\n|---|---|\n| **Provider name** | A recognizable name for the provider, such as `Authelia` or `Microsoft Entra ID`. |\n| **Issuer URL** | The provider's HTTPS issuer URL. For Authelia, this is normally the externally reachable URL of the Authelia portal, such as `https://auth.example.com`. \u003cbr /\u003eOpen `https://auth.example.com/.well-known/openid-configuration` and enter the exact value of its `issuer` field. |\n| **Client ID** | The client ID configured in the OIDC IdP. |\n| **Client secret** | The matching client secret as plain text (unhashed).\u003cbr /\u003eOn later changes, leave this blank to retain the stored secret. \u003cbr /\u003eThe visibility button only reveals the value currently typed in the browser; Sambee never returns the stored secret. |\n| **Scopes** | A comma-separated list. Include `openid` and every scope required for the configured claims, such as `profile` and `email`. Add `groups` for group admission or group-based role mappings. Add `offline_access` only if supported and needed for provider refresh tokens. |\n\n### 3. Configure Session Policy\n\nSet **Interactive sign-in interval (days)** to control the maximum age of a verified IdP sign-in. The default is 30 days.\n\nSet **Session limit without refresh token (hours)** separately for sign-ins that return no refresh token (default 8 hours; allowed range 1-24 hours).\n\nSambee issues short-lived API tokens (up to 60 minutes) while the browser session remains valid. With a refresh token, Sambee can renew through the IdP until the authentication-age limit. Without one, Sambee can issue another API token from the browser cookie only until the fixed session limit. Reducing that limit shortens existing no-refresh sessions; increasing it does not extend them. When the applicable deadline arrives, Sambee starts a new top-level IdP authorization, which might reuse the IdP's existing SSO session.\n\n### 4. Configure Access\n\nComplete these fields in the **Access** section:\n\n| Sambee field | Value to enter |\n|---|---|\n| **Admission** | **All authenticated users** is the default. Select **Only selected groups** to require membership in named groups before Sambee evaluates the person's role. |\n| **Admission groups** | When **Admission** is **Only selected groups**, enter the exact identity-provider groups that may sign in, separated by commas. |\n\n### 5. Configure Role Assignment\n\nChoose how Sambee assigns roles after an identity passes the admission policy:\n\n| Role assignment | Behavior |\n|---|---|\n| **All users are assigned to the same role** | Select **Administrator**, **Editor** (default), or **Viewer**. Every admitted user receives that role unless they have an individual assignment. This is the simplest choice for smaller environments. |\n| **Group-based** | Enter exact identity-provider groups for **Administrator**, **Editor**, and **Viewer**. A person without an individual assignment must match a configured group; otherwise Sambee denies access. |\n\nIn group-based mode, a group can appear in only one role mapping. When a person matches multiple mappings, Sambee grants the highest role: Administrator, then Editor, then Viewer.\n\nDuring activation (see below), Sambee gives the administrator completing the test an individual **Administrator** assignment. Individual assignments for linked or pending accounts always take precedence over the configured role assignment.\n\n### 6. Advanced Claims\n\nThe default claim names work with most OpenID Connect providers. Expand **Advanced claims** only when the provider returns different claim names.\n\n#### Claims\n\n| Sambee field | Value to enter |\n|---|---|\n| **Username claim** | The stable, unique claim used to identify a person, commonly `preferred_username`. |\n| **Name claim** | Optional claim containing the person's display name, commonly `name`. |\n| **Email claim** | Optional claim containing the person's email address, commonly `email`. |\n| **Groups claim** | Optional claim containing group membership, commonly `groups`. Required only for selected-group admission or group-based role assignment. |\n\nSambee records the OIDC issuer and subject for each linked account. By default, Sambee also treats the configured IdP as authoritative for usernames: when an admitted IdP user has the same username as a local account, Sambee links that identity to the local account. This also updates an existing link when an IdP migration changes the issuer or subject. Keep **Automatically link OIDC identities to local accounts by username** enabled unless you need to resolve username matches manually.\n\n### 7. Connect and Test\n\nSelect **Connect and test** in the setup dialog. Sambee redirects you to the provider and returns to the dialog for review. This verifies that:\n\n- Signing in via the specified OIDC configuration succeeds.\n- Sambee can read and evaluate the resulting OIDC user identity.\n- The tested identity passes the selected admission rule, so the current administrator can keep administrator access after activation.\n\nReview the resulting identity before activation:\n\n- **Username**, **Email**, and **Groups** show the claims Sambee received.\n- **Admission** and **Matching admission group** show whether the tested identity passes the admission rule.\n- **Session renewal** reports whether this particular test returned a refresh token. A test without one can still succeed; users will need to sign in again after the configured no-refresh session limit.\n\nOIDC activation remains unavailable unless the tested OIDC identity passes the admission rule to prevent the local admin making the changes from locking themselves out.\n\n### 8. Review and Activate\n\nSelect **Activate configuration** when the review is complete. The administrator who started the setup is linked to the tested provider identity automatically.\n\nWhen OIDC is active, users sign in normally after an IdP migration or subject reset. With automatic username linking enabled, Sambee updates their stored OIDC link during their next admitted sign-in and signs out existing Sambee sessions for that account. Until then, their existing OIDC link and IdP-managed full name and email remain read-only in User Management.\n\nAfter activation, see [OpenID Connect Authentication Operations](../openid-connect-authentication-operations/) for session, account-mapping, auditing, and request-limit administration.\n"}, "page_contents": {"0.9": "+++\ntitle = \"OpenID Connect Authentication Setup\"\n+++\n\nOpenID Connect (OIDC) is Sambee's preferred authentication method.\n\n## Preparation\n\n### Copy OIDC Callback URI\n\nOpen **Settings** \u003e **Administration** \u003e **Authentication** and select an OIDC authentication mode. Select **Configure OIDC** and copy the OIDC callback URI from the dialog that opens. You need the URI in the next step. It has the following format:\n\n```text\nhttps://files.example.com/api/auth/oidc/callback\n```\n\n## Configure the OpenID Connect Identity Provider (IdP)\n\n### Provider Properties\n\nIn your identity provider, create a new OpenID Connect IdP with the following properties:\n\n- Confidential web client\n- Authorization code flow\n- PKCE with `S256`\n- `client_secret_basic` token endpoint authentication\n- `RS256`-signed ID tokens\n- Sambee's callback URI (see above)\n- The scopes `openid`, `profile`, `email`, and `offline_access`\n   - Add `groups` only when using group admission or group-based role mappings\n- Authorization-code and refresh-token grants\n\nConfigure token lifetimes:\n\n- Refresh token:\n   - A shorter lifetime requires users to sign in again sooner.\n   - A longer lifetime increases the impact period if the token is compromised.\n   - Maximum useful length: slightly longer than Sambee's interactive sign-in interval (default: 30 days).\n- Access token and ID token:\n   - Lifetimes should be short, e.g., 1 hour.\n\n### Verify the Username Claim\n\nSambee needs to match OIDC provider usernames to its own usernames. Many OIDC providers return a username in the field `preferred_username` when the `profile` scope is enabled. To ensure that username claim is suitable, verify the following with your OIDC provider:\n\n- How to enable returning the username claim (typically through the `profile` scope).\n- The field name of the username claim (typically `preferred_username`).\n- The username claim is present for every person who can sign in, stable for that person, and unique across all provider users.\n\n### Authelia Example\n\nThe relevant Authelia client entry can look like this:\n\n```yaml\nidentity_providers:\n  oidc:\n    lifespans:\n      custom:\n        sambee:\n          # Maximum useful length: Sambee's interactive sign-in interval + 1 day\n          refresh_token: '31d'\n    clients:\n      - client_id: sambee\n        client_name: Sambee\n        client_secret: '$pbkdf2-sha512$replace-with-a-hashed-random-secret'\n        redirect_uris:\n          - https://files.example.com/api/auth/oidc/callback\n        grant_types:\n          - authorization_code\n          - refresh_token\n        response_types:\n          - code\n        lifespan: sambee\n        scopes:\n          - openid\n          - profile\n          - email\n          - offline_access\n          # Add groups when using group admission or group-based role mappings.\n          - groups\n```\n\nNotes:\n\n- See Authelia's instructions for generating a [hashed client secret](https://www.authelia.com/integration/openid-connect/frequently-asked-questions/#how-do-i-generate-a-client-identifier-or-client-secret).\n- Use your own values for the following fields: `redirect_uris`.\n- The `profile` scope makes Authelia's `preferred_username` claim available from the username used to sign in, which is exactly what Sambee expects in its default OIDC settings (see below).\n- See the [Authelia documentation](https://www.authelia.com/configuration/identity-providers/openid-connect/clients/) more details and default values.\n\n## Configure Sambee\n\nOpen **Settings** \u003e **Administration** \u003e **Authentication**.\n\n### 1. Choose the Sign-In Mode\n\nSelect one of these values in **Authentication mode**:\n\n- **OIDC or password**\n- **OIDC only**\n\nThe **Access** panel shows whether OIDC is configured and healthy. Select **Configure OIDC** to enter or change the provider settings.\n\n### 2. Enter Provider Details\n\nIn the setup dialog, complete these fields in the **Provider** section:\n\n| Sambee field | Value to enter |\n|---|---|\n| **Provider name** | A recognizable name for the provider, such as `Authelia` or `Microsoft Entra ID`. |\n| **Issuer URL** | The provider's HTTPS issuer URL. For Authelia, this is normally the externally reachable URL of the Authelia portal, such as `https://auth.example.com`. \u003cbr /\u003eOpen `https://auth.example.com/.well-known/openid-configuration` and enter the exact value of its `issuer` field. |\n| **Client ID** | The client ID configured in the OIDC IdP. |\n| **Client secret** | The matching client secret as plain text (unhashed).\u003cbr /\u003eOn later changes, leave this blank to retain the stored secret. \u003cbr /\u003eThe visibility button only reveals the value currently typed in the browser; Sambee never returns the stored secret. |\n| **Scopes** | A comma-separated list. Include `openid`, `offline_access`, and every scope required to return the claims configured below, such as `profile` and `email`. Add `groups` when using group admission or group-based role mappings. |\n\n### 3. Configure Session Policy\n\nSet **Interactive sign-in interval (days)** to control how long a verified IdP sign-in can be renewed in the background. The default is 30 days.\n\nDuring this interval, Sambee refreshes its short-lived API token in the background. At the interval deadline, Sambee requires a fresh interactive IdP sign-in.\n\n### 4. Configure Access\n\nComplete these fields in the **Access** section:\n\n| Sambee field | Value to enter |\n|---|---|\n| **Admission** | **All authenticated users** is the default. Select **Only selected groups** to require membership in named groups before Sambee evaluates the person's role. |\n| **Admission groups** | When **Admission** is **Only selected groups**, enter the exact identity-provider groups that may sign in, separated by commas. |\n\n### 5. Configure Role Assignment\n\nChoose how Sambee assigns roles after an identity passes the admission policy:\n\n| Role assignment | Behavior |\n|---|---|\n| **All users are assigned to the same role** | Select **Administrator**, **Editor** (default), or **Viewer**. Every admitted user receives that role unless they have an individual assignment. This is the simplest choice for smaller environments. |\n| **Group-based** | Enter exact identity-provider groups for **Administrator**, **Editor**, and **Viewer**. A person without an individual assignment must match a configured group; otherwise Sambee denies access. |\n\nIn group-based mode, a group can appear in only one role mapping. When a person matches multiple mappings, Sambee grants the highest role: Administrator, then Editor, then Viewer.\n\nDuring activation (see below), Sambee gives the administrator completing the test an individual **Administrator** assignment. Individual assignments for linked or pending accounts always take precedence over the configured role assignment.\n\n### 6. Advanced Claims\n\nThe default claim names work with most OpenID Connect providers. Expand **Advanced claims** only when the provider returns different claim names.\n\n#### Claims\n\n| Sambee field | Value to enter |\n|---|---|\n| **Username claim** | The stable, unique claim used to identify a person, commonly `preferred_username`. |\n| **Name claim** | Optional claim containing the person's display name, commonly `name`. |\n| **Email claim** | Optional claim containing the person's email address, commonly `email`. |\n| **Groups claim** | Optional claim containing group membership, commonly `groups`. Required only for selected-group admission or group-based role assignment. |\n\nSambee records the OIDC issuer and subject for each linked account. By default, Sambee also treats the configured IdP as authoritative for usernames: when an admitted IdP user has the same username as a local account, Sambee links that identity to the local account. This also updates an existing link when an IdP migration changes the issuer or subject. Keep **Automatically link OIDC identities to local accounts by username** enabled unless you need to resolve username matches manually.\n\n### 7. Connect and Test\n\nSelect **Connect and test** in the setup dialog. Sambee redirects you to the provider and returns to the dialog for review. This verifies that:\n\n- Signing in via the specified OIDC configuration succeeds.\n- Sambee can read and evaluate the resulting OIDC user identity.\n- The tested identity passes the selected admission rule, so the current administrator can keep administrator access after activation.\n\nReview the resulting identity before activation:\n\n- **Username**, **Email**, and **Groups** show the claims Sambee received.\n- **Admission** and **Matching admission group** show whether the tested identity passes the admission rule.\n\nOIDC activation remains unavailable unless the tested OIDC identity passes the admission rule to prevent the local admin making the changes from locking themselves out.\n\n### 8. Review and Activate\n\nSelect **Activate configuration** when the review is complete. The administrator who started the setup is linked to the tested provider identity automatically.\n\nWhen OIDC is active, users sign in normally after an IdP migration or subject reset. With automatic username linking enabled, Sambee updates their stored OIDC link during their next admitted sign-in and signs out existing Sambee sessions for that account. Until then, their existing OIDC link and IdP-managed full name and email remain read-only in User Management.\n\nAfter activation, see [OpenID Connect Authentication Operations](../openid-connect-authentication-operations/) for session, account-mapping, auditing, and request-limit administration.\n", "1.0": "+++\ntitle = \"OpenID Connect Authentication Setup\"\n+++\n\nOpenID Connect (OIDC) is Sambee's preferred authentication method.\n\n## Preparation\n\n### Copy OIDC Callback URI\n\nOpen **Settings** \u003e **Administration** \u003e **Authentication** and select an OIDC authentication mode. Select **Configure OIDC** and copy the OIDC callback URI from the dialog that opens. You need the URI in the next step. It has the following format:\n\n```text\nhttps://files.example.com/api/auth/oidc/callback\n```\n\n## Configure the OpenID Connect Identity Provider (IdP)\n\n### Provider Properties\n\nIn your identity provider, create a new OpenID Connect IdP with the following properties:\n\n- Confidential web client\n- Authorization code flow\n- PKCE with `S256`\n- `client_secret_basic` token endpoint authentication\n- `RS256`-signed ID tokens\n- Sambee's callback URI (see above)\n- The scopes `openid`, `profile`, `email`, and `offline_access`\n   - Add `groups` only when using group admission or group-based role mappings\n- Authorization-code and refresh-token grants\n\nConfigure token lifetimes:\n\n- Refresh token:\n   - A shorter lifetime requires users to sign in again sooner.\n   - A longer lifetime increases the impact period if the token is compromised.\n   - Maximum useful length: slightly longer than Sambee's interactive sign-in interval (default: 30 days).\n- Access token and ID token:\n   - Lifetimes should be short, e.g., 1 hour.\n\n### Verify the Username Claim\n\nSambee needs to match OIDC provider usernames to its own usernames. Many OIDC providers return a username in the field `preferred_username` when the `profile` scope is enabled. To ensure that username claim is suitable, verify the following with your OIDC provider:\n\n- How to enable returning the username claim (typically through the `profile` scope).\n- The field name of the username claim (typically `preferred_username`).\n- The username claim is present for every person who can sign in, stable for that person, and unique across all provider users.\n\n### Authelia Example\n\nThe relevant Authelia client entry can look like this:\n\n```yaml\nidentity_providers:\n  oidc:\n    lifespans:\n      custom:\n        sambee:\n          # Maximum useful length: Sambee's interactive sign-in interval + 1 day\n          refresh_token: '31d'\n    clients:\n      - client_id: sambee\n        client_name: Sambee\n        client_secret: '$pbkdf2-sha512$replace-with-a-hashed-random-secret'\n        redirect_uris:\n          - https://files.example.com/api/auth/oidc/callback\n        grant_types:\n          - authorization_code\n          - refresh_token\n        response_types:\n          - code\n        lifespan: sambee\n        scopes:\n          - openid\n          - profile\n          - email\n          - offline_access\n          # Add groups when using group admission or group-based role mappings.\n          - groups\n```\n\nNotes:\n\n- See Authelia's instructions for generating a [hashed client secret](https://www.authelia.com/integration/openid-connect/frequently-asked-questions/#how-do-i-generate-a-client-identifier-or-client-secret).\n- Use your own values for the following fields: `redirect_uris`.\n- The `profile` scope makes Authelia's `preferred_username` claim available from the username used to sign in, which is exactly what Sambee expects in its default OIDC settings (see below).\n- See the [Authelia documentation](https://www.authelia.com/configuration/identity-providers/openid-connect/clients/) more details and default values.\n\n## Configure Sambee\n\nOpen **Settings** \u003e **Administration** \u003e **Authentication**.\n\n### 1. Choose the Sign-In Mode\n\nSelect one of these values in **Authentication mode**:\n\n- **OIDC or password**\n- **OIDC only**\n\nThe **Access** panel shows whether OIDC is configured and healthy. Select **Configure OIDC** to enter or change the provider settings.\n\n### 2. Enter Provider Details\n\nIn the setup dialog, complete these fields in the **Provider** section:\n\n| Sambee field | Value to enter |\n|---|---|\n| **Provider name** | A recognizable name for the provider, such as `Authelia` or `Microsoft Entra ID`. |\n| **Issuer URL** | The provider's HTTPS issuer URL. For Authelia, this is normally the externally reachable URL of the Authelia portal, such as `https://auth.example.com`. \u003cbr /\u003eOpen `https://auth.example.com/.well-known/openid-configuration` and enter the exact value of its `issuer` field. |\n| **Client ID** | The client ID configured in the OIDC IdP. |\n| **Client secret** | The matching client secret as plain text (unhashed).\u003cbr /\u003eOn later changes, leave this blank to retain the stored secret. \u003cbr /\u003eThe visibility button only reveals the value currently typed in the browser; Sambee never returns the stored secret. |\n| **Scopes** | A comma-separated list. Include `openid`, `offline_access`, and every scope required to return the claims configured below, such as `profile` and `email`. Add `groups` when using group admission or group-based role mappings. |\n\n### 3. Configure Session Policy\n\nSet **Interactive sign-in interval (days)** to control how long a verified IdP sign-in can be renewed in the background. The default is 30 days.\n\nDuring this interval, Sambee refreshes its short-lived API token in the background. At the interval deadline, Sambee requires a fresh interactive IdP sign-in.\n\n### 4. Configure Access\n\nComplete these fields in the **Access** section:\n\n| Sambee field | Value to enter |\n|---|---|\n| **Admission** | **All authenticated users** is the default. Select **Only selected groups** to require membership in named groups before Sambee evaluates the person's role. |\n| **Admission groups** | When **Admission** is **Only selected groups**, enter the exact identity-provider groups that may sign in, separated by commas. |\n\n### 5. Configure Role Assignment\n\nChoose how Sambee assigns roles after an identity passes the admission policy:\n\n| Role assignment | Behavior |\n|---|---|\n| **All users are assigned to the same role** | Select **Administrator**, **Editor** (default), or **Viewer**. Every admitted user receives that role unless they have an individual assignment. This is the simplest choice for smaller environments. |\n| **Group-based** | Enter exact identity-provider groups for **Administrator**, **Editor**, and **Viewer**. A person without an individual assignment must match a configured group; otherwise Sambee denies access. |\n\nIn group-based mode, a group can appear in only one role mapping. When a person matches multiple mappings, Sambee grants the highest role: Administrator, then Editor, then Viewer.\n\nDuring activation (see below), Sambee gives the administrator completing the test an individual **Administrator** assignment. Individual assignments for linked or pending accounts always take precedence over the configured role assignment.\n\n### 6. Advanced Claims\n\nThe default claim names work with most OpenID Connect providers. Expand **Advanced claims** only when the provider returns different claim names.\n\n#### Claims\n\n| Sambee field | Value to enter |\n|---|---|\n| **Username claim** | The stable, unique claim used to identify a person, commonly `preferred_username`. |\n| **Name claim** | Optional claim containing the person's display name, commonly `name`. |\n| **Email claim** | Optional claim containing the person's email address, commonly `email`. |\n| **Groups claim** | Optional claim containing group membership, commonly `groups`. Required only for selected-group admission or group-based role assignment. |\n\nSambee records the OIDC issuer and subject for each linked account. By default, Sambee also treats the configured IdP as authoritative for usernames: when an admitted IdP user has the same username as a local account, Sambee links that identity to the local account. This also updates an existing link when an IdP migration changes the issuer or subject. Keep **Automatically link OIDC identities to local accounts by username** enabled unless you need to resolve username matches manually.\n\n### 7. Connect and Test\n\nSelect **Connect and test** in the setup dialog. Sambee redirects you to the provider and returns to the dialog for review. This verifies that:\n\n- Signing in via the specified OIDC configuration succeeds.\n- Sambee can read and evaluate the resulting OIDC user identity.\n- The tested identity passes the selected admission rule, so the current administrator can keep administrator access after activation.\n\nReview the resulting identity before activation:\n\n- **Username**, **Email**, and **Groups** show the claims Sambee received.\n- **Admission** and **Matching admission group** show whether the tested identity passes the admission rule.\n\nOIDC activation remains unavailable unless the tested OIDC identity passes the admission rule to prevent the local admin making the changes from locking themselves out.\n\n### 8. Review and Activate\n\nSelect **Activate configuration** when the review is complete. The administrator who started the setup is linked to the tested provider identity automatically.\n\nWhen OIDC is active, users sign in normally after an IdP migration or subject reset. With automatic username linking enabled, Sambee updates their stored OIDC link during their next admitted sign-in and signs out existing Sambee sessions for that account. Until then, their existing OIDC link and IdP-managed full name and email remain read-only in User Management.\n\nAfter activation, see [OpenID Connect Authentication Operations](../openid-connect-authentication-operations/) for session, account-mapping, auditing, and request-limit administration.\n", "2.0": "+++\ntitle = \"OpenID Connect Authentication Setup\"\n+++\n\nOpenID Connect (OIDC) is Sambee's preferred authentication method.\n\n## Preparation\n\n### Copy OIDC Callback URI\n\nOpen **Settings** \u003e **Administration** \u003e **Authentication** and select an OIDC authentication mode. Select **Configure OIDC** and copy the OIDC callback URI from the dialog that opens. You need the URI in the next step. It has the following format:\n\n```text\nhttps://files.example.com/api/auth/oidc/callback\n```\n\n## Configure the OpenID Connect Identity Provider (IdP)\n\n### Provider Properties\n\nIn your identity provider, create a new OpenID Connect IdP with the following properties:\n\n- Confidential web client\n- Authorization code flow\n- PKCE with `S256`\n- `client_secret_basic` token endpoint authentication\n- `RS256`-signed ID tokens\n- Sambee's callback URI (see above)\n- Scopes:\n   - `openid`: required\n   - `profile`: often necessary for the provider to return `preferred_username`, which Sambee requires\n   - `email`: optional\n   - `groups`: required when using group admission or group-based role mappings\n   - `offline_access`: may be required for refresh tokens, depending on the provider\n- Authorization code grant\n- Refresh token grant: optional\n\n#### Token Lifetimes\n\nConfigure token lifetimes:\n\n- Refresh token, if the provider issues one:\n   - A shorter lifetime requires users to sign in again sooner.\n   - A longer lifetime increases the impact period if the token is compromised.\n   - Maximum useful length: slightly longer than Sambee's interactive sign-in interval (default: 30 days).\n- Access token and ID token:\n   - Lifetimes should be short, e.g., 1 hour.\n\n#### Refresh Tokens\n\nHaving the provider issue refresh tokens is recommended as that enables background session renewal without user interaction.\n\nProviders that don't issue refresh tokens can still be used with Sambee. They must return an ID token with a valid `auth_time` claim when Sambee requests `max_age`.\n\n### Verify the Username Claim\n\nSambee needs to match OIDC provider usernames to its own usernames. Many OIDC providers return a username in the field `preferred_username` when the `profile` scope is enabled. To ensure that username claim is suitable, verify the following with your OIDC provider:\n\n- How to enable returning the username claim (typically through the `profile` scope).\n- The field name of the username claim (typically `preferred_username`).\n- The username claim is present for every person who can sign in, stable for that person, and unique across all provider users.\n\n### Authelia Example\n\nThe relevant Authelia client entry can look like this:\n\n```yaml\nidentity_providers:\n  oidc:\n    lifespans:\n      custom:\n        sambee:\n          # Maximum useful length: Sambee's interactive sign-in interval + 1 day\n          refresh_token: '31d'\n    clients:\n      - client_id: sambee\n        client_name: Sambee\n        client_secret: '$pbkdf2-sha512$replace-with-a-hashed-random-secret'\n        redirect_uris:\n          - https://files.example.com/api/auth/oidc/callback\n        grant_types:\n          - authorization_code\n          - refresh_token\n        response_types:\n          - code\n        lifespan: sambee\n        scopes:\n          - openid\n          - profile\n          - email\n          - offline_access\n          # Add groups when using group admission or group-based role mappings.\n          - groups\n```\n\nNotes:\n\n- See Authelia's instructions for generating a [hashed client secret](https://www.authelia.com/integration/openid-connect/frequently-asked-questions/#how-do-i-generate-a-client-identifier-or-client-secret).\n- Use your own values for the following fields: `redirect_uris`.\n- The `profile` scope makes Authelia's `preferred_username` claim available from the username used to sign in, which is exactly what Sambee expects in its default OIDC settings (see below).\n- See the [Authelia documentation](https://www.authelia.com/configuration/identity-providers/openid-connect/clients/) more details and default values.\n\n## Configure Sambee\n\nOpen **Settings** \u003e **Administration** \u003e **Authentication**.\n\n### 1. Choose the Sign-In Mode\n\nSelect one of these values in **Authentication mode**:\n\n- **OIDC or password**\n- **OIDC only**\n\nThe **Access** panel shows whether OIDC is configured and healthy. Select **Configure OIDC** to enter or change the provider settings.\n\n### 2. Enter Provider Details\n\nIn the setup dialog, complete these fields in the **Provider** section:\n\n| Sambee field | Value to enter |\n|---|---|\n| **Provider name** | A recognizable name for the provider, such as `Authelia` or `Microsoft Entra ID`. |\n| **Issuer URL** | The provider's HTTPS issuer URL. For Authelia, this is normally the externally reachable URL of the Authelia portal, such as `https://auth.example.com`. \u003cbr /\u003eOpen `https://auth.example.com/.well-known/openid-configuration` and enter the exact value of its `issuer` field. |\n| **Client ID** | The client ID configured in the OIDC IdP. |\n| **Client secret** | The matching client secret as plain text (unhashed).\u003cbr /\u003eOn later changes, leave this blank to retain the stored secret. \u003cbr /\u003eThe visibility button only reveals the value currently typed in the browser; Sambee never returns the stored secret. |\n| **Scopes** | A comma-separated list. Include `openid` and every scope required for the configured claims, such as `profile` and `email`. Add `groups` for group admission or group-based role mappings. Add `offline_access` only if supported and needed for provider refresh tokens. |\n\n### 3. Configure Session Policy\n\nSet **Interactive sign-in interval (days)** to control the maximum age of a verified IdP sign-in. The default is 30 days.\n\nSet **Session limit without refresh token (hours)** separately for sign-ins that return no refresh token (default 8 hours; allowed range 1-24 hours).\n\nSambee issues short-lived API tokens (up to 60 minutes) while the browser session remains valid. With a refresh token, Sambee can renew through the IdP until the authentication-age limit. Without one, Sambee can issue another API token from the browser cookie only until the fixed session limit. Reducing that limit shortens existing no-refresh sessions; increasing it does not extend them. When the applicable deadline arrives, Sambee starts a new top-level IdP authorization, which might reuse the IdP's existing SSO session.\n\n### 4. Configure Access\n\nComplete these fields in the **Access** section:\n\n| Sambee field | Value to enter |\n|---|---|\n| **Admission** | **All authenticated users** is the default. Select **Only selected groups** to require membership in named groups before Sambee evaluates the person's role. |\n| **Admission groups** | When **Admission** is **Only selected groups**, enter the exact identity-provider groups that may sign in, separated by commas. |\n\n### 5. Configure Role Assignment\n\nChoose how Sambee assigns roles after an identity passes the admission policy:\n\n| Role assignment | Behavior |\n|---|---|\n| **All users are assigned to the same role** | Select **Administrator**, **Editor** (default), or **Viewer**. Every admitted user receives that role unless they have an individual assignment. This is the simplest choice for smaller environments. |\n| **Group-based** | Enter exact identity-provider groups for **Administrator**, **Editor**, and **Viewer**. A person without an individual assignment must match a configured group; otherwise Sambee denies access. |\n\nIn group-based mode, a group can appear in only one role mapping. When a person matches multiple mappings, Sambee grants the highest role: Administrator, then Editor, then Viewer.\n\nDuring activation (see below), Sambee gives the administrator completing the test an individual **Administrator** assignment. Individual assignments for linked or pending accounts always take precedence over the configured role assignment.\n\n### 6. Advanced Claims\n\nThe default claim names work with most OpenID Connect providers. Expand **Advanced claims** only when the provider returns different claim names.\n\n#### Claims\n\n| Sambee field | Value to enter |\n|---|---|\n| **Username claim** | The stable, unique claim used to identify a person, commonly `preferred_username`. |\n| **Name claim** | Optional claim containing the person's display name, commonly `name`. |\n| **Email claim** | Optional claim containing the person's email address, commonly `email`. |\n| **Groups claim** | Optional claim containing group membership, commonly `groups`. Required only for selected-group admission or group-based role assignment. |\n\nSambee records the OIDC issuer and subject for each linked account. By default, Sambee also treats the configured IdP as authoritative for usernames: when an admitted IdP user has the same username as a local account, Sambee links that identity to the local account. This also updates an existing link when an IdP migration changes the issuer or subject. Keep **Automatically link OIDC identities to local accounts by username** enabled unless you need to resolve username matches manually.\n\n### 7. Connect and Test\n\nSelect **Connect and test** in the setup dialog. Sambee redirects you to the provider and returns to the dialog for review. This verifies that:\n\n- Signing in via the specified OIDC configuration succeeds.\n- Sambee can read and evaluate the resulting OIDC user identity.\n- The tested identity passes the selected admission rule, so the current administrator can keep administrator access after activation.\n\nReview the resulting identity before activation:\n\n- **Username**, **Email**, and **Groups** show the claims Sambee received.\n- **Admission** and **Matching admission group** show whether the tested identity passes the admission rule.\n- **Session renewal** reports whether this particular test returned a refresh token. A test without one can still succeed; users will need to sign in again after the configured no-refresh session limit.\n\nOIDC activation remains unavailable unless the tested OIDC identity passes the admission rule to prevent the local admin making the changes from locking themselves out.\n\n### 8. Review and Activate\n\nSelect **Activate configuration** when the review is complete. The administrator who started the setup is linked to the tested provider identity automatically.\n\nWhen OIDC is active, users sign in normally after an IdP migration or subject reset. With automatic username linking enabled, Sambee updates their stored OIDC link during their next admitted sign-in and signs out existing Sambee sessions for that account. Until then, their existing OIDC link and IdP-managed full name and email remain read-only in User Management.\n\nAfter activation, see [OpenID Connect Authentication Operations](../openid-connect-authentication-operations/) for session, account-mapping, auditing, and request-limit administration.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:admin-guide/authentication/openid-connect-authentication-operations", "parent_id": "section:admin-guide/authentication", "depth": 2, "kind": "page", "label": "openid-connect-authentication-operations", "title": "Openid Connect Authentication Operations", "path": "admin-guide/authentication/openid-connect-authentication-operations", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "authored"}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "branched", "source_version": "0.9", "diff_added": 25, "diff_removed": 4}}, "content_versions": {"0.9": "+++\ntitle = \"OpenID Connect Authentication Operations\"\n+++\n\nUse this guide to manage OIDC sessions, account mappings, and audit records after completing [OpenID Connect Authentication Setup](../openid-connect-authentication-setup/).\n\n## Session Lifecycle\n\nFor each OIDC browser session, Sambee stores the provider refresh token encrypted on the server. The browser holds only a short-lived API token in memory and an `HttpOnly` session cookie. Reloading the page can obtain a new API token from that cookie without exposing the provider refresh token to browser storage, URLs, logs, or API responses.\n\nSambee renews the API token in the background until the configured interactive sign-in interval ends. Refreshing does not extend the original verified sign-in time.\n\nAn interactive sign-in is required when the interval ends, the identity provider rejects or revokes the refresh token, a refresh result is uncertain, an access policy changes, or the browser session is revoked. Sambee returns the user to the same safe route after sign-in. See [Recover Unsaved In-Browser Edits](../../../user-guide/viewing-and-editing-files/recover-unsaved-edits/) for the editing behavior during required sign-in.\n\n## Manage OIDC Sessions\n\nUsers can open **Settings** \u003e **Account** to review their current session and other active OIDC browser sessions. The page separates **This browser** from **Other sessions**. For a local password sign-in, the current entry is not a persistent server-side browser session. For an OIDC sign-in, Sambee shows when each session was created and last active. Newly created OIDC sessions can also show a coarse browser and operating-system label without exposing a device fingerprint or token details. Existing sessions might not have a label. See [Manage Your Account](../../../user-guide/getting-started/manage-your-account/) for the user-facing controls.\n\n- Select **Sign out** next to the current browser to revoke its session and return to the sign-in page.\n- Select **Revoke** to end another browser session.\n\nRevocation immediately invalidates API tokens issued for the affected browser sessions. It does not sign the user out of the identity provider itself.\n\n## Manage Account Mappings\n\nOpen **Settings** \u003e **Administration** \u003e **Users** to review how each local account authenticates. An account can show **Local password**, **OIDC linked**, or both. Established mappings show the provider name and most recent OIDC sign-in. With automatic username linking enabled, an admitted IdP user with the same username automatically links to that local account or updates its existing OIDC link. A pending mapping shows the provider username that must complete the first admitted OIDC sign-in, who created the mapping, and when.\n\nIn **OIDC only** mode, Sambee creates a passwordless account automatically when an admitted identity signs in for the first time. User Management does not offer manual user creation or local-password resets in this mode. Existing accounts can still be reviewed and mapped when an administrator needs to resolve an identity collision or apply an individual OIDC role before the first sign-in.\n\n### Assign Individual Roles\n\nFor a linked or pending account, set **OIDC role assignment** to **Administrator**, **Editor**, or **Viewer** to create an individual override. Select **Use configured role assignment** to apply the provider's uniform or group-based policy instead. Individual assignments take precedence over the configured policy and work without a groups claim unless selected-group admission requires one.\n\n### Change Mappings\n\nAdministrators can map an unlinked local account to an expected provider username, cancel a pending mapping, or change a linked account to a different provider username. Changing a linked username removes the established identity and creates a pending mapping.\n\nUse **Advanced OIDC actions** to view the stored identity properties, including issuer, subject, last-seen provider username, and verified group snapshot. You can also move an established identity to another active, unlinked local account or detach it from a local account. Changing, moving, or detaching an established identity revokes affected Sambee sessions. Detaching does not revoke access at the identity provider; remove provider admission separately when the person must no longer sign in.\n\nMapping updates are atomic and revision checked. If another administrator changes mappings while the page is open, Sambee rejects the stale update; reload the users page and review the current state. In **OIDC only** mode, Sambee prevents removal of the last active OIDC administrator mapping.\n\nDeleting a local user also removes their established identity, pending mappings targeting that user, and incomplete OIDC flows in the same transaction. Pending mappings that the deleted user created for other accounts remain active and show **Deleted user** as their creator. Deletion remains subject to the last-administrator guard.\n\n## Audit Events\n\nOIDC configuration and identity events are stored in the Sambee database. They do not contain raw subjects, provider tokens, client secrets, authorization codes, nonces, verifiers, or one-time login grants. Events are retained until the database is removed or an external retention process deletes them.\n\nExport the complete audit stream as JSON Lines:\n\n```bash\ncd backend\npython -m app.oidc_admin export-audit --output sambee-audit.jsonl\n```\n\n## Authentication Request Limits\n\nSambee enforces authentication limits in the application. A reverse proxy can add stricter limits but does not replace these defaults:\n\n| Request | Default limit |\n|---|---|\n| Start OIDC authorization | 20 requests per source IP per 5 minutes |\n| Process OIDC callback | 60 requests per source IP per 5 minutes |\n| Exchange OIDC login grant | 30 requests per source IP per 5 minutes |\n| Password sign-in | 10 attempts per source IP per 5 minutes and 10 attempts per submitted username per 15 minutes |\n\nLimits refill continuously. A rejected API request returns `Retry-After`; browser-based OIDC requests return to the sign-in page with a generic retry message. Password forms larger than 64 KiB are rejected before parsing. These responses do not expose account existence, the active sign-in mode, provider payloads, or submitted credentials.\n\n", "1.0": "+++\ntitle = \"OpenID Connect Authentication Operations\"\n+++\n\nUse this guide to manage OIDC sessions, account mappings, and audit records after completing [OpenID Connect Authentication Setup](../openid-connect-authentication-setup/).\n\n## Session Lifecycle\n\nFor each OIDC browser session, Sambee stores the provider refresh token encrypted on the server. The browser holds only a short-lived API token in memory and an `HttpOnly` session cookie. Reloading the page can obtain a new API token from that cookie without exposing the provider refresh token to browser storage, URLs, logs, or API responses.\n\nSambee renews the API token in the background until the configured interactive sign-in interval ends. Refreshing does not extend the original verified sign-in time.\n\nAn interactive sign-in is required when the interval ends, the identity provider rejects or revokes the refresh token, a refresh result is uncertain, an access policy changes, or the browser session is revoked. Sambee returns the user to the same safe route after sign-in. See [Recover Unsaved In-Browser Edits](../../../user-guide/viewing-and-editing-files/recover-unsaved-edits/) for the editing behavior during required sign-in.\n\n## Manage OIDC Sessions\n\nUsers can open **Settings** \u003e **Account** to review their current session and other active OIDC browser sessions. The page separates **This browser** from **Other sessions**. For a local password sign-in, the current entry is not a persistent server-side browser session. For an OIDC sign-in, Sambee shows when each session was created and last active. Newly created OIDC sessions can also show a coarse browser and operating-system label without exposing a device fingerprint or token details. Existing sessions might not have a label. See [Manage Your Account](../../../user-guide/getting-started/manage-your-account/) for the user-facing controls.\n\n- Select **Sign out** next to the current browser to revoke its session and return to the sign-in page.\n- Select **Revoke** to end another browser session.\n\nRevocation immediately invalidates API tokens issued for the affected browser sessions. It does not sign the user out of the identity provider itself.\n\n## Manage Account Mappings\n\nOpen **Settings** \u003e **Administration** \u003e **Users** to review how each local account authenticates. An account can show **Local password**, **OIDC linked**, or both. Established mappings show the provider name and most recent OIDC sign-in. With automatic username linking enabled, an admitted IdP user with the same username automatically links to that local account or updates its existing OIDC link. A pending mapping shows the provider username that must complete the first admitted OIDC sign-in, who created the mapping, and when.\n\nIn **OIDC only** mode, Sambee creates a passwordless account automatically when an admitted identity signs in for the first time. User Management does not offer manual user creation or local-password resets in this mode. Existing accounts can still be reviewed and mapped when an administrator needs to resolve an identity collision or apply an individual OIDC role before the first sign-in.\n\n### Assign Individual Roles\n\nFor a linked or pending account, set **OIDC role assignment** to **Administrator**, **Editor**, or **Viewer** to create an individual override. Select **Use configured role assignment** to apply the provider's uniform or group-based policy instead. Individual assignments take precedence over the configured policy and work without a groups claim unless selected-group admission requires one.\n\n### Change Mappings\n\nAdministrators can map an unlinked local account to an expected provider username, cancel a pending mapping, or change a linked account to a different provider username. Changing a linked username removes the established identity and creates a pending mapping.\n\nUse **Advanced OIDC actions** to view the stored identity properties, including issuer, subject, last-seen provider username, and verified group snapshot. You can also move an established identity to another active, unlinked local account or detach it from a local account. Changing, moving, or detaching an established identity revokes affected Sambee sessions. Detaching does not revoke access at the identity provider; remove provider admission separately when the person must no longer sign in.\n\nMapping updates are atomic and revision checked. If another administrator changes mappings while the page is open, Sambee rejects the stale update; reload the users page and review the current state. In **OIDC only** mode, Sambee prevents removal of the last active OIDC administrator mapping.\n\nDeleting a local user also removes their established identity, pending mappings targeting that user, and incomplete OIDC flows in the same transaction. Pending mappings that the deleted user created for other accounts remain active and show **Deleted user** as their creator. Deletion remains subject to the last-administrator guard.\n\n## Audit Events\n\nOIDC configuration and identity events are stored in the Sambee database. They do not contain raw subjects, provider tokens, client secrets, authorization codes, nonces, verifiers, or one-time login grants. Events are retained until the database is removed or an external retention process deletes them.\n\nExport the complete audit stream as JSON Lines:\n\n```bash\ncd backend\npython -m app.oidc_admin export-audit --output sambee-audit.jsonl\n```\n\n## Authentication Request Limits\n\nSambee enforces authentication limits in the application. A reverse proxy can add stricter limits but does not replace these defaults:\n\n| Request | Default limit |\n|---|---|\n| Start OIDC authorization | 20 requests per source IP per 5 minutes |\n| Process OIDC callback | 60 requests per source IP per 5 minutes |\n| Exchange OIDC login grant | 30 requests per source IP per 5 minutes |\n| Password sign-in | 10 attempts per source IP per 5 minutes and 10 attempts per submitted username per 15 minutes |\n\nLimits refill continuously. A rejected API request returns `Retry-After`; browser-based OIDC requests return to the sign-in page with a generic retry message. Password forms larger than 64 KiB are rejected before parsing. These responses do not expose account existence, the active sign-in mode, provider payloads, or submitted credentials.\n\n", "2.0": "+++\ntitle = \"OpenID Connect Authentication Operations\"\n+++\n\nUse this guide to manage OIDC sessions, account mappings, and audit records after completing [OpenID Connect Authentication Setup](../openid-connect-authentication-setup/).\n\n## Session Lifecycle\n\nWhen a provider returns a refresh token, Sambee stores it encrypted on the server. If the provider returns none, Sambee stores no provider token. In both cases, the browser holds only a short-lived API token in memory and an `HttpOnly` session cookie. Reloading the page can obtain a new API token from that cookie without exposing provider tokens to browser storage, URLs, logs, or API responses.\n\nSambee renews the API token in the background while the session remains valid. A session with a refresh token is limited by the configured interactive sign-in interval (default 30 days from the verified IdP authentication). A session without a refresh token has a fixed limit of 8 hours from the callback by default, configurable from 1 to 24 hours. Neither local activity nor API-token renewal extends that deadline; the earlier applicable deadline always wins. Reducing the no-refresh limit permanently shortens existing sessions, including pending sign-ins.\n\nA new top-level authorization is required when the applicable deadline ends, the identity provider rejects or revokes a refresh token, a refresh result is uncertain, an access policy changes, or the browser session is revoked. The IdP might use its SSO cookie to return quickly, but this is not guaranteed. Sambee returns the user to the same safe route after sign-in. Registered text and Markdown drafts are snapshotted before an authentication redirect when storage is available; other unsaved work might be interrupted. See [Recover Unsaved In-Browser Edits](../../../user-guide/viewing-and-editing-files/recover-unsaved-edits/) for limitations and recovery behavior.\n\n## Manage OIDC Sessions\n\nUsers can open **Settings** \u003e **Account** to review their current session and other active OIDC browser sessions. The page separates **This browser** from **Other sessions**. For a local password sign-in, the current entry is not a persistent server-side browser session. For an OIDC sign-in, Sambee shows when each session was created and last active. Newly created OIDC sessions can also show a coarse browser and operating-system label without exposing a device fingerprint or token details. Existing sessions might not have a label. See [Manage Your Account](../../../user-guide/getting-started/manage-your-account/) for the user-facing controls.\n\n- Select **Sign out** next to the current browser to revoke its session and return to the sign-in page.\n- Select **Revoke** to end another browser session.\n\nRevocation immediately invalidates API tokens issued for the affected browser sessions. It does not sign the user out of the identity provider itself.\n\n## Manage Account Mappings\n\nOpen **Settings** \u003e **Administration** \u003e **Users** to review how each local account authenticates. An account can show **Local password**, **OIDC linked**, or both. Established mappings show the provider name and most recent OIDC sign-in. With automatic username linking enabled, an admitted IdP user with the same username automatically links to that local account or updates its existing OIDC link. A pending mapping shows the provider username that must complete the first admitted OIDC sign-in, who created the mapping, and when.\n\nIn **OIDC only** mode, Sambee creates a passwordless account automatically when an admitted identity signs in for the first time. User Management does not offer manual user creation or local-password resets in this mode. Existing accounts can still be reviewed and mapped when an administrator needs to resolve an identity collision or apply an individual OIDC role before the first sign-in.\n\n### Assign Individual Roles\n\nFor a linked or pending account, set **OIDC role assignment** to **Administrator**, **Editor**, or **Viewer** to create an individual override. Select **Use configured role assignment** to apply the provider's uniform or group-based policy instead. Individual assignments take precedence over the configured policy and work without a groups claim unless selected-group admission requires one.\n\n### Change Mappings\n\nAdministrators can map an unlinked local account to an expected provider username, cancel a pending mapping, or change a linked account to a different provider username. Changing a linked username removes the established identity and creates a pending mapping.\n\nUse **Advanced OIDC actions** to view the stored identity properties, including issuer, subject, last-seen provider username, and verified group snapshot. You can also move an established identity to another active, unlinked local account or detach it from a local account. Changing, moving, or detaching an established identity revokes affected Sambee sessions. Detaching does not revoke access at the identity provider; remove provider admission separately when the person must no longer sign in.\n\nMapping updates are atomic and revision checked. If another administrator changes mappings while the page is open, Sambee rejects the stale update; reload the users page and review the current state. In **OIDC only** mode, Sambee prevents removal of the last active OIDC administrator mapping.\n\nDeleting a local user also removes their established identity, pending mappings targeting that user, and incomplete OIDC flows in the same transaction. Pending mappings that the deleted user created for other accounts remain active and show **Deleted user** as their creator. Deletion remains subject to the last-administrator guard.\n\n## Local Username Matching And Upgrade Conflicts\n\nLocal-password sign-in matches usernames without regard to capitalization, using Unicode case folding and ignoring leading and trailing whitespace. Stored spelling is preserved. Passwords remain case-sensitive. New accounts and renamed accounts can't introduce case-insensitive duplicates, including accounts created through OIDC.\n\nUpgrades complete automatically even if existing accounts have conflicting names, such as `UserA` and `usera`. Accounts, passwords, roles, ownership, and identity links are preserved. Each conflicting account continues to accept only its exact stored username spelling; other capitalizations are rejected without choosing an account by its password. Disabled, expired, and passwordless accounts also count toward a conflict.\n\n**Settings** \u003e **Administration** \u003e **Users** lists conflicts in a warning, regardless of directory filters or pagination. Resolve a conflict by renaming an account through its normal editor, or deleting an account that's no longer needed. Deleting an account remains subject to the normal deletion consequences and administrator safeguards. Unchanged usernames and case-only renames remain available while resolving existing conflicts. Once only one account has a comparison key, case-insensitive password sign-in applies automatically, without restarting or rerunning a migration.\n\nOIDC identity matching and automatic linking still require the exact username spelling. A case-only match doesn't automatically link an identity or create another account; resolve that collision through the existing identity-mapping controls.\n\n## Require A Local Password Change\n\nWhen creating a local user or resetting an existing local password, enable **Require change on next password sign-in** to require a new password before the user can continue. The user directory shows **Pwd change req'd** while this requirement is pending.\n\nAfter signing in with the temporary or existing local password, the user must enter that password, choose a different password, and confirm it. They can sign out instead, but can't browse files, use administration settings, or issue companion credentials until the change succeeds. Successful changes invalidate existing Sambee tokens and require another sign-in.\n\nThe requirement applies only to local-password sessions. A linked user can still sign in through OIDC; that doesn't clear the local-password requirement or change the identity provider's password. Passwordless OIDC accounts have no local password to reset. In **OIDC only** mode, local password changes are unavailable.\n\nExisting password-change flags are enforced after upgrading. They aren't cleared automatically. If a user can't complete the change, an administrator can set another local password through User Management. Switch the requirement off during that reset only when the replacement password is intended to be permanent. Authentication-disabled mode doesn't enforce the change workflow.\n\n## Audit Events\n\nOIDC configuration, identity events, and successful local password changes and resets are stored in the Sambee database. They do not contain passwords, raw subjects, provider tokens, client secrets, authorization codes, nonces, verifiers, or one-time login grants. Events are retained until the database is removed or an external retention process deletes them.\n\nExport the complete audit stream as JSON Lines:\n\n```bash\ncd backend\npython -m app.oidc_admin export-audit --output sambee-audit.jsonl\n```\n\n## Authentication Request Limits\n\nSambee enforces authentication limits in the application. A reverse proxy can add stricter limits but does not replace these defaults:\n\n| Request | Default limit |\n|---|---|\n| Start OIDC authorization | 20 requests per source IP per 5 minutes |\n| Process OIDC callback | 60 requests per source IP per 5 minutes |\n| Exchange OIDC login grant | 30 requests per source IP per 5 minutes |\n| Password sign-in | 10 attempts per source IP per 5 minutes and 10 attempts per submitted username per 15 minutes |\n\nLimits refill continuously. A rejected API request returns `Retry-After`; browser-based OIDC requests return to the sign-in page with a generic retry message. Password forms larger than 64 KiB are rejected before parsing. These responses do not expose account existence, the active sign-in mode, provider payloads, or submitted credentials.\n\nAll capitalization and Unicode case-folding variants of a username share the same username-based password limit, including legacy conflicting accounts.\n"}, "page_contents": {"0.9": "+++\ntitle = \"OpenID Connect Authentication Operations\"\n+++\n\nUse this guide to manage OIDC sessions, account mappings, and audit records after completing [OpenID Connect Authentication Setup](../openid-connect-authentication-setup/).\n\n## Session Lifecycle\n\nFor each OIDC browser session, Sambee stores the provider refresh token encrypted on the server. The browser holds only a short-lived API token in memory and an `HttpOnly` session cookie. Reloading the page can obtain a new API token from that cookie without exposing the provider refresh token to browser storage, URLs, logs, or API responses.\n\nSambee renews the API token in the background until the configured interactive sign-in interval ends. Refreshing does not extend the original verified sign-in time.\n\nAn interactive sign-in is required when the interval ends, the identity provider rejects or revokes the refresh token, a refresh result is uncertain, an access policy changes, or the browser session is revoked. Sambee returns the user to the same safe route after sign-in. See [Recover Unsaved In-Browser Edits](../../../user-guide/viewing-and-editing-files/recover-unsaved-edits/) for the editing behavior during required sign-in.\n\n## Manage OIDC Sessions\n\nUsers can open **Settings** \u003e **Account** to review their current session and other active OIDC browser sessions. The page separates **This browser** from **Other sessions**. For a local password sign-in, the current entry is not a persistent server-side browser session. For an OIDC sign-in, Sambee shows when each session was created and last active. Newly created OIDC sessions can also show a coarse browser and operating-system label without exposing a device fingerprint or token details. Existing sessions might not have a label. See [Manage Your Account](../../../user-guide/getting-started/manage-your-account/) for the user-facing controls.\n\n- Select **Sign out** next to the current browser to revoke its session and return to the sign-in page.\n- Select **Revoke** to end another browser session.\n\nRevocation immediately invalidates API tokens issued for the affected browser sessions. It does not sign the user out of the identity provider itself.\n\n## Manage Account Mappings\n\nOpen **Settings** \u003e **Administration** \u003e **Users** to review how each local account authenticates. An account can show **Local password**, **OIDC linked**, or both. Established mappings show the provider name and most recent OIDC sign-in. With automatic username linking enabled, an admitted IdP user with the same username automatically links to that local account or updates its existing OIDC link. A pending mapping shows the provider username that must complete the first admitted OIDC sign-in, who created the mapping, and when.\n\nIn **OIDC only** mode, Sambee creates a passwordless account automatically when an admitted identity signs in for the first time. User Management does not offer manual user creation or local-password resets in this mode. Existing accounts can still be reviewed and mapped when an administrator needs to resolve an identity collision or apply an individual OIDC role before the first sign-in.\n\n### Assign Individual Roles\n\nFor a linked or pending account, set **OIDC role assignment** to **Administrator**, **Editor**, or **Viewer** to create an individual override. Select **Use configured role assignment** to apply the provider's uniform or group-based policy instead. Individual assignments take precedence over the configured policy and work without a groups claim unless selected-group admission requires one.\n\n### Change Mappings\n\nAdministrators can map an unlinked local account to an expected provider username, cancel a pending mapping, or change a linked account to a different provider username. Changing a linked username removes the established identity and creates a pending mapping.\n\nUse **Advanced OIDC actions** to view the stored identity properties, including issuer, subject, last-seen provider username, and verified group snapshot. You can also move an established identity to another active, unlinked local account or detach it from a local account. Changing, moving, or detaching an established identity revokes affected Sambee sessions. Detaching does not revoke access at the identity provider; remove provider admission separately when the person must no longer sign in.\n\nMapping updates are atomic and revision checked. If another administrator changes mappings while the page is open, Sambee rejects the stale update; reload the users page and review the current state. In **OIDC only** mode, Sambee prevents removal of the last active OIDC administrator mapping.\n\nDeleting a local user also removes their established identity, pending mappings targeting that user, and incomplete OIDC flows in the same transaction. Pending mappings that the deleted user created for other accounts remain active and show **Deleted user** as their creator. Deletion remains subject to the last-administrator guard.\n\n## Audit Events\n\nOIDC configuration and identity events are stored in the Sambee database. They do not contain raw subjects, provider tokens, client secrets, authorization codes, nonces, verifiers, or one-time login grants. Events are retained until the database is removed or an external retention process deletes them.\n\nExport the complete audit stream as JSON Lines:\n\n```bash\ncd backend\npython -m app.oidc_admin export-audit --output sambee-audit.jsonl\n```\n\n## Authentication Request Limits\n\nSambee enforces authentication limits in the application. A reverse proxy can add stricter limits but does not replace these defaults:\n\n| Request | Default limit |\n|---|---|\n| Start OIDC authorization | 20 requests per source IP per 5 minutes |\n| Process OIDC callback | 60 requests per source IP per 5 minutes |\n| Exchange OIDC login grant | 30 requests per source IP per 5 minutes |\n| Password sign-in | 10 attempts per source IP per 5 minutes and 10 attempts per submitted username per 15 minutes |\n\nLimits refill continuously. A rejected API request returns `Retry-After`; browser-based OIDC requests return to the sign-in page with a generic retry message. Password forms larger than 64 KiB are rejected before parsing. These responses do not expose account existence, the active sign-in mode, provider payloads, or submitted credentials.\n\n", "1.0": "+++\ntitle = \"OpenID Connect Authentication Operations\"\n+++\n\nUse this guide to manage OIDC sessions, account mappings, and audit records after completing [OpenID Connect Authentication Setup](../openid-connect-authentication-setup/).\n\n## Session Lifecycle\n\nFor each OIDC browser session, Sambee stores the provider refresh token encrypted on the server. The browser holds only a short-lived API token in memory and an `HttpOnly` session cookie. Reloading the page can obtain a new API token from that cookie without exposing the provider refresh token to browser storage, URLs, logs, or API responses.\n\nSambee renews the API token in the background until the configured interactive sign-in interval ends. Refreshing does not extend the original verified sign-in time.\n\nAn interactive sign-in is required when the interval ends, the identity provider rejects or revokes the refresh token, a refresh result is uncertain, an access policy changes, or the browser session is revoked. Sambee returns the user to the same safe route after sign-in. See [Recover Unsaved In-Browser Edits](../../../user-guide/viewing-and-editing-files/recover-unsaved-edits/) for the editing behavior during required sign-in.\n\n## Manage OIDC Sessions\n\nUsers can open **Settings** \u003e **Account** to review their current session and other active OIDC browser sessions. The page separates **This browser** from **Other sessions**. For a local password sign-in, the current entry is not a persistent server-side browser session. For an OIDC sign-in, Sambee shows when each session was created and last active. Newly created OIDC sessions can also show a coarse browser and operating-system label without exposing a device fingerprint or token details. Existing sessions might not have a label. See [Manage Your Account](../../../user-guide/getting-started/manage-your-account/) for the user-facing controls.\n\n- Select **Sign out** next to the current browser to revoke its session and return to the sign-in page.\n- Select **Revoke** to end another browser session.\n\nRevocation immediately invalidates API tokens issued for the affected browser sessions. It does not sign the user out of the identity provider itself.\n\n## Manage Account Mappings\n\nOpen **Settings** \u003e **Administration** \u003e **Users** to review how each local account authenticates. An account can show **Local password**, **OIDC linked**, or both. Established mappings show the provider name and most recent OIDC sign-in. With automatic username linking enabled, an admitted IdP user with the same username automatically links to that local account or updates its existing OIDC link. A pending mapping shows the provider username that must complete the first admitted OIDC sign-in, who created the mapping, and when.\n\nIn **OIDC only** mode, Sambee creates a passwordless account automatically when an admitted identity signs in for the first time. User Management does not offer manual user creation or local-password resets in this mode. Existing accounts can still be reviewed and mapped when an administrator needs to resolve an identity collision or apply an individual OIDC role before the first sign-in.\n\n### Assign Individual Roles\n\nFor a linked or pending account, set **OIDC role assignment** to **Administrator**, **Editor**, or **Viewer** to create an individual override. Select **Use configured role assignment** to apply the provider's uniform or group-based policy instead. Individual assignments take precedence over the configured policy and work without a groups claim unless selected-group admission requires one.\n\n### Change Mappings\n\nAdministrators can map an unlinked local account to an expected provider username, cancel a pending mapping, or change a linked account to a different provider username. Changing a linked username removes the established identity and creates a pending mapping.\n\nUse **Advanced OIDC actions** to view the stored identity properties, including issuer, subject, last-seen provider username, and verified group snapshot. You can also move an established identity to another active, unlinked local account or detach it from a local account. Changing, moving, or detaching an established identity revokes affected Sambee sessions. Detaching does not revoke access at the identity provider; remove provider admission separately when the person must no longer sign in.\n\nMapping updates are atomic and revision checked. If another administrator changes mappings while the page is open, Sambee rejects the stale update; reload the users page and review the current state. In **OIDC only** mode, Sambee prevents removal of the last active OIDC administrator mapping.\n\nDeleting a local user also removes their established identity, pending mappings targeting that user, and incomplete OIDC flows in the same transaction. Pending mappings that the deleted user created for other accounts remain active and show **Deleted user** as their creator. Deletion remains subject to the last-administrator guard.\n\n## Audit Events\n\nOIDC configuration and identity events are stored in the Sambee database. They do not contain raw subjects, provider tokens, client secrets, authorization codes, nonces, verifiers, or one-time login grants. Events are retained until the database is removed or an external retention process deletes them.\n\nExport the complete audit stream as JSON Lines:\n\n```bash\ncd backend\npython -m app.oidc_admin export-audit --output sambee-audit.jsonl\n```\n\n## Authentication Request Limits\n\nSambee enforces authentication limits in the application. A reverse proxy can add stricter limits but does not replace these defaults:\n\n| Request | Default limit |\n|---|---|\n| Start OIDC authorization | 20 requests per source IP per 5 minutes |\n| Process OIDC callback | 60 requests per source IP per 5 minutes |\n| Exchange OIDC login grant | 30 requests per source IP per 5 minutes |\n| Password sign-in | 10 attempts per source IP per 5 minutes and 10 attempts per submitted username per 15 minutes |\n\nLimits refill continuously. A rejected API request returns `Retry-After`; browser-based OIDC requests return to the sign-in page with a generic retry message. Password forms larger than 64 KiB are rejected before parsing. These responses do not expose account existence, the active sign-in mode, provider payloads, or submitted credentials.\n\n", "2.0": "+++\ntitle = \"OpenID Connect Authentication Operations\"\n+++\n\nUse this guide to manage OIDC sessions, account mappings, and audit records after completing [OpenID Connect Authentication Setup](../openid-connect-authentication-setup/).\n\n## Session Lifecycle\n\nWhen a provider returns a refresh token, Sambee stores it encrypted on the server. If the provider returns none, Sambee stores no provider token. In both cases, the browser holds only a short-lived API token in memory and an `HttpOnly` session cookie. Reloading the page can obtain a new API token from that cookie without exposing provider tokens to browser storage, URLs, logs, or API responses.\n\nSambee renews the API token in the background while the session remains valid. A session with a refresh token is limited by the configured interactive sign-in interval (default 30 days from the verified IdP authentication). A session without a refresh token has a fixed limit of 8 hours from the callback by default, configurable from 1 to 24 hours. Neither local activity nor API-token renewal extends that deadline; the earlier applicable deadline always wins. Reducing the no-refresh limit permanently shortens existing sessions, including pending sign-ins.\n\nA new top-level authorization is required when the applicable deadline ends, the identity provider rejects or revokes a refresh token, a refresh result is uncertain, an access policy changes, or the browser session is revoked. The IdP might use its SSO cookie to return quickly, but this is not guaranteed. Sambee returns the user to the same safe route after sign-in. Registered text and Markdown drafts are snapshotted before an authentication redirect when storage is available; other unsaved work might be interrupted. See [Recover Unsaved In-Browser Edits](../../../user-guide/viewing-and-editing-files/recover-unsaved-edits/) for limitations and recovery behavior.\n\n## Manage OIDC Sessions\n\nUsers can open **Settings** \u003e **Account** to review their current session and other active OIDC browser sessions. The page separates **This browser** from **Other sessions**. For a local password sign-in, the current entry is not a persistent server-side browser session. For an OIDC sign-in, Sambee shows when each session was created and last active. Newly created OIDC sessions can also show a coarse browser and operating-system label without exposing a device fingerprint or token details. Existing sessions might not have a label. See [Manage Your Account](../../../user-guide/getting-started/manage-your-account/) for the user-facing controls.\n\n- Select **Sign out** next to the current browser to revoke its session and return to the sign-in page.\n- Select **Revoke** to end another browser session.\n\nRevocation immediately invalidates API tokens issued for the affected browser sessions. It does not sign the user out of the identity provider itself.\n\n## Manage Account Mappings\n\nOpen **Settings** \u003e **Administration** \u003e **Users** to review how each local account authenticates. An account can show **Local password**, **OIDC linked**, or both. Established mappings show the provider name and most recent OIDC sign-in. With automatic username linking enabled, an admitted IdP user with the same username automatically links to that local account or updates its existing OIDC link. A pending mapping shows the provider username that must complete the first admitted OIDC sign-in, who created the mapping, and when.\n\nIn **OIDC only** mode, Sambee creates a passwordless account automatically when an admitted identity signs in for the first time. User Management does not offer manual user creation or local-password resets in this mode. Existing accounts can still be reviewed and mapped when an administrator needs to resolve an identity collision or apply an individual OIDC role before the first sign-in.\n\n### Assign Individual Roles\n\nFor a linked or pending account, set **OIDC role assignment** to **Administrator**, **Editor**, or **Viewer** to create an individual override. Select **Use configured role assignment** to apply the provider's uniform or group-based policy instead. Individual assignments take precedence over the configured policy and work without a groups claim unless selected-group admission requires one.\n\n### Change Mappings\n\nAdministrators can map an unlinked local account to an expected provider username, cancel a pending mapping, or change a linked account to a different provider username. Changing a linked username removes the established identity and creates a pending mapping.\n\nUse **Advanced OIDC actions** to view the stored identity properties, including issuer, subject, last-seen provider username, and verified group snapshot. You can also move an established identity to another active, unlinked local account or detach it from a local account. Changing, moving, or detaching an established identity revokes affected Sambee sessions. Detaching does not revoke access at the identity provider; remove provider admission separately when the person must no longer sign in.\n\nMapping updates are atomic and revision checked. If another administrator changes mappings while the page is open, Sambee rejects the stale update; reload the users page and review the current state. In **OIDC only** mode, Sambee prevents removal of the last active OIDC administrator mapping.\n\nDeleting a local user also removes their established identity, pending mappings targeting that user, and incomplete OIDC flows in the same transaction. Pending mappings that the deleted user created for other accounts remain active and show **Deleted user** as their creator. Deletion remains subject to the last-administrator guard.\n\n## Local Username Matching And Upgrade Conflicts\n\nLocal-password sign-in matches usernames without regard to capitalization, using Unicode case folding and ignoring leading and trailing whitespace. Stored spelling is preserved. Passwords remain case-sensitive. New accounts and renamed accounts can't introduce case-insensitive duplicates, including accounts created through OIDC.\n\nUpgrades complete automatically even if existing accounts have conflicting names, such as `UserA` and `usera`. Accounts, passwords, roles, ownership, and identity links are preserved. Each conflicting account continues to accept only its exact stored username spelling; other capitalizations are rejected without choosing an account by its password. Disabled, expired, and passwordless accounts also count toward a conflict.\n\n**Settings** \u003e **Administration** \u003e **Users** lists conflicts in a warning, regardless of directory filters or pagination. Resolve a conflict by renaming an account through its normal editor, or deleting an account that's no longer needed. Deleting an account remains subject to the normal deletion consequences and administrator safeguards. Unchanged usernames and case-only renames remain available while resolving existing conflicts. Once only one account has a comparison key, case-insensitive password sign-in applies automatically, without restarting or rerunning a migration.\n\nOIDC identity matching and automatic linking still require the exact username spelling. A case-only match doesn't automatically link an identity or create another account; resolve that collision through the existing identity-mapping controls.\n\n## Require A Local Password Change\n\nWhen creating a local user or resetting an existing local password, enable **Require change on next password sign-in** to require a new password before the user can continue. The user directory shows **Pwd change req'd** while this requirement is pending.\n\nAfter signing in with the temporary or existing local password, the user must enter that password, choose a different password, and confirm it. They can sign out instead, but can't browse files, use administration settings, or issue companion credentials until the change succeeds. Successful changes invalidate existing Sambee tokens and require another sign-in.\n\nThe requirement applies only to local-password sessions. A linked user can still sign in through OIDC; that doesn't clear the local-password requirement or change the identity provider's password. Passwordless OIDC accounts have no local password to reset. In **OIDC only** mode, local password changes are unavailable.\n\nExisting password-change flags are enforced after upgrading. They aren't cleared automatically. If a user can't complete the change, an administrator can set another local password through User Management. Switch the requirement off during that reset only when the replacement password is intended to be permanent. Authentication-disabled mode doesn't enforce the change workflow.\n\n## Audit Events\n\nOIDC configuration, identity events, and successful local password changes and resets are stored in the Sambee database. They do not contain passwords, raw subjects, provider tokens, client secrets, authorization codes, nonces, verifiers, or one-time login grants. Events are retained until the database is removed or an external retention process deletes them.\n\nExport the complete audit stream as JSON Lines:\n\n```bash\ncd backend\npython -m app.oidc_admin export-audit --output sambee-audit.jsonl\n```\n\n## Authentication Request Limits\n\nSambee enforces authentication limits in the application. A reverse proxy can add stricter limits but does not replace these defaults:\n\n| Request | Default limit |\n|---|---|\n| Start OIDC authorization | 20 requests per source IP per 5 minutes |\n| Process OIDC callback | 60 requests per source IP per 5 minutes |\n| Exchange OIDC login grant | 30 requests per source IP per 5 minutes |\n| Password sign-in | 10 attempts per source IP per 5 minutes and 10 attempts per submitted username per 15 minutes |\n\nLimits refill continuously. A rejected API request returns `Retry-After`; browser-based OIDC requests return to the sign-in page with a generic retry message. Password forms larger than 64 KiB are rejected before parsing. These responses do not expose account existence, the active sign-in mode, provider payloads, or submitted credentials.\n\nAll capitalization and Unicode case-folding variants of a username share the same username-based password limit, including legacy conflicting accounts.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "book:developer-guide", "parent_id": null, "depth": 0, "kind": "book", "label": "developer-guide", "title": "Developer Guide", "path": "developer-guide", "has_children": true, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Developer Guide\"\n+++\n\nUse this guide to understand how Sambee is built across the backend, frontend, and companion, work safely in the repository and choose the right contributor workflow, understand the architecture and cross-cutting systems before changing code, and validate changes with the right checks before review or release.\n\n## Start Here if You Want To\n\n- Understand how the browser app, backend, and companion fit together.\n- Find the right place in the repository before changing code.\n- Set up the development environment and use the common contributor workflows.\n- Understand the high-level architecture of the backend, frontend, and companion.\n- Understand deeper contributor rules for preview pipelines, companion trust, or version-sensitive changes.\n- Choose the right validation commands before you open a pull request.\n\n## In This Guide\n\n- [Project Orientation](./project-orientation/): Understand the product boundaries and the repository layout.\n- [Local Development Workflow](./local-development-workflow/): Set up the environment and find the commands you will actually use.\n- [Backend Architecture](./backend-architecture/): Understand the FastAPI service, SMB-facing behavior, and server-side contracts.\n- [Frontend Architecture](./frontend-architecture/): Understand the browser app, page structure, and UI behavior contracts.\n- [Companion Architecture](./companion-architecture/): Understand the desktop app, pairing model, local-drive access, and native-app editing workflow.\n- [Cross-Cutting Systems](./cross-cutting-systems/): Understand shared logging, localization, and other rules that span more than one app.\n- [Testing and Quality Gates](./testing-and-quality-gates/): Choose the right checks for the change you are making.\n- [Contribution Workflows](./contribution-workflows/): Plan and review changes with the right scope and validation depth.\n- [Security](./security/): Understand dependency automation, vulnerability scanning, and release-artifact integrity.\n- [Release and Versioning](./release-and-versioning/): Handle dependency updates and version metadata safely.\n\n## Use the Right Guide\n\n- Use the Developer Guide when the next question is implementation-facing.\n- Use the [Website Dev Guide](../website-dev-guide/) when the work is on the public website, published docs content, docs tooling, or shared website theme systems.\n- Use the [User Guide](../user-guide/) when the next step belongs to the person using Sambee in normal workflows.\n- Use the [Admin Guide](../admin-guide/) when the next step is deployment, configuration, operations, or escalation.\n\n", "0.8": "+++\ntitle = \"Developer Guide\"\n+++\n\nUse this guide to understand how Sambee is built across the backend, frontend, and companion, work safely in the repository and choose the right contributor workflow, understand the architecture and cross-cutting systems before changing code, and validate changes with the right checks before review or release.\n\n## Start Here if You Want To\n\n- Understand how the browser app, backend, and companion fit together.\n- Find the right place in the repository before changing code.\n- Set up the development environment and use the common contributor workflows.\n- Understand the high-level architecture of the backend, frontend, and companion.\n- Understand deeper contributor rules for preview pipelines, companion trust, or version-sensitive changes.\n- Choose the right validation commands before you open a pull request.\n\n## In This Guide\n\n- [Project Orientation](./project-orientation/): Understand the product boundaries and the repository layout.\n- [Local Development Workflow](./local-development-workflow/): Set up the environment and find the commands you will actually use.\n- [Backend Architecture](./backend-architecture/): Understand the FastAPI service, SMB-facing behavior, and server-side contracts.\n- [Frontend Architecture](./frontend-architecture/): Understand the browser app, page structure, and UI behavior contracts.\n- [Companion Architecture](./companion-architecture/): Understand the desktop app, pairing model, local-drive access, and native-app editing workflow.\n- [Cross-Cutting Systems](./cross-cutting-systems/): Understand shared logging, localization, and other rules that span more than one app.\n- [Testing and Quality Gates](./testing-and-quality-gates/): Choose the right checks for the change you are making.\n- [Contribution Workflows](./contribution-workflows/): Plan and review changes with the right scope and validation depth.\n- [Security](./security/): Understand dependency automation, vulnerability scanning, and release-artifact integrity.\n- [Release and Versioning](./release-and-versioning/): Handle dependency updates and version metadata safely.\n\n## Use the Right Guide\n\n- Use the Developer Guide when the next question is implementation-facing.\n- Use the [Website Dev Guide](../website-dev-guide/) when the work is on the public website, published docs content, docs tooling, or shared website theme systems.\n- Use the [User Guide](../user-guide/) when the next step belongs to the person using Sambee in normal workflows.\n- Use the [Admin Guide](../admin-guide/) when the next step is deployment, configuration, operations, or escalation.\n\n", "0.9": "+++\ntitle = \"Developer Guide\"\n+++\n\nUse this guide to understand how Sambee is built across the backend, frontend, and companion, work safely in the repository and choose the right contributor workflow, understand the architecture and cross-cutting systems before changing code, and validate changes with the right checks before review or release.\n\n## Start Here if You Want To\n\n- Understand how the browser app, backend, and companion fit together.\n- Find the right place in the repository before changing code.\n- Set up the development environment and use the common contributor workflows.\n- Understand the high-level architecture of the backend, frontend, and companion.\n- Understand deeper contributor rules for preview pipelines, companion trust, or version-sensitive changes.\n- Choose the right validation commands before you open a pull request.\n\n## In This Guide\n\n- [Project Orientation](./project-orientation/): Understand the product boundaries and the repository layout.\n- [Local Development Workflow](./local-development-workflow/): Set up the environment and find the commands you will actually use.\n- [Backend Architecture](./backend-architecture/): Understand the FastAPI service, SMB-facing behavior, and server-side contracts.\n- [Frontend Architecture](./frontend-architecture/): Understand the browser app, page structure, and UI behavior contracts.\n- [Companion Architecture](./companion-architecture/): Understand the desktop app, pairing model, local-drive access, and native-app editing workflow.\n- [Cross-Cutting Systems](./cross-cutting-systems/): Understand shared logging, localization, and other rules that span more than one app.\n- [Testing and Quality Gates](./testing-and-quality-gates/): Choose the right checks for the change you are making.\n- [Contribution Workflows](./contribution-workflows/): Plan and review changes with the right scope and validation depth.\n- [Security](./security/): Understand dependency automation, vulnerability scanning, and release-artifact integrity.\n- [Release and Versioning](./release-and-versioning/): Handle dependency updates and version metadata safely.\n\n## Use the Right Guide\n\n- Use the Developer Guide when the next question is implementation-facing.\n- Use the [Website Dev Guide](../website-dev-guide/) when the work is on the public website, published docs content, docs tooling, or shared website theme systems.\n- Use the [User Guide](../user-guide/) when the next step belongs to the person using Sambee in normal workflows.\n- Use the [Admin Guide](../admin-guide/) when the next step is deployment, configuration, operations, or escalation.\n\n", "1.0": "+++\ntitle = \"Developer Guide\"\n+++\n\nUse this guide to understand how Sambee is built across the backend, frontend, and companion, work safely in the repository and choose the right contributor workflow, understand the architecture and cross-cutting systems before changing code, and validate changes with the right checks before review or release.\n\n## Start Here if You Want To\n\n- Understand how the browser app, backend, and companion fit together.\n- Find the right place in the repository before changing code.\n- Set up the development environment and use the common contributor workflows.\n- Understand the high-level architecture of the backend, frontend, and companion.\n- Understand deeper contributor rules for preview pipelines, companion trust, or version-sensitive changes.\n- Choose the right validation commands before you open a pull request.\n\n## In This Guide\n\n- [Project Orientation](./project-orientation/): Understand the product boundaries and the repository layout.\n- [Local Development Workflow](./local-development-workflow/): Set up the environment and find the commands you will actually use.\n- [Backend Architecture](./backend-architecture/): Understand the FastAPI service, SMB-facing behavior, and server-side contracts.\n- [Frontend Architecture](./frontend-architecture/): Understand the browser app, page structure, and UI behavior contracts.\n- [Companion Architecture](./companion-architecture/): Understand the desktop app, pairing model, local-drive access, and native-app editing workflow.\n- [Cross-Cutting Systems](./cross-cutting-systems/): Understand shared logging, localization, and other rules that span more than one app.\n- [Testing and Quality Gates](./testing-and-quality-gates/): Choose the right checks for the change you are making.\n- [Contribution Workflows](./contribution-workflows/): Plan and review changes with the right scope and validation depth.\n- [Security](./security/): Understand dependency automation, vulnerability scanning, and release-artifact integrity.\n- [Release and Versioning](./release-and-versioning/): Handle dependency updates and version metadata safely.\n\n## Use the Right Guide\n\n- Use the Developer Guide when the next question is implementation-facing.\n- Use the [Website Dev Guide](../website-dev-guide/) when the work is on the public website, published docs content, docs tooling, or shared website theme systems.\n- Use the [User Guide](../user-guide/) when the next step belongs to the person using Sambee in normal workflows.\n- Use the [Admin Guide](../admin-guide/) when the next step is deployment, configuration, operations, or escalation.\n\n", "2.0": "+++\ntitle = \"Developer Guide\"\n+++\n\nUse this guide to understand how Sambee is built across the backend, frontend, and companion, work safely in the repository and choose the right contributor workflow, understand the architecture and cross-cutting systems before changing code, and validate changes with the right checks before review or release.\n\n## Start Here if You Want To\n\n- Understand how the browser app, backend, and companion fit together.\n- Find the right place in the repository before changing code.\n- Set up the development environment and use the common contributor workflows.\n- Understand the high-level architecture of the backend, frontend, and companion.\n- Understand deeper contributor rules for preview pipelines, companion trust, or version-sensitive changes.\n- Choose the right validation commands before you open a pull request.\n\n## In This Guide\n\n- [Project Orientation](./project-orientation/): Understand the product boundaries and the repository layout.\n- [Local Development Workflow](./local-development-workflow/): Set up the environment and find the commands you will actually use.\n- [Backend Architecture](./backend-architecture/): Understand the FastAPI service, SMB-facing behavior, and server-side contracts.\n- [Frontend Architecture](./frontend-architecture/): Understand the browser app, page structure, and UI behavior contracts.\n- [Companion Architecture](./companion-architecture/): Understand the desktop app, pairing model, local-drive access, and native-app editing workflow.\n- [Cross-Cutting Systems](./cross-cutting-systems/): Understand shared logging, localization, and other rules that span more than one app.\n- [Testing and Quality Gates](./testing-and-quality-gates/): Choose the right checks for the change you are making.\n- [Contribution Workflows](./contribution-workflows/): Plan and review changes with the right scope and validation depth.\n- [Security](./security/): Understand dependency automation, vulnerability scanning, and release-artifact integrity.\n- [Release and Versioning](./release-and-versioning/): Handle dependency updates and version metadata safely.\n\n## Use the Right Guide\n\n- Use the Developer Guide when the next question is implementation-facing.\n- Use the [Website Dev Guide](../website-dev-guide/) when the work is on the public website, published docs content, docs tooling, or shared website theme systems.\n- Use the [User Guide](../user-guide/) when the next step belongs to the person using Sambee in normal workflows.\n- Use the [Admin Guide](../admin-guide/) when the next step is deployment, configuration, operations, or escalation.\n\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:developer-guide/project-orientation", "parent_id": "book:developer-guide", "depth": 1, "kind": "section", "label": "project-orientation", "title": "Project Orientation", "path": "developer-guide/project-orientation", "has_children": true, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Project Orientation\"\n+++\n\nStart here when you need the high-level mental model before changing anything.\n\n- [What Sambee Consists Of](./what-sambee-consists-of/): the system boundaries contributors need to preserve\n- [Repository Tour](./repository-tour/): where backend, frontend, companion, and shared repo workflows live\n\nIf you already understand the system boundaries and just need to get running locally, continue to [Local Development Workflow](../local-development-workflow/).\n", "0.8": "+++\ntitle = \"Project Orientation\"\n+++\n\nStart here when you need the high-level mental model before changing anything.\n\n- [What Sambee Consists Of](./what-sambee-consists-of/): the system boundaries contributors need to preserve\n- [Repository Tour](./repository-tour/): where backend, frontend, companion, and shared repo workflows live\n\nIf you already understand the system boundaries and just need to get running locally, continue to [Local Development Workflow](../local-development-workflow/).\n", "0.9": "+++\ntitle = \"Project Orientation\"\n+++\n\nStart here when you need the high-level mental model before changing anything.\n\n- [What Sambee Consists Of](./what-sambee-consists-of/): the system boundaries contributors need to preserve\n- [Repository Tour](./repository-tour/): where backend, frontend, companion, and shared repo workflows live\n\nIf you already understand the system boundaries and just need to get running locally, continue to [Local Development Workflow](../local-development-workflow/).\n", "1.0": "+++\ntitle = \"Project Orientation\"\n+++\n\nStart here when you need the high-level mental model before changing anything.\n\n- [What Sambee Consists Of](./what-sambee-consists-of/): the system boundaries contributors need to preserve\n- [Repository Tour](./repository-tour/): where backend, frontend, companion, and shared repo workflows live\n\nIf you already understand the system boundaries and just need to get running locally, continue to [Local Development Workflow](../local-development-workflow/).\n", "2.0": "+++\ntitle = \"Project Orientation\"\n+++\n\nStart here when you need the high-level mental model before changing anything.\n\n- [What Sambee Consists Of](./what-sambee-consists-of/): the system boundaries contributors need to preserve\n- [Repository Tour](./repository-tour/): where backend, frontend, companion, and shared repo workflows live\n\nIf you already understand the system boundaries and just need to get running locally, continue to [Local Development Workflow](../local-development-workflow/).\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/project-orientation/what-sambee-consists-of", "parent_id": "section:developer-guide/project-orientation", "depth": 2, "kind": "page", "label": "what-sambee-consists-of", "title": "What Sambee Consists Of", "path": "developer-guide/project-orientation/what-sambee-consists-of", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"What Sambee Consists Of\"\n+++\n\nSambee is not a single app with one execution model. It is a coordinated system with separate responsibilities in the browser, on the server, and on the desktop.\n\n## The Major Pieces\n\n| Subsystem | Main responsibility | Where it lives |\n|---|---|---|\n| Browser app | User-facing file browsing, preview, editing UI, and service calls | `frontend/` |\n| Backend service | Authentication, API endpoints, SMB access, server-side file handling, locks, and notifications | `backend/` |\n| Companion app | Native-app editing, local-drive access, pairing, and desktop-local integrations | `companion/` |\n\n## Capability Boundaries Contributors Must Preserve\n\nSambee deliberately separates browser-only workflows from companion-backed workflows.\n\nBrowser-only workflows:\n\n- browsing SMB shares\n- previewing supported content in the browser\n- managing files through the web interface\n- editing Markdown directly in the browser\n\nCompanion-backed workflows:\n\n- browsing local drives on the same machine as the browser\n- opening files in installed native desktop applications\n- returning native-app edits to the source location\n- syncing localization and other browser-to-desktop state where the product requires it\n\nThose boundaries matter because the product makes different trust, runtime, and platform assumptions in each path.\n\n## How a Normal Request Path Splits\n\nFor an SMB-browser workflow:\n\n1. The browser app issues authenticated API calls.\n2. The backend enforces server-side policy and talks to SMB storage.\n3. The browser renders the result.\n\nFor a companion-backed workflow:\n\n1. The browser app still owns the main user workflow.\n2. The companion is discovered or launched locally.\n3. Browser and companion exchange trusted local information through pairing or deep links, depending on the flow.\n4. The backend remains the source of truth for SMB edit workflows, while the companion adds desktop-local capability.\n\n## What This Means for Contributors\n\nWhen you change Sambee, do not treat every feature as interchangeable.\n\n- A frontend-only change can still break a backend contract.\n- A backend change can alter browser behavior, companion behavior, or both.\n- A companion change can affect desktop editing, local drives, and paired browser expectations.\n\nUse the rest of this guide to go deeper into each subsystem rather than trying to keep the whole model in your head at once.\n", "0.8": "+++\ntitle = \"What Sambee Consists Of\"\n+++\n\nSambee is not a single app with one execution model. It is a coordinated system with separate responsibilities in the browser, on the server, and on the desktop.\n\n## The Major Pieces\n\n| Subsystem | Main responsibility | Where it lives |\n|---|---|---|\n| Browser app | User-facing file browsing, preview, editing UI, and service calls | `frontend/` |\n| Backend service | Authentication, API endpoints, SMB access, server-side file handling, locks, and notifications | `backend/` |\n| Companion app | Native-app editing, local-drive access, pairing, and desktop-local integrations | `companion/` |\n\n## Capability Boundaries Contributors Must Preserve\n\nSambee deliberately separates browser-only workflows from companion-backed workflows.\n\nBrowser-only workflows:\n\n- browsing SMB shares\n- previewing supported content in the browser\n- managing files through the web interface\n- editing Markdown directly in the browser\n\nCompanion-backed workflows:\n\n- browsing local drives on the same machine as the browser\n- opening files in installed native desktop applications\n- returning native-app edits to the source location\n- syncing localization and other browser-to-desktop state where the product requires it\n\nThose boundaries matter because the product makes different trust, runtime, and platform assumptions in each path.\n\n## How a Normal Request Path Splits\n\nFor an SMB-browser workflow:\n\n1. The browser app issues authenticated API calls.\n2. The backend enforces server-side policy and talks to SMB storage.\n3. The browser renders the result.\n\nFor a companion-backed workflow:\n\n1. The browser app still owns the main user workflow.\n2. The companion is discovered or launched locally.\n3. Browser and companion exchange trusted local information through pairing or deep links, depending on the flow.\n4. The backend remains the source of truth for SMB edit workflows, while the companion adds desktop-local capability.\n\n## What This Means for Contributors\n\nWhen you change Sambee, do not treat every feature as interchangeable.\n\n- A frontend-only change can still break a backend contract.\n- A backend change can alter browser behavior, companion behavior, or both.\n- A companion change can affect desktop editing, local drives, and paired browser expectations.\n\nUse the rest of this guide to go deeper into each subsystem rather than trying to keep the whole model in your head at once.\n", "0.9": "+++\ntitle = \"What Sambee Consists Of\"\n+++\n\nSambee is not a single app with one execution model. It is a coordinated system with separate responsibilities in the browser, on the server, and on the desktop.\n\n## The Major Pieces\n\n| Subsystem | Main responsibility | Where it lives |\n|---|---|---|\n| Browser app | User-facing file browsing, preview, editing UI, and service calls | `frontend/` |\n| Backend service | Authentication, API endpoints, SMB access, server-side file handling, locks, and notifications | `backend/` |\n| Companion app | Native-app editing, local-drive access, pairing, and desktop-local integrations | `companion/` |\n\n## Capability Boundaries Contributors Must Preserve\n\nSambee deliberately separates browser-only workflows from companion-backed workflows.\n\nBrowser-only workflows:\n\n- browsing SMB shares\n- previewing supported content in the browser\n- managing files through the web interface\n- editing Markdown directly in the browser\n\nCompanion-backed workflows:\n\n- browsing local drives on the same machine as the browser\n- opening files in installed native desktop applications\n- returning native-app edits to the source location\n- syncing localization and other browser-to-desktop state where the product requires it\n\nThose boundaries matter because the product makes different trust, runtime, and platform assumptions in each path.\n\n## How a Normal Request Path Splits\n\nFor an SMB-browser workflow:\n\n1. The browser app issues authenticated API calls.\n2. The backend enforces server-side policy and talks to SMB storage.\n3. The browser renders the result.\n\nFor a companion-backed workflow:\n\n1. The browser app still owns the main user workflow.\n2. The companion is discovered or launched locally.\n3. Browser and companion exchange trusted local information through pairing or deep links, depending on the flow.\n4. The backend remains the source of truth for SMB edit workflows, while the companion adds desktop-local capability.\n\n## What This Means for Contributors\n\nWhen you change Sambee, do not treat every feature as interchangeable.\n\n- A frontend-only change can still break a backend contract.\n- A backend change can alter browser behavior, companion behavior, or both.\n- A companion change can affect desktop editing, local drives, and paired browser expectations.\n\nUse the rest of this guide to go deeper into each subsystem rather than trying to keep the whole model in your head at once.\n", "1.0": "+++\ntitle = \"What Sambee Consists Of\"\n+++\n\nSambee is not a single app with one execution model. It is a coordinated system with separate responsibilities in the browser, on the server, and on the desktop.\n\n## The Major Pieces\n\n| Subsystem | Main responsibility | Where it lives |\n|---|---|---|\n| Browser app | User-facing file browsing, preview, editing UI, and service calls | `frontend/` |\n| Backend service | Authentication, API endpoints, SMB access, server-side file handling, locks, and notifications | `backend/` |\n| Companion app | Native-app editing, local-drive access, pairing, and desktop-local integrations | `companion/` |\n\n## Capability Boundaries Contributors Must Preserve\n\nSambee deliberately separates browser-only workflows from companion-backed workflows.\n\nBrowser-only workflows:\n\n- browsing SMB shares\n- previewing supported content in the browser\n- managing files through the web interface\n- editing Markdown directly in the browser\n\nCompanion-backed workflows:\n\n- browsing local drives on the same machine as the browser\n- opening files in installed native desktop applications\n- returning native-app edits to the source location\n- syncing localization and other browser-to-desktop state where the product requires it\n\nThose boundaries matter because the product makes different trust, runtime, and platform assumptions in each path.\n\n## How a Normal Request Path Splits\n\nFor an SMB-browser workflow:\n\n1. The browser app issues authenticated API calls.\n2. The backend enforces server-side policy and talks to SMB storage.\n3. The browser renders the result.\n\nFor a companion-backed workflow:\n\n1. The browser app still owns the main user workflow.\n2. The companion is discovered or launched locally.\n3. Browser and companion exchange trusted local information through pairing or deep links, depending on the flow.\n4. The backend remains the source of truth for SMB edit workflows, while the companion adds desktop-local capability.\n\n## What This Means for Contributors\n\nWhen you change Sambee, do not treat every feature as interchangeable.\n\n- A frontend-only change can still break a backend contract.\n- A backend change can alter browser behavior, companion behavior, or both.\n- A companion change can affect desktop editing, local drives, and paired browser expectations.\n\nUse the rest of this guide to go deeper into each subsystem rather than trying to keep the whole model in your head at once.\n", "2.0": "+++\ntitle = \"What Sambee Consists Of\"\n+++\n\nSambee is not a single app with one execution model. It is a coordinated system with separate responsibilities in the browser, on the server, and on the desktop.\n\n## The Major Pieces\n\n| Subsystem | Main responsibility | Where it lives |\n|---|---|---|\n| Browser app | User-facing file browsing, preview, editing UI, and service calls | `frontend/` |\n| Backend service | Authentication, API endpoints, SMB access, server-side file handling, locks, and notifications | `backend/` |\n| Companion app | Native-app editing, local-drive access, pairing, and desktop-local integrations | `companion/` |\n\n## Capability Boundaries Contributors Must Preserve\n\nSambee deliberately separates browser-only workflows from companion-backed workflows.\n\nBrowser-only workflows:\n\n- browsing SMB shares\n- previewing supported content in the browser\n- managing files through the web interface\n- editing Markdown directly in the browser\n\nCompanion-backed workflows:\n\n- browsing local drives on the same machine as the browser\n- opening files in installed native desktop applications\n- returning native-app edits to the source location\n- syncing localization and other browser-to-desktop state where the product requires it\n\nThose boundaries matter because the product makes different trust, runtime, and platform assumptions in each path.\n\n## How a Normal Request Path Splits\n\nFor an SMB-browser workflow:\n\n1. The browser app issues authenticated API calls.\n2. The backend enforces server-side policy and talks to SMB storage.\n3. The browser renders the result.\n\nFor a companion-backed workflow:\n\n1. The browser app still owns the main user workflow.\n2. The companion is discovered or launched locally.\n3. Browser and companion exchange trusted local information through pairing or deep links, depending on the flow.\n4. The backend remains the source of truth for SMB edit workflows, while the companion adds desktop-local capability.\n\n## What This Means for Contributors\n\nWhen you change Sambee, do not treat every feature as interchangeable.\n\n- A frontend-only change can still break a backend contract.\n- A backend change can alter browser behavior, companion behavior, or both.\n- A companion change can affect desktop editing, local drives, and paired browser expectations.\n\nUse the rest of this guide to go deeper into each subsystem rather than trying to keep the whole model in your head at once.\n"}, "page_contents": {"0.7": "+++\ntitle = \"What Sambee Consists Of\"\n+++\n\nSambee is not a single app with one execution model. It is a coordinated system with separate responsibilities in the browser, on the server, and on the desktop.\n\n## The Major Pieces\n\n| Subsystem | Main responsibility | Where it lives |\n|---|---|---|\n| Browser app | User-facing file browsing, preview, editing UI, and service calls | `frontend/` |\n| Backend service | Authentication, API endpoints, SMB access, server-side file handling, locks, and notifications | `backend/` |\n| Companion app | Native-app editing, local-drive access, pairing, and desktop-local integrations | `companion/` |\n\n## Capability Boundaries Contributors Must Preserve\n\nSambee deliberately separates browser-only workflows from companion-backed workflows.\n\nBrowser-only workflows:\n\n- browsing SMB shares\n- previewing supported content in the browser\n- managing files through the web interface\n- editing Markdown directly in the browser\n\nCompanion-backed workflows:\n\n- browsing local drives on the same machine as the browser\n- opening files in installed native desktop applications\n- returning native-app edits to the source location\n- syncing localization and other browser-to-desktop state where the product requires it\n\nThose boundaries matter because the product makes different trust, runtime, and platform assumptions in each path.\n\n## How a Normal Request Path Splits\n\nFor an SMB-browser workflow:\n\n1. The browser app issues authenticated API calls.\n2. The backend enforces server-side policy and talks to SMB storage.\n3. The browser renders the result.\n\nFor a companion-backed workflow:\n\n1. The browser app still owns the main user workflow.\n2. The companion is discovered or launched locally.\n3. Browser and companion exchange trusted local information through pairing or deep links, depending on the flow.\n4. The backend remains the source of truth for SMB edit workflows, while the companion adds desktop-local capability.\n\n## What This Means for Contributors\n\nWhen you change Sambee, do not treat every feature as interchangeable.\n\n- A frontend-only change can still break a backend contract.\n- A backend change can alter browser behavior, companion behavior, or both.\n- A companion change can affect desktop editing, local drives, and paired browser expectations.\n\nUse the rest of this guide to go deeper into each subsystem rather than trying to keep the whole model in your head at once.\n", "0.8": "+++\ntitle = \"What Sambee Consists Of\"\n+++\n\nSambee is not a single app with one execution model. It is a coordinated system with separate responsibilities in the browser, on the server, and on the desktop.\n\n## The Major Pieces\n\n| Subsystem | Main responsibility | Where it lives |\n|---|---|---|\n| Browser app | User-facing file browsing, preview, editing UI, and service calls | `frontend/` |\n| Backend service | Authentication, API endpoints, SMB access, server-side file handling, locks, and notifications | `backend/` |\n| Companion app | Native-app editing, local-drive access, pairing, and desktop-local integrations | `companion/` |\n\n## Capability Boundaries Contributors Must Preserve\n\nSambee deliberately separates browser-only workflows from companion-backed workflows.\n\nBrowser-only workflows:\n\n- browsing SMB shares\n- previewing supported content in the browser\n- managing files through the web interface\n- editing Markdown directly in the browser\n\nCompanion-backed workflows:\n\n- browsing local drives on the same machine as the browser\n- opening files in installed native desktop applications\n- returning native-app edits to the source location\n- syncing localization and other browser-to-desktop state where the product requires it\n\nThose boundaries matter because the product makes different trust, runtime, and platform assumptions in each path.\n\n## How a Normal Request Path Splits\n\nFor an SMB-browser workflow:\n\n1. The browser app issues authenticated API calls.\n2. The backend enforces server-side policy and talks to SMB storage.\n3. The browser renders the result.\n\nFor a companion-backed workflow:\n\n1. The browser app still owns the main user workflow.\n2. The companion is discovered or launched locally.\n3. Browser and companion exchange trusted local information through pairing or deep links, depending on the flow.\n4. The backend remains the source of truth for SMB edit workflows, while the companion adds desktop-local capability.\n\n## What This Means for Contributors\n\nWhen you change Sambee, do not treat every feature as interchangeable.\n\n- A frontend-only change can still break a backend contract.\n- A backend change can alter browser behavior, companion behavior, or both.\n- A companion change can affect desktop editing, local drives, and paired browser expectations.\n\nUse the rest of this guide to go deeper into each subsystem rather than trying to keep the whole model in your head at once.\n", "0.9": "+++\ntitle = \"What Sambee Consists Of\"\n+++\n\nSambee is not a single app with one execution model. It is a coordinated system with separate responsibilities in the browser, on the server, and on the desktop.\n\n## The Major Pieces\n\n| Subsystem | Main responsibility | Where it lives |\n|---|---|---|\n| Browser app | User-facing file browsing, preview, editing UI, and service calls | `frontend/` |\n| Backend service | Authentication, API endpoints, SMB access, server-side file handling, locks, and notifications | `backend/` |\n| Companion app | Native-app editing, local-drive access, pairing, and desktop-local integrations | `companion/` |\n\n## Capability Boundaries Contributors Must Preserve\n\nSambee deliberately separates browser-only workflows from companion-backed workflows.\n\nBrowser-only workflows:\n\n- browsing SMB shares\n- previewing supported content in the browser\n- managing files through the web interface\n- editing Markdown directly in the browser\n\nCompanion-backed workflows:\n\n- browsing local drives on the same machine as the browser\n- opening files in installed native desktop applications\n- returning native-app edits to the source location\n- syncing localization and other browser-to-desktop state where the product requires it\n\nThose boundaries matter because the product makes different trust, runtime, and platform assumptions in each path.\n\n## How a Normal Request Path Splits\n\nFor an SMB-browser workflow:\n\n1. The browser app issues authenticated API calls.\n2. The backend enforces server-side policy and talks to SMB storage.\n3. The browser renders the result.\n\nFor a companion-backed workflow:\n\n1. The browser app still owns the main user workflow.\n2. The companion is discovered or launched locally.\n3. Browser and companion exchange trusted local information through pairing or deep links, depending on the flow.\n4. The backend remains the source of truth for SMB edit workflows, while the companion adds desktop-local capability.\n\n## What This Means for Contributors\n\nWhen you change Sambee, do not treat every feature as interchangeable.\n\n- A frontend-only change can still break a backend contract.\n- A backend change can alter browser behavior, companion behavior, or both.\n- A companion change can affect desktop editing, local drives, and paired browser expectations.\n\nUse the rest of this guide to go deeper into each subsystem rather than trying to keep the whole model in your head at once.\n", "1.0": "+++\ntitle = \"What Sambee Consists Of\"\n+++\n\nSambee is not a single app with one execution model. It is a coordinated system with separate responsibilities in the browser, on the server, and on the desktop.\n\n## The Major Pieces\n\n| Subsystem | Main responsibility | Where it lives |\n|---|---|---|\n| Browser app | User-facing file browsing, preview, editing UI, and service calls | `frontend/` |\n| Backend service | Authentication, API endpoints, SMB access, server-side file handling, locks, and notifications | `backend/` |\n| Companion app | Native-app editing, local-drive access, pairing, and desktop-local integrations | `companion/` |\n\n## Capability Boundaries Contributors Must Preserve\n\nSambee deliberately separates browser-only workflows from companion-backed workflows.\n\nBrowser-only workflows:\n\n- browsing SMB shares\n- previewing supported content in the browser\n- managing files through the web interface\n- editing Markdown directly in the browser\n\nCompanion-backed workflows:\n\n- browsing local drives on the same machine as the browser\n- opening files in installed native desktop applications\n- returning native-app edits to the source location\n- syncing localization and other browser-to-desktop state where the product requires it\n\nThose boundaries matter because the product makes different trust, runtime, and platform assumptions in each path.\n\n## How a Normal Request Path Splits\n\nFor an SMB-browser workflow:\n\n1. The browser app issues authenticated API calls.\n2. The backend enforces server-side policy and talks to SMB storage.\n3. The browser renders the result.\n\nFor a companion-backed workflow:\n\n1. The browser app still owns the main user workflow.\n2. The companion is discovered or launched locally.\n3. Browser and companion exchange trusted local information through pairing or deep links, depending on the flow.\n4. The backend remains the source of truth for SMB edit workflows, while the companion adds desktop-local capability.\n\n## What This Means for Contributors\n\nWhen you change Sambee, do not treat every feature as interchangeable.\n\n- A frontend-only change can still break a backend contract.\n- A backend change can alter browser behavior, companion behavior, or both.\n- A companion change can affect desktop editing, local drives, and paired browser expectations.\n\nUse the rest of this guide to go deeper into each subsystem rather than trying to keep the whole model in your head at once.\n", "2.0": "+++\ntitle = \"What Sambee Consists Of\"\n+++\n\nSambee is not a single app with one execution model. It is a coordinated system with separate responsibilities in the browser, on the server, and on the desktop.\n\n## The Major Pieces\n\n| Subsystem | Main responsibility | Where it lives |\n|---|---|---|\n| Browser app | User-facing file browsing, preview, editing UI, and service calls | `frontend/` |\n| Backend service | Authentication, API endpoints, SMB access, server-side file handling, locks, and notifications | `backend/` |\n| Companion app | Native-app editing, local-drive access, pairing, and desktop-local integrations | `companion/` |\n\n## Capability Boundaries Contributors Must Preserve\n\nSambee deliberately separates browser-only workflows from companion-backed workflows.\n\nBrowser-only workflows:\n\n- browsing SMB shares\n- previewing supported content in the browser\n- managing files through the web interface\n- editing Markdown directly in the browser\n\nCompanion-backed workflows:\n\n- browsing local drives on the same machine as the browser\n- opening files in installed native desktop applications\n- returning native-app edits to the source location\n- syncing localization and other browser-to-desktop state where the product requires it\n\nThose boundaries matter because the product makes different trust, runtime, and platform assumptions in each path.\n\n## How a Normal Request Path Splits\n\nFor an SMB-browser workflow:\n\n1. The browser app issues authenticated API calls.\n2. The backend enforces server-side policy and talks to SMB storage.\n3. The browser renders the result.\n\nFor a companion-backed workflow:\n\n1. The browser app still owns the main user workflow.\n2. The companion is discovered or launched locally.\n3. Browser and companion exchange trusted local information through pairing or deep links, depending on the flow.\n4. The backend remains the source of truth for SMB edit workflows, while the companion adds desktop-local capability.\n\n## What This Means for Contributors\n\nWhen you change Sambee, do not treat every feature as interchangeable.\n\n- A frontend-only change can still break a backend contract.\n- A backend change can alter browser behavior, companion behavior, or both.\n- A companion change can affect desktop editing, local drives, and paired browser expectations.\n\nUse the rest of this guide to go deeper into each subsystem rather than trying to keep the whole model in your head at once.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/project-orientation/repository-tour", "parent_id": "section:developer-guide/project-orientation", "depth": 2, "kind": "page", "label": "repository-tour", "title": "Repository Tour", "path": "developer-guide/project-orientation/repository-tour", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Repository Tour\"\n+++\n\nThis repository is organized around product boundaries, not just programming languages.\n\n## Top-Level Areas\n\n| Path | What it contains | Start here when |\n|---|---|---|\n| `backend/` | FastAPI application, models, services, storage code, and backend tests | you are changing API behavior, SMB handling, server-side validation, or edit-lock behavior |\n| `frontend/` | React browser app, UI components, pages, hooks, services, and browser-side tests | you are changing the main web UI or browser behavior |\n| `companion/` | Tauri desktop app with Preact UI and Rust backend | you are changing local-drive access, native-app editing, pairing, or desktop-side behavior |\n| `scripts/` | repo-level helper scripts for dev services, tests, version sync, and setup | you need the supported workflow instead of an ad hoc command |\n\n## Important Root Files\n\nThese files shape contributor workflows even though they are not feature code.\n\n| Path | Why it matters |\n|---|---|\n| `VERSION` | single source of truth for the current release identifier |\n| `config.example.toml` | starting point for local configuration |\n| `config.toml` | active local configuration in development or deployment |\n| `README.md` | high-level product framing |\n| `AGENTS.md` | repository-specific working rules for this environment |\n| `biome.json` | shared formatting and lint configuration for JavaScript and TypeScript work |\n\n## Product-Specific Notes\n\n- `backend/app/` is where the service code lives. Use it when the browser depends on server behavior or when SMB behavior changes.\n- `backend/tests/` holds the backend validation layer. Keep it close to backend behavior changes.\n- `frontend/src/` is the main browser app surface. Pages, services, and UI contracts all converge here.\n- `companion/src/` holds the desktop UI, while `companion/src-tauri/` holds the Rust backend, local API, and deep-link handling.\n## Where to Look First for Common Changes\n\n- Browser workflow change: start in `frontend/`, then confirm the backend or companion contract the UI depends on.\n- SMB behavior change: start in `backend/`, then validate the frontend behavior that consumes it.\n- Native-app editing or local-drive change: start in `companion/`, then review the related browser and backend contract.\n\n## What Not to Do\n\n- Do not treat the repo as three isolated apps. Many changes cross backend, frontend, and companion boundaries.\n- Do not assume lockfiles, version metadata, or generated files are incidental. Several workflows rely on them as reviewed source.\n\nIf you know which area you need, continue to [Local Development Workflow](../../local-development-workflow/) or jump directly to the relevant architecture section.\n", "0.8": "+++\ntitle = \"Repository Tour\"\n+++\n\nThis repository is organized around product boundaries, not just programming languages.\n\n## Top-Level Areas\n\n| Path | What it contains | Start here when |\n|---|---|---|\n| `backend/` | FastAPI application, models, services, storage code, and backend tests | you are changing API behavior, SMB handling, server-side validation, or edit-lock behavior |\n| `frontend/` | React browser app, UI components, pages, hooks, services, and browser-side tests | you are changing the main web UI or browser behavior |\n| `companion/` | Tauri desktop app with Preact UI and Rust backend | you are changing local-drive access, native-app editing, pairing, or desktop-side behavior |\n| `scripts/` | repo-level helper scripts for dev services, tests, version sync, and setup | you need the supported workflow instead of an ad hoc command |\n\n## Important Root Files\n\nThese files shape contributor workflows even though they are not feature code.\n\n| Path | Why it matters |\n|---|---|\n| `VERSION` | single source of truth for the current release identifier |\n| `config.example.toml` | starting point for local configuration |\n| `config.toml` | active local configuration in development or deployment |\n| `README.md` | high-level product framing |\n| `AGENTS.md` | repository-specific working rules for this environment |\n| `biome.json` | shared formatting and lint configuration for JavaScript and TypeScript work |\n\n## Product-Specific Notes\n\n- `backend/app/` is where the service code lives. Use it when the browser depends on server behavior or when SMB behavior changes.\n- `backend/tests/` holds the backend validation layer. Keep it close to backend behavior changes.\n- `frontend/src/` is the main browser app surface. Pages, services, and UI contracts all converge here.\n- `companion/src/` holds the desktop UI, while `companion/src-tauri/` holds the Rust backend, local API, and deep-link handling.\n## Where to Look First for Common Changes\n\n- Browser workflow change: start in `frontend/`, then confirm the backend or companion contract the UI depends on.\n- SMB behavior change: start in `backend/`, then validate the frontend behavior that consumes it.\n- Native-app editing or local-drive change: start in `companion/`, then review the related browser and backend contract.\n\n## What Not to Do\n\n- Do not treat the repo as three isolated apps. Many changes cross backend, frontend, and companion boundaries.\n- Do not assume lockfiles, version metadata, or generated files are incidental. Several workflows rely on them as reviewed source.\n\nIf you know which area you need, continue to [Local Development Workflow](../../local-development-workflow/) or jump directly to the relevant architecture section.\n", "0.9": "+++\ntitle = \"Repository Tour\"\n+++\n\nThis repository is organized around product boundaries, not just programming languages.\n\n## Top-Level Areas\n\n| Path | What it contains | Start here when |\n|---|---|---|\n| `backend/` | FastAPI application, models, services, storage code, and backend tests | you are changing API behavior, SMB handling, server-side validation, or edit-lock behavior |\n| `frontend/` | React browser app, UI components, pages, hooks, services, and browser-side tests | you are changing the main web UI or browser behavior |\n| `companion/` | Tauri desktop app with Preact UI and Rust backend | you are changing local-drive access, native-app editing, pairing, or desktop-side behavior |\n| `scripts/` | repo-level helper scripts for dev services, tests, version sync, and setup | you need the supported workflow instead of an ad hoc command |\n\n## Important Root Files\n\nThese files shape contributor workflows even though they are not feature code.\n\n| Path | Why it matters |\n|---|---|\n| `VERSION` | single source of truth for the current release identifier |\n| `config.example.toml` | starting point for local configuration |\n| `config.toml` | active local configuration in development or deployment |\n| `README.md` | high-level product framing |\n| `AGENTS.md` | repository-specific working rules for this environment |\n| `biome.json` | shared formatting and lint configuration for JavaScript and TypeScript work |\n\n## Product-Specific Notes\n\n- `backend/app/` is where the service code lives. Use it when the browser depends on server behavior or when SMB behavior changes.\n- `backend/tests/` holds the backend validation layer. Keep it close to backend behavior changes.\n- `frontend/src/` is the main browser app surface. Pages, services, and UI contracts all converge here.\n- `companion/src/` holds the desktop UI, while `companion/src-tauri/` holds the Rust backend, local API, and deep-link handling.\n## Where to Look First for Common Changes\n\n- Browser workflow change: start in `frontend/`, then confirm the backend or companion contract the UI depends on.\n- SMB behavior change: start in `backend/`, then validate the frontend behavior that consumes it.\n- Native-app editing or local-drive change: start in `companion/`, then review the related browser and backend contract.\n\n## What Not to Do\n\n- Do not treat the repo as three isolated apps. Many changes cross backend, frontend, and companion boundaries.\n- Do not assume lockfiles, version metadata, or generated files are incidental. Several workflows rely on them as reviewed source.\n\nIf you know which area you need, continue to [Local Development Workflow](../../local-development-workflow/) or jump directly to the relevant architecture section.\n", "1.0": "+++\ntitle = \"Repository Tour\"\n+++\n\nThis repository is organized around product boundaries, not just programming languages.\n\n## Top-Level Areas\n\n| Path | What it contains | Start here when |\n|---|---|---|\n| `backend/` | FastAPI application, models, services, storage code, and backend tests | you are changing API behavior, SMB handling, server-side validation, or edit-lock behavior |\n| `frontend/` | React browser app, UI components, pages, hooks, services, and browser-side tests | you are changing the main web UI or browser behavior |\n| `companion/` | Tauri desktop app with Preact UI and Rust backend | you are changing local-drive access, native-app editing, pairing, or desktop-side behavior |\n| `scripts/` | repo-level helper scripts for dev services, tests, version sync, and setup | you need the supported workflow instead of an ad hoc command |\n\n## Important Root Files\n\nThese files shape contributor workflows even though they are not feature code.\n\n| Path | Why it matters |\n|---|---|\n| `VERSION` | single source of truth for the current release identifier |\n| `config.example.toml` | starting point for local configuration |\n| `config.toml` | active local configuration in development or deployment |\n| `README.md` | high-level product framing |\n| `AGENTS.md` | repository-specific working rules for this environment |\n| `biome.json` | shared formatting and lint configuration for JavaScript and TypeScript work |\n\n## Product-Specific Notes\n\n- `backend/app/` is where the service code lives. Use it when the browser depends on server behavior or when SMB behavior changes.\n- `backend/tests/` holds the backend validation layer. Keep it close to backend behavior changes.\n- `frontend/src/` is the main browser app surface. Pages, services, and UI contracts all converge here.\n- `companion/src/` holds the desktop UI, while `companion/src-tauri/` holds the Rust backend, local API, and deep-link handling.\n## Where to Look First for Common Changes\n\n- Browser workflow change: start in `frontend/`, then confirm the backend or companion contract the UI depends on.\n- SMB behavior change: start in `backend/`, then validate the frontend behavior that consumes it.\n- Native-app editing or local-drive change: start in `companion/`, then review the related browser and backend contract.\n\n## What Not to Do\n\n- Do not treat the repo as three isolated apps. Many changes cross backend, frontend, and companion boundaries.\n- Do not assume lockfiles, version metadata, or generated files are incidental. Several workflows rely on them as reviewed source.\n\nIf you know which area you need, continue to [Local Development Workflow](../../local-development-workflow/) or jump directly to the relevant architecture section.\n", "2.0": "+++\ntitle = \"Repository Tour\"\n+++\n\nThis repository is organized around product boundaries, not just programming languages.\n\n## Top-Level Areas\n\n| Path | What it contains | Start here when |\n|---|---|---|\n| `backend/` | FastAPI application, models, services, storage code, and backend tests | you are changing API behavior, SMB handling, server-side validation, or edit-lock behavior |\n| `frontend/` | React browser app, UI components, pages, hooks, services, and browser-side tests | you are changing the main web UI or browser behavior |\n| `companion/` | Tauri desktop app with Preact UI and Rust backend | you are changing local-drive access, native-app editing, pairing, or desktop-side behavior |\n| `scripts/` | repo-level helper scripts for dev services, tests, version sync, and setup | you need the supported workflow instead of an ad hoc command |\n\n## Important Root Files\n\nThese files shape contributor workflows even though they are not feature code.\n\n| Path | Why it matters |\n|---|---|\n| `VERSION` | single source of truth for the current release identifier |\n| `config.example.toml` | starting point for local configuration |\n| `config.toml` | active local configuration in development or deployment |\n| `README.md` | high-level product framing |\n| `AGENTS.md` | repository-specific working rules for this environment |\n| `biome.json` | shared formatting and lint configuration for JavaScript and TypeScript work |\n\n## Product-Specific Notes\n\n- `backend/app/` is where the service code lives. Use it when the browser depends on server behavior or when SMB behavior changes.\n- `backend/tests/` holds the backend validation layer. Keep it close to backend behavior changes.\n- `frontend/src/` is the main browser app surface. Pages, services, and UI contracts all converge here.\n- `companion/src/` holds the desktop UI, while `companion/src-tauri/` holds the Rust backend, local API, and deep-link handling.\n## Where to Look First for Common Changes\n\n- Browser workflow change: start in `frontend/`, then confirm the backend or companion contract the UI depends on.\n- SMB behavior change: start in `backend/`, then validate the frontend behavior that consumes it.\n- Native-app editing or local-drive change: start in `companion/`, then review the related browser and backend contract.\n\n## What Not to Do\n\n- Do not treat the repo as three isolated apps. Many changes cross backend, frontend, and companion boundaries.\n- Do not assume lockfiles, version metadata, or generated files are incidental. Several workflows rely on them as reviewed source.\n\nIf you know which area you need, continue to [Local Development Workflow](../../local-development-workflow/) or jump directly to the relevant architecture section.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Repository Tour\"\n+++\n\nThis repository is organized around product boundaries, not just programming languages.\n\n## Top-Level Areas\n\n| Path | What it contains | Start here when |\n|---|---|---|\n| `backend/` | FastAPI application, models, services, storage code, and backend tests | you are changing API behavior, SMB handling, server-side validation, or edit-lock behavior |\n| `frontend/` | React browser app, UI components, pages, hooks, services, and browser-side tests | you are changing the main web UI or browser behavior |\n| `companion/` | Tauri desktop app with Preact UI and Rust backend | you are changing local-drive access, native-app editing, pairing, or desktop-side behavior |\n| `scripts/` | repo-level helper scripts for dev services, tests, version sync, and setup | you need the supported workflow instead of an ad hoc command |\n\n## Important Root Files\n\nThese files shape contributor workflows even though they are not feature code.\n\n| Path | Why it matters |\n|---|---|\n| `VERSION` | single source of truth for the current release identifier |\n| `config.example.toml` | starting point for local configuration |\n| `config.toml` | active local configuration in development or deployment |\n| `README.md` | high-level product framing |\n| `AGENTS.md` | repository-specific working rules for this environment |\n| `biome.json` | shared formatting and lint configuration for JavaScript and TypeScript work |\n\n## Product-Specific Notes\n\n- `backend/app/` is where the service code lives. Use it when the browser depends on server behavior or when SMB behavior changes.\n- `backend/tests/` holds the backend validation layer. Keep it close to backend behavior changes.\n- `frontend/src/` is the main browser app surface. Pages, services, and UI contracts all converge here.\n- `companion/src/` holds the desktop UI, while `companion/src-tauri/` holds the Rust backend, local API, and deep-link handling.\n## Where to Look First for Common Changes\n\n- Browser workflow change: start in `frontend/`, then confirm the backend or companion contract the UI depends on.\n- SMB behavior change: start in `backend/`, then validate the frontend behavior that consumes it.\n- Native-app editing or local-drive change: start in `companion/`, then review the related browser and backend contract.\n\n## What Not to Do\n\n- Do not treat the repo as three isolated apps. Many changes cross backend, frontend, and companion boundaries.\n- Do not assume lockfiles, version metadata, or generated files are incidental. Several workflows rely on them as reviewed source.\n\nIf you know which area you need, continue to [Local Development Workflow](../../local-development-workflow/) or jump directly to the relevant architecture section.\n", "0.8": "+++\ntitle = \"Repository Tour\"\n+++\n\nThis repository is organized around product boundaries, not just programming languages.\n\n## Top-Level Areas\n\n| Path | What it contains | Start here when |\n|---|---|---|\n| `backend/` | FastAPI application, models, services, storage code, and backend tests | you are changing API behavior, SMB handling, server-side validation, or edit-lock behavior |\n| `frontend/` | React browser app, UI components, pages, hooks, services, and browser-side tests | you are changing the main web UI or browser behavior |\n| `companion/` | Tauri desktop app with Preact UI and Rust backend | you are changing local-drive access, native-app editing, pairing, or desktop-side behavior |\n| `scripts/` | repo-level helper scripts for dev services, tests, version sync, and setup | you need the supported workflow instead of an ad hoc command |\n\n## Important Root Files\n\nThese files shape contributor workflows even though they are not feature code.\n\n| Path | Why it matters |\n|---|---|\n| `VERSION` | single source of truth for the current release identifier |\n| `config.example.toml` | starting point for local configuration |\n| `config.toml` | active local configuration in development or deployment |\n| `README.md` | high-level product framing |\n| `AGENTS.md` | repository-specific working rules for this environment |\n| `biome.json` | shared formatting and lint configuration for JavaScript and TypeScript work |\n\n## Product-Specific Notes\n\n- `backend/app/` is where the service code lives. Use it when the browser depends on server behavior or when SMB behavior changes.\n- `backend/tests/` holds the backend validation layer. Keep it close to backend behavior changes.\n- `frontend/src/` is the main browser app surface. Pages, services, and UI contracts all converge here.\n- `companion/src/` holds the desktop UI, while `companion/src-tauri/` holds the Rust backend, local API, and deep-link handling.\n## Where to Look First for Common Changes\n\n- Browser workflow change: start in `frontend/`, then confirm the backend or companion contract the UI depends on.\n- SMB behavior change: start in `backend/`, then validate the frontend behavior that consumes it.\n- Native-app editing or local-drive change: start in `companion/`, then review the related browser and backend contract.\n\n## What Not to Do\n\n- Do not treat the repo as three isolated apps. Many changes cross backend, frontend, and companion boundaries.\n- Do not assume lockfiles, version metadata, or generated files are incidental. Several workflows rely on them as reviewed source.\n\nIf you know which area you need, continue to [Local Development Workflow](../../local-development-workflow/) or jump directly to the relevant architecture section.\n", "0.9": "+++\ntitle = \"Repository Tour\"\n+++\n\nThis repository is organized around product boundaries, not just programming languages.\n\n## Top-Level Areas\n\n| Path | What it contains | Start here when |\n|---|---|---|\n| `backend/` | FastAPI application, models, services, storage code, and backend tests | you are changing API behavior, SMB handling, server-side validation, or edit-lock behavior |\n| `frontend/` | React browser app, UI components, pages, hooks, services, and browser-side tests | you are changing the main web UI or browser behavior |\n| `companion/` | Tauri desktop app with Preact UI and Rust backend | you are changing local-drive access, native-app editing, pairing, or desktop-side behavior |\n| `scripts/` | repo-level helper scripts for dev services, tests, version sync, and setup | you need the supported workflow instead of an ad hoc command |\n\n## Important Root Files\n\nThese files shape contributor workflows even though they are not feature code.\n\n| Path | Why it matters |\n|---|---|\n| `VERSION` | single source of truth for the current release identifier |\n| `config.example.toml` | starting point for local configuration |\n| `config.toml` | active local configuration in development or deployment |\n| `README.md` | high-level product framing |\n| `AGENTS.md` | repository-specific working rules for this environment |\n| `biome.json` | shared formatting and lint configuration for JavaScript and TypeScript work |\n\n## Product-Specific Notes\n\n- `backend/app/` is where the service code lives. Use it when the browser depends on server behavior or when SMB behavior changes.\n- `backend/tests/` holds the backend validation layer. Keep it close to backend behavior changes.\n- `frontend/src/` is the main browser app surface. Pages, services, and UI contracts all converge here.\n- `companion/src/` holds the desktop UI, while `companion/src-tauri/` holds the Rust backend, local API, and deep-link handling.\n## Where to Look First for Common Changes\n\n- Browser workflow change: start in `frontend/`, then confirm the backend or companion contract the UI depends on.\n- SMB behavior change: start in `backend/`, then validate the frontend behavior that consumes it.\n- Native-app editing or local-drive change: start in `companion/`, then review the related browser and backend contract.\n\n## What Not to Do\n\n- Do not treat the repo as three isolated apps. Many changes cross backend, frontend, and companion boundaries.\n- Do not assume lockfiles, version metadata, or generated files are incidental. Several workflows rely on them as reviewed source.\n\nIf you know which area you need, continue to [Local Development Workflow](../../local-development-workflow/) or jump directly to the relevant architecture section.\n", "1.0": "+++\ntitle = \"Repository Tour\"\n+++\n\nThis repository is organized around product boundaries, not just programming languages.\n\n## Top-Level Areas\n\n| Path | What it contains | Start here when |\n|---|---|---|\n| `backend/` | FastAPI application, models, services, storage code, and backend tests | you are changing API behavior, SMB handling, server-side validation, or edit-lock behavior |\n| `frontend/` | React browser app, UI components, pages, hooks, services, and browser-side tests | you are changing the main web UI or browser behavior |\n| `companion/` | Tauri desktop app with Preact UI and Rust backend | you are changing local-drive access, native-app editing, pairing, or desktop-side behavior |\n| `scripts/` | repo-level helper scripts for dev services, tests, version sync, and setup | you need the supported workflow instead of an ad hoc command |\n\n## Important Root Files\n\nThese files shape contributor workflows even though they are not feature code.\n\n| Path | Why it matters |\n|---|---|\n| `VERSION` | single source of truth for the current release identifier |\n| `config.example.toml` | starting point for local configuration |\n| `config.toml` | active local configuration in development or deployment |\n| `README.md` | high-level product framing |\n| `AGENTS.md` | repository-specific working rules for this environment |\n| `biome.json` | shared formatting and lint configuration for JavaScript and TypeScript work |\n\n## Product-Specific Notes\n\n- `backend/app/` is where the service code lives. Use it when the browser depends on server behavior or when SMB behavior changes.\n- `backend/tests/` holds the backend validation layer. Keep it close to backend behavior changes.\n- `frontend/src/` is the main browser app surface. Pages, services, and UI contracts all converge here.\n- `companion/src/` holds the desktop UI, while `companion/src-tauri/` holds the Rust backend, local API, and deep-link handling.\n## Where to Look First for Common Changes\n\n- Browser workflow change: start in `frontend/`, then confirm the backend or companion contract the UI depends on.\n- SMB behavior change: start in `backend/`, then validate the frontend behavior that consumes it.\n- Native-app editing or local-drive change: start in `companion/`, then review the related browser and backend contract.\n\n## What Not to Do\n\n- Do not treat the repo as three isolated apps. Many changes cross backend, frontend, and companion boundaries.\n- Do not assume lockfiles, version metadata, or generated files are incidental. Several workflows rely on them as reviewed source.\n\nIf you know which area you need, continue to [Local Development Workflow](../../local-development-workflow/) or jump directly to the relevant architecture section.\n", "2.0": "+++\ntitle = \"Repository Tour\"\n+++\n\nThis repository is organized around product boundaries, not just programming languages.\n\n## Top-Level Areas\n\n| Path | What it contains | Start here when |\n|---|---|---|\n| `backend/` | FastAPI application, models, services, storage code, and backend tests | you are changing API behavior, SMB handling, server-side validation, or edit-lock behavior |\n| `frontend/` | React browser app, UI components, pages, hooks, services, and browser-side tests | you are changing the main web UI or browser behavior |\n| `companion/` | Tauri desktop app with Preact UI and Rust backend | you are changing local-drive access, native-app editing, pairing, or desktop-side behavior |\n| `scripts/` | repo-level helper scripts for dev services, tests, version sync, and setup | you need the supported workflow instead of an ad hoc command |\n\n## Important Root Files\n\nThese files shape contributor workflows even though they are not feature code.\n\n| Path | Why it matters |\n|---|---|\n| `VERSION` | single source of truth for the current release identifier |\n| `config.example.toml` | starting point for local configuration |\n| `config.toml` | active local configuration in development or deployment |\n| `README.md` | high-level product framing |\n| `AGENTS.md` | repository-specific working rules for this environment |\n| `biome.json` | shared formatting and lint configuration for JavaScript and TypeScript work |\n\n## Product-Specific Notes\n\n- `backend/app/` is where the service code lives. Use it when the browser depends on server behavior or when SMB behavior changes.\n- `backend/tests/` holds the backend validation layer. Keep it close to backend behavior changes.\n- `frontend/src/` is the main browser app surface. Pages, services, and UI contracts all converge here.\n- `companion/src/` holds the desktop UI, while `companion/src-tauri/` holds the Rust backend, local API, and deep-link handling.\n## Where to Look First for Common Changes\n\n- Browser workflow change: start in `frontend/`, then confirm the backend or companion contract the UI depends on.\n- SMB behavior change: start in `backend/`, then validate the frontend behavior that consumes it.\n- Native-app editing or local-drive change: start in `companion/`, then review the related browser and backend contract.\n\n## What Not to Do\n\n- Do not treat the repo as three isolated apps. Many changes cross backend, frontend, and companion boundaries.\n- Do not assume lockfiles, version metadata, or generated files are incidental. Several workflows rely on them as reviewed source.\n\nIf you know which area you need, continue to [Local Development Workflow](../../local-development-workflow/) or jump directly to the relevant architecture section.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:developer-guide/local-development-workflow", "parent_id": "book:developer-guide", "depth": 1, "kind": "section", "label": "local-development-workflow", "title": "Local Development Workflow", "path": "developer-guide/local-development-workflow", "has_children": true, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Local Development Workflow\"\n+++\n\nThis section is the contributor entry point for getting Sambee running locally and validating your changes.\n\nStart with:\n\n- [Set up the Development Environment](./set-up-the-development-environment/)\n- [Common Task Commands](./common-task-commands/)\n\nIf you already have the repo running locally and want subsystem context, continue to [Backend Architecture](../backend-architecture/), [Frontend Architecture](../frontend-architecture/), or [Companion Architecture](../companion-architecture/).\n", "0.8": "+++\ntitle = \"Local Development Workflow\"\n+++\n\nThis section is the contributor entry point for getting Sambee running locally and validating your changes.\n\nStart with:\n\n- [Set up the Development Environment](./set-up-the-development-environment/)\n- [Common Task Commands](./common-task-commands/)\n\nIf you already have the repo running locally and want subsystem context, continue to [Backend Architecture](../backend-architecture/), [Frontend Architecture](../frontend-architecture/), or [Companion Architecture](../companion-architecture/).\n", "0.9": "+++\ntitle = \"Local Development Workflow\"\n+++\n\nThis section is the contributor entry point for getting Sambee running locally and validating your changes.\n\nStart with:\n\n- [Set up the Development Environment](./set-up-the-development-environment/)\n- [Common Task Commands](./common-task-commands/)\n\nIf you already have the repo running locally and want subsystem context, continue to [Backend Architecture](../backend-architecture/), [Frontend Architecture](../frontend-architecture/), or [Companion Architecture](../companion-architecture/).\n", "1.0": "+++\ntitle = \"Local Development Workflow\"\n+++\n\nThis section is the contributor entry point for getting Sambee running locally and validating your changes.\n\nStart with:\n\n- [Set up the Development Environment](./set-up-the-development-environment/)\n- [Common Task Commands](./common-task-commands/)\n\nIf you already have the repo running locally and want subsystem context, continue to [Backend Architecture](../backend-architecture/), [Frontend Architecture](../frontend-architecture/), or [Companion Architecture](../companion-architecture/).\n", "2.0": "+++\ntitle = \"Local Development Workflow\"\n+++\n\nThis section is the contributor entry point for getting Sambee running locally and validating your changes.\n\nStart with:\n\n- [Set up the Development Environment](./set-up-the-development-environment/)\n- [Common Task Commands](./common-task-commands/)\n\nIf you already have the repo running locally and want subsystem context, continue to [Backend Architecture](../backend-architecture/), [Frontend Architecture](../frontend-architecture/), or [Companion Architecture](../companion-architecture/).\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/local-development-workflow/set-up-the-development-environment", "parent_id": "section:developer-guide/local-development-workflow", "depth": 2, "kind": "page", "label": "set-up-the-development-environment", "title": "Set Up The Development Environment", "path": "developer-guide/local-development-workflow/set-up-the-development-environment", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "branched", "source_version": "0.7", "diff_added": 7, "diff_removed": 0}, "0.9": {"state": "branched", "source_version": "0.8", "diff_added": 13, "diff_removed": 2}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "inherited", "source_version": "0.9"}}, "content_versions": {"0.7": "+++\ntitle = \"Set up the Development Environment\"\n+++\n\nThe supported contributor path is the repository dev container.\n\n## Preferred Setup Path\n\nThe project is designed to be opened in VS Code with Dev Containers.\n\nBaseline assumptions from the maintained setup:\n\n- Python is pinned to the reviewed `3.13.12` baseline.\n- Node and npm are available for frontend and companion work.\n- Rust tooling is available for companion development.\n- post-create setup installs reviewed dependencies, initializes local state, and prepares default config where needed.\n\n## First-Time Setup\n\n1. Open the repository in VS Code.\n2. Reopen in the dev container when prompted.\n3. Let the post-create setup complete.\n\nThe standard setup performs these tasks automatically:\n\n- configures Git hooks used by the repository workflow\n- installs backend dependencies from the hashed lockfiles\n- installs Node dependencies from the committed lockfiles\n- installs `pip-audit` and `cargo-audit` at the pinned versions used in CI\n- initializes the local database\n- creates a default `config.toml` if one is missing\n\nThe Git-hook setup matters more than it first appears.\n\n- the repo uses hooks from `.githooks/`\n- those hooks keep `GIT_COMMIT` aligned after commits and checkouts\n- they preserve the repository's Git LFS hook integration\n- they block pushes of `wip/*` branches\n\nIf you work outside the dev container, run:\n\n```bash\n./scripts/setup-git-hooks\n```\n\n## Local Service URLs\n\nIn the standard development setup, the main services are:\n\n- frontend: `http://localhost:3000`\n- backend: `http://localhost:8000`\n\nThe backend and frontend dev servers are usually started automatically by the workspace tasks.\n\n## Dependency Trust Rules\n\nContributors are expected to use the reviewed dependency workflow rather than ad hoc installs.\n\n- use `npm ci` in `frontend/`, `companion/`, and `website/` for routine installs\n- use the backend lockfile workflow instead of floating Python installs\n- treat `requirements*.txt`, lockfiles, and version metadata as reviewed source, not disposable setup noise\n- keep Tauri JavaScript packages and Rust crates aligned when companion dependencies move\n- treat Python runtime upgrades and high-risk frontend ecosystem upgrades as coordinated manual changes\n\n## Configuration Expectations\n\nLocal development depends on configuration, but the repo is designed to create a sane default local configuration automatically.\n\n- `config.example.toml` is the template\n- `config.toml` is the active local configuration\n- the backend startup workflow creates a default config with secure keys if one is missing\n\nDo not assume production deployment rules and local development rules are identical. The Admin Guide covers deployment-specific setup.\n\n## When to Leave the Happy Path\n\nUse the default container-based workflow unless you have a specific reason not to.\n\n- If your issue is environment-specific, fix the supported workflow first.\n- If you change tooling or dependencies, expect to update the corresponding reviewed inputs and rerun the relevant validation commands.\n- If you change version metadata, treat `VERSION` and the sync workflow as part of the change.\n\n## Common Setup Failures\n\nIf startup fails immediately after opening the dev container, start with the supported workflow rather than ad hoc fixes.\n\nCommon cases:\n\n- missing `config.toml`: the backend startup workflow should create a default config automatically\n- frontend `vite: not found` or `node_modules` permission failures: remove the broken install and rerun `npm ci` in `frontend/`\n- service startup confusion: backend and frontend dev servers are usually started by workspace tasks, so check task state before assuming the app itself is broken\n\nOnce the environment is ready, continue to [Common Task Commands](../common-task-commands/).\n", "0.8": "+++\ntitle = \"Set up the Development Environment\"\n+++\n\nThe supported contributor path is the repository dev container.\n\n## Preferred Setup Path\n\nThe project is designed to be opened in VS Code with Dev Containers.\n\nBaseline assumptions from the maintained setup:\n\n- Python is pinned to the reviewed `3.13.12` baseline.\n- Node and npm are available for frontend and companion work.\n- Rust tooling is available for companion development.\n- post-create setup installs reviewed dependencies, initializes local state, and prepares default config where needed.\n\n## First-Time Setup\n\n1. Open the repository in VS Code.\n2. Reopen in the dev container when prompted.\n3. Let the post-create setup complete.\n\nThe standard setup performs these tasks automatically:\n\n- configures Git hooks used by the repository workflow\n- installs backend dependencies from the hashed lockfiles\n- installs Node dependencies from the committed lockfiles\n- installs `pip-audit` and `cargo-audit` at the pinned versions used in CI\n- initializes the local database\n- creates a default `config.toml` if one is missing\n\nThe Git-hook setup matters more than it first appears.\n\n- the repo uses hooks from `.githooks/`\n- those hooks keep `GIT_COMMIT` aligned after commits and checkouts\n- they preserve the repository's Git LFS hook integration\n- they block pushes of `wip/*` branches\n- they refresh the committed docs structure report automatically when staged docs inputs affect it\n\nIf you work outside the dev container, run:\n\n```bash\n./scripts/setup-git-hooks\n```\n\nWhen you want to refresh docs-derived artifacts manually, use the workspace task `Website: Refresh Docs Derived Artifacts` or run:\n\n```bash\npython3 scripts/update-docs-derived-artifacts.py\n```\n\n## Local Service URLs\n\nIn the standard development setup, the main services are:\n\n- frontend: `http://localhost:3000`\n- backend: `http://localhost:8000`\n\nThe backend and frontend dev servers are usually started automatically by the workspace tasks.\n\n## Dependency Trust Rules\n\nContributors are expected to use the reviewed dependency workflow rather than ad hoc installs.\n\n- use `npm ci` in `frontend/`, `companion/`, and `website/` for routine installs\n- use the backend lockfile workflow instead of floating Python installs\n- treat `requirements*.txt`, lockfiles, and version metadata as reviewed source, not disposable setup noise\n- keep Tauri JavaScript packages and Rust crates aligned when companion dependencies move\n- treat Python runtime upgrades and high-risk frontend ecosystem upgrades as coordinated manual changes\n\n## Configuration Expectations\n\nLocal development depends on configuration, but the repo is designed to create a sane default local configuration automatically.\n\n- `config.example.toml` is the template\n- `config.toml` is the active local configuration\n- the backend startup workflow creates a default config with secure keys if one is missing\n\nDo not assume production deployment rules and local development rules are identical. The Admin Guide covers deployment-specific setup.\n\n## When to Leave the Happy Path\n\nUse the default container-based workflow unless you have a specific reason not to.\n\n- If your issue is environment-specific, fix the supported workflow first.\n- If you change tooling or dependencies, expect to update the corresponding reviewed inputs and rerun the relevant validation commands.\n- If you change version metadata, treat `VERSION` and the sync workflow as part of the change.\n\n## Common Setup Failures\n\nIf startup fails immediately after opening the dev container, start with the supported workflow rather than ad hoc fixes.\n\nCommon cases:\n\n- missing `config.toml`: the backend startup workflow should create a default config automatically\n- frontend `vite: not found` or `node_modules` permission failures: remove the broken install and rerun `npm ci` in `frontend/`\n- service startup confusion: backend and frontend dev servers are usually started by workspace tasks, so check task state before assuming the app itself is broken\n\nOnce the environment is ready, continue to [Common Task Commands](../common-task-commands/).", "0.9": "+++\ntitle = \"Set up the Development Environment\"\n+++\n\nThe supported contributor path is the repository dev container.\n\n## Preferred Setup Path\n\nThe project is designed to be opened in VS Code with Dev Containers.\n\nBaseline assumptions from the maintained setup:\n\n- The dev container and production image inherit the same pinned Python runtime base from the root `Dockerfile`.\n- Node and npm are available for frontend and companion work.\n- Rust tooling is available for companion development.\n- post-create setup installs reviewed dependencies, initializes local state, and prepares default config where needed.\n\n### Runtime Package Refreshes\n\nThe shared runtime base refreshes Debian packages, including SQLite, before it installs the runtime dependencies. Production and CI image builds use a unique refresh key, so each build checks the current Debian packages instead of reusing a cached package-upgrade layer.\n\nLocal Dev Containers can reuse Docker's build cache. Use **Dev Containers: Rebuild Container Without Cache** when you need the current available Debian packages locally. The runtime's Python, SQLite module, and `libsqlite3-0` package versions are reported by Docker image validation in CI.\n\nIndependent builds made on different days can resolve different Debian security updates. This is intentional: the shared base controls the package policy and Python runtime, while regular rebuilds keep native packages current without maintaining a separate internal base-image release process.\n\n## First-Time Setup\n\n1. Open the repository in VS Code.\n2. Reopen in the dev container when prompted.\n3. Let the post-create setup complete.\n\nThe standard setup performs these tasks automatically:\n\n- configures Git hooks used by the repository workflow\n- installs backend dependencies from the hashed lockfiles\n- installs Node dependencies from the committed lockfiles\n- installs `pip-audit` and `cargo-audit` at the pinned versions used in CI\n- initializes the local database\n- creates a default `config.toml` if one is missing\n\nBackend tools run from `backend/.venv`. VS Code selects that interpreter, and the backend workspace tasks use it explicitly. Use `backend/.venv/bin/python -m \u003ctool\u003e` for manual backend commands.\n\nThe Git-hook setup matters more than it first appears.\n\n- the repo uses hooks from `.githooks/`\n- those hooks keep `GIT_COMMIT` aligned after commits and checkouts\n- they preserve the repository's Git LFS hook integration\n- they block pushes of `wip/*` branches\n- they refresh the committed docs structure report automatically when staged docs inputs affect it\n\nIf you work outside the dev container, run:\n\n```bash\n./scripts/setup-git-hooks\n```\n\nWhen you want to refresh docs-derived artifacts manually, use the workspace task `Website: Refresh Docs Derived Artifacts` or run:\n\n```bash\npython3 scripts/update-docs-derived-artifacts.py\n```\n\n## Local Service URLs\n\nIn the standard development setup, the main services are:\n\n- frontend: `http://localhost:3000`\n- backend: `http://localhost:8000`\n\nThe backend and frontend dev servers are usually started automatically by the workspace tasks.\n\n## Dependency Trust Rules\n\nContributors are expected to use the reviewed dependency workflow rather than ad hoc installs.\n\n- use `npm ci` in `frontend/`, `companion/`, and `website/` for routine installs\n- use the backend lockfile workflow instead of floating Python installs\n- treat `requirements*.txt`, lockfiles, and version metadata as reviewed source, not disposable setup noise\n- keep Tauri JavaScript packages and Rust crates aligned when companion dependencies move\n- review Dependabot Python runtime image updates with the Docker target validation results\n- treat high-risk frontend ecosystem upgrades as coordinated manual changes\n\n## Configuration Expectations\n\nLocal development depends on configuration, but the repo is designed to create a sane default local configuration automatically.\n\n- `config.example.toml` is the template\n- `config.toml` is the active local configuration\n- the backend startup workflow creates a default config with secure keys if one is missing\n\nDo not assume production deployment rules and local development rules are identical. The Admin Guide covers deployment-specific setup.\n\n## When to Leave the Happy Path\n\nUse the default container-based workflow unless you have a specific reason not to.\n\n- If your issue is environment-specific, fix the supported workflow first.\n- If you change tooling or dependencies, expect to update the corresponding reviewed inputs and rerun the relevant validation commands.\n- If you change version metadata, treat `VERSION` and the sync workflow as part of the change.\n\n## Common Setup Failures\n\nIf startup fails immediately after opening the dev container, start with the supported workflow rather than ad hoc fixes.\n\nCommon cases:\n\n- missing `config.toml`: the backend startup workflow should create a default config automatically\n- frontend `vite: not found` or `node_modules` permission failures: remove the broken install and rerun `npm ci` in `frontend/`\n- service startup confusion: backend and frontend dev servers are usually started by workspace tasks, so check task state before assuming the app itself is broken\n\nOnce the environment is ready, continue to [Common Task Commands](../common-task-commands/).\n", "1.0": "+++\ntitle = \"Set up the Development Environment\"\n+++\n\nThe supported contributor path is the repository dev container.\n\n## Preferred Setup Path\n\nThe project is designed to be opened in VS Code with Dev Containers.\n\nBaseline assumptions from the maintained setup:\n\n- The dev container and production image inherit the same pinned Python runtime base from the root `Dockerfile`.\n- Node and npm are available for frontend and companion work.\n- Rust tooling is available for companion development.\n- post-create setup installs reviewed dependencies, initializes local state, and prepares default config where needed.\n\n### Runtime Package Refreshes\n\nThe shared runtime base refreshes Debian packages, including SQLite, before it installs the runtime dependencies. Production and CI image builds use a unique refresh key, so each build checks the current Debian packages instead of reusing a cached package-upgrade layer.\n\nLocal Dev Containers can reuse Docker's build cache. Use **Dev Containers: Rebuild Container Without Cache** when you need the current available Debian packages locally. The runtime's Python, SQLite module, and `libsqlite3-0` package versions are reported by Docker image validation in CI.\n\nIndependent builds made on different days can resolve different Debian security updates. This is intentional: the shared base controls the package policy and Python runtime, while regular rebuilds keep native packages current without maintaining a separate internal base-image release process.\n\n## First-Time Setup\n\n1. Open the repository in VS Code.\n2. Reopen in the dev container when prompted.\n3. Let the post-create setup complete.\n\nThe standard setup performs these tasks automatically:\n\n- configures Git hooks used by the repository workflow\n- installs backend dependencies from the hashed lockfiles\n- installs Node dependencies from the committed lockfiles\n- installs `pip-audit` and `cargo-audit` at the pinned versions used in CI\n- initializes the local database\n- creates a default `config.toml` if one is missing\n\nBackend tools run from `backend/.venv`. VS Code selects that interpreter, and the backend workspace tasks use it explicitly. Use `backend/.venv/bin/python -m \u003ctool\u003e` for manual backend commands.\n\nThe Git-hook setup matters more than it first appears.\n\n- the repo uses hooks from `.githooks/`\n- those hooks keep `GIT_COMMIT` aligned after commits and checkouts\n- they preserve the repository's Git LFS hook integration\n- they block pushes of `wip/*` branches\n- they refresh the committed docs structure report automatically when staged docs inputs affect it\n\nIf you work outside the dev container, run:\n\n```bash\n./scripts/setup-git-hooks\n```\n\nWhen you want to refresh docs-derived artifacts manually, use the workspace task `Website: Refresh Docs Derived Artifacts` or run:\n\n```bash\npython3 scripts/update-docs-derived-artifacts.py\n```\n\n## Local Service URLs\n\nIn the standard development setup, the main services are:\n\n- frontend: `http://localhost:3000`\n- backend: `http://localhost:8000`\n\nThe backend and frontend dev servers are usually started automatically by the workspace tasks.\n\n## Dependency Trust Rules\n\nContributors are expected to use the reviewed dependency workflow rather than ad hoc installs.\n\n- use `npm ci` in `frontend/`, `companion/`, and `website/` for routine installs\n- use the backend lockfile workflow instead of floating Python installs\n- treat `requirements*.txt`, lockfiles, and version metadata as reviewed source, not disposable setup noise\n- keep Tauri JavaScript packages and Rust crates aligned when companion dependencies move\n- review Dependabot Python runtime image updates with the Docker target validation results\n- treat high-risk frontend ecosystem upgrades as coordinated manual changes\n\n## Configuration Expectations\n\nLocal development depends on configuration, but the repo is designed to create a sane default local configuration automatically.\n\n- `config.example.toml` is the template\n- `config.toml` is the active local configuration\n- the backend startup workflow creates a default config with secure keys if one is missing\n\nDo not assume production deployment rules and local development rules are identical. The Admin Guide covers deployment-specific setup.\n\n## When to Leave the Happy Path\n\nUse the default container-based workflow unless you have a specific reason not to.\n\n- If your issue is environment-specific, fix the supported workflow first.\n- If you change tooling or dependencies, expect to update the corresponding reviewed inputs and rerun the relevant validation commands.\n- If you change version metadata, treat `VERSION` and the sync workflow as part of the change.\n\n## Common Setup Failures\n\nIf startup fails immediately after opening the dev container, start with the supported workflow rather than ad hoc fixes.\n\nCommon cases:\n\n- missing `config.toml`: the backend startup workflow should create a default config automatically\n- frontend `vite: not found` or `node_modules` permission failures: remove the broken install and rerun `npm ci` in `frontend/`\n- service startup confusion: backend and frontend dev servers are usually started by workspace tasks, so check task state before assuming the app itself is broken\n\nOnce the environment is ready, continue to [Common Task Commands](../common-task-commands/).\n", "2.0": "+++\ntitle = \"Set up the Development Environment\"\n+++\n\nThe supported contributor path is the repository dev container.\n\n## Preferred Setup Path\n\nThe project is designed to be opened in VS Code with Dev Containers.\n\nBaseline assumptions from the maintained setup:\n\n- The dev container and production image inherit the same pinned Python runtime base from the root `Dockerfile`.\n- Node and npm are available for frontend and companion work.\n- Rust tooling is available for companion development.\n- post-create setup installs reviewed dependencies, initializes local state, and prepares default config where needed.\n\n### Runtime Package Refreshes\n\nThe shared runtime base refreshes Debian packages, including SQLite, before it installs the runtime dependencies. Production and CI image builds use a unique refresh key, so each build checks the current Debian packages instead of reusing a cached package-upgrade layer.\n\nLocal Dev Containers can reuse Docker's build cache. Use **Dev Containers: Rebuild Container Without Cache** when you need the current available Debian packages locally. The runtime's Python, SQLite module, and `libsqlite3-0` package versions are reported by Docker image validation in CI.\n\nIndependent builds made on different days can resolve different Debian security updates. This is intentional: the shared base controls the package policy and Python runtime, while regular rebuilds keep native packages current without maintaining a separate internal base-image release process.\n\n## First-Time Setup\n\n1. Open the repository in VS Code.\n2. Reopen in the dev container when prompted.\n3. Let the post-create setup complete.\n\nThe standard setup performs these tasks automatically:\n\n- configures Git hooks used by the repository workflow\n- installs backend dependencies from the hashed lockfiles\n- installs Node dependencies from the committed lockfiles\n- installs `pip-audit` and `cargo-audit` at the pinned versions used in CI\n- initializes the local database\n- creates a default `config.toml` if one is missing\n\nBackend tools run from `backend/.venv`. VS Code selects that interpreter, and the backend workspace tasks use it explicitly. Use `backend/.venv/bin/python -m \u003ctool\u003e` for manual backend commands.\n\nThe Git-hook setup matters more than it first appears.\n\n- the repo uses hooks from `.githooks/`\n- those hooks keep `GIT_COMMIT` aligned after commits and checkouts\n- they preserve the repository's Git LFS hook integration\n- they block pushes of `wip/*` branches\n- they refresh the committed docs structure report automatically when staged docs inputs affect it\n\nIf you work outside the dev container, run:\n\n```bash\n./scripts/setup-git-hooks\n```\n\nWhen you want to refresh docs-derived artifacts manually, use the workspace task `Website: Refresh Docs Derived Artifacts` or run:\n\n```bash\npython3 scripts/update-docs-derived-artifacts.py\n```\n\n## Local Service URLs\n\nIn the standard development setup, the main services are:\n\n- frontend: `http://localhost:3000`\n- backend: `http://localhost:8000`\n\nThe backend and frontend dev servers are usually started automatically by the workspace tasks.\n\n## Dependency Trust Rules\n\nContributors are expected to use the reviewed dependency workflow rather than ad hoc installs.\n\n- use `npm ci` in `frontend/`, `companion/`, and `website/` for routine installs\n- use the backend lockfile workflow instead of floating Python installs\n- treat `requirements*.txt`, lockfiles, and version metadata as reviewed source, not disposable setup noise\n- keep Tauri JavaScript packages and Rust crates aligned when companion dependencies move\n- review Dependabot Python runtime image updates with the Docker target validation results\n- treat high-risk frontend ecosystem upgrades as coordinated manual changes\n\n## Configuration Expectations\n\nLocal development depends on configuration, but the repo is designed to create a sane default local configuration automatically.\n\n- `config.example.toml` is the template\n- `config.toml` is the active local configuration\n- the backend startup workflow creates a default config with secure keys if one is missing\n\nDo not assume production deployment rules and local development rules are identical. The Admin Guide covers deployment-specific setup.\n\n## When to Leave the Happy Path\n\nUse the default container-based workflow unless you have a specific reason not to.\n\n- If your issue is environment-specific, fix the supported workflow first.\n- If you change tooling or dependencies, expect to update the corresponding reviewed inputs and rerun the relevant validation commands.\n- If you change version metadata, treat `VERSION` and the sync workflow as part of the change.\n\n## Common Setup Failures\n\nIf startup fails immediately after opening the dev container, start with the supported workflow rather than ad hoc fixes.\n\nCommon cases:\n\n- missing `config.toml`: the backend startup workflow should create a default config automatically\n- frontend `vite: not found` or `node_modules` permission failures: remove the broken install and rerun `npm ci` in `frontend/`\n- service startup confusion: backend and frontend dev servers are usually started by workspace tasks, so check task state before assuming the app itself is broken\n\nOnce the environment is ready, continue to [Common Task Commands](../common-task-commands/).\n"}, "page_contents": {"0.7": "+++\ntitle = \"Set up the Development Environment\"\n+++\n\nThe supported contributor path is the repository dev container.\n\n## Preferred Setup Path\n\nThe project is designed to be opened in VS Code with Dev Containers.\n\nBaseline assumptions from the maintained setup:\n\n- Python is pinned to the reviewed `3.13.12` baseline.\n- Node and npm are available for frontend and companion work.\n- Rust tooling is available for companion development.\n- post-create setup installs reviewed dependencies, initializes local state, and prepares default config where needed.\n\n## First-Time Setup\n\n1. Open the repository in VS Code.\n2. Reopen in the dev container when prompted.\n3. Let the post-create setup complete.\n\nThe standard setup performs these tasks automatically:\n\n- configures Git hooks used by the repository workflow\n- installs backend dependencies from the hashed lockfiles\n- installs Node dependencies from the committed lockfiles\n- installs `pip-audit` and `cargo-audit` at the pinned versions used in CI\n- initializes the local database\n- creates a default `config.toml` if one is missing\n\nThe Git-hook setup matters more than it first appears.\n\n- the repo uses hooks from `.githooks/`\n- those hooks keep `GIT_COMMIT` aligned after commits and checkouts\n- they preserve the repository's Git LFS hook integration\n- they block pushes of `wip/*` branches\n\nIf you work outside the dev container, run:\n\n```bash\n./scripts/setup-git-hooks\n```\n\n## Local Service URLs\n\nIn the standard development setup, the main services are:\n\n- frontend: `http://localhost:3000`\n- backend: `http://localhost:8000`\n\nThe backend and frontend dev servers are usually started automatically by the workspace tasks.\n\n## Dependency Trust Rules\n\nContributors are expected to use the reviewed dependency workflow rather than ad hoc installs.\n\n- use `npm ci` in `frontend/`, `companion/`, and `website/` for routine installs\n- use the backend lockfile workflow instead of floating Python installs\n- treat `requirements*.txt`, lockfiles, and version metadata as reviewed source, not disposable setup noise\n- keep Tauri JavaScript packages and Rust crates aligned when companion dependencies move\n- treat Python runtime upgrades and high-risk frontend ecosystem upgrades as coordinated manual changes\n\n## Configuration Expectations\n\nLocal development depends on configuration, but the repo is designed to create a sane default local configuration automatically.\n\n- `config.example.toml` is the template\n- `config.toml` is the active local configuration\n- the backend startup workflow creates a default config with secure keys if one is missing\n\nDo not assume production deployment rules and local development rules are identical. The Admin Guide covers deployment-specific setup.\n\n## When to Leave the Happy Path\n\nUse the default container-based workflow unless you have a specific reason not to.\n\n- If your issue is environment-specific, fix the supported workflow first.\n- If you change tooling or dependencies, expect to update the corresponding reviewed inputs and rerun the relevant validation commands.\n- If you change version metadata, treat `VERSION` and the sync workflow as part of the change.\n\n## Common Setup Failures\n\nIf startup fails immediately after opening the dev container, start with the supported workflow rather than ad hoc fixes.\n\nCommon cases:\n\n- missing `config.toml`: the backend startup workflow should create a default config automatically\n- frontend `vite: not found` or `node_modules` permission failures: remove the broken install and rerun `npm ci` in `frontend/`\n- service startup confusion: backend and frontend dev servers are usually started by workspace tasks, so check task state before assuming the app itself is broken\n\nOnce the environment is ready, continue to [Common Task Commands](../common-task-commands/).\n", "0.8": "+++\ntitle = \"Set up the Development Environment\"\n+++\n\nThe supported contributor path is the repository dev container.\n\n## Preferred Setup Path\n\nThe project is designed to be opened in VS Code with Dev Containers.\n\nBaseline assumptions from the maintained setup:\n\n- Python is pinned to the reviewed `3.13.12` baseline.\n- Node and npm are available for frontend and companion work.\n- Rust tooling is available for companion development.\n- post-create setup installs reviewed dependencies, initializes local state, and prepares default config where needed.\n\n## First-Time Setup\n\n1. Open the repository in VS Code.\n2. Reopen in the dev container when prompted.\n3. Let the post-create setup complete.\n\nThe standard setup performs these tasks automatically:\n\n- configures Git hooks used by the repository workflow\n- installs backend dependencies from the hashed lockfiles\n- installs Node dependencies from the committed lockfiles\n- installs `pip-audit` and `cargo-audit` at the pinned versions used in CI\n- initializes the local database\n- creates a default `config.toml` if one is missing\n\nThe Git-hook setup matters more than it first appears.\n\n- the repo uses hooks from `.githooks/`\n- those hooks keep `GIT_COMMIT` aligned after commits and checkouts\n- they preserve the repository's Git LFS hook integration\n- they block pushes of `wip/*` branches\n- they refresh the committed docs structure report automatically when staged docs inputs affect it\n\nIf you work outside the dev container, run:\n\n```bash\n./scripts/setup-git-hooks\n```\n\nWhen you want to refresh docs-derived artifacts manually, use the workspace task `Website: Refresh Docs Derived Artifacts` or run:\n\n```bash\npython3 scripts/update-docs-derived-artifacts.py\n```\n\n## Local Service URLs\n\nIn the standard development setup, the main services are:\n\n- frontend: `http://localhost:3000`\n- backend: `http://localhost:8000`\n\nThe backend and frontend dev servers are usually started automatically by the workspace tasks.\n\n## Dependency Trust Rules\n\nContributors are expected to use the reviewed dependency workflow rather than ad hoc installs.\n\n- use `npm ci` in `frontend/`, `companion/`, and `website/` for routine installs\n- use the backend lockfile workflow instead of floating Python installs\n- treat `requirements*.txt`, lockfiles, and version metadata as reviewed source, not disposable setup noise\n- keep Tauri JavaScript packages and Rust crates aligned when companion dependencies move\n- treat Python runtime upgrades and high-risk frontend ecosystem upgrades as coordinated manual changes\n\n## Configuration Expectations\n\nLocal development depends on configuration, but the repo is designed to create a sane default local configuration automatically.\n\n- `config.example.toml` is the template\n- `config.toml` is the active local configuration\n- the backend startup workflow creates a default config with secure keys if one is missing\n\nDo not assume production deployment rules and local development rules are identical. The Admin Guide covers deployment-specific setup.\n\n## When to Leave the Happy Path\n\nUse the default container-based workflow unless you have a specific reason not to.\n\n- If your issue is environment-specific, fix the supported workflow first.\n- If you change tooling or dependencies, expect to update the corresponding reviewed inputs and rerun the relevant validation commands.\n- If you change version metadata, treat `VERSION` and the sync workflow as part of the change.\n\n## Common Setup Failures\n\nIf startup fails immediately after opening the dev container, start with the supported workflow rather than ad hoc fixes.\n\nCommon cases:\n\n- missing `config.toml`: the backend startup workflow should create a default config automatically\n- frontend `vite: not found` or `node_modules` permission failures: remove the broken install and rerun `npm ci` in `frontend/`\n- service startup confusion: backend and frontend dev servers are usually started by workspace tasks, so check task state before assuming the app itself is broken\n\nOnce the environment is ready, continue to [Common Task Commands](../common-task-commands/).", "0.9": "+++\ntitle = \"Set up the Development Environment\"\n+++\n\nThe supported contributor path is the repository dev container.\n\n## Preferred Setup Path\n\nThe project is designed to be opened in VS Code with Dev Containers.\n\nBaseline assumptions from the maintained setup:\n\n- The dev container and production image inherit the same pinned Python runtime base from the root `Dockerfile`.\n- Node and npm are available for frontend and companion work.\n- Rust tooling is available for companion development.\n- post-create setup installs reviewed dependencies, initializes local state, and prepares default config where needed.\n\n### Runtime Package Refreshes\n\nThe shared runtime base refreshes Debian packages, including SQLite, before it installs the runtime dependencies. Production and CI image builds use a unique refresh key, so each build checks the current Debian packages instead of reusing a cached package-upgrade layer.\n\nLocal Dev Containers can reuse Docker's build cache. Use **Dev Containers: Rebuild Container Without Cache** when you need the current available Debian packages locally. The runtime's Python, SQLite module, and `libsqlite3-0` package versions are reported by Docker image validation in CI.\n\nIndependent builds made on different days can resolve different Debian security updates. This is intentional: the shared base controls the package policy and Python runtime, while regular rebuilds keep native packages current without maintaining a separate internal base-image release process.\n\n## First-Time Setup\n\n1. Open the repository in VS Code.\n2. Reopen in the dev container when prompted.\n3. Let the post-create setup complete.\n\nThe standard setup performs these tasks automatically:\n\n- configures Git hooks used by the repository workflow\n- installs backend dependencies from the hashed lockfiles\n- installs Node dependencies from the committed lockfiles\n- installs `pip-audit` and `cargo-audit` at the pinned versions used in CI\n- initializes the local database\n- creates a default `config.toml` if one is missing\n\nBackend tools run from `backend/.venv`. VS Code selects that interpreter, and the backend workspace tasks use it explicitly. Use `backend/.venv/bin/python -m \u003ctool\u003e` for manual backend commands.\n\nThe Git-hook setup matters more than it first appears.\n\n- the repo uses hooks from `.githooks/`\n- those hooks keep `GIT_COMMIT` aligned after commits and checkouts\n- they preserve the repository's Git LFS hook integration\n- they block pushes of `wip/*` branches\n- they refresh the committed docs structure report automatically when staged docs inputs affect it\n\nIf you work outside the dev container, run:\n\n```bash\n./scripts/setup-git-hooks\n```\n\nWhen you want to refresh docs-derived artifacts manually, use the workspace task `Website: Refresh Docs Derived Artifacts` or run:\n\n```bash\npython3 scripts/update-docs-derived-artifacts.py\n```\n\n## Local Service URLs\n\nIn the standard development setup, the main services are:\n\n- frontend: `http://localhost:3000`\n- backend: `http://localhost:8000`\n\nThe backend and frontend dev servers are usually started automatically by the workspace tasks.\n\n## Dependency Trust Rules\n\nContributors are expected to use the reviewed dependency workflow rather than ad hoc installs.\n\n- use `npm ci` in `frontend/`, `companion/`, and `website/` for routine installs\n- use the backend lockfile workflow instead of floating Python installs\n- treat `requirements*.txt`, lockfiles, and version metadata as reviewed source, not disposable setup noise\n- keep Tauri JavaScript packages and Rust crates aligned when companion dependencies move\n- review Dependabot Python runtime image updates with the Docker target validation results\n- treat high-risk frontend ecosystem upgrades as coordinated manual changes\n\n## Configuration Expectations\n\nLocal development depends on configuration, but the repo is designed to create a sane default local configuration automatically.\n\n- `config.example.toml` is the template\n- `config.toml` is the active local configuration\n- the backend startup workflow creates a default config with secure keys if one is missing\n\nDo not assume production deployment rules and local development rules are identical. The Admin Guide covers deployment-specific setup.\n\n## When to Leave the Happy Path\n\nUse the default container-based workflow unless you have a specific reason not to.\n\n- If your issue is environment-specific, fix the supported workflow first.\n- If you change tooling or dependencies, expect to update the corresponding reviewed inputs and rerun the relevant validation commands.\n- If you change version metadata, treat `VERSION` and the sync workflow as part of the change.\n\n## Common Setup Failures\n\nIf startup fails immediately after opening the dev container, start with the supported workflow rather than ad hoc fixes.\n\nCommon cases:\n\n- missing `config.toml`: the backend startup workflow should create a default config automatically\n- frontend `vite: not found` or `node_modules` permission failures: remove the broken install and rerun `npm ci` in `frontend/`\n- service startup confusion: backend and frontend dev servers are usually started by workspace tasks, so check task state before assuming the app itself is broken\n\nOnce the environment is ready, continue to [Common Task Commands](../common-task-commands/).\n", "1.0": "+++\ntitle = \"Set up the Development Environment\"\n+++\n\nThe supported contributor path is the repository dev container.\n\n## Preferred Setup Path\n\nThe project is designed to be opened in VS Code with Dev Containers.\n\nBaseline assumptions from the maintained setup:\n\n- The dev container and production image inherit the same pinned Python runtime base from the root `Dockerfile`.\n- Node and npm are available for frontend and companion work.\n- Rust tooling is available for companion development.\n- post-create setup installs reviewed dependencies, initializes local state, and prepares default config where needed.\n\n### Runtime Package Refreshes\n\nThe shared runtime base refreshes Debian packages, including SQLite, before it installs the runtime dependencies. Production and CI image builds use a unique refresh key, so each build checks the current Debian packages instead of reusing a cached package-upgrade layer.\n\nLocal Dev Containers can reuse Docker's build cache. Use **Dev Containers: Rebuild Container Without Cache** when you need the current available Debian packages locally. The runtime's Python, SQLite module, and `libsqlite3-0` package versions are reported by Docker image validation in CI.\n\nIndependent builds made on different days can resolve different Debian security updates. This is intentional: the shared base controls the package policy and Python runtime, while regular rebuilds keep native packages current without maintaining a separate internal base-image release process.\n\n## First-Time Setup\n\n1. Open the repository in VS Code.\n2. Reopen in the dev container when prompted.\n3. Let the post-create setup complete.\n\nThe standard setup performs these tasks automatically:\n\n- configures Git hooks used by the repository workflow\n- installs backend dependencies from the hashed lockfiles\n- installs Node dependencies from the committed lockfiles\n- installs `pip-audit` and `cargo-audit` at the pinned versions used in CI\n- initializes the local database\n- creates a default `config.toml` if one is missing\n\nBackend tools run from `backend/.venv`. VS Code selects that interpreter, and the backend workspace tasks use it explicitly. Use `backend/.venv/bin/python -m \u003ctool\u003e` for manual backend commands.\n\nThe Git-hook setup matters more than it first appears.\n\n- the repo uses hooks from `.githooks/`\n- those hooks keep `GIT_COMMIT` aligned after commits and checkouts\n- they preserve the repository's Git LFS hook integration\n- they block pushes of `wip/*` branches\n- they refresh the committed docs structure report automatically when staged docs inputs affect it\n\nIf you work outside the dev container, run:\n\n```bash\n./scripts/setup-git-hooks\n```\n\nWhen you want to refresh docs-derived artifacts manually, use the workspace task `Website: Refresh Docs Derived Artifacts` or run:\n\n```bash\npython3 scripts/update-docs-derived-artifacts.py\n```\n\n## Local Service URLs\n\nIn the standard development setup, the main services are:\n\n- frontend: `http://localhost:3000`\n- backend: `http://localhost:8000`\n\nThe backend and frontend dev servers are usually started automatically by the workspace tasks.\n\n## Dependency Trust Rules\n\nContributors are expected to use the reviewed dependency workflow rather than ad hoc installs.\n\n- use `npm ci` in `frontend/`, `companion/`, and `website/` for routine installs\n- use the backend lockfile workflow instead of floating Python installs\n- treat `requirements*.txt`, lockfiles, and version metadata as reviewed source, not disposable setup noise\n- keep Tauri JavaScript packages and Rust crates aligned when companion dependencies move\n- review Dependabot Python runtime image updates with the Docker target validation results\n- treat high-risk frontend ecosystem upgrades as coordinated manual changes\n\n## Configuration Expectations\n\nLocal development depends on configuration, but the repo is designed to create a sane default local configuration automatically.\n\n- `config.example.toml` is the template\n- `config.toml` is the active local configuration\n- the backend startup workflow creates a default config with secure keys if one is missing\n\nDo not assume production deployment rules and local development rules are identical. The Admin Guide covers deployment-specific setup.\n\n## When to Leave the Happy Path\n\nUse the default container-based workflow unless you have a specific reason not to.\n\n- If your issue is environment-specific, fix the supported workflow first.\n- If you change tooling or dependencies, expect to update the corresponding reviewed inputs and rerun the relevant validation commands.\n- If you change version metadata, treat `VERSION` and the sync workflow as part of the change.\n\n## Common Setup Failures\n\nIf startup fails immediately after opening the dev container, start with the supported workflow rather than ad hoc fixes.\n\nCommon cases:\n\n- missing `config.toml`: the backend startup workflow should create a default config automatically\n- frontend `vite: not found` or `node_modules` permission failures: remove the broken install and rerun `npm ci` in `frontend/`\n- service startup confusion: backend and frontend dev servers are usually started by workspace tasks, so check task state before assuming the app itself is broken\n\nOnce the environment is ready, continue to [Common Task Commands](../common-task-commands/).\n", "2.0": "+++\ntitle = \"Set up the Development Environment\"\n+++\n\nThe supported contributor path is the repository dev container.\n\n## Preferred Setup Path\n\nThe project is designed to be opened in VS Code with Dev Containers.\n\nBaseline assumptions from the maintained setup:\n\n- The dev container and production image inherit the same pinned Python runtime base from the root `Dockerfile`.\n- Node and npm are available for frontend and companion work.\n- Rust tooling is available for companion development.\n- post-create setup installs reviewed dependencies, initializes local state, and prepares default config where needed.\n\n### Runtime Package Refreshes\n\nThe shared runtime base refreshes Debian packages, including SQLite, before it installs the runtime dependencies. Production and CI image builds use a unique refresh key, so each build checks the current Debian packages instead of reusing a cached package-upgrade layer.\n\nLocal Dev Containers can reuse Docker's build cache. Use **Dev Containers: Rebuild Container Without Cache** when you need the current available Debian packages locally. The runtime's Python, SQLite module, and `libsqlite3-0` package versions are reported by Docker image validation in CI.\n\nIndependent builds made on different days can resolve different Debian security updates. This is intentional: the shared base controls the package policy and Python runtime, while regular rebuilds keep native packages current without maintaining a separate internal base-image release process.\n\n## First-Time Setup\n\n1. Open the repository in VS Code.\n2. Reopen in the dev container when prompted.\n3. Let the post-create setup complete.\n\nThe standard setup performs these tasks automatically:\n\n- configures Git hooks used by the repository workflow\n- installs backend dependencies from the hashed lockfiles\n- installs Node dependencies from the committed lockfiles\n- installs `pip-audit` and `cargo-audit` at the pinned versions used in CI\n- initializes the local database\n- creates a default `config.toml` if one is missing\n\nBackend tools run from `backend/.venv`. VS Code selects that interpreter, and the backend workspace tasks use it explicitly. Use `backend/.venv/bin/python -m \u003ctool\u003e` for manual backend commands.\n\nThe Git-hook setup matters more than it first appears.\n\n- the repo uses hooks from `.githooks/`\n- those hooks keep `GIT_COMMIT` aligned after commits and checkouts\n- they preserve the repository's Git LFS hook integration\n- they block pushes of `wip/*` branches\n- they refresh the committed docs structure report automatically when staged docs inputs affect it\n\nIf you work outside the dev container, run:\n\n```bash\n./scripts/setup-git-hooks\n```\n\nWhen you want to refresh docs-derived artifacts manually, use the workspace task `Website: Refresh Docs Derived Artifacts` or run:\n\n```bash\npython3 scripts/update-docs-derived-artifacts.py\n```\n\n## Local Service URLs\n\nIn the standard development setup, the main services are:\n\n- frontend: `http://localhost:3000`\n- backend: `http://localhost:8000`\n\nThe backend and frontend dev servers are usually started automatically by the workspace tasks.\n\n## Dependency Trust Rules\n\nContributors are expected to use the reviewed dependency workflow rather than ad hoc installs.\n\n- use `npm ci` in `frontend/`, `companion/`, and `website/` for routine installs\n- use the backend lockfile workflow instead of floating Python installs\n- treat `requirements*.txt`, lockfiles, and version metadata as reviewed source, not disposable setup noise\n- keep Tauri JavaScript packages and Rust crates aligned when companion dependencies move\n- review Dependabot Python runtime image updates with the Docker target validation results\n- treat high-risk frontend ecosystem upgrades as coordinated manual changes\n\n## Configuration Expectations\n\nLocal development depends on configuration, but the repo is designed to create a sane default local configuration automatically.\n\n- `config.example.toml` is the template\n- `config.toml` is the active local configuration\n- the backend startup workflow creates a default config with secure keys if one is missing\n\nDo not assume production deployment rules and local development rules are identical. The Admin Guide covers deployment-specific setup.\n\n## When to Leave the Happy Path\n\nUse the default container-based workflow unless you have a specific reason not to.\n\n- If your issue is environment-specific, fix the supported workflow first.\n- If you change tooling or dependencies, expect to update the corresponding reviewed inputs and rerun the relevant validation commands.\n- If you change version metadata, treat `VERSION` and the sync workflow as part of the change.\n\n## Common Setup Failures\n\nIf startup fails immediately after opening the dev container, start with the supported workflow rather than ad hoc fixes.\n\nCommon cases:\n\n- missing `config.toml`: the backend startup workflow should create a default config automatically\n- frontend `vite: not found` or `node_modules` permission failures: remove the broken install and rerun `npm ci` in `frontend/`\n- service startup confusion: backend and frontend dev servers are usually started by workspace tasks, so check task state before assuming the app itself is broken\n\nOnce the environment is ready, continue to [Common Task Commands](../common-task-commands/).\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/local-development-workflow/common-task-commands", "parent_id": "section:developer-guide/local-development-workflow", "depth": 2, "kind": "page", "label": "common-task-commands", "title": "Common Task Commands", "path": "developer-guide/local-development-workflow/common-task-commands", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "branched", "source_version": "0.7", "diff_added": 16, "diff_removed": 0}, "0.9": {"state": "inherited", "source_version": "0.8"}, "1.0": {"state": "inherited", "source_version": "0.8"}, "2.0": {"state": "inherited", "source_version": "0.8"}}, "content_versions": {"0.7": "+++\ntitle = \"Common Task Commands\"\n+++\n\nPrefer the committed scripts and workspace tasks over improvised one-off commands.\n\n## Daily Entry Points\n\n| Goal | Preferred command or task |\n|---|---|\n| Start backend dev server | VS Code task `Backend: Start Dev Server` or `./scripts/start-backend` |\n| Start frontend dev server | VS Code task `Frontend: Start Dev Server` or `./scripts/start-frontend` |\n| Start both local dev servers together | `./scripts/dev-start` |\n| Stop local dev servers together | `./scripts/dev-stop` |\n| Inspect local dev logs | `./scripts/logs` |\n| Run fast repo tests | `./scripts/test` |\n| Run repo tests with coverage | `COVERAGE=1 ./scripts/test` |\n\n## Backend Commands\n\nUse these when you are changing backend behavior, API contracts, or SMB handling.\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nUseful related task:\n\n- VS Code task `Backend: Run Tests`\n- VS Code task `Backend: Type Check (mypy)`\n\n## Frontend Commands\n\nUse these when the browser UI, routing, services, or typed frontend behavior changes.\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nUseful related task:\n\n- VS Code task `Frontend: Run Tests`\n- VS Code task `Frontend: Type Check + Lint`\n\n## Companion Commands\n\nUse these when local-drive access, native-app editing, or Tauri-side behavior changes.\n\n```bash\ncd companion \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nUseful related task:\n\n- VS Code task `Companion: Run Rust Tests`\n- VS Code task `Companion: Validation Suite`\n\n## Local Dev Logs and Service Control\n\nUse the committed helper scripts first when you are diagnosing the supported local development workflow.\n\n### Combined Dev Server Control\n\nThese scripts manage the local backend and frontend together:\n\n```bash\n./scripts/dev-start\n./scripts/dev-stop\n./scripts/dev-stop \u0026\u0026 ./scripts/dev-start\n```\n\nUse those entry points when you want the repo's own startup logging and local log-file layout instead of ad hoc process control.\n\n### Log Inspection\n\nThe supported local log viewer is:\n\n```bash\n./scripts/logs\n./scripts/logs -f\n./scripts/logs -n 200\n```\n\nThat script summarizes service status and tails the main local development log files.\n\nThe current local log files are:\n\n- `/tmp/backend.log`\n- `/tmp/frontend.log`\n- `/tmp/dev-start.log`\n- `/tmp/post-start.log`\n\nYou can inspect individual files directly when needed:\n\n```bash\ntail -f /tmp/backend.log\ntail -f /tmp/frontend.log\ntail -f /tmp/dev-start.log\ntail -f /tmp/post-start.log\n```\n\n### Search and Status Checks\n\nWhen the helper scripts are not enough, targeted shell checks are still useful.\n\n```bash\npgrep -f \"uvicorn.*app.main:app\"\npgrep -f \"vite\"\nlsof -i :3000,8000\ngrep -i error /tmp/*.log\ngrep -i warning /tmp/*.log\ngrep -i smb /tmp/backend.log\ngrep -E \"\\([0-9]{4,}\\.[0-9]+ms\\)\" /tmp/backend.log\n```\n\nTreat these as diagnostics for the local development environment, not as the primary supported control surface.\n\nBe especially careful with broad `pkill -f vite`-style commands in a workspace that can also run website or companion dev servers.\n\n### Rotating and Clearing Local Logs\n\nWhen local logs become noisy, use the committed rotation script first:\n\n```bash\n./scripts/rotate-logs\n```\n\nThat script archives current `/tmp/*.log` files into `/tmp/logs-archive/` and truncates the live files in place so active writers keep working.\n\nTo inspect archived logs:\n\n```bash\nls -lh /tmp/logs-archive/\n```\n\nManual truncation is still possible for local development, but it is a deliberately destructive cleanup step:\n\n```bash\n\u003e /tmp/backend.log\n\u003e /tmp/frontend.log\n\u003e /tmp/dev-start.log\n\u003e /tmp/post-start.log\n```\n\nUse that only when you intentionally want to discard the current local log history.\n\n### Practical Local Triage Order\n\nFor the supported dev workflow, a reasonable first pass is:\n\n1. run `./scripts/logs`\n2. verify the expected dev processes or ports if the summary looks wrong\n3. search `/tmp/*.log` for the concrete failure signal\n4. restart with `./scripts/dev-stop \u0026\u0026 ./scripts/dev-start` if the issue is clearly local-process state rather than a code defect\n\n## Version Sync\n\nWhen you change `VERSION`, run the sync script and review all resulting metadata changes together.\n\n```bash\n./scripts/sync-version\n```\n\nThat workflow updates the frontend and companion package metadata and related version-bearing files.\n\n## Command Selection Rule of Thumb\n\n- smallest relevant change: run the checks for the area you changed\n- cross-boundary change: run checks for every touched subsystem\n- dependency or versioning change: run the affected subsystem checks plus the sync workflow if `VERSION` changed\n\nFor the broader validation strategy and how to choose depth, continue to [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/).\n", "0.8": "+++\ntitle = \"Common Task Commands\"\n+++\n\nPrefer the committed scripts and workspace tasks over improvised one-off commands.\n\n## Daily Entry Points\n\n| Goal | Preferred command or task |\n|---|---|\n| Start backend dev server | VS Code task `Backend: Start Dev Server` or `./scripts/start-backend` |\n| Start frontend dev server | VS Code task `Frontend: Start Dev Server` or `./scripts/start-frontend` |\n| Start both local dev servers together | `./scripts/dev-start` |\n| Stop local dev servers together | `./scripts/dev-stop` |\n| Inspect local dev logs | `./scripts/logs` |\n| Run fast repo tests | `./scripts/test` |\n| Run repo tests with coverage | `COVERAGE=1 ./scripts/test` |\n\n`./scripts/test` now includes the companion Windows GNU target compatibility check when the local toolchain is available.\nIn the devcontainer, that toolchain is preinstalled as part of the image build.\n\n## Backend Commands\n\nUse these when you are changing backend behavior, API contracts, or SMB handling.\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nUseful related task:\n\n- VS Code task `Backend: Run Tests`\n- VS Code task `Backend: Type Check (mypy)`\n\n## Frontend Commands\n\nUse these when the browser UI, routing, services, or typed frontend behavior changes.\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nUseful related task:\n\n- VS Code task `Frontend: Run Tests`\n- VS Code task `Frontend: Type Check + Lint`\n\n## Companion Commands\n\nUse these when local-drive access, native-app editing, or Tauri-side behavior changes.\n\n```bash\ncd companion \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run check:rust:windows\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nUse `npm run check:rust:windows` as a local Windows-target compatibility check.\nIt runs `cargo check` for `x86_64-pc-windows-gnu` from Linux and is intended to catch cross-target breakage early without replacing the real Windows release build.\n\nUseful related task:\n\n- VS Code task `Companion: Run Rust Tests`\n- VS Code task `Companion: Validation Suite`\n\nThe committed devcontainer image now includes:\n\n- the Rust target `x86_64-pc-windows-gnu`\n- the MinGW toolchain package `gcc-mingw-w64-x86-64`\n\nThat means a rebuilt devcontainer can run the companion Windows GNU cross-check without extra manual setup.\n\n## Local Dev Logs and Service Control\n\nUse the committed helper scripts first when you are diagnosing the supported local development workflow.\n\n### Combined Dev Server Control\n\nThese scripts manage the local backend and frontend together:\n\n```bash\n./scripts/dev-start\n./scripts/dev-stop\n./scripts/dev-stop \u0026\u0026 ./scripts/dev-start\n```\n\nUse those entry points when you want the repo's own startup logging and local log-file layout instead of ad hoc process control.\n\n### Log Inspection\n\nThe supported local log viewer is:\n\n```bash\n./scripts/logs\n./scripts/logs -f\n./scripts/logs -n 200\n```\n\nThat script summarizes service status and tails the main local development log files.\n\nThe current local log files are:\n\n- `/tmp/backend.log`\n- `/tmp/frontend.log`\n- `/tmp/dev-start.log`\n- `/tmp/post-start.log`\n\nYou can inspect individual files directly when needed:\n\n```bash\ntail -f /tmp/backend.log\ntail -f /tmp/frontend.log\ntail -f /tmp/dev-start.log\ntail -f /tmp/post-start.log\n```\n\n### Search and Status Checks\n\nWhen the helper scripts are not enough, targeted shell checks are still useful.\n\n```bash\npgrep -f \"uvicorn.*app.main:app\"\npgrep -f \"vite\"\nlsof -i :3000,8000\ngrep -i error /tmp/*.log\ngrep -i warning /tmp/*.log\ngrep -i smb /tmp/backend.log\ngrep -E \"\\([0-9]{4,}\\.[0-9]+ms\\)\" /tmp/backend.log\n```\n\nTreat these as diagnostics for the local development environment, not as the primary supported control surface.\n\nBe especially careful with broad `pkill -f vite`-style commands in a workspace that can also run website or companion dev servers.\n\n### Rotating and Clearing Local Logs\n\nWhen local logs become noisy, use the committed rotation script first:\n\n```bash\n./scripts/rotate-logs\n```\n\nThat script archives current `/tmp/*.log` files into `/tmp/logs-archive/` and truncates the live files in place so active writers keep working.\n\nTo inspect archived logs:\n\n```bash\nls -lh /tmp/logs-archive/\n```\n\nManual truncation is still possible for local development, but it is a deliberately destructive cleanup step:\n\n```bash\n\u003e /tmp/backend.log\n\u003e /tmp/frontend.log\n\u003e /tmp/dev-start.log\n\u003e /tmp/post-start.log\n```\n\nUse that only when you intentionally want to discard the current local log history.\n\n### Practical Local Triage Order\n\nFor the supported dev workflow, a reasonable first pass is:\n\n1. run `./scripts/logs`\n2. verify the expected dev processes or ports if the summary looks wrong\n3. search `/tmp/*.log` for the concrete failure signal\n4. restart with `./scripts/dev-stop \u0026\u0026 ./scripts/dev-start` if the issue is clearly local-process state rather than a code defect\n\n## Version Sync\n\nWhen you change `VERSION`, run the sync script and review all resulting metadata changes together.\n\n```bash\n./scripts/sync-version\n```\n\nThat workflow updates the frontend and companion package metadata and related version-bearing files.\n\n## Command Selection Rule of Thumb\n\n- smallest relevant change: run the checks for the area you changed\n- cross-boundary change: run checks for every touched subsystem\n- dependency or versioning change: run the affected subsystem checks plus the sync workflow if `VERSION` changed\n\nFor companion-native changes that affect packaging, Windows-specific crates, or Tauri platform integration, include the Windows GNU cross-check in the local validation set even when you are not creating release artifacts.\n\nFor the broader validation strategy and how to choose depth, continue to [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/).\n", "0.9": "+++\ntitle = \"Common Task Commands\"\n+++\n\nPrefer the committed scripts and workspace tasks over improvised one-off commands.\n\n## Daily Entry Points\n\n| Goal | Preferred command or task |\n|---|---|\n| Start backend dev server | VS Code task `Backend: Start Dev Server` or `./scripts/start-backend` |\n| Start frontend dev server | VS Code task `Frontend: Start Dev Server` or `./scripts/start-frontend` |\n| Start both local dev servers together | `./scripts/dev-start` |\n| Stop local dev servers together | `./scripts/dev-stop` |\n| Inspect local dev logs | `./scripts/logs` |\n| Run fast repo tests | `./scripts/test` |\n| Run repo tests with coverage | `COVERAGE=1 ./scripts/test` |\n\n`./scripts/test` now includes the companion Windows GNU target compatibility check when the local toolchain is available.\nIn the devcontainer, that toolchain is preinstalled as part of the image build.\n\n## Backend Commands\n\nUse these when you are changing backend behavior, API contracts, or SMB handling.\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nUseful related task:\n\n- VS Code task `Backend: Run Tests`\n- VS Code task `Backend: Type Check (mypy)`\n\n## Frontend Commands\n\nUse these when the browser UI, routing, services, or typed frontend behavior changes.\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nUseful related task:\n\n- VS Code task `Frontend: Run Tests`\n- VS Code task `Frontend: Type Check + Lint`\n\n## Companion Commands\n\nUse these when local-drive access, native-app editing, or Tauri-side behavior changes.\n\n```bash\ncd companion \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run check:rust:windows\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nUse `npm run check:rust:windows` as a local Windows-target compatibility check.\nIt runs `cargo check` for `x86_64-pc-windows-gnu` from Linux and is intended to catch cross-target breakage early without replacing the real Windows release build.\n\nUseful related task:\n\n- VS Code task `Companion: Run Rust Tests`\n- VS Code task `Companion: Validation Suite`\n\nThe committed devcontainer image now includes:\n\n- the Rust target `x86_64-pc-windows-gnu`\n- the MinGW toolchain package `gcc-mingw-w64-x86-64`\n\nThat means a rebuilt devcontainer can run the companion Windows GNU cross-check without extra manual setup.\n\n## Local Dev Logs and Service Control\n\nUse the committed helper scripts first when you are diagnosing the supported local development workflow.\n\n### Combined Dev Server Control\n\nThese scripts manage the local backend and frontend together:\n\n```bash\n./scripts/dev-start\n./scripts/dev-stop\n./scripts/dev-stop \u0026\u0026 ./scripts/dev-start\n```\n\nUse those entry points when you want the repo's own startup logging and local log-file layout instead of ad hoc process control.\n\n### Log Inspection\n\nThe supported local log viewer is:\n\n```bash\n./scripts/logs\n./scripts/logs -f\n./scripts/logs -n 200\n```\n\nThat script summarizes service status and tails the main local development log files.\n\nThe current local log files are:\n\n- `/tmp/backend.log`\n- `/tmp/frontend.log`\n- `/tmp/dev-start.log`\n- `/tmp/post-start.log`\n\nYou can inspect individual files directly when needed:\n\n```bash\ntail -f /tmp/backend.log\ntail -f /tmp/frontend.log\ntail -f /tmp/dev-start.log\ntail -f /tmp/post-start.log\n```\n\n### Search and Status Checks\n\nWhen the helper scripts are not enough, targeted shell checks are still useful.\n\n```bash\npgrep -f \"uvicorn.*app.main:app\"\npgrep -f \"vite\"\nlsof -i :3000,8000\ngrep -i error /tmp/*.log\ngrep -i warning /tmp/*.log\ngrep -i smb /tmp/backend.log\ngrep -E \"\\([0-9]{4,}\\.[0-9]+ms\\)\" /tmp/backend.log\n```\n\nTreat these as diagnostics for the local development environment, not as the primary supported control surface.\n\nBe especially careful with broad `pkill -f vite`-style commands in a workspace that can also run website or companion dev servers.\n\n### Rotating and Clearing Local Logs\n\nWhen local logs become noisy, use the committed rotation script first:\n\n```bash\n./scripts/rotate-logs\n```\n\nThat script archives current `/tmp/*.log` files into `/tmp/logs-archive/` and truncates the live files in place so active writers keep working.\n\nTo inspect archived logs:\n\n```bash\nls -lh /tmp/logs-archive/\n```\n\nManual truncation is still possible for local development, but it is a deliberately destructive cleanup step:\n\n```bash\n\u003e /tmp/backend.log\n\u003e /tmp/frontend.log\n\u003e /tmp/dev-start.log\n\u003e /tmp/post-start.log\n```\n\nUse that only when you intentionally want to discard the current local log history.\n\n### Practical Local Triage Order\n\nFor the supported dev workflow, a reasonable first pass is:\n\n1. run `./scripts/logs`\n2. verify the expected dev processes or ports if the summary looks wrong\n3. search `/tmp/*.log` for the concrete failure signal\n4. restart with `./scripts/dev-stop \u0026\u0026 ./scripts/dev-start` if the issue is clearly local-process state rather than a code defect\n\n## Version Sync\n\nWhen you change `VERSION`, run the sync script and review all resulting metadata changes together.\n\n```bash\n./scripts/sync-version\n```\n\nThat workflow updates the frontend and companion package metadata and related version-bearing files.\n\n## Command Selection Rule of Thumb\n\n- smallest relevant change: run the checks for the area you changed\n- cross-boundary change: run checks for every touched subsystem\n- dependency or versioning change: run the affected subsystem checks plus the sync workflow if `VERSION` changed\n\nFor companion-native changes that affect packaging, Windows-specific crates, or Tauri platform integration, include the Windows GNU cross-check in the local validation set even when you are not creating release artifacts.\n\nFor the broader validation strategy and how to choose depth, continue to [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/).\n", "1.0": "+++\ntitle = \"Common Task Commands\"\n+++\n\nPrefer the committed scripts and workspace tasks over improvised one-off commands.\n\n## Daily Entry Points\n\n| Goal | Preferred command or task |\n|---|---|\n| Start backend dev server | VS Code task `Backend: Start Dev Server` or `./scripts/start-backend` |\n| Start frontend dev server | VS Code task `Frontend: Start Dev Server` or `./scripts/start-frontend` |\n| Start both local dev servers together | `./scripts/dev-start` |\n| Stop local dev servers together | `./scripts/dev-stop` |\n| Inspect local dev logs | `./scripts/logs` |\n| Run fast repo tests | `./scripts/test` |\n| Run repo tests with coverage | `COVERAGE=1 ./scripts/test` |\n\n`./scripts/test` now includes the companion Windows GNU target compatibility check when the local toolchain is available.\nIn the devcontainer, that toolchain is preinstalled as part of the image build.\n\n## Backend Commands\n\nUse these when you are changing backend behavior, API contracts, or SMB handling.\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nUseful related task:\n\n- VS Code task `Backend: Run Tests`\n- VS Code task `Backend: Type Check (mypy)`\n\n## Frontend Commands\n\nUse these when the browser UI, routing, services, or typed frontend behavior changes.\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nUseful related task:\n\n- VS Code task `Frontend: Run Tests`\n- VS Code task `Frontend: Type Check + Lint`\n\n## Companion Commands\n\nUse these when local-drive access, native-app editing, or Tauri-side behavior changes.\n\n```bash\ncd companion \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run check:rust:windows\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nUse `npm run check:rust:windows` as a local Windows-target compatibility check.\nIt runs `cargo check` for `x86_64-pc-windows-gnu` from Linux and is intended to catch cross-target breakage early without replacing the real Windows release build.\n\nUseful related task:\n\n- VS Code task `Companion: Run Rust Tests`\n- VS Code task `Companion: Validation Suite`\n\nThe committed devcontainer image now includes:\n\n- the Rust target `x86_64-pc-windows-gnu`\n- the MinGW toolchain package `gcc-mingw-w64-x86-64`\n\nThat means a rebuilt devcontainer can run the companion Windows GNU cross-check without extra manual setup.\n\n## Local Dev Logs and Service Control\n\nUse the committed helper scripts first when you are diagnosing the supported local development workflow.\n\n### Combined Dev Server Control\n\nThese scripts manage the local backend and frontend together:\n\n```bash\n./scripts/dev-start\n./scripts/dev-stop\n./scripts/dev-stop \u0026\u0026 ./scripts/dev-start\n```\n\nUse those entry points when you want the repo's own startup logging and local log-file layout instead of ad hoc process control.\n\n### Log Inspection\n\nThe supported local log viewer is:\n\n```bash\n./scripts/logs\n./scripts/logs -f\n./scripts/logs -n 200\n```\n\nThat script summarizes service status and tails the main local development log files.\n\nThe current local log files are:\n\n- `/tmp/backend.log`\n- `/tmp/frontend.log`\n- `/tmp/dev-start.log`\n- `/tmp/post-start.log`\n\nYou can inspect individual files directly when needed:\n\n```bash\ntail -f /tmp/backend.log\ntail -f /tmp/frontend.log\ntail -f /tmp/dev-start.log\ntail -f /tmp/post-start.log\n```\n\n### Search and Status Checks\n\nWhen the helper scripts are not enough, targeted shell checks are still useful.\n\n```bash\npgrep -f \"uvicorn.*app.main:app\"\npgrep -f \"vite\"\nlsof -i :3000,8000\ngrep -i error /tmp/*.log\ngrep -i warning /tmp/*.log\ngrep -i smb /tmp/backend.log\ngrep -E \"\\([0-9]{4,}\\.[0-9]+ms\\)\" /tmp/backend.log\n```\n\nTreat these as diagnostics for the local development environment, not as the primary supported control surface.\n\nBe especially careful with broad `pkill -f vite`-style commands in a workspace that can also run website or companion dev servers.\n\n### Rotating and Clearing Local Logs\n\nWhen local logs become noisy, use the committed rotation script first:\n\n```bash\n./scripts/rotate-logs\n```\n\nThat script archives current `/tmp/*.log` files into `/tmp/logs-archive/` and truncates the live files in place so active writers keep working.\n\nTo inspect archived logs:\n\n```bash\nls -lh /tmp/logs-archive/\n```\n\nManual truncation is still possible for local development, but it is a deliberately destructive cleanup step:\n\n```bash\n\u003e /tmp/backend.log\n\u003e /tmp/frontend.log\n\u003e /tmp/dev-start.log\n\u003e /tmp/post-start.log\n```\n\nUse that only when you intentionally want to discard the current local log history.\n\n### Practical Local Triage Order\n\nFor the supported dev workflow, a reasonable first pass is:\n\n1. run `./scripts/logs`\n2. verify the expected dev processes or ports if the summary looks wrong\n3. search `/tmp/*.log` for the concrete failure signal\n4. restart with `./scripts/dev-stop \u0026\u0026 ./scripts/dev-start` if the issue is clearly local-process state rather than a code defect\n\n## Version Sync\n\nWhen you change `VERSION`, run the sync script and review all resulting metadata changes together.\n\n```bash\n./scripts/sync-version\n```\n\nThat workflow updates the frontend and companion package metadata and related version-bearing files.\n\n## Command Selection Rule of Thumb\n\n- smallest relevant change: run the checks for the area you changed\n- cross-boundary change: run checks for every touched subsystem\n- dependency or versioning change: run the affected subsystem checks plus the sync workflow if `VERSION` changed\n\nFor companion-native changes that affect packaging, Windows-specific crates, or Tauri platform integration, include the Windows GNU cross-check in the local validation set even when you are not creating release artifacts.\n\nFor the broader validation strategy and how to choose depth, continue to [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/).\n", "2.0": "+++\ntitle = \"Common Task Commands\"\n+++\n\nPrefer the committed scripts and workspace tasks over improvised one-off commands.\n\n## Daily Entry Points\n\n| Goal | Preferred command or task |\n|---|---|\n| Start backend dev server | VS Code task `Backend: Start Dev Server` or `./scripts/start-backend` |\n| Start frontend dev server | VS Code task `Frontend: Start Dev Server` or `./scripts/start-frontend` |\n| Start both local dev servers together | `./scripts/dev-start` |\n| Stop local dev servers together | `./scripts/dev-stop` |\n| Inspect local dev logs | `./scripts/logs` |\n| Run fast repo tests | `./scripts/test` |\n| Run repo tests with coverage | `COVERAGE=1 ./scripts/test` |\n\n`./scripts/test` now includes the companion Windows GNU target compatibility check when the local toolchain is available.\nIn the devcontainer, that toolchain is preinstalled as part of the image build.\n\n## Backend Commands\n\nUse these when you are changing backend behavior, API contracts, or SMB handling.\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nUseful related task:\n\n- VS Code task `Backend: Run Tests`\n- VS Code task `Backend: Type Check (mypy)`\n\n## Frontend Commands\n\nUse these when the browser UI, routing, services, or typed frontend behavior changes.\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nUseful related task:\n\n- VS Code task `Frontend: Run Tests`\n- VS Code task `Frontend: Type Check + Lint`\n\n## Companion Commands\n\nUse these when local-drive access, native-app editing, or Tauri-side behavior changes.\n\n```bash\ncd companion \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run check:rust:windows\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nUse `npm run check:rust:windows` as a local Windows-target compatibility check.\nIt runs `cargo check` for `x86_64-pc-windows-gnu` from Linux and is intended to catch cross-target breakage early without replacing the real Windows release build.\n\nUseful related task:\n\n- VS Code task `Companion: Run Rust Tests`\n- VS Code task `Companion: Validation Suite`\n\nThe committed devcontainer image now includes:\n\n- the Rust target `x86_64-pc-windows-gnu`\n- the MinGW toolchain package `gcc-mingw-w64-x86-64`\n\nThat means a rebuilt devcontainer can run the companion Windows GNU cross-check without extra manual setup.\n\n## Local Dev Logs and Service Control\n\nUse the committed helper scripts first when you are diagnosing the supported local development workflow.\n\n### Combined Dev Server Control\n\nThese scripts manage the local backend and frontend together:\n\n```bash\n./scripts/dev-start\n./scripts/dev-stop\n./scripts/dev-stop \u0026\u0026 ./scripts/dev-start\n```\n\nUse those entry points when you want the repo's own startup logging and local log-file layout instead of ad hoc process control.\n\n### Log Inspection\n\nThe supported local log viewer is:\n\n```bash\n./scripts/logs\n./scripts/logs -f\n./scripts/logs -n 200\n```\n\nThat script summarizes service status and tails the main local development log files.\n\nThe current local log files are:\n\n- `/tmp/backend.log`\n- `/tmp/frontend.log`\n- `/tmp/dev-start.log`\n- `/tmp/post-start.log`\n\nYou can inspect individual files directly when needed:\n\n```bash\ntail -f /tmp/backend.log\ntail -f /tmp/frontend.log\ntail -f /tmp/dev-start.log\ntail -f /tmp/post-start.log\n```\n\n### Search and Status Checks\n\nWhen the helper scripts are not enough, targeted shell checks are still useful.\n\n```bash\npgrep -f \"uvicorn.*app.main:app\"\npgrep -f \"vite\"\nlsof -i :3000,8000\ngrep -i error /tmp/*.log\ngrep -i warning /tmp/*.log\ngrep -i smb /tmp/backend.log\ngrep -E \"\\([0-9]{4,}\\.[0-9]+ms\\)\" /tmp/backend.log\n```\n\nTreat these as diagnostics for the local development environment, not as the primary supported control surface.\n\nBe especially careful with broad `pkill -f vite`-style commands in a workspace that can also run website or companion dev servers.\n\n### Rotating and Clearing Local Logs\n\nWhen local logs become noisy, use the committed rotation script first:\n\n```bash\n./scripts/rotate-logs\n```\n\nThat script archives current `/tmp/*.log` files into `/tmp/logs-archive/` and truncates the live files in place so active writers keep working.\n\nTo inspect archived logs:\n\n```bash\nls -lh /tmp/logs-archive/\n```\n\nManual truncation is still possible for local development, but it is a deliberately destructive cleanup step:\n\n```bash\n\u003e /tmp/backend.log\n\u003e /tmp/frontend.log\n\u003e /tmp/dev-start.log\n\u003e /tmp/post-start.log\n```\n\nUse that only when you intentionally want to discard the current local log history.\n\n### Practical Local Triage Order\n\nFor the supported dev workflow, a reasonable first pass is:\n\n1. run `./scripts/logs`\n2. verify the expected dev processes or ports if the summary looks wrong\n3. search `/tmp/*.log` for the concrete failure signal\n4. restart with `./scripts/dev-stop \u0026\u0026 ./scripts/dev-start` if the issue is clearly local-process state rather than a code defect\n\n## Version Sync\n\nWhen you change `VERSION`, run the sync script and review all resulting metadata changes together.\n\n```bash\n./scripts/sync-version\n```\n\nThat workflow updates the frontend and companion package metadata and related version-bearing files.\n\n## Command Selection Rule of Thumb\n\n- smallest relevant change: run the checks for the area you changed\n- cross-boundary change: run checks for every touched subsystem\n- dependency or versioning change: run the affected subsystem checks plus the sync workflow if `VERSION` changed\n\nFor companion-native changes that affect packaging, Windows-specific crates, or Tauri platform integration, include the Windows GNU cross-check in the local validation set even when you are not creating release artifacts.\n\nFor the broader validation strategy and how to choose depth, continue to [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/).\n"}, "page_contents": {"0.7": "+++\ntitle = \"Common Task Commands\"\n+++\n\nPrefer the committed scripts and workspace tasks over improvised one-off commands.\n\n## Daily Entry Points\n\n| Goal | Preferred command or task |\n|---|---|\n| Start backend dev server | VS Code task `Backend: Start Dev Server` or `./scripts/start-backend` |\n| Start frontend dev server | VS Code task `Frontend: Start Dev Server` or `./scripts/start-frontend` |\n| Start both local dev servers together | `./scripts/dev-start` |\n| Stop local dev servers together | `./scripts/dev-stop` |\n| Inspect local dev logs | `./scripts/logs` |\n| Run fast repo tests | `./scripts/test` |\n| Run repo tests with coverage | `COVERAGE=1 ./scripts/test` |\n\n## Backend Commands\n\nUse these when you are changing backend behavior, API contracts, or SMB handling.\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nUseful related task:\n\n- VS Code task `Backend: Run Tests`\n- VS Code task `Backend: Type Check (mypy)`\n\n## Frontend Commands\n\nUse these when the browser UI, routing, services, or typed frontend behavior changes.\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nUseful related task:\n\n- VS Code task `Frontend: Run Tests`\n- VS Code task `Frontend: Type Check + Lint`\n\n## Companion Commands\n\nUse these when local-drive access, native-app editing, or Tauri-side behavior changes.\n\n```bash\ncd companion \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nUseful related task:\n\n- VS Code task `Companion: Run Rust Tests`\n- VS Code task `Companion: Validation Suite`\n\n## Local Dev Logs and Service Control\n\nUse the committed helper scripts first when you are diagnosing the supported local development workflow.\n\n### Combined Dev Server Control\n\nThese scripts manage the local backend and frontend together:\n\n```bash\n./scripts/dev-start\n./scripts/dev-stop\n./scripts/dev-stop \u0026\u0026 ./scripts/dev-start\n```\n\nUse those entry points when you want the repo's own startup logging and local log-file layout instead of ad hoc process control.\n\n### Log Inspection\n\nThe supported local log viewer is:\n\n```bash\n./scripts/logs\n./scripts/logs -f\n./scripts/logs -n 200\n```\n\nThat script summarizes service status and tails the main local development log files.\n\nThe current local log files are:\n\n- `/tmp/backend.log`\n- `/tmp/frontend.log`\n- `/tmp/dev-start.log`\n- `/tmp/post-start.log`\n\nYou can inspect individual files directly when needed:\n\n```bash\ntail -f /tmp/backend.log\ntail -f /tmp/frontend.log\ntail -f /tmp/dev-start.log\ntail -f /tmp/post-start.log\n```\n\n### Search and Status Checks\n\nWhen the helper scripts are not enough, targeted shell checks are still useful.\n\n```bash\npgrep -f \"uvicorn.*app.main:app\"\npgrep -f \"vite\"\nlsof -i :3000,8000\ngrep -i error /tmp/*.log\ngrep -i warning /tmp/*.log\ngrep -i smb /tmp/backend.log\ngrep -E \"\\([0-9]{4,}\\.[0-9]+ms\\)\" /tmp/backend.log\n```\n\nTreat these as diagnostics for the local development environment, not as the primary supported control surface.\n\nBe especially careful with broad `pkill -f vite`-style commands in a workspace that can also run website or companion dev servers.\n\n### Rotating and Clearing Local Logs\n\nWhen local logs become noisy, use the committed rotation script first:\n\n```bash\n./scripts/rotate-logs\n```\n\nThat script archives current `/tmp/*.log` files into `/tmp/logs-archive/` and truncates the live files in place so active writers keep working.\n\nTo inspect archived logs:\n\n```bash\nls -lh /tmp/logs-archive/\n```\n\nManual truncation is still possible for local development, but it is a deliberately destructive cleanup step:\n\n```bash\n\u003e /tmp/backend.log\n\u003e /tmp/frontend.log\n\u003e /tmp/dev-start.log\n\u003e /tmp/post-start.log\n```\n\nUse that only when you intentionally want to discard the current local log history.\n\n### Practical Local Triage Order\n\nFor the supported dev workflow, a reasonable first pass is:\n\n1. run `./scripts/logs`\n2. verify the expected dev processes or ports if the summary looks wrong\n3. search `/tmp/*.log` for the concrete failure signal\n4. restart with `./scripts/dev-stop \u0026\u0026 ./scripts/dev-start` if the issue is clearly local-process state rather than a code defect\n\n## Version Sync\n\nWhen you change `VERSION`, run the sync script and review all resulting metadata changes together.\n\n```bash\n./scripts/sync-version\n```\n\nThat workflow updates the frontend and companion package metadata and related version-bearing files.\n\n## Command Selection Rule of Thumb\n\n- smallest relevant change: run the checks for the area you changed\n- cross-boundary change: run checks for every touched subsystem\n- dependency or versioning change: run the affected subsystem checks plus the sync workflow if `VERSION` changed\n\nFor the broader validation strategy and how to choose depth, continue to [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/).\n", "0.8": "+++\ntitle = \"Common Task Commands\"\n+++\n\nPrefer the committed scripts and workspace tasks over improvised one-off commands.\n\n## Daily Entry Points\n\n| Goal | Preferred command or task |\n|---|---|\n| Start backend dev server | VS Code task `Backend: Start Dev Server` or `./scripts/start-backend` |\n| Start frontend dev server | VS Code task `Frontend: Start Dev Server` or `./scripts/start-frontend` |\n| Start both local dev servers together | `./scripts/dev-start` |\n| Stop local dev servers together | `./scripts/dev-stop` |\n| Inspect local dev logs | `./scripts/logs` |\n| Run fast repo tests | `./scripts/test` |\n| Run repo tests with coverage | `COVERAGE=1 ./scripts/test` |\n\n`./scripts/test` now includes the companion Windows GNU target compatibility check when the local toolchain is available.\nIn the devcontainer, that toolchain is preinstalled as part of the image build.\n\n## Backend Commands\n\nUse these when you are changing backend behavior, API contracts, or SMB handling.\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nUseful related task:\n\n- VS Code task `Backend: Run Tests`\n- VS Code task `Backend: Type Check (mypy)`\n\n## Frontend Commands\n\nUse these when the browser UI, routing, services, or typed frontend behavior changes.\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nUseful related task:\n\n- VS Code task `Frontend: Run Tests`\n- VS Code task `Frontend: Type Check + Lint`\n\n## Companion Commands\n\nUse these when local-drive access, native-app editing, or Tauri-side behavior changes.\n\n```bash\ncd companion \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run check:rust:windows\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nUse `npm run check:rust:windows` as a local Windows-target compatibility check.\nIt runs `cargo check` for `x86_64-pc-windows-gnu` from Linux and is intended to catch cross-target breakage early without replacing the real Windows release build.\n\nUseful related task:\n\n- VS Code task `Companion: Run Rust Tests`\n- VS Code task `Companion: Validation Suite`\n\nThe committed devcontainer image now includes:\n\n- the Rust target `x86_64-pc-windows-gnu`\n- the MinGW toolchain package `gcc-mingw-w64-x86-64`\n\nThat means a rebuilt devcontainer can run the companion Windows GNU cross-check without extra manual setup.\n\n## Local Dev Logs and Service Control\n\nUse the committed helper scripts first when you are diagnosing the supported local development workflow.\n\n### Combined Dev Server Control\n\nThese scripts manage the local backend and frontend together:\n\n```bash\n./scripts/dev-start\n./scripts/dev-stop\n./scripts/dev-stop \u0026\u0026 ./scripts/dev-start\n```\n\nUse those entry points when you want the repo's own startup logging and local log-file layout instead of ad hoc process control.\n\n### Log Inspection\n\nThe supported local log viewer is:\n\n```bash\n./scripts/logs\n./scripts/logs -f\n./scripts/logs -n 200\n```\n\nThat script summarizes service status and tails the main local development log files.\n\nThe current local log files are:\n\n- `/tmp/backend.log`\n- `/tmp/frontend.log`\n- `/tmp/dev-start.log`\n- `/tmp/post-start.log`\n\nYou can inspect individual files directly when needed:\n\n```bash\ntail -f /tmp/backend.log\ntail -f /tmp/frontend.log\ntail -f /tmp/dev-start.log\ntail -f /tmp/post-start.log\n```\n\n### Search and Status Checks\n\nWhen the helper scripts are not enough, targeted shell checks are still useful.\n\n```bash\npgrep -f \"uvicorn.*app.main:app\"\npgrep -f \"vite\"\nlsof -i :3000,8000\ngrep -i error /tmp/*.log\ngrep -i warning /tmp/*.log\ngrep -i smb /tmp/backend.log\ngrep -E \"\\([0-9]{4,}\\.[0-9]+ms\\)\" /tmp/backend.log\n```\n\nTreat these as diagnostics for the local development environment, not as the primary supported control surface.\n\nBe especially careful with broad `pkill -f vite`-style commands in a workspace that can also run website or companion dev servers.\n\n### Rotating and Clearing Local Logs\n\nWhen local logs become noisy, use the committed rotation script first:\n\n```bash\n./scripts/rotate-logs\n```\n\nThat script archives current `/tmp/*.log` files into `/tmp/logs-archive/` and truncates the live files in place so active writers keep working.\n\nTo inspect archived logs:\n\n```bash\nls -lh /tmp/logs-archive/\n```\n\nManual truncation is still possible for local development, but it is a deliberately destructive cleanup step:\n\n```bash\n\u003e /tmp/backend.log\n\u003e /tmp/frontend.log\n\u003e /tmp/dev-start.log\n\u003e /tmp/post-start.log\n```\n\nUse that only when you intentionally want to discard the current local log history.\n\n### Practical Local Triage Order\n\nFor the supported dev workflow, a reasonable first pass is:\n\n1. run `./scripts/logs`\n2. verify the expected dev processes or ports if the summary looks wrong\n3. search `/tmp/*.log` for the concrete failure signal\n4. restart with `./scripts/dev-stop \u0026\u0026 ./scripts/dev-start` if the issue is clearly local-process state rather than a code defect\n\n## Version Sync\n\nWhen you change `VERSION`, run the sync script and review all resulting metadata changes together.\n\n```bash\n./scripts/sync-version\n```\n\nThat workflow updates the frontend and companion package metadata and related version-bearing files.\n\n## Command Selection Rule of Thumb\n\n- smallest relevant change: run the checks for the area you changed\n- cross-boundary change: run checks for every touched subsystem\n- dependency or versioning change: run the affected subsystem checks plus the sync workflow if `VERSION` changed\n\nFor companion-native changes that affect packaging, Windows-specific crates, or Tauri platform integration, include the Windows GNU cross-check in the local validation set even when you are not creating release artifacts.\n\nFor the broader validation strategy and how to choose depth, continue to [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/).\n", "0.9": "+++\ntitle = \"Common Task Commands\"\n+++\n\nPrefer the committed scripts and workspace tasks over improvised one-off commands.\n\n## Daily Entry Points\n\n| Goal | Preferred command or task |\n|---|---|\n| Start backend dev server | VS Code task `Backend: Start Dev Server` or `./scripts/start-backend` |\n| Start frontend dev server | VS Code task `Frontend: Start Dev Server` or `./scripts/start-frontend` |\n| Start both local dev servers together | `./scripts/dev-start` |\n| Stop local dev servers together | `./scripts/dev-stop` |\n| Inspect local dev logs | `./scripts/logs` |\n| Run fast repo tests | `./scripts/test` |\n| Run repo tests with coverage | `COVERAGE=1 ./scripts/test` |\n\n`./scripts/test` now includes the companion Windows GNU target compatibility check when the local toolchain is available.\nIn the devcontainer, that toolchain is preinstalled as part of the image build.\n\n## Backend Commands\n\nUse these when you are changing backend behavior, API contracts, or SMB handling.\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nUseful related task:\n\n- VS Code task `Backend: Run Tests`\n- VS Code task `Backend: Type Check (mypy)`\n\n## Frontend Commands\n\nUse these when the browser UI, routing, services, or typed frontend behavior changes.\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nUseful related task:\n\n- VS Code task `Frontend: Run Tests`\n- VS Code task `Frontend: Type Check + Lint`\n\n## Companion Commands\n\nUse these when local-drive access, native-app editing, or Tauri-side behavior changes.\n\n```bash\ncd companion \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run check:rust:windows\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nUse `npm run check:rust:windows` as a local Windows-target compatibility check.\nIt runs `cargo check` for `x86_64-pc-windows-gnu` from Linux and is intended to catch cross-target breakage early without replacing the real Windows release build.\n\nUseful related task:\n\n- VS Code task `Companion: Run Rust Tests`\n- VS Code task `Companion: Validation Suite`\n\nThe committed devcontainer image now includes:\n\n- the Rust target `x86_64-pc-windows-gnu`\n- the MinGW toolchain package `gcc-mingw-w64-x86-64`\n\nThat means a rebuilt devcontainer can run the companion Windows GNU cross-check without extra manual setup.\n\n## Local Dev Logs and Service Control\n\nUse the committed helper scripts first when you are diagnosing the supported local development workflow.\n\n### Combined Dev Server Control\n\nThese scripts manage the local backend and frontend together:\n\n```bash\n./scripts/dev-start\n./scripts/dev-stop\n./scripts/dev-stop \u0026\u0026 ./scripts/dev-start\n```\n\nUse those entry points when you want the repo's own startup logging and local log-file layout instead of ad hoc process control.\n\n### Log Inspection\n\nThe supported local log viewer is:\n\n```bash\n./scripts/logs\n./scripts/logs -f\n./scripts/logs -n 200\n```\n\nThat script summarizes service status and tails the main local development log files.\n\nThe current local log files are:\n\n- `/tmp/backend.log`\n- `/tmp/frontend.log`\n- `/tmp/dev-start.log`\n- `/tmp/post-start.log`\n\nYou can inspect individual files directly when needed:\n\n```bash\ntail -f /tmp/backend.log\ntail -f /tmp/frontend.log\ntail -f /tmp/dev-start.log\ntail -f /tmp/post-start.log\n```\n\n### Search and Status Checks\n\nWhen the helper scripts are not enough, targeted shell checks are still useful.\n\n```bash\npgrep -f \"uvicorn.*app.main:app\"\npgrep -f \"vite\"\nlsof -i :3000,8000\ngrep -i error /tmp/*.log\ngrep -i warning /tmp/*.log\ngrep -i smb /tmp/backend.log\ngrep -E \"\\([0-9]{4,}\\.[0-9]+ms\\)\" /tmp/backend.log\n```\n\nTreat these as diagnostics for the local development environment, not as the primary supported control surface.\n\nBe especially careful with broad `pkill -f vite`-style commands in a workspace that can also run website or companion dev servers.\n\n### Rotating and Clearing Local Logs\n\nWhen local logs become noisy, use the committed rotation script first:\n\n```bash\n./scripts/rotate-logs\n```\n\nThat script archives current `/tmp/*.log` files into `/tmp/logs-archive/` and truncates the live files in place so active writers keep working.\n\nTo inspect archived logs:\n\n```bash\nls -lh /tmp/logs-archive/\n```\n\nManual truncation is still possible for local development, but it is a deliberately destructive cleanup step:\n\n```bash\n\u003e /tmp/backend.log\n\u003e /tmp/frontend.log\n\u003e /tmp/dev-start.log\n\u003e /tmp/post-start.log\n```\n\nUse that only when you intentionally want to discard the current local log history.\n\n### Practical Local Triage Order\n\nFor the supported dev workflow, a reasonable first pass is:\n\n1. run `./scripts/logs`\n2. verify the expected dev processes or ports if the summary looks wrong\n3. search `/tmp/*.log` for the concrete failure signal\n4. restart with `./scripts/dev-stop \u0026\u0026 ./scripts/dev-start` if the issue is clearly local-process state rather than a code defect\n\n## Version Sync\n\nWhen you change `VERSION`, run the sync script and review all resulting metadata changes together.\n\n```bash\n./scripts/sync-version\n```\n\nThat workflow updates the frontend and companion package metadata and related version-bearing files.\n\n## Command Selection Rule of Thumb\n\n- smallest relevant change: run the checks for the area you changed\n- cross-boundary change: run checks for every touched subsystem\n- dependency or versioning change: run the affected subsystem checks plus the sync workflow if `VERSION` changed\n\nFor companion-native changes that affect packaging, Windows-specific crates, or Tauri platform integration, include the Windows GNU cross-check in the local validation set even when you are not creating release artifacts.\n\nFor the broader validation strategy and how to choose depth, continue to [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/).\n", "1.0": "+++\ntitle = \"Common Task Commands\"\n+++\n\nPrefer the committed scripts and workspace tasks over improvised one-off commands.\n\n## Daily Entry Points\n\n| Goal | Preferred command or task |\n|---|---|\n| Start backend dev server | VS Code task `Backend: Start Dev Server` or `./scripts/start-backend` |\n| Start frontend dev server | VS Code task `Frontend: Start Dev Server` or `./scripts/start-frontend` |\n| Start both local dev servers together | `./scripts/dev-start` |\n| Stop local dev servers together | `./scripts/dev-stop` |\n| Inspect local dev logs | `./scripts/logs` |\n| Run fast repo tests | `./scripts/test` |\n| Run repo tests with coverage | `COVERAGE=1 ./scripts/test` |\n\n`./scripts/test` now includes the companion Windows GNU target compatibility check when the local toolchain is available.\nIn the devcontainer, that toolchain is preinstalled as part of the image build.\n\n## Backend Commands\n\nUse these when you are changing backend behavior, API contracts, or SMB handling.\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nUseful related task:\n\n- VS Code task `Backend: Run Tests`\n- VS Code task `Backend: Type Check (mypy)`\n\n## Frontend Commands\n\nUse these when the browser UI, routing, services, or typed frontend behavior changes.\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nUseful related task:\n\n- VS Code task `Frontend: Run Tests`\n- VS Code task `Frontend: Type Check + Lint`\n\n## Companion Commands\n\nUse these when local-drive access, native-app editing, or Tauri-side behavior changes.\n\n```bash\ncd companion \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run check:rust:windows\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nUse `npm run check:rust:windows` as a local Windows-target compatibility check.\nIt runs `cargo check` for `x86_64-pc-windows-gnu` from Linux and is intended to catch cross-target breakage early without replacing the real Windows release build.\n\nUseful related task:\n\n- VS Code task `Companion: Run Rust Tests`\n- VS Code task `Companion: Validation Suite`\n\nThe committed devcontainer image now includes:\n\n- the Rust target `x86_64-pc-windows-gnu`\n- the MinGW toolchain package `gcc-mingw-w64-x86-64`\n\nThat means a rebuilt devcontainer can run the companion Windows GNU cross-check without extra manual setup.\n\n## Local Dev Logs and Service Control\n\nUse the committed helper scripts first when you are diagnosing the supported local development workflow.\n\n### Combined Dev Server Control\n\nThese scripts manage the local backend and frontend together:\n\n```bash\n./scripts/dev-start\n./scripts/dev-stop\n./scripts/dev-stop \u0026\u0026 ./scripts/dev-start\n```\n\nUse those entry points when you want the repo's own startup logging and local log-file layout instead of ad hoc process control.\n\n### Log Inspection\n\nThe supported local log viewer is:\n\n```bash\n./scripts/logs\n./scripts/logs -f\n./scripts/logs -n 200\n```\n\nThat script summarizes service status and tails the main local development log files.\n\nThe current local log files are:\n\n- `/tmp/backend.log`\n- `/tmp/frontend.log`\n- `/tmp/dev-start.log`\n- `/tmp/post-start.log`\n\nYou can inspect individual files directly when needed:\n\n```bash\ntail -f /tmp/backend.log\ntail -f /tmp/frontend.log\ntail -f /tmp/dev-start.log\ntail -f /tmp/post-start.log\n```\n\n### Search and Status Checks\n\nWhen the helper scripts are not enough, targeted shell checks are still useful.\n\n```bash\npgrep -f \"uvicorn.*app.main:app\"\npgrep -f \"vite\"\nlsof -i :3000,8000\ngrep -i error /tmp/*.log\ngrep -i warning /tmp/*.log\ngrep -i smb /tmp/backend.log\ngrep -E \"\\([0-9]{4,}\\.[0-9]+ms\\)\" /tmp/backend.log\n```\n\nTreat these as diagnostics for the local development environment, not as the primary supported control surface.\n\nBe especially careful with broad `pkill -f vite`-style commands in a workspace that can also run website or companion dev servers.\n\n### Rotating and Clearing Local Logs\n\nWhen local logs become noisy, use the committed rotation script first:\n\n```bash\n./scripts/rotate-logs\n```\n\nThat script archives current `/tmp/*.log` files into `/tmp/logs-archive/` and truncates the live files in place so active writers keep working.\n\nTo inspect archived logs:\n\n```bash\nls -lh /tmp/logs-archive/\n```\n\nManual truncation is still possible for local development, but it is a deliberately destructive cleanup step:\n\n```bash\n\u003e /tmp/backend.log\n\u003e /tmp/frontend.log\n\u003e /tmp/dev-start.log\n\u003e /tmp/post-start.log\n```\n\nUse that only when you intentionally want to discard the current local log history.\n\n### Practical Local Triage Order\n\nFor the supported dev workflow, a reasonable first pass is:\n\n1. run `./scripts/logs`\n2. verify the expected dev processes or ports if the summary looks wrong\n3. search `/tmp/*.log` for the concrete failure signal\n4. restart with `./scripts/dev-stop \u0026\u0026 ./scripts/dev-start` if the issue is clearly local-process state rather than a code defect\n\n## Version Sync\n\nWhen you change `VERSION`, run the sync script and review all resulting metadata changes together.\n\n```bash\n./scripts/sync-version\n```\n\nThat workflow updates the frontend and companion package metadata and related version-bearing files.\n\n## Command Selection Rule of Thumb\n\n- smallest relevant change: run the checks for the area you changed\n- cross-boundary change: run checks for every touched subsystem\n- dependency or versioning change: run the affected subsystem checks plus the sync workflow if `VERSION` changed\n\nFor companion-native changes that affect packaging, Windows-specific crates, or Tauri platform integration, include the Windows GNU cross-check in the local validation set even when you are not creating release artifacts.\n\nFor the broader validation strategy and how to choose depth, continue to [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/).\n", "2.0": "+++\ntitle = \"Common Task Commands\"\n+++\n\nPrefer the committed scripts and workspace tasks over improvised one-off commands.\n\n## Daily Entry Points\n\n| Goal | Preferred command or task |\n|---|---|\n| Start backend dev server | VS Code task `Backend: Start Dev Server` or `./scripts/start-backend` |\n| Start frontend dev server | VS Code task `Frontend: Start Dev Server` or `./scripts/start-frontend` |\n| Start both local dev servers together | `./scripts/dev-start` |\n| Stop local dev servers together | `./scripts/dev-stop` |\n| Inspect local dev logs | `./scripts/logs` |\n| Run fast repo tests | `./scripts/test` |\n| Run repo tests with coverage | `COVERAGE=1 ./scripts/test` |\n\n`./scripts/test` now includes the companion Windows GNU target compatibility check when the local toolchain is available.\nIn the devcontainer, that toolchain is preinstalled as part of the image build.\n\n## Backend Commands\n\nUse these when you are changing backend behavior, API contracts, or SMB handling.\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nUseful related task:\n\n- VS Code task `Backend: Run Tests`\n- VS Code task `Backend: Type Check (mypy)`\n\n## Frontend Commands\n\nUse these when the browser UI, routing, services, or typed frontend behavior changes.\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nUseful related task:\n\n- VS Code task `Frontend: Run Tests`\n- VS Code task `Frontend: Type Check + Lint`\n\n## Companion Commands\n\nUse these when local-drive access, native-app editing, or Tauri-side behavior changes.\n\n```bash\ncd companion \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run check:rust:windows\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nUse `npm run check:rust:windows` as a local Windows-target compatibility check.\nIt runs `cargo check` for `x86_64-pc-windows-gnu` from Linux and is intended to catch cross-target breakage early without replacing the real Windows release build.\n\nUseful related task:\n\n- VS Code task `Companion: Run Rust Tests`\n- VS Code task `Companion: Validation Suite`\n\nThe committed devcontainer image now includes:\n\n- the Rust target `x86_64-pc-windows-gnu`\n- the MinGW toolchain package `gcc-mingw-w64-x86-64`\n\nThat means a rebuilt devcontainer can run the companion Windows GNU cross-check without extra manual setup.\n\n## Local Dev Logs and Service Control\n\nUse the committed helper scripts first when you are diagnosing the supported local development workflow.\n\n### Combined Dev Server Control\n\nThese scripts manage the local backend and frontend together:\n\n```bash\n./scripts/dev-start\n./scripts/dev-stop\n./scripts/dev-stop \u0026\u0026 ./scripts/dev-start\n```\n\nUse those entry points when you want the repo's own startup logging and local log-file layout instead of ad hoc process control.\n\n### Log Inspection\n\nThe supported local log viewer is:\n\n```bash\n./scripts/logs\n./scripts/logs -f\n./scripts/logs -n 200\n```\n\nThat script summarizes service status and tails the main local development log files.\n\nThe current local log files are:\n\n- `/tmp/backend.log`\n- `/tmp/frontend.log`\n- `/tmp/dev-start.log`\n- `/tmp/post-start.log`\n\nYou can inspect individual files directly when needed:\n\n```bash\ntail -f /tmp/backend.log\ntail -f /tmp/frontend.log\ntail -f /tmp/dev-start.log\ntail -f /tmp/post-start.log\n```\n\n### Search and Status Checks\n\nWhen the helper scripts are not enough, targeted shell checks are still useful.\n\n```bash\npgrep -f \"uvicorn.*app.main:app\"\npgrep -f \"vite\"\nlsof -i :3000,8000\ngrep -i error /tmp/*.log\ngrep -i warning /tmp/*.log\ngrep -i smb /tmp/backend.log\ngrep -E \"\\([0-9]{4,}\\.[0-9]+ms\\)\" /tmp/backend.log\n```\n\nTreat these as diagnostics for the local development environment, not as the primary supported control surface.\n\nBe especially careful with broad `pkill -f vite`-style commands in a workspace that can also run website or companion dev servers.\n\n### Rotating and Clearing Local Logs\n\nWhen local logs become noisy, use the committed rotation script first:\n\n```bash\n./scripts/rotate-logs\n```\n\nThat script archives current `/tmp/*.log` files into `/tmp/logs-archive/` and truncates the live files in place so active writers keep working.\n\nTo inspect archived logs:\n\n```bash\nls -lh /tmp/logs-archive/\n```\n\nManual truncation is still possible for local development, but it is a deliberately destructive cleanup step:\n\n```bash\n\u003e /tmp/backend.log\n\u003e /tmp/frontend.log\n\u003e /tmp/dev-start.log\n\u003e /tmp/post-start.log\n```\n\nUse that only when you intentionally want to discard the current local log history.\n\n### Practical Local Triage Order\n\nFor the supported dev workflow, a reasonable first pass is:\n\n1. run `./scripts/logs`\n2. verify the expected dev processes or ports if the summary looks wrong\n3. search `/tmp/*.log` for the concrete failure signal\n4. restart with `./scripts/dev-stop \u0026\u0026 ./scripts/dev-start` if the issue is clearly local-process state rather than a code defect\n\n## Version Sync\n\nWhen you change `VERSION`, run the sync script and review all resulting metadata changes together.\n\n```bash\n./scripts/sync-version\n```\n\nThat workflow updates the frontend and companion package metadata and related version-bearing files.\n\n## Command Selection Rule of Thumb\n\n- smallest relevant change: run the checks for the area you changed\n- cross-boundary change: run checks for every touched subsystem\n- dependency or versioning change: run the affected subsystem checks plus the sync workflow if `VERSION` changed\n\nFor companion-native changes that affect packaging, Windows-specific crates, or Tauri platform integration, include the Windows GNU cross-check in the local validation set even when you are not creating release artifacts.\n\nFor the broader validation strategy and how to choose depth, continue to [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/).\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:developer-guide/backend-architecture", "parent_id": "book:developer-guide", "depth": 1, "kind": "section", "label": "backend-architecture", "title": "Backend Architecture", "path": "developer-guide/backend-architecture", "has_children": true, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Backend Architecture\"\n+++\n\nThe backend is where Sambee's server-side behavior becomes real: authentication, API shape, SMB access, file operations, edit locks, and change notifications all converge here.\n\nStart with:\n\n- [Backend Overview](./backend-overview/)\n- [Request Flow and Service Boundaries](./request-flow-and-service-boundaries/)\n- [Image Preprocessing and Conversion Pipeline](./image-preprocessing-and-conversion-pipeline/)\n- [SMB Change Notification and Directory Freshness](./smb-change-notification-and-directory-freshness/)\n- [File Operations and Edit Locking](./file-operations-and-edit-locking/)\n\nUse this section before you change browser-visible behavior that depends on the API, SMB semantics, or server-side validation.\n", "0.8": "+++\ntitle = \"Backend Architecture\"\n+++\n\nThe backend is where Sambee's server-side behavior becomes real: authentication, API shape, SMB access, file operations, edit locks, and change notifications all converge here.\n\nStart with:\n\n- [Backend Overview](./backend-overview/)\n- [Request Flow and Service Boundaries](./request-flow-and-service-boundaries/)\n- [Image Preprocessing and Conversion Pipeline](./image-preprocessing-and-conversion-pipeline/)\n- [SMB Change Notification and Directory Freshness](./smb-change-notification-and-directory-freshness/)\n- [File Operations and Edit Locking](./file-operations-and-edit-locking/)\n\nUse this section before you change browser-visible behavior that depends on the API, SMB semantics, or server-side validation.\n", "0.9": "+++\ntitle = \"Backend Architecture\"\n+++\n\nThe backend is where Sambee's server-side behavior becomes real: authentication, API shape, SMB access, file operations, edit locks, and change notifications all converge here.\n\nStart with:\n\n- [Backend Overview](./backend-overview/)\n- [Request Flow and Service Boundaries](./request-flow-and-service-boundaries/)\n- [Image Preprocessing and Conversion Pipeline](./image-preprocessing-and-conversion-pipeline/)\n- [SMB Change Notification and Directory Freshness](./smb-change-notification-and-directory-freshness/)\n- [File Operations and Edit Locking](./file-operations-and-edit-locking/)\n\nUse this section before you change browser-visible behavior that depends on the API, SMB semantics, or server-side validation.\n", "1.0": "+++\ntitle = \"Backend Architecture\"\n+++\n\nThe backend is where Sambee's server-side behavior becomes real: authentication, API shape, SMB access, file operations, edit locks, and change notifications all converge here.\n\nStart with:\n\n- [Backend Overview](./backend-overview/)\n- [Request Flow and Service Boundaries](./request-flow-and-service-boundaries/)\n- [Image Preprocessing and Conversion Pipeline](./image-preprocessing-and-conversion-pipeline/)\n- [SMB Change Notification and Directory Freshness](./smb-change-notification-and-directory-freshness/)\n- [File Operations and Edit Locking](./file-operations-and-edit-locking/)\n\nUse this section before you change browser-visible behavior that depends on the API, SMB semantics, or server-side validation.\n", "2.0": "+++\ntitle = \"Backend Architecture\"\n+++\n\nThe backend is where Sambee's server-side behavior becomes real: authentication, API shape, SMB access, file operations, edit locks, and change notifications all converge here.\n\nStart with:\n\n- [Backend Overview](./backend-overview/)\n- [Request Flow and Service Boundaries](./request-flow-and-service-boundaries/)\n- [Image Preprocessing and Conversion Pipeline](./image-preprocessing-and-conversion-pipeline/)\n- [SMB Change Notification and Directory Freshness](./smb-change-notification-and-directory-freshness/)\n- [File Operations and Edit Locking](./file-operations-and-edit-locking/)\n\nUse this section before you change browser-visible behavior that depends on the API, SMB semantics, or server-side validation.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/backend-architecture/backend-overview", "parent_id": "section:developer-guide/backend-architecture", "depth": 2, "kind": "page", "label": "backend-overview", "title": "Backend Overview", "path": "developer-guide/backend-architecture/backend-overview", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Backend Overview\"\n+++\n\nThe backend is the policy and integration layer between the browser-facing product and the storage systems Sambee works with.\n\n## What the Backend Owns\n\nThe backend is responsible for:\n\n- authentication and authorization\n- API endpoints consumed by the browser app and companion flows\n- SMB access and server-side file operations\n- server-side preview and download behavior where the product needs it\n- edit-lock and conflict-handling behavior for companion-assisted editing\n- directory-change notification and other state that must stay authoritative on the server side\n\n## Main Code Areas\n\nThe exact module layout evolves, but the backend is organized around a few stable concerns.\n\n| Area | Responsibility |\n|---|---|\n| `backend/app/api/` | request handlers and HTTP-facing endpoints |\n| `backend/app/models/` | API and domain models used across request and response boundaries |\n| `backend/app/storage/` | storage backends and storage-facing behavior, including SMB access |\n| `backend/app/services/` | longer-running or cross-cutting service behavior such as monitoring and background coordination |\n| `backend/app/db/` | database setup and models for persisted application state |\n| `backend/tests/` | pytest coverage for server behavior and contracts |\n\n## Request and Storage Flow\n\nFor the common SMB flow:\n\n1. The frontend issues an authenticated API request.\n2. The backend validates input and permissions.\n3. The backend performs the requested SMB operation through the storage layer.\n4. The backend returns a typed response the frontend or companion can rely on.\n\nThis is why the backend, not the browser, is the source of truth for SMB semantics and conflict-sensitive operations.\n\nIf you need the detailed layer breakdown, continue to [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/).\n\n## Important Backend Contracts\n\n### API Contract Stability\n\nThe frontend relies on typed request and response shapes. That is why contract testing guidance exists and why contributors should treat API shape changes as user-visible changes, not internal refactors.\n\n### File-Type and Preview Behavior\n\nThe backend contributes to preview behavior through MIME detection, file-type classification, and conversion decisions for formats that are not natively browser-friendly. Those rules have to stay aligned with frontend expectations.\n\n### Edit Locking and Companion Flows\n\nFor companion-assisted editing of SMB-backed files, the backend owns the server-side lock, heartbeat, upload, and conflict rules. A desktop-side improvement that ignores those rules can easily create data-loss regressions.\n\nFor the full lifecycle, continue to [File Operations and Edit Locking](../file-operations-and-edit-locking/).\n\n### Change Notification\n\nThe backend also owns SMB-side change monitoring and the notifications that tell browser clients when directory state should refresh.\n\nFor the watcher architecture, subscriber model, and cache-freshness split, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## What Usually Breaks When This Layer Changes\n\n- frontend assumptions about response shape\n- viewer or file-management behavior that depends on MIME or category detection\n- companion editing flows that depend on lock or upload semantics\n- directory freshness in the browser when change notifications stop matching product expectations\n\n## Go Deeper\n\n- [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/): how API, models, storage, services, and WebSocket coordination fit together\n- [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/): how backend watchers, WebSocket notifications, and cache freshness fit together\n- [File Operations and Edit Locking](../file-operations-and-edit-locking/): how ordinary file operations differ from companion-assisted SMB editing and lock handling\n\n## Validation Expectations\n\nWhen the backend changes, start with:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nThen add frontend or companion checks if the backend change affects a shared contract.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) for the broader decision rule.\n", "0.8": "+++\ntitle = \"Backend Overview\"\n+++\n\nThe backend is the policy and integration layer between the browser-facing product and the storage systems Sambee works with.\n\n## What the Backend Owns\n\nThe backend is responsible for:\n\n- authentication and authorization\n- API endpoints consumed by the browser app and companion flows\n- SMB access and server-side file operations\n- server-side preview and download behavior where the product needs it\n- edit-lock and conflict-handling behavior for companion-assisted editing\n- directory-change notification and other state that must stay authoritative on the server side\n\n## Main Code Areas\n\nThe exact module layout evolves, but the backend is organized around a few stable concerns.\n\n| Area | Responsibility |\n|---|---|\n| `backend/app/api/` | request handlers and HTTP-facing endpoints |\n| `backend/app/models/` | API and domain models used across request and response boundaries |\n| `backend/app/storage/` | storage backends and storage-facing behavior, including SMB access |\n| `backend/app/services/` | longer-running or cross-cutting service behavior such as monitoring and background coordination |\n| `backend/app/db/` | database setup and models for persisted application state |\n| `backend/tests/` | pytest coverage for server behavior and contracts |\n\n## Request and Storage Flow\n\nFor the common SMB flow:\n\n1. The frontend issues an authenticated API request.\n2. The backend validates input and permissions.\n3. The backend performs the requested SMB operation through the storage layer.\n4. The backend returns a typed response the frontend or companion can rely on.\n\nThis is why the backend, not the browser, is the source of truth for SMB semantics and conflict-sensitive operations.\n\nIf you need the detailed layer breakdown, continue to [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/).\n\n## Important Backend Contracts\n\n### API Contract Stability\n\nThe frontend relies on typed request and response shapes. That is why contract testing guidance exists and why contributors should treat API shape changes as user-visible changes, not internal refactors.\n\n### File-Type and Preview Behavior\n\nThe backend contributes to preview behavior through MIME detection, file-type classification, and conversion decisions for formats that are not natively browser-friendly. Those rules have to stay aligned with frontend expectations.\n\n### Edit Locking and Companion Flows\n\nFor companion-assisted editing of SMB-backed files, the backend owns the server-side lock, heartbeat, upload, and conflict rules. A desktop-side improvement that ignores those rules can easily create data-loss regressions.\n\nFor the full lifecycle, continue to [File Operations and Edit Locking](../file-operations-and-edit-locking/).\n\n### Change Notification\n\nThe backend also owns SMB-side change monitoring and the notifications that tell browser clients when directory state should refresh.\n\nFor the watcher architecture, subscriber model, and cache-freshness split, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## What Usually Breaks When This Layer Changes\n\n- frontend assumptions about response shape\n- viewer or file-management behavior that depends on MIME or category detection\n- companion editing flows that depend on lock or upload semantics\n- directory freshness in the browser when change notifications stop matching product expectations\n\n## Go Deeper\n\n- [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/): how API, models, storage, services, and WebSocket coordination fit together\n- [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/): how backend watchers, WebSocket notifications, and cache freshness fit together\n- [File Operations and Edit Locking](../file-operations-and-edit-locking/): how ordinary file operations differ from companion-assisted SMB editing and lock handling\n\n## Validation Expectations\n\nWhen the backend changes, start with:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nThen add frontend or companion checks if the backend change affects a shared contract.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) for the broader decision rule.\n", "0.9": "+++\ntitle = \"Backend Overview\"\n+++\n\nThe backend is the policy and integration layer between the browser-facing product and the storage systems Sambee works with.\n\n## What the Backend Owns\n\nThe backend is responsible for:\n\n- authentication and authorization\n- API endpoints consumed by the browser app and companion flows\n- SMB access and server-side file operations\n- server-side preview and download behavior where the product needs it\n- edit-lock and conflict-handling behavior for companion-assisted editing\n- directory-change notification and other state that must stay authoritative on the server side\n\n## Main Code Areas\n\nThe exact module layout evolves, but the backend is organized around a few stable concerns.\n\n| Area | Responsibility |\n|---|---|\n| `backend/app/api/` | request handlers and HTTP-facing endpoints |\n| `backend/app/models/` | API and domain models used across request and response boundaries |\n| `backend/app/storage/` | storage backends and storage-facing behavior, including SMB access |\n| `backend/app/services/` | longer-running or cross-cutting service behavior such as monitoring and background coordination |\n| `backend/app/db/` | database setup and models for persisted application state |\n| `backend/tests/` | pytest coverage for server behavior and contracts |\n\n## Request and Storage Flow\n\nFor the common SMB flow:\n\n1. The frontend issues an authenticated API request.\n2. The backend validates input and permissions.\n3. The backend performs the requested SMB operation through the storage layer.\n4. The backend returns a typed response the frontend or companion can rely on.\n\nThis is why the backend, not the browser, is the source of truth for SMB semantics and conflict-sensitive operations.\n\nIf you need the detailed layer breakdown, continue to [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/).\n\n## Important Backend Contracts\n\n### API Contract Stability\n\nThe frontend relies on typed request and response shapes. That is why contract testing guidance exists and why contributors should treat API shape changes as user-visible changes, not internal refactors.\n\n### File-Type and Preview Behavior\n\nThe backend contributes to preview behavior through MIME detection, file-type classification, and conversion decisions for formats that are not natively browser-friendly. Those rules have to stay aligned with frontend expectations.\n\n### Edit Locking and Companion Flows\n\nFor companion-assisted editing of SMB-backed files, the backend owns the server-side lock, heartbeat, upload, and conflict rules. A desktop-side improvement that ignores those rules can easily create data-loss regressions.\n\nFor the full lifecycle, continue to [File Operations and Edit Locking](../file-operations-and-edit-locking/).\n\n### Change Notification\n\nThe backend also owns SMB-side change monitoring and the notifications that tell browser clients when directory state should refresh.\n\nFor the watcher architecture, subscriber model, and cache-freshness split, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## What Usually Breaks When This Layer Changes\n\n- frontend assumptions about response shape\n- viewer or file-management behavior that depends on MIME or category detection\n- companion editing flows that depend on lock or upload semantics\n- directory freshness in the browser when change notifications stop matching product expectations\n\n## Go Deeper\n\n- [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/): how API, models, storage, services, and WebSocket coordination fit together\n- [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/): how backend watchers, WebSocket notifications, and cache freshness fit together\n- [File Operations and Edit Locking](../file-operations-and-edit-locking/): how ordinary file operations differ from companion-assisted SMB editing and lock handling\n\n## Validation Expectations\n\nWhen the backend changes, start with:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nThen add frontend or companion checks if the backend change affects a shared contract.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) for the broader decision rule.\n", "1.0": "+++\ntitle = \"Backend Overview\"\n+++\n\nThe backend is the policy and integration layer between the browser-facing product and the storage systems Sambee works with.\n\n## What the Backend Owns\n\nThe backend is responsible for:\n\n- authentication and authorization\n- API endpoints consumed by the browser app and companion flows\n- SMB access and server-side file operations\n- server-side preview and download behavior where the product needs it\n- edit-lock and conflict-handling behavior for companion-assisted editing\n- directory-change notification and other state that must stay authoritative on the server side\n\n## Main Code Areas\n\nThe exact module layout evolves, but the backend is organized around a few stable concerns.\n\n| Area | Responsibility |\n|---|---|\n| `backend/app/api/` | request handlers and HTTP-facing endpoints |\n| `backend/app/models/` | API and domain models used across request and response boundaries |\n| `backend/app/storage/` | storage backends and storage-facing behavior, including SMB access |\n| `backend/app/services/` | longer-running or cross-cutting service behavior such as monitoring and background coordination |\n| `backend/app/db/` | database setup and models for persisted application state |\n| `backend/tests/` | pytest coverage for server behavior and contracts |\n\n## Request and Storage Flow\n\nFor the common SMB flow:\n\n1. The frontend issues an authenticated API request.\n2. The backend validates input and permissions.\n3. The backend performs the requested SMB operation through the storage layer.\n4. The backend returns a typed response the frontend or companion can rely on.\n\nThis is why the backend, not the browser, is the source of truth for SMB semantics and conflict-sensitive operations.\n\nIf you need the detailed layer breakdown, continue to [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/).\n\n## Important Backend Contracts\n\n### API Contract Stability\n\nThe frontend relies on typed request and response shapes. That is why contract testing guidance exists and why contributors should treat API shape changes as user-visible changes, not internal refactors.\n\n### File-Type and Preview Behavior\n\nThe backend contributes to preview behavior through MIME detection, file-type classification, and conversion decisions for formats that are not natively browser-friendly. Those rules have to stay aligned with frontend expectations.\n\n### Edit Locking and Companion Flows\n\nFor companion-assisted editing of SMB-backed files, the backend owns the server-side lock, heartbeat, upload, and conflict rules. A desktop-side improvement that ignores those rules can easily create data-loss regressions.\n\nFor the full lifecycle, continue to [File Operations and Edit Locking](../file-operations-and-edit-locking/).\n\n### Change Notification\n\nThe backend also owns SMB-side change monitoring and the notifications that tell browser clients when directory state should refresh.\n\nFor the watcher architecture, subscriber model, and cache-freshness split, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## What Usually Breaks When This Layer Changes\n\n- frontend assumptions about response shape\n- viewer or file-management behavior that depends on MIME or category detection\n- companion editing flows that depend on lock or upload semantics\n- directory freshness in the browser when change notifications stop matching product expectations\n\n## Go Deeper\n\n- [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/): how API, models, storage, services, and WebSocket coordination fit together\n- [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/): how backend watchers, WebSocket notifications, and cache freshness fit together\n- [File Operations and Edit Locking](../file-operations-and-edit-locking/): how ordinary file operations differ from companion-assisted SMB editing and lock handling\n\n## Validation Expectations\n\nWhen the backend changes, start with:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nThen add frontend or companion checks if the backend change affects a shared contract.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) for the broader decision rule.\n", "2.0": "+++\ntitle = \"Backend Overview\"\n+++\n\nThe backend is the policy and integration layer between the browser-facing product and the storage systems Sambee works with.\n\n## What the Backend Owns\n\nThe backend is responsible for:\n\n- authentication and authorization\n- API endpoints consumed by the browser app and companion flows\n- SMB access and server-side file operations\n- server-side preview and download behavior where the product needs it\n- edit-lock and conflict-handling behavior for companion-assisted editing\n- directory-change notification and other state that must stay authoritative on the server side\n\n## Main Code Areas\n\nThe exact module layout evolves, but the backend is organized around a few stable concerns.\n\n| Area | Responsibility |\n|---|---|\n| `backend/app/api/` | request handlers and HTTP-facing endpoints |\n| `backend/app/models/` | API and domain models used across request and response boundaries |\n| `backend/app/storage/` | storage backends and storage-facing behavior, including SMB access |\n| `backend/app/services/` | longer-running or cross-cutting service behavior such as monitoring and background coordination |\n| `backend/app/db/` | database setup and models for persisted application state |\n| `backend/tests/` | pytest coverage for server behavior and contracts |\n\n## Request and Storage Flow\n\nFor the common SMB flow:\n\n1. The frontend issues an authenticated API request.\n2. The backend validates input and permissions.\n3. The backend performs the requested SMB operation through the storage layer.\n4. The backend returns a typed response the frontend or companion can rely on.\n\nThis is why the backend, not the browser, is the source of truth for SMB semantics and conflict-sensitive operations.\n\nIf you need the detailed layer breakdown, continue to [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/).\n\n## Important Backend Contracts\n\n### API Contract Stability\n\nThe frontend relies on typed request and response shapes. That is why contract testing guidance exists and why contributors should treat API shape changes as user-visible changes, not internal refactors.\n\n### File-Type and Preview Behavior\n\nThe backend contributes to preview behavior through MIME detection, file-type classification, and conversion decisions for formats that are not natively browser-friendly. Those rules have to stay aligned with frontend expectations.\n\n### Edit Locking and Companion Flows\n\nFor companion-assisted editing of SMB-backed files, the backend owns the server-side lock, heartbeat, upload, and conflict rules. A desktop-side improvement that ignores those rules can easily create data-loss regressions.\n\nFor the full lifecycle, continue to [File Operations and Edit Locking](../file-operations-and-edit-locking/).\n\n### Change Notification\n\nThe backend also owns SMB-side change monitoring and the notifications that tell browser clients when directory state should refresh.\n\nFor the watcher architecture, subscriber model, and cache-freshness split, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## What Usually Breaks When This Layer Changes\n\n- frontend assumptions about response shape\n- viewer or file-management behavior that depends on MIME or category detection\n- companion editing flows that depend on lock or upload semantics\n- directory freshness in the browser when change notifications stop matching product expectations\n\n## Go Deeper\n\n- [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/): how API, models, storage, services, and WebSocket coordination fit together\n- [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/): how backend watchers, WebSocket notifications, and cache freshness fit together\n- [File Operations and Edit Locking](../file-operations-and-edit-locking/): how ordinary file operations differ from companion-assisted SMB editing and lock handling\n\n## Validation Expectations\n\nWhen the backend changes, start with:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nThen add frontend or companion checks if the backend change affects a shared contract.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) for the broader decision rule.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Backend Overview\"\n+++\n\nThe backend is the policy and integration layer between the browser-facing product and the storage systems Sambee works with.\n\n## What the Backend Owns\n\nThe backend is responsible for:\n\n- authentication and authorization\n- API endpoints consumed by the browser app and companion flows\n- SMB access and server-side file operations\n- server-side preview and download behavior where the product needs it\n- edit-lock and conflict-handling behavior for companion-assisted editing\n- directory-change notification and other state that must stay authoritative on the server side\n\n## Main Code Areas\n\nThe exact module layout evolves, but the backend is organized around a few stable concerns.\n\n| Area | Responsibility |\n|---|---|\n| `backend/app/api/` | request handlers and HTTP-facing endpoints |\n| `backend/app/models/` | API and domain models used across request and response boundaries |\n| `backend/app/storage/` | storage backends and storage-facing behavior, including SMB access |\n| `backend/app/services/` | longer-running or cross-cutting service behavior such as monitoring and background coordination |\n| `backend/app/db/` | database setup and models for persisted application state |\n| `backend/tests/` | pytest coverage for server behavior and contracts |\n\n## Request and Storage Flow\n\nFor the common SMB flow:\n\n1. The frontend issues an authenticated API request.\n2. The backend validates input and permissions.\n3. The backend performs the requested SMB operation through the storage layer.\n4. The backend returns a typed response the frontend or companion can rely on.\n\nThis is why the backend, not the browser, is the source of truth for SMB semantics and conflict-sensitive operations.\n\nIf you need the detailed layer breakdown, continue to [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/).\n\n## Important Backend Contracts\n\n### API Contract Stability\n\nThe frontend relies on typed request and response shapes. That is why contract testing guidance exists and why contributors should treat API shape changes as user-visible changes, not internal refactors.\n\n### File-Type and Preview Behavior\n\nThe backend contributes to preview behavior through MIME detection, file-type classification, and conversion decisions for formats that are not natively browser-friendly. Those rules have to stay aligned with frontend expectations.\n\n### Edit Locking and Companion Flows\n\nFor companion-assisted editing of SMB-backed files, the backend owns the server-side lock, heartbeat, upload, and conflict rules. A desktop-side improvement that ignores those rules can easily create data-loss regressions.\n\nFor the full lifecycle, continue to [File Operations and Edit Locking](../file-operations-and-edit-locking/).\n\n### Change Notification\n\nThe backend also owns SMB-side change monitoring and the notifications that tell browser clients when directory state should refresh.\n\nFor the watcher architecture, subscriber model, and cache-freshness split, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## What Usually Breaks When This Layer Changes\n\n- frontend assumptions about response shape\n- viewer or file-management behavior that depends on MIME or category detection\n- companion editing flows that depend on lock or upload semantics\n- directory freshness in the browser when change notifications stop matching product expectations\n\n## Go Deeper\n\n- [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/): how API, models, storage, services, and WebSocket coordination fit together\n- [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/): how backend watchers, WebSocket notifications, and cache freshness fit together\n- [File Operations and Edit Locking](../file-operations-and-edit-locking/): how ordinary file operations differ from companion-assisted SMB editing and lock handling\n\n## Validation Expectations\n\nWhen the backend changes, start with:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nThen add frontend or companion checks if the backend change affects a shared contract.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) for the broader decision rule.\n", "0.8": "+++\ntitle = \"Backend Overview\"\n+++\n\nThe backend is the policy and integration layer between the browser-facing product and the storage systems Sambee works with.\n\n## What the Backend Owns\n\nThe backend is responsible for:\n\n- authentication and authorization\n- API endpoints consumed by the browser app and companion flows\n- SMB access and server-side file operations\n- server-side preview and download behavior where the product needs it\n- edit-lock and conflict-handling behavior for companion-assisted editing\n- directory-change notification and other state that must stay authoritative on the server side\n\n## Main Code Areas\n\nThe exact module layout evolves, but the backend is organized around a few stable concerns.\n\n| Area | Responsibility |\n|---|---|\n| `backend/app/api/` | request handlers and HTTP-facing endpoints |\n| `backend/app/models/` | API and domain models used across request and response boundaries |\n| `backend/app/storage/` | storage backends and storage-facing behavior, including SMB access |\n| `backend/app/services/` | longer-running or cross-cutting service behavior such as monitoring and background coordination |\n| `backend/app/db/` | database setup and models for persisted application state |\n| `backend/tests/` | pytest coverage for server behavior and contracts |\n\n## Request and Storage Flow\n\nFor the common SMB flow:\n\n1. The frontend issues an authenticated API request.\n2. The backend validates input and permissions.\n3. The backend performs the requested SMB operation through the storage layer.\n4. The backend returns a typed response the frontend or companion can rely on.\n\nThis is why the backend, not the browser, is the source of truth for SMB semantics and conflict-sensitive operations.\n\nIf you need the detailed layer breakdown, continue to [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/).\n\n## Important Backend Contracts\n\n### API Contract Stability\n\nThe frontend relies on typed request and response shapes. That is why contract testing guidance exists and why contributors should treat API shape changes as user-visible changes, not internal refactors.\n\n### File-Type and Preview Behavior\n\nThe backend contributes to preview behavior through MIME detection, file-type classification, and conversion decisions for formats that are not natively browser-friendly. Those rules have to stay aligned with frontend expectations.\n\n### Edit Locking and Companion Flows\n\nFor companion-assisted editing of SMB-backed files, the backend owns the server-side lock, heartbeat, upload, and conflict rules. A desktop-side improvement that ignores those rules can easily create data-loss regressions.\n\nFor the full lifecycle, continue to [File Operations and Edit Locking](../file-operations-and-edit-locking/).\n\n### Change Notification\n\nThe backend also owns SMB-side change monitoring and the notifications that tell browser clients when directory state should refresh.\n\nFor the watcher architecture, subscriber model, and cache-freshness split, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## What Usually Breaks When This Layer Changes\n\n- frontend assumptions about response shape\n- viewer or file-management behavior that depends on MIME or category detection\n- companion editing flows that depend on lock or upload semantics\n- directory freshness in the browser when change notifications stop matching product expectations\n\n## Go Deeper\n\n- [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/): how API, models, storage, services, and WebSocket coordination fit together\n- [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/): how backend watchers, WebSocket notifications, and cache freshness fit together\n- [File Operations and Edit Locking](../file-operations-and-edit-locking/): how ordinary file operations differ from companion-assisted SMB editing and lock handling\n\n## Validation Expectations\n\nWhen the backend changes, start with:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nThen add frontend or companion checks if the backend change affects a shared contract.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) for the broader decision rule.\n", "0.9": "+++\ntitle = \"Backend Overview\"\n+++\n\nThe backend is the policy and integration layer between the browser-facing product and the storage systems Sambee works with.\n\n## What the Backend Owns\n\nThe backend is responsible for:\n\n- authentication and authorization\n- API endpoints consumed by the browser app and companion flows\n- SMB access and server-side file operations\n- server-side preview and download behavior where the product needs it\n- edit-lock and conflict-handling behavior for companion-assisted editing\n- directory-change notification and other state that must stay authoritative on the server side\n\n## Main Code Areas\n\nThe exact module layout evolves, but the backend is organized around a few stable concerns.\n\n| Area | Responsibility |\n|---|---|\n| `backend/app/api/` | request handlers and HTTP-facing endpoints |\n| `backend/app/models/` | API and domain models used across request and response boundaries |\n| `backend/app/storage/` | storage backends and storage-facing behavior, including SMB access |\n| `backend/app/services/` | longer-running or cross-cutting service behavior such as monitoring and background coordination |\n| `backend/app/db/` | database setup and models for persisted application state |\n| `backend/tests/` | pytest coverage for server behavior and contracts |\n\n## Request and Storage Flow\n\nFor the common SMB flow:\n\n1. The frontend issues an authenticated API request.\n2. The backend validates input and permissions.\n3. The backend performs the requested SMB operation through the storage layer.\n4. The backend returns a typed response the frontend or companion can rely on.\n\nThis is why the backend, not the browser, is the source of truth for SMB semantics and conflict-sensitive operations.\n\nIf you need the detailed layer breakdown, continue to [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/).\n\n## Important Backend Contracts\n\n### API Contract Stability\n\nThe frontend relies on typed request and response shapes. That is why contract testing guidance exists and why contributors should treat API shape changes as user-visible changes, not internal refactors.\n\n### File-Type and Preview Behavior\n\nThe backend contributes to preview behavior through MIME detection, file-type classification, and conversion decisions for formats that are not natively browser-friendly. Those rules have to stay aligned with frontend expectations.\n\n### Edit Locking and Companion Flows\n\nFor companion-assisted editing of SMB-backed files, the backend owns the server-side lock, heartbeat, upload, and conflict rules. A desktop-side improvement that ignores those rules can easily create data-loss regressions.\n\nFor the full lifecycle, continue to [File Operations and Edit Locking](../file-operations-and-edit-locking/).\n\n### Change Notification\n\nThe backend also owns SMB-side change monitoring and the notifications that tell browser clients when directory state should refresh.\n\nFor the watcher architecture, subscriber model, and cache-freshness split, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## What Usually Breaks When This Layer Changes\n\n- frontend assumptions about response shape\n- viewer or file-management behavior that depends on MIME or category detection\n- companion editing flows that depend on lock or upload semantics\n- directory freshness in the browser when change notifications stop matching product expectations\n\n## Go Deeper\n\n- [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/): how API, models, storage, services, and WebSocket coordination fit together\n- [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/): how backend watchers, WebSocket notifications, and cache freshness fit together\n- [File Operations and Edit Locking](../file-operations-and-edit-locking/): how ordinary file operations differ from companion-assisted SMB editing and lock handling\n\n## Validation Expectations\n\nWhen the backend changes, start with:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nThen add frontend or companion checks if the backend change affects a shared contract.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) for the broader decision rule.\n", "1.0": "+++\ntitle = \"Backend Overview\"\n+++\n\nThe backend is the policy and integration layer between the browser-facing product and the storage systems Sambee works with.\n\n## What the Backend Owns\n\nThe backend is responsible for:\n\n- authentication and authorization\n- API endpoints consumed by the browser app and companion flows\n- SMB access and server-side file operations\n- server-side preview and download behavior where the product needs it\n- edit-lock and conflict-handling behavior for companion-assisted editing\n- directory-change notification and other state that must stay authoritative on the server side\n\n## Main Code Areas\n\nThe exact module layout evolves, but the backend is organized around a few stable concerns.\n\n| Area | Responsibility |\n|---|---|\n| `backend/app/api/` | request handlers and HTTP-facing endpoints |\n| `backend/app/models/` | API and domain models used across request and response boundaries |\n| `backend/app/storage/` | storage backends and storage-facing behavior, including SMB access |\n| `backend/app/services/` | longer-running or cross-cutting service behavior such as monitoring and background coordination |\n| `backend/app/db/` | database setup and models for persisted application state |\n| `backend/tests/` | pytest coverage for server behavior and contracts |\n\n## Request and Storage Flow\n\nFor the common SMB flow:\n\n1. The frontend issues an authenticated API request.\n2. The backend validates input and permissions.\n3. The backend performs the requested SMB operation through the storage layer.\n4. The backend returns a typed response the frontend or companion can rely on.\n\nThis is why the backend, not the browser, is the source of truth for SMB semantics and conflict-sensitive operations.\n\nIf you need the detailed layer breakdown, continue to [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/).\n\n## Important Backend Contracts\n\n### API Contract Stability\n\nThe frontend relies on typed request and response shapes. That is why contract testing guidance exists and why contributors should treat API shape changes as user-visible changes, not internal refactors.\n\n### File-Type and Preview Behavior\n\nThe backend contributes to preview behavior through MIME detection, file-type classification, and conversion decisions for formats that are not natively browser-friendly. Those rules have to stay aligned with frontend expectations.\n\n### Edit Locking and Companion Flows\n\nFor companion-assisted editing of SMB-backed files, the backend owns the server-side lock, heartbeat, upload, and conflict rules. A desktop-side improvement that ignores those rules can easily create data-loss regressions.\n\nFor the full lifecycle, continue to [File Operations and Edit Locking](../file-operations-and-edit-locking/).\n\n### Change Notification\n\nThe backend also owns SMB-side change monitoring and the notifications that tell browser clients when directory state should refresh.\n\nFor the watcher architecture, subscriber model, and cache-freshness split, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## What Usually Breaks When This Layer Changes\n\n- frontend assumptions about response shape\n- viewer or file-management behavior that depends on MIME or category detection\n- companion editing flows that depend on lock or upload semantics\n- directory freshness in the browser when change notifications stop matching product expectations\n\n## Go Deeper\n\n- [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/): how API, models, storage, services, and WebSocket coordination fit together\n- [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/): how backend watchers, WebSocket notifications, and cache freshness fit together\n- [File Operations and Edit Locking](../file-operations-and-edit-locking/): how ordinary file operations differ from companion-assisted SMB editing and lock handling\n\n## Validation Expectations\n\nWhen the backend changes, start with:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nThen add frontend or companion checks if the backend change affects a shared contract.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) for the broader decision rule.\n", "2.0": "+++\ntitle = \"Backend Overview\"\n+++\n\nThe backend is the policy and integration layer between the browser-facing product and the storage systems Sambee works with.\n\n## What the Backend Owns\n\nThe backend is responsible for:\n\n- authentication and authorization\n- API endpoints consumed by the browser app and companion flows\n- SMB access and server-side file operations\n- server-side preview and download behavior where the product needs it\n- edit-lock and conflict-handling behavior for companion-assisted editing\n- directory-change notification and other state that must stay authoritative on the server side\n\n## Main Code Areas\n\nThe exact module layout evolves, but the backend is organized around a few stable concerns.\n\n| Area | Responsibility |\n|---|---|\n| `backend/app/api/` | request handlers and HTTP-facing endpoints |\n| `backend/app/models/` | API and domain models used across request and response boundaries |\n| `backend/app/storage/` | storage backends and storage-facing behavior, including SMB access |\n| `backend/app/services/` | longer-running or cross-cutting service behavior such as monitoring and background coordination |\n| `backend/app/db/` | database setup and models for persisted application state |\n| `backend/tests/` | pytest coverage for server behavior and contracts |\n\n## Request and Storage Flow\n\nFor the common SMB flow:\n\n1. The frontend issues an authenticated API request.\n2. The backend validates input and permissions.\n3. The backend performs the requested SMB operation through the storage layer.\n4. The backend returns a typed response the frontend or companion can rely on.\n\nThis is why the backend, not the browser, is the source of truth for SMB semantics and conflict-sensitive operations.\n\nIf you need the detailed layer breakdown, continue to [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/).\n\n## Important Backend Contracts\n\n### API Contract Stability\n\nThe frontend relies on typed request and response shapes. That is why contract testing guidance exists and why contributors should treat API shape changes as user-visible changes, not internal refactors.\n\n### File-Type and Preview Behavior\n\nThe backend contributes to preview behavior through MIME detection, file-type classification, and conversion decisions for formats that are not natively browser-friendly. Those rules have to stay aligned with frontend expectations.\n\n### Edit Locking and Companion Flows\n\nFor companion-assisted editing of SMB-backed files, the backend owns the server-side lock, heartbeat, upload, and conflict rules. A desktop-side improvement that ignores those rules can easily create data-loss regressions.\n\nFor the full lifecycle, continue to [File Operations and Edit Locking](../file-operations-and-edit-locking/).\n\n### Change Notification\n\nThe backend also owns SMB-side change monitoring and the notifications that tell browser clients when directory state should refresh.\n\nFor the watcher architecture, subscriber model, and cache-freshness split, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## What Usually Breaks When This Layer Changes\n\n- frontend assumptions about response shape\n- viewer or file-management behavior that depends on MIME or category detection\n- companion editing flows that depend on lock or upload semantics\n- directory freshness in the browser when change notifications stop matching product expectations\n\n## Go Deeper\n\n- [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/): how API, models, storage, services, and WebSocket coordination fit together\n- [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/): how backend watchers, WebSocket notifications, and cache freshness fit together\n- [File Operations and Edit Locking](../file-operations-and-edit-locking/): how ordinary file operations differ from companion-assisted SMB editing and lock handling\n\n## Validation Expectations\n\nWhen the backend changes, start with:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nThen add frontend or companion checks if the backend change affects a shared contract.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) for the broader decision rule.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/backend-architecture/request-flow-and-service-boundaries", "parent_id": "section:developer-guide/backend-architecture", "depth": 2, "kind": "page", "label": "request-flow-and-service-boundaries", "title": "Request Flow And Service Boundaries", "path": "developer-guide/backend-architecture/request-flow-and-service-boundaries", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Request Flow and Service Boundaries\"\n+++\n\nThe backend is easiest to change safely when you treat it as layered coordination instead of one large request handler.\n\n## The Main Boundaries\n\n| Area | What it should own |\n|---|---|\n| `backend/app/api/` | HTTP and WebSocket entry points, request parsing, response shaping, and protocol-specific concerns |\n| `backend/app/models/` | request and response models plus typed data contracts |\n| `backend/app/storage/` | storage-facing behavior such as SMB operations and file handling |\n| `backend/app/services/` | cross-request or longer-lived coordination such as directory monitoring or image conversion |\n| `backend/app/db/` | persisted application state and database integration |\n\nContributors get into trouble when logic that belongs in one boundary starts leaking into another.\n\n## Common Request Paths\n\n### Standard Browser API Flow\n\nFor a typical browse or file-management request:\n\n1. a handler in `backend/app/api/` receives the request\n2. request data is validated against typed models\n3. the handler calls storage or service logic\n4. the backend returns a typed response for the frontend to consume\n\nThe handler should remain the HTTP-facing boundary, not the place where SMB implementation details accumulate.\n\n### Viewer and Preview Flow\n\nPreview-related requests are not just file streaming.\n\nThey can involve:\n\n- MIME classification through the file-type registry\n- conversion decisions for non-browser-native images\n- streaming or materialized responses depending on the format\n\nThis is one reason preview behavior spans both `api/`, `utils/`, and `services/` code.\n\nIf the change affects server-side conversion or preprocessing, continue to [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/).\n\n### Directory-Change Flow\n\nDirectory freshness is coordinated through a service boundary.\n\n1. the WebSocket layer manages subscriptions\n2. the directory monitor owns SMB-side watcher lifecycle for browser subscriptions\n3. the directory cache uses its own watcher path to keep connection-level directory-search data fresh\n4. change notifications are pushed back to subscribed clients when browser-visible refresh is needed\n\nThat split matters because connection recovery and handle cleanup are not ordinary request work.\n\nIf the change affects watcher lifecycle, subscriber bookkeeping, or directory freshness behavior, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## Why the Layering Matters\n\n### API Contracts\n\nThe frontend and companion depend on stable request and response shapes. If you change an API contract, you are changing a cross-boundary contract, not just moving code around.\n\n### Storage Semantics\n\nThe storage layer is where SMB-specific behavior belongs. It should not be reimplemented ad hoc in handlers just because a feature needs a quick change.\n\n### Long-Lived Coordination\n\nBackground coordination such as directory monitoring belongs in services because it outlives one request and needs explicit lifecycle management.\n\n## Signs the Boundary Is Slipping\n\n- request handlers know too much about SMB implementation details\n- the same response-shaping logic is duplicated across endpoints\n- storage helpers start taking HTTP-specific parameters\n- service-level coordination is recreated inside one endpoint instead of reused\n\n## Where to Continue\n\n- Use [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/) when the change affects the backend preview pipeline, conversion policy, or preprocessor behavior.\n- Use [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/) when the change affects watcher lifecycle, WebSocket refresh behavior, or directory-cache freshness.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the change affects create, rename, copy, move, upload, or companion-assisted editing.\n- Use [Frontend Overview](../../frontend-architecture/frontend-overview/) when the backend change alters browser-visible workflow behavior.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the changed boundary requires broader validation.\n", "0.8": "+++\ntitle = \"Request Flow and Service Boundaries\"\n+++\n\nThe backend is easiest to change safely when you treat it as layered coordination instead of one large request handler.\n\n## The Main Boundaries\n\n| Area | What it should own |\n|---|---|\n| `backend/app/api/` | HTTP and WebSocket entry points, request parsing, response shaping, and protocol-specific concerns |\n| `backend/app/models/` | request and response models plus typed data contracts |\n| `backend/app/storage/` | storage-facing behavior such as SMB operations and file handling |\n| `backend/app/services/` | cross-request or longer-lived coordination such as directory monitoring or image conversion |\n| `backend/app/db/` | persisted application state and database integration |\n\nContributors get into trouble when logic that belongs in one boundary starts leaking into another.\n\n## Common Request Paths\n\n### Standard Browser API Flow\n\nFor a typical browse or file-management request:\n\n1. a handler in `backend/app/api/` receives the request\n2. request data is validated against typed models\n3. the handler calls storage or service logic\n4. the backend returns a typed response for the frontend to consume\n\nThe handler should remain the HTTP-facing boundary, not the place where SMB implementation details accumulate.\n\n### Viewer and Preview Flow\n\nPreview-related requests are not just file streaming.\n\nThey can involve:\n\n- MIME classification through the file-type registry\n- conversion decisions for non-browser-native images\n- streaming or materialized responses depending on the format\n\nThis is one reason preview behavior spans both `api/`, `utils/`, and `services/` code.\n\nIf the change affects server-side conversion or preprocessing, continue to [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/).\n\n### Directory-Change Flow\n\nDirectory freshness is coordinated through a service boundary.\n\n1. the WebSocket layer manages subscriptions\n2. the directory monitor owns SMB-side watcher lifecycle for browser subscriptions\n3. the directory cache uses its own watcher path to keep connection-level directory-search data fresh\n4. change notifications are pushed back to subscribed clients when browser-visible refresh is needed\n\nThat split matters because connection recovery and handle cleanup are not ordinary request work.\n\nIf the change affects watcher lifecycle, subscriber bookkeeping, or directory freshness behavior, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## Why the Layering Matters\n\n### API Contracts\n\nThe frontend and companion depend on stable request and response shapes. If you change an API contract, you are changing a cross-boundary contract, not just moving code around.\n\n### Storage Semantics\n\nThe storage layer is where SMB-specific behavior belongs. It should not be reimplemented ad hoc in handlers just because a feature needs a quick change.\n\n### Long-Lived Coordination\n\nBackground coordination such as directory monitoring belongs in services because it outlives one request and needs explicit lifecycle management.\n\n## Signs the Boundary Is Slipping\n\n- request handlers know too much about SMB implementation details\n- the same response-shaping logic is duplicated across endpoints\n- storage helpers start taking HTTP-specific parameters\n- service-level coordination is recreated inside one endpoint instead of reused\n\n## Where to Continue\n\n- Use [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/) when the change affects the backend preview pipeline, conversion policy, or preprocessor behavior.\n- Use [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/) when the change affects watcher lifecycle, WebSocket refresh behavior, or directory-cache freshness.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the change affects create, rename, copy, move, upload, or companion-assisted editing.\n- Use [Frontend Overview](../../frontend-architecture/frontend-overview/) when the backend change alters browser-visible workflow behavior.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the changed boundary requires broader validation.\n", "0.9": "+++\ntitle = \"Request Flow and Service Boundaries\"\n+++\n\nThe backend is easiest to change safely when you treat it as layered coordination instead of one large request handler.\n\n## The Main Boundaries\n\n| Area | What it should own |\n|---|---|\n| `backend/app/api/` | HTTP and WebSocket entry points, request parsing, response shaping, and protocol-specific concerns |\n| `backend/app/models/` | request and response models plus typed data contracts |\n| `backend/app/storage/` | storage-facing behavior such as SMB operations and file handling |\n| `backend/app/services/` | cross-request or longer-lived coordination such as directory monitoring or image conversion |\n| `backend/app/db/` | persisted application state and database integration |\n\nContributors get into trouble when logic that belongs in one boundary starts leaking into another.\n\n## Common Request Paths\n\n### Standard Browser API Flow\n\nFor a typical browse or file-management request:\n\n1. a handler in `backend/app/api/` receives the request\n2. request data is validated against typed models\n3. the handler calls storage or service logic\n4. the backend returns a typed response for the frontend to consume\n\nThe handler should remain the HTTP-facing boundary, not the place where SMB implementation details accumulate.\n\n### Viewer and Preview Flow\n\nPreview-related requests are not just file streaming.\n\nThey can involve:\n\n- MIME classification through the file-type registry\n- conversion decisions for non-browser-native images\n- streaming or materialized responses depending on the format\n\nThis is one reason preview behavior spans both `api/`, `utils/`, and `services/` code.\n\nIf the change affects server-side conversion or preprocessing, continue to [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/).\n\n### Directory-Change Flow\n\nDirectory freshness is coordinated through a service boundary.\n\n1. the WebSocket layer manages subscriptions\n2. the directory monitor owns SMB-side watcher lifecycle for browser subscriptions\n3. the directory cache uses its own watcher path to keep connection-level directory-search data fresh\n4. change notifications are pushed back to subscribed clients when browser-visible refresh is needed\n\nThat split matters because connection recovery and handle cleanup are not ordinary request work.\n\nIf the change affects watcher lifecycle, subscriber bookkeeping, or directory freshness behavior, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## Why the Layering Matters\n\n### API Contracts\n\nThe frontend and companion depend on stable request and response shapes. If you change an API contract, you are changing a cross-boundary contract, not just moving code around.\n\n### Storage Semantics\n\nThe storage layer is where SMB-specific behavior belongs. It should not be reimplemented ad hoc in handlers just because a feature needs a quick change.\n\n### Long-Lived Coordination\n\nBackground coordination such as directory monitoring belongs in services because it outlives one request and needs explicit lifecycle management.\n\n## Signs the Boundary Is Slipping\n\n- request handlers know too much about SMB implementation details\n- the same response-shaping logic is duplicated across endpoints\n- storage helpers start taking HTTP-specific parameters\n- service-level coordination is recreated inside one endpoint instead of reused\n\n## Where to Continue\n\n- Use [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/) when the change affects the backend preview pipeline, conversion policy, or preprocessor behavior.\n- Use [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/) when the change affects watcher lifecycle, WebSocket refresh behavior, or directory-cache freshness.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the change affects create, rename, copy, move, upload, or companion-assisted editing.\n- Use [Frontend Overview](../../frontend-architecture/frontend-overview/) when the backend change alters browser-visible workflow behavior.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the changed boundary requires broader validation.\n", "1.0": "+++\ntitle = \"Request Flow and Service Boundaries\"\n+++\n\nThe backend is easiest to change safely when you treat it as layered coordination instead of one large request handler.\n\n## The Main Boundaries\n\n| Area | What it should own |\n|---|---|\n| `backend/app/api/` | HTTP and WebSocket entry points, request parsing, response shaping, and protocol-specific concerns |\n| `backend/app/models/` | request and response models plus typed data contracts |\n| `backend/app/storage/` | storage-facing behavior such as SMB operations and file handling |\n| `backend/app/services/` | cross-request or longer-lived coordination such as directory monitoring or image conversion |\n| `backend/app/db/` | persisted application state and database integration |\n\nContributors get into trouble when logic that belongs in one boundary starts leaking into another.\n\n## Common Request Paths\n\n### Standard Browser API Flow\n\nFor a typical browse or file-management request:\n\n1. a handler in `backend/app/api/` receives the request\n2. request data is validated against typed models\n3. the handler calls storage or service logic\n4. the backend returns a typed response for the frontend to consume\n\nThe handler should remain the HTTP-facing boundary, not the place where SMB implementation details accumulate.\n\n### Viewer and Preview Flow\n\nPreview-related requests are not just file streaming.\n\nThey can involve:\n\n- MIME classification through the file-type registry\n- conversion decisions for non-browser-native images\n- streaming or materialized responses depending on the format\n\nThis is one reason preview behavior spans both `api/`, `utils/`, and `services/` code.\n\nIf the change affects server-side conversion or preprocessing, continue to [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/).\n\n### Directory-Change Flow\n\nDirectory freshness is coordinated through a service boundary.\n\n1. the WebSocket layer manages subscriptions\n2. the directory monitor owns SMB-side watcher lifecycle for browser subscriptions\n3. the directory cache uses its own watcher path to keep connection-level directory-search data fresh\n4. change notifications are pushed back to subscribed clients when browser-visible refresh is needed\n\nThat split matters because connection recovery and handle cleanup are not ordinary request work.\n\nIf the change affects watcher lifecycle, subscriber bookkeeping, or directory freshness behavior, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## Why the Layering Matters\n\n### API Contracts\n\nThe frontend and companion depend on stable request and response shapes. If you change an API contract, you are changing a cross-boundary contract, not just moving code around.\n\n### Storage Semantics\n\nThe storage layer is where SMB-specific behavior belongs. It should not be reimplemented ad hoc in handlers just because a feature needs a quick change.\n\n### Long-Lived Coordination\n\nBackground coordination such as directory monitoring belongs in services because it outlives one request and needs explicit lifecycle management.\n\n## Signs the Boundary Is Slipping\n\n- request handlers know too much about SMB implementation details\n- the same response-shaping logic is duplicated across endpoints\n- storage helpers start taking HTTP-specific parameters\n- service-level coordination is recreated inside one endpoint instead of reused\n\n## Where to Continue\n\n- Use [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/) when the change affects the backend preview pipeline, conversion policy, or preprocessor behavior.\n- Use [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/) when the change affects watcher lifecycle, WebSocket refresh behavior, or directory-cache freshness.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the change affects create, rename, copy, move, upload, or companion-assisted editing.\n- Use [Frontend Overview](../../frontend-architecture/frontend-overview/) when the backend change alters browser-visible workflow behavior.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the changed boundary requires broader validation.\n", "2.0": "+++\ntitle = \"Request Flow and Service Boundaries\"\n+++\n\nThe backend is easiest to change safely when you treat it as layered coordination instead of one large request handler.\n\n## The Main Boundaries\n\n| Area | What it should own |\n|---|---|\n| `backend/app/api/` | HTTP and WebSocket entry points, request parsing, response shaping, and protocol-specific concerns |\n| `backend/app/models/` | request and response models plus typed data contracts |\n| `backend/app/storage/` | storage-facing behavior such as SMB operations and file handling |\n| `backend/app/services/` | cross-request or longer-lived coordination such as directory monitoring or image conversion |\n| `backend/app/db/` | persisted application state and database integration |\n\nContributors get into trouble when logic that belongs in one boundary starts leaking into another.\n\n## Common Request Paths\n\n### Standard Browser API Flow\n\nFor a typical browse or file-management request:\n\n1. a handler in `backend/app/api/` receives the request\n2. request data is validated against typed models\n3. the handler calls storage or service logic\n4. the backend returns a typed response for the frontend to consume\n\nThe handler should remain the HTTP-facing boundary, not the place where SMB implementation details accumulate.\n\n### Viewer and Preview Flow\n\nPreview-related requests are not just file streaming.\n\nThey can involve:\n\n- MIME classification through the file-type registry\n- conversion decisions for non-browser-native images\n- streaming or materialized responses depending on the format\n\nThis is one reason preview behavior spans both `api/`, `utils/`, and `services/` code.\n\nIf the change affects server-side conversion or preprocessing, continue to [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/).\n\n### Directory-Change Flow\n\nDirectory freshness is coordinated through a service boundary.\n\n1. the WebSocket layer manages subscriptions\n2. the directory monitor owns SMB-side watcher lifecycle for browser subscriptions\n3. the directory cache uses its own watcher path to keep connection-level directory-search data fresh\n4. change notifications are pushed back to subscribed clients when browser-visible refresh is needed\n\nThat split matters because connection recovery and handle cleanup are not ordinary request work.\n\nIf the change affects watcher lifecycle, subscriber bookkeeping, or directory freshness behavior, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## Why the Layering Matters\n\n### API Contracts\n\nThe frontend and companion depend on stable request and response shapes. If you change an API contract, you are changing a cross-boundary contract, not just moving code around.\n\n### Storage Semantics\n\nThe storage layer is where SMB-specific behavior belongs. It should not be reimplemented ad hoc in handlers just because a feature needs a quick change.\n\n### Long-Lived Coordination\n\nBackground coordination such as directory monitoring belongs in services because it outlives one request and needs explicit lifecycle management.\n\n## Signs the Boundary Is Slipping\n\n- request handlers know too much about SMB implementation details\n- the same response-shaping logic is duplicated across endpoints\n- storage helpers start taking HTTP-specific parameters\n- service-level coordination is recreated inside one endpoint instead of reused\n\n## Where to Continue\n\n- Use [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/) when the change affects the backend preview pipeline, conversion policy, or preprocessor behavior.\n- Use [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/) when the change affects watcher lifecycle, WebSocket refresh behavior, or directory-cache freshness.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the change affects create, rename, copy, move, upload, or companion-assisted editing.\n- Use [Frontend Overview](../../frontend-architecture/frontend-overview/) when the backend change alters browser-visible workflow behavior.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the changed boundary requires broader validation.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Request Flow and Service Boundaries\"\n+++\n\nThe backend is easiest to change safely when you treat it as layered coordination instead of one large request handler.\n\n## The Main Boundaries\n\n| Area | What it should own |\n|---|---|\n| `backend/app/api/` | HTTP and WebSocket entry points, request parsing, response shaping, and protocol-specific concerns |\n| `backend/app/models/` | request and response models plus typed data contracts |\n| `backend/app/storage/` | storage-facing behavior such as SMB operations and file handling |\n| `backend/app/services/` | cross-request or longer-lived coordination such as directory monitoring or image conversion |\n| `backend/app/db/` | persisted application state and database integration |\n\nContributors get into trouble when logic that belongs in one boundary starts leaking into another.\n\n## Common Request Paths\n\n### Standard Browser API Flow\n\nFor a typical browse or file-management request:\n\n1. a handler in `backend/app/api/` receives the request\n2. request data is validated against typed models\n3. the handler calls storage or service logic\n4. the backend returns a typed response for the frontend to consume\n\nThe handler should remain the HTTP-facing boundary, not the place where SMB implementation details accumulate.\n\n### Viewer and Preview Flow\n\nPreview-related requests are not just file streaming.\n\nThey can involve:\n\n- MIME classification through the file-type registry\n- conversion decisions for non-browser-native images\n- streaming or materialized responses depending on the format\n\nThis is one reason preview behavior spans both `api/`, `utils/`, and `services/` code.\n\nIf the change affects server-side conversion or preprocessing, continue to [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/).\n\n### Directory-Change Flow\n\nDirectory freshness is coordinated through a service boundary.\n\n1. the WebSocket layer manages subscriptions\n2. the directory monitor owns SMB-side watcher lifecycle for browser subscriptions\n3. the directory cache uses its own watcher path to keep connection-level directory-search data fresh\n4. change notifications are pushed back to subscribed clients when browser-visible refresh is needed\n\nThat split matters because connection recovery and handle cleanup are not ordinary request work.\n\nIf the change affects watcher lifecycle, subscriber bookkeeping, or directory freshness behavior, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## Why the Layering Matters\n\n### API Contracts\n\nThe frontend and companion depend on stable request and response shapes. If you change an API contract, you are changing a cross-boundary contract, not just moving code around.\n\n### Storage Semantics\n\nThe storage layer is where SMB-specific behavior belongs. It should not be reimplemented ad hoc in handlers just because a feature needs a quick change.\n\n### Long-Lived Coordination\n\nBackground coordination such as directory monitoring belongs in services because it outlives one request and needs explicit lifecycle management.\n\n## Signs the Boundary Is Slipping\n\n- request handlers know too much about SMB implementation details\n- the same response-shaping logic is duplicated across endpoints\n- storage helpers start taking HTTP-specific parameters\n- service-level coordination is recreated inside one endpoint instead of reused\n\n## Where to Continue\n\n- Use [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/) when the change affects the backend preview pipeline, conversion policy, or preprocessor behavior.\n- Use [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/) when the change affects watcher lifecycle, WebSocket refresh behavior, or directory-cache freshness.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the change affects create, rename, copy, move, upload, or companion-assisted editing.\n- Use [Frontend Overview](../../frontend-architecture/frontend-overview/) when the backend change alters browser-visible workflow behavior.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the changed boundary requires broader validation.\n", "0.8": "+++\ntitle = \"Request Flow and Service Boundaries\"\n+++\n\nThe backend is easiest to change safely when you treat it as layered coordination instead of one large request handler.\n\n## The Main Boundaries\n\n| Area | What it should own |\n|---|---|\n| `backend/app/api/` | HTTP and WebSocket entry points, request parsing, response shaping, and protocol-specific concerns |\n| `backend/app/models/` | request and response models plus typed data contracts |\n| `backend/app/storage/` | storage-facing behavior such as SMB operations and file handling |\n| `backend/app/services/` | cross-request or longer-lived coordination such as directory monitoring or image conversion |\n| `backend/app/db/` | persisted application state and database integration |\n\nContributors get into trouble when logic that belongs in one boundary starts leaking into another.\n\n## Common Request Paths\n\n### Standard Browser API Flow\n\nFor a typical browse or file-management request:\n\n1. a handler in `backend/app/api/` receives the request\n2. request data is validated against typed models\n3. the handler calls storage or service logic\n4. the backend returns a typed response for the frontend to consume\n\nThe handler should remain the HTTP-facing boundary, not the place where SMB implementation details accumulate.\n\n### Viewer and Preview Flow\n\nPreview-related requests are not just file streaming.\n\nThey can involve:\n\n- MIME classification through the file-type registry\n- conversion decisions for non-browser-native images\n- streaming or materialized responses depending on the format\n\nThis is one reason preview behavior spans both `api/`, `utils/`, and `services/` code.\n\nIf the change affects server-side conversion or preprocessing, continue to [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/).\n\n### Directory-Change Flow\n\nDirectory freshness is coordinated through a service boundary.\n\n1. the WebSocket layer manages subscriptions\n2. the directory monitor owns SMB-side watcher lifecycle for browser subscriptions\n3. the directory cache uses its own watcher path to keep connection-level directory-search data fresh\n4. change notifications are pushed back to subscribed clients when browser-visible refresh is needed\n\nThat split matters because connection recovery and handle cleanup are not ordinary request work.\n\nIf the change affects watcher lifecycle, subscriber bookkeeping, or directory freshness behavior, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## Why the Layering Matters\n\n### API Contracts\n\nThe frontend and companion depend on stable request and response shapes. If you change an API contract, you are changing a cross-boundary contract, not just moving code around.\n\n### Storage Semantics\n\nThe storage layer is where SMB-specific behavior belongs. It should not be reimplemented ad hoc in handlers just because a feature needs a quick change.\n\n### Long-Lived Coordination\n\nBackground coordination such as directory monitoring belongs in services because it outlives one request and needs explicit lifecycle management.\n\n## Signs the Boundary Is Slipping\n\n- request handlers know too much about SMB implementation details\n- the same response-shaping logic is duplicated across endpoints\n- storage helpers start taking HTTP-specific parameters\n- service-level coordination is recreated inside one endpoint instead of reused\n\n## Where to Continue\n\n- Use [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/) when the change affects the backend preview pipeline, conversion policy, or preprocessor behavior.\n- Use [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/) when the change affects watcher lifecycle, WebSocket refresh behavior, or directory-cache freshness.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the change affects create, rename, copy, move, upload, or companion-assisted editing.\n- Use [Frontend Overview](../../frontend-architecture/frontend-overview/) when the backend change alters browser-visible workflow behavior.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the changed boundary requires broader validation.\n", "0.9": "+++\ntitle = \"Request Flow and Service Boundaries\"\n+++\n\nThe backend is easiest to change safely when you treat it as layered coordination instead of one large request handler.\n\n## The Main Boundaries\n\n| Area | What it should own |\n|---|---|\n| `backend/app/api/` | HTTP and WebSocket entry points, request parsing, response shaping, and protocol-specific concerns |\n| `backend/app/models/` | request and response models plus typed data contracts |\n| `backend/app/storage/` | storage-facing behavior such as SMB operations and file handling |\n| `backend/app/services/` | cross-request or longer-lived coordination such as directory monitoring or image conversion |\n| `backend/app/db/` | persisted application state and database integration |\n\nContributors get into trouble when logic that belongs in one boundary starts leaking into another.\n\n## Common Request Paths\n\n### Standard Browser API Flow\n\nFor a typical browse or file-management request:\n\n1. a handler in `backend/app/api/` receives the request\n2. request data is validated against typed models\n3. the handler calls storage or service logic\n4. the backend returns a typed response for the frontend to consume\n\nThe handler should remain the HTTP-facing boundary, not the place where SMB implementation details accumulate.\n\n### Viewer and Preview Flow\n\nPreview-related requests are not just file streaming.\n\nThey can involve:\n\n- MIME classification through the file-type registry\n- conversion decisions for non-browser-native images\n- streaming or materialized responses depending on the format\n\nThis is one reason preview behavior spans both `api/`, `utils/`, and `services/` code.\n\nIf the change affects server-side conversion or preprocessing, continue to [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/).\n\n### Directory-Change Flow\n\nDirectory freshness is coordinated through a service boundary.\n\n1. the WebSocket layer manages subscriptions\n2. the directory monitor owns SMB-side watcher lifecycle for browser subscriptions\n3. the directory cache uses its own watcher path to keep connection-level directory-search data fresh\n4. change notifications are pushed back to subscribed clients when browser-visible refresh is needed\n\nThat split matters because connection recovery and handle cleanup are not ordinary request work.\n\nIf the change affects watcher lifecycle, subscriber bookkeeping, or directory freshness behavior, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## Why the Layering Matters\n\n### API Contracts\n\nThe frontend and companion depend on stable request and response shapes. If you change an API contract, you are changing a cross-boundary contract, not just moving code around.\n\n### Storage Semantics\n\nThe storage layer is where SMB-specific behavior belongs. It should not be reimplemented ad hoc in handlers just because a feature needs a quick change.\n\n### Long-Lived Coordination\n\nBackground coordination such as directory monitoring belongs in services because it outlives one request and needs explicit lifecycle management.\n\n## Signs the Boundary Is Slipping\n\n- request handlers know too much about SMB implementation details\n- the same response-shaping logic is duplicated across endpoints\n- storage helpers start taking HTTP-specific parameters\n- service-level coordination is recreated inside one endpoint instead of reused\n\n## Where to Continue\n\n- Use [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/) when the change affects the backend preview pipeline, conversion policy, or preprocessor behavior.\n- Use [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/) when the change affects watcher lifecycle, WebSocket refresh behavior, or directory-cache freshness.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the change affects create, rename, copy, move, upload, or companion-assisted editing.\n- Use [Frontend Overview](../../frontend-architecture/frontend-overview/) when the backend change alters browser-visible workflow behavior.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the changed boundary requires broader validation.\n", "1.0": "+++\ntitle = \"Request Flow and Service Boundaries\"\n+++\n\nThe backend is easiest to change safely when you treat it as layered coordination instead of one large request handler.\n\n## The Main Boundaries\n\n| Area | What it should own |\n|---|---|\n| `backend/app/api/` | HTTP and WebSocket entry points, request parsing, response shaping, and protocol-specific concerns |\n| `backend/app/models/` | request and response models plus typed data contracts |\n| `backend/app/storage/` | storage-facing behavior such as SMB operations and file handling |\n| `backend/app/services/` | cross-request or longer-lived coordination such as directory monitoring or image conversion |\n| `backend/app/db/` | persisted application state and database integration |\n\nContributors get into trouble when logic that belongs in one boundary starts leaking into another.\n\n## Common Request Paths\n\n### Standard Browser API Flow\n\nFor a typical browse or file-management request:\n\n1. a handler in `backend/app/api/` receives the request\n2. request data is validated against typed models\n3. the handler calls storage or service logic\n4. the backend returns a typed response for the frontend to consume\n\nThe handler should remain the HTTP-facing boundary, not the place where SMB implementation details accumulate.\n\n### Viewer and Preview Flow\n\nPreview-related requests are not just file streaming.\n\nThey can involve:\n\n- MIME classification through the file-type registry\n- conversion decisions for non-browser-native images\n- streaming or materialized responses depending on the format\n\nThis is one reason preview behavior spans both `api/`, `utils/`, and `services/` code.\n\nIf the change affects server-side conversion or preprocessing, continue to [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/).\n\n### Directory-Change Flow\n\nDirectory freshness is coordinated through a service boundary.\n\n1. the WebSocket layer manages subscriptions\n2. the directory monitor owns SMB-side watcher lifecycle for browser subscriptions\n3. the directory cache uses its own watcher path to keep connection-level directory-search data fresh\n4. change notifications are pushed back to subscribed clients when browser-visible refresh is needed\n\nThat split matters because connection recovery and handle cleanup are not ordinary request work.\n\nIf the change affects watcher lifecycle, subscriber bookkeeping, or directory freshness behavior, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## Why the Layering Matters\n\n### API Contracts\n\nThe frontend and companion depend on stable request and response shapes. If you change an API contract, you are changing a cross-boundary contract, not just moving code around.\n\n### Storage Semantics\n\nThe storage layer is where SMB-specific behavior belongs. It should not be reimplemented ad hoc in handlers just because a feature needs a quick change.\n\n### Long-Lived Coordination\n\nBackground coordination such as directory monitoring belongs in services because it outlives one request and needs explicit lifecycle management.\n\n## Signs the Boundary Is Slipping\n\n- request handlers know too much about SMB implementation details\n- the same response-shaping logic is duplicated across endpoints\n- storage helpers start taking HTTP-specific parameters\n- service-level coordination is recreated inside one endpoint instead of reused\n\n## Where to Continue\n\n- Use [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/) when the change affects the backend preview pipeline, conversion policy, or preprocessor behavior.\n- Use [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/) when the change affects watcher lifecycle, WebSocket refresh behavior, or directory-cache freshness.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the change affects create, rename, copy, move, upload, or companion-assisted editing.\n- Use [Frontend Overview](../../frontend-architecture/frontend-overview/) when the backend change alters browser-visible workflow behavior.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the changed boundary requires broader validation.\n", "2.0": "+++\ntitle = \"Request Flow and Service Boundaries\"\n+++\n\nThe backend is easiest to change safely when you treat it as layered coordination instead of one large request handler.\n\n## The Main Boundaries\n\n| Area | What it should own |\n|---|---|\n| `backend/app/api/` | HTTP and WebSocket entry points, request parsing, response shaping, and protocol-specific concerns |\n| `backend/app/models/` | request and response models plus typed data contracts |\n| `backend/app/storage/` | storage-facing behavior such as SMB operations and file handling |\n| `backend/app/services/` | cross-request or longer-lived coordination such as directory monitoring or image conversion |\n| `backend/app/db/` | persisted application state and database integration |\n\nContributors get into trouble when logic that belongs in one boundary starts leaking into another.\n\n## Common Request Paths\n\n### Standard Browser API Flow\n\nFor a typical browse or file-management request:\n\n1. a handler in `backend/app/api/` receives the request\n2. request data is validated against typed models\n3. the handler calls storage or service logic\n4. the backend returns a typed response for the frontend to consume\n\nThe handler should remain the HTTP-facing boundary, not the place where SMB implementation details accumulate.\n\n### Viewer and Preview Flow\n\nPreview-related requests are not just file streaming.\n\nThey can involve:\n\n- MIME classification through the file-type registry\n- conversion decisions for non-browser-native images\n- streaming or materialized responses depending on the format\n\nThis is one reason preview behavior spans both `api/`, `utils/`, and `services/` code.\n\nIf the change affects server-side conversion or preprocessing, continue to [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/).\n\n### Directory-Change Flow\n\nDirectory freshness is coordinated through a service boundary.\n\n1. the WebSocket layer manages subscriptions\n2. the directory monitor owns SMB-side watcher lifecycle for browser subscriptions\n3. the directory cache uses its own watcher path to keep connection-level directory-search data fresh\n4. change notifications are pushed back to subscribed clients when browser-visible refresh is needed\n\nThat split matters because connection recovery and handle cleanup are not ordinary request work.\n\nIf the change affects watcher lifecycle, subscriber bookkeeping, or directory freshness behavior, continue to [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/).\n\n## Why the Layering Matters\n\n### API Contracts\n\nThe frontend and companion depend on stable request and response shapes. If you change an API contract, you are changing a cross-boundary contract, not just moving code around.\n\n### Storage Semantics\n\nThe storage layer is where SMB-specific behavior belongs. It should not be reimplemented ad hoc in handlers just because a feature needs a quick change.\n\n### Long-Lived Coordination\n\nBackground coordination such as directory monitoring belongs in services because it outlives one request and needs explicit lifecycle management.\n\n## Signs the Boundary Is Slipping\n\n- request handlers know too much about SMB implementation details\n- the same response-shaping logic is duplicated across endpoints\n- storage helpers start taking HTTP-specific parameters\n- service-level coordination is recreated inside one endpoint instead of reused\n\n## Where to Continue\n\n- Use [Image Preprocessing and Conversion Pipeline](../image-preprocessing-and-conversion-pipeline/) when the change affects the backend preview pipeline, conversion policy, or preprocessor behavior.\n- Use [SMB Change Notification and Directory Freshness](../smb-change-notification-and-directory-freshness/) when the change affects watcher lifecycle, WebSocket refresh behavior, or directory-cache freshness.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the change affects create, rename, copy, move, upload, or companion-assisted editing.\n- Use [Frontend Overview](../../frontend-architecture/frontend-overview/) when the backend change alters browser-visible workflow behavior.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the changed boundary requires broader validation.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/backend-architecture/image-preprocessing-and-conversion-pipeline", "parent_id": "section:developer-guide/backend-architecture", "depth": 2, "kind": "page", "label": "image-preprocessing-and-conversion-pipeline", "title": "Image Preprocessing And Conversion Pipeline", "path": "developer-guide/backend-architecture/image-preprocessing-and-conversion-pipeline", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Image Preprocessing and Conversion Pipeline\"\n+++\n\nSambee's image preview path is not one converter with one code path.\n\nFor browser preview, the backend uses two related layers:\n\n- `backend/app/services/image_converter.py` for the general conversion pipeline\n- `backend/app/services/preprocessor.py` for formats that must be normalized before the general pipeline can produce browser-ready output\n\nUse this page when a format change affects backend conversion behavior, external image-tool dependencies, or preprocessing policy.\n\n## Why Preprocessing Exists\n\nSome formats can be decoded and converted directly through the main image-conversion path.\n\nOthers need an explicit preprocessing stage first because Sambee does not rely on the normal stack to decode them safely or usefully for browser preview.\n\nThat is the current role of preprocessing for formats such as:\n\n- `psd`\n- `psb`\n- `eps`\n- `ai`\n\nThe design goal is direct conversion to the final browser-ready result, not a chain of intermediate file formats.\n\n## Main Backend Pieces\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/services/image_converter.py` | primary image conversion path, libvips-backed processing, output-format selection, resizing, and MIME return values |\n| `backend/app/services/preprocessor.py` | preprocessor abstraction, ImageMagick-backed implementation, format registry, and factory behavior |\n| `backend/app/core/image_settings.py` | centralized encoder arguments and output-tuning settings |\n| `imagemagick-policy.xml` | repository-managed ImageMagick policy that constrains resource and delegate behavior |\n\n## Runtime Flow\n\nAt a high level, the backend image-preview flow is:\n\n1. the viewer request reaches the backend preview path\n2. the backend determines the file extension and preview behavior\n3. the converter checks whether the extension requires preprocessing\n4. preprocessable formats are sent to the registered preprocessor directly to produce browser-ready bytes\n5. all other convertible formats stay on the libvips-backed conversion path\n6. the viewer endpoint returns the converted bytes with the resulting MIME type\n\nThis is why preview changes can span registry metadata, service logic, environment dependencies, and viewer expectations at the same time.\n\n## General Conversion Path\n\n`convert_image_for_viewer(...)` in `image_converter.py` is the main entry point.\n\nFor the general conversion path it is responsible for:\n\n- loading image data through libvips\n- detecting alpha handling needs\n- converting colorspaces for web-safe output\n- downscaling when max dimensions are configured\n- choosing a final output format such as WebP, JPEG, or PNG\n- returning `(bytes, mime_type, converter_name, duration_ms)` for the caller\n\nThis is the path used for formats such as TIFF, HEIC, BMP, ICO, and similar server-converted formats that do not need the separate preprocessing registry.\n\n## Preprocessing Path\n\nWhen the extension is registered in `PreprocessorRegistry`, the converter takes a different route.\n\n`PreprocessorRegistry.requires_preprocessing(extension)` decides whether the format uses the preprocessing path.\n\nIf it does:\n\n1. the converter resolves the preprocessor with `get_preprocessor_for_format(...)`\n2. the preprocessor converts the source bytes directly to the final browser-ready format\n3. the converter returns those bytes without sending them through a second conversion stage\n\nCurrent product behavior intentionally chooses:\n\n- JPEG output for raster-oriented preprocessable formats such as PSD and PSB\n- PNG output for vector-style preprocessable formats such as EPS and AI when transparency preservation matters more\n\nThat is a product behavior decision, not just an implementation convenience.\n\n## Preprocessor Abstractions\n\nThe preprocessing service is structured around three backend concepts.\n\n### Preprocessorinterface\n\n`PreprocessorInterface` defines the contract every preprocessor must satisfy.\n\nKey responsibilities include:\n\n- `check_availability()`\n- `validate_input(...)`\n- `convert_to_final_format(...)`\n\nIt also centralizes file-size and timeout access through system settings so those limits do not get hard-coded in format-specific code.\n\n### Imagemagickpreprocessor\n\n`ImageMagickPreprocessor` is the only built-in implementation today.\n\nIt is responsible for:\n\n- requiring ImageMagick 7 through `magick`\n- validating supported extensions\n- converting PSD, PSB, EPS, and AI input directly to JPEG or PNG\n- applying centralized output arguments from `image_settings.py`\n- handling colorspace normalization, including CMYK-to-sRGB conversion behavior\n- enforcing timeout and size checks before or during conversion\n\nFor vector formats such as EPS and AI, it also applies density settings so rendered output quality is usable in the browser.\n\n### Preprocessor Registry and Factory\n\n`PreprocessorRegistry` is the single source of truth for which extensions require preprocessing and which preprocessor class handles them.\n\nThe registry:\n\n- normalizes extension lookup case-insensitively\n- maps extensions such as `psd`, `psb`, `eps`, and `ai` to `ImageMagickPreprocessor`\n- allows explicit runtime registration of additional formats\n- does not implement multi-tool fallback chains itself\n\n`PreprocessorFactory` is the configuration-oriented construction layer.\n\nIt currently supports:\n\n- `PREPROCESSOR=imagemagick`\n- `PREPROCESSOR=auto`\n\n`auto` currently means: use ImageMagick if it is available.\n\n## Security and Policy Constraints\n\nThe preprocessing path runs external tooling, so its constraints are part of the product contract.\n\nImportant protections include:\n\n- repository-managed ImageMagick policy in `imagemagick-policy.xml`\n- resource limits for memory, disk, and image dimensions\n- disabled network delegates\n- disabled indirect path reads\n- application-layer behavior that pipes bytes through stdin and stdout instead of constructing shell commands around user-controlled paths\n\nContributors should treat these protections as required behavior. If a format change needs weaker policy or looser limits, that is an architectural change, not a local implementation tweak.\n\n## Operational Behavior\n\nThe preprocessing path is designed to fail explicitly rather than degrade silently.\n\n- invalid input is rejected during validation\n- unavailable ImageMagick raises preprocessing errors\n- timeout failures surface as preprocessing errors\n- unsupported extensions are rejected by the registry path\n\nThe converter then turns preprocessing failures into user-visible conversion failures for the preview API.\n\n## Configuration Surface\n\nThe main advanced settings for ImageMagick-backed preprocessing are:\n\n- `preprocessors.imagemagick.max_file_size_bytes`\n- `preprocessors.imagemagick.timeout_seconds`\n\nContributors should adjust those only when they understand the operational impact on preview latency, memory pressure, and denial-of-service resistance.\n\n## Adding or Changing a Preprocessing Path Safely\n\nUse this sequence when introducing a new preprocessable format or a new preprocessing backend:\n\n1. decide that the format really belongs in preprocessing rather than the ordinary libvips-backed conversion path\n2. implement or reuse a `PreprocessorInterface` subclass\n3. register the extension in `PreprocessorRegistry`\n4. update file-type metadata and viewer expectations if the format becomes previewable\n5. validate ImageMagick policy or other tool-level constraints if the new path needs different capabilities\n6. add backend tests for availability, validation, timeout behavior, and successful conversion output\n\nIf you skip the first decision, it becomes easy to route a format through preprocessing simply because it works locally, even when it weakens the long-term architecture.\n\n## Common Failure Modes\n\n- a new format is registered for preprocessing when the ordinary conversion path would have been safer or simpler\n- extension registration and file-type metadata drift apart\n- ImageMagick availability differs between local development and deployment\n- policy restrictions block a format in production even though it worked in a permissive local environment\n- timeout or file-size limits are raised casually to make one sample file work, increasing operational risk for everyone else\n\n## Where to Continue\n\n- Use [Viewer Architecture and Preview Contracts](../../frontend-architecture/viewer-architecture-and-preview-contracts/) for the browser-visible preview contract, file-type registry alignment, and viewer routing implications.\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider validation coverage.\n\n## Validation Expectations\n\nWhen you change preprocessing or image-conversion architecture, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects preview behavior, add the relevant frontend checks as well.\n", "0.8": "+++\ntitle = \"Image Preprocessing and Conversion Pipeline\"\n+++\n\nSambee's image preview path is not one converter with one code path.\n\nFor browser preview, the backend uses two related layers:\n\n- `backend/app/services/image_converter.py` for the general conversion pipeline\n- `backend/app/services/preprocessor.py` for formats that must be normalized before the general pipeline can produce browser-ready output\n\nUse this page when a format change affects backend conversion behavior, external image-tool dependencies, or preprocessing policy.\n\n## Why Preprocessing Exists\n\nSome formats can be decoded and converted directly through the main image-conversion path.\n\nOthers need an explicit preprocessing stage first because Sambee does not rely on the normal stack to decode them safely or usefully for browser preview.\n\nThat is the current role of preprocessing for formats such as:\n\n- `psd`\n- `psb`\n- `eps`\n- `ai`\n\nThe design goal is direct conversion to the final browser-ready result, not a chain of intermediate file formats.\n\n## Main Backend Pieces\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/services/image_converter.py` | primary image conversion path, libvips-backed processing, output-format selection, resizing, and MIME return values |\n| `backend/app/services/preprocessor.py` | preprocessor abstraction, ImageMagick-backed implementation, format registry, and factory behavior |\n| `backend/app/core/image_settings.py` | centralized encoder arguments and output-tuning settings |\n| `imagemagick-policy.xml` | repository-managed ImageMagick policy that constrains resource and delegate behavior |\n\n## Runtime Flow\n\nAt a high level, the backend image-preview flow is:\n\n1. the viewer request reaches the backend preview path\n2. the backend determines the file extension and preview behavior\n3. the converter checks whether the extension requires preprocessing\n4. preprocessable formats are sent to the registered preprocessor directly to produce browser-ready bytes\n5. all other convertible formats stay on the libvips-backed conversion path\n6. the viewer endpoint returns the converted bytes with the resulting MIME type\n\nThis is why preview changes can span registry metadata, service logic, environment dependencies, and viewer expectations at the same time.\n\n## General Conversion Path\n\n`convert_image_for_viewer(...)` in `image_converter.py` is the main entry point.\n\nFor the general conversion path it is responsible for:\n\n- loading image data through libvips\n- detecting alpha handling needs\n- converting colorspaces for web-safe output\n- downscaling when max dimensions are configured\n- choosing a final output format such as WebP, JPEG, or PNG\n- returning `(bytes, mime_type, converter_name, duration_ms)` for the caller\n\nThis is the path used for formats such as TIFF, HEIC, BMP, ICO, and similar server-converted formats that do not need the separate preprocessing registry.\n\n## Preprocessing Path\n\nWhen the extension is registered in `PreprocessorRegistry`, the converter takes a different route.\n\n`PreprocessorRegistry.requires_preprocessing(extension)` decides whether the format uses the preprocessing path.\n\nIf it does:\n\n1. the converter resolves the preprocessor with `get_preprocessor_for_format(...)`\n2. the preprocessor converts the source bytes directly to the final browser-ready format\n3. the converter returns those bytes without sending them through a second conversion stage\n\nCurrent product behavior intentionally chooses:\n\n- JPEG output for raster-oriented preprocessable formats such as PSD and PSB\n- PNG output for vector-style preprocessable formats such as EPS and AI when transparency preservation matters more\n\nThat is a product behavior decision, not just an implementation convenience.\n\n## Preprocessor Abstractions\n\nThe preprocessing service is structured around three backend concepts.\n\n### Preprocessorinterface\n\n`PreprocessorInterface` defines the contract every preprocessor must satisfy.\n\nKey responsibilities include:\n\n- `check_availability()`\n- `validate_input(...)`\n- `convert_to_final_format(...)`\n\nIt also centralizes file-size and timeout access through system settings so those limits do not get hard-coded in format-specific code.\n\n### Imagemagickpreprocessor\n\n`ImageMagickPreprocessor` is the only built-in implementation today.\n\nIt is responsible for:\n\n- requiring ImageMagick 7 through `magick`\n- validating supported extensions\n- converting PSD, PSB, EPS, and AI input directly to JPEG or PNG\n- applying centralized output arguments from `image_settings.py`\n- handling colorspace normalization, including CMYK-to-sRGB conversion behavior\n- enforcing timeout and size checks before or during conversion\n\nFor vector formats such as EPS and AI, it also applies density settings so rendered output quality is usable in the browser.\n\n### Preprocessor Registry and Factory\n\n`PreprocessorRegistry` is the single source of truth for which extensions require preprocessing and which preprocessor class handles them.\n\nThe registry:\n\n- normalizes extension lookup case-insensitively\n- maps extensions such as `psd`, `psb`, `eps`, and `ai` to `ImageMagickPreprocessor`\n- allows explicit runtime registration of additional formats\n- does not implement multi-tool fallback chains itself\n\n`PreprocessorFactory` is the configuration-oriented construction layer.\n\nIt currently supports:\n\n- `PREPROCESSOR=imagemagick`\n- `PREPROCESSOR=auto`\n\n`auto` currently means: use ImageMagick if it is available.\n\n## Security and Policy Constraints\n\nThe preprocessing path runs external tooling, so its constraints are part of the product contract.\n\nImportant protections include:\n\n- repository-managed ImageMagick policy in `imagemagick-policy.xml`\n- resource limits for memory, disk, and image dimensions\n- disabled network delegates\n- disabled indirect path reads\n- application-layer behavior that pipes bytes through stdin and stdout instead of constructing shell commands around user-controlled paths\n\nContributors should treat these protections as required behavior. If a format change needs weaker policy or looser limits, that is an architectural change, not a local implementation tweak.\n\n## Operational Behavior\n\nThe preprocessing path is designed to fail explicitly rather than degrade silently.\n\n- invalid input is rejected during validation\n- unavailable ImageMagick raises preprocessing errors\n- timeout failures surface as preprocessing errors\n- unsupported extensions are rejected by the registry path\n\nThe converter then turns preprocessing failures into user-visible conversion failures for the preview API.\n\n## Configuration Surface\n\nThe main advanced settings for ImageMagick-backed preprocessing are:\n\n- `preprocessors.imagemagick.max_file_size_bytes`\n- `preprocessors.imagemagick.timeout_seconds`\n\nContributors should adjust those only when they understand the operational impact on preview latency, memory pressure, and denial-of-service resistance.\n\n## Adding or Changing a Preprocessing Path Safely\n\nUse this sequence when introducing a new preprocessable format or a new preprocessing backend:\n\n1. decide that the format really belongs in preprocessing rather than the ordinary libvips-backed conversion path\n2. implement or reuse a `PreprocessorInterface` subclass\n3. register the extension in `PreprocessorRegistry`\n4. update file-type metadata and viewer expectations if the format becomes previewable\n5. validate ImageMagick policy or other tool-level constraints if the new path needs different capabilities\n6. add backend tests for availability, validation, timeout behavior, and successful conversion output\n\nIf you skip the first decision, it becomes easy to route a format through preprocessing simply because it works locally, even when it weakens the long-term architecture.\n\n## Common Failure Modes\n\n- a new format is registered for preprocessing when the ordinary conversion path would have been safer or simpler\n- extension registration and file-type metadata drift apart\n- ImageMagick availability differs between local development and deployment\n- policy restrictions block a format in production even though it worked in a permissive local environment\n- timeout or file-size limits are raised casually to make one sample file work, increasing operational risk for everyone else\n\n## Where to Continue\n\n- Use [Viewer Architecture and Preview Contracts](../../frontend-architecture/viewer-architecture-and-preview-contracts/) for the browser-visible preview contract, file-type registry alignment, and viewer routing implications.\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider validation coverage.\n\n## Validation Expectations\n\nWhen you change preprocessing or image-conversion architecture, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects preview behavior, add the relevant frontend checks as well.\n", "0.9": "+++\ntitle = \"Image Preprocessing and Conversion Pipeline\"\n+++\n\nSambee's image preview path is not one converter with one code path.\n\nFor browser preview, the backend uses two related layers:\n\n- `backend/app/services/image_converter.py` for the general conversion pipeline\n- `backend/app/services/preprocessor.py` for formats that must be normalized before the general pipeline can produce browser-ready output\n\nUse this page when a format change affects backend conversion behavior, external image-tool dependencies, or preprocessing policy.\n\n## Why Preprocessing Exists\n\nSome formats can be decoded and converted directly through the main image-conversion path.\n\nOthers need an explicit preprocessing stage first because Sambee does not rely on the normal stack to decode them safely or usefully for browser preview.\n\nThat is the current role of preprocessing for formats such as:\n\n- `psd`\n- `psb`\n- `eps`\n- `ai`\n\nThe design goal is direct conversion to the final browser-ready result, not a chain of intermediate file formats.\n\n## Main Backend Pieces\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/services/image_converter.py` | primary image conversion path, libvips-backed processing, output-format selection, resizing, and MIME return values |\n| `backend/app/services/preprocessor.py` | preprocessor abstraction, ImageMagick-backed implementation, format registry, and factory behavior |\n| `backend/app/core/image_settings.py` | centralized encoder arguments and output-tuning settings |\n| `imagemagick-policy.xml` | repository-managed ImageMagick policy that constrains resource and delegate behavior |\n\n## Runtime Flow\n\nAt a high level, the backend image-preview flow is:\n\n1. the viewer request reaches the backend preview path\n2. the backend determines the file extension and preview behavior\n3. the converter checks whether the extension requires preprocessing\n4. preprocessable formats are sent to the registered preprocessor directly to produce browser-ready bytes\n5. all other convertible formats stay on the libvips-backed conversion path\n6. the viewer endpoint returns the converted bytes with the resulting MIME type\n\nThis is why preview changes can span registry metadata, service logic, environment dependencies, and viewer expectations at the same time.\n\n## General Conversion Path\n\n`convert_image_for_viewer(...)` in `image_converter.py` is the main entry point.\n\nFor the general conversion path it is responsible for:\n\n- loading image data through libvips\n- detecting alpha handling needs\n- converting colorspaces for web-safe output\n- downscaling when max dimensions are configured\n- choosing a final output format such as WebP, JPEG, or PNG\n- returning `(bytes, mime_type, converter_name, duration_ms)` for the caller\n\nThis is the path used for formats such as TIFF, HEIC, BMP, ICO, and similar server-converted formats that do not need the separate preprocessing registry.\n\n## Preprocessing Path\n\nWhen the extension is registered in `PreprocessorRegistry`, the converter takes a different route.\n\n`PreprocessorRegistry.requires_preprocessing(extension)` decides whether the format uses the preprocessing path.\n\nIf it does:\n\n1. the converter resolves the preprocessor with `get_preprocessor_for_format(...)`\n2. the preprocessor converts the source bytes directly to the final browser-ready format\n3. the converter returns those bytes without sending them through a second conversion stage\n\nCurrent product behavior intentionally chooses:\n\n- JPEG output for raster-oriented preprocessable formats such as PSD and PSB\n- PNG output for vector-style preprocessable formats such as EPS and AI when transparency preservation matters more\n\nThat is a product behavior decision, not just an implementation convenience.\n\n## Preprocessor Abstractions\n\nThe preprocessing service is structured around three backend concepts.\n\n### Preprocessorinterface\n\n`PreprocessorInterface` defines the contract every preprocessor must satisfy.\n\nKey responsibilities include:\n\n- `check_availability()`\n- `validate_input(...)`\n- `convert_to_final_format(...)`\n\nIt also centralizes file-size and timeout access through system settings so those limits do not get hard-coded in format-specific code.\n\n### Imagemagickpreprocessor\n\n`ImageMagickPreprocessor` is the only built-in implementation today.\n\nIt is responsible for:\n\n- requiring ImageMagick 7 through `magick`\n- validating supported extensions\n- converting PSD, PSB, EPS, and AI input directly to JPEG or PNG\n- applying centralized output arguments from `image_settings.py`\n- handling colorspace normalization, including CMYK-to-sRGB conversion behavior\n- enforcing timeout and size checks before or during conversion\n\nFor vector formats such as EPS and AI, it also applies density settings so rendered output quality is usable in the browser.\n\n### Preprocessor Registry and Factory\n\n`PreprocessorRegistry` is the single source of truth for which extensions require preprocessing and which preprocessor class handles them.\n\nThe registry:\n\n- normalizes extension lookup case-insensitively\n- maps extensions such as `psd`, `psb`, `eps`, and `ai` to `ImageMagickPreprocessor`\n- allows explicit runtime registration of additional formats\n- does not implement multi-tool fallback chains itself\n\n`PreprocessorFactory` is the configuration-oriented construction layer.\n\nIt currently supports:\n\n- `PREPROCESSOR=imagemagick`\n- `PREPROCESSOR=auto`\n\n`auto` currently means: use ImageMagick if it is available.\n\n## Security and Policy Constraints\n\nThe preprocessing path runs external tooling, so its constraints are part of the product contract.\n\nImportant protections include:\n\n- repository-managed ImageMagick policy in `imagemagick-policy.xml`\n- resource limits for memory, disk, and image dimensions\n- disabled network delegates\n- disabled indirect path reads\n- application-layer behavior that pipes bytes through stdin and stdout instead of constructing shell commands around user-controlled paths\n\nContributors should treat these protections as required behavior. If a format change needs weaker policy or looser limits, that is an architectural change, not a local implementation tweak.\n\n## Operational Behavior\n\nThe preprocessing path is designed to fail explicitly rather than degrade silently.\n\n- invalid input is rejected during validation\n- unavailable ImageMagick raises preprocessing errors\n- timeout failures surface as preprocessing errors\n- unsupported extensions are rejected by the registry path\n\nThe converter then turns preprocessing failures into user-visible conversion failures for the preview API.\n\n## Configuration Surface\n\nThe main advanced settings for ImageMagick-backed preprocessing are:\n\n- `preprocessors.imagemagick.max_file_size_bytes`\n- `preprocessors.imagemagick.timeout_seconds`\n\nContributors should adjust those only when they understand the operational impact on preview latency, memory pressure, and denial-of-service resistance.\n\n## Adding or Changing a Preprocessing Path Safely\n\nUse this sequence when introducing a new preprocessable format or a new preprocessing backend:\n\n1. decide that the format really belongs in preprocessing rather than the ordinary libvips-backed conversion path\n2. implement or reuse a `PreprocessorInterface` subclass\n3. register the extension in `PreprocessorRegistry`\n4. update file-type metadata and viewer expectations if the format becomes previewable\n5. validate ImageMagick policy or other tool-level constraints if the new path needs different capabilities\n6. add backend tests for availability, validation, timeout behavior, and successful conversion output\n\nIf you skip the first decision, it becomes easy to route a format through preprocessing simply because it works locally, even when it weakens the long-term architecture.\n\n## Common Failure Modes\n\n- a new format is registered for preprocessing when the ordinary conversion path would have been safer or simpler\n- extension registration and file-type metadata drift apart\n- ImageMagick availability differs between local development and deployment\n- policy restrictions block a format in production even though it worked in a permissive local environment\n- timeout or file-size limits are raised casually to make one sample file work, increasing operational risk for everyone else\n\n## Where to Continue\n\n- Use [Viewer Architecture and Preview Contracts](../../frontend-architecture/viewer-architecture-and-preview-contracts/) for the browser-visible preview contract, file-type registry alignment, and viewer routing implications.\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider validation coverage.\n\n## Validation Expectations\n\nWhen you change preprocessing or image-conversion architecture, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects preview behavior, add the relevant frontend checks as well.\n", "1.0": "+++\ntitle = \"Image Preprocessing and Conversion Pipeline\"\n+++\n\nSambee's image preview path is not one converter with one code path.\n\nFor browser preview, the backend uses two related layers:\n\n- `backend/app/services/image_converter.py` for the general conversion pipeline\n- `backend/app/services/preprocessor.py` for formats that must be normalized before the general pipeline can produce browser-ready output\n\nUse this page when a format change affects backend conversion behavior, external image-tool dependencies, or preprocessing policy.\n\n## Why Preprocessing Exists\n\nSome formats can be decoded and converted directly through the main image-conversion path.\n\nOthers need an explicit preprocessing stage first because Sambee does not rely on the normal stack to decode them safely or usefully for browser preview.\n\nThat is the current role of preprocessing for formats such as:\n\n- `psd`\n- `psb`\n- `eps`\n- `ai`\n\nThe design goal is direct conversion to the final browser-ready result, not a chain of intermediate file formats.\n\n## Main Backend Pieces\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/services/image_converter.py` | primary image conversion path, libvips-backed processing, output-format selection, resizing, and MIME return values |\n| `backend/app/services/preprocessor.py` | preprocessor abstraction, ImageMagick-backed implementation, format registry, and factory behavior |\n| `backend/app/core/image_settings.py` | centralized encoder arguments and output-tuning settings |\n| `imagemagick-policy.xml` | repository-managed ImageMagick policy that constrains resource and delegate behavior |\n\n## Runtime Flow\n\nAt a high level, the backend image-preview flow is:\n\n1. the viewer request reaches the backend preview path\n2. the backend determines the file extension and preview behavior\n3. the converter checks whether the extension requires preprocessing\n4. preprocessable formats are sent to the registered preprocessor directly to produce browser-ready bytes\n5. all other convertible formats stay on the libvips-backed conversion path\n6. the viewer endpoint returns the converted bytes with the resulting MIME type\n\nThis is why preview changes can span registry metadata, service logic, environment dependencies, and viewer expectations at the same time.\n\n## General Conversion Path\n\n`convert_image_for_viewer(...)` in `image_converter.py` is the main entry point.\n\nFor the general conversion path it is responsible for:\n\n- loading image data through libvips\n- detecting alpha handling needs\n- converting colorspaces for web-safe output\n- downscaling when max dimensions are configured\n- choosing a final output format such as WebP, JPEG, or PNG\n- returning `(bytes, mime_type, converter_name, duration_ms)` for the caller\n\nThis is the path used for formats such as TIFF, HEIC, BMP, ICO, and similar server-converted formats that do not need the separate preprocessing registry.\n\n## Preprocessing Path\n\nWhen the extension is registered in `PreprocessorRegistry`, the converter takes a different route.\n\n`PreprocessorRegistry.requires_preprocessing(extension)` decides whether the format uses the preprocessing path.\n\nIf it does:\n\n1. the converter resolves the preprocessor with `get_preprocessor_for_format(...)`\n2. the preprocessor converts the source bytes directly to the final browser-ready format\n3. the converter returns those bytes without sending them through a second conversion stage\n\nCurrent product behavior intentionally chooses:\n\n- JPEG output for raster-oriented preprocessable formats such as PSD and PSB\n- PNG output for vector-style preprocessable formats such as EPS and AI when transparency preservation matters more\n\nThat is a product behavior decision, not just an implementation convenience.\n\n## Preprocessor Abstractions\n\nThe preprocessing service is structured around three backend concepts.\n\n### Preprocessorinterface\n\n`PreprocessorInterface` defines the contract every preprocessor must satisfy.\n\nKey responsibilities include:\n\n- `check_availability()`\n- `validate_input(...)`\n- `convert_to_final_format(...)`\n\nIt also centralizes file-size and timeout access through system settings so those limits do not get hard-coded in format-specific code.\n\n### Imagemagickpreprocessor\n\n`ImageMagickPreprocessor` is the only built-in implementation today.\n\nIt is responsible for:\n\n- requiring ImageMagick 7 through `magick`\n- validating supported extensions\n- converting PSD, PSB, EPS, and AI input directly to JPEG or PNG\n- applying centralized output arguments from `image_settings.py`\n- handling colorspace normalization, including CMYK-to-sRGB conversion behavior\n- enforcing timeout and size checks before or during conversion\n\nFor vector formats such as EPS and AI, it also applies density settings so rendered output quality is usable in the browser.\n\n### Preprocessor Registry and Factory\n\n`PreprocessorRegistry` is the single source of truth for which extensions require preprocessing and which preprocessor class handles them.\n\nThe registry:\n\n- normalizes extension lookup case-insensitively\n- maps extensions such as `psd`, `psb`, `eps`, and `ai` to `ImageMagickPreprocessor`\n- allows explicit runtime registration of additional formats\n- does not implement multi-tool fallback chains itself\n\n`PreprocessorFactory` is the configuration-oriented construction layer.\n\nIt currently supports:\n\n- `PREPROCESSOR=imagemagick`\n- `PREPROCESSOR=auto`\n\n`auto` currently means: use ImageMagick if it is available.\n\n## Security and Policy Constraints\n\nThe preprocessing path runs external tooling, so its constraints are part of the product contract.\n\nImportant protections include:\n\n- repository-managed ImageMagick policy in `imagemagick-policy.xml`\n- resource limits for memory, disk, and image dimensions\n- disabled network delegates\n- disabled indirect path reads\n- application-layer behavior that pipes bytes through stdin and stdout instead of constructing shell commands around user-controlled paths\n\nContributors should treat these protections as required behavior. If a format change needs weaker policy or looser limits, that is an architectural change, not a local implementation tweak.\n\n## Operational Behavior\n\nThe preprocessing path is designed to fail explicitly rather than degrade silently.\n\n- invalid input is rejected during validation\n- unavailable ImageMagick raises preprocessing errors\n- timeout failures surface as preprocessing errors\n- unsupported extensions are rejected by the registry path\n\nThe converter then turns preprocessing failures into user-visible conversion failures for the preview API.\n\n## Configuration Surface\n\nThe main advanced settings for ImageMagick-backed preprocessing are:\n\n- `preprocessors.imagemagick.max_file_size_bytes`\n- `preprocessors.imagemagick.timeout_seconds`\n\nContributors should adjust those only when they understand the operational impact on preview latency, memory pressure, and denial-of-service resistance.\n\n## Adding or Changing a Preprocessing Path Safely\n\nUse this sequence when introducing a new preprocessable format or a new preprocessing backend:\n\n1. decide that the format really belongs in preprocessing rather than the ordinary libvips-backed conversion path\n2. implement or reuse a `PreprocessorInterface` subclass\n3. register the extension in `PreprocessorRegistry`\n4. update file-type metadata and viewer expectations if the format becomes previewable\n5. validate ImageMagick policy or other tool-level constraints if the new path needs different capabilities\n6. add backend tests for availability, validation, timeout behavior, and successful conversion output\n\nIf you skip the first decision, it becomes easy to route a format through preprocessing simply because it works locally, even when it weakens the long-term architecture.\n\n## Common Failure Modes\n\n- a new format is registered for preprocessing when the ordinary conversion path would have been safer or simpler\n- extension registration and file-type metadata drift apart\n- ImageMagick availability differs between local development and deployment\n- policy restrictions block a format in production even though it worked in a permissive local environment\n- timeout or file-size limits are raised casually to make one sample file work, increasing operational risk for everyone else\n\n## Where to Continue\n\n- Use [Viewer Architecture and Preview Contracts](../../frontend-architecture/viewer-architecture-and-preview-contracts/) for the browser-visible preview contract, file-type registry alignment, and viewer routing implications.\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider validation coverage.\n\n## Validation Expectations\n\nWhen you change preprocessing or image-conversion architecture, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects preview behavior, add the relevant frontend checks as well.\n", "2.0": "+++\ntitle = \"Image Preprocessing and Conversion Pipeline\"\n+++\n\nSambee's image preview path is not one converter with one code path.\n\nFor browser preview, the backend uses two related layers:\n\n- `backend/app/services/image_converter.py` for the general conversion pipeline\n- `backend/app/services/preprocessor.py` for formats that must be normalized before the general pipeline can produce browser-ready output\n\nUse this page when a format change affects backend conversion behavior, external image-tool dependencies, or preprocessing policy.\n\n## Why Preprocessing Exists\n\nSome formats can be decoded and converted directly through the main image-conversion path.\n\nOthers need an explicit preprocessing stage first because Sambee does not rely on the normal stack to decode them safely or usefully for browser preview.\n\nThat is the current role of preprocessing for formats such as:\n\n- `psd`\n- `psb`\n- `eps`\n- `ai`\n\nThe design goal is direct conversion to the final browser-ready result, not a chain of intermediate file formats.\n\n## Main Backend Pieces\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/services/image_converter.py` | primary image conversion path, libvips-backed processing, output-format selection, resizing, and MIME return values |\n| `backend/app/services/preprocessor.py` | preprocessor abstraction, ImageMagick-backed implementation, format registry, and factory behavior |\n| `backend/app/core/image_settings.py` | centralized encoder arguments and output-tuning settings |\n| `imagemagick-policy.xml` | repository-managed ImageMagick policy that constrains resource and delegate behavior |\n\n## Runtime Flow\n\nAt a high level, the backend image-preview flow is:\n\n1. the viewer request reaches the backend preview path\n2. the backend determines the file extension and preview behavior\n3. the converter checks whether the extension requires preprocessing\n4. preprocessable formats are sent to the registered preprocessor directly to produce browser-ready bytes\n5. all other convertible formats stay on the libvips-backed conversion path\n6. the viewer endpoint returns the converted bytes with the resulting MIME type\n\nThis is why preview changes can span registry metadata, service logic, environment dependencies, and viewer expectations at the same time.\n\n## General Conversion Path\n\n`convert_image_for_viewer(...)` in `image_converter.py` is the main entry point.\n\nFor the general conversion path it is responsible for:\n\n- loading image data through libvips\n- detecting alpha handling needs\n- converting colorspaces for web-safe output\n- downscaling when max dimensions are configured\n- choosing a final output format such as WebP, JPEG, or PNG\n- returning `(bytes, mime_type, converter_name, duration_ms)` for the caller\n\nThis is the path used for formats such as TIFF, HEIC, BMP, ICO, and similar server-converted formats that do not need the separate preprocessing registry.\n\n## Preprocessing Path\n\nWhen the extension is registered in `PreprocessorRegistry`, the converter takes a different route.\n\n`PreprocessorRegistry.requires_preprocessing(extension)` decides whether the format uses the preprocessing path.\n\nIf it does:\n\n1. the converter resolves the preprocessor with `get_preprocessor_for_format(...)`\n2. the preprocessor converts the source bytes directly to the final browser-ready format\n3. the converter returns those bytes without sending them through a second conversion stage\n\nCurrent product behavior intentionally chooses:\n\n- JPEG output for raster-oriented preprocessable formats such as PSD and PSB\n- PNG output for vector-style preprocessable formats such as EPS and AI when transparency preservation matters more\n\nThat is a product behavior decision, not just an implementation convenience.\n\n## Preprocessor Abstractions\n\nThe preprocessing service is structured around three backend concepts.\n\n### Preprocessorinterface\n\n`PreprocessorInterface` defines the contract every preprocessor must satisfy.\n\nKey responsibilities include:\n\n- `check_availability()`\n- `validate_input(...)`\n- `convert_to_final_format(...)`\n\nIt also centralizes file-size and timeout access through system settings so those limits do not get hard-coded in format-specific code.\n\n### Imagemagickpreprocessor\n\n`ImageMagickPreprocessor` is the only built-in implementation today.\n\nIt is responsible for:\n\n- requiring ImageMagick 7 through `magick`\n- validating supported extensions\n- converting PSD, PSB, EPS, and AI input directly to JPEG or PNG\n- applying centralized output arguments from `image_settings.py`\n- handling colorspace normalization, including CMYK-to-sRGB conversion behavior\n- enforcing timeout and size checks before or during conversion\n\nFor vector formats such as EPS and AI, it also applies density settings so rendered output quality is usable in the browser.\n\n### Preprocessor Registry and Factory\n\n`PreprocessorRegistry` is the single source of truth for which extensions require preprocessing and which preprocessor class handles them.\n\nThe registry:\n\n- normalizes extension lookup case-insensitively\n- maps extensions such as `psd`, `psb`, `eps`, and `ai` to `ImageMagickPreprocessor`\n- allows explicit runtime registration of additional formats\n- does not implement multi-tool fallback chains itself\n\n`PreprocessorFactory` is the configuration-oriented construction layer.\n\nIt currently supports:\n\n- `PREPROCESSOR=imagemagick`\n- `PREPROCESSOR=auto`\n\n`auto` currently means: use ImageMagick if it is available.\n\n## Security and Policy Constraints\n\nThe preprocessing path runs external tooling, so its constraints are part of the product contract.\n\nImportant protections include:\n\n- repository-managed ImageMagick policy in `imagemagick-policy.xml`\n- resource limits for memory, disk, and image dimensions\n- disabled network delegates\n- disabled indirect path reads\n- application-layer behavior that pipes bytes through stdin and stdout instead of constructing shell commands around user-controlled paths\n\nContributors should treat these protections as required behavior. If a format change needs weaker policy or looser limits, that is an architectural change, not a local implementation tweak.\n\n## Operational Behavior\n\nThe preprocessing path is designed to fail explicitly rather than degrade silently.\n\n- invalid input is rejected during validation\n- unavailable ImageMagick raises preprocessing errors\n- timeout failures surface as preprocessing errors\n- unsupported extensions are rejected by the registry path\n\nThe converter then turns preprocessing failures into user-visible conversion failures for the preview API.\n\n## Configuration Surface\n\nThe main advanced settings for ImageMagick-backed preprocessing are:\n\n- `preprocessors.imagemagick.max_file_size_bytes`\n- `preprocessors.imagemagick.timeout_seconds`\n\nContributors should adjust those only when they understand the operational impact on preview latency, memory pressure, and denial-of-service resistance.\n\n## Adding or Changing a Preprocessing Path Safely\n\nUse this sequence when introducing a new preprocessable format or a new preprocessing backend:\n\n1. decide that the format really belongs in preprocessing rather than the ordinary libvips-backed conversion path\n2. implement or reuse a `PreprocessorInterface` subclass\n3. register the extension in `PreprocessorRegistry`\n4. update file-type metadata and viewer expectations if the format becomes previewable\n5. validate ImageMagick policy or other tool-level constraints if the new path needs different capabilities\n6. add backend tests for availability, validation, timeout behavior, and successful conversion output\n\nIf you skip the first decision, it becomes easy to route a format through preprocessing simply because it works locally, even when it weakens the long-term architecture.\n\n## Common Failure Modes\n\n- a new format is registered for preprocessing when the ordinary conversion path would have been safer or simpler\n- extension registration and file-type metadata drift apart\n- ImageMagick availability differs between local development and deployment\n- policy restrictions block a format in production even though it worked in a permissive local environment\n- timeout or file-size limits are raised casually to make one sample file work, increasing operational risk for everyone else\n\n## Where to Continue\n\n- Use [Viewer Architecture and Preview Contracts](../../frontend-architecture/viewer-architecture-and-preview-contracts/) for the browser-visible preview contract, file-type registry alignment, and viewer routing implications.\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider validation coverage.\n\n## Validation Expectations\n\nWhen you change preprocessing or image-conversion architecture, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects preview behavior, add the relevant frontend checks as well.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Image Preprocessing and Conversion Pipeline\"\n+++\n\nSambee's image preview path is not one converter with one code path.\n\nFor browser preview, the backend uses two related layers:\n\n- `backend/app/services/image_converter.py` for the general conversion pipeline\n- `backend/app/services/preprocessor.py` for formats that must be normalized before the general pipeline can produce browser-ready output\n\nUse this page when a format change affects backend conversion behavior, external image-tool dependencies, or preprocessing policy.\n\n## Why Preprocessing Exists\n\nSome formats can be decoded and converted directly through the main image-conversion path.\n\nOthers need an explicit preprocessing stage first because Sambee does not rely on the normal stack to decode them safely or usefully for browser preview.\n\nThat is the current role of preprocessing for formats such as:\n\n- `psd`\n- `psb`\n- `eps`\n- `ai`\n\nThe design goal is direct conversion to the final browser-ready result, not a chain of intermediate file formats.\n\n## Main Backend Pieces\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/services/image_converter.py` | primary image conversion path, libvips-backed processing, output-format selection, resizing, and MIME return values |\n| `backend/app/services/preprocessor.py` | preprocessor abstraction, ImageMagick-backed implementation, format registry, and factory behavior |\n| `backend/app/core/image_settings.py` | centralized encoder arguments and output-tuning settings |\n| `imagemagick-policy.xml` | repository-managed ImageMagick policy that constrains resource and delegate behavior |\n\n## Runtime Flow\n\nAt a high level, the backend image-preview flow is:\n\n1. the viewer request reaches the backend preview path\n2. the backend determines the file extension and preview behavior\n3. the converter checks whether the extension requires preprocessing\n4. preprocessable formats are sent to the registered preprocessor directly to produce browser-ready bytes\n5. all other convertible formats stay on the libvips-backed conversion path\n6. the viewer endpoint returns the converted bytes with the resulting MIME type\n\nThis is why preview changes can span registry metadata, service logic, environment dependencies, and viewer expectations at the same time.\n\n## General Conversion Path\n\n`convert_image_for_viewer(...)` in `image_converter.py` is the main entry point.\n\nFor the general conversion path it is responsible for:\n\n- loading image data through libvips\n- detecting alpha handling needs\n- converting colorspaces for web-safe output\n- downscaling when max dimensions are configured\n- choosing a final output format such as WebP, JPEG, or PNG\n- returning `(bytes, mime_type, converter_name, duration_ms)` for the caller\n\nThis is the path used for formats such as TIFF, HEIC, BMP, ICO, and similar server-converted formats that do not need the separate preprocessing registry.\n\n## Preprocessing Path\n\nWhen the extension is registered in `PreprocessorRegistry`, the converter takes a different route.\n\n`PreprocessorRegistry.requires_preprocessing(extension)` decides whether the format uses the preprocessing path.\n\nIf it does:\n\n1. the converter resolves the preprocessor with `get_preprocessor_for_format(...)`\n2. the preprocessor converts the source bytes directly to the final browser-ready format\n3. the converter returns those bytes without sending them through a second conversion stage\n\nCurrent product behavior intentionally chooses:\n\n- JPEG output for raster-oriented preprocessable formats such as PSD and PSB\n- PNG output for vector-style preprocessable formats such as EPS and AI when transparency preservation matters more\n\nThat is a product behavior decision, not just an implementation convenience.\n\n## Preprocessor Abstractions\n\nThe preprocessing service is structured around three backend concepts.\n\n### Preprocessorinterface\n\n`PreprocessorInterface` defines the contract every preprocessor must satisfy.\n\nKey responsibilities include:\n\n- `check_availability()`\n- `validate_input(...)`\n- `convert_to_final_format(...)`\n\nIt also centralizes file-size and timeout access through system settings so those limits do not get hard-coded in format-specific code.\n\n### Imagemagickpreprocessor\n\n`ImageMagickPreprocessor` is the only built-in implementation today.\n\nIt is responsible for:\n\n- requiring ImageMagick 7 through `magick`\n- validating supported extensions\n- converting PSD, PSB, EPS, and AI input directly to JPEG or PNG\n- applying centralized output arguments from `image_settings.py`\n- handling colorspace normalization, including CMYK-to-sRGB conversion behavior\n- enforcing timeout and size checks before or during conversion\n\nFor vector formats such as EPS and AI, it also applies density settings so rendered output quality is usable in the browser.\n\n### Preprocessor Registry and Factory\n\n`PreprocessorRegistry` is the single source of truth for which extensions require preprocessing and which preprocessor class handles them.\n\nThe registry:\n\n- normalizes extension lookup case-insensitively\n- maps extensions such as `psd`, `psb`, `eps`, and `ai` to `ImageMagickPreprocessor`\n- allows explicit runtime registration of additional formats\n- does not implement multi-tool fallback chains itself\n\n`PreprocessorFactory` is the configuration-oriented construction layer.\n\nIt currently supports:\n\n- `PREPROCESSOR=imagemagick`\n- `PREPROCESSOR=auto`\n\n`auto` currently means: use ImageMagick if it is available.\n\n## Security and Policy Constraints\n\nThe preprocessing path runs external tooling, so its constraints are part of the product contract.\n\nImportant protections include:\n\n- repository-managed ImageMagick policy in `imagemagick-policy.xml`\n- resource limits for memory, disk, and image dimensions\n- disabled network delegates\n- disabled indirect path reads\n- application-layer behavior that pipes bytes through stdin and stdout instead of constructing shell commands around user-controlled paths\n\nContributors should treat these protections as required behavior. If a format change needs weaker policy or looser limits, that is an architectural change, not a local implementation tweak.\n\n## Operational Behavior\n\nThe preprocessing path is designed to fail explicitly rather than degrade silently.\n\n- invalid input is rejected during validation\n- unavailable ImageMagick raises preprocessing errors\n- timeout failures surface as preprocessing errors\n- unsupported extensions are rejected by the registry path\n\nThe converter then turns preprocessing failures into user-visible conversion failures for the preview API.\n\n## Configuration Surface\n\nThe main advanced settings for ImageMagick-backed preprocessing are:\n\n- `preprocessors.imagemagick.max_file_size_bytes`\n- `preprocessors.imagemagick.timeout_seconds`\n\nContributors should adjust those only when they understand the operational impact on preview latency, memory pressure, and denial-of-service resistance.\n\n## Adding or Changing a Preprocessing Path Safely\n\nUse this sequence when introducing a new preprocessable format or a new preprocessing backend:\n\n1. decide that the format really belongs in preprocessing rather than the ordinary libvips-backed conversion path\n2. implement or reuse a `PreprocessorInterface` subclass\n3. register the extension in `PreprocessorRegistry`\n4. update file-type metadata and viewer expectations if the format becomes previewable\n5. validate ImageMagick policy or other tool-level constraints if the new path needs different capabilities\n6. add backend tests for availability, validation, timeout behavior, and successful conversion output\n\nIf you skip the first decision, it becomes easy to route a format through preprocessing simply because it works locally, even when it weakens the long-term architecture.\n\n## Common Failure Modes\n\n- a new format is registered for preprocessing when the ordinary conversion path would have been safer or simpler\n- extension registration and file-type metadata drift apart\n- ImageMagick availability differs between local development and deployment\n- policy restrictions block a format in production even though it worked in a permissive local environment\n- timeout or file-size limits are raised casually to make one sample file work, increasing operational risk for everyone else\n\n## Where to Continue\n\n- Use [Viewer Architecture and Preview Contracts](../../frontend-architecture/viewer-architecture-and-preview-contracts/) for the browser-visible preview contract, file-type registry alignment, and viewer routing implications.\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider validation coverage.\n\n## Validation Expectations\n\nWhen you change preprocessing or image-conversion architecture, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects preview behavior, add the relevant frontend checks as well.\n", "0.8": "+++\ntitle = \"Image Preprocessing and Conversion Pipeline\"\n+++\n\nSambee's image preview path is not one converter with one code path.\n\nFor browser preview, the backend uses two related layers:\n\n- `backend/app/services/image_converter.py` for the general conversion pipeline\n- `backend/app/services/preprocessor.py` for formats that must be normalized before the general pipeline can produce browser-ready output\n\nUse this page when a format change affects backend conversion behavior, external image-tool dependencies, or preprocessing policy.\n\n## Why Preprocessing Exists\n\nSome formats can be decoded and converted directly through the main image-conversion path.\n\nOthers need an explicit preprocessing stage first because Sambee does not rely on the normal stack to decode them safely or usefully for browser preview.\n\nThat is the current role of preprocessing for formats such as:\n\n- `psd`\n- `psb`\n- `eps`\n- `ai`\n\nThe design goal is direct conversion to the final browser-ready result, not a chain of intermediate file formats.\n\n## Main Backend Pieces\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/services/image_converter.py` | primary image conversion path, libvips-backed processing, output-format selection, resizing, and MIME return values |\n| `backend/app/services/preprocessor.py` | preprocessor abstraction, ImageMagick-backed implementation, format registry, and factory behavior |\n| `backend/app/core/image_settings.py` | centralized encoder arguments and output-tuning settings |\n| `imagemagick-policy.xml` | repository-managed ImageMagick policy that constrains resource and delegate behavior |\n\n## Runtime Flow\n\nAt a high level, the backend image-preview flow is:\n\n1. the viewer request reaches the backend preview path\n2. the backend determines the file extension and preview behavior\n3. the converter checks whether the extension requires preprocessing\n4. preprocessable formats are sent to the registered preprocessor directly to produce browser-ready bytes\n5. all other convertible formats stay on the libvips-backed conversion path\n6. the viewer endpoint returns the converted bytes with the resulting MIME type\n\nThis is why preview changes can span registry metadata, service logic, environment dependencies, and viewer expectations at the same time.\n\n## General Conversion Path\n\n`convert_image_for_viewer(...)` in `image_converter.py` is the main entry point.\n\nFor the general conversion path it is responsible for:\n\n- loading image data through libvips\n- detecting alpha handling needs\n- converting colorspaces for web-safe output\n- downscaling when max dimensions are configured\n- choosing a final output format such as WebP, JPEG, or PNG\n- returning `(bytes, mime_type, converter_name, duration_ms)` for the caller\n\nThis is the path used for formats such as TIFF, HEIC, BMP, ICO, and similar server-converted formats that do not need the separate preprocessing registry.\n\n## Preprocessing Path\n\nWhen the extension is registered in `PreprocessorRegistry`, the converter takes a different route.\n\n`PreprocessorRegistry.requires_preprocessing(extension)` decides whether the format uses the preprocessing path.\n\nIf it does:\n\n1. the converter resolves the preprocessor with `get_preprocessor_for_format(...)`\n2. the preprocessor converts the source bytes directly to the final browser-ready format\n3. the converter returns those bytes without sending them through a second conversion stage\n\nCurrent product behavior intentionally chooses:\n\n- JPEG output for raster-oriented preprocessable formats such as PSD and PSB\n- PNG output for vector-style preprocessable formats such as EPS and AI when transparency preservation matters more\n\nThat is a product behavior decision, not just an implementation convenience.\n\n## Preprocessor Abstractions\n\nThe preprocessing service is structured around three backend concepts.\n\n### Preprocessorinterface\n\n`PreprocessorInterface` defines the contract every preprocessor must satisfy.\n\nKey responsibilities include:\n\n- `check_availability()`\n- `validate_input(...)`\n- `convert_to_final_format(...)`\n\nIt also centralizes file-size and timeout access through system settings so those limits do not get hard-coded in format-specific code.\n\n### Imagemagickpreprocessor\n\n`ImageMagickPreprocessor` is the only built-in implementation today.\n\nIt is responsible for:\n\n- requiring ImageMagick 7 through `magick`\n- validating supported extensions\n- converting PSD, PSB, EPS, and AI input directly to JPEG or PNG\n- applying centralized output arguments from `image_settings.py`\n- handling colorspace normalization, including CMYK-to-sRGB conversion behavior\n- enforcing timeout and size checks before or during conversion\n\nFor vector formats such as EPS and AI, it also applies density settings so rendered output quality is usable in the browser.\n\n### Preprocessor Registry and Factory\n\n`PreprocessorRegistry` is the single source of truth for which extensions require preprocessing and which preprocessor class handles them.\n\nThe registry:\n\n- normalizes extension lookup case-insensitively\n- maps extensions such as `psd`, `psb`, `eps`, and `ai` to `ImageMagickPreprocessor`\n- allows explicit runtime registration of additional formats\n- does not implement multi-tool fallback chains itself\n\n`PreprocessorFactory` is the configuration-oriented construction layer.\n\nIt currently supports:\n\n- `PREPROCESSOR=imagemagick`\n- `PREPROCESSOR=auto`\n\n`auto` currently means: use ImageMagick if it is available.\n\n## Security and Policy Constraints\n\nThe preprocessing path runs external tooling, so its constraints are part of the product contract.\n\nImportant protections include:\n\n- repository-managed ImageMagick policy in `imagemagick-policy.xml`\n- resource limits for memory, disk, and image dimensions\n- disabled network delegates\n- disabled indirect path reads\n- application-layer behavior that pipes bytes through stdin and stdout instead of constructing shell commands around user-controlled paths\n\nContributors should treat these protections as required behavior. If a format change needs weaker policy or looser limits, that is an architectural change, not a local implementation tweak.\n\n## Operational Behavior\n\nThe preprocessing path is designed to fail explicitly rather than degrade silently.\n\n- invalid input is rejected during validation\n- unavailable ImageMagick raises preprocessing errors\n- timeout failures surface as preprocessing errors\n- unsupported extensions are rejected by the registry path\n\nThe converter then turns preprocessing failures into user-visible conversion failures for the preview API.\n\n## Configuration Surface\n\nThe main advanced settings for ImageMagick-backed preprocessing are:\n\n- `preprocessors.imagemagick.max_file_size_bytes`\n- `preprocessors.imagemagick.timeout_seconds`\n\nContributors should adjust those only when they understand the operational impact on preview latency, memory pressure, and denial-of-service resistance.\n\n## Adding or Changing a Preprocessing Path Safely\n\nUse this sequence when introducing a new preprocessable format or a new preprocessing backend:\n\n1. decide that the format really belongs in preprocessing rather than the ordinary libvips-backed conversion path\n2. implement or reuse a `PreprocessorInterface` subclass\n3. register the extension in `PreprocessorRegistry`\n4. update file-type metadata and viewer expectations if the format becomes previewable\n5. validate ImageMagick policy or other tool-level constraints if the new path needs different capabilities\n6. add backend tests for availability, validation, timeout behavior, and successful conversion output\n\nIf you skip the first decision, it becomes easy to route a format through preprocessing simply because it works locally, even when it weakens the long-term architecture.\n\n## Common Failure Modes\n\n- a new format is registered for preprocessing when the ordinary conversion path would have been safer or simpler\n- extension registration and file-type metadata drift apart\n- ImageMagick availability differs between local development and deployment\n- policy restrictions block a format in production even though it worked in a permissive local environment\n- timeout or file-size limits are raised casually to make one sample file work, increasing operational risk for everyone else\n\n## Where to Continue\n\n- Use [Viewer Architecture and Preview Contracts](../../frontend-architecture/viewer-architecture-and-preview-contracts/) for the browser-visible preview contract, file-type registry alignment, and viewer routing implications.\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider validation coverage.\n\n## Validation Expectations\n\nWhen you change preprocessing or image-conversion architecture, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects preview behavior, add the relevant frontend checks as well.\n", "0.9": "+++\ntitle = \"Image Preprocessing and Conversion Pipeline\"\n+++\n\nSambee's image preview path is not one converter with one code path.\n\nFor browser preview, the backend uses two related layers:\n\n- `backend/app/services/image_converter.py` for the general conversion pipeline\n- `backend/app/services/preprocessor.py` for formats that must be normalized before the general pipeline can produce browser-ready output\n\nUse this page when a format change affects backend conversion behavior, external image-tool dependencies, or preprocessing policy.\n\n## Why Preprocessing Exists\n\nSome formats can be decoded and converted directly through the main image-conversion path.\n\nOthers need an explicit preprocessing stage first because Sambee does not rely on the normal stack to decode them safely or usefully for browser preview.\n\nThat is the current role of preprocessing for formats such as:\n\n- `psd`\n- `psb`\n- `eps`\n- `ai`\n\nThe design goal is direct conversion to the final browser-ready result, not a chain of intermediate file formats.\n\n## Main Backend Pieces\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/services/image_converter.py` | primary image conversion path, libvips-backed processing, output-format selection, resizing, and MIME return values |\n| `backend/app/services/preprocessor.py` | preprocessor abstraction, ImageMagick-backed implementation, format registry, and factory behavior |\n| `backend/app/core/image_settings.py` | centralized encoder arguments and output-tuning settings |\n| `imagemagick-policy.xml` | repository-managed ImageMagick policy that constrains resource and delegate behavior |\n\n## Runtime Flow\n\nAt a high level, the backend image-preview flow is:\n\n1. the viewer request reaches the backend preview path\n2. the backend determines the file extension and preview behavior\n3. the converter checks whether the extension requires preprocessing\n4. preprocessable formats are sent to the registered preprocessor directly to produce browser-ready bytes\n5. all other convertible formats stay on the libvips-backed conversion path\n6. the viewer endpoint returns the converted bytes with the resulting MIME type\n\nThis is why preview changes can span registry metadata, service logic, environment dependencies, and viewer expectations at the same time.\n\n## General Conversion Path\n\n`convert_image_for_viewer(...)` in `image_converter.py` is the main entry point.\n\nFor the general conversion path it is responsible for:\n\n- loading image data through libvips\n- detecting alpha handling needs\n- converting colorspaces for web-safe output\n- downscaling when max dimensions are configured\n- choosing a final output format such as WebP, JPEG, or PNG\n- returning `(bytes, mime_type, converter_name, duration_ms)` for the caller\n\nThis is the path used for formats such as TIFF, HEIC, BMP, ICO, and similar server-converted formats that do not need the separate preprocessing registry.\n\n## Preprocessing Path\n\nWhen the extension is registered in `PreprocessorRegistry`, the converter takes a different route.\n\n`PreprocessorRegistry.requires_preprocessing(extension)` decides whether the format uses the preprocessing path.\n\nIf it does:\n\n1. the converter resolves the preprocessor with `get_preprocessor_for_format(...)`\n2. the preprocessor converts the source bytes directly to the final browser-ready format\n3. the converter returns those bytes without sending them through a second conversion stage\n\nCurrent product behavior intentionally chooses:\n\n- JPEG output for raster-oriented preprocessable formats such as PSD and PSB\n- PNG output for vector-style preprocessable formats such as EPS and AI when transparency preservation matters more\n\nThat is a product behavior decision, not just an implementation convenience.\n\n## Preprocessor Abstractions\n\nThe preprocessing service is structured around three backend concepts.\n\n### Preprocessorinterface\n\n`PreprocessorInterface` defines the contract every preprocessor must satisfy.\n\nKey responsibilities include:\n\n- `check_availability()`\n- `validate_input(...)`\n- `convert_to_final_format(...)`\n\nIt also centralizes file-size and timeout access through system settings so those limits do not get hard-coded in format-specific code.\n\n### Imagemagickpreprocessor\n\n`ImageMagickPreprocessor` is the only built-in implementation today.\n\nIt is responsible for:\n\n- requiring ImageMagick 7 through `magick`\n- validating supported extensions\n- converting PSD, PSB, EPS, and AI input directly to JPEG or PNG\n- applying centralized output arguments from `image_settings.py`\n- handling colorspace normalization, including CMYK-to-sRGB conversion behavior\n- enforcing timeout and size checks before or during conversion\n\nFor vector formats such as EPS and AI, it also applies density settings so rendered output quality is usable in the browser.\n\n### Preprocessor Registry and Factory\n\n`PreprocessorRegistry` is the single source of truth for which extensions require preprocessing and which preprocessor class handles them.\n\nThe registry:\n\n- normalizes extension lookup case-insensitively\n- maps extensions such as `psd`, `psb`, `eps`, and `ai` to `ImageMagickPreprocessor`\n- allows explicit runtime registration of additional formats\n- does not implement multi-tool fallback chains itself\n\n`PreprocessorFactory` is the configuration-oriented construction layer.\n\nIt currently supports:\n\n- `PREPROCESSOR=imagemagick`\n- `PREPROCESSOR=auto`\n\n`auto` currently means: use ImageMagick if it is available.\n\n## Security and Policy Constraints\n\nThe preprocessing path runs external tooling, so its constraints are part of the product contract.\n\nImportant protections include:\n\n- repository-managed ImageMagick policy in `imagemagick-policy.xml`\n- resource limits for memory, disk, and image dimensions\n- disabled network delegates\n- disabled indirect path reads\n- application-layer behavior that pipes bytes through stdin and stdout instead of constructing shell commands around user-controlled paths\n\nContributors should treat these protections as required behavior. If a format change needs weaker policy or looser limits, that is an architectural change, not a local implementation tweak.\n\n## Operational Behavior\n\nThe preprocessing path is designed to fail explicitly rather than degrade silently.\n\n- invalid input is rejected during validation\n- unavailable ImageMagick raises preprocessing errors\n- timeout failures surface as preprocessing errors\n- unsupported extensions are rejected by the registry path\n\nThe converter then turns preprocessing failures into user-visible conversion failures for the preview API.\n\n## Configuration Surface\n\nThe main advanced settings for ImageMagick-backed preprocessing are:\n\n- `preprocessors.imagemagick.max_file_size_bytes`\n- `preprocessors.imagemagick.timeout_seconds`\n\nContributors should adjust those only when they understand the operational impact on preview latency, memory pressure, and denial-of-service resistance.\n\n## Adding or Changing a Preprocessing Path Safely\n\nUse this sequence when introducing a new preprocessable format or a new preprocessing backend:\n\n1. decide that the format really belongs in preprocessing rather than the ordinary libvips-backed conversion path\n2. implement or reuse a `PreprocessorInterface` subclass\n3. register the extension in `PreprocessorRegistry`\n4. update file-type metadata and viewer expectations if the format becomes previewable\n5. validate ImageMagick policy or other tool-level constraints if the new path needs different capabilities\n6. add backend tests for availability, validation, timeout behavior, and successful conversion output\n\nIf you skip the first decision, it becomes easy to route a format through preprocessing simply because it works locally, even when it weakens the long-term architecture.\n\n## Common Failure Modes\n\n- a new format is registered for preprocessing when the ordinary conversion path would have been safer or simpler\n- extension registration and file-type metadata drift apart\n- ImageMagick availability differs between local development and deployment\n- policy restrictions block a format in production even though it worked in a permissive local environment\n- timeout or file-size limits are raised casually to make one sample file work, increasing operational risk for everyone else\n\n## Where to Continue\n\n- Use [Viewer Architecture and Preview Contracts](../../frontend-architecture/viewer-architecture-and-preview-contracts/) for the browser-visible preview contract, file-type registry alignment, and viewer routing implications.\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider validation coverage.\n\n## Validation Expectations\n\nWhen you change preprocessing or image-conversion architecture, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects preview behavior, add the relevant frontend checks as well.\n", "1.0": "+++\ntitle = \"Image Preprocessing and Conversion Pipeline\"\n+++\n\nSambee's image preview path is not one converter with one code path.\n\nFor browser preview, the backend uses two related layers:\n\n- `backend/app/services/image_converter.py` for the general conversion pipeline\n- `backend/app/services/preprocessor.py` for formats that must be normalized before the general pipeline can produce browser-ready output\n\nUse this page when a format change affects backend conversion behavior, external image-tool dependencies, or preprocessing policy.\n\n## Why Preprocessing Exists\n\nSome formats can be decoded and converted directly through the main image-conversion path.\n\nOthers need an explicit preprocessing stage first because Sambee does not rely on the normal stack to decode them safely or usefully for browser preview.\n\nThat is the current role of preprocessing for formats such as:\n\n- `psd`\n- `psb`\n- `eps`\n- `ai`\n\nThe design goal is direct conversion to the final browser-ready result, not a chain of intermediate file formats.\n\n## Main Backend Pieces\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/services/image_converter.py` | primary image conversion path, libvips-backed processing, output-format selection, resizing, and MIME return values |\n| `backend/app/services/preprocessor.py` | preprocessor abstraction, ImageMagick-backed implementation, format registry, and factory behavior |\n| `backend/app/core/image_settings.py` | centralized encoder arguments and output-tuning settings |\n| `imagemagick-policy.xml` | repository-managed ImageMagick policy that constrains resource and delegate behavior |\n\n## Runtime Flow\n\nAt a high level, the backend image-preview flow is:\n\n1. the viewer request reaches the backend preview path\n2. the backend determines the file extension and preview behavior\n3. the converter checks whether the extension requires preprocessing\n4. preprocessable formats are sent to the registered preprocessor directly to produce browser-ready bytes\n5. all other convertible formats stay on the libvips-backed conversion path\n6. the viewer endpoint returns the converted bytes with the resulting MIME type\n\nThis is why preview changes can span registry metadata, service logic, environment dependencies, and viewer expectations at the same time.\n\n## General Conversion Path\n\n`convert_image_for_viewer(...)` in `image_converter.py` is the main entry point.\n\nFor the general conversion path it is responsible for:\n\n- loading image data through libvips\n- detecting alpha handling needs\n- converting colorspaces for web-safe output\n- downscaling when max dimensions are configured\n- choosing a final output format such as WebP, JPEG, or PNG\n- returning `(bytes, mime_type, converter_name, duration_ms)` for the caller\n\nThis is the path used for formats such as TIFF, HEIC, BMP, ICO, and similar server-converted formats that do not need the separate preprocessing registry.\n\n## Preprocessing Path\n\nWhen the extension is registered in `PreprocessorRegistry`, the converter takes a different route.\n\n`PreprocessorRegistry.requires_preprocessing(extension)` decides whether the format uses the preprocessing path.\n\nIf it does:\n\n1. the converter resolves the preprocessor with `get_preprocessor_for_format(...)`\n2. the preprocessor converts the source bytes directly to the final browser-ready format\n3. the converter returns those bytes without sending them through a second conversion stage\n\nCurrent product behavior intentionally chooses:\n\n- JPEG output for raster-oriented preprocessable formats such as PSD and PSB\n- PNG output for vector-style preprocessable formats such as EPS and AI when transparency preservation matters more\n\nThat is a product behavior decision, not just an implementation convenience.\n\n## Preprocessor Abstractions\n\nThe preprocessing service is structured around three backend concepts.\n\n### Preprocessorinterface\n\n`PreprocessorInterface` defines the contract every preprocessor must satisfy.\n\nKey responsibilities include:\n\n- `check_availability()`\n- `validate_input(...)`\n- `convert_to_final_format(...)`\n\nIt also centralizes file-size and timeout access through system settings so those limits do not get hard-coded in format-specific code.\n\n### Imagemagickpreprocessor\n\n`ImageMagickPreprocessor` is the only built-in implementation today.\n\nIt is responsible for:\n\n- requiring ImageMagick 7 through `magick`\n- validating supported extensions\n- converting PSD, PSB, EPS, and AI input directly to JPEG or PNG\n- applying centralized output arguments from `image_settings.py`\n- handling colorspace normalization, including CMYK-to-sRGB conversion behavior\n- enforcing timeout and size checks before or during conversion\n\nFor vector formats such as EPS and AI, it also applies density settings so rendered output quality is usable in the browser.\n\n### Preprocessor Registry and Factory\n\n`PreprocessorRegistry` is the single source of truth for which extensions require preprocessing and which preprocessor class handles them.\n\nThe registry:\n\n- normalizes extension lookup case-insensitively\n- maps extensions such as `psd`, `psb`, `eps`, and `ai` to `ImageMagickPreprocessor`\n- allows explicit runtime registration of additional formats\n- does not implement multi-tool fallback chains itself\n\n`PreprocessorFactory` is the configuration-oriented construction layer.\n\nIt currently supports:\n\n- `PREPROCESSOR=imagemagick`\n- `PREPROCESSOR=auto`\n\n`auto` currently means: use ImageMagick if it is available.\n\n## Security and Policy Constraints\n\nThe preprocessing path runs external tooling, so its constraints are part of the product contract.\n\nImportant protections include:\n\n- repository-managed ImageMagick policy in `imagemagick-policy.xml`\n- resource limits for memory, disk, and image dimensions\n- disabled network delegates\n- disabled indirect path reads\n- application-layer behavior that pipes bytes through stdin and stdout instead of constructing shell commands around user-controlled paths\n\nContributors should treat these protections as required behavior. If a format change needs weaker policy or looser limits, that is an architectural change, not a local implementation tweak.\n\n## Operational Behavior\n\nThe preprocessing path is designed to fail explicitly rather than degrade silently.\n\n- invalid input is rejected during validation\n- unavailable ImageMagick raises preprocessing errors\n- timeout failures surface as preprocessing errors\n- unsupported extensions are rejected by the registry path\n\nThe converter then turns preprocessing failures into user-visible conversion failures for the preview API.\n\n## Configuration Surface\n\nThe main advanced settings for ImageMagick-backed preprocessing are:\n\n- `preprocessors.imagemagick.max_file_size_bytes`\n- `preprocessors.imagemagick.timeout_seconds`\n\nContributors should adjust those only when they understand the operational impact on preview latency, memory pressure, and denial-of-service resistance.\n\n## Adding or Changing a Preprocessing Path Safely\n\nUse this sequence when introducing a new preprocessable format or a new preprocessing backend:\n\n1. decide that the format really belongs in preprocessing rather than the ordinary libvips-backed conversion path\n2. implement or reuse a `PreprocessorInterface` subclass\n3. register the extension in `PreprocessorRegistry`\n4. update file-type metadata and viewer expectations if the format becomes previewable\n5. validate ImageMagick policy or other tool-level constraints if the new path needs different capabilities\n6. add backend tests for availability, validation, timeout behavior, and successful conversion output\n\nIf you skip the first decision, it becomes easy to route a format through preprocessing simply because it works locally, even when it weakens the long-term architecture.\n\n## Common Failure Modes\n\n- a new format is registered for preprocessing when the ordinary conversion path would have been safer or simpler\n- extension registration and file-type metadata drift apart\n- ImageMagick availability differs between local development and deployment\n- policy restrictions block a format in production even though it worked in a permissive local environment\n- timeout or file-size limits are raised casually to make one sample file work, increasing operational risk for everyone else\n\n## Where to Continue\n\n- Use [Viewer Architecture and Preview Contracts](../../frontend-architecture/viewer-architecture-and-preview-contracts/) for the browser-visible preview contract, file-type registry alignment, and viewer routing implications.\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider validation coverage.\n\n## Validation Expectations\n\nWhen you change preprocessing or image-conversion architecture, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects preview behavior, add the relevant frontend checks as well.\n", "2.0": "+++\ntitle = \"Image Preprocessing and Conversion Pipeline\"\n+++\n\nSambee's image preview path is not one converter with one code path.\n\nFor browser preview, the backend uses two related layers:\n\n- `backend/app/services/image_converter.py` for the general conversion pipeline\n- `backend/app/services/preprocessor.py` for formats that must be normalized before the general pipeline can produce browser-ready output\n\nUse this page when a format change affects backend conversion behavior, external image-tool dependencies, or preprocessing policy.\n\n## Why Preprocessing Exists\n\nSome formats can be decoded and converted directly through the main image-conversion path.\n\nOthers need an explicit preprocessing stage first because Sambee does not rely on the normal stack to decode them safely or usefully for browser preview.\n\nThat is the current role of preprocessing for formats such as:\n\n- `psd`\n- `psb`\n- `eps`\n- `ai`\n\nThe design goal is direct conversion to the final browser-ready result, not a chain of intermediate file formats.\n\n## Main Backend Pieces\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/services/image_converter.py` | primary image conversion path, libvips-backed processing, output-format selection, resizing, and MIME return values |\n| `backend/app/services/preprocessor.py` | preprocessor abstraction, ImageMagick-backed implementation, format registry, and factory behavior |\n| `backend/app/core/image_settings.py` | centralized encoder arguments and output-tuning settings |\n| `imagemagick-policy.xml` | repository-managed ImageMagick policy that constrains resource and delegate behavior |\n\n## Runtime Flow\n\nAt a high level, the backend image-preview flow is:\n\n1. the viewer request reaches the backend preview path\n2. the backend determines the file extension and preview behavior\n3. the converter checks whether the extension requires preprocessing\n4. preprocessable formats are sent to the registered preprocessor directly to produce browser-ready bytes\n5. all other convertible formats stay on the libvips-backed conversion path\n6. the viewer endpoint returns the converted bytes with the resulting MIME type\n\nThis is why preview changes can span registry metadata, service logic, environment dependencies, and viewer expectations at the same time.\n\n## General Conversion Path\n\n`convert_image_for_viewer(...)` in `image_converter.py` is the main entry point.\n\nFor the general conversion path it is responsible for:\n\n- loading image data through libvips\n- detecting alpha handling needs\n- converting colorspaces for web-safe output\n- downscaling when max dimensions are configured\n- choosing a final output format such as WebP, JPEG, or PNG\n- returning `(bytes, mime_type, converter_name, duration_ms)` for the caller\n\nThis is the path used for formats such as TIFF, HEIC, BMP, ICO, and similar server-converted formats that do not need the separate preprocessing registry.\n\n## Preprocessing Path\n\nWhen the extension is registered in `PreprocessorRegistry`, the converter takes a different route.\n\n`PreprocessorRegistry.requires_preprocessing(extension)` decides whether the format uses the preprocessing path.\n\nIf it does:\n\n1. the converter resolves the preprocessor with `get_preprocessor_for_format(...)`\n2. the preprocessor converts the source bytes directly to the final browser-ready format\n3. the converter returns those bytes without sending them through a second conversion stage\n\nCurrent product behavior intentionally chooses:\n\n- JPEG output for raster-oriented preprocessable formats such as PSD and PSB\n- PNG output for vector-style preprocessable formats such as EPS and AI when transparency preservation matters more\n\nThat is a product behavior decision, not just an implementation convenience.\n\n## Preprocessor Abstractions\n\nThe preprocessing service is structured around three backend concepts.\n\n### Preprocessorinterface\n\n`PreprocessorInterface` defines the contract every preprocessor must satisfy.\n\nKey responsibilities include:\n\n- `check_availability()`\n- `validate_input(...)`\n- `convert_to_final_format(...)`\n\nIt also centralizes file-size and timeout access through system settings so those limits do not get hard-coded in format-specific code.\n\n### Imagemagickpreprocessor\n\n`ImageMagickPreprocessor` is the only built-in implementation today.\n\nIt is responsible for:\n\n- requiring ImageMagick 7 through `magick`\n- validating supported extensions\n- converting PSD, PSB, EPS, and AI input directly to JPEG or PNG\n- applying centralized output arguments from `image_settings.py`\n- handling colorspace normalization, including CMYK-to-sRGB conversion behavior\n- enforcing timeout and size checks before or during conversion\n\nFor vector formats such as EPS and AI, it also applies density settings so rendered output quality is usable in the browser.\n\n### Preprocessor Registry and Factory\n\n`PreprocessorRegistry` is the single source of truth for which extensions require preprocessing and which preprocessor class handles them.\n\nThe registry:\n\n- normalizes extension lookup case-insensitively\n- maps extensions such as `psd`, `psb`, `eps`, and `ai` to `ImageMagickPreprocessor`\n- allows explicit runtime registration of additional formats\n- does not implement multi-tool fallback chains itself\n\n`PreprocessorFactory` is the configuration-oriented construction layer.\n\nIt currently supports:\n\n- `PREPROCESSOR=imagemagick`\n- `PREPROCESSOR=auto`\n\n`auto` currently means: use ImageMagick if it is available.\n\n## Security and Policy Constraints\n\nThe preprocessing path runs external tooling, so its constraints are part of the product contract.\n\nImportant protections include:\n\n- repository-managed ImageMagick policy in `imagemagick-policy.xml`\n- resource limits for memory, disk, and image dimensions\n- disabled network delegates\n- disabled indirect path reads\n- application-layer behavior that pipes bytes through stdin and stdout instead of constructing shell commands around user-controlled paths\n\nContributors should treat these protections as required behavior. If a format change needs weaker policy or looser limits, that is an architectural change, not a local implementation tweak.\n\n## Operational Behavior\n\nThe preprocessing path is designed to fail explicitly rather than degrade silently.\n\n- invalid input is rejected during validation\n- unavailable ImageMagick raises preprocessing errors\n- timeout failures surface as preprocessing errors\n- unsupported extensions are rejected by the registry path\n\nThe converter then turns preprocessing failures into user-visible conversion failures for the preview API.\n\n## Configuration Surface\n\nThe main advanced settings for ImageMagick-backed preprocessing are:\n\n- `preprocessors.imagemagick.max_file_size_bytes`\n- `preprocessors.imagemagick.timeout_seconds`\n\nContributors should adjust those only when they understand the operational impact on preview latency, memory pressure, and denial-of-service resistance.\n\n## Adding or Changing a Preprocessing Path Safely\n\nUse this sequence when introducing a new preprocessable format or a new preprocessing backend:\n\n1. decide that the format really belongs in preprocessing rather than the ordinary libvips-backed conversion path\n2. implement or reuse a `PreprocessorInterface` subclass\n3. register the extension in `PreprocessorRegistry`\n4. update file-type metadata and viewer expectations if the format becomes previewable\n5. validate ImageMagick policy or other tool-level constraints if the new path needs different capabilities\n6. add backend tests for availability, validation, timeout behavior, and successful conversion output\n\nIf you skip the first decision, it becomes easy to route a format through preprocessing simply because it works locally, even when it weakens the long-term architecture.\n\n## Common Failure Modes\n\n- a new format is registered for preprocessing when the ordinary conversion path would have been safer or simpler\n- extension registration and file-type metadata drift apart\n- ImageMagick availability differs between local development and deployment\n- policy restrictions block a format in production even though it worked in a permissive local environment\n- timeout or file-size limits are raised casually to make one sample file work, increasing operational risk for everyone else\n\n## Where to Continue\n\n- Use [Viewer Architecture and Preview Contracts](../../frontend-architecture/viewer-architecture-and-preview-contracts/) for the browser-visible preview contract, file-type registry alignment, and viewer routing implications.\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider validation coverage.\n\n## Validation Expectations\n\nWhen you change preprocessing or image-conversion architecture, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects preview behavior, add the relevant frontend checks as well.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/backend-architecture/smb-change-notification-and-directory-freshness", "parent_id": "section:developer-guide/backend-architecture", "depth": 2, "kind": "page", "label": "smb-change-notification-and-directory-freshness", "title": "Smb Change Notification And Directory Freshness", "path": "developer-guide/backend-architecture/smb-change-notification-and-directory-freshness", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "branched", "source_version": "0.7", "diff_added": 23, "diff_removed": 1}}, "content_versions": {"0.7": "+++\ntitle = \"SMB Change Notification and Directory Freshness\"\n+++\n\nSambee uses SMB2/SMB3 `CHANGE_NOTIFY` support to keep directory state fresh without falling back to naive polling.\n\nThat capability is used in two different backend paths:\n\n- `backend/app/services/directory_monitor.py` for browser-visible WebSocket refresh notifications\n- `backend/app/services/directory_cache.py` for per-connection directory-cache freshness\n\nUse this page when a backend change affects WebSocket directory updates, SMB watcher lifecycle, or how the product maintains fresh directory state over time.\n\n## Why This Matters\n\nDirectory freshness is a cross-boundary product contract.\n\nUsers expect Sambee to react when:\n\n- another SMB client creates, deletes, renames, or edits content in the current directory\n- the current browser view should refresh because the underlying SMB directory changed\n- cached directory-search data should stay reasonably current without rescanning the entire tree on every request\n\nThat is why the backend owns change-notification behavior instead of leaving refresh decisions entirely to the browser.\n\n## The Two Change-Notification Paths\n\nSambee does not have a single watcher for all purposes.\n\n### Browser Notification Path\n\n`directory_monitor.py` is responsible for directory-specific monitoring tied to active WebSocket subscriptions.\n\nIts job is to:\n\n- start watching a directory when the first browser subscriber appears\n- share one SMB monitor across multiple subscribers for the same watched path\n- stop monitoring when the last subscriber leaves\n- send `directory_changed` messages back through the WebSocket layer\n\nThis is the path that keeps an open file browser view fresh.\n\n### Directory-Cache Freshness Path\n\n`directory_cache.py` uses its own `CHANGE_NOTIFY` watcher for a different reason.\n\nIts job is to:\n\n- watch the share root or effective path prefix for directory-name changes\n- keep the in-memory directory cache aligned with adds, removes, and renames\n- combine event-driven updates with periodic full rescans as a safety net\n- preserve fast directory-search behavior without rebuilding the entire cache on every navigation event\n\nThis is not the same as the browser WebSocket monitor, even though both rely on SMB `CHANGE_NOTIFY`.\n\n## Browser Notification Flow\n\nAt a high level, the browser-facing flow is:\n\n1. the browser opens the backend WebSocket endpoint\n2. it sends a subscription message for a connection and directory path\n3. `ConnectionManager` resolves access, applies any `path_prefix`, and starts monitoring if this is the first subscriber\n4. `DirectoryMonitor` opens SMB resources for that resolved directory and starts a background watcher thread\n5. when the SMB server reports a change, the backend emits `directory_changed` to all subscribers for the user-facing path\n6. when the last subscriber leaves, the monitor stops and releases its SMB resources\n\nRepresentative client messages include:\n\n- subscribe: `{ \"action\": \"subscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- unsubscribe: `{ \"action\": \"unsubscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- server notification: `{ \"type\": \"directory_changed\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n\n## Path Resolution and Subscription Keys\n\nOne subtle but important part of the design is that browser subscriptions and SMB watches do not always use the same path string.\n\nThe WebSocket layer keys subscriptions by the user-facing path.\n\nIf the SMB connection has a `path_prefix`, the backend resolves the actual watched SMB path by combining:\n\n- the normalized connection prefix\n- the user-facing relative path\n\nThat resolved SMB path is what `DirectoryMonitor` actually watches.\n\nThe callback then maps notifications back to the user-facing path before sending `directory_changed` over the WebSocket.\n\nIf you remove that mapping, subscriptions stop lining up with the paths the browser thinks it subscribed to.\n\n## Main Components\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/api/websocket.py` | WebSocket endpoint, subscription bookkeeping, access checks, path-prefix resolution, and delivery of `directory_changed` events |\n| `backend/app/services/directory_monitor.py` | per-directory SMB watchers for active browser subscriptions |\n| `backend/app/services/directory_cache.py` | per-connection directory cache plus root-level `CHANGE_NOTIFY` watcher for cache freshness |\n| `backend/app/main.py` | application shutdown hooks for directory caches and directory monitors |\n\n## Directory Monitor Lifecycle\n\nThe browser-facing monitor is reference-counted by subscription demand.\n\n`DirectoryMonitor` keeps one `MonitoredDirectory` per `connection_id:path` key and tracks subscriber counts.\n\nThat means:\n\n- the first subscriber starts the monitor\n- later subscribers reuse the same watched directory instance\n- unsubscribing decrements the count\n- the monitor only stops when the count reaches zero\n\nThis avoids opening duplicate SMB watcher handles for the same directory just because multiple browser clients are watching it.\n\n## SMB Resource Management\n\n`MonitoredDirectory` owns low-level SMB resources directly.\n\nCreation follows this order:\n\n1. connection\n2. session\n3. tree connect\n4. directory open handle\n5. `FileSystemWatcher`\n\nCleanup happens in reverse order so partial failure does not leak handles.\n\nThat ordering is important because change-notification bugs are often really handle-lifecycle bugs.\n\n## Watched Events\n\nThe browser-facing monitor currently watches for:\n\n- file-name changes\n- directory-name changes\n- size changes\n- last-write changes\n\nIt uses tree watching so changes in subdirectories can also surface through the same watch.\n\nThe directory-cache watcher is narrower by design.\n\nIt watches directory-name changes across the tree because the cache only needs enough signal to update its directory index efficiently.\n\n## Recovery and Failure Handling\n\nThe directory monitor treats connection failures as part of normal long-lived operation, not as impossible edge cases.\n\nCurrent behavior includes:\n\n- exponential backoff for reconnect attempts\n- retry jitter to avoid synchronized reconnect storms\n- capped retry attempts before giving up\n- explicit detection of connection, socket, and timeout failures\n- stop-on-delete behavior when the watched directory itself is deleted\n\nThe cache watcher has its own retry loop and also tolerates `CHANGE_NOTIFY` buffer-overflow conditions by relying on later rescans to restore correctness.\n\nThat distinction matters: browser notification is path-specific and subscriber-driven, while the cache watcher is connection-scoped and consistency-oriented.\n\n## Shutdown Behavior\n\nSambee shuts these systems down explicitly.\n\nDuring application shutdown:\n\n- directory caches are stopped through `shutdown_directory_cache()`\n- directory monitors are stopped through `shutdown_monitor()`\n\nThat explicit shutdown path exists to release watcher threads and SMB handles cleanly instead of depending on interpreter teardown.\n\n## Performance Characteristics\n\nThe design tries to keep freshness inexpensive without resorting to constant polling.\n\n- SMB `CHANGE_NOTIFY` is event-driven rather than poll-based\n- multiple browser subscribers share one monitor for the same watched path\n- directory-cache updates avoid full rescans for every single directory rename or add event\n- periodic rescans remain in place as a correctness safety net, not the primary freshness mechanism\n\n## Limits and Tradeoffs\n\nContributors need to preserve a few constraints here.\n\n- this requires SMB2 or later\n- some notifications can still be missed during network instability, which is why manual refresh and periodic cache rescans still matter\n- the browser-facing path is optimized for telling clients to refresh, not for transmitting rich per-file diffs\n- cache freshness and browser freshness are related concerns, but they are not the same subsystem and should not be collapsed casually\n\n## Common Failure Modes\n\n- path-prefix resolution is ignored, so the monitor watches the wrong SMB directory\n- subscriber bookkeeping drifts, so monitors are leaked or stopped too early\n- WebSocket disconnect cleanup forgets to release the last subscriber's monitor\n- a recovery change handles one timeout path but leaks SMB resources on reconnect\n- buffer-overflow or rename-edge handling is simplified in ways that quietly degrade cache correctness\n\n## Where to Continue\n\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the changed behavior interacts with uploads, moves, renames, or companion-assisted editing.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider backend or browser validation.\n\n## Validation Expectations\n\nWhen you change SMB change-notification behavior, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects browser-visible refresh behavior, add the relevant frontend checks as well.\n", "0.8": "+++\ntitle = \"SMB Change Notification and Directory Freshness\"\n+++\n\nSambee uses SMB2/SMB3 `CHANGE_NOTIFY` support to keep directory state fresh without falling back to naive polling.\n\nThat capability is used in two different backend paths:\n\n- `backend/app/services/directory_monitor.py` for browser-visible WebSocket refresh notifications\n- `backend/app/services/directory_cache.py` for per-connection directory-cache freshness\n\nUse this page when a backend change affects WebSocket directory updates, SMB watcher lifecycle, or how the product maintains fresh directory state over time.\n\n## Why This Matters\n\nDirectory freshness is a cross-boundary product contract.\n\nUsers expect Sambee to react when:\n\n- another SMB client creates, deletes, renames, or edits content in the current directory\n- the current browser view should refresh because the underlying SMB directory changed\n- cached directory-search data should stay reasonably current without rescanning the entire tree on every request\n\nThat is why the backend owns change-notification behavior instead of leaving refresh decisions entirely to the browser.\n\n## The Two Change-Notification Paths\n\nSambee does not have a single watcher for all purposes.\n\n### Browser Notification Path\n\n`directory_monitor.py` is responsible for directory-specific monitoring tied to active WebSocket subscriptions.\n\nIts job is to:\n\n- start watching a directory when the first browser subscriber appears\n- share one SMB monitor across multiple subscribers for the same watched path\n- stop monitoring when the last subscriber leaves\n- send `directory_changed` messages back through the WebSocket layer\n\nThis is the path that keeps an open file browser view fresh.\n\n### Directory-Cache Freshness Path\n\n`directory_cache.py` uses its own `CHANGE_NOTIFY` watcher for a different reason.\n\nIts job is to:\n\n- watch the share root or effective path prefix for directory-name changes\n- keep the in-memory directory cache aligned with adds, removes, and renames\n- combine event-driven updates with periodic full rescans as a safety net\n- preserve fast directory-search behavior without rebuilding the entire cache on every navigation event\n\nThis is not the same as the browser WebSocket monitor, even though both rely on SMB `CHANGE_NOTIFY`.\n\n## Browser Notification Flow\n\nAt a high level, the browser-facing flow is:\n\n1. the browser opens the backend WebSocket endpoint\n2. it sends a subscription message for a connection and directory path\n3. `ConnectionManager` resolves access, applies any `path_prefix`, and starts monitoring if this is the first subscriber\n4. `DirectoryMonitor` opens SMB resources for that resolved directory and starts a background watcher thread\n5. when the SMB server reports a change, the backend emits `directory_changed` to all subscribers for the user-facing path\n6. when the last subscriber leaves, the monitor stops and releases its SMB resources\n\nRepresentative client messages include:\n\n- subscribe: `{ \"action\": \"subscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- unsubscribe: `{ \"action\": \"unsubscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- server notification: `{ \"type\": \"directory_changed\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n\n## Path Resolution and Subscription Keys\n\nOne subtle but important part of the design is that browser subscriptions and SMB watches do not always use the same path string.\n\nThe WebSocket layer keys subscriptions by the user-facing path.\n\nIf the SMB connection has a `path_prefix`, the backend resolves the actual watched SMB path by combining:\n\n- the normalized connection prefix\n- the user-facing relative path\n\nThat resolved SMB path is what `DirectoryMonitor` actually watches.\n\nThe callback then maps notifications back to the user-facing path before sending `directory_changed` over the WebSocket.\n\nIf you remove that mapping, subscriptions stop lining up with the paths the browser thinks it subscribed to.\n\n## Main Components\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/api/websocket.py` | WebSocket endpoint, subscription bookkeeping, access checks, path-prefix resolution, and delivery of `directory_changed` events |\n| `backend/app/services/directory_monitor.py` | per-directory SMB watchers for active browser subscriptions |\n| `backend/app/services/directory_cache.py` | per-connection directory cache plus root-level `CHANGE_NOTIFY` watcher for cache freshness |\n| `backend/app/main.py` | application shutdown hooks for directory caches and directory monitors |\n\n## Directory Monitor Lifecycle\n\nThe browser-facing monitor is reference-counted by subscription demand.\n\n`DirectoryMonitor` keeps one `MonitoredDirectory` per `connection_id:path` key and tracks subscriber counts.\n\nThat means:\n\n- the first subscriber starts the monitor\n- later subscribers reuse the same watched directory instance\n- unsubscribing decrements the count\n- the monitor only stops when the count reaches zero\n\nThis avoids opening duplicate SMB watcher handles for the same directory just because multiple browser clients are watching it.\n\n## SMB Resource Management\n\n`MonitoredDirectory` owns low-level SMB resources directly.\n\nCreation follows this order:\n\n1. connection\n2. session\n3. tree connect\n4. directory open handle\n5. `FileSystemWatcher`\n\nCleanup happens in reverse order so partial failure does not leak handles.\n\nThat ordering is important because change-notification bugs are often really handle-lifecycle bugs.\n\n## Watched Events\n\nThe browser-facing monitor currently watches for:\n\n- file-name changes\n- directory-name changes\n- size changes\n- last-write changes\n\nIt uses tree watching so changes in subdirectories can also surface through the same watch.\n\nThe directory-cache watcher is narrower by design.\n\nIt watches directory-name changes across the tree because the cache only needs enough signal to update its directory index efficiently.\n\n## Recovery and Failure Handling\n\nThe directory monitor treats connection failures as part of normal long-lived operation, not as impossible edge cases.\n\nCurrent behavior includes:\n\n- exponential backoff for reconnect attempts\n- retry jitter to avoid synchronized reconnect storms\n- capped retry attempts before giving up\n- explicit detection of connection, socket, and timeout failures\n- stop-on-delete behavior when the watched directory itself is deleted\n\nThe cache watcher has its own retry loop and also tolerates `CHANGE_NOTIFY` buffer-overflow conditions by relying on later rescans to restore correctness.\n\nThat distinction matters: browser notification is path-specific and subscriber-driven, while the cache watcher is connection-scoped and consistency-oriented.\n\n## Shutdown Behavior\n\nSambee shuts these systems down explicitly.\n\nDuring application shutdown:\n\n- directory caches are stopped through `shutdown_directory_cache()`\n- directory monitors are stopped through `shutdown_monitor()`\n\nThat explicit shutdown path exists to release watcher threads and SMB handles cleanly instead of depending on interpreter teardown.\n\n## Performance Characteristics\n\nThe design tries to keep freshness inexpensive without resorting to constant polling.\n\n- SMB `CHANGE_NOTIFY` is event-driven rather than poll-based\n- multiple browser subscribers share one monitor for the same watched path\n- directory-cache updates avoid full rescans for every single directory rename or add event\n- periodic rescans remain in place as a correctness safety net, not the primary freshness mechanism\n\n## Limits and Tradeoffs\n\nContributors need to preserve a few constraints here.\n\n- this requires SMB2 or later\n- some notifications can still be missed during network instability, which is why manual refresh and periodic cache rescans still matter\n- the browser-facing path is optimized for telling clients to refresh, not for transmitting rich per-file diffs\n- cache freshness and browser freshness are related concerns, but they are not the same subsystem and should not be collapsed casually\n\n## Common Failure Modes\n\n- path-prefix resolution is ignored, so the monitor watches the wrong SMB directory\n- subscriber bookkeeping drifts, so monitors are leaked or stopped too early\n- WebSocket disconnect cleanup forgets to release the last subscriber's monitor\n- a recovery change handles one timeout path but leaks SMB resources on reconnect\n- buffer-overflow or rename-edge handling is simplified in ways that quietly degrade cache correctness\n\n## Where to Continue\n\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the changed behavior interacts with uploads, moves, renames, or companion-assisted editing.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider backend or browser validation.\n\n## Validation Expectations\n\nWhen you change SMB change-notification behavior, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects browser-visible refresh behavior, add the relevant frontend checks as well.\n", "0.9": "+++\ntitle = \"SMB Change Notification and Directory Freshness\"\n+++\n\nSambee uses SMB2/SMB3 `CHANGE_NOTIFY` support to keep directory state fresh without falling back to naive polling.\n\nThat capability is used in two different backend paths:\n\n- `backend/app/services/directory_monitor.py` for browser-visible WebSocket refresh notifications\n- `backend/app/services/directory_cache.py` for per-connection directory-cache freshness\n\nUse this page when a backend change affects WebSocket directory updates, SMB watcher lifecycle, or how the product maintains fresh directory state over time.\n\n## Why This Matters\n\nDirectory freshness is a cross-boundary product contract.\n\nUsers expect Sambee to react when:\n\n- another SMB client creates, deletes, renames, or edits content in the current directory\n- the current browser view should refresh because the underlying SMB directory changed\n- cached directory-search data should stay reasonably current without rescanning the entire tree on every request\n\nThat is why the backend owns change-notification behavior instead of leaving refresh decisions entirely to the browser.\n\n## The Two Change-Notification Paths\n\nSambee does not have a single watcher for all purposes.\n\n### Browser Notification Path\n\n`directory_monitor.py` is responsible for directory-specific monitoring tied to active WebSocket subscriptions.\n\nIts job is to:\n\n- start watching a directory when the first browser subscriber appears\n- share one SMB monitor across multiple subscribers for the same watched path\n- stop monitoring when the last subscriber leaves\n- send `directory_changed` messages back through the WebSocket layer\n\nThis is the path that keeps an open file browser view fresh.\n\n### Directory-Cache Freshness Path\n\n`directory_cache.py` uses its own `CHANGE_NOTIFY` watcher for a different reason.\n\nIts job is to:\n\n- watch the share root or effective path prefix for directory-name changes\n- keep the in-memory directory cache aligned with adds, removes, and renames\n- combine event-driven updates with periodic full rescans as a safety net\n- preserve fast directory-search behavior without rebuilding the entire cache on every navigation event\n\nThis is not the same as the browser WebSocket monitor, even though both rely on SMB `CHANGE_NOTIFY`.\n\n## Browser Notification Flow\n\nAt a high level, the browser-facing flow is:\n\n1. the browser opens the backend WebSocket endpoint\n2. it sends a subscription message for a connection and directory path\n3. `ConnectionManager` resolves access, applies any `path_prefix`, and starts monitoring if this is the first subscriber\n4. `DirectoryMonitor` opens SMB resources for that resolved directory and starts a background watcher thread\n5. when the SMB server reports a change, the backend emits `directory_changed` to all subscribers for the user-facing path\n6. when the last subscriber leaves, the monitor stops and releases its SMB resources\n\nRepresentative client messages include:\n\n- subscribe: `{ \"action\": \"subscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- unsubscribe: `{ \"action\": \"unsubscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- server notification: `{ \"type\": \"directory_changed\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n\n## Path Resolution and Subscription Keys\n\nOne subtle but important part of the design is that browser subscriptions and SMB watches do not always use the same path string.\n\nThe WebSocket layer keys subscriptions by the user-facing path.\n\nIf the SMB connection has a `path_prefix`, the backend resolves the actual watched SMB path by combining:\n\n- the normalized connection prefix\n- the user-facing relative path\n\nThat resolved SMB path is what `DirectoryMonitor` actually watches.\n\nThe callback then maps notifications back to the user-facing path before sending `directory_changed` over the WebSocket.\n\nIf you remove that mapping, subscriptions stop lining up with the paths the browser thinks it subscribed to.\n\n## Main Components\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/api/websocket.py` | WebSocket endpoint, subscription bookkeeping, access checks, path-prefix resolution, and delivery of `directory_changed` events |\n| `backend/app/services/directory_monitor.py` | per-directory SMB watchers for active browser subscriptions |\n| `backend/app/services/directory_cache.py` | per-connection directory cache plus root-level `CHANGE_NOTIFY` watcher for cache freshness |\n| `backend/app/main.py` | application shutdown hooks for directory caches and directory monitors |\n\n## Directory Monitor Lifecycle\n\nThe browser-facing monitor is reference-counted by subscription demand.\n\n`DirectoryMonitor` keeps one `MonitoredDirectory` per `connection_id:path` key and tracks subscriber counts.\n\nThat means:\n\n- the first subscriber starts the monitor\n- later subscribers reuse the same watched directory instance\n- unsubscribing decrements the count\n- the monitor only stops when the count reaches zero\n\nThis avoids opening duplicate SMB watcher handles for the same directory just because multiple browser clients are watching it.\n\n## SMB Resource Management\n\n`MonitoredDirectory` owns low-level SMB resources directly.\n\nCreation follows this order:\n\n1. connection\n2. session\n3. tree connect\n4. directory open handle\n5. `FileSystemWatcher`\n\nCleanup happens in reverse order so partial failure does not leak handles.\n\nThat ordering is important because change-notification bugs are often really handle-lifecycle bugs.\n\n## Watched Events\n\nThe browser-facing monitor currently watches for:\n\n- file-name changes\n- directory-name changes\n- size changes\n- last-write changes\n\nIt uses tree watching so changes in subdirectories can also surface through the same watch.\n\nThe directory-cache watcher is narrower by design.\n\nIt watches directory-name changes across the tree because the cache only needs enough signal to update its directory index efficiently.\n\n## Recovery and Failure Handling\n\nThe directory monitor treats connection failures as part of normal long-lived operation, not as impossible edge cases.\n\nCurrent behavior includes:\n\n- exponential backoff for reconnect attempts\n- retry jitter to avoid synchronized reconnect storms\n- capped retry attempts before giving up\n- explicit detection of connection, socket, and timeout failures\n- stop-on-delete behavior when the watched directory itself is deleted\n\nThe cache watcher has its own retry loop and also tolerates `CHANGE_NOTIFY` buffer-overflow conditions by relying on later rescans to restore correctness.\n\nThat distinction matters: browser notification is path-specific and subscriber-driven, while the cache watcher is connection-scoped and consistency-oriented.\n\n## Shutdown Behavior\n\nSambee shuts these systems down explicitly.\n\nDuring application shutdown:\n\n- directory caches are stopped through `shutdown_directory_cache()`\n- directory monitors are stopped through `shutdown_monitor()`\n\nThat explicit shutdown path exists to release watcher threads and SMB handles cleanly instead of depending on interpreter teardown.\n\n## Performance Characteristics\n\nThe design tries to keep freshness inexpensive without resorting to constant polling.\n\n- SMB `CHANGE_NOTIFY` is event-driven rather than poll-based\n- multiple browser subscribers share one monitor for the same watched path\n- directory-cache updates avoid full rescans for every single directory rename or add event\n- periodic rescans remain in place as a correctness safety net, not the primary freshness mechanism\n\n## Limits and Tradeoffs\n\nContributors need to preserve a few constraints here.\n\n- this requires SMB2 or later\n- some notifications can still be missed during network instability, which is why manual refresh and periodic cache rescans still matter\n- the browser-facing path is optimized for telling clients to refresh, not for transmitting rich per-file diffs\n- cache freshness and browser freshness are related concerns, but they are not the same subsystem and should not be collapsed casually\n\n## Common Failure Modes\n\n- path-prefix resolution is ignored, so the monitor watches the wrong SMB directory\n- subscriber bookkeeping drifts, so monitors are leaked or stopped too early\n- WebSocket disconnect cleanup forgets to release the last subscriber's monitor\n- a recovery change handles one timeout path but leaks SMB resources on reconnect\n- buffer-overflow or rename-edge handling is simplified in ways that quietly degrade cache correctness\n\n## Where to Continue\n\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the changed behavior interacts with uploads, moves, renames, or companion-assisted editing.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider backend or browser validation.\n\n## Validation Expectations\n\nWhen you change SMB change-notification behavior, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects browser-visible refresh behavior, add the relevant frontend checks as well.\n", "1.0": "+++\ntitle = \"SMB Change Notification and Directory Freshness\"\n+++\n\nSambee uses SMB2/SMB3 `CHANGE_NOTIFY` support to keep directory state fresh without falling back to naive polling.\n\nThat capability is used in two different backend paths:\n\n- `backend/app/services/directory_monitor.py` for browser-visible WebSocket refresh notifications\n- `backend/app/services/directory_cache.py` for per-connection directory-cache freshness\n\nUse this page when a backend change affects WebSocket directory updates, SMB watcher lifecycle, or how the product maintains fresh directory state over time.\n\n## Why This Matters\n\nDirectory freshness is a cross-boundary product contract.\n\nUsers expect Sambee to react when:\n\n- another SMB client creates, deletes, renames, or edits content in the current directory\n- the current browser view should refresh because the underlying SMB directory changed\n- cached directory-search data should stay reasonably current without rescanning the entire tree on every request\n\nThat is why the backend owns change-notification behavior instead of leaving refresh decisions entirely to the browser.\n\n## The Two Change-Notification Paths\n\nSambee does not have a single watcher for all purposes.\n\n### Browser Notification Path\n\n`directory_monitor.py` is responsible for directory-specific monitoring tied to active WebSocket subscriptions.\n\nIts job is to:\n\n- start watching a directory when the first browser subscriber appears\n- share one SMB monitor across multiple subscribers for the same watched path\n- stop monitoring when the last subscriber leaves\n- send `directory_changed` messages back through the WebSocket layer\n\nThis is the path that keeps an open file browser view fresh.\n\n### Directory-Cache Freshness Path\n\n`directory_cache.py` uses its own `CHANGE_NOTIFY` watcher for a different reason.\n\nIts job is to:\n\n- watch the share root or effective path prefix for directory-name changes\n- keep the in-memory directory cache aligned with adds, removes, and renames\n- combine event-driven updates with periodic full rescans as a safety net\n- preserve fast directory-search behavior without rebuilding the entire cache on every navigation event\n\nThis is not the same as the browser WebSocket monitor, even though both rely on SMB `CHANGE_NOTIFY`.\n\n## Browser Notification Flow\n\nAt a high level, the browser-facing flow is:\n\n1. the browser opens the backend WebSocket endpoint\n2. it sends a subscription message for a connection and directory path\n3. `ConnectionManager` resolves access, applies any `path_prefix`, and starts monitoring if this is the first subscriber\n4. `DirectoryMonitor` opens SMB resources for that resolved directory and starts a background watcher thread\n5. when the SMB server reports a change, the backend emits `directory_changed` to all subscribers for the user-facing path\n6. when the last subscriber leaves, the monitor stops and releases its SMB resources\n\nRepresentative client messages include:\n\n- subscribe: `{ \"action\": \"subscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- unsubscribe: `{ \"action\": \"unsubscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- server notification: `{ \"type\": \"directory_changed\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n\n## Path Resolution and Subscription Keys\n\nOne subtle but important part of the design is that browser subscriptions and SMB watches do not always use the same path string.\n\nThe WebSocket layer keys subscriptions by the user-facing path.\n\nIf the SMB connection has a `path_prefix`, the backend resolves the actual watched SMB path by combining:\n\n- the normalized connection prefix\n- the user-facing relative path\n\nThat resolved SMB path is what `DirectoryMonitor` actually watches.\n\nThe callback then maps notifications back to the user-facing path before sending `directory_changed` over the WebSocket.\n\nIf you remove that mapping, subscriptions stop lining up with the paths the browser thinks it subscribed to.\n\n## Main Components\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/api/websocket.py` | WebSocket endpoint, subscription bookkeeping, access checks, path-prefix resolution, and delivery of `directory_changed` events |\n| `backend/app/services/directory_monitor.py` | per-directory SMB watchers for active browser subscriptions |\n| `backend/app/services/directory_cache.py` | per-connection directory cache plus root-level `CHANGE_NOTIFY` watcher for cache freshness |\n| `backend/app/main.py` | application shutdown hooks for directory caches and directory monitors |\n\n## Directory Monitor Lifecycle\n\nThe browser-facing monitor is reference-counted by subscription demand.\n\n`DirectoryMonitor` keeps one `MonitoredDirectory` per `connection_id:path` key and tracks subscriber counts.\n\nThat means:\n\n- the first subscriber starts the monitor\n- later subscribers reuse the same watched directory instance\n- unsubscribing decrements the count\n- the monitor only stops when the count reaches zero\n\nThis avoids opening duplicate SMB watcher handles for the same directory just because multiple browser clients are watching it.\n\n## SMB Resource Management\n\n`MonitoredDirectory` owns low-level SMB resources directly.\n\nCreation follows this order:\n\n1. connection\n2. session\n3. tree connect\n4. directory open handle\n5. `FileSystemWatcher`\n\nCleanup happens in reverse order so partial failure does not leak handles.\n\nThat ordering is important because change-notification bugs are often really handle-lifecycle bugs.\n\n## Watched Events\n\nThe browser-facing monitor currently watches for:\n\n- file-name changes\n- directory-name changes\n- size changes\n- last-write changes\n\nIt uses tree watching so changes in subdirectories can also surface through the same watch.\n\nThe directory-cache watcher is narrower by design.\n\nIt watches directory-name changes across the tree because the cache only needs enough signal to update its directory index efficiently.\n\n## Recovery and Failure Handling\n\nThe directory monitor treats connection failures as part of normal long-lived operation, not as impossible edge cases.\n\nCurrent behavior includes:\n\n- exponential backoff for reconnect attempts\n- retry jitter to avoid synchronized reconnect storms\n- capped retry attempts before giving up\n- explicit detection of connection, socket, and timeout failures\n- stop-on-delete behavior when the watched directory itself is deleted\n\nThe cache watcher has its own retry loop and also tolerates `CHANGE_NOTIFY` buffer-overflow conditions by relying on later rescans to restore correctness.\n\nThat distinction matters: browser notification is path-specific and subscriber-driven, while the cache watcher is connection-scoped and consistency-oriented.\n\n## Shutdown Behavior\n\nSambee shuts these systems down explicitly.\n\nDuring application shutdown:\n\n- directory caches are stopped through `shutdown_directory_cache()`\n- directory monitors are stopped through `shutdown_monitor()`\n\nThat explicit shutdown path exists to release watcher threads and SMB handles cleanly instead of depending on interpreter teardown.\n\n## Performance Characteristics\n\nThe design tries to keep freshness inexpensive without resorting to constant polling.\n\n- SMB `CHANGE_NOTIFY` is event-driven rather than poll-based\n- multiple browser subscribers share one monitor for the same watched path\n- directory-cache updates avoid full rescans for every single directory rename or add event\n- periodic rescans remain in place as a correctness safety net, not the primary freshness mechanism\n\n## Limits and Tradeoffs\n\nContributors need to preserve a few constraints here.\n\n- this requires SMB2 or later\n- some notifications can still be missed during network instability, which is why manual refresh and periodic cache rescans still matter\n- the browser-facing path is optimized for telling clients to refresh, not for transmitting rich per-file diffs\n- cache freshness and browser freshness are related concerns, but they are not the same subsystem and should not be collapsed casually\n\n## Common Failure Modes\n\n- path-prefix resolution is ignored, so the monitor watches the wrong SMB directory\n- subscriber bookkeeping drifts, so monitors are leaked or stopped too early\n- WebSocket disconnect cleanup forgets to release the last subscriber's monitor\n- a recovery change handles one timeout path but leaks SMB resources on reconnect\n- buffer-overflow or rename-edge handling is simplified in ways that quietly degrade cache correctness\n\n## Where to Continue\n\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the changed behavior interacts with uploads, moves, renames, or companion-assisted editing.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider backend or browser validation.\n\n## Validation Expectations\n\nWhen you change SMB change-notification behavior, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects browser-visible refresh behavior, add the relevant frontend checks as well.\n", "2.0": "+++\ntitle = \"SMB Change Notification and Directory Freshness\"\n+++\n\nSambee uses SMB2/SMB3 `CHANGE_NOTIFY` support to keep directory state fresh without falling back to naive polling.\n\nThat capability is used in two different backend paths:\n\n- `backend/app/services/directory_monitor.py` for browser-visible WebSocket refresh notifications\n- `backend/app/services/directory_cache.py` for per-connection directory-cache freshness\n\nUse this page when a backend change affects WebSocket directory updates, SMB watcher lifecycle, or how the product maintains fresh directory state over time.\n\n## Why This Matters\n\nDirectory freshness is a cross-boundary product contract.\n\nUsers expect Sambee to react when:\n\n- another SMB client creates, deletes, renames, or edits content in the current directory\n- the current browser view should refresh because the underlying SMB directory changed\n- cached directory-search data should stay reasonably current without rescanning the entire tree on every request\n\nThat is why the backend owns change-notification behavior instead of leaving refresh decisions entirely to the browser.\n\n## The Two Change-Notification Paths\n\nSambee does not have a single watcher for all purposes.\n\n### Browser Notification Path\n\n`directory_monitor.py` is responsible for directory-specific monitoring tied to active WebSocket subscriptions.\n\nIts job is to:\n\n- start watching a directory when the first browser subscriber appears\n- share one SMB monitor across multiple subscribers for the same watched path\n- stop monitoring when the last subscriber leaves\n- send `directory_changed` messages back through the WebSocket layer\n\nThis is the path that keeps an open file browser view fresh.\n\n### Directory-Cache Freshness Path\n\n`directory_cache.py` uses its own `CHANGE_NOTIFY` watcher for a different reason.\n\nIts job is to:\n\n- watch the share root or effective path prefix for directory-name changes\n- keep the in-memory directory cache aligned with adds, removes, and renames\n- combine event-driven updates with periodic full rescans as a safety net\n- preserve fast directory-search behavior without rebuilding the entire cache on every navigation event\n\nThis is not the same as the browser WebSocket monitor, even though both rely on SMB `CHANGE_NOTIFY`.\n\n## Browser Notification Flow\n\nAt a high level, the browser-facing flow is:\n\n1. the browser opens the backend WebSocket endpoint\n2. it sends a subscription message for a connection and directory path\n3. `ConnectionManager` resolves access, applies any `path_prefix`, and starts monitoring if this is the first subscriber\n4. `DirectoryMonitor` opens SMB resources for that resolved directory and starts a background watcher thread\n5. when the SMB server reports a change, the backend emits `directory_changed` to all subscribers for the user-facing path\n6. when the last subscriber leaves, the monitor stops and releases its SMB resources\n\nRepresentative client messages include:\n\n- subscribe: `{ \"action\": \"subscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- unsubscribe: `{ \"action\": \"unsubscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- server notification: `{ \"type\": \"directory_changed\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n\n## Path Resolution and Subscription Keys\n\nOne subtle but important part of the design is that browser subscriptions and SMB watches do not always use the same path string.\n\nThe WebSocket layer keys subscriptions by the user-facing path.\n\nIf the SMB connection has a `path_prefix`, the backend resolves the actual watched SMB path by combining:\n\n- the normalized connection prefix\n- the user-facing relative path\n\nThat resolved SMB path is what `DirectoryMonitor` actually watches.\n\nThe callback then maps notifications back to the user-facing path before sending `directory_changed` over the WebSocket.\n\nIf you remove that mapping, subscriptions stop lining up with the paths the browser thinks it subscribed to.\n\n## Main Components\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/api/websocket.py` | WebSocket endpoint, subscription bookkeeping, access checks, path-prefix resolution, and delivery of `directory_changed` events |\n| `backend/app/services/directory_monitor.py` | per-directory SMB watchers for active browser subscriptions |\n| `backend/app/services/directory_cache.py` | per-connection directory cache plus root-level `CHANGE_NOTIFY` watcher for cache freshness |\n| `backend/app/main.py` | application shutdown hooks for directory caches and directory monitors |\n\n## Directory Monitor Lifecycle\n\nThe browser-facing monitor is reference-counted by subscription demand.\n\n`DirectoryMonitor` keeps one `MonitoredDirectory` per `connection_id:path` key and tracks subscriber counts.\n\nThat means:\n\n- the first subscriber starts the monitor\n- later subscribers reuse the same watched directory instance\n- unsubscribing decrements the count\n- the monitor only stops when the count reaches zero\n\nThis avoids opening duplicate SMB watcher handles for the same directory just because multiple browser clients are watching it.\n\n## SMB Resource Management\n\n`MonitoredDirectory` owns low-level SMB resources directly.\n\nCreation follows this order:\n\n1. connection\n2. session\n3. tree connect\n4. directory open handle\n5. `FileSystemWatcher`\n\nCleanup happens in reverse order so partial failure does not leak handles.\n\nThat ordering is important because change-notification bugs are often really handle-lifecycle bugs.\n\n## Watched Events\n\nThe browser-facing monitor currently watches for:\n\n- file-name changes\n- directory-name changes\n- size changes\n- last-write changes\n\nThe browser-facing monitor watches only immediate children of the subscribed directory. Writes deeper in the tree, such as installing packages in a project's `node_modules` folder, don't invalidate an ancestor's file list. If the SMB server reports a metadata change for an immediate child directory, that change can still trigger a refresh.\n\nThe directory-cache watcher is narrower by design.\n\nIt watches directory-name changes across the tree because the cache only needs enough signal to update its directory index efficiently.\n\n## Directory-Index Consistency\n\nA full rescan builds a replacement index while the current index continues to serve directory searches. If any directory read fails or times out, the replacement isn't published or persisted. The existing index remains available, and the scan error is recorded for diagnosis. A later successful rescan can replace it.\n\nWhile a rescan is running, directory additions, removals, and renames update the live index and are also recorded in order. Under the cache lock, Sambee checks pending operations before and after each directory read and before publication. Additions are safe to merge. Removals and renames can only be merged when they don't overlap a read that's already started.\n\nIf a removal or rename changes a directory that's already been read, one being read, an ancestor of either, or an immediate child's name, the replacement is ambiguous. Notifications can arrive after a read already reflects the change, so replaying them could rename or remove fresh paths a second time. Sambee discards the replacement rather than publishing or persisting it; the live index, including its recent changes, remains available. Only one rescan can run at a time, and cancellation discards pending reconciliation without discarding live updates.\n\nDirectory junctions, symbolic links, and unrecognized directory reparse points are indexed as destinations, but scans don't descend into their targets. This prevents ancestor links from causing repeated traversal. DFS referrals are identified by their reparse tag and remain traversable through the SMB client's referral support, so directories below DFS links stay searchable.\n\n### Persisted Snapshots\n\nVersion 2 snapshots are bound to the connection's host, port, share, normalized path prefix, username, and connection revision. The revision changes when the connection is edited, including credential changes. Passwords aren't stored in snapshot metadata.\n\nA snapshot with a different source identity is ignored, including when trying the backup file. Older version 1 snapshots are also ignored, so existing installations rebuild the directory index once after upgrading. Matching snapshots still provide immediate search results while background verification checks freshness.\n\nStartup verification and the periodic rescan loop have separate tracked tasks. Removing a cache or shutting down the application cancels both tasks, along with initial scanning and snapshot flushing.\n\n## Recovery and Failure Handling\n\nThe directory monitor treats connection failures as part of normal long-lived operation, not as impossible edge cases.\n\nCurrent behavior includes:\n\n- exponential backoff for reconnect attempts\n- retry jitter to avoid synchronized reconnect storms\n- capped retry attempts before giving up\n- explicit detection of connection, socket, and timeout failures\n- stop-on-delete behavior when the watched directory itself is deleted\n\nThe cache watcher has its own retry loop and also tolerates `CHANGE_NOTIFY` buffer-overflow conditions by relying on later rescans to restore correctness.\n\nThat distinction matters: browser notification is path-specific and subscriber-driven, while the cache watcher is connection-scoped and consistency-oriented.\n\n## Shutdown Behavior\n\nSambee shuts these systems down explicitly.\n\nDuring application shutdown:\n\n- directory caches are stopped through `shutdown_directory_cache()`\n- directory monitors are stopped through `shutdown_monitor()`\n\nThat explicit shutdown path exists to release watcher threads and SMB handles cleanly instead of depending on interpreter teardown.\n\n## Performance Characteristics\n\nThe design tries to keep freshness inexpensive without resorting to constant polling.\n\n- SMB `CHANGE_NOTIFY` is event-driven rather than poll-based\n- multiple browser subscribers share one monitor for the same watched path\n- browser-facing monitors don't request recursive subtree notifications\n- each browser pane keeps loaded physical-directory rows visible during automatic refreshes, including a previously loaded empty listing\n- automatic refreshes wait for an active listing request and combine newer notifications into one pending refresh, starting at most once per second\n- navigation and pane disposal cancel queued refreshes\n- directory-cache updates avoid full rescans for every single directory rename or add event\n- periodic rescans remain in place as a correctness safety net, not the primary freshness mechanism\n\n## Limits and Tradeoffs\n\nContributors need to preserve a few constraints here.\n\n- this requires SMB2 or later\n- some notifications can still be missed during network instability, which is why manual refresh and periodic cache rescans still matter\n- the browser-facing path is optimized for telling clients to refresh, not for transmitting rich per-file diffs\n- cache freshness and browser freshness are related concerns, but they are not the same subsystem and should not be collapsed casually\n\n## Common Failure Modes\n\n- path-prefix resolution is ignored, so the monitor watches the wrong SMB directory\n- subscriber bookkeeping drifts, so monitors are leaked or stopped too early\n- WebSocket disconnect cleanup forgets to release the last subscriber's monitor\n- a recovery change handles one timeout path but leaks SMB resources on reconnect\n- buffer-overflow or rename-edge handling is simplified in ways that quietly degrade cache correctness\n\n## Where to Continue\n\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the changed behavior interacts with uploads, moves, renames, or companion-assisted editing.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider backend or browser validation.\n\n## Validation Expectations\n\nWhen you change SMB change-notification behavior, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects browser-visible refresh behavior, add the relevant frontend checks as well.\n"}, "page_contents": {"0.7": "+++\ntitle = \"SMB Change Notification and Directory Freshness\"\n+++\n\nSambee uses SMB2/SMB3 `CHANGE_NOTIFY` support to keep directory state fresh without falling back to naive polling.\n\nThat capability is used in two different backend paths:\n\n- `backend/app/services/directory_monitor.py` for browser-visible WebSocket refresh notifications\n- `backend/app/services/directory_cache.py` for per-connection directory-cache freshness\n\nUse this page when a backend change affects WebSocket directory updates, SMB watcher lifecycle, or how the product maintains fresh directory state over time.\n\n## Why This Matters\n\nDirectory freshness is a cross-boundary product contract.\n\nUsers expect Sambee to react when:\n\n- another SMB client creates, deletes, renames, or edits content in the current directory\n- the current browser view should refresh because the underlying SMB directory changed\n- cached directory-search data should stay reasonably current without rescanning the entire tree on every request\n\nThat is why the backend owns change-notification behavior instead of leaving refresh decisions entirely to the browser.\n\n## The Two Change-Notification Paths\n\nSambee does not have a single watcher for all purposes.\n\n### Browser Notification Path\n\n`directory_monitor.py` is responsible for directory-specific monitoring tied to active WebSocket subscriptions.\n\nIts job is to:\n\n- start watching a directory when the first browser subscriber appears\n- share one SMB monitor across multiple subscribers for the same watched path\n- stop monitoring when the last subscriber leaves\n- send `directory_changed` messages back through the WebSocket layer\n\nThis is the path that keeps an open file browser view fresh.\n\n### Directory-Cache Freshness Path\n\n`directory_cache.py` uses its own `CHANGE_NOTIFY` watcher for a different reason.\n\nIts job is to:\n\n- watch the share root or effective path prefix for directory-name changes\n- keep the in-memory directory cache aligned with adds, removes, and renames\n- combine event-driven updates with periodic full rescans as a safety net\n- preserve fast directory-search behavior without rebuilding the entire cache on every navigation event\n\nThis is not the same as the browser WebSocket monitor, even though both rely on SMB `CHANGE_NOTIFY`.\n\n## Browser Notification Flow\n\nAt a high level, the browser-facing flow is:\n\n1. the browser opens the backend WebSocket endpoint\n2. it sends a subscription message for a connection and directory path\n3. `ConnectionManager` resolves access, applies any `path_prefix`, and starts monitoring if this is the first subscriber\n4. `DirectoryMonitor` opens SMB resources for that resolved directory and starts a background watcher thread\n5. when the SMB server reports a change, the backend emits `directory_changed` to all subscribers for the user-facing path\n6. when the last subscriber leaves, the monitor stops and releases its SMB resources\n\nRepresentative client messages include:\n\n- subscribe: `{ \"action\": \"subscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- unsubscribe: `{ \"action\": \"unsubscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- server notification: `{ \"type\": \"directory_changed\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n\n## Path Resolution and Subscription Keys\n\nOne subtle but important part of the design is that browser subscriptions and SMB watches do not always use the same path string.\n\nThe WebSocket layer keys subscriptions by the user-facing path.\n\nIf the SMB connection has a `path_prefix`, the backend resolves the actual watched SMB path by combining:\n\n- the normalized connection prefix\n- the user-facing relative path\n\nThat resolved SMB path is what `DirectoryMonitor` actually watches.\n\nThe callback then maps notifications back to the user-facing path before sending `directory_changed` over the WebSocket.\n\nIf you remove that mapping, subscriptions stop lining up with the paths the browser thinks it subscribed to.\n\n## Main Components\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/api/websocket.py` | WebSocket endpoint, subscription bookkeeping, access checks, path-prefix resolution, and delivery of `directory_changed` events |\n| `backend/app/services/directory_monitor.py` | per-directory SMB watchers for active browser subscriptions |\n| `backend/app/services/directory_cache.py` | per-connection directory cache plus root-level `CHANGE_NOTIFY` watcher for cache freshness |\n| `backend/app/main.py` | application shutdown hooks for directory caches and directory monitors |\n\n## Directory Monitor Lifecycle\n\nThe browser-facing monitor is reference-counted by subscription demand.\n\n`DirectoryMonitor` keeps one `MonitoredDirectory` per `connection_id:path` key and tracks subscriber counts.\n\nThat means:\n\n- the first subscriber starts the monitor\n- later subscribers reuse the same watched directory instance\n- unsubscribing decrements the count\n- the monitor only stops when the count reaches zero\n\nThis avoids opening duplicate SMB watcher handles for the same directory just because multiple browser clients are watching it.\n\n## SMB Resource Management\n\n`MonitoredDirectory` owns low-level SMB resources directly.\n\nCreation follows this order:\n\n1. connection\n2. session\n3. tree connect\n4. directory open handle\n5. `FileSystemWatcher`\n\nCleanup happens in reverse order so partial failure does not leak handles.\n\nThat ordering is important because change-notification bugs are often really handle-lifecycle bugs.\n\n## Watched Events\n\nThe browser-facing monitor currently watches for:\n\n- file-name changes\n- directory-name changes\n- size changes\n- last-write changes\n\nIt uses tree watching so changes in subdirectories can also surface through the same watch.\n\nThe directory-cache watcher is narrower by design.\n\nIt watches directory-name changes across the tree because the cache only needs enough signal to update its directory index efficiently.\n\n## Recovery and Failure Handling\n\nThe directory monitor treats connection failures as part of normal long-lived operation, not as impossible edge cases.\n\nCurrent behavior includes:\n\n- exponential backoff for reconnect attempts\n- retry jitter to avoid synchronized reconnect storms\n- capped retry attempts before giving up\n- explicit detection of connection, socket, and timeout failures\n- stop-on-delete behavior when the watched directory itself is deleted\n\nThe cache watcher has its own retry loop and also tolerates `CHANGE_NOTIFY` buffer-overflow conditions by relying on later rescans to restore correctness.\n\nThat distinction matters: browser notification is path-specific and subscriber-driven, while the cache watcher is connection-scoped and consistency-oriented.\n\n## Shutdown Behavior\n\nSambee shuts these systems down explicitly.\n\nDuring application shutdown:\n\n- directory caches are stopped through `shutdown_directory_cache()`\n- directory monitors are stopped through `shutdown_monitor()`\n\nThat explicit shutdown path exists to release watcher threads and SMB handles cleanly instead of depending on interpreter teardown.\n\n## Performance Characteristics\n\nThe design tries to keep freshness inexpensive without resorting to constant polling.\n\n- SMB `CHANGE_NOTIFY` is event-driven rather than poll-based\n- multiple browser subscribers share one monitor for the same watched path\n- directory-cache updates avoid full rescans for every single directory rename or add event\n- periodic rescans remain in place as a correctness safety net, not the primary freshness mechanism\n\n## Limits and Tradeoffs\n\nContributors need to preserve a few constraints here.\n\n- this requires SMB2 or later\n- some notifications can still be missed during network instability, which is why manual refresh and periodic cache rescans still matter\n- the browser-facing path is optimized for telling clients to refresh, not for transmitting rich per-file diffs\n- cache freshness and browser freshness are related concerns, but they are not the same subsystem and should not be collapsed casually\n\n## Common Failure Modes\n\n- path-prefix resolution is ignored, so the monitor watches the wrong SMB directory\n- subscriber bookkeeping drifts, so monitors are leaked or stopped too early\n- WebSocket disconnect cleanup forgets to release the last subscriber's monitor\n- a recovery change handles one timeout path but leaks SMB resources on reconnect\n- buffer-overflow or rename-edge handling is simplified in ways that quietly degrade cache correctness\n\n## Where to Continue\n\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the changed behavior interacts with uploads, moves, renames, or companion-assisted editing.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider backend or browser validation.\n\n## Validation Expectations\n\nWhen you change SMB change-notification behavior, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects browser-visible refresh behavior, add the relevant frontend checks as well.\n", "0.8": "+++\ntitle = \"SMB Change Notification and Directory Freshness\"\n+++\n\nSambee uses SMB2/SMB3 `CHANGE_NOTIFY` support to keep directory state fresh without falling back to naive polling.\n\nThat capability is used in two different backend paths:\n\n- `backend/app/services/directory_monitor.py` for browser-visible WebSocket refresh notifications\n- `backend/app/services/directory_cache.py` for per-connection directory-cache freshness\n\nUse this page when a backend change affects WebSocket directory updates, SMB watcher lifecycle, or how the product maintains fresh directory state over time.\n\n## Why This Matters\n\nDirectory freshness is a cross-boundary product contract.\n\nUsers expect Sambee to react when:\n\n- another SMB client creates, deletes, renames, or edits content in the current directory\n- the current browser view should refresh because the underlying SMB directory changed\n- cached directory-search data should stay reasonably current without rescanning the entire tree on every request\n\nThat is why the backend owns change-notification behavior instead of leaving refresh decisions entirely to the browser.\n\n## The Two Change-Notification Paths\n\nSambee does not have a single watcher for all purposes.\n\n### Browser Notification Path\n\n`directory_monitor.py` is responsible for directory-specific monitoring tied to active WebSocket subscriptions.\n\nIts job is to:\n\n- start watching a directory when the first browser subscriber appears\n- share one SMB monitor across multiple subscribers for the same watched path\n- stop monitoring when the last subscriber leaves\n- send `directory_changed` messages back through the WebSocket layer\n\nThis is the path that keeps an open file browser view fresh.\n\n### Directory-Cache Freshness Path\n\n`directory_cache.py` uses its own `CHANGE_NOTIFY` watcher for a different reason.\n\nIts job is to:\n\n- watch the share root or effective path prefix for directory-name changes\n- keep the in-memory directory cache aligned with adds, removes, and renames\n- combine event-driven updates with periodic full rescans as a safety net\n- preserve fast directory-search behavior without rebuilding the entire cache on every navigation event\n\nThis is not the same as the browser WebSocket monitor, even though both rely on SMB `CHANGE_NOTIFY`.\n\n## Browser Notification Flow\n\nAt a high level, the browser-facing flow is:\n\n1. the browser opens the backend WebSocket endpoint\n2. it sends a subscription message for a connection and directory path\n3. `ConnectionManager` resolves access, applies any `path_prefix`, and starts monitoring if this is the first subscriber\n4. `DirectoryMonitor` opens SMB resources for that resolved directory and starts a background watcher thread\n5. when the SMB server reports a change, the backend emits `directory_changed` to all subscribers for the user-facing path\n6. when the last subscriber leaves, the monitor stops and releases its SMB resources\n\nRepresentative client messages include:\n\n- subscribe: `{ \"action\": \"subscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- unsubscribe: `{ \"action\": \"unsubscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- server notification: `{ \"type\": \"directory_changed\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n\n## Path Resolution and Subscription Keys\n\nOne subtle but important part of the design is that browser subscriptions and SMB watches do not always use the same path string.\n\nThe WebSocket layer keys subscriptions by the user-facing path.\n\nIf the SMB connection has a `path_prefix`, the backend resolves the actual watched SMB path by combining:\n\n- the normalized connection prefix\n- the user-facing relative path\n\nThat resolved SMB path is what `DirectoryMonitor` actually watches.\n\nThe callback then maps notifications back to the user-facing path before sending `directory_changed` over the WebSocket.\n\nIf you remove that mapping, subscriptions stop lining up with the paths the browser thinks it subscribed to.\n\n## Main Components\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/api/websocket.py` | WebSocket endpoint, subscription bookkeeping, access checks, path-prefix resolution, and delivery of `directory_changed` events |\n| `backend/app/services/directory_monitor.py` | per-directory SMB watchers for active browser subscriptions |\n| `backend/app/services/directory_cache.py` | per-connection directory cache plus root-level `CHANGE_NOTIFY` watcher for cache freshness |\n| `backend/app/main.py` | application shutdown hooks for directory caches and directory monitors |\n\n## Directory Monitor Lifecycle\n\nThe browser-facing monitor is reference-counted by subscription demand.\n\n`DirectoryMonitor` keeps one `MonitoredDirectory` per `connection_id:path` key and tracks subscriber counts.\n\nThat means:\n\n- the first subscriber starts the monitor\n- later subscribers reuse the same watched directory instance\n- unsubscribing decrements the count\n- the monitor only stops when the count reaches zero\n\nThis avoids opening duplicate SMB watcher handles for the same directory just because multiple browser clients are watching it.\n\n## SMB Resource Management\n\n`MonitoredDirectory` owns low-level SMB resources directly.\n\nCreation follows this order:\n\n1. connection\n2. session\n3. tree connect\n4. directory open handle\n5. `FileSystemWatcher`\n\nCleanup happens in reverse order so partial failure does not leak handles.\n\nThat ordering is important because change-notification bugs are often really handle-lifecycle bugs.\n\n## Watched Events\n\nThe browser-facing monitor currently watches for:\n\n- file-name changes\n- directory-name changes\n- size changes\n- last-write changes\n\nIt uses tree watching so changes in subdirectories can also surface through the same watch.\n\nThe directory-cache watcher is narrower by design.\n\nIt watches directory-name changes across the tree because the cache only needs enough signal to update its directory index efficiently.\n\n## Recovery and Failure Handling\n\nThe directory monitor treats connection failures as part of normal long-lived operation, not as impossible edge cases.\n\nCurrent behavior includes:\n\n- exponential backoff for reconnect attempts\n- retry jitter to avoid synchronized reconnect storms\n- capped retry attempts before giving up\n- explicit detection of connection, socket, and timeout failures\n- stop-on-delete behavior when the watched directory itself is deleted\n\nThe cache watcher has its own retry loop and also tolerates `CHANGE_NOTIFY` buffer-overflow conditions by relying on later rescans to restore correctness.\n\nThat distinction matters: browser notification is path-specific and subscriber-driven, while the cache watcher is connection-scoped and consistency-oriented.\n\n## Shutdown Behavior\n\nSambee shuts these systems down explicitly.\n\nDuring application shutdown:\n\n- directory caches are stopped through `shutdown_directory_cache()`\n- directory monitors are stopped through `shutdown_monitor()`\n\nThat explicit shutdown path exists to release watcher threads and SMB handles cleanly instead of depending on interpreter teardown.\n\n## Performance Characteristics\n\nThe design tries to keep freshness inexpensive without resorting to constant polling.\n\n- SMB `CHANGE_NOTIFY` is event-driven rather than poll-based\n- multiple browser subscribers share one monitor for the same watched path\n- directory-cache updates avoid full rescans for every single directory rename or add event\n- periodic rescans remain in place as a correctness safety net, not the primary freshness mechanism\n\n## Limits and Tradeoffs\n\nContributors need to preserve a few constraints here.\n\n- this requires SMB2 or later\n- some notifications can still be missed during network instability, which is why manual refresh and periodic cache rescans still matter\n- the browser-facing path is optimized for telling clients to refresh, not for transmitting rich per-file diffs\n- cache freshness and browser freshness are related concerns, but they are not the same subsystem and should not be collapsed casually\n\n## Common Failure Modes\n\n- path-prefix resolution is ignored, so the monitor watches the wrong SMB directory\n- subscriber bookkeeping drifts, so monitors are leaked or stopped too early\n- WebSocket disconnect cleanup forgets to release the last subscriber's monitor\n- a recovery change handles one timeout path but leaks SMB resources on reconnect\n- buffer-overflow or rename-edge handling is simplified in ways that quietly degrade cache correctness\n\n## Where to Continue\n\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the changed behavior interacts with uploads, moves, renames, or companion-assisted editing.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider backend or browser validation.\n\n## Validation Expectations\n\nWhen you change SMB change-notification behavior, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects browser-visible refresh behavior, add the relevant frontend checks as well.\n", "0.9": "+++\ntitle = \"SMB Change Notification and Directory Freshness\"\n+++\n\nSambee uses SMB2/SMB3 `CHANGE_NOTIFY` support to keep directory state fresh without falling back to naive polling.\n\nThat capability is used in two different backend paths:\n\n- `backend/app/services/directory_monitor.py` for browser-visible WebSocket refresh notifications\n- `backend/app/services/directory_cache.py` for per-connection directory-cache freshness\n\nUse this page when a backend change affects WebSocket directory updates, SMB watcher lifecycle, or how the product maintains fresh directory state over time.\n\n## Why This Matters\n\nDirectory freshness is a cross-boundary product contract.\n\nUsers expect Sambee to react when:\n\n- another SMB client creates, deletes, renames, or edits content in the current directory\n- the current browser view should refresh because the underlying SMB directory changed\n- cached directory-search data should stay reasonably current without rescanning the entire tree on every request\n\nThat is why the backend owns change-notification behavior instead of leaving refresh decisions entirely to the browser.\n\n## The Two Change-Notification Paths\n\nSambee does not have a single watcher for all purposes.\n\n### Browser Notification Path\n\n`directory_monitor.py` is responsible for directory-specific monitoring tied to active WebSocket subscriptions.\n\nIts job is to:\n\n- start watching a directory when the first browser subscriber appears\n- share one SMB monitor across multiple subscribers for the same watched path\n- stop monitoring when the last subscriber leaves\n- send `directory_changed` messages back through the WebSocket layer\n\nThis is the path that keeps an open file browser view fresh.\n\n### Directory-Cache Freshness Path\n\n`directory_cache.py` uses its own `CHANGE_NOTIFY` watcher for a different reason.\n\nIts job is to:\n\n- watch the share root or effective path prefix for directory-name changes\n- keep the in-memory directory cache aligned with adds, removes, and renames\n- combine event-driven updates with periodic full rescans as a safety net\n- preserve fast directory-search behavior without rebuilding the entire cache on every navigation event\n\nThis is not the same as the browser WebSocket monitor, even though both rely on SMB `CHANGE_NOTIFY`.\n\n## Browser Notification Flow\n\nAt a high level, the browser-facing flow is:\n\n1. the browser opens the backend WebSocket endpoint\n2. it sends a subscription message for a connection and directory path\n3. `ConnectionManager` resolves access, applies any `path_prefix`, and starts monitoring if this is the first subscriber\n4. `DirectoryMonitor` opens SMB resources for that resolved directory and starts a background watcher thread\n5. when the SMB server reports a change, the backend emits `directory_changed` to all subscribers for the user-facing path\n6. when the last subscriber leaves, the monitor stops and releases its SMB resources\n\nRepresentative client messages include:\n\n- subscribe: `{ \"action\": \"subscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- unsubscribe: `{ \"action\": \"unsubscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- server notification: `{ \"type\": \"directory_changed\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n\n## Path Resolution and Subscription Keys\n\nOne subtle but important part of the design is that browser subscriptions and SMB watches do not always use the same path string.\n\nThe WebSocket layer keys subscriptions by the user-facing path.\n\nIf the SMB connection has a `path_prefix`, the backend resolves the actual watched SMB path by combining:\n\n- the normalized connection prefix\n- the user-facing relative path\n\nThat resolved SMB path is what `DirectoryMonitor` actually watches.\n\nThe callback then maps notifications back to the user-facing path before sending `directory_changed` over the WebSocket.\n\nIf you remove that mapping, subscriptions stop lining up with the paths the browser thinks it subscribed to.\n\n## Main Components\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/api/websocket.py` | WebSocket endpoint, subscription bookkeeping, access checks, path-prefix resolution, and delivery of `directory_changed` events |\n| `backend/app/services/directory_monitor.py` | per-directory SMB watchers for active browser subscriptions |\n| `backend/app/services/directory_cache.py` | per-connection directory cache plus root-level `CHANGE_NOTIFY` watcher for cache freshness |\n| `backend/app/main.py` | application shutdown hooks for directory caches and directory monitors |\n\n## Directory Monitor Lifecycle\n\nThe browser-facing monitor is reference-counted by subscription demand.\n\n`DirectoryMonitor` keeps one `MonitoredDirectory` per `connection_id:path` key and tracks subscriber counts.\n\nThat means:\n\n- the first subscriber starts the monitor\n- later subscribers reuse the same watched directory instance\n- unsubscribing decrements the count\n- the monitor only stops when the count reaches zero\n\nThis avoids opening duplicate SMB watcher handles for the same directory just because multiple browser clients are watching it.\n\n## SMB Resource Management\n\n`MonitoredDirectory` owns low-level SMB resources directly.\n\nCreation follows this order:\n\n1. connection\n2. session\n3. tree connect\n4. directory open handle\n5. `FileSystemWatcher`\n\nCleanup happens in reverse order so partial failure does not leak handles.\n\nThat ordering is important because change-notification bugs are often really handle-lifecycle bugs.\n\n## Watched Events\n\nThe browser-facing monitor currently watches for:\n\n- file-name changes\n- directory-name changes\n- size changes\n- last-write changes\n\nIt uses tree watching so changes in subdirectories can also surface through the same watch.\n\nThe directory-cache watcher is narrower by design.\n\nIt watches directory-name changes across the tree because the cache only needs enough signal to update its directory index efficiently.\n\n## Recovery and Failure Handling\n\nThe directory monitor treats connection failures as part of normal long-lived operation, not as impossible edge cases.\n\nCurrent behavior includes:\n\n- exponential backoff for reconnect attempts\n- retry jitter to avoid synchronized reconnect storms\n- capped retry attempts before giving up\n- explicit detection of connection, socket, and timeout failures\n- stop-on-delete behavior when the watched directory itself is deleted\n\nThe cache watcher has its own retry loop and also tolerates `CHANGE_NOTIFY` buffer-overflow conditions by relying on later rescans to restore correctness.\n\nThat distinction matters: browser notification is path-specific and subscriber-driven, while the cache watcher is connection-scoped and consistency-oriented.\n\n## Shutdown Behavior\n\nSambee shuts these systems down explicitly.\n\nDuring application shutdown:\n\n- directory caches are stopped through `shutdown_directory_cache()`\n- directory monitors are stopped through `shutdown_monitor()`\n\nThat explicit shutdown path exists to release watcher threads and SMB handles cleanly instead of depending on interpreter teardown.\n\n## Performance Characteristics\n\nThe design tries to keep freshness inexpensive without resorting to constant polling.\n\n- SMB `CHANGE_NOTIFY` is event-driven rather than poll-based\n- multiple browser subscribers share one monitor for the same watched path\n- directory-cache updates avoid full rescans for every single directory rename or add event\n- periodic rescans remain in place as a correctness safety net, not the primary freshness mechanism\n\n## Limits and Tradeoffs\n\nContributors need to preserve a few constraints here.\n\n- this requires SMB2 or later\n- some notifications can still be missed during network instability, which is why manual refresh and periodic cache rescans still matter\n- the browser-facing path is optimized for telling clients to refresh, not for transmitting rich per-file diffs\n- cache freshness and browser freshness are related concerns, but they are not the same subsystem and should not be collapsed casually\n\n## Common Failure Modes\n\n- path-prefix resolution is ignored, so the monitor watches the wrong SMB directory\n- subscriber bookkeeping drifts, so monitors are leaked or stopped too early\n- WebSocket disconnect cleanup forgets to release the last subscriber's monitor\n- a recovery change handles one timeout path but leaks SMB resources on reconnect\n- buffer-overflow or rename-edge handling is simplified in ways that quietly degrade cache correctness\n\n## Where to Continue\n\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the changed behavior interacts with uploads, moves, renames, or companion-assisted editing.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider backend or browser validation.\n\n## Validation Expectations\n\nWhen you change SMB change-notification behavior, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects browser-visible refresh behavior, add the relevant frontend checks as well.\n", "1.0": "+++\ntitle = \"SMB Change Notification and Directory Freshness\"\n+++\n\nSambee uses SMB2/SMB3 `CHANGE_NOTIFY` support to keep directory state fresh without falling back to naive polling.\n\nThat capability is used in two different backend paths:\n\n- `backend/app/services/directory_monitor.py` for browser-visible WebSocket refresh notifications\n- `backend/app/services/directory_cache.py` for per-connection directory-cache freshness\n\nUse this page when a backend change affects WebSocket directory updates, SMB watcher lifecycle, or how the product maintains fresh directory state over time.\n\n## Why This Matters\n\nDirectory freshness is a cross-boundary product contract.\n\nUsers expect Sambee to react when:\n\n- another SMB client creates, deletes, renames, or edits content in the current directory\n- the current browser view should refresh because the underlying SMB directory changed\n- cached directory-search data should stay reasonably current without rescanning the entire tree on every request\n\nThat is why the backend owns change-notification behavior instead of leaving refresh decisions entirely to the browser.\n\n## The Two Change-Notification Paths\n\nSambee does not have a single watcher for all purposes.\n\n### Browser Notification Path\n\n`directory_monitor.py` is responsible for directory-specific monitoring tied to active WebSocket subscriptions.\n\nIts job is to:\n\n- start watching a directory when the first browser subscriber appears\n- share one SMB monitor across multiple subscribers for the same watched path\n- stop monitoring when the last subscriber leaves\n- send `directory_changed` messages back through the WebSocket layer\n\nThis is the path that keeps an open file browser view fresh.\n\n### Directory-Cache Freshness Path\n\n`directory_cache.py` uses its own `CHANGE_NOTIFY` watcher for a different reason.\n\nIts job is to:\n\n- watch the share root or effective path prefix for directory-name changes\n- keep the in-memory directory cache aligned with adds, removes, and renames\n- combine event-driven updates with periodic full rescans as a safety net\n- preserve fast directory-search behavior without rebuilding the entire cache on every navigation event\n\nThis is not the same as the browser WebSocket monitor, even though both rely on SMB `CHANGE_NOTIFY`.\n\n## Browser Notification Flow\n\nAt a high level, the browser-facing flow is:\n\n1. the browser opens the backend WebSocket endpoint\n2. it sends a subscription message for a connection and directory path\n3. `ConnectionManager` resolves access, applies any `path_prefix`, and starts monitoring if this is the first subscriber\n4. `DirectoryMonitor` opens SMB resources for that resolved directory and starts a background watcher thread\n5. when the SMB server reports a change, the backend emits `directory_changed` to all subscribers for the user-facing path\n6. when the last subscriber leaves, the monitor stops and releases its SMB resources\n\nRepresentative client messages include:\n\n- subscribe: `{ \"action\": \"subscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- unsubscribe: `{ \"action\": \"unsubscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- server notification: `{ \"type\": \"directory_changed\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n\n## Path Resolution and Subscription Keys\n\nOne subtle but important part of the design is that browser subscriptions and SMB watches do not always use the same path string.\n\nThe WebSocket layer keys subscriptions by the user-facing path.\n\nIf the SMB connection has a `path_prefix`, the backend resolves the actual watched SMB path by combining:\n\n- the normalized connection prefix\n- the user-facing relative path\n\nThat resolved SMB path is what `DirectoryMonitor` actually watches.\n\nThe callback then maps notifications back to the user-facing path before sending `directory_changed` over the WebSocket.\n\nIf you remove that mapping, subscriptions stop lining up with the paths the browser thinks it subscribed to.\n\n## Main Components\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/api/websocket.py` | WebSocket endpoint, subscription bookkeeping, access checks, path-prefix resolution, and delivery of `directory_changed` events |\n| `backend/app/services/directory_monitor.py` | per-directory SMB watchers for active browser subscriptions |\n| `backend/app/services/directory_cache.py` | per-connection directory cache plus root-level `CHANGE_NOTIFY` watcher for cache freshness |\n| `backend/app/main.py` | application shutdown hooks for directory caches and directory monitors |\n\n## Directory Monitor Lifecycle\n\nThe browser-facing monitor is reference-counted by subscription demand.\n\n`DirectoryMonitor` keeps one `MonitoredDirectory` per `connection_id:path` key and tracks subscriber counts.\n\nThat means:\n\n- the first subscriber starts the monitor\n- later subscribers reuse the same watched directory instance\n- unsubscribing decrements the count\n- the monitor only stops when the count reaches zero\n\nThis avoids opening duplicate SMB watcher handles for the same directory just because multiple browser clients are watching it.\n\n## SMB Resource Management\n\n`MonitoredDirectory` owns low-level SMB resources directly.\n\nCreation follows this order:\n\n1. connection\n2. session\n3. tree connect\n4. directory open handle\n5. `FileSystemWatcher`\n\nCleanup happens in reverse order so partial failure does not leak handles.\n\nThat ordering is important because change-notification bugs are often really handle-lifecycle bugs.\n\n## Watched Events\n\nThe browser-facing monitor currently watches for:\n\n- file-name changes\n- directory-name changes\n- size changes\n- last-write changes\n\nIt uses tree watching so changes in subdirectories can also surface through the same watch.\n\nThe directory-cache watcher is narrower by design.\n\nIt watches directory-name changes across the tree because the cache only needs enough signal to update its directory index efficiently.\n\n## Recovery and Failure Handling\n\nThe directory monitor treats connection failures as part of normal long-lived operation, not as impossible edge cases.\n\nCurrent behavior includes:\n\n- exponential backoff for reconnect attempts\n- retry jitter to avoid synchronized reconnect storms\n- capped retry attempts before giving up\n- explicit detection of connection, socket, and timeout failures\n- stop-on-delete behavior when the watched directory itself is deleted\n\nThe cache watcher has its own retry loop and also tolerates `CHANGE_NOTIFY` buffer-overflow conditions by relying on later rescans to restore correctness.\n\nThat distinction matters: browser notification is path-specific and subscriber-driven, while the cache watcher is connection-scoped and consistency-oriented.\n\n## Shutdown Behavior\n\nSambee shuts these systems down explicitly.\n\nDuring application shutdown:\n\n- directory caches are stopped through `shutdown_directory_cache()`\n- directory monitors are stopped through `shutdown_monitor()`\n\nThat explicit shutdown path exists to release watcher threads and SMB handles cleanly instead of depending on interpreter teardown.\n\n## Performance Characteristics\n\nThe design tries to keep freshness inexpensive without resorting to constant polling.\n\n- SMB `CHANGE_NOTIFY` is event-driven rather than poll-based\n- multiple browser subscribers share one monitor for the same watched path\n- directory-cache updates avoid full rescans for every single directory rename or add event\n- periodic rescans remain in place as a correctness safety net, not the primary freshness mechanism\n\n## Limits and Tradeoffs\n\nContributors need to preserve a few constraints here.\n\n- this requires SMB2 or later\n- some notifications can still be missed during network instability, which is why manual refresh and periodic cache rescans still matter\n- the browser-facing path is optimized for telling clients to refresh, not for transmitting rich per-file diffs\n- cache freshness and browser freshness are related concerns, but they are not the same subsystem and should not be collapsed casually\n\n## Common Failure Modes\n\n- path-prefix resolution is ignored, so the monitor watches the wrong SMB directory\n- subscriber bookkeeping drifts, so monitors are leaked or stopped too early\n- WebSocket disconnect cleanup forgets to release the last subscriber's monitor\n- a recovery change handles one timeout path but leaks SMB resources on reconnect\n- buffer-overflow or rename-edge handling is simplified in ways that quietly degrade cache correctness\n\n## Where to Continue\n\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the changed behavior interacts with uploads, moves, renames, or companion-assisted editing.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider backend or browser validation.\n\n## Validation Expectations\n\nWhen you change SMB change-notification behavior, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects browser-visible refresh behavior, add the relevant frontend checks as well.\n", "2.0": "+++\ntitle = \"SMB Change Notification and Directory Freshness\"\n+++\n\nSambee uses SMB2/SMB3 `CHANGE_NOTIFY` support to keep directory state fresh without falling back to naive polling.\n\nThat capability is used in two different backend paths:\n\n- `backend/app/services/directory_monitor.py` for browser-visible WebSocket refresh notifications\n- `backend/app/services/directory_cache.py` for per-connection directory-cache freshness\n\nUse this page when a backend change affects WebSocket directory updates, SMB watcher lifecycle, or how the product maintains fresh directory state over time.\n\n## Why This Matters\n\nDirectory freshness is a cross-boundary product contract.\n\nUsers expect Sambee to react when:\n\n- another SMB client creates, deletes, renames, or edits content in the current directory\n- the current browser view should refresh because the underlying SMB directory changed\n- cached directory-search data should stay reasonably current without rescanning the entire tree on every request\n\nThat is why the backend owns change-notification behavior instead of leaving refresh decisions entirely to the browser.\n\n## The Two Change-Notification Paths\n\nSambee does not have a single watcher for all purposes.\n\n### Browser Notification Path\n\n`directory_monitor.py` is responsible for directory-specific monitoring tied to active WebSocket subscriptions.\n\nIts job is to:\n\n- start watching a directory when the first browser subscriber appears\n- share one SMB monitor across multiple subscribers for the same watched path\n- stop monitoring when the last subscriber leaves\n- send `directory_changed` messages back through the WebSocket layer\n\nThis is the path that keeps an open file browser view fresh.\n\n### Directory-Cache Freshness Path\n\n`directory_cache.py` uses its own `CHANGE_NOTIFY` watcher for a different reason.\n\nIts job is to:\n\n- watch the share root or effective path prefix for directory-name changes\n- keep the in-memory directory cache aligned with adds, removes, and renames\n- combine event-driven updates with periodic full rescans as a safety net\n- preserve fast directory-search behavior without rebuilding the entire cache on every navigation event\n\nThis is not the same as the browser WebSocket monitor, even though both rely on SMB `CHANGE_NOTIFY`.\n\n## Browser Notification Flow\n\nAt a high level, the browser-facing flow is:\n\n1. the browser opens the backend WebSocket endpoint\n2. it sends a subscription message for a connection and directory path\n3. `ConnectionManager` resolves access, applies any `path_prefix`, and starts monitoring if this is the first subscriber\n4. `DirectoryMonitor` opens SMB resources for that resolved directory and starts a background watcher thread\n5. when the SMB server reports a change, the backend emits `directory_changed` to all subscribers for the user-facing path\n6. when the last subscriber leaves, the monitor stops and releases its SMB resources\n\nRepresentative client messages include:\n\n- subscribe: `{ \"action\": \"subscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- unsubscribe: `{ \"action\": \"unsubscribe\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n- server notification: `{ \"type\": \"directory_changed\", \"connection_id\": \"uuid\", \"path\": \"/dir\" }`\n\n## Path Resolution and Subscription Keys\n\nOne subtle but important part of the design is that browser subscriptions and SMB watches do not always use the same path string.\n\nThe WebSocket layer keys subscriptions by the user-facing path.\n\nIf the SMB connection has a `path_prefix`, the backend resolves the actual watched SMB path by combining:\n\n- the normalized connection prefix\n- the user-facing relative path\n\nThat resolved SMB path is what `DirectoryMonitor` actually watches.\n\nThe callback then maps notifications back to the user-facing path before sending `directory_changed` over the WebSocket.\n\nIf you remove that mapping, subscriptions stop lining up with the paths the browser thinks it subscribed to.\n\n## Main Components\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/api/websocket.py` | WebSocket endpoint, subscription bookkeeping, access checks, path-prefix resolution, and delivery of `directory_changed` events |\n| `backend/app/services/directory_monitor.py` | per-directory SMB watchers for active browser subscriptions |\n| `backend/app/services/directory_cache.py` | per-connection directory cache plus root-level `CHANGE_NOTIFY` watcher for cache freshness |\n| `backend/app/main.py` | application shutdown hooks for directory caches and directory monitors |\n\n## Directory Monitor Lifecycle\n\nThe browser-facing monitor is reference-counted by subscription demand.\n\n`DirectoryMonitor` keeps one `MonitoredDirectory` per `connection_id:path` key and tracks subscriber counts.\n\nThat means:\n\n- the first subscriber starts the monitor\n- later subscribers reuse the same watched directory instance\n- unsubscribing decrements the count\n- the monitor only stops when the count reaches zero\n\nThis avoids opening duplicate SMB watcher handles for the same directory just because multiple browser clients are watching it.\n\n## SMB Resource Management\n\n`MonitoredDirectory` owns low-level SMB resources directly.\n\nCreation follows this order:\n\n1. connection\n2. session\n3. tree connect\n4. directory open handle\n5. `FileSystemWatcher`\n\nCleanup happens in reverse order so partial failure does not leak handles.\n\nThat ordering is important because change-notification bugs are often really handle-lifecycle bugs.\n\n## Watched Events\n\nThe browser-facing monitor currently watches for:\n\n- file-name changes\n- directory-name changes\n- size changes\n- last-write changes\n\nThe browser-facing monitor watches only immediate children of the subscribed directory. Writes deeper in the tree, such as installing packages in a project's `node_modules` folder, don't invalidate an ancestor's file list. If the SMB server reports a metadata change for an immediate child directory, that change can still trigger a refresh.\n\nThe directory-cache watcher is narrower by design.\n\nIt watches directory-name changes across the tree because the cache only needs enough signal to update its directory index efficiently.\n\n## Directory-Index Consistency\n\nA full rescan builds a replacement index while the current index continues to serve directory searches. If any directory read fails or times out, the replacement isn't published or persisted. The existing index remains available, and the scan error is recorded for diagnosis. A later successful rescan can replace it.\n\nWhile a rescan is running, directory additions, removals, and renames update the live index and are also recorded in order. Under the cache lock, Sambee checks pending operations before and after each directory read and before publication. Additions are safe to merge. Removals and renames can only be merged when they don't overlap a read that's already started.\n\nIf a removal or rename changes a directory that's already been read, one being read, an ancestor of either, or an immediate child's name, the replacement is ambiguous. Notifications can arrive after a read already reflects the change, so replaying them could rename or remove fresh paths a second time. Sambee discards the replacement rather than publishing or persisting it; the live index, including its recent changes, remains available. Only one rescan can run at a time, and cancellation discards pending reconciliation without discarding live updates.\n\nDirectory junctions, symbolic links, and unrecognized directory reparse points are indexed as destinations, but scans don't descend into their targets. This prevents ancestor links from causing repeated traversal. DFS referrals are identified by their reparse tag and remain traversable through the SMB client's referral support, so directories below DFS links stay searchable.\n\n### Persisted Snapshots\n\nVersion 2 snapshots are bound to the connection's host, port, share, normalized path prefix, username, and connection revision. The revision changes when the connection is edited, including credential changes. Passwords aren't stored in snapshot metadata.\n\nA snapshot with a different source identity is ignored, including when trying the backup file. Older version 1 snapshots are also ignored, so existing installations rebuild the directory index once after upgrading. Matching snapshots still provide immediate search results while background verification checks freshness.\n\nStartup verification and the periodic rescan loop have separate tracked tasks. Removing a cache or shutting down the application cancels both tasks, along with initial scanning and snapshot flushing.\n\n## Recovery and Failure Handling\n\nThe directory monitor treats connection failures as part of normal long-lived operation, not as impossible edge cases.\n\nCurrent behavior includes:\n\n- exponential backoff for reconnect attempts\n- retry jitter to avoid synchronized reconnect storms\n- capped retry attempts before giving up\n- explicit detection of connection, socket, and timeout failures\n- stop-on-delete behavior when the watched directory itself is deleted\n\nThe cache watcher has its own retry loop and also tolerates `CHANGE_NOTIFY` buffer-overflow conditions by relying on later rescans to restore correctness.\n\nThat distinction matters: browser notification is path-specific and subscriber-driven, while the cache watcher is connection-scoped and consistency-oriented.\n\n## Shutdown Behavior\n\nSambee shuts these systems down explicitly.\n\nDuring application shutdown:\n\n- directory caches are stopped through `shutdown_directory_cache()`\n- directory monitors are stopped through `shutdown_monitor()`\n\nThat explicit shutdown path exists to release watcher threads and SMB handles cleanly instead of depending on interpreter teardown.\n\n## Performance Characteristics\n\nThe design tries to keep freshness inexpensive without resorting to constant polling.\n\n- SMB `CHANGE_NOTIFY` is event-driven rather than poll-based\n- multiple browser subscribers share one monitor for the same watched path\n- browser-facing monitors don't request recursive subtree notifications\n- each browser pane keeps loaded physical-directory rows visible during automatic refreshes, including a previously loaded empty listing\n- automatic refreshes wait for an active listing request and combine newer notifications into one pending refresh, starting at most once per second\n- navigation and pane disposal cancel queued refreshes\n- directory-cache updates avoid full rescans for every single directory rename or add event\n- periodic rescans remain in place as a correctness safety net, not the primary freshness mechanism\n\n## Limits and Tradeoffs\n\nContributors need to preserve a few constraints here.\n\n- this requires SMB2 or later\n- some notifications can still be missed during network instability, which is why manual refresh and periodic cache rescans still matter\n- the browser-facing path is optimized for telling clients to refresh, not for transmitting rich per-file diffs\n- cache freshness and browser freshness are related concerns, but they are not the same subsystem and should not be collapsed casually\n\n## Common Failure Modes\n\n- path-prefix resolution is ignored, so the monitor watches the wrong SMB directory\n- subscriber bookkeeping drifts, so monitors are leaked or stopped too early\n- WebSocket disconnect cleanup forgets to release the last subscriber's monitor\n- a recovery change handles one timeout path but leaks SMB resources on reconnect\n- buffer-overflow or rename-edge handling is simplified in ways that quietly degrade cache correctness\n\n## Where to Continue\n\n- Use [Request Flow and Service Boundaries](../request-flow-and-service-boundaries/) for the broader backend layering model.\n- Use [File Operations and Edit Locking](../file-operations-and-edit-locking/) when the changed behavior interacts with uploads, moves, renames, or companion-assisted editing.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when the change requires wider backend or browser validation.\n\n## Validation Expectations\n\nWhen you change SMB change-notification behavior, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\n```\n\nIf the change affects browser-visible refresh behavior, add the relevant frontend checks as well.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/backend-architecture/file-operations-and-edit-locking", "parent_id": "section:developer-guide/backend-architecture", "depth": 2, "kind": "page", "label": "file-operations-and-edit-locking", "title": "File Operations And Edit Locking", "path": "developer-guide/backend-architecture/file-operations-and-edit-locking", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"File Operations and Edit Locking\"\n+++\n\nNot every file operation in Sambee follows the same lifecycle.\n\n## Two Different Operation Families\n\n### Ordinary File Operations\n\nThese are the browser-facing operations such as:\n\n- browse and inspect\n- create and rename\n- copy and move\n- upload and download\n- delete\n\nThese requests usually enter through the browser-facing API and are executed through the backend storage layer.\n\n### Companion-Assisted SMB Editing\n\nThis is the higher-risk path used when a user opens an SMB-backed file in a native desktop app.\n\nThat flow adds:\n\n- token exchange\n- file download to a temp location\n- backend-managed edit locking\n- lock heartbeat and lock-status checks\n- upload or discard decision at the end of editing\n- conflict handling before the server copy is replaced\n\n## Ordinary File Operations\n\nThe browser file-management path depends on typed request models and clear storage semantics.\n\n- copy and move requests use structured request data instead of ad hoc parameters\n- same-path or invalid operations are rejected explicitly\n- server-side copy and move semantics depend on the backend's storage capabilities\n- conflict responses and validation errors are part of the user-visible contract\n\nThe backend should stay authoritative here, even when the frontend tries to make the operation feel immediate.\n\n## Why Edit Locking Exists\n\nNative-app editing of SMB-backed files is a coordination problem, not just a download-and-upload shortcut.\n\nThe backend owns the server-facing lock lifecycle so that:\n\n- concurrent edits are visible and controllable\n- the companion can refresh the lock while editing is still in progress\n- stale or interrupted sessions can be detected\n- conflict decisions happen against the real server state\n\n## High-Level Companion Edit Lifecycle\n\nFor the SMB-backed desktop editing path:\n\n1. the companion exchanges the deep-link token for an authenticated session\n2. it fetches file metadata and downloads the file\n3. it acquires the edit lock from the backend\n4. it keeps the lock alive with heartbeat traffic while the file is open\n5. it uploads the changed file or discards it\n6. it releases the lock and closes out the operation\n\nThe backend is the source of truth for lock state even though the companion is the actor performing the desktop-side work.\n\n## Conflict Handling\n\nBefore a modified file is written back, the system compares the expected server state with the current one.\n\nIf the server copy changed while the user was editing, the companion should not silently overwrite it. That is why conflict handling is part of the backend contract rather than just a local desktop decision.\n\n## Important Distinction: Local Drives\n\nLocal-drive workflows do not use this backend edit-lock lifecycle.\n\n- local files are handled through the paired localhost companion API\n- direct local open can avoid download, lock, upload, and \"Done Editing\" entirely\n- SMB-backed native-app editing still depends on backend lock and upload semantics\n\nDo not blur those two paths when changing edit behavior.\n\n## Adjacent Concern: Freshness after Operations\n\nAfter file operations complete, the browser still needs fresh directory state. That is where change notification and WebSocket refresh behavior become relevant.\n\nOrdinary CRUD operations and companion-assisted edit completion both depend on the rest of the system noticing that directory state has changed.\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npm test\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nChoose the exact subset based on whether the change affects ordinary browser file management, companion editing, or both.\n", "0.8": "+++\ntitle = \"File Operations and Edit Locking\"\n+++\n\nNot every file operation in Sambee follows the same lifecycle.\n\n## Two Different Operation Families\n\n### Ordinary File Operations\n\nThese are the browser-facing operations such as:\n\n- browse and inspect\n- create and rename\n- copy and move\n- upload and download\n- delete\n\nThese requests usually enter through the browser-facing API and are executed through the backend storage layer.\n\n### Companion-Assisted SMB Editing\n\nThis is the higher-risk path used when a user opens an SMB-backed file in a native desktop app.\n\nThat flow adds:\n\n- token exchange\n- file download to a temp location\n- backend-managed edit locking\n- lock heartbeat and lock-status checks\n- upload or discard decision at the end of editing\n- conflict handling before the server copy is replaced\n\n## Ordinary File Operations\n\nThe browser file-management path depends on typed request models and clear storage semantics.\n\n- copy and move requests use structured request data instead of ad hoc parameters\n- same-path or invalid operations are rejected explicitly\n- server-side copy and move semantics depend on the backend's storage capabilities\n- conflict responses and validation errors are part of the user-visible contract\n\nThe backend should stay authoritative here, even when the frontend tries to make the operation feel immediate.\n\n## Why Edit Locking Exists\n\nNative-app editing of SMB-backed files is a coordination problem, not just a download-and-upload shortcut.\n\nThe backend owns the server-facing lock lifecycle so that:\n\n- concurrent edits are visible and controllable\n- the companion can refresh the lock while editing is still in progress\n- stale or interrupted sessions can be detected\n- conflict decisions happen against the real server state\n\n## High-Level Companion Edit Lifecycle\n\nFor the SMB-backed desktop editing path:\n\n1. the companion exchanges the deep-link token for an authenticated session\n2. it fetches file metadata and downloads the file\n3. it acquires the edit lock from the backend\n4. it keeps the lock alive with heartbeat traffic while the file is open\n5. it uploads the changed file or discards it\n6. it releases the lock and closes out the operation\n\nThe backend is the source of truth for lock state even though the companion is the actor performing the desktop-side work.\n\n## Conflict Handling\n\nBefore a modified file is written back, the system compares the expected server state with the current one.\n\nIf the server copy changed while the user was editing, the companion should not silently overwrite it. That is why conflict handling is part of the backend contract rather than just a local desktop decision.\n\n## Important Distinction: Local Drives\n\nLocal-drive workflows do not use this backend edit-lock lifecycle.\n\n- local files are handled through the paired localhost companion API\n- direct local open can avoid download, lock, upload, and \"Done Editing\" entirely\n- SMB-backed native-app editing still depends on backend lock and upload semantics\n\nDo not blur those two paths when changing edit behavior.\n\n## Adjacent Concern: Freshness after Operations\n\nAfter file operations complete, the browser still needs fresh directory state. That is where change notification and WebSocket refresh behavior become relevant.\n\nOrdinary CRUD operations and companion-assisted edit completion both depend on the rest of the system noticing that directory state has changed.\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npm test\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nChoose the exact subset based on whether the change affects ordinary browser file management, companion editing, or both.\n", "0.9": "+++\ntitle = \"File Operations and Edit Locking\"\n+++\n\nNot every file operation in Sambee follows the same lifecycle.\n\n## Two Different Operation Families\n\n### Ordinary File Operations\n\nThese are the browser-facing operations such as:\n\n- browse and inspect\n- create and rename\n- copy and move\n- upload and download\n- delete\n\nThese requests usually enter through the browser-facing API and are executed through the backend storage layer.\n\n### Companion-Assisted SMB Editing\n\nThis is the higher-risk path used when a user opens an SMB-backed file in a native desktop app.\n\nThat flow adds:\n\n- token exchange\n- file download to a temp location\n- backend-managed edit locking\n- lock heartbeat and lock-status checks\n- upload or discard decision at the end of editing\n- conflict handling before the server copy is replaced\n\n## Ordinary File Operations\n\nThe browser file-management path depends on typed request models and clear storage semantics.\n\n- copy and move requests use structured request data instead of ad hoc parameters\n- same-path or invalid operations are rejected explicitly\n- server-side copy and move semantics depend on the backend's storage capabilities\n- conflict responses and validation errors are part of the user-visible contract\n\nThe backend should stay authoritative here, even when the frontend tries to make the operation feel immediate.\n\n## Why Edit Locking Exists\n\nNative-app editing of SMB-backed files is a coordination problem, not just a download-and-upload shortcut.\n\nThe backend owns the server-facing lock lifecycle so that:\n\n- concurrent edits are visible and controllable\n- the companion can refresh the lock while editing is still in progress\n- stale or interrupted sessions can be detected\n- conflict decisions happen against the real server state\n\n## High-Level Companion Edit Lifecycle\n\nFor the SMB-backed desktop editing path:\n\n1. the companion exchanges the deep-link token for an authenticated session\n2. it fetches file metadata and downloads the file\n3. it acquires the edit lock from the backend\n4. it keeps the lock alive with heartbeat traffic while the file is open\n5. it uploads the changed file or discards it\n6. it releases the lock and closes out the operation\n\nThe backend is the source of truth for lock state even though the companion is the actor performing the desktop-side work.\n\n## Conflict Handling\n\nBefore a modified file is written back, the system compares the expected server state with the current one.\n\nIf the server copy changed while the user was editing, the companion should not silently overwrite it. That is why conflict handling is part of the backend contract rather than just a local desktop decision.\n\n## Important Distinction: Local Drives\n\nLocal-drive workflows do not use this backend edit-lock lifecycle.\n\n- local files are handled through the paired localhost companion API\n- direct local open can avoid download, lock, upload, and \"Done Editing\" entirely\n- SMB-backed native-app editing still depends on backend lock and upload semantics\n\nDo not blur those two paths when changing edit behavior.\n\n## Adjacent Concern: Freshness after Operations\n\nAfter file operations complete, the browser still needs fresh directory state. That is where change notification and WebSocket refresh behavior become relevant.\n\nOrdinary CRUD operations and companion-assisted edit completion both depend on the rest of the system noticing that directory state has changed.\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npm test\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nChoose the exact subset based on whether the change affects ordinary browser file management, companion editing, or both.\n", "1.0": "+++\ntitle = \"File Operations and Edit Locking\"\n+++\n\nNot every file operation in Sambee follows the same lifecycle.\n\n## Two Different Operation Families\n\n### Ordinary File Operations\n\nThese are the browser-facing operations such as:\n\n- browse and inspect\n- create and rename\n- copy and move\n- upload and download\n- delete\n\nThese requests usually enter through the browser-facing API and are executed through the backend storage layer.\n\n### Companion-Assisted SMB Editing\n\nThis is the higher-risk path used when a user opens an SMB-backed file in a native desktop app.\n\nThat flow adds:\n\n- token exchange\n- file download to a temp location\n- backend-managed edit locking\n- lock heartbeat and lock-status checks\n- upload or discard decision at the end of editing\n- conflict handling before the server copy is replaced\n\n## Ordinary File Operations\n\nThe browser file-management path depends on typed request models and clear storage semantics.\n\n- copy and move requests use structured request data instead of ad hoc parameters\n- same-path or invalid operations are rejected explicitly\n- server-side copy and move semantics depend on the backend's storage capabilities\n- conflict responses and validation errors are part of the user-visible contract\n\nThe backend should stay authoritative here, even when the frontend tries to make the operation feel immediate.\n\n## Why Edit Locking Exists\n\nNative-app editing of SMB-backed files is a coordination problem, not just a download-and-upload shortcut.\n\nThe backend owns the server-facing lock lifecycle so that:\n\n- concurrent edits are visible and controllable\n- the companion can refresh the lock while editing is still in progress\n- stale or interrupted sessions can be detected\n- conflict decisions happen against the real server state\n\n## High-Level Companion Edit Lifecycle\n\nFor the SMB-backed desktop editing path:\n\n1. the companion exchanges the deep-link token for an authenticated session\n2. it fetches file metadata and downloads the file\n3. it acquires the edit lock from the backend\n4. it keeps the lock alive with heartbeat traffic while the file is open\n5. it uploads the changed file or discards it\n6. it releases the lock and closes out the operation\n\nThe backend is the source of truth for lock state even though the companion is the actor performing the desktop-side work.\n\n## Conflict Handling\n\nBefore a modified file is written back, the system compares the expected server state with the current one.\n\nIf the server copy changed while the user was editing, the companion should not silently overwrite it. That is why conflict handling is part of the backend contract rather than just a local desktop decision.\n\n## Important Distinction: Local Drives\n\nLocal-drive workflows do not use this backend edit-lock lifecycle.\n\n- local files are handled through the paired localhost companion API\n- direct local open can avoid download, lock, upload, and \"Done Editing\" entirely\n- SMB-backed native-app editing still depends on backend lock and upload semantics\n\nDo not blur those two paths when changing edit behavior.\n\n## Adjacent Concern: Freshness after Operations\n\nAfter file operations complete, the browser still needs fresh directory state. That is where change notification and WebSocket refresh behavior become relevant.\n\nOrdinary CRUD operations and companion-assisted edit completion both depend on the rest of the system noticing that directory state has changed.\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npm test\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nChoose the exact subset based on whether the change affects ordinary browser file management, companion editing, or both.\n", "2.0": "+++\ntitle = \"File Operations and Edit Locking\"\n+++\n\nNot every file operation in Sambee follows the same lifecycle.\n\n## Two Different Operation Families\n\n### Ordinary File Operations\n\nThese are the browser-facing operations such as:\n\n- browse and inspect\n- create and rename\n- copy and move\n- upload and download\n- delete\n\nThese requests usually enter through the browser-facing API and are executed through the backend storage layer.\n\n### Companion-Assisted SMB Editing\n\nThis is the higher-risk path used when a user opens an SMB-backed file in a native desktop app.\n\nThat flow adds:\n\n- token exchange\n- file download to a temp location\n- backend-managed edit locking\n- lock heartbeat and lock-status checks\n- upload or discard decision at the end of editing\n- conflict handling before the server copy is replaced\n\n## Ordinary File Operations\n\nThe browser file-management path depends on typed request models and clear storage semantics.\n\n- copy and move requests use structured request data instead of ad hoc parameters\n- same-path or invalid operations are rejected explicitly\n- server-side copy and move semantics depend on the backend's storage capabilities\n- conflict responses and validation errors are part of the user-visible contract\n\nThe backend should stay authoritative here, even when the frontend tries to make the operation feel immediate.\n\n## Why Edit Locking Exists\n\nNative-app editing of SMB-backed files is a coordination problem, not just a download-and-upload shortcut.\n\nThe backend owns the server-facing lock lifecycle so that:\n\n- concurrent edits are visible and controllable\n- the companion can refresh the lock while editing is still in progress\n- stale or interrupted sessions can be detected\n- conflict decisions happen against the real server state\n\n## High-Level Companion Edit Lifecycle\n\nFor the SMB-backed desktop editing path:\n\n1. the companion exchanges the deep-link token for an authenticated session\n2. it fetches file metadata and downloads the file\n3. it acquires the edit lock from the backend\n4. it keeps the lock alive with heartbeat traffic while the file is open\n5. it uploads the changed file or discards it\n6. it releases the lock and closes out the operation\n\nThe backend is the source of truth for lock state even though the companion is the actor performing the desktop-side work.\n\n## Conflict Handling\n\nBefore a modified file is written back, the system compares the expected server state with the current one.\n\nIf the server copy changed while the user was editing, the companion should not silently overwrite it. That is why conflict handling is part of the backend contract rather than just a local desktop decision.\n\n## Important Distinction: Local Drives\n\nLocal-drive workflows do not use this backend edit-lock lifecycle.\n\n- local files are handled through the paired localhost companion API\n- direct local open can avoid download, lock, upload, and \"Done Editing\" entirely\n- SMB-backed native-app editing still depends on backend lock and upload semantics\n\nDo not blur those two paths when changing edit behavior.\n\n## Adjacent Concern: Freshness after Operations\n\nAfter file operations complete, the browser still needs fresh directory state. That is where change notification and WebSocket refresh behavior become relevant.\n\nOrdinary CRUD operations and companion-assisted edit completion both depend on the rest of the system noticing that directory state has changed.\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npm test\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nChoose the exact subset based on whether the change affects ordinary browser file management, companion editing, or both.\n"}, "page_contents": {"0.7": "+++\ntitle = \"File Operations and Edit Locking\"\n+++\n\nNot every file operation in Sambee follows the same lifecycle.\n\n## Two Different Operation Families\n\n### Ordinary File Operations\n\nThese are the browser-facing operations such as:\n\n- browse and inspect\n- create and rename\n- copy and move\n- upload and download\n- delete\n\nThese requests usually enter through the browser-facing API and are executed through the backend storage layer.\n\n### Companion-Assisted SMB Editing\n\nThis is the higher-risk path used when a user opens an SMB-backed file in a native desktop app.\n\nThat flow adds:\n\n- token exchange\n- file download to a temp location\n- backend-managed edit locking\n- lock heartbeat and lock-status checks\n- upload or discard decision at the end of editing\n- conflict handling before the server copy is replaced\n\n## Ordinary File Operations\n\nThe browser file-management path depends on typed request models and clear storage semantics.\n\n- copy and move requests use structured request data instead of ad hoc parameters\n- same-path or invalid operations are rejected explicitly\n- server-side copy and move semantics depend on the backend's storage capabilities\n- conflict responses and validation errors are part of the user-visible contract\n\nThe backend should stay authoritative here, even when the frontend tries to make the operation feel immediate.\n\n## Why Edit Locking Exists\n\nNative-app editing of SMB-backed files is a coordination problem, not just a download-and-upload shortcut.\n\nThe backend owns the server-facing lock lifecycle so that:\n\n- concurrent edits are visible and controllable\n- the companion can refresh the lock while editing is still in progress\n- stale or interrupted sessions can be detected\n- conflict decisions happen against the real server state\n\n## High-Level Companion Edit Lifecycle\n\nFor the SMB-backed desktop editing path:\n\n1. the companion exchanges the deep-link token for an authenticated session\n2. it fetches file metadata and downloads the file\n3. it acquires the edit lock from the backend\n4. it keeps the lock alive with heartbeat traffic while the file is open\n5. it uploads the changed file or discards it\n6. it releases the lock and closes out the operation\n\nThe backend is the source of truth for lock state even though the companion is the actor performing the desktop-side work.\n\n## Conflict Handling\n\nBefore a modified file is written back, the system compares the expected server state with the current one.\n\nIf the server copy changed while the user was editing, the companion should not silently overwrite it. That is why conflict handling is part of the backend contract rather than just a local desktop decision.\n\n## Important Distinction: Local Drives\n\nLocal-drive workflows do not use this backend edit-lock lifecycle.\n\n- local files are handled through the paired localhost companion API\n- direct local open can avoid download, lock, upload, and \"Done Editing\" entirely\n- SMB-backed native-app editing still depends on backend lock and upload semantics\n\nDo not blur those two paths when changing edit behavior.\n\n## Adjacent Concern: Freshness after Operations\n\nAfter file operations complete, the browser still needs fresh directory state. That is where change notification and WebSocket refresh behavior become relevant.\n\nOrdinary CRUD operations and companion-assisted edit completion both depend on the rest of the system noticing that directory state has changed.\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npm test\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nChoose the exact subset based on whether the change affects ordinary browser file management, companion editing, or both.\n", "0.8": "+++\ntitle = \"File Operations and Edit Locking\"\n+++\n\nNot every file operation in Sambee follows the same lifecycle.\n\n## Two Different Operation Families\n\n### Ordinary File Operations\n\nThese are the browser-facing operations such as:\n\n- browse and inspect\n- create and rename\n- copy and move\n- upload and download\n- delete\n\nThese requests usually enter through the browser-facing API and are executed through the backend storage layer.\n\n### Companion-Assisted SMB Editing\n\nThis is the higher-risk path used when a user opens an SMB-backed file in a native desktop app.\n\nThat flow adds:\n\n- token exchange\n- file download to a temp location\n- backend-managed edit locking\n- lock heartbeat and lock-status checks\n- upload or discard decision at the end of editing\n- conflict handling before the server copy is replaced\n\n## Ordinary File Operations\n\nThe browser file-management path depends on typed request models and clear storage semantics.\n\n- copy and move requests use structured request data instead of ad hoc parameters\n- same-path or invalid operations are rejected explicitly\n- server-side copy and move semantics depend on the backend's storage capabilities\n- conflict responses and validation errors are part of the user-visible contract\n\nThe backend should stay authoritative here, even when the frontend tries to make the operation feel immediate.\n\n## Why Edit Locking Exists\n\nNative-app editing of SMB-backed files is a coordination problem, not just a download-and-upload shortcut.\n\nThe backend owns the server-facing lock lifecycle so that:\n\n- concurrent edits are visible and controllable\n- the companion can refresh the lock while editing is still in progress\n- stale or interrupted sessions can be detected\n- conflict decisions happen against the real server state\n\n## High-Level Companion Edit Lifecycle\n\nFor the SMB-backed desktop editing path:\n\n1. the companion exchanges the deep-link token for an authenticated session\n2. it fetches file metadata and downloads the file\n3. it acquires the edit lock from the backend\n4. it keeps the lock alive with heartbeat traffic while the file is open\n5. it uploads the changed file or discards it\n6. it releases the lock and closes out the operation\n\nThe backend is the source of truth for lock state even though the companion is the actor performing the desktop-side work.\n\n## Conflict Handling\n\nBefore a modified file is written back, the system compares the expected server state with the current one.\n\nIf the server copy changed while the user was editing, the companion should not silently overwrite it. That is why conflict handling is part of the backend contract rather than just a local desktop decision.\n\n## Important Distinction: Local Drives\n\nLocal-drive workflows do not use this backend edit-lock lifecycle.\n\n- local files are handled through the paired localhost companion API\n- direct local open can avoid download, lock, upload, and \"Done Editing\" entirely\n- SMB-backed native-app editing still depends on backend lock and upload semantics\n\nDo not blur those two paths when changing edit behavior.\n\n## Adjacent Concern: Freshness after Operations\n\nAfter file operations complete, the browser still needs fresh directory state. That is where change notification and WebSocket refresh behavior become relevant.\n\nOrdinary CRUD operations and companion-assisted edit completion both depend on the rest of the system noticing that directory state has changed.\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npm test\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nChoose the exact subset based on whether the change affects ordinary browser file management, companion editing, or both.\n", "0.9": "+++\ntitle = \"File Operations and Edit Locking\"\n+++\n\nNot every file operation in Sambee follows the same lifecycle.\n\n## Two Different Operation Families\n\n### Ordinary File Operations\n\nThese are the browser-facing operations such as:\n\n- browse and inspect\n- create and rename\n- copy and move\n- upload and download\n- delete\n\nThese requests usually enter through the browser-facing API and are executed through the backend storage layer.\n\n### Companion-Assisted SMB Editing\n\nThis is the higher-risk path used when a user opens an SMB-backed file in a native desktop app.\n\nThat flow adds:\n\n- token exchange\n- file download to a temp location\n- backend-managed edit locking\n- lock heartbeat and lock-status checks\n- upload or discard decision at the end of editing\n- conflict handling before the server copy is replaced\n\n## Ordinary File Operations\n\nThe browser file-management path depends on typed request models and clear storage semantics.\n\n- copy and move requests use structured request data instead of ad hoc parameters\n- same-path or invalid operations are rejected explicitly\n- server-side copy and move semantics depend on the backend's storage capabilities\n- conflict responses and validation errors are part of the user-visible contract\n\nThe backend should stay authoritative here, even when the frontend tries to make the operation feel immediate.\n\n## Why Edit Locking Exists\n\nNative-app editing of SMB-backed files is a coordination problem, not just a download-and-upload shortcut.\n\nThe backend owns the server-facing lock lifecycle so that:\n\n- concurrent edits are visible and controllable\n- the companion can refresh the lock while editing is still in progress\n- stale or interrupted sessions can be detected\n- conflict decisions happen against the real server state\n\n## High-Level Companion Edit Lifecycle\n\nFor the SMB-backed desktop editing path:\n\n1. the companion exchanges the deep-link token for an authenticated session\n2. it fetches file metadata and downloads the file\n3. it acquires the edit lock from the backend\n4. it keeps the lock alive with heartbeat traffic while the file is open\n5. it uploads the changed file or discards it\n6. it releases the lock and closes out the operation\n\nThe backend is the source of truth for lock state even though the companion is the actor performing the desktop-side work.\n\n## Conflict Handling\n\nBefore a modified file is written back, the system compares the expected server state with the current one.\n\nIf the server copy changed while the user was editing, the companion should not silently overwrite it. That is why conflict handling is part of the backend contract rather than just a local desktop decision.\n\n## Important Distinction: Local Drives\n\nLocal-drive workflows do not use this backend edit-lock lifecycle.\n\n- local files are handled through the paired localhost companion API\n- direct local open can avoid download, lock, upload, and \"Done Editing\" entirely\n- SMB-backed native-app editing still depends on backend lock and upload semantics\n\nDo not blur those two paths when changing edit behavior.\n\n## Adjacent Concern: Freshness after Operations\n\nAfter file operations complete, the browser still needs fresh directory state. That is where change notification and WebSocket refresh behavior become relevant.\n\nOrdinary CRUD operations and companion-assisted edit completion both depend on the rest of the system noticing that directory state has changed.\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npm test\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nChoose the exact subset based on whether the change affects ordinary browser file management, companion editing, or both.\n", "1.0": "+++\ntitle = \"File Operations and Edit Locking\"\n+++\n\nNot every file operation in Sambee follows the same lifecycle.\n\n## Two Different Operation Families\n\n### Ordinary File Operations\n\nThese are the browser-facing operations such as:\n\n- browse and inspect\n- create and rename\n- copy and move\n- upload and download\n- delete\n\nThese requests usually enter through the browser-facing API and are executed through the backend storage layer.\n\n### Companion-Assisted SMB Editing\n\nThis is the higher-risk path used when a user opens an SMB-backed file in a native desktop app.\n\nThat flow adds:\n\n- token exchange\n- file download to a temp location\n- backend-managed edit locking\n- lock heartbeat and lock-status checks\n- upload or discard decision at the end of editing\n- conflict handling before the server copy is replaced\n\n## Ordinary File Operations\n\nThe browser file-management path depends on typed request models and clear storage semantics.\n\n- copy and move requests use structured request data instead of ad hoc parameters\n- same-path or invalid operations are rejected explicitly\n- server-side copy and move semantics depend on the backend's storage capabilities\n- conflict responses and validation errors are part of the user-visible contract\n\nThe backend should stay authoritative here, even when the frontend tries to make the operation feel immediate.\n\n## Why Edit Locking Exists\n\nNative-app editing of SMB-backed files is a coordination problem, not just a download-and-upload shortcut.\n\nThe backend owns the server-facing lock lifecycle so that:\n\n- concurrent edits are visible and controllable\n- the companion can refresh the lock while editing is still in progress\n- stale or interrupted sessions can be detected\n- conflict decisions happen against the real server state\n\n## High-Level Companion Edit Lifecycle\n\nFor the SMB-backed desktop editing path:\n\n1. the companion exchanges the deep-link token for an authenticated session\n2. it fetches file metadata and downloads the file\n3. it acquires the edit lock from the backend\n4. it keeps the lock alive with heartbeat traffic while the file is open\n5. it uploads the changed file or discards it\n6. it releases the lock and closes out the operation\n\nThe backend is the source of truth for lock state even though the companion is the actor performing the desktop-side work.\n\n## Conflict Handling\n\nBefore a modified file is written back, the system compares the expected server state with the current one.\n\nIf the server copy changed while the user was editing, the companion should not silently overwrite it. That is why conflict handling is part of the backend contract rather than just a local desktop decision.\n\n## Important Distinction: Local Drives\n\nLocal-drive workflows do not use this backend edit-lock lifecycle.\n\n- local files are handled through the paired localhost companion API\n- direct local open can avoid download, lock, upload, and \"Done Editing\" entirely\n- SMB-backed native-app editing still depends on backend lock and upload semantics\n\nDo not blur those two paths when changing edit behavior.\n\n## Adjacent Concern: Freshness after Operations\n\nAfter file operations complete, the browser still needs fresh directory state. That is where change notification and WebSocket refresh behavior become relevant.\n\nOrdinary CRUD operations and companion-assisted edit completion both depend on the rest of the system noticing that directory state has changed.\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npm test\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nChoose the exact subset based on whether the change affects ordinary browser file management, companion editing, or both.\n", "2.0": "+++\ntitle = \"File Operations and Edit Locking\"\n+++\n\nNot every file operation in Sambee follows the same lifecycle.\n\n## Two Different Operation Families\n\n### Ordinary File Operations\n\nThese are the browser-facing operations such as:\n\n- browse and inspect\n- create and rename\n- copy and move\n- upload and download\n- delete\n\nThese requests usually enter through the browser-facing API and are executed through the backend storage layer.\n\n### Companion-Assisted SMB Editing\n\nThis is the higher-risk path used when a user opens an SMB-backed file in a native desktop app.\n\nThat flow adds:\n\n- token exchange\n- file download to a temp location\n- backend-managed edit locking\n- lock heartbeat and lock-status checks\n- upload or discard decision at the end of editing\n- conflict handling before the server copy is replaced\n\n## Ordinary File Operations\n\nThe browser file-management path depends on typed request models and clear storage semantics.\n\n- copy and move requests use structured request data instead of ad hoc parameters\n- same-path or invalid operations are rejected explicitly\n- server-side copy and move semantics depend on the backend's storage capabilities\n- conflict responses and validation errors are part of the user-visible contract\n\nThe backend should stay authoritative here, even when the frontend tries to make the operation feel immediate.\n\n## Why Edit Locking Exists\n\nNative-app editing of SMB-backed files is a coordination problem, not just a download-and-upload shortcut.\n\nThe backend owns the server-facing lock lifecycle so that:\n\n- concurrent edits are visible and controllable\n- the companion can refresh the lock while editing is still in progress\n- stale or interrupted sessions can be detected\n- conflict decisions happen against the real server state\n\n## High-Level Companion Edit Lifecycle\n\nFor the SMB-backed desktop editing path:\n\n1. the companion exchanges the deep-link token for an authenticated session\n2. it fetches file metadata and downloads the file\n3. it acquires the edit lock from the backend\n4. it keeps the lock alive with heartbeat traffic while the file is open\n5. it uploads the changed file or discards it\n6. it releases the lock and closes out the operation\n\nThe backend is the source of truth for lock state even though the companion is the actor performing the desktop-side work.\n\n## Conflict Handling\n\nBefore a modified file is written back, the system compares the expected server state with the current one.\n\nIf the server copy changed while the user was editing, the companion should not silently overwrite it. That is why conflict handling is part of the backend contract rather than just a local desktop decision.\n\n## Important Distinction: Local Drives\n\nLocal-drive workflows do not use this backend edit-lock lifecycle.\n\n- local files are handled through the paired localhost companion API\n- direct local open can avoid download, lock, upload, and \"Done Editing\" entirely\n- SMB-backed native-app editing still depends on backend lock and upload semantics\n\nDo not blur those two paths when changing edit behavior.\n\n## Adjacent Concern: Freshness after Operations\n\nAfter file operations complete, the browser still needs fresh directory state. That is where change notification and WebSocket refresh behavior become relevant.\n\nOrdinary CRUD operations and companion-assisted edit completion both depend on the rest of the system noticing that directory state has changed.\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npm test\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nChoose the exact subset based on whether the change affects ordinary browser file management, companion editing, or both.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:developer-guide/frontend-architecture", "parent_id": "book:developer-guide", "depth": 1, "kind": "section", "label": "frontend-architecture", "title": "Frontend Architecture", "path": "developer-guide/frontend-architecture", "has_children": true, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Frontend Architecture\"\n+++\n\nThe frontend is the primary user-facing product surface. It is where Sambee's browsing, preview, editing, and navigation workflows become visible.\n\nStart with:\n\n- [Frontend Overview](./frontend-overview/)\n- [Theming System and Theme Selection](./theming-system-and-theme-selection/)\n- [File Browser and Navigation Model](./file-browser-and-navigation-model/)\n- [Keyboard Shortcuts and Command Model](./keyboard-shortcuts-and-command-model/)\n- [Viewer Architecture and Preview Contracts](./viewer-architecture-and-preview-contracts/)\n\nUse this section when you need to understand how browser-side behavior connects to the backend and companion.\n", "0.8": "+++\ntitle = \"Frontend Architecture\"\n+++\n\nThe frontend is the primary user-facing product surface. It is where Sambee's browsing, preview, editing, and navigation workflows become visible.\n\nStart with:\n\n- [Frontend Overview](./frontend-overview/)\n- [Theming System and Theme Selection](./theming-system-and-theme-selection/)\n- [File Browser and Navigation Model](./file-browser-and-navigation-model/)\n- [Keyboard Shortcuts and Command Model](./keyboard-shortcuts-and-command-model/)\n- [Viewer Architecture and Preview Contracts](./viewer-architecture-and-preview-contracts/)\n\nUse this section when you need to understand how browser-side behavior connects to the backend and companion.\n", "0.9": "+++\ntitle = \"Frontend Architecture\"\n+++\n\nThe frontend is the primary user-facing product surface. It is where Sambee's browsing, preview, editing, and navigation workflows become visible.\n\nStart with:\n\n- [Frontend Overview](./frontend-overview/)\n- [Theming System and Theme Selection](./theming-system-and-theme-selection/)\n- [File Browser and Navigation Model](./file-browser-and-navigation-model/)\n- [Keyboard Shortcuts and Command Model](./keyboard-shortcuts-and-command-model/)\n- [Viewer Architecture and Preview Contracts](./viewer-architecture-and-preview-contracts/)\n\nUse this section when you need to understand how browser-side behavior connects to the backend and companion.\n", "1.0": "+++\ntitle = \"Frontend Architecture\"\n+++\n\nThe frontend is the primary user-facing product surface. It is where Sambee's browsing, preview, editing, and navigation workflows become visible.\n\nStart with:\n\n- [Frontend Overview](./frontend-overview/)\n- [Theming System and Theme Selection](./theming-system-and-theme-selection/)\n- [File Browser and Navigation Model](./file-browser-and-navigation-model/)\n- [Keyboard Shortcuts and Command Model](./keyboard-shortcuts-and-command-model/)\n- [Viewer Architecture and Preview Contracts](./viewer-architecture-and-preview-contracts/)\n\nUse this section when you need to understand how browser-side behavior connects to the backend and companion.\n", "2.0": "+++\ntitle = \"Frontend Architecture\"\n+++\n\nThe frontend is the primary user-facing product surface. It is where Sambee's browsing, preview, editing, and navigation workflows become visible.\n\nStart with:\n\n- [Frontend Overview](./frontend-overview/)\n- [Theming System and Theme Selection](./theming-system-and-theme-selection/)\n- [File Browser and Navigation Model](./file-browser-and-navigation-model/)\n- [Keyboard Shortcuts and Command Model](./keyboard-shortcuts-and-command-model/)\n- [Viewer Architecture and Preview Contracts](./viewer-architecture-and-preview-contracts/)\n\nUse this section when you need to understand how browser-side behavior connects to the backend and companion.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/frontend-architecture/frontend-overview", "parent_id": "section:developer-guide/frontend-architecture", "depth": 2, "kind": "page", "label": "frontend-overview", "title": "Frontend Overview", "path": "developer-guide/frontend-architecture/frontend-overview", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Frontend Overview\"\n+++\n\nThe frontend is a React and TypeScript application built with Vite. It is responsible for presenting Sambee's workflows clearly while respecting the backend and companion contracts behind them.\n\n## What the Frontend Owns\n\nThe browser app is responsible for:\n\n- routing users into the main product surfaces\n- rendering the file browser, viewer, and editing flows\n- managing browser-side state, selection, and navigation behavior\n- calling backend and companion-facing services through typed client code\n- applying theming, localization, and browser-side logging behavior\n\n## Main Frontend Areas\n\n| Area | Responsibility |\n|---|---|\n| `frontend/src/pages/` | page-level product flows such as the file browser |\n| `frontend/src/components/` | reusable UI building blocks |\n| `frontend/src/services/` | API clients, browser-to-companion integration, and other service helpers |\n| `frontend/src/i18n/` | typed translation resources and locale wiring |\n| `frontend/src/theme/` | theme configuration and theme-selection behavior |\n| `frontend/src/utils/` | formatting, registry, and other supporting utilities |\n\n## File Browser as the Core Surface\n\nThe file browser is the center of the main product UI.\n\n- it supports single-pane and dual-pane workflows\n- it keeps layout state and pane routing aligned with the URL\n- it coordinates selection, search, sorting, CRUD actions, viewer state, and keyboard behavior\n- it handles WebSocket-driven directory refresh behavior\n\nThat is why frontend changes in the file browser often have broader user impact than they first appear to.\n\nFor the main browsing surface itself, continue to [File Browser and Navigation Model](../file-browser-and-navigation-model/).\n\n## Frontend Contracts That Matter\n\n### Backend Contracts\n\nThe frontend depends on stable backend response shapes. When those change, update the corresponding types, service logic, and contract tests together.\n\n### Companion Contracts\n\nThe frontend is also the browser-side orchestrator for companion detection, pairing, local-drive access, and native-app editing initiation. That means browser-side state and desktop-side behavior are tightly linked even though they live in different projects.\n\n### Theming and Localization\n\nThe app treats theme behavior and localization as typed, explicit systems rather than loose UI sugar.\n\n- frontend copy should come from the translation system\n- locale handling and regional formatting are treated as product behavior\n- theme behavior is centralized instead of ad hoc component styling\n\n## Cross-Cutting Frontend Concerns\n\n- keyboard-first browsing and command surfaces\n- typed logging and backend tracing configuration\n- viewer behavior by file type and preview capability\n- responsive behavior, including mobile limitations and dual-pane desktop features\n\n## Rendering Hazards and Prevention Rules\n\nThis codebase has already hit at least one subtle React rendering failure where the app was logically correct but the browser still lost the first user click.\n\nThe useful lesson is that React rendering behavior, native event timing, portal trees, and third-party props can interact in ways that are easy to miss during normal component-level work.\n\n### Representative Failure Mode\n\nOne real frontend regression affected Markdown links inside the viewer.\n\n- links in the Markdown viewer ignored the first click when the viewer had been opened via keyboard\n- the second click worked\n- opening the viewer via mouse did not reproduce the problem\n\nThe root cause was not a single bad line. It was the combination of several implementation details:\n\n1. a global capture-phase `pointerdown` handler in `FileBrowser.tsx` updated keyboard-versus-pointer focus state synchronously\n2. React treated that update as a discrete-event flush and applied it between `pointerdown` and `click`\n3. the viewer shell was still expensive enough that the re-render cascaded through the portal-rendered viewer tree\n4. `react-markdown` override props included a `node` value that would have been dangerous to spread onto a native DOM anchor\n\nThe current code fixes that by deferring the focus-state update with `requestAnimationFrame`, memoizing the dynamic viewer shell, and stripping `node` out of the Markdown link override before spreading the remaining props.\n\n### Why This Class of Bug Matters\n\nThis kind of problem is easy to underestimate because:\n\n- it can be input-mode specific rather than globally reproducible\n- it may only appear when several otherwise-correct abstractions interact\n- the visible symptom can look like a browser bug or flaky click handling when the real cause is a mid-event re-render\n\nContributors should treat event timing and render isolation as architecture concerns, not just local component details.\n\n### Prevention Rules\n\n#### 1. Do Not Trigger Synchronous State Changes in Capture-Phase Pointer Handlers Unless Necessary\n\nCapture-phase `pointerdown` and `mousedown` handlers can run before the click sequence finishes. If they trigger state updates synchronously, React can re-render in the middle of the browser's interaction pipeline.\n\nWhen the state change is not required immediately, defer it past the current event cycle with `requestAnimationFrame`.\n\n#### 2. Keep Portal-Rendered Viewer Surfaces Render-Isolated\n\nViewer trees rendered through dialogs or other portals should not re-render just because an unrelated parent concern changed.\n\nIn practice this means:\n\n- memoize portal-rendered viewer shells when they are intended to be stable\n- be skeptical of parent state changes that can cascade into the viewer tree during active pointer interaction\n- review viewer wrappers such as `DynamicViewer` with the same care as the concrete viewer components themselves\n\n#### 3. Never Blindly Spread Third-Party Props onto Native DOM Elements\n\nLibraries such as `react-markdown` can inject props that are valid for the library layer but unsafe for direct DOM output.\n\nWhen overriding renderers:\n\n- explicitly destructure library-only props such as `node`\n- spread only the remaining DOM-safe props onto native elements\n- assume that leaking unknown props onto the interaction target can change browser behavior in ways that are hard to diagnose\n\n### Practical Audit Checks\n\nWhen debugging or reviewing similar issues, use targeted searches like these:\n\n```bash\ngrep -rn 'addEventListener.*capture' frontend/src/\ngrep -rn '\\.\\.\\.props' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/FileBrowser/DynamicViewer.tsx\n```\n\nThese are not exhaustive audits, but they are good first-pass checks for the specific failure pattern this codebase has already seen.\n\n## Go Deeper\n\n- [Theming System and Theme Selection](../theming-system-and-theme-selection/): theme configuration, built-in themes, persistence, and how the UI switches themes\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL routing, keyboard flows, and refresh behavior\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): central shortcut definitions, browser commands, quick-bar modes, and context-aware handlers\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): file-type registries, preview selection, and conversion-sensitive viewer behavior\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared frontend-facing rules for diagnostics, translatable UI copy, and locale behavior\n\n## Validation Expectations\n\nWhen frontend behavior changes, start with:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change also affects backend or companion contracts, add the matching checks there too.\n", "0.8": "+++\ntitle = \"Frontend Overview\"\n+++\n\nThe frontend is a React and TypeScript application built with Vite. It is responsible for presenting Sambee's workflows clearly while respecting the backend and companion contracts behind them.\n\n## What the Frontend Owns\n\nThe browser app is responsible for:\n\n- routing users into the main product surfaces\n- rendering the file browser, viewer, and editing flows\n- managing browser-side state, selection, and navigation behavior\n- calling backend and companion-facing services through typed client code\n- applying theming, localization, and browser-side logging behavior\n\n## Main Frontend Areas\n\n| Area | Responsibility |\n|---|---|\n| `frontend/src/pages/` | page-level product flows such as the file browser |\n| `frontend/src/components/` | reusable UI building blocks |\n| `frontend/src/services/` | API clients, browser-to-companion integration, and other service helpers |\n| `frontend/src/i18n/` | typed translation resources and locale wiring |\n| `frontend/src/theme/` | theme configuration and theme-selection behavior |\n| `frontend/src/utils/` | formatting, registry, and other supporting utilities |\n\n## File Browser as the Core Surface\n\nThe file browser is the center of the main product UI.\n\n- it supports single-pane and dual-pane workflows\n- it keeps layout state and pane routing aligned with the URL\n- it coordinates selection, search, sorting, CRUD actions, viewer state, and keyboard behavior\n- it handles WebSocket-driven directory refresh behavior\n\nThat is why frontend changes in the file browser often have broader user impact than they first appear to.\n\nFor the main browsing surface itself, continue to [File Browser and Navigation Model](../file-browser-and-navigation-model/).\n\n## Frontend Contracts That Matter\n\n### Backend Contracts\n\nThe frontend depends on stable backend response shapes. When those change, update the corresponding types, service logic, and contract tests together.\n\n### Companion Contracts\n\nThe frontend is also the browser-side orchestrator for companion detection, pairing, local-drive access, and native-app editing initiation. That means browser-side state and desktop-side behavior are tightly linked even though they live in different projects.\n\n### Theming and Localization\n\nThe app treats theme behavior and localization as typed, explicit systems rather than loose UI sugar.\n\n- frontend copy should come from the translation system\n- locale handling and regional formatting are treated as product behavior\n- theme behavior is centralized instead of ad hoc component styling\n\n## Cross-Cutting Frontend Concerns\n\n- keyboard-first browsing and command surfaces\n- typed logging and backend tracing configuration\n- viewer behavior by file type and preview capability\n- responsive behavior, including mobile limitations and dual-pane desktop features\n\n## Rendering Hazards and Prevention Rules\n\nThis codebase has already hit at least one subtle React rendering failure where the app was logically correct but the browser still lost the first user click.\n\nThe useful lesson is that React rendering behavior, native event timing, portal trees, and third-party props can interact in ways that are easy to miss during normal component-level work.\n\n### Representative Failure Mode\n\nOne real frontend regression affected Markdown links inside the viewer.\n\n- links in the Markdown viewer ignored the first click when the viewer had been opened via keyboard\n- the second click worked\n- opening the viewer via mouse did not reproduce the problem\n\nThe root cause was not a single bad line. It was the combination of several implementation details:\n\n1. a global capture-phase `pointerdown` handler in `FileBrowser.tsx` updated keyboard-versus-pointer focus state synchronously\n2. React treated that update as a discrete-event flush and applied it between `pointerdown` and `click`\n3. the viewer shell was still expensive enough that the re-render cascaded through the portal-rendered viewer tree\n4. `react-markdown` override props included a `node` value that would have been dangerous to spread onto a native DOM anchor\n\nThe current code fixes that by deferring the focus-state update with `requestAnimationFrame`, memoizing the dynamic viewer shell, and stripping `node` out of the Markdown link override before spreading the remaining props.\n\n### Why This Class of Bug Matters\n\nThis kind of problem is easy to underestimate because:\n\n- it can be input-mode specific rather than globally reproducible\n- it may only appear when several otherwise-correct abstractions interact\n- the visible symptom can look like a browser bug or flaky click handling when the real cause is a mid-event re-render\n\nContributors should treat event timing and render isolation as architecture concerns, not just local component details.\n\n### Prevention Rules\n\n#### 1. Do Not Trigger Synchronous State Changes in Capture-Phase Pointer Handlers Unless Necessary\n\nCapture-phase `pointerdown` and `mousedown` handlers can run before the click sequence finishes. If they trigger state updates synchronously, React can re-render in the middle of the browser's interaction pipeline.\n\nWhen the state change is not required immediately, defer it past the current event cycle with `requestAnimationFrame`.\n\n#### 2. Keep Portal-Rendered Viewer Surfaces Render-Isolated\n\nViewer trees rendered through dialogs or other portals should not re-render just because an unrelated parent concern changed.\n\nIn practice this means:\n\n- memoize portal-rendered viewer shells when they are intended to be stable\n- be skeptical of parent state changes that can cascade into the viewer tree during active pointer interaction\n- review viewer wrappers such as `DynamicViewer` with the same care as the concrete viewer components themselves\n\n#### 3. Never Blindly Spread Third-Party Props onto Native DOM Elements\n\nLibraries such as `react-markdown` can inject props that are valid for the library layer but unsafe for direct DOM output.\n\nWhen overriding renderers:\n\n- explicitly destructure library-only props such as `node`\n- spread only the remaining DOM-safe props onto native elements\n- assume that leaking unknown props onto the interaction target can change browser behavior in ways that are hard to diagnose\n\n### Practical Audit Checks\n\nWhen debugging or reviewing similar issues, use targeted searches like these:\n\n```bash\ngrep -rn 'addEventListener.*capture' frontend/src/\ngrep -rn '\\.\\.\\.props' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/FileBrowser/DynamicViewer.tsx\n```\n\nThese are not exhaustive audits, but they are good first-pass checks for the specific failure pattern this codebase has already seen.\n\n## Go Deeper\n\n- [Theming System and Theme Selection](../theming-system-and-theme-selection/): theme configuration, built-in themes, persistence, and how the UI switches themes\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL routing, keyboard flows, and refresh behavior\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): central shortcut definitions, browser commands, quick-bar modes, and context-aware handlers\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): file-type registries, preview selection, and conversion-sensitive viewer behavior\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared frontend-facing rules for diagnostics, translatable UI copy, and locale behavior\n\n## Validation Expectations\n\nWhen frontend behavior changes, start with:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change also affects backend or companion contracts, add the matching checks there too.\n", "0.9": "+++\ntitle = \"Frontend Overview\"\n+++\n\nThe frontend is a React and TypeScript application built with Vite. It is responsible for presenting Sambee's workflows clearly while respecting the backend and companion contracts behind them.\n\n## What the Frontend Owns\n\nThe browser app is responsible for:\n\n- routing users into the main product surfaces\n- rendering the file browser, viewer, and editing flows\n- managing browser-side state, selection, and navigation behavior\n- calling backend and companion-facing services through typed client code\n- applying theming, localization, and browser-side logging behavior\n\n## Main Frontend Areas\n\n| Area | Responsibility |\n|---|---|\n| `frontend/src/pages/` | page-level product flows such as the file browser |\n| `frontend/src/components/` | reusable UI building blocks |\n| `frontend/src/services/` | API clients, browser-to-companion integration, and other service helpers |\n| `frontend/src/i18n/` | typed translation resources and locale wiring |\n| `frontend/src/theme/` | theme configuration and theme-selection behavior |\n| `frontend/src/utils/` | formatting, registry, and other supporting utilities |\n\n## File Browser as the Core Surface\n\nThe file browser is the center of the main product UI.\n\n- it supports single-pane and dual-pane workflows\n- it keeps layout state and pane routing aligned with the URL\n- it coordinates selection, search, sorting, CRUD actions, viewer state, and keyboard behavior\n- it handles WebSocket-driven directory refresh behavior\n\nThat is why frontend changes in the file browser often have broader user impact than they first appear to.\n\nFor the main browsing surface itself, continue to [File Browser and Navigation Model](../file-browser-and-navigation-model/).\n\n## Frontend Contracts That Matter\n\n### Backend Contracts\n\nThe frontend depends on stable backend response shapes. When those change, update the corresponding types, service logic, and contract tests together.\n\n### Companion Contracts\n\nThe frontend is also the browser-side orchestrator for companion detection, pairing, local-drive access, and native-app editing initiation. That means browser-side state and desktop-side behavior are tightly linked even though they live in different projects.\n\n### Theming and Localization\n\nThe app treats theme behavior and localization as typed, explicit systems rather than loose UI sugar.\n\n- frontend copy should come from the translation system\n- locale handling and regional formatting are treated as product behavior\n- theme behavior is centralized instead of ad hoc component styling\n\n## Cross-Cutting Frontend Concerns\n\n- keyboard-first browsing and command surfaces\n- typed logging and backend tracing configuration\n- viewer behavior by file type and preview capability\n- responsive behavior, including mobile limitations and dual-pane desktop features\n\n## Rendering Hazards and Prevention Rules\n\nThis codebase has already hit at least one subtle React rendering failure where the app was logically correct but the browser still lost the first user click.\n\nThe useful lesson is that React rendering behavior, native event timing, portal trees, and third-party props can interact in ways that are easy to miss during normal component-level work.\n\n### Representative Failure Mode\n\nOne real frontend regression affected Markdown links inside the viewer.\n\n- links in the Markdown viewer ignored the first click when the viewer had been opened via keyboard\n- the second click worked\n- opening the viewer via mouse did not reproduce the problem\n\nThe root cause was not a single bad line. It was the combination of several implementation details:\n\n1. a global capture-phase `pointerdown` handler in `FileBrowser.tsx` updated keyboard-versus-pointer focus state synchronously\n2. React treated that update as a discrete-event flush and applied it between `pointerdown` and `click`\n3. the viewer shell was still expensive enough that the re-render cascaded through the portal-rendered viewer tree\n4. `react-markdown` override props included a `node` value that would have been dangerous to spread onto a native DOM anchor\n\nThe current code fixes that by deferring the focus-state update with `requestAnimationFrame`, memoizing the dynamic viewer shell, and stripping `node` out of the Markdown link override before spreading the remaining props.\n\n### Why This Class of Bug Matters\n\nThis kind of problem is easy to underestimate because:\n\n- it can be input-mode specific rather than globally reproducible\n- it may only appear when several otherwise-correct abstractions interact\n- the visible symptom can look like a browser bug or flaky click handling when the real cause is a mid-event re-render\n\nContributors should treat event timing and render isolation as architecture concerns, not just local component details.\n\n### Prevention Rules\n\n#### 1. Do Not Trigger Synchronous State Changes in Capture-Phase Pointer Handlers Unless Necessary\n\nCapture-phase `pointerdown` and `mousedown` handlers can run before the click sequence finishes. If they trigger state updates synchronously, React can re-render in the middle of the browser's interaction pipeline.\n\nWhen the state change is not required immediately, defer it past the current event cycle with `requestAnimationFrame`.\n\n#### 2. Keep Portal-Rendered Viewer Surfaces Render-Isolated\n\nViewer trees rendered through dialogs or other portals should not re-render just because an unrelated parent concern changed.\n\nIn practice this means:\n\n- memoize portal-rendered viewer shells when they are intended to be stable\n- be skeptical of parent state changes that can cascade into the viewer tree during active pointer interaction\n- review viewer wrappers such as `DynamicViewer` with the same care as the concrete viewer components themselves\n\n#### 3. Never Blindly Spread Third-Party Props onto Native DOM Elements\n\nLibraries such as `react-markdown` can inject props that are valid for the library layer but unsafe for direct DOM output.\n\nWhen overriding renderers:\n\n- explicitly destructure library-only props such as `node`\n- spread only the remaining DOM-safe props onto native elements\n- assume that leaking unknown props onto the interaction target can change browser behavior in ways that are hard to diagnose\n\n### Practical Audit Checks\n\nWhen debugging or reviewing similar issues, use targeted searches like these:\n\n```bash\ngrep -rn 'addEventListener.*capture' frontend/src/\ngrep -rn '\\.\\.\\.props' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/FileBrowser/DynamicViewer.tsx\n```\n\nThese are not exhaustive audits, but they are good first-pass checks for the specific failure pattern this codebase has already seen.\n\n## Go Deeper\n\n- [Theming System and Theme Selection](../theming-system-and-theme-selection/): theme configuration, built-in themes, persistence, and how the UI switches themes\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL routing, keyboard flows, and refresh behavior\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): central shortcut definitions, browser commands, quick-bar modes, and context-aware handlers\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): file-type registries, preview selection, and conversion-sensitive viewer behavior\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared frontend-facing rules for diagnostics, translatable UI copy, and locale behavior\n\n## Validation Expectations\n\nWhen frontend behavior changes, start with:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change also affects backend or companion contracts, add the matching checks there too.\n", "1.0": "+++\ntitle = \"Frontend Overview\"\n+++\n\nThe frontend is a React and TypeScript application built with Vite. It is responsible for presenting Sambee's workflows clearly while respecting the backend and companion contracts behind them.\n\n## What the Frontend Owns\n\nThe browser app is responsible for:\n\n- routing users into the main product surfaces\n- rendering the file browser, viewer, and editing flows\n- managing browser-side state, selection, and navigation behavior\n- calling backend and companion-facing services through typed client code\n- applying theming, localization, and browser-side logging behavior\n\n## Main Frontend Areas\n\n| Area | Responsibility |\n|---|---|\n| `frontend/src/pages/` | page-level product flows such as the file browser |\n| `frontend/src/components/` | reusable UI building blocks |\n| `frontend/src/services/` | API clients, browser-to-companion integration, and other service helpers |\n| `frontend/src/i18n/` | typed translation resources and locale wiring |\n| `frontend/src/theme/` | theme configuration and theme-selection behavior |\n| `frontend/src/utils/` | formatting, registry, and other supporting utilities |\n\n## File Browser as the Core Surface\n\nThe file browser is the center of the main product UI.\n\n- it supports single-pane and dual-pane workflows\n- it keeps layout state and pane routing aligned with the URL\n- it coordinates selection, search, sorting, CRUD actions, viewer state, and keyboard behavior\n- it handles WebSocket-driven directory refresh behavior\n\nThat is why frontend changes in the file browser often have broader user impact than they first appear to.\n\nFor the main browsing surface itself, continue to [File Browser and Navigation Model](../file-browser-and-navigation-model/).\n\n## Frontend Contracts That Matter\n\n### Backend Contracts\n\nThe frontend depends on stable backend response shapes. When those change, update the corresponding types, service logic, and contract tests together.\n\n### Companion Contracts\n\nThe frontend is also the browser-side orchestrator for companion detection, pairing, local-drive access, and native-app editing initiation. That means browser-side state and desktop-side behavior are tightly linked even though they live in different projects.\n\n### Theming and Localization\n\nThe app treats theme behavior and localization as typed, explicit systems rather than loose UI sugar.\n\n- frontend copy should come from the translation system\n- locale handling and regional formatting are treated as product behavior\n- theme behavior is centralized instead of ad hoc component styling\n\n## Cross-Cutting Frontend Concerns\n\n- keyboard-first browsing and command surfaces\n- typed logging and backend tracing configuration\n- viewer behavior by file type and preview capability\n- responsive behavior, including mobile limitations and dual-pane desktop features\n\n## Rendering Hazards and Prevention Rules\n\nThis codebase has already hit at least one subtle React rendering failure where the app was logically correct but the browser still lost the first user click.\n\nThe useful lesson is that React rendering behavior, native event timing, portal trees, and third-party props can interact in ways that are easy to miss during normal component-level work.\n\n### Representative Failure Mode\n\nOne real frontend regression affected Markdown links inside the viewer.\n\n- links in the Markdown viewer ignored the first click when the viewer had been opened via keyboard\n- the second click worked\n- opening the viewer via mouse did not reproduce the problem\n\nThe root cause was not a single bad line. It was the combination of several implementation details:\n\n1. a global capture-phase `pointerdown` handler in `FileBrowser.tsx` updated keyboard-versus-pointer focus state synchronously\n2. React treated that update as a discrete-event flush and applied it between `pointerdown` and `click`\n3. the viewer shell was still expensive enough that the re-render cascaded through the portal-rendered viewer tree\n4. `react-markdown` override props included a `node` value that would have been dangerous to spread onto a native DOM anchor\n\nThe current code fixes that by deferring the focus-state update with `requestAnimationFrame`, memoizing the dynamic viewer shell, and stripping `node` out of the Markdown link override before spreading the remaining props.\n\n### Why This Class of Bug Matters\n\nThis kind of problem is easy to underestimate because:\n\n- it can be input-mode specific rather than globally reproducible\n- it may only appear when several otherwise-correct abstractions interact\n- the visible symptom can look like a browser bug or flaky click handling when the real cause is a mid-event re-render\n\nContributors should treat event timing and render isolation as architecture concerns, not just local component details.\n\n### Prevention Rules\n\n#### 1. Do Not Trigger Synchronous State Changes in Capture-Phase Pointer Handlers Unless Necessary\n\nCapture-phase `pointerdown` and `mousedown` handlers can run before the click sequence finishes. If they trigger state updates synchronously, React can re-render in the middle of the browser's interaction pipeline.\n\nWhen the state change is not required immediately, defer it past the current event cycle with `requestAnimationFrame`.\n\n#### 2. Keep Portal-Rendered Viewer Surfaces Render-Isolated\n\nViewer trees rendered through dialogs or other portals should not re-render just because an unrelated parent concern changed.\n\nIn practice this means:\n\n- memoize portal-rendered viewer shells when they are intended to be stable\n- be skeptical of parent state changes that can cascade into the viewer tree during active pointer interaction\n- review viewer wrappers such as `DynamicViewer` with the same care as the concrete viewer components themselves\n\n#### 3. Never Blindly Spread Third-Party Props onto Native DOM Elements\n\nLibraries such as `react-markdown` can inject props that are valid for the library layer but unsafe for direct DOM output.\n\nWhen overriding renderers:\n\n- explicitly destructure library-only props such as `node`\n- spread only the remaining DOM-safe props onto native elements\n- assume that leaking unknown props onto the interaction target can change browser behavior in ways that are hard to diagnose\n\n### Practical Audit Checks\n\nWhen debugging or reviewing similar issues, use targeted searches like these:\n\n```bash\ngrep -rn 'addEventListener.*capture' frontend/src/\ngrep -rn '\\.\\.\\.props' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/FileBrowser/DynamicViewer.tsx\n```\n\nThese are not exhaustive audits, but they are good first-pass checks for the specific failure pattern this codebase has already seen.\n\n## Go Deeper\n\n- [Theming System and Theme Selection](../theming-system-and-theme-selection/): theme configuration, built-in themes, persistence, and how the UI switches themes\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL routing, keyboard flows, and refresh behavior\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): central shortcut definitions, browser commands, quick-bar modes, and context-aware handlers\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): file-type registries, preview selection, and conversion-sensitive viewer behavior\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared frontend-facing rules for diagnostics, translatable UI copy, and locale behavior\n\n## Validation Expectations\n\nWhen frontend behavior changes, start with:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change also affects backend or companion contracts, add the matching checks there too.\n", "2.0": "+++\ntitle = \"Frontend Overview\"\n+++\n\nThe frontend is a React and TypeScript application built with Vite. It is responsible for presenting Sambee's workflows clearly while respecting the backend and companion contracts behind them.\n\n## What the Frontend Owns\n\nThe browser app is responsible for:\n\n- routing users into the main product surfaces\n- rendering the file browser, viewer, and editing flows\n- managing browser-side state, selection, and navigation behavior\n- calling backend and companion-facing services through typed client code\n- applying theming, localization, and browser-side logging behavior\n\n## Main Frontend Areas\n\n| Area | Responsibility |\n|---|---|\n| `frontend/src/pages/` | page-level product flows such as the file browser |\n| `frontend/src/components/` | reusable UI building blocks |\n| `frontend/src/services/` | API clients, browser-to-companion integration, and other service helpers |\n| `frontend/src/i18n/` | typed translation resources and locale wiring |\n| `frontend/src/theme/` | theme configuration and theme-selection behavior |\n| `frontend/src/utils/` | formatting, registry, and other supporting utilities |\n\n## File Browser as the Core Surface\n\nThe file browser is the center of the main product UI.\n\n- it supports single-pane and dual-pane workflows\n- it keeps layout state and pane routing aligned with the URL\n- it coordinates selection, search, sorting, CRUD actions, viewer state, and keyboard behavior\n- it handles WebSocket-driven directory refresh behavior\n\nThat is why frontend changes in the file browser often have broader user impact than they first appear to.\n\nFor the main browsing surface itself, continue to [File Browser and Navigation Model](../file-browser-and-navigation-model/).\n\n## Frontend Contracts That Matter\n\n### Backend Contracts\n\nThe frontend depends on stable backend response shapes. When those change, update the corresponding types, service logic, and contract tests together.\n\n### Companion Contracts\n\nThe frontend is also the browser-side orchestrator for companion detection, pairing, local-drive access, and native-app editing initiation. That means browser-side state and desktop-side behavior are tightly linked even though they live in different projects.\n\n### Theming and Localization\n\nThe app treats theme behavior and localization as typed, explicit systems rather than loose UI sugar.\n\n- frontend copy should come from the translation system\n- locale handling and regional formatting are treated as product behavior\n- theme behavior is centralized instead of ad hoc component styling\n\n## Cross-Cutting Frontend Concerns\n\n- keyboard-first browsing and command surfaces\n- typed logging and backend tracing configuration\n- viewer behavior by file type and preview capability\n- responsive behavior, including mobile limitations and dual-pane desktop features\n\n## Rendering Hazards and Prevention Rules\n\nThis codebase has already hit at least one subtle React rendering failure where the app was logically correct but the browser still lost the first user click.\n\nThe useful lesson is that React rendering behavior, native event timing, portal trees, and third-party props can interact in ways that are easy to miss during normal component-level work.\n\n### Representative Failure Mode\n\nOne real frontend regression affected Markdown links inside the viewer.\n\n- links in the Markdown viewer ignored the first click when the viewer had been opened via keyboard\n- the second click worked\n- opening the viewer via mouse did not reproduce the problem\n\nThe root cause was not a single bad line. It was the combination of several implementation details:\n\n1. a global capture-phase `pointerdown` handler in `FileBrowser.tsx` updated keyboard-versus-pointer focus state synchronously\n2. React treated that update as a discrete-event flush and applied it between `pointerdown` and `click`\n3. the viewer shell was still expensive enough that the re-render cascaded through the portal-rendered viewer tree\n4. `react-markdown` override props included a `node` value that would have been dangerous to spread onto a native DOM anchor\n\nThe current code fixes that by deferring the focus-state update with `requestAnimationFrame`, memoizing the dynamic viewer shell, and stripping `node` out of the Markdown link override before spreading the remaining props.\n\n### Why This Class of Bug Matters\n\nThis kind of problem is easy to underestimate because:\n\n- it can be input-mode specific rather than globally reproducible\n- it may only appear when several otherwise-correct abstractions interact\n- the visible symptom can look like a browser bug or flaky click handling when the real cause is a mid-event re-render\n\nContributors should treat event timing and render isolation as architecture concerns, not just local component details.\n\n### Prevention Rules\n\n#### 1. Do Not Trigger Synchronous State Changes in Capture-Phase Pointer Handlers Unless Necessary\n\nCapture-phase `pointerdown` and `mousedown` handlers can run before the click sequence finishes. If they trigger state updates synchronously, React can re-render in the middle of the browser's interaction pipeline.\n\nWhen the state change is not required immediately, defer it past the current event cycle with `requestAnimationFrame`.\n\n#### 2. Keep Portal-Rendered Viewer Surfaces Render-Isolated\n\nViewer trees rendered through dialogs or other portals should not re-render just because an unrelated parent concern changed.\n\nIn practice this means:\n\n- memoize portal-rendered viewer shells when they are intended to be stable\n- be skeptical of parent state changes that can cascade into the viewer tree during active pointer interaction\n- review viewer wrappers such as `DynamicViewer` with the same care as the concrete viewer components themselves\n\n#### 3. Never Blindly Spread Third-Party Props onto Native DOM Elements\n\nLibraries such as `react-markdown` can inject props that are valid for the library layer but unsafe for direct DOM output.\n\nWhen overriding renderers:\n\n- explicitly destructure library-only props such as `node`\n- spread only the remaining DOM-safe props onto native elements\n- assume that leaking unknown props onto the interaction target can change browser behavior in ways that are hard to diagnose\n\n### Practical Audit Checks\n\nWhen debugging or reviewing similar issues, use targeted searches like these:\n\n```bash\ngrep -rn 'addEventListener.*capture' frontend/src/\ngrep -rn '\\.\\.\\.props' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/FileBrowser/DynamicViewer.tsx\n```\n\nThese are not exhaustive audits, but they are good first-pass checks for the specific failure pattern this codebase has already seen.\n\n## Go Deeper\n\n- [Theming System and Theme Selection](../theming-system-and-theme-selection/): theme configuration, built-in themes, persistence, and how the UI switches themes\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL routing, keyboard flows, and refresh behavior\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): central shortcut definitions, browser commands, quick-bar modes, and context-aware handlers\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): file-type registries, preview selection, and conversion-sensitive viewer behavior\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared frontend-facing rules for diagnostics, translatable UI copy, and locale behavior\n\n## Validation Expectations\n\nWhen frontend behavior changes, start with:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change also affects backend or companion contracts, add the matching checks there too.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Frontend Overview\"\n+++\n\nThe frontend is a React and TypeScript application built with Vite. It is responsible for presenting Sambee's workflows clearly while respecting the backend and companion contracts behind them.\n\n## What the Frontend Owns\n\nThe browser app is responsible for:\n\n- routing users into the main product surfaces\n- rendering the file browser, viewer, and editing flows\n- managing browser-side state, selection, and navigation behavior\n- calling backend and companion-facing services through typed client code\n- applying theming, localization, and browser-side logging behavior\n\n## Main Frontend Areas\n\n| Area | Responsibility |\n|---|---|\n| `frontend/src/pages/` | page-level product flows such as the file browser |\n| `frontend/src/components/` | reusable UI building blocks |\n| `frontend/src/services/` | API clients, browser-to-companion integration, and other service helpers |\n| `frontend/src/i18n/` | typed translation resources and locale wiring |\n| `frontend/src/theme/` | theme configuration and theme-selection behavior |\n| `frontend/src/utils/` | formatting, registry, and other supporting utilities |\n\n## File Browser as the Core Surface\n\nThe file browser is the center of the main product UI.\n\n- it supports single-pane and dual-pane workflows\n- it keeps layout state and pane routing aligned with the URL\n- it coordinates selection, search, sorting, CRUD actions, viewer state, and keyboard behavior\n- it handles WebSocket-driven directory refresh behavior\n\nThat is why frontend changes in the file browser often have broader user impact than they first appear to.\n\nFor the main browsing surface itself, continue to [File Browser and Navigation Model](../file-browser-and-navigation-model/).\n\n## Frontend Contracts That Matter\n\n### Backend Contracts\n\nThe frontend depends on stable backend response shapes. When those change, update the corresponding types, service logic, and contract tests together.\n\n### Companion Contracts\n\nThe frontend is also the browser-side orchestrator for companion detection, pairing, local-drive access, and native-app editing initiation. That means browser-side state and desktop-side behavior are tightly linked even though they live in different projects.\n\n### Theming and Localization\n\nThe app treats theme behavior and localization as typed, explicit systems rather than loose UI sugar.\n\n- frontend copy should come from the translation system\n- locale handling and regional formatting are treated as product behavior\n- theme behavior is centralized instead of ad hoc component styling\n\n## Cross-Cutting Frontend Concerns\n\n- keyboard-first browsing and command surfaces\n- typed logging and backend tracing configuration\n- viewer behavior by file type and preview capability\n- responsive behavior, including mobile limitations and dual-pane desktop features\n\n## Rendering Hazards and Prevention Rules\n\nThis codebase has already hit at least one subtle React rendering failure where the app was logically correct but the browser still lost the first user click.\n\nThe useful lesson is that React rendering behavior, native event timing, portal trees, and third-party props can interact in ways that are easy to miss during normal component-level work.\n\n### Representative Failure Mode\n\nOne real frontend regression affected Markdown links inside the viewer.\n\n- links in the Markdown viewer ignored the first click when the viewer had been opened via keyboard\n- the second click worked\n- opening the viewer via mouse did not reproduce the problem\n\nThe root cause was not a single bad line. It was the combination of several implementation details:\n\n1. a global capture-phase `pointerdown` handler in `FileBrowser.tsx` updated keyboard-versus-pointer focus state synchronously\n2. React treated that update as a discrete-event flush and applied it between `pointerdown` and `click`\n3. the viewer shell was still expensive enough that the re-render cascaded through the portal-rendered viewer tree\n4. `react-markdown` override props included a `node` value that would have been dangerous to spread onto a native DOM anchor\n\nThe current code fixes that by deferring the focus-state update with `requestAnimationFrame`, memoizing the dynamic viewer shell, and stripping `node` out of the Markdown link override before spreading the remaining props.\n\n### Why This Class of Bug Matters\n\nThis kind of problem is easy to underestimate because:\n\n- it can be input-mode specific rather than globally reproducible\n- it may only appear when several otherwise-correct abstractions interact\n- the visible symptom can look like a browser bug or flaky click handling when the real cause is a mid-event re-render\n\nContributors should treat event timing and render isolation as architecture concerns, not just local component details.\n\n### Prevention Rules\n\n#### 1. Do Not Trigger Synchronous State Changes in Capture-Phase Pointer Handlers Unless Necessary\n\nCapture-phase `pointerdown` and `mousedown` handlers can run before the click sequence finishes. If they trigger state updates synchronously, React can re-render in the middle of the browser's interaction pipeline.\n\nWhen the state change is not required immediately, defer it past the current event cycle with `requestAnimationFrame`.\n\n#### 2. Keep Portal-Rendered Viewer Surfaces Render-Isolated\n\nViewer trees rendered through dialogs or other portals should not re-render just because an unrelated parent concern changed.\n\nIn practice this means:\n\n- memoize portal-rendered viewer shells when they are intended to be stable\n- be skeptical of parent state changes that can cascade into the viewer tree during active pointer interaction\n- review viewer wrappers such as `DynamicViewer` with the same care as the concrete viewer components themselves\n\n#### 3. Never Blindly Spread Third-Party Props onto Native DOM Elements\n\nLibraries such as `react-markdown` can inject props that are valid for the library layer but unsafe for direct DOM output.\n\nWhen overriding renderers:\n\n- explicitly destructure library-only props such as `node`\n- spread only the remaining DOM-safe props onto native elements\n- assume that leaking unknown props onto the interaction target can change browser behavior in ways that are hard to diagnose\n\n### Practical Audit Checks\n\nWhen debugging or reviewing similar issues, use targeted searches like these:\n\n```bash\ngrep -rn 'addEventListener.*capture' frontend/src/\ngrep -rn '\\.\\.\\.props' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/FileBrowser/DynamicViewer.tsx\n```\n\nThese are not exhaustive audits, but they are good first-pass checks for the specific failure pattern this codebase has already seen.\n\n## Go Deeper\n\n- [Theming System and Theme Selection](../theming-system-and-theme-selection/): theme configuration, built-in themes, persistence, and how the UI switches themes\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL routing, keyboard flows, and refresh behavior\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): central shortcut definitions, browser commands, quick-bar modes, and context-aware handlers\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): file-type registries, preview selection, and conversion-sensitive viewer behavior\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared frontend-facing rules for diagnostics, translatable UI copy, and locale behavior\n\n## Validation Expectations\n\nWhen frontend behavior changes, start with:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change also affects backend or companion contracts, add the matching checks there too.\n", "0.8": "+++\ntitle = \"Frontend Overview\"\n+++\n\nThe frontend is a React and TypeScript application built with Vite. It is responsible for presenting Sambee's workflows clearly while respecting the backend and companion contracts behind them.\n\n## What the Frontend Owns\n\nThe browser app is responsible for:\n\n- routing users into the main product surfaces\n- rendering the file browser, viewer, and editing flows\n- managing browser-side state, selection, and navigation behavior\n- calling backend and companion-facing services through typed client code\n- applying theming, localization, and browser-side logging behavior\n\n## Main Frontend Areas\n\n| Area | Responsibility |\n|---|---|\n| `frontend/src/pages/` | page-level product flows such as the file browser |\n| `frontend/src/components/` | reusable UI building blocks |\n| `frontend/src/services/` | API clients, browser-to-companion integration, and other service helpers |\n| `frontend/src/i18n/` | typed translation resources and locale wiring |\n| `frontend/src/theme/` | theme configuration and theme-selection behavior |\n| `frontend/src/utils/` | formatting, registry, and other supporting utilities |\n\n## File Browser as the Core Surface\n\nThe file browser is the center of the main product UI.\n\n- it supports single-pane and dual-pane workflows\n- it keeps layout state and pane routing aligned with the URL\n- it coordinates selection, search, sorting, CRUD actions, viewer state, and keyboard behavior\n- it handles WebSocket-driven directory refresh behavior\n\nThat is why frontend changes in the file browser often have broader user impact than they first appear to.\n\nFor the main browsing surface itself, continue to [File Browser and Navigation Model](../file-browser-and-navigation-model/).\n\n## Frontend Contracts That Matter\n\n### Backend Contracts\n\nThe frontend depends on stable backend response shapes. When those change, update the corresponding types, service logic, and contract tests together.\n\n### Companion Contracts\n\nThe frontend is also the browser-side orchestrator for companion detection, pairing, local-drive access, and native-app editing initiation. That means browser-side state and desktop-side behavior are tightly linked even though they live in different projects.\n\n### Theming and Localization\n\nThe app treats theme behavior and localization as typed, explicit systems rather than loose UI sugar.\n\n- frontend copy should come from the translation system\n- locale handling and regional formatting are treated as product behavior\n- theme behavior is centralized instead of ad hoc component styling\n\n## Cross-Cutting Frontend Concerns\n\n- keyboard-first browsing and command surfaces\n- typed logging and backend tracing configuration\n- viewer behavior by file type and preview capability\n- responsive behavior, including mobile limitations and dual-pane desktop features\n\n## Rendering Hazards and Prevention Rules\n\nThis codebase has already hit at least one subtle React rendering failure where the app was logically correct but the browser still lost the first user click.\n\nThe useful lesson is that React rendering behavior, native event timing, portal trees, and third-party props can interact in ways that are easy to miss during normal component-level work.\n\n### Representative Failure Mode\n\nOne real frontend regression affected Markdown links inside the viewer.\n\n- links in the Markdown viewer ignored the first click when the viewer had been opened via keyboard\n- the second click worked\n- opening the viewer via mouse did not reproduce the problem\n\nThe root cause was not a single bad line. It was the combination of several implementation details:\n\n1. a global capture-phase `pointerdown` handler in `FileBrowser.tsx` updated keyboard-versus-pointer focus state synchronously\n2. React treated that update as a discrete-event flush and applied it between `pointerdown` and `click`\n3. the viewer shell was still expensive enough that the re-render cascaded through the portal-rendered viewer tree\n4. `react-markdown` override props included a `node` value that would have been dangerous to spread onto a native DOM anchor\n\nThe current code fixes that by deferring the focus-state update with `requestAnimationFrame`, memoizing the dynamic viewer shell, and stripping `node` out of the Markdown link override before spreading the remaining props.\n\n### Why This Class of Bug Matters\n\nThis kind of problem is easy to underestimate because:\n\n- it can be input-mode specific rather than globally reproducible\n- it may only appear when several otherwise-correct abstractions interact\n- the visible symptom can look like a browser bug or flaky click handling when the real cause is a mid-event re-render\n\nContributors should treat event timing and render isolation as architecture concerns, not just local component details.\n\n### Prevention Rules\n\n#### 1. Do Not Trigger Synchronous State Changes in Capture-Phase Pointer Handlers Unless Necessary\n\nCapture-phase `pointerdown` and `mousedown` handlers can run before the click sequence finishes. If they trigger state updates synchronously, React can re-render in the middle of the browser's interaction pipeline.\n\nWhen the state change is not required immediately, defer it past the current event cycle with `requestAnimationFrame`.\n\n#### 2. Keep Portal-Rendered Viewer Surfaces Render-Isolated\n\nViewer trees rendered through dialogs or other portals should not re-render just because an unrelated parent concern changed.\n\nIn practice this means:\n\n- memoize portal-rendered viewer shells when they are intended to be stable\n- be skeptical of parent state changes that can cascade into the viewer tree during active pointer interaction\n- review viewer wrappers such as `DynamicViewer` with the same care as the concrete viewer components themselves\n\n#### 3. Never Blindly Spread Third-Party Props onto Native DOM Elements\n\nLibraries such as `react-markdown` can inject props that are valid for the library layer but unsafe for direct DOM output.\n\nWhen overriding renderers:\n\n- explicitly destructure library-only props such as `node`\n- spread only the remaining DOM-safe props onto native elements\n- assume that leaking unknown props onto the interaction target can change browser behavior in ways that are hard to diagnose\n\n### Practical Audit Checks\n\nWhen debugging or reviewing similar issues, use targeted searches like these:\n\n```bash\ngrep -rn 'addEventListener.*capture' frontend/src/\ngrep -rn '\\.\\.\\.props' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/FileBrowser/DynamicViewer.tsx\n```\n\nThese are not exhaustive audits, but they are good first-pass checks for the specific failure pattern this codebase has already seen.\n\n## Go Deeper\n\n- [Theming System and Theme Selection](../theming-system-and-theme-selection/): theme configuration, built-in themes, persistence, and how the UI switches themes\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL routing, keyboard flows, and refresh behavior\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): central shortcut definitions, browser commands, quick-bar modes, and context-aware handlers\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): file-type registries, preview selection, and conversion-sensitive viewer behavior\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared frontend-facing rules for diagnostics, translatable UI copy, and locale behavior\n\n## Validation Expectations\n\nWhen frontend behavior changes, start with:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change also affects backend or companion contracts, add the matching checks there too.\n", "0.9": "+++\ntitle = \"Frontend Overview\"\n+++\n\nThe frontend is a React and TypeScript application built with Vite. It is responsible for presenting Sambee's workflows clearly while respecting the backend and companion contracts behind them.\n\n## What the Frontend Owns\n\nThe browser app is responsible for:\n\n- routing users into the main product surfaces\n- rendering the file browser, viewer, and editing flows\n- managing browser-side state, selection, and navigation behavior\n- calling backend and companion-facing services through typed client code\n- applying theming, localization, and browser-side logging behavior\n\n## Main Frontend Areas\n\n| Area | Responsibility |\n|---|---|\n| `frontend/src/pages/` | page-level product flows such as the file browser |\n| `frontend/src/components/` | reusable UI building blocks |\n| `frontend/src/services/` | API clients, browser-to-companion integration, and other service helpers |\n| `frontend/src/i18n/` | typed translation resources and locale wiring |\n| `frontend/src/theme/` | theme configuration and theme-selection behavior |\n| `frontend/src/utils/` | formatting, registry, and other supporting utilities |\n\n## File Browser as the Core Surface\n\nThe file browser is the center of the main product UI.\n\n- it supports single-pane and dual-pane workflows\n- it keeps layout state and pane routing aligned with the URL\n- it coordinates selection, search, sorting, CRUD actions, viewer state, and keyboard behavior\n- it handles WebSocket-driven directory refresh behavior\n\nThat is why frontend changes in the file browser often have broader user impact than they first appear to.\n\nFor the main browsing surface itself, continue to [File Browser and Navigation Model](../file-browser-and-navigation-model/).\n\n## Frontend Contracts That Matter\n\n### Backend Contracts\n\nThe frontend depends on stable backend response shapes. When those change, update the corresponding types, service logic, and contract tests together.\n\n### Companion Contracts\n\nThe frontend is also the browser-side orchestrator for companion detection, pairing, local-drive access, and native-app editing initiation. That means browser-side state and desktop-side behavior are tightly linked even though they live in different projects.\n\n### Theming and Localization\n\nThe app treats theme behavior and localization as typed, explicit systems rather than loose UI sugar.\n\n- frontend copy should come from the translation system\n- locale handling and regional formatting are treated as product behavior\n- theme behavior is centralized instead of ad hoc component styling\n\n## Cross-Cutting Frontend Concerns\n\n- keyboard-first browsing and command surfaces\n- typed logging and backend tracing configuration\n- viewer behavior by file type and preview capability\n- responsive behavior, including mobile limitations and dual-pane desktop features\n\n## Rendering Hazards and Prevention Rules\n\nThis codebase has already hit at least one subtle React rendering failure where the app was logically correct but the browser still lost the first user click.\n\nThe useful lesson is that React rendering behavior, native event timing, portal trees, and third-party props can interact in ways that are easy to miss during normal component-level work.\n\n### Representative Failure Mode\n\nOne real frontend regression affected Markdown links inside the viewer.\n\n- links in the Markdown viewer ignored the first click when the viewer had been opened via keyboard\n- the second click worked\n- opening the viewer via mouse did not reproduce the problem\n\nThe root cause was not a single bad line. It was the combination of several implementation details:\n\n1. a global capture-phase `pointerdown` handler in `FileBrowser.tsx` updated keyboard-versus-pointer focus state synchronously\n2. React treated that update as a discrete-event flush and applied it between `pointerdown` and `click`\n3. the viewer shell was still expensive enough that the re-render cascaded through the portal-rendered viewer tree\n4. `react-markdown` override props included a `node` value that would have been dangerous to spread onto a native DOM anchor\n\nThe current code fixes that by deferring the focus-state update with `requestAnimationFrame`, memoizing the dynamic viewer shell, and stripping `node` out of the Markdown link override before spreading the remaining props.\n\n### Why This Class of Bug Matters\n\nThis kind of problem is easy to underestimate because:\n\n- it can be input-mode specific rather than globally reproducible\n- it may only appear when several otherwise-correct abstractions interact\n- the visible symptom can look like a browser bug or flaky click handling when the real cause is a mid-event re-render\n\nContributors should treat event timing and render isolation as architecture concerns, not just local component details.\n\n### Prevention Rules\n\n#### 1. Do Not Trigger Synchronous State Changes in Capture-Phase Pointer Handlers Unless Necessary\n\nCapture-phase `pointerdown` and `mousedown` handlers can run before the click sequence finishes. If they trigger state updates synchronously, React can re-render in the middle of the browser's interaction pipeline.\n\nWhen the state change is not required immediately, defer it past the current event cycle with `requestAnimationFrame`.\n\n#### 2. Keep Portal-Rendered Viewer Surfaces Render-Isolated\n\nViewer trees rendered through dialogs or other portals should not re-render just because an unrelated parent concern changed.\n\nIn practice this means:\n\n- memoize portal-rendered viewer shells when they are intended to be stable\n- be skeptical of parent state changes that can cascade into the viewer tree during active pointer interaction\n- review viewer wrappers such as `DynamicViewer` with the same care as the concrete viewer components themselves\n\n#### 3. Never Blindly Spread Third-Party Props onto Native DOM Elements\n\nLibraries such as `react-markdown` can inject props that are valid for the library layer but unsafe for direct DOM output.\n\nWhen overriding renderers:\n\n- explicitly destructure library-only props such as `node`\n- spread only the remaining DOM-safe props onto native elements\n- assume that leaking unknown props onto the interaction target can change browser behavior in ways that are hard to diagnose\n\n### Practical Audit Checks\n\nWhen debugging or reviewing similar issues, use targeted searches like these:\n\n```bash\ngrep -rn 'addEventListener.*capture' frontend/src/\ngrep -rn '\\.\\.\\.props' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/FileBrowser/DynamicViewer.tsx\n```\n\nThese are not exhaustive audits, but they are good first-pass checks for the specific failure pattern this codebase has already seen.\n\n## Go Deeper\n\n- [Theming System and Theme Selection](../theming-system-and-theme-selection/): theme configuration, built-in themes, persistence, and how the UI switches themes\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL routing, keyboard flows, and refresh behavior\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): central shortcut definitions, browser commands, quick-bar modes, and context-aware handlers\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): file-type registries, preview selection, and conversion-sensitive viewer behavior\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared frontend-facing rules for diagnostics, translatable UI copy, and locale behavior\n\n## Validation Expectations\n\nWhen frontend behavior changes, start with:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change also affects backend or companion contracts, add the matching checks there too.\n", "1.0": "+++\ntitle = \"Frontend Overview\"\n+++\n\nThe frontend is a React and TypeScript application built with Vite. It is responsible for presenting Sambee's workflows clearly while respecting the backend and companion contracts behind them.\n\n## What the Frontend Owns\n\nThe browser app is responsible for:\n\n- routing users into the main product surfaces\n- rendering the file browser, viewer, and editing flows\n- managing browser-side state, selection, and navigation behavior\n- calling backend and companion-facing services through typed client code\n- applying theming, localization, and browser-side logging behavior\n\n## Main Frontend Areas\n\n| Area | Responsibility |\n|---|---|\n| `frontend/src/pages/` | page-level product flows such as the file browser |\n| `frontend/src/components/` | reusable UI building blocks |\n| `frontend/src/services/` | API clients, browser-to-companion integration, and other service helpers |\n| `frontend/src/i18n/` | typed translation resources and locale wiring |\n| `frontend/src/theme/` | theme configuration and theme-selection behavior |\n| `frontend/src/utils/` | formatting, registry, and other supporting utilities |\n\n## File Browser as the Core Surface\n\nThe file browser is the center of the main product UI.\n\n- it supports single-pane and dual-pane workflows\n- it keeps layout state and pane routing aligned with the URL\n- it coordinates selection, search, sorting, CRUD actions, viewer state, and keyboard behavior\n- it handles WebSocket-driven directory refresh behavior\n\nThat is why frontend changes in the file browser often have broader user impact than they first appear to.\n\nFor the main browsing surface itself, continue to [File Browser and Navigation Model](../file-browser-and-navigation-model/).\n\n## Frontend Contracts That Matter\n\n### Backend Contracts\n\nThe frontend depends on stable backend response shapes. When those change, update the corresponding types, service logic, and contract tests together.\n\n### Companion Contracts\n\nThe frontend is also the browser-side orchestrator for companion detection, pairing, local-drive access, and native-app editing initiation. That means browser-side state and desktop-side behavior are tightly linked even though they live in different projects.\n\n### Theming and Localization\n\nThe app treats theme behavior and localization as typed, explicit systems rather than loose UI sugar.\n\n- frontend copy should come from the translation system\n- locale handling and regional formatting are treated as product behavior\n- theme behavior is centralized instead of ad hoc component styling\n\n## Cross-Cutting Frontend Concerns\n\n- keyboard-first browsing and command surfaces\n- typed logging and backend tracing configuration\n- viewer behavior by file type and preview capability\n- responsive behavior, including mobile limitations and dual-pane desktop features\n\n## Rendering Hazards and Prevention Rules\n\nThis codebase has already hit at least one subtle React rendering failure where the app was logically correct but the browser still lost the first user click.\n\nThe useful lesson is that React rendering behavior, native event timing, portal trees, and third-party props can interact in ways that are easy to miss during normal component-level work.\n\n### Representative Failure Mode\n\nOne real frontend regression affected Markdown links inside the viewer.\n\n- links in the Markdown viewer ignored the first click when the viewer had been opened via keyboard\n- the second click worked\n- opening the viewer via mouse did not reproduce the problem\n\nThe root cause was not a single bad line. It was the combination of several implementation details:\n\n1. a global capture-phase `pointerdown` handler in `FileBrowser.tsx` updated keyboard-versus-pointer focus state synchronously\n2. React treated that update as a discrete-event flush and applied it between `pointerdown` and `click`\n3. the viewer shell was still expensive enough that the re-render cascaded through the portal-rendered viewer tree\n4. `react-markdown` override props included a `node` value that would have been dangerous to spread onto a native DOM anchor\n\nThe current code fixes that by deferring the focus-state update with `requestAnimationFrame`, memoizing the dynamic viewer shell, and stripping `node` out of the Markdown link override before spreading the remaining props.\n\n### Why This Class of Bug Matters\n\nThis kind of problem is easy to underestimate because:\n\n- it can be input-mode specific rather than globally reproducible\n- it may only appear when several otherwise-correct abstractions interact\n- the visible symptom can look like a browser bug or flaky click handling when the real cause is a mid-event re-render\n\nContributors should treat event timing and render isolation as architecture concerns, not just local component details.\n\n### Prevention Rules\n\n#### 1. Do Not Trigger Synchronous State Changes in Capture-Phase Pointer Handlers Unless Necessary\n\nCapture-phase `pointerdown` and `mousedown` handlers can run before the click sequence finishes. If they trigger state updates synchronously, React can re-render in the middle of the browser's interaction pipeline.\n\nWhen the state change is not required immediately, defer it past the current event cycle with `requestAnimationFrame`.\n\n#### 2. Keep Portal-Rendered Viewer Surfaces Render-Isolated\n\nViewer trees rendered through dialogs or other portals should not re-render just because an unrelated parent concern changed.\n\nIn practice this means:\n\n- memoize portal-rendered viewer shells when they are intended to be stable\n- be skeptical of parent state changes that can cascade into the viewer tree during active pointer interaction\n- review viewer wrappers such as `DynamicViewer` with the same care as the concrete viewer components themselves\n\n#### 3. Never Blindly Spread Third-Party Props onto Native DOM Elements\n\nLibraries such as `react-markdown` can inject props that are valid for the library layer but unsafe for direct DOM output.\n\nWhen overriding renderers:\n\n- explicitly destructure library-only props such as `node`\n- spread only the remaining DOM-safe props onto native elements\n- assume that leaking unknown props onto the interaction target can change browser behavior in ways that are hard to diagnose\n\n### Practical Audit Checks\n\nWhen debugging or reviewing similar issues, use targeted searches like these:\n\n```bash\ngrep -rn 'addEventListener.*capture' frontend/src/\ngrep -rn '\\.\\.\\.props' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/FileBrowser/DynamicViewer.tsx\n```\n\nThese are not exhaustive audits, but they are good first-pass checks for the specific failure pattern this codebase has already seen.\n\n## Go Deeper\n\n- [Theming System and Theme Selection](../theming-system-and-theme-selection/): theme configuration, built-in themes, persistence, and how the UI switches themes\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL routing, keyboard flows, and refresh behavior\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): central shortcut definitions, browser commands, quick-bar modes, and context-aware handlers\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): file-type registries, preview selection, and conversion-sensitive viewer behavior\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared frontend-facing rules for diagnostics, translatable UI copy, and locale behavior\n\n## Validation Expectations\n\nWhen frontend behavior changes, start with:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change also affects backend or companion contracts, add the matching checks there too.\n", "2.0": "+++\ntitle = \"Frontend Overview\"\n+++\n\nThe frontend is a React and TypeScript application built with Vite. It is responsible for presenting Sambee's workflows clearly while respecting the backend and companion contracts behind them.\n\n## What the Frontend Owns\n\nThe browser app is responsible for:\n\n- routing users into the main product surfaces\n- rendering the file browser, viewer, and editing flows\n- managing browser-side state, selection, and navigation behavior\n- calling backend and companion-facing services through typed client code\n- applying theming, localization, and browser-side logging behavior\n\n## Main Frontend Areas\n\n| Area | Responsibility |\n|---|---|\n| `frontend/src/pages/` | page-level product flows such as the file browser |\n| `frontend/src/components/` | reusable UI building blocks |\n| `frontend/src/services/` | API clients, browser-to-companion integration, and other service helpers |\n| `frontend/src/i18n/` | typed translation resources and locale wiring |\n| `frontend/src/theme/` | theme configuration and theme-selection behavior |\n| `frontend/src/utils/` | formatting, registry, and other supporting utilities |\n\n## File Browser as the Core Surface\n\nThe file browser is the center of the main product UI.\n\n- it supports single-pane and dual-pane workflows\n- it keeps layout state and pane routing aligned with the URL\n- it coordinates selection, search, sorting, CRUD actions, viewer state, and keyboard behavior\n- it handles WebSocket-driven directory refresh behavior\n\nThat is why frontend changes in the file browser often have broader user impact than they first appear to.\n\nFor the main browsing surface itself, continue to [File Browser and Navigation Model](../file-browser-and-navigation-model/).\n\n## Frontend Contracts That Matter\n\n### Backend Contracts\n\nThe frontend depends on stable backend response shapes. When those change, update the corresponding types, service logic, and contract tests together.\n\n### Companion Contracts\n\nThe frontend is also the browser-side orchestrator for companion detection, pairing, local-drive access, and native-app editing initiation. That means browser-side state and desktop-side behavior are tightly linked even though they live in different projects.\n\n### Theming and Localization\n\nThe app treats theme behavior and localization as typed, explicit systems rather than loose UI sugar.\n\n- frontend copy should come from the translation system\n- locale handling and regional formatting are treated as product behavior\n- theme behavior is centralized instead of ad hoc component styling\n\n## Cross-Cutting Frontend Concerns\n\n- keyboard-first browsing and command surfaces\n- typed logging and backend tracing configuration\n- viewer behavior by file type and preview capability\n- responsive behavior, including mobile limitations and dual-pane desktop features\n\n## Rendering Hazards and Prevention Rules\n\nThis codebase has already hit at least one subtle React rendering failure where the app was logically correct but the browser still lost the first user click.\n\nThe useful lesson is that React rendering behavior, native event timing, portal trees, and third-party props can interact in ways that are easy to miss during normal component-level work.\n\n### Representative Failure Mode\n\nOne real frontend regression affected Markdown links inside the viewer.\n\n- links in the Markdown viewer ignored the first click when the viewer had been opened via keyboard\n- the second click worked\n- opening the viewer via mouse did not reproduce the problem\n\nThe root cause was not a single bad line. It was the combination of several implementation details:\n\n1. a global capture-phase `pointerdown` handler in `FileBrowser.tsx` updated keyboard-versus-pointer focus state synchronously\n2. React treated that update as a discrete-event flush and applied it between `pointerdown` and `click`\n3. the viewer shell was still expensive enough that the re-render cascaded through the portal-rendered viewer tree\n4. `react-markdown` override props included a `node` value that would have been dangerous to spread onto a native DOM anchor\n\nThe current code fixes that by deferring the focus-state update with `requestAnimationFrame`, memoizing the dynamic viewer shell, and stripping `node` out of the Markdown link override before spreading the remaining props.\n\n### Why This Class of Bug Matters\n\nThis kind of problem is easy to underestimate because:\n\n- it can be input-mode specific rather than globally reproducible\n- it may only appear when several otherwise-correct abstractions interact\n- the visible symptom can look like a browser bug or flaky click handling when the real cause is a mid-event re-render\n\nContributors should treat event timing and render isolation as architecture concerns, not just local component details.\n\n### Prevention Rules\n\n#### 1. Do Not Trigger Synchronous State Changes in Capture-Phase Pointer Handlers Unless Necessary\n\nCapture-phase `pointerdown` and `mousedown` handlers can run before the click sequence finishes. If they trigger state updates synchronously, React can re-render in the middle of the browser's interaction pipeline.\n\nWhen the state change is not required immediately, defer it past the current event cycle with `requestAnimationFrame`.\n\n#### 2. Keep Portal-Rendered Viewer Surfaces Render-Isolated\n\nViewer trees rendered through dialogs or other portals should not re-render just because an unrelated parent concern changed.\n\nIn practice this means:\n\n- memoize portal-rendered viewer shells when they are intended to be stable\n- be skeptical of parent state changes that can cascade into the viewer tree during active pointer interaction\n- review viewer wrappers such as `DynamicViewer` with the same care as the concrete viewer components themselves\n\n#### 3. Never Blindly Spread Third-Party Props onto Native DOM Elements\n\nLibraries such as `react-markdown` can inject props that are valid for the library layer but unsafe for direct DOM output.\n\nWhen overriding renderers:\n\n- explicitly destructure library-only props such as `node`\n- spread only the remaining DOM-safe props onto native elements\n- assume that leaking unknown props onto the interaction target can change browser behavior in ways that are hard to diagnose\n\n### Practical Audit Checks\n\nWhen debugging or reviewing similar issues, use targeted searches like these:\n\n```bash\ngrep -rn 'addEventListener.*capture' frontend/src/\ngrep -rn '\\.\\.\\.props' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/Viewer/\ngrep -rn 'React\\.memo\\|memo(' frontend/src/components/FileBrowser/DynamicViewer.tsx\n```\n\nThese are not exhaustive audits, but they are good first-pass checks for the specific failure pattern this codebase has already seen.\n\n## Go Deeper\n\n- [Theming System and Theme Selection](../theming-system-and-theme-selection/): theme configuration, built-in themes, persistence, and how the UI switches themes\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL routing, keyboard flows, and refresh behavior\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): central shortcut definitions, browser commands, quick-bar modes, and context-aware handlers\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): file-type registries, preview selection, and conversion-sensitive viewer behavior\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared frontend-facing rules for diagnostics, translatable UI copy, and locale behavior\n\n## Validation Expectations\n\nWhen frontend behavior changes, start with:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change also affects backend or companion contracts, add the matching checks there too.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/frontend-architecture/theming-system-and-theme-selection", "parent_id": "section:developer-guide/frontend-architecture", "depth": 2, "kind": "page", "label": "theming-system-and-theme-selection", "title": "Theming System And Theme Selection", "path": "developer-guide/frontend-architecture/theming-system-and-theme-selection", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "branched", "source_version": "0.7", "diff_added": 42, "diff_removed": 5}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "branched", "source_version": "0.9", "diff_added": 49, "diff_removed": 263}}, "content_versions": {"0.7": "+++\ntitle = \"Theming System and Theme Selection\"\n+++\n\nSambee's theming system is centralized. Theme configuration, runtime state, persistence, and selection UI are all treated as one frontend subsystem.\n\nUse this page when you are changing palette behavior, adding a built-in theme, wiring a theme-aware component, or debugging why a selected theme is not applied consistently.\n\n## Main Pieces\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/theme/types.ts` | TypeScript theme interfaces and theme configuration shape |\n| `frontend/src/theme/themes.ts` | built-in theme definitions plus default-theme helpers |\n| `frontend/src/theme/ThemeContext.tsx` | runtime theme state, persistence, and theme switching |\n| `frontend/src/theme/index.ts` | public theme exports for the rest of the app |\n| `frontend/src/components/ThemeSelector.tsx` | theme-selection UI and dialog |\n| `frontend/src/components/themeSelectorStrings.ts` | localized strings and built-in-theme labels for the selector |\n\nThese pieces matter together. Theme behavior is not just a palette file or just a toolbar widget.\n\n## What the System Supports\n\nThe theme model currently supports:\n\n- built-in light and dark themes\n- persistent theme preferences\n- custom theme storage and runtime selection\n- theme-aware MUI palette generation\n- one shared provider that updates the app when the theme changes\n\n## Built-In Themes\n\nThe built-in themes live in `builtInThemes` in `frontend/src/theme/themes.ts`.\n\nCurrent built-ins include:\n\n- `sambee-light`: the default light branded theme\n- `sambee-dark`: the default dark branded theme\n\nThe helper functions contributors use most are:\n\n- `getDefaultTheme()`\n- `getDefaultTheme(\"light\")`\n- `getDefaultTheme(\"dark\")`\n- `getThemeById(id)`\n\nThe theme module also includes compile-time assertions around the default-theme indices so the expected built-in defaults cannot silently disappear.\n\n## Runtime Flow\n\nAt runtime, theme selection follows this path:\n\n1. the app renders inside `SambeeThemeProvider`\n2. the current theme ID is restored from persisted state when available\n3. built-in themes are resolved from code and combined with persisted custom themes\n4. `useSambeeTheme().setThemeById()` updates the active theme\n5. the selected theme is persisted\n6. the MUI theme instance updates and the UI re-renders\n\nThat is why a theme bug can look like a local component styling issue while actually being a context, persistence, or provider problem.\n\n## Theme Context Contract\n\n`useSambeeTheme()` is the main runtime entry point.\n\nContributors typically consume values such as:\n\n- `currentTheme`\n- `muiTheme`\n- `availableThemes`\n- `setThemeById`\n- `addCustomTheme`\n\nThe hook must be used inside `SambeeThemeProvider`. If you bypass that provider boundary, theme state becomes inconsistent immediately.\n\nRepresentative usage:\n\n```tsx\nimport { useSambeeTheme } from \"../theme\";\n\nfunction ThemeExample() {\n\tconst { currentTheme, setThemeById } = useSambeeTheme();\n\n\treturn (\n\t\t\u003cbutton onClick={() =\u003e setThemeById(\"sambee-dark\")}\u003e\n\t\t\tCurrent: {currentTheme.name}\n\t\t\u003c/button\u003e\n\t);\n}\n```\n\n## Theme Configuration Model\n\nThemes are expressed as typed configuration rather than ad hoc color overrides.\n\nThe palette surface includes areas such as:\n\n- `primary`\n- `secondary`\n- `background`\n- `text`\n- `action`\n\nCommon uses in the UI include:\n\n- directory emphasis and action colors from `primary`\n- page and surface backgrounds from `background`\n- readable foreground text from `text`\n- hover and selection states from `action`\n\nMaterial UI also derives additional palette values such as divider color when enough base information is present.\n\n## Built-In Theme Characteristics\n\nThe current built-ins intentionally align with Sambee's branding.\n\n### Sambee Light\n\n- ID: `sambee-light`\n- mode: light\n- branded golden primary palette\n- cream-toned background\n- dark secondary contrast surface\n\n### Sambee Dark\n\n- ID: `sambee-dark`\n- mode: dark\n- branded golden primary palette\n- dark background\n- light secondary contrast surface\n\nThe exact palette values live in `frontend/src/theme/themes.ts`. Keep the docs focused on architectural meaning rather than duplicating every color token when the code is already authoritative.\n\n## Theme Selector UI\n\nThe visible selection UI lives in `frontend/src/components/ThemeSelector.tsx`.\n\nThe selector:\n\n- opens a dialog listing available themes\n- shows a preview of theme colors\n- uses localized strings through `themeSelectorStrings.ts`\n- calls `setThemeById` when the user changes themes\n\nThe selector is already integrated into the file-browser toolbar, and the current preferences UI also consumes the same theme state.\n\n## Persistence Model\n\nTheme preferences are persisted in local storage.\n\nThe main keys are:\n\n- `theme-id-current`: the currently selected theme ID\n- `themes-builtin`: built-in themes as last synchronized from code\n- `themes-custom`: user-created custom themes\n\nThis matters for two reasons:\n\n- the selected theme survives reloads\n- built-in theme definitions can still be refreshed from code when the app updates\n\nThe system syncs built-in themes from code so users pick up reviewed built-in theme changes without losing their custom themes.\n\n## Custom Themes\n\nThe theme context supports custom themes in addition to the built-ins.\n\nThat means contributors should treat theme IDs, storage layout, and theme resolution as stable interfaces rather than temporary implementation details.\n\nWhen adding custom-theme features or editing persistence logic:\n\n- preserve separation between built-in and custom theme sets\n- keep the active theme valid even if a custom theme is removed\n- preserve a safe fallback to the default theme\n\nRepresentative pattern:\n\n```tsx\nimport { useSambeeTheme } from \"../theme\";\n\nfunction addExampleTheme() {\n\tconst { addCustomTheme } = useSambeeTheme();\n\n\taddCustomTheme({\n\t\tid: \"my-custom-theme\",\n\t\tname: \"My Custom Theme\",\n\t\tdescription: \"A unique theme\",\n\t\tmode: \"light\",\n\t\tprimary: { main: \"#ff6b6b\" },\n\t\tsecondary: { main: \"#4ecdc4\" },\n\t});\n}\n```\n\n## Theme Schema and Future Builder Support\n\n`frontend/src/theme/types.ts` also exports `THEME_SCHEMA`.\n\nThat schema is runtime-accessible metadata describing:\n\n- field types such as text, color, and select\n- labels and descriptions for UI\n- required versus optional fields\n- nested field definitions\n- select options such as `light` and `dark`\n\nIt exists so future theme-builder tooling can generate forms and validation from one typed source instead of re-encoding theme structure in multiple places.\n\n## Theme-Aware Component Rules\n\nWhen building UI components:\n\n- use the active MUI theme instead of hard-coded surface and text colors when the style belongs to the app theme\n- prefer `useTheme()` or the shared theme context rather than duplicating palette lookups manually\n- keep file-type icon colors and other intentionally non-theme registry colors separate from the app palette when they serve a different product purpose\n\nA theme-aware component typically reads from `theme.palette` and `theme.spacing` rather than introducing standalone constants.\n\n## Browser and PWA Integration\n\nThe theme system also updates the browser `theme-color` meta tag to match the selected theme's primary color.\n\nThat affects:\n\n- browser UI tinting on supported browsers\n- Android browser chrome behavior\n- installed PWA status-bar appearance\n\nIf a theme appears correct inside the app but wrong in browser chrome, check this integration path rather than only inspecting component styles.\n\n## Common Failure Modes\n\n- a component hard-codes colors that should come from the active theme\n- a new built-in theme is added without keeping default-theme helpers valid\n- theme state is read outside `SambeeThemeProvider`\n- a persistence change breaks fallback to the default theme\n- built-in theme updates and custom theme persistence start overwriting each other\n- contributors treat selector labels as static strings instead of localized UI copy\n\n## Validation Expectations\n\nWhen the theming system changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nPay particular attention to:\n\n- theme-provider tests under `frontend/src/theme/__tests__/`\n- built-in-theme and default-theme tests\n- `types.test.ts` coverage around `THEME_SCHEMA`\n- theme-selector tests under `frontend/src/components/__tests__/`\n- manual checks that text remains readable in both built-in themes\n\n## Where to Continue\n\n- [Frontend Overview](../frontend-overview/): broader browser-app structure and the place of theme behavior in the frontend\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): another shared frontend subsystem with central configuration and runtime binding\n- [Localization and Locale Behavior](../../cross-cutting-systems/localization-and-locale-behavior/): shared UI-system rules that often change alongside settings and preferences surfaces\n", "0.8": "+++\ntitle = \"Theming System and Theme Selection\"\n+++\n\nSambee's theming system is centralized. Theme configuration, runtime state, persistence, and selection UI are all treated as one frontend subsystem.\n\nUse this page when you are changing palette behavior, adding a built-in theme, wiring a theme-aware component, or debugging why a selected theme is not applied consistently.\n\n## Main Pieces\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/theme/types.ts` | TypeScript theme interfaces and theme configuration shape |\n| `frontend/src/theme/themes.ts` | built-in theme definitions plus default-theme helpers |\n| `frontend/src/theme/ThemeContext.tsx` | runtime theme state, persistence, and theme switching |\n| `frontend/src/theme/index.ts` | public theme exports for the rest of the app |\n| `frontend/src/components/ThemeSelector.tsx` | theme-selection UI and dialog |\n| `frontend/src/components/themeSelectorStrings.ts` | localized strings and built-in-theme labels for the selector |\n\nThese pieces matter together. Theme behavior is not just a palette file or just a toolbar widget.\n\n## What the System Supports\n\nThe theme model currently supports:\n\n- built-in light and dark themes\n- persistent theme preferences\n- custom theme storage and runtime selection\n- theme-aware MUI palette generation\n- one shared provider that updates the app when the theme changes\n\n## Built-In Themes\n\nThe built-in themes live in `builtInThemes` in `frontend/src/theme/themes.ts`.\n\nCurrent built-ins include:\n\n- `sambee-light`: the default light branded theme\n- `sambee-dark`: the default dark branded theme\n\nThe helper functions contributors use most are:\n\n- `getDefaultTheme()`\n- `getDefaultTheme(\"light\")`\n- `getDefaultTheme(\"dark\")`\n- `getThemeById(id)`\n\nThe theme module also includes compile-time assertions around the default-theme indices so the expected built-in defaults cannot silently disappear.\n\n## Runtime Flow\n\nAt runtime, theme selection follows this path:\n\n1. the app renders inside `SambeeThemeProvider`\n2. the current theme ID is restored from persisted state when available\n3. built-in themes are resolved from code and combined with persisted custom themes\n4. `useSambeeTheme().setThemeById()` updates the active theme\n5. the selected theme is persisted\n6. the MUI theme instance updates and the UI re-renders\n\nThat is why a theme bug can look like a local component styling issue while actually being a context, persistence, or provider problem.\n\n## Theme Context Contract\n\n`useSambeeTheme()` is the main runtime entry point.\n\nContributors typically consume values such as:\n\n- `currentTheme`\n- `muiTheme`\n- `availableThemes`\n- `setThemeById`\n- `addCustomTheme`\n\nThe hook must be used inside `SambeeThemeProvider`. If you bypass that provider boundary, theme state becomes inconsistent immediately.\n\nRepresentative usage:\n\n```tsx\nimport { useSambeeTheme } from \"../theme\";\n\nfunction ThemeExample() {\n\tconst { currentTheme, setThemeById } = useSambeeTheme();\n\n\treturn (\n\t\t\u003cbutton onClick={() =\u003e setThemeById(\"sambee-dark\")}\u003e\n\t\t\tCurrent: {currentTheme.name}\n\t\t\u003c/button\u003e\n\t);\n}\n```\n\n## Theme Configuration Model\n\nThemes are expressed as typed configuration rather than ad hoc color overrides.\n\nThe palette surface includes areas such as:\n\n- `primary`\n- `secondary`\n- `background`\n- `text`\n- `action`\n\nCommon uses in the UI include:\n\n- directory emphasis and action colors from `primary`\n- page and surface backgrounds from `background`\n- readable foreground text from `text`\n- hover and selection states from `action`\n\nMaterial UI also derives additional palette values such as divider color when enough base information is present.\n\n## Built-In Theme Characteristics\n\nThe current built-ins intentionally align with Sambee's branding.\n\n### Sambee Light\n\n- ID: `sambee-light`\n- mode: light\n- branded golden primary palette\n- cream-toned background\n- dark secondary contrast surface\n\n### Sambee Dark\n\n- ID: `sambee-dark`\n- mode: dark\n- branded golden primary palette\n- dark background\n- light secondary contrast surface\n\nThe exact palette values live in `frontend/src/theme/themes.ts`. Keep the docs focused on architectural meaning rather than duplicating every color token when the code is already authoritative.\n\n## Theme Selector UI\n\nThe visible selection UI lives in `frontend/src/components/ThemeSelector.tsx`.\n\nThe selector:\n\n- opens a dialog listing available themes\n- shows a preview of theme colors\n- uses localized strings through `themeSelectorStrings.ts`\n- calls `setThemeById` when the user changes themes\n\nThe selector is already integrated into the file-browser toolbar, and the current preferences UI also consumes the same theme state.\n\n## Persistence Model\n\nTheme preferences are persisted in local storage.\n\nThe main keys are:\n\n- `theme-id-current`: the currently selected theme ID\n- `themes-builtin`: built-in themes as last synchronized from code\n- `themes-custom`: user-created custom themes\n\nThis matters for two reasons:\n\n- the selected theme survives reloads\n- built-in theme definitions can still be refreshed from code when the app updates\n\nThe system syncs built-in themes from code so users pick up reviewed built-in theme changes without losing their custom themes.\n\n## Custom Themes\n\nThe theme context supports custom themes in addition to the built-ins.\n\nThat means contributors should treat theme IDs, storage layout, and theme resolution as stable interfaces rather than temporary implementation details.\n\nWhen adding custom-theme features or editing persistence logic:\n\n- preserve separation between built-in and custom theme sets\n- keep the active theme valid even if a custom theme is removed\n- preserve a safe fallback to the default theme\n\nRepresentative pattern:\n\n```tsx\nimport { useSambeeTheme } from \"../theme\";\n\nfunction addExampleTheme() {\n\tconst { addCustomTheme } = useSambeeTheme();\n\n\taddCustomTheme({\n\t\tid: \"my-custom-theme\",\n\t\tname: \"My Custom Theme\",\n\t\tdescription: \"A unique theme\",\n\t\tmode: \"light\",\n\t\tprimary: { main: \"#ff6b6b\" },\n\t\tsecondary: { main: \"#4ecdc4\" },\n\t});\n}\n```\n\n## Theme Schema and Future Builder Support\n\n`frontend/src/theme/types.ts` also exports `THEME_SCHEMA`.\n\nThat schema is runtime-accessible metadata describing:\n\n- field types such as text, color, and select\n- labels and descriptions for UI\n- required versus optional fields\n- nested field definitions\n- select options such as `light` and `dark`\n\nIt exists so future theme-builder tooling can generate forms and validation from one typed source instead of re-encoding theme structure in multiple places.\n\n## Theme-Aware Component Rules\n\nWhen building UI components:\n\n- use the active MUI theme instead of hard-coded surface and text colors when the style belongs to the app theme\n- prefer `useTheme()` or the shared theme context rather than duplicating palette lookups manually\n- keep file-type icon colors and other intentionally non-theme registry colors separate from the app palette when they serve a different product purpose\n\nA theme-aware component typically reads from `theme.palette` and `theme.spacing` rather than introducing standalone constants.\n\n## Browser and PWA Integration\n\nThe theme system also updates the browser `theme-color` meta tag to match the selected theme's primary color.\n\nThat affects:\n\n- browser UI tinting on supported browsers\n- Android browser chrome behavior\n- installed PWA status-bar appearance\n\nIf a theme appears correct inside the app but wrong in browser chrome, check this integration path rather than only inspecting component styles.\n\n## Common Failure Modes\n\n- a component hard-codes colors that should come from the active theme\n- a new built-in theme is added without keeping default-theme helpers valid\n- theme state is read outside `SambeeThemeProvider`\n- a persistence change breaks fallback to the default theme\n- built-in theme updates and custom theme persistence start overwriting each other\n- contributors treat selector labels as static strings instead of localized UI copy\n\n## Validation Expectations\n\nWhen the theming system changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nPay particular attention to:\n\n- theme-provider tests under `frontend/src/theme/__tests__/`\n- built-in-theme and default-theme tests\n- `types.test.ts` coverage around `THEME_SCHEMA`\n- theme-selector tests under `frontend/src/components/__tests__/`\n- manual checks that text remains readable in both built-in themes\n\n## Where to Continue\n\n- [Frontend Overview](../frontend-overview/): broader browser-app structure and the place of theme behavior in the frontend\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): another shared frontend subsystem with central configuration and runtime binding\n- [Localization and Locale Behavior](../../cross-cutting-systems/localization-and-locale-behavior/): shared UI-system rules that often change alongside settings and preferences surfaces\n", "0.9": "+++\ntitle = \"Theming System and Theme Selection\"\n+++\n\nSambee's theming system is centralized. Theme configuration, runtime state, persistence, and selection UI are all treated as one frontend subsystem.\n\nUse this page when you are changing palette behavior, adding a built-in theme, wiring a theme-aware component, or debugging why a selected theme is not applied consistently.\n\n## Main Pieces\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/theme/types.ts` | TypeScript theme interfaces and theme configuration shape |\n| `frontend/src/theme/themes.ts` | built-in theme definitions plus default-theme helpers |\n| `frontend/src/theme/ThemeContext.tsx` | runtime theme state, persistence, and theme switching |\n| `frontend/src/theme/index.ts` | public theme exports for the rest of the app |\n| `frontend/src/components/ThemeSelector.tsx` | theme-selection UI and dialog |\n| `frontend/src/components/themeSelectorStrings.ts` | localized strings and built-in-theme labels for the selector |\n\nThese pieces matter together. Theme behavior is not just a palette file or just a toolbar widget.\n\n## What the System Supports\n\nThe theme model currently supports:\n\n- built-in light and dark themes\n- persistent theme preferences\n- custom theme storage and runtime selection\n- theme-aware MUI palette generation\n- one shared provider that updates the app when the theme changes\n\n## Built-In Themes\n\nThe built-in themes live in `builtInThemes` in `frontend/src/theme/themes.ts`.\n\nCurrent built-ins include:\n\n- `sambee-light`: the default light branded theme\n- `sambee-dark`: the default dark branded theme\n\nThe helper functions contributors use most are:\n\n- `getDefaultTheme()`\n- `getDefaultTheme(\"light\")`\n- `getDefaultTheme(\"dark\")`\n- `getThemeById(id)`\n\nThe theme module also includes compile-time assertions around the default-theme indices so the expected built-in defaults cannot silently disappear.\n\n## Runtime Flow\n\nAt runtime, theme selection follows this path:\n\n1. the app renders inside `SambeeThemeProvider`\n2. the current theme ID is restored from persisted state when available\n3. built-in themes are resolved from code and combined with persisted custom themes\n4. `useSambeeTheme().setThemeById()` updates the active theme\n5. the selected theme is persisted\n6. the MUI theme instance updates and the UI re-renders\n\nThat is why a theme bug can look like a local component styling issue while actually being a context, persistence, or provider problem.\n\n## Theme Context Contract\n\n`useSambeeTheme()` is the main runtime entry point.\n\nContributors typically consume values such as:\n\n- `currentTheme`\n- `muiTheme`\n- `availableThemes`\n- `setThemeById`\n- `addCustomTheme`\n\nThe hook must be used inside `SambeeThemeProvider`. If you bypass that provider boundary, theme state becomes inconsistent immediately.\n\nRepresentative usage:\n\n```tsx\nimport { useSambeeTheme } from \"../theme\";\n\nfunction ThemeExample() {\n\tconst { currentTheme, setThemeById } = useSambeeTheme();\n\n\treturn (\n\t\t\u003cbutton onClick={() =\u003e setThemeById(\"sambee-dark\")}\u003e\n\t\t\tCurrent: {currentTheme.name}\n\t\t\u003c/button\u003e\n\t);\n}\n```\n\n## Theme Configuration Model\n\nThemes are expressed as typed configuration rather than ad hoc color overrides.\n\nThe palette surface includes areas such as:\n\n- `primary`\n- `secondary`\n- `background`\n- `text`\n- `action`\n\nCommon uses in the UI include:\n\n- default primary controls and selected navigation from `primary.main`\n- high-emphasis dark-mode states from `primary.light`\n- light-mode pressed and contrast-sensitive controls from `primary.dark`\n- page and standard application surfaces from `background.default`\n- readable foreground text from `text`\n- selection fills from `action.selected`\n\nMaterial UI also derives additional palette values such as divider color when enough base information is present.\n\n### Surface Policy\n\n`background.default` is the standard application surface. Use it for pages, standard dialogs, settings, and compact controls.\n\n`background.paper` remains populated at runtime because Material UI expects the token. Sambee normalizes it to `background.default`; application components should not select it as a separate surface.\n\nThe shared settings form surface is a deliberate derived exception: it darkens the default surface by 4% in light mode and lightens it by 8% in dark mode. Inside a dark dialog, it uses a 12% black mix of the actual dialog paper surface, preserving a warm but recessed form area; its outlined fields inherit the dialog paper surface to remain visually distinct from the surrounding form layer. Application chrome is another exception: light-mode AppBar and StatusBar use the primary color, while dark-mode chrome uses the shared opaque brown `#382c0a`. Standard Material UI Dialog papers and popup menus use that same opaque dark-mode color, preventing the backdrop from showing through. Fullscreen viewers retain their dedicated viewer surfaces. Dark dialog backdrops use a high-opacity neutral composite of `background.default`, preventing nested dialogs from tinting the surface behind them. Dialogs do not add an elevation shadow because the modal backdrop provides their separation. Menu selection, hover, and keyboard focus use `action.selected`.\n\nStandard Material UI Alerts use the theme's `components.alert` semantic colors for their info, success, warning, and error backgrounds, text, and icons. Apply alert semantics through the shared theme rather than per-component overrides.\n\n### Primary Palette Roles\n\n`primary.main` is the default primary control color. It should not be the brightest available shade in a dark theme, because Material UI applies it to contained buttons, radios, selected icons, and many other default controls.\n\nUse `primary.light` for brighter dark-mode hover and high-emphasis states. Use `primary.dark` for pressed and contrast-sensitive light-mode controls. Do not swap `main` and `dark` between modes: Material UI treats `dark` as the darker interaction shade.\n\nThe built-in dark theme uses a subdued golden `main`, a brighter golden `light`, and a darker pressed `dark` shade. The exact values live in `frontend/src/theme/themes.ts`.\n\n### Foreground Color Policy\n\nStandard application UI uses two base foreground roles:\n\n- `text.primary` is high-emphasis text: headings, selected or active labels, form values, selectable menu choices, file names, and information required to complete the current task.\n- `text.secondary` is the default supporting layer: descriptions, metadata, timestamps, helper copy, captions, inactive navigation icons, and other text that should be readable without competing with the task.\n\nThe built-in dark theme intentionally makes `text.secondary` a muted version of the warm primary text. This reduces glare during extended use while preserving a clear emphasis hierarchy. Use `text.disabled` for non-interactive content and dedicated palette roles such as `statusBar.textSecondary`, alert colors, and viewer toolbar colors when the surface has its own semantic contract.\n\nFor Material UI `Typography`, apply dotted palette roles through `sx`, for example `sx={{ color: \"text.secondary\" }}`. In this application's Material UI v9 configuration, `color=\"text.secondary\"` does not emit a palette color rule, so the element falls back to inherited text.\n\nIcons should inherit the role of their associated text. Use `currentColor` for adaptable inline SVG illustrations. Brand assets, file-type registry icons, document rendering, syntax highlighting, and semantic alerts are deliberate exceptions: their colors convey identity, content type, or state and should remain separately named rather than being forced into the general text palette.\n\n## Built-In Theme Characteristics\n\nThe current built-ins intentionally align with Sambee's branding.\n\n### Sambee Light\n\n- ID: `sambee-light`\n- mode: light\n- branded golden primary palette\n- cream-toned background\n- dark secondary contrast surface\n\n### Sambee Dark\n\n- ID: `sambee-dark`\n- mode: dark\n- branded golden primary palette\n- dark background\n- light secondary contrast surface\n\nThe exact palette values live in `frontend/src/theme/themes.ts`. Keep the docs focused on architectural meaning rather than duplicating every color token when the code is already authoritative.\n\n## Theme Selector UI\n\nThe visible selection UI lives in `frontend/src/components/ThemeSelector.tsx`.\n\nThe selector:\n\n- opens a dialog listing available themes\n- shows a preview of theme colors\n- uses localized strings through `themeSelectorStrings.ts`\n- calls `setThemeById` when the user changes themes\n\nThe selector is already integrated into the file-browser toolbar, and the current preferences UI also consumes the same theme state.\n\n## Persistence Model\n\nTheme preferences are persisted in local storage.\n\nThe main keys are:\n\n- `theme-id-current`: the currently selected theme ID\n- `themes-custom`: user-created custom themes\n\nThis matters for two reasons:\n\n- the selected theme survives reloads\n- built-in theme definitions can still be refreshed from code when the app updates\n\nThe system syncs built-in themes from code so users pick up reviewed built-in theme changes without losing their custom themes.\n\n## Custom Themes\n\nThe theme context supports custom themes in addition to the built-ins.\n\nThat means contributors should treat theme IDs, storage layout, and theme resolution as stable interfaces rather than temporary implementation details.\n\nWhen adding custom-theme features or editing persistence logic:\n\n- preserve separation between built-in and custom theme sets\n- keep the active theme valid even if a custom theme is removed\n- preserve a safe fallback to the default theme\n\nRepresentative pattern:\n\n```tsx\nimport { useSambeeTheme } from \"../theme\";\n\nfunction addExampleTheme() {\n\tconst { addCustomTheme } = useSambeeTheme();\n\n\taddCustomTheme({\n\t\tid: \"my-custom-theme\",\n\t\tname: \"My Custom Theme\",\n\t\tdescription: \"A unique theme\",\n\t\tmode: \"light\",\n\t\tprimary: { main: \"#ff6b6b\" },\n\t});\n}\n```\n\n## Theme Schema and Future Builder Support\n\n`frontend/src/theme/types.ts` also exports `THEME_SCHEMA`.\n\nThat schema is runtime-accessible metadata describing:\n\n- field types such as text, color, and select\n- labels and descriptions for UI\n- required versus optional fields\n- nested field definitions\n- select options such as `light` and `dark`\n\nNew custom themes should provide `primary.main` and may provide the other primary shades, background, text, and selection colors. The runtime resolver supplies stable mode-aware defaults for omitted optional fields so existing minimally configured themes remain valid.\n\n`action.focus`, `components.appBar`, and `components.statusBar` are honored for already persisted themes but are intentionally not exposed by `THEME_SCHEMA`. New themes derive those values from the palette contract.\n\nIt exists so future theme-builder tooling can generate forms and validation from one typed source instead of re-encoding theme structure in multiple places.\n\n## Theme-Aware Component Rules\n\nWhen building UI components:\n\n- use the active MUI theme instead of hard-coded surface and text colors when the style belongs to the app theme\n- use `text.primary` and `text.secondary` to establish normal UI hierarchy; do not recreate muted text with local opacity values\n- prefer `useTheme()` or the shared theme context rather than duplicating palette lookups manually\n- derive viewer toolbar borders, muted labels, disabled controls, and subtle fills from the configured toolbar text color\n- keep file-type icon colors and other intentionally non-theme registry colors separate from the app palette when they serve a different product purpose\n\nA theme-aware component typically reads from `theme.palette` and `theme.spacing` rather than introducing standalone constants.\n\n## Browser and PWA Integration\n\nThe theme system also updates the browser `theme-color` meta tag to match the selected theme's primary color.\n\nThat affects:\n\n- browser UI tinting on supported browsers\n- Android browser chrome behavior\n- installed PWA status-bar appearance\n\nIf a theme appears correct inside the app but wrong in browser chrome, check this integration path rather than only inspecting component styles.\n\n## Common Failure Modes\n\n- a component hard-codes colors that should come from the active theme\n- a new built-in theme is added without keeping default-theme helpers valid\n- theme state is read outside `SambeeThemeProvider`\n- a persistence change breaks fallback to the default theme\n- built-in theme updates and custom theme persistence start overwriting each other\n- contributors treat selector labels as static strings instead of localized UI copy\n\n## Validation Expectations\n\nWhen the theming system changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nPay particular attention to:\n\n- theme-provider tests under `frontend/src/theme/__tests__/`\n- built-in-theme and default-theme tests\n- `types.test.ts` coverage around `THEME_SCHEMA`\n- theme-selector tests under `frontend/src/components/__tests__/`\n- manual checks that text remains readable in both built-in themes\n\n## Where to Continue\n\n- [Frontend Overview](../frontend-overview/): broader browser-app structure and the place of theme behavior in the frontend\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): another shared frontend subsystem with central configuration and runtime binding\n- [Localization and Locale Behavior](../../cross-cutting-systems/localization-and-locale-behavior/): shared UI-system rules that often change alongside settings and preferences surfaces\n", "1.0": "+++\ntitle = \"Theming System and Theme Selection\"\n+++\n\nSambee's theming system is centralized. Theme configuration, runtime state, persistence, and selection UI are all treated as one frontend subsystem.\n\nUse this page when you are changing palette behavior, adding a built-in theme, wiring a theme-aware component, or debugging why a selected theme is not applied consistently.\n\n## Main Pieces\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/theme/types.ts` | TypeScript theme interfaces and theme configuration shape |\n| `frontend/src/theme/themes.ts` | built-in theme definitions plus default-theme helpers |\n| `frontend/src/theme/ThemeContext.tsx` | runtime theme state, persistence, and theme switching |\n| `frontend/src/theme/index.ts` | public theme exports for the rest of the app |\n| `frontend/src/components/ThemeSelector.tsx` | theme-selection UI and dialog |\n| `frontend/src/components/themeSelectorStrings.ts` | localized strings and built-in-theme labels for the selector |\n\nThese pieces matter together. Theme behavior is not just a palette file or just a toolbar widget.\n\n## What the System Supports\n\nThe theme model currently supports:\n\n- built-in light and dark themes\n- persistent theme preferences\n- custom theme storage and runtime selection\n- theme-aware MUI palette generation\n- one shared provider that updates the app when the theme changes\n\n## Built-In Themes\n\nThe built-in themes live in `builtInThemes` in `frontend/src/theme/themes.ts`.\n\nCurrent built-ins include:\n\n- `sambee-light`: the default light branded theme\n- `sambee-dark`: the default dark branded theme\n\nThe helper functions contributors use most are:\n\n- `getDefaultTheme()`\n- `getDefaultTheme(\"light\")`\n- `getDefaultTheme(\"dark\")`\n- `getThemeById(id)`\n\nThe theme module also includes compile-time assertions around the default-theme indices so the expected built-in defaults cannot silently disappear.\n\n## Runtime Flow\n\nAt runtime, theme selection follows this path:\n\n1. the app renders inside `SambeeThemeProvider`\n2. the current theme ID is restored from persisted state when available\n3. built-in themes are resolved from code and combined with persisted custom themes\n4. `useSambeeTheme().setThemeById()` updates the active theme\n5. the selected theme is persisted\n6. the MUI theme instance updates and the UI re-renders\n\nThat is why a theme bug can look like a local component styling issue while actually being a context, persistence, or provider problem.\n\n## Theme Context Contract\n\n`useSambeeTheme()` is the main runtime entry point.\n\nContributors typically consume values such as:\n\n- `currentTheme`\n- `muiTheme`\n- `availableThemes`\n- `setThemeById`\n- `addCustomTheme`\n\nThe hook must be used inside `SambeeThemeProvider`. If you bypass that provider boundary, theme state becomes inconsistent immediately.\n\nRepresentative usage:\n\n```tsx\nimport { useSambeeTheme } from \"../theme\";\n\nfunction ThemeExample() {\n\tconst { currentTheme, setThemeById } = useSambeeTheme();\n\n\treturn (\n\t\t\u003cbutton onClick={() =\u003e setThemeById(\"sambee-dark\")}\u003e\n\t\t\tCurrent: {currentTheme.name}\n\t\t\u003c/button\u003e\n\t);\n}\n```\n\n## Theme Configuration Model\n\nThemes are expressed as typed configuration rather than ad hoc color overrides.\n\nThe palette surface includes areas such as:\n\n- `primary`\n- `secondary`\n- `background`\n- `text`\n- `action`\n\nCommon uses in the UI include:\n\n- default primary controls and selected navigation from `primary.main`\n- high-emphasis dark-mode states from `primary.light`\n- light-mode pressed and contrast-sensitive controls from `primary.dark`\n- page and standard application surfaces from `background.default`\n- readable foreground text from `text`\n- selection fills from `action.selected`\n\nMaterial UI also derives additional palette values such as divider color when enough base information is present.\n\n### Surface Policy\n\n`background.default` is the standard application surface. Use it for pages, standard dialogs, settings, and compact controls.\n\n`background.paper` remains populated at runtime because Material UI expects the token. Sambee normalizes it to `background.default`; application components should not select it as a separate surface.\n\nThe shared settings form surface is a deliberate derived exception: it darkens the default surface by 4% in light mode and lightens it by 8% in dark mode. Inside a dark dialog, it uses a 12% black mix of the actual dialog paper surface, preserving a warm but recessed form area; its outlined fields inherit the dialog paper surface to remain visually distinct from the surrounding form layer. Application chrome is another exception: light-mode AppBar and StatusBar use the primary color, while dark-mode chrome uses the shared opaque brown `#382c0a`. Standard Material UI Dialog papers and popup menus use that same opaque dark-mode color, preventing the backdrop from showing through. Fullscreen viewers retain their dedicated viewer surfaces. Dark dialog backdrops use a high-opacity neutral composite of `background.default`, preventing nested dialogs from tinting the surface behind them. Dialogs do not add an elevation shadow because the modal backdrop provides their separation. Menu selection, hover, and keyboard focus use `action.selected`.\n\nStandard Material UI Alerts use the theme's `components.alert` semantic colors for their info, success, warning, and error backgrounds, text, and icons. Apply alert semantics through the shared theme rather than per-component overrides.\n\n### Primary Palette Roles\n\n`primary.main` is the default primary control color. It should not be the brightest available shade in a dark theme, because Material UI applies it to contained buttons, radios, selected icons, and many other default controls.\n\nUse `primary.light` for brighter dark-mode hover and high-emphasis states. Use `primary.dark` for pressed and contrast-sensitive light-mode controls. Do not swap `main` and `dark` between modes: Material UI treats `dark` as the darker interaction shade.\n\nThe built-in dark theme uses a subdued golden `main`, a brighter golden `light`, and a darker pressed `dark` shade. The exact values live in `frontend/src/theme/themes.ts`.\n\n### Foreground Color Policy\n\nStandard application UI uses two base foreground roles:\n\n- `text.primary` is high-emphasis text: headings, selected or active labels, form values, selectable menu choices, file names, and information required to complete the current task.\n- `text.secondary` is the default supporting layer: descriptions, metadata, timestamps, helper copy, captions, inactive navigation icons, and other text that should be readable without competing with the task.\n\nThe built-in dark theme intentionally makes `text.secondary` a muted version of the warm primary text. This reduces glare during extended use while preserving a clear emphasis hierarchy. Use `text.disabled` for non-interactive content and dedicated palette roles such as `statusBar.textSecondary`, alert colors, and viewer toolbar colors when the surface has its own semantic contract.\n\nFor Material UI `Typography`, apply dotted palette roles through `sx`, for example `sx={{ color: \"text.secondary\" }}`. In this application's Material UI v9 configuration, `color=\"text.secondary\"` does not emit a palette color rule, so the element falls back to inherited text.\n\nIcons should inherit the role of their associated text. Use `currentColor` for adaptable inline SVG illustrations. Brand assets, file-type registry icons, document rendering, syntax highlighting, and semantic alerts are deliberate exceptions: their colors convey identity, content type, or state and should remain separately named rather than being forced into the general text palette.\n\n## Built-In Theme Characteristics\n\nThe current built-ins intentionally align with Sambee's branding.\n\n### Sambee Light\n\n- ID: `sambee-light`\n- mode: light\n- branded golden primary palette\n- cream-toned background\n- dark secondary contrast surface\n\n### Sambee Dark\n\n- ID: `sambee-dark`\n- mode: dark\n- branded golden primary palette\n- dark background\n- light secondary contrast surface\n\nThe exact palette values live in `frontend/src/theme/themes.ts`. Keep the docs focused on architectural meaning rather than duplicating every color token when the code is already authoritative.\n\n## Theme Selector UI\n\nThe visible selection UI lives in `frontend/src/components/ThemeSelector.tsx`.\n\nThe selector:\n\n- opens a dialog listing available themes\n- shows a preview of theme colors\n- uses localized strings through `themeSelectorStrings.ts`\n- calls `setThemeById` when the user changes themes\n\nThe selector is already integrated into the file-browser toolbar, and the current preferences UI also consumes the same theme state.\n\n## Persistence Model\n\nTheme preferences are persisted in local storage.\n\nThe main keys are:\n\n- `theme-id-current`: the currently selected theme ID\n- `themes-custom`: user-created custom themes\n\nThis matters for two reasons:\n\n- the selected theme survives reloads\n- built-in theme definitions can still be refreshed from code when the app updates\n\nThe system syncs built-in themes from code so users pick up reviewed built-in theme changes without losing their custom themes.\n\n## Custom Themes\n\nThe theme context supports custom themes in addition to the built-ins.\n\nThat means contributors should treat theme IDs, storage layout, and theme resolution as stable interfaces rather than temporary implementation details.\n\nWhen adding custom-theme features or editing persistence logic:\n\n- preserve separation between built-in and custom theme sets\n- keep the active theme valid even if a custom theme is removed\n- preserve a safe fallback to the default theme\n\nRepresentative pattern:\n\n```tsx\nimport { useSambeeTheme } from \"../theme\";\n\nfunction addExampleTheme() {\n\tconst { addCustomTheme } = useSambeeTheme();\n\n\taddCustomTheme({\n\t\tid: \"my-custom-theme\",\n\t\tname: \"My Custom Theme\",\n\t\tdescription: \"A unique theme\",\n\t\tmode: \"light\",\n\t\tprimary: { main: \"#ff6b6b\" },\n\t});\n}\n```\n\n## Theme Schema and Future Builder Support\n\n`frontend/src/theme/types.ts` also exports `THEME_SCHEMA`.\n\nThat schema is runtime-accessible metadata describing:\n\n- field types such as text, color, and select\n- labels and descriptions for UI\n- required versus optional fields\n- nested field definitions\n- select options such as `light` and `dark`\n\nNew custom themes should provide `primary.main` and may provide the other primary shades, background, text, and selection colors. The runtime resolver supplies stable mode-aware defaults for omitted optional fields so existing minimally configured themes remain valid.\n\n`action.focus`, `components.appBar`, and `components.statusBar` are honored for already persisted themes but are intentionally not exposed by `THEME_SCHEMA`. New themes derive those values from the palette contract.\n\nIt exists so future theme-builder tooling can generate forms and validation from one typed source instead of re-encoding theme structure in multiple places.\n\n## Theme-Aware Component Rules\n\nWhen building UI components:\n\n- use the active MUI theme instead of hard-coded surface and text colors when the style belongs to the app theme\n- use `text.primary` and `text.secondary` to establish normal UI hierarchy; do not recreate muted text with local opacity values\n- prefer `useTheme()` or the shared theme context rather than duplicating palette lookups manually\n- derive viewer toolbar borders, muted labels, disabled controls, and subtle fills from the configured toolbar text color\n- keep file-type icon colors and other intentionally non-theme registry colors separate from the app palette when they serve a different product purpose\n\nA theme-aware component typically reads from `theme.palette` and `theme.spacing` rather than introducing standalone constants.\n\n## Browser and PWA Integration\n\nThe theme system also updates the browser `theme-color` meta tag to match the selected theme's primary color.\n\nThat affects:\n\n- browser UI tinting on supported browsers\n- Android browser chrome behavior\n- installed PWA status-bar appearance\n\nIf a theme appears correct inside the app but wrong in browser chrome, check this integration path rather than only inspecting component styles.\n\n## Common Failure Modes\n\n- a component hard-codes colors that should come from the active theme\n- a new built-in theme is added without keeping default-theme helpers valid\n- theme state is read outside `SambeeThemeProvider`\n- a persistence change breaks fallback to the default theme\n- built-in theme updates and custom theme persistence start overwriting each other\n- contributors treat selector labels as static strings instead of localized UI copy\n\n## Validation Expectations\n\nWhen the theming system changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nPay particular attention to:\n\n- theme-provider tests under `frontend/src/theme/__tests__/`\n- built-in-theme and default-theme tests\n- `types.test.ts` coverage around `THEME_SCHEMA`\n- theme-selector tests under `frontend/src/components/__tests__/`\n- manual checks that text remains readable in both built-in themes\n\n## Where to Continue\n\n- [Frontend Overview](../frontend-overview/): broader browser-app structure and the place of theme behavior in the frontend\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): another shared frontend subsystem with central configuration and runtime binding\n- [Localization and Locale Behavior](../../cross-cutting-systems/localization-and-locale-behavior/): shared UI-system rules that often change alongside settings and preferences surfaces\n", "2.0": "+++\ntitle = \"Theming System and Theme Selection\"\n+++\n\nSambee has two built-in themes (`sambee-light` and `sambee-dark`), user-owned themes, and administrator-managed site themes. Built-in IDs stay stable across upgrades, so updating their palettes doesn't change anyone's selection.\n\n## Theme Data\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/theme/types.ts` | Palette types and editor field labels |\n| `frontend/src/theme/themes.ts` | Built-in definitions with stable IDs |\n| `frontend/src/theme/themeDefinition.ts` | Editable color catalog, hex checks, and versioned import/export |\n| `frontend/src/theme/resolveSyntaxTheme.ts` | Non-mutating legacy syntax defaults and strict supplied-palette validation |\n| `frontend/src/theme/syntaxStyles.ts` | Shared token classes and locally inherited syntax variables |\n| `frontend/src/theme/palette.ts` | Shared effective palette for the app |\n| `frontend/src/theme/viewerStyles.ts` | Viewer and Markdown document surfaces |\n| `frontend/src/theme/ThemeContext.tsx` | Registry refresh and Material UI theme |\n| `frontend/src/pages/PreferencesSettings.tsx` | Selection grid and selected-theme actions |\n| `frontend/src/components/Settings/ThemeEditorDialog.tsx` | Responsive theme editor |\n| `backend/app/api/themes.py` | Validated theme operations and site default |\n\nEach editable theme has its own server row with a globally unique ID, scope, owner (for user themes), and version. Built-in definitions remain in frontend code. A new theme ID is assigned by the server; an ID in an imported file does not claim or replace a stored theme.\n\nColors use `#RRGGBB` or `#RRGGBBAA`; the server normalizes valid hex to uppercase. The role catalog includes primary, backgrounds, text, selection, links, viewer surfaces, Markdown document surfaces, syntax, search highlights, and alerts. File-type icons aren't theme roles. Derived colors such as scrollbar shades, focus rings, and `background.paper` compatibility aren't editor fields. Keyboard focus rings follow the theme's primary text color: 57% opacity in light mode and 94% in dark mode. Changing that text color changes the focus color too, including in copied themes; legacy saved focus colors are ignored. Choose primary text that remains readable against the theme's surfaces.\n\nEvery existing editable role remains required. The additive `components.syntax` group has eight roles: `keyword`, `string`, `number`, `comment`, `type`, `function`, `operator`, and `punctuation`. If the entire group is absent from a stored definition or version-1 import, the frontend resolves the matching built-in light/dark palette without mutating or saving the original. A supplied group must contain exactly all eight valid colors; partial groups, nulls, unknown keys, and invalid colors are rejected by both frontend and backend. Save, copy, and export include the resolved group through the existing API and version-1 envelope. No database migration or separate syntax preferences are needed. Older application releases may reject these newer exports.\n\n## Selection And Defaults\n\n`SambeeThemeProvider` combines built-ins with the current user's themes and shared site themes from `GET /api/themes`. The per-user selection is saved separately through `appearance.theme_id` in `PUT /api/auth/me/settings`. The backend reports whether that value is an explicit override.\n\nA user without an override follows the site default (initially `sambee-light`). A user who explicitly chooses `sambee-light` keeps that ID even if an administrator changes the site default. The selected ID points at a theme definition, never at a frozen copy of a built-in. The provider refreshes shared themes, the default, and user settings on initial load, tab focus, visibility return, and local writes. It discards out-of-date responses when the account changes.\n\nAppearance settings display Your themes, Site themes, then Built-in themes. Clicking a tile or selecting its radio applies the theme and creates an explicit user override, even when it already matches the site default. Moving focus between radios doesn't change the applied theme or the target of Copy, Edit, Delete, and Set as default. The Default chip is distinct from the selected radio. Copy keeps writable themes in their group and copies read-only themes into Your themes without applying the copy. Editing read-only themes permits inspection and Save copy, but not Save. Only an administrator can save or delete site themes or make a built-in or site theme the default.\n\n## Editing And Persistence\n\nThe editor uses a responsive dialog with collapsible color groups. A swatch opens an alpha-aware picker and each color has an editable hex field. Invalid text stays in the field without changing the valid draft. Changes in the editor aren't applied to the app until Save succeeds; Cancel discards the draft. Import replaces only the draft after validating a versioned JSON definition, and Export writes the same format.\n\n`POST /api/themes` creates a theme. Save copy opens a destination menu with Your themes for everyone and Site themes for administrators. It always creates a new theme in the chosen group without changing the applied selection. If its name already exists in that group, the editor adds ` (copy)` or a numbered copy suffix. Save updates only the opened theme in its existing group and cannot create a copy. `PUT /api/themes/{id}` and `DELETE /api/themes/{id}?version=...` require the version read by the client; a stale version returns HTTP 409. The server checks ownership, admin permissions, names, IDs, and palette completeness before committing. Bulk writes to `appearance.custom_themes` are no longer supported. Legacy syntax compatibility is limited to an entirely absent syntax group; it doesn't repair incomplete older definitions.\n\nDeleting a theme clears explicit selections referencing it. If it was the site default, that setting is cleared too; users without an override then fall back to Sambee light. An explicit selection of another theme is unaffected.\n\n## Component Guidance\n\nPrefer the effective colors in `resolveThemePalette` and the MUI palette to hard-coded surfaces. `background.default` is the normal application surface; `background.paper` resolves to the same value for MUI compatibility. Dark chrome and dialogs use the editable `background.chrome` role. Markdown code, tables, blockquotes, and heading borders use the built-in theme's explicit document colors.\n\nViewer toolbar foreground variants, scrollbars, and subdued states can still derive opacity-adjusted values from their source color. Keep fixed colors for assets and file-type icons separate from the editor palette.\n\n## Shared Syntax Highlighting\n\nText viewing/editing, Markdown source and rendered Markdown fences share the CodeMirror language registry and tag mapping in `codeMirrorHighlightingCore.ts`. `syntaxHighlighting.ts` defines application-owned language IDs, UTF-16 token ranges, categories and explicit plain-text outcomes. Native editors and the syntax worker reuse that implementation. Fence aliases resolve to existing lazy grammars, including `mssql` to MS SQL and `mariadb` to MariaDB SQL. A `.sql` filename continues to select standard SQL; unknown fence labels aren't guessed.\n\nThe live Markdown viewer collects exact code occurrences from ReactMarkdown's existing AST, without another collection parse or embedded editors. A dedicated cancellable worker prepares syntax sequentially with acknowledged source chunks of at most 16,384 UTF-16 units and result pages of at most 512 ranges. Blocks above 100,000 UTF-16 units stay plain text. Nested Markdown fences use the configured Markdown parser, up to four Markdown levels including the outer block. Unknown, unlabelled and explicit plain-text fences remain neutral. A nested grammar load failure, or a parser error during static fence startup or advancement, leaves only the failed fence plain while retaining enclosing Markdown structure and successful siblings. The static adapter doesn't mutate cached grammars or retry parsing; later fences and preparations can still succeed. Closing during a pending grammar load terminates the generation's worker; reopening starts a fresh preparation. Cancellation still propagates, and exceeding the nesting limit intentionally keeps the whole outer block plain without suppressing unrelated blocks. There's no aggregate document-length or block-count cutoff. The pre-app browser capability gate requires the Web Worker API; Worker-less app operation isn't supported. The helper's defensive main-thread fallback isn't a supported browser mode or a responsiveness guarantee.\n\nEach preview generation owns cancellation and stale-result guards. After all requested blocks finish, the viewer paints at most 4,000 viewport syntax ranges through CSS Highlights. Vertical and horizontal clipping avoid publishing off-screen token ranges; scrolling, viewport resize, image loads and font readiness refresh presentation. Publication doesn't replace text nodes or insert token spans, preserving native text, whitespace, selection and the cached preview-search index. Missing highlight/visibility capabilities leave syntax plain instead of falling back to token DOM mutation. Disposal removes owned highlights, style, observers, listeners and queued frames. First visible syntax, complete preparation, memory and native interaction acceptance remain separate rollout gates; see [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/).\n\nThe existing theme provider installs stable application token rules once. Viewer/editor surfaces publish locally inherited CSS variables from the resolved MUI syntax palette, so changing theme colors doesn't require reparsing code or replacing token DOM. Identifiers and neutral code inherit the existing code foreground. Markdown source headings and structural markers use `keyword`; links use the existing link role; inline code uses the existing code foreground. Emphasis, strong text, and strikethrough change only their corresponding semantic treatment, not source font sizes or line geometry. Embedded code uses code categories, not Markdown prose styling.\n\nThe shared mapping also preserves built-ins, properties and keys, booleans, null, regular expressions, escapes, and metadata/directives when the grammar supplies those tags. `TOKEN_COLOR_ROLES` maps these categories to the existing eight syntax colors: built-ins use `function`; properties and regular expressions use `type`; booleans, null, and metadata use `keyword`; escapes use `operator`. Editors and rendered fences share this mapping without another parse or a theme schema change. Built-in names aren't necessarily commands, and grammar classifications vary: PowerShell variables and bare words can both remain neutral identifiers. There are no language-specific classification overrides.\n\nSearch matches use the viewer text foreground instead of syntax colors so matched keywords remain readable against their highlight backgrounds. Source editors apply that foreground to the match and its nested tokens. Preview search inherits `--sambee-search-foreground` from its own viewer; syntax highlights have priority -1, ordinary search highlights 0, and the current match 1. The shared search-color helper preserves the configured hues and uses 30%/36% opacity for ordinary/current matches in light mode and 40%/44% in dark mode. Custom theme validation checks color format and completeness, not contrast; choose text, syntax and surface colors that remain readable after alpha blending.\n\nTheme updates and lazy grammar completion preserve native selection, the active search match and both scroll axes on all four surfaces. Theme changes don't restart syntax preparation or renormalize unchanged Markdown. Late grammar completion can update editor token spans, while preview publication retains its original text nodes. These state guarantees don't establish scrolling performance, native clipboard behavior or close/navigation acceptance.\n\nReplacing an editor doesn't require replacing static highlighting. Replacing the engine requires preserving the application range/outcome contract, aliases where supported, and viewer lifecycle. Classification parity with a different engine isn't automatic. Removing CodeMirror entirely also requires migrating native editor integrations such as commands, autocomplete, and tables.\n\n## Verification\n\nRun focused theme tests and the project checks after changing the palette, API, or editor:\n\n```bash\ncd frontend \u0026\u0026 npm run test -- src/theme/__tests__ src/pages/__tests__/PreferencesSettings.test.tsx\ncd frontend \u0026\u0026 npm run build \u0026\u0026 npm run lint\ncd backend \u0026\u0026 .venv/bin/python -m pytest tests/test_user_settings.py\n```\n\nCheck the Appearance grid and editor on a phone and desktop in both built-in modes. Verify selection and saved-theme refresh after focus, color picker keyboard use and placement, alpha values and export, Cancel without applying the draft, and stale-save feedback.\n\nFor the production theme-dialog browser regressions, build the frontend first and keep the existing frontend/backend dev servers running. From `frontend/`, run:\n\n```bash\nSAMBEE_E2E_PRODUCTION=1 npm run test:e2e:all -- --grep 'production syntax theme dialog' --workers=1\n```\n\nThe suite serves built assets and intercepts theme APIs at `http://localhost:3000/browse/smb/demo`; it doesn't change stored themes. Chromium and Firefox cover save/cancel/copy, validation focus, personal/site/built-in permissions, alpha values, unchanged selection after copying, and rejected-save feedback at 1543x900 and 390x600. Narrow desktop viewports don't replace testing on a physical phone or with assistive technology.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Theming System and Theme Selection\"\n+++\n\nSambee's theming system is centralized. Theme configuration, runtime state, persistence, and selection UI are all treated as one frontend subsystem.\n\nUse this page when you are changing palette behavior, adding a built-in theme, wiring a theme-aware component, or debugging why a selected theme is not applied consistently.\n\n## Main Pieces\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/theme/types.ts` | TypeScript theme interfaces and theme configuration shape |\n| `frontend/src/theme/themes.ts` | built-in theme definitions plus default-theme helpers |\n| `frontend/src/theme/ThemeContext.tsx` | runtime theme state, persistence, and theme switching |\n| `frontend/src/theme/index.ts` | public theme exports for the rest of the app |\n| `frontend/src/components/ThemeSelector.tsx` | theme-selection UI and dialog |\n| `frontend/src/components/themeSelectorStrings.ts` | localized strings and built-in-theme labels for the selector |\n\nThese pieces matter together. Theme behavior is not just a palette file or just a toolbar widget.\n\n## What the System Supports\n\nThe theme model currently supports:\n\n- built-in light and dark themes\n- persistent theme preferences\n- custom theme storage and runtime selection\n- theme-aware MUI palette generation\n- one shared provider that updates the app when the theme changes\n\n## Built-In Themes\n\nThe built-in themes live in `builtInThemes` in `frontend/src/theme/themes.ts`.\n\nCurrent built-ins include:\n\n- `sambee-light`: the default light branded theme\n- `sambee-dark`: the default dark branded theme\n\nThe helper functions contributors use most are:\n\n- `getDefaultTheme()`\n- `getDefaultTheme(\"light\")`\n- `getDefaultTheme(\"dark\")`\n- `getThemeById(id)`\n\nThe theme module also includes compile-time assertions around the default-theme indices so the expected built-in defaults cannot silently disappear.\n\n## Runtime Flow\n\nAt runtime, theme selection follows this path:\n\n1. the app renders inside `SambeeThemeProvider`\n2. the current theme ID is restored from persisted state when available\n3. built-in themes are resolved from code and combined with persisted custom themes\n4. `useSambeeTheme().setThemeById()` updates the active theme\n5. the selected theme is persisted\n6. the MUI theme instance updates and the UI re-renders\n\nThat is why a theme bug can look like a local component styling issue while actually being a context, persistence, or provider problem.\n\n## Theme Context Contract\n\n`useSambeeTheme()` is the main runtime entry point.\n\nContributors typically consume values such as:\n\n- `currentTheme`\n- `muiTheme`\n- `availableThemes`\n- `setThemeById`\n- `addCustomTheme`\n\nThe hook must be used inside `SambeeThemeProvider`. If you bypass that provider boundary, theme state becomes inconsistent immediately.\n\nRepresentative usage:\n\n```tsx\nimport { useSambeeTheme } from \"../theme\";\n\nfunction ThemeExample() {\n\tconst { currentTheme, setThemeById } = useSambeeTheme();\n\n\treturn (\n\t\t\u003cbutton onClick={() =\u003e setThemeById(\"sambee-dark\")}\u003e\n\t\t\tCurrent: {currentTheme.name}\n\t\t\u003c/button\u003e\n\t);\n}\n```\n\n## Theme Configuration Model\n\nThemes are expressed as typed configuration rather than ad hoc color overrides.\n\nThe palette surface includes areas such as:\n\n- `primary`\n- `secondary`\n- `background`\n- `text`\n- `action`\n\nCommon uses in the UI include:\n\n- directory emphasis and action colors from `primary`\n- page and surface backgrounds from `background`\n- readable foreground text from `text`\n- hover and selection states from `action`\n\nMaterial UI also derives additional palette values such as divider color when enough base information is present.\n\n## Built-In Theme Characteristics\n\nThe current built-ins intentionally align with Sambee's branding.\n\n### Sambee Light\n\n- ID: `sambee-light`\n- mode: light\n- branded golden primary palette\n- cream-toned background\n- dark secondary contrast surface\n\n### Sambee Dark\n\n- ID: `sambee-dark`\n- mode: dark\n- branded golden primary palette\n- dark background\n- light secondary contrast surface\n\nThe exact palette values live in `frontend/src/theme/themes.ts`. Keep the docs focused on architectural meaning rather than duplicating every color token when the code is already authoritative.\n\n## Theme Selector UI\n\nThe visible selection UI lives in `frontend/src/components/ThemeSelector.tsx`.\n\nThe selector:\n\n- opens a dialog listing available themes\n- shows a preview of theme colors\n- uses localized strings through `themeSelectorStrings.ts`\n- calls `setThemeById` when the user changes themes\n\nThe selector is already integrated into the file-browser toolbar, and the current preferences UI also consumes the same theme state.\n\n## Persistence Model\n\nTheme preferences are persisted in local storage.\n\nThe main keys are:\n\n- `theme-id-current`: the currently selected theme ID\n- `themes-builtin`: built-in themes as last synchronized from code\n- `themes-custom`: user-created custom themes\n\nThis matters for two reasons:\n\n- the selected theme survives reloads\n- built-in theme definitions can still be refreshed from code when the app updates\n\nThe system syncs built-in themes from code so users pick up reviewed built-in theme changes without losing their custom themes.\n\n## Custom Themes\n\nThe theme context supports custom themes in addition to the built-ins.\n\nThat means contributors should treat theme IDs, storage layout, and theme resolution as stable interfaces rather than temporary implementation details.\n\nWhen adding custom-theme features or editing persistence logic:\n\n- preserve separation between built-in and custom theme sets\n- keep the active theme valid even if a custom theme is removed\n- preserve a safe fallback to the default theme\n\nRepresentative pattern:\n\n```tsx\nimport { useSambeeTheme } from \"../theme\";\n\nfunction addExampleTheme() {\n\tconst { addCustomTheme } = useSambeeTheme();\n\n\taddCustomTheme({\n\t\tid: \"my-custom-theme\",\n\t\tname: \"My Custom Theme\",\n\t\tdescription: \"A unique theme\",\n\t\tmode: \"light\",\n\t\tprimary: { main: \"#ff6b6b\" },\n\t\tsecondary: { main: \"#4ecdc4\" },\n\t});\n}\n```\n\n## Theme Schema and Future Builder Support\n\n`frontend/src/theme/types.ts` also exports `THEME_SCHEMA`.\n\nThat schema is runtime-accessible metadata describing:\n\n- field types such as text, color, and select\n- labels and descriptions for UI\n- required versus optional fields\n- nested field definitions\n- select options such as `light` and `dark`\n\nIt exists so future theme-builder tooling can generate forms and validation from one typed source instead of re-encoding theme structure in multiple places.\n\n## Theme-Aware Component Rules\n\nWhen building UI components:\n\n- use the active MUI theme instead of hard-coded surface and text colors when the style belongs to the app theme\n- prefer `useTheme()` or the shared theme context rather than duplicating palette lookups manually\n- keep file-type icon colors and other intentionally non-theme registry colors separate from the app palette when they serve a different product purpose\n\nA theme-aware component typically reads from `theme.palette` and `theme.spacing` rather than introducing standalone constants.\n\n## Browser and PWA Integration\n\nThe theme system also updates the browser `theme-color` meta tag to match the selected theme's primary color.\n\nThat affects:\n\n- browser UI tinting on supported browsers\n- Android browser chrome behavior\n- installed PWA status-bar appearance\n\nIf a theme appears correct inside the app but wrong in browser chrome, check this integration path rather than only inspecting component styles.\n\n## Common Failure Modes\n\n- a component hard-codes colors that should come from the active theme\n- a new built-in theme is added without keeping default-theme helpers valid\n- theme state is read outside `SambeeThemeProvider`\n- a persistence change breaks fallback to the default theme\n- built-in theme updates and custom theme persistence start overwriting each other\n- contributors treat selector labels as static strings instead of localized UI copy\n\n## Validation Expectations\n\nWhen the theming system changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nPay particular attention to:\n\n- theme-provider tests under `frontend/src/theme/__tests__/`\n- built-in-theme and default-theme tests\n- `types.test.ts` coverage around `THEME_SCHEMA`\n- theme-selector tests under `frontend/src/components/__tests__/`\n- manual checks that text remains readable in both built-in themes\n\n## Where to Continue\n\n- [Frontend Overview](../frontend-overview/): broader browser-app structure and the place of theme behavior in the frontend\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): another shared frontend subsystem with central configuration and runtime binding\n- [Localization and Locale Behavior](../../cross-cutting-systems/localization-and-locale-behavior/): shared UI-system rules that often change alongside settings and preferences surfaces\n", "0.8": "+++\ntitle = \"Theming System and Theme Selection\"\n+++\n\nSambee's theming system is centralized. Theme configuration, runtime state, persistence, and selection UI are all treated as one frontend subsystem.\n\nUse this page when you are changing palette behavior, adding a built-in theme, wiring a theme-aware component, or debugging why a selected theme is not applied consistently.\n\n## Main Pieces\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/theme/types.ts` | TypeScript theme interfaces and theme configuration shape |\n| `frontend/src/theme/themes.ts` | built-in theme definitions plus default-theme helpers |\n| `frontend/src/theme/ThemeContext.tsx` | runtime theme state, persistence, and theme switching |\n| `frontend/src/theme/index.ts` | public theme exports for the rest of the app |\n| `frontend/src/components/ThemeSelector.tsx` | theme-selection UI and dialog |\n| `frontend/src/components/themeSelectorStrings.ts` | localized strings and built-in-theme labels for the selector |\n\nThese pieces matter together. Theme behavior is not just a palette file or just a toolbar widget.\n\n## What the System Supports\n\nThe theme model currently supports:\n\n- built-in light and dark themes\n- persistent theme preferences\n- custom theme storage and runtime selection\n- theme-aware MUI palette generation\n- one shared provider that updates the app when the theme changes\n\n## Built-In Themes\n\nThe built-in themes live in `builtInThemes` in `frontend/src/theme/themes.ts`.\n\nCurrent built-ins include:\n\n- `sambee-light`: the default light branded theme\n- `sambee-dark`: the default dark branded theme\n\nThe helper functions contributors use most are:\n\n- `getDefaultTheme()`\n- `getDefaultTheme(\"light\")`\n- `getDefaultTheme(\"dark\")`\n- `getThemeById(id)`\n\nThe theme module also includes compile-time assertions around the default-theme indices so the expected built-in defaults cannot silently disappear.\n\n## Runtime Flow\n\nAt runtime, theme selection follows this path:\n\n1. the app renders inside `SambeeThemeProvider`\n2. the current theme ID is restored from persisted state when available\n3. built-in themes are resolved from code and combined with persisted custom themes\n4. `useSambeeTheme().setThemeById()` updates the active theme\n5. the selected theme is persisted\n6. the MUI theme instance updates and the UI re-renders\n\nThat is why a theme bug can look like a local component styling issue while actually being a context, persistence, or provider problem.\n\n## Theme Context Contract\n\n`useSambeeTheme()` is the main runtime entry point.\n\nContributors typically consume values such as:\n\n- `currentTheme`\n- `muiTheme`\n- `availableThemes`\n- `setThemeById`\n- `addCustomTheme`\n\nThe hook must be used inside `SambeeThemeProvider`. If you bypass that provider boundary, theme state becomes inconsistent immediately.\n\nRepresentative usage:\n\n```tsx\nimport { useSambeeTheme } from \"../theme\";\n\nfunction ThemeExample() {\n\tconst { currentTheme, setThemeById } = useSambeeTheme();\n\n\treturn (\n\t\t\u003cbutton onClick={() =\u003e setThemeById(\"sambee-dark\")}\u003e\n\t\t\tCurrent: {currentTheme.name}\n\t\t\u003c/button\u003e\n\t);\n}\n```\n\n## Theme Configuration Model\n\nThemes are expressed as typed configuration rather than ad hoc color overrides.\n\nThe palette surface includes areas such as:\n\n- `primary`\n- `secondary`\n- `background`\n- `text`\n- `action`\n\nCommon uses in the UI include:\n\n- directory emphasis and action colors from `primary`\n- page and surface backgrounds from `background`\n- readable foreground text from `text`\n- hover and selection states from `action`\n\nMaterial UI also derives additional palette values such as divider color when enough base information is present.\n\n## Built-In Theme Characteristics\n\nThe current built-ins intentionally align with Sambee's branding.\n\n### Sambee Light\n\n- ID: `sambee-light`\n- mode: light\n- branded golden primary palette\n- cream-toned background\n- dark secondary contrast surface\n\n### Sambee Dark\n\n- ID: `sambee-dark`\n- mode: dark\n- branded golden primary palette\n- dark background\n- light secondary contrast surface\n\nThe exact palette values live in `frontend/src/theme/themes.ts`. Keep the docs focused on architectural meaning rather than duplicating every color token when the code is already authoritative.\n\n## Theme Selector UI\n\nThe visible selection UI lives in `frontend/src/components/ThemeSelector.tsx`.\n\nThe selector:\n\n- opens a dialog listing available themes\n- shows a preview of theme colors\n- uses localized strings through `themeSelectorStrings.ts`\n- calls `setThemeById` when the user changes themes\n\nThe selector is already integrated into the file-browser toolbar, and the current preferences UI also consumes the same theme state.\n\n## Persistence Model\n\nTheme preferences are persisted in local storage.\n\nThe main keys are:\n\n- `theme-id-current`: the currently selected theme ID\n- `themes-builtin`: built-in themes as last synchronized from code\n- `themes-custom`: user-created custom themes\n\nThis matters for two reasons:\n\n- the selected theme survives reloads\n- built-in theme definitions can still be refreshed from code when the app updates\n\nThe system syncs built-in themes from code so users pick up reviewed built-in theme changes without losing their custom themes.\n\n## Custom Themes\n\nThe theme context supports custom themes in addition to the built-ins.\n\nThat means contributors should treat theme IDs, storage layout, and theme resolution as stable interfaces rather than temporary implementation details.\n\nWhen adding custom-theme features or editing persistence logic:\n\n- preserve separation between built-in and custom theme sets\n- keep the active theme valid even if a custom theme is removed\n- preserve a safe fallback to the default theme\n\nRepresentative pattern:\n\n```tsx\nimport { useSambeeTheme } from \"../theme\";\n\nfunction addExampleTheme() {\n\tconst { addCustomTheme } = useSambeeTheme();\n\n\taddCustomTheme({\n\t\tid: \"my-custom-theme\",\n\t\tname: \"My Custom Theme\",\n\t\tdescription: \"A unique theme\",\n\t\tmode: \"light\",\n\t\tprimary: { main: \"#ff6b6b\" },\n\t\tsecondary: { main: \"#4ecdc4\" },\n\t});\n}\n```\n\n## Theme Schema and Future Builder Support\n\n`frontend/src/theme/types.ts` also exports `THEME_SCHEMA`.\n\nThat schema is runtime-accessible metadata describing:\n\n- field types such as text, color, and select\n- labels and descriptions for UI\n- required versus optional fields\n- nested field definitions\n- select options such as `light` and `dark`\n\nIt exists so future theme-builder tooling can generate forms and validation from one typed source instead of re-encoding theme structure in multiple places.\n\n## Theme-Aware Component Rules\n\nWhen building UI components:\n\n- use the active MUI theme instead of hard-coded surface and text colors when the style belongs to the app theme\n- prefer `useTheme()` or the shared theme context rather than duplicating palette lookups manually\n- keep file-type icon colors and other intentionally non-theme registry colors separate from the app palette when they serve a different product purpose\n\nA theme-aware component typically reads from `theme.palette` and `theme.spacing` rather than introducing standalone constants.\n\n## Browser and PWA Integration\n\nThe theme system also updates the browser `theme-color` meta tag to match the selected theme's primary color.\n\nThat affects:\n\n- browser UI tinting on supported browsers\n- Android browser chrome behavior\n- installed PWA status-bar appearance\n\nIf a theme appears correct inside the app but wrong in browser chrome, check this integration path rather than only inspecting component styles.\n\n## Common Failure Modes\n\n- a component hard-codes colors that should come from the active theme\n- a new built-in theme is added without keeping default-theme helpers valid\n- theme state is read outside `SambeeThemeProvider`\n- a persistence change breaks fallback to the default theme\n- built-in theme updates and custom theme persistence start overwriting each other\n- contributors treat selector labels as static strings instead of localized UI copy\n\n## Validation Expectations\n\nWhen the theming system changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nPay particular attention to:\n\n- theme-provider tests under `frontend/src/theme/__tests__/`\n- built-in-theme and default-theme tests\n- `types.test.ts` coverage around `THEME_SCHEMA`\n- theme-selector tests under `frontend/src/components/__tests__/`\n- manual checks that text remains readable in both built-in themes\n\n## Where to Continue\n\n- [Frontend Overview](../frontend-overview/): broader browser-app structure and the place of theme behavior in the frontend\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): another shared frontend subsystem with central configuration and runtime binding\n- [Localization and Locale Behavior](../../cross-cutting-systems/localization-and-locale-behavior/): shared UI-system rules that often change alongside settings and preferences surfaces\n", "0.9": "+++\ntitle = \"Theming System and Theme Selection\"\n+++\n\nSambee's theming system is centralized. Theme configuration, runtime state, persistence, and selection UI are all treated as one frontend subsystem.\n\nUse this page when you are changing palette behavior, adding a built-in theme, wiring a theme-aware component, or debugging why a selected theme is not applied consistently.\n\n## Main Pieces\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/theme/types.ts` | TypeScript theme interfaces and theme configuration shape |\n| `frontend/src/theme/themes.ts` | built-in theme definitions plus default-theme helpers |\n| `frontend/src/theme/ThemeContext.tsx` | runtime theme state, persistence, and theme switching |\n| `frontend/src/theme/index.ts` | public theme exports for the rest of the app |\n| `frontend/src/components/ThemeSelector.tsx` | theme-selection UI and dialog |\n| `frontend/src/components/themeSelectorStrings.ts` | localized strings and built-in-theme labels for the selector |\n\nThese pieces matter together. Theme behavior is not just a palette file or just a toolbar widget.\n\n## What the System Supports\n\nThe theme model currently supports:\n\n- built-in light and dark themes\n- persistent theme preferences\n- custom theme storage and runtime selection\n- theme-aware MUI palette generation\n- one shared provider that updates the app when the theme changes\n\n## Built-In Themes\n\nThe built-in themes live in `builtInThemes` in `frontend/src/theme/themes.ts`.\n\nCurrent built-ins include:\n\n- `sambee-light`: the default light branded theme\n- `sambee-dark`: the default dark branded theme\n\nThe helper functions contributors use most are:\n\n- `getDefaultTheme()`\n- `getDefaultTheme(\"light\")`\n- `getDefaultTheme(\"dark\")`\n- `getThemeById(id)`\n\nThe theme module also includes compile-time assertions around the default-theme indices so the expected built-in defaults cannot silently disappear.\n\n## Runtime Flow\n\nAt runtime, theme selection follows this path:\n\n1. the app renders inside `SambeeThemeProvider`\n2. the current theme ID is restored from persisted state when available\n3. built-in themes are resolved from code and combined with persisted custom themes\n4. `useSambeeTheme().setThemeById()` updates the active theme\n5. the selected theme is persisted\n6. the MUI theme instance updates and the UI re-renders\n\nThat is why a theme bug can look like a local component styling issue while actually being a context, persistence, or provider problem.\n\n## Theme Context Contract\n\n`useSambeeTheme()` is the main runtime entry point.\n\nContributors typically consume values such as:\n\n- `currentTheme`\n- `muiTheme`\n- `availableThemes`\n- `setThemeById`\n- `addCustomTheme`\n\nThe hook must be used inside `SambeeThemeProvider`. If you bypass that provider boundary, theme state becomes inconsistent immediately.\n\nRepresentative usage:\n\n```tsx\nimport { useSambeeTheme } from \"../theme\";\n\nfunction ThemeExample() {\n\tconst { currentTheme, setThemeById } = useSambeeTheme();\n\n\treturn (\n\t\t\u003cbutton onClick={() =\u003e setThemeById(\"sambee-dark\")}\u003e\n\t\t\tCurrent: {currentTheme.name}\n\t\t\u003c/button\u003e\n\t);\n}\n```\n\n## Theme Configuration Model\n\nThemes are expressed as typed configuration rather than ad hoc color overrides.\n\nThe palette surface includes areas such as:\n\n- `primary`\n- `secondary`\n- `background`\n- `text`\n- `action`\n\nCommon uses in the UI include:\n\n- default primary controls and selected navigation from `primary.main`\n- high-emphasis dark-mode states from `primary.light`\n- light-mode pressed and contrast-sensitive controls from `primary.dark`\n- page and standard application surfaces from `background.default`\n- readable foreground text from `text`\n- selection fills from `action.selected`\n\nMaterial UI also derives additional palette values such as divider color when enough base information is present.\n\n### Surface Policy\n\n`background.default` is the standard application surface. Use it for pages, standard dialogs, settings, and compact controls.\n\n`background.paper` remains populated at runtime because Material UI expects the token. Sambee normalizes it to `background.default`; application components should not select it as a separate surface.\n\nThe shared settings form surface is a deliberate derived exception: it darkens the default surface by 4% in light mode and lightens it by 8% in dark mode. Inside a dark dialog, it uses a 12% black mix of the actual dialog paper surface, preserving a warm but recessed form area; its outlined fields inherit the dialog paper surface to remain visually distinct from the surrounding form layer. Application chrome is another exception: light-mode AppBar and StatusBar use the primary color, while dark-mode chrome uses the shared opaque brown `#382c0a`. Standard Material UI Dialog papers and popup menus use that same opaque dark-mode color, preventing the backdrop from showing through. Fullscreen viewers retain their dedicated viewer surfaces. Dark dialog backdrops use a high-opacity neutral composite of `background.default`, preventing nested dialogs from tinting the surface behind them. Dialogs do not add an elevation shadow because the modal backdrop provides their separation. Menu selection, hover, and keyboard focus use `action.selected`.\n\nStandard Material UI Alerts use the theme's `components.alert` semantic colors for their info, success, warning, and error backgrounds, text, and icons. Apply alert semantics through the shared theme rather than per-component overrides.\n\n### Primary Palette Roles\n\n`primary.main` is the default primary control color. It should not be the brightest available shade in a dark theme, because Material UI applies it to contained buttons, radios, selected icons, and many other default controls.\n\nUse `primary.light` for brighter dark-mode hover and high-emphasis states. Use `primary.dark` for pressed and contrast-sensitive light-mode controls. Do not swap `main` and `dark` between modes: Material UI treats `dark` as the darker interaction shade.\n\nThe built-in dark theme uses a subdued golden `main`, a brighter golden `light`, and a darker pressed `dark` shade. The exact values live in `frontend/src/theme/themes.ts`.\n\n### Foreground Color Policy\n\nStandard application UI uses two base foreground roles:\n\n- `text.primary` is high-emphasis text: headings, selected or active labels, form values, selectable menu choices, file names, and information required to complete the current task.\n- `text.secondary` is the default supporting layer: descriptions, metadata, timestamps, helper copy, captions, inactive navigation icons, and other text that should be readable without competing with the task.\n\nThe built-in dark theme intentionally makes `text.secondary` a muted version of the warm primary text. This reduces glare during extended use while preserving a clear emphasis hierarchy. Use `text.disabled` for non-interactive content and dedicated palette roles such as `statusBar.textSecondary`, alert colors, and viewer toolbar colors when the surface has its own semantic contract.\n\nFor Material UI `Typography`, apply dotted palette roles through `sx`, for example `sx={{ color: \"text.secondary\" }}`. In this application's Material UI v9 configuration, `color=\"text.secondary\"` does not emit a palette color rule, so the element falls back to inherited text.\n\nIcons should inherit the role of their associated text. Use `currentColor` for adaptable inline SVG illustrations. Brand assets, file-type registry icons, document rendering, syntax highlighting, and semantic alerts are deliberate exceptions: their colors convey identity, content type, or state and should remain separately named rather than being forced into the general text palette.\n\n## Built-In Theme Characteristics\n\nThe current built-ins intentionally align with Sambee's branding.\n\n### Sambee Light\n\n- ID: `sambee-light`\n- mode: light\n- branded golden primary palette\n- cream-toned background\n- dark secondary contrast surface\n\n### Sambee Dark\n\n- ID: `sambee-dark`\n- mode: dark\n- branded golden primary palette\n- dark background\n- light secondary contrast surface\n\nThe exact palette values live in `frontend/src/theme/themes.ts`. Keep the docs focused on architectural meaning rather than duplicating every color token when the code is already authoritative.\n\n## Theme Selector UI\n\nThe visible selection UI lives in `frontend/src/components/ThemeSelector.tsx`.\n\nThe selector:\n\n- opens a dialog listing available themes\n- shows a preview of theme colors\n- uses localized strings through `themeSelectorStrings.ts`\n- calls `setThemeById` when the user changes themes\n\nThe selector is already integrated into the file-browser toolbar, and the current preferences UI also consumes the same theme state.\n\n## Persistence Model\n\nTheme preferences are persisted in local storage.\n\nThe main keys are:\n\n- `theme-id-current`: the currently selected theme ID\n- `themes-custom`: user-created custom themes\n\nThis matters for two reasons:\n\n- the selected theme survives reloads\n- built-in theme definitions can still be refreshed from code when the app updates\n\nThe system syncs built-in themes from code so users pick up reviewed built-in theme changes without losing their custom themes.\n\n## Custom Themes\n\nThe theme context supports custom themes in addition to the built-ins.\n\nThat means contributors should treat theme IDs, storage layout, and theme resolution as stable interfaces rather than temporary implementation details.\n\nWhen adding custom-theme features or editing persistence logic:\n\n- preserve separation between built-in and custom theme sets\n- keep the active theme valid even if a custom theme is removed\n- preserve a safe fallback to the default theme\n\nRepresentative pattern:\n\n```tsx\nimport { useSambeeTheme } from \"../theme\";\n\nfunction addExampleTheme() {\n\tconst { addCustomTheme } = useSambeeTheme();\n\n\taddCustomTheme({\n\t\tid: \"my-custom-theme\",\n\t\tname: \"My Custom Theme\",\n\t\tdescription: \"A unique theme\",\n\t\tmode: \"light\",\n\t\tprimary: { main: \"#ff6b6b\" },\n\t});\n}\n```\n\n## Theme Schema and Future Builder Support\n\n`frontend/src/theme/types.ts` also exports `THEME_SCHEMA`.\n\nThat schema is runtime-accessible metadata describing:\n\n- field types such as text, color, and select\n- labels and descriptions for UI\n- required versus optional fields\n- nested field definitions\n- select options such as `light` and `dark`\n\nNew custom themes should provide `primary.main` and may provide the other primary shades, background, text, and selection colors. The runtime resolver supplies stable mode-aware defaults for omitted optional fields so existing minimally configured themes remain valid.\n\n`action.focus`, `components.appBar`, and `components.statusBar` are honored for already persisted themes but are intentionally not exposed by `THEME_SCHEMA`. New themes derive those values from the palette contract.\n\nIt exists so future theme-builder tooling can generate forms and validation from one typed source instead of re-encoding theme structure in multiple places.\n\n## Theme-Aware Component Rules\n\nWhen building UI components:\n\n- use the active MUI theme instead of hard-coded surface and text colors when the style belongs to the app theme\n- use `text.primary` and `text.secondary` to establish normal UI hierarchy; do not recreate muted text with local opacity values\n- prefer `useTheme()` or the shared theme context rather than duplicating palette lookups manually\n- derive viewer toolbar borders, muted labels, disabled controls, and subtle fills from the configured toolbar text color\n- keep file-type icon colors and other intentionally non-theme registry colors separate from the app palette when they serve a different product purpose\n\nA theme-aware component typically reads from `theme.palette` and `theme.spacing` rather than introducing standalone constants.\n\n## Browser and PWA Integration\n\nThe theme system also updates the browser `theme-color` meta tag to match the selected theme's primary color.\n\nThat affects:\n\n- browser UI tinting on supported browsers\n- Android browser chrome behavior\n- installed PWA status-bar appearance\n\nIf a theme appears correct inside the app but wrong in browser chrome, check this integration path rather than only inspecting component styles.\n\n## Common Failure Modes\n\n- a component hard-codes colors that should come from the active theme\n- a new built-in theme is added without keeping default-theme helpers valid\n- theme state is read outside `SambeeThemeProvider`\n- a persistence change breaks fallback to the default theme\n- built-in theme updates and custom theme persistence start overwriting each other\n- contributors treat selector labels as static strings instead of localized UI copy\n\n## Validation Expectations\n\nWhen the theming system changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nPay particular attention to:\n\n- theme-provider tests under `frontend/src/theme/__tests__/`\n- built-in-theme and default-theme tests\n- `types.test.ts` coverage around `THEME_SCHEMA`\n- theme-selector tests under `frontend/src/components/__tests__/`\n- manual checks that text remains readable in both built-in themes\n\n## Where to Continue\n\n- [Frontend Overview](../frontend-overview/): broader browser-app structure and the place of theme behavior in the frontend\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): another shared frontend subsystem with central configuration and runtime binding\n- [Localization and Locale Behavior](../../cross-cutting-systems/localization-and-locale-behavior/): shared UI-system rules that often change alongside settings and preferences surfaces\n", "1.0": "+++\ntitle = \"Theming System and Theme Selection\"\n+++\n\nSambee's theming system is centralized. Theme configuration, runtime state, persistence, and selection UI are all treated as one frontend subsystem.\n\nUse this page when you are changing palette behavior, adding a built-in theme, wiring a theme-aware component, or debugging why a selected theme is not applied consistently.\n\n## Main Pieces\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/theme/types.ts` | TypeScript theme interfaces and theme configuration shape |\n| `frontend/src/theme/themes.ts` | built-in theme definitions plus default-theme helpers |\n| `frontend/src/theme/ThemeContext.tsx` | runtime theme state, persistence, and theme switching |\n| `frontend/src/theme/index.ts` | public theme exports for the rest of the app |\n| `frontend/src/components/ThemeSelector.tsx` | theme-selection UI and dialog |\n| `frontend/src/components/themeSelectorStrings.ts` | localized strings and built-in-theme labels for the selector |\n\nThese pieces matter together. Theme behavior is not just a palette file or just a toolbar widget.\n\n## What the System Supports\n\nThe theme model currently supports:\n\n- built-in light and dark themes\n- persistent theme preferences\n- custom theme storage and runtime selection\n- theme-aware MUI palette generation\n- one shared provider that updates the app when the theme changes\n\n## Built-In Themes\n\nThe built-in themes live in `builtInThemes` in `frontend/src/theme/themes.ts`.\n\nCurrent built-ins include:\n\n- `sambee-light`: the default light branded theme\n- `sambee-dark`: the default dark branded theme\n\nThe helper functions contributors use most are:\n\n- `getDefaultTheme()`\n- `getDefaultTheme(\"light\")`\n- `getDefaultTheme(\"dark\")`\n- `getThemeById(id)`\n\nThe theme module also includes compile-time assertions around the default-theme indices so the expected built-in defaults cannot silently disappear.\n\n## Runtime Flow\n\nAt runtime, theme selection follows this path:\n\n1. the app renders inside `SambeeThemeProvider`\n2. the current theme ID is restored from persisted state when available\n3. built-in themes are resolved from code and combined with persisted custom themes\n4. `useSambeeTheme().setThemeById()` updates the active theme\n5. the selected theme is persisted\n6. the MUI theme instance updates and the UI re-renders\n\nThat is why a theme bug can look like a local component styling issue while actually being a context, persistence, or provider problem.\n\n## Theme Context Contract\n\n`useSambeeTheme()` is the main runtime entry point.\n\nContributors typically consume values such as:\n\n- `currentTheme`\n- `muiTheme`\n- `availableThemes`\n- `setThemeById`\n- `addCustomTheme`\n\nThe hook must be used inside `SambeeThemeProvider`. If you bypass that provider boundary, theme state becomes inconsistent immediately.\n\nRepresentative usage:\n\n```tsx\nimport { useSambeeTheme } from \"../theme\";\n\nfunction ThemeExample() {\n\tconst { currentTheme, setThemeById } = useSambeeTheme();\n\n\treturn (\n\t\t\u003cbutton onClick={() =\u003e setThemeById(\"sambee-dark\")}\u003e\n\t\t\tCurrent: {currentTheme.name}\n\t\t\u003c/button\u003e\n\t);\n}\n```\n\n## Theme Configuration Model\n\nThemes are expressed as typed configuration rather than ad hoc color overrides.\n\nThe palette surface includes areas such as:\n\n- `primary`\n- `secondary`\n- `background`\n- `text`\n- `action`\n\nCommon uses in the UI include:\n\n- default primary controls and selected navigation from `primary.main`\n- high-emphasis dark-mode states from `primary.light`\n- light-mode pressed and contrast-sensitive controls from `primary.dark`\n- page and standard application surfaces from `background.default`\n- readable foreground text from `text`\n- selection fills from `action.selected`\n\nMaterial UI also derives additional palette values such as divider color when enough base information is present.\n\n### Surface Policy\n\n`background.default` is the standard application surface. Use it for pages, standard dialogs, settings, and compact controls.\n\n`background.paper` remains populated at runtime because Material UI expects the token. Sambee normalizes it to `background.default`; application components should not select it as a separate surface.\n\nThe shared settings form surface is a deliberate derived exception: it darkens the default surface by 4% in light mode and lightens it by 8% in dark mode. Inside a dark dialog, it uses a 12% black mix of the actual dialog paper surface, preserving a warm but recessed form area; its outlined fields inherit the dialog paper surface to remain visually distinct from the surrounding form layer. Application chrome is another exception: light-mode AppBar and StatusBar use the primary color, while dark-mode chrome uses the shared opaque brown `#382c0a`. Standard Material UI Dialog papers and popup menus use that same opaque dark-mode color, preventing the backdrop from showing through. Fullscreen viewers retain their dedicated viewer surfaces. Dark dialog backdrops use a high-opacity neutral composite of `background.default`, preventing nested dialogs from tinting the surface behind them. Dialogs do not add an elevation shadow because the modal backdrop provides their separation. Menu selection, hover, and keyboard focus use `action.selected`.\n\nStandard Material UI Alerts use the theme's `components.alert` semantic colors for their info, success, warning, and error backgrounds, text, and icons. Apply alert semantics through the shared theme rather than per-component overrides.\n\n### Primary Palette Roles\n\n`primary.main` is the default primary control color. It should not be the brightest available shade in a dark theme, because Material UI applies it to contained buttons, radios, selected icons, and many other default controls.\n\nUse `primary.light` for brighter dark-mode hover and high-emphasis states. Use `primary.dark` for pressed and contrast-sensitive light-mode controls. Do not swap `main` and `dark` between modes: Material UI treats `dark` as the darker interaction shade.\n\nThe built-in dark theme uses a subdued golden `main`, a brighter golden `light`, and a darker pressed `dark` shade. The exact values live in `frontend/src/theme/themes.ts`.\n\n### Foreground Color Policy\n\nStandard application UI uses two base foreground roles:\n\n- `text.primary` is high-emphasis text: headings, selected or active labels, form values, selectable menu choices, file names, and information required to complete the current task.\n- `text.secondary` is the default supporting layer: descriptions, metadata, timestamps, helper copy, captions, inactive navigation icons, and other text that should be readable without competing with the task.\n\nThe built-in dark theme intentionally makes `text.secondary` a muted version of the warm primary text. This reduces glare during extended use while preserving a clear emphasis hierarchy. Use `text.disabled` for non-interactive content and dedicated palette roles such as `statusBar.textSecondary`, alert colors, and viewer toolbar colors when the surface has its own semantic contract.\n\nFor Material UI `Typography`, apply dotted palette roles through `sx`, for example `sx={{ color: \"text.secondary\" }}`. In this application's Material UI v9 configuration, `color=\"text.secondary\"` does not emit a palette color rule, so the element falls back to inherited text.\n\nIcons should inherit the role of their associated text. Use `currentColor` for adaptable inline SVG illustrations. Brand assets, file-type registry icons, document rendering, syntax highlighting, and semantic alerts are deliberate exceptions: their colors convey identity, content type, or state and should remain separately named rather than being forced into the general text palette.\n\n## Built-In Theme Characteristics\n\nThe current built-ins intentionally align with Sambee's branding.\n\n### Sambee Light\n\n- ID: `sambee-light`\n- mode: light\n- branded golden primary palette\n- cream-toned background\n- dark secondary contrast surface\n\n### Sambee Dark\n\n- ID: `sambee-dark`\n- mode: dark\n- branded golden primary palette\n- dark background\n- light secondary contrast surface\n\nThe exact palette values live in `frontend/src/theme/themes.ts`. Keep the docs focused on architectural meaning rather than duplicating every color token when the code is already authoritative.\n\n## Theme Selector UI\n\nThe visible selection UI lives in `frontend/src/components/ThemeSelector.tsx`.\n\nThe selector:\n\n- opens a dialog listing available themes\n- shows a preview of theme colors\n- uses localized strings through `themeSelectorStrings.ts`\n- calls `setThemeById` when the user changes themes\n\nThe selector is already integrated into the file-browser toolbar, and the current preferences UI also consumes the same theme state.\n\n## Persistence Model\n\nTheme preferences are persisted in local storage.\n\nThe main keys are:\n\n- `theme-id-current`: the currently selected theme ID\n- `themes-custom`: user-created custom themes\n\nThis matters for two reasons:\n\n- the selected theme survives reloads\n- built-in theme definitions can still be refreshed from code when the app updates\n\nThe system syncs built-in themes from code so users pick up reviewed built-in theme changes without losing their custom themes.\n\n## Custom Themes\n\nThe theme context supports custom themes in addition to the built-ins.\n\nThat means contributors should treat theme IDs, storage layout, and theme resolution as stable interfaces rather than temporary implementation details.\n\nWhen adding custom-theme features or editing persistence logic:\n\n- preserve separation between built-in and custom theme sets\n- keep the active theme valid even if a custom theme is removed\n- preserve a safe fallback to the default theme\n\nRepresentative pattern:\n\n```tsx\nimport { useSambeeTheme } from \"../theme\";\n\nfunction addExampleTheme() {\n\tconst { addCustomTheme } = useSambeeTheme();\n\n\taddCustomTheme({\n\t\tid: \"my-custom-theme\",\n\t\tname: \"My Custom Theme\",\n\t\tdescription: \"A unique theme\",\n\t\tmode: \"light\",\n\t\tprimary: { main: \"#ff6b6b\" },\n\t});\n}\n```\n\n## Theme Schema and Future Builder Support\n\n`frontend/src/theme/types.ts` also exports `THEME_SCHEMA`.\n\nThat schema is runtime-accessible metadata describing:\n\n- field types such as text, color, and select\n- labels and descriptions for UI\n- required versus optional fields\n- nested field definitions\n- select options such as `light` and `dark`\n\nNew custom themes should provide `primary.main` and may provide the other primary shades, background, text, and selection colors. The runtime resolver supplies stable mode-aware defaults for omitted optional fields so existing minimally configured themes remain valid.\n\n`action.focus`, `components.appBar`, and `components.statusBar` are honored for already persisted themes but are intentionally not exposed by `THEME_SCHEMA`. New themes derive those values from the palette contract.\n\nIt exists so future theme-builder tooling can generate forms and validation from one typed source instead of re-encoding theme structure in multiple places.\n\n## Theme-Aware Component Rules\n\nWhen building UI components:\n\n- use the active MUI theme instead of hard-coded surface and text colors when the style belongs to the app theme\n- use `text.primary` and `text.secondary` to establish normal UI hierarchy; do not recreate muted text with local opacity values\n- prefer `useTheme()` or the shared theme context rather than duplicating palette lookups manually\n- derive viewer toolbar borders, muted labels, disabled controls, and subtle fills from the configured toolbar text color\n- keep file-type icon colors and other intentionally non-theme registry colors separate from the app palette when they serve a different product purpose\n\nA theme-aware component typically reads from `theme.palette` and `theme.spacing` rather than introducing standalone constants.\n\n## Browser and PWA Integration\n\nThe theme system also updates the browser `theme-color` meta tag to match the selected theme's primary color.\n\nThat affects:\n\n- browser UI tinting on supported browsers\n- Android browser chrome behavior\n- installed PWA status-bar appearance\n\nIf a theme appears correct inside the app but wrong in browser chrome, check this integration path rather than only inspecting component styles.\n\n## Common Failure Modes\n\n- a component hard-codes colors that should come from the active theme\n- a new built-in theme is added without keeping default-theme helpers valid\n- theme state is read outside `SambeeThemeProvider`\n- a persistence change breaks fallback to the default theme\n- built-in theme updates and custom theme persistence start overwriting each other\n- contributors treat selector labels as static strings instead of localized UI copy\n\n## Validation Expectations\n\nWhen the theming system changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nPay particular attention to:\n\n- theme-provider tests under `frontend/src/theme/__tests__/`\n- built-in-theme and default-theme tests\n- `types.test.ts` coverage around `THEME_SCHEMA`\n- theme-selector tests under `frontend/src/components/__tests__/`\n- manual checks that text remains readable in both built-in themes\n\n## Where to Continue\n\n- [Frontend Overview](../frontend-overview/): broader browser-app structure and the place of theme behavior in the frontend\n- [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/): another shared frontend subsystem with central configuration and runtime binding\n- [Localization and Locale Behavior](../../cross-cutting-systems/localization-and-locale-behavior/): shared UI-system rules that often change alongside settings and preferences surfaces\n", "2.0": "+++\ntitle = \"Theming System and Theme Selection\"\n+++\n\nSambee has two built-in themes (`sambee-light` and `sambee-dark`), user-owned themes, and administrator-managed site themes. Built-in IDs stay stable across upgrades, so updating their palettes doesn't change anyone's selection.\n\n## Theme Data\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/theme/types.ts` | Palette types and editor field labels |\n| `frontend/src/theme/themes.ts` | Built-in definitions with stable IDs |\n| `frontend/src/theme/themeDefinition.ts` | Editable color catalog, hex checks, and versioned import/export |\n| `frontend/src/theme/resolveSyntaxTheme.ts` | Non-mutating legacy syntax defaults and strict supplied-palette validation |\n| `frontend/src/theme/syntaxStyles.ts` | Shared token classes and locally inherited syntax variables |\n| `frontend/src/theme/palette.ts` | Shared effective palette for the app |\n| `frontend/src/theme/viewerStyles.ts` | Viewer and Markdown document surfaces |\n| `frontend/src/theme/ThemeContext.tsx` | Registry refresh and Material UI theme |\n| `frontend/src/pages/PreferencesSettings.tsx` | Selection grid and selected-theme actions |\n| `frontend/src/components/Settings/ThemeEditorDialog.tsx` | Responsive theme editor |\n| `backend/app/api/themes.py` | Validated theme operations and site default |\n\nEach editable theme has its own server row with a globally unique ID, scope, owner (for user themes), and version. Built-in definitions remain in frontend code. A new theme ID is assigned by the server; an ID in an imported file does not claim or replace a stored theme.\n\nColors use `#RRGGBB` or `#RRGGBBAA`; the server normalizes valid hex to uppercase. The role catalog includes primary, backgrounds, text, selection, links, viewer surfaces, Markdown document surfaces, syntax, search highlights, and alerts. File-type icons aren't theme roles. Derived colors such as scrollbar shades, focus rings, and `background.paper` compatibility aren't editor fields. Keyboard focus rings follow the theme's primary text color: 57% opacity in light mode and 94% in dark mode. Changing that text color changes the focus color too, including in copied themes; legacy saved focus colors are ignored. Choose primary text that remains readable against the theme's surfaces.\n\nEvery existing editable role remains required. The additive `components.syntax` group has eight roles: `keyword`, `string`, `number`, `comment`, `type`, `function`, `operator`, and `punctuation`. If the entire group is absent from a stored definition or version-1 import, the frontend resolves the matching built-in light/dark palette without mutating or saving the original. A supplied group must contain exactly all eight valid colors; partial groups, nulls, unknown keys, and invalid colors are rejected by both frontend and backend. Save, copy, and export include the resolved group through the existing API and version-1 envelope. No database migration or separate syntax preferences are needed. Older application releases may reject these newer exports.\n\n## Selection And Defaults\n\n`SambeeThemeProvider` combines built-ins with the current user's themes and shared site themes from `GET /api/themes`. The per-user selection is saved separately through `appearance.theme_id` in `PUT /api/auth/me/settings`. The backend reports whether that value is an explicit override.\n\nA user without an override follows the site default (initially `sambee-light`). A user who explicitly chooses `sambee-light` keeps that ID even if an administrator changes the site default. The selected ID points at a theme definition, never at a frozen copy of a built-in. The provider refreshes shared themes, the default, and user settings on initial load, tab focus, visibility return, and local writes. It discards out-of-date responses when the account changes.\n\nAppearance settings display Your themes, Site themes, then Built-in themes. Clicking a tile or selecting its radio applies the theme and creates an explicit user override, even when it already matches the site default. Moving focus between radios doesn't change the applied theme or the target of Copy, Edit, Delete, and Set as default. The Default chip is distinct from the selected radio. Copy keeps writable themes in their group and copies read-only themes into Your themes without applying the copy. Editing read-only themes permits inspection and Save copy, but not Save. Only an administrator can save or delete site themes or make a built-in or site theme the default.\n\n## Editing And Persistence\n\nThe editor uses a responsive dialog with collapsible color groups. A swatch opens an alpha-aware picker and each color has an editable hex field. Invalid text stays in the field without changing the valid draft. Changes in the editor aren't applied to the app until Save succeeds; Cancel discards the draft. Import replaces only the draft after validating a versioned JSON definition, and Export writes the same format.\n\n`POST /api/themes` creates a theme. Save copy opens a destination menu with Your themes for everyone and Site themes for administrators. It always creates a new theme in the chosen group without changing the applied selection. If its name already exists in that group, the editor adds ` (copy)` or a numbered copy suffix. Save updates only the opened theme in its existing group and cannot create a copy. `PUT /api/themes/{id}` and `DELETE /api/themes/{id}?version=...` require the version read by the client; a stale version returns HTTP 409. The server checks ownership, admin permissions, names, IDs, and palette completeness before committing. Bulk writes to `appearance.custom_themes` are no longer supported. Legacy syntax compatibility is limited to an entirely absent syntax group; it doesn't repair incomplete older definitions.\n\nDeleting a theme clears explicit selections referencing it. If it was the site default, that setting is cleared too; users without an override then fall back to Sambee light. An explicit selection of another theme is unaffected.\n\n## Component Guidance\n\nPrefer the effective colors in `resolveThemePalette` and the MUI palette to hard-coded surfaces. `background.default` is the normal application surface; `background.paper` resolves to the same value for MUI compatibility. Dark chrome and dialogs use the editable `background.chrome` role. Markdown code, tables, blockquotes, and heading borders use the built-in theme's explicit document colors.\n\nViewer toolbar foreground variants, scrollbars, and subdued states can still derive opacity-adjusted values from their source color. Keep fixed colors for assets and file-type icons separate from the editor palette.\n\n## Shared Syntax Highlighting\n\nText viewing/editing, Markdown source and rendered Markdown fences share the CodeMirror language registry and tag mapping in `codeMirrorHighlightingCore.ts`. `syntaxHighlighting.ts` defines application-owned language IDs, UTF-16 token ranges, categories and explicit plain-text outcomes. Native editors and the syntax worker reuse that implementation. Fence aliases resolve to existing lazy grammars, including `mssql` to MS SQL and `mariadb` to MariaDB SQL. A `.sql` filename continues to select standard SQL; unknown fence labels aren't guessed.\n\nThe live Markdown viewer collects exact code occurrences from ReactMarkdown's existing AST, without another collection parse or embedded editors. A dedicated cancellable worker prepares syntax sequentially with acknowledged source chunks of at most 16,384 UTF-16 units and result pages of at most 512 ranges. Blocks above 100,000 UTF-16 units stay plain text. Nested Markdown fences use the configured Markdown parser, up to four Markdown levels including the outer block. Unknown, unlabelled and explicit plain-text fences remain neutral. A nested grammar load failure, or a parser error during static fence startup or advancement, leaves only the failed fence plain while retaining enclosing Markdown structure and successful siblings. The static adapter doesn't mutate cached grammars or retry parsing; later fences and preparations can still succeed. Closing during a pending grammar load terminates the generation's worker; reopening starts a fresh preparation. Cancellation still propagates, and exceeding the nesting limit intentionally keeps the whole outer block plain without suppressing unrelated blocks. There's no aggregate document-length or block-count cutoff. The pre-app browser capability gate requires the Web Worker API; Worker-less app operation isn't supported. The helper's defensive main-thread fallback isn't a supported browser mode or a responsiveness guarantee.\n\nEach preview generation owns cancellation and stale-result guards. After all requested blocks finish, the viewer paints at most 4,000 viewport syntax ranges through CSS Highlights. Vertical and horizontal clipping avoid publishing off-screen token ranges; scrolling, viewport resize, image loads and font readiness refresh presentation. Publication doesn't replace text nodes or insert token spans, preserving native text, whitespace, selection and the cached preview-search index. Missing highlight/visibility capabilities leave syntax plain instead of falling back to token DOM mutation. Disposal removes owned highlights, style, observers, listeners and queued frames. First visible syntax, complete preparation, memory and native interaction acceptance remain separate rollout gates; see [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/).\n\nThe existing theme provider installs stable application token rules once. Viewer/editor surfaces publish locally inherited CSS variables from the resolved MUI syntax palette, so changing theme colors doesn't require reparsing code or replacing token DOM. Identifiers and neutral code inherit the existing code foreground. Markdown source headings and structural markers use `keyword`; links use the existing link role; inline code uses the existing code foreground. Emphasis, strong text, and strikethrough change only their corresponding semantic treatment, not source font sizes or line geometry. Embedded code uses code categories, not Markdown prose styling.\n\nThe shared mapping also preserves built-ins, properties and keys, booleans, null, regular expressions, escapes, and metadata/directives when the grammar supplies those tags. `TOKEN_COLOR_ROLES` maps these categories to the existing eight syntax colors: built-ins use `function`; properties and regular expressions use `type`; booleans, null, and metadata use `keyword`; escapes use `operator`. Editors and rendered fences share this mapping without another parse or a theme schema change. Built-in names aren't necessarily commands, and grammar classifications vary: PowerShell variables and bare words can both remain neutral identifiers. There are no language-specific classification overrides.\n\nSearch matches use the viewer text foreground instead of syntax colors so matched keywords remain readable against their highlight backgrounds. Source editors apply that foreground to the match and its nested tokens. Preview search inherits `--sambee-search-foreground` from its own viewer; syntax highlights have priority -1, ordinary search highlights 0, and the current match 1. The shared search-color helper preserves the configured hues and uses 30%/36% opacity for ordinary/current matches in light mode and 40%/44% in dark mode. Custom theme validation checks color format and completeness, not contrast; choose text, syntax and surface colors that remain readable after alpha blending.\n\nTheme updates and lazy grammar completion preserve native selection, the active search match and both scroll axes on all four surfaces. Theme changes don't restart syntax preparation or renormalize unchanged Markdown. Late grammar completion can update editor token spans, while preview publication retains its original text nodes. These state guarantees don't establish scrolling performance, native clipboard behavior or close/navigation acceptance.\n\nReplacing an editor doesn't require replacing static highlighting. Replacing the engine requires preserving the application range/outcome contract, aliases where supported, and viewer lifecycle. Classification parity with a different engine isn't automatic. Removing CodeMirror entirely also requires migrating native editor integrations such as commands, autocomplete, and tables.\n\n## Verification\n\nRun focused theme tests and the project checks after changing the palette, API, or editor:\n\n```bash\ncd frontend \u0026\u0026 npm run test -- src/theme/__tests__ src/pages/__tests__/PreferencesSettings.test.tsx\ncd frontend \u0026\u0026 npm run build \u0026\u0026 npm run lint\ncd backend \u0026\u0026 .venv/bin/python -m pytest tests/test_user_settings.py\n```\n\nCheck the Appearance grid and editor on a phone and desktop in both built-in modes. Verify selection and saved-theme refresh after focus, color picker keyboard use and placement, alpha values and export, Cancel without applying the draft, and stale-save feedback.\n\nFor the production theme-dialog browser regressions, build the frontend first and keep the existing frontend/backend dev servers running. From `frontend/`, run:\n\n```bash\nSAMBEE_E2E_PRODUCTION=1 npm run test:e2e:all -- --grep 'production syntax theme dialog' --workers=1\n```\n\nThe suite serves built assets and intercepts theme APIs at `http://localhost:3000/browse/smb/demo`; it doesn't change stored themes. Chromium and Firefox cover save/cancel/copy, validation focus, personal/site/built-in permissions, alpha values, unchanged selection after copying, and rejected-save feedback at 1543x900 and 390x600. Narrow desktop viewports don't replace testing on a physical phone or with assistive technology.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/frontend-architecture/file-browser-and-navigation-model", "parent_id": "section:developer-guide/frontend-architecture", "depth": 2, "kind": "page", "label": "file-browser-and-navigation-model", "title": "File Browser And Navigation Model", "path": "developer-guide/frontend-architecture/file-browser-and-navigation-model", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "branched", "source_version": "0.7", "diff_added": 71, "diff_removed": 20}}, "content_versions": {"0.7": "+++\ntitle = \"File Browser and Navigation Model\"\n+++\n\nThe file browser is the densest browser-side product surface in Sambee. It combines navigation, selection, editing entry points, viewer launch, keyboard behavior, and real-time directory refresh.\n\n## Core Component Split\n\nThe implementation is deliberately split between shared page logic and per-pane logic.\n\n| Area | Responsibility |\n|---|---|\n| `pages/FileBrowser.tsx` | owns shared browser-level concerns such as active pane routing, URL sync, WebSocket lifecycle, and global shortcut registration |\n| `pages/FileBrowser/useFileBrowserPane.ts` | owns per-pane state such as connection and path, selection, sorting, filtering, dialogs, viewer state, incremental search, and directory refresh handling |\n| `pages/FileBrowser/FileBrowserPane.tsx` | renders one pane's UI |\n| `components/FileBrowser/CopyMoveDialog.tsx` | manages copy and move confirmation flow |\n| `config/keyboardShortcuts.ts` | central shortcut definitions used across the browser |\n\nThis split matters because two visible panes still need one coherent browser workflow.\n\nThe parent-versus-hook split is intentional:\n\n- `FileBrowser.tsx` owns shared state such as the connections list, active-pane routing, responsive layout, WebSocket connection lifecycle, and browser-level shortcut registration\n- `useFileBrowserPane.ts` owns per-pane state such as file loading, sort and filter state, viewer and dialog state, focus handling, multi-select state, and pane-specific directory-change reactions\n\n## Pane Model\n\nSambee supports one-pane and two-pane browsing, but the two-pane implementation is intentional rather than conditional duplication.\n\n- the left pane is always active in routing terms\n- the right pane is still instantiated even when not visible, which keeps the hook model stable\n- the active pane decides which pane keyboard shortcuts and toolbar commands target\n- dual-pane mode is desktop-first and collapses to single-pane on compact layouts\n- dual-pane preference and active-pane preference are persisted so the browser can restore the user's working style\n- the viewer opens as a fullscreen overlay from whichever pane launched it rather than being constrained to one pane region\n\nVisual state also matters:\n\n- the active pane gets the stronger emphasis treatment\n- the inactive pane is visually de-emphasized rather than treated as a separate route or different screen\n\n## URL-Synced Navigation\n\nThe file browser preserves layout state in the URL.\n\n- the primary pane stays in the path\n- the right pane is represented by the `p2` query parameter\n- active pane state is represented by the `active` query parameter\n\nThat design means refresh and back-forward navigation preserve more than a single path string.\n\nRepresentative shape:\n\n```text\nSingle pane: /browse/my-server/documents/subfolder\nDual pane:   /browse/my-server/documents?p2=other-server/photos\u0026active=2\n```\n\nImportant behavior:\n\n- the presence of `p2` on initial load activates dual-pane mode automatically\n- back and forward navigation can add or remove the second pane without changing the route definition itself\n- single-pane mode produces a clean URL without stale dual-pane query state\n- invalid right-pane connection slugs are ignored rather than breaking the whole browser route\n- the encoding model preserves slash-separated paths while still percent-encoding the path segments safely\n\n## Keyboard and Command Model\n\nKeyboard behavior is part of the product contract, not just convenience.\n\n- pane switching, selection, copy, and move use centralized shortcut definitions\n- the quick bar supports smart navigation, command mode, and pane-local current-directory filtering\n- browser defaults that conflict with the product's navigation model are overridden intentionally\n- shortcuts are disabled when dialogs or viewer states would make them unsafe\n\nChanges here can easily affect power-user workflows, accessibility, and focus management all at once.\n\nUse [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for the central registry, command-palette rules, and quick-bar interaction details. This page focuses on how those rules shape the file-browser architecture.\n\n## Pane-Local Current-Directory Filtering\n\nCurrent-directory filtering is part of pane state, not just quick-bar UI state.\n\nThe important design choice is that the quick bar only supplies the input shell. The actual filter value and filtered list live in `useFileBrowserPane`.\n\n- each pane owns its own `currentDirectoryFilter`\n- the pane computes `sortedAndFilteredFiles` from the normal sorted list plus the active filter text\n- the filtered list is the same list used by the virtualizer, keyboard navigation, viewer launch, selection helpers, and status bar\n- the active filter is considered scoped to the pane's current `connectionId + path`\n\nThat arrangement is what makes the behavior consistent in both single-pane and dual-pane workflows.\n\n### Why the Filter Lives in the Pane Hook\n\nThe filter is not modeled as a dropdown provider result set.\n\n- smart navigation is a navigation surface that benefits from dropdown results\n- command mode is a command surface that benefits from dropdown results\n- current-directory filtering is a local transformation of the pane's main file list\n\nBecause the pane already owns the rendered list, focus state, virtualizer, and file actions, the filter belongs there as well.\n\n### User-Facing Behavior the Architecture Must Preserve\n\nThe implemented flow is:\n\n1. `Ctrl+Alt+F` opens filter mode for the active pane.\n2. The shared input shows that pane's current filter value.\n3. Typing immediately filters the pane's main file list.\n4. `ArrowDown` from the input focuses the filtered file list.\n5. Arrow keys, `Home`, `End`, `PageUp`, `PageDown`, `Enter`, and file actions operate on the filtered visible list.\n6. Pressing `Ctrl+Alt+F` again returns focus to the same pane's filter input without clearing the term.\n\nReset and persistence rules are equally important:\n\n- switching between smart navigation, command mode, and filter mode does not clear the active filter\n- changing directories clears the filter for the new path scope\n- changing the pane connection also clears the filter\n- dual-pane mode keeps filter state isolated per pane\n- browser recovery snapshots capture and restore the pane filter together with path, focused item, and selection state\n\n### Focus and Zero-Result Behavior\n\nFiltering changes focus semantics because it can remove rows from the visible list.\n\n- if the previously focused file still exists in the filtered list, focus stays on that file\n- if it disappears, focus clamps to the nearest valid visible item\n- if the filter produces zero visible files, focus remains in the filter input when possible\n\nThat is why the pane hook owns both the filtered list and the focus-adjustment logic.\n\n### Status Bar Visibility\n\nThe filter must remain visible even when the quick bar is no longer in filter mode.\n\n- the desktop status bar renders the active filter term whenever the pane has a non-empty filter\n- the status bar uses the filtered visible list for item counts and file metadata\n- this keeps the active filter visible while the user switches to smart navigation or command mode\n\nThe status bar indicator is part of the product contract, not just decorative UI. It is the persistent signal that the pane is still filtered.\n\n## Selection, Copy, and Move\n\nThe browser maintains explicit multi-select state per pane, but still supports a focused-item fallback when nothing is explicitly selected.\n\nIn practice, the pane computes an effective selection from either:\n\n- the explicit selected-file set\n- or the focused file when nothing has been explicitly selected\n\nSelection is pane-local and clears naturally when directory navigation changes the active file list.\n\nCopy and move behavior depends on:\n\n- the active pane as the source\n- the other pane as the destination in dual-pane workflows\n- backend or companion routing depending on which connection types are involved\n- conflict and validation behavior that still comes from the destination backend contract\n\nThe copy and move dialog is not just a confirmation prompt. It also:\n\n- shows the selected source files\n- pre-fills the destination from the other pane\n- lets the user adjust the destination before confirming\n- reports progress while multiple operations execute\n\nImportant contract details:\n\n- `F5` means copy in dual-pane mode, but remains refresh in single-pane mode\n- `F6` means move in dual-pane mode\n- cross-connection operations are not treated the same as same-share SMB operations\n- backend validation still decides whether same-path, self-copy, or conflicting operations are allowed\n\nFor same-connection SMB copy and move, the backend uses server-side operations rather than streaming all file bytes through the browser app.\n\n## Refresh and Live State\n\nDirectory freshness is coordinated through WebSocket subscriptions.\n\n- the browser subscribes to each visible pane's directory\n- directory-change messages are routed back to the matching pane\n- local-drive and SMB-backed directories can use different backends while still feeding one browser experience\n\nIn dual-pane mode, both panes are live participants in refresh behavior:\n\n- each pane can subscribe to a different directory\n- each pane re-subscribes when its own path changes\n- directory-change events are dispatched back to the pane that owns the matching path and connection context\n\nThis is why navigation and data freshness are coupled more tightly than they first appear.\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome file-browser behaviors are deliberate tradeoffs rather than incidental implementation detail.\n\n- the UI caps visible panes at two even though the query-key pattern could theoretically scale further\n- browser-default shortcuts such as tab switching are overridden when they conflict with the product's pane model\n- dual-pane mode is disabled on compact layouts instead of forcing a cramped mobile approximation\n- one pane can stay hidden while still existing in state so the hook model remains stable\n\n## Why This Page Matters\n\nFrontend changes in the file browser often look local, but they can break:\n\n- URL-restoration behavior\n- keyboard and focus contracts\n- copy and move flows\n- viewer launch behavior\n- local-drive versus SMB routing assumptions\n- refresh behavior across both panes\n\n## Where to Continue\n\n- Use [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for centralized shortcut definitions, command-palette behavior, and focus rules.\n- Use [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/) for preview and file-type behavior.\n- Use [Browser-to-Companion Trust Model](../../companion-architecture/browser-to-companion-trust-model/) when navigation or actions depend on paired local-drive access.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when changes cross backend, frontend, and companion boundaries.\n", "0.8": "+++\ntitle = \"File Browser and Navigation Model\"\n+++\n\nThe file browser is the densest browser-side product surface in Sambee. It combines navigation, selection, editing entry points, viewer launch, keyboard behavior, and real-time directory refresh.\n\n## Core Component Split\n\nThe implementation is deliberately split between shared page logic and per-pane logic.\n\n| Area | Responsibility |\n|---|---|\n| `pages/FileBrowser.tsx` | owns shared browser-level concerns such as active pane routing, URL sync, WebSocket lifecycle, and global shortcut registration |\n| `pages/FileBrowser/useFileBrowserPane.ts` | owns per-pane state such as connection and path, selection, sorting, filtering, dialogs, viewer state, incremental search, and directory refresh handling |\n| `pages/FileBrowser/FileBrowserPane.tsx` | renders one pane's UI |\n| `components/FileBrowser/CopyMoveDialog.tsx` | manages copy and move confirmation flow |\n| `config/keyboardShortcuts.ts` | central shortcut definitions used across the browser |\n\nThis split matters because two visible panes still need one coherent browser workflow.\n\nThe parent-versus-hook split is intentional:\n\n- `FileBrowser.tsx` owns shared state such as the connections list, active-pane routing, responsive layout, WebSocket connection lifecycle, and browser-level shortcut registration\n- `useFileBrowserPane.ts` owns per-pane state such as file loading, sort and filter state, viewer and dialog state, focus handling, multi-select state, and pane-specific directory-change reactions\n\n## Pane Model\n\nSambee supports one-pane and two-pane browsing, but the two-pane implementation is intentional rather than conditional duplication.\n\n- the left pane is always active in routing terms\n- the right pane is still instantiated even when not visible, which keeps the hook model stable\n- the active pane decides which pane keyboard shortcuts and toolbar commands target\n- dual-pane mode is desktop-first and collapses to single-pane on compact layouts\n- dual-pane preference and active-pane preference are persisted so the browser can restore the user's working style\n- the viewer opens as a fullscreen overlay from whichever pane launched it rather than being constrained to one pane region\n\nVisual state also matters:\n\n- the active pane gets the stronger emphasis treatment\n- the inactive pane is visually de-emphasized rather than treated as a separate route or different screen\n\n## URL-Synced Navigation\n\nThe file browser preserves layout state in the URL.\n\n- the primary pane stays in the path\n- the right pane is represented by the `p2` query parameter\n- active pane state is represented by the `active` query parameter\n\nThat design means refresh and back-forward navigation preserve more than a single path string.\n\nRepresentative shape:\n\n```text\nSingle pane: /browse/my-server/documents/subfolder\nDual pane:   /browse/my-server/documents?p2=other-server/photos\u0026active=2\n```\n\nImportant behavior:\n\n- the presence of `p2` on initial load activates dual-pane mode automatically\n- back and forward navigation can add or remove the second pane without changing the route definition itself\n- single-pane mode produces a clean URL without stale dual-pane query state\n- invalid right-pane connection slugs are ignored rather than breaking the whole browser route\n- the encoding model preserves slash-separated paths while still percent-encoding the path segments safely\n\n## Keyboard and Command Model\n\nKeyboard behavior is part of the product contract, not just convenience.\n\n- pane switching, selection, copy, and move use centralized shortcut definitions\n- the quick bar supports smart navigation, command mode, and pane-local current-directory filtering\n- browser defaults that conflict with the product's navigation model are overridden intentionally\n- shortcuts are disabled when dialogs or viewer states would make them unsafe\n\nChanges here can easily affect power-user workflows, accessibility, and focus management all at once.\n\nUse [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for the central registry, command-palette rules, and quick-bar interaction details. This page focuses on how those rules shape the file-browser architecture.\n\n## Pane-Local Current-Directory Filtering\n\nCurrent-directory filtering is part of pane state, not just quick-bar UI state.\n\nThe important design choice is that the quick bar only supplies the input shell. The actual filter value and filtered list live in `useFileBrowserPane`.\n\n- each pane owns its own `currentDirectoryFilter`\n- the pane computes `sortedAndFilteredFiles` from the normal sorted list plus the active filter text\n- the filtered list is the same list used by the virtualizer, keyboard navigation, viewer launch, selection helpers, and status bar\n- the active filter is considered scoped to the pane's current `connectionId + path`\n\nThat arrangement is what makes the behavior consistent in both single-pane and dual-pane workflows.\n\n### Why the Filter Lives in the Pane Hook\n\nThe filter is not modeled as a dropdown provider result set.\n\n- smart navigation is a navigation surface that benefits from dropdown results\n- command mode is a command surface that benefits from dropdown results\n- current-directory filtering is a local transformation of the pane's main file list\n\nBecause the pane already owns the rendered list, focus state, virtualizer, and file actions, the filter belongs there as well.\n\n### User-Facing Behavior the Architecture Must Preserve\n\nThe implemented flow is:\n\n1. `Ctrl+Alt+F` opens filter mode for the active pane.\n2. The shared input shows that pane's current filter value.\n3. Typing immediately filters the pane's main file list.\n4. `ArrowDown` from the input focuses the filtered file list.\n5. Arrow keys, `Home`, `End`, `PageUp`, `PageDown`, `Enter`, and file actions operate on the filtered visible list.\n6. Pressing `Ctrl+Alt+F` again returns focus to the same pane's filter input without clearing the term.\n\nReset and persistence rules are equally important:\n\n- switching between smart navigation, command mode, and filter mode does not clear the active filter\n- changing directories clears the filter for the new path scope\n- changing the pane connection also clears the filter\n- dual-pane mode keeps filter state isolated per pane\n- browser recovery snapshots capture and restore the pane filter together with path, focused item, and selection state\n\n### Focus and Zero-Result Behavior\n\nFiltering changes focus semantics because it can remove rows from the visible list.\n\n- if the previously focused file still exists in the filtered list, focus stays on that file\n- if it disappears, focus clamps to the nearest valid visible item\n- if the filter produces zero visible files, focus remains in the filter input when possible\n\nThat is why the pane hook owns both the filtered list and the focus-adjustment logic.\n\n### Status Bar Visibility\n\nThe filter must remain visible even when the quick bar is no longer in filter mode.\n\n- the desktop status bar renders the active filter term whenever the pane has a non-empty filter\n- the status bar uses the filtered visible list for item counts and file metadata\n- this keeps the active filter visible while the user switches to smart navigation or command mode\n\nThe status bar indicator is part of the product contract, not just decorative UI. It is the persistent signal that the pane is still filtered.\n\n## Selection, Copy, and Move\n\nThe browser maintains explicit multi-select state per pane, but still supports a focused-item fallback when nothing is explicitly selected.\n\nIn practice, the pane computes an effective selection from either:\n\n- the explicit selected-file set\n- or the focused file when nothing has been explicitly selected\n\nSelection is pane-local and clears naturally when directory navigation changes the active file list.\n\nCopy and move behavior depends on:\n\n- the active pane as the source\n- the other pane as the destination in dual-pane workflows\n- backend or companion routing depending on which connection types are involved\n- conflict and validation behavior that still comes from the destination backend contract\n\nThe copy and move dialog is not just a confirmation prompt. It also:\n\n- shows the selected source files\n- pre-fills the destination from the other pane\n- lets the user adjust the destination before confirming\n- reports progress while multiple operations execute\n\nImportant contract details:\n\n- `F5` means copy in dual-pane mode, but remains refresh in single-pane mode\n- `F6` means move in dual-pane mode\n- cross-connection operations are not treated the same as same-share SMB operations\n- backend validation still decides whether same-path, self-copy, or conflicting operations are allowed\n\nFor same-connection SMB copy and move, the backend uses server-side operations rather than streaming all file bytes through the browser app.\n\n## Refresh and Live State\n\nDirectory freshness is coordinated through WebSocket subscriptions.\n\n- the browser subscribes to each visible pane's directory\n- directory-change messages are routed back to the matching pane\n- local-drive and SMB-backed directories can use different backends while still feeding one browser experience\n\nIn dual-pane mode, both panes are live participants in refresh behavior:\n\n- each pane can subscribe to a different directory\n- each pane re-subscribes when its own path changes\n- directory-change events are dispatched back to the pane that owns the matching path and connection context\n\nThis is why navigation and data freshness are coupled more tightly than they first appear.\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome file-browser behaviors are deliberate tradeoffs rather than incidental implementation detail.\n\n- the UI caps visible panes at two even though the query-key pattern could theoretically scale further\n- browser-default shortcuts such as tab switching are overridden when they conflict with the product's pane model\n- dual-pane mode is disabled on compact layouts instead of forcing a cramped mobile approximation\n- one pane can stay hidden while still existing in state so the hook model remains stable\n\n## Why This Page Matters\n\nFrontend changes in the file browser often look local, but they can break:\n\n- URL-restoration behavior\n- keyboard and focus contracts\n- copy and move flows\n- viewer launch behavior\n- local-drive versus SMB routing assumptions\n- refresh behavior across both panes\n\n## Where to Continue\n\n- Use [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for centralized shortcut definitions, command-palette behavior, and focus rules.\n- Use [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/) for preview and file-type behavior.\n- Use [Browser-to-Companion Trust Model](../../companion-architecture/browser-to-companion-trust-model/) when navigation or actions depend on paired local-drive access.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when changes cross backend, frontend, and companion boundaries.\n", "0.9": "+++\ntitle = \"File Browser and Navigation Model\"\n+++\n\nThe file browser is the densest browser-side product surface in Sambee. It combines navigation, selection, editing entry points, viewer launch, keyboard behavior, and real-time directory refresh.\n\n## Core Component Split\n\nThe implementation is deliberately split between shared page logic and per-pane logic.\n\n| Area | Responsibility |\n|---|---|\n| `pages/FileBrowser.tsx` | owns shared browser-level concerns such as active pane routing, URL sync, WebSocket lifecycle, and global shortcut registration |\n| `pages/FileBrowser/useFileBrowserPane.ts` | owns per-pane state such as connection and path, selection, sorting, filtering, dialogs, viewer state, incremental search, and directory refresh handling |\n| `pages/FileBrowser/FileBrowserPane.tsx` | renders one pane's UI |\n| `components/FileBrowser/CopyMoveDialog.tsx` | manages copy and move confirmation flow |\n| `config/keyboardShortcuts.ts` | central shortcut definitions used across the browser |\n\nThis split matters because two visible panes still need one coherent browser workflow.\n\nThe parent-versus-hook split is intentional:\n\n- `FileBrowser.tsx` owns shared state such as the connections list, active-pane routing, responsive layout, WebSocket connection lifecycle, and browser-level shortcut registration\n- `useFileBrowserPane.ts` owns per-pane state such as file loading, sort and filter state, viewer and dialog state, focus handling, multi-select state, and pane-specific directory-change reactions\n\n## Pane Model\n\nSambee supports one-pane and two-pane browsing, but the two-pane implementation is intentional rather than conditional duplication.\n\n- the left pane is always active in routing terms\n- the right pane is still instantiated even when not visible, which keeps the hook model stable\n- the active pane decides which pane keyboard shortcuts and toolbar commands target\n- dual-pane mode is desktop-first and collapses to single-pane on compact layouts\n- dual-pane preference and active-pane preference are persisted so the browser can restore the user's working style\n- the viewer opens as a fullscreen overlay from whichever pane launched it rather than being constrained to one pane region\n\nVisual state also matters:\n\n- the active pane gets the stronger emphasis treatment\n- the inactive pane is visually de-emphasized rather than treated as a separate route or different screen\n\n## URL-Synced Navigation\n\nThe file browser preserves layout state in the URL.\n\n- the primary pane stays in the path\n- the right pane is represented by the `p2` query parameter\n- active pane state is represented by the `active` query parameter\n\nThat design means refresh and back-forward navigation preserve more than a single path string.\n\nRepresentative shape:\n\n```text\nSingle pane: /browse/my-server/documents/subfolder\nDual pane:   /browse/my-server/documents?p2=other-server/photos\u0026active=2\n```\n\nImportant behavior:\n\n- the presence of `p2` on initial load activates dual-pane mode automatically\n- back and forward navigation can add or remove the second pane without changing the route definition itself\n- single-pane mode produces a clean URL without stale dual-pane query state\n- invalid right-pane connection slugs are ignored rather than breaking the whole browser route\n- the encoding model preserves slash-separated paths while still percent-encoding the path segments safely\n\n## Keyboard and Command Model\n\nKeyboard behavior is part of the product contract, not just convenience.\n\n- pane switching, selection, copy, and move use centralized shortcut definitions\n- the quick bar supports smart navigation, command mode, and pane-local current-directory filtering\n- browser defaults that conflict with the product's navigation model are overridden intentionally\n- shortcuts are disabled when dialogs or viewer states would make them unsafe\n\nChanges here can easily affect power-user workflows, accessibility, and focus management all at once.\n\nUse [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for the central registry, command-palette rules, and quick-bar interaction details. This page focuses on how those rules shape the file-browser architecture.\n\n## Pane-Local Current-Directory Filtering\n\nCurrent-directory filtering is part of pane state, not just quick-bar UI state.\n\nThe important design choice is that the quick bar only supplies the input shell. The actual filter value and filtered list live in `useFileBrowserPane`.\n\n- each pane owns its own `currentDirectoryFilter`\n- the pane computes `sortedAndFilteredFiles` from the normal sorted list plus the active filter text\n- the filtered list is the same list used by the virtualizer, keyboard navigation, viewer launch, selection helpers, and status bar\n- the active filter is considered scoped to the pane's current `connectionId + path`\n\nThat arrangement is what makes the behavior consistent in both single-pane and dual-pane workflows.\n\n### Why the Filter Lives in the Pane Hook\n\nThe filter is not modeled as a dropdown provider result set.\n\n- smart navigation is a navigation surface that benefits from dropdown results\n- command mode is a command surface that benefits from dropdown results\n- current-directory filtering is a local transformation of the pane's main file list\n\nBecause the pane already owns the rendered list, focus state, virtualizer, and file actions, the filter belongs there as well.\n\n### User-Facing Behavior the Architecture Must Preserve\n\nThe implemented flow is:\n\n1. `Ctrl+Alt+F` opens filter mode for the active pane.\n2. The shared input shows that pane's current filter value.\n3. Typing immediately filters the pane's main file list.\n4. `ArrowDown` from the input focuses the filtered file list.\n5. Arrow keys, `Home`, `End`, `PageUp`, `PageDown`, `Enter`, and file actions operate on the filtered visible list.\n6. Pressing `Ctrl+Alt+F` again returns focus to the same pane's filter input without clearing the term.\n\nReset and persistence rules are equally important:\n\n- switching between smart navigation, command mode, and filter mode does not clear the active filter\n- changing directories clears the filter for the new path scope\n- changing the pane connection also clears the filter\n- dual-pane mode keeps filter state isolated per pane\n- browser recovery snapshots capture and restore the pane filter together with path, focused item, and selection state\n\n### Focus and Zero-Result Behavior\n\nFiltering changes focus semantics because it can remove rows from the visible list.\n\n- if the previously focused file still exists in the filtered list, focus stays on that file\n- if it disappears, focus clamps to the nearest valid visible item\n- if the filter produces zero visible files, focus remains in the filter input when possible\n\nThat is why the pane hook owns both the filtered list and the focus-adjustment logic.\n\n### Status Bar Visibility\n\nThe filter must remain visible even when the quick bar is no longer in filter mode.\n\n- the desktop status bar renders the active filter term whenever the pane has a non-empty filter\n- the status bar uses the filtered visible list for item counts and file metadata\n- this keeps the active filter visible while the user switches to smart navigation or command mode\n\nThe status bar indicator is part of the product contract, not just decorative UI. It is the persistent signal that the pane is still filtered.\n\n## Selection, Copy, and Move\n\nThe browser maintains explicit multi-select state per pane, but still supports a focused-item fallback when nothing is explicitly selected.\n\nIn practice, the pane computes an effective selection from either:\n\n- the explicit selected-file set\n- or the focused file when nothing has been explicitly selected\n\nSelection is pane-local and clears naturally when directory navigation changes the active file list.\n\nCopy and move behavior depends on:\n\n- the active pane as the source\n- the other pane as the destination in dual-pane workflows\n- backend or companion routing depending on which connection types are involved\n- conflict and validation behavior that still comes from the destination backend contract\n\nThe copy and move dialog is not just a confirmation prompt. It also:\n\n- shows the selected source files\n- pre-fills the destination from the other pane\n- lets the user adjust the destination before confirming\n- reports progress while multiple operations execute\n\nImportant contract details:\n\n- `F5` means copy in dual-pane mode, but remains refresh in single-pane mode\n- `F6` means move in dual-pane mode\n- cross-connection operations are not treated the same as same-share SMB operations\n- backend validation still decides whether same-path, self-copy, or conflicting operations are allowed\n\nFor same-connection SMB copy and move, the backend uses server-side operations rather than streaming all file bytes through the browser app.\n\n## Refresh and Live State\n\nDirectory freshness is coordinated through WebSocket subscriptions.\n\n- the browser subscribes to each visible pane's directory\n- directory-change messages are routed back to the matching pane\n- local-drive and SMB-backed directories can use different backends while still feeding one browser experience\n\nIn dual-pane mode, both panes are live participants in refresh behavior:\n\n- each pane can subscribe to a different directory\n- each pane re-subscribes when its own path changes\n- directory-change events are dispatched back to the pane that owns the matching path and connection context\n\nThis is why navigation and data freshness are coupled more tightly than they first appear.\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome file-browser behaviors are deliberate tradeoffs rather than incidental implementation detail.\n\n- the UI caps visible panes at two even though the query-key pattern could theoretically scale further\n- browser-default shortcuts such as tab switching are overridden when they conflict with the product's pane model\n- dual-pane mode is disabled on compact layouts instead of forcing a cramped mobile approximation\n- one pane can stay hidden while still existing in state so the hook model remains stable\n\n## Why This Page Matters\n\nFrontend changes in the file browser often look local, but they can break:\n\n- URL-restoration behavior\n- keyboard and focus contracts\n- copy and move flows\n- viewer launch behavior\n- local-drive versus SMB routing assumptions\n- refresh behavior across both panes\n\n## Where to Continue\n\n- Use [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for centralized shortcut definitions, command-palette behavior, and focus rules.\n- Use [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/) for preview and file-type behavior.\n- Use [Browser-to-Companion Trust Model](../../companion-architecture/browser-to-companion-trust-model/) when navigation or actions depend on paired local-drive access.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when changes cross backend, frontend, and companion boundaries.\n", "1.0": "+++\ntitle = \"File Browser and Navigation Model\"\n+++\n\nThe file browser is the densest browser-side product surface in Sambee. It combines navigation, selection, editing entry points, viewer launch, keyboard behavior, and real-time directory refresh.\n\n## Core Component Split\n\nThe implementation is deliberately split between shared page logic and per-pane logic.\n\n| Area | Responsibility |\n|---|---|\n| `pages/FileBrowser.tsx` | owns shared browser-level concerns such as active pane routing, URL sync, WebSocket lifecycle, and global shortcut registration |\n| `pages/FileBrowser/useFileBrowserPane.ts` | owns per-pane state such as connection and path, selection, sorting, filtering, dialogs, viewer state, incremental search, and directory refresh handling |\n| `pages/FileBrowser/FileBrowserPane.tsx` | renders one pane's UI |\n| `components/FileBrowser/CopyMoveDialog.tsx` | manages copy and move confirmation flow |\n| `config/keyboardShortcuts.ts` | central shortcut definitions used across the browser |\n\nThis split matters because two visible panes still need one coherent browser workflow.\n\nThe parent-versus-hook split is intentional:\n\n- `FileBrowser.tsx` owns shared state such as the connections list, active-pane routing, responsive layout, WebSocket connection lifecycle, and browser-level shortcut registration\n- `useFileBrowserPane.ts` owns per-pane state such as file loading, sort and filter state, viewer and dialog state, focus handling, multi-select state, and pane-specific directory-change reactions\n\n## Pane Model\n\nSambee supports one-pane and two-pane browsing, but the two-pane implementation is intentional rather than conditional duplication.\n\n- the left pane is always active in routing terms\n- the right pane is still instantiated even when not visible, which keeps the hook model stable\n- the active pane decides which pane keyboard shortcuts and toolbar commands target\n- dual-pane mode is desktop-first and collapses to single-pane on compact layouts\n- dual-pane preference and active-pane preference are persisted so the browser can restore the user's working style\n- the viewer opens as a fullscreen overlay from whichever pane launched it rather than being constrained to one pane region\n\nVisual state also matters:\n\n- the active pane gets the stronger emphasis treatment\n- the inactive pane is visually de-emphasized rather than treated as a separate route or different screen\n\n## URL-Synced Navigation\n\nThe file browser preserves layout state in the URL.\n\n- the primary pane stays in the path\n- the right pane is represented by the `p2` query parameter\n- active pane state is represented by the `active` query parameter\n\nThat design means refresh and back-forward navigation preserve more than a single path string.\n\nRepresentative shape:\n\n```text\nSingle pane: /browse/my-server/documents/subfolder\nDual pane:   /browse/my-server/documents?p2=other-server/photos\u0026active=2\n```\n\nImportant behavior:\n\n- the presence of `p2` on initial load activates dual-pane mode automatically\n- back and forward navigation can add or remove the second pane without changing the route definition itself\n- single-pane mode produces a clean URL without stale dual-pane query state\n- invalid right-pane connection slugs are ignored rather than breaking the whole browser route\n- the encoding model preserves slash-separated paths while still percent-encoding the path segments safely\n\n## Keyboard and Command Model\n\nKeyboard behavior is part of the product contract, not just convenience.\n\n- pane switching, selection, copy, and move use centralized shortcut definitions\n- the quick bar supports smart navigation, command mode, and pane-local current-directory filtering\n- browser defaults that conflict with the product's navigation model are overridden intentionally\n- shortcuts are disabled when dialogs or viewer states would make them unsafe\n\nChanges here can easily affect power-user workflows, accessibility, and focus management all at once.\n\nUse [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for the central registry, command-palette rules, and quick-bar interaction details. This page focuses on how those rules shape the file-browser architecture.\n\n## Pane-Local Current-Directory Filtering\n\nCurrent-directory filtering is part of pane state, not just quick-bar UI state.\n\nThe important design choice is that the quick bar only supplies the input shell. The actual filter value and filtered list live in `useFileBrowserPane`.\n\n- each pane owns its own `currentDirectoryFilter`\n- the pane computes `sortedAndFilteredFiles` from the normal sorted list plus the active filter text\n- the filtered list is the same list used by the virtualizer, keyboard navigation, viewer launch, selection helpers, and status bar\n- the active filter is considered scoped to the pane's current `connectionId + path`\n\nThat arrangement is what makes the behavior consistent in both single-pane and dual-pane workflows.\n\n### Why the Filter Lives in the Pane Hook\n\nThe filter is not modeled as a dropdown provider result set.\n\n- smart navigation is a navigation surface that benefits from dropdown results\n- command mode is a command surface that benefits from dropdown results\n- current-directory filtering is a local transformation of the pane's main file list\n\nBecause the pane already owns the rendered list, focus state, virtualizer, and file actions, the filter belongs there as well.\n\n### User-Facing Behavior the Architecture Must Preserve\n\nThe implemented flow is:\n\n1. `Ctrl+Alt+F` opens filter mode for the active pane.\n2. The shared input shows that pane's current filter value.\n3. Typing immediately filters the pane's main file list.\n4. `ArrowDown` from the input focuses the filtered file list.\n5. Arrow keys, `Home`, `End`, `PageUp`, `PageDown`, `Enter`, and file actions operate on the filtered visible list.\n6. Pressing `Ctrl+Alt+F` again returns focus to the same pane's filter input without clearing the term.\n\nReset and persistence rules are equally important:\n\n- switching between smart navigation, command mode, and filter mode does not clear the active filter\n- changing directories clears the filter for the new path scope\n- changing the pane connection also clears the filter\n- dual-pane mode keeps filter state isolated per pane\n- browser recovery snapshots capture and restore the pane filter together with path, focused item, and selection state\n\n### Focus and Zero-Result Behavior\n\nFiltering changes focus semantics because it can remove rows from the visible list.\n\n- if the previously focused file still exists in the filtered list, focus stays on that file\n- if it disappears, focus clamps to the nearest valid visible item\n- if the filter produces zero visible files, focus remains in the filter input when possible\n\nThat is why the pane hook owns both the filtered list and the focus-adjustment logic.\n\n### Status Bar Visibility\n\nThe filter must remain visible even when the quick bar is no longer in filter mode.\n\n- the desktop status bar renders the active filter term whenever the pane has a non-empty filter\n- the status bar uses the filtered visible list for item counts and file metadata\n- this keeps the active filter visible while the user switches to smart navigation or command mode\n\nThe status bar indicator is part of the product contract, not just decorative UI. It is the persistent signal that the pane is still filtered.\n\n## Selection, Copy, and Move\n\nThe browser maintains explicit multi-select state per pane, but still supports a focused-item fallback when nothing is explicitly selected.\n\nIn practice, the pane computes an effective selection from either:\n\n- the explicit selected-file set\n- or the focused file when nothing has been explicitly selected\n\nSelection is pane-local and clears naturally when directory navigation changes the active file list.\n\nCopy and move behavior depends on:\n\n- the active pane as the source\n- the other pane as the destination in dual-pane workflows\n- backend or companion routing depending on which connection types are involved\n- conflict and validation behavior that still comes from the destination backend contract\n\nThe copy and move dialog is not just a confirmation prompt. It also:\n\n- shows the selected source files\n- pre-fills the destination from the other pane\n- lets the user adjust the destination before confirming\n- reports progress while multiple operations execute\n\nImportant contract details:\n\n- `F5` means copy in dual-pane mode, but remains refresh in single-pane mode\n- `F6` means move in dual-pane mode\n- cross-connection operations are not treated the same as same-share SMB operations\n- backend validation still decides whether same-path, self-copy, or conflicting operations are allowed\n\nFor same-connection SMB copy and move, the backend uses server-side operations rather than streaming all file bytes through the browser app.\n\n## Refresh and Live State\n\nDirectory freshness is coordinated through WebSocket subscriptions.\n\n- the browser subscribes to each visible pane's directory\n- directory-change messages are routed back to the matching pane\n- local-drive and SMB-backed directories can use different backends while still feeding one browser experience\n\nIn dual-pane mode, both panes are live participants in refresh behavior:\n\n- each pane can subscribe to a different directory\n- each pane re-subscribes when its own path changes\n- directory-change events are dispatched back to the pane that owns the matching path and connection context\n\nThis is why navigation and data freshness are coupled more tightly than they first appear.\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome file-browser behaviors are deliberate tradeoffs rather than incidental implementation detail.\n\n- the UI caps visible panes at two even though the query-key pattern could theoretically scale further\n- browser-default shortcuts such as tab switching are overridden when they conflict with the product's pane model\n- dual-pane mode is disabled on compact layouts instead of forcing a cramped mobile approximation\n- one pane can stay hidden while still existing in state so the hook model remains stable\n\n## Why This Page Matters\n\nFrontend changes in the file browser often look local, but they can break:\n\n- URL-restoration behavior\n- keyboard and focus contracts\n- copy and move flows\n- viewer launch behavior\n- local-drive versus SMB routing assumptions\n- refresh behavior across both panes\n\n## Where to Continue\n\n- Use [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for centralized shortcut definitions, command-palette behavior, and focus rules.\n- Use [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/) for preview and file-type behavior.\n- Use [Browser-to-Companion Trust Model](../../companion-architecture/browser-to-companion-trust-model/) when navigation or actions depend on paired local-drive access.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when changes cross backend, frontend, and companion boundaries.\n", "2.0": "+++\ntitle = \"File Browser and Navigation Model\"\n+++\n\nThe file browser is the densest browser-side product surface in Sambee. It combines navigation, selection, editing entry points, viewer launch, keyboard behavior, and real-time directory refresh.\n\n## Core Component Split\n\nThe implementation is deliberately split between shared page logic and per-pane logic.\n\n| Area | Responsibility |\n|---|---|\n| `pages/FileBrowser.tsx` | owns shared browser-level concerns such as active pane routing, URL sync, WebSocket lifecycle, and global shortcut registration |\n| `pages/FileBrowser/useFileBrowserPane.ts` | owns per-pane state such as connection and path, selection, sorting, filtering, dialogs, viewer state, incremental search, and directory refresh handling |\n| `pages/FileBrowser/routing.ts` | parses and serializes typed directory, viewer, editor, and settings locations |\n| `pages/FileBrowser/useWorkspaceNavigation.ts` | resolves viewer targets and owns workspace navigation and safe overlay return entries |\n| `hooks/useRoutedViewerEditing.tsx` | connects the active editor's existing confirmation dialog to React Router navigation blocking |\n| `pages/FileBrowser/FileBrowserPane.tsx` | renders one pane's UI |\n| `components/FileBrowser/CopyMoveDialog.tsx` | manages copy and move confirmation flow |\n| `config/keyboardShortcuts.ts` | central shortcut definitions used across the browser |\n\nThis split matters because two visible panes still need one coherent browser workflow.\n\nThe parent-versus-hook split is intentional:\n\n- `FileBrowser.tsx` owns shared state such as the connections list, active-pane routing, responsive layout, WebSocket connection lifecycle, and browser-level shortcut registration\n- `useFileBrowserPane.ts` owns per-pane state such as file loading, sort and filter state, viewer and dialog state, focus handling, multi-select state, and pane-specific directory-change reactions\n\n## Pane Model\n\nSambee supports one-pane and two-pane browsing, but the two-pane implementation is intentional rather than conditional duplication.\n\n- the left pane is always active in routing terms\n- the right pane is still instantiated even when not visible, which keeps the hook model stable\n- the active pane decides which pane keyboard shortcuts and toolbar commands target\n- dual-pane mode is desktop-first and collapses to single-pane on compact layouts\n- dual-pane preference and active-pane preference are persisted so the browser can restore the user's working style\n- the viewer opens as a fullscreen overlay from whichever pane launched it rather than being constrained to one pane region\n\nVisual state also matters:\n\n- the active pane gets the stronger emphasis treatment\n- the inactive pane is visually de-emphasized rather than treated as a separate route or different screen\n\n## Real-Time Directory Refresh\n\nEach pane handles directory-change notifications independently. An automatic refresh keeps an already loaded physical-directory listing mounted, including an empty listing, so unchanged rows retain selection, keyboard focus, and scroll position. Initial loading and navigation without a usable snapshot still show loading feedback.\n\nNotifications don't cancel an active listing request. Instead, the pane remembers that another refresh is needed and starts one follow-up request after the active request finishes. Automatic refreshes start at most once per second. Further notifications don't move an existing deadline, so continuous writes still produce periodic updates. Navigation and unmount cancel queued work.\n\nA listing with unprocessed change notifications can remain visible, but it isn't cached as fresh. Deferred link-target metadata only updates cache entries that are still valid, so cancelling a follow-up refresh can't make an outdated snapshot reusable on return.\n\nSMB file-list subscriptions watch immediate children rather than the whole subtree. The separate backend directory-search cache retains recursive directory-name monitoring. See [SMB Change Notification and Directory Freshness](../../backend-architecture/smb-change-notification-and-directory-freshness/) for watcher ownership and lifecycle.\n\n## URL-Driven Workspace Navigation\n\nThe URL selects the directory, pane layout, viewer, editing intent, and settings view. The file browser stays mounted under overlays. Loaded content, drafts, locks, selection, scroll, search panels, and zoom remain runtime state.\n\n| Part | Meaning |\n|---|---|\n| `/browse/smb/\u003cslug\u003e/\u003cpath\u003e` | Primary SMB pane |\n| `/browse/local/\u003cdrive-id\u003e/\u003cpath\u003e` | Primary companion-drive pane |\n| `p2=\u003ckind\u003e/\u003ctarget\u003e/\u003cpath\u003e` | Right pane, enabled when present |\n| `active=2` | Right pane is active |\n| `file=\u003ckind\u003e/\u003ctarget\u003e/\u003cpath\u003e` | Viewer target, independent of the directory and active pane |\n| `viewer=image\\|markdown\\|pdf\\|text` | Requested browser viewer |\n| `mode=edit` | Editing intent for text or Markdown |\n| `pane=2` | Right pane owns the viewer; requires a right-pane target |\n| `virtual=\u003cJSON array\u003e` | Archive member descriptor: provider ID, source archive path, member path |\n| `settings=main\\|\u003ccategory\u003e` | Settings main view or category from the shared category registry |\n\nFor example:\n\n```text\n/browse/smb/my-server/documents\n/browse/smb/my-server/documents?p2=smb%2Fother-server%2Fphotos\u0026active=2\n/browse/smb/my-server/documents?file=smb%2Fmy-server%2Fdocuments%2Fnotes.md\u0026viewer=markdown\n/browse/smb/my-server/documents?file=smb%2Fmy-server%2Fdocuments%2Fnotes.md\u0026viewer=markdown\u0026mode=edit\n/browse/smb/my-server/documents?settings=account\n```\n\nUse the shared parser/serializer and `URLSearchParams`, not concatenated query strings. File descriptors encode target IDs and individual path segments before query serialization. The archive provider is currently `zip`. Runtime session IDs, file contents, MIME guesses, gallery arrays, credentials, and lock capabilities never belong in navigation state.\n\n### Navigation and Dismissal\n\nOpening or closing a viewer, entering or leaving editing, changing gallery images, opening or closing settings, and changing settings categories push history entries. Repeating the same location does nothing. Pane-focus updates, invalid-descriptor recovery, failed edit acquisition, and canonicalization replace the current entry. Unrelated query parameters and authentication fragments are preserved.\n\nBack and Forward follow actual history without adding entries. Explicit Close pushes the current workspace with the dismissed layer removed, including for direct links and refreshed viewers. For example, opening a directory, opening an image, and closing it produces directory, image, and directory entries; Back reopens the image before returning to the earlier directory entry. A new action after Back discards the old Forward branch, following normal browser behavior. Close doesn't depend on opening-entry metadata or `history.length`. Settings back controls traverse observed history; without an observed predecessor they replace the URL with an in-app parent.\n\nDesktop settings and the mobile drawer are controlled by the same category descriptor. `settings=main` displays the desktop default category or the mobile category list. Resizing changes presentation without navigation. Standalone `/settings/...` routes and their aliases use the same category content and authorization checks. User Management owns its query keys through React Router, merging them with workspace parameters.\n\n### Direct Links and Recovery\n\nViewer links resolve metadata through the storage registry or content provider, without simulated file-row clicks. Resolution is cancelled when its identity changes. Missing resources show Retry and Close actions. A viewer URL never falls back to opening a native application.\n\nThe incoming URL always wins over a browser recovery snapshot. Snapshot hydration matches each pane's resource identity, clears legacy viewer state, and ignores unmatched panes. A bare `/browse` uses normal default navigation. Captured snapshots use the current canonical workspace URL and contain neither callback fragments nor edit-session tokens.\n\n### Viewer Loading and Transitions\n\nLoading feedback belongs to the selected image, PDF, text, or Markdown viewer. Workspace metadata resolution and dynamic component imports do not show an intermediate full-screen loading dialog. On an initial opening, the browser remains visible until metadata and the viewer component are available; the viewer then displays its existing content-loading feedback.\n\nDuring file-to-file or history navigation, keep the outgoing viewer presentation mounted until the replacement metadata and component are ready. Do not expose the directory between viewers or pass the new target's props to the old viewer component. Outgoing controls and shortcuts are suspended during the handoff, while Escape can cancel the pending opening. The existing error dialogs retain Retry and Close actions. Cancellation rejects late results rather than reopening a dismissed viewer.\n\nOne dynamic viewer host serves both panes. An explicit viewer ID, not an image's changing MIME type, controls component loading. Text and Markdown still reset resource-local state when the actual file changes; mode-only and settings-only navigation do not restart the viewer.\n\n### Editing and Router Integrity\n\nThe app uses a data router (`createBrowserRouter` and `RouterProvider`) for supported `useBlocker` behavior. One guard owner delegates resource-leaving transitions to the active text or Markdown editor when its draft is dirty, a save is pending, or a session is being acquired. Clean editor Back and Forward navigate directly, avoiding the history reversal required by a blocked browser navigation. Cancel keeps the draft and lock; successful Save or Discard continues the original transition; failed Save keeps the editor open. Changes that retain the same edited resource and mode don't discard its draft. Dirty drafts also register `beforeunload` protection.\n\nEdit bookmarks and history navigation back into editing acquire a fresh edit session after content and permission checks. Navigating away during acquisition invalidates the attempt and releases any late lock. Leaving editing releases its session once. The outgoing editor is read-only during cleanup, and re-entry waits for that cleanup to finish so an old release can't clear a new session. History restores navigation intent, not old file contents, discarded drafts, or saved locks. An edit URL doesn't grant permission.\n\nFull page reloads, including F5 and the update prompt, can resume the same edit lock. The shared storage edit-session layer keeps lock credentials separately in tab-scoped session storage, keyed by user, connection, and file. On reload it validates those credentials with a heartbeat before reusing them. Only a structured lost-lock response permits fresh acquisition; network and permission failures don't trigger replacement. Credentials follow replacement locks and are removed on successful release or logout. Unsaved text still uses the existing draft-recovery flow.\n\nRecovery requires session storage and the browser Web Locks API, available in secure contexts such as HTTPS and localhost. An exclusive Web Lock prevents another tab from using copied recovery credentials, even if that tab reloads. Without those capabilities, editing still works, but a reload may need to wait for the abandoned server lock to expire. Fresh navigations and history entries don't resume saved credentials, and no credentials appear in the URL or workspace recovery snapshot.\n\nUse router navigation for all mounted-route URL writes, including authentication fragment cleanup. `useRemoveLocationFragment` replaces the entry, removes only consumed fragment keys, and preserves the full query and application state. Never clear router-managed history state with `replaceState(null, ...)`: doing so can disable POP blocking.\n\n## Keyboard and Command Model\n\nKeyboard behavior is part of the product contract, not just convenience.\n\n- pane switching, selection, copy, and move use centralized shortcut definitions\n- the quick bar supports smart navigation, command mode, and pane-local current-directory filtering\n- browser defaults that conflict with the product's navigation model are overridden intentionally\n- shortcuts are disabled when dialogs or viewer states would make them unsafe\n\nChanges here can easily affect power-user workflows, accessibility, and focus management all at once.\n\nUse [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for the central registry, command-palette rules, and quick-bar interaction details. This page focuses on how those rules shape the file-browser architecture.\n\n## Pane-Local Current-Directory Filtering\n\nCurrent-directory filtering is part of pane state, not just quick-bar UI state.\n\nThe important design choice is that the quick bar only supplies the input shell. The actual filter value and filtered list live in `useFileBrowserPane`.\n\n- each pane owns its own `currentDirectoryFilter`\n- the pane computes `sortedAndFilteredFiles` from the normal sorted list plus the active filter text\n- the filtered list is the same list used by the virtualizer, keyboard navigation, viewer launch, selection helpers, and status bar\n- the active filter is considered scoped to the pane's current `connectionId + path`\n\nThat arrangement is what makes the behavior consistent in both single-pane and dual-pane workflows.\n\n### Why the Filter Lives in the Pane Hook\n\nThe filter is not modeled as a dropdown provider result set.\n\n- smart navigation is a navigation surface that benefits from dropdown results\n- command mode is a command surface that benefits from dropdown results\n- current-directory filtering is a local transformation of the pane's main file list\n\nBecause the pane already owns the rendered list, focus state, virtualizer, and file actions, the filter belongs there as well.\n\n### User-Facing Behavior the Architecture Must Preserve\n\nThe implemented flow is:\n\n1. `Ctrl+Alt+F` opens filter mode for the active pane.\n2. The shared input shows that pane's current filter value.\n3. Typing immediately filters the pane's main file list.\n4. `ArrowDown` from the input focuses the filtered file list.\n5. Arrow keys, `Home`, `End`, `PageUp`, `PageDown`, `Enter`, and file actions operate on the filtered visible list.\n6. Pressing `Ctrl+Alt+F` again returns focus to the same pane's filter input without clearing the term.\n\nReset and persistence rules are equally important:\n\n- switching between smart navigation, command mode, and filter mode does not clear the active filter\n- changing directories clears the filter for the new path scope\n- changing the pane connection also clears the filter\n- dual-pane mode keeps filter state isolated per pane\n- browser recovery snapshots capture and restore the pane filter together with path, focused item, and selection state\n\n### Focus and Zero-Result Behavior\n\nFiltering changes focus semantics because it can remove rows from the visible list.\n\n- if the previously focused file still exists in the filtered list, focus stays on that file\n- if it disappears, focus clamps to the nearest valid visible item\n- if the filter produces zero visible files, focus remains in the filter input when possible\n\nThat is why the pane hook owns both the filtered list and the focus-adjustment logic.\n\n### Status Bar Visibility\n\nThe filter must remain visible even when the quick bar is no longer in filter mode.\n\n- the desktop status bar renders the active filter term whenever the pane has a non-empty filter\n- the status bar uses the filtered visible list for item counts and file metadata\n- this keeps the active filter visible while the user switches to smart navigation or command mode\n\nThe status bar indicator is part of the product contract, not just decorative UI. It is the persistent signal that the pane is still filtered.\n\n## Selection, Copy, and Move\n\nThe browser maintains explicit multi-select state per pane, but still supports a focused-item fallback when nothing is explicitly selected.\n\nIn practice, the pane computes an effective selection from either:\n\n- the explicit selected-file set\n- or the focused file when nothing has been explicitly selected\n\nSelection is pane-local and clears naturally when directory navigation changes the active file list.\n\nCopy and move behavior depends on:\n\n- the active pane as the source\n- the other pane as the destination in dual-pane workflows\n- backend or companion routing depending on which connection types are involved\n- conflict and validation behavior that still comes from the destination backend contract\n\nThe copy and move dialog is not just a confirmation prompt. It also:\n\n- shows the selected source files\n- pre-fills the destination from the other pane\n- lets the user adjust the destination before confirming\n- reports progress while multiple operations execute\n\nImportant contract details:\n\n- `F5` means copy in dual-pane mode, but remains refresh in single-pane mode\n- `F6` means move in dual-pane mode\n- cross-connection operations are not treated the same as same-share SMB operations\n- backend validation still decides whether same-path, self-copy, or conflicting operations are allowed\n\nFor same-connection SMB copy and move, the backend uses server-side operations rather than streaming all file bytes through the browser app.\n\n## Refresh and Live State\n\nDirectory freshness is coordinated through WebSocket subscriptions.\n\n- the browser subscribes to each visible pane's directory\n- directory-change messages are routed back to the matching pane\n- local-drive and SMB-backed directories can use different backends while still feeding one browser experience\n\nIn dual-pane mode, both panes are live participants in refresh behavior:\n\n- each pane can subscribe to a different directory\n- each pane re-subscribes when its own path changes\n- directory-change events are dispatched back to the pane that owns the matching path and connection context\n\nThis is why navigation and data freshness are coupled more tightly than they first appear.\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome file-browser behaviors are deliberate tradeoffs rather than incidental implementation detail.\n\n- the UI caps visible panes at two even though the query-key pattern could theoretically scale further\n- browser-default shortcuts such as tab switching are overridden when they conflict with the product's pane model\n- dual-pane mode is disabled on compact layouts instead of forcing a cramped mobile approximation\n- one pane can stay hidden while still existing in state so the hook model remains stable\n\n## Why This Page Matters\n\nFrontend changes in the file browser often look local, but they can break:\n\n- URL-restoration behavior\n- keyboard and focus contracts\n- copy and move flows\n- viewer launch behavior\n- local-drive versus SMB routing assumptions\n- refresh behavior across both panes\n\n## Where to Continue\n\n- Use [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for centralized shortcut definitions, command-palette behavior, and focus rules.\n- Use [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/) for preview and file-type behavior.\n- Use [Browser-to-Companion Trust Model](../../companion-architecture/browser-to-companion-trust-model/) when navigation or actions depend on paired local-drive access.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when changes cross backend, frontend, and companion boundaries.\n"}, "page_contents": {"0.7": "+++\ntitle = \"File Browser and Navigation Model\"\n+++\n\nThe file browser is the densest browser-side product surface in Sambee. It combines navigation, selection, editing entry points, viewer launch, keyboard behavior, and real-time directory refresh.\n\n## Core Component Split\n\nThe implementation is deliberately split between shared page logic and per-pane logic.\n\n| Area | Responsibility |\n|---|---|\n| `pages/FileBrowser.tsx` | owns shared browser-level concerns such as active pane routing, URL sync, WebSocket lifecycle, and global shortcut registration |\n| `pages/FileBrowser/useFileBrowserPane.ts` | owns per-pane state such as connection and path, selection, sorting, filtering, dialogs, viewer state, incremental search, and directory refresh handling |\n| `pages/FileBrowser/FileBrowserPane.tsx` | renders one pane's UI |\n| `components/FileBrowser/CopyMoveDialog.tsx` | manages copy and move confirmation flow |\n| `config/keyboardShortcuts.ts` | central shortcut definitions used across the browser |\n\nThis split matters because two visible panes still need one coherent browser workflow.\n\nThe parent-versus-hook split is intentional:\n\n- `FileBrowser.tsx` owns shared state such as the connections list, active-pane routing, responsive layout, WebSocket connection lifecycle, and browser-level shortcut registration\n- `useFileBrowserPane.ts` owns per-pane state such as file loading, sort and filter state, viewer and dialog state, focus handling, multi-select state, and pane-specific directory-change reactions\n\n## Pane Model\n\nSambee supports one-pane and two-pane browsing, but the two-pane implementation is intentional rather than conditional duplication.\n\n- the left pane is always active in routing terms\n- the right pane is still instantiated even when not visible, which keeps the hook model stable\n- the active pane decides which pane keyboard shortcuts and toolbar commands target\n- dual-pane mode is desktop-first and collapses to single-pane on compact layouts\n- dual-pane preference and active-pane preference are persisted so the browser can restore the user's working style\n- the viewer opens as a fullscreen overlay from whichever pane launched it rather than being constrained to one pane region\n\nVisual state also matters:\n\n- the active pane gets the stronger emphasis treatment\n- the inactive pane is visually de-emphasized rather than treated as a separate route or different screen\n\n## URL-Synced Navigation\n\nThe file browser preserves layout state in the URL.\n\n- the primary pane stays in the path\n- the right pane is represented by the `p2` query parameter\n- active pane state is represented by the `active` query parameter\n\nThat design means refresh and back-forward navigation preserve more than a single path string.\n\nRepresentative shape:\n\n```text\nSingle pane: /browse/my-server/documents/subfolder\nDual pane:   /browse/my-server/documents?p2=other-server/photos\u0026active=2\n```\n\nImportant behavior:\n\n- the presence of `p2` on initial load activates dual-pane mode automatically\n- back and forward navigation can add or remove the second pane without changing the route definition itself\n- single-pane mode produces a clean URL without stale dual-pane query state\n- invalid right-pane connection slugs are ignored rather than breaking the whole browser route\n- the encoding model preserves slash-separated paths while still percent-encoding the path segments safely\n\n## Keyboard and Command Model\n\nKeyboard behavior is part of the product contract, not just convenience.\n\n- pane switching, selection, copy, and move use centralized shortcut definitions\n- the quick bar supports smart navigation, command mode, and pane-local current-directory filtering\n- browser defaults that conflict with the product's navigation model are overridden intentionally\n- shortcuts are disabled when dialogs or viewer states would make them unsafe\n\nChanges here can easily affect power-user workflows, accessibility, and focus management all at once.\n\nUse [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for the central registry, command-palette rules, and quick-bar interaction details. This page focuses on how those rules shape the file-browser architecture.\n\n## Pane-Local Current-Directory Filtering\n\nCurrent-directory filtering is part of pane state, not just quick-bar UI state.\n\nThe important design choice is that the quick bar only supplies the input shell. The actual filter value and filtered list live in `useFileBrowserPane`.\n\n- each pane owns its own `currentDirectoryFilter`\n- the pane computes `sortedAndFilteredFiles` from the normal sorted list plus the active filter text\n- the filtered list is the same list used by the virtualizer, keyboard navigation, viewer launch, selection helpers, and status bar\n- the active filter is considered scoped to the pane's current `connectionId + path`\n\nThat arrangement is what makes the behavior consistent in both single-pane and dual-pane workflows.\n\n### Why the Filter Lives in the Pane Hook\n\nThe filter is not modeled as a dropdown provider result set.\n\n- smart navigation is a navigation surface that benefits from dropdown results\n- command mode is a command surface that benefits from dropdown results\n- current-directory filtering is a local transformation of the pane's main file list\n\nBecause the pane already owns the rendered list, focus state, virtualizer, and file actions, the filter belongs there as well.\n\n### User-Facing Behavior the Architecture Must Preserve\n\nThe implemented flow is:\n\n1. `Ctrl+Alt+F` opens filter mode for the active pane.\n2. The shared input shows that pane's current filter value.\n3. Typing immediately filters the pane's main file list.\n4. `ArrowDown` from the input focuses the filtered file list.\n5. Arrow keys, `Home`, `End`, `PageUp`, `PageDown`, `Enter`, and file actions operate on the filtered visible list.\n6. Pressing `Ctrl+Alt+F` again returns focus to the same pane's filter input without clearing the term.\n\nReset and persistence rules are equally important:\n\n- switching between smart navigation, command mode, and filter mode does not clear the active filter\n- changing directories clears the filter for the new path scope\n- changing the pane connection also clears the filter\n- dual-pane mode keeps filter state isolated per pane\n- browser recovery snapshots capture and restore the pane filter together with path, focused item, and selection state\n\n### Focus and Zero-Result Behavior\n\nFiltering changes focus semantics because it can remove rows from the visible list.\n\n- if the previously focused file still exists in the filtered list, focus stays on that file\n- if it disappears, focus clamps to the nearest valid visible item\n- if the filter produces zero visible files, focus remains in the filter input when possible\n\nThat is why the pane hook owns both the filtered list and the focus-adjustment logic.\n\n### Status Bar Visibility\n\nThe filter must remain visible even when the quick bar is no longer in filter mode.\n\n- the desktop status bar renders the active filter term whenever the pane has a non-empty filter\n- the status bar uses the filtered visible list for item counts and file metadata\n- this keeps the active filter visible while the user switches to smart navigation or command mode\n\nThe status bar indicator is part of the product contract, not just decorative UI. It is the persistent signal that the pane is still filtered.\n\n## Selection, Copy, and Move\n\nThe browser maintains explicit multi-select state per pane, but still supports a focused-item fallback when nothing is explicitly selected.\n\nIn practice, the pane computes an effective selection from either:\n\n- the explicit selected-file set\n- or the focused file when nothing has been explicitly selected\n\nSelection is pane-local and clears naturally when directory navigation changes the active file list.\n\nCopy and move behavior depends on:\n\n- the active pane as the source\n- the other pane as the destination in dual-pane workflows\n- backend or companion routing depending on which connection types are involved\n- conflict and validation behavior that still comes from the destination backend contract\n\nThe copy and move dialog is not just a confirmation prompt. It also:\n\n- shows the selected source files\n- pre-fills the destination from the other pane\n- lets the user adjust the destination before confirming\n- reports progress while multiple operations execute\n\nImportant contract details:\n\n- `F5` means copy in dual-pane mode, but remains refresh in single-pane mode\n- `F6` means move in dual-pane mode\n- cross-connection operations are not treated the same as same-share SMB operations\n- backend validation still decides whether same-path, self-copy, or conflicting operations are allowed\n\nFor same-connection SMB copy and move, the backend uses server-side operations rather than streaming all file bytes through the browser app.\n\n## Refresh and Live State\n\nDirectory freshness is coordinated through WebSocket subscriptions.\n\n- the browser subscribes to each visible pane's directory\n- directory-change messages are routed back to the matching pane\n- local-drive and SMB-backed directories can use different backends while still feeding one browser experience\n\nIn dual-pane mode, both panes are live participants in refresh behavior:\n\n- each pane can subscribe to a different directory\n- each pane re-subscribes when its own path changes\n- directory-change events are dispatched back to the pane that owns the matching path and connection context\n\nThis is why navigation and data freshness are coupled more tightly than they first appear.\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome file-browser behaviors are deliberate tradeoffs rather than incidental implementation detail.\n\n- the UI caps visible panes at two even though the query-key pattern could theoretically scale further\n- browser-default shortcuts such as tab switching are overridden when they conflict with the product's pane model\n- dual-pane mode is disabled on compact layouts instead of forcing a cramped mobile approximation\n- one pane can stay hidden while still existing in state so the hook model remains stable\n\n## Why This Page Matters\n\nFrontend changes in the file browser often look local, but they can break:\n\n- URL-restoration behavior\n- keyboard and focus contracts\n- copy and move flows\n- viewer launch behavior\n- local-drive versus SMB routing assumptions\n- refresh behavior across both panes\n\n## Where to Continue\n\n- Use [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for centralized shortcut definitions, command-palette behavior, and focus rules.\n- Use [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/) for preview and file-type behavior.\n- Use [Browser-to-Companion Trust Model](../../companion-architecture/browser-to-companion-trust-model/) when navigation or actions depend on paired local-drive access.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when changes cross backend, frontend, and companion boundaries.\n", "0.8": "+++\ntitle = \"File Browser and Navigation Model\"\n+++\n\nThe file browser is the densest browser-side product surface in Sambee. It combines navigation, selection, editing entry points, viewer launch, keyboard behavior, and real-time directory refresh.\n\n## Core Component Split\n\nThe implementation is deliberately split between shared page logic and per-pane logic.\n\n| Area | Responsibility |\n|---|---|\n| `pages/FileBrowser.tsx` | owns shared browser-level concerns such as active pane routing, URL sync, WebSocket lifecycle, and global shortcut registration |\n| `pages/FileBrowser/useFileBrowserPane.ts` | owns per-pane state such as connection and path, selection, sorting, filtering, dialogs, viewer state, incremental search, and directory refresh handling |\n| `pages/FileBrowser/FileBrowserPane.tsx` | renders one pane's UI |\n| `components/FileBrowser/CopyMoveDialog.tsx` | manages copy and move confirmation flow |\n| `config/keyboardShortcuts.ts` | central shortcut definitions used across the browser |\n\nThis split matters because two visible panes still need one coherent browser workflow.\n\nThe parent-versus-hook split is intentional:\n\n- `FileBrowser.tsx` owns shared state such as the connections list, active-pane routing, responsive layout, WebSocket connection lifecycle, and browser-level shortcut registration\n- `useFileBrowserPane.ts` owns per-pane state such as file loading, sort and filter state, viewer and dialog state, focus handling, multi-select state, and pane-specific directory-change reactions\n\n## Pane Model\n\nSambee supports one-pane and two-pane browsing, but the two-pane implementation is intentional rather than conditional duplication.\n\n- the left pane is always active in routing terms\n- the right pane is still instantiated even when not visible, which keeps the hook model stable\n- the active pane decides which pane keyboard shortcuts and toolbar commands target\n- dual-pane mode is desktop-first and collapses to single-pane on compact layouts\n- dual-pane preference and active-pane preference are persisted so the browser can restore the user's working style\n- the viewer opens as a fullscreen overlay from whichever pane launched it rather than being constrained to one pane region\n\nVisual state also matters:\n\n- the active pane gets the stronger emphasis treatment\n- the inactive pane is visually de-emphasized rather than treated as a separate route or different screen\n\n## URL-Synced Navigation\n\nThe file browser preserves layout state in the URL.\n\n- the primary pane stays in the path\n- the right pane is represented by the `p2` query parameter\n- active pane state is represented by the `active` query parameter\n\nThat design means refresh and back-forward navigation preserve more than a single path string.\n\nRepresentative shape:\n\n```text\nSingle pane: /browse/my-server/documents/subfolder\nDual pane:   /browse/my-server/documents?p2=other-server/photos\u0026active=2\n```\n\nImportant behavior:\n\n- the presence of `p2` on initial load activates dual-pane mode automatically\n- back and forward navigation can add or remove the second pane without changing the route definition itself\n- single-pane mode produces a clean URL without stale dual-pane query state\n- invalid right-pane connection slugs are ignored rather than breaking the whole browser route\n- the encoding model preserves slash-separated paths while still percent-encoding the path segments safely\n\n## Keyboard and Command Model\n\nKeyboard behavior is part of the product contract, not just convenience.\n\n- pane switching, selection, copy, and move use centralized shortcut definitions\n- the quick bar supports smart navigation, command mode, and pane-local current-directory filtering\n- browser defaults that conflict with the product's navigation model are overridden intentionally\n- shortcuts are disabled when dialogs or viewer states would make them unsafe\n\nChanges here can easily affect power-user workflows, accessibility, and focus management all at once.\n\nUse [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for the central registry, command-palette rules, and quick-bar interaction details. This page focuses on how those rules shape the file-browser architecture.\n\n## Pane-Local Current-Directory Filtering\n\nCurrent-directory filtering is part of pane state, not just quick-bar UI state.\n\nThe important design choice is that the quick bar only supplies the input shell. The actual filter value and filtered list live in `useFileBrowserPane`.\n\n- each pane owns its own `currentDirectoryFilter`\n- the pane computes `sortedAndFilteredFiles` from the normal sorted list plus the active filter text\n- the filtered list is the same list used by the virtualizer, keyboard navigation, viewer launch, selection helpers, and status bar\n- the active filter is considered scoped to the pane's current `connectionId + path`\n\nThat arrangement is what makes the behavior consistent in both single-pane and dual-pane workflows.\n\n### Why the Filter Lives in the Pane Hook\n\nThe filter is not modeled as a dropdown provider result set.\n\n- smart navigation is a navigation surface that benefits from dropdown results\n- command mode is a command surface that benefits from dropdown results\n- current-directory filtering is a local transformation of the pane's main file list\n\nBecause the pane already owns the rendered list, focus state, virtualizer, and file actions, the filter belongs there as well.\n\n### User-Facing Behavior the Architecture Must Preserve\n\nThe implemented flow is:\n\n1. `Ctrl+Alt+F` opens filter mode for the active pane.\n2. The shared input shows that pane's current filter value.\n3. Typing immediately filters the pane's main file list.\n4. `ArrowDown` from the input focuses the filtered file list.\n5. Arrow keys, `Home`, `End`, `PageUp`, `PageDown`, `Enter`, and file actions operate on the filtered visible list.\n6. Pressing `Ctrl+Alt+F` again returns focus to the same pane's filter input without clearing the term.\n\nReset and persistence rules are equally important:\n\n- switching between smart navigation, command mode, and filter mode does not clear the active filter\n- changing directories clears the filter for the new path scope\n- changing the pane connection also clears the filter\n- dual-pane mode keeps filter state isolated per pane\n- browser recovery snapshots capture and restore the pane filter together with path, focused item, and selection state\n\n### Focus and Zero-Result Behavior\n\nFiltering changes focus semantics because it can remove rows from the visible list.\n\n- if the previously focused file still exists in the filtered list, focus stays on that file\n- if it disappears, focus clamps to the nearest valid visible item\n- if the filter produces zero visible files, focus remains in the filter input when possible\n\nThat is why the pane hook owns both the filtered list and the focus-adjustment logic.\n\n### Status Bar Visibility\n\nThe filter must remain visible even when the quick bar is no longer in filter mode.\n\n- the desktop status bar renders the active filter term whenever the pane has a non-empty filter\n- the status bar uses the filtered visible list for item counts and file metadata\n- this keeps the active filter visible while the user switches to smart navigation or command mode\n\nThe status bar indicator is part of the product contract, not just decorative UI. It is the persistent signal that the pane is still filtered.\n\n## Selection, Copy, and Move\n\nThe browser maintains explicit multi-select state per pane, but still supports a focused-item fallback when nothing is explicitly selected.\n\nIn practice, the pane computes an effective selection from either:\n\n- the explicit selected-file set\n- or the focused file when nothing has been explicitly selected\n\nSelection is pane-local and clears naturally when directory navigation changes the active file list.\n\nCopy and move behavior depends on:\n\n- the active pane as the source\n- the other pane as the destination in dual-pane workflows\n- backend or companion routing depending on which connection types are involved\n- conflict and validation behavior that still comes from the destination backend contract\n\nThe copy and move dialog is not just a confirmation prompt. It also:\n\n- shows the selected source files\n- pre-fills the destination from the other pane\n- lets the user adjust the destination before confirming\n- reports progress while multiple operations execute\n\nImportant contract details:\n\n- `F5` means copy in dual-pane mode, but remains refresh in single-pane mode\n- `F6` means move in dual-pane mode\n- cross-connection operations are not treated the same as same-share SMB operations\n- backend validation still decides whether same-path, self-copy, or conflicting operations are allowed\n\nFor same-connection SMB copy and move, the backend uses server-side operations rather than streaming all file bytes through the browser app.\n\n## Refresh and Live State\n\nDirectory freshness is coordinated through WebSocket subscriptions.\n\n- the browser subscribes to each visible pane's directory\n- directory-change messages are routed back to the matching pane\n- local-drive and SMB-backed directories can use different backends while still feeding one browser experience\n\nIn dual-pane mode, both panes are live participants in refresh behavior:\n\n- each pane can subscribe to a different directory\n- each pane re-subscribes when its own path changes\n- directory-change events are dispatched back to the pane that owns the matching path and connection context\n\nThis is why navigation and data freshness are coupled more tightly than they first appear.\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome file-browser behaviors are deliberate tradeoffs rather than incidental implementation detail.\n\n- the UI caps visible panes at two even though the query-key pattern could theoretically scale further\n- browser-default shortcuts such as tab switching are overridden when they conflict with the product's pane model\n- dual-pane mode is disabled on compact layouts instead of forcing a cramped mobile approximation\n- one pane can stay hidden while still existing in state so the hook model remains stable\n\n## Why This Page Matters\n\nFrontend changes in the file browser often look local, but they can break:\n\n- URL-restoration behavior\n- keyboard and focus contracts\n- copy and move flows\n- viewer launch behavior\n- local-drive versus SMB routing assumptions\n- refresh behavior across both panes\n\n## Where to Continue\n\n- Use [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for centralized shortcut definitions, command-palette behavior, and focus rules.\n- Use [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/) for preview and file-type behavior.\n- Use [Browser-to-Companion Trust Model](../../companion-architecture/browser-to-companion-trust-model/) when navigation or actions depend on paired local-drive access.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when changes cross backend, frontend, and companion boundaries.\n", "0.9": "+++\ntitle = \"File Browser and Navigation Model\"\n+++\n\nThe file browser is the densest browser-side product surface in Sambee. It combines navigation, selection, editing entry points, viewer launch, keyboard behavior, and real-time directory refresh.\n\n## Core Component Split\n\nThe implementation is deliberately split between shared page logic and per-pane logic.\n\n| Area | Responsibility |\n|---|---|\n| `pages/FileBrowser.tsx` | owns shared browser-level concerns such as active pane routing, URL sync, WebSocket lifecycle, and global shortcut registration |\n| `pages/FileBrowser/useFileBrowserPane.ts` | owns per-pane state such as connection and path, selection, sorting, filtering, dialogs, viewer state, incremental search, and directory refresh handling |\n| `pages/FileBrowser/FileBrowserPane.tsx` | renders one pane's UI |\n| `components/FileBrowser/CopyMoveDialog.tsx` | manages copy and move confirmation flow |\n| `config/keyboardShortcuts.ts` | central shortcut definitions used across the browser |\n\nThis split matters because two visible panes still need one coherent browser workflow.\n\nThe parent-versus-hook split is intentional:\n\n- `FileBrowser.tsx` owns shared state such as the connections list, active-pane routing, responsive layout, WebSocket connection lifecycle, and browser-level shortcut registration\n- `useFileBrowserPane.ts` owns per-pane state such as file loading, sort and filter state, viewer and dialog state, focus handling, multi-select state, and pane-specific directory-change reactions\n\n## Pane Model\n\nSambee supports one-pane and two-pane browsing, but the two-pane implementation is intentional rather than conditional duplication.\n\n- the left pane is always active in routing terms\n- the right pane is still instantiated even when not visible, which keeps the hook model stable\n- the active pane decides which pane keyboard shortcuts and toolbar commands target\n- dual-pane mode is desktop-first and collapses to single-pane on compact layouts\n- dual-pane preference and active-pane preference are persisted so the browser can restore the user's working style\n- the viewer opens as a fullscreen overlay from whichever pane launched it rather than being constrained to one pane region\n\nVisual state also matters:\n\n- the active pane gets the stronger emphasis treatment\n- the inactive pane is visually de-emphasized rather than treated as a separate route or different screen\n\n## URL-Synced Navigation\n\nThe file browser preserves layout state in the URL.\n\n- the primary pane stays in the path\n- the right pane is represented by the `p2` query parameter\n- active pane state is represented by the `active` query parameter\n\nThat design means refresh and back-forward navigation preserve more than a single path string.\n\nRepresentative shape:\n\n```text\nSingle pane: /browse/my-server/documents/subfolder\nDual pane:   /browse/my-server/documents?p2=other-server/photos\u0026active=2\n```\n\nImportant behavior:\n\n- the presence of `p2` on initial load activates dual-pane mode automatically\n- back and forward navigation can add or remove the second pane without changing the route definition itself\n- single-pane mode produces a clean URL without stale dual-pane query state\n- invalid right-pane connection slugs are ignored rather than breaking the whole browser route\n- the encoding model preserves slash-separated paths while still percent-encoding the path segments safely\n\n## Keyboard and Command Model\n\nKeyboard behavior is part of the product contract, not just convenience.\n\n- pane switching, selection, copy, and move use centralized shortcut definitions\n- the quick bar supports smart navigation, command mode, and pane-local current-directory filtering\n- browser defaults that conflict with the product's navigation model are overridden intentionally\n- shortcuts are disabled when dialogs or viewer states would make them unsafe\n\nChanges here can easily affect power-user workflows, accessibility, and focus management all at once.\n\nUse [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for the central registry, command-palette rules, and quick-bar interaction details. This page focuses on how those rules shape the file-browser architecture.\n\n## Pane-Local Current-Directory Filtering\n\nCurrent-directory filtering is part of pane state, not just quick-bar UI state.\n\nThe important design choice is that the quick bar only supplies the input shell. The actual filter value and filtered list live in `useFileBrowserPane`.\n\n- each pane owns its own `currentDirectoryFilter`\n- the pane computes `sortedAndFilteredFiles` from the normal sorted list plus the active filter text\n- the filtered list is the same list used by the virtualizer, keyboard navigation, viewer launch, selection helpers, and status bar\n- the active filter is considered scoped to the pane's current `connectionId + path`\n\nThat arrangement is what makes the behavior consistent in both single-pane and dual-pane workflows.\n\n### Why the Filter Lives in the Pane Hook\n\nThe filter is not modeled as a dropdown provider result set.\n\n- smart navigation is a navigation surface that benefits from dropdown results\n- command mode is a command surface that benefits from dropdown results\n- current-directory filtering is a local transformation of the pane's main file list\n\nBecause the pane already owns the rendered list, focus state, virtualizer, and file actions, the filter belongs there as well.\n\n### User-Facing Behavior the Architecture Must Preserve\n\nThe implemented flow is:\n\n1. `Ctrl+Alt+F` opens filter mode for the active pane.\n2. The shared input shows that pane's current filter value.\n3. Typing immediately filters the pane's main file list.\n4. `ArrowDown` from the input focuses the filtered file list.\n5. Arrow keys, `Home`, `End`, `PageUp`, `PageDown`, `Enter`, and file actions operate on the filtered visible list.\n6. Pressing `Ctrl+Alt+F` again returns focus to the same pane's filter input without clearing the term.\n\nReset and persistence rules are equally important:\n\n- switching between smart navigation, command mode, and filter mode does not clear the active filter\n- changing directories clears the filter for the new path scope\n- changing the pane connection also clears the filter\n- dual-pane mode keeps filter state isolated per pane\n- browser recovery snapshots capture and restore the pane filter together with path, focused item, and selection state\n\n### Focus and Zero-Result Behavior\n\nFiltering changes focus semantics because it can remove rows from the visible list.\n\n- if the previously focused file still exists in the filtered list, focus stays on that file\n- if it disappears, focus clamps to the nearest valid visible item\n- if the filter produces zero visible files, focus remains in the filter input when possible\n\nThat is why the pane hook owns both the filtered list and the focus-adjustment logic.\n\n### Status Bar Visibility\n\nThe filter must remain visible even when the quick bar is no longer in filter mode.\n\n- the desktop status bar renders the active filter term whenever the pane has a non-empty filter\n- the status bar uses the filtered visible list for item counts and file metadata\n- this keeps the active filter visible while the user switches to smart navigation or command mode\n\nThe status bar indicator is part of the product contract, not just decorative UI. It is the persistent signal that the pane is still filtered.\n\n## Selection, Copy, and Move\n\nThe browser maintains explicit multi-select state per pane, but still supports a focused-item fallback when nothing is explicitly selected.\n\nIn practice, the pane computes an effective selection from either:\n\n- the explicit selected-file set\n- or the focused file when nothing has been explicitly selected\n\nSelection is pane-local and clears naturally when directory navigation changes the active file list.\n\nCopy and move behavior depends on:\n\n- the active pane as the source\n- the other pane as the destination in dual-pane workflows\n- backend or companion routing depending on which connection types are involved\n- conflict and validation behavior that still comes from the destination backend contract\n\nThe copy and move dialog is not just a confirmation prompt. It also:\n\n- shows the selected source files\n- pre-fills the destination from the other pane\n- lets the user adjust the destination before confirming\n- reports progress while multiple operations execute\n\nImportant contract details:\n\n- `F5` means copy in dual-pane mode, but remains refresh in single-pane mode\n- `F6` means move in dual-pane mode\n- cross-connection operations are not treated the same as same-share SMB operations\n- backend validation still decides whether same-path, self-copy, or conflicting operations are allowed\n\nFor same-connection SMB copy and move, the backend uses server-side operations rather than streaming all file bytes through the browser app.\n\n## Refresh and Live State\n\nDirectory freshness is coordinated through WebSocket subscriptions.\n\n- the browser subscribes to each visible pane's directory\n- directory-change messages are routed back to the matching pane\n- local-drive and SMB-backed directories can use different backends while still feeding one browser experience\n\nIn dual-pane mode, both panes are live participants in refresh behavior:\n\n- each pane can subscribe to a different directory\n- each pane re-subscribes when its own path changes\n- directory-change events are dispatched back to the pane that owns the matching path and connection context\n\nThis is why navigation and data freshness are coupled more tightly than they first appear.\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome file-browser behaviors are deliberate tradeoffs rather than incidental implementation detail.\n\n- the UI caps visible panes at two even though the query-key pattern could theoretically scale further\n- browser-default shortcuts such as tab switching are overridden when they conflict with the product's pane model\n- dual-pane mode is disabled on compact layouts instead of forcing a cramped mobile approximation\n- one pane can stay hidden while still existing in state so the hook model remains stable\n\n## Why This Page Matters\n\nFrontend changes in the file browser often look local, but they can break:\n\n- URL-restoration behavior\n- keyboard and focus contracts\n- copy and move flows\n- viewer launch behavior\n- local-drive versus SMB routing assumptions\n- refresh behavior across both panes\n\n## Where to Continue\n\n- Use [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for centralized shortcut definitions, command-palette behavior, and focus rules.\n- Use [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/) for preview and file-type behavior.\n- Use [Browser-to-Companion Trust Model](../../companion-architecture/browser-to-companion-trust-model/) when navigation or actions depend on paired local-drive access.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when changes cross backend, frontend, and companion boundaries.\n", "1.0": "+++\ntitle = \"File Browser and Navigation Model\"\n+++\n\nThe file browser is the densest browser-side product surface in Sambee. It combines navigation, selection, editing entry points, viewer launch, keyboard behavior, and real-time directory refresh.\n\n## Core Component Split\n\nThe implementation is deliberately split between shared page logic and per-pane logic.\n\n| Area | Responsibility |\n|---|---|\n| `pages/FileBrowser.tsx` | owns shared browser-level concerns such as active pane routing, URL sync, WebSocket lifecycle, and global shortcut registration |\n| `pages/FileBrowser/useFileBrowserPane.ts` | owns per-pane state such as connection and path, selection, sorting, filtering, dialogs, viewer state, incremental search, and directory refresh handling |\n| `pages/FileBrowser/FileBrowserPane.tsx` | renders one pane's UI |\n| `components/FileBrowser/CopyMoveDialog.tsx` | manages copy and move confirmation flow |\n| `config/keyboardShortcuts.ts` | central shortcut definitions used across the browser |\n\nThis split matters because two visible panes still need one coherent browser workflow.\n\nThe parent-versus-hook split is intentional:\n\n- `FileBrowser.tsx` owns shared state such as the connections list, active-pane routing, responsive layout, WebSocket connection lifecycle, and browser-level shortcut registration\n- `useFileBrowserPane.ts` owns per-pane state such as file loading, sort and filter state, viewer and dialog state, focus handling, multi-select state, and pane-specific directory-change reactions\n\n## Pane Model\n\nSambee supports one-pane and two-pane browsing, but the two-pane implementation is intentional rather than conditional duplication.\n\n- the left pane is always active in routing terms\n- the right pane is still instantiated even when not visible, which keeps the hook model stable\n- the active pane decides which pane keyboard shortcuts and toolbar commands target\n- dual-pane mode is desktop-first and collapses to single-pane on compact layouts\n- dual-pane preference and active-pane preference are persisted so the browser can restore the user's working style\n- the viewer opens as a fullscreen overlay from whichever pane launched it rather than being constrained to one pane region\n\nVisual state also matters:\n\n- the active pane gets the stronger emphasis treatment\n- the inactive pane is visually de-emphasized rather than treated as a separate route or different screen\n\n## URL-Synced Navigation\n\nThe file browser preserves layout state in the URL.\n\n- the primary pane stays in the path\n- the right pane is represented by the `p2` query parameter\n- active pane state is represented by the `active` query parameter\n\nThat design means refresh and back-forward navigation preserve more than a single path string.\n\nRepresentative shape:\n\n```text\nSingle pane: /browse/my-server/documents/subfolder\nDual pane:   /browse/my-server/documents?p2=other-server/photos\u0026active=2\n```\n\nImportant behavior:\n\n- the presence of `p2` on initial load activates dual-pane mode automatically\n- back and forward navigation can add or remove the second pane without changing the route definition itself\n- single-pane mode produces a clean URL without stale dual-pane query state\n- invalid right-pane connection slugs are ignored rather than breaking the whole browser route\n- the encoding model preserves slash-separated paths while still percent-encoding the path segments safely\n\n## Keyboard and Command Model\n\nKeyboard behavior is part of the product contract, not just convenience.\n\n- pane switching, selection, copy, and move use centralized shortcut definitions\n- the quick bar supports smart navigation, command mode, and pane-local current-directory filtering\n- browser defaults that conflict with the product's navigation model are overridden intentionally\n- shortcuts are disabled when dialogs or viewer states would make them unsafe\n\nChanges here can easily affect power-user workflows, accessibility, and focus management all at once.\n\nUse [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for the central registry, command-palette rules, and quick-bar interaction details. This page focuses on how those rules shape the file-browser architecture.\n\n## Pane-Local Current-Directory Filtering\n\nCurrent-directory filtering is part of pane state, not just quick-bar UI state.\n\nThe important design choice is that the quick bar only supplies the input shell. The actual filter value and filtered list live in `useFileBrowserPane`.\n\n- each pane owns its own `currentDirectoryFilter`\n- the pane computes `sortedAndFilteredFiles` from the normal sorted list plus the active filter text\n- the filtered list is the same list used by the virtualizer, keyboard navigation, viewer launch, selection helpers, and status bar\n- the active filter is considered scoped to the pane's current `connectionId + path`\n\nThat arrangement is what makes the behavior consistent in both single-pane and dual-pane workflows.\n\n### Why the Filter Lives in the Pane Hook\n\nThe filter is not modeled as a dropdown provider result set.\n\n- smart navigation is a navigation surface that benefits from dropdown results\n- command mode is a command surface that benefits from dropdown results\n- current-directory filtering is a local transformation of the pane's main file list\n\nBecause the pane already owns the rendered list, focus state, virtualizer, and file actions, the filter belongs there as well.\n\n### User-Facing Behavior the Architecture Must Preserve\n\nThe implemented flow is:\n\n1. `Ctrl+Alt+F` opens filter mode for the active pane.\n2. The shared input shows that pane's current filter value.\n3. Typing immediately filters the pane's main file list.\n4. `ArrowDown` from the input focuses the filtered file list.\n5. Arrow keys, `Home`, `End`, `PageUp`, `PageDown`, `Enter`, and file actions operate on the filtered visible list.\n6. Pressing `Ctrl+Alt+F` again returns focus to the same pane's filter input without clearing the term.\n\nReset and persistence rules are equally important:\n\n- switching between smart navigation, command mode, and filter mode does not clear the active filter\n- changing directories clears the filter for the new path scope\n- changing the pane connection also clears the filter\n- dual-pane mode keeps filter state isolated per pane\n- browser recovery snapshots capture and restore the pane filter together with path, focused item, and selection state\n\n### Focus and Zero-Result Behavior\n\nFiltering changes focus semantics because it can remove rows from the visible list.\n\n- if the previously focused file still exists in the filtered list, focus stays on that file\n- if it disappears, focus clamps to the nearest valid visible item\n- if the filter produces zero visible files, focus remains in the filter input when possible\n\nThat is why the pane hook owns both the filtered list and the focus-adjustment logic.\n\n### Status Bar Visibility\n\nThe filter must remain visible even when the quick bar is no longer in filter mode.\n\n- the desktop status bar renders the active filter term whenever the pane has a non-empty filter\n- the status bar uses the filtered visible list for item counts and file metadata\n- this keeps the active filter visible while the user switches to smart navigation or command mode\n\nThe status bar indicator is part of the product contract, not just decorative UI. It is the persistent signal that the pane is still filtered.\n\n## Selection, Copy, and Move\n\nThe browser maintains explicit multi-select state per pane, but still supports a focused-item fallback when nothing is explicitly selected.\n\nIn practice, the pane computes an effective selection from either:\n\n- the explicit selected-file set\n- or the focused file when nothing has been explicitly selected\n\nSelection is pane-local and clears naturally when directory navigation changes the active file list.\n\nCopy and move behavior depends on:\n\n- the active pane as the source\n- the other pane as the destination in dual-pane workflows\n- backend or companion routing depending on which connection types are involved\n- conflict and validation behavior that still comes from the destination backend contract\n\nThe copy and move dialog is not just a confirmation prompt. It also:\n\n- shows the selected source files\n- pre-fills the destination from the other pane\n- lets the user adjust the destination before confirming\n- reports progress while multiple operations execute\n\nImportant contract details:\n\n- `F5` means copy in dual-pane mode, but remains refresh in single-pane mode\n- `F6` means move in dual-pane mode\n- cross-connection operations are not treated the same as same-share SMB operations\n- backend validation still decides whether same-path, self-copy, or conflicting operations are allowed\n\nFor same-connection SMB copy and move, the backend uses server-side operations rather than streaming all file bytes through the browser app.\n\n## Refresh and Live State\n\nDirectory freshness is coordinated through WebSocket subscriptions.\n\n- the browser subscribes to each visible pane's directory\n- directory-change messages are routed back to the matching pane\n- local-drive and SMB-backed directories can use different backends while still feeding one browser experience\n\nIn dual-pane mode, both panes are live participants in refresh behavior:\n\n- each pane can subscribe to a different directory\n- each pane re-subscribes when its own path changes\n- directory-change events are dispatched back to the pane that owns the matching path and connection context\n\nThis is why navigation and data freshness are coupled more tightly than they first appear.\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome file-browser behaviors are deliberate tradeoffs rather than incidental implementation detail.\n\n- the UI caps visible panes at two even though the query-key pattern could theoretically scale further\n- browser-default shortcuts such as tab switching are overridden when they conflict with the product's pane model\n- dual-pane mode is disabled on compact layouts instead of forcing a cramped mobile approximation\n- one pane can stay hidden while still existing in state so the hook model remains stable\n\n## Why This Page Matters\n\nFrontend changes in the file browser often look local, but they can break:\n\n- URL-restoration behavior\n- keyboard and focus contracts\n- copy and move flows\n- viewer launch behavior\n- local-drive versus SMB routing assumptions\n- refresh behavior across both panes\n\n## Where to Continue\n\n- Use [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for centralized shortcut definitions, command-palette behavior, and focus rules.\n- Use [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/) for preview and file-type behavior.\n- Use [Browser-to-Companion Trust Model](../../companion-architecture/browser-to-companion-trust-model/) when navigation or actions depend on paired local-drive access.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when changes cross backend, frontend, and companion boundaries.\n", "2.0": "+++\ntitle = \"File Browser and Navigation Model\"\n+++\n\nThe file browser is the densest browser-side product surface in Sambee. It combines navigation, selection, editing entry points, viewer launch, keyboard behavior, and real-time directory refresh.\n\n## Core Component Split\n\nThe implementation is deliberately split between shared page logic and per-pane logic.\n\n| Area | Responsibility |\n|---|---|\n| `pages/FileBrowser.tsx` | owns shared browser-level concerns such as active pane routing, URL sync, WebSocket lifecycle, and global shortcut registration |\n| `pages/FileBrowser/useFileBrowserPane.ts` | owns per-pane state such as connection and path, selection, sorting, filtering, dialogs, viewer state, incremental search, and directory refresh handling |\n| `pages/FileBrowser/routing.ts` | parses and serializes typed directory, viewer, editor, and settings locations |\n| `pages/FileBrowser/useWorkspaceNavigation.ts` | resolves viewer targets and owns workspace navigation and safe overlay return entries |\n| `hooks/useRoutedViewerEditing.tsx` | connects the active editor's existing confirmation dialog to React Router navigation blocking |\n| `pages/FileBrowser/FileBrowserPane.tsx` | renders one pane's UI |\n| `components/FileBrowser/CopyMoveDialog.tsx` | manages copy and move confirmation flow |\n| `config/keyboardShortcuts.ts` | central shortcut definitions used across the browser |\n\nThis split matters because two visible panes still need one coherent browser workflow.\n\nThe parent-versus-hook split is intentional:\n\n- `FileBrowser.tsx` owns shared state such as the connections list, active-pane routing, responsive layout, WebSocket connection lifecycle, and browser-level shortcut registration\n- `useFileBrowserPane.ts` owns per-pane state such as file loading, sort and filter state, viewer and dialog state, focus handling, multi-select state, and pane-specific directory-change reactions\n\n## Pane Model\n\nSambee supports one-pane and two-pane browsing, but the two-pane implementation is intentional rather than conditional duplication.\n\n- the left pane is always active in routing terms\n- the right pane is still instantiated even when not visible, which keeps the hook model stable\n- the active pane decides which pane keyboard shortcuts and toolbar commands target\n- dual-pane mode is desktop-first and collapses to single-pane on compact layouts\n- dual-pane preference and active-pane preference are persisted so the browser can restore the user's working style\n- the viewer opens as a fullscreen overlay from whichever pane launched it rather than being constrained to one pane region\n\nVisual state also matters:\n\n- the active pane gets the stronger emphasis treatment\n- the inactive pane is visually de-emphasized rather than treated as a separate route or different screen\n\n## Real-Time Directory Refresh\n\nEach pane handles directory-change notifications independently. An automatic refresh keeps an already loaded physical-directory listing mounted, including an empty listing, so unchanged rows retain selection, keyboard focus, and scroll position. Initial loading and navigation without a usable snapshot still show loading feedback.\n\nNotifications don't cancel an active listing request. Instead, the pane remembers that another refresh is needed and starts one follow-up request after the active request finishes. Automatic refreshes start at most once per second. Further notifications don't move an existing deadline, so continuous writes still produce periodic updates. Navigation and unmount cancel queued work.\n\nA listing with unprocessed change notifications can remain visible, but it isn't cached as fresh. Deferred link-target metadata only updates cache entries that are still valid, so cancelling a follow-up refresh can't make an outdated snapshot reusable on return.\n\nSMB file-list subscriptions watch immediate children rather than the whole subtree. The separate backend directory-search cache retains recursive directory-name monitoring. See [SMB Change Notification and Directory Freshness](../../backend-architecture/smb-change-notification-and-directory-freshness/) for watcher ownership and lifecycle.\n\n## URL-Driven Workspace Navigation\n\nThe URL selects the directory, pane layout, viewer, editing intent, and settings view. The file browser stays mounted under overlays. Loaded content, drafts, locks, selection, scroll, search panels, and zoom remain runtime state.\n\n| Part | Meaning |\n|---|---|\n| `/browse/smb/\u003cslug\u003e/\u003cpath\u003e` | Primary SMB pane |\n| `/browse/local/\u003cdrive-id\u003e/\u003cpath\u003e` | Primary companion-drive pane |\n| `p2=\u003ckind\u003e/\u003ctarget\u003e/\u003cpath\u003e` | Right pane, enabled when present |\n| `active=2` | Right pane is active |\n| `file=\u003ckind\u003e/\u003ctarget\u003e/\u003cpath\u003e` | Viewer target, independent of the directory and active pane |\n| `viewer=image\\|markdown\\|pdf\\|text` | Requested browser viewer |\n| `mode=edit` | Editing intent for text or Markdown |\n| `pane=2` | Right pane owns the viewer; requires a right-pane target |\n| `virtual=\u003cJSON array\u003e` | Archive member descriptor: provider ID, source archive path, member path |\n| `settings=main\\|\u003ccategory\u003e` | Settings main view or category from the shared category registry |\n\nFor example:\n\n```text\n/browse/smb/my-server/documents\n/browse/smb/my-server/documents?p2=smb%2Fother-server%2Fphotos\u0026active=2\n/browse/smb/my-server/documents?file=smb%2Fmy-server%2Fdocuments%2Fnotes.md\u0026viewer=markdown\n/browse/smb/my-server/documents?file=smb%2Fmy-server%2Fdocuments%2Fnotes.md\u0026viewer=markdown\u0026mode=edit\n/browse/smb/my-server/documents?settings=account\n```\n\nUse the shared parser/serializer and `URLSearchParams`, not concatenated query strings. File descriptors encode target IDs and individual path segments before query serialization. The archive provider is currently `zip`. Runtime session IDs, file contents, MIME guesses, gallery arrays, credentials, and lock capabilities never belong in navigation state.\n\n### Navigation and Dismissal\n\nOpening or closing a viewer, entering or leaving editing, changing gallery images, opening or closing settings, and changing settings categories push history entries. Repeating the same location does nothing. Pane-focus updates, invalid-descriptor recovery, failed edit acquisition, and canonicalization replace the current entry. Unrelated query parameters and authentication fragments are preserved.\n\nBack and Forward follow actual history without adding entries. Explicit Close pushes the current workspace with the dismissed layer removed, including for direct links and refreshed viewers. For example, opening a directory, opening an image, and closing it produces directory, image, and directory entries; Back reopens the image before returning to the earlier directory entry. A new action after Back discards the old Forward branch, following normal browser behavior. Close doesn't depend on opening-entry metadata or `history.length`. Settings back controls traverse observed history; without an observed predecessor they replace the URL with an in-app parent.\n\nDesktop settings and the mobile drawer are controlled by the same category descriptor. `settings=main` displays the desktop default category or the mobile category list. Resizing changes presentation without navigation. Standalone `/settings/...` routes and their aliases use the same category content and authorization checks. User Management owns its query keys through React Router, merging them with workspace parameters.\n\n### Direct Links and Recovery\n\nViewer links resolve metadata through the storage registry or content provider, without simulated file-row clicks. Resolution is cancelled when its identity changes. Missing resources show Retry and Close actions. A viewer URL never falls back to opening a native application.\n\nThe incoming URL always wins over a browser recovery snapshot. Snapshot hydration matches each pane's resource identity, clears legacy viewer state, and ignores unmatched panes. A bare `/browse` uses normal default navigation. Captured snapshots use the current canonical workspace URL and contain neither callback fragments nor edit-session tokens.\n\n### Viewer Loading and Transitions\n\nLoading feedback belongs to the selected image, PDF, text, or Markdown viewer. Workspace metadata resolution and dynamic component imports do not show an intermediate full-screen loading dialog. On an initial opening, the browser remains visible until metadata and the viewer component are available; the viewer then displays its existing content-loading feedback.\n\nDuring file-to-file or history navigation, keep the outgoing viewer presentation mounted until the replacement metadata and component are ready. Do not expose the directory between viewers or pass the new target's props to the old viewer component. Outgoing controls and shortcuts are suspended during the handoff, while Escape can cancel the pending opening. The existing error dialogs retain Retry and Close actions. Cancellation rejects late results rather than reopening a dismissed viewer.\n\nOne dynamic viewer host serves both panes. An explicit viewer ID, not an image's changing MIME type, controls component loading. Text and Markdown still reset resource-local state when the actual file changes; mode-only and settings-only navigation do not restart the viewer.\n\n### Editing and Router Integrity\n\nThe app uses a data router (`createBrowserRouter` and `RouterProvider`) for supported `useBlocker` behavior. One guard owner delegates resource-leaving transitions to the active text or Markdown editor when its draft is dirty, a save is pending, or a session is being acquired. Clean editor Back and Forward navigate directly, avoiding the history reversal required by a blocked browser navigation. Cancel keeps the draft and lock; successful Save or Discard continues the original transition; failed Save keeps the editor open. Changes that retain the same edited resource and mode don't discard its draft. Dirty drafts also register `beforeunload` protection.\n\nEdit bookmarks and history navigation back into editing acquire a fresh edit session after content and permission checks. Navigating away during acquisition invalidates the attempt and releases any late lock. Leaving editing releases its session once. The outgoing editor is read-only during cleanup, and re-entry waits for that cleanup to finish so an old release can't clear a new session. History restores navigation intent, not old file contents, discarded drafts, or saved locks. An edit URL doesn't grant permission.\n\nFull page reloads, including F5 and the update prompt, can resume the same edit lock. The shared storage edit-session layer keeps lock credentials separately in tab-scoped session storage, keyed by user, connection, and file. On reload it validates those credentials with a heartbeat before reusing them. Only a structured lost-lock response permits fresh acquisition; network and permission failures don't trigger replacement. Credentials follow replacement locks and are removed on successful release or logout. Unsaved text still uses the existing draft-recovery flow.\n\nRecovery requires session storage and the browser Web Locks API, available in secure contexts such as HTTPS and localhost. An exclusive Web Lock prevents another tab from using copied recovery credentials, even if that tab reloads. Without those capabilities, editing still works, but a reload may need to wait for the abandoned server lock to expire. Fresh navigations and history entries don't resume saved credentials, and no credentials appear in the URL or workspace recovery snapshot.\n\nUse router navigation for all mounted-route URL writes, including authentication fragment cleanup. `useRemoveLocationFragment` replaces the entry, removes only consumed fragment keys, and preserves the full query and application state. Never clear router-managed history state with `replaceState(null, ...)`: doing so can disable POP blocking.\n\n## Keyboard and Command Model\n\nKeyboard behavior is part of the product contract, not just convenience.\n\n- pane switching, selection, copy, and move use centralized shortcut definitions\n- the quick bar supports smart navigation, command mode, and pane-local current-directory filtering\n- browser defaults that conflict with the product's navigation model are overridden intentionally\n- shortcuts are disabled when dialogs or viewer states would make them unsafe\n\nChanges here can easily affect power-user workflows, accessibility, and focus management all at once.\n\nUse [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for the central registry, command-palette rules, and quick-bar interaction details. This page focuses on how those rules shape the file-browser architecture.\n\n## Pane-Local Current-Directory Filtering\n\nCurrent-directory filtering is part of pane state, not just quick-bar UI state.\n\nThe important design choice is that the quick bar only supplies the input shell. The actual filter value and filtered list live in `useFileBrowserPane`.\n\n- each pane owns its own `currentDirectoryFilter`\n- the pane computes `sortedAndFilteredFiles` from the normal sorted list plus the active filter text\n- the filtered list is the same list used by the virtualizer, keyboard navigation, viewer launch, selection helpers, and status bar\n- the active filter is considered scoped to the pane's current `connectionId + path`\n\nThat arrangement is what makes the behavior consistent in both single-pane and dual-pane workflows.\n\n### Why the Filter Lives in the Pane Hook\n\nThe filter is not modeled as a dropdown provider result set.\n\n- smart navigation is a navigation surface that benefits from dropdown results\n- command mode is a command surface that benefits from dropdown results\n- current-directory filtering is a local transformation of the pane's main file list\n\nBecause the pane already owns the rendered list, focus state, virtualizer, and file actions, the filter belongs there as well.\n\n### User-Facing Behavior the Architecture Must Preserve\n\nThe implemented flow is:\n\n1. `Ctrl+Alt+F` opens filter mode for the active pane.\n2. The shared input shows that pane's current filter value.\n3. Typing immediately filters the pane's main file list.\n4. `ArrowDown` from the input focuses the filtered file list.\n5. Arrow keys, `Home`, `End`, `PageUp`, `PageDown`, `Enter`, and file actions operate on the filtered visible list.\n6. Pressing `Ctrl+Alt+F` again returns focus to the same pane's filter input without clearing the term.\n\nReset and persistence rules are equally important:\n\n- switching between smart navigation, command mode, and filter mode does not clear the active filter\n- changing directories clears the filter for the new path scope\n- changing the pane connection also clears the filter\n- dual-pane mode keeps filter state isolated per pane\n- browser recovery snapshots capture and restore the pane filter together with path, focused item, and selection state\n\n### Focus and Zero-Result Behavior\n\nFiltering changes focus semantics because it can remove rows from the visible list.\n\n- if the previously focused file still exists in the filtered list, focus stays on that file\n- if it disappears, focus clamps to the nearest valid visible item\n- if the filter produces zero visible files, focus remains in the filter input when possible\n\nThat is why the pane hook owns both the filtered list and the focus-adjustment logic.\n\n### Status Bar Visibility\n\nThe filter must remain visible even when the quick bar is no longer in filter mode.\n\n- the desktop status bar renders the active filter term whenever the pane has a non-empty filter\n- the status bar uses the filtered visible list for item counts and file metadata\n- this keeps the active filter visible while the user switches to smart navigation or command mode\n\nThe status bar indicator is part of the product contract, not just decorative UI. It is the persistent signal that the pane is still filtered.\n\n## Selection, Copy, and Move\n\nThe browser maintains explicit multi-select state per pane, but still supports a focused-item fallback when nothing is explicitly selected.\n\nIn practice, the pane computes an effective selection from either:\n\n- the explicit selected-file set\n- or the focused file when nothing has been explicitly selected\n\nSelection is pane-local and clears naturally when directory navigation changes the active file list.\n\nCopy and move behavior depends on:\n\n- the active pane as the source\n- the other pane as the destination in dual-pane workflows\n- backend or companion routing depending on which connection types are involved\n- conflict and validation behavior that still comes from the destination backend contract\n\nThe copy and move dialog is not just a confirmation prompt. It also:\n\n- shows the selected source files\n- pre-fills the destination from the other pane\n- lets the user adjust the destination before confirming\n- reports progress while multiple operations execute\n\nImportant contract details:\n\n- `F5` means copy in dual-pane mode, but remains refresh in single-pane mode\n- `F6` means move in dual-pane mode\n- cross-connection operations are not treated the same as same-share SMB operations\n- backend validation still decides whether same-path, self-copy, or conflicting operations are allowed\n\nFor same-connection SMB copy and move, the backend uses server-side operations rather than streaming all file bytes through the browser app.\n\n## Refresh and Live State\n\nDirectory freshness is coordinated through WebSocket subscriptions.\n\n- the browser subscribes to each visible pane's directory\n- directory-change messages are routed back to the matching pane\n- local-drive and SMB-backed directories can use different backends while still feeding one browser experience\n\nIn dual-pane mode, both panes are live participants in refresh behavior:\n\n- each pane can subscribe to a different directory\n- each pane re-subscribes when its own path changes\n- directory-change events are dispatched back to the pane that owns the matching path and connection context\n\nThis is why navigation and data freshness are coupled more tightly than they first appear.\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome file-browser behaviors are deliberate tradeoffs rather than incidental implementation detail.\n\n- the UI caps visible panes at two even though the query-key pattern could theoretically scale further\n- browser-default shortcuts such as tab switching are overridden when they conflict with the product's pane model\n- dual-pane mode is disabled on compact layouts instead of forcing a cramped mobile approximation\n- one pane can stay hidden while still existing in state so the hook model remains stable\n\n## Why This Page Matters\n\nFrontend changes in the file browser often look local, but they can break:\n\n- URL-restoration behavior\n- keyboard and focus contracts\n- copy and move flows\n- viewer launch behavior\n- local-drive versus SMB routing assumptions\n- refresh behavior across both panes\n\n## Where to Continue\n\n- Use [Keyboard Shortcuts and Command Model](../keyboard-shortcuts-and-command-model/) for centralized shortcut definitions, command-palette behavior, and focus rules.\n- Use [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/) for preview and file-type behavior.\n- Use [Browser-to-Companion Trust Model](../../companion-architecture/browser-to-companion-trust-model/) when navigation or actions depend on paired local-drive access.\n- Use [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) when changes cross backend, frontend, and companion boundaries.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/frontend-architecture/keyboard-shortcuts-and-command-model", "parent_id": "section:developer-guide/frontend-architecture", "depth": 2, "kind": "page", "label": "keyboard-shortcuts-and-command-model", "title": "Keyboard Shortcuts And Command Model", "path": "developer-guide/frontend-architecture/keyboard-shortcuts-and-command-model", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "branched", "source_version": "0.7", "diff_added": 14, "diff_removed": 6}, "2.0": {"state": "inherited", "source_version": "1.0"}}, "content_versions": {"0.7": "+++\ntitle = \"Keyboard Shortcuts and Command Model\"\n+++\n\nKeyboard behavior in Sambee is a shared frontend system, not a pile of local `keydown` handlers.\n\nThe product depends on contributors keeping shortcuts, command labels, viewer controls, and file-browser focus behavior aligned.\n\n## Core Pieces\n\nThese files define the keyboard and command model:\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/config/keyboardShortcuts.ts` | single source of truth for shortcut definitions and display labels |\n| `frontend/src/config/browserCommands.ts` | file-browser command registry for command-palette behavior |\n| `frontend/src/hooks/useKeyboardShortcuts.ts` | shared hook that binds shortcut definitions to runtime handlers |\n| `frontend/src/pages/FileBrowser.tsx` | registers browser-level shortcuts and routes command actions |\n| `frontend/src/components/Viewer/` | consumes shared shortcut definitions for viewer behavior and tooltip labels |\n\nThe system is intentionally split so shortcuts stay declarative while feature surfaces keep control of their own runtime behavior.\n\n## Why the Registry Exists\n\nBefore the centralized model, shortcut keys, tooltip labels, and component handlers drifted apart easily.\n\nThe current approach preserves these rules:\n\n- define shortcut keys and display intent once\n- reuse the same definition across viewers and file-browser surfaces\n- let components supply handlers without redefining labels and modifiers\n- keep file-browser actions discoverable even when users do not know the shortcut\n\n## Shortcut Definition Model\n\nShortcut definitions are grouped by scope, such as common viewer actions, PDF-specific actions, image-viewer actions, or browser actions.\n\nRepresentative structure:\n\n```typescript\nexport const COMMON_SHORTCUTS = {\n  CLOSE: {\n    id: \"close\",\n    keys: \"Escape\",\n    description: \"Close\",\n    label: \"Esc\",\n    allowInInput: true,\n  },\n  DOWNLOAD: {\n    id: \"download\",\n    keys: \"s\",\n    description: \"Download\",\n    label: \"Ctrl+S\",\n    ctrl: true,\n  },\n} as const;\n```\n\nCommon properties include:\n\n- `id`: stable identifier\n- `keys`: one key or multiple equivalent keys\n- `description`: human-readable intent\n- `label`: optional display label; if omitted, it can be generated from the config\n- `ctrl`, `shift`, `alt`: required modifiers\n- `allowInInput`: whether the shortcut still works while an input is focused\n- `priority`: ordering for overlapping shortcut candidates\n\n## Using the Shared Hook\n\nFeature components bind runtime behavior through `useKeyboardShortcuts` instead of duplicating event parsing logic.\n\nTypical usage:\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...COMMON_SHORTCUTS.CLOSE,\n      handler: onClose,\n    },\n    {\n      ...COMMON_SHORTCUTS.DOWNLOAD,\n      handler: handleDownload,\n    },\n    {\n      ...PDF_SHORTCUTS.SEARCH,\n      handler: handleOpenSearch,\n    },\n  ],\n});\n```\n\nThat split keeps the registry declarative and keeps feature logic in the feature component.\n\n## Labels and Tooltip Reuse\n\nViewer controls and similar UI surfaces should reuse the same shortcut definition instead of duplicating string formatting.\n\nThe shared formatter can turn a shortcut definition into a tooltip label such as `Download (Ctrl+S)`.\n\nThat matters because a changed shortcut should update viewer behavior and visible affordances together.\n\n## Browser Commands Versus Raw Shortcuts\n\nThe file browser uses both shortcut definitions and a command registry.\n\n- shortcut definitions remain centralized in `keyboardShortcuts.ts`\n- discoverable browser actions live in `browserCommands.ts`\n- command definitions point back to shortcut identifiers when a keyboard binding exists\n\nThis lets Sambee expose browser actions through the quick bar even when the user does not know the shortcut.\n\nEach browser command definition includes concepts such as:\n\n- a stable `id`\n- a user-facing `title`\n- a `category` for command grouping\n- linked shortcut identifiers\n- `isEnabled(context)` for context-aware availability\n- `run(context)` for execution\n- `selectionFocusTarget` for post-selection focus behavior\n\n## Quick-Bar Modes\n\nThe file browser quick bar is not just a text filter. It supports multiple modes with different intent.\n\n- `Ctrl+K`: open the smart navigation surface\n- `Ctrl+Alt+F`: open pane-local current-directory filter mode\n- `Ctrl+P` or `F1`: open command mode directly\n- typing `\u003e` as the first character switches the quick bar into command mode\n\nSmart navigation and command mode are dropdown-backed provider modes. Filter mode deliberately is not.\n\n- `smart` mode uses the search provider composition that merges directory navigation and command escape-hatch behavior\n- `commands` mode uses the browser command registry directly\n- `filter` mode uses the same input shell, but as a controlled pane-local filter box with dropdown rendering disabled\n\nThe quick bar captures the pane that opened it. In dual-pane mode, the active quick-bar pane stays fixed even if the other pane becomes active before selection.\n\nThat capture rule matters especially for filter mode, because the filter text belongs to the pane state, not to the shared quick-bar component.\n\n### Current-Directory Filter Mode\n\n`Ctrl+Alt+F` is now a real current-directory filter workflow, not a smart-navigation alias.\n\nThe implemented contract is:\n\n- the active pane opens the quick bar in `filter` mode\n- the quick bar shows that pane's `currentDirectoryFilter` as a controlled value\n- typing filters the pane's visible file list immediately\n- no dropdown results are shown in this mode\n- `ArrowDown` hands focus from the input into the pane's file list\n- `Escape` clears the filter first, then returns focus to the file list when the input is already empty\n\nThe filter state is pane-local and scoped to the current `connectionId + path`.\n\n- switching between `smart`, `commands`, and `filter` modes does not clear the current directory filter\n- navigating to a different directory clears the filter for the new scope\n- changing the pane's connection also clears the filter for the new scope\n- the status bar remains the persistent reminder that a filter is active even when the quick bar is in another mode\n\n## Current Browser-Level Shortcuts\n\nCurrent browser-level shortcuts include:\n\n- `Ctrl+K`: open smart navigation\n- `Ctrl+Alt+F`: focus current-directory filter mode for the active pane\n- `Ctrl+P`: show commands\n- `F1`: alternate binding for show commands\n- `Ctrl+,`: open settings\n- `?`: show keyboard shortcuts help\n- `Backspace`: go up one directory\n- `Ctrl+R`: refresh file list\n- `F2`: rename focused item\n- `Delete`: delete focused item\n- `F7`: create new directory\n- `Shift+F7`: create new file\n- `Ctrl+Enter`: open focused file in the companion app\n- `Ctrl+B`: toggle dual-pane view\n- `Ctrl+1`: focus left pane\n- `Ctrl+2`: focus right pane\n- `Tab`: switch active pane\n- `F5`: copy to the other pane\n- `F6`: move to the other pane\n\nWhen changing these, treat the behavior as product-level interaction design rather than local implementation detail.\n\n## Focus and Interaction Rules\n\nShortcut work often breaks focus behavior before it breaks functionality. Keep these rules intact:\n\n- opening the quick bar focuses its input immediately\n- selecting a navigation result returns focus to the relevant file list\n- selecting commands that switch quick-bar modes keeps focus inside the quick bar\n- `ArrowDown` from current-directory filter mode moves focus into the filtered file list\n- current-directory filter mode does not open a dropdown for local matches\n- `Escape` in filter mode clears the active filter before it hands focus back to the file list\n- commands that open dialogs or settings do not force focus back to the file list\n- pane-switching shortcuts do not fire while the quick-bar input is focused\n- shortcuts that should work during text entry must explicitly opt in with `allowInInput`\n- shortcuts should be disabled when dialog state or viewer state would make them unsafe\n\n## Context-Aware Shortcut Handling\n\nWhen one key needs different behavior depending on state, prefer one context-aware handler over overlapping registrations.\n\nFor example, `Escape` may close a search panel when that panel is open, but close the viewer when it is not.\n\nThat pattern is better than registering multiple conflicting `Escape` shortcuts because:\n\n- one shortcut definition stays authoritative\n- behavior remains explicit in the component state logic\n- conflicts are easier to reason about and test\n\n### Priority as an Escape Hatch\n\nIn rare cases, multiple handlers for one key are unavoidable. The system supports a `priority` field so higher-priority candidates are evaluated first.\n\nUse that sparingly. A context-aware handler is usually easier to understand and maintain than several competing registrations.\n\n## Adding New Shortcuts Safely\n\nWhen you add a shortcut, keep the workflow centralized.\n\n1. define the shortcut in `config/keyboardShortcuts.ts`\n2. bind it through `useKeyboardShortcuts` in the feature component\n3. reuse the same definition for tooltip or help-surface labels\n4. test both the runtime behavior and the visible affordance\n\nTypical sequence:\n\n```typescript\nexport const PDF_SHORTCUTS = {\n  PRINT: {\n    id: \"print\",\n    keys: \"p\",\n    description: \"Print\",\n    label: \"Ctrl+P\",\n    ctrl: true,\n  },\n} as const;\n```\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...PDF_SHORTCUTS.PRINT,\n      handler: handlePrint,\n    },\n  ],\n});\n```\n\n```typescript\ntitle={withShortcut(PDF_SHORTCUTS.PRINT)}\n```\n\nDo not add one-off tooltip strings or imperative event parsing when the shortcut belongs in the shared system.\n\n## Label Formatting Rules\n\nThe shortcut system also owns display formatting.\n\n- `ArrowRight` becomes `Right`\n- `ArrowLeft` becomes `Left`\n- `ArrowUp` becomes `Up`\n- `ArrowDown` becomes `Down`\n- `Escape` becomes `Esc`\n- space becomes `Space`\n- multiple equivalent keys are joined with ` / `\n- modifiers render as `Ctrl+`, `Shift+`, and `Alt+`\n\nThat formatting should come from the shared system, not from ad hoc component strings.\n\n## Common Failure Modes\n\n- shortcut keys and visible labels drift apart\n- a component registers imperative keyboard logic instead of using the shared hook\n- the browser command palette exposes actions that do not respect the current UI context\n- shortcuts fire while text input or dialog state should block them\n- quick-bar focus returns to the wrong pane in dual-pane workflows\n- multiple overlapping handlers compete for one key instead of using a context-aware handler\n\n## Validation Expectations\n\nWhen keyboard behavior changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change affects file-browser behavior, also test:\n\n- quick-bar navigation and command mode\n- pane switching in dual-pane and single-pane layouts\n- dialog safety for destructive shortcuts\n- viewer shortcut labels and matching runtime behavior\n\nFor new shortcut registrations, also verify:\n\n- the shared label matches the actual bound keys\n- `allowInInput` behavior matches the intended text-entry experience\n- priority and enabled-state logic do not create hidden overlaps\n\n## Where to Continue\n\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL sync, selection, and refresh behavior\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): viewer reuse, preview behavior, and file-type contracts\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): other shared frontend systems contributors should keep centralized\n", "0.8": "+++\ntitle = \"Keyboard Shortcuts and Command Model\"\n+++\n\nKeyboard behavior in Sambee is a shared frontend system, not a pile of local `keydown` handlers.\n\nThe product depends on contributors keeping shortcuts, command labels, viewer controls, and file-browser focus behavior aligned.\n\n## Core Pieces\n\nThese files define the keyboard and command model:\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/config/keyboardShortcuts.ts` | single source of truth for shortcut definitions and display labels |\n| `frontend/src/config/browserCommands.ts` | file-browser command registry for command-palette behavior |\n| `frontend/src/hooks/useKeyboardShortcuts.ts` | shared hook that binds shortcut definitions to runtime handlers |\n| `frontend/src/pages/FileBrowser.tsx` | registers browser-level shortcuts and routes command actions |\n| `frontend/src/components/Viewer/` | consumes shared shortcut definitions for viewer behavior and tooltip labels |\n\nThe system is intentionally split so shortcuts stay declarative while feature surfaces keep control of their own runtime behavior.\n\n## Why the Registry Exists\n\nBefore the centralized model, shortcut keys, tooltip labels, and component handlers drifted apart easily.\n\nThe current approach preserves these rules:\n\n- define shortcut keys and display intent once\n- reuse the same definition across viewers and file-browser surfaces\n- let components supply handlers without redefining labels and modifiers\n- keep file-browser actions discoverable even when users do not know the shortcut\n\n## Shortcut Definition Model\n\nShortcut definitions are grouped by scope, such as common viewer actions, PDF-specific actions, image-viewer actions, or browser actions.\n\nRepresentative structure:\n\n```typescript\nexport const COMMON_SHORTCUTS = {\n  CLOSE: {\n    id: \"close\",\n    keys: \"Escape\",\n    description: \"Close\",\n    label: \"Esc\",\n    allowInInput: true,\n  },\n  DOWNLOAD: {\n    id: \"download\",\n    keys: \"s\",\n    description: \"Download\",\n    label: \"Ctrl+S\",\n    ctrl: true,\n  },\n} as const;\n```\n\nCommon properties include:\n\n- `id`: stable identifier\n- `keys`: one key or multiple equivalent keys\n- `description`: human-readable intent\n- `label`: optional display label; if omitted, it can be generated from the config\n- `ctrl`, `shift`, `alt`: required modifiers\n- `allowInInput`: whether the shortcut still works while an input is focused\n- `priority`: ordering for overlapping shortcut candidates\n\n## Using the Shared Hook\n\nFeature components bind runtime behavior through `useKeyboardShortcuts` instead of duplicating event parsing logic.\n\nTypical usage:\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...COMMON_SHORTCUTS.CLOSE,\n      handler: onClose,\n    },\n    {\n      ...COMMON_SHORTCUTS.DOWNLOAD,\n      handler: handleDownload,\n    },\n    {\n      ...PDF_SHORTCUTS.SEARCH,\n      handler: handleOpenSearch,\n    },\n  ],\n});\n```\n\nThat split keeps the registry declarative and keeps feature logic in the feature component.\n\n## Labels and Tooltip Reuse\n\nViewer controls and similar UI surfaces should reuse the same shortcut definition instead of duplicating string formatting.\n\nThe shared formatter can turn a shortcut definition into a tooltip label such as `Download (Ctrl+S)`.\n\nThat matters because a changed shortcut should update viewer behavior and visible affordances together.\n\n## Browser Commands Versus Raw Shortcuts\n\nThe file browser uses both shortcut definitions and a command registry.\n\n- shortcut definitions remain centralized in `keyboardShortcuts.ts`\n- discoverable browser actions live in `browserCommands.ts`\n- command definitions point back to shortcut identifiers when a keyboard binding exists\n\nThis lets Sambee expose browser actions through the quick bar even when the user does not know the shortcut.\n\nEach browser command definition includes concepts such as:\n\n- a stable `id`\n- a user-facing `title`\n- a `category` for command grouping\n- linked shortcut identifiers\n- `isEnabled(context)` for context-aware availability\n- `run(context)` for execution\n- `selectionFocusTarget` for post-selection focus behavior\n\n## Quick-Bar Modes\n\nThe file browser quick bar is not just a text filter. It supports multiple modes with different intent.\n\n- `Ctrl+K`: open the smart navigation surface\n- `Ctrl+Alt+F`: open pane-local current-directory filter mode\n- `Ctrl+P` or `F1`: open command mode directly\n- typing `\u003e` as the first character switches the quick bar into command mode\n\nSmart navigation and command mode are dropdown-backed provider modes. Filter mode deliberately is not.\n\n- `smart` mode uses the search provider composition that merges directory navigation and command escape-hatch behavior\n- `commands` mode uses the browser command registry directly\n- `filter` mode uses the same input shell, but as a controlled pane-local filter box with dropdown rendering disabled\n\nThe quick bar captures the pane that opened it. In dual-pane mode, the active quick-bar pane stays fixed even if the other pane becomes active before selection.\n\nThat capture rule matters especially for filter mode, because the filter text belongs to the pane state, not to the shared quick-bar component.\n\n### Current-Directory Filter Mode\n\n`Ctrl+Alt+F` is now a real current-directory filter workflow, not a smart-navigation alias.\n\nThe implemented contract is:\n\n- the active pane opens the quick bar in `filter` mode\n- the quick bar shows that pane's `currentDirectoryFilter` as a controlled value\n- typing filters the pane's visible file list immediately\n- no dropdown results are shown in this mode\n- `ArrowDown` hands focus from the input into the pane's file list\n- `Escape` clears the filter first, then returns focus to the file list when the input is already empty\n\nThe filter state is pane-local and scoped to the current `connectionId + path`.\n\n- switching between `smart`, `commands`, and `filter` modes does not clear the current directory filter\n- navigating to a different directory clears the filter for the new scope\n- changing the pane's connection also clears the filter for the new scope\n- the status bar remains the persistent reminder that a filter is active even when the quick bar is in another mode\n\n## Current Browser-Level Shortcuts\n\nCurrent browser-level shortcuts include:\n\n- `Ctrl+K`: open smart navigation\n- `Ctrl+Alt+F`: focus current-directory filter mode for the active pane\n- `Ctrl+P`: show commands\n- `F1`: alternate binding for show commands\n- `Ctrl+,`: open settings\n- `?`: show keyboard shortcuts help\n- `Backspace`: go up one directory\n- `Ctrl+R`: refresh file list\n- `F2`: rename focused item\n- `Delete`: delete focused item\n- `F7`: create new directory\n- `Shift+F7`: create new file\n- `Ctrl+Enter`: open focused file in the companion app\n- `Ctrl+B`: toggle dual-pane view\n- `Ctrl+1`: focus left pane\n- `Ctrl+2`: focus right pane\n- `Tab`: switch active pane\n- `F5`: copy to the other pane\n- `F6`: move to the other pane\n\nWhen changing these, treat the behavior as product-level interaction design rather than local implementation detail.\n\n## Focus and Interaction Rules\n\nShortcut work often breaks focus behavior before it breaks functionality. Keep these rules intact:\n\n- opening the quick bar focuses its input immediately\n- selecting a navigation result returns focus to the relevant file list\n- selecting commands that switch quick-bar modes keeps focus inside the quick bar\n- `ArrowDown` from current-directory filter mode moves focus into the filtered file list\n- current-directory filter mode does not open a dropdown for local matches\n- `Escape` in filter mode clears the active filter before it hands focus back to the file list\n- commands that open dialogs or settings do not force focus back to the file list\n- pane-switching shortcuts do not fire while the quick-bar input is focused\n- shortcuts that should work during text entry must explicitly opt in with `allowInInput`\n- shortcuts should be disabled when dialog state or viewer state would make them unsafe\n\n## Context-Aware Shortcut Handling\n\nWhen one key needs different behavior depending on state, prefer one context-aware handler over overlapping registrations.\n\nFor example, `Escape` may close a search panel when that panel is open, but close the viewer when it is not.\n\nThat pattern is better than registering multiple conflicting `Escape` shortcuts because:\n\n- one shortcut definition stays authoritative\n- behavior remains explicit in the component state logic\n- conflicts are easier to reason about and test\n\n### Priority as an Escape Hatch\n\nIn rare cases, multiple handlers for one key are unavoidable. The system supports a `priority` field so higher-priority candidates are evaluated first.\n\nUse that sparingly. A context-aware handler is usually easier to understand and maintain than several competing registrations.\n\n## Adding New Shortcuts Safely\n\nWhen you add a shortcut, keep the workflow centralized.\n\n1. define the shortcut in `config/keyboardShortcuts.ts`\n2. bind it through `useKeyboardShortcuts` in the feature component\n3. reuse the same definition for tooltip or help-surface labels\n4. test both the runtime behavior and the visible affordance\n\nTypical sequence:\n\n```typescript\nexport const PDF_SHORTCUTS = {\n  PRINT: {\n    id: \"print\",\n    keys: \"p\",\n    description: \"Print\",\n    label: \"Ctrl+P\",\n    ctrl: true,\n  },\n} as const;\n```\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...PDF_SHORTCUTS.PRINT,\n      handler: handlePrint,\n    },\n  ],\n});\n```\n\n```typescript\ntitle={withShortcut(PDF_SHORTCUTS.PRINT)}\n```\n\nDo not add one-off tooltip strings or imperative event parsing when the shortcut belongs in the shared system.\n\n## Label Formatting Rules\n\nThe shortcut system also owns display formatting.\n\n- `ArrowRight` becomes `Right`\n- `ArrowLeft` becomes `Left`\n- `ArrowUp` becomes `Up`\n- `ArrowDown` becomes `Down`\n- `Escape` becomes `Esc`\n- space becomes `Space`\n- multiple equivalent keys are joined with ` / `\n- modifiers render as `Ctrl+`, `Shift+`, and `Alt+`\n\nThat formatting should come from the shared system, not from ad hoc component strings.\n\n## Common Failure Modes\n\n- shortcut keys and visible labels drift apart\n- a component registers imperative keyboard logic instead of using the shared hook\n- the browser command palette exposes actions that do not respect the current UI context\n- shortcuts fire while text input or dialog state should block them\n- quick-bar focus returns to the wrong pane in dual-pane workflows\n- multiple overlapping handlers compete for one key instead of using a context-aware handler\n\n## Validation Expectations\n\nWhen keyboard behavior changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change affects file-browser behavior, also test:\n\n- quick-bar navigation and command mode\n- pane switching in dual-pane and single-pane layouts\n- dialog safety for destructive shortcuts\n- viewer shortcut labels and matching runtime behavior\n\nFor new shortcut registrations, also verify:\n\n- the shared label matches the actual bound keys\n- `allowInInput` behavior matches the intended text-entry experience\n- priority and enabled-state logic do not create hidden overlaps\n\n## Where to Continue\n\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL sync, selection, and refresh behavior\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): viewer reuse, preview behavior, and file-type contracts\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): other shared frontend systems contributors should keep centralized\n", "0.9": "+++\ntitle = \"Keyboard Shortcuts and Command Model\"\n+++\n\nKeyboard behavior in Sambee is a shared frontend system, not a pile of local `keydown` handlers.\n\nThe product depends on contributors keeping shortcuts, command labels, viewer controls, and file-browser focus behavior aligned.\n\n## Core Pieces\n\nThese files define the keyboard and command model:\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/config/keyboardShortcuts.ts` | single source of truth for shortcut definitions and display labels |\n| `frontend/src/config/browserCommands.ts` | file-browser command registry for command-palette behavior |\n| `frontend/src/hooks/useKeyboardShortcuts.ts` | shared hook that binds shortcut definitions to runtime handlers |\n| `frontend/src/pages/FileBrowser.tsx` | registers browser-level shortcuts and routes command actions |\n| `frontend/src/components/Viewer/` | consumes shared shortcut definitions for viewer behavior and tooltip labels |\n\nThe system is intentionally split so shortcuts stay declarative while feature surfaces keep control of their own runtime behavior.\n\n## Why the Registry Exists\n\nBefore the centralized model, shortcut keys, tooltip labels, and component handlers drifted apart easily.\n\nThe current approach preserves these rules:\n\n- define shortcut keys and display intent once\n- reuse the same definition across viewers and file-browser surfaces\n- let components supply handlers without redefining labels and modifiers\n- keep file-browser actions discoverable even when users do not know the shortcut\n\n## Shortcut Definition Model\n\nShortcut definitions are grouped by scope, such as common viewer actions, PDF-specific actions, image-viewer actions, or browser actions.\n\nRepresentative structure:\n\n```typescript\nexport const COMMON_SHORTCUTS = {\n  CLOSE: {\n    id: \"close\",\n    keys: \"Escape\",\n    description: \"Close\",\n    label: \"Esc\",\n    allowInInput: true,\n  },\n  DOWNLOAD: {\n    id: \"download\",\n    keys: \"s\",\n    description: \"Download\",\n    label: \"Ctrl+S\",\n    ctrl: true,\n  },\n} as const;\n```\n\nCommon properties include:\n\n- `id`: stable identifier\n- `keys`: one key or multiple equivalent keys\n- `description`: human-readable intent\n- `label`: optional display label; if omitted, it can be generated from the config\n- `ctrl`, `shift`, `alt`: required modifiers\n- `allowInInput`: whether the shortcut still works while an input is focused\n- `priority`: ordering for overlapping shortcut candidates\n\n## Using the Shared Hook\n\nFeature components bind runtime behavior through `useKeyboardShortcuts` instead of duplicating event parsing logic.\n\nTypical usage:\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...COMMON_SHORTCUTS.CLOSE,\n      handler: onClose,\n    },\n    {\n      ...COMMON_SHORTCUTS.DOWNLOAD,\n      handler: handleDownload,\n    },\n    {\n      ...PDF_SHORTCUTS.SEARCH,\n      handler: handleOpenSearch,\n    },\n  ],\n});\n```\n\nThat split keeps the registry declarative and keeps feature logic in the feature component.\n\n## Labels and Tooltip Reuse\n\nViewer controls and similar UI surfaces should reuse the same shortcut definition instead of duplicating string formatting.\n\nThe shared formatter can turn a shortcut definition into a tooltip label such as `Download (Ctrl+S)`.\n\nThat matters because a changed shortcut should update viewer behavior and visible affordances together.\n\n## Browser Commands Versus Raw Shortcuts\n\nThe file browser uses both shortcut definitions and a command registry.\n\n- shortcut definitions remain centralized in `keyboardShortcuts.ts`\n- discoverable browser actions live in `browserCommands.ts`\n- command definitions point back to shortcut identifiers when a keyboard binding exists\n\nThis lets Sambee expose browser actions through the quick bar even when the user does not know the shortcut.\n\nEach browser command definition includes concepts such as:\n\n- a stable `id`\n- a user-facing `title`\n- a `category` for command grouping\n- linked shortcut identifiers\n- `isEnabled(context)` for context-aware availability\n- `run(context)` for execution\n- `selectionFocusTarget` for post-selection focus behavior\n\n## Quick-Bar Modes\n\nThe file browser quick bar is not just a text filter. It supports multiple modes with different intent.\n\n- `Ctrl+K`: open the smart navigation surface\n- `Ctrl+Alt+F`: open pane-local current-directory filter mode\n- `Ctrl+P` or `F1`: open command mode directly\n- typing `\u003e` as the first character switches the quick bar into command mode\n\nSmart navigation and command mode are dropdown-backed provider modes. Filter mode deliberately is not.\n\n- `smart` mode uses the search provider composition that merges directory navigation and command escape-hatch behavior\n- `commands` mode uses the browser command registry directly\n- `filter` mode uses the same input shell, but as a controlled pane-local filter box with dropdown rendering disabled\n\nThe quick bar captures the pane that opened it. In dual-pane mode, the active quick-bar pane stays fixed even if the other pane becomes active before selection.\n\nThat capture rule matters especially for filter mode, because the filter text belongs to the pane state, not to the shared quick-bar component.\n\n### Current-Directory Filter Mode\n\n`Ctrl+Alt+F` is now a real current-directory filter workflow, not a smart-navigation alias.\n\nThe implemented contract is:\n\n- the active pane opens the quick bar in `filter` mode\n- the quick bar shows that pane's `currentDirectoryFilter` as a controlled value\n- typing filters the pane's visible file list immediately\n- no dropdown results are shown in this mode\n- `ArrowDown` hands focus from the input into the pane's file list\n- `Escape` clears the filter first, then returns focus to the file list when the input is already empty\n\nThe filter state is pane-local and scoped to the current `connectionId + path`.\n\n- switching between `smart`, `commands`, and `filter` modes does not clear the current directory filter\n- navigating to a different directory clears the filter for the new scope\n- changing the pane's connection also clears the filter for the new scope\n- the status bar remains the persistent reminder that a filter is active even when the quick bar is in another mode\n\n## Current Browser-Level Shortcuts\n\nCurrent browser-level shortcuts include:\n\n- `Ctrl+K`: open smart navigation\n- `Ctrl+Alt+F`: focus current-directory filter mode for the active pane\n- `Ctrl+P`: show commands\n- `F1`: alternate binding for show commands\n- `Ctrl+,`: open settings\n- `?`: show keyboard shortcuts help\n- `Backspace`: go up one directory\n- `Ctrl+R`: refresh file list\n- `F2`: rename focused item\n- `Delete`: delete focused item\n- `F7`: create new directory\n- `Shift+F7`: create new file\n- `Ctrl+Enter`: open focused file in the companion app\n- `Ctrl+B`: toggle dual-pane view\n- `Ctrl+1`: focus left pane\n- `Ctrl+2`: focus right pane\n- `Tab`: switch active pane\n- `F5`: copy to the other pane\n- `F6`: move to the other pane\n\nWhen changing these, treat the behavior as product-level interaction design rather than local implementation detail.\n\n## Focus and Interaction Rules\n\nShortcut work often breaks focus behavior before it breaks functionality. Keep these rules intact:\n\n- opening the quick bar focuses its input immediately\n- selecting a navigation result returns focus to the relevant file list\n- selecting commands that switch quick-bar modes keeps focus inside the quick bar\n- `ArrowDown` from current-directory filter mode moves focus into the filtered file list\n- current-directory filter mode does not open a dropdown for local matches\n- `Escape` in filter mode clears the active filter before it hands focus back to the file list\n- commands that open dialogs or settings do not force focus back to the file list\n- pane-switching shortcuts do not fire while the quick-bar input is focused\n- shortcuts that should work during text entry must explicitly opt in with `allowInInput`\n- shortcuts should be disabled when dialog state or viewer state would make them unsafe\n\n## Context-Aware Shortcut Handling\n\nWhen one key needs different behavior depending on state, prefer one context-aware handler over overlapping registrations.\n\nFor example, `Escape` may close a search panel when that panel is open, but close the viewer when it is not.\n\nThat pattern is better than registering multiple conflicting `Escape` shortcuts because:\n\n- one shortcut definition stays authoritative\n- behavior remains explicit in the component state logic\n- conflicts are easier to reason about and test\n\n### Priority as an Escape Hatch\n\nIn rare cases, multiple handlers for one key are unavoidable. The system supports a `priority` field so higher-priority candidates are evaluated first.\n\nUse that sparingly. A context-aware handler is usually easier to understand and maintain than several competing registrations.\n\n## Adding New Shortcuts Safely\n\nWhen you add a shortcut, keep the workflow centralized.\n\n1. define the shortcut in `config/keyboardShortcuts.ts`\n2. bind it through `useKeyboardShortcuts` in the feature component\n3. reuse the same definition for tooltip or help-surface labels\n4. test both the runtime behavior and the visible affordance\n\nTypical sequence:\n\n```typescript\nexport const PDF_SHORTCUTS = {\n  PRINT: {\n    id: \"print\",\n    keys: \"p\",\n    description: \"Print\",\n    label: \"Ctrl+P\",\n    ctrl: true,\n  },\n} as const;\n```\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...PDF_SHORTCUTS.PRINT,\n      handler: handlePrint,\n    },\n  ],\n});\n```\n\n```typescript\ntitle={withShortcut(PDF_SHORTCUTS.PRINT)}\n```\n\nDo not add one-off tooltip strings or imperative event parsing when the shortcut belongs in the shared system.\n\n## Label Formatting Rules\n\nThe shortcut system also owns display formatting.\n\n- `ArrowRight` becomes `Right`\n- `ArrowLeft` becomes `Left`\n- `ArrowUp` becomes `Up`\n- `ArrowDown` becomes `Down`\n- `Escape` becomes `Esc`\n- space becomes `Space`\n- multiple equivalent keys are joined with ` / `\n- modifiers render as `Ctrl+`, `Shift+`, and `Alt+`\n\nThat formatting should come from the shared system, not from ad hoc component strings.\n\n## Common Failure Modes\n\n- shortcut keys and visible labels drift apart\n- a component registers imperative keyboard logic instead of using the shared hook\n- the browser command palette exposes actions that do not respect the current UI context\n- shortcuts fire while text input or dialog state should block them\n- quick-bar focus returns to the wrong pane in dual-pane workflows\n- multiple overlapping handlers compete for one key instead of using a context-aware handler\n\n## Validation Expectations\n\nWhen keyboard behavior changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change affects file-browser behavior, also test:\n\n- quick-bar navigation and command mode\n- pane switching in dual-pane and single-pane layouts\n- dialog safety for destructive shortcuts\n- viewer shortcut labels and matching runtime behavior\n\nFor new shortcut registrations, also verify:\n\n- the shared label matches the actual bound keys\n- `allowInInput` behavior matches the intended text-entry experience\n- priority and enabled-state logic do not create hidden overlaps\n\n## Where to Continue\n\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL sync, selection, and refresh behavior\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): viewer reuse, preview behavior, and file-type contracts\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): other shared frontend systems contributors should keep centralized\n", "1.0": "+++\ntitle = \"Keyboard Shortcuts and Command Model\"\n+++\n\nKeyboard behavior in Sambee is a shared frontend system, not a pile of local `keydown` handlers.\n\nThe product depends on contributors keeping shortcuts, command labels, viewer controls, and file-browser focus behavior aligned.\n\n## Core Pieces\n\nThese files define the keyboard and command model:\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/config/keyboardShortcuts.ts` | single source of truth for shortcut definitions and display labels |\n| `frontend/src/config/browserCommands.ts` | file-browser command registry for command-palette behavior |\n| `frontend/src/hooks/useKeyboardShortcuts.ts` | shared hook that binds shortcut definitions to runtime handlers |\n| `frontend/src/pages/FileBrowser.tsx` | registers browser-level shortcuts and routes command actions |\n| `frontend/src/components/Viewer/` | consumes shared shortcut definitions for viewer behavior and tooltip labels |\n| `frontend/src/components/Viewer/CodeMirrorFindReplacePopover.tsx` | shared compact find, match-option, and replacement controls for CodeMirror editors |\n\nThe system is intentionally split so shortcuts stay declarative while feature surfaces keep control of their own runtime behavior.\n\n## Why the Registry Exists\n\nBefore the centralized model, shortcut keys, tooltip labels, and component handlers drifted apart easily.\n\nThe current approach preserves these rules:\n\n- define shortcut keys and display intent once\n- reuse the same definition across viewers and file-browser surfaces\n- let components supply handlers without redefining labels and modifiers\n- keep file-browser actions discoverable even when users do not know the shortcut\n\n## Shortcut Definition Model\n\nShortcut definitions are grouped by scope, such as common viewer actions, PDF-specific actions, image-viewer actions, or browser actions.\n\nRepresentative structure:\n\n```typescript\nexport const COMMON_SHORTCUTS = {\n  CLOSE: {\n    id: \"close\",\n    keys: \"Escape\",\n    description: \"Close\",\n    label: \"Esc\",\n    allowInInput: true,\n  },\n  DOWNLOAD: {\n    id: \"download\",\n    keys: \"s\",\n    description: \"Download\",\n    label: \"Ctrl+S\",\n    ctrl: true,\n  },\n} as const;\n```\n\nCommon properties include:\n\n- `id`: stable identifier\n- `keys`: one key or multiple equivalent keys\n- `description`: human-readable intent\n- `label`: optional display label; if omitted, it can be generated from the config\n- `ctrl`, `shift`, `alt`: required modifiers\n- `allowInInput`: whether the shortcut still works while an input is focused\n- `priority`: ordering for overlapping shortcut candidates\n\n## Using the Shared Hook\n\nFeature components bind runtime behavior through `useKeyboardShortcuts` instead of duplicating event parsing logic.\n\nTypical usage:\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...COMMON_SHORTCUTS.CLOSE,\n      handler: onClose,\n    },\n    {\n      ...COMMON_SHORTCUTS.DOWNLOAD,\n      handler: handleDownload,\n    },\n    {\n      ...PDF_SHORTCUTS.SEARCH,\n      handler: handleOpenSearch,\n    },\n  ],\n});\n```\n\nThat split keeps the registry declarative and keeps feature logic in the feature component.\n\n## Labels and Tooltip Reuse\n\nViewer controls and similar UI surfaces should reuse the same shortcut definition instead of duplicating string formatting.\n\nThe shared formatter can turn a shortcut definition into a tooltip label such as `Download (Ctrl+S)`.\n\nThat matters because a changed shortcut should update viewer behavior and visible affordances together.\n\n## Browser Commands Versus Raw Shortcuts\n\nThe file browser uses both shortcut definitions and a command registry.\n\n- shortcut definitions remain centralized in `keyboardShortcuts.ts`\n- discoverable browser actions live in `browserCommands.ts`\n- command definitions point back to shortcut identifiers when a keyboard binding exists\n\nThis lets Sambee expose browser actions through the quick bar even when the user does not know the shortcut.\n\nEach browser command definition includes concepts such as:\n\n- a stable `id`\n- a user-facing `title`\n- a `category` for command grouping\n- linked shortcut identifiers\n- `isEnabled(context)` for context-aware availability\n- `run(context)` for execution\n- `selectionFocusTarget` for post-selection focus behavior\n\n## Quick-Bar Modes\n\nThe file browser quick bar is not just a text filter. It supports multiple modes with different intent.\n\n- `Ctrl+K`: open the smart navigation surface\n- `Ctrl+Alt+F`: open pane-local current-directory filter mode\n- `Ctrl+P`: open command mode directly\n- typing `\u003e` as the first character switches the quick bar into command mode\n\nSmart navigation and command mode are dropdown-backed provider modes. Filter mode deliberately is not.\n\n- `smart` mode uses the search provider composition that merges directory navigation and command escape-hatch behavior\n- `commands` mode uses the browser command registry directly\n- `filter` mode uses the same input shell, but as a controlled pane-local filter box with dropdown rendering disabled\n\nThe quick bar captures the pane that opened it. In dual-pane mode, the active quick-bar pane stays fixed even if the other pane becomes active before selection.\n\nThat capture rule matters especially for filter mode, because the filter text belongs to the pane state, not to the shared quick-bar component.\n\n### Current-Directory Filter Mode\n\n`Ctrl+Alt+F` is now a real current-directory filter workflow, not a smart-navigation alias.\n\nThe implemented contract is:\n\n- the active pane opens the quick bar in `filter` mode\n- the quick bar shows that pane's `currentDirectoryFilter` as a controlled value\n- typing filters the pane's visible file list immediately\n- no dropdown results are shown in this mode\n- `ArrowDown` hands focus from the input into the pane's file list\n- `Escape` clears the filter first, then returns focus to the file list when the input is already empty\n\nThe filter state is pane-local and scoped to the current `connectionId + path`.\n\n- switching between `smart`, `commands`, and `filter` modes does not clear the current directory filter\n- navigating to a different directory clears the filter for the new scope\n- changing the pane's connection also clears the filter for the new scope\n- the status bar remains the persistent reminder that a filter is active even when the quick bar is in another mode\n\n## Current Browser-Level Shortcuts\n\nCurrent browser-level shortcuts include:\n\n- `Ctrl+K`: open smart navigation\n- `Ctrl+Alt+F`: focus current-directory filter mode for the active pane\n- `Ctrl+P`: show commands\n- `Ctrl+,`: open settings\n- `?` or `F1`: show keyboard shortcuts help\n- `Backspace`: go up one directory\n- `Ctrl+R`: refresh file list\n- `F2`: rename focused item\n- `Delete`: delete focused item\n- `F7`: create new directory\n- `Shift+F7`: create new file\n- `Ctrl+Enter`: open focused file in the companion app\n- `Ctrl+B`: toggle dual-pane view\n- `Ctrl+1`: focus left pane\n- `Ctrl+2`: focus right pane\n- `Tab`: switch active pane\n- `F5`: copy to the other pane\n- `F6`: move to the other pane\n\nWhen changing these, treat the behavior as product-level interaction design rather than local implementation detail.\n\n## Focus and Interaction Rules\n\nShortcut work often breaks focus behavior before it breaks functionality. Keep these rules intact:\n\n- opening the quick bar focuses its input immediately\n- selecting a navigation result returns focus to the relevant file list\n- selecting commands that switch quick-bar modes keeps focus inside the quick bar\n- `ArrowDown` from current-directory filter mode moves focus into the filtered file list\n- current-directory filter mode does not open a dropdown for local matches\n- `Escape` in filter mode clears the active filter before it hands focus back to the file list\n- commands that open dialogs or settings do not force focus back to the file list\n- pane-switching shortcuts do not fire while the quick-bar input is focused\n- shortcuts that should work during text entry must explicitly opt in with `allowInInput`\n- shortcuts should be disabled when dialog state or viewer state would make them unsafe\n\n## Context-Aware Shortcut Handling\n\nWhen one key needs different behavior depending on state, prefer one context-aware handler over overlapping registrations.\n\nFor example, `Escape` may close a search panel when that panel is open, but close the viewer when it is not.\n\nThat pattern is better than registering multiple conflicting `Escape` shortcuts because:\n\n- one shortcut definition stays authoritative\n- behavior remains explicit in the component state logic\n- conflicts are easier to reason about and test\n\n### Priority as an Escape Hatch\n\nIn rare cases, multiple handlers for one key are unavoidable. The system supports a `priority` field so higher-priority candidates are evaluated first.\n\nUse that sparingly. A context-aware handler is usually easier to understand and maintain than several competing registrations.\n\n## Adding New Shortcuts Safely\n\nWhen you add a shortcut, keep the workflow centralized.\n\n1. define the shortcut in `config/keyboardShortcuts.ts`\n1. bind it through `useKeyboardShortcuts` in the feature component\n1. reuse the same definition for tooltip or help-surface labels\n1. test both the runtime behavior and the visible affordance\n\nTypical sequence:\n\n```typescript\nexport const PDF_SHORTCUTS = {\n  PRINT: {\n    id: \"print\",\n    keys: \"p\",\n    description: \"Print\",\n    label: \"Ctrl+P\",\n    ctrl: true,\n  },\n} as const;\n```\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...PDF_SHORTCUTS.PRINT,\n      handler: handlePrint,\n    },\n  ],\n});\n```\n\n```typescript\ntitle={withShortcut(PDF_SHORTCUTS.PRINT)}\n```\n\nDo not add one-off tooltip strings or imperative event parsing when the shortcut belongs in the shared system.\n\n## CodeMirror Find and Replace\n\nMarkdown and text editing keep find and replace in an editor-local fixed surface near the upper-right viewport edge, below the viewer toolbar, rather than in the shared viewer toolbar. `MarkdownViewer` and `TextViewer` own the surrounding viewer state and bind `Ctrl+H`, `Alt+C`, `Alt+W`, and `Alt+R` through `CODEMIRROR_EDITOR_SHORTCUTS`. The existing shared `F3` and `Shift+F3` registrations remain the navigation authority, including while a find or replace input has focus. `Enter` and `Ctrl+Alt+Enter` are also declared in that registry for replace-current and replace-all, but their `allowInInputWithin` scope limits them to the replacement field.\n\n`codeMirrorFindReplace.ts` owns the shared `SearchQuery` construction, validity-aware metrics, and auto-navigation logic. `MarkdownRichEditor` and `TextCodeEditor` map the controlled state to that API and use CodeMirror's native `replaceNext` and `replaceAll` commands. Keep replacement operations on those native commands so CodeMirror owns selection updates and undo transactions. Search metrics must check the query validity before creating a cursor because an invalid regular expression cannot produce one.\n\n`CodeMirrorFindReplacePopover` is intentionally non-modal so the editor remains visible and keyboard navigation remains continuous. Its Find and Replace inputs come first in DOM order to preserve the first two tab stops. The history affordance is supplied by the in-field `Search (\u21c5 for history)` and `Replace (\u21c5 for history)` placeholders; result count, match options, navigation, and close controls occupy the first row to the inputs' right. `codeMirrorFindReplaceHistory.ts` persists independent Find and Replace histories in local storage, safely tolerating unavailable or malformed storage and retaining only the ten newest unique non-empty values. Reuse dialog surface tokens for its paper, but do not use `ResponsiveFormDialog`: full-screen viewers retain their specialized focus and layout shell.\n\n## Label Formatting Rules\n\nThe shortcut system also owns display formatting.\n\n- `ArrowRight` becomes `Right`\n- `ArrowLeft` becomes `Left`\n- `ArrowUp` becomes `Up`\n- `ArrowDown` becomes `Down`\n- `Escape` becomes `Esc`\n- space becomes `Space`\n- multiple equivalent keys are joined with ` / `\n- modifiers render as `Ctrl+`, `Shift+`, and `Alt+`\n\nThat formatting should come from the shared system, not from ad hoc component strings.\n\n## Common Failure Modes\n\n- shortcut keys and visible labels drift apart\n- a component registers imperative keyboard logic instead of using the shared hook\n- the browser command palette exposes actions that do not respect the current UI context\n- shortcuts fire while text input or dialog state should block them\n- quick-bar focus returns to the wrong pane in dual-pane workflows\n- multiple overlapping handlers compete for one key instead of using a context-aware handler\n\n## Validation Expectations\n\nWhen keyboard behavior changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change affects file-browser behavior, also test:\n\n- quick-bar navigation and command mode\n- pane switching in dual-pane and single-pane layouts\n- dialog safety for destructive shortcuts\n- viewer shortcut labels and matching runtime behavior\n\nFor new shortcut registrations, also verify:\n\n- the shared label matches the actual bound keys\n- `allowInInput` behavior matches the intended text-entry experience\n- priority and enabled-state logic do not create hidden overlaps\n\n## Where to Continue\n\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL sync, selection, and refresh behavior\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): viewer reuse, preview behavior, and file-type contracts\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): other shared frontend systems contributors should keep centralized\n", "2.0": "+++\ntitle = \"Keyboard Shortcuts and Command Model\"\n+++\n\nKeyboard behavior in Sambee is a shared frontend system, not a pile of local `keydown` handlers.\n\nThe product depends on contributors keeping shortcuts, command labels, viewer controls, and file-browser focus behavior aligned.\n\n## Core Pieces\n\nThese files define the keyboard and command model:\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/config/keyboardShortcuts.ts` | single source of truth for shortcut definitions and display labels |\n| `frontend/src/config/browserCommands.ts` | file-browser command registry for command-palette behavior |\n| `frontend/src/hooks/useKeyboardShortcuts.ts` | shared hook that binds shortcut definitions to runtime handlers |\n| `frontend/src/pages/FileBrowser.tsx` | registers browser-level shortcuts and routes command actions |\n| `frontend/src/components/Viewer/` | consumes shared shortcut definitions for viewer behavior and tooltip labels |\n| `frontend/src/components/Viewer/CodeMirrorFindReplacePopover.tsx` | shared compact find, match-option, and replacement controls for CodeMirror editors |\n\nThe system is intentionally split so shortcuts stay declarative while feature surfaces keep control of their own runtime behavior.\n\n## Why the Registry Exists\n\nBefore the centralized model, shortcut keys, tooltip labels, and component handlers drifted apart easily.\n\nThe current approach preserves these rules:\n\n- define shortcut keys and display intent once\n- reuse the same definition across viewers and file-browser surfaces\n- let components supply handlers without redefining labels and modifiers\n- keep file-browser actions discoverable even when users do not know the shortcut\n\n## Shortcut Definition Model\n\nShortcut definitions are grouped by scope, such as common viewer actions, PDF-specific actions, image-viewer actions, or browser actions.\n\nRepresentative structure:\n\n```typescript\nexport const COMMON_SHORTCUTS = {\n  CLOSE: {\n    id: \"close\",\n    keys: \"Escape\",\n    description: \"Close\",\n    label: \"Esc\",\n    allowInInput: true,\n  },\n  DOWNLOAD: {\n    id: \"download\",\n    keys: \"s\",\n    description: \"Download\",\n    label: \"Ctrl+S\",\n    ctrl: true,\n  },\n} as const;\n```\n\nCommon properties include:\n\n- `id`: stable identifier\n- `keys`: one key or multiple equivalent keys\n- `description`: human-readable intent\n- `label`: optional display label; if omitted, it can be generated from the config\n- `ctrl`, `shift`, `alt`: required modifiers\n- `allowInInput`: whether the shortcut still works while an input is focused\n- `priority`: ordering for overlapping shortcut candidates\n\n## Using the Shared Hook\n\nFeature components bind runtime behavior through `useKeyboardShortcuts` instead of duplicating event parsing logic.\n\nTypical usage:\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...COMMON_SHORTCUTS.CLOSE,\n      handler: onClose,\n    },\n    {\n      ...COMMON_SHORTCUTS.DOWNLOAD,\n      handler: handleDownload,\n    },\n    {\n      ...PDF_SHORTCUTS.SEARCH,\n      handler: handleOpenSearch,\n    },\n  ],\n});\n```\n\nThat split keeps the registry declarative and keeps feature logic in the feature component.\n\n## Labels and Tooltip Reuse\n\nViewer controls and similar UI surfaces should reuse the same shortcut definition instead of duplicating string formatting.\n\nThe shared formatter can turn a shortcut definition into a tooltip label such as `Download (Ctrl+S)`.\n\nThat matters because a changed shortcut should update viewer behavior and visible affordances together.\n\n## Browser Commands Versus Raw Shortcuts\n\nThe file browser uses both shortcut definitions and a command registry.\n\n- shortcut definitions remain centralized in `keyboardShortcuts.ts`\n- discoverable browser actions live in `browserCommands.ts`\n- command definitions point back to shortcut identifiers when a keyboard binding exists\n\nThis lets Sambee expose browser actions through the quick bar even when the user does not know the shortcut.\n\nEach browser command definition includes concepts such as:\n\n- a stable `id`\n- a user-facing `title`\n- a `category` for command grouping\n- linked shortcut identifiers\n- `isEnabled(context)` for context-aware availability\n- `run(context)` for execution\n- `selectionFocusTarget` for post-selection focus behavior\n\n## Quick-Bar Modes\n\nThe file browser quick bar is not just a text filter. It supports multiple modes with different intent.\n\n- `Ctrl+K`: open the smart navigation surface\n- `Ctrl+Alt+F`: open pane-local current-directory filter mode\n- `Ctrl+P`: open command mode directly\n- typing `\u003e` as the first character switches the quick bar into command mode\n\nSmart navigation and command mode are dropdown-backed provider modes. Filter mode deliberately is not.\n\n- `smart` mode uses the search provider composition that merges directory navigation and command escape-hatch behavior\n- `commands` mode uses the browser command registry directly\n- `filter` mode uses the same input shell, but as a controlled pane-local filter box with dropdown rendering disabled\n\nThe quick bar captures the pane that opened it. In dual-pane mode, the active quick-bar pane stays fixed even if the other pane becomes active before selection.\n\nThat capture rule matters especially for filter mode, because the filter text belongs to the pane state, not to the shared quick-bar component.\n\n### Current-Directory Filter Mode\n\n`Ctrl+Alt+F` is now a real current-directory filter workflow, not a smart-navigation alias.\n\nThe implemented contract is:\n\n- the active pane opens the quick bar in `filter` mode\n- the quick bar shows that pane's `currentDirectoryFilter` as a controlled value\n- typing filters the pane's visible file list immediately\n- no dropdown results are shown in this mode\n- `ArrowDown` hands focus from the input into the pane's file list\n- `Escape` clears the filter first, then returns focus to the file list when the input is already empty\n\nThe filter state is pane-local and scoped to the current `connectionId + path`.\n\n- switching between `smart`, `commands`, and `filter` modes does not clear the current directory filter\n- navigating to a different directory clears the filter for the new scope\n- changing the pane's connection also clears the filter for the new scope\n- the status bar remains the persistent reminder that a filter is active even when the quick bar is in another mode\n\n## Current Browser-Level Shortcuts\n\nCurrent browser-level shortcuts include:\n\n- `Ctrl+K`: open smart navigation\n- `Ctrl+Alt+F`: focus current-directory filter mode for the active pane\n- `Ctrl+P`: show commands\n- `Ctrl+,`: open settings\n- `?` or `F1`: show keyboard shortcuts help\n- `Backspace`: go up one directory\n- `Ctrl+R`: refresh file list\n- `F2`: rename focused item\n- `Delete`: delete focused item\n- `F7`: create new directory\n- `Shift+F7`: create new file\n- `Ctrl+Enter`: open focused file in the companion app\n- `Ctrl+B`: toggle dual-pane view\n- `Ctrl+1`: focus left pane\n- `Ctrl+2`: focus right pane\n- `Tab`: switch active pane\n- `F5`: copy to the other pane\n- `F6`: move to the other pane\n\nWhen changing these, treat the behavior as product-level interaction design rather than local implementation detail.\n\n## Focus and Interaction Rules\n\nShortcut work often breaks focus behavior before it breaks functionality. Keep these rules intact:\n\n- opening the quick bar focuses its input immediately\n- selecting a navigation result returns focus to the relevant file list\n- selecting commands that switch quick-bar modes keeps focus inside the quick bar\n- `ArrowDown` from current-directory filter mode moves focus into the filtered file list\n- current-directory filter mode does not open a dropdown for local matches\n- `Escape` in filter mode clears the active filter before it hands focus back to the file list\n- commands that open dialogs or settings do not force focus back to the file list\n- pane-switching shortcuts do not fire while the quick-bar input is focused\n- shortcuts that should work during text entry must explicitly opt in with `allowInInput`\n- shortcuts should be disabled when dialog state or viewer state would make them unsafe\n\n## Context-Aware Shortcut Handling\n\nWhen one key needs different behavior depending on state, prefer one context-aware handler over overlapping registrations.\n\nFor example, `Escape` may close a search panel when that panel is open, but close the viewer when it is not.\n\nThat pattern is better than registering multiple conflicting `Escape` shortcuts because:\n\n- one shortcut definition stays authoritative\n- behavior remains explicit in the component state logic\n- conflicts are easier to reason about and test\n\n### Priority as an Escape Hatch\n\nIn rare cases, multiple handlers for one key are unavoidable. The system supports a `priority` field so higher-priority candidates are evaluated first.\n\nUse that sparingly. A context-aware handler is usually easier to understand and maintain than several competing registrations.\n\n## Adding New Shortcuts Safely\n\nWhen you add a shortcut, keep the workflow centralized.\n\n1. define the shortcut in `config/keyboardShortcuts.ts`\n1. bind it through `useKeyboardShortcuts` in the feature component\n1. reuse the same definition for tooltip or help-surface labels\n1. test both the runtime behavior and the visible affordance\n\nTypical sequence:\n\n```typescript\nexport const PDF_SHORTCUTS = {\n  PRINT: {\n    id: \"print\",\n    keys: \"p\",\n    description: \"Print\",\n    label: \"Ctrl+P\",\n    ctrl: true,\n  },\n} as const;\n```\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...PDF_SHORTCUTS.PRINT,\n      handler: handlePrint,\n    },\n  ],\n});\n```\n\n```typescript\ntitle={withShortcut(PDF_SHORTCUTS.PRINT)}\n```\n\nDo not add one-off tooltip strings or imperative event parsing when the shortcut belongs in the shared system.\n\n## CodeMirror Find and Replace\n\nMarkdown and text editing keep find and replace in an editor-local fixed surface near the upper-right viewport edge, below the viewer toolbar, rather than in the shared viewer toolbar. `MarkdownViewer` and `TextViewer` own the surrounding viewer state and bind `Ctrl+H`, `Alt+C`, `Alt+W`, and `Alt+R` through `CODEMIRROR_EDITOR_SHORTCUTS`. The existing shared `F3` and `Shift+F3` registrations remain the navigation authority, including while a find or replace input has focus. `Enter` and `Ctrl+Alt+Enter` are also declared in that registry for replace-current and replace-all, but their `allowInInputWithin` scope limits them to the replacement field.\n\n`codeMirrorFindReplace.ts` owns the shared `SearchQuery` construction, validity-aware metrics, and auto-navigation logic. `MarkdownRichEditor` and `TextCodeEditor` map the controlled state to that API and use CodeMirror's native `replaceNext` and `replaceAll` commands. Keep replacement operations on those native commands so CodeMirror owns selection updates and undo transactions. Search metrics must check the query validity before creating a cursor because an invalid regular expression cannot produce one.\n\n`CodeMirrorFindReplacePopover` is intentionally non-modal so the editor remains visible and keyboard navigation remains continuous. Its Find and Replace inputs come first in DOM order to preserve the first two tab stops. The history affordance is supplied by the in-field `Search (\u21c5 for history)` and `Replace (\u21c5 for history)` placeholders; result count, match options, navigation, and close controls occupy the first row to the inputs' right. `codeMirrorFindReplaceHistory.ts` persists independent Find and Replace histories in local storage, safely tolerating unavailable or malformed storage and retaining only the ten newest unique non-empty values. Reuse dialog surface tokens for its paper, but do not use `ResponsiveFormDialog`: full-screen viewers retain their specialized focus and layout shell.\n\n## Label Formatting Rules\n\nThe shortcut system also owns display formatting.\n\n- `ArrowRight` becomes `Right`\n- `ArrowLeft` becomes `Left`\n- `ArrowUp` becomes `Up`\n- `ArrowDown` becomes `Down`\n- `Escape` becomes `Esc`\n- space becomes `Space`\n- multiple equivalent keys are joined with ` / `\n- modifiers render as `Ctrl+`, `Shift+`, and `Alt+`\n\nThat formatting should come from the shared system, not from ad hoc component strings.\n\n## Common Failure Modes\n\n- shortcut keys and visible labels drift apart\n- a component registers imperative keyboard logic instead of using the shared hook\n- the browser command palette exposes actions that do not respect the current UI context\n- shortcuts fire while text input or dialog state should block them\n- quick-bar focus returns to the wrong pane in dual-pane workflows\n- multiple overlapping handlers compete for one key instead of using a context-aware handler\n\n## Validation Expectations\n\nWhen keyboard behavior changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change affects file-browser behavior, also test:\n\n- quick-bar navigation and command mode\n- pane switching in dual-pane and single-pane layouts\n- dialog safety for destructive shortcuts\n- viewer shortcut labels and matching runtime behavior\n\nFor new shortcut registrations, also verify:\n\n- the shared label matches the actual bound keys\n- `allowInInput` behavior matches the intended text-entry experience\n- priority and enabled-state logic do not create hidden overlaps\n\n## Where to Continue\n\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL sync, selection, and refresh behavior\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): viewer reuse, preview behavior, and file-type contracts\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): other shared frontend systems contributors should keep centralized\n"}, "page_contents": {"0.7": "+++\ntitle = \"Keyboard Shortcuts and Command Model\"\n+++\n\nKeyboard behavior in Sambee is a shared frontend system, not a pile of local `keydown` handlers.\n\nThe product depends on contributors keeping shortcuts, command labels, viewer controls, and file-browser focus behavior aligned.\n\n## Core Pieces\n\nThese files define the keyboard and command model:\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/config/keyboardShortcuts.ts` | single source of truth for shortcut definitions and display labels |\n| `frontend/src/config/browserCommands.ts` | file-browser command registry for command-palette behavior |\n| `frontend/src/hooks/useKeyboardShortcuts.ts` | shared hook that binds shortcut definitions to runtime handlers |\n| `frontend/src/pages/FileBrowser.tsx` | registers browser-level shortcuts and routes command actions |\n| `frontend/src/components/Viewer/` | consumes shared shortcut definitions for viewer behavior and tooltip labels |\n\nThe system is intentionally split so shortcuts stay declarative while feature surfaces keep control of their own runtime behavior.\n\n## Why the Registry Exists\n\nBefore the centralized model, shortcut keys, tooltip labels, and component handlers drifted apart easily.\n\nThe current approach preserves these rules:\n\n- define shortcut keys and display intent once\n- reuse the same definition across viewers and file-browser surfaces\n- let components supply handlers without redefining labels and modifiers\n- keep file-browser actions discoverable even when users do not know the shortcut\n\n## Shortcut Definition Model\n\nShortcut definitions are grouped by scope, such as common viewer actions, PDF-specific actions, image-viewer actions, or browser actions.\n\nRepresentative structure:\n\n```typescript\nexport const COMMON_SHORTCUTS = {\n  CLOSE: {\n    id: \"close\",\n    keys: \"Escape\",\n    description: \"Close\",\n    label: \"Esc\",\n    allowInInput: true,\n  },\n  DOWNLOAD: {\n    id: \"download\",\n    keys: \"s\",\n    description: \"Download\",\n    label: \"Ctrl+S\",\n    ctrl: true,\n  },\n} as const;\n```\n\nCommon properties include:\n\n- `id`: stable identifier\n- `keys`: one key or multiple equivalent keys\n- `description`: human-readable intent\n- `label`: optional display label; if omitted, it can be generated from the config\n- `ctrl`, `shift`, `alt`: required modifiers\n- `allowInInput`: whether the shortcut still works while an input is focused\n- `priority`: ordering for overlapping shortcut candidates\n\n## Using the Shared Hook\n\nFeature components bind runtime behavior through `useKeyboardShortcuts` instead of duplicating event parsing logic.\n\nTypical usage:\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...COMMON_SHORTCUTS.CLOSE,\n      handler: onClose,\n    },\n    {\n      ...COMMON_SHORTCUTS.DOWNLOAD,\n      handler: handleDownload,\n    },\n    {\n      ...PDF_SHORTCUTS.SEARCH,\n      handler: handleOpenSearch,\n    },\n  ],\n});\n```\n\nThat split keeps the registry declarative and keeps feature logic in the feature component.\n\n## Labels and Tooltip Reuse\n\nViewer controls and similar UI surfaces should reuse the same shortcut definition instead of duplicating string formatting.\n\nThe shared formatter can turn a shortcut definition into a tooltip label such as `Download (Ctrl+S)`.\n\nThat matters because a changed shortcut should update viewer behavior and visible affordances together.\n\n## Browser Commands Versus Raw Shortcuts\n\nThe file browser uses both shortcut definitions and a command registry.\n\n- shortcut definitions remain centralized in `keyboardShortcuts.ts`\n- discoverable browser actions live in `browserCommands.ts`\n- command definitions point back to shortcut identifiers when a keyboard binding exists\n\nThis lets Sambee expose browser actions through the quick bar even when the user does not know the shortcut.\n\nEach browser command definition includes concepts such as:\n\n- a stable `id`\n- a user-facing `title`\n- a `category` for command grouping\n- linked shortcut identifiers\n- `isEnabled(context)` for context-aware availability\n- `run(context)` for execution\n- `selectionFocusTarget` for post-selection focus behavior\n\n## Quick-Bar Modes\n\nThe file browser quick bar is not just a text filter. It supports multiple modes with different intent.\n\n- `Ctrl+K`: open the smart navigation surface\n- `Ctrl+Alt+F`: open pane-local current-directory filter mode\n- `Ctrl+P` or `F1`: open command mode directly\n- typing `\u003e` as the first character switches the quick bar into command mode\n\nSmart navigation and command mode are dropdown-backed provider modes. Filter mode deliberately is not.\n\n- `smart` mode uses the search provider composition that merges directory navigation and command escape-hatch behavior\n- `commands` mode uses the browser command registry directly\n- `filter` mode uses the same input shell, but as a controlled pane-local filter box with dropdown rendering disabled\n\nThe quick bar captures the pane that opened it. In dual-pane mode, the active quick-bar pane stays fixed even if the other pane becomes active before selection.\n\nThat capture rule matters especially for filter mode, because the filter text belongs to the pane state, not to the shared quick-bar component.\n\n### Current-Directory Filter Mode\n\n`Ctrl+Alt+F` is now a real current-directory filter workflow, not a smart-navigation alias.\n\nThe implemented contract is:\n\n- the active pane opens the quick bar in `filter` mode\n- the quick bar shows that pane's `currentDirectoryFilter` as a controlled value\n- typing filters the pane's visible file list immediately\n- no dropdown results are shown in this mode\n- `ArrowDown` hands focus from the input into the pane's file list\n- `Escape` clears the filter first, then returns focus to the file list when the input is already empty\n\nThe filter state is pane-local and scoped to the current `connectionId + path`.\n\n- switching between `smart`, `commands`, and `filter` modes does not clear the current directory filter\n- navigating to a different directory clears the filter for the new scope\n- changing the pane's connection also clears the filter for the new scope\n- the status bar remains the persistent reminder that a filter is active even when the quick bar is in another mode\n\n## Current Browser-Level Shortcuts\n\nCurrent browser-level shortcuts include:\n\n- `Ctrl+K`: open smart navigation\n- `Ctrl+Alt+F`: focus current-directory filter mode for the active pane\n- `Ctrl+P`: show commands\n- `F1`: alternate binding for show commands\n- `Ctrl+,`: open settings\n- `?`: show keyboard shortcuts help\n- `Backspace`: go up one directory\n- `Ctrl+R`: refresh file list\n- `F2`: rename focused item\n- `Delete`: delete focused item\n- `F7`: create new directory\n- `Shift+F7`: create new file\n- `Ctrl+Enter`: open focused file in the companion app\n- `Ctrl+B`: toggle dual-pane view\n- `Ctrl+1`: focus left pane\n- `Ctrl+2`: focus right pane\n- `Tab`: switch active pane\n- `F5`: copy to the other pane\n- `F6`: move to the other pane\n\nWhen changing these, treat the behavior as product-level interaction design rather than local implementation detail.\n\n## Focus and Interaction Rules\n\nShortcut work often breaks focus behavior before it breaks functionality. Keep these rules intact:\n\n- opening the quick bar focuses its input immediately\n- selecting a navigation result returns focus to the relevant file list\n- selecting commands that switch quick-bar modes keeps focus inside the quick bar\n- `ArrowDown` from current-directory filter mode moves focus into the filtered file list\n- current-directory filter mode does not open a dropdown for local matches\n- `Escape` in filter mode clears the active filter before it hands focus back to the file list\n- commands that open dialogs or settings do not force focus back to the file list\n- pane-switching shortcuts do not fire while the quick-bar input is focused\n- shortcuts that should work during text entry must explicitly opt in with `allowInInput`\n- shortcuts should be disabled when dialog state or viewer state would make them unsafe\n\n## Context-Aware Shortcut Handling\n\nWhen one key needs different behavior depending on state, prefer one context-aware handler over overlapping registrations.\n\nFor example, `Escape` may close a search panel when that panel is open, but close the viewer when it is not.\n\nThat pattern is better than registering multiple conflicting `Escape` shortcuts because:\n\n- one shortcut definition stays authoritative\n- behavior remains explicit in the component state logic\n- conflicts are easier to reason about and test\n\n### Priority as an Escape Hatch\n\nIn rare cases, multiple handlers for one key are unavoidable. The system supports a `priority` field so higher-priority candidates are evaluated first.\n\nUse that sparingly. A context-aware handler is usually easier to understand and maintain than several competing registrations.\n\n## Adding New Shortcuts Safely\n\nWhen you add a shortcut, keep the workflow centralized.\n\n1. define the shortcut in `config/keyboardShortcuts.ts`\n2. bind it through `useKeyboardShortcuts` in the feature component\n3. reuse the same definition for tooltip or help-surface labels\n4. test both the runtime behavior and the visible affordance\n\nTypical sequence:\n\n```typescript\nexport const PDF_SHORTCUTS = {\n  PRINT: {\n    id: \"print\",\n    keys: \"p\",\n    description: \"Print\",\n    label: \"Ctrl+P\",\n    ctrl: true,\n  },\n} as const;\n```\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...PDF_SHORTCUTS.PRINT,\n      handler: handlePrint,\n    },\n  ],\n});\n```\n\n```typescript\ntitle={withShortcut(PDF_SHORTCUTS.PRINT)}\n```\n\nDo not add one-off tooltip strings or imperative event parsing when the shortcut belongs in the shared system.\n\n## Label Formatting Rules\n\nThe shortcut system also owns display formatting.\n\n- `ArrowRight` becomes `Right`\n- `ArrowLeft` becomes `Left`\n- `ArrowUp` becomes `Up`\n- `ArrowDown` becomes `Down`\n- `Escape` becomes `Esc`\n- space becomes `Space`\n- multiple equivalent keys are joined with ` / `\n- modifiers render as `Ctrl+`, `Shift+`, and `Alt+`\n\nThat formatting should come from the shared system, not from ad hoc component strings.\n\n## Common Failure Modes\n\n- shortcut keys and visible labels drift apart\n- a component registers imperative keyboard logic instead of using the shared hook\n- the browser command palette exposes actions that do not respect the current UI context\n- shortcuts fire while text input or dialog state should block them\n- quick-bar focus returns to the wrong pane in dual-pane workflows\n- multiple overlapping handlers compete for one key instead of using a context-aware handler\n\n## Validation Expectations\n\nWhen keyboard behavior changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change affects file-browser behavior, also test:\n\n- quick-bar navigation and command mode\n- pane switching in dual-pane and single-pane layouts\n- dialog safety for destructive shortcuts\n- viewer shortcut labels and matching runtime behavior\n\nFor new shortcut registrations, also verify:\n\n- the shared label matches the actual bound keys\n- `allowInInput` behavior matches the intended text-entry experience\n- priority and enabled-state logic do not create hidden overlaps\n\n## Where to Continue\n\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL sync, selection, and refresh behavior\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): viewer reuse, preview behavior, and file-type contracts\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): other shared frontend systems contributors should keep centralized\n", "0.8": "+++\ntitle = \"Keyboard Shortcuts and Command Model\"\n+++\n\nKeyboard behavior in Sambee is a shared frontend system, not a pile of local `keydown` handlers.\n\nThe product depends on contributors keeping shortcuts, command labels, viewer controls, and file-browser focus behavior aligned.\n\n## Core Pieces\n\nThese files define the keyboard and command model:\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/config/keyboardShortcuts.ts` | single source of truth for shortcut definitions and display labels |\n| `frontend/src/config/browserCommands.ts` | file-browser command registry for command-palette behavior |\n| `frontend/src/hooks/useKeyboardShortcuts.ts` | shared hook that binds shortcut definitions to runtime handlers |\n| `frontend/src/pages/FileBrowser.tsx` | registers browser-level shortcuts and routes command actions |\n| `frontend/src/components/Viewer/` | consumes shared shortcut definitions for viewer behavior and tooltip labels |\n\nThe system is intentionally split so shortcuts stay declarative while feature surfaces keep control of their own runtime behavior.\n\n## Why the Registry Exists\n\nBefore the centralized model, shortcut keys, tooltip labels, and component handlers drifted apart easily.\n\nThe current approach preserves these rules:\n\n- define shortcut keys and display intent once\n- reuse the same definition across viewers and file-browser surfaces\n- let components supply handlers without redefining labels and modifiers\n- keep file-browser actions discoverable even when users do not know the shortcut\n\n## Shortcut Definition Model\n\nShortcut definitions are grouped by scope, such as common viewer actions, PDF-specific actions, image-viewer actions, or browser actions.\n\nRepresentative structure:\n\n```typescript\nexport const COMMON_SHORTCUTS = {\n  CLOSE: {\n    id: \"close\",\n    keys: \"Escape\",\n    description: \"Close\",\n    label: \"Esc\",\n    allowInInput: true,\n  },\n  DOWNLOAD: {\n    id: \"download\",\n    keys: \"s\",\n    description: \"Download\",\n    label: \"Ctrl+S\",\n    ctrl: true,\n  },\n} as const;\n```\n\nCommon properties include:\n\n- `id`: stable identifier\n- `keys`: one key or multiple equivalent keys\n- `description`: human-readable intent\n- `label`: optional display label; if omitted, it can be generated from the config\n- `ctrl`, `shift`, `alt`: required modifiers\n- `allowInInput`: whether the shortcut still works while an input is focused\n- `priority`: ordering for overlapping shortcut candidates\n\n## Using the Shared Hook\n\nFeature components bind runtime behavior through `useKeyboardShortcuts` instead of duplicating event parsing logic.\n\nTypical usage:\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...COMMON_SHORTCUTS.CLOSE,\n      handler: onClose,\n    },\n    {\n      ...COMMON_SHORTCUTS.DOWNLOAD,\n      handler: handleDownload,\n    },\n    {\n      ...PDF_SHORTCUTS.SEARCH,\n      handler: handleOpenSearch,\n    },\n  ],\n});\n```\n\nThat split keeps the registry declarative and keeps feature logic in the feature component.\n\n## Labels and Tooltip Reuse\n\nViewer controls and similar UI surfaces should reuse the same shortcut definition instead of duplicating string formatting.\n\nThe shared formatter can turn a shortcut definition into a tooltip label such as `Download (Ctrl+S)`.\n\nThat matters because a changed shortcut should update viewer behavior and visible affordances together.\n\n## Browser Commands Versus Raw Shortcuts\n\nThe file browser uses both shortcut definitions and a command registry.\n\n- shortcut definitions remain centralized in `keyboardShortcuts.ts`\n- discoverable browser actions live in `browserCommands.ts`\n- command definitions point back to shortcut identifiers when a keyboard binding exists\n\nThis lets Sambee expose browser actions through the quick bar even when the user does not know the shortcut.\n\nEach browser command definition includes concepts such as:\n\n- a stable `id`\n- a user-facing `title`\n- a `category` for command grouping\n- linked shortcut identifiers\n- `isEnabled(context)` for context-aware availability\n- `run(context)` for execution\n- `selectionFocusTarget` for post-selection focus behavior\n\n## Quick-Bar Modes\n\nThe file browser quick bar is not just a text filter. It supports multiple modes with different intent.\n\n- `Ctrl+K`: open the smart navigation surface\n- `Ctrl+Alt+F`: open pane-local current-directory filter mode\n- `Ctrl+P` or `F1`: open command mode directly\n- typing `\u003e` as the first character switches the quick bar into command mode\n\nSmart navigation and command mode are dropdown-backed provider modes. Filter mode deliberately is not.\n\n- `smart` mode uses the search provider composition that merges directory navigation and command escape-hatch behavior\n- `commands` mode uses the browser command registry directly\n- `filter` mode uses the same input shell, but as a controlled pane-local filter box with dropdown rendering disabled\n\nThe quick bar captures the pane that opened it. In dual-pane mode, the active quick-bar pane stays fixed even if the other pane becomes active before selection.\n\nThat capture rule matters especially for filter mode, because the filter text belongs to the pane state, not to the shared quick-bar component.\n\n### Current-Directory Filter Mode\n\n`Ctrl+Alt+F` is now a real current-directory filter workflow, not a smart-navigation alias.\n\nThe implemented contract is:\n\n- the active pane opens the quick bar in `filter` mode\n- the quick bar shows that pane's `currentDirectoryFilter` as a controlled value\n- typing filters the pane's visible file list immediately\n- no dropdown results are shown in this mode\n- `ArrowDown` hands focus from the input into the pane's file list\n- `Escape` clears the filter first, then returns focus to the file list when the input is already empty\n\nThe filter state is pane-local and scoped to the current `connectionId + path`.\n\n- switching between `smart`, `commands`, and `filter` modes does not clear the current directory filter\n- navigating to a different directory clears the filter for the new scope\n- changing the pane's connection also clears the filter for the new scope\n- the status bar remains the persistent reminder that a filter is active even when the quick bar is in another mode\n\n## Current Browser-Level Shortcuts\n\nCurrent browser-level shortcuts include:\n\n- `Ctrl+K`: open smart navigation\n- `Ctrl+Alt+F`: focus current-directory filter mode for the active pane\n- `Ctrl+P`: show commands\n- `F1`: alternate binding for show commands\n- `Ctrl+,`: open settings\n- `?`: show keyboard shortcuts help\n- `Backspace`: go up one directory\n- `Ctrl+R`: refresh file list\n- `F2`: rename focused item\n- `Delete`: delete focused item\n- `F7`: create new directory\n- `Shift+F7`: create new file\n- `Ctrl+Enter`: open focused file in the companion app\n- `Ctrl+B`: toggle dual-pane view\n- `Ctrl+1`: focus left pane\n- `Ctrl+2`: focus right pane\n- `Tab`: switch active pane\n- `F5`: copy to the other pane\n- `F6`: move to the other pane\n\nWhen changing these, treat the behavior as product-level interaction design rather than local implementation detail.\n\n## Focus and Interaction Rules\n\nShortcut work often breaks focus behavior before it breaks functionality. Keep these rules intact:\n\n- opening the quick bar focuses its input immediately\n- selecting a navigation result returns focus to the relevant file list\n- selecting commands that switch quick-bar modes keeps focus inside the quick bar\n- `ArrowDown` from current-directory filter mode moves focus into the filtered file list\n- current-directory filter mode does not open a dropdown for local matches\n- `Escape` in filter mode clears the active filter before it hands focus back to the file list\n- commands that open dialogs or settings do not force focus back to the file list\n- pane-switching shortcuts do not fire while the quick-bar input is focused\n- shortcuts that should work during text entry must explicitly opt in with `allowInInput`\n- shortcuts should be disabled when dialog state or viewer state would make them unsafe\n\n## Context-Aware Shortcut Handling\n\nWhen one key needs different behavior depending on state, prefer one context-aware handler over overlapping registrations.\n\nFor example, `Escape` may close a search panel when that panel is open, but close the viewer when it is not.\n\nThat pattern is better than registering multiple conflicting `Escape` shortcuts because:\n\n- one shortcut definition stays authoritative\n- behavior remains explicit in the component state logic\n- conflicts are easier to reason about and test\n\n### Priority as an Escape Hatch\n\nIn rare cases, multiple handlers for one key are unavoidable. The system supports a `priority` field so higher-priority candidates are evaluated first.\n\nUse that sparingly. A context-aware handler is usually easier to understand and maintain than several competing registrations.\n\n## Adding New Shortcuts Safely\n\nWhen you add a shortcut, keep the workflow centralized.\n\n1. define the shortcut in `config/keyboardShortcuts.ts`\n2. bind it through `useKeyboardShortcuts` in the feature component\n3. reuse the same definition for tooltip or help-surface labels\n4. test both the runtime behavior and the visible affordance\n\nTypical sequence:\n\n```typescript\nexport const PDF_SHORTCUTS = {\n  PRINT: {\n    id: \"print\",\n    keys: \"p\",\n    description: \"Print\",\n    label: \"Ctrl+P\",\n    ctrl: true,\n  },\n} as const;\n```\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...PDF_SHORTCUTS.PRINT,\n      handler: handlePrint,\n    },\n  ],\n});\n```\n\n```typescript\ntitle={withShortcut(PDF_SHORTCUTS.PRINT)}\n```\n\nDo not add one-off tooltip strings or imperative event parsing when the shortcut belongs in the shared system.\n\n## Label Formatting Rules\n\nThe shortcut system also owns display formatting.\n\n- `ArrowRight` becomes `Right`\n- `ArrowLeft` becomes `Left`\n- `ArrowUp` becomes `Up`\n- `ArrowDown` becomes `Down`\n- `Escape` becomes `Esc`\n- space becomes `Space`\n- multiple equivalent keys are joined with ` / `\n- modifiers render as `Ctrl+`, `Shift+`, and `Alt+`\n\nThat formatting should come from the shared system, not from ad hoc component strings.\n\n## Common Failure Modes\n\n- shortcut keys and visible labels drift apart\n- a component registers imperative keyboard logic instead of using the shared hook\n- the browser command palette exposes actions that do not respect the current UI context\n- shortcuts fire while text input or dialog state should block them\n- quick-bar focus returns to the wrong pane in dual-pane workflows\n- multiple overlapping handlers compete for one key instead of using a context-aware handler\n\n## Validation Expectations\n\nWhen keyboard behavior changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change affects file-browser behavior, also test:\n\n- quick-bar navigation and command mode\n- pane switching in dual-pane and single-pane layouts\n- dialog safety for destructive shortcuts\n- viewer shortcut labels and matching runtime behavior\n\nFor new shortcut registrations, also verify:\n\n- the shared label matches the actual bound keys\n- `allowInInput` behavior matches the intended text-entry experience\n- priority and enabled-state logic do not create hidden overlaps\n\n## Where to Continue\n\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL sync, selection, and refresh behavior\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): viewer reuse, preview behavior, and file-type contracts\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): other shared frontend systems contributors should keep centralized\n", "0.9": "+++\ntitle = \"Keyboard Shortcuts and Command Model\"\n+++\n\nKeyboard behavior in Sambee is a shared frontend system, not a pile of local `keydown` handlers.\n\nThe product depends on contributors keeping shortcuts, command labels, viewer controls, and file-browser focus behavior aligned.\n\n## Core Pieces\n\nThese files define the keyboard and command model:\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/config/keyboardShortcuts.ts` | single source of truth for shortcut definitions and display labels |\n| `frontend/src/config/browserCommands.ts` | file-browser command registry for command-palette behavior |\n| `frontend/src/hooks/useKeyboardShortcuts.ts` | shared hook that binds shortcut definitions to runtime handlers |\n| `frontend/src/pages/FileBrowser.tsx` | registers browser-level shortcuts and routes command actions |\n| `frontend/src/components/Viewer/` | consumes shared shortcut definitions for viewer behavior and tooltip labels |\n\nThe system is intentionally split so shortcuts stay declarative while feature surfaces keep control of their own runtime behavior.\n\n## Why the Registry Exists\n\nBefore the centralized model, shortcut keys, tooltip labels, and component handlers drifted apart easily.\n\nThe current approach preserves these rules:\n\n- define shortcut keys and display intent once\n- reuse the same definition across viewers and file-browser surfaces\n- let components supply handlers without redefining labels and modifiers\n- keep file-browser actions discoverable even when users do not know the shortcut\n\n## Shortcut Definition Model\n\nShortcut definitions are grouped by scope, such as common viewer actions, PDF-specific actions, image-viewer actions, or browser actions.\n\nRepresentative structure:\n\n```typescript\nexport const COMMON_SHORTCUTS = {\n  CLOSE: {\n    id: \"close\",\n    keys: \"Escape\",\n    description: \"Close\",\n    label: \"Esc\",\n    allowInInput: true,\n  },\n  DOWNLOAD: {\n    id: \"download\",\n    keys: \"s\",\n    description: \"Download\",\n    label: \"Ctrl+S\",\n    ctrl: true,\n  },\n} as const;\n```\n\nCommon properties include:\n\n- `id`: stable identifier\n- `keys`: one key or multiple equivalent keys\n- `description`: human-readable intent\n- `label`: optional display label; if omitted, it can be generated from the config\n- `ctrl`, `shift`, `alt`: required modifiers\n- `allowInInput`: whether the shortcut still works while an input is focused\n- `priority`: ordering for overlapping shortcut candidates\n\n## Using the Shared Hook\n\nFeature components bind runtime behavior through `useKeyboardShortcuts` instead of duplicating event parsing logic.\n\nTypical usage:\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...COMMON_SHORTCUTS.CLOSE,\n      handler: onClose,\n    },\n    {\n      ...COMMON_SHORTCUTS.DOWNLOAD,\n      handler: handleDownload,\n    },\n    {\n      ...PDF_SHORTCUTS.SEARCH,\n      handler: handleOpenSearch,\n    },\n  ],\n});\n```\n\nThat split keeps the registry declarative and keeps feature logic in the feature component.\n\n## Labels and Tooltip Reuse\n\nViewer controls and similar UI surfaces should reuse the same shortcut definition instead of duplicating string formatting.\n\nThe shared formatter can turn a shortcut definition into a tooltip label such as `Download (Ctrl+S)`.\n\nThat matters because a changed shortcut should update viewer behavior and visible affordances together.\n\n## Browser Commands Versus Raw Shortcuts\n\nThe file browser uses both shortcut definitions and a command registry.\n\n- shortcut definitions remain centralized in `keyboardShortcuts.ts`\n- discoverable browser actions live in `browserCommands.ts`\n- command definitions point back to shortcut identifiers when a keyboard binding exists\n\nThis lets Sambee expose browser actions through the quick bar even when the user does not know the shortcut.\n\nEach browser command definition includes concepts such as:\n\n- a stable `id`\n- a user-facing `title`\n- a `category` for command grouping\n- linked shortcut identifiers\n- `isEnabled(context)` for context-aware availability\n- `run(context)` for execution\n- `selectionFocusTarget` for post-selection focus behavior\n\n## Quick-Bar Modes\n\nThe file browser quick bar is not just a text filter. It supports multiple modes with different intent.\n\n- `Ctrl+K`: open the smart navigation surface\n- `Ctrl+Alt+F`: open pane-local current-directory filter mode\n- `Ctrl+P` or `F1`: open command mode directly\n- typing `\u003e` as the first character switches the quick bar into command mode\n\nSmart navigation and command mode are dropdown-backed provider modes. Filter mode deliberately is not.\n\n- `smart` mode uses the search provider composition that merges directory navigation and command escape-hatch behavior\n- `commands` mode uses the browser command registry directly\n- `filter` mode uses the same input shell, but as a controlled pane-local filter box with dropdown rendering disabled\n\nThe quick bar captures the pane that opened it. In dual-pane mode, the active quick-bar pane stays fixed even if the other pane becomes active before selection.\n\nThat capture rule matters especially for filter mode, because the filter text belongs to the pane state, not to the shared quick-bar component.\n\n### Current-Directory Filter Mode\n\n`Ctrl+Alt+F` is now a real current-directory filter workflow, not a smart-navigation alias.\n\nThe implemented contract is:\n\n- the active pane opens the quick bar in `filter` mode\n- the quick bar shows that pane's `currentDirectoryFilter` as a controlled value\n- typing filters the pane's visible file list immediately\n- no dropdown results are shown in this mode\n- `ArrowDown` hands focus from the input into the pane's file list\n- `Escape` clears the filter first, then returns focus to the file list when the input is already empty\n\nThe filter state is pane-local and scoped to the current `connectionId + path`.\n\n- switching between `smart`, `commands`, and `filter` modes does not clear the current directory filter\n- navigating to a different directory clears the filter for the new scope\n- changing the pane's connection also clears the filter for the new scope\n- the status bar remains the persistent reminder that a filter is active even when the quick bar is in another mode\n\n## Current Browser-Level Shortcuts\n\nCurrent browser-level shortcuts include:\n\n- `Ctrl+K`: open smart navigation\n- `Ctrl+Alt+F`: focus current-directory filter mode for the active pane\n- `Ctrl+P`: show commands\n- `F1`: alternate binding for show commands\n- `Ctrl+,`: open settings\n- `?`: show keyboard shortcuts help\n- `Backspace`: go up one directory\n- `Ctrl+R`: refresh file list\n- `F2`: rename focused item\n- `Delete`: delete focused item\n- `F7`: create new directory\n- `Shift+F7`: create new file\n- `Ctrl+Enter`: open focused file in the companion app\n- `Ctrl+B`: toggle dual-pane view\n- `Ctrl+1`: focus left pane\n- `Ctrl+2`: focus right pane\n- `Tab`: switch active pane\n- `F5`: copy to the other pane\n- `F6`: move to the other pane\n\nWhen changing these, treat the behavior as product-level interaction design rather than local implementation detail.\n\n## Focus and Interaction Rules\n\nShortcut work often breaks focus behavior before it breaks functionality. Keep these rules intact:\n\n- opening the quick bar focuses its input immediately\n- selecting a navigation result returns focus to the relevant file list\n- selecting commands that switch quick-bar modes keeps focus inside the quick bar\n- `ArrowDown` from current-directory filter mode moves focus into the filtered file list\n- current-directory filter mode does not open a dropdown for local matches\n- `Escape` in filter mode clears the active filter before it hands focus back to the file list\n- commands that open dialogs or settings do not force focus back to the file list\n- pane-switching shortcuts do not fire while the quick-bar input is focused\n- shortcuts that should work during text entry must explicitly opt in with `allowInInput`\n- shortcuts should be disabled when dialog state or viewer state would make them unsafe\n\n## Context-Aware Shortcut Handling\n\nWhen one key needs different behavior depending on state, prefer one context-aware handler over overlapping registrations.\n\nFor example, `Escape` may close a search panel when that panel is open, but close the viewer when it is not.\n\nThat pattern is better than registering multiple conflicting `Escape` shortcuts because:\n\n- one shortcut definition stays authoritative\n- behavior remains explicit in the component state logic\n- conflicts are easier to reason about and test\n\n### Priority as an Escape Hatch\n\nIn rare cases, multiple handlers for one key are unavoidable. The system supports a `priority` field so higher-priority candidates are evaluated first.\n\nUse that sparingly. A context-aware handler is usually easier to understand and maintain than several competing registrations.\n\n## Adding New Shortcuts Safely\n\nWhen you add a shortcut, keep the workflow centralized.\n\n1. define the shortcut in `config/keyboardShortcuts.ts`\n2. bind it through `useKeyboardShortcuts` in the feature component\n3. reuse the same definition for tooltip or help-surface labels\n4. test both the runtime behavior and the visible affordance\n\nTypical sequence:\n\n```typescript\nexport const PDF_SHORTCUTS = {\n  PRINT: {\n    id: \"print\",\n    keys: \"p\",\n    description: \"Print\",\n    label: \"Ctrl+P\",\n    ctrl: true,\n  },\n} as const;\n```\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...PDF_SHORTCUTS.PRINT,\n      handler: handlePrint,\n    },\n  ],\n});\n```\n\n```typescript\ntitle={withShortcut(PDF_SHORTCUTS.PRINT)}\n```\n\nDo not add one-off tooltip strings or imperative event parsing when the shortcut belongs in the shared system.\n\n## Label Formatting Rules\n\nThe shortcut system also owns display formatting.\n\n- `ArrowRight` becomes `Right`\n- `ArrowLeft` becomes `Left`\n- `ArrowUp` becomes `Up`\n- `ArrowDown` becomes `Down`\n- `Escape` becomes `Esc`\n- space becomes `Space`\n- multiple equivalent keys are joined with ` / `\n- modifiers render as `Ctrl+`, `Shift+`, and `Alt+`\n\nThat formatting should come from the shared system, not from ad hoc component strings.\n\n## Common Failure Modes\n\n- shortcut keys and visible labels drift apart\n- a component registers imperative keyboard logic instead of using the shared hook\n- the browser command palette exposes actions that do not respect the current UI context\n- shortcuts fire while text input or dialog state should block them\n- quick-bar focus returns to the wrong pane in dual-pane workflows\n- multiple overlapping handlers compete for one key instead of using a context-aware handler\n\n## Validation Expectations\n\nWhen keyboard behavior changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change affects file-browser behavior, also test:\n\n- quick-bar navigation and command mode\n- pane switching in dual-pane and single-pane layouts\n- dialog safety for destructive shortcuts\n- viewer shortcut labels and matching runtime behavior\n\nFor new shortcut registrations, also verify:\n\n- the shared label matches the actual bound keys\n- `allowInInput` behavior matches the intended text-entry experience\n- priority and enabled-state logic do not create hidden overlaps\n\n## Where to Continue\n\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL sync, selection, and refresh behavior\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): viewer reuse, preview behavior, and file-type contracts\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): other shared frontend systems contributors should keep centralized\n", "1.0": "+++\ntitle = \"Keyboard Shortcuts and Command Model\"\n+++\n\nKeyboard behavior in Sambee is a shared frontend system, not a pile of local `keydown` handlers.\n\nThe product depends on contributors keeping shortcuts, command labels, viewer controls, and file-browser focus behavior aligned.\n\n## Core Pieces\n\nThese files define the keyboard and command model:\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/config/keyboardShortcuts.ts` | single source of truth for shortcut definitions and display labels |\n| `frontend/src/config/browserCommands.ts` | file-browser command registry for command-palette behavior |\n| `frontend/src/hooks/useKeyboardShortcuts.ts` | shared hook that binds shortcut definitions to runtime handlers |\n| `frontend/src/pages/FileBrowser.tsx` | registers browser-level shortcuts and routes command actions |\n| `frontend/src/components/Viewer/` | consumes shared shortcut definitions for viewer behavior and tooltip labels |\n| `frontend/src/components/Viewer/CodeMirrorFindReplacePopover.tsx` | shared compact find, match-option, and replacement controls for CodeMirror editors |\n\nThe system is intentionally split so shortcuts stay declarative while feature surfaces keep control of their own runtime behavior.\n\n## Why the Registry Exists\n\nBefore the centralized model, shortcut keys, tooltip labels, and component handlers drifted apart easily.\n\nThe current approach preserves these rules:\n\n- define shortcut keys and display intent once\n- reuse the same definition across viewers and file-browser surfaces\n- let components supply handlers without redefining labels and modifiers\n- keep file-browser actions discoverable even when users do not know the shortcut\n\n## Shortcut Definition Model\n\nShortcut definitions are grouped by scope, such as common viewer actions, PDF-specific actions, image-viewer actions, or browser actions.\n\nRepresentative structure:\n\n```typescript\nexport const COMMON_SHORTCUTS = {\n  CLOSE: {\n    id: \"close\",\n    keys: \"Escape\",\n    description: \"Close\",\n    label: \"Esc\",\n    allowInInput: true,\n  },\n  DOWNLOAD: {\n    id: \"download\",\n    keys: \"s\",\n    description: \"Download\",\n    label: \"Ctrl+S\",\n    ctrl: true,\n  },\n} as const;\n```\n\nCommon properties include:\n\n- `id`: stable identifier\n- `keys`: one key or multiple equivalent keys\n- `description`: human-readable intent\n- `label`: optional display label; if omitted, it can be generated from the config\n- `ctrl`, `shift`, `alt`: required modifiers\n- `allowInInput`: whether the shortcut still works while an input is focused\n- `priority`: ordering for overlapping shortcut candidates\n\n## Using the Shared Hook\n\nFeature components bind runtime behavior through `useKeyboardShortcuts` instead of duplicating event parsing logic.\n\nTypical usage:\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...COMMON_SHORTCUTS.CLOSE,\n      handler: onClose,\n    },\n    {\n      ...COMMON_SHORTCUTS.DOWNLOAD,\n      handler: handleDownload,\n    },\n    {\n      ...PDF_SHORTCUTS.SEARCH,\n      handler: handleOpenSearch,\n    },\n  ],\n});\n```\n\nThat split keeps the registry declarative and keeps feature logic in the feature component.\n\n## Labels and Tooltip Reuse\n\nViewer controls and similar UI surfaces should reuse the same shortcut definition instead of duplicating string formatting.\n\nThe shared formatter can turn a shortcut definition into a tooltip label such as `Download (Ctrl+S)`.\n\nThat matters because a changed shortcut should update viewer behavior and visible affordances together.\n\n## Browser Commands Versus Raw Shortcuts\n\nThe file browser uses both shortcut definitions and a command registry.\n\n- shortcut definitions remain centralized in `keyboardShortcuts.ts`\n- discoverable browser actions live in `browserCommands.ts`\n- command definitions point back to shortcut identifiers when a keyboard binding exists\n\nThis lets Sambee expose browser actions through the quick bar even when the user does not know the shortcut.\n\nEach browser command definition includes concepts such as:\n\n- a stable `id`\n- a user-facing `title`\n- a `category` for command grouping\n- linked shortcut identifiers\n- `isEnabled(context)` for context-aware availability\n- `run(context)` for execution\n- `selectionFocusTarget` for post-selection focus behavior\n\n## Quick-Bar Modes\n\nThe file browser quick bar is not just a text filter. It supports multiple modes with different intent.\n\n- `Ctrl+K`: open the smart navigation surface\n- `Ctrl+Alt+F`: open pane-local current-directory filter mode\n- `Ctrl+P`: open command mode directly\n- typing `\u003e` as the first character switches the quick bar into command mode\n\nSmart navigation and command mode are dropdown-backed provider modes. Filter mode deliberately is not.\n\n- `smart` mode uses the search provider composition that merges directory navigation and command escape-hatch behavior\n- `commands` mode uses the browser command registry directly\n- `filter` mode uses the same input shell, but as a controlled pane-local filter box with dropdown rendering disabled\n\nThe quick bar captures the pane that opened it. In dual-pane mode, the active quick-bar pane stays fixed even if the other pane becomes active before selection.\n\nThat capture rule matters especially for filter mode, because the filter text belongs to the pane state, not to the shared quick-bar component.\n\n### Current-Directory Filter Mode\n\n`Ctrl+Alt+F` is now a real current-directory filter workflow, not a smart-navigation alias.\n\nThe implemented contract is:\n\n- the active pane opens the quick bar in `filter` mode\n- the quick bar shows that pane's `currentDirectoryFilter` as a controlled value\n- typing filters the pane's visible file list immediately\n- no dropdown results are shown in this mode\n- `ArrowDown` hands focus from the input into the pane's file list\n- `Escape` clears the filter first, then returns focus to the file list when the input is already empty\n\nThe filter state is pane-local and scoped to the current `connectionId + path`.\n\n- switching between `smart`, `commands`, and `filter` modes does not clear the current directory filter\n- navigating to a different directory clears the filter for the new scope\n- changing the pane's connection also clears the filter for the new scope\n- the status bar remains the persistent reminder that a filter is active even when the quick bar is in another mode\n\n## Current Browser-Level Shortcuts\n\nCurrent browser-level shortcuts include:\n\n- `Ctrl+K`: open smart navigation\n- `Ctrl+Alt+F`: focus current-directory filter mode for the active pane\n- `Ctrl+P`: show commands\n- `Ctrl+,`: open settings\n- `?` or `F1`: show keyboard shortcuts help\n- `Backspace`: go up one directory\n- `Ctrl+R`: refresh file list\n- `F2`: rename focused item\n- `Delete`: delete focused item\n- `F7`: create new directory\n- `Shift+F7`: create new file\n- `Ctrl+Enter`: open focused file in the companion app\n- `Ctrl+B`: toggle dual-pane view\n- `Ctrl+1`: focus left pane\n- `Ctrl+2`: focus right pane\n- `Tab`: switch active pane\n- `F5`: copy to the other pane\n- `F6`: move to the other pane\n\nWhen changing these, treat the behavior as product-level interaction design rather than local implementation detail.\n\n## Focus and Interaction Rules\n\nShortcut work often breaks focus behavior before it breaks functionality. Keep these rules intact:\n\n- opening the quick bar focuses its input immediately\n- selecting a navigation result returns focus to the relevant file list\n- selecting commands that switch quick-bar modes keeps focus inside the quick bar\n- `ArrowDown` from current-directory filter mode moves focus into the filtered file list\n- current-directory filter mode does not open a dropdown for local matches\n- `Escape` in filter mode clears the active filter before it hands focus back to the file list\n- commands that open dialogs or settings do not force focus back to the file list\n- pane-switching shortcuts do not fire while the quick-bar input is focused\n- shortcuts that should work during text entry must explicitly opt in with `allowInInput`\n- shortcuts should be disabled when dialog state or viewer state would make them unsafe\n\n## Context-Aware Shortcut Handling\n\nWhen one key needs different behavior depending on state, prefer one context-aware handler over overlapping registrations.\n\nFor example, `Escape` may close a search panel when that panel is open, but close the viewer when it is not.\n\nThat pattern is better than registering multiple conflicting `Escape` shortcuts because:\n\n- one shortcut definition stays authoritative\n- behavior remains explicit in the component state logic\n- conflicts are easier to reason about and test\n\n### Priority as an Escape Hatch\n\nIn rare cases, multiple handlers for one key are unavoidable. The system supports a `priority` field so higher-priority candidates are evaluated first.\n\nUse that sparingly. A context-aware handler is usually easier to understand and maintain than several competing registrations.\n\n## Adding New Shortcuts Safely\n\nWhen you add a shortcut, keep the workflow centralized.\n\n1. define the shortcut in `config/keyboardShortcuts.ts`\n1. bind it through `useKeyboardShortcuts` in the feature component\n1. reuse the same definition for tooltip or help-surface labels\n1. test both the runtime behavior and the visible affordance\n\nTypical sequence:\n\n```typescript\nexport const PDF_SHORTCUTS = {\n  PRINT: {\n    id: \"print\",\n    keys: \"p\",\n    description: \"Print\",\n    label: \"Ctrl+P\",\n    ctrl: true,\n  },\n} as const;\n```\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...PDF_SHORTCUTS.PRINT,\n      handler: handlePrint,\n    },\n  ],\n});\n```\n\n```typescript\ntitle={withShortcut(PDF_SHORTCUTS.PRINT)}\n```\n\nDo not add one-off tooltip strings or imperative event parsing when the shortcut belongs in the shared system.\n\n## CodeMirror Find and Replace\n\nMarkdown and text editing keep find and replace in an editor-local fixed surface near the upper-right viewport edge, below the viewer toolbar, rather than in the shared viewer toolbar. `MarkdownViewer` and `TextViewer` own the surrounding viewer state and bind `Ctrl+H`, `Alt+C`, `Alt+W`, and `Alt+R` through `CODEMIRROR_EDITOR_SHORTCUTS`. The existing shared `F3` and `Shift+F3` registrations remain the navigation authority, including while a find or replace input has focus. `Enter` and `Ctrl+Alt+Enter` are also declared in that registry for replace-current and replace-all, but their `allowInInputWithin` scope limits them to the replacement field.\n\n`codeMirrorFindReplace.ts` owns the shared `SearchQuery` construction, validity-aware metrics, and auto-navigation logic. `MarkdownRichEditor` and `TextCodeEditor` map the controlled state to that API and use CodeMirror's native `replaceNext` and `replaceAll` commands. Keep replacement operations on those native commands so CodeMirror owns selection updates and undo transactions. Search metrics must check the query validity before creating a cursor because an invalid regular expression cannot produce one.\n\n`CodeMirrorFindReplacePopover` is intentionally non-modal so the editor remains visible and keyboard navigation remains continuous. Its Find and Replace inputs come first in DOM order to preserve the first two tab stops. The history affordance is supplied by the in-field `Search (\u21c5 for history)` and `Replace (\u21c5 for history)` placeholders; result count, match options, navigation, and close controls occupy the first row to the inputs' right. `codeMirrorFindReplaceHistory.ts` persists independent Find and Replace histories in local storage, safely tolerating unavailable or malformed storage and retaining only the ten newest unique non-empty values. Reuse dialog surface tokens for its paper, but do not use `ResponsiveFormDialog`: full-screen viewers retain their specialized focus and layout shell.\n\n## Label Formatting Rules\n\nThe shortcut system also owns display formatting.\n\n- `ArrowRight` becomes `Right`\n- `ArrowLeft` becomes `Left`\n- `ArrowUp` becomes `Up`\n- `ArrowDown` becomes `Down`\n- `Escape` becomes `Esc`\n- space becomes `Space`\n- multiple equivalent keys are joined with ` / `\n- modifiers render as `Ctrl+`, `Shift+`, and `Alt+`\n\nThat formatting should come from the shared system, not from ad hoc component strings.\n\n## Common Failure Modes\n\n- shortcut keys and visible labels drift apart\n- a component registers imperative keyboard logic instead of using the shared hook\n- the browser command palette exposes actions that do not respect the current UI context\n- shortcuts fire while text input or dialog state should block them\n- quick-bar focus returns to the wrong pane in dual-pane workflows\n- multiple overlapping handlers compete for one key instead of using a context-aware handler\n\n## Validation Expectations\n\nWhen keyboard behavior changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change affects file-browser behavior, also test:\n\n- quick-bar navigation and command mode\n- pane switching in dual-pane and single-pane layouts\n- dialog safety for destructive shortcuts\n- viewer shortcut labels and matching runtime behavior\n\nFor new shortcut registrations, also verify:\n\n- the shared label matches the actual bound keys\n- `allowInInput` behavior matches the intended text-entry experience\n- priority and enabled-state logic do not create hidden overlaps\n\n## Where to Continue\n\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL sync, selection, and refresh behavior\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): viewer reuse, preview behavior, and file-type contracts\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): other shared frontend systems contributors should keep centralized\n", "2.0": "+++\ntitle = \"Keyboard Shortcuts and Command Model\"\n+++\n\nKeyboard behavior in Sambee is a shared frontend system, not a pile of local `keydown` handlers.\n\nThe product depends on contributors keeping shortcuts, command labels, viewer controls, and file-browser focus behavior aligned.\n\n## Core Pieces\n\nThese files define the keyboard and command model:\n\n| Path | Responsibility |\n|---|---|\n| `frontend/src/config/keyboardShortcuts.ts` | single source of truth for shortcut definitions and display labels |\n| `frontend/src/config/browserCommands.ts` | file-browser command registry for command-palette behavior |\n| `frontend/src/hooks/useKeyboardShortcuts.ts` | shared hook that binds shortcut definitions to runtime handlers |\n| `frontend/src/pages/FileBrowser.tsx` | registers browser-level shortcuts and routes command actions |\n| `frontend/src/components/Viewer/` | consumes shared shortcut definitions for viewer behavior and tooltip labels |\n| `frontend/src/components/Viewer/CodeMirrorFindReplacePopover.tsx` | shared compact find, match-option, and replacement controls for CodeMirror editors |\n\nThe system is intentionally split so shortcuts stay declarative while feature surfaces keep control of their own runtime behavior.\n\n## Why the Registry Exists\n\nBefore the centralized model, shortcut keys, tooltip labels, and component handlers drifted apart easily.\n\nThe current approach preserves these rules:\n\n- define shortcut keys and display intent once\n- reuse the same definition across viewers and file-browser surfaces\n- let components supply handlers without redefining labels and modifiers\n- keep file-browser actions discoverable even when users do not know the shortcut\n\n## Shortcut Definition Model\n\nShortcut definitions are grouped by scope, such as common viewer actions, PDF-specific actions, image-viewer actions, or browser actions.\n\nRepresentative structure:\n\n```typescript\nexport const COMMON_SHORTCUTS = {\n  CLOSE: {\n    id: \"close\",\n    keys: \"Escape\",\n    description: \"Close\",\n    label: \"Esc\",\n    allowInInput: true,\n  },\n  DOWNLOAD: {\n    id: \"download\",\n    keys: \"s\",\n    description: \"Download\",\n    label: \"Ctrl+S\",\n    ctrl: true,\n  },\n} as const;\n```\n\nCommon properties include:\n\n- `id`: stable identifier\n- `keys`: one key or multiple equivalent keys\n- `description`: human-readable intent\n- `label`: optional display label; if omitted, it can be generated from the config\n- `ctrl`, `shift`, `alt`: required modifiers\n- `allowInInput`: whether the shortcut still works while an input is focused\n- `priority`: ordering for overlapping shortcut candidates\n\n## Using the Shared Hook\n\nFeature components bind runtime behavior through `useKeyboardShortcuts` instead of duplicating event parsing logic.\n\nTypical usage:\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...COMMON_SHORTCUTS.CLOSE,\n      handler: onClose,\n    },\n    {\n      ...COMMON_SHORTCUTS.DOWNLOAD,\n      handler: handleDownload,\n    },\n    {\n      ...PDF_SHORTCUTS.SEARCH,\n      handler: handleOpenSearch,\n    },\n  ],\n});\n```\n\nThat split keeps the registry declarative and keeps feature logic in the feature component.\n\n## Labels and Tooltip Reuse\n\nViewer controls and similar UI surfaces should reuse the same shortcut definition instead of duplicating string formatting.\n\nThe shared formatter can turn a shortcut definition into a tooltip label such as `Download (Ctrl+S)`.\n\nThat matters because a changed shortcut should update viewer behavior and visible affordances together.\n\n## Browser Commands Versus Raw Shortcuts\n\nThe file browser uses both shortcut definitions and a command registry.\n\n- shortcut definitions remain centralized in `keyboardShortcuts.ts`\n- discoverable browser actions live in `browserCommands.ts`\n- command definitions point back to shortcut identifiers when a keyboard binding exists\n\nThis lets Sambee expose browser actions through the quick bar even when the user does not know the shortcut.\n\nEach browser command definition includes concepts such as:\n\n- a stable `id`\n- a user-facing `title`\n- a `category` for command grouping\n- linked shortcut identifiers\n- `isEnabled(context)` for context-aware availability\n- `run(context)` for execution\n- `selectionFocusTarget` for post-selection focus behavior\n\n## Quick-Bar Modes\n\nThe file browser quick bar is not just a text filter. It supports multiple modes with different intent.\n\n- `Ctrl+K`: open the smart navigation surface\n- `Ctrl+Alt+F`: open pane-local current-directory filter mode\n- `Ctrl+P`: open command mode directly\n- typing `\u003e` as the first character switches the quick bar into command mode\n\nSmart navigation and command mode are dropdown-backed provider modes. Filter mode deliberately is not.\n\n- `smart` mode uses the search provider composition that merges directory navigation and command escape-hatch behavior\n- `commands` mode uses the browser command registry directly\n- `filter` mode uses the same input shell, but as a controlled pane-local filter box with dropdown rendering disabled\n\nThe quick bar captures the pane that opened it. In dual-pane mode, the active quick-bar pane stays fixed even if the other pane becomes active before selection.\n\nThat capture rule matters especially for filter mode, because the filter text belongs to the pane state, not to the shared quick-bar component.\n\n### Current-Directory Filter Mode\n\n`Ctrl+Alt+F` is now a real current-directory filter workflow, not a smart-navigation alias.\n\nThe implemented contract is:\n\n- the active pane opens the quick bar in `filter` mode\n- the quick bar shows that pane's `currentDirectoryFilter` as a controlled value\n- typing filters the pane's visible file list immediately\n- no dropdown results are shown in this mode\n- `ArrowDown` hands focus from the input into the pane's file list\n- `Escape` clears the filter first, then returns focus to the file list when the input is already empty\n\nThe filter state is pane-local and scoped to the current `connectionId + path`.\n\n- switching between `smart`, `commands`, and `filter` modes does not clear the current directory filter\n- navigating to a different directory clears the filter for the new scope\n- changing the pane's connection also clears the filter for the new scope\n- the status bar remains the persistent reminder that a filter is active even when the quick bar is in another mode\n\n## Current Browser-Level Shortcuts\n\nCurrent browser-level shortcuts include:\n\n- `Ctrl+K`: open smart navigation\n- `Ctrl+Alt+F`: focus current-directory filter mode for the active pane\n- `Ctrl+P`: show commands\n- `Ctrl+,`: open settings\n- `?` or `F1`: show keyboard shortcuts help\n- `Backspace`: go up one directory\n- `Ctrl+R`: refresh file list\n- `F2`: rename focused item\n- `Delete`: delete focused item\n- `F7`: create new directory\n- `Shift+F7`: create new file\n- `Ctrl+Enter`: open focused file in the companion app\n- `Ctrl+B`: toggle dual-pane view\n- `Ctrl+1`: focus left pane\n- `Ctrl+2`: focus right pane\n- `Tab`: switch active pane\n- `F5`: copy to the other pane\n- `F6`: move to the other pane\n\nWhen changing these, treat the behavior as product-level interaction design rather than local implementation detail.\n\n## Focus and Interaction Rules\n\nShortcut work often breaks focus behavior before it breaks functionality. Keep these rules intact:\n\n- opening the quick bar focuses its input immediately\n- selecting a navigation result returns focus to the relevant file list\n- selecting commands that switch quick-bar modes keeps focus inside the quick bar\n- `ArrowDown` from current-directory filter mode moves focus into the filtered file list\n- current-directory filter mode does not open a dropdown for local matches\n- `Escape` in filter mode clears the active filter before it hands focus back to the file list\n- commands that open dialogs or settings do not force focus back to the file list\n- pane-switching shortcuts do not fire while the quick-bar input is focused\n- shortcuts that should work during text entry must explicitly opt in with `allowInInput`\n- shortcuts should be disabled when dialog state or viewer state would make them unsafe\n\n## Context-Aware Shortcut Handling\n\nWhen one key needs different behavior depending on state, prefer one context-aware handler over overlapping registrations.\n\nFor example, `Escape` may close a search panel when that panel is open, but close the viewer when it is not.\n\nThat pattern is better than registering multiple conflicting `Escape` shortcuts because:\n\n- one shortcut definition stays authoritative\n- behavior remains explicit in the component state logic\n- conflicts are easier to reason about and test\n\n### Priority as an Escape Hatch\n\nIn rare cases, multiple handlers for one key are unavoidable. The system supports a `priority` field so higher-priority candidates are evaluated first.\n\nUse that sparingly. A context-aware handler is usually easier to understand and maintain than several competing registrations.\n\n## Adding New Shortcuts Safely\n\nWhen you add a shortcut, keep the workflow centralized.\n\n1. define the shortcut in `config/keyboardShortcuts.ts`\n1. bind it through `useKeyboardShortcuts` in the feature component\n1. reuse the same definition for tooltip or help-surface labels\n1. test both the runtime behavior and the visible affordance\n\nTypical sequence:\n\n```typescript\nexport const PDF_SHORTCUTS = {\n  PRINT: {\n    id: \"print\",\n    keys: \"p\",\n    description: \"Print\",\n    label: \"Ctrl+P\",\n    ctrl: true,\n  },\n} as const;\n```\n\n```typescript\nuseKeyboardShortcuts({\n  shortcuts: [\n    {\n      ...PDF_SHORTCUTS.PRINT,\n      handler: handlePrint,\n    },\n  ],\n});\n```\n\n```typescript\ntitle={withShortcut(PDF_SHORTCUTS.PRINT)}\n```\n\nDo not add one-off tooltip strings or imperative event parsing when the shortcut belongs in the shared system.\n\n## CodeMirror Find and Replace\n\nMarkdown and text editing keep find and replace in an editor-local fixed surface near the upper-right viewport edge, below the viewer toolbar, rather than in the shared viewer toolbar. `MarkdownViewer` and `TextViewer` own the surrounding viewer state and bind `Ctrl+H`, `Alt+C`, `Alt+W`, and `Alt+R` through `CODEMIRROR_EDITOR_SHORTCUTS`. The existing shared `F3` and `Shift+F3` registrations remain the navigation authority, including while a find or replace input has focus. `Enter` and `Ctrl+Alt+Enter` are also declared in that registry for replace-current and replace-all, but their `allowInInputWithin` scope limits them to the replacement field.\n\n`codeMirrorFindReplace.ts` owns the shared `SearchQuery` construction, validity-aware metrics, and auto-navigation logic. `MarkdownRichEditor` and `TextCodeEditor` map the controlled state to that API and use CodeMirror's native `replaceNext` and `replaceAll` commands. Keep replacement operations on those native commands so CodeMirror owns selection updates and undo transactions. Search metrics must check the query validity before creating a cursor because an invalid regular expression cannot produce one.\n\n`CodeMirrorFindReplacePopover` is intentionally non-modal so the editor remains visible and keyboard navigation remains continuous. Its Find and Replace inputs come first in DOM order to preserve the first two tab stops. The history affordance is supplied by the in-field `Search (\u21c5 for history)` and `Replace (\u21c5 for history)` placeholders; result count, match options, navigation, and close controls occupy the first row to the inputs' right. `codeMirrorFindReplaceHistory.ts` persists independent Find and Replace histories in local storage, safely tolerating unavailable or malformed storage and retaining only the ten newest unique non-empty values. Reuse dialog surface tokens for its paper, but do not use `ResponsiveFormDialog`: full-screen viewers retain their specialized focus and layout shell.\n\n## Label Formatting Rules\n\nThe shortcut system also owns display formatting.\n\n- `ArrowRight` becomes `Right`\n- `ArrowLeft` becomes `Left`\n- `ArrowUp` becomes `Up`\n- `ArrowDown` becomes `Down`\n- `Escape` becomes `Esc`\n- space becomes `Space`\n- multiple equivalent keys are joined with ` / `\n- modifiers render as `Ctrl+`, `Shift+`, and `Alt+`\n\nThat formatting should come from the shared system, not from ad hoc component strings.\n\n## Common Failure Modes\n\n- shortcut keys and visible labels drift apart\n- a component registers imperative keyboard logic instead of using the shared hook\n- the browser command palette exposes actions that do not respect the current UI context\n- shortcuts fire while text input or dialog state should block them\n- quick-bar focus returns to the wrong pane in dual-pane workflows\n- multiple overlapping handlers compete for one key instead of using a context-aware handler\n\n## Validation Expectations\n\nWhen keyboard behavior changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nIf the change affects file-browser behavior, also test:\n\n- quick-bar navigation and command mode\n- pane switching in dual-pane and single-pane layouts\n- dialog safety for destructive shortcuts\n- viewer shortcut labels and matching runtime behavior\n\nFor new shortcut registrations, also verify:\n\n- the shared label matches the actual bound keys\n- `allowInInput` behavior matches the intended text-entry experience\n- priority and enabled-state logic do not create hidden overlaps\n\n## Where to Continue\n\n- [File Browser and Navigation Model](../file-browser-and-navigation-model/): pane state, URL sync, selection, and refresh behavior\n- [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/): viewer reuse, preview behavior, and file-type contracts\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): other shared frontend systems contributors should keep centralized\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/frontend-architecture/viewer-architecture-and-preview-contracts", "parent_id": "section:developer-guide/frontend-architecture", "depth": 2, "kind": "page", "label": "viewer-architecture-and-preview-contracts", "title": "Viewer Architecture And Preview Contracts", "path": "developer-guide/frontend-architecture/viewer-architecture-and-preview-contracts", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "branched", "source_version": "0.7", "diff_added": 165, "diff_removed": 4}}, "content_versions": {"0.7": "+++\ntitle = \"Viewer Architecture and Preview Contracts\"\n+++\n\nPreview behavior in Sambee is a cross-boundary contract, not just a frontend component choice.\n\n## The Core Contract\n\nThe browser app decides how to render a file based on metadata and file-type information, but that depends on server-side classification staying aligned.\n\nThree rules matter most:\n\n- the backend and frontend file-type registries must describe the same extensions and MIME types\n- the backend decides whether an image format needs server-side conversion for browser compatibility\n- the frontend chooses the right viewer component and file icon based on the effective file type and MIME information it receives\n\n## Where the Main Decisions Live\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | backend source of truth for extensions, MIME types, categories, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | frontend source of truth for extensions, MIME types, categories, viewer components, icons, and colors |\n| `frontend/src/components/Viewer/` | viewer components and shared viewer UI |\n| `backend/app/services/image_converter.py` | server-side conversion for non-browser-native image formats |\n\n## Viewer Selection Model\n\nAt a high level, the preview pipeline works like this:\n\n1. the backend determines file category and MIME behavior\n2. the backend decides whether the file can stream as-is or needs image conversion\n3. the frontend maps the file type to the appropriate viewer component\n4. the shared viewer controls keep the toolbar and common behavior consistent across viewers\n\nThat is why a file-type change almost always touches both backend and frontend code.\n\n## Browser-Native Versus Server-Converted Images\n\nSambee supports both browser-native formats and formats that need server-side conversion.\n\n- browser-native formats can be sent to the viewer directly\n- non-browser-native image formats are converted on the server before the browser renders them\n- special cases such as transparency preservation can change the output format choice\n\nIf you change conversion rules, you are changing a product contract, not just an implementation detail.\n\n### Server-Side Conversion Contract\n\nThe conversion path is owned by `backend/app/services/image_converter.py` and is exercised through the viewer API.\n\nThe backend conversion service is responsible for:\n\n- deciding whether an image needs processing\n- converting unsupported or impractical browser formats into a viewer-safe output format\n- preserving transparency where the output contract requires it\n- applying optional downscaling so one preview request cannot explode memory usage casually\n- returning enough metadata for the viewer endpoint to send the correct MIME type back to the browser\n\nRepresentative service responsibilities include:\n\n- `needs_processing(filename)`\n- `convert_image_for_viewer(...)`\n- `is_image_file(filename)`\n- `get_image_info(...)`\n\nThe viewer endpoint then follows this rule:\n\n- if the image can stream safely as-is, return a streaming response\n- if it requires conversion, read it, convert it, and return the converted bytes with the converted MIME type\n\nThat means preview behavior for formats such as TIFF, HEIC, BMP, ICO, and similar formats depends on backend conversion policy, not just on frontend MIME recognition.\n\n### Local-Drive Preview Policy\n\nThe Companion serves local-drive files and archive members as raw bytes. It does not copy local content to the backend for processing and does not bundle the backend image or PDF processing stack.\n\n- Browser-native images, text files, and original PDFs can preview from their raw local bytes.\n- Image formats that require server-side conversion, such as TIFF, HEIC, PSD, JPEG XL, and scientific image formats, show an explicit preview-unavailable state for local drives.\n- Image resizing and PDF compatibility normalization are unavailable for local drives.\n- Downloading and opening the original file locally remain available when a local preview is unavailable.\n\nThe frontend resolves these capabilities before making a local viewer request. Local archive-member requests use the Companion's strict raw-stream contract, while SMB archive-member requests retain the full conversion and PDF-normalization request parameters.\n\n### Output Format Rules\n\nThe backend does not always convert everything to the same output type.\n\n- JPEG is the common output for opaque images\n- PNG remains important when transparency must be preserved\n- ICO-like transparency handling is therefore different from ordinary opaque-photo conversion\n- alpha-bearing formats converted to JPEG need explicit compositing behavior rather than silent accidental loss\n\nIf you change those rules, check both visual correctness and user-facing assumptions such as download behavior and gallery continuity.\n\n### Current Format-Specific Preview Semantics\n\nSeveral converted-image families have product-specific preview semantics that contributors should preserve unless the product intentionally changes.\n\n- multi-page TIFF currently previews the first page rather than exposing a document-style page stack\n- PSD and PSB preview the flattened composite instead of surfacing layer-edit semantics through the browser viewer\n- EPS and AI are rasterized through the preprocessing path at high quality, currently using the 300 DPI rendering baseline\n- HDR-oriented formats such as EXR and Radiance HDR are tone-mapped into ordinary browser-display output\n- whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF preview as an overview or first practical pyramid level rather than as a full pathology viewer\n- FITS and similar scientific-image formats apply visibility scaling so low-level pixel values become inspectable in a normal browser image surface\n\nThese are not accidental implementation details. They define what users should expect from preview and therefore belong to the product contract.\n\n### Resizing and Resource Limits\n\nServer-side conversion can consume significant memory because the file must be read, decoded, and re-encoded.\n\nThe current contract therefore includes:\n\n- configurable JPEG-quality behavior\n- maximum-dimension downscaling to avoid unbounded preview size\n- backend-side protection against excessive memory usage from large source images\n\nContributors should treat those limits as operational safety controls, not as arbitrary defaults.\n\n### Dependency and Environment Expectations\n\nThe conversion path depends on reviewed Python and system-image libraries.\n\nThat includes the normal image stack plus HEIC/HEIF support through the reviewed dependency chain and corresponding system libraries in the container or runtime image.\n\nWhen conversion support seems to disappear unexpectedly, check:\n\n- the backend Python dependency set\n- the container or host system-image libraries\n- whether the format-specific support was actually installed in the current environment\n\n### Preprocessor Registry for Exotic Formats\n\nSome formats need a preprocessing step before the normal conversion path can handle them at all.\n\nThat registry lives in:\n\n- `backend/app/services/preprocessor.py`\n\nIt is consumed by:\n\n- `backend/app/services/image_converter.py`\n\nThe preprocessor layer exists for formats that libvips should not or cannot decode directly for Sambee's preview contract.\n\nCurrent registered formats route through the ImageMagick-backed preprocessor:\n\n- `.psd`\n- `.psb`\n- `.eps`\n- `.ai`\n\nThe registry is the single source of truth for which extensions require preprocessing before the final viewer-safe conversion step.\n\nFor the backend service architecture behind that path, continue to [Image Preprocessing and Conversion Pipeline](../../backend-architecture/image-preprocessing-and-conversion-pipeline/).\n\nRepresentative registry operations include:\n\n- `PreprocessorRegistry.requires_preprocessing(extension)`\n- `PreprocessorRegistry.get_preprocessor_for_format(extension)`\n- `PreprocessorRegistry.get_supported_formats()`\n- `PreprocessorRegistry.register_format(extension, preprocessor_class)`\n\n### Preprocessor Design Rules\n\nThe preprocessor layer has its own constraints:\n\n- one registry entry per preprocessable extension\n- direct in-memory conversion to the final browser-ready format rather than chained intermediate formats\n- no shell-mediated fallback chain logic in the registry itself\n- input validation and timeout enforcement happen in the preprocessor layer\n- failures should surface as explicit preprocessing or conversion errors rather than silent format drift\n\nThe main abstraction is `PreprocessorInterface`, with `ImageMagickPreprocessor` as the current built-in implementation.\n\n### Adding a New Preprocessed Format\n\nIf a new format cannot be handled by the normal conversion stack directly:\n\n1. implement a `PreprocessorInterface` subclass if the existing preprocessor is not appropriate\n2. register the extension in `PreprocessorRegistry`\n3. add or update file-type metadata if the format becomes user-visible in preview flows\n4. add tests for format recognition, tool availability, validation, and successful conversion\n\nDo not treat preprocessable formats as ordinary file-type additions. They change the backend conversion pipeline itself.\n\n### Error Surface Contributors Must Preserve\n\nConversion failures are user-visible API behavior, not internal-only exceptions.\n\nTypical outcomes include:\n\n- not implemented when the current environment lacks support for a format family\n- unprocessable-content style failures when the file is corrupt or cannot be decoded\n- ordinary backend failures when an unexpected exception escapes the conversion path\n\nThat means error wording, status behavior, and frontend fallback behavior should be reviewed together.\n\n## Shared Viewer UI\n\nThe main viewer toolbar is intentionally centralized in `frontend/src/components/Viewer/ViewerControls.tsx`.\n\nThis is no longer just an image-and-PDF convenience component. It is the canonical control surface for the current full-screen image, PDF, and Markdown viewers.\n\n- shared toolbar layout, styling, keyboard-tooltip behavior, and responsive behavior live in `ViewerControls`\n- each viewer turns features on through configuration and passes only the state objects it needs\n- future viewers should reuse that control shell where possible instead of creating another top-level toolbar implementation\n\n### Control-Surface Model\n\n`ViewerControls` uses a feature-flag configuration plus typed state objects.\n\nThe configuration currently enables these capability groups:\n\n- `navigation` for gallery-style previous and next navigation\n- `pageNavigation` for PDF page input and page stepping\n- `zoom` for viewer-managed zoom actions\n- `rotation` for image and PDF rotation actions\n- `search` for the shared search row and match navigation affordances\n- `download` for explicit download actions\n- `share` for mobile-first share actions\n\nThe component then accepts matching state surfaces:\n\n- `NavigationState` for item index, total items, and next or previous handlers\n- `PageNavigationState` for current page, total pages, and page-change handling\n- `ZoomState` for zoom-in and zoom-out handlers\n- `RotationState` for rotate-left and rotate-right handlers\n- `SearchState` for search text, match counts, search-panel state, open or close callbacks, and viewer-specific search navigation\n\nThat split matters because `ViewerControls` owns the common UI, but it does not own viewer logic. It renders controls and delegates behavior back to the viewer that actually knows how to navigate pages, zoom, rotate, or search.\n\n### Current Consumers\n\nThe current shared-toolbar consumers are:\n\n- `ImageViewer`, which enables gallery navigation, zoom, rotation, download, and optional mobile share\n- `PDFViewer`, which enables page navigation, zoom, rotation, search, download, and optional mobile share\n- `MarkdownViewer`, which reuses the same shell for download, optional mobile share, shared search UI, and viewer-specific action buttons such as editing flows\n\n`ViewerControls` also supports generic toolbar actions through the `actions` prop, which can render either text buttons or icon buttons. That is what allows Markdown-specific actions to live inside the same shared toolbar instead of forcing a second toolbar implementation.\n\n### Search UI Versus Search Engine\n\nThe search row is shared, but the search backend is viewer-specific.\n\n- `PDFViewer` wires the search controls to PDF text extraction, page-aware match tracking, and PDF-specific next or previous navigation\n- rendered Markdown and other rendered text views can route search through the DOM text-search utility in `frontend/src/utils/domTextSearch.ts`\n- Markdown edit mode does not reuse the rendered-view DOM search implementation; it bridges the same outer toolbar UI into the editor-specific search state and commands instead\n\nThat separation is an important contract: contributors should reuse the shared search UI when possible, but should not assume every viewer can use the same search implementation under the hood.\n\n### Responsive and Accessibility Rules\n\nThe centralized toolbar also encodes product behavior that should stay consistent across viewers.\n\n- filename display, optional filename adornments, and close behavior are shared\n- mobile layout uses safe-area-aware spacing and smaller controls\n- gallery arrows and desktop zoom controls are intentionally reduced on mobile, where gesture-based interaction is preferred\n- share is exposed as a mobile-first affordance, with optional early-intent warming through `onShareIntent`\n- buttons use explicit `aria-label` values and shortcut-oriented `title` text so the control surface remains navigable and self-describing\n- the shared search row manages focus when it opens and preserves consistent close behavior for toggle and Escape-driven exits\n\n### Legacy Components and Contributor Guidance\n\nLegacy `ImageControls.tsx` and `PDFControls.tsx` files still exist in the frontend tree, but `ViewerControls` is the current architectural direction and the shared component used by the active image, PDF, and Markdown viewers.\n\nIf you add another viewer or extend an existing one:\n\n- prefer extending `ViewerControlsConfig`, the relevant state interfaces, or the generic `actions` surface\n- keep viewer-specific logic in the viewer component rather than teaching `ViewerControls` about file-format internals\n- preserve shared mobile, accessibility, and search-panel behavior unless the product intentionally changes that contract\n- add or update focused tests in `frontend/src/components/Viewer/__tests__/ViewerControls.test.tsx` when the shared toolbar contract changes\n\n## Adding a New File Type Safely\n\nFile-type support is registry-driven. The safest way to add a new type is to treat backend and frontend changes as one contract update.\n\n### Main Files to Change\n\n| Path | Why it changes |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | declare extensions, MIME types, category, description, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | declare extensions, MIME types, category, viewer component, icon, color, and description |\n| `frontend/src/components/Viewer/` | add or reuse a viewer component when the type needs a dedicated preview surface |\n\nIf a file type is user-visible, update the published support docs that describe what Sambee can preview.\n\n### Quick Start for a New Image Format\n\nFor an image format such as JPEG XL, the minimum workflow is:\n\n1. add a `FileTypeDefinition` entry to the backend registry\n2. add the matching entry to the frontend registry\n3. decide whether the image is browser-native or requires server-side conversion\n4. keep extensions and MIME types identical across both registries\n5. run the viewer and backend validation checks\n\nBackend example:\n\n```python\nFileTypeDefinition(\n\t\textensions=(\".jxl\",),\n\t\tmime_types=(\"image/jxl\",),\n\t\tcategory=FileCategory.IMAGE,\n\t\trequires_conversion=True,\n\t\tdescription=\"JPEG XL Image\",\n)\n```\n\nFrontend example:\n\n```typescript\n{\n\textensions: [\".jxl\"],\n\tmimeTypes: [\"image/jxl\"],\n\tcategory: \"image\",\n\tviewerComponent: () =\u003e import(\"../components/Viewer/ImageViewer\"),\n\ticon: \"image\",\n\tcolor: \"#a855f7\",\n\tdescription: \"JPEG XL Image\",\n}\n```\n\nThat registry update is what drives MIME matching, icon treatment, viewer routing, and image-gallery inclusion.\n\n### Backend Registry Rules\n\nBackend file-type definitions must stay explicit and type-safe.\n\n- `extensions` are tuples with a leading dot, such as `(\".jpg\", \".jpeg\")`\n- `mime_types` are tuples of standard MIME strings\n- `category` uses `FileCategory` values such as `IMAGE`, `DOCUMENT`, `TEXT`, `VIDEO`, `AUDIO`, `ARCHIVE`, `CODE`, `SPREADSHEET`, or `OTHER`\n- `requires_conversion` matters for image formats that cannot be rendered directly by the browser\n- `description` should be the human-readable label contributors and users would expect\n\nHow to decide `requires_conversion`:\n\n- set it to `False` for browser-native formats such as PNG, JPEG, GIF, WebP, SVG, and AVIF\n- set it to `True` for formats with limited browser support or formats that are not practical to render directly, such as TIFF, HEIC, BMP, JPEG 2000, or JPEG XL when browser support is not sufficient for the product baseline\n\n### Frontend Registry Rules\n\nFrontend file-type definitions control how the browser app presents the file.\n\n- keep `extensions` and `mimeTypes` aligned with the backend registry\n- set `viewerComponent` to the shared viewer that should render the type\n- choose an icon that matches the product language for that file category\n- choose a color that distinguishes the format without inventing a new palette on every addition\n\nFor image formats, reusing `ImageViewer` is usually enough. For non-image formats, you may need a dedicated viewer such as `PdfViewer`, `VideoViewer`, `AudioViewer`, or `TextViewer`.\n\n### Non-Image File Types\n\nThe overall process is the same for documents, video, audio, text, archives, and code files.\n\n1. add the backend registry entry\n2. add the frontend registry entry\n3. create or reuse the viewer component when preview support exists\n4. verify the file icon, viewer routing, and download behavior\n\nFor non-image files, `requires_conversion` is usually `False`. The main design question is whether the product has a viewer component for that category or should fall back to download-only behavior.\n\n### Integration Checklist\n\nUse this checklist before you consider the file type integrated:\n\n- backend registry entry added\n- frontend registry entry added\n- extensions and MIME types match exactly across both registries\n- browser-native versus converted-image behavior decided intentionally\n- viewer component chosen or added\n- icon and color treatment chosen\n- user-visible support docs updated if the file type changes what Sambee can preview\n\n### Testing Checklist\n\nAfter the registry change, verify:\n\n- icon display in the file browser\n- file opening in the expected viewer\n- shared toolbar behavior if the preview uses `ViewerControls`\n- conversion output if the format is server-converted\n- gallery inclusion for image formats\n- MIME type behavior across extension variants such as upper-case filenames\n- download behavior with the correct MIME type\n- mobile and tablet behavior when the preview is expected to work there\n\nFor server-converted formats, also verify:\n\n- the backend returns the converted MIME type you expect\n- transparency-sensitive formats still render correctly\n- resizing or quality settings do not degrade the preview contract unexpectedly\n- environment-specific format support failures surface in a controlled way\n\nFor preprocessable formats, also verify:\n\n- the registry recognizes the extension regardless of case and leading-dot differences\n- the expected preprocessor is selected for that format\n- missing external-tool support fails cleanly\n- validation and timeout rules behave as intended under bad inputs and slow conversions\n\n### Architecture Notes\n\nThese helper functions are the practical integration points contributors usually touch:\n\n- backend: `get_mime_type`, `needs_processing`, `is_image_file`, `get_file_type_by_extension`, `get_file_type_by_mime`\n- frontend: `getViewerComponent`, `isImageFile`, `getFileIcon`, `getFileTypeByExtension`, `getFileTypeByMime`\n\nAt runtime, the flow is:\n\n1. the backend lists files and assigns MIME information\n2. the frontend receives `FileInfo` data with that MIME information\n3. the frontend chooses icon treatment from filename and type rules\n4. the frontend selects the viewer from MIME and file-type data\n5. the backend routes convertible images through the image-conversion pipeline when needed\n\nThe frontend side still has work to do even when the backend owns the conversion:\n\n- viewer MIME recognition must include the input formats the backend classifies as previewable\n- file-type icon and color treatment must still reflect the original file type rather than the converted transport format\n- browser-side fallback MIME logic must not drift from the backend contract in ways that hide conversion bugs\n\n### Operational Characteristics\n\nServer-side conversion changes the runtime profile of preview requests.\n\n- large images can produce short CPU spikes during decode and encode\n- memory usage can rise well above compressed input size while the image is fully decoded\n- SMB-backed reads add their own latency before conversion even starts\n\nThat is why preview regressions for large HEIC or TIFF files often need both backend and user-facing verification.\n\n### Future Extension Points\n\nThe current conversion path leaves room for later enhancements such as:\n\n- caching converted preview outputs\n- queueing especially large conversions\n- dedicated thumbnail generation\n- richer multi-page image handling\n- conversion metrics for operational monitoring\n\nThose are extension points, not assumptions the current product already guarantees.\n\nThe highest-risk mistake is still registry drift. If the backend and frontend disagree about extensions or MIME types, preview behavior becomes unreliable in ways that are easy to miss until users hit them.\n\n## Common Failure Modes\n\n- backend and frontend MIME types do not match\n- a format is marked browser-native when it really needs conversion\n- a viewer component is not registered even though the type is recognized\n- a conversion change improves one format but breaks gallery behavior, download semantics, or mobile viewing\n\n## Validation Expectations\n\nWhen you change viewer or file-type behavior, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd backend \u0026\u0026 pytest -v\n```\n\nIf the change is image-conversion-specific, include the relevant backend tests around image conversion and preview behavior.\n", "0.8": "+++\ntitle = \"Viewer Architecture and Preview Contracts\"\n+++\n\nPreview behavior in Sambee is a cross-boundary contract, not just a frontend component choice.\n\n## The Core Contract\n\nThe browser app decides how to render a file based on metadata and file-type information, but that depends on server-side classification staying aligned.\n\nThree rules matter most:\n\n- the backend and frontend file-type registries must describe the same extensions and MIME types\n- the backend decides whether an image format needs server-side conversion for browser compatibility\n- the frontend chooses the right viewer component and file icon based on the effective file type and MIME information it receives\n\n## Where the Main Decisions Live\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | backend source of truth for extensions, MIME types, categories, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | frontend source of truth for extensions, MIME types, categories, viewer components, icons, and colors |\n| `frontend/src/components/Viewer/` | viewer components and shared viewer UI |\n| `backend/app/services/image_converter.py` | server-side conversion for non-browser-native image formats |\n\n## Viewer Selection Model\n\nAt a high level, the preview pipeline works like this:\n\n1. the backend determines file category and MIME behavior\n2. the backend decides whether the file can stream as-is or needs image conversion\n3. the frontend maps the file type to the appropriate viewer component\n4. the shared viewer controls keep the toolbar and common behavior consistent across viewers\n\nThat is why a file-type change almost always touches both backend and frontend code.\n\n## Browser-Native Versus Server-Converted Images\n\nSambee supports both browser-native formats and formats that need server-side conversion.\n\n- browser-native formats can be sent to the viewer directly\n- non-browser-native image formats are converted on the server before the browser renders them\n- special cases such as transparency preservation can change the output format choice\n\nIf you change conversion rules, you are changing a product contract, not just an implementation detail.\n\n### Server-Side Conversion Contract\n\nThe conversion path is owned by `backend/app/services/image_converter.py` and is exercised through the viewer API.\n\nThe backend conversion service is responsible for:\n\n- deciding whether an image needs processing\n- converting unsupported or impractical browser formats into a viewer-safe output format\n- preserving transparency where the output contract requires it\n- applying optional downscaling so one preview request cannot explode memory usage casually\n- returning enough metadata for the viewer endpoint to send the correct MIME type back to the browser\n\nRepresentative service responsibilities include:\n\n- `needs_processing(filename)`\n- `convert_image_for_viewer(...)`\n- `is_image_file(filename)`\n- `get_image_info(...)`\n\nThe viewer endpoint then follows this rule:\n\n- if the image can stream safely as-is, return a streaming response\n- if it requires conversion, read it, convert it, and return the converted bytes with the converted MIME type\n\nThat means preview behavior for formats such as TIFF, HEIC, BMP, ICO, and similar formats depends on backend conversion policy, not just on frontend MIME recognition.\n\n### Local-Drive Preview Policy\n\nThe Companion serves local-drive files and archive members as raw bytes. It does not copy local content to the backend for processing and does not bundle the backend image or PDF processing stack.\n\n- Browser-native images, text files, and original PDFs can preview from their raw local bytes.\n- Image formats that require server-side conversion, such as TIFF, HEIC, PSD, JPEG XL, and scientific image formats, show an explicit preview-unavailable state for local drives.\n- Image resizing and PDF compatibility normalization are unavailable for local drives.\n- Downloading and opening the original file locally remain available when a local preview is unavailable.\n\nThe frontend resolves these capabilities before making a local viewer request. Local archive-member requests use the Companion's strict raw-stream contract, while SMB archive-member requests retain the full conversion and PDF-normalization request parameters.\n\n### Output Format Rules\n\nThe backend does not always convert everything to the same output type.\n\n- JPEG is the common output for opaque images\n- PNG remains important when transparency must be preserved\n- ICO-like transparency handling is therefore different from ordinary opaque-photo conversion\n- alpha-bearing formats converted to JPEG need explicit compositing behavior rather than silent accidental loss\n\nIf you change those rules, check both visual correctness and user-facing assumptions such as download behavior and gallery continuity.\n\n### Current Format-Specific Preview Semantics\n\nSeveral converted-image families have product-specific preview semantics that contributors should preserve unless the product intentionally changes.\n\n- multi-page TIFF currently previews the first page rather than exposing a document-style page stack\n- PSD and PSB preview the flattened composite instead of surfacing layer-edit semantics through the browser viewer\n- EPS and AI are rasterized through the preprocessing path at high quality, currently using the 300 DPI rendering baseline\n- HDR-oriented formats such as EXR and Radiance HDR are tone-mapped into ordinary browser-display output\n- whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF preview as an overview or first practical pyramid level rather than as a full pathology viewer\n- FITS and similar scientific-image formats apply visibility scaling so low-level pixel values become inspectable in a normal browser image surface\n\nThese are not accidental implementation details. They define what users should expect from preview and therefore belong to the product contract.\n\n### Resizing and Resource Limits\n\nServer-side conversion can consume significant memory because the file must be read, decoded, and re-encoded.\n\nThe current contract therefore includes:\n\n- configurable JPEG-quality behavior\n- maximum-dimension downscaling to avoid unbounded preview size\n- backend-side protection against excessive memory usage from large source images\n\nContributors should treat those limits as operational safety controls, not as arbitrary defaults.\n\n### Dependency and Environment Expectations\n\nThe conversion path depends on reviewed Python and system-image libraries.\n\nThat includes the normal image stack plus HEIC/HEIF support through the reviewed dependency chain and corresponding system libraries in the container or runtime image.\n\nWhen conversion support seems to disappear unexpectedly, check:\n\n- the backend Python dependency set\n- the container or host system-image libraries\n- whether the format-specific support was actually installed in the current environment\n\n### Preprocessor Registry for Exotic Formats\n\nSome formats need a preprocessing step before the normal conversion path can handle them at all.\n\nThat registry lives in:\n\n- `backend/app/services/preprocessor.py`\n\nIt is consumed by:\n\n- `backend/app/services/image_converter.py`\n\nThe preprocessor layer exists for formats that libvips should not or cannot decode directly for Sambee's preview contract.\n\nCurrent registered formats route through the ImageMagick-backed preprocessor:\n\n- `.psd`\n- `.psb`\n- `.eps`\n- `.ai`\n\nThe registry is the single source of truth for which extensions require preprocessing before the final viewer-safe conversion step.\n\nFor the backend service architecture behind that path, continue to [Image Preprocessing and Conversion Pipeline](../../backend-architecture/image-preprocessing-and-conversion-pipeline/).\n\nRepresentative registry operations include:\n\n- `PreprocessorRegistry.requires_preprocessing(extension)`\n- `PreprocessorRegistry.get_preprocessor_for_format(extension)`\n- `PreprocessorRegistry.get_supported_formats()`\n- `PreprocessorRegistry.register_format(extension, preprocessor_class)`\n\n### Preprocessor Design Rules\n\nThe preprocessor layer has its own constraints:\n\n- one registry entry per preprocessable extension\n- direct in-memory conversion to the final browser-ready format rather than chained intermediate formats\n- no shell-mediated fallback chain logic in the registry itself\n- input validation and timeout enforcement happen in the preprocessor layer\n- failures should surface as explicit preprocessing or conversion errors rather than silent format drift\n\nThe main abstraction is `PreprocessorInterface`, with `ImageMagickPreprocessor` as the current built-in implementation.\n\n### Adding a New Preprocessed Format\n\nIf a new format cannot be handled by the normal conversion stack directly:\n\n1. implement a `PreprocessorInterface` subclass if the existing preprocessor is not appropriate\n2. register the extension in `PreprocessorRegistry`\n3. add or update file-type metadata if the format becomes user-visible in preview flows\n4. add tests for format recognition, tool availability, validation, and successful conversion\n\nDo not treat preprocessable formats as ordinary file-type additions. They change the backend conversion pipeline itself.\n\n### Error Surface Contributors Must Preserve\n\nConversion failures are user-visible API behavior, not internal-only exceptions.\n\nTypical outcomes include:\n\n- not implemented when the current environment lacks support for a format family\n- unprocessable-content style failures when the file is corrupt or cannot be decoded\n- ordinary backend failures when an unexpected exception escapes the conversion path\n\nThat means error wording, status behavior, and frontend fallback behavior should be reviewed together.\n\n## Shared Viewer UI\n\nThe main viewer toolbar is intentionally centralized in `frontend/src/components/Viewer/ViewerControls.tsx`.\n\nThis is no longer just an image-and-PDF convenience component. It is the canonical control surface for the current full-screen image, PDF, and Markdown viewers.\n\n- shared toolbar layout, styling, keyboard-tooltip behavior, and responsive behavior live in `ViewerControls`\n- each viewer turns features on through configuration and passes only the state objects it needs\n- future viewers should reuse that control shell where possible instead of creating another top-level toolbar implementation\n\n### Control-Surface Model\n\n`ViewerControls` uses a feature-flag configuration plus typed state objects.\n\nThe configuration currently enables these capability groups:\n\n- `navigation` for gallery-style previous and next navigation\n- `pageNavigation` for PDF page input and page stepping\n- `zoom` for viewer-managed zoom actions\n- `rotation` for image and PDF rotation actions\n- `search` for the shared search row and match navigation affordances\n- `download` for explicit download actions\n- `share` for mobile-first share actions\n\nThe component then accepts matching state surfaces:\n\n- `NavigationState` for item index, total items, and next or previous handlers\n- `PageNavigationState` for current page, total pages, and page-change handling\n- `ZoomState` for zoom-in and zoom-out handlers\n- `RotationState` for rotate-left and rotate-right handlers\n- `SearchState` for search text, match counts, search-panel state, open or close callbacks, and viewer-specific search navigation\n\nThat split matters because `ViewerControls` owns the common UI, but it does not own viewer logic. It renders controls and delegates behavior back to the viewer that actually knows how to navigate pages, zoom, rotate, or search.\n\n### Current Consumers\n\nThe current shared-toolbar consumers are:\n\n- `ImageViewer`, which enables gallery navigation, zoom, rotation, download, and optional mobile share\n- `PDFViewer`, which enables page navigation, zoom, rotation, search, download, and optional mobile share\n- `MarkdownViewer`, which reuses the same shell for download, optional mobile share, shared search UI, and viewer-specific action buttons such as editing flows\n\n`ViewerControls` also supports generic toolbar actions through the `actions` prop, which can render either text buttons or icon buttons. That is what allows Markdown-specific actions to live inside the same shared toolbar instead of forcing a second toolbar implementation.\n\n### Search UI Versus Search Engine\n\nThe search row is shared, but the search backend is viewer-specific.\n\n- `PDFViewer` wires the search controls to PDF text extraction, page-aware match tracking, and PDF-specific next or previous navigation\n- rendered Markdown and other rendered text views can route search through the DOM text-search utility in `frontend/src/utils/domTextSearch.ts`\n- Markdown edit mode does not reuse the rendered-view DOM search implementation; it bridges the same outer toolbar UI into the editor-specific search state and commands instead\n\nThat separation is an important contract: contributors should reuse the shared search UI when possible, but should not assume every viewer can use the same search implementation under the hood.\n\n### Responsive and Accessibility Rules\n\nThe centralized toolbar also encodes product behavior that should stay consistent across viewers.\n\n- filename display, optional filename adornments, and close behavior are shared\n- mobile layout uses safe-area-aware spacing and smaller controls\n- gallery arrows and desktop zoom controls are intentionally reduced on mobile, where gesture-based interaction is preferred\n- share is exposed as a mobile-first affordance, with optional early-intent warming through `onShareIntent`\n- buttons use explicit `aria-label` values and shortcut-oriented `title` text so the control surface remains navigable and self-describing\n- the shared search row manages focus when it opens and preserves consistent close behavior for toggle and Escape-driven exits\n\n### Legacy Components and Contributor Guidance\n\nLegacy `ImageControls.tsx` and `PDFControls.tsx` files still exist in the frontend tree, but `ViewerControls` is the current architectural direction and the shared component used by the active image, PDF, and Markdown viewers.\n\nIf you add another viewer or extend an existing one:\n\n- prefer extending `ViewerControlsConfig`, the relevant state interfaces, or the generic `actions` surface\n- keep viewer-specific logic in the viewer component rather than teaching `ViewerControls` about file-format internals\n- preserve shared mobile, accessibility, and search-panel behavior unless the product intentionally changes that contract\n- add or update focused tests in `frontend/src/components/Viewer/__tests__/ViewerControls.test.tsx` when the shared toolbar contract changes\n\n## Adding a New File Type Safely\n\nFile-type support is registry-driven. The safest way to add a new type is to treat backend and frontend changes as one contract update.\n\n### Main Files to Change\n\n| Path | Why it changes |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | declare extensions, MIME types, category, description, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | declare extensions, MIME types, category, viewer component, icon, color, and description |\n| `frontend/src/components/Viewer/` | add or reuse a viewer component when the type needs a dedicated preview surface |\n\nIf a file type is user-visible, update the published support docs that describe what Sambee can preview.\n\n### Quick Start for a New Image Format\n\nFor an image format such as JPEG XL, the minimum workflow is:\n\n1. add a `FileTypeDefinition` entry to the backend registry\n2. add the matching entry to the frontend registry\n3. decide whether the image is browser-native or requires server-side conversion\n4. keep extensions and MIME types identical across both registries\n5. run the viewer and backend validation checks\n\nBackend example:\n\n```python\nFileTypeDefinition(\n\t\textensions=(\".jxl\",),\n\t\tmime_types=(\"image/jxl\",),\n\t\tcategory=FileCategory.IMAGE,\n\t\trequires_conversion=True,\n\t\tdescription=\"JPEG XL Image\",\n)\n```\n\nFrontend example:\n\n```typescript\n{\n\textensions: [\".jxl\"],\n\tmimeTypes: [\"image/jxl\"],\n\tcategory: \"image\",\n\tviewerComponent: () =\u003e import(\"../components/Viewer/ImageViewer\"),\n\ticon: \"image\",\n\tcolor: \"#a855f7\",\n\tdescription: \"JPEG XL Image\",\n}\n```\n\nThat registry update is what drives MIME matching, icon treatment, viewer routing, and image-gallery inclusion.\n\n### Backend Registry Rules\n\nBackend file-type definitions must stay explicit and type-safe.\n\n- `extensions` are tuples with a leading dot, such as `(\".jpg\", \".jpeg\")`\n- `mime_types` are tuples of standard MIME strings\n- `category` uses `FileCategory` values such as `IMAGE`, `DOCUMENT`, `TEXT`, `VIDEO`, `AUDIO`, `ARCHIVE`, `CODE`, `SPREADSHEET`, or `OTHER`\n- `requires_conversion` matters for image formats that cannot be rendered directly by the browser\n- `description` should be the human-readable label contributors and users would expect\n\nHow to decide `requires_conversion`:\n\n- set it to `False` for browser-native formats such as PNG, JPEG, GIF, WebP, SVG, and AVIF\n- set it to `True` for formats with limited browser support or formats that are not practical to render directly, such as TIFF, HEIC, BMP, JPEG 2000, or JPEG XL when browser support is not sufficient for the product baseline\n\n### Frontend Registry Rules\n\nFrontend file-type definitions control how the browser app presents the file.\n\n- keep `extensions` and `mimeTypes` aligned with the backend registry\n- set `viewerComponent` to the shared viewer that should render the type\n- choose an icon that matches the product language for that file category\n- choose a color that distinguishes the format without inventing a new palette on every addition\n\nFor image formats, reusing `ImageViewer` is usually enough. For non-image formats, you may need a dedicated viewer such as `PdfViewer`, `VideoViewer`, `AudioViewer`, or `TextViewer`.\n\n### Non-Image File Types\n\nThe overall process is the same for documents, video, audio, text, archives, and code files.\n\n1. add the backend registry entry\n2. add the frontend registry entry\n3. create or reuse the viewer component when preview support exists\n4. verify the file icon, viewer routing, and download behavior\n\nFor non-image files, `requires_conversion` is usually `False`. The main design question is whether the product has a viewer component for that category or should fall back to download-only behavior.\n\n### Integration Checklist\n\nUse this checklist before you consider the file type integrated:\n\n- backend registry entry added\n- frontend registry entry added\n- extensions and MIME types match exactly across both registries\n- browser-native versus converted-image behavior decided intentionally\n- viewer component chosen or added\n- icon and color treatment chosen\n- user-visible support docs updated if the file type changes what Sambee can preview\n\n### Testing Checklist\n\nAfter the registry change, verify:\n\n- icon display in the file browser\n- file opening in the expected viewer\n- shared toolbar behavior if the preview uses `ViewerControls`\n- conversion output if the format is server-converted\n- gallery inclusion for image formats\n- MIME type behavior across extension variants such as upper-case filenames\n- download behavior with the correct MIME type\n- mobile and tablet behavior when the preview is expected to work there\n\nFor server-converted formats, also verify:\n\n- the backend returns the converted MIME type you expect\n- transparency-sensitive formats still render correctly\n- resizing or quality settings do not degrade the preview contract unexpectedly\n- environment-specific format support failures surface in a controlled way\n\nFor preprocessable formats, also verify:\n\n- the registry recognizes the extension regardless of case and leading-dot differences\n- the expected preprocessor is selected for that format\n- missing external-tool support fails cleanly\n- validation and timeout rules behave as intended under bad inputs and slow conversions\n\n### Architecture Notes\n\nThese helper functions are the practical integration points contributors usually touch:\n\n- backend: `get_mime_type`, `needs_processing`, `is_image_file`, `get_file_type_by_extension`, `get_file_type_by_mime`\n- frontend: `getViewerComponent`, `isImageFile`, `getFileIcon`, `getFileTypeByExtension`, `getFileTypeByMime`\n\nAt runtime, the flow is:\n\n1. the backend lists files and assigns MIME information\n2. the frontend receives `FileInfo` data with that MIME information\n3. the frontend chooses icon treatment from filename and type rules\n4. the frontend selects the viewer from MIME and file-type data\n5. the backend routes convertible images through the image-conversion pipeline when needed\n\nThe frontend side still has work to do even when the backend owns the conversion:\n\n- viewer MIME recognition must include the input formats the backend classifies as previewable\n- file-type icon and color treatment must still reflect the original file type rather than the converted transport format\n- browser-side fallback MIME logic must not drift from the backend contract in ways that hide conversion bugs\n\n### Operational Characteristics\n\nServer-side conversion changes the runtime profile of preview requests.\n\n- large images can produce short CPU spikes during decode and encode\n- memory usage can rise well above compressed input size while the image is fully decoded\n- SMB-backed reads add their own latency before conversion even starts\n\nThat is why preview regressions for large HEIC or TIFF files often need both backend and user-facing verification.\n\n### Future Extension Points\n\nThe current conversion path leaves room for later enhancements such as:\n\n- caching converted preview outputs\n- queueing especially large conversions\n- dedicated thumbnail generation\n- richer multi-page image handling\n- conversion metrics for operational monitoring\n\nThose are extension points, not assumptions the current product already guarantees.\n\nThe highest-risk mistake is still registry drift. If the backend and frontend disagree about extensions or MIME types, preview behavior becomes unreliable in ways that are easy to miss until users hit them.\n\n## Common Failure Modes\n\n- backend and frontend MIME types do not match\n- a format is marked browser-native when it really needs conversion\n- a viewer component is not registered even though the type is recognized\n- a conversion change improves one format but breaks gallery behavior, download semantics, or mobile viewing\n\n## Validation Expectations\n\nWhen you change viewer or file-type behavior, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd backend \u0026\u0026 pytest -v\n```\n\nIf the change is image-conversion-specific, include the relevant backend tests around image conversion and preview behavior.\n", "0.9": "+++\ntitle = \"Viewer Architecture and Preview Contracts\"\n+++\n\nPreview behavior in Sambee is a cross-boundary contract, not just a frontend component choice.\n\n## The Core Contract\n\nThe browser app decides how to render a file based on metadata and file-type information, but that depends on server-side classification staying aligned.\n\nThree rules matter most:\n\n- the backend and frontend file-type registries must describe the same extensions and MIME types\n- the backend decides whether an image format needs server-side conversion for browser compatibility\n- the frontend chooses the right viewer component and file icon based on the effective file type and MIME information it receives\n\n## Where the Main Decisions Live\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | backend source of truth for extensions, MIME types, categories, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | frontend source of truth for extensions, MIME types, categories, viewer components, icons, and colors |\n| `frontend/src/components/Viewer/` | viewer components and shared viewer UI |\n| `backend/app/services/image_converter.py` | server-side conversion for non-browser-native image formats |\n\n## Viewer Selection Model\n\nAt a high level, the preview pipeline works like this:\n\n1. the backend determines file category and MIME behavior\n2. the backend decides whether the file can stream as-is or needs image conversion\n3. the frontend maps the file type to the appropriate viewer component\n4. the shared viewer controls keep the toolbar and common behavior consistent across viewers\n\nThat is why a file-type change almost always touches both backend and frontend code.\n\n## Browser-Native Versus Server-Converted Images\n\nSambee supports both browser-native formats and formats that need server-side conversion.\n\n- browser-native formats can be sent to the viewer directly\n- non-browser-native image formats are converted on the server before the browser renders them\n- special cases such as transparency preservation can change the output format choice\n\nIf you change conversion rules, you are changing a product contract, not just an implementation detail.\n\n### Server-Side Conversion Contract\n\nThe conversion path is owned by `backend/app/services/image_converter.py` and is exercised through the viewer API.\n\nThe backend conversion service is responsible for:\n\n- deciding whether an image needs processing\n- converting unsupported or impractical browser formats into a viewer-safe output format\n- preserving transparency where the output contract requires it\n- applying optional downscaling so one preview request cannot explode memory usage casually\n- returning enough metadata for the viewer endpoint to send the correct MIME type back to the browser\n\nRepresentative service responsibilities include:\n\n- `needs_processing(filename)`\n- `convert_image_for_viewer(...)`\n- `is_image_file(filename)`\n- `get_image_info(...)`\n\nThe viewer endpoint then follows this rule:\n\n- if the image can stream safely as-is, return a streaming response\n- if it requires conversion, read it, convert it, and return the converted bytes with the converted MIME type\n\nThat means preview behavior for formats such as TIFF, HEIC, BMP, ICO, and similar formats depends on backend conversion policy, not just on frontend MIME recognition.\n\n### Local-Drive Preview Policy\n\nThe Companion serves local-drive files and archive members as raw bytes. It does not copy local content to the backend for processing and does not bundle the backend image or PDF processing stack.\n\n- Browser-native images, text files, and original PDFs can preview from their raw local bytes.\n- Image formats that require server-side conversion, such as TIFF, HEIC, PSD, JPEG XL, and scientific image formats, show an explicit preview-unavailable state for local drives.\n- Image resizing and PDF compatibility normalization are unavailable for local drives.\n- Downloading and opening the original file locally remain available when a local preview is unavailable.\n\nThe frontend resolves these capabilities before making a local viewer request. Local archive-member requests use the Companion's strict raw-stream contract, while SMB archive-member requests retain the full conversion and PDF-normalization request parameters.\n\n### Output Format Rules\n\nThe backend does not always convert everything to the same output type.\n\n- JPEG is the common output for opaque images\n- PNG remains important when transparency must be preserved\n- ICO-like transparency handling is therefore different from ordinary opaque-photo conversion\n- alpha-bearing formats converted to JPEG need explicit compositing behavior rather than silent accidental loss\n\nIf you change those rules, check both visual correctness and user-facing assumptions such as download behavior and gallery continuity.\n\n### Current Format-Specific Preview Semantics\n\nSeveral converted-image families have product-specific preview semantics that contributors should preserve unless the product intentionally changes.\n\n- multi-page TIFF currently previews the first page rather than exposing a document-style page stack\n- PSD and PSB preview the flattened composite instead of surfacing layer-edit semantics through the browser viewer\n- EPS and AI are rasterized through the preprocessing path at high quality, currently using the 300 DPI rendering baseline\n- HDR-oriented formats such as EXR and Radiance HDR are tone-mapped into ordinary browser-display output\n- whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF preview as an overview or first practical pyramid level rather than as a full pathology viewer\n- FITS and similar scientific-image formats apply visibility scaling so low-level pixel values become inspectable in a normal browser image surface\n\nThese are not accidental implementation details. They define what users should expect from preview and therefore belong to the product contract.\n\n### Resizing and Resource Limits\n\nServer-side conversion can consume significant memory because the file must be read, decoded, and re-encoded.\n\nThe current contract therefore includes:\n\n- configurable JPEG-quality behavior\n- maximum-dimension downscaling to avoid unbounded preview size\n- backend-side protection against excessive memory usage from large source images\n\nContributors should treat those limits as operational safety controls, not as arbitrary defaults.\n\n### Dependency and Environment Expectations\n\nThe conversion path depends on reviewed Python and system-image libraries.\n\nThat includes the normal image stack plus HEIC/HEIF support through the reviewed dependency chain and corresponding system libraries in the container or runtime image.\n\nWhen conversion support seems to disappear unexpectedly, check:\n\n- the backend Python dependency set\n- the container or host system-image libraries\n- whether the format-specific support was actually installed in the current environment\n\n### Preprocessor Registry for Exotic Formats\n\nSome formats need a preprocessing step before the normal conversion path can handle them at all.\n\nThat registry lives in:\n\n- `backend/app/services/preprocessor.py`\n\nIt is consumed by:\n\n- `backend/app/services/image_converter.py`\n\nThe preprocessor layer exists for formats that libvips should not or cannot decode directly for Sambee's preview contract.\n\nCurrent registered formats route through the ImageMagick-backed preprocessor:\n\n- `.psd`\n- `.psb`\n- `.eps`\n- `.ai`\n\nThe registry is the single source of truth for which extensions require preprocessing before the final viewer-safe conversion step.\n\nFor the backend service architecture behind that path, continue to [Image Preprocessing and Conversion Pipeline](../../backend-architecture/image-preprocessing-and-conversion-pipeline/).\n\nRepresentative registry operations include:\n\n- `PreprocessorRegistry.requires_preprocessing(extension)`\n- `PreprocessorRegistry.get_preprocessor_for_format(extension)`\n- `PreprocessorRegistry.get_supported_formats()`\n- `PreprocessorRegistry.register_format(extension, preprocessor_class)`\n\n### Preprocessor Design Rules\n\nThe preprocessor layer has its own constraints:\n\n- one registry entry per preprocessable extension\n- direct in-memory conversion to the final browser-ready format rather than chained intermediate formats\n- no shell-mediated fallback chain logic in the registry itself\n- input validation and timeout enforcement happen in the preprocessor layer\n- failures should surface as explicit preprocessing or conversion errors rather than silent format drift\n\nThe main abstraction is `PreprocessorInterface`, with `ImageMagickPreprocessor` as the current built-in implementation.\n\n### Adding a New Preprocessed Format\n\nIf a new format cannot be handled by the normal conversion stack directly:\n\n1. implement a `PreprocessorInterface` subclass if the existing preprocessor is not appropriate\n2. register the extension in `PreprocessorRegistry`\n3. add or update file-type metadata if the format becomes user-visible in preview flows\n4. add tests for format recognition, tool availability, validation, and successful conversion\n\nDo not treat preprocessable formats as ordinary file-type additions. They change the backend conversion pipeline itself.\n\n### Error Surface Contributors Must Preserve\n\nConversion failures are user-visible API behavior, not internal-only exceptions.\n\nTypical outcomes include:\n\n- not implemented when the current environment lacks support for a format family\n- unprocessable-content style failures when the file is corrupt or cannot be decoded\n- ordinary backend failures when an unexpected exception escapes the conversion path\n\nThat means error wording, status behavior, and frontend fallback behavior should be reviewed together.\n\n## Shared Viewer UI\n\nThe main viewer toolbar is intentionally centralized in `frontend/src/components/Viewer/ViewerControls.tsx`.\n\nThis is no longer just an image-and-PDF convenience component. It is the canonical control surface for the current full-screen image, PDF, and Markdown viewers.\n\n- shared toolbar layout, styling, keyboard-tooltip behavior, and responsive behavior live in `ViewerControls`\n- each viewer turns features on through configuration and passes only the state objects it needs\n- future viewers should reuse that control shell where possible instead of creating another top-level toolbar implementation\n\n### Control-Surface Model\n\n`ViewerControls` uses a feature-flag configuration plus typed state objects.\n\nThe configuration currently enables these capability groups:\n\n- `navigation` for gallery-style previous and next navigation\n- `pageNavigation` for PDF page input and page stepping\n- `zoom` for viewer-managed zoom actions\n- `rotation` for image and PDF rotation actions\n- `search` for the shared search row and match navigation affordances\n- `download` for explicit download actions\n- `share` for mobile-first share actions\n\nThe component then accepts matching state surfaces:\n\n- `NavigationState` for item index, total items, and next or previous handlers\n- `PageNavigationState` for current page, total pages, and page-change handling\n- `ZoomState` for zoom-in and zoom-out handlers\n- `RotationState` for rotate-left and rotate-right handlers\n- `SearchState` for search text, match counts, search-panel state, open or close callbacks, and viewer-specific search navigation\n\nThat split matters because `ViewerControls` owns the common UI, but it does not own viewer logic. It renders controls and delegates behavior back to the viewer that actually knows how to navigate pages, zoom, rotate, or search.\n\n### Current Consumers\n\nThe current shared-toolbar consumers are:\n\n- `ImageViewer`, which enables gallery navigation, zoom, rotation, download, and optional mobile share\n- `PDFViewer`, which enables page navigation, zoom, rotation, search, download, and optional mobile share\n- `MarkdownViewer`, which reuses the same shell for download, optional mobile share, shared search UI, and viewer-specific action buttons such as editing flows\n\n`ViewerControls` also supports generic toolbar actions through the `actions` prop, which can render either text buttons or icon buttons. That is what allows Markdown-specific actions to live inside the same shared toolbar instead of forcing a second toolbar implementation.\n\n### Search UI Versus Search Engine\n\nThe search row is shared, but the search backend is viewer-specific.\n\n- `PDFViewer` wires the search controls to PDF text extraction, page-aware match tracking, and PDF-specific next or previous navigation\n- rendered Markdown and other rendered text views can route search through the DOM text-search utility in `frontend/src/utils/domTextSearch.ts`\n- Markdown edit mode does not reuse the rendered-view DOM search implementation; it bridges the same outer toolbar UI into the editor-specific search state and commands instead\n\nThat separation is an important contract: contributors should reuse the shared search UI when possible, but should not assume every viewer can use the same search implementation under the hood.\n\n### Responsive and Accessibility Rules\n\nThe centralized toolbar also encodes product behavior that should stay consistent across viewers.\n\n- filename display, optional filename adornments, and close behavior are shared\n- mobile layout uses safe-area-aware spacing and smaller controls\n- gallery arrows and desktop zoom controls are intentionally reduced on mobile, where gesture-based interaction is preferred\n- share is exposed as a mobile-first affordance, with optional early-intent warming through `onShareIntent`\n- buttons use explicit `aria-label` values and shortcut-oriented `title` text so the control surface remains navigable and self-describing\n- the shared search row manages focus when it opens and preserves consistent close behavior for toggle and Escape-driven exits\n\n### Legacy Components and Contributor Guidance\n\nLegacy `ImageControls.tsx` and `PDFControls.tsx` files still exist in the frontend tree, but `ViewerControls` is the current architectural direction and the shared component used by the active image, PDF, and Markdown viewers.\n\nIf you add another viewer or extend an existing one:\n\n- prefer extending `ViewerControlsConfig`, the relevant state interfaces, or the generic `actions` surface\n- keep viewer-specific logic in the viewer component rather than teaching `ViewerControls` about file-format internals\n- preserve shared mobile, accessibility, and search-panel behavior unless the product intentionally changes that contract\n- add or update focused tests in `frontend/src/components/Viewer/__tests__/ViewerControls.test.tsx` when the shared toolbar contract changes\n\n## Adding a New File Type Safely\n\nFile-type support is registry-driven. The safest way to add a new type is to treat backend and frontend changes as one contract update.\n\n### Main Files to Change\n\n| Path | Why it changes |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | declare extensions, MIME types, category, description, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | declare extensions, MIME types, category, viewer component, icon, color, and description |\n| `frontend/src/components/Viewer/` | add or reuse a viewer component when the type needs a dedicated preview surface |\n\nIf a file type is user-visible, update the published support docs that describe what Sambee can preview.\n\n### Quick Start for a New Image Format\n\nFor an image format such as JPEG XL, the minimum workflow is:\n\n1. add a `FileTypeDefinition` entry to the backend registry\n2. add the matching entry to the frontend registry\n3. decide whether the image is browser-native or requires server-side conversion\n4. keep extensions and MIME types identical across both registries\n5. run the viewer and backend validation checks\n\nBackend example:\n\n```python\nFileTypeDefinition(\n\t\textensions=(\".jxl\",),\n\t\tmime_types=(\"image/jxl\",),\n\t\tcategory=FileCategory.IMAGE,\n\t\trequires_conversion=True,\n\t\tdescription=\"JPEG XL Image\",\n)\n```\n\nFrontend example:\n\n```typescript\n{\n\textensions: [\".jxl\"],\n\tmimeTypes: [\"image/jxl\"],\n\tcategory: \"image\",\n\tviewerComponent: () =\u003e import(\"../components/Viewer/ImageViewer\"),\n\ticon: \"image\",\n\tcolor: \"#a855f7\",\n\tdescription: \"JPEG XL Image\",\n}\n```\n\nThat registry update is what drives MIME matching, icon treatment, viewer routing, and image-gallery inclusion.\n\n### Backend Registry Rules\n\nBackend file-type definitions must stay explicit and type-safe.\n\n- `extensions` are tuples with a leading dot, such as `(\".jpg\", \".jpeg\")`\n- `mime_types` are tuples of standard MIME strings\n- `category` uses `FileCategory` values such as `IMAGE`, `DOCUMENT`, `TEXT`, `VIDEO`, `AUDIO`, `ARCHIVE`, `CODE`, `SPREADSHEET`, or `OTHER`\n- `requires_conversion` matters for image formats that cannot be rendered directly by the browser\n- `description` should be the human-readable label contributors and users would expect\n\nHow to decide `requires_conversion`:\n\n- set it to `False` for browser-native formats such as PNG, JPEG, GIF, WebP, SVG, and AVIF\n- set it to `True` for formats with limited browser support or formats that are not practical to render directly, such as TIFF, HEIC, BMP, JPEG 2000, or JPEG XL when browser support is not sufficient for the product baseline\n\n### Frontend Registry Rules\n\nFrontend file-type definitions control how the browser app presents the file.\n\n- keep `extensions` and `mimeTypes` aligned with the backend registry\n- set `viewerComponent` to the shared viewer that should render the type\n- choose an icon that matches the product language for that file category\n- choose a color that distinguishes the format without inventing a new palette on every addition\n\nFor image formats, reusing `ImageViewer` is usually enough. For non-image formats, you may need a dedicated viewer such as `PdfViewer`, `VideoViewer`, `AudioViewer`, or `TextViewer`.\n\n### Non-Image File Types\n\nThe overall process is the same for documents, video, audio, text, archives, and code files.\n\n1. add the backend registry entry\n2. add the frontend registry entry\n3. create or reuse the viewer component when preview support exists\n4. verify the file icon, viewer routing, and download behavior\n\nFor non-image files, `requires_conversion` is usually `False`. The main design question is whether the product has a viewer component for that category or should fall back to download-only behavior.\n\n### Integration Checklist\n\nUse this checklist before you consider the file type integrated:\n\n- backend registry entry added\n- frontend registry entry added\n- extensions and MIME types match exactly across both registries\n- browser-native versus converted-image behavior decided intentionally\n- viewer component chosen or added\n- icon and color treatment chosen\n- user-visible support docs updated if the file type changes what Sambee can preview\n\n### Testing Checklist\n\nAfter the registry change, verify:\n\n- icon display in the file browser\n- file opening in the expected viewer\n- shared toolbar behavior if the preview uses `ViewerControls`\n- conversion output if the format is server-converted\n- gallery inclusion for image formats\n- MIME type behavior across extension variants such as upper-case filenames\n- download behavior with the correct MIME type\n- mobile and tablet behavior when the preview is expected to work there\n\nFor server-converted formats, also verify:\n\n- the backend returns the converted MIME type you expect\n- transparency-sensitive formats still render correctly\n- resizing or quality settings do not degrade the preview contract unexpectedly\n- environment-specific format support failures surface in a controlled way\n\nFor preprocessable formats, also verify:\n\n- the registry recognizes the extension regardless of case and leading-dot differences\n- the expected preprocessor is selected for that format\n- missing external-tool support fails cleanly\n- validation and timeout rules behave as intended under bad inputs and slow conversions\n\n### Architecture Notes\n\nThese helper functions are the practical integration points contributors usually touch:\n\n- backend: `get_mime_type`, `needs_processing`, `is_image_file`, `get_file_type_by_extension`, `get_file_type_by_mime`\n- frontend: `getViewerComponent`, `isImageFile`, `getFileIcon`, `getFileTypeByExtension`, `getFileTypeByMime`\n\nAt runtime, the flow is:\n\n1. the backend lists files and assigns MIME information\n2. the frontend receives `FileInfo` data with that MIME information\n3. the frontend chooses icon treatment from filename and type rules\n4. the frontend selects the viewer from MIME and file-type data\n5. the backend routes convertible images through the image-conversion pipeline when needed\n\nThe frontend side still has work to do even when the backend owns the conversion:\n\n- viewer MIME recognition must include the input formats the backend classifies as previewable\n- file-type icon and color treatment must still reflect the original file type rather than the converted transport format\n- browser-side fallback MIME logic must not drift from the backend contract in ways that hide conversion bugs\n\n### Operational Characteristics\n\nServer-side conversion changes the runtime profile of preview requests.\n\n- large images can produce short CPU spikes during decode and encode\n- memory usage can rise well above compressed input size while the image is fully decoded\n- SMB-backed reads add their own latency before conversion even starts\n\nThat is why preview regressions for large HEIC or TIFF files often need both backend and user-facing verification.\n\n### Future Extension Points\n\nThe current conversion path leaves room for later enhancements such as:\n\n- caching converted preview outputs\n- queueing especially large conversions\n- dedicated thumbnail generation\n- richer multi-page image handling\n- conversion metrics for operational monitoring\n\nThose are extension points, not assumptions the current product already guarantees.\n\nThe highest-risk mistake is still registry drift. If the backend and frontend disagree about extensions or MIME types, preview behavior becomes unreliable in ways that are easy to miss until users hit them.\n\n## Common Failure Modes\n\n- backend and frontend MIME types do not match\n- a format is marked browser-native when it really needs conversion\n- a viewer component is not registered even though the type is recognized\n- a conversion change improves one format but breaks gallery behavior, download semantics, or mobile viewing\n\n## Validation Expectations\n\nWhen you change viewer or file-type behavior, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd backend \u0026\u0026 pytest -v\n```\n\nIf the change is image-conversion-specific, include the relevant backend tests around image conversion and preview behavior.\n", "1.0": "+++\ntitle = \"Viewer Architecture and Preview Contracts\"\n+++\n\nPreview behavior in Sambee is a cross-boundary contract, not just a frontend component choice.\n\n## The Core Contract\n\nThe browser app decides how to render a file based on metadata and file-type information, but that depends on server-side classification staying aligned.\n\nThree rules matter most:\n\n- the backend and frontend file-type registries must describe the same extensions and MIME types\n- the backend decides whether an image format needs server-side conversion for browser compatibility\n- the frontend chooses the right viewer component and file icon based on the effective file type and MIME information it receives\n\n## Where the Main Decisions Live\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | backend source of truth for extensions, MIME types, categories, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | frontend source of truth for extensions, MIME types, categories, viewer components, icons, and colors |\n| `frontend/src/components/Viewer/` | viewer components and shared viewer UI |\n| `backend/app/services/image_converter.py` | server-side conversion for non-browser-native image formats |\n\n## Viewer Selection Model\n\nAt a high level, the preview pipeline works like this:\n\n1. the backend determines file category and MIME behavior\n2. the backend decides whether the file can stream as-is or needs image conversion\n3. the frontend maps the file type to the appropriate viewer component\n4. the shared viewer controls keep the toolbar and common behavior consistent across viewers\n\nThat is why a file-type change almost always touches both backend and frontend code.\n\n## Browser-Native Versus Server-Converted Images\n\nSambee supports both browser-native formats and formats that need server-side conversion.\n\n- browser-native formats can be sent to the viewer directly\n- non-browser-native image formats are converted on the server before the browser renders them\n- special cases such as transparency preservation can change the output format choice\n\nIf you change conversion rules, you are changing a product contract, not just an implementation detail.\n\n### Server-Side Conversion Contract\n\nThe conversion path is owned by `backend/app/services/image_converter.py` and is exercised through the viewer API.\n\nThe backend conversion service is responsible for:\n\n- deciding whether an image needs processing\n- converting unsupported or impractical browser formats into a viewer-safe output format\n- preserving transparency where the output contract requires it\n- applying optional downscaling so one preview request cannot explode memory usage casually\n- returning enough metadata for the viewer endpoint to send the correct MIME type back to the browser\n\nRepresentative service responsibilities include:\n\n- `needs_processing(filename)`\n- `convert_image_for_viewer(...)`\n- `is_image_file(filename)`\n- `get_image_info(...)`\n\nThe viewer endpoint then follows this rule:\n\n- if the image can stream safely as-is, return a streaming response\n- if it requires conversion, read it, convert it, and return the converted bytes with the converted MIME type\n\nThat means preview behavior for formats such as TIFF, HEIC, BMP, ICO, and similar formats depends on backend conversion policy, not just on frontend MIME recognition.\n\n### Local-Drive Preview Policy\n\nThe Companion serves local-drive files and archive members as raw bytes. It does not copy local content to the backend for processing and does not bundle the backend image or PDF processing stack.\n\n- Browser-native images, text files, and original PDFs can preview from their raw local bytes.\n- Image formats that require server-side conversion, such as TIFF, HEIC, PSD, JPEG XL, and scientific image formats, show an explicit preview-unavailable state for local drives.\n- Image resizing and PDF compatibility normalization are unavailable for local drives.\n- Downloading and opening the original file locally remain available when a local preview is unavailable.\n\nThe frontend resolves these capabilities before making a local viewer request. Local archive-member requests use the Companion's strict raw-stream contract, while SMB archive-member requests retain the full conversion and PDF-normalization request parameters.\n\n### Output Format Rules\n\nThe backend does not always convert everything to the same output type.\n\n- JPEG is the common output for opaque images\n- PNG remains important when transparency must be preserved\n- ICO-like transparency handling is therefore different from ordinary opaque-photo conversion\n- alpha-bearing formats converted to JPEG need explicit compositing behavior rather than silent accidental loss\n\nIf you change those rules, check both visual correctness and user-facing assumptions such as download behavior and gallery continuity.\n\n### Current Format-Specific Preview Semantics\n\nSeveral converted-image families have product-specific preview semantics that contributors should preserve unless the product intentionally changes.\n\n- multi-page TIFF currently previews the first page rather than exposing a document-style page stack\n- PSD and PSB preview the flattened composite instead of surfacing layer-edit semantics through the browser viewer\n- EPS and AI are rasterized through the preprocessing path at high quality, currently using the 300 DPI rendering baseline\n- HDR-oriented formats such as EXR and Radiance HDR are tone-mapped into ordinary browser-display output\n- whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF preview as an overview or first practical pyramid level rather than as a full pathology viewer\n- FITS and similar scientific-image formats apply visibility scaling so low-level pixel values become inspectable in a normal browser image surface\n\nThese are not accidental implementation details. They define what users should expect from preview and therefore belong to the product contract.\n\n### Resizing and Resource Limits\n\nServer-side conversion can consume significant memory because the file must be read, decoded, and re-encoded.\n\nThe current contract therefore includes:\n\n- configurable JPEG-quality behavior\n- maximum-dimension downscaling to avoid unbounded preview size\n- backend-side protection against excessive memory usage from large source images\n\nContributors should treat those limits as operational safety controls, not as arbitrary defaults.\n\n### Dependency and Environment Expectations\n\nThe conversion path depends on reviewed Python and system-image libraries.\n\nThat includes the normal image stack plus HEIC/HEIF support through the reviewed dependency chain and corresponding system libraries in the container or runtime image.\n\nWhen conversion support seems to disappear unexpectedly, check:\n\n- the backend Python dependency set\n- the container or host system-image libraries\n- whether the format-specific support was actually installed in the current environment\n\n### Preprocessor Registry for Exotic Formats\n\nSome formats need a preprocessing step before the normal conversion path can handle them at all.\n\nThat registry lives in:\n\n- `backend/app/services/preprocessor.py`\n\nIt is consumed by:\n\n- `backend/app/services/image_converter.py`\n\nThe preprocessor layer exists for formats that libvips should not or cannot decode directly for Sambee's preview contract.\n\nCurrent registered formats route through the ImageMagick-backed preprocessor:\n\n- `.psd`\n- `.psb`\n- `.eps`\n- `.ai`\n\nThe registry is the single source of truth for which extensions require preprocessing before the final viewer-safe conversion step.\n\nFor the backend service architecture behind that path, continue to [Image Preprocessing and Conversion Pipeline](../../backend-architecture/image-preprocessing-and-conversion-pipeline/).\n\nRepresentative registry operations include:\n\n- `PreprocessorRegistry.requires_preprocessing(extension)`\n- `PreprocessorRegistry.get_preprocessor_for_format(extension)`\n- `PreprocessorRegistry.get_supported_formats()`\n- `PreprocessorRegistry.register_format(extension, preprocessor_class)`\n\n### Preprocessor Design Rules\n\nThe preprocessor layer has its own constraints:\n\n- one registry entry per preprocessable extension\n- direct in-memory conversion to the final browser-ready format rather than chained intermediate formats\n- no shell-mediated fallback chain logic in the registry itself\n- input validation and timeout enforcement happen in the preprocessor layer\n- failures should surface as explicit preprocessing or conversion errors rather than silent format drift\n\nThe main abstraction is `PreprocessorInterface`, with `ImageMagickPreprocessor` as the current built-in implementation.\n\n### Adding a New Preprocessed Format\n\nIf a new format cannot be handled by the normal conversion stack directly:\n\n1. implement a `PreprocessorInterface` subclass if the existing preprocessor is not appropriate\n2. register the extension in `PreprocessorRegistry`\n3. add or update file-type metadata if the format becomes user-visible in preview flows\n4. add tests for format recognition, tool availability, validation, and successful conversion\n\nDo not treat preprocessable formats as ordinary file-type additions. They change the backend conversion pipeline itself.\n\n### Error Surface Contributors Must Preserve\n\nConversion failures are user-visible API behavior, not internal-only exceptions.\n\nTypical outcomes include:\n\n- not implemented when the current environment lacks support for a format family\n- unprocessable-content style failures when the file is corrupt or cannot be decoded\n- ordinary backend failures when an unexpected exception escapes the conversion path\n\nThat means error wording, status behavior, and frontend fallback behavior should be reviewed together.\n\n## Shared Viewer UI\n\nThe main viewer toolbar is intentionally centralized in `frontend/src/components/Viewer/ViewerControls.tsx`.\n\nThis is no longer just an image-and-PDF convenience component. It is the canonical control surface for the current full-screen image, PDF, and Markdown viewers.\n\n- shared toolbar layout, styling, keyboard-tooltip behavior, and responsive behavior live in `ViewerControls`\n- each viewer turns features on through configuration and passes only the state objects it needs\n- future viewers should reuse that control shell where possible instead of creating another top-level toolbar implementation\n\n### Control-Surface Model\n\n`ViewerControls` uses a feature-flag configuration plus typed state objects.\n\nThe configuration currently enables these capability groups:\n\n- `navigation` for gallery-style previous and next navigation\n- `pageNavigation` for PDF page input and page stepping\n- `zoom` for viewer-managed zoom actions\n- `rotation` for image and PDF rotation actions\n- `search` for the shared search row and match navigation affordances\n- `download` for explicit download actions\n- `share` for mobile-first share actions\n\nThe component then accepts matching state surfaces:\n\n- `NavigationState` for item index, total items, and next or previous handlers\n- `PageNavigationState` for current page, total pages, and page-change handling\n- `ZoomState` for zoom-in and zoom-out handlers\n- `RotationState` for rotate-left and rotate-right handlers\n- `SearchState` for search text, match counts, search-panel state, open or close callbacks, and viewer-specific search navigation\n\nThat split matters because `ViewerControls` owns the common UI, but it does not own viewer logic. It renders controls and delegates behavior back to the viewer that actually knows how to navigate pages, zoom, rotate, or search.\n\n### Current Consumers\n\nThe current shared-toolbar consumers are:\n\n- `ImageViewer`, which enables gallery navigation, zoom, rotation, download, and optional mobile share\n- `PDFViewer`, which enables page navigation, zoom, rotation, search, download, and optional mobile share\n- `MarkdownViewer`, which reuses the same shell for download, optional mobile share, shared search UI, and viewer-specific action buttons such as editing flows\n\n`ViewerControls` also supports generic toolbar actions through the `actions` prop, which can render either text buttons or icon buttons. That is what allows Markdown-specific actions to live inside the same shared toolbar instead of forcing a second toolbar implementation.\n\n### Search UI Versus Search Engine\n\nThe search row is shared, but the search backend is viewer-specific.\n\n- `PDFViewer` wires the search controls to PDF text extraction, page-aware match tracking, and PDF-specific next or previous navigation\n- rendered Markdown and other rendered text views can route search through the DOM text-search utility in `frontend/src/utils/domTextSearch.ts`\n- Markdown edit mode does not reuse the rendered-view DOM search implementation; it bridges the same outer toolbar UI into the editor-specific search state and commands instead\n\nThat separation is an important contract: contributors should reuse the shared search UI when possible, but should not assume every viewer can use the same search implementation under the hood.\n\n### Responsive and Accessibility Rules\n\nThe centralized toolbar also encodes product behavior that should stay consistent across viewers.\n\n- filename display, optional filename adornments, and close behavior are shared\n- mobile layout uses safe-area-aware spacing and smaller controls\n- gallery arrows and desktop zoom controls are intentionally reduced on mobile, where gesture-based interaction is preferred\n- share is exposed as a mobile-first affordance, with optional early-intent warming through `onShareIntent`\n- buttons use explicit `aria-label` values and shortcut-oriented `title` text so the control surface remains navigable and self-describing\n- the shared search row manages focus when it opens and preserves consistent close behavior for toggle and Escape-driven exits\n\n### Legacy Components and Contributor Guidance\n\nLegacy `ImageControls.tsx` and `PDFControls.tsx` files still exist in the frontend tree, but `ViewerControls` is the current architectural direction and the shared component used by the active image, PDF, and Markdown viewers.\n\nIf you add another viewer or extend an existing one:\n\n- prefer extending `ViewerControlsConfig`, the relevant state interfaces, or the generic `actions` surface\n- keep viewer-specific logic in the viewer component rather than teaching `ViewerControls` about file-format internals\n- preserve shared mobile, accessibility, and search-panel behavior unless the product intentionally changes that contract\n- add or update focused tests in `frontend/src/components/Viewer/__tests__/ViewerControls.test.tsx` when the shared toolbar contract changes\n\n## Adding a New File Type Safely\n\nFile-type support is registry-driven. The safest way to add a new type is to treat backend and frontend changes as one contract update.\n\n### Main Files to Change\n\n| Path | Why it changes |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | declare extensions, MIME types, category, description, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | declare extensions, MIME types, category, viewer component, icon, color, and description |\n| `frontend/src/components/Viewer/` | add or reuse a viewer component when the type needs a dedicated preview surface |\n\nIf a file type is user-visible, update the published support docs that describe what Sambee can preview.\n\n### Quick Start for a New Image Format\n\nFor an image format such as JPEG XL, the minimum workflow is:\n\n1. add a `FileTypeDefinition` entry to the backend registry\n2. add the matching entry to the frontend registry\n3. decide whether the image is browser-native or requires server-side conversion\n4. keep extensions and MIME types identical across both registries\n5. run the viewer and backend validation checks\n\nBackend example:\n\n```python\nFileTypeDefinition(\n\t\textensions=(\".jxl\",),\n\t\tmime_types=(\"image/jxl\",),\n\t\tcategory=FileCategory.IMAGE,\n\t\trequires_conversion=True,\n\t\tdescription=\"JPEG XL Image\",\n)\n```\n\nFrontend example:\n\n```typescript\n{\n\textensions: [\".jxl\"],\n\tmimeTypes: [\"image/jxl\"],\n\tcategory: \"image\",\n\tviewerComponent: () =\u003e import(\"../components/Viewer/ImageViewer\"),\n\ticon: \"image\",\n\tcolor: \"#a855f7\",\n\tdescription: \"JPEG XL Image\",\n}\n```\n\nThat registry update is what drives MIME matching, icon treatment, viewer routing, and image-gallery inclusion.\n\n### Backend Registry Rules\n\nBackend file-type definitions must stay explicit and type-safe.\n\n- `extensions` are tuples with a leading dot, such as `(\".jpg\", \".jpeg\")`\n- `mime_types` are tuples of standard MIME strings\n- `category` uses `FileCategory` values such as `IMAGE`, `DOCUMENT`, `TEXT`, `VIDEO`, `AUDIO`, `ARCHIVE`, `CODE`, `SPREADSHEET`, or `OTHER`\n- `requires_conversion` matters for image formats that cannot be rendered directly by the browser\n- `description` should be the human-readable label contributors and users would expect\n\nHow to decide `requires_conversion`:\n\n- set it to `False` for browser-native formats such as PNG, JPEG, GIF, WebP, SVG, and AVIF\n- set it to `True` for formats with limited browser support or formats that are not practical to render directly, such as TIFF, HEIC, BMP, JPEG 2000, or JPEG XL when browser support is not sufficient for the product baseline\n\n### Frontend Registry Rules\n\nFrontend file-type definitions control how the browser app presents the file.\n\n- keep `extensions` and `mimeTypes` aligned with the backend registry\n- set `viewerComponent` to the shared viewer that should render the type\n- choose an icon that matches the product language for that file category\n- choose a color that distinguishes the format without inventing a new palette on every addition\n\nFor image formats, reusing `ImageViewer` is usually enough. For non-image formats, you may need a dedicated viewer such as `PdfViewer`, `VideoViewer`, `AudioViewer`, or `TextViewer`.\n\n### Non-Image File Types\n\nThe overall process is the same for documents, video, audio, text, archives, and code files.\n\n1. add the backend registry entry\n2. add the frontend registry entry\n3. create or reuse the viewer component when preview support exists\n4. verify the file icon, viewer routing, and download behavior\n\nFor non-image files, `requires_conversion` is usually `False`. The main design question is whether the product has a viewer component for that category or should fall back to download-only behavior.\n\n### Integration Checklist\n\nUse this checklist before you consider the file type integrated:\n\n- backend registry entry added\n- frontend registry entry added\n- extensions and MIME types match exactly across both registries\n- browser-native versus converted-image behavior decided intentionally\n- viewer component chosen or added\n- icon and color treatment chosen\n- user-visible support docs updated if the file type changes what Sambee can preview\n\n### Testing Checklist\n\nAfter the registry change, verify:\n\n- icon display in the file browser\n- file opening in the expected viewer\n- shared toolbar behavior if the preview uses `ViewerControls`\n- conversion output if the format is server-converted\n- gallery inclusion for image formats\n- MIME type behavior across extension variants such as upper-case filenames\n- download behavior with the correct MIME type\n- mobile and tablet behavior when the preview is expected to work there\n\nFor server-converted formats, also verify:\n\n- the backend returns the converted MIME type you expect\n- transparency-sensitive formats still render correctly\n- resizing or quality settings do not degrade the preview contract unexpectedly\n- environment-specific format support failures surface in a controlled way\n\nFor preprocessable formats, also verify:\n\n- the registry recognizes the extension regardless of case and leading-dot differences\n- the expected preprocessor is selected for that format\n- missing external-tool support fails cleanly\n- validation and timeout rules behave as intended under bad inputs and slow conversions\n\n### Architecture Notes\n\nThese helper functions are the practical integration points contributors usually touch:\n\n- backend: `get_mime_type`, `needs_processing`, `is_image_file`, `get_file_type_by_extension`, `get_file_type_by_mime`\n- frontend: `getViewerComponent`, `isImageFile`, `getFileIcon`, `getFileTypeByExtension`, `getFileTypeByMime`\n\nAt runtime, the flow is:\n\n1. the backend lists files and assigns MIME information\n2. the frontend receives `FileInfo` data with that MIME information\n3. the frontend chooses icon treatment from filename and type rules\n4. the frontend selects the viewer from MIME and file-type data\n5. the backend routes convertible images through the image-conversion pipeline when needed\n\nThe frontend side still has work to do even when the backend owns the conversion:\n\n- viewer MIME recognition must include the input formats the backend classifies as previewable\n- file-type icon and color treatment must still reflect the original file type rather than the converted transport format\n- browser-side fallback MIME logic must not drift from the backend contract in ways that hide conversion bugs\n\n### Operational Characteristics\n\nServer-side conversion changes the runtime profile of preview requests.\n\n- large images can produce short CPU spikes during decode and encode\n- memory usage can rise well above compressed input size while the image is fully decoded\n- SMB-backed reads add their own latency before conversion even starts\n\nThat is why preview regressions for large HEIC or TIFF files often need both backend and user-facing verification.\n\n### Future Extension Points\n\nThe current conversion path leaves room for later enhancements such as:\n\n- caching converted preview outputs\n- queueing especially large conversions\n- dedicated thumbnail generation\n- richer multi-page image handling\n- conversion metrics for operational monitoring\n\nThose are extension points, not assumptions the current product already guarantees.\n\nThe highest-risk mistake is still registry drift. If the backend and frontend disagree about extensions or MIME types, preview behavior becomes unreliable in ways that are easy to miss until users hit them.\n\n## Common Failure Modes\n\n- backend and frontend MIME types do not match\n- a format is marked browser-native when it really needs conversion\n- a viewer component is not registered even though the type is recognized\n- a conversion change improves one format but breaks gallery behavior, download semantics, or mobile viewing\n\n## Validation Expectations\n\nWhen you change viewer or file-type behavior, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd backend \u0026\u0026 pytest -v\n```\n\nIf the change is image-conversion-specific, include the relevant backend tests around image conversion and preview behavior.\n", "2.0": "+++\ntitle = \"Viewer Architecture and Preview Contracts\"\n+++\n\nPreview behavior in Sambee is a cross-boundary contract, not just a frontend component choice.\n\n## The Core Contract\n\nThe browser app decides how to render a file based on metadata and file-type information, but that depends on server-side classification staying aligned.\n\nThree rules matter most:\n\n- the backend and frontend file-type registries must describe the same extensions and MIME types\n- the backend decides whether an image format needs server-side conversion for browser compatibility\n- the frontend chooses the right viewer component and file icon based on the effective file type and MIME information it receives\n\n## Where the Main Decisions Live\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | backend source of truth for extensions, MIME types, categories, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | frontend source of truth for extensions, MIME types, categories, viewer components, icons, and colors |\n| `frontend/src/components/Viewer/` | viewer components and shared viewer UI |\n| `backend/app/services/image_converter.py` | server-side conversion for non-browser-native image formats |\n\n## Viewer Selection Model\n\nAt a high level, the preview pipeline works like this:\n\n1. the backend determines file category and MIME behavior\n2. the backend decides whether the file can stream as-is or needs image conversion\n3. the frontend maps the file type to the appropriate viewer component\n4. the shared viewer controls keep the toolbar and common behavior consistent across viewers\n\nThat is why a file-type change almost always touches both backend and frontend code.\n\n## Browser-Native Versus Server-Converted Images\n\nSambee supports both browser-native formats and formats that need server-side conversion.\n\n- browser-native formats can be sent to the viewer directly\n- non-browser-native image formats are converted on the server before the browser renders them\n- special cases such as transparency preservation can change the output format choice\n\nIf you change conversion rules, you are changing a product contract, not just an implementation detail.\n\n### Server-Side Conversion Contract\n\nThe conversion path is owned by `backend/app/services/image_converter.py` and is exercised through the viewer API.\n\nThe backend conversion service is responsible for:\n\n- deciding whether an image needs processing\n- converting unsupported or impractical browser formats into a viewer-safe output format\n- preserving transparency where the output contract requires it\n- applying optional downscaling so one preview request cannot explode memory usage casually\n- returning enough metadata for the viewer endpoint to send the correct MIME type back to the browser\n\nRepresentative service responsibilities include:\n\n- `needs_processing(filename)`\n- `convert_image_for_viewer(...)`\n- `is_image_file(filename)`\n- `get_image_info(...)`\n\nThe viewer endpoint then follows this rule:\n\n- if the image can stream safely as-is, return a streaming response\n- if it requires conversion, read it, convert it, and return the converted bytes with the converted MIME type\n\nThat means preview behavior for formats such as TIFF, HEIC, BMP, ICO, and similar formats depends on backend conversion policy, not just on frontend MIME recognition.\n\n### Local-Drive Preview Policy\n\nThe Companion serves local-drive files and archive members as raw bytes. It does not copy local content to the backend for processing and does not bundle the backend image or PDF processing stack.\n\n- Browser-native images, text files, and original PDFs can preview from their raw local bytes.\n- Image formats that require server-side conversion, such as TIFF, HEIC, PSD, JPEG XL, and scientific image formats, show an explicit preview-unavailable state for local drives.\n- Image resizing and PDF compatibility normalization are unavailable for local drives.\n- Downloading and opening the original file locally remain available when a local preview is unavailable.\n\nThe frontend resolves these capabilities before making a local viewer request. Local archive-member requests use the Companion's strict raw-stream contract, while SMB archive-member requests retain the full conversion and PDF-normalization request parameters.\n\n### Output Format Rules\n\nThe backend does not always convert everything to the same output type.\n\n- JPEG is the common output for opaque images\n- PNG remains important when transparency must be preserved\n- ICO-like transparency handling is therefore different from ordinary opaque-photo conversion\n- alpha-bearing formats converted to JPEG need explicit compositing behavior rather than silent accidental loss\n\nIf you change those rules, check both visual correctness and user-facing assumptions such as download behavior and gallery continuity.\n\n### Current Format-Specific Preview Semantics\n\nSeveral converted-image families have product-specific preview semantics that contributors should preserve unless the product intentionally changes.\n\n- multi-page TIFF currently previews the first page rather than exposing a document-style page stack\n- PSD and PSB preview the flattened composite instead of surfacing layer-edit semantics through the browser viewer\n- EPS and AI are rasterized through the preprocessing path at high quality, currently using the 300 DPI rendering baseline\n- HDR-oriented formats such as EXR and Radiance HDR are tone-mapped into ordinary browser-display output\n- whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF preview as an overview or first practical pyramid level rather than as a full pathology viewer\n- FITS and similar scientific-image formats apply visibility scaling so low-level pixel values become inspectable in a normal browser image surface\n\nThese are not accidental implementation details. They define what users should expect from preview and therefore belong to the product contract.\n\n### Resizing and Resource Limits\n\nServer-side conversion can consume significant memory because the file must be read, decoded, and re-encoded.\n\nThe current contract therefore includes:\n\n- configurable JPEG-quality behavior\n- maximum-dimension downscaling to avoid unbounded preview size\n- backend-side protection against excessive memory usage from large source images\n\nContributors should treat those limits as operational safety controls, not as arbitrary defaults.\n\n### Dependency and Environment Expectations\n\nThe conversion path depends on reviewed Python and system-image libraries.\n\nThat includes the normal image stack plus HEIC/HEIF support through the reviewed dependency chain and corresponding system libraries in the container or runtime image.\n\nWhen conversion support seems to disappear unexpectedly, check:\n\n- the backend Python dependency set\n- the container or host system-image libraries\n- whether the format-specific support was actually installed in the current environment\n\n### Preprocessor Registry for Exotic Formats\n\nSome formats need a preprocessing step before the normal conversion path can handle them at all.\n\nThat registry lives in:\n\n- `backend/app/services/preprocessor.py`\n\nIt is consumed by:\n\n- `backend/app/services/image_converter.py`\n\nThe preprocessor layer exists for formats that libvips should not or cannot decode directly for Sambee's preview contract.\n\nCurrent registered formats route through the ImageMagick-backed preprocessor:\n\n- `.psd`\n- `.psb`\n- `.eps`\n- `.ai`\n\nThe registry is the single source of truth for which extensions require preprocessing before the final viewer-safe conversion step.\n\nFor the backend service architecture behind that path, continue to [Image Preprocessing and Conversion Pipeline](../../backend-architecture/image-preprocessing-and-conversion-pipeline/).\n\nRepresentative registry operations include:\n\n- `PreprocessorRegistry.requires_preprocessing(extension)`\n- `PreprocessorRegistry.get_preprocessor_for_format(extension)`\n- `PreprocessorRegistry.get_supported_formats()`\n- `PreprocessorRegistry.register_format(extension, preprocessor_class)`\n\n### Preprocessor Design Rules\n\nThe preprocessor layer has its own constraints:\n\n- one registry entry per preprocessable extension\n- direct in-memory conversion to the final browser-ready format rather than chained intermediate formats\n- no shell-mediated fallback chain logic in the registry itself\n- input validation and timeout enforcement happen in the preprocessor layer\n- failures should surface as explicit preprocessing or conversion errors rather than silent format drift\n\nThe main abstraction is `PreprocessorInterface`, with `ImageMagickPreprocessor` as the current built-in implementation.\n\n### Adding a New Preprocessed Format\n\nIf a new format cannot be handled by the normal conversion stack directly:\n\n1. implement a `PreprocessorInterface` subclass if the existing preprocessor is not appropriate\n2. register the extension in `PreprocessorRegistry`\n3. add or update file-type metadata if the format becomes user-visible in preview flows\n4. add tests for format recognition, tool availability, validation, and successful conversion\n\nDo not treat preprocessable formats as ordinary file-type additions. They change the backend conversion pipeline itself.\n\n### Error Surface Contributors Must Preserve\n\nConversion failures are user-visible API behavior, not internal-only exceptions.\n\nTypical outcomes include:\n\n- not implemented when the current environment lacks support for a format family\n- unprocessable-content style failures when the file is corrupt or cannot be decoded\n- ordinary backend failures when an unexpected exception escapes the conversion path\n\nThat means error wording, status behavior, and frontend fallback behavior should be reviewed together.\n\n## Shared Viewer UI\n\nThe main viewer toolbar is intentionally centralized in `frontend/src/components/Viewer/ViewerControls.tsx`.\n\nThis is no longer just an image-and-PDF convenience component. It is the canonical control surface for the current full-screen image, PDF, and Markdown viewers.\n\n- shared toolbar layout, styling, keyboard-tooltip behavior, and responsive behavior live in `ViewerControls`\n- each viewer turns features on through configuration and passes only the state objects it needs\n- future viewers should reuse that control shell where possible instead of creating another top-level toolbar implementation\n\n### Control-Surface Model\n\n`ViewerControls` uses a feature-flag configuration plus typed state objects.\n\nThe configuration currently enables these capability groups:\n\n- `navigation` for gallery-style previous and next navigation\n- `pageNavigation` for PDF page input and page stepping\n- `zoom` for viewer-managed zoom actions\n- `rotation` for image and PDF rotation actions\n- `search` for the shared search row and match navigation affordances\n- `download` for explicit download actions\n- `share` for mobile-first share actions\n\nThe component then accepts matching state surfaces:\n\n- `NavigationState` for item index, total items, and next or previous handlers\n- `PageNavigationState` for current page, total pages, and page-change handling\n- `ZoomState` for zoom-in and zoom-out handlers\n- `RotationState` for rotate-left and rotate-right handlers\n- `SearchState` for search text, match counts, search-panel state, open or close callbacks, and viewer-specific search navigation\n\nThat split matters because `ViewerControls` owns the common UI, but it does not own viewer logic. It renders controls and delegates behavior back to the viewer that actually knows how to navigate pages, zoom, rotate, or search.\n\n### Current Consumers\n\nThe current shared-toolbar consumers are:\n\n- `ImageViewer`, which enables gallery navigation, zoom, rotation, download, and optional mobile share\n- `PDFViewer`, which enables page navigation, zoom, rotation, search, download, and optional mobile share\n- `MarkdownViewer`, which reuses the same shell for download, optional mobile share, shared search UI, and viewer-specific action buttons such as editing flows\n\n`ViewerControls` also supports generic toolbar actions through the `actions` prop, which can render either text buttons or icon buttons. That is what allows Markdown-specific actions to live inside the same shared toolbar instead of forcing a second toolbar implementation.\n\n### Search UI Versus Search Engine\n\nThe search row is shared, but the search backend is viewer-specific.\n\n- `PDFViewer` wires the search controls to PDF text extraction, page-aware match tracking, and PDF-specific next or previous navigation. Its text-layer markers use `frontend/src/utils/domTextSearch.ts`.\n- Rendered Markdown uses a preview-owned session in `frontend/src/utils/viewportDomTextSearch.ts`. It reuses the DOM index and matcher from `domTextSearch.ts`, preserving rendered-text boundaries, cross-inline matches and exact code whitespace.\n- Markdown edit mode doesn't reuse the rendered-view DOM search implementation. It bridges the same outer toolbar UI into the editor-specific search state and commands instead.\n\nThe Markdown preview separates logical matches from their presentation. It retains exact match positions and text-node mappings, but paints at most 1,000 viewport search ranges plus one active-match range through CSS Highlights. Search doesn't insert markers, split text nodes or replace preview content. Navigation resolves the destination directly from the index and scrolls the content viewport, including for off-screen matches.\n\nEach preview generation owns its search session. Query changes reuse the unchanged DOM index; text replacement or character-data changes invalidate it. Syntax painting and theme-variable changes don't invalidate it. Scroll, resize, image loading and font readiness refresh presentation without matching the document again. Disposing the preview removes its highlights, style, observers, listeners, cached text and pending animation frame. PDF search remains independent.\n\nDOM capture collects text chunks and joins them once, preserving numeric offsets and block separators without repeatedly flattening the growing source. Syntax publication separately caps its viewport ranges and clips horizontally overflowing unwrapped code to visible columns. Both search and syntax skip vertical character-range lookup when the owning text box is wholly inside the viewport; partially clipped boxes retain exact boundary lookup. Horizontal clipping is independent of that fast path: the left lookup can stop at the first character, and the right lookup reuses the exact left boundary as its lower bound. Disjoint horizontal clips produce no ranges. These optimizations don't estimate character widths or cache geometry. Nested code-block scrolling refreshes syntax and search ranges without changing the source or search index.\n\nSearch highlight colors inherit the preview's scoped theme variables. Browsers without CSS Highlights retain counts and indexed navigation without visual search highlighting; the viewer logs that limitation rather than falling back to whole-document marker insertion. Browser support and whole-viewer performance acceptance remain separate rollout gates. Cached indexing doesn't guarantee responsive capture or rendering for arbitrarily large documents.\n\nUse the existing production-viewer check in `frontend/e2e/markdown-viewer.spec.ts` to attribute performance within the ReactMarkdown path. Its User Timing entries separate preview-search lookup, geometry, scrolling and publication from syntax mapping, geometry, range construction and publication. Geometry reads may force layout; registry calls can include native browser work, but don't necessarily include deferred painting. Worker round trips include transfer and acknowledgements, not just parsing. Source-response, DOM-commit-observer and frame milestones narrow initial-load costs without claiming isolated React CPU or hardware input-to-visible-paint latency. Functional passes don't establish the responsiveness budgets.\n\nInitial-load Markdown normalization runs through the existing preparation worker in `frontend/src/utils/markdownCodePreparation.ts`. Each load owns a worker and transfers source, canonical text and an equivalent canonical MDAST in acknowledged, bounded chunks. Tree batches contain at most 512 records and 16,384 string UTF-16 units; individual field pieces are at most 2,048 units. Numeric/flag/position metadata is validated separately, and large text and table alignment fields use the chunk channel instead of content limits. Host acknowledgements yield between tree batches. Success, cancellation, decode failure and timeout terminate the worker; aborted loads can't publish content. Worker failures use the existing load-error path without a synchronous retry, and local preparation failures aren't reported as server overload. The pre-app capability gate requires a callable Web Worker API and otherwise shows the existing unsupported-browser screen without importing the app. The helper retains defensive synchronous normalization with a diagnostic, but Worker-less app operation isn't supported. API presence doesn't guarantee successful worker construction or execution; existing startup, timeout, crash and decode-error handling remains necessary. The shared protocol is DOM-free. Vite's shared resolver aliases the character decoder to its non-DOM implementation before dependency optimization, so development and production workers use the same implementation. A worker-build-only resolver isn't sufficient for development's prebundled dependencies.\n\nReactMarkdown remains the only application whole-document renderer in every build mode. Its parser hook reuses a defensive clone of the prepared tree only when the tree matches the preview generation's exact source. All normal remark transforms, GFM, table-cell break handling, safe URL/raw HTML behavior and React rendering remain in that path. Cloning prevents those transforms from mutating the retained canonical tree. A successful Save that changes the source releases the superseded tree; edited content without a matching tree uses the normal parser.\n\nRendered Markdown sources of at least 50,000 UTF-16 units use `ProgressiveMarkdown` to append the existing pipeline's fully transformed output. Document-wide references, headings and GFM are resolved once before staging. Chunks aren't parsed as independent Markdown documents. Ordinary sources keep their immediate rendering path. Staged batches use the same ReactMarkdown rendering and safe-link/raw-HTML handling, with at most 1,024 structural nodes or 8,192 text units. Oversized tables, containers and code blocks are subdivided internally, preserving one native table or code block rather than splitting it into separate documents. Already-published nodes aren't replaced by later appends.\n\nThe viewer targets two viewport heights for the initial fill, then yields. Later frames use the 4 ms elapsed-work target without a height limit or repeated per-batch geometry reads. Each frame commits at most four batches, checking elapsed time after every commit to bound work accumulated before native layout. Neither the fill target nor these limits guarantee a maximum task duration: whole-document cloning/transforms, a single commit and native layout remain synchronous. Visible pages use animation frames; hidden pages use timers so completion doesn't wait indefinitely for a frame. Source or rendering-configuration changes and disposal cancel the old publication owner; a restarted generation resets document readiness. A 200 ms delayed, accessible loading indicator disappears immediately on completion and respects reduced motion.\n\nReading published text and closing the viewer remain available during progressive loading. Document search/counts, editing, heading-link navigation and toolbar printing wait for complete publication; syntax painting and DOM search indexing also wait. Browser-menu printing while loading shows a loading notice instead of partial document content. Once complete, normal native selection, search, links and print behavior apply. These controls prevent partial results from being presented as complete; they don't promise that synchronous preparation can never block input.\n\nMarkdown editing reuses the preparation worker for full-document canonical normalization when the editor source contains `\u003cbr`. The existing no-`\u003cbr` typing path still publishes immediately without normalization. If both the original baseline and edited document contain possible table syntax, a background preservation-only job compares their tables without changing that typing normalization policy. Identical sources or documents without a pipe character need no table comparison. Each editor owns at most one active job and one replaceable latest request. Only the current source, baseline, policy and generation can satisfy a prepared snapshot; obsolete success, failure and diagnostic messages are ignored. Worker acknowledgements never replace the native CodeMirror document, recreate table-cell editors or change transaction history. Pending table/IME publication and worker preparation keep the viewer dirty independently of canonical draft publication. External source changes and unmount dispose the old owner and its workers; a baseline change invalidates unmatched prepared bytes.\n\nToolbar Save takes focus before its click handler captures selection. The rich editor therefore remembers the active nested table cell on native focus entry and departure, and refreshes that snapshot when selection is explicitly preserved inside the editor. Stay-edit Save restores the same connected cell within the current root instead of focusing the root and triggering native table-widget reconstruction. If the cell document changed while Save was pending, restoration keeps its newer native selection rather than replaying old offsets. Returning to root-text editing, replacing the external document and unmounting clear the remembered cell; disconnected or replaced cells use the existing root-selection fallback. This doesn't change native transactions, history grouping or composition handling. Production checks require retained cell identity/focus after Save, continued typing, and native undo/redo; these functional checks don't establish responsiveness acceptance.\n\nAsync snapshot capture flushes table/IME publication and worker preparation within the existing transition deadline. It requires full-document normalization even after the typing fast path, so Save retains list, escape and table canonicalization. The same worker performs the unchanged AST-aware table comparison against the exact original baseline, preserving original source for semantically unchanged tables. Source and baseline transfer sequentially in acknowledged chunks of at most 16,384 UTF-16 units, with generation and sequence validation; result chunks retain the same bound. Edit preparation doesn't request a preview tree, whose offsets would no longer match preserved source. Save consumes immutable, complete source-preserving snapshot bytes; repeated serialization returns the captured string without parsing. A successful write acknowledges only its snapshot: newer pending edits stay dirty, and an unavailable newer snapshot doesn't turn the completed write into a failure. Worker failure preserves editing and dirty content; a subsequent explicit async snapshot request can retry, but failures never trigger a synchronous parsing fallback or an automatic retry loop.\n\nSynchronous snapshot capture and canonical getters reject pending or failed worker preparation, including an unmatched source-preservation baseline, rather than returning an older revision as current. Recovery retains its synchronous pagehide/pre-sign-in attempts, debounce and limits; failed capture logs the failure and shows the existing recovery warning. It doesn't mark content saved. Native text sharing is unavailable while publication is pending and reads a complete snapshot when ready. Worker-side normalization and source preservation don't establish whole-viewer timing or resource acceptance; native table editing, layout and preview reconstruction remain separately measured costs.\n\nThe bounded `sambee:edit-preparation:*` entries separate queue wait, worker startup/first acknowledgement, source and baseline transfers, run-to-first-result, result delivery, total transport/job time and complete async snapshot flush. Numeric metadata records generation, source/baseline lengths, policy, chunk counts and whether a completed job is current or obsolete; it contains no source text. Transport completion also reports worker normalization and source-preservation durations separately. Host intervals include event-loop scheduling and acknowledgement delays, so startup isn't isolated worker boot time and transfer isn't pure wire time. Worker durations aren't main-thread CPU, and nested intervals mustn't be added to their enclosing job or snapshot flush. Each stage retains only its latest entry; the existing test observer collects individual samples. Use these measurements to distinguish Save wait from the native table/focus work that can follow write acknowledgement, not to infer a faster Save or passing keyboard/paint budgets from worker offload alone.\n\nThe bounded `sambee:preview-preparation:*` entries separate asynchronous decode elapsed time, load normalization, tree cloning, code-block collection and ReactMarkdown transforms. `load-normalization-elapsed` includes worker startup, transfer, work, host tree assembly, acknowledgements and scheduling, not main-thread CPU time. `render-prepared-tree` measures the defensive clone; `render-parse` measures normal parsing when no matching tree is available. The initial-load production matrix requires the clone stage and rejects synchronous `render-parse` and standalone `collection-parse` stages. Live syntax request collection walks the renderer's existing tree; it doesn't parse source again or change markup. The `collection-walk` interval is included in `render-transform`, not additional time to sum. Each generation publishes its ordered requests after DOM commit, before the passive syntax preparation effect, which snapshots them and retains cancellation and stale-generation guards.\n\nThe HAST-ready-to-layout-effect interval includes element construction, reconciliation, commit and scheduling, not just React CPU or paint. Entries contain no source text; each stage retains its latest measurement while the browser test observer collects individual samples. Normalization reuses its parsed tree when canonicalization leaves the source unchanged and reparses in the worker when edits change source offsets. Tree reuse doesn't close responsiveness, retained-memory, syntax-completion or native interaction acceptance.\n\nThat separation is an important contract: contributors should reuse the shared search UI when possible, but should not assume every viewer can use the same search implementation under the hood.\n\n### Single-Renderer Acceptance\n\nThe retained whole-document viewer integration and its special build-mode selection have been removed. Don't reconnect the historical publisher or add a second renderer to finish shared highlighting. Reuse ReactMarkdown, its parsed-tree code collection, the existing workers and viewport CSS highlights. Standalone renderer proofs are historical research, not application acceptance or a delivery dependency.\n\nRun `npm run build`, then `SAMBEE_E2E_PRODUCTION=1 SAMBEE_E2E_BUDGETS=1 npm run test:e2e:all -- --grep 'production syntax publication' --workers=1 --repeat-each=3` from `frontend/`. The existing matrix uses the approved demo connection and unchanged dense, near-safeguard, host-envelope, many-block and long-line fixtures in Chromium and Firefox at desktop and narrow widths. Add `PLAYWRIGHT_JSON_OUTPUT_FILE=/tmp/sambee-reactmarkdown-baseline.json` and `--reporter=json` to retain structured reports without npm's console preamble. Each fixture attaches `viewer-timing-budgets.json`, with observed values, numeric targets, pass/fail results and criteria that remain unmeasured.\n\nThe timing gate evaluates file-click-to-text-completion, first exact search, changed query, last-match navigation and maximum viewer timer-service gap. Missing, non-finite or negative samples fail every run; `SAMBEE_E2E_BUDGETS=1` also fails over-budget samples. Omit that flag for functional-only runs, which still attach the budget result. Forced-GC and tracing runs are marked diagnostic and can't enforce timing acceptance. Run `npm run test -- src/utils/__tests__/viewerPerformanceBudgets.test.ts` from `frontend/` for the evaluator's boundary and error tests. These browser-independent checks also run in the normal Vitest CI suite, without repeating them for each browser project. To validate a recorded report, the existing Playwright entry point remains available: `SAMBEE_E2E_PRODUCTION=1 SAMBEE_E2E_REPORT=/tmp/report.json SAMBEE_E2E_SLICE=publication npm run test:e2e -- viewer-performance-budgets.spec.ts --workers=1`.\n\nSearch/query/navigation probes start in browser event handlers, observe the expected count and active highlight in the existing small search controls, and finish after two frames. They avoid page-wide text queries and Playwright round-trip timing, but aren't hardware input-to-visible-paint measurements. The existing active-search fixture deliberately holds syntax preparation; text-load completion doesn't include syntax. Fresh/cached grammar isolation, first usable text/highlight completion, source editing, large prose/tables, resource acceptance and native interaction still require their own evidence. A passing timing subset isn't full rollout acceptance.\n\nThe browser checks compare exact rendered text, native Select All, selected code text and accessibility-tree output. They also exercise keyboard focus, safe links/HTML, GFM tables/tasks, shared Find navigation, theme-variable updates without text-node replacement, native copy events and Chromium PDF generation. These don't establish OS clipboard payloads, browser-native Find reveal, assistive-technology behavior or visual full-document print/PDF correctness. Those remain manual gates.\n\nThe separate native-constraint slice checks representative multiline, long-line and nested Markdown at widths 1543/390 in Chromium/Firefox. It compares cross-block selected text with a trusted keyboard copy/paste payload, exercises keyboard focus and native `window.find` selection/reveal, and attaches real Chromium PDFs. The native text-find API isn't the browser Find toolbar, and a narrow desktop viewport isn't a physical phone. From `frontend/`, after a normal production build, run:\n\n```sh\nPLAYWRIGHT_JSON_OUTPUT_FILE=/tmp/sambee-native-constraints.json SAMBEE_E2E_PRODUCTION=1 npm run test:e2e:all -- --grep 'production native Markdown constraints' --workers=1 --reporter=json\n```\n\nFrom the repository root, check the attached PDF text with the existing backend environment:\n\n```sh\nbackend/.venv/bin/python -m scripts.check_native_markdown_pdf /tmp/sambee-native-constraints.json\n```\n\nThe checker rejects missing/duplicate PDF cases, unsuccessful browser results and missing rendered-document lines. Heading IDs use a safe prefix and standard duplicate/Unicode slugging in the existing HAST pipeline; matching fragments are rewritten consistently. Native and printing matrices have independent checks. Chromium's `window.find` reveal is diagnostic-only because it can select without scrolling even outside Sambee; exact selection remains required in both engines, and Firefox reveal remains enforced. Don't add application scrolling to manufacture a native Find pass.\n\nThe Markdown preview's Print icon calls the native browser print dialog; Save as PDF is a destination in that dialog, not a second renderer or server-side conversion. Print isn't offered in edit mode or enabled while loading has failed or is incomplete. Print-only styles hide controls/background UI, release fullscreen/scroll constraints, wrap code/table cells, retain images and use black text on white regardless of the screen theme. Native `beforeprint`/`afterprint` handlers preserve focus, selection and nested scroll, with pending callbacks removed on disposal. The fullscreen paper sizes against its fixed container rather than dynamic viewport units that can retain print-page dimensions.\n\nRun the independent print matrix from `frontend/`, then inspect the PDF attachments from the repository root:\n\n```sh\nPLAYWRIGHT_JSON_OUTPUT_FILE=/tmp/sambee-markdown-printing.json SAMBEE_E2E_PRODUCTION=1 npm run test:e2e:all -- --grep 'production Markdown printing' --workers=1 --reporter=json\n```\n\n```sh\nbackend/.venv/bin/python -m scripts.check_native_markdown_pdf /tmp/sambee-markdown-printing.json --printing\n```\n\nThe 24-case matrix covers three fixtures, both themes, both widths and both engines. It verifies action invocation, print CSS, wrapping/widths and actual Chromium PDF state restoration. The PDF gate requires all 12 Chromium outputs to contain every rendered non-whitespace text line and an embedded image. Clear any forced screen-media override before PDF generation; otherwise Playwright prints screen CSS. First/last-page raster inspection supplements text checks. Firefox CSS checks aren't actual Firefox PDF evidence. Actual Firefox PDF and desktop/physical printing were separately confirmed complete by the user on 2026-10-24; no detailed browser/printer support matrix is inferred. Browser destination, paper, margin and header/footer settings remain user-controlled.\n\nKeep performance changes local to measured costs in the current path. Distinguish first visible syntax from completion of all block preparation, and include serialization and parent updates when measuring typing or atomic replace-all. Configuration-only theme and grammar updates must not request caret reveal or replace the document, selection or editor. Don't add streaming, scheduling abstractions or new edit protocols without evidence that the existing path misses its target.\n\nThe existing viewer harness also has a `production source responsiveness` slice for the 54,000-unit dense and 6,000-match long-line source fixtures. It verifies bounded worker delivery, one atomic replacement, undo/redo, exact saved file bytes and worker termination. Save assertions decode the complete multipart body received by the isolated test HTTP proxy; Playwright's request snapshot can omit uploaded file bytes. All traffic uses fixtures, never stored demo edits.\n\nLarge Replace All operations may temporarily block the editor while CodeMirror applies their atomic change set. This latency is an accepted limitation under D5, not permission to truncate output, split history or replace the entire document instead of preserving logical changes. Text and Markdown editors share an editor-owned indeterminate replacement indicator. Worker preparation shows it only after 200 ms; completion before that threshold cancels it without a flash. Ordinary literal replacements stay synchronous and aren't given an artificial delay.\n\nBefore a known-heavy apply, the indicator is shown and given two animation-frame callbacks so the browser has a paint opportunity before the native dispatch. The conservative workload gate requires at least 1,000 replacements and at least 50,000 UTF-16 units in the source or inserted payload. Literal commands inspect at most 1,000 matches for this estimate; worker commands use the completed change plan. This isn't a duration prediction: some fast workloads may be classified as heavy, and unexpectedly slow synchronous work cannot reveal a delayed indicator while blocking the main thread. Feedback already visible during preparation also receives a paint opportunity before application. There's no minimum visible duration or delayed completion, and the spinner doesn't promise continued animation or input responsiveness during synchronous apply.\n\nThe same command boundary covers toolbar and keyboard Replace All. Pending replacements reject duplicate invocations. Any introduced yield revalidates the exact document, query, selection and writability; editing or switching state cancels obsolete work rather than applying stale replacements. Failure, timeout, cancellation and editor disposal release the indicator, animation, timers and listeners. Hidden documents don't wait indefinitely for throttled animation frames. The status uses the editor theme, exposes accessible busy/status semantics and respects reduced motion; physical assistive-technology behavior remains a separate manual check.\n\nThe `production replacement feedback` slice checks quick no-flash behavior and captures visible feedback with the original source still present, then releases held frames and verifies atomic undo/redo, exact multipart Save and editor cleanup in both engines at widths 1543/390. Its held-frame evidence is functional, not timing acceptance.\n\nSource edits retain one bounded User Timing entry per stage: `sambee:source-editor:serialize`, `sambee:source-editor:publish`, `sambee:source-editor:normalize` and `sambee:source-editor:parent-update`. The enclosing publication includes normalization and the synchronous parent callback. These overlapping stages mustn't be added together. Entries contain lengths/revisions, not document contents. `sambee:source-search:commit` brackets the native atomic dispatch, including its synchronous listeners; deferred React work isn't isolated CPU time inside that measure. The separate click-to-completion probe waits for the parent dirty-state render and two subsequent frames. That boundary is a scheduling proxy, not hardware paint.\n\nFrom `frontend/`, after a normal production build, run:\n\n```sh\nPLAYWRIGHT_JSON_OUTPUT_FILE=/tmp/sambee-source-responsiveness.json SAMBEE_E2E_PRODUCTION=1 SAMBEE_E2E_BUDGETS=1 npm run test:e2e:all -- --grep 'production source responsiveness' --workers=1 --repeat-each=3 --reporter=json\n```\n\nEach sample attaches source-private measurements and explicit 50 ms atomic-dispatch, enclosing serialization/publication and maximum-timer-gap checks. Missing or invalid evidence fails even without `SAMBEE_E2E_BUDGETS`; that flag additionally enforces the original limits. Retain the failed native atomic-application timing results as diagnostic evidence of the D5 accepted limitation, not as passing samples or a reason to repeat performance-only matrices. Unrelated source timing, worker correctness and resource gates remain required. Transfer counts aren't retained/peak memory evidence, and these fixtures don't establish sustained typing, large-table normalization, dense output expansion or scrolling acceptance.\n\nThe separate `production source typing` slice types 82 characters at a requested 10 ms inter-key delay into each 54,000-unit fixture, without per-key polling. It records trusted browser keydown-to-first/two-frame samples, timer gaps, all four edit stages and optional whole-renderer Long Tasks entries, then verifies exact saved source plus the payload. The `source-typing` attachment enforces two-frame p95 strictly below 50 ms and stage/gap maxima at most 50 ms. All 24 engine/width/repeat trials pass; the worst per-trial p95 is 35 ms. This is a scheduling proxy, not physical input-to-painted-pixel acceptance. Unsupported Long Tasks capability stays unmeasured, and observed tasks wouldn't establish application-owned CPU attribution.\n\nThe `production prose table responsiveness` slice mounts the approved 4,000 formatted paragraphs or 2,400 two-column table rows. It checks every rendered paragraph/cell exactly, preserves native block whitespace, root/text-node identity and full rendered text through 60 programmatic scroll steps, and verifies cross-block native selection and close cleanup. Load timing runs from the browser's file-open click through two frames after all expected blocks mount. The `prose-table-responsiveness` attachment separates load budgets, the earlier two-viewport geometry milestone and diagnostic rAF scroll intervals, including the frame following the final scroll assignment. The final 24 trials complete within 1,110 ms, with the first viewport available within 761 ms. Nineteen trials exceed the unchanged 50 ms timer-gap limit, with a worst gap of 128 ms. These recorded loading pauses are accepted under D6, not passing timing samples or isolated CPU attribution. Headless rAF intervals don't establish physical refresh rate, wheel/touch, compositor or painted-frame acceptance. These fixtures have no fenced syntax and don't measure syntax readiness or large-table source normalization.\n\nThe separate `production progressive Markdown loading cancellation` slice holds frame callbacks after two viewport heights exist. It requires visible feedback, disabled document controls, loading-only print output and a working Close action, then releases stale callbacks and verifies complete reopening. It runs in Chromium and Firefox at widths 1543/390. Its paused screenshots and functional passes aren't timing evidence. The existing large-code publication, native interaction and print matrices remain independent regression checks; their completion and acceptance boundaries are recorded below.\n\nRun these slices separately from forced GC and CPU profiling:\n\n```sh\nPLAYWRIGHT_JSON_OUTPUT_FILE=/tmp/sambee-source-typing.json SAMBEE_E2E_PRODUCTION=1 SAMBEE_E2E_BUDGETS=1 npm run test:e2e:all -- --grep 'production source typing' --workers=1 --repeat-each=3 --reporter=json\nPLAYWRIGHT_JSON_OUTPUT_FILE=/tmp/sambee-prose-table-responsiveness-final.json SAMBEE_E2E_PRODUCTION=1 SAMBEE_E2E_BUDGETS=1 npm run test:e2e:all -- --grep 'production prose table responsiveness' --workers=1 --repeat-each=3 --reporter=json\n```\n\nFor separate Chromium load attribution, select the same prose/table slice with `SAMBEE_E2E_TRACE=1` and no budget enforcement or forced GC. The `viewer-load-cpu-profile` and `viewer-load-timeline` attachments span file open through completed mounting; nonempty CPU samples and both `sambee:viewer-load:start`/`sambee:viewer-load:complete` timeline markers are required. Budget status is diagnostic, never acceptance. Two desktop captures show one preview build, with a 126.05 ms prose render callback and a 53.69 ms table callback before native style/layout. The prose clone, transforms and HAST-to-layout-effect stages take 38.3, 37.5 and 44.5 ms; these overlap the encompassing callback and mustn't be added to it. Prose native style/layout takes a further 21.14/38.13 ms. Keep cached-tree isolation and native document semantics; neither deleting the clone nor an unapproved publication/renderer change is justified by this evidence. Firefox/mobile CPU attribution remains unverified.\n\nChromium CPU sample deltas can be negative. Reconstruct cumulative sample timestamps, sort them, then clip nonoverlapping intervals to the load markers. Summing only positive deltas inflates CPU weights. Use the marker's renderer PID/thread for main-thread timeline attribution; worker processing and unclassified native samples aren't automatically application-owned blocking CPU.\n\nRepeated source-regex Next/Previous requests are queued in order while navigation is pending. The active navigation worker reuses its transferred document for that burst, applying each native CodeMirror command from the preceding result's selection with the current position's whole-word rules. It terminates when the queue drains; no idle worker is retained. Document/query changes, external selection changes, replacement commands, failures and disposal cancel obsolete queued navigation. Unit tests compare reused-worker navigation with native commands, including mixed directions, wraparound, overlapping matches and zero-length expressions.\n\nThe independent `production source regex parity` slice compares counts and exact saved output with the installed CodeMirror commands for zero-length lookahead, case-sensitive and whole-word matching. A replacement exceeding two source-transfer chunks verifies continuation assembly without truncation. `production source regex lifecycle` injects worker-construction, error/decode-event and startup-timeout failures, requires actionable feedback and a successful retry, and preserves continued editing and exact Save bytes. A partial-delivery case lets one replacement chunk arrive before cancellation, then replays stale change/completion messages; no partial replacement may be committed. These are host-side fault injections, not actual browser-process crash or structured-clone failure evidence. Run both functional slices with:\n\n```sh\nSAMBEE_E2E_PRODUCTION=1 npm run test:e2e:all -- --grep 'production source regex (parity|lifecycle)' --workers=1\n```\n\nFor optional source renderer footprint diagnostics, use `SAMBEE_E2E_MEMORY=1` without timing enforcement, select `production source responsiveness`, and run the Chromium-only `npm run test:e2e`. The `source-renderer-memory` attachment records CDP renderer heap after explicit GC at pre-open, counted-results, post-replacement and post-close boundaries. Its historical 64 MiB assertion isn't a release criterion under D11. These are whole-viewer post-GC observations, not isolated result-array bytes, peak/worker/native memory or proof of leak-free cleanup. Staged/peak-memory limits and a fixed close/reopen cycle protocol aren't required. The source budget status is diagnostic in memory mode.\n\nFor a separate Chromium CPU diagnostic, use `SAMBEE_E2E_TRACE=1` without `SAMBEE_E2E_BUDGETS=1`, restrict the grep to `production source responsiveness long-line at 1543px`, and run `npm run test:e2e`. The `source-dispatch-cpu-profile` attachment contains the CDP CPU profile; its source budget status is diagnostic, never an acceptance pass. The source slice rejects combined profiling/GC and either diagnostic mode combined with timing enforcement.\n\nFor separate controlled-memory trials, add `SAMBEE_E2E_MEMORY=1` and restrict the existing matrix to the many-block fixture and Chromium. Release harness-held node references before post-GC sampling. Renderer heap excludes worker heaps and aggregate/native memory; a single close isn't repeated-close leak acceptance. Keep forced GC separate from responsiveness timing.\n\nFor diagnostic scheduling traces, add `SAMBEE_E2E_TRACE=1` to a single-fixture Chromium run. The `viewer-scheduling-trace` attachment contains a CDP timeline and V8 CPU profile. Align `sambee:viewer-trace:start` with browser timestamps; join CPU chunks by renderer PID and profile ID and count samples once. Firefox native profiling must use content-process User Timing markers rather than parent-only samples. Profiling adds overhead and isn't acceptance timing.\n\nTo isolate native table input from application work, run the existing proof from `frontend/`:\n\n```sh\nSAMBEE_NATIVE_TABLE_REPORT=/tmp/sambee-native-table node scripts/source-search-containment-proof.mjs --native-table\n```\n\nThis uses public CodeMirror/Lezer and `markdownTables` APIs at the approved demo URL, with an isolated HTML response and default package styling. It edits the middle cell of the fixed 2,400-row table at 1543x900 without React, application CSS, normalization, Save or workers. It requires exact complete native source, atomic full-table replacement spans, native undo/redo and disposal. Native table source uses `\u003cbr\u003e`; application canonicalization to `\u003cbr /\u003e` isn't part of this proof. Root state materialization and view-update intervals are reported separately; input-to-root includes scheduling and deferred publication, not just model CPU. The unminified desktop diagnostic isn't a production acceptance trial or a replacement for mobile, composition and lifecycle checks.\n\nThe optional report prefix writes per-engine JSON and the exact diagnostic bundle. For separate profiling, add `SAMBEE_E2E_TRACE=1` and configure `MOZ_PROFILER_STARTUP=1`, `MOZ_PROFILER_STARTUP_FILTERS=GeckoMain`, `MOZ_PROFILER_STARTUP_FEATURES=js,stackwalk,leaf` and `MOZ_PROFILER_SHUTDOWN` with an absolute output path. Chromium records input-only CPU samples; clip Firefox content-process samples between `sambee:native-table:input-start` and `sambee:native-table:input-end`, excluding construction and history checks. Profiling requires a report prefix and Firefox startup configuration; product-budget enforcement and controlled-GC modes are rejected. Inclusive model, parsing and native reflow samples overlap and mustn't be summed. Unclassified Chromium native samples aren't automatically package JavaScript CPU. Slow native input doesn't by itself establish slow atomic state application or justify private package patches, changed history, wrapping or selection semantics.\n\nCount assertions remain scoped to the existing search controls to avoid page-wide Playwright text caches inside measurement windows. Results are labelled `scoped-controls-v2`; older input figures aren't directly comparable. Handler-to-frame samples and synthetic event age don't establish hardware input-to-visible-paint latency. Removing the alternate renderer doesn't close any performance, memory or manual interaction gate.\n\n### Shared Highlighting Acceptance And Limitations\n\nThe shared-highlighting implementation was approved by the user for merge and rollout on 2026-10-24. Approval doesn't turn failed measurements into passes or establish support for untested devices. Keep original targets, raw verdicts and these scoped acceptance decisions together:\n\n| Decision | Accepted scope | Boundaries |\n|---|---|---|\n| D5 | Noticeable large atomic Replace All latency with visible busy feedback. | Preserve complete output, logical change mapping, one native transaction and undo/redo. Unrelated source-search or typing pauses aren't accepted by this decision. |\n| D6 | The recorded progressive prose/table preview-loading pauses: 19/24 trials above 50 ms, worst 128 ms; all complete within 1,110 ms. | These remain failed gap samples. Longer future delays and other workloads aren't covered. Asynchronous preview preparation remains declined. |\n| D8 | Responsiveness limitations of the existing Markdown table editor. | Table-component timing is diagnostic and non-blocking; exact input, Save, composition, history and cleanup remain required. |\n| D9 | Ten recorded Firefox many-block syntax-color samples at 1,511-1,579 ms against the 1,500 ms target. | All 120 cold/warm samples were collected; 110 meet that target. Full syntax preparation stays within 3,000 ms. No broader delay exception is implied. |\n| D10 | Four recorded Firefox desktop code-display gaps at 51-59 ms against 50 ms. | Preserve the raw failures. Additional delayed-image/font/resize and scroll-anchor test coverage was removed, not passed. Correct content, selection and scrolling remain required. |\n| D11 | Leak investigation and fixes for demonstrated unwanted retention, rather than quantitative memory acceptance. | Staged/peak-memory limits and fixed-cycle shutdown checks were removed, not passed. No exhaustive leak-free claim is made. |\n| D12 | Removal of real-phone and physical keyboard/IME acceptance, including phone print UI and hardware-response measurements. | This isn't verified device support. Automated keyboard/composition, exact editing/Save/recovery and desktop native/print correctness remain required. |\n\nBrowser-menu Find/reveal, OS clipboard, assistive-technology and physical-scrolling checks were confirmed complete by the user on 2026-10-23. Remaining Firefox PDF and desktop/physical printing checks were confirmed complete on 2026-10-24. These are user confirmations, not new automated measurements or a detailed device, browser, AT or printer support matrix. Don't reopen completed checks or rerun accepted timing failures solely to close a checklist; retest affected behavior after a relevant change or demonstrated regression.\n\nThe final editing checks cover theme changes followed by editing exit and Close, late worker results, distinct documents, captured-revision Save with newer dirty edits, failed writes and recovery/snapshot failures. Source-regex terminal cleanup detaches worker handlers, releases terminated workers and clears obsolete replacement buffers, while retaining buffers needed for a pending atomic apply. Ownership review and lifecycle assertions establish the investigated cleanup, not a heap-retention proof for every browser object.\n\nUse `PLAYWRIGHT_JSON_OUTPUT_FILE`, not `PLAYWRIGHT_JSON_OUTPUT_NAME`, for an explicit report path with the JSON reporter. Preserve complete identities, both engines, widths 1543/390, original workloads and three trials per timing identity. Recorded-report evaluation must retain failed samples and reject missing, duplicate, invalid, skipped or retried identities. Functional-only runs and tracing/GC diagnostics don't establish timing passes. Retain local reports before temporary-file cleanup; overlapping runs aren't additive test totals.\n\n### Responsive and Accessibility Rules\n\nThe centralized toolbar also encodes product behavior that should stay consistent across viewers.\n\n- filename display, optional filename adornments, and close behavior are shared\n- mobile layout uses safe-area-aware spacing and smaller controls\n- gallery arrows and desktop zoom controls are intentionally reduced on mobile, where gesture-based interaction is preferred\n- share is exposed as a mobile-first affordance, with optional early-intent warming through `onShareIntent`\n- buttons use explicit `aria-label` values and shortcut-oriented `title` text so the control surface remains navigable and self-describing\n- the shared search row manages focus when it opens and preserves consistent close behavior for toggle and Escape-driven exits\n\n### Legacy Components and Contributor Guidance\n\nLegacy `ImageControls.tsx` and `PDFControls.tsx` files still exist in the frontend tree, but `ViewerControls` is the current architectural direction and the shared component used by the active image, PDF, and Markdown viewers.\n\nIf you add another viewer or extend an existing one:\n\n- prefer extending `ViewerControlsConfig`, the relevant state interfaces, or the generic `actions` surface\n- keep viewer-specific logic in the viewer component rather than teaching `ViewerControls` about file-format internals\n- preserve shared mobile, accessibility, and search-panel behavior unless the product intentionally changes that contract\n- add or update focused tests in `frontend/src/components/Viewer/__tests__/ViewerControls.test.tsx` when the shared toolbar contract changes\n\n## Adding a New File Type Safely\n\nFile-type support is registry-driven. The safest way to add a new type is to treat backend and frontend changes as one contract update.\n\n### Main Files to Change\n\n| Path | Why it changes |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | declare extensions, MIME types, category, description, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | declare extensions, MIME types, category, viewer component, icon, color, and description |\n| `frontend/src/components/Viewer/` | add or reuse a viewer component when the type needs a dedicated preview surface |\n\nIf a file type is user-visible, update the published support docs that describe what Sambee can preview.\n\n### Quick Start for a New Image Format\n\nFor an image format such as JPEG XL, the minimum workflow is:\n\n1. add a `FileTypeDefinition` entry to the backend registry\n2. add the matching entry to the frontend registry\n3. decide whether the image is browser-native or requires server-side conversion\n4. keep extensions and MIME types identical across both registries\n5. run the viewer and backend validation checks\n\nBackend example:\n\n```python\nFileTypeDefinition(\n\t\textensions=(\".jxl\",),\n\t\tmime_types=(\"image/jxl\",),\n\t\tcategory=FileCategory.IMAGE,\n\t\trequires_conversion=True,\n\t\tdescription=\"JPEG XL Image\",\n)\n```\n\nFrontend example:\n\n```typescript\n{\n\textensions: [\".jxl\"],\n\tmimeTypes: [\"image/jxl\"],\n\tcategory: \"image\",\n\tviewerComponent: () =\u003e import(\"../components/Viewer/ImageViewer\"),\n\ticon: \"image\",\n\tcolor: \"#a855f7\",\n\tdescription: \"JPEG XL Image\",\n}\n```\n\nThat registry update is what drives MIME matching, icon treatment, viewer routing, and image-gallery inclusion.\n\n### Backend Registry Rules\n\nBackend file-type definitions must stay explicit and type-safe.\n\n- `extensions` are tuples with a leading dot, such as `(\".jpg\", \".jpeg\")`\n- `mime_types` are tuples of standard MIME strings\n- `category` uses `FileCategory` values such as `IMAGE`, `DOCUMENT`, `TEXT`, `VIDEO`, `AUDIO`, `ARCHIVE`, `CODE`, `SPREADSHEET`, or `OTHER`\n- `requires_conversion` matters for image formats that cannot be rendered directly by the browser\n- `description` should be the human-readable label contributors and users would expect\n\nHow to decide `requires_conversion`:\n\n- set it to `False` for browser-native formats such as PNG, JPEG, GIF, WebP, SVG, and AVIF\n- set it to `True` for formats with limited browser support or formats that are not practical to render directly, such as TIFF, HEIC, BMP, JPEG 2000, or JPEG XL when browser support is not sufficient for the product baseline\n\n### Frontend Registry Rules\n\nFrontend file-type definitions control how the browser app presents the file.\n\n- keep `extensions` and `mimeTypes` aligned with the backend registry\n- set `viewerComponent` to the shared viewer that should render the type\n- choose an icon that matches the product language for that file category\n- choose a color that distinguishes the format without inventing a new palette on every addition\n\nFor image formats, reusing `ImageViewer` is usually enough. For non-image formats, you may need a dedicated viewer such as `PdfViewer`, `VideoViewer`, `AudioViewer`, or `TextViewer`.\n\n### Non-Image File Types\n\nThe overall process is the same for documents, video, audio, text, archives, and code files.\n\n1. add the backend registry entry\n2. add the frontend registry entry\n3. create or reuse the viewer component when preview support exists\n4. verify the file icon, viewer routing, and download behavior\n\nFor non-image files, `requires_conversion` is usually `False`. The main design question is whether the product has a viewer component for that category or should fall back to download-only behavior.\n\n### Integration Checklist\n\nUse this checklist before you consider the file type integrated:\n\n- backend registry entry added\n- frontend registry entry added\n- extensions and MIME types match exactly across both registries\n- browser-native versus converted-image behavior decided intentionally\n- viewer component chosen or added\n- icon and color treatment chosen\n- user-visible support docs updated if the file type changes what Sambee can preview\n\n### Testing Checklist\n\nAfter the registry change, verify:\n\n- icon display in the file browser\n- file opening in the expected viewer\n- shared toolbar behavior if the preview uses `ViewerControls`\n- conversion output if the format is server-converted\n- gallery inclusion for image formats\n- MIME type behavior across extension variants such as upper-case filenames\n- download behavior with the correct MIME type\n- mobile and tablet behavior when the preview is expected to work there\n\nFor server-converted formats, also verify:\n\n- the backend returns the converted MIME type you expect\n- transparency-sensitive formats still render correctly\n- resizing or quality settings do not degrade the preview contract unexpectedly\n- environment-specific format support failures surface in a controlled way\n\nFor preprocessable formats, also verify:\n\n- the registry recognizes the extension regardless of case and leading-dot differences\n- the expected preprocessor is selected for that format\n- missing external-tool support fails cleanly\n- validation and timeout rules behave as intended under bad inputs and slow conversions\n\n### Architecture Notes\n\nThese helper functions are the practical integration points contributors usually touch:\n\n- backend: `get_mime_type`, `needs_processing`, `is_image_file`, `get_file_type_by_extension`, `get_file_type_by_mime`\n- frontend: `getViewerComponent`, `isImageFile`, `getFileIcon`, `getFileTypeByExtension`, `getFileTypeByMime`\n\nAt runtime, the flow is:\n\n1. the backend lists files and assigns MIME information\n2. the frontend receives `FileInfo` data with that MIME information\n3. the frontend chooses icon treatment from filename and type rules\n4. the frontend selects the viewer from MIME and file-type data\n5. the backend routes convertible images through the image-conversion pipeline when needed\n\nThe frontend side still has work to do even when the backend owns the conversion:\n\n- viewer MIME recognition must include the input formats the backend classifies as previewable\n- file-type icon and color treatment must still reflect the original file type rather than the converted transport format\n- browser-side fallback MIME logic must not drift from the backend contract in ways that hide conversion bugs\n\n### Operational Characteristics\n\nServer-side conversion changes the runtime profile of preview requests.\n\n- large images can produce short CPU spikes during decode and encode\n- memory usage can rise well above compressed input size while the image is fully decoded\n- SMB-backed reads add their own latency before conversion even starts\n\nThat is why preview regressions for large HEIC or TIFF files often need both backend and user-facing verification.\n\n### Future Extension Points\n\nThe current conversion path leaves room for later enhancements such as:\n\n- caching converted preview outputs\n- queueing especially large conversions\n- dedicated thumbnail generation\n- richer multi-page image handling\n- conversion metrics for operational monitoring\n\nThose are extension points, not assumptions the current product already guarantees.\n\nThe highest-risk mistake is still registry drift. If the backend and frontend disagree about extensions or MIME types, preview behavior becomes unreliable in ways that are easy to miss until users hit them.\n\n## Common Failure Modes\n\n- backend and frontend MIME types do not match\n- a format is marked browser-native when it really needs conversion\n- a viewer component is not registered even though the type is recognized\n- a conversion change improves one format but breaks gallery behavior, download semantics, or mobile viewing\n\n## Validation Expectations\n\nWhen you change viewer or file-type behavior, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npm run typecheck\ncd frontend \u0026\u0026 npm run lint\ncd backend \u0026\u0026 pytest -v\n```\n\nIf the change is image-conversion-specific, include the relevant backend tests around image conversion and preview behavior.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Viewer Architecture and Preview Contracts\"\n+++\n\nPreview behavior in Sambee is a cross-boundary contract, not just a frontend component choice.\n\n## The Core Contract\n\nThe browser app decides how to render a file based on metadata and file-type information, but that depends on server-side classification staying aligned.\n\nThree rules matter most:\n\n- the backend and frontend file-type registries must describe the same extensions and MIME types\n- the backend decides whether an image format needs server-side conversion for browser compatibility\n- the frontend chooses the right viewer component and file icon based on the effective file type and MIME information it receives\n\n## Where the Main Decisions Live\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | backend source of truth for extensions, MIME types, categories, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | frontend source of truth for extensions, MIME types, categories, viewer components, icons, and colors |\n| `frontend/src/components/Viewer/` | viewer components and shared viewer UI |\n| `backend/app/services/image_converter.py` | server-side conversion for non-browser-native image formats |\n\n## Viewer Selection Model\n\nAt a high level, the preview pipeline works like this:\n\n1. the backend determines file category and MIME behavior\n2. the backend decides whether the file can stream as-is or needs image conversion\n3. the frontend maps the file type to the appropriate viewer component\n4. the shared viewer controls keep the toolbar and common behavior consistent across viewers\n\nThat is why a file-type change almost always touches both backend and frontend code.\n\n## Browser-Native Versus Server-Converted Images\n\nSambee supports both browser-native formats and formats that need server-side conversion.\n\n- browser-native formats can be sent to the viewer directly\n- non-browser-native image formats are converted on the server before the browser renders them\n- special cases such as transparency preservation can change the output format choice\n\nIf you change conversion rules, you are changing a product contract, not just an implementation detail.\n\n### Server-Side Conversion Contract\n\nThe conversion path is owned by `backend/app/services/image_converter.py` and is exercised through the viewer API.\n\nThe backend conversion service is responsible for:\n\n- deciding whether an image needs processing\n- converting unsupported or impractical browser formats into a viewer-safe output format\n- preserving transparency where the output contract requires it\n- applying optional downscaling so one preview request cannot explode memory usage casually\n- returning enough metadata for the viewer endpoint to send the correct MIME type back to the browser\n\nRepresentative service responsibilities include:\n\n- `needs_processing(filename)`\n- `convert_image_for_viewer(...)`\n- `is_image_file(filename)`\n- `get_image_info(...)`\n\nThe viewer endpoint then follows this rule:\n\n- if the image can stream safely as-is, return a streaming response\n- if it requires conversion, read it, convert it, and return the converted bytes with the converted MIME type\n\nThat means preview behavior for formats such as TIFF, HEIC, BMP, ICO, and similar formats depends on backend conversion policy, not just on frontend MIME recognition.\n\n### Local-Drive Preview Policy\n\nThe Companion serves local-drive files and archive members as raw bytes. It does not copy local content to the backend for processing and does not bundle the backend image or PDF processing stack.\n\n- Browser-native images, text files, and original PDFs can preview from their raw local bytes.\n- Image formats that require server-side conversion, such as TIFF, HEIC, PSD, JPEG XL, and scientific image formats, show an explicit preview-unavailable state for local drives.\n- Image resizing and PDF compatibility normalization are unavailable for local drives.\n- Downloading and opening the original file locally remain available when a local preview is unavailable.\n\nThe frontend resolves these capabilities before making a local viewer request. Local archive-member requests use the Companion's strict raw-stream contract, while SMB archive-member requests retain the full conversion and PDF-normalization request parameters.\n\n### Output Format Rules\n\nThe backend does not always convert everything to the same output type.\n\n- JPEG is the common output for opaque images\n- PNG remains important when transparency must be preserved\n- ICO-like transparency handling is therefore different from ordinary opaque-photo conversion\n- alpha-bearing formats converted to JPEG need explicit compositing behavior rather than silent accidental loss\n\nIf you change those rules, check both visual correctness and user-facing assumptions such as download behavior and gallery continuity.\n\n### Current Format-Specific Preview Semantics\n\nSeveral converted-image families have product-specific preview semantics that contributors should preserve unless the product intentionally changes.\n\n- multi-page TIFF currently previews the first page rather than exposing a document-style page stack\n- PSD and PSB preview the flattened composite instead of surfacing layer-edit semantics through the browser viewer\n- EPS and AI are rasterized through the preprocessing path at high quality, currently using the 300 DPI rendering baseline\n- HDR-oriented formats such as EXR and Radiance HDR are tone-mapped into ordinary browser-display output\n- whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF preview as an overview or first practical pyramid level rather than as a full pathology viewer\n- FITS and similar scientific-image formats apply visibility scaling so low-level pixel values become inspectable in a normal browser image surface\n\nThese are not accidental implementation details. They define what users should expect from preview and therefore belong to the product contract.\n\n### Resizing and Resource Limits\n\nServer-side conversion can consume significant memory because the file must be read, decoded, and re-encoded.\n\nThe current contract therefore includes:\n\n- configurable JPEG-quality behavior\n- maximum-dimension downscaling to avoid unbounded preview size\n- backend-side protection against excessive memory usage from large source images\n\nContributors should treat those limits as operational safety controls, not as arbitrary defaults.\n\n### Dependency and Environment Expectations\n\nThe conversion path depends on reviewed Python and system-image libraries.\n\nThat includes the normal image stack plus HEIC/HEIF support through the reviewed dependency chain and corresponding system libraries in the container or runtime image.\n\nWhen conversion support seems to disappear unexpectedly, check:\n\n- the backend Python dependency set\n- the container or host system-image libraries\n- whether the format-specific support was actually installed in the current environment\n\n### Preprocessor Registry for Exotic Formats\n\nSome formats need a preprocessing step before the normal conversion path can handle them at all.\n\nThat registry lives in:\n\n- `backend/app/services/preprocessor.py`\n\nIt is consumed by:\n\n- `backend/app/services/image_converter.py`\n\nThe preprocessor layer exists for formats that libvips should not or cannot decode directly for Sambee's preview contract.\n\nCurrent registered formats route through the ImageMagick-backed preprocessor:\n\n- `.psd`\n- `.psb`\n- `.eps`\n- `.ai`\n\nThe registry is the single source of truth for which extensions require preprocessing before the final viewer-safe conversion step.\n\nFor the backend service architecture behind that path, continue to [Image Preprocessing and Conversion Pipeline](../../backend-architecture/image-preprocessing-and-conversion-pipeline/).\n\nRepresentative registry operations include:\n\n- `PreprocessorRegistry.requires_preprocessing(extension)`\n- `PreprocessorRegistry.get_preprocessor_for_format(extension)`\n- `PreprocessorRegistry.get_supported_formats()`\n- `PreprocessorRegistry.register_format(extension, preprocessor_class)`\n\n### Preprocessor Design Rules\n\nThe preprocessor layer has its own constraints:\n\n- one registry entry per preprocessable extension\n- direct in-memory conversion to the final browser-ready format rather than chained intermediate formats\n- no shell-mediated fallback chain logic in the registry itself\n- input validation and timeout enforcement happen in the preprocessor layer\n- failures should surface as explicit preprocessing or conversion errors rather than silent format drift\n\nThe main abstraction is `PreprocessorInterface`, with `ImageMagickPreprocessor` as the current built-in implementation.\n\n### Adding a New Preprocessed Format\n\nIf a new format cannot be handled by the normal conversion stack directly:\n\n1. implement a `PreprocessorInterface` subclass if the existing preprocessor is not appropriate\n2. register the extension in `PreprocessorRegistry`\n3. add or update file-type metadata if the format becomes user-visible in preview flows\n4. add tests for format recognition, tool availability, validation, and successful conversion\n\nDo not treat preprocessable formats as ordinary file-type additions. They change the backend conversion pipeline itself.\n\n### Error Surface Contributors Must Preserve\n\nConversion failures are user-visible API behavior, not internal-only exceptions.\n\nTypical outcomes include:\n\n- not implemented when the current environment lacks support for a format family\n- unprocessable-content style failures when the file is corrupt or cannot be decoded\n- ordinary backend failures when an unexpected exception escapes the conversion path\n\nThat means error wording, status behavior, and frontend fallback behavior should be reviewed together.\n\n## Shared Viewer UI\n\nThe main viewer toolbar is intentionally centralized in `frontend/src/components/Viewer/ViewerControls.tsx`.\n\nThis is no longer just an image-and-PDF convenience component. It is the canonical control surface for the current full-screen image, PDF, and Markdown viewers.\n\n- shared toolbar layout, styling, keyboard-tooltip behavior, and responsive behavior live in `ViewerControls`\n- each viewer turns features on through configuration and passes only the state objects it needs\n- future viewers should reuse that control shell where possible instead of creating another top-level toolbar implementation\n\n### Control-Surface Model\n\n`ViewerControls` uses a feature-flag configuration plus typed state objects.\n\nThe configuration currently enables these capability groups:\n\n- `navigation` for gallery-style previous and next navigation\n- `pageNavigation` for PDF page input and page stepping\n- `zoom` for viewer-managed zoom actions\n- `rotation` for image and PDF rotation actions\n- `search` for the shared search row and match navigation affordances\n- `download` for explicit download actions\n- `share` for mobile-first share actions\n\nThe component then accepts matching state surfaces:\n\n- `NavigationState` for item index, total items, and next or previous handlers\n- `PageNavigationState` for current page, total pages, and page-change handling\n- `ZoomState` for zoom-in and zoom-out handlers\n- `RotationState` for rotate-left and rotate-right handlers\n- `SearchState` for search text, match counts, search-panel state, open or close callbacks, and viewer-specific search navigation\n\nThat split matters because `ViewerControls` owns the common UI, but it does not own viewer logic. It renders controls and delegates behavior back to the viewer that actually knows how to navigate pages, zoom, rotate, or search.\n\n### Current Consumers\n\nThe current shared-toolbar consumers are:\n\n- `ImageViewer`, which enables gallery navigation, zoom, rotation, download, and optional mobile share\n- `PDFViewer`, which enables page navigation, zoom, rotation, search, download, and optional mobile share\n- `MarkdownViewer`, which reuses the same shell for download, optional mobile share, shared search UI, and viewer-specific action buttons such as editing flows\n\n`ViewerControls` also supports generic toolbar actions through the `actions` prop, which can render either text buttons or icon buttons. That is what allows Markdown-specific actions to live inside the same shared toolbar instead of forcing a second toolbar implementation.\n\n### Search UI Versus Search Engine\n\nThe search row is shared, but the search backend is viewer-specific.\n\n- `PDFViewer` wires the search controls to PDF text extraction, page-aware match tracking, and PDF-specific next or previous navigation\n- rendered Markdown and other rendered text views can route search through the DOM text-search utility in `frontend/src/utils/domTextSearch.ts`\n- Markdown edit mode does not reuse the rendered-view DOM search implementation; it bridges the same outer toolbar UI into the editor-specific search state and commands instead\n\nThat separation is an important contract: contributors should reuse the shared search UI when possible, but should not assume every viewer can use the same search implementation under the hood.\n\n### Responsive and Accessibility Rules\n\nThe centralized toolbar also encodes product behavior that should stay consistent across viewers.\n\n- filename display, optional filename adornments, and close behavior are shared\n- mobile layout uses safe-area-aware spacing and smaller controls\n- gallery arrows and desktop zoom controls are intentionally reduced on mobile, where gesture-based interaction is preferred\n- share is exposed as a mobile-first affordance, with optional early-intent warming through `onShareIntent`\n- buttons use explicit `aria-label` values and shortcut-oriented `title` text so the control surface remains navigable and self-describing\n- the shared search row manages focus when it opens and preserves consistent close behavior for toggle and Escape-driven exits\n\n### Legacy Components and Contributor Guidance\n\nLegacy `ImageControls.tsx` and `PDFControls.tsx` files still exist in the frontend tree, but `ViewerControls` is the current architectural direction and the shared component used by the active image, PDF, and Markdown viewers.\n\nIf you add another viewer or extend an existing one:\n\n- prefer extending `ViewerControlsConfig`, the relevant state interfaces, or the generic `actions` surface\n- keep viewer-specific logic in the viewer component rather than teaching `ViewerControls` about file-format internals\n- preserve shared mobile, accessibility, and search-panel behavior unless the product intentionally changes that contract\n- add or update focused tests in `frontend/src/components/Viewer/__tests__/ViewerControls.test.tsx` when the shared toolbar contract changes\n\n## Adding a New File Type Safely\n\nFile-type support is registry-driven. The safest way to add a new type is to treat backend and frontend changes as one contract update.\n\n### Main Files to Change\n\n| Path | Why it changes |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | declare extensions, MIME types, category, description, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | declare extensions, MIME types, category, viewer component, icon, color, and description |\n| `frontend/src/components/Viewer/` | add or reuse a viewer component when the type needs a dedicated preview surface |\n\nIf a file type is user-visible, update the published support docs that describe what Sambee can preview.\n\n### Quick Start for a New Image Format\n\nFor an image format such as JPEG XL, the minimum workflow is:\n\n1. add a `FileTypeDefinition` entry to the backend registry\n2. add the matching entry to the frontend registry\n3. decide whether the image is browser-native or requires server-side conversion\n4. keep extensions and MIME types identical across both registries\n5. run the viewer and backend validation checks\n\nBackend example:\n\n```python\nFileTypeDefinition(\n\t\textensions=(\".jxl\",),\n\t\tmime_types=(\"image/jxl\",),\n\t\tcategory=FileCategory.IMAGE,\n\t\trequires_conversion=True,\n\t\tdescription=\"JPEG XL Image\",\n)\n```\n\nFrontend example:\n\n```typescript\n{\n\textensions: [\".jxl\"],\n\tmimeTypes: [\"image/jxl\"],\n\tcategory: \"image\",\n\tviewerComponent: () =\u003e import(\"../components/Viewer/ImageViewer\"),\n\ticon: \"image\",\n\tcolor: \"#a855f7\",\n\tdescription: \"JPEG XL Image\",\n}\n```\n\nThat registry update is what drives MIME matching, icon treatment, viewer routing, and image-gallery inclusion.\n\n### Backend Registry Rules\n\nBackend file-type definitions must stay explicit and type-safe.\n\n- `extensions` are tuples with a leading dot, such as `(\".jpg\", \".jpeg\")`\n- `mime_types` are tuples of standard MIME strings\n- `category` uses `FileCategory` values such as `IMAGE`, `DOCUMENT`, `TEXT`, `VIDEO`, `AUDIO`, `ARCHIVE`, `CODE`, `SPREADSHEET`, or `OTHER`\n- `requires_conversion` matters for image formats that cannot be rendered directly by the browser\n- `description` should be the human-readable label contributors and users would expect\n\nHow to decide `requires_conversion`:\n\n- set it to `False` for browser-native formats such as PNG, JPEG, GIF, WebP, SVG, and AVIF\n- set it to `True` for formats with limited browser support or formats that are not practical to render directly, such as TIFF, HEIC, BMP, JPEG 2000, or JPEG XL when browser support is not sufficient for the product baseline\n\n### Frontend Registry Rules\n\nFrontend file-type definitions control how the browser app presents the file.\n\n- keep `extensions` and `mimeTypes` aligned with the backend registry\n- set `viewerComponent` to the shared viewer that should render the type\n- choose an icon that matches the product language for that file category\n- choose a color that distinguishes the format without inventing a new palette on every addition\n\nFor image formats, reusing `ImageViewer` is usually enough. For non-image formats, you may need a dedicated viewer such as `PdfViewer`, `VideoViewer`, `AudioViewer`, or `TextViewer`.\n\n### Non-Image File Types\n\nThe overall process is the same for documents, video, audio, text, archives, and code files.\n\n1. add the backend registry entry\n2. add the frontend registry entry\n3. create or reuse the viewer component when preview support exists\n4. verify the file icon, viewer routing, and download behavior\n\nFor non-image files, `requires_conversion` is usually `False`. The main design question is whether the product has a viewer component for that category or should fall back to download-only behavior.\n\n### Integration Checklist\n\nUse this checklist before you consider the file type integrated:\n\n- backend registry entry added\n- frontend registry entry added\n- extensions and MIME types match exactly across both registries\n- browser-native versus converted-image behavior decided intentionally\n- viewer component chosen or added\n- icon and color treatment chosen\n- user-visible support docs updated if the file type changes what Sambee can preview\n\n### Testing Checklist\n\nAfter the registry change, verify:\n\n- icon display in the file browser\n- file opening in the expected viewer\n- shared toolbar behavior if the preview uses `ViewerControls`\n- conversion output if the format is server-converted\n- gallery inclusion for image formats\n- MIME type behavior across extension variants such as upper-case filenames\n- download behavior with the correct MIME type\n- mobile and tablet behavior when the preview is expected to work there\n\nFor server-converted formats, also verify:\n\n- the backend returns the converted MIME type you expect\n- transparency-sensitive formats still render correctly\n- resizing or quality settings do not degrade the preview contract unexpectedly\n- environment-specific format support failures surface in a controlled way\n\nFor preprocessable formats, also verify:\n\n- the registry recognizes the extension regardless of case and leading-dot differences\n- the expected preprocessor is selected for that format\n- missing external-tool support fails cleanly\n- validation and timeout rules behave as intended under bad inputs and slow conversions\n\n### Architecture Notes\n\nThese helper functions are the practical integration points contributors usually touch:\n\n- backend: `get_mime_type`, `needs_processing`, `is_image_file`, `get_file_type_by_extension`, `get_file_type_by_mime`\n- frontend: `getViewerComponent`, `isImageFile`, `getFileIcon`, `getFileTypeByExtension`, `getFileTypeByMime`\n\nAt runtime, the flow is:\n\n1. the backend lists files and assigns MIME information\n2. the frontend receives `FileInfo` data with that MIME information\n3. the frontend chooses icon treatment from filename and type rules\n4. the frontend selects the viewer from MIME and file-type data\n5. the backend routes convertible images through the image-conversion pipeline when needed\n\nThe frontend side still has work to do even when the backend owns the conversion:\n\n- viewer MIME recognition must include the input formats the backend classifies as previewable\n- file-type icon and color treatment must still reflect the original file type rather than the converted transport format\n- browser-side fallback MIME logic must not drift from the backend contract in ways that hide conversion bugs\n\n### Operational Characteristics\n\nServer-side conversion changes the runtime profile of preview requests.\n\n- large images can produce short CPU spikes during decode and encode\n- memory usage can rise well above compressed input size while the image is fully decoded\n- SMB-backed reads add their own latency before conversion even starts\n\nThat is why preview regressions for large HEIC or TIFF files often need both backend and user-facing verification.\n\n### Future Extension Points\n\nThe current conversion path leaves room for later enhancements such as:\n\n- caching converted preview outputs\n- queueing especially large conversions\n- dedicated thumbnail generation\n- richer multi-page image handling\n- conversion metrics for operational monitoring\n\nThose are extension points, not assumptions the current product already guarantees.\n\nThe highest-risk mistake is still registry drift. If the backend and frontend disagree about extensions or MIME types, preview behavior becomes unreliable in ways that are easy to miss until users hit them.\n\n## Common Failure Modes\n\n- backend and frontend MIME types do not match\n- a format is marked browser-native when it really needs conversion\n- a viewer component is not registered even though the type is recognized\n- a conversion change improves one format but breaks gallery behavior, download semantics, or mobile viewing\n\n## Validation Expectations\n\nWhen you change viewer or file-type behavior, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd backend \u0026\u0026 pytest -v\n```\n\nIf the change is image-conversion-specific, include the relevant backend tests around image conversion and preview behavior.\n", "0.8": "+++\ntitle = \"Viewer Architecture and Preview Contracts\"\n+++\n\nPreview behavior in Sambee is a cross-boundary contract, not just a frontend component choice.\n\n## The Core Contract\n\nThe browser app decides how to render a file based on metadata and file-type information, but that depends on server-side classification staying aligned.\n\nThree rules matter most:\n\n- the backend and frontend file-type registries must describe the same extensions and MIME types\n- the backend decides whether an image format needs server-side conversion for browser compatibility\n- the frontend chooses the right viewer component and file icon based on the effective file type and MIME information it receives\n\n## Where the Main Decisions Live\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | backend source of truth for extensions, MIME types, categories, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | frontend source of truth for extensions, MIME types, categories, viewer components, icons, and colors |\n| `frontend/src/components/Viewer/` | viewer components and shared viewer UI |\n| `backend/app/services/image_converter.py` | server-side conversion for non-browser-native image formats |\n\n## Viewer Selection Model\n\nAt a high level, the preview pipeline works like this:\n\n1. the backend determines file category and MIME behavior\n2. the backend decides whether the file can stream as-is or needs image conversion\n3. the frontend maps the file type to the appropriate viewer component\n4. the shared viewer controls keep the toolbar and common behavior consistent across viewers\n\nThat is why a file-type change almost always touches both backend and frontend code.\n\n## Browser-Native Versus Server-Converted Images\n\nSambee supports both browser-native formats and formats that need server-side conversion.\n\n- browser-native formats can be sent to the viewer directly\n- non-browser-native image formats are converted on the server before the browser renders them\n- special cases such as transparency preservation can change the output format choice\n\nIf you change conversion rules, you are changing a product contract, not just an implementation detail.\n\n### Server-Side Conversion Contract\n\nThe conversion path is owned by `backend/app/services/image_converter.py` and is exercised through the viewer API.\n\nThe backend conversion service is responsible for:\n\n- deciding whether an image needs processing\n- converting unsupported or impractical browser formats into a viewer-safe output format\n- preserving transparency where the output contract requires it\n- applying optional downscaling so one preview request cannot explode memory usage casually\n- returning enough metadata for the viewer endpoint to send the correct MIME type back to the browser\n\nRepresentative service responsibilities include:\n\n- `needs_processing(filename)`\n- `convert_image_for_viewer(...)`\n- `is_image_file(filename)`\n- `get_image_info(...)`\n\nThe viewer endpoint then follows this rule:\n\n- if the image can stream safely as-is, return a streaming response\n- if it requires conversion, read it, convert it, and return the converted bytes with the converted MIME type\n\nThat means preview behavior for formats such as TIFF, HEIC, BMP, ICO, and similar formats depends on backend conversion policy, not just on frontend MIME recognition.\n\n### Local-Drive Preview Policy\n\nThe Companion serves local-drive files and archive members as raw bytes. It does not copy local content to the backend for processing and does not bundle the backend image or PDF processing stack.\n\n- Browser-native images, text files, and original PDFs can preview from their raw local bytes.\n- Image formats that require server-side conversion, such as TIFF, HEIC, PSD, JPEG XL, and scientific image formats, show an explicit preview-unavailable state for local drives.\n- Image resizing and PDF compatibility normalization are unavailable for local drives.\n- Downloading and opening the original file locally remain available when a local preview is unavailable.\n\nThe frontend resolves these capabilities before making a local viewer request. Local archive-member requests use the Companion's strict raw-stream contract, while SMB archive-member requests retain the full conversion and PDF-normalization request parameters.\n\n### Output Format Rules\n\nThe backend does not always convert everything to the same output type.\n\n- JPEG is the common output for opaque images\n- PNG remains important when transparency must be preserved\n- ICO-like transparency handling is therefore different from ordinary opaque-photo conversion\n- alpha-bearing formats converted to JPEG need explicit compositing behavior rather than silent accidental loss\n\nIf you change those rules, check both visual correctness and user-facing assumptions such as download behavior and gallery continuity.\n\n### Current Format-Specific Preview Semantics\n\nSeveral converted-image families have product-specific preview semantics that contributors should preserve unless the product intentionally changes.\n\n- multi-page TIFF currently previews the first page rather than exposing a document-style page stack\n- PSD and PSB preview the flattened composite instead of surfacing layer-edit semantics through the browser viewer\n- EPS and AI are rasterized through the preprocessing path at high quality, currently using the 300 DPI rendering baseline\n- HDR-oriented formats such as EXR and Radiance HDR are tone-mapped into ordinary browser-display output\n- whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF preview as an overview or first practical pyramid level rather than as a full pathology viewer\n- FITS and similar scientific-image formats apply visibility scaling so low-level pixel values become inspectable in a normal browser image surface\n\nThese are not accidental implementation details. They define what users should expect from preview and therefore belong to the product contract.\n\n### Resizing and Resource Limits\n\nServer-side conversion can consume significant memory because the file must be read, decoded, and re-encoded.\n\nThe current contract therefore includes:\n\n- configurable JPEG-quality behavior\n- maximum-dimension downscaling to avoid unbounded preview size\n- backend-side protection against excessive memory usage from large source images\n\nContributors should treat those limits as operational safety controls, not as arbitrary defaults.\n\n### Dependency and Environment Expectations\n\nThe conversion path depends on reviewed Python and system-image libraries.\n\nThat includes the normal image stack plus HEIC/HEIF support through the reviewed dependency chain and corresponding system libraries in the container or runtime image.\n\nWhen conversion support seems to disappear unexpectedly, check:\n\n- the backend Python dependency set\n- the container or host system-image libraries\n- whether the format-specific support was actually installed in the current environment\n\n### Preprocessor Registry for Exotic Formats\n\nSome formats need a preprocessing step before the normal conversion path can handle them at all.\n\nThat registry lives in:\n\n- `backend/app/services/preprocessor.py`\n\nIt is consumed by:\n\n- `backend/app/services/image_converter.py`\n\nThe preprocessor layer exists for formats that libvips should not or cannot decode directly for Sambee's preview contract.\n\nCurrent registered formats route through the ImageMagick-backed preprocessor:\n\n- `.psd`\n- `.psb`\n- `.eps`\n- `.ai`\n\nThe registry is the single source of truth for which extensions require preprocessing before the final viewer-safe conversion step.\n\nFor the backend service architecture behind that path, continue to [Image Preprocessing and Conversion Pipeline](../../backend-architecture/image-preprocessing-and-conversion-pipeline/).\n\nRepresentative registry operations include:\n\n- `PreprocessorRegistry.requires_preprocessing(extension)`\n- `PreprocessorRegistry.get_preprocessor_for_format(extension)`\n- `PreprocessorRegistry.get_supported_formats()`\n- `PreprocessorRegistry.register_format(extension, preprocessor_class)`\n\n### Preprocessor Design Rules\n\nThe preprocessor layer has its own constraints:\n\n- one registry entry per preprocessable extension\n- direct in-memory conversion to the final browser-ready format rather than chained intermediate formats\n- no shell-mediated fallback chain logic in the registry itself\n- input validation and timeout enforcement happen in the preprocessor layer\n- failures should surface as explicit preprocessing or conversion errors rather than silent format drift\n\nThe main abstraction is `PreprocessorInterface`, with `ImageMagickPreprocessor` as the current built-in implementation.\n\n### Adding a New Preprocessed Format\n\nIf a new format cannot be handled by the normal conversion stack directly:\n\n1. implement a `PreprocessorInterface` subclass if the existing preprocessor is not appropriate\n2. register the extension in `PreprocessorRegistry`\n3. add or update file-type metadata if the format becomes user-visible in preview flows\n4. add tests for format recognition, tool availability, validation, and successful conversion\n\nDo not treat preprocessable formats as ordinary file-type additions. They change the backend conversion pipeline itself.\n\n### Error Surface Contributors Must Preserve\n\nConversion failures are user-visible API behavior, not internal-only exceptions.\n\nTypical outcomes include:\n\n- not implemented when the current environment lacks support for a format family\n- unprocessable-content style failures when the file is corrupt or cannot be decoded\n- ordinary backend failures when an unexpected exception escapes the conversion path\n\nThat means error wording, status behavior, and frontend fallback behavior should be reviewed together.\n\n## Shared Viewer UI\n\nThe main viewer toolbar is intentionally centralized in `frontend/src/components/Viewer/ViewerControls.tsx`.\n\nThis is no longer just an image-and-PDF convenience component. It is the canonical control surface for the current full-screen image, PDF, and Markdown viewers.\n\n- shared toolbar layout, styling, keyboard-tooltip behavior, and responsive behavior live in `ViewerControls`\n- each viewer turns features on through configuration and passes only the state objects it needs\n- future viewers should reuse that control shell where possible instead of creating another top-level toolbar implementation\n\n### Control-Surface Model\n\n`ViewerControls` uses a feature-flag configuration plus typed state objects.\n\nThe configuration currently enables these capability groups:\n\n- `navigation` for gallery-style previous and next navigation\n- `pageNavigation` for PDF page input and page stepping\n- `zoom` for viewer-managed zoom actions\n- `rotation` for image and PDF rotation actions\n- `search` for the shared search row and match navigation affordances\n- `download` for explicit download actions\n- `share` for mobile-first share actions\n\nThe component then accepts matching state surfaces:\n\n- `NavigationState` for item index, total items, and next or previous handlers\n- `PageNavigationState` for current page, total pages, and page-change handling\n- `ZoomState` for zoom-in and zoom-out handlers\n- `RotationState` for rotate-left and rotate-right handlers\n- `SearchState` for search text, match counts, search-panel state, open or close callbacks, and viewer-specific search navigation\n\nThat split matters because `ViewerControls` owns the common UI, but it does not own viewer logic. It renders controls and delegates behavior back to the viewer that actually knows how to navigate pages, zoom, rotate, or search.\n\n### Current Consumers\n\nThe current shared-toolbar consumers are:\n\n- `ImageViewer`, which enables gallery navigation, zoom, rotation, download, and optional mobile share\n- `PDFViewer`, which enables page navigation, zoom, rotation, search, download, and optional mobile share\n- `MarkdownViewer`, which reuses the same shell for download, optional mobile share, shared search UI, and viewer-specific action buttons such as editing flows\n\n`ViewerControls` also supports generic toolbar actions through the `actions` prop, which can render either text buttons or icon buttons. That is what allows Markdown-specific actions to live inside the same shared toolbar instead of forcing a second toolbar implementation.\n\n### Search UI Versus Search Engine\n\nThe search row is shared, but the search backend is viewer-specific.\n\n- `PDFViewer` wires the search controls to PDF text extraction, page-aware match tracking, and PDF-specific next or previous navigation\n- rendered Markdown and other rendered text views can route search through the DOM text-search utility in `frontend/src/utils/domTextSearch.ts`\n- Markdown edit mode does not reuse the rendered-view DOM search implementation; it bridges the same outer toolbar UI into the editor-specific search state and commands instead\n\nThat separation is an important contract: contributors should reuse the shared search UI when possible, but should not assume every viewer can use the same search implementation under the hood.\n\n### Responsive and Accessibility Rules\n\nThe centralized toolbar also encodes product behavior that should stay consistent across viewers.\n\n- filename display, optional filename adornments, and close behavior are shared\n- mobile layout uses safe-area-aware spacing and smaller controls\n- gallery arrows and desktop zoom controls are intentionally reduced on mobile, where gesture-based interaction is preferred\n- share is exposed as a mobile-first affordance, with optional early-intent warming through `onShareIntent`\n- buttons use explicit `aria-label` values and shortcut-oriented `title` text so the control surface remains navigable and self-describing\n- the shared search row manages focus when it opens and preserves consistent close behavior for toggle and Escape-driven exits\n\n### Legacy Components and Contributor Guidance\n\nLegacy `ImageControls.tsx` and `PDFControls.tsx` files still exist in the frontend tree, but `ViewerControls` is the current architectural direction and the shared component used by the active image, PDF, and Markdown viewers.\n\nIf you add another viewer or extend an existing one:\n\n- prefer extending `ViewerControlsConfig`, the relevant state interfaces, or the generic `actions` surface\n- keep viewer-specific logic in the viewer component rather than teaching `ViewerControls` about file-format internals\n- preserve shared mobile, accessibility, and search-panel behavior unless the product intentionally changes that contract\n- add or update focused tests in `frontend/src/components/Viewer/__tests__/ViewerControls.test.tsx` when the shared toolbar contract changes\n\n## Adding a New File Type Safely\n\nFile-type support is registry-driven. The safest way to add a new type is to treat backend and frontend changes as one contract update.\n\n### Main Files to Change\n\n| Path | Why it changes |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | declare extensions, MIME types, category, description, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | declare extensions, MIME types, category, viewer component, icon, color, and description |\n| `frontend/src/components/Viewer/` | add or reuse a viewer component when the type needs a dedicated preview surface |\n\nIf a file type is user-visible, update the published support docs that describe what Sambee can preview.\n\n### Quick Start for a New Image Format\n\nFor an image format such as JPEG XL, the minimum workflow is:\n\n1. add a `FileTypeDefinition` entry to the backend registry\n2. add the matching entry to the frontend registry\n3. decide whether the image is browser-native or requires server-side conversion\n4. keep extensions and MIME types identical across both registries\n5. run the viewer and backend validation checks\n\nBackend example:\n\n```python\nFileTypeDefinition(\n\t\textensions=(\".jxl\",),\n\t\tmime_types=(\"image/jxl\",),\n\t\tcategory=FileCategory.IMAGE,\n\t\trequires_conversion=True,\n\t\tdescription=\"JPEG XL Image\",\n)\n```\n\nFrontend example:\n\n```typescript\n{\n\textensions: [\".jxl\"],\n\tmimeTypes: [\"image/jxl\"],\n\tcategory: \"image\",\n\tviewerComponent: () =\u003e import(\"../components/Viewer/ImageViewer\"),\n\ticon: \"image\",\n\tcolor: \"#a855f7\",\n\tdescription: \"JPEG XL Image\",\n}\n```\n\nThat registry update is what drives MIME matching, icon treatment, viewer routing, and image-gallery inclusion.\n\n### Backend Registry Rules\n\nBackend file-type definitions must stay explicit and type-safe.\n\n- `extensions` are tuples with a leading dot, such as `(\".jpg\", \".jpeg\")`\n- `mime_types` are tuples of standard MIME strings\n- `category` uses `FileCategory` values such as `IMAGE`, `DOCUMENT`, `TEXT`, `VIDEO`, `AUDIO`, `ARCHIVE`, `CODE`, `SPREADSHEET`, or `OTHER`\n- `requires_conversion` matters for image formats that cannot be rendered directly by the browser\n- `description` should be the human-readable label contributors and users would expect\n\nHow to decide `requires_conversion`:\n\n- set it to `False` for browser-native formats such as PNG, JPEG, GIF, WebP, SVG, and AVIF\n- set it to `True` for formats with limited browser support or formats that are not practical to render directly, such as TIFF, HEIC, BMP, JPEG 2000, or JPEG XL when browser support is not sufficient for the product baseline\n\n### Frontend Registry Rules\n\nFrontend file-type definitions control how the browser app presents the file.\n\n- keep `extensions` and `mimeTypes` aligned with the backend registry\n- set `viewerComponent` to the shared viewer that should render the type\n- choose an icon that matches the product language for that file category\n- choose a color that distinguishes the format without inventing a new palette on every addition\n\nFor image formats, reusing `ImageViewer` is usually enough. For non-image formats, you may need a dedicated viewer such as `PdfViewer`, `VideoViewer`, `AudioViewer`, or `TextViewer`.\n\n### Non-Image File Types\n\nThe overall process is the same for documents, video, audio, text, archives, and code files.\n\n1. add the backend registry entry\n2. add the frontend registry entry\n3. create or reuse the viewer component when preview support exists\n4. verify the file icon, viewer routing, and download behavior\n\nFor non-image files, `requires_conversion` is usually `False`. The main design question is whether the product has a viewer component for that category or should fall back to download-only behavior.\n\n### Integration Checklist\n\nUse this checklist before you consider the file type integrated:\n\n- backend registry entry added\n- frontend registry entry added\n- extensions and MIME types match exactly across both registries\n- browser-native versus converted-image behavior decided intentionally\n- viewer component chosen or added\n- icon and color treatment chosen\n- user-visible support docs updated if the file type changes what Sambee can preview\n\n### Testing Checklist\n\nAfter the registry change, verify:\n\n- icon display in the file browser\n- file opening in the expected viewer\n- shared toolbar behavior if the preview uses `ViewerControls`\n- conversion output if the format is server-converted\n- gallery inclusion for image formats\n- MIME type behavior across extension variants such as upper-case filenames\n- download behavior with the correct MIME type\n- mobile and tablet behavior when the preview is expected to work there\n\nFor server-converted formats, also verify:\n\n- the backend returns the converted MIME type you expect\n- transparency-sensitive formats still render correctly\n- resizing or quality settings do not degrade the preview contract unexpectedly\n- environment-specific format support failures surface in a controlled way\n\nFor preprocessable formats, also verify:\n\n- the registry recognizes the extension regardless of case and leading-dot differences\n- the expected preprocessor is selected for that format\n- missing external-tool support fails cleanly\n- validation and timeout rules behave as intended under bad inputs and slow conversions\n\n### Architecture Notes\n\nThese helper functions are the practical integration points contributors usually touch:\n\n- backend: `get_mime_type`, `needs_processing`, `is_image_file`, `get_file_type_by_extension`, `get_file_type_by_mime`\n- frontend: `getViewerComponent`, `isImageFile`, `getFileIcon`, `getFileTypeByExtension`, `getFileTypeByMime`\n\nAt runtime, the flow is:\n\n1. the backend lists files and assigns MIME information\n2. the frontend receives `FileInfo` data with that MIME information\n3. the frontend chooses icon treatment from filename and type rules\n4. the frontend selects the viewer from MIME and file-type data\n5. the backend routes convertible images through the image-conversion pipeline when needed\n\nThe frontend side still has work to do even when the backend owns the conversion:\n\n- viewer MIME recognition must include the input formats the backend classifies as previewable\n- file-type icon and color treatment must still reflect the original file type rather than the converted transport format\n- browser-side fallback MIME logic must not drift from the backend contract in ways that hide conversion bugs\n\n### Operational Characteristics\n\nServer-side conversion changes the runtime profile of preview requests.\n\n- large images can produce short CPU spikes during decode and encode\n- memory usage can rise well above compressed input size while the image is fully decoded\n- SMB-backed reads add their own latency before conversion even starts\n\nThat is why preview regressions for large HEIC or TIFF files often need both backend and user-facing verification.\n\n### Future Extension Points\n\nThe current conversion path leaves room for later enhancements such as:\n\n- caching converted preview outputs\n- queueing especially large conversions\n- dedicated thumbnail generation\n- richer multi-page image handling\n- conversion metrics for operational monitoring\n\nThose are extension points, not assumptions the current product already guarantees.\n\nThe highest-risk mistake is still registry drift. If the backend and frontend disagree about extensions or MIME types, preview behavior becomes unreliable in ways that are easy to miss until users hit them.\n\n## Common Failure Modes\n\n- backend and frontend MIME types do not match\n- a format is marked browser-native when it really needs conversion\n- a viewer component is not registered even though the type is recognized\n- a conversion change improves one format but breaks gallery behavior, download semantics, or mobile viewing\n\n## Validation Expectations\n\nWhen you change viewer or file-type behavior, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd backend \u0026\u0026 pytest -v\n```\n\nIf the change is image-conversion-specific, include the relevant backend tests around image conversion and preview behavior.\n", "0.9": "+++\ntitle = \"Viewer Architecture and Preview Contracts\"\n+++\n\nPreview behavior in Sambee is a cross-boundary contract, not just a frontend component choice.\n\n## The Core Contract\n\nThe browser app decides how to render a file based on metadata and file-type information, but that depends on server-side classification staying aligned.\n\nThree rules matter most:\n\n- the backend and frontend file-type registries must describe the same extensions and MIME types\n- the backend decides whether an image format needs server-side conversion for browser compatibility\n- the frontend chooses the right viewer component and file icon based on the effective file type and MIME information it receives\n\n## Where the Main Decisions Live\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | backend source of truth for extensions, MIME types, categories, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | frontend source of truth for extensions, MIME types, categories, viewer components, icons, and colors |\n| `frontend/src/components/Viewer/` | viewer components and shared viewer UI |\n| `backend/app/services/image_converter.py` | server-side conversion for non-browser-native image formats |\n\n## Viewer Selection Model\n\nAt a high level, the preview pipeline works like this:\n\n1. the backend determines file category and MIME behavior\n2. the backend decides whether the file can stream as-is or needs image conversion\n3. the frontend maps the file type to the appropriate viewer component\n4. the shared viewer controls keep the toolbar and common behavior consistent across viewers\n\nThat is why a file-type change almost always touches both backend and frontend code.\n\n## Browser-Native Versus Server-Converted Images\n\nSambee supports both browser-native formats and formats that need server-side conversion.\n\n- browser-native formats can be sent to the viewer directly\n- non-browser-native image formats are converted on the server before the browser renders them\n- special cases such as transparency preservation can change the output format choice\n\nIf you change conversion rules, you are changing a product contract, not just an implementation detail.\n\n### Server-Side Conversion Contract\n\nThe conversion path is owned by `backend/app/services/image_converter.py` and is exercised through the viewer API.\n\nThe backend conversion service is responsible for:\n\n- deciding whether an image needs processing\n- converting unsupported or impractical browser formats into a viewer-safe output format\n- preserving transparency where the output contract requires it\n- applying optional downscaling so one preview request cannot explode memory usage casually\n- returning enough metadata for the viewer endpoint to send the correct MIME type back to the browser\n\nRepresentative service responsibilities include:\n\n- `needs_processing(filename)`\n- `convert_image_for_viewer(...)`\n- `is_image_file(filename)`\n- `get_image_info(...)`\n\nThe viewer endpoint then follows this rule:\n\n- if the image can stream safely as-is, return a streaming response\n- if it requires conversion, read it, convert it, and return the converted bytes with the converted MIME type\n\nThat means preview behavior for formats such as TIFF, HEIC, BMP, ICO, and similar formats depends on backend conversion policy, not just on frontend MIME recognition.\n\n### Local-Drive Preview Policy\n\nThe Companion serves local-drive files and archive members as raw bytes. It does not copy local content to the backend for processing and does not bundle the backend image or PDF processing stack.\n\n- Browser-native images, text files, and original PDFs can preview from their raw local bytes.\n- Image formats that require server-side conversion, such as TIFF, HEIC, PSD, JPEG XL, and scientific image formats, show an explicit preview-unavailable state for local drives.\n- Image resizing and PDF compatibility normalization are unavailable for local drives.\n- Downloading and opening the original file locally remain available when a local preview is unavailable.\n\nThe frontend resolves these capabilities before making a local viewer request. Local archive-member requests use the Companion's strict raw-stream contract, while SMB archive-member requests retain the full conversion and PDF-normalization request parameters.\n\n### Output Format Rules\n\nThe backend does not always convert everything to the same output type.\n\n- JPEG is the common output for opaque images\n- PNG remains important when transparency must be preserved\n- ICO-like transparency handling is therefore different from ordinary opaque-photo conversion\n- alpha-bearing formats converted to JPEG need explicit compositing behavior rather than silent accidental loss\n\nIf you change those rules, check both visual correctness and user-facing assumptions such as download behavior and gallery continuity.\n\n### Current Format-Specific Preview Semantics\n\nSeveral converted-image families have product-specific preview semantics that contributors should preserve unless the product intentionally changes.\n\n- multi-page TIFF currently previews the first page rather than exposing a document-style page stack\n- PSD and PSB preview the flattened composite instead of surfacing layer-edit semantics through the browser viewer\n- EPS and AI are rasterized through the preprocessing path at high quality, currently using the 300 DPI rendering baseline\n- HDR-oriented formats such as EXR and Radiance HDR are tone-mapped into ordinary browser-display output\n- whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF preview as an overview or first practical pyramid level rather than as a full pathology viewer\n- FITS and similar scientific-image formats apply visibility scaling so low-level pixel values become inspectable in a normal browser image surface\n\nThese are not accidental implementation details. They define what users should expect from preview and therefore belong to the product contract.\n\n### Resizing and Resource Limits\n\nServer-side conversion can consume significant memory because the file must be read, decoded, and re-encoded.\n\nThe current contract therefore includes:\n\n- configurable JPEG-quality behavior\n- maximum-dimension downscaling to avoid unbounded preview size\n- backend-side protection against excessive memory usage from large source images\n\nContributors should treat those limits as operational safety controls, not as arbitrary defaults.\n\n### Dependency and Environment Expectations\n\nThe conversion path depends on reviewed Python and system-image libraries.\n\nThat includes the normal image stack plus HEIC/HEIF support through the reviewed dependency chain and corresponding system libraries in the container or runtime image.\n\nWhen conversion support seems to disappear unexpectedly, check:\n\n- the backend Python dependency set\n- the container or host system-image libraries\n- whether the format-specific support was actually installed in the current environment\n\n### Preprocessor Registry for Exotic Formats\n\nSome formats need a preprocessing step before the normal conversion path can handle them at all.\n\nThat registry lives in:\n\n- `backend/app/services/preprocessor.py`\n\nIt is consumed by:\n\n- `backend/app/services/image_converter.py`\n\nThe preprocessor layer exists for formats that libvips should not or cannot decode directly for Sambee's preview contract.\n\nCurrent registered formats route through the ImageMagick-backed preprocessor:\n\n- `.psd`\n- `.psb`\n- `.eps`\n- `.ai`\n\nThe registry is the single source of truth for which extensions require preprocessing before the final viewer-safe conversion step.\n\nFor the backend service architecture behind that path, continue to [Image Preprocessing and Conversion Pipeline](../../backend-architecture/image-preprocessing-and-conversion-pipeline/).\n\nRepresentative registry operations include:\n\n- `PreprocessorRegistry.requires_preprocessing(extension)`\n- `PreprocessorRegistry.get_preprocessor_for_format(extension)`\n- `PreprocessorRegistry.get_supported_formats()`\n- `PreprocessorRegistry.register_format(extension, preprocessor_class)`\n\n### Preprocessor Design Rules\n\nThe preprocessor layer has its own constraints:\n\n- one registry entry per preprocessable extension\n- direct in-memory conversion to the final browser-ready format rather than chained intermediate formats\n- no shell-mediated fallback chain logic in the registry itself\n- input validation and timeout enforcement happen in the preprocessor layer\n- failures should surface as explicit preprocessing or conversion errors rather than silent format drift\n\nThe main abstraction is `PreprocessorInterface`, with `ImageMagickPreprocessor` as the current built-in implementation.\n\n### Adding a New Preprocessed Format\n\nIf a new format cannot be handled by the normal conversion stack directly:\n\n1. implement a `PreprocessorInterface` subclass if the existing preprocessor is not appropriate\n2. register the extension in `PreprocessorRegistry`\n3. add or update file-type metadata if the format becomes user-visible in preview flows\n4. add tests for format recognition, tool availability, validation, and successful conversion\n\nDo not treat preprocessable formats as ordinary file-type additions. They change the backend conversion pipeline itself.\n\n### Error Surface Contributors Must Preserve\n\nConversion failures are user-visible API behavior, not internal-only exceptions.\n\nTypical outcomes include:\n\n- not implemented when the current environment lacks support for a format family\n- unprocessable-content style failures when the file is corrupt or cannot be decoded\n- ordinary backend failures when an unexpected exception escapes the conversion path\n\nThat means error wording, status behavior, and frontend fallback behavior should be reviewed together.\n\n## Shared Viewer UI\n\nThe main viewer toolbar is intentionally centralized in `frontend/src/components/Viewer/ViewerControls.tsx`.\n\nThis is no longer just an image-and-PDF convenience component. It is the canonical control surface for the current full-screen image, PDF, and Markdown viewers.\n\n- shared toolbar layout, styling, keyboard-tooltip behavior, and responsive behavior live in `ViewerControls`\n- each viewer turns features on through configuration and passes only the state objects it needs\n- future viewers should reuse that control shell where possible instead of creating another top-level toolbar implementation\n\n### Control-Surface Model\n\n`ViewerControls` uses a feature-flag configuration plus typed state objects.\n\nThe configuration currently enables these capability groups:\n\n- `navigation` for gallery-style previous and next navigation\n- `pageNavigation` for PDF page input and page stepping\n- `zoom` for viewer-managed zoom actions\n- `rotation` for image and PDF rotation actions\n- `search` for the shared search row and match navigation affordances\n- `download` for explicit download actions\n- `share` for mobile-first share actions\n\nThe component then accepts matching state surfaces:\n\n- `NavigationState` for item index, total items, and next or previous handlers\n- `PageNavigationState` for current page, total pages, and page-change handling\n- `ZoomState` for zoom-in and zoom-out handlers\n- `RotationState` for rotate-left and rotate-right handlers\n- `SearchState` for search text, match counts, search-panel state, open or close callbacks, and viewer-specific search navigation\n\nThat split matters because `ViewerControls` owns the common UI, but it does not own viewer logic. It renders controls and delegates behavior back to the viewer that actually knows how to navigate pages, zoom, rotate, or search.\n\n### Current Consumers\n\nThe current shared-toolbar consumers are:\n\n- `ImageViewer`, which enables gallery navigation, zoom, rotation, download, and optional mobile share\n- `PDFViewer`, which enables page navigation, zoom, rotation, search, download, and optional mobile share\n- `MarkdownViewer`, which reuses the same shell for download, optional mobile share, shared search UI, and viewer-specific action buttons such as editing flows\n\n`ViewerControls` also supports generic toolbar actions through the `actions` prop, which can render either text buttons or icon buttons. That is what allows Markdown-specific actions to live inside the same shared toolbar instead of forcing a second toolbar implementation.\n\n### Search UI Versus Search Engine\n\nThe search row is shared, but the search backend is viewer-specific.\n\n- `PDFViewer` wires the search controls to PDF text extraction, page-aware match tracking, and PDF-specific next or previous navigation\n- rendered Markdown and other rendered text views can route search through the DOM text-search utility in `frontend/src/utils/domTextSearch.ts`\n- Markdown edit mode does not reuse the rendered-view DOM search implementation; it bridges the same outer toolbar UI into the editor-specific search state and commands instead\n\nThat separation is an important contract: contributors should reuse the shared search UI when possible, but should not assume every viewer can use the same search implementation under the hood.\n\n### Responsive and Accessibility Rules\n\nThe centralized toolbar also encodes product behavior that should stay consistent across viewers.\n\n- filename display, optional filename adornments, and close behavior are shared\n- mobile layout uses safe-area-aware spacing and smaller controls\n- gallery arrows and desktop zoom controls are intentionally reduced on mobile, where gesture-based interaction is preferred\n- share is exposed as a mobile-first affordance, with optional early-intent warming through `onShareIntent`\n- buttons use explicit `aria-label` values and shortcut-oriented `title` text so the control surface remains navigable and self-describing\n- the shared search row manages focus when it opens and preserves consistent close behavior for toggle and Escape-driven exits\n\n### Legacy Components and Contributor Guidance\n\nLegacy `ImageControls.tsx` and `PDFControls.tsx` files still exist in the frontend tree, but `ViewerControls` is the current architectural direction and the shared component used by the active image, PDF, and Markdown viewers.\n\nIf you add another viewer or extend an existing one:\n\n- prefer extending `ViewerControlsConfig`, the relevant state interfaces, or the generic `actions` surface\n- keep viewer-specific logic in the viewer component rather than teaching `ViewerControls` about file-format internals\n- preserve shared mobile, accessibility, and search-panel behavior unless the product intentionally changes that contract\n- add or update focused tests in `frontend/src/components/Viewer/__tests__/ViewerControls.test.tsx` when the shared toolbar contract changes\n\n## Adding a New File Type Safely\n\nFile-type support is registry-driven. The safest way to add a new type is to treat backend and frontend changes as one contract update.\n\n### Main Files to Change\n\n| Path | Why it changes |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | declare extensions, MIME types, category, description, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | declare extensions, MIME types, category, viewer component, icon, color, and description |\n| `frontend/src/components/Viewer/` | add or reuse a viewer component when the type needs a dedicated preview surface |\n\nIf a file type is user-visible, update the published support docs that describe what Sambee can preview.\n\n### Quick Start for a New Image Format\n\nFor an image format such as JPEG XL, the minimum workflow is:\n\n1. add a `FileTypeDefinition` entry to the backend registry\n2. add the matching entry to the frontend registry\n3. decide whether the image is browser-native or requires server-side conversion\n4. keep extensions and MIME types identical across both registries\n5. run the viewer and backend validation checks\n\nBackend example:\n\n```python\nFileTypeDefinition(\n\t\textensions=(\".jxl\",),\n\t\tmime_types=(\"image/jxl\",),\n\t\tcategory=FileCategory.IMAGE,\n\t\trequires_conversion=True,\n\t\tdescription=\"JPEG XL Image\",\n)\n```\n\nFrontend example:\n\n```typescript\n{\n\textensions: [\".jxl\"],\n\tmimeTypes: [\"image/jxl\"],\n\tcategory: \"image\",\n\tviewerComponent: () =\u003e import(\"../components/Viewer/ImageViewer\"),\n\ticon: \"image\",\n\tcolor: \"#a855f7\",\n\tdescription: \"JPEG XL Image\",\n}\n```\n\nThat registry update is what drives MIME matching, icon treatment, viewer routing, and image-gallery inclusion.\n\n### Backend Registry Rules\n\nBackend file-type definitions must stay explicit and type-safe.\n\n- `extensions` are tuples with a leading dot, such as `(\".jpg\", \".jpeg\")`\n- `mime_types` are tuples of standard MIME strings\n- `category` uses `FileCategory` values such as `IMAGE`, `DOCUMENT`, `TEXT`, `VIDEO`, `AUDIO`, `ARCHIVE`, `CODE`, `SPREADSHEET`, or `OTHER`\n- `requires_conversion` matters for image formats that cannot be rendered directly by the browser\n- `description` should be the human-readable label contributors and users would expect\n\nHow to decide `requires_conversion`:\n\n- set it to `False` for browser-native formats such as PNG, JPEG, GIF, WebP, SVG, and AVIF\n- set it to `True` for formats with limited browser support or formats that are not practical to render directly, such as TIFF, HEIC, BMP, JPEG 2000, or JPEG XL when browser support is not sufficient for the product baseline\n\n### Frontend Registry Rules\n\nFrontend file-type definitions control how the browser app presents the file.\n\n- keep `extensions` and `mimeTypes` aligned with the backend registry\n- set `viewerComponent` to the shared viewer that should render the type\n- choose an icon that matches the product language for that file category\n- choose a color that distinguishes the format without inventing a new palette on every addition\n\nFor image formats, reusing `ImageViewer` is usually enough. For non-image formats, you may need a dedicated viewer such as `PdfViewer`, `VideoViewer`, `AudioViewer`, or `TextViewer`.\n\n### Non-Image File Types\n\nThe overall process is the same for documents, video, audio, text, archives, and code files.\n\n1. add the backend registry entry\n2. add the frontend registry entry\n3. create or reuse the viewer component when preview support exists\n4. verify the file icon, viewer routing, and download behavior\n\nFor non-image files, `requires_conversion` is usually `False`. The main design question is whether the product has a viewer component for that category or should fall back to download-only behavior.\n\n### Integration Checklist\n\nUse this checklist before you consider the file type integrated:\n\n- backend registry entry added\n- frontend registry entry added\n- extensions and MIME types match exactly across both registries\n- browser-native versus converted-image behavior decided intentionally\n- viewer component chosen or added\n- icon and color treatment chosen\n- user-visible support docs updated if the file type changes what Sambee can preview\n\n### Testing Checklist\n\nAfter the registry change, verify:\n\n- icon display in the file browser\n- file opening in the expected viewer\n- shared toolbar behavior if the preview uses `ViewerControls`\n- conversion output if the format is server-converted\n- gallery inclusion for image formats\n- MIME type behavior across extension variants such as upper-case filenames\n- download behavior with the correct MIME type\n- mobile and tablet behavior when the preview is expected to work there\n\nFor server-converted formats, also verify:\n\n- the backend returns the converted MIME type you expect\n- transparency-sensitive formats still render correctly\n- resizing or quality settings do not degrade the preview contract unexpectedly\n- environment-specific format support failures surface in a controlled way\n\nFor preprocessable formats, also verify:\n\n- the registry recognizes the extension regardless of case and leading-dot differences\n- the expected preprocessor is selected for that format\n- missing external-tool support fails cleanly\n- validation and timeout rules behave as intended under bad inputs and slow conversions\n\n### Architecture Notes\n\nThese helper functions are the practical integration points contributors usually touch:\n\n- backend: `get_mime_type`, `needs_processing`, `is_image_file`, `get_file_type_by_extension`, `get_file_type_by_mime`\n- frontend: `getViewerComponent`, `isImageFile`, `getFileIcon`, `getFileTypeByExtension`, `getFileTypeByMime`\n\nAt runtime, the flow is:\n\n1. the backend lists files and assigns MIME information\n2. the frontend receives `FileInfo` data with that MIME information\n3. the frontend chooses icon treatment from filename and type rules\n4. the frontend selects the viewer from MIME and file-type data\n5. the backend routes convertible images through the image-conversion pipeline when needed\n\nThe frontend side still has work to do even when the backend owns the conversion:\n\n- viewer MIME recognition must include the input formats the backend classifies as previewable\n- file-type icon and color treatment must still reflect the original file type rather than the converted transport format\n- browser-side fallback MIME logic must not drift from the backend contract in ways that hide conversion bugs\n\n### Operational Characteristics\n\nServer-side conversion changes the runtime profile of preview requests.\n\n- large images can produce short CPU spikes during decode and encode\n- memory usage can rise well above compressed input size while the image is fully decoded\n- SMB-backed reads add their own latency before conversion even starts\n\nThat is why preview regressions for large HEIC or TIFF files often need both backend and user-facing verification.\n\n### Future Extension Points\n\nThe current conversion path leaves room for later enhancements such as:\n\n- caching converted preview outputs\n- queueing especially large conversions\n- dedicated thumbnail generation\n- richer multi-page image handling\n- conversion metrics for operational monitoring\n\nThose are extension points, not assumptions the current product already guarantees.\n\nThe highest-risk mistake is still registry drift. If the backend and frontend disagree about extensions or MIME types, preview behavior becomes unreliable in ways that are easy to miss until users hit them.\n\n## Common Failure Modes\n\n- backend and frontend MIME types do not match\n- a format is marked browser-native when it really needs conversion\n- a viewer component is not registered even though the type is recognized\n- a conversion change improves one format but breaks gallery behavior, download semantics, or mobile viewing\n\n## Validation Expectations\n\nWhen you change viewer or file-type behavior, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd backend \u0026\u0026 pytest -v\n```\n\nIf the change is image-conversion-specific, include the relevant backend tests around image conversion and preview behavior.\n", "1.0": "+++\ntitle = \"Viewer Architecture and Preview Contracts\"\n+++\n\nPreview behavior in Sambee is a cross-boundary contract, not just a frontend component choice.\n\n## The Core Contract\n\nThe browser app decides how to render a file based on metadata and file-type information, but that depends on server-side classification staying aligned.\n\nThree rules matter most:\n\n- the backend and frontend file-type registries must describe the same extensions and MIME types\n- the backend decides whether an image format needs server-side conversion for browser compatibility\n- the frontend chooses the right viewer component and file icon based on the effective file type and MIME information it receives\n\n## Where the Main Decisions Live\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | backend source of truth for extensions, MIME types, categories, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | frontend source of truth for extensions, MIME types, categories, viewer components, icons, and colors |\n| `frontend/src/components/Viewer/` | viewer components and shared viewer UI |\n| `backend/app/services/image_converter.py` | server-side conversion for non-browser-native image formats |\n\n## Viewer Selection Model\n\nAt a high level, the preview pipeline works like this:\n\n1. the backend determines file category and MIME behavior\n2. the backend decides whether the file can stream as-is or needs image conversion\n3. the frontend maps the file type to the appropriate viewer component\n4. the shared viewer controls keep the toolbar and common behavior consistent across viewers\n\nThat is why a file-type change almost always touches both backend and frontend code.\n\n## Browser-Native Versus Server-Converted Images\n\nSambee supports both browser-native formats and formats that need server-side conversion.\n\n- browser-native formats can be sent to the viewer directly\n- non-browser-native image formats are converted on the server before the browser renders them\n- special cases such as transparency preservation can change the output format choice\n\nIf you change conversion rules, you are changing a product contract, not just an implementation detail.\n\n### Server-Side Conversion Contract\n\nThe conversion path is owned by `backend/app/services/image_converter.py` and is exercised through the viewer API.\n\nThe backend conversion service is responsible for:\n\n- deciding whether an image needs processing\n- converting unsupported or impractical browser formats into a viewer-safe output format\n- preserving transparency where the output contract requires it\n- applying optional downscaling so one preview request cannot explode memory usage casually\n- returning enough metadata for the viewer endpoint to send the correct MIME type back to the browser\n\nRepresentative service responsibilities include:\n\n- `needs_processing(filename)`\n- `convert_image_for_viewer(...)`\n- `is_image_file(filename)`\n- `get_image_info(...)`\n\nThe viewer endpoint then follows this rule:\n\n- if the image can stream safely as-is, return a streaming response\n- if it requires conversion, read it, convert it, and return the converted bytes with the converted MIME type\n\nThat means preview behavior for formats such as TIFF, HEIC, BMP, ICO, and similar formats depends on backend conversion policy, not just on frontend MIME recognition.\n\n### Local-Drive Preview Policy\n\nThe Companion serves local-drive files and archive members as raw bytes. It does not copy local content to the backend for processing and does not bundle the backend image or PDF processing stack.\n\n- Browser-native images, text files, and original PDFs can preview from their raw local bytes.\n- Image formats that require server-side conversion, such as TIFF, HEIC, PSD, JPEG XL, and scientific image formats, show an explicit preview-unavailable state for local drives.\n- Image resizing and PDF compatibility normalization are unavailable for local drives.\n- Downloading and opening the original file locally remain available when a local preview is unavailable.\n\nThe frontend resolves these capabilities before making a local viewer request. Local archive-member requests use the Companion's strict raw-stream contract, while SMB archive-member requests retain the full conversion and PDF-normalization request parameters.\n\n### Output Format Rules\n\nThe backend does not always convert everything to the same output type.\n\n- JPEG is the common output for opaque images\n- PNG remains important when transparency must be preserved\n- ICO-like transparency handling is therefore different from ordinary opaque-photo conversion\n- alpha-bearing formats converted to JPEG need explicit compositing behavior rather than silent accidental loss\n\nIf you change those rules, check both visual correctness and user-facing assumptions such as download behavior and gallery continuity.\n\n### Current Format-Specific Preview Semantics\n\nSeveral converted-image families have product-specific preview semantics that contributors should preserve unless the product intentionally changes.\n\n- multi-page TIFF currently previews the first page rather than exposing a document-style page stack\n- PSD and PSB preview the flattened composite instead of surfacing layer-edit semantics through the browser viewer\n- EPS and AI are rasterized through the preprocessing path at high quality, currently using the 300 DPI rendering baseline\n- HDR-oriented formats such as EXR and Radiance HDR are tone-mapped into ordinary browser-display output\n- whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF preview as an overview or first practical pyramid level rather than as a full pathology viewer\n- FITS and similar scientific-image formats apply visibility scaling so low-level pixel values become inspectable in a normal browser image surface\n\nThese are not accidental implementation details. They define what users should expect from preview and therefore belong to the product contract.\n\n### Resizing and Resource Limits\n\nServer-side conversion can consume significant memory because the file must be read, decoded, and re-encoded.\n\nThe current contract therefore includes:\n\n- configurable JPEG-quality behavior\n- maximum-dimension downscaling to avoid unbounded preview size\n- backend-side protection against excessive memory usage from large source images\n\nContributors should treat those limits as operational safety controls, not as arbitrary defaults.\n\n### Dependency and Environment Expectations\n\nThe conversion path depends on reviewed Python and system-image libraries.\n\nThat includes the normal image stack plus HEIC/HEIF support through the reviewed dependency chain and corresponding system libraries in the container or runtime image.\n\nWhen conversion support seems to disappear unexpectedly, check:\n\n- the backend Python dependency set\n- the container or host system-image libraries\n- whether the format-specific support was actually installed in the current environment\n\n### Preprocessor Registry for Exotic Formats\n\nSome formats need a preprocessing step before the normal conversion path can handle them at all.\n\nThat registry lives in:\n\n- `backend/app/services/preprocessor.py`\n\nIt is consumed by:\n\n- `backend/app/services/image_converter.py`\n\nThe preprocessor layer exists for formats that libvips should not or cannot decode directly for Sambee's preview contract.\n\nCurrent registered formats route through the ImageMagick-backed preprocessor:\n\n- `.psd`\n- `.psb`\n- `.eps`\n- `.ai`\n\nThe registry is the single source of truth for which extensions require preprocessing before the final viewer-safe conversion step.\n\nFor the backend service architecture behind that path, continue to [Image Preprocessing and Conversion Pipeline](../../backend-architecture/image-preprocessing-and-conversion-pipeline/).\n\nRepresentative registry operations include:\n\n- `PreprocessorRegistry.requires_preprocessing(extension)`\n- `PreprocessorRegistry.get_preprocessor_for_format(extension)`\n- `PreprocessorRegistry.get_supported_formats()`\n- `PreprocessorRegistry.register_format(extension, preprocessor_class)`\n\n### Preprocessor Design Rules\n\nThe preprocessor layer has its own constraints:\n\n- one registry entry per preprocessable extension\n- direct in-memory conversion to the final browser-ready format rather than chained intermediate formats\n- no shell-mediated fallback chain logic in the registry itself\n- input validation and timeout enforcement happen in the preprocessor layer\n- failures should surface as explicit preprocessing or conversion errors rather than silent format drift\n\nThe main abstraction is `PreprocessorInterface`, with `ImageMagickPreprocessor` as the current built-in implementation.\n\n### Adding a New Preprocessed Format\n\nIf a new format cannot be handled by the normal conversion stack directly:\n\n1. implement a `PreprocessorInterface` subclass if the existing preprocessor is not appropriate\n2. register the extension in `PreprocessorRegistry`\n3. add or update file-type metadata if the format becomes user-visible in preview flows\n4. add tests for format recognition, tool availability, validation, and successful conversion\n\nDo not treat preprocessable formats as ordinary file-type additions. They change the backend conversion pipeline itself.\n\n### Error Surface Contributors Must Preserve\n\nConversion failures are user-visible API behavior, not internal-only exceptions.\n\nTypical outcomes include:\n\n- not implemented when the current environment lacks support for a format family\n- unprocessable-content style failures when the file is corrupt or cannot be decoded\n- ordinary backend failures when an unexpected exception escapes the conversion path\n\nThat means error wording, status behavior, and frontend fallback behavior should be reviewed together.\n\n## Shared Viewer UI\n\nThe main viewer toolbar is intentionally centralized in `frontend/src/components/Viewer/ViewerControls.tsx`.\n\nThis is no longer just an image-and-PDF convenience component. It is the canonical control surface for the current full-screen image, PDF, and Markdown viewers.\n\n- shared toolbar layout, styling, keyboard-tooltip behavior, and responsive behavior live in `ViewerControls`\n- each viewer turns features on through configuration and passes only the state objects it needs\n- future viewers should reuse that control shell where possible instead of creating another top-level toolbar implementation\n\n### Control-Surface Model\n\n`ViewerControls` uses a feature-flag configuration plus typed state objects.\n\nThe configuration currently enables these capability groups:\n\n- `navigation` for gallery-style previous and next navigation\n- `pageNavigation` for PDF page input and page stepping\n- `zoom` for viewer-managed zoom actions\n- `rotation` for image and PDF rotation actions\n- `search` for the shared search row and match navigation affordances\n- `download` for explicit download actions\n- `share` for mobile-first share actions\n\nThe component then accepts matching state surfaces:\n\n- `NavigationState` for item index, total items, and next or previous handlers\n- `PageNavigationState` for current page, total pages, and page-change handling\n- `ZoomState` for zoom-in and zoom-out handlers\n- `RotationState` for rotate-left and rotate-right handlers\n- `SearchState` for search text, match counts, search-panel state, open or close callbacks, and viewer-specific search navigation\n\nThat split matters because `ViewerControls` owns the common UI, but it does not own viewer logic. It renders controls and delegates behavior back to the viewer that actually knows how to navigate pages, zoom, rotate, or search.\n\n### Current Consumers\n\nThe current shared-toolbar consumers are:\n\n- `ImageViewer`, which enables gallery navigation, zoom, rotation, download, and optional mobile share\n- `PDFViewer`, which enables page navigation, zoom, rotation, search, download, and optional mobile share\n- `MarkdownViewer`, which reuses the same shell for download, optional mobile share, shared search UI, and viewer-specific action buttons such as editing flows\n\n`ViewerControls` also supports generic toolbar actions through the `actions` prop, which can render either text buttons or icon buttons. That is what allows Markdown-specific actions to live inside the same shared toolbar instead of forcing a second toolbar implementation.\n\n### Search UI Versus Search Engine\n\nThe search row is shared, but the search backend is viewer-specific.\n\n- `PDFViewer` wires the search controls to PDF text extraction, page-aware match tracking, and PDF-specific next or previous navigation\n- rendered Markdown and other rendered text views can route search through the DOM text-search utility in `frontend/src/utils/domTextSearch.ts`\n- Markdown edit mode does not reuse the rendered-view DOM search implementation; it bridges the same outer toolbar UI into the editor-specific search state and commands instead\n\nThat separation is an important contract: contributors should reuse the shared search UI when possible, but should not assume every viewer can use the same search implementation under the hood.\n\n### Responsive and Accessibility Rules\n\nThe centralized toolbar also encodes product behavior that should stay consistent across viewers.\n\n- filename display, optional filename adornments, and close behavior are shared\n- mobile layout uses safe-area-aware spacing and smaller controls\n- gallery arrows and desktop zoom controls are intentionally reduced on mobile, where gesture-based interaction is preferred\n- share is exposed as a mobile-first affordance, with optional early-intent warming through `onShareIntent`\n- buttons use explicit `aria-label` values and shortcut-oriented `title` text so the control surface remains navigable and self-describing\n- the shared search row manages focus when it opens and preserves consistent close behavior for toggle and Escape-driven exits\n\n### Legacy Components and Contributor Guidance\n\nLegacy `ImageControls.tsx` and `PDFControls.tsx` files still exist in the frontend tree, but `ViewerControls` is the current architectural direction and the shared component used by the active image, PDF, and Markdown viewers.\n\nIf you add another viewer or extend an existing one:\n\n- prefer extending `ViewerControlsConfig`, the relevant state interfaces, or the generic `actions` surface\n- keep viewer-specific logic in the viewer component rather than teaching `ViewerControls` about file-format internals\n- preserve shared mobile, accessibility, and search-panel behavior unless the product intentionally changes that contract\n- add or update focused tests in `frontend/src/components/Viewer/__tests__/ViewerControls.test.tsx` when the shared toolbar contract changes\n\n## Adding a New File Type Safely\n\nFile-type support is registry-driven. The safest way to add a new type is to treat backend and frontend changes as one contract update.\n\n### Main Files to Change\n\n| Path | Why it changes |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | declare extensions, MIME types, category, description, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | declare extensions, MIME types, category, viewer component, icon, color, and description |\n| `frontend/src/components/Viewer/` | add or reuse a viewer component when the type needs a dedicated preview surface |\n\nIf a file type is user-visible, update the published support docs that describe what Sambee can preview.\n\n### Quick Start for a New Image Format\n\nFor an image format such as JPEG XL, the minimum workflow is:\n\n1. add a `FileTypeDefinition` entry to the backend registry\n2. add the matching entry to the frontend registry\n3. decide whether the image is browser-native or requires server-side conversion\n4. keep extensions and MIME types identical across both registries\n5. run the viewer and backend validation checks\n\nBackend example:\n\n```python\nFileTypeDefinition(\n\t\textensions=(\".jxl\",),\n\t\tmime_types=(\"image/jxl\",),\n\t\tcategory=FileCategory.IMAGE,\n\t\trequires_conversion=True,\n\t\tdescription=\"JPEG XL Image\",\n)\n```\n\nFrontend example:\n\n```typescript\n{\n\textensions: [\".jxl\"],\n\tmimeTypes: [\"image/jxl\"],\n\tcategory: \"image\",\n\tviewerComponent: () =\u003e import(\"../components/Viewer/ImageViewer\"),\n\ticon: \"image\",\n\tcolor: \"#a855f7\",\n\tdescription: \"JPEG XL Image\",\n}\n```\n\nThat registry update is what drives MIME matching, icon treatment, viewer routing, and image-gallery inclusion.\n\n### Backend Registry Rules\n\nBackend file-type definitions must stay explicit and type-safe.\n\n- `extensions` are tuples with a leading dot, such as `(\".jpg\", \".jpeg\")`\n- `mime_types` are tuples of standard MIME strings\n- `category` uses `FileCategory` values such as `IMAGE`, `DOCUMENT`, `TEXT`, `VIDEO`, `AUDIO`, `ARCHIVE`, `CODE`, `SPREADSHEET`, or `OTHER`\n- `requires_conversion` matters for image formats that cannot be rendered directly by the browser\n- `description` should be the human-readable label contributors and users would expect\n\nHow to decide `requires_conversion`:\n\n- set it to `False` for browser-native formats such as PNG, JPEG, GIF, WebP, SVG, and AVIF\n- set it to `True` for formats with limited browser support or formats that are not practical to render directly, such as TIFF, HEIC, BMP, JPEG 2000, or JPEG XL when browser support is not sufficient for the product baseline\n\n### Frontend Registry Rules\n\nFrontend file-type definitions control how the browser app presents the file.\n\n- keep `extensions` and `mimeTypes` aligned with the backend registry\n- set `viewerComponent` to the shared viewer that should render the type\n- choose an icon that matches the product language for that file category\n- choose a color that distinguishes the format without inventing a new palette on every addition\n\nFor image formats, reusing `ImageViewer` is usually enough. For non-image formats, you may need a dedicated viewer such as `PdfViewer`, `VideoViewer`, `AudioViewer`, or `TextViewer`.\n\n### Non-Image File Types\n\nThe overall process is the same for documents, video, audio, text, archives, and code files.\n\n1. add the backend registry entry\n2. add the frontend registry entry\n3. create or reuse the viewer component when preview support exists\n4. verify the file icon, viewer routing, and download behavior\n\nFor non-image files, `requires_conversion` is usually `False`. The main design question is whether the product has a viewer component for that category or should fall back to download-only behavior.\n\n### Integration Checklist\n\nUse this checklist before you consider the file type integrated:\n\n- backend registry entry added\n- frontend registry entry added\n- extensions and MIME types match exactly across both registries\n- browser-native versus converted-image behavior decided intentionally\n- viewer component chosen or added\n- icon and color treatment chosen\n- user-visible support docs updated if the file type changes what Sambee can preview\n\n### Testing Checklist\n\nAfter the registry change, verify:\n\n- icon display in the file browser\n- file opening in the expected viewer\n- shared toolbar behavior if the preview uses `ViewerControls`\n- conversion output if the format is server-converted\n- gallery inclusion for image formats\n- MIME type behavior across extension variants such as upper-case filenames\n- download behavior with the correct MIME type\n- mobile and tablet behavior when the preview is expected to work there\n\nFor server-converted formats, also verify:\n\n- the backend returns the converted MIME type you expect\n- transparency-sensitive formats still render correctly\n- resizing or quality settings do not degrade the preview contract unexpectedly\n- environment-specific format support failures surface in a controlled way\n\nFor preprocessable formats, also verify:\n\n- the registry recognizes the extension regardless of case and leading-dot differences\n- the expected preprocessor is selected for that format\n- missing external-tool support fails cleanly\n- validation and timeout rules behave as intended under bad inputs and slow conversions\n\n### Architecture Notes\n\nThese helper functions are the practical integration points contributors usually touch:\n\n- backend: `get_mime_type`, `needs_processing`, `is_image_file`, `get_file_type_by_extension`, `get_file_type_by_mime`\n- frontend: `getViewerComponent`, `isImageFile`, `getFileIcon`, `getFileTypeByExtension`, `getFileTypeByMime`\n\nAt runtime, the flow is:\n\n1. the backend lists files and assigns MIME information\n2. the frontend receives `FileInfo` data with that MIME information\n3. the frontend chooses icon treatment from filename and type rules\n4. the frontend selects the viewer from MIME and file-type data\n5. the backend routes convertible images through the image-conversion pipeline when needed\n\nThe frontend side still has work to do even when the backend owns the conversion:\n\n- viewer MIME recognition must include the input formats the backend classifies as previewable\n- file-type icon and color treatment must still reflect the original file type rather than the converted transport format\n- browser-side fallback MIME logic must not drift from the backend contract in ways that hide conversion bugs\n\n### Operational Characteristics\n\nServer-side conversion changes the runtime profile of preview requests.\n\n- large images can produce short CPU spikes during decode and encode\n- memory usage can rise well above compressed input size while the image is fully decoded\n- SMB-backed reads add their own latency before conversion even starts\n\nThat is why preview regressions for large HEIC or TIFF files often need both backend and user-facing verification.\n\n### Future Extension Points\n\nThe current conversion path leaves room for later enhancements such as:\n\n- caching converted preview outputs\n- queueing especially large conversions\n- dedicated thumbnail generation\n- richer multi-page image handling\n- conversion metrics for operational monitoring\n\nThose are extension points, not assumptions the current product already guarantees.\n\nThe highest-risk mistake is still registry drift. If the backend and frontend disagree about extensions or MIME types, preview behavior becomes unreliable in ways that are easy to miss until users hit them.\n\n## Common Failure Modes\n\n- backend and frontend MIME types do not match\n- a format is marked browser-native when it really needs conversion\n- a viewer component is not registered even though the type is recognized\n- a conversion change improves one format but breaks gallery behavior, download semantics, or mobile viewing\n\n## Validation Expectations\n\nWhen you change viewer or file-type behavior, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd backend \u0026\u0026 pytest -v\n```\n\nIf the change is image-conversion-specific, include the relevant backend tests around image conversion and preview behavior.\n", "2.0": "+++\ntitle = \"Viewer Architecture and Preview Contracts\"\n+++\n\nPreview behavior in Sambee is a cross-boundary contract, not just a frontend component choice.\n\n## The Core Contract\n\nThe browser app decides how to render a file based on metadata and file-type information, but that depends on server-side classification staying aligned.\n\nThree rules matter most:\n\n- the backend and frontend file-type registries must describe the same extensions and MIME types\n- the backend decides whether an image format needs server-side conversion for browser compatibility\n- the frontend chooses the right viewer component and file icon based on the effective file type and MIME information it receives\n\n## Where the Main Decisions Live\n\n| Path | Responsibility |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | backend source of truth for extensions, MIME types, categories, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | frontend source of truth for extensions, MIME types, categories, viewer components, icons, and colors |\n| `frontend/src/components/Viewer/` | viewer components and shared viewer UI |\n| `backend/app/services/image_converter.py` | server-side conversion for non-browser-native image formats |\n\n## Viewer Selection Model\n\nAt a high level, the preview pipeline works like this:\n\n1. the backend determines file category and MIME behavior\n2. the backend decides whether the file can stream as-is or needs image conversion\n3. the frontend maps the file type to the appropriate viewer component\n4. the shared viewer controls keep the toolbar and common behavior consistent across viewers\n\nThat is why a file-type change almost always touches both backend and frontend code.\n\n## Browser-Native Versus Server-Converted Images\n\nSambee supports both browser-native formats and formats that need server-side conversion.\n\n- browser-native formats can be sent to the viewer directly\n- non-browser-native image formats are converted on the server before the browser renders them\n- special cases such as transparency preservation can change the output format choice\n\nIf you change conversion rules, you are changing a product contract, not just an implementation detail.\n\n### Server-Side Conversion Contract\n\nThe conversion path is owned by `backend/app/services/image_converter.py` and is exercised through the viewer API.\n\nThe backend conversion service is responsible for:\n\n- deciding whether an image needs processing\n- converting unsupported or impractical browser formats into a viewer-safe output format\n- preserving transparency where the output contract requires it\n- applying optional downscaling so one preview request cannot explode memory usage casually\n- returning enough metadata for the viewer endpoint to send the correct MIME type back to the browser\n\nRepresentative service responsibilities include:\n\n- `needs_processing(filename)`\n- `convert_image_for_viewer(...)`\n- `is_image_file(filename)`\n- `get_image_info(...)`\n\nThe viewer endpoint then follows this rule:\n\n- if the image can stream safely as-is, return a streaming response\n- if it requires conversion, read it, convert it, and return the converted bytes with the converted MIME type\n\nThat means preview behavior for formats such as TIFF, HEIC, BMP, ICO, and similar formats depends on backend conversion policy, not just on frontend MIME recognition.\n\n### Local-Drive Preview Policy\n\nThe Companion serves local-drive files and archive members as raw bytes. It does not copy local content to the backend for processing and does not bundle the backend image or PDF processing stack.\n\n- Browser-native images, text files, and original PDFs can preview from their raw local bytes.\n- Image formats that require server-side conversion, such as TIFF, HEIC, PSD, JPEG XL, and scientific image formats, show an explicit preview-unavailable state for local drives.\n- Image resizing and PDF compatibility normalization are unavailable for local drives.\n- Downloading and opening the original file locally remain available when a local preview is unavailable.\n\nThe frontend resolves these capabilities before making a local viewer request. Local archive-member requests use the Companion's strict raw-stream contract, while SMB archive-member requests retain the full conversion and PDF-normalization request parameters.\n\n### Output Format Rules\n\nThe backend does not always convert everything to the same output type.\n\n- JPEG is the common output for opaque images\n- PNG remains important when transparency must be preserved\n- ICO-like transparency handling is therefore different from ordinary opaque-photo conversion\n- alpha-bearing formats converted to JPEG need explicit compositing behavior rather than silent accidental loss\n\nIf you change those rules, check both visual correctness and user-facing assumptions such as download behavior and gallery continuity.\n\n### Current Format-Specific Preview Semantics\n\nSeveral converted-image families have product-specific preview semantics that contributors should preserve unless the product intentionally changes.\n\n- multi-page TIFF currently previews the first page rather than exposing a document-style page stack\n- PSD and PSB preview the flattened composite instead of surfacing layer-edit semantics through the browser viewer\n- EPS and AI are rasterized through the preprocessing path at high quality, currently using the 300 DPI rendering baseline\n- HDR-oriented formats such as EXR and Radiance HDR are tone-mapped into ordinary browser-display output\n- whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF preview as an overview or first practical pyramid level rather than as a full pathology viewer\n- FITS and similar scientific-image formats apply visibility scaling so low-level pixel values become inspectable in a normal browser image surface\n\nThese are not accidental implementation details. They define what users should expect from preview and therefore belong to the product contract.\n\n### Resizing and Resource Limits\n\nServer-side conversion can consume significant memory because the file must be read, decoded, and re-encoded.\n\nThe current contract therefore includes:\n\n- configurable JPEG-quality behavior\n- maximum-dimension downscaling to avoid unbounded preview size\n- backend-side protection against excessive memory usage from large source images\n\nContributors should treat those limits as operational safety controls, not as arbitrary defaults.\n\n### Dependency and Environment Expectations\n\nThe conversion path depends on reviewed Python and system-image libraries.\n\nThat includes the normal image stack plus HEIC/HEIF support through the reviewed dependency chain and corresponding system libraries in the container or runtime image.\n\nWhen conversion support seems to disappear unexpectedly, check:\n\n- the backend Python dependency set\n- the container or host system-image libraries\n- whether the format-specific support was actually installed in the current environment\n\n### Preprocessor Registry for Exotic Formats\n\nSome formats need a preprocessing step before the normal conversion path can handle them at all.\n\nThat registry lives in:\n\n- `backend/app/services/preprocessor.py`\n\nIt is consumed by:\n\n- `backend/app/services/image_converter.py`\n\nThe preprocessor layer exists for formats that libvips should not or cannot decode directly for Sambee's preview contract.\n\nCurrent registered formats route through the ImageMagick-backed preprocessor:\n\n- `.psd`\n- `.psb`\n- `.eps`\n- `.ai`\n\nThe registry is the single source of truth for which extensions require preprocessing before the final viewer-safe conversion step.\n\nFor the backend service architecture behind that path, continue to [Image Preprocessing and Conversion Pipeline](../../backend-architecture/image-preprocessing-and-conversion-pipeline/).\n\nRepresentative registry operations include:\n\n- `PreprocessorRegistry.requires_preprocessing(extension)`\n- `PreprocessorRegistry.get_preprocessor_for_format(extension)`\n- `PreprocessorRegistry.get_supported_formats()`\n- `PreprocessorRegistry.register_format(extension, preprocessor_class)`\n\n### Preprocessor Design Rules\n\nThe preprocessor layer has its own constraints:\n\n- one registry entry per preprocessable extension\n- direct in-memory conversion to the final browser-ready format rather than chained intermediate formats\n- no shell-mediated fallback chain logic in the registry itself\n- input validation and timeout enforcement happen in the preprocessor layer\n- failures should surface as explicit preprocessing or conversion errors rather than silent format drift\n\nThe main abstraction is `PreprocessorInterface`, with `ImageMagickPreprocessor` as the current built-in implementation.\n\n### Adding a New Preprocessed Format\n\nIf a new format cannot be handled by the normal conversion stack directly:\n\n1. implement a `PreprocessorInterface` subclass if the existing preprocessor is not appropriate\n2. register the extension in `PreprocessorRegistry`\n3. add or update file-type metadata if the format becomes user-visible in preview flows\n4. add tests for format recognition, tool availability, validation, and successful conversion\n\nDo not treat preprocessable formats as ordinary file-type additions. They change the backend conversion pipeline itself.\n\n### Error Surface Contributors Must Preserve\n\nConversion failures are user-visible API behavior, not internal-only exceptions.\n\nTypical outcomes include:\n\n- not implemented when the current environment lacks support for a format family\n- unprocessable-content style failures when the file is corrupt or cannot be decoded\n- ordinary backend failures when an unexpected exception escapes the conversion path\n\nThat means error wording, status behavior, and frontend fallback behavior should be reviewed together.\n\n## Shared Viewer UI\n\nThe main viewer toolbar is intentionally centralized in `frontend/src/components/Viewer/ViewerControls.tsx`.\n\nThis is no longer just an image-and-PDF convenience component. It is the canonical control surface for the current full-screen image, PDF, and Markdown viewers.\n\n- shared toolbar layout, styling, keyboard-tooltip behavior, and responsive behavior live in `ViewerControls`\n- each viewer turns features on through configuration and passes only the state objects it needs\n- future viewers should reuse that control shell where possible instead of creating another top-level toolbar implementation\n\n### Control-Surface Model\n\n`ViewerControls` uses a feature-flag configuration plus typed state objects.\n\nThe configuration currently enables these capability groups:\n\n- `navigation` for gallery-style previous and next navigation\n- `pageNavigation` for PDF page input and page stepping\n- `zoom` for viewer-managed zoom actions\n- `rotation` for image and PDF rotation actions\n- `search` for the shared search row and match navigation affordances\n- `download` for explicit download actions\n- `share` for mobile-first share actions\n\nThe component then accepts matching state surfaces:\n\n- `NavigationState` for item index, total items, and next or previous handlers\n- `PageNavigationState` for current page, total pages, and page-change handling\n- `ZoomState` for zoom-in and zoom-out handlers\n- `RotationState` for rotate-left and rotate-right handlers\n- `SearchState` for search text, match counts, search-panel state, open or close callbacks, and viewer-specific search navigation\n\nThat split matters because `ViewerControls` owns the common UI, but it does not own viewer logic. It renders controls and delegates behavior back to the viewer that actually knows how to navigate pages, zoom, rotate, or search.\n\n### Current Consumers\n\nThe current shared-toolbar consumers are:\n\n- `ImageViewer`, which enables gallery navigation, zoom, rotation, download, and optional mobile share\n- `PDFViewer`, which enables page navigation, zoom, rotation, search, download, and optional mobile share\n- `MarkdownViewer`, which reuses the same shell for download, optional mobile share, shared search UI, and viewer-specific action buttons such as editing flows\n\n`ViewerControls` also supports generic toolbar actions through the `actions` prop, which can render either text buttons or icon buttons. That is what allows Markdown-specific actions to live inside the same shared toolbar instead of forcing a second toolbar implementation.\n\n### Search UI Versus Search Engine\n\nThe search row is shared, but the search backend is viewer-specific.\n\n- `PDFViewer` wires the search controls to PDF text extraction, page-aware match tracking, and PDF-specific next or previous navigation. Its text-layer markers use `frontend/src/utils/domTextSearch.ts`.\n- Rendered Markdown uses a preview-owned session in `frontend/src/utils/viewportDomTextSearch.ts`. It reuses the DOM index and matcher from `domTextSearch.ts`, preserving rendered-text boundaries, cross-inline matches and exact code whitespace.\n- Markdown edit mode doesn't reuse the rendered-view DOM search implementation. It bridges the same outer toolbar UI into the editor-specific search state and commands instead.\n\nThe Markdown preview separates logical matches from their presentation. It retains exact match positions and text-node mappings, but paints at most 1,000 viewport search ranges plus one active-match range through CSS Highlights. Search doesn't insert markers, split text nodes or replace preview content. Navigation resolves the destination directly from the index and scrolls the content viewport, including for off-screen matches.\n\nEach preview generation owns its search session. Query changes reuse the unchanged DOM index; text replacement or character-data changes invalidate it. Syntax painting and theme-variable changes don't invalidate it. Scroll, resize, image loading and font readiness refresh presentation without matching the document again. Disposing the preview removes its highlights, style, observers, listeners, cached text and pending animation frame. PDF search remains independent.\n\nDOM capture collects text chunks and joins them once, preserving numeric offsets and block separators without repeatedly flattening the growing source. Syntax publication separately caps its viewport ranges and clips horizontally overflowing unwrapped code to visible columns. Both search and syntax skip vertical character-range lookup when the owning text box is wholly inside the viewport; partially clipped boxes retain exact boundary lookup. Horizontal clipping is independent of that fast path: the left lookup can stop at the first character, and the right lookup reuses the exact left boundary as its lower bound. Disjoint horizontal clips produce no ranges. These optimizations don't estimate character widths or cache geometry. Nested code-block scrolling refreshes syntax and search ranges without changing the source or search index.\n\nSearch highlight colors inherit the preview's scoped theme variables. Browsers without CSS Highlights retain counts and indexed navigation without visual search highlighting; the viewer logs that limitation rather than falling back to whole-document marker insertion. Browser support and whole-viewer performance acceptance remain separate rollout gates. Cached indexing doesn't guarantee responsive capture or rendering for arbitrarily large documents.\n\nUse the existing production-viewer check in `frontend/e2e/markdown-viewer.spec.ts` to attribute performance within the ReactMarkdown path. Its User Timing entries separate preview-search lookup, geometry, scrolling and publication from syntax mapping, geometry, range construction and publication. Geometry reads may force layout; registry calls can include native browser work, but don't necessarily include deferred painting. Worker round trips include transfer and acknowledgements, not just parsing. Source-response, DOM-commit-observer and frame milestones narrow initial-load costs without claiming isolated React CPU or hardware input-to-visible-paint latency. Functional passes don't establish the responsiveness budgets.\n\nInitial-load Markdown normalization runs through the existing preparation worker in `frontend/src/utils/markdownCodePreparation.ts`. Each load owns a worker and transfers source, canonical text and an equivalent canonical MDAST in acknowledged, bounded chunks. Tree batches contain at most 512 records and 16,384 string UTF-16 units; individual field pieces are at most 2,048 units. Numeric/flag/position metadata is validated separately, and large text and table alignment fields use the chunk channel instead of content limits. Host acknowledgements yield between tree batches. Success, cancellation, decode failure and timeout terminate the worker; aborted loads can't publish content. Worker failures use the existing load-error path without a synchronous retry, and local preparation failures aren't reported as server overload. The pre-app capability gate requires a callable Web Worker API and otherwise shows the existing unsupported-browser screen without importing the app. The helper retains defensive synchronous normalization with a diagnostic, but Worker-less app operation isn't supported. API presence doesn't guarantee successful worker construction or execution; existing startup, timeout, crash and decode-error handling remains necessary. The shared protocol is DOM-free. Vite's shared resolver aliases the character decoder to its non-DOM implementation before dependency optimization, so development and production workers use the same implementation. A worker-build-only resolver isn't sufficient for development's prebundled dependencies.\n\nReactMarkdown remains the only application whole-document renderer in every build mode. Its parser hook reuses a defensive clone of the prepared tree only when the tree matches the preview generation's exact source. All normal remark transforms, GFM, table-cell break handling, safe URL/raw HTML behavior and React rendering remain in that path. Cloning prevents those transforms from mutating the retained canonical tree. A successful Save that changes the source releases the superseded tree; edited content without a matching tree uses the normal parser.\n\nRendered Markdown sources of at least 50,000 UTF-16 units use `ProgressiveMarkdown` to append the existing pipeline's fully transformed output. Document-wide references, headings and GFM are resolved once before staging. Chunks aren't parsed as independent Markdown documents. Ordinary sources keep their immediate rendering path. Staged batches use the same ReactMarkdown rendering and safe-link/raw-HTML handling, with at most 1,024 structural nodes or 8,192 text units. Oversized tables, containers and code blocks are subdivided internally, preserving one native table or code block rather than splitting it into separate documents. Already-published nodes aren't replaced by later appends.\n\nThe viewer targets two viewport heights for the initial fill, then yields. Later frames use the 4 ms elapsed-work target without a height limit or repeated per-batch geometry reads. Each frame commits at most four batches, checking elapsed time after every commit to bound work accumulated before native layout. Neither the fill target nor these limits guarantee a maximum task duration: whole-document cloning/transforms, a single commit and native layout remain synchronous. Visible pages use animation frames; hidden pages use timers so completion doesn't wait indefinitely for a frame. Source or rendering-configuration changes and disposal cancel the old publication owner; a restarted generation resets document readiness. A 200 ms delayed, accessible loading indicator disappears immediately on completion and respects reduced motion.\n\nReading published text and closing the viewer remain available during progressive loading. Document search/counts, editing, heading-link navigation and toolbar printing wait for complete publication; syntax painting and DOM search indexing also wait. Browser-menu printing while loading shows a loading notice instead of partial document content. Once complete, normal native selection, search, links and print behavior apply. These controls prevent partial results from being presented as complete; they don't promise that synchronous preparation can never block input.\n\nMarkdown editing reuses the preparation worker for full-document canonical normalization when the editor source contains `\u003cbr`. The existing no-`\u003cbr` typing path still publishes immediately without normalization. If both the original baseline and edited document contain possible table syntax, a background preservation-only job compares their tables without changing that typing normalization policy. Identical sources or documents without a pipe character need no table comparison. Each editor owns at most one active job and one replaceable latest request. Only the current source, baseline, policy and generation can satisfy a prepared snapshot; obsolete success, failure and diagnostic messages are ignored. Worker acknowledgements never replace the native CodeMirror document, recreate table-cell editors or change transaction history. Pending table/IME publication and worker preparation keep the viewer dirty independently of canonical draft publication. External source changes and unmount dispose the old owner and its workers; a baseline change invalidates unmatched prepared bytes.\n\nToolbar Save takes focus before its click handler captures selection. The rich editor therefore remembers the active nested table cell on native focus entry and departure, and refreshes that snapshot when selection is explicitly preserved inside the editor. Stay-edit Save restores the same connected cell within the current root instead of focusing the root and triggering native table-widget reconstruction. If the cell document changed while Save was pending, restoration keeps its newer native selection rather than replaying old offsets. Returning to root-text editing, replacing the external document and unmounting clear the remembered cell; disconnected or replaced cells use the existing root-selection fallback. This doesn't change native transactions, history grouping or composition handling. Production checks require retained cell identity/focus after Save, continued typing, and native undo/redo; these functional checks don't establish responsiveness acceptance.\n\nAsync snapshot capture flushes table/IME publication and worker preparation within the existing transition deadline. It requires full-document normalization even after the typing fast path, so Save retains list, escape and table canonicalization. The same worker performs the unchanged AST-aware table comparison against the exact original baseline, preserving original source for semantically unchanged tables. Source and baseline transfer sequentially in acknowledged chunks of at most 16,384 UTF-16 units, with generation and sequence validation; result chunks retain the same bound. Edit preparation doesn't request a preview tree, whose offsets would no longer match preserved source. Save consumes immutable, complete source-preserving snapshot bytes; repeated serialization returns the captured string without parsing. A successful write acknowledges only its snapshot: newer pending edits stay dirty, and an unavailable newer snapshot doesn't turn the completed write into a failure. Worker failure preserves editing and dirty content; a subsequent explicit async snapshot request can retry, but failures never trigger a synchronous parsing fallback or an automatic retry loop.\n\nSynchronous snapshot capture and canonical getters reject pending or failed worker preparation, including an unmatched source-preservation baseline, rather than returning an older revision as current. Recovery retains its synchronous pagehide/pre-sign-in attempts, debounce and limits; failed capture logs the failure and shows the existing recovery warning. It doesn't mark content saved. Native text sharing is unavailable while publication is pending and reads a complete snapshot when ready. Worker-side normalization and source preservation don't establish whole-viewer timing or resource acceptance; native table editing, layout and preview reconstruction remain separately measured costs.\n\nThe bounded `sambee:edit-preparation:*` entries separate queue wait, worker startup/first acknowledgement, source and baseline transfers, run-to-first-result, result delivery, total transport/job time and complete async snapshot flush. Numeric metadata records generation, source/baseline lengths, policy, chunk counts and whether a completed job is current or obsolete; it contains no source text. Transport completion also reports worker normalization and source-preservation durations separately. Host intervals include event-loop scheduling and acknowledgement delays, so startup isn't isolated worker boot time and transfer isn't pure wire time. Worker durations aren't main-thread CPU, and nested intervals mustn't be added to their enclosing job or snapshot flush. Each stage retains only its latest entry; the existing test observer collects individual samples. Use these measurements to distinguish Save wait from the native table/focus work that can follow write acknowledgement, not to infer a faster Save or passing keyboard/paint budgets from worker offload alone.\n\nThe bounded `sambee:preview-preparation:*` entries separate asynchronous decode elapsed time, load normalization, tree cloning, code-block collection and ReactMarkdown transforms. `load-normalization-elapsed` includes worker startup, transfer, work, host tree assembly, acknowledgements and scheduling, not main-thread CPU time. `render-prepared-tree` measures the defensive clone; `render-parse` measures normal parsing when no matching tree is available. The initial-load production matrix requires the clone stage and rejects synchronous `render-parse` and standalone `collection-parse` stages. Live syntax request collection walks the renderer's existing tree; it doesn't parse source again or change markup. The `collection-walk` interval is included in `render-transform`, not additional time to sum. Each generation publishes its ordered requests after DOM commit, before the passive syntax preparation effect, which snapshots them and retains cancellation and stale-generation guards.\n\nThe HAST-ready-to-layout-effect interval includes element construction, reconciliation, commit and scheduling, not just React CPU or paint. Entries contain no source text; each stage retains its latest measurement while the browser test observer collects individual samples. Normalization reuses its parsed tree when canonicalization leaves the source unchanged and reparses in the worker when edits change source offsets. Tree reuse doesn't close responsiveness, retained-memory, syntax-completion or native interaction acceptance.\n\nThat separation is an important contract: contributors should reuse the shared search UI when possible, but should not assume every viewer can use the same search implementation under the hood.\n\n### Single-Renderer Acceptance\n\nThe retained whole-document viewer integration and its special build-mode selection have been removed. Don't reconnect the historical publisher or add a second renderer to finish shared highlighting. Reuse ReactMarkdown, its parsed-tree code collection, the existing workers and viewport CSS highlights. Standalone renderer proofs are historical research, not application acceptance or a delivery dependency.\n\nRun `npm run build`, then `SAMBEE_E2E_PRODUCTION=1 SAMBEE_E2E_BUDGETS=1 npm run test:e2e:all -- --grep 'production syntax publication' --workers=1 --repeat-each=3` from `frontend/`. The existing matrix uses the approved demo connection and unchanged dense, near-safeguard, host-envelope, many-block and long-line fixtures in Chromium and Firefox at desktop and narrow widths. Add `PLAYWRIGHT_JSON_OUTPUT_FILE=/tmp/sambee-reactmarkdown-baseline.json` and `--reporter=json` to retain structured reports without npm's console preamble. Each fixture attaches `viewer-timing-budgets.json`, with observed values, numeric targets, pass/fail results and criteria that remain unmeasured.\n\nThe timing gate evaluates file-click-to-text-completion, first exact search, changed query, last-match navigation and maximum viewer timer-service gap. Missing, non-finite or negative samples fail every run; `SAMBEE_E2E_BUDGETS=1` also fails over-budget samples. Omit that flag for functional-only runs, which still attach the budget result. Forced-GC and tracing runs are marked diagnostic and can't enforce timing acceptance. Run `npm run test -- src/utils/__tests__/viewerPerformanceBudgets.test.ts` from `frontend/` for the evaluator's boundary and error tests. These browser-independent checks also run in the normal Vitest CI suite, without repeating them for each browser project. To validate a recorded report, the existing Playwright entry point remains available: `SAMBEE_E2E_PRODUCTION=1 SAMBEE_E2E_REPORT=/tmp/report.json SAMBEE_E2E_SLICE=publication npm run test:e2e -- viewer-performance-budgets.spec.ts --workers=1`.\n\nSearch/query/navigation probes start in browser event handlers, observe the expected count and active highlight in the existing small search controls, and finish after two frames. They avoid page-wide text queries and Playwright round-trip timing, but aren't hardware input-to-visible-paint measurements. The existing active-search fixture deliberately holds syntax preparation; text-load completion doesn't include syntax. Fresh/cached grammar isolation, first usable text/highlight completion, source editing, large prose/tables, resource acceptance and native interaction still require their own evidence. A passing timing subset isn't full rollout acceptance.\n\nThe browser checks compare exact rendered text, native Select All, selected code text and accessibility-tree output. They also exercise keyboard focus, safe links/HTML, GFM tables/tasks, shared Find navigation, theme-variable updates without text-node replacement, native copy events and Chromium PDF generation. These don't establish OS clipboard payloads, browser-native Find reveal, assistive-technology behavior or visual full-document print/PDF correctness. Those remain manual gates.\n\nThe separate native-constraint slice checks representative multiline, long-line and nested Markdown at widths 1543/390 in Chromium/Firefox. It compares cross-block selected text with a trusted keyboard copy/paste payload, exercises keyboard focus and native `window.find` selection/reveal, and attaches real Chromium PDFs. The native text-find API isn't the browser Find toolbar, and a narrow desktop viewport isn't a physical phone. From `frontend/`, after a normal production build, run:\n\n```sh\nPLAYWRIGHT_JSON_OUTPUT_FILE=/tmp/sambee-native-constraints.json SAMBEE_E2E_PRODUCTION=1 npm run test:e2e:all -- --grep 'production native Markdown constraints' --workers=1 --reporter=json\n```\n\nFrom the repository root, check the attached PDF text with the existing backend environment:\n\n```sh\nbackend/.venv/bin/python -m scripts.check_native_markdown_pdf /tmp/sambee-native-constraints.json\n```\n\nThe checker rejects missing/duplicate PDF cases, unsuccessful browser results and missing rendered-document lines. Heading IDs use a safe prefix and standard duplicate/Unicode slugging in the existing HAST pipeline; matching fragments are rewritten consistently. Native and printing matrices have independent checks. Chromium's `window.find` reveal is diagnostic-only because it can select without scrolling even outside Sambee; exact selection remains required in both engines, and Firefox reveal remains enforced. Don't add application scrolling to manufacture a native Find pass.\n\nThe Markdown preview's Print icon calls the native browser print dialog; Save as PDF is a destination in that dialog, not a second renderer or server-side conversion. Print isn't offered in edit mode or enabled while loading has failed or is incomplete. Print-only styles hide controls/background UI, release fullscreen/scroll constraints, wrap code/table cells, retain images and use black text on white regardless of the screen theme. Native `beforeprint`/`afterprint` handlers preserve focus, selection and nested scroll, with pending callbacks removed on disposal. The fullscreen paper sizes against its fixed container rather than dynamic viewport units that can retain print-page dimensions.\n\nRun the independent print matrix from `frontend/`, then inspect the PDF attachments from the repository root:\n\n```sh\nPLAYWRIGHT_JSON_OUTPUT_FILE=/tmp/sambee-markdown-printing.json SAMBEE_E2E_PRODUCTION=1 npm run test:e2e:all -- --grep 'production Markdown printing' --workers=1 --reporter=json\n```\n\n```sh\nbackend/.venv/bin/python -m scripts.check_native_markdown_pdf /tmp/sambee-markdown-printing.json --printing\n```\n\nThe 24-case matrix covers three fixtures, both themes, both widths and both engines. It verifies action invocation, print CSS, wrapping/widths and actual Chromium PDF state restoration. The PDF gate requires all 12 Chromium outputs to contain every rendered non-whitespace text line and an embedded image. Clear any forced screen-media override before PDF generation; otherwise Playwright prints screen CSS. First/last-page raster inspection supplements text checks. Firefox CSS checks aren't actual Firefox PDF evidence. Actual Firefox PDF and desktop/physical printing were separately confirmed complete by the user on 2026-10-24; no detailed browser/printer support matrix is inferred. Browser destination, paper, margin and header/footer settings remain user-controlled.\n\nKeep performance changes local to measured costs in the current path. Distinguish first visible syntax from completion of all block preparation, and include serialization and parent updates when measuring typing or atomic replace-all. Configuration-only theme and grammar updates must not request caret reveal or replace the document, selection or editor. Don't add streaming, scheduling abstractions or new edit protocols without evidence that the existing path misses its target.\n\nThe existing viewer harness also has a `production source responsiveness` slice for the 54,000-unit dense and 6,000-match long-line source fixtures. It verifies bounded worker delivery, one atomic replacement, undo/redo, exact saved file bytes and worker termination. Save assertions decode the complete multipart body received by the isolated test HTTP proxy; Playwright's request snapshot can omit uploaded file bytes. All traffic uses fixtures, never stored demo edits.\n\nLarge Replace All operations may temporarily block the editor while CodeMirror applies their atomic change set. This latency is an accepted limitation under D5, not permission to truncate output, split history or replace the entire document instead of preserving logical changes. Text and Markdown editors share an editor-owned indeterminate replacement indicator. Worker preparation shows it only after 200 ms; completion before that threshold cancels it without a flash. Ordinary literal replacements stay synchronous and aren't given an artificial delay.\n\nBefore a known-heavy apply, the indicator is shown and given two animation-frame callbacks so the browser has a paint opportunity before the native dispatch. The conservative workload gate requires at least 1,000 replacements and at least 50,000 UTF-16 units in the source or inserted payload. Literal commands inspect at most 1,000 matches for this estimate; worker commands use the completed change plan. This isn't a duration prediction: some fast workloads may be classified as heavy, and unexpectedly slow synchronous work cannot reveal a delayed indicator while blocking the main thread. Feedback already visible during preparation also receives a paint opportunity before application. There's no minimum visible duration or delayed completion, and the spinner doesn't promise continued animation or input responsiveness during synchronous apply.\n\nThe same command boundary covers toolbar and keyboard Replace All. Pending replacements reject duplicate invocations. Any introduced yield revalidates the exact document, query, selection and writability; editing or switching state cancels obsolete work rather than applying stale replacements. Failure, timeout, cancellation and editor disposal release the indicator, animation, timers and listeners. Hidden documents don't wait indefinitely for throttled animation frames. The status uses the editor theme, exposes accessible busy/status semantics and respects reduced motion; physical assistive-technology behavior remains a separate manual check.\n\nThe `production replacement feedback` slice checks quick no-flash behavior and captures visible feedback with the original source still present, then releases held frames and verifies atomic undo/redo, exact multipart Save and editor cleanup in both engines at widths 1543/390. Its held-frame evidence is functional, not timing acceptance.\n\nSource edits retain one bounded User Timing entry per stage: `sambee:source-editor:serialize`, `sambee:source-editor:publish`, `sambee:source-editor:normalize` and `sambee:source-editor:parent-update`. The enclosing publication includes normalization and the synchronous parent callback. These overlapping stages mustn't be added together. Entries contain lengths/revisions, not document contents. `sambee:source-search:commit` brackets the native atomic dispatch, including its synchronous listeners; deferred React work isn't isolated CPU time inside that measure. The separate click-to-completion probe waits for the parent dirty-state render and two subsequent frames. That boundary is a scheduling proxy, not hardware paint.\n\nFrom `frontend/`, after a normal production build, run:\n\n```sh\nPLAYWRIGHT_JSON_OUTPUT_FILE=/tmp/sambee-source-responsiveness.json SAMBEE_E2E_PRODUCTION=1 SAMBEE_E2E_BUDGETS=1 npm run test:e2e:all -- --grep 'production source responsiveness' --workers=1 --repeat-each=3 --reporter=json\n```\n\nEach sample attaches source-private measurements and explicit 50 ms atomic-dispatch, enclosing serialization/publication and maximum-timer-gap checks. Missing or invalid evidence fails even without `SAMBEE_E2E_BUDGETS`; that flag additionally enforces the original limits. Retain the failed native atomic-application timing results as diagnostic evidence of the D5 accepted limitation, not as passing samples or a reason to repeat performance-only matrices. Unrelated source timing, worker correctness and resource gates remain required. Transfer counts aren't retained/peak memory evidence, and these fixtures don't establish sustained typing, large-table normalization, dense output expansion or scrolling acceptance.\n\nThe separate `production source typing` slice types 82 characters at a requested 10 ms inter-key delay into each 54,000-unit fixture, without per-key polling. It records trusted browser keydown-to-first/two-frame samples, timer gaps, all four edit stages and optional whole-renderer Long Tasks entries, then verifies exact saved source plus the payload. The `source-typing` attachment enforces two-frame p95 strictly below 50 ms and stage/gap maxima at most 50 ms. All 24 engine/width/repeat trials pass; the worst per-trial p95 is 35 ms. This is a scheduling proxy, not physical input-to-painted-pixel acceptance. Unsupported Long Tasks capability stays unmeasured, and observed tasks wouldn't establish application-owned CPU attribution.\n\nThe `production prose table responsiveness` slice mounts the approved 4,000 formatted paragraphs or 2,400 two-column table rows. It checks every rendered paragraph/cell exactly, preserves native block whitespace, root/text-node identity and full rendered text through 60 programmatic scroll steps, and verifies cross-block native selection and close cleanup. Load timing runs from the browser's file-open click through two frames after all expected blocks mount. The `prose-table-responsiveness` attachment separates load budgets, the earlier two-viewport geometry milestone and diagnostic rAF scroll intervals, including the frame following the final scroll assignment. The final 24 trials complete within 1,110 ms, with the first viewport available within 761 ms. Nineteen trials exceed the unchanged 50 ms timer-gap limit, with a worst gap of 128 ms. These recorded loading pauses are accepted under D6, not passing timing samples or isolated CPU attribution. Headless rAF intervals don't establish physical refresh rate, wheel/touch, compositor or painted-frame acceptance. These fixtures have no fenced syntax and don't measure syntax readiness or large-table source normalization.\n\nThe separate `production progressive Markdown loading cancellation` slice holds frame callbacks after two viewport heights exist. It requires visible feedback, disabled document controls, loading-only print output and a working Close action, then releases stale callbacks and verifies complete reopening. It runs in Chromium and Firefox at widths 1543/390. Its paused screenshots and functional passes aren't timing evidence. The existing large-code publication, native interaction and print matrices remain independent regression checks; their completion and acceptance boundaries are recorded below.\n\nRun these slices separately from forced GC and CPU profiling:\n\n```sh\nPLAYWRIGHT_JSON_OUTPUT_FILE=/tmp/sambee-source-typing.json SAMBEE_E2E_PRODUCTION=1 SAMBEE_E2E_BUDGETS=1 npm run test:e2e:all -- --grep 'production source typing' --workers=1 --repeat-each=3 --reporter=json\nPLAYWRIGHT_JSON_OUTPUT_FILE=/tmp/sambee-prose-table-responsiveness-final.json SAMBEE_E2E_PRODUCTION=1 SAMBEE_E2E_BUDGETS=1 npm run test:e2e:all -- --grep 'production prose table responsiveness' --workers=1 --repeat-each=3 --reporter=json\n```\n\nFor separate Chromium load attribution, select the same prose/table slice with `SAMBEE_E2E_TRACE=1` and no budget enforcement or forced GC. The `viewer-load-cpu-profile` and `viewer-load-timeline` attachments span file open through completed mounting; nonempty CPU samples and both `sambee:viewer-load:start`/`sambee:viewer-load:complete` timeline markers are required. Budget status is diagnostic, never acceptance. Two desktop captures show one preview build, with a 126.05 ms prose render callback and a 53.69 ms table callback before native style/layout. The prose clone, transforms and HAST-to-layout-effect stages take 38.3, 37.5 and 44.5 ms; these overlap the encompassing callback and mustn't be added to it. Prose native style/layout takes a further 21.14/38.13 ms. Keep cached-tree isolation and native document semantics; neither deleting the clone nor an unapproved publication/renderer change is justified by this evidence. Firefox/mobile CPU attribution remains unverified.\n\nChromium CPU sample deltas can be negative. Reconstruct cumulative sample timestamps, sort them, then clip nonoverlapping intervals to the load markers. Summing only positive deltas inflates CPU weights. Use the marker's renderer PID/thread for main-thread timeline attribution; worker processing and unclassified native samples aren't automatically application-owned blocking CPU.\n\nRepeated source-regex Next/Previous requests are queued in order while navigation is pending. The active navigation worker reuses its transferred document for that burst, applying each native CodeMirror command from the preceding result's selection with the current position's whole-word rules. It terminates when the queue drains; no idle worker is retained. Document/query changes, external selection changes, replacement commands, failures and disposal cancel obsolete queued navigation. Unit tests compare reused-worker navigation with native commands, including mixed directions, wraparound, overlapping matches and zero-length expressions.\n\nThe independent `production source regex parity` slice compares counts and exact saved output with the installed CodeMirror commands for zero-length lookahead, case-sensitive and whole-word matching. A replacement exceeding two source-transfer chunks verifies continuation assembly without truncation. `production source regex lifecycle` injects worker-construction, error/decode-event and startup-timeout failures, requires actionable feedback and a successful retry, and preserves continued editing and exact Save bytes. A partial-delivery case lets one replacement chunk arrive before cancellation, then replays stale change/completion messages; no partial replacement may be committed. These are host-side fault injections, not actual browser-process crash or structured-clone failure evidence. Run both functional slices with:\n\n```sh\nSAMBEE_E2E_PRODUCTION=1 npm run test:e2e:all -- --grep 'production source regex (parity|lifecycle)' --workers=1\n```\n\nFor optional source renderer footprint diagnostics, use `SAMBEE_E2E_MEMORY=1` without timing enforcement, select `production source responsiveness`, and run the Chromium-only `npm run test:e2e`. The `source-renderer-memory` attachment records CDP renderer heap after explicit GC at pre-open, counted-results, post-replacement and post-close boundaries. Its historical 64 MiB assertion isn't a release criterion under D11. These are whole-viewer post-GC observations, not isolated result-array bytes, peak/worker/native memory or proof of leak-free cleanup. Staged/peak-memory limits and a fixed close/reopen cycle protocol aren't required. The source budget status is diagnostic in memory mode.\n\nFor a separate Chromium CPU diagnostic, use `SAMBEE_E2E_TRACE=1` without `SAMBEE_E2E_BUDGETS=1`, restrict the grep to `production source responsiveness long-line at 1543px`, and run `npm run test:e2e`. The `source-dispatch-cpu-profile` attachment contains the CDP CPU profile; its source budget status is diagnostic, never an acceptance pass. The source slice rejects combined profiling/GC and either diagnostic mode combined with timing enforcement.\n\nFor separate controlled-memory trials, add `SAMBEE_E2E_MEMORY=1` and restrict the existing matrix to the many-block fixture and Chromium. Release harness-held node references before post-GC sampling. Renderer heap excludes worker heaps and aggregate/native memory; a single close isn't repeated-close leak acceptance. Keep forced GC separate from responsiveness timing.\n\nFor diagnostic scheduling traces, add `SAMBEE_E2E_TRACE=1` to a single-fixture Chromium run. The `viewer-scheduling-trace` attachment contains a CDP timeline and V8 CPU profile. Align `sambee:viewer-trace:start` with browser timestamps; join CPU chunks by renderer PID and profile ID and count samples once. Firefox native profiling must use content-process User Timing markers rather than parent-only samples. Profiling adds overhead and isn't acceptance timing.\n\nTo isolate native table input from application work, run the existing proof from `frontend/`:\n\n```sh\nSAMBEE_NATIVE_TABLE_REPORT=/tmp/sambee-native-table node scripts/source-search-containment-proof.mjs --native-table\n```\n\nThis uses public CodeMirror/Lezer and `markdownTables` APIs at the approved demo URL, with an isolated HTML response and default package styling. It edits the middle cell of the fixed 2,400-row table at 1543x900 without React, application CSS, normalization, Save or workers. It requires exact complete native source, atomic full-table replacement spans, native undo/redo and disposal. Native table source uses `\u003cbr\u003e`; application canonicalization to `\u003cbr /\u003e` isn't part of this proof. Root state materialization and view-update intervals are reported separately; input-to-root includes scheduling and deferred publication, not just model CPU. The unminified desktop diagnostic isn't a production acceptance trial or a replacement for mobile, composition and lifecycle checks.\n\nThe optional report prefix writes per-engine JSON and the exact diagnostic bundle. For separate profiling, add `SAMBEE_E2E_TRACE=1` and configure `MOZ_PROFILER_STARTUP=1`, `MOZ_PROFILER_STARTUP_FILTERS=GeckoMain`, `MOZ_PROFILER_STARTUP_FEATURES=js,stackwalk,leaf` and `MOZ_PROFILER_SHUTDOWN` with an absolute output path. Chromium records input-only CPU samples; clip Firefox content-process samples between `sambee:native-table:input-start` and `sambee:native-table:input-end`, excluding construction and history checks. Profiling requires a report prefix and Firefox startup configuration; product-budget enforcement and controlled-GC modes are rejected. Inclusive model, parsing and native reflow samples overlap and mustn't be summed. Unclassified Chromium native samples aren't automatically package JavaScript CPU. Slow native input doesn't by itself establish slow atomic state application or justify private package patches, changed history, wrapping or selection semantics.\n\nCount assertions remain scoped to the existing search controls to avoid page-wide Playwright text caches inside measurement windows. Results are labelled `scoped-controls-v2`; older input figures aren't directly comparable. Handler-to-frame samples and synthetic event age don't establish hardware input-to-visible-paint latency. Removing the alternate renderer doesn't close any performance, memory or manual interaction gate.\n\n### Shared Highlighting Acceptance And Limitations\n\nThe shared-highlighting implementation was approved by the user for merge and rollout on 2026-10-24. Approval doesn't turn failed measurements into passes or establish support for untested devices. Keep original targets, raw verdicts and these scoped acceptance decisions together:\n\n| Decision | Accepted scope | Boundaries |\n|---|---|---|\n| D5 | Noticeable large atomic Replace All latency with visible busy feedback. | Preserve complete output, logical change mapping, one native transaction and undo/redo. Unrelated source-search or typing pauses aren't accepted by this decision. |\n| D6 | The recorded progressive prose/table preview-loading pauses: 19/24 trials above 50 ms, worst 128 ms; all complete within 1,110 ms. | These remain failed gap samples. Longer future delays and other workloads aren't covered. Asynchronous preview preparation remains declined. |\n| D8 | Responsiveness limitations of the existing Markdown table editor. | Table-component timing is diagnostic and non-blocking; exact input, Save, composition, history and cleanup remain required. |\n| D9 | Ten recorded Firefox many-block syntax-color samples at 1,511-1,579 ms against the 1,500 ms target. | All 120 cold/warm samples were collected; 110 meet that target. Full syntax preparation stays within 3,000 ms. No broader delay exception is implied. |\n| D10 | Four recorded Firefox desktop code-display gaps at 51-59 ms against 50 ms. | Preserve the raw failures. Additional delayed-image/font/resize and scroll-anchor test coverage was removed, not passed. Correct content, selection and scrolling remain required. |\n| D11 | Leak investigation and fixes for demonstrated unwanted retention, rather than quantitative memory acceptance. | Staged/peak-memory limits and fixed-cycle shutdown checks were removed, not passed. No exhaustive leak-free claim is made. |\n| D12 | Removal of real-phone and physical keyboard/IME acceptance, including phone print UI and hardware-response measurements. | This isn't verified device support. Automated keyboard/composition, exact editing/Save/recovery and desktop native/print correctness remain required. |\n\nBrowser-menu Find/reveal, OS clipboard, assistive-technology and physical-scrolling checks were confirmed complete by the user on 2026-10-23. Remaining Firefox PDF and desktop/physical printing checks were confirmed complete on 2026-10-24. These are user confirmations, not new automated measurements or a detailed device, browser, AT or printer support matrix. Don't reopen completed checks or rerun accepted timing failures solely to close a checklist; retest affected behavior after a relevant change or demonstrated regression.\n\nThe final editing checks cover theme changes followed by editing exit and Close, late worker results, distinct documents, captured-revision Save with newer dirty edits, failed writes and recovery/snapshot failures. Source-regex terminal cleanup detaches worker handlers, releases terminated workers and clears obsolete replacement buffers, while retaining buffers needed for a pending atomic apply. Ownership review and lifecycle assertions establish the investigated cleanup, not a heap-retention proof for every browser object.\n\nUse `PLAYWRIGHT_JSON_OUTPUT_FILE`, not `PLAYWRIGHT_JSON_OUTPUT_NAME`, for an explicit report path with the JSON reporter. Preserve complete identities, both engines, widths 1543/390, original workloads and three trials per timing identity. Recorded-report evaluation must retain failed samples and reject missing, duplicate, invalid, skipped or retried identities. Functional-only runs and tracing/GC diagnostics don't establish timing passes. Retain local reports before temporary-file cleanup; overlapping runs aren't additive test totals.\n\n### Responsive and Accessibility Rules\n\nThe centralized toolbar also encodes product behavior that should stay consistent across viewers.\n\n- filename display, optional filename adornments, and close behavior are shared\n- mobile layout uses safe-area-aware spacing and smaller controls\n- gallery arrows and desktop zoom controls are intentionally reduced on mobile, where gesture-based interaction is preferred\n- share is exposed as a mobile-first affordance, with optional early-intent warming through `onShareIntent`\n- buttons use explicit `aria-label` values and shortcut-oriented `title` text so the control surface remains navigable and self-describing\n- the shared search row manages focus when it opens and preserves consistent close behavior for toggle and Escape-driven exits\n\n### Legacy Components and Contributor Guidance\n\nLegacy `ImageControls.tsx` and `PDFControls.tsx` files still exist in the frontend tree, but `ViewerControls` is the current architectural direction and the shared component used by the active image, PDF, and Markdown viewers.\n\nIf you add another viewer or extend an existing one:\n\n- prefer extending `ViewerControlsConfig`, the relevant state interfaces, or the generic `actions` surface\n- keep viewer-specific logic in the viewer component rather than teaching `ViewerControls` about file-format internals\n- preserve shared mobile, accessibility, and search-panel behavior unless the product intentionally changes that contract\n- add or update focused tests in `frontend/src/components/Viewer/__tests__/ViewerControls.test.tsx` when the shared toolbar contract changes\n\n## Adding a New File Type Safely\n\nFile-type support is registry-driven. The safest way to add a new type is to treat backend and frontend changes as one contract update.\n\n### Main Files to Change\n\n| Path | Why it changes |\n|---|---|\n| `backend/app/utils/file_type_registry.py` | declare extensions, MIME types, category, description, and whether an image requires conversion |\n| `frontend/src/utils/FileTypeRegistry.ts` | declare extensions, MIME types, category, viewer component, icon, color, and description |\n| `frontend/src/components/Viewer/` | add or reuse a viewer component when the type needs a dedicated preview surface |\n\nIf a file type is user-visible, update the published support docs that describe what Sambee can preview.\n\n### Quick Start for a New Image Format\n\nFor an image format such as JPEG XL, the minimum workflow is:\n\n1. add a `FileTypeDefinition` entry to the backend registry\n2. add the matching entry to the frontend registry\n3. decide whether the image is browser-native or requires server-side conversion\n4. keep extensions and MIME types identical across both registries\n5. run the viewer and backend validation checks\n\nBackend example:\n\n```python\nFileTypeDefinition(\n\t\textensions=(\".jxl\",),\n\t\tmime_types=(\"image/jxl\",),\n\t\tcategory=FileCategory.IMAGE,\n\t\trequires_conversion=True,\n\t\tdescription=\"JPEG XL Image\",\n)\n```\n\nFrontend example:\n\n```typescript\n{\n\textensions: [\".jxl\"],\n\tmimeTypes: [\"image/jxl\"],\n\tcategory: \"image\",\n\tviewerComponent: () =\u003e import(\"../components/Viewer/ImageViewer\"),\n\ticon: \"image\",\n\tcolor: \"#a855f7\",\n\tdescription: \"JPEG XL Image\",\n}\n```\n\nThat registry update is what drives MIME matching, icon treatment, viewer routing, and image-gallery inclusion.\n\n### Backend Registry Rules\n\nBackend file-type definitions must stay explicit and type-safe.\n\n- `extensions` are tuples with a leading dot, such as `(\".jpg\", \".jpeg\")`\n- `mime_types` are tuples of standard MIME strings\n- `category` uses `FileCategory` values such as `IMAGE`, `DOCUMENT`, `TEXT`, `VIDEO`, `AUDIO`, `ARCHIVE`, `CODE`, `SPREADSHEET`, or `OTHER`\n- `requires_conversion` matters for image formats that cannot be rendered directly by the browser\n- `description` should be the human-readable label contributors and users would expect\n\nHow to decide `requires_conversion`:\n\n- set it to `False` for browser-native formats such as PNG, JPEG, GIF, WebP, SVG, and AVIF\n- set it to `True` for formats with limited browser support or formats that are not practical to render directly, such as TIFF, HEIC, BMP, JPEG 2000, or JPEG XL when browser support is not sufficient for the product baseline\n\n### Frontend Registry Rules\n\nFrontend file-type definitions control how the browser app presents the file.\n\n- keep `extensions` and `mimeTypes` aligned with the backend registry\n- set `viewerComponent` to the shared viewer that should render the type\n- choose an icon that matches the product language for that file category\n- choose a color that distinguishes the format without inventing a new palette on every addition\n\nFor image formats, reusing `ImageViewer` is usually enough. For non-image formats, you may need a dedicated viewer such as `PdfViewer`, `VideoViewer`, `AudioViewer`, or `TextViewer`.\n\n### Non-Image File Types\n\nThe overall process is the same for documents, video, audio, text, archives, and code files.\n\n1. add the backend registry entry\n2. add the frontend registry entry\n3. create or reuse the viewer component when preview support exists\n4. verify the file icon, viewer routing, and download behavior\n\nFor non-image files, `requires_conversion` is usually `False`. The main design question is whether the product has a viewer component for that category or should fall back to download-only behavior.\n\n### Integration Checklist\n\nUse this checklist before you consider the file type integrated:\n\n- backend registry entry added\n- frontend registry entry added\n- extensions and MIME types match exactly across both registries\n- browser-native versus converted-image behavior decided intentionally\n- viewer component chosen or added\n- icon and color treatment chosen\n- user-visible support docs updated if the file type changes what Sambee can preview\n\n### Testing Checklist\n\nAfter the registry change, verify:\n\n- icon display in the file browser\n- file opening in the expected viewer\n- shared toolbar behavior if the preview uses `ViewerControls`\n- conversion output if the format is server-converted\n- gallery inclusion for image formats\n- MIME type behavior across extension variants such as upper-case filenames\n- download behavior with the correct MIME type\n- mobile and tablet behavior when the preview is expected to work there\n\nFor server-converted formats, also verify:\n\n- the backend returns the converted MIME type you expect\n- transparency-sensitive formats still render correctly\n- resizing or quality settings do not degrade the preview contract unexpectedly\n- environment-specific format support failures surface in a controlled way\n\nFor preprocessable formats, also verify:\n\n- the registry recognizes the extension regardless of case and leading-dot differences\n- the expected preprocessor is selected for that format\n- missing external-tool support fails cleanly\n- validation and timeout rules behave as intended under bad inputs and slow conversions\n\n### Architecture Notes\n\nThese helper functions are the practical integration points contributors usually touch:\n\n- backend: `get_mime_type`, `needs_processing`, `is_image_file`, `get_file_type_by_extension`, `get_file_type_by_mime`\n- frontend: `getViewerComponent`, `isImageFile`, `getFileIcon`, `getFileTypeByExtension`, `getFileTypeByMime`\n\nAt runtime, the flow is:\n\n1. the backend lists files and assigns MIME information\n2. the frontend receives `FileInfo` data with that MIME information\n3. the frontend chooses icon treatment from filename and type rules\n4. the frontend selects the viewer from MIME and file-type data\n5. the backend routes convertible images through the image-conversion pipeline when needed\n\nThe frontend side still has work to do even when the backend owns the conversion:\n\n- viewer MIME recognition must include the input formats the backend classifies as previewable\n- file-type icon and color treatment must still reflect the original file type rather than the converted transport format\n- browser-side fallback MIME logic must not drift from the backend contract in ways that hide conversion bugs\n\n### Operational Characteristics\n\nServer-side conversion changes the runtime profile of preview requests.\n\n- large images can produce short CPU spikes during decode and encode\n- memory usage can rise well above compressed input size while the image is fully decoded\n- SMB-backed reads add their own latency before conversion even starts\n\nThat is why preview regressions for large HEIC or TIFF files often need both backend and user-facing verification.\n\n### Future Extension Points\n\nThe current conversion path leaves room for later enhancements such as:\n\n- caching converted preview outputs\n- queueing especially large conversions\n- dedicated thumbnail generation\n- richer multi-page image handling\n- conversion metrics for operational monitoring\n\nThose are extension points, not assumptions the current product already guarantees.\n\nThe highest-risk mistake is still registry drift. If the backend and frontend disagree about extensions or MIME types, preview behavior becomes unreliable in ways that are easy to miss until users hit them.\n\n## Common Failure Modes\n\n- backend and frontend MIME types do not match\n- a format is marked browser-native when it really needs conversion\n- a viewer component is not registered even though the type is recognized\n- a conversion change improves one format but breaks gallery behavior, download semantics, or mobile viewing\n\n## Validation Expectations\n\nWhen you change viewer or file-type behavior, usually run:\n\n```bash\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npm run typecheck\ncd frontend \u0026\u0026 npm run lint\ncd backend \u0026\u0026 pytest -v\n```\n\nIf the change is image-conversion-specific, include the relevant backend tests around image conversion and preview behavior.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/frontend-architecture/settings-form-dialog-pattern", "parent_id": "section:developer-guide/frontend-architecture", "depth": 2, "kind": "page", "label": "settings-form-dialog-pattern", "title": "Settings Form Dialog Pattern", "path": "developer-guide/frontend-architecture/settings-form-dialog-pattern", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "authored"}, "1.0": {"state": "branched", "source_version": "0.9", "diff_added": 56, "diff_removed": 26}, "2.0": {"state": "branched", "source_version": "1.0", "diff_added": 57, "diff_removed": 9}}, "content_versions": {"0.9": "+++\ntitle = \"Settings Form Dialog Pattern\"\n+++\n\nUse this pattern for stateful settings editors that create or update configuration. It keeps the same form behavior across a phone drawer, a narrow dialog, and a desktop dialog while avoiding separate mobile and desktop forms.\n\nThe reference implementation is `frontend/src/components/Admin/ConnectionDialog.tsx`.\n\n## When To Use It\n\nUse the pattern when a dialog edits several related settings and needs validation, field descriptions, or more than one action.\n\nDo not use it for a confirmation or destructive-action dialog. Those should continue to use `ResponsiveFormDialog` directly with focused content and actions.\n\n## Dialog Categories\n\nUse `ResponsiveFormDialog` as the shared shell for every ordinary application dialog. It provides the responsive Drawer and Dialog behavior, safe-area action area, dialog surface tokens, title and description relationships, close blocking, and focus restoration.\n\nSmall dialogs use traditional Cancel and confirmation actions; do not add a top-right close button.\n\nChoose the content pattern that matches the job:\n\n| Dialog type | Use | Examples |\n|---|---|---|\n| Multi-field editor | `ResponsiveFormDialog` with the settings form building blocks below. | Connections, users, OIDC configuration, copy or move. |\n| One- or two-field editor | `ResponsiveFormDialog` with a single-column settings surface. Keep the floating MUI label at every width. | Create, rename, copy, and move. |\n| Decision | `ResponsiveFormDialog` with compact content and actions. Do not add `SettingsFormSurface`. | Delete, overwrite conflict, application update, connection test result. |\n| Picker | `ResponsiveFormDialog` with a listbox or selection grid. Keep the picker\u2019s keyboard and selection semantics in the owning component. | Viewer and theme pickers. |\n| Short workflow | `ResponsiveFormDialog` with state-specific body and actions. | Companion pairing. |\n| Full-screen workspace | Keep the specialized full-screen viewer shell. Share only reusable behavior that does not interfere with the viewer\u2019s focus, toolbar, or third-party integration. | Image, PDF, Markdown, and text viewers. |\n\nThe desktop settings overlay and mobile settings drawer are navigation containers, not form dialogs. Keep their information architecture separate while composing settings-form pages inside them.\n\nFor safety-critical decisions, focus the least destructive action after opening. For input workflows, focus the first input. Do not make a destructive action the default Enter action unless the user has already focused it.\n\n## Shared Building Blocks\n\nImport the structural primitives and control styles from `frontend/src/components/Settings/SettingsFormLayout.tsx`.\n\n| Building block | Responsibility |\n|---|---|\n| `SettingsFormSurface` | Provides the muted, rounded background and shared interior padding. It darkens the default background by 4% in light mode and lightens it by 8% in dark mode. |\n| `SettingsFormGroup` | Groups related rows and adds row dividers only at the desktop breakpoint. |\n| `SettingsFormRow` | Uses one column below `md` and the two-column label/control grid at `md` and above. |\n| `SettingsFormFieldLabel` | Renders a desktop label with its description or validation error. |\n| `SettingsFormSection` | Separates groups with the standard settings heading, subdued divider, and spacing. |\n| `SettingsSelectMenuItem` | Renders a select option with a label and supporting description. |\n| `SettingsPasswordVisibilityToggle` | Renders the shared show/hide password adornment. The owning dialog keeps password visibility state and translated labels. |\n| `settingsFormFieldControlSx` | Aligns a control to the desktop control column. |\n| `settingsFormSelectControlSx` | Makes a desktop select content-width and right-aligned. |\n| `settingsFormOutlinedControlSx` | Applies the shared outlined-field, focus, error, and floating-label treatment. |\n| `settingsSelectSx` and `settingsSelectMenuProps` | Keep select values, icons, and options at the standard subdued text color. |\n\nKeep field state, API calls, validation rules, translations, and the concrete MUI controls in the owning dialog. The shared layer owns layout and presentation; it must not become a schema-driven form engine.\n\n## Responsive Contract\n\nMulti-field settings editors have exactly two form layouts. One- and two-field operation dialogs stay single-column at every width so long names and paths retain the available width.\n\n### Below `md`\n\nUse one column in both responsive shells.\n\n- Below `sm`, `ResponsiveFormDialog` renders the form in a Drawer.\n- From `sm` through `\u003cmd`, it renders the same form in a Dialog.\n- Use normal-height MUI outlined controls.\n- Keep MUI labels inside empty fields and floating in the outline after focus or entry.\n- Keep descriptions and validation errors directly below their controls as MUI helper text.\n- Use the grouped surface and section heading, but do not show individual field-row dividers.\n\n### At `md` And Above For Multi-Field Editors\n\nUse the two-column desktop layout.\n\n- Put labels and descriptions in the left column.\n- Put compact controls in the right column.\n- Use the compact MUI `size=\"small\"` variant only when a desktop field has an external label in the left column.\n- Replace the left-column description with the validation error instead of showing helper text below the input.\n- Keep full-width text inputs within the control column.\n- Use content-width, right-aligned selects when the selected option remains readable.\n- For checkboxes and switches, use the external label and description on the left, with the control in the right column. Keep the control label and helper text next to the control below `md`.\n- For boolean settings, use a `Switch` with a visible `On` or `Off` state label. Let Material UI apply its standard palette colors.\n- For native `datetime-local` inputs, preserve the MUI shrunk input label below `md`; use the external desktop label at `md` and above.\n- Show subdued dividers between rows in a group.\n\n## Control Conventions\n\nApply `settingsSelectSx` and `settingsSelectMenuProps` to every settings `Select`. Use `SettingsSelectMenuItem` when an option needs a short explanation below its label.\n\nUse `SettingsPasswordVisibilityToggle` as the end adornment for password fields. Keep its `visible` state, toggle handler, and localized show/hide labels in the owning dialog.\n\nUse `DialogReadOnlyField` for a name, path, connection, or other value that a dialog shows without allowing the user to change it. Give the field a specific label such as `Destination directory` or `File to delete`; do not recreate a styled text pill. Keep the normal MUI field height when its label is inside the outlined field. Use a subdued read-only surface while keeping long values selectable.\n\nWrite the dialog description as the outcome of the selected action. State what will be copied, moved, replaced, skipped, or deleted and name the source item for a single-item operation, then present the affected value in a labelled read-only field. Keep notices tied to their current condition: a no-op destination notice must disappear as soon as a renamed target makes the operation valid, without changing the dialog's layout.\n\n## Implementation Checklist\n\n1. Start with `ResponsiveFormDialog` for the responsive Drawer and Dialog shell.\n2. Wrap the fields in `SettingsFormSurface` and one or more `SettingsFormGroup` components.\n3. Put every field in `SettingsFormRow`.\n4. Use `SettingsFormFieldLabel` only for a multi-field editor at `md` or wider. Keep one- and two-field operation dialogs in a single column with floating MUI labels at every width.\n5. Keep the below-`md` MUI `label`, `InputLabel`, and `FormHelperText` props in the concrete control. Use normal field height for inline-labelled one- or two-field operation dialogs; reserve helper-text space when a field can show a validation error.\n6. Use `SettingsFormSection` between related groups instead of recreating section borders and title spacing locally.\n7. Reuse the shared action styles when the dialog has split or responsive actions.\n8. Render conditional fields or sections only when their state applies, while keeping each visible control in a `SettingsFormRow`.\n\nFor a non-form dialog, start with `ResponsiveFormDialog` and retain only the content, selection, workflow, and keyboard behavior specific to that dialog. Do not duplicate MUI `Dialog`, `Drawer`, sticky mobile actions, focus restoration, or dialog surface styling in the owning component.\n\n## Accessibility And Validation\n\nAssociate desktop controls with their external labels and descriptions using `htmlFor`, `labelId`, and `aria-describedby` as appropriate. Preserve a description ID when an error replaces the description so the relationship remains valid.\n\nAfter a failed save or test, focus the first invalid field. Do not remove normal MUI error states from controls; the desktop error text supplements them by making the issue readable in the label column.\n\nUse field-level errors for validation that the dialog can determine before submitting. Reserve one helper-text line, then replace it with the active error so the form does not shift. Do not repeat a field-owned error in a form-level alert. Error text must explain the cause and the corrective action, not only name a failed rule.\n\nPrefer a safe, valid default over presenting a predictable error when the dialog can infer the intended correction. For example, a one-item copy into its source directory should prefill an extension-aware name such as `report (copy).pdf`. Do not apply this pattern to a same-directory move: it is a rename operation, so the user must deliberately choose the new name.\n\nUse a stable form-level alert only when no editable field owns the remedy, such as a multi-item copy whose destination directory is also its source directory. Use error severity when the state blocks confirmation. Keep API failures in this form-level feedback region as well, above the form surface so they do not disrupt a desktop field row.\n\n## Testing And Review\n\nFor every dialog that adopts this pattern, cover all of the following:\n\n- The mobile Drawer and the `sm` through `\u003cmd` Dialog use the same single-column form semantics.\n- A populated narrow-screen field uses a floating MUI label, normal control height, and helper text below the field.\n- A multi-field editor retains external labels, compact controls, and desktop-only row dividers at `md` and above.\n- A one- or two-field operation dialog remains single-column and keeps floating labels at `md` and above.\n- Errors, focus-first-invalid behavior, keyboard handling, and pending action states still work.\n- The surface, controls, and helper text remain legible in both light and dark themes.\n\nFor every non-form dialog that adopts the shared shell, cover all of the following:\n\n- The phone Drawer has reachable actions above safe-area insets and does not obscure content in a short viewport.\n- Keyboard focus, Enter, Escape cancellation, and the dialog-specific safe default still work. Escape must always issue the dialog's cancellation request.\n- Picker and workflow state remains usable with a keyboard.\n- Dialog content and action states remain legible in light and dark themes.\n\nUse a live browser check at a phone width and a desktop width in addition to focused tests. Check a short viewport as well so the fixed mobile actions do not obscure the final control.\n\n", "1.0": "+++\ntitle = \"Settings Form Dialog Pattern\"\n+++\n\nUse this pattern for stateful settings editors that create or update configuration. It keeps the same form behavior across a phone drawer, a narrow dialog, and a desktop dialog while avoiding separate mobile and desktop forms.\n\nThe reference implementation is `frontend/src/components/Admin/ConnectionDialog.tsx`.\n\n## When To Use It\n\nUse the pattern when a dialog edits several related settings and needs validation, field descriptions, or more than one action.\n\nDo not use it for a confirmation or destructive-action dialog. Those should continue to use `ResponsiveDialogShell` directly with focused content and actions.\n\n## Dialog Categories\n\nUse `ResponsiveDialogShell` from `frontend/src/components/Dialog/ResponsiveDialogShell.tsx` as the shared shell for every ordinary application dialog. It provides responsive Drawer and Dialog behavior, safe-area actions, overlay/form surface tokens, title and description relationships, close blocking, and focus restoration.\n\nSmall dialogs use traditional Cancel and confirmation actions; do not add a top-right close button.\n\nChoose the content pattern that matches the job:\n\n| Dialog type | Use | Examples |\n|---|---|---|\n| Multi-field editor | `ResponsiveDialogShell` with the form building blocks below. | Connections, users, OIDC configuration, copy or move. |\n| One- or two-field editor | `ResponsiveDialogShell` with a single-column form surface. Keep the floating MUI label at every width. | Create, rename, copy, and move. |\n| Decision | `ResponsiveDialogShell` with compact content and actions. Do not add `FormSurface`. | Delete, overwrite conflict, application update, connection test result. |\n| Picker | `ResponsiveDialogShell` with a listbox or selection grid. Keep the picker\u2019s keyboard and selection semantics in the owning component. | Viewer and theme pickers. |\n| Short workflow | `ResponsiveDialogShell` with state-specific body and actions. | Companion pairing. |\n| Full-screen workspace | Keep the specialized full-screen viewer shell. Share only reusable behavior that does not interfere with the viewer\u2019s focus, toolbar, or third-party integration. | Image, PDF, Markdown, and text viewers. |\n\nThe desktop settings overlay and mobile settings drawer are navigation containers, not form dialogs. Keep their information architecture separate while composing settings-form pages inside them.\n\nFor safety-critical decisions, focus the least destructive action after opening. For input workflows, focus the first input. Do not make a destructive action the default Enter action unless the user has already focused it.\n\n## Shared Building Blocks\n\nImport reusable structural primitives and control styles from `frontend/src/components/Form/FormLayout.tsx`. Settings-only sections remain in `frontend/src/components/Settings/SettingsFormLayout.tsx`.\n\n| Building block | Responsibility |\n|---|---|\n| `FormSurface` | Provides the shared form-surface background and interior padding. |\n| `FormGroup` | Groups related rows and adds row dividers only at the desktop breakpoint. |\n| `FormRow` | Uses one column below `md` and the two-column label/control grid at `md` and above. |\n| `FormFieldLabel` | Renders a desktop label with its description or active error/warning. |\n| `SettingsFormSection` | Separates groups with the standard settings heading, subdued divider, and spacing. |\n| `SettingsSelectMenuItem` | Renders a select option with a label and supporting description. |\n| `SettingsPasswordVisibilityToggle` | Renders the shared show/hide password adornment. The owning dialog keeps password visibility state and translated labels. |\n| `formFieldControlSx` | Aligns a control to the desktop control column. |\n| `formSelectControlSx` | Makes a desktop select content-width and right-aligned. |\n| `formOutlinedControlSx` | Applies the shared outlined-field, focus, error, and floating-label treatment. |\n| `formSelectSx` and `formSelectMenuProps` | Keep select values, icons, and options at the standard subdued text color. |\n\nKeep field state, API calls, validation rules, translations, and the concrete MUI controls in the owning dialog. The shared layer owns layout and presentation; it must not become a schema-driven form engine.\n\n## Responsive Contract\n\nMulti-field settings editors have exactly two form layouts. One- and two-field operation dialogs stay single-column at every width so long names and paths retain the available width.\n\n### Below `md`\n\nUse one column in both responsive shells.\n\n- Below `sm`, `ResponsiveDialogShell` renders the form in a Drawer.\n- From `sm` through `\u003cmd`, it renders the same form in a Dialog.\n- Use normal-height MUI outlined controls.\n- Keep MUI labels inside empty fields and floating in the outline after focus or entry.\n- Keep descriptions and validation errors directly below their controls as MUI helper text.\n- Use the grouped surface and section heading, but do not show individual field-row dividers.\n\n### At `md` And Above For Multi-Field Editors\n\nUse the two-column desktop layout.\n\n- Put labels and descriptions in the left column.\n- Put compact controls in the right column.\n- Use the compact MUI `size=\"small\"` variant only when a desktop field has an external label in the left column.\n- Replace the left-column description with the validation error instead of showing helper text below the input.\n- Keep full-width text inputs within the control column.\n- Use content-width, right-aligned selects when the selected option remains readable.\n- For checkboxes and switches, use the external label and description on the left, with the control in the right column. Keep the control label and helper text next to the control below `md`.\n- For boolean settings, use a `Switch` with a visible `On` or `Off` state label. Let Material UI apply its standard palette colors.\n- For native `datetime-local` inputs, preserve the MUI shrunk input label below `md`; use the external desktop label at `md` and above.\n- Show subdued dividers between rows in a group.\n\n## Control Conventions\n\nApply `settingsSelectSx` and `settingsSelectMenuProps` to every settings `Select`. Use `SettingsSelectMenuItem` when an option needs a short explanation below its label.\n\nUse `SettingsPasswordVisibilityToggle` as the end adornment for password fields. Keep its `visible` state, toggle handler, and localized show/hide labels in the owning dialog.\n\nUse `DialogReadOnlyField` for a name, path, connection, or other value that a dialog shows without allowing the user to change it. Give the field a specific label such as `Destination directory` or `File to delete`; do not recreate a styled text pill. Keep the normal MUI field height when its label is inside the outlined field. Use a subdued read-only surface while keeping long values selectable.\n\nWrite the dialog description as the outcome of the selected action. State what will be copied, moved, replaced, skipped, or deleted and name the source item for a single-item operation, then present the affected value in a labelled read-only field. Keep notices tied to their current condition: a no-op destination notice must disappear as soon as a renamed target makes the operation valid, without changing the dialog's layout.\n\n## Operation Context\n\nOperation dialogs show their subject and destination independently of translated prose. This lets a translated description use its natural word order and keeps a long identifier from making the dialog hard to scan.\n\nUse `DialogOperationContext` for passive operation metadata. Each entry has a translated label and a value with either the `fileName` or `path` kind. The component renders a vertical definition list, so every filename and path occupies its own line and does not share that line with explanatory text.\n\n`OverwriteConflictDialog` is the deliberate exception. Its compact Existing item and Incoming item metadata grids remain intact because they support side-by-side conflict comparison. Use `DialogIdentifierDisplay` for each Path value in those grids, but do not replace the grids with `DialogOperationContext`.\n\nUse `DialogIdentifierDisplay` inside this context rather than truncating an identifier locally. It keeps the full value in the accessible name, applies bidi isolation with `bdi` and `dir=\"auto\"`, and abbreviates only the visual value when the available width requires it. A shortened value has a hover-only tooltip with its full value. Do not make the identifier focusable and do not reveal the tooltip on focus or touch.\n\nFile-name shortening preserves the extension where possible. Path shortening preserves useful leading and trailing segments. Both use grapheme-aware boundaries, so combining characters and emoji sequences are never split. Breadcrumb segment labels must use `truncateTextByGrapheme` from `utils/pathDisplay` for the same reason.\n\nUse outcome-only translation strings for the dialog description. Do not interpolate filenames or paths into `Trans` text. For example, a single-item copy describes copying the item to the destination directory, then context rows identify `Source item` and `Destination directory`.\n\n## Feedback And Persistence\n\nRender feedback only while it is active. Field errors and warnings belong to their control; use normal MUI helper text below `md`, and pass `FieldFeedback` to `FormFieldLabel` at `md` and above so it replaces the left-column description. Error feedback uses the normal MUI error state. Warning text starts with `Warning:` and uses the warning color. Do not reserve blank helper-text space, clip feedback to one line, or use a tooltip as the only way to read it.\n\nUse `DialogNotice` and `DialogNoticeRegion` from `frontend/src/components/Dialog/` for non-field notices. A contextual condition known when the dialog opens belongs in the shell's `contextualNotice` slot, after its description and before the body. A result caused by an action belongs in the `actionNotice` slot immediately above the actions. Idle notices render no alert. An error alert uses the default dynamic `role=\"alert\"`; a non-urgent warning uses `role=\"status\"`. Do not move focus to an alert.\n\nOrdinary settings persist a valid committed value immediately. Selects, toggles, and checkboxes commit on change. Text and numeric fields commit on blur or Enter after local validation succeeds. Keep invalid candidates locally and associate their error with the field. Each field has at most one in-flight request; disable every representation of that field while it is pending, but do not queue, debounce, batch, or serialize unrelated fields. Show a `role=\"status\"` saving indicator only while active, then a brief saved indicator. A failed write remains a readable field error until editing or a later success resolves it.\n\nEvery settings update uses exactly one discriminated `{ field, value }` request and receives the matching canonical pair. Apply a response only to its matching field. Complete settings state is read through `GET`; routine settings pages have no Save, reset, dirty-state, or success-alert workflow. File Search and SMB policy fields are independent persisted keys; the backend validates correlated aggregates transactionally. SMB policy writes retain their full post-commit runtime refresh lifecycle, while its read-chunk-size update does not trigger that lifecycle.\n\n`userSettingsStore` is the sole frontend boundary for `/auth/me/settings`. Components use its field selectors and `useCurrentUserSetting()` hook, retain only local drafts/previews, and never store server-backed user settings in local storage. The store hydrates for identity changes, rejects stale requests, allows one write per field, and refreshes other tabs from invalidation-only BroadcastChannel messages.\n\nDuring a cancellable operation, keep its cancellation action enabled unless the owner is already processing the cancellation request. Move focus to that action when the pending state starts. Keep the primary action disabled while the operation is active. Archive progress must report only data actually provided by the operation: archive creation shows an indeterminate status, and extraction may show its processed-member count without inventing byte totals or an item total.\n\n## Implementation Checklist\n\n1. Start with `ResponsiveDialogShell` for the responsive Drawer and Dialog shell.\n2. Wrap the fields in `FormSurface` and one or more `FormGroup` components.\n3. Put every field in `FormRow`.\n4. Use `FormFieldLabel` only for a multi-field editor at `md` or wider. Keep one- and two-field operation dialogs in a single column with floating MUI labels at every width.\n5. Keep the below-`md` MUI `label`, `InputLabel`, and active `FormHelperText` props in the concrete control. Use normal field height for inline-labelled one- or two-field operation dialogs; do not reserve helper-text space.\n6. Use `SettingsFormSection` between related groups instead of recreating section borders and title spacing locally.\n7. Reuse the shared action styles when the dialog has split or responsive actions.\n8. Render conditional fields or sections only when their state applies, while keeping each visible control in a `FormRow`.\n\nFor a non-form dialog, start with `ResponsiveDialogShell` and retain only the content, selection, workflow, and keyboard behavior specific to that dialog. Do not duplicate MUI `Dialog`, `Drawer`, sticky mobile actions, focus restoration, or dialog surface styling in the owning component.\n\n## Accessibility And Validation\n\nAssociate desktop controls with their external labels and descriptions using `htmlFor`, `labelId`, and `aria-describedby` as appropriate. Preserve a description ID when an error replaces the description so the relationship remains valid.\n\nAfter a failed save or test, focus the first invalid field. Do not remove normal MUI error states from controls; the desktop error text supplements them by making the issue readable in the label column.\n\nUse field-level errors for validation that the dialog can determine before submitting. Do not repeat a field-owned error in a form-level alert. Error text must explain the cause and the corrective action, not only name a failed rule. Bounded reflow when feedback appears is expected and preferred to hidden space.\n\nPrefer a safe, valid default over presenting a predictable error when the dialog can infer the intended correction. For example, a one-item copy into its source directory should prefill an extension-aware name such as `report (copy).pdf`. Do not apply this pattern to a same-directory move: it is a rename operation, so the user must deliberately choose the new name.\n\nUse a stable form-level alert only when no editable field owns the remedy, such as a multi-item copy whose destination directory is also its source directory. Use error severity when the state blocks confirmation. Keep API failures in this form-level feedback region as well, above the form surface so they do not disrupt a desktop field row.\n\n## Testing And Review\n\nFor every dialog that adopts this pattern, cover all of the following:\n\n- The mobile Drawer and the `sm` through `\u003cmd` Dialog use the same single-column form semantics.\n- A populated narrow-screen field uses a floating MUI label, normal control height, and helper text below the field.\n- A multi-field editor retains external labels, compact controls, and desktop-only row dividers at `md` and above.\n- A one- or two-field operation dialog remains single-column and keeps floating labels at `md` and above.\n- Errors, focus-first-invalid behavior, keyboard handling, and pending action states still work.\n- The surface, controls, and helper text remain legible in both light and dark themes.\n- Long filenames and paths remain one line at phone, tablet, and desktop widths; shortened values expose the complete identifier only on hover.\n- Identifier rendering remains correct for mixed left-to-right and right-to-left text, including after the available width changes.\n- A cancellable pending workflow focuses its cancellation action and does not submit a duplicate request.\n\nFor every non-form dialog that adopts the shared shell, cover all of the following:\n\n- The phone Drawer has reachable actions above safe-area insets and does not obscure content in a short viewport.\n- Keyboard focus, Enter, Escape cancellation, and the dialog-specific safe default still work. Escape must always issue the dialog's cancellation request.\n- Picker and workflow state remains usable with a keyboard.\n- Dialog content and action states remain legible in light and dark themes.\n\nUse a live browser check at a phone width and a desktop width in addition to focused tests. Check a short viewport as well so the fixed mobile actions do not obscure the final control.\n", "2.0": "+++\ntitle = \"Settings Forms and Actions\"\n+++\n\nUse these conventions for settings pages and stateful settings editors. Pages share section, surface, and action styles. Editors keep the same form behavior across a phone drawer, a narrow dialog, and a desktop dialog without separate mobile and desktop forms.\n\nThe page reference is `frontend/src/pages/LocalDrivesSettings.tsx`; the dialog reference is `frontend/src/components/Admin/ConnectionDialog.tsx`.\n\n## When To Use It\n\nUse the page conventions for settings content and actions. Use the dialog pattern when an editor changes several related settings and needs validation, field descriptions, or more than one action.\n\nDo not use the form pattern for a confirmation or destructive-action dialog. Those should continue to use `ResponsiveDialogShell` directly with focused content and actions.\n\n## Settings Page Layout and Actions\n\nCompose settings pages with `SettingsPage`, `SettingsSectionList`, and `SettingsGroup`. Use `FormSurface` for the subdued background of an action section, not an additional bordered card. For action sections, put the description or metadata on the left and controls on the right in a `FormRow`: the columns stack below `md` and share the row at `md` and above. Right-align actions on desktop, allow them to wrap, and keep result notices below the row. An informational section such as Local Drives' Current status can keep its own layout; don't force it into an action row.\n\nChoose button styling by the action's role, not by whether its MUI variant is `outlined` or `contained`:\n\n| Role | Treatment | Example |\n|---|---|---|\n| Regular or secondary | Neutral `settingsUtilityButtonSx`; on a grey `FormSurface`, use `settingsFormSurfaceUtilityButtonSx` so the overlay background shows through, as it does for dialog inputs. Keep the existing border, hover, and keyboard-focus treatment. | Account \u003e Change password; Local Drives \u003e Test Current Pairing. |\n| Danger or alert | Red-tinted `settingsDestructiveButtonSx` for settings-page actions. Use the dialog action rules below for the confirmation. | Local Drives \u003e Unpair This Browser. |\n| Main or default | Prominent `settingsPrimaryButtonSx` for the main action on a grey settings-page surface and for the main action in a page footer or dialog. Avoid giving several routine actions the same emphasis. | Authentication \u003e Configure OIDC; Local Drives \u003e Pair This Browser. |\n\nAdd a relevant `@mui/icons-material` icon with `startIcon` to labeled outlined or contained settings-page action buttons that lack one. Leave text-only buttons, including buttons without an explicit outlined or contained variant, without icons. Adding an icon must not change the button's variant, colors, label, or behavior.\n\n## User Directory Layout\n\nUser Management renders roles and statuses as ordinary text, with each simultaneous status on its own line. Summary counts and removable filters remain badges. Keep column headings and cell values readable: wrap headings, email addresses, usernames, provider names, and other long values without truncating their underlying text. Top-align row contents, and reserve space for sort icons and row actions.\n\nUse the settings content container's width to choose between the desktop grid and stacked records, with a shared 40rem breakpoint for the table and its toolbar. Changing selected columns must not change the layout breakpoint. A narrow settings overlay must stack even on a wide screen. Preserve every selected field when stacking; don't introduce horizontal scrolling or silently hide columns. Show timestamps as a short localized date and time on separate lines, retaining the full timestamp in a tooltip and the original value in a semantic `time` element.\n\nPlace the desktop column chooser icon at the far-right end of the table header, above the row actions. In stacked layouts, place the Columns control at the toolbar's right edge. Keep the toolbar control available while the directory is loading or empty. Anchor the menu to the visible control, reposition it when the settings container resizes, and return focus to the visible control when it closes.\n\nValidate the layout in a real browser with all columns enabled, long identifiers, multiple statuses, different regional formats, narrow containers, mobile widths, and zoom. Component tests don't measure text overlap or container-query behavior.\n\n## Dialog Categories\n\nUse `ResponsiveDialogShell` from `frontend/src/components/Dialog/ResponsiveDialogShell.tsx` as the shared shell for every ordinary application dialog. It provides responsive Drawer and Dialog behavior, safe-area actions, overlay/form surface tokens, title and description relationships, close blocking, and focus restoration.\n\nSmall dialogs use traditional Cancel and confirmation actions; do not add a top-right close button.\n\nChoose the content pattern that matches the job:\n\n| Dialog type | Use | Examples |\n|---|---|---|\n| Multi-field editor | `ResponsiveDialogShell` with the form building blocks below. | Connections, users, OIDC configuration, copy or move. |\n| One- or two-field editor | `ResponsiveDialogShell` with a single-column form surface. Keep the floating MUI label at every width. | Create, rename, copy, and move. |\n| Decision | `ResponsiveDialogShell` with compact content and actions. Do not add `FormSurface`. | Delete, overwrite conflict, application update, connection test result. |\n| Picker | `ResponsiveDialogShell` with a listbox or selection grid. Keep the picker\u2019s keyboard and selection semantics in the owning component. | Viewer and theme pickers. |\n| Short workflow | `ResponsiveDialogShell` with state-specific body and actions. | Companion pairing. |\n| Full-screen workspace | Keep the specialized full-screen viewer shell. Share only reusable behavior that does not interfere with the viewer\u2019s focus, toolbar, or third-party integration. | Image, PDF, Markdown, and text viewers. |\n\nThe desktop settings overlay and mobile settings drawer are navigation containers, not form dialogs. Keep their information architecture separate while composing settings-form pages inside them.\n\n## Keyboard Isolation\n\n`ResponsiveDialogShell` establishes a keyboard shortcut scope automatically for both its Drawer and Dialog layouts. While it's open, `useKeyboardShortcuts` ignores background registrations and lets the innermost open dialog own shortcuts, including when a control portals outside the dialog. The shell also stops key events from bubbling into parent workspace handlers. Closing the dialog releases its scope; normal shortcut handling resumes when focus returns to the workspace.\n\nDon't add dialog-specific flags to parent shortcut handlers to provide this isolation. Keep ordinary dialog keyboard behavior in the shell's `onKeyDown` or `onEscape` callbacks. If dialog content needs `useKeyboardShortcuts`, register it in a child component rendered inside the shell so it inherits the dialog's scope, not in the component that creates the shell. Existing focus trapping and interactive-control checks still apply.\n\nEscape dismissal goes through MUI's modal close callback, preserving its top-modal and IME process-key checks. `onEscape`, when supplied, replaces the normal Escape close action and runs once, even when `disableClose` blocks ordinary closing. Use it for cancellation requests during pending operations. Close buttons and backdrop requests still use `onClose` and respect `disableClose`. Don't add document-level Escape listeners or duplicate Escape closing in `onKeyDown`; the shared shell owns that behavior.\n\n## Dialog Action Buttons\n\nChoose each action's treatment by what it does, including in decisions embedded inside full-screen viewers. Keep the viewer workspace shell and toolbars separate from its decision dialogs.\n\n| Role | Treatment | Example |\n|---|---|---|\n| Destructive confirmation | MUI `variant=\"contained\" color=\"error\"`, as in the File delete dialog. Do not use the red-tinted settings-page `settingsDestructiveButtonSx` or introduce another red button style. | Delete, Discard unsaved changes, or Continue with overwrite selected. |\n| Main non-destructive action | MUI `variant=\"contained\"` in the theme's primary color. | Create directory, Save, Retry, or the sole Close action. |\n| Secondary or alternate action | MUI `variant=\"outlined\"` with the existing subdued utility fill and focus treatment. | Cancel, Later, Ignore, or Open without saving. |\n\nAn action's role can change with the selected option: a conflict dialog's Continue is destructive only when it will overwrite an existing item. When a decision offers both Save and Discard, distinguish the primary and destructive actions without changing what either one does. Do not restyle settings-page triggers when styling their confirmation dialogs.\n\nVisual priority does not determine Enter behavior. For safety-critical decisions, focus the least destructive action on opening; for input workflows, focus the first input. Never make a destructive action the default Enter action unless the user has already focused it. Keep cancellation available and focused during cancellable pending operations. Use `ResponsiveDialogShell` for application confirmations rather than native `window.confirm`, whose buttons cannot follow these styles.\n\n## Shared Building Blocks\n\nImport reusable structural primitives and control styles from `frontend/src/components/Form/FormLayout.tsx`. Settings-only sections remain in `frontend/src/components/Settings/SettingsFormLayout.tsx`.\n\n| Building block | Responsibility |\n|---|---|\n| `FormSurface` | Provides the shared form-surface background and interior padding. |\n| `FormGroup` | Groups related rows and adds row dividers only at the desktop breakpoint. |\n| `FormRow` | Uses one column below `md` and the two-column label/control grid at `md` and above. |\n| `FormFieldLabel` | Renders a desktop label with its description or active error/warning. |\n| `SettingsFormSection` | Separates groups with the standard settings heading, subdued divider, and spacing. |\n| `SettingsSelectMenuItem` | Renders a select option with a label and supporting description. |\n| `SettingsPasswordVisibilityToggle` | Renders the shared show/hide password adornment. The owning dialog keeps password visibility state and translated labels. |\n| `formFieldControlSx` | Aligns a control to the desktop control column. |\n| `formSelectControlSx` | Makes a desktop select content-width and right-aligned. |\n| `formOutlinedControlSx` | Applies the shared outlined-field, focus, error, and floating-label treatment. |\n| `formSelectSx` and `formSelectMenuProps` | Keep select values, icons, and options at the standard subdued text color. |\n\nKeep field state, API calls, validation rules, translations, and the concrete MUI controls in the owning dialog. The shared layer owns layout and presentation; it must not become a schema-driven form engine.\n\n## Responsive Contract\n\nMulti-field settings editors have exactly two form layouts. One- and two-field operation dialogs stay single-column at every width so long names and paths retain the available width.\n\n### Below `md`\n\nUse one column in both responsive shells.\n\n- Below `sm`, `ResponsiveDialogShell` renders the form in a Drawer.\n- From `sm` through `\u003cmd`, it renders the same form in a Dialog.\n- Use normal-height MUI outlined controls.\n- Keep MUI labels inside empty fields and floating in the outline after focus or entry.\n- Keep descriptions and validation errors directly below their controls as MUI helper text.\n- Use the grouped surface and section heading, but do not show individual field-row dividers.\n\n### At `md` And Above For Multi-Field Editors\n\nUse the two-column desktop layout.\n\n- Put labels and descriptions in the left column.\n- Put compact controls in the right column.\n- For text inputs and selects with an external label in the left column, use MUI `size=\"small\"` and omit the control's `label` or `InputLabel`. The left-column label is the only visible label; associate it with the control so it remains accessible. Below `md`, restore the control's floating label and normal height.\n- Replace the left-column description with the validation error instead of showing helper text below the input.\n- Keep full-width text inputs within the control column.\n- Use content-width, right-aligned selects when the selected option remains readable.\n- For checkboxes and switches, use the external label and description on the left, with the control in the right column. Keep the control label and helper text next to the control below `md`.\n- For boolean settings, use a `Switch` with a visible `On` or `Off` state label. Let Material UI apply its standard palette colors.\n- For native `datetime-local` inputs, preserve the MUI shrunk input label below `md`; use the external desktop label at `md` and above.\n- Show subdued dividers between rows in a group.\n\n## Control Conventions\n\nApply `settingsSelectSx` and `settingsSelectMenuProps` to every settings `Select`. Use `SettingsSelectMenuItem` when an option needs a short explanation below its label.\n\nUse `SettingsPasswordVisibilityToggle` as the end adornment for password fields. Keep its `visible` state, toggle handler, and localized show/hide labels in the owning dialog.\n\nUse `DialogReadOnlyField` for a name, path, connection, or other value that a dialog shows without allowing the user to change it. Give the field a specific label such as `Destination directory` or `File to delete`; do not recreate a styled text pill. Keep the normal MUI field height when its label is inside the outlined field. Use a subdued read-only surface while keeping long values selectable.\n\nWrite the dialog description as the outcome of the selected action. State what will be copied, moved, replaced, skipped, or deleted and name the source item for a single-item operation, then present the affected value in a labelled read-only field. Keep notices tied to their current condition: a no-op destination notice must disappear as soon as a renamed target makes the operation valid, without changing the dialog's layout.\n\n## Operation Context\n\nOperation dialogs show their subject and destination independently of translated prose. This lets a translated description use its natural word order and keeps a long identifier from making the dialog hard to scan.\n\nUse `DialogOperationContext` for passive operation metadata. Each entry has a translated label and a value with either the `fileName` or `path` kind. The component renders a vertical definition list, so every filename and path occupies its own line and does not share that line with explanatory text.\n\n`OverwriteConflictDialog` is the deliberate exception. Its compact Existing item and Incoming item metadata grids remain intact because they support side-by-side conflict comparison. Use `DialogIdentifierDisplay` for each Path value in those grids, but do not replace the grids with `DialogOperationContext`.\n\nUse `DialogIdentifierDisplay` inside this context rather than truncating an identifier locally. It keeps the full value in the accessible name, applies bidi isolation with `bdi` and `dir=\"auto\"`, and abbreviates only the visual value when the available width requires it. A shortened value has a hover-only tooltip with its full value. Do not make the identifier focusable and do not reveal the tooltip on focus or touch.\n\nFile-name shortening preserves the extension where possible. Path shortening preserves useful leading and trailing segments. Both use grapheme-aware boundaries, so combining characters and emoji sequences are never split. Breadcrumb segment labels must use `truncateTextByGrapheme` from `utils/pathDisplay` for the same reason.\n\nUse outcome-only translation strings for the dialog description. Do not interpolate filenames or paths into `Trans` text. For example, a single-item copy describes copying the item to the destination directory, then context rows identify `Source item` and `Destination directory`.\n\n## Feedback And Persistence\n\nRender feedback only while it is active. Field errors and warnings belong to their control; use normal MUI helper text below `md`, and pass `FieldFeedback` to `FormFieldLabel` at `md` and above so it replaces the left-column description. Error feedback uses the normal MUI error state. Warning text starts with `Warning:` and uses the warning color. Do not reserve blank helper-text space, clip feedback to one line, or use a tooltip as the only way to read it.\n\nUse `DialogNotice` and `DialogNoticeRegion` from `frontend/src/components/Dialog/` for non-field notices. A contextual condition known when the dialog opens belongs in the shell's `contextualNotice` slot, after its description and before the body. A result caused by an action belongs in the `actionNotice` slot immediately above the actions. Idle notices render no alert. An error alert uses the default dynamic `role=\"alert\"`; a non-urgent warning uses `role=\"status\"`. Do not move focus to an alert.\n\nOrdinary settings persist a valid committed value immediately. Selects, toggles, and checkboxes commit on change. Text and numeric fields commit on blur or Enter after local validation succeeds. Keep invalid candidates locally and associate their error with the field. Each field has at most one in-flight request; disable every representation of that field while it is pending, but do not queue, debounce, batch, or serialize unrelated fields. Show a `role=\"status\"` saving indicator only while active, then a brief saved indicator. A failed write remains a readable field error until editing or a later success resolves it.\n\nEvery settings update uses exactly one discriminated `{ field, value }` request and receives the matching canonical pair. Apply a response only to its matching field. Complete settings state is read through `GET`; routine settings pages have no Save, reset, dirty-state, or success-alert workflow. File Search and SMB policy fields are independent persisted keys; the backend validates correlated aggregates transactionally. SMB policy writes retain their full post-commit runtime refresh lifecycle, while its read-chunk-size update does not trigger that lifecycle.\n\n`userSettingsStore` is the sole frontend boundary for `/auth/me/settings`. Components use its field selectors and `useCurrentUserSetting()` hook, retain only local drafts/previews, and never store server-backed user settings in local storage. The store hydrates for identity changes, rejects stale requests, allows one write per field, and refreshes other tabs from invalidation-only BroadcastChannel messages.\n\nDuring a cancellable operation, keep its cancellation action enabled unless the owner is already processing the cancellation request. Move focus to that action when the pending state starts. Keep the primary action disabled while the operation is active. Archive progress must report only data actually provided by the operation: archive creation shows an indeterminate status, and extraction may show its processed-member count without inventing byte totals or an item total.\n\n## Implementation Checklist\n\n1. Start with `ResponsiveDialogShell` for the responsive Drawer and Dialog shell.\n2. Wrap the fields in `FormSurface` and one or more `FormGroup` components.\n3. Put every field in `FormRow`.\n4. Use `FormFieldLabel` only for a multi-field editor at `md` or wider. Keep one- and two-field operation dialogs in a single column with floating MUI labels at every width.\n5. Keep the below-`md` MUI `label`, `InputLabel`, and active `FormHelperText` props in the concrete control. Use normal field height for inline-labelled one- or two-field operation dialogs; do not reserve helper-text space.\n6. Use `SettingsFormSection` between related groups instead of recreating section borders and title spacing locally.\n7. Reuse the shared action styles when the dialog has split or responsive actions.\n8. Render conditional fields or sections only when their state applies, while keeping each visible control in a `FormRow`.\n\nFor a non-form dialog, start with `ResponsiveDialogShell` and retain only the content, selection, workflow, and keyboard behavior specific to that dialog. Do not duplicate MUI `Dialog`, `Drawer`, sticky mobile actions, focus restoration, or dialog surface styling in the owning component.\n\n## Accessibility And Validation\n\nAssociate desktop controls with their external labels and descriptions using `htmlFor`, `labelId`, and `aria-describedby` as appropriate. Preserve a description ID when an error replaces the description so the relationship remains valid.\n\nAfter a failed save or test, focus the first invalid field. Do not remove normal MUI error states from controls; the desktop error text supplements them by making the issue readable in the label column.\n\nUse field-level errors for validation that the dialog can determine before submitting. Do not repeat a field-owned error in a form-level alert. Error text must explain the cause and the corrective action, not only name a failed rule. Bounded reflow when feedback appears is expected and preferred to hidden space.\n\nPrefer a safe, valid default over presenting a predictable error when the dialog can infer the intended correction. For example, a one-item copy into its source directory should prefill an extension-aware name such as `report (copy).pdf`. Do not apply this pattern to a same-directory move: it is a rename operation, so the user must deliberately choose the new name.\n\nUse a stable form-level alert only when no editable field owns the remedy, such as a multi-item copy whose destination directory is also its source directory. Use error severity when the state blocks confirmation. Keep API failures in this form-level feedback region as well, above the form surface so they do not disrupt a desktop field row.\n\n## Testing And Review\n\nFor settings-page action sections, check the one-column layout below `md` and the two-column description/action layout at `md` and above. Check neutral-button contrast against grey form surfaces in light and dark themes, including hover and keyboard focus. Check that added icons do not change accessible names or cause button labels to overflow at phone widths. Keep informational sections readable without imposing the action-row grid, and verify that notices remain below the row.\n\nFor dialog actions, check contained error and primary buttons and outlined secondary buttons in light and dark themes, including hover and keyboard focus. Verify that option-dependent destructive actions change treatment without changing their safe initial focus or Enter behavior.\n\nFor every dialog that adopts this pattern, cover all of the following:\n\n- The mobile Drawer and the `sm` through `\u003cmd` Dialog use the same single-column form semantics.\n- A populated narrow-screen field uses a floating MUI label, normal control height, and helper text below the field.\n- A multi-field editor retains external labels, compact controls, and desktop-only row dividers at `md` and above.\n- A one- or two-field operation dialog remains single-column and keeps floating labels at `md` and above.\n- Errors, focus-first-invalid behavior, keyboard handling, and pending action states still work.\n- The surface, controls, and helper text remain legible in both light and dark themes.\n- Long filenames and paths remain one line at phone, tablet, and desktop widths; shortened values expose the complete identifier only on hover.\n- Identifier rendering remains correct for mixed left-to-right and right-to-left text, including after the available width changes.\n- A cancellable pending workflow focuses its cancellation action and does not submit a duplicate request.\n\nFor every non-form dialog that adopts the shared shell, cover all of the following:\n\n- The phone Drawer has reachable actions above safe-area insets and does not obscure content in a short viewport.\n- Keyboard focus, Enter, Escape cancellation, and the dialog-specific safe default still work. Escape must always issue the dialog's cancellation request.\n- Picker and workflow state remains usable with a keyboard.\n- Dialog content and action states remain legible in light and dark themes.\n\nUse a live browser check at a phone width and a desktop width in addition to focused tests. Check a short viewport as well so the fixed mobile actions do not obscure the final control.\n"}, "page_contents": {"0.9": "+++\ntitle = \"Settings Form Dialog Pattern\"\n+++\n\nUse this pattern for stateful settings editors that create or update configuration. It keeps the same form behavior across a phone drawer, a narrow dialog, and a desktop dialog while avoiding separate mobile and desktop forms.\n\nThe reference implementation is `frontend/src/components/Admin/ConnectionDialog.tsx`.\n\n## When To Use It\n\nUse the pattern when a dialog edits several related settings and needs validation, field descriptions, or more than one action.\n\nDo not use it for a confirmation or destructive-action dialog. Those should continue to use `ResponsiveFormDialog` directly with focused content and actions.\n\n## Dialog Categories\n\nUse `ResponsiveFormDialog` as the shared shell for every ordinary application dialog. It provides the responsive Drawer and Dialog behavior, safe-area action area, dialog surface tokens, title and description relationships, close blocking, and focus restoration.\n\nSmall dialogs use traditional Cancel and confirmation actions; do not add a top-right close button.\n\nChoose the content pattern that matches the job:\n\n| Dialog type | Use | Examples |\n|---|---|---|\n| Multi-field editor | `ResponsiveFormDialog` with the settings form building blocks below. | Connections, users, OIDC configuration, copy or move. |\n| One- or two-field editor | `ResponsiveFormDialog` with a single-column settings surface. Keep the floating MUI label at every width. | Create, rename, copy, and move. |\n| Decision | `ResponsiveFormDialog` with compact content and actions. Do not add `SettingsFormSurface`. | Delete, overwrite conflict, application update, connection test result. |\n| Picker | `ResponsiveFormDialog` with a listbox or selection grid. Keep the picker\u2019s keyboard and selection semantics in the owning component. | Viewer and theme pickers. |\n| Short workflow | `ResponsiveFormDialog` with state-specific body and actions. | Companion pairing. |\n| Full-screen workspace | Keep the specialized full-screen viewer shell. Share only reusable behavior that does not interfere with the viewer\u2019s focus, toolbar, or third-party integration. | Image, PDF, Markdown, and text viewers. |\n\nThe desktop settings overlay and mobile settings drawer are navigation containers, not form dialogs. Keep their information architecture separate while composing settings-form pages inside them.\n\nFor safety-critical decisions, focus the least destructive action after opening. For input workflows, focus the first input. Do not make a destructive action the default Enter action unless the user has already focused it.\n\n## Shared Building Blocks\n\nImport the structural primitives and control styles from `frontend/src/components/Settings/SettingsFormLayout.tsx`.\n\n| Building block | Responsibility |\n|---|---|\n| `SettingsFormSurface` | Provides the muted, rounded background and shared interior padding. It darkens the default background by 4% in light mode and lightens it by 8% in dark mode. |\n| `SettingsFormGroup` | Groups related rows and adds row dividers only at the desktop breakpoint. |\n| `SettingsFormRow` | Uses one column below `md` and the two-column label/control grid at `md` and above. |\n| `SettingsFormFieldLabel` | Renders a desktop label with its description or validation error. |\n| `SettingsFormSection` | Separates groups with the standard settings heading, subdued divider, and spacing. |\n| `SettingsSelectMenuItem` | Renders a select option with a label and supporting description. |\n| `SettingsPasswordVisibilityToggle` | Renders the shared show/hide password adornment. The owning dialog keeps password visibility state and translated labels. |\n| `settingsFormFieldControlSx` | Aligns a control to the desktop control column. |\n| `settingsFormSelectControlSx` | Makes a desktop select content-width and right-aligned. |\n| `settingsFormOutlinedControlSx` | Applies the shared outlined-field, focus, error, and floating-label treatment. |\n| `settingsSelectSx` and `settingsSelectMenuProps` | Keep select values, icons, and options at the standard subdued text color. |\n\nKeep field state, API calls, validation rules, translations, and the concrete MUI controls in the owning dialog. The shared layer owns layout and presentation; it must not become a schema-driven form engine.\n\n## Responsive Contract\n\nMulti-field settings editors have exactly two form layouts. One- and two-field operation dialogs stay single-column at every width so long names and paths retain the available width.\n\n### Below `md`\n\nUse one column in both responsive shells.\n\n- Below `sm`, `ResponsiveFormDialog` renders the form in a Drawer.\n- From `sm` through `\u003cmd`, it renders the same form in a Dialog.\n- Use normal-height MUI outlined controls.\n- Keep MUI labels inside empty fields and floating in the outline after focus or entry.\n- Keep descriptions and validation errors directly below their controls as MUI helper text.\n- Use the grouped surface and section heading, but do not show individual field-row dividers.\n\n### At `md` And Above For Multi-Field Editors\n\nUse the two-column desktop layout.\n\n- Put labels and descriptions in the left column.\n- Put compact controls in the right column.\n- Use the compact MUI `size=\"small\"` variant only when a desktop field has an external label in the left column.\n- Replace the left-column description with the validation error instead of showing helper text below the input.\n- Keep full-width text inputs within the control column.\n- Use content-width, right-aligned selects when the selected option remains readable.\n- For checkboxes and switches, use the external label and description on the left, with the control in the right column. Keep the control label and helper text next to the control below `md`.\n- For boolean settings, use a `Switch` with a visible `On` or `Off` state label. Let Material UI apply its standard palette colors.\n- For native `datetime-local` inputs, preserve the MUI shrunk input label below `md`; use the external desktop label at `md` and above.\n- Show subdued dividers between rows in a group.\n\n## Control Conventions\n\nApply `settingsSelectSx` and `settingsSelectMenuProps` to every settings `Select`. Use `SettingsSelectMenuItem` when an option needs a short explanation below its label.\n\nUse `SettingsPasswordVisibilityToggle` as the end adornment for password fields. Keep its `visible` state, toggle handler, and localized show/hide labels in the owning dialog.\n\nUse `DialogReadOnlyField` for a name, path, connection, or other value that a dialog shows without allowing the user to change it. Give the field a specific label such as `Destination directory` or `File to delete`; do not recreate a styled text pill. Keep the normal MUI field height when its label is inside the outlined field. Use a subdued read-only surface while keeping long values selectable.\n\nWrite the dialog description as the outcome of the selected action. State what will be copied, moved, replaced, skipped, or deleted and name the source item for a single-item operation, then present the affected value in a labelled read-only field. Keep notices tied to their current condition: a no-op destination notice must disappear as soon as a renamed target makes the operation valid, without changing the dialog's layout.\n\n## Implementation Checklist\n\n1. Start with `ResponsiveFormDialog` for the responsive Drawer and Dialog shell.\n2. Wrap the fields in `SettingsFormSurface` and one or more `SettingsFormGroup` components.\n3. Put every field in `SettingsFormRow`.\n4. Use `SettingsFormFieldLabel` only for a multi-field editor at `md` or wider. Keep one- and two-field operation dialogs in a single column with floating MUI labels at every width.\n5. Keep the below-`md` MUI `label`, `InputLabel`, and `FormHelperText` props in the concrete control. Use normal field height for inline-labelled one- or two-field operation dialogs; reserve helper-text space when a field can show a validation error.\n6. Use `SettingsFormSection` between related groups instead of recreating section borders and title spacing locally.\n7. Reuse the shared action styles when the dialog has split or responsive actions.\n8. Render conditional fields or sections only when their state applies, while keeping each visible control in a `SettingsFormRow`.\n\nFor a non-form dialog, start with `ResponsiveFormDialog` and retain only the content, selection, workflow, and keyboard behavior specific to that dialog. Do not duplicate MUI `Dialog`, `Drawer`, sticky mobile actions, focus restoration, or dialog surface styling in the owning component.\n\n## Accessibility And Validation\n\nAssociate desktop controls with their external labels and descriptions using `htmlFor`, `labelId`, and `aria-describedby` as appropriate. Preserve a description ID when an error replaces the description so the relationship remains valid.\n\nAfter a failed save or test, focus the first invalid field. Do not remove normal MUI error states from controls; the desktop error text supplements them by making the issue readable in the label column.\n\nUse field-level errors for validation that the dialog can determine before submitting. Reserve one helper-text line, then replace it with the active error so the form does not shift. Do not repeat a field-owned error in a form-level alert. Error text must explain the cause and the corrective action, not only name a failed rule.\n\nPrefer a safe, valid default over presenting a predictable error when the dialog can infer the intended correction. For example, a one-item copy into its source directory should prefill an extension-aware name such as `report (copy).pdf`. Do not apply this pattern to a same-directory move: it is a rename operation, so the user must deliberately choose the new name.\n\nUse a stable form-level alert only when no editable field owns the remedy, such as a multi-item copy whose destination directory is also its source directory. Use error severity when the state blocks confirmation. Keep API failures in this form-level feedback region as well, above the form surface so they do not disrupt a desktop field row.\n\n## Testing And Review\n\nFor every dialog that adopts this pattern, cover all of the following:\n\n- The mobile Drawer and the `sm` through `\u003cmd` Dialog use the same single-column form semantics.\n- A populated narrow-screen field uses a floating MUI label, normal control height, and helper text below the field.\n- A multi-field editor retains external labels, compact controls, and desktop-only row dividers at `md` and above.\n- A one- or two-field operation dialog remains single-column and keeps floating labels at `md` and above.\n- Errors, focus-first-invalid behavior, keyboard handling, and pending action states still work.\n- The surface, controls, and helper text remain legible in both light and dark themes.\n\nFor every non-form dialog that adopts the shared shell, cover all of the following:\n\n- The phone Drawer has reachable actions above safe-area insets and does not obscure content in a short viewport.\n- Keyboard focus, Enter, Escape cancellation, and the dialog-specific safe default still work. Escape must always issue the dialog's cancellation request.\n- Picker and workflow state remains usable with a keyboard.\n- Dialog content and action states remain legible in light and dark themes.\n\nUse a live browser check at a phone width and a desktop width in addition to focused tests. Check a short viewport as well so the fixed mobile actions do not obscure the final control.\n\n", "1.0": "+++\ntitle = \"Settings Form Dialog Pattern\"\n+++\n\nUse this pattern for stateful settings editors that create or update configuration. It keeps the same form behavior across a phone drawer, a narrow dialog, and a desktop dialog while avoiding separate mobile and desktop forms.\n\nThe reference implementation is `frontend/src/components/Admin/ConnectionDialog.tsx`.\n\n## When To Use It\n\nUse the pattern when a dialog edits several related settings and needs validation, field descriptions, or more than one action.\n\nDo not use it for a confirmation or destructive-action dialog. Those should continue to use `ResponsiveDialogShell` directly with focused content and actions.\n\n## Dialog Categories\n\nUse `ResponsiveDialogShell` from `frontend/src/components/Dialog/ResponsiveDialogShell.tsx` as the shared shell for every ordinary application dialog. It provides responsive Drawer and Dialog behavior, safe-area actions, overlay/form surface tokens, title and description relationships, close blocking, and focus restoration.\n\nSmall dialogs use traditional Cancel and confirmation actions; do not add a top-right close button.\n\nChoose the content pattern that matches the job:\n\n| Dialog type | Use | Examples |\n|---|---|---|\n| Multi-field editor | `ResponsiveDialogShell` with the form building blocks below. | Connections, users, OIDC configuration, copy or move. |\n| One- or two-field editor | `ResponsiveDialogShell` with a single-column form surface. Keep the floating MUI label at every width. | Create, rename, copy, and move. |\n| Decision | `ResponsiveDialogShell` with compact content and actions. Do not add `FormSurface`. | Delete, overwrite conflict, application update, connection test result. |\n| Picker | `ResponsiveDialogShell` with a listbox or selection grid. Keep the picker\u2019s keyboard and selection semantics in the owning component. | Viewer and theme pickers. |\n| Short workflow | `ResponsiveDialogShell` with state-specific body and actions. | Companion pairing. |\n| Full-screen workspace | Keep the specialized full-screen viewer shell. Share only reusable behavior that does not interfere with the viewer\u2019s focus, toolbar, or third-party integration. | Image, PDF, Markdown, and text viewers. |\n\nThe desktop settings overlay and mobile settings drawer are navigation containers, not form dialogs. Keep their information architecture separate while composing settings-form pages inside them.\n\nFor safety-critical decisions, focus the least destructive action after opening. For input workflows, focus the first input. Do not make a destructive action the default Enter action unless the user has already focused it.\n\n## Shared Building Blocks\n\nImport reusable structural primitives and control styles from `frontend/src/components/Form/FormLayout.tsx`. Settings-only sections remain in `frontend/src/components/Settings/SettingsFormLayout.tsx`.\n\n| Building block | Responsibility |\n|---|---|\n| `FormSurface` | Provides the shared form-surface background and interior padding. |\n| `FormGroup` | Groups related rows and adds row dividers only at the desktop breakpoint. |\n| `FormRow` | Uses one column below `md` and the two-column label/control grid at `md` and above. |\n| `FormFieldLabel` | Renders a desktop label with its description or active error/warning. |\n| `SettingsFormSection` | Separates groups with the standard settings heading, subdued divider, and spacing. |\n| `SettingsSelectMenuItem` | Renders a select option with a label and supporting description. |\n| `SettingsPasswordVisibilityToggle` | Renders the shared show/hide password adornment. The owning dialog keeps password visibility state and translated labels. |\n| `formFieldControlSx` | Aligns a control to the desktop control column. |\n| `formSelectControlSx` | Makes a desktop select content-width and right-aligned. |\n| `formOutlinedControlSx` | Applies the shared outlined-field, focus, error, and floating-label treatment. |\n| `formSelectSx` and `formSelectMenuProps` | Keep select values, icons, and options at the standard subdued text color. |\n\nKeep field state, API calls, validation rules, translations, and the concrete MUI controls in the owning dialog. The shared layer owns layout and presentation; it must not become a schema-driven form engine.\n\n## Responsive Contract\n\nMulti-field settings editors have exactly two form layouts. One- and two-field operation dialogs stay single-column at every width so long names and paths retain the available width.\n\n### Below `md`\n\nUse one column in both responsive shells.\n\n- Below `sm`, `ResponsiveDialogShell` renders the form in a Drawer.\n- From `sm` through `\u003cmd`, it renders the same form in a Dialog.\n- Use normal-height MUI outlined controls.\n- Keep MUI labels inside empty fields and floating in the outline after focus or entry.\n- Keep descriptions and validation errors directly below their controls as MUI helper text.\n- Use the grouped surface and section heading, but do not show individual field-row dividers.\n\n### At `md` And Above For Multi-Field Editors\n\nUse the two-column desktop layout.\n\n- Put labels and descriptions in the left column.\n- Put compact controls in the right column.\n- Use the compact MUI `size=\"small\"` variant only when a desktop field has an external label in the left column.\n- Replace the left-column description with the validation error instead of showing helper text below the input.\n- Keep full-width text inputs within the control column.\n- Use content-width, right-aligned selects when the selected option remains readable.\n- For checkboxes and switches, use the external label and description on the left, with the control in the right column. Keep the control label and helper text next to the control below `md`.\n- For boolean settings, use a `Switch` with a visible `On` or `Off` state label. Let Material UI apply its standard palette colors.\n- For native `datetime-local` inputs, preserve the MUI shrunk input label below `md`; use the external desktop label at `md` and above.\n- Show subdued dividers between rows in a group.\n\n## Control Conventions\n\nApply `settingsSelectSx` and `settingsSelectMenuProps` to every settings `Select`. Use `SettingsSelectMenuItem` when an option needs a short explanation below its label.\n\nUse `SettingsPasswordVisibilityToggle` as the end adornment for password fields. Keep its `visible` state, toggle handler, and localized show/hide labels in the owning dialog.\n\nUse `DialogReadOnlyField` for a name, path, connection, or other value that a dialog shows without allowing the user to change it. Give the field a specific label such as `Destination directory` or `File to delete`; do not recreate a styled text pill. Keep the normal MUI field height when its label is inside the outlined field. Use a subdued read-only surface while keeping long values selectable.\n\nWrite the dialog description as the outcome of the selected action. State what will be copied, moved, replaced, skipped, or deleted and name the source item for a single-item operation, then present the affected value in a labelled read-only field. Keep notices tied to their current condition: a no-op destination notice must disappear as soon as a renamed target makes the operation valid, without changing the dialog's layout.\n\n## Operation Context\n\nOperation dialogs show their subject and destination independently of translated prose. This lets a translated description use its natural word order and keeps a long identifier from making the dialog hard to scan.\n\nUse `DialogOperationContext` for passive operation metadata. Each entry has a translated label and a value with either the `fileName` or `path` kind. The component renders a vertical definition list, so every filename and path occupies its own line and does not share that line with explanatory text.\n\n`OverwriteConflictDialog` is the deliberate exception. Its compact Existing item and Incoming item metadata grids remain intact because they support side-by-side conflict comparison. Use `DialogIdentifierDisplay` for each Path value in those grids, but do not replace the grids with `DialogOperationContext`.\n\nUse `DialogIdentifierDisplay` inside this context rather than truncating an identifier locally. It keeps the full value in the accessible name, applies bidi isolation with `bdi` and `dir=\"auto\"`, and abbreviates only the visual value when the available width requires it. A shortened value has a hover-only tooltip with its full value. Do not make the identifier focusable and do not reveal the tooltip on focus or touch.\n\nFile-name shortening preserves the extension where possible. Path shortening preserves useful leading and trailing segments. Both use grapheme-aware boundaries, so combining characters and emoji sequences are never split. Breadcrumb segment labels must use `truncateTextByGrapheme` from `utils/pathDisplay` for the same reason.\n\nUse outcome-only translation strings for the dialog description. Do not interpolate filenames or paths into `Trans` text. For example, a single-item copy describes copying the item to the destination directory, then context rows identify `Source item` and `Destination directory`.\n\n## Feedback And Persistence\n\nRender feedback only while it is active. Field errors and warnings belong to their control; use normal MUI helper text below `md`, and pass `FieldFeedback` to `FormFieldLabel` at `md` and above so it replaces the left-column description. Error feedback uses the normal MUI error state. Warning text starts with `Warning:` and uses the warning color. Do not reserve blank helper-text space, clip feedback to one line, or use a tooltip as the only way to read it.\n\nUse `DialogNotice` and `DialogNoticeRegion` from `frontend/src/components/Dialog/` for non-field notices. A contextual condition known when the dialog opens belongs in the shell's `contextualNotice` slot, after its description and before the body. A result caused by an action belongs in the `actionNotice` slot immediately above the actions. Idle notices render no alert. An error alert uses the default dynamic `role=\"alert\"`; a non-urgent warning uses `role=\"status\"`. Do not move focus to an alert.\n\nOrdinary settings persist a valid committed value immediately. Selects, toggles, and checkboxes commit on change. Text and numeric fields commit on blur or Enter after local validation succeeds. Keep invalid candidates locally and associate their error with the field. Each field has at most one in-flight request; disable every representation of that field while it is pending, but do not queue, debounce, batch, or serialize unrelated fields. Show a `role=\"status\"` saving indicator only while active, then a brief saved indicator. A failed write remains a readable field error until editing or a later success resolves it.\n\nEvery settings update uses exactly one discriminated `{ field, value }` request and receives the matching canonical pair. Apply a response only to its matching field. Complete settings state is read through `GET`; routine settings pages have no Save, reset, dirty-state, or success-alert workflow. File Search and SMB policy fields are independent persisted keys; the backend validates correlated aggregates transactionally. SMB policy writes retain their full post-commit runtime refresh lifecycle, while its read-chunk-size update does not trigger that lifecycle.\n\n`userSettingsStore` is the sole frontend boundary for `/auth/me/settings`. Components use its field selectors and `useCurrentUserSetting()` hook, retain only local drafts/previews, and never store server-backed user settings in local storage. The store hydrates for identity changes, rejects stale requests, allows one write per field, and refreshes other tabs from invalidation-only BroadcastChannel messages.\n\nDuring a cancellable operation, keep its cancellation action enabled unless the owner is already processing the cancellation request. Move focus to that action when the pending state starts. Keep the primary action disabled while the operation is active. Archive progress must report only data actually provided by the operation: archive creation shows an indeterminate status, and extraction may show its processed-member count without inventing byte totals or an item total.\n\n## Implementation Checklist\n\n1. Start with `ResponsiveDialogShell` for the responsive Drawer and Dialog shell.\n2. Wrap the fields in `FormSurface` and one or more `FormGroup` components.\n3. Put every field in `FormRow`.\n4. Use `FormFieldLabel` only for a multi-field editor at `md` or wider. Keep one- and two-field operation dialogs in a single column with floating MUI labels at every width.\n5. Keep the below-`md` MUI `label`, `InputLabel`, and active `FormHelperText` props in the concrete control. Use normal field height for inline-labelled one- or two-field operation dialogs; do not reserve helper-text space.\n6. Use `SettingsFormSection` between related groups instead of recreating section borders and title spacing locally.\n7. Reuse the shared action styles when the dialog has split or responsive actions.\n8. Render conditional fields or sections only when their state applies, while keeping each visible control in a `FormRow`.\n\nFor a non-form dialog, start with `ResponsiveDialogShell` and retain only the content, selection, workflow, and keyboard behavior specific to that dialog. Do not duplicate MUI `Dialog`, `Drawer`, sticky mobile actions, focus restoration, or dialog surface styling in the owning component.\n\n## Accessibility And Validation\n\nAssociate desktop controls with their external labels and descriptions using `htmlFor`, `labelId`, and `aria-describedby` as appropriate. Preserve a description ID when an error replaces the description so the relationship remains valid.\n\nAfter a failed save or test, focus the first invalid field. Do not remove normal MUI error states from controls; the desktop error text supplements them by making the issue readable in the label column.\n\nUse field-level errors for validation that the dialog can determine before submitting. Do not repeat a field-owned error in a form-level alert. Error text must explain the cause and the corrective action, not only name a failed rule. Bounded reflow when feedback appears is expected and preferred to hidden space.\n\nPrefer a safe, valid default over presenting a predictable error when the dialog can infer the intended correction. For example, a one-item copy into its source directory should prefill an extension-aware name such as `report (copy).pdf`. Do not apply this pattern to a same-directory move: it is a rename operation, so the user must deliberately choose the new name.\n\nUse a stable form-level alert only when no editable field owns the remedy, such as a multi-item copy whose destination directory is also its source directory. Use error severity when the state blocks confirmation. Keep API failures in this form-level feedback region as well, above the form surface so they do not disrupt a desktop field row.\n\n## Testing And Review\n\nFor every dialog that adopts this pattern, cover all of the following:\n\n- The mobile Drawer and the `sm` through `\u003cmd` Dialog use the same single-column form semantics.\n- A populated narrow-screen field uses a floating MUI label, normal control height, and helper text below the field.\n- A multi-field editor retains external labels, compact controls, and desktop-only row dividers at `md` and above.\n- A one- or two-field operation dialog remains single-column and keeps floating labels at `md` and above.\n- Errors, focus-first-invalid behavior, keyboard handling, and pending action states still work.\n- The surface, controls, and helper text remain legible in both light and dark themes.\n- Long filenames and paths remain one line at phone, tablet, and desktop widths; shortened values expose the complete identifier only on hover.\n- Identifier rendering remains correct for mixed left-to-right and right-to-left text, including after the available width changes.\n- A cancellable pending workflow focuses its cancellation action and does not submit a duplicate request.\n\nFor every non-form dialog that adopts the shared shell, cover all of the following:\n\n- The phone Drawer has reachable actions above safe-area insets and does not obscure content in a short viewport.\n- Keyboard focus, Enter, Escape cancellation, and the dialog-specific safe default still work. Escape must always issue the dialog's cancellation request.\n- Picker and workflow state remains usable with a keyboard.\n- Dialog content and action states remain legible in light and dark themes.\n\nUse a live browser check at a phone width and a desktop width in addition to focused tests. Check a short viewport as well so the fixed mobile actions do not obscure the final control.\n", "2.0": "+++\ntitle = \"Settings Forms and Actions\"\n+++\n\nUse these conventions for settings pages and stateful settings editors. Pages share section, surface, and action styles. Editors keep the same form behavior across a phone drawer, a narrow dialog, and a desktop dialog without separate mobile and desktop forms.\n\nThe page reference is `frontend/src/pages/LocalDrivesSettings.tsx`; the dialog reference is `frontend/src/components/Admin/ConnectionDialog.tsx`.\n\n## When To Use It\n\nUse the page conventions for settings content and actions. Use the dialog pattern when an editor changes several related settings and needs validation, field descriptions, or more than one action.\n\nDo not use the form pattern for a confirmation or destructive-action dialog. Those should continue to use `ResponsiveDialogShell` directly with focused content and actions.\n\n## Settings Page Layout and Actions\n\nCompose settings pages with `SettingsPage`, `SettingsSectionList`, and `SettingsGroup`. Use `FormSurface` for the subdued background of an action section, not an additional bordered card. For action sections, put the description or metadata on the left and controls on the right in a `FormRow`: the columns stack below `md` and share the row at `md` and above. Right-align actions on desktop, allow them to wrap, and keep result notices below the row. An informational section such as Local Drives' Current status can keep its own layout; don't force it into an action row.\n\nChoose button styling by the action's role, not by whether its MUI variant is `outlined` or `contained`:\n\n| Role | Treatment | Example |\n|---|---|---|\n| Regular or secondary | Neutral `settingsUtilityButtonSx`; on a grey `FormSurface`, use `settingsFormSurfaceUtilityButtonSx` so the overlay background shows through, as it does for dialog inputs. Keep the existing border, hover, and keyboard-focus treatment. | Account \u003e Change password; Local Drives \u003e Test Current Pairing. |\n| Danger or alert | Red-tinted `settingsDestructiveButtonSx` for settings-page actions. Use the dialog action rules below for the confirmation. | Local Drives \u003e Unpair This Browser. |\n| Main or default | Prominent `settingsPrimaryButtonSx` for the main action on a grey settings-page surface and for the main action in a page footer or dialog. Avoid giving several routine actions the same emphasis. | Authentication \u003e Configure OIDC; Local Drives \u003e Pair This Browser. |\n\nAdd a relevant `@mui/icons-material` icon with `startIcon` to labeled outlined or contained settings-page action buttons that lack one. Leave text-only buttons, including buttons without an explicit outlined or contained variant, without icons. Adding an icon must not change the button's variant, colors, label, or behavior.\n\n## User Directory Layout\n\nUser Management renders roles and statuses as ordinary text, with each simultaneous status on its own line. Summary counts and removable filters remain badges. Keep column headings and cell values readable: wrap headings, email addresses, usernames, provider names, and other long values without truncating their underlying text. Top-align row contents, and reserve space for sort icons and row actions.\n\nUse the settings content container's width to choose between the desktop grid and stacked records, with a shared 40rem breakpoint for the table and its toolbar. Changing selected columns must not change the layout breakpoint. A narrow settings overlay must stack even on a wide screen. Preserve every selected field when stacking; don't introduce horizontal scrolling or silently hide columns. Show timestamps as a short localized date and time on separate lines, retaining the full timestamp in a tooltip and the original value in a semantic `time` element.\n\nPlace the desktop column chooser icon at the far-right end of the table header, above the row actions. In stacked layouts, place the Columns control at the toolbar's right edge. Keep the toolbar control available while the directory is loading or empty. Anchor the menu to the visible control, reposition it when the settings container resizes, and return focus to the visible control when it closes.\n\nValidate the layout in a real browser with all columns enabled, long identifiers, multiple statuses, different regional formats, narrow containers, mobile widths, and zoom. Component tests don't measure text overlap or container-query behavior.\n\n## Dialog Categories\n\nUse `ResponsiveDialogShell` from `frontend/src/components/Dialog/ResponsiveDialogShell.tsx` as the shared shell for every ordinary application dialog. It provides responsive Drawer and Dialog behavior, safe-area actions, overlay/form surface tokens, title and description relationships, close blocking, and focus restoration.\n\nSmall dialogs use traditional Cancel and confirmation actions; do not add a top-right close button.\n\nChoose the content pattern that matches the job:\n\n| Dialog type | Use | Examples |\n|---|---|---|\n| Multi-field editor | `ResponsiveDialogShell` with the form building blocks below. | Connections, users, OIDC configuration, copy or move. |\n| One- or two-field editor | `ResponsiveDialogShell` with a single-column form surface. Keep the floating MUI label at every width. | Create, rename, copy, and move. |\n| Decision | `ResponsiveDialogShell` with compact content and actions. Do not add `FormSurface`. | Delete, overwrite conflict, application update, connection test result. |\n| Picker | `ResponsiveDialogShell` with a listbox or selection grid. Keep the picker\u2019s keyboard and selection semantics in the owning component. | Viewer and theme pickers. |\n| Short workflow | `ResponsiveDialogShell` with state-specific body and actions. | Companion pairing. |\n| Full-screen workspace | Keep the specialized full-screen viewer shell. Share only reusable behavior that does not interfere with the viewer\u2019s focus, toolbar, or third-party integration. | Image, PDF, Markdown, and text viewers. |\n\nThe desktop settings overlay and mobile settings drawer are navigation containers, not form dialogs. Keep their information architecture separate while composing settings-form pages inside them.\n\n## Keyboard Isolation\n\n`ResponsiveDialogShell` establishes a keyboard shortcut scope automatically for both its Drawer and Dialog layouts. While it's open, `useKeyboardShortcuts` ignores background registrations and lets the innermost open dialog own shortcuts, including when a control portals outside the dialog. The shell also stops key events from bubbling into parent workspace handlers. Closing the dialog releases its scope; normal shortcut handling resumes when focus returns to the workspace.\n\nDon't add dialog-specific flags to parent shortcut handlers to provide this isolation. Keep ordinary dialog keyboard behavior in the shell's `onKeyDown` or `onEscape` callbacks. If dialog content needs `useKeyboardShortcuts`, register it in a child component rendered inside the shell so it inherits the dialog's scope, not in the component that creates the shell. Existing focus trapping and interactive-control checks still apply.\n\nEscape dismissal goes through MUI's modal close callback, preserving its top-modal and IME process-key checks. `onEscape`, when supplied, replaces the normal Escape close action and runs once, even when `disableClose` blocks ordinary closing. Use it for cancellation requests during pending operations. Close buttons and backdrop requests still use `onClose` and respect `disableClose`. Don't add document-level Escape listeners or duplicate Escape closing in `onKeyDown`; the shared shell owns that behavior.\n\n## Dialog Action Buttons\n\nChoose each action's treatment by what it does, including in decisions embedded inside full-screen viewers. Keep the viewer workspace shell and toolbars separate from its decision dialogs.\n\n| Role | Treatment | Example |\n|---|---|---|\n| Destructive confirmation | MUI `variant=\"contained\" color=\"error\"`, as in the File delete dialog. Do not use the red-tinted settings-page `settingsDestructiveButtonSx` or introduce another red button style. | Delete, Discard unsaved changes, or Continue with overwrite selected. |\n| Main non-destructive action | MUI `variant=\"contained\"` in the theme's primary color. | Create directory, Save, Retry, or the sole Close action. |\n| Secondary or alternate action | MUI `variant=\"outlined\"` with the existing subdued utility fill and focus treatment. | Cancel, Later, Ignore, or Open without saving. |\n\nAn action's role can change with the selected option: a conflict dialog's Continue is destructive only when it will overwrite an existing item. When a decision offers both Save and Discard, distinguish the primary and destructive actions without changing what either one does. Do not restyle settings-page triggers when styling their confirmation dialogs.\n\nVisual priority does not determine Enter behavior. For safety-critical decisions, focus the least destructive action on opening; for input workflows, focus the first input. Never make a destructive action the default Enter action unless the user has already focused it. Keep cancellation available and focused during cancellable pending operations. Use `ResponsiveDialogShell` for application confirmations rather than native `window.confirm`, whose buttons cannot follow these styles.\n\n## Shared Building Blocks\n\nImport reusable structural primitives and control styles from `frontend/src/components/Form/FormLayout.tsx`. Settings-only sections remain in `frontend/src/components/Settings/SettingsFormLayout.tsx`.\n\n| Building block | Responsibility |\n|---|---|\n| `FormSurface` | Provides the shared form-surface background and interior padding. |\n| `FormGroup` | Groups related rows and adds row dividers only at the desktop breakpoint. |\n| `FormRow` | Uses one column below `md` and the two-column label/control grid at `md` and above. |\n| `FormFieldLabel` | Renders a desktop label with its description or active error/warning. |\n| `SettingsFormSection` | Separates groups with the standard settings heading, subdued divider, and spacing. |\n| `SettingsSelectMenuItem` | Renders a select option with a label and supporting description. |\n| `SettingsPasswordVisibilityToggle` | Renders the shared show/hide password adornment. The owning dialog keeps password visibility state and translated labels. |\n| `formFieldControlSx` | Aligns a control to the desktop control column. |\n| `formSelectControlSx` | Makes a desktop select content-width and right-aligned. |\n| `formOutlinedControlSx` | Applies the shared outlined-field, focus, error, and floating-label treatment. |\n| `formSelectSx` and `formSelectMenuProps` | Keep select values, icons, and options at the standard subdued text color. |\n\nKeep field state, API calls, validation rules, translations, and the concrete MUI controls in the owning dialog. The shared layer owns layout and presentation; it must not become a schema-driven form engine.\n\n## Responsive Contract\n\nMulti-field settings editors have exactly two form layouts. One- and two-field operation dialogs stay single-column at every width so long names and paths retain the available width.\n\n### Below `md`\n\nUse one column in both responsive shells.\n\n- Below `sm`, `ResponsiveDialogShell` renders the form in a Drawer.\n- From `sm` through `\u003cmd`, it renders the same form in a Dialog.\n- Use normal-height MUI outlined controls.\n- Keep MUI labels inside empty fields and floating in the outline after focus or entry.\n- Keep descriptions and validation errors directly below their controls as MUI helper text.\n- Use the grouped surface and section heading, but do not show individual field-row dividers.\n\n### At `md` And Above For Multi-Field Editors\n\nUse the two-column desktop layout.\n\n- Put labels and descriptions in the left column.\n- Put compact controls in the right column.\n- For text inputs and selects with an external label in the left column, use MUI `size=\"small\"` and omit the control's `label` or `InputLabel`. The left-column label is the only visible label; associate it with the control so it remains accessible. Below `md`, restore the control's floating label and normal height.\n- Replace the left-column description with the validation error instead of showing helper text below the input.\n- Keep full-width text inputs within the control column.\n- Use content-width, right-aligned selects when the selected option remains readable.\n- For checkboxes and switches, use the external label and description on the left, with the control in the right column. Keep the control label and helper text next to the control below `md`.\n- For boolean settings, use a `Switch` with a visible `On` or `Off` state label. Let Material UI apply its standard palette colors.\n- For native `datetime-local` inputs, preserve the MUI shrunk input label below `md`; use the external desktop label at `md` and above.\n- Show subdued dividers between rows in a group.\n\n## Control Conventions\n\nApply `settingsSelectSx` and `settingsSelectMenuProps` to every settings `Select`. Use `SettingsSelectMenuItem` when an option needs a short explanation below its label.\n\nUse `SettingsPasswordVisibilityToggle` as the end adornment for password fields. Keep its `visible` state, toggle handler, and localized show/hide labels in the owning dialog.\n\nUse `DialogReadOnlyField` for a name, path, connection, or other value that a dialog shows without allowing the user to change it. Give the field a specific label such as `Destination directory` or `File to delete`; do not recreate a styled text pill. Keep the normal MUI field height when its label is inside the outlined field. Use a subdued read-only surface while keeping long values selectable.\n\nWrite the dialog description as the outcome of the selected action. State what will be copied, moved, replaced, skipped, or deleted and name the source item for a single-item operation, then present the affected value in a labelled read-only field. Keep notices tied to their current condition: a no-op destination notice must disappear as soon as a renamed target makes the operation valid, without changing the dialog's layout.\n\n## Operation Context\n\nOperation dialogs show their subject and destination independently of translated prose. This lets a translated description use its natural word order and keeps a long identifier from making the dialog hard to scan.\n\nUse `DialogOperationContext` for passive operation metadata. Each entry has a translated label and a value with either the `fileName` or `path` kind. The component renders a vertical definition list, so every filename and path occupies its own line and does not share that line with explanatory text.\n\n`OverwriteConflictDialog` is the deliberate exception. Its compact Existing item and Incoming item metadata grids remain intact because they support side-by-side conflict comparison. Use `DialogIdentifierDisplay` for each Path value in those grids, but do not replace the grids with `DialogOperationContext`.\n\nUse `DialogIdentifierDisplay` inside this context rather than truncating an identifier locally. It keeps the full value in the accessible name, applies bidi isolation with `bdi` and `dir=\"auto\"`, and abbreviates only the visual value when the available width requires it. A shortened value has a hover-only tooltip with its full value. Do not make the identifier focusable and do not reveal the tooltip on focus or touch.\n\nFile-name shortening preserves the extension where possible. Path shortening preserves useful leading and trailing segments. Both use grapheme-aware boundaries, so combining characters and emoji sequences are never split. Breadcrumb segment labels must use `truncateTextByGrapheme` from `utils/pathDisplay` for the same reason.\n\nUse outcome-only translation strings for the dialog description. Do not interpolate filenames or paths into `Trans` text. For example, a single-item copy describes copying the item to the destination directory, then context rows identify `Source item` and `Destination directory`.\n\n## Feedback And Persistence\n\nRender feedback only while it is active. Field errors and warnings belong to their control; use normal MUI helper text below `md`, and pass `FieldFeedback` to `FormFieldLabel` at `md` and above so it replaces the left-column description. Error feedback uses the normal MUI error state. Warning text starts with `Warning:` and uses the warning color. Do not reserve blank helper-text space, clip feedback to one line, or use a tooltip as the only way to read it.\n\nUse `DialogNotice` and `DialogNoticeRegion` from `frontend/src/components/Dialog/` for non-field notices. A contextual condition known when the dialog opens belongs in the shell's `contextualNotice` slot, after its description and before the body. A result caused by an action belongs in the `actionNotice` slot immediately above the actions. Idle notices render no alert. An error alert uses the default dynamic `role=\"alert\"`; a non-urgent warning uses `role=\"status\"`. Do not move focus to an alert.\n\nOrdinary settings persist a valid committed value immediately. Selects, toggles, and checkboxes commit on change. Text and numeric fields commit on blur or Enter after local validation succeeds. Keep invalid candidates locally and associate their error with the field. Each field has at most one in-flight request; disable every representation of that field while it is pending, but do not queue, debounce, batch, or serialize unrelated fields. Show a `role=\"status\"` saving indicator only while active, then a brief saved indicator. A failed write remains a readable field error until editing or a later success resolves it.\n\nEvery settings update uses exactly one discriminated `{ field, value }` request and receives the matching canonical pair. Apply a response only to its matching field. Complete settings state is read through `GET`; routine settings pages have no Save, reset, dirty-state, or success-alert workflow. File Search and SMB policy fields are independent persisted keys; the backend validates correlated aggregates transactionally. SMB policy writes retain their full post-commit runtime refresh lifecycle, while its read-chunk-size update does not trigger that lifecycle.\n\n`userSettingsStore` is the sole frontend boundary for `/auth/me/settings`. Components use its field selectors and `useCurrentUserSetting()` hook, retain only local drafts/previews, and never store server-backed user settings in local storage. The store hydrates for identity changes, rejects stale requests, allows one write per field, and refreshes other tabs from invalidation-only BroadcastChannel messages.\n\nDuring a cancellable operation, keep its cancellation action enabled unless the owner is already processing the cancellation request. Move focus to that action when the pending state starts. Keep the primary action disabled while the operation is active. Archive progress must report only data actually provided by the operation: archive creation shows an indeterminate status, and extraction may show its processed-member count without inventing byte totals or an item total.\n\n## Implementation Checklist\n\n1. Start with `ResponsiveDialogShell` for the responsive Drawer and Dialog shell.\n2. Wrap the fields in `FormSurface` and one or more `FormGroup` components.\n3. Put every field in `FormRow`.\n4. Use `FormFieldLabel` only for a multi-field editor at `md` or wider. Keep one- and two-field operation dialogs in a single column with floating MUI labels at every width.\n5. Keep the below-`md` MUI `label`, `InputLabel`, and active `FormHelperText` props in the concrete control. Use normal field height for inline-labelled one- or two-field operation dialogs; do not reserve helper-text space.\n6. Use `SettingsFormSection` between related groups instead of recreating section borders and title spacing locally.\n7. Reuse the shared action styles when the dialog has split or responsive actions.\n8. Render conditional fields or sections only when their state applies, while keeping each visible control in a `FormRow`.\n\nFor a non-form dialog, start with `ResponsiveDialogShell` and retain only the content, selection, workflow, and keyboard behavior specific to that dialog. Do not duplicate MUI `Dialog`, `Drawer`, sticky mobile actions, focus restoration, or dialog surface styling in the owning component.\n\n## Accessibility And Validation\n\nAssociate desktop controls with their external labels and descriptions using `htmlFor`, `labelId`, and `aria-describedby` as appropriate. Preserve a description ID when an error replaces the description so the relationship remains valid.\n\nAfter a failed save or test, focus the first invalid field. Do not remove normal MUI error states from controls; the desktop error text supplements them by making the issue readable in the label column.\n\nUse field-level errors for validation that the dialog can determine before submitting. Do not repeat a field-owned error in a form-level alert. Error text must explain the cause and the corrective action, not only name a failed rule. Bounded reflow when feedback appears is expected and preferred to hidden space.\n\nPrefer a safe, valid default over presenting a predictable error when the dialog can infer the intended correction. For example, a one-item copy into its source directory should prefill an extension-aware name such as `report (copy).pdf`. Do not apply this pattern to a same-directory move: it is a rename operation, so the user must deliberately choose the new name.\n\nUse a stable form-level alert only when no editable field owns the remedy, such as a multi-item copy whose destination directory is also its source directory. Use error severity when the state blocks confirmation. Keep API failures in this form-level feedback region as well, above the form surface so they do not disrupt a desktop field row.\n\n## Testing And Review\n\nFor settings-page action sections, check the one-column layout below `md` and the two-column description/action layout at `md` and above. Check neutral-button contrast against grey form surfaces in light and dark themes, including hover and keyboard focus. Check that added icons do not change accessible names or cause button labels to overflow at phone widths. Keep informational sections readable without imposing the action-row grid, and verify that notices remain below the row.\n\nFor dialog actions, check contained error and primary buttons and outlined secondary buttons in light and dark themes, including hover and keyboard focus. Verify that option-dependent destructive actions change treatment without changing their safe initial focus or Enter behavior.\n\nFor every dialog that adopts this pattern, cover all of the following:\n\n- The mobile Drawer and the `sm` through `\u003cmd` Dialog use the same single-column form semantics.\n- A populated narrow-screen field uses a floating MUI label, normal control height, and helper text below the field.\n- A multi-field editor retains external labels, compact controls, and desktop-only row dividers at `md` and above.\n- A one- or two-field operation dialog remains single-column and keeps floating labels at `md` and above.\n- Errors, focus-first-invalid behavior, keyboard handling, and pending action states still work.\n- The surface, controls, and helper text remain legible in both light and dark themes.\n- Long filenames and paths remain one line at phone, tablet, and desktop widths; shortened values expose the complete identifier only on hover.\n- Identifier rendering remains correct for mixed left-to-right and right-to-left text, including after the available width changes.\n- A cancellable pending workflow focuses its cancellation action and does not submit a duplicate request.\n\nFor every non-form dialog that adopts the shared shell, cover all of the following:\n\n- The phone Drawer has reachable actions above safe-area insets and does not obscure content in a short viewport.\n- Keyboard focus, Enter, Escape cancellation, and the dialog-specific safe default still work. Escape must always issue the dialog's cancellation request.\n- Picker and workflow state remains usable with a keyboard.\n- Dialog content and action states remain legible in light and dark themes.\n\nUse a live browser check at a phone width and a desktop width in addition to focused tests. Check a short viewport as well so the fixed mobile actions do not obscure the final control.\n"}, "flags": {"has_branched": true, "has_inherited": false, "has_structural": false, "has_invalid": false}}, {"id": "section:developer-guide/companion-architecture", "parent_id": "book:developer-guide", "depth": 1, "kind": "section", "label": "companion-architecture", "title": "Companion Architecture", "path": "developer-guide/companion-architecture", "has_children": true, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Companion Architecture\"\n+++\n\nThe companion exists because some valuable workflows cannot be delivered by the browser app alone.\n\nStart with:\n\n- [Companion Overview](./companion-overview/)\n- [Companion Runtime and Native-App Editing](./companion-runtime-and-native-app-editing/)\n- [Browser-to-Companion Trust Model](./browser-to-companion-trust-model/)\n- [Local-Drive and Save-Back Pipeline](./local-drive-and-save-back-pipeline/)\n\nUse this section when you are changing local-drive access, native-app editing, pairing, or desktop-side diagnostics.\n", "0.8": "+++\ntitle = \"Companion Architecture\"\n+++\n\nThe companion exists because some valuable workflows cannot be delivered by the browser app alone.\n\nStart with:\n\n- [Companion Overview](./companion-overview/)\n- [Companion Runtime and Native-App Editing](./companion-runtime-and-native-app-editing/)\n- [Browser-to-Companion Trust Model](./browser-to-companion-trust-model/)\n- [Local-Drive and Save-Back Pipeline](./local-drive-and-save-back-pipeline/)\n\nUse this section when you are changing local-drive access, native-app editing, pairing, or desktop-side diagnostics.\n", "0.9": "+++\ntitle = \"Companion Architecture\"\n+++\n\nThe companion exists because some valuable workflows cannot be delivered by the browser app alone.\n\nStart with:\n\n- [Companion Overview](./companion-overview/)\n- [Companion Runtime and Native-App Editing](./companion-runtime-and-native-app-editing/)\n- [Browser-to-Companion Trust Model](./browser-to-companion-trust-model/)\n- [Local-Drive and Save-Back Pipeline](./local-drive-and-save-back-pipeline/)\n\nUse this section when you are changing local-drive access, native-app editing, pairing, or desktop-side diagnostics.\n", "1.0": "+++\ntitle = \"Companion Architecture\"\n+++\n\nThe companion exists because some valuable workflows cannot be delivered by the browser app alone.\n\nStart with:\n\n- [Companion Overview](./companion-overview/)\n- [Companion Runtime and Native-App Editing](./companion-runtime-and-native-app-editing/)\n- [Browser-to-Companion Trust Model](./browser-to-companion-trust-model/)\n- [Local-Drive and Save-Back Pipeline](./local-drive-and-save-back-pipeline/)\n\nUse this section when you are changing local-drive access, native-app editing, pairing, or desktop-side diagnostics.\n", "2.0": "+++\ntitle = \"Companion Architecture\"\n+++\n\nThe companion exists because some valuable workflows cannot be delivered by the browser app alone.\n\nStart with:\n\n- [Companion Overview](./companion-overview/)\n- [Companion Runtime and Native-App Editing](./companion-runtime-and-native-app-editing/)\n- [Browser-to-Companion Trust Model](./browser-to-companion-trust-model/)\n- [Local-Drive and Save-Back Pipeline](./local-drive-and-save-back-pipeline/)\n\nUse this section when you are changing local-drive access, native-app editing, pairing, or desktop-side diagnostics.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/companion-architecture/companion-overview", "parent_id": "section:developer-guide/companion-architecture", "depth": 2, "kind": "page", "label": "companion-overview", "title": "Companion Overview", "path": "developer-guide/companion-architecture/companion-overview", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Companion Overview\"\n+++\n\nSambee Companion is a lightweight desktop application built with Tauri v2, a Preact UI, and a Rust backend.\n\nIt exists for two major reasons:\n\n- to enable native-app editing of files that originate in Sambee workflows\n- to provide a paired localhost API for local-drive access and browser-to-desktop integrations\n\n## The Two Main Capability Paths\n\n### Deep-Link Native-App Editing\n\nFor SMB-backed edit workflows:\n\n1. The browser starts the action.\n2. The OS launches or activates the companion through a `sambee://` deep link.\n3. The companion exchanges tokens, downloads the file, acquires an edit lock, and opens the file in a native app.\n4. The companion later uploads the result and releases the lock.\n\n### Paired Localhost API\n\nFor local-drive access and related desktop-side capabilities:\n\n1. The browser detects the companion on `127.0.0.1:21549`.\n2. Browser and companion perform an explicit pairing flow.\n3. The browser uses the authenticated localhost API to enumerate drives and perform local file operations.\n4. WebSocket notifications keep the browser updated when local directories change.\n\nFor the full desktop-side data path, continue to [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\nFor the deep-link runtime, native-app edit lifecycle, and operation recovery model, continue to [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/).\n\n## Why This Is a Separate App\n\nThe companion handles behavior the browser cannot safely or reliably do by itself.\n\n- launching installed native apps\n- accessing local drives on the user's computer\n- holding desktop-side state and recovery information\n- participating in OS-level integration such as deep-link registration and tray behavior\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/` | Preact UI, preferences, pairing windows, and desktop-facing interaction surfaces |\n| `companion/src-tauri/src/` | Rust backend for deep links, local API, file operations, logging, and integration with the OS |\n| `companion/src-tauri/src/server/` | localhost pairing, auth, drive enumeration, handlers, and watcher behavior |\n| `companion/src-tauri/src/commands/` | command handlers for file opening, upload, pairing, update, and related actions |\n\n## Trust and Safety Boundaries\n\nThe companion adds power, so it also adds security-sensitive behavior.\n\n- deep-link flows depend on short-lived tokens and server-side lock behavior\n- localhost API access is intentionally paired and authenticated\n- the app is single-instance so later deep links are routed to the running process\n- desktop-local behavior should not silently bypass the browser or backend contracts it depends on\n\n## What Usually Breaks When This Layer Changes\n\n- native-app editing lifecycle behavior\n- lock release or upload expectations after editing\n- browser pairing and local-drive discovery\n- localization sync or other browser-to-desktop coordination\n- platform-specific startup, packaging, or tray behavior\n\n## Go Deeper\n\n- [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/): deep-link ingress, app picker flow, operation persistence, recovery, and tray/window runtime behavior\n- [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/): deep links, pairing, localhost auth, and trust boundaries\n- [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/): how local-drive operations and SMB-backed native-app editing differ in practice\n\n## Validation Expectations\n\nWhen companion behavior changes, start with:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nThen add frontend or backend checks if the companion change alters a shared workflow contract.\n", "0.8": "+++\ntitle = \"Companion Overview\"\n+++\n\nSambee Companion is a lightweight desktop application built with Tauri v2, a Preact UI, and a Rust backend.\n\nIt exists for two major reasons:\n\n- to enable native-app editing of files that originate in Sambee workflows\n- to provide a paired localhost API for local-drive access and browser-to-desktop integrations\n\n## The Two Main Capability Paths\n\n### Deep-Link Native-App Editing\n\nFor SMB-backed edit workflows:\n\n1. The browser starts the action.\n2. The OS launches or activates the companion through a `sambee://` deep link.\n3. The companion exchanges tokens, downloads the file, acquires an edit lock, and opens the file in a native app.\n4. The companion later uploads the result and releases the lock.\n\n### Paired Localhost API\n\nFor local-drive access and related desktop-side capabilities:\n\n1. The browser detects the companion on `127.0.0.1:21549`.\n2. Browser and companion perform an explicit pairing flow.\n3. The browser uses the authenticated localhost API to enumerate drives and perform local file operations.\n4. WebSocket notifications keep the browser updated when local directories change.\n\nFor the full desktop-side data path, continue to [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\nFor the deep-link runtime, native-app edit lifecycle, and operation recovery model, continue to [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/).\n\n## Why This Is a Separate App\n\nThe companion handles behavior the browser cannot safely or reliably do by itself.\n\n- launching installed native apps\n- accessing local drives on the user's computer\n- holding desktop-side state and recovery information\n- participating in OS-level integration such as deep-link registration and tray behavior\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/` | Preact UI, preferences, pairing windows, and desktop-facing interaction surfaces |\n| `companion/src-tauri/src/` | Rust backend for deep links, local API, file operations, logging, and integration with the OS |\n| `companion/src-tauri/src/server/` | localhost pairing, auth, drive enumeration, handlers, and watcher behavior |\n| `companion/src-tauri/src/commands/` | command handlers for file opening, upload, pairing, update, and related actions |\n\n## Trust and Safety Boundaries\n\nThe companion adds power, so it also adds security-sensitive behavior.\n\n- deep-link flows depend on short-lived tokens and server-side lock behavior\n- localhost API access is intentionally paired and authenticated\n- the app is single-instance so later deep links are routed to the running process\n- desktop-local behavior should not silently bypass the browser or backend contracts it depends on\n\n## What Usually Breaks When This Layer Changes\n\n- native-app editing lifecycle behavior\n- lock release or upload expectations after editing\n- browser pairing and local-drive discovery\n- localization sync or other browser-to-desktop coordination\n- platform-specific startup, packaging, or tray behavior\n\n## Go Deeper\n\n- [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/): deep-link ingress, app picker flow, operation persistence, recovery, and tray/window runtime behavior\n- [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/): deep links, pairing, localhost auth, and trust boundaries\n- [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/): how local-drive operations and SMB-backed native-app editing differ in practice\n\n## Validation Expectations\n\nWhen companion behavior changes, start with:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nThen add frontend or backend checks if the companion change alters a shared workflow contract.\n", "0.9": "+++\ntitle = \"Companion Overview\"\n+++\n\nSambee Companion is a lightweight desktop application built with Tauri v2, a Preact UI, and a Rust backend.\n\nIt exists for two major reasons:\n\n- to enable native-app editing of files that originate in Sambee workflows\n- to provide a paired localhost API for local-drive access and browser-to-desktop integrations\n\n## The Two Main Capability Paths\n\n### Deep-Link Native-App Editing\n\nFor SMB-backed edit workflows:\n\n1. The browser starts the action.\n2. The OS launches or activates the companion through a `sambee://` deep link.\n3. The companion exchanges tokens, downloads the file, acquires an edit lock, and opens the file in a native app.\n4. The companion later uploads the result and releases the lock.\n\n### Paired Localhost API\n\nFor local-drive access and related desktop-side capabilities:\n\n1. The browser detects the companion on `127.0.0.1:21549`.\n2. Browser and companion perform an explicit pairing flow.\n3. The browser uses the authenticated localhost API to enumerate drives and perform local file operations.\n4. WebSocket notifications keep the browser updated when local directories change.\n\nFor the full desktop-side data path, continue to [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\nFor the deep-link runtime, native-app edit lifecycle, and operation recovery model, continue to [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/).\n\n## Why This Is a Separate App\n\nThe companion handles behavior the browser cannot safely or reliably do by itself.\n\n- launching installed native apps\n- accessing local drives on the user's computer\n- holding desktop-side state and recovery information\n- participating in OS-level integration such as deep-link registration and tray behavior\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/` | Preact UI, preferences, pairing windows, and desktop-facing interaction surfaces |\n| `companion/src-tauri/src/` | Rust backend for deep links, local API, file operations, logging, and integration with the OS |\n| `companion/src-tauri/src/server/` | localhost pairing, auth, drive enumeration, handlers, and watcher behavior |\n| `companion/src-tauri/src/commands/` | command handlers for file opening, upload, pairing, update, and related actions |\n\n## Trust and Safety Boundaries\n\nThe companion adds power, so it also adds security-sensitive behavior.\n\n- deep-link flows depend on short-lived tokens and server-side lock behavior\n- localhost API access is intentionally paired and authenticated\n- the app is single-instance so later deep links are routed to the running process\n- desktop-local behavior should not silently bypass the browser or backend contracts it depends on\n\n## What Usually Breaks When This Layer Changes\n\n- native-app editing lifecycle behavior\n- lock release or upload expectations after editing\n- browser pairing and local-drive discovery\n- localization sync or other browser-to-desktop coordination\n- platform-specific startup, packaging, or tray behavior\n\n## Go Deeper\n\n- [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/): deep-link ingress, app picker flow, operation persistence, recovery, and tray/window runtime behavior\n- [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/): deep links, pairing, localhost auth, and trust boundaries\n- [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/): how local-drive operations and SMB-backed native-app editing differ in practice\n\n## Validation Expectations\n\nWhen companion behavior changes, start with:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nThen add frontend or backend checks if the companion change alters a shared workflow contract.\n", "1.0": "+++\ntitle = \"Companion Overview\"\n+++\n\nSambee Companion is a lightweight desktop application built with Tauri v2, a Preact UI, and a Rust backend.\n\nIt exists for two major reasons:\n\n- to enable native-app editing of files that originate in Sambee workflows\n- to provide a paired localhost API for local-drive access and browser-to-desktop integrations\n\n## The Two Main Capability Paths\n\n### Deep-Link Native-App Editing\n\nFor SMB-backed edit workflows:\n\n1. The browser starts the action.\n2. The OS launches or activates the companion through a `sambee://` deep link.\n3. The companion exchanges tokens, downloads the file, acquires an edit lock, and opens the file in a native app.\n4. The companion later uploads the result and releases the lock.\n\n### Paired Localhost API\n\nFor local-drive access and related desktop-side capabilities:\n\n1. The browser detects the companion on `127.0.0.1:21549`.\n2. Browser and companion perform an explicit pairing flow.\n3. The browser uses the authenticated localhost API to enumerate drives and perform local file operations.\n4. WebSocket notifications keep the browser updated when local directories change.\n\nFor the full desktop-side data path, continue to [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\nFor the deep-link runtime, native-app edit lifecycle, and operation recovery model, continue to [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/).\n\n## Why This Is a Separate App\n\nThe companion handles behavior the browser cannot safely or reliably do by itself.\n\n- launching installed native apps\n- accessing local drives on the user's computer\n- holding desktop-side state and recovery information\n- participating in OS-level integration such as deep-link registration and tray behavior\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/` | Preact UI, preferences, pairing windows, and desktop-facing interaction surfaces |\n| `companion/src-tauri/src/` | Rust backend for deep links, local API, file operations, logging, and integration with the OS |\n| `companion/src-tauri/src/server/` | localhost pairing, auth, drive enumeration, handlers, and watcher behavior |\n| `companion/src-tauri/src/commands/` | command handlers for file opening, upload, pairing, update, and related actions |\n\n## Trust and Safety Boundaries\n\nThe companion adds power, so it also adds security-sensitive behavior.\n\n- deep-link flows depend on short-lived tokens and server-side lock behavior\n- localhost API access is intentionally paired and authenticated\n- the app is single-instance so later deep links are routed to the running process\n- desktop-local behavior should not silently bypass the browser or backend contracts it depends on\n\n## What Usually Breaks When This Layer Changes\n\n- native-app editing lifecycle behavior\n- lock release or upload expectations after editing\n- browser pairing and local-drive discovery\n- localization sync or other browser-to-desktop coordination\n- platform-specific startup, packaging, or tray behavior\n\n## Go Deeper\n\n- [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/): deep-link ingress, app picker flow, operation persistence, recovery, and tray/window runtime behavior\n- [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/): deep links, pairing, localhost auth, and trust boundaries\n- [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/): how local-drive operations and SMB-backed native-app editing differ in practice\n\n## Validation Expectations\n\nWhen companion behavior changes, start with:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nThen add frontend or backend checks if the companion change alters a shared workflow contract.\n", "2.0": "+++\ntitle = \"Companion Overview\"\n+++\n\nSambee Companion is a lightweight desktop application built with Tauri v2, a Preact UI, and a Rust backend.\n\nIt exists for two major reasons:\n\n- to enable native-app editing of files that originate in Sambee workflows\n- to provide a paired localhost API for local-drive access and browser-to-desktop integrations\n\n## The Two Main Capability Paths\n\n### Deep-Link Native-App Editing\n\nFor SMB-backed edit workflows:\n\n1. The browser starts the action.\n2. The OS launches or activates the companion through a `sambee://` deep link.\n3. The companion exchanges tokens, downloads the file, acquires an edit lock, and opens the file in a native app.\n4. The companion later uploads the result and releases the lock.\n\n### Paired Localhost API\n\nFor local-drive access and related desktop-side capabilities:\n\n1. The browser detects the companion on `127.0.0.1:21549`.\n2. Browser and companion perform an explicit pairing flow.\n3. The browser uses the authenticated localhost API to enumerate drives and perform local file operations.\n4. WebSocket notifications keep the browser updated when local directories change.\n\nFor the full desktop-side data path, continue to [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\nFor the deep-link runtime, native-app edit lifecycle, and operation recovery model, continue to [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/).\n\n## Why This Is a Separate App\n\nThe companion handles behavior the browser cannot safely or reliably do by itself.\n\n- launching installed native apps\n- accessing local drives on the user's computer\n- holding desktop-side state and recovery information\n- participating in OS-level integration such as deep-link registration and tray behavior\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/` | Preact UI, preferences, pairing windows, and desktop-facing interaction surfaces |\n| `companion/src-tauri/src/` | Rust backend for deep links, local API, file operations, logging, and integration with the OS |\n| `companion/src-tauri/src/server/` | localhost pairing, auth, drive enumeration, handlers, and watcher behavior |\n| `companion/src-tauri/src/commands/` | command handlers for file opening, upload, pairing, update, and related actions |\n\n## Trust and Safety Boundaries\n\nThe companion adds power, so it also adds security-sensitive behavior.\n\n- deep-link flows depend on short-lived tokens and server-side lock behavior\n- localhost API access is intentionally paired and authenticated\n- the app is single-instance so later deep links are routed to the running process\n- desktop-local behavior should not silently bypass the browser or backend contracts it depends on\n\n## What Usually Breaks When This Layer Changes\n\n- native-app editing lifecycle behavior\n- lock release or upload expectations after editing\n- browser pairing and local-drive discovery\n- localization sync or other browser-to-desktop coordination\n- platform-specific startup, packaging, or tray behavior\n\n## Go Deeper\n\n- [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/): deep-link ingress, app picker flow, operation persistence, recovery, and tray/window runtime behavior\n- [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/): deep links, pairing, localhost auth, and trust boundaries\n- [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/): how local-drive operations and SMB-backed native-app editing differ in practice\n\n## Validation Expectations\n\nWhen companion behavior changes, start with:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nThen add frontend or backend checks if the companion change alters a shared workflow contract.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Companion Overview\"\n+++\n\nSambee Companion is a lightweight desktop application built with Tauri v2, a Preact UI, and a Rust backend.\n\nIt exists for two major reasons:\n\n- to enable native-app editing of files that originate in Sambee workflows\n- to provide a paired localhost API for local-drive access and browser-to-desktop integrations\n\n## The Two Main Capability Paths\n\n### Deep-Link Native-App Editing\n\nFor SMB-backed edit workflows:\n\n1. The browser starts the action.\n2. The OS launches or activates the companion through a `sambee://` deep link.\n3. The companion exchanges tokens, downloads the file, acquires an edit lock, and opens the file in a native app.\n4. The companion later uploads the result and releases the lock.\n\n### Paired Localhost API\n\nFor local-drive access and related desktop-side capabilities:\n\n1. The browser detects the companion on `127.0.0.1:21549`.\n2. Browser and companion perform an explicit pairing flow.\n3. The browser uses the authenticated localhost API to enumerate drives and perform local file operations.\n4. WebSocket notifications keep the browser updated when local directories change.\n\nFor the full desktop-side data path, continue to [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\nFor the deep-link runtime, native-app edit lifecycle, and operation recovery model, continue to [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/).\n\n## Why This Is a Separate App\n\nThe companion handles behavior the browser cannot safely or reliably do by itself.\n\n- launching installed native apps\n- accessing local drives on the user's computer\n- holding desktop-side state and recovery information\n- participating in OS-level integration such as deep-link registration and tray behavior\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/` | Preact UI, preferences, pairing windows, and desktop-facing interaction surfaces |\n| `companion/src-tauri/src/` | Rust backend for deep links, local API, file operations, logging, and integration with the OS |\n| `companion/src-tauri/src/server/` | localhost pairing, auth, drive enumeration, handlers, and watcher behavior |\n| `companion/src-tauri/src/commands/` | command handlers for file opening, upload, pairing, update, and related actions |\n\n## Trust and Safety Boundaries\n\nThe companion adds power, so it also adds security-sensitive behavior.\n\n- deep-link flows depend on short-lived tokens and server-side lock behavior\n- localhost API access is intentionally paired and authenticated\n- the app is single-instance so later deep links are routed to the running process\n- desktop-local behavior should not silently bypass the browser or backend contracts it depends on\n\n## What Usually Breaks When This Layer Changes\n\n- native-app editing lifecycle behavior\n- lock release or upload expectations after editing\n- browser pairing and local-drive discovery\n- localization sync or other browser-to-desktop coordination\n- platform-specific startup, packaging, or tray behavior\n\n## Go Deeper\n\n- [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/): deep-link ingress, app picker flow, operation persistence, recovery, and tray/window runtime behavior\n- [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/): deep links, pairing, localhost auth, and trust boundaries\n- [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/): how local-drive operations and SMB-backed native-app editing differ in practice\n\n## Validation Expectations\n\nWhen companion behavior changes, start with:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nThen add frontend or backend checks if the companion change alters a shared workflow contract.\n", "0.8": "+++\ntitle = \"Companion Overview\"\n+++\n\nSambee Companion is a lightweight desktop application built with Tauri v2, a Preact UI, and a Rust backend.\n\nIt exists for two major reasons:\n\n- to enable native-app editing of files that originate in Sambee workflows\n- to provide a paired localhost API for local-drive access and browser-to-desktop integrations\n\n## The Two Main Capability Paths\n\n### Deep-Link Native-App Editing\n\nFor SMB-backed edit workflows:\n\n1. The browser starts the action.\n2. The OS launches or activates the companion through a `sambee://` deep link.\n3. The companion exchanges tokens, downloads the file, acquires an edit lock, and opens the file in a native app.\n4. The companion later uploads the result and releases the lock.\n\n### Paired Localhost API\n\nFor local-drive access and related desktop-side capabilities:\n\n1. The browser detects the companion on `127.0.0.1:21549`.\n2. Browser and companion perform an explicit pairing flow.\n3. The browser uses the authenticated localhost API to enumerate drives and perform local file operations.\n4. WebSocket notifications keep the browser updated when local directories change.\n\nFor the full desktop-side data path, continue to [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\nFor the deep-link runtime, native-app edit lifecycle, and operation recovery model, continue to [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/).\n\n## Why This Is a Separate App\n\nThe companion handles behavior the browser cannot safely or reliably do by itself.\n\n- launching installed native apps\n- accessing local drives on the user's computer\n- holding desktop-side state and recovery information\n- participating in OS-level integration such as deep-link registration and tray behavior\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/` | Preact UI, preferences, pairing windows, and desktop-facing interaction surfaces |\n| `companion/src-tauri/src/` | Rust backend for deep links, local API, file operations, logging, and integration with the OS |\n| `companion/src-tauri/src/server/` | localhost pairing, auth, drive enumeration, handlers, and watcher behavior |\n| `companion/src-tauri/src/commands/` | command handlers for file opening, upload, pairing, update, and related actions |\n\n## Trust and Safety Boundaries\n\nThe companion adds power, so it also adds security-sensitive behavior.\n\n- deep-link flows depend on short-lived tokens and server-side lock behavior\n- localhost API access is intentionally paired and authenticated\n- the app is single-instance so later deep links are routed to the running process\n- desktop-local behavior should not silently bypass the browser or backend contracts it depends on\n\n## What Usually Breaks When This Layer Changes\n\n- native-app editing lifecycle behavior\n- lock release or upload expectations after editing\n- browser pairing and local-drive discovery\n- localization sync or other browser-to-desktop coordination\n- platform-specific startup, packaging, or tray behavior\n\n## Go Deeper\n\n- [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/): deep-link ingress, app picker flow, operation persistence, recovery, and tray/window runtime behavior\n- [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/): deep links, pairing, localhost auth, and trust boundaries\n- [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/): how local-drive operations and SMB-backed native-app editing differ in practice\n\n## Validation Expectations\n\nWhen companion behavior changes, start with:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nThen add frontend or backend checks if the companion change alters a shared workflow contract.\n", "0.9": "+++\ntitle = \"Companion Overview\"\n+++\n\nSambee Companion is a lightweight desktop application built with Tauri v2, a Preact UI, and a Rust backend.\n\nIt exists for two major reasons:\n\n- to enable native-app editing of files that originate in Sambee workflows\n- to provide a paired localhost API for local-drive access and browser-to-desktop integrations\n\n## The Two Main Capability Paths\n\n### Deep-Link Native-App Editing\n\nFor SMB-backed edit workflows:\n\n1. The browser starts the action.\n2. The OS launches or activates the companion through a `sambee://` deep link.\n3. The companion exchanges tokens, downloads the file, acquires an edit lock, and opens the file in a native app.\n4. The companion later uploads the result and releases the lock.\n\n### Paired Localhost API\n\nFor local-drive access and related desktop-side capabilities:\n\n1. The browser detects the companion on `127.0.0.1:21549`.\n2. Browser and companion perform an explicit pairing flow.\n3. The browser uses the authenticated localhost API to enumerate drives and perform local file operations.\n4. WebSocket notifications keep the browser updated when local directories change.\n\nFor the full desktop-side data path, continue to [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\nFor the deep-link runtime, native-app edit lifecycle, and operation recovery model, continue to [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/).\n\n## Why This Is a Separate App\n\nThe companion handles behavior the browser cannot safely or reliably do by itself.\n\n- launching installed native apps\n- accessing local drives on the user's computer\n- holding desktop-side state and recovery information\n- participating in OS-level integration such as deep-link registration and tray behavior\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/` | Preact UI, preferences, pairing windows, and desktop-facing interaction surfaces |\n| `companion/src-tauri/src/` | Rust backend for deep links, local API, file operations, logging, and integration with the OS |\n| `companion/src-tauri/src/server/` | localhost pairing, auth, drive enumeration, handlers, and watcher behavior |\n| `companion/src-tauri/src/commands/` | command handlers for file opening, upload, pairing, update, and related actions |\n\n## Trust and Safety Boundaries\n\nThe companion adds power, so it also adds security-sensitive behavior.\n\n- deep-link flows depend on short-lived tokens and server-side lock behavior\n- localhost API access is intentionally paired and authenticated\n- the app is single-instance so later deep links are routed to the running process\n- desktop-local behavior should not silently bypass the browser or backend contracts it depends on\n\n## What Usually Breaks When This Layer Changes\n\n- native-app editing lifecycle behavior\n- lock release or upload expectations after editing\n- browser pairing and local-drive discovery\n- localization sync or other browser-to-desktop coordination\n- platform-specific startup, packaging, or tray behavior\n\n## Go Deeper\n\n- [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/): deep-link ingress, app picker flow, operation persistence, recovery, and tray/window runtime behavior\n- [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/): deep links, pairing, localhost auth, and trust boundaries\n- [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/): how local-drive operations and SMB-backed native-app editing differ in practice\n\n## Validation Expectations\n\nWhen companion behavior changes, start with:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nThen add frontend or backend checks if the companion change alters a shared workflow contract.\n", "1.0": "+++\ntitle = \"Companion Overview\"\n+++\n\nSambee Companion is a lightweight desktop application built with Tauri v2, a Preact UI, and a Rust backend.\n\nIt exists for two major reasons:\n\n- to enable native-app editing of files that originate in Sambee workflows\n- to provide a paired localhost API for local-drive access and browser-to-desktop integrations\n\n## The Two Main Capability Paths\n\n### Deep-Link Native-App Editing\n\nFor SMB-backed edit workflows:\n\n1. The browser starts the action.\n2. The OS launches or activates the companion through a `sambee://` deep link.\n3. The companion exchanges tokens, downloads the file, acquires an edit lock, and opens the file in a native app.\n4. The companion later uploads the result and releases the lock.\n\n### Paired Localhost API\n\nFor local-drive access and related desktop-side capabilities:\n\n1. The browser detects the companion on `127.0.0.1:21549`.\n2. Browser and companion perform an explicit pairing flow.\n3. The browser uses the authenticated localhost API to enumerate drives and perform local file operations.\n4. WebSocket notifications keep the browser updated when local directories change.\n\nFor the full desktop-side data path, continue to [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\nFor the deep-link runtime, native-app edit lifecycle, and operation recovery model, continue to [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/).\n\n## Why This Is a Separate App\n\nThe companion handles behavior the browser cannot safely or reliably do by itself.\n\n- launching installed native apps\n- accessing local drives on the user's computer\n- holding desktop-side state and recovery information\n- participating in OS-level integration such as deep-link registration and tray behavior\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/` | Preact UI, preferences, pairing windows, and desktop-facing interaction surfaces |\n| `companion/src-tauri/src/` | Rust backend for deep links, local API, file operations, logging, and integration with the OS |\n| `companion/src-tauri/src/server/` | localhost pairing, auth, drive enumeration, handlers, and watcher behavior |\n| `companion/src-tauri/src/commands/` | command handlers for file opening, upload, pairing, update, and related actions |\n\n## Trust and Safety Boundaries\n\nThe companion adds power, so it also adds security-sensitive behavior.\n\n- deep-link flows depend on short-lived tokens and server-side lock behavior\n- localhost API access is intentionally paired and authenticated\n- the app is single-instance so later deep links are routed to the running process\n- desktop-local behavior should not silently bypass the browser or backend contracts it depends on\n\n## What Usually Breaks When This Layer Changes\n\n- native-app editing lifecycle behavior\n- lock release or upload expectations after editing\n- browser pairing and local-drive discovery\n- localization sync or other browser-to-desktop coordination\n- platform-specific startup, packaging, or tray behavior\n\n## Go Deeper\n\n- [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/): deep-link ingress, app picker flow, operation persistence, recovery, and tray/window runtime behavior\n- [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/): deep links, pairing, localhost auth, and trust boundaries\n- [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/): how local-drive operations and SMB-backed native-app editing differ in practice\n\n## Validation Expectations\n\nWhen companion behavior changes, start with:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nThen add frontend or backend checks if the companion change alters a shared workflow contract.\n", "2.0": "+++\ntitle = \"Companion Overview\"\n+++\n\nSambee Companion is a lightweight desktop application built with Tauri v2, a Preact UI, and a Rust backend.\n\nIt exists for two major reasons:\n\n- to enable native-app editing of files that originate in Sambee workflows\n- to provide a paired localhost API for local-drive access and browser-to-desktop integrations\n\n## The Two Main Capability Paths\n\n### Deep-Link Native-App Editing\n\nFor SMB-backed edit workflows:\n\n1. The browser starts the action.\n2. The OS launches or activates the companion through a `sambee://` deep link.\n3. The companion exchanges tokens, downloads the file, acquires an edit lock, and opens the file in a native app.\n4. The companion later uploads the result and releases the lock.\n\n### Paired Localhost API\n\nFor local-drive access and related desktop-side capabilities:\n\n1. The browser detects the companion on `127.0.0.1:21549`.\n2. Browser and companion perform an explicit pairing flow.\n3. The browser uses the authenticated localhost API to enumerate drives and perform local file operations.\n4. WebSocket notifications keep the browser updated when local directories change.\n\nFor the full desktop-side data path, continue to [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\nFor the deep-link runtime, native-app edit lifecycle, and operation recovery model, continue to [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/).\n\n## Why This Is a Separate App\n\nThe companion handles behavior the browser cannot safely or reliably do by itself.\n\n- launching installed native apps\n- accessing local drives on the user's computer\n- holding desktop-side state and recovery information\n- participating in OS-level integration such as deep-link registration and tray behavior\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/` | Preact UI, preferences, pairing windows, and desktop-facing interaction surfaces |\n| `companion/src-tauri/src/` | Rust backend for deep links, local API, file operations, logging, and integration with the OS |\n| `companion/src-tauri/src/server/` | localhost pairing, auth, drive enumeration, handlers, and watcher behavior |\n| `companion/src-tauri/src/commands/` | command handlers for file opening, upload, pairing, update, and related actions |\n\n## Trust and Safety Boundaries\n\nThe companion adds power, so it also adds security-sensitive behavior.\n\n- deep-link flows depend on short-lived tokens and server-side lock behavior\n- localhost API access is intentionally paired and authenticated\n- the app is single-instance so later deep links are routed to the running process\n- desktop-local behavior should not silently bypass the browser or backend contracts it depends on\n\n## What Usually Breaks When This Layer Changes\n\n- native-app editing lifecycle behavior\n- lock release or upload expectations after editing\n- browser pairing and local-drive discovery\n- localization sync or other browser-to-desktop coordination\n- platform-specific startup, packaging, or tray behavior\n\n## Go Deeper\n\n- [Companion Runtime and Native-App Editing](../companion-runtime-and-native-app-editing/): deep-link ingress, app picker flow, operation persistence, recovery, and tray/window runtime behavior\n- [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/): deep links, pairing, localhost auth, and trust boundaries\n- [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/): how local-drive operations and SMB-backed native-app editing differ in practice\n\n## Validation Expectations\n\nWhen companion behavior changes, start with:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\n```\n\nThen add frontend or backend checks if the companion change alters a shared workflow contract.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/companion-architecture/companion-runtime-and-native-app-editing", "parent_id": "section:developer-guide/companion-architecture", "depth": 2, "kind": "page", "label": "companion-runtime-and-native-app-editing", "title": "Companion Runtime And Native App Editing", "path": "developer-guide/companion-architecture/companion-runtime-and-native-app-editing", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Companion Runtime and Native-App Editing\"\n+++\n\nThis page covers the companion runtime that sits between the browser's deep-link request and the desktop user's native editing session.\n\nUse it when a change affects:\n\n- deep-link handling and single-instance behavior\n- app selection and native-app launching\n- operation persistence, recovery, and temp-file lifecycle\n- tray, app-picker, large-file, and \"Done Editing\" window behavior\n\nFor localhost pairing and local-drive behavior, continue to [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) and [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\n## Runtime Modes and UI Surfaces\n\nThe companion is not a traditional always-visible desktop app.\n\nIn normal use it shifts between a few runtime modes:\n\n- tray-oriented background state when no editing dialog is open\n- a reused main window for app picker, preferences, large-file confirmation, and recovery dialogs\n- a dedicated pairing window for browser-to-companion approval\n- one \"Done Editing\" window per active native-app edit session\n\nThat split is deliberate. The companion should stay lightweight when idle, but it still needs focused UI surfaces for edit coordination and pairing approval.\n\nBecause the companion is a tray-oriented app, closing the last transient webview must not implicitly terminate the process. The runtime intentionally prevents last-window destruction from exiting the app; explicit quit requests from the tray still exit normally.\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/App.tsx` | frontend view routing for idle, app picker, preferences, recovery, and large-file flows |\n| `companion/src/components/` | desktop-facing UI surfaces such as `AppPicker`, `DoneEditingWindow`, `RecoveryDialog`, and `Preferences` |\n| `companion/src/stores/` | persisted frontend preferences for app selection and companion settings |\n| `companion/src-tauri/src/lib.rs` | Tauri setup, plugin wiring, deep-link handling, window management, tray behavior, and lifecycle orchestration |\n| `companion/src-tauri/src/commands/` | commands for file info, download, upload, app selection, pairing, localization, and updates |\n| `companion/src-tauri/src/http_client.rs` | shared backend HTTP clients, reverse-proxy cookie jars, request diagnostics, and URL sanitization |\n| `companion/src-tauri/src/app_registry/` | platform-specific native-app discovery and launch integration |\n| `companion/src-tauri/src/sync/` | operation persistence, temp-file handling, recycle retention, and recovery helpers |\n| `companion/src-tauri/src/token/` and `uri/` | URI parsing and bootstrap-token exchange for deep-link editing |\n\n## Deep-Link Ingress\n\nNative-app editing starts from a `sambee://open?...` URI.\n\nThe runtime pieces involved are:\n\n- `tauri-plugin-deep-link` for receiving the URI\n- `tauri-plugin-single-instance` so later URIs are forwarded to the running instance instead of launching competing copies\n- `uri/mod.rs` for parsing required parameters such as `server`, `token`, `connId`, and `path`\n- `token/mod.rs` for exchanging the short-lived URI token for a companion bootstrap token\n\nThe deep link can also carry theme data so the companion UI matches the browser-side theme during the editing flow.\n\n## Reverse-Proxy Authentication Path\n\nNative editing supports reverse proxies and SSO layers that require interactive browser authentication before backend API requests are allowed through.\n\nThe implemented flow is:\n\n1. Companion tries the normal URI-token exchange.\n2. If token exchange is intercepted by a login redirect or HTML sign-in page, the companion opens a dedicated `Sambee Authentication` webview.\n3. The user signs in through that embedded webview.\n4. Companion reads backend-origin cookies from that same webview and seeds its shared Rust `reqwest` cookie jar.\n5. Token exchange and the rest of the native-edit lifecycle reuse that authenticated client state.\n\nThe HTTP client store is keyed by normalized server URL. For each server, it keeps a stable cookie jar plus default and no-redirect clients. The no-redirect client is used where redirect responses are diagnostic signals, such as URI-token exchange. The default client is reused for file-info lookup, lock acquisition, download, upload, lock release, and heartbeat requests.\n\nThis matters for the trust model:\n\n- Browser-to-companion localhost pairing remains separate from reverse-proxy authentication.\n- The Sambee bearer token remains separate from reverse-proxy cookies.\n- External browser cookies are not read or imported.\n- Reverse-proxy cookies stay inside the companion-owned webview and Rust HTTP client state.\n- Cookie values must not be logged.\n\nCompanion automatically retries idempotent backend calls such as file-info lookup, lock acquisition, download, lock release, and heartbeats after reauthentication. Non-idempotent uploads are not replayed automatically; the runtime instead asks the user to retry the action after authentication has been refreshed.\n\nFor reverse-proxy auth robustness, the shared Companion HTTP clients stay on HTTP/1.1 rather than enabling HTTP/2.\n\nRequest failures are logged with classified diagnostics such as timeout, connect, request, body, decode, and status. URLs and chained source errors are sanitized before logging so deep-link tokens, proxy sessions, and other sensitive query values do not appear in logs.\n\n## Native-App Edit Lifecycle\n\nThe implemented lifecycle in `lib.rs` is intentionally explicit.\n\nAt a high level it is:\n\n1. parse the deep link\n2. exchange the URI token for a companion bootstrap token\n3. fetch file metadata for file-size checks and conflict baseline\n4. optionally pause for a large-file confirmation dialog\n5. acquire the backend edit lock and receive operation-scoped lock context\n6. download the file into the companion temp area\n7. create a `FileOperation`, persist its sidecar, and add it to the in-memory store\n8. show the app picker and wait for user selection\n9. open the local file in the selected native application\n10. spawn a dedicated \"Done Editing\" window\n11. start background renewal, heartbeat, and file-status polling\n\nTwo rules matter here:\n\n- the backend lock is acquired before the edit session is allowed to proceed\n- the companion records local operation state before handing control to the native app\n\nThose decisions are what make recovery and conflict handling possible after crashes or interrupted sessions.\n\n## App Selection and Native Launching\n\nThe companion keeps platform-specific native-app discovery behind `app_registry/`.\n\nThat layer is responsible for:\n\n- listing handlers for a file extension\n- surfacing the default app first when possible\n- returning enough information for the UI to distinguish executable paths and handler identifiers\n- launching the chosen app or falling back to system-default open behavior when appropriate\n\nThe app picker flow is coordinated through Tauri events.\n\n- the Rust runtime emits `show-app-picker`\n- the frontend displays `AppPicker`\n- the user response is sent back through `respond_app_selection`\n\nStored per-extension app preferences live in `appPreferences.ts`, which is how repeated opens can bypass unnecessary picker friction.\n\nOn Windows, the launch path is more subtle than a simple `CreateProcess` call because packaged handlers and opaque shell associations may need Windows shell invocation rather than direct executable launching.\n\n## Operation Model, Temp Files, and Recovery\n\nDeep-link editing is tracked through `FileOperation` in `sync/operations.rs`.\n\nEach operation records:\n\n- server URL, connection, and remote path\n- local temp-file path\n- current status\n- original modification time\n- chosen app name\n- operation-scoped lock context and server-side last-modified baseline\n\nThe companion keeps this state in two places:\n\n- an in-memory `OperationStore` for active runtime coordination\n- a sidecar on disk so the session can be recovered after a restart or crash\n\nThat persistence model supports the recovery flow shown through `RecoveryDialog` when leftover operations are discovered at startup.\n\nThe temp-file lifecycle is also intentionally not just \"download and delete\":\n\n- active sessions live in a managed temp area\n- completed or discarded files move through recycle and retention logic\n- retention duration is user-configurable through preferences\n\n## \"Done Editing\" and Explicit Save-Back\n\nThe companion does not try to infer when a user is \"probably done\" in their native editor.\n\nInstead it keeps a dedicated \"Done Editing\" window open while:\n\n- file status polling checks whether the local temp file changed\n- renewal and heartbeat requests keep the edit session and backend lock alive\n\nWhen the user explicitly finishes or discards the session, the companion can:\n\n- upload the modified file\n- release the backend lock\n- recycle the temp copy\n- update the tray and operation state\n\nThat explicit-confirmation model is one of the core product decisions behind native-app editing, not a UI accident.\n\n## Conflict and Recovery Handling\n\nThe companion keeps enough state to detect overwrite-sensitive conflicts.\n\nBefore completing an upload-sensitive flow, it compares the current server-side state with the baseline captured earlier in the edit session. If those diverge, the conflict dialog path is used instead of silently overwriting the server copy.\n\nThis is also why recovery state is more than a cosmetic convenience feature. It protects the editing workflow from leaving users with stranded temp files and unclear lock state after interruption.\n\n## Preferences, Pairing UI, and Update Checks\n\nThe reused main window also hosts companion preferences.\n\nCurrent public settings include:\n\n- upload conflict behavior\n- auto-start at sign-in\n- desktop notifications\n- update channel selection\n- temp-file retention period\n- paired-origin management\n\nThe update path itself is channel-aware and lives in `commands/update.rs`, but detailed release-feed and packaging workflow belongs with companion distribution and update documentation rather than this runtime page.\n\nThe pairing window is a separate UI surface because browser-to-companion approval is part of the trust boundary, not just another generic settings dialog.\n\n## What Usually Breaks When This Layer Changes\n\n- deep links reach the app, but the running instance does not receive forwarded URIs correctly\n- lock acquisition or release gets out of sync with the visible edit lifecycle\n- picker cancellation or launch failure leaves behind stale temp files or sidecars\n- operation recovery loses enough metadata that interrupted edits become hard to resolve safely\n- tray and window state drift apart from the actual set of active operations\n\n## Where to Continue\n\n- Use [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) for pairing, localhost auth, deep-link trust boundaries, and origin scoping.\n- Use [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/) for the difference between local-drive access and SMB-backed save-back.\n- Use [Companion Release Overview](../../release-and-versioning/companion-release-overview/) when the change affects packaged releases or updater rollout rather than runtime behavior.\n\n## Validation Expectations\n\nWhen this runtime changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe frontend and backend checks matter whenever the companion change alters a shared workflow contract.\n", "0.8": "+++\ntitle = \"Companion Runtime and Native-App Editing\"\n+++\n\nThis page covers the companion runtime that sits between the browser's deep-link request and the desktop user's native editing session.\n\nUse it when a change affects:\n\n- deep-link handling and single-instance behavior\n- app selection and native-app launching\n- operation persistence, recovery, and temp-file lifecycle\n- tray, app-picker, large-file, and \"Done Editing\" window behavior\n\nFor localhost pairing and local-drive behavior, continue to [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) and [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\n## Runtime Modes and UI Surfaces\n\nThe companion is not a traditional always-visible desktop app.\n\nIn normal use it shifts between a few runtime modes:\n\n- tray-oriented background state when no editing dialog is open\n- a reused main window for app picker, preferences, large-file confirmation, and recovery dialogs\n- a dedicated pairing window for browser-to-companion approval\n- one \"Done Editing\" window per active native-app edit session\n\nThat split is deliberate. The companion should stay lightweight when idle, but it still needs focused UI surfaces for edit coordination and pairing approval.\n\nBecause the companion is a tray-oriented app, closing the last transient webview must not implicitly terminate the process. The runtime intentionally prevents last-window destruction from exiting the app; explicit quit requests from the tray still exit normally.\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/App.tsx` | frontend view routing for idle, app picker, preferences, recovery, and large-file flows |\n| `companion/src/components/` | desktop-facing UI surfaces such as `AppPicker`, `DoneEditingWindow`, `RecoveryDialog`, and `Preferences` |\n| `companion/src/stores/` | persisted frontend preferences for app selection and companion settings |\n| `companion/src-tauri/src/lib.rs` | Tauri setup, plugin wiring, deep-link handling, window management, tray behavior, and lifecycle orchestration |\n| `companion/src-tauri/src/commands/` | commands for file info, download, upload, app selection, pairing, localization, and updates |\n| `companion/src-tauri/src/http_client.rs` | shared backend HTTP clients, reverse-proxy cookie jars, request diagnostics, and URL sanitization |\n| `companion/src-tauri/src/app_registry/` | platform-specific native-app discovery and launch integration |\n| `companion/src-tauri/src/sync/` | operation persistence, temp-file handling, recycle retention, and recovery helpers |\n| `companion/src-tauri/src/token/` and `uri/` | URI parsing and bootstrap-token exchange for deep-link editing |\n\n## Deep-Link Ingress\n\nNative-app editing starts from a `sambee://open?...` URI.\n\nThe runtime pieces involved are:\n\n- `tauri-plugin-deep-link` for receiving the URI\n- `tauri-plugin-single-instance` so later URIs are forwarded to the running instance instead of launching competing copies\n- `uri/mod.rs` for parsing required parameters such as `server`, `token`, `connId`, and `path`\n- `token/mod.rs` for exchanging the short-lived URI token for a companion bootstrap token\n\nThe deep link can also carry theme data so the companion UI matches the browser-side theme during the editing flow.\n\n## Reverse-Proxy Authentication Path\n\nNative editing supports reverse proxies and SSO layers that require interactive browser authentication before backend API requests are allowed through.\n\nThe implemented flow is:\n\n1. Companion tries the normal URI-token exchange.\n2. If token exchange is intercepted by a login redirect or HTML sign-in page, the companion opens a dedicated `Sambee Authentication` webview.\n3. The user signs in through that embedded webview.\n4. Companion reads backend-origin cookies from that same webview and seeds its shared Rust `reqwest` cookie jar.\n5. Token exchange and the rest of the native-edit lifecycle reuse that authenticated client state.\n\nThe HTTP client store is keyed by normalized server URL. For each server, it keeps a stable cookie jar plus default and no-redirect clients. The no-redirect client is used where redirect responses are diagnostic signals, such as URI-token exchange. The default client is reused for file-info lookup, lock acquisition, download, upload, lock release, and heartbeat requests.\n\nThis matters for the trust model:\n\n- Browser-to-companion localhost pairing remains separate from reverse-proxy authentication.\n- The Sambee bearer token remains separate from reverse-proxy cookies.\n- External browser cookies are not read or imported.\n- Reverse-proxy cookies stay inside the companion-owned webview and Rust HTTP client state.\n- Cookie values must not be logged.\n\nCompanion automatically retries idempotent backend calls such as file-info lookup, lock acquisition, download, lock release, and heartbeats after reauthentication. Non-idempotent uploads are not replayed automatically; the runtime instead asks the user to retry the action after authentication has been refreshed.\n\nFor reverse-proxy auth robustness, the shared Companion HTTP clients stay on HTTP/1.1 rather than enabling HTTP/2.\n\nRequest failures are logged with classified diagnostics such as timeout, connect, request, body, decode, and status. URLs and chained source errors are sanitized before logging so deep-link tokens, proxy sessions, and other sensitive query values do not appear in logs.\n\n## Native-App Edit Lifecycle\n\nThe implemented lifecycle in `lib.rs` is intentionally explicit.\n\nAt a high level it is:\n\n1. parse the deep link\n2. exchange the URI token for a companion bootstrap token\n3. fetch file metadata for file-size checks and conflict baseline\n4. optionally pause for a large-file confirmation dialog\n5. acquire the backend edit lock and receive operation-scoped lock context\n6. download the file into the companion temp area\n7. create a `FileOperation`, persist its sidecar, and add it to the in-memory store\n8. show the app picker and wait for user selection\n9. open the local file in the selected native application\n10. spawn a dedicated \"Done Editing\" window\n11. start background renewal, heartbeat, and file-status polling\n\nTwo rules matter here:\n\n- the backend lock is acquired before the edit session is allowed to proceed\n- the companion records local operation state before handing control to the native app\n\nThose decisions are what make recovery and conflict handling possible after crashes or interrupted sessions.\n\n## App Selection and Native Launching\n\nThe companion keeps platform-specific native-app discovery behind `app_registry/`.\n\nThat layer is responsible for:\n\n- listing handlers for a file extension\n- surfacing the default app first when possible\n- returning enough information for the UI to distinguish executable paths and handler identifiers\n- launching the chosen app or falling back to system-default open behavior when appropriate\n\nThe app picker flow is coordinated through Tauri events.\n\n- the Rust runtime emits `show-app-picker`\n- the frontend displays `AppPicker`\n- the user response is sent back through `respond_app_selection`\n\nStored per-extension app preferences live in `appPreferences.ts`, which is how repeated opens can bypass unnecessary picker friction.\n\nOn Windows, the launch path is more subtle than a simple `CreateProcess` call because packaged handlers and opaque shell associations may need Windows shell invocation rather than direct executable launching.\n\n## Operation Model, Temp Files, and Recovery\n\nDeep-link editing is tracked through `FileOperation` in `sync/operations.rs`.\n\nEach operation records:\n\n- server URL, connection, and remote path\n- local temp-file path\n- current status\n- original modification time\n- chosen app name\n- operation-scoped lock context and server-side last-modified baseline\n\nThe companion keeps this state in two places:\n\n- an in-memory `OperationStore` for active runtime coordination\n- a sidecar on disk so the session can be recovered after a restart or crash\n\nThat persistence model supports the recovery flow shown through `RecoveryDialog` when leftover operations are discovered at startup.\n\nThe temp-file lifecycle is also intentionally not just \"download and delete\":\n\n- active sessions live in a managed temp area\n- completed or discarded files move through recycle and retention logic\n- retention duration is user-configurable through preferences\n\n## \"Done Editing\" and Explicit Save-Back\n\nThe companion does not try to infer when a user is \"probably done\" in their native editor.\n\nInstead it keeps a dedicated \"Done Editing\" window open while:\n\n- file status polling checks whether the local temp file changed\n- renewal and heartbeat requests keep the edit session and backend lock alive\n\nWhen the user explicitly finishes or discards the session, the companion can:\n\n- upload the modified file\n- release the backend lock\n- recycle the temp copy\n- update the tray and operation state\n\nThat explicit-confirmation model is one of the core product decisions behind native-app editing, not a UI accident.\n\n## Conflict and Recovery Handling\n\nThe companion keeps enough state to detect overwrite-sensitive conflicts.\n\nBefore completing an upload-sensitive flow, it compares the current server-side state with the baseline captured earlier in the edit session. If those diverge, the conflict dialog path is used instead of silently overwriting the server copy.\n\nThis is also why recovery state is more than a cosmetic convenience feature. It protects the editing workflow from leaving users with stranded temp files and unclear lock state after interruption.\n\n## Preferences, Pairing UI, and Update Checks\n\nThe reused main window also hosts companion preferences.\n\nCurrent public settings include:\n\n- upload conflict behavior\n- auto-start at sign-in\n- desktop notifications\n- update channel selection\n- temp-file retention period\n- paired-origin management\n\nThe update path itself is channel-aware and lives in `commands/update.rs`, but detailed release-feed and packaging workflow belongs with companion distribution and update documentation rather than this runtime page.\n\nThe pairing window is a separate UI surface because browser-to-companion approval is part of the trust boundary, not just another generic settings dialog.\n\n## What Usually Breaks When This Layer Changes\n\n- deep links reach the app, but the running instance does not receive forwarded URIs correctly\n- lock acquisition or release gets out of sync with the visible edit lifecycle\n- picker cancellation or launch failure leaves behind stale temp files or sidecars\n- operation recovery loses enough metadata that interrupted edits become hard to resolve safely\n- tray and window state drift apart from the actual set of active operations\n\n## Where to Continue\n\n- Use [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) for pairing, localhost auth, deep-link trust boundaries, and origin scoping.\n- Use [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/) for the difference between local-drive access and SMB-backed save-back.\n- Use [Companion Release Overview](../../release-and-versioning/companion-release-overview/) when the change affects packaged releases or updater rollout rather than runtime behavior.\n\n## Validation Expectations\n\nWhen this runtime changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe frontend and backend checks matter whenever the companion change alters a shared workflow contract.\n", "0.9": "+++\ntitle = \"Companion Runtime and Native-App Editing\"\n+++\n\nThis page covers the companion runtime that sits between the browser's deep-link request and the desktop user's native editing session.\n\nUse it when a change affects:\n\n- deep-link handling and single-instance behavior\n- app selection and native-app launching\n- operation persistence, recovery, and temp-file lifecycle\n- tray, app-picker, large-file, and \"Done Editing\" window behavior\n\nFor localhost pairing and local-drive behavior, continue to [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) and [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\n## Runtime Modes and UI Surfaces\n\nThe companion is not a traditional always-visible desktop app.\n\nIn normal use it shifts between a few runtime modes:\n\n- tray-oriented background state when no editing dialog is open\n- a reused main window for app picker, preferences, large-file confirmation, and recovery dialogs\n- a dedicated pairing window for browser-to-companion approval\n- one \"Done Editing\" window per active native-app edit session\n\nThat split is deliberate. The companion should stay lightweight when idle, but it still needs focused UI surfaces for edit coordination and pairing approval.\n\nBecause the companion is a tray-oriented app, closing the last transient webview must not implicitly terminate the process. The runtime intentionally prevents last-window destruction from exiting the app; explicit quit requests from the tray still exit normally.\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/App.tsx` | frontend view routing for idle, app picker, preferences, recovery, and large-file flows |\n| `companion/src/components/` | desktop-facing UI surfaces such as `AppPicker`, `DoneEditingWindow`, `RecoveryDialog`, and `Preferences` |\n| `companion/src/stores/` | persisted frontend preferences for app selection and companion settings |\n| `companion/src-tauri/src/lib.rs` | Tauri setup, plugin wiring, deep-link handling, window management, tray behavior, and lifecycle orchestration |\n| `companion/src-tauri/src/commands/` | commands for file info, download, upload, app selection, pairing, localization, and updates |\n| `companion/src-tauri/src/http_client.rs` | shared backend HTTP clients, reverse-proxy cookie jars, request diagnostics, and URL sanitization |\n| `companion/src-tauri/src/app_registry/` | platform-specific native-app discovery and launch integration |\n| `companion/src-tauri/src/sync/` | operation persistence, temp-file handling, recycle retention, and recovery helpers |\n| `companion/src-tauri/src/token/` and `uri/` | URI parsing and bootstrap-token exchange for deep-link editing |\n\n## Deep-Link Ingress\n\nNative-app editing starts from a `sambee://open?...` URI.\n\nThe runtime pieces involved are:\n\n- `tauri-plugin-deep-link` for receiving the URI\n- `tauri-plugin-single-instance` so later URIs are forwarded to the running instance instead of launching competing copies\n- `uri/mod.rs` for parsing required parameters such as `server`, `token`, `connId`, and `path`\n- `token/mod.rs` for exchanging the short-lived URI token for a companion bootstrap token\n\nThe deep link can also carry theme data so the companion UI matches the browser-side theme during the editing flow.\n\n## Reverse-Proxy Authentication Path\n\nNative editing supports reverse proxies and SSO layers that require interactive browser authentication before backend API requests are allowed through.\n\nThe implemented flow is:\n\n1. Companion tries the normal URI-token exchange.\n2. If token exchange is intercepted by a login redirect or HTML sign-in page, the companion opens a dedicated `Sambee Authentication` webview.\n3. The user signs in through that embedded webview.\n4. Companion reads backend-origin cookies from that same webview and seeds its shared Rust `reqwest` cookie jar.\n5. Token exchange and the rest of the native-edit lifecycle reuse that authenticated client state.\n\nThe HTTP client store is keyed by normalized server URL. For each server, it keeps a stable cookie jar plus default and no-redirect clients. The no-redirect client is used where redirect responses are diagnostic signals, such as URI-token exchange. The default client is reused for file-info lookup, lock acquisition, download, upload, lock release, and heartbeat requests.\n\nThis matters for the trust model:\n\n- Browser-to-companion localhost pairing remains separate from reverse-proxy authentication.\n- The Sambee bearer token remains separate from reverse-proxy cookies.\n- External browser cookies are not read or imported.\n- Reverse-proxy cookies stay inside the companion-owned webview and Rust HTTP client state.\n- Cookie values must not be logged.\n\nCompanion automatically retries idempotent backend calls such as file-info lookup, lock acquisition, download, lock release, and heartbeats after reauthentication. Non-idempotent uploads are not replayed automatically; the runtime instead asks the user to retry the action after authentication has been refreshed.\n\nFor reverse-proxy auth robustness, the shared Companion HTTP clients stay on HTTP/1.1 rather than enabling HTTP/2.\n\nRequest failures are logged with classified diagnostics such as timeout, connect, request, body, decode, and status. URLs and chained source errors are sanitized before logging so deep-link tokens, proxy sessions, and other sensitive query values do not appear in logs.\n\n## Native-App Edit Lifecycle\n\nThe implemented lifecycle in `lib.rs` is intentionally explicit.\n\nAt a high level it is:\n\n1. parse the deep link\n2. exchange the URI token for a companion bootstrap token\n3. fetch file metadata for file-size checks and conflict baseline\n4. optionally pause for a large-file confirmation dialog\n5. acquire the backend edit lock and receive operation-scoped lock context\n6. download the file into the companion temp area\n7. create a `FileOperation`, persist its sidecar, and add it to the in-memory store\n8. show the app picker and wait for user selection\n9. open the local file in the selected native application\n10. spawn a dedicated \"Done Editing\" window\n11. start background renewal, heartbeat, and file-status polling\n\nTwo rules matter here:\n\n- the backend lock is acquired before the edit session is allowed to proceed\n- the companion records local operation state before handing control to the native app\n\nThose decisions are what make recovery and conflict handling possible after crashes or interrupted sessions.\n\n## App Selection and Native Launching\n\nThe companion keeps platform-specific native-app discovery behind `app_registry/`.\n\nThat layer is responsible for:\n\n- listing handlers for a file extension\n- surfacing the default app first when possible\n- returning enough information for the UI to distinguish executable paths and handler identifiers\n- launching the chosen app or falling back to system-default open behavior when appropriate\n\nThe app picker flow is coordinated through Tauri events.\n\n- the Rust runtime emits `show-app-picker`\n- the frontend displays `AppPicker`\n- the user response is sent back through `respond_app_selection`\n\nStored per-extension app preferences live in `appPreferences.ts`, which is how repeated opens can bypass unnecessary picker friction.\n\nOn Windows, the launch path is more subtle than a simple `CreateProcess` call because packaged handlers and opaque shell associations may need Windows shell invocation rather than direct executable launching.\n\n## Operation Model, Temp Files, and Recovery\n\nDeep-link editing is tracked through `FileOperation` in `sync/operations.rs`.\n\nEach operation records:\n\n- server URL, connection, and remote path\n- local temp-file path\n- current status\n- original modification time\n- chosen app name\n- operation-scoped lock context and server-side last-modified baseline\n\nThe companion keeps this state in two places:\n\n- an in-memory `OperationStore` for active runtime coordination\n- a sidecar on disk so the session can be recovered after a restart or crash\n\nThat persistence model supports the recovery flow shown through `RecoveryDialog` when leftover operations are discovered at startup.\n\nThe temp-file lifecycle is also intentionally not just \"download and delete\":\n\n- active sessions live in a managed temp area\n- completed or discarded files move through recycle and retention logic\n- retention duration is user-configurable through preferences\n\n## \"Done Editing\" and Explicit Save-Back\n\nThe companion does not try to infer when a user is \"probably done\" in their native editor.\n\nInstead it keeps a dedicated \"Done Editing\" window open while:\n\n- file status polling checks whether the local temp file changed\n- renewal and heartbeat requests keep the edit session and backend lock alive\n\nWhen the user explicitly finishes or discards the session, the companion can:\n\n- upload the modified file\n- release the backend lock\n- recycle the temp copy\n- update the tray and operation state\n\nThat explicit-confirmation model is one of the core product decisions behind native-app editing, not a UI accident.\n\n## Conflict and Recovery Handling\n\nThe companion keeps enough state to detect overwrite-sensitive conflicts.\n\nBefore completing an upload-sensitive flow, it compares the current server-side state with the baseline captured earlier in the edit session. If those diverge, the conflict dialog path is used instead of silently overwriting the server copy.\n\nThis is also why recovery state is more than a cosmetic convenience feature. It protects the editing workflow from leaving users with stranded temp files and unclear lock state after interruption.\n\n## Preferences, Pairing UI, and Update Checks\n\nThe reused main window also hosts companion preferences.\n\nCurrent public settings include:\n\n- upload conflict behavior\n- auto-start at sign-in\n- desktop notifications\n- update channel selection\n- temp-file retention period\n- paired-origin management\n\nThe update path itself is channel-aware and lives in `commands/update.rs`, but detailed release-feed and packaging workflow belongs with companion distribution and update documentation rather than this runtime page.\n\nThe pairing window is a separate UI surface because browser-to-companion approval is part of the trust boundary, not just another generic settings dialog.\n\n## What Usually Breaks When This Layer Changes\n\n- deep links reach the app, but the running instance does not receive forwarded URIs correctly\n- lock acquisition or release gets out of sync with the visible edit lifecycle\n- picker cancellation or launch failure leaves behind stale temp files or sidecars\n- operation recovery loses enough metadata that interrupted edits become hard to resolve safely\n- tray and window state drift apart from the actual set of active operations\n\n## Where to Continue\n\n- Use [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) for pairing, localhost auth, deep-link trust boundaries, and origin scoping.\n- Use [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/) for the difference between local-drive access and SMB-backed save-back.\n- Use [Companion Release Overview](../../release-and-versioning/companion-release-overview/) when the change affects packaged releases or updater rollout rather than runtime behavior.\n\n## Validation Expectations\n\nWhen this runtime changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe frontend and backend checks matter whenever the companion change alters a shared workflow contract.\n", "1.0": "+++\ntitle = \"Companion Runtime and Native-App Editing\"\n+++\n\nThis page covers the companion runtime that sits between the browser's deep-link request and the desktop user's native editing session.\n\nUse it when a change affects:\n\n- deep-link handling and single-instance behavior\n- app selection and native-app launching\n- operation persistence, recovery, and temp-file lifecycle\n- tray, app-picker, large-file, and \"Done Editing\" window behavior\n\nFor localhost pairing and local-drive behavior, continue to [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) and [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\n## Runtime Modes and UI Surfaces\n\nThe companion is not a traditional always-visible desktop app.\n\nIn normal use it shifts between a few runtime modes:\n\n- tray-oriented background state when no editing dialog is open\n- a reused main window for app picker, preferences, large-file confirmation, and recovery dialogs\n- a dedicated pairing window for browser-to-companion approval\n- one \"Done Editing\" window per active native-app edit session\n\nThat split is deliberate. The companion should stay lightweight when idle, but it still needs focused UI surfaces for edit coordination and pairing approval.\n\nBecause the companion is a tray-oriented app, closing the last transient webview must not implicitly terminate the process. The runtime intentionally prevents last-window destruction from exiting the app; explicit quit requests from the tray still exit normally.\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/App.tsx` | frontend view routing for idle, app picker, preferences, recovery, and large-file flows |\n| `companion/src/components/` | desktop-facing UI surfaces such as `AppPicker`, `DoneEditingWindow`, `RecoveryDialog`, and `Preferences` |\n| `companion/src/stores/` | persisted frontend preferences for app selection and companion settings |\n| `companion/src-tauri/src/lib.rs` | Tauri setup, plugin wiring, deep-link handling, window management, tray behavior, and lifecycle orchestration |\n| `companion/src-tauri/src/commands/` | commands for file info, download, upload, app selection, pairing, localization, and updates |\n| `companion/src-tauri/src/http_client.rs` | shared backend HTTP clients, reverse-proxy cookie jars, request diagnostics, and URL sanitization |\n| `companion/src-tauri/src/app_registry/` | platform-specific native-app discovery and launch integration |\n| `companion/src-tauri/src/sync/` | operation persistence, temp-file handling, recycle retention, and recovery helpers |\n| `companion/src-tauri/src/token/` and `uri/` | URI parsing and bootstrap-token exchange for deep-link editing |\n\n## Deep-Link Ingress\n\nNative-app editing starts from a `sambee://open?...` URI.\n\nThe runtime pieces involved are:\n\n- `tauri-plugin-deep-link` for receiving the URI\n- `tauri-plugin-single-instance` so later URIs are forwarded to the running instance instead of launching competing copies\n- `uri/mod.rs` for parsing required parameters such as `server`, `token`, `connId`, and `path`\n- `token/mod.rs` for exchanging the short-lived URI token for a companion bootstrap token\n\nThe deep link can also carry theme data so the companion UI matches the browser-side theme during the editing flow.\n\n## Reverse-Proxy Authentication Path\n\nNative editing supports reverse proxies and SSO layers that require interactive browser authentication before backend API requests are allowed through.\n\nThe implemented flow is:\n\n1. Companion tries the normal URI-token exchange.\n2. If token exchange is intercepted by a login redirect or HTML sign-in page, the companion opens a dedicated `Sambee Authentication` webview.\n3. The user signs in through that embedded webview.\n4. Companion reads backend-origin cookies from that same webview and seeds its shared Rust `reqwest` cookie jar.\n5. Token exchange and the rest of the native-edit lifecycle reuse that authenticated client state.\n\nThe HTTP client store is keyed by normalized server URL. For each server, it keeps a stable cookie jar plus default and no-redirect clients. The no-redirect client is used where redirect responses are diagnostic signals, such as URI-token exchange. The default client is reused for file-info lookup, lock acquisition, download, upload, lock release, and heartbeat requests.\n\nThis matters for the trust model:\n\n- Browser-to-companion localhost pairing remains separate from reverse-proxy authentication.\n- The Sambee bearer token remains separate from reverse-proxy cookies.\n- External browser cookies are not read or imported.\n- Reverse-proxy cookies stay inside the companion-owned webview and Rust HTTP client state.\n- Cookie values must not be logged.\n\nCompanion automatically retries idempotent backend calls such as file-info lookup, lock acquisition, download, lock release, and heartbeats after reauthentication. Non-idempotent uploads are not replayed automatically; the runtime instead asks the user to retry the action after authentication has been refreshed.\n\nFor reverse-proxy auth robustness, the shared Companion HTTP clients stay on HTTP/1.1 rather than enabling HTTP/2.\n\nRequest failures are logged with classified diagnostics such as timeout, connect, request, body, decode, and status. URLs and chained source errors are sanitized before logging so deep-link tokens, proxy sessions, and other sensitive query values do not appear in logs.\n\n## Native-App Edit Lifecycle\n\nThe implemented lifecycle in `lib.rs` is intentionally explicit.\n\nAt a high level it is:\n\n1. parse the deep link\n2. exchange the URI token for a companion bootstrap token\n3. fetch file metadata for file-size checks and conflict baseline\n4. optionally pause for a large-file confirmation dialog\n5. acquire the backend edit lock and receive operation-scoped lock context\n6. download the file into the companion temp area\n7. create a `FileOperation`, persist its sidecar, and add it to the in-memory store\n8. show the app picker and wait for user selection\n9. open the local file in the selected native application\n10. spawn a dedicated \"Done Editing\" window\n11. start background renewal, heartbeat, and file-status polling\n\nTwo rules matter here:\n\n- the backend lock is acquired before the edit session is allowed to proceed\n- the companion records local operation state before handing control to the native app\n\nThose decisions are what make recovery and conflict handling possible after crashes or interrupted sessions.\n\n## App Selection and Native Launching\n\nThe companion keeps platform-specific native-app discovery behind `app_registry/`.\n\nThat layer is responsible for:\n\n- listing handlers for a file extension\n- surfacing the default app first when possible\n- returning enough information for the UI to distinguish executable paths and handler identifiers\n- launching the chosen app or falling back to system-default open behavior when appropriate\n\nThe app picker flow is coordinated through Tauri events.\n\n- the Rust runtime emits `show-app-picker`\n- the frontend displays `AppPicker`\n- the user response is sent back through `respond_app_selection`\n\nStored per-extension app preferences live in `appPreferences.ts`, which is how repeated opens can bypass unnecessary picker friction.\n\nOn Windows, the launch path is more subtle than a simple `CreateProcess` call because packaged handlers and opaque shell associations may need Windows shell invocation rather than direct executable launching.\n\n## Operation Model, Temp Files, and Recovery\n\nDeep-link editing is tracked through `FileOperation` in `sync/operations.rs`.\n\nEach operation records:\n\n- server URL, connection, and remote path\n- local temp-file path\n- current status\n- original modification time\n- chosen app name\n- operation-scoped lock context and server-side last-modified baseline\n\nThe companion keeps this state in two places:\n\n- an in-memory `OperationStore` for active runtime coordination\n- a sidecar on disk so the session can be recovered after a restart or crash\n\nThat persistence model supports the recovery flow shown through `RecoveryDialog` when leftover operations are discovered at startup.\n\nThe temp-file lifecycle is also intentionally not just \"download and delete\":\n\n- active sessions live in a managed temp area\n- completed or discarded files move through recycle and retention logic\n- retention duration is user-configurable through preferences\n\n## \"Done Editing\" and Explicit Save-Back\n\nThe companion does not try to infer when a user is \"probably done\" in their native editor.\n\nInstead it keeps a dedicated \"Done Editing\" window open while:\n\n- file status polling checks whether the local temp file changed\n- renewal and heartbeat requests keep the edit session and backend lock alive\n\nWhen the user explicitly finishes or discards the session, the companion can:\n\n- upload the modified file\n- release the backend lock\n- recycle the temp copy\n- update the tray and operation state\n\nThat explicit-confirmation model is one of the core product decisions behind native-app editing, not a UI accident.\n\n## Conflict and Recovery Handling\n\nThe companion keeps enough state to detect overwrite-sensitive conflicts.\n\nBefore completing an upload-sensitive flow, it compares the current server-side state with the baseline captured earlier in the edit session. If those diverge, the conflict dialog path is used instead of silently overwriting the server copy.\n\nThis is also why recovery state is more than a cosmetic convenience feature. It protects the editing workflow from leaving users with stranded temp files and unclear lock state after interruption.\n\n## Preferences, Pairing UI, and Update Checks\n\nThe reused main window also hosts companion preferences.\n\nCurrent public settings include:\n\n- upload conflict behavior\n- auto-start at sign-in\n- desktop notifications\n- update channel selection\n- temp-file retention period\n- paired-origin management\n\nThe update path itself is channel-aware and lives in `commands/update.rs`, but detailed release-feed and packaging workflow belongs with companion distribution and update documentation rather than this runtime page.\n\nThe pairing window is a separate UI surface because browser-to-companion approval is part of the trust boundary, not just another generic settings dialog.\n\n## What Usually Breaks When This Layer Changes\n\n- deep links reach the app, but the running instance does not receive forwarded URIs correctly\n- lock acquisition or release gets out of sync with the visible edit lifecycle\n- picker cancellation or launch failure leaves behind stale temp files or sidecars\n- operation recovery loses enough metadata that interrupted edits become hard to resolve safely\n- tray and window state drift apart from the actual set of active operations\n\n## Where to Continue\n\n- Use [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) for pairing, localhost auth, deep-link trust boundaries, and origin scoping.\n- Use [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/) for the difference between local-drive access and SMB-backed save-back.\n- Use [Companion Release Overview](../../release-and-versioning/companion-release-overview/) when the change affects packaged releases or updater rollout rather than runtime behavior.\n\n## Validation Expectations\n\nWhen this runtime changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe frontend and backend checks matter whenever the companion change alters a shared workflow contract.\n", "2.0": "+++\ntitle = \"Companion Runtime and Native-App Editing\"\n+++\n\nThis page covers the companion runtime that sits between the browser's deep-link request and the desktop user's native editing session.\n\nUse it when a change affects:\n\n- deep-link handling and single-instance behavior\n- app selection and native-app launching\n- operation persistence, recovery, and temp-file lifecycle\n- tray, app-picker, large-file, and \"Done Editing\" window behavior\n\nFor localhost pairing and local-drive behavior, continue to [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) and [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\n## Runtime Modes and UI Surfaces\n\nThe companion is not a traditional always-visible desktop app.\n\nIn normal use it shifts between a few runtime modes:\n\n- tray-oriented background state when no editing dialog is open\n- a reused main window for app picker, preferences, large-file confirmation, and recovery dialogs\n- a dedicated pairing window for browser-to-companion approval\n- one \"Done Editing\" window per active native-app edit session\n\nThat split is deliberate. The companion should stay lightweight when idle, but it still needs focused UI surfaces for edit coordination and pairing approval.\n\nBecause the companion is a tray-oriented app, closing the last transient webview must not implicitly terminate the process. The runtime intentionally prevents last-window destruction from exiting the app; explicit quit requests from the tray still exit normally.\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/App.tsx` | frontend view routing for idle, app picker, preferences, recovery, and large-file flows |\n| `companion/src/components/` | desktop-facing UI surfaces such as `AppPicker`, `DoneEditingWindow`, `RecoveryDialog`, and `Preferences` |\n| `companion/src/stores/` | persisted frontend preferences for app selection and companion settings |\n| `companion/src-tauri/src/lib.rs` | Tauri setup, plugin wiring, deep-link handling, window management, tray behavior, and lifecycle orchestration |\n| `companion/src-tauri/src/commands/` | commands for file info, download, upload, app selection, pairing, localization, and updates |\n| `companion/src-tauri/src/http_client.rs` | shared backend HTTP clients, reverse-proxy cookie jars, request diagnostics, and URL sanitization |\n| `companion/src-tauri/src/app_registry/` | platform-specific native-app discovery and launch integration |\n| `companion/src-tauri/src/sync/` | operation persistence, temp-file handling, recycle retention, and recovery helpers |\n| `companion/src-tauri/src/token/` and `uri/` | URI parsing and bootstrap-token exchange for deep-link editing |\n\n## Deep-Link Ingress\n\nNative-app editing starts from a `sambee://open?...` URI.\n\nThe runtime pieces involved are:\n\n- `tauri-plugin-deep-link` for receiving the URI\n- `tauri-plugin-single-instance` so later URIs are forwarded to the running instance instead of launching competing copies\n- `uri/mod.rs` for parsing required parameters such as `server`, `token`, `connId`, and `path`\n- `token/mod.rs` for exchanging the short-lived URI token for a companion bootstrap token\n\nThe deep link can also carry theme data so the companion UI matches the browser-side theme during the editing flow.\n\n## Reverse-Proxy Authentication Path\n\nNative editing supports reverse proxies and SSO layers that require interactive browser authentication before backend API requests are allowed through.\n\nThe implemented flow is:\n\n1. Companion tries the normal URI-token exchange.\n2. If token exchange is intercepted by a login redirect or HTML sign-in page, the companion opens a dedicated `Sambee Authentication` webview.\n3. The user signs in through that embedded webview.\n4. Companion reads backend-origin cookies from that same webview and seeds its shared Rust `reqwest` cookie jar.\n5. Token exchange and the rest of the native-edit lifecycle reuse that authenticated client state.\n\nThe HTTP client store is keyed by normalized server URL. For each server, it keeps a stable cookie jar plus default and no-redirect clients. The no-redirect client is used where redirect responses are diagnostic signals, such as URI-token exchange. The default client is reused for file-info lookup, lock acquisition, download, upload, lock release, and heartbeat requests.\n\nThis matters for the trust model:\n\n- Browser-to-companion localhost pairing remains separate from reverse-proxy authentication.\n- The Sambee bearer token remains separate from reverse-proxy cookies.\n- External browser cookies are not read or imported.\n- Reverse-proxy cookies stay inside the companion-owned webview and Rust HTTP client state.\n- Cookie values must not be logged.\n\nCompanion automatically retries idempotent backend calls such as file-info lookup, lock acquisition, download, lock release, and heartbeats after reauthentication. Non-idempotent uploads are not replayed automatically; the runtime instead asks the user to retry the action after authentication has been refreshed.\n\nFor reverse-proxy auth robustness, the shared Companion HTTP clients stay on HTTP/1.1 rather than enabling HTTP/2.\n\nRequest failures are logged with classified diagnostics such as timeout, connect, request, body, decode, and status. URLs and chained source errors are sanitized before logging so deep-link tokens, proxy sessions, and other sensitive query values do not appear in logs.\n\n## Native-App Edit Lifecycle\n\nThe implemented lifecycle in `lib.rs` is intentionally explicit.\n\nAt a high level it is:\n\n1. parse the deep link\n2. exchange the URI token for a companion bootstrap token\n3. fetch file metadata for file-size checks and conflict baseline\n4. optionally pause for a large-file confirmation dialog\n5. acquire the backend edit lock and receive operation-scoped lock context\n6. download the file into the companion temp area\n7. create a `FileOperation`, persist its sidecar, and add it to the in-memory store\n8. show the app picker and wait for user selection\n9. open the local file in the selected native application\n10. spawn a dedicated \"Done Editing\" window\n11. start background renewal, heartbeat, and file-status polling\n\nTwo rules matter here:\n\n- the backend lock is acquired before the edit session is allowed to proceed\n- the companion records local operation state before handing control to the native app\n\nThose decisions are what make recovery and conflict handling possible after crashes or interrupted sessions.\n\n## App Selection and Native Launching\n\nThe companion keeps platform-specific native-app discovery behind `app_registry/`.\n\nThat layer is responsible for:\n\n- listing handlers for a file extension\n- surfacing the default app first when possible\n- returning enough information for the UI to distinguish executable paths and handler identifiers\n- launching the chosen app or falling back to system-default open behavior when appropriate\n\nThe app picker flow is coordinated through Tauri events.\n\n- the Rust runtime emits `show-app-picker`\n- the frontend displays `AppPicker`\n- the user response is sent back through `respond_app_selection`\n\nStored per-extension app preferences live in `appPreferences.ts`, which is how repeated opens can bypass unnecessary picker friction.\n\nOn Windows, the launch path is more subtle than a simple `CreateProcess` call because packaged handlers and opaque shell associations may need Windows shell invocation rather than direct executable launching.\n\n## Operation Model, Temp Files, and Recovery\n\nDeep-link editing is tracked through `FileOperation` in `sync/operations.rs`.\n\nEach operation records:\n\n- server URL, connection, and remote path\n- local temp-file path\n- current status\n- original modification time\n- chosen app name\n- operation-scoped lock context and server-side last-modified baseline\n\nThe companion keeps this state in two places:\n\n- an in-memory `OperationStore` for active runtime coordination\n- a sidecar on disk so the session can be recovered after a restart or crash\n\nThat persistence model supports the recovery flow shown through `RecoveryDialog` when leftover operations are discovered at startup.\n\nThe temp-file lifecycle is also intentionally not just \"download and delete\":\n\n- active sessions live in a managed temp area\n- completed or discarded files move through recycle and retention logic\n- retention duration is user-configurable through preferences\n\n## \"Done Editing\" and Explicit Save-Back\n\nThe companion does not try to infer when a user is \"probably done\" in their native editor.\n\nInstead it keeps a dedicated \"Done Editing\" window open while:\n\n- file status polling checks whether the local temp file changed\n- renewal and heartbeat requests keep the edit session and backend lock alive\n\nWhen the user explicitly finishes or discards the session, the companion can:\n\n- upload the modified file\n- release the backend lock\n- recycle the temp copy\n- update the tray and operation state\n\nThat explicit-confirmation model is one of the core product decisions behind native-app editing, not a UI accident.\n\n## Conflict and Recovery Handling\n\nThe companion keeps enough state to detect overwrite-sensitive conflicts.\n\nBefore completing an upload-sensitive flow, it compares the current server-side state with the baseline captured earlier in the edit session. If those diverge, the conflict dialog path is used instead of silently overwriting the server copy.\n\nThis is also why recovery state is more than a cosmetic convenience feature. It protects the editing workflow from leaving users with stranded temp files and unclear lock state after interruption.\n\n## Preferences, Pairing UI, and Update Checks\n\nThe reused main window also hosts companion preferences.\n\nCurrent public settings include:\n\n- upload conflict behavior\n- auto-start at sign-in\n- desktop notifications\n- update channel selection\n- temp-file retention period\n- paired-origin management\n\nThe update path itself is channel-aware and lives in `commands/update.rs`, but detailed release-feed and packaging workflow belongs with companion distribution and update documentation rather than this runtime page.\n\nThe pairing window is a separate UI surface because browser-to-companion approval is part of the trust boundary, not just another generic settings dialog.\n\n## What Usually Breaks When This Layer Changes\n\n- deep links reach the app, but the running instance does not receive forwarded URIs correctly\n- lock acquisition or release gets out of sync with the visible edit lifecycle\n- picker cancellation or launch failure leaves behind stale temp files or sidecars\n- operation recovery loses enough metadata that interrupted edits become hard to resolve safely\n- tray and window state drift apart from the actual set of active operations\n\n## Where to Continue\n\n- Use [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) for pairing, localhost auth, deep-link trust boundaries, and origin scoping.\n- Use [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/) for the difference between local-drive access and SMB-backed save-back.\n- Use [Companion Release Overview](../../release-and-versioning/companion-release-overview/) when the change affects packaged releases or updater rollout rather than runtime behavior.\n\n## Validation Expectations\n\nWhen this runtime changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe frontend and backend checks matter whenever the companion change alters a shared workflow contract.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Companion Runtime and Native-App Editing\"\n+++\n\nThis page covers the companion runtime that sits between the browser's deep-link request and the desktop user's native editing session.\n\nUse it when a change affects:\n\n- deep-link handling and single-instance behavior\n- app selection and native-app launching\n- operation persistence, recovery, and temp-file lifecycle\n- tray, app-picker, large-file, and \"Done Editing\" window behavior\n\nFor localhost pairing and local-drive behavior, continue to [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) and [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\n## Runtime Modes and UI Surfaces\n\nThe companion is not a traditional always-visible desktop app.\n\nIn normal use it shifts between a few runtime modes:\n\n- tray-oriented background state when no editing dialog is open\n- a reused main window for app picker, preferences, large-file confirmation, and recovery dialogs\n- a dedicated pairing window for browser-to-companion approval\n- one \"Done Editing\" window per active native-app edit session\n\nThat split is deliberate. The companion should stay lightweight when idle, but it still needs focused UI surfaces for edit coordination and pairing approval.\n\nBecause the companion is a tray-oriented app, closing the last transient webview must not implicitly terminate the process. The runtime intentionally prevents last-window destruction from exiting the app; explicit quit requests from the tray still exit normally.\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/App.tsx` | frontend view routing for idle, app picker, preferences, recovery, and large-file flows |\n| `companion/src/components/` | desktop-facing UI surfaces such as `AppPicker`, `DoneEditingWindow`, `RecoveryDialog`, and `Preferences` |\n| `companion/src/stores/` | persisted frontend preferences for app selection and companion settings |\n| `companion/src-tauri/src/lib.rs` | Tauri setup, plugin wiring, deep-link handling, window management, tray behavior, and lifecycle orchestration |\n| `companion/src-tauri/src/commands/` | commands for file info, download, upload, app selection, pairing, localization, and updates |\n| `companion/src-tauri/src/http_client.rs` | shared backend HTTP clients, reverse-proxy cookie jars, request diagnostics, and URL sanitization |\n| `companion/src-tauri/src/app_registry/` | platform-specific native-app discovery and launch integration |\n| `companion/src-tauri/src/sync/` | operation persistence, temp-file handling, recycle retention, and recovery helpers |\n| `companion/src-tauri/src/token/` and `uri/` | URI parsing and bootstrap-token exchange for deep-link editing |\n\n## Deep-Link Ingress\n\nNative-app editing starts from a `sambee://open?...` URI.\n\nThe runtime pieces involved are:\n\n- `tauri-plugin-deep-link` for receiving the URI\n- `tauri-plugin-single-instance` so later URIs are forwarded to the running instance instead of launching competing copies\n- `uri/mod.rs` for parsing required parameters such as `server`, `token`, `connId`, and `path`\n- `token/mod.rs` for exchanging the short-lived URI token for a companion bootstrap token\n\nThe deep link can also carry theme data so the companion UI matches the browser-side theme during the editing flow.\n\n## Reverse-Proxy Authentication Path\n\nNative editing supports reverse proxies and SSO layers that require interactive browser authentication before backend API requests are allowed through.\n\nThe implemented flow is:\n\n1. Companion tries the normal URI-token exchange.\n2. If token exchange is intercepted by a login redirect or HTML sign-in page, the companion opens a dedicated `Sambee Authentication` webview.\n3. The user signs in through that embedded webview.\n4. Companion reads backend-origin cookies from that same webview and seeds its shared Rust `reqwest` cookie jar.\n5. Token exchange and the rest of the native-edit lifecycle reuse that authenticated client state.\n\nThe HTTP client store is keyed by normalized server URL. For each server, it keeps a stable cookie jar plus default and no-redirect clients. The no-redirect client is used where redirect responses are diagnostic signals, such as URI-token exchange. The default client is reused for file-info lookup, lock acquisition, download, upload, lock release, and heartbeat requests.\n\nThis matters for the trust model:\n\n- Browser-to-companion localhost pairing remains separate from reverse-proxy authentication.\n- The Sambee bearer token remains separate from reverse-proxy cookies.\n- External browser cookies are not read or imported.\n- Reverse-proxy cookies stay inside the companion-owned webview and Rust HTTP client state.\n- Cookie values must not be logged.\n\nCompanion automatically retries idempotent backend calls such as file-info lookup, lock acquisition, download, lock release, and heartbeats after reauthentication. Non-idempotent uploads are not replayed automatically; the runtime instead asks the user to retry the action after authentication has been refreshed.\n\nFor reverse-proxy auth robustness, the shared Companion HTTP clients stay on HTTP/1.1 rather than enabling HTTP/2.\n\nRequest failures are logged with classified diagnostics such as timeout, connect, request, body, decode, and status. URLs and chained source errors are sanitized before logging so deep-link tokens, proxy sessions, and other sensitive query values do not appear in logs.\n\n## Native-App Edit Lifecycle\n\nThe implemented lifecycle in `lib.rs` is intentionally explicit.\n\nAt a high level it is:\n\n1. parse the deep link\n2. exchange the URI token for a companion bootstrap token\n3. fetch file metadata for file-size checks and conflict baseline\n4. optionally pause for a large-file confirmation dialog\n5. acquire the backend edit lock and receive operation-scoped lock context\n6. download the file into the companion temp area\n7. create a `FileOperation`, persist its sidecar, and add it to the in-memory store\n8. show the app picker and wait for user selection\n9. open the local file in the selected native application\n10. spawn a dedicated \"Done Editing\" window\n11. start background renewal, heartbeat, and file-status polling\n\nTwo rules matter here:\n\n- the backend lock is acquired before the edit session is allowed to proceed\n- the companion records local operation state before handing control to the native app\n\nThose decisions are what make recovery and conflict handling possible after crashes or interrupted sessions.\n\n## App Selection and Native Launching\n\nThe companion keeps platform-specific native-app discovery behind `app_registry/`.\n\nThat layer is responsible for:\n\n- listing handlers for a file extension\n- surfacing the default app first when possible\n- returning enough information for the UI to distinguish executable paths and handler identifiers\n- launching the chosen app or falling back to system-default open behavior when appropriate\n\nThe app picker flow is coordinated through Tauri events.\n\n- the Rust runtime emits `show-app-picker`\n- the frontend displays `AppPicker`\n- the user response is sent back through `respond_app_selection`\n\nStored per-extension app preferences live in `appPreferences.ts`, which is how repeated opens can bypass unnecessary picker friction.\n\nOn Windows, the launch path is more subtle than a simple `CreateProcess` call because packaged handlers and opaque shell associations may need Windows shell invocation rather than direct executable launching.\n\n## Operation Model, Temp Files, and Recovery\n\nDeep-link editing is tracked through `FileOperation` in `sync/operations.rs`.\n\nEach operation records:\n\n- server URL, connection, and remote path\n- local temp-file path\n- current status\n- original modification time\n- chosen app name\n- operation-scoped lock context and server-side last-modified baseline\n\nThe companion keeps this state in two places:\n\n- an in-memory `OperationStore` for active runtime coordination\n- a sidecar on disk so the session can be recovered after a restart or crash\n\nThat persistence model supports the recovery flow shown through `RecoveryDialog` when leftover operations are discovered at startup.\n\nThe temp-file lifecycle is also intentionally not just \"download and delete\":\n\n- active sessions live in a managed temp area\n- completed or discarded files move through recycle and retention logic\n- retention duration is user-configurable through preferences\n\n## \"Done Editing\" and Explicit Save-Back\n\nThe companion does not try to infer when a user is \"probably done\" in their native editor.\n\nInstead it keeps a dedicated \"Done Editing\" window open while:\n\n- file status polling checks whether the local temp file changed\n- renewal and heartbeat requests keep the edit session and backend lock alive\n\nWhen the user explicitly finishes or discards the session, the companion can:\n\n- upload the modified file\n- release the backend lock\n- recycle the temp copy\n- update the tray and operation state\n\nThat explicit-confirmation model is one of the core product decisions behind native-app editing, not a UI accident.\n\n## Conflict and Recovery Handling\n\nThe companion keeps enough state to detect overwrite-sensitive conflicts.\n\nBefore completing an upload-sensitive flow, it compares the current server-side state with the baseline captured earlier in the edit session. If those diverge, the conflict dialog path is used instead of silently overwriting the server copy.\n\nThis is also why recovery state is more than a cosmetic convenience feature. It protects the editing workflow from leaving users with stranded temp files and unclear lock state after interruption.\n\n## Preferences, Pairing UI, and Update Checks\n\nThe reused main window also hosts companion preferences.\n\nCurrent public settings include:\n\n- upload conflict behavior\n- auto-start at sign-in\n- desktop notifications\n- update channel selection\n- temp-file retention period\n- paired-origin management\n\nThe update path itself is channel-aware and lives in `commands/update.rs`, but detailed release-feed and packaging workflow belongs with companion distribution and update documentation rather than this runtime page.\n\nThe pairing window is a separate UI surface because browser-to-companion approval is part of the trust boundary, not just another generic settings dialog.\n\n## What Usually Breaks When This Layer Changes\n\n- deep links reach the app, but the running instance does not receive forwarded URIs correctly\n- lock acquisition or release gets out of sync with the visible edit lifecycle\n- picker cancellation or launch failure leaves behind stale temp files or sidecars\n- operation recovery loses enough metadata that interrupted edits become hard to resolve safely\n- tray and window state drift apart from the actual set of active operations\n\n## Where to Continue\n\n- Use [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) for pairing, localhost auth, deep-link trust boundaries, and origin scoping.\n- Use [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/) for the difference between local-drive access and SMB-backed save-back.\n- Use [Companion Release Overview](../../release-and-versioning/companion-release-overview/) when the change affects packaged releases or updater rollout rather than runtime behavior.\n\n## Validation Expectations\n\nWhen this runtime changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe frontend and backend checks matter whenever the companion change alters a shared workflow contract.\n", "0.8": "+++\ntitle = \"Companion Runtime and Native-App Editing\"\n+++\n\nThis page covers the companion runtime that sits between the browser's deep-link request and the desktop user's native editing session.\n\nUse it when a change affects:\n\n- deep-link handling and single-instance behavior\n- app selection and native-app launching\n- operation persistence, recovery, and temp-file lifecycle\n- tray, app-picker, large-file, and \"Done Editing\" window behavior\n\nFor localhost pairing and local-drive behavior, continue to [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) and [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\n## Runtime Modes and UI Surfaces\n\nThe companion is not a traditional always-visible desktop app.\n\nIn normal use it shifts between a few runtime modes:\n\n- tray-oriented background state when no editing dialog is open\n- a reused main window for app picker, preferences, large-file confirmation, and recovery dialogs\n- a dedicated pairing window for browser-to-companion approval\n- one \"Done Editing\" window per active native-app edit session\n\nThat split is deliberate. The companion should stay lightweight when idle, but it still needs focused UI surfaces for edit coordination and pairing approval.\n\nBecause the companion is a tray-oriented app, closing the last transient webview must not implicitly terminate the process. The runtime intentionally prevents last-window destruction from exiting the app; explicit quit requests from the tray still exit normally.\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/App.tsx` | frontend view routing for idle, app picker, preferences, recovery, and large-file flows |\n| `companion/src/components/` | desktop-facing UI surfaces such as `AppPicker`, `DoneEditingWindow`, `RecoveryDialog`, and `Preferences` |\n| `companion/src/stores/` | persisted frontend preferences for app selection and companion settings |\n| `companion/src-tauri/src/lib.rs` | Tauri setup, plugin wiring, deep-link handling, window management, tray behavior, and lifecycle orchestration |\n| `companion/src-tauri/src/commands/` | commands for file info, download, upload, app selection, pairing, localization, and updates |\n| `companion/src-tauri/src/http_client.rs` | shared backend HTTP clients, reverse-proxy cookie jars, request diagnostics, and URL sanitization |\n| `companion/src-tauri/src/app_registry/` | platform-specific native-app discovery and launch integration |\n| `companion/src-tauri/src/sync/` | operation persistence, temp-file handling, recycle retention, and recovery helpers |\n| `companion/src-tauri/src/token/` and `uri/` | URI parsing and bootstrap-token exchange for deep-link editing |\n\n## Deep-Link Ingress\n\nNative-app editing starts from a `sambee://open?...` URI.\n\nThe runtime pieces involved are:\n\n- `tauri-plugin-deep-link` for receiving the URI\n- `tauri-plugin-single-instance` so later URIs are forwarded to the running instance instead of launching competing copies\n- `uri/mod.rs` for parsing required parameters such as `server`, `token`, `connId`, and `path`\n- `token/mod.rs` for exchanging the short-lived URI token for a companion bootstrap token\n\nThe deep link can also carry theme data so the companion UI matches the browser-side theme during the editing flow.\n\n## Reverse-Proxy Authentication Path\n\nNative editing supports reverse proxies and SSO layers that require interactive browser authentication before backend API requests are allowed through.\n\nThe implemented flow is:\n\n1. Companion tries the normal URI-token exchange.\n2. If token exchange is intercepted by a login redirect or HTML sign-in page, the companion opens a dedicated `Sambee Authentication` webview.\n3. The user signs in through that embedded webview.\n4. Companion reads backend-origin cookies from that same webview and seeds its shared Rust `reqwest` cookie jar.\n5. Token exchange and the rest of the native-edit lifecycle reuse that authenticated client state.\n\nThe HTTP client store is keyed by normalized server URL. For each server, it keeps a stable cookie jar plus default and no-redirect clients. The no-redirect client is used where redirect responses are diagnostic signals, such as URI-token exchange. The default client is reused for file-info lookup, lock acquisition, download, upload, lock release, and heartbeat requests.\n\nThis matters for the trust model:\n\n- Browser-to-companion localhost pairing remains separate from reverse-proxy authentication.\n- The Sambee bearer token remains separate from reverse-proxy cookies.\n- External browser cookies are not read or imported.\n- Reverse-proxy cookies stay inside the companion-owned webview and Rust HTTP client state.\n- Cookie values must not be logged.\n\nCompanion automatically retries idempotent backend calls such as file-info lookup, lock acquisition, download, lock release, and heartbeats after reauthentication. Non-idempotent uploads are not replayed automatically; the runtime instead asks the user to retry the action after authentication has been refreshed.\n\nFor reverse-proxy auth robustness, the shared Companion HTTP clients stay on HTTP/1.1 rather than enabling HTTP/2.\n\nRequest failures are logged with classified diagnostics such as timeout, connect, request, body, decode, and status. URLs and chained source errors are sanitized before logging so deep-link tokens, proxy sessions, and other sensitive query values do not appear in logs.\n\n## Native-App Edit Lifecycle\n\nThe implemented lifecycle in `lib.rs` is intentionally explicit.\n\nAt a high level it is:\n\n1. parse the deep link\n2. exchange the URI token for a companion bootstrap token\n3. fetch file metadata for file-size checks and conflict baseline\n4. optionally pause for a large-file confirmation dialog\n5. acquire the backend edit lock and receive operation-scoped lock context\n6. download the file into the companion temp area\n7. create a `FileOperation`, persist its sidecar, and add it to the in-memory store\n8. show the app picker and wait for user selection\n9. open the local file in the selected native application\n10. spawn a dedicated \"Done Editing\" window\n11. start background renewal, heartbeat, and file-status polling\n\nTwo rules matter here:\n\n- the backend lock is acquired before the edit session is allowed to proceed\n- the companion records local operation state before handing control to the native app\n\nThose decisions are what make recovery and conflict handling possible after crashes or interrupted sessions.\n\n## App Selection and Native Launching\n\nThe companion keeps platform-specific native-app discovery behind `app_registry/`.\n\nThat layer is responsible for:\n\n- listing handlers for a file extension\n- surfacing the default app first when possible\n- returning enough information for the UI to distinguish executable paths and handler identifiers\n- launching the chosen app or falling back to system-default open behavior when appropriate\n\nThe app picker flow is coordinated through Tauri events.\n\n- the Rust runtime emits `show-app-picker`\n- the frontend displays `AppPicker`\n- the user response is sent back through `respond_app_selection`\n\nStored per-extension app preferences live in `appPreferences.ts`, which is how repeated opens can bypass unnecessary picker friction.\n\nOn Windows, the launch path is more subtle than a simple `CreateProcess` call because packaged handlers and opaque shell associations may need Windows shell invocation rather than direct executable launching.\n\n## Operation Model, Temp Files, and Recovery\n\nDeep-link editing is tracked through `FileOperation` in `sync/operations.rs`.\n\nEach operation records:\n\n- server URL, connection, and remote path\n- local temp-file path\n- current status\n- original modification time\n- chosen app name\n- operation-scoped lock context and server-side last-modified baseline\n\nThe companion keeps this state in two places:\n\n- an in-memory `OperationStore` for active runtime coordination\n- a sidecar on disk so the session can be recovered after a restart or crash\n\nThat persistence model supports the recovery flow shown through `RecoveryDialog` when leftover operations are discovered at startup.\n\nThe temp-file lifecycle is also intentionally not just \"download and delete\":\n\n- active sessions live in a managed temp area\n- completed or discarded files move through recycle and retention logic\n- retention duration is user-configurable through preferences\n\n## \"Done Editing\" and Explicit Save-Back\n\nThe companion does not try to infer when a user is \"probably done\" in their native editor.\n\nInstead it keeps a dedicated \"Done Editing\" window open while:\n\n- file status polling checks whether the local temp file changed\n- renewal and heartbeat requests keep the edit session and backend lock alive\n\nWhen the user explicitly finishes or discards the session, the companion can:\n\n- upload the modified file\n- release the backend lock\n- recycle the temp copy\n- update the tray and operation state\n\nThat explicit-confirmation model is one of the core product decisions behind native-app editing, not a UI accident.\n\n## Conflict and Recovery Handling\n\nThe companion keeps enough state to detect overwrite-sensitive conflicts.\n\nBefore completing an upload-sensitive flow, it compares the current server-side state with the baseline captured earlier in the edit session. If those diverge, the conflict dialog path is used instead of silently overwriting the server copy.\n\nThis is also why recovery state is more than a cosmetic convenience feature. It protects the editing workflow from leaving users with stranded temp files and unclear lock state after interruption.\n\n## Preferences, Pairing UI, and Update Checks\n\nThe reused main window also hosts companion preferences.\n\nCurrent public settings include:\n\n- upload conflict behavior\n- auto-start at sign-in\n- desktop notifications\n- update channel selection\n- temp-file retention period\n- paired-origin management\n\nThe update path itself is channel-aware and lives in `commands/update.rs`, but detailed release-feed and packaging workflow belongs with companion distribution and update documentation rather than this runtime page.\n\nThe pairing window is a separate UI surface because browser-to-companion approval is part of the trust boundary, not just another generic settings dialog.\n\n## What Usually Breaks When This Layer Changes\n\n- deep links reach the app, but the running instance does not receive forwarded URIs correctly\n- lock acquisition or release gets out of sync with the visible edit lifecycle\n- picker cancellation or launch failure leaves behind stale temp files or sidecars\n- operation recovery loses enough metadata that interrupted edits become hard to resolve safely\n- tray and window state drift apart from the actual set of active operations\n\n## Where to Continue\n\n- Use [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) for pairing, localhost auth, deep-link trust boundaries, and origin scoping.\n- Use [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/) for the difference between local-drive access and SMB-backed save-back.\n- Use [Companion Release Overview](../../release-and-versioning/companion-release-overview/) when the change affects packaged releases or updater rollout rather than runtime behavior.\n\n## Validation Expectations\n\nWhen this runtime changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe frontend and backend checks matter whenever the companion change alters a shared workflow contract.\n", "0.9": "+++\ntitle = \"Companion Runtime and Native-App Editing\"\n+++\n\nThis page covers the companion runtime that sits between the browser's deep-link request and the desktop user's native editing session.\n\nUse it when a change affects:\n\n- deep-link handling and single-instance behavior\n- app selection and native-app launching\n- operation persistence, recovery, and temp-file lifecycle\n- tray, app-picker, large-file, and \"Done Editing\" window behavior\n\nFor localhost pairing and local-drive behavior, continue to [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) and [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\n## Runtime Modes and UI Surfaces\n\nThe companion is not a traditional always-visible desktop app.\n\nIn normal use it shifts between a few runtime modes:\n\n- tray-oriented background state when no editing dialog is open\n- a reused main window for app picker, preferences, large-file confirmation, and recovery dialogs\n- a dedicated pairing window for browser-to-companion approval\n- one \"Done Editing\" window per active native-app edit session\n\nThat split is deliberate. The companion should stay lightweight when idle, but it still needs focused UI surfaces for edit coordination and pairing approval.\n\nBecause the companion is a tray-oriented app, closing the last transient webview must not implicitly terminate the process. The runtime intentionally prevents last-window destruction from exiting the app; explicit quit requests from the tray still exit normally.\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/App.tsx` | frontend view routing for idle, app picker, preferences, recovery, and large-file flows |\n| `companion/src/components/` | desktop-facing UI surfaces such as `AppPicker`, `DoneEditingWindow`, `RecoveryDialog`, and `Preferences` |\n| `companion/src/stores/` | persisted frontend preferences for app selection and companion settings |\n| `companion/src-tauri/src/lib.rs` | Tauri setup, plugin wiring, deep-link handling, window management, tray behavior, and lifecycle orchestration |\n| `companion/src-tauri/src/commands/` | commands for file info, download, upload, app selection, pairing, localization, and updates |\n| `companion/src-tauri/src/http_client.rs` | shared backend HTTP clients, reverse-proxy cookie jars, request diagnostics, and URL sanitization |\n| `companion/src-tauri/src/app_registry/` | platform-specific native-app discovery and launch integration |\n| `companion/src-tauri/src/sync/` | operation persistence, temp-file handling, recycle retention, and recovery helpers |\n| `companion/src-tauri/src/token/` and `uri/` | URI parsing and bootstrap-token exchange for deep-link editing |\n\n## Deep-Link Ingress\n\nNative-app editing starts from a `sambee://open?...` URI.\n\nThe runtime pieces involved are:\n\n- `tauri-plugin-deep-link` for receiving the URI\n- `tauri-plugin-single-instance` so later URIs are forwarded to the running instance instead of launching competing copies\n- `uri/mod.rs` for parsing required parameters such as `server`, `token`, `connId`, and `path`\n- `token/mod.rs` for exchanging the short-lived URI token for a companion bootstrap token\n\nThe deep link can also carry theme data so the companion UI matches the browser-side theme during the editing flow.\n\n## Reverse-Proxy Authentication Path\n\nNative editing supports reverse proxies and SSO layers that require interactive browser authentication before backend API requests are allowed through.\n\nThe implemented flow is:\n\n1. Companion tries the normal URI-token exchange.\n2. If token exchange is intercepted by a login redirect or HTML sign-in page, the companion opens a dedicated `Sambee Authentication` webview.\n3. The user signs in through that embedded webview.\n4. Companion reads backend-origin cookies from that same webview and seeds its shared Rust `reqwest` cookie jar.\n5. Token exchange and the rest of the native-edit lifecycle reuse that authenticated client state.\n\nThe HTTP client store is keyed by normalized server URL. For each server, it keeps a stable cookie jar plus default and no-redirect clients. The no-redirect client is used where redirect responses are diagnostic signals, such as URI-token exchange. The default client is reused for file-info lookup, lock acquisition, download, upload, lock release, and heartbeat requests.\n\nThis matters for the trust model:\n\n- Browser-to-companion localhost pairing remains separate from reverse-proxy authentication.\n- The Sambee bearer token remains separate from reverse-proxy cookies.\n- External browser cookies are not read or imported.\n- Reverse-proxy cookies stay inside the companion-owned webview and Rust HTTP client state.\n- Cookie values must not be logged.\n\nCompanion automatically retries idempotent backend calls such as file-info lookup, lock acquisition, download, lock release, and heartbeats after reauthentication. Non-idempotent uploads are not replayed automatically; the runtime instead asks the user to retry the action after authentication has been refreshed.\n\nFor reverse-proxy auth robustness, the shared Companion HTTP clients stay on HTTP/1.1 rather than enabling HTTP/2.\n\nRequest failures are logged with classified diagnostics such as timeout, connect, request, body, decode, and status. URLs and chained source errors are sanitized before logging so deep-link tokens, proxy sessions, and other sensitive query values do not appear in logs.\n\n## Native-App Edit Lifecycle\n\nThe implemented lifecycle in `lib.rs` is intentionally explicit.\n\nAt a high level it is:\n\n1. parse the deep link\n2. exchange the URI token for a companion bootstrap token\n3. fetch file metadata for file-size checks and conflict baseline\n4. optionally pause for a large-file confirmation dialog\n5. acquire the backend edit lock and receive operation-scoped lock context\n6. download the file into the companion temp area\n7. create a `FileOperation`, persist its sidecar, and add it to the in-memory store\n8. show the app picker and wait for user selection\n9. open the local file in the selected native application\n10. spawn a dedicated \"Done Editing\" window\n11. start background renewal, heartbeat, and file-status polling\n\nTwo rules matter here:\n\n- the backend lock is acquired before the edit session is allowed to proceed\n- the companion records local operation state before handing control to the native app\n\nThose decisions are what make recovery and conflict handling possible after crashes or interrupted sessions.\n\n## App Selection and Native Launching\n\nThe companion keeps platform-specific native-app discovery behind `app_registry/`.\n\nThat layer is responsible for:\n\n- listing handlers for a file extension\n- surfacing the default app first when possible\n- returning enough information for the UI to distinguish executable paths and handler identifiers\n- launching the chosen app or falling back to system-default open behavior when appropriate\n\nThe app picker flow is coordinated through Tauri events.\n\n- the Rust runtime emits `show-app-picker`\n- the frontend displays `AppPicker`\n- the user response is sent back through `respond_app_selection`\n\nStored per-extension app preferences live in `appPreferences.ts`, which is how repeated opens can bypass unnecessary picker friction.\n\nOn Windows, the launch path is more subtle than a simple `CreateProcess` call because packaged handlers and opaque shell associations may need Windows shell invocation rather than direct executable launching.\n\n## Operation Model, Temp Files, and Recovery\n\nDeep-link editing is tracked through `FileOperation` in `sync/operations.rs`.\n\nEach operation records:\n\n- server URL, connection, and remote path\n- local temp-file path\n- current status\n- original modification time\n- chosen app name\n- operation-scoped lock context and server-side last-modified baseline\n\nThe companion keeps this state in two places:\n\n- an in-memory `OperationStore` for active runtime coordination\n- a sidecar on disk so the session can be recovered after a restart or crash\n\nThat persistence model supports the recovery flow shown through `RecoveryDialog` when leftover operations are discovered at startup.\n\nThe temp-file lifecycle is also intentionally not just \"download and delete\":\n\n- active sessions live in a managed temp area\n- completed or discarded files move through recycle and retention logic\n- retention duration is user-configurable through preferences\n\n## \"Done Editing\" and Explicit Save-Back\n\nThe companion does not try to infer when a user is \"probably done\" in their native editor.\n\nInstead it keeps a dedicated \"Done Editing\" window open while:\n\n- file status polling checks whether the local temp file changed\n- renewal and heartbeat requests keep the edit session and backend lock alive\n\nWhen the user explicitly finishes or discards the session, the companion can:\n\n- upload the modified file\n- release the backend lock\n- recycle the temp copy\n- update the tray and operation state\n\nThat explicit-confirmation model is one of the core product decisions behind native-app editing, not a UI accident.\n\n## Conflict and Recovery Handling\n\nThe companion keeps enough state to detect overwrite-sensitive conflicts.\n\nBefore completing an upload-sensitive flow, it compares the current server-side state with the baseline captured earlier in the edit session. If those diverge, the conflict dialog path is used instead of silently overwriting the server copy.\n\nThis is also why recovery state is more than a cosmetic convenience feature. It protects the editing workflow from leaving users with stranded temp files and unclear lock state after interruption.\n\n## Preferences, Pairing UI, and Update Checks\n\nThe reused main window also hosts companion preferences.\n\nCurrent public settings include:\n\n- upload conflict behavior\n- auto-start at sign-in\n- desktop notifications\n- update channel selection\n- temp-file retention period\n- paired-origin management\n\nThe update path itself is channel-aware and lives in `commands/update.rs`, but detailed release-feed and packaging workflow belongs with companion distribution and update documentation rather than this runtime page.\n\nThe pairing window is a separate UI surface because browser-to-companion approval is part of the trust boundary, not just another generic settings dialog.\n\n## What Usually Breaks When This Layer Changes\n\n- deep links reach the app, but the running instance does not receive forwarded URIs correctly\n- lock acquisition or release gets out of sync with the visible edit lifecycle\n- picker cancellation or launch failure leaves behind stale temp files or sidecars\n- operation recovery loses enough metadata that interrupted edits become hard to resolve safely\n- tray and window state drift apart from the actual set of active operations\n\n## Where to Continue\n\n- Use [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) for pairing, localhost auth, deep-link trust boundaries, and origin scoping.\n- Use [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/) for the difference between local-drive access and SMB-backed save-back.\n- Use [Companion Release Overview](../../release-and-versioning/companion-release-overview/) when the change affects packaged releases or updater rollout rather than runtime behavior.\n\n## Validation Expectations\n\nWhen this runtime changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe frontend and backend checks matter whenever the companion change alters a shared workflow contract.\n", "1.0": "+++\ntitle = \"Companion Runtime and Native-App Editing\"\n+++\n\nThis page covers the companion runtime that sits between the browser's deep-link request and the desktop user's native editing session.\n\nUse it when a change affects:\n\n- deep-link handling and single-instance behavior\n- app selection and native-app launching\n- operation persistence, recovery, and temp-file lifecycle\n- tray, app-picker, large-file, and \"Done Editing\" window behavior\n\nFor localhost pairing and local-drive behavior, continue to [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) and [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\n## Runtime Modes and UI Surfaces\n\nThe companion is not a traditional always-visible desktop app.\n\nIn normal use it shifts between a few runtime modes:\n\n- tray-oriented background state when no editing dialog is open\n- a reused main window for app picker, preferences, large-file confirmation, and recovery dialogs\n- a dedicated pairing window for browser-to-companion approval\n- one \"Done Editing\" window per active native-app edit session\n\nThat split is deliberate. The companion should stay lightweight when idle, but it still needs focused UI surfaces for edit coordination and pairing approval.\n\nBecause the companion is a tray-oriented app, closing the last transient webview must not implicitly terminate the process. The runtime intentionally prevents last-window destruction from exiting the app; explicit quit requests from the tray still exit normally.\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/App.tsx` | frontend view routing for idle, app picker, preferences, recovery, and large-file flows |\n| `companion/src/components/` | desktop-facing UI surfaces such as `AppPicker`, `DoneEditingWindow`, `RecoveryDialog`, and `Preferences` |\n| `companion/src/stores/` | persisted frontend preferences for app selection and companion settings |\n| `companion/src-tauri/src/lib.rs` | Tauri setup, plugin wiring, deep-link handling, window management, tray behavior, and lifecycle orchestration |\n| `companion/src-tauri/src/commands/` | commands for file info, download, upload, app selection, pairing, localization, and updates |\n| `companion/src-tauri/src/http_client.rs` | shared backend HTTP clients, reverse-proxy cookie jars, request diagnostics, and URL sanitization |\n| `companion/src-tauri/src/app_registry/` | platform-specific native-app discovery and launch integration |\n| `companion/src-tauri/src/sync/` | operation persistence, temp-file handling, recycle retention, and recovery helpers |\n| `companion/src-tauri/src/token/` and `uri/` | URI parsing and bootstrap-token exchange for deep-link editing |\n\n## Deep-Link Ingress\n\nNative-app editing starts from a `sambee://open?...` URI.\n\nThe runtime pieces involved are:\n\n- `tauri-plugin-deep-link` for receiving the URI\n- `tauri-plugin-single-instance` so later URIs are forwarded to the running instance instead of launching competing copies\n- `uri/mod.rs` for parsing required parameters such as `server`, `token`, `connId`, and `path`\n- `token/mod.rs` for exchanging the short-lived URI token for a companion bootstrap token\n\nThe deep link can also carry theme data so the companion UI matches the browser-side theme during the editing flow.\n\n## Reverse-Proxy Authentication Path\n\nNative editing supports reverse proxies and SSO layers that require interactive browser authentication before backend API requests are allowed through.\n\nThe implemented flow is:\n\n1. Companion tries the normal URI-token exchange.\n2. If token exchange is intercepted by a login redirect or HTML sign-in page, the companion opens a dedicated `Sambee Authentication` webview.\n3. The user signs in through that embedded webview.\n4. Companion reads backend-origin cookies from that same webview and seeds its shared Rust `reqwest` cookie jar.\n5. Token exchange and the rest of the native-edit lifecycle reuse that authenticated client state.\n\nThe HTTP client store is keyed by normalized server URL. For each server, it keeps a stable cookie jar plus default and no-redirect clients. The no-redirect client is used where redirect responses are diagnostic signals, such as URI-token exchange. The default client is reused for file-info lookup, lock acquisition, download, upload, lock release, and heartbeat requests.\n\nThis matters for the trust model:\n\n- Browser-to-companion localhost pairing remains separate from reverse-proxy authentication.\n- The Sambee bearer token remains separate from reverse-proxy cookies.\n- External browser cookies are not read or imported.\n- Reverse-proxy cookies stay inside the companion-owned webview and Rust HTTP client state.\n- Cookie values must not be logged.\n\nCompanion automatically retries idempotent backend calls such as file-info lookup, lock acquisition, download, lock release, and heartbeats after reauthentication. Non-idempotent uploads are not replayed automatically; the runtime instead asks the user to retry the action after authentication has been refreshed.\n\nFor reverse-proxy auth robustness, the shared Companion HTTP clients stay on HTTP/1.1 rather than enabling HTTP/2.\n\nRequest failures are logged with classified diagnostics such as timeout, connect, request, body, decode, and status. URLs and chained source errors are sanitized before logging so deep-link tokens, proxy sessions, and other sensitive query values do not appear in logs.\n\n## Native-App Edit Lifecycle\n\nThe implemented lifecycle in `lib.rs` is intentionally explicit.\n\nAt a high level it is:\n\n1. parse the deep link\n2. exchange the URI token for a companion bootstrap token\n3. fetch file metadata for file-size checks and conflict baseline\n4. optionally pause for a large-file confirmation dialog\n5. acquire the backend edit lock and receive operation-scoped lock context\n6. download the file into the companion temp area\n7. create a `FileOperation`, persist its sidecar, and add it to the in-memory store\n8. show the app picker and wait for user selection\n9. open the local file in the selected native application\n10. spawn a dedicated \"Done Editing\" window\n11. start background renewal, heartbeat, and file-status polling\n\nTwo rules matter here:\n\n- the backend lock is acquired before the edit session is allowed to proceed\n- the companion records local operation state before handing control to the native app\n\nThose decisions are what make recovery and conflict handling possible after crashes or interrupted sessions.\n\n## App Selection and Native Launching\n\nThe companion keeps platform-specific native-app discovery behind `app_registry/`.\n\nThat layer is responsible for:\n\n- listing handlers for a file extension\n- surfacing the default app first when possible\n- returning enough information for the UI to distinguish executable paths and handler identifiers\n- launching the chosen app or falling back to system-default open behavior when appropriate\n\nThe app picker flow is coordinated through Tauri events.\n\n- the Rust runtime emits `show-app-picker`\n- the frontend displays `AppPicker`\n- the user response is sent back through `respond_app_selection`\n\nStored per-extension app preferences live in `appPreferences.ts`, which is how repeated opens can bypass unnecessary picker friction.\n\nOn Windows, the launch path is more subtle than a simple `CreateProcess` call because packaged handlers and opaque shell associations may need Windows shell invocation rather than direct executable launching.\n\n## Operation Model, Temp Files, and Recovery\n\nDeep-link editing is tracked through `FileOperation` in `sync/operations.rs`.\n\nEach operation records:\n\n- server URL, connection, and remote path\n- local temp-file path\n- current status\n- original modification time\n- chosen app name\n- operation-scoped lock context and server-side last-modified baseline\n\nThe companion keeps this state in two places:\n\n- an in-memory `OperationStore` for active runtime coordination\n- a sidecar on disk so the session can be recovered after a restart or crash\n\nThat persistence model supports the recovery flow shown through `RecoveryDialog` when leftover operations are discovered at startup.\n\nThe temp-file lifecycle is also intentionally not just \"download and delete\":\n\n- active sessions live in a managed temp area\n- completed or discarded files move through recycle and retention logic\n- retention duration is user-configurable through preferences\n\n## \"Done Editing\" and Explicit Save-Back\n\nThe companion does not try to infer when a user is \"probably done\" in their native editor.\n\nInstead it keeps a dedicated \"Done Editing\" window open while:\n\n- file status polling checks whether the local temp file changed\n- renewal and heartbeat requests keep the edit session and backend lock alive\n\nWhen the user explicitly finishes or discards the session, the companion can:\n\n- upload the modified file\n- release the backend lock\n- recycle the temp copy\n- update the tray and operation state\n\nThat explicit-confirmation model is one of the core product decisions behind native-app editing, not a UI accident.\n\n## Conflict and Recovery Handling\n\nThe companion keeps enough state to detect overwrite-sensitive conflicts.\n\nBefore completing an upload-sensitive flow, it compares the current server-side state with the baseline captured earlier in the edit session. If those diverge, the conflict dialog path is used instead of silently overwriting the server copy.\n\nThis is also why recovery state is more than a cosmetic convenience feature. It protects the editing workflow from leaving users with stranded temp files and unclear lock state after interruption.\n\n## Preferences, Pairing UI, and Update Checks\n\nThe reused main window also hosts companion preferences.\n\nCurrent public settings include:\n\n- upload conflict behavior\n- auto-start at sign-in\n- desktop notifications\n- update channel selection\n- temp-file retention period\n- paired-origin management\n\nThe update path itself is channel-aware and lives in `commands/update.rs`, but detailed release-feed and packaging workflow belongs with companion distribution and update documentation rather than this runtime page.\n\nThe pairing window is a separate UI surface because browser-to-companion approval is part of the trust boundary, not just another generic settings dialog.\n\n## What Usually Breaks When This Layer Changes\n\n- deep links reach the app, but the running instance does not receive forwarded URIs correctly\n- lock acquisition or release gets out of sync with the visible edit lifecycle\n- picker cancellation or launch failure leaves behind stale temp files or sidecars\n- operation recovery loses enough metadata that interrupted edits become hard to resolve safely\n- tray and window state drift apart from the actual set of active operations\n\n## Where to Continue\n\n- Use [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) for pairing, localhost auth, deep-link trust boundaries, and origin scoping.\n- Use [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/) for the difference between local-drive access and SMB-backed save-back.\n- Use [Companion Release Overview](../../release-and-versioning/companion-release-overview/) when the change affects packaged releases or updater rollout rather than runtime behavior.\n\n## Validation Expectations\n\nWhen this runtime changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe frontend and backend checks matter whenever the companion change alters a shared workflow contract.\n", "2.0": "+++\ntitle = \"Companion Runtime and Native-App Editing\"\n+++\n\nThis page covers the companion runtime that sits between the browser's deep-link request and the desktop user's native editing session.\n\nUse it when a change affects:\n\n- deep-link handling and single-instance behavior\n- app selection and native-app launching\n- operation persistence, recovery, and temp-file lifecycle\n- tray, app-picker, large-file, and \"Done Editing\" window behavior\n\nFor localhost pairing and local-drive behavior, continue to [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) and [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/).\n\n## Runtime Modes and UI Surfaces\n\nThe companion is not a traditional always-visible desktop app.\n\nIn normal use it shifts between a few runtime modes:\n\n- tray-oriented background state when no editing dialog is open\n- a reused main window for app picker, preferences, large-file confirmation, and recovery dialogs\n- a dedicated pairing window for browser-to-companion approval\n- one \"Done Editing\" window per active native-app edit session\n\nThat split is deliberate. The companion should stay lightweight when idle, but it still needs focused UI surfaces for edit coordination and pairing approval.\n\nBecause the companion is a tray-oriented app, closing the last transient webview must not implicitly terminate the process. The runtime intentionally prevents last-window destruction from exiting the app; explicit quit requests from the tray still exit normally.\n\n## Main Code Areas\n\n| Path | Responsibility |\n|---|---|\n| `companion/src/App.tsx` | frontend view routing for idle, app picker, preferences, recovery, and large-file flows |\n| `companion/src/components/` | desktop-facing UI surfaces such as `AppPicker`, `DoneEditingWindow`, `RecoveryDialog`, and `Preferences` |\n| `companion/src/stores/` | persisted frontend preferences for app selection and companion settings |\n| `companion/src-tauri/src/lib.rs` | Tauri setup, plugin wiring, deep-link handling, window management, tray behavior, and lifecycle orchestration |\n| `companion/src-tauri/src/commands/` | commands for file info, download, upload, app selection, pairing, localization, and updates |\n| `companion/src-tauri/src/http_client.rs` | shared backend HTTP clients, reverse-proxy cookie jars, request diagnostics, and URL sanitization |\n| `companion/src-tauri/src/app_registry/` | platform-specific native-app discovery and launch integration |\n| `companion/src-tauri/src/sync/` | operation persistence, temp-file handling, recycle retention, and recovery helpers |\n| `companion/src-tauri/src/token/` and `uri/` | URI parsing and bootstrap-token exchange for deep-link editing |\n\n## Deep-Link Ingress\n\nNative-app editing starts from a `sambee://open?...` URI.\n\nThe runtime pieces involved are:\n\n- `tauri-plugin-deep-link` for receiving the URI\n- `tauri-plugin-single-instance` so later URIs are forwarded to the running instance instead of launching competing copies\n- `uri/mod.rs` for parsing required parameters such as `server`, `token`, `connId`, and `path`\n- `token/mod.rs` for exchanging the short-lived URI token for a companion bootstrap token\n\nThe deep link can also carry theme data so the companion UI matches the browser-side theme during the editing flow.\n\n## Reverse-Proxy Authentication Path\n\nNative editing supports reverse proxies and SSO layers that require interactive browser authentication before backend API requests are allowed through.\n\nThe implemented flow is:\n\n1. Companion tries the normal URI-token exchange.\n2. If token exchange is intercepted by a login redirect or HTML sign-in page, the companion opens a dedicated `Sambee Authentication` webview.\n3. The user signs in through that embedded webview.\n4. Companion reads backend-origin cookies from that same webview and seeds its shared Rust `reqwest` cookie jar.\n5. Token exchange and the rest of the native-edit lifecycle reuse that authenticated client state.\n\nThe HTTP client store is keyed by normalized server URL. For each server, it keeps a stable cookie jar plus default and no-redirect clients. The no-redirect client is used where redirect responses are diagnostic signals, such as URI-token exchange. The default client is reused for file-info lookup, lock acquisition, download, upload, lock release, and heartbeat requests.\n\nThis matters for the trust model:\n\n- Browser-to-companion localhost pairing remains separate from reverse-proxy authentication.\n- The Sambee bearer token remains separate from reverse-proxy cookies.\n- External browser cookies are not read or imported.\n- Reverse-proxy cookies stay inside the companion-owned webview and Rust HTTP client state.\n- Cookie values must not be logged.\n\nCompanion automatically retries idempotent backend calls such as file-info lookup, lock acquisition, download, lock release, and heartbeats after reauthentication. Non-idempotent uploads are not replayed automatically; the runtime instead asks the user to retry the action after authentication has been refreshed.\n\nFor reverse-proxy auth robustness, the shared Companion HTTP clients stay on HTTP/1.1 rather than enabling HTTP/2.\n\nRequest failures are logged with classified diagnostics such as timeout, connect, request, body, decode, and status. URLs and chained source errors are sanitized before logging so deep-link tokens, proxy sessions, and other sensitive query values do not appear in logs.\n\n## Native-App Edit Lifecycle\n\nThe implemented lifecycle in `lib.rs` is intentionally explicit.\n\nAt a high level it is:\n\n1. parse the deep link\n2. exchange the URI token for a companion bootstrap token\n3. fetch file metadata for file-size checks and conflict baseline\n4. optionally pause for a large-file confirmation dialog\n5. acquire the backend edit lock and receive operation-scoped lock context\n6. download the file into the companion temp area\n7. create a `FileOperation`, persist its sidecar, and add it to the in-memory store\n8. show the app picker and wait for user selection\n9. open the local file in the selected native application\n10. spawn a dedicated \"Done Editing\" window\n11. start background renewal, heartbeat, and file-status polling\n\nTwo rules matter here:\n\n- the backend lock is acquired before the edit session is allowed to proceed\n- the companion records local operation state before handing control to the native app\n\nThose decisions are what make recovery and conflict handling possible after crashes or interrupted sessions.\n\n## App Selection and Native Launching\n\nThe companion keeps platform-specific native-app discovery behind `app_registry/`.\n\nThat layer is responsible for:\n\n- listing handlers for a file extension\n- surfacing the default app first when possible\n- returning enough information for the UI to distinguish executable paths and handler identifiers\n- launching the chosen app or falling back to system-default open behavior when appropriate\n\nThe app picker flow is coordinated through Tauri events.\n\n- the Rust runtime emits `show-app-picker`\n- the frontend displays `AppPicker`\n- the user response is sent back through `respond_app_selection`\n\nStored per-extension app preferences live in `appPreferences.ts`, which is how repeated opens can bypass unnecessary picker friction.\n\nOn Windows, the launch path is more subtle than a simple `CreateProcess` call because packaged handlers and opaque shell associations may need Windows shell invocation rather than direct executable launching.\n\n## Operation Model, Temp Files, and Recovery\n\nDeep-link editing is tracked through `FileOperation` in `sync/operations.rs`.\n\nEach operation records:\n\n- server URL, connection, and remote path\n- local temp-file path\n- current status\n- original modification time\n- chosen app name\n- operation-scoped lock context and server-side last-modified baseline\n\nThe companion keeps this state in two places:\n\n- an in-memory `OperationStore` for active runtime coordination\n- a sidecar on disk so the session can be recovered after a restart or crash\n\nThat persistence model supports the recovery flow shown through `RecoveryDialog` when leftover operations are discovered at startup.\n\nThe temp-file lifecycle is also intentionally not just \"download and delete\":\n\n- active sessions live in a managed temp area\n- completed or discarded files move through recycle and retention logic\n- retention duration is user-configurable through preferences\n\n## \"Done Editing\" and Explicit Save-Back\n\nThe companion does not try to infer when a user is \"probably done\" in their native editor.\n\nInstead it keeps a dedicated \"Done Editing\" window open while:\n\n- file status polling checks whether the local temp file changed\n- renewal and heartbeat requests keep the edit session and backend lock alive\n\nWhen the user explicitly finishes or discards the session, the companion can:\n\n- upload the modified file\n- release the backend lock\n- recycle the temp copy\n- update the tray and operation state\n\nThat explicit-confirmation model is one of the core product decisions behind native-app editing, not a UI accident.\n\n## Conflict and Recovery Handling\n\nThe companion keeps enough state to detect overwrite-sensitive conflicts.\n\nBefore completing an upload-sensitive flow, it compares the current server-side state with the baseline captured earlier in the edit session. If those diverge, the conflict dialog path is used instead of silently overwriting the server copy.\n\nThis is also why recovery state is more than a cosmetic convenience feature. It protects the editing workflow from leaving users with stranded temp files and unclear lock state after interruption.\n\n## Preferences, Pairing UI, and Update Checks\n\nThe reused main window also hosts companion preferences.\n\nCurrent public settings include:\n\n- upload conflict behavior\n- auto-start at sign-in\n- desktop notifications\n- update channel selection\n- temp-file retention period\n- paired-origin management\n\nThe update path itself is channel-aware and lives in `commands/update.rs`, but detailed release-feed and packaging workflow belongs with companion distribution and update documentation rather than this runtime page.\n\nThe pairing window is a separate UI surface because browser-to-companion approval is part of the trust boundary, not just another generic settings dialog.\n\n## What Usually Breaks When This Layer Changes\n\n- deep links reach the app, but the running instance does not receive forwarded URIs correctly\n- lock acquisition or release gets out of sync with the visible edit lifecycle\n- picker cancellation or launch failure leaves behind stale temp files or sidecars\n- operation recovery loses enough metadata that interrupted edits become hard to resolve safely\n- tray and window state drift apart from the actual set of active operations\n\n## Where to Continue\n\n- Use [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/) for pairing, localhost auth, deep-link trust boundaries, and origin scoping.\n- Use [Local-Drive and Save-Back Pipeline](../local-drive-and-save-back-pipeline/) for the difference between local-drive access and SMB-backed save-back.\n- Use [Companion Release Overview](../../release-and-versioning/companion-release-overview/) when the change affects packaged releases or updater rollout rather than runtime behavior.\n\n## Validation Expectations\n\nWhen this runtime changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe frontend and backend checks matter whenever the companion change alters a shared workflow contract.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/companion-architecture/browser-to-companion-trust-model", "parent_id": "section:developer-guide/companion-architecture", "depth": 2, "kind": "page", "label": "browser-to-companion-trust-model", "title": "Browser To Companion Trust Model", "path": "developer-guide/companion-architecture/browser-to-companion-trust-model", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "branched", "source_version": "0.7", "diff_added": 42, "diff_removed": 8}, "0.9": {"state": "inherited", "source_version": "0.8"}, "1.0": {"state": "inherited", "source_version": "0.8"}, "2.0": {"state": "inherited", "source_version": "0.8"}}, "content_versions": {"0.7": "+++\ntitle = \"Browser-to-Companion Trust Model\"\n+++\n\nThe browser-to-companion boundary is powerful because it crosses from the browser app into desktop-local capability. That makes it one of the most security-sensitive parts of Sambee.\n\n## Two Distinct Trust Paths\n\nSambee uses two browser-to-companion interaction models.\n\n### Deep-Link Editing Path\n\nThis path is used when the browser asks the companion to open an SMB-backed file in a native desktop app.\n\n1. The browser asks the backend for a short-lived URI token.\n1. The browser launches a `sambee://` deep link.\n1. Companion exchanges the one-time token for a companion bootstrap token.\n1. Companion uses that bootstrap token to look up file info, acquire the edit lock, receive an operation-scoped token plus lock context, and later upload or release through that narrower edit-session authority.\n\nCompanion sends the URI token to the backend token endpoint in a JSON request body. Do not reintroduce query-string token exchange compatibility; deep-link tokens are sensitive and should not be exposed in URLs, logs, proxy access logs, or browser history.\n\nThe deep-link token is not a general browser-to-companion credential. It is a short-lived bootstrap value for one native-editing handoff.\n\nAfter lock acquisition, the browser no longer carries the authority for that edit. The companion holds an operation-scoped backend token plus `operation_id`, `lock_id`, and `lock_capability` for the lifetime of the edit session.\n\n### Localhost API Path\n\nThis path is used for local-drive access and related browser-to-desktop features.\n\n1. the browser probes `http://localhost:21549/api/health`\n1. browser and companion perform an explicit pairing flow\n1. the browser uses authenticated localhost requests for local-drive operations\n1. the companion sends directory-change notifications over a paired WebSocket channel\n\n## Why Pairing Exists\n\nLocalhost alone is not a trust boundary.\n\nThe companion therefore requires explicit pairing and per-request authentication so that:\n\n- remote network clients cannot reach it\n- arbitrary websites cannot use it just because they run in the browser\n- local native processes do not gain the browser's paired privileges automatically\n\n## Pairing Model\n\nThe pairing flow is deliberately shaped like numeric-comparison pairing.\n\n- the browser and companion exchange nonces\n- both sides independently derive the same short pairing code\n- the user confirms the match in both places\n- the companion returns a shared secret only after dual confirmation succeeds\n\nThat dual confirmation step is what turns \u201csomething can reach localhost\u201d into \u201cthe user intentionally paired this browser origin with this desktop app.\u201d\n\n## Request Authentication after Pairing\n\nAfter pairing, companion-bound requests use HMAC-based authentication rather than the server's bearer-token flow.\n\n- localhost API requests carry an HMAC derived from the shared secret and a timestamp\n- the companion rejects requests outside the allowed clock window\n- pairing is tracked per browser origin, not as one global switch\n- the shared secret is stored in OS-protected credential storage on the companion side\n\n## Trust Boundaries Contributors Must Preserve\n\n- keep the companion bound to `127.0.0.1`\n- do not relax CORS rules casually\n- do not replace explicit pairing with silent trust-on-first-use behavior\n- keep browser-to-companion auth distinct from backend bearer-token auth\n- preserve the server-side edit-lock lifecycle for SMB-backed editing instead of letting the companion bypass it\n- keep reverse-proxy cookies distinct from Sambee bearer tokens and companion localhost pairing secrets\n- redact deep-link tokens, bootstrap tokens, operation tokens, cookies, authorization data, and other sensitive query values before logging\n\nReverse-proxy authentication is a separate trust path from localhost pairing. The companion may use cookies captured in its own backend-origin authentication webview for Rust-side backend requests, but it must not import cookies from the user's normal browser session.\n\n## What Changes Are High Risk\n\n- anything that alters token exchange or deep-link parsing\n- anything that changes pairing confirmation rules\n- anything that weakens HMAC validation, timestamp checking, or origin scoping\n- anything that blurs the distinction between local-drive workflows and SMB-backed edit workflows\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/auth.rs` | localhost API authentication |\n| `companion/src-tauri/src/server/pairing.rs` | pairing flow and secret lifecycle |\n| `companion/src-tauri/src/uri/` and `token/` | deep-link parsing and token exchange support |\n| `frontend/src/services/companion.ts` | browser-side pairing and companion communication |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion appropriately |\n\n## Validation Expectations\n\nWhen this trust model changes, do not validate only the companion.\n\nRun at least:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\n```\n\nIf the change alters SMB edit flows, add the relevant backend checks too.\n", "0.8": "+++\ntitle = \"Browser-to-Companion Trust Model\"\n+++\n\nThe browser-to-companion boundary is powerful because it crosses from the browser app into desktop-local capability. That makes it one of the most security-sensitive parts of Sambee.\n\n## Two Distinct Trust Paths\n\nSambee uses two browser-to-companion interaction models.\n\n### Deep-Link Editing Path\n\nThis path is used when the browser asks the companion to open an SMB-backed file in a native desktop app.\n\n1. The browser asks the backend for a short-lived URI token.\n1. The browser launches a `sambee://` deep link.\n1. Companion exchanges the one-time token for a session token.\n1. Companion downloads the file, acquires the edit lock, and later uploads the result.\n\nCompanion sends the URI token to the backend token endpoint in a JSON request body. Do not reintroduce query-string token exchange compatibility; deep-link tokens are sensitive and should not be exposed in URLs, logs, proxy access logs, or browser history.\n\nThe deep-link token is not a general browser-to-companion credential. It is a short-lived bootstrap value for one native-editing handoff.\n\n### Localhost API Path\n\nThis path is used for local-drive access and related browser-to-desktop features.\n\n1. the browser probes `http://localhost:21549/api/health`\n1. browser and companion perform an explicit pairing flow for the current browser origin\n1. the browser uses authenticated localhost requests for local-drive operations\n1. the companion sends directory-change notifications over a paired WebSocket channel\n\n## Why Pairing Exists\n\nLocalhost alone is not a trust boundary.\n\nThe companion therefore requires explicit pairing and per-request authentication so that:\n\n- remote network clients cannot reach it\n- arbitrary websites cannot use it just because they run in the browser\n- local native processes do not gain the browser's paired privileges automatically\n\n## Pairing Model\n\nThe pairing flow is deliberately shaped like numeric-comparison pairing, but the important trust decision is not just \u201cdo the codes match?\u201d It is \u201cdoes the user approve this exact browser origin on this computer?\u201d\n\n- the browser and companion exchange nonces\n- both sides independently derive the same short pairing code\n- the companion displays the exact requesting browser origin in a native approval window\n- the user confirms the match in both places\n- the companion returns a shared secret only after dual confirmation succeeds\n\nThat dual confirmation step is what turns \u201csomething can reach localhost\u201d into \u201cthe user intentionally paired this browser origin with this desktop app.\u201d\n\n### Production and Development Origin Rules\n\nIn production, Companion does not rely on a preconfigured list of Sambee frontend URLs.\n\n- any valid browser origin can request pairing\n- Companion normalizes that exact origin and shows it to the user for local approval\n- once approved, that exact origin becomes the paired browser origin for future authenticated localhost requests\n\nFor development, typical loopback browser origins such as `localhost`, `127.0.0.1`, and `::1` remain usable without manual per-port configuration.\n\nThis keeps development practical without weakening the production trust boundary into hostname heuristics or silent trust-on-first-use.\n\n## Request Authentication after Pairing\n\nAfter pairing, companion-bound requests use HMAC-based authentication rather than the server's bearer-token flow.\n\n- localhost API requests carry an HMAC derived from the shared secret and a timestamp\n- the companion rejects requests outside the allowed clock window\n- pairing is tracked per browser origin, not as one global switch\n- the shared secret is stored in OS-protected credential storage on the companion side\n\nBrowser-facing pairing state should also stay origin-scoped and typed.\n\nImportant browser-visible states include:\n\n- unavailable\n- unpaired\n- pending local approval\n- paired\n- repair required because the browser-side secret is missing or unusable\n\nThat state model matters because local trust problems should surface as explicit recovery states rather than as a misleading generic \u201cnot paired\u201d result.\n\n## Pairing Management and Cancellation\n\nPairing management is intentionally narrower than routine local-drive access.\n\n- the browser should only learn the status of its own current origin\n- browser-visible paired-origin enumeration is not part of the browser contract\n- browser-managed unpairing is limited to the current origin\n- closing either pairing UI path should cancel the pending request explicitly\n\nThat last point is part of the trust model, not just a UX detail. A dismissed pairing window should not leave behind a stale approval request that can still be completed later by accident.\n\n## Trust Boundaries Contributors Must Preserve\n\n- keep the companion bound to `127.0.0.1`\n- do not relax CORS rules casually\n- do not replace exact-origin approval with hostname heuristics or silent trust-on-first-use behavior\n- keep browser-to-companion auth distinct from backend bearer-token auth\n- preserve the server-side edit-lock lifecycle for SMB-backed editing instead of letting the companion bypass it\n- keep reverse-proxy cookies distinct from Sambee bearer tokens and companion localhost pairing secrets\n- redact deep-link tokens, sessions, cookies, authorization data, and other sensitive query values before logging\n\nReverse-proxy authentication is a separate trust path from localhost pairing. The companion may use cookies captured in its own backend-origin authentication webview for Rust-side backend requests, but it must not import cookies from the user's normal browser session.\n\n## What Changes Are High Risk\n\n- anything that alters token exchange or deep-link parsing\n- anything that changes pairing confirmation rules\n- anything that weakens HMAC validation, timestamp checking, or origin scoping\n- anything that blurs the distinction between local-drive workflows and SMB-backed edit workflows\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/auth.rs` | localhost API authentication |\n| `companion/src-tauri/src/server/pairing.rs` | pairing flow and secret lifecycle |\n| `companion/src-tauri/src/uri/` and `token/` | deep-link parsing and token exchange support |\n| `frontend/src/services/companion.ts` | browser-side pairing and companion communication |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion appropriately |\n\n## Validation Expectations\n\nWhen this trust model changes, do not validate only the companion.\n\nRun at least:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\n```\n\nIf the change alters SMB edit flows, add the relevant backend checks too.\n", "0.9": "+++\ntitle = \"Browser-to-Companion Trust Model\"\n+++\n\nThe browser-to-companion boundary is powerful because it crosses from the browser app into desktop-local capability. That makes it one of the most security-sensitive parts of Sambee.\n\n## Two Distinct Trust Paths\n\nSambee uses two browser-to-companion interaction models.\n\n### Deep-Link Editing Path\n\nThis path is used when the browser asks the companion to open an SMB-backed file in a native desktop app.\n\n1. The browser asks the backend for a short-lived URI token.\n1. The browser launches a `sambee://` deep link.\n1. Companion exchanges the one-time token for a session token.\n1. Companion downloads the file, acquires the edit lock, and later uploads the result.\n\nCompanion sends the URI token to the backend token endpoint in a JSON request body. Do not reintroduce query-string token exchange compatibility; deep-link tokens are sensitive and should not be exposed in URLs, logs, proxy access logs, or browser history.\n\nThe deep-link token is not a general browser-to-companion credential. It is a short-lived bootstrap value for one native-editing handoff.\n\n### Localhost API Path\n\nThis path is used for local-drive access and related browser-to-desktop features.\n\n1. the browser probes `http://localhost:21549/api/health`\n1. browser and companion perform an explicit pairing flow for the current browser origin\n1. the browser uses authenticated localhost requests for local-drive operations\n1. the companion sends directory-change notifications over a paired WebSocket channel\n\n## Why Pairing Exists\n\nLocalhost alone is not a trust boundary.\n\nThe companion therefore requires explicit pairing and per-request authentication so that:\n\n- remote network clients cannot reach it\n- arbitrary websites cannot use it just because they run in the browser\n- local native processes do not gain the browser's paired privileges automatically\n\n## Pairing Model\n\nThe pairing flow is deliberately shaped like numeric-comparison pairing, but the important trust decision is not just \u201cdo the codes match?\u201d It is \u201cdoes the user approve this exact browser origin on this computer?\u201d\n\n- the browser and companion exchange nonces\n- both sides independently derive the same short pairing code\n- the companion displays the exact requesting browser origin in a native approval window\n- the user confirms the match in both places\n- the companion returns a shared secret only after dual confirmation succeeds\n\nThat dual confirmation step is what turns \u201csomething can reach localhost\u201d into \u201cthe user intentionally paired this browser origin with this desktop app.\u201d\n\n### Production and Development Origin Rules\n\nIn production, Companion does not rely on a preconfigured list of Sambee frontend URLs.\n\n- any valid browser origin can request pairing\n- Companion normalizes that exact origin and shows it to the user for local approval\n- once approved, that exact origin becomes the paired browser origin for future authenticated localhost requests\n\nFor development, typical loopback browser origins such as `localhost`, `127.0.0.1`, and `::1` remain usable without manual per-port configuration.\n\nThis keeps development practical without weakening the production trust boundary into hostname heuristics or silent trust-on-first-use.\n\n## Request Authentication after Pairing\n\nAfter pairing, companion-bound requests use HMAC-based authentication rather than the server's bearer-token flow.\n\n- localhost API requests carry an HMAC derived from the shared secret and a timestamp\n- the companion rejects requests outside the allowed clock window\n- pairing is tracked per browser origin, not as one global switch\n- the shared secret is stored in OS-protected credential storage on the companion side\n\nBrowser-facing pairing state should also stay origin-scoped and typed.\n\nImportant browser-visible states include:\n\n- unavailable\n- unpaired\n- pending local approval\n- paired\n- repair required because the browser-side secret is missing or unusable\n\nThat state model matters because local trust problems should surface as explicit recovery states rather than as a misleading generic \u201cnot paired\u201d result.\n\n## Pairing Management and Cancellation\n\nPairing management is intentionally narrower than routine local-drive access.\n\n- the browser should only learn the status of its own current origin\n- browser-visible paired-origin enumeration is not part of the browser contract\n- browser-managed unpairing is limited to the current origin\n- closing either pairing UI path should cancel the pending request explicitly\n\nThat last point is part of the trust model, not just a UX detail. A dismissed pairing window should not leave behind a stale approval request that can still be completed later by accident.\n\n## Trust Boundaries Contributors Must Preserve\n\n- keep the companion bound to `127.0.0.1`\n- do not relax CORS rules casually\n- do not replace exact-origin approval with hostname heuristics or silent trust-on-first-use behavior\n- keep browser-to-companion auth distinct from backend bearer-token auth\n- preserve the server-side edit-lock lifecycle for SMB-backed editing instead of letting the companion bypass it\n- keep reverse-proxy cookies distinct from Sambee bearer tokens and companion localhost pairing secrets\n- redact deep-link tokens, sessions, cookies, authorization data, and other sensitive query values before logging\n\nReverse-proxy authentication is a separate trust path from localhost pairing. The companion may use cookies captured in its own backend-origin authentication webview for Rust-side backend requests, but it must not import cookies from the user's normal browser session.\n\n## What Changes Are High Risk\n\n- anything that alters token exchange or deep-link parsing\n- anything that changes pairing confirmation rules\n- anything that weakens HMAC validation, timestamp checking, or origin scoping\n- anything that blurs the distinction between local-drive workflows and SMB-backed edit workflows\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/auth.rs` | localhost API authentication |\n| `companion/src-tauri/src/server/pairing.rs` | pairing flow and secret lifecycle |\n| `companion/src-tauri/src/uri/` and `token/` | deep-link parsing and token exchange support |\n| `frontend/src/services/companion.ts` | browser-side pairing and companion communication |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion appropriately |\n\n## Validation Expectations\n\nWhen this trust model changes, do not validate only the companion.\n\nRun at least:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\n```\n\nIf the change alters SMB edit flows, add the relevant backend checks too.\n", "1.0": "+++\ntitle = \"Browser-to-Companion Trust Model\"\n+++\n\nThe browser-to-companion boundary is powerful because it crosses from the browser app into desktop-local capability. That makes it one of the most security-sensitive parts of Sambee.\n\n## Two Distinct Trust Paths\n\nSambee uses two browser-to-companion interaction models.\n\n### Deep-Link Editing Path\n\nThis path is used when the browser asks the companion to open an SMB-backed file in a native desktop app.\n\n1. The browser asks the backend for a short-lived URI token.\n1. The browser launches a `sambee://` deep link.\n1. Companion exchanges the one-time token for a session token.\n1. Companion downloads the file, acquires the edit lock, and later uploads the result.\n\nCompanion sends the URI token to the backend token endpoint in a JSON request body. Do not reintroduce query-string token exchange compatibility; deep-link tokens are sensitive and should not be exposed in URLs, logs, proxy access logs, or browser history.\n\nThe deep-link token is not a general browser-to-companion credential. It is a short-lived bootstrap value for one native-editing handoff.\n\n### Localhost API Path\n\nThis path is used for local-drive access and related browser-to-desktop features.\n\n1. the browser probes `http://localhost:21549/api/health`\n1. browser and companion perform an explicit pairing flow for the current browser origin\n1. the browser uses authenticated localhost requests for local-drive operations\n1. the companion sends directory-change notifications over a paired WebSocket channel\n\n## Why Pairing Exists\n\nLocalhost alone is not a trust boundary.\n\nThe companion therefore requires explicit pairing and per-request authentication so that:\n\n- remote network clients cannot reach it\n- arbitrary websites cannot use it just because they run in the browser\n- local native processes do not gain the browser's paired privileges automatically\n\n## Pairing Model\n\nThe pairing flow is deliberately shaped like numeric-comparison pairing, but the important trust decision is not just \u201cdo the codes match?\u201d It is \u201cdoes the user approve this exact browser origin on this computer?\u201d\n\n- the browser and companion exchange nonces\n- both sides independently derive the same short pairing code\n- the companion displays the exact requesting browser origin in a native approval window\n- the user confirms the match in both places\n- the companion returns a shared secret only after dual confirmation succeeds\n\nThat dual confirmation step is what turns \u201csomething can reach localhost\u201d into \u201cthe user intentionally paired this browser origin with this desktop app.\u201d\n\n### Production and Development Origin Rules\n\nIn production, Companion does not rely on a preconfigured list of Sambee frontend URLs.\n\n- any valid browser origin can request pairing\n- Companion normalizes that exact origin and shows it to the user for local approval\n- once approved, that exact origin becomes the paired browser origin for future authenticated localhost requests\n\nFor development, typical loopback browser origins such as `localhost`, `127.0.0.1`, and `::1` remain usable without manual per-port configuration.\n\nThis keeps development practical without weakening the production trust boundary into hostname heuristics or silent trust-on-first-use.\n\n## Request Authentication after Pairing\n\nAfter pairing, companion-bound requests use HMAC-based authentication rather than the server's bearer-token flow.\n\n- localhost API requests carry an HMAC derived from the shared secret and a timestamp\n- the companion rejects requests outside the allowed clock window\n- pairing is tracked per browser origin, not as one global switch\n- the shared secret is stored in OS-protected credential storage on the companion side\n\nBrowser-facing pairing state should also stay origin-scoped and typed.\n\nImportant browser-visible states include:\n\n- unavailable\n- unpaired\n- pending local approval\n- paired\n- repair required because the browser-side secret is missing or unusable\n\nThat state model matters because local trust problems should surface as explicit recovery states rather than as a misleading generic \u201cnot paired\u201d result.\n\n## Pairing Management and Cancellation\n\nPairing management is intentionally narrower than routine local-drive access.\n\n- the browser should only learn the status of its own current origin\n- browser-visible paired-origin enumeration is not part of the browser contract\n- browser-managed unpairing is limited to the current origin\n- closing either pairing UI path should cancel the pending request explicitly\n\nThat last point is part of the trust model, not just a UX detail. A dismissed pairing window should not leave behind a stale approval request that can still be completed later by accident.\n\n## Trust Boundaries Contributors Must Preserve\n\n- keep the companion bound to `127.0.0.1`\n- do not relax CORS rules casually\n- do not replace exact-origin approval with hostname heuristics or silent trust-on-first-use behavior\n- keep browser-to-companion auth distinct from backend bearer-token auth\n- preserve the server-side edit-lock lifecycle for SMB-backed editing instead of letting the companion bypass it\n- keep reverse-proxy cookies distinct from Sambee bearer tokens and companion localhost pairing secrets\n- redact deep-link tokens, sessions, cookies, authorization data, and other sensitive query values before logging\n\nReverse-proxy authentication is a separate trust path from localhost pairing. The companion may use cookies captured in its own backend-origin authentication webview for Rust-side backend requests, but it must not import cookies from the user's normal browser session.\n\n## What Changes Are High Risk\n\n- anything that alters token exchange or deep-link parsing\n- anything that changes pairing confirmation rules\n- anything that weakens HMAC validation, timestamp checking, or origin scoping\n- anything that blurs the distinction between local-drive workflows and SMB-backed edit workflows\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/auth.rs` | localhost API authentication |\n| `companion/src-tauri/src/server/pairing.rs` | pairing flow and secret lifecycle |\n| `companion/src-tauri/src/uri/` and `token/` | deep-link parsing and token exchange support |\n| `frontend/src/services/companion.ts` | browser-side pairing and companion communication |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion appropriately |\n\n## Validation Expectations\n\nWhen this trust model changes, do not validate only the companion.\n\nRun at least:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\n```\n\nIf the change alters SMB edit flows, add the relevant backend checks too.\n", "2.0": "+++\ntitle = \"Browser-to-Companion Trust Model\"\n+++\n\nThe browser-to-companion boundary is powerful because it crosses from the browser app into desktop-local capability. That makes it one of the most security-sensitive parts of Sambee.\n\n## Two Distinct Trust Paths\n\nSambee uses two browser-to-companion interaction models.\n\n### Deep-Link Editing Path\n\nThis path is used when the browser asks the companion to open an SMB-backed file in a native desktop app.\n\n1. The browser asks the backend for a short-lived URI token.\n1. The browser launches a `sambee://` deep link.\n1. Companion exchanges the one-time token for a session token.\n1. Companion downloads the file, acquires the edit lock, and later uploads the result.\n\nCompanion sends the URI token to the backend token endpoint in a JSON request body. Do not reintroduce query-string token exchange compatibility; deep-link tokens are sensitive and should not be exposed in URLs, logs, proxy access logs, or browser history.\n\nThe deep-link token is not a general browser-to-companion credential. It is a short-lived bootstrap value for one native-editing handoff.\n\n### Localhost API Path\n\nThis path is used for local-drive access and related browser-to-desktop features.\n\n1. the browser probes `http://localhost:21549/api/health`\n1. browser and companion perform an explicit pairing flow for the current browser origin\n1. the browser uses authenticated localhost requests for local-drive operations\n1. the companion sends directory-change notifications over a paired WebSocket channel\n\n## Why Pairing Exists\n\nLocalhost alone is not a trust boundary.\n\nThe companion therefore requires explicit pairing and per-request authentication so that:\n\n- remote network clients cannot reach it\n- arbitrary websites cannot use it just because they run in the browser\n- local native processes do not gain the browser's paired privileges automatically\n\n## Pairing Model\n\nThe pairing flow is deliberately shaped like numeric-comparison pairing, but the important trust decision is not just \u201cdo the codes match?\u201d It is \u201cdoes the user approve this exact browser origin on this computer?\u201d\n\n- the browser and companion exchange nonces\n- both sides independently derive the same short pairing code\n- the companion displays the exact requesting browser origin in a native approval window\n- the user confirms the match in both places\n- the companion returns a shared secret only after dual confirmation succeeds\n\nThat dual confirmation step is what turns \u201csomething can reach localhost\u201d into \u201cthe user intentionally paired this browser origin with this desktop app.\u201d\n\n### Production and Development Origin Rules\n\nIn production, Companion does not rely on a preconfigured list of Sambee frontend URLs.\n\n- any valid browser origin can request pairing\n- Companion normalizes that exact origin and shows it to the user for local approval\n- once approved, that exact origin becomes the paired browser origin for future authenticated localhost requests\n\nFor development, typical loopback browser origins such as `localhost`, `127.0.0.1`, and `::1` remain usable without manual per-port configuration.\n\nThis keeps development practical without weakening the production trust boundary into hostname heuristics or silent trust-on-first-use.\n\n## Request Authentication after Pairing\n\nAfter pairing, companion-bound requests use HMAC-based authentication rather than the server's bearer-token flow.\n\n- localhost API requests carry an HMAC derived from the shared secret and a timestamp\n- the companion rejects requests outside the allowed clock window\n- pairing is tracked per browser origin, not as one global switch\n- the shared secret is stored in OS-protected credential storage on the companion side\n\nBrowser-facing pairing state should also stay origin-scoped and typed.\n\nImportant browser-visible states include:\n\n- unavailable\n- unpaired\n- pending local approval\n- paired\n- repair required because the browser-side secret is missing or unusable\n\nThat state model matters because local trust problems should surface as explicit recovery states rather than as a misleading generic \u201cnot paired\u201d result.\n\n## Pairing Management and Cancellation\n\nPairing management is intentionally narrower than routine local-drive access.\n\n- the browser should only learn the status of its own current origin\n- browser-visible paired-origin enumeration is not part of the browser contract\n- browser-managed unpairing is limited to the current origin\n- closing either pairing UI path should cancel the pending request explicitly\n\nThat last point is part of the trust model, not just a UX detail. A dismissed pairing window should not leave behind a stale approval request that can still be completed later by accident.\n\n## Trust Boundaries Contributors Must Preserve\n\n- keep the companion bound to `127.0.0.1`\n- do not relax CORS rules casually\n- do not replace exact-origin approval with hostname heuristics or silent trust-on-first-use behavior\n- keep browser-to-companion auth distinct from backend bearer-token auth\n- preserve the server-side edit-lock lifecycle for SMB-backed editing instead of letting the companion bypass it\n- keep reverse-proxy cookies distinct from Sambee bearer tokens and companion localhost pairing secrets\n- redact deep-link tokens, sessions, cookies, authorization data, and other sensitive query values before logging\n\nReverse-proxy authentication is a separate trust path from localhost pairing. The companion may use cookies captured in its own backend-origin authentication webview for Rust-side backend requests, but it must not import cookies from the user's normal browser session.\n\n## What Changes Are High Risk\n\n- anything that alters token exchange or deep-link parsing\n- anything that changes pairing confirmation rules\n- anything that weakens HMAC validation, timestamp checking, or origin scoping\n- anything that blurs the distinction between local-drive workflows and SMB-backed edit workflows\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/auth.rs` | localhost API authentication |\n| `companion/src-tauri/src/server/pairing.rs` | pairing flow and secret lifecycle |\n| `companion/src-tauri/src/uri/` and `token/` | deep-link parsing and token exchange support |\n| `frontend/src/services/companion.ts` | browser-side pairing and companion communication |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion appropriately |\n\n## Validation Expectations\n\nWhen this trust model changes, do not validate only the companion.\n\nRun at least:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\n```\n\nIf the change alters SMB edit flows, add the relevant backend checks too.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Browser-to-Companion Trust Model\"\n+++\n\nThe browser-to-companion boundary is powerful because it crosses from the browser app into desktop-local capability. That makes it one of the most security-sensitive parts of Sambee.\n\n## Two Distinct Trust Paths\n\nSambee uses two browser-to-companion interaction models.\n\n### Deep-Link Editing Path\n\nThis path is used when the browser asks the companion to open an SMB-backed file in a native desktop app.\n\n1. The browser asks the backend for a short-lived URI token.\n1. The browser launches a `sambee://` deep link.\n1. Companion exchanges the one-time token for a companion bootstrap token.\n1. Companion uses that bootstrap token to look up file info, acquire the edit lock, receive an operation-scoped token plus lock context, and later upload or release through that narrower edit-session authority.\n\nCompanion sends the URI token to the backend token endpoint in a JSON request body. Do not reintroduce query-string token exchange compatibility; deep-link tokens are sensitive and should not be exposed in URLs, logs, proxy access logs, or browser history.\n\nThe deep-link token is not a general browser-to-companion credential. It is a short-lived bootstrap value for one native-editing handoff.\n\nAfter lock acquisition, the browser no longer carries the authority for that edit. The companion holds an operation-scoped backend token plus `operation_id`, `lock_id`, and `lock_capability` for the lifetime of the edit session.\n\n### Localhost API Path\n\nThis path is used for local-drive access and related browser-to-desktop features.\n\n1. the browser probes `http://localhost:21549/api/health`\n1. browser and companion perform an explicit pairing flow\n1. the browser uses authenticated localhost requests for local-drive operations\n1. the companion sends directory-change notifications over a paired WebSocket channel\n\n## Why Pairing Exists\n\nLocalhost alone is not a trust boundary.\n\nThe companion therefore requires explicit pairing and per-request authentication so that:\n\n- remote network clients cannot reach it\n- arbitrary websites cannot use it just because they run in the browser\n- local native processes do not gain the browser's paired privileges automatically\n\n## Pairing Model\n\nThe pairing flow is deliberately shaped like numeric-comparison pairing.\n\n- the browser and companion exchange nonces\n- both sides independently derive the same short pairing code\n- the user confirms the match in both places\n- the companion returns a shared secret only after dual confirmation succeeds\n\nThat dual confirmation step is what turns \u201csomething can reach localhost\u201d into \u201cthe user intentionally paired this browser origin with this desktop app.\u201d\n\n## Request Authentication after Pairing\n\nAfter pairing, companion-bound requests use HMAC-based authentication rather than the server's bearer-token flow.\n\n- localhost API requests carry an HMAC derived from the shared secret and a timestamp\n- the companion rejects requests outside the allowed clock window\n- pairing is tracked per browser origin, not as one global switch\n- the shared secret is stored in OS-protected credential storage on the companion side\n\n## Trust Boundaries Contributors Must Preserve\n\n- keep the companion bound to `127.0.0.1`\n- do not relax CORS rules casually\n- do not replace explicit pairing with silent trust-on-first-use behavior\n- keep browser-to-companion auth distinct from backend bearer-token auth\n- preserve the server-side edit-lock lifecycle for SMB-backed editing instead of letting the companion bypass it\n- keep reverse-proxy cookies distinct from Sambee bearer tokens and companion localhost pairing secrets\n- redact deep-link tokens, bootstrap tokens, operation tokens, cookies, authorization data, and other sensitive query values before logging\n\nReverse-proxy authentication is a separate trust path from localhost pairing. The companion may use cookies captured in its own backend-origin authentication webview for Rust-side backend requests, but it must not import cookies from the user's normal browser session.\n\n## What Changes Are High Risk\n\n- anything that alters token exchange or deep-link parsing\n- anything that changes pairing confirmation rules\n- anything that weakens HMAC validation, timestamp checking, or origin scoping\n- anything that blurs the distinction between local-drive workflows and SMB-backed edit workflows\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/auth.rs` | localhost API authentication |\n| `companion/src-tauri/src/server/pairing.rs` | pairing flow and secret lifecycle |\n| `companion/src-tauri/src/uri/` and `token/` | deep-link parsing and token exchange support |\n| `frontend/src/services/companion.ts` | browser-side pairing and companion communication |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion appropriately |\n\n## Validation Expectations\n\nWhen this trust model changes, do not validate only the companion.\n\nRun at least:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\n```\n\nIf the change alters SMB edit flows, add the relevant backend checks too.\n", "0.8": "+++\ntitle = \"Browser-to-Companion Trust Model\"\n+++\n\nThe browser-to-companion boundary is powerful because it crosses from the browser app into desktop-local capability. That makes it one of the most security-sensitive parts of Sambee.\n\n## Two Distinct Trust Paths\n\nSambee uses two browser-to-companion interaction models.\n\n### Deep-Link Editing Path\n\nThis path is used when the browser asks the companion to open an SMB-backed file in a native desktop app.\n\n1. The browser asks the backend for a short-lived URI token.\n1. The browser launches a `sambee://` deep link.\n1. Companion exchanges the one-time token for a session token.\n1. Companion downloads the file, acquires the edit lock, and later uploads the result.\n\nCompanion sends the URI token to the backend token endpoint in a JSON request body. Do not reintroduce query-string token exchange compatibility; deep-link tokens are sensitive and should not be exposed in URLs, logs, proxy access logs, or browser history.\n\nThe deep-link token is not a general browser-to-companion credential. It is a short-lived bootstrap value for one native-editing handoff.\n\n### Localhost API Path\n\nThis path is used for local-drive access and related browser-to-desktop features.\n\n1. the browser probes `http://localhost:21549/api/health`\n1. browser and companion perform an explicit pairing flow for the current browser origin\n1. the browser uses authenticated localhost requests for local-drive operations\n1. the companion sends directory-change notifications over a paired WebSocket channel\n\n## Why Pairing Exists\n\nLocalhost alone is not a trust boundary.\n\nThe companion therefore requires explicit pairing and per-request authentication so that:\n\n- remote network clients cannot reach it\n- arbitrary websites cannot use it just because they run in the browser\n- local native processes do not gain the browser's paired privileges automatically\n\n## Pairing Model\n\nThe pairing flow is deliberately shaped like numeric-comparison pairing, but the important trust decision is not just \u201cdo the codes match?\u201d It is \u201cdoes the user approve this exact browser origin on this computer?\u201d\n\n- the browser and companion exchange nonces\n- both sides independently derive the same short pairing code\n- the companion displays the exact requesting browser origin in a native approval window\n- the user confirms the match in both places\n- the companion returns a shared secret only after dual confirmation succeeds\n\nThat dual confirmation step is what turns \u201csomething can reach localhost\u201d into \u201cthe user intentionally paired this browser origin with this desktop app.\u201d\n\n### Production and Development Origin Rules\n\nIn production, Companion does not rely on a preconfigured list of Sambee frontend URLs.\n\n- any valid browser origin can request pairing\n- Companion normalizes that exact origin and shows it to the user for local approval\n- once approved, that exact origin becomes the paired browser origin for future authenticated localhost requests\n\nFor development, typical loopback browser origins such as `localhost`, `127.0.0.1`, and `::1` remain usable without manual per-port configuration.\n\nThis keeps development practical without weakening the production trust boundary into hostname heuristics or silent trust-on-first-use.\n\n## Request Authentication after Pairing\n\nAfter pairing, companion-bound requests use HMAC-based authentication rather than the server's bearer-token flow.\n\n- localhost API requests carry an HMAC derived from the shared secret and a timestamp\n- the companion rejects requests outside the allowed clock window\n- pairing is tracked per browser origin, not as one global switch\n- the shared secret is stored in OS-protected credential storage on the companion side\n\nBrowser-facing pairing state should also stay origin-scoped and typed.\n\nImportant browser-visible states include:\n\n- unavailable\n- unpaired\n- pending local approval\n- paired\n- repair required because the browser-side secret is missing or unusable\n\nThat state model matters because local trust problems should surface as explicit recovery states rather than as a misleading generic \u201cnot paired\u201d result.\n\n## Pairing Management and Cancellation\n\nPairing management is intentionally narrower than routine local-drive access.\n\n- the browser should only learn the status of its own current origin\n- browser-visible paired-origin enumeration is not part of the browser contract\n- browser-managed unpairing is limited to the current origin\n- closing either pairing UI path should cancel the pending request explicitly\n\nThat last point is part of the trust model, not just a UX detail. A dismissed pairing window should not leave behind a stale approval request that can still be completed later by accident.\n\n## Trust Boundaries Contributors Must Preserve\n\n- keep the companion bound to `127.0.0.1`\n- do not relax CORS rules casually\n- do not replace exact-origin approval with hostname heuristics or silent trust-on-first-use behavior\n- keep browser-to-companion auth distinct from backend bearer-token auth\n- preserve the server-side edit-lock lifecycle for SMB-backed editing instead of letting the companion bypass it\n- keep reverse-proxy cookies distinct from Sambee bearer tokens and companion localhost pairing secrets\n- redact deep-link tokens, sessions, cookies, authorization data, and other sensitive query values before logging\n\nReverse-proxy authentication is a separate trust path from localhost pairing. The companion may use cookies captured in its own backend-origin authentication webview for Rust-side backend requests, but it must not import cookies from the user's normal browser session.\n\n## What Changes Are High Risk\n\n- anything that alters token exchange or deep-link parsing\n- anything that changes pairing confirmation rules\n- anything that weakens HMAC validation, timestamp checking, or origin scoping\n- anything that blurs the distinction between local-drive workflows and SMB-backed edit workflows\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/auth.rs` | localhost API authentication |\n| `companion/src-tauri/src/server/pairing.rs` | pairing flow and secret lifecycle |\n| `companion/src-tauri/src/uri/` and `token/` | deep-link parsing and token exchange support |\n| `frontend/src/services/companion.ts` | browser-side pairing and companion communication |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion appropriately |\n\n## Validation Expectations\n\nWhen this trust model changes, do not validate only the companion.\n\nRun at least:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\n```\n\nIf the change alters SMB edit flows, add the relevant backend checks too.\n", "0.9": "+++\ntitle = \"Browser-to-Companion Trust Model\"\n+++\n\nThe browser-to-companion boundary is powerful because it crosses from the browser app into desktop-local capability. That makes it one of the most security-sensitive parts of Sambee.\n\n## Two Distinct Trust Paths\n\nSambee uses two browser-to-companion interaction models.\n\n### Deep-Link Editing Path\n\nThis path is used when the browser asks the companion to open an SMB-backed file in a native desktop app.\n\n1. The browser asks the backend for a short-lived URI token.\n1. The browser launches a `sambee://` deep link.\n1. Companion exchanges the one-time token for a session token.\n1. Companion downloads the file, acquires the edit lock, and later uploads the result.\n\nCompanion sends the URI token to the backend token endpoint in a JSON request body. Do not reintroduce query-string token exchange compatibility; deep-link tokens are sensitive and should not be exposed in URLs, logs, proxy access logs, or browser history.\n\nThe deep-link token is not a general browser-to-companion credential. It is a short-lived bootstrap value for one native-editing handoff.\n\n### Localhost API Path\n\nThis path is used for local-drive access and related browser-to-desktop features.\n\n1. the browser probes `http://localhost:21549/api/health`\n1. browser and companion perform an explicit pairing flow for the current browser origin\n1. the browser uses authenticated localhost requests for local-drive operations\n1. the companion sends directory-change notifications over a paired WebSocket channel\n\n## Why Pairing Exists\n\nLocalhost alone is not a trust boundary.\n\nThe companion therefore requires explicit pairing and per-request authentication so that:\n\n- remote network clients cannot reach it\n- arbitrary websites cannot use it just because they run in the browser\n- local native processes do not gain the browser's paired privileges automatically\n\n## Pairing Model\n\nThe pairing flow is deliberately shaped like numeric-comparison pairing, but the important trust decision is not just \u201cdo the codes match?\u201d It is \u201cdoes the user approve this exact browser origin on this computer?\u201d\n\n- the browser and companion exchange nonces\n- both sides independently derive the same short pairing code\n- the companion displays the exact requesting browser origin in a native approval window\n- the user confirms the match in both places\n- the companion returns a shared secret only after dual confirmation succeeds\n\nThat dual confirmation step is what turns \u201csomething can reach localhost\u201d into \u201cthe user intentionally paired this browser origin with this desktop app.\u201d\n\n### Production and Development Origin Rules\n\nIn production, Companion does not rely on a preconfigured list of Sambee frontend URLs.\n\n- any valid browser origin can request pairing\n- Companion normalizes that exact origin and shows it to the user for local approval\n- once approved, that exact origin becomes the paired browser origin for future authenticated localhost requests\n\nFor development, typical loopback browser origins such as `localhost`, `127.0.0.1`, and `::1` remain usable without manual per-port configuration.\n\nThis keeps development practical without weakening the production trust boundary into hostname heuristics or silent trust-on-first-use.\n\n## Request Authentication after Pairing\n\nAfter pairing, companion-bound requests use HMAC-based authentication rather than the server's bearer-token flow.\n\n- localhost API requests carry an HMAC derived from the shared secret and a timestamp\n- the companion rejects requests outside the allowed clock window\n- pairing is tracked per browser origin, not as one global switch\n- the shared secret is stored in OS-protected credential storage on the companion side\n\nBrowser-facing pairing state should also stay origin-scoped and typed.\n\nImportant browser-visible states include:\n\n- unavailable\n- unpaired\n- pending local approval\n- paired\n- repair required because the browser-side secret is missing or unusable\n\nThat state model matters because local trust problems should surface as explicit recovery states rather than as a misleading generic \u201cnot paired\u201d result.\n\n## Pairing Management and Cancellation\n\nPairing management is intentionally narrower than routine local-drive access.\n\n- the browser should only learn the status of its own current origin\n- browser-visible paired-origin enumeration is not part of the browser contract\n- browser-managed unpairing is limited to the current origin\n- closing either pairing UI path should cancel the pending request explicitly\n\nThat last point is part of the trust model, not just a UX detail. A dismissed pairing window should not leave behind a stale approval request that can still be completed later by accident.\n\n## Trust Boundaries Contributors Must Preserve\n\n- keep the companion bound to `127.0.0.1`\n- do not relax CORS rules casually\n- do not replace exact-origin approval with hostname heuristics or silent trust-on-first-use behavior\n- keep browser-to-companion auth distinct from backend bearer-token auth\n- preserve the server-side edit-lock lifecycle for SMB-backed editing instead of letting the companion bypass it\n- keep reverse-proxy cookies distinct from Sambee bearer tokens and companion localhost pairing secrets\n- redact deep-link tokens, sessions, cookies, authorization data, and other sensitive query values before logging\n\nReverse-proxy authentication is a separate trust path from localhost pairing. The companion may use cookies captured in its own backend-origin authentication webview for Rust-side backend requests, but it must not import cookies from the user's normal browser session.\n\n## What Changes Are High Risk\n\n- anything that alters token exchange or deep-link parsing\n- anything that changes pairing confirmation rules\n- anything that weakens HMAC validation, timestamp checking, or origin scoping\n- anything that blurs the distinction between local-drive workflows and SMB-backed edit workflows\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/auth.rs` | localhost API authentication |\n| `companion/src-tauri/src/server/pairing.rs` | pairing flow and secret lifecycle |\n| `companion/src-tauri/src/uri/` and `token/` | deep-link parsing and token exchange support |\n| `frontend/src/services/companion.ts` | browser-side pairing and companion communication |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion appropriately |\n\n## Validation Expectations\n\nWhen this trust model changes, do not validate only the companion.\n\nRun at least:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\n```\n\nIf the change alters SMB edit flows, add the relevant backend checks too.\n", "1.0": "+++\ntitle = \"Browser-to-Companion Trust Model\"\n+++\n\nThe browser-to-companion boundary is powerful because it crosses from the browser app into desktop-local capability. That makes it one of the most security-sensitive parts of Sambee.\n\n## Two Distinct Trust Paths\n\nSambee uses two browser-to-companion interaction models.\n\n### Deep-Link Editing Path\n\nThis path is used when the browser asks the companion to open an SMB-backed file in a native desktop app.\n\n1. The browser asks the backend for a short-lived URI token.\n1. The browser launches a `sambee://` deep link.\n1. Companion exchanges the one-time token for a session token.\n1. Companion downloads the file, acquires the edit lock, and later uploads the result.\n\nCompanion sends the URI token to the backend token endpoint in a JSON request body. Do not reintroduce query-string token exchange compatibility; deep-link tokens are sensitive and should not be exposed in URLs, logs, proxy access logs, or browser history.\n\nThe deep-link token is not a general browser-to-companion credential. It is a short-lived bootstrap value for one native-editing handoff.\n\n### Localhost API Path\n\nThis path is used for local-drive access and related browser-to-desktop features.\n\n1. the browser probes `http://localhost:21549/api/health`\n1. browser and companion perform an explicit pairing flow for the current browser origin\n1. the browser uses authenticated localhost requests for local-drive operations\n1. the companion sends directory-change notifications over a paired WebSocket channel\n\n## Why Pairing Exists\n\nLocalhost alone is not a trust boundary.\n\nThe companion therefore requires explicit pairing and per-request authentication so that:\n\n- remote network clients cannot reach it\n- arbitrary websites cannot use it just because they run in the browser\n- local native processes do not gain the browser's paired privileges automatically\n\n## Pairing Model\n\nThe pairing flow is deliberately shaped like numeric-comparison pairing, but the important trust decision is not just \u201cdo the codes match?\u201d It is \u201cdoes the user approve this exact browser origin on this computer?\u201d\n\n- the browser and companion exchange nonces\n- both sides independently derive the same short pairing code\n- the companion displays the exact requesting browser origin in a native approval window\n- the user confirms the match in both places\n- the companion returns a shared secret only after dual confirmation succeeds\n\nThat dual confirmation step is what turns \u201csomething can reach localhost\u201d into \u201cthe user intentionally paired this browser origin with this desktop app.\u201d\n\n### Production and Development Origin Rules\n\nIn production, Companion does not rely on a preconfigured list of Sambee frontend URLs.\n\n- any valid browser origin can request pairing\n- Companion normalizes that exact origin and shows it to the user for local approval\n- once approved, that exact origin becomes the paired browser origin for future authenticated localhost requests\n\nFor development, typical loopback browser origins such as `localhost`, `127.0.0.1`, and `::1` remain usable without manual per-port configuration.\n\nThis keeps development practical without weakening the production trust boundary into hostname heuristics or silent trust-on-first-use.\n\n## Request Authentication after Pairing\n\nAfter pairing, companion-bound requests use HMAC-based authentication rather than the server's bearer-token flow.\n\n- localhost API requests carry an HMAC derived from the shared secret and a timestamp\n- the companion rejects requests outside the allowed clock window\n- pairing is tracked per browser origin, not as one global switch\n- the shared secret is stored in OS-protected credential storage on the companion side\n\nBrowser-facing pairing state should also stay origin-scoped and typed.\n\nImportant browser-visible states include:\n\n- unavailable\n- unpaired\n- pending local approval\n- paired\n- repair required because the browser-side secret is missing or unusable\n\nThat state model matters because local trust problems should surface as explicit recovery states rather than as a misleading generic \u201cnot paired\u201d result.\n\n## Pairing Management and Cancellation\n\nPairing management is intentionally narrower than routine local-drive access.\n\n- the browser should only learn the status of its own current origin\n- browser-visible paired-origin enumeration is not part of the browser contract\n- browser-managed unpairing is limited to the current origin\n- closing either pairing UI path should cancel the pending request explicitly\n\nThat last point is part of the trust model, not just a UX detail. A dismissed pairing window should not leave behind a stale approval request that can still be completed later by accident.\n\n## Trust Boundaries Contributors Must Preserve\n\n- keep the companion bound to `127.0.0.1`\n- do not relax CORS rules casually\n- do not replace exact-origin approval with hostname heuristics or silent trust-on-first-use behavior\n- keep browser-to-companion auth distinct from backend bearer-token auth\n- preserve the server-side edit-lock lifecycle for SMB-backed editing instead of letting the companion bypass it\n- keep reverse-proxy cookies distinct from Sambee bearer tokens and companion localhost pairing secrets\n- redact deep-link tokens, sessions, cookies, authorization data, and other sensitive query values before logging\n\nReverse-proxy authentication is a separate trust path from localhost pairing. The companion may use cookies captured in its own backend-origin authentication webview for Rust-side backend requests, but it must not import cookies from the user's normal browser session.\n\n## What Changes Are High Risk\n\n- anything that alters token exchange or deep-link parsing\n- anything that changes pairing confirmation rules\n- anything that weakens HMAC validation, timestamp checking, or origin scoping\n- anything that blurs the distinction between local-drive workflows and SMB-backed edit workflows\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/auth.rs` | localhost API authentication |\n| `companion/src-tauri/src/server/pairing.rs` | pairing flow and secret lifecycle |\n| `companion/src-tauri/src/uri/` and `token/` | deep-link parsing and token exchange support |\n| `frontend/src/services/companion.ts` | browser-side pairing and companion communication |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion appropriately |\n\n## Validation Expectations\n\nWhen this trust model changes, do not validate only the companion.\n\nRun at least:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\n```\n\nIf the change alters SMB edit flows, add the relevant backend checks too.\n", "2.0": "+++\ntitle = \"Browser-to-Companion Trust Model\"\n+++\n\nThe browser-to-companion boundary is powerful because it crosses from the browser app into desktop-local capability. That makes it one of the most security-sensitive parts of Sambee.\n\n## Two Distinct Trust Paths\n\nSambee uses two browser-to-companion interaction models.\n\n### Deep-Link Editing Path\n\nThis path is used when the browser asks the companion to open an SMB-backed file in a native desktop app.\n\n1. The browser asks the backend for a short-lived URI token.\n1. The browser launches a `sambee://` deep link.\n1. Companion exchanges the one-time token for a session token.\n1. Companion downloads the file, acquires the edit lock, and later uploads the result.\n\nCompanion sends the URI token to the backend token endpoint in a JSON request body. Do not reintroduce query-string token exchange compatibility; deep-link tokens are sensitive and should not be exposed in URLs, logs, proxy access logs, or browser history.\n\nThe deep-link token is not a general browser-to-companion credential. It is a short-lived bootstrap value for one native-editing handoff.\n\n### Localhost API Path\n\nThis path is used for local-drive access and related browser-to-desktop features.\n\n1. the browser probes `http://localhost:21549/api/health`\n1. browser and companion perform an explicit pairing flow for the current browser origin\n1. the browser uses authenticated localhost requests for local-drive operations\n1. the companion sends directory-change notifications over a paired WebSocket channel\n\n## Why Pairing Exists\n\nLocalhost alone is not a trust boundary.\n\nThe companion therefore requires explicit pairing and per-request authentication so that:\n\n- remote network clients cannot reach it\n- arbitrary websites cannot use it just because they run in the browser\n- local native processes do not gain the browser's paired privileges automatically\n\n## Pairing Model\n\nThe pairing flow is deliberately shaped like numeric-comparison pairing, but the important trust decision is not just \u201cdo the codes match?\u201d It is \u201cdoes the user approve this exact browser origin on this computer?\u201d\n\n- the browser and companion exchange nonces\n- both sides independently derive the same short pairing code\n- the companion displays the exact requesting browser origin in a native approval window\n- the user confirms the match in both places\n- the companion returns a shared secret only after dual confirmation succeeds\n\nThat dual confirmation step is what turns \u201csomething can reach localhost\u201d into \u201cthe user intentionally paired this browser origin with this desktop app.\u201d\n\n### Production and Development Origin Rules\n\nIn production, Companion does not rely on a preconfigured list of Sambee frontend URLs.\n\n- any valid browser origin can request pairing\n- Companion normalizes that exact origin and shows it to the user for local approval\n- once approved, that exact origin becomes the paired browser origin for future authenticated localhost requests\n\nFor development, typical loopback browser origins such as `localhost`, `127.0.0.1`, and `::1` remain usable without manual per-port configuration.\n\nThis keeps development practical without weakening the production trust boundary into hostname heuristics or silent trust-on-first-use.\n\n## Request Authentication after Pairing\n\nAfter pairing, companion-bound requests use HMAC-based authentication rather than the server's bearer-token flow.\n\n- localhost API requests carry an HMAC derived from the shared secret and a timestamp\n- the companion rejects requests outside the allowed clock window\n- pairing is tracked per browser origin, not as one global switch\n- the shared secret is stored in OS-protected credential storage on the companion side\n\nBrowser-facing pairing state should also stay origin-scoped and typed.\n\nImportant browser-visible states include:\n\n- unavailable\n- unpaired\n- pending local approval\n- paired\n- repair required because the browser-side secret is missing or unusable\n\nThat state model matters because local trust problems should surface as explicit recovery states rather than as a misleading generic \u201cnot paired\u201d result.\n\n## Pairing Management and Cancellation\n\nPairing management is intentionally narrower than routine local-drive access.\n\n- the browser should only learn the status of its own current origin\n- browser-visible paired-origin enumeration is not part of the browser contract\n- browser-managed unpairing is limited to the current origin\n- closing either pairing UI path should cancel the pending request explicitly\n\nThat last point is part of the trust model, not just a UX detail. A dismissed pairing window should not leave behind a stale approval request that can still be completed later by accident.\n\n## Trust Boundaries Contributors Must Preserve\n\n- keep the companion bound to `127.0.0.1`\n- do not relax CORS rules casually\n- do not replace exact-origin approval with hostname heuristics or silent trust-on-first-use behavior\n- keep browser-to-companion auth distinct from backend bearer-token auth\n- preserve the server-side edit-lock lifecycle for SMB-backed editing instead of letting the companion bypass it\n- keep reverse-proxy cookies distinct from Sambee bearer tokens and companion localhost pairing secrets\n- redact deep-link tokens, sessions, cookies, authorization data, and other sensitive query values before logging\n\nReverse-proxy authentication is a separate trust path from localhost pairing. The companion may use cookies captured in its own backend-origin authentication webview for Rust-side backend requests, but it must not import cookies from the user's normal browser session.\n\n## What Changes Are High Risk\n\n- anything that alters token exchange or deep-link parsing\n- anything that changes pairing confirmation rules\n- anything that weakens HMAC validation, timestamp checking, or origin scoping\n- anything that blurs the distinction between local-drive workflows and SMB-backed edit workflows\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/auth.rs` | localhost API authentication |\n| `companion/src-tauri/src/server/pairing.rs` | pairing flow and secret lifecycle |\n| `companion/src-tauri/src/uri/` and `token/` | deep-link parsing and token exchange support |\n| `frontend/src/services/companion.ts` | browser-side pairing and companion communication |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion appropriately |\n\n## Validation Expectations\n\nWhen this trust model changes, do not validate only the companion.\n\nRun at least:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\n```\n\nIf the change alters SMB edit flows, add the relevant backend checks too.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/companion-architecture/local-drive-and-save-back-pipeline", "parent_id": "section:developer-guide/companion-architecture", "depth": 2, "kind": "page", "label": "local-drive-and-save-back-pipeline", "title": "Local Drive And Save Back Pipeline", "path": "developer-guide/companion-architecture/local-drive-and-save-back-pipeline", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "branched", "source_version": "0.7", "diff_added": 16, "diff_removed": 6}, "0.9": {"state": "inherited", "source_version": "0.8"}, "1.0": {"state": "inherited", "source_version": "0.8"}, "2.0": {"state": "inherited", "source_version": "0.8"}}, "content_versions": {"0.7": "+++\ntitle = \"Local-Drive and Save-Back Pipeline\"\n+++\n\nThe companion supports two different desktop-side data paths.\n\n- paired local-drive access through the localhost API\n- SMB-backed native-app editing with temp files, locks, and explicit save-back\n\nThey are related because the same desktop app participates in both, but they do not share the same trust or data lifecycle.\n\n## Local-Drive Access Pipeline\n\nFor local drives, the browser stays in control and the companion behaves like a desktop-local backend.\n\n1. the browser detects the companion through the localhost health endpoint\n2. browser and companion pair explicitly\n3. the browser requests available drives\n4. the browser routes local-drive browse, file, and file-management requests to the companion instead of the server backend\n5. a companion-side watcher and WebSocket channel keep local directory state fresh\n\nThis is why local drives can appear inside the same UI as SMB shares while still using a different execution path.\n\n## Localhost API Shape\n\nThe companion embeds a localhost HTTP server and mirrors the backend API contract closely enough that the frontend can stay mostly connection-type agnostic.\n\nThe server is bound to `127.0.0.1:21549` and exposes routes under `/api`.\n\nRepresentative endpoints include:\n\n- `GET /api/health`: companion availability and pairing state\n- `POST /api/pair/initiate`: begin pairing\n- `POST /api/pair/confirm`: finish pairing after dual confirmation\n- `GET /api/drives`: enumerate available local drives and volumes\n- `GET /api/browse/{drive}/list`: list a directory\n- `GET /api/browse/{drive}/info`: stat one file or directory\n- `GET /api/browse/{drive}/directories`: search directories recursively\n- `GET /api/viewer/{drive}/file`: stream a file for inline viewing\n- `GET /api/viewer/{drive}/download`: stream a file as a download\n- `POST /api/browse/{drive}/upload`: upload a file into the drive-backed path\n- `DELETE /api/browse/{drive}/item`: delete a file or directory\n- `POST /api/browse/{drive}/rename`: rename a path\n- `POST /api/browse/{drive}/create`: create a file or directory\n- `POST /api/browse/{drive}/copy`: copy within or across local drives\n- `POST /api/browse/{drive}/move`: move within or across local drives\n- `WS /api/ws`: companion-side directory change notifications\n\nResponse shapes intentionally follow the backend contract so the browser can reuse models such as directory listings and file info instead of maintaining a separate local-drive UI protocol.\n\n## Local-Drive Operation Rules\n\n- the companion mirrors the backend API contract closely so the frontend can stay mostly connection-type agnostic\n- local-drive operations use desktop filesystem primitives, not SMB semantics\n- local files opened directly through the companion can skip download, lock, upload, and the \"Done Editing\" flow entirely\n\nAdditional rules that matter in practice:\n\n- image conversion is not part of the companion local-drive path; raw local files are served directly\n- local-drive browsing has no SMB edit-lock semantics\n- same-drive copy and move use local filesystem operations directly\n- cross-backend transfers between SMB and local storage are browser-mediated rather than hidden inside the companion's direct-open flow\n\nThat direct local-open path is intentionally different from SMB-backed native-app editing.\n\n## Drive Enumeration Model\n\nThe companion discovers drives and mounted volumes automatically.\n\nPlatform-specific inputs differ, but the goal is the same: expose what the current desktop user can already access through the normal filesystem.\n\n- Windows: fixed drives, removable drives, mapped drives, and virtual drives exposed through the filesystem\n- macOS: mounted volumes under the normal desktop volume model\n- Linux: mounted filesystems that represent real file content rather than pseudo-filesystems\n\nThat includes cloud-backed or virtual drives when they appear through the OS filesystem layer.\n\nThe browser therefore does not need manual drive configuration. It asks the companion for the current drive list and renders those entries alongside SMB connections.\n\nThe companion should still filter out pseudo-filesystems and other non-file mounts that would only add noise or unsafe paths.\n\n## Browser Routing and Auth Behavior\n\nThe browser uses the same UI for SMB and local drives, but the request path changes underneath.\n\n- SMB-backed requests continue through the main Sambee backend\n- local-drive requests route to the companion localhost API instead\n- the browser detects the companion through the health endpoint\n- once paired, it requests drives and merges them into the connection list as local-drive entries\n\nAuthentication also changes:\n\n- backend requests use the normal server-side auth model\n- companion requests use the pairing-derived HMAC model described in [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/)\n\nThat distinction is critical. Local-drive access is not \"server auth pointed at localhost\". It is a separate authenticated browser-to-desktop channel.\n\n## Local-Drive Watching and WebSockets\n\nThe companion keeps local directory state fresh through its own watcher and WebSocket path.\n\n- the browser opens a companion WebSocket when local-drive behavior is active\n- subscriptions are tracked per directory\n- the companion shares watcher state when possible instead of creating wasteful duplicate watchers\n- local directory changes propagate back into the same browser refresh model used by the file browser\n\nThis is why local drives can participate in the same dual-pane and refresh workflows as SMB connections without pretending the transport is the same.\n\n## SMB-Backed Native-App Save-Back Pipeline\n\nFor SMB-backed native-app editing, the companion is not the source of truth. It is the desktop-side coordinator for a backend-governed editing lifecycle.\n\n1. the browser launches a `sambee://` deep link\n2. the companion exchanges the URI token for a bootstrap token\n3. it fetches metadata and conflict baseline information\n4. it acquires the backend edit lock and receives operation-scoped lock context\n5. it downloads the file to a temp directory\n5. it opens the file in the chosen native application\n6. a \"Done Editing\" window stays open while renewal, heartbeat, and file-status checks continue in the background\n7. on explicit user confirmation, the companion uploads the file or discards it\n8. the backend lock is released and the temp file is recycled\n\n## Why Save-Back Uses Explicit Confirmation\n\nThe save-back model uses explicit user action rather than automatic filesystem watching.\n\nThat avoids a harder class of problems around:\n\n- partial writes and atomic-save behavior\n- repeated intermediate uploads\n- uncertainty about when editing is truly finished\n\nThe hold-to-confirm interaction is therefore a product decision, not just a UI quirk.\n\n## Conflict and Recovery Behavior\n\nThe companion keeps operation state because desktop editing can outlive one clean process lifecycle.\n\n- operation state is persisted alongside temp files for recovery\n- server state is checked before overwrite-sensitive upload completes\n- when server state changed during editing, the user must resolve the conflict rather than silently replacing the file\n\n## Critical Distinction Contributors Must Preserve\n\n- local-drive workflows do not use backend SMB edit locks\n- SMB-backed native-app editing does use backend lock, heartbeat, and upload semantics\n- cross-backend transfers between SMB and local storage are their own browser-mediated flow, not a shortcut through the deep-link edit lifecycle\n- localhost API pairing and HMAC auth are part of the product contract, not replaceable convenience layers\n\nIf you blur these paths, you usually break either security assumptions or data-integrity guarantees.\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/` | localhost API, drive enumeration, auth, pairing, and watcher behavior |\n| `companion/src-tauri/src/commands/open_file.rs` | download and native-app open lifecycle |\n| `companion/src-tauri/src/commands/upload.rs` | upload, lock, and heartbeat support |\n| `companion/src-tauri/src/sync/operations.rs` | operation state and recovery tracking |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion based on connection type |\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome local-drive behavior is intentionally scoped rather than incomplete by accident.\n\n- local direct-open avoids the SMB save-back lifecycle on purpose\n- raw local files are served directly instead of bundling server-style image conversion into the companion path\n- drive scope follows what the current desktop user can already access rather than inventing a separate path-allowlist model by default\n- cross-backend file movement is a separate browser-mediated path because SMB and local-drive backends do not share one native transfer primitive\n\n## Validation Expectations\n\nWhen this pipeline changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe backend checks matter whenever the change touches SMB-backed save-back, lock, heartbeat, or upload behavior.\n", "0.8": "+++\ntitle = \"Local-Drive and Save-Back Pipeline\"\n+++\n\nThe companion supports two different desktop-side data paths.\n\n- paired local-drive access through the localhost API\n- SMB-backed native-app editing with temp files, locks, and explicit save-back\n\nThey are related because the same desktop app participates in both, but they do not share the same trust or data lifecycle.\n\n## Local-Drive Access Pipeline\n\nFor local drives, the browser stays in control and the companion behaves like a desktop-local backend.\n\n1. the browser detects the companion through the localhost health endpoint\n2. browser and companion pair explicitly\n3. the browser requests available drives\n4. the browser routes local-drive browse, file, and file-management requests to the companion instead of the server backend\n5. a companion-side watcher and WebSocket channel keep local directory state fresh\n\nThis is why local drives can appear inside the same UI as SMB shares while still using a different execution path.\n\n## Localhost API Shape\n\nThe companion embeds a localhost HTTP server and mirrors the backend API contract closely enough that the frontend can stay mostly connection-type agnostic.\n\nThe server is bound to `127.0.0.1:21549` and exposes routes under `/api`.\n\nRepresentative endpoints include:\n\n- `GET /api/health`: companion availability\n- `POST /api/pair/initiate`: begin pairing\n- `POST /api/pair/confirm`: finish pairing after dual confirmation\n- `GET /api/pair/status`: origin-scoped browser pairing status\n- `POST /api/pair/cancel`: cancel a pending pairing for the current browser origin\n- `DELETE /api/pair/current`: remove the current browser origin's pairing\n- `GET /api/drives`: enumerate available local drives and volumes\n- `GET /api/browse/{drive}/list`: list a directory\n- `GET /api/browse/{drive}/info`: stat one file or directory\n- `GET /api/browse/{drive}/directories`: search directories recursively\n- `GET /api/viewer/{drive}/file`: stream a file for inline viewing\n- `GET /api/viewer/{drive}/download`: stream a file as a download\n- `POST /api/browse/{drive}/upload`: upload a file into the drive-backed path\n- `DELETE /api/browse/{drive}/item`: delete a file or directory\n- `POST /api/browse/{drive}/rename`: rename a path\n- `POST /api/browse/{drive}/create`: create a file or directory\n- `POST /api/browse/{drive}/copy`: copy within or across local drives\n- `POST /api/browse/{drive}/move`: move within or across local drives\n- `WS /api/ws`: companion-side directory change notifications\n\nResponse shapes intentionally follow the backend contract so the browser can reuse models such as directory listings and file info instead of maintaining a separate local-drive UI protocol.\n\nThe important exception is pairing state: the browser-facing pairing contract is intentionally origin-scoped and typed, rather than exposing a global paired flag or browser-visible inventory of all trusted origins.\n\n## Local-Drive Operation Rules\n\n- the companion mirrors the backend API contract closely so the frontend can stay mostly connection-type agnostic\n- local-drive operations use desktop filesystem primitives, not SMB semantics\n- local files opened directly through the companion can skip download, lock, upload, and the \"Done Editing\" flow entirely\n\nAdditional rules that matter in practice:\n\n- image conversion is not part of the companion local-drive path; raw local files are served directly\n- local-drive browsing has no SMB edit-lock semantics\n- same-drive copy and move use local filesystem operations directly\n- cross-backend transfers between SMB and local storage are browser-mediated rather than hidden inside the companion's direct-open flow\n\nThat direct local-open path is intentionally different from SMB-backed native-app editing.\n\n## Drive Enumeration Model\n\nThe companion discovers drives and mounted volumes automatically.\n\nPlatform-specific inputs differ, but the goal is the same: expose what the current desktop user can already access through the normal filesystem.\n\n- Windows: fixed drives, removable drives, mapped drives, and virtual drives exposed through the filesystem\n- macOS: mounted volumes under the normal desktop volume model\n- Linux: mounted filesystems that represent real file content rather than pseudo-filesystems\n\nThat includes cloud-backed or virtual drives when they appear through the OS filesystem layer.\n\nThe browser therefore does not need manual drive configuration. It asks the companion for the current drive list and renders those entries alongside SMB connections.\n\nThe companion should still filter out pseudo-filesystems and other non-file mounts that would only add noise or unsafe paths.\n\n## Browser Routing and Auth Behavior\n\nThe browser uses the same UI for SMB and local drives, but the request path changes underneath.\n\n- SMB-backed requests continue through the main Sambee backend\n- local-drive requests route to the companion localhost API instead\n- the browser detects the companion through the health endpoint\n- once paired, it requests drives and merges them into the connection list as local-drive entries\n\nAuthentication also changes:\n\n- backend requests use the normal server-side auth model\n- companion requests use the pairing-derived HMAC model described in [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/)\n\nThe localhost bootstrap boundary also changed in an important way:\n\n- production trust is established by exact-origin approval during pairing\n- development remains practical through loopback-origin allowance\n- browser-facing pairing management is limited to the current origin rather than arbitrary origin inventory or deletion\n\nThat distinction is critical. Local-drive access is not \"server auth pointed at localhost\". It is a separate authenticated browser-to-desktop channel.\n\n## Local-Drive Watching and WebSockets\n\nThe companion keeps local directory state fresh through its own watcher and WebSocket path.\n\n- the browser opens a companion WebSocket when local-drive behavior is active\n- subscriptions are tracked per directory\n- the companion shares watcher state when possible instead of creating wasteful duplicate watchers\n- local directory changes propagate back into the same browser refresh model used by the file browser\n\nThis is why local drives can participate in the same dual-pane and refresh workflows as SMB connections without pretending the transport is the same.\n\n## SMB-Backed Native-App Save-Back Pipeline\n\nFor SMB-backed native-app editing, the companion is not the source of truth. It is the desktop-side coordinator for a backend-governed editing lifecycle.\n\n1. the browser launches a `sambee://` deep link\n2. the companion exchanges the URI token for an authenticated session\n3. it fetches metadata and downloads the file to a temp directory\n4. it acquires the backend edit lock\n5. it opens the file in the chosen native application\n6. a \"Done Editing\" window stays open while heartbeat and file-status checks continue in the background\n7. on explicit user confirmation, the companion uploads the file or discards it\n8. the backend lock is released and the temp file is recycled\n\n## Why Save-Back Uses Explicit Confirmation\n\nThe save-back model uses explicit user action rather than automatic filesystem watching.\n\nThat avoids a harder class of problems around:\n\n- partial writes and atomic-save behavior\n- repeated intermediate uploads\n- uncertainty about when editing is truly finished\n\nThe hold-to-confirm interaction is therefore a product decision, not just a UI quirk.\n\n## Conflict and Recovery Behavior\n\nThe companion keeps operation state because desktop editing can outlive one clean process lifecycle.\n\n- operation state is persisted alongside temp files for recovery\n- server state is checked before overwrite-sensitive upload completes\n- when server state changed during editing, the user must resolve the conflict rather than silently replacing the file\n\n## Critical Distinction Contributors Must Preserve\n\n- local-drive workflows do not use backend SMB edit locks\n- SMB-backed native-app editing does use backend lock, heartbeat, and upload semantics\n- cross-backend transfers between SMB and local storage are their own browser-mediated flow, not a shortcut through the deep-link edit lifecycle\n- localhost API pairing and HMAC auth are part of the product contract, not replaceable convenience layers\n\nIf you blur these paths, you usually break either security assumptions or data-integrity guarantees.\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/` | localhost API, drive enumeration, auth, pairing, and watcher behavior |\n| `companion/src-tauri/src/commands/open_file.rs` | download and native-app open lifecycle |\n| `companion/src-tauri/src/commands/upload.rs` | upload, lock, and heartbeat support |\n| `companion/src-tauri/src/sync/operations.rs` | operation state and recovery tracking |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion based on connection type |\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome local-drive behavior is intentionally scoped rather than incomplete by accident.\n\n- local direct-open avoids the SMB save-back lifecycle on purpose\n- raw local files are served directly instead of bundling server-style image conversion into the companion path\n- drive scope follows what the current desktop user can already access rather than inventing a separate path-allowlist model by default\n- cross-backend file movement is a separate browser-mediated path because SMB and local-drive backends do not share one native transfer primitive\n\n## Validation Expectations\n\nWhen this pipeline changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe backend checks matter whenever the change touches SMB-backed save-back, lock, heartbeat, or upload behavior.\n", "0.9": "+++\ntitle = \"Local-Drive and Save-Back Pipeline\"\n+++\n\nThe companion supports two different desktop-side data paths.\n\n- paired local-drive access through the localhost API\n- SMB-backed native-app editing with temp files, locks, and explicit save-back\n\nThey are related because the same desktop app participates in both, but they do not share the same trust or data lifecycle.\n\n## Local-Drive Access Pipeline\n\nFor local drives, the browser stays in control and the companion behaves like a desktop-local backend.\n\n1. the browser detects the companion through the localhost health endpoint\n2. browser and companion pair explicitly\n3. the browser requests available drives\n4. the browser routes local-drive browse, file, and file-management requests to the companion instead of the server backend\n5. a companion-side watcher and WebSocket channel keep local directory state fresh\n\nThis is why local drives can appear inside the same UI as SMB shares while still using a different execution path.\n\n## Localhost API Shape\n\nThe companion embeds a localhost HTTP server and mirrors the backend API contract closely enough that the frontend can stay mostly connection-type agnostic.\n\nThe server is bound to `127.0.0.1:21549` and exposes routes under `/api`.\n\nRepresentative endpoints include:\n\n- `GET /api/health`: companion availability\n- `POST /api/pair/initiate`: begin pairing\n- `POST /api/pair/confirm`: finish pairing after dual confirmation\n- `GET /api/pair/status`: origin-scoped browser pairing status\n- `POST /api/pair/cancel`: cancel a pending pairing for the current browser origin\n- `DELETE /api/pair/current`: remove the current browser origin's pairing\n- `GET /api/drives`: enumerate available local drives and volumes\n- `GET /api/browse/{drive}/list`: list a directory\n- `GET /api/browse/{drive}/info`: stat one file or directory\n- `GET /api/browse/{drive}/directories`: search directories recursively\n- `GET /api/viewer/{drive}/file`: stream a file for inline viewing\n- `GET /api/viewer/{drive}/download`: stream a file as a download\n- `POST /api/browse/{drive}/upload`: upload a file into the drive-backed path\n- `DELETE /api/browse/{drive}/item`: delete a file or directory\n- `POST /api/browse/{drive}/rename`: rename a path\n- `POST /api/browse/{drive}/create`: create a file or directory\n- `POST /api/browse/{drive}/copy`: copy within or across local drives\n- `POST /api/browse/{drive}/move`: move within or across local drives\n- `WS /api/ws`: companion-side directory change notifications\n\nResponse shapes intentionally follow the backend contract so the browser can reuse models such as directory listings and file info instead of maintaining a separate local-drive UI protocol.\n\nThe important exception is pairing state: the browser-facing pairing contract is intentionally origin-scoped and typed, rather than exposing a global paired flag or browser-visible inventory of all trusted origins.\n\n## Local-Drive Operation Rules\n\n- the companion mirrors the backend API contract closely so the frontend can stay mostly connection-type agnostic\n- local-drive operations use desktop filesystem primitives, not SMB semantics\n- local files opened directly through the companion can skip download, lock, upload, and the \"Done Editing\" flow entirely\n\nAdditional rules that matter in practice:\n\n- image conversion is not part of the companion local-drive path; raw local files are served directly\n- local-drive browsing has no SMB edit-lock semantics\n- same-drive copy and move use local filesystem operations directly\n- cross-backend transfers between SMB and local storage are browser-mediated rather than hidden inside the companion's direct-open flow\n\nThat direct local-open path is intentionally different from SMB-backed native-app editing.\n\n## Drive Enumeration Model\n\nThe companion discovers drives and mounted volumes automatically.\n\nPlatform-specific inputs differ, but the goal is the same: expose what the current desktop user can already access through the normal filesystem.\n\n- Windows: fixed drives, removable drives, mapped drives, and virtual drives exposed through the filesystem\n- macOS: mounted volumes under the normal desktop volume model\n- Linux: mounted filesystems that represent real file content rather than pseudo-filesystems\n\nThat includes cloud-backed or virtual drives when they appear through the OS filesystem layer.\n\nThe browser therefore does not need manual drive configuration. It asks the companion for the current drive list and renders those entries alongside SMB connections.\n\nThe companion should still filter out pseudo-filesystems and other non-file mounts that would only add noise or unsafe paths.\n\n## Browser Routing and Auth Behavior\n\nThe browser uses the same UI for SMB and local drives, but the request path changes underneath.\n\n- SMB-backed requests continue through the main Sambee backend\n- local-drive requests route to the companion localhost API instead\n- the browser detects the companion through the health endpoint\n- once paired, it requests drives and merges them into the connection list as local-drive entries\n\nAuthentication also changes:\n\n- backend requests use the normal server-side auth model\n- companion requests use the pairing-derived HMAC model described in [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/)\n\nThe localhost bootstrap boundary also changed in an important way:\n\n- production trust is established by exact-origin approval during pairing\n- development remains practical through loopback-origin allowance\n- browser-facing pairing management is limited to the current origin rather than arbitrary origin inventory or deletion\n\nThat distinction is critical. Local-drive access is not \"server auth pointed at localhost\". It is a separate authenticated browser-to-desktop channel.\n\n## Local-Drive Watching and WebSockets\n\nThe companion keeps local directory state fresh through its own watcher and WebSocket path.\n\n- the browser opens a companion WebSocket when local-drive behavior is active\n- subscriptions are tracked per directory\n- the companion shares watcher state when possible instead of creating wasteful duplicate watchers\n- local directory changes propagate back into the same browser refresh model used by the file browser\n\nThis is why local drives can participate in the same dual-pane and refresh workflows as SMB connections without pretending the transport is the same.\n\n## SMB-Backed Native-App Save-Back Pipeline\n\nFor SMB-backed native-app editing, the companion is not the source of truth. It is the desktop-side coordinator for a backend-governed editing lifecycle.\n\n1. the browser launches a `sambee://` deep link\n2. the companion exchanges the URI token for an authenticated session\n3. it fetches metadata and downloads the file to a temp directory\n4. it acquires the backend edit lock\n5. it opens the file in the chosen native application\n6. a \"Done Editing\" window stays open while heartbeat and file-status checks continue in the background\n7. on explicit user confirmation, the companion uploads the file or discards it\n8. the backend lock is released and the temp file is recycled\n\n## Why Save-Back Uses Explicit Confirmation\n\nThe save-back model uses explicit user action rather than automatic filesystem watching.\n\nThat avoids a harder class of problems around:\n\n- partial writes and atomic-save behavior\n- repeated intermediate uploads\n- uncertainty about when editing is truly finished\n\nThe hold-to-confirm interaction is therefore a product decision, not just a UI quirk.\n\n## Conflict and Recovery Behavior\n\nThe companion keeps operation state because desktop editing can outlive one clean process lifecycle.\n\n- operation state is persisted alongside temp files for recovery\n- server state is checked before overwrite-sensitive upload completes\n- when server state changed during editing, the user must resolve the conflict rather than silently replacing the file\n\n## Critical Distinction Contributors Must Preserve\n\n- local-drive workflows do not use backend SMB edit locks\n- SMB-backed native-app editing does use backend lock, heartbeat, and upload semantics\n- cross-backend transfers between SMB and local storage are their own browser-mediated flow, not a shortcut through the deep-link edit lifecycle\n- localhost API pairing and HMAC auth are part of the product contract, not replaceable convenience layers\n\nIf you blur these paths, you usually break either security assumptions or data-integrity guarantees.\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/` | localhost API, drive enumeration, auth, pairing, and watcher behavior |\n| `companion/src-tauri/src/commands/open_file.rs` | download and native-app open lifecycle |\n| `companion/src-tauri/src/commands/upload.rs` | upload, lock, and heartbeat support |\n| `companion/src-tauri/src/sync/operations.rs` | operation state and recovery tracking |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion based on connection type |\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome local-drive behavior is intentionally scoped rather than incomplete by accident.\n\n- local direct-open avoids the SMB save-back lifecycle on purpose\n- raw local files are served directly instead of bundling server-style image conversion into the companion path\n- drive scope follows what the current desktop user can already access rather than inventing a separate path-allowlist model by default\n- cross-backend file movement is a separate browser-mediated path because SMB and local-drive backends do not share one native transfer primitive\n\n## Validation Expectations\n\nWhen this pipeline changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe backend checks matter whenever the change touches SMB-backed save-back, lock, heartbeat, or upload behavior.\n", "1.0": "+++\ntitle = \"Local-Drive and Save-Back Pipeline\"\n+++\n\nThe companion supports two different desktop-side data paths.\n\n- paired local-drive access through the localhost API\n- SMB-backed native-app editing with temp files, locks, and explicit save-back\n\nThey are related because the same desktop app participates in both, but they do not share the same trust or data lifecycle.\n\n## Local-Drive Access Pipeline\n\nFor local drives, the browser stays in control and the companion behaves like a desktop-local backend.\n\n1. the browser detects the companion through the localhost health endpoint\n2. browser and companion pair explicitly\n3. the browser requests available drives\n4. the browser routes local-drive browse, file, and file-management requests to the companion instead of the server backend\n5. a companion-side watcher and WebSocket channel keep local directory state fresh\n\nThis is why local drives can appear inside the same UI as SMB shares while still using a different execution path.\n\n## Localhost API Shape\n\nThe companion embeds a localhost HTTP server and mirrors the backend API contract closely enough that the frontend can stay mostly connection-type agnostic.\n\nThe server is bound to `127.0.0.1:21549` and exposes routes under `/api`.\n\nRepresentative endpoints include:\n\n- `GET /api/health`: companion availability\n- `POST /api/pair/initiate`: begin pairing\n- `POST /api/pair/confirm`: finish pairing after dual confirmation\n- `GET /api/pair/status`: origin-scoped browser pairing status\n- `POST /api/pair/cancel`: cancel a pending pairing for the current browser origin\n- `DELETE /api/pair/current`: remove the current browser origin's pairing\n- `GET /api/drives`: enumerate available local drives and volumes\n- `GET /api/browse/{drive}/list`: list a directory\n- `GET /api/browse/{drive}/info`: stat one file or directory\n- `GET /api/browse/{drive}/directories`: search directories recursively\n- `GET /api/viewer/{drive}/file`: stream a file for inline viewing\n- `GET /api/viewer/{drive}/download`: stream a file as a download\n- `POST /api/browse/{drive}/upload`: upload a file into the drive-backed path\n- `DELETE /api/browse/{drive}/item`: delete a file or directory\n- `POST /api/browse/{drive}/rename`: rename a path\n- `POST /api/browse/{drive}/create`: create a file or directory\n- `POST /api/browse/{drive}/copy`: copy within or across local drives\n- `POST /api/browse/{drive}/move`: move within or across local drives\n- `WS /api/ws`: companion-side directory change notifications\n\nResponse shapes intentionally follow the backend contract so the browser can reuse models such as directory listings and file info instead of maintaining a separate local-drive UI protocol.\n\nThe important exception is pairing state: the browser-facing pairing contract is intentionally origin-scoped and typed, rather than exposing a global paired flag or browser-visible inventory of all trusted origins.\n\n## Local-Drive Operation Rules\n\n- the companion mirrors the backend API contract closely so the frontend can stay mostly connection-type agnostic\n- local-drive operations use desktop filesystem primitives, not SMB semantics\n- local files opened directly through the companion can skip download, lock, upload, and the \"Done Editing\" flow entirely\n\nAdditional rules that matter in practice:\n\n- image conversion is not part of the companion local-drive path; raw local files are served directly\n- local-drive browsing has no SMB edit-lock semantics\n- same-drive copy and move use local filesystem operations directly\n- cross-backend transfers between SMB and local storage are browser-mediated rather than hidden inside the companion's direct-open flow\n\nThat direct local-open path is intentionally different from SMB-backed native-app editing.\n\n## Drive Enumeration Model\n\nThe companion discovers drives and mounted volumes automatically.\n\nPlatform-specific inputs differ, but the goal is the same: expose what the current desktop user can already access through the normal filesystem.\n\n- Windows: fixed drives, removable drives, mapped drives, and virtual drives exposed through the filesystem\n- macOS: mounted volumes under the normal desktop volume model\n- Linux: mounted filesystems that represent real file content rather than pseudo-filesystems\n\nThat includes cloud-backed or virtual drives when they appear through the OS filesystem layer.\n\nThe browser therefore does not need manual drive configuration. It asks the companion for the current drive list and renders those entries alongside SMB connections.\n\nThe companion should still filter out pseudo-filesystems and other non-file mounts that would only add noise or unsafe paths.\n\n## Browser Routing and Auth Behavior\n\nThe browser uses the same UI for SMB and local drives, but the request path changes underneath.\n\n- SMB-backed requests continue through the main Sambee backend\n- local-drive requests route to the companion localhost API instead\n- the browser detects the companion through the health endpoint\n- once paired, it requests drives and merges them into the connection list as local-drive entries\n\nAuthentication also changes:\n\n- backend requests use the normal server-side auth model\n- companion requests use the pairing-derived HMAC model described in [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/)\n\nThe localhost bootstrap boundary also changed in an important way:\n\n- production trust is established by exact-origin approval during pairing\n- development remains practical through loopback-origin allowance\n- browser-facing pairing management is limited to the current origin rather than arbitrary origin inventory or deletion\n\nThat distinction is critical. Local-drive access is not \"server auth pointed at localhost\". It is a separate authenticated browser-to-desktop channel.\n\n## Local-Drive Watching and WebSockets\n\nThe companion keeps local directory state fresh through its own watcher and WebSocket path.\n\n- the browser opens a companion WebSocket when local-drive behavior is active\n- subscriptions are tracked per directory\n- the companion shares watcher state when possible instead of creating wasteful duplicate watchers\n- local directory changes propagate back into the same browser refresh model used by the file browser\n\nThis is why local drives can participate in the same dual-pane and refresh workflows as SMB connections without pretending the transport is the same.\n\n## SMB-Backed Native-App Save-Back Pipeline\n\nFor SMB-backed native-app editing, the companion is not the source of truth. It is the desktop-side coordinator for a backend-governed editing lifecycle.\n\n1. the browser launches a `sambee://` deep link\n2. the companion exchanges the URI token for an authenticated session\n3. it fetches metadata and downloads the file to a temp directory\n4. it acquires the backend edit lock\n5. it opens the file in the chosen native application\n6. a \"Done Editing\" window stays open while heartbeat and file-status checks continue in the background\n7. on explicit user confirmation, the companion uploads the file or discards it\n8. the backend lock is released and the temp file is recycled\n\n## Why Save-Back Uses Explicit Confirmation\n\nThe save-back model uses explicit user action rather than automatic filesystem watching.\n\nThat avoids a harder class of problems around:\n\n- partial writes and atomic-save behavior\n- repeated intermediate uploads\n- uncertainty about when editing is truly finished\n\nThe hold-to-confirm interaction is therefore a product decision, not just a UI quirk.\n\n## Conflict and Recovery Behavior\n\nThe companion keeps operation state because desktop editing can outlive one clean process lifecycle.\n\n- operation state is persisted alongside temp files for recovery\n- server state is checked before overwrite-sensitive upload completes\n- when server state changed during editing, the user must resolve the conflict rather than silently replacing the file\n\n## Critical Distinction Contributors Must Preserve\n\n- local-drive workflows do not use backend SMB edit locks\n- SMB-backed native-app editing does use backend lock, heartbeat, and upload semantics\n- cross-backend transfers between SMB and local storage are their own browser-mediated flow, not a shortcut through the deep-link edit lifecycle\n- localhost API pairing and HMAC auth are part of the product contract, not replaceable convenience layers\n\nIf you blur these paths, you usually break either security assumptions or data-integrity guarantees.\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/` | localhost API, drive enumeration, auth, pairing, and watcher behavior |\n| `companion/src-tauri/src/commands/open_file.rs` | download and native-app open lifecycle |\n| `companion/src-tauri/src/commands/upload.rs` | upload, lock, and heartbeat support |\n| `companion/src-tauri/src/sync/operations.rs` | operation state and recovery tracking |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion based on connection type |\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome local-drive behavior is intentionally scoped rather than incomplete by accident.\n\n- local direct-open avoids the SMB save-back lifecycle on purpose\n- raw local files are served directly instead of bundling server-style image conversion into the companion path\n- drive scope follows what the current desktop user can already access rather than inventing a separate path-allowlist model by default\n- cross-backend file movement is a separate browser-mediated path because SMB and local-drive backends do not share one native transfer primitive\n\n## Validation Expectations\n\nWhen this pipeline changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe backend checks matter whenever the change touches SMB-backed save-back, lock, heartbeat, or upload behavior.\n", "2.0": "+++\ntitle = \"Local-Drive and Save-Back Pipeline\"\n+++\n\nThe companion supports two different desktop-side data paths.\n\n- paired local-drive access through the localhost API\n- SMB-backed native-app editing with temp files, locks, and explicit save-back\n\nThey are related because the same desktop app participates in both, but they do not share the same trust or data lifecycle.\n\n## Local-Drive Access Pipeline\n\nFor local drives, the browser stays in control and the companion behaves like a desktop-local backend.\n\n1. the browser detects the companion through the localhost health endpoint\n2. browser and companion pair explicitly\n3. the browser requests available drives\n4. the browser routes local-drive browse, file, and file-management requests to the companion instead of the server backend\n5. a companion-side watcher and WebSocket channel keep local directory state fresh\n\nThis is why local drives can appear inside the same UI as SMB shares while still using a different execution path.\n\n## Localhost API Shape\n\nThe companion embeds a localhost HTTP server and mirrors the backend API contract closely enough that the frontend can stay mostly connection-type agnostic.\n\nThe server is bound to `127.0.0.1:21549` and exposes routes under `/api`.\n\nRepresentative endpoints include:\n\n- `GET /api/health`: companion availability\n- `POST /api/pair/initiate`: begin pairing\n- `POST /api/pair/confirm`: finish pairing after dual confirmation\n- `GET /api/pair/status`: origin-scoped browser pairing status\n- `POST /api/pair/cancel`: cancel a pending pairing for the current browser origin\n- `DELETE /api/pair/current`: remove the current browser origin's pairing\n- `GET /api/drives`: enumerate available local drives and volumes\n- `GET /api/browse/{drive}/list`: list a directory\n- `GET /api/browse/{drive}/info`: stat one file or directory\n- `GET /api/browse/{drive}/directories`: search directories recursively\n- `GET /api/viewer/{drive}/file`: stream a file for inline viewing\n- `GET /api/viewer/{drive}/download`: stream a file as a download\n- `POST /api/browse/{drive}/upload`: upload a file into the drive-backed path\n- `DELETE /api/browse/{drive}/item`: delete a file or directory\n- `POST /api/browse/{drive}/rename`: rename a path\n- `POST /api/browse/{drive}/create`: create a file or directory\n- `POST /api/browse/{drive}/copy`: copy within or across local drives\n- `POST /api/browse/{drive}/move`: move within or across local drives\n- `WS /api/ws`: companion-side directory change notifications\n\nResponse shapes intentionally follow the backend contract so the browser can reuse models such as directory listings and file info instead of maintaining a separate local-drive UI protocol.\n\nThe important exception is pairing state: the browser-facing pairing contract is intentionally origin-scoped and typed, rather than exposing a global paired flag or browser-visible inventory of all trusted origins.\n\n## Local-Drive Operation Rules\n\n- the companion mirrors the backend API contract closely so the frontend can stay mostly connection-type agnostic\n- local-drive operations use desktop filesystem primitives, not SMB semantics\n- local files opened directly through the companion can skip download, lock, upload, and the \"Done Editing\" flow entirely\n\nAdditional rules that matter in practice:\n\n- image conversion is not part of the companion local-drive path; raw local files are served directly\n- local-drive browsing has no SMB edit-lock semantics\n- same-drive copy and move use local filesystem operations directly\n- cross-backend transfers between SMB and local storage are browser-mediated rather than hidden inside the companion's direct-open flow\n\nThat direct local-open path is intentionally different from SMB-backed native-app editing.\n\n## Drive Enumeration Model\n\nThe companion discovers drives and mounted volumes automatically.\n\nPlatform-specific inputs differ, but the goal is the same: expose what the current desktop user can already access through the normal filesystem.\n\n- Windows: fixed drives, removable drives, mapped drives, and virtual drives exposed through the filesystem\n- macOS: mounted volumes under the normal desktop volume model\n- Linux: mounted filesystems that represent real file content rather than pseudo-filesystems\n\nThat includes cloud-backed or virtual drives when they appear through the OS filesystem layer.\n\nThe browser therefore does not need manual drive configuration. It asks the companion for the current drive list and renders those entries alongside SMB connections.\n\nThe companion should still filter out pseudo-filesystems and other non-file mounts that would only add noise or unsafe paths.\n\n## Browser Routing and Auth Behavior\n\nThe browser uses the same UI for SMB and local drives, but the request path changes underneath.\n\n- SMB-backed requests continue through the main Sambee backend\n- local-drive requests route to the companion localhost API instead\n- the browser detects the companion through the health endpoint\n- once paired, it requests drives and merges them into the connection list as local-drive entries\n\nAuthentication also changes:\n\n- backend requests use the normal server-side auth model\n- companion requests use the pairing-derived HMAC model described in [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/)\n\nThe localhost bootstrap boundary also changed in an important way:\n\n- production trust is established by exact-origin approval during pairing\n- development remains practical through loopback-origin allowance\n- browser-facing pairing management is limited to the current origin rather than arbitrary origin inventory or deletion\n\nThat distinction is critical. Local-drive access is not \"server auth pointed at localhost\". It is a separate authenticated browser-to-desktop channel.\n\n## Local-Drive Watching and WebSockets\n\nThe companion keeps local directory state fresh through its own watcher and WebSocket path.\n\n- the browser opens a companion WebSocket when local-drive behavior is active\n- subscriptions are tracked per directory\n- the companion shares watcher state when possible instead of creating wasteful duplicate watchers\n- local directory changes propagate back into the same browser refresh model used by the file browser\n\nThis is why local drives can participate in the same dual-pane and refresh workflows as SMB connections without pretending the transport is the same.\n\n## SMB-Backed Native-App Save-Back Pipeline\n\nFor SMB-backed native-app editing, the companion is not the source of truth. It is the desktop-side coordinator for a backend-governed editing lifecycle.\n\n1. the browser launches a `sambee://` deep link\n2. the companion exchanges the URI token for an authenticated session\n3. it fetches metadata and downloads the file to a temp directory\n4. it acquires the backend edit lock\n5. it opens the file in the chosen native application\n6. a \"Done Editing\" window stays open while heartbeat and file-status checks continue in the background\n7. on explicit user confirmation, the companion uploads the file or discards it\n8. the backend lock is released and the temp file is recycled\n\n## Why Save-Back Uses Explicit Confirmation\n\nThe save-back model uses explicit user action rather than automatic filesystem watching.\n\nThat avoids a harder class of problems around:\n\n- partial writes and atomic-save behavior\n- repeated intermediate uploads\n- uncertainty about when editing is truly finished\n\nThe hold-to-confirm interaction is therefore a product decision, not just a UI quirk.\n\n## Conflict and Recovery Behavior\n\nThe companion keeps operation state because desktop editing can outlive one clean process lifecycle.\n\n- operation state is persisted alongside temp files for recovery\n- server state is checked before overwrite-sensitive upload completes\n- when server state changed during editing, the user must resolve the conflict rather than silently replacing the file\n\n## Critical Distinction Contributors Must Preserve\n\n- local-drive workflows do not use backend SMB edit locks\n- SMB-backed native-app editing does use backend lock, heartbeat, and upload semantics\n- cross-backend transfers between SMB and local storage are their own browser-mediated flow, not a shortcut through the deep-link edit lifecycle\n- localhost API pairing and HMAC auth are part of the product contract, not replaceable convenience layers\n\nIf you blur these paths, you usually break either security assumptions or data-integrity guarantees.\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/` | localhost API, drive enumeration, auth, pairing, and watcher behavior |\n| `companion/src-tauri/src/commands/open_file.rs` | download and native-app open lifecycle |\n| `companion/src-tauri/src/commands/upload.rs` | upload, lock, and heartbeat support |\n| `companion/src-tauri/src/sync/operations.rs` | operation state and recovery tracking |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion based on connection type |\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome local-drive behavior is intentionally scoped rather than incomplete by accident.\n\n- local direct-open avoids the SMB save-back lifecycle on purpose\n- raw local files are served directly instead of bundling server-style image conversion into the companion path\n- drive scope follows what the current desktop user can already access rather than inventing a separate path-allowlist model by default\n- cross-backend file movement is a separate browser-mediated path because SMB and local-drive backends do not share one native transfer primitive\n\n## Validation Expectations\n\nWhen this pipeline changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe backend checks matter whenever the change touches SMB-backed save-back, lock, heartbeat, or upload behavior.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Local-Drive and Save-Back Pipeline\"\n+++\n\nThe companion supports two different desktop-side data paths.\n\n- paired local-drive access through the localhost API\n- SMB-backed native-app editing with temp files, locks, and explicit save-back\n\nThey are related because the same desktop app participates in both, but they do not share the same trust or data lifecycle.\n\n## Local-Drive Access Pipeline\n\nFor local drives, the browser stays in control and the companion behaves like a desktop-local backend.\n\n1. the browser detects the companion through the localhost health endpoint\n2. browser and companion pair explicitly\n3. the browser requests available drives\n4. the browser routes local-drive browse, file, and file-management requests to the companion instead of the server backend\n5. a companion-side watcher and WebSocket channel keep local directory state fresh\n\nThis is why local drives can appear inside the same UI as SMB shares while still using a different execution path.\n\n## Localhost API Shape\n\nThe companion embeds a localhost HTTP server and mirrors the backend API contract closely enough that the frontend can stay mostly connection-type agnostic.\n\nThe server is bound to `127.0.0.1:21549` and exposes routes under `/api`.\n\nRepresentative endpoints include:\n\n- `GET /api/health`: companion availability and pairing state\n- `POST /api/pair/initiate`: begin pairing\n- `POST /api/pair/confirm`: finish pairing after dual confirmation\n- `GET /api/drives`: enumerate available local drives and volumes\n- `GET /api/browse/{drive}/list`: list a directory\n- `GET /api/browse/{drive}/info`: stat one file or directory\n- `GET /api/browse/{drive}/directories`: search directories recursively\n- `GET /api/viewer/{drive}/file`: stream a file for inline viewing\n- `GET /api/viewer/{drive}/download`: stream a file as a download\n- `POST /api/browse/{drive}/upload`: upload a file into the drive-backed path\n- `DELETE /api/browse/{drive}/item`: delete a file or directory\n- `POST /api/browse/{drive}/rename`: rename a path\n- `POST /api/browse/{drive}/create`: create a file or directory\n- `POST /api/browse/{drive}/copy`: copy within or across local drives\n- `POST /api/browse/{drive}/move`: move within or across local drives\n- `WS /api/ws`: companion-side directory change notifications\n\nResponse shapes intentionally follow the backend contract so the browser can reuse models such as directory listings and file info instead of maintaining a separate local-drive UI protocol.\n\n## Local-Drive Operation Rules\n\n- the companion mirrors the backend API contract closely so the frontend can stay mostly connection-type agnostic\n- local-drive operations use desktop filesystem primitives, not SMB semantics\n- local files opened directly through the companion can skip download, lock, upload, and the \"Done Editing\" flow entirely\n\nAdditional rules that matter in practice:\n\n- image conversion is not part of the companion local-drive path; raw local files are served directly\n- local-drive browsing has no SMB edit-lock semantics\n- same-drive copy and move use local filesystem operations directly\n- cross-backend transfers between SMB and local storage are browser-mediated rather than hidden inside the companion's direct-open flow\n\nThat direct local-open path is intentionally different from SMB-backed native-app editing.\n\n## Drive Enumeration Model\n\nThe companion discovers drives and mounted volumes automatically.\n\nPlatform-specific inputs differ, but the goal is the same: expose what the current desktop user can already access through the normal filesystem.\n\n- Windows: fixed drives, removable drives, mapped drives, and virtual drives exposed through the filesystem\n- macOS: mounted volumes under the normal desktop volume model\n- Linux: mounted filesystems that represent real file content rather than pseudo-filesystems\n\nThat includes cloud-backed or virtual drives when they appear through the OS filesystem layer.\n\nThe browser therefore does not need manual drive configuration. It asks the companion for the current drive list and renders those entries alongside SMB connections.\n\nThe companion should still filter out pseudo-filesystems and other non-file mounts that would only add noise or unsafe paths.\n\n## Browser Routing and Auth Behavior\n\nThe browser uses the same UI for SMB and local drives, but the request path changes underneath.\n\n- SMB-backed requests continue through the main Sambee backend\n- local-drive requests route to the companion localhost API instead\n- the browser detects the companion through the health endpoint\n- once paired, it requests drives and merges them into the connection list as local-drive entries\n\nAuthentication also changes:\n\n- backend requests use the normal server-side auth model\n- companion requests use the pairing-derived HMAC model described in [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/)\n\nThat distinction is critical. Local-drive access is not \"server auth pointed at localhost\". It is a separate authenticated browser-to-desktop channel.\n\n## Local-Drive Watching and WebSockets\n\nThe companion keeps local directory state fresh through its own watcher and WebSocket path.\n\n- the browser opens a companion WebSocket when local-drive behavior is active\n- subscriptions are tracked per directory\n- the companion shares watcher state when possible instead of creating wasteful duplicate watchers\n- local directory changes propagate back into the same browser refresh model used by the file browser\n\nThis is why local drives can participate in the same dual-pane and refresh workflows as SMB connections without pretending the transport is the same.\n\n## SMB-Backed Native-App Save-Back Pipeline\n\nFor SMB-backed native-app editing, the companion is not the source of truth. It is the desktop-side coordinator for a backend-governed editing lifecycle.\n\n1. the browser launches a `sambee://` deep link\n2. the companion exchanges the URI token for a bootstrap token\n3. it fetches metadata and conflict baseline information\n4. it acquires the backend edit lock and receives operation-scoped lock context\n5. it downloads the file to a temp directory\n5. it opens the file in the chosen native application\n6. a \"Done Editing\" window stays open while renewal, heartbeat, and file-status checks continue in the background\n7. on explicit user confirmation, the companion uploads the file or discards it\n8. the backend lock is released and the temp file is recycled\n\n## Why Save-Back Uses Explicit Confirmation\n\nThe save-back model uses explicit user action rather than automatic filesystem watching.\n\nThat avoids a harder class of problems around:\n\n- partial writes and atomic-save behavior\n- repeated intermediate uploads\n- uncertainty about when editing is truly finished\n\nThe hold-to-confirm interaction is therefore a product decision, not just a UI quirk.\n\n## Conflict and Recovery Behavior\n\nThe companion keeps operation state because desktop editing can outlive one clean process lifecycle.\n\n- operation state is persisted alongside temp files for recovery\n- server state is checked before overwrite-sensitive upload completes\n- when server state changed during editing, the user must resolve the conflict rather than silently replacing the file\n\n## Critical Distinction Contributors Must Preserve\n\n- local-drive workflows do not use backend SMB edit locks\n- SMB-backed native-app editing does use backend lock, heartbeat, and upload semantics\n- cross-backend transfers between SMB and local storage are their own browser-mediated flow, not a shortcut through the deep-link edit lifecycle\n- localhost API pairing and HMAC auth are part of the product contract, not replaceable convenience layers\n\nIf you blur these paths, you usually break either security assumptions or data-integrity guarantees.\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/` | localhost API, drive enumeration, auth, pairing, and watcher behavior |\n| `companion/src-tauri/src/commands/open_file.rs` | download and native-app open lifecycle |\n| `companion/src-tauri/src/commands/upload.rs` | upload, lock, and heartbeat support |\n| `companion/src-tauri/src/sync/operations.rs` | operation state and recovery tracking |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion based on connection type |\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome local-drive behavior is intentionally scoped rather than incomplete by accident.\n\n- local direct-open avoids the SMB save-back lifecycle on purpose\n- raw local files are served directly instead of bundling server-style image conversion into the companion path\n- drive scope follows what the current desktop user can already access rather than inventing a separate path-allowlist model by default\n- cross-backend file movement is a separate browser-mediated path because SMB and local-drive backends do not share one native transfer primitive\n\n## Validation Expectations\n\nWhen this pipeline changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe backend checks matter whenever the change touches SMB-backed save-back, lock, heartbeat, or upload behavior.\n", "0.8": "+++\ntitle = \"Local-Drive and Save-Back Pipeline\"\n+++\n\nThe companion supports two different desktop-side data paths.\n\n- paired local-drive access through the localhost API\n- SMB-backed native-app editing with temp files, locks, and explicit save-back\n\nThey are related because the same desktop app participates in both, but they do not share the same trust or data lifecycle.\n\n## Local-Drive Access Pipeline\n\nFor local drives, the browser stays in control and the companion behaves like a desktop-local backend.\n\n1. the browser detects the companion through the localhost health endpoint\n2. browser and companion pair explicitly\n3. the browser requests available drives\n4. the browser routes local-drive browse, file, and file-management requests to the companion instead of the server backend\n5. a companion-side watcher and WebSocket channel keep local directory state fresh\n\nThis is why local drives can appear inside the same UI as SMB shares while still using a different execution path.\n\n## Localhost API Shape\n\nThe companion embeds a localhost HTTP server and mirrors the backend API contract closely enough that the frontend can stay mostly connection-type agnostic.\n\nThe server is bound to `127.0.0.1:21549` and exposes routes under `/api`.\n\nRepresentative endpoints include:\n\n- `GET /api/health`: companion availability\n- `POST /api/pair/initiate`: begin pairing\n- `POST /api/pair/confirm`: finish pairing after dual confirmation\n- `GET /api/pair/status`: origin-scoped browser pairing status\n- `POST /api/pair/cancel`: cancel a pending pairing for the current browser origin\n- `DELETE /api/pair/current`: remove the current browser origin's pairing\n- `GET /api/drives`: enumerate available local drives and volumes\n- `GET /api/browse/{drive}/list`: list a directory\n- `GET /api/browse/{drive}/info`: stat one file or directory\n- `GET /api/browse/{drive}/directories`: search directories recursively\n- `GET /api/viewer/{drive}/file`: stream a file for inline viewing\n- `GET /api/viewer/{drive}/download`: stream a file as a download\n- `POST /api/browse/{drive}/upload`: upload a file into the drive-backed path\n- `DELETE /api/browse/{drive}/item`: delete a file or directory\n- `POST /api/browse/{drive}/rename`: rename a path\n- `POST /api/browse/{drive}/create`: create a file or directory\n- `POST /api/browse/{drive}/copy`: copy within or across local drives\n- `POST /api/browse/{drive}/move`: move within or across local drives\n- `WS /api/ws`: companion-side directory change notifications\n\nResponse shapes intentionally follow the backend contract so the browser can reuse models such as directory listings and file info instead of maintaining a separate local-drive UI protocol.\n\nThe important exception is pairing state: the browser-facing pairing contract is intentionally origin-scoped and typed, rather than exposing a global paired flag or browser-visible inventory of all trusted origins.\n\n## Local-Drive Operation Rules\n\n- the companion mirrors the backend API contract closely so the frontend can stay mostly connection-type agnostic\n- local-drive operations use desktop filesystem primitives, not SMB semantics\n- local files opened directly through the companion can skip download, lock, upload, and the \"Done Editing\" flow entirely\n\nAdditional rules that matter in practice:\n\n- image conversion is not part of the companion local-drive path; raw local files are served directly\n- local-drive browsing has no SMB edit-lock semantics\n- same-drive copy and move use local filesystem operations directly\n- cross-backend transfers between SMB and local storage are browser-mediated rather than hidden inside the companion's direct-open flow\n\nThat direct local-open path is intentionally different from SMB-backed native-app editing.\n\n## Drive Enumeration Model\n\nThe companion discovers drives and mounted volumes automatically.\n\nPlatform-specific inputs differ, but the goal is the same: expose what the current desktop user can already access through the normal filesystem.\n\n- Windows: fixed drives, removable drives, mapped drives, and virtual drives exposed through the filesystem\n- macOS: mounted volumes under the normal desktop volume model\n- Linux: mounted filesystems that represent real file content rather than pseudo-filesystems\n\nThat includes cloud-backed or virtual drives when they appear through the OS filesystem layer.\n\nThe browser therefore does not need manual drive configuration. It asks the companion for the current drive list and renders those entries alongside SMB connections.\n\nThe companion should still filter out pseudo-filesystems and other non-file mounts that would only add noise or unsafe paths.\n\n## Browser Routing and Auth Behavior\n\nThe browser uses the same UI for SMB and local drives, but the request path changes underneath.\n\n- SMB-backed requests continue through the main Sambee backend\n- local-drive requests route to the companion localhost API instead\n- the browser detects the companion through the health endpoint\n- once paired, it requests drives and merges them into the connection list as local-drive entries\n\nAuthentication also changes:\n\n- backend requests use the normal server-side auth model\n- companion requests use the pairing-derived HMAC model described in [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/)\n\nThe localhost bootstrap boundary also changed in an important way:\n\n- production trust is established by exact-origin approval during pairing\n- development remains practical through loopback-origin allowance\n- browser-facing pairing management is limited to the current origin rather than arbitrary origin inventory or deletion\n\nThat distinction is critical. Local-drive access is not \"server auth pointed at localhost\". It is a separate authenticated browser-to-desktop channel.\n\n## Local-Drive Watching and WebSockets\n\nThe companion keeps local directory state fresh through its own watcher and WebSocket path.\n\n- the browser opens a companion WebSocket when local-drive behavior is active\n- subscriptions are tracked per directory\n- the companion shares watcher state when possible instead of creating wasteful duplicate watchers\n- local directory changes propagate back into the same browser refresh model used by the file browser\n\nThis is why local drives can participate in the same dual-pane and refresh workflows as SMB connections without pretending the transport is the same.\n\n## SMB-Backed Native-App Save-Back Pipeline\n\nFor SMB-backed native-app editing, the companion is not the source of truth. It is the desktop-side coordinator for a backend-governed editing lifecycle.\n\n1. the browser launches a `sambee://` deep link\n2. the companion exchanges the URI token for an authenticated session\n3. it fetches metadata and downloads the file to a temp directory\n4. it acquires the backend edit lock\n5. it opens the file in the chosen native application\n6. a \"Done Editing\" window stays open while heartbeat and file-status checks continue in the background\n7. on explicit user confirmation, the companion uploads the file or discards it\n8. the backend lock is released and the temp file is recycled\n\n## Why Save-Back Uses Explicit Confirmation\n\nThe save-back model uses explicit user action rather than automatic filesystem watching.\n\nThat avoids a harder class of problems around:\n\n- partial writes and atomic-save behavior\n- repeated intermediate uploads\n- uncertainty about when editing is truly finished\n\nThe hold-to-confirm interaction is therefore a product decision, not just a UI quirk.\n\n## Conflict and Recovery Behavior\n\nThe companion keeps operation state because desktop editing can outlive one clean process lifecycle.\n\n- operation state is persisted alongside temp files for recovery\n- server state is checked before overwrite-sensitive upload completes\n- when server state changed during editing, the user must resolve the conflict rather than silently replacing the file\n\n## Critical Distinction Contributors Must Preserve\n\n- local-drive workflows do not use backend SMB edit locks\n- SMB-backed native-app editing does use backend lock, heartbeat, and upload semantics\n- cross-backend transfers between SMB and local storage are their own browser-mediated flow, not a shortcut through the deep-link edit lifecycle\n- localhost API pairing and HMAC auth are part of the product contract, not replaceable convenience layers\n\nIf you blur these paths, you usually break either security assumptions or data-integrity guarantees.\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/` | localhost API, drive enumeration, auth, pairing, and watcher behavior |\n| `companion/src-tauri/src/commands/open_file.rs` | download and native-app open lifecycle |\n| `companion/src-tauri/src/commands/upload.rs` | upload, lock, and heartbeat support |\n| `companion/src-tauri/src/sync/operations.rs` | operation state and recovery tracking |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion based on connection type |\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome local-drive behavior is intentionally scoped rather than incomplete by accident.\n\n- local direct-open avoids the SMB save-back lifecycle on purpose\n- raw local files are served directly instead of bundling server-style image conversion into the companion path\n- drive scope follows what the current desktop user can already access rather than inventing a separate path-allowlist model by default\n- cross-backend file movement is a separate browser-mediated path because SMB and local-drive backends do not share one native transfer primitive\n\n## Validation Expectations\n\nWhen this pipeline changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe backend checks matter whenever the change touches SMB-backed save-back, lock, heartbeat, or upload behavior.\n", "0.9": "+++\ntitle = \"Local-Drive and Save-Back Pipeline\"\n+++\n\nThe companion supports two different desktop-side data paths.\n\n- paired local-drive access through the localhost API\n- SMB-backed native-app editing with temp files, locks, and explicit save-back\n\nThey are related because the same desktop app participates in both, but they do not share the same trust or data lifecycle.\n\n## Local-Drive Access Pipeline\n\nFor local drives, the browser stays in control and the companion behaves like a desktop-local backend.\n\n1. the browser detects the companion through the localhost health endpoint\n2. browser and companion pair explicitly\n3. the browser requests available drives\n4. the browser routes local-drive browse, file, and file-management requests to the companion instead of the server backend\n5. a companion-side watcher and WebSocket channel keep local directory state fresh\n\nThis is why local drives can appear inside the same UI as SMB shares while still using a different execution path.\n\n## Localhost API Shape\n\nThe companion embeds a localhost HTTP server and mirrors the backend API contract closely enough that the frontend can stay mostly connection-type agnostic.\n\nThe server is bound to `127.0.0.1:21549` and exposes routes under `/api`.\n\nRepresentative endpoints include:\n\n- `GET /api/health`: companion availability\n- `POST /api/pair/initiate`: begin pairing\n- `POST /api/pair/confirm`: finish pairing after dual confirmation\n- `GET /api/pair/status`: origin-scoped browser pairing status\n- `POST /api/pair/cancel`: cancel a pending pairing for the current browser origin\n- `DELETE /api/pair/current`: remove the current browser origin's pairing\n- `GET /api/drives`: enumerate available local drives and volumes\n- `GET /api/browse/{drive}/list`: list a directory\n- `GET /api/browse/{drive}/info`: stat one file or directory\n- `GET /api/browse/{drive}/directories`: search directories recursively\n- `GET /api/viewer/{drive}/file`: stream a file for inline viewing\n- `GET /api/viewer/{drive}/download`: stream a file as a download\n- `POST /api/browse/{drive}/upload`: upload a file into the drive-backed path\n- `DELETE /api/browse/{drive}/item`: delete a file or directory\n- `POST /api/browse/{drive}/rename`: rename a path\n- `POST /api/browse/{drive}/create`: create a file or directory\n- `POST /api/browse/{drive}/copy`: copy within or across local drives\n- `POST /api/browse/{drive}/move`: move within or across local drives\n- `WS /api/ws`: companion-side directory change notifications\n\nResponse shapes intentionally follow the backend contract so the browser can reuse models such as directory listings and file info instead of maintaining a separate local-drive UI protocol.\n\nThe important exception is pairing state: the browser-facing pairing contract is intentionally origin-scoped and typed, rather than exposing a global paired flag or browser-visible inventory of all trusted origins.\n\n## Local-Drive Operation Rules\n\n- the companion mirrors the backend API contract closely so the frontend can stay mostly connection-type agnostic\n- local-drive operations use desktop filesystem primitives, not SMB semantics\n- local files opened directly through the companion can skip download, lock, upload, and the \"Done Editing\" flow entirely\n\nAdditional rules that matter in practice:\n\n- image conversion is not part of the companion local-drive path; raw local files are served directly\n- local-drive browsing has no SMB edit-lock semantics\n- same-drive copy and move use local filesystem operations directly\n- cross-backend transfers between SMB and local storage are browser-mediated rather than hidden inside the companion's direct-open flow\n\nThat direct local-open path is intentionally different from SMB-backed native-app editing.\n\n## Drive Enumeration Model\n\nThe companion discovers drives and mounted volumes automatically.\n\nPlatform-specific inputs differ, but the goal is the same: expose what the current desktop user can already access through the normal filesystem.\n\n- Windows: fixed drives, removable drives, mapped drives, and virtual drives exposed through the filesystem\n- macOS: mounted volumes under the normal desktop volume model\n- Linux: mounted filesystems that represent real file content rather than pseudo-filesystems\n\nThat includes cloud-backed or virtual drives when they appear through the OS filesystem layer.\n\nThe browser therefore does not need manual drive configuration. It asks the companion for the current drive list and renders those entries alongside SMB connections.\n\nThe companion should still filter out pseudo-filesystems and other non-file mounts that would only add noise or unsafe paths.\n\n## Browser Routing and Auth Behavior\n\nThe browser uses the same UI for SMB and local drives, but the request path changes underneath.\n\n- SMB-backed requests continue through the main Sambee backend\n- local-drive requests route to the companion localhost API instead\n- the browser detects the companion through the health endpoint\n- once paired, it requests drives and merges them into the connection list as local-drive entries\n\nAuthentication also changes:\n\n- backend requests use the normal server-side auth model\n- companion requests use the pairing-derived HMAC model described in [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/)\n\nThe localhost bootstrap boundary also changed in an important way:\n\n- production trust is established by exact-origin approval during pairing\n- development remains practical through loopback-origin allowance\n- browser-facing pairing management is limited to the current origin rather than arbitrary origin inventory or deletion\n\nThat distinction is critical. Local-drive access is not \"server auth pointed at localhost\". It is a separate authenticated browser-to-desktop channel.\n\n## Local-Drive Watching and WebSockets\n\nThe companion keeps local directory state fresh through its own watcher and WebSocket path.\n\n- the browser opens a companion WebSocket when local-drive behavior is active\n- subscriptions are tracked per directory\n- the companion shares watcher state when possible instead of creating wasteful duplicate watchers\n- local directory changes propagate back into the same browser refresh model used by the file browser\n\nThis is why local drives can participate in the same dual-pane and refresh workflows as SMB connections without pretending the transport is the same.\n\n## SMB-Backed Native-App Save-Back Pipeline\n\nFor SMB-backed native-app editing, the companion is not the source of truth. It is the desktop-side coordinator for a backend-governed editing lifecycle.\n\n1. the browser launches a `sambee://` deep link\n2. the companion exchanges the URI token for an authenticated session\n3. it fetches metadata and downloads the file to a temp directory\n4. it acquires the backend edit lock\n5. it opens the file in the chosen native application\n6. a \"Done Editing\" window stays open while heartbeat and file-status checks continue in the background\n7. on explicit user confirmation, the companion uploads the file or discards it\n8. the backend lock is released and the temp file is recycled\n\n## Why Save-Back Uses Explicit Confirmation\n\nThe save-back model uses explicit user action rather than automatic filesystem watching.\n\nThat avoids a harder class of problems around:\n\n- partial writes and atomic-save behavior\n- repeated intermediate uploads\n- uncertainty about when editing is truly finished\n\nThe hold-to-confirm interaction is therefore a product decision, not just a UI quirk.\n\n## Conflict and Recovery Behavior\n\nThe companion keeps operation state because desktop editing can outlive one clean process lifecycle.\n\n- operation state is persisted alongside temp files for recovery\n- server state is checked before overwrite-sensitive upload completes\n- when server state changed during editing, the user must resolve the conflict rather than silently replacing the file\n\n## Critical Distinction Contributors Must Preserve\n\n- local-drive workflows do not use backend SMB edit locks\n- SMB-backed native-app editing does use backend lock, heartbeat, and upload semantics\n- cross-backend transfers between SMB and local storage are their own browser-mediated flow, not a shortcut through the deep-link edit lifecycle\n- localhost API pairing and HMAC auth are part of the product contract, not replaceable convenience layers\n\nIf you blur these paths, you usually break either security assumptions or data-integrity guarantees.\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/` | localhost API, drive enumeration, auth, pairing, and watcher behavior |\n| `companion/src-tauri/src/commands/open_file.rs` | download and native-app open lifecycle |\n| `companion/src-tauri/src/commands/upload.rs` | upload, lock, and heartbeat support |\n| `companion/src-tauri/src/sync/operations.rs` | operation state and recovery tracking |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion based on connection type |\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome local-drive behavior is intentionally scoped rather than incomplete by accident.\n\n- local direct-open avoids the SMB save-back lifecycle on purpose\n- raw local files are served directly instead of bundling server-style image conversion into the companion path\n- drive scope follows what the current desktop user can already access rather than inventing a separate path-allowlist model by default\n- cross-backend file movement is a separate browser-mediated path because SMB and local-drive backends do not share one native transfer primitive\n\n## Validation Expectations\n\nWhen this pipeline changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe backend checks matter whenever the change touches SMB-backed save-back, lock, heartbeat, or upload behavior.\n", "1.0": "+++\ntitle = \"Local-Drive and Save-Back Pipeline\"\n+++\n\nThe companion supports two different desktop-side data paths.\n\n- paired local-drive access through the localhost API\n- SMB-backed native-app editing with temp files, locks, and explicit save-back\n\nThey are related because the same desktop app participates in both, but they do not share the same trust or data lifecycle.\n\n## Local-Drive Access Pipeline\n\nFor local drives, the browser stays in control and the companion behaves like a desktop-local backend.\n\n1. the browser detects the companion through the localhost health endpoint\n2. browser and companion pair explicitly\n3. the browser requests available drives\n4. the browser routes local-drive browse, file, and file-management requests to the companion instead of the server backend\n5. a companion-side watcher and WebSocket channel keep local directory state fresh\n\nThis is why local drives can appear inside the same UI as SMB shares while still using a different execution path.\n\n## Localhost API Shape\n\nThe companion embeds a localhost HTTP server and mirrors the backend API contract closely enough that the frontend can stay mostly connection-type agnostic.\n\nThe server is bound to `127.0.0.1:21549` and exposes routes under `/api`.\n\nRepresentative endpoints include:\n\n- `GET /api/health`: companion availability\n- `POST /api/pair/initiate`: begin pairing\n- `POST /api/pair/confirm`: finish pairing after dual confirmation\n- `GET /api/pair/status`: origin-scoped browser pairing status\n- `POST /api/pair/cancel`: cancel a pending pairing for the current browser origin\n- `DELETE /api/pair/current`: remove the current browser origin's pairing\n- `GET /api/drives`: enumerate available local drives and volumes\n- `GET /api/browse/{drive}/list`: list a directory\n- `GET /api/browse/{drive}/info`: stat one file or directory\n- `GET /api/browse/{drive}/directories`: search directories recursively\n- `GET /api/viewer/{drive}/file`: stream a file for inline viewing\n- `GET /api/viewer/{drive}/download`: stream a file as a download\n- `POST /api/browse/{drive}/upload`: upload a file into the drive-backed path\n- `DELETE /api/browse/{drive}/item`: delete a file or directory\n- `POST /api/browse/{drive}/rename`: rename a path\n- `POST /api/browse/{drive}/create`: create a file or directory\n- `POST /api/browse/{drive}/copy`: copy within or across local drives\n- `POST /api/browse/{drive}/move`: move within or across local drives\n- `WS /api/ws`: companion-side directory change notifications\n\nResponse shapes intentionally follow the backend contract so the browser can reuse models such as directory listings and file info instead of maintaining a separate local-drive UI protocol.\n\nThe important exception is pairing state: the browser-facing pairing contract is intentionally origin-scoped and typed, rather than exposing a global paired flag or browser-visible inventory of all trusted origins.\n\n## Local-Drive Operation Rules\n\n- the companion mirrors the backend API contract closely so the frontend can stay mostly connection-type agnostic\n- local-drive operations use desktop filesystem primitives, not SMB semantics\n- local files opened directly through the companion can skip download, lock, upload, and the \"Done Editing\" flow entirely\n\nAdditional rules that matter in practice:\n\n- image conversion is not part of the companion local-drive path; raw local files are served directly\n- local-drive browsing has no SMB edit-lock semantics\n- same-drive copy and move use local filesystem operations directly\n- cross-backend transfers between SMB and local storage are browser-mediated rather than hidden inside the companion's direct-open flow\n\nThat direct local-open path is intentionally different from SMB-backed native-app editing.\n\n## Drive Enumeration Model\n\nThe companion discovers drives and mounted volumes automatically.\n\nPlatform-specific inputs differ, but the goal is the same: expose what the current desktop user can already access through the normal filesystem.\n\n- Windows: fixed drives, removable drives, mapped drives, and virtual drives exposed through the filesystem\n- macOS: mounted volumes under the normal desktop volume model\n- Linux: mounted filesystems that represent real file content rather than pseudo-filesystems\n\nThat includes cloud-backed or virtual drives when they appear through the OS filesystem layer.\n\nThe browser therefore does not need manual drive configuration. It asks the companion for the current drive list and renders those entries alongside SMB connections.\n\nThe companion should still filter out pseudo-filesystems and other non-file mounts that would only add noise or unsafe paths.\n\n## Browser Routing and Auth Behavior\n\nThe browser uses the same UI for SMB and local drives, but the request path changes underneath.\n\n- SMB-backed requests continue through the main Sambee backend\n- local-drive requests route to the companion localhost API instead\n- the browser detects the companion through the health endpoint\n- once paired, it requests drives and merges them into the connection list as local-drive entries\n\nAuthentication also changes:\n\n- backend requests use the normal server-side auth model\n- companion requests use the pairing-derived HMAC model described in [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/)\n\nThe localhost bootstrap boundary also changed in an important way:\n\n- production trust is established by exact-origin approval during pairing\n- development remains practical through loopback-origin allowance\n- browser-facing pairing management is limited to the current origin rather than arbitrary origin inventory or deletion\n\nThat distinction is critical. Local-drive access is not \"server auth pointed at localhost\". It is a separate authenticated browser-to-desktop channel.\n\n## Local-Drive Watching and WebSockets\n\nThe companion keeps local directory state fresh through its own watcher and WebSocket path.\n\n- the browser opens a companion WebSocket when local-drive behavior is active\n- subscriptions are tracked per directory\n- the companion shares watcher state when possible instead of creating wasteful duplicate watchers\n- local directory changes propagate back into the same browser refresh model used by the file browser\n\nThis is why local drives can participate in the same dual-pane and refresh workflows as SMB connections without pretending the transport is the same.\n\n## SMB-Backed Native-App Save-Back Pipeline\n\nFor SMB-backed native-app editing, the companion is not the source of truth. It is the desktop-side coordinator for a backend-governed editing lifecycle.\n\n1. the browser launches a `sambee://` deep link\n2. the companion exchanges the URI token for an authenticated session\n3. it fetches metadata and downloads the file to a temp directory\n4. it acquires the backend edit lock\n5. it opens the file in the chosen native application\n6. a \"Done Editing\" window stays open while heartbeat and file-status checks continue in the background\n7. on explicit user confirmation, the companion uploads the file or discards it\n8. the backend lock is released and the temp file is recycled\n\n## Why Save-Back Uses Explicit Confirmation\n\nThe save-back model uses explicit user action rather than automatic filesystem watching.\n\nThat avoids a harder class of problems around:\n\n- partial writes and atomic-save behavior\n- repeated intermediate uploads\n- uncertainty about when editing is truly finished\n\nThe hold-to-confirm interaction is therefore a product decision, not just a UI quirk.\n\n## Conflict and Recovery Behavior\n\nThe companion keeps operation state because desktop editing can outlive one clean process lifecycle.\n\n- operation state is persisted alongside temp files for recovery\n- server state is checked before overwrite-sensitive upload completes\n- when server state changed during editing, the user must resolve the conflict rather than silently replacing the file\n\n## Critical Distinction Contributors Must Preserve\n\n- local-drive workflows do not use backend SMB edit locks\n- SMB-backed native-app editing does use backend lock, heartbeat, and upload semantics\n- cross-backend transfers between SMB and local storage are their own browser-mediated flow, not a shortcut through the deep-link edit lifecycle\n- localhost API pairing and HMAC auth are part of the product contract, not replaceable convenience layers\n\nIf you blur these paths, you usually break either security assumptions or data-integrity guarantees.\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/` | localhost API, drive enumeration, auth, pairing, and watcher behavior |\n| `companion/src-tauri/src/commands/open_file.rs` | download and native-app open lifecycle |\n| `companion/src-tauri/src/commands/upload.rs` | upload, lock, and heartbeat support |\n| `companion/src-tauri/src/sync/operations.rs` | operation state and recovery tracking |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion based on connection type |\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome local-drive behavior is intentionally scoped rather than incomplete by accident.\n\n- local direct-open avoids the SMB save-back lifecycle on purpose\n- raw local files are served directly instead of bundling server-style image conversion into the companion path\n- drive scope follows what the current desktop user can already access rather than inventing a separate path-allowlist model by default\n- cross-backend file movement is a separate browser-mediated path because SMB and local-drive backends do not share one native transfer primitive\n\n## Validation Expectations\n\nWhen this pipeline changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe backend checks matter whenever the change touches SMB-backed save-back, lock, heartbeat, or upload behavior.\n", "2.0": "+++\ntitle = \"Local-Drive and Save-Back Pipeline\"\n+++\n\nThe companion supports two different desktop-side data paths.\n\n- paired local-drive access through the localhost API\n- SMB-backed native-app editing with temp files, locks, and explicit save-back\n\nThey are related because the same desktop app participates in both, but they do not share the same trust or data lifecycle.\n\n## Local-Drive Access Pipeline\n\nFor local drives, the browser stays in control and the companion behaves like a desktop-local backend.\n\n1. the browser detects the companion through the localhost health endpoint\n2. browser and companion pair explicitly\n3. the browser requests available drives\n4. the browser routes local-drive browse, file, and file-management requests to the companion instead of the server backend\n5. a companion-side watcher and WebSocket channel keep local directory state fresh\n\nThis is why local drives can appear inside the same UI as SMB shares while still using a different execution path.\n\n## Localhost API Shape\n\nThe companion embeds a localhost HTTP server and mirrors the backend API contract closely enough that the frontend can stay mostly connection-type agnostic.\n\nThe server is bound to `127.0.0.1:21549` and exposes routes under `/api`.\n\nRepresentative endpoints include:\n\n- `GET /api/health`: companion availability\n- `POST /api/pair/initiate`: begin pairing\n- `POST /api/pair/confirm`: finish pairing after dual confirmation\n- `GET /api/pair/status`: origin-scoped browser pairing status\n- `POST /api/pair/cancel`: cancel a pending pairing for the current browser origin\n- `DELETE /api/pair/current`: remove the current browser origin's pairing\n- `GET /api/drives`: enumerate available local drives and volumes\n- `GET /api/browse/{drive}/list`: list a directory\n- `GET /api/browse/{drive}/info`: stat one file or directory\n- `GET /api/browse/{drive}/directories`: search directories recursively\n- `GET /api/viewer/{drive}/file`: stream a file for inline viewing\n- `GET /api/viewer/{drive}/download`: stream a file as a download\n- `POST /api/browse/{drive}/upload`: upload a file into the drive-backed path\n- `DELETE /api/browse/{drive}/item`: delete a file or directory\n- `POST /api/browse/{drive}/rename`: rename a path\n- `POST /api/browse/{drive}/create`: create a file or directory\n- `POST /api/browse/{drive}/copy`: copy within or across local drives\n- `POST /api/browse/{drive}/move`: move within or across local drives\n- `WS /api/ws`: companion-side directory change notifications\n\nResponse shapes intentionally follow the backend contract so the browser can reuse models such as directory listings and file info instead of maintaining a separate local-drive UI protocol.\n\nThe important exception is pairing state: the browser-facing pairing contract is intentionally origin-scoped and typed, rather than exposing a global paired flag or browser-visible inventory of all trusted origins.\n\n## Local-Drive Operation Rules\n\n- the companion mirrors the backend API contract closely so the frontend can stay mostly connection-type agnostic\n- local-drive operations use desktop filesystem primitives, not SMB semantics\n- local files opened directly through the companion can skip download, lock, upload, and the \"Done Editing\" flow entirely\n\nAdditional rules that matter in practice:\n\n- image conversion is not part of the companion local-drive path; raw local files are served directly\n- local-drive browsing has no SMB edit-lock semantics\n- same-drive copy and move use local filesystem operations directly\n- cross-backend transfers between SMB and local storage are browser-mediated rather than hidden inside the companion's direct-open flow\n\nThat direct local-open path is intentionally different from SMB-backed native-app editing.\n\n## Drive Enumeration Model\n\nThe companion discovers drives and mounted volumes automatically.\n\nPlatform-specific inputs differ, but the goal is the same: expose what the current desktop user can already access through the normal filesystem.\n\n- Windows: fixed drives, removable drives, mapped drives, and virtual drives exposed through the filesystem\n- macOS: mounted volumes under the normal desktop volume model\n- Linux: mounted filesystems that represent real file content rather than pseudo-filesystems\n\nThat includes cloud-backed or virtual drives when they appear through the OS filesystem layer.\n\nThe browser therefore does not need manual drive configuration. It asks the companion for the current drive list and renders those entries alongside SMB connections.\n\nThe companion should still filter out pseudo-filesystems and other non-file mounts that would only add noise or unsafe paths.\n\n## Browser Routing and Auth Behavior\n\nThe browser uses the same UI for SMB and local drives, but the request path changes underneath.\n\n- SMB-backed requests continue through the main Sambee backend\n- local-drive requests route to the companion localhost API instead\n- the browser detects the companion through the health endpoint\n- once paired, it requests drives and merges them into the connection list as local-drive entries\n\nAuthentication also changes:\n\n- backend requests use the normal server-side auth model\n- companion requests use the pairing-derived HMAC model described in [Browser-to-Companion Trust Model](../browser-to-companion-trust-model/)\n\nThe localhost bootstrap boundary also changed in an important way:\n\n- production trust is established by exact-origin approval during pairing\n- development remains practical through loopback-origin allowance\n- browser-facing pairing management is limited to the current origin rather than arbitrary origin inventory or deletion\n\nThat distinction is critical. Local-drive access is not \"server auth pointed at localhost\". It is a separate authenticated browser-to-desktop channel.\n\n## Local-Drive Watching and WebSockets\n\nThe companion keeps local directory state fresh through its own watcher and WebSocket path.\n\n- the browser opens a companion WebSocket when local-drive behavior is active\n- subscriptions are tracked per directory\n- the companion shares watcher state when possible instead of creating wasteful duplicate watchers\n- local directory changes propagate back into the same browser refresh model used by the file browser\n\nThis is why local drives can participate in the same dual-pane and refresh workflows as SMB connections without pretending the transport is the same.\n\n## SMB-Backed Native-App Save-Back Pipeline\n\nFor SMB-backed native-app editing, the companion is not the source of truth. It is the desktop-side coordinator for a backend-governed editing lifecycle.\n\n1. the browser launches a `sambee://` deep link\n2. the companion exchanges the URI token for an authenticated session\n3. it fetches metadata and downloads the file to a temp directory\n4. it acquires the backend edit lock\n5. it opens the file in the chosen native application\n6. a \"Done Editing\" window stays open while heartbeat and file-status checks continue in the background\n7. on explicit user confirmation, the companion uploads the file or discards it\n8. the backend lock is released and the temp file is recycled\n\n## Why Save-Back Uses Explicit Confirmation\n\nThe save-back model uses explicit user action rather than automatic filesystem watching.\n\nThat avoids a harder class of problems around:\n\n- partial writes and atomic-save behavior\n- repeated intermediate uploads\n- uncertainty about when editing is truly finished\n\nThe hold-to-confirm interaction is therefore a product decision, not just a UI quirk.\n\n## Conflict and Recovery Behavior\n\nThe companion keeps operation state because desktop editing can outlive one clean process lifecycle.\n\n- operation state is persisted alongside temp files for recovery\n- server state is checked before overwrite-sensitive upload completes\n- when server state changed during editing, the user must resolve the conflict rather than silently replacing the file\n\n## Critical Distinction Contributors Must Preserve\n\n- local-drive workflows do not use backend SMB edit locks\n- SMB-backed native-app editing does use backend lock, heartbeat, and upload semantics\n- cross-backend transfers between SMB and local storage are their own browser-mediated flow, not a shortcut through the deep-link edit lifecycle\n- localhost API pairing and HMAC auth are part of the product contract, not replaceable convenience layers\n\nIf you blur these paths, you usually break either security assumptions or data-integrity guarantees.\n\n## Where the Main Logic Lives\n\n| Path | Responsibility |\n|---|---|\n| `companion/src-tauri/src/server/` | localhost API, drive enumeration, auth, pairing, and watcher behavior |\n| `companion/src-tauri/src/commands/open_file.rs` | download and native-app open lifecycle |\n| `companion/src-tauri/src/commands/upload.rs` | upload, lock, and heartbeat support |\n| `companion/src-tauri/src/sync/operations.rs` | operation state and recovery tracking |\n| `frontend/src/services/backendRouter.ts` | routes browser requests to backend or companion based on connection type |\n\n## Design Constraints and Deliberate Tradeoffs\n\nSome local-drive behavior is intentionally scoped rather than incomplete by accident.\n\n- local direct-open avoids the SMB save-back lifecycle on purpose\n- raw local files are served directly instead of bundling server-style image conversion into the companion path\n- drive scope follows what the current desktop user can already access rather than inventing a separate path-allowlist model by default\n- cross-backend file movement is a separate browser-mediated path because SMB and local-drive backends do not share one native transfer primitive\n\n## Validation Expectations\n\nWhen this pipeline changes, usually run:\n\n```bash\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\ncd companion/src-tauri \u0026\u0026 cargo test\ncd frontend \u0026\u0026 npm test\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd backend \u0026\u0026 pytest -v\n```\n\nThe backend checks matter whenever the change touches SMB-backed save-back, lock, heartbeat, or upload behavior.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:developer-guide/cross-cutting-systems", "parent_id": "book:developer-guide", "depth": 1, "kind": "section", "label": "cross-cutting-systems", "title": "Cross-Cutting Systems", "path": "developer-guide/cross-cutting-systems", "has_children": true, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Cross-Cutting Systems\"\n+++\n\nSome Sambee behaviors are shared systems rather than one-team implementation details.\n\nStart with:\n\n- [Logging and Localization](./logging-and-localization/)\n- [Localization and Locale Behavior](./localization-and-locale-behavior/)\n- [Frontend Logging and Tracing](./frontend-logging-and-tracing/)\n\nUse this section when a change spans the browser app, backend, or companion and you need one consistent rule set instead of app-by-app drift.\n", "0.8": "+++\ntitle = \"Cross-Cutting Systems\"\n+++\n\nSome Sambee behaviors are shared systems rather than one-team implementation details.\n\nStart with:\n\n- [Logging and Localization](./logging-and-localization/)\n- [Localization and Locale Behavior](./localization-and-locale-behavior/)\n- [Frontend Logging and Tracing](./frontend-logging-and-tracing/)\n\nUse this section when a change spans the browser app, backend, or companion and you need one consistent rule set instead of app-by-app drift.\n", "0.9": "+++\ntitle = \"Cross-Cutting Systems\"\n+++\n\nSome Sambee behaviors are shared systems rather than one-team implementation details.\n\nStart with:\n\n- [Logging and Localization](./logging-and-localization/)\n- [Localization and Locale Behavior](./localization-and-locale-behavior/)\n- [Frontend Logging and Tracing](./frontend-logging-and-tracing/)\n\nUse this section when a change spans the browser app, backend, or companion and you need one consistent rule set instead of app-by-app drift.\n", "1.0": "+++\ntitle = \"Cross-Cutting Systems\"\n+++\n\nSome Sambee behaviors are shared systems rather than one-team implementation details.\n\nStart with:\n\n- [Logging and Localization](./logging-and-localization/)\n- [Localization and Locale Behavior](./localization-and-locale-behavior/)\n- [Frontend Logging and Tracing](./frontend-logging-and-tracing/)\n\nUse this section when a change spans the browser app, backend, or companion and you need one consistent rule set instead of app-by-app drift.\n", "2.0": "+++\ntitle = \"Cross-Cutting Systems\"\n+++\n\nSome Sambee behaviors are shared systems rather than one-team implementation details.\n\nStart with:\n\n- [Logging and Localization](./logging-and-localization/)\n- [Localization and Locale Behavior](./localization-and-locale-behavior/)\n- [Frontend Logging and Tracing](./frontend-logging-and-tracing/)\n\nUse this section when a change spans the browser app, backend, or companion and you need one consistent rule set instead of app-by-app drift.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/cross-cutting-systems/logging-and-localization", "parent_id": "section:developer-guide/cross-cutting-systems", "depth": 2, "kind": "page", "label": "logging-and-localization", "title": "Logging And Localization", "path": "developer-guide/cross-cutting-systems/logging-and-localization", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "branched", "source_version": "0.7", "diff_added": 43, "diff_removed": 22}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "inherited", "source_version": "0.9"}}, "content_versions": {"0.7": "+++\ntitle = \"Logging and Localization\"\n+++\n\nLogging and localization are both cross-boundary product systems in Sambee.\n\n- logging affects local debugging, operator visibility, and backend trace collection\n- localization affects typed UI copy, locale behavior, browser formatting, and browser-to-companion sync\n\nTreat both as shared contracts rather than optional polish.\n\n## Logging Model\n\nSambee uses more than one logging surface, but the goal is still one coherent diagnostic story.\n\n### Browser App Logging\n\nThe browser app supports both:\n\n- console logging for local development and debugging\n- backend tracing for server-side log collection when production or mobile debugging needs it\n\nThat means a logging change can affect both developer ergonomics and support visibility.\n\n### Companion and Service-Side Logging\n\nThe companion has its own desktop-side logging path, and operational logs are still important on the backend and in local development scripts.\n\n- use the shared logging utilities where the app already has them\n- keep log messages specific enough to be actionable\n- avoid replacing structured or filtered logging with scattered ad hoc output\n\nFor local environment diagnosis, the repo also provides supported log and service-status scripts instead of relying entirely on manual process inspection.\n\n## Localization Model\n\nLocalization is a typed system, not just a string file.\n\n### Sources of Truth\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Typed wrappers | each app's `i18n/index.ts` layer |\n\nEnglish is the source locale, and the pseudo-locale is generated automatically from the English tree.\n\n### Contributor Rules\n\n- add new UI strings through the translation resources instead of hard-coding copy\n- keep translation keys type-safe instead of casting around the type system\n- preserve the distinction between UI language and regional formatting behavior\n- remember that the browser app can push its effective locale into the companion through the paired localhost API\n\n## What Contributors Must Preserve\n\n### Logging\n\n- browser app logging and backend tracing are related but separately configurable\n- logging changes should not silently remove trace visibility that support workflows depend on\n- diagnostics should stay specific and action-oriented\n\n### Localization\n\n- typed keys should remain enforced\n- browser-localization behavior and companion-localization sync should keep using effective locale values rather than raw unresolved preferences\n- app-owned UI text should stay translatable\n\nFor the concrete contributor workflow, continue to [Localization and Locale Behavior](../localization-and-locale-behavior/).\n\n## Common Failure Modes\n\n- adding UI text without a translation key\n- bypassing typed translation keys with casts\n- changing localization behavior in the browser app without checking companion sync effects\n- switching logging behavior in a way that helps local debugging but breaks backend tracing or support visibility\n- flooding logs with noisy messages that hide the actionable ones\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\n```\n\nFor higher-confidence changes, add the relevant frontend or companion tests, especially when localization sync or logging configuration behavior changes.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) to decide when those cross-boundary checks need to extend further.\n", "0.8": "+++\ntitle = \"Logging and Localization\"\n+++\n\nLogging and localization are both cross-boundary product systems in Sambee.\n\n- logging affects local debugging, operator visibility, and backend trace collection\n- localization affects typed UI copy, locale behavior, browser formatting, and browser-to-companion sync\n\nTreat both as shared contracts rather than optional polish.\n\n## Logging Model\n\nSambee uses more than one logging surface, but the goal is still one coherent diagnostic story.\n\n### Browser App Logging\n\nThe browser app supports both:\n\n- console logging for local development and debugging\n- backend tracing for server-side log collection when production or mobile debugging needs it\n\nThat means a logging change can affect both developer ergonomics and support visibility.\n\n### Companion and Service-Side Logging\n\nThe companion has its own desktop-side logging path, and operational logs are still important on the backend and in local development scripts.\n\n- use the shared logging utilities where the app already has them\n- keep log messages specific enough to be actionable\n- avoid replacing structured or filtered logging with scattered ad hoc output\n\nFor local environment diagnosis, the repo also provides supported log and service-status scripts instead of relying entirely on manual process inspection.\n\n## Localization Model\n\nLocalization is a typed system, not just a string file.\n\n### Sources of Truth\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Typed wrappers | each app's `i18n/index.ts` layer |\n\nEnglish is the source locale, and the pseudo-locale is generated automatically from the English tree.\n\n### Contributor Rules\n\n- add new UI strings through the translation resources instead of hard-coding copy\n- keep translation keys type-safe instead of casting around the type system\n- preserve the distinction between UI language and regional formatting behavior\n- remember that the browser app can push its effective locale into the companion through the paired localhost API\n\n## What Contributors Must Preserve\n\n### Logging\n\n- browser app logging and backend tracing are related but separately configurable\n- logging changes should not silently remove trace visibility that support workflows depend on\n- diagnostics should stay specific and action-oriented\n\n### Localization\n\n- typed keys should remain enforced\n- browser-localization behavior and companion-localization sync should keep using effective locale values rather than raw unresolved preferences\n- app-owned UI text should stay translatable\n\nFor the concrete contributor workflow, continue to [Localization and Locale Behavior](../localization-and-locale-behavior/).\n\n## Common Failure Modes\n\n- adding UI text without a translation key\n- bypassing typed translation keys with casts\n- changing localization behavior in the browser app without checking companion sync effects\n- switching logging behavior in a way that helps local debugging but breaks backend tracing or support visibility\n- flooding logs with noisy messages that hide the actionable ones\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\n```\n\nFor higher-confidence changes, add the relevant frontend or companion tests, especially when localization sync or logging configuration behavior changes.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) to decide when those cross-boundary checks need to extend further.\n", "0.9": "+++\ntitle = \"Logging and Localization\"\n+++\n\nLogging and localization are both cross-boundary product systems in Sambee.\n\n- Logging affects local debugging, operator visibility, and backend trace collection.\n- Localization affects typed UI copy, locale behavior, browser formatting, and browser-to-companion sync.\n\nTreat both as shared contracts rather than optional polish.\n\n## Logging Model\n\nSambee uses more than one logging surface, but the goal is still one coherent diagnostic story.\n\n### Backend Logging\n\nThe backend sends logs to standard output so they are available through Docker or the process supervisor. Configure the backend in the `[app]` section of `config.toml`:\n\n```toml\n[app]\nlog_level = \"INFO\"\naccess_log_level = \"WARNING\"\nprotocol_log_level = \"WARNING\"\n```\n\n| Key | Controls | Default |\n|---|---|---|\n| `log_level` | Application diagnostics and Uvicorn startup, shutdown, and error messages. | `INFO` |\n| `access_log_level` | Uvicorn HTTP request access records. | `WARNING` |\n| `protocol_log_level` | Uvicorn WebSocket connection, frame, and keepalive records. | `WARNING` |\n\nAll three settings accept `DEBUG`, `INFO`, `WARNING`, or `ERROR`, regardless of case. The default access and protocol levels keep successful requests, WebSocket payloads, and ping traffic out of normal operational logs while retaining application lifecycle and error messages.\n\nSet `access_log_level` to `INFO` when request auditing is needed. Set `protocol_log_level` to `DEBUG` only while diagnosing WebSocket communication; it includes sent and received frames as well as keepalive messages and can be very verbose.\n\n### Browser App Logging\n\nThe browser app supports both:\n\n- Console logging for local development and debugging.\n- Backend tracing for server-side log collection when production or mobile debugging needs it.\n\nThat means a logging change can affect both developer ergonomics and support visibility.\n\n### Companion and Service-Side Logging\n\nThe companion has its own desktop-side logging path, and operational logs are still important on the backend and in local development scripts.\n\n- Use the shared logging utilities where the app already has them.\n- Keep log messages specific enough to be actionable.\n- Avoid replacing structured or filtered logging with scattered ad hoc output.\n\nFor local environment diagnosis, the repo also provides supported log and service-status scripts instead of relying entirely on manual process inspection.\n\n## Localization Model\n\nLocalization is a typed system, not just a string file.\n\n### Sources of Truth\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Typed wrappers | each app's `i18n/index.ts` layer |\n\nEnglish is the source locale, and the pseudo-locale is generated automatically from the English tree.\n\n### Contributor Rules\n\n- Add new UI strings through the translation resources instead of hard-coding copy.\n- Keep translation keys type-safe instead of casting around the type system.\n- Preserve the distinction between UI language and regional formatting behavior.\n- Remember that the browser app can push its effective locale into the companion through the paired localhost API.\n\n## What Contributors Must Preserve\n\n### Logging\n\n- Browser app logging and backend tracing are related but separately configurable.\n- Logging changes should not silently remove trace visibility that support workflows depend on.\n- Diagnostics should stay specific and action-oriented.\n\n### Localization\n\n- Typed keys should remain enforced.\n- Browser-localization behavior and companion-localization sync should keep using effective locale values rather than raw unresolved preferences.\n- App-owned UI text should stay translatable.\n\nFor the concrete contributor workflow, continue to [Localization and Locale Behavior](../localization-and-locale-behavior/).\n\n## Common Failure Modes\n\n- Adding UI text without a translation key.\n- Bypassing typed translation keys with casts.\n- Changing localization behavior in the browser app without checking companion sync effects.\n- Switching logging behavior in a way that helps local debugging but breaks backend tracing or support visibility.\n- Flooding logs with noisy messages that hide the actionable ones.\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\n```\n\nFor higher-confidence changes, add the relevant frontend or companion tests, especially when localization sync or logging configuration behavior changes.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) to decide when those cross-boundary checks need to extend further.", "1.0": "+++\ntitle = \"Logging and Localization\"\n+++\n\nLogging and localization are both cross-boundary product systems in Sambee.\n\n- Logging affects local debugging, operator visibility, and backend trace collection.\n- Localization affects typed UI copy, locale behavior, browser formatting, and browser-to-companion sync.\n\nTreat both as shared contracts rather than optional polish.\n\n## Logging Model\n\nSambee uses more than one logging surface, but the goal is still one coherent diagnostic story.\n\n### Backend Logging\n\nThe backend sends logs to standard output so they are available through Docker or the process supervisor. Configure the backend in the `[app]` section of `config.toml`:\n\n```toml\n[app]\nlog_level = \"INFO\"\naccess_log_level = \"WARNING\"\nprotocol_log_level = \"WARNING\"\n```\n\n| Key | Controls | Default |\n|---|---|---|\n| `log_level` | Application diagnostics and Uvicorn startup, shutdown, and error messages. | `INFO` |\n| `access_log_level` | Uvicorn HTTP request access records. | `WARNING` |\n| `protocol_log_level` | Uvicorn WebSocket connection, frame, and keepalive records. | `WARNING` |\n\nAll three settings accept `DEBUG`, `INFO`, `WARNING`, or `ERROR`, regardless of case. The default access and protocol levels keep successful requests, WebSocket payloads, and ping traffic out of normal operational logs while retaining application lifecycle and error messages.\n\nSet `access_log_level` to `INFO` when request auditing is needed. Set `protocol_log_level` to `DEBUG` only while diagnosing WebSocket communication; it includes sent and received frames as well as keepalive messages and can be very verbose.\n\n### Browser App Logging\n\nThe browser app supports both:\n\n- Console logging for local development and debugging.\n- Backend tracing for server-side log collection when production or mobile debugging needs it.\n\nThat means a logging change can affect both developer ergonomics and support visibility.\n\n### Companion and Service-Side Logging\n\nThe companion has its own desktop-side logging path, and operational logs are still important on the backend and in local development scripts.\n\n- Use the shared logging utilities where the app already has them.\n- Keep log messages specific enough to be actionable.\n- Avoid replacing structured or filtered logging with scattered ad hoc output.\n\nFor local environment diagnosis, the repo also provides supported log and service-status scripts instead of relying entirely on manual process inspection.\n\n## Localization Model\n\nLocalization is a typed system, not just a string file.\n\n### Sources of Truth\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Typed wrappers | each app's `i18n/index.ts` layer |\n\nEnglish is the source locale, and the pseudo-locale is generated automatically from the English tree.\n\n### Contributor Rules\n\n- Add new UI strings through the translation resources instead of hard-coding copy.\n- Keep translation keys type-safe instead of casting around the type system.\n- Preserve the distinction between UI language and regional formatting behavior.\n- Remember that the browser app can push its effective locale into the companion through the paired localhost API.\n\n## What Contributors Must Preserve\n\n### Logging\n\n- Browser app logging and backend tracing are related but separately configurable.\n- Logging changes should not silently remove trace visibility that support workflows depend on.\n- Diagnostics should stay specific and action-oriented.\n\n### Localization\n\n- Typed keys should remain enforced.\n- Browser-localization behavior and companion-localization sync should keep using effective locale values rather than raw unresolved preferences.\n- App-owned UI text should stay translatable.\n\nFor the concrete contributor workflow, continue to [Localization and Locale Behavior](../localization-and-locale-behavior/).\n\n## Common Failure Modes\n\n- Adding UI text without a translation key.\n- Bypassing typed translation keys with casts.\n- Changing localization behavior in the browser app without checking companion sync effects.\n- Switching logging behavior in a way that helps local debugging but breaks backend tracing or support visibility.\n- Flooding logs with noisy messages that hide the actionable ones.\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\n```\n\nFor higher-confidence changes, add the relevant frontend or companion tests, especially when localization sync or logging configuration behavior changes.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) to decide when those cross-boundary checks need to extend further.", "2.0": "+++\ntitle = \"Logging and Localization\"\n+++\n\nLogging and localization are both cross-boundary product systems in Sambee.\n\n- Logging affects local debugging, operator visibility, and backend trace collection.\n- Localization affects typed UI copy, locale behavior, browser formatting, and browser-to-companion sync.\n\nTreat both as shared contracts rather than optional polish.\n\n## Logging Model\n\nSambee uses more than one logging surface, but the goal is still one coherent diagnostic story.\n\n### Backend Logging\n\nThe backend sends logs to standard output so they are available through Docker or the process supervisor. Configure the backend in the `[app]` section of `config.toml`:\n\n```toml\n[app]\nlog_level = \"INFO\"\naccess_log_level = \"WARNING\"\nprotocol_log_level = \"WARNING\"\n```\n\n| Key | Controls | Default |\n|---|---|---|\n| `log_level` | Application diagnostics and Uvicorn startup, shutdown, and error messages. | `INFO` |\n| `access_log_level` | Uvicorn HTTP request access records. | `WARNING` |\n| `protocol_log_level` | Uvicorn WebSocket connection, frame, and keepalive records. | `WARNING` |\n\nAll three settings accept `DEBUG`, `INFO`, `WARNING`, or `ERROR`, regardless of case. The default access and protocol levels keep successful requests, WebSocket payloads, and ping traffic out of normal operational logs while retaining application lifecycle and error messages.\n\nSet `access_log_level` to `INFO` when request auditing is needed. Set `protocol_log_level` to `DEBUG` only while diagnosing WebSocket communication; it includes sent and received frames as well as keepalive messages and can be very verbose.\n\n### Browser App Logging\n\nThe browser app supports both:\n\n- Console logging for local development and debugging.\n- Backend tracing for server-side log collection when production or mobile debugging needs it.\n\nThat means a logging change can affect both developer ergonomics and support visibility.\n\n### Companion and Service-Side Logging\n\nThe companion has its own desktop-side logging path, and operational logs are still important on the backend and in local development scripts.\n\n- Use the shared logging utilities where the app already has them.\n- Keep log messages specific enough to be actionable.\n- Avoid replacing structured or filtered logging with scattered ad hoc output.\n\nFor local environment diagnosis, the repo also provides supported log and service-status scripts instead of relying entirely on manual process inspection.\n\n## Localization Model\n\nLocalization is a typed system, not just a string file.\n\n### Sources of Truth\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Typed wrappers | each app's `i18n/index.ts` layer |\n\nEnglish is the source locale, and the pseudo-locale is generated automatically from the English tree.\n\n### Contributor Rules\n\n- Add new UI strings through the translation resources instead of hard-coding copy.\n- Keep translation keys type-safe instead of casting around the type system.\n- Preserve the distinction between UI language and regional formatting behavior.\n- Remember that the browser app can push its effective locale into the companion through the paired localhost API.\n\n## What Contributors Must Preserve\n\n### Logging\n\n- Browser app logging and backend tracing are related but separately configurable.\n- Logging changes should not silently remove trace visibility that support workflows depend on.\n- Diagnostics should stay specific and action-oriented.\n\n### Localization\n\n- Typed keys should remain enforced.\n- Browser-localization behavior and companion-localization sync should keep using effective locale values rather than raw unresolved preferences.\n- App-owned UI text should stay translatable.\n\nFor the concrete contributor workflow, continue to [Localization and Locale Behavior](../localization-and-locale-behavior/).\n\n## Common Failure Modes\n\n- Adding UI text without a translation key.\n- Bypassing typed translation keys with casts.\n- Changing localization behavior in the browser app without checking companion sync effects.\n- Switching logging behavior in a way that helps local debugging but breaks backend tracing or support visibility.\n- Flooding logs with noisy messages that hide the actionable ones.\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\n```\n\nFor higher-confidence changes, add the relevant frontend or companion tests, especially when localization sync or logging configuration behavior changes.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) to decide when those cross-boundary checks need to extend further."}, "page_contents": {"0.7": "+++\ntitle = \"Logging and Localization\"\n+++\n\nLogging and localization are both cross-boundary product systems in Sambee.\n\n- logging affects local debugging, operator visibility, and backend trace collection\n- localization affects typed UI copy, locale behavior, browser formatting, and browser-to-companion sync\n\nTreat both as shared contracts rather than optional polish.\n\n## Logging Model\n\nSambee uses more than one logging surface, but the goal is still one coherent diagnostic story.\n\n### Browser App Logging\n\nThe browser app supports both:\n\n- console logging for local development and debugging\n- backend tracing for server-side log collection when production or mobile debugging needs it\n\nThat means a logging change can affect both developer ergonomics and support visibility.\n\n### Companion and Service-Side Logging\n\nThe companion has its own desktop-side logging path, and operational logs are still important on the backend and in local development scripts.\n\n- use the shared logging utilities where the app already has them\n- keep log messages specific enough to be actionable\n- avoid replacing structured or filtered logging with scattered ad hoc output\n\nFor local environment diagnosis, the repo also provides supported log and service-status scripts instead of relying entirely on manual process inspection.\n\n## Localization Model\n\nLocalization is a typed system, not just a string file.\n\n### Sources of Truth\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Typed wrappers | each app's `i18n/index.ts` layer |\n\nEnglish is the source locale, and the pseudo-locale is generated automatically from the English tree.\n\n### Contributor Rules\n\n- add new UI strings through the translation resources instead of hard-coding copy\n- keep translation keys type-safe instead of casting around the type system\n- preserve the distinction between UI language and regional formatting behavior\n- remember that the browser app can push its effective locale into the companion through the paired localhost API\n\n## What Contributors Must Preserve\n\n### Logging\n\n- browser app logging and backend tracing are related but separately configurable\n- logging changes should not silently remove trace visibility that support workflows depend on\n- diagnostics should stay specific and action-oriented\n\n### Localization\n\n- typed keys should remain enforced\n- browser-localization behavior and companion-localization sync should keep using effective locale values rather than raw unresolved preferences\n- app-owned UI text should stay translatable\n\nFor the concrete contributor workflow, continue to [Localization and Locale Behavior](../localization-and-locale-behavior/).\n\n## Common Failure Modes\n\n- adding UI text without a translation key\n- bypassing typed translation keys with casts\n- changing localization behavior in the browser app without checking companion sync effects\n- switching logging behavior in a way that helps local debugging but breaks backend tracing or support visibility\n- flooding logs with noisy messages that hide the actionable ones\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\n```\n\nFor higher-confidence changes, add the relevant frontend or companion tests, especially when localization sync or logging configuration behavior changes.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) to decide when those cross-boundary checks need to extend further.\n", "0.8": "+++\ntitle = \"Logging and Localization\"\n+++\n\nLogging and localization are both cross-boundary product systems in Sambee.\n\n- logging affects local debugging, operator visibility, and backend trace collection\n- localization affects typed UI copy, locale behavior, browser formatting, and browser-to-companion sync\n\nTreat both as shared contracts rather than optional polish.\n\n## Logging Model\n\nSambee uses more than one logging surface, but the goal is still one coherent diagnostic story.\n\n### Browser App Logging\n\nThe browser app supports both:\n\n- console logging for local development and debugging\n- backend tracing for server-side log collection when production or mobile debugging needs it\n\nThat means a logging change can affect both developer ergonomics and support visibility.\n\n### Companion and Service-Side Logging\n\nThe companion has its own desktop-side logging path, and operational logs are still important on the backend and in local development scripts.\n\n- use the shared logging utilities where the app already has them\n- keep log messages specific enough to be actionable\n- avoid replacing structured or filtered logging with scattered ad hoc output\n\nFor local environment diagnosis, the repo also provides supported log and service-status scripts instead of relying entirely on manual process inspection.\n\n## Localization Model\n\nLocalization is a typed system, not just a string file.\n\n### Sources of Truth\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Typed wrappers | each app's `i18n/index.ts` layer |\n\nEnglish is the source locale, and the pseudo-locale is generated automatically from the English tree.\n\n### Contributor Rules\n\n- add new UI strings through the translation resources instead of hard-coding copy\n- keep translation keys type-safe instead of casting around the type system\n- preserve the distinction between UI language and regional formatting behavior\n- remember that the browser app can push its effective locale into the companion through the paired localhost API\n\n## What Contributors Must Preserve\n\n### Logging\n\n- browser app logging and backend tracing are related but separately configurable\n- logging changes should not silently remove trace visibility that support workflows depend on\n- diagnostics should stay specific and action-oriented\n\n### Localization\n\n- typed keys should remain enforced\n- browser-localization behavior and companion-localization sync should keep using effective locale values rather than raw unresolved preferences\n- app-owned UI text should stay translatable\n\nFor the concrete contributor workflow, continue to [Localization and Locale Behavior](../localization-and-locale-behavior/).\n\n## Common Failure Modes\n\n- adding UI text without a translation key\n- bypassing typed translation keys with casts\n- changing localization behavior in the browser app without checking companion sync effects\n- switching logging behavior in a way that helps local debugging but breaks backend tracing or support visibility\n- flooding logs with noisy messages that hide the actionable ones\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\n```\n\nFor higher-confidence changes, add the relevant frontend or companion tests, especially when localization sync or logging configuration behavior changes.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) to decide when those cross-boundary checks need to extend further.\n", "0.9": "+++\ntitle = \"Logging and Localization\"\n+++\n\nLogging and localization are both cross-boundary product systems in Sambee.\n\n- Logging affects local debugging, operator visibility, and backend trace collection.\n- Localization affects typed UI copy, locale behavior, browser formatting, and browser-to-companion sync.\n\nTreat both as shared contracts rather than optional polish.\n\n## Logging Model\n\nSambee uses more than one logging surface, but the goal is still one coherent diagnostic story.\n\n### Backend Logging\n\nThe backend sends logs to standard output so they are available through Docker or the process supervisor. Configure the backend in the `[app]` section of `config.toml`:\n\n```toml\n[app]\nlog_level = \"INFO\"\naccess_log_level = \"WARNING\"\nprotocol_log_level = \"WARNING\"\n```\n\n| Key | Controls | Default |\n|---|---|---|\n| `log_level` | Application diagnostics and Uvicorn startup, shutdown, and error messages. | `INFO` |\n| `access_log_level` | Uvicorn HTTP request access records. | `WARNING` |\n| `protocol_log_level` | Uvicorn WebSocket connection, frame, and keepalive records. | `WARNING` |\n\nAll three settings accept `DEBUG`, `INFO`, `WARNING`, or `ERROR`, regardless of case. The default access and protocol levels keep successful requests, WebSocket payloads, and ping traffic out of normal operational logs while retaining application lifecycle and error messages.\n\nSet `access_log_level` to `INFO` when request auditing is needed. Set `protocol_log_level` to `DEBUG` only while diagnosing WebSocket communication; it includes sent and received frames as well as keepalive messages and can be very verbose.\n\n### Browser App Logging\n\nThe browser app supports both:\n\n- Console logging for local development and debugging.\n- Backend tracing for server-side log collection when production or mobile debugging needs it.\n\nThat means a logging change can affect both developer ergonomics and support visibility.\n\n### Companion and Service-Side Logging\n\nThe companion has its own desktop-side logging path, and operational logs are still important on the backend and in local development scripts.\n\n- Use the shared logging utilities where the app already has them.\n- Keep log messages specific enough to be actionable.\n- Avoid replacing structured or filtered logging with scattered ad hoc output.\n\nFor local environment diagnosis, the repo also provides supported log and service-status scripts instead of relying entirely on manual process inspection.\n\n## Localization Model\n\nLocalization is a typed system, not just a string file.\n\n### Sources of Truth\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Typed wrappers | each app's `i18n/index.ts` layer |\n\nEnglish is the source locale, and the pseudo-locale is generated automatically from the English tree.\n\n### Contributor Rules\n\n- Add new UI strings through the translation resources instead of hard-coding copy.\n- Keep translation keys type-safe instead of casting around the type system.\n- Preserve the distinction between UI language and regional formatting behavior.\n- Remember that the browser app can push its effective locale into the companion through the paired localhost API.\n\n## What Contributors Must Preserve\n\n### Logging\n\n- Browser app logging and backend tracing are related but separately configurable.\n- Logging changes should not silently remove trace visibility that support workflows depend on.\n- Diagnostics should stay specific and action-oriented.\n\n### Localization\n\n- Typed keys should remain enforced.\n- Browser-localization behavior and companion-localization sync should keep using effective locale values rather than raw unresolved preferences.\n- App-owned UI text should stay translatable.\n\nFor the concrete contributor workflow, continue to [Localization and Locale Behavior](../localization-and-locale-behavior/).\n\n## Common Failure Modes\n\n- Adding UI text without a translation key.\n- Bypassing typed translation keys with casts.\n- Changing localization behavior in the browser app without checking companion sync effects.\n- Switching logging behavior in a way that helps local debugging but breaks backend tracing or support visibility.\n- Flooding logs with noisy messages that hide the actionable ones.\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\n```\n\nFor higher-confidence changes, add the relevant frontend or companion tests, especially when localization sync or logging configuration behavior changes.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) to decide when those cross-boundary checks need to extend further.", "1.0": "+++\ntitle = \"Logging and Localization\"\n+++\n\nLogging and localization are both cross-boundary product systems in Sambee.\n\n- Logging affects local debugging, operator visibility, and backend trace collection.\n- Localization affects typed UI copy, locale behavior, browser formatting, and browser-to-companion sync.\n\nTreat both as shared contracts rather than optional polish.\n\n## Logging Model\n\nSambee uses more than one logging surface, but the goal is still one coherent diagnostic story.\n\n### Backend Logging\n\nThe backend sends logs to standard output so they are available through Docker or the process supervisor. Configure the backend in the `[app]` section of `config.toml`:\n\n```toml\n[app]\nlog_level = \"INFO\"\naccess_log_level = \"WARNING\"\nprotocol_log_level = \"WARNING\"\n```\n\n| Key | Controls | Default |\n|---|---|---|\n| `log_level` | Application diagnostics and Uvicorn startup, shutdown, and error messages. | `INFO` |\n| `access_log_level` | Uvicorn HTTP request access records. | `WARNING` |\n| `protocol_log_level` | Uvicorn WebSocket connection, frame, and keepalive records. | `WARNING` |\n\nAll three settings accept `DEBUG`, `INFO`, `WARNING`, or `ERROR`, regardless of case. The default access and protocol levels keep successful requests, WebSocket payloads, and ping traffic out of normal operational logs while retaining application lifecycle and error messages.\n\nSet `access_log_level` to `INFO` when request auditing is needed. Set `protocol_log_level` to `DEBUG` only while diagnosing WebSocket communication; it includes sent and received frames as well as keepalive messages and can be very verbose.\n\n### Browser App Logging\n\nThe browser app supports both:\n\n- Console logging for local development and debugging.\n- Backend tracing for server-side log collection when production or mobile debugging needs it.\n\nThat means a logging change can affect both developer ergonomics and support visibility.\n\n### Companion and Service-Side Logging\n\nThe companion has its own desktop-side logging path, and operational logs are still important on the backend and in local development scripts.\n\n- Use the shared logging utilities where the app already has them.\n- Keep log messages specific enough to be actionable.\n- Avoid replacing structured or filtered logging with scattered ad hoc output.\n\nFor local environment diagnosis, the repo also provides supported log and service-status scripts instead of relying entirely on manual process inspection.\n\n## Localization Model\n\nLocalization is a typed system, not just a string file.\n\n### Sources of Truth\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Typed wrappers | each app's `i18n/index.ts` layer |\n\nEnglish is the source locale, and the pseudo-locale is generated automatically from the English tree.\n\n### Contributor Rules\n\n- Add new UI strings through the translation resources instead of hard-coding copy.\n- Keep translation keys type-safe instead of casting around the type system.\n- Preserve the distinction between UI language and regional formatting behavior.\n- Remember that the browser app can push its effective locale into the companion through the paired localhost API.\n\n## What Contributors Must Preserve\n\n### Logging\n\n- Browser app logging and backend tracing are related but separately configurable.\n- Logging changes should not silently remove trace visibility that support workflows depend on.\n- Diagnostics should stay specific and action-oriented.\n\n### Localization\n\n- Typed keys should remain enforced.\n- Browser-localization behavior and companion-localization sync should keep using effective locale values rather than raw unresolved preferences.\n- App-owned UI text should stay translatable.\n\nFor the concrete contributor workflow, continue to [Localization and Locale Behavior](../localization-and-locale-behavior/).\n\n## Common Failure Modes\n\n- Adding UI text without a translation key.\n- Bypassing typed translation keys with casts.\n- Changing localization behavior in the browser app without checking companion sync effects.\n- Switching logging behavior in a way that helps local debugging but breaks backend tracing or support visibility.\n- Flooding logs with noisy messages that hide the actionable ones.\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\n```\n\nFor higher-confidence changes, add the relevant frontend or companion tests, especially when localization sync or logging configuration behavior changes.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) to decide when those cross-boundary checks need to extend further.", "2.0": "+++\ntitle = \"Logging and Localization\"\n+++\n\nLogging and localization are both cross-boundary product systems in Sambee.\n\n- Logging affects local debugging, operator visibility, and backend trace collection.\n- Localization affects typed UI copy, locale behavior, browser formatting, and browser-to-companion sync.\n\nTreat both as shared contracts rather than optional polish.\n\n## Logging Model\n\nSambee uses more than one logging surface, but the goal is still one coherent diagnostic story.\n\n### Backend Logging\n\nThe backend sends logs to standard output so they are available through Docker or the process supervisor. Configure the backend in the `[app]` section of `config.toml`:\n\n```toml\n[app]\nlog_level = \"INFO\"\naccess_log_level = \"WARNING\"\nprotocol_log_level = \"WARNING\"\n```\n\n| Key | Controls | Default |\n|---|---|---|\n| `log_level` | Application diagnostics and Uvicorn startup, shutdown, and error messages. | `INFO` |\n| `access_log_level` | Uvicorn HTTP request access records. | `WARNING` |\n| `protocol_log_level` | Uvicorn WebSocket connection, frame, and keepalive records. | `WARNING` |\n\nAll three settings accept `DEBUG`, `INFO`, `WARNING`, or `ERROR`, regardless of case. The default access and protocol levels keep successful requests, WebSocket payloads, and ping traffic out of normal operational logs while retaining application lifecycle and error messages.\n\nSet `access_log_level` to `INFO` when request auditing is needed. Set `protocol_log_level` to `DEBUG` only while diagnosing WebSocket communication; it includes sent and received frames as well as keepalive messages and can be very verbose.\n\n### Browser App Logging\n\nThe browser app supports both:\n\n- Console logging for local development and debugging.\n- Backend tracing for server-side log collection when production or mobile debugging needs it.\n\nThat means a logging change can affect both developer ergonomics and support visibility.\n\n### Companion and Service-Side Logging\n\nThe companion has its own desktop-side logging path, and operational logs are still important on the backend and in local development scripts.\n\n- Use the shared logging utilities where the app already has them.\n- Keep log messages specific enough to be actionable.\n- Avoid replacing structured or filtered logging with scattered ad hoc output.\n\nFor local environment diagnosis, the repo also provides supported log and service-status scripts instead of relying entirely on manual process inspection.\n\n## Localization Model\n\nLocalization is a typed system, not just a string file.\n\n### Sources of Truth\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Typed wrappers | each app's `i18n/index.ts` layer |\n\nEnglish is the source locale, and the pseudo-locale is generated automatically from the English tree.\n\n### Contributor Rules\n\n- Add new UI strings through the translation resources instead of hard-coding copy.\n- Keep translation keys type-safe instead of casting around the type system.\n- Preserve the distinction between UI language and regional formatting behavior.\n- Remember that the browser app can push its effective locale into the companion through the paired localhost API.\n\n## What Contributors Must Preserve\n\n### Logging\n\n- Browser app logging and backend tracing are related but separately configurable.\n- Logging changes should not silently remove trace visibility that support workflows depend on.\n- Diagnostics should stay specific and action-oriented.\n\n### Localization\n\n- Typed keys should remain enforced.\n- Browser-localization behavior and companion-localization sync should keep using effective locale values rather than raw unresolved preferences.\n- App-owned UI text should stay translatable.\n\nFor the concrete contributor workflow, continue to [Localization and Locale Behavior](../localization-and-locale-behavior/).\n\n## Common Failure Modes\n\n- Adding UI text without a translation key.\n- Bypassing typed translation keys with casts.\n- Changing localization behavior in the browser app without checking companion sync effects.\n- Switching logging behavior in a way that helps local debugging but breaks backend tracing or support visibility.\n- Flooding logs with noisy messages that hide the actionable ones.\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit\ncd companion \u0026\u0026 npm run lint\n```\n\nFor higher-confidence changes, add the relevant frontend or companion tests, especially when localization sync or logging configuration behavior changes.\n\nUse [Test Strategy Overview](../../testing-and-quality-gates/test-strategy-overview/) to decide when those cross-boundary checks need to extend further."}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/cross-cutting-systems/localization-and-locale-behavior", "parent_id": "section:developer-guide/cross-cutting-systems", "depth": 2, "kind": "page", "label": "localization-and-locale-behavior", "title": "Localization And Locale Behavior", "path": "developer-guide/cross-cutting-systems/localization-and-locale-behavior", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Localization and Locale Behavior\"\n+++\n\nLocalization in Sambee is a typed cross-app system. It affects UI copy, browser formatting, and browser-to-companion behavior.\n\nUse this page when you are adding copy, changing locale behavior, or touching browser-to-companion localization sync.\n\n## Sources of Truth\n\nThese files own the localization model:\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Browser app typed wrapper | `frontend/src/i18n/index.ts` |\n| Companion typed wrapper | `companion/src/i18n/index.ts` |\n\nEnglish is the source locale.\n\nThe pseudo-locale `en-XA` is generated from the English translation tree. Do not edit pseudo-locale strings manually.\n\n## Adding New UI Copy\n\nWhen you add new copy:\n\n1. add the English key to the relevant `EN_TRANSLATIONS` tree\n2. use that key from UI code instead of hard-coding a string\n3. use the existing translation access pattern for the surface you are editing\n4. add or extend tests when the copy sits in a reused or high-risk surface\n\nTypical access patterns are:\n\n- browser app React components: `useTranslation()`\n- browser app non-component helpers or config: `translate(...)`\n- companion components: `useI18n()` or `translate(...)`\n\n## Type-Safety Rules\n\nTyped translation keys are part of the contract.\n\n- translation keys are type-checked through the i18n type layer\n- invalid keys should fail TypeScript compilation\n- do not bypass that with casts to `string` or `any`\n- keep wrapper signatures typed instead of weakening them for convenience\n\nIf localization typing becomes optional, contributors lose one of the main protections against copy drift and key mismatches.\n\n## Compile-Time Guard Fixtures\n\nThese files exist specifically to catch regressions in localization typing:\n\n- `frontend/src/i18n/__tests__/typecheck.ts`\n- `companion/src/i18n/__tests__/typecheck.ts`\n\nThey intentionally include both:\n\n- valid translation calls that must compile\n- invalid keys marked with `@ts-expect-error` that must stay invalid\n\nIf a change weakens typed keys, these fixtures should fail type checking.\n\n## Language Versus Regional Formatting\n\nSambee separates UI language from regional formatting.\n\n- language decides which translated copy the UI shows\n- regional formatting decides how dates, numbers, and sorting behave\n\nThat split matters because users may want English UI with non-US formatting, or any other mixed combination the product supports.\n\n## Preference Storage Rules\n\nFrontend language and regional formatting preferences are stored separately.\n\n- language preference lives in `localization.language` in current-user settings and is mirrored in local storage under the app locale key\n- regional formatting preference lives in `localization.regional_locale` in current-user settings and is mirrored in local storage under `sambee.regional-locale`\n- `browser` is the default for both preferences\n\n`browser` means:\n\n- UI language resolves from the browser locale list against the supported translation set\n- regional formatting resolves from the browser locale while preserving variants such as `en-GB` versus `en-US`\n\n## Runtime Locale Behavior\n\nBoth apps keep document locale metadata aligned with the active locale.\n\n- `document.documentElement.lang` stays synchronized\n- text direction stays synchronized through `dir`\n\nFrontend date, number, and sorting behavior should use the locale-aware helpers instead of raw browser-default formatting.\n\nPrefer:\n\n- `frontend/src/utils/localeFormatting.ts`\n\nFrontend React trees that depend on localization preferences should be wrapped in:\n\n- `frontend/src/i18n/LocalePreferencesProvider.tsx`\n\nThe user-facing preferences UI lives in:\n\n- `frontend/src/pages/PreferencesSettings.tsx`\n\n## Browser-to-Companion Localization Sync\n\nWhen the browser is paired with Sambee Companion, the browser pushes its effective localization state to the companion over the authenticated localhost API.\n\nImportant rules:\n\n- sync uses concrete effective locale values, not unresolved `browser` preferences\n- the companion therefore receives resolved values such as `en` or `en-GB`\n- companion localization is persisted on the Rust side and mirrored into companion local storage for fast startup\n- synchronization is global within the desktop app\n- last-writer-wins behavior is based on the browser-provided `updated_at` timestamp\n- persisted companion state also records the source browser origin\n- open companion windows listen for localization update events and apply the new locale immediately\n\nIf you change the browser-side locale model, you must check the companion sync path too.\n\n## Scope Rules\n\n- translate app-owned UI strings\n- do not translate raw backend error payloads or third-party library messages unless Sambee wraps them in its own copy\n- decorative glyphs are fine when they are not the only user-facing label\n\n## Common Failure Modes\n\n- adding UI text without a translation key\n- weakening typed-key enforcement with casts\n- changing browser locale behavior without checking companion sync\n- treating language preference and formatting preference as the same value\n- using browser-default formatting instead of the shared locale-aware helpers\n\n## Validation Expectations\n\nFor routine localization changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nFor higher-confidence UI changes, also run the relevant frontend or companion tests.\n\nFor browser-to-companion localization sync changes, also validate:\n\n```bash\ncd frontend \u0026\u0026 npm test -- src/services/__tests__/companionService.test.ts\ncd companion \u0026\u0026 npm test -- src/i18n/__tests__/index.test.ts src/components/__tests__/Preferences.test.tsx\n```\n", "0.8": "+++\ntitle = \"Localization and Locale Behavior\"\n+++\n\nLocalization in Sambee is a typed cross-app system. It affects UI copy, browser formatting, and browser-to-companion behavior.\n\nUse this page when you are adding copy, changing locale behavior, or touching browser-to-companion localization sync.\n\n## Sources of Truth\n\nThese files own the localization model:\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Browser app typed wrapper | `frontend/src/i18n/index.ts` |\n| Companion typed wrapper | `companion/src/i18n/index.ts` |\n\nEnglish is the source locale.\n\nThe pseudo-locale `en-XA` is generated from the English translation tree. Do not edit pseudo-locale strings manually.\n\n## Adding New UI Copy\n\nWhen you add new copy:\n\n1. add the English key to the relevant `EN_TRANSLATIONS` tree\n2. use that key from UI code instead of hard-coding a string\n3. use the existing translation access pattern for the surface you are editing\n4. add or extend tests when the copy sits in a reused or high-risk surface\n\nTypical access patterns are:\n\n- browser app React components: `useTranslation()`\n- browser app non-component helpers or config: `translate(...)`\n- companion components: `useI18n()` or `translate(...)`\n\n## Type-Safety Rules\n\nTyped translation keys are part of the contract.\n\n- translation keys are type-checked through the i18n type layer\n- invalid keys should fail TypeScript compilation\n- do not bypass that with casts to `string` or `any`\n- keep wrapper signatures typed instead of weakening them for convenience\n\nIf localization typing becomes optional, contributors lose one of the main protections against copy drift and key mismatches.\n\n## Compile-Time Guard Fixtures\n\nThese files exist specifically to catch regressions in localization typing:\n\n- `frontend/src/i18n/__tests__/typecheck.ts`\n- `companion/src/i18n/__tests__/typecheck.ts`\n\nThey intentionally include both:\n\n- valid translation calls that must compile\n- invalid keys marked with `@ts-expect-error` that must stay invalid\n\nIf a change weakens typed keys, these fixtures should fail type checking.\n\n## Language Versus Regional Formatting\n\nSambee separates UI language from regional formatting.\n\n- language decides which translated copy the UI shows\n- regional formatting decides how dates, numbers, and sorting behave\n\nThat split matters because users may want English UI with non-US formatting, or any other mixed combination the product supports.\n\n## Preference Storage Rules\n\nFrontend language and regional formatting preferences are stored separately.\n\n- language preference lives in `localization.language` in current-user settings and is mirrored in local storage under the app locale key\n- regional formatting preference lives in `localization.regional_locale` in current-user settings and is mirrored in local storage under `sambee.regional-locale`\n- `browser` is the default for both preferences\n\n`browser` means:\n\n- UI language resolves from the browser locale list against the supported translation set\n- regional formatting resolves from the browser locale while preserving variants such as `en-GB` versus `en-US`\n\n## Runtime Locale Behavior\n\nBoth apps keep document locale metadata aligned with the active locale.\n\n- `document.documentElement.lang` stays synchronized\n- text direction stays synchronized through `dir`\n\nFrontend date, number, and sorting behavior should use the locale-aware helpers instead of raw browser-default formatting.\n\nPrefer:\n\n- `frontend/src/utils/localeFormatting.ts`\n\nFrontend React trees that depend on localization preferences should be wrapped in:\n\n- `frontend/src/i18n/LocalePreferencesProvider.tsx`\n\nThe user-facing preferences UI lives in:\n\n- `frontend/src/pages/PreferencesSettings.tsx`\n\n## Browser-to-Companion Localization Sync\n\nWhen the browser is paired with Sambee Companion, the browser pushes its effective localization state to the companion over the authenticated localhost API.\n\nImportant rules:\n\n- sync uses concrete effective locale values, not unresolved `browser` preferences\n- the companion therefore receives resolved values such as `en` or `en-GB`\n- companion localization is persisted on the Rust side and mirrored into companion local storage for fast startup\n- synchronization is global within the desktop app\n- last-writer-wins behavior is based on the browser-provided `updated_at` timestamp\n- persisted companion state also records the source browser origin\n- open companion windows listen for localization update events and apply the new locale immediately\n\nIf you change the browser-side locale model, you must check the companion sync path too.\n\n## Scope Rules\n\n- translate app-owned UI strings\n- do not translate raw backend error payloads or third-party library messages unless Sambee wraps them in its own copy\n- decorative glyphs are fine when they are not the only user-facing label\n\n## Common Failure Modes\n\n- adding UI text without a translation key\n- weakening typed-key enforcement with casts\n- changing browser locale behavior without checking companion sync\n- treating language preference and formatting preference as the same value\n- using browser-default formatting instead of the shared locale-aware helpers\n\n## Validation Expectations\n\nFor routine localization changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nFor higher-confidence UI changes, also run the relevant frontend or companion tests.\n\nFor browser-to-companion localization sync changes, also validate:\n\n```bash\ncd frontend \u0026\u0026 npm test -- src/services/__tests__/companionService.test.ts\ncd companion \u0026\u0026 npm test -- src/i18n/__tests__/index.test.ts src/components/__tests__/Preferences.test.tsx\n```\n", "0.9": "+++\ntitle = \"Localization and Locale Behavior\"\n+++\n\nLocalization in Sambee is a typed cross-app system. It affects UI copy, browser formatting, and browser-to-companion behavior.\n\nUse this page when you are adding copy, changing locale behavior, or touching browser-to-companion localization sync.\n\n## Sources of Truth\n\nThese files own the localization model:\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Browser app typed wrapper | `frontend/src/i18n/index.ts` |\n| Companion typed wrapper | `companion/src/i18n/index.ts` |\n\nEnglish is the source locale.\n\nThe pseudo-locale `en-XA` is generated from the English translation tree. Do not edit pseudo-locale strings manually.\n\n## Adding New UI Copy\n\nWhen you add new copy:\n\n1. add the English key to the relevant `EN_TRANSLATIONS` tree\n2. use that key from UI code instead of hard-coding a string\n3. use the existing translation access pattern for the surface you are editing\n4. add or extend tests when the copy sits in a reused or high-risk surface\n\nTypical access patterns are:\n\n- browser app React components: `useTranslation()`\n- browser app non-component helpers or config: `translate(...)`\n- companion components: `useI18n()` or `translate(...)`\n\n## Type-Safety Rules\n\nTyped translation keys are part of the contract.\n\n- translation keys are type-checked through the i18n type layer\n- invalid keys should fail TypeScript compilation\n- do not bypass that with casts to `string` or `any`\n- keep wrapper signatures typed instead of weakening them for convenience\n\nIf localization typing becomes optional, contributors lose one of the main protections against copy drift and key mismatches.\n\n## Compile-Time Guard Fixtures\n\nThese files exist specifically to catch regressions in localization typing:\n\n- `frontend/src/i18n/__tests__/typecheck.ts`\n- `companion/src/i18n/__tests__/typecheck.ts`\n\nThey intentionally include both:\n\n- valid translation calls that must compile\n- invalid keys marked with `@ts-expect-error` that must stay invalid\n\nIf a change weakens typed keys, these fixtures should fail type checking.\n\n## Language Versus Regional Formatting\n\nSambee separates UI language from regional formatting.\n\n- language decides which translated copy the UI shows\n- regional formatting decides how dates, numbers, and sorting behave\n\nThat split matters because users may want English UI with non-US formatting, or any other mixed combination the product supports.\n\n## Preference Storage Rules\n\nFrontend language and regional formatting preferences are stored separately.\n\n- language preference lives in `localization.language` in current-user settings and is mirrored in local storage under the app locale key\n- regional formatting preference lives in `localization.regional_locale` in current-user settings and is mirrored in local storage under `sambee.regional-locale`\n- `browser` is the default for both preferences\n\n`browser` means:\n\n- UI language resolves from the browser locale list against the supported translation set\n- regional formatting resolves from the browser locale while preserving variants such as `en-GB` versus `en-US`\n\n## Runtime Locale Behavior\n\nBoth apps keep document locale metadata aligned with the active locale.\n\n- `document.documentElement.lang` stays synchronized\n- text direction stays synchronized through `dir`\n\nFrontend date, number, and sorting behavior should use the locale-aware helpers instead of raw browser-default formatting.\n\nPrefer:\n\n- `frontend/src/utils/localeFormatting.ts`\n\nFrontend React trees that depend on localization preferences should be wrapped in:\n\n- `frontend/src/i18n/LocalePreferencesProvider.tsx`\n\nThe user-facing preferences UI lives in:\n\n- `frontend/src/pages/PreferencesSettings.tsx`\n\n## Browser-to-Companion Localization Sync\n\nWhen the browser is paired with Sambee Companion, the browser pushes its effective localization state to the companion over the authenticated localhost API.\n\nImportant rules:\n\n- sync uses concrete effective locale values, not unresolved `browser` preferences\n- the companion therefore receives resolved values such as `en` or `en-GB`\n- companion localization is persisted on the Rust side and mirrored into companion local storage for fast startup\n- synchronization is global within the desktop app\n- last-writer-wins behavior is based on the browser-provided `updated_at` timestamp\n- persisted companion state also records the source browser origin\n- open companion windows listen for localization update events and apply the new locale immediately\n\nIf you change the browser-side locale model, you must check the companion sync path too.\n\n## Scope Rules\n\n- translate app-owned UI strings\n- do not translate raw backend error payloads or third-party library messages unless Sambee wraps them in its own copy\n- decorative glyphs are fine when they are not the only user-facing label\n\n## Common Failure Modes\n\n- adding UI text without a translation key\n- weakening typed-key enforcement with casts\n- changing browser locale behavior without checking companion sync\n- treating language preference and formatting preference as the same value\n- using browser-default formatting instead of the shared locale-aware helpers\n\n## Validation Expectations\n\nFor routine localization changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nFor higher-confidence UI changes, also run the relevant frontend or companion tests.\n\nFor browser-to-companion localization sync changes, also validate:\n\n```bash\ncd frontend \u0026\u0026 npm test -- src/services/__tests__/companionService.test.ts\ncd companion \u0026\u0026 npm test -- src/i18n/__tests__/index.test.ts src/components/__tests__/Preferences.test.tsx\n```\n", "1.0": "+++\ntitle = \"Localization and Locale Behavior\"\n+++\n\nLocalization in Sambee is a typed cross-app system. It affects UI copy, browser formatting, and browser-to-companion behavior.\n\nUse this page when you are adding copy, changing locale behavior, or touching browser-to-companion localization sync.\n\n## Sources of Truth\n\nThese files own the localization model:\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Browser app typed wrapper | `frontend/src/i18n/index.ts` |\n| Companion typed wrapper | `companion/src/i18n/index.ts` |\n\nEnglish is the source locale.\n\nThe pseudo-locale `en-XA` is generated from the English translation tree. Do not edit pseudo-locale strings manually.\n\n## Adding New UI Copy\n\nWhen you add new copy:\n\n1. add the English key to the relevant `EN_TRANSLATIONS` tree\n2. use that key from UI code instead of hard-coding a string\n3. use the existing translation access pattern for the surface you are editing\n4. add or extend tests when the copy sits in a reused or high-risk surface\n\nTypical access patterns are:\n\n- browser app React components: `useTranslation()`\n- browser app non-component helpers or config: `translate(...)`\n- companion components: `useI18n()` or `translate(...)`\n\n## Type-Safety Rules\n\nTyped translation keys are part of the contract.\n\n- translation keys are type-checked through the i18n type layer\n- invalid keys should fail TypeScript compilation\n- do not bypass that with casts to `string` or `any`\n- keep wrapper signatures typed instead of weakening them for convenience\n\nIf localization typing becomes optional, contributors lose one of the main protections against copy drift and key mismatches.\n\n## Compile-Time Guard Fixtures\n\nThese files exist specifically to catch regressions in localization typing:\n\n- `frontend/src/i18n/__tests__/typecheck.ts`\n- `companion/src/i18n/__tests__/typecheck.ts`\n\nThey intentionally include both:\n\n- valid translation calls that must compile\n- invalid keys marked with `@ts-expect-error` that must stay invalid\n\nIf a change weakens typed keys, these fixtures should fail type checking.\n\n## Language Versus Regional Formatting\n\nSambee separates UI language from regional formatting.\n\n- language decides which translated copy the UI shows\n- regional formatting decides how dates, numbers, and sorting behave\n\nThat split matters because users may want English UI with non-US formatting, or any other mixed combination the product supports.\n\n## Preference Storage Rules\n\nFrontend language and regional formatting preferences are stored separately.\n\n- language preference lives in `localization.language` in current-user settings and is mirrored in local storage under the app locale key\n- regional formatting preference lives in `localization.regional_locale` in current-user settings and is mirrored in local storage under `sambee.regional-locale`\n- `browser` is the default for both preferences\n\n`browser` means:\n\n- UI language resolves from the browser locale list against the supported translation set\n- regional formatting resolves from the browser locale while preserving variants such as `en-GB` versus `en-US`\n\n## Runtime Locale Behavior\n\nBoth apps keep document locale metadata aligned with the active locale.\n\n- `document.documentElement.lang` stays synchronized\n- text direction stays synchronized through `dir`\n\nFrontend date, number, and sorting behavior should use the locale-aware helpers instead of raw browser-default formatting.\n\nPrefer:\n\n- `frontend/src/utils/localeFormatting.ts`\n\nFrontend React trees that depend on localization preferences should be wrapped in:\n\n- `frontend/src/i18n/LocalePreferencesProvider.tsx`\n\nThe user-facing preferences UI lives in:\n\n- `frontend/src/pages/PreferencesSettings.tsx`\n\n## Browser-to-Companion Localization Sync\n\nWhen the browser is paired with Sambee Companion, the browser pushes its effective localization state to the companion over the authenticated localhost API.\n\nImportant rules:\n\n- sync uses concrete effective locale values, not unresolved `browser` preferences\n- the companion therefore receives resolved values such as `en` or `en-GB`\n- companion localization is persisted on the Rust side and mirrored into companion local storage for fast startup\n- synchronization is global within the desktop app\n- last-writer-wins behavior is based on the browser-provided `updated_at` timestamp\n- persisted companion state also records the source browser origin\n- open companion windows listen for localization update events and apply the new locale immediately\n\nIf you change the browser-side locale model, you must check the companion sync path too.\n\n## Scope Rules\n\n- translate app-owned UI strings\n- do not translate raw backend error payloads or third-party library messages unless Sambee wraps them in its own copy\n- decorative glyphs are fine when they are not the only user-facing label\n\n## Common Failure Modes\n\n- adding UI text without a translation key\n- weakening typed-key enforcement with casts\n- changing browser locale behavior without checking companion sync\n- treating language preference and formatting preference as the same value\n- using browser-default formatting instead of the shared locale-aware helpers\n\n## Validation Expectations\n\nFor routine localization changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nFor higher-confidence UI changes, also run the relevant frontend or companion tests.\n\nFor browser-to-companion localization sync changes, also validate:\n\n```bash\ncd frontend \u0026\u0026 npm test -- src/services/__tests__/companionService.test.ts\ncd companion \u0026\u0026 npm test -- src/i18n/__tests__/index.test.ts src/components/__tests__/Preferences.test.tsx\n```\n", "2.0": "+++\ntitle = \"Localization and Locale Behavior\"\n+++\n\nLocalization in Sambee is a typed cross-app system. It affects UI copy, browser formatting, and browser-to-companion behavior.\n\nUse this page when you are adding copy, changing locale behavior, or touching browser-to-companion localization sync.\n\n## Sources of Truth\n\nThese files own the localization model:\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Browser app typed wrapper | `frontend/src/i18n/index.ts` |\n| Companion typed wrapper | `companion/src/i18n/index.ts` |\n\nEnglish is the source locale.\n\nThe pseudo-locale `en-XA` is generated from the English translation tree. Do not edit pseudo-locale strings manually.\n\n## Adding New UI Copy\n\nWhen you add new copy:\n\n1. add the English key to the relevant `EN_TRANSLATIONS` tree\n2. use that key from UI code instead of hard-coding a string\n3. use the existing translation access pattern for the surface you are editing\n4. add or extend tests when the copy sits in a reused or high-risk surface\n\nTypical access patterns are:\n\n- browser app React components: `useTranslation()`\n- browser app non-component helpers or config: `translate(...)`\n- companion components: `useI18n()` or `translate(...)`\n\n## Type-Safety Rules\n\nTyped translation keys are part of the contract.\n\n- translation keys are type-checked through the i18n type layer\n- invalid keys should fail TypeScript compilation\n- do not bypass that with casts to `string` or `any`\n- keep wrapper signatures typed instead of weakening them for convenience\n\nIf localization typing becomes optional, contributors lose one of the main protections against copy drift and key mismatches.\n\n## Compile-Time Guard Fixtures\n\nThese files exist specifically to catch regressions in localization typing:\n\n- `frontend/src/i18n/__tests__/typecheck.ts`\n- `companion/src/i18n/__tests__/typecheck.ts`\n\nThey intentionally include both:\n\n- valid translation calls that must compile\n- invalid keys marked with `@ts-expect-error` that must stay invalid\n\nIf a change weakens typed keys, these fixtures should fail type checking.\n\n## Language Versus Regional Formatting\n\nSambee separates UI language from regional formatting.\n\n- language decides which translated copy the UI shows\n- regional formatting decides how dates, numbers, and sorting behave\n\nThat split matters because users may want English UI with non-US formatting, or any other mixed combination the product supports.\n\n## Preference Storage Rules\n\nFrontend language and regional formatting preferences are stored separately.\n\n- language preference lives in `localization.language` in current-user settings and is mirrored in local storage under the app locale key\n- regional formatting preference lives in `localization.regional_locale` in current-user settings and is mirrored in local storage under `sambee.regional-locale`\n- `browser` is the default for both preferences\n\n`browser` means:\n\n- UI language resolves from the browser locale list against the supported translation set\n- regional formatting resolves from the browser locale while preserving variants such as `en-GB` versus `en-US`\n\n## Runtime Locale Behavior\n\nBoth apps keep document locale metadata aligned with the active locale.\n\n- `document.documentElement.lang` stays synchronized\n- text direction stays synchronized through `dir`\n\nFrontend date, number, and sorting behavior should use the locale-aware helpers instead of raw browser-default formatting.\n\nPrefer:\n\n- `frontend/src/utils/localeFormatting.ts`\n\nFrontend React trees that depend on localization preferences should be wrapped in:\n\n- `frontend/src/i18n/LocalePreferencesProvider.tsx`\n\nThe user-facing preferences UI lives in:\n\n- `frontend/src/pages/PreferencesSettings.tsx`\n\n## Browser-to-Companion Localization Sync\n\nWhen the browser is paired with Sambee Companion, the browser pushes its effective localization state to the companion over the authenticated localhost API.\n\nImportant rules:\n\n- sync uses concrete effective locale values, not unresolved `browser` preferences\n- the companion therefore receives resolved values such as `en` or `en-GB`\n- companion localization is persisted on the Rust side and mirrored into companion local storage for fast startup\n- synchronization is global within the desktop app\n- last-writer-wins behavior is based on the browser-provided `updated_at` timestamp\n- persisted companion state also records the source browser origin\n- open companion windows listen for localization update events and apply the new locale immediately\n\nIf you change the browser-side locale model, you must check the companion sync path too.\n\n## Scope Rules\n\n- translate app-owned UI strings\n- do not translate raw backend error payloads or third-party library messages unless Sambee wraps them in its own copy\n- decorative glyphs are fine when they are not the only user-facing label\n\n## Common Failure Modes\n\n- adding UI text without a translation key\n- weakening typed-key enforcement with casts\n- changing browser locale behavior without checking companion sync\n- treating language preference and formatting preference as the same value\n- using browser-default formatting instead of the shared locale-aware helpers\n\n## Validation Expectations\n\nFor routine localization changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nFor higher-confidence UI changes, also run the relevant frontend or companion tests.\n\nFor browser-to-companion localization sync changes, also validate:\n\n```bash\ncd frontend \u0026\u0026 npm test -- src/services/__tests__/companionService.test.ts\ncd companion \u0026\u0026 npm test -- src/i18n/__tests__/index.test.ts src/components/__tests__/Preferences.test.tsx\n```\n"}, "page_contents": {"0.7": "+++\ntitle = \"Localization and Locale Behavior\"\n+++\n\nLocalization in Sambee is a typed cross-app system. It affects UI copy, browser formatting, and browser-to-companion behavior.\n\nUse this page when you are adding copy, changing locale behavior, or touching browser-to-companion localization sync.\n\n## Sources of Truth\n\nThese files own the localization model:\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Browser app typed wrapper | `frontend/src/i18n/index.ts` |\n| Companion typed wrapper | `companion/src/i18n/index.ts` |\n\nEnglish is the source locale.\n\nThe pseudo-locale `en-XA` is generated from the English translation tree. Do not edit pseudo-locale strings manually.\n\n## Adding New UI Copy\n\nWhen you add new copy:\n\n1. add the English key to the relevant `EN_TRANSLATIONS` tree\n2. use that key from UI code instead of hard-coding a string\n3. use the existing translation access pattern for the surface you are editing\n4. add or extend tests when the copy sits in a reused or high-risk surface\n\nTypical access patterns are:\n\n- browser app React components: `useTranslation()`\n- browser app non-component helpers or config: `translate(...)`\n- companion components: `useI18n()` or `translate(...)`\n\n## Type-Safety Rules\n\nTyped translation keys are part of the contract.\n\n- translation keys are type-checked through the i18n type layer\n- invalid keys should fail TypeScript compilation\n- do not bypass that with casts to `string` or `any`\n- keep wrapper signatures typed instead of weakening them for convenience\n\nIf localization typing becomes optional, contributors lose one of the main protections against copy drift and key mismatches.\n\n## Compile-Time Guard Fixtures\n\nThese files exist specifically to catch regressions in localization typing:\n\n- `frontend/src/i18n/__tests__/typecheck.ts`\n- `companion/src/i18n/__tests__/typecheck.ts`\n\nThey intentionally include both:\n\n- valid translation calls that must compile\n- invalid keys marked with `@ts-expect-error` that must stay invalid\n\nIf a change weakens typed keys, these fixtures should fail type checking.\n\n## Language Versus Regional Formatting\n\nSambee separates UI language from regional formatting.\n\n- language decides which translated copy the UI shows\n- regional formatting decides how dates, numbers, and sorting behave\n\nThat split matters because users may want English UI with non-US formatting, or any other mixed combination the product supports.\n\n## Preference Storage Rules\n\nFrontend language and regional formatting preferences are stored separately.\n\n- language preference lives in `localization.language` in current-user settings and is mirrored in local storage under the app locale key\n- regional formatting preference lives in `localization.regional_locale` in current-user settings and is mirrored in local storage under `sambee.regional-locale`\n- `browser` is the default for both preferences\n\n`browser` means:\n\n- UI language resolves from the browser locale list against the supported translation set\n- regional formatting resolves from the browser locale while preserving variants such as `en-GB` versus `en-US`\n\n## Runtime Locale Behavior\n\nBoth apps keep document locale metadata aligned with the active locale.\n\n- `document.documentElement.lang` stays synchronized\n- text direction stays synchronized through `dir`\n\nFrontend date, number, and sorting behavior should use the locale-aware helpers instead of raw browser-default formatting.\n\nPrefer:\n\n- `frontend/src/utils/localeFormatting.ts`\n\nFrontend React trees that depend on localization preferences should be wrapped in:\n\n- `frontend/src/i18n/LocalePreferencesProvider.tsx`\n\nThe user-facing preferences UI lives in:\n\n- `frontend/src/pages/PreferencesSettings.tsx`\n\n## Browser-to-Companion Localization Sync\n\nWhen the browser is paired with Sambee Companion, the browser pushes its effective localization state to the companion over the authenticated localhost API.\n\nImportant rules:\n\n- sync uses concrete effective locale values, not unresolved `browser` preferences\n- the companion therefore receives resolved values such as `en` or `en-GB`\n- companion localization is persisted on the Rust side and mirrored into companion local storage for fast startup\n- synchronization is global within the desktop app\n- last-writer-wins behavior is based on the browser-provided `updated_at` timestamp\n- persisted companion state also records the source browser origin\n- open companion windows listen for localization update events and apply the new locale immediately\n\nIf you change the browser-side locale model, you must check the companion sync path too.\n\n## Scope Rules\n\n- translate app-owned UI strings\n- do not translate raw backend error payloads or third-party library messages unless Sambee wraps them in its own copy\n- decorative glyphs are fine when they are not the only user-facing label\n\n## Common Failure Modes\n\n- adding UI text without a translation key\n- weakening typed-key enforcement with casts\n- changing browser locale behavior without checking companion sync\n- treating language preference and formatting preference as the same value\n- using browser-default formatting instead of the shared locale-aware helpers\n\n## Validation Expectations\n\nFor routine localization changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nFor higher-confidence UI changes, also run the relevant frontend or companion tests.\n\nFor browser-to-companion localization sync changes, also validate:\n\n```bash\ncd frontend \u0026\u0026 npm test -- src/services/__tests__/companionService.test.ts\ncd companion \u0026\u0026 npm test -- src/i18n/__tests__/index.test.ts src/components/__tests__/Preferences.test.tsx\n```\n", "0.8": "+++\ntitle = \"Localization and Locale Behavior\"\n+++\n\nLocalization in Sambee is a typed cross-app system. It affects UI copy, browser formatting, and browser-to-companion behavior.\n\nUse this page when you are adding copy, changing locale behavior, or touching browser-to-companion localization sync.\n\n## Sources of Truth\n\nThese files own the localization model:\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Browser app typed wrapper | `frontend/src/i18n/index.ts` |\n| Companion typed wrapper | `companion/src/i18n/index.ts` |\n\nEnglish is the source locale.\n\nThe pseudo-locale `en-XA` is generated from the English translation tree. Do not edit pseudo-locale strings manually.\n\n## Adding New UI Copy\n\nWhen you add new copy:\n\n1. add the English key to the relevant `EN_TRANSLATIONS` tree\n2. use that key from UI code instead of hard-coding a string\n3. use the existing translation access pattern for the surface you are editing\n4. add or extend tests when the copy sits in a reused or high-risk surface\n\nTypical access patterns are:\n\n- browser app React components: `useTranslation()`\n- browser app non-component helpers or config: `translate(...)`\n- companion components: `useI18n()` or `translate(...)`\n\n## Type-Safety Rules\n\nTyped translation keys are part of the contract.\n\n- translation keys are type-checked through the i18n type layer\n- invalid keys should fail TypeScript compilation\n- do not bypass that with casts to `string` or `any`\n- keep wrapper signatures typed instead of weakening them for convenience\n\nIf localization typing becomes optional, contributors lose one of the main protections against copy drift and key mismatches.\n\n## Compile-Time Guard Fixtures\n\nThese files exist specifically to catch regressions in localization typing:\n\n- `frontend/src/i18n/__tests__/typecheck.ts`\n- `companion/src/i18n/__tests__/typecheck.ts`\n\nThey intentionally include both:\n\n- valid translation calls that must compile\n- invalid keys marked with `@ts-expect-error` that must stay invalid\n\nIf a change weakens typed keys, these fixtures should fail type checking.\n\n## Language Versus Regional Formatting\n\nSambee separates UI language from regional formatting.\n\n- language decides which translated copy the UI shows\n- regional formatting decides how dates, numbers, and sorting behave\n\nThat split matters because users may want English UI with non-US formatting, or any other mixed combination the product supports.\n\n## Preference Storage Rules\n\nFrontend language and regional formatting preferences are stored separately.\n\n- language preference lives in `localization.language` in current-user settings and is mirrored in local storage under the app locale key\n- regional formatting preference lives in `localization.regional_locale` in current-user settings and is mirrored in local storage under `sambee.regional-locale`\n- `browser` is the default for both preferences\n\n`browser` means:\n\n- UI language resolves from the browser locale list against the supported translation set\n- regional formatting resolves from the browser locale while preserving variants such as `en-GB` versus `en-US`\n\n## Runtime Locale Behavior\n\nBoth apps keep document locale metadata aligned with the active locale.\n\n- `document.documentElement.lang` stays synchronized\n- text direction stays synchronized through `dir`\n\nFrontend date, number, and sorting behavior should use the locale-aware helpers instead of raw browser-default formatting.\n\nPrefer:\n\n- `frontend/src/utils/localeFormatting.ts`\n\nFrontend React trees that depend on localization preferences should be wrapped in:\n\n- `frontend/src/i18n/LocalePreferencesProvider.tsx`\n\nThe user-facing preferences UI lives in:\n\n- `frontend/src/pages/PreferencesSettings.tsx`\n\n## Browser-to-Companion Localization Sync\n\nWhen the browser is paired with Sambee Companion, the browser pushes its effective localization state to the companion over the authenticated localhost API.\n\nImportant rules:\n\n- sync uses concrete effective locale values, not unresolved `browser` preferences\n- the companion therefore receives resolved values such as `en` or `en-GB`\n- companion localization is persisted on the Rust side and mirrored into companion local storage for fast startup\n- synchronization is global within the desktop app\n- last-writer-wins behavior is based on the browser-provided `updated_at` timestamp\n- persisted companion state also records the source browser origin\n- open companion windows listen for localization update events and apply the new locale immediately\n\nIf you change the browser-side locale model, you must check the companion sync path too.\n\n## Scope Rules\n\n- translate app-owned UI strings\n- do not translate raw backend error payloads or third-party library messages unless Sambee wraps them in its own copy\n- decorative glyphs are fine when they are not the only user-facing label\n\n## Common Failure Modes\n\n- adding UI text without a translation key\n- weakening typed-key enforcement with casts\n- changing browser locale behavior without checking companion sync\n- treating language preference and formatting preference as the same value\n- using browser-default formatting instead of the shared locale-aware helpers\n\n## Validation Expectations\n\nFor routine localization changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nFor higher-confidence UI changes, also run the relevant frontend or companion tests.\n\nFor browser-to-companion localization sync changes, also validate:\n\n```bash\ncd frontend \u0026\u0026 npm test -- src/services/__tests__/companionService.test.ts\ncd companion \u0026\u0026 npm test -- src/i18n/__tests__/index.test.ts src/components/__tests__/Preferences.test.tsx\n```\n", "0.9": "+++\ntitle = \"Localization and Locale Behavior\"\n+++\n\nLocalization in Sambee is a typed cross-app system. It affects UI copy, browser formatting, and browser-to-companion behavior.\n\nUse this page when you are adding copy, changing locale behavior, or touching browser-to-companion localization sync.\n\n## Sources of Truth\n\nThese files own the localization model:\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Browser app typed wrapper | `frontend/src/i18n/index.ts` |\n| Companion typed wrapper | `companion/src/i18n/index.ts` |\n\nEnglish is the source locale.\n\nThe pseudo-locale `en-XA` is generated from the English translation tree. Do not edit pseudo-locale strings manually.\n\n## Adding New UI Copy\n\nWhen you add new copy:\n\n1. add the English key to the relevant `EN_TRANSLATIONS` tree\n2. use that key from UI code instead of hard-coding a string\n3. use the existing translation access pattern for the surface you are editing\n4. add or extend tests when the copy sits in a reused or high-risk surface\n\nTypical access patterns are:\n\n- browser app React components: `useTranslation()`\n- browser app non-component helpers or config: `translate(...)`\n- companion components: `useI18n()` or `translate(...)`\n\n## Type-Safety Rules\n\nTyped translation keys are part of the contract.\n\n- translation keys are type-checked through the i18n type layer\n- invalid keys should fail TypeScript compilation\n- do not bypass that with casts to `string` or `any`\n- keep wrapper signatures typed instead of weakening them for convenience\n\nIf localization typing becomes optional, contributors lose one of the main protections against copy drift and key mismatches.\n\n## Compile-Time Guard Fixtures\n\nThese files exist specifically to catch regressions in localization typing:\n\n- `frontend/src/i18n/__tests__/typecheck.ts`\n- `companion/src/i18n/__tests__/typecheck.ts`\n\nThey intentionally include both:\n\n- valid translation calls that must compile\n- invalid keys marked with `@ts-expect-error` that must stay invalid\n\nIf a change weakens typed keys, these fixtures should fail type checking.\n\n## Language Versus Regional Formatting\n\nSambee separates UI language from regional formatting.\n\n- language decides which translated copy the UI shows\n- regional formatting decides how dates, numbers, and sorting behave\n\nThat split matters because users may want English UI with non-US formatting, or any other mixed combination the product supports.\n\n## Preference Storage Rules\n\nFrontend language and regional formatting preferences are stored separately.\n\n- language preference lives in `localization.language` in current-user settings and is mirrored in local storage under the app locale key\n- regional formatting preference lives in `localization.regional_locale` in current-user settings and is mirrored in local storage under `sambee.regional-locale`\n- `browser` is the default for both preferences\n\n`browser` means:\n\n- UI language resolves from the browser locale list against the supported translation set\n- regional formatting resolves from the browser locale while preserving variants such as `en-GB` versus `en-US`\n\n## Runtime Locale Behavior\n\nBoth apps keep document locale metadata aligned with the active locale.\n\n- `document.documentElement.lang` stays synchronized\n- text direction stays synchronized through `dir`\n\nFrontend date, number, and sorting behavior should use the locale-aware helpers instead of raw browser-default formatting.\n\nPrefer:\n\n- `frontend/src/utils/localeFormatting.ts`\n\nFrontend React trees that depend on localization preferences should be wrapped in:\n\n- `frontend/src/i18n/LocalePreferencesProvider.tsx`\n\nThe user-facing preferences UI lives in:\n\n- `frontend/src/pages/PreferencesSettings.tsx`\n\n## Browser-to-Companion Localization Sync\n\nWhen the browser is paired with Sambee Companion, the browser pushes its effective localization state to the companion over the authenticated localhost API.\n\nImportant rules:\n\n- sync uses concrete effective locale values, not unresolved `browser` preferences\n- the companion therefore receives resolved values such as `en` or `en-GB`\n- companion localization is persisted on the Rust side and mirrored into companion local storage for fast startup\n- synchronization is global within the desktop app\n- last-writer-wins behavior is based on the browser-provided `updated_at` timestamp\n- persisted companion state also records the source browser origin\n- open companion windows listen for localization update events and apply the new locale immediately\n\nIf you change the browser-side locale model, you must check the companion sync path too.\n\n## Scope Rules\n\n- translate app-owned UI strings\n- do not translate raw backend error payloads or third-party library messages unless Sambee wraps them in its own copy\n- decorative glyphs are fine when they are not the only user-facing label\n\n## Common Failure Modes\n\n- adding UI text without a translation key\n- weakening typed-key enforcement with casts\n- changing browser locale behavior without checking companion sync\n- treating language preference and formatting preference as the same value\n- using browser-default formatting instead of the shared locale-aware helpers\n\n## Validation Expectations\n\nFor routine localization changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nFor higher-confidence UI changes, also run the relevant frontend or companion tests.\n\nFor browser-to-companion localization sync changes, also validate:\n\n```bash\ncd frontend \u0026\u0026 npm test -- src/services/__tests__/companionService.test.ts\ncd companion \u0026\u0026 npm test -- src/i18n/__tests__/index.test.ts src/components/__tests__/Preferences.test.tsx\n```\n", "1.0": "+++\ntitle = \"Localization and Locale Behavior\"\n+++\n\nLocalization in Sambee is a typed cross-app system. It affects UI copy, browser formatting, and browser-to-companion behavior.\n\nUse this page when you are adding copy, changing locale behavior, or touching browser-to-companion localization sync.\n\n## Sources of Truth\n\nThese files own the localization model:\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Browser app typed wrapper | `frontend/src/i18n/index.ts` |\n| Companion typed wrapper | `companion/src/i18n/index.ts` |\n\nEnglish is the source locale.\n\nThe pseudo-locale `en-XA` is generated from the English translation tree. Do not edit pseudo-locale strings manually.\n\n## Adding New UI Copy\n\nWhen you add new copy:\n\n1. add the English key to the relevant `EN_TRANSLATIONS` tree\n2. use that key from UI code instead of hard-coding a string\n3. use the existing translation access pattern for the surface you are editing\n4. add or extend tests when the copy sits in a reused or high-risk surface\n\nTypical access patterns are:\n\n- browser app React components: `useTranslation()`\n- browser app non-component helpers or config: `translate(...)`\n- companion components: `useI18n()` or `translate(...)`\n\n## Type-Safety Rules\n\nTyped translation keys are part of the contract.\n\n- translation keys are type-checked through the i18n type layer\n- invalid keys should fail TypeScript compilation\n- do not bypass that with casts to `string` or `any`\n- keep wrapper signatures typed instead of weakening them for convenience\n\nIf localization typing becomes optional, contributors lose one of the main protections against copy drift and key mismatches.\n\n## Compile-Time Guard Fixtures\n\nThese files exist specifically to catch regressions in localization typing:\n\n- `frontend/src/i18n/__tests__/typecheck.ts`\n- `companion/src/i18n/__tests__/typecheck.ts`\n\nThey intentionally include both:\n\n- valid translation calls that must compile\n- invalid keys marked with `@ts-expect-error` that must stay invalid\n\nIf a change weakens typed keys, these fixtures should fail type checking.\n\n## Language Versus Regional Formatting\n\nSambee separates UI language from regional formatting.\n\n- language decides which translated copy the UI shows\n- regional formatting decides how dates, numbers, and sorting behave\n\nThat split matters because users may want English UI with non-US formatting, or any other mixed combination the product supports.\n\n## Preference Storage Rules\n\nFrontend language and regional formatting preferences are stored separately.\n\n- language preference lives in `localization.language` in current-user settings and is mirrored in local storage under the app locale key\n- regional formatting preference lives in `localization.regional_locale` in current-user settings and is mirrored in local storage under `sambee.regional-locale`\n- `browser` is the default for both preferences\n\n`browser` means:\n\n- UI language resolves from the browser locale list against the supported translation set\n- regional formatting resolves from the browser locale while preserving variants such as `en-GB` versus `en-US`\n\n## Runtime Locale Behavior\n\nBoth apps keep document locale metadata aligned with the active locale.\n\n- `document.documentElement.lang` stays synchronized\n- text direction stays synchronized through `dir`\n\nFrontend date, number, and sorting behavior should use the locale-aware helpers instead of raw browser-default formatting.\n\nPrefer:\n\n- `frontend/src/utils/localeFormatting.ts`\n\nFrontend React trees that depend on localization preferences should be wrapped in:\n\n- `frontend/src/i18n/LocalePreferencesProvider.tsx`\n\nThe user-facing preferences UI lives in:\n\n- `frontend/src/pages/PreferencesSettings.tsx`\n\n## Browser-to-Companion Localization Sync\n\nWhen the browser is paired with Sambee Companion, the browser pushes its effective localization state to the companion over the authenticated localhost API.\n\nImportant rules:\n\n- sync uses concrete effective locale values, not unresolved `browser` preferences\n- the companion therefore receives resolved values such as `en` or `en-GB`\n- companion localization is persisted on the Rust side and mirrored into companion local storage for fast startup\n- synchronization is global within the desktop app\n- last-writer-wins behavior is based on the browser-provided `updated_at` timestamp\n- persisted companion state also records the source browser origin\n- open companion windows listen for localization update events and apply the new locale immediately\n\nIf you change the browser-side locale model, you must check the companion sync path too.\n\n## Scope Rules\n\n- translate app-owned UI strings\n- do not translate raw backend error payloads or third-party library messages unless Sambee wraps them in its own copy\n- decorative glyphs are fine when they are not the only user-facing label\n\n## Common Failure Modes\n\n- adding UI text without a translation key\n- weakening typed-key enforcement with casts\n- changing browser locale behavior without checking companion sync\n- treating language preference and formatting preference as the same value\n- using browser-default formatting instead of the shared locale-aware helpers\n\n## Validation Expectations\n\nFor routine localization changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nFor higher-confidence UI changes, also run the relevant frontend or companion tests.\n\nFor browser-to-companion localization sync changes, also validate:\n\n```bash\ncd frontend \u0026\u0026 npm test -- src/services/__tests__/companionService.test.ts\ncd companion \u0026\u0026 npm test -- src/i18n/__tests__/index.test.ts src/components/__tests__/Preferences.test.tsx\n```\n", "2.0": "+++\ntitle = \"Localization and Locale Behavior\"\n+++\n\nLocalization in Sambee is a typed cross-app system. It affects UI copy, browser formatting, and browser-to-companion behavior.\n\nUse this page when you are adding copy, changing locale behavior, or touching browser-to-companion localization sync.\n\n## Sources of Truth\n\nThese files own the localization model:\n\n| Area | Source |\n|---|---|\n| Browser app translations | `frontend/src/i18n/resources.ts` |\n| Companion translations | `companion/src/i18n/resources.ts` |\n| Browser app typed wrapper | `frontend/src/i18n/index.ts` |\n| Companion typed wrapper | `companion/src/i18n/index.ts` |\n\nEnglish is the source locale.\n\nThe pseudo-locale `en-XA` is generated from the English translation tree. Do not edit pseudo-locale strings manually.\n\n## Adding New UI Copy\n\nWhen you add new copy:\n\n1. add the English key to the relevant `EN_TRANSLATIONS` tree\n2. use that key from UI code instead of hard-coding a string\n3. use the existing translation access pattern for the surface you are editing\n4. add or extend tests when the copy sits in a reused or high-risk surface\n\nTypical access patterns are:\n\n- browser app React components: `useTranslation()`\n- browser app non-component helpers or config: `translate(...)`\n- companion components: `useI18n()` or `translate(...)`\n\n## Type-Safety Rules\n\nTyped translation keys are part of the contract.\n\n- translation keys are type-checked through the i18n type layer\n- invalid keys should fail TypeScript compilation\n- do not bypass that with casts to `string` or `any`\n- keep wrapper signatures typed instead of weakening them for convenience\n\nIf localization typing becomes optional, contributors lose one of the main protections against copy drift and key mismatches.\n\n## Compile-Time Guard Fixtures\n\nThese files exist specifically to catch regressions in localization typing:\n\n- `frontend/src/i18n/__tests__/typecheck.ts`\n- `companion/src/i18n/__tests__/typecheck.ts`\n\nThey intentionally include both:\n\n- valid translation calls that must compile\n- invalid keys marked with `@ts-expect-error` that must stay invalid\n\nIf a change weakens typed keys, these fixtures should fail type checking.\n\n## Language Versus Regional Formatting\n\nSambee separates UI language from regional formatting.\n\n- language decides which translated copy the UI shows\n- regional formatting decides how dates, numbers, and sorting behave\n\nThat split matters because users may want English UI with non-US formatting, or any other mixed combination the product supports.\n\n## Preference Storage Rules\n\nFrontend language and regional formatting preferences are stored separately.\n\n- language preference lives in `localization.language` in current-user settings and is mirrored in local storage under the app locale key\n- regional formatting preference lives in `localization.regional_locale` in current-user settings and is mirrored in local storage under `sambee.regional-locale`\n- `browser` is the default for both preferences\n\n`browser` means:\n\n- UI language resolves from the browser locale list against the supported translation set\n- regional formatting resolves from the browser locale while preserving variants such as `en-GB` versus `en-US`\n\n## Runtime Locale Behavior\n\nBoth apps keep document locale metadata aligned with the active locale.\n\n- `document.documentElement.lang` stays synchronized\n- text direction stays synchronized through `dir`\n\nFrontend date, number, and sorting behavior should use the locale-aware helpers instead of raw browser-default formatting.\n\nPrefer:\n\n- `frontend/src/utils/localeFormatting.ts`\n\nFrontend React trees that depend on localization preferences should be wrapped in:\n\n- `frontend/src/i18n/LocalePreferencesProvider.tsx`\n\nThe user-facing preferences UI lives in:\n\n- `frontend/src/pages/PreferencesSettings.tsx`\n\n## Browser-to-Companion Localization Sync\n\nWhen the browser is paired with Sambee Companion, the browser pushes its effective localization state to the companion over the authenticated localhost API.\n\nImportant rules:\n\n- sync uses concrete effective locale values, not unresolved `browser` preferences\n- the companion therefore receives resolved values such as `en` or `en-GB`\n- companion localization is persisted on the Rust side and mirrored into companion local storage for fast startup\n- synchronization is global within the desktop app\n- last-writer-wins behavior is based on the browser-provided `updated_at` timestamp\n- persisted companion state also records the source browser origin\n- open companion windows listen for localization update events and apply the new locale immediately\n\nIf you change the browser-side locale model, you must check the companion sync path too.\n\n## Scope Rules\n\n- translate app-owned UI strings\n- do not translate raw backend error payloads or third-party library messages unless Sambee wraps them in its own copy\n- decorative glyphs are fine when they are not the only user-facing label\n\n## Common Failure Modes\n\n- adding UI text without a translation key\n- weakening typed-key enforcement with casts\n- changing browser locale behavior without checking companion sync\n- treating language preference and formatting preference as the same value\n- using browser-default formatting instead of the shared locale-aware helpers\n\n## Validation Expectations\n\nFor routine localization changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nFor higher-confidence UI changes, also run the relevant frontend or companion tests.\n\nFor browser-to-companion localization sync changes, also validate:\n\n```bash\ncd frontend \u0026\u0026 npm test -- src/services/__tests__/companionService.test.ts\ncd companion \u0026\u0026 npm test -- src/i18n/__tests__/index.test.ts src/components/__tests__/Preferences.test.tsx\n```\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/cross-cutting-systems/frontend-logging-and-tracing", "parent_id": "section:developer-guide/cross-cutting-systems", "depth": 2, "kind": "page", "label": "frontend-logging-and-tracing", "title": "Frontend Logging And Tracing", "path": "developer-guide/cross-cutting-systems/frontend-logging-and-tracing", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Frontend Logging and Tracing\"\n+++\n\nThe browser app has one shared logging API, but it can feed two different diagnostic surfaces.\n\n- browser-console output for local development and interactive debugging\n- backend trace collection for support workflows and cases where direct console access is unavailable\n\nThat split matters because a small frontend logging change can improve one surface while degrading the other.\n\n## Main Implementation Files\n\n| File | Role |\n|---|---|\n| `frontend/src/services/logger.ts` | shared logging entry point and backend-tracing orchestration |\n| `frontend/src/services/loggingConfig.ts` | fetches and caches server logging config |\n| `frontend/src/services/logBuffer.ts` | buffers trace events before flush |\n| `frontend/src/services/logTransport.ts` | sends trace batches to `/api/logs/mobile` |\n| `backend/app/api/logs.py` | serves frontend logging config and accepts uploaded trace batches |\n| `backend/app/services/log_manager.py` | writes trace batches to JSONL files and cleans up retained logs |\n| `frontend/src/pages/Login.tsx` and `frontend/src/pages/FileBrowser.tsx` | initialize tracing after authenticated app startup |\n\n## Runtime Flow\n\n1. the authenticated browser app calls `logger.initializeBackendTracing()`\n2. the logger loads config through `loggingConfig.getConfig()`\n3. console logging level is updated from backend config when enabled\n4. backend tracing is enabled only when the server config allows it\n5. each logger call writes to the console if its level passes the console threshold\n6. the same call asynchronously checks trace level and component filters before buffering a backend trace entry\n7. the buffer flushes by size or interval and posts the batch to `/api/logs/mobile`\n\nThe log call is the single source of truth. Contributors should not have to choose between console visibility and trace collection by using different APIs.\n\n## Configuration Model\n\nThe frontend pulls logging state from the backend rather than hard-coding it in the browser app.\n\n- `logging_enabled` and `logging_level` control console output\n- `tracing_enabled`, `tracing_level`, and `tracing_components` control backend trace collection\n- `frontend_tracing_username_regex` on the backend can disable tracing for users who do not match the configured pattern\n- `loggingConfig` caches the fetched config in `localStorage` for five minutes to avoid repeated requests\n\nThe logger also keeps different local defaults before server config is loaded.\n\n- development builds default to verbose console logging\n- production builds default to warnings and errors\n- test runs skip backend tracing setup entirely\n\nThe current backend contract is exposed through `GET /api/logs/config` and returns:\n\n- `logging_enabled`\n- `logging_level`\n- `tracing_enabled`\n- `tracing_level`\n- `tracing_components`\n\n`loggingConfig` then adds a client-side timestamp when caching the response locally.\n\n### Level and Component Filtering\n\nConsole logging and backend tracing are independent.\n\n- console output is gated only by `logging_enabled` plus the effective console level\n- backend tracing is gated by `tracing_enabled`, `tracing_level`, and optional component matching\n- an empty `tracing_components` list means all components are accepted\n- component matching is exact string matching, so inconsistent tag names reduce the usefulness of filtered tracing quickly\n\nLevel filtering is threshold-based.\n\n- `DEBUG` allows everything\n- `INFO` suppresses only `DEBUG`\n- `WARNING` allows `WARNING` and `ERROR`\n- `ERROR` allows only `ERROR`\n\n## Buffering and Transport\n\nBackend tracing is buffered on purpose.\n\n- `LogBuffer` groups trace entries in memory instead of posting every log call immediately\n- each batch carries a generated session ID plus device information such as user agent, screen size, and touch capability\n- the default flush behavior is size-based or time-based, whichever happens first\n- failed flushes keep the buffered entries for retry on the next flush attempt\n\nThe current implementation details are worth preserving:\n\n- `LogBuffer` generates one session ID for the browser runtime that enabled tracing\n- the batch payload includes `userAgent`, screen size, `devicePixelRatio`, platform, and touch capability\n- `LogTransport` uses `fetch` directly instead of the shared API service to avoid circular dependencies in the logging stack\n- trace uploads include the bearer token when one is available\n- if repeated flush failures push the in-memory buffer above twice the configured size, the oldest entries are dropped to cap memory growth\n\nThis design keeps routine logging cheap while still giving the backend enough session context to debug real field problems.\n\n### Backend Receipt and Storage\n\nThe backend logging API is simple and file-backed.\n\n- `POST /api/logs/mobile` accepts a trace batch for the authenticated user\n- `GET /api/logs/config` serves the frontend logging configuration\n- `GET /api/logs/list` lists available uploaded mobile-log files\n- `GET /api/logs/download/{filename}` downloads a stored log file\n\nUploaded trace batches are written under `data/mobile_logs/` as JSONL files.\n\n- the first line is metadata, including session ID, device info, server timestamp, and request metadata such as client IP or user agent\n- subsequent lines are individual log entries\n- retention cleanup is handled by `MobileLogManager.cleanup_old_logs()` using the configured retention window\n\nThis is why frontend logging changes can affect both browser behavior and support-facing backend artifacts.\n\n## Component Tags and Taxonomy\n\nComponent tags are optional for console output but important for backend tracing.\n\nRepresentative tags currently used in the frontend include:\n\n- `api`\n- `auth`\n- `backend-recovery`\n- `browser`\n- `browser-perf`\n- `companion`\n- `config`\n- `directory-search-provider`\n- `file-browser`\n- `viewer`\n- `websocket`\n\nThese tags are not just naming style. They are the filter vocabulary for targeted trace collection.\n\nContributors should:\n\n- reuse an existing tag when the log belongs to an established subsystem\n- add a new tag only when it introduces a real new filter boundary\n- keep names stable once they appear in backend config or support playbooks\n\nOne log call still drives both surfaces. The component tag only changes backend-tracing selection behavior.\n\n## Error Context and Safety Rules\n\n`logger.error()` enriches the provided context when an `Error` object is passed.\n\n- `error.message`\n- `error.stack`\n- `error.name`\n\nThat gives support traces more useful failure context without forcing every caller to serialize errors manually.\n\nContributors still need to be selective.\n\n- include actionable IDs, paths, counts, durations, or status values\n- avoid passwords, tokens, private payloads, or large opaque objects\n- avoid high-volume logs inside tight loops or animation-heavy code paths\n\n## Contributor Rules\n\n- use the shared logger instead of scattering long-lived `console.*` calls through components and hooks\n- pass a component tag when backend trace filtering matters to the workflow you are changing\n- do not assume a visible console message also means backend tracing is enabled for that session\n- keep structured context specific and actionable instead of dumping large objects or noisy state snapshots\n- do not move tracing initialization earlier than authenticated startup without checking token and request-path assumptions\n\nThe supported call shape is:\n\n- `logger.debug(message, context?, component?)`\n- `logger.info(message, context?, component?)`\n- `logger.warn(message, context?, component?)`\n- `logger.error(message, context?, component?, error?)`\n\nParameter order matters. If a component tag is needed, it is the third argument for non-error calls and still the third argument for `logger.error()` before the optional `Error` object.\n\nThe older dedicated trace-only helpers are gone. Shared logger calls are the canonical path.\n\n## Test and Runtime Nuances\n\nThe logger deliberately behaves differently in tests.\n\n- test detection suppresses console output\n- backend tracing initialization is skipped in test environments\n- `loggingConfig` falls back to a disabled state when config loading fails\n\nThis is intentional defensive behavior, not a missing feature. It keeps tests quieter and prevents trace setup from leaking across environments.\n\n## Common Failure Modes\n\n- adding raw console logs that never reach backend trace collection\n- expecting a server-side logging-config change to apply instantly while a cached config is still valid\n- using inconsistent component names that make trace filtering unreliable\n- adding high-volume debug logs that drown out the actionable events\n- treating trace transport failures as if they were equivalent to application failures\n\nOther common mistakes include:\n\n- assuming the mobile-log download endpoint is `/api/logs/{filename}` instead of the current `/api/logs/download/{filename}` route\n- documenting stale field names such as `enabled` or `log_level` instead of the current `logging_*` and `tracing_*` contract\n- swapping the logger parameter order and accidentally passing the component tag as context\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nAdd or update targeted frontend tests when the change affects config caching, filtering behavior, startup initialization, or log transport.\n\nThe current targeted suites already cover the most important contracts:\n\n- `frontend/src/services/__tests__/loggingConfig.test.ts` for config shape, threshold logic, and disabled-state behavior\n- `frontend/src/services/__tests__/mobileLoggingApi.test.ts` for the mobile-log API payload and response contract\n\nIf the change touches backend receipt, storage, or filename behavior, pair the frontend checks with the relevant backend tests around `backend/app/api/logs.py` and `backend/tests/test_logging_config.py`.\n", "0.8": "+++\ntitle = \"Frontend Logging and Tracing\"\n+++\n\nThe browser app has one shared logging API, but it can feed two different diagnostic surfaces.\n\n- browser-console output for local development and interactive debugging\n- backend trace collection for support workflows and cases where direct console access is unavailable\n\nThat split matters because a small frontend logging change can improve one surface while degrading the other.\n\n## Main Implementation Files\n\n| File | Role |\n|---|---|\n| `frontend/src/services/logger.ts` | shared logging entry point and backend-tracing orchestration |\n| `frontend/src/services/loggingConfig.ts` | fetches and caches server logging config |\n| `frontend/src/services/logBuffer.ts` | buffers trace events before flush |\n| `frontend/src/services/logTransport.ts` | sends trace batches to `/api/logs/mobile` |\n| `backend/app/api/logs.py` | serves frontend logging config and accepts uploaded trace batches |\n| `backend/app/services/log_manager.py` | writes trace batches to JSONL files and cleans up retained logs |\n| `frontend/src/pages/Login.tsx` and `frontend/src/pages/FileBrowser.tsx` | initialize tracing after authenticated app startup |\n\n## Runtime Flow\n\n1. the authenticated browser app calls `logger.initializeBackendTracing()`\n2. the logger loads config through `loggingConfig.getConfig()`\n3. console logging level is updated from backend config when enabled\n4. backend tracing is enabled only when the server config allows it\n5. each logger call writes to the console if its level passes the console threshold\n6. the same call asynchronously checks trace level and component filters before buffering a backend trace entry\n7. the buffer flushes by size or interval and posts the batch to `/api/logs/mobile`\n\nThe log call is the single source of truth. Contributors should not have to choose between console visibility and trace collection by using different APIs.\n\n## Configuration Model\n\nThe frontend pulls logging state from the backend rather than hard-coding it in the browser app.\n\n- `logging_enabled` and `logging_level` control console output\n- `tracing_enabled`, `tracing_level`, and `tracing_components` control backend trace collection\n- `frontend_tracing_username_regex` on the backend can disable tracing for users who do not match the configured pattern\n- `loggingConfig` caches the fetched config in `localStorage` for five minutes to avoid repeated requests\n\nThe logger also keeps different local defaults before server config is loaded.\n\n- development builds default to verbose console logging\n- production builds default to warnings and errors\n- test runs skip backend tracing setup entirely\n\nThe current backend contract is exposed through `GET /api/logs/config` and returns:\n\n- `logging_enabled`\n- `logging_level`\n- `tracing_enabled`\n- `tracing_level`\n- `tracing_components`\n\n`loggingConfig` then adds a client-side timestamp when caching the response locally.\n\n### Level and Component Filtering\n\nConsole logging and backend tracing are independent.\n\n- console output is gated only by `logging_enabled` plus the effective console level\n- backend tracing is gated by `tracing_enabled`, `tracing_level`, and optional component matching\n- an empty `tracing_components` list means all components are accepted\n- component matching is exact string matching, so inconsistent tag names reduce the usefulness of filtered tracing quickly\n\nLevel filtering is threshold-based.\n\n- `DEBUG` allows everything\n- `INFO` suppresses only `DEBUG`\n- `WARNING` allows `WARNING` and `ERROR`\n- `ERROR` allows only `ERROR`\n\n## Buffering and Transport\n\nBackend tracing is buffered on purpose.\n\n- `LogBuffer` groups trace entries in memory instead of posting every log call immediately\n- each batch carries a generated session ID plus device information such as user agent, screen size, and touch capability\n- the default flush behavior is size-based or time-based, whichever happens first\n- failed flushes keep the buffered entries for retry on the next flush attempt\n\nThe current implementation details are worth preserving:\n\n- `LogBuffer` generates one session ID for the browser runtime that enabled tracing\n- the batch payload includes `userAgent`, screen size, `devicePixelRatio`, platform, and touch capability\n- `LogTransport` uses `fetch` directly instead of the shared API service to avoid circular dependencies in the logging stack\n- trace uploads include the bearer token when one is available\n- if repeated flush failures push the in-memory buffer above twice the configured size, the oldest entries are dropped to cap memory growth\n\nThis design keeps routine logging cheap while still giving the backend enough session context to debug real field problems.\n\n### Backend Receipt and Storage\n\nThe backend logging API is simple and file-backed.\n\n- `POST /api/logs/mobile` accepts a trace batch for the authenticated user\n- `GET /api/logs/config` serves the frontend logging configuration\n- `GET /api/logs/list` lists available uploaded mobile-log files\n- `GET /api/logs/download/{filename}` downloads a stored log file\n\nUploaded trace batches are written under `data/mobile_logs/` as JSONL files.\n\n- the first line is metadata, including session ID, device info, server timestamp, and request metadata such as client IP or user agent\n- subsequent lines are individual log entries\n- retention cleanup is handled by `MobileLogManager.cleanup_old_logs()` using the configured retention window\n\nThis is why frontend logging changes can affect both browser behavior and support-facing backend artifacts.\n\n## Component Tags and Taxonomy\n\nComponent tags are optional for console output but important for backend tracing.\n\nRepresentative tags currently used in the frontend include:\n\n- `api`\n- `auth`\n- `backend-recovery`\n- `browser`\n- `browser-perf`\n- `companion`\n- `config`\n- `directory-search-provider`\n- `file-browser`\n- `viewer`\n- `websocket`\n\nThese tags are not just naming style. They are the filter vocabulary for targeted trace collection.\n\nContributors should:\n\n- reuse an existing tag when the log belongs to an established subsystem\n- add a new tag only when it introduces a real new filter boundary\n- keep names stable once they appear in backend config or support playbooks\n\nOne log call still drives both surfaces. The component tag only changes backend-tracing selection behavior.\n\n## Error Context and Safety Rules\n\n`logger.error()` enriches the provided context when an `Error` object is passed.\n\n- `error.message`\n- `error.stack`\n- `error.name`\n\nThat gives support traces more useful failure context without forcing every caller to serialize errors manually.\n\nContributors still need to be selective.\n\n- include actionable IDs, paths, counts, durations, or status values\n- avoid passwords, tokens, private payloads, or large opaque objects\n- avoid high-volume logs inside tight loops or animation-heavy code paths\n\n## Contributor Rules\n\n- use the shared logger instead of scattering long-lived `console.*` calls through components and hooks\n- pass a component tag when backend trace filtering matters to the workflow you are changing\n- do not assume a visible console message also means backend tracing is enabled for that session\n- keep structured context specific and actionable instead of dumping large objects or noisy state snapshots\n- do not move tracing initialization earlier than authenticated startup without checking token and request-path assumptions\n\nThe supported call shape is:\n\n- `logger.debug(message, context?, component?)`\n- `logger.info(message, context?, component?)`\n- `logger.warn(message, context?, component?)`\n- `logger.error(message, context?, component?, error?)`\n\nParameter order matters. If a component tag is needed, it is the third argument for non-error calls and still the third argument for `logger.error()` before the optional `Error` object.\n\nThe older dedicated trace-only helpers are gone. Shared logger calls are the canonical path.\n\n## Test and Runtime Nuances\n\nThe logger deliberately behaves differently in tests.\n\n- test detection suppresses console output\n- backend tracing initialization is skipped in test environments\n- `loggingConfig` falls back to a disabled state when config loading fails\n\nThis is intentional defensive behavior, not a missing feature. It keeps tests quieter and prevents trace setup from leaking across environments.\n\n## Common Failure Modes\n\n- adding raw console logs that never reach backend trace collection\n- expecting a server-side logging-config change to apply instantly while a cached config is still valid\n- using inconsistent component names that make trace filtering unreliable\n- adding high-volume debug logs that drown out the actionable events\n- treating trace transport failures as if they were equivalent to application failures\n\nOther common mistakes include:\n\n- assuming the mobile-log download endpoint is `/api/logs/{filename}` instead of the current `/api/logs/download/{filename}` route\n- documenting stale field names such as `enabled` or `log_level` instead of the current `logging_*` and `tracing_*` contract\n- swapping the logger parameter order and accidentally passing the component tag as context\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nAdd or update targeted frontend tests when the change affects config caching, filtering behavior, startup initialization, or log transport.\n\nThe current targeted suites already cover the most important contracts:\n\n- `frontend/src/services/__tests__/loggingConfig.test.ts` for config shape, threshold logic, and disabled-state behavior\n- `frontend/src/services/__tests__/mobileLoggingApi.test.ts` for the mobile-log API payload and response contract\n\nIf the change touches backend receipt, storage, or filename behavior, pair the frontend checks with the relevant backend tests around `backend/app/api/logs.py` and `backend/tests/test_logging_config.py`.\n", "0.9": "+++\ntitle = \"Frontend Logging and Tracing\"\n+++\n\nThe browser app has one shared logging API, but it can feed two different diagnostic surfaces.\n\n- browser-console output for local development and interactive debugging\n- backend trace collection for support workflows and cases where direct console access is unavailable\n\nThat split matters because a small frontend logging change can improve one surface while degrading the other.\n\n## Main Implementation Files\n\n| File | Role |\n|---|---|\n| `frontend/src/services/logger.ts` | shared logging entry point and backend-tracing orchestration |\n| `frontend/src/services/loggingConfig.ts` | fetches and caches server logging config |\n| `frontend/src/services/logBuffer.ts` | buffers trace events before flush |\n| `frontend/src/services/logTransport.ts` | sends trace batches to `/api/logs/mobile` |\n| `backend/app/api/logs.py` | serves frontend logging config and accepts uploaded trace batches |\n| `backend/app/services/log_manager.py` | writes trace batches to JSONL files and cleans up retained logs |\n| `frontend/src/pages/Login.tsx` and `frontend/src/pages/FileBrowser.tsx` | initialize tracing after authenticated app startup |\n\n## Runtime Flow\n\n1. the authenticated browser app calls `logger.initializeBackendTracing()`\n2. the logger loads config through `loggingConfig.getConfig()`\n3. console logging level is updated from backend config when enabled\n4. backend tracing is enabled only when the server config allows it\n5. each logger call writes to the console if its level passes the console threshold\n6. the same call asynchronously checks trace level and component filters before buffering a backend trace entry\n7. the buffer flushes by size or interval and posts the batch to `/api/logs/mobile`\n\nThe log call is the single source of truth. Contributors should not have to choose between console visibility and trace collection by using different APIs.\n\n## Configuration Model\n\nThe frontend pulls logging state from the backend rather than hard-coding it in the browser app.\n\n- `logging_enabled` and `logging_level` control console output\n- `tracing_enabled`, `tracing_level`, and `tracing_components` control backend trace collection\n- `frontend_tracing_username_regex` on the backend can disable tracing for users who do not match the configured pattern\n- `loggingConfig` caches the fetched config in `localStorage` for five minutes to avoid repeated requests\n\nThe logger also keeps different local defaults before server config is loaded.\n\n- development builds default to verbose console logging\n- production builds default to warnings and errors\n- test runs skip backend tracing setup entirely\n\nThe current backend contract is exposed through `GET /api/logs/config` and returns:\n\n- `logging_enabled`\n- `logging_level`\n- `tracing_enabled`\n- `tracing_level`\n- `tracing_components`\n\n`loggingConfig` then adds a client-side timestamp when caching the response locally.\n\n### Level and Component Filtering\n\nConsole logging and backend tracing are independent.\n\n- console output is gated only by `logging_enabled` plus the effective console level\n- backend tracing is gated by `tracing_enabled`, `tracing_level`, and optional component matching\n- an empty `tracing_components` list means all components are accepted\n- component matching is exact string matching, so inconsistent tag names reduce the usefulness of filtered tracing quickly\n\nLevel filtering is threshold-based.\n\n- `DEBUG` allows everything\n- `INFO` suppresses only `DEBUG`\n- `WARNING` allows `WARNING` and `ERROR`\n- `ERROR` allows only `ERROR`\n\n## Buffering and Transport\n\nBackend tracing is buffered on purpose.\n\n- `LogBuffer` groups trace entries in memory instead of posting every log call immediately\n- each batch carries a generated session ID plus device information such as user agent, screen size, and touch capability\n- the default flush behavior is size-based or time-based, whichever happens first\n- failed flushes keep the buffered entries for retry on the next flush attempt\n\nThe current implementation details are worth preserving:\n\n- `LogBuffer` generates one session ID for the browser runtime that enabled tracing\n- the batch payload includes `userAgent`, screen size, `devicePixelRatio`, platform, and touch capability\n- `LogTransport` uses `fetch` directly instead of the shared API service to avoid circular dependencies in the logging stack\n- trace uploads include the bearer token when one is available\n- if repeated flush failures push the in-memory buffer above twice the configured size, the oldest entries are dropped to cap memory growth\n\nThis design keeps routine logging cheap while still giving the backend enough session context to debug real field problems.\n\n### Backend Receipt and Storage\n\nThe backend logging API is simple and file-backed.\n\n- `POST /api/logs/mobile` accepts a trace batch for the authenticated user\n- `GET /api/logs/config` serves the frontend logging configuration\n- `GET /api/logs/list` lists available uploaded mobile-log files\n- `GET /api/logs/download/{filename}` downloads a stored log file\n\nUploaded trace batches are written under `data/mobile_logs/` as JSONL files.\n\n- the first line is metadata, including session ID, device info, server timestamp, and request metadata such as client IP or user agent\n- subsequent lines are individual log entries\n- retention cleanup is handled by `MobileLogManager.cleanup_old_logs()` using the configured retention window\n\nThis is why frontend logging changes can affect both browser behavior and support-facing backend artifacts.\n\n## Component Tags and Taxonomy\n\nComponent tags are optional for console output but important for backend tracing.\n\nRepresentative tags currently used in the frontend include:\n\n- `api`\n- `auth`\n- `backend-recovery`\n- `browser`\n- `browser-perf`\n- `companion`\n- `config`\n- `directory-search-provider`\n- `file-browser`\n- `viewer`\n- `websocket`\n\nThese tags are not just naming style. They are the filter vocabulary for targeted trace collection.\n\nContributors should:\n\n- reuse an existing tag when the log belongs to an established subsystem\n- add a new tag only when it introduces a real new filter boundary\n- keep names stable once they appear in backend config or support playbooks\n\nOne log call still drives both surfaces. The component tag only changes backend-tracing selection behavior.\n\n## Error Context and Safety Rules\n\n`logger.error()` enriches the provided context when an `Error` object is passed.\n\n- `error.message`\n- `error.stack`\n- `error.name`\n\nThat gives support traces more useful failure context without forcing every caller to serialize errors manually.\n\nContributors still need to be selective.\n\n- include actionable IDs, paths, counts, durations, or status values\n- avoid passwords, tokens, private payloads, or large opaque objects\n- avoid high-volume logs inside tight loops or animation-heavy code paths\n\n## Contributor Rules\n\n- use the shared logger instead of scattering long-lived `console.*` calls through components and hooks\n- pass a component tag when backend trace filtering matters to the workflow you are changing\n- do not assume a visible console message also means backend tracing is enabled for that session\n- keep structured context specific and actionable instead of dumping large objects or noisy state snapshots\n- do not move tracing initialization earlier than authenticated startup without checking token and request-path assumptions\n\nThe supported call shape is:\n\n- `logger.debug(message, context?, component?)`\n- `logger.info(message, context?, component?)`\n- `logger.warn(message, context?, component?)`\n- `logger.error(message, context?, component?, error?)`\n\nParameter order matters. If a component tag is needed, it is the third argument for non-error calls and still the third argument for `logger.error()` before the optional `Error` object.\n\nThe older dedicated trace-only helpers are gone. Shared logger calls are the canonical path.\n\n## Test and Runtime Nuances\n\nThe logger deliberately behaves differently in tests.\n\n- test detection suppresses console output\n- backend tracing initialization is skipped in test environments\n- `loggingConfig` falls back to a disabled state when config loading fails\n\nThis is intentional defensive behavior, not a missing feature. It keeps tests quieter and prevents trace setup from leaking across environments.\n\n## Common Failure Modes\n\n- adding raw console logs that never reach backend trace collection\n- expecting a server-side logging-config change to apply instantly while a cached config is still valid\n- using inconsistent component names that make trace filtering unreliable\n- adding high-volume debug logs that drown out the actionable events\n- treating trace transport failures as if they were equivalent to application failures\n\nOther common mistakes include:\n\n- assuming the mobile-log download endpoint is `/api/logs/{filename}` instead of the current `/api/logs/download/{filename}` route\n- documenting stale field names such as `enabled` or `log_level` instead of the current `logging_*` and `tracing_*` contract\n- swapping the logger parameter order and accidentally passing the component tag as context\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nAdd or update targeted frontend tests when the change affects config caching, filtering behavior, startup initialization, or log transport.\n\nThe current targeted suites already cover the most important contracts:\n\n- `frontend/src/services/__tests__/loggingConfig.test.ts` for config shape, threshold logic, and disabled-state behavior\n- `frontend/src/services/__tests__/mobileLoggingApi.test.ts` for the mobile-log API payload and response contract\n\nIf the change touches backend receipt, storage, or filename behavior, pair the frontend checks with the relevant backend tests around `backend/app/api/logs.py` and `backend/tests/test_logging_config.py`.\n", "1.0": "+++\ntitle = \"Frontend Logging and Tracing\"\n+++\n\nThe browser app has one shared logging API, but it can feed two different diagnostic surfaces.\n\n- browser-console output for local development and interactive debugging\n- backend trace collection for support workflows and cases where direct console access is unavailable\n\nThat split matters because a small frontend logging change can improve one surface while degrading the other.\n\n## Main Implementation Files\n\n| File | Role |\n|---|---|\n| `frontend/src/services/logger.ts` | shared logging entry point and backend-tracing orchestration |\n| `frontend/src/services/loggingConfig.ts` | fetches and caches server logging config |\n| `frontend/src/services/logBuffer.ts` | buffers trace events before flush |\n| `frontend/src/services/logTransport.ts` | sends trace batches to `/api/logs/mobile` |\n| `backend/app/api/logs.py` | serves frontend logging config and accepts uploaded trace batches |\n| `backend/app/services/log_manager.py` | writes trace batches to JSONL files and cleans up retained logs |\n| `frontend/src/pages/Login.tsx` and `frontend/src/pages/FileBrowser.tsx` | initialize tracing after authenticated app startup |\n\n## Runtime Flow\n\n1. the authenticated browser app calls `logger.initializeBackendTracing()`\n2. the logger loads config through `loggingConfig.getConfig()`\n3. console logging level is updated from backend config when enabled\n4. backend tracing is enabled only when the server config allows it\n5. each logger call writes to the console if its level passes the console threshold\n6. the same call asynchronously checks trace level and component filters before buffering a backend trace entry\n7. the buffer flushes by size or interval and posts the batch to `/api/logs/mobile`\n\nThe log call is the single source of truth. Contributors should not have to choose between console visibility and trace collection by using different APIs.\n\n## Configuration Model\n\nThe frontend pulls logging state from the backend rather than hard-coding it in the browser app.\n\n- `logging_enabled` and `logging_level` control console output\n- `tracing_enabled`, `tracing_level`, and `tracing_components` control backend trace collection\n- `frontend_tracing_username_regex` on the backend can disable tracing for users who do not match the configured pattern\n- `loggingConfig` caches the fetched config in `localStorage` for five minutes to avoid repeated requests\n\nThe logger also keeps different local defaults before server config is loaded.\n\n- development builds default to verbose console logging\n- production builds default to warnings and errors\n- test runs skip backend tracing setup entirely\n\nThe current backend contract is exposed through `GET /api/logs/config` and returns:\n\n- `logging_enabled`\n- `logging_level`\n- `tracing_enabled`\n- `tracing_level`\n- `tracing_components`\n\n`loggingConfig` then adds a client-side timestamp when caching the response locally.\n\n### Level and Component Filtering\n\nConsole logging and backend tracing are independent.\n\n- console output is gated only by `logging_enabled` plus the effective console level\n- backend tracing is gated by `tracing_enabled`, `tracing_level`, and optional component matching\n- an empty `tracing_components` list means all components are accepted\n- component matching is exact string matching, so inconsistent tag names reduce the usefulness of filtered tracing quickly\n\nLevel filtering is threshold-based.\n\n- `DEBUG` allows everything\n- `INFO` suppresses only `DEBUG`\n- `WARNING` allows `WARNING` and `ERROR`\n- `ERROR` allows only `ERROR`\n\n## Buffering and Transport\n\nBackend tracing is buffered on purpose.\n\n- `LogBuffer` groups trace entries in memory instead of posting every log call immediately\n- each batch carries a generated session ID plus device information such as user agent, screen size, and touch capability\n- the default flush behavior is size-based or time-based, whichever happens first\n- failed flushes keep the buffered entries for retry on the next flush attempt\n\nThe current implementation details are worth preserving:\n\n- `LogBuffer` generates one session ID for the browser runtime that enabled tracing\n- the batch payload includes `userAgent`, screen size, `devicePixelRatio`, platform, and touch capability\n- `LogTransport` uses `fetch` directly instead of the shared API service to avoid circular dependencies in the logging stack\n- trace uploads include the bearer token when one is available\n- if repeated flush failures push the in-memory buffer above twice the configured size, the oldest entries are dropped to cap memory growth\n\nThis design keeps routine logging cheap while still giving the backend enough session context to debug real field problems.\n\n### Backend Receipt and Storage\n\nThe backend logging API is simple and file-backed.\n\n- `POST /api/logs/mobile` accepts a trace batch for the authenticated user\n- `GET /api/logs/config` serves the frontend logging configuration\n- `GET /api/logs/list` lists available uploaded mobile-log files\n- `GET /api/logs/download/{filename}` downloads a stored log file\n\nUploaded trace batches are written under `data/mobile_logs/` as JSONL files.\n\n- the first line is metadata, including session ID, device info, server timestamp, and request metadata such as client IP or user agent\n- subsequent lines are individual log entries\n- retention cleanup is handled by `MobileLogManager.cleanup_old_logs()` using the configured retention window\n\nThis is why frontend logging changes can affect both browser behavior and support-facing backend artifacts.\n\n## Component Tags and Taxonomy\n\nComponent tags are optional for console output but important for backend tracing.\n\nRepresentative tags currently used in the frontend include:\n\n- `api`\n- `auth`\n- `backend-recovery`\n- `browser`\n- `browser-perf`\n- `companion`\n- `config`\n- `directory-search-provider`\n- `file-browser`\n- `viewer`\n- `websocket`\n\nThese tags are not just naming style. They are the filter vocabulary for targeted trace collection.\n\nContributors should:\n\n- reuse an existing tag when the log belongs to an established subsystem\n- add a new tag only when it introduces a real new filter boundary\n- keep names stable once they appear in backend config or support playbooks\n\nOne log call still drives both surfaces. The component tag only changes backend-tracing selection behavior.\n\n## Error Context and Safety Rules\n\n`logger.error()` enriches the provided context when an `Error` object is passed.\n\n- `error.message`\n- `error.stack`\n- `error.name`\n\nThat gives support traces more useful failure context without forcing every caller to serialize errors manually.\n\nContributors still need to be selective.\n\n- include actionable IDs, paths, counts, durations, or status values\n- avoid passwords, tokens, private payloads, or large opaque objects\n- avoid high-volume logs inside tight loops or animation-heavy code paths\n\n## Contributor Rules\n\n- use the shared logger instead of scattering long-lived `console.*` calls through components and hooks\n- pass a component tag when backend trace filtering matters to the workflow you are changing\n- do not assume a visible console message also means backend tracing is enabled for that session\n- keep structured context specific and actionable instead of dumping large objects or noisy state snapshots\n- do not move tracing initialization earlier than authenticated startup without checking token and request-path assumptions\n\nThe supported call shape is:\n\n- `logger.debug(message, context?, component?)`\n- `logger.info(message, context?, component?)`\n- `logger.warn(message, context?, component?)`\n- `logger.error(message, context?, component?, error?)`\n\nParameter order matters. If a component tag is needed, it is the third argument for non-error calls and still the third argument for `logger.error()` before the optional `Error` object.\n\nThe older dedicated trace-only helpers are gone. Shared logger calls are the canonical path.\n\n## Test and Runtime Nuances\n\nThe logger deliberately behaves differently in tests.\n\n- test detection suppresses console output\n- backend tracing initialization is skipped in test environments\n- `loggingConfig` falls back to a disabled state when config loading fails\n\nThis is intentional defensive behavior, not a missing feature. It keeps tests quieter and prevents trace setup from leaking across environments.\n\n## Common Failure Modes\n\n- adding raw console logs that never reach backend trace collection\n- expecting a server-side logging-config change to apply instantly while a cached config is still valid\n- using inconsistent component names that make trace filtering unreliable\n- adding high-volume debug logs that drown out the actionable events\n- treating trace transport failures as if they were equivalent to application failures\n\nOther common mistakes include:\n\n- assuming the mobile-log download endpoint is `/api/logs/{filename}` instead of the current `/api/logs/download/{filename}` route\n- documenting stale field names such as `enabled` or `log_level` instead of the current `logging_*` and `tracing_*` contract\n- swapping the logger parameter order and accidentally passing the component tag as context\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nAdd or update targeted frontend tests when the change affects config caching, filtering behavior, startup initialization, or log transport.\n\nThe current targeted suites already cover the most important contracts:\n\n- `frontend/src/services/__tests__/loggingConfig.test.ts` for config shape, threshold logic, and disabled-state behavior\n- `frontend/src/services/__tests__/mobileLoggingApi.test.ts` for the mobile-log API payload and response contract\n\nIf the change touches backend receipt, storage, or filename behavior, pair the frontend checks with the relevant backend tests around `backend/app/api/logs.py` and `backend/tests/test_logging_config.py`.\n", "2.0": "+++\ntitle = \"Frontend Logging and Tracing\"\n+++\n\nThe browser app has one shared logging API, but it can feed two different diagnostic surfaces.\n\n- browser-console output for local development and interactive debugging\n- backend trace collection for support workflows and cases where direct console access is unavailable\n\nThat split matters because a small frontend logging change can improve one surface while degrading the other.\n\n## Main Implementation Files\n\n| File | Role |\n|---|---|\n| `frontend/src/services/logger.ts` | shared logging entry point and backend-tracing orchestration |\n| `frontend/src/services/loggingConfig.ts` | fetches and caches server logging config |\n| `frontend/src/services/logBuffer.ts` | buffers trace events before flush |\n| `frontend/src/services/logTransport.ts` | sends trace batches to `/api/logs/mobile` |\n| `backend/app/api/logs.py` | serves frontend logging config and accepts uploaded trace batches |\n| `backend/app/services/log_manager.py` | writes trace batches to JSONL files and cleans up retained logs |\n| `frontend/src/pages/Login.tsx` and `frontend/src/pages/FileBrowser.tsx` | initialize tracing after authenticated app startup |\n\n## Runtime Flow\n\n1. the authenticated browser app calls `logger.initializeBackendTracing()`\n2. the logger loads config through `loggingConfig.getConfig()`\n3. console logging level is updated from backend config when enabled\n4. backend tracing is enabled only when the server config allows it\n5. each logger call writes to the console if its level passes the console threshold\n6. the same call asynchronously checks trace level and component filters before buffering a backend trace entry\n7. the buffer flushes by size or interval and posts the batch to `/api/logs/mobile`\n\nThe log call is the single source of truth. Contributors should not have to choose between console visibility and trace collection by using different APIs.\n\n## Configuration Model\n\nThe frontend pulls logging state from the backend rather than hard-coding it in the browser app.\n\n- `logging_enabled` and `logging_level` control console output\n- `tracing_enabled`, `tracing_level`, and `tracing_components` control backend trace collection\n- `frontend_tracing_username_regex` on the backend can disable tracing for users who do not match the configured pattern\n- `loggingConfig` caches the fetched config in `localStorage` for five minutes to avoid repeated requests\n\nThe logger also keeps different local defaults before server config is loaded.\n\n- development builds default to verbose console logging\n- production builds default to warnings and errors\n- test runs skip backend tracing setup entirely\n\nThe current backend contract is exposed through `GET /api/logs/config` and returns:\n\n- `logging_enabled`\n- `logging_level`\n- `tracing_enabled`\n- `tracing_level`\n- `tracing_components`\n\n`loggingConfig` then adds a client-side timestamp when caching the response locally.\n\n### Level and Component Filtering\n\nConsole logging and backend tracing are independent.\n\n- console output is gated only by `logging_enabled` plus the effective console level\n- backend tracing is gated by `tracing_enabled`, `tracing_level`, and optional component matching\n- an empty `tracing_components` list means all components are accepted\n- component matching is exact string matching, so inconsistent tag names reduce the usefulness of filtered tracing quickly\n\nLevel filtering is threshold-based.\n\n- `DEBUG` allows everything\n- `INFO` suppresses only `DEBUG`\n- `WARNING` allows `WARNING` and `ERROR`\n- `ERROR` allows only `ERROR`\n\n## Buffering and Transport\n\nBackend tracing is buffered on purpose.\n\n- `LogBuffer` groups trace entries in memory instead of posting every log call immediately\n- each batch carries a generated session ID plus device information such as user agent, screen size, and touch capability\n- the default flush behavior is size-based or time-based, whichever happens first\n- failed flushes keep the buffered entries for retry on the next flush attempt\n\nThe current implementation details are worth preserving:\n\n- `LogBuffer` generates one session ID for the browser runtime that enabled tracing\n- the batch payload includes `userAgent`, screen size, `devicePixelRatio`, platform, and touch capability\n- `LogTransport` uses `fetch` directly instead of the shared API service to avoid circular dependencies in the logging stack\n- trace uploads include the bearer token when one is available\n- if repeated flush failures push the in-memory buffer above twice the configured size, the oldest entries are dropped to cap memory growth\n\nThis design keeps routine logging cheap while still giving the backend enough session context to debug real field problems.\n\n### Backend Receipt and Storage\n\nThe backend logging API is simple and file-backed.\n\n- `POST /api/logs/mobile` accepts a trace batch for the authenticated user\n- `GET /api/logs/config` serves the frontend logging configuration\n- `GET /api/logs/list` lists available uploaded mobile-log files\n- `GET /api/logs/download/{filename}` downloads a stored log file\n\nUploaded trace batches are written under `data/mobile_logs/` as JSONL files.\n\n- the first line is metadata, including session ID, device info, server timestamp, and request metadata such as client IP or user agent\n- subsequent lines are individual log entries\n- retention cleanup is handled by `MobileLogManager.cleanup_old_logs()` using the configured retention window\n\nThis is why frontend logging changes can affect both browser behavior and support-facing backend artifacts.\n\n## Component Tags and Taxonomy\n\nComponent tags are optional for console output but important for backend tracing.\n\nRepresentative tags currently used in the frontend include:\n\n- `api`\n- `auth`\n- `backend-recovery`\n- `browser`\n- `browser-perf`\n- `companion`\n- `config`\n- `directory-search-provider`\n- `file-browser`\n- `viewer`\n- `websocket`\n\nThese tags are not just naming style. They are the filter vocabulary for targeted trace collection.\n\nContributors should:\n\n- reuse an existing tag when the log belongs to an established subsystem\n- add a new tag only when it introduces a real new filter boundary\n- keep names stable once they appear in backend config or support playbooks\n\nOne log call still drives both surfaces. The component tag only changes backend-tracing selection behavior.\n\n## Error Context and Safety Rules\n\n`logger.error()` enriches the provided context when an `Error` object is passed.\n\n- `error.message`\n- `error.stack`\n- `error.name`\n\nThat gives support traces more useful failure context without forcing every caller to serialize errors manually.\n\nContributors still need to be selective.\n\n- include actionable IDs, paths, counts, durations, or status values\n- avoid passwords, tokens, private payloads, or large opaque objects\n- avoid high-volume logs inside tight loops or animation-heavy code paths\n\n## Contributor Rules\n\n- use the shared logger instead of scattering long-lived `console.*` calls through components and hooks\n- pass a component tag when backend trace filtering matters to the workflow you are changing\n- do not assume a visible console message also means backend tracing is enabled for that session\n- keep structured context specific and actionable instead of dumping large objects or noisy state snapshots\n- do not move tracing initialization earlier than authenticated startup without checking token and request-path assumptions\n\nThe supported call shape is:\n\n- `logger.debug(message, context?, component?)`\n- `logger.info(message, context?, component?)`\n- `logger.warn(message, context?, component?)`\n- `logger.error(message, context?, component?, error?)`\n\nParameter order matters. If a component tag is needed, it is the third argument for non-error calls and still the third argument for `logger.error()` before the optional `Error` object.\n\nThe older dedicated trace-only helpers are gone. Shared logger calls are the canonical path.\n\n## Test and Runtime Nuances\n\nThe logger deliberately behaves differently in tests.\n\n- test detection suppresses console output\n- backend tracing initialization is skipped in test environments\n- `loggingConfig` falls back to a disabled state when config loading fails\n\nThis is intentional defensive behavior, not a missing feature. It keeps tests quieter and prevents trace setup from leaking across environments.\n\n## Common Failure Modes\n\n- adding raw console logs that never reach backend trace collection\n- expecting a server-side logging-config change to apply instantly while a cached config is still valid\n- using inconsistent component names that make trace filtering unreliable\n- adding high-volume debug logs that drown out the actionable events\n- treating trace transport failures as if they were equivalent to application failures\n\nOther common mistakes include:\n\n- assuming the mobile-log download endpoint is `/api/logs/{filename}` instead of the current `/api/logs/download/{filename}` route\n- documenting stale field names such as `enabled` or `log_level` instead of the current `logging_*` and `tracing_*` contract\n- swapping the logger parameter order and accidentally passing the component tag as context\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nAdd or update targeted frontend tests when the change affects config caching, filtering behavior, startup initialization, or log transport.\n\nThe current targeted suites already cover the most important contracts:\n\n- `frontend/src/services/__tests__/loggingConfig.test.ts` for config shape, threshold logic, and disabled-state behavior\n- `frontend/src/services/__tests__/mobileLoggingApi.test.ts` for the mobile-log API payload and response contract\n\nIf the change touches backend receipt, storage, or filename behavior, pair the frontend checks with the relevant backend tests around `backend/app/api/logs.py` and `backend/tests/test_logging_config.py`.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Frontend Logging and Tracing\"\n+++\n\nThe browser app has one shared logging API, but it can feed two different diagnostic surfaces.\n\n- browser-console output for local development and interactive debugging\n- backend trace collection for support workflows and cases where direct console access is unavailable\n\nThat split matters because a small frontend logging change can improve one surface while degrading the other.\n\n## Main Implementation Files\n\n| File | Role |\n|---|---|\n| `frontend/src/services/logger.ts` | shared logging entry point and backend-tracing orchestration |\n| `frontend/src/services/loggingConfig.ts` | fetches and caches server logging config |\n| `frontend/src/services/logBuffer.ts` | buffers trace events before flush |\n| `frontend/src/services/logTransport.ts` | sends trace batches to `/api/logs/mobile` |\n| `backend/app/api/logs.py` | serves frontend logging config and accepts uploaded trace batches |\n| `backend/app/services/log_manager.py` | writes trace batches to JSONL files and cleans up retained logs |\n| `frontend/src/pages/Login.tsx` and `frontend/src/pages/FileBrowser.tsx` | initialize tracing after authenticated app startup |\n\n## Runtime Flow\n\n1. the authenticated browser app calls `logger.initializeBackendTracing()`\n2. the logger loads config through `loggingConfig.getConfig()`\n3. console logging level is updated from backend config when enabled\n4. backend tracing is enabled only when the server config allows it\n5. each logger call writes to the console if its level passes the console threshold\n6. the same call asynchronously checks trace level and component filters before buffering a backend trace entry\n7. the buffer flushes by size or interval and posts the batch to `/api/logs/mobile`\n\nThe log call is the single source of truth. Contributors should not have to choose between console visibility and trace collection by using different APIs.\n\n## Configuration Model\n\nThe frontend pulls logging state from the backend rather than hard-coding it in the browser app.\n\n- `logging_enabled` and `logging_level` control console output\n- `tracing_enabled`, `tracing_level`, and `tracing_components` control backend trace collection\n- `frontend_tracing_username_regex` on the backend can disable tracing for users who do not match the configured pattern\n- `loggingConfig` caches the fetched config in `localStorage` for five minutes to avoid repeated requests\n\nThe logger also keeps different local defaults before server config is loaded.\n\n- development builds default to verbose console logging\n- production builds default to warnings and errors\n- test runs skip backend tracing setup entirely\n\nThe current backend contract is exposed through `GET /api/logs/config` and returns:\n\n- `logging_enabled`\n- `logging_level`\n- `tracing_enabled`\n- `tracing_level`\n- `tracing_components`\n\n`loggingConfig` then adds a client-side timestamp when caching the response locally.\n\n### Level and Component Filtering\n\nConsole logging and backend tracing are independent.\n\n- console output is gated only by `logging_enabled` plus the effective console level\n- backend tracing is gated by `tracing_enabled`, `tracing_level`, and optional component matching\n- an empty `tracing_components` list means all components are accepted\n- component matching is exact string matching, so inconsistent tag names reduce the usefulness of filtered tracing quickly\n\nLevel filtering is threshold-based.\n\n- `DEBUG` allows everything\n- `INFO` suppresses only `DEBUG`\n- `WARNING` allows `WARNING` and `ERROR`\n- `ERROR` allows only `ERROR`\n\n## Buffering and Transport\n\nBackend tracing is buffered on purpose.\n\n- `LogBuffer` groups trace entries in memory instead of posting every log call immediately\n- each batch carries a generated session ID plus device information such as user agent, screen size, and touch capability\n- the default flush behavior is size-based or time-based, whichever happens first\n- failed flushes keep the buffered entries for retry on the next flush attempt\n\nThe current implementation details are worth preserving:\n\n- `LogBuffer` generates one session ID for the browser runtime that enabled tracing\n- the batch payload includes `userAgent`, screen size, `devicePixelRatio`, platform, and touch capability\n- `LogTransport` uses `fetch` directly instead of the shared API service to avoid circular dependencies in the logging stack\n- trace uploads include the bearer token when one is available\n- if repeated flush failures push the in-memory buffer above twice the configured size, the oldest entries are dropped to cap memory growth\n\nThis design keeps routine logging cheap while still giving the backend enough session context to debug real field problems.\n\n### Backend Receipt and Storage\n\nThe backend logging API is simple and file-backed.\n\n- `POST /api/logs/mobile` accepts a trace batch for the authenticated user\n- `GET /api/logs/config` serves the frontend logging configuration\n- `GET /api/logs/list` lists available uploaded mobile-log files\n- `GET /api/logs/download/{filename}` downloads a stored log file\n\nUploaded trace batches are written under `data/mobile_logs/` as JSONL files.\n\n- the first line is metadata, including session ID, device info, server timestamp, and request metadata such as client IP or user agent\n- subsequent lines are individual log entries\n- retention cleanup is handled by `MobileLogManager.cleanup_old_logs()` using the configured retention window\n\nThis is why frontend logging changes can affect both browser behavior and support-facing backend artifacts.\n\n## Component Tags and Taxonomy\n\nComponent tags are optional for console output but important for backend tracing.\n\nRepresentative tags currently used in the frontend include:\n\n- `api`\n- `auth`\n- `backend-recovery`\n- `browser`\n- `browser-perf`\n- `companion`\n- `config`\n- `directory-search-provider`\n- `file-browser`\n- `viewer`\n- `websocket`\n\nThese tags are not just naming style. They are the filter vocabulary for targeted trace collection.\n\nContributors should:\n\n- reuse an existing tag when the log belongs to an established subsystem\n- add a new tag only when it introduces a real new filter boundary\n- keep names stable once they appear in backend config or support playbooks\n\nOne log call still drives both surfaces. The component tag only changes backend-tracing selection behavior.\n\n## Error Context and Safety Rules\n\n`logger.error()` enriches the provided context when an `Error` object is passed.\n\n- `error.message`\n- `error.stack`\n- `error.name`\n\nThat gives support traces more useful failure context without forcing every caller to serialize errors manually.\n\nContributors still need to be selective.\n\n- include actionable IDs, paths, counts, durations, or status values\n- avoid passwords, tokens, private payloads, or large opaque objects\n- avoid high-volume logs inside tight loops or animation-heavy code paths\n\n## Contributor Rules\n\n- use the shared logger instead of scattering long-lived `console.*` calls through components and hooks\n- pass a component tag when backend trace filtering matters to the workflow you are changing\n- do not assume a visible console message also means backend tracing is enabled for that session\n- keep structured context specific and actionable instead of dumping large objects or noisy state snapshots\n- do not move tracing initialization earlier than authenticated startup without checking token and request-path assumptions\n\nThe supported call shape is:\n\n- `logger.debug(message, context?, component?)`\n- `logger.info(message, context?, component?)`\n- `logger.warn(message, context?, component?)`\n- `logger.error(message, context?, component?, error?)`\n\nParameter order matters. If a component tag is needed, it is the third argument for non-error calls and still the third argument for `logger.error()` before the optional `Error` object.\n\nThe older dedicated trace-only helpers are gone. Shared logger calls are the canonical path.\n\n## Test and Runtime Nuances\n\nThe logger deliberately behaves differently in tests.\n\n- test detection suppresses console output\n- backend tracing initialization is skipped in test environments\n- `loggingConfig` falls back to a disabled state when config loading fails\n\nThis is intentional defensive behavior, not a missing feature. It keeps tests quieter and prevents trace setup from leaking across environments.\n\n## Common Failure Modes\n\n- adding raw console logs that never reach backend trace collection\n- expecting a server-side logging-config change to apply instantly while a cached config is still valid\n- using inconsistent component names that make trace filtering unreliable\n- adding high-volume debug logs that drown out the actionable events\n- treating trace transport failures as if they were equivalent to application failures\n\nOther common mistakes include:\n\n- assuming the mobile-log download endpoint is `/api/logs/{filename}` instead of the current `/api/logs/download/{filename}` route\n- documenting stale field names such as `enabled` or `log_level` instead of the current `logging_*` and `tracing_*` contract\n- swapping the logger parameter order and accidentally passing the component tag as context\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nAdd or update targeted frontend tests when the change affects config caching, filtering behavior, startup initialization, or log transport.\n\nThe current targeted suites already cover the most important contracts:\n\n- `frontend/src/services/__tests__/loggingConfig.test.ts` for config shape, threshold logic, and disabled-state behavior\n- `frontend/src/services/__tests__/mobileLoggingApi.test.ts` for the mobile-log API payload and response contract\n\nIf the change touches backend receipt, storage, or filename behavior, pair the frontend checks with the relevant backend tests around `backend/app/api/logs.py` and `backend/tests/test_logging_config.py`.\n", "0.8": "+++\ntitle = \"Frontend Logging and Tracing\"\n+++\n\nThe browser app has one shared logging API, but it can feed two different diagnostic surfaces.\n\n- browser-console output for local development and interactive debugging\n- backend trace collection for support workflows and cases where direct console access is unavailable\n\nThat split matters because a small frontend logging change can improve one surface while degrading the other.\n\n## Main Implementation Files\n\n| File | Role |\n|---|---|\n| `frontend/src/services/logger.ts` | shared logging entry point and backend-tracing orchestration |\n| `frontend/src/services/loggingConfig.ts` | fetches and caches server logging config |\n| `frontend/src/services/logBuffer.ts` | buffers trace events before flush |\n| `frontend/src/services/logTransport.ts` | sends trace batches to `/api/logs/mobile` |\n| `backend/app/api/logs.py` | serves frontend logging config and accepts uploaded trace batches |\n| `backend/app/services/log_manager.py` | writes trace batches to JSONL files and cleans up retained logs |\n| `frontend/src/pages/Login.tsx` and `frontend/src/pages/FileBrowser.tsx` | initialize tracing after authenticated app startup |\n\n## Runtime Flow\n\n1. the authenticated browser app calls `logger.initializeBackendTracing()`\n2. the logger loads config through `loggingConfig.getConfig()`\n3. console logging level is updated from backend config when enabled\n4. backend tracing is enabled only when the server config allows it\n5. each logger call writes to the console if its level passes the console threshold\n6. the same call asynchronously checks trace level and component filters before buffering a backend trace entry\n7. the buffer flushes by size or interval and posts the batch to `/api/logs/mobile`\n\nThe log call is the single source of truth. Contributors should not have to choose between console visibility and trace collection by using different APIs.\n\n## Configuration Model\n\nThe frontend pulls logging state from the backend rather than hard-coding it in the browser app.\n\n- `logging_enabled` and `logging_level` control console output\n- `tracing_enabled`, `tracing_level`, and `tracing_components` control backend trace collection\n- `frontend_tracing_username_regex` on the backend can disable tracing for users who do not match the configured pattern\n- `loggingConfig` caches the fetched config in `localStorage` for five minutes to avoid repeated requests\n\nThe logger also keeps different local defaults before server config is loaded.\n\n- development builds default to verbose console logging\n- production builds default to warnings and errors\n- test runs skip backend tracing setup entirely\n\nThe current backend contract is exposed through `GET /api/logs/config` and returns:\n\n- `logging_enabled`\n- `logging_level`\n- `tracing_enabled`\n- `tracing_level`\n- `tracing_components`\n\n`loggingConfig` then adds a client-side timestamp when caching the response locally.\n\n### Level and Component Filtering\n\nConsole logging and backend tracing are independent.\n\n- console output is gated only by `logging_enabled` plus the effective console level\n- backend tracing is gated by `tracing_enabled`, `tracing_level`, and optional component matching\n- an empty `tracing_components` list means all components are accepted\n- component matching is exact string matching, so inconsistent tag names reduce the usefulness of filtered tracing quickly\n\nLevel filtering is threshold-based.\n\n- `DEBUG` allows everything\n- `INFO` suppresses only `DEBUG`\n- `WARNING` allows `WARNING` and `ERROR`\n- `ERROR` allows only `ERROR`\n\n## Buffering and Transport\n\nBackend tracing is buffered on purpose.\n\n- `LogBuffer` groups trace entries in memory instead of posting every log call immediately\n- each batch carries a generated session ID plus device information such as user agent, screen size, and touch capability\n- the default flush behavior is size-based or time-based, whichever happens first\n- failed flushes keep the buffered entries for retry on the next flush attempt\n\nThe current implementation details are worth preserving:\n\n- `LogBuffer` generates one session ID for the browser runtime that enabled tracing\n- the batch payload includes `userAgent`, screen size, `devicePixelRatio`, platform, and touch capability\n- `LogTransport` uses `fetch` directly instead of the shared API service to avoid circular dependencies in the logging stack\n- trace uploads include the bearer token when one is available\n- if repeated flush failures push the in-memory buffer above twice the configured size, the oldest entries are dropped to cap memory growth\n\nThis design keeps routine logging cheap while still giving the backend enough session context to debug real field problems.\n\n### Backend Receipt and Storage\n\nThe backend logging API is simple and file-backed.\n\n- `POST /api/logs/mobile` accepts a trace batch for the authenticated user\n- `GET /api/logs/config` serves the frontend logging configuration\n- `GET /api/logs/list` lists available uploaded mobile-log files\n- `GET /api/logs/download/{filename}` downloads a stored log file\n\nUploaded trace batches are written under `data/mobile_logs/` as JSONL files.\n\n- the first line is metadata, including session ID, device info, server timestamp, and request metadata such as client IP or user agent\n- subsequent lines are individual log entries\n- retention cleanup is handled by `MobileLogManager.cleanup_old_logs()` using the configured retention window\n\nThis is why frontend logging changes can affect both browser behavior and support-facing backend artifacts.\n\n## Component Tags and Taxonomy\n\nComponent tags are optional for console output but important for backend tracing.\n\nRepresentative tags currently used in the frontend include:\n\n- `api`\n- `auth`\n- `backend-recovery`\n- `browser`\n- `browser-perf`\n- `companion`\n- `config`\n- `directory-search-provider`\n- `file-browser`\n- `viewer`\n- `websocket`\n\nThese tags are not just naming style. They are the filter vocabulary for targeted trace collection.\n\nContributors should:\n\n- reuse an existing tag when the log belongs to an established subsystem\n- add a new tag only when it introduces a real new filter boundary\n- keep names stable once they appear in backend config or support playbooks\n\nOne log call still drives both surfaces. The component tag only changes backend-tracing selection behavior.\n\n## Error Context and Safety Rules\n\n`logger.error()` enriches the provided context when an `Error` object is passed.\n\n- `error.message`\n- `error.stack`\n- `error.name`\n\nThat gives support traces more useful failure context without forcing every caller to serialize errors manually.\n\nContributors still need to be selective.\n\n- include actionable IDs, paths, counts, durations, or status values\n- avoid passwords, tokens, private payloads, or large opaque objects\n- avoid high-volume logs inside tight loops or animation-heavy code paths\n\n## Contributor Rules\n\n- use the shared logger instead of scattering long-lived `console.*` calls through components and hooks\n- pass a component tag when backend trace filtering matters to the workflow you are changing\n- do not assume a visible console message also means backend tracing is enabled for that session\n- keep structured context specific and actionable instead of dumping large objects or noisy state snapshots\n- do not move tracing initialization earlier than authenticated startup without checking token and request-path assumptions\n\nThe supported call shape is:\n\n- `logger.debug(message, context?, component?)`\n- `logger.info(message, context?, component?)`\n- `logger.warn(message, context?, component?)`\n- `logger.error(message, context?, component?, error?)`\n\nParameter order matters. If a component tag is needed, it is the third argument for non-error calls and still the third argument for `logger.error()` before the optional `Error` object.\n\nThe older dedicated trace-only helpers are gone. Shared logger calls are the canonical path.\n\n## Test and Runtime Nuances\n\nThe logger deliberately behaves differently in tests.\n\n- test detection suppresses console output\n- backend tracing initialization is skipped in test environments\n- `loggingConfig` falls back to a disabled state when config loading fails\n\nThis is intentional defensive behavior, not a missing feature. It keeps tests quieter and prevents trace setup from leaking across environments.\n\n## Common Failure Modes\n\n- adding raw console logs that never reach backend trace collection\n- expecting a server-side logging-config change to apply instantly while a cached config is still valid\n- using inconsistent component names that make trace filtering unreliable\n- adding high-volume debug logs that drown out the actionable events\n- treating trace transport failures as if they were equivalent to application failures\n\nOther common mistakes include:\n\n- assuming the mobile-log download endpoint is `/api/logs/{filename}` instead of the current `/api/logs/download/{filename}` route\n- documenting stale field names such as `enabled` or `log_level` instead of the current `logging_*` and `tracing_*` contract\n- swapping the logger parameter order and accidentally passing the component tag as context\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nAdd or update targeted frontend tests when the change affects config caching, filtering behavior, startup initialization, or log transport.\n\nThe current targeted suites already cover the most important contracts:\n\n- `frontend/src/services/__tests__/loggingConfig.test.ts` for config shape, threshold logic, and disabled-state behavior\n- `frontend/src/services/__tests__/mobileLoggingApi.test.ts` for the mobile-log API payload and response contract\n\nIf the change touches backend receipt, storage, or filename behavior, pair the frontend checks with the relevant backend tests around `backend/app/api/logs.py` and `backend/tests/test_logging_config.py`.\n", "0.9": "+++\ntitle = \"Frontend Logging and Tracing\"\n+++\n\nThe browser app has one shared logging API, but it can feed two different diagnostic surfaces.\n\n- browser-console output for local development and interactive debugging\n- backend trace collection for support workflows and cases where direct console access is unavailable\n\nThat split matters because a small frontend logging change can improve one surface while degrading the other.\n\n## Main Implementation Files\n\n| File | Role |\n|---|---|\n| `frontend/src/services/logger.ts` | shared logging entry point and backend-tracing orchestration |\n| `frontend/src/services/loggingConfig.ts` | fetches and caches server logging config |\n| `frontend/src/services/logBuffer.ts` | buffers trace events before flush |\n| `frontend/src/services/logTransport.ts` | sends trace batches to `/api/logs/mobile` |\n| `backend/app/api/logs.py` | serves frontend logging config and accepts uploaded trace batches |\n| `backend/app/services/log_manager.py` | writes trace batches to JSONL files and cleans up retained logs |\n| `frontend/src/pages/Login.tsx` and `frontend/src/pages/FileBrowser.tsx` | initialize tracing after authenticated app startup |\n\n## Runtime Flow\n\n1. the authenticated browser app calls `logger.initializeBackendTracing()`\n2. the logger loads config through `loggingConfig.getConfig()`\n3. console logging level is updated from backend config when enabled\n4. backend tracing is enabled only when the server config allows it\n5. each logger call writes to the console if its level passes the console threshold\n6. the same call asynchronously checks trace level and component filters before buffering a backend trace entry\n7. the buffer flushes by size or interval and posts the batch to `/api/logs/mobile`\n\nThe log call is the single source of truth. Contributors should not have to choose between console visibility and trace collection by using different APIs.\n\n## Configuration Model\n\nThe frontend pulls logging state from the backend rather than hard-coding it in the browser app.\n\n- `logging_enabled` and `logging_level` control console output\n- `tracing_enabled`, `tracing_level`, and `tracing_components` control backend trace collection\n- `frontend_tracing_username_regex` on the backend can disable tracing for users who do not match the configured pattern\n- `loggingConfig` caches the fetched config in `localStorage` for five minutes to avoid repeated requests\n\nThe logger also keeps different local defaults before server config is loaded.\n\n- development builds default to verbose console logging\n- production builds default to warnings and errors\n- test runs skip backend tracing setup entirely\n\nThe current backend contract is exposed through `GET /api/logs/config` and returns:\n\n- `logging_enabled`\n- `logging_level`\n- `tracing_enabled`\n- `tracing_level`\n- `tracing_components`\n\n`loggingConfig` then adds a client-side timestamp when caching the response locally.\n\n### Level and Component Filtering\n\nConsole logging and backend tracing are independent.\n\n- console output is gated only by `logging_enabled` plus the effective console level\n- backend tracing is gated by `tracing_enabled`, `tracing_level`, and optional component matching\n- an empty `tracing_components` list means all components are accepted\n- component matching is exact string matching, so inconsistent tag names reduce the usefulness of filtered tracing quickly\n\nLevel filtering is threshold-based.\n\n- `DEBUG` allows everything\n- `INFO` suppresses only `DEBUG`\n- `WARNING` allows `WARNING` and `ERROR`\n- `ERROR` allows only `ERROR`\n\n## Buffering and Transport\n\nBackend tracing is buffered on purpose.\n\n- `LogBuffer` groups trace entries in memory instead of posting every log call immediately\n- each batch carries a generated session ID plus device information such as user agent, screen size, and touch capability\n- the default flush behavior is size-based or time-based, whichever happens first\n- failed flushes keep the buffered entries for retry on the next flush attempt\n\nThe current implementation details are worth preserving:\n\n- `LogBuffer` generates one session ID for the browser runtime that enabled tracing\n- the batch payload includes `userAgent`, screen size, `devicePixelRatio`, platform, and touch capability\n- `LogTransport` uses `fetch` directly instead of the shared API service to avoid circular dependencies in the logging stack\n- trace uploads include the bearer token when one is available\n- if repeated flush failures push the in-memory buffer above twice the configured size, the oldest entries are dropped to cap memory growth\n\nThis design keeps routine logging cheap while still giving the backend enough session context to debug real field problems.\n\n### Backend Receipt and Storage\n\nThe backend logging API is simple and file-backed.\n\n- `POST /api/logs/mobile` accepts a trace batch for the authenticated user\n- `GET /api/logs/config` serves the frontend logging configuration\n- `GET /api/logs/list` lists available uploaded mobile-log files\n- `GET /api/logs/download/{filename}` downloads a stored log file\n\nUploaded trace batches are written under `data/mobile_logs/` as JSONL files.\n\n- the first line is metadata, including session ID, device info, server timestamp, and request metadata such as client IP or user agent\n- subsequent lines are individual log entries\n- retention cleanup is handled by `MobileLogManager.cleanup_old_logs()` using the configured retention window\n\nThis is why frontend logging changes can affect both browser behavior and support-facing backend artifacts.\n\n## Component Tags and Taxonomy\n\nComponent tags are optional for console output but important for backend tracing.\n\nRepresentative tags currently used in the frontend include:\n\n- `api`\n- `auth`\n- `backend-recovery`\n- `browser`\n- `browser-perf`\n- `companion`\n- `config`\n- `directory-search-provider`\n- `file-browser`\n- `viewer`\n- `websocket`\n\nThese tags are not just naming style. They are the filter vocabulary for targeted trace collection.\n\nContributors should:\n\n- reuse an existing tag when the log belongs to an established subsystem\n- add a new tag only when it introduces a real new filter boundary\n- keep names stable once they appear in backend config or support playbooks\n\nOne log call still drives both surfaces. The component tag only changes backend-tracing selection behavior.\n\n## Error Context and Safety Rules\n\n`logger.error()` enriches the provided context when an `Error` object is passed.\n\n- `error.message`\n- `error.stack`\n- `error.name`\n\nThat gives support traces more useful failure context without forcing every caller to serialize errors manually.\n\nContributors still need to be selective.\n\n- include actionable IDs, paths, counts, durations, or status values\n- avoid passwords, tokens, private payloads, or large opaque objects\n- avoid high-volume logs inside tight loops or animation-heavy code paths\n\n## Contributor Rules\n\n- use the shared logger instead of scattering long-lived `console.*` calls through components and hooks\n- pass a component tag when backend trace filtering matters to the workflow you are changing\n- do not assume a visible console message also means backend tracing is enabled for that session\n- keep structured context specific and actionable instead of dumping large objects or noisy state snapshots\n- do not move tracing initialization earlier than authenticated startup without checking token and request-path assumptions\n\nThe supported call shape is:\n\n- `logger.debug(message, context?, component?)`\n- `logger.info(message, context?, component?)`\n- `logger.warn(message, context?, component?)`\n- `logger.error(message, context?, component?, error?)`\n\nParameter order matters. If a component tag is needed, it is the third argument for non-error calls and still the third argument for `logger.error()` before the optional `Error` object.\n\nThe older dedicated trace-only helpers are gone. Shared logger calls are the canonical path.\n\n## Test and Runtime Nuances\n\nThe logger deliberately behaves differently in tests.\n\n- test detection suppresses console output\n- backend tracing initialization is skipped in test environments\n- `loggingConfig` falls back to a disabled state when config loading fails\n\nThis is intentional defensive behavior, not a missing feature. It keeps tests quieter and prevents trace setup from leaking across environments.\n\n## Common Failure Modes\n\n- adding raw console logs that never reach backend trace collection\n- expecting a server-side logging-config change to apply instantly while a cached config is still valid\n- using inconsistent component names that make trace filtering unreliable\n- adding high-volume debug logs that drown out the actionable events\n- treating trace transport failures as if they were equivalent to application failures\n\nOther common mistakes include:\n\n- assuming the mobile-log download endpoint is `/api/logs/{filename}` instead of the current `/api/logs/download/{filename}` route\n- documenting stale field names such as `enabled` or `log_level` instead of the current `logging_*` and `tracing_*` contract\n- swapping the logger parameter order and accidentally passing the component tag as context\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nAdd or update targeted frontend tests when the change affects config caching, filtering behavior, startup initialization, or log transport.\n\nThe current targeted suites already cover the most important contracts:\n\n- `frontend/src/services/__tests__/loggingConfig.test.ts` for config shape, threshold logic, and disabled-state behavior\n- `frontend/src/services/__tests__/mobileLoggingApi.test.ts` for the mobile-log API payload and response contract\n\nIf the change touches backend receipt, storage, or filename behavior, pair the frontend checks with the relevant backend tests around `backend/app/api/logs.py` and `backend/tests/test_logging_config.py`.\n", "1.0": "+++\ntitle = \"Frontend Logging and Tracing\"\n+++\n\nThe browser app has one shared logging API, but it can feed two different diagnostic surfaces.\n\n- browser-console output for local development and interactive debugging\n- backend trace collection for support workflows and cases where direct console access is unavailable\n\nThat split matters because a small frontend logging change can improve one surface while degrading the other.\n\n## Main Implementation Files\n\n| File | Role |\n|---|---|\n| `frontend/src/services/logger.ts` | shared logging entry point and backend-tracing orchestration |\n| `frontend/src/services/loggingConfig.ts` | fetches and caches server logging config |\n| `frontend/src/services/logBuffer.ts` | buffers trace events before flush |\n| `frontend/src/services/logTransport.ts` | sends trace batches to `/api/logs/mobile` |\n| `backend/app/api/logs.py` | serves frontend logging config and accepts uploaded trace batches |\n| `backend/app/services/log_manager.py` | writes trace batches to JSONL files and cleans up retained logs |\n| `frontend/src/pages/Login.tsx` and `frontend/src/pages/FileBrowser.tsx` | initialize tracing after authenticated app startup |\n\n## Runtime Flow\n\n1. the authenticated browser app calls `logger.initializeBackendTracing()`\n2. the logger loads config through `loggingConfig.getConfig()`\n3. console logging level is updated from backend config when enabled\n4. backend tracing is enabled only when the server config allows it\n5. each logger call writes to the console if its level passes the console threshold\n6. the same call asynchronously checks trace level and component filters before buffering a backend trace entry\n7. the buffer flushes by size or interval and posts the batch to `/api/logs/mobile`\n\nThe log call is the single source of truth. Contributors should not have to choose between console visibility and trace collection by using different APIs.\n\n## Configuration Model\n\nThe frontend pulls logging state from the backend rather than hard-coding it in the browser app.\n\n- `logging_enabled` and `logging_level` control console output\n- `tracing_enabled`, `tracing_level`, and `tracing_components` control backend trace collection\n- `frontend_tracing_username_regex` on the backend can disable tracing for users who do not match the configured pattern\n- `loggingConfig` caches the fetched config in `localStorage` for five minutes to avoid repeated requests\n\nThe logger also keeps different local defaults before server config is loaded.\n\n- development builds default to verbose console logging\n- production builds default to warnings and errors\n- test runs skip backend tracing setup entirely\n\nThe current backend contract is exposed through `GET /api/logs/config` and returns:\n\n- `logging_enabled`\n- `logging_level`\n- `tracing_enabled`\n- `tracing_level`\n- `tracing_components`\n\n`loggingConfig` then adds a client-side timestamp when caching the response locally.\n\n### Level and Component Filtering\n\nConsole logging and backend tracing are independent.\n\n- console output is gated only by `logging_enabled` plus the effective console level\n- backend tracing is gated by `tracing_enabled`, `tracing_level`, and optional component matching\n- an empty `tracing_components` list means all components are accepted\n- component matching is exact string matching, so inconsistent tag names reduce the usefulness of filtered tracing quickly\n\nLevel filtering is threshold-based.\n\n- `DEBUG` allows everything\n- `INFO` suppresses only `DEBUG`\n- `WARNING` allows `WARNING` and `ERROR`\n- `ERROR` allows only `ERROR`\n\n## Buffering and Transport\n\nBackend tracing is buffered on purpose.\n\n- `LogBuffer` groups trace entries in memory instead of posting every log call immediately\n- each batch carries a generated session ID plus device information such as user agent, screen size, and touch capability\n- the default flush behavior is size-based or time-based, whichever happens first\n- failed flushes keep the buffered entries for retry on the next flush attempt\n\nThe current implementation details are worth preserving:\n\n- `LogBuffer` generates one session ID for the browser runtime that enabled tracing\n- the batch payload includes `userAgent`, screen size, `devicePixelRatio`, platform, and touch capability\n- `LogTransport` uses `fetch` directly instead of the shared API service to avoid circular dependencies in the logging stack\n- trace uploads include the bearer token when one is available\n- if repeated flush failures push the in-memory buffer above twice the configured size, the oldest entries are dropped to cap memory growth\n\nThis design keeps routine logging cheap while still giving the backend enough session context to debug real field problems.\n\n### Backend Receipt and Storage\n\nThe backend logging API is simple and file-backed.\n\n- `POST /api/logs/mobile` accepts a trace batch for the authenticated user\n- `GET /api/logs/config` serves the frontend logging configuration\n- `GET /api/logs/list` lists available uploaded mobile-log files\n- `GET /api/logs/download/{filename}` downloads a stored log file\n\nUploaded trace batches are written under `data/mobile_logs/` as JSONL files.\n\n- the first line is metadata, including session ID, device info, server timestamp, and request metadata such as client IP or user agent\n- subsequent lines are individual log entries\n- retention cleanup is handled by `MobileLogManager.cleanup_old_logs()` using the configured retention window\n\nThis is why frontend logging changes can affect both browser behavior and support-facing backend artifacts.\n\n## Component Tags and Taxonomy\n\nComponent tags are optional for console output but important for backend tracing.\n\nRepresentative tags currently used in the frontend include:\n\n- `api`\n- `auth`\n- `backend-recovery`\n- `browser`\n- `browser-perf`\n- `companion`\n- `config`\n- `directory-search-provider`\n- `file-browser`\n- `viewer`\n- `websocket`\n\nThese tags are not just naming style. They are the filter vocabulary for targeted trace collection.\n\nContributors should:\n\n- reuse an existing tag when the log belongs to an established subsystem\n- add a new tag only when it introduces a real new filter boundary\n- keep names stable once they appear in backend config or support playbooks\n\nOne log call still drives both surfaces. The component tag only changes backend-tracing selection behavior.\n\n## Error Context and Safety Rules\n\n`logger.error()` enriches the provided context when an `Error` object is passed.\n\n- `error.message`\n- `error.stack`\n- `error.name`\n\nThat gives support traces more useful failure context without forcing every caller to serialize errors manually.\n\nContributors still need to be selective.\n\n- include actionable IDs, paths, counts, durations, or status values\n- avoid passwords, tokens, private payloads, or large opaque objects\n- avoid high-volume logs inside tight loops or animation-heavy code paths\n\n## Contributor Rules\n\n- use the shared logger instead of scattering long-lived `console.*` calls through components and hooks\n- pass a component tag when backend trace filtering matters to the workflow you are changing\n- do not assume a visible console message also means backend tracing is enabled for that session\n- keep structured context specific and actionable instead of dumping large objects or noisy state snapshots\n- do not move tracing initialization earlier than authenticated startup without checking token and request-path assumptions\n\nThe supported call shape is:\n\n- `logger.debug(message, context?, component?)`\n- `logger.info(message, context?, component?)`\n- `logger.warn(message, context?, component?)`\n- `logger.error(message, context?, component?, error?)`\n\nParameter order matters. If a component tag is needed, it is the third argument for non-error calls and still the third argument for `logger.error()` before the optional `Error` object.\n\nThe older dedicated trace-only helpers are gone. Shared logger calls are the canonical path.\n\n## Test and Runtime Nuances\n\nThe logger deliberately behaves differently in tests.\n\n- test detection suppresses console output\n- backend tracing initialization is skipped in test environments\n- `loggingConfig` falls back to a disabled state when config loading fails\n\nThis is intentional defensive behavior, not a missing feature. It keeps tests quieter and prevents trace setup from leaking across environments.\n\n## Common Failure Modes\n\n- adding raw console logs that never reach backend trace collection\n- expecting a server-side logging-config change to apply instantly while a cached config is still valid\n- using inconsistent component names that make trace filtering unreliable\n- adding high-volume debug logs that drown out the actionable events\n- treating trace transport failures as if they were equivalent to application failures\n\nOther common mistakes include:\n\n- assuming the mobile-log download endpoint is `/api/logs/{filename}` instead of the current `/api/logs/download/{filename}` route\n- documenting stale field names such as `enabled` or `log_level` instead of the current `logging_*` and `tracing_*` contract\n- swapping the logger parameter order and accidentally passing the component tag as context\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nAdd or update targeted frontend tests when the change affects config caching, filtering behavior, startup initialization, or log transport.\n\nThe current targeted suites already cover the most important contracts:\n\n- `frontend/src/services/__tests__/loggingConfig.test.ts` for config shape, threshold logic, and disabled-state behavior\n- `frontend/src/services/__tests__/mobileLoggingApi.test.ts` for the mobile-log API payload and response contract\n\nIf the change touches backend receipt, storage, or filename behavior, pair the frontend checks with the relevant backend tests around `backend/app/api/logs.py` and `backend/tests/test_logging_config.py`.\n", "2.0": "+++\ntitle = \"Frontend Logging and Tracing\"\n+++\n\nThe browser app has one shared logging API, but it can feed two different diagnostic surfaces.\n\n- browser-console output for local development and interactive debugging\n- backend trace collection for support workflows and cases where direct console access is unavailable\n\nThat split matters because a small frontend logging change can improve one surface while degrading the other.\n\n## Main Implementation Files\n\n| File | Role |\n|---|---|\n| `frontend/src/services/logger.ts` | shared logging entry point and backend-tracing orchestration |\n| `frontend/src/services/loggingConfig.ts` | fetches and caches server logging config |\n| `frontend/src/services/logBuffer.ts` | buffers trace events before flush |\n| `frontend/src/services/logTransport.ts` | sends trace batches to `/api/logs/mobile` |\n| `backend/app/api/logs.py` | serves frontend logging config and accepts uploaded trace batches |\n| `backend/app/services/log_manager.py` | writes trace batches to JSONL files and cleans up retained logs |\n| `frontend/src/pages/Login.tsx` and `frontend/src/pages/FileBrowser.tsx` | initialize tracing after authenticated app startup |\n\n## Runtime Flow\n\n1. the authenticated browser app calls `logger.initializeBackendTracing()`\n2. the logger loads config through `loggingConfig.getConfig()`\n3. console logging level is updated from backend config when enabled\n4. backend tracing is enabled only when the server config allows it\n5. each logger call writes to the console if its level passes the console threshold\n6. the same call asynchronously checks trace level and component filters before buffering a backend trace entry\n7. the buffer flushes by size or interval and posts the batch to `/api/logs/mobile`\n\nThe log call is the single source of truth. Contributors should not have to choose between console visibility and trace collection by using different APIs.\n\n## Configuration Model\n\nThe frontend pulls logging state from the backend rather than hard-coding it in the browser app.\n\n- `logging_enabled` and `logging_level` control console output\n- `tracing_enabled`, `tracing_level`, and `tracing_components` control backend trace collection\n- `frontend_tracing_username_regex` on the backend can disable tracing for users who do not match the configured pattern\n- `loggingConfig` caches the fetched config in `localStorage` for five minutes to avoid repeated requests\n\nThe logger also keeps different local defaults before server config is loaded.\n\n- development builds default to verbose console logging\n- production builds default to warnings and errors\n- test runs skip backend tracing setup entirely\n\nThe current backend contract is exposed through `GET /api/logs/config` and returns:\n\n- `logging_enabled`\n- `logging_level`\n- `tracing_enabled`\n- `tracing_level`\n- `tracing_components`\n\n`loggingConfig` then adds a client-side timestamp when caching the response locally.\n\n### Level and Component Filtering\n\nConsole logging and backend tracing are independent.\n\n- console output is gated only by `logging_enabled` plus the effective console level\n- backend tracing is gated by `tracing_enabled`, `tracing_level`, and optional component matching\n- an empty `tracing_components` list means all components are accepted\n- component matching is exact string matching, so inconsistent tag names reduce the usefulness of filtered tracing quickly\n\nLevel filtering is threshold-based.\n\n- `DEBUG` allows everything\n- `INFO` suppresses only `DEBUG`\n- `WARNING` allows `WARNING` and `ERROR`\n- `ERROR` allows only `ERROR`\n\n## Buffering and Transport\n\nBackend tracing is buffered on purpose.\n\n- `LogBuffer` groups trace entries in memory instead of posting every log call immediately\n- each batch carries a generated session ID plus device information such as user agent, screen size, and touch capability\n- the default flush behavior is size-based or time-based, whichever happens first\n- failed flushes keep the buffered entries for retry on the next flush attempt\n\nThe current implementation details are worth preserving:\n\n- `LogBuffer` generates one session ID for the browser runtime that enabled tracing\n- the batch payload includes `userAgent`, screen size, `devicePixelRatio`, platform, and touch capability\n- `LogTransport` uses `fetch` directly instead of the shared API service to avoid circular dependencies in the logging stack\n- trace uploads include the bearer token when one is available\n- if repeated flush failures push the in-memory buffer above twice the configured size, the oldest entries are dropped to cap memory growth\n\nThis design keeps routine logging cheap while still giving the backend enough session context to debug real field problems.\n\n### Backend Receipt and Storage\n\nThe backend logging API is simple and file-backed.\n\n- `POST /api/logs/mobile` accepts a trace batch for the authenticated user\n- `GET /api/logs/config` serves the frontend logging configuration\n- `GET /api/logs/list` lists available uploaded mobile-log files\n- `GET /api/logs/download/{filename}` downloads a stored log file\n\nUploaded trace batches are written under `data/mobile_logs/` as JSONL files.\n\n- the first line is metadata, including session ID, device info, server timestamp, and request metadata such as client IP or user agent\n- subsequent lines are individual log entries\n- retention cleanup is handled by `MobileLogManager.cleanup_old_logs()` using the configured retention window\n\nThis is why frontend logging changes can affect both browser behavior and support-facing backend artifacts.\n\n## Component Tags and Taxonomy\n\nComponent tags are optional for console output but important for backend tracing.\n\nRepresentative tags currently used in the frontend include:\n\n- `api`\n- `auth`\n- `backend-recovery`\n- `browser`\n- `browser-perf`\n- `companion`\n- `config`\n- `directory-search-provider`\n- `file-browser`\n- `viewer`\n- `websocket`\n\nThese tags are not just naming style. They are the filter vocabulary for targeted trace collection.\n\nContributors should:\n\n- reuse an existing tag when the log belongs to an established subsystem\n- add a new tag only when it introduces a real new filter boundary\n- keep names stable once they appear in backend config or support playbooks\n\nOne log call still drives both surfaces. The component tag only changes backend-tracing selection behavior.\n\n## Error Context and Safety Rules\n\n`logger.error()` enriches the provided context when an `Error` object is passed.\n\n- `error.message`\n- `error.stack`\n- `error.name`\n\nThat gives support traces more useful failure context without forcing every caller to serialize errors manually.\n\nContributors still need to be selective.\n\n- include actionable IDs, paths, counts, durations, or status values\n- avoid passwords, tokens, private payloads, or large opaque objects\n- avoid high-volume logs inside tight loops or animation-heavy code paths\n\n## Contributor Rules\n\n- use the shared logger instead of scattering long-lived `console.*` calls through components and hooks\n- pass a component tag when backend trace filtering matters to the workflow you are changing\n- do not assume a visible console message also means backend tracing is enabled for that session\n- keep structured context specific and actionable instead of dumping large objects or noisy state snapshots\n- do not move tracing initialization earlier than authenticated startup without checking token and request-path assumptions\n\nThe supported call shape is:\n\n- `logger.debug(message, context?, component?)`\n- `logger.info(message, context?, component?)`\n- `logger.warn(message, context?, component?)`\n- `logger.error(message, context?, component?, error?)`\n\nParameter order matters. If a component tag is needed, it is the third argument for non-error calls and still the third argument for `logger.error()` before the optional `Error` object.\n\nThe older dedicated trace-only helpers are gone. Shared logger calls are the canonical path.\n\n## Test and Runtime Nuances\n\nThe logger deliberately behaves differently in tests.\n\n- test detection suppresses console output\n- backend tracing initialization is skipped in test environments\n- `loggingConfig` falls back to a disabled state when config loading fails\n\nThis is intentional defensive behavior, not a missing feature. It keeps tests quieter and prevents trace setup from leaking across environments.\n\n## Common Failure Modes\n\n- adding raw console logs that never reach backend trace collection\n- expecting a server-side logging-config change to apply instantly while a cached config is still valid\n- using inconsistent component names that make trace filtering unreliable\n- adding high-volume debug logs that drown out the actionable events\n- treating trace transport failures as if they were equivalent to application failures\n\nOther common mistakes include:\n\n- assuming the mobile-log download endpoint is `/api/logs/{filename}` instead of the current `/api/logs/download/{filename}` route\n- documenting stale field names such as `enabled` or `log_level` instead of the current `logging_*` and `tracing_*` contract\n- swapping the logger parameter order and accidentally passing the component tag as context\n\n## Validation Expectations\n\nWhen this area changes, usually run:\n\n```bash\ncd frontend \u0026\u0026 npx tsc --noEmit\ncd frontend \u0026\u0026 npm run lint\n```\n\nAdd or update targeted frontend tests when the change affects config caching, filtering behavior, startup initialization, or log transport.\n\nThe current targeted suites already cover the most important contracts:\n\n- `frontend/src/services/__tests__/loggingConfig.test.ts` for config shape, threshold logic, and disabled-state behavior\n- `frontend/src/services/__tests__/mobileLoggingApi.test.ts` for the mobile-log API payload and response contract\n\nIf the change touches backend receipt, storage, or filename behavior, pair the frontend checks with the relevant backend tests around `backend/app/api/logs.py` and `backend/tests/test_logging_config.py`.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:developer-guide/testing-and-quality-gates", "parent_id": "book:developer-guide", "depth": 1, "kind": "section", "label": "testing-and-quality-gates", "title": "Testing and Quality Gates", "path": "developer-guide/testing-and-quality-gates", "has_children": true, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Testing and Quality Gates\"\n+++\n\nThis section helps contributors choose the right validation depth instead of running either too little or everything all the time.\n\nStart with:\n\n- [Test Strategy Overview](./test-strategy-overview/)\n\nRelated supporting pages:\n\n- [CI Workflows and Repository Automation](./ci-workflows-and-repository-automation/)\n- [Logging and Localization](../cross-cutting-systems/logging-and-localization/)\n- [Dependency Update Workflow](../release-and-versioning/dependency-update-workflow/)\n\nUse this section before you finish a change that affects API behavior, UI behavior, or companion workflows.\n", "0.8": "+++\ntitle = \"Testing and Quality Gates\"\n+++\n\nThis section helps contributors choose the right validation depth instead of running either too little or everything all the time.\n\nStart with:\n\n- [Test Strategy Overview](./test-strategy-overview/)\n\nRelated supporting pages:\n\n- [CI Workflows and Repository Automation](./ci-workflows-and-repository-automation/)\n- [Logging and Localization](../cross-cutting-systems/logging-and-localization/)\n- [Dependency Update Workflow](../release-and-versioning/dependency-update-workflow/)\n\nUse this section before you finish a change that affects API behavior, UI behavior, or companion workflows.\n", "0.9": "+++\ntitle = \"Testing and Quality Gates\"\n+++\n\nThis section helps contributors choose the right validation depth instead of running either too little or everything all the time.\n\nStart with:\n\n- [Test Strategy Overview](./test-strategy-overview/)\n\nRelated supporting pages:\n\n- [CI Workflows and Repository Automation](./ci-workflows-and-repository-automation/)\n- [Logging and Localization](../cross-cutting-systems/logging-and-localization/)\n- [Dependency Update Workflow](../release-and-versioning/dependency-update-workflow/)\n\nUse this section before you finish a change that affects API behavior, UI behavior, or companion workflows.\n", "1.0": "+++\ntitle = \"Testing and Quality Gates\"\n+++\n\nThis section helps contributors choose the right validation depth instead of running either too little or everything all the time.\n\nStart with:\n\n- [Test Strategy Overview](./test-strategy-overview/)\n\nRelated supporting pages:\n\n- [CI Workflows and Repository Automation](./ci-workflows-and-repository-automation/)\n- [Logging and Localization](../cross-cutting-systems/logging-and-localization/)\n- [Dependency Update Workflow](../release-and-versioning/dependency-update-workflow/)\n\nUse this section before you finish a change that affects API behavior, UI behavior, or companion workflows.\n", "2.0": "+++\ntitle = \"Testing and Quality Gates\"\n+++\n\nThis section helps contributors choose the right validation depth instead of running either too little or everything all the time.\n\nStart with:\n\n- [Test Strategy Overview](./test-strategy-overview/)\n\nRelated supporting pages:\n\n- [CI Workflows and Repository Automation](./ci-workflows-and-repository-automation/)\n- [Logging and Localization](../cross-cutting-systems/logging-and-localization/)\n- [Dependency Update Workflow](../release-and-versioning/dependency-update-workflow/)\n\nUse this section before you finish a change that affects API behavior, UI behavior, or companion workflows.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/testing-and-quality-gates/test-strategy-overview", "parent_id": "section:developer-guide/testing-and-quality-gates", "depth": 2, "kind": "page", "label": "test-strategy-overview", "title": "Test Strategy Overview", "path": "developer-guide/testing-and-quality-gates/test-strategy-overview", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "branched", "source_version": "0.7", "diff_added": 29, "diff_removed": 4}, "0.9": {"state": "inherited", "source_version": "0.8"}, "1.0": {"state": "inherited", "source_version": "0.8"}, "2.0": {"state": "inherited", "source_version": "0.8"}}, "content_versions": {"0.7": "+++\ntitle = \"Test Strategy Overview\"\n+++\n\nSambee has multiple subsystems, so the right validation strategy depends on which contract you changed.\n\n## Start with the Smallest Relevant Set\n\nDo not default to either no validation or every possible check.\n\n- backend-only change with no shared contract impact: run backend tests and type checking\n- frontend-only change: run frontend tests, type check, and lint\n- companion-only change: run companion checks and Rust tests\n- shared workflow change: run every affected subsystem's checks\n\n## Recommended Checks by Change Area\n\n| Change area | Baseline checks |\n|---|---|\n| Backend behavior | `cd backend \u0026\u0026 pytest -m 'not performance' -v`, `cd backend \u0026\u0026 pytest -m performance -v`, `cd backend \u0026\u0026 mypy app` |\n| Frontend behavior | `cd frontend \u0026\u0026 npm test`, `cd frontend \u0026\u0026 npx tsc --noEmit`, `cd frontend \u0026\u0026 npm run lint` |\n| Companion behavior | `cd companion \u0026\u0026 npx tsc --noEmit`, `cd companion \u0026\u0026 npm run lint`, `cd companion/src-tauri \u0026\u0026 cargo test` |\n\nFor fast local iteration, `./scripts/test` runs the main backend, frontend, companion, and archive-topology suites together. It stops at the first failed check so you can fix that subsystem before spending time on later suites. The order is backend type checking and tests, frontend type checking, linting, and tests, companion checks and tests, then archive-specific topology verification. Its backend pass mirrors CI by running non-performance tests in parallel and `@performance` tests in a separate serial pass. Use `COVERAGE=1 ./scripts/test` when you want the broader CI-style coverage pass.\n\n## Cross-Boundary Changes Need Cross-Boundary Checks\n\nRun broader coverage when you change a shared contract, for example:\n\n- backend response shape that the frontend consumes\n- companion behavior that changes browser-facing pairing or editing flows\n- localization or logging behavior that spans more than one app\n\n## Contract-Sensitive Areas\n\n### API Contracts\n\nFrontend and backend compatibility depends on stable response shapes and matching types. Sambee currently protects that boundary primarily with frontend service contract tests plus backend endpoint tests for the same response families.\n\n#### Current Pattern in This Repository\n\nThe current API-contract pattern is broader than a single logging endpoint.\n\n- frontend contract suites live under `frontend/src/services/__tests__/`\n- those tests typically mock the HTTP client, call the real frontend service methods, and assert endpoint paths, request parameters, response shapes, field types, enum values, blob headers, and error handling\n- representative suites include `authApi.test.ts`, `connectionApi.test.ts`, `browseApi.test.ts`, `viewerApi.test.ts`, `mobileLoggingApi.test.ts`, and `loggingConfig.test.ts`\n- backend tests validate the corresponding FastAPI surface from the server side, for example `backend/tests/test_logging_config.py`\n\nThat means an API-shape change is not just a backend refactor. It is a cross-boundary behavior change that should update backend models, backend tests, frontend types, frontend service logic, and the contract tests that bind them together.\n\n#### What the Frontend Contract Tests Actually Check\n\nThe frontend service contract tests are not only smoke tests.\n\n- authentication and admin flows check required fields and value shapes for token, user, and connection payloads\n- browse tests check nested directory listings, `FileInfo` structure, enum values, optional metadata, and path handling\n- viewer tests check binary-response behavior such as `Blob` creation, `Content-Type` handling, viewport parameters, and download semantics\n- logging-config tests check the exact backend response shape and then verify behavior derived from it, such as level-threshold evaluation and disabled-state behavior\n\nThe useful rule is: test the response contract first, then test the frontend behavior that depends on that contract.\n\n#### Logging Configuration as a Concrete Example\n\nThe logging configuration tests are a good example because they show both sides of the boundary.\n\n- backend tests assert the `/api/logs/config` response contains `logging_enabled`, `logging_level`, `tracing_enabled`, `tracing_level`, and `tracing_components`\n- frontend tests in `loggingConfig.test.ts` consume that exact shape and then verify threshold and filtering behavior that would break if the backend fields drifted\n\nThis matters because an older or copied example that still expects fields like `enabled` or `log_level` would describe the wrong contract for the current codebase.\n\n#### When to Add or Update Contract Tests\n\nAdd or expand API contract coverage when:\n\n- you add a new frontend-consumed endpoint\n- you rename, remove, or add a response field\n- you change enum values or allowed string values\n- you change binary-response behavior such as MIME handling, blob creation, or download headers\n- you add frontend logic that derives behavior from backend configuration values rather than just displaying them\n\nFor those changes, update both ends together:\n\n1. backend response model or endpoint behavior\n2. backend tests for the server response\n3. frontend types and service methods\n4. frontend contract tests for the consumed shape\n5. frontend behavior tests for the logic built on top of that shape\n\n#### Practical Contract-Testing Checklist\n\nFor a new or changed endpoint, usually verify:\n\n- required fields exist\n- field types match the frontend types\n- optional fields behave correctly when present or absent\n- known enum or string-literal values are accepted intentionally\n- request parameters and path construction still match the backend route contract\n- error responses degrade in a controlled way\n- derived frontend behavior still works once the typed response is consumed\n\n#### OpenAPI as a Future Option\n\nSambee exposes and tests the backend OpenAPI schema, including `/openapi.json`, but TypeScript type generation from that schema is not part of the checked-in frontend workflow today.\n\nIf API surface area grows enough to justify generation, OpenAPI-driven types are a reasonable future option because the backend is already able to publish the schema. Treat that as an explicit workflow addition, not as something the repository already guarantees.\n\nPossible future additions include:\n\n- generating TypeScript types from the FastAPI schema in a reviewed frontend workflow\n- adding CI checks that detect generated-type drift\n- widening contract-style coverage for endpoints that still rely mostly on broader unit tests or integration tests\n\n### Localization\n\nLocalization is treated as typed product behavior, not just string replacement. If you touch translation wiring or browser-to-companion localization sync, validate the relevant frontend and companion checks.\n\n### Logging and Diagnostics\n\nLogging changes can affect both local debugging and backend trace collection. Validate the app surfaces that consume those logging contracts.\n\n## Practical Selection Rule\n\nUse this decision order:\n\n1. Identify which subsystem changed directly.\n2. Identify which other subsystem consumes the changed contract.\n3. Run baseline checks for the changed subsystem.\n4. Add checks for every subsystem whose contract might now be wrong.\n\n## When to Go beyond the Baseline\n\nRun deeper or wider validation when:\n\n- the change affects a high-risk workflow such as file editing, locking, upload, or pairing\n- you changed dependencies or version metadata\n- you changed typed API contracts\n- the change fixes a regression that previously escaped narrower coverage\n\nThe goal is not maximum command count. The goal is to prove the changed behavior still matches Sambee's cross-app contracts.\n\n## Backend Test Structure and Fixtures\n\nBackend tests live under `backend/tests/`.\n\nCommon files include:\n\n- `conftest.py`: shared fixtures and test wiring\n- `test_auth.py`: authentication and authorization behavior\n- `test_connections.py`: SMB connection management\n- `test_browser.py`: file-browsing behavior with mocked SMB backends\n\nCommon fixtures include:\n\n- `client`\n- `session`\n- `admin_user`, `regular_user`\n- `admin_token`, `user_token`\n- `auth_headers_admin`, `auth_headers_user`\n- `test_connection`\n- `multiple_connections`\n- `mock_smb_backend`\n\nUse the shared fixtures instead of rebuilding the same setup in each test file.\n\n## Performance Notes\n\n- backend tests use `pytest-xdist` for parallel execution in the normal workflow, but `@performance` tests run separately without xdist so timing assertions stay stable\n- coverage is intentionally optional during routine local work because it is slower\n- use deeper coverage when the change touches risky backend behavior or when CI-equivalent evidence matters\n\n## Go Deeper\n\n- [Image Conversion Test Assets](../image-conversion-test-assets/): generated fixtures, real colorspace assertions, and the backend integration suite for image-conversion regressions\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared cross-boundary rules that often expand the validation surface\n- [How to Plan and Review a Change](../../contribution-workflows/how-to-plan-and-review-a-change/): decide scope before choosing checks\n- [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/): use this when version metadata or reviewed dependency inputs are part of the change\n", "0.8": "+++\ntitle = \"Test Strategy Overview\"\n+++\n\nSambee has multiple subsystems, so the right validation strategy depends on which contract you changed.\n\n## Start with the Smallest Relevant Set\n\nDo not default to either no validation or every possible check.\n\n- backend-only change with no shared contract impact: run backend tests and type checking\n- frontend-only change: run frontend tests, type check, and lint\n- companion-only change: run companion checks, the Windows GNU cross-check, and Rust tests\n- shared workflow change: run every affected subsystem's checks\n\n## Recommended Checks by Change Area\n\n| Change area | Baseline checks |\n|---|---|\n| Backend behavior | `cd backend \u0026\u0026 pytest -m 'not performance' -v`, `cd backend \u0026\u0026 pytest -m performance -v`, `cd backend \u0026\u0026 mypy app` |\n| Frontend behavior | `cd frontend \u0026\u0026 npm test`, `cd frontend \u0026\u0026 npx tsc --noEmit`, `cd frontend \u0026\u0026 npm run lint` |\n| Companion behavior | `cd companion \u0026\u0026 npx tsc --noEmit`, `cd companion \u0026\u0026 npm run lint`, `cd companion \u0026\u0026 npm run check:rust:windows`, `cd companion/src-tauri \u0026\u0026 cargo test` |\n\nFor fast local iteration, `./scripts/test` runs the main backend, frontend, and companion suites together. Its backend pass mirrors CI by running non-performance tests in parallel and `@performance` tests in a separate serial pass. The local companion pass now also includes the Windows GNU target compatibility check when the toolchain is installed. Use `COVERAGE=1 ./scripts/test` when you want the broader CI-style coverage pass.\n\n### Frontend Browser-Test Layers\n\nKeep frontend browser coverage explicit instead of folding it into the default Vitest command.\n\n- `cd frontend \u0026\u0026 npm test` runs the default Vitest suite.\n- `cd frontend \u0026\u0026 npm run test:e2e` runs the default Playwright Chromium suite.\n- `cd frontend \u0026\u0026 npm run test:e2e:all` runs all configured Playwright browser projects.\n\nInstall Playwright browsers locally with `cd frontend \u0026\u0026 npm run test:e2e:install` when a fresh environment does not have the browser binaries yet.\n\n## Cross-Boundary Changes Need Cross-Boundary Checks\n\nRun broader coverage when you change a shared contract, for example:\n\n- backend response shape that the frontend consumes\n- companion behavior that changes browser-facing pairing or editing flows\n- localization or logging behavior that spans more than one app\n\n## Contract-Sensitive Areas\n\n### API Contracts\n\nFrontend and backend compatibility depends on stable response shapes and matching types. Sambee currently protects that boundary primarily with frontend service contract tests plus backend endpoint tests for the same response families.\n\n#### Current Pattern in This Repository\n\nThe current API-contract pattern is broader than a single logging endpoint.\n\n- frontend contract suites live under `frontend/src/services/__tests__/`\n- those tests typically mock the HTTP client, call the real frontend service methods, and assert endpoint paths, request parameters, response shapes, field types, enum values, blob headers, and error handling\n- representative suites include `authApi.test.ts`, `connectionApi.test.ts`, `browseApi.test.ts`, `viewerApi.test.ts`, `mobileLoggingApi.test.ts`, and `loggingConfig.test.ts`\n- backend tests validate the corresponding FastAPI surface from the server side, for example `backend/tests/test_logging_config.py`\n\nThat means an API-shape change is not just a backend refactor. It is a cross-boundary behavior change that should update backend models, backend tests, frontend types, frontend service logic, and the contract tests that bind them together.\n\n#### What the Frontend Contract Tests Actually Check\n\nThe frontend service contract tests are not only smoke tests.\n\n- authentication and admin flows check required fields and value shapes for token, user, and connection payloads\n- browse tests check nested directory listings, `FileInfo` structure, enum values, optional metadata, and path handling\n- viewer tests check binary-response behavior such as `Blob` creation, `Content-Type` handling, viewport parameters, and download semantics\n- logging-config tests check the exact backend response shape and then verify behavior derived from it, such as level-threshold evaluation and disabled-state behavior\n\nThe useful rule is: test the response contract first, then test the frontend behavior that depends on that contract.\n\n#### Logging Configuration as a Concrete Example\n\nThe logging configuration tests are a good example because they show both sides of the boundary.\n\n- backend tests assert the `/api/logs/config` response contains `logging_enabled`, `logging_level`, `tracing_enabled`, `tracing_level`, and `tracing_components`\n- frontend tests in `loggingConfig.test.ts` consume that exact shape and then verify threshold and filtering behavior that would break if the backend fields drifted\n\nThis matters because an older or copied example that still expects fields like `enabled` or `log_level` would describe the wrong contract for the current codebase.\n\n#### When to Add or Update Contract Tests\n\nAdd or expand API contract coverage when:\n\n- you add a new frontend-consumed endpoint\n- you rename, remove, or add a response field\n- you change enum values or allowed string values\n- you change binary-response behavior such as MIME handling, blob creation, or download headers\n- you add frontend logic that derives behavior from backend configuration values rather than just displaying them\n\nFor those changes, update both ends together:\n\n1. backend response model or endpoint behavior\n2. backend tests for the server response\n3. frontend types and service methods\n4. frontend contract tests for the consumed shape\n5. frontend behavior tests for the logic built on top of that shape\n\n#### Practical Contract-Testing Checklist\n\nFor a new or changed endpoint, usually verify:\n\n- required fields exist\n- field types match the frontend types\n- optional fields behave correctly when present or absent\n- known enum or string-literal values are accepted intentionally\n- request parameters and path construction still match the backend route contract\n- error responses degrade in a controlled way\n- derived frontend behavior still works once the typed response is consumed\n\n#### OpenAPI as a Future Option\n\nSambee exposes and tests the backend OpenAPI schema, including `/openapi.json`, but TypeScript type generation from that schema is not part of the checked-in frontend workflow today.\n\nIf API surface area grows enough to justify generation, OpenAPI-driven types are a reasonable future option because the backend is already able to publish the schema. Treat that as an explicit workflow addition, not as something the repository already guarantees.\n\nPossible future additions include:\n\n- generating TypeScript types from the FastAPI schema in a reviewed frontend workflow\n- adding CI checks that detect generated-type drift\n- widening contract-style coverage for endpoints that still rely mostly on broader unit tests or integration tests\n\n### Localization\n\nLocalization is treated as typed product behavior, not just string replacement. If you touch translation wiring or browser-to-companion localization sync, validate the relevant frontend and companion checks.\n\n### Companion Cross-Target Safety\n\nCompanion contributors now have a local Linux-hosted Windows-target safety check.\n\n- `npm run check:rust:windows` runs `cargo check` for `x86_64-pc-windows-gnu`.\n- In the devcontainer, the required Rust target and MinGW toolchain are preinstalled.\n- This check is for compatibility validation, not for producing release-ready Windows binaries.\n\nKeep the distinction clear:\n\n- local cross-check: prove the Windows target still compiles far enough for contract and dependency safety\n- release build: create the signed Windows installer and updater artifacts in CI on Windows runners\n\n### Logging and Diagnostics\n\nLogging changes can affect both local debugging and backend trace collection. Validate the app surfaces that consume those logging contracts.\n\n## Practical Selection Rule\n\nUse this decision order:\n\n1. Identify which subsystem changed directly.\n2. Identify which other subsystem consumes the changed contract.\n3. Run baseline checks for the changed subsystem.\n4. Add checks for every subsystem whose contract might now be wrong.\n\n## When to Go beyond the Baseline\n\nRun deeper or wider validation when:\n\n- the change affects a high-risk workflow such as file editing, locking, upload, or pairing\n- you changed dependencies or version metadata\n- you changed typed API contracts\n- you changed browser-sensitive editor behavior such as focus handoff, contenteditable selection, keyboard navigation, or decorator-backed editing flows\n- you changed companion native dependencies, Windows-specific crates, or Tauri integration\n- the change fixes a regression that previously escaped narrower coverage\n\nThe goal is not maximum command count. The goal is to prove the changed behavior still matches Sambee's cross-app contracts.\n\n## Backend Test Structure and Fixtures\n\nBackend tests live under `backend/tests/`.\n\nCommon files include:\n\n- `conftest.py`: shared fixtures and test wiring\n- `test_auth.py`: authentication and authorization behavior\n- `test_connections.py`: SMB connection management\n- `test_browser.py`: file-browsing behavior with mocked SMB backends\n\nCommon fixtures include:\n\n- `client`\n- `session`\n- `admin_user`, `regular_user`\n- `admin_token`, `user_token`\n- `auth_headers_admin`, `auth_headers_user`\n- `test_connection`\n- `multiple_connections`\n- `mock_smb_backend`\n\nUse the shared fixtures instead of rebuilding the same setup in each test file.\n\n## Performance Notes\n\n- backend tests use `pytest-xdist` for parallel execution in the normal workflow, but `@performance` tests run separately without xdist so timing assertions stay stable\n- coverage is intentionally optional during routine local work because it is slower\n- use deeper coverage when the change touches risky backend behavior or when CI-equivalent evidence matters\n\n## Go Deeper\n\n- [Image Conversion Test Assets](../image-conversion-test-assets/): generated fixtures, real colorspace assertions, and the backend integration suite for image-conversion regressions\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared cross-boundary rules that often expand the validation surface\n- [How to Plan and Review a Change](../../contribution-workflows/how-to-plan-and-review-a-change/): decide scope before choosing checks\n- [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/): use this when version metadata or reviewed dependency inputs are part of the change\n", "0.9": "+++\ntitle = \"Test Strategy Overview\"\n+++\n\nSambee has multiple subsystems, so the right validation strategy depends on which contract you changed.\n\n## Start with the Smallest Relevant Set\n\nDo not default to either no validation or every possible check.\n\n- backend-only change with no shared contract impact: run backend tests and type checking\n- frontend-only change: run frontend tests, type check, and lint\n- companion-only change: run companion checks, the Windows GNU cross-check, and Rust tests\n- shared workflow change: run every affected subsystem's checks\n\n## Recommended Checks by Change Area\n\n| Change area | Baseline checks |\n|---|---|\n| Backend behavior | `cd backend \u0026\u0026 pytest -m 'not performance' -v`, `cd backend \u0026\u0026 pytest -m performance -v`, `cd backend \u0026\u0026 mypy app` |\n| Frontend behavior | `cd frontend \u0026\u0026 npm test`, `cd frontend \u0026\u0026 npx tsc --noEmit`, `cd frontend \u0026\u0026 npm run lint` |\n| Companion behavior | `cd companion \u0026\u0026 npx tsc --noEmit`, `cd companion \u0026\u0026 npm run lint`, `cd companion \u0026\u0026 npm run check:rust:windows`, `cd companion/src-tauri \u0026\u0026 cargo test` |\n\nFor fast local iteration, `./scripts/test` runs the main backend, frontend, and companion suites together. Its backend pass mirrors CI by running non-performance tests in parallel and `@performance` tests in a separate serial pass. The local companion pass now also includes the Windows GNU target compatibility check when the toolchain is installed. Use `COVERAGE=1 ./scripts/test` when you want the broader CI-style coverage pass.\n\n### Frontend Browser-Test Layers\n\nKeep frontend browser coverage explicit instead of folding it into the default Vitest command.\n\n- `cd frontend \u0026\u0026 npm test` runs the default Vitest suite.\n- `cd frontend \u0026\u0026 npm run test:e2e` runs the default Playwright Chromium suite.\n- `cd frontend \u0026\u0026 npm run test:e2e:all` runs all configured Playwright browser projects.\n\nInstall Playwright browsers locally with `cd frontend \u0026\u0026 npm run test:e2e:install` when a fresh environment does not have the browser binaries yet.\n\n## Cross-Boundary Changes Need Cross-Boundary Checks\n\nRun broader coverage when you change a shared contract, for example:\n\n- backend response shape that the frontend consumes\n- companion behavior that changes browser-facing pairing or editing flows\n- localization or logging behavior that spans more than one app\n\n## Contract-Sensitive Areas\n\n### API Contracts\n\nFrontend and backend compatibility depends on stable response shapes and matching types. Sambee currently protects that boundary primarily with frontend service contract tests plus backend endpoint tests for the same response families.\n\n#### Current Pattern in This Repository\n\nThe current API-contract pattern is broader than a single logging endpoint.\n\n- frontend contract suites live under `frontend/src/services/__tests__/`\n- those tests typically mock the HTTP client, call the real frontend service methods, and assert endpoint paths, request parameters, response shapes, field types, enum values, blob headers, and error handling\n- representative suites include `authApi.test.ts`, `connectionApi.test.ts`, `browseApi.test.ts`, `viewerApi.test.ts`, `mobileLoggingApi.test.ts`, and `loggingConfig.test.ts`\n- backend tests validate the corresponding FastAPI surface from the server side, for example `backend/tests/test_logging_config.py`\n\nThat means an API-shape change is not just a backend refactor. It is a cross-boundary behavior change that should update backend models, backend tests, frontend types, frontend service logic, and the contract tests that bind them together.\n\n#### What the Frontend Contract Tests Actually Check\n\nThe frontend service contract tests are not only smoke tests.\n\n- authentication and admin flows check required fields and value shapes for token, user, and connection payloads\n- browse tests check nested directory listings, `FileInfo` structure, enum values, optional metadata, and path handling\n- viewer tests check binary-response behavior such as `Blob` creation, `Content-Type` handling, viewport parameters, and download semantics\n- logging-config tests check the exact backend response shape and then verify behavior derived from it, such as level-threshold evaluation and disabled-state behavior\n\nThe useful rule is: test the response contract first, then test the frontend behavior that depends on that contract.\n\n#### Logging Configuration as a Concrete Example\n\nThe logging configuration tests are a good example because they show both sides of the boundary.\n\n- backend tests assert the `/api/logs/config` response contains `logging_enabled`, `logging_level`, `tracing_enabled`, `tracing_level`, and `tracing_components`\n- frontend tests in `loggingConfig.test.ts` consume that exact shape and then verify threshold and filtering behavior that would break if the backend fields drifted\n\nThis matters because an older or copied example that still expects fields like `enabled` or `log_level` would describe the wrong contract for the current codebase.\n\n#### When to Add or Update Contract Tests\n\nAdd or expand API contract coverage when:\n\n- you add a new frontend-consumed endpoint\n- you rename, remove, or add a response field\n- you change enum values or allowed string values\n- you change binary-response behavior such as MIME handling, blob creation, or download headers\n- you add frontend logic that derives behavior from backend configuration values rather than just displaying them\n\nFor those changes, update both ends together:\n\n1. backend response model or endpoint behavior\n2. backend tests for the server response\n3. frontend types and service methods\n4. frontend contract tests for the consumed shape\n5. frontend behavior tests for the logic built on top of that shape\n\n#### Practical Contract-Testing Checklist\n\nFor a new or changed endpoint, usually verify:\n\n- required fields exist\n- field types match the frontend types\n- optional fields behave correctly when present or absent\n- known enum or string-literal values are accepted intentionally\n- request parameters and path construction still match the backend route contract\n- error responses degrade in a controlled way\n- derived frontend behavior still works once the typed response is consumed\n\n#### OpenAPI as a Future Option\n\nSambee exposes and tests the backend OpenAPI schema, including `/openapi.json`, but TypeScript type generation from that schema is not part of the checked-in frontend workflow today.\n\nIf API surface area grows enough to justify generation, OpenAPI-driven types are a reasonable future option because the backend is already able to publish the schema. Treat that as an explicit workflow addition, not as something the repository already guarantees.\n\nPossible future additions include:\n\n- generating TypeScript types from the FastAPI schema in a reviewed frontend workflow\n- adding CI checks that detect generated-type drift\n- widening contract-style coverage for endpoints that still rely mostly on broader unit tests or integration tests\n\n### Localization\n\nLocalization is treated as typed product behavior, not just string replacement. If you touch translation wiring or browser-to-companion localization sync, validate the relevant frontend and companion checks.\n\n### Companion Cross-Target Safety\n\nCompanion contributors now have a local Linux-hosted Windows-target safety check.\n\n- `npm run check:rust:windows` runs `cargo check` for `x86_64-pc-windows-gnu`.\n- In the devcontainer, the required Rust target and MinGW toolchain are preinstalled.\n- This check is for compatibility validation, not for producing release-ready Windows binaries.\n\nKeep the distinction clear:\n\n- local cross-check: prove the Windows target still compiles far enough for contract and dependency safety\n- release build: create the signed Windows installer and updater artifacts in CI on Windows runners\n\n### Logging and Diagnostics\n\nLogging changes can affect both local debugging and backend trace collection. Validate the app surfaces that consume those logging contracts.\n\n## Practical Selection Rule\n\nUse this decision order:\n\n1. Identify which subsystem changed directly.\n2. Identify which other subsystem consumes the changed contract.\n3. Run baseline checks for the changed subsystem.\n4. Add checks for every subsystem whose contract might now be wrong.\n\n## When to Go beyond the Baseline\n\nRun deeper or wider validation when:\n\n- the change affects a high-risk workflow such as file editing, locking, upload, or pairing\n- you changed dependencies or version metadata\n- you changed typed API contracts\n- you changed browser-sensitive editor behavior such as focus handoff, contenteditable selection, keyboard navigation, or decorator-backed editing flows\n- you changed companion native dependencies, Windows-specific crates, or Tauri integration\n- the change fixes a regression that previously escaped narrower coverage\n\nThe goal is not maximum command count. The goal is to prove the changed behavior still matches Sambee's cross-app contracts.\n\n## Backend Test Structure and Fixtures\n\nBackend tests live under `backend/tests/`.\n\nCommon files include:\n\n- `conftest.py`: shared fixtures and test wiring\n- `test_auth.py`: authentication and authorization behavior\n- `test_connections.py`: SMB connection management\n- `test_browser.py`: file-browsing behavior with mocked SMB backends\n\nCommon fixtures include:\n\n- `client`\n- `session`\n- `admin_user`, `regular_user`\n- `admin_token`, `user_token`\n- `auth_headers_admin`, `auth_headers_user`\n- `test_connection`\n- `multiple_connections`\n- `mock_smb_backend`\n\nUse the shared fixtures instead of rebuilding the same setup in each test file.\n\n## Performance Notes\n\n- backend tests use `pytest-xdist` for parallel execution in the normal workflow, but `@performance` tests run separately without xdist so timing assertions stay stable\n- coverage is intentionally optional during routine local work because it is slower\n- use deeper coverage when the change touches risky backend behavior or when CI-equivalent evidence matters\n\n## Go Deeper\n\n- [Image Conversion Test Assets](../image-conversion-test-assets/): generated fixtures, real colorspace assertions, and the backend integration suite for image-conversion regressions\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared cross-boundary rules that often expand the validation surface\n- [How to Plan and Review a Change](../../contribution-workflows/how-to-plan-and-review-a-change/): decide scope before choosing checks\n- [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/): use this when version metadata or reviewed dependency inputs are part of the change\n", "1.0": "+++\ntitle = \"Test Strategy Overview\"\n+++\n\nSambee has multiple subsystems, so the right validation strategy depends on which contract you changed.\n\n## Start with the Smallest Relevant Set\n\nDo not default to either no validation or every possible check.\n\n- backend-only change with no shared contract impact: run backend tests and type checking\n- frontend-only change: run frontend tests, type check, and lint\n- companion-only change: run companion checks, the Windows GNU cross-check, and Rust tests\n- shared workflow change: run every affected subsystem's checks\n\n## Recommended Checks by Change Area\n\n| Change area | Baseline checks |\n|---|---|\n| Backend behavior | `cd backend \u0026\u0026 pytest -m 'not performance' -v`, `cd backend \u0026\u0026 pytest -m performance -v`, `cd backend \u0026\u0026 mypy app` |\n| Frontend behavior | `cd frontend \u0026\u0026 npm test`, `cd frontend \u0026\u0026 npx tsc --noEmit`, `cd frontend \u0026\u0026 npm run lint` |\n| Companion behavior | `cd companion \u0026\u0026 npx tsc --noEmit`, `cd companion \u0026\u0026 npm run lint`, `cd companion \u0026\u0026 npm run check:rust:windows`, `cd companion/src-tauri \u0026\u0026 cargo test` |\n\nFor fast local iteration, `./scripts/test` runs the main backend, frontend, and companion suites together. Its backend pass mirrors CI by running non-performance tests in parallel and `@performance` tests in a separate serial pass. The local companion pass now also includes the Windows GNU target compatibility check when the toolchain is installed. Use `COVERAGE=1 ./scripts/test` when you want the broader CI-style coverage pass.\n\n### Frontend Browser-Test Layers\n\nKeep frontend browser coverage explicit instead of folding it into the default Vitest command.\n\n- `cd frontend \u0026\u0026 npm test` runs the default Vitest suite.\n- `cd frontend \u0026\u0026 npm run test:e2e` runs the default Playwright Chromium suite.\n- `cd frontend \u0026\u0026 npm run test:e2e:all` runs all configured Playwright browser projects.\n\nInstall Playwright browsers locally with `cd frontend \u0026\u0026 npm run test:e2e:install` when a fresh environment does not have the browser binaries yet.\n\n## Cross-Boundary Changes Need Cross-Boundary Checks\n\nRun broader coverage when you change a shared contract, for example:\n\n- backend response shape that the frontend consumes\n- companion behavior that changes browser-facing pairing or editing flows\n- localization or logging behavior that spans more than one app\n\n## Contract-Sensitive Areas\n\n### API Contracts\n\nFrontend and backend compatibility depends on stable response shapes and matching types. Sambee currently protects that boundary primarily with frontend service contract tests plus backend endpoint tests for the same response families.\n\n#### Current Pattern in This Repository\n\nThe current API-contract pattern is broader than a single logging endpoint.\n\n- frontend contract suites live under `frontend/src/services/__tests__/`\n- those tests typically mock the HTTP client, call the real frontend service methods, and assert endpoint paths, request parameters, response shapes, field types, enum values, blob headers, and error handling\n- representative suites include `authApi.test.ts`, `connectionApi.test.ts`, `browseApi.test.ts`, `viewerApi.test.ts`, `mobileLoggingApi.test.ts`, and `loggingConfig.test.ts`\n- backend tests validate the corresponding FastAPI surface from the server side, for example `backend/tests/test_logging_config.py`\n\nThat means an API-shape change is not just a backend refactor. It is a cross-boundary behavior change that should update backend models, backend tests, frontend types, frontend service logic, and the contract tests that bind them together.\n\n#### What the Frontend Contract Tests Actually Check\n\nThe frontend service contract tests are not only smoke tests.\n\n- authentication and admin flows check required fields and value shapes for token, user, and connection payloads\n- browse tests check nested directory listings, `FileInfo` structure, enum values, optional metadata, and path handling\n- viewer tests check binary-response behavior such as `Blob` creation, `Content-Type` handling, viewport parameters, and download semantics\n- logging-config tests check the exact backend response shape and then verify behavior derived from it, such as level-threshold evaluation and disabled-state behavior\n\nThe useful rule is: test the response contract first, then test the frontend behavior that depends on that contract.\n\n#### Logging Configuration as a Concrete Example\n\nThe logging configuration tests are a good example because they show both sides of the boundary.\n\n- backend tests assert the `/api/logs/config` response contains `logging_enabled`, `logging_level`, `tracing_enabled`, `tracing_level`, and `tracing_components`\n- frontend tests in `loggingConfig.test.ts` consume that exact shape and then verify threshold and filtering behavior that would break if the backend fields drifted\n\nThis matters because an older or copied example that still expects fields like `enabled` or `log_level` would describe the wrong contract for the current codebase.\n\n#### When to Add or Update Contract Tests\n\nAdd or expand API contract coverage when:\n\n- you add a new frontend-consumed endpoint\n- you rename, remove, or add a response field\n- you change enum values or allowed string values\n- you change binary-response behavior such as MIME handling, blob creation, or download headers\n- you add frontend logic that derives behavior from backend configuration values rather than just displaying them\n\nFor those changes, update both ends together:\n\n1. backend response model or endpoint behavior\n2. backend tests for the server response\n3. frontend types and service methods\n4. frontend contract tests for the consumed shape\n5. frontend behavior tests for the logic built on top of that shape\n\n#### Practical Contract-Testing Checklist\n\nFor a new or changed endpoint, usually verify:\n\n- required fields exist\n- field types match the frontend types\n- optional fields behave correctly when present or absent\n- known enum or string-literal values are accepted intentionally\n- request parameters and path construction still match the backend route contract\n- error responses degrade in a controlled way\n- derived frontend behavior still works once the typed response is consumed\n\n#### OpenAPI as a Future Option\n\nSambee exposes and tests the backend OpenAPI schema, including `/openapi.json`, but TypeScript type generation from that schema is not part of the checked-in frontend workflow today.\n\nIf API surface area grows enough to justify generation, OpenAPI-driven types are a reasonable future option because the backend is already able to publish the schema. Treat that as an explicit workflow addition, not as something the repository already guarantees.\n\nPossible future additions include:\n\n- generating TypeScript types from the FastAPI schema in a reviewed frontend workflow\n- adding CI checks that detect generated-type drift\n- widening contract-style coverage for endpoints that still rely mostly on broader unit tests or integration tests\n\n### Localization\n\nLocalization is treated as typed product behavior, not just string replacement. If you touch translation wiring or browser-to-companion localization sync, validate the relevant frontend and companion checks.\n\n### Companion Cross-Target Safety\n\nCompanion contributors now have a local Linux-hosted Windows-target safety check.\n\n- `npm run check:rust:windows` runs `cargo check` for `x86_64-pc-windows-gnu`.\n- In the devcontainer, the required Rust target and MinGW toolchain are preinstalled.\n- This check is for compatibility validation, not for producing release-ready Windows binaries.\n\nKeep the distinction clear:\n\n- local cross-check: prove the Windows target still compiles far enough for contract and dependency safety\n- release build: create the signed Windows installer and updater artifacts in CI on Windows runners\n\n### Logging and Diagnostics\n\nLogging changes can affect both local debugging and backend trace collection. Validate the app surfaces that consume those logging contracts.\n\n## Practical Selection Rule\n\nUse this decision order:\n\n1. Identify which subsystem changed directly.\n2. Identify which other subsystem consumes the changed contract.\n3. Run baseline checks for the changed subsystem.\n4. Add checks for every subsystem whose contract might now be wrong.\n\n## When to Go beyond the Baseline\n\nRun deeper or wider validation when:\n\n- the change affects a high-risk workflow such as file editing, locking, upload, or pairing\n- you changed dependencies or version metadata\n- you changed typed API contracts\n- you changed browser-sensitive editor behavior such as focus handoff, contenteditable selection, keyboard navigation, or decorator-backed editing flows\n- you changed companion native dependencies, Windows-specific crates, or Tauri integration\n- the change fixes a regression that previously escaped narrower coverage\n\nThe goal is not maximum command count. The goal is to prove the changed behavior still matches Sambee's cross-app contracts.\n\n## Backend Test Structure and Fixtures\n\nBackend tests live under `backend/tests/`.\n\nCommon files include:\n\n- `conftest.py`: shared fixtures and test wiring\n- `test_auth.py`: authentication and authorization behavior\n- `test_connections.py`: SMB connection management\n- `test_browser.py`: file-browsing behavior with mocked SMB backends\n\nCommon fixtures include:\n\n- `client`\n- `session`\n- `admin_user`, `regular_user`\n- `admin_token`, `user_token`\n- `auth_headers_admin`, `auth_headers_user`\n- `test_connection`\n- `multiple_connections`\n- `mock_smb_backend`\n\nUse the shared fixtures instead of rebuilding the same setup in each test file.\n\n## Performance Notes\n\n- backend tests use `pytest-xdist` for parallel execution in the normal workflow, but `@performance` tests run separately without xdist so timing assertions stay stable\n- coverage is intentionally optional during routine local work because it is slower\n- use deeper coverage when the change touches risky backend behavior or when CI-equivalent evidence matters\n\n## Go Deeper\n\n- [Image Conversion Test Assets](../image-conversion-test-assets/): generated fixtures, real colorspace assertions, and the backend integration suite for image-conversion regressions\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared cross-boundary rules that often expand the validation surface\n- [How to Plan and Review a Change](../../contribution-workflows/how-to-plan-and-review-a-change/): decide scope before choosing checks\n- [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/): use this when version metadata or reviewed dependency inputs are part of the change\n", "2.0": "+++\ntitle = \"Test Strategy Overview\"\n+++\n\nSambee has multiple subsystems, so the right validation strategy depends on which contract you changed.\n\n## Start with the Smallest Relevant Set\n\nDo not default to either no validation or every possible check.\n\n- backend-only change with no shared contract impact: run backend tests and type checking\n- frontend-only change: run frontend tests, type check, and lint\n- companion-only change: run companion checks, the Windows GNU cross-check, and Rust tests\n- shared workflow change: run every affected subsystem's checks\n\n## Recommended Checks by Change Area\n\n| Change area | Baseline checks |\n|---|---|\n| Backend behavior | `cd backend \u0026\u0026 pytest -m 'not performance' -v`, `cd backend \u0026\u0026 pytest -m performance -v`, `cd backend \u0026\u0026 mypy app` |\n| Frontend behavior | `cd frontend \u0026\u0026 npm test`, `cd frontend \u0026\u0026 npx tsc --noEmit`, `cd frontend \u0026\u0026 npm run lint` |\n| Companion behavior | `cd companion \u0026\u0026 npx tsc --noEmit`, `cd companion \u0026\u0026 npm run lint`, `cd companion \u0026\u0026 npm run check:rust:windows`, `cd companion/src-tauri \u0026\u0026 cargo test` |\n\nFor fast local iteration, `./scripts/test` runs the main backend, frontend, and companion suites together. Its backend pass mirrors CI by running non-performance tests in parallel and `@performance` tests in a separate serial pass. The local companion pass now also includes the Windows GNU target compatibility check when the toolchain is installed. Use `COVERAGE=1 ./scripts/test` when you want the broader CI-style coverage pass.\n\n### Frontend Browser-Test Layers\n\nKeep frontend browser coverage explicit instead of folding it into the default Vitest command.\n\n- `cd frontend \u0026\u0026 npm test` runs the default Vitest suite.\n- `cd frontend \u0026\u0026 npm run test:e2e` runs the default Playwright Chromium suite.\n- `cd frontend \u0026\u0026 npm run test:e2e:all` runs all configured Playwright browser projects.\n\nInstall Playwright browsers locally with `cd frontend \u0026\u0026 npm run test:e2e:install` when a fresh environment does not have the browser binaries yet.\n\n## Cross-Boundary Changes Need Cross-Boundary Checks\n\nRun broader coverage when you change a shared contract, for example:\n\n- backend response shape that the frontend consumes\n- companion behavior that changes browser-facing pairing or editing flows\n- localization or logging behavior that spans more than one app\n\n## Contract-Sensitive Areas\n\n### API Contracts\n\nFrontend and backend compatibility depends on stable response shapes and matching types. Sambee currently protects that boundary primarily with frontend service contract tests plus backend endpoint tests for the same response families.\n\n#### Current Pattern in This Repository\n\nThe current API-contract pattern is broader than a single logging endpoint.\n\n- frontend contract suites live under `frontend/src/services/__tests__/`\n- those tests typically mock the HTTP client, call the real frontend service methods, and assert endpoint paths, request parameters, response shapes, field types, enum values, blob headers, and error handling\n- representative suites include `authApi.test.ts`, `connectionApi.test.ts`, `browseApi.test.ts`, `viewerApi.test.ts`, `mobileLoggingApi.test.ts`, and `loggingConfig.test.ts`\n- backend tests validate the corresponding FastAPI surface from the server side, for example `backend/tests/test_logging_config.py`\n\nThat means an API-shape change is not just a backend refactor. It is a cross-boundary behavior change that should update backend models, backend tests, frontend types, frontend service logic, and the contract tests that bind them together.\n\n#### What the Frontend Contract Tests Actually Check\n\nThe frontend service contract tests are not only smoke tests.\n\n- authentication and admin flows check required fields and value shapes for token, user, and connection payloads\n- browse tests check nested directory listings, `FileInfo` structure, enum values, optional metadata, and path handling\n- viewer tests check binary-response behavior such as `Blob` creation, `Content-Type` handling, viewport parameters, and download semantics\n- logging-config tests check the exact backend response shape and then verify behavior derived from it, such as level-threshold evaluation and disabled-state behavior\n\nThe useful rule is: test the response contract first, then test the frontend behavior that depends on that contract.\n\n#### Logging Configuration as a Concrete Example\n\nThe logging configuration tests are a good example because they show both sides of the boundary.\n\n- backend tests assert the `/api/logs/config` response contains `logging_enabled`, `logging_level`, `tracing_enabled`, `tracing_level`, and `tracing_components`\n- frontend tests in `loggingConfig.test.ts` consume that exact shape and then verify threshold and filtering behavior that would break if the backend fields drifted\n\nThis matters because an older or copied example that still expects fields like `enabled` or `log_level` would describe the wrong contract for the current codebase.\n\n#### When to Add or Update Contract Tests\n\nAdd or expand API contract coverage when:\n\n- you add a new frontend-consumed endpoint\n- you rename, remove, or add a response field\n- you change enum values or allowed string values\n- you change binary-response behavior such as MIME handling, blob creation, or download headers\n- you add frontend logic that derives behavior from backend configuration values rather than just displaying them\n\nFor those changes, update both ends together:\n\n1. backend response model or endpoint behavior\n2. backend tests for the server response\n3. frontend types and service methods\n4. frontend contract tests for the consumed shape\n5. frontend behavior tests for the logic built on top of that shape\n\n#### Practical Contract-Testing Checklist\n\nFor a new or changed endpoint, usually verify:\n\n- required fields exist\n- field types match the frontend types\n- optional fields behave correctly when present or absent\n- known enum or string-literal values are accepted intentionally\n- request parameters and path construction still match the backend route contract\n- error responses degrade in a controlled way\n- derived frontend behavior still works once the typed response is consumed\n\n#### OpenAPI as a Future Option\n\nSambee exposes and tests the backend OpenAPI schema, including `/openapi.json`, but TypeScript type generation from that schema is not part of the checked-in frontend workflow today.\n\nIf API surface area grows enough to justify generation, OpenAPI-driven types are a reasonable future option because the backend is already able to publish the schema. Treat that as an explicit workflow addition, not as something the repository already guarantees.\n\nPossible future additions include:\n\n- generating TypeScript types from the FastAPI schema in a reviewed frontend workflow\n- adding CI checks that detect generated-type drift\n- widening contract-style coverage for endpoints that still rely mostly on broader unit tests or integration tests\n\n### Localization\n\nLocalization is treated as typed product behavior, not just string replacement. If you touch translation wiring or browser-to-companion localization sync, validate the relevant frontend and companion checks.\n\n### Companion Cross-Target Safety\n\nCompanion contributors now have a local Linux-hosted Windows-target safety check.\n\n- `npm run check:rust:windows` runs `cargo check` for `x86_64-pc-windows-gnu`.\n- In the devcontainer, the required Rust target and MinGW toolchain are preinstalled.\n- This check is for compatibility validation, not for producing release-ready Windows binaries.\n\nKeep the distinction clear:\n\n- local cross-check: prove the Windows target still compiles far enough for contract and dependency safety\n- release build: create the signed Windows installer and updater artifacts in CI on Windows runners\n\n### Logging and Diagnostics\n\nLogging changes can affect both local debugging and backend trace collection. Validate the app surfaces that consume those logging contracts.\n\n## Practical Selection Rule\n\nUse this decision order:\n\n1. Identify which subsystem changed directly.\n2. Identify which other subsystem consumes the changed contract.\n3. Run baseline checks for the changed subsystem.\n4. Add checks for every subsystem whose contract might now be wrong.\n\n## When to Go beyond the Baseline\n\nRun deeper or wider validation when:\n\n- the change affects a high-risk workflow such as file editing, locking, upload, or pairing\n- you changed dependencies or version metadata\n- you changed typed API contracts\n- you changed browser-sensitive editor behavior such as focus handoff, contenteditable selection, keyboard navigation, or decorator-backed editing flows\n- you changed companion native dependencies, Windows-specific crates, or Tauri integration\n- the change fixes a regression that previously escaped narrower coverage\n\nThe goal is not maximum command count. The goal is to prove the changed behavior still matches Sambee's cross-app contracts.\n\n## Backend Test Structure and Fixtures\n\nBackend tests live under `backend/tests/`.\n\nCommon files include:\n\n- `conftest.py`: shared fixtures and test wiring\n- `test_auth.py`: authentication and authorization behavior\n- `test_connections.py`: SMB connection management\n- `test_browser.py`: file-browsing behavior with mocked SMB backends\n\nCommon fixtures include:\n\n- `client`\n- `session`\n- `admin_user`, `regular_user`\n- `admin_token`, `user_token`\n- `auth_headers_admin`, `auth_headers_user`\n- `test_connection`\n- `multiple_connections`\n- `mock_smb_backend`\n\nUse the shared fixtures instead of rebuilding the same setup in each test file.\n\n## Performance Notes\n\n- backend tests use `pytest-xdist` for parallel execution in the normal workflow, but `@performance` tests run separately without xdist so timing assertions stay stable\n- coverage is intentionally optional during routine local work because it is slower\n- use deeper coverage when the change touches risky backend behavior or when CI-equivalent evidence matters\n\n## Go Deeper\n\n- [Image Conversion Test Assets](../image-conversion-test-assets/): generated fixtures, real colorspace assertions, and the backend integration suite for image-conversion regressions\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared cross-boundary rules that often expand the validation surface\n- [How to Plan and Review a Change](../../contribution-workflows/how-to-plan-and-review-a-change/): decide scope before choosing checks\n- [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/): use this when version metadata or reviewed dependency inputs are part of the change\n"}, "page_contents": {"0.7": "+++\ntitle = \"Test Strategy Overview\"\n+++\n\nSambee has multiple subsystems, so the right validation strategy depends on which contract you changed.\n\n## Start with the Smallest Relevant Set\n\nDo not default to either no validation or every possible check.\n\n- backend-only change with no shared contract impact: run backend tests and type checking\n- frontend-only change: run frontend tests, type check, and lint\n- companion-only change: run companion checks and Rust tests\n- shared workflow change: run every affected subsystem's checks\n\n## Recommended Checks by Change Area\n\n| Change area | Baseline checks |\n|---|---|\n| Backend behavior | `cd backend \u0026\u0026 pytest -m 'not performance' -v`, `cd backend \u0026\u0026 pytest -m performance -v`, `cd backend \u0026\u0026 mypy app` |\n| Frontend behavior | `cd frontend \u0026\u0026 npm test`, `cd frontend \u0026\u0026 npx tsc --noEmit`, `cd frontend \u0026\u0026 npm run lint` |\n| Companion behavior | `cd companion \u0026\u0026 npx tsc --noEmit`, `cd companion \u0026\u0026 npm run lint`, `cd companion/src-tauri \u0026\u0026 cargo test` |\n\nFor fast local iteration, `./scripts/test` runs the main backend, frontend, companion, and archive-topology suites together. It stops at the first failed check so you can fix that subsystem before spending time on later suites. The order is backend type checking and tests, frontend type checking, linting, and tests, companion checks and tests, then archive-specific topology verification. Its backend pass mirrors CI by running non-performance tests in parallel and `@performance` tests in a separate serial pass. Use `COVERAGE=1 ./scripts/test` when you want the broader CI-style coverage pass.\n\n## Cross-Boundary Changes Need Cross-Boundary Checks\n\nRun broader coverage when you change a shared contract, for example:\n\n- backend response shape that the frontend consumes\n- companion behavior that changes browser-facing pairing or editing flows\n- localization or logging behavior that spans more than one app\n\n## Contract-Sensitive Areas\n\n### API Contracts\n\nFrontend and backend compatibility depends on stable response shapes and matching types. Sambee currently protects that boundary primarily with frontend service contract tests plus backend endpoint tests for the same response families.\n\n#### Current Pattern in This Repository\n\nThe current API-contract pattern is broader than a single logging endpoint.\n\n- frontend contract suites live under `frontend/src/services/__tests__/`\n- those tests typically mock the HTTP client, call the real frontend service methods, and assert endpoint paths, request parameters, response shapes, field types, enum values, blob headers, and error handling\n- representative suites include `authApi.test.ts`, `connectionApi.test.ts`, `browseApi.test.ts`, `viewerApi.test.ts`, `mobileLoggingApi.test.ts`, and `loggingConfig.test.ts`\n- backend tests validate the corresponding FastAPI surface from the server side, for example `backend/tests/test_logging_config.py`\n\nThat means an API-shape change is not just a backend refactor. It is a cross-boundary behavior change that should update backend models, backend tests, frontend types, frontend service logic, and the contract tests that bind them together.\n\n#### What the Frontend Contract Tests Actually Check\n\nThe frontend service contract tests are not only smoke tests.\n\n- authentication and admin flows check required fields and value shapes for token, user, and connection payloads\n- browse tests check nested directory listings, `FileInfo` structure, enum values, optional metadata, and path handling\n- viewer tests check binary-response behavior such as `Blob` creation, `Content-Type` handling, viewport parameters, and download semantics\n- logging-config tests check the exact backend response shape and then verify behavior derived from it, such as level-threshold evaluation and disabled-state behavior\n\nThe useful rule is: test the response contract first, then test the frontend behavior that depends on that contract.\n\n#### Logging Configuration as a Concrete Example\n\nThe logging configuration tests are a good example because they show both sides of the boundary.\n\n- backend tests assert the `/api/logs/config` response contains `logging_enabled`, `logging_level`, `tracing_enabled`, `tracing_level`, and `tracing_components`\n- frontend tests in `loggingConfig.test.ts` consume that exact shape and then verify threshold and filtering behavior that would break if the backend fields drifted\n\nThis matters because an older or copied example that still expects fields like `enabled` or `log_level` would describe the wrong contract for the current codebase.\n\n#### When to Add or Update Contract Tests\n\nAdd or expand API contract coverage when:\n\n- you add a new frontend-consumed endpoint\n- you rename, remove, or add a response field\n- you change enum values or allowed string values\n- you change binary-response behavior such as MIME handling, blob creation, or download headers\n- you add frontend logic that derives behavior from backend configuration values rather than just displaying them\n\nFor those changes, update both ends together:\n\n1. backend response model or endpoint behavior\n2. backend tests for the server response\n3. frontend types and service methods\n4. frontend contract tests for the consumed shape\n5. frontend behavior tests for the logic built on top of that shape\n\n#### Practical Contract-Testing Checklist\n\nFor a new or changed endpoint, usually verify:\n\n- required fields exist\n- field types match the frontend types\n- optional fields behave correctly when present or absent\n- known enum or string-literal values are accepted intentionally\n- request parameters and path construction still match the backend route contract\n- error responses degrade in a controlled way\n- derived frontend behavior still works once the typed response is consumed\n\n#### OpenAPI as a Future Option\n\nSambee exposes and tests the backend OpenAPI schema, including `/openapi.json`, but TypeScript type generation from that schema is not part of the checked-in frontend workflow today.\n\nIf API surface area grows enough to justify generation, OpenAPI-driven types are a reasonable future option because the backend is already able to publish the schema. Treat that as an explicit workflow addition, not as something the repository already guarantees.\n\nPossible future additions include:\n\n- generating TypeScript types from the FastAPI schema in a reviewed frontend workflow\n- adding CI checks that detect generated-type drift\n- widening contract-style coverage for endpoints that still rely mostly on broader unit tests or integration tests\n\n### Localization\n\nLocalization is treated as typed product behavior, not just string replacement. If you touch translation wiring or browser-to-companion localization sync, validate the relevant frontend and companion checks.\n\n### Logging and Diagnostics\n\nLogging changes can affect both local debugging and backend trace collection. Validate the app surfaces that consume those logging contracts.\n\n## Practical Selection Rule\n\nUse this decision order:\n\n1. Identify which subsystem changed directly.\n2. Identify which other subsystem consumes the changed contract.\n3. Run baseline checks for the changed subsystem.\n4. Add checks for every subsystem whose contract might now be wrong.\n\n## When to Go beyond the Baseline\n\nRun deeper or wider validation when:\n\n- the change affects a high-risk workflow such as file editing, locking, upload, or pairing\n- you changed dependencies or version metadata\n- you changed typed API contracts\n- the change fixes a regression that previously escaped narrower coverage\n\nThe goal is not maximum command count. The goal is to prove the changed behavior still matches Sambee's cross-app contracts.\n\n## Backend Test Structure and Fixtures\n\nBackend tests live under `backend/tests/`.\n\nCommon files include:\n\n- `conftest.py`: shared fixtures and test wiring\n- `test_auth.py`: authentication and authorization behavior\n- `test_connections.py`: SMB connection management\n- `test_browser.py`: file-browsing behavior with mocked SMB backends\n\nCommon fixtures include:\n\n- `client`\n- `session`\n- `admin_user`, `regular_user`\n- `admin_token`, `user_token`\n- `auth_headers_admin`, `auth_headers_user`\n- `test_connection`\n- `multiple_connections`\n- `mock_smb_backend`\n\nUse the shared fixtures instead of rebuilding the same setup in each test file.\n\n## Performance Notes\n\n- backend tests use `pytest-xdist` for parallel execution in the normal workflow, but `@performance` tests run separately without xdist so timing assertions stay stable\n- coverage is intentionally optional during routine local work because it is slower\n- use deeper coverage when the change touches risky backend behavior or when CI-equivalent evidence matters\n\n## Go Deeper\n\n- [Image Conversion Test Assets](../image-conversion-test-assets/): generated fixtures, real colorspace assertions, and the backend integration suite for image-conversion regressions\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared cross-boundary rules that often expand the validation surface\n- [How to Plan and Review a Change](../../contribution-workflows/how-to-plan-and-review-a-change/): decide scope before choosing checks\n- [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/): use this when version metadata or reviewed dependency inputs are part of the change\n", "0.8": "+++\ntitle = \"Test Strategy Overview\"\n+++\n\nSambee has multiple subsystems, so the right validation strategy depends on which contract you changed.\n\n## Start with the Smallest Relevant Set\n\nDo not default to either no validation or every possible check.\n\n- backend-only change with no shared contract impact: run backend tests and type checking\n- frontend-only change: run frontend tests, type check, and lint\n- companion-only change: run companion checks, the Windows GNU cross-check, and Rust tests\n- shared workflow change: run every affected subsystem's checks\n\n## Recommended Checks by Change Area\n\n| Change area | Baseline checks |\n|---|---|\n| Backend behavior | `cd backend \u0026\u0026 pytest -m 'not performance' -v`, `cd backend \u0026\u0026 pytest -m performance -v`, `cd backend \u0026\u0026 mypy app` |\n| Frontend behavior | `cd frontend \u0026\u0026 npm test`, `cd frontend \u0026\u0026 npx tsc --noEmit`, `cd frontend \u0026\u0026 npm run lint` |\n| Companion behavior | `cd companion \u0026\u0026 npx tsc --noEmit`, `cd companion \u0026\u0026 npm run lint`, `cd companion \u0026\u0026 npm run check:rust:windows`, `cd companion/src-tauri \u0026\u0026 cargo test` |\n\nFor fast local iteration, `./scripts/test` runs the main backend, frontend, and companion suites together. Its backend pass mirrors CI by running non-performance tests in parallel and `@performance` tests in a separate serial pass. The local companion pass now also includes the Windows GNU target compatibility check when the toolchain is installed. Use `COVERAGE=1 ./scripts/test` when you want the broader CI-style coverage pass.\n\n### Frontend Browser-Test Layers\n\nKeep frontend browser coverage explicit instead of folding it into the default Vitest command.\n\n- `cd frontend \u0026\u0026 npm test` runs the default Vitest suite.\n- `cd frontend \u0026\u0026 npm run test:e2e` runs the default Playwright Chromium suite.\n- `cd frontend \u0026\u0026 npm run test:e2e:all` runs all configured Playwright browser projects.\n\nInstall Playwright browsers locally with `cd frontend \u0026\u0026 npm run test:e2e:install` when a fresh environment does not have the browser binaries yet.\n\n## Cross-Boundary Changes Need Cross-Boundary Checks\n\nRun broader coverage when you change a shared contract, for example:\n\n- backend response shape that the frontend consumes\n- companion behavior that changes browser-facing pairing or editing flows\n- localization or logging behavior that spans more than one app\n\n## Contract-Sensitive Areas\n\n### API Contracts\n\nFrontend and backend compatibility depends on stable response shapes and matching types. Sambee currently protects that boundary primarily with frontend service contract tests plus backend endpoint tests for the same response families.\n\n#### Current Pattern in This Repository\n\nThe current API-contract pattern is broader than a single logging endpoint.\n\n- frontend contract suites live under `frontend/src/services/__tests__/`\n- those tests typically mock the HTTP client, call the real frontend service methods, and assert endpoint paths, request parameters, response shapes, field types, enum values, blob headers, and error handling\n- representative suites include `authApi.test.ts`, `connectionApi.test.ts`, `browseApi.test.ts`, `viewerApi.test.ts`, `mobileLoggingApi.test.ts`, and `loggingConfig.test.ts`\n- backend tests validate the corresponding FastAPI surface from the server side, for example `backend/tests/test_logging_config.py`\n\nThat means an API-shape change is not just a backend refactor. It is a cross-boundary behavior change that should update backend models, backend tests, frontend types, frontend service logic, and the contract tests that bind them together.\n\n#### What the Frontend Contract Tests Actually Check\n\nThe frontend service contract tests are not only smoke tests.\n\n- authentication and admin flows check required fields and value shapes for token, user, and connection payloads\n- browse tests check nested directory listings, `FileInfo` structure, enum values, optional metadata, and path handling\n- viewer tests check binary-response behavior such as `Blob` creation, `Content-Type` handling, viewport parameters, and download semantics\n- logging-config tests check the exact backend response shape and then verify behavior derived from it, such as level-threshold evaluation and disabled-state behavior\n\nThe useful rule is: test the response contract first, then test the frontend behavior that depends on that contract.\n\n#### Logging Configuration as a Concrete Example\n\nThe logging configuration tests are a good example because they show both sides of the boundary.\n\n- backend tests assert the `/api/logs/config` response contains `logging_enabled`, `logging_level`, `tracing_enabled`, `tracing_level`, and `tracing_components`\n- frontend tests in `loggingConfig.test.ts` consume that exact shape and then verify threshold and filtering behavior that would break if the backend fields drifted\n\nThis matters because an older or copied example that still expects fields like `enabled` or `log_level` would describe the wrong contract for the current codebase.\n\n#### When to Add or Update Contract Tests\n\nAdd or expand API contract coverage when:\n\n- you add a new frontend-consumed endpoint\n- you rename, remove, or add a response field\n- you change enum values or allowed string values\n- you change binary-response behavior such as MIME handling, blob creation, or download headers\n- you add frontend logic that derives behavior from backend configuration values rather than just displaying them\n\nFor those changes, update both ends together:\n\n1. backend response model or endpoint behavior\n2. backend tests for the server response\n3. frontend types and service methods\n4. frontend contract tests for the consumed shape\n5. frontend behavior tests for the logic built on top of that shape\n\n#### Practical Contract-Testing Checklist\n\nFor a new or changed endpoint, usually verify:\n\n- required fields exist\n- field types match the frontend types\n- optional fields behave correctly when present or absent\n- known enum or string-literal values are accepted intentionally\n- request parameters and path construction still match the backend route contract\n- error responses degrade in a controlled way\n- derived frontend behavior still works once the typed response is consumed\n\n#### OpenAPI as a Future Option\n\nSambee exposes and tests the backend OpenAPI schema, including `/openapi.json`, but TypeScript type generation from that schema is not part of the checked-in frontend workflow today.\n\nIf API surface area grows enough to justify generation, OpenAPI-driven types are a reasonable future option because the backend is already able to publish the schema. Treat that as an explicit workflow addition, not as something the repository already guarantees.\n\nPossible future additions include:\n\n- generating TypeScript types from the FastAPI schema in a reviewed frontend workflow\n- adding CI checks that detect generated-type drift\n- widening contract-style coverage for endpoints that still rely mostly on broader unit tests or integration tests\n\n### Localization\n\nLocalization is treated as typed product behavior, not just string replacement. If you touch translation wiring or browser-to-companion localization sync, validate the relevant frontend and companion checks.\n\n### Companion Cross-Target Safety\n\nCompanion contributors now have a local Linux-hosted Windows-target safety check.\n\n- `npm run check:rust:windows` runs `cargo check` for `x86_64-pc-windows-gnu`.\n- In the devcontainer, the required Rust target and MinGW toolchain are preinstalled.\n- This check is for compatibility validation, not for producing release-ready Windows binaries.\n\nKeep the distinction clear:\n\n- local cross-check: prove the Windows target still compiles far enough for contract and dependency safety\n- release build: create the signed Windows installer and updater artifacts in CI on Windows runners\n\n### Logging and Diagnostics\n\nLogging changes can affect both local debugging and backend trace collection. Validate the app surfaces that consume those logging contracts.\n\n## Practical Selection Rule\n\nUse this decision order:\n\n1. Identify which subsystem changed directly.\n2. Identify which other subsystem consumes the changed contract.\n3. Run baseline checks for the changed subsystem.\n4. Add checks for every subsystem whose contract might now be wrong.\n\n## When to Go beyond the Baseline\n\nRun deeper or wider validation when:\n\n- the change affects a high-risk workflow such as file editing, locking, upload, or pairing\n- you changed dependencies or version metadata\n- you changed typed API contracts\n- you changed browser-sensitive editor behavior such as focus handoff, contenteditable selection, keyboard navigation, or decorator-backed editing flows\n- you changed companion native dependencies, Windows-specific crates, or Tauri integration\n- the change fixes a regression that previously escaped narrower coverage\n\nThe goal is not maximum command count. The goal is to prove the changed behavior still matches Sambee's cross-app contracts.\n\n## Backend Test Structure and Fixtures\n\nBackend tests live under `backend/tests/`.\n\nCommon files include:\n\n- `conftest.py`: shared fixtures and test wiring\n- `test_auth.py`: authentication and authorization behavior\n- `test_connections.py`: SMB connection management\n- `test_browser.py`: file-browsing behavior with mocked SMB backends\n\nCommon fixtures include:\n\n- `client`\n- `session`\n- `admin_user`, `regular_user`\n- `admin_token`, `user_token`\n- `auth_headers_admin`, `auth_headers_user`\n- `test_connection`\n- `multiple_connections`\n- `mock_smb_backend`\n\nUse the shared fixtures instead of rebuilding the same setup in each test file.\n\n## Performance Notes\n\n- backend tests use `pytest-xdist` for parallel execution in the normal workflow, but `@performance` tests run separately without xdist so timing assertions stay stable\n- coverage is intentionally optional during routine local work because it is slower\n- use deeper coverage when the change touches risky backend behavior or when CI-equivalent evidence matters\n\n## Go Deeper\n\n- [Image Conversion Test Assets](../image-conversion-test-assets/): generated fixtures, real colorspace assertions, and the backend integration suite for image-conversion regressions\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared cross-boundary rules that often expand the validation surface\n- [How to Plan and Review a Change](../../contribution-workflows/how-to-plan-and-review-a-change/): decide scope before choosing checks\n- [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/): use this when version metadata or reviewed dependency inputs are part of the change\n", "0.9": "+++\ntitle = \"Test Strategy Overview\"\n+++\n\nSambee has multiple subsystems, so the right validation strategy depends on which contract you changed.\n\n## Start with the Smallest Relevant Set\n\nDo not default to either no validation or every possible check.\n\n- backend-only change with no shared contract impact: run backend tests and type checking\n- frontend-only change: run frontend tests, type check, and lint\n- companion-only change: run companion checks, the Windows GNU cross-check, and Rust tests\n- shared workflow change: run every affected subsystem's checks\n\n## Recommended Checks by Change Area\n\n| Change area | Baseline checks |\n|---|---|\n| Backend behavior | `cd backend \u0026\u0026 pytest -m 'not performance' -v`, `cd backend \u0026\u0026 pytest -m performance -v`, `cd backend \u0026\u0026 mypy app` |\n| Frontend behavior | `cd frontend \u0026\u0026 npm test`, `cd frontend \u0026\u0026 npx tsc --noEmit`, `cd frontend \u0026\u0026 npm run lint` |\n| Companion behavior | `cd companion \u0026\u0026 npx tsc --noEmit`, `cd companion \u0026\u0026 npm run lint`, `cd companion \u0026\u0026 npm run check:rust:windows`, `cd companion/src-tauri \u0026\u0026 cargo test` |\n\nFor fast local iteration, `./scripts/test` runs the main backend, frontend, and companion suites together. Its backend pass mirrors CI by running non-performance tests in parallel and `@performance` tests in a separate serial pass. The local companion pass now also includes the Windows GNU target compatibility check when the toolchain is installed. Use `COVERAGE=1 ./scripts/test` when you want the broader CI-style coverage pass.\n\n### Frontend Browser-Test Layers\n\nKeep frontend browser coverage explicit instead of folding it into the default Vitest command.\n\n- `cd frontend \u0026\u0026 npm test` runs the default Vitest suite.\n- `cd frontend \u0026\u0026 npm run test:e2e` runs the default Playwright Chromium suite.\n- `cd frontend \u0026\u0026 npm run test:e2e:all` runs all configured Playwright browser projects.\n\nInstall Playwright browsers locally with `cd frontend \u0026\u0026 npm run test:e2e:install` when a fresh environment does not have the browser binaries yet.\n\n## Cross-Boundary Changes Need Cross-Boundary Checks\n\nRun broader coverage when you change a shared contract, for example:\n\n- backend response shape that the frontend consumes\n- companion behavior that changes browser-facing pairing or editing flows\n- localization or logging behavior that spans more than one app\n\n## Contract-Sensitive Areas\n\n### API Contracts\n\nFrontend and backend compatibility depends on stable response shapes and matching types. Sambee currently protects that boundary primarily with frontend service contract tests plus backend endpoint tests for the same response families.\n\n#### Current Pattern in This Repository\n\nThe current API-contract pattern is broader than a single logging endpoint.\n\n- frontend contract suites live under `frontend/src/services/__tests__/`\n- those tests typically mock the HTTP client, call the real frontend service methods, and assert endpoint paths, request parameters, response shapes, field types, enum values, blob headers, and error handling\n- representative suites include `authApi.test.ts`, `connectionApi.test.ts`, `browseApi.test.ts`, `viewerApi.test.ts`, `mobileLoggingApi.test.ts`, and `loggingConfig.test.ts`\n- backend tests validate the corresponding FastAPI surface from the server side, for example `backend/tests/test_logging_config.py`\n\nThat means an API-shape change is not just a backend refactor. It is a cross-boundary behavior change that should update backend models, backend tests, frontend types, frontend service logic, and the contract tests that bind them together.\n\n#### What the Frontend Contract Tests Actually Check\n\nThe frontend service contract tests are not only smoke tests.\n\n- authentication and admin flows check required fields and value shapes for token, user, and connection payloads\n- browse tests check nested directory listings, `FileInfo` structure, enum values, optional metadata, and path handling\n- viewer tests check binary-response behavior such as `Blob` creation, `Content-Type` handling, viewport parameters, and download semantics\n- logging-config tests check the exact backend response shape and then verify behavior derived from it, such as level-threshold evaluation and disabled-state behavior\n\nThe useful rule is: test the response contract first, then test the frontend behavior that depends on that contract.\n\n#### Logging Configuration as a Concrete Example\n\nThe logging configuration tests are a good example because they show both sides of the boundary.\n\n- backend tests assert the `/api/logs/config` response contains `logging_enabled`, `logging_level`, `tracing_enabled`, `tracing_level`, and `tracing_components`\n- frontend tests in `loggingConfig.test.ts` consume that exact shape and then verify threshold and filtering behavior that would break if the backend fields drifted\n\nThis matters because an older or copied example that still expects fields like `enabled` or `log_level` would describe the wrong contract for the current codebase.\n\n#### When to Add or Update Contract Tests\n\nAdd or expand API contract coverage when:\n\n- you add a new frontend-consumed endpoint\n- you rename, remove, or add a response field\n- you change enum values or allowed string values\n- you change binary-response behavior such as MIME handling, blob creation, or download headers\n- you add frontend logic that derives behavior from backend configuration values rather than just displaying them\n\nFor those changes, update both ends together:\n\n1. backend response model or endpoint behavior\n2. backend tests for the server response\n3. frontend types and service methods\n4. frontend contract tests for the consumed shape\n5. frontend behavior tests for the logic built on top of that shape\n\n#### Practical Contract-Testing Checklist\n\nFor a new or changed endpoint, usually verify:\n\n- required fields exist\n- field types match the frontend types\n- optional fields behave correctly when present or absent\n- known enum or string-literal values are accepted intentionally\n- request parameters and path construction still match the backend route contract\n- error responses degrade in a controlled way\n- derived frontend behavior still works once the typed response is consumed\n\n#### OpenAPI as a Future Option\n\nSambee exposes and tests the backend OpenAPI schema, including `/openapi.json`, but TypeScript type generation from that schema is not part of the checked-in frontend workflow today.\n\nIf API surface area grows enough to justify generation, OpenAPI-driven types are a reasonable future option because the backend is already able to publish the schema. Treat that as an explicit workflow addition, not as something the repository already guarantees.\n\nPossible future additions include:\n\n- generating TypeScript types from the FastAPI schema in a reviewed frontend workflow\n- adding CI checks that detect generated-type drift\n- widening contract-style coverage for endpoints that still rely mostly on broader unit tests or integration tests\n\n### Localization\n\nLocalization is treated as typed product behavior, not just string replacement. If you touch translation wiring or browser-to-companion localization sync, validate the relevant frontend and companion checks.\n\n### Companion Cross-Target Safety\n\nCompanion contributors now have a local Linux-hosted Windows-target safety check.\n\n- `npm run check:rust:windows` runs `cargo check` for `x86_64-pc-windows-gnu`.\n- In the devcontainer, the required Rust target and MinGW toolchain are preinstalled.\n- This check is for compatibility validation, not for producing release-ready Windows binaries.\n\nKeep the distinction clear:\n\n- local cross-check: prove the Windows target still compiles far enough for contract and dependency safety\n- release build: create the signed Windows installer and updater artifacts in CI on Windows runners\n\n### Logging and Diagnostics\n\nLogging changes can affect both local debugging and backend trace collection. Validate the app surfaces that consume those logging contracts.\n\n## Practical Selection Rule\n\nUse this decision order:\n\n1. Identify which subsystem changed directly.\n2. Identify which other subsystem consumes the changed contract.\n3. Run baseline checks for the changed subsystem.\n4. Add checks for every subsystem whose contract might now be wrong.\n\n## When to Go beyond the Baseline\n\nRun deeper or wider validation when:\n\n- the change affects a high-risk workflow such as file editing, locking, upload, or pairing\n- you changed dependencies or version metadata\n- you changed typed API contracts\n- you changed browser-sensitive editor behavior such as focus handoff, contenteditable selection, keyboard navigation, or decorator-backed editing flows\n- you changed companion native dependencies, Windows-specific crates, or Tauri integration\n- the change fixes a regression that previously escaped narrower coverage\n\nThe goal is not maximum command count. The goal is to prove the changed behavior still matches Sambee's cross-app contracts.\n\n## Backend Test Structure and Fixtures\n\nBackend tests live under `backend/tests/`.\n\nCommon files include:\n\n- `conftest.py`: shared fixtures and test wiring\n- `test_auth.py`: authentication and authorization behavior\n- `test_connections.py`: SMB connection management\n- `test_browser.py`: file-browsing behavior with mocked SMB backends\n\nCommon fixtures include:\n\n- `client`\n- `session`\n- `admin_user`, `regular_user`\n- `admin_token`, `user_token`\n- `auth_headers_admin`, `auth_headers_user`\n- `test_connection`\n- `multiple_connections`\n- `mock_smb_backend`\n\nUse the shared fixtures instead of rebuilding the same setup in each test file.\n\n## Performance Notes\n\n- backend tests use `pytest-xdist` for parallel execution in the normal workflow, but `@performance` tests run separately without xdist so timing assertions stay stable\n- coverage is intentionally optional during routine local work because it is slower\n- use deeper coverage when the change touches risky backend behavior or when CI-equivalent evidence matters\n\n## Go Deeper\n\n- [Image Conversion Test Assets](../image-conversion-test-assets/): generated fixtures, real colorspace assertions, and the backend integration suite for image-conversion regressions\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared cross-boundary rules that often expand the validation surface\n- [How to Plan and Review a Change](../../contribution-workflows/how-to-plan-and-review-a-change/): decide scope before choosing checks\n- [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/): use this when version metadata or reviewed dependency inputs are part of the change\n", "1.0": "+++\ntitle = \"Test Strategy Overview\"\n+++\n\nSambee has multiple subsystems, so the right validation strategy depends on which contract you changed.\n\n## Start with the Smallest Relevant Set\n\nDo not default to either no validation or every possible check.\n\n- backend-only change with no shared contract impact: run backend tests and type checking\n- frontend-only change: run frontend tests, type check, and lint\n- companion-only change: run companion checks, the Windows GNU cross-check, and Rust tests\n- shared workflow change: run every affected subsystem's checks\n\n## Recommended Checks by Change Area\n\n| Change area | Baseline checks |\n|---|---|\n| Backend behavior | `cd backend \u0026\u0026 pytest -m 'not performance' -v`, `cd backend \u0026\u0026 pytest -m performance -v`, `cd backend \u0026\u0026 mypy app` |\n| Frontend behavior | `cd frontend \u0026\u0026 npm test`, `cd frontend \u0026\u0026 npx tsc --noEmit`, `cd frontend \u0026\u0026 npm run lint` |\n| Companion behavior | `cd companion \u0026\u0026 npx tsc --noEmit`, `cd companion \u0026\u0026 npm run lint`, `cd companion \u0026\u0026 npm run check:rust:windows`, `cd companion/src-tauri \u0026\u0026 cargo test` |\n\nFor fast local iteration, `./scripts/test` runs the main backend, frontend, and companion suites together. Its backend pass mirrors CI by running non-performance tests in parallel and `@performance` tests in a separate serial pass. The local companion pass now also includes the Windows GNU target compatibility check when the toolchain is installed. Use `COVERAGE=1 ./scripts/test` when you want the broader CI-style coverage pass.\n\n### Frontend Browser-Test Layers\n\nKeep frontend browser coverage explicit instead of folding it into the default Vitest command.\n\n- `cd frontend \u0026\u0026 npm test` runs the default Vitest suite.\n- `cd frontend \u0026\u0026 npm run test:e2e` runs the default Playwright Chromium suite.\n- `cd frontend \u0026\u0026 npm run test:e2e:all` runs all configured Playwright browser projects.\n\nInstall Playwright browsers locally with `cd frontend \u0026\u0026 npm run test:e2e:install` when a fresh environment does not have the browser binaries yet.\n\n## Cross-Boundary Changes Need Cross-Boundary Checks\n\nRun broader coverage when you change a shared contract, for example:\n\n- backend response shape that the frontend consumes\n- companion behavior that changes browser-facing pairing or editing flows\n- localization or logging behavior that spans more than one app\n\n## Contract-Sensitive Areas\n\n### API Contracts\n\nFrontend and backend compatibility depends on stable response shapes and matching types. Sambee currently protects that boundary primarily with frontend service contract tests plus backend endpoint tests for the same response families.\n\n#### Current Pattern in This Repository\n\nThe current API-contract pattern is broader than a single logging endpoint.\n\n- frontend contract suites live under `frontend/src/services/__tests__/`\n- those tests typically mock the HTTP client, call the real frontend service methods, and assert endpoint paths, request parameters, response shapes, field types, enum values, blob headers, and error handling\n- representative suites include `authApi.test.ts`, `connectionApi.test.ts`, `browseApi.test.ts`, `viewerApi.test.ts`, `mobileLoggingApi.test.ts`, and `loggingConfig.test.ts`\n- backend tests validate the corresponding FastAPI surface from the server side, for example `backend/tests/test_logging_config.py`\n\nThat means an API-shape change is not just a backend refactor. It is a cross-boundary behavior change that should update backend models, backend tests, frontend types, frontend service logic, and the contract tests that bind them together.\n\n#### What the Frontend Contract Tests Actually Check\n\nThe frontend service contract tests are not only smoke tests.\n\n- authentication and admin flows check required fields and value shapes for token, user, and connection payloads\n- browse tests check nested directory listings, `FileInfo` structure, enum values, optional metadata, and path handling\n- viewer tests check binary-response behavior such as `Blob` creation, `Content-Type` handling, viewport parameters, and download semantics\n- logging-config tests check the exact backend response shape and then verify behavior derived from it, such as level-threshold evaluation and disabled-state behavior\n\nThe useful rule is: test the response contract first, then test the frontend behavior that depends on that contract.\n\n#### Logging Configuration as a Concrete Example\n\nThe logging configuration tests are a good example because they show both sides of the boundary.\n\n- backend tests assert the `/api/logs/config` response contains `logging_enabled`, `logging_level`, `tracing_enabled`, `tracing_level`, and `tracing_components`\n- frontend tests in `loggingConfig.test.ts` consume that exact shape and then verify threshold and filtering behavior that would break if the backend fields drifted\n\nThis matters because an older or copied example that still expects fields like `enabled` or `log_level` would describe the wrong contract for the current codebase.\n\n#### When to Add or Update Contract Tests\n\nAdd or expand API contract coverage when:\n\n- you add a new frontend-consumed endpoint\n- you rename, remove, or add a response field\n- you change enum values or allowed string values\n- you change binary-response behavior such as MIME handling, blob creation, or download headers\n- you add frontend logic that derives behavior from backend configuration values rather than just displaying them\n\nFor those changes, update both ends together:\n\n1. backend response model or endpoint behavior\n2. backend tests for the server response\n3. frontend types and service methods\n4. frontend contract tests for the consumed shape\n5. frontend behavior tests for the logic built on top of that shape\n\n#### Practical Contract-Testing Checklist\n\nFor a new or changed endpoint, usually verify:\n\n- required fields exist\n- field types match the frontend types\n- optional fields behave correctly when present or absent\n- known enum or string-literal values are accepted intentionally\n- request parameters and path construction still match the backend route contract\n- error responses degrade in a controlled way\n- derived frontend behavior still works once the typed response is consumed\n\n#### OpenAPI as a Future Option\n\nSambee exposes and tests the backend OpenAPI schema, including `/openapi.json`, but TypeScript type generation from that schema is not part of the checked-in frontend workflow today.\n\nIf API surface area grows enough to justify generation, OpenAPI-driven types are a reasonable future option because the backend is already able to publish the schema. Treat that as an explicit workflow addition, not as something the repository already guarantees.\n\nPossible future additions include:\n\n- generating TypeScript types from the FastAPI schema in a reviewed frontend workflow\n- adding CI checks that detect generated-type drift\n- widening contract-style coverage for endpoints that still rely mostly on broader unit tests or integration tests\n\n### Localization\n\nLocalization is treated as typed product behavior, not just string replacement. If you touch translation wiring or browser-to-companion localization sync, validate the relevant frontend and companion checks.\n\n### Companion Cross-Target Safety\n\nCompanion contributors now have a local Linux-hosted Windows-target safety check.\n\n- `npm run check:rust:windows` runs `cargo check` for `x86_64-pc-windows-gnu`.\n- In the devcontainer, the required Rust target and MinGW toolchain are preinstalled.\n- This check is for compatibility validation, not for producing release-ready Windows binaries.\n\nKeep the distinction clear:\n\n- local cross-check: prove the Windows target still compiles far enough for contract and dependency safety\n- release build: create the signed Windows installer and updater artifacts in CI on Windows runners\n\n### Logging and Diagnostics\n\nLogging changes can affect both local debugging and backend trace collection. Validate the app surfaces that consume those logging contracts.\n\n## Practical Selection Rule\n\nUse this decision order:\n\n1. Identify which subsystem changed directly.\n2. Identify which other subsystem consumes the changed contract.\n3. Run baseline checks for the changed subsystem.\n4. Add checks for every subsystem whose contract might now be wrong.\n\n## When to Go beyond the Baseline\n\nRun deeper or wider validation when:\n\n- the change affects a high-risk workflow such as file editing, locking, upload, or pairing\n- you changed dependencies or version metadata\n- you changed typed API contracts\n- you changed browser-sensitive editor behavior such as focus handoff, contenteditable selection, keyboard navigation, or decorator-backed editing flows\n- you changed companion native dependencies, Windows-specific crates, or Tauri integration\n- the change fixes a regression that previously escaped narrower coverage\n\nThe goal is not maximum command count. The goal is to prove the changed behavior still matches Sambee's cross-app contracts.\n\n## Backend Test Structure and Fixtures\n\nBackend tests live under `backend/tests/`.\n\nCommon files include:\n\n- `conftest.py`: shared fixtures and test wiring\n- `test_auth.py`: authentication and authorization behavior\n- `test_connections.py`: SMB connection management\n- `test_browser.py`: file-browsing behavior with mocked SMB backends\n\nCommon fixtures include:\n\n- `client`\n- `session`\n- `admin_user`, `regular_user`\n- `admin_token`, `user_token`\n- `auth_headers_admin`, `auth_headers_user`\n- `test_connection`\n- `multiple_connections`\n- `mock_smb_backend`\n\nUse the shared fixtures instead of rebuilding the same setup in each test file.\n\n## Performance Notes\n\n- backend tests use `pytest-xdist` for parallel execution in the normal workflow, but `@performance` tests run separately without xdist so timing assertions stay stable\n- coverage is intentionally optional during routine local work because it is slower\n- use deeper coverage when the change touches risky backend behavior or when CI-equivalent evidence matters\n\n## Go Deeper\n\n- [Image Conversion Test Assets](../image-conversion-test-assets/): generated fixtures, real colorspace assertions, and the backend integration suite for image-conversion regressions\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared cross-boundary rules that often expand the validation surface\n- [How to Plan and Review a Change](../../contribution-workflows/how-to-plan-and-review-a-change/): decide scope before choosing checks\n- [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/): use this when version metadata or reviewed dependency inputs are part of the change\n", "2.0": "+++\ntitle = \"Test Strategy Overview\"\n+++\n\nSambee has multiple subsystems, so the right validation strategy depends on which contract you changed.\n\n## Start with the Smallest Relevant Set\n\nDo not default to either no validation or every possible check.\n\n- backend-only change with no shared contract impact: run backend tests and type checking\n- frontend-only change: run frontend tests, type check, and lint\n- companion-only change: run companion checks, the Windows GNU cross-check, and Rust tests\n- shared workflow change: run every affected subsystem's checks\n\n## Recommended Checks by Change Area\n\n| Change area | Baseline checks |\n|---|---|\n| Backend behavior | `cd backend \u0026\u0026 pytest -m 'not performance' -v`, `cd backend \u0026\u0026 pytest -m performance -v`, `cd backend \u0026\u0026 mypy app` |\n| Frontend behavior | `cd frontend \u0026\u0026 npm test`, `cd frontend \u0026\u0026 npx tsc --noEmit`, `cd frontend \u0026\u0026 npm run lint` |\n| Companion behavior | `cd companion \u0026\u0026 npx tsc --noEmit`, `cd companion \u0026\u0026 npm run lint`, `cd companion \u0026\u0026 npm run check:rust:windows`, `cd companion/src-tauri \u0026\u0026 cargo test` |\n\nFor fast local iteration, `./scripts/test` runs the main backend, frontend, and companion suites together. Its backend pass mirrors CI by running non-performance tests in parallel and `@performance` tests in a separate serial pass. The local companion pass now also includes the Windows GNU target compatibility check when the toolchain is installed. Use `COVERAGE=1 ./scripts/test` when you want the broader CI-style coverage pass.\n\n### Frontend Browser-Test Layers\n\nKeep frontend browser coverage explicit instead of folding it into the default Vitest command.\n\n- `cd frontend \u0026\u0026 npm test` runs the default Vitest suite.\n- `cd frontend \u0026\u0026 npm run test:e2e` runs the default Playwright Chromium suite.\n- `cd frontend \u0026\u0026 npm run test:e2e:all` runs all configured Playwright browser projects.\n\nInstall Playwright browsers locally with `cd frontend \u0026\u0026 npm run test:e2e:install` when a fresh environment does not have the browser binaries yet.\n\n## Cross-Boundary Changes Need Cross-Boundary Checks\n\nRun broader coverage when you change a shared contract, for example:\n\n- backend response shape that the frontend consumes\n- companion behavior that changes browser-facing pairing or editing flows\n- localization or logging behavior that spans more than one app\n\n## Contract-Sensitive Areas\n\n### API Contracts\n\nFrontend and backend compatibility depends on stable response shapes and matching types. Sambee currently protects that boundary primarily with frontend service contract tests plus backend endpoint tests for the same response families.\n\n#### Current Pattern in This Repository\n\nThe current API-contract pattern is broader than a single logging endpoint.\n\n- frontend contract suites live under `frontend/src/services/__tests__/`\n- those tests typically mock the HTTP client, call the real frontend service methods, and assert endpoint paths, request parameters, response shapes, field types, enum values, blob headers, and error handling\n- representative suites include `authApi.test.ts`, `connectionApi.test.ts`, `browseApi.test.ts`, `viewerApi.test.ts`, `mobileLoggingApi.test.ts`, and `loggingConfig.test.ts`\n- backend tests validate the corresponding FastAPI surface from the server side, for example `backend/tests/test_logging_config.py`\n\nThat means an API-shape change is not just a backend refactor. It is a cross-boundary behavior change that should update backend models, backend tests, frontend types, frontend service logic, and the contract tests that bind them together.\n\n#### What the Frontend Contract Tests Actually Check\n\nThe frontend service contract tests are not only smoke tests.\n\n- authentication and admin flows check required fields and value shapes for token, user, and connection payloads\n- browse tests check nested directory listings, `FileInfo` structure, enum values, optional metadata, and path handling\n- viewer tests check binary-response behavior such as `Blob` creation, `Content-Type` handling, viewport parameters, and download semantics\n- logging-config tests check the exact backend response shape and then verify behavior derived from it, such as level-threshold evaluation and disabled-state behavior\n\nThe useful rule is: test the response contract first, then test the frontend behavior that depends on that contract.\n\n#### Logging Configuration as a Concrete Example\n\nThe logging configuration tests are a good example because they show both sides of the boundary.\n\n- backend tests assert the `/api/logs/config` response contains `logging_enabled`, `logging_level`, `tracing_enabled`, `tracing_level`, and `tracing_components`\n- frontend tests in `loggingConfig.test.ts` consume that exact shape and then verify threshold and filtering behavior that would break if the backend fields drifted\n\nThis matters because an older or copied example that still expects fields like `enabled` or `log_level` would describe the wrong contract for the current codebase.\n\n#### When to Add or Update Contract Tests\n\nAdd or expand API contract coverage when:\n\n- you add a new frontend-consumed endpoint\n- you rename, remove, or add a response field\n- you change enum values or allowed string values\n- you change binary-response behavior such as MIME handling, blob creation, or download headers\n- you add frontend logic that derives behavior from backend configuration values rather than just displaying them\n\nFor those changes, update both ends together:\n\n1. backend response model or endpoint behavior\n2. backend tests for the server response\n3. frontend types and service methods\n4. frontend contract tests for the consumed shape\n5. frontend behavior tests for the logic built on top of that shape\n\n#### Practical Contract-Testing Checklist\n\nFor a new or changed endpoint, usually verify:\n\n- required fields exist\n- field types match the frontend types\n- optional fields behave correctly when present or absent\n- known enum or string-literal values are accepted intentionally\n- request parameters and path construction still match the backend route contract\n- error responses degrade in a controlled way\n- derived frontend behavior still works once the typed response is consumed\n\n#### OpenAPI as a Future Option\n\nSambee exposes and tests the backend OpenAPI schema, including `/openapi.json`, but TypeScript type generation from that schema is not part of the checked-in frontend workflow today.\n\nIf API surface area grows enough to justify generation, OpenAPI-driven types are a reasonable future option because the backend is already able to publish the schema. Treat that as an explicit workflow addition, not as something the repository already guarantees.\n\nPossible future additions include:\n\n- generating TypeScript types from the FastAPI schema in a reviewed frontend workflow\n- adding CI checks that detect generated-type drift\n- widening contract-style coverage for endpoints that still rely mostly on broader unit tests or integration tests\n\n### Localization\n\nLocalization is treated as typed product behavior, not just string replacement. If you touch translation wiring or browser-to-companion localization sync, validate the relevant frontend and companion checks.\n\n### Companion Cross-Target Safety\n\nCompanion contributors now have a local Linux-hosted Windows-target safety check.\n\n- `npm run check:rust:windows` runs `cargo check` for `x86_64-pc-windows-gnu`.\n- In the devcontainer, the required Rust target and MinGW toolchain are preinstalled.\n- This check is for compatibility validation, not for producing release-ready Windows binaries.\n\nKeep the distinction clear:\n\n- local cross-check: prove the Windows target still compiles far enough for contract and dependency safety\n- release build: create the signed Windows installer and updater artifacts in CI on Windows runners\n\n### Logging and Diagnostics\n\nLogging changes can affect both local debugging and backend trace collection. Validate the app surfaces that consume those logging contracts.\n\n## Practical Selection Rule\n\nUse this decision order:\n\n1. Identify which subsystem changed directly.\n2. Identify which other subsystem consumes the changed contract.\n3. Run baseline checks for the changed subsystem.\n4. Add checks for every subsystem whose contract might now be wrong.\n\n## When to Go beyond the Baseline\n\nRun deeper or wider validation when:\n\n- the change affects a high-risk workflow such as file editing, locking, upload, or pairing\n- you changed dependencies or version metadata\n- you changed typed API contracts\n- you changed browser-sensitive editor behavior such as focus handoff, contenteditable selection, keyboard navigation, or decorator-backed editing flows\n- you changed companion native dependencies, Windows-specific crates, or Tauri integration\n- the change fixes a regression that previously escaped narrower coverage\n\nThe goal is not maximum command count. The goal is to prove the changed behavior still matches Sambee's cross-app contracts.\n\n## Backend Test Structure and Fixtures\n\nBackend tests live under `backend/tests/`.\n\nCommon files include:\n\n- `conftest.py`: shared fixtures and test wiring\n- `test_auth.py`: authentication and authorization behavior\n- `test_connections.py`: SMB connection management\n- `test_browser.py`: file-browsing behavior with mocked SMB backends\n\nCommon fixtures include:\n\n- `client`\n- `session`\n- `admin_user`, `regular_user`\n- `admin_token`, `user_token`\n- `auth_headers_admin`, `auth_headers_user`\n- `test_connection`\n- `multiple_connections`\n- `mock_smb_backend`\n\nUse the shared fixtures instead of rebuilding the same setup in each test file.\n\n## Performance Notes\n\n- backend tests use `pytest-xdist` for parallel execution in the normal workflow, but `@performance` tests run separately without xdist so timing assertions stay stable\n- coverage is intentionally optional during routine local work because it is slower\n- use deeper coverage when the change touches risky backend behavior or when CI-equivalent evidence matters\n\n## Go Deeper\n\n- [Image Conversion Test Assets](../image-conversion-test-assets/): generated fixtures, real colorspace assertions, and the backend integration suite for image-conversion regressions\n- [Logging and Localization](../../cross-cutting-systems/logging-and-localization/): shared cross-boundary rules that often expand the validation surface\n- [How to Plan and Review a Change](../../contribution-workflows/how-to-plan-and-review-a-change/): decide scope before choosing checks\n- [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/): use this when version metadata or reviewed dependency inputs are part of the change\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/testing-and-quality-gates/image-conversion-test-assets", "parent_id": "section:developer-guide/testing-and-quality-gates", "depth": 2, "kind": "page", "label": "image-conversion-test-assets", "title": "Image Conversion Test Assets", "path": "developer-guide/testing-and-quality-gates/image-conversion-test-assets", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Image Conversion Test Assets\"\n+++\n\nSambee uses generated image fixtures to test the image-conversion and preprocessing pipeline without bloating the repository with large checked-in binaries.\n\nThese fixtures exist to verify real conversion behavior, especially around colorspace handling where naive expectations are often wrong.\n\n## Why These Assets Exist\n\nThe backend conversion pipeline has to do more than just decode files successfully.\n\n- CMYK inputs must convert into browser-safe RGB output without silent inversion or broken ICC handling\n- RGB inputs should preserve color rather than drifting during conversion\n- preprocessable vector formats such as EPS and AI need realistic fixtures, not only mocked unit tests\n- grayscale and Lab examples protect less-common conversion paths\n\nThat is why the repo includes a generated fixture workflow instead of relying only on synthetic unit-level mocks.\n\n## Where the Generated Assets Live\n\nThe generation workflow populates `backend/tests/test_data/`.\n\nCurrent layout:\n\n- `backend/tests/test_data/images/cmyk/`\n- `backend/tests/test_data/images/rgb/`\n- `backend/tests/test_data/images/special/`\n- `backend/tests/test_data/expected/`\n- `backend/tests/test_data/metadata/manifest.json`\n- `backend/tests/test_data/.gitignore`\n\nThe generated image set is intentionally small.\n\n- 4 CMYK fixtures\n- 4 RGB fixtures\n- 2 special-colorspace fixtures\n\nThose ten files are enough to exercise the main conversion and preprocessing paths without turning the repo into an asset dump.\n\n## What the Current Fixture Set Covers\n\n### CMYK Fixtures\n\nThe CMYK set covers:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThese are the highest-value fixtures because CMYK conversion is where incorrect assumptions are most likely.\n\nImportant rule: CMYK inputs do not convert to the naive pure RGB values contributors often expect.\n\nExamples from the real tests:\n\n- CMYK cyan does not become pure `(0, 255, 255)`\n- CMYK magenta does not become pure `(255, 0, 255)`\n- CMYK yellow does not become pure `(255, 255, 0)`\n- CMYK black does not become pure `(0, 0, 0)`\n\nThe expected values in `backend/tests/test_image_conversion_real.py` reflect real ICC-profile conversion output, and those test expectations are the current source of truth for assertion behavior.\n\n### RGB Fixtures\n\nThe RGB set verifies that already-browser-friendly color inputs do not get unintentionally altered during conversion.\n\nThose fixtures cover:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThe expectation there is preservation rather than major transformation.\n\n### Special Colorspaces\n\nThe special set currently includes:\n\n- grayscale PSD\n- Lab TIFF\n\nThese protect lesser-used but still important conversion paths.\n\n## How the Assets Are Generated\n\nThe supported entry point is:\n\n```bash\n./scripts/setup-test-images\n```\n\nThat script:\n\n- creates the test-data directory structure\n- generates raster fixtures with ImageMagick\n- generates EPS and AI fixtures with hand-crafted PostScript instead of relying on ImageMagick to produce trustworthy CMYK vector output\n- writes `metadata/manifest.json`\n- writes `backend/tests/test_data/.gitignore` so the generated artifacts do not become repository noise\n\nThe vector-generation choice is deliberate. Hand-crafted PostScript gives the tests explicit `DeviceCMYK` or `DeviceRGB` behavior that is more reliable than hoping a generic export path preserves the intended colorspace semantics.\n\n## Manifest Versus Test Assertions\n\nTreat the manifest as generated inventory metadata, not as the sole assertion source for the image-conversion tests.\n\nThe real backend assertions currently live in `backend/tests/test_image_conversion_real.py`, including:\n\n- colorspace expectations\n- color-distance tolerances\n- converter-path expectations such as preprocessor usage\n\nThat distinction matters because fixture metadata can drift if contributors update the script but forget the test semantics, or vice versa.\n\n## How the Tests Use the Assets\n\nThe main integration coverage lives in `backend/tests/test_image_conversion_real.py`.\n\nThat file:\n\n- auto-generates the fixtures through an autouse module-scoped fixture when they are missing\n- loads the generated manifest for iteration over the asset set\n- uses `pyvips` to inspect colorspace and average color values\n- verifies conversion output from `convert_image_for_viewer(...)`\n- checks preprocessable formats through `PreprocessorRegistry`\n\nThe tests are marked as integration tests because they exercise real decoding and conversion behavior rather than only mocked internals.\n\n## Supported Commands\n\nTo generate the assets explicitly:\n\n```bash\n./scripts/setup-test-images\n```\n\nTo run the real image-conversion integration suite:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -v\n```\n\nTo focus on CMYK behavior:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -k cmyk -v\n```\n\nTo pair the tests with backend coverage for the conversion service:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py --cov=app/services/image_converter\n```\n\n## Tolerances and Performance Expectations\n\nThe current suite intentionally allows some color-distance tolerance.\n\n- CMYK conversion assertions allow wider tolerance because ICC-based conversion is not a byte-for-byte identity transform\n- RGB preservation assertions use tighter thresholds because the expected result is much closer to the source color intent\n\nThe same suite also keeps a simple performance guard so tiny generated fixtures do not regress into unexpectedly slow conversions.\n\n## When to Change the Fixture Set\n\nUpdate the generated assets when:\n\n- you add support for a new preprocessable format\n- you change CMYK or colorspace handling in a way that should be locked down by a real fixture\n- you discover a real-world conversion regression that a small generated file can reproduce reliably\n\nWhen you add or change assets, update all three layers together:\n\n1. `scripts/setup-test-images`\n2. `backend/tests/test_image_conversion_real.py`\n3. the generated manifest or any related inventory description that the script emits\n\nDo not treat the assets as static binaries that should be edited by hand.\n\n## Troubleshooting\n\n### Assets Missing\n\nIf the fixtures are missing, rerun:\n\n```bash\n./scripts/setup-test-images\n```\n\nThe test module can generate them automatically, but explicit generation is usually the fastest way to confirm the local environment is healthy.\n\n### Imagemagick Missing\n\nThe generator expects ImageMagick 7 with the supported wrapper path or binary on `PATH`.\n\nIf the script reports that `magick` is missing, run the repo's supported system-dependency setup first:\n\n```bash\n./scripts/install-system-deps\n```\n\n### Color Mismatches\n\nIf color assertions change unexpectedly:\n\n- verify that the local environment still has the expected ImageMagick and ICC-profile support\n- check whether the backend conversion path changed intentionally\n- compare the actual average color output from the failing test before changing tolerances or expected values\n\nDo not update expected colors casually. CMYK expectations in particular exist to catch exactly that sort of silent behavior drift.\n", "0.8": "+++\ntitle = \"Image Conversion Test Assets\"\n+++\n\nSambee uses generated image fixtures to test the image-conversion and preprocessing pipeline without bloating the repository with large checked-in binaries.\n\nThese fixtures exist to verify real conversion behavior, especially around colorspace handling where naive expectations are often wrong.\n\n## Why These Assets Exist\n\nThe backend conversion pipeline has to do more than just decode files successfully.\n\n- CMYK inputs must convert into browser-safe RGB output without silent inversion or broken ICC handling\n- RGB inputs should preserve color rather than drifting during conversion\n- preprocessable vector formats such as EPS and AI need realistic fixtures, not only mocked unit tests\n- grayscale and Lab examples protect less-common conversion paths\n\nThat is why the repo includes a generated fixture workflow instead of relying only on synthetic unit-level mocks.\n\n## Where the Generated Assets Live\n\nThe generation workflow populates `backend/tests/test_data/`.\n\nCurrent layout:\n\n- `backend/tests/test_data/images/cmyk/`\n- `backend/tests/test_data/images/rgb/`\n- `backend/tests/test_data/images/special/`\n- `backend/tests/test_data/expected/`\n- `backend/tests/test_data/metadata/manifest.json`\n- `backend/tests/test_data/.gitignore`\n\nThe generated image set is intentionally small.\n\n- 4 CMYK fixtures\n- 4 RGB fixtures\n- 2 special-colorspace fixtures\n\nThose ten files are enough to exercise the main conversion and preprocessing paths without turning the repo into an asset dump.\n\n## What the Current Fixture Set Covers\n\n### CMYK Fixtures\n\nThe CMYK set covers:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThese are the highest-value fixtures because CMYK conversion is where incorrect assumptions are most likely.\n\nImportant rule: CMYK inputs do not convert to the naive pure RGB values contributors often expect.\n\nExamples from the real tests:\n\n- CMYK cyan does not become pure `(0, 255, 255)`\n- CMYK magenta does not become pure `(255, 0, 255)`\n- CMYK yellow does not become pure `(255, 255, 0)`\n- CMYK black does not become pure `(0, 0, 0)`\n\nThe expected values in `backend/tests/test_image_conversion_real.py` reflect real ICC-profile conversion output, and those test expectations are the current source of truth for assertion behavior.\n\n### RGB Fixtures\n\nThe RGB set verifies that already-browser-friendly color inputs do not get unintentionally altered during conversion.\n\nThose fixtures cover:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThe expectation there is preservation rather than major transformation.\n\n### Special Colorspaces\n\nThe special set currently includes:\n\n- grayscale PSD\n- Lab TIFF\n\nThese protect lesser-used but still important conversion paths.\n\n## How the Assets Are Generated\n\nThe supported entry point is:\n\n```bash\n./scripts/setup-test-images\n```\n\nThat script:\n\n- creates the test-data directory structure\n- generates raster fixtures with ImageMagick\n- generates EPS and AI fixtures with hand-crafted PostScript instead of relying on ImageMagick to produce trustworthy CMYK vector output\n- writes `metadata/manifest.json`\n- writes `backend/tests/test_data/.gitignore` so the generated artifacts do not become repository noise\n\nThe vector-generation choice is deliberate. Hand-crafted PostScript gives the tests explicit `DeviceCMYK` or `DeviceRGB` behavior that is more reliable than hoping a generic export path preserves the intended colorspace semantics.\n\n## Manifest Versus Test Assertions\n\nTreat the manifest as generated inventory metadata, not as the sole assertion source for the image-conversion tests.\n\nThe real backend assertions currently live in `backend/tests/test_image_conversion_real.py`, including:\n\n- colorspace expectations\n- color-distance tolerances\n- converter-path expectations such as preprocessor usage\n\nThat distinction matters because fixture metadata can drift if contributors update the script but forget the test semantics, or vice versa.\n\n## How the Tests Use the Assets\n\nThe main integration coverage lives in `backend/tests/test_image_conversion_real.py`.\n\nThat file:\n\n- auto-generates the fixtures through an autouse module-scoped fixture when they are missing\n- loads the generated manifest for iteration over the asset set\n- uses `pyvips` to inspect colorspace and average color values\n- verifies conversion output from `convert_image_for_viewer(...)`\n- checks preprocessable formats through `PreprocessorRegistry`\n\nThe tests are marked as integration tests because they exercise real decoding and conversion behavior rather than only mocked internals.\n\n## Supported Commands\n\nTo generate the assets explicitly:\n\n```bash\n./scripts/setup-test-images\n```\n\nTo run the real image-conversion integration suite:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -v\n```\n\nTo focus on CMYK behavior:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -k cmyk -v\n```\n\nTo pair the tests with backend coverage for the conversion service:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py --cov=app/services/image_converter\n```\n\n## Tolerances and Performance Expectations\n\nThe current suite intentionally allows some color-distance tolerance.\n\n- CMYK conversion assertions allow wider tolerance because ICC-based conversion is not a byte-for-byte identity transform\n- RGB preservation assertions use tighter thresholds because the expected result is much closer to the source color intent\n\nThe same suite also keeps a simple performance guard so tiny generated fixtures do not regress into unexpectedly slow conversions.\n\n## When to Change the Fixture Set\n\nUpdate the generated assets when:\n\n- you add support for a new preprocessable format\n- you change CMYK or colorspace handling in a way that should be locked down by a real fixture\n- you discover a real-world conversion regression that a small generated file can reproduce reliably\n\nWhen you add or change assets, update all three layers together:\n\n1. `scripts/setup-test-images`\n2. `backend/tests/test_image_conversion_real.py`\n3. the generated manifest or any related inventory description that the script emits\n\nDo not treat the assets as static binaries that should be edited by hand.\n\n## Troubleshooting\n\n### Assets Missing\n\nIf the fixtures are missing, rerun:\n\n```bash\n./scripts/setup-test-images\n```\n\nThe test module can generate them automatically, but explicit generation is usually the fastest way to confirm the local environment is healthy.\n\n### Imagemagick Missing\n\nThe generator expects ImageMagick 7 with the supported wrapper path or binary on `PATH`.\n\nIf the script reports that `magick` is missing, run the repo's supported system-dependency setup first:\n\n```bash\n./scripts/install-system-deps\n```\n\n### Color Mismatches\n\nIf color assertions change unexpectedly:\n\n- verify that the local environment still has the expected ImageMagick and ICC-profile support\n- check whether the backend conversion path changed intentionally\n- compare the actual average color output from the failing test before changing tolerances or expected values\n\nDo not update expected colors casually. CMYK expectations in particular exist to catch exactly that sort of silent behavior drift.\n", "0.9": "+++\ntitle = \"Image Conversion Test Assets\"\n+++\n\nSambee uses generated image fixtures to test the image-conversion and preprocessing pipeline without bloating the repository with large checked-in binaries.\n\nThese fixtures exist to verify real conversion behavior, especially around colorspace handling where naive expectations are often wrong.\n\n## Why These Assets Exist\n\nThe backend conversion pipeline has to do more than just decode files successfully.\n\n- CMYK inputs must convert into browser-safe RGB output without silent inversion or broken ICC handling\n- RGB inputs should preserve color rather than drifting during conversion\n- preprocessable vector formats such as EPS and AI need realistic fixtures, not only mocked unit tests\n- grayscale and Lab examples protect less-common conversion paths\n\nThat is why the repo includes a generated fixture workflow instead of relying only on synthetic unit-level mocks.\n\n## Where the Generated Assets Live\n\nThe generation workflow populates `backend/tests/test_data/`.\n\nCurrent layout:\n\n- `backend/tests/test_data/images/cmyk/`\n- `backend/tests/test_data/images/rgb/`\n- `backend/tests/test_data/images/special/`\n- `backend/tests/test_data/expected/`\n- `backend/tests/test_data/metadata/manifest.json`\n- `backend/tests/test_data/.gitignore`\n\nThe generated image set is intentionally small.\n\n- 4 CMYK fixtures\n- 4 RGB fixtures\n- 2 special-colorspace fixtures\n\nThose ten files are enough to exercise the main conversion and preprocessing paths without turning the repo into an asset dump.\n\n## What the Current Fixture Set Covers\n\n### CMYK Fixtures\n\nThe CMYK set covers:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThese are the highest-value fixtures because CMYK conversion is where incorrect assumptions are most likely.\n\nImportant rule: CMYK inputs do not convert to the naive pure RGB values contributors often expect.\n\nExamples from the real tests:\n\n- CMYK cyan does not become pure `(0, 255, 255)`\n- CMYK magenta does not become pure `(255, 0, 255)`\n- CMYK yellow does not become pure `(255, 255, 0)`\n- CMYK black does not become pure `(0, 0, 0)`\n\nThe expected values in `backend/tests/test_image_conversion_real.py` reflect real ICC-profile conversion output, and those test expectations are the current source of truth for assertion behavior.\n\n### RGB Fixtures\n\nThe RGB set verifies that already-browser-friendly color inputs do not get unintentionally altered during conversion.\n\nThose fixtures cover:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThe expectation there is preservation rather than major transformation.\n\n### Special Colorspaces\n\nThe special set currently includes:\n\n- grayscale PSD\n- Lab TIFF\n\nThese protect lesser-used but still important conversion paths.\n\n## How the Assets Are Generated\n\nThe supported entry point is:\n\n```bash\n./scripts/setup-test-images\n```\n\nThat script:\n\n- creates the test-data directory structure\n- generates raster fixtures with ImageMagick\n- generates EPS and AI fixtures with hand-crafted PostScript instead of relying on ImageMagick to produce trustworthy CMYK vector output\n- writes `metadata/manifest.json`\n- writes `backend/tests/test_data/.gitignore` so the generated artifacts do not become repository noise\n\nThe vector-generation choice is deliberate. Hand-crafted PostScript gives the tests explicit `DeviceCMYK` or `DeviceRGB` behavior that is more reliable than hoping a generic export path preserves the intended colorspace semantics.\n\n## Manifest Versus Test Assertions\n\nTreat the manifest as generated inventory metadata, not as the sole assertion source for the image-conversion tests.\n\nThe real backend assertions currently live in `backend/tests/test_image_conversion_real.py`, including:\n\n- colorspace expectations\n- color-distance tolerances\n- converter-path expectations such as preprocessor usage\n\nThat distinction matters because fixture metadata can drift if contributors update the script but forget the test semantics, or vice versa.\n\n## How the Tests Use the Assets\n\nThe main integration coverage lives in `backend/tests/test_image_conversion_real.py`.\n\nThat file:\n\n- auto-generates the fixtures through an autouse module-scoped fixture when they are missing\n- loads the generated manifest for iteration over the asset set\n- uses `pyvips` to inspect colorspace and average color values\n- verifies conversion output from `convert_image_for_viewer(...)`\n- checks preprocessable formats through `PreprocessorRegistry`\n\nThe tests are marked as integration tests because they exercise real decoding and conversion behavior rather than only mocked internals.\n\n## Supported Commands\n\nTo generate the assets explicitly:\n\n```bash\n./scripts/setup-test-images\n```\n\nTo run the real image-conversion integration suite:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -v\n```\n\nTo focus on CMYK behavior:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -k cmyk -v\n```\n\nTo pair the tests with backend coverage for the conversion service:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py --cov=app/services/image_converter\n```\n\n## Tolerances and Performance Expectations\n\nThe current suite intentionally allows some color-distance tolerance.\n\n- CMYK conversion assertions allow wider tolerance because ICC-based conversion is not a byte-for-byte identity transform\n- RGB preservation assertions use tighter thresholds because the expected result is much closer to the source color intent\n\nThe same suite also keeps a simple performance guard so tiny generated fixtures do not regress into unexpectedly slow conversions.\n\n## When to Change the Fixture Set\n\nUpdate the generated assets when:\n\n- you add support for a new preprocessable format\n- you change CMYK or colorspace handling in a way that should be locked down by a real fixture\n- you discover a real-world conversion regression that a small generated file can reproduce reliably\n\nWhen you add or change assets, update all three layers together:\n\n1. `scripts/setup-test-images`\n2. `backend/tests/test_image_conversion_real.py`\n3. the generated manifest or any related inventory description that the script emits\n\nDo not treat the assets as static binaries that should be edited by hand.\n\n## Troubleshooting\n\n### Assets Missing\n\nIf the fixtures are missing, rerun:\n\n```bash\n./scripts/setup-test-images\n```\n\nThe test module can generate them automatically, but explicit generation is usually the fastest way to confirm the local environment is healthy.\n\n### Imagemagick Missing\n\nThe generator expects ImageMagick 7 with the supported wrapper path or binary on `PATH`.\n\nIf the script reports that `magick` is missing, run the repo's supported system-dependency setup first:\n\n```bash\n./scripts/install-system-deps\n```\n\n### Color Mismatches\n\nIf color assertions change unexpectedly:\n\n- verify that the local environment still has the expected ImageMagick and ICC-profile support\n- check whether the backend conversion path changed intentionally\n- compare the actual average color output from the failing test before changing tolerances or expected values\n\nDo not update expected colors casually. CMYK expectations in particular exist to catch exactly that sort of silent behavior drift.\n", "1.0": "+++\ntitle = \"Image Conversion Test Assets\"\n+++\n\nSambee uses generated image fixtures to test the image-conversion and preprocessing pipeline without bloating the repository with large checked-in binaries.\n\nThese fixtures exist to verify real conversion behavior, especially around colorspace handling where naive expectations are often wrong.\n\n## Why These Assets Exist\n\nThe backend conversion pipeline has to do more than just decode files successfully.\n\n- CMYK inputs must convert into browser-safe RGB output without silent inversion or broken ICC handling\n- RGB inputs should preserve color rather than drifting during conversion\n- preprocessable vector formats such as EPS and AI need realistic fixtures, not only mocked unit tests\n- grayscale and Lab examples protect less-common conversion paths\n\nThat is why the repo includes a generated fixture workflow instead of relying only on synthetic unit-level mocks.\n\n## Where the Generated Assets Live\n\nThe generation workflow populates `backend/tests/test_data/`.\n\nCurrent layout:\n\n- `backend/tests/test_data/images/cmyk/`\n- `backend/tests/test_data/images/rgb/`\n- `backend/tests/test_data/images/special/`\n- `backend/tests/test_data/expected/`\n- `backend/tests/test_data/metadata/manifest.json`\n- `backend/tests/test_data/.gitignore`\n\nThe generated image set is intentionally small.\n\n- 4 CMYK fixtures\n- 4 RGB fixtures\n- 2 special-colorspace fixtures\n\nThose ten files are enough to exercise the main conversion and preprocessing paths without turning the repo into an asset dump.\n\n## What the Current Fixture Set Covers\n\n### CMYK Fixtures\n\nThe CMYK set covers:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThese are the highest-value fixtures because CMYK conversion is where incorrect assumptions are most likely.\n\nImportant rule: CMYK inputs do not convert to the naive pure RGB values contributors often expect.\n\nExamples from the real tests:\n\n- CMYK cyan does not become pure `(0, 255, 255)`\n- CMYK magenta does not become pure `(255, 0, 255)`\n- CMYK yellow does not become pure `(255, 255, 0)`\n- CMYK black does not become pure `(0, 0, 0)`\n\nThe expected values in `backend/tests/test_image_conversion_real.py` reflect real ICC-profile conversion output, and those test expectations are the current source of truth for assertion behavior.\n\n### RGB Fixtures\n\nThe RGB set verifies that already-browser-friendly color inputs do not get unintentionally altered during conversion.\n\nThose fixtures cover:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThe expectation there is preservation rather than major transformation.\n\n### Special Colorspaces\n\nThe special set currently includes:\n\n- grayscale PSD\n- Lab TIFF\n\nThese protect lesser-used but still important conversion paths.\n\n## How the Assets Are Generated\n\nThe supported entry point is:\n\n```bash\n./scripts/setup-test-images\n```\n\nThat script:\n\n- creates the test-data directory structure\n- generates raster fixtures with ImageMagick\n- generates EPS and AI fixtures with hand-crafted PostScript instead of relying on ImageMagick to produce trustworthy CMYK vector output\n- writes `metadata/manifest.json`\n- writes `backend/tests/test_data/.gitignore` so the generated artifacts do not become repository noise\n\nThe vector-generation choice is deliberate. Hand-crafted PostScript gives the tests explicit `DeviceCMYK` or `DeviceRGB` behavior that is more reliable than hoping a generic export path preserves the intended colorspace semantics.\n\n## Manifest Versus Test Assertions\n\nTreat the manifest as generated inventory metadata, not as the sole assertion source for the image-conversion tests.\n\nThe real backend assertions currently live in `backend/tests/test_image_conversion_real.py`, including:\n\n- colorspace expectations\n- color-distance tolerances\n- converter-path expectations such as preprocessor usage\n\nThat distinction matters because fixture metadata can drift if contributors update the script but forget the test semantics, or vice versa.\n\n## How the Tests Use the Assets\n\nThe main integration coverage lives in `backend/tests/test_image_conversion_real.py`.\n\nThat file:\n\n- auto-generates the fixtures through an autouse module-scoped fixture when they are missing\n- loads the generated manifest for iteration over the asset set\n- uses `pyvips` to inspect colorspace and average color values\n- verifies conversion output from `convert_image_for_viewer(...)`\n- checks preprocessable formats through `PreprocessorRegistry`\n\nThe tests are marked as integration tests because they exercise real decoding and conversion behavior rather than only mocked internals.\n\n## Supported Commands\n\nTo generate the assets explicitly:\n\n```bash\n./scripts/setup-test-images\n```\n\nTo run the real image-conversion integration suite:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -v\n```\n\nTo focus on CMYK behavior:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -k cmyk -v\n```\n\nTo pair the tests with backend coverage for the conversion service:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py --cov=app/services/image_converter\n```\n\n## Tolerances and Performance Expectations\n\nThe current suite intentionally allows some color-distance tolerance.\n\n- CMYK conversion assertions allow wider tolerance because ICC-based conversion is not a byte-for-byte identity transform\n- RGB preservation assertions use tighter thresholds because the expected result is much closer to the source color intent\n\nThe same suite also keeps a simple performance guard so tiny generated fixtures do not regress into unexpectedly slow conversions.\n\n## When to Change the Fixture Set\n\nUpdate the generated assets when:\n\n- you add support for a new preprocessable format\n- you change CMYK or colorspace handling in a way that should be locked down by a real fixture\n- you discover a real-world conversion regression that a small generated file can reproduce reliably\n\nWhen you add or change assets, update all three layers together:\n\n1. `scripts/setup-test-images`\n2. `backend/tests/test_image_conversion_real.py`\n3. the generated manifest or any related inventory description that the script emits\n\nDo not treat the assets as static binaries that should be edited by hand.\n\n## Troubleshooting\n\n### Assets Missing\n\nIf the fixtures are missing, rerun:\n\n```bash\n./scripts/setup-test-images\n```\n\nThe test module can generate them automatically, but explicit generation is usually the fastest way to confirm the local environment is healthy.\n\n### Imagemagick Missing\n\nThe generator expects ImageMagick 7 with the supported wrapper path or binary on `PATH`.\n\nIf the script reports that `magick` is missing, run the repo's supported system-dependency setup first:\n\n```bash\n./scripts/install-system-deps\n```\n\n### Color Mismatches\n\nIf color assertions change unexpectedly:\n\n- verify that the local environment still has the expected ImageMagick and ICC-profile support\n- check whether the backend conversion path changed intentionally\n- compare the actual average color output from the failing test before changing tolerances or expected values\n\nDo not update expected colors casually. CMYK expectations in particular exist to catch exactly that sort of silent behavior drift.\n", "2.0": "+++\ntitle = \"Image Conversion Test Assets\"\n+++\n\nSambee uses generated image fixtures to test the image-conversion and preprocessing pipeline without bloating the repository with large checked-in binaries.\n\nThese fixtures exist to verify real conversion behavior, especially around colorspace handling where naive expectations are often wrong.\n\n## Why These Assets Exist\n\nThe backend conversion pipeline has to do more than just decode files successfully.\n\n- CMYK inputs must convert into browser-safe RGB output without silent inversion or broken ICC handling\n- RGB inputs should preserve color rather than drifting during conversion\n- preprocessable vector formats such as EPS and AI need realistic fixtures, not only mocked unit tests\n- grayscale and Lab examples protect less-common conversion paths\n\nThat is why the repo includes a generated fixture workflow instead of relying only on synthetic unit-level mocks.\n\n## Where the Generated Assets Live\n\nThe generation workflow populates `backend/tests/test_data/`.\n\nCurrent layout:\n\n- `backend/tests/test_data/images/cmyk/`\n- `backend/tests/test_data/images/rgb/`\n- `backend/tests/test_data/images/special/`\n- `backend/tests/test_data/expected/`\n- `backend/tests/test_data/metadata/manifest.json`\n- `backend/tests/test_data/.gitignore`\n\nThe generated image set is intentionally small.\n\n- 4 CMYK fixtures\n- 4 RGB fixtures\n- 2 special-colorspace fixtures\n\nThose ten files are enough to exercise the main conversion and preprocessing paths without turning the repo into an asset dump.\n\n## What the Current Fixture Set Covers\n\n### CMYK Fixtures\n\nThe CMYK set covers:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThese are the highest-value fixtures because CMYK conversion is where incorrect assumptions are most likely.\n\nImportant rule: CMYK inputs do not convert to the naive pure RGB values contributors often expect.\n\nExamples from the real tests:\n\n- CMYK cyan does not become pure `(0, 255, 255)`\n- CMYK magenta does not become pure `(255, 0, 255)`\n- CMYK yellow does not become pure `(255, 255, 0)`\n- CMYK black does not become pure `(0, 0, 0)`\n\nThe expected values in `backend/tests/test_image_conversion_real.py` reflect real ICC-profile conversion output, and those test expectations are the current source of truth for assertion behavior.\n\n### RGB Fixtures\n\nThe RGB set verifies that already-browser-friendly color inputs do not get unintentionally altered during conversion.\n\nThose fixtures cover:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThe expectation there is preservation rather than major transformation.\n\n### Special Colorspaces\n\nThe special set currently includes:\n\n- grayscale PSD\n- Lab TIFF\n\nThese protect lesser-used but still important conversion paths.\n\n## How the Assets Are Generated\n\nThe supported entry point is:\n\n```bash\n./scripts/setup-test-images\n```\n\nThat script:\n\n- creates the test-data directory structure\n- generates raster fixtures with ImageMagick\n- generates EPS and AI fixtures with hand-crafted PostScript instead of relying on ImageMagick to produce trustworthy CMYK vector output\n- writes `metadata/manifest.json`\n- writes `backend/tests/test_data/.gitignore` so the generated artifacts do not become repository noise\n\nThe vector-generation choice is deliberate. Hand-crafted PostScript gives the tests explicit `DeviceCMYK` or `DeviceRGB` behavior that is more reliable than hoping a generic export path preserves the intended colorspace semantics.\n\n## Manifest Versus Test Assertions\n\nTreat the manifest as generated inventory metadata, not as the sole assertion source for the image-conversion tests.\n\nThe real backend assertions currently live in `backend/tests/test_image_conversion_real.py`, including:\n\n- colorspace expectations\n- color-distance tolerances\n- converter-path expectations such as preprocessor usage\n\nThat distinction matters because fixture metadata can drift if contributors update the script but forget the test semantics, or vice versa.\n\n## How the Tests Use the Assets\n\nThe main integration coverage lives in `backend/tests/test_image_conversion_real.py`.\n\nThat file:\n\n- auto-generates the fixtures through an autouse module-scoped fixture when they are missing\n- loads the generated manifest for iteration over the asset set\n- uses `pyvips` to inspect colorspace and average color values\n- verifies conversion output from `convert_image_for_viewer(...)`\n- checks preprocessable formats through `PreprocessorRegistry`\n\nThe tests are marked as integration tests because they exercise real decoding and conversion behavior rather than only mocked internals.\n\n## Supported Commands\n\nTo generate the assets explicitly:\n\n```bash\n./scripts/setup-test-images\n```\n\nTo run the real image-conversion integration suite:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -v\n```\n\nTo focus on CMYK behavior:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -k cmyk -v\n```\n\nTo pair the tests with backend coverage for the conversion service:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py --cov=app/services/image_converter\n```\n\n## Tolerances and Performance Expectations\n\nThe current suite intentionally allows some color-distance tolerance.\n\n- CMYK conversion assertions allow wider tolerance because ICC-based conversion is not a byte-for-byte identity transform\n- RGB preservation assertions use tighter thresholds because the expected result is much closer to the source color intent\n\nThe same suite also keeps a simple performance guard so tiny generated fixtures do not regress into unexpectedly slow conversions.\n\n## When to Change the Fixture Set\n\nUpdate the generated assets when:\n\n- you add support for a new preprocessable format\n- you change CMYK or colorspace handling in a way that should be locked down by a real fixture\n- you discover a real-world conversion regression that a small generated file can reproduce reliably\n\nWhen you add or change assets, update all three layers together:\n\n1. `scripts/setup-test-images`\n2. `backend/tests/test_image_conversion_real.py`\n3. the generated manifest or any related inventory description that the script emits\n\nDo not treat the assets as static binaries that should be edited by hand.\n\n## Troubleshooting\n\n### Assets Missing\n\nIf the fixtures are missing, rerun:\n\n```bash\n./scripts/setup-test-images\n```\n\nThe test module can generate them automatically, but explicit generation is usually the fastest way to confirm the local environment is healthy.\n\n### Imagemagick Missing\n\nThe generator expects ImageMagick 7 with the supported wrapper path or binary on `PATH`.\n\nIf the script reports that `magick` is missing, run the repo's supported system-dependency setup first:\n\n```bash\n./scripts/install-system-deps\n```\n\n### Color Mismatches\n\nIf color assertions change unexpectedly:\n\n- verify that the local environment still has the expected ImageMagick and ICC-profile support\n- check whether the backend conversion path changed intentionally\n- compare the actual average color output from the failing test before changing tolerances or expected values\n\nDo not update expected colors casually. CMYK expectations in particular exist to catch exactly that sort of silent behavior drift.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Image Conversion Test Assets\"\n+++\n\nSambee uses generated image fixtures to test the image-conversion and preprocessing pipeline without bloating the repository with large checked-in binaries.\n\nThese fixtures exist to verify real conversion behavior, especially around colorspace handling where naive expectations are often wrong.\n\n## Why These Assets Exist\n\nThe backend conversion pipeline has to do more than just decode files successfully.\n\n- CMYK inputs must convert into browser-safe RGB output without silent inversion or broken ICC handling\n- RGB inputs should preserve color rather than drifting during conversion\n- preprocessable vector formats such as EPS and AI need realistic fixtures, not only mocked unit tests\n- grayscale and Lab examples protect less-common conversion paths\n\nThat is why the repo includes a generated fixture workflow instead of relying only on synthetic unit-level mocks.\n\n## Where the Generated Assets Live\n\nThe generation workflow populates `backend/tests/test_data/`.\n\nCurrent layout:\n\n- `backend/tests/test_data/images/cmyk/`\n- `backend/tests/test_data/images/rgb/`\n- `backend/tests/test_data/images/special/`\n- `backend/tests/test_data/expected/`\n- `backend/tests/test_data/metadata/manifest.json`\n- `backend/tests/test_data/.gitignore`\n\nThe generated image set is intentionally small.\n\n- 4 CMYK fixtures\n- 4 RGB fixtures\n- 2 special-colorspace fixtures\n\nThose ten files are enough to exercise the main conversion and preprocessing paths without turning the repo into an asset dump.\n\n## What the Current Fixture Set Covers\n\n### CMYK Fixtures\n\nThe CMYK set covers:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThese are the highest-value fixtures because CMYK conversion is where incorrect assumptions are most likely.\n\nImportant rule: CMYK inputs do not convert to the naive pure RGB values contributors often expect.\n\nExamples from the real tests:\n\n- CMYK cyan does not become pure `(0, 255, 255)`\n- CMYK magenta does not become pure `(255, 0, 255)`\n- CMYK yellow does not become pure `(255, 255, 0)`\n- CMYK black does not become pure `(0, 0, 0)`\n\nThe expected values in `backend/tests/test_image_conversion_real.py` reflect real ICC-profile conversion output, and those test expectations are the current source of truth for assertion behavior.\n\n### RGB Fixtures\n\nThe RGB set verifies that already-browser-friendly color inputs do not get unintentionally altered during conversion.\n\nThose fixtures cover:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThe expectation there is preservation rather than major transformation.\n\n### Special Colorspaces\n\nThe special set currently includes:\n\n- grayscale PSD\n- Lab TIFF\n\nThese protect lesser-used but still important conversion paths.\n\n## How the Assets Are Generated\n\nThe supported entry point is:\n\n```bash\n./scripts/setup-test-images\n```\n\nThat script:\n\n- creates the test-data directory structure\n- generates raster fixtures with ImageMagick\n- generates EPS and AI fixtures with hand-crafted PostScript instead of relying on ImageMagick to produce trustworthy CMYK vector output\n- writes `metadata/manifest.json`\n- writes `backend/tests/test_data/.gitignore` so the generated artifacts do not become repository noise\n\nThe vector-generation choice is deliberate. Hand-crafted PostScript gives the tests explicit `DeviceCMYK` or `DeviceRGB` behavior that is more reliable than hoping a generic export path preserves the intended colorspace semantics.\n\n## Manifest Versus Test Assertions\n\nTreat the manifest as generated inventory metadata, not as the sole assertion source for the image-conversion tests.\n\nThe real backend assertions currently live in `backend/tests/test_image_conversion_real.py`, including:\n\n- colorspace expectations\n- color-distance tolerances\n- converter-path expectations such as preprocessor usage\n\nThat distinction matters because fixture metadata can drift if contributors update the script but forget the test semantics, or vice versa.\n\n## How the Tests Use the Assets\n\nThe main integration coverage lives in `backend/tests/test_image_conversion_real.py`.\n\nThat file:\n\n- auto-generates the fixtures through an autouse module-scoped fixture when they are missing\n- loads the generated manifest for iteration over the asset set\n- uses `pyvips` to inspect colorspace and average color values\n- verifies conversion output from `convert_image_for_viewer(...)`\n- checks preprocessable formats through `PreprocessorRegistry`\n\nThe tests are marked as integration tests because they exercise real decoding and conversion behavior rather than only mocked internals.\n\n## Supported Commands\n\nTo generate the assets explicitly:\n\n```bash\n./scripts/setup-test-images\n```\n\nTo run the real image-conversion integration suite:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -v\n```\n\nTo focus on CMYK behavior:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -k cmyk -v\n```\n\nTo pair the tests with backend coverage for the conversion service:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py --cov=app/services/image_converter\n```\n\n## Tolerances and Performance Expectations\n\nThe current suite intentionally allows some color-distance tolerance.\n\n- CMYK conversion assertions allow wider tolerance because ICC-based conversion is not a byte-for-byte identity transform\n- RGB preservation assertions use tighter thresholds because the expected result is much closer to the source color intent\n\nThe same suite also keeps a simple performance guard so tiny generated fixtures do not regress into unexpectedly slow conversions.\n\n## When to Change the Fixture Set\n\nUpdate the generated assets when:\n\n- you add support for a new preprocessable format\n- you change CMYK or colorspace handling in a way that should be locked down by a real fixture\n- you discover a real-world conversion regression that a small generated file can reproduce reliably\n\nWhen you add or change assets, update all three layers together:\n\n1. `scripts/setup-test-images`\n2. `backend/tests/test_image_conversion_real.py`\n3. the generated manifest or any related inventory description that the script emits\n\nDo not treat the assets as static binaries that should be edited by hand.\n\n## Troubleshooting\n\n### Assets Missing\n\nIf the fixtures are missing, rerun:\n\n```bash\n./scripts/setup-test-images\n```\n\nThe test module can generate them automatically, but explicit generation is usually the fastest way to confirm the local environment is healthy.\n\n### Imagemagick Missing\n\nThe generator expects ImageMagick 7 with the supported wrapper path or binary on `PATH`.\n\nIf the script reports that `magick` is missing, run the repo's supported system-dependency setup first:\n\n```bash\n./scripts/install-system-deps\n```\n\n### Color Mismatches\n\nIf color assertions change unexpectedly:\n\n- verify that the local environment still has the expected ImageMagick and ICC-profile support\n- check whether the backend conversion path changed intentionally\n- compare the actual average color output from the failing test before changing tolerances or expected values\n\nDo not update expected colors casually. CMYK expectations in particular exist to catch exactly that sort of silent behavior drift.\n", "0.8": "+++\ntitle = \"Image Conversion Test Assets\"\n+++\n\nSambee uses generated image fixtures to test the image-conversion and preprocessing pipeline without bloating the repository with large checked-in binaries.\n\nThese fixtures exist to verify real conversion behavior, especially around colorspace handling where naive expectations are often wrong.\n\n## Why These Assets Exist\n\nThe backend conversion pipeline has to do more than just decode files successfully.\n\n- CMYK inputs must convert into browser-safe RGB output without silent inversion or broken ICC handling\n- RGB inputs should preserve color rather than drifting during conversion\n- preprocessable vector formats such as EPS and AI need realistic fixtures, not only mocked unit tests\n- grayscale and Lab examples protect less-common conversion paths\n\nThat is why the repo includes a generated fixture workflow instead of relying only on synthetic unit-level mocks.\n\n## Where the Generated Assets Live\n\nThe generation workflow populates `backend/tests/test_data/`.\n\nCurrent layout:\n\n- `backend/tests/test_data/images/cmyk/`\n- `backend/tests/test_data/images/rgb/`\n- `backend/tests/test_data/images/special/`\n- `backend/tests/test_data/expected/`\n- `backend/tests/test_data/metadata/manifest.json`\n- `backend/tests/test_data/.gitignore`\n\nThe generated image set is intentionally small.\n\n- 4 CMYK fixtures\n- 4 RGB fixtures\n- 2 special-colorspace fixtures\n\nThose ten files are enough to exercise the main conversion and preprocessing paths without turning the repo into an asset dump.\n\n## What the Current Fixture Set Covers\n\n### CMYK Fixtures\n\nThe CMYK set covers:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThese are the highest-value fixtures because CMYK conversion is where incorrect assumptions are most likely.\n\nImportant rule: CMYK inputs do not convert to the naive pure RGB values contributors often expect.\n\nExamples from the real tests:\n\n- CMYK cyan does not become pure `(0, 255, 255)`\n- CMYK magenta does not become pure `(255, 0, 255)`\n- CMYK yellow does not become pure `(255, 255, 0)`\n- CMYK black does not become pure `(0, 0, 0)`\n\nThe expected values in `backend/tests/test_image_conversion_real.py` reflect real ICC-profile conversion output, and those test expectations are the current source of truth for assertion behavior.\n\n### RGB Fixtures\n\nThe RGB set verifies that already-browser-friendly color inputs do not get unintentionally altered during conversion.\n\nThose fixtures cover:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThe expectation there is preservation rather than major transformation.\n\n### Special Colorspaces\n\nThe special set currently includes:\n\n- grayscale PSD\n- Lab TIFF\n\nThese protect lesser-used but still important conversion paths.\n\n## How the Assets Are Generated\n\nThe supported entry point is:\n\n```bash\n./scripts/setup-test-images\n```\n\nThat script:\n\n- creates the test-data directory structure\n- generates raster fixtures with ImageMagick\n- generates EPS and AI fixtures with hand-crafted PostScript instead of relying on ImageMagick to produce trustworthy CMYK vector output\n- writes `metadata/manifest.json`\n- writes `backend/tests/test_data/.gitignore` so the generated artifacts do not become repository noise\n\nThe vector-generation choice is deliberate. Hand-crafted PostScript gives the tests explicit `DeviceCMYK` or `DeviceRGB` behavior that is more reliable than hoping a generic export path preserves the intended colorspace semantics.\n\n## Manifest Versus Test Assertions\n\nTreat the manifest as generated inventory metadata, not as the sole assertion source for the image-conversion tests.\n\nThe real backend assertions currently live in `backend/tests/test_image_conversion_real.py`, including:\n\n- colorspace expectations\n- color-distance tolerances\n- converter-path expectations such as preprocessor usage\n\nThat distinction matters because fixture metadata can drift if contributors update the script but forget the test semantics, or vice versa.\n\n## How the Tests Use the Assets\n\nThe main integration coverage lives in `backend/tests/test_image_conversion_real.py`.\n\nThat file:\n\n- auto-generates the fixtures through an autouse module-scoped fixture when they are missing\n- loads the generated manifest for iteration over the asset set\n- uses `pyvips` to inspect colorspace and average color values\n- verifies conversion output from `convert_image_for_viewer(...)`\n- checks preprocessable formats through `PreprocessorRegistry`\n\nThe tests are marked as integration tests because they exercise real decoding and conversion behavior rather than only mocked internals.\n\n## Supported Commands\n\nTo generate the assets explicitly:\n\n```bash\n./scripts/setup-test-images\n```\n\nTo run the real image-conversion integration suite:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -v\n```\n\nTo focus on CMYK behavior:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -k cmyk -v\n```\n\nTo pair the tests with backend coverage for the conversion service:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py --cov=app/services/image_converter\n```\n\n## Tolerances and Performance Expectations\n\nThe current suite intentionally allows some color-distance tolerance.\n\n- CMYK conversion assertions allow wider tolerance because ICC-based conversion is not a byte-for-byte identity transform\n- RGB preservation assertions use tighter thresholds because the expected result is much closer to the source color intent\n\nThe same suite also keeps a simple performance guard so tiny generated fixtures do not regress into unexpectedly slow conversions.\n\n## When to Change the Fixture Set\n\nUpdate the generated assets when:\n\n- you add support for a new preprocessable format\n- you change CMYK or colorspace handling in a way that should be locked down by a real fixture\n- you discover a real-world conversion regression that a small generated file can reproduce reliably\n\nWhen you add or change assets, update all three layers together:\n\n1. `scripts/setup-test-images`\n2. `backend/tests/test_image_conversion_real.py`\n3. the generated manifest or any related inventory description that the script emits\n\nDo not treat the assets as static binaries that should be edited by hand.\n\n## Troubleshooting\n\n### Assets Missing\n\nIf the fixtures are missing, rerun:\n\n```bash\n./scripts/setup-test-images\n```\n\nThe test module can generate them automatically, but explicit generation is usually the fastest way to confirm the local environment is healthy.\n\n### Imagemagick Missing\n\nThe generator expects ImageMagick 7 with the supported wrapper path or binary on `PATH`.\n\nIf the script reports that `magick` is missing, run the repo's supported system-dependency setup first:\n\n```bash\n./scripts/install-system-deps\n```\n\n### Color Mismatches\n\nIf color assertions change unexpectedly:\n\n- verify that the local environment still has the expected ImageMagick and ICC-profile support\n- check whether the backend conversion path changed intentionally\n- compare the actual average color output from the failing test before changing tolerances or expected values\n\nDo not update expected colors casually. CMYK expectations in particular exist to catch exactly that sort of silent behavior drift.\n", "0.9": "+++\ntitle = \"Image Conversion Test Assets\"\n+++\n\nSambee uses generated image fixtures to test the image-conversion and preprocessing pipeline without bloating the repository with large checked-in binaries.\n\nThese fixtures exist to verify real conversion behavior, especially around colorspace handling where naive expectations are often wrong.\n\n## Why These Assets Exist\n\nThe backend conversion pipeline has to do more than just decode files successfully.\n\n- CMYK inputs must convert into browser-safe RGB output without silent inversion or broken ICC handling\n- RGB inputs should preserve color rather than drifting during conversion\n- preprocessable vector formats such as EPS and AI need realistic fixtures, not only mocked unit tests\n- grayscale and Lab examples protect less-common conversion paths\n\nThat is why the repo includes a generated fixture workflow instead of relying only on synthetic unit-level mocks.\n\n## Where the Generated Assets Live\n\nThe generation workflow populates `backend/tests/test_data/`.\n\nCurrent layout:\n\n- `backend/tests/test_data/images/cmyk/`\n- `backend/tests/test_data/images/rgb/`\n- `backend/tests/test_data/images/special/`\n- `backend/tests/test_data/expected/`\n- `backend/tests/test_data/metadata/manifest.json`\n- `backend/tests/test_data/.gitignore`\n\nThe generated image set is intentionally small.\n\n- 4 CMYK fixtures\n- 4 RGB fixtures\n- 2 special-colorspace fixtures\n\nThose ten files are enough to exercise the main conversion and preprocessing paths without turning the repo into an asset dump.\n\n## What the Current Fixture Set Covers\n\n### CMYK Fixtures\n\nThe CMYK set covers:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThese are the highest-value fixtures because CMYK conversion is where incorrect assumptions are most likely.\n\nImportant rule: CMYK inputs do not convert to the naive pure RGB values contributors often expect.\n\nExamples from the real tests:\n\n- CMYK cyan does not become pure `(0, 255, 255)`\n- CMYK magenta does not become pure `(255, 0, 255)`\n- CMYK yellow does not become pure `(255, 255, 0)`\n- CMYK black does not become pure `(0, 0, 0)`\n\nThe expected values in `backend/tests/test_image_conversion_real.py` reflect real ICC-profile conversion output, and those test expectations are the current source of truth for assertion behavior.\n\n### RGB Fixtures\n\nThe RGB set verifies that already-browser-friendly color inputs do not get unintentionally altered during conversion.\n\nThose fixtures cover:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThe expectation there is preservation rather than major transformation.\n\n### Special Colorspaces\n\nThe special set currently includes:\n\n- grayscale PSD\n- Lab TIFF\n\nThese protect lesser-used but still important conversion paths.\n\n## How the Assets Are Generated\n\nThe supported entry point is:\n\n```bash\n./scripts/setup-test-images\n```\n\nThat script:\n\n- creates the test-data directory structure\n- generates raster fixtures with ImageMagick\n- generates EPS and AI fixtures with hand-crafted PostScript instead of relying on ImageMagick to produce trustworthy CMYK vector output\n- writes `metadata/manifest.json`\n- writes `backend/tests/test_data/.gitignore` so the generated artifacts do not become repository noise\n\nThe vector-generation choice is deliberate. Hand-crafted PostScript gives the tests explicit `DeviceCMYK` or `DeviceRGB` behavior that is more reliable than hoping a generic export path preserves the intended colorspace semantics.\n\n## Manifest Versus Test Assertions\n\nTreat the manifest as generated inventory metadata, not as the sole assertion source for the image-conversion tests.\n\nThe real backend assertions currently live in `backend/tests/test_image_conversion_real.py`, including:\n\n- colorspace expectations\n- color-distance tolerances\n- converter-path expectations such as preprocessor usage\n\nThat distinction matters because fixture metadata can drift if contributors update the script but forget the test semantics, or vice versa.\n\n## How the Tests Use the Assets\n\nThe main integration coverage lives in `backend/tests/test_image_conversion_real.py`.\n\nThat file:\n\n- auto-generates the fixtures through an autouse module-scoped fixture when they are missing\n- loads the generated manifest for iteration over the asset set\n- uses `pyvips` to inspect colorspace and average color values\n- verifies conversion output from `convert_image_for_viewer(...)`\n- checks preprocessable formats through `PreprocessorRegistry`\n\nThe tests are marked as integration tests because they exercise real decoding and conversion behavior rather than only mocked internals.\n\n## Supported Commands\n\nTo generate the assets explicitly:\n\n```bash\n./scripts/setup-test-images\n```\n\nTo run the real image-conversion integration suite:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -v\n```\n\nTo focus on CMYK behavior:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -k cmyk -v\n```\n\nTo pair the tests with backend coverage for the conversion service:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py --cov=app/services/image_converter\n```\n\n## Tolerances and Performance Expectations\n\nThe current suite intentionally allows some color-distance tolerance.\n\n- CMYK conversion assertions allow wider tolerance because ICC-based conversion is not a byte-for-byte identity transform\n- RGB preservation assertions use tighter thresholds because the expected result is much closer to the source color intent\n\nThe same suite also keeps a simple performance guard so tiny generated fixtures do not regress into unexpectedly slow conversions.\n\n## When to Change the Fixture Set\n\nUpdate the generated assets when:\n\n- you add support for a new preprocessable format\n- you change CMYK or colorspace handling in a way that should be locked down by a real fixture\n- you discover a real-world conversion regression that a small generated file can reproduce reliably\n\nWhen you add or change assets, update all three layers together:\n\n1. `scripts/setup-test-images`\n2. `backend/tests/test_image_conversion_real.py`\n3. the generated manifest or any related inventory description that the script emits\n\nDo not treat the assets as static binaries that should be edited by hand.\n\n## Troubleshooting\n\n### Assets Missing\n\nIf the fixtures are missing, rerun:\n\n```bash\n./scripts/setup-test-images\n```\n\nThe test module can generate them automatically, but explicit generation is usually the fastest way to confirm the local environment is healthy.\n\n### Imagemagick Missing\n\nThe generator expects ImageMagick 7 with the supported wrapper path or binary on `PATH`.\n\nIf the script reports that `magick` is missing, run the repo's supported system-dependency setup first:\n\n```bash\n./scripts/install-system-deps\n```\n\n### Color Mismatches\n\nIf color assertions change unexpectedly:\n\n- verify that the local environment still has the expected ImageMagick and ICC-profile support\n- check whether the backend conversion path changed intentionally\n- compare the actual average color output from the failing test before changing tolerances or expected values\n\nDo not update expected colors casually. CMYK expectations in particular exist to catch exactly that sort of silent behavior drift.\n", "1.0": "+++\ntitle = \"Image Conversion Test Assets\"\n+++\n\nSambee uses generated image fixtures to test the image-conversion and preprocessing pipeline without bloating the repository with large checked-in binaries.\n\nThese fixtures exist to verify real conversion behavior, especially around colorspace handling where naive expectations are often wrong.\n\n## Why These Assets Exist\n\nThe backend conversion pipeline has to do more than just decode files successfully.\n\n- CMYK inputs must convert into browser-safe RGB output without silent inversion or broken ICC handling\n- RGB inputs should preserve color rather than drifting during conversion\n- preprocessable vector formats such as EPS and AI need realistic fixtures, not only mocked unit tests\n- grayscale and Lab examples protect less-common conversion paths\n\nThat is why the repo includes a generated fixture workflow instead of relying only on synthetic unit-level mocks.\n\n## Where the Generated Assets Live\n\nThe generation workflow populates `backend/tests/test_data/`.\n\nCurrent layout:\n\n- `backend/tests/test_data/images/cmyk/`\n- `backend/tests/test_data/images/rgb/`\n- `backend/tests/test_data/images/special/`\n- `backend/tests/test_data/expected/`\n- `backend/tests/test_data/metadata/manifest.json`\n- `backend/tests/test_data/.gitignore`\n\nThe generated image set is intentionally small.\n\n- 4 CMYK fixtures\n- 4 RGB fixtures\n- 2 special-colorspace fixtures\n\nThose ten files are enough to exercise the main conversion and preprocessing paths without turning the repo into an asset dump.\n\n## What the Current Fixture Set Covers\n\n### CMYK Fixtures\n\nThe CMYK set covers:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThese are the highest-value fixtures because CMYK conversion is where incorrect assumptions are most likely.\n\nImportant rule: CMYK inputs do not convert to the naive pure RGB values contributors often expect.\n\nExamples from the real tests:\n\n- CMYK cyan does not become pure `(0, 255, 255)`\n- CMYK magenta does not become pure `(255, 0, 255)`\n- CMYK yellow does not become pure `(255, 255, 0)`\n- CMYK black does not become pure `(0, 0, 0)`\n\nThe expected values in `backend/tests/test_image_conversion_real.py` reflect real ICC-profile conversion output, and those test expectations are the current source of truth for assertion behavior.\n\n### RGB Fixtures\n\nThe RGB set verifies that already-browser-friendly color inputs do not get unintentionally altered during conversion.\n\nThose fixtures cover:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThe expectation there is preservation rather than major transformation.\n\n### Special Colorspaces\n\nThe special set currently includes:\n\n- grayscale PSD\n- Lab TIFF\n\nThese protect lesser-used but still important conversion paths.\n\n## How the Assets Are Generated\n\nThe supported entry point is:\n\n```bash\n./scripts/setup-test-images\n```\n\nThat script:\n\n- creates the test-data directory structure\n- generates raster fixtures with ImageMagick\n- generates EPS and AI fixtures with hand-crafted PostScript instead of relying on ImageMagick to produce trustworthy CMYK vector output\n- writes `metadata/manifest.json`\n- writes `backend/tests/test_data/.gitignore` so the generated artifacts do not become repository noise\n\nThe vector-generation choice is deliberate. Hand-crafted PostScript gives the tests explicit `DeviceCMYK` or `DeviceRGB` behavior that is more reliable than hoping a generic export path preserves the intended colorspace semantics.\n\n## Manifest Versus Test Assertions\n\nTreat the manifest as generated inventory metadata, not as the sole assertion source for the image-conversion tests.\n\nThe real backend assertions currently live in `backend/tests/test_image_conversion_real.py`, including:\n\n- colorspace expectations\n- color-distance tolerances\n- converter-path expectations such as preprocessor usage\n\nThat distinction matters because fixture metadata can drift if contributors update the script but forget the test semantics, or vice versa.\n\n## How the Tests Use the Assets\n\nThe main integration coverage lives in `backend/tests/test_image_conversion_real.py`.\n\nThat file:\n\n- auto-generates the fixtures through an autouse module-scoped fixture when they are missing\n- loads the generated manifest for iteration over the asset set\n- uses `pyvips` to inspect colorspace and average color values\n- verifies conversion output from `convert_image_for_viewer(...)`\n- checks preprocessable formats through `PreprocessorRegistry`\n\nThe tests are marked as integration tests because they exercise real decoding and conversion behavior rather than only mocked internals.\n\n## Supported Commands\n\nTo generate the assets explicitly:\n\n```bash\n./scripts/setup-test-images\n```\n\nTo run the real image-conversion integration suite:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -v\n```\n\nTo focus on CMYK behavior:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -k cmyk -v\n```\n\nTo pair the tests with backend coverage for the conversion service:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py --cov=app/services/image_converter\n```\n\n## Tolerances and Performance Expectations\n\nThe current suite intentionally allows some color-distance tolerance.\n\n- CMYK conversion assertions allow wider tolerance because ICC-based conversion is not a byte-for-byte identity transform\n- RGB preservation assertions use tighter thresholds because the expected result is much closer to the source color intent\n\nThe same suite also keeps a simple performance guard so tiny generated fixtures do not regress into unexpectedly slow conversions.\n\n## When to Change the Fixture Set\n\nUpdate the generated assets when:\n\n- you add support for a new preprocessable format\n- you change CMYK or colorspace handling in a way that should be locked down by a real fixture\n- you discover a real-world conversion regression that a small generated file can reproduce reliably\n\nWhen you add or change assets, update all three layers together:\n\n1. `scripts/setup-test-images`\n2. `backend/tests/test_image_conversion_real.py`\n3. the generated manifest or any related inventory description that the script emits\n\nDo not treat the assets as static binaries that should be edited by hand.\n\n## Troubleshooting\n\n### Assets Missing\n\nIf the fixtures are missing, rerun:\n\n```bash\n./scripts/setup-test-images\n```\n\nThe test module can generate them automatically, but explicit generation is usually the fastest way to confirm the local environment is healthy.\n\n### Imagemagick Missing\n\nThe generator expects ImageMagick 7 with the supported wrapper path or binary on `PATH`.\n\nIf the script reports that `magick` is missing, run the repo's supported system-dependency setup first:\n\n```bash\n./scripts/install-system-deps\n```\n\n### Color Mismatches\n\nIf color assertions change unexpectedly:\n\n- verify that the local environment still has the expected ImageMagick and ICC-profile support\n- check whether the backend conversion path changed intentionally\n- compare the actual average color output from the failing test before changing tolerances or expected values\n\nDo not update expected colors casually. CMYK expectations in particular exist to catch exactly that sort of silent behavior drift.\n", "2.0": "+++\ntitle = \"Image Conversion Test Assets\"\n+++\n\nSambee uses generated image fixtures to test the image-conversion and preprocessing pipeline without bloating the repository with large checked-in binaries.\n\nThese fixtures exist to verify real conversion behavior, especially around colorspace handling where naive expectations are often wrong.\n\n## Why These Assets Exist\n\nThe backend conversion pipeline has to do more than just decode files successfully.\n\n- CMYK inputs must convert into browser-safe RGB output without silent inversion or broken ICC handling\n- RGB inputs should preserve color rather than drifting during conversion\n- preprocessable vector formats such as EPS and AI need realistic fixtures, not only mocked unit tests\n- grayscale and Lab examples protect less-common conversion paths\n\nThat is why the repo includes a generated fixture workflow instead of relying only on synthetic unit-level mocks.\n\n## Where the Generated Assets Live\n\nThe generation workflow populates `backend/tests/test_data/`.\n\nCurrent layout:\n\n- `backend/tests/test_data/images/cmyk/`\n- `backend/tests/test_data/images/rgb/`\n- `backend/tests/test_data/images/special/`\n- `backend/tests/test_data/expected/`\n- `backend/tests/test_data/metadata/manifest.json`\n- `backend/tests/test_data/.gitignore`\n\nThe generated image set is intentionally small.\n\n- 4 CMYK fixtures\n- 4 RGB fixtures\n- 2 special-colorspace fixtures\n\nThose ten files are enough to exercise the main conversion and preprocessing paths without turning the repo into an asset dump.\n\n## What the Current Fixture Set Covers\n\n### CMYK Fixtures\n\nThe CMYK set covers:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThese are the highest-value fixtures because CMYK conversion is where incorrect assumptions are most likely.\n\nImportant rule: CMYK inputs do not convert to the naive pure RGB values contributors often expect.\n\nExamples from the real tests:\n\n- CMYK cyan does not become pure `(0, 255, 255)`\n- CMYK magenta does not become pure `(255, 0, 255)`\n- CMYK yellow does not become pure `(255, 255, 0)`\n- CMYK black does not become pure `(0, 0, 0)`\n\nThe expected values in `backend/tests/test_image_conversion_real.py` reflect real ICC-profile conversion output, and those test expectations are the current source of truth for assertion behavior.\n\n### RGB Fixtures\n\nThe RGB set verifies that already-browser-friendly color inputs do not get unintentionally altered during conversion.\n\nThose fixtures cover:\n\n- PSD\n- TIFF\n- EPS\n- AI\n\nThe expectation there is preservation rather than major transformation.\n\n### Special Colorspaces\n\nThe special set currently includes:\n\n- grayscale PSD\n- Lab TIFF\n\nThese protect lesser-used but still important conversion paths.\n\n## How the Assets Are Generated\n\nThe supported entry point is:\n\n```bash\n./scripts/setup-test-images\n```\n\nThat script:\n\n- creates the test-data directory structure\n- generates raster fixtures with ImageMagick\n- generates EPS and AI fixtures with hand-crafted PostScript instead of relying on ImageMagick to produce trustworthy CMYK vector output\n- writes `metadata/manifest.json`\n- writes `backend/tests/test_data/.gitignore` so the generated artifacts do not become repository noise\n\nThe vector-generation choice is deliberate. Hand-crafted PostScript gives the tests explicit `DeviceCMYK` or `DeviceRGB` behavior that is more reliable than hoping a generic export path preserves the intended colorspace semantics.\n\n## Manifest Versus Test Assertions\n\nTreat the manifest as generated inventory metadata, not as the sole assertion source for the image-conversion tests.\n\nThe real backend assertions currently live in `backend/tests/test_image_conversion_real.py`, including:\n\n- colorspace expectations\n- color-distance tolerances\n- converter-path expectations such as preprocessor usage\n\nThat distinction matters because fixture metadata can drift if contributors update the script but forget the test semantics, or vice versa.\n\n## How the Tests Use the Assets\n\nThe main integration coverage lives in `backend/tests/test_image_conversion_real.py`.\n\nThat file:\n\n- auto-generates the fixtures through an autouse module-scoped fixture when they are missing\n- loads the generated manifest for iteration over the asset set\n- uses `pyvips` to inspect colorspace and average color values\n- verifies conversion output from `convert_image_for_viewer(...)`\n- checks preprocessable formats through `PreprocessorRegistry`\n\nThe tests are marked as integration tests because they exercise real decoding and conversion behavior rather than only mocked internals.\n\n## Supported Commands\n\nTo generate the assets explicitly:\n\n```bash\n./scripts/setup-test-images\n```\n\nTo run the real image-conversion integration suite:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -v\n```\n\nTo focus on CMYK behavior:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py -k cmyk -v\n```\n\nTo pair the tests with backend coverage for the conversion service:\n\n```bash\ncd backend \u0026\u0026 pytest tests/test_image_conversion_real.py --cov=app/services/image_converter\n```\n\n## Tolerances and Performance Expectations\n\nThe current suite intentionally allows some color-distance tolerance.\n\n- CMYK conversion assertions allow wider tolerance because ICC-based conversion is not a byte-for-byte identity transform\n- RGB preservation assertions use tighter thresholds because the expected result is much closer to the source color intent\n\nThe same suite also keeps a simple performance guard so tiny generated fixtures do not regress into unexpectedly slow conversions.\n\n## When to Change the Fixture Set\n\nUpdate the generated assets when:\n\n- you add support for a new preprocessable format\n- you change CMYK or colorspace handling in a way that should be locked down by a real fixture\n- you discover a real-world conversion regression that a small generated file can reproduce reliably\n\nWhen you add or change assets, update all three layers together:\n\n1. `scripts/setup-test-images`\n2. `backend/tests/test_image_conversion_real.py`\n3. the generated manifest or any related inventory description that the script emits\n\nDo not treat the assets as static binaries that should be edited by hand.\n\n## Troubleshooting\n\n### Assets Missing\n\nIf the fixtures are missing, rerun:\n\n```bash\n./scripts/setup-test-images\n```\n\nThe test module can generate them automatically, but explicit generation is usually the fastest way to confirm the local environment is healthy.\n\n### Imagemagick Missing\n\nThe generator expects ImageMagick 7 with the supported wrapper path or binary on `PATH`.\n\nIf the script reports that `magick` is missing, run the repo's supported system-dependency setup first:\n\n```bash\n./scripts/install-system-deps\n```\n\n### Color Mismatches\n\nIf color assertions change unexpectedly:\n\n- verify that the local environment still has the expected ImageMagick and ICC-profile support\n- check whether the backend conversion path changed intentionally\n- compare the actual average color output from the failing test before changing tolerances or expected values\n\nDo not update expected colors casually. CMYK expectations in particular exist to catch exactly that sort of silent behavior drift.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/testing-and-quality-gates/ci-workflows-and-repository-automation", "parent_id": "section:developer-guide/testing-and-quality-gates", "depth": 2, "kind": "page", "label": "ci-workflows-and-repository-automation", "title": "Ci Workflows And Repository Automation", "path": "developer-guide/testing-and-quality-gates/ci-workflows-and-repository-automation", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "branched", "source_version": "0.7", "diff_added": 26, "diff_removed": 2}, "0.9": {"state": "branched", "source_version": "0.8", "diff_added": 15, "diff_removed": 1}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "branched", "source_version": "0.9", "diff_added": 43, "diff_removed": 29}}, "content_versions": {"0.7": "+++\ntitle = \"CI Workflows and Repository Automation\"\n+++\n\nUse this page to understand the GitHub Actions workflows contributors hit most often and to keep the workflow list grouped predictably in the GitHub UI.\n\n## Naming Convention\n\nGitHub lists workflows by the top-level `name` field.\n\nSambee groups workflow display names by operational purpose using `Area: Subject`.\n\nCurrent workflow groups are:\n\n- `CI`.\n- `Release`.\n- `Deploy`.\n- `Security`.\n- `Admin`.\n\nKeep new names short, stable, and grouped by what the workflow does rather than by how it is triggered.\n\n## Workflow Map\n\n| Display name | File | Role |\n|---|---|---|\n| `CI: Test` | `.github/workflows/test.yml` | Runs the main backend, frontend, and companion validation suites. |\n| `CI: Lint` | `.github/workflows/lint.yml` | Runs repository lint and formatting checks across backend, frontend, and companion. |\n| `CI: Check Backend Lockfiles` | `.github/workflows/check-backend-lockfiles.yml` | Verifies that committed backend lockfiles still match the reviewed requirement sources. |\n| `CI: Validate Docker Image` | `.github/workflows/docker-image-validate.yml` | Builds and smoke-tests the production container image on pull requests, pushes, and manual runs. |\n| `Release: Publish Docker Image` | `.github/workflows/docker-image-publish.yml` | Promotes an existing preview candidate onto release tags and the `stable` or `beta` channel, then signs the digest. |\n| `Release: Create Docker Image` | `.github/workflows/docker-image-preview-publish.yml` | Builds, validates, publishes, and signs a new preview image, forcing a fresh Debian package-layer rebuild for that run before moving the `test` channel tag. |\n| `Maintenance: Backfill Docker Release Tags` | `.github/workflows/docker-image-backfill.yml` | Reattaches release tags and release-channel aliases to an already published candidate digest for an existing release. |\n| `Maintenance: Clean Up Docker Package Versions` | `.github/workflows/docker-image-cleanup.yml` | Removes unprotected SHA-tagged preview GHCR package versions, prunes stale signature artifacts, and deletes unreferenced untagged package versions while preserving release-tagged and channel-protected versions including `test`. |\n| `Release: Build Companion Artifact` | `.github/workflows/build-companion.yml` | Builds companion release artifacts for a new unique version or prerelease candidate in the public distribution repository. |\n| `Release: Promote Companion Release` | `.github/workflows/promote-companion-release.yml` | Moves an existing companion release onto one or more update channels. |\n| `Deploy: Website` | `.github/workflows/website-deploy.yml` | Builds the website and deploys `website/public/` to Cloudflare Pages. |\n| `Security: Dependency Audit` | `.github/workflows/dependency-security.yml` | Runs scheduled and manual dependency vulnerability audits. |\n| `Security: Docker Image Scan` | `.github/workflows/docker-image-security-scan.yml` | Builds the current main image, forces a fresh Debian package-layer rebuild for that run, and scans it for newly disclosed vulnerabilities. |\n| `Admin: Sync Labels` | `.github/workflows/sync-labels.yml` | Synchronizes repository labels from `.github/labels.yml` without deleting unmanaged labels. |\n\nGitHub also shows repository-level features such as `Dependabot updates` and `Dependency graph`.\n\nThose are not repository workflows, so their display names are not controlled by these YAML files.\n\n## CI: Test\n\n`CI: Test` is the main validation workflow for pushes to `main`, pull requests against `main`, and manual dispatch.\n\nIt first detects which top-level product areas changed, then fans out only the relevant jobs for:\n\n- backend\n- frontend\n- companion\n\nManual dispatch runs all three areas.\n\nThe workflow ends with a single gate job so branch protection can depend on one stable required check instead of a changing set of per-area jobs.\n\nIn the backend job, regular tests run under `pytest-xdist` for throughput, while `@performance` tests run in a separate serial pass so wall-clock assertions are not distorted by parallel worker contention.\n\n### Caching Model\n\nThe test workflow uses layered caching to reduce repeated setup work while keeping dependency inputs explicit.\n\nCurrent cache layers include:\n\n- `backend/.venv` caching keyed by the resolved backend requirement files and Python version.\n- `backend/.mypy_cache` caching keyed by backend Python source changes.\n- `actions/setup-node` npm download caching for frontend and companion jobs.\n- `frontend/node_modules` caching keyed by `frontend/package-lock.json`.\n- Rust build caching for `companion/src-tauri`.\n\nTreat those cache keys as reviewed dependency inputs, not as disposable generated noise.\n\nWhen dependency manifests or lockfiles change, commit the corresponding lockfile updates in the same pull request so cache invalidation and dependency review stay aligned.\n\n### Local Parity\n\nFor fast local iteration, use `./scripts/test`.\n\nWhen you want a closer CI-style pass, run the per-subsystem checks from [Test Strategy Overview](../test-strategy-overview/) and keep lockfile-driven installs intact.\n\n## CI: Lint\n\n`CI: Lint` applies the same change-detection pattern, then runs the repository's static checks for only the affected areas.\n\nCurrent coverage includes:\n\n- backend Ruff checks and formatting validation.\n- frontend Biome validation.\n- companion Clippy, Rustfmt, and Biome validation.\n\nThe workflow also ends with one gate job so branch protection can depend on a stable result.\n\n## Runner Distro Policy\n\nSambee does not require every GitHub Actions job to run on the same base distro.\n\nInstead, the rule is:\n\n- jobs that validate production-like runtime behavior or install native runtime dependencies should follow the same Debian family used by the production image and the dev container\n- jobs that only run language-level checks, dependency audits, repository automation, or other host-agnostic validation can stay on `ubuntu-latest`\n\nCurrent Debian-family jobs include:\n\n- the backend job in `CI: Test`\n- the `validate-tests` job in `Release: Create Docker Image`\n\nThose jobs run inside the pinned `python:3.13.12-slim` container because `scripts/install-system-deps` now requires distro-provided ImageMagick 7, while the default Ubuntu GitHub-hosted runner image still resolves `imagemagick` to ImageMagick 6.\n\nCurrent jobs that intentionally remain on `ubuntu-latest` include:\n\n- change-detection, label-sync, and website deployment workflows\n- pure Python lint, lockfile freshness, and dependency-audit workflows\n- frontend-only and companion-only validation workflows\n- Docker build, smoke-test, and vulnerability-scan workflows, where the distro-sensitive logic runs inside the built image rather than on the host runner\n\nWhen adding or changing a workflow, treat runner distro as part of the test contract whenever a job installs OS packages or validates native behavior.\n\n## CI: Check Backend Lockfiles\n\n`CI: Check Backend Lockfiles` protects the reviewed Python dependency workflow.\n\nIt runs `scripts/refresh-backend-lockfiles --check` on pushes, pull requests, and manual runs that touch backend requirement inputs, generated lockfiles, or the refresh script itself.\n\nUse this as the fast failure signal when requirement files and generated lockfiles drift apart.\n\nFor the broader dependency-update workflow, use [Dependency Update Workflow](../release-and-versioning/dependency-update-workflow/).\n\n## Admin: Sync Labels\n\n`Admin: Sync Labels` keeps repository labels aligned with `.github/labels.yml`.\n\nIt is intentionally conservative.\n\n- Dependabot-related labels should stay declared in `.github/labels.yml`.\n- The workflow uses `skip-delete: true`, so labels not declared there are left alone.\n\nThat keeps automation-owned labels deterministic without forcing the repository to delete every manually created label.\n\n## Related Workflow Docs\n\nUse the more specific pages for the workflows that have dedicated operational guidance:\n\n- [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/)\n- [Docker Release Overview](../../release-and-versioning/docker-release-overview/)\n- [Companion Release Overview](../../release-and-versioning/companion-release-overview/)\n- [Set Up Cloudflare Pages Publishing](../../../website-dev-guide/setup-and-operations/set-up-cloudflare-pages-publishing/)\n\n", "0.8": "+++\ntitle = \"CI Workflows and Repository Automation\"\n+++\n\nUse this page to understand the GitHub Actions workflows contributors hit most often and to keep the workflow list grouped predictably in the GitHub UI.\n\n## Naming Convention\n\nGitHub lists workflows by the top-level `name` field.\n\nSambee groups workflow display names by operational purpose using `Area: Subject`.\n\nCurrent workflow groups are:\n\n- `CI`.\n- `Release`.\n- `Deploy`.\n- `Security`.\n- `Admin`.\n\nKeep new names short, stable, and grouped by what the workflow does rather than by how it is triggered.\n\n## Workflow Map\n\n| Display name | File | Role |\n|---|---|---|\n| `CI: Test` | `.github/workflows/test.yml` | Runs the main backend, frontend, and companion validation suites. |\n| `CI: Lint` | `.github/workflows/lint.yml` | Runs repository lint and formatting checks across backend, frontend, and companion. |\n| `CI: Check Backend Lockfiles` | `.github/workflows/check-backend-lockfiles.yml` | Verifies that committed backend lockfiles still match the reviewed requirement sources. |\n| `CI: Validate Docker Image` | `.github/workflows/docker-image-validate.yml` | Builds and smoke-tests the production container image on pull requests, pushes, and manual runs. |\n| `Release: Publish Docker Image` | `.github/workflows/docker-image-publish.yml` | Promotes an existing preview candidate onto release tags and the `stable` or `beta` channel, then signs the digest. |\n| `Release: Create Docker Image` | `.github/workflows/docker-image-preview-publish.yml` | Builds, validates, publishes, and signs a new preview image, forcing a fresh Debian package-layer rebuild for that run before moving the `test` channel tag. |\n| `Maintenance: Backfill Docker Release Tags` | `.github/workflows/docker-image-backfill.yml` | Reattaches release tags and release-channel aliases to an already published candidate digest for an existing release. |\n| `Maintenance: Clean Up Docker Package Versions` | `.github/workflows/docker-image-cleanup.yml` | Removes unprotected SHA-tagged preview GHCR package versions, prunes stale signature artifacts, and deletes unreferenced untagged package versions while preserving release-tagged and channel-protected versions including `test`. |\n| `Release: Build Companion Artifact` | `.github/workflows/build-companion.yml` | Builds companion release artifacts for a new unique version or prerelease candidate in the public distribution repository. |\n| `Release: Promote Companion Release` | `.github/workflows/promote-companion-release.yml` | Moves an existing companion release onto one or more update channels. |\n| `Deploy: Website` | `.github/workflows/website-deploy.yml` | Builds the website and deploys `website/public/` to Cloudflare Pages. |\n| `Security: Dependency Audit` | `.github/workflows/dependency-security.yml` | Runs scheduled and manual dependency vulnerability audits. |\n| `Security: Docker Image Scan` | `.github/workflows/docker-image-security-scan.yml` | Builds the current main image, forces a fresh Debian package-layer rebuild for that run, and scans it for newly disclosed vulnerabilities. |\n| `Admin: Sync Labels` | `.github/workflows/sync-labels.yml` | Synchronizes repository labels from `.github/labels.yml` without deleting unmanaged labels. |\n\nGitHub also shows repository-level features such as `Dependabot updates` and `Dependency graph`.\n\nThose are not repository workflows, so their display names are not controlled by these YAML files.\n\n## CI: Test\n\n`CI: Test` is the main validation workflow for pushes to `main`, pull requests against `main`, and manual dispatch.\n\nIt first detects which top-level product areas changed, then fans out only the relevant jobs for:\n\n- backend\n- frontend\n- frontend Playwright Chromium smoke\n- frontend Playwright Firefox markdown coverage on pushes to `main` and manual runs\n- companion\n\nManual dispatch runs all three areas.\n\nThe workflow ends with a single gate job so branch protection can depend on one stable required check instead of a changing set of per-area jobs.\n\nIn the backend job, regular tests run under `pytest-xdist` for throughput, while `@performance` tests run in a separate serial pass so wall-clock assertions are not distorted by parallel worker contention.\n\nFor frontend coverage, the workflow is intentionally layered:\n\n- the `frontend` job keeps the fast TypeScript, lint, and Vitest checks in the main PR path\n- the `frontend-e2e` job runs a bounded Playwright Chromium smoke slice on frontend changes\n- the `frontend-e2e-firefox` job runs the markdown editor Playwright slice only on pushes to `main` and manual dispatch\n\nThat split keeps pull-request runtime under control while still protecting the browser-sensitive editing workflows that unit tests do not cover.\n\nThe current companion test job does not call `./scripts/test`.\nIt runs explicit steps for Node install, companion TypeScript type checking, and `cargo test`.\nThat means the local Windows GNU cross-check in `./scripts/test` does not currently run in `CI: Test`.\n\n### Caching Model\n\nThe test workflow uses layered caching to reduce repeated setup work while keeping dependency inputs explicit.\n\nCurrent cache layers include:\n\n- `backend/.venv` caching keyed by the resolved backend requirement files and Python version.\n- `backend/.mypy_cache` caching keyed by backend Python source changes.\n- `actions/setup-node` npm download caching for frontend and companion jobs.\n- `frontend/node_modules` caching keyed by `frontend/package-lock.json`.\n- Rust build caching for `companion/src-tauri`.\n\nTreat those cache keys as reviewed dependency inputs, not as disposable generated noise.\n\nWhen dependency manifests or lockfiles change, commit the corresponding lockfile updates in the same pull request so cache invalidation and dependency review stay aligned.\n\n### Local Parity\n\nFor fast local iteration, use `./scripts/test`.\n\nWhen you want a closer CI-style pass, run the per-subsystem checks from [Test Strategy Overview](../test-strategy-overview/) and keep lockfile-driven installs intact.\n\nFor frontend work, that usually means:\n\n- `cd frontend \u0026\u0026 npm test` for the default Vitest suite\n- `cd frontend \u0026\u0026 npm run test:e2e` for the default Chromium browser pass\n\n`./scripts/test` now includes a local companion Windows GNU target compatibility check.\nThat check is intentionally a local validation aid, not part of the current `CI: Test` workflow contract.\n\n## CI: Lint\n\n`CI: Lint` applies the same change-detection pattern, then runs the repository's static checks for only the affected areas.\n\nCurrent coverage includes:\n\n- backend Ruff checks and formatting validation.\n- frontend Biome validation.\n- companion Clippy, Rustfmt, and Biome validation.\n\nThe lint workflow does not run the local companion Windows GNU cross-check either.\nThat cross-target validation is currently a local developer workflow check, while actual Windows artifact creation remains in the release workflow.\n\nThe workflow also ends with one gate job so branch protection can depend on a stable result.\n\n## Runner Distro Policy\n\nSambee does not require every GitHub Actions job to run on the same base distro.\n\nInstead, the rule is:\n\n- jobs that validate production-like runtime behavior or install native runtime dependencies should follow the same Debian family used by the production image and the dev container\n- jobs that only run language-level checks, dependency audits, repository automation, or other host-agnostic validation can stay on `ubuntu-latest`\n\nCurrent Debian-family jobs include:\n\n- the backend job in `CI: Test`\n- the `validate-tests` job in `Release: Create Docker Image`\n\nThose jobs run inside the pinned `python:3.13.12-slim` container because `scripts/install-system-deps` now requires distro-provided ImageMagick 7, while the default Ubuntu GitHub-hosted runner image still resolves `imagemagick` to ImageMagick 6.\n\nCurrent jobs that intentionally remain on `ubuntu-latest` include:\n\n- change-detection, label-sync, and website deployment workflows\n- pure Python lint, lockfile freshness, and dependency-audit workflows\n- frontend-only and companion-only validation workflows\n- Docker build, smoke-test, and vulnerability-scan workflows, where the distro-sensitive logic runs inside the built image rather than on the host runner\n\nWhen adding or changing a workflow, treat runner distro as part of the test contract whenever a job installs OS packages or validates native behavior.\n\n## CI: Check Backend Lockfiles\n\n`CI: Check Backend Lockfiles` protects the reviewed Python dependency workflow.\n\nIt runs `scripts/refresh-backend-lockfiles --check` on pushes, pull requests, and manual runs that touch backend requirement inputs, generated lockfiles, or the refresh script itself.\n\nUse this as the fast failure signal when requirement files and generated lockfiles drift apart.\n\nFor the broader dependency-update workflow, use [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/).\n\n## Admin: Sync Labels\n\n`Admin: Sync Labels` keeps repository labels aligned with `.github/labels.yml`.\n\nIt is intentionally conservative.\n\n- Dependabot-related labels should stay declared in `.github/labels.yml`.\n- The workflow uses `skip-delete: true`, so labels not declared there are left alone.\n\nThat keeps automation-owned labels deterministic without forcing the repository to delete every manually created label.\n\n## Related Workflow Docs\n\nUse the more specific pages for the workflows that have dedicated operational guidance:\n\n- [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/)\n- [Docker Release Overview](../../release-and-versioning/docker-release-overview/)\n- [Companion Release Overview](../../release-and-versioning/companion-release-overview/)\n- [Set Up Cloudflare Pages Publishing](../../../website-dev-guide/setup-and-operations/set-up-cloudflare-pages-publishing/)\n", "0.9": "+++\ntitle = \"CI Workflows and Repository Automation\"\n+++\n\nUse this page to understand the GitHub Actions workflows contributors hit most often and to keep the workflow list grouped predictably in the GitHub UI.\n\n## Naming Convention\n\nGitHub lists workflows by the top-level `name` field.\n\nSambee groups workflow display names by operational purpose using `Area: Subject`.\n\nCurrent workflow groups are:\n\n- `CI`.\n- `Release`.\n- `Deploy`.\n- `Security`.\n- `Admin`.\n\nKeep new names short, stable, and grouped by what the workflow does rather than by how it is triggered.\n\n## Workflow Map\n\n| Display name | File | Role |\n|---|---|---|\n| `CI: Test` | `.github/workflows/test.yml` | Runs the main backend, frontend, and companion validation suites. |\n| `CI: Lint` | `.github/workflows/lint.yml` | Runs repository lint and formatting checks across backend, frontend, and companion. |\n| `CI: Check Backend Lockfiles` | `.github/workflows/check-backend-lockfiles.yml` | Verifies that committed backend lockfiles still match the reviewed requirement sources. |\n| `CI: Validate Docker Image` | `.github/workflows/docker-image-validate.yml` | Builds and smoke-tests the production container image on pull requests, pushes, and manual runs. |\n| `Release: Publish Docker Image` | `.github/workflows/docker-image-publish.yml` | Promotes an existing preview candidate onto release tags and the `stable` or `beta` channel, then signs the digest. |\n| `Release: Create Docker Image` | `.github/workflows/docker-image-preview-publish.yml` | Builds, validates, publishes, and signs a new preview image, forcing a fresh Debian package-layer rebuild for that run before moving the `test` channel tag. |\n| `Maintenance: Backfill Docker Release Tags` | `.github/workflows/docker-image-backfill.yml` | Reattaches release tags and release-channel aliases to an already published candidate digest for an existing release. |\n| `Maintenance: Clean Up Docker Package Versions` | `.github/workflows/docker-image-cleanup.yml` | Removes unprotected SHA-tagged preview GHCR package versions, prunes stale signature artifacts, and deletes unreferenced untagged package versions while preserving release-tagged and channel-protected versions including `test`. |\n| `Release: Build Companion Artifact` | `.github/workflows/build-companion.yml` | Builds companion release artifacts for a new unique version or prerelease candidate in the public distribution repository. |\n| `Release: Promote Companion Release` | `.github/workflows/promote-companion-release.yml` | Moves an existing companion release onto one or more update channels. |\n| `Deploy: Website` | `.github/workflows/website-deploy.yml` | Builds the website and deploys `website/public/` to Cloudflare Pages. |\n| `Security: Dependency Audit` | `.github/workflows/dependency-security.yml` | Runs scheduled and manual dependency vulnerability audits. |\n| `Security: Docker Image Scan` | `.github/workflows/docker-image-security-scan.yml` | Builds the current main image, forces a fresh Debian package-layer rebuild for that run, and scans it for newly disclosed vulnerabilities. |\n| `Admin: Sync Labels` | `.github/workflows/sync-labels.yml` | Synchronizes repository labels from `.github/labels.yml` without deleting unmanaged labels. |\n\nGitHub also shows repository-level features such as `Dependabot updates` and `Dependency graph`.\n\nThose are not repository workflows, so their display names are not controlled by these YAML files.\n\n## CI: Test\n\n`CI: Test` is the main validation workflow for pushes to `main`, pull requests against `main`, and manual dispatch.\n\nIt first detects which top-level product areas changed, then fans out only the relevant jobs for:\n\n- backend\n- frontend\n- frontend Playwright Chromium smoke\n- frontend Playwright Firefox markdown coverage on pushes to `main` and manual runs\n- companion\n\nManual dispatch runs all three areas.\n\nThe workflow ends with a single gate job so branch protection can depend on one stable required check instead of a changing set of per-area jobs.\n\nIn the backend job, regular tests run under `pytest-xdist` for throughput, while `@performance` tests run in a separate serial pass so wall-clock assertions are not distorted by parallel worker contention.\n\nFor frontend coverage, the workflow is intentionally layered:\n\n- the `frontend` job keeps the fast TypeScript, lint, and Vitest checks in the main PR path\n- the `frontend-e2e` job runs a bounded Playwright Chromium smoke slice on frontend changes\n- the `frontend-e2e-firefox` job runs the markdown editor Playwright slice only on pushes to `main` and manual dispatch\n\nThat split keeps pull-request runtime under control while still protecting the browser-sensitive editing workflows that unit tests do not cover.\n\nThe current companion test job does not call `./scripts/test`.\nIt runs explicit steps for Node install, companion TypeScript type checking, and `cargo test`.\nThat means the local Windows GNU cross-check in `./scripts/test` does not currently run in `CI: Test`.\n\n### Caching Model\n\nThe test workflow uses layered caching to reduce repeated setup work while keeping dependency inputs explicit.\n\nCurrent cache layers include:\n\n- `backend/.venv` caching keyed by the resolved backend requirement files and Python version.\n- `backend/.mypy_cache` caching keyed by backend Python source changes.\n- `actions/setup-node` npm download caching for frontend and companion jobs.\n- `frontend/node_modules` caching keyed by `frontend/package-lock.json`.\n- Rust build caching for `companion/src-tauri`.\n\nTreat those cache keys as reviewed dependency inputs, not as disposable generated noise.\n\nWhen dependency manifests or lockfiles change, commit the corresponding lockfile updates in the same pull request so cache invalidation and dependency review stay aligned.\n\n### Local Parity\n\nFor fast local iteration, use `./scripts/test`.\n\nWhen you want a closer CI-style pass, run the per-subsystem checks from [Test Strategy Overview](../test-strategy-overview/) and keep lockfile-driven installs intact.\n\nFor frontend work, that usually means:\n\n- `cd frontend \u0026\u0026 npm test` for the default Vitest suite\n- `cd frontend \u0026\u0026 npm run test:e2e` for the default Chromium browser pass\n\n`./scripts/test` now includes a local companion Windows GNU target compatibility check.\nThat check is intentionally a local validation aid, not part of the current `CI: Test` workflow contract.\n\n## CI: Lint\n\n`CI: Lint` applies the same change-detection pattern, then runs the repository's static checks for only the affected areas.\n\nCurrent coverage includes:\n\n- backend Ruff checks and formatting validation.\n- frontend Biome validation.\n- companion Clippy, Rustfmt, and Biome validation.\n\nThe lint workflow does not run the local companion Windows GNU cross-check either.\nThat cross-target validation is currently a local developer workflow check, while actual Windows artifact creation remains in the release workflow.\n\nThe workflow also ends with one gate job so branch protection can depend on a stable result.\n\n## Runner Distro Policy\n\nSambee does not require every GitHub Actions job to run on the same base distro.\n\nInstead, the rule is:\n\n- jobs that validate production-like runtime behavior or install native runtime dependencies should follow the same Debian family used by the production image and the dev container\n- jobs that only run language-level checks, dependency audits, repository automation, or other host-agnostic validation can stay on `ubuntu-latest`\n\nCurrent Debian-family jobs include:\n\n- the backend job in `CI: Test`\n- the `validate-tests` job in `Release: Create Docker Image`\n\nThe backend job builds the `backend-test` Docker target, which inherits the same runtime base as production. It runs mypy and the backend test suites inside that target, including when a Python image or other runtime input changes. The release validation job uses the pinned Debian-based Python container because `scripts/install-system-deps` requires distro-provided ImageMagick 7, while the default Ubuntu GitHub-hosted runner image still resolves `imagemagick` to ImageMagick 6.\n\n## Shared Runtime Targets\n\nThe root `Dockerfile` defines a shared `runtime-base` target. Production and the VS Code dev container both inherit that target, so they use the same pinned Python image and shared runtime package-installation policy.\n\nBefore building targets, Docker validation confirms that every Python image reference in the Dockerfile uses the same tag and digest. This keeps the native wheel-builder aligned with the shared runtime when Dependabot updates the Python image.\n\n`CI: Validate Docker Image` builds and reports the following values for the production target on each supported image platform and for the devcontainer target on Linux AMD64:\n\n- Python version.\n- `sqlite3` module version.\n- Debian `libsqlite3-0` package version.\n\nThe workflow passes a unique APT refresh key to each build, which intentionally refreshes Debian packages instead of reusing an older cached upgrade layer. The reported versions are evidence of the resolved native runtime; they are not required to match across images built at different times.\n\nCurrent jobs that intentionally remain on `ubuntu-latest` include:\n\n- change-detection, label-sync, and website deployment workflows\n- pure Python lint, lockfile freshness, and dependency-audit workflows\n- frontend-only and companion-only validation workflows\n- Docker build, smoke-test, and vulnerability-scan workflows, where the distro-sensitive logic runs inside the built image rather than on the host runner\n\nWhen adding or changing a workflow, treat runner distro as part of the test contract whenever a job installs OS packages or validates native behavior.\n\n## CI: Check Backend Lockfiles\n\n`CI: Check Backend Lockfiles` protects the reviewed Python dependency workflow.\n\nIt runs `scripts/refresh-backend-lockfiles --check` on pushes, pull requests, and manual runs that touch backend requirement inputs, generated lockfiles, or the refresh script itself.\n\nUse this as the fast failure signal when requirement files and generated lockfiles drift apart.\n\nFor the broader dependency-update workflow, use [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/).\n\n## Admin: Sync Labels\n\n`Admin: Sync Labels` keeps repository labels aligned with `.github/labels.yml`.\n\nIt is intentionally conservative.\n\n- Dependabot-related labels should stay declared in `.github/labels.yml`.\n- The workflow uses `skip-delete: true`, so labels not declared there are left alone.\n\nThat keeps automation-owned labels deterministic without forcing the repository to delete every manually created label.\n\n## Related Workflow Docs\n\nUse the more specific pages for the workflows that have dedicated operational guidance:\n\n- [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/)\n- [Docker Release Overview](../../release-and-versioning/docker-release-overview/)\n- [Companion Release Overview](../../release-and-versioning/companion-release-overview/)\n- [Set Up Cloudflare Pages Publishing](../../../website-dev-guide/setup-and-operations/set-up-cloudflare-pages-publishing/)\n", "1.0": "+++\ntitle = \"CI Workflows and Repository Automation\"\n+++\n\nUse this page to understand the GitHub Actions workflows contributors hit most often and to keep the workflow list grouped predictably in the GitHub UI.\n\n## Naming Convention\n\nGitHub lists workflows by the top-level `name` field.\n\nSambee groups workflow display names by operational purpose using `Area: Subject`.\n\nCurrent workflow groups are:\n\n- `CI`.\n- `Release`.\n- `Deploy`.\n- `Security`.\n- `Admin`.\n\nKeep new names short, stable, and grouped by what the workflow does rather than by how it is triggered.\n\n## Workflow Map\n\n| Display name | File | Role |\n|---|---|---|\n| `CI: Test` | `.github/workflows/test.yml` | Runs the main backend, frontend, and companion validation suites. |\n| `CI: Lint` | `.github/workflows/lint.yml` | Runs repository lint and formatting checks across backend, frontend, and companion. |\n| `CI: Check Backend Lockfiles` | `.github/workflows/check-backend-lockfiles.yml` | Verifies that committed backend lockfiles still match the reviewed requirement sources. |\n| `CI: Validate Docker Image` | `.github/workflows/docker-image-validate.yml` | Builds and smoke-tests the production container image on pull requests, pushes, and manual runs. |\n| `Release: Publish Docker Image` | `.github/workflows/docker-image-publish.yml` | Promotes an existing preview candidate onto release tags and the `stable` or `beta` channel, then signs the digest. |\n| `Release: Create Docker Image` | `.github/workflows/docker-image-preview-publish.yml` | Builds, validates, publishes, and signs a new preview image, forcing a fresh Debian package-layer rebuild for that run before moving the `test` channel tag. |\n| `Maintenance: Backfill Docker Release Tags` | `.github/workflows/docker-image-backfill.yml` | Reattaches release tags and release-channel aliases to an already published candidate digest for an existing release. |\n| `Maintenance: Clean Up Docker Package Versions` | `.github/workflows/docker-image-cleanup.yml` | Removes unprotected SHA-tagged preview GHCR package versions, prunes stale signature artifacts, and deletes unreferenced untagged package versions while preserving release-tagged and channel-protected versions including `test`. |\n| `Release: Build Companion Artifact` | `.github/workflows/build-companion.yml` | Builds companion release artifacts for a new unique version or prerelease candidate in the public distribution repository. |\n| `Release: Promote Companion Release` | `.github/workflows/promote-companion-release.yml` | Moves an existing companion release onto one or more update channels. |\n| `Deploy: Website` | `.github/workflows/website-deploy.yml` | Builds the website and deploys `website/public/` to Cloudflare Pages. |\n| `Security: Dependency Audit` | `.github/workflows/dependency-security.yml` | Runs scheduled and manual dependency vulnerability audits. |\n| `Security: Docker Image Scan` | `.github/workflows/docker-image-security-scan.yml` | Builds the current main image, forces a fresh Debian package-layer rebuild for that run, and scans it for newly disclosed vulnerabilities. |\n| `Admin: Sync Labels` | `.github/workflows/sync-labels.yml` | Synchronizes repository labels from `.github/labels.yml` without deleting unmanaged labels. |\n\nGitHub also shows repository-level features such as `Dependabot updates` and `Dependency graph`.\n\nThose are not repository workflows, so their display names are not controlled by these YAML files.\n\n## CI: Test\n\n`CI: Test` is the main validation workflow for pushes to `main`, pull requests against `main`, and manual dispatch.\n\nIt first detects which top-level product areas changed, then fans out only the relevant jobs for:\n\n- backend\n- frontend\n- frontend Playwright Chromium smoke\n- frontend Playwright Firefox markdown coverage on pushes to `main` and manual runs\n- companion\n\nManual dispatch runs all three areas.\n\nThe workflow ends with a single gate job so branch protection can depend on one stable required check instead of a changing set of per-area jobs.\n\nIn the backend job, regular tests run under `pytest-xdist` for throughput, while `@performance` tests run in a separate serial pass so wall-clock assertions are not distorted by parallel worker contention.\n\nFor frontend coverage, the workflow is intentionally layered:\n\n- the `frontend` job keeps the fast TypeScript, lint, and Vitest checks in the main PR path\n- the `frontend-e2e` job runs a bounded Playwright Chromium smoke slice on frontend changes\n- the `frontend-e2e-firefox` job runs the markdown editor Playwright slice only on pushes to `main` and manual dispatch\n\nThat split keeps pull-request runtime under control while still protecting the browser-sensitive editing workflows that unit tests do not cover.\n\nThe current companion test job does not call `./scripts/test`.\nIt runs explicit steps for Node install, companion TypeScript type checking, and `cargo test`.\nThat means the local Windows GNU cross-check in `./scripts/test` does not currently run in `CI: Test`.\n\n### Caching Model\n\nThe test workflow uses layered caching to reduce repeated setup work while keeping dependency inputs explicit.\n\nCurrent cache layers include:\n\n- `backend/.venv` caching keyed by the resolved backend requirement files and Python version.\n- `backend/.mypy_cache` caching keyed by backend Python source changes.\n- `actions/setup-node` npm download caching for frontend and companion jobs.\n- `frontend/node_modules` caching keyed by `frontend/package-lock.json`.\n- Rust build caching for `companion/src-tauri`.\n\nTreat those cache keys as reviewed dependency inputs, not as disposable generated noise.\n\nWhen dependency manifests or lockfiles change, commit the corresponding lockfile updates in the same pull request so cache invalidation and dependency review stay aligned.\n\n### Local Parity\n\nFor fast local iteration, use `./scripts/test`.\n\nWhen you want a closer CI-style pass, run the per-subsystem checks from [Test Strategy Overview](../test-strategy-overview/) and keep lockfile-driven installs intact.\n\nFor frontend work, that usually means:\n\n- `cd frontend \u0026\u0026 npm test` for the default Vitest suite\n- `cd frontend \u0026\u0026 npm run test:e2e` for the default Chromium browser pass\n\n`./scripts/test` now includes a local companion Windows GNU target compatibility check.\nThat check is intentionally a local validation aid, not part of the current `CI: Test` workflow contract.\n\n## CI: Lint\n\n`CI: Lint` applies the same change-detection pattern, then runs the repository's static checks for only the affected areas.\n\nCurrent coverage includes:\n\n- backend Ruff checks and formatting validation.\n- frontend Biome validation.\n- companion Clippy, Rustfmt, and Biome validation.\n\nThe lint workflow does not run the local companion Windows GNU cross-check either.\nThat cross-target validation is currently a local developer workflow check, while actual Windows artifact creation remains in the release workflow.\n\nThe workflow also ends with one gate job so branch protection can depend on a stable result.\n\n## Runner Distro Policy\n\nSambee does not require every GitHub Actions job to run on the same base distro.\n\nInstead, the rule is:\n\n- jobs that validate production-like runtime behavior or install native runtime dependencies should follow the same Debian family used by the production image and the dev container\n- jobs that only run language-level checks, dependency audits, repository automation, or other host-agnostic validation can stay on `ubuntu-latest`\n\nCurrent Debian-family jobs include:\n\n- the backend job in `CI: Test`\n- the `validate-tests` job in `Release: Create Docker Image`\n\nThe backend job builds the `backend-test` Docker target, which inherits the same runtime base as production. It runs mypy and the backend test suites inside that target, including when a Python image or other runtime input changes. The release validation job uses the pinned Debian-based Python container because `scripts/install-system-deps` requires distro-provided ImageMagick 7, while the default Ubuntu GitHub-hosted runner image still resolves `imagemagick` to ImageMagick 6.\n\n## Shared Runtime Targets\n\nThe root `Dockerfile` defines a shared `runtime-base` target. Production and the VS Code dev container both inherit that target, so they use the same pinned Python image and shared runtime package-installation policy.\n\nBefore building targets, Docker validation confirms that every Python image reference in the Dockerfile uses the same tag and digest. This keeps the native wheel-builder aligned with the shared runtime when Dependabot updates the Python image.\n\n`CI: Validate Docker Image` builds and reports the following values for the production target on each supported image platform and for the devcontainer target on Linux AMD64:\n\n- Python version.\n- `sqlite3` module version.\n- Debian `libsqlite3-0` package version.\n\nThe workflow passes a unique APT refresh key to each build, which intentionally refreshes Debian packages instead of reusing an older cached upgrade layer. The reported versions are evidence of the resolved native runtime; they are not required to match across images built at different times.\n\nCurrent jobs that intentionally remain on `ubuntu-latest` include:\n\n- change-detection, label-sync, and website deployment workflows\n- pure Python lint, lockfile freshness, and dependency-audit workflows\n- frontend-only and companion-only validation workflows\n- Docker build, smoke-test, and vulnerability-scan workflows, where the distro-sensitive logic runs inside the built image rather than on the host runner\n\nWhen adding or changing a workflow, treat runner distro as part of the test contract whenever a job installs OS packages or validates native behavior.\n\n## CI: Check Backend Lockfiles\n\n`CI: Check Backend Lockfiles` protects the reviewed Python dependency workflow.\n\nIt runs `scripts/refresh-backend-lockfiles --check` on pushes, pull requests, and manual runs that touch backend requirement inputs, generated lockfiles, or the refresh script itself.\n\nUse this as the fast failure signal when requirement files and generated lockfiles drift apart.\n\nFor the broader dependency-update workflow, use [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/).\n\n## Admin: Sync Labels\n\n`Admin: Sync Labels` keeps repository labels aligned with `.github/labels.yml`.\n\nIt is intentionally conservative.\n\n- Dependabot-related labels should stay declared in `.github/labels.yml`.\n- The workflow uses `skip-delete: true`, so labels not declared there are left alone.\n\nThat keeps automation-owned labels deterministic without forcing the repository to delete every manually created label.\n\n## Related Workflow Docs\n\nUse the more specific pages for the workflows that have dedicated operational guidance:\n\n- [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/)\n- [Docker Release Overview](../../release-and-versioning/docker-release-overview/)\n- [Companion Release Overview](../../release-and-versioning/companion-release-overview/)\n- [Set Up Cloudflare Pages Publishing](../../../website-dev-guide/setup-and-operations/set-up-cloudflare-pages-publishing/)\n", "2.0": "+++\ntitle = \"CI Workflows and Repository Automation\"\n+++\n\nUse this page to understand the GitHub Actions workflows contributors hit most often and to keep the workflow list grouped predictably in the GitHub UI.\n\n## Naming Convention\n\nGitHub lists workflows by the top-level `name` field.\n\nSambee groups workflow display names by operational purpose using `Area: Subject`.\n\nCurrent workflow groups are:\n\n- `CI`.\n- `Release`.\n- `Deploy`.\n- `Security`.\n- `Admin`.\n\nKeep new names short, stable, and grouped by what the workflow does rather than by how it is triggered.\n\n## Workflow Map\n\n| Display name | File | Role |\n|---|---|---|\n| `CI: Test` | `.github/workflows/test.yml` | Runs the main backend, frontend, and companion validation suites. |\n| `CI: Lint` | `.github/workflows/lint.yml` | Runs repository lint and formatting checks across backend, frontend, and companion. |\n| `CI: Check Backend Lockfiles` | `.github/workflows/check-backend-lockfiles.yml` | Verifies that committed backend lockfiles still match the reviewed requirement sources. |\n| `CI: Validate Docker Image` | `.github/workflows/docker-image-validate.yml` | Builds and smoke-tests the production container image on pull requests, pushes, and manual runs. |\n| `Release: Publish Docker Image` | `.github/workflows/docker-image-publish.yml` | Promotes an existing preview candidate onto release tags and the `stable` or `beta` channel, then signs the digest. |\n| `Release: Create Docker Image` | `.github/workflows/docker-image-preview-publish.yml` | Builds, validates, publishes, and signs a new preview image, forcing a fresh Debian package-layer rebuild for that run before moving the `test` channel tag. |\n| `Maintenance: Backfill Docker Release Tags` | `.github/workflows/docker-image-backfill.yml` | Reattaches release tags and release-channel aliases to an already published candidate digest for an existing release. |\n| `Maintenance: Clean Up Docker Package Versions` | `.github/workflows/docker-image-cleanup.yml` | Removes unprotected SHA-tagged preview GHCR package versions, prunes stale signature artifacts, and deletes unreferenced untagged package versions while preserving release-tagged and channel-protected versions including `test`. |\n| `Maintenance: Clean Up Actions Caches` | `.github/workflows/cleanup-actions-caches.yml` | Removes closed-PR caches and superseded known cache keys without disabling warm caches for active builds. |\n| `Maintenance: Signal Closed PR Cache Cleanup` | `.github/workflows/signal-closed-pr-cache-cleanup.yml` | Triggers cache cleanup after a pull request closes without granting the pull request write access. |\n| `Release: Build Companion Artifact` | `.github/workflows/build-companion.yml` | Builds companion release artifacts for a new unique version or prerelease candidate in the public distribution repository. |\n| `Release: Promote Companion Release` | `.github/workflows/promote-companion-release.yml` | Moves an existing companion release onto one or more update channels. |\n| `Deploy: Website` | `.github/workflows/website-deploy.yml` | Builds the website and deploys `website/public/` to Cloudflare Pages. |\n| `Security: Dependency Audit` | `.github/workflows/dependency-security.yml` | Runs scheduled and manual dependency vulnerability audits. |\n| `Security: Docker Image Scan` | `.github/workflows/docker-image-security-scan.yml` | Builds the current main image, forces a fresh Debian package-layer rebuild for that run, and scans it for newly disclosed vulnerabilities. |\n| `Admin: Sync Labels` | `.github/workflows/sync-labels.yml` | Synchronizes repository labels from `.github/labels.yml` without deleting unmanaged labels. |\n\nGitHub also shows repository-level features such as `Dependabot updates` and `Dependency graph`.\n\nThose are not repository workflows, so their display names are not controlled by these YAML files.\n\n## CI: Test\n\n`CI: Test` is the main validation workflow for pushes to `main`, pull requests against `main`, and manual dispatch.\n\nIt first detects which top-level product areas changed, then fans out only the relevant jobs for:\n\n- backend\n- frontend, including Chromium and Firefox browser correctness\n- companion\n- website documentation\n\nManual dispatch runs all areas. Changes to shared frontend CI infrastructure also select frontend validation.\n\nThe workflow ends with a single gate job so branch protection can depend on one stable required check instead of a changing set of per-area jobs.\n\nIn the backend job, regular tests run under `pytest-xdist` for throughput, while `@performance` tests run in a separate serial pass so wall-clock assertions are not distorted by parallel worker contention.\n\nBackend pytest runs treat unexpected warnings as errors, including resource-cleanup warnings. The shared policy in `backend/pyproject.toml` applies to both local and CI runs, and warning summaries aren't suppressed. Tests that deliberately trigger a warning must assert it with `pytest.warns(...)`, matching the warning category and message. Fix application warnings rather than ignoring them. Unavoidable dependency exceptions must be narrowly scoped and documented; the current exception covers Starlette's TestClient reference to AnyIO's deprecated `BlockingPortal` alias. Remove that exception when the dependency no longer needs it.\n\nThe `frontend` job requires a clean TypeScript check, runs Vitest, builds normal production assets, installs version-matched Playwright Chromium/Firefox binaries and their Linux dependencies, then runs `npm run test:browser:ci`. Both engines run on frontend pull requests, pushes, and manual dispatch. The same required checks run in release fallback when successful source CI cannot be reused.\n\nThe browser command requires exactly 16 production cases: four scenarios at desktop and narrow widths in each engine. They protect real normalization/syntax workers, entity decoding, native selection/focus/heading links/search, regex replacement with undo/redo and exact Save content, and cancellation/reopen cleanup with stale-result replay. Two additional development-worker cases exercise Vite's dependency-resolution path. Browser APIs and workers are real; backend responses are mocked at `http://localhost:3000/browse/smb/demo`. This isn't full-stack SMB E2E or evidence of physical printing, browser-menu Find, hardware IME, or assistive-technology behavior.\n\nThe correctness reporter rejects missing, duplicate, skipped, failed, and retried cases. Browser cases run with one worker and no retries. Reports and retained failure traces/screenshots are uploaded for seven days. Timing budgets, profiling, heap measurements, alternate renderers, and repeated cache/performance matrices remain separate opt-in diagnostics.\n\n`npm run typecheck` runs `tsc -b --noEmit` across the application, test/helper, and Node configuration projects. Browser code uses browser types; tests add Vitest and Node types; configuration tooling uses Node types. All source and declaration files remain checked with strict null/index and unused-code diagnostics enabled. The ES2023 library declarations describe existing APIs; the emitted target remains ES2020, and declarations don't provide runtime polyfills.\n\nType correctness is mandatory in routine CI, release fallback, ordinary `npm run build`, `./scripts/test`, and the VS Code frontend validation task. The old root `tsc --noEmit` command checked no input files and mustn't be used as a substitute. Regression tests protect required command wiring, strict options, separate environments, and complete source coverage. Unit and browser correctness remain independent required gates.\n\nThe required gate rejects an unexpectedly skipped selected job. Only unrelated, unselected areas may be skipped. Superseded pull-request test/lint runs are cancelled; main-branch validation runs aren't cancelled by that policy. Release reuse requires the exact source commit's successful frontend job, its successful browser-correctness step, and the new required `Verify frontend type correctness` step. Missing, skipped, or failed steps and legacy advisory type-check runs don't qualify.\n\nThe current companion test job does not call `./scripts/test`.\nIt runs explicit steps for Node install, companion TypeScript type checking, and the archive topology conformance script, including Rust tests, formatting, and Clippy.\nThat means the local Windows GNU cross-check in `./scripts/test` does not currently run in `CI: Test`.\n\n### Caching Model\n\nThe test workflow uses layered caching to reduce repeated setup work while keeping dependency inputs explicit.\n\nCurrent cache layers include:\n\n- GitHub Actions BuildKit caching for the `backend-test` Docker target, with dependency layers before source copies.\n- `actions/setup-node` npm download caching for frontend and companion jobs.\n- Rust build caching for `companion/src-tauri`.\n\nFrontend jobs use clean `npm ci --prefer-offline` installs; they don't cache `node_modules` or Playwright browser downloads. The mypy cache inside the disposable backend test container isn't persisted separately.\n\nVitest file parallelism is capped at four workers and further limited by the runner's available CPUs and RAM, reserving 2 GiB plus 2 GiB per worker. The CI command logs the actual resources and selected cap. Standard public Ubuntu runners currently provide 4 vCPUs/16 GB RAM; private runners provide 2 vCPUs/8 GB RAM. Local measurements on a larger machine aren't Actions performance guarantees.\n\nTreat those cache keys as reviewed dependency inputs, not as disposable generated noise.\n\nWhen dependency manifests or lockfiles change, commit the corresponding lockfile updates in the same pull request so cache invalidation and dependency review stay aligned.\n\n### Cache Retention\n\n`Maintenance: Clean Up Actions Caches` runs after cache-producing workflows finish and daily as a fallback. When a pull request closes, an unprivileged signal workflow runs first; its completion triggers the same cleanup. A manual run defaults to a dry run; select **Delete eligible caches** to apply the policy. Its run summary lists selected entries and the amount of storage reclaimed. The cleanup reads only trusted code from `main`, and does not run pull-request code with cache-deletion permissions.\n\nThe policy keeps the newest known cache family on `main` and each open pull request. It removes superseded Rust and website cache keys, and deletes all caches for a closed pull request after its builds finish. It skips refs with active builds and leaves unrecognized keys, including individual BuildKit blobs on active refs, alone. GitHub's normal expiration still applies to those unclassified entries. The job deletes caches by ID so a pull request's copy cannot inadvertently delete an identically keyed cache on `main`.\n\nReview the dry-run report before changing cache-family rules. If active caches alone approach the repository storage limit, raise the limit or accept more cache misses: deleting their newest copies would make CI slower. Cleanup happens after cache uploads, so it cannot prevent a full repository from evicting caches during an upload.\n\n### Local Parity\n\nFor fast local iteration, use `./scripts/test`.\n\nWhen you want a closer CI-style pass, run the per-subsystem checks from [Test Strategy Overview](../test-strategy-overview/) and keep lockfile-driven installs intact.\n\nFor frontend work, that usually means:\n\n- `cd frontend \u0026\u0026 npm run test` for the default Vitest suite\n- `cd frontend \u0026\u0026 npm run test:ci` for runner-aware Vitest concurrency\n- `cd frontend \u0026\u0026 npm run typecheck` for the complete strict compiler check\n- `cd frontend \u0026\u0026 npm run build` followed by `npm run test:browser:ci` for the exact production/development browser contract\n- `cd frontend \u0026\u0026 npm run test:e2e:install -- --with-deps` to install the matching browsers and Linux dependencies\n\n`./scripts/test` now includes a local companion Windows GNU target compatibility check.\nThat check is intentionally a local validation aid, not part of the current `CI: Test` workflow contract.\n\n## CI: Lint\n\n`CI: Lint` applies the same change-detection pattern, then runs the repository's static checks for only the affected areas.\n\nCurrent coverage includes:\n\n- backend Ruff checks and formatting validation.\n- frontend Biome validation.\n- companion Clippy, Rustfmt, and Biome validation.\n\nRuff's executable-script rules (`EXE`) also check Python files throughout the repository, including `.github/`. Any Python-file change selects backend lint, as do changes to the lint workflow or `scripts/test`. These checks fail CI and `./scripts/test` on errors; they aren't advisory. A script with a shebang must be executable. Files invoked explicitly through Python, and imported modules, don't need a shebang.\n\nThe lint workflow does not run the local companion Windows GNU cross-check either.\nThat cross-target validation is currently a local developer workflow check, while actual Windows artifact creation remains in the release workflow.\n\nThe workflow also ends with one gate job so branch protection can depend on a stable result.\n\n## Runner Distro Policy\n\nAll Ubuntu x64 host jobs use `ubuntu-latest`, following GitHub's managed OS migrations and runner-image updates. Native ARM64 image matrices use `ubuntu-26.04-arm`; GitHub doesn't currently document an `ubuntu-latest-arm` label. Windows and macOS coverage remains on its own platform runners.\n\nHost runner choice doesn't replace production-runtime validation. Debian-family checks still include the backend test container and the release `validate-tests` container.\n\nThe backend job builds the `backend-test` Docker target, which inherits the same runtime base as production. It runs mypy and the backend test suites inside that target, including when a Python image or other runtime input changes. The release validation job uses the pinned Debian-based Python container because `scripts/install-system-deps` requires distro-provided ImageMagick 7, while the default Ubuntu GitHub-hosted runner image still resolves `imagemagick` to ImageMagick 6.\n\n## Shared Runtime Targets\n\nThe root `Dockerfile` defines a shared `runtime-base` target. Production and the VS Code dev container both inherit that target, so they use the same pinned Python image and shared runtime package-installation policy.\n\nBefore building targets, Docker validation confirms that every Python image reference in the Dockerfile uses the same tag and digest. This keeps the native wheel-builder aligned with the shared runtime when Dependabot updates the Python image.\n\n`CI: Validate Docker Image` builds and reports the following values for the production target on each supported image platform and for the devcontainer target on Linux AMD64:\n\n- Python version.\n- `sqlite3` module version.\n- Debian `libsqlite3-0` package version.\n\nThe workflow passes a unique APT refresh key to each build, which intentionally refreshes Debian packages instead of reusing an older cached upgrade layer. The reported versions are evidence of the resolved native runtime; they are not required to match across images built at different times.\n\nCurrent jobs that intentionally remain on `ubuntu-latest` include:\n\n- change-detection, label-sync, and website deployment workflows\n- pure Python lint, lockfile freshness, and dependency-audit workflows\n- frontend-only and companion-only validation workflows\n- Docker build, smoke-test, and vulnerability-scan workflows, where the distro-sensitive logic runs inside the built image rather than on the host runner\n\nWhen adding or changing a workflow, treat runner distro as part of the test contract whenever a job installs OS packages or validates native behavior.\n\n## CI: Check Backend Lockfiles\n\n`CI: Check Backend Lockfiles` protects the reviewed Python dependency workflow.\n\nIt runs `scripts/refresh-backend-lockfiles --check` on pushes, pull requests, and manual runs that touch backend requirement inputs, generated lockfiles, or the refresh script itself.\n\nUse this as the fast failure signal when requirement files and generated lockfiles drift apart.\n\nFor the broader dependency-update workflow, use [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/).\n\n## Admin: Sync Labels\n\n`Admin: Sync Labels` keeps repository labels aligned with `.github/labels.yml`.\n\nIt is intentionally conservative.\n\n- Dependabot-related labels should stay declared in `.github/labels.yml`.\n- The workflow uses `skip-delete: true`, so labels not declared there are left alone.\n\nThat keeps automation-owned labels deterministic without forcing the repository to delete every manually created label.\n\n## Related Workflow Docs\n\nUse the more specific pages for the workflows that have dedicated operational guidance:\n\n- [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/)\n- [Docker Release Overview](../../release-and-versioning/docker-release-overview/)\n- [Companion Release Overview](../../release-and-versioning/companion-release-overview/)\n- [Set Up Cloudflare Pages Publishing](../../../website-dev-guide/setup-and-operations/set-up-cloudflare-pages-publishing/)\n"}, "page_contents": {"0.7": "+++\ntitle = \"CI Workflows and Repository Automation\"\n+++\n\nUse this page to understand the GitHub Actions workflows contributors hit most often and to keep the workflow list grouped predictably in the GitHub UI.\n\n## Naming Convention\n\nGitHub lists workflows by the top-level `name` field.\n\nSambee groups workflow display names by operational purpose using `Area: Subject`.\n\nCurrent workflow groups are:\n\n- `CI`.\n- `Release`.\n- `Deploy`.\n- `Security`.\n- `Admin`.\n\nKeep new names short, stable, and grouped by what the workflow does rather than by how it is triggered.\n\n## Workflow Map\n\n| Display name | File | Role |\n|---|---|---|\n| `CI: Test` | `.github/workflows/test.yml` | Runs the main backend, frontend, and companion validation suites. |\n| `CI: Lint` | `.github/workflows/lint.yml` | Runs repository lint and formatting checks across backend, frontend, and companion. |\n| `CI: Check Backend Lockfiles` | `.github/workflows/check-backend-lockfiles.yml` | Verifies that committed backend lockfiles still match the reviewed requirement sources. |\n| `CI: Validate Docker Image` | `.github/workflows/docker-image-validate.yml` | Builds and smoke-tests the production container image on pull requests, pushes, and manual runs. |\n| `Release: Publish Docker Image` | `.github/workflows/docker-image-publish.yml` | Promotes an existing preview candidate onto release tags and the `stable` or `beta` channel, then signs the digest. |\n| `Release: Create Docker Image` | `.github/workflows/docker-image-preview-publish.yml` | Builds, validates, publishes, and signs a new preview image, forcing a fresh Debian package-layer rebuild for that run before moving the `test` channel tag. |\n| `Maintenance: Backfill Docker Release Tags` | `.github/workflows/docker-image-backfill.yml` | Reattaches release tags and release-channel aliases to an already published candidate digest for an existing release. |\n| `Maintenance: Clean Up Docker Package Versions` | `.github/workflows/docker-image-cleanup.yml` | Removes unprotected SHA-tagged preview GHCR package versions, prunes stale signature artifacts, and deletes unreferenced untagged package versions while preserving release-tagged and channel-protected versions including `test`. |\n| `Release: Build Companion Artifact` | `.github/workflows/build-companion.yml` | Builds companion release artifacts for a new unique version or prerelease candidate in the public distribution repository. |\n| `Release: Promote Companion Release` | `.github/workflows/promote-companion-release.yml` | Moves an existing companion release onto one or more update channels. |\n| `Deploy: Website` | `.github/workflows/website-deploy.yml` | Builds the website and deploys `website/public/` to Cloudflare Pages. |\n| `Security: Dependency Audit` | `.github/workflows/dependency-security.yml` | Runs scheduled and manual dependency vulnerability audits. |\n| `Security: Docker Image Scan` | `.github/workflows/docker-image-security-scan.yml` | Builds the current main image, forces a fresh Debian package-layer rebuild for that run, and scans it for newly disclosed vulnerabilities. |\n| `Admin: Sync Labels` | `.github/workflows/sync-labels.yml` | Synchronizes repository labels from `.github/labels.yml` without deleting unmanaged labels. |\n\nGitHub also shows repository-level features such as `Dependabot updates` and `Dependency graph`.\n\nThose are not repository workflows, so their display names are not controlled by these YAML files.\n\n## CI: Test\n\n`CI: Test` is the main validation workflow for pushes to `main`, pull requests against `main`, and manual dispatch.\n\nIt first detects which top-level product areas changed, then fans out only the relevant jobs for:\n\n- backend\n- frontend\n- companion\n\nManual dispatch runs all three areas.\n\nThe workflow ends with a single gate job so branch protection can depend on one stable required check instead of a changing set of per-area jobs.\n\nIn the backend job, regular tests run under `pytest-xdist` for throughput, while `@performance` tests run in a separate serial pass so wall-clock assertions are not distorted by parallel worker contention.\n\n### Caching Model\n\nThe test workflow uses layered caching to reduce repeated setup work while keeping dependency inputs explicit.\n\nCurrent cache layers include:\n\n- `backend/.venv` caching keyed by the resolved backend requirement files and Python version.\n- `backend/.mypy_cache` caching keyed by backend Python source changes.\n- `actions/setup-node` npm download caching for frontend and companion jobs.\n- `frontend/node_modules` caching keyed by `frontend/package-lock.json`.\n- Rust build caching for `companion/src-tauri`.\n\nTreat those cache keys as reviewed dependency inputs, not as disposable generated noise.\n\nWhen dependency manifests or lockfiles change, commit the corresponding lockfile updates in the same pull request so cache invalidation and dependency review stay aligned.\n\n### Local Parity\n\nFor fast local iteration, use `./scripts/test`.\n\nWhen you want a closer CI-style pass, run the per-subsystem checks from [Test Strategy Overview](../test-strategy-overview/) and keep lockfile-driven installs intact.\n\n## CI: Lint\n\n`CI: Lint` applies the same change-detection pattern, then runs the repository's static checks for only the affected areas.\n\nCurrent coverage includes:\n\n- backend Ruff checks and formatting validation.\n- frontend Biome validation.\n- companion Clippy, Rustfmt, and Biome validation.\n\nThe workflow also ends with one gate job so branch protection can depend on a stable result.\n\n## Runner Distro Policy\n\nSambee does not require every GitHub Actions job to run on the same base distro.\n\nInstead, the rule is:\n\n- jobs that validate production-like runtime behavior or install native runtime dependencies should follow the same Debian family used by the production image and the dev container\n- jobs that only run language-level checks, dependency audits, repository automation, or other host-agnostic validation can stay on `ubuntu-latest`\n\nCurrent Debian-family jobs include:\n\n- the backend job in `CI: Test`\n- the `validate-tests` job in `Release: Create Docker Image`\n\nThose jobs run inside the pinned `python:3.13.12-slim` container because `scripts/install-system-deps` now requires distro-provided ImageMagick 7, while the default Ubuntu GitHub-hosted runner image still resolves `imagemagick` to ImageMagick 6.\n\nCurrent jobs that intentionally remain on `ubuntu-latest` include:\n\n- change-detection, label-sync, and website deployment workflows\n- pure Python lint, lockfile freshness, and dependency-audit workflows\n- frontend-only and companion-only validation workflows\n- Docker build, smoke-test, and vulnerability-scan workflows, where the distro-sensitive logic runs inside the built image rather than on the host runner\n\nWhen adding or changing a workflow, treat runner distro as part of the test contract whenever a job installs OS packages or validates native behavior.\n\n## CI: Check Backend Lockfiles\n\n`CI: Check Backend Lockfiles` protects the reviewed Python dependency workflow.\n\nIt runs `scripts/refresh-backend-lockfiles --check` on pushes, pull requests, and manual runs that touch backend requirement inputs, generated lockfiles, or the refresh script itself.\n\nUse this as the fast failure signal when requirement files and generated lockfiles drift apart.\n\nFor the broader dependency-update workflow, use [Dependency Update Workflow](../release-and-versioning/dependency-update-workflow/).\n\n## Admin: Sync Labels\n\n`Admin: Sync Labels` keeps repository labels aligned with `.github/labels.yml`.\n\nIt is intentionally conservative.\n\n- Dependabot-related labels should stay declared in `.github/labels.yml`.\n- The workflow uses `skip-delete: true`, so labels not declared there are left alone.\n\nThat keeps automation-owned labels deterministic without forcing the repository to delete every manually created label.\n\n## Related Workflow Docs\n\nUse the more specific pages for the workflows that have dedicated operational guidance:\n\n- [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/)\n- [Docker Release Overview](../../release-and-versioning/docker-release-overview/)\n- [Companion Release Overview](../../release-and-versioning/companion-release-overview/)\n- [Set Up Cloudflare Pages Publishing](../../../website-dev-guide/setup-and-operations/set-up-cloudflare-pages-publishing/)\n\n", "0.8": "+++\ntitle = \"CI Workflows and Repository Automation\"\n+++\n\nUse this page to understand the GitHub Actions workflows contributors hit most often and to keep the workflow list grouped predictably in the GitHub UI.\n\n## Naming Convention\n\nGitHub lists workflows by the top-level `name` field.\n\nSambee groups workflow display names by operational purpose using `Area: Subject`.\n\nCurrent workflow groups are:\n\n- `CI`.\n- `Release`.\n- `Deploy`.\n- `Security`.\n- `Admin`.\n\nKeep new names short, stable, and grouped by what the workflow does rather than by how it is triggered.\n\n## Workflow Map\n\n| Display name | File | Role |\n|---|---|---|\n| `CI: Test` | `.github/workflows/test.yml` | Runs the main backend, frontend, and companion validation suites. |\n| `CI: Lint` | `.github/workflows/lint.yml` | Runs repository lint and formatting checks across backend, frontend, and companion. |\n| `CI: Check Backend Lockfiles` | `.github/workflows/check-backend-lockfiles.yml` | Verifies that committed backend lockfiles still match the reviewed requirement sources. |\n| `CI: Validate Docker Image` | `.github/workflows/docker-image-validate.yml` | Builds and smoke-tests the production container image on pull requests, pushes, and manual runs. |\n| `Release: Publish Docker Image` | `.github/workflows/docker-image-publish.yml` | Promotes an existing preview candidate onto release tags and the `stable` or `beta` channel, then signs the digest. |\n| `Release: Create Docker Image` | `.github/workflows/docker-image-preview-publish.yml` | Builds, validates, publishes, and signs a new preview image, forcing a fresh Debian package-layer rebuild for that run before moving the `test` channel tag. |\n| `Maintenance: Backfill Docker Release Tags` | `.github/workflows/docker-image-backfill.yml` | Reattaches release tags and release-channel aliases to an already published candidate digest for an existing release. |\n| `Maintenance: Clean Up Docker Package Versions` | `.github/workflows/docker-image-cleanup.yml` | Removes unprotected SHA-tagged preview GHCR package versions, prunes stale signature artifacts, and deletes unreferenced untagged package versions while preserving release-tagged and channel-protected versions including `test`. |\n| `Release: Build Companion Artifact` | `.github/workflows/build-companion.yml` | Builds companion release artifacts for a new unique version or prerelease candidate in the public distribution repository. |\n| `Release: Promote Companion Release` | `.github/workflows/promote-companion-release.yml` | Moves an existing companion release onto one or more update channels. |\n| `Deploy: Website` | `.github/workflows/website-deploy.yml` | Builds the website and deploys `website/public/` to Cloudflare Pages. |\n| `Security: Dependency Audit` | `.github/workflows/dependency-security.yml` | Runs scheduled and manual dependency vulnerability audits. |\n| `Security: Docker Image Scan` | `.github/workflows/docker-image-security-scan.yml` | Builds the current main image, forces a fresh Debian package-layer rebuild for that run, and scans it for newly disclosed vulnerabilities. |\n| `Admin: Sync Labels` | `.github/workflows/sync-labels.yml` | Synchronizes repository labels from `.github/labels.yml` without deleting unmanaged labels. |\n\nGitHub also shows repository-level features such as `Dependabot updates` and `Dependency graph`.\n\nThose are not repository workflows, so their display names are not controlled by these YAML files.\n\n## CI: Test\n\n`CI: Test` is the main validation workflow for pushes to `main`, pull requests against `main`, and manual dispatch.\n\nIt first detects which top-level product areas changed, then fans out only the relevant jobs for:\n\n- backend\n- frontend\n- frontend Playwright Chromium smoke\n- frontend Playwright Firefox markdown coverage on pushes to `main` and manual runs\n- companion\n\nManual dispatch runs all three areas.\n\nThe workflow ends with a single gate job so branch protection can depend on one stable required check instead of a changing set of per-area jobs.\n\nIn the backend job, regular tests run under `pytest-xdist` for throughput, while `@performance` tests run in a separate serial pass so wall-clock assertions are not distorted by parallel worker contention.\n\nFor frontend coverage, the workflow is intentionally layered:\n\n- the `frontend` job keeps the fast TypeScript, lint, and Vitest checks in the main PR path\n- the `frontend-e2e` job runs a bounded Playwright Chromium smoke slice on frontend changes\n- the `frontend-e2e-firefox` job runs the markdown editor Playwright slice only on pushes to `main` and manual dispatch\n\nThat split keeps pull-request runtime under control while still protecting the browser-sensitive editing workflows that unit tests do not cover.\n\nThe current companion test job does not call `./scripts/test`.\nIt runs explicit steps for Node install, companion TypeScript type checking, and `cargo test`.\nThat means the local Windows GNU cross-check in `./scripts/test` does not currently run in `CI: Test`.\n\n### Caching Model\n\nThe test workflow uses layered caching to reduce repeated setup work while keeping dependency inputs explicit.\n\nCurrent cache layers include:\n\n- `backend/.venv` caching keyed by the resolved backend requirement files and Python version.\n- `backend/.mypy_cache` caching keyed by backend Python source changes.\n- `actions/setup-node` npm download caching for frontend and companion jobs.\n- `frontend/node_modules` caching keyed by `frontend/package-lock.json`.\n- Rust build caching for `companion/src-tauri`.\n\nTreat those cache keys as reviewed dependency inputs, not as disposable generated noise.\n\nWhen dependency manifests or lockfiles change, commit the corresponding lockfile updates in the same pull request so cache invalidation and dependency review stay aligned.\n\n### Local Parity\n\nFor fast local iteration, use `./scripts/test`.\n\nWhen you want a closer CI-style pass, run the per-subsystem checks from [Test Strategy Overview](../test-strategy-overview/) and keep lockfile-driven installs intact.\n\nFor frontend work, that usually means:\n\n- `cd frontend \u0026\u0026 npm test` for the default Vitest suite\n- `cd frontend \u0026\u0026 npm run test:e2e` for the default Chromium browser pass\n\n`./scripts/test` now includes a local companion Windows GNU target compatibility check.\nThat check is intentionally a local validation aid, not part of the current `CI: Test` workflow contract.\n\n## CI: Lint\n\n`CI: Lint` applies the same change-detection pattern, then runs the repository's static checks for only the affected areas.\n\nCurrent coverage includes:\n\n- backend Ruff checks and formatting validation.\n- frontend Biome validation.\n- companion Clippy, Rustfmt, and Biome validation.\n\nThe lint workflow does not run the local companion Windows GNU cross-check either.\nThat cross-target validation is currently a local developer workflow check, while actual Windows artifact creation remains in the release workflow.\n\nThe workflow also ends with one gate job so branch protection can depend on a stable result.\n\n## Runner Distro Policy\n\nSambee does not require every GitHub Actions job to run on the same base distro.\n\nInstead, the rule is:\n\n- jobs that validate production-like runtime behavior or install native runtime dependencies should follow the same Debian family used by the production image and the dev container\n- jobs that only run language-level checks, dependency audits, repository automation, or other host-agnostic validation can stay on `ubuntu-latest`\n\nCurrent Debian-family jobs include:\n\n- the backend job in `CI: Test`\n- the `validate-tests` job in `Release: Create Docker Image`\n\nThose jobs run inside the pinned `python:3.13.12-slim` container because `scripts/install-system-deps` now requires distro-provided ImageMagick 7, while the default Ubuntu GitHub-hosted runner image still resolves `imagemagick` to ImageMagick 6.\n\nCurrent jobs that intentionally remain on `ubuntu-latest` include:\n\n- change-detection, label-sync, and website deployment workflows\n- pure Python lint, lockfile freshness, and dependency-audit workflows\n- frontend-only and companion-only validation workflows\n- Docker build, smoke-test, and vulnerability-scan workflows, where the distro-sensitive logic runs inside the built image rather than on the host runner\n\nWhen adding or changing a workflow, treat runner distro as part of the test contract whenever a job installs OS packages or validates native behavior.\n\n## CI: Check Backend Lockfiles\n\n`CI: Check Backend Lockfiles` protects the reviewed Python dependency workflow.\n\nIt runs `scripts/refresh-backend-lockfiles --check` on pushes, pull requests, and manual runs that touch backend requirement inputs, generated lockfiles, or the refresh script itself.\n\nUse this as the fast failure signal when requirement files and generated lockfiles drift apart.\n\nFor the broader dependency-update workflow, use [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/).\n\n## Admin: Sync Labels\n\n`Admin: Sync Labels` keeps repository labels aligned with `.github/labels.yml`.\n\nIt is intentionally conservative.\n\n- Dependabot-related labels should stay declared in `.github/labels.yml`.\n- The workflow uses `skip-delete: true`, so labels not declared there are left alone.\n\nThat keeps automation-owned labels deterministic without forcing the repository to delete every manually created label.\n\n## Related Workflow Docs\n\nUse the more specific pages for the workflows that have dedicated operational guidance:\n\n- [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/)\n- [Docker Release Overview](../../release-and-versioning/docker-release-overview/)\n- [Companion Release Overview](../../release-and-versioning/companion-release-overview/)\n- [Set Up Cloudflare Pages Publishing](../../../website-dev-guide/setup-and-operations/set-up-cloudflare-pages-publishing/)\n", "0.9": "+++\ntitle = \"CI Workflows and Repository Automation\"\n+++\n\nUse this page to understand the GitHub Actions workflows contributors hit most often and to keep the workflow list grouped predictably in the GitHub UI.\n\n## Naming Convention\n\nGitHub lists workflows by the top-level `name` field.\n\nSambee groups workflow display names by operational purpose using `Area: Subject`.\n\nCurrent workflow groups are:\n\n- `CI`.\n- `Release`.\n- `Deploy`.\n- `Security`.\n- `Admin`.\n\nKeep new names short, stable, and grouped by what the workflow does rather than by how it is triggered.\n\n## Workflow Map\n\n| Display name | File | Role |\n|---|---|---|\n| `CI: Test` | `.github/workflows/test.yml` | Runs the main backend, frontend, and companion validation suites. |\n| `CI: Lint` | `.github/workflows/lint.yml` | Runs repository lint and formatting checks across backend, frontend, and companion. |\n| `CI: Check Backend Lockfiles` | `.github/workflows/check-backend-lockfiles.yml` | Verifies that committed backend lockfiles still match the reviewed requirement sources. |\n| `CI: Validate Docker Image` | `.github/workflows/docker-image-validate.yml` | Builds and smoke-tests the production container image on pull requests, pushes, and manual runs. |\n| `Release: Publish Docker Image` | `.github/workflows/docker-image-publish.yml` | Promotes an existing preview candidate onto release tags and the `stable` or `beta` channel, then signs the digest. |\n| `Release: Create Docker Image` | `.github/workflows/docker-image-preview-publish.yml` | Builds, validates, publishes, and signs a new preview image, forcing a fresh Debian package-layer rebuild for that run before moving the `test` channel tag. |\n| `Maintenance: Backfill Docker Release Tags` | `.github/workflows/docker-image-backfill.yml` | Reattaches release tags and release-channel aliases to an already published candidate digest for an existing release. |\n| `Maintenance: Clean Up Docker Package Versions` | `.github/workflows/docker-image-cleanup.yml` | Removes unprotected SHA-tagged preview GHCR package versions, prunes stale signature artifacts, and deletes unreferenced untagged package versions while preserving release-tagged and channel-protected versions including `test`. |\n| `Release: Build Companion Artifact` | `.github/workflows/build-companion.yml` | Builds companion release artifacts for a new unique version or prerelease candidate in the public distribution repository. |\n| `Release: Promote Companion Release` | `.github/workflows/promote-companion-release.yml` | Moves an existing companion release onto one or more update channels. |\n| `Deploy: Website` | `.github/workflows/website-deploy.yml` | Builds the website and deploys `website/public/` to Cloudflare Pages. |\n| `Security: Dependency Audit` | `.github/workflows/dependency-security.yml` | Runs scheduled and manual dependency vulnerability audits. |\n| `Security: Docker Image Scan` | `.github/workflows/docker-image-security-scan.yml` | Builds the current main image, forces a fresh Debian package-layer rebuild for that run, and scans it for newly disclosed vulnerabilities. |\n| `Admin: Sync Labels` | `.github/workflows/sync-labels.yml` | Synchronizes repository labels from `.github/labels.yml` without deleting unmanaged labels. |\n\nGitHub also shows repository-level features such as `Dependabot updates` and `Dependency graph`.\n\nThose are not repository workflows, so their display names are not controlled by these YAML files.\n\n## CI: Test\n\n`CI: Test` is the main validation workflow for pushes to `main`, pull requests against `main`, and manual dispatch.\n\nIt first detects which top-level product areas changed, then fans out only the relevant jobs for:\n\n- backend\n- frontend\n- frontend Playwright Chromium smoke\n- frontend Playwright Firefox markdown coverage on pushes to `main` and manual runs\n- companion\n\nManual dispatch runs all three areas.\n\nThe workflow ends with a single gate job so branch protection can depend on one stable required check instead of a changing set of per-area jobs.\n\nIn the backend job, regular tests run under `pytest-xdist` for throughput, while `@performance` tests run in a separate serial pass so wall-clock assertions are not distorted by parallel worker contention.\n\nFor frontend coverage, the workflow is intentionally layered:\n\n- the `frontend` job keeps the fast TypeScript, lint, and Vitest checks in the main PR path\n- the `frontend-e2e` job runs a bounded Playwright Chromium smoke slice on frontend changes\n- the `frontend-e2e-firefox` job runs the markdown editor Playwright slice only on pushes to `main` and manual dispatch\n\nThat split keeps pull-request runtime under control while still protecting the browser-sensitive editing workflows that unit tests do not cover.\n\nThe current companion test job does not call `./scripts/test`.\nIt runs explicit steps for Node install, companion TypeScript type checking, and `cargo test`.\nThat means the local Windows GNU cross-check in `./scripts/test` does not currently run in `CI: Test`.\n\n### Caching Model\n\nThe test workflow uses layered caching to reduce repeated setup work while keeping dependency inputs explicit.\n\nCurrent cache layers include:\n\n- `backend/.venv` caching keyed by the resolved backend requirement files and Python version.\n- `backend/.mypy_cache` caching keyed by backend Python source changes.\n- `actions/setup-node` npm download caching for frontend and companion jobs.\n- `frontend/node_modules` caching keyed by `frontend/package-lock.json`.\n- Rust build caching for `companion/src-tauri`.\n\nTreat those cache keys as reviewed dependency inputs, not as disposable generated noise.\n\nWhen dependency manifests or lockfiles change, commit the corresponding lockfile updates in the same pull request so cache invalidation and dependency review stay aligned.\n\n### Local Parity\n\nFor fast local iteration, use `./scripts/test`.\n\nWhen you want a closer CI-style pass, run the per-subsystem checks from [Test Strategy Overview](../test-strategy-overview/) and keep lockfile-driven installs intact.\n\nFor frontend work, that usually means:\n\n- `cd frontend \u0026\u0026 npm test` for the default Vitest suite\n- `cd frontend \u0026\u0026 npm run test:e2e` for the default Chromium browser pass\n\n`./scripts/test` now includes a local companion Windows GNU target compatibility check.\nThat check is intentionally a local validation aid, not part of the current `CI: Test` workflow contract.\n\n## CI: Lint\n\n`CI: Lint` applies the same change-detection pattern, then runs the repository's static checks for only the affected areas.\n\nCurrent coverage includes:\n\n- backend Ruff checks and formatting validation.\n- frontend Biome validation.\n- companion Clippy, Rustfmt, and Biome validation.\n\nThe lint workflow does not run the local companion Windows GNU cross-check either.\nThat cross-target validation is currently a local developer workflow check, while actual Windows artifact creation remains in the release workflow.\n\nThe workflow also ends with one gate job so branch protection can depend on a stable result.\n\n## Runner Distro Policy\n\nSambee does not require every GitHub Actions job to run on the same base distro.\n\nInstead, the rule is:\n\n- jobs that validate production-like runtime behavior or install native runtime dependencies should follow the same Debian family used by the production image and the dev container\n- jobs that only run language-level checks, dependency audits, repository automation, or other host-agnostic validation can stay on `ubuntu-latest`\n\nCurrent Debian-family jobs include:\n\n- the backend job in `CI: Test`\n- the `validate-tests` job in `Release: Create Docker Image`\n\nThe backend job builds the `backend-test` Docker target, which inherits the same runtime base as production. It runs mypy and the backend test suites inside that target, including when a Python image or other runtime input changes. The release validation job uses the pinned Debian-based Python container because `scripts/install-system-deps` requires distro-provided ImageMagick 7, while the default Ubuntu GitHub-hosted runner image still resolves `imagemagick` to ImageMagick 6.\n\n## Shared Runtime Targets\n\nThe root `Dockerfile` defines a shared `runtime-base` target. Production and the VS Code dev container both inherit that target, so they use the same pinned Python image and shared runtime package-installation policy.\n\nBefore building targets, Docker validation confirms that every Python image reference in the Dockerfile uses the same tag and digest. This keeps the native wheel-builder aligned with the shared runtime when Dependabot updates the Python image.\n\n`CI: Validate Docker Image` builds and reports the following values for the production target on each supported image platform and for the devcontainer target on Linux AMD64:\n\n- Python version.\n- `sqlite3` module version.\n- Debian `libsqlite3-0` package version.\n\nThe workflow passes a unique APT refresh key to each build, which intentionally refreshes Debian packages instead of reusing an older cached upgrade layer. The reported versions are evidence of the resolved native runtime; they are not required to match across images built at different times.\n\nCurrent jobs that intentionally remain on `ubuntu-latest` include:\n\n- change-detection, label-sync, and website deployment workflows\n- pure Python lint, lockfile freshness, and dependency-audit workflows\n- frontend-only and companion-only validation workflows\n- Docker build, smoke-test, and vulnerability-scan workflows, where the distro-sensitive logic runs inside the built image rather than on the host runner\n\nWhen adding or changing a workflow, treat runner distro as part of the test contract whenever a job installs OS packages or validates native behavior.\n\n## CI: Check Backend Lockfiles\n\n`CI: Check Backend Lockfiles` protects the reviewed Python dependency workflow.\n\nIt runs `scripts/refresh-backend-lockfiles --check` on pushes, pull requests, and manual runs that touch backend requirement inputs, generated lockfiles, or the refresh script itself.\n\nUse this as the fast failure signal when requirement files and generated lockfiles drift apart.\n\nFor the broader dependency-update workflow, use [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/).\n\n## Admin: Sync Labels\n\n`Admin: Sync Labels` keeps repository labels aligned with `.github/labels.yml`.\n\nIt is intentionally conservative.\n\n- Dependabot-related labels should stay declared in `.github/labels.yml`.\n- The workflow uses `skip-delete: true`, so labels not declared there are left alone.\n\nThat keeps automation-owned labels deterministic without forcing the repository to delete every manually created label.\n\n## Related Workflow Docs\n\nUse the more specific pages for the workflows that have dedicated operational guidance:\n\n- [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/)\n- [Docker Release Overview](../../release-and-versioning/docker-release-overview/)\n- [Companion Release Overview](../../release-and-versioning/companion-release-overview/)\n- [Set Up Cloudflare Pages Publishing](../../../website-dev-guide/setup-and-operations/set-up-cloudflare-pages-publishing/)\n", "1.0": "+++\ntitle = \"CI Workflows and Repository Automation\"\n+++\n\nUse this page to understand the GitHub Actions workflows contributors hit most often and to keep the workflow list grouped predictably in the GitHub UI.\n\n## Naming Convention\n\nGitHub lists workflows by the top-level `name` field.\n\nSambee groups workflow display names by operational purpose using `Area: Subject`.\n\nCurrent workflow groups are:\n\n- `CI`.\n- `Release`.\n- `Deploy`.\n- `Security`.\n- `Admin`.\n\nKeep new names short, stable, and grouped by what the workflow does rather than by how it is triggered.\n\n## Workflow Map\n\n| Display name | File | Role |\n|---|---|---|\n| `CI: Test` | `.github/workflows/test.yml` | Runs the main backend, frontend, and companion validation suites. |\n| `CI: Lint` | `.github/workflows/lint.yml` | Runs repository lint and formatting checks across backend, frontend, and companion. |\n| `CI: Check Backend Lockfiles` | `.github/workflows/check-backend-lockfiles.yml` | Verifies that committed backend lockfiles still match the reviewed requirement sources. |\n| `CI: Validate Docker Image` | `.github/workflows/docker-image-validate.yml` | Builds and smoke-tests the production container image on pull requests, pushes, and manual runs. |\n| `Release: Publish Docker Image` | `.github/workflows/docker-image-publish.yml` | Promotes an existing preview candidate onto release tags and the `stable` or `beta` channel, then signs the digest. |\n| `Release: Create Docker Image` | `.github/workflows/docker-image-preview-publish.yml` | Builds, validates, publishes, and signs a new preview image, forcing a fresh Debian package-layer rebuild for that run before moving the `test` channel tag. |\n| `Maintenance: Backfill Docker Release Tags` | `.github/workflows/docker-image-backfill.yml` | Reattaches release tags and release-channel aliases to an already published candidate digest for an existing release. |\n| `Maintenance: Clean Up Docker Package Versions` | `.github/workflows/docker-image-cleanup.yml` | Removes unprotected SHA-tagged preview GHCR package versions, prunes stale signature artifacts, and deletes unreferenced untagged package versions while preserving release-tagged and channel-protected versions including `test`. |\n| `Release: Build Companion Artifact` | `.github/workflows/build-companion.yml` | Builds companion release artifacts for a new unique version or prerelease candidate in the public distribution repository. |\n| `Release: Promote Companion Release` | `.github/workflows/promote-companion-release.yml` | Moves an existing companion release onto one or more update channels. |\n| `Deploy: Website` | `.github/workflows/website-deploy.yml` | Builds the website and deploys `website/public/` to Cloudflare Pages. |\n| `Security: Dependency Audit` | `.github/workflows/dependency-security.yml` | Runs scheduled and manual dependency vulnerability audits. |\n| `Security: Docker Image Scan` | `.github/workflows/docker-image-security-scan.yml` | Builds the current main image, forces a fresh Debian package-layer rebuild for that run, and scans it for newly disclosed vulnerabilities. |\n| `Admin: Sync Labels` | `.github/workflows/sync-labels.yml` | Synchronizes repository labels from `.github/labels.yml` without deleting unmanaged labels. |\n\nGitHub also shows repository-level features such as `Dependabot updates` and `Dependency graph`.\n\nThose are not repository workflows, so their display names are not controlled by these YAML files.\n\n## CI: Test\n\n`CI: Test` is the main validation workflow for pushes to `main`, pull requests against `main`, and manual dispatch.\n\nIt first detects which top-level product areas changed, then fans out only the relevant jobs for:\n\n- backend\n- frontend\n- frontend Playwright Chromium smoke\n- frontend Playwright Firefox markdown coverage on pushes to `main` and manual runs\n- companion\n\nManual dispatch runs all three areas.\n\nThe workflow ends with a single gate job so branch protection can depend on one stable required check instead of a changing set of per-area jobs.\n\nIn the backend job, regular tests run under `pytest-xdist` for throughput, while `@performance` tests run in a separate serial pass so wall-clock assertions are not distorted by parallel worker contention.\n\nFor frontend coverage, the workflow is intentionally layered:\n\n- the `frontend` job keeps the fast TypeScript, lint, and Vitest checks in the main PR path\n- the `frontend-e2e` job runs a bounded Playwright Chromium smoke slice on frontend changes\n- the `frontend-e2e-firefox` job runs the markdown editor Playwright slice only on pushes to `main` and manual dispatch\n\nThat split keeps pull-request runtime under control while still protecting the browser-sensitive editing workflows that unit tests do not cover.\n\nThe current companion test job does not call `./scripts/test`.\nIt runs explicit steps for Node install, companion TypeScript type checking, and `cargo test`.\nThat means the local Windows GNU cross-check in `./scripts/test` does not currently run in `CI: Test`.\n\n### Caching Model\n\nThe test workflow uses layered caching to reduce repeated setup work while keeping dependency inputs explicit.\n\nCurrent cache layers include:\n\n- `backend/.venv` caching keyed by the resolved backend requirement files and Python version.\n- `backend/.mypy_cache` caching keyed by backend Python source changes.\n- `actions/setup-node` npm download caching for frontend and companion jobs.\n- `frontend/node_modules` caching keyed by `frontend/package-lock.json`.\n- Rust build caching for `companion/src-tauri`.\n\nTreat those cache keys as reviewed dependency inputs, not as disposable generated noise.\n\nWhen dependency manifests or lockfiles change, commit the corresponding lockfile updates in the same pull request so cache invalidation and dependency review stay aligned.\n\n### Local Parity\n\nFor fast local iteration, use `./scripts/test`.\n\nWhen you want a closer CI-style pass, run the per-subsystem checks from [Test Strategy Overview](../test-strategy-overview/) and keep lockfile-driven installs intact.\n\nFor frontend work, that usually means:\n\n- `cd frontend \u0026\u0026 npm test` for the default Vitest suite\n- `cd frontend \u0026\u0026 npm run test:e2e` for the default Chromium browser pass\n\n`./scripts/test` now includes a local companion Windows GNU target compatibility check.\nThat check is intentionally a local validation aid, not part of the current `CI: Test` workflow contract.\n\n## CI: Lint\n\n`CI: Lint` applies the same change-detection pattern, then runs the repository's static checks for only the affected areas.\n\nCurrent coverage includes:\n\n- backend Ruff checks and formatting validation.\n- frontend Biome validation.\n- companion Clippy, Rustfmt, and Biome validation.\n\nThe lint workflow does not run the local companion Windows GNU cross-check either.\nThat cross-target validation is currently a local developer workflow check, while actual Windows artifact creation remains in the release workflow.\n\nThe workflow also ends with one gate job so branch protection can depend on a stable result.\n\n## Runner Distro Policy\n\nSambee does not require every GitHub Actions job to run on the same base distro.\n\nInstead, the rule is:\n\n- jobs that validate production-like runtime behavior or install native runtime dependencies should follow the same Debian family used by the production image and the dev container\n- jobs that only run language-level checks, dependency audits, repository automation, or other host-agnostic validation can stay on `ubuntu-latest`\n\nCurrent Debian-family jobs include:\n\n- the backend job in `CI: Test`\n- the `validate-tests` job in `Release: Create Docker Image`\n\nThe backend job builds the `backend-test` Docker target, which inherits the same runtime base as production. It runs mypy and the backend test suites inside that target, including when a Python image or other runtime input changes. The release validation job uses the pinned Debian-based Python container because `scripts/install-system-deps` requires distro-provided ImageMagick 7, while the default Ubuntu GitHub-hosted runner image still resolves `imagemagick` to ImageMagick 6.\n\n## Shared Runtime Targets\n\nThe root `Dockerfile` defines a shared `runtime-base` target. Production and the VS Code dev container both inherit that target, so they use the same pinned Python image and shared runtime package-installation policy.\n\nBefore building targets, Docker validation confirms that every Python image reference in the Dockerfile uses the same tag and digest. This keeps the native wheel-builder aligned with the shared runtime when Dependabot updates the Python image.\n\n`CI: Validate Docker Image` builds and reports the following values for the production target on each supported image platform and for the devcontainer target on Linux AMD64:\n\n- Python version.\n- `sqlite3` module version.\n- Debian `libsqlite3-0` package version.\n\nThe workflow passes a unique APT refresh key to each build, which intentionally refreshes Debian packages instead of reusing an older cached upgrade layer. The reported versions are evidence of the resolved native runtime; they are not required to match across images built at different times.\n\nCurrent jobs that intentionally remain on `ubuntu-latest` include:\n\n- change-detection, label-sync, and website deployment workflows\n- pure Python lint, lockfile freshness, and dependency-audit workflows\n- frontend-only and companion-only validation workflows\n- Docker build, smoke-test, and vulnerability-scan workflows, where the distro-sensitive logic runs inside the built image rather than on the host runner\n\nWhen adding or changing a workflow, treat runner distro as part of the test contract whenever a job installs OS packages or validates native behavior.\n\n## CI: Check Backend Lockfiles\n\n`CI: Check Backend Lockfiles` protects the reviewed Python dependency workflow.\n\nIt runs `scripts/refresh-backend-lockfiles --check` on pushes, pull requests, and manual runs that touch backend requirement inputs, generated lockfiles, or the refresh script itself.\n\nUse this as the fast failure signal when requirement files and generated lockfiles drift apart.\n\nFor the broader dependency-update workflow, use [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/).\n\n## Admin: Sync Labels\n\n`Admin: Sync Labels` keeps repository labels aligned with `.github/labels.yml`.\n\nIt is intentionally conservative.\n\n- Dependabot-related labels should stay declared in `.github/labels.yml`.\n- The workflow uses `skip-delete: true`, so labels not declared there are left alone.\n\nThat keeps automation-owned labels deterministic without forcing the repository to delete every manually created label.\n\n## Related Workflow Docs\n\nUse the more specific pages for the workflows that have dedicated operational guidance:\n\n- [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/)\n- [Docker Release Overview](../../release-and-versioning/docker-release-overview/)\n- [Companion Release Overview](../../release-and-versioning/companion-release-overview/)\n- [Set Up Cloudflare Pages Publishing](../../../website-dev-guide/setup-and-operations/set-up-cloudflare-pages-publishing/)\n", "2.0": "+++\ntitle = \"CI Workflows and Repository Automation\"\n+++\n\nUse this page to understand the GitHub Actions workflows contributors hit most often and to keep the workflow list grouped predictably in the GitHub UI.\n\n## Naming Convention\n\nGitHub lists workflows by the top-level `name` field.\n\nSambee groups workflow display names by operational purpose using `Area: Subject`.\n\nCurrent workflow groups are:\n\n- `CI`.\n- `Release`.\n- `Deploy`.\n- `Security`.\n- `Admin`.\n\nKeep new names short, stable, and grouped by what the workflow does rather than by how it is triggered.\n\n## Workflow Map\n\n| Display name | File | Role |\n|---|---|---|\n| `CI: Test` | `.github/workflows/test.yml` | Runs the main backend, frontend, and companion validation suites. |\n| `CI: Lint` | `.github/workflows/lint.yml` | Runs repository lint and formatting checks across backend, frontend, and companion. |\n| `CI: Check Backend Lockfiles` | `.github/workflows/check-backend-lockfiles.yml` | Verifies that committed backend lockfiles still match the reviewed requirement sources. |\n| `CI: Validate Docker Image` | `.github/workflows/docker-image-validate.yml` | Builds and smoke-tests the production container image on pull requests, pushes, and manual runs. |\n| `Release: Publish Docker Image` | `.github/workflows/docker-image-publish.yml` | Promotes an existing preview candidate onto release tags and the `stable` or `beta` channel, then signs the digest. |\n| `Release: Create Docker Image` | `.github/workflows/docker-image-preview-publish.yml` | Builds, validates, publishes, and signs a new preview image, forcing a fresh Debian package-layer rebuild for that run before moving the `test` channel tag. |\n| `Maintenance: Backfill Docker Release Tags` | `.github/workflows/docker-image-backfill.yml` | Reattaches release tags and release-channel aliases to an already published candidate digest for an existing release. |\n| `Maintenance: Clean Up Docker Package Versions` | `.github/workflows/docker-image-cleanup.yml` | Removes unprotected SHA-tagged preview GHCR package versions, prunes stale signature artifacts, and deletes unreferenced untagged package versions while preserving release-tagged and channel-protected versions including `test`. |\n| `Maintenance: Clean Up Actions Caches` | `.github/workflows/cleanup-actions-caches.yml` | Removes closed-PR caches and superseded known cache keys without disabling warm caches for active builds. |\n| `Maintenance: Signal Closed PR Cache Cleanup` | `.github/workflows/signal-closed-pr-cache-cleanup.yml` | Triggers cache cleanup after a pull request closes without granting the pull request write access. |\n| `Release: Build Companion Artifact` | `.github/workflows/build-companion.yml` | Builds companion release artifacts for a new unique version or prerelease candidate in the public distribution repository. |\n| `Release: Promote Companion Release` | `.github/workflows/promote-companion-release.yml` | Moves an existing companion release onto one or more update channels. |\n| `Deploy: Website` | `.github/workflows/website-deploy.yml` | Builds the website and deploys `website/public/` to Cloudflare Pages. |\n| `Security: Dependency Audit` | `.github/workflows/dependency-security.yml` | Runs scheduled and manual dependency vulnerability audits. |\n| `Security: Docker Image Scan` | `.github/workflows/docker-image-security-scan.yml` | Builds the current main image, forces a fresh Debian package-layer rebuild for that run, and scans it for newly disclosed vulnerabilities. |\n| `Admin: Sync Labels` | `.github/workflows/sync-labels.yml` | Synchronizes repository labels from `.github/labels.yml` without deleting unmanaged labels. |\n\nGitHub also shows repository-level features such as `Dependabot updates` and `Dependency graph`.\n\nThose are not repository workflows, so their display names are not controlled by these YAML files.\n\n## CI: Test\n\n`CI: Test` is the main validation workflow for pushes to `main`, pull requests against `main`, and manual dispatch.\n\nIt first detects which top-level product areas changed, then fans out only the relevant jobs for:\n\n- backend\n- frontend, including Chromium and Firefox browser correctness\n- companion\n- website documentation\n\nManual dispatch runs all areas. Changes to shared frontend CI infrastructure also select frontend validation.\n\nThe workflow ends with a single gate job so branch protection can depend on one stable required check instead of a changing set of per-area jobs.\n\nIn the backend job, regular tests run under `pytest-xdist` for throughput, while `@performance` tests run in a separate serial pass so wall-clock assertions are not distorted by parallel worker contention.\n\nBackend pytest runs treat unexpected warnings as errors, including resource-cleanup warnings. The shared policy in `backend/pyproject.toml` applies to both local and CI runs, and warning summaries aren't suppressed. Tests that deliberately trigger a warning must assert it with `pytest.warns(...)`, matching the warning category and message. Fix application warnings rather than ignoring them. Unavoidable dependency exceptions must be narrowly scoped and documented; the current exception covers Starlette's TestClient reference to AnyIO's deprecated `BlockingPortal` alias. Remove that exception when the dependency no longer needs it.\n\nThe `frontend` job requires a clean TypeScript check, runs Vitest, builds normal production assets, installs version-matched Playwright Chromium/Firefox binaries and their Linux dependencies, then runs `npm run test:browser:ci`. Both engines run on frontend pull requests, pushes, and manual dispatch. The same required checks run in release fallback when successful source CI cannot be reused.\n\nThe browser command requires exactly 16 production cases: four scenarios at desktop and narrow widths in each engine. They protect real normalization/syntax workers, entity decoding, native selection/focus/heading links/search, regex replacement with undo/redo and exact Save content, and cancellation/reopen cleanup with stale-result replay. Two additional development-worker cases exercise Vite's dependency-resolution path. Browser APIs and workers are real; backend responses are mocked at `http://localhost:3000/browse/smb/demo`. This isn't full-stack SMB E2E or evidence of physical printing, browser-menu Find, hardware IME, or assistive-technology behavior.\n\nThe correctness reporter rejects missing, duplicate, skipped, failed, and retried cases. Browser cases run with one worker and no retries. Reports and retained failure traces/screenshots are uploaded for seven days. Timing budgets, profiling, heap measurements, alternate renderers, and repeated cache/performance matrices remain separate opt-in diagnostics.\n\n`npm run typecheck` runs `tsc -b --noEmit` across the application, test/helper, and Node configuration projects. Browser code uses browser types; tests add Vitest and Node types; configuration tooling uses Node types. All source and declaration files remain checked with strict null/index and unused-code diagnostics enabled. The ES2023 library declarations describe existing APIs; the emitted target remains ES2020, and declarations don't provide runtime polyfills.\n\nType correctness is mandatory in routine CI, release fallback, ordinary `npm run build`, `./scripts/test`, and the VS Code frontend validation task. The old root `tsc --noEmit` command checked no input files and mustn't be used as a substitute. Regression tests protect required command wiring, strict options, separate environments, and complete source coverage. Unit and browser correctness remain independent required gates.\n\nThe required gate rejects an unexpectedly skipped selected job. Only unrelated, unselected areas may be skipped. Superseded pull-request test/lint runs are cancelled; main-branch validation runs aren't cancelled by that policy. Release reuse requires the exact source commit's successful frontend job, its successful browser-correctness step, and the new required `Verify frontend type correctness` step. Missing, skipped, or failed steps and legacy advisory type-check runs don't qualify.\n\nThe current companion test job does not call `./scripts/test`.\nIt runs explicit steps for Node install, companion TypeScript type checking, and the archive topology conformance script, including Rust tests, formatting, and Clippy.\nThat means the local Windows GNU cross-check in `./scripts/test` does not currently run in `CI: Test`.\n\n### Caching Model\n\nThe test workflow uses layered caching to reduce repeated setup work while keeping dependency inputs explicit.\n\nCurrent cache layers include:\n\n- GitHub Actions BuildKit caching for the `backend-test` Docker target, with dependency layers before source copies.\n- `actions/setup-node` npm download caching for frontend and companion jobs.\n- Rust build caching for `companion/src-tauri`.\n\nFrontend jobs use clean `npm ci --prefer-offline` installs; they don't cache `node_modules` or Playwright browser downloads. The mypy cache inside the disposable backend test container isn't persisted separately.\n\nVitest file parallelism is capped at four workers and further limited by the runner's available CPUs and RAM, reserving 2 GiB plus 2 GiB per worker. The CI command logs the actual resources and selected cap. Standard public Ubuntu runners currently provide 4 vCPUs/16 GB RAM; private runners provide 2 vCPUs/8 GB RAM. Local measurements on a larger machine aren't Actions performance guarantees.\n\nTreat those cache keys as reviewed dependency inputs, not as disposable generated noise.\n\nWhen dependency manifests or lockfiles change, commit the corresponding lockfile updates in the same pull request so cache invalidation and dependency review stay aligned.\n\n### Cache Retention\n\n`Maintenance: Clean Up Actions Caches` runs after cache-producing workflows finish and daily as a fallback. When a pull request closes, an unprivileged signal workflow runs first; its completion triggers the same cleanup. A manual run defaults to a dry run; select **Delete eligible caches** to apply the policy. Its run summary lists selected entries and the amount of storage reclaimed. The cleanup reads only trusted code from `main`, and does not run pull-request code with cache-deletion permissions.\n\nThe policy keeps the newest known cache family on `main` and each open pull request. It removes superseded Rust and website cache keys, and deletes all caches for a closed pull request after its builds finish. It skips refs with active builds and leaves unrecognized keys, including individual BuildKit blobs on active refs, alone. GitHub's normal expiration still applies to those unclassified entries. The job deletes caches by ID so a pull request's copy cannot inadvertently delete an identically keyed cache on `main`.\n\nReview the dry-run report before changing cache-family rules. If active caches alone approach the repository storage limit, raise the limit or accept more cache misses: deleting their newest copies would make CI slower. Cleanup happens after cache uploads, so it cannot prevent a full repository from evicting caches during an upload.\n\n### Local Parity\n\nFor fast local iteration, use `./scripts/test`.\n\nWhen you want a closer CI-style pass, run the per-subsystem checks from [Test Strategy Overview](../test-strategy-overview/) and keep lockfile-driven installs intact.\n\nFor frontend work, that usually means:\n\n- `cd frontend \u0026\u0026 npm run test` for the default Vitest suite\n- `cd frontend \u0026\u0026 npm run test:ci` for runner-aware Vitest concurrency\n- `cd frontend \u0026\u0026 npm run typecheck` for the complete strict compiler check\n- `cd frontend \u0026\u0026 npm run build` followed by `npm run test:browser:ci` for the exact production/development browser contract\n- `cd frontend \u0026\u0026 npm run test:e2e:install -- --with-deps` to install the matching browsers and Linux dependencies\n\n`./scripts/test` now includes a local companion Windows GNU target compatibility check.\nThat check is intentionally a local validation aid, not part of the current `CI: Test` workflow contract.\n\n## CI: Lint\n\n`CI: Lint` applies the same change-detection pattern, then runs the repository's static checks for only the affected areas.\n\nCurrent coverage includes:\n\n- backend Ruff checks and formatting validation.\n- frontend Biome validation.\n- companion Clippy, Rustfmt, and Biome validation.\n\nRuff's executable-script rules (`EXE`) also check Python files throughout the repository, including `.github/`. Any Python-file change selects backend lint, as do changes to the lint workflow or `scripts/test`. These checks fail CI and `./scripts/test` on errors; they aren't advisory. A script with a shebang must be executable. Files invoked explicitly through Python, and imported modules, don't need a shebang.\n\nThe lint workflow does not run the local companion Windows GNU cross-check either.\nThat cross-target validation is currently a local developer workflow check, while actual Windows artifact creation remains in the release workflow.\n\nThe workflow also ends with one gate job so branch protection can depend on a stable result.\n\n## Runner Distro Policy\n\nAll Ubuntu x64 host jobs use `ubuntu-latest`, following GitHub's managed OS migrations and runner-image updates. Native ARM64 image matrices use `ubuntu-26.04-arm`; GitHub doesn't currently document an `ubuntu-latest-arm` label. Windows and macOS coverage remains on its own platform runners.\n\nHost runner choice doesn't replace production-runtime validation. Debian-family checks still include the backend test container and the release `validate-tests` container.\n\nThe backend job builds the `backend-test` Docker target, which inherits the same runtime base as production. It runs mypy and the backend test suites inside that target, including when a Python image or other runtime input changes. The release validation job uses the pinned Debian-based Python container because `scripts/install-system-deps` requires distro-provided ImageMagick 7, while the default Ubuntu GitHub-hosted runner image still resolves `imagemagick` to ImageMagick 6.\n\n## Shared Runtime Targets\n\nThe root `Dockerfile` defines a shared `runtime-base` target. Production and the VS Code dev container both inherit that target, so they use the same pinned Python image and shared runtime package-installation policy.\n\nBefore building targets, Docker validation confirms that every Python image reference in the Dockerfile uses the same tag and digest. This keeps the native wheel-builder aligned with the shared runtime when Dependabot updates the Python image.\n\n`CI: Validate Docker Image` builds and reports the following values for the production target on each supported image platform and for the devcontainer target on Linux AMD64:\n\n- Python version.\n- `sqlite3` module version.\n- Debian `libsqlite3-0` package version.\n\nThe workflow passes a unique APT refresh key to each build, which intentionally refreshes Debian packages instead of reusing an older cached upgrade layer. The reported versions are evidence of the resolved native runtime; they are not required to match across images built at different times.\n\nCurrent jobs that intentionally remain on `ubuntu-latest` include:\n\n- change-detection, label-sync, and website deployment workflows\n- pure Python lint, lockfile freshness, and dependency-audit workflows\n- frontend-only and companion-only validation workflows\n- Docker build, smoke-test, and vulnerability-scan workflows, where the distro-sensitive logic runs inside the built image rather than on the host runner\n\nWhen adding or changing a workflow, treat runner distro as part of the test contract whenever a job installs OS packages or validates native behavior.\n\n## CI: Check Backend Lockfiles\n\n`CI: Check Backend Lockfiles` protects the reviewed Python dependency workflow.\n\nIt runs `scripts/refresh-backend-lockfiles --check` on pushes, pull requests, and manual runs that touch backend requirement inputs, generated lockfiles, or the refresh script itself.\n\nUse this as the fast failure signal when requirement files and generated lockfiles drift apart.\n\nFor the broader dependency-update workflow, use [Dependency Update Workflow](../../release-and-versioning/dependency-update-workflow/).\n\n## Admin: Sync Labels\n\n`Admin: Sync Labels` keeps repository labels aligned with `.github/labels.yml`.\n\nIt is intentionally conservative.\n\n- Dependabot-related labels should stay declared in `.github/labels.yml`.\n- The workflow uses `skip-delete: true`, so labels not declared there are left alone.\n\nThat keeps automation-owned labels deterministic without forcing the repository to delete every manually created label.\n\n## Related Workflow Docs\n\nUse the more specific pages for the workflows that have dedicated operational guidance:\n\n- [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/)\n- [Docker Release Overview](../../release-and-versioning/docker-release-overview/)\n- [Companion Release Overview](../../release-and-versioning/companion-release-overview/)\n- [Set Up Cloudflare Pages Publishing](../../../website-dev-guide/setup-and-operations/set-up-cloudflare-pages-publishing/)\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:developer-guide/contribution-workflows", "parent_id": "book:developer-guide", "depth": 1, "kind": "section", "label": "contribution-workflows", "title": "Contribution Workflows", "path": "developer-guide/contribution-workflows", "has_children": true, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Contribution Workflows\"\n+++\n\nThis section is about how to approach a Sambee change before it becomes a pile of disconnected file edits.\n\nStart with:\n\n- [How to Plan and Review a Change](./how-to-plan-and-review-a-change/)\n\nUse this section when you are scoping work, preparing a review, or deciding whether a change also needs wider testing or version-sensitive follow-up.\n", "0.8": "+++\ntitle = \"Contribution Workflows\"\n+++\n\nThis section is about how to approach a Sambee change before it becomes a pile of disconnected file edits.\n\nStart with:\n\n- [How to Plan and Review a Change](./how-to-plan-and-review-a-change/)\n\nUse this section when you are scoping work, preparing a review, or deciding whether a change also needs wider testing or version-sensitive follow-up.\n", "0.9": "+++\ntitle = \"Contribution Workflows\"\n+++\n\nThis section is about how to approach a Sambee change before it becomes a pile of disconnected file edits.\n\nStart with:\n\n- [How to Plan and Review a Change](./how-to-plan-and-review-a-change/)\n\nUse this section when you are scoping work, preparing a review, or deciding whether a change also needs wider testing or version-sensitive follow-up.\n", "1.0": "+++\ntitle = \"Contribution Workflows\"\n+++\n\nThis section is about how to approach a Sambee change before it becomes a pile of disconnected file edits.\n\nStart with:\n\n- [How to Plan and Review a Change](./how-to-plan-and-review-a-change/)\n\nUse this section when you are scoping work, preparing a review, or deciding whether a change also needs wider testing or version-sensitive follow-up.\n", "2.0": "+++\ntitle = \"Contribution Workflows\"\n+++\n\nThis section is about how to approach a Sambee change before it becomes a pile of disconnected file edits.\n\nStart with:\n\n- [How to Plan and Review a Change](./how-to-plan-and-review-a-change/)\n\nUse this section when you are scoping work, preparing a review, or deciding whether a change also needs wider testing or version-sensitive follow-up.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/contribution-workflows/how-to-plan-and-review-a-change", "parent_id": "section:developer-guide/contribution-workflows", "depth": 2, "kind": "page", "label": "how-to-plan-and-review-a-change", "title": "How To Plan And Review A Change", "path": "developer-guide/contribution-workflows/how-to-plan-and-review-a-change", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"How to Plan and Review a Change\"\n+++\n\nThe safest Sambee changes start from the contract that is changing, not from the first file you happened to open.\n\n## Start with the Contract\n\nAsk which part of the system's behavior is actually moving.\n\n- browser app workflow\n- backend API or SMB behavior\n- companion trust, local-drive, or native-app editing behavior\n- release-sensitive metadata or dependency policy\n\nThat answer tells you which subsystems might need to move together.\n\n## Scope the Change by Boundary\n\nBefore you implement anything, identify:\n\n1. which subsystem changes directly\n2. which other subsystem consumes the changed contract\n\nFor example:\n\n- a backend response-shape change usually also needs frontend service updates and matching validation\n- a companion pairing change may affect browser app behavior and tests in more than one project\n\n## Prefer the Smallest Change That Fixes the Right Problem\n\n- fix the root cause instead of layering extra workarounds on top\n- avoid mixing unrelated refactors into a behavior change unless they are required for correctness\n- do not treat lockfiles, version metadata, or generated navigation inputs as incidental noise when they are part of the reviewed workflow\n\n## Review with Regression Risk in Mind\n\nThe highest-value review questions are usually:\n\n- did the changed contract stay coherent across browser app, backend, and companion?\n- are new or changed validation checks proportional to the risk?\n- did a version-sensitive or dependency-sensitive workflow change without the matching metadata review?\n\n## Typical Review Checklist\n\n- the change goal is stated in terms of behavior, not just files touched\n- cross-boundary contracts were updated together\n- validation covers the actual risk surface\n- release-sensitive files were reviewed intentionally when touched\n", "0.8": "+++\ntitle = \"How to Plan and Review a Change\"\n+++\n\nThe safest Sambee changes start from the contract that is changing, not from the first file you happened to open.\n\n## Start with the Contract\n\nAsk which part of the system's behavior is actually moving.\n\n- browser app workflow\n- backend API or SMB behavior\n- companion trust, local-drive, or native-app editing behavior\n- release-sensitive metadata or dependency policy\n\nThat answer tells you which subsystems might need to move together.\n\n## Scope the Change by Boundary\n\nBefore you implement anything, identify:\n\n1. which subsystem changes directly\n2. which other subsystem consumes the changed contract\n\nFor example:\n\n- a backend response-shape change usually also needs frontend service updates and matching validation\n- a companion pairing change may affect browser app behavior and tests in more than one project\n\n## Prefer the Smallest Change That Fixes the Right Problem\n\n- fix the root cause instead of layering extra workarounds on top\n- avoid mixing unrelated refactors into a behavior change unless they are required for correctness\n- do not treat lockfiles, version metadata, or generated navigation inputs as incidental noise when they are part of the reviewed workflow\n\n## Review with Regression Risk in Mind\n\nThe highest-value review questions are usually:\n\n- did the changed contract stay coherent across browser app, backend, and companion?\n- are new or changed validation checks proportional to the risk?\n- did a version-sensitive or dependency-sensitive workflow change without the matching metadata review?\n\n## Typical Review Checklist\n\n- the change goal is stated in terms of behavior, not just files touched\n- cross-boundary contracts were updated together\n- validation covers the actual risk surface\n- release-sensitive files were reviewed intentionally when touched\n", "0.9": "+++\ntitle = \"How to Plan and Review a Change\"\n+++\n\nThe safest Sambee changes start from the contract that is changing, not from the first file you happened to open.\n\n## Start with the Contract\n\nAsk which part of the system's behavior is actually moving.\n\n- browser app workflow\n- backend API or SMB behavior\n- companion trust, local-drive, or native-app editing behavior\n- release-sensitive metadata or dependency policy\n\nThat answer tells you which subsystems might need to move together.\n\n## Scope the Change by Boundary\n\nBefore you implement anything, identify:\n\n1. which subsystem changes directly\n2. which other subsystem consumes the changed contract\n\nFor example:\n\n- a backend response-shape change usually also needs frontend service updates and matching validation\n- a companion pairing change may affect browser app behavior and tests in more than one project\n\n## Prefer the Smallest Change That Fixes the Right Problem\n\n- fix the root cause instead of layering extra workarounds on top\n- avoid mixing unrelated refactors into a behavior change unless they are required for correctness\n- do not treat lockfiles, version metadata, or generated navigation inputs as incidental noise when they are part of the reviewed workflow\n\n## Review with Regression Risk in Mind\n\nThe highest-value review questions are usually:\n\n- did the changed contract stay coherent across browser app, backend, and companion?\n- are new or changed validation checks proportional to the risk?\n- did a version-sensitive or dependency-sensitive workflow change without the matching metadata review?\n\n## Typical Review Checklist\n\n- the change goal is stated in terms of behavior, not just files touched\n- cross-boundary contracts were updated together\n- validation covers the actual risk surface\n- release-sensitive files were reviewed intentionally when touched\n", "1.0": "+++\ntitle = \"How to Plan and Review a Change\"\n+++\n\nThe safest Sambee changes start from the contract that is changing, not from the first file you happened to open.\n\n## Start with the Contract\n\nAsk which part of the system's behavior is actually moving.\n\n- browser app workflow\n- backend API or SMB behavior\n- companion trust, local-drive, or native-app editing behavior\n- release-sensitive metadata or dependency policy\n\nThat answer tells you which subsystems might need to move together.\n\n## Scope the Change by Boundary\n\nBefore you implement anything, identify:\n\n1. which subsystem changes directly\n2. which other subsystem consumes the changed contract\n\nFor example:\n\n- a backend response-shape change usually also needs frontend service updates and matching validation\n- a companion pairing change may affect browser app behavior and tests in more than one project\n\n## Prefer the Smallest Change That Fixes the Right Problem\n\n- fix the root cause instead of layering extra workarounds on top\n- avoid mixing unrelated refactors into a behavior change unless they are required for correctness\n- do not treat lockfiles, version metadata, or generated navigation inputs as incidental noise when they are part of the reviewed workflow\n\n## Review with Regression Risk in Mind\n\nThe highest-value review questions are usually:\n\n- did the changed contract stay coherent across browser app, backend, and companion?\n- are new or changed validation checks proportional to the risk?\n- did a version-sensitive or dependency-sensitive workflow change without the matching metadata review?\n\n## Typical Review Checklist\n\n- the change goal is stated in terms of behavior, not just files touched\n- cross-boundary contracts were updated together\n- validation covers the actual risk surface\n- release-sensitive files were reviewed intentionally when touched\n", "2.0": "+++\ntitle = \"How to Plan and Review a Change\"\n+++\n\nThe safest Sambee changes start from the contract that is changing, not from the first file you happened to open.\n\n## Start with the Contract\n\nAsk which part of the system's behavior is actually moving.\n\n- browser app workflow\n- backend API or SMB behavior\n- companion trust, local-drive, or native-app editing behavior\n- release-sensitive metadata or dependency policy\n\nThat answer tells you which subsystems might need to move together.\n\n## Scope the Change by Boundary\n\nBefore you implement anything, identify:\n\n1. which subsystem changes directly\n2. which other subsystem consumes the changed contract\n\nFor example:\n\n- a backend response-shape change usually also needs frontend service updates and matching validation\n- a companion pairing change may affect browser app behavior and tests in more than one project\n\n## Prefer the Smallest Change That Fixes the Right Problem\n\n- fix the root cause instead of layering extra workarounds on top\n- avoid mixing unrelated refactors into a behavior change unless they are required for correctness\n- do not treat lockfiles, version metadata, or generated navigation inputs as incidental noise when they are part of the reviewed workflow\n\n## Review with Regression Risk in Mind\n\nThe highest-value review questions are usually:\n\n- did the changed contract stay coherent across browser app, backend, and companion?\n- are new or changed validation checks proportional to the risk?\n- did a version-sensitive or dependency-sensitive workflow change without the matching metadata review?\n\n## Typical Review Checklist\n\n- the change goal is stated in terms of behavior, not just files touched\n- cross-boundary contracts were updated together\n- validation covers the actual risk surface\n- release-sensitive files were reviewed intentionally when touched\n"}, "page_contents": {"0.7": "+++\ntitle = \"How to Plan and Review a Change\"\n+++\n\nThe safest Sambee changes start from the contract that is changing, not from the first file you happened to open.\n\n## Start with the Contract\n\nAsk which part of the system's behavior is actually moving.\n\n- browser app workflow\n- backend API or SMB behavior\n- companion trust, local-drive, or native-app editing behavior\n- release-sensitive metadata or dependency policy\n\nThat answer tells you which subsystems might need to move together.\n\n## Scope the Change by Boundary\n\nBefore you implement anything, identify:\n\n1. which subsystem changes directly\n2. which other subsystem consumes the changed contract\n\nFor example:\n\n- a backend response-shape change usually also needs frontend service updates and matching validation\n- a companion pairing change may affect browser app behavior and tests in more than one project\n\n## Prefer the Smallest Change That Fixes the Right Problem\n\n- fix the root cause instead of layering extra workarounds on top\n- avoid mixing unrelated refactors into a behavior change unless they are required for correctness\n- do not treat lockfiles, version metadata, or generated navigation inputs as incidental noise when they are part of the reviewed workflow\n\n## Review with Regression Risk in Mind\n\nThe highest-value review questions are usually:\n\n- did the changed contract stay coherent across browser app, backend, and companion?\n- are new or changed validation checks proportional to the risk?\n- did a version-sensitive or dependency-sensitive workflow change without the matching metadata review?\n\n## Typical Review Checklist\n\n- the change goal is stated in terms of behavior, not just files touched\n- cross-boundary contracts were updated together\n- validation covers the actual risk surface\n- release-sensitive files were reviewed intentionally when touched\n", "0.8": "+++\ntitle = \"How to Plan and Review a Change\"\n+++\n\nThe safest Sambee changes start from the contract that is changing, not from the first file you happened to open.\n\n## Start with the Contract\n\nAsk which part of the system's behavior is actually moving.\n\n- browser app workflow\n- backend API or SMB behavior\n- companion trust, local-drive, or native-app editing behavior\n- release-sensitive metadata or dependency policy\n\nThat answer tells you which subsystems might need to move together.\n\n## Scope the Change by Boundary\n\nBefore you implement anything, identify:\n\n1. which subsystem changes directly\n2. which other subsystem consumes the changed contract\n\nFor example:\n\n- a backend response-shape change usually also needs frontend service updates and matching validation\n- a companion pairing change may affect browser app behavior and tests in more than one project\n\n## Prefer the Smallest Change That Fixes the Right Problem\n\n- fix the root cause instead of layering extra workarounds on top\n- avoid mixing unrelated refactors into a behavior change unless they are required for correctness\n- do not treat lockfiles, version metadata, or generated navigation inputs as incidental noise when they are part of the reviewed workflow\n\n## Review with Regression Risk in Mind\n\nThe highest-value review questions are usually:\n\n- did the changed contract stay coherent across browser app, backend, and companion?\n- are new or changed validation checks proportional to the risk?\n- did a version-sensitive or dependency-sensitive workflow change without the matching metadata review?\n\n## Typical Review Checklist\n\n- the change goal is stated in terms of behavior, not just files touched\n- cross-boundary contracts were updated together\n- validation covers the actual risk surface\n- release-sensitive files were reviewed intentionally when touched\n", "0.9": "+++\ntitle = \"How to Plan and Review a Change\"\n+++\n\nThe safest Sambee changes start from the contract that is changing, not from the first file you happened to open.\n\n## Start with the Contract\n\nAsk which part of the system's behavior is actually moving.\n\n- browser app workflow\n- backend API or SMB behavior\n- companion trust, local-drive, or native-app editing behavior\n- release-sensitive metadata or dependency policy\n\nThat answer tells you which subsystems might need to move together.\n\n## Scope the Change by Boundary\n\nBefore you implement anything, identify:\n\n1. which subsystem changes directly\n2. which other subsystem consumes the changed contract\n\nFor example:\n\n- a backend response-shape change usually also needs frontend service updates and matching validation\n- a companion pairing change may affect browser app behavior and tests in more than one project\n\n## Prefer the Smallest Change That Fixes the Right Problem\n\n- fix the root cause instead of layering extra workarounds on top\n- avoid mixing unrelated refactors into a behavior change unless they are required for correctness\n- do not treat lockfiles, version metadata, or generated navigation inputs as incidental noise when they are part of the reviewed workflow\n\n## Review with Regression Risk in Mind\n\nThe highest-value review questions are usually:\n\n- did the changed contract stay coherent across browser app, backend, and companion?\n- are new or changed validation checks proportional to the risk?\n- did a version-sensitive or dependency-sensitive workflow change without the matching metadata review?\n\n## Typical Review Checklist\n\n- the change goal is stated in terms of behavior, not just files touched\n- cross-boundary contracts were updated together\n- validation covers the actual risk surface\n- release-sensitive files were reviewed intentionally when touched\n", "1.0": "+++\ntitle = \"How to Plan and Review a Change\"\n+++\n\nThe safest Sambee changes start from the contract that is changing, not from the first file you happened to open.\n\n## Start with the Contract\n\nAsk which part of the system's behavior is actually moving.\n\n- browser app workflow\n- backend API or SMB behavior\n- companion trust, local-drive, or native-app editing behavior\n- release-sensitive metadata or dependency policy\n\nThat answer tells you which subsystems might need to move together.\n\n## Scope the Change by Boundary\n\nBefore you implement anything, identify:\n\n1. which subsystem changes directly\n2. which other subsystem consumes the changed contract\n\nFor example:\n\n- a backend response-shape change usually also needs frontend service updates and matching validation\n- a companion pairing change may affect browser app behavior and tests in more than one project\n\n## Prefer the Smallest Change That Fixes the Right Problem\n\n- fix the root cause instead of layering extra workarounds on top\n- avoid mixing unrelated refactors into a behavior change unless they are required for correctness\n- do not treat lockfiles, version metadata, or generated navigation inputs as incidental noise when they are part of the reviewed workflow\n\n## Review with Regression Risk in Mind\n\nThe highest-value review questions are usually:\n\n- did the changed contract stay coherent across browser app, backend, and companion?\n- are new or changed validation checks proportional to the risk?\n- did a version-sensitive or dependency-sensitive workflow change without the matching metadata review?\n\n## Typical Review Checklist\n\n- the change goal is stated in terms of behavior, not just files touched\n- cross-boundary contracts were updated together\n- validation covers the actual risk surface\n- release-sensitive files were reviewed intentionally when touched\n", "2.0": "+++\ntitle = \"How to Plan and Review a Change\"\n+++\n\nThe safest Sambee changes start from the contract that is changing, not from the first file you happened to open.\n\n## Start with the Contract\n\nAsk which part of the system's behavior is actually moving.\n\n- browser app workflow\n- backend API or SMB behavior\n- companion trust, local-drive, or native-app editing behavior\n- release-sensitive metadata or dependency policy\n\nThat answer tells you which subsystems might need to move together.\n\n## Scope the Change by Boundary\n\nBefore you implement anything, identify:\n\n1. which subsystem changes directly\n2. which other subsystem consumes the changed contract\n\nFor example:\n\n- a backend response-shape change usually also needs frontend service updates and matching validation\n- a companion pairing change may affect browser app behavior and tests in more than one project\n\n## Prefer the Smallest Change That Fixes the Right Problem\n\n- fix the root cause instead of layering extra workarounds on top\n- avoid mixing unrelated refactors into a behavior change unless they are required for correctness\n- do not treat lockfiles, version metadata, or generated navigation inputs as incidental noise when they are part of the reviewed workflow\n\n## Review with Regression Risk in Mind\n\nThe highest-value review questions are usually:\n\n- did the changed contract stay coherent across browser app, backend, and companion?\n- are new or changed validation checks proportional to the risk?\n- did a version-sensitive or dependency-sensitive workflow change without the matching metadata review?\n\n## Typical Review Checklist\n\n- the change goal is stated in terms of behavior, not just files touched\n- cross-boundary contracts were updated together\n- validation covers the actual risk surface\n- release-sensitive files were reviewed intentionally when touched\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:developer-guide/security", "parent_id": "book:developer-guide", "depth": 1, "kind": "section", "label": "security", "title": "Security", "path": "developer-guide/security", "has_children": true, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Security\"\n+++\n\nUse this section when the next question is about dependency intake, vulnerability scanning, or release-artifact trust.\n\nStart with:\n\n- [Dependency Security and Dependabot](./dependency-security-and-dependabot/)\n- [Container Image Security and Artifact Integrity](./container-image-security-and-artifact-integrity/)\n\nThis section focuses on supply-chain and release-security automation.\n\nFor product-boundary security design inside the app itself, keep using the architecture pages that document the backend preview pipeline, browser-to-companion trust model, and other security-sensitive subsystems.\n\n", "0.8": "+++\ntitle = \"Security\"\n+++\n\nUse this section when the next question is about dependency intake, vulnerability scanning, or release-artifact trust.\n\nStart with:\n\n- [Dependency Security and Dependabot](./dependency-security-and-dependabot/)\n- [Container Image Security and Artifact Integrity](./container-image-security-and-artifact-integrity/)\n\nThis section focuses on supply-chain and release-security automation.\n\nFor product-boundary security design inside the app itself, keep using the architecture pages that document the backend preview pipeline, browser-to-companion trust model, and other security-sensitive subsystems.\n\n", "0.9": "+++\ntitle = \"Security\"\n+++\n\nUse this section when the next question is about dependency intake, vulnerability scanning, or release-artifact trust.\n\nStart with:\n\n- [Dependency Security and Dependabot](./dependency-security-and-dependabot/)\n- [Container Image Security and Artifact Integrity](./container-image-security-and-artifact-integrity/)\n\nThis section focuses on supply-chain and release-security automation.\n\nFor product-boundary security design inside the app itself, keep using the architecture pages that document the backend preview pipeline, browser-to-companion trust model, and other security-sensitive subsystems.\n\n", "1.0": "+++\ntitle = \"Security\"\n+++\n\nUse this section when the next question is about dependency intake, vulnerability scanning, or release-artifact trust.\n\nStart with:\n\n- [Dependency Security and Dependabot](./dependency-security-and-dependabot/)\n- [Container Image Security and Artifact Integrity](./container-image-security-and-artifact-integrity/)\n\nThis section focuses on supply-chain and release-security automation.\n\nFor product-boundary security design inside the app itself, keep using the architecture pages that document the backend preview pipeline, browser-to-companion trust model, and other security-sensitive subsystems.\n\n", "2.0": "+++\ntitle = \"Security\"\n+++\n\nUse this section when the next question is about dependency intake, vulnerability scanning, or release-artifact trust.\n\nStart with:\n\n- [Dependency Security and Dependabot](./dependency-security-and-dependabot/)\n- [Container Image Security and Artifact Integrity](./container-image-security-and-artifact-integrity/)\n\nThis section focuses on supply-chain and release-security automation.\n\nFor product-boundary security design inside the app itself, keep using the architecture pages that document the backend preview pipeline, browser-to-companion trust model, and other security-sensitive subsystems.\n\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/security/dependency-security-and-dependabot", "parent_id": "section:developer-guide/security", "depth": 2, "kind": "page", "label": "dependency-security-and-dependabot", "title": "Dependency Security And Dependabot", "path": "developer-guide/security/dependency-security-and-dependabot", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "branched", "source_version": "0.7", "diff_added": 15, "diff_removed": 2}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "branched", "source_version": "0.9", "diff_added": 3, "diff_removed": 2}}, "content_versions": {"0.7": "+++\ntitle = \"Dependency Security and Dependabot\"\n+++\n\nSambee treats dependency intake and dependency vulnerability audits as separate workflows.\n\nDependabot helps bring reviewed update proposals into the repository.\n\nThe dependency audit workflow checks the current manifests and lockfiles for known published vulnerabilities.\n\nIn GitHub Actions, the repository-defined audit workflow appears as `Security: Dependency Audit`.\n\nDependabot activity still appears under GitHub-managed `Dependabot updates`, which is not renamed from this repository.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/dependabot.yml` | schedules and groups automated dependency update pull requests |\n| `.github/workflows/dependency-security.yml` | runs scheduled and manual dependency vulnerability audits |\n| local dev container setup | installs the same core audit tools used in CI for local verification |\n\n## Dependabot Setup\n\nDependabot is configured in `.github/dependabot.yml`.\n\nCurrent coverage includes:\n\n- GitHub Actions dependencies.\n- Backend Python dependencies under `backend/`.\n- Frontend npm dependencies under `frontend/`.\n- Companion npm dependencies under `companion/`.\n- Companion Rust dependencies under `companion/src-tauri/`.\n- Docker image dependencies from the repository root.\n\nThe configuration is intentionally grouped and filtered instead of allowing every update to arrive as an isolated pull request.\n\nExamples:\n\n- Backend Python updates split higher-risk areas such as `smbprotocol` and `pyvips` away from routine development-tool bumps.\n- Frontend major upgrades for React, MUI, Vite, TypeScript, routing, localization, and related runtime-critical packages stay manual.\n- Companion Tauri JavaScript and Rust updates are coordinated through a multi-ecosystem group.\n- Root Docker dependency updates are allowed, but Node and Python base-image version changes stay manual so they can be coordinated across Docker, CI, local development, and docs.\n\nThat split keeps routine maintenance moving while preserving deliberate review for dependency changes that can affect runtime compatibility, release behavior, or user workflows.\n\n## Dependency Vulnerability Audits\n\nThe dependency audit workflow lives in `.github/workflows/dependency-security.yml`.\n\nGitHub Actions displays that workflow as `Security: Dependency Audit`.\n\nIt runs weekly and on manual dispatch.\n\nCurrent checks are:\n\n- backend: `pip-audit -r backend/requirements-dev.lock.txt`\n- frontend: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion npm: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion Rust: `cargo audit`\n\nUse this workflow to catch known issues in the dependency manifests and lockfiles that the repository owns directly.\n\nInside the dev container, `pip-audit` and `cargo-audit` are installed during setup with the same pinned versions used in CI, so local verification can match the workflow behavior closely.\n\n## How This Fits with Release Work\n\nThese checks support release safety, but they are not the same as release publication controls.\n\nUse [Container Image Security and Artifact Integrity](../container-image-security-and-artifact-integrity/) for the Trivy image scans, `.trivyignore.yaml` policy, SBOM emission, provenance, and image signing workflow.\n\n", "0.8": "+++\ntitle = \"Dependency Security and Dependabot\"\n+++\n\nSambee treats dependency intake and dependency vulnerability audits as separate workflows.\n\nDependabot helps bring reviewed update proposals into the repository.\n\nThe dependency audit workflow checks the current manifests and lockfiles for known published vulnerabilities.\n\nIn GitHub Actions, the repository-defined audit workflow appears as `Security: Dependency Audit`.\n\nDependabot activity still appears under GitHub-managed `Dependabot updates`, which is not renamed from this repository.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/dependabot.yml` | schedules and groups automated dependency update pull requests |\n| `.github/workflows/dependency-security.yml` | runs scheduled and manual dependency vulnerability audits |\n| local dev container setup | installs the same core audit tools used in CI for local verification |\n\n## Dependabot Setup\n\nDependabot is configured in `.github/dependabot.yml`.\n\nCurrent coverage includes:\n\n- GitHub Actions dependencies.\n- Backend Python dependencies under `backend/`.\n- Frontend npm dependencies under `frontend/`.\n- Companion npm dependencies under `companion/`.\n- Companion Rust dependencies under `companion/src-tauri/`.\n- Docker image dependencies from the repository root.\n\nThe configuration is intentionally grouped and filtered instead of allowing every update to arrive as an isolated pull request.\n\nExamples:\n\n- Backend Python updates split higher-risk areas such as `smbprotocol` and `pyvips` away from routine development-tool bumps.\n- Frontend major upgrades for React, MUI, Vite, TypeScript, routing, localization, and related runtime-critical packages stay manual.\n- Companion Tauri JavaScript and Rust updates are coordinated through a multi-ecosystem group.\n- Root Docker dependency updates are allowed, but Node and Python base-image version changes stay manual so they can be coordinated across Docker, CI, local development, and docs.\n\nThat split keeps routine maintenance moving while preserving deliberate review for dependency changes that can affect runtime compatibility, release behavior, or user workflows.\n\n## Dependency Vulnerability Audits\n\nThe dependency audit workflow lives in `.github/workflows/dependency-security.yml`.\n\nGitHub Actions displays that workflow as `Security: Dependency Audit`.\n\nIt runs weekly and on manual dispatch.\n\nCurrent checks are:\n\n- backend: `pip-audit -r backend/requirements-dev.lock.txt`\n- frontend: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion npm: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion Rust: `cargo audit`\n\nUse this workflow to catch known issues in the dependency manifests and lockfiles that the repository owns directly.\n\nInside the dev container, `pip-audit` and `cargo-audit` are installed during setup with the same pinned versions used in CI, so local verification can match the workflow behavior closely.\n\n## How This Fits with Release Work\n\nThese checks support release safety, but they are not the same as release publication controls.\n\nUse [Container Image Security and Artifact Integrity](../container-image-security-and-artifact-integrity/) for the Trivy image scans, `.trivyignore.yaml` policy, SBOM emission, provenance, and image signing workflow.\n\n", "0.9": "+++\ntitle = \"Dependency Security and Dependabot\"\n+++\n\nSambee treats dependency intake and dependency vulnerability audits as separate workflows.\n\nDependabot helps bring reviewed update proposals into the repository.\n\nThe dependency audit workflow checks the current manifests and lockfiles for known published vulnerabilities.\n\nIn GitHub Actions, the repository-defined audit workflow appears as `Security: Dependency Audit`.\n\nDependabot activity still appears under GitHub-managed `Dependabot updates`, which is not renamed from this repository.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/dependabot.yml` | schedules and groups automated dependency update pull requests |\n| `.github/workflows/dependency-security.yml` | runs scheduled and manual dependency vulnerability audits |\n| local dev container setup | installs the same core audit tools used in CI for local verification |\n\n## Dependabot Setup\n\nDependabot is configured in `.github/dependabot.yml`.\n\nDependabot commit messages and ungrouped pull request titles use Conventional\nCommit-style prefixes. Ecosystem updates use `deps(npm)`, `deps(pip)`,\n`deps(cargo)`, or `deps(docker)`; GitHub Actions and CI-only tools use\n`deps(ci)`. Development dependencies use the matching `deps-dev(...)` prefix\nwhere Dependabot supports dependency groups.\n\nDependabot generates grouped pull request titles from the group identifier,\nwhich bypasses its configured prefix. The `Format Dependabot PR Title` workflow\nadds the matching prefix when Dependabot opens a grouped pull request. The\nmulti-ecosystem Companion group uses `deps(companion)` because it combines npm\nand Cargo updates.\n\nCurrent coverage includes:\n\n- GitHub Actions dependencies.\n- Backend Python dependencies under `backend/`.\n- Frontend npm dependencies under `frontend/`.\n- Companion npm dependencies under `companion/`.\n- Companion Rust dependencies under `companion/src-tauri/`.\n- Docker image dependencies from the repository root.\n\nThe configuration is intentionally grouped and filtered instead of allowing every update to arrive as an isolated pull request.\n\nExamples:\n\n- Backend Python updates split higher-risk areas such as `smbprotocol` and `pyvips` away from routine development-tool bumps.\n- Frontend major upgrades for React, MUI, Vite, TypeScript, routing, localization, and related runtime-critical packages stay manual.\n- Companion Tauri JavaScript and Rust updates are coordinated through a multi-ecosystem group.\n- Root Docker dependency updates include the shared Python runtime base. Dependabot proposes these updates, and Docker target validation reports the resolved Python and SQLite runtime versions before review.\n- Node base-image version changes stay manual because they affect both frontend and companion toolchains.\n\nThat split keeps routine maintenance moving while preserving deliberate review for dependency changes that can affect runtime compatibility, release behavior, or user workflows. Dependabot pull requests for the Python runtime must not be auto-merged: review the Docker validation, backend validation, image scan, and release-impacting changes before merging.\n\n## Dependency Vulnerability Audits\n\nThe dependency audit workflow lives in `.github/workflows/dependency-security.yml`.\n\nGitHub Actions displays that workflow as `Security: Dependency Audit`.\n\nIt runs weekly and on manual dispatch.\n\nCurrent checks are:\n\n- backend: `pip-audit -r backend/requirements-dev.lock.txt`\n- frontend: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion npm: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion Rust: `cargo audit`\n\nUse this workflow to catch known issues in the dependency manifests and lockfiles that the repository owns directly.\n\nInside the dev container, `pip-audit` and `cargo-audit` are installed during setup with the same pinned versions used in CI, so local verification can match the workflow behavior closely.\n\n## How This Fits with Release Work\n\nThese checks support release safety, but they are not the same as release publication controls.\n\nUse [Container Image Security and Artifact Integrity](../container-image-security-and-artifact-integrity/) for the Trivy image scans, `.trivyignore.yaml` policy, SBOM emission, provenance, and image signing workflow.\n\n", "1.0": "+++\ntitle = \"Dependency Security and Dependabot\"\n+++\n\nSambee treats dependency intake and dependency vulnerability audits as separate workflows.\n\nDependabot helps bring reviewed update proposals into the repository.\n\nThe dependency audit workflow checks the current manifests and lockfiles for known published vulnerabilities.\n\nIn GitHub Actions, the repository-defined audit workflow appears as `Security: Dependency Audit`.\n\nDependabot activity still appears under GitHub-managed `Dependabot updates`, which is not renamed from this repository.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/dependabot.yml` | schedules and groups automated dependency update pull requests |\n| `.github/workflows/dependency-security.yml` | runs scheduled and manual dependency vulnerability audits |\n| local dev container setup | installs the same core audit tools used in CI for local verification |\n\n## Dependabot Setup\n\nDependabot is configured in `.github/dependabot.yml`.\n\nDependabot commit messages and ungrouped pull request titles use Conventional\nCommit-style prefixes. Ecosystem updates use `deps(npm)`, `deps(pip)`,\n`deps(cargo)`, or `deps(docker)`; GitHub Actions and CI-only tools use\n`deps(ci)`. Development dependencies use the matching `deps-dev(...)` prefix\nwhere Dependabot supports dependency groups.\n\nDependabot generates grouped pull request titles from the group identifier,\nwhich bypasses its configured prefix. The `Format Dependabot PR Title` workflow\nadds the matching prefix when Dependabot opens a grouped pull request. The\nmulti-ecosystem Companion group uses `deps(companion)` because it combines npm\nand Cargo updates.\n\nCurrent coverage includes:\n\n- GitHub Actions dependencies.\n- Backend Python dependencies under `backend/`.\n- Frontend npm dependencies under `frontend/`.\n- Companion npm dependencies under `companion/`.\n- Companion Rust dependencies under `companion/src-tauri/`.\n- Docker image dependencies from the repository root.\n\nThe configuration is intentionally grouped and filtered instead of allowing every update to arrive as an isolated pull request.\n\nExamples:\n\n- Backend Python updates split higher-risk areas such as `smbprotocol` and `pyvips` away from routine development-tool bumps.\n- Frontend major upgrades for React, MUI, Vite, TypeScript, routing, localization, and related runtime-critical packages stay manual.\n- Companion Tauri JavaScript and Rust updates are coordinated through a multi-ecosystem group.\n- Root Docker dependency updates include the shared Python runtime base. Dependabot proposes these updates, and Docker target validation reports the resolved Python and SQLite runtime versions before review.\n- Node base-image version changes stay manual because they affect both frontend and companion toolchains.\n\nThat split keeps routine maintenance moving while preserving deliberate review for dependency changes that can affect runtime compatibility, release behavior, or user workflows. Dependabot pull requests for the Python runtime must not be auto-merged: review the Docker validation, backend validation, image scan, and release-impacting changes before merging.\n\n## Dependency Vulnerability Audits\n\nThe dependency audit workflow lives in `.github/workflows/dependency-security.yml`.\n\nGitHub Actions displays that workflow as `Security: Dependency Audit`.\n\nIt runs weekly and on manual dispatch.\n\nCurrent checks are:\n\n- backend: `pip-audit -r backend/requirements-dev.lock.txt`\n- frontend: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion npm: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion Rust: `cargo audit`\n\nUse this workflow to catch known issues in the dependency manifests and lockfiles that the repository owns directly.\n\nInside the dev container, `pip-audit` and `cargo-audit` are installed during setup with the same pinned versions used in CI, so local verification can match the workflow behavior closely.\n\n## How This Fits with Release Work\n\nThese checks support release safety, but they are not the same as release publication controls.\n\nUse [Container Image Security and Artifact Integrity](../container-image-security-and-artifact-integrity/) for the Trivy image scans, `.trivyignore.yaml` policy, SBOM emission, provenance, and image signing workflow.\n\n", "2.0": "+++\ntitle = \"Dependency Security and Dependabot\"\n+++\n\nSambee treats dependency intake and dependency vulnerability audits as separate workflows.\n\nDependabot helps bring reviewed update proposals into the repository.\n\nThe dependency audit workflow checks the current manifests and lockfiles for known published vulnerabilities.\n\nIn GitHub Actions, the repository-defined audit workflow appears as `Security: Dependency Audit`.\n\nDependabot activity still appears under GitHub-managed `Dependabot updates`, which is not renamed from this repository.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/dependabot.yml` | schedules and groups automated dependency update pull requests |\n| `.github/workflows/format-dependabot-pr-title.yml` | prefixes Dependabot pull request titles when configured group names omit them |\n| `.github/workflows/dependency-security.yml` | runs scheduled and manual dependency vulnerability audits |\n| local dev container setup | installs the same core audit tools used in CI for local verification |\n\n## Dependabot Setup\n\nDependabot is configured in `.github/dependabot.yml`.\n\nDependabot commit messages and ungrouped pull request titles use Conventional\nCommit-style prefixes. Ecosystem updates use `deps(npm)`, `deps(pip)`,\n`deps(cargo)`, or `deps(docker)`; GitHub Actions and CI-only tools use\n`deps(ci)`. Development dependencies use the matching `deps-dev(...)` prefix\nwhere Dependabot supports dependency groups.\n\nDependabot generates grouped pull request titles from the group identifier,\nwhich bypasses its configured prefix. The `Format Dependabot PR Title` workflow\nchecks open Dependabot pull requests when a `CI: Test` run triggered by\nDependabot starts and finishes, and adds the matching prefix where needed. It runs trusted workflow code with pull-request write access, without using `pull_request_target` or checking out pull-request code. Run it manually to retry title formatting if a CI run did not trigger it. The\nmulti-ecosystem Companion group uses `deps(companion)` because it combines npm\nand Cargo updates.\n\nCurrent coverage includes:\n\n- GitHub Actions dependencies.\n- Backend Python dependencies under `backend/`.\n- Frontend npm dependencies under `frontend/`.\n- Companion npm dependencies under `companion/`.\n- Companion Rust dependencies under `companion/src-tauri/`.\n- Docker image dependencies from the repository root.\n\nThe configuration is intentionally grouped and filtered instead of allowing every update to arrive as an isolated pull request.\n\nExamples:\n\n- Backend Python updates split higher-risk areas such as `smbprotocol` and `pyvips` away from routine development-tool bumps.\n- Frontend major upgrades for React, MUI, Vite, TypeScript, routing, localization, and related runtime-critical packages stay manual.\n- Companion Tauri JavaScript and Rust updates are coordinated through a multi-ecosystem group.\n- Root Docker dependency updates include the shared Python runtime base. Dependabot proposes these updates, and Docker target validation reports the resolved Python and SQLite runtime versions before review.\n- Node base-image version changes stay manual because they affect both frontend and companion toolchains.\n\nThat split keeps routine maintenance moving while preserving deliberate review for dependency changes that can affect runtime compatibility, release behavior, or user workflows. Dependabot pull requests for the Python runtime must not be auto-merged: review the Docker validation, backend validation, image scan, and release-impacting changes before merging.\n\n## Dependency Vulnerability Audits\n\nThe dependency audit workflow lives in `.github/workflows/dependency-security.yml`.\n\nGitHub Actions displays that workflow as `Security: Dependency Audit`.\n\nIt runs weekly and on manual dispatch.\n\nCurrent checks are:\n\n- backend: `pip-audit -r backend/requirements-dev.lock.txt`\n- frontend: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion npm: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion Rust: `cargo audit`\n\nUse this workflow to catch known issues in the dependency manifests and lockfiles that the repository owns directly.\n\nInside the dev container, `pip-audit` and `cargo-audit` are installed during setup with the same pinned versions used in CI, so local verification can match the workflow behavior closely.\n\n## How This Fits with Release Work\n\nThese checks support release safety, but they are not the same as release publication controls.\n\nUse [Container Image Security and Artifact Integrity](../container-image-security-and-artifact-integrity/) for the Trivy image scans, `.trivyignore.yaml` policy, SBOM emission, provenance, and image signing workflow.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Dependency Security and Dependabot\"\n+++\n\nSambee treats dependency intake and dependency vulnerability audits as separate workflows.\n\nDependabot helps bring reviewed update proposals into the repository.\n\nThe dependency audit workflow checks the current manifests and lockfiles for known published vulnerabilities.\n\nIn GitHub Actions, the repository-defined audit workflow appears as `Security: Dependency Audit`.\n\nDependabot activity still appears under GitHub-managed `Dependabot updates`, which is not renamed from this repository.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/dependabot.yml` | schedules and groups automated dependency update pull requests |\n| `.github/workflows/dependency-security.yml` | runs scheduled and manual dependency vulnerability audits |\n| local dev container setup | installs the same core audit tools used in CI for local verification |\n\n## Dependabot Setup\n\nDependabot is configured in `.github/dependabot.yml`.\n\nCurrent coverage includes:\n\n- GitHub Actions dependencies.\n- Backend Python dependencies under `backend/`.\n- Frontend npm dependencies under `frontend/`.\n- Companion npm dependencies under `companion/`.\n- Companion Rust dependencies under `companion/src-tauri/`.\n- Docker image dependencies from the repository root.\n\nThe configuration is intentionally grouped and filtered instead of allowing every update to arrive as an isolated pull request.\n\nExamples:\n\n- Backend Python updates split higher-risk areas such as `smbprotocol` and `pyvips` away from routine development-tool bumps.\n- Frontend major upgrades for React, MUI, Vite, TypeScript, routing, localization, and related runtime-critical packages stay manual.\n- Companion Tauri JavaScript and Rust updates are coordinated through a multi-ecosystem group.\n- Root Docker dependency updates are allowed, but Node and Python base-image version changes stay manual so they can be coordinated across Docker, CI, local development, and docs.\n\nThat split keeps routine maintenance moving while preserving deliberate review for dependency changes that can affect runtime compatibility, release behavior, or user workflows.\n\n## Dependency Vulnerability Audits\n\nThe dependency audit workflow lives in `.github/workflows/dependency-security.yml`.\n\nGitHub Actions displays that workflow as `Security: Dependency Audit`.\n\nIt runs weekly and on manual dispatch.\n\nCurrent checks are:\n\n- backend: `pip-audit -r backend/requirements-dev.lock.txt`\n- frontend: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion npm: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion Rust: `cargo audit`\n\nUse this workflow to catch known issues in the dependency manifests and lockfiles that the repository owns directly.\n\nInside the dev container, `pip-audit` and `cargo-audit` are installed during setup with the same pinned versions used in CI, so local verification can match the workflow behavior closely.\n\n## How This Fits with Release Work\n\nThese checks support release safety, but they are not the same as release publication controls.\n\nUse [Container Image Security and Artifact Integrity](../container-image-security-and-artifact-integrity/) for the Trivy image scans, `.trivyignore.yaml` policy, SBOM emission, provenance, and image signing workflow.\n\n", "0.8": "+++\ntitle = \"Dependency Security and Dependabot\"\n+++\n\nSambee treats dependency intake and dependency vulnerability audits as separate workflows.\n\nDependabot helps bring reviewed update proposals into the repository.\n\nThe dependency audit workflow checks the current manifests and lockfiles for known published vulnerabilities.\n\nIn GitHub Actions, the repository-defined audit workflow appears as `Security: Dependency Audit`.\n\nDependabot activity still appears under GitHub-managed `Dependabot updates`, which is not renamed from this repository.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/dependabot.yml` | schedules and groups automated dependency update pull requests |\n| `.github/workflows/dependency-security.yml` | runs scheduled and manual dependency vulnerability audits |\n| local dev container setup | installs the same core audit tools used in CI for local verification |\n\n## Dependabot Setup\n\nDependabot is configured in `.github/dependabot.yml`.\n\nCurrent coverage includes:\n\n- GitHub Actions dependencies.\n- Backend Python dependencies under `backend/`.\n- Frontend npm dependencies under `frontend/`.\n- Companion npm dependencies under `companion/`.\n- Companion Rust dependencies under `companion/src-tauri/`.\n- Docker image dependencies from the repository root.\n\nThe configuration is intentionally grouped and filtered instead of allowing every update to arrive as an isolated pull request.\n\nExamples:\n\n- Backend Python updates split higher-risk areas such as `smbprotocol` and `pyvips` away from routine development-tool bumps.\n- Frontend major upgrades for React, MUI, Vite, TypeScript, routing, localization, and related runtime-critical packages stay manual.\n- Companion Tauri JavaScript and Rust updates are coordinated through a multi-ecosystem group.\n- Root Docker dependency updates are allowed, but Node and Python base-image version changes stay manual so they can be coordinated across Docker, CI, local development, and docs.\n\nThat split keeps routine maintenance moving while preserving deliberate review for dependency changes that can affect runtime compatibility, release behavior, or user workflows.\n\n## Dependency Vulnerability Audits\n\nThe dependency audit workflow lives in `.github/workflows/dependency-security.yml`.\n\nGitHub Actions displays that workflow as `Security: Dependency Audit`.\n\nIt runs weekly and on manual dispatch.\n\nCurrent checks are:\n\n- backend: `pip-audit -r backend/requirements-dev.lock.txt`\n- frontend: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion npm: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion Rust: `cargo audit`\n\nUse this workflow to catch known issues in the dependency manifests and lockfiles that the repository owns directly.\n\nInside the dev container, `pip-audit` and `cargo-audit` are installed during setup with the same pinned versions used in CI, so local verification can match the workflow behavior closely.\n\n## How This Fits with Release Work\n\nThese checks support release safety, but they are not the same as release publication controls.\n\nUse [Container Image Security and Artifact Integrity](../container-image-security-and-artifact-integrity/) for the Trivy image scans, `.trivyignore.yaml` policy, SBOM emission, provenance, and image signing workflow.\n\n", "0.9": "+++\ntitle = \"Dependency Security and Dependabot\"\n+++\n\nSambee treats dependency intake and dependency vulnerability audits as separate workflows.\n\nDependabot helps bring reviewed update proposals into the repository.\n\nThe dependency audit workflow checks the current manifests and lockfiles for known published vulnerabilities.\n\nIn GitHub Actions, the repository-defined audit workflow appears as `Security: Dependency Audit`.\n\nDependabot activity still appears under GitHub-managed `Dependabot updates`, which is not renamed from this repository.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/dependabot.yml` | schedules and groups automated dependency update pull requests |\n| `.github/workflows/dependency-security.yml` | runs scheduled and manual dependency vulnerability audits |\n| local dev container setup | installs the same core audit tools used in CI for local verification |\n\n## Dependabot Setup\n\nDependabot is configured in `.github/dependabot.yml`.\n\nDependabot commit messages and ungrouped pull request titles use Conventional\nCommit-style prefixes. Ecosystem updates use `deps(npm)`, `deps(pip)`,\n`deps(cargo)`, or `deps(docker)`; GitHub Actions and CI-only tools use\n`deps(ci)`. Development dependencies use the matching `deps-dev(...)` prefix\nwhere Dependabot supports dependency groups.\n\nDependabot generates grouped pull request titles from the group identifier,\nwhich bypasses its configured prefix. The `Format Dependabot PR Title` workflow\nadds the matching prefix when Dependabot opens a grouped pull request. The\nmulti-ecosystem Companion group uses `deps(companion)` because it combines npm\nand Cargo updates.\n\nCurrent coverage includes:\n\n- GitHub Actions dependencies.\n- Backend Python dependencies under `backend/`.\n- Frontend npm dependencies under `frontend/`.\n- Companion npm dependencies under `companion/`.\n- Companion Rust dependencies under `companion/src-tauri/`.\n- Docker image dependencies from the repository root.\n\nThe configuration is intentionally grouped and filtered instead of allowing every update to arrive as an isolated pull request.\n\nExamples:\n\n- Backend Python updates split higher-risk areas such as `smbprotocol` and `pyvips` away from routine development-tool bumps.\n- Frontend major upgrades for React, MUI, Vite, TypeScript, routing, localization, and related runtime-critical packages stay manual.\n- Companion Tauri JavaScript and Rust updates are coordinated through a multi-ecosystem group.\n- Root Docker dependency updates include the shared Python runtime base. Dependabot proposes these updates, and Docker target validation reports the resolved Python and SQLite runtime versions before review.\n- Node base-image version changes stay manual because they affect both frontend and companion toolchains.\n\nThat split keeps routine maintenance moving while preserving deliberate review for dependency changes that can affect runtime compatibility, release behavior, or user workflows. Dependabot pull requests for the Python runtime must not be auto-merged: review the Docker validation, backend validation, image scan, and release-impacting changes before merging.\n\n## Dependency Vulnerability Audits\n\nThe dependency audit workflow lives in `.github/workflows/dependency-security.yml`.\n\nGitHub Actions displays that workflow as `Security: Dependency Audit`.\n\nIt runs weekly and on manual dispatch.\n\nCurrent checks are:\n\n- backend: `pip-audit -r backend/requirements-dev.lock.txt`\n- frontend: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion npm: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion Rust: `cargo audit`\n\nUse this workflow to catch known issues in the dependency manifests and lockfiles that the repository owns directly.\n\nInside the dev container, `pip-audit` and `cargo-audit` are installed during setup with the same pinned versions used in CI, so local verification can match the workflow behavior closely.\n\n## How This Fits with Release Work\n\nThese checks support release safety, but they are not the same as release publication controls.\n\nUse [Container Image Security and Artifact Integrity](../container-image-security-and-artifact-integrity/) for the Trivy image scans, `.trivyignore.yaml` policy, SBOM emission, provenance, and image signing workflow.\n\n", "1.0": "+++\ntitle = \"Dependency Security and Dependabot\"\n+++\n\nSambee treats dependency intake and dependency vulnerability audits as separate workflows.\n\nDependabot helps bring reviewed update proposals into the repository.\n\nThe dependency audit workflow checks the current manifests and lockfiles for known published vulnerabilities.\n\nIn GitHub Actions, the repository-defined audit workflow appears as `Security: Dependency Audit`.\n\nDependabot activity still appears under GitHub-managed `Dependabot updates`, which is not renamed from this repository.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/dependabot.yml` | schedules and groups automated dependency update pull requests |\n| `.github/workflows/dependency-security.yml` | runs scheduled and manual dependency vulnerability audits |\n| local dev container setup | installs the same core audit tools used in CI for local verification |\n\n## Dependabot Setup\n\nDependabot is configured in `.github/dependabot.yml`.\n\nDependabot commit messages and ungrouped pull request titles use Conventional\nCommit-style prefixes. Ecosystem updates use `deps(npm)`, `deps(pip)`,\n`deps(cargo)`, or `deps(docker)`; GitHub Actions and CI-only tools use\n`deps(ci)`. Development dependencies use the matching `deps-dev(...)` prefix\nwhere Dependabot supports dependency groups.\n\nDependabot generates grouped pull request titles from the group identifier,\nwhich bypasses its configured prefix. The `Format Dependabot PR Title` workflow\nadds the matching prefix when Dependabot opens a grouped pull request. The\nmulti-ecosystem Companion group uses `deps(companion)` because it combines npm\nand Cargo updates.\n\nCurrent coverage includes:\n\n- GitHub Actions dependencies.\n- Backend Python dependencies under `backend/`.\n- Frontend npm dependencies under `frontend/`.\n- Companion npm dependencies under `companion/`.\n- Companion Rust dependencies under `companion/src-tauri/`.\n- Docker image dependencies from the repository root.\n\nThe configuration is intentionally grouped and filtered instead of allowing every update to arrive as an isolated pull request.\n\nExamples:\n\n- Backend Python updates split higher-risk areas such as `smbprotocol` and `pyvips` away from routine development-tool bumps.\n- Frontend major upgrades for React, MUI, Vite, TypeScript, routing, localization, and related runtime-critical packages stay manual.\n- Companion Tauri JavaScript and Rust updates are coordinated through a multi-ecosystem group.\n- Root Docker dependency updates include the shared Python runtime base. Dependabot proposes these updates, and Docker target validation reports the resolved Python and SQLite runtime versions before review.\n- Node base-image version changes stay manual because they affect both frontend and companion toolchains.\n\nThat split keeps routine maintenance moving while preserving deliberate review for dependency changes that can affect runtime compatibility, release behavior, or user workflows. Dependabot pull requests for the Python runtime must not be auto-merged: review the Docker validation, backend validation, image scan, and release-impacting changes before merging.\n\n## Dependency Vulnerability Audits\n\nThe dependency audit workflow lives in `.github/workflows/dependency-security.yml`.\n\nGitHub Actions displays that workflow as `Security: Dependency Audit`.\n\nIt runs weekly and on manual dispatch.\n\nCurrent checks are:\n\n- backend: `pip-audit -r backend/requirements-dev.lock.txt`\n- frontend: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion npm: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion Rust: `cargo audit`\n\nUse this workflow to catch known issues in the dependency manifests and lockfiles that the repository owns directly.\n\nInside the dev container, `pip-audit` and `cargo-audit` are installed during setup with the same pinned versions used in CI, so local verification can match the workflow behavior closely.\n\n## How This Fits with Release Work\n\nThese checks support release safety, but they are not the same as release publication controls.\n\nUse [Container Image Security and Artifact Integrity](../container-image-security-and-artifact-integrity/) for the Trivy image scans, `.trivyignore.yaml` policy, SBOM emission, provenance, and image signing workflow.\n\n", "2.0": "+++\ntitle = \"Dependency Security and Dependabot\"\n+++\n\nSambee treats dependency intake and dependency vulnerability audits as separate workflows.\n\nDependabot helps bring reviewed update proposals into the repository.\n\nThe dependency audit workflow checks the current manifests and lockfiles for known published vulnerabilities.\n\nIn GitHub Actions, the repository-defined audit workflow appears as `Security: Dependency Audit`.\n\nDependabot activity still appears under GitHub-managed `Dependabot updates`, which is not renamed from this repository.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/dependabot.yml` | schedules and groups automated dependency update pull requests |\n| `.github/workflows/format-dependabot-pr-title.yml` | prefixes Dependabot pull request titles when configured group names omit them |\n| `.github/workflows/dependency-security.yml` | runs scheduled and manual dependency vulnerability audits |\n| local dev container setup | installs the same core audit tools used in CI for local verification |\n\n## Dependabot Setup\n\nDependabot is configured in `.github/dependabot.yml`.\n\nDependabot commit messages and ungrouped pull request titles use Conventional\nCommit-style prefixes. Ecosystem updates use `deps(npm)`, `deps(pip)`,\n`deps(cargo)`, or `deps(docker)`; GitHub Actions and CI-only tools use\n`deps(ci)`. Development dependencies use the matching `deps-dev(...)` prefix\nwhere Dependabot supports dependency groups.\n\nDependabot generates grouped pull request titles from the group identifier,\nwhich bypasses its configured prefix. The `Format Dependabot PR Title` workflow\nchecks open Dependabot pull requests when a `CI: Test` run triggered by\nDependabot starts and finishes, and adds the matching prefix where needed. It runs trusted workflow code with pull-request write access, without using `pull_request_target` or checking out pull-request code. Run it manually to retry title formatting if a CI run did not trigger it. The\nmulti-ecosystem Companion group uses `deps(companion)` because it combines npm\nand Cargo updates.\n\nCurrent coverage includes:\n\n- GitHub Actions dependencies.\n- Backend Python dependencies under `backend/`.\n- Frontend npm dependencies under `frontend/`.\n- Companion npm dependencies under `companion/`.\n- Companion Rust dependencies under `companion/src-tauri/`.\n- Docker image dependencies from the repository root.\n\nThe configuration is intentionally grouped and filtered instead of allowing every update to arrive as an isolated pull request.\n\nExamples:\n\n- Backend Python updates split higher-risk areas such as `smbprotocol` and `pyvips` away from routine development-tool bumps.\n- Frontend major upgrades for React, MUI, Vite, TypeScript, routing, localization, and related runtime-critical packages stay manual.\n- Companion Tauri JavaScript and Rust updates are coordinated through a multi-ecosystem group.\n- Root Docker dependency updates include the shared Python runtime base. Dependabot proposes these updates, and Docker target validation reports the resolved Python and SQLite runtime versions before review.\n- Node base-image version changes stay manual because they affect both frontend and companion toolchains.\n\nThat split keeps routine maintenance moving while preserving deliberate review for dependency changes that can affect runtime compatibility, release behavior, or user workflows. Dependabot pull requests for the Python runtime must not be auto-merged: review the Docker validation, backend validation, image scan, and release-impacting changes before merging.\n\n## Dependency Vulnerability Audits\n\nThe dependency audit workflow lives in `.github/workflows/dependency-security.yml`.\n\nGitHub Actions displays that workflow as `Security: Dependency Audit`.\n\nIt runs weekly and on manual dispatch.\n\nCurrent checks are:\n\n- backend: `pip-audit -r backend/requirements-dev.lock.txt`\n- frontend: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion npm: `npm audit --package-lock-only --omit=dev --audit-level=high`\n- companion Rust: `cargo audit`\n\nUse this workflow to catch known issues in the dependency manifests and lockfiles that the repository owns directly.\n\nInside the dev container, `pip-audit` and `cargo-audit` are installed during setup with the same pinned versions used in CI, so local verification can match the workflow behavior closely.\n\n## How This Fits with Release Work\n\nThese checks support release safety, but they are not the same as release publication controls.\n\nUse [Container Image Security and Artifact Integrity](../container-image-security-and-artifact-integrity/) for the Trivy image scans, `.trivyignore.yaml` policy, SBOM emission, provenance, and image signing workflow.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/security/container-image-security-and-artifact-integrity", "parent_id": "section:developer-guide/security", "depth": 2, "kind": "page", "label": "container-image-security-and-artifact-integrity", "title": "Container Image Security And Artifact Integrity", "path": "developer-guide/security/container-image-security-and-artifact-integrity", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Container Image Security and Artifact Integrity\"\n+++\n\nContainer-image security answers a different question than dependency-manifest auditing.\n\nSambee uses Trivy and release-artifact integrity controls to validate the final published container image, not just the repository dependency files.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/docker-image-security-scan.yml` | builds the current `main` image and runs the weekly Trivy scan |\n| `.github/workflows/docker-image-preview-publish.yml` | runs the preview-candidate Trivy scan before publishing to the `test` channel |\n| `.github/workflows/docker-image-publish.yml` | promotes a verified candidate digest onto release tags after checking image metadata and the published metadata bundle |\n| `.github/scripts/verify_candidate_metadata_bundle.sh` | verifies that the preview-built SBOM and provenance bundle exists under the expected digest-derived metadata tag |\n| `.github/tools/trivy/Dockerfile` | pins the Trivy container image version that both scan workflows use |\n| `.trivyignore.yaml` | holds reviewed Trivy suppressions for the image scans |\n| `Dockerfile` | defines the runtime artifact that is actually scanned and published |\n\n## Why Trivy Exists Alongside Dependency Audits\n\nDependency audits help with application dependency drift.\n\nTrivy adds coverage for the built runtime artifact itself, especially:\n\n- vulnerabilities inherited from the pinned base image\n- vulnerabilities in OS packages installed during the Docker build\n- the final package set that actually ships in the container\n\nThat matters for Sambee because the final image includes native tooling and runtime libraries that are outside the normal `pip`, `npm`, and `cargo` manifest audits.\n\n## Trivy Setup\n\nSambee currently uses Trivy in two places.\n\nBoth workflows resolve the Trivy runtime image from `.github/tools/trivy/Dockerfile`, so the pin is reviewed once and Dependabot can update it through the `docker` ecosystem.\n\nBoth workflows also force a fresh rebuild of the Dockerfile layer that installs Debian packages.\n\nThey do that with a workflow-provided refresh key passed into the image build, so `apt-get update`, `apt-get upgrade`, and package installation rerun against the latest repository state available at build time while the rest of the image can still benefit from BuildKit caching.\n\n### Weekly Image Scan on `main`\n\n`.github/workflows/docker-image-security-scan.yml` builds the current production image from `main` and scans it once per week.\n\nThe scan currently:\n\n- builds and scans the supported `linux/amd64` and `linux/arm64` image variants separately\n- forces a fresh rebuild of the Debian package-install layer for each workflow run\n- uses `.trivyignore.yaml` as the reviewed suppression file\n- shows suppressed findings in the output\n- checks OS packages and application libraries\n- considers only `HIGH` and `CRITICAL` vulnerabilities\n- ignores unfixed vulnerabilities\n- fails the workflow when matching fixed vulnerabilities remain after suppression\n\nThis is the workflow that tells you a shipped runtime stack has picked up a newly disclosed issue even when no new Sambee release is in progress.\n\n### Preview Publish Scan\n\n`.github/workflows/docker-image-preview-publish.yml` runs Trivy against each pushed preview platform image before those platform manifests are assembled into the preview candidate index.\n\nCurrent preview behavior is intentionally advisory:\n\n- the preview build forces a fresh rebuild of the Debian package-install layer before Trivy runs and before the candidate is published\n- Trivy scans the same pushed platform digests that are later assembled into the final preview candidate\n- preview publishes still show matching `HIGH` or `CRITICAL` findings\n- the findings do not block publication to the `test` channel\n\nThat keeps the newest preview candidate available for validation while still surfacing image risk clearly in CI.\n\n## Trivy Ignore Policy\n\nThe repository-root `.trivyignore.yaml` file is the shared suppression file for both Trivy workflows.\n\nKeep entries narrow and reviewable.\n\nEach suppression should include:\n\n- the finding ID\n- a short statement describing why the risk is accepted temporarily\n- an `expired_at` date so the exception must be revisited explicitly\n\nThat keeps long-lived silent exceptions from accumulating in the image-security workflows.\n\n## Artifact Integrity\n\nThe preview publish and release promotion workflows enable:\n\n- SBOM and provenance bundle publication in a dedicated metadata repository\n- Cosign signing of the pushed image digest through GitHub Actions OIDC\n\nRelease promotion also verifies that the preview-built metadata bundle matches the candidate digest before channel tags are moved.\n\nRelease and backfill workflows mirror the exact metadata bundle files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in GHCR remains the canonical store.\n\nCosign signatures are stored in a dedicated GHCR repository instead of the main image repository.\n\nCurrent split:\n\n- deployable images and multi-arch manifests stay under `ghcr.io/\u003cowner\u003e/sambee`\n- SBOM and provenance metadata bundles and Cosign signature artifacts are written under `ghcr.io/\u003cowner\u003e/sambee-signatures`\n\nFor Cosign-managed signatures, GHCR can display a digest-derived tagged signature artifact together with an untagged referenced bundle manifest for the same retained image digest.\n\nThat keeps the main package page focused on deployable image versions instead of showing non-runnable attestation content there.\n\nThose controls do not replace vulnerability scanning.\n\nThey answer a different question: whether a published artifact can be traced and verified after it is built.\n\n## Workflow Pinning Discipline\n\nSecurity-relevant GitHub Actions in this repository are pinned by commit SHA rather than floating major tags.\n\nThat reduces uncontrolled workflow drift in the automation layer itself.\n\nTreat action-version changes in these workflows as reviewed dependency changes, not as incidental cleanup.\n\n## How This Fits with Dependency Security\n\nUse [Dependency Security and Dependabot](../dependency-security-and-dependabot/) for the repository's dependency intake rules, Dependabot grouping, and scheduled dependency vulnerability audits.\n\n", "0.8": "+++\ntitle = \"Container Image Security and Artifact Integrity\"\n+++\n\nContainer-image security answers a different question than dependency-manifest auditing.\n\nSambee uses Trivy and release-artifact integrity controls to validate the final published container image, not just the repository dependency files.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/docker-image-security-scan.yml` | builds the current `main` image and runs the weekly Trivy scan |\n| `.github/workflows/docker-image-preview-publish.yml` | runs the preview-candidate Trivy scan before publishing to the `test` channel |\n| `.github/workflows/docker-image-publish.yml` | promotes a verified candidate digest onto release tags after checking image metadata and the published metadata bundle |\n| `.github/scripts/verify_candidate_metadata_bundle.sh` | verifies that the preview-built SBOM and provenance bundle exists under the expected digest-derived metadata tag |\n| `.github/tools/trivy/Dockerfile` | pins the Trivy container image version that both scan workflows use |\n| `.trivyignore.yaml` | holds reviewed Trivy suppressions for the image scans |\n| `Dockerfile` | defines the runtime artifact that is actually scanned and published |\n\n## Why Trivy Exists Alongside Dependency Audits\n\nDependency audits help with application dependency drift.\n\nTrivy adds coverage for the built runtime artifact itself, especially:\n\n- vulnerabilities inherited from the pinned base image\n- vulnerabilities in OS packages installed during the Docker build\n- the final package set that actually ships in the container\n\nThat matters for Sambee because the final image includes native tooling and runtime libraries that are outside the normal `pip`, `npm`, and `cargo` manifest audits.\n\n## Trivy Setup\n\nSambee currently uses Trivy in two places.\n\nBoth workflows resolve the Trivy runtime image from `.github/tools/trivy/Dockerfile`, so the pin is reviewed once and Dependabot can update it through the `docker` ecosystem.\n\nBoth workflows also force a fresh rebuild of the Dockerfile layer that installs Debian packages.\n\nThey do that with a workflow-provided refresh key passed into the image build, so `apt-get update`, `apt-get upgrade`, and package installation rerun against the latest repository state available at build time while the rest of the image can still benefit from BuildKit caching.\n\n### Weekly Image Scan on `main`\n\n`.github/workflows/docker-image-security-scan.yml` builds the current production image from `main` and scans it once per week.\n\nThe scan currently:\n\n- builds and scans the supported `linux/amd64` and `linux/arm64` image variants separately\n- forces a fresh rebuild of the Debian package-install layer for each workflow run\n- uses `.trivyignore.yaml` as the reviewed suppression file\n- shows suppressed findings in the output\n- checks OS packages and application libraries\n- considers only `HIGH` and `CRITICAL` vulnerabilities\n- ignores unfixed vulnerabilities\n- fails the workflow when matching fixed vulnerabilities remain after suppression\n\nThis is the workflow that tells you a shipped runtime stack has picked up a newly disclosed issue even when no new Sambee release is in progress.\n\n### Preview Publish Scan\n\n`.github/workflows/docker-image-preview-publish.yml` runs Trivy against each pushed preview platform image before those platform manifests are assembled into the preview candidate index.\n\nCurrent preview behavior is intentionally advisory:\n\n- the preview build forces a fresh rebuild of the Debian package-install layer before Trivy runs and before the candidate is published\n- Trivy scans the same pushed platform digests that are later assembled into the final preview candidate\n- preview publishes still show matching `HIGH` or `CRITICAL` findings\n- the findings do not block publication to the `test` channel\n\nThat keeps the newest preview candidate available for validation while still surfacing image risk clearly in CI.\n\n## Trivy Ignore Policy\n\nThe repository-root `.trivyignore.yaml` file is the shared suppression file for both Trivy workflows.\n\nKeep entries narrow and reviewable.\n\nEach suppression should include:\n\n- the finding ID\n- a short statement describing why the risk is accepted temporarily\n- an `expired_at` date so the exception must be revisited explicitly\n\nThat keeps long-lived silent exceptions from accumulating in the image-security workflows.\n\n## Artifact Integrity\n\nThe preview publish and release promotion workflows enable:\n\n- SBOM and provenance bundle publication in a dedicated metadata repository\n- Cosign signing of the pushed image digest through GitHub Actions OIDC\n\nRelease promotion also verifies that the preview-built metadata bundle matches the candidate digest before channel tags are moved.\n\nRelease and backfill workflows mirror the exact metadata bundle files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in GHCR remains the canonical store.\n\nCosign signatures are stored in a dedicated GHCR repository instead of the main image repository.\n\nCurrent split:\n\n- deployable images and multi-arch manifests stay under `ghcr.io/\u003cowner\u003e/sambee`\n- SBOM and provenance metadata bundles and Cosign signature artifacts are written under `ghcr.io/\u003cowner\u003e/sambee-signatures`\n\nFor Cosign-managed signatures, GHCR can display a digest-derived tagged signature artifact together with an untagged referenced bundle manifest for the same retained image digest.\n\nThat keeps the main package page focused on deployable image versions instead of showing non-runnable attestation content there.\n\nThose controls do not replace vulnerability scanning.\n\nThey answer a different question: whether a published artifact can be traced and verified after it is built.\n\n## Workflow Pinning Discipline\n\nSecurity-relevant GitHub Actions in this repository are pinned by commit SHA rather than floating major tags.\n\nThat reduces uncontrolled workflow drift in the automation layer itself.\n\nTreat action-version changes in these workflows as reviewed dependency changes, not as incidental cleanup.\n\n## How This Fits with Dependency Security\n\nUse [Dependency Security and Dependabot](../dependency-security-and-dependabot/) for the repository's dependency intake rules, Dependabot grouping, and scheduled dependency vulnerability audits.\n\n", "0.9": "+++\ntitle = \"Container Image Security and Artifact Integrity\"\n+++\n\nContainer-image security answers a different question than dependency-manifest auditing.\n\nSambee uses Trivy and release-artifact integrity controls to validate the final published container image, not just the repository dependency files.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/docker-image-security-scan.yml` | builds the current `main` image and runs the weekly Trivy scan |\n| `.github/workflows/docker-image-preview-publish.yml` | runs the preview-candidate Trivy scan before publishing to the `test` channel |\n| `.github/workflows/docker-image-publish.yml` | promotes a verified candidate digest onto release tags after checking image metadata and the published metadata bundle |\n| `.github/scripts/verify_candidate_metadata_bundle.sh` | verifies that the preview-built SBOM and provenance bundle exists under the expected digest-derived metadata tag |\n| `.github/tools/trivy/Dockerfile` | pins the Trivy container image version that both scan workflows use |\n| `.trivyignore.yaml` | holds reviewed Trivy suppressions for the image scans |\n| `Dockerfile` | defines the runtime artifact that is actually scanned and published |\n\n## Why Trivy Exists Alongside Dependency Audits\n\nDependency audits help with application dependency drift.\n\nTrivy adds coverage for the built runtime artifact itself, especially:\n\n- vulnerabilities inherited from the pinned base image\n- vulnerabilities in OS packages installed during the Docker build\n- the final package set that actually ships in the container\n\nThat matters for Sambee because the final image includes native tooling and runtime libraries that are outside the normal `pip`, `npm`, and `cargo` manifest audits.\n\n## Trivy Setup\n\nSambee currently uses Trivy in two places.\n\nBoth workflows resolve the Trivy runtime image from `.github/tools/trivy/Dockerfile`, so the pin is reviewed once and Dependabot can update it through the `docker` ecosystem.\n\nBoth workflows also force a fresh rebuild of the Dockerfile layer that installs Debian packages.\n\nThey do that with a workflow-provided refresh key passed into the image build, so `apt-get update`, `apt-get upgrade`, and package installation rerun against the latest repository state available at build time while the rest of the image can still benefit from BuildKit caching.\n\n### Weekly Image Scan on `main`\n\n`.github/workflows/docker-image-security-scan.yml` builds the current production image from `main` and scans it once per week.\n\nThe scan currently:\n\n- builds and scans the supported `linux/amd64` and `linux/arm64` image variants separately\n- forces a fresh rebuild of the Debian package-install layer for each workflow run\n- uses `.trivyignore.yaml` as the reviewed suppression file\n- shows suppressed findings in the output\n- checks OS packages and application libraries\n- considers only `HIGH` and `CRITICAL` vulnerabilities\n- ignores unfixed vulnerabilities\n- fails the workflow when matching fixed vulnerabilities remain after suppression\n\nThis is the workflow that tells you a shipped runtime stack has picked up a newly disclosed issue even when no new Sambee release is in progress.\n\n### Preview Publish Scan\n\n`.github/workflows/docker-image-preview-publish.yml` runs Trivy against each pushed preview platform image before those platform manifests are assembled into the preview candidate index.\n\nCurrent preview behavior is intentionally advisory:\n\n- the preview build forces a fresh rebuild of the Debian package-install layer before Trivy runs and before the candidate is published\n- Trivy scans the same pushed platform digests that are later assembled into the final preview candidate\n- preview publishes still show matching `HIGH` or `CRITICAL` findings\n- the findings do not block publication to the `test` channel\n\nThat keeps the newest preview candidate available for validation while still surfacing image risk clearly in CI.\n\n## Trivy Ignore Policy\n\nThe repository-root `.trivyignore.yaml` file is the shared suppression file for both Trivy workflows.\n\nKeep entries narrow and reviewable.\n\nEach suppression should include:\n\n- the finding ID\n- a short statement describing why the risk is accepted temporarily\n- an `expired_at` date so the exception must be revisited explicitly\n\nThat keeps long-lived silent exceptions from accumulating in the image-security workflows.\n\n## Artifact Integrity\n\nThe preview publish and release promotion workflows enable:\n\n- SBOM and provenance bundle publication in a dedicated metadata repository\n- Cosign signing of the pushed image digest through GitHub Actions OIDC\n\nRelease promotion also verifies that the preview-built metadata bundle matches the candidate digest before channel tags are moved.\n\nRelease and backfill workflows mirror the exact metadata bundle files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in GHCR remains the canonical store.\n\nCosign signatures are stored in a dedicated GHCR repository instead of the main image repository.\n\nCurrent split:\n\n- deployable images and multi-arch manifests stay under `ghcr.io/\u003cowner\u003e/sambee`\n- SBOM and provenance metadata bundles and Cosign signature artifacts are written under `ghcr.io/\u003cowner\u003e/sambee-signatures`\n\nFor Cosign-managed signatures, GHCR can display a digest-derived tagged signature artifact together with an untagged referenced bundle manifest for the same retained image digest.\n\nThat keeps the main package page focused on deployable image versions instead of showing non-runnable attestation content there.\n\nThose controls do not replace vulnerability scanning.\n\nThey answer a different question: whether a published artifact can be traced and verified after it is built.\n\n## Workflow Pinning Discipline\n\nSecurity-relevant GitHub Actions in this repository are pinned by commit SHA rather than floating major tags.\n\nThat reduces uncontrolled workflow drift in the automation layer itself.\n\nTreat action-version changes in these workflows as reviewed dependency changes, not as incidental cleanup.\n\n## How This Fits with Dependency Security\n\nUse [Dependency Security and Dependabot](../dependency-security-and-dependabot/) for the repository's dependency intake rules, Dependabot grouping, and scheduled dependency vulnerability audits.\n\n", "1.0": "+++\ntitle = \"Container Image Security and Artifact Integrity\"\n+++\n\nContainer-image security answers a different question than dependency-manifest auditing.\n\nSambee uses Trivy and release-artifact integrity controls to validate the final published container image, not just the repository dependency files.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/docker-image-security-scan.yml` | builds the current `main` image and runs the weekly Trivy scan |\n| `.github/workflows/docker-image-preview-publish.yml` | runs the preview-candidate Trivy scan before publishing to the `test` channel |\n| `.github/workflows/docker-image-publish.yml` | promotes a verified candidate digest onto release tags after checking image metadata and the published metadata bundle |\n| `.github/scripts/verify_candidate_metadata_bundle.sh` | verifies that the preview-built SBOM and provenance bundle exists under the expected digest-derived metadata tag |\n| `.github/tools/trivy/Dockerfile` | pins the Trivy container image version that both scan workflows use |\n| `.trivyignore.yaml` | holds reviewed Trivy suppressions for the image scans |\n| `Dockerfile` | defines the runtime artifact that is actually scanned and published |\n\n## Why Trivy Exists Alongside Dependency Audits\n\nDependency audits help with application dependency drift.\n\nTrivy adds coverage for the built runtime artifact itself, especially:\n\n- vulnerabilities inherited from the pinned base image\n- vulnerabilities in OS packages installed during the Docker build\n- the final package set that actually ships in the container\n\nThat matters for Sambee because the final image includes native tooling and runtime libraries that are outside the normal `pip`, `npm`, and `cargo` manifest audits.\n\n## Trivy Setup\n\nSambee currently uses Trivy in two places.\n\nBoth workflows resolve the Trivy runtime image from `.github/tools/trivy/Dockerfile`, so the pin is reviewed once and Dependabot can update it through the `docker` ecosystem.\n\nBoth workflows also force a fresh rebuild of the Dockerfile layer that installs Debian packages.\n\nThey do that with a workflow-provided refresh key passed into the image build, so `apt-get update`, `apt-get upgrade`, and package installation rerun against the latest repository state available at build time while the rest of the image can still benefit from BuildKit caching.\n\n### Weekly Image Scan on `main`\n\n`.github/workflows/docker-image-security-scan.yml` builds the current production image from `main` and scans it once per week.\n\nThe scan currently:\n\n- builds and scans the supported `linux/amd64` and `linux/arm64` image variants separately\n- forces a fresh rebuild of the Debian package-install layer for each workflow run\n- uses `.trivyignore.yaml` as the reviewed suppression file\n- shows suppressed findings in the output\n- checks OS packages and application libraries\n- considers only `HIGH` and `CRITICAL` vulnerabilities\n- ignores unfixed vulnerabilities\n- fails the workflow when matching fixed vulnerabilities remain after suppression\n\nThis is the workflow that tells you a shipped runtime stack has picked up a newly disclosed issue even when no new Sambee release is in progress.\n\n### Preview Publish Scan\n\n`.github/workflows/docker-image-preview-publish.yml` runs Trivy against each pushed preview platform image before those platform manifests are assembled into the preview candidate index.\n\nCurrent preview behavior is intentionally advisory:\n\n- the preview build forces a fresh rebuild of the Debian package-install layer before Trivy runs and before the candidate is published\n- Trivy scans the same pushed platform digests that are later assembled into the final preview candidate\n- preview publishes still show matching `HIGH` or `CRITICAL` findings\n- the findings do not block publication to the `test` channel\n\nThat keeps the newest preview candidate available for validation while still surfacing image risk clearly in CI.\n\n## Trivy Ignore Policy\n\nThe repository-root `.trivyignore.yaml` file is the shared suppression file for both Trivy workflows.\n\nKeep entries narrow and reviewable.\n\nEach suppression should include:\n\n- the finding ID\n- a short statement describing why the risk is accepted temporarily\n- an `expired_at` date so the exception must be revisited explicitly\n\nThat keeps long-lived silent exceptions from accumulating in the image-security workflows.\n\n## Artifact Integrity\n\nThe preview publish and release promotion workflows enable:\n\n- SBOM and provenance bundle publication in a dedicated metadata repository\n- Cosign signing of the pushed image digest through GitHub Actions OIDC\n\nRelease promotion also verifies that the preview-built metadata bundle matches the candidate digest before channel tags are moved.\n\nRelease and backfill workflows mirror the exact metadata bundle files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in GHCR remains the canonical store.\n\nCosign signatures are stored in a dedicated GHCR repository instead of the main image repository.\n\nCurrent split:\n\n- deployable images and multi-arch manifests stay under `ghcr.io/\u003cowner\u003e/sambee`\n- SBOM and provenance metadata bundles and Cosign signature artifacts are written under `ghcr.io/\u003cowner\u003e/sambee-signatures`\n\nFor Cosign-managed signatures, GHCR can display a digest-derived tagged signature artifact together with an untagged referenced bundle manifest for the same retained image digest.\n\nThat keeps the main package page focused on deployable image versions instead of showing non-runnable attestation content there.\n\nThose controls do not replace vulnerability scanning.\n\nThey answer a different question: whether a published artifact can be traced and verified after it is built.\n\n## Workflow Pinning Discipline\n\nSecurity-relevant GitHub Actions in this repository are pinned by commit SHA rather than floating major tags.\n\nThat reduces uncontrolled workflow drift in the automation layer itself.\n\nTreat action-version changes in these workflows as reviewed dependency changes, not as incidental cleanup.\n\n## How This Fits with Dependency Security\n\nUse [Dependency Security and Dependabot](../dependency-security-and-dependabot/) for the repository's dependency intake rules, Dependabot grouping, and scheduled dependency vulnerability audits.\n\n", "2.0": "+++\ntitle = \"Container Image Security and Artifact Integrity\"\n+++\n\nContainer-image security answers a different question than dependency-manifest auditing.\n\nSambee uses Trivy and release-artifact integrity controls to validate the final published container image, not just the repository dependency files.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/docker-image-security-scan.yml` | builds the current `main` image and runs the weekly Trivy scan |\n| `.github/workflows/docker-image-preview-publish.yml` | runs the preview-candidate Trivy scan before publishing to the `test` channel |\n| `.github/workflows/docker-image-publish.yml` | promotes a verified candidate digest onto release tags after checking image metadata and the published metadata bundle |\n| `.github/scripts/verify_candidate_metadata_bundle.sh` | verifies that the preview-built SBOM and provenance bundle exists under the expected digest-derived metadata tag |\n| `.github/tools/trivy/Dockerfile` | pins the Trivy container image version that both scan workflows use |\n| `.trivyignore.yaml` | holds reviewed Trivy suppressions for the image scans |\n| `Dockerfile` | defines the runtime artifact that is actually scanned and published |\n\n## Why Trivy Exists Alongside Dependency Audits\n\nDependency audits help with application dependency drift.\n\nTrivy adds coverage for the built runtime artifact itself, especially:\n\n- vulnerabilities inherited from the pinned base image\n- vulnerabilities in OS packages installed during the Docker build\n- the final package set that actually ships in the container\n\nThat matters for Sambee because the final image includes native tooling and runtime libraries that are outside the normal `pip`, `npm`, and `cargo` manifest audits.\n\n## Trivy Setup\n\nSambee currently uses Trivy in two places.\n\nBoth workflows resolve the Trivy runtime image from `.github/tools/trivy/Dockerfile`, so the pin is reviewed once and Dependabot can update it through the `docker` ecosystem.\n\nBoth workflows also force a fresh rebuild of the Dockerfile layer that installs Debian packages.\n\nThey do that with a workflow-provided refresh key passed into the image build, so `apt-get update`, `apt-get upgrade`, and package installation rerun against the latest repository state available at build time while the rest of the image can still benefit from BuildKit caching.\n\n### Weekly Image Scan on `main`\n\n`.github/workflows/docker-image-security-scan.yml` builds the current production image from `main` and scans it once per week.\n\nThe scan currently:\n\n- builds and scans the supported `linux/amd64` and `linux/arm64` image variants separately\n- forces a fresh rebuild of the Debian package-install layer for each workflow run\n- uses `.trivyignore.yaml` as the reviewed suppression file\n- shows suppressed findings in the output\n- checks OS packages and application libraries\n- considers only `HIGH` and `CRITICAL` vulnerabilities\n- ignores unfixed vulnerabilities\n- fails the workflow when matching fixed vulnerabilities remain after suppression\n\nThis is the workflow that tells you a shipped runtime stack has picked up a newly disclosed issue even when no new Sambee release is in progress.\n\n### Preview Publish Scan\n\n`.github/workflows/docker-image-preview-publish.yml` runs Trivy against each pushed preview platform image before those platform manifests are assembled into the preview candidate index.\n\nCurrent preview behavior is intentionally advisory:\n\n- the preview build forces a fresh rebuild of the Debian package-install layer before Trivy runs and before the candidate is published\n- Trivy scans the same pushed platform digests that are later assembled into the final preview candidate\n- preview publishes still show matching `HIGH` or `CRITICAL` findings\n- the findings do not block publication to the `test` channel\n\nThat keeps the newest preview candidate available for validation while still surfacing image risk clearly in CI.\n\n## Trivy Ignore Policy\n\nThe repository-root `.trivyignore.yaml` file is the shared suppression file for both Trivy workflows.\n\nKeep entries narrow and reviewable.\n\nEach suppression should include:\n\n- the finding ID\n- a short statement describing why the risk is accepted temporarily\n- an `expired_at` date so the exception must be revisited explicitly\n\nThat keeps long-lived silent exceptions from accumulating in the image-security workflows.\n\n## Artifact Integrity\n\nThe preview publish and release promotion workflows enable:\n\n- SBOM and provenance bundle publication in a dedicated metadata repository\n- Cosign signing of the pushed image digest through GitHub Actions OIDC\n\nRelease promotion also verifies that the preview-built metadata bundle matches the candidate digest before channel tags are moved.\n\nRelease and backfill workflows mirror the exact metadata bundle files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in GHCR remains the canonical store.\n\nCosign signatures are stored in a dedicated GHCR repository instead of the main image repository.\n\nCurrent split:\n\n- deployable images and multi-arch manifests stay under `ghcr.io/\u003cowner\u003e/sambee`\n- SBOM and provenance metadata bundles and Cosign signature artifacts are written under `ghcr.io/\u003cowner\u003e/sambee-signatures`\n\nFor Cosign-managed signatures, GHCR can display a digest-derived tagged signature artifact together with an untagged referenced bundle manifest for the same retained image digest.\n\nThat keeps the main package page focused on deployable image versions instead of showing non-runnable attestation content there.\n\nThose controls do not replace vulnerability scanning.\n\nThey answer a different question: whether a published artifact can be traced and verified after it is built.\n\n## Workflow Pinning Discipline\n\nSecurity-relevant GitHub Actions in this repository are pinned by commit SHA rather than floating major tags.\n\nThat reduces uncontrolled workflow drift in the automation layer itself.\n\nTreat action-version changes in these workflows as reviewed dependency changes, not as incidental cleanup.\n\n## How This Fits with Dependency Security\n\nUse [Dependency Security and Dependabot](../dependency-security-and-dependabot/) for the repository's dependency intake rules, Dependabot grouping, and scheduled dependency vulnerability audits.\n\n"}, "page_contents": {"0.7": "+++\ntitle = \"Container Image Security and Artifact Integrity\"\n+++\n\nContainer-image security answers a different question than dependency-manifest auditing.\n\nSambee uses Trivy and release-artifact integrity controls to validate the final published container image, not just the repository dependency files.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/docker-image-security-scan.yml` | builds the current `main` image and runs the weekly Trivy scan |\n| `.github/workflows/docker-image-preview-publish.yml` | runs the preview-candidate Trivy scan before publishing to the `test` channel |\n| `.github/workflows/docker-image-publish.yml` | promotes a verified candidate digest onto release tags after checking image metadata and the published metadata bundle |\n| `.github/scripts/verify_candidate_metadata_bundle.sh` | verifies that the preview-built SBOM and provenance bundle exists under the expected digest-derived metadata tag |\n| `.github/tools/trivy/Dockerfile` | pins the Trivy container image version that both scan workflows use |\n| `.trivyignore.yaml` | holds reviewed Trivy suppressions for the image scans |\n| `Dockerfile` | defines the runtime artifact that is actually scanned and published |\n\n## Why Trivy Exists Alongside Dependency Audits\n\nDependency audits help with application dependency drift.\n\nTrivy adds coverage for the built runtime artifact itself, especially:\n\n- vulnerabilities inherited from the pinned base image\n- vulnerabilities in OS packages installed during the Docker build\n- the final package set that actually ships in the container\n\nThat matters for Sambee because the final image includes native tooling and runtime libraries that are outside the normal `pip`, `npm`, and `cargo` manifest audits.\n\n## Trivy Setup\n\nSambee currently uses Trivy in two places.\n\nBoth workflows resolve the Trivy runtime image from `.github/tools/trivy/Dockerfile`, so the pin is reviewed once and Dependabot can update it through the `docker` ecosystem.\n\nBoth workflows also force a fresh rebuild of the Dockerfile layer that installs Debian packages.\n\nThey do that with a workflow-provided refresh key passed into the image build, so `apt-get update`, `apt-get upgrade`, and package installation rerun against the latest repository state available at build time while the rest of the image can still benefit from BuildKit caching.\n\n### Weekly Image Scan on `main`\n\n`.github/workflows/docker-image-security-scan.yml` builds the current production image from `main` and scans it once per week.\n\nThe scan currently:\n\n- builds and scans the supported `linux/amd64` and `linux/arm64` image variants separately\n- forces a fresh rebuild of the Debian package-install layer for each workflow run\n- uses `.trivyignore.yaml` as the reviewed suppression file\n- shows suppressed findings in the output\n- checks OS packages and application libraries\n- considers only `HIGH` and `CRITICAL` vulnerabilities\n- ignores unfixed vulnerabilities\n- fails the workflow when matching fixed vulnerabilities remain after suppression\n\nThis is the workflow that tells you a shipped runtime stack has picked up a newly disclosed issue even when no new Sambee release is in progress.\n\n### Preview Publish Scan\n\n`.github/workflows/docker-image-preview-publish.yml` runs Trivy against each pushed preview platform image before those platform manifests are assembled into the preview candidate index.\n\nCurrent preview behavior is intentionally advisory:\n\n- the preview build forces a fresh rebuild of the Debian package-install layer before Trivy runs and before the candidate is published\n- Trivy scans the same pushed platform digests that are later assembled into the final preview candidate\n- preview publishes still show matching `HIGH` or `CRITICAL` findings\n- the findings do not block publication to the `test` channel\n\nThat keeps the newest preview candidate available for validation while still surfacing image risk clearly in CI.\n\n## Trivy Ignore Policy\n\nThe repository-root `.trivyignore.yaml` file is the shared suppression file for both Trivy workflows.\n\nKeep entries narrow and reviewable.\n\nEach suppression should include:\n\n- the finding ID\n- a short statement describing why the risk is accepted temporarily\n- an `expired_at` date so the exception must be revisited explicitly\n\nThat keeps long-lived silent exceptions from accumulating in the image-security workflows.\n\n## Artifact Integrity\n\nThe preview publish and release promotion workflows enable:\n\n- SBOM and provenance bundle publication in a dedicated metadata repository\n- Cosign signing of the pushed image digest through GitHub Actions OIDC\n\nRelease promotion also verifies that the preview-built metadata bundle matches the candidate digest before channel tags are moved.\n\nRelease and backfill workflows mirror the exact metadata bundle files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in GHCR remains the canonical store.\n\nCosign signatures are stored in a dedicated GHCR repository instead of the main image repository.\n\nCurrent split:\n\n- deployable images and multi-arch manifests stay under `ghcr.io/\u003cowner\u003e/sambee`\n- SBOM and provenance metadata bundles and Cosign signature artifacts are written under `ghcr.io/\u003cowner\u003e/sambee-signatures`\n\nFor Cosign-managed signatures, GHCR can display a digest-derived tagged signature artifact together with an untagged referenced bundle manifest for the same retained image digest.\n\nThat keeps the main package page focused on deployable image versions instead of showing non-runnable attestation content there.\n\nThose controls do not replace vulnerability scanning.\n\nThey answer a different question: whether a published artifact can be traced and verified after it is built.\n\n## Workflow Pinning Discipline\n\nSecurity-relevant GitHub Actions in this repository are pinned by commit SHA rather than floating major tags.\n\nThat reduces uncontrolled workflow drift in the automation layer itself.\n\nTreat action-version changes in these workflows as reviewed dependency changes, not as incidental cleanup.\n\n## How This Fits with Dependency Security\n\nUse [Dependency Security and Dependabot](../dependency-security-and-dependabot/) for the repository's dependency intake rules, Dependabot grouping, and scheduled dependency vulnerability audits.\n\n", "0.8": "+++\ntitle = \"Container Image Security and Artifact Integrity\"\n+++\n\nContainer-image security answers a different question than dependency-manifest auditing.\n\nSambee uses Trivy and release-artifact integrity controls to validate the final published container image, not just the repository dependency files.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/docker-image-security-scan.yml` | builds the current `main` image and runs the weekly Trivy scan |\n| `.github/workflows/docker-image-preview-publish.yml` | runs the preview-candidate Trivy scan before publishing to the `test` channel |\n| `.github/workflows/docker-image-publish.yml` | promotes a verified candidate digest onto release tags after checking image metadata and the published metadata bundle |\n| `.github/scripts/verify_candidate_metadata_bundle.sh` | verifies that the preview-built SBOM and provenance bundle exists under the expected digest-derived metadata tag |\n| `.github/tools/trivy/Dockerfile` | pins the Trivy container image version that both scan workflows use |\n| `.trivyignore.yaml` | holds reviewed Trivy suppressions for the image scans |\n| `Dockerfile` | defines the runtime artifact that is actually scanned and published |\n\n## Why Trivy Exists Alongside Dependency Audits\n\nDependency audits help with application dependency drift.\n\nTrivy adds coverage for the built runtime artifact itself, especially:\n\n- vulnerabilities inherited from the pinned base image\n- vulnerabilities in OS packages installed during the Docker build\n- the final package set that actually ships in the container\n\nThat matters for Sambee because the final image includes native tooling and runtime libraries that are outside the normal `pip`, `npm`, and `cargo` manifest audits.\n\n## Trivy Setup\n\nSambee currently uses Trivy in two places.\n\nBoth workflows resolve the Trivy runtime image from `.github/tools/trivy/Dockerfile`, so the pin is reviewed once and Dependabot can update it through the `docker` ecosystem.\n\nBoth workflows also force a fresh rebuild of the Dockerfile layer that installs Debian packages.\n\nThey do that with a workflow-provided refresh key passed into the image build, so `apt-get update`, `apt-get upgrade`, and package installation rerun against the latest repository state available at build time while the rest of the image can still benefit from BuildKit caching.\n\n### Weekly Image Scan on `main`\n\n`.github/workflows/docker-image-security-scan.yml` builds the current production image from `main` and scans it once per week.\n\nThe scan currently:\n\n- builds and scans the supported `linux/amd64` and `linux/arm64` image variants separately\n- forces a fresh rebuild of the Debian package-install layer for each workflow run\n- uses `.trivyignore.yaml` as the reviewed suppression file\n- shows suppressed findings in the output\n- checks OS packages and application libraries\n- considers only `HIGH` and `CRITICAL` vulnerabilities\n- ignores unfixed vulnerabilities\n- fails the workflow when matching fixed vulnerabilities remain after suppression\n\nThis is the workflow that tells you a shipped runtime stack has picked up a newly disclosed issue even when no new Sambee release is in progress.\n\n### Preview Publish Scan\n\n`.github/workflows/docker-image-preview-publish.yml` runs Trivy against each pushed preview platform image before those platform manifests are assembled into the preview candidate index.\n\nCurrent preview behavior is intentionally advisory:\n\n- the preview build forces a fresh rebuild of the Debian package-install layer before Trivy runs and before the candidate is published\n- Trivy scans the same pushed platform digests that are later assembled into the final preview candidate\n- preview publishes still show matching `HIGH` or `CRITICAL` findings\n- the findings do not block publication to the `test` channel\n\nThat keeps the newest preview candidate available for validation while still surfacing image risk clearly in CI.\n\n## Trivy Ignore Policy\n\nThe repository-root `.trivyignore.yaml` file is the shared suppression file for both Trivy workflows.\n\nKeep entries narrow and reviewable.\n\nEach suppression should include:\n\n- the finding ID\n- a short statement describing why the risk is accepted temporarily\n- an `expired_at` date so the exception must be revisited explicitly\n\nThat keeps long-lived silent exceptions from accumulating in the image-security workflows.\n\n## Artifact Integrity\n\nThe preview publish and release promotion workflows enable:\n\n- SBOM and provenance bundle publication in a dedicated metadata repository\n- Cosign signing of the pushed image digest through GitHub Actions OIDC\n\nRelease promotion also verifies that the preview-built metadata bundle matches the candidate digest before channel tags are moved.\n\nRelease and backfill workflows mirror the exact metadata bundle files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in GHCR remains the canonical store.\n\nCosign signatures are stored in a dedicated GHCR repository instead of the main image repository.\n\nCurrent split:\n\n- deployable images and multi-arch manifests stay under `ghcr.io/\u003cowner\u003e/sambee`\n- SBOM and provenance metadata bundles and Cosign signature artifacts are written under `ghcr.io/\u003cowner\u003e/sambee-signatures`\n\nFor Cosign-managed signatures, GHCR can display a digest-derived tagged signature artifact together with an untagged referenced bundle manifest for the same retained image digest.\n\nThat keeps the main package page focused on deployable image versions instead of showing non-runnable attestation content there.\n\nThose controls do not replace vulnerability scanning.\n\nThey answer a different question: whether a published artifact can be traced and verified after it is built.\n\n## Workflow Pinning Discipline\n\nSecurity-relevant GitHub Actions in this repository are pinned by commit SHA rather than floating major tags.\n\nThat reduces uncontrolled workflow drift in the automation layer itself.\n\nTreat action-version changes in these workflows as reviewed dependency changes, not as incidental cleanup.\n\n## How This Fits with Dependency Security\n\nUse [Dependency Security and Dependabot](../dependency-security-and-dependabot/) for the repository's dependency intake rules, Dependabot grouping, and scheduled dependency vulnerability audits.\n\n", "0.9": "+++\ntitle = \"Container Image Security and Artifact Integrity\"\n+++\n\nContainer-image security answers a different question than dependency-manifest auditing.\n\nSambee uses Trivy and release-artifact integrity controls to validate the final published container image, not just the repository dependency files.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/docker-image-security-scan.yml` | builds the current `main` image and runs the weekly Trivy scan |\n| `.github/workflows/docker-image-preview-publish.yml` | runs the preview-candidate Trivy scan before publishing to the `test` channel |\n| `.github/workflows/docker-image-publish.yml` | promotes a verified candidate digest onto release tags after checking image metadata and the published metadata bundle |\n| `.github/scripts/verify_candidate_metadata_bundle.sh` | verifies that the preview-built SBOM and provenance bundle exists under the expected digest-derived metadata tag |\n| `.github/tools/trivy/Dockerfile` | pins the Trivy container image version that both scan workflows use |\n| `.trivyignore.yaml` | holds reviewed Trivy suppressions for the image scans |\n| `Dockerfile` | defines the runtime artifact that is actually scanned and published |\n\n## Why Trivy Exists Alongside Dependency Audits\n\nDependency audits help with application dependency drift.\n\nTrivy adds coverage for the built runtime artifact itself, especially:\n\n- vulnerabilities inherited from the pinned base image\n- vulnerabilities in OS packages installed during the Docker build\n- the final package set that actually ships in the container\n\nThat matters for Sambee because the final image includes native tooling and runtime libraries that are outside the normal `pip`, `npm`, and `cargo` manifest audits.\n\n## Trivy Setup\n\nSambee currently uses Trivy in two places.\n\nBoth workflows resolve the Trivy runtime image from `.github/tools/trivy/Dockerfile`, so the pin is reviewed once and Dependabot can update it through the `docker` ecosystem.\n\nBoth workflows also force a fresh rebuild of the Dockerfile layer that installs Debian packages.\n\nThey do that with a workflow-provided refresh key passed into the image build, so `apt-get update`, `apt-get upgrade`, and package installation rerun against the latest repository state available at build time while the rest of the image can still benefit from BuildKit caching.\n\n### Weekly Image Scan on `main`\n\n`.github/workflows/docker-image-security-scan.yml` builds the current production image from `main` and scans it once per week.\n\nThe scan currently:\n\n- builds and scans the supported `linux/amd64` and `linux/arm64` image variants separately\n- forces a fresh rebuild of the Debian package-install layer for each workflow run\n- uses `.trivyignore.yaml` as the reviewed suppression file\n- shows suppressed findings in the output\n- checks OS packages and application libraries\n- considers only `HIGH` and `CRITICAL` vulnerabilities\n- ignores unfixed vulnerabilities\n- fails the workflow when matching fixed vulnerabilities remain after suppression\n\nThis is the workflow that tells you a shipped runtime stack has picked up a newly disclosed issue even when no new Sambee release is in progress.\n\n### Preview Publish Scan\n\n`.github/workflows/docker-image-preview-publish.yml` runs Trivy against each pushed preview platform image before those platform manifests are assembled into the preview candidate index.\n\nCurrent preview behavior is intentionally advisory:\n\n- the preview build forces a fresh rebuild of the Debian package-install layer before Trivy runs and before the candidate is published\n- Trivy scans the same pushed platform digests that are later assembled into the final preview candidate\n- preview publishes still show matching `HIGH` or `CRITICAL` findings\n- the findings do not block publication to the `test` channel\n\nThat keeps the newest preview candidate available for validation while still surfacing image risk clearly in CI.\n\n## Trivy Ignore Policy\n\nThe repository-root `.trivyignore.yaml` file is the shared suppression file for both Trivy workflows.\n\nKeep entries narrow and reviewable.\n\nEach suppression should include:\n\n- the finding ID\n- a short statement describing why the risk is accepted temporarily\n- an `expired_at` date so the exception must be revisited explicitly\n\nThat keeps long-lived silent exceptions from accumulating in the image-security workflows.\n\n## Artifact Integrity\n\nThe preview publish and release promotion workflows enable:\n\n- SBOM and provenance bundle publication in a dedicated metadata repository\n- Cosign signing of the pushed image digest through GitHub Actions OIDC\n\nRelease promotion also verifies that the preview-built metadata bundle matches the candidate digest before channel tags are moved.\n\nRelease and backfill workflows mirror the exact metadata bundle files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in GHCR remains the canonical store.\n\nCosign signatures are stored in a dedicated GHCR repository instead of the main image repository.\n\nCurrent split:\n\n- deployable images and multi-arch manifests stay under `ghcr.io/\u003cowner\u003e/sambee`\n- SBOM and provenance metadata bundles and Cosign signature artifacts are written under `ghcr.io/\u003cowner\u003e/sambee-signatures`\n\nFor Cosign-managed signatures, GHCR can display a digest-derived tagged signature artifact together with an untagged referenced bundle manifest for the same retained image digest.\n\nThat keeps the main package page focused on deployable image versions instead of showing non-runnable attestation content there.\n\nThose controls do not replace vulnerability scanning.\n\nThey answer a different question: whether a published artifact can be traced and verified after it is built.\n\n## Workflow Pinning Discipline\n\nSecurity-relevant GitHub Actions in this repository are pinned by commit SHA rather than floating major tags.\n\nThat reduces uncontrolled workflow drift in the automation layer itself.\n\nTreat action-version changes in these workflows as reviewed dependency changes, not as incidental cleanup.\n\n## How This Fits with Dependency Security\n\nUse [Dependency Security and Dependabot](../dependency-security-and-dependabot/) for the repository's dependency intake rules, Dependabot grouping, and scheduled dependency vulnerability audits.\n\n", "1.0": "+++\ntitle = \"Container Image Security and Artifact Integrity\"\n+++\n\nContainer-image security answers a different question than dependency-manifest auditing.\n\nSambee uses Trivy and release-artifact integrity controls to validate the final published container image, not just the repository dependency files.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/docker-image-security-scan.yml` | builds the current `main` image and runs the weekly Trivy scan |\n| `.github/workflows/docker-image-preview-publish.yml` | runs the preview-candidate Trivy scan before publishing to the `test` channel |\n| `.github/workflows/docker-image-publish.yml` | promotes a verified candidate digest onto release tags after checking image metadata and the published metadata bundle |\n| `.github/scripts/verify_candidate_metadata_bundle.sh` | verifies that the preview-built SBOM and provenance bundle exists under the expected digest-derived metadata tag |\n| `.github/tools/trivy/Dockerfile` | pins the Trivy container image version that both scan workflows use |\n| `.trivyignore.yaml` | holds reviewed Trivy suppressions for the image scans |\n| `Dockerfile` | defines the runtime artifact that is actually scanned and published |\n\n## Why Trivy Exists Alongside Dependency Audits\n\nDependency audits help with application dependency drift.\n\nTrivy adds coverage for the built runtime artifact itself, especially:\n\n- vulnerabilities inherited from the pinned base image\n- vulnerabilities in OS packages installed during the Docker build\n- the final package set that actually ships in the container\n\nThat matters for Sambee because the final image includes native tooling and runtime libraries that are outside the normal `pip`, `npm`, and `cargo` manifest audits.\n\n## Trivy Setup\n\nSambee currently uses Trivy in two places.\n\nBoth workflows resolve the Trivy runtime image from `.github/tools/trivy/Dockerfile`, so the pin is reviewed once and Dependabot can update it through the `docker` ecosystem.\n\nBoth workflows also force a fresh rebuild of the Dockerfile layer that installs Debian packages.\n\nThey do that with a workflow-provided refresh key passed into the image build, so `apt-get update`, `apt-get upgrade`, and package installation rerun against the latest repository state available at build time while the rest of the image can still benefit from BuildKit caching.\n\n### Weekly Image Scan on `main`\n\n`.github/workflows/docker-image-security-scan.yml` builds the current production image from `main` and scans it once per week.\n\nThe scan currently:\n\n- builds and scans the supported `linux/amd64` and `linux/arm64` image variants separately\n- forces a fresh rebuild of the Debian package-install layer for each workflow run\n- uses `.trivyignore.yaml` as the reviewed suppression file\n- shows suppressed findings in the output\n- checks OS packages and application libraries\n- considers only `HIGH` and `CRITICAL` vulnerabilities\n- ignores unfixed vulnerabilities\n- fails the workflow when matching fixed vulnerabilities remain after suppression\n\nThis is the workflow that tells you a shipped runtime stack has picked up a newly disclosed issue even when no new Sambee release is in progress.\n\n### Preview Publish Scan\n\n`.github/workflows/docker-image-preview-publish.yml` runs Trivy against each pushed preview platform image before those platform manifests are assembled into the preview candidate index.\n\nCurrent preview behavior is intentionally advisory:\n\n- the preview build forces a fresh rebuild of the Debian package-install layer before Trivy runs and before the candidate is published\n- Trivy scans the same pushed platform digests that are later assembled into the final preview candidate\n- preview publishes still show matching `HIGH` or `CRITICAL` findings\n- the findings do not block publication to the `test` channel\n\nThat keeps the newest preview candidate available for validation while still surfacing image risk clearly in CI.\n\n## Trivy Ignore Policy\n\nThe repository-root `.trivyignore.yaml` file is the shared suppression file for both Trivy workflows.\n\nKeep entries narrow and reviewable.\n\nEach suppression should include:\n\n- the finding ID\n- a short statement describing why the risk is accepted temporarily\n- an `expired_at` date so the exception must be revisited explicitly\n\nThat keeps long-lived silent exceptions from accumulating in the image-security workflows.\n\n## Artifact Integrity\n\nThe preview publish and release promotion workflows enable:\n\n- SBOM and provenance bundle publication in a dedicated metadata repository\n- Cosign signing of the pushed image digest through GitHub Actions OIDC\n\nRelease promotion also verifies that the preview-built metadata bundle matches the candidate digest before channel tags are moved.\n\nRelease and backfill workflows mirror the exact metadata bundle files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in GHCR remains the canonical store.\n\nCosign signatures are stored in a dedicated GHCR repository instead of the main image repository.\n\nCurrent split:\n\n- deployable images and multi-arch manifests stay under `ghcr.io/\u003cowner\u003e/sambee`\n- SBOM and provenance metadata bundles and Cosign signature artifacts are written under `ghcr.io/\u003cowner\u003e/sambee-signatures`\n\nFor Cosign-managed signatures, GHCR can display a digest-derived tagged signature artifact together with an untagged referenced bundle manifest for the same retained image digest.\n\nThat keeps the main package page focused on deployable image versions instead of showing non-runnable attestation content there.\n\nThose controls do not replace vulnerability scanning.\n\nThey answer a different question: whether a published artifact can be traced and verified after it is built.\n\n## Workflow Pinning Discipline\n\nSecurity-relevant GitHub Actions in this repository are pinned by commit SHA rather than floating major tags.\n\nThat reduces uncontrolled workflow drift in the automation layer itself.\n\nTreat action-version changes in these workflows as reviewed dependency changes, not as incidental cleanup.\n\n## How This Fits with Dependency Security\n\nUse [Dependency Security and Dependabot](../dependency-security-and-dependabot/) for the repository's dependency intake rules, Dependabot grouping, and scheduled dependency vulnerability audits.\n\n", "2.0": "+++\ntitle = \"Container Image Security and Artifact Integrity\"\n+++\n\nContainer-image security answers a different question than dependency-manifest auditing.\n\nSambee uses Trivy and release-artifact integrity controls to validate the final published container image, not just the repository dependency files.\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/docker-image-security-scan.yml` | builds the current `main` image and runs the weekly Trivy scan |\n| `.github/workflows/docker-image-preview-publish.yml` | runs the preview-candidate Trivy scan before publishing to the `test` channel |\n| `.github/workflows/docker-image-publish.yml` | promotes a verified candidate digest onto release tags after checking image metadata and the published metadata bundle |\n| `.github/scripts/verify_candidate_metadata_bundle.sh` | verifies that the preview-built SBOM and provenance bundle exists under the expected digest-derived metadata tag |\n| `.github/tools/trivy/Dockerfile` | pins the Trivy container image version that both scan workflows use |\n| `.trivyignore.yaml` | holds reviewed Trivy suppressions for the image scans |\n| `Dockerfile` | defines the runtime artifact that is actually scanned and published |\n\n## Why Trivy Exists Alongside Dependency Audits\n\nDependency audits help with application dependency drift.\n\nTrivy adds coverage for the built runtime artifact itself, especially:\n\n- vulnerabilities inherited from the pinned base image\n- vulnerabilities in OS packages installed during the Docker build\n- the final package set that actually ships in the container\n\nThat matters for Sambee because the final image includes native tooling and runtime libraries that are outside the normal `pip`, `npm`, and `cargo` manifest audits.\n\n## Trivy Setup\n\nSambee currently uses Trivy in two places.\n\nBoth workflows resolve the Trivy runtime image from `.github/tools/trivy/Dockerfile`, so the pin is reviewed once and Dependabot can update it through the `docker` ecosystem.\n\nBoth workflows also force a fresh rebuild of the Dockerfile layer that installs Debian packages.\n\nThey do that with a workflow-provided refresh key passed into the image build, so `apt-get update`, `apt-get upgrade`, and package installation rerun against the latest repository state available at build time while the rest of the image can still benefit from BuildKit caching.\n\n### Weekly Image Scan on `main`\n\n`.github/workflows/docker-image-security-scan.yml` builds the current production image from `main` and scans it once per week.\n\nThe scan currently:\n\n- builds and scans the supported `linux/amd64` and `linux/arm64` image variants separately\n- forces a fresh rebuild of the Debian package-install layer for each workflow run\n- uses `.trivyignore.yaml` as the reviewed suppression file\n- shows suppressed findings in the output\n- checks OS packages and application libraries\n- considers only `HIGH` and `CRITICAL` vulnerabilities\n- ignores unfixed vulnerabilities\n- fails the workflow when matching fixed vulnerabilities remain after suppression\n\nThis is the workflow that tells you a shipped runtime stack has picked up a newly disclosed issue even when no new Sambee release is in progress.\n\n### Preview Publish Scan\n\n`.github/workflows/docker-image-preview-publish.yml` runs Trivy against each pushed preview platform image before those platform manifests are assembled into the preview candidate index.\n\nCurrent preview behavior is intentionally advisory:\n\n- the preview build forces a fresh rebuild of the Debian package-install layer before Trivy runs and before the candidate is published\n- Trivy scans the same pushed platform digests that are later assembled into the final preview candidate\n- preview publishes still show matching `HIGH` or `CRITICAL` findings\n- the findings do not block publication to the `test` channel\n\nThat keeps the newest preview candidate available for validation while still surfacing image risk clearly in CI.\n\n## Trivy Ignore Policy\n\nThe repository-root `.trivyignore.yaml` file is the shared suppression file for both Trivy workflows.\n\nKeep entries narrow and reviewable.\n\nEach suppression should include:\n\n- the finding ID\n- a short statement describing why the risk is accepted temporarily\n- an `expired_at` date so the exception must be revisited explicitly\n\nThat keeps long-lived silent exceptions from accumulating in the image-security workflows.\n\n## Artifact Integrity\n\nThe preview publish and release promotion workflows enable:\n\n- SBOM and provenance bundle publication in a dedicated metadata repository\n- Cosign signing of the pushed image digest through GitHub Actions OIDC\n\nRelease promotion also verifies that the preview-built metadata bundle matches the candidate digest before channel tags are moved.\n\nRelease and backfill workflows mirror the exact metadata bundle files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in GHCR remains the canonical store.\n\nCosign signatures are stored in a dedicated GHCR repository instead of the main image repository.\n\nCurrent split:\n\n- deployable images and multi-arch manifests stay under `ghcr.io/\u003cowner\u003e/sambee`\n- SBOM and provenance metadata bundles and Cosign signature artifacts are written under `ghcr.io/\u003cowner\u003e/sambee-signatures`\n\nFor Cosign-managed signatures, GHCR can display a digest-derived tagged signature artifact together with an untagged referenced bundle manifest for the same retained image digest.\n\nThat keeps the main package page focused on deployable image versions instead of showing non-runnable attestation content there.\n\nThose controls do not replace vulnerability scanning.\n\nThey answer a different question: whether a published artifact can be traced and verified after it is built.\n\n## Workflow Pinning Discipline\n\nSecurity-relevant GitHub Actions in this repository are pinned by commit SHA rather than floating major tags.\n\nThat reduces uncontrolled workflow drift in the automation layer itself.\n\nTreat action-version changes in these workflows as reviewed dependency changes, not as incidental cleanup.\n\n## How This Fits with Dependency Security\n\nUse [Dependency Security and Dependabot](../dependency-security-and-dependabot/) for the repository's dependency intake rules, Dependabot grouping, and scheduled dependency vulnerability audits.\n\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:developer-guide/release-and-versioning", "parent_id": "book:developer-guide", "depth": 1, "kind": "section", "label": "release-and-versioning", "title": "Release and Versioning", "path": "developer-guide/release-and-versioning", "has_children": true, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "branched", "source_version": "0.7", "diff_added": 2, "diff_removed": 6}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "inherited", "source_version": "0.9"}}, "content_versions": {"0.7": "+++\ntitle = \"Release and Versioning\"\n+++\n\nThis section covers the workflows where a small metadata mistake can create cross-boundary drift.\n\nFor a complete Sambee product release, start here:\n\n- [Release Checklist](./release-checklist/)\n- [Product Versioning](./product-versioning/)\n\nFor dependency changes, use:\n\n- [Dependency Update Workflow](./dependency-update-workflow/)\n\nFor Sambee Docker image releases, read these pages in order:\n\n- [Docker Release Overview](./docker-release-overview/)\n- [Build Docker Image](./build-docker-image/)\n- [Promote Docker Image](./promote-docker-image/)\n- [Docker Backfill And Cleanup](./docker-backfill-and-cleanup/)\n\nUse these pages when the goal is to take one reviewed commit all the way to `stable` without rebuilding at release time.\n\nFor Companion release distribution, read these pages in order:\n\n- [Companion Release Overview](./companion-release-overview/)\n- [Build Companion Release](./build-companion-release/)\n- [Promote Companion Release](./promote-companion-release/)\n- [Companion Channels, Feeds, And Downloads](./companion-channels-feeds-and-downloads/)\n\nUse this section when you are changing version numbers, updating reviewed dependencies, or publishing a product release.\n", "0.8": "+++\ntitle = \"Release and Versioning\"\n+++\n\nThis section covers the workflows where a small metadata mistake can create cross-boundary drift.\n\nFor a complete Sambee product release, start here:\n\n- [Release Checklist](./release-checklist/)\n- [Product Versioning](./product-versioning/)\n\nFor dependency changes, use:\n\n- [Dependency Update Workflow](./dependency-update-workflow/)\n\nFor Sambee Docker image releases, read these pages in order:\n\n- [Docker Release Overview](./docker-release-overview/)\n- [Build Docker Image](./build-docker-image/)\n- [Promote Docker Image](./promote-docker-image/)\n- [Docker Backfill And Cleanup](./docker-backfill-and-cleanup/)\n\nUse these pages when the goal is to take one reviewed commit all the way to `stable` without rebuilding at release time.\n\nFor Companion release distribution, read these pages in order:\n\n- [Companion Release Overview](./companion-release-overview/)\n- [Build Companion Release](./build-companion-release/)\n- [Promote Companion Release](./promote-companion-release/)\n- [Companion Channels, Feeds, And Downloads](./companion-channels-feeds-and-downloads/)\n\nUse this section when you are changing version numbers, updating reviewed dependencies, or publishing a product release.\n", "0.9": "+++\ntitle = \"Release and Versioning\"\n+++\n\nThis section covers the process of publishing new versions of the Docker image and the Companion app.\n\nFor a complete Sambee product release, start here:\n\n- [Release Overview](./release-overview/)\n- [Product Versioning](./product-versioning/)\n\nFor dependency changes, use:\n\n- [Dependency Update Workflow](./dependency-update-workflow/)\n\nFor Sambee Docker image releases, read these pages in order:\n\n- [Docker Release Overview](./docker-release-overview/)\n- [Build Docker Image](./build-docker-image/)\n- [Promote Docker Image](./promote-docker-image/)\n- [Docker Backfill And Cleanup](./docker-backfill-and-cleanup/)\n\nFor Companion release distribution, read these pages in order:\n\n- [Companion Release Overview](./companion-release-overview/)\n- [Build Companion Release](./build-companion-release/)\n- [Promote Companion Release](./promote-companion-release/)\n- [Companion Channels, Feeds, And Downloads](./companion-channels-feeds-and-downloads/)\n", "1.0": "+++\ntitle = \"Release and Versioning\"\n+++\n\nThis section covers the process of publishing new versions of the Docker image and the Companion app.\n\nFor a complete Sambee product release, start here:\n\n- [Release Overview](./release-overview/)\n- [Product Versioning](./product-versioning/)\n\nFor dependency changes, use:\n\n- [Dependency Update Workflow](./dependency-update-workflow/)\n\nFor Sambee Docker image releases, read these pages in order:\n\n- [Docker Release Overview](./docker-release-overview/)\n- [Build Docker Image](./build-docker-image/)\n- [Promote Docker Image](./promote-docker-image/)\n- [Docker Backfill And Cleanup](./docker-backfill-and-cleanup/)\n\nFor Companion release distribution, read these pages in order:\n\n- [Companion Release Overview](./companion-release-overview/)\n- [Build Companion Release](./build-companion-release/)\n- [Promote Companion Release](./promote-companion-release/)\n- [Companion Channels, Feeds, And Downloads](./companion-channels-feeds-and-downloads/)\n", "2.0": "+++\ntitle = \"Release and Versioning\"\n+++\n\nThis section covers the process of publishing new versions of the Docker image and the Companion app.\n\nFor a complete Sambee product release, start here:\n\n- [Release Overview](./release-overview/)\n- [Product Versioning](./product-versioning/)\n\nFor dependency changes, use:\n\n- [Dependency Update Workflow](./dependency-update-workflow/)\n\nFor Sambee Docker image releases, read these pages in order:\n\n- [Docker Release Overview](./docker-release-overview/)\n- [Build Docker Image](./build-docker-image/)\n- [Promote Docker Image](./promote-docker-image/)\n- [Docker Backfill And Cleanup](./docker-backfill-and-cleanup/)\n\nFor Companion release distribution, read these pages in order:\n\n- [Companion Release Overview](./companion-release-overview/)\n- [Build Companion Release](./build-companion-release/)\n- [Promote Companion Release](./promote-companion-release/)\n- [Companion Channels, Feeds, And Downloads](./companion-channels-feeds-and-downloads/)\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/release-and-versioning/dependency-update-workflow", "parent_id": "section:developer-guide/release-and-versioning", "depth": 2, "kind": "page", "label": "dependency-update-workflow", "title": "Dependency Update Workflow", "path": "developer-guide/release-and-versioning/dependency-update-workflow", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "branched", "source_version": "0.7", "diff_added": 3, "diff_removed": 2}, "1.0": {"state": "branched", "source_version": "0.9", "diff_added": 12, "diff_removed": 14}, "2.0": {"state": "branched", "source_version": "1.0", "diff_added": 32, "diff_removed": 1}}, "content_versions": {"0.7": "+++\ntitle = \"Dependency Update Workflow\"\n+++\n\nUse this page for routine dependency updates and dependency-related release preparation. Use [Product Versioning](../product-versioning/) when changing the Sambee version, and [Release Checklist](../release-checklist/) when preparing a complete product release.\n\n## Dependency Update Rules\n\nRoutine install behavior and actual dependency changes are different workflows.\n\n- use `npm ci` for routine installs in `frontend/` and `companion/`\n- use the hashed backend lockfiles for routine Python installs\n- do not hand-edit generated lockfile details when the repository already provides a regeneration workflow\n\n### Backend Dependency Updates\n\nFor backend dependency changes:\n\n- update the reviewed top-level requirement files first\n- regenerate backend lockfiles with the supported refresh script\n- use `scripts/refresh-backend-lockfiles --check` for a read-only freshness check when needed\n- validate with backend tests and type checking\n\nThat keeps direct requirements, transitive dependencies, and hashes aligned.\n\nMore specifically:\n\n- change `requirements.txt` and `requirements-dev.txt`, not only the generated lockfiles\n- regenerate `requirements.lock.txt` and `requirements-dev.lock.txt` through `scripts/refresh-backend-lockfiles`\n- treat resolver conflicts as real compatibility constraints instead of forcing transitive pins by hand\n- avoid hand-editing lockfile hashes except as a last resort\n\nFor an already-open backend dependency-update PR:\n\n- review the direct requirement changes first\n- run `scripts/refresh-backend-lockfiles --check` if you want a quick stale-lockfile check before editing\n- regenerate the lockfiles from the reviewed sources\n- validate with at least `pytest -v` and `mypy app`\n- commit regenerated lockfiles back to the update branch instead of patching transitive entries manually\n\n### High-Risk Dependency Areas\n\nSome ecosystems are intentionally treated as coordinated manual changes rather than casual bumps.\n\n- Python runtime version\n- high-risk frontend packages such as React, Vite, TypeScript, and MUI\n- companion Tauri package and crate alignment\n- backend packages with higher behavioral risk such as `smbprotocol` and `pyvips`\n\nAdditional contributor rules in those areas:\n\n- keep companion Tauri JavaScript packages and Rust crates on matching major.minor versions\n- validate companion Tauri alignment with `scripts/check_tauri_version_alignment.py` when those dependencies move\n- treat Python runtime upgrades as coordinated manual changes across production Docker, the devcontainer, and CI\n- prefer committed scripts and lockfiles over one-off installers or floating `npx` downloads\n\n## Dependency Security Audits\n\nThe audit workflow and Dependabot configuration now live in the Developer Guide security section.\n\nUse [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/) for:\n\n- Dependabot grouping and ignore rules\n- scheduled dependency audit coverage\n\nUse [Container Image Security and Artifact Integrity](../../security/container-image-security-and-artifact-integrity/) for:\n\n- container-image vulnerability scanning\n- Trivy suppression policy\n- image signing, SBOM, and provenance controls\n\nKeep this page focused on dependency inputs, generated lockfiles, and dependency-specific validation.\n\n## Validation Expectations\n\nAt minimum, run the checks for the subsystem whose release-sensitive files changed.\n\nCommon examples:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nChoose the relevant subset based on the dependencies that changed.\n", "0.8": "+++\ntitle = \"Dependency Update Workflow\"\n+++\n\nUse this page for routine dependency updates and dependency-related release preparation. Use [Product Versioning](../product-versioning/) when changing the Sambee version, and [Release Checklist](../release-checklist/) when preparing a complete product release.\n\n## Dependency Update Rules\n\nRoutine install behavior and actual dependency changes are different workflows.\n\n- use `npm ci` for routine installs in `frontend/` and `companion/`\n- use the hashed backend lockfiles for routine Python installs\n- do not hand-edit generated lockfile details when the repository already provides a regeneration workflow\n\n### Backend Dependency Updates\n\nFor backend dependency changes:\n\n- update the reviewed top-level requirement files first\n- regenerate backend lockfiles with the supported refresh script\n- use `scripts/refresh-backend-lockfiles --check` for a read-only freshness check when needed\n- validate with backend tests and type checking\n\nThat keeps direct requirements, transitive dependencies, and hashes aligned.\n\nMore specifically:\n\n- change `requirements.txt` and `requirements-dev.txt`, not only the generated lockfiles\n- regenerate `requirements.lock.txt` and `requirements-dev.lock.txt` through `scripts/refresh-backend-lockfiles`\n- treat resolver conflicts as real compatibility constraints instead of forcing transitive pins by hand\n- avoid hand-editing lockfile hashes except as a last resort\n\nFor an already-open backend dependency-update PR:\n\n- review the direct requirement changes first\n- run `scripts/refresh-backend-lockfiles --check` if you want a quick stale-lockfile check before editing\n- regenerate the lockfiles from the reviewed sources\n- validate with at least `pytest -v` and `mypy app`\n- commit regenerated lockfiles back to the update branch instead of patching transitive entries manually\n\n### High-Risk Dependency Areas\n\nSome ecosystems are intentionally treated as coordinated manual changes rather than casual bumps.\n\n- Python runtime version\n- high-risk frontend packages such as React, Vite, TypeScript, and MUI\n- companion Tauri package and crate alignment\n- backend packages with higher behavioral risk such as `smbprotocol` and `pyvips`\n\nAdditional contributor rules in those areas:\n\n- keep companion Tauri JavaScript packages and Rust crates on matching major.minor versions\n- validate companion Tauri alignment with `scripts/check_tauri_version_alignment.py` when those dependencies move\n- treat Python runtime upgrades as coordinated manual changes across production Docker, the devcontainer, and CI\n- prefer committed scripts and lockfiles over one-off installers or floating `npx` downloads\n\n## Dependency Security Audits\n\nThe audit workflow and Dependabot configuration now live in the Developer Guide security section.\n\nUse [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/) for:\n\n- Dependabot grouping and ignore rules\n- scheduled dependency audit coverage\n\nUse [Container Image Security and Artifact Integrity](../../security/container-image-security-and-artifact-integrity/) for:\n\n- container-image vulnerability scanning\n- Trivy suppression policy\n- image signing, SBOM, and provenance controls\n\nKeep this page focused on dependency inputs, generated lockfiles, and dependency-specific validation.\n\n## Validation Expectations\n\nAt minimum, run the checks for the subsystem whose release-sensitive files changed.\n\nCommon examples:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nChoose the relevant subset based on the dependencies that changed.\n", "0.9": "+++\ntitle = \"Dependency Update Workflow\"\n+++\n\nUse this page for routine dependency updates and dependency-related release preparation. Use [Product Versioning](../product-versioning/) when changing the Sambee version, and [Release Checklist](../release-checklist/) when preparing a complete product release.\n\n## Dependency Update Rules\n\nRoutine install behavior and actual dependency changes are different workflows.\n\n- use `npm ci` for routine installs in `frontend/` and `companion/`\n- use the hashed backend lockfiles for routine Python installs\n- do not hand-edit generated lockfile details when the repository already provides a regeneration workflow\n\n### Backend Dependency Updates\n\nFor backend dependency changes:\n\n- update the reviewed top-level requirement files first\n- regenerate backend lockfiles with the supported refresh script\n- use `scripts/refresh-backend-lockfiles --check` for a read-only freshness check when needed\n- validate with backend tests and type checking\n\nThat keeps direct requirements, transitive dependencies, and hashes aligned.\n\nMore specifically:\n\n- change `requirements.txt` and `requirements-dev.txt`, not only the generated lockfiles\n- regenerate `requirements.lock.txt` and `requirements-dev.lock.txt` through `scripts/refresh-backend-lockfiles`\n- treat resolver conflicts as real compatibility constraints instead of forcing transitive pins by hand\n- avoid hand-editing lockfile hashes except as a last resort\n\nFor an already-open backend dependency-update PR:\n\n- review the direct requirement changes first\n- run `scripts/refresh-backend-lockfiles --check` if you want a quick stale-lockfile check before editing\n- regenerate the lockfiles from the reviewed sources\n- validate with at least `pytest -v` and `mypy app`\n- commit regenerated lockfiles back to the update branch instead of patching transitive entries manually\n\n### High-Risk Dependency Areas\n\nSome ecosystems are intentionally treated as coordinated manual changes rather than casual bumps.\n\n- high-risk frontend packages such as React, Vite, TypeScript, and MUI\n- companion Tauri package and crate alignment\n- backend packages with higher behavioral risk such as `smbprotocol` and `pyvips`\n\nAdditional contributor rules in those areas:\n\n- keep companion Tauri JavaScript packages and Rust crates on matching major.minor versions\n- validate companion Tauri alignment with `scripts/check_tauri_version_alignment.py` when those dependencies move\n- review Dependabot proposals for the shared Python runtime base as container-runtime changes\n- confirm Docker target validation reports the expected Python and SQLite versions before merging a Python runtime update\n- expect Debian packages to refresh during cache-busted image builds; do not hand-pin individual APT packages unless reproducibility requirements change\n- prefer committed scripts and lockfiles over one-off installers or floating `npx` downloads\n\n## Dependency Security Audits\n\nThe audit workflow and Dependabot configuration now live in the Developer Guide security section.\n\nUse [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/) for:\n\n- Dependabot grouping and ignore rules\n- scheduled dependency audit coverage\n\nUse [Container Image Security and Artifact Integrity](../../security/container-image-security-and-artifact-integrity/) for:\n\n- container-image vulnerability scanning\n- Trivy suppression policy\n- image signing, SBOM, and provenance controls\n\nKeep this page focused on dependency inputs, generated lockfiles, and dependency-specific validation.\n\n## Validation Expectations\n\nAt minimum, run the checks for the subsystem whose release-sensitive files changed.\n\nCommon examples:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nChoose the relevant subset based on the dependencies that changed.\n", "1.0": "+++\ntitle = \"Dependency Update Workflow\"\n+++\n\nUse this page for routine dependency updates and dependency-related release preparation. Use [Product Versioning](../product-versioning/) when changing the Sambee version, and [Release Checklist](../release-checklist/) when preparing a complete product release.\n\n## Dependency Update Rules\n\nRoutine install behavior and actual dependency changes are different workflows.\n\n- use `npm ci` for routine installs in `frontend/` and `companion/`\n- use the hashed backend lockfiles for routine Python installs\n- do not hand-edit generated lockfile details when the repository already provides a regeneration workflow\n- accept Dependabot updates to backend requirements and pip-compile lockfiles when CI validation passes\n\n### Backend Dependency Updates\n\nFor routine Dependabot backend dependency-update pull requests:\n\n- review the direct requirement and generated lockfile changes\n- do not rerun the backend lockfile refresh script only to satisfy CI\n- validate with backend tests and type checking\n\nCI verifies that direct source pins match both generated lockfiles. The backend\ntest image and production Docker image validate hash-enforced installations.\n\nFor manual backend dependency changes or an intentional full transitive refresh:\n\n- update `requirements.txt` and `requirements-dev.txt` first\n- regenerate `requirements.lock.txt` and `requirements-dev.lock.txt` through `scripts/refresh-backend-lockfiles`\n- treat resolver conflicts as real compatibility constraints instead of forcing transitive pins by hand\n- avoid hand-editing lockfile hashes except as a last resort\n\nUse `scripts/refresh-backend-lockfiles --check` when you deliberately want to\ncompare the committed locks with a new clean dependency resolution. It is an\noptional maintenance check, not a required step for routine Dependabot pull\nrequests.\n\n### High-Risk Dependency Areas\n\nSome ecosystems are intentionally treated as coordinated manual changes rather than casual bumps.\n\n- high-risk frontend packages such as React, Vite, TypeScript, and MUI\n- companion Tauri package and crate alignment\n- backend packages with higher behavioral risk such as `smbprotocol` and `pyvips`\n\nAdditional contributor rules in those areas:\n\n- keep companion Tauri JavaScript packages and Rust crates on matching major.minor versions\n- validate companion Tauri alignment with `scripts/check_tauri_version_alignment.py` when those dependencies move\n- review Dependabot proposals for the shared Python runtime base as container-runtime changes\n- confirm Docker target validation reports the expected Python and SQLite versions before merging a Python runtime update\n- expect Debian packages to refresh during cache-busted image builds; do not hand-pin individual APT packages unless reproducibility requirements change\n- prefer committed scripts and lockfiles over one-off installers or floating `npx` downloads\n\n## Dependency Security Audits\n\nThe audit workflow and Dependabot configuration now live in the Developer Guide security section.\n\nUse [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/) for:\n\n- Dependabot grouping and ignore rules\n- scheduled dependency audit coverage\n\nUse [Container Image Security and Artifact Integrity](../../security/container-image-security-and-artifact-integrity/) for:\n\n- container-image vulnerability scanning\n- Trivy suppression policy\n- image signing, SBOM, and provenance controls\n\nKeep this page focused on dependency inputs, generated lockfiles, and dependency-specific validation.\n\n## Validation Expectations\n\nAt minimum, run the checks for the subsystem whose release-sensitive files changed.\n\nCommon examples:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nChoose the relevant subset based on the dependencies that changed.\n", "2.0": "+++\ntitle = \"Dependency Update Workflow\"\n+++\n\nUse this page for routine dependency updates and dependency-related release preparation. Use [Product Versioning](../product-versioning/) when changing the Sambee version, and [Release Checklist](../release-checklist/) when preparing a complete product release.\n\n## Dependency Update Rules\n\nRoutine install behavior and actual dependency changes are different workflows.\n\n- use `npm ci` for routine installs in `frontend/` and `companion/`\n- use the hashed backend lockfiles for routine Python installs\n- do not hand-edit generated lockfile details when the repository already provides a regeneration workflow\n- accept Dependabot updates to backend requirements and pip-compile lockfiles when CI validation passes\n\n### Frontend Install Freshness\n\n`./scripts/test` checks frontend dependency freshness before generating test\nfixtures or running backend tests. It stops if the install stamp is missing or\ndoesn't match the current `frontend/package.json` and\n`frontend/package-lock.json`. It doesn't install dependencies automatically or\nrequire network access for the check.\n\nTo restore the frontend environment, run this from the repository root:\n\n```bash\ncd frontend \u0026\u0026 npm ci\n```\n\nThe install lifecycle clears any previous stamp before setup and writes a SHA-256\nhash to `frontend/node_modules/.dependencies.sha256` only after the existing\npostinstall setup succeeds. The stamp is local to the installed environment and\nisn't committed. Existing installations need one successful `npm ci` to create\nit. Installations using `--ignore-scripts` won't create the stamp.\n\nTo check the environment separately, run:\n\n```bash\ncd frontend \u0026\u0026 npm run check:dependencies\n```\n\nThe hash covers both files in full, so metadata-only changes also require a fresh\ninstall. This check detects changed dependency inputs, not arbitrary damage to\ninstalled packages. If individual packages are missing despite a matching stamp,\nrun `npm ci` again.\n\n### Backend Dependency Updates\n\nFor routine Dependabot backend dependency-update pull requests:\n\n- review the direct requirement and generated lockfile changes\n- do not rerun the backend lockfile refresh script only to satisfy CI\n- validate with backend tests and type checking\n\nCI verifies that direct source pins match both generated lockfiles. The backend\ntest image and production Docker image validate hash-enforced installations.\n\nFor manual backend dependency changes or an intentional full transitive refresh:\n\n- update `requirements.txt` and `requirements-dev.txt` first\n- regenerate `requirements.lock.txt` and `requirements-dev.lock.txt` through `scripts/refresh-backend-lockfiles`\n- treat resolver conflicts as real compatibility constraints instead of forcing transitive pins by hand\n- avoid hand-editing lockfile hashes except as a last resort\n\nUse `scripts/refresh-backend-lockfiles --check` when you deliberately want to\ncompare the committed locks with a new clean dependency resolution. It is an\noptional maintenance check, not a required step for routine Dependabot pull\nrequests.\n\n### High-Risk Dependency Areas\n\nSome ecosystems are intentionally treated as coordinated manual changes rather than casual bumps.\n\n- high-risk frontend packages such as React, Vite, TypeScript, and MUI\n- companion Tauri package and crate alignment\n- backend packages with higher behavioral risk such as `smbprotocol` and `pyvips`\n\nAdditional contributor rules in those areas:\n\n- keep companion Tauri JavaScript packages and Rust crates on matching major.minor versions\n- validate companion Tauri alignment with `scripts/check_tauri_version_alignment.py` when those dependencies move\n- review Dependabot proposals for the shared Python runtime base as container-runtime changes\n- confirm Docker target validation reports the expected Python and SQLite versions before merging a Python runtime update\n- expect Debian packages to refresh during cache-busted image builds; do not hand-pin individual APT packages unless reproducibility requirements change\n- prefer committed scripts and lockfiles over one-off installers or floating `npx` downloads\n\n## Dependency Security Audits\n\nThe audit workflow and Dependabot configuration now live in the Developer Guide security section.\n\nUse [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/) for:\n\n- Dependabot grouping and ignore rules\n- scheduled dependency audit coverage\n\nUse [Container Image Security and Artifact Integrity](../../security/container-image-security-and-artifact-integrity/) for:\n\n- container-image vulnerability scanning\n- Trivy suppression policy\n- image signing, SBOM, and provenance controls\n\nKeep this page focused on dependency inputs, generated lockfiles, and dependency-specific validation.\n\n## Validation Expectations\n\nAt minimum, run the checks for the subsystem whose release-sensitive files changed.\n\nCommon examples:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npm run typecheck \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nChoose the relevant subset based on the dependencies that changed.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Dependency Update Workflow\"\n+++\n\nUse this page for routine dependency updates and dependency-related release preparation. Use [Product Versioning](../product-versioning/) when changing the Sambee version, and [Release Checklist](../release-checklist/) when preparing a complete product release.\n\n## Dependency Update Rules\n\nRoutine install behavior and actual dependency changes are different workflows.\n\n- use `npm ci` for routine installs in `frontend/` and `companion/`\n- use the hashed backend lockfiles for routine Python installs\n- do not hand-edit generated lockfile details when the repository already provides a regeneration workflow\n\n### Backend Dependency Updates\n\nFor backend dependency changes:\n\n- update the reviewed top-level requirement files first\n- regenerate backend lockfiles with the supported refresh script\n- use `scripts/refresh-backend-lockfiles --check` for a read-only freshness check when needed\n- validate with backend tests and type checking\n\nThat keeps direct requirements, transitive dependencies, and hashes aligned.\n\nMore specifically:\n\n- change `requirements.txt` and `requirements-dev.txt`, not only the generated lockfiles\n- regenerate `requirements.lock.txt` and `requirements-dev.lock.txt` through `scripts/refresh-backend-lockfiles`\n- treat resolver conflicts as real compatibility constraints instead of forcing transitive pins by hand\n- avoid hand-editing lockfile hashes except as a last resort\n\nFor an already-open backend dependency-update PR:\n\n- review the direct requirement changes first\n- run `scripts/refresh-backend-lockfiles --check` if you want a quick stale-lockfile check before editing\n- regenerate the lockfiles from the reviewed sources\n- validate with at least `pytest -v` and `mypy app`\n- commit regenerated lockfiles back to the update branch instead of patching transitive entries manually\n\n### High-Risk Dependency Areas\n\nSome ecosystems are intentionally treated as coordinated manual changes rather than casual bumps.\n\n- Python runtime version\n- high-risk frontend packages such as React, Vite, TypeScript, and MUI\n- companion Tauri package and crate alignment\n- backend packages with higher behavioral risk such as `smbprotocol` and `pyvips`\n\nAdditional contributor rules in those areas:\n\n- keep companion Tauri JavaScript packages and Rust crates on matching major.minor versions\n- validate companion Tauri alignment with `scripts/check_tauri_version_alignment.py` when those dependencies move\n- treat Python runtime upgrades as coordinated manual changes across production Docker, the devcontainer, and CI\n- prefer committed scripts and lockfiles over one-off installers or floating `npx` downloads\n\n## Dependency Security Audits\n\nThe audit workflow and Dependabot configuration now live in the Developer Guide security section.\n\nUse [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/) for:\n\n- Dependabot grouping and ignore rules\n- scheduled dependency audit coverage\n\nUse [Container Image Security and Artifact Integrity](../../security/container-image-security-and-artifact-integrity/) for:\n\n- container-image vulnerability scanning\n- Trivy suppression policy\n- image signing, SBOM, and provenance controls\n\nKeep this page focused on dependency inputs, generated lockfiles, and dependency-specific validation.\n\n## Validation Expectations\n\nAt minimum, run the checks for the subsystem whose release-sensitive files changed.\n\nCommon examples:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nChoose the relevant subset based on the dependencies that changed.\n", "0.8": "+++\ntitle = \"Dependency Update Workflow\"\n+++\n\nUse this page for routine dependency updates and dependency-related release preparation. Use [Product Versioning](../product-versioning/) when changing the Sambee version, and [Release Checklist](../release-checklist/) when preparing a complete product release.\n\n## Dependency Update Rules\n\nRoutine install behavior and actual dependency changes are different workflows.\n\n- use `npm ci` for routine installs in `frontend/` and `companion/`\n- use the hashed backend lockfiles for routine Python installs\n- do not hand-edit generated lockfile details when the repository already provides a regeneration workflow\n\n### Backend Dependency Updates\n\nFor backend dependency changes:\n\n- update the reviewed top-level requirement files first\n- regenerate backend lockfiles with the supported refresh script\n- use `scripts/refresh-backend-lockfiles --check` for a read-only freshness check when needed\n- validate with backend tests and type checking\n\nThat keeps direct requirements, transitive dependencies, and hashes aligned.\n\nMore specifically:\n\n- change `requirements.txt` and `requirements-dev.txt`, not only the generated lockfiles\n- regenerate `requirements.lock.txt` and `requirements-dev.lock.txt` through `scripts/refresh-backend-lockfiles`\n- treat resolver conflicts as real compatibility constraints instead of forcing transitive pins by hand\n- avoid hand-editing lockfile hashes except as a last resort\n\nFor an already-open backend dependency-update PR:\n\n- review the direct requirement changes first\n- run `scripts/refresh-backend-lockfiles --check` if you want a quick stale-lockfile check before editing\n- regenerate the lockfiles from the reviewed sources\n- validate with at least `pytest -v` and `mypy app`\n- commit regenerated lockfiles back to the update branch instead of patching transitive entries manually\n\n### High-Risk Dependency Areas\n\nSome ecosystems are intentionally treated as coordinated manual changes rather than casual bumps.\n\n- Python runtime version\n- high-risk frontend packages such as React, Vite, TypeScript, and MUI\n- companion Tauri package and crate alignment\n- backend packages with higher behavioral risk such as `smbprotocol` and `pyvips`\n\nAdditional contributor rules in those areas:\n\n- keep companion Tauri JavaScript packages and Rust crates on matching major.minor versions\n- validate companion Tauri alignment with `scripts/check_tauri_version_alignment.py` when those dependencies move\n- treat Python runtime upgrades as coordinated manual changes across production Docker, the devcontainer, and CI\n- prefer committed scripts and lockfiles over one-off installers or floating `npx` downloads\n\n## Dependency Security Audits\n\nThe audit workflow and Dependabot configuration now live in the Developer Guide security section.\n\nUse [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/) for:\n\n- Dependabot grouping and ignore rules\n- scheduled dependency audit coverage\n\nUse [Container Image Security and Artifact Integrity](../../security/container-image-security-and-artifact-integrity/) for:\n\n- container-image vulnerability scanning\n- Trivy suppression policy\n- image signing, SBOM, and provenance controls\n\nKeep this page focused on dependency inputs, generated lockfiles, and dependency-specific validation.\n\n## Validation Expectations\n\nAt minimum, run the checks for the subsystem whose release-sensitive files changed.\n\nCommon examples:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nChoose the relevant subset based on the dependencies that changed.\n", "0.9": "+++\ntitle = \"Dependency Update Workflow\"\n+++\n\nUse this page for routine dependency updates and dependency-related release preparation. Use [Product Versioning](../product-versioning/) when changing the Sambee version, and [Release Checklist](../release-checklist/) when preparing a complete product release.\n\n## Dependency Update Rules\n\nRoutine install behavior and actual dependency changes are different workflows.\n\n- use `npm ci` for routine installs in `frontend/` and `companion/`\n- use the hashed backend lockfiles for routine Python installs\n- do not hand-edit generated lockfile details when the repository already provides a regeneration workflow\n\n### Backend Dependency Updates\n\nFor backend dependency changes:\n\n- update the reviewed top-level requirement files first\n- regenerate backend lockfiles with the supported refresh script\n- use `scripts/refresh-backend-lockfiles --check` for a read-only freshness check when needed\n- validate with backend tests and type checking\n\nThat keeps direct requirements, transitive dependencies, and hashes aligned.\n\nMore specifically:\n\n- change `requirements.txt` and `requirements-dev.txt`, not only the generated lockfiles\n- regenerate `requirements.lock.txt` and `requirements-dev.lock.txt` through `scripts/refresh-backend-lockfiles`\n- treat resolver conflicts as real compatibility constraints instead of forcing transitive pins by hand\n- avoid hand-editing lockfile hashes except as a last resort\n\nFor an already-open backend dependency-update PR:\n\n- review the direct requirement changes first\n- run `scripts/refresh-backend-lockfiles --check` if you want a quick stale-lockfile check before editing\n- regenerate the lockfiles from the reviewed sources\n- validate with at least `pytest -v` and `mypy app`\n- commit regenerated lockfiles back to the update branch instead of patching transitive entries manually\n\n### High-Risk Dependency Areas\n\nSome ecosystems are intentionally treated as coordinated manual changes rather than casual bumps.\n\n- high-risk frontend packages such as React, Vite, TypeScript, and MUI\n- companion Tauri package and crate alignment\n- backend packages with higher behavioral risk such as `smbprotocol` and `pyvips`\n\nAdditional contributor rules in those areas:\n\n- keep companion Tauri JavaScript packages and Rust crates on matching major.minor versions\n- validate companion Tauri alignment with `scripts/check_tauri_version_alignment.py` when those dependencies move\n- review Dependabot proposals for the shared Python runtime base as container-runtime changes\n- confirm Docker target validation reports the expected Python and SQLite versions before merging a Python runtime update\n- expect Debian packages to refresh during cache-busted image builds; do not hand-pin individual APT packages unless reproducibility requirements change\n- prefer committed scripts and lockfiles over one-off installers or floating `npx` downloads\n\n## Dependency Security Audits\n\nThe audit workflow and Dependabot configuration now live in the Developer Guide security section.\n\nUse [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/) for:\n\n- Dependabot grouping and ignore rules\n- scheduled dependency audit coverage\n\nUse [Container Image Security and Artifact Integrity](../../security/container-image-security-and-artifact-integrity/) for:\n\n- container-image vulnerability scanning\n- Trivy suppression policy\n- image signing, SBOM, and provenance controls\n\nKeep this page focused on dependency inputs, generated lockfiles, and dependency-specific validation.\n\n## Validation Expectations\n\nAt minimum, run the checks for the subsystem whose release-sensitive files changed.\n\nCommon examples:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nChoose the relevant subset based on the dependencies that changed.\n", "1.0": "+++\ntitle = \"Dependency Update Workflow\"\n+++\n\nUse this page for routine dependency updates and dependency-related release preparation. Use [Product Versioning](../product-versioning/) when changing the Sambee version, and [Release Checklist](../release-checklist/) when preparing a complete product release.\n\n## Dependency Update Rules\n\nRoutine install behavior and actual dependency changes are different workflows.\n\n- use `npm ci` for routine installs in `frontend/` and `companion/`\n- use the hashed backend lockfiles for routine Python installs\n- do not hand-edit generated lockfile details when the repository already provides a regeneration workflow\n- accept Dependabot updates to backend requirements and pip-compile lockfiles when CI validation passes\n\n### Backend Dependency Updates\n\nFor routine Dependabot backend dependency-update pull requests:\n\n- review the direct requirement and generated lockfile changes\n- do not rerun the backend lockfile refresh script only to satisfy CI\n- validate with backend tests and type checking\n\nCI verifies that direct source pins match both generated lockfiles. The backend\ntest image and production Docker image validate hash-enforced installations.\n\nFor manual backend dependency changes or an intentional full transitive refresh:\n\n- update `requirements.txt` and `requirements-dev.txt` first\n- regenerate `requirements.lock.txt` and `requirements-dev.lock.txt` through `scripts/refresh-backend-lockfiles`\n- treat resolver conflicts as real compatibility constraints instead of forcing transitive pins by hand\n- avoid hand-editing lockfile hashes except as a last resort\n\nUse `scripts/refresh-backend-lockfiles --check` when you deliberately want to\ncompare the committed locks with a new clean dependency resolution. It is an\noptional maintenance check, not a required step for routine Dependabot pull\nrequests.\n\n### High-Risk Dependency Areas\n\nSome ecosystems are intentionally treated as coordinated manual changes rather than casual bumps.\n\n- high-risk frontend packages such as React, Vite, TypeScript, and MUI\n- companion Tauri package and crate alignment\n- backend packages with higher behavioral risk such as `smbprotocol` and `pyvips`\n\nAdditional contributor rules in those areas:\n\n- keep companion Tauri JavaScript packages and Rust crates on matching major.minor versions\n- validate companion Tauri alignment with `scripts/check_tauri_version_alignment.py` when those dependencies move\n- review Dependabot proposals for the shared Python runtime base as container-runtime changes\n- confirm Docker target validation reports the expected Python and SQLite versions before merging a Python runtime update\n- expect Debian packages to refresh during cache-busted image builds; do not hand-pin individual APT packages unless reproducibility requirements change\n- prefer committed scripts and lockfiles over one-off installers or floating `npx` downloads\n\n## Dependency Security Audits\n\nThe audit workflow and Dependabot configuration now live in the Developer Guide security section.\n\nUse [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/) for:\n\n- Dependabot grouping and ignore rules\n- scheduled dependency audit coverage\n\nUse [Container Image Security and Artifact Integrity](../../security/container-image-security-and-artifact-integrity/) for:\n\n- container-image vulnerability scanning\n- Trivy suppression policy\n- image signing, SBOM, and provenance controls\n\nKeep this page focused on dependency inputs, generated lockfiles, and dependency-specific validation.\n\n## Validation Expectations\n\nAt minimum, run the checks for the subsystem whose release-sensitive files changed.\n\nCommon examples:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nChoose the relevant subset based on the dependencies that changed.\n", "2.0": "+++\ntitle = \"Dependency Update Workflow\"\n+++\n\nUse this page for routine dependency updates and dependency-related release preparation. Use [Product Versioning](../product-versioning/) when changing the Sambee version, and [Release Checklist](../release-checklist/) when preparing a complete product release.\n\n## Dependency Update Rules\n\nRoutine install behavior and actual dependency changes are different workflows.\n\n- use `npm ci` for routine installs in `frontend/` and `companion/`\n- use the hashed backend lockfiles for routine Python installs\n- do not hand-edit generated lockfile details when the repository already provides a regeneration workflow\n- accept Dependabot updates to backend requirements and pip-compile lockfiles when CI validation passes\n\n### Frontend Install Freshness\n\n`./scripts/test` checks frontend dependency freshness before generating test\nfixtures or running backend tests. It stops if the install stamp is missing or\ndoesn't match the current `frontend/package.json` and\n`frontend/package-lock.json`. It doesn't install dependencies automatically or\nrequire network access for the check.\n\nTo restore the frontend environment, run this from the repository root:\n\n```bash\ncd frontend \u0026\u0026 npm ci\n```\n\nThe install lifecycle clears any previous stamp before setup and writes a SHA-256\nhash to `frontend/node_modules/.dependencies.sha256` only after the existing\npostinstall setup succeeds. The stamp is local to the installed environment and\nisn't committed. Existing installations need one successful `npm ci` to create\nit. Installations using `--ignore-scripts` won't create the stamp.\n\nTo check the environment separately, run:\n\n```bash\ncd frontend \u0026\u0026 npm run check:dependencies\n```\n\nThe hash covers both files in full, so metadata-only changes also require a fresh\ninstall. This check detects changed dependency inputs, not arbitrary damage to\ninstalled packages. If individual packages are missing despite a matching stamp,\nrun `npm ci` again.\n\n### Backend Dependency Updates\n\nFor routine Dependabot backend dependency-update pull requests:\n\n- review the direct requirement and generated lockfile changes\n- do not rerun the backend lockfile refresh script only to satisfy CI\n- validate with backend tests and type checking\n\nCI verifies that direct source pins match both generated lockfiles. The backend\ntest image and production Docker image validate hash-enforced installations.\n\nFor manual backend dependency changes or an intentional full transitive refresh:\n\n- update `requirements.txt` and `requirements-dev.txt` first\n- regenerate `requirements.lock.txt` and `requirements-dev.lock.txt` through `scripts/refresh-backend-lockfiles`\n- treat resolver conflicts as real compatibility constraints instead of forcing transitive pins by hand\n- avoid hand-editing lockfile hashes except as a last resort\n\nUse `scripts/refresh-backend-lockfiles --check` when you deliberately want to\ncompare the committed locks with a new clean dependency resolution. It is an\noptional maintenance check, not a required step for routine Dependabot pull\nrequests.\n\n### High-Risk Dependency Areas\n\nSome ecosystems are intentionally treated as coordinated manual changes rather than casual bumps.\n\n- high-risk frontend packages such as React, Vite, TypeScript, and MUI\n- companion Tauri package and crate alignment\n- backend packages with higher behavioral risk such as `smbprotocol` and `pyvips`\n\nAdditional contributor rules in those areas:\n\n- keep companion Tauri JavaScript packages and Rust crates on matching major.minor versions\n- validate companion Tauri alignment with `scripts/check_tauri_version_alignment.py` when those dependencies move\n- review Dependabot proposals for the shared Python runtime base as container-runtime changes\n- confirm Docker target validation reports the expected Python and SQLite versions before merging a Python runtime update\n- expect Debian packages to refresh during cache-busted image builds; do not hand-pin individual APT packages unless reproducibility requirements change\n- prefer committed scripts and lockfiles over one-off installers or floating `npx` downloads\n\n## Dependency Security Audits\n\nThe audit workflow and Dependabot configuration now live in the Developer Guide security section.\n\nUse [Dependency Security and Dependabot](../../security/dependency-security-and-dependabot/) for:\n\n- Dependabot grouping and ignore rules\n- scheduled dependency audit coverage\n\nUse [Container Image Security and Artifact Integrity](../../security/container-image-security-and-artifact-integrity/) for:\n\n- container-image vulnerability scanning\n- Trivy suppression policy\n- image signing, SBOM, and provenance controls\n\nKeep this page focused on dependency inputs, generated lockfiles, and dependency-specific validation.\n\n## Validation Expectations\n\nAt minimum, run the checks for the subsystem whose release-sensitive files changed.\n\nCommon examples:\n\n```bash\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npm run typecheck \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nChoose the relevant subset based on the dependencies that changed.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/release-and-versioning/product-versioning", "parent_id": "section:developer-guide/release-and-versioning", "depth": 2, "kind": "page", "label": "product-versioning", "title": "Product Versioning", "path": "developer-guide/release-and-versioning/product-versioning", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "branched", "source_version": "0.7", "diff_added": 13, "diff_removed": 18}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "inherited", "source_version": "0.9"}}, "content_versions": {"0.7": "+++\ntitle = \"Product Versioning\"\n+++\n\nThe Sambee product version has one source of truth. Use this page whenever you change the product version, whether for a prerelease or a stable release.\n\n## Product Version Source of Truth\n\nThe application version lives in:\n\n- `VERSION`\n\nWhen the product version changes:\n\n1. Update `VERSION`.\n1. Run `./scripts/sync-version`.\n1. Review all resulting metadata changes together.\n\nThe sync step updates version-bearing frontend and Companion files so they do not drift away from the root version.\n\n## Files That Move with Product Version Changes\n\nThe sync workflow updates files such as:\n\n- `frontend/package.json`\n- `frontend/package-lock.json`\n- `companion/package.json`\n- `companion/package-lock.json`\n- `companion/src-tauri/Cargo.toml`\n- `companion/src-tauri/tauri.conf.json`\n- `companion/src-tauri/Cargo.lock`\n\nTreat those edits as release metadata, not as noise to separate later.\n\n## Validation\n\nRun the version sync before validating the affected release surfaces. At minimum, review the generated metadata and run the checks required by the changed subsystem.\n\nCommon examples:\n\n```bash\n./scripts/sync-version\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nUse [Release Checklist](../release-checklist/) for the complete product-release sequence.\n\n", "0.8": "+++\ntitle = \"Product Versioning\"\n+++\n\nThe Sambee product version has one source of truth. Use this page whenever you change the product version, whether for a prerelease or a stable release.\n\n## Product Version Source of Truth\n\nThe application version lives in:\n\n- `VERSION`\n\nWhen the product version changes:\n\n1. Update `VERSION`.\n1. Run `./scripts/sync-version`.\n1. Review all resulting metadata changes together.\n\nThe sync step updates version-bearing frontend and Companion files so they do not drift away from the root version.\n\n## Files That Move with Product Version Changes\n\nThe sync workflow updates files such as:\n\n- `frontend/package.json`\n- `frontend/package-lock.json`\n- `companion/package.json`\n- `companion/package-lock.json`\n- `companion/src-tauri/Cargo.toml`\n- `companion/src-tauri/tauri.conf.json`\n- `companion/src-tauri/Cargo.lock`\n\nTreat those edits as release metadata, not as noise to separate later.\n\n## Validation\n\nRun the version sync before validating the affected release surfaces. At minimum, review the generated metadata and run the checks required by the changed subsystem.\n\nCommon examples:\n\n```bash\n./scripts/sync-version\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nUse [Release Checklist](../release-checklist/) for the complete product-release sequence.\n\n", "0.9": "+++\ntitle = \"Product Versioning\"\n+++\n\n## Product Version Source of Truth\n\nThe application version lives in:\n\n- `VERSION`\n\nWhen the product version changes:\n\n1. Update `VERSION`.\n1. Run `./scripts/sync-version`.\n\nThe sync step updates relevant frontend and Companion files.\n\n### Files That Move with Product Version Changes\n\nThe sync workflow updates files such as:\n\n- `frontend/package.json`\n- `frontend/package-lock.json`\n- `companion/package.json`\n- `companion/package-lock.json`\n- `companion/src-tauri/Cargo.toml`\n- `companion/src-tauri/tauri.conf.json`\n- `companion/src-tauri/Cargo.lock`\n\n## Publishable Build Policy\n\nSambee uses a `X.Y.Z` versionining scheme where the components have the following meanings:\n\n- `X` is the major version number.\n- `Y` is the minor version number:\n   - `0` for regular releases.\n   - `1` ... `n` for maintenance releases.\n- `Z` is the immutable publishable build sequence within `X.Y`:\n   - Each new `X.Y` branch starts at `Z == 0`.\n\nPublishable versions contain only non-negative numeric components. Prerelease suffixes and build metadata are not publishable because they do not support a single monotonic update path for Companion users.\n\n### Git Build Tags\n\nWhen a release workflow starts from `main`, it reserves the annotated Git tag `build-vX.Y.Z` for that exact source commit. Reusing an existing build selects that tag and checks out its immutable commit. Never move or recreate a `build-v...` tag.\n", "1.0": "+++\ntitle = \"Product Versioning\"\n+++\n\n## Product Version Source of Truth\n\nThe application version lives in:\n\n- `VERSION`\n\nWhen the product version changes:\n\n1. Update `VERSION`.\n1. Run `./scripts/sync-version`.\n\nThe sync step updates relevant frontend and Companion files.\n\n### Files That Move with Product Version Changes\n\nThe sync workflow updates files such as:\n\n- `frontend/package.json`\n- `frontend/package-lock.json`\n- `companion/package.json`\n- `companion/package-lock.json`\n- `companion/src-tauri/Cargo.toml`\n- `companion/src-tauri/tauri.conf.json`\n- `companion/src-tauri/Cargo.lock`\n\n## Publishable Build Policy\n\nSambee uses a `X.Y.Z` versionining scheme where the components have the following meanings:\n\n- `X` is the major version number.\n- `Y` is the minor version number:\n   - `0` for regular releases.\n   - `1` ... `n` for maintenance releases.\n- `Z` is the immutable publishable build sequence within `X.Y`:\n   - Each new `X.Y` branch starts at `Z == 0`.\n\nPublishable versions contain only non-negative numeric components. Prerelease suffixes and build metadata are not publishable because they do not support a single monotonic update path for Companion users.\n\n### Git Build Tags\n\nWhen a release workflow starts from `main`, it reserves the annotated Git tag `build-vX.Y.Z` for that exact source commit. Reusing an existing build selects that tag and checks out its immutable commit. Never move or recreate a `build-v...` tag.\n", "2.0": "+++\ntitle = \"Product Versioning\"\n+++\n\n## Product Version Source of Truth\n\nThe application version lives in:\n\n- `VERSION`\n\nWhen the product version changes:\n\n1. Update `VERSION`.\n1. Run `./scripts/sync-version`.\n\nThe sync step updates relevant frontend and Companion files.\n\n### Files That Move with Product Version Changes\n\nThe sync workflow updates files such as:\n\n- `frontend/package.json`\n- `frontend/package-lock.json`\n- `companion/package.json`\n- `companion/package-lock.json`\n- `companion/src-tauri/Cargo.toml`\n- `companion/src-tauri/tauri.conf.json`\n- `companion/src-tauri/Cargo.lock`\n\n## Publishable Build Policy\n\nSambee uses a `X.Y.Z` versionining scheme where the components have the following meanings:\n\n- `X` is the major version number.\n- `Y` is the minor version number:\n   - `0` for regular releases.\n   - `1` ... `n` for maintenance releases.\n- `Z` is the immutable publishable build sequence within `X.Y`:\n   - Each new `X.Y` branch starts at `Z == 0`.\n\nPublishable versions contain only non-negative numeric components. Prerelease suffixes and build metadata are not publishable because they do not support a single monotonic update path for Companion users.\n\n### Git Build Tags\n\nWhen a release workflow starts from `main`, it reserves the annotated Git tag `build-vX.Y.Z` for that exact source commit. Reusing an existing build selects that tag and checks out its immutable commit. Never move or recreate a `build-v...` tag.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Product Versioning\"\n+++\n\nThe Sambee product version has one source of truth. Use this page whenever you change the product version, whether for a prerelease or a stable release.\n\n## Product Version Source of Truth\n\nThe application version lives in:\n\n- `VERSION`\n\nWhen the product version changes:\n\n1. Update `VERSION`.\n1. Run `./scripts/sync-version`.\n1. Review all resulting metadata changes together.\n\nThe sync step updates version-bearing frontend and Companion files so they do not drift away from the root version.\n\n## Files That Move with Product Version Changes\n\nThe sync workflow updates files such as:\n\n- `frontend/package.json`\n- `frontend/package-lock.json`\n- `companion/package.json`\n- `companion/package-lock.json`\n- `companion/src-tauri/Cargo.toml`\n- `companion/src-tauri/tauri.conf.json`\n- `companion/src-tauri/Cargo.lock`\n\nTreat those edits as release metadata, not as noise to separate later.\n\n## Validation\n\nRun the version sync before validating the affected release surfaces. At minimum, review the generated metadata and run the checks required by the changed subsystem.\n\nCommon examples:\n\n```bash\n./scripts/sync-version\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nUse [Release Checklist](../release-checklist/) for the complete product-release sequence.\n\n", "0.8": "+++\ntitle = \"Product Versioning\"\n+++\n\nThe Sambee product version has one source of truth. Use this page whenever you change the product version, whether for a prerelease or a stable release.\n\n## Product Version Source of Truth\n\nThe application version lives in:\n\n- `VERSION`\n\nWhen the product version changes:\n\n1. Update `VERSION`.\n1. Run `./scripts/sync-version`.\n1. Review all resulting metadata changes together.\n\nThe sync step updates version-bearing frontend and Companion files so they do not drift away from the root version.\n\n## Files That Move with Product Version Changes\n\nThe sync workflow updates files such as:\n\n- `frontend/package.json`\n- `frontend/package-lock.json`\n- `companion/package.json`\n- `companion/package-lock.json`\n- `companion/src-tauri/Cargo.toml`\n- `companion/src-tauri/tauri.conf.json`\n- `companion/src-tauri/Cargo.lock`\n\nTreat those edits as release metadata, not as noise to separate later.\n\n## Validation\n\nRun the version sync before validating the affected release surfaces. At minimum, review the generated metadata and run the checks required by the changed subsystem.\n\nCommon examples:\n\n```bash\n./scripts/sync-version\ncd backend \u0026\u0026 pytest -v\ncd backend \u0026\u0026 mypy app\ncd frontend \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\ncd companion \u0026\u0026 npx tsc --noEmit \u0026\u0026 npm run lint\n```\n\nUse [Release Checklist](../release-checklist/) for the complete product-release sequence.\n\n", "0.9": "+++\ntitle = \"Product Versioning\"\n+++\n\n## Product Version Source of Truth\n\nThe application version lives in:\n\n- `VERSION`\n\nWhen the product version changes:\n\n1. Update `VERSION`.\n1. Run `./scripts/sync-version`.\n\nThe sync step updates relevant frontend and Companion files.\n\n### Files That Move with Product Version Changes\n\nThe sync workflow updates files such as:\n\n- `frontend/package.json`\n- `frontend/package-lock.json`\n- `companion/package.json`\n- `companion/package-lock.json`\n- `companion/src-tauri/Cargo.toml`\n- `companion/src-tauri/tauri.conf.json`\n- `companion/src-tauri/Cargo.lock`\n\n## Publishable Build Policy\n\nSambee uses a `X.Y.Z` versionining scheme where the components have the following meanings:\n\n- `X` is the major version number.\n- `Y` is the minor version number:\n   - `0` for regular releases.\n   - `1` ... `n` for maintenance releases.\n- `Z` is the immutable publishable build sequence within `X.Y`:\n   - Each new `X.Y` branch starts at `Z == 0`.\n\nPublishable versions contain only non-negative numeric components. Prerelease suffixes and build metadata are not publishable because they do not support a single monotonic update path for Companion users.\n\n### Git Build Tags\n\nWhen a release workflow starts from `main`, it reserves the annotated Git tag `build-vX.Y.Z` for that exact source commit. Reusing an existing build selects that tag and checks out its immutable commit. Never move or recreate a `build-v...` tag.\n", "1.0": "+++\ntitle = \"Product Versioning\"\n+++\n\n## Product Version Source of Truth\n\nThe application version lives in:\n\n- `VERSION`\n\nWhen the product version changes:\n\n1. Update `VERSION`.\n1. Run `./scripts/sync-version`.\n\nThe sync step updates relevant frontend and Companion files.\n\n### Files That Move with Product Version Changes\n\nThe sync workflow updates files such as:\n\n- `frontend/package.json`\n- `frontend/package-lock.json`\n- `companion/package.json`\n- `companion/package-lock.json`\n- `companion/src-tauri/Cargo.toml`\n- `companion/src-tauri/tauri.conf.json`\n- `companion/src-tauri/Cargo.lock`\n\n## Publishable Build Policy\n\nSambee uses a `X.Y.Z` versionining scheme where the components have the following meanings:\n\n- `X` is the major version number.\n- `Y` is the minor version number:\n   - `0` for regular releases.\n   - `1` ... `n` for maintenance releases.\n- `Z` is the immutable publishable build sequence within `X.Y`:\n   - Each new `X.Y` branch starts at `Z == 0`.\n\nPublishable versions contain only non-negative numeric components. Prerelease suffixes and build metadata are not publishable because they do not support a single monotonic update path for Companion users.\n\n### Git Build Tags\n\nWhen a release workflow starts from `main`, it reserves the annotated Git tag `build-vX.Y.Z` for that exact source commit. Reusing an existing build selects that tag and checks out its immutable commit. Never move or recreate a `build-v...` tag.\n", "2.0": "+++\ntitle = \"Product Versioning\"\n+++\n\n## Product Version Source of Truth\n\nThe application version lives in:\n\n- `VERSION`\n\nWhen the product version changes:\n\n1. Update `VERSION`.\n1. Run `./scripts/sync-version`.\n\nThe sync step updates relevant frontend and Companion files.\n\n### Files That Move with Product Version Changes\n\nThe sync workflow updates files such as:\n\n- `frontend/package.json`\n- `frontend/package-lock.json`\n- `companion/package.json`\n- `companion/package-lock.json`\n- `companion/src-tauri/Cargo.toml`\n- `companion/src-tauri/tauri.conf.json`\n- `companion/src-tauri/Cargo.lock`\n\n## Publishable Build Policy\n\nSambee uses a `X.Y.Z` versionining scheme where the components have the following meanings:\n\n- `X` is the major version number.\n- `Y` is the minor version number:\n   - `0` for regular releases.\n   - `1` ... `n` for maintenance releases.\n- `Z` is the immutable publishable build sequence within `X.Y`:\n   - Each new `X.Y` branch starts at `Z == 0`.\n\nPublishable versions contain only non-negative numeric components. Prerelease suffixes and build metadata are not publishable because they do not support a single monotonic update path for Companion users.\n\n### Git Build Tags\n\nWhen a release workflow starts from `main`, it reserves the annotated Git tag `build-vX.Y.Z` for that exact source commit. Reusing an existing build selects that tag and checks out its immutable commit. Never move or recreate a `build-v...` tag.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/release-and-versioning/release-checklist", "parent_id": "section:developer-guide/release-and-versioning", "depth": 2, "kind": "page", "label": "release-checklist", "title": "Release Checklist", "path": "developer-guide/release-and-versioning/release-checklist", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "missing"}, "0.9": {"state": "missing"}, "1.0": {"state": "missing"}, "2.0": {"state": "missing"}}, "content_versions": {"0.7": "+++\ntitle = \"Release Checklist\"\n+++\n\n## Preparation\n\n1. Update the product **version** ([details](../product-versioning/)). Ensure it's at the version you want to release.\n\n## Build and Test the Docker Image\n\nSee [Overview](../docker-release-overview/).\n\n1. Run the CI workflow [Release: Create Docker Image](../build-docker-image/) to **build** the Docker image and move the `test` tag to it.\n   - Don't override the product version in the CI workflow.\n1. **Test** the newly built image (pull it via the `test` tag).\n\n## Documentation\n\n1. Review the **homepage** content and update it where necessary.\n1. **Docs:**\n   - Verify [Supported File Formats](../../../user-guide/reference/supported-file-formats/) and update as necessary.\n   - Finalize the target release's [What's New](/release-info/news-and-changes/whats-new/) page.\n   - Mark the target version as current in `website/data/docs-versions.toml`.\n   - Run the VS Code task **Website: Refresh Docs Derived Artifacts**.\n   - Review the Docs Structure Report this creates in `/workspace/website-meta/docs-reports/docs-structure-report.html`.\n1. Git merge all changes.\n\n## Publish the Docker Image\n\nSee [Overview](../docker-release-overview/).\n\n1. Create a Git tag on the commit the tested image was built from.\n1. Publish a GitHub release from that tag.\n   - Release publication triggers [Release: Publish Docker Image](../promote-docker-image/), which tags the image built earlier as `beta` (prereleases) or `stable` and adds version tags for stable releases.\n\n## Publish the Companion\n\nSee [Overview](../companion-release-overview/)\n\n1. Run [Release: Build Companion Artifact](../build-companion-release/) to build Companion for the target platforms.\n   - Publish the Companion GitHub Release created by the workflow.\n1. Run [Release: Promote Companion Release](../promote-companion-release/) to promote the release to the `test`, `beta`, and/or `stable` update channels and to update the Sambee download-metadata feed.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Release Checklist\"\n+++\n\n## Preparation\n\n1. Update the product **version** ([details](../product-versioning/)). Ensure it's at the version you want to release.\n\n## Build and Test the Docker Image\n\nSee [Overview](../docker-release-overview/).\n\n1. Run the CI workflow [Release: Create Docker Image](../build-docker-image/) to **build** the Docker image and move the `test` tag to it.\n   - Don't override the product version in the CI workflow.\n1. **Test** the newly built image (pull it via the `test` tag).\n\n## Documentation\n\n1. Review the **homepage** content and update it where necessary.\n1. **Docs:**\n   - Verify [Supported File Formats](../../../user-guide/reference/supported-file-formats/) and update as necessary.\n   - Finalize the target release's [What's New](/release-info/news-and-changes/whats-new/) page.\n   - Mark the target version as current in `website/data/docs-versions.toml`.\n   - Run the VS Code task **Website: Refresh Docs Derived Artifacts**.\n   - Review the Docs Structure Report this creates in `/workspace/website-meta/docs-reports/docs-structure-report.html`.\n1. Git merge all changes.\n\n## Publish the Docker Image\n\nSee [Overview](../docker-release-overview/).\n\n1. Create a Git tag on the commit the tested image was built from.\n1. Publish a GitHub release from that tag.\n   - Release publication triggers [Release: Publish Docker Image](../promote-docker-image/), which tags the image built earlier as `beta` (prereleases) or `stable` and adds version tags for stable releases.\n\n## Publish the Companion\n\nSee [Overview](../companion-release-overview/)\n\n1. Run [Release: Build Companion Artifact](../build-companion-release/) to build Companion for the target platforms.\n   - Publish the Companion GitHub Release created by the workflow.\n1. Run [Release: Promote Companion Release](../promote-companion-release/) to promote the release to the `test`, `beta`, and/or `stable` update channels and to update the Sambee download-metadata feed.\n"}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/release-and-versioning/docker-release-overview", "parent_id": "section:developer-guide/release-and-versioning", "depth": 2, "kind": "page", "label": "docker-release-overview", "title": "Docker Release Overview", "path": "developer-guide/release-and-versioning/docker-release-overview", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "branched", "source_version": "0.7", "diff_added": 30, "diff_removed": 45}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "inherited", "source_version": "0.9"}}, "content_versions": {"0.7": "+++\ntitle = \"Docker Release Overview\"\n+++\n\nSambee ships one production container image built from the repository-root Dockerfile.\n\nThe release flow builds a candidate once, validates it, and later promotes that same digest to `stable` or `beta`.\n\nUse this page as the entry point for the Docker release path.\n\n## Summary\n\nIf you want to publish a new Docker image:\n\n1. Update `VERSION` and run `./scripts/sync-version`.\n   - Git merge the reviewed `version-sync` changes.\n1. Run `Release: Create Docker Image` for the commit you want to ship.\n   - This creates a new Docker image in GHCR and moves the `test` tag to it.\n1. Test and validate the new image.\n1. Create and push the real release Git tag on that same commit.\n   - Use:\n      - `git tag -a vX.Y.Z-beta.N \u003ccommit\u003e -m \"Sambee X.Y.Z beta N\"` for prereleases\n      - `git tag -a vX.Y.Z \u003ccommit\u003e -m \"Sambee X.Y.Z\"` for stable releases\n   - Push the tag with `git push origin \u003ctag\u003e`.\n1. Publish a GitHub Release from that existing tag.\n1. Release publication triggers `Release: Publish Docker Image`, which tags the image built earlier as `beta` (prereleases) or `stable` and adds version tags for stable releases.\n   - Stable publication also moves `beta` forward unless `beta` already points to a higher semver release.\n\nRead the detailed pages in this order:\n\n1. [Build Docker Image](../build-docker-image/)\n2. [Promote Docker Image](../promote-docker-image/)\n3. [Docker Backfill And Cleanup](../docker-backfill-and-cleanup/)\n\n## Workflow Map\n\n| Workflow | When to use it | Result |\n|---|---|---|\n| `CI: Validate Docker Image` | Any pull request, push to `main`, or manual smoke-test run. | Proves the production image still builds and starts, but does not publish anything. |\n| `Release: Create Docker Image` | You want a real candidate image for a specific commit or tag. | Builds, validates, publishes the metadata bundle, marks that digest as the current `test` image, and signs the digest. |\n| `Release: Publish Docker Image` | A Git tag was pushed and the matching GitHub Release was published from an approved candidate commit. | Verifies the existing preview-built digest, then attaches release tags, moves `stable` or `beta`, and catches `beta` up during stable publication unless `beta` already points to a higher semver release. |\n| `Maintenance: Backfill Docker Release Tags` | You need to restore or attach release tags for an already approved GitHub Release. | Reapplies release tags and channel aliases to an existing digest without publishing a new runtime image. |\n| `Maintenance: Clean Up Docker Package Versions` | Preview history and unreferenced GHCR artifacts need cleanup. | Deletes unprotected SHA-tagged preview GHCR versions, prunes stale signature artifacts, and removes unreferenced untagged package versions while preserving release-tagged artifacts and protected aliases including `test`. |\n\n## Channels And Tags\n\nSambee publishes three moving channel tags:\n\n- `stable` for the current non-prerelease line.\n- `beta` for the current prerelease line, or for the newest stable line when `beta` is not already ahead on a higher semver prerelease path.\n- `test` for the newest manually published preview candidate.\n\nEach preview publish also creates an immutable lookup tag in the `sha-\u003cfull-commit-sha\u003e` form.\n\nDuring publication, the workflow pushes native platform manifests by digest before it assembles the final multi-platform index.\nThose digest-only platform pushes are implementation details of the publish workflow and are not user-facing tags.\n\nRelease workflows resolve that immutable candidate tag first and then attach the appropriate release tags to the same digest.\n\n`latest` is intentionally not published.\n\n## Published Artifact\n\nThe published container artifact is a multi-platform image index in GitHub Container Registry for:\n\n- `linux/amd64`.\n- `linux/arm64`.\n\nThe repository name is `ghcr.io/\u003cowner\u003e/sambee`.\n\nEach platform variant comes from the same Dockerfile, is built and validated on a native runner, and is assembled into the same candidate index digest.\n\nCosign signatures for that image digest are stored in a dedicated GHCR signature repository rather than in the main image repository.\nCosign manages its own digest-derived signature artifact layout in that repository, so GHCR may show both tagged signature entries and referenced untagged bundle manifests for a retained image digest.\n\nSBOM and provenance data for that digest are extracted per platform on native runners, assembled into one metadata bundle, and published in the dedicated `ghcr.io/\u003cowner\u003e/sambee-signatures` repository under a digest-derived `.meta` tag.\n\nRelease and backfill workflows also upload the exact bundle files to the GitHub Release as convenience assets. The GHCR `.meta` artifact remains the canonical metadata bundle.\n\n## Security Model\n\nPreview publication is the only workflow that builds and pushes a new image.\n\nThat preview build also forces a fresh rebuild of the Dockerfile layer that installs Debian packages for the workflow run, so release candidates pick up the latest Debian package fixes available at build time instead of relying only on a previously cached OS-package layer.\n\nIt also:\n\n- publishes an SBOM and provenance metadata bundle under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n- signs the digest with Cosign using GitHub Actions OIDC.\n\nRelease promotion does not rebuild the image. It verifies candidate image metadata and the published metadata bundle first, then promotes the existing digest.\n\nUse [Build Docker Image](../build-docker-image/) for the build-and-publish flow.\n\nUse [Promote Docker Image](../promote-docker-image/) for the release path.\n\nUse [Docker Backfill And Cleanup](../docker-backfill-and-cleanup/) for recovery, backfill, and cleanup.\n\nUse [Container Image Security and Artifact Integrity](../../security/container-image-security-and-artifact-integrity/) for the deeper signing, SBOM, provenance, and vulnerability-scanning details.\n\nUse [Deploy Sambee with Docker](../../../admin-guide/installation-and-deployment/deploy-sambee-with-docker/) for operator-facing deployment guidance.\n", "0.8": "+++\ntitle = \"Docker Release Overview\"\n+++\n\nSambee ships one production container image built from the repository-root Dockerfile.\n\nThe release flow builds a candidate once, validates it, and later promotes that same digest to `stable` or `beta`.\n\nUse this page as the entry point for the Docker release path.\n\n## Summary\n\nIf you want to publish a new Docker image:\n\n1. Update `VERSION` and run `./scripts/sync-version`.\n   - Git merge the reviewed `version-sync` changes.\n1. Run `Release: Create Docker Image` for the commit you want to ship.\n   - This creates a new Docker image in GHCR and moves the `test` tag to it.\n1. Test and validate the new image.\n1. Create and push the real release Git tag on that same commit.\n   - Use:\n      - `git tag -a vX.Y.Z-beta.N \u003ccommit\u003e -m \"Sambee X.Y.Z beta N\"` for prereleases\n      - `git tag -a vX.Y.Z \u003ccommit\u003e -m \"Sambee X.Y.Z\"` for stable releases\n   - Push the tag with `git push origin \u003ctag\u003e`.\n1. Publish a GitHub Release from that existing tag.\n1. Release publication triggers `Release: Publish Docker Image`, which tags the image built earlier as `beta` (prereleases) or `stable` and adds version tags for stable releases.\n   - Stable publication also moves `beta` forward unless `beta` already points to a higher semver release.\n\nRead the detailed pages in this order:\n\n1. [Build Docker Image](../build-docker-image/)\n2. [Promote Docker Image](../promote-docker-image/)\n3. [Docker Backfill And Cleanup](../docker-backfill-and-cleanup/)\n\n## Workflow Map\n\n| Workflow | When to use it | Result |\n|---|---|---|\n| `CI: Validate Docker Image` | Any pull request, push to `main`, or manual smoke-test run. | Proves the production image still builds and starts, but does not publish anything. |\n| `Release: Create Docker Image` | You want a real candidate image for a specific commit or tag. | Builds, validates, publishes the metadata bundle, marks that digest as the current `test` image, and signs the digest. |\n| `Release: Publish Docker Image` | A Git tag was pushed and the matching GitHub Release was published from an approved candidate commit. | Verifies the existing preview-built digest, then attaches release tags, moves `stable` or `beta`, and catches `beta` up during stable publication unless `beta` already points to a higher semver release. |\n| `Maintenance: Backfill Docker Release Tags` | You need to restore or attach release tags for an already approved GitHub Release. | Reapplies release tags and channel aliases to an existing digest without publishing a new runtime image. |\n| `Maintenance: Clean Up Docker Package Versions` | Preview history and unreferenced GHCR artifacts need cleanup. | Deletes unprotected SHA-tagged preview GHCR versions, prunes stale signature artifacts, and removes unreferenced untagged package versions while preserving release-tagged artifacts and protected aliases including `test`. |\n\n## Channels And Tags\n\nSambee publishes three moving channel tags:\n\n- `stable` for the current non-prerelease line.\n- `beta` for the current prerelease line, or for the newest stable line when `beta` is not already ahead on a higher semver prerelease path.\n- `test` for the newest manually published preview candidate.\n\nEach preview publish also creates an immutable lookup tag in the `sha-\u003cfull-commit-sha\u003e` form.\n\nDuring publication, the workflow pushes native platform manifests by digest before it assembles the final multi-platform index.\nThose digest-only platform pushes are implementation details of the publish workflow and are not user-facing tags.\n\nRelease workflows resolve that immutable candidate tag first and then attach the appropriate release tags to the same digest.\n\n`latest` is intentionally not published.\n\n## Published Artifact\n\nThe published container artifact is a multi-platform image index in GitHub Container Registry for:\n\n- `linux/amd64`.\n- `linux/arm64`.\n\nThe repository name is `ghcr.io/\u003cowner\u003e/sambee`.\n\nEach platform variant comes from the same Dockerfile, is built and validated on a native runner, and is assembled into the same candidate index digest.\n\nCosign signatures for that image digest are stored in a dedicated GHCR signature repository rather than in the main image repository.\nCosign manages its own digest-derived signature artifact layout in that repository, so GHCR may show both tagged signature entries and referenced untagged bundle manifests for a retained image digest.\n\nSBOM and provenance data for that digest are extracted per platform on native runners, assembled into one metadata bundle, and published in the dedicated `ghcr.io/\u003cowner\u003e/sambee-signatures` repository under a digest-derived `.meta` tag.\n\nRelease and backfill workflows also upload the exact bundle files to the GitHub Release as convenience assets. The GHCR `.meta` artifact remains the canonical metadata bundle.\n\n## Security Model\n\nPreview publication is the only workflow that builds and pushes a new image.\n\nThat preview build also forces a fresh rebuild of the Dockerfile layer that installs Debian packages for the workflow run, so release candidates pick up the latest Debian package fixes available at build time instead of relying only on a previously cached OS-package layer.\n\nIt also:\n\n- publishes an SBOM and provenance metadata bundle under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n- signs the digest with Cosign using GitHub Actions OIDC.\n\nRelease promotion does not rebuild the image. It verifies candidate image metadata and the published metadata bundle first, then promotes the existing digest.\n\nUse [Build Docker Image](../build-docker-image/) for the build-and-publish flow.\n\nUse [Promote Docker Image](../promote-docker-image/) for the release path.\n\nUse [Docker Backfill And Cleanup](../docker-backfill-and-cleanup/) for recovery, backfill, and cleanup.\n\nUse [Container Image Security and Artifact Integrity](../../security/container-image-security-and-artifact-integrity/) for the deeper signing, SBOM, provenance, and vulnerability-scanning details.\n\nUse [Deploy Sambee with Docker](../../../admin-guide/installation-and-deployment/deploy-sambee-with-docker/) for operator-facing deployment guidance.\n", "0.9": "+++\ntitle = \"Docker Release Overview\"\n+++\n\nSambee ships one production container image built from the repository-root Dockerfile.\n\nThe release flow builds a candidate image once, validates it, and later promotes that same image to `stable` or `beta`.\n\n## Summary\n\nIf you want to publish a new Docker image:\n\n1. Increment `VERSION` to the next `X.Y.Z` value and run `./scripts/sync-version`.\n1. Run `Release: Create Docker Image`.\n   - If the workflow's source version field is left blank, the image is built from the current commit in `main` and the Git tag `build-vX.Y.Z` is created to reserve the version for the commit the image is built from.\n   - If a source version field is specified, the workflow verifies and repairs the image associated with the version via the Git tag used for reservation.\n1. The workflow:\n   - assures concurrency via unique `stage-\u003crun\u003e-\u003cattempt\u003e-\u003cplatform\u003e` Docker tags in the internal staging repository\n   - builds the image\n   - validates and signs the image\n   - creates immutable `build-vX.Y.Z` Git commit and Docker image tags\n   - moves the `test` Docker tag to the newly built image\n1. Test the new image via the `test` Docker image tag.\n1. To move the `beta` Docker tag to the newly built image, run `Release: Publish Docker Image` manually.\n1. To publish the newly built image as `stable`, run `Release: Create Public Sambee Release` publish the resulting GitHub release.\n   - Release publication verifies the existing signed candidate and moves only the authorized mutable aliases. It never rebuilds an image.\n\nRead the detailed pages in this order:\n\n1. [Build Docker Image](../build-docker-image/)\n2. [Promote Docker Image](../promote-docker-image/)\n3. [Docker Backfill And Cleanup](../docker-backfill-and-cleanup/)\n\n## Workflow Map\n\n| Workflow | When to use it | Result |\n|---|---|---|\n| `CI: Validate Docker Image` | Any pull request, push to `main`, or manual smoke-test run. | Proves the production image still builds and starts, but does not publish anything. |\n| `Release: Create Docker Image` | To create an image for the current `main` commit or to verify/repair an image for an commit identified by its version tag. | Builds, validates, publishes the metadata bundle, marks that image as the current `test` image, and signs it. |\n| `Release: Publish Docker Image` | Run manually: to promote an image to `beta`.\u003cbr /\u003eIs run automatically when publishing a GitHub Release to promote an image to `stable`. | Verifies the existing preview-built image. Manual beta promotion moves only `beta`; public-release promotion moves `stable`, the minor-series tag, and catches `beta` up unless it already points to a higher version. |\n| `Maintenance: Backfill Docker Release Tags` | You need to restore or attach release tags for an already approved GitHub Release. | Reapplies release tags and channel aliases to an existing image without publishing a new runtime image. |\n| `Maintenance: Clean Up Docker Package Versions` | Clean up Docker image tag history and remove unreferenced GHCR artifacts. | Deletes unprotected SHA-tagged preview GHCR versions, prunes stale signature artifacts, and removes unreferenced untagged package versions while preserving release-tagged artifacts and protected aliases including `test`. |\n\n## Channels And Tags\n\nSambee publishes three moving channel tags:\n\n- `stable` for the approved production image.\n- `beta` for the approved preview image.\n- `test` for the most recently verified candidate image.\n\nEach candidate creates immutable tags:\n- Git: `build-vX.Y.Z`\n- Docker: `build-vX.Y.Z`, `X.Y.Z`, and `sha-\u003cfull-commit-sha\u003e`\n\nDuring publication, the workflow pushes native platform manifests by digest and assembles a multi-platform index in `ghcr.io/\u003cowner\u003e/sambee-staging`. It verifies metadata and signatures there, then copies the verified index by digest to the final immutable marker in `ghcr.io/\u003cowner\u003e/sambee`. Staging references are implementation details and are not user-facing tags.\n\nRelease workflows identify the target image by resolving the immutable Docker tag and attaching the appropriate release tags to the same image.\n\n`latest` is intentionally not published.\n\n## Published Artifact\n\nThe published container artifact is a multi-platform image index in GitHub Container Registry (GHCR) for:\n\n- `linux/amd64`.\n- `linux/arm64`.\n\nThe repository name is `ghcr.io/\u003cowner\u003e/sambee`.\n\nEach platform variant comes from the same Dockerfile, is built and validated on a native runner, and is assembled into the same candidate index digest.\n\nCosign signatures for that image digest are stored in a dedicated GHCR signature repository rather than in the main image repository. Cosign manages its own digest-derived signature artifact layout in that repository, so GHCR may show both tagged signature entries and referenced untagged bundle manifests for a retained image digest.\n\nSBOM and provenance data for that digest are extracted per platform on native runners, assembled into one metadata bundle, and published in the dedicated `ghcr.io/\u003cowner\u003e/sambee-signatures` repository under a digest-derived `.meta` tag.\n\nRelease and backfill workflows also upload the exact bundle files to the GitHub Release as convenience assets. The GHCR `.meta` artifact remains the canonical metadata bundle.\n\n## Security Model\n\nA new Docker build forces a fresh rebuild of the Dockerfile layer that installs Debian packages for the workflow run, so release candidates pick up the latest Debian package fixes available at build time instead of relying only on a previously cached OS-package layer.\n\nIt also:\n\n- publishes an SBOM and provenance metadata bundle under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n- signs the digest with Cosign using GitHub Actions OIDC.\n", "1.0": "+++\ntitle = \"Docker Release Overview\"\n+++\n\nSambee ships one production container image built from the repository-root Dockerfile.\n\nThe release flow builds a candidate image once, validates it, and later promotes that same image to `stable` or `beta`.\n\n## Summary\n\nIf you want to publish a new Docker image:\n\n1. Increment `VERSION` to the next `X.Y.Z` value and run `./scripts/sync-version`.\n1. Run `Release: Create Docker Image`.\n   - If the workflow's source version field is left blank, the image is built from the current commit in `main` and the Git tag `build-vX.Y.Z` is created to reserve the version for the commit the image is built from.\n   - If a source version field is specified, the workflow verifies and repairs the image associated with the version via the Git tag used for reservation.\n1. The workflow:\n   - assures concurrency via unique `stage-\u003crun\u003e-\u003cattempt\u003e-\u003cplatform\u003e` Docker tags in the internal staging repository\n   - builds the image\n   - validates and signs the image\n   - creates immutable `build-vX.Y.Z` Git commit and Docker image tags\n   - moves the `test` Docker tag to the newly built image\n1. Test the new image via the `test` Docker image tag.\n1. To move the `beta` Docker tag to the newly built image, run `Release: Publish Docker Image` manually.\n1. To publish the newly built image as `stable`, run `Release: Create Public Sambee Release` publish the resulting GitHub release.\n   - Release publication verifies the existing signed candidate and moves only the authorized mutable aliases. It never rebuilds an image.\n\nRead the detailed pages in this order:\n\n1. [Build Docker Image](../build-docker-image/)\n2. [Promote Docker Image](../promote-docker-image/)\n3. [Docker Backfill And Cleanup](../docker-backfill-and-cleanup/)\n\n## Workflow Map\n\n| Workflow | When to use it | Result |\n|---|---|---|\n| `CI: Validate Docker Image` | Any pull request, push to `main`, or manual smoke-test run. | Proves the production image still builds and starts, but does not publish anything. |\n| `Release: Create Docker Image` | To create an image for the current `main` commit or to verify/repair an image for an commit identified by its version tag. | Builds, validates, publishes the metadata bundle, marks that image as the current `test` image, and signs it. |\n| `Release: Publish Docker Image` | Run manually: to promote an image to `beta`.\u003cbr /\u003eIs run automatically when publishing a GitHub Release to promote an image to `stable`. | Verifies the existing preview-built image. Manual beta promotion moves only `beta`; public-release promotion moves `stable`, the minor-series tag, and catches `beta` up unless it already points to a higher version. |\n| `Maintenance: Backfill Docker Release Tags` | You need to restore or attach release tags for an already approved GitHub Release. | Reapplies release tags and channel aliases to an existing image without publishing a new runtime image. |\n| `Maintenance: Clean Up Docker Package Versions` | Clean up Docker image tag history and remove unreferenced GHCR artifacts. | Deletes unprotected SHA-tagged preview GHCR versions, prunes stale signature artifacts, and removes unreferenced untagged package versions while preserving release-tagged artifacts and protected aliases including `test`. |\n\n## Channels And Tags\n\nSambee publishes three moving channel tags:\n\n- `stable` for the approved production image.\n- `beta` for the approved preview image.\n- `test` for the most recently verified candidate image.\n\nEach candidate creates immutable tags:\n- Git: `build-vX.Y.Z`\n- Docker: `build-vX.Y.Z`, `X.Y.Z`, and `sha-\u003cfull-commit-sha\u003e`\n\nDuring publication, the workflow pushes native platform manifests by digest and assembles a multi-platform index in `ghcr.io/\u003cowner\u003e/sambee-staging`. It verifies metadata and signatures there, then copies the verified index by digest to the final immutable marker in `ghcr.io/\u003cowner\u003e/sambee`. Staging references are implementation details and are not user-facing tags.\n\nRelease workflows identify the target image by resolving the immutable Docker tag and attaching the appropriate release tags to the same image.\n\n`latest` is intentionally not published.\n\n## Published Artifact\n\nThe published container artifact is a multi-platform image index in GitHub Container Registry (GHCR) for:\n\n- `linux/amd64`.\n- `linux/arm64`.\n\nThe repository name is `ghcr.io/\u003cowner\u003e/sambee`.\n\nEach platform variant comes from the same Dockerfile, is built and validated on a native runner, and is assembled into the same candidate index digest.\n\nCosign signatures for that image digest are stored in a dedicated GHCR signature repository rather than in the main image repository. Cosign manages its own digest-derived signature artifact layout in that repository, so GHCR may show both tagged signature entries and referenced untagged bundle manifests for a retained image digest.\n\nSBOM and provenance data for that digest are extracted per platform on native runners, assembled into one metadata bundle, and published in the dedicated `ghcr.io/\u003cowner\u003e/sambee-signatures` repository under a digest-derived `.meta` tag.\n\nRelease and backfill workflows also upload the exact bundle files to the GitHub Release as convenience assets. The GHCR `.meta` artifact remains the canonical metadata bundle.\n\n## Security Model\n\nA new Docker build forces a fresh rebuild of the Dockerfile layer that installs Debian packages for the workflow run, so release candidates pick up the latest Debian package fixes available at build time instead of relying only on a previously cached OS-package layer.\n\nIt also:\n\n- publishes an SBOM and provenance metadata bundle under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n- signs the digest with Cosign using GitHub Actions OIDC.\n", "2.0": "+++\ntitle = \"Docker Release Overview\"\n+++\n\nSambee ships one production container image built from the repository-root Dockerfile.\n\nThe release flow builds a candidate image once, validates it, and later promotes that same image to `stable` or `beta`.\n\n## Summary\n\nIf you want to publish a new Docker image:\n\n1. Increment `VERSION` to the next `X.Y.Z` value and run `./scripts/sync-version`.\n1. Run `Release: Create Docker Image`.\n   - If the workflow's source version field is left blank, the image is built from the current commit in `main` and the Git tag `build-vX.Y.Z` is created to reserve the version for the commit the image is built from.\n   - If a source version field is specified, the workflow verifies and repairs the image associated with the version via the Git tag used for reservation.\n1. The workflow:\n   - assures concurrency via unique `stage-\u003crun\u003e-\u003cattempt\u003e-\u003cplatform\u003e` Docker tags in the internal staging repository\n   - builds the image\n   - validates and signs the image\n   - creates immutable `build-vX.Y.Z` Git commit and Docker image tags\n   - moves the `test` Docker tag to the newly built image\n1. Test the new image via the `test` Docker image tag.\n1. To move the `beta` Docker tag to the newly built image, run `Release: Publish Docker Image` manually.\n1. To publish the newly built image as `stable`, run `Release: Create Public Sambee Release` publish the resulting GitHub release.\n   - Release publication verifies the existing signed candidate and moves only the authorized mutable aliases. It never rebuilds an image.\n\nRead the detailed pages in this order:\n\n1. [Build Docker Image](../build-docker-image/)\n2. [Promote Docker Image](../promote-docker-image/)\n3. [Docker Backfill And Cleanup](../docker-backfill-and-cleanup/)\n\n## Workflow Map\n\n| Workflow | When to use it | Result |\n|---|---|---|\n| `CI: Validate Docker Image` | Any pull request, push to `main`, or manual smoke-test run. | Proves the production image still builds and starts, but does not publish anything. |\n| `Release: Create Docker Image` | To create an image for the current `main` commit or to verify/repair an image for an commit identified by its version tag. | Builds, validates, publishes the metadata bundle, marks that image as the current `test` image, and signs it. |\n| `Release: Publish Docker Image` | Run manually: to promote an image to `beta`.\u003cbr /\u003eIs run automatically when publishing a GitHub Release to promote an image to `stable`. | Verifies the existing preview-built image. Manual beta promotion moves only `beta`; public-release promotion moves `stable`, the minor-series tag, and catches `beta` up unless it already points to a higher version. |\n| `Maintenance: Backfill Docker Release Tags` | You need to restore or attach release tags for an already approved GitHub Release. | Reapplies release tags and channel aliases to an existing image without publishing a new runtime image. |\n| `Maintenance: Clean Up Docker Package Versions` | Clean up Docker image tag history and remove unreferenced GHCR artifacts. | Deletes unprotected SHA-tagged preview GHCR versions, prunes stale signature artifacts, and removes unreferenced untagged package versions while preserving release-tagged artifacts and protected aliases including `test`. |\n\n## Channels And Tags\n\nSambee publishes three moving channel tags:\n\n- `stable` for the approved production image.\n- `beta` for the approved preview image.\n- `test` for the most recently verified candidate image.\n\nEach candidate creates immutable tags:\n- Git: `build-vX.Y.Z`\n- Docker: `build-vX.Y.Z`, `X.Y.Z`, and `sha-\u003cfull-commit-sha\u003e`\n\nDuring publication, the workflow pushes native platform manifests by digest and assembles a multi-platform index in `ghcr.io/\u003cowner\u003e/sambee-staging`. It verifies metadata and signatures there, then copies the verified index by digest to the final immutable marker in `ghcr.io/\u003cowner\u003e/sambee`. Staging references are implementation details and are not user-facing tags.\n\nRelease workflows identify the target image by resolving the immutable Docker tag and attaching the appropriate release tags to the same image.\n\n`latest` is intentionally not published.\n\n## Published Artifact\n\nThe published container artifact is a multi-platform image index in GitHub Container Registry (GHCR) for:\n\n- `linux/amd64`.\n- `linux/arm64`.\n\nThe repository name is `ghcr.io/\u003cowner\u003e/sambee`.\n\nEach platform variant comes from the same Dockerfile, is built and validated on a native runner, and is assembled into the same candidate index digest.\n\nCosign signatures for that image digest are stored in a dedicated GHCR signature repository rather than in the main image repository. Cosign manages its own digest-derived signature artifact layout in that repository, so GHCR may show both tagged signature entries and referenced untagged bundle manifests for a retained image digest.\n\nSBOM and provenance data for that digest are extracted per platform on native runners, assembled into one metadata bundle, and published in the dedicated `ghcr.io/\u003cowner\u003e/sambee-signatures` repository under a digest-derived `.meta` tag.\n\nRelease and backfill workflows also upload the exact bundle files to the GitHub Release as convenience assets. The GHCR `.meta` artifact remains the canonical metadata bundle.\n\n## Security Model\n\nA new Docker build forces a fresh rebuild of the Dockerfile layer that installs Debian packages for the workflow run, so release candidates pick up the latest Debian package fixes available at build time instead of relying only on a previously cached OS-package layer.\n\nIt also:\n\n- publishes an SBOM and provenance metadata bundle under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n- signs the digest with Cosign using GitHub Actions OIDC.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Docker Release Overview\"\n+++\n\nSambee ships one production container image built from the repository-root Dockerfile.\n\nThe release flow builds a candidate once, validates it, and later promotes that same digest to `stable` or `beta`.\n\nUse this page as the entry point for the Docker release path.\n\n## Summary\n\nIf you want to publish a new Docker image:\n\n1. Update `VERSION` and run `./scripts/sync-version`.\n   - Git merge the reviewed `version-sync` changes.\n1. Run `Release: Create Docker Image` for the commit you want to ship.\n   - This creates a new Docker image in GHCR and moves the `test` tag to it.\n1. Test and validate the new image.\n1. Create and push the real release Git tag on that same commit.\n   - Use:\n      - `git tag -a vX.Y.Z-beta.N \u003ccommit\u003e -m \"Sambee X.Y.Z beta N\"` for prereleases\n      - `git tag -a vX.Y.Z \u003ccommit\u003e -m \"Sambee X.Y.Z\"` for stable releases\n   - Push the tag with `git push origin \u003ctag\u003e`.\n1. Publish a GitHub Release from that existing tag.\n1. Release publication triggers `Release: Publish Docker Image`, which tags the image built earlier as `beta` (prereleases) or `stable` and adds version tags for stable releases.\n   - Stable publication also moves `beta` forward unless `beta` already points to a higher semver release.\n\nRead the detailed pages in this order:\n\n1. [Build Docker Image](../build-docker-image/)\n2. [Promote Docker Image](../promote-docker-image/)\n3. [Docker Backfill And Cleanup](../docker-backfill-and-cleanup/)\n\n## Workflow Map\n\n| Workflow | When to use it | Result |\n|---|---|---|\n| `CI: Validate Docker Image` | Any pull request, push to `main`, or manual smoke-test run. | Proves the production image still builds and starts, but does not publish anything. |\n| `Release: Create Docker Image` | You want a real candidate image for a specific commit or tag. | Builds, validates, publishes the metadata bundle, marks that digest as the current `test` image, and signs the digest. |\n| `Release: Publish Docker Image` | A Git tag was pushed and the matching GitHub Release was published from an approved candidate commit. | Verifies the existing preview-built digest, then attaches release tags, moves `stable` or `beta`, and catches `beta` up during stable publication unless `beta` already points to a higher semver release. |\n| `Maintenance: Backfill Docker Release Tags` | You need to restore or attach release tags for an already approved GitHub Release. | Reapplies release tags and channel aliases to an existing digest without publishing a new runtime image. |\n| `Maintenance: Clean Up Docker Package Versions` | Preview history and unreferenced GHCR artifacts need cleanup. | Deletes unprotected SHA-tagged preview GHCR versions, prunes stale signature artifacts, and removes unreferenced untagged package versions while preserving release-tagged artifacts and protected aliases including `test`. |\n\n## Channels And Tags\n\nSambee publishes three moving channel tags:\n\n- `stable` for the current non-prerelease line.\n- `beta` for the current prerelease line, or for the newest stable line when `beta` is not already ahead on a higher semver prerelease path.\n- `test` for the newest manually published preview candidate.\n\nEach preview publish also creates an immutable lookup tag in the `sha-\u003cfull-commit-sha\u003e` form.\n\nDuring publication, the workflow pushes native platform manifests by digest before it assembles the final multi-platform index.\nThose digest-only platform pushes are implementation details of the publish workflow and are not user-facing tags.\n\nRelease workflows resolve that immutable candidate tag first and then attach the appropriate release tags to the same digest.\n\n`latest` is intentionally not published.\n\n## Published Artifact\n\nThe published container artifact is a multi-platform image index in GitHub Container Registry for:\n\n- `linux/amd64`.\n- `linux/arm64`.\n\nThe repository name is `ghcr.io/\u003cowner\u003e/sambee`.\n\nEach platform variant comes from the same Dockerfile, is built and validated on a native runner, and is assembled into the same candidate index digest.\n\nCosign signatures for that image digest are stored in a dedicated GHCR signature repository rather than in the main image repository.\nCosign manages its own digest-derived signature artifact layout in that repository, so GHCR may show both tagged signature entries and referenced untagged bundle manifests for a retained image digest.\n\nSBOM and provenance data for that digest are extracted per platform on native runners, assembled into one metadata bundle, and published in the dedicated `ghcr.io/\u003cowner\u003e/sambee-signatures` repository under a digest-derived `.meta` tag.\n\nRelease and backfill workflows also upload the exact bundle files to the GitHub Release as convenience assets. The GHCR `.meta` artifact remains the canonical metadata bundle.\n\n## Security Model\n\nPreview publication is the only workflow that builds and pushes a new image.\n\nThat preview build also forces a fresh rebuild of the Dockerfile layer that installs Debian packages for the workflow run, so release candidates pick up the latest Debian package fixes available at build time instead of relying only on a previously cached OS-package layer.\n\nIt also:\n\n- publishes an SBOM and provenance metadata bundle under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n- signs the digest with Cosign using GitHub Actions OIDC.\n\nRelease promotion does not rebuild the image. It verifies candidate image metadata and the published metadata bundle first, then promotes the existing digest.\n\nUse [Build Docker Image](../build-docker-image/) for the build-and-publish flow.\n\nUse [Promote Docker Image](../promote-docker-image/) for the release path.\n\nUse [Docker Backfill And Cleanup](../docker-backfill-and-cleanup/) for recovery, backfill, and cleanup.\n\nUse [Container Image Security and Artifact Integrity](../../security/container-image-security-and-artifact-integrity/) for the deeper signing, SBOM, provenance, and vulnerability-scanning details.\n\nUse [Deploy Sambee with Docker](../../../admin-guide/installation-and-deployment/deploy-sambee-with-docker/) for operator-facing deployment guidance.\n", "0.8": "+++\ntitle = \"Docker Release Overview\"\n+++\n\nSambee ships one production container image built from the repository-root Dockerfile.\n\nThe release flow builds a candidate once, validates it, and later promotes that same digest to `stable` or `beta`.\n\nUse this page as the entry point for the Docker release path.\n\n## Summary\n\nIf you want to publish a new Docker image:\n\n1. Update `VERSION` and run `./scripts/sync-version`.\n   - Git merge the reviewed `version-sync` changes.\n1. Run `Release: Create Docker Image` for the commit you want to ship.\n   - This creates a new Docker image in GHCR and moves the `test` tag to it.\n1. Test and validate the new image.\n1. Create and push the real release Git tag on that same commit.\n   - Use:\n      - `git tag -a vX.Y.Z-beta.N \u003ccommit\u003e -m \"Sambee X.Y.Z beta N\"` for prereleases\n      - `git tag -a vX.Y.Z \u003ccommit\u003e -m \"Sambee X.Y.Z\"` for stable releases\n   - Push the tag with `git push origin \u003ctag\u003e`.\n1. Publish a GitHub Release from that existing tag.\n1. Release publication triggers `Release: Publish Docker Image`, which tags the image built earlier as `beta` (prereleases) or `stable` and adds version tags for stable releases.\n   - Stable publication also moves `beta` forward unless `beta` already points to a higher semver release.\n\nRead the detailed pages in this order:\n\n1. [Build Docker Image](../build-docker-image/)\n2. [Promote Docker Image](../promote-docker-image/)\n3. [Docker Backfill And Cleanup](../docker-backfill-and-cleanup/)\n\n## Workflow Map\n\n| Workflow | When to use it | Result |\n|---|---|---|\n| `CI: Validate Docker Image` | Any pull request, push to `main`, or manual smoke-test run. | Proves the production image still builds and starts, but does not publish anything. |\n| `Release: Create Docker Image` | You want a real candidate image for a specific commit or tag. | Builds, validates, publishes the metadata bundle, marks that digest as the current `test` image, and signs the digest. |\n| `Release: Publish Docker Image` | A Git tag was pushed and the matching GitHub Release was published from an approved candidate commit. | Verifies the existing preview-built digest, then attaches release tags, moves `stable` or `beta`, and catches `beta` up during stable publication unless `beta` already points to a higher semver release. |\n| `Maintenance: Backfill Docker Release Tags` | You need to restore or attach release tags for an already approved GitHub Release. | Reapplies release tags and channel aliases to an existing digest without publishing a new runtime image. |\n| `Maintenance: Clean Up Docker Package Versions` | Preview history and unreferenced GHCR artifacts need cleanup. | Deletes unprotected SHA-tagged preview GHCR versions, prunes stale signature artifacts, and removes unreferenced untagged package versions while preserving release-tagged artifacts and protected aliases including `test`. |\n\n## Channels And Tags\n\nSambee publishes three moving channel tags:\n\n- `stable` for the current non-prerelease line.\n- `beta` for the current prerelease line, or for the newest stable line when `beta` is not already ahead on a higher semver prerelease path.\n- `test` for the newest manually published preview candidate.\n\nEach preview publish also creates an immutable lookup tag in the `sha-\u003cfull-commit-sha\u003e` form.\n\nDuring publication, the workflow pushes native platform manifests by digest before it assembles the final multi-platform index.\nThose digest-only platform pushes are implementation details of the publish workflow and are not user-facing tags.\n\nRelease workflows resolve that immutable candidate tag first and then attach the appropriate release tags to the same digest.\n\n`latest` is intentionally not published.\n\n## Published Artifact\n\nThe published container artifact is a multi-platform image index in GitHub Container Registry for:\n\n- `linux/amd64`.\n- `linux/arm64`.\n\nThe repository name is `ghcr.io/\u003cowner\u003e/sambee`.\n\nEach platform variant comes from the same Dockerfile, is built and validated on a native runner, and is assembled into the same candidate index digest.\n\nCosign signatures for that image digest are stored in a dedicated GHCR signature repository rather than in the main image repository.\nCosign manages its own digest-derived signature artifact layout in that repository, so GHCR may show both tagged signature entries and referenced untagged bundle manifests for a retained image digest.\n\nSBOM and provenance data for that digest are extracted per platform on native runners, assembled into one metadata bundle, and published in the dedicated `ghcr.io/\u003cowner\u003e/sambee-signatures` repository under a digest-derived `.meta` tag.\n\nRelease and backfill workflows also upload the exact bundle files to the GitHub Release as convenience assets. The GHCR `.meta` artifact remains the canonical metadata bundle.\n\n## Security Model\n\nPreview publication is the only workflow that builds and pushes a new image.\n\nThat preview build also forces a fresh rebuild of the Dockerfile layer that installs Debian packages for the workflow run, so release candidates pick up the latest Debian package fixes available at build time instead of relying only on a previously cached OS-package layer.\n\nIt also:\n\n- publishes an SBOM and provenance metadata bundle under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n- signs the digest with Cosign using GitHub Actions OIDC.\n\nRelease promotion does not rebuild the image. It verifies candidate image metadata and the published metadata bundle first, then promotes the existing digest.\n\nUse [Build Docker Image](../build-docker-image/) for the build-and-publish flow.\n\nUse [Promote Docker Image](../promote-docker-image/) for the release path.\n\nUse [Docker Backfill And Cleanup](../docker-backfill-and-cleanup/) for recovery, backfill, and cleanup.\n\nUse [Container Image Security and Artifact Integrity](../../security/container-image-security-and-artifact-integrity/) for the deeper signing, SBOM, provenance, and vulnerability-scanning details.\n\nUse [Deploy Sambee with Docker](../../../admin-guide/installation-and-deployment/deploy-sambee-with-docker/) for operator-facing deployment guidance.\n", "0.9": "+++\ntitle = \"Docker Release Overview\"\n+++\n\nSambee ships one production container image built from the repository-root Dockerfile.\n\nThe release flow builds a candidate image once, validates it, and later promotes that same image to `stable` or `beta`.\n\n## Summary\n\nIf you want to publish a new Docker image:\n\n1. Increment `VERSION` to the next `X.Y.Z` value and run `./scripts/sync-version`.\n1. Run `Release: Create Docker Image`.\n   - If the workflow's source version field is left blank, the image is built from the current commit in `main` and the Git tag `build-vX.Y.Z` is created to reserve the version for the commit the image is built from.\n   - If a source version field is specified, the workflow verifies and repairs the image associated with the version via the Git tag used for reservation.\n1. The workflow:\n   - assures concurrency via unique `stage-\u003crun\u003e-\u003cattempt\u003e-\u003cplatform\u003e` Docker tags in the internal staging repository\n   - builds the image\n   - validates and signs the image\n   - creates immutable `build-vX.Y.Z` Git commit and Docker image tags\n   - moves the `test` Docker tag to the newly built image\n1. Test the new image via the `test` Docker image tag.\n1. To move the `beta` Docker tag to the newly built image, run `Release: Publish Docker Image` manually.\n1. To publish the newly built image as `stable`, run `Release: Create Public Sambee Release` publish the resulting GitHub release.\n   - Release publication verifies the existing signed candidate and moves only the authorized mutable aliases. It never rebuilds an image.\n\nRead the detailed pages in this order:\n\n1. [Build Docker Image](../build-docker-image/)\n2. [Promote Docker Image](../promote-docker-image/)\n3. [Docker Backfill And Cleanup](../docker-backfill-and-cleanup/)\n\n## Workflow Map\n\n| Workflow | When to use it | Result |\n|---|---|---|\n| `CI: Validate Docker Image` | Any pull request, push to `main`, or manual smoke-test run. | Proves the production image still builds and starts, but does not publish anything. |\n| `Release: Create Docker Image` | To create an image for the current `main` commit or to verify/repair an image for an commit identified by its version tag. | Builds, validates, publishes the metadata bundle, marks that image as the current `test` image, and signs it. |\n| `Release: Publish Docker Image` | Run manually: to promote an image to `beta`.\u003cbr /\u003eIs run automatically when publishing a GitHub Release to promote an image to `stable`. | Verifies the existing preview-built image. Manual beta promotion moves only `beta`; public-release promotion moves `stable`, the minor-series tag, and catches `beta` up unless it already points to a higher version. |\n| `Maintenance: Backfill Docker Release Tags` | You need to restore or attach release tags for an already approved GitHub Release. | Reapplies release tags and channel aliases to an existing image without publishing a new runtime image. |\n| `Maintenance: Clean Up Docker Package Versions` | Clean up Docker image tag history and remove unreferenced GHCR artifacts. | Deletes unprotected SHA-tagged preview GHCR versions, prunes stale signature artifacts, and removes unreferenced untagged package versions while preserving release-tagged artifacts and protected aliases including `test`. |\n\n## Channels And Tags\n\nSambee publishes three moving channel tags:\n\n- `stable` for the approved production image.\n- `beta` for the approved preview image.\n- `test` for the most recently verified candidate image.\n\nEach candidate creates immutable tags:\n- Git: `build-vX.Y.Z`\n- Docker: `build-vX.Y.Z`, `X.Y.Z`, and `sha-\u003cfull-commit-sha\u003e`\n\nDuring publication, the workflow pushes native platform manifests by digest and assembles a multi-platform index in `ghcr.io/\u003cowner\u003e/sambee-staging`. It verifies metadata and signatures there, then copies the verified index by digest to the final immutable marker in `ghcr.io/\u003cowner\u003e/sambee`. Staging references are implementation details and are not user-facing tags.\n\nRelease workflows identify the target image by resolving the immutable Docker tag and attaching the appropriate release tags to the same image.\n\n`latest` is intentionally not published.\n\n## Published Artifact\n\nThe published container artifact is a multi-platform image index in GitHub Container Registry (GHCR) for:\n\n- `linux/amd64`.\n- `linux/arm64`.\n\nThe repository name is `ghcr.io/\u003cowner\u003e/sambee`.\n\nEach platform variant comes from the same Dockerfile, is built and validated on a native runner, and is assembled into the same candidate index digest.\n\nCosign signatures for that image digest are stored in a dedicated GHCR signature repository rather than in the main image repository. Cosign manages its own digest-derived signature artifact layout in that repository, so GHCR may show both tagged signature entries and referenced untagged bundle manifests for a retained image digest.\n\nSBOM and provenance data for that digest are extracted per platform on native runners, assembled into one metadata bundle, and published in the dedicated `ghcr.io/\u003cowner\u003e/sambee-signatures` repository under a digest-derived `.meta` tag.\n\nRelease and backfill workflows also upload the exact bundle files to the GitHub Release as convenience assets. The GHCR `.meta` artifact remains the canonical metadata bundle.\n\n## Security Model\n\nA new Docker build forces a fresh rebuild of the Dockerfile layer that installs Debian packages for the workflow run, so release candidates pick up the latest Debian package fixes available at build time instead of relying only on a previously cached OS-package layer.\n\nIt also:\n\n- publishes an SBOM and provenance metadata bundle under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n- signs the digest with Cosign using GitHub Actions OIDC.\n", "1.0": "+++\ntitle = \"Docker Release Overview\"\n+++\n\nSambee ships one production container image built from the repository-root Dockerfile.\n\nThe release flow builds a candidate image once, validates it, and later promotes that same image to `stable` or `beta`.\n\n## Summary\n\nIf you want to publish a new Docker image:\n\n1. Increment `VERSION` to the next `X.Y.Z` value and run `./scripts/sync-version`.\n1. Run `Release: Create Docker Image`.\n   - If the workflow's source version field is left blank, the image is built from the current commit in `main` and the Git tag `build-vX.Y.Z` is created to reserve the version for the commit the image is built from.\n   - If a source version field is specified, the workflow verifies and repairs the image associated with the version via the Git tag used for reservation.\n1. The workflow:\n   - assures concurrency via unique `stage-\u003crun\u003e-\u003cattempt\u003e-\u003cplatform\u003e` Docker tags in the internal staging repository\n   - builds the image\n   - validates and signs the image\n   - creates immutable `build-vX.Y.Z` Git commit and Docker image tags\n   - moves the `test` Docker tag to the newly built image\n1. Test the new image via the `test` Docker image tag.\n1. To move the `beta` Docker tag to the newly built image, run `Release: Publish Docker Image` manually.\n1. To publish the newly built image as `stable`, run `Release: Create Public Sambee Release` publish the resulting GitHub release.\n   - Release publication verifies the existing signed candidate and moves only the authorized mutable aliases. It never rebuilds an image.\n\nRead the detailed pages in this order:\n\n1. [Build Docker Image](../build-docker-image/)\n2. [Promote Docker Image](../promote-docker-image/)\n3. [Docker Backfill And Cleanup](../docker-backfill-and-cleanup/)\n\n## Workflow Map\n\n| Workflow | When to use it | Result |\n|---|---|---|\n| `CI: Validate Docker Image` | Any pull request, push to `main`, or manual smoke-test run. | Proves the production image still builds and starts, but does not publish anything. |\n| `Release: Create Docker Image` | To create an image for the current `main` commit or to verify/repair an image for an commit identified by its version tag. | Builds, validates, publishes the metadata bundle, marks that image as the current `test` image, and signs it. |\n| `Release: Publish Docker Image` | Run manually: to promote an image to `beta`.\u003cbr /\u003eIs run automatically when publishing a GitHub Release to promote an image to `stable`. | Verifies the existing preview-built image. Manual beta promotion moves only `beta`; public-release promotion moves `stable`, the minor-series tag, and catches `beta` up unless it already points to a higher version. |\n| `Maintenance: Backfill Docker Release Tags` | You need to restore or attach release tags for an already approved GitHub Release. | Reapplies release tags and channel aliases to an existing image without publishing a new runtime image. |\n| `Maintenance: Clean Up Docker Package Versions` | Clean up Docker image tag history and remove unreferenced GHCR artifacts. | Deletes unprotected SHA-tagged preview GHCR versions, prunes stale signature artifacts, and removes unreferenced untagged package versions while preserving release-tagged artifacts and protected aliases including `test`. |\n\n## Channels And Tags\n\nSambee publishes three moving channel tags:\n\n- `stable` for the approved production image.\n- `beta` for the approved preview image.\n- `test` for the most recently verified candidate image.\n\nEach candidate creates immutable tags:\n- Git: `build-vX.Y.Z`\n- Docker: `build-vX.Y.Z`, `X.Y.Z`, and `sha-\u003cfull-commit-sha\u003e`\n\nDuring publication, the workflow pushes native platform manifests by digest and assembles a multi-platform index in `ghcr.io/\u003cowner\u003e/sambee-staging`. It verifies metadata and signatures there, then copies the verified index by digest to the final immutable marker in `ghcr.io/\u003cowner\u003e/sambee`. Staging references are implementation details and are not user-facing tags.\n\nRelease workflows identify the target image by resolving the immutable Docker tag and attaching the appropriate release tags to the same image.\n\n`latest` is intentionally not published.\n\n## Published Artifact\n\nThe published container artifact is a multi-platform image index in GitHub Container Registry (GHCR) for:\n\n- `linux/amd64`.\n- `linux/arm64`.\n\nThe repository name is `ghcr.io/\u003cowner\u003e/sambee`.\n\nEach platform variant comes from the same Dockerfile, is built and validated on a native runner, and is assembled into the same candidate index digest.\n\nCosign signatures for that image digest are stored in a dedicated GHCR signature repository rather than in the main image repository. Cosign manages its own digest-derived signature artifact layout in that repository, so GHCR may show both tagged signature entries and referenced untagged bundle manifests for a retained image digest.\n\nSBOM and provenance data for that digest are extracted per platform on native runners, assembled into one metadata bundle, and published in the dedicated `ghcr.io/\u003cowner\u003e/sambee-signatures` repository under a digest-derived `.meta` tag.\n\nRelease and backfill workflows also upload the exact bundle files to the GitHub Release as convenience assets. The GHCR `.meta` artifact remains the canonical metadata bundle.\n\n## Security Model\n\nA new Docker build forces a fresh rebuild of the Dockerfile layer that installs Debian packages for the workflow run, so release candidates pick up the latest Debian package fixes available at build time instead of relying only on a previously cached OS-package layer.\n\nIt also:\n\n- publishes an SBOM and provenance metadata bundle under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n- signs the digest with Cosign using GitHub Actions OIDC.\n", "2.0": "+++\ntitle = \"Docker Release Overview\"\n+++\n\nSambee ships one production container image built from the repository-root Dockerfile.\n\nThe release flow builds a candidate image once, validates it, and later promotes that same image to `stable` or `beta`.\n\n## Summary\n\nIf you want to publish a new Docker image:\n\n1. Increment `VERSION` to the next `X.Y.Z` value and run `./scripts/sync-version`.\n1. Run `Release: Create Docker Image`.\n   - If the workflow's source version field is left blank, the image is built from the current commit in `main` and the Git tag `build-vX.Y.Z` is created to reserve the version for the commit the image is built from.\n   - If a source version field is specified, the workflow verifies and repairs the image associated with the version via the Git tag used for reservation.\n1. The workflow:\n   - assures concurrency via unique `stage-\u003crun\u003e-\u003cattempt\u003e-\u003cplatform\u003e` Docker tags in the internal staging repository\n   - builds the image\n   - validates and signs the image\n   - creates immutable `build-vX.Y.Z` Git commit and Docker image tags\n   - moves the `test` Docker tag to the newly built image\n1. Test the new image via the `test` Docker image tag.\n1. To move the `beta` Docker tag to the newly built image, run `Release: Publish Docker Image` manually.\n1. To publish the newly built image as `stable`, run `Release: Create Public Sambee Release` publish the resulting GitHub release.\n   - Release publication verifies the existing signed candidate and moves only the authorized mutable aliases. It never rebuilds an image.\n\nRead the detailed pages in this order:\n\n1. [Build Docker Image](../build-docker-image/)\n2. [Promote Docker Image](../promote-docker-image/)\n3. [Docker Backfill And Cleanup](../docker-backfill-and-cleanup/)\n\n## Workflow Map\n\n| Workflow | When to use it | Result |\n|---|---|---|\n| `CI: Validate Docker Image` | Any pull request, push to `main`, or manual smoke-test run. | Proves the production image still builds and starts, but does not publish anything. |\n| `Release: Create Docker Image` | To create an image for the current `main` commit or to verify/repair an image for an commit identified by its version tag. | Builds, validates, publishes the metadata bundle, marks that image as the current `test` image, and signs it. |\n| `Release: Publish Docker Image` | Run manually: to promote an image to `beta`.\u003cbr /\u003eIs run automatically when publishing a GitHub Release to promote an image to `stable`. | Verifies the existing preview-built image. Manual beta promotion moves only `beta`; public-release promotion moves `stable`, the minor-series tag, and catches `beta` up unless it already points to a higher version. |\n| `Maintenance: Backfill Docker Release Tags` | You need to restore or attach release tags for an already approved GitHub Release. | Reapplies release tags and channel aliases to an existing image without publishing a new runtime image. |\n| `Maintenance: Clean Up Docker Package Versions` | Clean up Docker image tag history and remove unreferenced GHCR artifacts. | Deletes unprotected SHA-tagged preview GHCR versions, prunes stale signature artifacts, and removes unreferenced untagged package versions while preserving release-tagged artifacts and protected aliases including `test`. |\n\n## Channels And Tags\n\nSambee publishes three moving channel tags:\n\n- `stable` for the approved production image.\n- `beta` for the approved preview image.\n- `test` for the most recently verified candidate image.\n\nEach candidate creates immutable tags:\n- Git: `build-vX.Y.Z`\n- Docker: `build-vX.Y.Z`, `X.Y.Z`, and `sha-\u003cfull-commit-sha\u003e`\n\nDuring publication, the workflow pushes native platform manifests by digest and assembles a multi-platform index in `ghcr.io/\u003cowner\u003e/sambee-staging`. It verifies metadata and signatures there, then copies the verified index by digest to the final immutable marker in `ghcr.io/\u003cowner\u003e/sambee`. Staging references are implementation details and are not user-facing tags.\n\nRelease workflows identify the target image by resolving the immutable Docker tag and attaching the appropriate release tags to the same image.\n\n`latest` is intentionally not published.\n\n## Published Artifact\n\nThe published container artifact is a multi-platform image index in GitHub Container Registry (GHCR) for:\n\n- `linux/amd64`.\n- `linux/arm64`.\n\nThe repository name is `ghcr.io/\u003cowner\u003e/sambee`.\n\nEach platform variant comes from the same Dockerfile, is built and validated on a native runner, and is assembled into the same candidate index digest.\n\nCosign signatures for that image digest are stored in a dedicated GHCR signature repository rather than in the main image repository. Cosign manages its own digest-derived signature artifact layout in that repository, so GHCR may show both tagged signature entries and referenced untagged bundle manifests for a retained image digest.\n\nSBOM and provenance data for that digest are extracted per platform on native runners, assembled into one metadata bundle, and published in the dedicated `ghcr.io/\u003cowner\u003e/sambee-signatures` repository under a digest-derived `.meta` tag.\n\nRelease and backfill workflows also upload the exact bundle files to the GitHub Release as convenience assets. The GHCR `.meta` artifact remains the canonical metadata bundle.\n\n## Security Model\n\nA new Docker build forces a fresh rebuild of the Dockerfile layer that installs Debian packages for the workflow run, so release candidates pick up the latest Debian package fixes available at build time instead of relying only on a previously cached OS-package layer.\n\nIt also:\n\n- publishes an SBOM and provenance metadata bundle under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n- signs the digest with Cosign using GitHub Actions OIDC.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/release-and-versioning/build-docker-image", "parent_id": "section:developer-guide/release-and-versioning", "depth": 2, "kind": "page", "label": "build-docker-image", "title": "Build Docker Image", "path": "developer-guide/release-and-versioning/build-docker-image", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "branched", "source_version": "0.7", "diff_added": 23, "diff_removed": 28}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "branched", "source_version": "0.9", "diff_added": 3, "diff_removed": 1}}, "content_versions": {"0.7": "+++\ntitle = \"Build Docker Image\"\n+++\n\nThis is step 1 of the Docker release flow.\n\nUse this `Release: Create Docker Image` workflow to create a deployable Docker image from a specific commit. It is the only workflow that builds and pushes a new Sambee image to GitHub Container Registry.\n\nThis workflow does not create a Git tag, does not publish a GitHub Release, and does not move anything to `stable` or `beta`. It builds a candidate image, validates it, publishes it under an immutable `sha-\u003cfull-commit-sha\u003e` tag, and moves the `test` tag to that same digest.\n\n## Summary\n\nUse this order when you are preparing a release candidate (RC) Docker image:\n\n1. Merge the commit you may want to ship.\n1. Start `Release: Create Docker Image` from that exact commit.\n   - Leave `source_ref` empty unless you deliberately need another immutable ref.\n   - Leave `publish_version_override` empty unless this is a preview-only label.\n1. Wait for the workflow to publish a new Docker image in GHCR tagged `sha-\u003cfull-commit-sha\u003e` and `test`.\n\n## Inputs\n\nThe manual workflow accepts these inputs:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `source_ref` | Which code to build. Use a commit SHA or tag. | Leave empty to build from the latest commit of the branch you selected when starting the run. Set it only when you need to point the run at a different commit. |\n| `publish_version_override` | Which version label to bake into the image. This is **not** the image tag used by Docker Compose. If you leave it empty, the workflow uses the checked-in `VERSION` value. | Use it for preview-only labels such as `0.8.0-test.1`. Leave it empty for a normal release candidate. |\n\nIf `publish_version_override` is set, CI rewrites `VERSION` for that run only and reruns `./scripts/sync-version` before building.\n\nThat version value is written into the image metadata and the generated metadata bundle. It is not the main preview lookup tag. The candidate is still published under `sha-\u003cfull-commit-sha\u003e` and then exposed through the moving `test` tag.\n\n## Validation\n\nBefore it publishes anything, the workflow runs the following validation checks:\n\n- Backend type checks must pass.\n- Backend tests must pass.\n- Frontend type checks must pass.\n- Frontend tests must pass.\n- Each supported platform image must build, publish by digest, and start successfully.\n\nThe workflow forces a fresh rebuild of the Dockerfile layer that installs Debian packages for that run. That keeps preview candidates aligned with the latest package fixes available from the Debian repositories at build time while still letting the rest of the image reuse BuildKit cache.\n\n## Published Output\n\nAfter validation, the workflow:\n\n1. Builds and pushes native `linux/amd64` and `linux/arm64` platform manifests.\n2. Starts those same images and waits for the health endpoint to succeed.\n3. Scans those same images with Trivy.\n4. Assembles the platform manifests into one multi-platform candidate index.\n5. Publishes that candidate index under `sha-\u003cfull-commit-sha\u003e`.\n6. Extracts per-platform SBOM and provenance payloads on native runners, then assembles and publishes the metadata bundle under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n7. Moves the `test` tag onto that same digest after metadata bundle publication succeeds.\n8. Signs the digest with Cosign using GitHub Actions OIDC.\n\nThe digest is the real artifact identity. The `test` tag is only a moving alias.\n\nLater promotion may move `stable`, `beta`, or both channel aliases to that same digest, depending on the release type and the current `beta` version.\n\nThe workflow uses digest-only platform pushes while assembling the final candidate index. Treat those platform manifests as internal publish artifacts, not release candidates.\n\nCosign writes the signature artifact into a dedicated signature repository so the main `sambee` package page stays centered on deployable image versions.\nThat signature repository can still show both digest-derived signature tags and referenced untagged bundle manifests, which are part of Cosign's current storage model rather than extra preview image variants.\n\n## Security Scan Behavior\n\nThe preview workflow runs Trivy before publish.\n\nFor preview publishing, Trivy findings are advisory rather than blocking. That keeps the newest candidate available for testing while still surfacing risk clearly in the workflow output.\n\nThe preview scan runs against the same pushed platform digests that are later assembled into the published candidate index, so validation and publication use the same platform manifests.\n\nThose manifests use the same OS-package refresh policy, so the candidate that gets published is rebuilt against current Debian package metadata for that workflow run.\n\n## Metadata\n\nThe published image includes OCI labels for the source repository, source ref name, git revision, version, creation time, and license.\n\nThe workflow also generates `GIT_COMMIT` in CI before building because GitHub-hosted runners do not run the local git hooks that usually keep that file current. That keeps frontend and backend build metadata aligned inside the container image.\n", "0.8": "+++\ntitle = \"Build Docker Image\"\n+++\n\nThis is step 1 of the Docker release flow.\n\nUse this `Release: Create Docker Image` workflow to create a deployable Docker image from a specific commit. It is the only workflow that builds and pushes a new Sambee image to GitHub Container Registry.\n\nThis workflow does not create a Git tag, does not publish a GitHub Release, and does not move anything to `stable` or `beta`. It builds a candidate image, validates it, publishes it under an immutable `sha-\u003cfull-commit-sha\u003e` tag, and moves the `test` tag to that same digest.\n\n## Summary\n\nUse this order when you are preparing a release candidate (RC) Docker image:\n\n1. Merge the commit you may want to ship.\n1. Start `Release: Create Docker Image` from that exact commit.\n   - Leave `source_ref` empty unless you deliberately need another immutable ref.\n   - Leave `publish_version_override` empty unless this is a preview-only label.\n1. Wait for the workflow to publish a new Docker image in GHCR tagged `sha-\u003cfull-commit-sha\u003e` and `test`.\n\n## Inputs\n\nThe manual workflow accepts these inputs:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `source_ref` | Which code to build. Use a commit SHA or tag. | Leave empty to build from the latest commit of the branch you selected when starting the run. Set it only when you need to point the run at a different commit. |\n| `publish_version_override` | Which version label to bake into the image. This is **not** the image tag used by Docker Compose. If you leave it empty, the workflow uses the checked-in `VERSION` value. | Use it for preview-only labels such as `0.8.0-test.1`. Leave it empty for a normal release candidate. |\n\nIf `publish_version_override` is set, CI rewrites `VERSION` for that run only and reruns `./scripts/sync-version` before building.\n\nThat version value is written into the image metadata and the generated metadata bundle. It is not the main preview lookup tag. The candidate is still published under `sha-\u003cfull-commit-sha\u003e` and then exposed through the moving `test` tag.\n\n## Validation\n\nBefore it publishes anything, the workflow runs the following validation checks:\n\n- Backend type checks must pass.\n- Backend tests must pass.\n- Frontend type checks must pass.\n- Frontend tests must pass.\n- Each supported platform image must build, publish by digest, and start successfully.\n\nThe workflow forces a fresh rebuild of the Dockerfile layer that installs Debian packages for that run. That keeps preview candidates aligned with the latest package fixes available from the Debian repositories at build time while still letting the rest of the image reuse BuildKit cache.\n\n## Published Output\n\nAfter validation, the workflow:\n\n1. Builds and pushes native `linux/amd64` and `linux/arm64` platform manifests.\n2. Starts those same images and waits for the health endpoint to succeed.\n3. Scans those same images with Trivy.\n4. Assembles the platform manifests into one multi-platform candidate index.\n5. Publishes that candidate index under `sha-\u003cfull-commit-sha\u003e`.\n6. Extracts per-platform SBOM and provenance payloads on native runners, then assembles and publishes the metadata bundle under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n7. Moves the `test` tag onto that same digest after metadata bundle publication succeeds.\n8. Signs the digest with Cosign using GitHub Actions OIDC.\n\nThe digest is the real artifact identity. The `test` tag is only a moving alias.\n\nLater promotion may move `stable`, `beta`, or both channel aliases to that same digest, depending on the release type and the current `beta` version.\n\nThe workflow uses digest-only platform pushes while assembling the final candidate index. Treat those platform manifests as internal publish artifacts, not release candidates.\n\nCosign writes the signature artifact into a dedicated signature repository so the main `sambee` package page stays centered on deployable image versions.\nThat signature repository can still show both digest-derived signature tags and referenced untagged bundle manifests, which are part of Cosign's current storage model rather than extra preview image variants.\n\n## Security Scan Behavior\n\nThe preview workflow runs Trivy before publish.\n\nFor preview publishing, Trivy findings are advisory rather than blocking. That keeps the newest candidate available for testing while still surfacing risk clearly in the workflow output.\n\nThe preview scan runs against the same pushed platform digests that are later assembled into the published candidate index, so validation and publication use the same platform manifests.\n\nThose manifests use the same OS-package refresh policy, so the candidate that gets published is rebuilt against current Debian package metadata for that workflow run.\n\n## Metadata\n\nThe published image includes OCI labels for the source repository, source ref name, git revision, version, creation time, and license.\n\nThe workflow also generates `GIT_COMMIT` in CI before building because GitHub-hosted runners do not run the local git hooks that usually keep that file current. That keeps frontend and backend build metadata aligned inside the container image.\n", "0.9": "+++\ntitle = \"Build Docker Image\"\n+++\n\nThis is step 1 of the Docker release flow ([overview](../docker-release-overview/)).\n\nUse `Release: Create Docker Image` to build one immutable Docker candidate from `main`. It is the only workflow that builds and pushes a new Sambee image to GitHub Container Registry (GHCR).\n\nThe workflow reserves the annotated canonical Git tag `build-vX.Y.Z` for the committed, synchronized `VERSION` source. It does not publish a GitHub Release or move `stable` or `beta`.\n\n## Inputs\n\nThe workflow accepts only an optional existing candidate selector:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `build_version` | Reuse an existing immutable `X.Y.Z` candidate. | Leave empty for a new candidate. Use an existing value only to verify or repair its immutable aliases. |\n\nThe workflow rejects arbitrary source refs, source SHAs, and temporary version overrides. The checked-in, synchronized plain numeric `VERSION` is the only publishable version source.\n\n## Validation\n\nBefore it publishes anything, the workflow runs the following validation checks:\n\n- Backend type checks must pass.\n- Backend tests must pass.\n- Frontend type checks must pass.\n- Frontend tests must pass.\n- Each supported platform image must build, publish by digest, and start successfully.\n\nThe workflow forces a fresh rebuild of the Dockerfile layer that installs Debian packages for that run. That keeps preview candidates aligned with the latest package fixes available from the Debian repositories at build time while still letting the rest of the image reuse BuildKit cache.\n\n## Published Output\n\nAfter validation, the workflow:\n\n1. Builds and pushes native `linux/amd64` and `linux/arm64` platform manifests to the internal `ghcr.io/\u003cowner\u003e/sambee-staging` repository.\n2. Starts those same images and waits for the health endpoint to succeed.\n3. Scans those same images with Trivy.\n4. Assembles the platform manifests into one multi-platform staging index and verifies its image labels.\n5. Extracts per-platform SBOM and provenance payloads on native runners, then assembles and publishes a metadata bundle that names the final `sambee` image identity under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n6. Signs and verifies the staging digest with Cosign using GitHub Actions OIDC.\n7. Copies the verified multi-platform index by digest to the immutable `sambee:build-vX.Y.Z` marker, then verifies the final image, metadata bundle, and signature again.\n8. Creates immutable `X.Y.Z` and `sha-\u003cfull-commit-sha\u003e` aliases and moves `test` to that same verified image.\n\nThe digest is the real artifact identity. The canonical `build-vX.Y.Z` tag is the candidate source of truth; `test` is only a moving alias.\n\nLater promotion may move `stable`, `beta`, or both channel aliases to that same image, depending on the release type and the current `beta` version.\n\nThe workflow uses digest-only platform pushes and run-scoped `stage-\u003crun\u003e-\u003cattempt\u003e-*` tags in `sambee-staging`. Treat them as internal transport artifacts, not release candidates.\n\nCosign writes the signature artifact into a dedicated signature repository so the main `sambee` package page stays centered on deployable image versions.\nThat signature repository can still show both digest-derived signature tags and referenced untagged bundle manifests, which are part of Cosign's current storage model rather than extra preview image variants.\n\n## Retry Behavior\n\nBefore the late candidate marker is written, a failed run may be retried with the same `Z` version. The run uses a unique `stage-\u003crun\u003e-\u003cattempt\u003e-\u003cplatform\u003e` tag in `sambee-staging` and cleans up its staging versions after promotion or failure. That package can also contain untagged digest-only platform manifests. The Docker publication lock serializes candidate and maintenance cleanup, so the cleanup may delete the whole isolated package when every tagged version is a staging tag; GHCR requires that package-level operation when the last tagged version remains. Scheduled cleanup reclaims stale staging artifacts and unreferenced signature and metadata artifacts.\n\nAfter a valid candidate marker exists, a matching dispatch takes the repair-only path. It verifies the signed digest and restores only missing matching immutable aliases or the `test` pointer; it does not rebuild the image. A conflicting immutable marker requires incrementing `Z` and publishing a new candidate.\n\nGitHub Actions concurrency is mutual exclusion, not a FIFO queue: only one pending run is retained for the publication lock. Avoid stacking dispatches. A superseded pending dispatch is safe to submit again because it did not reach a publication step.\n\n## Security Scan Behavior\n\nThe preview workflow runs Trivy before publish.\n\nFor preview publishing, Trivy findings are advisory rather than blocking. That keeps the newest candidate available for testing while still surfacing risk clearly in the workflow output.\n\nThe preview scan runs against the same pushed platform digests that are later assembled into the published candidate index, so validation and publication use the same platform manifests.\n\nThose manifests use the same OS-package refresh policy, so the candidate that gets published is rebuilt against current Debian package metadata for that workflow run.\n\n## Metadata\n\nThe published image includes OCI labels for the source repository, source ref name, git revision, version, creation time, and license.\n\nThe workflow also generates `GIT_COMMIT` in CI before building because GitHub-hosted runners do not run the local git hooks that usually keep that file current. That keeps frontend and backend build metadata aligned inside the container image.\n", "1.0": "+++\ntitle = \"Build Docker Image\"\n+++\n\nThis is step 1 of the Docker release flow ([overview](../docker-release-overview/)).\n\nUse `Release: Create Docker Image` to build one immutable Docker candidate from `main`. It is the only workflow that builds and pushes a new Sambee image to GitHub Container Registry (GHCR).\n\nThe workflow reserves the annotated canonical Git tag `build-vX.Y.Z` for the committed, synchronized `VERSION` source. It does not publish a GitHub Release or move `stable` or `beta`.\n\n## Inputs\n\nThe workflow accepts only an optional existing candidate selector:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `build_version` | Reuse an existing immutable `X.Y.Z` candidate. | Leave empty for a new candidate. Use an existing value only to verify or repair its immutable aliases. |\n\nThe workflow rejects arbitrary source refs, source SHAs, and temporary version overrides. The checked-in, synchronized plain numeric `VERSION` is the only publishable version source.\n\n## Validation\n\nBefore it publishes anything, the workflow runs the following validation checks:\n\n- Backend type checks must pass.\n- Backend tests must pass.\n- Frontend type checks must pass.\n- Frontend tests must pass.\n- Each supported platform image must build, publish by digest, and start successfully.\n\nThe workflow forces a fresh rebuild of the Dockerfile layer that installs Debian packages for that run. That keeps preview candidates aligned with the latest package fixes available from the Debian repositories at build time while still letting the rest of the image reuse BuildKit cache.\n\n## Published Output\n\nAfter validation, the workflow:\n\n1. Builds and pushes native `linux/amd64` and `linux/arm64` platform manifests to the internal `ghcr.io/\u003cowner\u003e/sambee-staging` repository.\n2. Starts those same images and waits for the health endpoint to succeed.\n3. Scans those same images with Trivy.\n4. Assembles the platform manifests into one multi-platform staging index and verifies its image labels.\n5. Extracts per-platform SBOM and provenance payloads on native runners, then assembles and publishes a metadata bundle that names the final `sambee` image identity under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n6. Signs and verifies the staging digest with Cosign using GitHub Actions OIDC.\n7. Copies the verified multi-platform index by digest to the immutable `sambee:build-vX.Y.Z` marker, then verifies the final image, metadata bundle, and signature again.\n8. Creates immutable `X.Y.Z` and `sha-\u003cfull-commit-sha\u003e` aliases and moves `test` to that same verified image.\n\nThe digest is the real artifact identity. The canonical `build-vX.Y.Z` tag is the candidate source of truth; `test` is only a moving alias.\n\nLater promotion may move `stable`, `beta`, or both channel aliases to that same image, depending on the release type and the current `beta` version.\n\nThe workflow uses digest-only platform pushes and run-scoped `stage-\u003crun\u003e-\u003cattempt\u003e-*` tags in `sambee-staging`. Treat them as internal transport artifacts, not release candidates.\n\nCosign writes the signature artifact into a dedicated signature repository so the main `sambee` package page stays centered on deployable image versions.\nThat signature repository can still show both digest-derived signature tags and referenced untagged bundle manifests, which are part of Cosign's current storage model rather than extra preview image variants.\n\n## Retry Behavior\n\nBefore the late candidate marker is written, a failed run may be retried with the same `Z` version. The run uses a unique `stage-\u003crun\u003e-\u003cattempt\u003e-\u003cplatform\u003e` tag in `sambee-staging` and cleans up its staging versions after promotion or failure. That package can also contain untagged digest-only platform manifests. The Docker publication lock serializes candidate and maintenance cleanup, so the cleanup may delete the whole isolated package when every tagged version is a staging tag; GHCR requires that package-level operation when the last tagged version remains. Scheduled cleanup reclaims stale staging artifacts and unreferenced signature and metadata artifacts.\n\nAfter a valid candidate marker exists, a matching dispatch takes the repair-only path. It verifies the signed digest and restores only missing matching immutable aliases or the `test` pointer; it does not rebuild the image. A conflicting immutable marker requires incrementing `Z` and publishing a new candidate.\n\nGitHub Actions concurrency is mutual exclusion, not a FIFO queue: only one pending run is retained for the publication lock. Avoid stacking dispatches. A superseded pending dispatch is safe to submit again because it did not reach a publication step.\n\n## Security Scan Behavior\n\nThe preview workflow runs Trivy before publish.\n\nFor preview publishing, Trivy findings are advisory rather than blocking. That keeps the newest candidate available for testing while still surfacing risk clearly in the workflow output.\n\nThe preview scan runs against the same pushed platform digests that are later assembled into the published candidate index, so validation and publication use the same platform manifests.\n\nThose manifests use the same OS-package refresh policy, so the candidate that gets published is rebuilt against current Debian package metadata for that workflow run.\n\n## Metadata\n\nThe published image includes OCI labels for the source repository, source ref name, git revision, version, creation time, and license.\n\nThe workflow also generates `GIT_COMMIT` in CI before building because GitHub-hosted runners do not run the local git hooks that usually keep that file current. That keeps frontend and backend build metadata aligned inside the container image.\n", "2.0": "+++\ntitle = \"Build Docker Image\"\n+++\n\nThis is step 1 of the Docker release flow ([overview](../docker-release-overview/)).\n\nUse `Release: Create Docker Image` to build one immutable Docker candidate from `main`. It is the only workflow that builds and pushes a new Sambee image to GitHub Container Registry (GHCR).\n\nThe workflow reserves the annotated canonical Git tag `build-vX.Y.Z` for the committed, synchronized `VERSION` source. It does not publish a GitHub Release or move `stable` or `beta`.\n\n## Inputs\n\nThe workflow accepts only an optional existing candidate selector:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `build_version` | Reuse an existing immutable `X.Y.Z` candidate. | Leave empty for a new candidate. Use an existing value only to verify or repair its immutable aliases. |\n\nThe workflow rejects arbitrary source refs, source SHAs, and temporary version overrides. The checked-in, synchronized plain numeric `VERSION` is the only publishable version source.\n\n## Validation\n\nBefore it publishes anything, the workflow requires the following validation checks:\n\n- Backend type checks must pass.\n- Backend tests must pass.\n- Frontend type checks must pass.\n- Frontend tests must pass.\n- Each supported platform image must build, publish by digest, and start successfully.\n\nFor source checks, the workflow reuses successful backend and frontend jobs from `CI: Test` only when they ran on a push to `main` for the exact candidate commit. It checks each job separately. If a job was skipped, is still running, or its result cannot be verified, the release workflow runs that area's checks itself. PR checks alone do not qualify because they may test a different merge commit. Platform image builds and startup checks always run for a new candidate.\n\nThe workflow forces a fresh rebuild of the Dockerfile layer that installs Debian packages for that run. That keeps preview candidates aligned with the latest package fixes available from the Debian repositories at build time while still letting the rest of the image reuse BuildKit cache.\n\n## Published Output\n\nAfter validation, the workflow:\n\n1. Builds and pushes native `linux/amd64` and `linux/arm64` platform manifests to the internal `ghcr.io/\u003cowner\u003e/sambee-staging` repository.\n2. Starts those same images and waits for the health endpoint to succeed.\n3. Scans those same images with Trivy.\n4. Assembles the platform manifests into one multi-platform staging index and verifies its image labels.\n5. Extracts per-platform SBOM and provenance payloads on native runners, then assembles and publishes a metadata bundle that names the final `sambee` image identity under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n6. Signs and verifies the staging digest with Cosign using GitHub Actions OIDC.\n7. Copies the verified multi-platform index by digest to the immutable `sambee:build-vX.Y.Z` marker, then verifies the final image, metadata bundle, and signature again.\n8. Creates immutable `X.Y.Z` and `sha-\u003cfull-commit-sha\u003e` aliases and moves `test` to that same verified image.\n\nThe digest is the real artifact identity. The canonical `build-vX.Y.Z` tag is the candidate source of truth; `test` is only a moving alias.\n\nLater promotion may move `stable`, `beta`, or both channel aliases to that same image, depending on the release type and the current `beta` version.\n\nThe workflow uses digest-only platform pushes and run-scoped `stage-\u003crun\u003e-\u003cattempt\u003e-*` tags in `sambee-staging`. Treat them as internal transport artifacts, not release candidates.\n\nCosign writes the signature artifact into a dedicated signature repository so the main `sambee` package page stays centered on deployable image versions.\nThat signature repository can still show both digest-derived signature tags and referenced untagged bundle manifests, which are part of Cosign's current storage model rather than extra preview image variants.\n\n## Retry Behavior\n\nBefore the late candidate marker is written, a failed run may be retried with the same `Z` version. The run uses a unique `stage-\u003crun\u003e-\u003cattempt\u003e-\u003cplatform\u003e` tag in `sambee-staging` and cleans up its staging versions after promotion or failure. That package can also contain untagged digest-only platform manifests. The Docker publication lock serializes candidate and maintenance cleanup, so the cleanup may delete the whole isolated package when every tagged version is a staging tag; GHCR requires that package-level operation when the last tagged version remains. Scheduled cleanup reclaims stale staging artifacts and unreferenced signature and metadata artifacts.\n\nAfter a valid candidate marker exists, a matching dispatch takes the repair-only path. It verifies the signed digest and restores only missing matching immutable aliases or the `test` pointer; it does not rebuild the image. A conflicting immutable marker requires incrementing `Z` and publishing a new candidate.\n\nGitHub Actions concurrency is mutual exclusion, not a FIFO queue: only one pending run is retained for the publication lock. Avoid stacking dispatches. A superseded pending dispatch is safe to submit again because it did not reach a publication step.\n\n## Security Scan Behavior\n\nThe preview workflow runs Trivy before publish.\n\nFor preview publishing, Trivy findings are advisory rather than blocking. That keeps the newest candidate available for testing while still surfacing risk clearly in the workflow output.\n\nThe preview scan runs against the same pushed platform digests that are later assembled into the published candidate index, so validation and publication use the same platform manifests.\n\nThose manifests use the same OS-package refresh policy, so the candidate that gets published is rebuilt against current Debian package metadata for that workflow run.\n\n## Metadata\n\nThe published image includes OCI labels for the source repository, source ref name, git revision, version, creation time, and license.\n\nThe workflow also generates `GIT_COMMIT` in CI before building because GitHub-hosted runners do not run the local git hooks that usually keep that file current. That keeps frontend and backend build metadata aligned inside the container image.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Build Docker Image\"\n+++\n\nThis is step 1 of the Docker release flow.\n\nUse this `Release: Create Docker Image` workflow to create a deployable Docker image from a specific commit. It is the only workflow that builds and pushes a new Sambee image to GitHub Container Registry.\n\nThis workflow does not create a Git tag, does not publish a GitHub Release, and does not move anything to `stable` or `beta`. It builds a candidate image, validates it, publishes it under an immutable `sha-\u003cfull-commit-sha\u003e` tag, and moves the `test` tag to that same digest.\n\n## Summary\n\nUse this order when you are preparing a release candidate (RC) Docker image:\n\n1. Merge the commit you may want to ship.\n1. Start `Release: Create Docker Image` from that exact commit.\n   - Leave `source_ref` empty unless you deliberately need another immutable ref.\n   - Leave `publish_version_override` empty unless this is a preview-only label.\n1. Wait for the workflow to publish a new Docker image in GHCR tagged `sha-\u003cfull-commit-sha\u003e` and `test`.\n\n## Inputs\n\nThe manual workflow accepts these inputs:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `source_ref` | Which code to build. Use a commit SHA or tag. | Leave empty to build from the latest commit of the branch you selected when starting the run. Set it only when you need to point the run at a different commit. |\n| `publish_version_override` | Which version label to bake into the image. This is **not** the image tag used by Docker Compose. If you leave it empty, the workflow uses the checked-in `VERSION` value. | Use it for preview-only labels such as `0.8.0-test.1`. Leave it empty for a normal release candidate. |\n\nIf `publish_version_override` is set, CI rewrites `VERSION` for that run only and reruns `./scripts/sync-version` before building.\n\nThat version value is written into the image metadata and the generated metadata bundle. It is not the main preview lookup tag. The candidate is still published under `sha-\u003cfull-commit-sha\u003e` and then exposed through the moving `test` tag.\n\n## Validation\n\nBefore it publishes anything, the workflow runs the following validation checks:\n\n- Backend type checks must pass.\n- Backend tests must pass.\n- Frontend type checks must pass.\n- Frontend tests must pass.\n- Each supported platform image must build, publish by digest, and start successfully.\n\nThe workflow forces a fresh rebuild of the Dockerfile layer that installs Debian packages for that run. That keeps preview candidates aligned with the latest package fixes available from the Debian repositories at build time while still letting the rest of the image reuse BuildKit cache.\n\n## Published Output\n\nAfter validation, the workflow:\n\n1. Builds and pushes native `linux/amd64` and `linux/arm64` platform manifests.\n2. Starts those same images and waits for the health endpoint to succeed.\n3. Scans those same images with Trivy.\n4. Assembles the platform manifests into one multi-platform candidate index.\n5. Publishes that candidate index under `sha-\u003cfull-commit-sha\u003e`.\n6. Extracts per-platform SBOM and provenance payloads on native runners, then assembles and publishes the metadata bundle under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n7. Moves the `test` tag onto that same digest after metadata bundle publication succeeds.\n8. Signs the digest with Cosign using GitHub Actions OIDC.\n\nThe digest is the real artifact identity. The `test` tag is only a moving alias.\n\nLater promotion may move `stable`, `beta`, or both channel aliases to that same digest, depending on the release type and the current `beta` version.\n\nThe workflow uses digest-only platform pushes while assembling the final candidate index. Treat those platform manifests as internal publish artifacts, not release candidates.\n\nCosign writes the signature artifact into a dedicated signature repository so the main `sambee` package page stays centered on deployable image versions.\nThat signature repository can still show both digest-derived signature tags and referenced untagged bundle manifests, which are part of Cosign's current storage model rather than extra preview image variants.\n\n## Security Scan Behavior\n\nThe preview workflow runs Trivy before publish.\n\nFor preview publishing, Trivy findings are advisory rather than blocking. That keeps the newest candidate available for testing while still surfacing risk clearly in the workflow output.\n\nThe preview scan runs against the same pushed platform digests that are later assembled into the published candidate index, so validation and publication use the same platform manifests.\n\nThose manifests use the same OS-package refresh policy, so the candidate that gets published is rebuilt against current Debian package metadata for that workflow run.\n\n## Metadata\n\nThe published image includes OCI labels for the source repository, source ref name, git revision, version, creation time, and license.\n\nThe workflow also generates `GIT_COMMIT` in CI before building because GitHub-hosted runners do not run the local git hooks that usually keep that file current. That keeps frontend and backend build metadata aligned inside the container image.\n", "0.8": "+++\ntitle = \"Build Docker Image\"\n+++\n\nThis is step 1 of the Docker release flow.\n\nUse this `Release: Create Docker Image` workflow to create a deployable Docker image from a specific commit. It is the only workflow that builds and pushes a new Sambee image to GitHub Container Registry.\n\nThis workflow does not create a Git tag, does not publish a GitHub Release, and does not move anything to `stable` or `beta`. It builds a candidate image, validates it, publishes it under an immutable `sha-\u003cfull-commit-sha\u003e` tag, and moves the `test` tag to that same digest.\n\n## Summary\n\nUse this order when you are preparing a release candidate (RC) Docker image:\n\n1. Merge the commit you may want to ship.\n1. Start `Release: Create Docker Image` from that exact commit.\n   - Leave `source_ref` empty unless you deliberately need another immutable ref.\n   - Leave `publish_version_override` empty unless this is a preview-only label.\n1. Wait for the workflow to publish a new Docker image in GHCR tagged `sha-\u003cfull-commit-sha\u003e` and `test`.\n\n## Inputs\n\nThe manual workflow accepts these inputs:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `source_ref` | Which code to build. Use a commit SHA or tag. | Leave empty to build from the latest commit of the branch you selected when starting the run. Set it only when you need to point the run at a different commit. |\n| `publish_version_override` | Which version label to bake into the image. This is **not** the image tag used by Docker Compose. If you leave it empty, the workflow uses the checked-in `VERSION` value. | Use it for preview-only labels such as `0.8.0-test.1`. Leave it empty for a normal release candidate. |\n\nIf `publish_version_override` is set, CI rewrites `VERSION` for that run only and reruns `./scripts/sync-version` before building.\n\nThat version value is written into the image metadata and the generated metadata bundle. It is not the main preview lookup tag. The candidate is still published under `sha-\u003cfull-commit-sha\u003e` and then exposed through the moving `test` tag.\n\n## Validation\n\nBefore it publishes anything, the workflow runs the following validation checks:\n\n- Backend type checks must pass.\n- Backend tests must pass.\n- Frontend type checks must pass.\n- Frontend tests must pass.\n- Each supported platform image must build, publish by digest, and start successfully.\n\nThe workflow forces a fresh rebuild of the Dockerfile layer that installs Debian packages for that run. That keeps preview candidates aligned with the latest package fixes available from the Debian repositories at build time while still letting the rest of the image reuse BuildKit cache.\n\n## Published Output\n\nAfter validation, the workflow:\n\n1. Builds and pushes native `linux/amd64` and `linux/arm64` platform manifests.\n2. Starts those same images and waits for the health endpoint to succeed.\n3. Scans those same images with Trivy.\n4. Assembles the platform manifests into one multi-platform candidate index.\n5. Publishes that candidate index under `sha-\u003cfull-commit-sha\u003e`.\n6. Extracts per-platform SBOM and provenance payloads on native runners, then assembles and publishes the metadata bundle under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n7. Moves the `test` tag onto that same digest after metadata bundle publication succeeds.\n8. Signs the digest with Cosign using GitHub Actions OIDC.\n\nThe digest is the real artifact identity. The `test` tag is only a moving alias.\n\nLater promotion may move `stable`, `beta`, or both channel aliases to that same digest, depending on the release type and the current `beta` version.\n\nThe workflow uses digest-only platform pushes while assembling the final candidate index. Treat those platform manifests as internal publish artifacts, not release candidates.\n\nCosign writes the signature artifact into a dedicated signature repository so the main `sambee` package page stays centered on deployable image versions.\nThat signature repository can still show both digest-derived signature tags and referenced untagged bundle manifests, which are part of Cosign's current storage model rather than extra preview image variants.\n\n## Security Scan Behavior\n\nThe preview workflow runs Trivy before publish.\n\nFor preview publishing, Trivy findings are advisory rather than blocking. That keeps the newest candidate available for testing while still surfacing risk clearly in the workflow output.\n\nThe preview scan runs against the same pushed platform digests that are later assembled into the published candidate index, so validation and publication use the same platform manifests.\n\nThose manifests use the same OS-package refresh policy, so the candidate that gets published is rebuilt against current Debian package metadata for that workflow run.\n\n## Metadata\n\nThe published image includes OCI labels for the source repository, source ref name, git revision, version, creation time, and license.\n\nThe workflow also generates `GIT_COMMIT` in CI before building because GitHub-hosted runners do not run the local git hooks that usually keep that file current. That keeps frontend and backend build metadata aligned inside the container image.\n", "0.9": "+++\ntitle = \"Build Docker Image\"\n+++\n\nThis is step 1 of the Docker release flow ([overview](../docker-release-overview/)).\n\nUse `Release: Create Docker Image` to build one immutable Docker candidate from `main`. It is the only workflow that builds and pushes a new Sambee image to GitHub Container Registry (GHCR).\n\nThe workflow reserves the annotated canonical Git tag `build-vX.Y.Z` for the committed, synchronized `VERSION` source. It does not publish a GitHub Release or move `stable` or `beta`.\n\n## Inputs\n\nThe workflow accepts only an optional existing candidate selector:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `build_version` | Reuse an existing immutable `X.Y.Z` candidate. | Leave empty for a new candidate. Use an existing value only to verify or repair its immutable aliases. |\n\nThe workflow rejects arbitrary source refs, source SHAs, and temporary version overrides. The checked-in, synchronized plain numeric `VERSION` is the only publishable version source.\n\n## Validation\n\nBefore it publishes anything, the workflow runs the following validation checks:\n\n- Backend type checks must pass.\n- Backend tests must pass.\n- Frontend type checks must pass.\n- Frontend tests must pass.\n- Each supported platform image must build, publish by digest, and start successfully.\n\nThe workflow forces a fresh rebuild of the Dockerfile layer that installs Debian packages for that run. That keeps preview candidates aligned with the latest package fixes available from the Debian repositories at build time while still letting the rest of the image reuse BuildKit cache.\n\n## Published Output\n\nAfter validation, the workflow:\n\n1. Builds and pushes native `linux/amd64` and `linux/arm64` platform manifests to the internal `ghcr.io/\u003cowner\u003e/sambee-staging` repository.\n2. Starts those same images and waits for the health endpoint to succeed.\n3. Scans those same images with Trivy.\n4. Assembles the platform manifests into one multi-platform staging index and verifies its image labels.\n5. Extracts per-platform SBOM and provenance payloads on native runners, then assembles and publishes a metadata bundle that names the final `sambee` image identity under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n6. Signs and verifies the staging digest with Cosign using GitHub Actions OIDC.\n7. Copies the verified multi-platform index by digest to the immutable `sambee:build-vX.Y.Z` marker, then verifies the final image, metadata bundle, and signature again.\n8. Creates immutable `X.Y.Z` and `sha-\u003cfull-commit-sha\u003e` aliases and moves `test` to that same verified image.\n\nThe digest is the real artifact identity. The canonical `build-vX.Y.Z` tag is the candidate source of truth; `test` is only a moving alias.\n\nLater promotion may move `stable`, `beta`, or both channel aliases to that same image, depending on the release type and the current `beta` version.\n\nThe workflow uses digest-only platform pushes and run-scoped `stage-\u003crun\u003e-\u003cattempt\u003e-*` tags in `sambee-staging`. Treat them as internal transport artifacts, not release candidates.\n\nCosign writes the signature artifact into a dedicated signature repository so the main `sambee` package page stays centered on deployable image versions.\nThat signature repository can still show both digest-derived signature tags and referenced untagged bundle manifests, which are part of Cosign's current storage model rather than extra preview image variants.\n\n## Retry Behavior\n\nBefore the late candidate marker is written, a failed run may be retried with the same `Z` version. The run uses a unique `stage-\u003crun\u003e-\u003cattempt\u003e-\u003cplatform\u003e` tag in `sambee-staging` and cleans up its staging versions after promotion or failure. That package can also contain untagged digest-only platform manifests. The Docker publication lock serializes candidate and maintenance cleanup, so the cleanup may delete the whole isolated package when every tagged version is a staging tag; GHCR requires that package-level operation when the last tagged version remains. Scheduled cleanup reclaims stale staging artifacts and unreferenced signature and metadata artifacts.\n\nAfter a valid candidate marker exists, a matching dispatch takes the repair-only path. It verifies the signed digest and restores only missing matching immutable aliases or the `test` pointer; it does not rebuild the image. A conflicting immutable marker requires incrementing `Z` and publishing a new candidate.\n\nGitHub Actions concurrency is mutual exclusion, not a FIFO queue: only one pending run is retained for the publication lock. Avoid stacking dispatches. A superseded pending dispatch is safe to submit again because it did not reach a publication step.\n\n## Security Scan Behavior\n\nThe preview workflow runs Trivy before publish.\n\nFor preview publishing, Trivy findings are advisory rather than blocking. That keeps the newest candidate available for testing while still surfacing risk clearly in the workflow output.\n\nThe preview scan runs against the same pushed platform digests that are later assembled into the published candidate index, so validation and publication use the same platform manifests.\n\nThose manifests use the same OS-package refresh policy, so the candidate that gets published is rebuilt against current Debian package metadata for that workflow run.\n\n## Metadata\n\nThe published image includes OCI labels for the source repository, source ref name, git revision, version, creation time, and license.\n\nThe workflow also generates `GIT_COMMIT` in CI before building because GitHub-hosted runners do not run the local git hooks that usually keep that file current. That keeps frontend and backend build metadata aligned inside the container image.\n", "1.0": "+++\ntitle = \"Build Docker Image\"\n+++\n\nThis is step 1 of the Docker release flow ([overview](../docker-release-overview/)).\n\nUse `Release: Create Docker Image` to build one immutable Docker candidate from `main`. It is the only workflow that builds and pushes a new Sambee image to GitHub Container Registry (GHCR).\n\nThe workflow reserves the annotated canonical Git tag `build-vX.Y.Z` for the committed, synchronized `VERSION` source. It does not publish a GitHub Release or move `stable` or `beta`.\n\n## Inputs\n\nThe workflow accepts only an optional existing candidate selector:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `build_version` | Reuse an existing immutable `X.Y.Z` candidate. | Leave empty for a new candidate. Use an existing value only to verify or repair its immutable aliases. |\n\nThe workflow rejects arbitrary source refs, source SHAs, and temporary version overrides. The checked-in, synchronized plain numeric `VERSION` is the only publishable version source.\n\n## Validation\n\nBefore it publishes anything, the workflow runs the following validation checks:\n\n- Backend type checks must pass.\n- Backend tests must pass.\n- Frontend type checks must pass.\n- Frontend tests must pass.\n- Each supported platform image must build, publish by digest, and start successfully.\n\nThe workflow forces a fresh rebuild of the Dockerfile layer that installs Debian packages for that run. That keeps preview candidates aligned with the latest package fixes available from the Debian repositories at build time while still letting the rest of the image reuse BuildKit cache.\n\n## Published Output\n\nAfter validation, the workflow:\n\n1. Builds and pushes native `linux/amd64` and `linux/arm64` platform manifests to the internal `ghcr.io/\u003cowner\u003e/sambee-staging` repository.\n2. Starts those same images and waits for the health endpoint to succeed.\n3. Scans those same images with Trivy.\n4. Assembles the platform manifests into one multi-platform staging index and verifies its image labels.\n5. Extracts per-platform SBOM and provenance payloads on native runners, then assembles and publishes a metadata bundle that names the final `sambee` image identity under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n6. Signs and verifies the staging digest with Cosign using GitHub Actions OIDC.\n7. Copies the verified multi-platform index by digest to the immutable `sambee:build-vX.Y.Z` marker, then verifies the final image, metadata bundle, and signature again.\n8. Creates immutable `X.Y.Z` and `sha-\u003cfull-commit-sha\u003e` aliases and moves `test` to that same verified image.\n\nThe digest is the real artifact identity. The canonical `build-vX.Y.Z` tag is the candidate source of truth; `test` is only a moving alias.\n\nLater promotion may move `stable`, `beta`, or both channel aliases to that same image, depending on the release type and the current `beta` version.\n\nThe workflow uses digest-only platform pushes and run-scoped `stage-\u003crun\u003e-\u003cattempt\u003e-*` tags in `sambee-staging`. Treat them as internal transport artifacts, not release candidates.\n\nCosign writes the signature artifact into a dedicated signature repository so the main `sambee` package page stays centered on deployable image versions.\nThat signature repository can still show both digest-derived signature tags and referenced untagged bundle manifests, which are part of Cosign's current storage model rather than extra preview image variants.\n\n## Retry Behavior\n\nBefore the late candidate marker is written, a failed run may be retried with the same `Z` version. The run uses a unique `stage-\u003crun\u003e-\u003cattempt\u003e-\u003cplatform\u003e` tag in `sambee-staging` and cleans up its staging versions after promotion or failure. That package can also contain untagged digest-only platform manifests. The Docker publication lock serializes candidate and maintenance cleanup, so the cleanup may delete the whole isolated package when every tagged version is a staging tag; GHCR requires that package-level operation when the last tagged version remains. Scheduled cleanup reclaims stale staging artifacts and unreferenced signature and metadata artifacts.\n\nAfter a valid candidate marker exists, a matching dispatch takes the repair-only path. It verifies the signed digest and restores only missing matching immutable aliases or the `test` pointer; it does not rebuild the image. A conflicting immutable marker requires incrementing `Z` and publishing a new candidate.\n\nGitHub Actions concurrency is mutual exclusion, not a FIFO queue: only one pending run is retained for the publication lock. Avoid stacking dispatches. A superseded pending dispatch is safe to submit again because it did not reach a publication step.\n\n## Security Scan Behavior\n\nThe preview workflow runs Trivy before publish.\n\nFor preview publishing, Trivy findings are advisory rather than blocking. That keeps the newest candidate available for testing while still surfacing risk clearly in the workflow output.\n\nThe preview scan runs against the same pushed platform digests that are later assembled into the published candidate index, so validation and publication use the same platform manifests.\n\nThose manifests use the same OS-package refresh policy, so the candidate that gets published is rebuilt against current Debian package metadata for that workflow run.\n\n## Metadata\n\nThe published image includes OCI labels for the source repository, source ref name, git revision, version, creation time, and license.\n\nThe workflow also generates `GIT_COMMIT` in CI before building because GitHub-hosted runners do not run the local git hooks that usually keep that file current. That keeps frontend and backend build metadata aligned inside the container image.\n", "2.0": "+++\ntitle = \"Build Docker Image\"\n+++\n\nThis is step 1 of the Docker release flow ([overview](../docker-release-overview/)).\n\nUse `Release: Create Docker Image` to build one immutable Docker candidate from `main`. It is the only workflow that builds and pushes a new Sambee image to GitHub Container Registry (GHCR).\n\nThe workflow reserves the annotated canonical Git tag `build-vX.Y.Z` for the committed, synchronized `VERSION` source. It does not publish a GitHub Release or move `stable` or `beta`.\n\n## Inputs\n\nThe workflow accepts only an optional existing candidate selector:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `build_version` | Reuse an existing immutable `X.Y.Z` candidate. | Leave empty for a new candidate. Use an existing value only to verify or repair its immutable aliases. |\n\nThe workflow rejects arbitrary source refs, source SHAs, and temporary version overrides. The checked-in, synchronized plain numeric `VERSION` is the only publishable version source.\n\n## Validation\n\nBefore it publishes anything, the workflow requires the following validation checks:\n\n- Backend type checks must pass.\n- Backend tests must pass.\n- Frontend type checks must pass.\n- Frontend tests must pass.\n- Each supported platform image must build, publish by digest, and start successfully.\n\nFor source checks, the workflow reuses successful backend and frontend jobs from `CI: Test` only when they ran on a push to `main` for the exact candidate commit. It checks each job separately. If a job was skipped, is still running, or its result cannot be verified, the release workflow runs that area's checks itself. PR checks alone do not qualify because they may test a different merge commit. Platform image builds and startup checks always run for a new candidate.\n\nThe workflow forces a fresh rebuild of the Dockerfile layer that installs Debian packages for that run. That keeps preview candidates aligned with the latest package fixes available from the Debian repositories at build time while still letting the rest of the image reuse BuildKit cache.\n\n## Published Output\n\nAfter validation, the workflow:\n\n1. Builds and pushes native `linux/amd64` and `linux/arm64` platform manifests to the internal `ghcr.io/\u003cowner\u003e/sambee-staging` repository.\n2. Starts those same images and waits for the health endpoint to succeed.\n3. Scans those same images with Trivy.\n4. Assembles the platform manifests into one multi-platform staging index and verifies its image labels.\n5. Extracts per-platform SBOM and provenance payloads on native runners, then assembles and publishes a metadata bundle that names the final `sambee` image identity under the digest-derived `.meta` tag in `ghcr.io/\u003cowner\u003e/sambee-signatures`.\n6. Signs and verifies the staging digest with Cosign using GitHub Actions OIDC.\n7. Copies the verified multi-platform index by digest to the immutable `sambee:build-vX.Y.Z` marker, then verifies the final image, metadata bundle, and signature again.\n8. Creates immutable `X.Y.Z` and `sha-\u003cfull-commit-sha\u003e` aliases and moves `test` to that same verified image.\n\nThe digest is the real artifact identity. The canonical `build-vX.Y.Z` tag is the candidate source of truth; `test` is only a moving alias.\n\nLater promotion may move `stable`, `beta`, or both channel aliases to that same image, depending on the release type and the current `beta` version.\n\nThe workflow uses digest-only platform pushes and run-scoped `stage-\u003crun\u003e-\u003cattempt\u003e-*` tags in `sambee-staging`. Treat them as internal transport artifacts, not release candidates.\n\nCosign writes the signature artifact into a dedicated signature repository so the main `sambee` package page stays centered on deployable image versions.\nThat signature repository can still show both digest-derived signature tags and referenced untagged bundle manifests, which are part of Cosign's current storage model rather than extra preview image variants.\n\n## Retry Behavior\n\nBefore the late candidate marker is written, a failed run may be retried with the same `Z` version. The run uses a unique `stage-\u003crun\u003e-\u003cattempt\u003e-\u003cplatform\u003e` tag in `sambee-staging` and cleans up its staging versions after promotion or failure. That package can also contain untagged digest-only platform manifests. The Docker publication lock serializes candidate and maintenance cleanup, so the cleanup may delete the whole isolated package when every tagged version is a staging tag; GHCR requires that package-level operation when the last tagged version remains. Scheduled cleanup reclaims stale staging artifacts and unreferenced signature and metadata artifacts.\n\nAfter a valid candidate marker exists, a matching dispatch takes the repair-only path. It verifies the signed digest and restores only missing matching immutable aliases or the `test` pointer; it does not rebuild the image. A conflicting immutable marker requires incrementing `Z` and publishing a new candidate.\n\nGitHub Actions concurrency is mutual exclusion, not a FIFO queue: only one pending run is retained for the publication lock. Avoid stacking dispatches. A superseded pending dispatch is safe to submit again because it did not reach a publication step.\n\n## Security Scan Behavior\n\nThe preview workflow runs Trivy before publish.\n\nFor preview publishing, Trivy findings are advisory rather than blocking. That keeps the newest candidate available for testing while still surfacing risk clearly in the workflow output.\n\nThe preview scan runs against the same pushed platform digests that are later assembled into the published candidate index, so validation and publication use the same platform manifests.\n\nThose manifests use the same OS-package refresh policy, so the candidate that gets published is rebuilt against current Debian package metadata for that workflow run.\n\n## Metadata\n\nThe published image includes OCI labels for the source repository, source ref name, git revision, version, creation time, and license.\n\nThe workflow also generates `GIT_COMMIT` in CI before building because GitHub-hosted runners do not run the local git hooks that usually keep that file current. That keeps frontend and backend build metadata aligned inside the container image.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/release-and-versioning/promote-docker-image", "parent_id": "section:developer-guide/release-and-versioning", "depth": 2, "kind": "page", "label": "promote-docker-image", "title": "Promote Docker Image", "path": "developer-guide/release-and-versioning/promote-docker-image", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "branched", "source_version": "0.7", "diff_added": 42, "diff_removed": 32}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "inherited", "source_version": "0.9"}}, "content_versions": {"0.7": "+++\ntitle = \"Promote Docker Image\"\n+++\n\nThis is step 2 of the Docker release flow.\n\nUse this `Release: Publish Docker Image` workflow to move the `beta` or `stable` tags to an existing Docker image, and to apply version tags to the image (stable releases only).\n\n## How To Trigger the Workflow\n\nUse this order:\n\n1. Identify the commit whose preview image you validated from the tag on the GHCR Docker image (`sha-\u003ccommit\u003e`).\n1. Create the release Git tag on that exact commit.\n1. Push the tag to GitHub.\n1. Publish the GitHub Release from that tag.\n\nFor example, if the approved commit is `89378a28b18ba6532571e62734a6a9aefac6c99a` and `VERSION` is `0.7.0`:\n\n### Beta Example\n\n```bash\ngit tag -a v0.7.0-beta.1 89378a28b18ba6532571e62734a6a9aefac6c99a -m \"Sambee 0.7.0 beta 1\"\ngit push origin v0.7.0-beta.1\n```\n\n### Stable Example\n\n```bash\ngit tag -a v0.7.0 89378a28b18ba6532571e62734a6a9aefac6c99a -m \"Sambee 0.7.0\"\ngit push origin v0.7.0\n```\n\nIn the GitHub web UI, create a release from the existing tag. Avoid the branch selection.\n\n## Validation\n\nBefore promotion, the workflow checks all of the following:\n\n1. Stable releases must use the tag `v$(cat VERSION)`. Prereleases must start with that same base version and add a prerelease suffix, for example `v0.8.0-beta.1`.\n1. The corresponding immutable preview candidate tag `sha-\u003cfull-commit-sha\u003e` exists in GitHub Container Registry.\n1. The candidate image labels match the expected revision, checked-in product version, and source repository.\n1. The preview-built SBOM and provenance metadata bundle exists under the expected digest-derived `.meta` tag and matches the candidate digest.\n\nIf any of those checks fail, promotion stops.\n\n## Published Tags\n\nStable releases publish:\n\n- The full version tag, such as `0.7.0`.\n- The moving minor-series tag, such as `0.7`.\n- The moving channel tag `stable`.\n- The moving channel tag `beta`, unless `beta` already points to a higher semver release.\n\nPrereleases publish:\n\n- The moving channel tag `beta`.\n\nThat stable-release `beta` catch-up rule uses standard semver precedence. Build metadata does not make a version newer for ordering purposes.\n\nAfter the tag-promotion steps finish, the workflow uploads `metadata.json`, `provenance/intoto.jsonl`, and the platform SPDX SBOM files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in `ghcr.io/\u003cowner\u003e/sambee-signatures` remains the canonical metadata bundle.\n\nThe workflow then signs the promoted digest with Cosign. That signing step covers the same image digest that was validated and promoted.\n\n## Why No Rebuild\n\nThis model avoids rebuilding at release time.\n\nThe image tested as a preview candidate is therefore the exact same image that later becomes `stable` or `beta`. The preview-generated SBOM and provenance bundle is also verified against that same digest during promotion.\n\n## Tag Contract\n\nDocker image promotion expects release tags to use the checked-in base version from `VERSION`.\n\nExamples:\n\n- `VERSION` contains `0.7.0`.\n- A stable Git tag and GitHub Release must be `v0.7.0`.\n- A prerelease Git tag and GitHub Release may be `v0.7.0-beta.1`.\n\nIf those values drift apart, promotion fails.\n", "0.8": "+++\ntitle = \"Promote Docker Image\"\n+++\n\nThis is step 2 of the Docker release flow.\n\nUse this `Release: Publish Docker Image` workflow to move the `beta` or `stable` tags to an existing Docker image, and to apply version tags to the image (stable releases only).\n\n## How To Trigger the Workflow\n\nUse this order:\n\n1. Identify the commit whose preview image you validated from the tag on the GHCR Docker image (`sha-\u003ccommit\u003e`).\n1. Create the release Git tag on that exact commit.\n1. Push the tag to GitHub.\n1. Publish the GitHub Release from that tag.\n\nFor example, if the approved commit is `89378a28b18ba6532571e62734a6a9aefac6c99a` and `VERSION` is `0.7.0`:\n\n### Beta Example\n\n```bash\ngit tag -a v0.7.0-beta.1 89378a28b18ba6532571e62734a6a9aefac6c99a -m \"Sambee 0.7.0 beta 1\"\ngit push origin v0.7.0-beta.1\n```\n\n### Stable Example\n\n```bash\ngit tag -a v0.7.0 89378a28b18ba6532571e62734a6a9aefac6c99a -m \"Sambee 0.7.0\"\ngit push origin v0.7.0\n```\n\nIn the GitHub web UI, create a release from the existing tag. Avoid the branch selection.\n\n## Validation\n\nBefore promotion, the workflow checks all of the following:\n\n1. Stable releases must use the tag `v$(cat VERSION)`. Prereleases must start with that same base version and add a prerelease suffix, for example `v0.8.0-beta.1`.\n1. The corresponding immutable preview candidate tag `sha-\u003cfull-commit-sha\u003e` exists in GitHub Container Registry.\n1. The candidate image labels match the expected revision, checked-in product version, and source repository.\n1. The preview-built SBOM and provenance metadata bundle exists under the expected digest-derived `.meta` tag and matches the candidate digest.\n\nIf any of those checks fail, promotion stops.\n\n## Published Tags\n\nStable releases publish:\n\n- The full version tag, such as `0.7.0`.\n- The moving minor-series tag, such as `0.7`.\n- The moving channel tag `stable`.\n- The moving channel tag `beta`, unless `beta` already points to a higher semver release.\n\nPrereleases publish:\n\n- The moving channel tag `beta`.\n\nThat stable-release `beta` catch-up rule uses standard semver precedence. Build metadata does not make a version newer for ordering purposes.\n\nAfter the tag-promotion steps finish, the workflow uploads `metadata.json`, `provenance/intoto.jsonl`, and the platform SPDX SBOM files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in `ghcr.io/\u003cowner\u003e/sambee-signatures` remains the canonical metadata bundle.\n\nThe workflow then signs the promoted digest with Cosign. That signing step covers the same image digest that was validated and promoted.\n\n## Why No Rebuild\n\nThis model avoids rebuilding at release time.\n\nThe image tested as a preview candidate is therefore the exact same image that later becomes `stable` or `beta`. The preview-generated SBOM and provenance bundle is also verified against that same digest during promotion.\n\n## Tag Contract\n\nDocker image promotion expects release tags to use the checked-in base version from `VERSION`.\n\nExamples:\n\n- `VERSION` contains `0.7.0`.\n- A stable Git tag and GitHub Release must be `v0.7.0`.\n- A prerelease Git tag and GitHub Release may be `v0.7.0-beta.1`.\n\nIf those values drift apart, promotion fails.\n", "0.9": "+++\ntitle = \"Promote Docker Image\"\n+++\n\nThis is step 2 of the Docker release flow ([overview](../docker-release-overview/)).\n\nUse this `Release: Publish Docker Image` workflow to move Docker channel pointers to an already signed, immutable build. It has separate beta and stable paths.\n\n## How To Trigger the Workflow\n\n### Promote Beta\n\nTo promote an approved candidate to `beta`, run the workflow manually from `main` and enter its canonical build version, `X.Y.Z`.\n\nThe workflow resolves and verifies `build-vX.Y.Z`, then moves only the `beta` pointer. It does not create a public Git tag or GitHub Release, move `stable`, or add a minor-series tag. Normal beta promotion never moves the channel to an older version.\n\n### Promote Stable\n\nUse this order to promote a candidate to `stable`:\n\n1. Identify the approved canonical build tag, `build-vX.Y.Z`.\n1. Create the public Git tag `vX.Y.Z` on that same commit.\n1. Add `sambee-release.json` to the draft public release with `schema_version`, `version`, `build_tag`, `source_sha`, and `component_scope`.\n1. Set `component_scope` to `docker` or `both`, then publish the GitHub Release.\n\nFor example, if the approved commit is `89378a28b18ba6532571e62734a6a9aefac6c99a` and `VERSION` is `0.7.0`:\n\n```bash\ngit tag -a v0.7.0 89378a28b18ba6532571e62734a6a9aefac6c99a -m \"Sambee 0.7.0\"\ngit push origin v0.7.0\n```\n\nIn the GitHub web UI, create a release from the existing tag. Avoid the branch selection.\n\n## Validation\n\n### Beta Validation\n\nBefore beta promotion, the workflow checks all of the following:\n\n1. The workflow was dispatched from `main` with a plain numeric `X.Y.Z` build version.\n1. The corresponding `build-v\u003cversion\u003e` Git tag exists, is reachable from `main`, and identifies a source whose checked-in `VERSION` matches the requested version.\n\n### Stable Validation\n\nBefore stable promotion, the workflow checks all of the following:\n\n1. The release tag is exactly `v$(cat VERSION)` and is not a prerelease.\n1. The corresponding `build-v\u003cversion\u003e` Git and GHCR markers identify the same source and image.\n1. `sambee-release.json` authorizes Docker or both components and matches the version, build tag, and source SHA.\n\n### Common Validation\n\nBoth promotion paths check all of the following:\n\n1. The candidate image labels match the expected revision, checked-in product version, and source repository.\n1. The preview-built SBOM and provenance metadata bundle exists under the expected digest-derived `.meta` tag and matches the candidate digest.\n1. The candidate digest has the expected Cosign signature from the preview-build workflow.\n\nIf any of those checks fail, promotion stops.\n\n## Published Tags\n\nBeta promotion moves only the `beta` pointer.\n\nStable promotion moves these mutable pointers:\n\n- The moving minor-series tag, such as `0.7`.\n- The moving channel tag `stable`.\n- The `beta` tag when it is absent or does not point to a higher version.\n\nThe exact `X.Y.Z`, source-SHA, and `build-vX.Y.Z` tags were created by the build workflow and are immutable.\n\nAfter the tag-promotion steps finish, the workflow uploads `metadata.json`, `provenance/intoto.jsonl`, and the platform SPDX SBOM files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in `ghcr.io/\u003cowner\u003e/sambee-signatures` remains the canonical metadata bundle.\n\nThe build workflow signs the digest with Cosign before it assigns immutable registry markers. Promotion only moves pointers after verifying that published artifact.\n\n## Why No Rebuild\n\nThis model avoids rebuilding at release time.\n\nThe image tested as a preview candidate is therefore the exact same image that later becomes `stable` or `beta`. The preview-generated SBOM and provenance bundle is also verified against that same image during promotion.\n\n## Tag Contract\n\nDocker image promotion expects a plain release tag matching the checked-in version from `VERSION`.\n\nExamples:\n\n- `VERSION` contains `0.7.0`.\n- A stable Git tag and GitHub Release must be `v0.7.0`.\nIf those values drift apart, promotion fails.\n", "1.0": "+++\ntitle = \"Promote Docker Image\"\n+++\n\nThis is step 2 of the Docker release flow ([overview](../docker-release-overview/)).\n\nUse this `Release: Publish Docker Image` workflow to move Docker channel pointers to an already signed, immutable build. It has separate beta and stable paths.\n\n## How To Trigger the Workflow\n\n### Promote Beta\n\nTo promote an approved candidate to `beta`, run the workflow manually from `main` and enter its canonical build version, `X.Y.Z`.\n\nThe workflow resolves and verifies `build-vX.Y.Z`, then moves only the `beta` pointer. It does not create a public Git tag or GitHub Release, move `stable`, or add a minor-series tag. Normal beta promotion never moves the channel to an older version.\n\n### Promote Stable\n\nUse this order to promote a candidate to `stable`:\n\n1. Identify the approved canonical build tag, `build-vX.Y.Z`.\n1. Create the public Git tag `vX.Y.Z` on that same commit.\n1. Add `sambee-release.json` to the draft public release with `schema_version`, `version`, `build_tag`, `source_sha`, and `component_scope`.\n1. Set `component_scope` to `docker` or `both`, then publish the GitHub Release.\n\nFor example, if the approved commit is `89378a28b18ba6532571e62734a6a9aefac6c99a` and `VERSION` is `0.7.0`:\n\n```bash\ngit tag -a v0.7.0 89378a28b18ba6532571e62734a6a9aefac6c99a -m \"Sambee 0.7.0\"\ngit push origin v0.7.0\n```\n\nIn the GitHub web UI, create a release from the existing tag. Avoid the branch selection.\n\n## Validation\n\n### Beta Validation\n\nBefore beta promotion, the workflow checks all of the following:\n\n1. The workflow was dispatched from `main` with a plain numeric `X.Y.Z` build version.\n1. The corresponding `build-v\u003cversion\u003e` Git tag exists, is reachable from `main`, and identifies a source whose checked-in `VERSION` matches the requested version.\n\n### Stable Validation\n\nBefore stable promotion, the workflow checks all of the following:\n\n1. The release tag is exactly `v$(cat VERSION)` and is not a prerelease.\n1. The corresponding `build-v\u003cversion\u003e` Git and GHCR markers identify the same source and image.\n1. `sambee-release.json` authorizes Docker or both components and matches the version, build tag, and source SHA.\n\n### Common Validation\n\nBoth promotion paths check all of the following:\n\n1. The candidate image labels match the expected revision, checked-in product version, and source repository.\n1. The preview-built SBOM and provenance metadata bundle exists under the expected digest-derived `.meta` tag and matches the candidate digest.\n1. The candidate digest has the expected Cosign signature from the preview-build workflow.\n\nIf any of those checks fail, promotion stops.\n\n## Published Tags\n\nBeta promotion moves only the `beta` pointer.\n\nStable promotion moves these mutable pointers:\n\n- The moving minor-series tag, such as `0.7`.\n- The moving channel tag `stable`.\n- The `beta` tag when it is absent or does not point to a higher version.\n\nThe exact `X.Y.Z`, source-SHA, and `build-vX.Y.Z` tags were created by the build workflow and are immutable.\n\nAfter the tag-promotion steps finish, the workflow uploads `metadata.json`, `provenance/intoto.jsonl`, and the platform SPDX SBOM files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in `ghcr.io/\u003cowner\u003e/sambee-signatures` remains the canonical metadata bundle.\n\nThe build workflow signs the digest with Cosign before it assigns immutable registry markers. Promotion only moves pointers after verifying that published artifact.\n\n## Why No Rebuild\n\nThis model avoids rebuilding at release time.\n\nThe image tested as a preview candidate is therefore the exact same image that later becomes `stable` or `beta`. The preview-generated SBOM and provenance bundle is also verified against that same image during promotion.\n\n## Tag Contract\n\nDocker image promotion expects a plain release tag matching the checked-in version from `VERSION`.\n\nExamples:\n\n- `VERSION` contains `0.7.0`.\n- A stable Git tag and GitHub Release must be `v0.7.0`.\nIf those values drift apart, promotion fails.\n", "2.0": "+++\ntitle = \"Promote Docker Image\"\n+++\n\nThis is step 2 of the Docker release flow ([overview](../docker-release-overview/)).\n\nUse this `Release: Publish Docker Image` workflow to move Docker channel pointers to an already signed, immutable build. It has separate beta and stable paths.\n\n## How To Trigger the Workflow\n\n### Promote Beta\n\nTo promote an approved candidate to `beta`, run the workflow manually from `main` and enter its canonical build version, `X.Y.Z`.\n\nThe workflow resolves and verifies `build-vX.Y.Z`, then moves only the `beta` pointer. It does not create a public Git tag or GitHub Release, move `stable`, or add a minor-series tag. Normal beta promotion never moves the channel to an older version.\n\n### Promote Stable\n\nUse this order to promote a candidate to `stable`:\n\n1. Identify the approved canonical build tag, `build-vX.Y.Z`.\n1. Create the public Git tag `vX.Y.Z` on that same commit.\n1. Add `sambee-release.json` to the draft public release with `schema_version`, `version`, `build_tag`, `source_sha`, and `component_scope`.\n1. Set `component_scope` to `docker` or `both`, then publish the GitHub Release.\n\nFor example, if the approved commit is `89378a28b18ba6532571e62734a6a9aefac6c99a` and `VERSION` is `0.7.0`:\n\n```bash\ngit tag -a v0.7.0 89378a28b18ba6532571e62734a6a9aefac6c99a -m \"Sambee 0.7.0\"\ngit push origin v0.7.0\n```\n\nIn the GitHub web UI, create a release from the existing tag. Avoid the branch selection.\n\n## Validation\n\n### Beta Validation\n\nBefore beta promotion, the workflow checks all of the following:\n\n1. The workflow was dispatched from `main` with a plain numeric `X.Y.Z` build version.\n1. The corresponding `build-v\u003cversion\u003e` Git tag exists, is reachable from `main`, and identifies a source whose checked-in `VERSION` matches the requested version.\n\n### Stable Validation\n\nBefore stable promotion, the workflow checks all of the following:\n\n1. The release tag is exactly `v$(cat VERSION)` and is not a prerelease.\n1. The corresponding `build-v\u003cversion\u003e` Git and GHCR markers identify the same source and image.\n1. `sambee-release.json` authorizes Docker or both components and matches the version, build tag, and source SHA.\n\n### Common Validation\n\nBoth promotion paths check all of the following:\n\n1. The candidate image labels match the expected revision, checked-in product version, and source repository.\n1. The preview-built SBOM and provenance metadata bundle exists under the expected digest-derived `.meta` tag and matches the candidate digest.\n1. The candidate digest has the expected Cosign signature from the preview-build workflow.\n\nIf any of those checks fail, promotion stops.\n\n## Published Tags\n\nBeta promotion moves only the `beta` pointer.\n\nStable promotion moves these mutable pointers:\n\n- The moving minor-series tag, such as `0.7`.\n- The moving channel tag `stable`.\n- The `beta` tag when it is absent or does not point to a higher version.\n\nThe exact `X.Y.Z`, source-SHA, and `build-vX.Y.Z` tags were created by the build workflow and are immutable.\n\nAfter the tag-promotion steps finish, the workflow uploads `metadata.json`, `provenance/intoto.jsonl`, and the platform SPDX SBOM files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in `ghcr.io/\u003cowner\u003e/sambee-signatures` remains the canonical metadata bundle.\n\nThe build workflow signs the digest with Cosign before it assigns immutable registry markers. Promotion only moves pointers after verifying that published artifact.\n\n## Why No Rebuild\n\nThis model avoids rebuilding at release time.\n\nThe image tested as a preview candidate is therefore the exact same image that later becomes `stable` or `beta`. The preview-generated SBOM and provenance bundle is also verified against that same image during promotion.\n\n## Tag Contract\n\nDocker image promotion expects a plain release tag matching the checked-in version from `VERSION`.\n\nExamples:\n\n- `VERSION` contains `0.7.0`.\n- A stable Git tag and GitHub Release must be `v0.7.0`.\nIf those values drift apart, promotion fails.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Promote Docker Image\"\n+++\n\nThis is step 2 of the Docker release flow.\n\nUse this `Release: Publish Docker Image` workflow to move the `beta` or `stable` tags to an existing Docker image, and to apply version tags to the image (stable releases only).\n\n## How To Trigger the Workflow\n\nUse this order:\n\n1. Identify the commit whose preview image you validated from the tag on the GHCR Docker image (`sha-\u003ccommit\u003e`).\n1. Create the release Git tag on that exact commit.\n1. Push the tag to GitHub.\n1. Publish the GitHub Release from that tag.\n\nFor example, if the approved commit is `89378a28b18ba6532571e62734a6a9aefac6c99a` and `VERSION` is `0.7.0`:\n\n### Beta Example\n\n```bash\ngit tag -a v0.7.0-beta.1 89378a28b18ba6532571e62734a6a9aefac6c99a -m \"Sambee 0.7.0 beta 1\"\ngit push origin v0.7.0-beta.1\n```\n\n### Stable Example\n\n```bash\ngit tag -a v0.7.0 89378a28b18ba6532571e62734a6a9aefac6c99a -m \"Sambee 0.7.0\"\ngit push origin v0.7.0\n```\n\nIn the GitHub web UI, create a release from the existing tag. Avoid the branch selection.\n\n## Validation\n\nBefore promotion, the workflow checks all of the following:\n\n1. Stable releases must use the tag `v$(cat VERSION)`. Prereleases must start with that same base version and add a prerelease suffix, for example `v0.8.0-beta.1`.\n1. The corresponding immutable preview candidate tag `sha-\u003cfull-commit-sha\u003e` exists in GitHub Container Registry.\n1. The candidate image labels match the expected revision, checked-in product version, and source repository.\n1. The preview-built SBOM and provenance metadata bundle exists under the expected digest-derived `.meta` tag and matches the candidate digest.\n\nIf any of those checks fail, promotion stops.\n\n## Published Tags\n\nStable releases publish:\n\n- The full version tag, such as `0.7.0`.\n- The moving minor-series tag, such as `0.7`.\n- The moving channel tag `stable`.\n- The moving channel tag `beta`, unless `beta` already points to a higher semver release.\n\nPrereleases publish:\n\n- The moving channel tag `beta`.\n\nThat stable-release `beta` catch-up rule uses standard semver precedence. Build metadata does not make a version newer for ordering purposes.\n\nAfter the tag-promotion steps finish, the workflow uploads `metadata.json`, `provenance/intoto.jsonl`, and the platform SPDX SBOM files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in `ghcr.io/\u003cowner\u003e/sambee-signatures` remains the canonical metadata bundle.\n\nThe workflow then signs the promoted digest with Cosign. That signing step covers the same image digest that was validated and promoted.\n\n## Why No Rebuild\n\nThis model avoids rebuilding at release time.\n\nThe image tested as a preview candidate is therefore the exact same image that later becomes `stable` or `beta`. The preview-generated SBOM and provenance bundle is also verified against that same digest during promotion.\n\n## Tag Contract\n\nDocker image promotion expects release tags to use the checked-in base version from `VERSION`.\n\nExamples:\n\n- `VERSION` contains `0.7.0`.\n- A stable Git tag and GitHub Release must be `v0.7.0`.\n- A prerelease Git tag and GitHub Release may be `v0.7.0-beta.1`.\n\nIf those values drift apart, promotion fails.\n", "0.8": "+++\ntitle = \"Promote Docker Image\"\n+++\n\nThis is step 2 of the Docker release flow.\n\nUse this `Release: Publish Docker Image` workflow to move the `beta` or `stable` tags to an existing Docker image, and to apply version tags to the image (stable releases only).\n\n## How To Trigger the Workflow\n\nUse this order:\n\n1. Identify the commit whose preview image you validated from the tag on the GHCR Docker image (`sha-\u003ccommit\u003e`).\n1. Create the release Git tag on that exact commit.\n1. Push the tag to GitHub.\n1. Publish the GitHub Release from that tag.\n\nFor example, if the approved commit is `89378a28b18ba6532571e62734a6a9aefac6c99a` and `VERSION` is `0.7.0`:\n\n### Beta Example\n\n```bash\ngit tag -a v0.7.0-beta.1 89378a28b18ba6532571e62734a6a9aefac6c99a -m \"Sambee 0.7.0 beta 1\"\ngit push origin v0.7.0-beta.1\n```\n\n### Stable Example\n\n```bash\ngit tag -a v0.7.0 89378a28b18ba6532571e62734a6a9aefac6c99a -m \"Sambee 0.7.0\"\ngit push origin v0.7.0\n```\n\nIn the GitHub web UI, create a release from the existing tag. Avoid the branch selection.\n\n## Validation\n\nBefore promotion, the workflow checks all of the following:\n\n1. Stable releases must use the tag `v$(cat VERSION)`. Prereleases must start with that same base version and add a prerelease suffix, for example `v0.8.0-beta.1`.\n1. The corresponding immutable preview candidate tag `sha-\u003cfull-commit-sha\u003e` exists in GitHub Container Registry.\n1. The candidate image labels match the expected revision, checked-in product version, and source repository.\n1. The preview-built SBOM and provenance metadata bundle exists under the expected digest-derived `.meta` tag and matches the candidate digest.\n\nIf any of those checks fail, promotion stops.\n\n## Published Tags\n\nStable releases publish:\n\n- The full version tag, such as `0.7.0`.\n- The moving minor-series tag, such as `0.7`.\n- The moving channel tag `stable`.\n- The moving channel tag `beta`, unless `beta` already points to a higher semver release.\n\nPrereleases publish:\n\n- The moving channel tag `beta`.\n\nThat stable-release `beta` catch-up rule uses standard semver precedence. Build metadata does not make a version newer for ordering purposes.\n\nAfter the tag-promotion steps finish, the workflow uploads `metadata.json`, `provenance/intoto.jsonl`, and the platform SPDX SBOM files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in `ghcr.io/\u003cowner\u003e/sambee-signatures` remains the canonical metadata bundle.\n\nThe workflow then signs the promoted digest with Cosign. That signing step covers the same image digest that was validated and promoted.\n\n## Why No Rebuild\n\nThis model avoids rebuilding at release time.\n\nThe image tested as a preview candidate is therefore the exact same image that later becomes `stable` or `beta`. The preview-generated SBOM and provenance bundle is also verified against that same digest during promotion.\n\n## Tag Contract\n\nDocker image promotion expects release tags to use the checked-in base version from `VERSION`.\n\nExamples:\n\n- `VERSION` contains `0.7.0`.\n- A stable Git tag and GitHub Release must be `v0.7.0`.\n- A prerelease Git tag and GitHub Release may be `v0.7.0-beta.1`.\n\nIf those values drift apart, promotion fails.\n", "0.9": "+++\ntitle = \"Promote Docker Image\"\n+++\n\nThis is step 2 of the Docker release flow ([overview](../docker-release-overview/)).\n\nUse this `Release: Publish Docker Image` workflow to move Docker channel pointers to an already signed, immutable build. It has separate beta and stable paths.\n\n## How To Trigger the Workflow\n\n### Promote Beta\n\nTo promote an approved candidate to `beta`, run the workflow manually from `main` and enter its canonical build version, `X.Y.Z`.\n\nThe workflow resolves and verifies `build-vX.Y.Z`, then moves only the `beta` pointer. It does not create a public Git tag or GitHub Release, move `stable`, or add a minor-series tag. Normal beta promotion never moves the channel to an older version.\n\n### Promote Stable\n\nUse this order to promote a candidate to `stable`:\n\n1. Identify the approved canonical build tag, `build-vX.Y.Z`.\n1. Create the public Git tag `vX.Y.Z` on that same commit.\n1. Add `sambee-release.json` to the draft public release with `schema_version`, `version`, `build_tag`, `source_sha`, and `component_scope`.\n1. Set `component_scope` to `docker` or `both`, then publish the GitHub Release.\n\nFor example, if the approved commit is `89378a28b18ba6532571e62734a6a9aefac6c99a` and `VERSION` is `0.7.0`:\n\n```bash\ngit tag -a v0.7.0 89378a28b18ba6532571e62734a6a9aefac6c99a -m \"Sambee 0.7.0\"\ngit push origin v0.7.0\n```\n\nIn the GitHub web UI, create a release from the existing tag. Avoid the branch selection.\n\n## Validation\n\n### Beta Validation\n\nBefore beta promotion, the workflow checks all of the following:\n\n1. The workflow was dispatched from `main` with a plain numeric `X.Y.Z` build version.\n1. The corresponding `build-v\u003cversion\u003e` Git tag exists, is reachable from `main`, and identifies a source whose checked-in `VERSION` matches the requested version.\n\n### Stable Validation\n\nBefore stable promotion, the workflow checks all of the following:\n\n1. The release tag is exactly `v$(cat VERSION)` and is not a prerelease.\n1. The corresponding `build-v\u003cversion\u003e` Git and GHCR markers identify the same source and image.\n1. `sambee-release.json` authorizes Docker or both components and matches the version, build tag, and source SHA.\n\n### Common Validation\n\nBoth promotion paths check all of the following:\n\n1. The candidate image labels match the expected revision, checked-in product version, and source repository.\n1. The preview-built SBOM and provenance metadata bundle exists under the expected digest-derived `.meta` tag and matches the candidate digest.\n1. The candidate digest has the expected Cosign signature from the preview-build workflow.\n\nIf any of those checks fail, promotion stops.\n\n## Published Tags\n\nBeta promotion moves only the `beta` pointer.\n\nStable promotion moves these mutable pointers:\n\n- The moving minor-series tag, such as `0.7`.\n- The moving channel tag `stable`.\n- The `beta` tag when it is absent or does not point to a higher version.\n\nThe exact `X.Y.Z`, source-SHA, and `build-vX.Y.Z` tags were created by the build workflow and are immutable.\n\nAfter the tag-promotion steps finish, the workflow uploads `metadata.json`, `provenance/intoto.jsonl`, and the platform SPDX SBOM files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in `ghcr.io/\u003cowner\u003e/sambee-signatures` remains the canonical metadata bundle.\n\nThe build workflow signs the digest with Cosign before it assigns immutable registry markers. Promotion only moves pointers after verifying that published artifact.\n\n## Why No Rebuild\n\nThis model avoids rebuilding at release time.\n\nThe image tested as a preview candidate is therefore the exact same image that later becomes `stable` or `beta`. The preview-generated SBOM and provenance bundle is also verified against that same image during promotion.\n\n## Tag Contract\n\nDocker image promotion expects a plain release tag matching the checked-in version from `VERSION`.\n\nExamples:\n\n- `VERSION` contains `0.7.0`.\n- A stable Git tag and GitHub Release must be `v0.7.0`.\nIf those values drift apart, promotion fails.\n", "1.0": "+++\ntitle = \"Promote Docker Image\"\n+++\n\nThis is step 2 of the Docker release flow ([overview](../docker-release-overview/)).\n\nUse this `Release: Publish Docker Image` workflow to move Docker channel pointers to an already signed, immutable build. It has separate beta and stable paths.\n\n## How To Trigger the Workflow\n\n### Promote Beta\n\nTo promote an approved candidate to `beta`, run the workflow manually from `main` and enter its canonical build version, `X.Y.Z`.\n\nThe workflow resolves and verifies `build-vX.Y.Z`, then moves only the `beta` pointer. It does not create a public Git tag or GitHub Release, move `stable`, or add a minor-series tag. Normal beta promotion never moves the channel to an older version.\n\n### Promote Stable\n\nUse this order to promote a candidate to `stable`:\n\n1. Identify the approved canonical build tag, `build-vX.Y.Z`.\n1. Create the public Git tag `vX.Y.Z` on that same commit.\n1. Add `sambee-release.json` to the draft public release with `schema_version`, `version`, `build_tag`, `source_sha`, and `component_scope`.\n1. Set `component_scope` to `docker` or `both`, then publish the GitHub Release.\n\nFor example, if the approved commit is `89378a28b18ba6532571e62734a6a9aefac6c99a` and `VERSION` is `0.7.0`:\n\n```bash\ngit tag -a v0.7.0 89378a28b18ba6532571e62734a6a9aefac6c99a -m \"Sambee 0.7.0\"\ngit push origin v0.7.0\n```\n\nIn the GitHub web UI, create a release from the existing tag. Avoid the branch selection.\n\n## Validation\n\n### Beta Validation\n\nBefore beta promotion, the workflow checks all of the following:\n\n1. The workflow was dispatched from `main` with a plain numeric `X.Y.Z` build version.\n1. The corresponding `build-v\u003cversion\u003e` Git tag exists, is reachable from `main`, and identifies a source whose checked-in `VERSION` matches the requested version.\n\n### Stable Validation\n\nBefore stable promotion, the workflow checks all of the following:\n\n1. The release tag is exactly `v$(cat VERSION)` and is not a prerelease.\n1. The corresponding `build-v\u003cversion\u003e` Git and GHCR markers identify the same source and image.\n1. `sambee-release.json` authorizes Docker or both components and matches the version, build tag, and source SHA.\n\n### Common Validation\n\nBoth promotion paths check all of the following:\n\n1. The candidate image labels match the expected revision, checked-in product version, and source repository.\n1. The preview-built SBOM and provenance metadata bundle exists under the expected digest-derived `.meta` tag and matches the candidate digest.\n1. The candidate digest has the expected Cosign signature from the preview-build workflow.\n\nIf any of those checks fail, promotion stops.\n\n## Published Tags\n\nBeta promotion moves only the `beta` pointer.\n\nStable promotion moves these mutable pointers:\n\n- The moving minor-series tag, such as `0.7`.\n- The moving channel tag `stable`.\n- The `beta` tag when it is absent or does not point to a higher version.\n\nThe exact `X.Y.Z`, source-SHA, and `build-vX.Y.Z` tags were created by the build workflow and are immutable.\n\nAfter the tag-promotion steps finish, the workflow uploads `metadata.json`, `provenance/intoto.jsonl`, and the platform SPDX SBOM files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in `ghcr.io/\u003cowner\u003e/sambee-signatures` remains the canonical metadata bundle.\n\nThe build workflow signs the digest with Cosign before it assigns immutable registry markers. Promotion only moves pointers after verifying that published artifact.\n\n## Why No Rebuild\n\nThis model avoids rebuilding at release time.\n\nThe image tested as a preview candidate is therefore the exact same image that later becomes `stable` or `beta`. The preview-generated SBOM and provenance bundle is also verified against that same image during promotion.\n\n## Tag Contract\n\nDocker image promotion expects a plain release tag matching the checked-in version from `VERSION`.\n\nExamples:\n\n- `VERSION` contains `0.7.0`.\n- A stable Git tag and GitHub Release must be `v0.7.0`.\nIf those values drift apart, promotion fails.\n", "2.0": "+++\ntitle = \"Promote Docker Image\"\n+++\n\nThis is step 2 of the Docker release flow ([overview](../docker-release-overview/)).\n\nUse this `Release: Publish Docker Image` workflow to move Docker channel pointers to an already signed, immutable build. It has separate beta and stable paths.\n\n## How To Trigger the Workflow\n\n### Promote Beta\n\nTo promote an approved candidate to `beta`, run the workflow manually from `main` and enter its canonical build version, `X.Y.Z`.\n\nThe workflow resolves and verifies `build-vX.Y.Z`, then moves only the `beta` pointer. It does not create a public Git tag or GitHub Release, move `stable`, or add a minor-series tag. Normal beta promotion never moves the channel to an older version.\n\n### Promote Stable\n\nUse this order to promote a candidate to `stable`:\n\n1. Identify the approved canonical build tag, `build-vX.Y.Z`.\n1. Create the public Git tag `vX.Y.Z` on that same commit.\n1. Add `sambee-release.json` to the draft public release with `schema_version`, `version`, `build_tag`, `source_sha`, and `component_scope`.\n1. Set `component_scope` to `docker` or `both`, then publish the GitHub Release.\n\nFor example, if the approved commit is `89378a28b18ba6532571e62734a6a9aefac6c99a` and `VERSION` is `0.7.0`:\n\n```bash\ngit tag -a v0.7.0 89378a28b18ba6532571e62734a6a9aefac6c99a -m \"Sambee 0.7.0\"\ngit push origin v0.7.0\n```\n\nIn the GitHub web UI, create a release from the existing tag. Avoid the branch selection.\n\n## Validation\n\n### Beta Validation\n\nBefore beta promotion, the workflow checks all of the following:\n\n1. The workflow was dispatched from `main` with a plain numeric `X.Y.Z` build version.\n1. The corresponding `build-v\u003cversion\u003e` Git tag exists, is reachable from `main`, and identifies a source whose checked-in `VERSION` matches the requested version.\n\n### Stable Validation\n\nBefore stable promotion, the workflow checks all of the following:\n\n1. The release tag is exactly `v$(cat VERSION)` and is not a prerelease.\n1. The corresponding `build-v\u003cversion\u003e` Git and GHCR markers identify the same source and image.\n1. `sambee-release.json` authorizes Docker or both components and matches the version, build tag, and source SHA.\n\n### Common Validation\n\nBoth promotion paths check all of the following:\n\n1. The candidate image labels match the expected revision, checked-in product version, and source repository.\n1. The preview-built SBOM and provenance metadata bundle exists under the expected digest-derived `.meta` tag and matches the candidate digest.\n1. The candidate digest has the expected Cosign signature from the preview-build workflow.\n\nIf any of those checks fail, promotion stops.\n\n## Published Tags\n\nBeta promotion moves only the `beta` pointer.\n\nStable promotion moves these mutable pointers:\n\n- The moving minor-series tag, such as `0.7`.\n- The moving channel tag `stable`.\n- The `beta` tag when it is absent or does not point to a higher version.\n\nThe exact `X.Y.Z`, source-SHA, and `build-vX.Y.Z` tags were created by the build workflow and are immutable.\n\nAfter the tag-promotion steps finish, the workflow uploads `metadata.json`, `provenance/intoto.jsonl`, and the platform SPDX SBOM files to the GitHub Release as convenience assets. The digest-derived `.meta` artifact in `ghcr.io/\u003cowner\u003e/sambee-signatures` remains the canonical metadata bundle.\n\nThe build workflow signs the digest with Cosign before it assigns immutable registry markers. Promotion only moves pointers after verifying that published artifact.\n\n## Why No Rebuild\n\nThis model avoids rebuilding at release time.\n\nThe image tested as a preview candidate is therefore the exact same image that later becomes `stable` or `beta`. The preview-generated SBOM and provenance bundle is also verified against that same image during promotion.\n\n## Tag Contract\n\nDocker image promotion expects a plain release tag matching the checked-in version from `VERSION`.\n\nExamples:\n\n- `VERSION` contains `0.7.0`.\n- A stable Git tag and GitHub Release must be `v0.7.0`.\nIf those values drift apart, promotion fails.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/release-and-versioning/docker-backfill-and-cleanup", "parent_id": "section:developer-guide/release-and-versioning", "depth": 2, "kind": "page", "label": "docker-backfill-and-cleanup", "title": "Docker Backfill And Cleanup", "path": "developer-guide/release-and-versioning/docker-backfill-and-cleanup", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Docker Backfill And Cleanup\"\n+++\n\nThis is the maintenance page for the Docker release flow.\n\nUse these maintenance workflows when you need to repair tags, backfill an older approved release, or keep preview history under control.\n\n## Summary\n\nUse this page when you are not publishing a new Docker image, but instead need to maintain existing release artifacts in GitHub Container Registry.\n\n| Workflow | What it does | Required input | Use it when... |\n|---|---|---|---|\n| `Maintenance: Backfill Docker Release Tags` | Reattaches release tags and channel aliases to an already approved digest and republishes missing metadata bundle assets when needed. | One existing Git tag in release form, such as `v0.7.0` or `v0.7.0-beta.1`. | A release already exists, but its GHCR tags or release assets are missing, wrong, or need to be reconstructed without building a new image. |\n| `Maintenance: Clean Up Docker Package Versions` | Deletes unprotected preview versions, stale signature artifacts, and unreferenced untagged GHCR package versions. | None. | Preview history and dangling GHCR artifacts have accumulated and you want the repository cleaned up without touching protected release artifacts. |\n\n## Backfill Docker Release Tags\n\nGitHub Actions displays the recovery workflow as `Maintenance: Backfill Docker Release Tags`.\n\n### What it does\n\nUse it to repair or reconstruct the publish side of an already approved Docker release without publishing a new runtime image.\n\nThe workflow:\n\n- resolves the digest that already belongs to the approved release\n- verifies image metadata\n- verifies the preview-built metadata bundle, generating and publishing it first if an older release does not have one yet\n- reapplies the expected release tags to that same digest\n- updates channel aliases with the same semver rules as normal promotion\n- uploads the metadata bundle files to the GitHub Release as convenience assets\n\nFor stable releases, that means backfill also moves `beta` forward unless `beta` already points to the same digest or to a higher semver release line.\n\n### Required input\n\nThe workflow takes one manual input:\n\n| Input | What it means | Required |\n|---|---|---|\n| `release_tag` | An existing immutable Git tag for the approved release, for example `v0.7.0` or `v0.7.0-beta.1`. The tag must match the checked-in `VERSION` value for that tagged commit. | Yes |\n\n### When to use it\n\nUse backfill in specific repair scenarios such as:\n\n- The GitHub Release exists, but the expected GHCR release tags were not attached.\n- A stable release was approved earlier, and you need to restore `stable`, version tags, or `beta` catch-up behavior to the correct existing digest.\n- A prerelease was approved earlier, and you need to restore the `beta` alias to the already approved digest.\n- A transient runner or registry failure interrupted release publication after the candidate image had already been built successfully.\n- An older approved release predates the current metadata-bundle flow, and you need to reconstruct the release assets without rebuilding the runtime image.\n\nDo not use backfill when you want to ship a new candidate commit. In that case, go back to [Build Docker Image](../build-docker-image/) and then [Promote Docker Image](../promote-docker-image/).\n\n### Tag requirements\n\nThe release tag can be either a stable tag such as `v0.7.0` or a prerelease tag such as `vX.Y.Z-beta.N`, as long as it matches the checked-in base `VERSION` for that release commit.\n\nWhen an older release does not have the new metadata bundle yet, backfill may create a local attested OCI export from the tagged source to recover SBOM and provenance files. That export is used only to publish the missing metadata bundle; the runtime image digest being promoted does not change.\n\nUse backfill only for already approved releases. It is not an alternate way to publish a new image.\n\n## Clean Up Docker Package Versions\n\nGitHub Actions displays the retention workflow as `Maintenance: Clean Up Docker Package Versions`.\n\n### What it does\n\nThis workflow removes disposable GHCR history while preserving artifacts that are still in use.\n\nIt:\n\n- deletes unprotected preview package versions\n- prunes stale metadata and Cosign signature artifacts\n- removes unreferenced untagged package versions\n- preserves release-tagged versions, protected channel aliases, and graph-referenced child manifests\n\n### Required input\n\nThis workflow has no manual inputs.\n\nIt runs automatically after successful preview publication, on a schedule, or manually when you want to force a cleanup pass.\n\n### When to use it\n\nUse cleanup in specific maintenance scenarios such as:\n\n- Preview publishing has created many old `sha-\u003cfull-commit-sha\u003e` versions that are no longer needed.\n- GHCR package pages have accumulated stale signature or metadata artifacts from deleted image digests.\n- You want to verify that retention behavior is working after changes to release-tagging or cleanup logic.\n- You want an immediate cleanup run instead of waiting for the next scheduled pass.\n\nDo not use cleanup to repair a missing release tag or channel alias. Use `Maintenance: Backfill Docker Release Tags` for that.\n\n### What cleanup preserves\n\nThis workflow periodically deletes unprotected preview and unreferenced GitHub Container Registry versions while preserving:\n\n- release-tagged versions.\n- `stable`, `beta`, `test`, and stable minor-series tags.\n\nThe moving `test` tag is protected like the other channel aliases.\nImmutable `sha-\u003cfull-commit-sha\u003e` preview tags are deleted when they are no longer protected by another retained tag.\nUntagged child manifests referenced by retained multi-platform indexes are protected before stale untagged versions are deleted.\nThe cleanup also prunes stale `ghcr.io/\u003cowner\u003e/sambee-signatures` metadata and Cosign signature tags after their corresponding `sambee` image digest is no longer retained.\nThe same reference-aware untagged cleanup runs for `sambee-signatures`, where it keeps Cosign signature bundle children referenced by retained signature indexes.\n\nThat keeps the `test` channel usable while aggressively removing disposable preview history.\n\n## Cleanup Rules\n\nUse this quick reference when deciding what the cleanup workflow will keep versus delete.\n\n| If a package version is... | Cleanup action |\n|---|---|\n| Tagged with a release tag, whether stable or prerelease | Keep |\n| Tagged with a protected channel or series tag such as `stable`, `beta`, `test`, or `0.7` | Keep |\n| Tagged only with an immutable preview tag such as `sha-\u003cfull-commit-sha\u003e` | Delete |\n| Untagged but still referenced by a retained multi-platform image index | Keep |\n| Untagged and not referenced by any retained index | Delete |\n| A signature or metadata artifact for a retained image digest | Keep |\n| A signature or metadata artifact for a deleted image digest | Delete |\n\nThere is no retention count anymore. The workflow deletes every package version that is not protected by tags or by graph references.\n\n## Examples\n\n- `ghcr.io/\u003cowner\u003e/sambee:test` stays because `test` is a protected channel tag.\n- `ghcr.io/\u003cowner\u003e/sambee:sha-\u003cfull-commit-sha\u003e` is deleted if that digest is not also kept by another protected tag.\n- An untagged platform manifest stays if a retained multi-platform index still points to it.\n- A stale `ghcr.io/\u003cowner\u003e/sambee-signatures` artifact is deleted after its corresponding image digest is no longer retained.\n\n## Boundaries\n\n- Do not publish a replacement runtime image in backfill. Recovery should point tags back at an existing digest.\n- Do not treat immutable `sha-\u003cfull-commit-sha\u003e` preview tags as permanent history. The cleanup workflow is expected to prune them.\n- Do not use moving tags such as `stable`, `beta`, or `test` as the only source of deployment truth when a digest is available.\n\nIf you are starting from a new candidate commit rather than repairing an existing release path, go back to [Build Docker Image](../build-docker-image/) or [Promote Docker Image](../promote-docker-image/).\n", "0.8": "+++\ntitle = \"Docker Backfill And Cleanup\"\n+++\n\nThis is the maintenance page for the Docker release flow.\n\nUse these maintenance workflows when you need to repair tags, backfill an older approved release, or keep preview history under control.\n\n## Summary\n\nUse this page when you are not publishing a new Docker image, but instead need to maintain existing release artifacts in GitHub Container Registry.\n\n| Workflow | What it does | Required input | Use it when... |\n|---|---|---|---|\n| `Maintenance: Backfill Docker Release Tags` | Reattaches release tags and channel aliases to an already approved digest and republishes missing metadata bundle assets when needed. | One existing Git tag in release form, such as `v0.7.0` or `v0.7.0-beta.1`. | A release already exists, but its GHCR tags or release assets are missing, wrong, or need to be reconstructed without building a new image. |\n| `Maintenance: Clean Up Docker Package Versions` | Deletes unprotected preview versions, stale signature artifacts, and unreferenced untagged GHCR package versions. | None. | Preview history and dangling GHCR artifacts have accumulated and you want the repository cleaned up without touching protected release artifacts. |\n\n## Backfill Docker Release Tags\n\nGitHub Actions displays the recovery workflow as `Maintenance: Backfill Docker Release Tags`.\n\n### What it does\n\nUse it to repair or reconstruct the publish side of an already approved Docker release without publishing a new runtime image.\n\nThe workflow:\n\n- resolves the digest that already belongs to the approved release\n- verifies image metadata\n- verifies the preview-built metadata bundle, generating and publishing it first if an older release does not have one yet\n- reapplies the expected release tags to that same digest\n- updates channel aliases with the same semver rules as normal promotion\n- uploads the metadata bundle files to the GitHub Release as convenience assets\n\nFor stable releases, that means backfill also moves `beta` forward unless `beta` already points to the same digest or to a higher semver release line.\n\n### Required input\n\nThe workflow takes one manual input:\n\n| Input | What it means | Required |\n|---|---|---|\n| `release_tag` | An existing immutable Git tag for the approved release, for example `v0.7.0` or `v0.7.0-beta.1`. The tag must match the checked-in `VERSION` value for that tagged commit. | Yes |\n\n### When to use it\n\nUse backfill in specific repair scenarios such as:\n\n- The GitHub Release exists, but the expected GHCR release tags were not attached.\n- A stable release was approved earlier, and you need to restore `stable`, version tags, or `beta` catch-up behavior to the correct existing digest.\n- A prerelease was approved earlier, and you need to restore the `beta` alias to the already approved digest.\n- A transient runner or registry failure interrupted release publication after the candidate image had already been built successfully.\n- An older approved release predates the current metadata-bundle flow, and you need to reconstruct the release assets without rebuilding the runtime image.\n\nDo not use backfill when you want to ship a new candidate commit. In that case, go back to [Build Docker Image](../build-docker-image/) and then [Promote Docker Image](../promote-docker-image/).\n\n### Tag requirements\n\nThe release tag can be either a stable tag such as `v0.7.0` or a prerelease tag such as `vX.Y.Z-beta.N`, as long as it matches the checked-in base `VERSION` for that release commit.\n\nWhen an older release does not have the new metadata bundle yet, backfill may create a local attested OCI export from the tagged source to recover SBOM and provenance files. That export is used only to publish the missing metadata bundle; the runtime image digest being promoted does not change.\n\nUse backfill only for already approved releases. It is not an alternate way to publish a new image.\n\n## Clean Up Docker Package Versions\n\nGitHub Actions displays the retention workflow as `Maintenance: Clean Up Docker Package Versions`.\n\n### What it does\n\nThis workflow removes disposable GHCR history while preserving artifacts that are still in use.\n\nIt:\n\n- deletes unprotected preview package versions\n- prunes stale metadata and Cosign signature artifacts\n- removes unreferenced untagged package versions\n- preserves release-tagged versions, protected channel aliases, and graph-referenced child manifests\n\n### Required input\n\nThis workflow has no manual inputs.\n\nIt runs automatically after successful preview publication, on a schedule, or manually when you want to force a cleanup pass.\n\n### When to use it\n\nUse cleanup in specific maintenance scenarios such as:\n\n- Preview publishing has created many old `sha-\u003cfull-commit-sha\u003e` versions that are no longer needed.\n- GHCR package pages have accumulated stale signature or metadata artifacts from deleted image digests.\n- You want to verify that retention behavior is working after changes to release-tagging or cleanup logic.\n- You want an immediate cleanup run instead of waiting for the next scheduled pass.\n\nDo not use cleanup to repair a missing release tag or channel alias. Use `Maintenance: Backfill Docker Release Tags` for that.\n\n### What cleanup preserves\n\nThis workflow periodically deletes unprotected preview and unreferenced GitHub Container Registry versions while preserving:\n\n- release-tagged versions.\n- `stable`, `beta`, `test`, and stable minor-series tags.\n\nThe moving `test` tag is protected like the other channel aliases.\nImmutable `sha-\u003cfull-commit-sha\u003e` preview tags are deleted when they are no longer protected by another retained tag.\nUntagged child manifests referenced by retained multi-platform indexes are protected before stale untagged versions are deleted.\nThe cleanup also prunes stale `ghcr.io/\u003cowner\u003e/sambee-signatures` metadata and Cosign signature tags after their corresponding `sambee` image digest is no longer retained.\nThe same reference-aware untagged cleanup runs for `sambee-signatures`, where it keeps Cosign signature bundle children referenced by retained signature indexes.\n\nThat keeps the `test` channel usable while aggressively removing disposable preview history.\n\n## Cleanup Rules\n\nUse this quick reference when deciding what the cleanup workflow will keep versus delete.\n\n| If a package version is... | Cleanup action |\n|---|---|\n| Tagged with a release tag, whether stable or prerelease | Keep |\n| Tagged with a protected channel or series tag such as `stable`, `beta`, `test`, or `0.7` | Keep |\n| Tagged only with an immutable preview tag such as `sha-\u003cfull-commit-sha\u003e` | Delete |\n| Untagged but still referenced by a retained multi-platform image index | Keep |\n| Untagged and not referenced by any retained index | Delete |\n| A signature or metadata artifact for a retained image digest | Keep |\n| A signature or metadata artifact for a deleted image digest | Delete |\n\nThere is no retention count anymore. The workflow deletes every package version that is not protected by tags or by graph references.\n\n## Examples\n\n- `ghcr.io/\u003cowner\u003e/sambee:test` stays because `test` is a protected channel tag.\n- `ghcr.io/\u003cowner\u003e/sambee:sha-\u003cfull-commit-sha\u003e` is deleted if that digest is not also kept by another protected tag.\n- An untagged platform manifest stays if a retained multi-platform index still points to it.\n- A stale `ghcr.io/\u003cowner\u003e/sambee-signatures` artifact is deleted after its corresponding image digest is no longer retained.\n\n## Boundaries\n\n- Do not publish a replacement runtime image in backfill. Recovery should point tags back at an existing digest.\n- Do not treat immutable `sha-\u003cfull-commit-sha\u003e` preview tags as permanent history. The cleanup workflow is expected to prune them.\n- Do not use moving tags such as `stable`, `beta`, or `test` as the only source of deployment truth when a digest is available.\n\nIf you are starting from a new candidate commit rather than repairing an existing release path, go back to [Build Docker Image](../build-docker-image/) or [Promote Docker Image](../promote-docker-image/).\n", "0.9": "+++\ntitle = \"Docker Backfill And Cleanup\"\n+++\n\nThis is the maintenance page for the Docker release flow.\n\nUse these maintenance workflows when you need to repair tags, backfill an older approved release, or keep preview history under control.\n\n## Summary\n\nUse this page when you are not publishing a new Docker image, but instead need to maintain existing release artifacts in GitHub Container Registry.\n\n| Workflow | What it does | Required input | Use it when... |\n|---|---|---|---|\n| `Maintenance: Backfill Docker Release Tags` | Reattaches release tags and channel aliases to an already approved digest and republishes missing metadata bundle assets when needed. | One existing Git tag in release form, such as `v0.7.0` or `v0.7.0-beta.1`. | A release already exists, but its GHCR tags or release assets are missing, wrong, or need to be reconstructed without building a new image. |\n| `Maintenance: Clean Up Docker Package Versions` | Deletes unprotected preview versions, stale signature artifacts, and unreferenced untagged GHCR package versions. | None. | Preview history and dangling GHCR artifacts have accumulated and you want the repository cleaned up without touching protected release artifacts. |\n\n## Backfill Docker Release Tags\n\nGitHub Actions displays the recovery workflow as `Maintenance: Backfill Docker Release Tags`.\n\n### What it does\n\nUse it to repair or reconstruct the publish side of an already approved Docker release without publishing a new runtime image.\n\nThe workflow:\n\n- resolves the digest that already belongs to the approved release\n- verifies image metadata\n- verifies the preview-built metadata bundle, generating and publishing it first if an older release does not have one yet\n- reapplies the expected release tags to that same digest\n- updates channel aliases with the same semver rules as normal promotion\n- uploads the metadata bundle files to the GitHub Release as convenience assets\n\nFor stable releases, that means backfill also moves `beta` forward unless `beta` already points to the same digest or to a higher semver release line.\n\n### Required input\n\nThe workflow takes one manual input:\n\n| Input | What it means | Required |\n|---|---|---|\n| `release_tag` | An existing immutable Git tag for the approved release, for example `v0.7.0` or `v0.7.0-beta.1`. The tag must match the checked-in `VERSION` value for that tagged commit. | Yes |\n\n### When to use it\n\nUse backfill in specific repair scenarios such as:\n\n- The GitHub Release exists, but the expected GHCR release tags were not attached.\n- A stable release was approved earlier, and you need to restore `stable`, version tags, or `beta` catch-up behavior to the correct existing digest.\n- A prerelease was approved earlier, and you need to restore the `beta` alias to the already approved digest.\n- A transient runner or registry failure interrupted release publication after the candidate image had already been built successfully.\n- An older approved release predates the current metadata-bundle flow, and you need to reconstruct the release assets without rebuilding the runtime image.\n\nDo not use backfill when you want to ship a new candidate commit. In that case, go back to [Build Docker Image](../build-docker-image/) and then [Promote Docker Image](../promote-docker-image/).\n\n### Tag requirements\n\nThe release tag can be either a stable tag such as `v0.7.0` or a prerelease tag such as `vX.Y.Z-beta.N`, as long as it matches the checked-in base `VERSION` for that release commit.\n\nWhen an older release does not have the new metadata bundle yet, backfill may create a local attested OCI export from the tagged source to recover SBOM and provenance files. That export is used only to publish the missing metadata bundle; the runtime image digest being promoted does not change.\n\nUse backfill only for already approved releases. It is not an alternate way to publish a new image.\n\n## Clean Up Docker Package Versions\n\nGitHub Actions displays the retention workflow as `Maintenance: Clean Up Docker Package Versions`.\n\n### What it does\n\nThis workflow removes disposable GHCR history while preserving artifacts that are still in use.\n\nIt:\n\n- deletes unprotected preview package versions\n- prunes stale metadata and Cosign signature artifacts\n- removes unreferenced untagged package versions\n- preserves release-tagged versions, protected channel aliases, and graph-referenced child manifests\n\n### Required input\n\nThis workflow has no manual inputs.\n\nIt runs automatically after successful preview publication, on a schedule, or manually when you want to force a cleanup pass.\n\n### When to use it\n\nUse cleanup in specific maintenance scenarios such as:\n\n- Preview publishing has created many old `sha-\u003cfull-commit-sha\u003e` versions that are no longer needed.\n- GHCR package pages have accumulated stale signature or metadata artifacts from deleted image digests.\n- You want to verify that retention behavior is working after changes to release-tagging or cleanup logic.\n- You want an immediate cleanup run instead of waiting for the next scheduled pass.\n\nDo not use cleanup to repair a missing release tag or channel alias. Use `Maintenance: Backfill Docker Release Tags` for that.\n\n### What cleanup preserves\n\nThis workflow periodically deletes unprotected preview and unreferenced GitHub Container Registry versions while preserving:\n\n- release-tagged versions.\n- `stable`, `beta`, `test`, and stable minor-series tags.\n\nThe moving `test` tag is protected like the other channel aliases.\nImmutable `sha-\u003cfull-commit-sha\u003e` preview tags are deleted when they are no longer protected by another retained tag.\nUntagged child manifests referenced by retained multi-platform indexes are protected before stale untagged versions are deleted.\nThe cleanup also prunes stale `ghcr.io/\u003cowner\u003e/sambee-signatures` metadata and Cosign signature tags after their corresponding `sambee` image digest is no longer retained.\nThe same reference-aware untagged cleanup runs for `sambee-signatures`, where it keeps Cosign signature bundle children referenced by retained signature indexes.\n\nThat keeps the `test` channel usable while aggressively removing disposable preview history.\n\n## Cleanup Rules\n\nUse this quick reference when deciding what the cleanup workflow will keep versus delete.\n\n| If a package version is... | Cleanup action |\n|---|---|\n| Tagged with a release tag, whether stable or prerelease | Keep |\n| Tagged with a protected channel or series tag such as `stable`, `beta`, `test`, or `0.7` | Keep |\n| Tagged only with an immutable preview tag such as `sha-\u003cfull-commit-sha\u003e` | Delete |\n| Untagged but still referenced by a retained multi-platform image index | Keep |\n| Untagged and not referenced by any retained index | Delete |\n| A signature or metadata artifact for a retained image digest | Keep |\n| A signature or metadata artifact for a deleted image digest | Delete |\n\nThere is no retention count anymore. The workflow deletes every package version that is not protected by tags or by graph references.\n\n## Examples\n\n- `ghcr.io/\u003cowner\u003e/sambee:test` stays because `test` is a protected channel tag.\n- `ghcr.io/\u003cowner\u003e/sambee:sha-\u003cfull-commit-sha\u003e` is deleted if that digest is not also kept by another protected tag.\n- An untagged platform manifest stays if a retained multi-platform index still points to it.\n- A stale `ghcr.io/\u003cowner\u003e/sambee-signatures` artifact is deleted after its corresponding image digest is no longer retained.\n\n## Boundaries\n\n- Do not publish a replacement runtime image in backfill. Recovery should point tags back at an existing digest.\n- Do not treat immutable `sha-\u003cfull-commit-sha\u003e` preview tags as permanent history. The cleanup workflow is expected to prune them.\n- Do not use moving tags such as `stable`, `beta`, or `test` as the only source of deployment truth when a digest is available.\n\nIf you are starting from a new candidate commit rather than repairing an existing release path, go back to [Build Docker Image](../build-docker-image/) or [Promote Docker Image](../promote-docker-image/).\n", "1.0": "+++\ntitle = \"Docker Backfill And Cleanup\"\n+++\n\nThis is the maintenance page for the Docker release flow.\n\nUse these maintenance workflows when you need to repair tags, backfill an older approved release, or keep preview history under control.\n\n## Summary\n\nUse this page when you are not publishing a new Docker image, but instead need to maintain existing release artifacts in GitHub Container Registry.\n\n| Workflow | What it does | Required input | Use it when... |\n|---|---|---|---|\n| `Maintenance: Backfill Docker Release Tags` | Reattaches release tags and channel aliases to an already approved digest and republishes missing metadata bundle assets when needed. | One existing Git tag in release form, such as `v0.7.0` or `v0.7.0-beta.1`. | A release already exists, but its GHCR tags or release assets are missing, wrong, or need to be reconstructed without building a new image. |\n| `Maintenance: Clean Up Docker Package Versions` | Deletes unprotected preview versions, stale signature artifacts, and unreferenced untagged GHCR package versions. | None. | Preview history and dangling GHCR artifacts have accumulated and you want the repository cleaned up without touching protected release artifacts. |\n\n## Backfill Docker Release Tags\n\nGitHub Actions displays the recovery workflow as `Maintenance: Backfill Docker Release Tags`.\n\n### What it does\n\nUse it to repair or reconstruct the publish side of an already approved Docker release without publishing a new runtime image.\n\nThe workflow:\n\n- resolves the digest that already belongs to the approved release\n- verifies image metadata\n- verifies the preview-built metadata bundle, generating and publishing it first if an older release does not have one yet\n- reapplies the expected release tags to that same digest\n- updates channel aliases with the same semver rules as normal promotion\n- uploads the metadata bundle files to the GitHub Release as convenience assets\n\nFor stable releases, that means backfill also moves `beta` forward unless `beta` already points to the same digest or to a higher semver release line.\n\n### Required input\n\nThe workflow takes one manual input:\n\n| Input | What it means | Required |\n|---|---|---|\n| `release_tag` | An existing immutable Git tag for the approved release, for example `v0.7.0` or `v0.7.0-beta.1`. The tag must match the checked-in `VERSION` value for that tagged commit. | Yes |\n\n### When to use it\n\nUse backfill in specific repair scenarios such as:\n\n- The GitHub Release exists, but the expected GHCR release tags were not attached.\n- A stable release was approved earlier, and you need to restore `stable`, version tags, or `beta` catch-up behavior to the correct existing digest.\n- A prerelease was approved earlier, and you need to restore the `beta` alias to the already approved digest.\n- A transient runner or registry failure interrupted release publication after the candidate image had already been built successfully.\n- An older approved release predates the current metadata-bundle flow, and you need to reconstruct the release assets without rebuilding the runtime image.\n\nDo not use backfill when you want to ship a new candidate commit. In that case, go back to [Build Docker Image](../build-docker-image/) and then [Promote Docker Image](../promote-docker-image/).\n\n### Tag requirements\n\nThe release tag can be either a stable tag such as `v0.7.0` or a prerelease tag such as `vX.Y.Z-beta.N`, as long as it matches the checked-in base `VERSION` for that release commit.\n\nWhen an older release does not have the new metadata bundle yet, backfill may create a local attested OCI export from the tagged source to recover SBOM and provenance files. That export is used only to publish the missing metadata bundle; the runtime image digest being promoted does not change.\n\nUse backfill only for already approved releases. It is not an alternate way to publish a new image.\n\n## Clean Up Docker Package Versions\n\nGitHub Actions displays the retention workflow as `Maintenance: Clean Up Docker Package Versions`.\n\n### What it does\n\nThis workflow removes disposable GHCR history while preserving artifacts that are still in use.\n\nIt:\n\n- deletes unprotected preview package versions\n- prunes stale metadata and Cosign signature artifacts\n- removes unreferenced untagged package versions\n- preserves release-tagged versions, protected channel aliases, and graph-referenced child manifests\n\n### Required input\n\nThis workflow has no manual inputs.\n\nIt runs automatically after successful preview publication, on a schedule, or manually when you want to force a cleanup pass.\n\n### When to use it\n\nUse cleanup in specific maintenance scenarios such as:\n\n- Preview publishing has created many old `sha-\u003cfull-commit-sha\u003e` versions that are no longer needed.\n- GHCR package pages have accumulated stale signature or metadata artifacts from deleted image digests.\n- You want to verify that retention behavior is working after changes to release-tagging or cleanup logic.\n- You want an immediate cleanup run instead of waiting for the next scheduled pass.\n\nDo not use cleanup to repair a missing release tag or channel alias. Use `Maintenance: Backfill Docker Release Tags` for that.\n\n### What cleanup preserves\n\nThis workflow periodically deletes unprotected preview and unreferenced GitHub Container Registry versions while preserving:\n\n- release-tagged versions.\n- `stable`, `beta`, `test`, and stable minor-series tags.\n\nThe moving `test` tag is protected like the other channel aliases.\nImmutable `sha-\u003cfull-commit-sha\u003e` preview tags are deleted when they are no longer protected by another retained tag.\nUntagged child manifests referenced by retained multi-platform indexes are protected before stale untagged versions are deleted.\nThe cleanup also prunes stale `ghcr.io/\u003cowner\u003e/sambee-signatures` metadata and Cosign signature tags after their corresponding `sambee` image digest is no longer retained.\nThe same reference-aware untagged cleanup runs for `sambee-signatures`, where it keeps Cosign signature bundle children referenced by retained signature indexes.\n\nThat keeps the `test` channel usable while aggressively removing disposable preview history.\n\n## Cleanup Rules\n\nUse this quick reference when deciding what the cleanup workflow will keep versus delete.\n\n| If a package version is... | Cleanup action |\n|---|---|\n| Tagged with a release tag, whether stable or prerelease | Keep |\n| Tagged with a protected channel or series tag such as `stable`, `beta`, `test`, or `0.7` | Keep |\n| Tagged only with an immutable preview tag such as `sha-\u003cfull-commit-sha\u003e` | Delete |\n| Untagged but still referenced by a retained multi-platform image index | Keep |\n| Untagged and not referenced by any retained index | Delete |\n| A signature or metadata artifact for a retained image digest | Keep |\n| A signature or metadata artifact for a deleted image digest | Delete |\n\nThere is no retention count anymore. The workflow deletes every package version that is not protected by tags or by graph references.\n\n## Examples\n\n- `ghcr.io/\u003cowner\u003e/sambee:test` stays because `test` is a protected channel tag.\n- `ghcr.io/\u003cowner\u003e/sambee:sha-\u003cfull-commit-sha\u003e` is deleted if that digest is not also kept by another protected tag.\n- An untagged platform manifest stays if a retained multi-platform index still points to it.\n- A stale `ghcr.io/\u003cowner\u003e/sambee-signatures` artifact is deleted after its corresponding image digest is no longer retained.\n\n## Boundaries\n\n- Do not publish a replacement runtime image in backfill. Recovery should point tags back at an existing digest.\n- Do not treat immutable `sha-\u003cfull-commit-sha\u003e` preview tags as permanent history. The cleanup workflow is expected to prune them.\n- Do not use moving tags such as `stable`, `beta`, or `test` as the only source of deployment truth when a digest is available.\n\nIf you are starting from a new candidate commit rather than repairing an existing release path, go back to [Build Docker Image](../build-docker-image/) or [Promote Docker Image](../promote-docker-image/).\n", "2.0": "+++\ntitle = \"Docker Backfill And Cleanup\"\n+++\n\nThis is the maintenance page for the Docker release flow.\n\nUse these maintenance workflows when you need to repair tags, backfill an older approved release, or keep preview history under control.\n\n## Summary\n\nUse this page when you are not publishing a new Docker image, but instead need to maintain existing release artifacts in GitHub Container Registry.\n\n| Workflow | What it does | Required input | Use it when... |\n|---|---|---|---|\n| `Maintenance: Backfill Docker Release Tags` | Reattaches release tags and channel aliases to an already approved digest and republishes missing metadata bundle assets when needed. | One existing Git tag in release form, such as `v0.7.0` or `v0.7.0-beta.1`. | A release already exists, but its GHCR tags or release assets are missing, wrong, or need to be reconstructed without building a new image. |\n| `Maintenance: Clean Up Docker Package Versions` | Deletes unprotected preview versions, stale signature artifacts, and unreferenced untagged GHCR package versions. | None. | Preview history and dangling GHCR artifacts have accumulated and you want the repository cleaned up without touching protected release artifacts. |\n\n## Backfill Docker Release Tags\n\nGitHub Actions displays the recovery workflow as `Maintenance: Backfill Docker Release Tags`.\n\n### What it does\n\nUse it to repair or reconstruct the publish side of an already approved Docker release without publishing a new runtime image.\n\nThe workflow:\n\n- resolves the digest that already belongs to the approved release\n- verifies image metadata\n- verifies the preview-built metadata bundle, generating and publishing it first if an older release does not have one yet\n- reapplies the expected release tags to that same digest\n- updates channel aliases with the same semver rules as normal promotion\n- uploads the metadata bundle files to the GitHub Release as convenience assets\n\nFor stable releases, that means backfill also moves `beta` forward unless `beta` already points to the same digest or to a higher semver release line.\n\n### Required input\n\nThe workflow takes one manual input:\n\n| Input | What it means | Required |\n|---|---|---|\n| `release_tag` | An existing immutable Git tag for the approved release, for example `v0.7.0` or `v0.7.0-beta.1`. The tag must match the checked-in `VERSION` value for that tagged commit. | Yes |\n\n### When to use it\n\nUse backfill in specific repair scenarios such as:\n\n- The GitHub Release exists, but the expected GHCR release tags were not attached.\n- A stable release was approved earlier, and you need to restore `stable`, version tags, or `beta` catch-up behavior to the correct existing digest.\n- A prerelease was approved earlier, and you need to restore the `beta` alias to the already approved digest.\n- A transient runner or registry failure interrupted release publication after the candidate image had already been built successfully.\n- An older approved release predates the current metadata-bundle flow, and you need to reconstruct the release assets without rebuilding the runtime image.\n\nDo not use backfill when you want to ship a new candidate commit. In that case, go back to [Build Docker Image](../build-docker-image/) and then [Promote Docker Image](../promote-docker-image/).\n\n### Tag requirements\n\nThe release tag can be either a stable tag such as `v0.7.0` or a prerelease tag such as `vX.Y.Z-beta.N`, as long as it matches the checked-in base `VERSION` for that release commit.\n\nWhen an older release does not have the new metadata bundle yet, backfill may create a local attested OCI export from the tagged source to recover SBOM and provenance files. That export is used only to publish the missing metadata bundle; the runtime image digest being promoted does not change.\n\nUse backfill only for already approved releases. It is not an alternate way to publish a new image.\n\n## Clean Up Docker Package Versions\n\nGitHub Actions displays the retention workflow as `Maintenance: Clean Up Docker Package Versions`.\n\n### What it does\n\nThis workflow removes disposable GHCR history while preserving artifacts that are still in use.\n\nIt:\n\n- deletes unprotected preview package versions\n- prunes stale metadata and Cosign signature artifacts\n- removes unreferenced untagged package versions\n- preserves release-tagged versions, protected channel aliases, and graph-referenced child manifests\n\n### Required input\n\nThis workflow has no manual inputs.\n\nIt runs automatically after successful preview publication, on a schedule, or manually when you want to force a cleanup pass.\n\n### When to use it\n\nUse cleanup in specific maintenance scenarios such as:\n\n- Preview publishing has created many old `sha-\u003cfull-commit-sha\u003e` versions that are no longer needed.\n- GHCR package pages have accumulated stale signature or metadata artifacts from deleted image digests.\n- You want to verify that retention behavior is working after changes to release-tagging or cleanup logic.\n- You want an immediate cleanup run instead of waiting for the next scheduled pass.\n\nDo not use cleanup to repair a missing release tag or channel alias. Use `Maintenance: Backfill Docker Release Tags` for that.\n\n### What cleanup preserves\n\nThis workflow periodically deletes unprotected preview and unreferenced GitHub Container Registry versions while preserving:\n\n- release-tagged versions.\n- `stable`, `beta`, `test`, and stable minor-series tags.\n\nThe moving `test` tag is protected like the other channel aliases.\nImmutable `sha-\u003cfull-commit-sha\u003e` preview tags are deleted when they are no longer protected by another retained tag.\nUntagged child manifests referenced by retained multi-platform indexes are protected before stale untagged versions are deleted.\nThe cleanup also prunes stale `ghcr.io/\u003cowner\u003e/sambee-signatures` metadata and Cosign signature tags after their corresponding `sambee` image digest is no longer retained.\nThe same reference-aware untagged cleanup runs for `sambee-signatures`, where it keeps Cosign signature bundle children referenced by retained signature indexes.\n\nThat keeps the `test` channel usable while aggressively removing disposable preview history.\n\n## Cleanup Rules\n\nUse this quick reference when deciding what the cleanup workflow will keep versus delete.\n\n| If a package version is... | Cleanup action |\n|---|---|\n| Tagged with a release tag, whether stable or prerelease | Keep |\n| Tagged with a protected channel or series tag such as `stable`, `beta`, `test`, or `0.7` | Keep |\n| Tagged only with an immutable preview tag such as `sha-\u003cfull-commit-sha\u003e` | Delete |\n| Untagged but still referenced by a retained multi-platform image index | Keep |\n| Untagged and not referenced by any retained index | Delete |\n| A signature or metadata artifact for a retained image digest | Keep |\n| A signature or metadata artifact for a deleted image digest | Delete |\n\nThere is no retention count anymore. The workflow deletes every package version that is not protected by tags or by graph references.\n\n## Examples\n\n- `ghcr.io/\u003cowner\u003e/sambee:test` stays because `test` is a protected channel tag.\n- `ghcr.io/\u003cowner\u003e/sambee:sha-\u003cfull-commit-sha\u003e` is deleted if that digest is not also kept by another protected tag.\n- An untagged platform manifest stays if a retained multi-platform index still points to it.\n- A stale `ghcr.io/\u003cowner\u003e/sambee-signatures` artifact is deleted after its corresponding image digest is no longer retained.\n\n## Boundaries\n\n- Do not publish a replacement runtime image in backfill. Recovery should point tags back at an existing digest.\n- Do not treat immutable `sha-\u003cfull-commit-sha\u003e` preview tags as permanent history. The cleanup workflow is expected to prune them.\n- Do not use moving tags such as `stable`, `beta`, or `test` as the only source of deployment truth when a digest is available.\n\nIf you are starting from a new candidate commit rather than repairing an existing release path, go back to [Build Docker Image](../build-docker-image/) or [Promote Docker Image](../promote-docker-image/).\n"}, "page_contents": {"0.7": "+++\ntitle = \"Docker Backfill And Cleanup\"\n+++\n\nThis is the maintenance page for the Docker release flow.\n\nUse these maintenance workflows when you need to repair tags, backfill an older approved release, or keep preview history under control.\n\n## Summary\n\nUse this page when you are not publishing a new Docker image, but instead need to maintain existing release artifacts in GitHub Container Registry.\n\n| Workflow | What it does | Required input | Use it when... |\n|---|---|---|---|\n| `Maintenance: Backfill Docker Release Tags` | Reattaches release tags and channel aliases to an already approved digest and republishes missing metadata bundle assets when needed. | One existing Git tag in release form, such as `v0.7.0` or `v0.7.0-beta.1`. | A release already exists, but its GHCR tags or release assets are missing, wrong, or need to be reconstructed without building a new image. |\n| `Maintenance: Clean Up Docker Package Versions` | Deletes unprotected preview versions, stale signature artifacts, and unreferenced untagged GHCR package versions. | None. | Preview history and dangling GHCR artifacts have accumulated and you want the repository cleaned up without touching protected release artifacts. |\n\n## Backfill Docker Release Tags\n\nGitHub Actions displays the recovery workflow as `Maintenance: Backfill Docker Release Tags`.\n\n### What it does\n\nUse it to repair or reconstruct the publish side of an already approved Docker release without publishing a new runtime image.\n\nThe workflow:\n\n- resolves the digest that already belongs to the approved release\n- verifies image metadata\n- verifies the preview-built metadata bundle, generating and publishing it first if an older release does not have one yet\n- reapplies the expected release tags to that same digest\n- updates channel aliases with the same semver rules as normal promotion\n- uploads the metadata bundle files to the GitHub Release as convenience assets\n\nFor stable releases, that means backfill also moves `beta` forward unless `beta` already points to the same digest or to a higher semver release line.\n\n### Required input\n\nThe workflow takes one manual input:\n\n| Input | What it means | Required |\n|---|---|---|\n| `release_tag` | An existing immutable Git tag for the approved release, for example `v0.7.0` or `v0.7.0-beta.1`. The tag must match the checked-in `VERSION` value for that tagged commit. | Yes |\n\n### When to use it\n\nUse backfill in specific repair scenarios such as:\n\n- The GitHub Release exists, but the expected GHCR release tags were not attached.\n- A stable release was approved earlier, and you need to restore `stable`, version tags, or `beta` catch-up behavior to the correct existing digest.\n- A prerelease was approved earlier, and you need to restore the `beta` alias to the already approved digest.\n- A transient runner or registry failure interrupted release publication after the candidate image had already been built successfully.\n- An older approved release predates the current metadata-bundle flow, and you need to reconstruct the release assets without rebuilding the runtime image.\n\nDo not use backfill when you want to ship a new candidate commit. In that case, go back to [Build Docker Image](../build-docker-image/) and then [Promote Docker Image](../promote-docker-image/).\n\n### Tag requirements\n\nThe release tag can be either a stable tag such as `v0.7.0` or a prerelease tag such as `vX.Y.Z-beta.N`, as long as it matches the checked-in base `VERSION` for that release commit.\n\nWhen an older release does not have the new metadata bundle yet, backfill may create a local attested OCI export from the tagged source to recover SBOM and provenance files. That export is used only to publish the missing metadata bundle; the runtime image digest being promoted does not change.\n\nUse backfill only for already approved releases. It is not an alternate way to publish a new image.\n\n## Clean Up Docker Package Versions\n\nGitHub Actions displays the retention workflow as `Maintenance: Clean Up Docker Package Versions`.\n\n### What it does\n\nThis workflow removes disposable GHCR history while preserving artifacts that are still in use.\n\nIt:\n\n- deletes unprotected preview package versions\n- prunes stale metadata and Cosign signature artifacts\n- removes unreferenced untagged package versions\n- preserves release-tagged versions, protected channel aliases, and graph-referenced child manifests\n\n### Required input\n\nThis workflow has no manual inputs.\n\nIt runs automatically after successful preview publication, on a schedule, or manually when you want to force a cleanup pass.\n\n### When to use it\n\nUse cleanup in specific maintenance scenarios such as:\n\n- Preview publishing has created many old `sha-\u003cfull-commit-sha\u003e` versions that are no longer needed.\n- GHCR package pages have accumulated stale signature or metadata artifacts from deleted image digests.\n- You want to verify that retention behavior is working after changes to release-tagging or cleanup logic.\n- You want an immediate cleanup run instead of waiting for the next scheduled pass.\n\nDo not use cleanup to repair a missing release tag or channel alias. Use `Maintenance: Backfill Docker Release Tags` for that.\n\n### What cleanup preserves\n\nThis workflow periodically deletes unprotected preview and unreferenced GitHub Container Registry versions while preserving:\n\n- release-tagged versions.\n- `stable`, `beta`, `test`, and stable minor-series tags.\n\nThe moving `test` tag is protected like the other channel aliases.\nImmutable `sha-\u003cfull-commit-sha\u003e` preview tags are deleted when they are no longer protected by another retained tag.\nUntagged child manifests referenced by retained multi-platform indexes are protected before stale untagged versions are deleted.\nThe cleanup also prunes stale `ghcr.io/\u003cowner\u003e/sambee-signatures` metadata and Cosign signature tags after their corresponding `sambee` image digest is no longer retained.\nThe same reference-aware untagged cleanup runs for `sambee-signatures`, where it keeps Cosign signature bundle children referenced by retained signature indexes.\n\nThat keeps the `test` channel usable while aggressively removing disposable preview history.\n\n## Cleanup Rules\n\nUse this quick reference when deciding what the cleanup workflow will keep versus delete.\n\n| If a package version is... | Cleanup action |\n|---|---|\n| Tagged with a release tag, whether stable or prerelease | Keep |\n| Tagged with a protected channel or series tag such as `stable`, `beta`, `test`, or `0.7` | Keep |\n| Tagged only with an immutable preview tag such as `sha-\u003cfull-commit-sha\u003e` | Delete |\n| Untagged but still referenced by a retained multi-platform image index | Keep |\n| Untagged and not referenced by any retained index | Delete |\n| A signature or metadata artifact for a retained image digest | Keep |\n| A signature or metadata artifact for a deleted image digest | Delete |\n\nThere is no retention count anymore. The workflow deletes every package version that is not protected by tags or by graph references.\n\n## Examples\n\n- `ghcr.io/\u003cowner\u003e/sambee:test` stays because `test` is a protected channel tag.\n- `ghcr.io/\u003cowner\u003e/sambee:sha-\u003cfull-commit-sha\u003e` is deleted if that digest is not also kept by another protected tag.\n- An untagged platform manifest stays if a retained multi-platform index still points to it.\n- A stale `ghcr.io/\u003cowner\u003e/sambee-signatures` artifact is deleted after its corresponding image digest is no longer retained.\n\n## Boundaries\n\n- Do not publish a replacement runtime image in backfill. Recovery should point tags back at an existing digest.\n- Do not treat immutable `sha-\u003cfull-commit-sha\u003e` preview tags as permanent history. The cleanup workflow is expected to prune them.\n- Do not use moving tags such as `stable`, `beta`, or `test` as the only source of deployment truth when a digest is available.\n\nIf you are starting from a new candidate commit rather than repairing an existing release path, go back to [Build Docker Image](../build-docker-image/) or [Promote Docker Image](../promote-docker-image/).\n", "0.8": "+++\ntitle = \"Docker Backfill And Cleanup\"\n+++\n\nThis is the maintenance page for the Docker release flow.\n\nUse these maintenance workflows when you need to repair tags, backfill an older approved release, or keep preview history under control.\n\n## Summary\n\nUse this page when you are not publishing a new Docker image, but instead need to maintain existing release artifacts in GitHub Container Registry.\n\n| Workflow | What it does | Required input | Use it when... |\n|---|---|---|---|\n| `Maintenance: Backfill Docker Release Tags` | Reattaches release tags and channel aliases to an already approved digest and republishes missing metadata bundle assets when needed. | One existing Git tag in release form, such as `v0.7.0` or `v0.7.0-beta.1`. | A release already exists, but its GHCR tags or release assets are missing, wrong, or need to be reconstructed without building a new image. |\n| `Maintenance: Clean Up Docker Package Versions` | Deletes unprotected preview versions, stale signature artifacts, and unreferenced untagged GHCR package versions. | None. | Preview history and dangling GHCR artifacts have accumulated and you want the repository cleaned up without touching protected release artifacts. |\n\n## Backfill Docker Release Tags\n\nGitHub Actions displays the recovery workflow as `Maintenance: Backfill Docker Release Tags`.\n\n### What it does\n\nUse it to repair or reconstruct the publish side of an already approved Docker release without publishing a new runtime image.\n\nThe workflow:\n\n- resolves the digest that already belongs to the approved release\n- verifies image metadata\n- verifies the preview-built metadata bundle, generating and publishing it first if an older release does not have one yet\n- reapplies the expected release tags to that same digest\n- updates channel aliases with the same semver rules as normal promotion\n- uploads the metadata bundle files to the GitHub Release as convenience assets\n\nFor stable releases, that means backfill also moves `beta` forward unless `beta` already points to the same digest or to a higher semver release line.\n\n### Required input\n\nThe workflow takes one manual input:\n\n| Input | What it means | Required |\n|---|---|---|\n| `release_tag` | An existing immutable Git tag for the approved release, for example `v0.7.0` or `v0.7.0-beta.1`. The tag must match the checked-in `VERSION` value for that tagged commit. | Yes |\n\n### When to use it\n\nUse backfill in specific repair scenarios such as:\n\n- The GitHub Release exists, but the expected GHCR release tags were not attached.\n- A stable release was approved earlier, and you need to restore `stable`, version tags, or `beta` catch-up behavior to the correct existing digest.\n- A prerelease was approved earlier, and you need to restore the `beta` alias to the already approved digest.\n- A transient runner or registry failure interrupted release publication after the candidate image had already been built successfully.\n- An older approved release predates the current metadata-bundle flow, and you need to reconstruct the release assets without rebuilding the runtime image.\n\nDo not use backfill when you want to ship a new candidate commit. In that case, go back to [Build Docker Image](../build-docker-image/) and then [Promote Docker Image](../promote-docker-image/).\n\n### Tag requirements\n\nThe release tag can be either a stable tag such as `v0.7.0` or a prerelease tag such as `vX.Y.Z-beta.N`, as long as it matches the checked-in base `VERSION` for that release commit.\n\nWhen an older release does not have the new metadata bundle yet, backfill may create a local attested OCI export from the tagged source to recover SBOM and provenance files. That export is used only to publish the missing metadata bundle; the runtime image digest being promoted does not change.\n\nUse backfill only for already approved releases. It is not an alternate way to publish a new image.\n\n## Clean Up Docker Package Versions\n\nGitHub Actions displays the retention workflow as `Maintenance: Clean Up Docker Package Versions`.\n\n### What it does\n\nThis workflow removes disposable GHCR history while preserving artifacts that are still in use.\n\nIt:\n\n- deletes unprotected preview package versions\n- prunes stale metadata and Cosign signature artifacts\n- removes unreferenced untagged package versions\n- preserves release-tagged versions, protected channel aliases, and graph-referenced child manifests\n\n### Required input\n\nThis workflow has no manual inputs.\n\nIt runs automatically after successful preview publication, on a schedule, or manually when you want to force a cleanup pass.\n\n### When to use it\n\nUse cleanup in specific maintenance scenarios such as:\n\n- Preview publishing has created many old `sha-\u003cfull-commit-sha\u003e` versions that are no longer needed.\n- GHCR package pages have accumulated stale signature or metadata artifacts from deleted image digests.\n- You want to verify that retention behavior is working after changes to release-tagging or cleanup logic.\n- You want an immediate cleanup run instead of waiting for the next scheduled pass.\n\nDo not use cleanup to repair a missing release tag or channel alias. Use `Maintenance: Backfill Docker Release Tags` for that.\n\n### What cleanup preserves\n\nThis workflow periodically deletes unprotected preview and unreferenced GitHub Container Registry versions while preserving:\n\n- release-tagged versions.\n- `stable`, `beta`, `test`, and stable minor-series tags.\n\nThe moving `test` tag is protected like the other channel aliases.\nImmutable `sha-\u003cfull-commit-sha\u003e` preview tags are deleted when they are no longer protected by another retained tag.\nUntagged child manifests referenced by retained multi-platform indexes are protected before stale untagged versions are deleted.\nThe cleanup also prunes stale `ghcr.io/\u003cowner\u003e/sambee-signatures` metadata and Cosign signature tags after their corresponding `sambee` image digest is no longer retained.\nThe same reference-aware untagged cleanup runs for `sambee-signatures`, where it keeps Cosign signature bundle children referenced by retained signature indexes.\n\nThat keeps the `test` channel usable while aggressively removing disposable preview history.\n\n## Cleanup Rules\n\nUse this quick reference when deciding what the cleanup workflow will keep versus delete.\n\n| If a package version is... | Cleanup action |\n|---|---|\n| Tagged with a release tag, whether stable or prerelease | Keep |\n| Tagged with a protected channel or series tag such as `stable`, `beta`, `test`, or `0.7` | Keep |\n| Tagged only with an immutable preview tag such as `sha-\u003cfull-commit-sha\u003e` | Delete |\n| Untagged but still referenced by a retained multi-platform image index | Keep |\n| Untagged and not referenced by any retained index | Delete |\n| A signature or metadata artifact for a retained image digest | Keep |\n| A signature or metadata artifact for a deleted image digest | Delete |\n\nThere is no retention count anymore. The workflow deletes every package version that is not protected by tags or by graph references.\n\n## Examples\n\n- `ghcr.io/\u003cowner\u003e/sambee:test` stays because `test` is a protected channel tag.\n- `ghcr.io/\u003cowner\u003e/sambee:sha-\u003cfull-commit-sha\u003e` is deleted if that digest is not also kept by another protected tag.\n- An untagged platform manifest stays if a retained multi-platform index still points to it.\n- A stale `ghcr.io/\u003cowner\u003e/sambee-signatures` artifact is deleted after its corresponding image digest is no longer retained.\n\n## Boundaries\n\n- Do not publish a replacement runtime image in backfill. Recovery should point tags back at an existing digest.\n- Do not treat immutable `sha-\u003cfull-commit-sha\u003e` preview tags as permanent history. The cleanup workflow is expected to prune them.\n- Do not use moving tags such as `stable`, `beta`, or `test` as the only source of deployment truth when a digest is available.\n\nIf you are starting from a new candidate commit rather than repairing an existing release path, go back to [Build Docker Image](../build-docker-image/) or [Promote Docker Image](../promote-docker-image/).\n", "0.9": "+++\ntitle = \"Docker Backfill And Cleanup\"\n+++\n\nThis is the maintenance page for the Docker release flow.\n\nUse these maintenance workflows when you need to repair tags, backfill an older approved release, or keep preview history under control.\n\n## Summary\n\nUse this page when you are not publishing a new Docker image, but instead need to maintain existing release artifacts in GitHub Container Registry.\n\n| Workflow | What it does | Required input | Use it when... |\n|---|---|---|---|\n| `Maintenance: Backfill Docker Release Tags` | Reattaches release tags and channel aliases to an already approved digest and republishes missing metadata bundle assets when needed. | One existing Git tag in release form, such as `v0.7.0` or `v0.7.0-beta.1`. | A release already exists, but its GHCR tags or release assets are missing, wrong, or need to be reconstructed without building a new image. |\n| `Maintenance: Clean Up Docker Package Versions` | Deletes unprotected preview versions, stale signature artifacts, and unreferenced untagged GHCR package versions. | None. | Preview history and dangling GHCR artifacts have accumulated and you want the repository cleaned up without touching protected release artifacts. |\n\n## Backfill Docker Release Tags\n\nGitHub Actions displays the recovery workflow as `Maintenance: Backfill Docker Release Tags`.\n\n### What it does\n\nUse it to repair or reconstruct the publish side of an already approved Docker release without publishing a new runtime image.\n\nThe workflow:\n\n- resolves the digest that already belongs to the approved release\n- verifies image metadata\n- verifies the preview-built metadata bundle, generating and publishing it first if an older release does not have one yet\n- reapplies the expected release tags to that same digest\n- updates channel aliases with the same semver rules as normal promotion\n- uploads the metadata bundle files to the GitHub Release as convenience assets\n\nFor stable releases, that means backfill also moves `beta` forward unless `beta` already points to the same digest or to a higher semver release line.\n\n### Required input\n\nThe workflow takes one manual input:\n\n| Input | What it means | Required |\n|---|---|---|\n| `release_tag` | An existing immutable Git tag for the approved release, for example `v0.7.0` or `v0.7.0-beta.1`. The tag must match the checked-in `VERSION` value for that tagged commit. | Yes |\n\n### When to use it\n\nUse backfill in specific repair scenarios such as:\n\n- The GitHub Release exists, but the expected GHCR release tags were not attached.\n- A stable release was approved earlier, and you need to restore `stable`, version tags, or `beta` catch-up behavior to the correct existing digest.\n- A prerelease was approved earlier, and you need to restore the `beta` alias to the already approved digest.\n- A transient runner or registry failure interrupted release publication after the candidate image had already been built successfully.\n- An older approved release predates the current metadata-bundle flow, and you need to reconstruct the release assets without rebuilding the runtime image.\n\nDo not use backfill when you want to ship a new candidate commit. In that case, go back to [Build Docker Image](../build-docker-image/) and then [Promote Docker Image](../promote-docker-image/).\n\n### Tag requirements\n\nThe release tag can be either a stable tag such as `v0.7.0` or a prerelease tag such as `vX.Y.Z-beta.N`, as long as it matches the checked-in base `VERSION` for that release commit.\n\nWhen an older release does not have the new metadata bundle yet, backfill may create a local attested OCI export from the tagged source to recover SBOM and provenance files. That export is used only to publish the missing metadata bundle; the runtime image digest being promoted does not change.\n\nUse backfill only for already approved releases. It is not an alternate way to publish a new image.\n\n## Clean Up Docker Package Versions\n\nGitHub Actions displays the retention workflow as `Maintenance: Clean Up Docker Package Versions`.\n\n### What it does\n\nThis workflow removes disposable GHCR history while preserving artifacts that are still in use.\n\nIt:\n\n- deletes unprotected preview package versions\n- prunes stale metadata and Cosign signature artifacts\n- removes unreferenced untagged package versions\n- preserves release-tagged versions, protected channel aliases, and graph-referenced child manifests\n\n### Required input\n\nThis workflow has no manual inputs.\n\nIt runs automatically after successful preview publication, on a schedule, or manually when you want to force a cleanup pass.\n\n### When to use it\n\nUse cleanup in specific maintenance scenarios such as:\n\n- Preview publishing has created many old `sha-\u003cfull-commit-sha\u003e` versions that are no longer needed.\n- GHCR package pages have accumulated stale signature or metadata artifacts from deleted image digests.\n- You want to verify that retention behavior is working after changes to release-tagging or cleanup logic.\n- You want an immediate cleanup run instead of waiting for the next scheduled pass.\n\nDo not use cleanup to repair a missing release tag or channel alias. Use `Maintenance: Backfill Docker Release Tags` for that.\n\n### What cleanup preserves\n\nThis workflow periodically deletes unprotected preview and unreferenced GitHub Container Registry versions while preserving:\n\n- release-tagged versions.\n- `stable`, `beta`, `test`, and stable minor-series tags.\n\nThe moving `test` tag is protected like the other channel aliases.\nImmutable `sha-\u003cfull-commit-sha\u003e` preview tags are deleted when they are no longer protected by another retained tag.\nUntagged child manifests referenced by retained multi-platform indexes are protected before stale untagged versions are deleted.\nThe cleanup also prunes stale `ghcr.io/\u003cowner\u003e/sambee-signatures` metadata and Cosign signature tags after their corresponding `sambee` image digest is no longer retained.\nThe same reference-aware untagged cleanup runs for `sambee-signatures`, where it keeps Cosign signature bundle children referenced by retained signature indexes.\n\nThat keeps the `test` channel usable while aggressively removing disposable preview history.\n\n## Cleanup Rules\n\nUse this quick reference when deciding what the cleanup workflow will keep versus delete.\n\n| If a package version is... | Cleanup action |\n|---|---|\n| Tagged with a release tag, whether stable or prerelease | Keep |\n| Tagged with a protected channel or series tag such as `stable`, `beta`, `test`, or `0.7` | Keep |\n| Tagged only with an immutable preview tag such as `sha-\u003cfull-commit-sha\u003e` | Delete |\n| Untagged but still referenced by a retained multi-platform image index | Keep |\n| Untagged and not referenced by any retained index | Delete |\n| A signature or metadata artifact for a retained image digest | Keep |\n| A signature or metadata artifact for a deleted image digest | Delete |\n\nThere is no retention count anymore. The workflow deletes every package version that is not protected by tags or by graph references.\n\n## Examples\n\n- `ghcr.io/\u003cowner\u003e/sambee:test` stays because `test` is a protected channel tag.\n- `ghcr.io/\u003cowner\u003e/sambee:sha-\u003cfull-commit-sha\u003e` is deleted if that digest is not also kept by another protected tag.\n- An untagged platform manifest stays if a retained multi-platform index still points to it.\n- A stale `ghcr.io/\u003cowner\u003e/sambee-signatures` artifact is deleted after its corresponding image digest is no longer retained.\n\n## Boundaries\n\n- Do not publish a replacement runtime image in backfill. Recovery should point tags back at an existing digest.\n- Do not treat immutable `sha-\u003cfull-commit-sha\u003e` preview tags as permanent history. The cleanup workflow is expected to prune them.\n- Do not use moving tags such as `stable`, `beta`, or `test` as the only source of deployment truth when a digest is available.\n\nIf you are starting from a new candidate commit rather than repairing an existing release path, go back to [Build Docker Image](../build-docker-image/) or [Promote Docker Image](../promote-docker-image/).\n", "1.0": "+++\ntitle = \"Docker Backfill And Cleanup\"\n+++\n\nThis is the maintenance page for the Docker release flow.\n\nUse these maintenance workflows when you need to repair tags, backfill an older approved release, or keep preview history under control.\n\n## Summary\n\nUse this page when you are not publishing a new Docker image, but instead need to maintain existing release artifacts in GitHub Container Registry.\n\n| Workflow | What it does | Required input | Use it when... |\n|---|---|---|---|\n| `Maintenance: Backfill Docker Release Tags` | Reattaches release tags and channel aliases to an already approved digest and republishes missing metadata bundle assets when needed. | One existing Git tag in release form, such as `v0.7.0` or `v0.7.0-beta.1`. | A release already exists, but its GHCR tags or release assets are missing, wrong, or need to be reconstructed without building a new image. |\n| `Maintenance: Clean Up Docker Package Versions` | Deletes unprotected preview versions, stale signature artifacts, and unreferenced untagged GHCR package versions. | None. | Preview history and dangling GHCR artifacts have accumulated and you want the repository cleaned up without touching protected release artifacts. |\n\n## Backfill Docker Release Tags\n\nGitHub Actions displays the recovery workflow as `Maintenance: Backfill Docker Release Tags`.\n\n### What it does\n\nUse it to repair or reconstruct the publish side of an already approved Docker release without publishing a new runtime image.\n\nThe workflow:\n\n- resolves the digest that already belongs to the approved release\n- verifies image metadata\n- verifies the preview-built metadata bundle, generating and publishing it first if an older release does not have one yet\n- reapplies the expected release tags to that same digest\n- updates channel aliases with the same semver rules as normal promotion\n- uploads the metadata bundle files to the GitHub Release as convenience assets\n\nFor stable releases, that means backfill also moves `beta` forward unless `beta` already points to the same digest or to a higher semver release line.\n\n### Required input\n\nThe workflow takes one manual input:\n\n| Input | What it means | Required |\n|---|---|---|\n| `release_tag` | An existing immutable Git tag for the approved release, for example `v0.7.0` or `v0.7.0-beta.1`. The tag must match the checked-in `VERSION` value for that tagged commit. | Yes |\n\n### When to use it\n\nUse backfill in specific repair scenarios such as:\n\n- The GitHub Release exists, but the expected GHCR release tags were not attached.\n- A stable release was approved earlier, and you need to restore `stable`, version tags, or `beta` catch-up behavior to the correct existing digest.\n- A prerelease was approved earlier, and you need to restore the `beta` alias to the already approved digest.\n- A transient runner or registry failure interrupted release publication after the candidate image had already been built successfully.\n- An older approved release predates the current metadata-bundle flow, and you need to reconstruct the release assets without rebuilding the runtime image.\n\nDo not use backfill when you want to ship a new candidate commit. In that case, go back to [Build Docker Image](../build-docker-image/) and then [Promote Docker Image](../promote-docker-image/).\n\n### Tag requirements\n\nThe release tag can be either a stable tag such as `v0.7.0` or a prerelease tag such as `vX.Y.Z-beta.N`, as long as it matches the checked-in base `VERSION` for that release commit.\n\nWhen an older release does not have the new metadata bundle yet, backfill may create a local attested OCI export from the tagged source to recover SBOM and provenance files. That export is used only to publish the missing metadata bundle; the runtime image digest being promoted does not change.\n\nUse backfill only for already approved releases. It is not an alternate way to publish a new image.\n\n## Clean Up Docker Package Versions\n\nGitHub Actions displays the retention workflow as `Maintenance: Clean Up Docker Package Versions`.\n\n### What it does\n\nThis workflow removes disposable GHCR history while preserving artifacts that are still in use.\n\nIt:\n\n- deletes unprotected preview package versions\n- prunes stale metadata and Cosign signature artifacts\n- removes unreferenced untagged package versions\n- preserves release-tagged versions, protected channel aliases, and graph-referenced child manifests\n\n### Required input\n\nThis workflow has no manual inputs.\n\nIt runs automatically after successful preview publication, on a schedule, or manually when you want to force a cleanup pass.\n\n### When to use it\n\nUse cleanup in specific maintenance scenarios such as:\n\n- Preview publishing has created many old `sha-\u003cfull-commit-sha\u003e` versions that are no longer needed.\n- GHCR package pages have accumulated stale signature or metadata artifacts from deleted image digests.\n- You want to verify that retention behavior is working after changes to release-tagging or cleanup logic.\n- You want an immediate cleanup run instead of waiting for the next scheduled pass.\n\nDo not use cleanup to repair a missing release tag or channel alias. Use `Maintenance: Backfill Docker Release Tags` for that.\n\n### What cleanup preserves\n\nThis workflow periodically deletes unprotected preview and unreferenced GitHub Container Registry versions while preserving:\n\n- release-tagged versions.\n- `stable`, `beta`, `test`, and stable minor-series tags.\n\nThe moving `test` tag is protected like the other channel aliases.\nImmutable `sha-\u003cfull-commit-sha\u003e` preview tags are deleted when they are no longer protected by another retained tag.\nUntagged child manifests referenced by retained multi-platform indexes are protected before stale untagged versions are deleted.\nThe cleanup also prunes stale `ghcr.io/\u003cowner\u003e/sambee-signatures` metadata and Cosign signature tags after their corresponding `sambee` image digest is no longer retained.\nThe same reference-aware untagged cleanup runs for `sambee-signatures`, where it keeps Cosign signature bundle children referenced by retained signature indexes.\n\nThat keeps the `test` channel usable while aggressively removing disposable preview history.\n\n## Cleanup Rules\n\nUse this quick reference when deciding what the cleanup workflow will keep versus delete.\n\n| If a package version is... | Cleanup action |\n|---|---|\n| Tagged with a release tag, whether stable or prerelease | Keep |\n| Tagged with a protected channel or series tag such as `stable`, `beta`, `test`, or `0.7` | Keep |\n| Tagged only with an immutable preview tag such as `sha-\u003cfull-commit-sha\u003e` | Delete |\n| Untagged but still referenced by a retained multi-platform image index | Keep |\n| Untagged and not referenced by any retained index | Delete |\n| A signature or metadata artifact for a retained image digest | Keep |\n| A signature or metadata artifact for a deleted image digest | Delete |\n\nThere is no retention count anymore. The workflow deletes every package version that is not protected by tags or by graph references.\n\n## Examples\n\n- `ghcr.io/\u003cowner\u003e/sambee:test` stays because `test` is a protected channel tag.\n- `ghcr.io/\u003cowner\u003e/sambee:sha-\u003cfull-commit-sha\u003e` is deleted if that digest is not also kept by another protected tag.\n- An untagged platform manifest stays if a retained multi-platform index still points to it.\n- A stale `ghcr.io/\u003cowner\u003e/sambee-signatures` artifact is deleted after its corresponding image digest is no longer retained.\n\n## Boundaries\n\n- Do not publish a replacement runtime image in backfill. Recovery should point tags back at an existing digest.\n- Do not treat immutable `sha-\u003cfull-commit-sha\u003e` preview tags as permanent history. The cleanup workflow is expected to prune them.\n- Do not use moving tags such as `stable`, `beta`, or `test` as the only source of deployment truth when a digest is available.\n\nIf you are starting from a new candidate commit rather than repairing an existing release path, go back to [Build Docker Image](../build-docker-image/) or [Promote Docker Image](../promote-docker-image/).\n", "2.0": "+++\ntitle = \"Docker Backfill And Cleanup\"\n+++\n\nThis is the maintenance page for the Docker release flow.\n\nUse these maintenance workflows when you need to repair tags, backfill an older approved release, or keep preview history under control.\n\n## Summary\n\nUse this page when you are not publishing a new Docker image, but instead need to maintain existing release artifacts in GitHub Container Registry.\n\n| Workflow | What it does | Required input | Use it when... |\n|---|---|---|---|\n| `Maintenance: Backfill Docker Release Tags` | Reattaches release tags and channel aliases to an already approved digest and republishes missing metadata bundle assets when needed. | One existing Git tag in release form, such as `v0.7.0` or `v0.7.0-beta.1`. | A release already exists, but its GHCR tags or release assets are missing, wrong, or need to be reconstructed without building a new image. |\n| `Maintenance: Clean Up Docker Package Versions` | Deletes unprotected preview versions, stale signature artifacts, and unreferenced untagged GHCR package versions. | None. | Preview history and dangling GHCR artifacts have accumulated and you want the repository cleaned up without touching protected release artifacts. |\n\n## Backfill Docker Release Tags\n\nGitHub Actions displays the recovery workflow as `Maintenance: Backfill Docker Release Tags`.\n\n### What it does\n\nUse it to repair or reconstruct the publish side of an already approved Docker release without publishing a new runtime image.\n\nThe workflow:\n\n- resolves the digest that already belongs to the approved release\n- verifies image metadata\n- verifies the preview-built metadata bundle, generating and publishing it first if an older release does not have one yet\n- reapplies the expected release tags to that same digest\n- updates channel aliases with the same semver rules as normal promotion\n- uploads the metadata bundle files to the GitHub Release as convenience assets\n\nFor stable releases, that means backfill also moves `beta` forward unless `beta` already points to the same digest or to a higher semver release line.\n\n### Required input\n\nThe workflow takes one manual input:\n\n| Input | What it means | Required |\n|---|---|---|\n| `release_tag` | An existing immutable Git tag for the approved release, for example `v0.7.0` or `v0.7.0-beta.1`. The tag must match the checked-in `VERSION` value for that tagged commit. | Yes |\n\n### When to use it\n\nUse backfill in specific repair scenarios such as:\n\n- The GitHub Release exists, but the expected GHCR release tags were not attached.\n- A stable release was approved earlier, and you need to restore `stable`, version tags, or `beta` catch-up behavior to the correct existing digest.\n- A prerelease was approved earlier, and you need to restore the `beta` alias to the already approved digest.\n- A transient runner or registry failure interrupted release publication after the candidate image had already been built successfully.\n- An older approved release predates the current metadata-bundle flow, and you need to reconstruct the release assets without rebuilding the runtime image.\n\nDo not use backfill when you want to ship a new candidate commit. In that case, go back to [Build Docker Image](../build-docker-image/) and then [Promote Docker Image](../promote-docker-image/).\n\n### Tag requirements\n\nThe release tag can be either a stable tag such as `v0.7.0` or a prerelease tag such as `vX.Y.Z-beta.N`, as long as it matches the checked-in base `VERSION` for that release commit.\n\nWhen an older release does not have the new metadata bundle yet, backfill may create a local attested OCI export from the tagged source to recover SBOM and provenance files. That export is used only to publish the missing metadata bundle; the runtime image digest being promoted does not change.\n\nUse backfill only for already approved releases. It is not an alternate way to publish a new image.\n\n## Clean Up Docker Package Versions\n\nGitHub Actions displays the retention workflow as `Maintenance: Clean Up Docker Package Versions`.\n\n### What it does\n\nThis workflow removes disposable GHCR history while preserving artifacts that are still in use.\n\nIt:\n\n- deletes unprotected preview package versions\n- prunes stale metadata and Cosign signature artifacts\n- removes unreferenced untagged package versions\n- preserves release-tagged versions, protected channel aliases, and graph-referenced child manifests\n\n### Required input\n\nThis workflow has no manual inputs.\n\nIt runs automatically after successful preview publication, on a schedule, or manually when you want to force a cleanup pass.\n\n### When to use it\n\nUse cleanup in specific maintenance scenarios such as:\n\n- Preview publishing has created many old `sha-\u003cfull-commit-sha\u003e` versions that are no longer needed.\n- GHCR package pages have accumulated stale signature or metadata artifacts from deleted image digests.\n- You want to verify that retention behavior is working after changes to release-tagging or cleanup logic.\n- You want an immediate cleanup run instead of waiting for the next scheduled pass.\n\nDo not use cleanup to repair a missing release tag or channel alias. Use `Maintenance: Backfill Docker Release Tags` for that.\n\n### What cleanup preserves\n\nThis workflow periodically deletes unprotected preview and unreferenced GitHub Container Registry versions while preserving:\n\n- release-tagged versions.\n- `stable`, `beta`, `test`, and stable minor-series tags.\n\nThe moving `test` tag is protected like the other channel aliases.\nImmutable `sha-\u003cfull-commit-sha\u003e` preview tags are deleted when they are no longer protected by another retained tag.\nUntagged child manifests referenced by retained multi-platform indexes are protected before stale untagged versions are deleted.\nThe cleanup also prunes stale `ghcr.io/\u003cowner\u003e/sambee-signatures` metadata and Cosign signature tags after their corresponding `sambee` image digest is no longer retained.\nThe same reference-aware untagged cleanup runs for `sambee-signatures`, where it keeps Cosign signature bundle children referenced by retained signature indexes.\n\nThat keeps the `test` channel usable while aggressively removing disposable preview history.\n\n## Cleanup Rules\n\nUse this quick reference when deciding what the cleanup workflow will keep versus delete.\n\n| If a package version is... | Cleanup action |\n|---|---|\n| Tagged with a release tag, whether stable or prerelease | Keep |\n| Tagged with a protected channel or series tag such as `stable`, `beta`, `test`, or `0.7` | Keep |\n| Tagged only with an immutable preview tag such as `sha-\u003cfull-commit-sha\u003e` | Delete |\n| Untagged but still referenced by a retained multi-platform image index | Keep |\n| Untagged and not referenced by any retained index | Delete |\n| A signature or metadata artifact for a retained image digest | Keep |\n| A signature or metadata artifact for a deleted image digest | Delete |\n\nThere is no retention count anymore. The workflow deletes every package version that is not protected by tags or by graph references.\n\n## Examples\n\n- `ghcr.io/\u003cowner\u003e/sambee:test` stays because `test` is a protected channel tag.\n- `ghcr.io/\u003cowner\u003e/sambee:sha-\u003cfull-commit-sha\u003e` is deleted if that digest is not also kept by another protected tag.\n- An untagged platform manifest stays if a retained multi-platform index still points to it.\n- A stale `ghcr.io/\u003cowner\u003e/sambee-signatures` artifact is deleted after its corresponding image digest is no longer retained.\n\n## Boundaries\n\n- Do not publish a replacement runtime image in backfill. Recovery should point tags back at an existing digest.\n- Do not treat immutable `sha-\u003cfull-commit-sha\u003e` preview tags as permanent history. The cleanup workflow is expected to prune them.\n- Do not use moving tags such as `stable`, `beta`, or `test` as the only source of deployment truth when a digest is available.\n\nIf you are starting from a new candidate commit rather than repairing an existing release path, go back to [Build Docker Image](../build-docker-image/) or [Promote Docker Image](../promote-docker-image/).\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/release-and-versioning/companion-release-overview", "parent_id": "section:developer-guide/release-and-versioning", "depth": 2, "kind": "page", "label": "companion-release-overview", "title": "Companion Release Overview", "path": "developer-guide/release-and-versioning/companion-release-overview", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "branched", "source_version": "0.7", "diff_added": 4, "diff_removed": 0}, "0.9": {"state": "branched", "source_version": "0.8", "diff_added": 25, "diff_removed": 20}, "1.0": {"state": "branched", "source_version": "0.9", "diff_added": 14, "diff_removed": 47}, "2.0": {"state": "branched", "source_version": "1.0", "diff_added": 3, "diff_removed": 3}}, "content_versions": {"0.7": "+++\ntitle = \"Companion Release Overview\"\n+++\n\nSambee Companion releases are built and published once, and later promoted across update channels by changing public feed files.\n\nKey differences between the Companion and Docker release paths:\n\n- Docker releases promote an already published container digest.\n- Companion releases promote an already published GitHub Release by rewriting feeds read by Companion's auto-updater and by the Sambee frontend.\n\n## Summary\n\nIf you want to take a new Companion version to the `stable` update channel, follow this order:\n\n1. Update `VERSION` and run `./scripts/sync-version`.\n   - Git merge the reviewed `version-sync` changes.\n1. If you need a prerelease or test build before the official version, choose a distinct override version such as `0.8.0-beta.1` or `0.8.0-rc.1`.\n1. Run `Release: Build Companion Artifact` and select the target platforms.\n   - Leave `publish_version_override` empty for the checked-in version, or set it to the temporary prerelease version for this run.\n   - This creates draft release in the GitHub repo `helgeklein/sambee-companion`.\n1. Test the draft release.\n   - Download the installer from the releases artifacts, install and test.\n1. Publish the draft release.\n1. Run `Release: Promote Companion Release` for `test`.\n   - Validate both update behavior and direct-download metadata against the promoted feeds.\n1. Rerun `Release: Promote Companion Release` for `beta`, `stable`, and Sambee download metadata.\n\nCompanion release tags follow the `companion-v\u003cversion\u003e` pattern.\n\nThe build workflow refuses to reuse an existing Companion release tag, whether that release is still a draft or already published.\nWhen you need another pre-release candidate, assign a distinct suffix instead of rebuilding the same tag.\n\nOne published release can move from `test` to `beta` to `stable` without rebuilding binaries.\n\nRead the detailed pages in this order:\n\n1. [Build Companion Release](../build-companion-release/)\n1. [Promote Companion Release](../promote-companion-release/)\n1. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/)\n\n## Workflow Map\n\n| Workflow or system | When to use it | Result |\n|---|---|---|\n| `Release: Build Companion Artifact` | You want to create release assets for one new Companion version or prerelease candidate. | Builds the selected platform set and creates a draft GitHub Release in `helgeklein/sambee-companion`, failing early if that tag already exists. |\n| `Release: Promote Companion Release` | A published Companion release is approved for one or more channels or for Sambee download metadata. | Rewrites the selected feed files in `docs/feeds` of the release repository. |\n| `helgeklein/sambee-companion` | You need the release repository that owns public Companion release artifacts. | Hosts immutable GitHub Release assets and stores the committed feed files under `docs/feeds` to be served by GitHub Pages. |\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/build-companion.yml` | Builds platform artifacts, supports a one-run version override, and creates a draft release for a unique tag. |\n| `.github/workflows/promote-companion-release.yml` | Promotes one published release to selected public feeds. |\n| `.github/scripts/promote_companion_release.py` | Resolves release assets and writes the feed JSON files. |\n| `helgeklein/sambee-companion` | Dedicated public release repository for Companion GitHub Releases and committed feed source files. |\n| `release-repo/docs/feeds` | Source-controlled feed JSON files that promotion updates and commits. |\n\n## Channels And Consumers\n\nCompanion does not use separate binaries per channel. It uses one published release plus multiple mutable feed pointers.\n\nFor the public feed host, exact feed locations, and consumer-specific behavior, see [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/).\n\n## Published Artifact\n\nPublished Companion releases live in `helgeklein/sambee-companion` as GitHub Releases.\n\nEach release may contain:\n\n- Installer assets.\n- Tauri updater bundles.\n- `.sig` files for updater verification.\n- Release notes.\n\nRelease tags do not encode a channel.\nChannel visibility is decided only by the promoted feed files.\n\n## Operating Rules\n\n- Do not treat update channels as different binaries.\n- Do not patch broken published assets in place.\n- Build and publish a new release instead of replacing assets on an existing tag.\n- Assign a distinct prerelease suffix when you need another build before the official release.\n- Review whether you are changing Companion updater visibility, Sambee download visibility, or both.\n\nUse [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) for the system model behind those rules.\n", "0.8": "+++\ntitle = \"Companion Release Overview\"\n+++\n\nSambee Companion releases are built and published once, and later promoted across update channels by changing public feed files.\n\nKey differences between the Companion and Docker release paths:\n\n- Docker releases promote an already published container digest.\n- Companion releases promote an already published GitHub Release by rewriting feeds read by Companion's auto-updater and by the Sambee frontend.\n- Local Linux-hosted cross-checks can validate Windows-target compatibility, but they do not replace the Windows CI release build.\n\n## Summary\n\nIf you want to take a new Companion version to the `stable` update channel, follow this order:\n\n1. Update `VERSION` and run `./scripts/sync-version`.\n   - Git merge the reviewed `version-sync` changes.\n1. If you need a prerelease or test build before the official version, choose a distinct override version such as `0.8.0-beta.1` or `0.8.0-rc.1`.\n1. Run `Release: Build Companion Artifact` and select the target platforms.\n   - Leave `publish_version_override` empty for the checked-in version, or set it to the temporary prerelease version for this run.\n   - This creates draft release in the GitHub repo `helgeklein/sambee-companion`.\n1. Test the draft release.\n   - Download the installer from the releases artifacts, install and test.\n1. Publish the draft release.\n1. Run `Release: Promote Companion Release` for `test`.\n   - Validate both update behavior and direct-download metadata against the promoted feeds.\n1. Rerun `Release: Promote Companion Release` for `beta`, `stable`, and Sambee download metadata.\n\nCompanion release tags follow the `companion-v\u003cversion\u003e` pattern.\n\nThe build workflow refuses to reuse an existing Companion release tag, whether that release is still a draft or already published.\nWhen you need another pre-release candidate, assign a distinct suffix instead of rebuilding the same tag.\n\nOne published release can move from `test` to `beta` to `stable` without rebuilding binaries.\n\nRead the detailed pages in this order:\n\n1. [Build Companion Release](../build-companion-release/)\n1. [Promote Companion Release](../promote-companion-release/)\n1. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/)\n\n## Workflow Map\n\n| Workflow or system | When to use it | Result |\n|---|---|---|\n| Local `npm run check:rust:windows` | You want an early local Windows-target compatibility signal while working in Linux or the devcontainer. | Runs a Windows GNU target `cargo check` only. It does not create signed release assets. |\n| `Release: Build Companion Artifact` | You want to create release assets for one new Companion version or prerelease candidate. | Builds the selected platform set and creates a draft GitHub Release in `helgeklein/sambee-companion`, failing early if that tag already exists. |\n| `Release: Promote Companion Release` | A published Companion release is approved for one or more channels or for Sambee download metadata. | Rewrites the selected feed files in `docs/feeds` of the release repository. |\n| `helgeklein/sambee-companion` | You need the release repository that owns public Companion release artifacts. | Hosts immutable GitHub Release assets and stores the committed feed files under `docs/feeds` to be served by GitHub Pages. |\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/build-companion.yml` | Builds platform artifacts, supports a one-run version override, and creates a draft release for a unique tag. |\n| `.github/workflows/promote-companion-release.yml` | Promotes one published release to selected public feeds. |\n| `.github/scripts/promote_companion_release.py` | Resolves release assets and writes the feed JSON files. |\n| `helgeklein/sambee-companion` | Dedicated public release repository for Companion GitHub Releases and committed feed source files. |\n| `release-repo/docs/feeds` | Source-controlled feed JSON files that promotion updates and commits. |\n\n## Channels And Consumers\n\nCompanion does not use separate binaries per channel. It uses one published release plus multiple mutable feed pointers.\n\nFor the public feed host, exact feed locations, and consumer-specific behavior, see [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/).\n\n## Published Artifact\n\nPublished Companion releases live in `helgeklein/sambee-companion` as GitHub Releases.\n\nEach release may contain:\n\n- Installer assets.\n- Tauri updater bundles.\n- `.sig` files for updater verification.\n- Release notes.\n\nRelease tags do not encode a channel.\nChannel visibility is decided only by the promoted feed files.\n\n## Operating Rules\n\n- Do not treat update channels as different binaries.\n- Do not patch broken published assets in place.\n- Build and publish a new release instead of replacing assets on an existing tag.\n- Assign a distinct prerelease suffix when you need another build before the official release.\n- Review whether you are changing Companion updater visibility, Sambee download visibility, or both.\n- Treat local Windows GNU cross-checks as compatibility validation only.\n- Keep actual Windows artifact creation and signing in the CI release workflow.\n\nUse [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) for the system model behind those rules.\n", "0.9": "+++\ntitle = \"Companion Release Overview\"\n+++\n\nSambee Companion releases are built and published once, and later promoted across update channels by changing public feed files.\n\nKey differences between the Companion and Docker release paths:\n\n- Docker releases promote an already published container image.\n- Companion releases promote an already published GitHub Release by rewriting feeds read by Companion's auto-updater and by the Sambee frontend.\n- Docker images are available for Linux only, whereas Companion is a native app for Windows, Linux, and macOS. Each platform binary needs to be built on the respective OS.\n\n## Summary\n\nIf you want to take a new Companion version to the `stable` update channel, follow this order:\n\n1. Increment `VERSION` to the next `X.Y.Z` value and run `./scripts/sync-version`.\n1. Run `Release: Build Companion Artifact`:\n   - Select target platforms\n   - If the workflow's source version field is left blank, the artifact is built from the current commit in `main`, and the Git tag `build-vX.Y.Z` is created to reserve the version for the commit the artifact is built from.\n   - If a source version field is specified, the workflow verifies and repairs the artifact associated with the version via the Git tag used for reservation.\n1. The workflow:\n   - builds Companion\n   - signs the build artifacts\n   - creates one immutable draft release in in the [Companion GitHub repo](https://github.com/helgeklein/sambee-companion/releases).\n   - assigns a `companion-vX.Y.Z` tag to the draft release.\n1. Test the draft release.\n   - Download the installer from the release's artifacts, install and test.\n1. Publish the draft release. This:\n   - Makes the release eligible for promotion to the `test`, `beta`, and `stable` channels.\n   - Prevents additional build workflow runs changing the published Companion release.\n1. Ensure that a matching published public Sambee release `vX.Y.Z` exists.\n   - This authorizes the Companion workflow to promote a release.\n1. To promote the release to the update channels, run `Release: Promote Companion Release`:\n   - Select the channels: `test`, `beta`, and/or `stable`.\n   - Select whether to update the Sambee download metadata.\n\nThe workflow uses `build`, `recover-finalizer`, and `complete` states. A matching incomplete draft resumes only from recorded retained Actions artifacts; a complete draft or published release is not rebuilt. When a replacement is needed, increment `Z`, synchronize, commit on `main`, and build a new candidate.\n\nOne published release can move from `test` to `beta` to `stable` without rebuilding binaries.\n\nRead the detailed pages in this order:\n\n1. [Build Companion Release](../build-companion-release/)\n1. [Promote Companion Release](../promote-companion-release/)\n1. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/)\n\n## Workflow Map\n\n| Workflow or system | When to use it | Result |\n|---|---|---|\n| Local `npm run check:rust:windows` | You want an early local Windows-target compatibility signal while working in Linux or the devcontainer. | Runs a Windows GNU target `cargo check` only. It does not create signed release assets. |\n| `Release: Build Companion Artifact` | You want to create release assets for one canonical version. | Builds the selected platform set and creates, resumes, or reports the immutable draft GitHub Release in `helgeklein/sambee-companion`. |\n| `Release: Promote Companion Release` | A published Companion release is approved for one or more channels or for Sambee download metadata. | Rewrites the selected feed files in `docs/feeds` of the release repository. |\n| `helgeklein/sambee-companion` | You need the release repository that owns public Companion release artifacts. | Hosts immutable GitHub Release assets and stores the committed feed files under `docs/feeds` to be served by GitHub Pages. |\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/build-companion.yml` | Builds platform artifacts from a canonical source and creates or resumes one draft release for its immutable tag. |\n| `.github/workflows/promote-companion-release.yml` | Promotes one published release to selected public feeds. |\n| `.github/scripts/promote_companion_release.py` | Resolves release assets and writes the feed JSON files. |\n| `helgeklein/sambee-companion` | Dedicated public release repository for Companion GitHub Releases and committed feed source files. |\n| `release-repo/docs/feeds` | Source-controlled feed JSON files that promotion updates and commits. |\n\n## Channels And Consumers\n\nCompanion does not use separate binaries per channel. It uses one published release plus multiple mutable feed pointers.\n\nFor the public feed host, exact feed locations, and consumer-specific behavior, see [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/).\n\n## Published Artifact\n\nPublished Companion releases live in `helgeklein/sambee-companion` as GitHub Releases.\n\nEach release may contain:\n\n- Installer assets.\n- Tauri updater bundles.\n- `.sig` files for updater verification.\n- Release notes.\n\nRelease tags do not encode a channel.\nChannel visibility is decided only by the promoted feed files.\n\n## Operating Rules\n\n- Do not treat update channels as different binaries.\n- Do not patch broken published assets in place.\n- Build and publish a new release instead of replacing assets on an existing tag.\n- Increment the `Z` build sequence when you need another candidate.\n- Review whether you are changing Companion updater visibility, Sambee download visibility, or both.\n- Treat local Windows GNU cross-checks as compatibility validation only.\n- Keep actual Windows artifact creation and signing in the CI release workflow.\n\nUse [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) for the system model behind those rules.\n", "1.0": "+++\ntitle = \"Companion Release Overview\"\n+++\n\nSambee Companion releases are built and published once. A successful build automatically promotes the release to `test`; later channel promotion rewrites public feed files without rebuilding binaries.\n\nKey differences between the Companion and Docker release paths:\n\n- Docker releases promote an already published container image.\n- Companion releases promote an already published GitHub Release by rewriting feeds read by Companion's auto-updater and by the Sambee frontend.\n- Docker images are available for Linux only, whereas Companion is a native app for Windows, Linux, and macOS. Each platform binary needs to be built on the respective OS.\n\n## Summary\n\nIf you want to take a new Companion version to `stable`, follow this order:\n\n1. Increment `VERSION` to the next `X.Y.Z` value and run `./scripts/sync-version`.\n1. Run `Release: Build Companion Artifact`:\n   - Select target platforms\n   - If the workflow's source version field is left blank, the artifact is built from the current commit in `main`, and the Git tag `build-vX.Y.Z` is created to reserve the version for the commit the artifact is built from.\n   - If a source version field is specified, the workflow verifies and repairs the artifact associated with the version via the Git tag used for reservation.\n1. The workflow builds and signs Companion, publishes the verified immutable release in the [Companion GitHub repo](https://github.com/helgeklein/sambee-companion/releases), promotes it to `test`, and cleans up obsolete releases.\n1. Test the published release through the `test` channel or by installing its release assets.\n1. Run `Release: Promote Companion Release` when the release is approved for `beta`, `stable`, or Sambee download metadata.\n\nOne published release can move from `test` to `beta` to `stable` without rebuilding binaries.\n\nRead the detailed pages in this order:\n\n1. [Build Companion Release](../build-companion-release/)\n1. [Promote Companion Release](../promote-companion-release/)\n1. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/)\n1. [Companion Release Cleanup](../companion-release-cleanup/)\n\n## Workflow Map\n\n| Workflow | When to use it | Result |\n|---|---|---|\n| Local `npm run check:rust:windows` | You want an early local Windows-target compatibility signal while working in Linux or the devcontainer. | Runs a Windows GNU target `cargo check` only. It does not create signed release assets. |\n| `Release: Build Companion Artifact` | You want to create release assets for one canonical version. | Builds the selected platform set, publishes the verified immutable GitHub Release, promotes only `test`, and cleans up obsolete releases. |\n| `Release: Promote Companion Release` | A published Companion release is approved for one or more channels or for Sambee download metadata. | Rewrites the selected feed files in `docs/feeds` of the release repository. |\n| `Maintenance: Clean Up Companion Releases` | You want to reconcile release retention outside a promotion run. | Validates the feed markers and deletes obsolete GitHub Releases. |\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/build-companion.yml` | Builds platform artifacts from a canonical source, publishes the verified release, promotes `test`, and runs cleanup. |\n| `.github/workflows/promote-companion-release.yml` | Promotes one published release to selected public feeds. |\n| `.github/scripts/promote_companion_release.py` | Resolves release assets and writes the feed JSON files. |\n| `.github/scripts/cleanup_companion_releases.py` | Validates feed references and applies Companion release retention. |\n| [helgeklein/sambee-companion](https://github.com/helgeklein/sambee-companion/) | Dedicated public release repository for Companion GitHub Releases and committed feed source files. |\n| `release-repo/docs/feeds` | Source-controlled feed JSON files that promotion updates and commits ([docs](../companion-channels-feeds-and-downloads/)). |\n\n## Published Artifact\n\nPublished Companion releases live in [helgeklein/sambee-companion](https://github.com/helgeklein/sambee-companion/) as GitHub Releases.\n\nEach release may contain:\n\n- Installer assets.\n- Tauri updater bundles.\n- `.sig` files for updater verification.\n- Release notes.\n", "2.0": "+++\ntitle = \"Companion Release Overview\"\n+++\n\nSambee Companion releases are built and published once. A successful build automatically promotes the release to `test`; later channel promotion rewrites public feed files without rebuilding binaries.\n\nKey differences between the Companion and Docker release paths:\n\n- Docker releases promote an already published container image.\n- Companion releases promote an already published GitHub Release by rewriting feeds read by Companion's auto-updater and by the Sambee frontend.\n- Docker images are available for Linux only, whereas Companion is a native app for Windows, Linux, and macOS. Each platform binary needs to be built on the respective OS.\n\n## Summary\n\nIf you want to take a new Companion version to `stable`, follow this order:\n\n1. Increment `VERSION` to the next `X.Y.Z` value and run `./scripts/sync-version`.\n1. Run `Release: Build Companion Artifact`:\n   - Select target platforms\n   - If the workflow's source version field is left blank, the artifact is built from the current commit in `main`, and the Git tag `build-vX.Y.Z` is created to reserve the version for the commit the artifact is built from.\n   - If a source version field is specified, the workflow verifies and repairs the artifact associated with the version via the Git tag used for reservation.\n1. The workflow builds and signs Companion, publishes the verified immutable release in the [Companion GitHub repo](https://github.com/sambee-app/sambee-companion/releases), promotes it to `test`, and cleans up obsolete releases.\n1. Test the published release through the `test` channel or by installing its release assets.\n1. Run `Release: Promote Companion Release` when the release is approved for `beta`, `stable`, or Sambee download metadata.\n\nOne published release can move from `test` to `beta` to `stable` without rebuilding binaries.\n\nRead the detailed pages in this order:\n\n1. [Build Companion Release](../build-companion-release/)\n1. [Promote Companion Release](../promote-companion-release/)\n1. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/)\n1. [Companion Release Cleanup](../companion-release-cleanup/)\n\n## Workflow Map\n\n| Workflow | When to use it | Result |\n|---|---|---|\n| Local `npm run check:rust:windows` | You want an early local Windows-target compatibility signal while working in Linux or the devcontainer. | Runs a Windows GNU target `cargo check` only. It does not create signed release assets. |\n| `Release: Build Companion Artifact` | You want to create release assets for one canonical version. | Builds the selected platform set, publishes the verified immutable GitHub Release, promotes only `test`, and cleans up obsolete releases. |\n| `Release: Promote Companion Release` | A published Companion release is approved for one or more channels or for Sambee download metadata. | Rewrites the selected feed files in `docs/feeds` of the release repository. |\n| `Maintenance: Clean Up Companion Releases` | You want to reconcile release retention outside a promotion run. | Validates the feed markers and deletes obsolete GitHub Releases. |\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/build-companion.yml` | Builds platform artifacts from a canonical source, publishes the verified release, promotes `test`, and runs cleanup. |\n| `.github/workflows/promote-companion-release.yml` | Promotes one published release to selected public feeds. |\n| `.github/scripts/promote_companion_release.py` | Resolves release assets and writes the feed JSON files. |\n| `.github/scripts/cleanup_companion_releases.py` | Validates feed references and applies Companion release retention. |\n| [sambee-app/sambee-companion](https://github.com/sambee-app/sambee-companion/) | Dedicated public release repository for Companion GitHub Releases and committed feed source files. |\n| `release-repo/docs/feeds` | Source-controlled feed JSON files that promotion updates and commits ([docs](../companion-channels-feeds-and-downloads/)). |\n\n## Published Artifact\n\nPublished Companion releases live in [sambee-app/sambee-companion](https://github.com/sambee-app/sambee-companion/) as GitHub Releases.\n\nEach release may contain:\n\n- Installer assets.\n- Tauri updater bundles.\n- `.sig` files for updater verification.\n- Release notes.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Companion Release Overview\"\n+++\n\nSambee Companion releases are built and published once, and later promoted across update channels by changing public feed files.\n\nKey differences between the Companion and Docker release paths:\n\n- Docker releases promote an already published container digest.\n- Companion releases promote an already published GitHub Release by rewriting feeds read by Companion's auto-updater and by the Sambee frontend.\n\n## Summary\n\nIf you want to take a new Companion version to the `stable` update channel, follow this order:\n\n1. Update `VERSION` and run `./scripts/sync-version`.\n   - Git merge the reviewed `version-sync` changes.\n1. If you need a prerelease or test build before the official version, choose a distinct override version such as `0.8.0-beta.1` or `0.8.0-rc.1`.\n1. Run `Release: Build Companion Artifact` and select the target platforms.\n   - Leave `publish_version_override` empty for the checked-in version, or set it to the temporary prerelease version for this run.\n   - This creates draft release in the GitHub repo `helgeklein/sambee-companion`.\n1. Test the draft release.\n   - Download the installer from the releases artifacts, install and test.\n1. Publish the draft release.\n1. Run `Release: Promote Companion Release` for `test`.\n   - Validate both update behavior and direct-download metadata against the promoted feeds.\n1. Rerun `Release: Promote Companion Release` for `beta`, `stable`, and Sambee download metadata.\n\nCompanion release tags follow the `companion-v\u003cversion\u003e` pattern.\n\nThe build workflow refuses to reuse an existing Companion release tag, whether that release is still a draft or already published.\nWhen you need another pre-release candidate, assign a distinct suffix instead of rebuilding the same tag.\n\nOne published release can move from `test` to `beta` to `stable` without rebuilding binaries.\n\nRead the detailed pages in this order:\n\n1. [Build Companion Release](../build-companion-release/)\n1. [Promote Companion Release](../promote-companion-release/)\n1. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/)\n\n## Workflow Map\n\n| Workflow or system | When to use it | Result |\n|---|---|---|\n| `Release: Build Companion Artifact` | You want to create release assets for one new Companion version or prerelease candidate. | Builds the selected platform set and creates a draft GitHub Release in `helgeklein/sambee-companion`, failing early if that tag already exists. |\n| `Release: Promote Companion Release` | A published Companion release is approved for one or more channels or for Sambee download metadata. | Rewrites the selected feed files in `docs/feeds` of the release repository. |\n| `helgeklein/sambee-companion` | You need the release repository that owns public Companion release artifacts. | Hosts immutable GitHub Release assets and stores the committed feed files under `docs/feeds` to be served by GitHub Pages. |\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/build-companion.yml` | Builds platform artifacts, supports a one-run version override, and creates a draft release for a unique tag. |\n| `.github/workflows/promote-companion-release.yml` | Promotes one published release to selected public feeds. |\n| `.github/scripts/promote_companion_release.py` | Resolves release assets and writes the feed JSON files. |\n| `helgeklein/sambee-companion` | Dedicated public release repository for Companion GitHub Releases and committed feed source files. |\n| `release-repo/docs/feeds` | Source-controlled feed JSON files that promotion updates and commits. |\n\n## Channels And Consumers\n\nCompanion does not use separate binaries per channel. It uses one published release plus multiple mutable feed pointers.\n\nFor the public feed host, exact feed locations, and consumer-specific behavior, see [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/).\n\n## Published Artifact\n\nPublished Companion releases live in `helgeklein/sambee-companion` as GitHub Releases.\n\nEach release may contain:\n\n- Installer assets.\n- Tauri updater bundles.\n- `.sig` files for updater verification.\n- Release notes.\n\nRelease tags do not encode a channel.\nChannel visibility is decided only by the promoted feed files.\n\n## Operating Rules\n\n- Do not treat update channels as different binaries.\n- Do not patch broken published assets in place.\n- Build and publish a new release instead of replacing assets on an existing tag.\n- Assign a distinct prerelease suffix when you need another build before the official release.\n- Review whether you are changing Companion updater visibility, Sambee download visibility, or both.\n\nUse [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) for the system model behind those rules.\n", "0.8": "+++\ntitle = \"Companion Release Overview\"\n+++\n\nSambee Companion releases are built and published once, and later promoted across update channels by changing public feed files.\n\nKey differences between the Companion and Docker release paths:\n\n- Docker releases promote an already published container digest.\n- Companion releases promote an already published GitHub Release by rewriting feeds read by Companion's auto-updater and by the Sambee frontend.\n- Local Linux-hosted cross-checks can validate Windows-target compatibility, but they do not replace the Windows CI release build.\n\n## Summary\n\nIf you want to take a new Companion version to the `stable` update channel, follow this order:\n\n1. Update `VERSION` and run `./scripts/sync-version`.\n   - Git merge the reviewed `version-sync` changes.\n1. If you need a prerelease or test build before the official version, choose a distinct override version such as `0.8.0-beta.1` or `0.8.0-rc.1`.\n1. Run `Release: Build Companion Artifact` and select the target platforms.\n   - Leave `publish_version_override` empty for the checked-in version, or set it to the temporary prerelease version for this run.\n   - This creates draft release in the GitHub repo `helgeklein/sambee-companion`.\n1. Test the draft release.\n   - Download the installer from the releases artifacts, install and test.\n1. Publish the draft release.\n1. Run `Release: Promote Companion Release` for `test`.\n   - Validate both update behavior and direct-download metadata against the promoted feeds.\n1. Rerun `Release: Promote Companion Release` for `beta`, `stable`, and Sambee download metadata.\n\nCompanion release tags follow the `companion-v\u003cversion\u003e` pattern.\n\nThe build workflow refuses to reuse an existing Companion release tag, whether that release is still a draft or already published.\nWhen you need another pre-release candidate, assign a distinct suffix instead of rebuilding the same tag.\n\nOne published release can move from `test` to `beta` to `stable` without rebuilding binaries.\n\nRead the detailed pages in this order:\n\n1. [Build Companion Release](../build-companion-release/)\n1. [Promote Companion Release](../promote-companion-release/)\n1. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/)\n\n## Workflow Map\n\n| Workflow or system | When to use it | Result |\n|---|---|---|\n| Local `npm run check:rust:windows` | You want an early local Windows-target compatibility signal while working in Linux or the devcontainer. | Runs a Windows GNU target `cargo check` only. It does not create signed release assets. |\n| `Release: Build Companion Artifact` | You want to create release assets for one new Companion version or prerelease candidate. | Builds the selected platform set and creates a draft GitHub Release in `helgeklein/sambee-companion`, failing early if that tag already exists. |\n| `Release: Promote Companion Release` | A published Companion release is approved for one or more channels or for Sambee download metadata. | Rewrites the selected feed files in `docs/feeds` of the release repository. |\n| `helgeklein/sambee-companion` | You need the release repository that owns public Companion release artifacts. | Hosts immutable GitHub Release assets and stores the committed feed files under `docs/feeds` to be served by GitHub Pages. |\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/build-companion.yml` | Builds platform artifacts, supports a one-run version override, and creates a draft release for a unique tag. |\n| `.github/workflows/promote-companion-release.yml` | Promotes one published release to selected public feeds. |\n| `.github/scripts/promote_companion_release.py` | Resolves release assets and writes the feed JSON files. |\n| `helgeklein/sambee-companion` | Dedicated public release repository for Companion GitHub Releases and committed feed source files. |\n| `release-repo/docs/feeds` | Source-controlled feed JSON files that promotion updates and commits. |\n\n## Channels And Consumers\n\nCompanion does not use separate binaries per channel. It uses one published release plus multiple mutable feed pointers.\n\nFor the public feed host, exact feed locations, and consumer-specific behavior, see [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/).\n\n## Published Artifact\n\nPublished Companion releases live in `helgeklein/sambee-companion` as GitHub Releases.\n\nEach release may contain:\n\n- Installer assets.\n- Tauri updater bundles.\n- `.sig` files for updater verification.\n- Release notes.\n\nRelease tags do not encode a channel.\nChannel visibility is decided only by the promoted feed files.\n\n## Operating Rules\n\n- Do not treat update channels as different binaries.\n- Do not patch broken published assets in place.\n- Build and publish a new release instead of replacing assets on an existing tag.\n- Assign a distinct prerelease suffix when you need another build before the official release.\n- Review whether you are changing Companion updater visibility, Sambee download visibility, or both.\n- Treat local Windows GNU cross-checks as compatibility validation only.\n- Keep actual Windows artifact creation and signing in the CI release workflow.\n\nUse [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) for the system model behind those rules.\n", "0.9": "+++\ntitle = \"Companion Release Overview\"\n+++\n\nSambee Companion releases are built and published once, and later promoted across update channels by changing public feed files.\n\nKey differences between the Companion and Docker release paths:\n\n- Docker releases promote an already published container image.\n- Companion releases promote an already published GitHub Release by rewriting feeds read by Companion's auto-updater and by the Sambee frontend.\n- Docker images are available for Linux only, whereas Companion is a native app for Windows, Linux, and macOS. Each platform binary needs to be built on the respective OS.\n\n## Summary\n\nIf you want to take a new Companion version to the `stable` update channel, follow this order:\n\n1. Increment `VERSION` to the next `X.Y.Z` value and run `./scripts/sync-version`.\n1. Run `Release: Build Companion Artifact`:\n   - Select target platforms\n   - If the workflow's source version field is left blank, the artifact is built from the current commit in `main`, and the Git tag `build-vX.Y.Z` is created to reserve the version for the commit the artifact is built from.\n   - If a source version field is specified, the workflow verifies and repairs the artifact associated with the version via the Git tag used for reservation.\n1. The workflow:\n   - builds Companion\n   - signs the build artifacts\n   - creates one immutable draft release in in the [Companion GitHub repo](https://github.com/helgeklein/sambee-companion/releases).\n   - assigns a `companion-vX.Y.Z` tag to the draft release.\n1. Test the draft release.\n   - Download the installer from the release's artifacts, install and test.\n1. Publish the draft release. This:\n   - Makes the release eligible for promotion to the `test`, `beta`, and `stable` channels.\n   - Prevents additional build workflow runs changing the published Companion release.\n1. Ensure that a matching published public Sambee release `vX.Y.Z` exists.\n   - This authorizes the Companion workflow to promote a release.\n1. To promote the release to the update channels, run `Release: Promote Companion Release`:\n   - Select the channels: `test`, `beta`, and/or `stable`.\n   - Select whether to update the Sambee download metadata.\n\nThe workflow uses `build`, `recover-finalizer`, and `complete` states. A matching incomplete draft resumes only from recorded retained Actions artifacts; a complete draft or published release is not rebuilt. When a replacement is needed, increment `Z`, synchronize, commit on `main`, and build a new candidate.\n\nOne published release can move from `test` to `beta` to `stable` without rebuilding binaries.\n\nRead the detailed pages in this order:\n\n1. [Build Companion Release](../build-companion-release/)\n1. [Promote Companion Release](../promote-companion-release/)\n1. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/)\n\n## Workflow Map\n\n| Workflow or system | When to use it | Result |\n|---|---|---|\n| Local `npm run check:rust:windows` | You want an early local Windows-target compatibility signal while working in Linux or the devcontainer. | Runs a Windows GNU target `cargo check` only. It does not create signed release assets. |\n| `Release: Build Companion Artifact` | You want to create release assets for one canonical version. | Builds the selected platform set and creates, resumes, or reports the immutable draft GitHub Release in `helgeklein/sambee-companion`. |\n| `Release: Promote Companion Release` | A published Companion release is approved for one or more channels or for Sambee download metadata. | Rewrites the selected feed files in `docs/feeds` of the release repository. |\n| `helgeklein/sambee-companion` | You need the release repository that owns public Companion release artifacts. | Hosts immutable GitHub Release assets and stores the committed feed files under `docs/feeds` to be served by GitHub Pages. |\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/build-companion.yml` | Builds platform artifacts from a canonical source and creates or resumes one draft release for its immutable tag. |\n| `.github/workflows/promote-companion-release.yml` | Promotes one published release to selected public feeds. |\n| `.github/scripts/promote_companion_release.py` | Resolves release assets and writes the feed JSON files. |\n| `helgeklein/sambee-companion` | Dedicated public release repository for Companion GitHub Releases and committed feed source files. |\n| `release-repo/docs/feeds` | Source-controlled feed JSON files that promotion updates and commits. |\n\n## Channels And Consumers\n\nCompanion does not use separate binaries per channel. It uses one published release plus multiple mutable feed pointers.\n\nFor the public feed host, exact feed locations, and consumer-specific behavior, see [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/).\n\n## Published Artifact\n\nPublished Companion releases live in `helgeklein/sambee-companion` as GitHub Releases.\n\nEach release may contain:\n\n- Installer assets.\n- Tauri updater bundles.\n- `.sig` files for updater verification.\n- Release notes.\n\nRelease tags do not encode a channel.\nChannel visibility is decided only by the promoted feed files.\n\n## Operating Rules\n\n- Do not treat update channels as different binaries.\n- Do not patch broken published assets in place.\n- Build and publish a new release instead of replacing assets on an existing tag.\n- Increment the `Z` build sequence when you need another candidate.\n- Review whether you are changing Companion updater visibility, Sambee download visibility, or both.\n- Treat local Windows GNU cross-checks as compatibility validation only.\n- Keep actual Windows artifact creation and signing in the CI release workflow.\n\nUse [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) for the system model behind those rules.\n", "1.0": "+++\ntitle = \"Companion Release Overview\"\n+++\n\nSambee Companion releases are built and published once. A successful build automatically promotes the release to `test`; later channel promotion rewrites public feed files without rebuilding binaries.\n\nKey differences between the Companion and Docker release paths:\n\n- Docker releases promote an already published container image.\n- Companion releases promote an already published GitHub Release by rewriting feeds read by Companion's auto-updater and by the Sambee frontend.\n- Docker images are available for Linux only, whereas Companion is a native app for Windows, Linux, and macOS. Each platform binary needs to be built on the respective OS.\n\n## Summary\n\nIf you want to take a new Companion version to `stable`, follow this order:\n\n1. Increment `VERSION` to the next `X.Y.Z` value and run `./scripts/sync-version`.\n1. Run `Release: Build Companion Artifact`:\n   - Select target platforms\n   - If the workflow's source version field is left blank, the artifact is built from the current commit in `main`, and the Git tag `build-vX.Y.Z` is created to reserve the version for the commit the artifact is built from.\n   - If a source version field is specified, the workflow verifies and repairs the artifact associated with the version via the Git tag used for reservation.\n1. The workflow builds and signs Companion, publishes the verified immutable release in the [Companion GitHub repo](https://github.com/helgeklein/sambee-companion/releases), promotes it to `test`, and cleans up obsolete releases.\n1. Test the published release through the `test` channel or by installing its release assets.\n1. Run `Release: Promote Companion Release` when the release is approved for `beta`, `stable`, or Sambee download metadata.\n\nOne published release can move from `test` to `beta` to `stable` without rebuilding binaries.\n\nRead the detailed pages in this order:\n\n1. [Build Companion Release](../build-companion-release/)\n1. [Promote Companion Release](../promote-companion-release/)\n1. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/)\n1. [Companion Release Cleanup](../companion-release-cleanup/)\n\n## Workflow Map\n\n| Workflow | When to use it | Result |\n|---|---|---|\n| Local `npm run check:rust:windows` | You want an early local Windows-target compatibility signal while working in Linux or the devcontainer. | Runs a Windows GNU target `cargo check` only. It does not create signed release assets. |\n| `Release: Build Companion Artifact` | You want to create release assets for one canonical version. | Builds the selected platform set, publishes the verified immutable GitHub Release, promotes only `test`, and cleans up obsolete releases. |\n| `Release: Promote Companion Release` | A published Companion release is approved for one or more channels or for Sambee download metadata. | Rewrites the selected feed files in `docs/feeds` of the release repository. |\n| `Maintenance: Clean Up Companion Releases` | You want to reconcile release retention outside a promotion run. | Validates the feed markers and deletes obsolete GitHub Releases. |\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/build-companion.yml` | Builds platform artifacts from a canonical source, publishes the verified release, promotes `test`, and runs cleanup. |\n| `.github/workflows/promote-companion-release.yml` | Promotes one published release to selected public feeds. |\n| `.github/scripts/promote_companion_release.py` | Resolves release assets and writes the feed JSON files. |\n| `.github/scripts/cleanup_companion_releases.py` | Validates feed references and applies Companion release retention. |\n| [helgeklein/sambee-companion](https://github.com/helgeklein/sambee-companion/) | Dedicated public release repository for Companion GitHub Releases and committed feed source files. |\n| `release-repo/docs/feeds` | Source-controlled feed JSON files that promotion updates and commits ([docs](../companion-channels-feeds-and-downloads/)). |\n\n## Published Artifact\n\nPublished Companion releases live in [helgeklein/sambee-companion](https://github.com/helgeklein/sambee-companion/) as GitHub Releases.\n\nEach release may contain:\n\n- Installer assets.\n- Tauri updater bundles.\n- `.sig` files for updater verification.\n- Release notes.\n", "2.0": "+++\ntitle = \"Companion Release Overview\"\n+++\n\nSambee Companion releases are built and published once. A successful build automatically promotes the release to `test`; later channel promotion rewrites public feed files without rebuilding binaries.\n\nKey differences between the Companion and Docker release paths:\n\n- Docker releases promote an already published container image.\n- Companion releases promote an already published GitHub Release by rewriting feeds read by Companion's auto-updater and by the Sambee frontend.\n- Docker images are available for Linux only, whereas Companion is a native app for Windows, Linux, and macOS. Each platform binary needs to be built on the respective OS.\n\n## Summary\n\nIf you want to take a new Companion version to `stable`, follow this order:\n\n1. Increment `VERSION` to the next `X.Y.Z` value and run `./scripts/sync-version`.\n1. Run `Release: Build Companion Artifact`:\n   - Select target platforms\n   - If the workflow's source version field is left blank, the artifact is built from the current commit in `main`, and the Git tag `build-vX.Y.Z` is created to reserve the version for the commit the artifact is built from.\n   - If a source version field is specified, the workflow verifies and repairs the artifact associated with the version via the Git tag used for reservation.\n1. The workflow builds and signs Companion, publishes the verified immutable release in the [Companion GitHub repo](https://github.com/sambee-app/sambee-companion/releases), promotes it to `test`, and cleans up obsolete releases.\n1. Test the published release through the `test` channel or by installing its release assets.\n1. Run `Release: Promote Companion Release` when the release is approved for `beta`, `stable`, or Sambee download metadata.\n\nOne published release can move from `test` to `beta` to `stable` without rebuilding binaries.\n\nRead the detailed pages in this order:\n\n1. [Build Companion Release](../build-companion-release/)\n1. [Promote Companion Release](../promote-companion-release/)\n1. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/)\n1. [Companion Release Cleanup](../companion-release-cleanup/)\n\n## Workflow Map\n\n| Workflow | When to use it | Result |\n|---|---|---|\n| Local `npm run check:rust:windows` | You want an early local Windows-target compatibility signal while working in Linux or the devcontainer. | Runs a Windows GNU target `cargo check` only. It does not create signed release assets. |\n| `Release: Build Companion Artifact` | You want to create release assets for one canonical version. | Builds the selected platform set, publishes the verified immutable GitHub Release, promotes only `test`, and cleans up obsolete releases. |\n| `Release: Promote Companion Release` | A published Companion release is approved for one or more channels or for Sambee download metadata. | Rewrites the selected feed files in `docs/feeds` of the release repository. |\n| `Maintenance: Clean Up Companion Releases` | You want to reconcile release retention outside a promotion run. | Validates the feed markers and deletes obsolete GitHub Releases. |\n\n## Main Control Points\n\n| File or system | Role |\n|---|---|\n| `.github/workflows/build-companion.yml` | Builds platform artifacts from a canonical source, publishes the verified release, promotes `test`, and runs cleanup. |\n| `.github/workflows/promote-companion-release.yml` | Promotes one published release to selected public feeds. |\n| `.github/scripts/promote_companion_release.py` | Resolves release assets and writes the feed JSON files. |\n| `.github/scripts/cleanup_companion_releases.py` | Validates feed references and applies Companion release retention. |\n| [sambee-app/sambee-companion](https://github.com/sambee-app/sambee-companion/) | Dedicated public release repository for Companion GitHub Releases and committed feed source files. |\n| `release-repo/docs/feeds` | Source-controlled feed JSON files that promotion updates and commits ([docs](../companion-channels-feeds-and-downloads/)). |\n\n## Published Artifact\n\nPublished Companion releases live in [sambee-app/sambee-companion](https://github.com/sambee-app/sambee-companion/) as GitHub Releases.\n\nEach release may contain:\n\n- Installer assets.\n- Tauri updater bundles.\n- `.sig` files for updater verification.\n- Release notes.\n"}, "flags": {"has_branched": true, "has_inherited": false, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/release-and-versioning/build-companion-release", "parent_id": "section:developer-guide/release-and-versioning", "depth": 2, "kind": "page", "label": "build-companion-release", "title": "Build Companion Release", "path": "developer-guide/release-and-versioning/build-companion-release", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "branched", "source_version": "0.7", "diff_added": 27, "diff_removed": 83}, "1.0": {"state": "branched", "source_version": "0.9", "diff_added": 25, "diff_removed": 39}, "2.0": {"state": "inherited", "source_version": "1.0"}}, "content_versions": {"0.7": "+++\ntitle = \"Build Companion Release\"\n+++\n\nThis is step 1 of the Companion release flow.\n\nUse this workflow to create the published Companion release assets for one version. GitHub Actions displays this workflow as `Release: Build Companion Artifact`. It builds release artifacts and creates a draft GitHub Release for a new, unique Companion tag, but it does not decide which update channels see that release.\n\n## Use It When\n\nRun the build workflow when:\n\n- You want to publish a new Companion version.\n- You want fresh installer and updater artifacts in the public Companion release repository.\n- You are preparing a release that may later be promoted to `test`, `beta`, `stable`, or Sambee download metadata.\n\nDo not use this workflow to change channel visibility.\nThat is the job of `Release: Promote Companion Release`.\n\n## Input\n\nThe manual workflow exposes one optional version override plus one checkbox per platform:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `publish_version_override` | Use a temporary version for this run instead of the checked-in `VERSION` value. Enter `major.minor.patch` with an optional prerelease suffix and optional build metadata. | Set it for prerelease, beta, rc, or test builds such as `0.8.0-beta.1` without changing the repository version. |\n| `build_all_platforms` | Include every supported platform in one run. | Check it for a normal full release. |\n| `build_linux_x64` | Include the Linux x64 build. | Check it when you need Linux release assets. |\n| `build_macos_arm64` | Include the macOS ARM64 build. | Check it when you need Apple Silicon macOS release assets. |\n| `build_windows_x64` | Include the Windows x64 build. | Check it when you need the standard Windows desktop release assets. |\n| `build_windows_arm64` | Include the Windows ARM64 build. | Check it when you need Windows on ARM release assets. |\n\nCurrent platform checkboxes are:\n\n- `build_all_platforms`\n- `build_linux_x64`\n- `build_macos_arm64`\n- `build_windows_x64`\n- `build_windows_arm64`\n\nIf you leave `publish_version_override` empty, the workflow uses the checked-in `VERSION` value and verifies that all synced metadata files are already committed.\nIf you set `publish_version_override`, the workflow writes that value into the synced Companion metadata files for this run only.\n\nUse the same version shape you would expect from a release tag:\n\n- `0.8.0` for a plain release version\n- `0.8.0-beta.1` or `0.8.0-rc.1` for prerelease candidates\n- `0.8.0-test.1` for temporary test builds\n- `0.8.0-beta.1+build.5` if you need build metadata\n\nIn other words, the accepted structure is `major.minor.patch`, optionally followed by `-prerelease` and then `+build-metadata`.\n\nThe workflow fails early if the resulting release tag already exists in `helgeklein/sambee-companion`, whether that release is still a draft or already published.\nChoose a distinct prerelease suffix such as `-beta.1` or `-rc.1` when you need another build before the official release.\n\nIf you check `build_all_platforms`, the workflow builds the full matrix and ignores the per-platform checkboxes.\nIf you leave every checkbox cleared, the workflow does not build anything.\nCheck only the platforms you want when you deliberately need a partial release.\n\n## What It Does\n\nBefore packaging, the workflow:\n\n1. Checks out the main repository.\n2. Resolves the effective Companion version from either the checked-in `VERSION` file or `publish_version_override`.\n3. Fails early if the resulting release tag already exists in `helgeklein/sambee-companion` as either a draft or a published release.\n4. Either runs version-sync verification or applies the temporary override version for this run.\n5. Builds the platform matrix derived from the checked boxes.\n6. Uses Tauri packaging to upload assets into a draft release in `helgeklein/sambee-companion`.\n\nThe build matrix is currently configured for:\n\n- Linux x64.\n- macOS ARM64.\n- Windows x64.\n- Windows ARM64.\n\nIf you build only a subset, the resulting release exposes only that subset.\nPromotion works from the assets actually present in the published release, not from an assumed full matrix.\n\n## Published Output\n\nThe workflow publishes assets into a draft GitHub Release in `helgeklein/sambee-companion`.\n\nThat release can contain:\n\n- Installer assets.\n- Tauri updater bundles.\n- `.sig` files for updater verification.\n- Release notes.\n\nThe workflow uses the tag format `companion-v\u003ceffective-version\u003e`.\n\nThat means an override such as `0.8.0-beta.1` produces the tag `companion-v0.8.0-beta.1`.\n\nChannel visibility is still unset at this stage.\nThe build is only a published candidate until a later promotion updates the feed files.\n\n## Review Before Publish\n\nBefore you publish the draft release, verify:\n\n- The version metadata is correct.\n- The release tag is the distinct version you intended to publish.\n- The expected platform assets are present.\n- The updater bundle and `.sig` pairs look complete for the platforms you expect to promote.\n- The release notes are acceptable for public distribution.\n\nIf the draft contents are wrong, fix the release process and produce a new release instead of trying to patch channel metadata around a bad artifact set.\n\n## Run the Workflow\n\nUse this order when you are preparing a Companion release:\n\n1. For an official release, merge the version-sync changes for the checked-in version you want to ship.\n2. For a prerelease or test build, decide the distinct override version you want to use for this run, for example `0.8.0-beta.1`.\n3. Start `Release: Build Companion Artifact` from the commit you want to release.\n4. Leave `publish_version_override` empty for the checked-in version, or set it to the temporary prerelease version you want for this run.\n5. Check `build_all_platforms` for a normal full release, or check only the specific platform boxes you want for a partial release. If you leave all boxes cleared, the workflow skips artifact builds.\n6. Wait for the workflow to create the draft release in `helgeklein/sambee-companion`.\n7. Review the uploaded assets and publish the draft release.\n8. Continue with [Promote Companion Release](../promote-companion-release/).\n", "0.8": "+++\ntitle = \"Build Companion Release\"\n+++\n\nThis is step 1 of the Companion release flow.\n\nUse this workflow to create the published Companion release assets for one version. GitHub Actions displays this workflow as `Release: Build Companion Artifact`. It builds release artifacts and creates a draft GitHub Release for a new, unique Companion tag, but it does not decide which update channels see that release.\n\n## Use It When\n\nRun the build workflow when:\n\n- You want to publish a new Companion version.\n- You want fresh installer and updater artifacts in the public Companion release repository.\n- You are preparing a release that may later be promoted to `test`, `beta`, `stable`, or Sambee download metadata.\n\nDo not use this workflow to change channel visibility.\nThat is the job of `Release: Promote Companion Release`.\n\n## Input\n\nThe manual workflow exposes one optional version override plus one checkbox per platform:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `publish_version_override` | Use a temporary version for this run instead of the checked-in `VERSION` value. Enter `major.minor.patch` with an optional prerelease suffix and optional build metadata. | Set it for prerelease, beta, rc, or test builds such as `0.8.0-beta.1` without changing the repository version. |\n| `build_all_platforms` | Include every supported platform in one run. | Check it for a normal full release. |\n| `build_linux_x64` | Include the Linux x64 build. | Check it when you need Linux release assets. |\n| `build_macos_arm64` | Include the macOS ARM64 build. | Check it when you need Apple Silicon macOS release assets. |\n| `build_windows_x64` | Include the Windows x64 build. | Check it when you need the standard Windows desktop release assets. |\n| `build_windows_arm64` | Include the Windows ARM64 build. | Check it when you need Windows on ARM release assets. |\n\nCurrent platform checkboxes are:\n\n- `build_all_platforms`\n- `build_linux_x64`\n- `build_macos_arm64`\n- `build_windows_x64`\n- `build_windows_arm64`\n\nIf you leave `publish_version_override` empty, the workflow uses the checked-in `VERSION` value and verifies that all synced metadata files are already committed.\nIf you set `publish_version_override`, the workflow writes that value into the synced Companion metadata files for this run only.\n\nUse the same version shape you would expect from a release tag:\n\n- `0.8.0` for a plain release version\n- `0.8.0-beta.1` or `0.8.0-rc.1` for prerelease candidates\n- `0.8.0-test.1` for temporary test builds\n- `0.8.0-beta.1+build.5` if you need build metadata\n\nIn other words, the accepted structure is `major.minor.patch`, optionally followed by `-prerelease` and then `+build-metadata`.\n\nThe workflow fails early if the resulting release tag already exists in `helgeklein/sambee-companion`, whether that release is still a draft or already published.\nChoose a distinct prerelease suffix such as `-beta.1` or `-rc.1` when you need another build before the official release.\n\nIf you check `build_all_platforms`, the workflow builds the full matrix and ignores the per-platform checkboxes.\nIf you leave every checkbox cleared, the workflow does not build anything.\nCheck only the platforms you want when you deliberately need a partial release.\n\n## What It Does\n\nBefore packaging, the workflow:\n\n1. Checks out the main repository.\n2. Resolves the effective Companion version from either the checked-in `VERSION` file or `publish_version_override`.\n3. Fails early if the resulting release tag already exists in `helgeklein/sambee-companion` as either a draft or a published release.\n4. Either runs version-sync verification or applies the temporary override version for this run.\n5. Builds the platform matrix derived from the checked boxes.\n6. Uses Tauri packaging to upload assets into a draft release in `helgeklein/sambee-companion`.\n\nThe build matrix is currently configured for:\n\n- Linux x64.\n- macOS ARM64.\n- Windows x64.\n- Windows ARM64.\n\nIf you build only a subset, the resulting release exposes only that subset.\nPromotion works from the assets actually present in the published release, not from an assumed full matrix.\n\n## Published Output\n\nThe workflow publishes assets into a draft GitHub Release in `helgeklein/sambee-companion`.\n\nThat release can contain:\n\n- Installer assets.\n- Tauri updater bundles.\n- `.sig` files for updater verification.\n- Release notes.\n\nThe workflow uses the tag format `companion-v\u003ceffective-version\u003e`.\n\nThat means an override such as `0.8.0-beta.1` produces the tag `companion-v0.8.0-beta.1`.\n\nChannel visibility is still unset at this stage.\nThe build is only a published candidate until a later promotion updates the feed files.\n\n## Review Before Publish\n\nBefore you publish the draft release, verify:\n\n- The version metadata is correct.\n- The release tag is the distinct version you intended to publish.\n- The expected platform assets are present.\n- The updater bundle and `.sig` pairs look complete for the platforms you expect to promote.\n- The release notes are acceptable for public distribution.\n\nIf the draft contents are wrong, fix the release process and produce a new release instead of trying to patch channel metadata around a bad artifact set.\n\n## Run the Workflow\n\nUse this order when you are preparing a Companion release:\n\n1. For an official release, merge the version-sync changes for the checked-in version you want to ship.\n2. For a prerelease or test build, decide the distinct override version you want to use for this run, for example `0.8.0-beta.1`.\n3. Start `Release: Build Companion Artifact` from the commit you want to release.\n4. Leave `publish_version_override` empty for the checked-in version, or set it to the temporary prerelease version you want for this run.\n5. Check `build_all_platforms` for a normal full release, or check only the specific platform boxes you want for a partial release. If you leave all boxes cleared, the workflow skips artifact builds.\n6. Wait for the workflow to create the draft release in `helgeklein/sambee-companion`.\n7. Review the uploaded assets and publish the draft release.\n8. Continue with [Promote Companion Release](../promote-companion-release/).\n", "0.9": "+++\ntitle = \"Build Companion Release\"\n+++\n\nThis is step 1 of the Companion release flow.\n\nUse this workflow to create Companion release assets for one immutable build version. GitHub Actions displays this workflow as `Release: Build Companion Artifact`. It creates builds for the selected platforms, which are then uploaded to the GitHub draft release by a finalizer.\n\n## Input\n\nThe manual workflow exposes an optional existing build-version selector plus one checkbox per platform:\n\n| Input | What it means |\n|---|---|\n| `build_version` | Build the commit with the `build-vX.Y.Z` tag. Leave empty to build the latest commit and set the `build-vX.Y.Z` tag on that commit. |\n| `build_all_platforms` | Include every supported platform in one run. |\n| `build_linux_x64` | Include the Linux x64 build. |\n| `build_macos_arm64` | Include the macOS ARM64 build. |\n| `build_windows_x64` | Include the Windows x64 build. |\n| `build_windows_arm64` | Include the Windows ARM64 build. |\n\nNew builds must be dispatched from `main`. The workflow verifies synchronized metadata, reserves `build-vX.Y.Z` for the exact source commit, and rejects any version that is not plain numeric `X.Y.Z`. It never changes an existing build tag.\n\nIf you check `build_all_platforms`, the workflow builds the full matrix and ignores the per-platform checkboxes.\nIf you leave every checkbox cleared, the workflow does not build anything.\nCheck only the platforms you want when you deliberately need a partial release.\n\n## What It Does\n\nBefore packaging, the workflow:\n\n1. Checks out the main repository.\n2. Resolves the canonical `build-vX.Y.Z` source commit or assigns it to the latest commit.\n3. Verifies synchronized version metadata.\n4. Builds the platform matrix derived from the checked boxes.\n5. Writes a per-platform artifact manifest with package names, SHA-256 checksums, installer/updater/signature roles, platform, and target; then uploads uniquely named private Actions artifacts.\n6. The finalizer downloads every retained artifact, verifies the manifests and complete package sets, writes a public aggregate manifest, provenance, and completion marker, then creates or resumes the external draft release.\n\nIf you build only a subset, the resulting release exposes only that subset.\nPromotion works from the assets actually present in the published release, not from an assumed full matrix.\n\n## Build Output\n\nThe finalizer uploads assets into a draft GitHub Release in `helgeklein/sambee-companion`.\n\nThat release can contain:\n\n- Installer assets.\n- Tauri updater bundles.\n- `.sig` files for updater verification.\n- A public aggregate artifact manifest, uploaded before all package assets.\n- Release provenance and a completion marker binding the release tag, aggregate-manifest digest, provenance digest, and exact expected assets.\n\n### Recovery And Immutability\n\nThe draft GitHub release is immutable once any asset is present: the finalizer uploads a missing asset or accepts an existing byte-identical asset, and rejects a conflicting replacement.\n\nIf a finalizer is interrupted, a later run uses the exact retained Actions artifact IDs, digests, originating run ID, run attempt, platform, and target recorded in draft provenance. It does not rebuild matrix artifacts. Expired, missing, ambiguous, or mismatched retained artifacts require a new `Z` candidate.\n\nGitHub Actions concurrency is mutual exclusion, not a FIFO queue: only one pending run is retained for the `companion-release-publication` lock. Avoid stacking dispatches. A superseded pending dispatch is safe to submit again because it never reached a publication step.\n\n## Review and Publish\n\nReview the draft GitHub release created or updated by this workflow. Then publish it.\n\nPublishing assigns the tag `companion-vX.Y.Z`.\n", "1.0": "+++\ntitle = \"Build Companion Release\"\n+++\n\nThis is step 1 of the Companion release flow.\n\nUse `Release: Build Companion Artifact` to create one immutable Companion release from a canonical build version. The workflow builds the selected platforms, verifies their manifests, publishes the GitHub Release automatically, promotes it to the `test` updater channel, and removes obsolete releases.\n\n## Input\n\nThe workflow accepts an optional existing build version and platform checkboxes.\n\n| Input | What it means |\n|---|---|\n| `build_version` | Build the commit reserved by `build-vX.Y.Z`. Leave it empty to reserve the current `main` commit. |\n| `build_all_platforms` | Include every supported platform. |\n| Platform checkboxes | Build only the selected platforms. |\n\nNew builds must start from `main`. The workflow verifies synchronized version metadata, reserves the exact source commit, and accepts only plain numeric `X.Y.Z` versions. It never changes an existing build tag.\n\nIf no platform is selected, the workflow does not create or promote a release.\n\n## What It Does\n\nThe workflow:\n\n1. Resolves the canonical `build-vX.Y.Z` source commit.\n1. Builds, signs, and records a manifest for every selected platform.\n1. Downloads and verifies the retained build artifacts in the finalizer.\n1. Creates a private provisional GitHub Release while assets are uploaded.\n1. Verifies the aggregate manifest, provenance, completion marker, and every release asset.\n1. Publishes `companion-vX.Y.Z` automatically after verification succeeds.\n1. Promotes only the Companion `test` updater feed to the published release.\n1. Cleans up obsolete Companion GitHub Releases.\n\nThe temporary draft is an upload and recovery boundary, not a review step. A release becomes public only after its complete verified asset set is present.\n\n## Recovery And Immutability\n\nOnce an asset is present, the provisional release accepts only a missing asset or an existing byte-identical asset. A conflicting replacement fails.\n\nIf finalization is interrupted, a later run uses the exact retained Actions artifact IDs, digests, run ID, attempt, platform, and target recorded in provenance. It does not rebuild the artifact matrix. Expired, missing, ambiguous, or mismatched retained artifacts require a new `Z` candidate.\n\nIf publication succeeds but the `test` feed push fails, rerun the build workflow with the same build version. It verifies the already published immutable release and retries promotion without rebuilding binaries.\n\nGitHub Actions concurrency is mutual exclusion, not a FIFO queue: only one pending run is retained for `companion-release-publication`. Avoid stacking dispatches.\n\n## What Happens Next\n\nThe automatic flow changes only `test`. Use [Promote Companion Release](../promote-companion-release/) later when the same published release is approved for `beta`, `stable`, or Sambee download metadata.\n\nSee [Companion Release Cleanup](../companion-release-cleanup/) for the retention policy.", "2.0": "+++\ntitle = \"Build Companion Release\"\n+++\n\nThis is step 1 of the Companion release flow.\n\nUse `Release: Build Companion Artifact` to create one immutable Companion release from a canonical build version. The workflow builds the selected platforms, verifies their manifests, publishes the GitHub Release automatically, promotes it to the `test` updater channel, and removes obsolete releases.\n\n## Input\n\nThe workflow accepts an optional existing build version and platform checkboxes.\n\n| Input | What it means |\n|---|---|\n| `build_version` | Build the commit reserved by `build-vX.Y.Z`. Leave it empty to reserve the current `main` commit. |\n| `build_all_platforms` | Include every supported platform. |\n| Platform checkboxes | Build only the selected platforms. |\n\nNew builds must start from `main`. The workflow verifies synchronized version metadata, reserves the exact source commit, and accepts only plain numeric `X.Y.Z` versions. It never changes an existing build tag.\n\nIf no platform is selected, the workflow does not create or promote a release.\n\n## What It Does\n\nThe workflow:\n\n1. Resolves the canonical `build-vX.Y.Z` source commit.\n1. Builds, signs, and records a manifest for every selected platform.\n1. Downloads and verifies the retained build artifacts in the finalizer.\n1. Creates a private provisional GitHub Release while assets are uploaded.\n1. Verifies the aggregate manifest, provenance, completion marker, and every release asset.\n1. Publishes `companion-vX.Y.Z` automatically after verification succeeds.\n1. Promotes only the Companion `test` updater feed to the published release.\n1. Cleans up obsolete Companion GitHub Releases.\n\nThe temporary draft is an upload and recovery boundary, not a review step. A release becomes public only after its complete verified asset set is present.\n\n## Recovery And Immutability\n\nOnce an asset is present, the provisional release accepts only a missing asset or an existing byte-identical asset. A conflicting replacement fails.\n\nIf finalization is interrupted, a later run uses the exact retained Actions artifact IDs, digests, run ID, attempt, platform, and target recorded in provenance. It does not rebuild the artifact matrix. Expired, missing, ambiguous, or mismatched retained artifacts require a new `Z` candidate.\n\nIf publication succeeds but the `test` feed push fails, rerun the build workflow with the same build version. It verifies the already published immutable release and retries promotion without rebuilding binaries.\n\nGitHub Actions concurrency is mutual exclusion, not a FIFO queue: only one pending run is retained for `companion-release-publication`. Avoid stacking dispatches.\n\n## What Happens Next\n\nThe automatic flow changes only `test`. Use [Promote Companion Release](../promote-companion-release/) later when the same published release is approved for `beta`, `stable`, or Sambee download metadata.\n\nSee [Companion Release Cleanup](../companion-release-cleanup/) for the retention policy."}, "page_contents": {"0.7": "+++\ntitle = \"Build Companion Release\"\n+++\n\nThis is step 1 of the Companion release flow.\n\nUse this workflow to create the published Companion release assets for one version. GitHub Actions displays this workflow as `Release: Build Companion Artifact`. It builds release artifacts and creates a draft GitHub Release for a new, unique Companion tag, but it does not decide which update channels see that release.\n\n## Use It When\n\nRun the build workflow when:\n\n- You want to publish a new Companion version.\n- You want fresh installer and updater artifacts in the public Companion release repository.\n- You are preparing a release that may later be promoted to `test`, `beta`, `stable`, or Sambee download metadata.\n\nDo not use this workflow to change channel visibility.\nThat is the job of `Release: Promote Companion Release`.\n\n## Input\n\nThe manual workflow exposes one optional version override plus one checkbox per platform:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `publish_version_override` | Use a temporary version for this run instead of the checked-in `VERSION` value. Enter `major.minor.patch` with an optional prerelease suffix and optional build metadata. | Set it for prerelease, beta, rc, or test builds such as `0.8.0-beta.1` without changing the repository version. |\n| `build_all_platforms` | Include every supported platform in one run. | Check it for a normal full release. |\n| `build_linux_x64` | Include the Linux x64 build. | Check it when you need Linux release assets. |\n| `build_macos_arm64` | Include the macOS ARM64 build. | Check it when you need Apple Silicon macOS release assets. |\n| `build_windows_x64` | Include the Windows x64 build. | Check it when you need the standard Windows desktop release assets. |\n| `build_windows_arm64` | Include the Windows ARM64 build. | Check it when you need Windows on ARM release assets. |\n\nCurrent platform checkboxes are:\n\n- `build_all_platforms`\n- `build_linux_x64`\n- `build_macos_arm64`\n- `build_windows_x64`\n- `build_windows_arm64`\n\nIf you leave `publish_version_override` empty, the workflow uses the checked-in `VERSION` value and verifies that all synced metadata files are already committed.\nIf you set `publish_version_override`, the workflow writes that value into the synced Companion metadata files for this run only.\n\nUse the same version shape you would expect from a release tag:\n\n- `0.8.0` for a plain release version\n- `0.8.0-beta.1` or `0.8.0-rc.1` for prerelease candidates\n- `0.8.0-test.1` for temporary test builds\n- `0.8.0-beta.1+build.5` if you need build metadata\n\nIn other words, the accepted structure is `major.minor.patch`, optionally followed by `-prerelease` and then `+build-metadata`.\n\nThe workflow fails early if the resulting release tag already exists in `helgeklein/sambee-companion`, whether that release is still a draft or already published.\nChoose a distinct prerelease suffix such as `-beta.1` or `-rc.1` when you need another build before the official release.\n\nIf you check `build_all_platforms`, the workflow builds the full matrix and ignores the per-platform checkboxes.\nIf you leave every checkbox cleared, the workflow does not build anything.\nCheck only the platforms you want when you deliberately need a partial release.\n\n## What It Does\n\nBefore packaging, the workflow:\n\n1. Checks out the main repository.\n2. Resolves the effective Companion version from either the checked-in `VERSION` file or `publish_version_override`.\n3. Fails early if the resulting release tag already exists in `helgeklein/sambee-companion` as either a draft or a published release.\n4. Either runs version-sync verification or applies the temporary override version for this run.\n5. Builds the platform matrix derived from the checked boxes.\n6. Uses Tauri packaging to upload assets into a draft release in `helgeklein/sambee-companion`.\n\nThe build matrix is currently configured for:\n\n- Linux x64.\n- macOS ARM64.\n- Windows x64.\n- Windows ARM64.\n\nIf you build only a subset, the resulting release exposes only that subset.\nPromotion works from the assets actually present in the published release, not from an assumed full matrix.\n\n## Published Output\n\nThe workflow publishes assets into a draft GitHub Release in `helgeklein/sambee-companion`.\n\nThat release can contain:\n\n- Installer assets.\n- Tauri updater bundles.\n- `.sig` files for updater verification.\n- Release notes.\n\nThe workflow uses the tag format `companion-v\u003ceffective-version\u003e`.\n\nThat means an override such as `0.8.0-beta.1` produces the tag `companion-v0.8.0-beta.1`.\n\nChannel visibility is still unset at this stage.\nThe build is only a published candidate until a later promotion updates the feed files.\n\n## Review Before Publish\n\nBefore you publish the draft release, verify:\n\n- The version metadata is correct.\n- The release tag is the distinct version you intended to publish.\n- The expected platform assets are present.\n- The updater bundle and `.sig` pairs look complete for the platforms you expect to promote.\n- The release notes are acceptable for public distribution.\n\nIf the draft contents are wrong, fix the release process and produce a new release instead of trying to patch channel metadata around a bad artifact set.\n\n## Run the Workflow\n\nUse this order when you are preparing a Companion release:\n\n1. For an official release, merge the version-sync changes for the checked-in version you want to ship.\n2. For a prerelease or test build, decide the distinct override version you want to use for this run, for example `0.8.0-beta.1`.\n3. Start `Release: Build Companion Artifact` from the commit you want to release.\n4. Leave `publish_version_override` empty for the checked-in version, or set it to the temporary prerelease version you want for this run.\n5. Check `build_all_platforms` for a normal full release, or check only the specific platform boxes you want for a partial release. If you leave all boxes cleared, the workflow skips artifact builds.\n6. Wait for the workflow to create the draft release in `helgeklein/sambee-companion`.\n7. Review the uploaded assets and publish the draft release.\n8. Continue with [Promote Companion Release](../promote-companion-release/).\n", "0.8": "+++\ntitle = \"Build Companion Release\"\n+++\n\nThis is step 1 of the Companion release flow.\n\nUse this workflow to create the published Companion release assets for one version. GitHub Actions displays this workflow as `Release: Build Companion Artifact`. It builds release artifacts and creates a draft GitHub Release for a new, unique Companion tag, but it does not decide which update channels see that release.\n\n## Use It When\n\nRun the build workflow when:\n\n- You want to publish a new Companion version.\n- You want fresh installer and updater artifacts in the public Companion release repository.\n- You are preparing a release that may later be promoted to `test`, `beta`, `stable`, or Sambee download metadata.\n\nDo not use this workflow to change channel visibility.\nThat is the job of `Release: Promote Companion Release`.\n\n## Input\n\nThe manual workflow exposes one optional version override plus one checkbox per platform:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `publish_version_override` | Use a temporary version for this run instead of the checked-in `VERSION` value. Enter `major.minor.patch` with an optional prerelease suffix and optional build metadata. | Set it for prerelease, beta, rc, or test builds such as `0.8.0-beta.1` without changing the repository version. |\n| `build_all_platforms` | Include every supported platform in one run. | Check it for a normal full release. |\n| `build_linux_x64` | Include the Linux x64 build. | Check it when you need Linux release assets. |\n| `build_macos_arm64` | Include the macOS ARM64 build. | Check it when you need Apple Silicon macOS release assets. |\n| `build_windows_x64` | Include the Windows x64 build. | Check it when you need the standard Windows desktop release assets. |\n| `build_windows_arm64` | Include the Windows ARM64 build. | Check it when you need Windows on ARM release assets. |\n\nCurrent platform checkboxes are:\n\n- `build_all_platforms`\n- `build_linux_x64`\n- `build_macos_arm64`\n- `build_windows_x64`\n- `build_windows_arm64`\n\nIf you leave `publish_version_override` empty, the workflow uses the checked-in `VERSION` value and verifies that all synced metadata files are already committed.\nIf you set `publish_version_override`, the workflow writes that value into the synced Companion metadata files for this run only.\n\nUse the same version shape you would expect from a release tag:\n\n- `0.8.0` for a plain release version\n- `0.8.0-beta.1` or `0.8.0-rc.1` for prerelease candidates\n- `0.8.0-test.1` for temporary test builds\n- `0.8.0-beta.1+build.5` if you need build metadata\n\nIn other words, the accepted structure is `major.minor.patch`, optionally followed by `-prerelease` and then `+build-metadata`.\n\nThe workflow fails early if the resulting release tag already exists in `helgeklein/sambee-companion`, whether that release is still a draft or already published.\nChoose a distinct prerelease suffix such as `-beta.1` or `-rc.1` when you need another build before the official release.\n\nIf you check `build_all_platforms`, the workflow builds the full matrix and ignores the per-platform checkboxes.\nIf you leave every checkbox cleared, the workflow does not build anything.\nCheck only the platforms you want when you deliberately need a partial release.\n\n## What It Does\n\nBefore packaging, the workflow:\n\n1. Checks out the main repository.\n2. Resolves the effective Companion version from either the checked-in `VERSION` file or `publish_version_override`.\n3. Fails early if the resulting release tag already exists in `helgeklein/sambee-companion` as either a draft or a published release.\n4. Either runs version-sync verification or applies the temporary override version for this run.\n5. Builds the platform matrix derived from the checked boxes.\n6. Uses Tauri packaging to upload assets into a draft release in `helgeklein/sambee-companion`.\n\nThe build matrix is currently configured for:\n\n- Linux x64.\n- macOS ARM64.\n- Windows x64.\n- Windows ARM64.\n\nIf you build only a subset, the resulting release exposes only that subset.\nPromotion works from the assets actually present in the published release, not from an assumed full matrix.\n\n## Published Output\n\nThe workflow publishes assets into a draft GitHub Release in `helgeklein/sambee-companion`.\n\nThat release can contain:\n\n- Installer assets.\n- Tauri updater bundles.\n- `.sig` files for updater verification.\n- Release notes.\n\nThe workflow uses the tag format `companion-v\u003ceffective-version\u003e`.\n\nThat means an override such as `0.8.0-beta.1` produces the tag `companion-v0.8.0-beta.1`.\n\nChannel visibility is still unset at this stage.\nThe build is only a published candidate until a later promotion updates the feed files.\n\n## Review Before Publish\n\nBefore you publish the draft release, verify:\n\n- The version metadata is correct.\n- The release tag is the distinct version you intended to publish.\n- The expected platform assets are present.\n- The updater bundle and `.sig` pairs look complete for the platforms you expect to promote.\n- The release notes are acceptable for public distribution.\n\nIf the draft contents are wrong, fix the release process and produce a new release instead of trying to patch channel metadata around a bad artifact set.\n\n## Run the Workflow\n\nUse this order when you are preparing a Companion release:\n\n1. For an official release, merge the version-sync changes for the checked-in version you want to ship.\n2. For a prerelease or test build, decide the distinct override version you want to use for this run, for example `0.8.0-beta.1`.\n3. Start `Release: Build Companion Artifact` from the commit you want to release.\n4. Leave `publish_version_override` empty for the checked-in version, or set it to the temporary prerelease version you want for this run.\n5. Check `build_all_platforms` for a normal full release, or check only the specific platform boxes you want for a partial release. If you leave all boxes cleared, the workflow skips artifact builds.\n6. Wait for the workflow to create the draft release in `helgeklein/sambee-companion`.\n7. Review the uploaded assets and publish the draft release.\n8. Continue with [Promote Companion Release](../promote-companion-release/).\n", "0.9": "+++\ntitle = \"Build Companion Release\"\n+++\n\nThis is step 1 of the Companion release flow.\n\nUse this workflow to create Companion release assets for one immutable build version. GitHub Actions displays this workflow as `Release: Build Companion Artifact`. It creates builds for the selected platforms, which are then uploaded to the GitHub draft release by a finalizer.\n\n## Input\n\nThe manual workflow exposes an optional existing build-version selector plus one checkbox per platform:\n\n| Input | What it means |\n|---|---|\n| `build_version` | Build the commit with the `build-vX.Y.Z` tag. Leave empty to build the latest commit and set the `build-vX.Y.Z` tag on that commit. |\n| `build_all_platforms` | Include every supported platform in one run. |\n| `build_linux_x64` | Include the Linux x64 build. |\n| `build_macos_arm64` | Include the macOS ARM64 build. |\n| `build_windows_x64` | Include the Windows x64 build. |\n| `build_windows_arm64` | Include the Windows ARM64 build. |\n\nNew builds must be dispatched from `main`. The workflow verifies synchronized metadata, reserves `build-vX.Y.Z` for the exact source commit, and rejects any version that is not plain numeric `X.Y.Z`. It never changes an existing build tag.\n\nIf you check `build_all_platforms`, the workflow builds the full matrix and ignores the per-platform checkboxes.\nIf you leave every checkbox cleared, the workflow does not build anything.\nCheck only the platforms you want when you deliberately need a partial release.\n\n## What It Does\n\nBefore packaging, the workflow:\n\n1. Checks out the main repository.\n2. Resolves the canonical `build-vX.Y.Z` source commit or assigns it to the latest commit.\n3. Verifies synchronized version metadata.\n4. Builds the platform matrix derived from the checked boxes.\n5. Writes a per-platform artifact manifest with package names, SHA-256 checksums, installer/updater/signature roles, platform, and target; then uploads uniquely named private Actions artifacts.\n6. The finalizer downloads every retained artifact, verifies the manifests and complete package sets, writes a public aggregate manifest, provenance, and completion marker, then creates or resumes the external draft release.\n\nIf you build only a subset, the resulting release exposes only that subset.\nPromotion works from the assets actually present in the published release, not from an assumed full matrix.\n\n## Build Output\n\nThe finalizer uploads assets into a draft GitHub Release in `helgeklein/sambee-companion`.\n\nThat release can contain:\n\n- Installer assets.\n- Tauri updater bundles.\n- `.sig` files for updater verification.\n- A public aggregate artifact manifest, uploaded before all package assets.\n- Release provenance and a completion marker binding the release tag, aggregate-manifest digest, provenance digest, and exact expected assets.\n\n### Recovery And Immutability\n\nThe draft GitHub release is immutable once any asset is present: the finalizer uploads a missing asset or accepts an existing byte-identical asset, and rejects a conflicting replacement.\n\nIf a finalizer is interrupted, a later run uses the exact retained Actions artifact IDs, digests, originating run ID, run attempt, platform, and target recorded in draft provenance. It does not rebuild matrix artifacts. Expired, missing, ambiguous, or mismatched retained artifacts require a new `Z` candidate.\n\nGitHub Actions concurrency is mutual exclusion, not a FIFO queue: only one pending run is retained for the `companion-release-publication` lock. Avoid stacking dispatches. A superseded pending dispatch is safe to submit again because it never reached a publication step.\n\n## Review and Publish\n\nReview the draft GitHub release created or updated by this workflow. Then publish it.\n\nPublishing assigns the tag `companion-vX.Y.Z`.\n", "1.0": "+++\ntitle = \"Build Companion Release\"\n+++\n\nThis is step 1 of the Companion release flow.\n\nUse `Release: Build Companion Artifact` to create one immutable Companion release from a canonical build version. The workflow builds the selected platforms, verifies their manifests, publishes the GitHub Release automatically, promotes it to the `test` updater channel, and removes obsolete releases.\n\n## Input\n\nThe workflow accepts an optional existing build version and platform checkboxes.\n\n| Input | What it means |\n|---|---|\n| `build_version` | Build the commit reserved by `build-vX.Y.Z`. Leave it empty to reserve the current `main` commit. |\n| `build_all_platforms` | Include every supported platform. |\n| Platform checkboxes | Build only the selected platforms. |\n\nNew builds must start from `main`. The workflow verifies synchronized version metadata, reserves the exact source commit, and accepts only plain numeric `X.Y.Z` versions. It never changes an existing build tag.\n\nIf no platform is selected, the workflow does not create or promote a release.\n\n## What It Does\n\nThe workflow:\n\n1. Resolves the canonical `build-vX.Y.Z` source commit.\n1. Builds, signs, and records a manifest for every selected platform.\n1. Downloads and verifies the retained build artifacts in the finalizer.\n1. Creates a private provisional GitHub Release while assets are uploaded.\n1. Verifies the aggregate manifest, provenance, completion marker, and every release asset.\n1. Publishes `companion-vX.Y.Z` automatically after verification succeeds.\n1. Promotes only the Companion `test` updater feed to the published release.\n1. Cleans up obsolete Companion GitHub Releases.\n\nThe temporary draft is an upload and recovery boundary, not a review step. A release becomes public only after its complete verified asset set is present.\n\n## Recovery And Immutability\n\nOnce an asset is present, the provisional release accepts only a missing asset or an existing byte-identical asset. A conflicting replacement fails.\n\nIf finalization is interrupted, a later run uses the exact retained Actions artifact IDs, digests, run ID, attempt, platform, and target recorded in provenance. It does not rebuild the artifact matrix. Expired, missing, ambiguous, or mismatched retained artifacts require a new `Z` candidate.\n\nIf publication succeeds but the `test` feed push fails, rerun the build workflow with the same build version. It verifies the already published immutable release and retries promotion without rebuilding binaries.\n\nGitHub Actions concurrency is mutual exclusion, not a FIFO queue: only one pending run is retained for `companion-release-publication`. Avoid stacking dispatches.\n\n## What Happens Next\n\nThe automatic flow changes only `test`. Use [Promote Companion Release](../promote-companion-release/) later when the same published release is approved for `beta`, `stable`, or Sambee download metadata.\n\nSee [Companion Release Cleanup](../companion-release-cleanup/) for the retention policy.", "2.0": "+++\ntitle = \"Build Companion Release\"\n+++\n\nThis is step 1 of the Companion release flow.\n\nUse `Release: Build Companion Artifact` to create one immutable Companion release from a canonical build version. The workflow builds the selected platforms, verifies their manifests, publishes the GitHub Release automatically, promotes it to the `test` updater channel, and removes obsolete releases.\n\n## Input\n\nThe workflow accepts an optional existing build version and platform checkboxes.\n\n| Input | What it means |\n|---|---|\n| `build_version` | Build the commit reserved by `build-vX.Y.Z`. Leave it empty to reserve the current `main` commit. |\n| `build_all_platforms` | Include every supported platform. |\n| Platform checkboxes | Build only the selected platforms. |\n\nNew builds must start from `main`. The workflow verifies synchronized version metadata, reserves the exact source commit, and accepts only plain numeric `X.Y.Z` versions. It never changes an existing build tag.\n\nIf no platform is selected, the workflow does not create or promote a release.\n\n## What It Does\n\nThe workflow:\n\n1. Resolves the canonical `build-vX.Y.Z` source commit.\n1. Builds, signs, and records a manifest for every selected platform.\n1. Downloads and verifies the retained build artifacts in the finalizer.\n1. Creates a private provisional GitHub Release while assets are uploaded.\n1. Verifies the aggregate manifest, provenance, completion marker, and every release asset.\n1. Publishes `companion-vX.Y.Z` automatically after verification succeeds.\n1. Promotes only the Companion `test` updater feed to the published release.\n1. Cleans up obsolete Companion GitHub Releases.\n\nThe temporary draft is an upload and recovery boundary, not a review step. A release becomes public only after its complete verified asset set is present.\n\n## Recovery And Immutability\n\nOnce an asset is present, the provisional release accepts only a missing asset or an existing byte-identical asset. A conflicting replacement fails.\n\nIf finalization is interrupted, a later run uses the exact retained Actions artifact IDs, digests, run ID, attempt, platform, and target recorded in provenance. It does not rebuild the artifact matrix. Expired, missing, ambiguous, or mismatched retained artifacts require a new `Z` candidate.\n\nIf publication succeeds but the `test` feed push fails, rerun the build workflow with the same build version. It verifies the already published immutable release and retries promotion without rebuilding binaries.\n\nGitHub Actions concurrency is mutual exclusion, not a FIFO queue: only one pending run is retained for `companion-release-publication`. Avoid stacking dispatches.\n\n## What Happens Next\n\nThe automatic flow changes only `test`. Use [Promote Companion Release](../promote-companion-release/) later when the same published release is approved for `beta`, `stable`, or Sambee download metadata.\n\nSee [Companion Release Cleanup](../companion-release-cleanup/) for the retention policy."}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/release-and-versioning/promote-companion-release", "parent_id": "section:developer-guide/release-and-versioning", "depth": 2, "kind": "page", "label": "promote-companion-release", "title": "Promote Companion Release", "path": "developer-guide/release-and-versioning/promote-companion-release", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "branched", "source_version": "0.7", "diff_added": 5, "diff_removed": 1}, "1.0": {"state": "branched", "source_version": "0.9", "diff_added": 18, "diff_removed": 16}, "2.0": {"state": "branched", "source_version": "1.0", "diff_added": 2, "diff_removed": 3}}, "content_versions": {"0.7": "+++\ntitle = \"Promote Companion Release\"\n+++\n\nThis is step 2 of the Companion release flow.\n\nUse this workflow to point one or more public feeds at an already published Companion release. GitHub Actions displays this workflow as `Release: Promote Companion Release`.\n\nThis workflow does not rebuild binaries. It rewrites feed files in the public release repository and commits those pointer changes. See [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) for the public feed layout and serving model.\n\n## Use It When\n\nRun the promotion workflow when:\n\n- A published Companion release should become visible on `test`, `beta`, or `stable`.\n- Sambee should start offering direct downloads for that same published release.\n- You want to move an already published release from one visibility level to another without rebuilding it.\n\nDo not use this workflow for draft releases.\nPromotion should target a published release only.\n\n## Inputs\n\nThe manual workflow accepts these inputs:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `release_ref` | The release to promote. | Use the Companion tag for the clearest intent, for example `companion-v0.6.0`. |\n| `companion_channel_test` | Update the Companion `test` updater feed. | Use when installed test-channel builds should see this release. |\n| `companion_channel_beta` | Update the Companion `beta` updater feed. | Use when prerelease users should see this release. |\n| `companion_channel_stable` | Update the Companion `stable` updater feed. | Use when the release is approved for normal users. |\n| `sambee` | Update the Sambee Companion download-metadata feed. | Use when Sambee should offer this release for direct download. |\n\n`release_ref` can be:\n\n- A Companion tag such as `companion-v0.6.0`.\n- A GitHub release URL.\n- A numeric GitHub release ID.\n\nAt least one target must be selected.\n\n## What It Updates\n\nThe workflow checks out both repositories, resolves the release, and rewrites only the selected feed files in `helgeklein/sambee-companion`.\n\nSelected Companion channel targets update the appropriate updater manifest. The Sambee target updates the direct-download metadata document. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) defines those files and their consumers.\n\nAfter rewriting the files, the workflow commits and pushes the feed updates to the release repository, where they become available to their consumers.\n\n## Validation Rules\n\nPromotion is intentionally strict.\n\nIt fails when:\n\n- No promotion target was selected.\n- The referenced release is still a draft.\n- The release has no assets.\n- A selected Tauri feed target lacks a required bundle-and-signature pair for an included platform.\n- The Sambee metadata target would have no usable downloadable installer assets.\n\nA release does not need every supported platform to be promotable.\nIt only needs complete assets for the platforms that are actually included in the selected feed output.\n\n## Promotion Targets Mean Different Things\n\nCompanion updater feeds and Sambee download metadata are separate surfaces.\n\n- Promote a Companion channel when installed desktop apps should see the release through self-update.\n- Promote Sambee metadata when the product UI should offer the release as a direct download.\n- Select both when you want both outcomes from the same published release.\n\nUse [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) when you need the underlying model.\n\n## Run the Workflow\n\nUse this order when you are promoting a Companion release:\n\n1. Publish the reviewed draft release in `helgeklein/sambee-companion`.\n2. Start `Release: Promote Companion Release`.\n3. Set `release_ref` to the exact published release you want to expose.\n4. Select only the feed targets you intend to change.\n5. Let the workflow update and push the selected feed files.\n6. Validate the affected updater channel or Sambee download surface.\n7. Rerun the same workflow later if that same release should move from `test` to `beta` or `stable`.\n\n", "0.8": "+++\ntitle = \"Promote Companion Release\"\n+++\n\nThis is step 2 of the Companion release flow.\n\nUse this workflow to point one or more public feeds at an already published Companion release. GitHub Actions displays this workflow as `Release: Promote Companion Release`.\n\nThis workflow does not rebuild binaries. It rewrites feed files in the public release repository and commits those pointer changes. See [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) for the public feed layout and serving model.\n\n## Use It When\n\nRun the promotion workflow when:\n\n- A published Companion release should become visible on `test`, `beta`, or `stable`.\n- Sambee should start offering direct downloads for that same published release.\n- You want to move an already published release from one visibility level to another without rebuilding it.\n\nDo not use this workflow for draft releases.\nPromotion should target a published release only.\n\n## Inputs\n\nThe manual workflow accepts these inputs:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `release_ref` | The release to promote. | Use the Companion tag for the clearest intent, for example `companion-v0.6.0`. |\n| `companion_channel_test` | Update the Companion `test` updater feed. | Use when installed test-channel builds should see this release. |\n| `companion_channel_beta` | Update the Companion `beta` updater feed. | Use when prerelease users should see this release. |\n| `companion_channel_stable` | Update the Companion `stable` updater feed. | Use when the release is approved for normal users. |\n| `sambee` | Update the Sambee Companion download-metadata feed. | Use when Sambee should offer this release for direct download. |\n\n`release_ref` can be:\n\n- A Companion tag such as `companion-v0.6.0`.\n- A GitHub release URL.\n- A numeric GitHub release ID.\n\nAt least one target must be selected.\n\n## What It Updates\n\nThe workflow checks out both repositories, resolves the release, and rewrites only the selected feed files in `helgeklein/sambee-companion`.\n\nSelected Companion channel targets update the appropriate updater manifest. The Sambee target updates the direct-download metadata document. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) defines those files and their consumers.\n\nAfter rewriting the files, the workflow commits and pushes the feed updates to the release repository, where they become available to their consumers.\n\n## Validation Rules\n\nPromotion is intentionally strict.\n\nIt fails when:\n\n- No promotion target was selected.\n- The referenced release is still a draft.\n- The release has no assets.\n- A selected Tauri feed target lacks a required bundle-and-signature pair for an included platform.\n- The Sambee metadata target would have no usable downloadable installer assets.\n\nA release does not need every supported platform to be promotable.\nIt only needs complete assets for the platforms that are actually included in the selected feed output.\n\n## Promotion Targets Mean Different Things\n\nCompanion updater feeds and Sambee download metadata are separate surfaces.\n\n- Promote a Companion channel when installed desktop apps should see the release through self-update.\n- Promote Sambee metadata when the product UI should offer the release as a direct download.\n- Select both when you want both outcomes from the same published release.\n\nUse [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) when you need the underlying model.\n\n## Run the Workflow\n\nUse this order when you are promoting a Companion release:\n\n1. Publish the reviewed draft release in `helgeklein/sambee-companion`.\n2. Start `Release: Promote Companion Release`.\n3. Set `release_ref` to the exact published release you want to expose.\n4. Select only the feed targets you intend to change.\n5. Let the workflow update and push the selected feed files.\n6. Validate the affected updater channel or Sambee download surface.\n7. Rerun the same workflow later if that same release should move from `test` to `beta` or `stable`.\n\n", "0.9": "+++\ntitle = \"Promote Companion Release\"\n+++\n\nThis is step 2 of the Companion release flow.\n\nUse this workflow to point one or more public feeds at an already published Companion release. GitHub Actions displays this workflow as `Release: Promote Companion Release`.\n\nThis workflow does not rebuild binaries. It rewrites feed files in the public release repository and commits those pointer changes. See [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) for the public feed layout and serving model.\n\n## Use It When\n\nRun the promotion workflow when:\n\n- A published Companion release should become visible on `test`, `beta`, or `stable`.\n- Sambee should start offering direct downloads for that same published release.\n- You want to move an already published release from one visibility level to another without rebuilding it.\n\nDo not use this workflow for draft releases.\nPromotion should target a published release only.\n\n## Inputs\n\nThe manual workflow accepts these inputs:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `release_ref` | The release to promote. | Use the Companion tag for the clearest intent, for example `companion-v0.6.0`. |\n| `companion_channel_test` | Update the Companion `test` updater feed. | Use when installed test-channel builds should see this release. |\n| `companion_channel_beta` | Update the Companion `beta` updater feed. | Use when prerelease users should see this release. |\n| `companion_channel_stable` | Update the Companion `stable` updater feed. | Use when the release is approved for normal users. |\n| `sambee` | Update the Sambee Companion download-metadata feed. | Use when Sambee should offer this release for direct download. |\n\n`release_ref` can be:\n\n- A Companion tag such as `companion-v0.6.0`.\n- A GitHub release URL.\n- A numeric GitHub release ID.\n\nThe workflow reads the selected release's immutable provenance and derives the required public Sambee authorization tag as `vX.Y.Z`. That public release must contain `sambee-release.json` with a matching version, build tag, source SHA, and Companion-compatible scope.\n\nAt least one target must be selected.\n\n## What It Updates\n\nThe workflow checks out both repositories, resolves the release, and rewrites only the selected feed files in `helgeklein/sambee-companion`.\n\nSelected Companion channel targets update the appropriate updater manifest. The Sambee target updates the direct-download metadata document. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) defines those files and their consumers.\n\nAfter rewriting the files, the workflow commits and pushes the feed updates to the release repository, where they become available to their consumers.\n\n## Validation Rules\n\nPromotion is intentionally strict.\n\nIt fails when:\n\n- No promotion target was selected.\n- The referenced release is still a draft.\n- The release has no assets.\n- The external release provenance or completion marker does not exactly match its assets and checksums.\n- The public `sambee-release.json` does not authorize `companion` or `both`, or its version, build tag, or source SHA differs from the Companion provenance.\n- A selected Tauri feed target lacks a required bundle-and-signature pair for an included platform.\n- The Sambee metadata target would have no usable downloadable installer assets.\n\nA release does not need every supported platform to be promotable.\nIt only needs complete assets for the platforms that are actually included in the selected feed output.\n\n## Promotion Targets Mean Different Things\n\nCompanion updater feeds and Sambee download metadata are separate surfaces.\n\n- Promote a Companion channel when installed desktop apps should see the release through self-update.\n- Promote Sambee metadata when the product UI should offer the release as a direct download.\n- Select both when you want both outcomes from the same published release.\n\nUse [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) when you need the underlying model.\n\n## Run the Workflow\n\nUse this order when you are promoting a Companion release:\n\n1. Publish the reviewed draft release in `helgeklein/sambee-companion`.\n2. Start `Release: Promote Companion Release`.\n3. Set `release_ref` to the exact published release you want to expose.\n4. Select only the feed targets you intend to change.\n5. Let the workflow derive the matching public Sambee release, then update and push the selected feed files.\n6. Validate the affected updater channel or Sambee download surface.\n7. Rerun the same workflow later if that same release should move from `test` to `beta` or `stable`.\n\n", "1.0": "+++\ntitle = \"Promote Companion Release\"\n+++\n\nThis is the manual promotion step of the Companion release flow.\n\nUse this workflow to point one or more public feeds at an already published Companion release. GitHub Actions displays this workflow as `Release: Promote Companion Release`.\n\nThis workflow does not rebuild binaries. It rewrites feed files in the public release repository and commits those pointer changes. See [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) for the public feed layout and serving model.\n\n## Use It When\n\nRun the promotion workflow when:\n\n- A published Companion release should become visible on `beta` or `stable`.\n- Sambee should start offering direct downloads for that same published release.\n- You want to move an already published release from one visibility level to another without rebuilding it.\n\nNew builds already promote their verified published release to `test` automatically. You can still select `test` manually when you need to repair or deliberately move that feed.\n\nDo not use this workflow for draft or GitHub prerelease releases.\nPromotion should target a published, non-prerelease release only.\n\n## Inputs\n\nThe manual workflow accepts these inputs:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `release_ref` | The release to promote. | Use the Companion tag for the clearest intent, for example `companion-v0.6.0`. |\n| `companion_channel_test` | Update the Companion `test` updater feed. | Use when installed test-channel builds should see this release. |\n| `companion_channel_beta` | Update the Companion `beta` updater feed. | Use when installed beta-channel builds should see this release. |\n| `companion_channel_stable` | Update the Companion `stable` updater feed. | Use when the release is approved for normal users. |\n| `sambee` | Update the Sambee Companion download-metadata feed. | Use when Sambee should offer this release for direct download. |\n\n`release_ref` can be:\n\n- A Companion tag such as `companion-v0.6.0`.\n- A GitHub release URL for `helgeklein/sambee-companion`, such as `https://github.com/helgeklein/sambee-companion/releases/tag/companion-v0.6.0`.\n- A numeric GitHub release ID.\n\nBefore updating feeds, the workflow verifies that the selected release's immutable provenance refers to a canonical build tag at the recorded source commit. A matching public Sambee release or Docker image is not required.\n\nAt least one target must be selected.\n\n## What It Updates\n\nThe workflow checks out both repositories, resolves the release, and rewrites only the selected feed files in `helgeklein/sambee-companion`.\n\nSelected Companion channel targets update the appropriate updater manifest. The Sambee target updates the direct-download metadata document. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) defines those files and their consumers.\n\nAfter rewriting the files, the workflow commits and pushes the feed updates to the release repository, where they become available to their consumers. A successful promotion then runs the same release cleanup used by new builds.\n\n## Validation Rules\n\nPromotion is intentionally strict.\n\nIt fails when:\n\n- No promotion target was selected.\n- The referenced release is still a draft.\n- The referenced release is a GitHub prerelease.\n- The release has no assets.\n- The external release provenance or completion marker does not exactly match its assets and checksums.\n- The Companion provenance build tag does not resolve to the recorded source commit.\n- A selected Tauri feed target lacks a required bundle-and-signature pair for an included platform.\n- The Sambee metadata target would have no usable downloadable installer assets.\n\nA release does not need every supported platform to be promotable.\nIt only needs complete assets for the platforms that are actually included in the selected feed output.\n\n## Promotion Targets Mean Different Things\n\nCompanion updater feeds and Sambee download metadata are separate surfaces.\n\n- Promote a Companion channel when installed desktop apps should see the release through self-update.\n- Promote Sambee metadata when the product UI should offer the release as a direct download.\n- Select both when you want both outcomes from the same published release.\n\nUse [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) when you need the underlying model.\n\n## Run the Workflow\n\nUse this order when you are promoting a Companion release:\n\n1. Start `Release: Promote Companion Release`.\n1. Set `release_ref` to the exact published release you want to expose.\n1. Select only the feed targets you intend to change.\n1. Let the workflow verify the Companion provenance, then update and push the selected feed files.\n1. Validate the affected updater channel or Sambee download surface.\n1. Rerun the same workflow later if that same release should move from `test` to `beta` or `stable`.\n\n", "2.0": "+++\ntitle = \"Promote Companion Release\"\n+++\n\nThis is the manual promotion step of the Companion release flow.\n\nUse this workflow to point one or more public feeds at an already published Companion release. GitHub Actions displays this workflow as `Release: Promote Companion Release`.\n\nThis workflow does not rebuild binaries. It rewrites feed files in the public release repository and commits those pointer changes. See [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) for the public feed layout and serving model.\n\n## Use It When\n\nRun the promotion workflow when:\n\n- A published Companion release should become visible on `beta` or `stable`.\n- Sambee should start offering direct downloads for that same published release.\n- You want to move an already published release from one visibility level to another without rebuilding it.\n\nNew builds already promote their verified published release to `test` automatically. You can still select `test` manually when you need to repair or deliberately move that feed.\n\nDo not use this workflow for draft or GitHub prerelease releases.\nPromotion should target a published, non-prerelease release only.\n\n## Inputs\n\nThe manual workflow accepts these inputs:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `release_ref` | The release to promote. | Use the Companion tag for the clearest intent, for example `companion-v0.6.0`. |\n| `companion_channel_test` | Update the Companion `test` updater feed. | Use when installed test-channel builds should see this release. |\n| `companion_channel_beta` | Update the Companion `beta` updater feed. | Use when installed beta-channel builds should see this release. |\n| `companion_channel_stable` | Update the Companion `stable` updater feed. | Use when the release is approved for normal users. |\n| `sambee` | Update the Sambee Companion download-metadata feed. | Use when Sambee should offer this release for direct download. |\n\n`release_ref` can be:\n\n- A Companion tag such as `companion-v0.6.0`.\n- A GitHub release URL for `sambee-app/sambee-companion`, such as `https://github.com/sambee-app/sambee-companion/releases/tag/companion-v0.6.0`.\n- A numeric GitHub release ID.\n\nBefore updating feeds, the workflow verifies that the selected release's immutable provenance refers to a canonical build tag at the recorded source commit. A matching public Sambee release or Docker image is not required.\n\nAt least one target must be selected.\n\n## What It Updates\n\nThe workflow checks out both repositories, resolves the release, and rewrites only the selected feed files in `sambee-app/sambee-companion`.\n\nSelected Companion channel targets update the appropriate updater manifest. The Sambee target updates the direct-download metadata document. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) defines those files and their consumers.\n\nAfter rewriting the files, the workflow commits and pushes the feed updates to the release repository, where they become available to their consumers. A successful promotion then runs the same release cleanup used by new builds.\n\n## Validation Rules\n\nPromotion is intentionally strict.\n\nIt fails when:\n\n- No promotion target was selected.\n- The referenced release is still a draft.\n- The referenced release is a GitHub prerelease.\n- The release has no assets.\n- The external release provenance or completion marker does not exactly match its assets and checksums.\n- The Companion provenance build tag does not resolve to the recorded source commit.\n- A selected Tauri feed target lacks a required bundle-and-signature pair for an included platform.\n- The Sambee metadata target would have no usable downloadable installer assets.\n\nA release does not need every supported platform to be promotable.\nIt only needs complete assets for the platforms that are actually included in the selected feed output.\n\n## Promotion Targets Mean Different Things\n\nCompanion updater feeds and Sambee download metadata are separate surfaces.\n\n- Promote a Companion channel when installed desktop apps should see the release through self-update.\n- Promote Sambee metadata when the product UI should offer the release as a direct download.\n- Select both when you want both outcomes from the same published release.\n\nUse [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) when you need the underlying model.\n\n## Run the Workflow\n\nUse this order when you are promoting a Companion release:\n\n1. Start `Release: Promote Companion Release`.\n1. Set `release_ref` to the exact published release you want to expose.\n1. Select only the feed targets you intend to change.\n1. Let the workflow verify the Companion provenance, then update and push the selected feed files.\n1. Validate the affected updater channel or Sambee download surface.\n1. Rerun the same workflow later if that same release should move from `test` to `beta` or `stable`.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Promote Companion Release\"\n+++\n\nThis is step 2 of the Companion release flow.\n\nUse this workflow to point one or more public feeds at an already published Companion release. GitHub Actions displays this workflow as `Release: Promote Companion Release`.\n\nThis workflow does not rebuild binaries. It rewrites feed files in the public release repository and commits those pointer changes. See [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) for the public feed layout and serving model.\n\n## Use It When\n\nRun the promotion workflow when:\n\n- A published Companion release should become visible on `test`, `beta`, or `stable`.\n- Sambee should start offering direct downloads for that same published release.\n- You want to move an already published release from one visibility level to another without rebuilding it.\n\nDo not use this workflow for draft releases.\nPromotion should target a published release only.\n\n## Inputs\n\nThe manual workflow accepts these inputs:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `release_ref` | The release to promote. | Use the Companion tag for the clearest intent, for example `companion-v0.6.0`. |\n| `companion_channel_test` | Update the Companion `test` updater feed. | Use when installed test-channel builds should see this release. |\n| `companion_channel_beta` | Update the Companion `beta` updater feed. | Use when prerelease users should see this release. |\n| `companion_channel_stable` | Update the Companion `stable` updater feed. | Use when the release is approved for normal users. |\n| `sambee` | Update the Sambee Companion download-metadata feed. | Use when Sambee should offer this release for direct download. |\n\n`release_ref` can be:\n\n- A Companion tag such as `companion-v0.6.0`.\n- A GitHub release URL.\n- A numeric GitHub release ID.\n\nAt least one target must be selected.\n\n## What It Updates\n\nThe workflow checks out both repositories, resolves the release, and rewrites only the selected feed files in `helgeklein/sambee-companion`.\n\nSelected Companion channel targets update the appropriate updater manifest. The Sambee target updates the direct-download metadata document. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) defines those files and their consumers.\n\nAfter rewriting the files, the workflow commits and pushes the feed updates to the release repository, where they become available to their consumers.\n\n## Validation Rules\n\nPromotion is intentionally strict.\n\nIt fails when:\n\n- No promotion target was selected.\n- The referenced release is still a draft.\n- The release has no assets.\n- A selected Tauri feed target lacks a required bundle-and-signature pair for an included platform.\n- The Sambee metadata target would have no usable downloadable installer assets.\n\nA release does not need every supported platform to be promotable.\nIt only needs complete assets for the platforms that are actually included in the selected feed output.\n\n## Promotion Targets Mean Different Things\n\nCompanion updater feeds and Sambee download metadata are separate surfaces.\n\n- Promote a Companion channel when installed desktop apps should see the release through self-update.\n- Promote Sambee metadata when the product UI should offer the release as a direct download.\n- Select both when you want both outcomes from the same published release.\n\nUse [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) when you need the underlying model.\n\n## Run the Workflow\n\nUse this order when you are promoting a Companion release:\n\n1. Publish the reviewed draft release in `helgeklein/sambee-companion`.\n2. Start `Release: Promote Companion Release`.\n3. Set `release_ref` to the exact published release you want to expose.\n4. Select only the feed targets you intend to change.\n5. Let the workflow update and push the selected feed files.\n6. Validate the affected updater channel or Sambee download surface.\n7. Rerun the same workflow later if that same release should move from `test` to `beta` or `stable`.\n\n", "0.8": "+++\ntitle = \"Promote Companion Release\"\n+++\n\nThis is step 2 of the Companion release flow.\n\nUse this workflow to point one or more public feeds at an already published Companion release. GitHub Actions displays this workflow as `Release: Promote Companion Release`.\n\nThis workflow does not rebuild binaries. It rewrites feed files in the public release repository and commits those pointer changes. See [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) for the public feed layout and serving model.\n\n## Use It When\n\nRun the promotion workflow when:\n\n- A published Companion release should become visible on `test`, `beta`, or `stable`.\n- Sambee should start offering direct downloads for that same published release.\n- You want to move an already published release from one visibility level to another without rebuilding it.\n\nDo not use this workflow for draft releases.\nPromotion should target a published release only.\n\n## Inputs\n\nThe manual workflow accepts these inputs:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `release_ref` | The release to promote. | Use the Companion tag for the clearest intent, for example `companion-v0.6.0`. |\n| `companion_channel_test` | Update the Companion `test` updater feed. | Use when installed test-channel builds should see this release. |\n| `companion_channel_beta` | Update the Companion `beta` updater feed. | Use when prerelease users should see this release. |\n| `companion_channel_stable` | Update the Companion `stable` updater feed. | Use when the release is approved for normal users. |\n| `sambee` | Update the Sambee Companion download-metadata feed. | Use when Sambee should offer this release for direct download. |\n\n`release_ref` can be:\n\n- A Companion tag such as `companion-v0.6.0`.\n- A GitHub release URL.\n- A numeric GitHub release ID.\n\nAt least one target must be selected.\n\n## What It Updates\n\nThe workflow checks out both repositories, resolves the release, and rewrites only the selected feed files in `helgeklein/sambee-companion`.\n\nSelected Companion channel targets update the appropriate updater manifest. The Sambee target updates the direct-download metadata document. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) defines those files and their consumers.\n\nAfter rewriting the files, the workflow commits and pushes the feed updates to the release repository, where they become available to their consumers.\n\n## Validation Rules\n\nPromotion is intentionally strict.\n\nIt fails when:\n\n- No promotion target was selected.\n- The referenced release is still a draft.\n- The release has no assets.\n- A selected Tauri feed target lacks a required bundle-and-signature pair for an included platform.\n- The Sambee metadata target would have no usable downloadable installer assets.\n\nA release does not need every supported platform to be promotable.\nIt only needs complete assets for the platforms that are actually included in the selected feed output.\n\n## Promotion Targets Mean Different Things\n\nCompanion updater feeds and Sambee download metadata are separate surfaces.\n\n- Promote a Companion channel when installed desktop apps should see the release through self-update.\n- Promote Sambee metadata when the product UI should offer the release as a direct download.\n- Select both when you want both outcomes from the same published release.\n\nUse [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) when you need the underlying model.\n\n## Run the Workflow\n\nUse this order when you are promoting a Companion release:\n\n1. Publish the reviewed draft release in `helgeklein/sambee-companion`.\n2. Start `Release: Promote Companion Release`.\n3. Set `release_ref` to the exact published release you want to expose.\n4. Select only the feed targets you intend to change.\n5. Let the workflow update and push the selected feed files.\n6. Validate the affected updater channel or Sambee download surface.\n7. Rerun the same workflow later if that same release should move from `test` to `beta` or `stable`.\n\n", "0.9": "+++\ntitle = \"Promote Companion Release\"\n+++\n\nThis is step 2 of the Companion release flow.\n\nUse this workflow to point one or more public feeds at an already published Companion release. GitHub Actions displays this workflow as `Release: Promote Companion Release`.\n\nThis workflow does not rebuild binaries. It rewrites feed files in the public release repository and commits those pointer changes. See [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) for the public feed layout and serving model.\n\n## Use It When\n\nRun the promotion workflow when:\n\n- A published Companion release should become visible on `test`, `beta`, or `stable`.\n- Sambee should start offering direct downloads for that same published release.\n- You want to move an already published release from one visibility level to another without rebuilding it.\n\nDo not use this workflow for draft releases.\nPromotion should target a published release only.\n\n## Inputs\n\nThe manual workflow accepts these inputs:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `release_ref` | The release to promote. | Use the Companion tag for the clearest intent, for example `companion-v0.6.0`. |\n| `companion_channel_test` | Update the Companion `test` updater feed. | Use when installed test-channel builds should see this release. |\n| `companion_channel_beta` | Update the Companion `beta` updater feed. | Use when prerelease users should see this release. |\n| `companion_channel_stable` | Update the Companion `stable` updater feed. | Use when the release is approved for normal users. |\n| `sambee` | Update the Sambee Companion download-metadata feed. | Use when Sambee should offer this release for direct download. |\n\n`release_ref` can be:\n\n- A Companion tag such as `companion-v0.6.0`.\n- A GitHub release URL.\n- A numeric GitHub release ID.\n\nThe workflow reads the selected release's immutable provenance and derives the required public Sambee authorization tag as `vX.Y.Z`. That public release must contain `sambee-release.json` with a matching version, build tag, source SHA, and Companion-compatible scope.\n\nAt least one target must be selected.\n\n## What It Updates\n\nThe workflow checks out both repositories, resolves the release, and rewrites only the selected feed files in `helgeklein/sambee-companion`.\n\nSelected Companion channel targets update the appropriate updater manifest. The Sambee target updates the direct-download metadata document. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) defines those files and their consumers.\n\nAfter rewriting the files, the workflow commits and pushes the feed updates to the release repository, where they become available to their consumers.\n\n## Validation Rules\n\nPromotion is intentionally strict.\n\nIt fails when:\n\n- No promotion target was selected.\n- The referenced release is still a draft.\n- The release has no assets.\n- The external release provenance or completion marker does not exactly match its assets and checksums.\n- The public `sambee-release.json` does not authorize `companion` or `both`, or its version, build tag, or source SHA differs from the Companion provenance.\n- A selected Tauri feed target lacks a required bundle-and-signature pair for an included platform.\n- The Sambee metadata target would have no usable downloadable installer assets.\n\nA release does not need every supported platform to be promotable.\nIt only needs complete assets for the platforms that are actually included in the selected feed output.\n\n## Promotion Targets Mean Different Things\n\nCompanion updater feeds and Sambee download metadata are separate surfaces.\n\n- Promote a Companion channel when installed desktop apps should see the release through self-update.\n- Promote Sambee metadata when the product UI should offer the release as a direct download.\n- Select both when you want both outcomes from the same published release.\n\nUse [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) when you need the underlying model.\n\n## Run the Workflow\n\nUse this order when you are promoting a Companion release:\n\n1. Publish the reviewed draft release in `helgeklein/sambee-companion`.\n2. Start `Release: Promote Companion Release`.\n3. Set `release_ref` to the exact published release you want to expose.\n4. Select only the feed targets you intend to change.\n5. Let the workflow derive the matching public Sambee release, then update and push the selected feed files.\n6. Validate the affected updater channel or Sambee download surface.\n7. Rerun the same workflow later if that same release should move from `test` to `beta` or `stable`.\n\n", "1.0": "+++\ntitle = \"Promote Companion Release\"\n+++\n\nThis is the manual promotion step of the Companion release flow.\n\nUse this workflow to point one or more public feeds at an already published Companion release. GitHub Actions displays this workflow as `Release: Promote Companion Release`.\n\nThis workflow does not rebuild binaries. It rewrites feed files in the public release repository and commits those pointer changes. See [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) for the public feed layout and serving model.\n\n## Use It When\n\nRun the promotion workflow when:\n\n- A published Companion release should become visible on `beta` or `stable`.\n- Sambee should start offering direct downloads for that same published release.\n- You want to move an already published release from one visibility level to another without rebuilding it.\n\nNew builds already promote their verified published release to `test` automatically. You can still select `test` manually when you need to repair or deliberately move that feed.\n\nDo not use this workflow for draft or GitHub prerelease releases.\nPromotion should target a published, non-prerelease release only.\n\n## Inputs\n\nThe manual workflow accepts these inputs:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `release_ref` | The release to promote. | Use the Companion tag for the clearest intent, for example `companion-v0.6.0`. |\n| `companion_channel_test` | Update the Companion `test` updater feed. | Use when installed test-channel builds should see this release. |\n| `companion_channel_beta` | Update the Companion `beta` updater feed. | Use when installed beta-channel builds should see this release. |\n| `companion_channel_stable` | Update the Companion `stable` updater feed. | Use when the release is approved for normal users. |\n| `sambee` | Update the Sambee Companion download-metadata feed. | Use when Sambee should offer this release for direct download. |\n\n`release_ref` can be:\n\n- A Companion tag such as `companion-v0.6.0`.\n- A GitHub release URL for `helgeklein/sambee-companion`, such as `https://github.com/helgeklein/sambee-companion/releases/tag/companion-v0.6.0`.\n- A numeric GitHub release ID.\n\nBefore updating feeds, the workflow verifies that the selected release's immutable provenance refers to a canonical build tag at the recorded source commit. A matching public Sambee release or Docker image is not required.\n\nAt least one target must be selected.\n\n## What It Updates\n\nThe workflow checks out both repositories, resolves the release, and rewrites only the selected feed files in `helgeklein/sambee-companion`.\n\nSelected Companion channel targets update the appropriate updater manifest. The Sambee target updates the direct-download metadata document. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) defines those files and their consumers.\n\nAfter rewriting the files, the workflow commits and pushes the feed updates to the release repository, where they become available to their consumers. A successful promotion then runs the same release cleanup used by new builds.\n\n## Validation Rules\n\nPromotion is intentionally strict.\n\nIt fails when:\n\n- No promotion target was selected.\n- The referenced release is still a draft.\n- The referenced release is a GitHub prerelease.\n- The release has no assets.\n- The external release provenance or completion marker does not exactly match its assets and checksums.\n- The Companion provenance build tag does not resolve to the recorded source commit.\n- A selected Tauri feed target lacks a required bundle-and-signature pair for an included platform.\n- The Sambee metadata target would have no usable downloadable installer assets.\n\nA release does not need every supported platform to be promotable.\nIt only needs complete assets for the platforms that are actually included in the selected feed output.\n\n## Promotion Targets Mean Different Things\n\nCompanion updater feeds and Sambee download metadata are separate surfaces.\n\n- Promote a Companion channel when installed desktop apps should see the release through self-update.\n- Promote Sambee metadata when the product UI should offer the release as a direct download.\n- Select both when you want both outcomes from the same published release.\n\nUse [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) when you need the underlying model.\n\n## Run the Workflow\n\nUse this order when you are promoting a Companion release:\n\n1. Start `Release: Promote Companion Release`.\n1. Set `release_ref` to the exact published release you want to expose.\n1. Select only the feed targets you intend to change.\n1. Let the workflow verify the Companion provenance, then update and push the selected feed files.\n1. Validate the affected updater channel or Sambee download surface.\n1. Rerun the same workflow later if that same release should move from `test` to `beta` or `stable`.\n\n", "2.0": "+++\ntitle = \"Promote Companion Release\"\n+++\n\nThis is the manual promotion step of the Companion release flow.\n\nUse this workflow to point one or more public feeds at an already published Companion release. GitHub Actions displays this workflow as `Release: Promote Companion Release`.\n\nThis workflow does not rebuild binaries. It rewrites feed files in the public release repository and commits those pointer changes. See [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) for the public feed layout and serving model.\n\n## Use It When\n\nRun the promotion workflow when:\n\n- A published Companion release should become visible on `beta` or `stable`.\n- Sambee should start offering direct downloads for that same published release.\n- You want to move an already published release from one visibility level to another without rebuilding it.\n\nNew builds already promote their verified published release to `test` automatically. You can still select `test` manually when you need to repair or deliberately move that feed.\n\nDo not use this workflow for draft or GitHub prerelease releases.\nPromotion should target a published, non-prerelease release only.\n\n## Inputs\n\nThe manual workflow accepts these inputs:\n\n| Input | What it means | Typical usage |\n|---|---|---|\n| `release_ref` | The release to promote. | Use the Companion tag for the clearest intent, for example `companion-v0.6.0`. |\n| `companion_channel_test` | Update the Companion `test` updater feed. | Use when installed test-channel builds should see this release. |\n| `companion_channel_beta` | Update the Companion `beta` updater feed. | Use when installed beta-channel builds should see this release. |\n| `companion_channel_stable` | Update the Companion `stable` updater feed. | Use when the release is approved for normal users. |\n| `sambee` | Update the Sambee Companion download-metadata feed. | Use when Sambee should offer this release for direct download. |\n\n`release_ref` can be:\n\n- A Companion tag such as `companion-v0.6.0`.\n- A GitHub release URL for `sambee-app/sambee-companion`, such as `https://github.com/sambee-app/sambee-companion/releases/tag/companion-v0.6.0`.\n- A numeric GitHub release ID.\n\nBefore updating feeds, the workflow verifies that the selected release's immutable provenance refers to a canonical build tag at the recorded source commit. A matching public Sambee release or Docker image is not required.\n\nAt least one target must be selected.\n\n## What It Updates\n\nThe workflow checks out both repositories, resolves the release, and rewrites only the selected feed files in `sambee-app/sambee-companion`.\n\nSelected Companion channel targets update the appropriate updater manifest. The Sambee target updates the direct-download metadata document. [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) defines those files and their consumers.\n\nAfter rewriting the files, the workflow commits and pushes the feed updates to the release repository, where they become available to their consumers. A successful promotion then runs the same release cleanup used by new builds.\n\n## Validation Rules\n\nPromotion is intentionally strict.\n\nIt fails when:\n\n- No promotion target was selected.\n- The referenced release is still a draft.\n- The referenced release is a GitHub prerelease.\n- The release has no assets.\n- The external release provenance or completion marker does not exactly match its assets and checksums.\n- The Companion provenance build tag does not resolve to the recorded source commit.\n- A selected Tauri feed target lacks a required bundle-and-signature pair for an included platform.\n- The Sambee metadata target would have no usable downloadable installer assets.\n\nA release does not need every supported platform to be promotable.\nIt only needs complete assets for the platforms that are actually included in the selected feed output.\n\n## Promotion Targets Mean Different Things\n\nCompanion updater feeds and Sambee download metadata are separate surfaces.\n\n- Promote a Companion channel when installed desktop apps should see the release through self-update.\n- Promote Sambee metadata when the product UI should offer the release as a direct download.\n- Select both when you want both outcomes from the same published release.\n\nUse [Companion Channels, Feeds, And Downloads](../companion-channels-feeds-and-downloads/) when you need the underlying model.\n\n## Run the Workflow\n\nUse this order when you are promoting a Companion release:\n\n1. Start `Release: Promote Companion Release`.\n1. Set `release_ref` to the exact published release you want to expose.\n1. Select only the feed targets you intend to change.\n1. Let the workflow verify the Companion provenance, then update and push the selected feed files.\n1. Validate the affected updater channel or Sambee download surface.\n1. Rerun the same workflow later if that same release should move from `test` to `beta` or `stable`.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/release-and-versioning/companion-channels-feeds-and-downloads", "parent_id": "section:developer-guide/release-and-versioning", "depth": 2, "kind": "page", "label": "companion-channels-feeds-and-downloads", "title": "Companion Channels Feeds And Downloads", "path": "developer-guide/release-and-versioning/companion-channels-feeds-and-downloads", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "branched", "source_version": "0.7", "diff_added": 3, "diff_removed": 1}, "1.0": {"state": "branched", "source_version": "0.9", "diff_added": 6, "diff_removed": 11}, "2.0": {"state": "branched", "source_version": "1.0", "diff_added": 1, "diff_removed": 1}}, "content_versions": {"0.7": "+++\ntitle = \"Companion Channels, Feeds, And Downloads\"\n+++\n\nUse this page when you need the system model behind Companion release promotion.\n\nIt explains which public files exist, who reads them, and why channel promotion does not require rebuilding binaries.\n\n## Core Model\n\nCompanion release distribution is intentionally split between build control in the main repository, release assets in a dedicated release repository, and public feed serving from a separate feed host.\n\nThat split keeps Companion binaries out of normal Sambee deployments while still letting:\n\n- Sambee render Companion download links.\n- Installed Companion builds fetch updates.\n\nThe current model uses four moving parts:\n\n1. The main `sambee` repository builds Companion releases.\n2. The dedicated `sambee-companion` repository hosts immutable GitHub Release assets and stores the committed feed files under `docs/feeds`.\n3. The separate host `https://release-feeds.sambee.net` serves those committed feed files publicly.\n4. Channel manifests under `stable`, `beta`, and `test` decide which published release installed Companion builds see.\n5. A separate Sambee download-metadata file decides which installer links Sambee renders in the product UI.\n\nThe important consequence is simple: channels are feed pointers, not separate binaries.\n\n## Public Distribution Surface\n\nPublished Companion releases live in `helgeklein/sambee-companion` as GitHub Releases.\n\nThe public feed host is:\n\n- `https://release-feeds.sambee.net`\n\nThat host is separate from the main `sambee.net` website deployment in this repository.\nThe website workflow here deploys `website/public` to Cloudflare Pages for `sambee.net`, while the live feed host currently responds separately.\n\nThe current public layout is:\n\n```text\nfeeds/companion/tauri/stable/latest.json\nfeeds/companion/tauri/beta/latest.json\nfeeds/companion/tauri/test/latest.json\nfeeds/sambee/companion/latest.json\n```\n\nInside the release repository, those files are committed under `docs/feeds/`.\nThat repository path is the source of the published feed JSON, not the same thing as the main website source tree in this repository.\n\n## Who Reads What\n\n| Consumer | Public file | Format | Purpose |\n|---|---|---|---|\n| Installed Companion builds | `feeds/companion/tauri/\u003cchannel\u003e/latest.json` | Tauri updater JSON | Exposes the published release visible to the selected update channel. |\n| Sambee backend | `feeds/sambee/companion/latest.json` | Sambee-specific download metadata | Exposes version, notes, and installer URLs for the product UI. |\n\nSambee and Companion do not read the same feed.\n\n- Promoting a Companion channel changes auto-update visibility for installed desktop apps.\n- Promoting the Sambee metadata feed changes which direct downloads the product surfaces.\n- The same published release can move across `test`, `beta`, and `stable` over time.\n\n## Feed Rules\n\nInstalled Companion builds consume standard Tauri updater JSON.\n\nImportant behavior:\n\n- Each channel manifest points to immutable release assets in `sambee-companion`.\n- Feed files can move between releases over time, but published asset URLs should not be patched in place.\n- The promotion script includes every platform for which it finds a complete bundle-and-signature pair.\n- A release does not need every platform to be promotable.\n\nSambee uses a different JSON document.\n\nImportant behavior:\n\n- It contains only what Sambee needs to render download UI.\n- The asset map can contain any supported subset of discovered installers.\n- Sambee does not read the Tauri channel manifests directly.\n\n## Runtime Behavior\n\nCompanion uses `tauri-plugin-updater` for self-update checks.\n\nThe runtime updater is channel-aware:\n\n- The Rust update commands build the updater URL from the selected channel at runtime.\n- The frontend stores the local preference as `companionUpdateChannel`.\n- Allowed channel values are `stable`, `beta`, and `test`.\n- The default channel is `stable`.\n\nIn practice, that means the same installed app can see different releases over time based on the local channel setting and the currently promoted feed file.\n\n## Sambee Integration\n\nSambee does not bundle Companion binaries.\n\nBy default, the backend resolves Companion download metadata from `https://release-feeds.sambee.net/feeds/sambee/companion/latest.json`.\n\nThe backend then:\n\n- Fetches the hosted Companion download metadata.\n- Normalizes and validates installer URLs.\n- Exposes the result through the backend API to the frontend.\n\nSambee also supports a deterministic pin override in configuration.\n\nWhen a pin is configured, the backend stops using the hosted feed for Companion download links and serves the pinned version, notes, and installer URLs instead.\n\n## App Identity And Signing\n\nCompanion uses one app identity across all update channels.\n\nChannel separation comes from feed selection, not from separate binaries or per-channel app identifiers.\n\nCompanion also uses one Tauri updater signing key across all channels.\n\n- Updater artifacts are signed during release builds.\n- Installed Companion builds verify updates using the embedded updater public key.\n- Platform-specific installer signing is separate from the Tauri updater signature.\n\n## Contributor Rules\n\n- Do not treat update channels as different binaries.\n- Do not patch broken published assets in place.\n- Build and publish a new release instead.\n- Review whether you are changing Companion updater visibility, Sambee download visibility, or both.\n- Keep release automation aligned with asset naming conventions, because promotion depends on asset-pattern matching.\n\n", "0.8": "+++\ntitle = \"Companion Channels, Feeds, And Downloads\"\n+++\n\nUse this page when you need the system model behind Companion release promotion.\n\nIt explains which public files exist, who reads them, and why channel promotion does not require rebuilding binaries.\n\n## Core Model\n\nCompanion release distribution is intentionally split between build control in the main repository, release assets in a dedicated release repository, and public feed serving from a separate feed host.\n\nThat split keeps Companion binaries out of normal Sambee deployments while still letting:\n\n- Sambee render Companion download links.\n- Installed Companion builds fetch updates.\n\nThe current model uses four moving parts:\n\n1. The main `sambee` repository builds Companion releases.\n2. The dedicated `sambee-companion` repository hosts immutable GitHub Release assets and stores the committed feed files under `docs/feeds`.\n3. The separate host `https://release-feeds.sambee.net` serves those committed feed files publicly.\n4. Channel manifests under `stable`, `beta`, and `test` decide which published release installed Companion builds see.\n5. A separate Sambee download-metadata file decides which installer links Sambee renders in the product UI.\n\nThe important consequence is simple: channels are feed pointers, not separate binaries.\n\n## Public Distribution Surface\n\nPublished Companion releases live in `helgeklein/sambee-companion` as GitHub Releases.\n\nThe public feed host is:\n\n- `https://release-feeds.sambee.net`\n\nThat host is separate from the main `sambee.net` website deployment in this repository.\nThe website workflow here deploys `website/public` to Cloudflare Pages for `sambee.net`, while the live feed host currently responds separately.\n\nThe current public layout is:\n\n```text\nfeeds/companion/tauri/stable/latest.json\nfeeds/companion/tauri/beta/latest.json\nfeeds/companion/tauri/test/latest.json\nfeeds/sambee/companion/latest.json\n```\n\nInside the release repository, those files are committed under `docs/feeds/`.\nThat repository path is the source of the published feed JSON, not the same thing as the main website source tree in this repository.\n\n## Who Reads What\n\n| Consumer | Public file | Format | Purpose |\n|---|---|---|---|\n| Installed Companion builds | `feeds/companion/tauri/\u003cchannel\u003e/latest.json` | Tauri updater JSON | Exposes the published release visible to the selected update channel. |\n| Sambee backend | `feeds/sambee/companion/latest.json` | Sambee-specific download metadata | Exposes version, notes, and installer URLs for the product UI. |\n\nSambee and Companion do not read the same feed.\n\n- Promoting a Companion channel changes auto-update visibility for installed desktop apps.\n- Promoting the Sambee metadata feed changes which direct downloads the product surfaces.\n- The same published release can move across `test`, `beta`, and `stable` over time.\n\n## Feed Rules\n\nInstalled Companion builds consume standard Tauri updater JSON.\n\nImportant behavior:\n\n- Each channel manifest points to immutable release assets in `sambee-companion`.\n- Feed files can move between releases over time, but published asset URLs should not be patched in place.\n- The promotion script includes every platform for which it finds a complete bundle-and-signature pair.\n- A release does not need every platform to be promotable.\n\nSambee uses a different JSON document.\n\nImportant behavior:\n\n- It contains only what Sambee needs to render download UI.\n- The asset map can contain any supported subset of discovered installers.\n- Sambee does not read the Tauri channel manifests directly.\n\n## Runtime Behavior\n\nCompanion uses `tauri-plugin-updater` for self-update checks.\n\nThe runtime updater is channel-aware:\n\n- The Rust update commands build the updater URL from the selected channel at runtime.\n- The frontend stores the local preference as `companionUpdateChannel`.\n- Allowed channel values are `stable`, `beta`, and `test`.\n- The default channel is `stable`.\n\nIn practice, that means the same installed app can see different releases over time based on the local channel setting and the currently promoted feed file.\n\n## Sambee Integration\n\nSambee does not bundle Companion binaries.\n\nBy default, the backend resolves Companion download metadata from `https://release-feeds.sambee.net/feeds/sambee/companion/latest.json`.\n\nThe backend then:\n\n- Fetches the hosted Companion download metadata.\n- Normalizes and validates installer URLs.\n- Exposes the result through the backend API to the frontend.\n\nSambee also supports a deterministic pin override in configuration.\n\nWhen a pin is configured, the backend stops using the hosted feed for Companion download links and serves the pinned version, notes, and installer URLs instead.\n\n## App Identity And Signing\n\nCompanion uses one app identity across all update channels.\n\nChannel separation comes from feed selection, not from separate binaries or per-channel app identifiers.\n\nCompanion also uses one Tauri updater signing key across all channels.\n\n- Updater artifacts are signed during release builds.\n- Installed Companion builds verify updates using the embedded updater public key.\n- Platform-specific installer signing is separate from the Tauri updater signature.\n\n## Contributor Rules\n\n- Do not treat update channels as different binaries.\n- Do not patch broken published assets in place.\n- Build and publish a new release instead.\n- Review whether you are changing Companion updater visibility, Sambee download visibility, or both.\n- Keep release automation aligned with asset naming conventions, because promotion depends on asset-pattern matching.\n\n", "0.9": "+++\ntitle = \"Companion Channels, Feeds, And Downloads\"\n+++\n\nUse this page when you need the system model behind Companion release promotion.\n\nIt explains which public files exist, who reads them, and why channel promotion does not require rebuilding binaries.\n\n## Core Model\n\nCompanion release distribution is intentionally split between build control in the main repository, release assets in a dedicated release repository, and public feed serving from a separate feed host.\n\nThat split keeps Companion binaries out of normal Sambee deployments while still letting:\n\n- Sambee render Companion download links.\n- Installed Companion builds fetch updates.\n\nThe current model uses four moving parts:\n\n1. The main `sambee` repository builds Companion releases.\n2. The dedicated `sambee-companion` repository hosts immutable GitHub Release assets and stores the committed feed files under `docs/feeds`.\n3. The separate host `https://release-feeds.sambee.net` serves those committed feed files publicly.\n4. Channel manifests under `stable`, `beta`, and `test` decide which published release installed Companion builds see.\n5. A separate Sambee download-metadata file decides which installer links Sambee renders in the product UI.\n\nThe important consequence is simple: channels are feed pointers, not separate binaries.\n\n## Public Distribution Surface\n\nPublished Companion releases live in `helgeklein/sambee-companion` as GitHub Releases.\n\nThe public feed host is:\n\n- `https://release-feeds.sambee.net`\n\nThat host is separate from the main `sambee.net` website deployment in this repository.\nThe website workflow here deploys `website/public` to Cloudflare Pages for `sambee.net`, while the live feed host currently responds separately.\n\nThe current public layout is:\n\n```text\nfeeds/companion/tauri/stable/latest.json\nfeeds/companion/tauri/beta/latest.json\nfeeds/companion/tauri/test/latest.json\nfeeds/sambee/companion/latest.json\n```\n\nInside the release repository, those files are committed under `docs/feeds/`.\nThat repository path is the source of the published feed JSON, not the same thing as the main website source tree in this repository.\n\n## Who Reads What\n\n| Consumer | Public file | Format | Purpose |\n|---|---|---|---|\n| Installed Companion builds | `feeds/companion/tauri/\u003cchannel\u003e/latest.json` | Tauri updater JSON | Exposes the published release visible to the selected update channel. |\n| Sambee backend | `feeds/sambee/companion/latest.json` | Sambee-specific download metadata | Exposes version, notes, and installer URLs for the product UI. |\n\nSambee and Companion do not read the same feed.\n\n- Promoting a Companion channel changes auto-update visibility for installed desktop apps.\n- Promoting the Sambee metadata feed changes which direct downloads the product surfaces.\n- The same published release can move across `test`, `beta`, and `stable` over time.\n\n## Feed Rules\n\nInstalled Companion builds consume standard Tauri updater JSON.\n\nImportant behavior:\n\n- Each channel manifest points to immutable release assets in `sambee-companion`.\n- Feed files can move between releases over time, but published asset URLs should not be patched in place.\n- Each publishable release uses a new plain numeric `X.Y.Z` version. Tauri offers an update only when the later version is greater; publishing replacement bytes under an equal version is unsupported.\n- The promotion script includes every platform for which it finds a complete bundle-and-signature pair.\n- A release does not need every platform to be promotable.\n\nSambee uses a different JSON document.\n\nImportant behavior:\n\n- It contains only what Sambee needs to render download UI.\n- The asset map can contain any supported subset of discovered installers.\n- Sambee does not read the Tauri channel manifests directly.\n\n## Runtime Behavior\n\nCompanion uses `tauri-plugin-updater` for self-update checks.\n\nThe runtime updater is channel-aware:\n\n- The Rust update commands build the updater URL from the selected channel at runtime.\n- The frontend stores the local preference as `companionUpdateChannel`.\n- Allowed channel values are `stable`, `beta`, and `test`.\n- The default channel is `stable`.\n\nIn practice, that means the same installed app can see different releases over time based on the local channel setting and the currently promoted feed file.\n\n## Sambee Integration\n\nSambee does not bundle Companion binaries.\n\nBy default, the backend resolves Companion download metadata from `https://release-feeds.sambee.net/feeds/sambee/companion/latest.json`.\n\nThe backend then:\n\n- Fetches the hosted Companion download metadata.\n- Normalizes and validates installer URLs.\n- Exposes the result through the backend API to the frontend.\n\nSambee also supports a deterministic pin override in configuration.\n\nWhen a pin is configured, the backend stops using the hosted feed for Companion download links and serves the pinned version, notes, and installer URLs instead.\n\n## App Identity And Signing\n\nCompanion uses one app identity across all update channels.\n\nChannel separation comes from feed selection, not from separate binaries or per-channel app identifiers.\n\nCompanion also uses one Tauri updater signing key across all channels.\n\n- Updater artifacts are signed during release builds.\n- Installed Companion builds verify updates using the embedded updater public key.\n- Platform-specific installer signing is separate from the Tauri updater signature.\n\n## Contributor Rules\n\n- Do not treat update channels as different binaries.\n- Do not patch broken published assets in place.\n- Build and publish a new `Z` version instead.\n- Treat `test`, `beta`, and `stable` as visibility pointers, never as different binaries or version suffixes.\n- Review whether you are changing Companion updater visibility, Sambee download visibility, or both.\n- Keep release automation aligned with asset naming conventions, because promotion depends on asset-pattern matching.\n\n", "1.0": "+++\ntitle = \"Companion Channels, Feeds \u0026 Downloads\"\n+++\n\nUse this page when you need the system model behind Companion release promotion.\n\nIt explains which public files exist, who reads them, and why channel promotion does not require rebuilding binaries.\n\n{{\u003c companion-promotion-overview \u003e}}\n\n## Core Model\n\nCompanion release distribution is intentionally split between build control in the main repository, release assets in a dedicated release repository, and public feed serving from a separate feed host.\n\nThat split keeps Companion binaries out of normal Sambee deployments while still letting:\n\n- Sambee render Companion download links.\n- Installed Companion builds fetch updates.\n\nThe current model uses four moving parts:\n\n1. The main `sambee` repository builds Companion releases.\n2. The dedicated `sambee-companion` repository hosts immutable GitHub Release assets and stores the committed feed files under `docs/feeds`.\n3. The separate host `https://release-feeds.sambee.net` serves those committed feed files publicly.\n4. Channel manifests under `stable`, `beta`, and `test` decide which published release installed Companion builds see.\n5. A separate Sambee download-metadata file decides which installer links Sambee renders in the product UI.\n\nThe important consequence is simple: channels are feed pointers, not separate binaries.\n\nEvery successful Companion build moves only the `test` updater feed. It does not change `beta`, `stable`, or the Sambee download-metadata feed.\n\n## Public Distribution Surface\n\nPublished Companion releases live in `helgeklein/sambee-companion` as GitHub Releases.\n\nThe public feed host is:\n\n- `https://release-feeds.sambee.net`\n\nThat host is separate from the main `sambee.net` website deployment in this repository.\nThe website workflow here deploys `website/public` to Cloudflare Pages for `sambee.net`, while the live feed host currently responds separately.\n\nThe current public layout is:\n\n```text\nfeeds/companion/tauri/stable/latest.json\nfeeds/companion/tauri/beta/latest.json\nfeeds/companion/tauri/test/latest.json\nfeeds/sambee/companion/latest.json\n```\n\nInside the release repository, those files are committed under `docs/feeds/`.\nThat repository path is the source of the published feed JSON, not the same thing as the main website source tree in this repository.\n\n## Who Reads What\n\n| Consumer | Public file | Format | Purpose |\n|---|---|---|---|\n| Installed Companion builds | `feeds/companion/tauri/\u003cchannel\u003e/latest.json` | Tauri updater JSON | Exposes the published release visible to the selected update channel. |\n| Sambee backend | `feeds/sambee/companion/latest.json` | Sambee-specific download metadata | Exposes version, notes, and installer URLs for the product UI. |\n\nSambee and Companion do not read the same feed.\n\n- Promoting a Companion channel changes auto-update visibility for installed desktop apps.\n- Promoting the Sambee metadata feed changes which direct downloads the product surfaces.\n- The same published release can move across `test`, `beta`, and `stable` over time.\n- The build workflow promotes `test` automatically; later promotion targets remain manual.\n\n## Feed Rules\n\nInstalled Companion builds consume standard Tauri updater JSON.\n\nImportant behavior:\n\n- Each channel manifest points to immutable release assets in `sambee-companion`.\n- Feed files can move between releases over time, but published asset URLs should not be patched in place.\n- Each publishable release uses a new plain numeric `X.Y.Z` version. Tauri offers an update only when the later version is greater; publishing replacement bytes under an equal version is unsupported.\n- The promotion script includes every platform for which it finds a complete bundle-and-signature pair.\n- A release does not need every platform to be promotable.\n\nSambee uses a different JSON document.\n\nImportant behavior:\n\n- It contains only what Sambee needs to render download UI.\n- The asset map can contain any supported subset of discovered installers.\n- Sambee does not read the Tauri channel manifests directly.\n\n## Runtime Behavior\n\nCompanion uses `tauri-plugin-updater` for self-update checks.\n\nThe runtime updater is channel-aware:\n\n- The Rust update commands build the updater URL from the selected channel at runtime.\n- The frontend stores the local preference as `companionUpdateChannel`.\n- Allowed channel values are `stable`, `beta`, and `test`.\n- The default channel is `stable`.\n\nIn practice, that means the same installed app can see different releases over time based on the local channel setting and the currently promoted feed file.\n\n## Sambee Integration\n\nSambee does not bundle Companion binaries.\n\nBy default, the backend resolves Companion download metadata from `https://release-feeds.sambee.net/feeds/sambee/companion/latest.json`.\n\nThe backend then:\n\n- Fetches the hosted Companion download metadata.\n- Normalizes and validates installer URLs.\n- Exposes the result through the backend API to the frontend.\n\nSambee also supports a deterministic pin override in configuration.\n\nWhen a pin is configured, the backend stops using the hosted feed for Companion download links and serves the pinned version, notes, and installer URLs instead.\n\n## App Identity And Signing\n\nCompanion uses one app identity across all update channels.\n\nChannel separation comes from feed selection, not from separate binaries or per-channel app identifiers.\n\nCompanion also uses one Tauri updater signing key across all channels.\n\n- Updater artifacts are signed during release builds.\n- Installed Companion builds verify updates using the embedded updater public key.\n- Platform-specific installer signing is separate from the Tauri updater signature.\n", "2.0": "+++\ntitle = \"Companion Channels, Feeds \u0026 Downloads\"\n+++\n\nUse this page when you need the system model behind Companion release promotion.\n\nIt explains which public files exist, who reads them, and why channel promotion does not require rebuilding binaries.\n\n{{\u003c companion-promotion-overview \u003e}}\n\n## Core Model\n\nCompanion release distribution is intentionally split between build control in the main repository, release assets in a dedicated release repository, and public feed serving from a separate feed host.\n\nThat split keeps Companion binaries out of normal Sambee deployments while still letting:\n\n- Sambee render Companion download links.\n- Installed Companion builds fetch updates.\n\nThe current model uses four moving parts:\n\n1. The main `sambee` repository builds Companion releases.\n2. The dedicated `sambee-companion` repository hosts immutable GitHub Release assets and stores the committed feed files under `docs/feeds`.\n3. The separate host `https://release-feeds.sambee.net` serves those committed feed files publicly.\n4. Channel manifests under `stable`, `beta`, and `test` decide which published release installed Companion builds see.\n5. A separate Sambee download-metadata file decides which installer links Sambee renders in the product UI.\n\nThe important consequence is simple: channels are feed pointers, not separate binaries.\n\nEvery successful Companion build moves only the `test` updater feed. It does not change `beta`, `stable`, or the Sambee download-metadata feed.\n\n## Public Distribution Surface\n\nPublished Companion releases live in `sambee-app/sambee-companion` as GitHub Releases.\n\nThe public feed host is:\n\n- `https://release-feeds.sambee.net`\n\nThat host is separate from the main `sambee.net` website deployment in this repository.\nThe website workflow here deploys `website/public` to Cloudflare Pages for `sambee.net`, while the live feed host currently responds separately.\n\nThe current public layout is:\n\n```text\nfeeds/companion/tauri/stable/latest.json\nfeeds/companion/tauri/beta/latest.json\nfeeds/companion/tauri/test/latest.json\nfeeds/sambee/companion/latest.json\n```\n\nInside the release repository, those files are committed under `docs/feeds/`.\nThat repository path is the source of the published feed JSON, not the same thing as the main website source tree in this repository.\n\n## Who Reads What\n\n| Consumer | Public file | Format | Purpose |\n|---|---|---|---|\n| Installed Companion builds | `feeds/companion/tauri/\u003cchannel\u003e/latest.json` | Tauri updater JSON | Exposes the published release visible to the selected update channel. |\n| Sambee backend | `feeds/sambee/companion/latest.json` | Sambee-specific download metadata | Exposes version, notes, and installer URLs for the product UI. |\n\nSambee and Companion do not read the same feed.\n\n- Promoting a Companion channel changes auto-update visibility for installed desktop apps.\n- Promoting the Sambee metadata feed changes which direct downloads the product surfaces.\n- The same published release can move across `test`, `beta`, and `stable` over time.\n- The build workflow promotes `test` automatically; later promotion targets remain manual.\n\n## Feed Rules\n\nInstalled Companion builds consume standard Tauri updater JSON.\n\nImportant behavior:\n\n- Each channel manifest points to immutable release assets in `sambee-companion`.\n- Feed files can move between releases over time, but published asset URLs should not be patched in place.\n- Each publishable release uses a new plain numeric `X.Y.Z` version. Tauri offers an update only when the later version is greater; publishing replacement bytes under an equal version is unsupported.\n- The promotion script includes every platform for which it finds a complete bundle-and-signature pair.\n- A release does not need every platform to be promotable.\n\nSambee uses a different JSON document.\n\nImportant behavior:\n\n- It contains only what Sambee needs to render download UI.\n- The asset map can contain any supported subset of discovered installers.\n- Sambee does not read the Tauri channel manifests directly.\n\n## Runtime Behavior\n\nCompanion uses `tauri-plugin-updater` for self-update checks.\n\nThe runtime updater is channel-aware:\n\n- The Rust update commands build the updater URL from the selected channel at runtime.\n- The frontend stores the local preference as `companionUpdateChannel`.\n- Allowed channel values are `stable`, `beta`, and `test`.\n- The default channel is `stable`.\n\nIn practice, that means the same installed app can see different releases over time based on the local channel setting and the currently promoted feed file.\n\n## Sambee Integration\n\nSambee does not bundle Companion binaries.\n\nBy default, the backend resolves Companion download metadata from `https://release-feeds.sambee.net/feeds/sambee/companion/latest.json`.\n\nThe backend then:\n\n- Fetches the hosted Companion download metadata.\n- Normalizes and validates installer URLs.\n- Exposes the result through the backend API to the frontend.\n\nSambee also supports a deterministic pin override in configuration.\n\nWhen a pin is configured, the backend stops using the hosted feed for Companion download links and serves the pinned version, notes, and installer URLs instead.\n\n## App Identity And Signing\n\nCompanion uses one app identity across all update channels.\n\nChannel separation comes from feed selection, not from separate binaries or per-channel app identifiers.\n\nCompanion also uses one Tauri updater signing key across all channels.\n\n- Updater artifacts are signed during release builds.\n- Installed Companion builds verify updates using the embedded updater public key.\n- Platform-specific installer signing is separate from the Tauri updater signature.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Companion Channels, Feeds, And Downloads\"\n+++\n\nUse this page when you need the system model behind Companion release promotion.\n\nIt explains which public files exist, who reads them, and why channel promotion does not require rebuilding binaries.\n\n## Core Model\n\nCompanion release distribution is intentionally split between build control in the main repository, release assets in a dedicated release repository, and public feed serving from a separate feed host.\n\nThat split keeps Companion binaries out of normal Sambee deployments while still letting:\n\n- Sambee render Companion download links.\n- Installed Companion builds fetch updates.\n\nThe current model uses four moving parts:\n\n1. The main `sambee` repository builds Companion releases.\n2. The dedicated `sambee-companion` repository hosts immutable GitHub Release assets and stores the committed feed files under `docs/feeds`.\n3. The separate host `https://release-feeds.sambee.net` serves those committed feed files publicly.\n4. Channel manifests under `stable`, `beta`, and `test` decide which published release installed Companion builds see.\n5. A separate Sambee download-metadata file decides which installer links Sambee renders in the product UI.\n\nThe important consequence is simple: channels are feed pointers, not separate binaries.\n\n## Public Distribution Surface\n\nPublished Companion releases live in `helgeklein/sambee-companion` as GitHub Releases.\n\nThe public feed host is:\n\n- `https://release-feeds.sambee.net`\n\nThat host is separate from the main `sambee.net` website deployment in this repository.\nThe website workflow here deploys `website/public` to Cloudflare Pages for `sambee.net`, while the live feed host currently responds separately.\n\nThe current public layout is:\n\n```text\nfeeds/companion/tauri/stable/latest.json\nfeeds/companion/tauri/beta/latest.json\nfeeds/companion/tauri/test/latest.json\nfeeds/sambee/companion/latest.json\n```\n\nInside the release repository, those files are committed under `docs/feeds/`.\nThat repository path is the source of the published feed JSON, not the same thing as the main website source tree in this repository.\n\n## Who Reads What\n\n| Consumer | Public file | Format | Purpose |\n|---|---|---|---|\n| Installed Companion builds | `feeds/companion/tauri/\u003cchannel\u003e/latest.json` | Tauri updater JSON | Exposes the published release visible to the selected update channel. |\n| Sambee backend | `feeds/sambee/companion/latest.json` | Sambee-specific download metadata | Exposes version, notes, and installer URLs for the product UI. |\n\nSambee and Companion do not read the same feed.\n\n- Promoting a Companion channel changes auto-update visibility for installed desktop apps.\n- Promoting the Sambee metadata feed changes which direct downloads the product surfaces.\n- The same published release can move across `test`, `beta`, and `stable` over time.\n\n## Feed Rules\n\nInstalled Companion builds consume standard Tauri updater JSON.\n\nImportant behavior:\n\n- Each channel manifest points to immutable release assets in `sambee-companion`.\n- Feed files can move between releases over time, but published asset URLs should not be patched in place.\n- The promotion script includes every platform for which it finds a complete bundle-and-signature pair.\n- A release does not need every platform to be promotable.\n\nSambee uses a different JSON document.\n\nImportant behavior:\n\n- It contains only what Sambee needs to render download UI.\n- The asset map can contain any supported subset of discovered installers.\n- Sambee does not read the Tauri channel manifests directly.\n\n## Runtime Behavior\n\nCompanion uses `tauri-plugin-updater` for self-update checks.\n\nThe runtime updater is channel-aware:\n\n- The Rust update commands build the updater URL from the selected channel at runtime.\n- The frontend stores the local preference as `companionUpdateChannel`.\n- Allowed channel values are `stable`, `beta`, and `test`.\n- The default channel is `stable`.\n\nIn practice, that means the same installed app can see different releases over time based on the local channel setting and the currently promoted feed file.\n\n## Sambee Integration\n\nSambee does not bundle Companion binaries.\n\nBy default, the backend resolves Companion download metadata from `https://release-feeds.sambee.net/feeds/sambee/companion/latest.json`.\n\nThe backend then:\n\n- Fetches the hosted Companion download metadata.\n- Normalizes and validates installer URLs.\n- Exposes the result through the backend API to the frontend.\n\nSambee also supports a deterministic pin override in configuration.\n\nWhen a pin is configured, the backend stops using the hosted feed for Companion download links and serves the pinned version, notes, and installer URLs instead.\n\n## App Identity And Signing\n\nCompanion uses one app identity across all update channels.\n\nChannel separation comes from feed selection, not from separate binaries or per-channel app identifiers.\n\nCompanion also uses one Tauri updater signing key across all channels.\n\n- Updater artifacts are signed during release builds.\n- Installed Companion builds verify updates using the embedded updater public key.\n- Platform-specific installer signing is separate from the Tauri updater signature.\n\n## Contributor Rules\n\n- Do not treat update channels as different binaries.\n- Do not patch broken published assets in place.\n- Build and publish a new release instead.\n- Review whether you are changing Companion updater visibility, Sambee download visibility, or both.\n- Keep release automation aligned with asset naming conventions, because promotion depends on asset-pattern matching.\n\n", "0.8": "+++\ntitle = \"Companion Channels, Feeds, And Downloads\"\n+++\n\nUse this page when you need the system model behind Companion release promotion.\n\nIt explains which public files exist, who reads them, and why channel promotion does not require rebuilding binaries.\n\n## Core Model\n\nCompanion release distribution is intentionally split between build control in the main repository, release assets in a dedicated release repository, and public feed serving from a separate feed host.\n\nThat split keeps Companion binaries out of normal Sambee deployments while still letting:\n\n- Sambee render Companion download links.\n- Installed Companion builds fetch updates.\n\nThe current model uses four moving parts:\n\n1. The main `sambee` repository builds Companion releases.\n2. The dedicated `sambee-companion` repository hosts immutable GitHub Release assets and stores the committed feed files under `docs/feeds`.\n3. The separate host `https://release-feeds.sambee.net` serves those committed feed files publicly.\n4. Channel manifests under `stable`, `beta`, and `test` decide which published release installed Companion builds see.\n5. A separate Sambee download-metadata file decides which installer links Sambee renders in the product UI.\n\nThe important consequence is simple: channels are feed pointers, not separate binaries.\n\n## Public Distribution Surface\n\nPublished Companion releases live in `helgeklein/sambee-companion` as GitHub Releases.\n\nThe public feed host is:\n\n- `https://release-feeds.sambee.net`\n\nThat host is separate from the main `sambee.net` website deployment in this repository.\nThe website workflow here deploys `website/public` to Cloudflare Pages for `sambee.net`, while the live feed host currently responds separately.\n\nThe current public layout is:\n\n```text\nfeeds/companion/tauri/stable/latest.json\nfeeds/companion/tauri/beta/latest.json\nfeeds/companion/tauri/test/latest.json\nfeeds/sambee/companion/latest.json\n```\n\nInside the release repository, those files are committed under `docs/feeds/`.\nThat repository path is the source of the published feed JSON, not the same thing as the main website source tree in this repository.\n\n## Who Reads What\n\n| Consumer | Public file | Format | Purpose |\n|---|---|---|---|\n| Installed Companion builds | `feeds/companion/tauri/\u003cchannel\u003e/latest.json` | Tauri updater JSON | Exposes the published release visible to the selected update channel. |\n| Sambee backend | `feeds/sambee/companion/latest.json` | Sambee-specific download metadata | Exposes version, notes, and installer URLs for the product UI. |\n\nSambee and Companion do not read the same feed.\n\n- Promoting a Companion channel changes auto-update visibility for installed desktop apps.\n- Promoting the Sambee metadata feed changes which direct downloads the product surfaces.\n- The same published release can move across `test`, `beta`, and `stable` over time.\n\n## Feed Rules\n\nInstalled Companion builds consume standard Tauri updater JSON.\n\nImportant behavior:\n\n- Each channel manifest points to immutable release assets in `sambee-companion`.\n- Feed files can move between releases over time, but published asset URLs should not be patched in place.\n- The promotion script includes every platform for which it finds a complete bundle-and-signature pair.\n- A release does not need every platform to be promotable.\n\nSambee uses a different JSON document.\n\nImportant behavior:\n\n- It contains only what Sambee needs to render download UI.\n- The asset map can contain any supported subset of discovered installers.\n- Sambee does not read the Tauri channel manifests directly.\n\n## Runtime Behavior\n\nCompanion uses `tauri-plugin-updater` for self-update checks.\n\nThe runtime updater is channel-aware:\n\n- The Rust update commands build the updater URL from the selected channel at runtime.\n- The frontend stores the local preference as `companionUpdateChannel`.\n- Allowed channel values are `stable`, `beta`, and `test`.\n- The default channel is `stable`.\n\nIn practice, that means the same installed app can see different releases over time based on the local channel setting and the currently promoted feed file.\n\n## Sambee Integration\n\nSambee does not bundle Companion binaries.\n\nBy default, the backend resolves Companion download metadata from `https://release-feeds.sambee.net/feeds/sambee/companion/latest.json`.\n\nThe backend then:\n\n- Fetches the hosted Companion download metadata.\n- Normalizes and validates installer URLs.\n- Exposes the result through the backend API to the frontend.\n\nSambee also supports a deterministic pin override in configuration.\n\nWhen a pin is configured, the backend stops using the hosted feed for Companion download links and serves the pinned version, notes, and installer URLs instead.\n\n## App Identity And Signing\n\nCompanion uses one app identity across all update channels.\n\nChannel separation comes from feed selection, not from separate binaries or per-channel app identifiers.\n\nCompanion also uses one Tauri updater signing key across all channels.\n\n- Updater artifacts are signed during release builds.\n- Installed Companion builds verify updates using the embedded updater public key.\n- Platform-specific installer signing is separate from the Tauri updater signature.\n\n## Contributor Rules\n\n- Do not treat update channels as different binaries.\n- Do not patch broken published assets in place.\n- Build and publish a new release instead.\n- Review whether you are changing Companion updater visibility, Sambee download visibility, or both.\n- Keep release automation aligned with asset naming conventions, because promotion depends on asset-pattern matching.\n\n", "0.9": "+++\ntitle = \"Companion Channels, Feeds, And Downloads\"\n+++\n\nUse this page when you need the system model behind Companion release promotion.\n\nIt explains which public files exist, who reads them, and why channel promotion does not require rebuilding binaries.\n\n## Core Model\n\nCompanion release distribution is intentionally split between build control in the main repository, release assets in a dedicated release repository, and public feed serving from a separate feed host.\n\nThat split keeps Companion binaries out of normal Sambee deployments while still letting:\n\n- Sambee render Companion download links.\n- Installed Companion builds fetch updates.\n\nThe current model uses four moving parts:\n\n1. The main `sambee` repository builds Companion releases.\n2. The dedicated `sambee-companion` repository hosts immutable GitHub Release assets and stores the committed feed files under `docs/feeds`.\n3. The separate host `https://release-feeds.sambee.net` serves those committed feed files publicly.\n4. Channel manifests under `stable`, `beta`, and `test` decide which published release installed Companion builds see.\n5. A separate Sambee download-metadata file decides which installer links Sambee renders in the product UI.\n\nThe important consequence is simple: channels are feed pointers, not separate binaries.\n\n## Public Distribution Surface\n\nPublished Companion releases live in `helgeklein/sambee-companion` as GitHub Releases.\n\nThe public feed host is:\n\n- `https://release-feeds.sambee.net`\n\nThat host is separate from the main `sambee.net` website deployment in this repository.\nThe website workflow here deploys `website/public` to Cloudflare Pages for `sambee.net`, while the live feed host currently responds separately.\n\nThe current public layout is:\n\n```text\nfeeds/companion/tauri/stable/latest.json\nfeeds/companion/tauri/beta/latest.json\nfeeds/companion/tauri/test/latest.json\nfeeds/sambee/companion/latest.json\n```\n\nInside the release repository, those files are committed under `docs/feeds/`.\nThat repository path is the source of the published feed JSON, not the same thing as the main website source tree in this repository.\n\n## Who Reads What\n\n| Consumer | Public file | Format | Purpose |\n|---|---|---|---|\n| Installed Companion builds | `feeds/companion/tauri/\u003cchannel\u003e/latest.json` | Tauri updater JSON | Exposes the published release visible to the selected update channel. |\n| Sambee backend | `feeds/sambee/companion/latest.json` | Sambee-specific download metadata | Exposes version, notes, and installer URLs for the product UI. |\n\nSambee and Companion do not read the same feed.\n\n- Promoting a Companion channel changes auto-update visibility for installed desktop apps.\n- Promoting the Sambee metadata feed changes which direct downloads the product surfaces.\n- The same published release can move across `test`, `beta`, and `stable` over time.\n\n## Feed Rules\n\nInstalled Companion builds consume standard Tauri updater JSON.\n\nImportant behavior:\n\n- Each channel manifest points to immutable release assets in `sambee-companion`.\n- Feed files can move between releases over time, but published asset URLs should not be patched in place.\n- Each publishable release uses a new plain numeric `X.Y.Z` version. Tauri offers an update only when the later version is greater; publishing replacement bytes under an equal version is unsupported.\n- The promotion script includes every platform for which it finds a complete bundle-and-signature pair.\n- A release does not need every platform to be promotable.\n\nSambee uses a different JSON document.\n\nImportant behavior:\n\n- It contains only what Sambee needs to render download UI.\n- The asset map can contain any supported subset of discovered installers.\n- Sambee does not read the Tauri channel manifests directly.\n\n## Runtime Behavior\n\nCompanion uses `tauri-plugin-updater` for self-update checks.\n\nThe runtime updater is channel-aware:\n\n- The Rust update commands build the updater URL from the selected channel at runtime.\n- The frontend stores the local preference as `companionUpdateChannel`.\n- Allowed channel values are `stable`, `beta`, and `test`.\n- The default channel is `stable`.\n\nIn practice, that means the same installed app can see different releases over time based on the local channel setting and the currently promoted feed file.\n\n## Sambee Integration\n\nSambee does not bundle Companion binaries.\n\nBy default, the backend resolves Companion download metadata from `https://release-feeds.sambee.net/feeds/sambee/companion/latest.json`.\n\nThe backend then:\n\n- Fetches the hosted Companion download metadata.\n- Normalizes and validates installer URLs.\n- Exposes the result through the backend API to the frontend.\n\nSambee also supports a deterministic pin override in configuration.\n\nWhen a pin is configured, the backend stops using the hosted feed for Companion download links and serves the pinned version, notes, and installer URLs instead.\n\n## App Identity And Signing\n\nCompanion uses one app identity across all update channels.\n\nChannel separation comes from feed selection, not from separate binaries or per-channel app identifiers.\n\nCompanion also uses one Tauri updater signing key across all channels.\n\n- Updater artifacts are signed during release builds.\n- Installed Companion builds verify updates using the embedded updater public key.\n- Platform-specific installer signing is separate from the Tauri updater signature.\n\n## Contributor Rules\n\n- Do not treat update channels as different binaries.\n- Do not patch broken published assets in place.\n- Build and publish a new `Z` version instead.\n- Treat `test`, `beta`, and `stable` as visibility pointers, never as different binaries or version suffixes.\n- Review whether you are changing Companion updater visibility, Sambee download visibility, or both.\n- Keep release automation aligned with asset naming conventions, because promotion depends on asset-pattern matching.\n\n", "1.0": "+++\ntitle = \"Companion Channels, Feeds \u0026 Downloads\"\n+++\n\nUse this page when you need the system model behind Companion release promotion.\n\nIt explains which public files exist, who reads them, and why channel promotion does not require rebuilding binaries.\n\n{{\u003c companion-promotion-overview \u003e}}\n\n## Core Model\n\nCompanion release distribution is intentionally split between build control in the main repository, release assets in a dedicated release repository, and public feed serving from a separate feed host.\n\nThat split keeps Companion binaries out of normal Sambee deployments while still letting:\n\n- Sambee render Companion download links.\n- Installed Companion builds fetch updates.\n\nThe current model uses four moving parts:\n\n1. The main `sambee` repository builds Companion releases.\n2. The dedicated `sambee-companion` repository hosts immutable GitHub Release assets and stores the committed feed files under `docs/feeds`.\n3. The separate host `https://release-feeds.sambee.net` serves those committed feed files publicly.\n4. Channel manifests under `stable`, `beta`, and `test` decide which published release installed Companion builds see.\n5. A separate Sambee download-metadata file decides which installer links Sambee renders in the product UI.\n\nThe important consequence is simple: channels are feed pointers, not separate binaries.\n\nEvery successful Companion build moves only the `test` updater feed. It does not change `beta`, `stable`, or the Sambee download-metadata feed.\n\n## Public Distribution Surface\n\nPublished Companion releases live in `helgeklein/sambee-companion` as GitHub Releases.\n\nThe public feed host is:\n\n- `https://release-feeds.sambee.net`\n\nThat host is separate from the main `sambee.net` website deployment in this repository.\nThe website workflow here deploys `website/public` to Cloudflare Pages for `sambee.net`, while the live feed host currently responds separately.\n\nThe current public layout is:\n\n```text\nfeeds/companion/tauri/stable/latest.json\nfeeds/companion/tauri/beta/latest.json\nfeeds/companion/tauri/test/latest.json\nfeeds/sambee/companion/latest.json\n```\n\nInside the release repository, those files are committed under `docs/feeds/`.\nThat repository path is the source of the published feed JSON, not the same thing as the main website source tree in this repository.\n\n## Who Reads What\n\n| Consumer | Public file | Format | Purpose |\n|---|---|---|---|\n| Installed Companion builds | `feeds/companion/tauri/\u003cchannel\u003e/latest.json` | Tauri updater JSON | Exposes the published release visible to the selected update channel. |\n| Sambee backend | `feeds/sambee/companion/latest.json` | Sambee-specific download metadata | Exposes version, notes, and installer URLs for the product UI. |\n\nSambee and Companion do not read the same feed.\n\n- Promoting a Companion channel changes auto-update visibility for installed desktop apps.\n- Promoting the Sambee metadata feed changes which direct downloads the product surfaces.\n- The same published release can move across `test`, `beta`, and `stable` over time.\n- The build workflow promotes `test` automatically; later promotion targets remain manual.\n\n## Feed Rules\n\nInstalled Companion builds consume standard Tauri updater JSON.\n\nImportant behavior:\n\n- Each channel manifest points to immutable release assets in `sambee-companion`.\n- Feed files can move between releases over time, but published asset URLs should not be patched in place.\n- Each publishable release uses a new plain numeric `X.Y.Z` version. Tauri offers an update only when the later version is greater; publishing replacement bytes under an equal version is unsupported.\n- The promotion script includes every platform for which it finds a complete bundle-and-signature pair.\n- A release does not need every platform to be promotable.\n\nSambee uses a different JSON document.\n\nImportant behavior:\n\n- It contains only what Sambee needs to render download UI.\n- The asset map can contain any supported subset of discovered installers.\n- Sambee does not read the Tauri channel manifests directly.\n\n## Runtime Behavior\n\nCompanion uses `tauri-plugin-updater` for self-update checks.\n\nThe runtime updater is channel-aware:\n\n- The Rust update commands build the updater URL from the selected channel at runtime.\n- The frontend stores the local preference as `companionUpdateChannel`.\n- Allowed channel values are `stable`, `beta`, and `test`.\n- The default channel is `stable`.\n\nIn practice, that means the same installed app can see different releases over time based on the local channel setting and the currently promoted feed file.\n\n## Sambee Integration\n\nSambee does not bundle Companion binaries.\n\nBy default, the backend resolves Companion download metadata from `https://release-feeds.sambee.net/feeds/sambee/companion/latest.json`.\n\nThe backend then:\n\n- Fetches the hosted Companion download metadata.\n- Normalizes and validates installer URLs.\n- Exposes the result through the backend API to the frontend.\n\nSambee also supports a deterministic pin override in configuration.\n\nWhen a pin is configured, the backend stops using the hosted feed for Companion download links and serves the pinned version, notes, and installer URLs instead.\n\n## App Identity And Signing\n\nCompanion uses one app identity across all update channels.\n\nChannel separation comes from feed selection, not from separate binaries or per-channel app identifiers.\n\nCompanion also uses one Tauri updater signing key across all channels.\n\n- Updater artifacts are signed during release builds.\n- Installed Companion builds verify updates using the embedded updater public key.\n- Platform-specific installer signing is separate from the Tauri updater signature.\n", "2.0": "+++\ntitle = \"Companion Channels, Feeds \u0026 Downloads\"\n+++\n\nUse this page when you need the system model behind Companion release promotion.\n\nIt explains which public files exist, who reads them, and why channel promotion does not require rebuilding binaries.\n\n{{\u003c companion-promotion-overview \u003e}}\n\n## Core Model\n\nCompanion release distribution is intentionally split between build control in the main repository, release assets in a dedicated release repository, and public feed serving from a separate feed host.\n\nThat split keeps Companion binaries out of normal Sambee deployments while still letting:\n\n- Sambee render Companion download links.\n- Installed Companion builds fetch updates.\n\nThe current model uses four moving parts:\n\n1. The main `sambee` repository builds Companion releases.\n2. The dedicated `sambee-companion` repository hosts immutable GitHub Release assets and stores the committed feed files under `docs/feeds`.\n3. The separate host `https://release-feeds.sambee.net` serves those committed feed files publicly.\n4. Channel manifests under `stable`, `beta`, and `test` decide which published release installed Companion builds see.\n5. A separate Sambee download-metadata file decides which installer links Sambee renders in the product UI.\n\nThe important consequence is simple: channels are feed pointers, not separate binaries.\n\nEvery successful Companion build moves only the `test` updater feed. It does not change `beta`, `stable`, or the Sambee download-metadata feed.\n\n## Public Distribution Surface\n\nPublished Companion releases live in `sambee-app/sambee-companion` as GitHub Releases.\n\nThe public feed host is:\n\n- `https://release-feeds.sambee.net`\n\nThat host is separate from the main `sambee.net` website deployment in this repository.\nThe website workflow here deploys `website/public` to Cloudflare Pages for `sambee.net`, while the live feed host currently responds separately.\n\nThe current public layout is:\n\n```text\nfeeds/companion/tauri/stable/latest.json\nfeeds/companion/tauri/beta/latest.json\nfeeds/companion/tauri/test/latest.json\nfeeds/sambee/companion/latest.json\n```\n\nInside the release repository, those files are committed under `docs/feeds/`.\nThat repository path is the source of the published feed JSON, not the same thing as the main website source tree in this repository.\n\n## Who Reads What\n\n| Consumer | Public file | Format | Purpose |\n|---|---|---|---|\n| Installed Companion builds | `feeds/companion/tauri/\u003cchannel\u003e/latest.json` | Tauri updater JSON | Exposes the published release visible to the selected update channel. |\n| Sambee backend | `feeds/sambee/companion/latest.json` | Sambee-specific download metadata | Exposes version, notes, and installer URLs for the product UI. |\n\nSambee and Companion do not read the same feed.\n\n- Promoting a Companion channel changes auto-update visibility for installed desktop apps.\n- Promoting the Sambee metadata feed changes which direct downloads the product surfaces.\n- The same published release can move across `test`, `beta`, and `stable` over time.\n- The build workflow promotes `test` automatically; later promotion targets remain manual.\n\n## Feed Rules\n\nInstalled Companion builds consume standard Tauri updater JSON.\n\nImportant behavior:\n\n- Each channel manifest points to immutable release assets in `sambee-companion`.\n- Feed files can move between releases over time, but published asset URLs should not be patched in place.\n- Each publishable release uses a new plain numeric `X.Y.Z` version. Tauri offers an update only when the later version is greater; publishing replacement bytes under an equal version is unsupported.\n- The promotion script includes every platform for which it finds a complete bundle-and-signature pair.\n- A release does not need every platform to be promotable.\n\nSambee uses a different JSON document.\n\nImportant behavior:\n\n- It contains only what Sambee needs to render download UI.\n- The asset map can contain any supported subset of discovered installers.\n- Sambee does not read the Tauri channel manifests directly.\n\n## Runtime Behavior\n\nCompanion uses `tauri-plugin-updater` for self-update checks.\n\nThe runtime updater is channel-aware:\n\n- The Rust update commands build the updater URL from the selected channel at runtime.\n- The frontend stores the local preference as `companionUpdateChannel`.\n- Allowed channel values are `stable`, `beta`, and `test`.\n- The default channel is `stable`.\n\nIn practice, that means the same installed app can see different releases over time based on the local channel setting and the currently promoted feed file.\n\n## Sambee Integration\n\nSambee does not bundle Companion binaries.\n\nBy default, the backend resolves Companion download metadata from `https://release-feeds.sambee.net/feeds/sambee/companion/latest.json`.\n\nThe backend then:\n\n- Fetches the hosted Companion download metadata.\n- Normalizes and validates installer URLs.\n- Exposes the result through the backend API to the frontend.\n\nSambee also supports a deterministic pin override in configuration.\n\nWhen a pin is configured, the backend stops using the hosted feed for Companion download links and serves the pinned version, notes, and installer URLs instead.\n\n## App Identity And Signing\n\nCompanion uses one app identity across all update channels.\n\nChannel separation comes from feed selection, not from separate binaries or per-channel app identifiers.\n\nCompanion also uses one Tauri updater signing key across all channels.\n\n- Updater artifacts are signed during release builds.\n- Installed Companion builds verify updates using the embedded updater public key.\n- Platform-specific installer signing is separate from the Tauri updater signature.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/release-and-versioning/release-overview", "parent_id": "section:developer-guide/release-and-versioning", "depth": 2, "kind": "page", "label": "release-overview", "title": "Release Overview", "path": "developer-guide/release-and-versioning/release-overview", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "authored"}, "0.9": {"state": "branched", "source_version": "0.8", "diff_added": 58, "diff_removed": 21}, "1.0": {"state": "branched", "source_version": "0.9", "diff_added": 20, "diff_removed": 13}, "2.0": {"state": "branched", "source_version": "1.0", "diff_added": 2, "diff_removed": 2}}, "content_versions": {"0.8": "+++\ntitle = \"Release Overview\"\n+++\n\n## Preparation\n\n1. Update the product **version** ([details](../product-versioning/)). Ensure it's at the version you want to release.\n\n## Build and Test the Docker Image\n\nSee [Overview](../docker-release-overview/).\n\n1. Run the CI workflow [Release: Create Docker Image](../build-docker-image/) to **build** the Docker image and move the `test` tag to it.\n   - Don't override the product version in the CI workflow.\n1. **Test** the newly built image (pull it via the `test` tag).\n\n## Documentation\n\n1. Review the **homepage** content and update it where necessary.\n1. **Docs:**\n   - Verify [Supported File Formats](../../../user-guide/reference/supported-file-formats/) and update as necessary.\n   - Finalize the target release's [What's New](/release-info/news-and-changes/whats-new/) page.\n   - Mark the target version as current in `website/data/docs-versions.toml`.\n   - Run the VS Code task **Website: Refresh Docs Derived Artifacts**.\n   - Review the Docs Structure Report this creates in `/workspace/website-meta/docs-reports/docs-structure-report.html`.\n1. Git merge all changes.\n\n## Publish the Docker Image\n\nSee [Overview](../docker-release-overview/).\n\n1. Create a Git tag on the commit the tested image was built from.\n1. Publish a GitHub release from that tag.\n   - Release publication triggers [Release: Publish Docker Image](../promote-docker-image/), which tags the image built earlier as `beta` (prereleases) or `stable` and adds version tags for stable releases.\n\n## Publish the Companion\n\nSee [Overview](../companion-release-overview/)\n\n1. Run [Release: Build Companion Artifact](../build-companion-release/) to build Companion for the target platforms.\n   - Publish the Companion GitHub Release created by the workflow.\n1. Run [Release: Promote Companion Release](../promote-companion-release/) to promote the release to the `test`, `beta`, and/or `stable` update channels and to update the Sambee download-metadata feed.\n", "0.9": "+++\ntitle = \"Release Overview\"\n+++\n\n## Principles\n\n- The version number source of truth is the `VERSION` file in the repository.\n- Every built artifact gets a unique version number.\n- Each version is built only once.\n- Releases happen without rebuilds but by applying tags to existing builds (Docker image) or updating channel pointers (Companion app).\n\n## Process Overview for Test and Preview Candidates\n\n1. Update `VERSION` to the next plain numeric `X.Y.Z` build sequence ([details](../product-versioning/)).\n   - Run `./scripts/sync-version`.\n   - Commit the synchronized metadata on `main`.\n1. Build the affected component (see below for details).\n   - Build workflows reserve the current `VERSION` by adding a Git tag when building from the latest commit.\n   - Alternatively, select an existing `build-vX.Y.Z` Git tag to build from.\n1. Test the resulting build.\n   - Docker: Through the `test` tag.\n   - Companion: Through the Companion draft release assets. Promote them to the Companion `test` feed as needed.\n1. Repeat the loop with a new `Z` value when a new candidate is required. Never rebuild or replace a published artifact under the same version.\n\nNotes:\n\n- Docker and Companion candidates may be built independently.\n\n## Component Build \u0026 Release Process\n\n### Update Documentation\n\n1. Review the homepage content and update it where necessary.\n1. Docs:\n   - Verify [Supported File Formats](../../../user-guide/reference/supported-file-formats/) and update as necessary.\n   - Finalize the target release's [What's New](/release-info/news-and-changes/whats-new/) page.\n   - Mark the target version as current in `website/data/docs-versions.toml`.\n   - Run the VS Code task `Website: Refresh Docs Derived Artifacts`.\n   - Review the Docs Structure Report this creates in `/workspace/website-meta/docs-reports/docs-structure-report.html`.\n1. Git merge all changes.\n\n### Build Docker Image\n\nSee this [Overview](../docker-release-overview/). In short:\n\n1. Run [Release: Create Docker Image](../build-docker-image/)\n   - The workflow:\n      - Builds the [Docker image](https://github.com/helgeklein/sambee/pkgs/container/sambee/versions).\n      - Moves the `test` tag to it.\n      - Adds the `X.Y.Z` version tag.\n1. To also move the `beta` tag to the newly built image, run [Release: Publish Docker Image](../promote-docker-image/) manually.\n\n### Build Companion\n\nSee this [Overview](../companion-release-overview/). In short:\n\n1. Run [Release: Build Companion Artifact](../build-companion-release/).\n   - The workflow creates a draft release in the [Companion GitHub repo](https://github.com/helgeklein/sambee-companion/releases).\n   - Publish it.\n\n### Publish a Build\n\nTo publish a candidate build after testing and validation, complete the following steps.\n\n1. Run `Release: Create Public Sambee Release`. Specify:\n   - the validated canonical build version.\n   - the intended scope: `docker`, `companion`, or `both`.\n1. The workflow creates or verifies a draft release in the Sambee GitHub repo.\n1. Review and edit the draft release's changelog, then publish it manually.\n\nIf you selected `docker` or `both`:\n\n- Publishing the reviewed draft triggers [Release: Publish Docker Image](../promote-docker-image/) through the GitHub Release event.\n   - The workflow tags the image built earlier as `beta` (if not ahead) and `stable`, and adds `X.Y` a version tag.\n\nIf you selected `companion` or `both`:\n\n1. Run [Release: Promote Companion Release](../promote-companion-release/).\n   - The workflow promotes the release to the `test`, `beta`, and/or `stable` update channels and updates the Sambee download-metadata feed.\n", "1.0": "+++\ntitle = \"Release Overview\"\n+++\n\n## Principles\n\n- The version number source of truth is the `VERSION` file in the repository.\n- Every built artifact gets a unique version number.\n- Each version is built only once.\n- Releases happen without rebuilds but by applying tags to existing builds (Docker image) or updating channel pointers (Companion app).\n\n## Process Overview for Test and Preview Candidates\n\n1. Update `VERSION` to the next plain numeric `X.Y.Z` build sequence ([details](../product-versioning/)).\n   - Run `./scripts/sync-version`.\n   - Commit the synchronized metadata on `main`.\n1. Build the affected component (see below for details).\n   - Build workflows reserve the current `VERSION` by adding a Git tag when building from the latest commit.\n   - Alternatively, select an existing `build-vX.Y.Z` Git tag to build from.\n1. Test the resulting build.\n   - Docker: Through the `test` tag.\n   - Companion: Through the Companion draft release assets. Promote them to the Companion `test` feed as needed.\n1. Repeat the loop with a new `Z` value when a new candidate is required. Never rebuild or replace a published artifact under the same version.\n\nNotes:\n\n- Docker and Companion candidates may be built independently.\n\n## Release Process \u0026 Checklist\n\n### Update Website\n\n1. Review the homepage content and update it where necessary.\n\n### Update Documentation\n\n1. Verify [Supported File Formats](../../../user-guide/reference/supported-file-formats/) and update as necessary.\n1. Finalize the target release's [What's New](/release-info/news-and-changes/whats-new/) page.\n1. Mark the target version as current in `website/data/docs-versions.toml`:\n   - Update the top-level `current` key, e.g.: `current = \"1.0\"`\n   - Update the `[[versions]]` sections of the previous and the new current version\n1. Run the VS Code task `Website: Refresh Docs Derived Artifacts`.\n1. Review the Docs Structure Report this creates in `/workspace/website-meta/docs-reports/docs-structure-report.html`.\n\nGit merge all changes.\n\n### Build Docker Image\n\nSee this [Overview](../docker-release-overview/). In short:\n\n1. Run [Release: Create Docker Image](../build-docker-image/)\n   - The workflow:\n      - Builds the [Docker image](https://github.com/helgeklein/sambee/pkgs/container/sambee/versions).\n      - Moves the `test` tag to it.\n      - Adds the `X.Y.Z` version tag.\n1. To also move the `beta` tag to the newly built image, run [Release: Publish Docker Image](../promote-docker-image/) manually.\n\n### Build Companion\n\nSee this [Overview](../companion-release-overview/). In short:\n\n1. Run [Release: Build Companion Artifact](../build-companion-release/).\n   - The workflow:\n      - Creates and publishes a [Companion release](https://github.com/helgeklein/sambee-companion/releases)\n      - Moves the `test` tag to it.\n      - Adds the `X.Y.Z` version tag.\n\n### Publish a Build\n\nTo publish a candidate build after testing and validation, complete the following steps.\n\n1. Run `Release: Create Public Sambee Release`. Specify:\n   - the validated canonical build version.\n   - the intended scope: `docker`, `companion`, or `both`.\n1. The workflow creates or verifies a draft release in the Sambee GitHub repo.\n1. Review and edit the draft release's changelog, then publish it manually.\n\nIf you selected `docker` or `both`:\n\n- Publishing the reviewed draft triggers [Release: Publish Docker Image](../promote-docker-image/) through the GitHub Release event.\n   - The workflow tags the image built earlier as `beta` (if not ahead) and `stable`, and adds a `X.Y` version tag.\n\nIf you selected `companion` or `both`:\n\n1. Run [Release: Promote Companion Release](../promote-companion-release/).\n   - The workflow promotes the release to the `beta`, and/or `stable` update channels and updates the Sambee download-metadata feed.\n", "2.0": "+++\ntitle = \"Release Overview\"\n+++\n\n## Principles\n\n- The version number source of truth is the `VERSION` file in the repository.\n- Every built artifact gets a unique version number.\n- Each version is built only once.\n- Releases happen without rebuilds but by applying tags to existing builds (Docker image) or updating channel pointers (Companion app).\n\n## Process Overview for Test and Preview Candidates\n\n1. Update `VERSION` to the next plain numeric `X.Y.Z` build sequence ([details](../product-versioning/)).\n   - Run `./scripts/sync-version`.\n   - Commit the synchronized metadata on `main`.\n1. Build the affected component (see below for details).\n   - Build workflows reserve the current `VERSION` by adding a Git tag when building from the latest commit.\n   - Alternatively, select an existing `build-vX.Y.Z` Git tag to build from.\n1. Test the resulting build.\n   - Docker: Through the `test` tag.\n   - Companion: Through the Companion draft release assets. Promote them to the Companion `test` feed as needed.\n1. Repeat the loop with a new `Z` value when a new candidate is required. Never rebuild or replace a published artifact under the same version.\n\nNotes:\n\n- Docker and Companion candidates may be built independently.\n\n## Release Process \u0026 Checklist\n\n### Update Website\n\n1. Review the homepage content and update it where necessary.\n\n### Update Documentation\n\n1. Verify [Supported File Formats](../../../user-guide/reference/supported-file-formats/) and update as necessary.\n1. Finalize the target release's [What's New](/release-info/news-and-changes/whats-new/) page.\n1. Mark the target version as current in `website/data/docs-versions.toml`:\n   - Update the top-level `current` key, e.g.: `current = \"1.0\"`\n   - Update the `[[versions]]` sections of the previous and the new current version\n1. Run the VS Code task `Website: Refresh Docs Derived Artifacts`.\n1. Review the Docs Structure Report this creates in `/workspace/website-meta/docs-reports/docs-structure-report.html`.\n\nGit merge all changes.\n\n### Build Docker Image\n\nSee this [Overview](../docker-release-overview/). In short:\n\n1. Run [Release: Create Docker Image](../build-docker-image/)\n   - The workflow:\n      - Builds the [Docker image](https://github.com/sambee-app/sambee/pkgs/container/sambee/versions).\n      - Moves the `test` tag to it.\n      - Adds the `X.Y.Z` version tag.\n1. To also move the `beta` tag to the newly built image, run [Release: Publish Docker Image](../promote-docker-image/) manually.\n\n### Build Companion\n\nSee this [Overview](../companion-release-overview/). In short:\n\n1. Run [Release: Build Companion Artifact](../build-companion-release/).\n   - The workflow:\n      - Creates and publishes a [Companion release](https://github.com/sambee-app/sambee-companion/releases)\n      - Moves the `test` tag to it.\n      - Adds the `X.Y.Z` version tag.\n\n### Publish a Build\n\nTo publish a candidate build after testing and validation, complete the following steps.\n\n1. Run `Release: Create Public Sambee Release`. Specify:\n   - the validated canonical build version.\n   - the intended scope: `docker`, `companion`, or `both`.\n1. The workflow creates or verifies a draft release in the Sambee GitHub repo.\n1. Review and edit the draft release's changelog, then publish it manually.\n\nIf you selected `docker` or `both`:\n\n- Publishing the reviewed draft triggers [Release: Publish Docker Image](../promote-docker-image/) through the GitHub Release event.\n   - The workflow tags the image built earlier as `beta` (if not ahead) and `stable`, and adds a `X.Y` version tag.\n\nIf you selected `companion` or `both`:\n\n1. Run [Release: Promote Companion Release](../promote-companion-release/).\n   - The workflow promotes the release to the `beta`, and/or `stable` update channels and updates the Sambee download-metadata feed.\n"}, "page_contents": {"0.8": "+++\ntitle = \"Release Overview\"\n+++\n\n## Preparation\n\n1. Update the product **version** ([details](../product-versioning/)). Ensure it's at the version you want to release.\n\n## Build and Test the Docker Image\n\nSee [Overview](../docker-release-overview/).\n\n1. Run the CI workflow [Release: Create Docker Image](../build-docker-image/) to **build** the Docker image and move the `test` tag to it.\n   - Don't override the product version in the CI workflow.\n1. **Test** the newly built image (pull it via the `test` tag).\n\n## Documentation\n\n1. Review the **homepage** content and update it where necessary.\n1. **Docs:**\n   - Verify [Supported File Formats](../../../user-guide/reference/supported-file-formats/) and update as necessary.\n   - Finalize the target release's [What's New](/release-info/news-and-changes/whats-new/) page.\n   - Mark the target version as current in `website/data/docs-versions.toml`.\n   - Run the VS Code task **Website: Refresh Docs Derived Artifacts**.\n   - Review the Docs Structure Report this creates in `/workspace/website-meta/docs-reports/docs-structure-report.html`.\n1. Git merge all changes.\n\n## Publish the Docker Image\n\nSee [Overview](../docker-release-overview/).\n\n1. Create a Git tag on the commit the tested image was built from.\n1. Publish a GitHub release from that tag.\n   - Release publication triggers [Release: Publish Docker Image](../promote-docker-image/), which tags the image built earlier as `beta` (prereleases) or `stable` and adds version tags for stable releases.\n\n## Publish the Companion\n\nSee [Overview](../companion-release-overview/)\n\n1. Run [Release: Build Companion Artifact](../build-companion-release/) to build Companion for the target platforms.\n   - Publish the Companion GitHub Release created by the workflow.\n1. Run [Release: Promote Companion Release](../promote-companion-release/) to promote the release to the `test`, `beta`, and/or `stable` update channels and to update the Sambee download-metadata feed.\n", "0.9": "+++\ntitle = \"Release Overview\"\n+++\n\n## Principles\n\n- The version number source of truth is the `VERSION` file in the repository.\n- Every built artifact gets a unique version number.\n- Each version is built only once.\n- Releases happen without rebuilds but by applying tags to existing builds (Docker image) or updating channel pointers (Companion app).\n\n## Process Overview for Test and Preview Candidates\n\n1. Update `VERSION` to the next plain numeric `X.Y.Z` build sequence ([details](../product-versioning/)).\n   - Run `./scripts/sync-version`.\n   - Commit the synchronized metadata on `main`.\n1. Build the affected component (see below for details).\n   - Build workflows reserve the current `VERSION` by adding a Git tag when building from the latest commit.\n   - Alternatively, select an existing `build-vX.Y.Z` Git tag to build from.\n1. Test the resulting build.\n   - Docker: Through the `test` tag.\n   - Companion: Through the Companion draft release assets. Promote them to the Companion `test` feed as needed.\n1. Repeat the loop with a new `Z` value when a new candidate is required. Never rebuild or replace a published artifact under the same version.\n\nNotes:\n\n- Docker and Companion candidates may be built independently.\n\n## Component Build \u0026 Release Process\n\n### Update Documentation\n\n1. Review the homepage content and update it where necessary.\n1. Docs:\n   - Verify [Supported File Formats](../../../user-guide/reference/supported-file-formats/) and update as necessary.\n   - Finalize the target release's [What's New](/release-info/news-and-changes/whats-new/) page.\n   - Mark the target version as current in `website/data/docs-versions.toml`.\n   - Run the VS Code task `Website: Refresh Docs Derived Artifacts`.\n   - Review the Docs Structure Report this creates in `/workspace/website-meta/docs-reports/docs-structure-report.html`.\n1. Git merge all changes.\n\n### Build Docker Image\n\nSee this [Overview](../docker-release-overview/). In short:\n\n1. Run [Release: Create Docker Image](../build-docker-image/)\n   - The workflow:\n      - Builds the [Docker image](https://github.com/helgeklein/sambee/pkgs/container/sambee/versions).\n      - Moves the `test` tag to it.\n      - Adds the `X.Y.Z` version tag.\n1. To also move the `beta` tag to the newly built image, run [Release: Publish Docker Image](../promote-docker-image/) manually.\n\n### Build Companion\n\nSee this [Overview](../companion-release-overview/). In short:\n\n1. Run [Release: Build Companion Artifact](../build-companion-release/).\n   - The workflow creates a draft release in the [Companion GitHub repo](https://github.com/helgeklein/sambee-companion/releases).\n   - Publish it.\n\n### Publish a Build\n\nTo publish a candidate build after testing and validation, complete the following steps.\n\n1. Run `Release: Create Public Sambee Release`. Specify:\n   - the validated canonical build version.\n   - the intended scope: `docker`, `companion`, or `both`.\n1. The workflow creates or verifies a draft release in the Sambee GitHub repo.\n1. Review and edit the draft release's changelog, then publish it manually.\n\nIf you selected `docker` or `both`:\n\n- Publishing the reviewed draft triggers [Release: Publish Docker Image](../promote-docker-image/) through the GitHub Release event.\n   - The workflow tags the image built earlier as `beta` (if not ahead) and `stable`, and adds `X.Y` a version tag.\n\nIf you selected `companion` or `both`:\n\n1. Run [Release: Promote Companion Release](../promote-companion-release/).\n   - The workflow promotes the release to the `test`, `beta`, and/or `stable` update channels and updates the Sambee download-metadata feed.\n", "1.0": "+++\ntitle = \"Release Overview\"\n+++\n\n## Principles\n\n- The version number source of truth is the `VERSION` file in the repository.\n- Every built artifact gets a unique version number.\n- Each version is built only once.\n- Releases happen without rebuilds but by applying tags to existing builds (Docker image) or updating channel pointers (Companion app).\n\n## Process Overview for Test and Preview Candidates\n\n1. Update `VERSION` to the next plain numeric `X.Y.Z` build sequence ([details](../product-versioning/)).\n   - Run `./scripts/sync-version`.\n   - Commit the synchronized metadata on `main`.\n1. Build the affected component (see below for details).\n   - Build workflows reserve the current `VERSION` by adding a Git tag when building from the latest commit.\n   - Alternatively, select an existing `build-vX.Y.Z` Git tag to build from.\n1. Test the resulting build.\n   - Docker: Through the `test` tag.\n   - Companion: Through the Companion draft release assets. Promote them to the Companion `test` feed as needed.\n1. Repeat the loop with a new `Z` value when a new candidate is required. Never rebuild or replace a published artifact under the same version.\n\nNotes:\n\n- Docker and Companion candidates may be built independently.\n\n## Release Process \u0026 Checklist\n\n### Update Website\n\n1. Review the homepage content and update it where necessary.\n\n### Update Documentation\n\n1. Verify [Supported File Formats](../../../user-guide/reference/supported-file-formats/) and update as necessary.\n1. Finalize the target release's [What's New](/release-info/news-and-changes/whats-new/) page.\n1. Mark the target version as current in `website/data/docs-versions.toml`:\n   - Update the top-level `current` key, e.g.: `current = \"1.0\"`\n   - Update the `[[versions]]` sections of the previous and the new current version\n1. Run the VS Code task `Website: Refresh Docs Derived Artifacts`.\n1. Review the Docs Structure Report this creates in `/workspace/website-meta/docs-reports/docs-structure-report.html`.\n\nGit merge all changes.\n\n### Build Docker Image\n\nSee this [Overview](../docker-release-overview/). In short:\n\n1. Run [Release: Create Docker Image](../build-docker-image/)\n   - The workflow:\n      - Builds the [Docker image](https://github.com/helgeklein/sambee/pkgs/container/sambee/versions).\n      - Moves the `test` tag to it.\n      - Adds the `X.Y.Z` version tag.\n1. To also move the `beta` tag to the newly built image, run [Release: Publish Docker Image](../promote-docker-image/) manually.\n\n### Build Companion\n\nSee this [Overview](../companion-release-overview/). In short:\n\n1. Run [Release: Build Companion Artifact](../build-companion-release/).\n   - The workflow:\n      - Creates and publishes a [Companion release](https://github.com/helgeklein/sambee-companion/releases)\n      - Moves the `test` tag to it.\n      - Adds the `X.Y.Z` version tag.\n\n### Publish a Build\n\nTo publish a candidate build after testing and validation, complete the following steps.\n\n1. Run `Release: Create Public Sambee Release`. Specify:\n   - the validated canonical build version.\n   - the intended scope: `docker`, `companion`, or `both`.\n1. The workflow creates or verifies a draft release in the Sambee GitHub repo.\n1. Review and edit the draft release's changelog, then publish it manually.\n\nIf you selected `docker` or `both`:\n\n- Publishing the reviewed draft triggers [Release: Publish Docker Image](../promote-docker-image/) through the GitHub Release event.\n   - The workflow tags the image built earlier as `beta` (if not ahead) and `stable`, and adds a `X.Y` version tag.\n\nIf you selected `companion` or `both`:\n\n1. Run [Release: Promote Companion Release](../promote-companion-release/).\n   - The workflow promotes the release to the `beta`, and/or `stable` update channels and updates the Sambee download-metadata feed.\n", "2.0": "+++\ntitle = \"Release Overview\"\n+++\n\n## Principles\n\n- The version number source of truth is the `VERSION` file in the repository.\n- Every built artifact gets a unique version number.\n- Each version is built only once.\n- Releases happen without rebuilds but by applying tags to existing builds (Docker image) or updating channel pointers (Companion app).\n\n## Process Overview for Test and Preview Candidates\n\n1. Update `VERSION` to the next plain numeric `X.Y.Z` build sequence ([details](../product-versioning/)).\n   - Run `./scripts/sync-version`.\n   - Commit the synchronized metadata on `main`.\n1. Build the affected component (see below for details).\n   - Build workflows reserve the current `VERSION` by adding a Git tag when building from the latest commit.\n   - Alternatively, select an existing `build-vX.Y.Z` Git tag to build from.\n1. Test the resulting build.\n   - Docker: Through the `test` tag.\n   - Companion: Through the Companion draft release assets. Promote them to the Companion `test` feed as needed.\n1. Repeat the loop with a new `Z` value when a new candidate is required. Never rebuild or replace a published artifact under the same version.\n\nNotes:\n\n- Docker and Companion candidates may be built independently.\n\n## Release Process \u0026 Checklist\n\n### Update Website\n\n1. Review the homepage content and update it where necessary.\n\n### Update Documentation\n\n1. Verify [Supported File Formats](../../../user-guide/reference/supported-file-formats/) and update as necessary.\n1. Finalize the target release's [What's New](/release-info/news-and-changes/whats-new/) page.\n1. Mark the target version as current in `website/data/docs-versions.toml`:\n   - Update the top-level `current` key, e.g.: `current = \"1.0\"`\n   - Update the `[[versions]]` sections of the previous and the new current version\n1. Run the VS Code task `Website: Refresh Docs Derived Artifacts`.\n1. Review the Docs Structure Report this creates in `/workspace/website-meta/docs-reports/docs-structure-report.html`.\n\nGit merge all changes.\n\n### Build Docker Image\n\nSee this [Overview](../docker-release-overview/). In short:\n\n1. Run [Release: Create Docker Image](../build-docker-image/)\n   - The workflow:\n      - Builds the [Docker image](https://github.com/sambee-app/sambee/pkgs/container/sambee/versions).\n      - Moves the `test` tag to it.\n      - Adds the `X.Y.Z` version tag.\n1. To also move the `beta` tag to the newly built image, run [Release: Publish Docker Image](../promote-docker-image/) manually.\n\n### Build Companion\n\nSee this [Overview](../companion-release-overview/). In short:\n\n1. Run [Release: Build Companion Artifact](../build-companion-release/).\n   - The workflow:\n      - Creates and publishes a [Companion release](https://github.com/sambee-app/sambee-companion/releases)\n      - Moves the `test` tag to it.\n      - Adds the `X.Y.Z` version tag.\n\n### Publish a Build\n\nTo publish a candidate build after testing and validation, complete the following steps.\n\n1. Run `Release: Create Public Sambee Release`. Specify:\n   - the validated canonical build version.\n   - the intended scope: `docker`, `companion`, or `both`.\n1. The workflow creates or verifies a draft release in the Sambee GitHub repo.\n1. Review and edit the draft release's changelog, then publish it manually.\n\nIf you selected `docker` or `both`:\n\n- Publishing the reviewed draft triggers [Release: Publish Docker Image](../promote-docker-image/) through the GitHub Release event.\n   - The workflow tags the image built earlier as `beta` (if not ahead) and `stable`, and adds a `X.Y` version tag.\n\nIf you selected `companion` or `both`:\n\n1. Run [Release: Promote Companion Release](../promote-companion-release/).\n   - The workflow promotes the release to the `beta`, and/or `stable` update channels and updates the Sambee download-metadata feed.\n"}, "flags": {"has_branched": true, "has_inherited": false, "has_structural": false, "has_invalid": false}}, {"id": "page:developer-guide/release-and-versioning/companion-release-cleanup", "parent_id": "section:developer-guide/release-and-versioning", "depth": 2, "kind": "page", "label": "companion-release-cleanup", "title": "Companion Release Cleanup", "path": "developer-guide/release-and-versioning/companion-release-cleanup", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "missing"}, "1.0": {"state": "authored"}, "2.0": {"state": "branched", "source_version": "1.0", "diff_added": 1, "diff_removed": 2}}, "content_versions": {"1.0": "+++\ntitle = \"Companion Release Cleanup\"\n+++\n\nCompanion cleanup removes obsolete GitHub Releases after a successful feed promotion. It also runs on a schedule and can be started manually as `Maintenance: Clean Up Companion Releases`.\n\n## Retention Rules\n\nCleanup keeps:\n\n- Every published, non-prerelease release referenced by a `test`, `beta`, `stable`, or Sambee feed marker.\n- The latest published, non-prerelease `companion-vX.Y.Z` release in every `X.Y` series.\n\nFor example, it keeps `companion-v8.0.13` and deletes `companion-v8.0.12` unless a feed still points to the older release.\n\nCleanup deletes every other GitHub Release, including obsolete drafts, GitHub prereleases, and noncanonical legacy releases. It does not delete Git tags.\n\n## Safety Checks\n\nBefore deleting anything, cleanup reads the committed feed files in `sambee-companion` and validates every referenced release asset.\n\nFor each present marker, it requires:\n\n- A plain numeric `X.Y.Z` version.\n- Asset URLs for `helgeklein/sambee-companion` release downloads.\n- One canonical `companion-vX.Y.Z` release tag for every asset in the marker.\n- A marker version that matches that tag.\n- A published, non-prerelease release containing every referenced asset.\n\nMissing marker files represent an unpromoted channel and do not protect a release. A malformed present marker, inconsistent asset URL, missing asset, ambiguous release, or GitHub API failure stops cleanup before deletion.\n\nThe `companion-release-publication` concurrency group prevents cleanup from overlapping an active provisional release upload.\n\n## When It Runs\n\nCleanup runs after automatic `test` promotion from `Release: Build Companion Artifact` and after successful manual `Release: Promote Companion Release` runs. Use the maintenance workflow when you need an additional reconciliation pass.\n\n", "2.0": "+++\ntitle = \"Companion Release Cleanup\"\n+++\n\nCompanion cleanup removes obsolete GitHub Releases after a successful feed promotion. It also runs on a schedule and can be started manually as `Maintenance: Clean Up Companion Releases`.\n\n## Retention Rules\n\nCleanup keeps:\n\n- Every published, non-prerelease release referenced by a `test`, `beta`, `stable`, or Sambee feed marker.\n- The latest published, non-prerelease `companion-vX.Y.Z` release in every `X.Y` series.\n\nFor example, it keeps `companion-v8.0.13` and deletes `companion-v8.0.12` unless a feed still points to the older release.\n\nCleanup deletes every other GitHub Release, including obsolete drafts, GitHub prereleases, and noncanonical legacy releases. It does not delete Git tags.\n\n## Safety Checks\n\nBefore deleting anything, cleanup reads the committed feed files in `sambee-companion` and validates every referenced release asset.\n\nFor each present marker, it requires:\n\n- A plain numeric `X.Y.Z` version.\n- Asset URLs for `sambee-app/sambee-companion` release downloads.\n- One canonical `companion-vX.Y.Z` release tag for every asset in the marker.\n- A marker version that matches that tag.\n- A published, non-prerelease release containing every referenced asset.\n\nMissing marker files represent an unpromoted channel and do not protect a release. A malformed present marker, inconsistent asset URL, missing asset, ambiguous release, or GitHub API failure stops cleanup before deletion.\n\nThe `companion-release-publication` concurrency group prevents cleanup from overlapping an active provisional release upload.\n\n## When It Runs\n\nCleanup runs after automatic `test` promotion from `Release: Build Companion Artifact` and after successful manual `Release: Promote Companion Release` runs. Use the maintenance workflow when you need an additional reconciliation pass.\n"}, "page_contents": {"1.0": "+++\ntitle = \"Companion Release Cleanup\"\n+++\n\nCompanion cleanup removes obsolete GitHub Releases after a successful feed promotion. It also runs on a schedule and can be started manually as `Maintenance: Clean Up Companion Releases`.\n\n## Retention Rules\n\nCleanup keeps:\n\n- Every published, non-prerelease release referenced by a `test`, `beta`, `stable`, or Sambee feed marker.\n- The latest published, non-prerelease `companion-vX.Y.Z` release in every `X.Y` series.\n\nFor example, it keeps `companion-v8.0.13` and deletes `companion-v8.0.12` unless a feed still points to the older release.\n\nCleanup deletes every other GitHub Release, including obsolete drafts, GitHub prereleases, and noncanonical legacy releases. It does not delete Git tags.\n\n## Safety Checks\n\nBefore deleting anything, cleanup reads the committed feed files in `sambee-companion` and validates every referenced release asset.\n\nFor each present marker, it requires:\n\n- A plain numeric `X.Y.Z` version.\n- Asset URLs for `helgeklein/sambee-companion` release downloads.\n- One canonical `companion-vX.Y.Z` release tag for every asset in the marker.\n- A marker version that matches that tag.\n- A published, non-prerelease release containing every referenced asset.\n\nMissing marker files represent an unpromoted channel and do not protect a release. A malformed present marker, inconsistent asset URL, missing asset, ambiguous release, or GitHub API failure stops cleanup before deletion.\n\nThe `companion-release-publication` concurrency group prevents cleanup from overlapping an active provisional release upload.\n\n## When It Runs\n\nCleanup runs after automatic `test` promotion from `Release: Build Companion Artifact` and after successful manual `Release: Promote Companion Release` runs. Use the maintenance workflow when you need an additional reconciliation pass.\n\n", "2.0": "+++\ntitle = \"Companion Release Cleanup\"\n+++\n\nCompanion cleanup removes obsolete GitHub Releases after a successful feed promotion. It also runs on a schedule and can be started manually as `Maintenance: Clean Up Companion Releases`.\n\n## Retention Rules\n\nCleanup keeps:\n\n- Every published, non-prerelease release referenced by a `test`, `beta`, `stable`, or Sambee feed marker.\n- The latest published, non-prerelease `companion-vX.Y.Z` release in every `X.Y` series.\n\nFor example, it keeps `companion-v8.0.13` and deletes `companion-v8.0.12` unless a feed still points to the older release.\n\nCleanup deletes every other GitHub Release, including obsolete drafts, GitHub prereleases, and noncanonical legacy releases. It does not delete Git tags.\n\n## Safety Checks\n\nBefore deleting anything, cleanup reads the committed feed files in `sambee-companion` and validates every referenced release asset.\n\nFor each present marker, it requires:\n\n- A plain numeric `X.Y.Z` version.\n- Asset URLs for `sambee-app/sambee-companion` release downloads.\n- One canonical `companion-vX.Y.Z` release tag for every asset in the marker.\n- A marker version that matches that tag.\n- A published, non-prerelease release containing every referenced asset.\n\nMissing marker files represent an unpromoted channel and do not protect a release. A malformed present marker, inconsistent asset URL, missing asset, ambiguous release, or GitHub API failure stops cleanup before deletion.\n\nThe `companion-release-publication` concurrency group prevents cleanup from overlapping an active provisional release upload.\n\n## When It Runs\n\nCleanup runs after automatic `test` promotion from `Release: Build Companion Artifact` and after successful manual `Release: Promote Companion Release` runs. Use the maintenance workflow when you need an additional reconciliation pass.\n"}, "flags": {"has_branched": true, "has_inherited": false, "has_structural": false, "has_invalid": false}}, {"id": "book:website-dev-guide", "parent_id": null, "depth": 0, "kind": "book", "label": "website-dev-guide", "title": "Website Dev Guide", "path": "website-dev-guide", "has_children": true, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "branched", "source_version": "0.7", "diff_added": 0, "diff_removed": 0}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "inherited", "source_version": "0.9"}}, "content_versions": {"0.7": "+++\ntitle = \"Website Dev Guide\"\n+++\n\nUse this guide to edit and publish website and docs content, understand how the Hugo site and versioned docs system work, use the docs editor safely, and change shared website systems such as media and typography.\n\n## Start Here if You Want To\n\n- Add or revise published website or docs content.\n- Understand the website build pipeline and versioned docs model.\n- Update docs navigation, versions, or inheritance behavior safely.\n- Use the docs editor for structural docs changes.\n- Change shared website theme systems such as media handling or typography.\n- Prepare or maintain the website publishing environment.\n\n## In This Guide\n\n- [Docs Platform](./docs-platform/website-and-docs-architecture-overview/): Understand what lives in `website/`, how docs routing works, and how versioned docs content is resolved.\n- [Authoring and Tooling](./authoring-and-tooling/docs-authoring-workflow/): Write published content, update navigation, and use the docs editor safely.\n- [Site Systems](./site-systems/media-publishing-workflow/): Preserve the media and typography contracts used by the public site.\n- [Setup and Operations](./setup-and-operations/set-up-cloudflare-pages-publishing/): Configure publishing infrastructure such as Cloudflare Pages and understand what the current website workflow actually deploys.\n\n## Use the Right Guide\n\n- Use this Website Dev Guide for website editing, docs authoring, Hugo theme work, docs tooling, shared website system changes, and website publishing infrastructure.\n- Use the [Developer Guide](../developer-guide/) when the work is primarily on the backend, frontend app, companion, or cross-application runtime behavior.\n- Use the [Admin Guide](../admin-guide/) when the next step is deployment, configuration, operations, or troubleshooting a running service.\n- Use the [User Guide](../user-guide/) when the next step belongs to someone using Sambee in normal product workflows.\n", "0.8": "+++\ntitle = \"Website Dev Guide\"\n+++\n\nUse this guide to edit and publish website and docs content, understand how the Hugo site and versioned docs system work, use the docs editor safely, and change shared website systems such as media and typography.\n\n## Start Here if You Want To\n\n- Add or revise published website or docs content.\n- Understand the website build pipeline and versioned docs model.\n- Update docs navigation, versions, or inheritance behavior safely.\n- Use the docs editor for structural docs changes.\n- Change shared website theme systems such as media handling or typography.\n- Prepare or maintain the website publishing environment.\n\n## In This Guide\n\n- [Docs Platform](./docs-platform/website-and-docs-architecture-overview/): Understand what lives in `website/`, how docs routing works, and how versioned docs content is resolved.\n- [Authoring and Tooling](./authoring-and-tooling/docs-authoring-workflow/): Write published content, update navigation, and use the docs editor safely.\n- [Site Systems](./site-systems/media-publishing-workflow/): Preserve the media and typography contracts used by the public site.\n- [Setup and Operations](./setup-and-operations/set-up-cloudflare-pages-publishing/): Configure publishing infrastructure such as Cloudflare Pages and understand what the current website workflow actually deploys.\n\n## Use the Right Guide\n\n- Use this Website Dev Guide for website editing, docs authoring, Hugo theme work, docs tooling, shared website system changes, and website publishing infrastructure.\n- Use the [Developer Guide](../developer-guide/) when the work is primarily on the backend, frontend app, companion, or cross-application runtime behavior.\n- Use the [Admin Guide](../admin-guide/) when the next step is deployment, configuration, operations, or troubleshooting a running service.\n- Use the [User Guide](../user-guide/) when the next step belongs to someone using Sambee in normal product workflows.\n", "0.9": "+++\ntitle = \"Website Dev Guide\"\n+++\n\nUse this guide to edit and publish website and docs content, understand how the Hugo site and versioned docs system work, use the docs editor safely, and change shared website systems such as media and typography.\n\n## Start Here if You Want To\n\n- Add or revise published website or docs content.\n- Understand the website build pipeline and versioned docs model.\n- Update docs navigation, versions, or inheritance behavior safely.\n- Use the docs editor for structural docs changes.\n- Change shared website theme systems such as media handling or typography.\n- Prepare or maintain the website publishing environment.\n\n## In This Guide\n\n- [Docs Platform](./docs-platform/website-and-docs-architecture-overview/): Understand what lives in `website/`, how docs routing works, and how versioned docs content is resolved.\n- [Authoring and Tooling](./authoring-and-tooling/docs-authoring-workflow/): Write published content, update navigation, and use the docs editor safely.\n- [Site Systems](./site-systems/media-publishing-workflow/): Preserve the media and typography contracts used by the public site.\n- [Setup and Operations](./setup-and-operations/set-up-cloudflare-pages-publishing/): Configure publishing infrastructure such as Cloudflare Pages and understand what the current website workflow actually deploys.\n\n## Use the Right Guide\n\n- Use this Website Dev Guide for website editing, docs authoring, Hugo theme work, docs tooling, shared website system changes, and website publishing infrastructure.\n- Use the [Developer Guide](../developer-guide/) when the work is primarily on the backend, frontend app, companion, or cross-application runtime behavior.\n- Use the [Admin Guide](../admin-guide/) when the next step is deployment, configuration, operations, or troubleshooting a running service.\n- Use the [User Guide](../user-guide/) when the next step belongs to someone using Sambee in normal product workflows.\n", "1.0": "+++\ntitle = \"Website Dev Guide\"\n+++\n\nUse this guide to edit and publish website and docs content, understand how the Hugo site and versioned docs system work, use the docs editor safely, and change shared website systems such as media and typography.\n\n## Start Here if You Want To\n\n- Add or revise published website or docs content.\n- Understand the website build pipeline and versioned docs model.\n- Update docs navigation, versions, or inheritance behavior safely.\n- Use the docs editor for structural docs changes.\n- Change shared website theme systems such as media handling or typography.\n- Prepare or maintain the website publishing environment.\n\n## In This Guide\n\n- [Docs Platform](./docs-platform/website-and-docs-architecture-overview/): Understand what lives in `website/`, how docs routing works, and how versioned docs content is resolved.\n- [Authoring and Tooling](./authoring-and-tooling/docs-authoring-workflow/): Write published content, update navigation, and use the docs editor safely.\n- [Site Systems](./site-systems/media-publishing-workflow/): Preserve the media and typography contracts used by the public site.\n- [Setup and Operations](./setup-and-operations/set-up-cloudflare-pages-publishing/): Configure publishing infrastructure such as Cloudflare Pages and understand what the current website workflow actually deploys.\n\n## Use the Right Guide\n\n- Use this Website Dev Guide for website editing, docs authoring, Hugo theme work, docs tooling, shared website system changes, and website publishing infrastructure.\n- Use the [Developer Guide](../developer-guide/) when the work is primarily on the backend, frontend app, companion, or cross-application runtime behavior.\n- Use the [Admin Guide](../admin-guide/) when the next step is deployment, configuration, operations, or troubleshooting a running service.\n- Use the [User Guide](../user-guide/) when the next step belongs to someone using Sambee in normal product workflows.\n", "2.0": "+++\ntitle = \"Website Dev Guide\"\n+++\n\nUse this guide to edit and publish website and docs content, understand how the Hugo site and versioned docs system work, use the docs editor safely, and change shared website systems such as media and typography.\n\n## Start Here if You Want To\n\n- Add or revise published website or docs content.\n- Understand the website build pipeline and versioned docs model.\n- Update docs navigation, versions, or inheritance behavior safely.\n- Use the docs editor for structural docs changes.\n- Change shared website theme systems such as media handling or typography.\n- Prepare or maintain the website publishing environment.\n\n## In This Guide\n\n- [Docs Platform](./docs-platform/website-and-docs-architecture-overview/): Understand what lives in `website/`, how docs routing works, and how versioned docs content is resolved.\n- [Authoring and Tooling](./authoring-and-tooling/docs-authoring-workflow/): Write published content, update navigation, and use the docs editor safely.\n- [Site Systems](./site-systems/media-publishing-workflow/): Preserve the media and typography contracts used by the public site.\n- [Setup and Operations](./setup-and-operations/set-up-cloudflare-pages-publishing/): Configure publishing infrastructure such as Cloudflare Pages and understand what the current website workflow actually deploys.\n\n## Use the Right Guide\n\n- Use this Website Dev Guide for website editing, docs authoring, Hugo theme work, docs tooling, shared website system changes, and website publishing infrastructure.\n- Use the [Developer Guide](../developer-guide/) when the work is primarily on the backend, frontend app, companion, or cross-application runtime behavior.\n- Use the [Admin Guide](../admin-guide/) when the next step is deployment, configuration, operations, or troubleshooting a running service.\n- Use the [User Guide](../user-guide/) when the next step belongs to someone using Sambee in normal product workflows.\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:website-dev-guide/docs-platform", "parent_id": "book:website-dev-guide", "depth": 1, "kind": "section", "label": "docs-platform", "title": "Docs Platform", "path": "website-dev-guide/docs-platform", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:website-dev-guide/docs-platform/website-and-docs-architecture-overview", "parent_id": "section:website-dev-guide/docs-platform", "depth": 2, "kind": "page", "label": "website-and-docs-architecture-overview", "title": "Website And Docs Architecture Overview", "path": "website-dev-guide/docs-platform/website-and-docs-architecture-overview", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Website and Docs Architecture Overview\"\n+++\n\n## What Lives In `website/`\n\nThe public site lives under `website/`. The important areas are:\n\n```text\nwebsite/\n  content/\n    docs/\n  data/\n    docs-nav/\n    docs-versions.toml\n  scripts/\n  themes/sambee/\n  assets/\n  static/\n```\n\nIn practice:\n\n- `content/` holds the authored website pages and docs pages.\n- `content/docs/` holds the published versioned docs books.\n- `data/docs-versions.toml` declares the canonical docs version order and the current version.\n- `data/docs-nav/\u003cversion\u003e.toml` declares book, section, and page ordering for one version.\n- `scripts/` holds build helpers, docs validation, docs materialization, and docs editor automation.\n- `themes/sambee/` holds the Hugo layouts, partials, CSS, and JS for the public site.\n- `assets/` and `static/` hold source media, generated media, and static files.\n\n## How Docs Routing Works\n\nDocs content is versioned in the content tree:\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe current docs version also publishes stable unversioned routes:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nArchived or explicit versioned routes remain available at:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/...`\n\nThe routing rules, inheritance markers, and stable-current behavior are covered in more detail in [Docs Content Model, Navigation, and Inheritance](../docs-content-model-navigation-and-inheritance/).\n\n## Build and Preview Pipeline\n\nThe website build is more than a plain Hugo render.\n\nThe normal production-style build is:\n\n```bash\ncd website\nnpm run build\n```\n\nThat command runs:\n\n1. theme generation\n2. docs validation\n3. inherited-doc materialization\n4. Hugo site build\n5. homepage CTA validation\n\nFor local development, use:\n\n```bash\n./scripts/start-website\n```\n\nOr run the website dev workflow directly:\n\n```bash\ncd website\nnpm run dev\n```\n\nThat dev workflow also keeps search indexing and WebP generation in sync while you iterate. Its transient output is written to `website/public-dev/`, so production-style builds can safely continue to use `website/public/` without disrupting the running preview.\n", "0.8": "+++\ntitle = \"Website and Docs Architecture Overview\"\n+++\n\n## What Lives In `website/`\n\nThe public site lives under `website/`. The important areas are:\n\n```text\nwebsite/\n  content/\n    docs/\n  data/\n    docs-nav/\n    docs-versions.toml\n  scripts/\n  themes/sambee/\n  assets/\n  static/\n```\n\nIn practice:\n\n- `content/` holds the authored website pages and docs pages.\n- `content/docs/` holds the published versioned docs books.\n- `data/docs-versions.toml` declares the canonical docs version order and the current version.\n- `data/docs-nav/\u003cversion\u003e.toml` declares book, section, and page ordering for one version.\n- `scripts/` holds build helpers, docs validation, docs materialization, and docs editor automation.\n- `themes/sambee/` holds the Hugo layouts, partials, CSS, and JS for the public site.\n- `assets/` and `static/` hold source media, generated media, and static files.\n\n## How Docs Routing Works\n\nDocs content is versioned in the content tree:\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe current docs version also publishes stable unversioned routes:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nArchived or explicit versioned routes remain available at:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/...`\n\nThe routing rules, inheritance markers, and stable-current behavior are covered in more detail in [Docs Content Model, Navigation, and Inheritance](../docs-content-model-navigation-and-inheritance/).\n\n## Build and Preview Pipeline\n\nThe website build is more than a plain Hugo render.\n\nThe normal production-style build is:\n\n```bash\ncd website\nnpm run build\n```\n\nThat command runs:\n\n1. theme generation\n2. docs validation\n3. inherited-doc materialization\n4. Hugo site build\n5. homepage CTA validation\n\nFor local development, use:\n\n```bash\n./scripts/start-website\n```\n\nOr run the website dev workflow directly:\n\n```bash\ncd website\nnpm run dev\n```\n\nThat dev workflow also keeps search indexing and WebP generation in sync while you iterate. Its transient output is written to `website/public-dev/`, so production-style builds can safely continue to use `website/public/` without disrupting the running preview.\n", "0.9": "+++\ntitle = \"Website and Docs Architecture Overview\"\n+++\n\n## What Lives In `website/`\n\nThe public site lives under `website/`. The important areas are:\n\n```text\nwebsite/\n  content/\n    docs/\n  data/\n    docs-nav/\n    docs-versions.toml\n  scripts/\n  themes/sambee/\n  assets/\n  static/\n```\n\nIn practice:\n\n- `content/` holds the authored website pages and docs pages.\n- `content/docs/` holds the published versioned docs books.\n- `data/docs-versions.toml` declares the canonical docs version order and the current version.\n- `data/docs-nav/\u003cversion\u003e.toml` declares book, section, and page ordering for one version.\n- `scripts/` holds build helpers, docs validation, docs materialization, and docs editor automation.\n- `themes/sambee/` holds the Hugo layouts, partials, CSS, and JS for the public site.\n- `assets/` and `static/` hold source media, generated media, and static files.\n\n## How Docs Routing Works\n\nDocs content is versioned in the content tree:\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe current docs version also publishes stable unversioned routes:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nArchived or explicit versioned routes remain available at:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/...`\n\nThe routing rules, inheritance markers, and stable-current behavior are covered in more detail in [Docs Content Model, Navigation, and Inheritance](../docs-content-model-navigation-and-inheritance/).\n\n## Build and Preview Pipeline\n\nThe website build is more than a plain Hugo render.\n\nThe normal production-style build is:\n\n```bash\ncd website\nnpm run build\n```\n\nThat command runs:\n\n1. theme generation\n2. docs validation\n3. inherited-doc materialization\n4. Hugo site build\n5. homepage CTA validation\n\nFor local development, use:\n\n```bash\n./scripts/start-website\n```\n\nOr run the website dev workflow directly:\n\n```bash\ncd website\nnpm run dev\n```\n\nThat dev workflow also keeps search indexing and WebP generation in sync while you iterate. Its transient output is written to `website/public-dev/`, so production-style builds can safely continue to use `website/public/` without disrupting the running preview.\n", "1.0": "+++\ntitle = \"Website and Docs Architecture Overview\"\n+++\n\n## What Lives In `website/`\n\nThe public site lives under `website/`. The important areas are:\n\n```text\nwebsite/\n  content/\n    docs/\n  data/\n    docs-nav/\n    docs-versions.toml\n  scripts/\n  themes/sambee/\n  assets/\n  static/\n```\n\nIn practice:\n\n- `content/` holds the authored website pages and docs pages.\n- `content/docs/` holds the published versioned docs books.\n- `data/docs-versions.toml` declares the canonical docs version order and the current version.\n- `data/docs-nav/\u003cversion\u003e.toml` declares book, section, and page ordering for one version.\n- `scripts/` holds build helpers, docs validation, docs materialization, and docs editor automation.\n- `themes/sambee/` holds the Hugo layouts, partials, CSS, and JS for the public site.\n- `assets/` and `static/` hold source media, generated media, and static files.\n\n## How Docs Routing Works\n\nDocs content is versioned in the content tree:\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe current docs version also publishes stable unversioned routes:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nArchived or explicit versioned routes remain available at:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/...`\n\nThe routing rules, inheritance markers, and stable-current behavior are covered in more detail in [Docs Content Model, Navigation, and Inheritance](../docs-content-model-navigation-and-inheritance/).\n\n## Build and Preview Pipeline\n\nThe website build is more than a plain Hugo render.\n\nThe normal production-style build is:\n\n```bash\ncd website\nnpm run build\n```\n\nThat command runs:\n\n1. theme generation\n2. docs validation\n3. inherited-doc materialization\n4. Hugo site build\n5. homepage CTA validation\n\nFor local development, use:\n\n```bash\n./scripts/start-website\n```\n\nOr run the website dev workflow directly:\n\n```bash\ncd website\nnpm run dev\n```\n\nThat dev workflow also keeps search indexing and WebP generation in sync while you iterate. Its transient output is written to `website/public-dev/`, so production-style builds can safely continue to use `website/public/` without disrupting the running preview.\n", "2.0": "+++\ntitle = \"Website and Docs Architecture Overview\"\n+++\n\n## What Lives In `website/`\n\nThe public site lives under `website/`. The important areas are:\n\n```text\nwebsite/\n  content/\n    docs/\n  data/\n    docs-nav/\n    docs-versions.toml\n  scripts/\n  themes/sambee/\n  assets/\n  static/\n```\n\nIn practice:\n\n- `content/` holds the authored website pages and docs pages.\n- `content/docs/` holds the published versioned docs books.\n- `data/docs-versions.toml` declares the canonical docs version order and the current version.\n- `data/docs-nav/\u003cversion\u003e.toml` declares book, section, and page ordering for one version.\n- `scripts/` holds build helpers, docs validation, docs materialization, and docs editor automation.\n- `themes/sambee/` holds the Hugo layouts, partials, CSS, and JS for the public site.\n- `assets/` and `static/` hold source media, generated media, and static files.\n\n## How Docs Routing Works\n\nDocs content is versioned in the content tree:\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe current docs version also publishes stable unversioned routes:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nArchived or explicit versioned routes remain available at:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/...`\n\nThe routing rules, inheritance markers, and stable-current behavior are covered in more detail in [Docs Content Model, Navigation, and Inheritance](../docs-content-model-navigation-and-inheritance/).\n\n## Build and Preview Pipeline\n\nThe website build is more than a plain Hugo render.\n\nThe normal production-style build is:\n\n```bash\ncd website\nnpm run build\n```\n\nThat command runs:\n\n1. theme generation\n2. docs validation\n3. inherited-doc materialization\n4. Hugo site build\n5. homepage CTA validation\n\nFor local development, use:\n\n```bash\n./scripts/start-website\n```\n\nOr run the website dev workflow directly:\n\n```bash\ncd website\nnpm run dev\n```\n\nThat dev workflow also keeps search indexing and WebP generation in sync while you iterate. Its transient output is written to `website/public-dev/`, so production-style builds can safely continue to use `website/public/` without disrupting the running preview.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Website and Docs Architecture Overview\"\n+++\n\n## What Lives In `website/`\n\nThe public site lives under `website/`. The important areas are:\n\n```text\nwebsite/\n  content/\n    docs/\n  data/\n    docs-nav/\n    docs-versions.toml\n  scripts/\n  themes/sambee/\n  assets/\n  static/\n```\n\nIn practice:\n\n- `content/` holds the authored website pages and docs pages.\n- `content/docs/` holds the published versioned docs books.\n- `data/docs-versions.toml` declares the canonical docs version order and the current version.\n- `data/docs-nav/\u003cversion\u003e.toml` declares book, section, and page ordering for one version.\n- `scripts/` holds build helpers, docs validation, docs materialization, and docs editor automation.\n- `themes/sambee/` holds the Hugo layouts, partials, CSS, and JS for the public site.\n- `assets/` and `static/` hold source media, generated media, and static files.\n\n## How Docs Routing Works\n\nDocs content is versioned in the content tree:\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe current docs version also publishes stable unversioned routes:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nArchived or explicit versioned routes remain available at:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/...`\n\nThe routing rules, inheritance markers, and stable-current behavior are covered in more detail in [Docs Content Model, Navigation, and Inheritance](../docs-content-model-navigation-and-inheritance/).\n\n## Build and Preview Pipeline\n\nThe website build is more than a plain Hugo render.\n\nThe normal production-style build is:\n\n```bash\ncd website\nnpm run build\n```\n\nThat command runs:\n\n1. theme generation\n2. docs validation\n3. inherited-doc materialization\n4. Hugo site build\n5. homepage CTA validation\n\nFor local development, use:\n\n```bash\n./scripts/start-website\n```\n\nOr run the website dev workflow directly:\n\n```bash\ncd website\nnpm run dev\n```\n\nThat dev workflow also keeps search indexing and WebP generation in sync while you iterate. Its transient output is written to `website/public-dev/`, so production-style builds can safely continue to use `website/public/` without disrupting the running preview.\n", "0.8": "+++\ntitle = \"Website and Docs Architecture Overview\"\n+++\n\n## What Lives In `website/`\n\nThe public site lives under `website/`. The important areas are:\n\n```text\nwebsite/\n  content/\n    docs/\n  data/\n    docs-nav/\n    docs-versions.toml\n  scripts/\n  themes/sambee/\n  assets/\n  static/\n```\n\nIn practice:\n\n- `content/` holds the authored website pages and docs pages.\n- `content/docs/` holds the published versioned docs books.\n- `data/docs-versions.toml` declares the canonical docs version order and the current version.\n- `data/docs-nav/\u003cversion\u003e.toml` declares book, section, and page ordering for one version.\n- `scripts/` holds build helpers, docs validation, docs materialization, and docs editor automation.\n- `themes/sambee/` holds the Hugo layouts, partials, CSS, and JS for the public site.\n- `assets/` and `static/` hold source media, generated media, and static files.\n\n## How Docs Routing Works\n\nDocs content is versioned in the content tree:\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe current docs version also publishes stable unversioned routes:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nArchived or explicit versioned routes remain available at:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/...`\n\nThe routing rules, inheritance markers, and stable-current behavior are covered in more detail in [Docs Content Model, Navigation, and Inheritance](../docs-content-model-navigation-and-inheritance/).\n\n## Build and Preview Pipeline\n\nThe website build is more than a plain Hugo render.\n\nThe normal production-style build is:\n\n```bash\ncd website\nnpm run build\n```\n\nThat command runs:\n\n1. theme generation\n2. docs validation\n3. inherited-doc materialization\n4. Hugo site build\n5. homepage CTA validation\n\nFor local development, use:\n\n```bash\n./scripts/start-website\n```\n\nOr run the website dev workflow directly:\n\n```bash\ncd website\nnpm run dev\n```\n\nThat dev workflow also keeps search indexing and WebP generation in sync while you iterate. Its transient output is written to `website/public-dev/`, so production-style builds can safely continue to use `website/public/` without disrupting the running preview.\n", "0.9": "+++\ntitle = \"Website and Docs Architecture Overview\"\n+++\n\n## What Lives In `website/`\n\nThe public site lives under `website/`. The important areas are:\n\n```text\nwebsite/\n  content/\n    docs/\n  data/\n    docs-nav/\n    docs-versions.toml\n  scripts/\n  themes/sambee/\n  assets/\n  static/\n```\n\nIn practice:\n\n- `content/` holds the authored website pages and docs pages.\n- `content/docs/` holds the published versioned docs books.\n- `data/docs-versions.toml` declares the canonical docs version order and the current version.\n- `data/docs-nav/\u003cversion\u003e.toml` declares book, section, and page ordering for one version.\n- `scripts/` holds build helpers, docs validation, docs materialization, and docs editor automation.\n- `themes/sambee/` holds the Hugo layouts, partials, CSS, and JS for the public site.\n- `assets/` and `static/` hold source media, generated media, and static files.\n\n## How Docs Routing Works\n\nDocs content is versioned in the content tree:\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe current docs version also publishes stable unversioned routes:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nArchived or explicit versioned routes remain available at:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/...`\n\nThe routing rules, inheritance markers, and stable-current behavior are covered in more detail in [Docs Content Model, Navigation, and Inheritance](../docs-content-model-navigation-and-inheritance/).\n\n## Build and Preview Pipeline\n\nThe website build is more than a plain Hugo render.\n\nThe normal production-style build is:\n\n```bash\ncd website\nnpm run build\n```\n\nThat command runs:\n\n1. theme generation\n2. docs validation\n3. inherited-doc materialization\n4. Hugo site build\n5. homepage CTA validation\n\nFor local development, use:\n\n```bash\n./scripts/start-website\n```\n\nOr run the website dev workflow directly:\n\n```bash\ncd website\nnpm run dev\n```\n\nThat dev workflow also keeps search indexing and WebP generation in sync while you iterate. Its transient output is written to `website/public-dev/`, so production-style builds can safely continue to use `website/public/` without disrupting the running preview.\n", "1.0": "+++\ntitle = \"Website and Docs Architecture Overview\"\n+++\n\n## What Lives In `website/`\n\nThe public site lives under `website/`. The important areas are:\n\n```text\nwebsite/\n  content/\n    docs/\n  data/\n    docs-nav/\n    docs-versions.toml\n  scripts/\n  themes/sambee/\n  assets/\n  static/\n```\n\nIn practice:\n\n- `content/` holds the authored website pages and docs pages.\n- `content/docs/` holds the published versioned docs books.\n- `data/docs-versions.toml` declares the canonical docs version order and the current version.\n- `data/docs-nav/\u003cversion\u003e.toml` declares book, section, and page ordering for one version.\n- `scripts/` holds build helpers, docs validation, docs materialization, and docs editor automation.\n- `themes/sambee/` holds the Hugo layouts, partials, CSS, and JS for the public site.\n- `assets/` and `static/` hold source media, generated media, and static files.\n\n## How Docs Routing Works\n\nDocs content is versioned in the content tree:\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe current docs version also publishes stable unversioned routes:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nArchived or explicit versioned routes remain available at:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/...`\n\nThe routing rules, inheritance markers, and stable-current behavior are covered in more detail in [Docs Content Model, Navigation, and Inheritance](../docs-content-model-navigation-and-inheritance/).\n\n## Build and Preview Pipeline\n\nThe website build is more than a plain Hugo render.\n\nThe normal production-style build is:\n\n```bash\ncd website\nnpm run build\n```\n\nThat command runs:\n\n1. theme generation\n2. docs validation\n3. inherited-doc materialization\n4. Hugo site build\n5. homepage CTA validation\n\nFor local development, use:\n\n```bash\n./scripts/start-website\n```\n\nOr run the website dev workflow directly:\n\n```bash\ncd website\nnpm run dev\n```\n\nThat dev workflow also keeps search indexing and WebP generation in sync while you iterate. Its transient output is written to `website/public-dev/`, so production-style builds can safely continue to use `website/public/` without disrupting the running preview.\n", "2.0": "+++\ntitle = \"Website and Docs Architecture Overview\"\n+++\n\n## What Lives In `website/`\n\nThe public site lives under `website/`. The important areas are:\n\n```text\nwebsite/\n  content/\n    docs/\n  data/\n    docs-nav/\n    docs-versions.toml\n  scripts/\n  themes/sambee/\n  assets/\n  static/\n```\n\nIn practice:\n\n- `content/` holds the authored website pages and docs pages.\n- `content/docs/` holds the published versioned docs books.\n- `data/docs-versions.toml` declares the canonical docs version order and the current version.\n- `data/docs-nav/\u003cversion\u003e.toml` declares book, section, and page ordering for one version.\n- `scripts/` holds build helpers, docs validation, docs materialization, and docs editor automation.\n- `themes/sambee/` holds the Hugo layouts, partials, CSS, and JS for the public site.\n- `assets/` and `static/` hold source media, generated media, and static files.\n\n## How Docs Routing Works\n\nDocs content is versioned in the content tree:\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe current docs version also publishes stable unversioned routes:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nArchived or explicit versioned routes remain available at:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/...`\n\nThe routing rules, inheritance markers, and stable-current behavior are covered in more detail in [Docs Content Model, Navigation, and Inheritance](../docs-content-model-navigation-and-inheritance/).\n\n## Build and Preview Pipeline\n\nThe website build is more than a plain Hugo render.\n\nThe normal production-style build is:\n\n```bash\ncd website\nnpm run build\n```\n\nThat command runs:\n\n1. theme generation\n2. docs validation\n3. inherited-doc materialization\n4. Hugo site build\n5. homepage CTA validation\n\nFor local development, use:\n\n```bash\n./scripts/start-website\n```\n\nOr run the website dev workflow directly:\n\n```bash\ncd website\nnpm run dev\n```\n\nThat dev workflow also keeps search indexing and WebP generation in sync while you iterate. Its transient output is written to `website/public-dev/`, so production-style builds can safely continue to use `website/public/` without disrupting the running preview.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:website-dev-guide/docs-platform/docs-content-model-navigation-and-inheritance", "parent_id": "section:website-dev-guide/docs-platform", "depth": 2, "kind": "page", "label": "docs-content-model-navigation-and-inheritance", "title": "Docs Content Model Navigation And Inheritance", "path": "website-dev-guide/docs-platform/docs-content-model-navigation-and-inheritance", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Docs Content Model, Navigation, and Inheritance\"\n+++\n\nSambee's docs system is intentionally strict. That is a feature, not incidental complexity.\n\nThe strict rules keep URLs, page identity, navigation, inheritance, and render-time resolution aligned.\n\n## Core Model\n\nDocs identity is path-derived under `website/content/docs/`.\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe path itself defines the docs identity:\n\n- version slug: `content/docs/\u003cversion\u003e/`\n- book slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- section slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- page slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Public URL Contract\n\nFor the docs version marked as current, the canonical public routes are stable and unversioned:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nExplicit versioned routes are available for each existing version:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Filesystem Contract\n\nThe docs system allows real authored content and inheritance markers. The allowed combinations are strict.\n\n### Page Folders\n\nA page folder under `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/` must contain exactly one of:\n\n- `index.md`: real page content\n- `inherit.md`: empty inheritance marker\n\nDo not keep both files in the same page folder.\n\n### Version Folders\n\nA version folder must contain exactly one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\n### Book and Section Folders\n\nA book folder or section folder may contain zero or one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\nIf neither file exists, the folder is structural only and has no content or public landing route of its own.\n\n## Marker Files Are Markers Only\n\nInheritance markers do not carry content or override metadata.\n\n- `inherit.md` and `_inherit.md` must be empty and have no front matter.\n\nIf a newer version needs different content, replace the marker with real content.\n\n## Navigation Data Contract\n\nNavigation data lives in `website/data/docs-nav/\u003cversion\u003e.toml`.\n\nThese files define ordering only.\n\n- `books` orders books\n- `[[sections.\u003cbook\u003e.items]]` orders sections and gives each section a displayed title\n- `[pages.\u003cbook\u003e.\u003csection\u003e].items` orders pages inside one section\n\nExample:\n\n```toml\nbooks = [\n  \"user-guide\",\n  \"admin-guide\",\n  \"developer-guide\",\n  \"website-dev-guide\",\n]\n\n[[sections.website-dev-guide.items]]\nslug = \"authoring-and-tooling\"\ntitle = \"Authoring and Tooling\"\n\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n]\n```\n\nNavigation data does not define:\n\n- URLs\n- page titles\n- page existence\n- inheritance behavior\n\nThose come from the content tree and the effective-page resolver.\n\n## Version Order and Current Version\n\nVersion metadata lives in `website/data/docs-versions.toml`.\n\nImportant rules:\n\n- versions are listed in ascending release order, oldest to newest\n- that declaration order is canonical\n- inheritance only walks backward through that order\n- the `current` key defines the version that publishes at stable unversioned routes\n\nDo not infer chronology from the version slug string itself. Use the declared order.\n\n### Inheritance Resolution\n\nWhen Hugo renders a docs URL for a version, the system checks the requested version first and then walks backward through earlier versions until it finds real content.\n\nFor article pages, the resolution order is:\n\n1. check `index.md` at the requested path\n   - if present, use it\n   - otherwise, if `inherit.md` exists, move to the previous declared version and check the same path\n   - if neither file exists, validation should fail\n1. if the backward scan ends without finding real content, validation should fail\n\nLanding-page resolution follows the same pattern with `_index.md` and `_inherit.md`.\n\nExample:\n\n```text\ncontent/docs/0.7/website-dev-guide/docs-platform/website-and-docs-architecture-overview/index.md\ncontent/docs/0.8/website-dev-guide/docs-platform/website-and-docs-architecture-overview/inherit.md\n```\n\nIn that case, the `0.8` route remains routable, but the content comes from the `0.7` authored page until `0.8` diverges.\n\n## Safe Change Checklist\n\nWhen changing docs content, navigation, or routing behavior:\n\n- keep the filesystem path aligned with the intended public URL\n- update `docs-nav/\u003cversion\u003e.toml` when section or page ordering changes\n- treat slug changes as URL changes, not cosmetic edits\n- keep marker files empty\n- preserve the expected file combinations for pages, books, and sections\n- run the website build before finishing\n\n## Common Failure Modes\n\n- adding a page without adding the corresponding nav entry\n- changing a slug in content but not in nav data\n- leaving both `index.md` and `inherit.md` in one page folder\n- adding content or front matter to `inherit.md` or `_inherit.md`\n- putting published content into a source-material folder and assuming it is live docs\n- changing template or script behavior without preserving the same docs path contract\n", "0.8": "+++\ntitle = \"Docs Content Model, Navigation, and Inheritance\"\n+++\n\nSambee's docs system is intentionally strict. That is a feature, not incidental complexity.\n\nThe strict rules keep URLs, page identity, navigation, inheritance, and render-time resolution aligned.\n\n## Core Model\n\nDocs identity is path-derived under `website/content/docs/`.\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe path itself defines the docs identity:\n\n- version slug: `content/docs/\u003cversion\u003e/`\n- book slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- section slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- page slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Public URL Contract\n\nFor the docs version marked as current, the canonical public routes are stable and unversioned:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nExplicit versioned routes are available for each existing version:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Filesystem Contract\n\nThe docs system allows real authored content and inheritance markers. The allowed combinations are strict.\n\n### Page Folders\n\nA page folder under `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/` must contain exactly one of:\n\n- `index.md`: real page content\n- `inherit.md`: empty inheritance marker\n\nDo not keep both files in the same page folder.\n\n### Version Folders\n\nA version folder must contain exactly one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\n### Book and Section Folders\n\nA book folder or section folder may contain zero or one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\nIf neither file exists, the folder is structural only and has no content or public landing route of its own.\n\n## Marker Files Are Markers Only\n\nInheritance markers do not carry content or override metadata.\n\n- `inherit.md` and `_inherit.md` must be empty and have no front matter.\n\nIf a newer version needs different content, replace the marker with real content.\n\n## Navigation Data Contract\n\nNavigation data lives in `website/data/docs-nav/\u003cversion\u003e.toml`.\n\nThese files define ordering only.\n\n- `books` orders books\n- `[[sections.\u003cbook\u003e.items]]` orders sections and gives each section a displayed title\n- `[pages.\u003cbook\u003e.\u003csection\u003e].items` orders pages inside one section\n\nExample:\n\n```toml\nbooks = [\n  \"user-guide\",\n  \"admin-guide\",\n  \"developer-guide\",\n  \"website-dev-guide\",\n]\n\n[[sections.website-dev-guide.items]]\nslug = \"authoring-and-tooling\"\ntitle = \"Authoring and Tooling\"\n\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n]\n```\n\nNavigation data does not define:\n\n- URLs\n- page titles\n- page existence\n- inheritance behavior\n\nThose come from the content tree and the effective-page resolver.\n\n## Version Order and Current Version\n\nVersion metadata lives in `website/data/docs-versions.toml`.\n\nImportant rules:\n\n- versions are listed in ascending release order, oldest to newest\n- that declaration order is canonical\n- inheritance only walks backward through that order\n- the `current` key defines the version that publishes at stable unversioned routes\n\nDo not infer chronology from the version slug string itself. Use the declared order.\n\n### Inheritance Resolution\n\nWhen Hugo renders a docs URL for a version, the system checks the requested version first and then walks backward through earlier versions until it finds real content.\n\nFor article pages, the resolution order is:\n\n1. check `index.md` at the requested path\n   - if present, use it\n   - otherwise, if `inherit.md` exists, move to the previous declared version and check the same path\n   - if neither file exists, validation should fail\n1. if the backward scan ends without finding real content, validation should fail\n\nLanding-page resolution follows the same pattern with `_index.md` and `_inherit.md`.\n\nExample:\n\n```text\ncontent/docs/0.7/website-dev-guide/docs-platform/website-and-docs-architecture-overview/index.md\ncontent/docs/0.8/website-dev-guide/docs-platform/website-and-docs-architecture-overview/inherit.md\n```\n\nIn that case, the `0.8` route remains routable, but the content comes from the `0.7` authored page until `0.8` diverges.\n\n## Safe Change Checklist\n\nWhen changing docs content, navigation, or routing behavior:\n\n- keep the filesystem path aligned with the intended public URL\n- update `docs-nav/\u003cversion\u003e.toml` when section or page ordering changes\n- treat slug changes as URL changes, not cosmetic edits\n- keep marker files empty\n- preserve the expected file combinations for pages, books, and sections\n- run the website build before finishing\n\n## Common Failure Modes\n\n- adding a page without adding the corresponding nav entry\n- changing a slug in content but not in nav data\n- leaving both `index.md` and `inherit.md` in one page folder\n- adding content or front matter to `inherit.md` or `_inherit.md`\n- putting published content into a source-material folder and assuming it is live docs\n- changing template or script behavior without preserving the same docs path contract\n", "0.9": "+++\ntitle = \"Docs Content Model, Navigation, and Inheritance\"\n+++\n\nSambee's docs system is intentionally strict. That is a feature, not incidental complexity.\n\nThe strict rules keep URLs, page identity, navigation, inheritance, and render-time resolution aligned.\n\n## Core Model\n\nDocs identity is path-derived under `website/content/docs/`.\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe path itself defines the docs identity:\n\n- version slug: `content/docs/\u003cversion\u003e/`\n- book slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- section slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- page slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Public URL Contract\n\nFor the docs version marked as current, the canonical public routes are stable and unversioned:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nExplicit versioned routes are available for each existing version:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Filesystem Contract\n\nThe docs system allows real authored content and inheritance markers. The allowed combinations are strict.\n\n### Page Folders\n\nA page folder under `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/` must contain exactly one of:\n\n- `index.md`: real page content\n- `inherit.md`: empty inheritance marker\n\nDo not keep both files in the same page folder.\n\n### Version Folders\n\nA version folder must contain exactly one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\n### Book and Section Folders\n\nA book folder or section folder may contain zero or one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\nIf neither file exists, the folder is structural only and has no content or public landing route of its own.\n\n## Marker Files Are Markers Only\n\nInheritance markers do not carry content or override metadata.\n\n- `inherit.md` and `_inherit.md` must be empty and have no front matter.\n\nIf a newer version needs different content, replace the marker with real content.\n\n## Navigation Data Contract\n\nNavigation data lives in `website/data/docs-nav/\u003cversion\u003e.toml`.\n\nThese files define ordering only.\n\n- `books` orders books\n- `[[sections.\u003cbook\u003e.items]]` orders sections and gives each section a displayed title\n- `[pages.\u003cbook\u003e.\u003csection\u003e].items` orders pages inside one section\n\nExample:\n\n```toml\nbooks = [\n  \"user-guide\",\n  \"admin-guide\",\n  \"developer-guide\",\n  \"website-dev-guide\",\n]\n\n[[sections.website-dev-guide.items]]\nslug = \"authoring-and-tooling\"\ntitle = \"Authoring and Tooling\"\n\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n]\n```\n\nNavigation data does not define:\n\n- URLs\n- page titles\n- page existence\n- inheritance behavior\n\nThose come from the content tree and the effective-page resolver.\n\n## Version Order and Current Version\n\nVersion metadata lives in `website/data/docs-versions.toml`.\n\nImportant rules:\n\n- versions are listed in ascending release order, oldest to newest\n- that declaration order is canonical\n- inheritance only walks backward through that order\n- the `current` key defines the version that publishes at stable unversioned routes\n\nDo not infer chronology from the version slug string itself. Use the declared order.\n\n### Inheritance Resolution\n\nWhen Hugo renders a docs URL for a version, the system checks the requested version first and then walks backward through earlier versions until it finds real content.\n\nFor article pages, the resolution order is:\n\n1. check `index.md` at the requested path\n   - if present, use it\n   - otherwise, if `inherit.md` exists, move to the previous declared version and check the same path\n   - if neither file exists, validation should fail\n1. if the backward scan ends without finding real content, validation should fail\n\nLanding-page resolution follows the same pattern with `_index.md` and `_inherit.md`.\n\nExample:\n\n```text\ncontent/docs/0.7/website-dev-guide/docs-platform/website-and-docs-architecture-overview/index.md\ncontent/docs/0.8/website-dev-guide/docs-platform/website-and-docs-architecture-overview/inherit.md\n```\n\nIn that case, the `0.8` route remains routable, but the content comes from the `0.7` authored page until `0.8` diverges.\n\n## Safe Change Checklist\n\nWhen changing docs content, navigation, or routing behavior:\n\n- keep the filesystem path aligned with the intended public URL\n- update `docs-nav/\u003cversion\u003e.toml` when section or page ordering changes\n- treat slug changes as URL changes, not cosmetic edits\n- keep marker files empty\n- preserve the expected file combinations for pages, books, and sections\n- run the website build before finishing\n\n## Common Failure Modes\n\n- adding a page without adding the corresponding nav entry\n- changing a slug in content but not in nav data\n- leaving both `index.md` and `inherit.md` in one page folder\n- adding content or front matter to `inherit.md` or `_inherit.md`\n- putting published content into a source-material folder and assuming it is live docs\n- changing template or script behavior without preserving the same docs path contract\n", "1.0": "+++\ntitle = \"Docs Content Model, Navigation, and Inheritance\"\n+++\n\nSambee's docs system is intentionally strict. That is a feature, not incidental complexity.\n\nThe strict rules keep URLs, page identity, navigation, inheritance, and render-time resolution aligned.\n\n## Core Model\n\nDocs identity is path-derived under `website/content/docs/`.\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe path itself defines the docs identity:\n\n- version slug: `content/docs/\u003cversion\u003e/`\n- book slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- section slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- page slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Public URL Contract\n\nFor the docs version marked as current, the canonical public routes are stable and unversioned:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nExplicit versioned routes are available for each existing version:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Filesystem Contract\n\nThe docs system allows real authored content and inheritance markers. The allowed combinations are strict.\n\n### Page Folders\n\nA page folder under `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/` must contain exactly one of:\n\n- `index.md`: real page content\n- `inherit.md`: empty inheritance marker\n\nDo not keep both files in the same page folder.\n\n### Version Folders\n\nA version folder must contain exactly one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\n### Book and Section Folders\n\nA book folder or section folder may contain zero or one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\nIf neither file exists, the folder is structural only and has no content or public landing route of its own.\n\n## Marker Files Are Markers Only\n\nInheritance markers do not carry content or override metadata.\n\n- `inherit.md` and `_inherit.md` must be empty and have no front matter.\n\nIf a newer version needs different content, replace the marker with real content.\n\n## Navigation Data Contract\n\nNavigation data lives in `website/data/docs-nav/\u003cversion\u003e.toml`.\n\nThese files define ordering only.\n\n- `books` orders books\n- `[[sections.\u003cbook\u003e.items]]` orders sections and gives each section a displayed title\n- `[pages.\u003cbook\u003e.\u003csection\u003e].items` orders pages inside one section\n\nExample:\n\n```toml\nbooks = [\n  \"user-guide\",\n  \"admin-guide\",\n  \"developer-guide\",\n  \"website-dev-guide\",\n]\n\n[[sections.website-dev-guide.items]]\nslug = \"authoring-and-tooling\"\ntitle = \"Authoring and Tooling\"\n\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n]\n```\n\nNavigation data does not define:\n\n- URLs\n- page titles\n- page existence\n- inheritance behavior\n\nThose come from the content tree and the effective-page resolver.\n\n## Version Order and Current Version\n\nVersion metadata lives in `website/data/docs-versions.toml`.\n\nImportant rules:\n\n- versions are listed in ascending release order, oldest to newest\n- that declaration order is canonical\n- inheritance only walks backward through that order\n- the `current` key defines the version that publishes at stable unversioned routes\n\nDo not infer chronology from the version slug string itself. Use the declared order.\n\n### Inheritance Resolution\n\nWhen Hugo renders a docs URL for a version, the system checks the requested version first and then walks backward through earlier versions until it finds real content.\n\nFor article pages, the resolution order is:\n\n1. check `index.md` at the requested path\n   - if present, use it\n   - otherwise, if `inherit.md` exists, move to the previous declared version and check the same path\n   - if neither file exists, validation should fail\n1. if the backward scan ends without finding real content, validation should fail\n\nLanding-page resolution follows the same pattern with `_index.md` and `_inherit.md`.\n\nExample:\n\n```text\ncontent/docs/0.7/website-dev-guide/docs-platform/website-and-docs-architecture-overview/index.md\ncontent/docs/0.8/website-dev-guide/docs-platform/website-and-docs-architecture-overview/inherit.md\n```\n\nIn that case, the `0.8` route remains routable, but the content comes from the `0.7` authored page until `0.8` diverges.\n\n## Safe Change Checklist\n\nWhen changing docs content, navigation, or routing behavior:\n\n- keep the filesystem path aligned with the intended public URL\n- update `docs-nav/\u003cversion\u003e.toml` when section or page ordering changes\n- treat slug changes as URL changes, not cosmetic edits\n- keep marker files empty\n- preserve the expected file combinations for pages, books, and sections\n- run the website build before finishing\n\n## Common Failure Modes\n\n- adding a page without adding the corresponding nav entry\n- changing a slug in content but not in nav data\n- leaving both `index.md` and `inherit.md` in one page folder\n- adding content or front matter to `inherit.md` or `_inherit.md`\n- putting published content into a source-material folder and assuming it is live docs\n- changing template or script behavior without preserving the same docs path contract\n", "2.0": "+++\ntitle = \"Docs Content Model, Navigation, and Inheritance\"\n+++\n\nSambee's docs system is intentionally strict. That is a feature, not incidental complexity.\n\nThe strict rules keep URLs, page identity, navigation, inheritance, and render-time resolution aligned.\n\n## Core Model\n\nDocs identity is path-derived under `website/content/docs/`.\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe path itself defines the docs identity:\n\n- version slug: `content/docs/\u003cversion\u003e/`\n- book slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- section slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- page slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Public URL Contract\n\nFor the docs version marked as current, the canonical public routes are stable and unversioned:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nExplicit versioned routes are available for each existing version:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Filesystem Contract\n\nThe docs system allows real authored content and inheritance markers. The allowed combinations are strict.\n\n### Page Folders\n\nA page folder under `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/` must contain exactly one of:\n\n- `index.md`: real page content\n- `inherit.md`: empty inheritance marker\n\nDo not keep both files in the same page folder.\n\n### Version Folders\n\nA version folder must contain exactly one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\n### Book and Section Folders\n\nA book folder or section folder may contain zero or one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\nIf neither file exists, the folder is structural only and has no content or public landing route of its own.\n\n## Marker Files Are Markers Only\n\nInheritance markers do not carry content or override metadata.\n\n- `inherit.md` and `_inherit.md` must be empty and have no front matter.\n\nIf a newer version needs different content, replace the marker with real content.\n\n## Navigation Data Contract\n\nNavigation data lives in `website/data/docs-nav/\u003cversion\u003e.toml`.\n\nThese files define ordering only.\n\n- `books` orders books\n- `[[sections.\u003cbook\u003e.items]]` orders sections and gives each section a displayed title\n- `[pages.\u003cbook\u003e.\u003csection\u003e].items` orders pages inside one section\n\nExample:\n\n```toml\nbooks = [\n  \"user-guide\",\n  \"admin-guide\",\n  \"developer-guide\",\n  \"website-dev-guide\",\n]\n\n[[sections.website-dev-guide.items]]\nslug = \"authoring-and-tooling\"\ntitle = \"Authoring and Tooling\"\n\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n]\n```\n\nNavigation data does not define:\n\n- URLs\n- page titles\n- page existence\n- inheritance behavior\n\nThose come from the content tree and the effective-page resolver.\n\n## Version Order and Current Version\n\nVersion metadata lives in `website/data/docs-versions.toml`.\n\nImportant rules:\n\n- versions are listed in ascending release order, oldest to newest\n- that declaration order is canonical\n- inheritance only walks backward through that order\n- the `current` key defines the version that publishes at stable unversioned routes\n\nDo not infer chronology from the version slug string itself. Use the declared order.\n\n### Inheritance Resolution\n\nWhen Hugo renders a docs URL for a version, the system checks the requested version first and then walks backward through earlier versions until it finds real content.\n\nFor article pages, the resolution order is:\n\n1. check `index.md` at the requested path\n   - if present, use it\n   - otherwise, if `inherit.md` exists, move to the previous declared version and check the same path\n   - if neither file exists, validation should fail\n1. if the backward scan ends without finding real content, validation should fail\n\nLanding-page resolution follows the same pattern with `_index.md` and `_inherit.md`.\n\nExample:\n\n```text\ncontent/docs/0.7/website-dev-guide/docs-platform/website-and-docs-architecture-overview/index.md\ncontent/docs/0.8/website-dev-guide/docs-platform/website-and-docs-architecture-overview/inherit.md\n```\n\nIn that case, the `0.8` route remains routable, but the content comes from the `0.7` authored page until `0.8` diverges.\n\n## Safe Change Checklist\n\nWhen changing docs content, navigation, or routing behavior:\n\n- keep the filesystem path aligned with the intended public URL\n- update `docs-nav/\u003cversion\u003e.toml` when section or page ordering changes\n- treat slug changes as URL changes, not cosmetic edits\n- keep marker files empty\n- preserve the expected file combinations for pages, books, and sections\n- run the website build before finishing\n\n## Common Failure Modes\n\n- adding a page without adding the corresponding nav entry\n- changing a slug in content but not in nav data\n- leaving both `index.md` and `inherit.md` in one page folder\n- adding content or front matter to `inherit.md` or `_inherit.md`\n- putting published content into a source-material folder and assuming it is live docs\n- changing template or script behavior without preserving the same docs path contract\n"}, "page_contents": {"0.7": "+++\ntitle = \"Docs Content Model, Navigation, and Inheritance\"\n+++\n\nSambee's docs system is intentionally strict. That is a feature, not incidental complexity.\n\nThe strict rules keep URLs, page identity, navigation, inheritance, and render-time resolution aligned.\n\n## Core Model\n\nDocs identity is path-derived under `website/content/docs/`.\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe path itself defines the docs identity:\n\n- version slug: `content/docs/\u003cversion\u003e/`\n- book slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- section slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- page slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Public URL Contract\n\nFor the docs version marked as current, the canonical public routes are stable and unversioned:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nExplicit versioned routes are available for each existing version:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Filesystem Contract\n\nThe docs system allows real authored content and inheritance markers. The allowed combinations are strict.\n\n### Page Folders\n\nA page folder under `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/` must contain exactly one of:\n\n- `index.md`: real page content\n- `inherit.md`: empty inheritance marker\n\nDo not keep both files in the same page folder.\n\n### Version Folders\n\nA version folder must contain exactly one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\n### Book and Section Folders\n\nA book folder or section folder may contain zero or one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\nIf neither file exists, the folder is structural only and has no content or public landing route of its own.\n\n## Marker Files Are Markers Only\n\nInheritance markers do not carry content or override metadata.\n\n- `inherit.md` and `_inherit.md` must be empty and have no front matter.\n\nIf a newer version needs different content, replace the marker with real content.\n\n## Navigation Data Contract\n\nNavigation data lives in `website/data/docs-nav/\u003cversion\u003e.toml`.\n\nThese files define ordering only.\n\n- `books` orders books\n- `[[sections.\u003cbook\u003e.items]]` orders sections and gives each section a displayed title\n- `[pages.\u003cbook\u003e.\u003csection\u003e].items` orders pages inside one section\n\nExample:\n\n```toml\nbooks = [\n  \"user-guide\",\n  \"admin-guide\",\n  \"developer-guide\",\n  \"website-dev-guide\",\n]\n\n[[sections.website-dev-guide.items]]\nslug = \"authoring-and-tooling\"\ntitle = \"Authoring and Tooling\"\n\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n]\n```\n\nNavigation data does not define:\n\n- URLs\n- page titles\n- page existence\n- inheritance behavior\n\nThose come from the content tree and the effective-page resolver.\n\n## Version Order and Current Version\n\nVersion metadata lives in `website/data/docs-versions.toml`.\n\nImportant rules:\n\n- versions are listed in ascending release order, oldest to newest\n- that declaration order is canonical\n- inheritance only walks backward through that order\n- the `current` key defines the version that publishes at stable unversioned routes\n\nDo not infer chronology from the version slug string itself. Use the declared order.\n\n### Inheritance Resolution\n\nWhen Hugo renders a docs URL for a version, the system checks the requested version first and then walks backward through earlier versions until it finds real content.\n\nFor article pages, the resolution order is:\n\n1. check `index.md` at the requested path\n   - if present, use it\n   - otherwise, if `inherit.md` exists, move to the previous declared version and check the same path\n   - if neither file exists, validation should fail\n1. if the backward scan ends without finding real content, validation should fail\n\nLanding-page resolution follows the same pattern with `_index.md` and `_inherit.md`.\n\nExample:\n\n```text\ncontent/docs/0.7/website-dev-guide/docs-platform/website-and-docs-architecture-overview/index.md\ncontent/docs/0.8/website-dev-guide/docs-platform/website-and-docs-architecture-overview/inherit.md\n```\n\nIn that case, the `0.8` route remains routable, but the content comes from the `0.7` authored page until `0.8` diverges.\n\n## Safe Change Checklist\n\nWhen changing docs content, navigation, or routing behavior:\n\n- keep the filesystem path aligned with the intended public URL\n- update `docs-nav/\u003cversion\u003e.toml` when section or page ordering changes\n- treat slug changes as URL changes, not cosmetic edits\n- keep marker files empty\n- preserve the expected file combinations for pages, books, and sections\n- run the website build before finishing\n\n## Common Failure Modes\n\n- adding a page without adding the corresponding nav entry\n- changing a slug in content but not in nav data\n- leaving both `index.md` and `inherit.md` in one page folder\n- adding content or front matter to `inherit.md` or `_inherit.md`\n- putting published content into a source-material folder and assuming it is live docs\n- changing template or script behavior without preserving the same docs path contract\n", "0.8": "+++\ntitle = \"Docs Content Model, Navigation, and Inheritance\"\n+++\n\nSambee's docs system is intentionally strict. That is a feature, not incidental complexity.\n\nThe strict rules keep URLs, page identity, navigation, inheritance, and render-time resolution aligned.\n\n## Core Model\n\nDocs identity is path-derived under `website/content/docs/`.\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe path itself defines the docs identity:\n\n- version slug: `content/docs/\u003cversion\u003e/`\n- book slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- section slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- page slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Public URL Contract\n\nFor the docs version marked as current, the canonical public routes are stable and unversioned:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nExplicit versioned routes are available for each existing version:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Filesystem Contract\n\nThe docs system allows real authored content and inheritance markers. The allowed combinations are strict.\n\n### Page Folders\n\nA page folder under `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/` must contain exactly one of:\n\n- `index.md`: real page content\n- `inherit.md`: empty inheritance marker\n\nDo not keep both files in the same page folder.\n\n### Version Folders\n\nA version folder must contain exactly one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\n### Book and Section Folders\n\nA book folder or section folder may contain zero or one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\nIf neither file exists, the folder is structural only and has no content or public landing route of its own.\n\n## Marker Files Are Markers Only\n\nInheritance markers do not carry content or override metadata.\n\n- `inherit.md` and `_inherit.md` must be empty and have no front matter.\n\nIf a newer version needs different content, replace the marker with real content.\n\n## Navigation Data Contract\n\nNavigation data lives in `website/data/docs-nav/\u003cversion\u003e.toml`.\n\nThese files define ordering only.\n\n- `books` orders books\n- `[[sections.\u003cbook\u003e.items]]` orders sections and gives each section a displayed title\n- `[pages.\u003cbook\u003e.\u003csection\u003e].items` orders pages inside one section\n\nExample:\n\n```toml\nbooks = [\n  \"user-guide\",\n  \"admin-guide\",\n  \"developer-guide\",\n  \"website-dev-guide\",\n]\n\n[[sections.website-dev-guide.items]]\nslug = \"authoring-and-tooling\"\ntitle = \"Authoring and Tooling\"\n\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n]\n```\n\nNavigation data does not define:\n\n- URLs\n- page titles\n- page existence\n- inheritance behavior\n\nThose come from the content tree and the effective-page resolver.\n\n## Version Order and Current Version\n\nVersion metadata lives in `website/data/docs-versions.toml`.\n\nImportant rules:\n\n- versions are listed in ascending release order, oldest to newest\n- that declaration order is canonical\n- inheritance only walks backward through that order\n- the `current` key defines the version that publishes at stable unversioned routes\n\nDo not infer chronology from the version slug string itself. Use the declared order.\n\n### Inheritance Resolution\n\nWhen Hugo renders a docs URL for a version, the system checks the requested version first and then walks backward through earlier versions until it finds real content.\n\nFor article pages, the resolution order is:\n\n1. check `index.md` at the requested path\n   - if present, use it\n   - otherwise, if `inherit.md` exists, move to the previous declared version and check the same path\n   - if neither file exists, validation should fail\n1. if the backward scan ends without finding real content, validation should fail\n\nLanding-page resolution follows the same pattern with `_index.md` and `_inherit.md`.\n\nExample:\n\n```text\ncontent/docs/0.7/website-dev-guide/docs-platform/website-and-docs-architecture-overview/index.md\ncontent/docs/0.8/website-dev-guide/docs-platform/website-and-docs-architecture-overview/inherit.md\n```\n\nIn that case, the `0.8` route remains routable, but the content comes from the `0.7` authored page until `0.8` diverges.\n\n## Safe Change Checklist\n\nWhen changing docs content, navigation, or routing behavior:\n\n- keep the filesystem path aligned with the intended public URL\n- update `docs-nav/\u003cversion\u003e.toml` when section or page ordering changes\n- treat slug changes as URL changes, not cosmetic edits\n- keep marker files empty\n- preserve the expected file combinations for pages, books, and sections\n- run the website build before finishing\n\n## Common Failure Modes\n\n- adding a page without adding the corresponding nav entry\n- changing a slug in content but not in nav data\n- leaving both `index.md` and `inherit.md` in one page folder\n- adding content or front matter to `inherit.md` or `_inherit.md`\n- putting published content into a source-material folder and assuming it is live docs\n- changing template or script behavior without preserving the same docs path contract\n", "0.9": "+++\ntitle = \"Docs Content Model, Navigation, and Inheritance\"\n+++\n\nSambee's docs system is intentionally strict. That is a feature, not incidental complexity.\n\nThe strict rules keep URLs, page identity, navigation, inheritance, and render-time resolution aligned.\n\n## Core Model\n\nDocs identity is path-derived under `website/content/docs/`.\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe path itself defines the docs identity:\n\n- version slug: `content/docs/\u003cversion\u003e/`\n- book slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- section slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- page slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Public URL Contract\n\nFor the docs version marked as current, the canonical public routes are stable and unversioned:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nExplicit versioned routes are available for each existing version:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Filesystem Contract\n\nThe docs system allows real authored content and inheritance markers. The allowed combinations are strict.\n\n### Page Folders\n\nA page folder under `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/` must contain exactly one of:\n\n- `index.md`: real page content\n- `inherit.md`: empty inheritance marker\n\nDo not keep both files in the same page folder.\n\n### Version Folders\n\nA version folder must contain exactly one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\n### Book and Section Folders\n\nA book folder or section folder may contain zero or one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\nIf neither file exists, the folder is structural only and has no content or public landing route of its own.\n\n## Marker Files Are Markers Only\n\nInheritance markers do not carry content or override metadata.\n\n- `inherit.md` and `_inherit.md` must be empty and have no front matter.\n\nIf a newer version needs different content, replace the marker with real content.\n\n## Navigation Data Contract\n\nNavigation data lives in `website/data/docs-nav/\u003cversion\u003e.toml`.\n\nThese files define ordering only.\n\n- `books` orders books\n- `[[sections.\u003cbook\u003e.items]]` orders sections and gives each section a displayed title\n- `[pages.\u003cbook\u003e.\u003csection\u003e].items` orders pages inside one section\n\nExample:\n\n```toml\nbooks = [\n  \"user-guide\",\n  \"admin-guide\",\n  \"developer-guide\",\n  \"website-dev-guide\",\n]\n\n[[sections.website-dev-guide.items]]\nslug = \"authoring-and-tooling\"\ntitle = \"Authoring and Tooling\"\n\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n]\n```\n\nNavigation data does not define:\n\n- URLs\n- page titles\n- page existence\n- inheritance behavior\n\nThose come from the content tree and the effective-page resolver.\n\n## Version Order and Current Version\n\nVersion metadata lives in `website/data/docs-versions.toml`.\n\nImportant rules:\n\n- versions are listed in ascending release order, oldest to newest\n- that declaration order is canonical\n- inheritance only walks backward through that order\n- the `current` key defines the version that publishes at stable unversioned routes\n\nDo not infer chronology from the version slug string itself. Use the declared order.\n\n### Inheritance Resolution\n\nWhen Hugo renders a docs URL for a version, the system checks the requested version first and then walks backward through earlier versions until it finds real content.\n\nFor article pages, the resolution order is:\n\n1. check `index.md` at the requested path\n   - if present, use it\n   - otherwise, if `inherit.md` exists, move to the previous declared version and check the same path\n   - if neither file exists, validation should fail\n1. if the backward scan ends without finding real content, validation should fail\n\nLanding-page resolution follows the same pattern with `_index.md` and `_inherit.md`.\n\nExample:\n\n```text\ncontent/docs/0.7/website-dev-guide/docs-platform/website-and-docs-architecture-overview/index.md\ncontent/docs/0.8/website-dev-guide/docs-platform/website-and-docs-architecture-overview/inherit.md\n```\n\nIn that case, the `0.8` route remains routable, but the content comes from the `0.7` authored page until `0.8` diverges.\n\n## Safe Change Checklist\n\nWhen changing docs content, navigation, or routing behavior:\n\n- keep the filesystem path aligned with the intended public URL\n- update `docs-nav/\u003cversion\u003e.toml` when section or page ordering changes\n- treat slug changes as URL changes, not cosmetic edits\n- keep marker files empty\n- preserve the expected file combinations for pages, books, and sections\n- run the website build before finishing\n\n## Common Failure Modes\n\n- adding a page without adding the corresponding nav entry\n- changing a slug in content but not in nav data\n- leaving both `index.md` and `inherit.md` in one page folder\n- adding content or front matter to `inherit.md` or `_inherit.md`\n- putting published content into a source-material folder and assuming it is live docs\n- changing template or script behavior without preserving the same docs path contract\n", "1.0": "+++\ntitle = \"Docs Content Model, Navigation, and Inheritance\"\n+++\n\nSambee's docs system is intentionally strict. That is a feature, not incidental complexity.\n\nThe strict rules keep URLs, page identity, navigation, inheritance, and render-time resolution aligned.\n\n## Core Model\n\nDocs identity is path-derived under `website/content/docs/`.\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe path itself defines the docs identity:\n\n- version slug: `content/docs/\u003cversion\u003e/`\n- book slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- section slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- page slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Public URL Contract\n\nFor the docs version marked as current, the canonical public routes are stable and unversioned:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nExplicit versioned routes are available for each existing version:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Filesystem Contract\n\nThe docs system allows real authored content and inheritance markers. The allowed combinations are strict.\n\n### Page Folders\n\nA page folder under `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/` must contain exactly one of:\n\n- `index.md`: real page content\n- `inherit.md`: empty inheritance marker\n\nDo not keep both files in the same page folder.\n\n### Version Folders\n\nA version folder must contain exactly one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\n### Book and Section Folders\n\nA book folder or section folder may contain zero or one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\nIf neither file exists, the folder is structural only and has no content or public landing route of its own.\n\n## Marker Files Are Markers Only\n\nInheritance markers do not carry content or override metadata.\n\n- `inherit.md` and `_inherit.md` must be empty and have no front matter.\n\nIf a newer version needs different content, replace the marker with real content.\n\n## Navigation Data Contract\n\nNavigation data lives in `website/data/docs-nav/\u003cversion\u003e.toml`.\n\nThese files define ordering only.\n\n- `books` orders books\n- `[[sections.\u003cbook\u003e.items]]` orders sections and gives each section a displayed title\n- `[pages.\u003cbook\u003e.\u003csection\u003e].items` orders pages inside one section\n\nExample:\n\n```toml\nbooks = [\n  \"user-guide\",\n  \"admin-guide\",\n  \"developer-guide\",\n  \"website-dev-guide\",\n]\n\n[[sections.website-dev-guide.items]]\nslug = \"authoring-and-tooling\"\ntitle = \"Authoring and Tooling\"\n\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n]\n```\n\nNavigation data does not define:\n\n- URLs\n- page titles\n- page existence\n- inheritance behavior\n\nThose come from the content tree and the effective-page resolver.\n\n## Version Order and Current Version\n\nVersion metadata lives in `website/data/docs-versions.toml`.\n\nImportant rules:\n\n- versions are listed in ascending release order, oldest to newest\n- that declaration order is canonical\n- inheritance only walks backward through that order\n- the `current` key defines the version that publishes at stable unversioned routes\n\nDo not infer chronology from the version slug string itself. Use the declared order.\n\n### Inheritance Resolution\n\nWhen Hugo renders a docs URL for a version, the system checks the requested version first and then walks backward through earlier versions until it finds real content.\n\nFor article pages, the resolution order is:\n\n1. check `index.md` at the requested path\n   - if present, use it\n   - otherwise, if `inherit.md` exists, move to the previous declared version and check the same path\n   - if neither file exists, validation should fail\n1. if the backward scan ends without finding real content, validation should fail\n\nLanding-page resolution follows the same pattern with `_index.md` and `_inherit.md`.\n\nExample:\n\n```text\ncontent/docs/0.7/website-dev-guide/docs-platform/website-and-docs-architecture-overview/index.md\ncontent/docs/0.8/website-dev-guide/docs-platform/website-and-docs-architecture-overview/inherit.md\n```\n\nIn that case, the `0.8` route remains routable, but the content comes from the `0.7` authored page until `0.8` diverges.\n\n## Safe Change Checklist\n\nWhen changing docs content, navigation, or routing behavior:\n\n- keep the filesystem path aligned with the intended public URL\n- update `docs-nav/\u003cversion\u003e.toml` when section or page ordering changes\n- treat slug changes as URL changes, not cosmetic edits\n- keep marker files empty\n- preserve the expected file combinations for pages, books, and sections\n- run the website build before finishing\n\n## Common Failure Modes\n\n- adding a page without adding the corresponding nav entry\n- changing a slug in content but not in nav data\n- leaving both `index.md` and `inherit.md` in one page folder\n- adding content or front matter to `inherit.md` or `_inherit.md`\n- putting published content into a source-material folder and assuming it is live docs\n- changing template or script behavior without preserving the same docs path contract\n", "2.0": "+++\ntitle = \"Docs Content Model, Navigation, and Inheritance\"\n+++\n\nSambee's docs system is intentionally strict. That is a feature, not incidental complexity.\n\nThe strict rules keep URLs, page identity, navigation, inheritance, and render-time resolution aligned.\n\n## Core Model\n\nDocs identity is path-derived under `website/content/docs/`.\n\n```text\nwebsite/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md\n```\n\nThe path itself defines the docs identity:\n\n- version slug: `content/docs/\u003cversion\u003e/`\n- book slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- section slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- page slug: `content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Public URL Contract\n\nFor the docs version marked as current, the canonical public routes are stable and unversioned:\n\n- `/docs/\u003cbook\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\nExplicit versioned routes are available for each existing version:\n\n- `/docs/\u003cversion\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/`\n- `/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/`\n\n## Filesystem Contract\n\nThe docs system allows real authored content and inheritance markers. The allowed combinations are strict.\n\n### Page Folders\n\nA page folder under `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/` must contain exactly one of:\n\n- `index.md`: real page content\n- `inherit.md`: empty inheritance marker\n\nDo not keep both files in the same page folder.\n\n### Version Folders\n\nA version folder must contain exactly one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\n### Book and Section Folders\n\nA book folder or section folder may contain zero or one of:\n\n- `_index.md`: real landing-page content\n- `_inherit.md`: empty inheritance marker\n\nIf neither file exists, the folder is structural only and has no content or public landing route of its own.\n\n## Marker Files Are Markers Only\n\nInheritance markers do not carry content or override metadata.\n\n- `inherit.md` and `_inherit.md` must be empty and have no front matter.\n\nIf a newer version needs different content, replace the marker with real content.\n\n## Navigation Data Contract\n\nNavigation data lives in `website/data/docs-nav/\u003cversion\u003e.toml`.\n\nThese files define ordering only.\n\n- `books` orders books\n- `[[sections.\u003cbook\u003e.items]]` orders sections and gives each section a displayed title\n- `[pages.\u003cbook\u003e.\u003csection\u003e].items` orders pages inside one section\n\nExample:\n\n```toml\nbooks = [\n  \"user-guide\",\n  \"admin-guide\",\n  \"developer-guide\",\n  \"website-dev-guide\",\n]\n\n[[sections.website-dev-guide.items]]\nslug = \"authoring-and-tooling\"\ntitle = \"Authoring and Tooling\"\n\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n]\n```\n\nNavigation data does not define:\n\n- URLs\n- page titles\n- page existence\n- inheritance behavior\n\nThose come from the content tree and the effective-page resolver.\n\n## Version Order and Current Version\n\nVersion metadata lives in `website/data/docs-versions.toml`.\n\nImportant rules:\n\n- versions are listed in ascending release order, oldest to newest\n- that declaration order is canonical\n- inheritance only walks backward through that order\n- the `current` key defines the version that publishes at stable unversioned routes\n\nDo not infer chronology from the version slug string itself. Use the declared order.\n\n### Inheritance Resolution\n\nWhen Hugo renders a docs URL for a version, the system checks the requested version first and then walks backward through earlier versions until it finds real content.\n\nFor article pages, the resolution order is:\n\n1. check `index.md` at the requested path\n   - if present, use it\n   - otherwise, if `inherit.md` exists, move to the previous declared version and check the same path\n   - if neither file exists, validation should fail\n1. if the backward scan ends without finding real content, validation should fail\n\nLanding-page resolution follows the same pattern with `_index.md` and `_inherit.md`.\n\nExample:\n\n```text\ncontent/docs/0.7/website-dev-guide/docs-platform/website-and-docs-architecture-overview/index.md\ncontent/docs/0.8/website-dev-guide/docs-platform/website-and-docs-architecture-overview/inherit.md\n```\n\nIn that case, the `0.8` route remains routable, but the content comes from the `0.7` authored page until `0.8` diverges.\n\n## Safe Change Checklist\n\nWhen changing docs content, navigation, or routing behavior:\n\n- keep the filesystem path aligned with the intended public URL\n- update `docs-nav/\u003cversion\u003e.toml` when section or page ordering changes\n- treat slug changes as URL changes, not cosmetic edits\n- keep marker files empty\n- preserve the expected file combinations for pages, books, and sections\n- run the website build before finishing\n\n## Common Failure Modes\n\n- adding a page without adding the corresponding nav entry\n- changing a slug in content but not in nav data\n- leaving both `index.md` and `inherit.md` in one page folder\n- adding content or front matter to `inherit.md` or `_inherit.md`\n- putting published content into a source-material folder and assuming it is live docs\n- changing template or script behavior without preserving the same docs path contract\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:website-dev-guide/docs-platform/docs-runtime-and-route-resolution", "parent_id": "section:website-dev-guide/docs-platform", "depth": 2, "kind": "page", "label": "docs-runtime-and-route-resolution", "title": "Docs Runtime And Route Resolution", "path": "website-dev-guide/docs-platform/docs-runtime-and-route-resolution", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Docs Runtime and Route Resolution\"\n+++\n\nThis page covers the implementation-facing side of docs routing.\n\nUse it when you need to answer questions such as:\n\n- which files own docs route resolution\n- how stable current routes differ from explicit versioned routes\n- how inherited pages become routable\n- how version switching and docs search stay version-aware\n\n## Runtime Map\n\nEditors usually work in content and nav files. Web developers also need to know which files own version metadata, build-time validation, and runtime route resolution.\n\n### Content and Navigation Sources\n\nThese files define what the docs tree is supposed to be:\n\n- `website/data/docs-versions.toml`: canonical docs version metadata\n- `website/data/docs-nav/\u003cversion\u003e.toml`: ordered books, sections, and pages\n\nIf the docs UI order looks wrong, or a page exists on disk but not in navigation, these are the first files to check.\n\n### Build and Tooling Scripts\n\nThese scripts keep the docs tree valid and routable:\n\n- `website/scripts/validate-docs-content.py`: validates docs structure, markers, and nav integrity\n- `website/scripts/materialize-inherited-docs.py`: generates transient routable anchors for inherited docs and stable current routes\n- `website/scripts/docs-editor.py`: CLI for creating, deleting, and renaming docs versions, books, sections, and pages safely\n\nIn practice:\n\n- use the validator when you need to confirm content-tree and nav consistency\n- use materialization when testing inheritance or stable-current route behavior\n- use the docs editor for structural changes instead of hand-editing multiple files\n\n### Runtime Template Layer\n\nThese files turn the requested docs URL into the page the user actually sees:\n\n- `website/themes/sambee/layouts/partials/docs/context.html`: derives docs path context from the requested route\n- `website/themes/sambee/layouts/partials/docs/page-path.html`: builds docs content paths with stable-current routing support\n- `website/themes/sambee/layouts/partials/docs/page-url.html`: resolves navigable docs URLs\n- `website/themes/sambee/layouts/partials/docs/source-page.html`: resolves the explicit versioned source page behind stable current routes\n- `website/themes/sambee/layouts/partials/docs/effective-page.html`: resolves the authored page that supplies body content and metadata\n- `website/themes/sambee/layouts/partials/docs/render-data.html`: prepares shared docs render data, including redirect and indexing state\n- `website/themes/sambee/layouts/partials/docs/article-shell.html`: renders the shared docs article shell\n- `website/themes/sambee/layouts/partials/docs/redirect-target.html`: resolves docs entry redirects\n- `website/themes/sambee/layouts/partials/docs/nav-tree.html`: resolves navigation targets and displayed titles\n- `website/themes/sambee/layouts/partials/docs/version-target-url.html`: resolves cross-version switch targets\n- `website/themes/sambee/layouts/partials/search-modal.html`: applies docs-version-aware search behavior\n- `website/themes/sambee/layouts/docs/list.html` and `website/themes/sambee/layouts/docs/single.html`: route docs list and page rendering through the shared shell\n\n### Theme Assets\n\nThese assets shape the visible docs experience once the route and content have been resolved:\n\n- `website/themes/sambee/assets/css/`: shared theme CSS, including docs UI and typography\n\n## Requested Route Versus Effective Page\n\nThe docs runtime keeps requested-path context separate from effective-content resolution.\n\n### Requested Route Context\n\n`website/themes/sambee/layouts/partials/docs/context.html` derives path context from the requested route and returns values including:\n\n- `isDocs`\n- `version`\n- `book`\n- `section`\n- `page`\n- `kind`\n- `currentVersion`\n- `isExplicitVersion`\n- `isCurrentRoute`\n- `isCurrentVersion`\n- convenience booleans: `isDocsRoot`, `isVersion`, `isBook`, `isSection`, and `isPage`\n\nInterpretation rules that matter when changing templates:\n\n- stable current routes such as `/docs/website-dev-guide/...` still resolve to the current version even though the version slug is omitted\n- explicit current-version routes such as `/docs/0.7/...` are compatibility routes and should redirect to stable current routes\n- archived explicit version routes stay routable and render as full docs pages\n\n### Effective Content Resolution\n\n`website/themes/sambee/layouts/partials/docs/effective-page.html` then resolves the authored content source and returns values including:\n\n- `page`: the authored page that should supply title, description, TOC, and body content\n- `requestedPage`: the Hugo page for the requested route\n- `requestedVersion`: the version derived from the route\n- `resolvedVersion`: the version that supplied the effective content\n- `isInherited`: whether the route resolved through inheritance\n\nTemplates should render article content and metadata from `page`, while navigation state, breadcrumbs, and version-switcher state stay tied to the requested route context.\n\n## Why Materialization Exists\n\nHugo needs a concrete page object at the requested path. Raw marker files alone are not enough.\n\nThe build therefore materializes transient route anchors under `.generated/content/docs` so Hugo can route inherited pages and stable current routes without publishing broken `/inherit/` or `/_inherit/` URLs.\n\nFrom Hugo's perspective, `inherit.md` and `_inherit.md` are ordinary content files. If the site consumed them directly, Hugo would try to publish the wrong public URLs.\n\nExample:\n\n- `content/docs/1.1/end-user/getting-started/install/inherit.md` would naturally publish at `/docs/1.1/end-user/getting-started/install/inherit/`\n- `content/docs/1.1/_inherit.md` would naturally publish at `/docs/1.1/_inherit/`\n\nThose are invalid for this docs model. The canonical public URLs must stay attached to the folder path itself:\n\n- `/docs/1.1/end-user/getting-started/install/`\n- `/docs/1.1/`\n\nThat creates a routing gap:\n\n- raw marker files must not become public pages\n- Hugo still needs a real page or section node at the requested folder path so templates can run and the resolver can supply inherited content\n\nThe moving pieces are:\n\n- `website/hugo.toml` ignores raw marker files as direct public pages\n- `website/scripts/materialize-inherited-docs.py` generates transient anchors at the canonical folder paths\n- `website/config/_default/module.toml` mounts `.generated/content` into Hugo's content tree\n- `website/themes/sambee/layouts/partials/docs/effective-page.html` resolves the real authored page that should supply the body, title, description, and TOC\n\nDuring the build, `materialize-inherited-docs.py` does this work:\n\n1. deletes stale generated docs anchors under `website/.generated/content/docs/`\n2. scans `website/content/docs/` for `inherit.md` and `_inherit.md`\n3. generates transient `index.md` or `_index.md` anchors at the matching canonical folder paths under `website/.generated/content/docs/`\n4. generates transient anchors for the declared current version at stable routes under `website/.generated/content/docs/\u003cbook\u003e/...`\n5. marks inherited-route anchors with `inherit = true`\n6. marks stable current-route anchors with `current_route = true` and `source_docs_path = \"/docs/\u003ccurrent\u003e/...\"`\n\nOperational notes:\n\n- `website/.generated/` is build output and is ignored by Git\n- Hugo mounts `.generated/content` into the site content tree during the build\n- Hugo is configured to ignore raw `inherit.md` and `_inherit.md` files\n\nWithout this script, the project would be stuck with two bad options:\n\n- keep raw marker files visible to Hugo and accept broken `/inherit/` and `/_inherit/` URLs\n- ignore marker files and lose the routable page nodes needed to render inherited docs at canonical folder URLs\n\n## Version Switcher Fallback Order\n\nWhen a reader switches from one docs version to another, the target lookup order is:\n\n1. the same page path\n2. the same section landing path\n3. the same book landing path\n4. the target version landing path\n\n## Search Behavior\n\nDocs search is intentionally version-aware.\n\n- Pagefind indexes stable current docs URLs, not explicit current-version compatibility routes\n- current docs search results therefore keep stable unversioned URLs\n- explicit versioned docs pages are excluded from the current-version search index\n- on non-docs pages, the UI defaults docs search filters to the `current` version from `website/data/docs-versions.toml`\n- versions with `searchable = false` are excluded from docs search indexing\n\n## Commands for Runtime Changes\n\nThe most relevant commands when you are changing docs runtime behavior are:\n\n- `npm run docs:validate`: validate docs content, nav data, markers, and inheritance rules\n- The validator checks for:\n\t- both `index.md` and `inherit.md` in the same page folder\n\t- both `_index.md` and `_inherit.md` in the same version, book, or section folder\n\t- missing required page markers in page folders\n\t- missing required `_index.md` or `_inherit.md` in version or book folders\n\t- invalid non-empty inheritance marker files\n\t- inheritance chains that never resolve to real content\n\t- nav entries that point to missing version, book, section, or page paths\n\t- duplicate nav slugs in books, sections, or pages\n\t- legacy identity metadata such as `doc_id` and `product_version`\n\t- disallowed docs front matter such as `aliases`\n- `npm run docs:materialize-inherited`: regenerate transient inherited-route and stable current-route anchors\n- `npm run build`: generate theme assets, validate docs, materialize docs route anchors, and build the site\n- `npm run build:search`: run the full build and then generate the Pagefind search index\n", "0.8": "+++\ntitle = \"Docs Runtime and Route Resolution\"\n+++\n\nThis page covers the implementation-facing side of docs routing.\n\nUse it when you need to answer questions such as:\n\n- which files own docs route resolution\n- how stable current routes differ from explicit versioned routes\n- how inherited pages become routable\n- how version switching and docs search stay version-aware\n\n## Runtime Map\n\nEditors usually work in content and nav files. Web developers also need to know which files own version metadata, build-time validation, and runtime route resolution.\n\n### Content and Navigation Sources\n\nThese files define what the docs tree is supposed to be:\n\n- `website/data/docs-versions.toml`: canonical docs version metadata\n- `website/data/docs-nav/\u003cversion\u003e.toml`: ordered books, sections, and pages\n\nIf the docs UI order looks wrong, or a page exists on disk but not in navigation, these are the first files to check.\n\n### Build and Tooling Scripts\n\nThese scripts keep the docs tree valid and routable:\n\n- `website/scripts/validate-docs-content.py`: validates docs structure, markers, and nav integrity\n- `website/scripts/materialize-inherited-docs.py`: generates transient routable anchors for inherited docs and stable current routes\n- `website/scripts/docs-editor.py`: CLI for creating, deleting, and renaming docs versions, books, sections, and pages safely\n\nIn practice:\n\n- use the validator when you need to confirm content-tree and nav consistency\n- use materialization when testing inheritance or stable-current route behavior\n- use the docs editor for structural changes instead of hand-editing multiple files\n\n### Runtime Template Layer\n\nThese files turn the requested docs URL into the page the user actually sees:\n\n- `website/themes/sambee/layouts/partials/docs/context.html`: derives docs path context from the requested route\n- `website/themes/sambee/layouts/partials/docs/page-path.html`: builds docs content paths with stable-current routing support\n- `website/themes/sambee/layouts/partials/docs/page-url.html`: resolves navigable docs URLs\n- `website/themes/sambee/layouts/partials/docs/source-page.html`: resolves the explicit versioned source page behind stable current routes\n- `website/themes/sambee/layouts/partials/docs/effective-page.html`: resolves the authored page that supplies body content and metadata\n- `website/themes/sambee/layouts/partials/docs/render-data.html`: prepares shared docs render data, including redirect and indexing state\n- `website/themes/sambee/layouts/partials/docs/article-shell.html`: renders the shared docs article shell\n- `website/themes/sambee/layouts/partials/docs/redirect-target.html`: resolves docs entry redirects\n- `website/themes/sambee/layouts/partials/docs/nav-tree.html`: resolves navigation targets and displayed titles\n- `website/themes/sambee/layouts/partials/docs/version-target-url.html`: resolves cross-version switch targets\n- `website/themes/sambee/layouts/partials/search-modal.html`: applies docs-version-aware search behavior\n- `website/themes/sambee/layouts/docs/list.html` and `website/themes/sambee/layouts/docs/single.html`: route docs list and page rendering through the shared shell\n\n### Theme Assets\n\nThese assets shape the visible docs experience once the route and content have been resolved:\n\n- `website/themes/sambee/assets/css/`: shared theme CSS, including docs UI and typography\n\n## Requested Route Versus Effective Page\n\nThe docs runtime keeps requested-path context separate from effective-content resolution.\n\n### Requested Route Context\n\n`website/themes/sambee/layouts/partials/docs/context.html` derives path context from the requested route and returns values including:\n\n- `isDocs`\n- `version`\n- `book`\n- `section`\n- `page`\n- `kind`\n- `currentVersion`\n- `isExplicitVersion`\n- `isCurrentRoute`\n- `isCurrentVersion`\n- convenience booleans: `isDocsRoot`, `isVersion`, `isBook`, `isSection`, and `isPage`\n\nInterpretation rules that matter when changing templates:\n\n- stable current routes such as `/docs/website-dev-guide/...` still resolve to the current version even though the version slug is omitted\n- explicit current-version routes such as `/docs/0.7/...` are compatibility routes and should redirect to stable current routes\n- archived explicit version routes stay routable and render as full docs pages\n\n### Effective Content Resolution\n\n`website/themes/sambee/layouts/partials/docs/effective-page.html` then resolves the authored content source and returns values including:\n\n- `page`: the authored page that should supply title, description, TOC, and body content\n- `requestedPage`: the Hugo page for the requested route\n- `requestedVersion`: the version derived from the route\n- `resolvedVersion`: the version that supplied the effective content\n- `isInherited`: whether the route resolved through inheritance\n\nTemplates should render article content and metadata from `page`, while navigation state, breadcrumbs, and version-switcher state stay tied to the requested route context.\n\n## Why Materialization Exists\n\nHugo needs a concrete page object at the requested path. Raw marker files alone are not enough.\n\nThe build therefore materializes transient route anchors under `.generated/content/docs` so Hugo can route inherited pages and stable current routes without publishing broken `/inherit/` or `/_inherit/` URLs.\n\nFrom Hugo's perspective, `inherit.md` and `_inherit.md` are ordinary content files. If the site consumed them directly, Hugo would try to publish the wrong public URLs.\n\nExample:\n\n- `content/docs/1.1/end-user/getting-started/install/inherit.md` would naturally publish at `/docs/1.1/end-user/getting-started/install/inherit/`\n- `content/docs/1.1/_inherit.md` would naturally publish at `/docs/1.1/_inherit/`\n\nThose are invalid for this docs model. The canonical public URLs must stay attached to the folder path itself:\n\n- `/docs/1.1/end-user/getting-started/install/`\n- `/docs/1.1/`\n\nThat creates a routing gap:\n\n- raw marker files must not become public pages\n- Hugo still needs a real page or section node at the requested folder path so templates can run and the resolver can supply inherited content\n\nThe moving pieces are:\n\n- `website/hugo.toml` ignores raw marker files as direct public pages\n- `website/scripts/materialize-inherited-docs.py` generates transient anchors at the canonical folder paths\n- `website/config/_default/module.toml` mounts `.generated/content` into Hugo's content tree\n- `website/themes/sambee/layouts/partials/docs/effective-page.html` resolves the real authored page that should supply the body, title, description, and TOC\n\nDuring the build, `materialize-inherited-docs.py` does this work:\n\n1. deletes stale generated docs anchors under `website/.generated/content/docs/`\n2. scans `website/content/docs/` for `inherit.md` and `_inherit.md`\n3. generates transient `index.md` or `_index.md` anchors at the matching canonical folder paths under `website/.generated/content/docs/`\n4. generates transient anchors for the declared current version at stable routes under `website/.generated/content/docs/\u003cbook\u003e/...`\n5. marks inherited-route anchors with `inherit = true`\n6. marks stable current-route anchors with `current_route = true` and `source_docs_path = \"/docs/\u003ccurrent\u003e/...\"`\n\nOperational notes:\n\n- `website/.generated/` is build output and is ignored by Git\n- Hugo mounts `.generated/content` into the site content tree during the build\n- Hugo is configured to ignore raw `inherit.md` and `_inherit.md` files\n\nWithout this script, the project would be stuck with two bad options:\n\n- keep raw marker files visible to Hugo and accept broken `/inherit/` and `/_inherit/` URLs\n- ignore marker files and lose the routable page nodes needed to render inherited docs at canonical folder URLs\n\n## Version Switcher Fallback Order\n\nWhen a reader switches from one docs version to another, the target lookup order is:\n\n1. the same page path\n2. the same section landing path\n3. the same book landing path\n4. the target version landing path\n\n## Search Behavior\n\nDocs search is intentionally version-aware.\n\n- Pagefind indexes stable current docs URLs, not explicit current-version compatibility routes\n- current docs search results therefore keep stable unversioned URLs\n- explicit versioned docs pages are excluded from the current-version search index\n- on non-docs pages, the UI defaults docs search filters to the `current` version from `website/data/docs-versions.toml`\n- versions with `searchable = false` are excluded from docs search indexing\n\n## Commands for Runtime Changes\n\nThe most relevant commands when you are changing docs runtime behavior are:\n\n- `npm run docs:validate`: validate docs content, nav data, markers, and inheritance rules\n- The validator checks for:\n\t- both `index.md` and `inherit.md` in the same page folder\n\t- both `_index.md` and `_inherit.md` in the same version, book, or section folder\n\t- missing required page markers in page folders\n\t- missing required `_index.md` or `_inherit.md` in version or book folders\n\t- invalid non-empty inheritance marker files\n\t- inheritance chains that never resolve to real content\n\t- nav entries that point to missing version, book, section, or page paths\n\t- duplicate nav slugs in books, sections, or pages\n\t- legacy identity metadata such as `doc_id` and `product_version`\n\t- disallowed docs front matter such as `aliases`\n- `npm run docs:materialize-inherited`: regenerate transient inherited-route and stable current-route anchors\n- `npm run build`: generate theme assets, validate docs, materialize docs route anchors, and build the site\n- `npm run build:search`: run the full build and then generate the Pagefind search index\n", "0.9": "+++\ntitle = \"Docs Runtime and Route Resolution\"\n+++\n\nThis page covers the implementation-facing side of docs routing.\n\nUse it when you need to answer questions such as:\n\n- which files own docs route resolution\n- how stable current routes differ from explicit versioned routes\n- how inherited pages become routable\n- how version switching and docs search stay version-aware\n\n## Runtime Map\n\nEditors usually work in content and nav files. Web developers also need to know which files own version metadata, build-time validation, and runtime route resolution.\n\n### Content and Navigation Sources\n\nThese files define what the docs tree is supposed to be:\n\n- `website/data/docs-versions.toml`: canonical docs version metadata\n- `website/data/docs-nav/\u003cversion\u003e.toml`: ordered books, sections, and pages\n\nIf the docs UI order looks wrong, or a page exists on disk but not in navigation, these are the first files to check.\n\n### Build and Tooling Scripts\n\nThese scripts keep the docs tree valid and routable:\n\n- `website/scripts/validate-docs-content.py`: validates docs structure, markers, and nav integrity\n- `website/scripts/materialize-inherited-docs.py`: generates transient routable anchors for inherited docs and stable current routes\n- `website/scripts/docs-editor.py`: CLI for creating, deleting, and renaming docs versions, books, sections, and pages safely\n\nIn practice:\n\n- use the validator when you need to confirm content-tree and nav consistency\n- use materialization when testing inheritance or stable-current route behavior\n- use the docs editor for structural changes instead of hand-editing multiple files\n\n### Runtime Template Layer\n\nThese files turn the requested docs URL into the page the user actually sees:\n\n- `website/themes/sambee/layouts/partials/docs/context.html`: derives docs path context from the requested route\n- `website/themes/sambee/layouts/partials/docs/page-path.html`: builds docs content paths with stable-current routing support\n- `website/themes/sambee/layouts/partials/docs/page-url.html`: resolves navigable docs URLs\n- `website/themes/sambee/layouts/partials/docs/source-page.html`: resolves the explicit versioned source page behind stable current routes\n- `website/themes/sambee/layouts/partials/docs/effective-page.html`: resolves the authored page that supplies body content and metadata\n- `website/themes/sambee/layouts/partials/docs/render-data.html`: prepares shared docs render data, including redirect and indexing state\n- `website/themes/sambee/layouts/partials/docs/article-shell.html`: renders the shared docs article shell\n- `website/themes/sambee/layouts/partials/docs/redirect-target.html`: resolves docs entry redirects\n- `website/themes/sambee/layouts/partials/docs/nav-tree.html`: resolves navigation targets and displayed titles\n- `website/themes/sambee/layouts/partials/docs/version-target-url.html`: resolves cross-version switch targets\n- `website/themes/sambee/layouts/partials/search-modal.html`: applies docs-version-aware search behavior\n- `website/themes/sambee/layouts/docs/list.html` and `website/themes/sambee/layouts/docs/single.html`: route docs list and page rendering through the shared shell\n\n### Theme Assets\n\nThese assets shape the visible docs experience once the route and content have been resolved:\n\n- `website/themes/sambee/assets/css/`: shared theme CSS, including docs UI and typography\n\n## Requested Route Versus Effective Page\n\nThe docs runtime keeps requested-path context separate from effective-content resolution.\n\n### Requested Route Context\n\n`website/themes/sambee/layouts/partials/docs/context.html` derives path context from the requested route and returns values including:\n\n- `isDocs`\n- `version`\n- `book`\n- `section`\n- `page`\n- `kind`\n- `currentVersion`\n- `isExplicitVersion`\n- `isCurrentRoute`\n- `isCurrentVersion`\n- convenience booleans: `isDocsRoot`, `isVersion`, `isBook`, `isSection`, and `isPage`\n\nInterpretation rules that matter when changing templates:\n\n- stable current routes such as `/docs/website-dev-guide/...` still resolve to the current version even though the version slug is omitted\n- explicit current-version routes such as `/docs/0.7/...` are compatibility routes and should redirect to stable current routes\n- archived explicit version routes stay routable and render as full docs pages\n\n### Effective Content Resolution\n\n`website/themes/sambee/layouts/partials/docs/effective-page.html` then resolves the authored content source and returns values including:\n\n- `page`: the authored page that should supply title, description, TOC, and body content\n- `requestedPage`: the Hugo page for the requested route\n- `requestedVersion`: the version derived from the route\n- `resolvedVersion`: the version that supplied the effective content\n- `isInherited`: whether the route resolved through inheritance\n\nTemplates should render article content and metadata from `page`, while navigation state, breadcrumbs, and version-switcher state stay tied to the requested route context.\n\n## Why Materialization Exists\n\nHugo needs a concrete page object at the requested path. Raw marker files alone are not enough.\n\nThe build therefore materializes transient route anchors under `.generated/content/docs` so Hugo can route inherited pages and stable current routes without publishing broken `/inherit/` or `/_inherit/` URLs.\n\nFrom Hugo's perspective, `inherit.md` and `_inherit.md` are ordinary content files. If the site consumed them directly, Hugo would try to publish the wrong public URLs.\n\nExample:\n\n- `content/docs/1.1/end-user/getting-started/install/inherit.md` would naturally publish at `/docs/1.1/end-user/getting-started/install/inherit/`\n- `content/docs/1.1/_inherit.md` would naturally publish at `/docs/1.1/_inherit/`\n\nThose are invalid for this docs model. The canonical public URLs must stay attached to the folder path itself:\n\n- `/docs/1.1/end-user/getting-started/install/`\n- `/docs/1.1/`\n\nThat creates a routing gap:\n\n- raw marker files must not become public pages\n- Hugo still needs a real page or section node at the requested folder path so templates can run and the resolver can supply inherited content\n\nThe moving pieces are:\n\n- `website/hugo.toml` ignores raw marker files as direct public pages\n- `website/scripts/materialize-inherited-docs.py` generates transient anchors at the canonical folder paths\n- `website/config/_default/module.toml` mounts `.generated/content` into Hugo's content tree\n- `website/themes/sambee/layouts/partials/docs/effective-page.html` resolves the real authored page that should supply the body, title, description, and TOC\n\nDuring the build, `materialize-inherited-docs.py` does this work:\n\n1. deletes stale generated docs anchors under `website/.generated/content/docs/`\n2. scans `website/content/docs/` for `inherit.md` and `_inherit.md`\n3. generates transient `index.md` or `_index.md` anchors at the matching canonical folder paths under `website/.generated/content/docs/`\n4. generates transient anchors for the declared current version at stable routes under `website/.generated/content/docs/\u003cbook\u003e/...`\n5. marks inherited-route anchors with `inherit = true`\n6. marks stable current-route anchors with `current_route = true` and `source_docs_path = \"/docs/\u003ccurrent\u003e/...\"`\n\nOperational notes:\n\n- `website/.generated/` is build output and is ignored by Git\n- Hugo mounts `.generated/content` into the site content tree during the build\n- Hugo is configured to ignore raw `inherit.md` and `_inherit.md` files\n\nWithout this script, the project would be stuck with two bad options:\n\n- keep raw marker files visible to Hugo and accept broken `/inherit/` and `/_inherit/` URLs\n- ignore marker files and lose the routable page nodes needed to render inherited docs at canonical folder URLs\n\n## Version Switcher Fallback Order\n\nWhen a reader switches from one docs version to another, the target lookup order is:\n\n1. the same page path\n2. the same section landing path\n3. the same book landing path\n4. the target version landing path\n\n## Search Behavior\n\nDocs search is intentionally version-aware.\n\n- Pagefind indexes stable current docs URLs, not explicit current-version compatibility routes\n- current docs search results therefore keep stable unversioned URLs\n- explicit versioned docs pages are excluded from the current-version search index\n- on non-docs pages, the UI defaults docs search filters to the `current` version from `website/data/docs-versions.toml`\n- versions with `searchable = false` are excluded from docs search indexing\n\n## Commands for Runtime Changes\n\nThe most relevant commands when you are changing docs runtime behavior are:\n\n- `npm run docs:validate`: validate docs content, nav data, markers, and inheritance rules\n- The validator checks for:\n\t- both `index.md` and `inherit.md` in the same page folder\n\t- both `_index.md` and `_inherit.md` in the same version, book, or section folder\n\t- missing required page markers in page folders\n\t- missing required `_index.md` or `_inherit.md` in version or book folders\n\t- invalid non-empty inheritance marker files\n\t- inheritance chains that never resolve to real content\n\t- nav entries that point to missing version, book, section, or page paths\n\t- duplicate nav slugs in books, sections, or pages\n\t- legacy identity metadata such as `doc_id` and `product_version`\n\t- disallowed docs front matter such as `aliases`\n- `npm run docs:materialize-inherited`: regenerate transient inherited-route and stable current-route anchors\n- `npm run build`: generate theme assets, validate docs, materialize docs route anchors, and build the site\n- `npm run build:search`: run the full build and then generate the Pagefind search index\n", "1.0": "+++\ntitle = \"Docs Runtime and Route Resolution\"\n+++\n\nThis page covers the implementation-facing side of docs routing.\n\nUse it when you need to answer questions such as:\n\n- which files own docs route resolution\n- how stable current routes differ from explicit versioned routes\n- how inherited pages become routable\n- how version switching and docs search stay version-aware\n\n## Runtime Map\n\nEditors usually work in content and nav files. Web developers also need to know which files own version metadata, build-time validation, and runtime route resolution.\n\n### Content and Navigation Sources\n\nThese files define what the docs tree is supposed to be:\n\n- `website/data/docs-versions.toml`: canonical docs version metadata\n- `website/data/docs-nav/\u003cversion\u003e.toml`: ordered books, sections, and pages\n\nIf the docs UI order looks wrong, or a page exists on disk but not in navigation, these are the first files to check.\n\n### Build and Tooling Scripts\n\nThese scripts keep the docs tree valid and routable:\n\n- `website/scripts/validate-docs-content.py`: validates docs structure, markers, and nav integrity\n- `website/scripts/materialize-inherited-docs.py`: generates transient routable anchors for inherited docs and stable current routes\n- `website/scripts/docs-editor.py`: CLI for creating, deleting, and renaming docs versions, books, sections, and pages safely\n\nIn practice:\n\n- use the validator when you need to confirm content-tree and nav consistency\n- use materialization when testing inheritance or stable-current route behavior\n- use the docs editor for structural changes instead of hand-editing multiple files\n\n### Runtime Template Layer\n\nThese files turn the requested docs URL into the page the user actually sees:\n\n- `website/themes/sambee/layouts/partials/docs/context.html`: derives docs path context from the requested route\n- `website/themes/sambee/layouts/partials/docs/page-path.html`: builds docs content paths with stable-current routing support\n- `website/themes/sambee/layouts/partials/docs/page-url.html`: resolves navigable docs URLs\n- `website/themes/sambee/layouts/partials/docs/source-page.html`: resolves the explicit versioned source page behind stable current routes\n- `website/themes/sambee/layouts/partials/docs/effective-page.html`: resolves the authored page that supplies body content and metadata\n- `website/themes/sambee/layouts/partials/docs/render-data.html`: prepares shared docs render data, including redirect and indexing state\n- `website/themes/sambee/layouts/partials/docs/article-shell.html`: renders the shared docs article shell\n- `website/themes/sambee/layouts/partials/docs/redirect-target.html`: resolves docs entry redirects\n- `website/themes/sambee/layouts/partials/docs/nav-tree.html`: resolves navigation targets and displayed titles\n- `website/themes/sambee/layouts/partials/docs/version-target-url.html`: resolves cross-version switch targets\n- `website/themes/sambee/layouts/partials/search-modal.html`: applies docs-version-aware search behavior\n- `website/themes/sambee/layouts/docs/list.html` and `website/themes/sambee/layouts/docs/single.html`: route docs list and page rendering through the shared shell\n\n### Theme Assets\n\nThese assets shape the visible docs experience once the route and content have been resolved:\n\n- `website/themes/sambee/assets/css/`: shared theme CSS, including docs UI and typography\n\n## Requested Route Versus Effective Page\n\nThe docs runtime keeps requested-path context separate from effective-content resolution.\n\n### Requested Route Context\n\n`website/themes/sambee/layouts/partials/docs/context.html` derives path context from the requested route and returns values including:\n\n- `isDocs`\n- `version`\n- `book`\n- `section`\n- `page`\n- `kind`\n- `currentVersion`\n- `isExplicitVersion`\n- `isCurrentRoute`\n- `isCurrentVersion`\n- convenience booleans: `isDocsRoot`, `isVersion`, `isBook`, `isSection`, and `isPage`\n\nInterpretation rules that matter when changing templates:\n\n- stable current routes such as `/docs/website-dev-guide/...` still resolve to the current version even though the version slug is omitted\n- explicit current-version routes such as `/docs/0.7/...` are compatibility routes and should redirect to stable current routes\n- archived explicit version routes stay routable and render as full docs pages\n\n### Effective Content Resolution\n\n`website/themes/sambee/layouts/partials/docs/effective-page.html` then resolves the authored content source and returns values including:\n\n- `page`: the authored page that should supply title, description, TOC, and body content\n- `requestedPage`: the Hugo page for the requested route\n- `requestedVersion`: the version derived from the route\n- `resolvedVersion`: the version that supplied the effective content\n- `isInherited`: whether the route resolved through inheritance\n\nTemplates should render article content and metadata from `page`, while navigation state, breadcrumbs, and version-switcher state stay tied to the requested route context.\n\n## Why Materialization Exists\n\nHugo needs a concrete page object at the requested path. Raw marker files alone are not enough.\n\nThe build therefore materializes transient route anchors under `.generated/content/docs` so Hugo can route inherited pages and stable current routes without publishing broken `/inherit/` or `/_inherit/` URLs.\n\nFrom Hugo's perspective, `inherit.md` and `_inherit.md` are ordinary content files. If the site consumed them directly, Hugo would try to publish the wrong public URLs.\n\nExample:\n\n- `content/docs/1.1/end-user/getting-started/install/inherit.md` would naturally publish at `/docs/1.1/end-user/getting-started/install/inherit/`\n- `content/docs/1.1/_inherit.md` would naturally publish at `/docs/1.1/_inherit/`\n\nThose are invalid for this docs model. The canonical public URLs must stay attached to the folder path itself:\n\n- `/docs/1.1/end-user/getting-started/install/`\n- `/docs/1.1/`\n\nThat creates a routing gap:\n\n- raw marker files must not become public pages\n- Hugo still needs a real page or section node at the requested folder path so templates can run and the resolver can supply inherited content\n\nThe moving pieces are:\n\n- `website/hugo.toml` ignores raw marker files as direct public pages\n- `website/scripts/materialize-inherited-docs.py` generates transient anchors at the canonical folder paths\n- `website/config/_default/module.toml` mounts `.generated/content` into Hugo's content tree\n- `website/themes/sambee/layouts/partials/docs/effective-page.html` resolves the real authored page that should supply the body, title, description, and TOC\n\nDuring the build, `materialize-inherited-docs.py` does this work:\n\n1. deletes stale generated docs anchors under `website/.generated/content/docs/`\n2. scans `website/content/docs/` for `inherit.md` and `_inherit.md`\n3. generates transient `index.md` or `_index.md` anchors at the matching canonical folder paths under `website/.generated/content/docs/`\n4. generates transient anchors for the declared current version at stable routes under `website/.generated/content/docs/\u003cbook\u003e/...`\n5. marks inherited-route anchors with `inherit = true`\n6. marks stable current-route anchors with `current_route = true` and `source_docs_path = \"/docs/\u003ccurrent\u003e/...\"`\n\nOperational notes:\n\n- `website/.generated/` is build output and is ignored by Git\n- Hugo mounts `.generated/content` into the site content tree during the build\n- Hugo is configured to ignore raw `inherit.md` and `_inherit.md` files\n\nWithout this script, the project would be stuck with two bad options:\n\n- keep raw marker files visible to Hugo and accept broken `/inherit/` and `/_inherit/` URLs\n- ignore marker files and lose the routable page nodes needed to render inherited docs at canonical folder URLs\n\n## Version Switcher Fallback Order\n\nWhen a reader switches from one docs version to another, the target lookup order is:\n\n1. the same page path\n2. the same section landing path\n3. the same book landing path\n4. the target version landing path\n\n## Search Behavior\n\nDocs search is intentionally version-aware.\n\n- Pagefind indexes stable current docs URLs, not explicit current-version compatibility routes\n- current docs search results therefore keep stable unversioned URLs\n- explicit versioned docs pages are excluded from the current-version search index\n- on non-docs pages, the UI defaults docs search filters to the `current` version from `website/data/docs-versions.toml`\n- versions with `searchable = false` are excluded from docs search indexing\n\n## Commands for Runtime Changes\n\nThe most relevant commands when you are changing docs runtime behavior are:\n\n- `npm run docs:validate`: validate docs content, nav data, markers, and inheritance rules\n- The validator checks for:\n\t- both `index.md` and `inherit.md` in the same page folder\n\t- both `_index.md` and `_inherit.md` in the same version, book, or section folder\n\t- missing required page markers in page folders\n\t- missing required `_index.md` or `_inherit.md` in version or book folders\n\t- invalid non-empty inheritance marker files\n\t- inheritance chains that never resolve to real content\n\t- nav entries that point to missing version, book, section, or page paths\n\t- duplicate nav slugs in books, sections, or pages\n\t- legacy identity metadata such as `doc_id` and `product_version`\n\t- disallowed docs front matter such as `aliases`\n- `npm run docs:materialize-inherited`: regenerate transient inherited-route and stable current-route anchors\n- `npm run build`: generate theme assets, validate docs, materialize docs route anchors, and build the site\n- `npm run build:search`: run the full build and then generate the Pagefind search index\n", "2.0": "+++\ntitle = \"Docs Runtime and Route Resolution\"\n+++\n\nThis page covers the implementation-facing side of docs routing.\n\nUse it when you need to answer questions such as:\n\n- which files own docs route resolution\n- how stable current routes differ from explicit versioned routes\n- how inherited pages become routable\n- how version switching and docs search stay version-aware\n\n## Runtime Map\n\nEditors usually work in content and nav files. Web developers also need to know which files own version metadata, build-time validation, and runtime route resolution.\n\n### Content and Navigation Sources\n\nThese files define what the docs tree is supposed to be:\n\n- `website/data/docs-versions.toml`: canonical docs version metadata\n- `website/data/docs-nav/\u003cversion\u003e.toml`: ordered books, sections, and pages\n\nIf the docs UI order looks wrong, or a page exists on disk but not in navigation, these are the first files to check.\n\n### Build and Tooling Scripts\n\nThese scripts keep the docs tree valid and routable:\n\n- `website/scripts/validate-docs-content.py`: validates docs structure, markers, and nav integrity\n- `website/scripts/materialize-inherited-docs.py`: generates transient routable anchors for inherited docs and stable current routes\n- `website/scripts/docs-editor.py`: CLI for creating, deleting, and renaming docs versions, books, sections, and pages safely\n\nIn practice:\n\n- use the validator when you need to confirm content-tree and nav consistency\n- use materialization when testing inheritance or stable-current route behavior\n- use the docs editor for structural changes instead of hand-editing multiple files\n\n### Runtime Template Layer\n\nThese files turn the requested docs URL into the page the user actually sees:\n\n- `website/themes/sambee/layouts/partials/docs/context.html`: derives docs path context from the requested route\n- `website/themes/sambee/layouts/partials/docs/page-path.html`: builds docs content paths with stable-current routing support\n- `website/themes/sambee/layouts/partials/docs/page-url.html`: resolves navigable docs URLs\n- `website/themes/sambee/layouts/partials/docs/source-page.html`: resolves the explicit versioned source page behind stable current routes\n- `website/themes/sambee/layouts/partials/docs/effective-page.html`: resolves the authored page that supplies body content and metadata\n- `website/themes/sambee/layouts/partials/docs/render-data.html`: prepares shared docs render data, including redirect and indexing state\n- `website/themes/sambee/layouts/partials/docs/article-shell.html`: renders the shared docs article shell\n- `website/themes/sambee/layouts/partials/docs/redirect-target.html`: resolves docs entry redirects\n- `website/themes/sambee/layouts/partials/docs/nav-tree.html`: resolves navigation targets and displayed titles\n- `website/themes/sambee/layouts/partials/docs/version-target-url.html`: resolves cross-version switch targets\n- `website/themes/sambee/layouts/partials/search-modal.html`: applies docs-version-aware search behavior\n- `website/themes/sambee/layouts/docs/list.html` and `website/themes/sambee/layouts/docs/single.html`: route docs list and page rendering through the shared shell\n\n### Theme Assets\n\nThese assets shape the visible docs experience once the route and content have been resolved:\n\n- `website/themes/sambee/assets/css/`: shared theme CSS, including docs UI and typography\n\n## Requested Route Versus Effective Page\n\nThe docs runtime keeps requested-path context separate from effective-content resolution.\n\n### Requested Route Context\n\n`website/themes/sambee/layouts/partials/docs/context.html` derives path context from the requested route and returns values including:\n\n- `isDocs`\n- `version`\n- `book`\n- `section`\n- `page`\n- `kind`\n- `currentVersion`\n- `isExplicitVersion`\n- `isCurrentRoute`\n- `isCurrentVersion`\n- convenience booleans: `isDocsRoot`, `isVersion`, `isBook`, `isSection`, and `isPage`\n\nInterpretation rules that matter when changing templates:\n\n- stable current routes such as `/docs/website-dev-guide/...` still resolve to the current version even though the version slug is omitted\n- explicit current-version routes such as `/docs/0.7/...` are compatibility routes and should redirect to stable current routes\n- archived explicit version routes stay routable and render as full docs pages\n\n### Effective Content Resolution\n\n`website/themes/sambee/layouts/partials/docs/effective-page.html` then resolves the authored content source and returns values including:\n\n- `page`: the authored page that should supply title, description, TOC, and body content\n- `requestedPage`: the Hugo page for the requested route\n- `requestedVersion`: the version derived from the route\n- `resolvedVersion`: the version that supplied the effective content\n- `isInherited`: whether the route resolved through inheritance\n\nTemplates should render article content and metadata from `page`, while navigation state, breadcrumbs, and version-switcher state stay tied to the requested route context.\n\n## Why Materialization Exists\n\nHugo needs a concrete page object at the requested path. Raw marker files alone are not enough.\n\nThe build therefore materializes transient route anchors under `.generated/content/docs` so Hugo can route inherited pages and stable current routes without publishing broken `/inherit/` or `/_inherit/` URLs.\n\nFrom Hugo's perspective, `inherit.md` and `_inherit.md` are ordinary content files. If the site consumed them directly, Hugo would try to publish the wrong public URLs.\n\nExample:\n\n- `content/docs/1.1/end-user/getting-started/install/inherit.md` would naturally publish at `/docs/1.1/end-user/getting-started/install/inherit/`\n- `content/docs/1.1/_inherit.md` would naturally publish at `/docs/1.1/_inherit/`\n\nThose are invalid for this docs model. The canonical public URLs must stay attached to the folder path itself:\n\n- `/docs/1.1/end-user/getting-started/install/`\n- `/docs/1.1/`\n\nThat creates a routing gap:\n\n- raw marker files must not become public pages\n- Hugo still needs a real page or section node at the requested folder path so templates can run and the resolver can supply inherited content\n\nThe moving pieces are:\n\n- `website/hugo.toml` ignores raw marker files as direct public pages\n- `website/scripts/materialize-inherited-docs.py` generates transient anchors at the canonical folder paths\n- `website/config/_default/module.toml` mounts `.generated/content` into Hugo's content tree\n- `website/themes/sambee/layouts/partials/docs/effective-page.html` resolves the real authored page that should supply the body, title, description, and TOC\n\nDuring the build, `materialize-inherited-docs.py` does this work:\n\n1. deletes stale generated docs anchors under `website/.generated/content/docs/`\n2. scans `website/content/docs/` for `inherit.md` and `_inherit.md`\n3. generates transient `index.md` or `_index.md` anchors at the matching canonical folder paths under `website/.generated/content/docs/`\n4. generates transient anchors for the declared current version at stable routes under `website/.generated/content/docs/\u003cbook\u003e/...`\n5. marks inherited-route anchors with `inherit = true`\n6. marks stable current-route anchors with `current_route = true` and `source_docs_path = \"/docs/\u003ccurrent\u003e/...\"`\n\nOperational notes:\n\n- `website/.generated/` is build output and is ignored by Git\n- Hugo mounts `.generated/content` into the site content tree during the build\n- Hugo is configured to ignore raw `inherit.md` and `_inherit.md` files\n\nWithout this script, the project would be stuck with two bad options:\n\n- keep raw marker files visible to Hugo and accept broken `/inherit/` and `/_inherit/` URLs\n- ignore marker files and lose the routable page nodes needed to render inherited docs at canonical folder URLs\n\n## Version Switcher Fallback Order\n\nWhen a reader switches from one docs version to another, the target lookup order is:\n\n1. the same page path\n2. the same section landing path\n3. the same book landing path\n4. the target version landing path\n\n## Search Behavior\n\nDocs search is intentionally version-aware.\n\n- Pagefind indexes stable current docs URLs, not explicit current-version compatibility routes\n- current docs search results therefore keep stable unversioned URLs\n- explicit versioned docs pages are excluded from the current-version search index\n- on non-docs pages, the UI defaults docs search filters to the `current` version from `website/data/docs-versions.toml`\n- versions with `searchable = false` are excluded from docs search indexing\n\n## Commands for Runtime Changes\n\nThe most relevant commands when you are changing docs runtime behavior are:\n\n- `npm run docs:validate`: validate docs content, nav data, markers, and inheritance rules\n- The validator checks for:\n\t- both `index.md` and `inherit.md` in the same page folder\n\t- both `_index.md` and `_inherit.md` in the same version, book, or section folder\n\t- missing required page markers in page folders\n\t- missing required `_index.md` or `_inherit.md` in version or book folders\n\t- invalid non-empty inheritance marker files\n\t- inheritance chains that never resolve to real content\n\t- nav entries that point to missing version, book, section, or page paths\n\t- duplicate nav slugs in books, sections, or pages\n\t- legacy identity metadata such as `doc_id` and `product_version`\n\t- disallowed docs front matter such as `aliases`\n- `npm run docs:materialize-inherited`: regenerate transient inherited-route and stable current-route anchors\n- `npm run build`: generate theme assets, validate docs, materialize docs route anchors, and build the site\n- `npm run build:search`: run the full build and then generate the Pagefind search index\n"}, "page_contents": {"0.7": "+++\ntitle = \"Docs Runtime and Route Resolution\"\n+++\n\nThis page covers the implementation-facing side of docs routing.\n\nUse it when you need to answer questions such as:\n\n- which files own docs route resolution\n- how stable current routes differ from explicit versioned routes\n- how inherited pages become routable\n- how version switching and docs search stay version-aware\n\n## Runtime Map\n\nEditors usually work in content and nav files. Web developers also need to know which files own version metadata, build-time validation, and runtime route resolution.\n\n### Content and Navigation Sources\n\nThese files define what the docs tree is supposed to be:\n\n- `website/data/docs-versions.toml`: canonical docs version metadata\n- `website/data/docs-nav/\u003cversion\u003e.toml`: ordered books, sections, and pages\n\nIf the docs UI order looks wrong, or a page exists on disk but not in navigation, these are the first files to check.\n\n### Build and Tooling Scripts\n\nThese scripts keep the docs tree valid and routable:\n\n- `website/scripts/validate-docs-content.py`: validates docs structure, markers, and nav integrity\n- `website/scripts/materialize-inherited-docs.py`: generates transient routable anchors for inherited docs and stable current routes\n- `website/scripts/docs-editor.py`: CLI for creating, deleting, and renaming docs versions, books, sections, and pages safely\n\nIn practice:\n\n- use the validator when you need to confirm content-tree and nav consistency\n- use materialization when testing inheritance or stable-current route behavior\n- use the docs editor for structural changes instead of hand-editing multiple files\n\n### Runtime Template Layer\n\nThese files turn the requested docs URL into the page the user actually sees:\n\n- `website/themes/sambee/layouts/partials/docs/context.html`: derives docs path context from the requested route\n- `website/themes/sambee/layouts/partials/docs/page-path.html`: builds docs content paths with stable-current routing support\n- `website/themes/sambee/layouts/partials/docs/page-url.html`: resolves navigable docs URLs\n- `website/themes/sambee/layouts/partials/docs/source-page.html`: resolves the explicit versioned source page behind stable current routes\n- `website/themes/sambee/layouts/partials/docs/effective-page.html`: resolves the authored page that supplies body content and metadata\n- `website/themes/sambee/layouts/partials/docs/render-data.html`: prepares shared docs render data, including redirect and indexing state\n- `website/themes/sambee/layouts/partials/docs/article-shell.html`: renders the shared docs article shell\n- `website/themes/sambee/layouts/partials/docs/redirect-target.html`: resolves docs entry redirects\n- `website/themes/sambee/layouts/partials/docs/nav-tree.html`: resolves navigation targets and displayed titles\n- `website/themes/sambee/layouts/partials/docs/version-target-url.html`: resolves cross-version switch targets\n- `website/themes/sambee/layouts/partials/search-modal.html`: applies docs-version-aware search behavior\n- `website/themes/sambee/layouts/docs/list.html` and `website/themes/sambee/layouts/docs/single.html`: route docs list and page rendering through the shared shell\n\n### Theme Assets\n\nThese assets shape the visible docs experience once the route and content have been resolved:\n\n- `website/themes/sambee/assets/css/`: shared theme CSS, including docs UI and typography\n\n## Requested Route Versus Effective Page\n\nThe docs runtime keeps requested-path context separate from effective-content resolution.\n\n### Requested Route Context\n\n`website/themes/sambee/layouts/partials/docs/context.html` derives path context from the requested route and returns values including:\n\n- `isDocs`\n- `version`\n- `book`\n- `section`\n- `page`\n- `kind`\n- `currentVersion`\n- `isExplicitVersion`\n- `isCurrentRoute`\n- `isCurrentVersion`\n- convenience booleans: `isDocsRoot`, `isVersion`, `isBook`, `isSection`, and `isPage`\n\nInterpretation rules that matter when changing templates:\n\n- stable current routes such as `/docs/website-dev-guide/...` still resolve to the current version even though the version slug is omitted\n- explicit current-version routes such as `/docs/0.7/...` are compatibility routes and should redirect to stable current routes\n- archived explicit version routes stay routable and render as full docs pages\n\n### Effective Content Resolution\n\n`website/themes/sambee/layouts/partials/docs/effective-page.html` then resolves the authored content source and returns values including:\n\n- `page`: the authored page that should supply title, description, TOC, and body content\n- `requestedPage`: the Hugo page for the requested route\n- `requestedVersion`: the version derived from the route\n- `resolvedVersion`: the version that supplied the effective content\n- `isInherited`: whether the route resolved through inheritance\n\nTemplates should render article content and metadata from `page`, while navigation state, breadcrumbs, and version-switcher state stay tied to the requested route context.\n\n## Why Materialization Exists\n\nHugo needs a concrete page object at the requested path. Raw marker files alone are not enough.\n\nThe build therefore materializes transient route anchors under `.generated/content/docs` so Hugo can route inherited pages and stable current routes without publishing broken `/inherit/` or `/_inherit/` URLs.\n\nFrom Hugo's perspective, `inherit.md` and `_inherit.md` are ordinary content files. If the site consumed them directly, Hugo would try to publish the wrong public URLs.\n\nExample:\n\n- `content/docs/1.1/end-user/getting-started/install/inherit.md` would naturally publish at `/docs/1.1/end-user/getting-started/install/inherit/`\n- `content/docs/1.1/_inherit.md` would naturally publish at `/docs/1.1/_inherit/`\n\nThose are invalid for this docs model. The canonical public URLs must stay attached to the folder path itself:\n\n- `/docs/1.1/end-user/getting-started/install/`\n- `/docs/1.1/`\n\nThat creates a routing gap:\n\n- raw marker files must not become public pages\n- Hugo still needs a real page or section node at the requested folder path so templates can run and the resolver can supply inherited content\n\nThe moving pieces are:\n\n- `website/hugo.toml` ignores raw marker files as direct public pages\n- `website/scripts/materialize-inherited-docs.py` generates transient anchors at the canonical folder paths\n- `website/config/_default/module.toml` mounts `.generated/content` into Hugo's content tree\n- `website/themes/sambee/layouts/partials/docs/effective-page.html` resolves the real authored page that should supply the body, title, description, and TOC\n\nDuring the build, `materialize-inherited-docs.py` does this work:\n\n1. deletes stale generated docs anchors under `website/.generated/content/docs/`\n2. scans `website/content/docs/` for `inherit.md` and `_inherit.md`\n3. generates transient `index.md` or `_index.md` anchors at the matching canonical folder paths under `website/.generated/content/docs/`\n4. generates transient anchors for the declared current version at stable routes under `website/.generated/content/docs/\u003cbook\u003e/...`\n5. marks inherited-route anchors with `inherit = true`\n6. marks stable current-route anchors with `current_route = true` and `source_docs_path = \"/docs/\u003ccurrent\u003e/...\"`\n\nOperational notes:\n\n- `website/.generated/` is build output and is ignored by Git\n- Hugo mounts `.generated/content` into the site content tree during the build\n- Hugo is configured to ignore raw `inherit.md` and `_inherit.md` files\n\nWithout this script, the project would be stuck with two bad options:\n\n- keep raw marker files visible to Hugo and accept broken `/inherit/` and `/_inherit/` URLs\n- ignore marker files and lose the routable page nodes needed to render inherited docs at canonical folder URLs\n\n## Version Switcher Fallback Order\n\nWhen a reader switches from one docs version to another, the target lookup order is:\n\n1. the same page path\n2. the same section landing path\n3. the same book landing path\n4. the target version landing path\n\n## Search Behavior\n\nDocs search is intentionally version-aware.\n\n- Pagefind indexes stable current docs URLs, not explicit current-version compatibility routes\n- current docs search results therefore keep stable unversioned URLs\n- explicit versioned docs pages are excluded from the current-version search index\n- on non-docs pages, the UI defaults docs search filters to the `current` version from `website/data/docs-versions.toml`\n- versions with `searchable = false` are excluded from docs search indexing\n\n## Commands for Runtime Changes\n\nThe most relevant commands when you are changing docs runtime behavior are:\n\n- `npm run docs:validate`: validate docs content, nav data, markers, and inheritance rules\n- The validator checks for:\n\t- both `index.md` and `inherit.md` in the same page folder\n\t- both `_index.md` and `_inherit.md` in the same version, book, or section folder\n\t- missing required page markers in page folders\n\t- missing required `_index.md` or `_inherit.md` in version or book folders\n\t- invalid non-empty inheritance marker files\n\t- inheritance chains that never resolve to real content\n\t- nav entries that point to missing version, book, section, or page paths\n\t- duplicate nav slugs in books, sections, or pages\n\t- legacy identity metadata such as `doc_id` and `product_version`\n\t- disallowed docs front matter such as `aliases`\n- `npm run docs:materialize-inherited`: regenerate transient inherited-route and stable current-route anchors\n- `npm run build`: generate theme assets, validate docs, materialize docs route anchors, and build the site\n- `npm run build:search`: run the full build and then generate the Pagefind search index\n", "0.8": "+++\ntitle = \"Docs Runtime and Route Resolution\"\n+++\n\nThis page covers the implementation-facing side of docs routing.\n\nUse it when you need to answer questions such as:\n\n- which files own docs route resolution\n- how stable current routes differ from explicit versioned routes\n- how inherited pages become routable\n- how version switching and docs search stay version-aware\n\n## Runtime Map\n\nEditors usually work in content and nav files. Web developers also need to know which files own version metadata, build-time validation, and runtime route resolution.\n\n### Content and Navigation Sources\n\nThese files define what the docs tree is supposed to be:\n\n- `website/data/docs-versions.toml`: canonical docs version metadata\n- `website/data/docs-nav/\u003cversion\u003e.toml`: ordered books, sections, and pages\n\nIf the docs UI order looks wrong, or a page exists on disk but not in navigation, these are the first files to check.\n\n### Build and Tooling Scripts\n\nThese scripts keep the docs tree valid and routable:\n\n- `website/scripts/validate-docs-content.py`: validates docs structure, markers, and nav integrity\n- `website/scripts/materialize-inherited-docs.py`: generates transient routable anchors for inherited docs and stable current routes\n- `website/scripts/docs-editor.py`: CLI for creating, deleting, and renaming docs versions, books, sections, and pages safely\n\nIn practice:\n\n- use the validator when you need to confirm content-tree and nav consistency\n- use materialization when testing inheritance or stable-current route behavior\n- use the docs editor for structural changes instead of hand-editing multiple files\n\n### Runtime Template Layer\n\nThese files turn the requested docs URL into the page the user actually sees:\n\n- `website/themes/sambee/layouts/partials/docs/context.html`: derives docs path context from the requested route\n- `website/themes/sambee/layouts/partials/docs/page-path.html`: builds docs content paths with stable-current routing support\n- `website/themes/sambee/layouts/partials/docs/page-url.html`: resolves navigable docs URLs\n- `website/themes/sambee/layouts/partials/docs/source-page.html`: resolves the explicit versioned source page behind stable current routes\n- `website/themes/sambee/layouts/partials/docs/effective-page.html`: resolves the authored page that supplies body content and metadata\n- `website/themes/sambee/layouts/partials/docs/render-data.html`: prepares shared docs render data, including redirect and indexing state\n- `website/themes/sambee/layouts/partials/docs/article-shell.html`: renders the shared docs article shell\n- `website/themes/sambee/layouts/partials/docs/redirect-target.html`: resolves docs entry redirects\n- `website/themes/sambee/layouts/partials/docs/nav-tree.html`: resolves navigation targets and displayed titles\n- `website/themes/sambee/layouts/partials/docs/version-target-url.html`: resolves cross-version switch targets\n- `website/themes/sambee/layouts/partials/search-modal.html`: applies docs-version-aware search behavior\n- `website/themes/sambee/layouts/docs/list.html` and `website/themes/sambee/layouts/docs/single.html`: route docs list and page rendering through the shared shell\n\n### Theme Assets\n\nThese assets shape the visible docs experience once the route and content have been resolved:\n\n- `website/themes/sambee/assets/css/`: shared theme CSS, including docs UI and typography\n\n## Requested Route Versus Effective Page\n\nThe docs runtime keeps requested-path context separate from effective-content resolution.\n\n### Requested Route Context\n\n`website/themes/sambee/layouts/partials/docs/context.html` derives path context from the requested route and returns values including:\n\n- `isDocs`\n- `version`\n- `book`\n- `section`\n- `page`\n- `kind`\n- `currentVersion`\n- `isExplicitVersion`\n- `isCurrentRoute`\n- `isCurrentVersion`\n- convenience booleans: `isDocsRoot`, `isVersion`, `isBook`, `isSection`, and `isPage`\n\nInterpretation rules that matter when changing templates:\n\n- stable current routes such as `/docs/website-dev-guide/...` still resolve to the current version even though the version slug is omitted\n- explicit current-version routes such as `/docs/0.7/...` are compatibility routes and should redirect to stable current routes\n- archived explicit version routes stay routable and render as full docs pages\n\n### Effective Content Resolution\n\n`website/themes/sambee/layouts/partials/docs/effective-page.html` then resolves the authored content source and returns values including:\n\n- `page`: the authored page that should supply title, description, TOC, and body content\n- `requestedPage`: the Hugo page for the requested route\n- `requestedVersion`: the version derived from the route\n- `resolvedVersion`: the version that supplied the effective content\n- `isInherited`: whether the route resolved through inheritance\n\nTemplates should render article content and metadata from `page`, while navigation state, breadcrumbs, and version-switcher state stay tied to the requested route context.\n\n## Why Materialization Exists\n\nHugo needs a concrete page object at the requested path. Raw marker files alone are not enough.\n\nThe build therefore materializes transient route anchors under `.generated/content/docs` so Hugo can route inherited pages and stable current routes without publishing broken `/inherit/` or `/_inherit/` URLs.\n\nFrom Hugo's perspective, `inherit.md` and `_inherit.md` are ordinary content files. If the site consumed them directly, Hugo would try to publish the wrong public URLs.\n\nExample:\n\n- `content/docs/1.1/end-user/getting-started/install/inherit.md` would naturally publish at `/docs/1.1/end-user/getting-started/install/inherit/`\n- `content/docs/1.1/_inherit.md` would naturally publish at `/docs/1.1/_inherit/`\n\nThose are invalid for this docs model. The canonical public URLs must stay attached to the folder path itself:\n\n- `/docs/1.1/end-user/getting-started/install/`\n- `/docs/1.1/`\n\nThat creates a routing gap:\n\n- raw marker files must not become public pages\n- Hugo still needs a real page or section node at the requested folder path so templates can run and the resolver can supply inherited content\n\nThe moving pieces are:\n\n- `website/hugo.toml` ignores raw marker files as direct public pages\n- `website/scripts/materialize-inherited-docs.py` generates transient anchors at the canonical folder paths\n- `website/config/_default/module.toml` mounts `.generated/content` into Hugo's content tree\n- `website/themes/sambee/layouts/partials/docs/effective-page.html` resolves the real authored page that should supply the body, title, description, and TOC\n\nDuring the build, `materialize-inherited-docs.py` does this work:\n\n1. deletes stale generated docs anchors under `website/.generated/content/docs/`\n2. scans `website/content/docs/` for `inherit.md` and `_inherit.md`\n3. generates transient `index.md` or `_index.md` anchors at the matching canonical folder paths under `website/.generated/content/docs/`\n4. generates transient anchors for the declared current version at stable routes under `website/.generated/content/docs/\u003cbook\u003e/...`\n5. marks inherited-route anchors with `inherit = true`\n6. marks stable current-route anchors with `current_route = true` and `source_docs_path = \"/docs/\u003ccurrent\u003e/...\"`\n\nOperational notes:\n\n- `website/.generated/` is build output and is ignored by Git\n- Hugo mounts `.generated/content` into the site content tree during the build\n- Hugo is configured to ignore raw `inherit.md` and `_inherit.md` files\n\nWithout this script, the project would be stuck with two bad options:\n\n- keep raw marker files visible to Hugo and accept broken `/inherit/` and `/_inherit/` URLs\n- ignore marker files and lose the routable page nodes needed to render inherited docs at canonical folder URLs\n\n## Version Switcher Fallback Order\n\nWhen a reader switches from one docs version to another, the target lookup order is:\n\n1. the same page path\n2. the same section landing path\n3. the same book landing path\n4. the target version landing path\n\n## Search Behavior\n\nDocs search is intentionally version-aware.\n\n- Pagefind indexes stable current docs URLs, not explicit current-version compatibility routes\n- current docs search results therefore keep stable unversioned URLs\n- explicit versioned docs pages are excluded from the current-version search index\n- on non-docs pages, the UI defaults docs search filters to the `current` version from `website/data/docs-versions.toml`\n- versions with `searchable = false` are excluded from docs search indexing\n\n## Commands for Runtime Changes\n\nThe most relevant commands when you are changing docs runtime behavior are:\n\n- `npm run docs:validate`: validate docs content, nav data, markers, and inheritance rules\n- The validator checks for:\n\t- both `index.md` and `inherit.md` in the same page folder\n\t- both `_index.md` and `_inherit.md` in the same version, book, or section folder\n\t- missing required page markers in page folders\n\t- missing required `_index.md` or `_inherit.md` in version or book folders\n\t- invalid non-empty inheritance marker files\n\t- inheritance chains that never resolve to real content\n\t- nav entries that point to missing version, book, section, or page paths\n\t- duplicate nav slugs in books, sections, or pages\n\t- legacy identity metadata such as `doc_id` and `product_version`\n\t- disallowed docs front matter such as `aliases`\n- `npm run docs:materialize-inherited`: regenerate transient inherited-route and stable current-route anchors\n- `npm run build`: generate theme assets, validate docs, materialize docs route anchors, and build the site\n- `npm run build:search`: run the full build and then generate the Pagefind search index\n", "0.9": "+++\ntitle = \"Docs Runtime and Route Resolution\"\n+++\n\nThis page covers the implementation-facing side of docs routing.\n\nUse it when you need to answer questions such as:\n\n- which files own docs route resolution\n- how stable current routes differ from explicit versioned routes\n- how inherited pages become routable\n- how version switching and docs search stay version-aware\n\n## Runtime Map\n\nEditors usually work in content and nav files. Web developers also need to know which files own version metadata, build-time validation, and runtime route resolution.\n\n### Content and Navigation Sources\n\nThese files define what the docs tree is supposed to be:\n\n- `website/data/docs-versions.toml`: canonical docs version metadata\n- `website/data/docs-nav/\u003cversion\u003e.toml`: ordered books, sections, and pages\n\nIf the docs UI order looks wrong, or a page exists on disk but not in navigation, these are the first files to check.\n\n### Build and Tooling Scripts\n\nThese scripts keep the docs tree valid and routable:\n\n- `website/scripts/validate-docs-content.py`: validates docs structure, markers, and nav integrity\n- `website/scripts/materialize-inherited-docs.py`: generates transient routable anchors for inherited docs and stable current routes\n- `website/scripts/docs-editor.py`: CLI for creating, deleting, and renaming docs versions, books, sections, and pages safely\n\nIn practice:\n\n- use the validator when you need to confirm content-tree and nav consistency\n- use materialization when testing inheritance or stable-current route behavior\n- use the docs editor for structural changes instead of hand-editing multiple files\n\n### Runtime Template Layer\n\nThese files turn the requested docs URL into the page the user actually sees:\n\n- `website/themes/sambee/layouts/partials/docs/context.html`: derives docs path context from the requested route\n- `website/themes/sambee/layouts/partials/docs/page-path.html`: builds docs content paths with stable-current routing support\n- `website/themes/sambee/layouts/partials/docs/page-url.html`: resolves navigable docs URLs\n- `website/themes/sambee/layouts/partials/docs/source-page.html`: resolves the explicit versioned source page behind stable current routes\n- `website/themes/sambee/layouts/partials/docs/effective-page.html`: resolves the authored page that supplies body content and metadata\n- `website/themes/sambee/layouts/partials/docs/render-data.html`: prepares shared docs render data, including redirect and indexing state\n- `website/themes/sambee/layouts/partials/docs/article-shell.html`: renders the shared docs article shell\n- `website/themes/sambee/layouts/partials/docs/redirect-target.html`: resolves docs entry redirects\n- `website/themes/sambee/layouts/partials/docs/nav-tree.html`: resolves navigation targets and displayed titles\n- `website/themes/sambee/layouts/partials/docs/version-target-url.html`: resolves cross-version switch targets\n- `website/themes/sambee/layouts/partials/search-modal.html`: applies docs-version-aware search behavior\n- `website/themes/sambee/layouts/docs/list.html` and `website/themes/sambee/layouts/docs/single.html`: route docs list and page rendering through the shared shell\n\n### Theme Assets\n\nThese assets shape the visible docs experience once the route and content have been resolved:\n\n- `website/themes/sambee/assets/css/`: shared theme CSS, including docs UI and typography\n\n## Requested Route Versus Effective Page\n\nThe docs runtime keeps requested-path context separate from effective-content resolution.\n\n### Requested Route Context\n\n`website/themes/sambee/layouts/partials/docs/context.html` derives path context from the requested route and returns values including:\n\n- `isDocs`\n- `version`\n- `book`\n- `section`\n- `page`\n- `kind`\n- `currentVersion`\n- `isExplicitVersion`\n- `isCurrentRoute`\n- `isCurrentVersion`\n- convenience booleans: `isDocsRoot`, `isVersion`, `isBook`, `isSection`, and `isPage`\n\nInterpretation rules that matter when changing templates:\n\n- stable current routes such as `/docs/website-dev-guide/...` still resolve to the current version even though the version slug is omitted\n- explicit current-version routes such as `/docs/0.7/...` are compatibility routes and should redirect to stable current routes\n- archived explicit version routes stay routable and render as full docs pages\n\n### Effective Content Resolution\n\n`website/themes/sambee/layouts/partials/docs/effective-page.html` then resolves the authored content source and returns values including:\n\n- `page`: the authored page that should supply title, description, TOC, and body content\n- `requestedPage`: the Hugo page for the requested route\n- `requestedVersion`: the version derived from the route\n- `resolvedVersion`: the version that supplied the effective content\n- `isInherited`: whether the route resolved through inheritance\n\nTemplates should render article content and metadata from `page`, while navigation state, breadcrumbs, and version-switcher state stay tied to the requested route context.\n\n## Why Materialization Exists\n\nHugo needs a concrete page object at the requested path. Raw marker files alone are not enough.\n\nThe build therefore materializes transient route anchors under `.generated/content/docs` so Hugo can route inherited pages and stable current routes without publishing broken `/inherit/` or `/_inherit/` URLs.\n\nFrom Hugo's perspective, `inherit.md` and `_inherit.md` are ordinary content files. If the site consumed them directly, Hugo would try to publish the wrong public URLs.\n\nExample:\n\n- `content/docs/1.1/end-user/getting-started/install/inherit.md` would naturally publish at `/docs/1.1/end-user/getting-started/install/inherit/`\n- `content/docs/1.1/_inherit.md` would naturally publish at `/docs/1.1/_inherit/`\n\nThose are invalid for this docs model. The canonical public URLs must stay attached to the folder path itself:\n\n- `/docs/1.1/end-user/getting-started/install/`\n- `/docs/1.1/`\n\nThat creates a routing gap:\n\n- raw marker files must not become public pages\n- Hugo still needs a real page or section node at the requested folder path so templates can run and the resolver can supply inherited content\n\nThe moving pieces are:\n\n- `website/hugo.toml` ignores raw marker files as direct public pages\n- `website/scripts/materialize-inherited-docs.py` generates transient anchors at the canonical folder paths\n- `website/config/_default/module.toml` mounts `.generated/content` into Hugo's content tree\n- `website/themes/sambee/layouts/partials/docs/effective-page.html` resolves the real authored page that should supply the body, title, description, and TOC\n\nDuring the build, `materialize-inherited-docs.py` does this work:\n\n1. deletes stale generated docs anchors under `website/.generated/content/docs/`\n2. scans `website/content/docs/` for `inherit.md` and `_inherit.md`\n3. generates transient `index.md` or `_index.md` anchors at the matching canonical folder paths under `website/.generated/content/docs/`\n4. generates transient anchors for the declared current version at stable routes under `website/.generated/content/docs/\u003cbook\u003e/...`\n5. marks inherited-route anchors with `inherit = true`\n6. marks stable current-route anchors with `current_route = true` and `source_docs_path = \"/docs/\u003ccurrent\u003e/...\"`\n\nOperational notes:\n\n- `website/.generated/` is build output and is ignored by Git\n- Hugo mounts `.generated/content` into the site content tree during the build\n- Hugo is configured to ignore raw `inherit.md` and `_inherit.md` files\n\nWithout this script, the project would be stuck with two bad options:\n\n- keep raw marker files visible to Hugo and accept broken `/inherit/` and `/_inherit/` URLs\n- ignore marker files and lose the routable page nodes needed to render inherited docs at canonical folder URLs\n\n## Version Switcher Fallback Order\n\nWhen a reader switches from one docs version to another, the target lookup order is:\n\n1. the same page path\n2. the same section landing path\n3. the same book landing path\n4. the target version landing path\n\n## Search Behavior\n\nDocs search is intentionally version-aware.\n\n- Pagefind indexes stable current docs URLs, not explicit current-version compatibility routes\n- current docs search results therefore keep stable unversioned URLs\n- explicit versioned docs pages are excluded from the current-version search index\n- on non-docs pages, the UI defaults docs search filters to the `current` version from `website/data/docs-versions.toml`\n- versions with `searchable = false` are excluded from docs search indexing\n\n## Commands for Runtime Changes\n\nThe most relevant commands when you are changing docs runtime behavior are:\n\n- `npm run docs:validate`: validate docs content, nav data, markers, and inheritance rules\n- The validator checks for:\n\t- both `index.md` and `inherit.md` in the same page folder\n\t- both `_index.md` and `_inherit.md` in the same version, book, or section folder\n\t- missing required page markers in page folders\n\t- missing required `_index.md` or `_inherit.md` in version or book folders\n\t- invalid non-empty inheritance marker files\n\t- inheritance chains that never resolve to real content\n\t- nav entries that point to missing version, book, section, or page paths\n\t- duplicate nav slugs in books, sections, or pages\n\t- legacy identity metadata such as `doc_id` and `product_version`\n\t- disallowed docs front matter such as `aliases`\n- `npm run docs:materialize-inherited`: regenerate transient inherited-route and stable current-route anchors\n- `npm run build`: generate theme assets, validate docs, materialize docs route anchors, and build the site\n- `npm run build:search`: run the full build and then generate the Pagefind search index\n", "1.0": "+++\ntitle = \"Docs Runtime and Route Resolution\"\n+++\n\nThis page covers the implementation-facing side of docs routing.\n\nUse it when you need to answer questions such as:\n\n- which files own docs route resolution\n- how stable current routes differ from explicit versioned routes\n- how inherited pages become routable\n- how version switching and docs search stay version-aware\n\n## Runtime Map\n\nEditors usually work in content and nav files. Web developers also need to know which files own version metadata, build-time validation, and runtime route resolution.\n\n### Content and Navigation Sources\n\nThese files define what the docs tree is supposed to be:\n\n- `website/data/docs-versions.toml`: canonical docs version metadata\n- `website/data/docs-nav/\u003cversion\u003e.toml`: ordered books, sections, and pages\n\nIf the docs UI order looks wrong, or a page exists on disk but not in navigation, these are the first files to check.\n\n### Build and Tooling Scripts\n\nThese scripts keep the docs tree valid and routable:\n\n- `website/scripts/validate-docs-content.py`: validates docs structure, markers, and nav integrity\n- `website/scripts/materialize-inherited-docs.py`: generates transient routable anchors for inherited docs and stable current routes\n- `website/scripts/docs-editor.py`: CLI for creating, deleting, and renaming docs versions, books, sections, and pages safely\n\nIn practice:\n\n- use the validator when you need to confirm content-tree and nav consistency\n- use materialization when testing inheritance or stable-current route behavior\n- use the docs editor for structural changes instead of hand-editing multiple files\n\n### Runtime Template Layer\n\nThese files turn the requested docs URL into the page the user actually sees:\n\n- `website/themes/sambee/layouts/partials/docs/context.html`: derives docs path context from the requested route\n- `website/themes/sambee/layouts/partials/docs/page-path.html`: builds docs content paths with stable-current routing support\n- `website/themes/sambee/layouts/partials/docs/page-url.html`: resolves navigable docs URLs\n- `website/themes/sambee/layouts/partials/docs/source-page.html`: resolves the explicit versioned source page behind stable current routes\n- `website/themes/sambee/layouts/partials/docs/effective-page.html`: resolves the authored page that supplies body content and metadata\n- `website/themes/sambee/layouts/partials/docs/render-data.html`: prepares shared docs render data, including redirect and indexing state\n- `website/themes/sambee/layouts/partials/docs/article-shell.html`: renders the shared docs article shell\n- `website/themes/sambee/layouts/partials/docs/redirect-target.html`: resolves docs entry redirects\n- `website/themes/sambee/layouts/partials/docs/nav-tree.html`: resolves navigation targets and displayed titles\n- `website/themes/sambee/layouts/partials/docs/version-target-url.html`: resolves cross-version switch targets\n- `website/themes/sambee/layouts/partials/search-modal.html`: applies docs-version-aware search behavior\n- `website/themes/sambee/layouts/docs/list.html` and `website/themes/sambee/layouts/docs/single.html`: route docs list and page rendering through the shared shell\n\n### Theme Assets\n\nThese assets shape the visible docs experience once the route and content have been resolved:\n\n- `website/themes/sambee/assets/css/`: shared theme CSS, including docs UI and typography\n\n## Requested Route Versus Effective Page\n\nThe docs runtime keeps requested-path context separate from effective-content resolution.\n\n### Requested Route Context\n\n`website/themes/sambee/layouts/partials/docs/context.html` derives path context from the requested route and returns values including:\n\n- `isDocs`\n- `version`\n- `book`\n- `section`\n- `page`\n- `kind`\n- `currentVersion`\n- `isExplicitVersion`\n- `isCurrentRoute`\n- `isCurrentVersion`\n- convenience booleans: `isDocsRoot`, `isVersion`, `isBook`, `isSection`, and `isPage`\n\nInterpretation rules that matter when changing templates:\n\n- stable current routes such as `/docs/website-dev-guide/...` still resolve to the current version even though the version slug is omitted\n- explicit current-version routes such as `/docs/0.7/...` are compatibility routes and should redirect to stable current routes\n- archived explicit version routes stay routable and render as full docs pages\n\n### Effective Content Resolution\n\n`website/themes/sambee/layouts/partials/docs/effective-page.html` then resolves the authored content source and returns values including:\n\n- `page`: the authored page that should supply title, description, TOC, and body content\n- `requestedPage`: the Hugo page for the requested route\n- `requestedVersion`: the version derived from the route\n- `resolvedVersion`: the version that supplied the effective content\n- `isInherited`: whether the route resolved through inheritance\n\nTemplates should render article content and metadata from `page`, while navigation state, breadcrumbs, and version-switcher state stay tied to the requested route context.\n\n## Why Materialization Exists\n\nHugo needs a concrete page object at the requested path. Raw marker files alone are not enough.\n\nThe build therefore materializes transient route anchors under `.generated/content/docs` so Hugo can route inherited pages and stable current routes without publishing broken `/inherit/` or `/_inherit/` URLs.\n\nFrom Hugo's perspective, `inherit.md` and `_inherit.md` are ordinary content files. If the site consumed them directly, Hugo would try to publish the wrong public URLs.\n\nExample:\n\n- `content/docs/1.1/end-user/getting-started/install/inherit.md` would naturally publish at `/docs/1.1/end-user/getting-started/install/inherit/`\n- `content/docs/1.1/_inherit.md` would naturally publish at `/docs/1.1/_inherit/`\n\nThose are invalid for this docs model. The canonical public URLs must stay attached to the folder path itself:\n\n- `/docs/1.1/end-user/getting-started/install/`\n- `/docs/1.1/`\n\nThat creates a routing gap:\n\n- raw marker files must not become public pages\n- Hugo still needs a real page or section node at the requested folder path so templates can run and the resolver can supply inherited content\n\nThe moving pieces are:\n\n- `website/hugo.toml` ignores raw marker files as direct public pages\n- `website/scripts/materialize-inherited-docs.py` generates transient anchors at the canonical folder paths\n- `website/config/_default/module.toml` mounts `.generated/content` into Hugo's content tree\n- `website/themes/sambee/layouts/partials/docs/effective-page.html` resolves the real authored page that should supply the body, title, description, and TOC\n\nDuring the build, `materialize-inherited-docs.py` does this work:\n\n1. deletes stale generated docs anchors under `website/.generated/content/docs/`\n2. scans `website/content/docs/` for `inherit.md` and `_inherit.md`\n3. generates transient `index.md` or `_index.md` anchors at the matching canonical folder paths under `website/.generated/content/docs/`\n4. generates transient anchors for the declared current version at stable routes under `website/.generated/content/docs/\u003cbook\u003e/...`\n5. marks inherited-route anchors with `inherit = true`\n6. marks stable current-route anchors with `current_route = true` and `source_docs_path = \"/docs/\u003ccurrent\u003e/...\"`\n\nOperational notes:\n\n- `website/.generated/` is build output and is ignored by Git\n- Hugo mounts `.generated/content` into the site content tree during the build\n- Hugo is configured to ignore raw `inherit.md` and `_inherit.md` files\n\nWithout this script, the project would be stuck with two bad options:\n\n- keep raw marker files visible to Hugo and accept broken `/inherit/` and `/_inherit/` URLs\n- ignore marker files and lose the routable page nodes needed to render inherited docs at canonical folder URLs\n\n## Version Switcher Fallback Order\n\nWhen a reader switches from one docs version to another, the target lookup order is:\n\n1. the same page path\n2. the same section landing path\n3. the same book landing path\n4. the target version landing path\n\n## Search Behavior\n\nDocs search is intentionally version-aware.\n\n- Pagefind indexes stable current docs URLs, not explicit current-version compatibility routes\n- current docs search results therefore keep stable unversioned URLs\n- explicit versioned docs pages are excluded from the current-version search index\n- on non-docs pages, the UI defaults docs search filters to the `current` version from `website/data/docs-versions.toml`\n- versions with `searchable = false` are excluded from docs search indexing\n\n## Commands for Runtime Changes\n\nThe most relevant commands when you are changing docs runtime behavior are:\n\n- `npm run docs:validate`: validate docs content, nav data, markers, and inheritance rules\n- The validator checks for:\n\t- both `index.md` and `inherit.md` in the same page folder\n\t- both `_index.md` and `_inherit.md` in the same version, book, or section folder\n\t- missing required page markers in page folders\n\t- missing required `_index.md` or `_inherit.md` in version or book folders\n\t- invalid non-empty inheritance marker files\n\t- inheritance chains that never resolve to real content\n\t- nav entries that point to missing version, book, section, or page paths\n\t- duplicate nav slugs in books, sections, or pages\n\t- legacy identity metadata such as `doc_id` and `product_version`\n\t- disallowed docs front matter such as `aliases`\n- `npm run docs:materialize-inherited`: regenerate transient inherited-route and stable current-route anchors\n- `npm run build`: generate theme assets, validate docs, materialize docs route anchors, and build the site\n- `npm run build:search`: run the full build and then generate the Pagefind search index\n", "2.0": "+++\ntitle = \"Docs Runtime and Route Resolution\"\n+++\n\nThis page covers the implementation-facing side of docs routing.\n\nUse it when you need to answer questions such as:\n\n- which files own docs route resolution\n- how stable current routes differ from explicit versioned routes\n- how inherited pages become routable\n- how version switching and docs search stay version-aware\n\n## Runtime Map\n\nEditors usually work in content and nav files. Web developers also need to know which files own version metadata, build-time validation, and runtime route resolution.\n\n### Content and Navigation Sources\n\nThese files define what the docs tree is supposed to be:\n\n- `website/data/docs-versions.toml`: canonical docs version metadata\n- `website/data/docs-nav/\u003cversion\u003e.toml`: ordered books, sections, and pages\n\nIf the docs UI order looks wrong, or a page exists on disk but not in navigation, these are the first files to check.\n\n### Build and Tooling Scripts\n\nThese scripts keep the docs tree valid and routable:\n\n- `website/scripts/validate-docs-content.py`: validates docs structure, markers, and nav integrity\n- `website/scripts/materialize-inherited-docs.py`: generates transient routable anchors for inherited docs and stable current routes\n- `website/scripts/docs-editor.py`: CLI for creating, deleting, and renaming docs versions, books, sections, and pages safely\n\nIn practice:\n\n- use the validator when you need to confirm content-tree and nav consistency\n- use materialization when testing inheritance or stable-current route behavior\n- use the docs editor for structural changes instead of hand-editing multiple files\n\n### Runtime Template Layer\n\nThese files turn the requested docs URL into the page the user actually sees:\n\n- `website/themes/sambee/layouts/partials/docs/context.html`: derives docs path context from the requested route\n- `website/themes/sambee/layouts/partials/docs/page-path.html`: builds docs content paths with stable-current routing support\n- `website/themes/sambee/layouts/partials/docs/page-url.html`: resolves navigable docs URLs\n- `website/themes/sambee/layouts/partials/docs/source-page.html`: resolves the explicit versioned source page behind stable current routes\n- `website/themes/sambee/layouts/partials/docs/effective-page.html`: resolves the authored page that supplies body content and metadata\n- `website/themes/sambee/layouts/partials/docs/render-data.html`: prepares shared docs render data, including redirect and indexing state\n- `website/themes/sambee/layouts/partials/docs/article-shell.html`: renders the shared docs article shell\n- `website/themes/sambee/layouts/partials/docs/redirect-target.html`: resolves docs entry redirects\n- `website/themes/sambee/layouts/partials/docs/nav-tree.html`: resolves navigation targets and displayed titles\n- `website/themes/sambee/layouts/partials/docs/version-target-url.html`: resolves cross-version switch targets\n- `website/themes/sambee/layouts/partials/search-modal.html`: applies docs-version-aware search behavior\n- `website/themes/sambee/layouts/docs/list.html` and `website/themes/sambee/layouts/docs/single.html`: route docs list and page rendering through the shared shell\n\n### Theme Assets\n\nThese assets shape the visible docs experience once the route and content have been resolved:\n\n- `website/themes/sambee/assets/css/`: shared theme CSS, including docs UI and typography\n\n## Requested Route Versus Effective Page\n\nThe docs runtime keeps requested-path context separate from effective-content resolution.\n\n### Requested Route Context\n\n`website/themes/sambee/layouts/partials/docs/context.html` derives path context from the requested route and returns values including:\n\n- `isDocs`\n- `version`\n- `book`\n- `section`\n- `page`\n- `kind`\n- `currentVersion`\n- `isExplicitVersion`\n- `isCurrentRoute`\n- `isCurrentVersion`\n- convenience booleans: `isDocsRoot`, `isVersion`, `isBook`, `isSection`, and `isPage`\n\nInterpretation rules that matter when changing templates:\n\n- stable current routes such as `/docs/website-dev-guide/...` still resolve to the current version even though the version slug is omitted\n- explicit current-version routes such as `/docs/0.7/...` are compatibility routes and should redirect to stable current routes\n- archived explicit version routes stay routable and render as full docs pages\n\n### Effective Content Resolution\n\n`website/themes/sambee/layouts/partials/docs/effective-page.html` then resolves the authored content source and returns values including:\n\n- `page`: the authored page that should supply title, description, TOC, and body content\n- `requestedPage`: the Hugo page for the requested route\n- `requestedVersion`: the version derived from the route\n- `resolvedVersion`: the version that supplied the effective content\n- `isInherited`: whether the route resolved through inheritance\n\nTemplates should render article content and metadata from `page`, while navigation state, breadcrumbs, and version-switcher state stay tied to the requested route context.\n\n## Why Materialization Exists\n\nHugo needs a concrete page object at the requested path. Raw marker files alone are not enough.\n\nThe build therefore materializes transient route anchors under `.generated/content/docs` so Hugo can route inherited pages and stable current routes without publishing broken `/inherit/` or `/_inherit/` URLs.\n\nFrom Hugo's perspective, `inherit.md` and `_inherit.md` are ordinary content files. If the site consumed them directly, Hugo would try to publish the wrong public URLs.\n\nExample:\n\n- `content/docs/1.1/end-user/getting-started/install/inherit.md` would naturally publish at `/docs/1.1/end-user/getting-started/install/inherit/`\n- `content/docs/1.1/_inherit.md` would naturally publish at `/docs/1.1/_inherit/`\n\nThose are invalid for this docs model. The canonical public URLs must stay attached to the folder path itself:\n\n- `/docs/1.1/end-user/getting-started/install/`\n- `/docs/1.1/`\n\nThat creates a routing gap:\n\n- raw marker files must not become public pages\n- Hugo still needs a real page or section node at the requested folder path so templates can run and the resolver can supply inherited content\n\nThe moving pieces are:\n\n- `website/hugo.toml` ignores raw marker files as direct public pages\n- `website/scripts/materialize-inherited-docs.py` generates transient anchors at the canonical folder paths\n- `website/config/_default/module.toml` mounts `.generated/content` into Hugo's content tree\n- `website/themes/sambee/layouts/partials/docs/effective-page.html` resolves the real authored page that should supply the body, title, description, and TOC\n\nDuring the build, `materialize-inherited-docs.py` does this work:\n\n1. deletes stale generated docs anchors under `website/.generated/content/docs/`\n2. scans `website/content/docs/` for `inherit.md` and `_inherit.md`\n3. generates transient `index.md` or `_index.md` anchors at the matching canonical folder paths under `website/.generated/content/docs/`\n4. generates transient anchors for the declared current version at stable routes under `website/.generated/content/docs/\u003cbook\u003e/...`\n5. marks inherited-route anchors with `inherit = true`\n6. marks stable current-route anchors with `current_route = true` and `source_docs_path = \"/docs/\u003ccurrent\u003e/...\"`\n\nOperational notes:\n\n- `website/.generated/` is build output and is ignored by Git\n- Hugo mounts `.generated/content` into the site content tree during the build\n- Hugo is configured to ignore raw `inherit.md` and `_inherit.md` files\n\nWithout this script, the project would be stuck with two bad options:\n\n- keep raw marker files visible to Hugo and accept broken `/inherit/` and `/_inherit/` URLs\n- ignore marker files and lose the routable page nodes needed to render inherited docs at canonical folder URLs\n\n## Version Switcher Fallback Order\n\nWhen a reader switches from one docs version to another, the target lookup order is:\n\n1. the same page path\n2. the same section landing path\n3. the same book landing path\n4. the target version landing path\n\n## Search Behavior\n\nDocs search is intentionally version-aware.\n\n- Pagefind indexes stable current docs URLs, not explicit current-version compatibility routes\n- current docs search results therefore keep stable unversioned URLs\n- explicit versioned docs pages are excluded from the current-version search index\n- on non-docs pages, the UI defaults docs search filters to the `current` version from `website/data/docs-versions.toml`\n- versions with `searchable = false` are excluded from docs search indexing\n\n## Commands for Runtime Changes\n\nThe most relevant commands when you are changing docs runtime behavior are:\n\n- `npm run docs:validate`: validate docs content, nav data, markers, and inheritance rules\n- The validator checks for:\n\t- both `index.md` and `inherit.md` in the same page folder\n\t- both `_index.md` and `_inherit.md` in the same version, book, or section folder\n\t- missing required page markers in page folders\n\t- missing required `_index.md` or `_inherit.md` in version or book folders\n\t- invalid non-empty inheritance marker files\n\t- inheritance chains that never resolve to real content\n\t- nav entries that point to missing version, book, section, or page paths\n\t- duplicate nav slugs in books, sections, or pages\n\t- legacy identity metadata such as `doc_id` and `product_version`\n\t- disallowed docs front matter such as `aliases`\n- `npm run docs:materialize-inherited`: regenerate transient inherited-route and stable current-route anchors\n- `npm run build`: generate theme assets, validate docs, materialize docs route anchors, and build the site\n- `npm run build:search`: run the full build and then generate the Pagefind search index\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:website-dev-guide/authoring-and-tooling", "parent_id": "book:website-dev-guide", "depth": 1, "kind": "section", "label": "authoring-and-tooling", "title": "Authoring and Tooling", "path": "website-dev-guide/authoring-and-tooling", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:website-dev-guide/authoring-and-tooling/docs-authoring-workflow", "parent_id": "section:website-dev-guide/authoring-and-tooling", "depth": 2, "kind": "page", "label": "docs-authoring-workflow", "title": "Docs Authoring Workflow", "path": "website-dev-guide/authoring-and-tooling/docs-authoring-workflow", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "Book and section landing pages are optional. Either may be structural only, with no `_index.md` and no `_inherit.md`. A structural node remains in navigation but has no public landing route. This Website Dev Guide uses structural-only sections.\n+++\ntitle = \"Docs Authoring Workflow\"\n+++\n\nFor wording, list punctuation, and capitalization conventions, use the [Docs Style Guide](../docs-style-guide/).\n\n## Content Structure Rules\n\nThe docs system is path-derived.\n\n- book landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/_index.md`\n- section landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/_index.md`\n- article page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md`\n\nSection landing pages are optional. A section may be structural only, with no `_index.md` and no `_inherit.md`. This Website Dev Guide uses structural-only sections.\n\n## Example: Add a New Page\n\nSuppose you want a new page under `website-dev-guide/authoring-and-tooling/`.\n\nCreate the content bundle:\n\n```text\nwebsite/content/docs/0.7/website-dev-guide/authoring-and-tooling/new-page/index.md\n```\n\nThen add the page slug to the matching nav section:\n\n```toml\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n  \"new-page\",\n]\n```\n\nWithout the nav update, the page may exist on disk but stay absent from generated navigation.\n\n## Example: Reuse an Older Page without Copying the Content\n\nWhen a newer version should reuse the same page unchanged:\n\n1. create the same page folder in the newer version\n2. add an empty `inherit.md`\n3. keep the corresponding path in an older version with real `index.md` content\n\nExample:\n\n```text\nwebsite/content/docs/0.8/website-dev-guide/site-systems/media-publishing-workflow/inherit.md\n```\n\nDo not put front matter or body content into `inherit.md`.\n\n## Example: Diverge in a Newer Version\n\nIf a newer version needs different content, replace the marker with a real page:\n\n1. remove `inherit.md`\n2. create `index.md`\n3. write the new content for that version\n\nThat keeps the inheritance chain explicit and avoids template-side special cases.\n\n## Navigation Rules\n\nNavigation data controls order, not content. Keep these rules in mind:\n\n- slugs in the nav file must match the folder names on disk\n- changing a slug changes the public URL\n- page titles come from the page's own front matter, not from the nav file\n- section titles come from `docs-nav/\u003cversion\u003e.toml`\n\n## When to Use the Docs Editor Instead of Manual File Edits\n\nManual edits are normal for copy changes inside an existing page.\n\nUse the docs editor when the change is structural, for example:\n\n- creating a new book\n- creating, deleting, or renaming a section\n- creating, deleting, or renaming a page\n- changing docs structure across inherited versions\n\nThe docs editor keeps content paths and nav data in sync and refuses destructive changes that would silently overwrite newer authored content.\n\n## Validation\n\nFor docs and website changes, run:\n\n```bash\ncd website\nnpm run build\n```\n\nThat is the minimum meaningful verification because it runs theme generation, docs validation, inherited-doc materialization, Hugo rendering, and homepage CTA validation.\n", "0.8": "Book and section landing pages are optional. Either may be structural only, with no `_index.md` and no `_inherit.md`. A structural node remains in navigation but has no public landing route. This Website Dev Guide uses structural-only sections.\n+++\ntitle = \"Docs Authoring Workflow\"\n+++\n\nFor wording, list punctuation, and capitalization conventions, use the [Docs Style Guide](../docs-style-guide/).\n\n## Content Structure Rules\n\nThe docs system is path-derived.\n\n- book landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/_index.md`\n- section landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/_index.md`\n- article page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md`\n\nSection landing pages are optional. A section may be structural only, with no `_index.md` and no `_inherit.md`. This Website Dev Guide uses structural-only sections.\n\n## Example: Add a New Page\n\nSuppose you want a new page under `website-dev-guide/authoring-and-tooling/`.\n\nCreate the content bundle:\n\n```text\nwebsite/content/docs/0.7/website-dev-guide/authoring-and-tooling/new-page/index.md\n```\n\nThen add the page slug to the matching nav section:\n\n```toml\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n  \"new-page\",\n]\n```\n\nWithout the nav update, the page may exist on disk but stay absent from generated navigation.\n\n## Example: Reuse an Older Page without Copying the Content\n\nWhen a newer version should reuse the same page unchanged:\n\n1. create the same page folder in the newer version\n2. add an empty `inherit.md`\n3. keep the corresponding path in an older version with real `index.md` content\n\nExample:\n\n```text\nwebsite/content/docs/0.8/website-dev-guide/site-systems/media-publishing-workflow/inherit.md\n```\n\nDo not put front matter or body content into `inherit.md`.\n\n## Example: Diverge in a Newer Version\n\nIf a newer version needs different content, replace the marker with a real page:\n\n1. remove `inherit.md`\n2. create `index.md`\n3. write the new content for that version\n\nThat keeps the inheritance chain explicit and avoids template-side special cases.\n\n## Navigation Rules\n\nNavigation data controls order, not content. Keep these rules in mind:\n\n- slugs in the nav file must match the folder names on disk\n- changing a slug changes the public URL\n- page titles come from the page's own front matter, not from the nav file\n- section titles come from `docs-nav/\u003cversion\u003e.toml`\n\n## When to Use the Docs Editor Instead of Manual File Edits\n\nManual edits are normal for copy changes inside an existing page.\n\nUse the docs editor when the change is structural, for example:\n\n- creating a new book\n- creating, deleting, or renaming a section\n- creating, deleting, or renaming a page\n- changing docs structure across inherited versions\n\nThe docs editor keeps content paths and nav data in sync and refuses destructive changes that would silently overwrite newer authored content.\n\n## Validation\n\nFor docs and website changes, run:\n\n```bash\ncd website\nnpm run build\n```\n\nThat is the minimum meaningful verification because it runs theme generation, docs validation, inherited-doc materialization, Hugo rendering, and homepage CTA validation.\n", "0.9": "Book and section landing pages are optional. Either may be structural only, with no `_index.md` and no `_inherit.md`. A structural node remains in navigation but has no public landing route. This Website Dev Guide uses structural-only sections.\n+++\ntitle = \"Docs Authoring Workflow\"\n+++\n\nFor wording, list punctuation, and capitalization conventions, use the [Docs Style Guide](../docs-style-guide/).\n\n## Content Structure Rules\n\nThe docs system is path-derived.\n\n- book landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/_index.md`\n- section landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/_index.md`\n- article page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md`\n\nSection landing pages are optional. A section may be structural only, with no `_index.md` and no `_inherit.md`. This Website Dev Guide uses structural-only sections.\n\n## Example: Add a New Page\n\nSuppose you want a new page under `website-dev-guide/authoring-and-tooling/`.\n\nCreate the content bundle:\n\n```text\nwebsite/content/docs/0.7/website-dev-guide/authoring-and-tooling/new-page/index.md\n```\n\nThen add the page slug to the matching nav section:\n\n```toml\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n  \"new-page\",\n]\n```\n\nWithout the nav update, the page may exist on disk but stay absent from generated navigation.\n\n## Example: Reuse an Older Page without Copying the Content\n\nWhen a newer version should reuse the same page unchanged:\n\n1. create the same page folder in the newer version\n2. add an empty `inherit.md`\n3. keep the corresponding path in an older version with real `index.md` content\n\nExample:\n\n```text\nwebsite/content/docs/0.8/website-dev-guide/site-systems/media-publishing-workflow/inherit.md\n```\n\nDo not put front matter or body content into `inherit.md`.\n\n## Example: Diverge in a Newer Version\n\nIf a newer version needs different content, replace the marker with a real page:\n\n1. remove `inherit.md`\n2. create `index.md`\n3. write the new content for that version\n\nThat keeps the inheritance chain explicit and avoids template-side special cases.\n\n## Navigation Rules\n\nNavigation data controls order, not content. Keep these rules in mind:\n\n- slugs in the nav file must match the folder names on disk\n- changing a slug changes the public URL\n- page titles come from the page's own front matter, not from the nav file\n- section titles come from `docs-nav/\u003cversion\u003e.toml`\n\n## When to Use the Docs Editor Instead of Manual File Edits\n\nManual edits are normal for copy changes inside an existing page.\n\nUse the docs editor when the change is structural, for example:\n\n- creating a new book\n- creating, deleting, or renaming a section\n- creating, deleting, or renaming a page\n- changing docs structure across inherited versions\n\nThe docs editor keeps content paths and nav data in sync and refuses destructive changes that would silently overwrite newer authored content.\n\n## Validation\n\nFor docs and website changes, run:\n\n```bash\ncd website\nnpm run build\n```\n\nThat is the minimum meaningful verification because it runs theme generation, docs validation, inherited-doc materialization, Hugo rendering, and homepage CTA validation.\n", "1.0": "Book and section landing pages are optional. Either may be structural only, with no `_index.md` and no `_inherit.md`. A structural node remains in navigation but has no public landing route. This Website Dev Guide uses structural-only sections.\n+++\ntitle = \"Docs Authoring Workflow\"\n+++\n\nFor wording, list punctuation, and capitalization conventions, use the [Docs Style Guide](../docs-style-guide/).\n\n## Content Structure Rules\n\nThe docs system is path-derived.\n\n- book landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/_index.md`\n- section landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/_index.md`\n- article page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md`\n\nSection landing pages are optional. A section may be structural only, with no `_index.md` and no `_inherit.md`. This Website Dev Guide uses structural-only sections.\n\n## Example: Add a New Page\n\nSuppose you want a new page under `website-dev-guide/authoring-and-tooling/`.\n\nCreate the content bundle:\n\n```text\nwebsite/content/docs/0.7/website-dev-guide/authoring-and-tooling/new-page/index.md\n```\n\nThen add the page slug to the matching nav section:\n\n```toml\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n  \"new-page\",\n]\n```\n\nWithout the nav update, the page may exist on disk but stay absent from generated navigation.\n\n## Example: Reuse an Older Page without Copying the Content\n\nWhen a newer version should reuse the same page unchanged:\n\n1. create the same page folder in the newer version\n2. add an empty `inherit.md`\n3. keep the corresponding path in an older version with real `index.md` content\n\nExample:\n\n```text\nwebsite/content/docs/0.8/website-dev-guide/site-systems/media-publishing-workflow/inherit.md\n```\n\nDo not put front matter or body content into `inherit.md`.\n\n## Example: Diverge in a Newer Version\n\nIf a newer version needs different content, replace the marker with a real page:\n\n1. remove `inherit.md`\n2. create `index.md`\n3. write the new content for that version\n\nThat keeps the inheritance chain explicit and avoids template-side special cases.\n\n## Navigation Rules\n\nNavigation data controls order, not content. Keep these rules in mind:\n\n- slugs in the nav file must match the folder names on disk\n- changing a slug changes the public URL\n- page titles come from the page's own front matter, not from the nav file\n- section titles come from `docs-nav/\u003cversion\u003e.toml`\n\n## When to Use the Docs Editor Instead of Manual File Edits\n\nManual edits are normal for copy changes inside an existing page.\n\nUse the docs editor when the change is structural, for example:\n\n- creating a new book\n- creating, deleting, or renaming a section\n- creating, deleting, or renaming a page\n- changing docs structure across inherited versions\n\nThe docs editor keeps content paths and nav data in sync and refuses destructive changes that would silently overwrite newer authored content.\n\n## Validation\n\nFor docs and website changes, run:\n\n```bash\ncd website\nnpm run build\n```\n\nThat is the minimum meaningful verification because it runs theme generation, docs validation, inherited-doc materialization, Hugo rendering, and homepage CTA validation.\n", "2.0": "Book and section landing pages are optional. Either may be structural only, with no `_index.md` and no `_inherit.md`. A structural node remains in navigation but has no public landing route. This Website Dev Guide uses structural-only sections.\n+++\ntitle = \"Docs Authoring Workflow\"\n+++\n\nFor wording, list punctuation, and capitalization conventions, use the [Docs Style Guide](../docs-style-guide/).\n\n## Content Structure Rules\n\nThe docs system is path-derived.\n\n- book landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/_index.md`\n- section landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/_index.md`\n- article page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md`\n\nSection landing pages are optional. A section may be structural only, with no `_index.md` and no `_inherit.md`. This Website Dev Guide uses structural-only sections.\n\n## Example: Add a New Page\n\nSuppose you want a new page under `website-dev-guide/authoring-and-tooling/`.\n\nCreate the content bundle:\n\n```text\nwebsite/content/docs/0.7/website-dev-guide/authoring-and-tooling/new-page/index.md\n```\n\nThen add the page slug to the matching nav section:\n\n```toml\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n  \"new-page\",\n]\n```\n\nWithout the nav update, the page may exist on disk but stay absent from generated navigation.\n\n## Example: Reuse an Older Page without Copying the Content\n\nWhen a newer version should reuse the same page unchanged:\n\n1. create the same page folder in the newer version\n2. add an empty `inherit.md`\n3. keep the corresponding path in an older version with real `index.md` content\n\nExample:\n\n```text\nwebsite/content/docs/0.8/website-dev-guide/site-systems/media-publishing-workflow/inherit.md\n```\n\nDo not put front matter or body content into `inherit.md`.\n\n## Example: Diverge in a Newer Version\n\nIf a newer version needs different content, replace the marker with a real page:\n\n1. remove `inherit.md`\n2. create `index.md`\n3. write the new content for that version\n\nThat keeps the inheritance chain explicit and avoids template-side special cases.\n\n## Navigation Rules\n\nNavigation data controls order, not content. Keep these rules in mind:\n\n- slugs in the nav file must match the folder names on disk\n- changing a slug changes the public URL\n- page titles come from the page's own front matter, not from the nav file\n- section titles come from `docs-nav/\u003cversion\u003e.toml`\n\n## When to Use the Docs Editor Instead of Manual File Edits\n\nManual edits are normal for copy changes inside an existing page.\n\nUse the docs editor when the change is structural, for example:\n\n- creating a new book\n- creating, deleting, or renaming a section\n- creating, deleting, or renaming a page\n- changing docs structure across inherited versions\n\nThe docs editor keeps content paths and nav data in sync and refuses destructive changes that would silently overwrite newer authored content.\n\n## Validation\n\nFor docs and website changes, run:\n\n```bash\ncd website\nnpm run build\n```\n\nThat is the minimum meaningful verification because it runs theme generation, docs validation, inherited-doc materialization, Hugo rendering, and homepage CTA validation.\n"}, "page_contents": {"0.7": "Book and section landing pages are optional. Either may be structural only, with no `_index.md` and no `_inherit.md`. A structural node remains in navigation but has no public landing route. This Website Dev Guide uses structural-only sections.\n+++\ntitle = \"Docs Authoring Workflow\"\n+++\n\nFor wording, list punctuation, and capitalization conventions, use the [Docs Style Guide](../docs-style-guide/).\n\n## Content Structure Rules\n\nThe docs system is path-derived.\n\n- book landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/_index.md`\n- section landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/_index.md`\n- article page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md`\n\nSection landing pages are optional. A section may be structural only, with no `_index.md` and no `_inherit.md`. This Website Dev Guide uses structural-only sections.\n\n## Example: Add a New Page\n\nSuppose you want a new page under `website-dev-guide/authoring-and-tooling/`.\n\nCreate the content bundle:\n\n```text\nwebsite/content/docs/0.7/website-dev-guide/authoring-and-tooling/new-page/index.md\n```\n\nThen add the page slug to the matching nav section:\n\n```toml\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n  \"new-page\",\n]\n```\n\nWithout the nav update, the page may exist on disk but stay absent from generated navigation.\n\n## Example: Reuse an Older Page without Copying the Content\n\nWhen a newer version should reuse the same page unchanged:\n\n1. create the same page folder in the newer version\n2. add an empty `inherit.md`\n3. keep the corresponding path in an older version with real `index.md` content\n\nExample:\n\n```text\nwebsite/content/docs/0.8/website-dev-guide/site-systems/media-publishing-workflow/inherit.md\n```\n\nDo not put front matter or body content into `inherit.md`.\n\n## Example: Diverge in a Newer Version\n\nIf a newer version needs different content, replace the marker with a real page:\n\n1. remove `inherit.md`\n2. create `index.md`\n3. write the new content for that version\n\nThat keeps the inheritance chain explicit and avoids template-side special cases.\n\n## Navigation Rules\n\nNavigation data controls order, not content. Keep these rules in mind:\n\n- slugs in the nav file must match the folder names on disk\n- changing a slug changes the public URL\n- page titles come from the page's own front matter, not from the nav file\n- section titles come from `docs-nav/\u003cversion\u003e.toml`\n\n## When to Use the Docs Editor Instead of Manual File Edits\n\nManual edits are normal for copy changes inside an existing page.\n\nUse the docs editor when the change is structural, for example:\n\n- creating a new book\n- creating, deleting, or renaming a section\n- creating, deleting, or renaming a page\n- changing docs structure across inherited versions\n\nThe docs editor keeps content paths and nav data in sync and refuses destructive changes that would silently overwrite newer authored content.\n\n## Validation\n\nFor docs and website changes, run:\n\n```bash\ncd website\nnpm run build\n```\n\nThat is the minimum meaningful verification because it runs theme generation, docs validation, inherited-doc materialization, Hugo rendering, and homepage CTA validation.\n", "0.8": "Book and section landing pages are optional. Either may be structural only, with no `_index.md` and no `_inherit.md`. A structural node remains in navigation but has no public landing route. This Website Dev Guide uses structural-only sections.\n+++\ntitle = \"Docs Authoring Workflow\"\n+++\n\nFor wording, list punctuation, and capitalization conventions, use the [Docs Style Guide](../docs-style-guide/).\n\n## Content Structure Rules\n\nThe docs system is path-derived.\n\n- book landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/_index.md`\n- section landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/_index.md`\n- article page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md`\n\nSection landing pages are optional. A section may be structural only, with no `_index.md` and no `_inherit.md`. This Website Dev Guide uses structural-only sections.\n\n## Example: Add a New Page\n\nSuppose you want a new page under `website-dev-guide/authoring-and-tooling/`.\n\nCreate the content bundle:\n\n```text\nwebsite/content/docs/0.7/website-dev-guide/authoring-and-tooling/new-page/index.md\n```\n\nThen add the page slug to the matching nav section:\n\n```toml\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n  \"new-page\",\n]\n```\n\nWithout the nav update, the page may exist on disk but stay absent from generated navigation.\n\n## Example: Reuse an Older Page without Copying the Content\n\nWhen a newer version should reuse the same page unchanged:\n\n1. create the same page folder in the newer version\n2. add an empty `inherit.md`\n3. keep the corresponding path in an older version with real `index.md` content\n\nExample:\n\n```text\nwebsite/content/docs/0.8/website-dev-guide/site-systems/media-publishing-workflow/inherit.md\n```\n\nDo not put front matter or body content into `inherit.md`.\n\n## Example: Diverge in a Newer Version\n\nIf a newer version needs different content, replace the marker with a real page:\n\n1. remove `inherit.md`\n2. create `index.md`\n3. write the new content for that version\n\nThat keeps the inheritance chain explicit and avoids template-side special cases.\n\n## Navigation Rules\n\nNavigation data controls order, not content. Keep these rules in mind:\n\n- slugs in the nav file must match the folder names on disk\n- changing a slug changes the public URL\n- page titles come from the page's own front matter, not from the nav file\n- section titles come from `docs-nav/\u003cversion\u003e.toml`\n\n## When to Use the Docs Editor Instead of Manual File Edits\n\nManual edits are normal for copy changes inside an existing page.\n\nUse the docs editor when the change is structural, for example:\n\n- creating a new book\n- creating, deleting, or renaming a section\n- creating, deleting, or renaming a page\n- changing docs structure across inherited versions\n\nThe docs editor keeps content paths and nav data in sync and refuses destructive changes that would silently overwrite newer authored content.\n\n## Validation\n\nFor docs and website changes, run:\n\n```bash\ncd website\nnpm run build\n```\n\nThat is the minimum meaningful verification because it runs theme generation, docs validation, inherited-doc materialization, Hugo rendering, and homepage CTA validation.\n", "0.9": "Book and section landing pages are optional. Either may be structural only, with no `_index.md` and no `_inherit.md`. A structural node remains in navigation but has no public landing route. This Website Dev Guide uses structural-only sections.\n+++\ntitle = \"Docs Authoring Workflow\"\n+++\n\nFor wording, list punctuation, and capitalization conventions, use the [Docs Style Guide](../docs-style-guide/).\n\n## Content Structure Rules\n\nThe docs system is path-derived.\n\n- book landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/_index.md`\n- section landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/_index.md`\n- article page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md`\n\nSection landing pages are optional. A section may be structural only, with no `_index.md` and no `_inherit.md`. This Website Dev Guide uses structural-only sections.\n\n## Example: Add a New Page\n\nSuppose you want a new page under `website-dev-guide/authoring-and-tooling/`.\n\nCreate the content bundle:\n\n```text\nwebsite/content/docs/0.7/website-dev-guide/authoring-and-tooling/new-page/index.md\n```\n\nThen add the page slug to the matching nav section:\n\n```toml\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n  \"new-page\",\n]\n```\n\nWithout the nav update, the page may exist on disk but stay absent from generated navigation.\n\n## Example: Reuse an Older Page without Copying the Content\n\nWhen a newer version should reuse the same page unchanged:\n\n1. create the same page folder in the newer version\n2. add an empty `inherit.md`\n3. keep the corresponding path in an older version with real `index.md` content\n\nExample:\n\n```text\nwebsite/content/docs/0.8/website-dev-guide/site-systems/media-publishing-workflow/inherit.md\n```\n\nDo not put front matter or body content into `inherit.md`.\n\n## Example: Diverge in a Newer Version\n\nIf a newer version needs different content, replace the marker with a real page:\n\n1. remove `inherit.md`\n2. create `index.md`\n3. write the new content for that version\n\nThat keeps the inheritance chain explicit and avoids template-side special cases.\n\n## Navigation Rules\n\nNavigation data controls order, not content. Keep these rules in mind:\n\n- slugs in the nav file must match the folder names on disk\n- changing a slug changes the public URL\n- page titles come from the page's own front matter, not from the nav file\n- section titles come from `docs-nav/\u003cversion\u003e.toml`\n\n## When to Use the Docs Editor Instead of Manual File Edits\n\nManual edits are normal for copy changes inside an existing page.\n\nUse the docs editor when the change is structural, for example:\n\n- creating a new book\n- creating, deleting, or renaming a section\n- creating, deleting, or renaming a page\n- changing docs structure across inherited versions\n\nThe docs editor keeps content paths and nav data in sync and refuses destructive changes that would silently overwrite newer authored content.\n\n## Validation\n\nFor docs and website changes, run:\n\n```bash\ncd website\nnpm run build\n```\n\nThat is the minimum meaningful verification because it runs theme generation, docs validation, inherited-doc materialization, Hugo rendering, and homepage CTA validation.\n", "1.0": "Book and section landing pages are optional. Either may be structural only, with no `_index.md` and no `_inherit.md`. A structural node remains in navigation but has no public landing route. This Website Dev Guide uses structural-only sections.\n+++\ntitle = \"Docs Authoring Workflow\"\n+++\n\nFor wording, list punctuation, and capitalization conventions, use the [Docs Style Guide](../docs-style-guide/).\n\n## Content Structure Rules\n\nThe docs system is path-derived.\n\n- book landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/_index.md`\n- section landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/_index.md`\n- article page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md`\n\nSection landing pages are optional. A section may be structural only, with no `_index.md` and no `_inherit.md`. This Website Dev Guide uses structural-only sections.\n\n## Example: Add a New Page\n\nSuppose you want a new page under `website-dev-guide/authoring-and-tooling/`.\n\nCreate the content bundle:\n\n```text\nwebsite/content/docs/0.7/website-dev-guide/authoring-and-tooling/new-page/index.md\n```\n\nThen add the page slug to the matching nav section:\n\n```toml\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n  \"new-page\",\n]\n```\n\nWithout the nav update, the page may exist on disk but stay absent from generated navigation.\n\n## Example: Reuse an Older Page without Copying the Content\n\nWhen a newer version should reuse the same page unchanged:\n\n1. create the same page folder in the newer version\n2. add an empty `inherit.md`\n3. keep the corresponding path in an older version with real `index.md` content\n\nExample:\n\n```text\nwebsite/content/docs/0.8/website-dev-guide/site-systems/media-publishing-workflow/inherit.md\n```\n\nDo not put front matter or body content into `inherit.md`.\n\n## Example: Diverge in a Newer Version\n\nIf a newer version needs different content, replace the marker with a real page:\n\n1. remove `inherit.md`\n2. create `index.md`\n3. write the new content for that version\n\nThat keeps the inheritance chain explicit and avoids template-side special cases.\n\n## Navigation Rules\n\nNavigation data controls order, not content. Keep these rules in mind:\n\n- slugs in the nav file must match the folder names on disk\n- changing a slug changes the public URL\n- page titles come from the page's own front matter, not from the nav file\n- section titles come from `docs-nav/\u003cversion\u003e.toml`\n\n## When to Use the Docs Editor Instead of Manual File Edits\n\nManual edits are normal for copy changes inside an existing page.\n\nUse the docs editor when the change is structural, for example:\n\n- creating a new book\n- creating, deleting, or renaming a section\n- creating, deleting, or renaming a page\n- changing docs structure across inherited versions\n\nThe docs editor keeps content paths and nav data in sync and refuses destructive changes that would silently overwrite newer authored content.\n\n## Validation\n\nFor docs and website changes, run:\n\n```bash\ncd website\nnpm run build\n```\n\nThat is the minimum meaningful verification because it runs theme generation, docs validation, inherited-doc materialization, Hugo rendering, and homepage CTA validation.\n", "2.0": "Book and section landing pages are optional. Either may be structural only, with no `_index.md` and no `_inherit.md`. A structural node remains in navigation but has no public landing route. This Website Dev Guide uses structural-only sections.\n+++\ntitle = \"Docs Authoring Workflow\"\n+++\n\nFor wording, list punctuation, and capitalization conventions, use the [Docs Style Guide](../docs-style-guide/).\n\n## Content Structure Rules\n\nThe docs system is path-derived.\n\n- book landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/_index.md`\n- section landing page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/_index.md`\n- article page: `website/content/docs/\u003cversion\u003e/\u003cbook\u003e/\u003csection\u003e/\u003cpage\u003e/index.md`\n\nSection landing pages are optional. A section may be structural only, with no `_index.md` and no `_inherit.md`. This Website Dev Guide uses structural-only sections.\n\n## Example: Add a New Page\n\nSuppose you want a new page under `website-dev-guide/authoring-and-tooling/`.\n\nCreate the content bundle:\n\n```text\nwebsite/content/docs/0.7/website-dev-guide/authoring-and-tooling/new-page/index.md\n```\n\nThen add the page slug to the matching nav section:\n\n```toml\n[pages.website-dev-guide.authoring-and-tooling]\nitems = [\n  \"docs-authoring-workflow\",\n  \"docs-editor-tool\",\n  \"new-page\",\n]\n```\n\nWithout the nav update, the page may exist on disk but stay absent from generated navigation.\n\n## Example: Reuse an Older Page without Copying the Content\n\nWhen a newer version should reuse the same page unchanged:\n\n1. create the same page folder in the newer version\n2. add an empty `inherit.md`\n3. keep the corresponding path in an older version with real `index.md` content\n\nExample:\n\n```text\nwebsite/content/docs/0.8/website-dev-guide/site-systems/media-publishing-workflow/inherit.md\n```\n\nDo not put front matter or body content into `inherit.md`.\n\n## Example: Diverge in a Newer Version\n\nIf a newer version needs different content, replace the marker with a real page:\n\n1. remove `inherit.md`\n2. create `index.md`\n3. write the new content for that version\n\nThat keeps the inheritance chain explicit and avoids template-side special cases.\n\n## Navigation Rules\n\nNavigation data controls order, not content. Keep these rules in mind:\n\n- slugs in the nav file must match the folder names on disk\n- changing a slug changes the public URL\n- page titles come from the page's own front matter, not from the nav file\n- section titles come from `docs-nav/\u003cversion\u003e.toml`\n\n## When to Use the Docs Editor Instead of Manual File Edits\n\nManual edits are normal for copy changes inside an existing page.\n\nUse the docs editor when the change is structural, for example:\n\n- creating a new book\n- creating, deleting, or renaming a section\n- creating, deleting, or renaming a page\n- changing docs structure across inherited versions\n\nThe docs editor keeps content paths and nav data in sync and refuses destructive changes that would silently overwrite newer authored content.\n\n## Validation\n\nFor docs and website changes, run:\n\n```bash\ncd website\nnpm run build\n```\n\nThat is the minimum meaningful verification because it runs theme generation, docs validation, inherited-doc materialization, Hugo rendering, and homepage CTA validation.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:website-dev-guide/authoring-and-tooling/docs-style-guide", "parent_id": "section:website-dev-guide/authoring-and-tooling", "depth": 2, "kind": "page", "label": "docs-style-guide", "title": "Docs Style Guide", "path": "website-dev-guide/authoring-and-tooling/docs-style-guide", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Docs Style Guide\"\n+++\n\nUse this page as the canonical copy style reference for published docs.\n\n## Language and Writing Style\n\n- Clarity and readability are paramount.\n- Use simple but correct language.\n- Don't be nitpicky or wordy.\n- Use contracted instead of expanded forms, e.g. `we're` instead of `we are`.\n- Explain (as appropriate) the following:\n  - why things are the way they are\n  - how to use things\n  - when to use things\n\n## Lists\n\n### Sentence Style\n\nUse one list style per list. Do not mix sentence bullets and fragment bullets.\n\n- Sentence lists use complete sentences.\n   - Sentence bullets start with a capital letter and end with a full stop.\n   - After a colon, capitalize the next word when what follows is a sentence.\n- Fragment lists use short labels, file names, commands, paths, shortcuts, or other bare literals.\n   - Fragment bullets preserve literal casing and usually do not take a full stop.\n   - Prefer short, parallel labels for control or feature lists, for example `Zoom`, `Pan`, `Rotate`.\n   - If a fragment needs explanation, rewrite it as a sentence bullet or use a table.\n\nPreferred sentence list:\n\n```markdown\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n```\n\nValid fragment list:\n\n```markdown\n- `config.toml`\n- `website/content/docs/`\n- `Ctrl` + `K`\n```\n\n### List Structure\n\n- Make use of multiple hierarchies to structure content.\n- Mixing ordered and unordered lists is allowed.\n\n### Ordered Lists\n\n- Don't number ordered lists consecutively, use `1.` for all items. Let the Markdown renderer do the numbering.\n\n## Headings\n\n- Use multiple heading levels to logically group and structure content. Don't limit yourself to h2.\n\n## More Information\n\nSee [Docs Authoring Workflow](../docs-authoring-workflow/) for where copy edits fit into the docs workflow, and [Docs Editor Tool](../docs-editor-tool/) for structural docs changes.\n", "0.8": "+++\ntitle = \"Docs Style Guide\"\n+++\n\nUse this page as the canonical copy style reference for published docs.\n\n## Language and Writing Style\n\n- Clarity and readability are paramount.\n- Use simple but correct language.\n- Don't be nitpicky or wordy.\n- Use contracted instead of expanded forms, e.g. `we're` instead of `we are`.\n- Explain (as appropriate) the following:\n  - why things are the way they are\n  - how to use things\n  - when to use things\n\n## Lists\n\n### Sentence Style\n\nUse one list style per list. Do not mix sentence bullets and fragment bullets.\n\n- Sentence lists use complete sentences.\n   - Sentence bullets start with a capital letter and end with a full stop.\n   - After a colon, capitalize the next word when what follows is a sentence.\n- Fragment lists use short labels, file names, commands, paths, shortcuts, or other bare literals.\n   - Fragment bullets preserve literal casing and usually do not take a full stop.\n   - Prefer short, parallel labels for control or feature lists, for example `Zoom`, `Pan`, `Rotate`.\n   - If a fragment needs explanation, rewrite it as a sentence bullet or use a table.\n\nPreferred sentence list:\n\n```markdown\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n```\n\nValid fragment list:\n\n```markdown\n- `config.toml`\n- `website/content/docs/`\n- `Ctrl` + `K`\n```\n\n### List Structure\n\n- Make use of multiple hierarchies to structure content.\n- Mixing ordered and unordered lists is allowed.\n\n### Ordered Lists\n\n- Don't number ordered lists consecutively, use `1.` for all items. Let the Markdown renderer do the numbering.\n\n## Headings\n\n- Use multiple heading levels to logically group and structure content. Don't limit yourself to h2.\n\n## More Information\n\nSee [Docs Authoring Workflow](../docs-authoring-workflow/) for where copy edits fit into the docs workflow, and [Docs Editor Tool](../docs-editor-tool/) for structural docs changes.\n", "0.9": "+++\ntitle = \"Docs Style Guide\"\n+++\n\nUse this page as the canonical copy style reference for published docs.\n\n## Language and Writing Style\n\n- Clarity and readability are paramount.\n- Use simple but correct language.\n- Don't be nitpicky or wordy.\n- Use contracted instead of expanded forms, e.g. `we're` instead of `we are`.\n- Explain (as appropriate) the following:\n  - why things are the way they are\n  - how to use things\n  - when to use things\n\n## Lists\n\n### Sentence Style\n\nUse one list style per list. Do not mix sentence bullets and fragment bullets.\n\n- Sentence lists use complete sentences.\n   - Sentence bullets start with a capital letter and end with a full stop.\n   - After a colon, capitalize the next word when what follows is a sentence.\n- Fragment lists use short labels, file names, commands, paths, shortcuts, or other bare literals.\n   - Fragment bullets preserve literal casing and usually do not take a full stop.\n   - Prefer short, parallel labels for control or feature lists, for example `Zoom`, `Pan`, `Rotate`.\n   - If a fragment needs explanation, rewrite it as a sentence bullet or use a table.\n\nPreferred sentence list:\n\n```markdown\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n```\n\nValid fragment list:\n\n```markdown\n- `config.toml`\n- `website/content/docs/`\n- `Ctrl` + `K`\n```\n\n### List Structure\n\n- Make use of multiple hierarchies to structure content.\n- Mixing ordered and unordered lists is allowed.\n\n### Ordered Lists\n\n- Don't number ordered lists consecutively, use `1.` for all items. Let the Markdown renderer do the numbering.\n\n## Headings\n\n- Use multiple heading levels to logically group and structure content. Don't limit yourself to h2.\n\n## More Information\n\nSee [Docs Authoring Workflow](../docs-authoring-workflow/) for where copy edits fit into the docs workflow, and [Docs Editor Tool](../docs-editor-tool/) for structural docs changes.\n", "1.0": "+++\ntitle = \"Docs Style Guide\"\n+++\n\nUse this page as the canonical copy style reference for published docs.\n\n## Language and Writing Style\n\n- Clarity and readability are paramount.\n- Use simple but correct language.\n- Don't be nitpicky or wordy.\n- Use contracted instead of expanded forms, e.g. `we're` instead of `we are`.\n- Explain (as appropriate) the following:\n  - why things are the way they are\n  - how to use things\n  - when to use things\n\n## Lists\n\n### Sentence Style\n\nUse one list style per list. Do not mix sentence bullets and fragment bullets.\n\n- Sentence lists use complete sentences.\n   - Sentence bullets start with a capital letter and end with a full stop.\n   - After a colon, capitalize the next word when what follows is a sentence.\n- Fragment lists use short labels, file names, commands, paths, shortcuts, or other bare literals.\n   - Fragment bullets preserve literal casing and usually do not take a full stop.\n   - Prefer short, parallel labels for control or feature lists, for example `Zoom`, `Pan`, `Rotate`.\n   - If a fragment needs explanation, rewrite it as a sentence bullet or use a table.\n\nPreferred sentence list:\n\n```markdown\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n```\n\nValid fragment list:\n\n```markdown\n- `config.toml`\n- `website/content/docs/`\n- `Ctrl` + `K`\n```\n\n### List Structure\n\n- Make use of multiple hierarchies to structure content.\n- Mixing ordered and unordered lists is allowed.\n\n### Ordered Lists\n\n- Don't number ordered lists consecutively, use `1.` for all items. Let the Markdown renderer do the numbering.\n\n## Headings\n\n- Use multiple heading levels to logically group and structure content. Don't limit yourself to h2.\n\n## More Information\n\nSee [Docs Authoring Workflow](../docs-authoring-workflow/) for where copy edits fit into the docs workflow, and [Docs Editor Tool](../docs-editor-tool/) for structural docs changes.\n", "2.0": "+++\ntitle = \"Docs Style Guide\"\n+++\n\nUse this page as the canonical copy style reference for published docs.\n\n## Language and Writing Style\n\n- Clarity and readability are paramount.\n- Use simple but correct language.\n- Don't be nitpicky or wordy.\n- Use contracted instead of expanded forms, e.g. `we're` instead of `we are`.\n- Explain (as appropriate) the following:\n  - why things are the way they are\n  - how to use things\n  - when to use things\n\n## Lists\n\n### Sentence Style\n\nUse one list style per list. Do not mix sentence bullets and fragment bullets.\n\n- Sentence lists use complete sentences.\n   - Sentence bullets start with a capital letter and end with a full stop.\n   - After a colon, capitalize the next word when what follows is a sentence.\n- Fragment lists use short labels, file names, commands, paths, shortcuts, or other bare literals.\n   - Fragment bullets preserve literal casing and usually do not take a full stop.\n   - Prefer short, parallel labels for control or feature lists, for example `Zoom`, `Pan`, `Rotate`.\n   - If a fragment needs explanation, rewrite it as a sentence bullet or use a table.\n\nPreferred sentence list:\n\n```markdown\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n```\n\nValid fragment list:\n\n```markdown\n- `config.toml`\n- `website/content/docs/`\n- `Ctrl` + `K`\n```\n\n### List Structure\n\n- Make use of multiple hierarchies to structure content.\n- Mixing ordered and unordered lists is allowed.\n\n### Ordered Lists\n\n- Don't number ordered lists consecutively, use `1.` for all items. Let the Markdown renderer do the numbering.\n\n## Headings\n\n- Use multiple heading levels to logically group and structure content. Don't limit yourself to h2.\n\n## More Information\n\nSee [Docs Authoring Workflow](../docs-authoring-workflow/) for where copy edits fit into the docs workflow, and [Docs Editor Tool](../docs-editor-tool/) for structural docs changes.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Docs Style Guide\"\n+++\n\nUse this page as the canonical copy style reference for published docs.\n\n## Language and Writing Style\n\n- Clarity and readability are paramount.\n- Use simple but correct language.\n- Don't be nitpicky or wordy.\n- Use contracted instead of expanded forms, e.g. `we're` instead of `we are`.\n- Explain (as appropriate) the following:\n  - why things are the way they are\n  - how to use things\n  - when to use things\n\n## Lists\n\n### Sentence Style\n\nUse one list style per list. Do not mix sentence bullets and fragment bullets.\n\n- Sentence lists use complete sentences.\n   - Sentence bullets start with a capital letter and end with a full stop.\n   - After a colon, capitalize the next word when what follows is a sentence.\n- Fragment lists use short labels, file names, commands, paths, shortcuts, or other bare literals.\n   - Fragment bullets preserve literal casing and usually do not take a full stop.\n   - Prefer short, parallel labels for control or feature lists, for example `Zoom`, `Pan`, `Rotate`.\n   - If a fragment needs explanation, rewrite it as a sentence bullet or use a table.\n\nPreferred sentence list:\n\n```markdown\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n```\n\nValid fragment list:\n\n```markdown\n- `config.toml`\n- `website/content/docs/`\n- `Ctrl` + `K`\n```\n\n### List Structure\n\n- Make use of multiple hierarchies to structure content.\n- Mixing ordered and unordered lists is allowed.\n\n### Ordered Lists\n\n- Don't number ordered lists consecutively, use `1.` for all items. Let the Markdown renderer do the numbering.\n\n## Headings\n\n- Use multiple heading levels to logically group and structure content. Don't limit yourself to h2.\n\n## More Information\n\nSee [Docs Authoring Workflow](../docs-authoring-workflow/) for where copy edits fit into the docs workflow, and [Docs Editor Tool](../docs-editor-tool/) for structural docs changes.\n", "0.8": "+++\ntitle = \"Docs Style Guide\"\n+++\n\nUse this page as the canonical copy style reference for published docs.\n\n## Language and Writing Style\n\n- Clarity and readability are paramount.\n- Use simple but correct language.\n- Don't be nitpicky or wordy.\n- Use contracted instead of expanded forms, e.g. `we're` instead of `we are`.\n- Explain (as appropriate) the following:\n  - why things are the way they are\n  - how to use things\n  - when to use things\n\n## Lists\n\n### Sentence Style\n\nUse one list style per list. Do not mix sentence bullets and fragment bullets.\n\n- Sentence lists use complete sentences.\n   - Sentence bullets start with a capital letter and end with a full stop.\n   - After a colon, capitalize the next word when what follows is a sentence.\n- Fragment lists use short labels, file names, commands, paths, shortcuts, or other bare literals.\n   - Fragment bullets preserve literal casing and usually do not take a full stop.\n   - Prefer short, parallel labels for control or feature lists, for example `Zoom`, `Pan`, `Rotate`.\n   - If a fragment needs explanation, rewrite it as a sentence bullet or use a table.\n\nPreferred sentence list:\n\n```markdown\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n```\n\nValid fragment list:\n\n```markdown\n- `config.toml`\n- `website/content/docs/`\n- `Ctrl` + `K`\n```\n\n### List Structure\n\n- Make use of multiple hierarchies to structure content.\n- Mixing ordered and unordered lists is allowed.\n\n### Ordered Lists\n\n- Don't number ordered lists consecutively, use `1.` for all items. Let the Markdown renderer do the numbering.\n\n## Headings\n\n- Use multiple heading levels to logically group and structure content. Don't limit yourself to h2.\n\n## More Information\n\nSee [Docs Authoring Workflow](../docs-authoring-workflow/) for where copy edits fit into the docs workflow, and [Docs Editor Tool](../docs-editor-tool/) for structural docs changes.\n", "0.9": "+++\ntitle = \"Docs Style Guide\"\n+++\n\nUse this page as the canonical copy style reference for published docs.\n\n## Language and Writing Style\n\n- Clarity and readability are paramount.\n- Use simple but correct language.\n- Don't be nitpicky or wordy.\n- Use contracted instead of expanded forms, e.g. `we're` instead of `we are`.\n- Explain (as appropriate) the following:\n  - why things are the way they are\n  - how to use things\n  - when to use things\n\n## Lists\n\n### Sentence Style\n\nUse one list style per list. Do not mix sentence bullets and fragment bullets.\n\n- Sentence lists use complete sentences.\n   - Sentence bullets start with a capital letter and end with a full stop.\n   - After a colon, capitalize the next word when what follows is a sentence.\n- Fragment lists use short labels, file names, commands, paths, shortcuts, or other bare literals.\n   - Fragment bullets preserve literal casing and usually do not take a full stop.\n   - Prefer short, parallel labels for control or feature lists, for example `Zoom`, `Pan`, `Rotate`.\n   - If a fragment needs explanation, rewrite it as a sentence bullet or use a table.\n\nPreferred sentence list:\n\n```markdown\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n```\n\nValid fragment list:\n\n```markdown\n- `config.toml`\n- `website/content/docs/`\n- `Ctrl` + `K`\n```\n\n### List Structure\n\n- Make use of multiple hierarchies to structure content.\n- Mixing ordered and unordered lists is allowed.\n\n### Ordered Lists\n\n- Don't number ordered lists consecutively, use `1.` for all items. Let the Markdown renderer do the numbering.\n\n## Headings\n\n- Use multiple heading levels to logically group and structure content. Don't limit yourself to h2.\n\n## More Information\n\nSee [Docs Authoring Workflow](../docs-authoring-workflow/) for where copy edits fit into the docs workflow, and [Docs Editor Tool](../docs-editor-tool/) for structural docs changes.\n", "1.0": "+++\ntitle = \"Docs Style Guide\"\n+++\n\nUse this page as the canonical copy style reference for published docs.\n\n## Language and Writing Style\n\n- Clarity and readability are paramount.\n- Use simple but correct language.\n- Don't be nitpicky or wordy.\n- Use contracted instead of expanded forms, e.g. `we're` instead of `we are`.\n- Explain (as appropriate) the following:\n  - why things are the way they are\n  - how to use things\n  - when to use things\n\n## Lists\n\n### Sentence Style\n\nUse one list style per list. Do not mix sentence bullets and fragment bullets.\n\n- Sentence lists use complete sentences.\n   - Sentence bullets start with a capital letter and end with a full stop.\n   - After a colon, capitalize the next word when what follows is a sentence.\n- Fragment lists use short labels, file names, commands, paths, shortcuts, or other bare literals.\n   - Fragment bullets preserve literal casing and usually do not take a full stop.\n   - Prefer short, parallel labels for control or feature lists, for example `Zoom`, `Pan`, `Rotate`.\n   - If a fragment needs explanation, rewrite it as a sentence bullet or use a table.\n\nPreferred sentence list:\n\n```markdown\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n```\n\nValid fragment list:\n\n```markdown\n- `config.toml`\n- `website/content/docs/`\n- `Ctrl` + `K`\n```\n\n### List Structure\n\n- Make use of multiple hierarchies to structure content.\n- Mixing ordered and unordered lists is allowed.\n\n### Ordered Lists\n\n- Don't number ordered lists consecutively, use `1.` for all items. Let the Markdown renderer do the numbering.\n\n## Headings\n\n- Use multiple heading levels to logically group and structure content. Don't limit yourself to h2.\n\n## More Information\n\nSee [Docs Authoring Workflow](../docs-authoring-workflow/) for where copy edits fit into the docs workflow, and [Docs Editor Tool](../docs-editor-tool/) for structural docs changes.\n", "2.0": "+++\ntitle = \"Docs Style Guide\"\n+++\n\nUse this page as the canonical copy style reference for published docs.\n\n## Language and Writing Style\n\n- Clarity and readability are paramount.\n- Use simple but correct language.\n- Don't be nitpicky or wordy.\n- Use contracted instead of expanded forms, e.g. `we're` instead of `we are`.\n- Explain (as appropriate) the following:\n  - why things are the way they are\n  - how to use things\n  - when to use things\n\n## Lists\n\n### Sentence Style\n\nUse one list style per list. Do not mix sentence bullets and fragment bullets.\n\n- Sentence lists use complete sentences.\n   - Sentence bullets start with a capital letter and end with a full stop.\n   - After a colon, capitalize the next word when what follows is a sentence.\n- Fragment lists use short labels, file names, commands, paths, shortcuts, or other bare literals.\n   - Fragment bullets preserve literal casing and usually do not take a full stop.\n   - Prefer short, parallel labels for control or feature lists, for example `Zoom`, `Pan`, `Rotate`.\n   - If a fragment needs explanation, rewrite it as a sentence bullet or use a table.\n\nPreferred sentence list:\n\n```markdown\n- Focus matters: Shortcuts act on the item that currently has focus.\n- The active pane matters: In dual-pane mode, many browser commands target the currently active pane.\n- Important actions stay discoverable: The same actions are also available through visible controls and the in-app shortcuts help.\n```\n\nValid fragment list:\n\n```markdown\n- `config.toml`\n- `website/content/docs/`\n- `Ctrl` + `K`\n```\n\n### List Structure\n\n- Make use of multiple hierarchies to structure content.\n- Mixing ordered and unordered lists is allowed.\n\n### Ordered Lists\n\n- Don't number ordered lists consecutively, use `1.` for all items. Let the Markdown renderer do the numbering.\n\n## Headings\n\n- Use multiple heading levels to logically group and structure content. Don't limit yourself to h2.\n\n## More Information\n\nSee [Docs Authoring Workflow](../docs-authoring-workflow/) for where copy edits fit into the docs workflow, and [Docs Editor Tool](../docs-editor-tool/) for structural docs changes.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:website-dev-guide/authoring-and-tooling/docs-shortcodes", "parent_id": "section:website-dev-guide/authoring-and-tooling", "depth": 2, "kind": "page", "label": "docs-shortcodes", "title": "Docs Shortcodes", "path": "website-dev-guide/authoring-and-tooling/docs-shortcodes", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Docs Shortcodes\"\n+++\n\nUse this page when you need a docs-only Hugo shortcode in published documentation content.\n\n## Current Shortcodes\n\nThe website currently exposes one docs shortcode for normal content authors:\n\n- `admonition`: render a styled callout block for notes, tips, warnings, and similar emphasis\n\n## Admonition Shortcode\n\nUse the `admonition` shortcode for highlighted callout content inside a docs page.\n\nBasic form:\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Info\" */\u003e}}\nThis is an informational callout.\n{{\u003c/* /admonition */\u003e}}\n```\n\nThe body is rendered as normal Markdown, so links, emphasis, lists, and other inline formatting work inside the block.\n\n### Supported Types\n\nThe shortcode supports these `type` values:\n\n- `note`\n- `tip`\n- `info`\n- `warning`\n- `danger`\n\nIf `type` is omitted or invalid, it defaults to `note`.\n\n### Title Behavior\n\nThe `title` parameter is optional.\n\n- If you provide a non-empty title, the admonition renders a title line.\n- If you omit `title`, no title line is rendered.\n\n### Examples\n\n#### Note Callout\n\n```md\n{{\u003c/* admonition type=\"note\" */\u003e}}\nThis is a note without a title.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"note\" \u003e}}\nThis is a note without a title.\n{{\u003c /admonition \u003e}}\n\n#### Tip Callout\n\n```md\n{{\u003c/* admonition type=\"tip\" title=\"Tip\" */\u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"tip\" title=\"Tip\" \u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c /admonition \u003e}}\n\n#### Informational Callout\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Background\" */\u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"info\" title=\"Background\" \u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c /admonition \u003e}}\n\n#### Warning Callout\n\n```md\n{{\u003c/* admonition type=\"warning\" title=\"Do Not Edit Marker Files\" */\u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"warning\" title=\"Do Not Edit Marker Files\" \u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c /admonition \u003e}}\n\n#### Danger Callout\n\n```md\n{{\u003c/* admonition type=\"danger\" title=\"Destructive Change\" */\u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"danger\" title=\"Destructive Change\" \u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c /admonition \u003e}}\n\n### Implementation Reference\n\nThe shortcode implementation lives in `themes/sambee/layouts/shortcodes/admonition.html`.\n\nThe styling for the rendered admonition variants lives in `themes/sambee/assets/css/content.css`.\n", "0.8": "+++\ntitle = \"Docs Shortcodes\"\n+++\n\nUse this page when you need a docs-only Hugo shortcode in published documentation content.\n\n## Current Shortcodes\n\nThe website currently exposes one docs shortcode for normal content authors:\n\n- `admonition`: render a styled callout block for notes, tips, warnings, and similar emphasis\n\n## Admonition Shortcode\n\nUse the `admonition` shortcode for highlighted callout content inside a docs page.\n\nBasic form:\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Info\" */\u003e}}\nThis is an informational callout.\n{{\u003c/* /admonition */\u003e}}\n```\n\nThe body is rendered as normal Markdown, so links, emphasis, lists, and other inline formatting work inside the block.\n\n### Supported Types\n\nThe shortcode supports these `type` values:\n\n- `note`\n- `tip`\n- `info`\n- `warning`\n- `danger`\n\nIf `type` is omitted or invalid, it defaults to `note`.\n\n### Title Behavior\n\nThe `title` parameter is optional.\n\n- If you provide a non-empty title, the admonition renders a title line.\n- If you omit `title`, no title line is rendered.\n\n### Examples\n\n#### Note Callout\n\n```md\n{{\u003c/* admonition type=\"note\" */\u003e}}\nThis is a note without a title.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"note\" \u003e}}\nThis is a note without a title.\n{{\u003c /admonition \u003e}}\n\n#### Tip Callout\n\n```md\n{{\u003c/* admonition type=\"tip\" title=\"Tip\" */\u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"tip\" title=\"Tip\" \u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c /admonition \u003e}}\n\n#### Informational Callout\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Background\" */\u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"info\" title=\"Background\" \u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c /admonition \u003e}}\n\n#### Warning Callout\n\n```md\n{{\u003c/* admonition type=\"warning\" title=\"Do Not Edit Marker Files\" */\u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"warning\" title=\"Do Not Edit Marker Files\" \u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c /admonition \u003e}}\n\n#### Danger Callout\n\n```md\n{{\u003c/* admonition type=\"danger\" title=\"Destructive Change\" */\u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"danger\" title=\"Destructive Change\" \u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c /admonition \u003e}}\n\n### Implementation Reference\n\nThe shortcode implementation lives in `themes/sambee/layouts/shortcodes/admonition.html`.\n\nThe styling for the rendered admonition variants lives in `themes/sambee/assets/css/content.css`.\n", "0.9": "+++\ntitle = \"Docs Shortcodes\"\n+++\n\nUse this page when you need a docs-only Hugo shortcode in published documentation content.\n\n## Current Shortcodes\n\nThe website currently exposes one docs shortcode for normal content authors:\n\n- `admonition`: render a styled callout block for notes, tips, warnings, and similar emphasis\n\n## Admonition Shortcode\n\nUse the `admonition` shortcode for highlighted callout content inside a docs page.\n\nBasic form:\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Info\" */\u003e}}\nThis is an informational callout.\n{{\u003c/* /admonition */\u003e}}\n```\n\nThe body is rendered as normal Markdown, so links, emphasis, lists, and other inline formatting work inside the block.\n\n### Supported Types\n\nThe shortcode supports these `type` values:\n\n- `note`\n- `tip`\n- `info`\n- `warning`\n- `danger`\n\nIf `type` is omitted or invalid, it defaults to `note`.\n\n### Title Behavior\n\nThe `title` parameter is optional.\n\n- If you provide a non-empty title, the admonition renders a title line.\n- If you omit `title`, no title line is rendered.\n\n### Examples\n\n#### Note Callout\n\n```md\n{{\u003c/* admonition type=\"note\" */\u003e}}\nThis is a note without a title.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"note\" \u003e}}\nThis is a note without a title.\n{{\u003c /admonition \u003e}}\n\n#### Tip Callout\n\n```md\n{{\u003c/* admonition type=\"tip\" title=\"Tip\" */\u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"tip\" title=\"Tip\" \u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c /admonition \u003e}}\n\n#### Informational Callout\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Background\" */\u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"info\" title=\"Background\" \u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c /admonition \u003e}}\n\n#### Warning Callout\n\n```md\n{{\u003c/* admonition type=\"warning\" title=\"Do Not Edit Marker Files\" */\u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"warning\" title=\"Do Not Edit Marker Files\" \u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c /admonition \u003e}}\n\n#### Danger Callout\n\n```md\n{{\u003c/* admonition type=\"danger\" title=\"Destructive Change\" */\u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"danger\" title=\"Destructive Change\" \u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c /admonition \u003e}}\n\n### Implementation Reference\n\nThe shortcode implementation lives in `themes/sambee/layouts/shortcodes/admonition.html`.\n\nThe styling for the rendered admonition variants lives in `themes/sambee/assets/css/content.css`.\n", "1.0": "+++\ntitle = \"Docs Shortcodes\"\n+++\n\nUse this page when you need a docs-only Hugo shortcode in published documentation content.\n\n## Current Shortcodes\n\nThe website currently exposes one docs shortcode for normal content authors:\n\n- `admonition`: render a styled callout block for notes, tips, warnings, and similar emphasis\n\n## Admonition Shortcode\n\nUse the `admonition` shortcode for highlighted callout content inside a docs page.\n\nBasic form:\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Info\" */\u003e}}\nThis is an informational callout.\n{{\u003c/* /admonition */\u003e}}\n```\n\nThe body is rendered as normal Markdown, so links, emphasis, lists, and other inline formatting work inside the block.\n\n### Supported Types\n\nThe shortcode supports these `type` values:\n\n- `note`\n- `tip`\n- `info`\n- `warning`\n- `danger`\n\nIf `type` is omitted or invalid, it defaults to `note`.\n\n### Title Behavior\n\nThe `title` parameter is optional.\n\n- If you provide a non-empty title, the admonition renders a title line.\n- If you omit `title`, no title line is rendered.\n\n### Examples\n\n#### Note Callout\n\n```md\n{{\u003c/* admonition type=\"note\" */\u003e}}\nThis is a note without a title.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"note\" \u003e}}\nThis is a note without a title.\n{{\u003c /admonition \u003e}}\n\n#### Tip Callout\n\n```md\n{{\u003c/* admonition type=\"tip\" title=\"Tip\" */\u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"tip\" title=\"Tip\" \u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c /admonition \u003e}}\n\n#### Informational Callout\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Background\" */\u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"info\" title=\"Background\" \u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c /admonition \u003e}}\n\n#### Warning Callout\n\n```md\n{{\u003c/* admonition type=\"warning\" title=\"Do Not Edit Marker Files\" */\u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"warning\" title=\"Do Not Edit Marker Files\" \u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c /admonition \u003e}}\n\n#### Danger Callout\n\n```md\n{{\u003c/* admonition type=\"danger\" title=\"Destructive Change\" */\u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"danger\" title=\"Destructive Change\" \u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c /admonition \u003e}}\n\n### Implementation Reference\n\nThe shortcode implementation lives in `themes/sambee/layouts/shortcodes/admonition.html`.\n\nThe styling for the rendered admonition variants lives in `themes/sambee/assets/css/content.css`.\n", "2.0": "+++\ntitle = \"Docs Shortcodes\"\n+++\n\nUse this page when you need a docs-only Hugo shortcode in published documentation content.\n\n## Current Shortcodes\n\nThe website currently exposes one docs shortcode for normal content authors:\n\n- `admonition`: render a styled callout block for notes, tips, warnings, and similar emphasis\n\n## Admonition Shortcode\n\nUse the `admonition` shortcode for highlighted callout content inside a docs page.\n\nBasic form:\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Info\" */\u003e}}\nThis is an informational callout.\n{{\u003c/* /admonition */\u003e}}\n```\n\nThe body is rendered as normal Markdown, so links, emphasis, lists, and other inline formatting work inside the block.\n\n### Supported Types\n\nThe shortcode supports these `type` values:\n\n- `note`\n- `tip`\n- `info`\n- `warning`\n- `danger`\n\nIf `type` is omitted or invalid, it defaults to `note`.\n\n### Title Behavior\n\nThe `title` parameter is optional.\n\n- If you provide a non-empty title, the admonition renders a title line.\n- If you omit `title`, no title line is rendered.\n\n### Examples\n\n#### Note Callout\n\n```md\n{{\u003c/* admonition type=\"note\" */\u003e}}\nThis is a note without a title.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"note\" \u003e}}\nThis is a note without a title.\n{{\u003c /admonition \u003e}}\n\n#### Tip Callout\n\n```md\n{{\u003c/* admonition type=\"tip\" title=\"Tip\" */\u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"tip\" title=\"Tip\" \u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c /admonition \u003e}}\n\n#### Informational Callout\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Background\" */\u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"info\" title=\"Background\" \u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c /admonition \u003e}}\n\n#### Warning Callout\n\n```md\n{{\u003c/* admonition type=\"warning\" title=\"Do Not Edit Marker Files\" */\u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"warning\" title=\"Do Not Edit Marker Files\" \u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c /admonition \u003e}}\n\n#### Danger Callout\n\n```md\n{{\u003c/* admonition type=\"danger\" title=\"Destructive Change\" */\u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"danger\" title=\"Destructive Change\" \u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c /admonition \u003e}}\n\n### Implementation Reference\n\nThe shortcode implementation lives in `themes/sambee/layouts/shortcodes/admonition.html`.\n\nThe styling for the rendered admonition variants lives in `themes/sambee/assets/css/content.css`.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Docs Shortcodes\"\n+++\n\nUse this page when you need a docs-only Hugo shortcode in published documentation content.\n\n## Current Shortcodes\n\nThe website currently exposes one docs shortcode for normal content authors:\n\n- `admonition`: render a styled callout block for notes, tips, warnings, and similar emphasis\n\n## Admonition Shortcode\n\nUse the `admonition` shortcode for highlighted callout content inside a docs page.\n\nBasic form:\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Info\" */\u003e}}\nThis is an informational callout.\n{{\u003c/* /admonition */\u003e}}\n```\n\nThe body is rendered as normal Markdown, so links, emphasis, lists, and other inline formatting work inside the block.\n\n### Supported Types\n\nThe shortcode supports these `type` values:\n\n- `note`\n- `tip`\n- `info`\n- `warning`\n- `danger`\n\nIf `type` is omitted or invalid, it defaults to `note`.\n\n### Title Behavior\n\nThe `title` parameter is optional.\n\n- If you provide a non-empty title, the admonition renders a title line.\n- If you omit `title`, no title line is rendered.\n\n### Examples\n\n#### Note Callout\n\n```md\n{{\u003c/* admonition type=\"note\" */\u003e}}\nThis is a note without a title.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"note\" \u003e}}\nThis is a note without a title.\n{{\u003c /admonition \u003e}}\n\n#### Tip Callout\n\n```md\n{{\u003c/* admonition type=\"tip\" title=\"Tip\" */\u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"tip\" title=\"Tip\" \u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c /admonition \u003e}}\n\n#### Informational Callout\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Background\" */\u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"info\" title=\"Background\" \u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c /admonition \u003e}}\n\n#### Warning Callout\n\n```md\n{{\u003c/* admonition type=\"warning\" title=\"Do Not Edit Marker Files\" */\u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"warning\" title=\"Do Not Edit Marker Files\" \u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c /admonition \u003e}}\n\n#### Danger Callout\n\n```md\n{{\u003c/* admonition type=\"danger\" title=\"Destructive Change\" */\u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"danger\" title=\"Destructive Change\" \u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c /admonition \u003e}}\n\n### Implementation Reference\n\nThe shortcode implementation lives in `themes/sambee/layouts/shortcodes/admonition.html`.\n\nThe styling for the rendered admonition variants lives in `themes/sambee/assets/css/content.css`.\n", "0.8": "+++\ntitle = \"Docs Shortcodes\"\n+++\n\nUse this page when you need a docs-only Hugo shortcode in published documentation content.\n\n## Current Shortcodes\n\nThe website currently exposes one docs shortcode for normal content authors:\n\n- `admonition`: render a styled callout block for notes, tips, warnings, and similar emphasis\n\n## Admonition Shortcode\n\nUse the `admonition` shortcode for highlighted callout content inside a docs page.\n\nBasic form:\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Info\" */\u003e}}\nThis is an informational callout.\n{{\u003c/* /admonition */\u003e}}\n```\n\nThe body is rendered as normal Markdown, so links, emphasis, lists, and other inline formatting work inside the block.\n\n### Supported Types\n\nThe shortcode supports these `type` values:\n\n- `note`\n- `tip`\n- `info`\n- `warning`\n- `danger`\n\nIf `type` is omitted or invalid, it defaults to `note`.\n\n### Title Behavior\n\nThe `title` parameter is optional.\n\n- If you provide a non-empty title, the admonition renders a title line.\n- If you omit `title`, no title line is rendered.\n\n### Examples\n\n#### Note Callout\n\n```md\n{{\u003c/* admonition type=\"note\" */\u003e}}\nThis is a note without a title.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"note\" \u003e}}\nThis is a note without a title.\n{{\u003c /admonition \u003e}}\n\n#### Tip Callout\n\n```md\n{{\u003c/* admonition type=\"tip\" title=\"Tip\" */\u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"tip\" title=\"Tip\" \u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c /admonition \u003e}}\n\n#### Informational Callout\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Background\" */\u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"info\" title=\"Background\" \u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c /admonition \u003e}}\n\n#### Warning Callout\n\n```md\n{{\u003c/* admonition type=\"warning\" title=\"Do Not Edit Marker Files\" */\u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"warning\" title=\"Do Not Edit Marker Files\" \u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c /admonition \u003e}}\n\n#### Danger Callout\n\n```md\n{{\u003c/* admonition type=\"danger\" title=\"Destructive Change\" */\u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"danger\" title=\"Destructive Change\" \u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c /admonition \u003e}}\n\n### Implementation Reference\n\nThe shortcode implementation lives in `themes/sambee/layouts/shortcodes/admonition.html`.\n\nThe styling for the rendered admonition variants lives in `themes/sambee/assets/css/content.css`.\n", "0.9": "+++\ntitle = \"Docs Shortcodes\"\n+++\n\nUse this page when you need a docs-only Hugo shortcode in published documentation content.\n\n## Current Shortcodes\n\nThe website currently exposes one docs shortcode for normal content authors:\n\n- `admonition`: render a styled callout block for notes, tips, warnings, and similar emphasis\n\n## Admonition Shortcode\n\nUse the `admonition` shortcode for highlighted callout content inside a docs page.\n\nBasic form:\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Info\" */\u003e}}\nThis is an informational callout.\n{{\u003c/* /admonition */\u003e}}\n```\n\nThe body is rendered as normal Markdown, so links, emphasis, lists, and other inline formatting work inside the block.\n\n### Supported Types\n\nThe shortcode supports these `type` values:\n\n- `note`\n- `tip`\n- `info`\n- `warning`\n- `danger`\n\nIf `type` is omitted or invalid, it defaults to `note`.\n\n### Title Behavior\n\nThe `title` parameter is optional.\n\n- If you provide a non-empty title, the admonition renders a title line.\n- If you omit `title`, no title line is rendered.\n\n### Examples\n\n#### Note Callout\n\n```md\n{{\u003c/* admonition type=\"note\" */\u003e}}\nThis is a note without a title.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"note\" \u003e}}\nThis is a note without a title.\n{{\u003c /admonition \u003e}}\n\n#### Tip Callout\n\n```md\n{{\u003c/* admonition type=\"tip\" title=\"Tip\" */\u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"tip\" title=\"Tip\" \u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c /admonition \u003e}}\n\n#### Informational Callout\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Background\" */\u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"info\" title=\"Background\" \u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c /admonition \u003e}}\n\n#### Warning Callout\n\n```md\n{{\u003c/* admonition type=\"warning\" title=\"Do Not Edit Marker Files\" */\u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"warning\" title=\"Do Not Edit Marker Files\" \u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c /admonition \u003e}}\n\n#### Danger Callout\n\n```md\n{{\u003c/* admonition type=\"danger\" title=\"Destructive Change\" */\u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"danger\" title=\"Destructive Change\" \u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c /admonition \u003e}}\n\n### Implementation Reference\n\nThe shortcode implementation lives in `themes/sambee/layouts/shortcodes/admonition.html`.\n\nThe styling for the rendered admonition variants lives in `themes/sambee/assets/css/content.css`.\n", "1.0": "+++\ntitle = \"Docs Shortcodes\"\n+++\n\nUse this page when you need a docs-only Hugo shortcode in published documentation content.\n\n## Current Shortcodes\n\nThe website currently exposes one docs shortcode for normal content authors:\n\n- `admonition`: render a styled callout block for notes, tips, warnings, and similar emphasis\n\n## Admonition Shortcode\n\nUse the `admonition` shortcode for highlighted callout content inside a docs page.\n\nBasic form:\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Info\" */\u003e}}\nThis is an informational callout.\n{{\u003c/* /admonition */\u003e}}\n```\n\nThe body is rendered as normal Markdown, so links, emphasis, lists, and other inline formatting work inside the block.\n\n### Supported Types\n\nThe shortcode supports these `type` values:\n\n- `note`\n- `tip`\n- `info`\n- `warning`\n- `danger`\n\nIf `type` is omitted or invalid, it defaults to `note`.\n\n### Title Behavior\n\nThe `title` parameter is optional.\n\n- If you provide a non-empty title, the admonition renders a title line.\n- If you omit `title`, no title line is rendered.\n\n### Examples\n\n#### Note Callout\n\n```md\n{{\u003c/* admonition type=\"note\" */\u003e}}\nThis is a note without a title.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"note\" \u003e}}\nThis is a note without a title.\n{{\u003c /admonition \u003e}}\n\n#### Tip Callout\n\n```md\n{{\u003c/* admonition type=\"tip\" title=\"Tip\" */\u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"tip\" title=\"Tip\" \u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c /admonition \u003e}}\n\n#### Informational Callout\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Background\" */\u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"info\" title=\"Background\" \u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c /admonition \u003e}}\n\n#### Warning Callout\n\n```md\n{{\u003c/* admonition type=\"warning\" title=\"Do Not Edit Marker Files\" */\u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"warning\" title=\"Do Not Edit Marker Files\" \u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c /admonition \u003e}}\n\n#### Danger Callout\n\n```md\n{{\u003c/* admonition type=\"danger\" title=\"Destructive Change\" */\u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"danger\" title=\"Destructive Change\" \u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c /admonition \u003e}}\n\n### Implementation Reference\n\nThe shortcode implementation lives in `themes/sambee/layouts/shortcodes/admonition.html`.\n\nThe styling for the rendered admonition variants lives in `themes/sambee/assets/css/content.css`.\n", "2.0": "+++\ntitle = \"Docs Shortcodes\"\n+++\n\nUse this page when you need a docs-only Hugo shortcode in published documentation content.\n\n## Current Shortcodes\n\nThe website currently exposes one docs shortcode for normal content authors:\n\n- `admonition`: render a styled callout block for notes, tips, warnings, and similar emphasis\n\n## Admonition Shortcode\n\nUse the `admonition` shortcode for highlighted callout content inside a docs page.\n\nBasic form:\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Info\" */\u003e}}\nThis is an informational callout.\n{{\u003c/* /admonition */\u003e}}\n```\n\nThe body is rendered as normal Markdown, so links, emphasis, lists, and other inline formatting work inside the block.\n\n### Supported Types\n\nThe shortcode supports these `type` values:\n\n- `note`\n- `tip`\n- `info`\n- `warning`\n- `danger`\n\nIf `type` is omitted or invalid, it defaults to `note`.\n\n### Title Behavior\n\nThe `title` parameter is optional.\n\n- If you provide a non-empty title, the admonition renders a title line.\n- If you omit `title`, no title line is rendered.\n\n### Examples\n\n#### Note Callout\n\n```md\n{{\u003c/* admonition type=\"note\" */\u003e}}\nThis is a note without a title.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"note\" \u003e}}\nThis is a note without a title.\n{{\u003c /admonition \u003e}}\n\n#### Tip Callout\n\n```md\n{{\u003c/* admonition type=\"tip\" title=\"Tip\" */\u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"tip\" title=\"Tip\" \u003e}}\nKeep admonitions rare so they still mean something when readers encounter them.\n{{\u003c /admonition \u003e}}\n\n#### Informational Callout\n\n```md\n{{\u003c/* admonition type=\"info\" title=\"Background\" */\u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"info\" title=\"Background\" \u003e}}\nThe docs editor updates both the content tree and the docs navigation data.\n{{\u003c /admonition \u003e}}\n\n#### Warning Callout\n\n```md\n{{\u003c/* admonition type=\"warning\" title=\"Do Not Edit Marker Files\" */\u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"warning\" title=\"Do Not Edit Marker Files\" \u003e}}\nDo not add front matter or body content to `inherit.md` or `_inherit.md` files.\n{{\u003c /admonition \u003e}}\n\n#### Danger Callout\n\n```md\n{{\u003c/* admonition type=\"danger\" title=\"Destructive Change\" */\u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c/* /admonition */\u003e}}\n```\n\n{{\u003c admonition type=\"danger\" title=\"Destructive Change\" \u003e}}\nDeleting or renaming docs structure manually can desynchronize navigation and inherited versions.\n{{\u003c /admonition \u003e}}\n\n### Implementation Reference\n\nThe shortcode implementation lives in `themes/sambee/layouts/shortcodes/admonition.html`.\n\nThe styling for the rendered admonition variants lives in `themes/sambee/assets/css/content.css`.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:website-dev-guide/authoring-and-tooling/docs-editor-tool", "parent_id": "section:website-dev-guide/authoring-and-tooling", "depth": 2, "kind": "page", "label": "docs-editor-tool", "title": "Docs Editor Tool", "path": "website-dev-guide/authoring-and-tooling/docs-editor-tool", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "branched", "source_version": "0.7", "diff_added": 109, "diff_removed": 17}, "0.9": {"state": "branched", "source_version": "0.8", "diff_added": 37, "diff_removed": 0}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "inherited", "source_version": "0.9"}}, "content_versions": {"0.7": "+++\ntitle = \"Docs Editor Tool\"\n+++\n\nThe docs editor CLI manages structural website docs changes safely and consistently. For ordinary copy edits inside an existing page, edit the Markdown file directly instead.\n\nPreview is the default mode. Run a command once to inspect the plan, then rerun it with `--apply` when the preview matches what you want.\n\n## Tool Location\n\nThe CLI lives at `website/scripts/docs-editor.py`.\n\nRun it from the `website/` directory:\n\n```bash\ncd website\npython3 scripts/docs-editor.py [global-options] \u003centity\u003e \u003coperation\u003e [operation-options]\n```\n\n## Normal Workflow\n\nUse the tool in this order:\n\n1. run the command in preview mode first\n2. review the planned metadata and file changes\n3. rerun the command with `--apply` when the plan is correct\n4. add `--yes` for destructive apply operations in non-interactive shells\n\nAfter a successful apply, the tool runs docs validation automatically.\n\nThe human-readable preview now shows:\n\n- the operation summary\n- the key metadata for the operation\n- the planned file and nav changes\n\n## What the Tool Handles\n\nThe docs editor supports four entity types:\n\n- versions\n- books\n- sections\n- pages\n\nSupported structural operations include:\n\n- creating\n- deleting\n- renaming\n\n## Common Tasks\n\nUse the built-in help when you know the action but not the exact flags:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --help\npython3 scripts/docs-editor.py page create --help\n```\n\nUse these commands as a starting point for the most common workflows:\n\n- add a new page\n- rename a page or section\n- create a new docs version that inherits from the latest one\n\n## Example: Create a New Version\n\nThis example:\n\n- creates `0.8` as a new version\n- adds it as to the end of the version list as the newest version (`--latest`)\n- adds the status label `preview` (which is shown in the UI)\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\n## Example: Create a New Book\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\n## Example: Create a Structural-Only Book\n\nUse this when a book is only a navigation container and should not have a landing page of its own.\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create \\\n  --version 0.7 \\\n  --book release-info \\\n  --position start \\\n  --structural-only\n```\n\nThat creates the book directory and nav entry without `_index.md` or `_inherit.md`.\n\n## Example: Create a Structural-Only Section\n\nThis is useful when you want a navigation group without a section landing page.\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --title \"Authoring And Tooling\" \\\n  --position end \\\n  --structural-only\n```\n\nThat creates the section directory and nav entry without `_index.md` or `_inherit.md`.\n\n## Example: Create a New Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\n## Example: Rename a Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --from website-and-docs-architecture-overview \\\n  --to website-and-docs-system-overview \\\n  --title \"Website And Docs System Overview\"\n```\n\nThat preview is especially useful when a rename may propagate into inherited descendants, because the metadata section shows which later inherited versions will follow the rename.\n\n## Convert an Inherited Page to Real Content\n\nSometimes a later version already has the page path and nav entry, but the page itself is still inherited through an empty `inherit.md` marker.\n\nIn that case, do not use `page create`. The page already exists structurally.\n\nInstead:\n\n1. Identify the inherited source page you want to override.\n1. Copy that page's current content into the later version as a starting point.\n1. Replace the later version's empty `inherit.md` with a real `index.md`.\n1. Edit the new `index.md` for the version-specific behavior.\n\nThis is a manual content-materialization step, not a page-creation step. The docs editor currently manages page identity and nav structure, but it does not provide a dedicated command that turns an existing inherited page marker into authored page content.\n\nIf a position selector fails, the CLI also reports the valid sibling slugs so you can retry without opening the nav file first.\n\n## Safety Model\n\nThe docs editor is deliberately conservative.\n\n- preview is the default\n- no files are written unless you pass `--apply`\n- destructive operations require confirmation unless you pass `--yes`\n- docs validation runs automatically after a successful apply\n\n### Refusal Semantics\n\nThe tool refuses destructive operations when they would silently rewrite newer authored content.\n\nTypical refusal case:\n\n- an older version rename would force changes into a later version that already has real content at the affected path\n\nIn that case, the CLI exits non-zero, reports the refusal reason, and leaves the docs tree unchanged.\n\n## Detailed Reference\n\nThe full CLI reference now lives on a separate page so this overview can stay task-focused.\n\nUse [Docs Editor Operation Reference](../docs-editor-operation-reference/) when you need:\n\n- the full global option list\n- forward-impact analysis rules\n- content invariants preserved by the tool\n- real-content stub and inherited-marker behavior\n- preview output details\n- per-entity create, delete, and rename reference behavior\n", "0.8": "+++\ntitle = \"Docs Editor Tool\"\n+++\n\nThe docs editor CLI manages structural website docs changes safely and consistently. For ordinary copy edits inside an existing page, edit the Markdown file directly instead.\n\nPreview is the default mode. Run a command once to inspect the plan, then rerun it with `--apply` when the preview matches what you want.\n\n## Tool Location\n\nThe CLI lives at `website/scripts/docs-editor.py`.\n\nRun it from the `website/` directory:\n\n```bash\ncd website\npython3 scripts/docs-editor.py [global-options] \u003centity\u003e \u003coperation\u003e [operation-options]\n```\n\n## Normal Workflow\n\nUse the tool in this order:\n\n1. run the command in preview mode first\n2. review the planned metadata and file changes\n3. rerun the command with `--apply` when the plan is correct\n4. add `--yes` for destructive apply operations in non-interactive shells\n\nAfter a successful apply, the tool runs docs validation automatically.\n\nThe human-readable preview now shows:\n\n- the operation summary\n- the key metadata for the operation\n- the planned file and nav changes\n\n## What the Tool Handles\n\nThe docs editor supports four entity types:\n\n- versions\n- books\n- sections\n- pages\n\nSupported structural operations include:\n\n- creating\n- deleting\n- renaming\n\nThe docs editor package also includes a standalone visualization report generator for the docs tree.\n\n## Common Tasks\n\nUse the built-in help when you know the action but not the exact flags:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --help\npython3 scripts/docs-editor.py page create --help\n```\n\nUse these commands as a starting point for the most common workflows:\n\n- add a new page\n- rename a page or section\n- create a new docs version that inherits from the latest one\n\n## Example: Create a New Version\n\nThis example:\n\n- creates `0.8` as a new version\n- adds it as to the end of the version list as the newest version (`--latest`)\n- adds the status label `preview` (which is shown in the UI)\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\n## Example: Create a New Book\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\n## Example: Create a Structural-Only Section\n\nThis is useful when you want a navigation group without a section landing page.\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --title \"Authoring And Tooling\" \\\n  --position end \\\n  --structural-only\n```\n\nThat creates the section directory and nav entry without `_index.md` or `_inherit.md`.\n\n## Example: Create a New Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\n## Example: Rename a Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --from website-and-docs-architecture-overview \\\n  --to website-and-docs-system-overview \\\n  --title \"Website And Docs System Overview\"\n```\n\nThat preview is especially useful when a rename may propagate into inherited descendants, because the metadata section shows which later inherited versions will follow the rename.\n\n## Convert an Inherited Page to Real Content\n\nSometimes a later version already has the page path and nav entry, but the page itself is still inherited through an empty `inherit.md` marker.\n\nIn that case, do not use `page create`. The page already exists structurally.\n\nUse `page materialize`:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page materialize \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page materialize \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nThat command:\n\n- removes the empty `inherit.md` marker in that version\n- copies the currently resolved inherited `index.md` content into the page directory\n- lets you optionally replace the page title with `--title`\n\nAfter that, edit the new `index.md` for the version-specific behavior.\n\n## Convert Real Page Content Back to Inherited Content\n\nIf you no longer need a version-specific page override, you can convert the page back to an inherited marker.\n\nUse `page inherit`:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page inherit \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply --yes page inherit \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nThis is destructive because it removes that version's real `index.md` and replaces it with `inherit.md`.\n\nThe command refuses when no earlier version provides real page content for the same path.\n\nManual fallback if you need finer control:\n\n1. Identify the inherited source page you want to override.\n1. Copy that page's current content into the later version as a starting point.\n1. Replace the later version's empty `inherit.md` with a real `index.md`.\n1. Edit the new `index.md` for the version-specific behavior.\n\nThis is still not a page-creation step. The page identity and nav structure already exist; `page materialize` only turns the inherited marker into authored page content in the selected version.\n\nIf a position selector fails, the CLI also reports the valid sibling slugs so you can retry without opening the nav file first.\n\n## Safety Model\n\nThe docs editor is deliberately conservative.\n\n- preview is the default\n- no files are written unless you pass `--apply`\n- destructive operations require confirmation unless you pass `--yes`\n- docs validation runs automatically after a successful apply\n\n### Refusal Semantics\n\nThe tool refuses destructive operations when they would silently rewrite newer authored content.\n\nTypical refusal case:\n\n- an older version rename would force changes into a later version that already has real content at the affected path\n\nIn that case, the CLI exits non-zero, reports the refusal reason, and leaves the docs tree unchanged.\n\n## Generate a Docs Structure Report\n\nThe docs editor package also includes a standalone report generator for exploring the docs tree across versions.\n\nUse it when you want a repo-local HTML view of:\n\n- books, sections, and pages in one expandable tree-table\n- current-version metadata and version status labels\n- inherited versus authored versus branched page states\n- diff counts for branched pages relative to the earlier authored version\n- per-page version comparison in the side panel\n\nThe wrapper script lives at `website/scripts/docs-report.py`.\n\nFor normal contributor workflow, prefer the repo helper:\n\n```bash\ncd /workspace\npython3 scripts/update-docs-derived-artifacts.py\n```\n\nThat helper centralizes the repo-local behavior around derived docs artifacts.\n\n- the pre-commit hook calls it automatically when staged docs inputs can stale the committed report\n- it stages the refreshed report for you in that hook-driven path\n- the VS Code workspace task `Website: Refresh Docs Derived Artifacts` runs the same helper manually\n\nGenerate the report into the committed output path:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py\n```\n\nThat writes `website-meta/docs-reports/docs-structure-report.html`.\n\nUse check mode in CI or before opening a pull request:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py --check\n```\n\nThat exits non-zero when the committed HTML report is stale.\n\n## Detailed Reference\n\nThe full CLI reference now lives on a separate page so this overview can stay task-focused.\n\nUse [Docs Editor Operation Reference](../docs-editor-operation-reference/) when you need:\n\n- the full global option list\n- forward-impact analysis rules\n- content invariants preserved by the tool\n- real-content stub and inherited-marker behavior\n- preview output details\n- per-entity create, delete, and rename reference behavior\n", "0.9": "+++\ntitle = \"Docs Editor Tool\"\n+++\n\nThe docs editor CLI manages structural website docs changes safely and consistently. For ordinary copy edits inside an existing page, edit the Markdown file directly instead.\n\nPreview is the default mode. Run a command once to inspect the plan, then rerun it with `--apply` when the preview matches what you want.\n\n## Tool Location\n\nThe CLI lives at `website/scripts/docs-editor.py`.\n\nRun it from the `website/` directory:\n\n```bash\ncd website\npython3 scripts/docs-editor.py [global-options] \u003centity\u003e \u003coperation\u003e [operation-options]\n```\n\n## Normal Workflow\n\nUse the tool in this order:\n\n1. run the command in preview mode first\n2. review the planned metadata and file changes\n3. rerun the command with `--apply` when the plan is correct\n4. add `--yes` for destructive apply operations in non-interactive shells\n\nAfter a successful apply, the tool runs docs validation automatically.\n\nThe human-readable preview now shows:\n\n- the operation summary\n- the key metadata for the operation\n- the planned file and nav changes\n\n## What the Tool Handles\n\nThe docs editor supports four entity types:\n\n- versions\n- books\n- sections\n- pages\n\nSupported structural operations include:\n\n- creating\n- deleting\n- materializing inherited landing content\n- moving pages between sections\n- renaming\n\nThe docs editor package also includes a standalone visualization report generator for the docs tree.\n\n## Common Tasks\n\nUse the built-in help when you know the action but not the exact flags:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --help\npython3 scripts/docs-editor.py page create --help\n```\n\nUse these commands as a starting point for the most common workflows:\n\n- add a new page\n- materialize an inherited book landing page\n- move a page to another section\n- rename a page or section\n- create a new docs version that inherits from the latest one\n\n## Example: Create a New Version\n\nThis example:\n\n- creates `0.8` as a new version\n- adds it as to the end of the version list as the newest version (`--latest`)\n- adds the status label `preview` (which is shown in the UI)\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\n## Example: Create a New Book\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\n## Example: Create a Structural-Only Section\n\nThis is useful when you want a navigation group without a section landing page.\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --title \"Authoring And Tooling\" \\\n  --position end \\\n  --structural-only\n```\n\nThat creates the section directory and nav entry without `_index.md` or `_inherit.md`.\n\n## Example: Create a New Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\n## Example: Rename a Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --from website-and-docs-architecture-overview \\\n  --to website-and-docs-system-overview \\\n  --title \"Website And Docs System Overview\"\n```\n\nThat preview is especially useful when a rename may propagate into inherited descendants, because the metadata section shows which later inherited versions will follow the rename.\n\n## Convert an Inherited Page to Real Content\n\nSometimes a later version already has the page path and nav entry, but the page itself is still inherited through an empty `inherit.md` marker.\n\nIn that case, do not use `page create`. The page already exists structurally.\n\nUse `page materialize`:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page materialize \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page materialize \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nThat command:\n\n- removes the empty `inherit.md` marker in that version\n- copies the currently resolved inherited `index.md` content into the page directory\n- lets you optionally replace the page title with `--title`\n\nAfter that, edit the new `index.md` for the version-specific behavior.\n\n## Convert an Inherited Book Landing Page to Real Content\n\nUse `book materialize` when a version inherits a book landing page through `_inherit.md` and needs version-specific copy:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply book materialize \\\n  --version 0.9 \\\n  --book admin-guide\n```\n\nThe command replaces `_inherit.md` with the currently resolved `_index.md` content. Use `--title` to replace its title while materializing.\n\n## Move a Page Between Sections\n\nUse `page move` to move a page within one book while preserving its body content:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page move \\\n  --version 0.9 \\\n  --book admin-guide \\\n  --from-section configuration \\\n  --to-section reference \\\n  --page configuration-key-reference \\\n  --to-page configuration-file-reference \\\n  --position start\n```\n\nThe tool updates both page lists, creates real content at the destination, and removes the source directory. `--to-page` is optional and defaults to the source page slug. `--position` applies to the selected version's destination section.\n\nLater inherited-only versions follow the move automatically. The tool refuses when the destination exists, a later version has authored source content, or a later version lacks the destination section. Update Markdown links and managed redirects separately.\n\n## Convert Real Page Content Back to Inherited Content\n\nIf you no longer need a version-specific page override, you can convert the page back to an inherited marker.\n\nUse `page inherit`:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page inherit \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply --yes page inherit \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nThis is destructive because it removes that version's real `index.md` and replaces it with `inherit.md`.\n\nThe command refuses when no earlier version provides real page content for the same path.\n\nManual fallback if you need finer control:\n\n1. Identify the inherited source page you want to override.\n1. Copy that page's current content into the later version as a starting point.\n1. Replace the later version's empty `inherit.md` with a real `index.md`.\n1. Edit the new `index.md` for the version-specific behavior.\n\nThis is still not a page-creation step. The page identity and nav structure already exist; `page materialize` only turns the inherited marker into authored page content in the selected version.\n\nIf a position selector fails, the CLI also reports the valid sibling slugs so you can retry without opening the nav file first.\n\n## Safety Model\n\nThe docs editor is deliberately conservative.\n\n- preview is the default\n- no files are written unless you pass `--apply`\n- destructive operations require confirmation unless you pass `--yes`\n- docs validation runs automatically after a successful apply\n\n### Refusal Semantics\n\nThe tool refuses destructive operations when they would silently rewrite newer authored content.\n\nTypical refusal case:\n\n- an older version rename would force changes into a later version that already has real content at the affected path\n\nIn that case, the CLI exits non-zero, reports the refusal reason, and leaves the docs tree unchanged.\n\n## Generate a Docs Structure Report\n\nThe docs editor package also includes a standalone report generator for exploring the docs tree across versions.\n\nUse it when you want a repo-local HTML view of:\n\n- books, sections, and pages in one expandable tree-table\n- current-version metadata and version status labels\n- inherited versus authored versus branched page states\n- diff counts for branched pages relative to the earlier authored version\n- per-page version comparison in the side panel\n\nThe wrapper script lives at `website/scripts/docs-report.py`.\n\nFor normal contributor workflow, prefer the repo helper:\n\n```bash\ncd /workspace\npython3 scripts/update-docs-derived-artifacts.py\n```\n\nThat helper centralizes the repo-local behavior around derived docs artifacts.\n\n- the pre-commit hook calls it automatically when staged docs inputs can stale the committed report\n- it stages the refreshed report for you in that hook-driven path\n- the VS Code workspace task `Website: Refresh Docs Derived Artifacts` runs the same helper manually\n\nGenerate the report into the committed output path:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py\n```\n\nThat writes `website-meta/docs-reports/docs-structure-report.html`.\n\nUse check mode in CI or before opening a pull request:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py --check\n```\n\nThat exits non-zero when the committed HTML report is stale.\n\n## Detailed Reference\n\nThe full CLI reference now lives on a separate page so this overview can stay task-focused.\n\nUse [Docs Editor Operation Reference](../docs-editor-operation-reference/) when you need:\n\n- the full global option list\n- forward-impact analysis rules\n- content invariants preserved by the tool\n- real-content stub and inherited-marker behavior\n- preview output details\n- per-entity create, delete, and rename reference behavior\n", "1.0": "+++\ntitle = \"Docs Editor Tool\"\n+++\n\nThe docs editor CLI manages structural website docs changes safely and consistently. For ordinary copy edits inside an existing page, edit the Markdown file directly instead.\n\nPreview is the default mode. Run a command once to inspect the plan, then rerun it with `--apply` when the preview matches what you want.\n\n## Tool Location\n\nThe CLI lives at `website/scripts/docs-editor.py`.\n\nRun it from the `website/` directory:\n\n```bash\ncd website\npython3 scripts/docs-editor.py [global-options] \u003centity\u003e \u003coperation\u003e [operation-options]\n```\n\n## Normal Workflow\n\nUse the tool in this order:\n\n1. run the command in preview mode first\n2. review the planned metadata and file changes\n3. rerun the command with `--apply` when the plan is correct\n4. add `--yes` for destructive apply operations in non-interactive shells\n\nAfter a successful apply, the tool runs docs validation automatically.\n\nThe human-readable preview now shows:\n\n- the operation summary\n- the key metadata for the operation\n- the planned file and nav changes\n\n## What the Tool Handles\n\nThe docs editor supports four entity types:\n\n- versions\n- books\n- sections\n- pages\n\nSupported structural operations include:\n\n- creating\n- deleting\n- materializing inherited landing content\n- moving pages between sections\n- renaming\n\nThe docs editor package also includes a standalone visualization report generator for the docs tree.\n\n## Common Tasks\n\nUse the built-in help when you know the action but not the exact flags:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --help\npython3 scripts/docs-editor.py page create --help\n```\n\nUse these commands as a starting point for the most common workflows:\n\n- add a new page\n- materialize an inherited book landing page\n- move a page to another section\n- rename a page or section\n- create a new docs version that inherits from the latest one\n\n## Example: Create a New Version\n\nThis example:\n\n- creates `0.8` as a new version\n- adds it as to the end of the version list as the newest version (`--latest`)\n- adds the status label `preview` (which is shown in the UI)\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\n## Example: Create a New Book\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\n## Example: Create a Structural-Only Section\n\nThis is useful when you want a navigation group without a section landing page.\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --title \"Authoring And Tooling\" \\\n  --position end \\\n  --structural-only\n```\n\nThat creates the section directory and nav entry without `_index.md` or `_inherit.md`.\n\n## Example: Create a New Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\n## Example: Rename a Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --from website-and-docs-architecture-overview \\\n  --to website-and-docs-system-overview \\\n  --title \"Website And Docs System Overview\"\n```\n\nThat preview is especially useful when a rename may propagate into inherited descendants, because the metadata section shows which later inherited versions will follow the rename.\n\n## Convert an Inherited Page to Real Content\n\nSometimes a later version already has the page path and nav entry, but the page itself is still inherited through an empty `inherit.md` marker.\n\nIn that case, do not use `page create`. The page already exists structurally.\n\nUse `page materialize`:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page materialize \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page materialize \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nThat command:\n\n- removes the empty `inherit.md` marker in that version\n- copies the currently resolved inherited `index.md` content into the page directory\n- lets you optionally replace the page title with `--title`\n\nAfter that, edit the new `index.md` for the version-specific behavior.\n\n## Convert an Inherited Book Landing Page to Real Content\n\nUse `book materialize` when a version inherits a book landing page through `_inherit.md` and needs version-specific copy:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply book materialize \\\n  --version 0.9 \\\n  --book admin-guide\n```\n\nThe command replaces `_inherit.md` with the currently resolved `_index.md` content. Use `--title` to replace its title while materializing.\n\n## Move a Page Between Sections\n\nUse `page move` to move a page within one book while preserving its body content:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page move \\\n  --version 0.9 \\\n  --book admin-guide \\\n  --from-section configuration \\\n  --to-section reference \\\n  --page configuration-key-reference \\\n  --to-page configuration-file-reference \\\n  --position start\n```\n\nThe tool updates both page lists, creates real content at the destination, and removes the source directory. `--to-page` is optional and defaults to the source page slug. `--position` applies to the selected version's destination section.\n\nLater inherited-only versions follow the move automatically. The tool refuses when the destination exists, a later version has authored source content, or a later version lacks the destination section. Update Markdown links and managed redirects separately.\n\n## Convert Real Page Content Back to Inherited Content\n\nIf you no longer need a version-specific page override, you can convert the page back to an inherited marker.\n\nUse `page inherit`:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page inherit \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply --yes page inherit \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nThis is destructive because it removes that version's real `index.md` and replaces it with `inherit.md`.\n\nThe command refuses when no earlier version provides real page content for the same path.\n\nManual fallback if you need finer control:\n\n1. Identify the inherited source page you want to override.\n1. Copy that page's current content into the later version as a starting point.\n1. Replace the later version's empty `inherit.md` with a real `index.md`.\n1. Edit the new `index.md` for the version-specific behavior.\n\nThis is still not a page-creation step. The page identity and nav structure already exist; `page materialize` only turns the inherited marker into authored page content in the selected version.\n\nIf a position selector fails, the CLI also reports the valid sibling slugs so you can retry without opening the nav file first.\n\n## Safety Model\n\nThe docs editor is deliberately conservative.\n\n- preview is the default\n- no files are written unless you pass `--apply`\n- destructive operations require confirmation unless you pass `--yes`\n- docs validation runs automatically after a successful apply\n\n### Refusal Semantics\n\nThe tool refuses destructive operations when they would silently rewrite newer authored content.\n\nTypical refusal case:\n\n- an older version rename would force changes into a later version that already has real content at the affected path\n\nIn that case, the CLI exits non-zero, reports the refusal reason, and leaves the docs tree unchanged.\n\n## Generate a Docs Structure Report\n\nThe docs editor package also includes a standalone report generator for exploring the docs tree across versions.\n\nUse it when you want a repo-local HTML view of:\n\n- books, sections, and pages in one expandable tree-table\n- current-version metadata and version status labels\n- inherited versus authored versus branched page states\n- diff counts for branched pages relative to the earlier authored version\n- per-page version comparison in the side panel\n\nThe wrapper script lives at `website/scripts/docs-report.py`.\n\nFor normal contributor workflow, prefer the repo helper:\n\n```bash\ncd /workspace\npython3 scripts/update-docs-derived-artifacts.py\n```\n\nThat helper centralizes the repo-local behavior around derived docs artifacts.\n\n- the pre-commit hook calls it automatically when staged docs inputs can stale the committed report\n- it stages the refreshed report for you in that hook-driven path\n- the VS Code workspace task `Website: Refresh Docs Derived Artifacts` runs the same helper manually\n\nGenerate the report into the committed output path:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py\n```\n\nThat writes `website-meta/docs-reports/docs-structure-report.html`.\n\nUse check mode in CI or before opening a pull request:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py --check\n```\n\nThat exits non-zero when the committed HTML report is stale.\n\n## Detailed Reference\n\nThe full CLI reference now lives on a separate page so this overview can stay task-focused.\n\nUse [Docs Editor Operation Reference](../docs-editor-operation-reference/) when you need:\n\n- the full global option list\n- forward-impact analysis rules\n- content invariants preserved by the tool\n- real-content stub and inherited-marker behavior\n- preview output details\n- per-entity create, delete, and rename reference behavior\n", "2.0": "+++\ntitle = \"Docs Editor Tool\"\n+++\n\nThe docs editor CLI manages structural website docs changes safely and consistently. For ordinary copy edits inside an existing page, edit the Markdown file directly instead.\n\nPreview is the default mode. Run a command once to inspect the plan, then rerun it with `--apply` when the preview matches what you want.\n\n## Tool Location\n\nThe CLI lives at `website/scripts/docs-editor.py`.\n\nRun it from the `website/` directory:\n\n```bash\ncd website\npython3 scripts/docs-editor.py [global-options] \u003centity\u003e \u003coperation\u003e [operation-options]\n```\n\n## Normal Workflow\n\nUse the tool in this order:\n\n1. run the command in preview mode first\n2. review the planned metadata and file changes\n3. rerun the command with `--apply` when the plan is correct\n4. add `--yes` for destructive apply operations in non-interactive shells\n\nAfter a successful apply, the tool runs docs validation automatically.\n\nThe human-readable preview now shows:\n\n- the operation summary\n- the key metadata for the operation\n- the planned file and nav changes\n\n## What the Tool Handles\n\nThe docs editor supports four entity types:\n\n- versions\n- books\n- sections\n- pages\n\nSupported structural operations include:\n\n- creating\n- deleting\n- materializing inherited landing content\n- moving pages between sections\n- renaming\n\nThe docs editor package also includes a standalone visualization report generator for the docs tree.\n\n## Common Tasks\n\nUse the built-in help when you know the action but not the exact flags:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --help\npython3 scripts/docs-editor.py page create --help\n```\n\nUse these commands as a starting point for the most common workflows:\n\n- add a new page\n- materialize an inherited book landing page\n- move a page to another section\n- rename a page or section\n- create a new docs version that inherits from the latest one\n\n## Example: Create a New Version\n\nThis example:\n\n- creates `0.8` as a new version\n- adds it as to the end of the version list as the newest version (`--latest`)\n- adds the status label `preview` (which is shown in the UI)\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\n## Example: Create a New Book\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\n## Example: Create a Structural-Only Section\n\nThis is useful when you want a navigation group without a section landing page.\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --title \"Authoring And Tooling\" \\\n  --position end \\\n  --structural-only\n```\n\nThat creates the section directory and nav entry without `_index.md` or `_inherit.md`.\n\n## Example: Create a New Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\n## Example: Rename a Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --from website-and-docs-architecture-overview \\\n  --to website-and-docs-system-overview \\\n  --title \"Website And Docs System Overview\"\n```\n\nThat preview is especially useful when a rename may propagate into inherited descendants, because the metadata section shows which later inherited versions will follow the rename.\n\n## Convert an Inherited Page to Real Content\n\nSometimes a later version already has the page path and nav entry, but the page itself is still inherited through an empty `inherit.md` marker.\n\nIn that case, do not use `page create`. The page already exists structurally.\n\nUse `page materialize`:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page materialize \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page materialize \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nThat command:\n\n- removes the empty `inherit.md` marker in that version\n- copies the currently resolved inherited `index.md` content into the page directory\n- lets you optionally replace the page title with `--title`\n\nAfter that, edit the new `index.md` for the version-specific behavior.\n\n## Convert an Inherited Book Landing Page to Real Content\n\nUse `book materialize` when a version inherits a book landing page through `_inherit.md` and needs version-specific copy:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply book materialize \\\n  --version 0.9 \\\n  --book admin-guide\n```\n\nThe command replaces `_inherit.md` with the currently resolved `_index.md` content. Use `--title` to replace its title while materializing.\n\n## Move a Page Between Sections\n\nUse `page move` to move a page within one book while preserving its body content:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page move \\\n  --version 0.9 \\\n  --book admin-guide \\\n  --from-section configuration \\\n  --to-section reference \\\n  --page configuration-key-reference \\\n  --to-page configuration-file-reference \\\n  --position start\n```\n\nThe tool updates both page lists, creates real content at the destination, and removes the source directory. `--to-page` is optional and defaults to the source page slug. `--position` applies to the selected version's destination section.\n\nLater inherited-only versions follow the move automatically. The tool refuses when the destination exists, a later version has authored source content, or a later version lacks the destination section. Update Markdown links and managed redirects separately.\n\n## Convert Real Page Content Back to Inherited Content\n\nIf you no longer need a version-specific page override, you can convert the page back to an inherited marker.\n\nUse `page inherit`:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page inherit \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply --yes page inherit \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nThis is destructive because it removes that version's real `index.md` and replaces it with `inherit.md`.\n\nThe command refuses when no earlier version provides real page content for the same path.\n\nManual fallback if you need finer control:\n\n1. Identify the inherited source page you want to override.\n1. Copy that page's current content into the later version as a starting point.\n1. Replace the later version's empty `inherit.md` with a real `index.md`.\n1. Edit the new `index.md` for the version-specific behavior.\n\nThis is still not a page-creation step. The page identity and nav structure already exist; `page materialize` only turns the inherited marker into authored page content in the selected version.\n\nIf a position selector fails, the CLI also reports the valid sibling slugs so you can retry without opening the nav file first.\n\n## Safety Model\n\nThe docs editor is deliberately conservative.\n\n- preview is the default\n- no files are written unless you pass `--apply`\n- destructive operations require confirmation unless you pass `--yes`\n- docs validation runs automatically after a successful apply\n\n### Refusal Semantics\n\nThe tool refuses destructive operations when they would silently rewrite newer authored content.\n\nTypical refusal case:\n\n- an older version rename would force changes into a later version that already has real content at the affected path\n\nIn that case, the CLI exits non-zero, reports the refusal reason, and leaves the docs tree unchanged.\n\n## Generate a Docs Structure Report\n\nThe docs editor package also includes a standalone report generator for exploring the docs tree across versions.\n\nUse it when you want a repo-local HTML view of:\n\n- books, sections, and pages in one expandable tree-table\n- current-version metadata and version status labels\n- inherited versus authored versus branched page states\n- diff counts for branched pages relative to the earlier authored version\n- per-page version comparison in the side panel\n\nThe wrapper script lives at `website/scripts/docs-report.py`.\n\nFor normal contributor workflow, prefer the repo helper:\n\n```bash\ncd /workspace\npython3 scripts/update-docs-derived-artifacts.py\n```\n\nThat helper centralizes the repo-local behavior around derived docs artifacts.\n\n- the pre-commit hook calls it automatically when staged docs inputs can stale the committed report\n- it stages the refreshed report for you in that hook-driven path\n- the VS Code workspace task `Website: Refresh Docs Derived Artifacts` runs the same helper manually\n\nGenerate the report into the committed output path:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py\n```\n\nThat writes `website-meta/docs-reports/docs-structure-report.html`.\n\nUse check mode in CI or before opening a pull request:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py --check\n```\n\nThat exits non-zero when the committed HTML report is stale.\n\n## Detailed Reference\n\nThe full CLI reference now lives on a separate page so this overview can stay task-focused.\n\nUse [Docs Editor Operation Reference](../docs-editor-operation-reference/) when you need:\n\n- the full global option list\n- forward-impact analysis rules\n- content invariants preserved by the tool\n- real-content stub and inherited-marker behavior\n- preview output details\n- per-entity create, delete, and rename reference behavior\n"}, "page_contents": {"0.7": "+++\ntitle = \"Docs Editor Tool\"\n+++\n\nThe docs editor CLI manages structural website docs changes safely and consistently. For ordinary copy edits inside an existing page, edit the Markdown file directly instead.\n\nPreview is the default mode. Run a command once to inspect the plan, then rerun it with `--apply` when the preview matches what you want.\n\n## Tool Location\n\nThe CLI lives at `website/scripts/docs-editor.py`.\n\nRun it from the `website/` directory:\n\n```bash\ncd website\npython3 scripts/docs-editor.py [global-options] \u003centity\u003e \u003coperation\u003e [operation-options]\n```\n\n## Normal Workflow\n\nUse the tool in this order:\n\n1. run the command in preview mode first\n2. review the planned metadata and file changes\n3. rerun the command with `--apply` when the plan is correct\n4. add `--yes` for destructive apply operations in non-interactive shells\n\nAfter a successful apply, the tool runs docs validation automatically.\n\nThe human-readable preview now shows:\n\n- the operation summary\n- the key metadata for the operation\n- the planned file and nav changes\n\n## What the Tool Handles\n\nThe docs editor supports four entity types:\n\n- versions\n- books\n- sections\n- pages\n\nSupported structural operations include:\n\n- creating\n- deleting\n- renaming\n\n## Common Tasks\n\nUse the built-in help when you know the action but not the exact flags:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --help\npython3 scripts/docs-editor.py page create --help\n```\n\nUse these commands as a starting point for the most common workflows:\n\n- add a new page\n- rename a page or section\n- create a new docs version that inherits from the latest one\n\n## Example: Create a New Version\n\nThis example:\n\n- creates `0.8` as a new version\n- adds it as to the end of the version list as the newest version (`--latest`)\n- adds the status label `preview` (which is shown in the UI)\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\n## Example: Create a New Book\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\n## Example: Create a Structural-Only Book\n\nUse this when a book is only a navigation container and should not have a landing page of its own.\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create \\\n  --version 0.7 \\\n  --book release-info \\\n  --position start \\\n  --structural-only\n```\n\nThat creates the book directory and nav entry without `_index.md` or `_inherit.md`.\n\n## Example: Create a Structural-Only Section\n\nThis is useful when you want a navigation group without a section landing page.\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --title \"Authoring And Tooling\" \\\n  --position end \\\n  --structural-only\n```\n\nThat creates the section directory and nav entry without `_index.md` or `_inherit.md`.\n\n## Example: Create a New Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\n## Example: Rename a Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --from website-and-docs-architecture-overview \\\n  --to website-and-docs-system-overview \\\n  --title \"Website And Docs System Overview\"\n```\n\nThat preview is especially useful when a rename may propagate into inherited descendants, because the metadata section shows which later inherited versions will follow the rename.\n\n## Convert an Inherited Page to Real Content\n\nSometimes a later version already has the page path and nav entry, but the page itself is still inherited through an empty `inherit.md` marker.\n\nIn that case, do not use `page create`. The page already exists structurally.\n\nInstead:\n\n1. Identify the inherited source page you want to override.\n1. Copy that page's current content into the later version as a starting point.\n1. Replace the later version's empty `inherit.md` with a real `index.md`.\n1. Edit the new `index.md` for the version-specific behavior.\n\nThis is a manual content-materialization step, not a page-creation step. The docs editor currently manages page identity and nav structure, but it does not provide a dedicated command that turns an existing inherited page marker into authored page content.\n\nIf a position selector fails, the CLI also reports the valid sibling slugs so you can retry without opening the nav file first.\n\n## Safety Model\n\nThe docs editor is deliberately conservative.\n\n- preview is the default\n- no files are written unless you pass `--apply`\n- destructive operations require confirmation unless you pass `--yes`\n- docs validation runs automatically after a successful apply\n\n### Refusal Semantics\n\nThe tool refuses destructive operations when they would silently rewrite newer authored content.\n\nTypical refusal case:\n\n- an older version rename would force changes into a later version that already has real content at the affected path\n\nIn that case, the CLI exits non-zero, reports the refusal reason, and leaves the docs tree unchanged.\n\n## Detailed Reference\n\nThe full CLI reference now lives on a separate page so this overview can stay task-focused.\n\nUse [Docs Editor Operation Reference](../docs-editor-operation-reference/) when you need:\n\n- the full global option list\n- forward-impact analysis rules\n- content invariants preserved by the tool\n- real-content stub and inherited-marker behavior\n- preview output details\n- per-entity create, delete, and rename reference behavior\n", "0.8": "+++\ntitle = \"Docs Editor Tool\"\n+++\n\nThe docs editor CLI manages structural website docs changes safely and consistently. For ordinary copy edits inside an existing page, edit the Markdown file directly instead.\n\nPreview is the default mode. Run a command once to inspect the plan, then rerun it with `--apply` when the preview matches what you want.\n\n## Tool Location\n\nThe CLI lives at `website/scripts/docs-editor.py`.\n\nRun it from the `website/` directory:\n\n```bash\ncd website\npython3 scripts/docs-editor.py [global-options] \u003centity\u003e \u003coperation\u003e [operation-options]\n```\n\n## Normal Workflow\n\nUse the tool in this order:\n\n1. run the command in preview mode first\n2. review the planned metadata and file changes\n3. rerun the command with `--apply` when the plan is correct\n4. add `--yes` for destructive apply operations in non-interactive shells\n\nAfter a successful apply, the tool runs docs validation automatically.\n\nThe human-readable preview now shows:\n\n- the operation summary\n- the key metadata for the operation\n- the planned file and nav changes\n\n## What the Tool Handles\n\nThe docs editor supports four entity types:\n\n- versions\n- books\n- sections\n- pages\n\nSupported structural operations include:\n\n- creating\n- deleting\n- renaming\n\nThe docs editor package also includes a standalone visualization report generator for the docs tree.\n\n## Common Tasks\n\nUse the built-in help when you know the action but not the exact flags:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --help\npython3 scripts/docs-editor.py page create --help\n```\n\nUse these commands as a starting point for the most common workflows:\n\n- add a new page\n- rename a page or section\n- create a new docs version that inherits from the latest one\n\n## Example: Create a New Version\n\nThis example:\n\n- creates `0.8` as a new version\n- adds it as to the end of the version list as the newest version (`--latest`)\n- adds the status label `preview` (which is shown in the UI)\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\n## Example: Create a New Book\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\n## Example: Create a Structural-Only Section\n\nThis is useful when you want a navigation group without a section landing page.\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --title \"Authoring And Tooling\" \\\n  --position end \\\n  --structural-only\n```\n\nThat creates the section directory and nav entry without `_index.md` or `_inherit.md`.\n\n## Example: Create a New Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\n## Example: Rename a Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --from website-and-docs-architecture-overview \\\n  --to website-and-docs-system-overview \\\n  --title \"Website And Docs System Overview\"\n```\n\nThat preview is especially useful when a rename may propagate into inherited descendants, because the metadata section shows which later inherited versions will follow the rename.\n\n## Convert an Inherited Page to Real Content\n\nSometimes a later version already has the page path and nav entry, but the page itself is still inherited through an empty `inherit.md` marker.\n\nIn that case, do not use `page create`. The page already exists structurally.\n\nUse `page materialize`:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page materialize \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page materialize \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nThat command:\n\n- removes the empty `inherit.md` marker in that version\n- copies the currently resolved inherited `index.md` content into the page directory\n- lets you optionally replace the page title with `--title`\n\nAfter that, edit the new `index.md` for the version-specific behavior.\n\n## Convert Real Page Content Back to Inherited Content\n\nIf you no longer need a version-specific page override, you can convert the page back to an inherited marker.\n\nUse `page inherit`:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page inherit \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply --yes page inherit \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nThis is destructive because it removes that version's real `index.md` and replaces it with `inherit.md`.\n\nThe command refuses when no earlier version provides real page content for the same path.\n\nManual fallback if you need finer control:\n\n1. Identify the inherited source page you want to override.\n1. Copy that page's current content into the later version as a starting point.\n1. Replace the later version's empty `inherit.md` with a real `index.md`.\n1. Edit the new `index.md` for the version-specific behavior.\n\nThis is still not a page-creation step. The page identity and nav structure already exist; `page materialize` only turns the inherited marker into authored page content in the selected version.\n\nIf a position selector fails, the CLI also reports the valid sibling slugs so you can retry without opening the nav file first.\n\n## Safety Model\n\nThe docs editor is deliberately conservative.\n\n- preview is the default\n- no files are written unless you pass `--apply`\n- destructive operations require confirmation unless you pass `--yes`\n- docs validation runs automatically after a successful apply\n\n### Refusal Semantics\n\nThe tool refuses destructive operations when they would silently rewrite newer authored content.\n\nTypical refusal case:\n\n- an older version rename would force changes into a later version that already has real content at the affected path\n\nIn that case, the CLI exits non-zero, reports the refusal reason, and leaves the docs tree unchanged.\n\n## Generate a Docs Structure Report\n\nThe docs editor package also includes a standalone report generator for exploring the docs tree across versions.\n\nUse it when you want a repo-local HTML view of:\n\n- books, sections, and pages in one expandable tree-table\n- current-version metadata and version status labels\n- inherited versus authored versus branched page states\n- diff counts for branched pages relative to the earlier authored version\n- per-page version comparison in the side panel\n\nThe wrapper script lives at `website/scripts/docs-report.py`.\n\nFor normal contributor workflow, prefer the repo helper:\n\n```bash\ncd /workspace\npython3 scripts/update-docs-derived-artifacts.py\n```\n\nThat helper centralizes the repo-local behavior around derived docs artifacts.\n\n- the pre-commit hook calls it automatically when staged docs inputs can stale the committed report\n- it stages the refreshed report for you in that hook-driven path\n- the VS Code workspace task `Website: Refresh Docs Derived Artifacts` runs the same helper manually\n\nGenerate the report into the committed output path:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py\n```\n\nThat writes `website-meta/docs-reports/docs-structure-report.html`.\n\nUse check mode in CI or before opening a pull request:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py --check\n```\n\nThat exits non-zero when the committed HTML report is stale.\n\n## Detailed Reference\n\nThe full CLI reference now lives on a separate page so this overview can stay task-focused.\n\nUse [Docs Editor Operation Reference](../docs-editor-operation-reference/) when you need:\n\n- the full global option list\n- forward-impact analysis rules\n- content invariants preserved by the tool\n- real-content stub and inherited-marker behavior\n- preview output details\n- per-entity create, delete, and rename reference behavior\n", "0.9": "+++\ntitle = \"Docs Editor Tool\"\n+++\n\nThe docs editor CLI manages structural website docs changes safely and consistently. For ordinary copy edits inside an existing page, edit the Markdown file directly instead.\n\nPreview is the default mode. Run a command once to inspect the plan, then rerun it with `--apply` when the preview matches what you want.\n\n## Tool Location\n\nThe CLI lives at `website/scripts/docs-editor.py`.\n\nRun it from the `website/` directory:\n\n```bash\ncd website\npython3 scripts/docs-editor.py [global-options] \u003centity\u003e \u003coperation\u003e [operation-options]\n```\n\n## Normal Workflow\n\nUse the tool in this order:\n\n1. run the command in preview mode first\n2. review the planned metadata and file changes\n3. rerun the command with `--apply` when the plan is correct\n4. add `--yes` for destructive apply operations in non-interactive shells\n\nAfter a successful apply, the tool runs docs validation automatically.\n\nThe human-readable preview now shows:\n\n- the operation summary\n- the key metadata for the operation\n- the planned file and nav changes\n\n## What the Tool Handles\n\nThe docs editor supports four entity types:\n\n- versions\n- books\n- sections\n- pages\n\nSupported structural operations include:\n\n- creating\n- deleting\n- materializing inherited landing content\n- moving pages between sections\n- renaming\n\nThe docs editor package also includes a standalone visualization report generator for the docs tree.\n\n## Common Tasks\n\nUse the built-in help when you know the action but not the exact flags:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --help\npython3 scripts/docs-editor.py page create --help\n```\n\nUse these commands as a starting point for the most common workflows:\n\n- add a new page\n- materialize an inherited book landing page\n- move a page to another section\n- rename a page or section\n- create a new docs version that inherits from the latest one\n\n## Example: Create a New Version\n\nThis example:\n\n- creates `0.8` as a new version\n- adds it as to the end of the version list as the newest version (`--latest`)\n- adds the status label `preview` (which is shown in the UI)\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\n## Example: Create a New Book\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\n## Example: Create a Structural-Only Section\n\nThis is useful when you want a navigation group without a section landing page.\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --title \"Authoring And Tooling\" \\\n  --position end \\\n  --structural-only\n```\n\nThat creates the section directory and nav entry without `_index.md` or `_inherit.md`.\n\n## Example: Create a New Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\n## Example: Rename a Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --from website-and-docs-architecture-overview \\\n  --to website-and-docs-system-overview \\\n  --title \"Website And Docs System Overview\"\n```\n\nThat preview is especially useful when a rename may propagate into inherited descendants, because the metadata section shows which later inherited versions will follow the rename.\n\n## Convert an Inherited Page to Real Content\n\nSometimes a later version already has the page path and nav entry, but the page itself is still inherited through an empty `inherit.md` marker.\n\nIn that case, do not use `page create`. The page already exists structurally.\n\nUse `page materialize`:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page materialize \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page materialize \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nThat command:\n\n- removes the empty `inherit.md` marker in that version\n- copies the currently resolved inherited `index.md` content into the page directory\n- lets you optionally replace the page title with `--title`\n\nAfter that, edit the new `index.md` for the version-specific behavior.\n\n## Convert an Inherited Book Landing Page to Real Content\n\nUse `book materialize` when a version inherits a book landing page through `_inherit.md` and needs version-specific copy:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply book materialize \\\n  --version 0.9 \\\n  --book admin-guide\n```\n\nThe command replaces `_inherit.md` with the currently resolved `_index.md` content. Use `--title` to replace its title while materializing.\n\n## Move a Page Between Sections\n\nUse `page move` to move a page within one book while preserving its body content:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page move \\\n  --version 0.9 \\\n  --book admin-guide \\\n  --from-section configuration \\\n  --to-section reference \\\n  --page configuration-key-reference \\\n  --to-page configuration-file-reference \\\n  --position start\n```\n\nThe tool updates both page lists, creates real content at the destination, and removes the source directory. `--to-page` is optional and defaults to the source page slug. `--position` applies to the selected version's destination section.\n\nLater inherited-only versions follow the move automatically. The tool refuses when the destination exists, a later version has authored source content, or a later version lacks the destination section. Update Markdown links and managed redirects separately.\n\n## Convert Real Page Content Back to Inherited Content\n\nIf you no longer need a version-specific page override, you can convert the page back to an inherited marker.\n\nUse `page inherit`:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page inherit \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply --yes page inherit \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nThis is destructive because it removes that version's real `index.md` and replaces it with `inherit.md`.\n\nThe command refuses when no earlier version provides real page content for the same path.\n\nManual fallback if you need finer control:\n\n1. Identify the inherited source page you want to override.\n1. Copy that page's current content into the later version as a starting point.\n1. Replace the later version's empty `inherit.md` with a real `index.md`.\n1. Edit the new `index.md` for the version-specific behavior.\n\nThis is still not a page-creation step. The page identity and nav structure already exist; `page materialize` only turns the inherited marker into authored page content in the selected version.\n\nIf a position selector fails, the CLI also reports the valid sibling slugs so you can retry without opening the nav file first.\n\n## Safety Model\n\nThe docs editor is deliberately conservative.\n\n- preview is the default\n- no files are written unless you pass `--apply`\n- destructive operations require confirmation unless you pass `--yes`\n- docs validation runs automatically after a successful apply\n\n### Refusal Semantics\n\nThe tool refuses destructive operations when they would silently rewrite newer authored content.\n\nTypical refusal case:\n\n- an older version rename would force changes into a later version that already has real content at the affected path\n\nIn that case, the CLI exits non-zero, reports the refusal reason, and leaves the docs tree unchanged.\n\n## Generate a Docs Structure Report\n\nThe docs editor package also includes a standalone report generator for exploring the docs tree across versions.\n\nUse it when you want a repo-local HTML view of:\n\n- books, sections, and pages in one expandable tree-table\n- current-version metadata and version status labels\n- inherited versus authored versus branched page states\n- diff counts for branched pages relative to the earlier authored version\n- per-page version comparison in the side panel\n\nThe wrapper script lives at `website/scripts/docs-report.py`.\n\nFor normal contributor workflow, prefer the repo helper:\n\n```bash\ncd /workspace\npython3 scripts/update-docs-derived-artifacts.py\n```\n\nThat helper centralizes the repo-local behavior around derived docs artifacts.\n\n- the pre-commit hook calls it automatically when staged docs inputs can stale the committed report\n- it stages the refreshed report for you in that hook-driven path\n- the VS Code workspace task `Website: Refresh Docs Derived Artifacts` runs the same helper manually\n\nGenerate the report into the committed output path:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py\n```\n\nThat writes `website-meta/docs-reports/docs-structure-report.html`.\n\nUse check mode in CI or before opening a pull request:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py --check\n```\n\nThat exits non-zero when the committed HTML report is stale.\n\n## Detailed Reference\n\nThe full CLI reference now lives on a separate page so this overview can stay task-focused.\n\nUse [Docs Editor Operation Reference](../docs-editor-operation-reference/) when you need:\n\n- the full global option list\n- forward-impact analysis rules\n- content invariants preserved by the tool\n- real-content stub and inherited-marker behavior\n- preview output details\n- per-entity create, delete, and rename reference behavior\n", "1.0": "+++\ntitle = \"Docs Editor Tool\"\n+++\n\nThe docs editor CLI manages structural website docs changes safely and consistently. For ordinary copy edits inside an existing page, edit the Markdown file directly instead.\n\nPreview is the default mode. Run a command once to inspect the plan, then rerun it with `--apply` when the preview matches what you want.\n\n## Tool Location\n\nThe CLI lives at `website/scripts/docs-editor.py`.\n\nRun it from the `website/` directory:\n\n```bash\ncd website\npython3 scripts/docs-editor.py [global-options] \u003centity\u003e \u003coperation\u003e [operation-options]\n```\n\n## Normal Workflow\n\nUse the tool in this order:\n\n1. run the command in preview mode first\n2. review the planned metadata and file changes\n3. rerun the command with `--apply` when the plan is correct\n4. add `--yes` for destructive apply operations in non-interactive shells\n\nAfter a successful apply, the tool runs docs validation automatically.\n\nThe human-readable preview now shows:\n\n- the operation summary\n- the key metadata for the operation\n- the planned file and nav changes\n\n## What the Tool Handles\n\nThe docs editor supports four entity types:\n\n- versions\n- books\n- sections\n- pages\n\nSupported structural operations include:\n\n- creating\n- deleting\n- materializing inherited landing content\n- moving pages between sections\n- renaming\n\nThe docs editor package also includes a standalone visualization report generator for the docs tree.\n\n## Common Tasks\n\nUse the built-in help when you know the action but not the exact flags:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --help\npython3 scripts/docs-editor.py page create --help\n```\n\nUse these commands as a starting point for the most common workflows:\n\n- add a new page\n- materialize an inherited book landing page\n- move a page to another section\n- rename a page or section\n- create a new docs version that inherits from the latest one\n\n## Example: Create a New Version\n\nThis example:\n\n- creates `0.8` as a new version\n- adds it as to the end of the version list as the newest version (`--latest`)\n- adds the status label `preview` (which is shown in the UI)\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\n## Example: Create a New Book\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\n## Example: Create a Structural-Only Section\n\nThis is useful when you want a navigation group without a section landing page.\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --title \"Authoring And Tooling\" \\\n  --position end \\\n  --structural-only\n```\n\nThat creates the section directory and nav entry without `_index.md` or `_inherit.md`.\n\n## Example: Create a New Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\n## Example: Rename a Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --from website-and-docs-architecture-overview \\\n  --to website-and-docs-system-overview \\\n  --title \"Website And Docs System Overview\"\n```\n\nThat preview is especially useful when a rename may propagate into inherited descendants, because the metadata section shows which later inherited versions will follow the rename.\n\n## Convert an Inherited Page to Real Content\n\nSometimes a later version already has the page path and nav entry, but the page itself is still inherited through an empty `inherit.md` marker.\n\nIn that case, do not use `page create`. The page already exists structurally.\n\nUse `page materialize`:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page materialize \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page materialize \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nThat command:\n\n- removes the empty `inherit.md` marker in that version\n- copies the currently resolved inherited `index.md` content into the page directory\n- lets you optionally replace the page title with `--title`\n\nAfter that, edit the new `index.md` for the version-specific behavior.\n\n## Convert an Inherited Book Landing Page to Real Content\n\nUse `book materialize` when a version inherits a book landing page through `_inherit.md` and needs version-specific copy:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply book materialize \\\n  --version 0.9 \\\n  --book admin-guide\n```\n\nThe command replaces `_inherit.md` with the currently resolved `_index.md` content. Use `--title` to replace its title while materializing.\n\n## Move a Page Between Sections\n\nUse `page move` to move a page within one book while preserving its body content:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page move \\\n  --version 0.9 \\\n  --book admin-guide \\\n  --from-section configuration \\\n  --to-section reference \\\n  --page configuration-key-reference \\\n  --to-page configuration-file-reference \\\n  --position start\n```\n\nThe tool updates both page lists, creates real content at the destination, and removes the source directory. `--to-page` is optional and defaults to the source page slug. `--position` applies to the selected version's destination section.\n\nLater inherited-only versions follow the move automatically. The tool refuses when the destination exists, a later version has authored source content, or a later version lacks the destination section. Update Markdown links and managed redirects separately.\n\n## Convert Real Page Content Back to Inherited Content\n\nIf you no longer need a version-specific page override, you can convert the page back to an inherited marker.\n\nUse `page inherit`:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page inherit \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply --yes page inherit \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nThis is destructive because it removes that version's real `index.md` and replaces it with `inherit.md`.\n\nThe command refuses when no earlier version provides real page content for the same path.\n\nManual fallback if you need finer control:\n\n1. Identify the inherited source page you want to override.\n1. Copy that page's current content into the later version as a starting point.\n1. Replace the later version's empty `inherit.md` with a real `index.md`.\n1. Edit the new `index.md` for the version-specific behavior.\n\nThis is still not a page-creation step. The page identity and nav structure already exist; `page materialize` only turns the inherited marker into authored page content in the selected version.\n\nIf a position selector fails, the CLI also reports the valid sibling slugs so you can retry without opening the nav file first.\n\n## Safety Model\n\nThe docs editor is deliberately conservative.\n\n- preview is the default\n- no files are written unless you pass `--apply`\n- destructive operations require confirmation unless you pass `--yes`\n- docs validation runs automatically after a successful apply\n\n### Refusal Semantics\n\nThe tool refuses destructive operations when they would silently rewrite newer authored content.\n\nTypical refusal case:\n\n- an older version rename would force changes into a later version that already has real content at the affected path\n\nIn that case, the CLI exits non-zero, reports the refusal reason, and leaves the docs tree unchanged.\n\n## Generate a Docs Structure Report\n\nThe docs editor package also includes a standalone report generator for exploring the docs tree across versions.\n\nUse it when you want a repo-local HTML view of:\n\n- books, sections, and pages in one expandable tree-table\n- current-version metadata and version status labels\n- inherited versus authored versus branched page states\n- diff counts for branched pages relative to the earlier authored version\n- per-page version comparison in the side panel\n\nThe wrapper script lives at `website/scripts/docs-report.py`.\n\nFor normal contributor workflow, prefer the repo helper:\n\n```bash\ncd /workspace\npython3 scripts/update-docs-derived-artifacts.py\n```\n\nThat helper centralizes the repo-local behavior around derived docs artifacts.\n\n- the pre-commit hook calls it automatically when staged docs inputs can stale the committed report\n- it stages the refreshed report for you in that hook-driven path\n- the VS Code workspace task `Website: Refresh Docs Derived Artifacts` runs the same helper manually\n\nGenerate the report into the committed output path:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py\n```\n\nThat writes `website-meta/docs-reports/docs-structure-report.html`.\n\nUse check mode in CI or before opening a pull request:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py --check\n```\n\nThat exits non-zero when the committed HTML report is stale.\n\n## Detailed Reference\n\nThe full CLI reference now lives on a separate page so this overview can stay task-focused.\n\nUse [Docs Editor Operation Reference](../docs-editor-operation-reference/) when you need:\n\n- the full global option list\n- forward-impact analysis rules\n- content invariants preserved by the tool\n- real-content stub and inherited-marker behavior\n- preview output details\n- per-entity create, delete, and rename reference behavior\n", "2.0": "+++\ntitle = \"Docs Editor Tool\"\n+++\n\nThe docs editor CLI manages structural website docs changes safely and consistently. For ordinary copy edits inside an existing page, edit the Markdown file directly instead.\n\nPreview is the default mode. Run a command once to inspect the plan, then rerun it with `--apply` when the preview matches what you want.\n\n## Tool Location\n\nThe CLI lives at `website/scripts/docs-editor.py`.\n\nRun it from the `website/` directory:\n\n```bash\ncd website\npython3 scripts/docs-editor.py [global-options] \u003centity\u003e \u003coperation\u003e [operation-options]\n```\n\n## Normal Workflow\n\nUse the tool in this order:\n\n1. run the command in preview mode first\n2. review the planned metadata and file changes\n3. rerun the command with `--apply` when the plan is correct\n4. add `--yes` for destructive apply operations in non-interactive shells\n\nAfter a successful apply, the tool runs docs validation automatically.\n\nThe human-readable preview now shows:\n\n- the operation summary\n- the key metadata for the operation\n- the planned file and nav changes\n\n## What the Tool Handles\n\nThe docs editor supports four entity types:\n\n- versions\n- books\n- sections\n- pages\n\nSupported structural operations include:\n\n- creating\n- deleting\n- materializing inherited landing content\n- moving pages between sections\n- renaming\n\nThe docs editor package also includes a standalone visualization report generator for the docs tree.\n\n## Common Tasks\n\nUse the built-in help when you know the action but not the exact flags:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --help\npython3 scripts/docs-editor.py page create --help\n```\n\nUse these commands as a starting point for the most common workflows:\n\n- add a new page\n- materialize an inherited book landing page\n- move a page to another section\n- rename a page or section\n- create a new docs version that inherits from the latest one\n\n## Example: Create a New Version\n\nThis example:\n\n- creates `0.8` as a new version\n- adds it as to the end of the version list as the newest version (`--latest`)\n- adds the status label `preview` (which is shown in the UI)\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply version create 0.8 \\\n  --latest \\\n  --status preview\n```\n\n## Example: Create a New Book\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\nApply the same change:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply book create \\\n  --version 0.7 \\\n  --book tutorials \\\n  --title \"Tutorials\"\n```\n\n## Example: Create a Structural-Only Section\n\nThis is useful when you want a navigation group without a section landing page.\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --title \"Authoring And Tooling\" \\\n  --position end \\\n  --structural-only\n```\n\nThat creates the section directory and nav entry without `_index.md` or `_inherit.md`.\n\n## Example: Create a New Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page create \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section authoring-and-tooling \\\n  --page docs-editor-quickstart \\\n  --title \"Docs Editor Quickstart\"\n```\n\n## Example: Rename a Page\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename \\\n  --version 0.7 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --from website-and-docs-architecture-overview \\\n  --to website-and-docs-system-overview \\\n  --title \"Website And Docs System Overview\"\n```\n\nThat preview is especially useful when a rename may propagate into inherited descendants, because the metadata section shows which later inherited versions will follow the rename.\n\n## Convert an Inherited Page to Real Content\n\nSometimes a later version already has the page path and nav entry, but the page itself is still inherited through an empty `inherit.md` marker.\n\nIn that case, do not use `page create`. The page already exists structurally.\n\nUse `page materialize`:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page materialize \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply page materialize \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nThat command:\n\n- removes the empty `inherit.md` marker in that version\n- copies the currently resolved inherited `index.md` content into the page directory\n- lets you optionally replace the page title with `--title`\n\nAfter that, edit the new `index.md` for the version-specific behavior.\n\n## Convert an Inherited Book Landing Page to Real Content\n\nUse `book materialize` when a version inherits a book landing page through `_inherit.md` and needs version-specific copy:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply book materialize \\\n  --version 0.9 \\\n  --book admin-guide\n```\n\nThe command replaces `_inherit.md` with the currently resolved `_index.md` content. Use `--title` to replace its title while materializing.\n\n## Move a Page Between Sections\n\nUse `page move` to move a page within one book while preserving its body content:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page move \\\n  --version 0.9 \\\n  --book admin-guide \\\n  --from-section configuration \\\n  --to-section reference \\\n  --page configuration-key-reference \\\n  --to-page configuration-file-reference \\\n  --position start\n```\n\nThe tool updates both page lists, creates real content at the destination, and removes the source directory. `--to-page` is optional and defaults to the source page slug. `--position` applies to the selected version's destination section.\n\nLater inherited-only versions follow the move automatically. The tool refuses when the destination exists, a later version has authored source content, or a later version lacks the destination section. Update Markdown links and managed redirects separately.\n\n## Convert Real Page Content Back to Inherited Content\n\nIf you no longer need a version-specific page override, you can convert the page back to an inherited marker.\n\nUse `page inherit`:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page inherit \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nApply it:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply --yes page inherit \\\n  --version 0.8 \\\n  --book website-dev-guide \\\n  --section docs-platform \\\n  --page website-and-docs-architecture-overview\n```\n\nThis is destructive because it removes that version's real `index.md` and replaces it with `inherit.md`.\n\nThe command refuses when no earlier version provides real page content for the same path.\n\nManual fallback if you need finer control:\n\n1. Identify the inherited source page you want to override.\n1. Copy that page's current content into the later version as a starting point.\n1. Replace the later version's empty `inherit.md` with a real `index.md`.\n1. Edit the new `index.md` for the version-specific behavior.\n\nThis is still not a page-creation step. The page identity and nav structure already exist; `page materialize` only turns the inherited marker into authored page content in the selected version.\n\nIf a position selector fails, the CLI also reports the valid sibling slugs so you can retry without opening the nav file first.\n\n## Safety Model\n\nThe docs editor is deliberately conservative.\n\n- preview is the default\n- no files are written unless you pass `--apply`\n- destructive operations require confirmation unless you pass `--yes`\n- docs validation runs automatically after a successful apply\n\n### Refusal Semantics\n\nThe tool refuses destructive operations when they would silently rewrite newer authored content.\n\nTypical refusal case:\n\n- an older version rename would force changes into a later version that already has real content at the affected path\n\nIn that case, the CLI exits non-zero, reports the refusal reason, and leaves the docs tree unchanged.\n\n## Generate a Docs Structure Report\n\nThe docs editor package also includes a standalone report generator for exploring the docs tree across versions.\n\nUse it when you want a repo-local HTML view of:\n\n- books, sections, and pages in one expandable tree-table\n- current-version metadata and version status labels\n- inherited versus authored versus branched page states\n- diff counts for branched pages relative to the earlier authored version\n- per-page version comparison in the side panel\n\nThe wrapper script lives at `website/scripts/docs-report.py`.\n\nFor normal contributor workflow, prefer the repo helper:\n\n```bash\ncd /workspace\npython3 scripts/update-docs-derived-artifacts.py\n```\n\nThat helper centralizes the repo-local behavior around derived docs artifacts.\n\n- the pre-commit hook calls it automatically when staged docs inputs can stale the committed report\n- it stages the refreshed report for you in that hook-driven path\n- the VS Code workspace task `Website: Refresh Docs Derived Artifacts` runs the same helper manually\n\nGenerate the report into the committed output path:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py\n```\n\nThat writes `website-meta/docs-reports/docs-structure-report.html`.\n\nUse check mode in CI or before opening a pull request:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py --check\n```\n\nThat exits non-zero when the committed HTML report is stale.\n\n## Detailed Reference\n\nThe full CLI reference now lives on a separate page so this overview can stay task-focused.\n\nUse [Docs Editor Operation Reference](../docs-editor-operation-reference/) when you need:\n\n- the full global option list\n- forward-impact analysis rules\n- content invariants preserved by the tool\n- real-content stub and inherited-marker behavior\n- preview output details\n- per-entity create, delete, and rename reference behavior\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:website-dev-guide/authoring-and-tooling/docs-editor-operation-reference", "parent_id": "section:website-dev-guide/authoring-and-tooling", "depth": 2, "kind": "page", "label": "docs-editor-operation-reference", "title": "Docs Editor Operation Reference", "path": "website-dev-guide/authoring-and-tooling/docs-editor-operation-reference", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "branched", "source_version": "0.7", "diff_added": 60, "diff_removed": 4}, "0.9": {"state": "branched", "source_version": "0.8", "diff_added": 29, "diff_removed": 5}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "inherited", "source_version": "0.9"}}, "content_versions": {"0.7": "`book create` creates a book folder, writes `_index.md` by default or `_inherit.md` with `--inherit`, and inserts the book into the version nav file. With `--structural-only`, it creates no landing file. `--structural-only` cannot be combined with `--inherit` or `--title`.\n`book rename` renames the book directory, updates `books` ordering plus the associated `sections` and `pages` tables, and propagates inherited-only descendants when allowed. It preserves a structural-only book as structural-only; `--title` is not valid when renaming such a book.\n+++\ntitle = \"Docs Editor Operation Reference\"\n+++\n\nUse this page when you already know you need the docs editor and want the detailed reference behavior.\n\n## Position Selectors\n\nOperations that insert books, sections, or pages use the same position syntax:\n\n- `\u003cindex\u003e`: insert at a zero-based numeric index\n- `before:\u003cslug\u003e`: insert immediately before the existing item\n- `after:\u003cslug\u003e`: insert immediately after the existing item\n- `start`: insert at the beginning\n- `end`: insert at the end\n\nIf the requested selector does not resolve cleanly in the target nav list, the operation refuses instead of guessing.\n\n## Global Options\n\nThe CLI supports these global options:\n\n- `--apply`: write changes to disk instead of previewing them\n- `--yes`: skip confirmation for destructive apply operations\n- `--json`: emit machine-readable preview or result output\n- `--quiet`: reduce non-error output\n- `--verbose`: reserved for future detailed output\n\n## Forward-Impact Analysis\n\nChanges in an older version can affect newer versions that still resolve through the same path. The tool analyzes that forward impact before destructive rename and delete operations.\n\nAffected newer versions fall into these categories:\n\n- inherited-only descendants: newer versions that contain only marker files for the affected path\n- structural descendants: newer versions that keep the path only as structure, without landing-page content\n- modified descendants: newer versions that contain real `_index.md` or `index.md` content at the affected path\n\nDefault behavior:\n\n- inherited-only descendants are updated automatically in apply mode\n- structural descendants are preserved where the operation allows it\n- modified descendants block destructive rename and delete operations\n\n## Content Rules the Tool Preserves\n\nThe docs editor preserves these invariants:\n\n- docs identity remains path-derived\n- `doc_id`, `product_version`, and `aliases` are not introduced\n- page folders contain exactly one of `index.md` or `inherit.md`\n- version and book folders contain exactly one of `_index.md` or `_inherit.md`\n- section folders contain zero or one of `_index.md` or `_inherit.md`\n- `inherit.md` and `_inherit.md` remain empty marker files\n- version order in `website/data/docs-versions.toml` stays canonical\n- nav data remains ordering-only metadata\n\n## Real Content Stubs\n\nWhen the tool creates real content, it writes a minimal front matter stub.\n\nDefaults:\n\n- page `index.md`: `title` defaults to a humanized page slug unless `--title` is provided\n- section `_index.md`: `title` defaults to the section title from nav data unless `--title` is provided\n- book `_index.md`: `title` defaults to a humanized book slug unless `--title` is provided\n- version `_index.md`: `title` defaults to the version label unless `--title` is provided\n\n## Inherited Markers\n\nWhen the tool creates inherited content, it writes:\n\n- empty `inherit.md` files for pages\n- empty `_inherit.md` files for version, book, and section landing pages\n\nNo front matter or body content is written into marker files.\n\n## Output Formats\n\nHuman-readable preview output shows the operation, the target path or version, the planned file changes, and the metadata changes that will be made on apply.\n\nJSON preview output includes:\n\n- `result`\n- `destructive`\n- `apply`\n- `metadata`\n- `changes`\n\nFor propagated destructive operations, `metadata` includes `propagated_versions` when later inherited-only versions will follow the change.\n\n## Operation Reference\n\n### Version Operations\n\n`version create` adds a new docs version, creates the matching content tree, initializes the new version to inherit from the previous version, and creates a matching nav file.\n\nRequired input:\n\n- new version slug\n- one insertion selector: `--after \u003cexisting-version\u003e` or `--latest`\n\nOptional input:\n\n- `--label \u003clabel\u003e`\n- `--status \u003cstatus\u003e`: optional UI label appended in parentheses after the version label, for example `preview` or `current`\n- `--visible true|false`\n- `--searchable true|false`\n- `--set-current`\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 1.2 --after 1.1 --label \"1.2\"\n```\n\nBehavior:\n\n1. inserts the new version into `website/data/docs-versions.toml`\n2. creates `website/content/docs/\u003cnew-version\u003e/`\n3. creates `website/data/docs-nav/\u003cnew-version\u003e.toml` from the previous version's nav data\n4. mirrors the previous version's docs tree shape\n5. creates inherited markers instead of copying authored content\n\nBootstrap behavior:\n\n- if `docs-versions.toml` has no declared versions, `--latest` bootstraps the first version instead of inheriting from a base version\n- in that case, the tool creates an authored version root with `_index.md`, creates an empty nav file, and sets the new version as `current`\n- this bootstrap path only works for a truly empty docs workspace; if version directories or version nav files still exist on disk, reconcile or remove them first\n\nImportant details:\n\n- the new version slug must not collide with an existing version\n- the reference version must exist\n- `status` is display metadata only; it does not decide which version is current\n- the actual current docs version is controlled by the top-level `current = \"\u003cslug\u003e\"` entry in `website/data/docs-versions.toml`\n- the current docs version changes only when `--set-current` is passed\n- `searchable` defaults to `false` unless explicitly set otherwise\n\n`version delete` removes a version entry, its nav file, and its content directory.\n\nRequired input:\n\n- version slug\n\nOptional input:\n\n- `--new-current \u003cversion\u003e` when deleting the current version\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version delete 1.1\n```\n\nBehavior:\n\n1. removes the version from `website/data/docs-versions.toml`\n2. removes `website/data/docs-nav/\u003cversion\u003e.toml`\n3. removes `website/content/docs/\u003cversion\u003e/`\n4. revalidates inheritance resolution across remaining versions\n\nRefusal cases:\n\n- the version does not exist\n- the version is current and `--new-current` was not supplied\n- `--new-current` points to the deleted version\n- `--new-current` does not exist after deletion\n- `--new-current` was supplied while deleting a non-current version\n\n### Book Operations\n\n`book create` creates a book folder, writes `_index.md` by default or `_inherit.md` with `--inherit`, and inserts the book into the version nav file.\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create --version 1.1 --book tutorials --title \"Tutorials\" --position end\n```\n\n`book delete` removes the book folder, the book entry in nav data, and the matching `sections.\u003cbook\u003e` and `pages.\u003cbook\u003e` data.\n\n`book rename` renames the book directory, updates `books` ordering plus the associated `sections` and `pages` tables, and propagates inherited-only descendants when allowed.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book rename --version 1.1 --from end-user --to user-guide --title \"User Guide\"\n```\n\n### Section Operations\n\n`section create` creates a section directory, adds a section entry in nav data, and initializes an empty `pages.\u003cbook\u003e.\u003csection\u003e.items` array.\n\nBy default it creates `_index.md`. With `--inherit`, it creates `_inherit.md`. With `--structural-only`, it creates no landing file. Optional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create --version 1.1 --book admin --section authentication --title \"Authentication\" --position end\n```\n\n`section delete` removes the section directory, its nav entry, and the matching `pages.\u003cbook\u003e.\u003csection\u003e` table.\n\n`section rename` renames the section directory, updates `sections.\u003cbook\u003e.items`, moves the matching `pages.\u003cbook\u003e.\u003csection\u003e` table to the new key, and preserves structural-only descendants as structural-only when no landing file exists at the renamed path.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section rename --version 1.1 --book admin --from configuration --to authentication --title \"Authentication\"\n```\n\n### Page Operations\n\n`page create` creates the page directory, writes `index.md` by default or `inherit.md` with `--inherit`, and adds the page slug to `pages.\u003cbook\u003e.\u003csection\u003e.items`.\n\nUse `page create` only when the page does not already exist in that version.\n\nIf the page already exists as an inherited page marker:\n\n- the directory already exists\n- the nav entry already exists\n- the page folder contains an empty `inherit.md`\n\nThen the correct workflow is to materialize real content manually:\n\n1. remove the inherited marker\n1. add `index.md`\n1. copy the inherited page body as the starting point\n1. edit that authored copy for the version-specific behavior\n\nThis is intentionally outside the scope of `page create`, because the page identity and nav structure already exist.\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create --version 1.1 --book developer --section architecture --page overview --title \"Architecture Overview\"\n```\n\n`page delete` removes the page directory and the matching page slug from nav data.\n\n`page rename` renames the page directory, updates `pages.\u003cbook\u003e.\u003csection\u003e.items`, and propagates inherited-only descendants when allowed.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename --version 1.1 --book end-user --section getting-started --from install --to setup --title \"Setup Sambee\"\n```\n\n## Notes\n\n- the tool does not edit `website/.generated/` directly\n- the tool does not run `materialize-inherited-docs.py` for you\n- the tool does not edit page body content or offer free-form front matter editing\n", "0.8": "+++\ntitle = \"Docs Editor Operation Reference\"\n+++\n\nUse this page when you already know you need the docs editor and want the detailed reference behavior.\n\n## Position Selectors\n\nOperations that insert books, sections, or pages use the same position syntax:\n\n- `\u003cindex\u003e`: insert at a zero-based numeric index\n- `before:\u003cslug\u003e`: insert immediately before the existing item\n- `after:\u003cslug\u003e`: insert immediately after the existing item\n- `start`: insert at the beginning\n- `end`: insert at the end\n\nIf the requested selector does not resolve cleanly in the target nav list, the operation refuses instead of guessing.\n\n## Global Options\n\nThe CLI supports these global options:\n\n- `--apply`: write changes to disk instead of previewing them\n- `--yes`: skip confirmation for destructive apply operations\n- `--json`: emit machine-readable preview or result output\n- `--quiet`: reduce non-error output\n- `--verbose`: reserved for future detailed output\n\n## Forward-Impact Analysis\n\nChanges in an older version can affect newer versions that still resolve through the same path. The tool analyzes that forward impact before destructive rename and delete operations.\n\nAffected newer versions fall into these categories:\n\n- inherited-only descendants: newer versions that contain only marker files for the affected path\n- structural descendants: newer versions that keep the path only as structure, without landing-page content\n- modified descendants: newer versions that contain real `_index.md` or `index.md` content at the affected path\n\nDefault behavior:\n\n- inherited-only descendants are updated automatically in apply mode\n- structural descendants are preserved where the operation allows it\n- modified descendants block destructive rename and delete operations\n\n## Content Rules the Tool Preserves\n\nThe docs editor preserves these invariants:\n\n- docs identity remains path-derived\n- `doc_id`, `product_version`, and `aliases` are not introduced\n- page folders contain exactly one of `index.md` or `inherit.md`\n- version and book folders contain exactly one of `_index.md` or `_inherit.md`\n- section folders contain zero or one of `_index.md` or `_inherit.md`\n- `inherit.md` and `_inherit.md` remain empty marker files\n- version order in `website/data/docs-versions.toml` stays canonical\n- nav data remains ordering-only metadata\n\n## Real Content Stubs\n\nWhen the tool creates real content, it writes a minimal front matter stub.\n\nDefaults:\n\n- page `index.md`: `title` defaults to a humanized page slug unless `--title` is provided\n- section `_index.md`: `title` defaults to the section title from nav data unless `--title` is provided\n- book `_index.md`: `title` defaults to a humanized book slug unless `--title` is provided\n- version `_index.md`: `title` defaults to the version label unless `--title` is provided\n\n## Inherited Markers\n\nWhen the tool creates inherited content, it writes:\n\n- empty `inherit.md` files for pages\n- empty `_inherit.md` files for version, book, and section landing pages\n\nNo front matter or body content is written into marker files.\n\n## Output Formats\n\nHuman-readable preview output shows the operation, the target path or version, the planned file changes, and the metadata changes that will be made on apply.\n\nJSON preview output includes:\n\n- `result`\n- `destructive`\n- `apply`\n- `metadata`\n- `changes`\n\nFor propagated destructive operations, `metadata` includes `propagated_versions` when later inherited-only versions will follow the change.\n\n## Standalone Report Generator\n\nUse [Docs Editor Tool](../docs-editor-tool/) for the high-level explanation of when to use the report and what it shows.\n\nThis reference section keeps only the CLI-specific behavior.\n\nThe report generator command is `website/scripts/docs-report.py`.\n\nBehavior:\n\n1. reads version metadata, nav files, and docs content directly from the repository\n2. writes `website-meta/docs-reports/docs-structure-report.html` by default\n3. embeds the report data, CSS, and JavaScript into one standalone HTML file\n\nExample:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py\n```\n\nCheck mode compares the current repository state against the committed HTML report and exits non-zero when the report needs regeneration:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py --check\n```\n\n## Operation Reference\n\n### Version Operations\n\n`version create` adds a new docs version, creates the matching content tree, initializes the new version to inherit from the previous version, and creates a matching nav file.\n\nRequired input:\n\n- new version slug\n- one insertion selector: `--after \u003cexisting-version\u003e` or `--latest`\n\nOptional input:\n\n- `--label \u003clabel\u003e`\n- `--status \u003cstatus\u003e`: optional UI label appended in parentheses after the version label, for example `preview` or `current`\n- `--visible true|false`\n- `--searchable true|false`\n- `--set-current`\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 1.2 --after 1.1 --label \"1.2\"\n```\n\nBehavior:\n\n1. inserts the new version into `website/data/docs-versions.toml`\n2. creates `website/content/docs/\u003cnew-version\u003e/`\n3. creates `website/data/docs-nav/\u003cnew-version\u003e.toml` from the previous version's nav data\n4. mirrors the previous version's docs tree shape\n5. creates inherited markers instead of copying authored content\n\nBootstrap behavior:\n\n- if `docs-versions.toml` has no declared versions, `--latest` bootstraps the first version instead of inheriting from a base version\n- in that case, the tool creates an authored version root with `_index.md`, creates an empty nav file, and sets the new version as `current`\n- this bootstrap path only works for a truly empty docs workspace; if version directories or version nav files still exist on disk, reconcile or remove them first\n\nImportant details:\n\n- the new version slug must not collide with an existing version\n- the reference version must exist\n- `status` is display metadata only; it does not decide which version is current\n- the actual current docs version is controlled by the top-level `current = \"\u003cslug\u003e\"` entry in `website/data/docs-versions.toml`\n- the current docs version changes only when `--set-current` is passed\n- `searchable` defaults to `false` unless explicitly set otherwise\n\n`version delete` removes a version entry, its nav file, and its content directory.\n\nRequired input:\n\n- version slug\n\nOptional input:\n\n- `--new-current \u003cversion\u003e` when deleting the current version\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version delete 1.1\n```\n\nBehavior:\n\n1. removes the version from `website/data/docs-versions.toml`\n2. removes `website/data/docs-nav/\u003cversion\u003e.toml`\n3. removes `website/content/docs/\u003cversion\u003e/`\n4. revalidates inheritance resolution across remaining versions\n\nRefusal cases:\n\n- the version does not exist\n- the version is current and `--new-current` was not supplied\n- `--new-current` points to the deleted version\n- `--new-current` does not exist after deletion\n- `--new-current` was supplied while deleting a non-current version\n\n### Book Operations\n\n`book create` creates a book folder, writes `_index.md` by default or `_inherit.md` with `--inherit`, and inserts the book into the version nav file.\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create --version 1.1 --book tutorials --title \"Tutorials\" --position end\n```\n\n`book delete` removes the book folder, the book entry in nav data, and the matching `sections.\u003cbook\u003e` and `pages.\u003cbook\u003e` data.\n\n`book rename` renames the book directory, updates `books` ordering plus the associated `sections` and `pages` tables, and propagates inherited-only descendants when allowed.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book rename --version 1.1 --from end-user --to user-guide --title \"User Guide\"\n```\n\n### Section Operations\n\n`section create` creates a section directory, adds a section entry in nav data, and initializes an empty `pages.\u003cbook\u003e.\u003csection\u003e.items` array.\n\nBy default it creates `_index.md`. With `--inherit`, it creates `_inherit.md`. With `--structural-only`, it creates no landing file. Optional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create --version 1.1 --book admin --section authentication --title \"Authentication\" --position end\n```\n\n`section delete` removes the section directory, its nav entry, and the matching `pages.\u003cbook\u003e.\u003csection\u003e` table.\n\n`section rename` renames the section directory, updates `sections.\u003cbook\u003e.items`, moves the matching `pages.\u003cbook\u003e.\u003csection\u003e` table to the new key, and preserves structural-only descendants as structural-only when no landing file exists at the renamed path.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section rename --version 1.1 --book admin --from configuration --to authentication --title \"Authentication\"\n```\n\n### Page Operations\n\n`page create` creates the page directory, writes `index.md` by default or `inherit.md` with `--inherit`, and adds the page slug to `pages.\u003cbook\u003e.\u003csection\u003e.items`.\n\nUse `page create` only when the page does not already exist in that version.\n\nIf the page already exists as an inherited page marker:\n\n- the directory already exists\n- the nav entry already exists\n- the page folder contains an empty `inherit.md`\n\nThen use `page materialize` instead of `page create`.\n\n`page materialize` replaces `inherit.md` with a real `index.md`, using the currently resolved inherited page content as the starting point.\n\nOptional input:\n\n- `--title \u003ctitle\u003e`: replace the inherited page title while materializing the real content\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page materialize --version 0.8 --book website-dev-guide --section docs-platform --page website-and-docs-architecture-overview\n```\n\nManual fallback if you need to control the copy step yourself:\n\n1. remove the inherited marker\n1. add `index.md`\n1. copy the inherited page body as the starting point\n1. edit that authored copy for the version-specific behavior\n\nThis remains outside the scope of `page create`, because the page identity and nav structure already exist.\n\n`page inherit` does the reverse: it replaces a real `index.md` in the selected version with `inherit.md` so the page resolves from an earlier authored version again.\n\nImportant details:\n\n- it is destructive because it removes that version's authored page content\n- apply mode requires `--yes` in non-interactive shells\n- it refuses when no earlier version resolves the same path to real `index.md` content\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply --yes page inherit --version 0.8 --book website-dev-guide --section docs-platform --page website-and-docs-architecture-overview\n```\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create --version 1.1 --book developer --section architecture --page overview --title \"Architecture Overview\"\n```\n\n`page delete` removes the page directory and the matching page slug from nav data.\n\n`page rename` renames the page directory, updates `pages.\u003cbook\u003e.\u003csection\u003e.items`, and propagates inherited-only descendants when allowed.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename --version 1.1 --book end-user --section getting-started --from install --to setup --title \"Setup Sambee\"\n```\n\n## Notes\n\n- the tool does not edit `website/.generated/` directly\n- the tool does not run `materialize-inherited-docs.py` for you\n- the tool does not edit page body content or offer free-form front matter editing\n", "0.9": "+++\ntitle = \"Docs Editor Operation Reference\"\n+++\n\nUse this page when you already know you need the docs editor and want the detailed reference behavior.\n\n## Position Selectors\n\nOperations that insert books, sections, or pages use the same position syntax:\n\n- `\u003cindex\u003e`: insert at a zero-based numeric index\n- `before:\u003cslug\u003e`: insert immediately before the existing item\n- `after:\u003cslug\u003e`: insert immediately after the existing item\n- `start`: insert at the beginning\n- `end`: insert at the end\n\nIf the requested selector does not resolve cleanly in the target nav list, the operation refuses instead of guessing.\n\n## Global Options\n\nThe CLI supports these global options:\n\n- `--apply`: write changes to disk instead of previewing them\n- `--yes`: skip confirmation for destructive apply operations\n- `--json`: emit machine-readable preview or result output\n- `--quiet`: reduce non-error output\n- `--verbose`: reserved for future detailed output\n\n## Forward-Impact Analysis\n\nChanges in an older version can affect newer versions that still resolve through the same path. The tool analyzes that forward impact before destructive rename and delete operations.\n\nAffected newer versions fall into these categories:\n\n- inherited-only descendants: newer versions that contain only marker files for the affected path\n- structural descendants: newer versions that keep the path only as structure, without landing-page content\n- modified descendants: newer versions that contain real `_index.md` or `index.md` content at the affected path\n\nDefault behavior:\n\n- inherited-only descendants are updated automatically in apply mode\n- structural descendants are preserved where the operation allows it\n- modified descendants block destructive rename and delete operations\n\n## Content Rules the Tool Preserves\n\nThe docs editor preserves these invariants:\n\n- docs identity remains path-derived\n- `doc_id`, `product_version`, and `aliases` are not introduced\n- page folders contain exactly one of `index.md` or `inherit.md`\n- version and book folders contain exactly one of `_index.md` or `_inherit.md`\n- section folders contain zero or one of `_index.md` or `_inherit.md`\n- `inherit.md` and `_inherit.md` remain empty marker files\n- version order in `website/data/docs-versions.toml` stays canonical\n- nav data remains ordering-only metadata\n\n## Real Content Stubs\n\nWhen the tool creates real content, it writes a minimal front matter stub.\n\nDefaults:\n\n- page `index.md`: `title` defaults to a humanized page slug unless `--title` is provided\n- section `_index.md`: `title` defaults to the section title from nav data unless `--title` is provided\n- book `_index.md`: `title` defaults to a humanized book slug unless `--title` is provided\n- version `_index.md`: `title` defaults to the version label unless `--title` is provided\n\n## Inherited Markers\n\nWhen the tool creates inherited content, it writes:\n\n- empty `inherit.md` files for pages\n- empty `_inherit.md` files for version, book, and section landing pages\n\nNo front matter or body content is written into marker files.\n\n## Output Formats\n\nHuman-readable preview output shows the operation, the target path or version, the planned file changes, and the metadata changes that will be made on apply.\n\nJSON preview output includes:\n\n- `result`\n- `destructive`\n- `apply`\n- `metadata`\n- `changes`\n\nFor propagated destructive operations, `metadata` includes `propagated_versions` when later inherited-only versions will follow the change.\n\n## Standalone Report Generator\n\nUse [Docs Editor Tool](../docs-editor-tool/) for the high-level explanation of when to use the report and what it shows.\n\nThis reference section keeps only the CLI-specific behavior.\n\nThe report generator command is `website/scripts/docs-report.py`.\n\nBehavior:\n\n1. reads version metadata, nav files, and docs content directly from the repository\n2. writes `website-meta/docs-reports/docs-structure-report.html` by default\n3. embeds the report data, CSS, and JavaScript into one standalone HTML file\n\nExample:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py\n```\n\nCheck mode compares the current repository state against the committed HTML report and exits non-zero when the report needs regeneration:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py --check\n```\n\n## Operation Reference\n\n### Version Operations\n\n`version create` adds a new docs version, creates the matching content tree, initializes the new version to inherit from the previous version, and creates a matching nav file.\n\nRequired input:\n\n- new version slug\n- one insertion selector: `--after \u003cexisting-version\u003e` or `--latest`\n\nOptional input:\n\n- `--label \u003clabel\u003e`\n- `--status \u003cstatus\u003e`: optional UI label appended in parentheses after the version label, for example `preview` or `current`\n- `--visible true|false`\n- `--searchable true|false`\n- `--set-current`\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 1.2 --after 1.1 --label \"1.2\"\n```\n\nBehavior:\n\n1. inserts the new version into `website/data/docs-versions.toml`\n2. creates `website/content/docs/\u003cnew-version\u003e/`\n3. creates `website/data/docs-nav/\u003cnew-version\u003e.toml` from the previous version's nav data\n4. mirrors the previous version's docs tree shape\n5. creates inherited markers instead of copying authored content\n\nBootstrap behavior:\n\n- if `docs-versions.toml` has no declared versions, `--latest` bootstraps the first version instead of inheriting from a base version\n- in that case, the tool creates an authored version root with `_index.md`, creates an empty nav file, and sets the new version as `current`\n- this bootstrap path only works for a truly empty docs workspace; if version directories or version nav files still exist on disk, reconcile or remove them first\n\nImportant details:\n\n- the new version slug must not collide with an existing version\n- the reference version must exist\n- `status` is display metadata only; it does not decide which version is current\n- the actual current docs version is controlled by the top-level `current = \"\u003cslug\u003e\"` entry in `website/data/docs-versions.toml`\n- the current docs version changes only when `--set-current` is passed\n- `searchable` defaults to `false` unless explicitly set otherwise\n\n`version delete` removes a version entry, its nav file, and its content directory.\n\nRequired input:\n\n- version slug\n\nOptional input:\n\n- `--new-current \u003cversion\u003e` when deleting the current version\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version delete 1.1\n```\n\nBehavior:\n\n1. removes the version from `website/data/docs-versions.toml`\n2. removes `website/data/docs-nav/\u003cversion\u003e.toml`\n3. removes `website/content/docs/\u003cversion\u003e/`\n4. revalidates inheritance resolution across remaining versions\n\nRefusal cases:\n\n- the version does not exist\n- the version is current and `--new-current` was not supplied\n- `--new-current` points to the deleted version\n- `--new-current` does not exist after deletion\n- `--new-current` was supplied while deleting a non-current version\n\n### Book Operations\n\n`book create` creates a book folder, writes `_index.md` by default or `_inherit.md` with `--inherit`, and inserts the book into the version nav file.\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create --version 1.1 --book tutorials --title \"Tutorials\" --position end\n```\n\n`book delete` removes the book folder, the book entry in nav data, and the matching `sections.\u003cbook\u003e` and `pages.\u003cbook\u003e` data.\n\n`book rename` renames the book directory, updates `books` ordering plus the associated `sections` and `pages` tables, and propagates inherited-only descendants when allowed.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book rename --version 1.1 --from end-user --to user-guide --title \"User Guide\"\n```\n\n`book materialize` replaces an inherited book `_inherit.md` marker with a real `_index.md` using the currently resolved landing-page content. Use `--title` to replace the title while materializing.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book materialize --version 0.9 --book admin-guide\n```\n\n### Section Operations\n\n`section create` creates a section directory, adds a section entry in nav data, and initializes an empty `pages.\u003cbook\u003e.\u003csection\u003e.items` array.\n\nBy default it creates `_index.md`. With `--inherit`, it creates `_inherit.md`. With `--structural-only`, it creates no landing file. Optional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create --version 1.1 --book admin --section authentication --title \"Authentication\" --position end\n```\n\n`section delete` removes the section directory, its nav entry, and the matching `pages.\u003cbook\u003e.\u003csection\u003e` table.\n\n`section rename` renames the section directory, updates `sections.\u003cbook\u003e.items`, moves the matching `pages.\u003cbook\u003e.\u003csection\u003e` table to the new key, and preserves structural-only descendants as structural-only when no landing file exists at the renamed path.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section rename --version 1.1 --book admin --from configuration --to authentication --title \"Authentication\"\n```\n\n### Page Operations\n\n`page create` creates the page directory, writes `index.md` by default or `inherit.md` with `--inherit`, and adds the page slug to `pages.\u003cbook\u003e.\u003csection\u003e.items`.\n\nUse `page create` only when the page does not already exist in that version.\n\nIf the page already exists as an inherited page marker:\n\n- the directory already exists\n- the nav entry already exists\n- the page folder contains an empty `inherit.md`\n\nThen use `page materialize` instead of `page create`.\n\n`page materialize` replaces `inherit.md` with a real `index.md`, using the currently resolved inherited page content as the starting point.\n\nOptional input:\n\n- `--title \u003ctitle\u003e`: replace the inherited page title while materializing the real content\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page materialize --version 0.8 --book website-dev-guide --section docs-platform --page website-and-docs-architecture-overview\n```\n\nManual fallback if you need to control the copy step yourself:\n\n1. remove the inherited marker\n1. add `index.md`\n1. copy the inherited page body as the starting point\n1. edit that authored copy for the version-specific behavior\n\nThis remains outside the scope of `page create`, because the page identity and nav structure already exist.\n\n`page inherit` does the reverse: it replaces a real `index.md` in the selected version with `inherit.md` so the page resolves from an earlier authored version again.\n\nImportant details:\n\n- it is destructive because it removes that version's authored page content\n- apply mode requires `--yes` in non-interactive shells\n- it refuses when no earlier version resolves the same path to real `index.md` content\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply --yes page inherit --version 0.8 --book website-dev-guide --section docs-platform --page website-and-docs-architecture-overview\n```\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create --version 1.1 --book developer --section architecture --page overview --title \"Architecture Overview\"\n```\n\n`page delete` removes the page directory and the matching page slug from nav data.\n\n`page rename` renames the page directory, updates `pages.\u003cbook\u003e.\u003csection\u003e.items`, and propagates inherited-only descendants when allowed.\n\nWhen a later version has independently authored the page, include it with `--also-version` to rename both versions in one atomic operation. Repeat the option for each independently authored version. The tool continues to move inherited-only versions automatically.\n\nA later version may already use the destination slug when it no longer contains the old slug. The tool refuses a version that contains both slugs, because that is an ambiguous page collision.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename --version 1.1 --also-version 1.3 --book end-user --section getting-started --from install --to setup --title \"Setup Sambee\"\n```\n\n`page move` moves a page to another section in the same book. It updates both page lists, materializes the selected version's destination page, and removes the source directory. `--to-page` optionally changes the slug; otherwise the source slug is retained. `--position` controls the destination order in the selected version.\n\nInherited-only descendants move automatically. The operation refuses if the destination exists, a later source page has real content, or a later version lacks the destination section. Links and managed redirects remain explicit content or deployment changes.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page move --version 0.9 --book admin-guide --from-section configuration --to-section reference --page configuration-key-reference --to-page configuration-file-reference --position start\n```\n\n## Notes\n\n- the tool does not edit `website/.generated/` directly\n- the tool does not run `materialize-inherited-docs.py` for you\n- the tool does not edit page body content or offer free-form front matter editing\n", "1.0": "+++\ntitle = \"Docs Editor Operation Reference\"\n+++\n\nUse this page when you already know you need the docs editor and want the detailed reference behavior.\n\n## Position Selectors\n\nOperations that insert books, sections, or pages use the same position syntax:\n\n- `\u003cindex\u003e`: insert at a zero-based numeric index\n- `before:\u003cslug\u003e`: insert immediately before the existing item\n- `after:\u003cslug\u003e`: insert immediately after the existing item\n- `start`: insert at the beginning\n- `end`: insert at the end\n\nIf the requested selector does not resolve cleanly in the target nav list, the operation refuses instead of guessing.\n\n## Global Options\n\nThe CLI supports these global options:\n\n- `--apply`: write changes to disk instead of previewing them\n- `--yes`: skip confirmation for destructive apply operations\n- `--json`: emit machine-readable preview or result output\n- `--quiet`: reduce non-error output\n- `--verbose`: reserved for future detailed output\n\n## Forward-Impact Analysis\n\nChanges in an older version can affect newer versions that still resolve through the same path. The tool analyzes that forward impact before destructive rename and delete operations.\n\nAffected newer versions fall into these categories:\n\n- inherited-only descendants: newer versions that contain only marker files for the affected path\n- structural descendants: newer versions that keep the path only as structure, without landing-page content\n- modified descendants: newer versions that contain real `_index.md` or `index.md` content at the affected path\n\nDefault behavior:\n\n- inherited-only descendants are updated automatically in apply mode\n- structural descendants are preserved where the operation allows it\n- modified descendants block destructive rename and delete operations\n\n## Content Rules the Tool Preserves\n\nThe docs editor preserves these invariants:\n\n- docs identity remains path-derived\n- `doc_id`, `product_version`, and `aliases` are not introduced\n- page folders contain exactly one of `index.md` or `inherit.md`\n- version and book folders contain exactly one of `_index.md` or `_inherit.md`\n- section folders contain zero or one of `_index.md` or `_inherit.md`\n- `inherit.md` and `_inherit.md` remain empty marker files\n- version order in `website/data/docs-versions.toml` stays canonical\n- nav data remains ordering-only metadata\n\n## Real Content Stubs\n\nWhen the tool creates real content, it writes a minimal front matter stub.\n\nDefaults:\n\n- page `index.md`: `title` defaults to a humanized page slug unless `--title` is provided\n- section `_index.md`: `title` defaults to the section title from nav data unless `--title` is provided\n- book `_index.md`: `title` defaults to a humanized book slug unless `--title` is provided\n- version `_index.md`: `title` defaults to the version label unless `--title` is provided\n\n## Inherited Markers\n\nWhen the tool creates inherited content, it writes:\n\n- empty `inherit.md` files for pages\n- empty `_inherit.md` files for version, book, and section landing pages\n\nNo front matter or body content is written into marker files.\n\n## Output Formats\n\nHuman-readable preview output shows the operation, the target path or version, the planned file changes, and the metadata changes that will be made on apply.\n\nJSON preview output includes:\n\n- `result`\n- `destructive`\n- `apply`\n- `metadata`\n- `changes`\n\nFor propagated destructive operations, `metadata` includes `propagated_versions` when later inherited-only versions will follow the change.\n\n## Standalone Report Generator\n\nUse [Docs Editor Tool](../docs-editor-tool/) for the high-level explanation of when to use the report and what it shows.\n\nThis reference section keeps only the CLI-specific behavior.\n\nThe report generator command is `website/scripts/docs-report.py`.\n\nBehavior:\n\n1. reads version metadata, nav files, and docs content directly from the repository\n2. writes `website-meta/docs-reports/docs-structure-report.html` by default\n3. embeds the report data, CSS, and JavaScript into one standalone HTML file\n\nExample:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py\n```\n\nCheck mode compares the current repository state against the committed HTML report and exits non-zero when the report needs regeneration:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py --check\n```\n\n## Operation Reference\n\n### Version Operations\n\n`version create` adds a new docs version, creates the matching content tree, initializes the new version to inherit from the previous version, and creates a matching nav file.\n\nRequired input:\n\n- new version slug\n- one insertion selector: `--after \u003cexisting-version\u003e` or `--latest`\n\nOptional input:\n\n- `--label \u003clabel\u003e`\n- `--status \u003cstatus\u003e`: optional UI label appended in parentheses after the version label, for example `preview` or `current`\n- `--visible true|false`\n- `--searchable true|false`\n- `--set-current`\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 1.2 --after 1.1 --label \"1.2\"\n```\n\nBehavior:\n\n1. inserts the new version into `website/data/docs-versions.toml`\n2. creates `website/content/docs/\u003cnew-version\u003e/`\n3. creates `website/data/docs-nav/\u003cnew-version\u003e.toml` from the previous version's nav data\n4. mirrors the previous version's docs tree shape\n5. creates inherited markers instead of copying authored content\n\nBootstrap behavior:\n\n- if `docs-versions.toml` has no declared versions, `--latest` bootstraps the first version instead of inheriting from a base version\n- in that case, the tool creates an authored version root with `_index.md`, creates an empty nav file, and sets the new version as `current`\n- this bootstrap path only works for a truly empty docs workspace; if version directories or version nav files still exist on disk, reconcile or remove them first\n\nImportant details:\n\n- the new version slug must not collide with an existing version\n- the reference version must exist\n- `status` is display metadata only; it does not decide which version is current\n- the actual current docs version is controlled by the top-level `current = \"\u003cslug\u003e\"` entry in `website/data/docs-versions.toml`\n- the current docs version changes only when `--set-current` is passed\n- `searchable` defaults to `false` unless explicitly set otherwise\n\n`version delete` removes a version entry, its nav file, and its content directory.\n\nRequired input:\n\n- version slug\n\nOptional input:\n\n- `--new-current \u003cversion\u003e` when deleting the current version\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version delete 1.1\n```\n\nBehavior:\n\n1. removes the version from `website/data/docs-versions.toml`\n2. removes `website/data/docs-nav/\u003cversion\u003e.toml`\n3. removes `website/content/docs/\u003cversion\u003e/`\n4. revalidates inheritance resolution across remaining versions\n\nRefusal cases:\n\n- the version does not exist\n- the version is current and `--new-current` was not supplied\n- `--new-current` points to the deleted version\n- `--new-current` does not exist after deletion\n- `--new-current` was supplied while deleting a non-current version\n\n### Book Operations\n\n`book create` creates a book folder, writes `_index.md` by default or `_inherit.md` with `--inherit`, and inserts the book into the version nav file.\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create --version 1.1 --book tutorials --title \"Tutorials\" --position end\n```\n\n`book delete` removes the book folder, the book entry in nav data, and the matching `sections.\u003cbook\u003e` and `pages.\u003cbook\u003e` data.\n\n`book rename` renames the book directory, updates `books` ordering plus the associated `sections` and `pages` tables, and propagates inherited-only descendants when allowed.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book rename --version 1.1 --from end-user --to user-guide --title \"User Guide\"\n```\n\n`book materialize` replaces an inherited book `_inherit.md` marker with a real `_index.md` using the currently resolved landing-page content. Use `--title` to replace the title while materializing.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book materialize --version 0.9 --book admin-guide\n```\n\n### Section Operations\n\n`section create` creates a section directory, adds a section entry in nav data, and initializes an empty `pages.\u003cbook\u003e.\u003csection\u003e.items` array.\n\nBy default it creates `_index.md`. With `--inherit`, it creates `_inherit.md`. With `--structural-only`, it creates no landing file. Optional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create --version 1.1 --book admin --section authentication --title \"Authentication\" --position end\n```\n\n`section delete` removes the section directory, its nav entry, and the matching `pages.\u003cbook\u003e.\u003csection\u003e` table.\n\n`section rename` renames the section directory, updates `sections.\u003cbook\u003e.items`, moves the matching `pages.\u003cbook\u003e.\u003csection\u003e` table to the new key, and preserves structural-only descendants as structural-only when no landing file exists at the renamed path.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section rename --version 1.1 --book admin --from configuration --to authentication --title \"Authentication\"\n```\n\n### Page Operations\n\n`page create` creates the page directory, writes `index.md` by default or `inherit.md` with `--inherit`, and adds the page slug to `pages.\u003cbook\u003e.\u003csection\u003e.items`.\n\nUse `page create` only when the page does not already exist in that version.\n\nIf the page already exists as an inherited page marker:\n\n- the directory already exists\n- the nav entry already exists\n- the page folder contains an empty `inherit.md`\n\nThen use `page materialize` instead of `page create`.\n\n`page materialize` replaces `inherit.md` with a real `index.md`, using the currently resolved inherited page content as the starting point.\n\nOptional input:\n\n- `--title \u003ctitle\u003e`: replace the inherited page title while materializing the real content\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page materialize --version 0.8 --book website-dev-guide --section docs-platform --page website-and-docs-architecture-overview\n```\n\nManual fallback if you need to control the copy step yourself:\n\n1. remove the inherited marker\n1. add `index.md`\n1. copy the inherited page body as the starting point\n1. edit that authored copy for the version-specific behavior\n\nThis remains outside the scope of `page create`, because the page identity and nav structure already exist.\n\n`page inherit` does the reverse: it replaces a real `index.md` in the selected version with `inherit.md` so the page resolves from an earlier authored version again.\n\nImportant details:\n\n- it is destructive because it removes that version's authored page content\n- apply mode requires `--yes` in non-interactive shells\n- it refuses when no earlier version resolves the same path to real `index.md` content\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply --yes page inherit --version 0.8 --book website-dev-guide --section docs-platform --page website-and-docs-architecture-overview\n```\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create --version 1.1 --book developer --section architecture --page overview --title \"Architecture Overview\"\n```\n\n`page delete` removes the page directory and the matching page slug from nav data.\n\n`page rename` renames the page directory, updates `pages.\u003cbook\u003e.\u003csection\u003e.items`, and propagates inherited-only descendants when allowed.\n\nWhen a later version has independently authored the page, include it with `--also-version` to rename both versions in one atomic operation. Repeat the option for each independently authored version. The tool continues to move inherited-only versions automatically.\n\nA later version may already use the destination slug when it no longer contains the old slug. The tool refuses a version that contains both slugs, because that is an ambiguous page collision.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename --version 1.1 --also-version 1.3 --book end-user --section getting-started --from install --to setup --title \"Setup Sambee\"\n```\n\n`page move` moves a page to another section in the same book. It updates both page lists, materializes the selected version's destination page, and removes the source directory. `--to-page` optionally changes the slug; otherwise the source slug is retained. `--position` controls the destination order in the selected version.\n\nInherited-only descendants move automatically. The operation refuses if the destination exists, a later source page has real content, or a later version lacks the destination section. Links and managed redirects remain explicit content or deployment changes.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page move --version 0.9 --book admin-guide --from-section configuration --to-section reference --page configuration-key-reference --to-page configuration-file-reference --position start\n```\n\n## Notes\n\n- the tool does not edit `website/.generated/` directly\n- the tool does not run `materialize-inherited-docs.py` for you\n- the tool does not edit page body content or offer free-form front matter editing\n", "2.0": "+++\ntitle = \"Docs Editor Operation Reference\"\n+++\n\nUse this page when you already know you need the docs editor and want the detailed reference behavior.\n\n## Position Selectors\n\nOperations that insert books, sections, or pages use the same position syntax:\n\n- `\u003cindex\u003e`: insert at a zero-based numeric index\n- `before:\u003cslug\u003e`: insert immediately before the existing item\n- `after:\u003cslug\u003e`: insert immediately after the existing item\n- `start`: insert at the beginning\n- `end`: insert at the end\n\nIf the requested selector does not resolve cleanly in the target nav list, the operation refuses instead of guessing.\n\n## Global Options\n\nThe CLI supports these global options:\n\n- `--apply`: write changes to disk instead of previewing them\n- `--yes`: skip confirmation for destructive apply operations\n- `--json`: emit machine-readable preview or result output\n- `--quiet`: reduce non-error output\n- `--verbose`: reserved for future detailed output\n\n## Forward-Impact Analysis\n\nChanges in an older version can affect newer versions that still resolve through the same path. The tool analyzes that forward impact before destructive rename and delete operations.\n\nAffected newer versions fall into these categories:\n\n- inherited-only descendants: newer versions that contain only marker files for the affected path\n- structural descendants: newer versions that keep the path only as structure, without landing-page content\n- modified descendants: newer versions that contain real `_index.md` or `index.md` content at the affected path\n\nDefault behavior:\n\n- inherited-only descendants are updated automatically in apply mode\n- structural descendants are preserved where the operation allows it\n- modified descendants block destructive rename and delete operations\n\n## Content Rules the Tool Preserves\n\nThe docs editor preserves these invariants:\n\n- docs identity remains path-derived\n- `doc_id`, `product_version`, and `aliases` are not introduced\n- page folders contain exactly one of `index.md` or `inherit.md`\n- version and book folders contain exactly one of `_index.md` or `_inherit.md`\n- section folders contain zero or one of `_index.md` or `_inherit.md`\n- `inherit.md` and `_inherit.md` remain empty marker files\n- version order in `website/data/docs-versions.toml` stays canonical\n- nav data remains ordering-only metadata\n\n## Real Content Stubs\n\nWhen the tool creates real content, it writes a minimal front matter stub.\n\nDefaults:\n\n- page `index.md`: `title` defaults to a humanized page slug unless `--title` is provided\n- section `_index.md`: `title` defaults to the section title from nav data unless `--title` is provided\n- book `_index.md`: `title` defaults to a humanized book slug unless `--title` is provided\n- version `_index.md`: `title` defaults to the version label unless `--title` is provided\n\n## Inherited Markers\n\nWhen the tool creates inherited content, it writes:\n\n- empty `inherit.md` files for pages\n- empty `_inherit.md` files for version, book, and section landing pages\n\nNo front matter or body content is written into marker files.\n\n## Output Formats\n\nHuman-readable preview output shows the operation, the target path or version, the planned file changes, and the metadata changes that will be made on apply.\n\nJSON preview output includes:\n\n- `result`\n- `destructive`\n- `apply`\n- `metadata`\n- `changes`\n\nFor propagated destructive operations, `metadata` includes `propagated_versions` when later inherited-only versions will follow the change.\n\n## Standalone Report Generator\n\nUse [Docs Editor Tool](../docs-editor-tool/) for the high-level explanation of when to use the report and what it shows.\n\nThis reference section keeps only the CLI-specific behavior.\n\nThe report generator command is `website/scripts/docs-report.py`.\n\nBehavior:\n\n1. reads version metadata, nav files, and docs content directly from the repository\n2. writes `website-meta/docs-reports/docs-structure-report.html` by default\n3. embeds the report data, CSS, and JavaScript into one standalone HTML file\n\nExample:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py\n```\n\nCheck mode compares the current repository state against the committed HTML report and exits non-zero when the report needs regeneration:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py --check\n```\n\n## Operation Reference\n\n### Version Operations\n\n`version create` adds a new docs version, creates the matching content tree, initializes the new version to inherit from the previous version, and creates a matching nav file.\n\nRequired input:\n\n- new version slug\n- one insertion selector: `--after \u003cexisting-version\u003e` or `--latest`\n\nOptional input:\n\n- `--label \u003clabel\u003e`\n- `--status \u003cstatus\u003e`: optional UI label appended in parentheses after the version label, for example `preview` or `current`\n- `--visible true|false`\n- `--searchable true|false`\n- `--set-current`\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 1.2 --after 1.1 --label \"1.2\"\n```\n\nBehavior:\n\n1. inserts the new version into `website/data/docs-versions.toml`\n2. creates `website/content/docs/\u003cnew-version\u003e/`\n3. creates `website/data/docs-nav/\u003cnew-version\u003e.toml` from the previous version's nav data\n4. mirrors the previous version's docs tree shape\n5. creates inherited markers instead of copying authored content\n\nBootstrap behavior:\n\n- if `docs-versions.toml` has no declared versions, `--latest` bootstraps the first version instead of inheriting from a base version\n- in that case, the tool creates an authored version root with `_index.md`, creates an empty nav file, and sets the new version as `current`\n- this bootstrap path only works for a truly empty docs workspace; if version directories or version nav files still exist on disk, reconcile or remove them first\n\nImportant details:\n\n- the new version slug must not collide with an existing version\n- the reference version must exist\n- `status` is display metadata only; it does not decide which version is current\n- the actual current docs version is controlled by the top-level `current = \"\u003cslug\u003e\"` entry in `website/data/docs-versions.toml`\n- the current docs version changes only when `--set-current` is passed\n- `searchable` defaults to `false` unless explicitly set otherwise\n\n`version delete` removes a version entry, its nav file, and its content directory.\n\nRequired input:\n\n- version slug\n\nOptional input:\n\n- `--new-current \u003cversion\u003e` when deleting the current version\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version delete 1.1\n```\n\nBehavior:\n\n1. removes the version from `website/data/docs-versions.toml`\n2. removes `website/data/docs-nav/\u003cversion\u003e.toml`\n3. removes `website/content/docs/\u003cversion\u003e/`\n4. revalidates inheritance resolution across remaining versions\n\nRefusal cases:\n\n- the version does not exist\n- the version is current and `--new-current` was not supplied\n- `--new-current` points to the deleted version\n- `--new-current` does not exist after deletion\n- `--new-current` was supplied while deleting a non-current version\n\n### Book Operations\n\n`book create` creates a book folder, writes `_index.md` by default or `_inherit.md` with `--inherit`, and inserts the book into the version nav file.\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create --version 1.1 --book tutorials --title \"Tutorials\" --position end\n```\n\n`book delete` removes the book folder, the book entry in nav data, and the matching `sections.\u003cbook\u003e` and `pages.\u003cbook\u003e` data.\n\n`book rename` renames the book directory, updates `books` ordering plus the associated `sections` and `pages` tables, and propagates inherited-only descendants when allowed.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book rename --version 1.1 --from end-user --to user-guide --title \"User Guide\"\n```\n\n`book materialize` replaces an inherited book `_inherit.md` marker with a real `_index.md` using the currently resolved landing-page content. Use `--title` to replace the title while materializing.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book materialize --version 0.9 --book admin-guide\n```\n\n### Section Operations\n\n`section create` creates a section directory, adds a section entry in nav data, and initializes an empty `pages.\u003cbook\u003e.\u003csection\u003e.items` array.\n\nBy default it creates `_index.md`. With `--inherit`, it creates `_inherit.md`. With `--structural-only`, it creates no landing file. Optional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create --version 1.1 --book admin --section authentication --title \"Authentication\" --position end\n```\n\n`section delete` removes the section directory, its nav entry, and the matching `pages.\u003cbook\u003e.\u003csection\u003e` table.\n\n`section rename` renames the section directory, updates `sections.\u003cbook\u003e.items`, moves the matching `pages.\u003cbook\u003e.\u003csection\u003e` table to the new key, and preserves structural-only descendants as structural-only when no landing file exists at the renamed path.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section rename --version 1.1 --book admin --from configuration --to authentication --title \"Authentication\"\n```\n\n### Page Operations\n\n`page create` creates the page directory, writes `index.md` by default or `inherit.md` with `--inherit`, and adds the page slug to `pages.\u003cbook\u003e.\u003csection\u003e.items`.\n\nUse `page create` only when the page does not already exist in that version.\n\nIf the page already exists as an inherited page marker:\n\n- the directory already exists\n- the nav entry already exists\n- the page folder contains an empty `inherit.md`\n\nThen use `page materialize` instead of `page create`.\n\n`page materialize` replaces `inherit.md` with a real `index.md`, using the currently resolved inherited page content as the starting point.\n\nOptional input:\n\n- `--title \u003ctitle\u003e`: replace the inherited page title while materializing the real content\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page materialize --version 0.8 --book website-dev-guide --section docs-platform --page website-and-docs-architecture-overview\n```\n\nManual fallback if you need to control the copy step yourself:\n\n1. remove the inherited marker\n1. add `index.md`\n1. copy the inherited page body as the starting point\n1. edit that authored copy for the version-specific behavior\n\nThis remains outside the scope of `page create`, because the page identity and nav structure already exist.\n\n`page inherit` does the reverse: it replaces a real `index.md` in the selected version with `inherit.md` so the page resolves from an earlier authored version again.\n\nImportant details:\n\n- it is destructive because it removes that version's authored page content\n- apply mode requires `--yes` in non-interactive shells\n- it refuses when no earlier version resolves the same path to real `index.md` content\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply --yes page inherit --version 0.8 --book website-dev-guide --section docs-platform --page website-and-docs-architecture-overview\n```\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create --version 1.1 --book developer --section architecture --page overview --title \"Architecture Overview\"\n```\n\n`page delete` removes the page directory and the matching page slug from nav data.\n\n`page rename` renames the page directory, updates `pages.\u003cbook\u003e.\u003csection\u003e.items`, and propagates inherited-only descendants when allowed.\n\nWhen a later version has independently authored the page, include it with `--also-version` to rename both versions in one atomic operation. Repeat the option for each independently authored version. The tool continues to move inherited-only versions automatically.\n\nA later version may already use the destination slug when it no longer contains the old slug. The tool refuses a version that contains both slugs, because that is an ambiguous page collision.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename --version 1.1 --also-version 1.3 --book end-user --section getting-started --from install --to setup --title \"Setup Sambee\"\n```\n\n`page move` moves a page to another section in the same book. It updates both page lists, materializes the selected version's destination page, and removes the source directory. `--to-page` optionally changes the slug; otherwise the source slug is retained. `--position` controls the destination order in the selected version.\n\nInherited-only descendants move automatically. The operation refuses if the destination exists, a later source page has real content, or a later version lacks the destination section. Links and managed redirects remain explicit content or deployment changes.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page move --version 0.9 --book admin-guide --from-section configuration --to-section reference --page configuration-key-reference --to-page configuration-file-reference --position start\n```\n\n## Notes\n\n- the tool does not edit `website/.generated/` directly\n- the tool does not run `materialize-inherited-docs.py` for you\n- the tool does not edit page body content or offer free-form front matter editing\n"}, "page_contents": {"0.7": "`book create` creates a book folder, writes `_index.md` by default or `_inherit.md` with `--inherit`, and inserts the book into the version nav file. With `--structural-only`, it creates no landing file. `--structural-only` cannot be combined with `--inherit` or `--title`.\n`book rename` renames the book directory, updates `books` ordering plus the associated `sections` and `pages` tables, and propagates inherited-only descendants when allowed. It preserves a structural-only book as structural-only; `--title` is not valid when renaming such a book.\n+++\ntitle = \"Docs Editor Operation Reference\"\n+++\n\nUse this page when you already know you need the docs editor and want the detailed reference behavior.\n\n## Position Selectors\n\nOperations that insert books, sections, or pages use the same position syntax:\n\n- `\u003cindex\u003e`: insert at a zero-based numeric index\n- `before:\u003cslug\u003e`: insert immediately before the existing item\n- `after:\u003cslug\u003e`: insert immediately after the existing item\n- `start`: insert at the beginning\n- `end`: insert at the end\n\nIf the requested selector does not resolve cleanly in the target nav list, the operation refuses instead of guessing.\n\n## Global Options\n\nThe CLI supports these global options:\n\n- `--apply`: write changes to disk instead of previewing them\n- `--yes`: skip confirmation for destructive apply operations\n- `--json`: emit machine-readable preview or result output\n- `--quiet`: reduce non-error output\n- `--verbose`: reserved for future detailed output\n\n## Forward-Impact Analysis\n\nChanges in an older version can affect newer versions that still resolve through the same path. The tool analyzes that forward impact before destructive rename and delete operations.\n\nAffected newer versions fall into these categories:\n\n- inherited-only descendants: newer versions that contain only marker files for the affected path\n- structural descendants: newer versions that keep the path only as structure, without landing-page content\n- modified descendants: newer versions that contain real `_index.md` or `index.md` content at the affected path\n\nDefault behavior:\n\n- inherited-only descendants are updated automatically in apply mode\n- structural descendants are preserved where the operation allows it\n- modified descendants block destructive rename and delete operations\n\n## Content Rules the Tool Preserves\n\nThe docs editor preserves these invariants:\n\n- docs identity remains path-derived\n- `doc_id`, `product_version`, and `aliases` are not introduced\n- page folders contain exactly one of `index.md` or `inherit.md`\n- version and book folders contain exactly one of `_index.md` or `_inherit.md`\n- section folders contain zero or one of `_index.md` or `_inherit.md`\n- `inherit.md` and `_inherit.md` remain empty marker files\n- version order in `website/data/docs-versions.toml` stays canonical\n- nav data remains ordering-only metadata\n\n## Real Content Stubs\n\nWhen the tool creates real content, it writes a minimal front matter stub.\n\nDefaults:\n\n- page `index.md`: `title` defaults to a humanized page slug unless `--title` is provided\n- section `_index.md`: `title` defaults to the section title from nav data unless `--title` is provided\n- book `_index.md`: `title` defaults to a humanized book slug unless `--title` is provided\n- version `_index.md`: `title` defaults to the version label unless `--title` is provided\n\n## Inherited Markers\n\nWhen the tool creates inherited content, it writes:\n\n- empty `inherit.md` files for pages\n- empty `_inherit.md` files for version, book, and section landing pages\n\nNo front matter or body content is written into marker files.\n\n## Output Formats\n\nHuman-readable preview output shows the operation, the target path or version, the planned file changes, and the metadata changes that will be made on apply.\n\nJSON preview output includes:\n\n- `result`\n- `destructive`\n- `apply`\n- `metadata`\n- `changes`\n\nFor propagated destructive operations, `metadata` includes `propagated_versions` when later inherited-only versions will follow the change.\n\n## Operation Reference\n\n### Version Operations\n\n`version create` adds a new docs version, creates the matching content tree, initializes the new version to inherit from the previous version, and creates a matching nav file.\n\nRequired input:\n\n- new version slug\n- one insertion selector: `--after \u003cexisting-version\u003e` or `--latest`\n\nOptional input:\n\n- `--label \u003clabel\u003e`\n- `--status \u003cstatus\u003e`: optional UI label appended in parentheses after the version label, for example `preview` or `current`\n- `--visible true|false`\n- `--searchable true|false`\n- `--set-current`\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 1.2 --after 1.1 --label \"1.2\"\n```\n\nBehavior:\n\n1. inserts the new version into `website/data/docs-versions.toml`\n2. creates `website/content/docs/\u003cnew-version\u003e/`\n3. creates `website/data/docs-nav/\u003cnew-version\u003e.toml` from the previous version's nav data\n4. mirrors the previous version's docs tree shape\n5. creates inherited markers instead of copying authored content\n\nBootstrap behavior:\n\n- if `docs-versions.toml` has no declared versions, `--latest` bootstraps the first version instead of inheriting from a base version\n- in that case, the tool creates an authored version root with `_index.md`, creates an empty nav file, and sets the new version as `current`\n- this bootstrap path only works for a truly empty docs workspace; if version directories or version nav files still exist on disk, reconcile or remove them first\n\nImportant details:\n\n- the new version slug must not collide with an existing version\n- the reference version must exist\n- `status` is display metadata only; it does not decide which version is current\n- the actual current docs version is controlled by the top-level `current = \"\u003cslug\u003e\"` entry in `website/data/docs-versions.toml`\n- the current docs version changes only when `--set-current` is passed\n- `searchable` defaults to `false` unless explicitly set otherwise\n\n`version delete` removes a version entry, its nav file, and its content directory.\n\nRequired input:\n\n- version slug\n\nOptional input:\n\n- `--new-current \u003cversion\u003e` when deleting the current version\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version delete 1.1\n```\n\nBehavior:\n\n1. removes the version from `website/data/docs-versions.toml`\n2. removes `website/data/docs-nav/\u003cversion\u003e.toml`\n3. removes `website/content/docs/\u003cversion\u003e/`\n4. revalidates inheritance resolution across remaining versions\n\nRefusal cases:\n\n- the version does not exist\n- the version is current and `--new-current` was not supplied\n- `--new-current` points to the deleted version\n- `--new-current` does not exist after deletion\n- `--new-current` was supplied while deleting a non-current version\n\n### Book Operations\n\n`book create` creates a book folder, writes `_index.md` by default or `_inherit.md` with `--inherit`, and inserts the book into the version nav file.\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create --version 1.1 --book tutorials --title \"Tutorials\" --position end\n```\n\n`book delete` removes the book folder, the book entry in nav data, and the matching `sections.\u003cbook\u003e` and `pages.\u003cbook\u003e` data.\n\n`book rename` renames the book directory, updates `books` ordering plus the associated `sections` and `pages` tables, and propagates inherited-only descendants when allowed.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book rename --version 1.1 --from end-user --to user-guide --title \"User Guide\"\n```\n\n### Section Operations\n\n`section create` creates a section directory, adds a section entry in nav data, and initializes an empty `pages.\u003cbook\u003e.\u003csection\u003e.items` array.\n\nBy default it creates `_index.md`. With `--inherit`, it creates `_inherit.md`. With `--structural-only`, it creates no landing file. Optional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create --version 1.1 --book admin --section authentication --title \"Authentication\" --position end\n```\n\n`section delete` removes the section directory, its nav entry, and the matching `pages.\u003cbook\u003e.\u003csection\u003e` table.\n\n`section rename` renames the section directory, updates `sections.\u003cbook\u003e.items`, moves the matching `pages.\u003cbook\u003e.\u003csection\u003e` table to the new key, and preserves structural-only descendants as structural-only when no landing file exists at the renamed path.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section rename --version 1.1 --book admin --from configuration --to authentication --title \"Authentication\"\n```\n\n### Page Operations\n\n`page create` creates the page directory, writes `index.md` by default or `inherit.md` with `--inherit`, and adds the page slug to `pages.\u003cbook\u003e.\u003csection\u003e.items`.\n\nUse `page create` only when the page does not already exist in that version.\n\nIf the page already exists as an inherited page marker:\n\n- the directory already exists\n- the nav entry already exists\n- the page folder contains an empty `inherit.md`\n\nThen the correct workflow is to materialize real content manually:\n\n1. remove the inherited marker\n1. add `index.md`\n1. copy the inherited page body as the starting point\n1. edit that authored copy for the version-specific behavior\n\nThis is intentionally outside the scope of `page create`, because the page identity and nav structure already exist.\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create --version 1.1 --book developer --section architecture --page overview --title \"Architecture Overview\"\n```\n\n`page delete` removes the page directory and the matching page slug from nav data.\n\n`page rename` renames the page directory, updates `pages.\u003cbook\u003e.\u003csection\u003e.items`, and propagates inherited-only descendants when allowed.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename --version 1.1 --book end-user --section getting-started --from install --to setup --title \"Setup Sambee\"\n```\n\n## Notes\n\n- the tool does not edit `website/.generated/` directly\n- the tool does not run `materialize-inherited-docs.py` for you\n- the tool does not edit page body content or offer free-form front matter editing\n", "0.8": "+++\ntitle = \"Docs Editor Operation Reference\"\n+++\n\nUse this page when you already know you need the docs editor and want the detailed reference behavior.\n\n## Position Selectors\n\nOperations that insert books, sections, or pages use the same position syntax:\n\n- `\u003cindex\u003e`: insert at a zero-based numeric index\n- `before:\u003cslug\u003e`: insert immediately before the existing item\n- `after:\u003cslug\u003e`: insert immediately after the existing item\n- `start`: insert at the beginning\n- `end`: insert at the end\n\nIf the requested selector does not resolve cleanly in the target nav list, the operation refuses instead of guessing.\n\n## Global Options\n\nThe CLI supports these global options:\n\n- `--apply`: write changes to disk instead of previewing them\n- `--yes`: skip confirmation for destructive apply operations\n- `--json`: emit machine-readable preview or result output\n- `--quiet`: reduce non-error output\n- `--verbose`: reserved for future detailed output\n\n## Forward-Impact Analysis\n\nChanges in an older version can affect newer versions that still resolve through the same path. The tool analyzes that forward impact before destructive rename and delete operations.\n\nAffected newer versions fall into these categories:\n\n- inherited-only descendants: newer versions that contain only marker files for the affected path\n- structural descendants: newer versions that keep the path only as structure, without landing-page content\n- modified descendants: newer versions that contain real `_index.md` or `index.md` content at the affected path\n\nDefault behavior:\n\n- inherited-only descendants are updated automatically in apply mode\n- structural descendants are preserved where the operation allows it\n- modified descendants block destructive rename and delete operations\n\n## Content Rules the Tool Preserves\n\nThe docs editor preserves these invariants:\n\n- docs identity remains path-derived\n- `doc_id`, `product_version`, and `aliases` are not introduced\n- page folders contain exactly one of `index.md` or `inherit.md`\n- version and book folders contain exactly one of `_index.md` or `_inherit.md`\n- section folders contain zero or one of `_index.md` or `_inherit.md`\n- `inherit.md` and `_inherit.md` remain empty marker files\n- version order in `website/data/docs-versions.toml` stays canonical\n- nav data remains ordering-only metadata\n\n## Real Content Stubs\n\nWhen the tool creates real content, it writes a minimal front matter stub.\n\nDefaults:\n\n- page `index.md`: `title` defaults to a humanized page slug unless `--title` is provided\n- section `_index.md`: `title` defaults to the section title from nav data unless `--title` is provided\n- book `_index.md`: `title` defaults to a humanized book slug unless `--title` is provided\n- version `_index.md`: `title` defaults to the version label unless `--title` is provided\n\n## Inherited Markers\n\nWhen the tool creates inherited content, it writes:\n\n- empty `inherit.md` files for pages\n- empty `_inherit.md` files for version, book, and section landing pages\n\nNo front matter or body content is written into marker files.\n\n## Output Formats\n\nHuman-readable preview output shows the operation, the target path or version, the planned file changes, and the metadata changes that will be made on apply.\n\nJSON preview output includes:\n\n- `result`\n- `destructive`\n- `apply`\n- `metadata`\n- `changes`\n\nFor propagated destructive operations, `metadata` includes `propagated_versions` when later inherited-only versions will follow the change.\n\n## Standalone Report Generator\n\nUse [Docs Editor Tool](../docs-editor-tool/) for the high-level explanation of when to use the report and what it shows.\n\nThis reference section keeps only the CLI-specific behavior.\n\nThe report generator command is `website/scripts/docs-report.py`.\n\nBehavior:\n\n1. reads version metadata, nav files, and docs content directly from the repository\n2. writes `website-meta/docs-reports/docs-structure-report.html` by default\n3. embeds the report data, CSS, and JavaScript into one standalone HTML file\n\nExample:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py\n```\n\nCheck mode compares the current repository state against the committed HTML report and exits non-zero when the report needs regeneration:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py --check\n```\n\n## Operation Reference\n\n### Version Operations\n\n`version create` adds a new docs version, creates the matching content tree, initializes the new version to inherit from the previous version, and creates a matching nav file.\n\nRequired input:\n\n- new version slug\n- one insertion selector: `--after \u003cexisting-version\u003e` or `--latest`\n\nOptional input:\n\n- `--label \u003clabel\u003e`\n- `--status \u003cstatus\u003e`: optional UI label appended in parentheses after the version label, for example `preview` or `current`\n- `--visible true|false`\n- `--searchable true|false`\n- `--set-current`\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 1.2 --after 1.1 --label \"1.2\"\n```\n\nBehavior:\n\n1. inserts the new version into `website/data/docs-versions.toml`\n2. creates `website/content/docs/\u003cnew-version\u003e/`\n3. creates `website/data/docs-nav/\u003cnew-version\u003e.toml` from the previous version's nav data\n4. mirrors the previous version's docs tree shape\n5. creates inherited markers instead of copying authored content\n\nBootstrap behavior:\n\n- if `docs-versions.toml` has no declared versions, `--latest` bootstraps the first version instead of inheriting from a base version\n- in that case, the tool creates an authored version root with `_index.md`, creates an empty nav file, and sets the new version as `current`\n- this bootstrap path only works for a truly empty docs workspace; if version directories or version nav files still exist on disk, reconcile or remove them first\n\nImportant details:\n\n- the new version slug must not collide with an existing version\n- the reference version must exist\n- `status` is display metadata only; it does not decide which version is current\n- the actual current docs version is controlled by the top-level `current = \"\u003cslug\u003e\"` entry in `website/data/docs-versions.toml`\n- the current docs version changes only when `--set-current` is passed\n- `searchable` defaults to `false` unless explicitly set otherwise\n\n`version delete` removes a version entry, its nav file, and its content directory.\n\nRequired input:\n\n- version slug\n\nOptional input:\n\n- `--new-current \u003cversion\u003e` when deleting the current version\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version delete 1.1\n```\n\nBehavior:\n\n1. removes the version from `website/data/docs-versions.toml`\n2. removes `website/data/docs-nav/\u003cversion\u003e.toml`\n3. removes `website/content/docs/\u003cversion\u003e/`\n4. revalidates inheritance resolution across remaining versions\n\nRefusal cases:\n\n- the version does not exist\n- the version is current and `--new-current` was not supplied\n- `--new-current` points to the deleted version\n- `--new-current` does not exist after deletion\n- `--new-current` was supplied while deleting a non-current version\n\n### Book Operations\n\n`book create` creates a book folder, writes `_index.md` by default or `_inherit.md` with `--inherit`, and inserts the book into the version nav file.\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create --version 1.1 --book tutorials --title \"Tutorials\" --position end\n```\n\n`book delete` removes the book folder, the book entry in nav data, and the matching `sections.\u003cbook\u003e` and `pages.\u003cbook\u003e` data.\n\n`book rename` renames the book directory, updates `books` ordering plus the associated `sections` and `pages` tables, and propagates inherited-only descendants when allowed.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book rename --version 1.1 --from end-user --to user-guide --title \"User Guide\"\n```\n\n### Section Operations\n\n`section create` creates a section directory, adds a section entry in nav data, and initializes an empty `pages.\u003cbook\u003e.\u003csection\u003e.items` array.\n\nBy default it creates `_index.md`. With `--inherit`, it creates `_inherit.md`. With `--structural-only`, it creates no landing file. Optional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create --version 1.1 --book admin --section authentication --title \"Authentication\" --position end\n```\n\n`section delete` removes the section directory, its nav entry, and the matching `pages.\u003cbook\u003e.\u003csection\u003e` table.\n\n`section rename` renames the section directory, updates `sections.\u003cbook\u003e.items`, moves the matching `pages.\u003cbook\u003e.\u003csection\u003e` table to the new key, and preserves structural-only descendants as structural-only when no landing file exists at the renamed path.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section rename --version 1.1 --book admin --from configuration --to authentication --title \"Authentication\"\n```\n\n### Page Operations\n\n`page create` creates the page directory, writes `index.md` by default or `inherit.md` with `--inherit`, and adds the page slug to `pages.\u003cbook\u003e.\u003csection\u003e.items`.\n\nUse `page create` only when the page does not already exist in that version.\n\nIf the page already exists as an inherited page marker:\n\n- the directory already exists\n- the nav entry already exists\n- the page folder contains an empty `inherit.md`\n\nThen use `page materialize` instead of `page create`.\n\n`page materialize` replaces `inherit.md` with a real `index.md`, using the currently resolved inherited page content as the starting point.\n\nOptional input:\n\n- `--title \u003ctitle\u003e`: replace the inherited page title while materializing the real content\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page materialize --version 0.8 --book website-dev-guide --section docs-platform --page website-and-docs-architecture-overview\n```\n\nManual fallback if you need to control the copy step yourself:\n\n1. remove the inherited marker\n1. add `index.md`\n1. copy the inherited page body as the starting point\n1. edit that authored copy for the version-specific behavior\n\nThis remains outside the scope of `page create`, because the page identity and nav structure already exist.\n\n`page inherit` does the reverse: it replaces a real `index.md` in the selected version with `inherit.md` so the page resolves from an earlier authored version again.\n\nImportant details:\n\n- it is destructive because it removes that version's authored page content\n- apply mode requires `--yes` in non-interactive shells\n- it refuses when no earlier version resolves the same path to real `index.md` content\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply --yes page inherit --version 0.8 --book website-dev-guide --section docs-platform --page website-and-docs-architecture-overview\n```\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create --version 1.1 --book developer --section architecture --page overview --title \"Architecture Overview\"\n```\n\n`page delete` removes the page directory and the matching page slug from nav data.\n\n`page rename` renames the page directory, updates `pages.\u003cbook\u003e.\u003csection\u003e.items`, and propagates inherited-only descendants when allowed.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename --version 1.1 --book end-user --section getting-started --from install --to setup --title \"Setup Sambee\"\n```\n\n## Notes\n\n- the tool does not edit `website/.generated/` directly\n- the tool does not run `materialize-inherited-docs.py` for you\n- the tool does not edit page body content or offer free-form front matter editing\n", "0.9": "+++\ntitle = \"Docs Editor Operation Reference\"\n+++\n\nUse this page when you already know you need the docs editor and want the detailed reference behavior.\n\n## Position Selectors\n\nOperations that insert books, sections, or pages use the same position syntax:\n\n- `\u003cindex\u003e`: insert at a zero-based numeric index\n- `before:\u003cslug\u003e`: insert immediately before the existing item\n- `after:\u003cslug\u003e`: insert immediately after the existing item\n- `start`: insert at the beginning\n- `end`: insert at the end\n\nIf the requested selector does not resolve cleanly in the target nav list, the operation refuses instead of guessing.\n\n## Global Options\n\nThe CLI supports these global options:\n\n- `--apply`: write changes to disk instead of previewing them\n- `--yes`: skip confirmation for destructive apply operations\n- `--json`: emit machine-readable preview or result output\n- `--quiet`: reduce non-error output\n- `--verbose`: reserved for future detailed output\n\n## Forward-Impact Analysis\n\nChanges in an older version can affect newer versions that still resolve through the same path. The tool analyzes that forward impact before destructive rename and delete operations.\n\nAffected newer versions fall into these categories:\n\n- inherited-only descendants: newer versions that contain only marker files for the affected path\n- structural descendants: newer versions that keep the path only as structure, without landing-page content\n- modified descendants: newer versions that contain real `_index.md` or `index.md` content at the affected path\n\nDefault behavior:\n\n- inherited-only descendants are updated automatically in apply mode\n- structural descendants are preserved where the operation allows it\n- modified descendants block destructive rename and delete operations\n\n## Content Rules the Tool Preserves\n\nThe docs editor preserves these invariants:\n\n- docs identity remains path-derived\n- `doc_id`, `product_version`, and `aliases` are not introduced\n- page folders contain exactly one of `index.md` or `inherit.md`\n- version and book folders contain exactly one of `_index.md` or `_inherit.md`\n- section folders contain zero or one of `_index.md` or `_inherit.md`\n- `inherit.md` and `_inherit.md` remain empty marker files\n- version order in `website/data/docs-versions.toml` stays canonical\n- nav data remains ordering-only metadata\n\n## Real Content Stubs\n\nWhen the tool creates real content, it writes a minimal front matter stub.\n\nDefaults:\n\n- page `index.md`: `title` defaults to a humanized page slug unless `--title` is provided\n- section `_index.md`: `title` defaults to the section title from nav data unless `--title` is provided\n- book `_index.md`: `title` defaults to a humanized book slug unless `--title` is provided\n- version `_index.md`: `title` defaults to the version label unless `--title` is provided\n\n## Inherited Markers\n\nWhen the tool creates inherited content, it writes:\n\n- empty `inherit.md` files for pages\n- empty `_inherit.md` files for version, book, and section landing pages\n\nNo front matter or body content is written into marker files.\n\n## Output Formats\n\nHuman-readable preview output shows the operation, the target path or version, the planned file changes, and the metadata changes that will be made on apply.\n\nJSON preview output includes:\n\n- `result`\n- `destructive`\n- `apply`\n- `metadata`\n- `changes`\n\nFor propagated destructive operations, `metadata` includes `propagated_versions` when later inherited-only versions will follow the change.\n\n## Standalone Report Generator\n\nUse [Docs Editor Tool](../docs-editor-tool/) for the high-level explanation of when to use the report and what it shows.\n\nThis reference section keeps only the CLI-specific behavior.\n\nThe report generator command is `website/scripts/docs-report.py`.\n\nBehavior:\n\n1. reads version metadata, nav files, and docs content directly from the repository\n2. writes `website-meta/docs-reports/docs-structure-report.html` by default\n3. embeds the report data, CSS, and JavaScript into one standalone HTML file\n\nExample:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py\n```\n\nCheck mode compares the current repository state against the committed HTML report and exits non-zero when the report needs regeneration:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py --check\n```\n\n## Operation Reference\n\n### Version Operations\n\n`version create` adds a new docs version, creates the matching content tree, initializes the new version to inherit from the previous version, and creates a matching nav file.\n\nRequired input:\n\n- new version slug\n- one insertion selector: `--after \u003cexisting-version\u003e` or `--latest`\n\nOptional input:\n\n- `--label \u003clabel\u003e`\n- `--status \u003cstatus\u003e`: optional UI label appended in parentheses after the version label, for example `preview` or `current`\n- `--visible true|false`\n- `--searchable true|false`\n- `--set-current`\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 1.2 --after 1.1 --label \"1.2\"\n```\n\nBehavior:\n\n1. inserts the new version into `website/data/docs-versions.toml`\n2. creates `website/content/docs/\u003cnew-version\u003e/`\n3. creates `website/data/docs-nav/\u003cnew-version\u003e.toml` from the previous version's nav data\n4. mirrors the previous version's docs tree shape\n5. creates inherited markers instead of copying authored content\n\nBootstrap behavior:\n\n- if `docs-versions.toml` has no declared versions, `--latest` bootstraps the first version instead of inheriting from a base version\n- in that case, the tool creates an authored version root with `_index.md`, creates an empty nav file, and sets the new version as `current`\n- this bootstrap path only works for a truly empty docs workspace; if version directories or version nav files still exist on disk, reconcile or remove them first\n\nImportant details:\n\n- the new version slug must not collide with an existing version\n- the reference version must exist\n- `status` is display metadata only; it does not decide which version is current\n- the actual current docs version is controlled by the top-level `current = \"\u003cslug\u003e\"` entry in `website/data/docs-versions.toml`\n- the current docs version changes only when `--set-current` is passed\n- `searchable` defaults to `false` unless explicitly set otherwise\n\n`version delete` removes a version entry, its nav file, and its content directory.\n\nRequired input:\n\n- version slug\n\nOptional input:\n\n- `--new-current \u003cversion\u003e` when deleting the current version\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version delete 1.1\n```\n\nBehavior:\n\n1. removes the version from `website/data/docs-versions.toml`\n2. removes `website/data/docs-nav/\u003cversion\u003e.toml`\n3. removes `website/content/docs/\u003cversion\u003e/`\n4. revalidates inheritance resolution across remaining versions\n\nRefusal cases:\n\n- the version does not exist\n- the version is current and `--new-current` was not supplied\n- `--new-current` points to the deleted version\n- `--new-current` does not exist after deletion\n- `--new-current` was supplied while deleting a non-current version\n\n### Book Operations\n\n`book create` creates a book folder, writes `_index.md` by default or `_inherit.md` with `--inherit`, and inserts the book into the version nav file.\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create --version 1.1 --book tutorials --title \"Tutorials\" --position end\n```\n\n`book delete` removes the book folder, the book entry in nav data, and the matching `sections.\u003cbook\u003e` and `pages.\u003cbook\u003e` data.\n\n`book rename` renames the book directory, updates `books` ordering plus the associated `sections` and `pages` tables, and propagates inherited-only descendants when allowed.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book rename --version 1.1 --from end-user --to user-guide --title \"User Guide\"\n```\n\n`book materialize` replaces an inherited book `_inherit.md` marker with a real `_index.md` using the currently resolved landing-page content. Use `--title` to replace the title while materializing.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book materialize --version 0.9 --book admin-guide\n```\n\n### Section Operations\n\n`section create` creates a section directory, adds a section entry in nav data, and initializes an empty `pages.\u003cbook\u003e.\u003csection\u003e.items` array.\n\nBy default it creates `_index.md`. With `--inherit`, it creates `_inherit.md`. With `--structural-only`, it creates no landing file. Optional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create --version 1.1 --book admin --section authentication --title \"Authentication\" --position end\n```\n\n`section delete` removes the section directory, its nav entry, and the matching `pages.\u003cbook\u003e.\u003csection\u003e` table.\n\n`section rename` renames the section directory, updates `sections.\u003cbook\u003e.items`, moves the matching `pages.\u003cbook\u003e.\u003csection\u003e` table to the new key, and preserves structural-only descendants as structural-only when no landing file exists at the renamed path.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section rename --version 1.1 --book admin --from configuration --to authentication --title \"Authentication\"\n```\n\n### Page Operations\n\n`page create` creates the page directory, writes `index.md` by default or `inherit.md` with `--inherit`, and adds the page slug to `pages.\u003cbook\u003e.\u003csection\u003e.items`.\n\nUse `page create` only when the page does not already exist in that version.\n\nIf the page already exists as an inherited page marker:\n\n- the directory already exists\n- the nav entry already exists\n- the page folder contains an empty `inherit.md`\n\nThen use `page materialize` instead of `page create`.\n\n`page materialize` replaces `inherit.md` with a real `index.md`, using the currently resolved inherited page content as the starting point.\n\nOptional input:\n\n- `--title \u003ctitle\u003e`: replace the inherited page title while materializing the real content\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page materialize --version 0.8 --book website-dev-guide --section docs-platform --page website-and-docs-architecture-overview\n```\n\nManual fallback if you need to control the copy step yourself:\n\n1. remove the inherited marker\n1. add `index.md`\n1. copy the inherited page body as the starting point\n1. edit that authored copy for the version-specific behavior\n\nThis remains outside the scope of `page create`, because the page identity and nav structure already exist.\n\n`page inherit` does the reverse: it replaces a real `index.md` in the selected version with `inherit.md` so the page resolves from an earlier authored version again.\n\nImportant details:\n\n- it is destructive because it removes that version's authored page content\n- apply mode requires `--yes` in non-interactive shells\n- it refuses when no earlier version resolves the same path to real `index.md` content\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply --yes page inherit --version 0.8 --book website-dev-guide --section docs-platform --page website-and-docs-architecture-overview\n```\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create --version 1.1 --book developer --section architecture --page overview --title \"Architecture Overview\"\n```\n\n`page delete` removes the page directory and the matching page slug from nav data.\n\n`page rename` renames the page directory, updates `pages.\u003cbook\u003e.\u003csection\u003e.items`, and propagates inherited-only descendants when allowed.\n\nWhen a later version has independently authored the page, include it with `--also-version` to rename both versions in one atomic operation. Repeat the option for each independently authored version. The tool continues to move inherited-only versions automatically.\n\nA later version may already use the destination slug when it no longer contains the old slug. The tool refuses a version that contains both slugs, because that is an ambiguous page collision.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename --version 1.1 --also-version 1.3 --book end-user --section getting-started --from install --to setup --title \"Setup Sambee\"\n```\n\n`page move` moves a page to another section in the same book. It updates both page lists, materializes the selected version's destination page, and removes the source directory. `--to-page` optionally changes the slug; otherwise the source slug is retained. `--position` controls the destination order in the selected version.\n\nInherited-only descendants move automatically. The operation refuses if the destination exists, a later source page has real content, or a later version lacks the destination section. Links and managed redirects remain explicit content or deployment changes.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page move --version 0.9 --book admin-guide --from-section configuration --to-section reference --page configuration-key-reference --to-page configuration-file-reference --position start\n```\n\n## Notes\n\n- the tool does not edit `website/.generated/` directly\n- the tool does not run `materialize-inherited-docs.py` for you\n- the tool does not edit page body content or offer free-form front matter editing\n", "1.0": "+++\ntitle = \"Docs Editor Operation Reference\"\n+++\n\nUse this page when you already know you need the docs editor and want the detailed reference behavior.\n\n## Position Selectors\n\nOperations that insert books, sections, or pages use the same position syntax:\n\n- `\u003cindex\u003e`: insert at a zero-based numeric index\n- `before:\u003cslug\u003e`: insert immediately before the existing item\n- `after:\u003cslug\u003e`: insert immediately after the existing item\n- `start`: insert at the beginning\n- `end`: insert at the end\n\nIf the requested selector does not resolve cleanly in the target nav list, the operation refuses instead of guessing.\n\n## Global Options\n\nThe CLI supports these global options:\n\n- `--apply`: write changes to disk instead of previewing them\n- `--yes`: skip confirmation for destructive apply operations\n- `--json`: emit machine-readable preview or result output\n- `--quiet`: reduce non-error output\n- `--verbose`: reserved for future detailed output\n\n## Forward-Impact Analysis\n\nChanges in an older version can affect newer versions that still resolve through the same path. The tool analyzes that forward impact before destructive rename and delete operations.\n\nAffected newer versions fall into these categories:\n\n- inherited-only descendants: newer versions that contain only marker files for the affected path\n- structural descendants: newer versions that keep the path only as structure, without landing-page content\n- modified descendants: newer versions that contain real `_index.md` or `index.md` content at the affected path\n\nDefault behavior:\n\n- inherited-only descendants are updated automatically in apply mode\n- structural descendants are preserved where the operation allows it\n- modified descendants block destructive rename and delete operations\n\n## Content Rules the Tool Preserves\n\nThe docs editor preserves these invariants:\n\n- docs identity remains path-derived\n- `doc_id`, `product_version`, and `aliases` are not introduced\n- page folders contain exactly one of `index.md` or `inherit.md`\n- version and book folders contain exactly one of `_index.md` or `_inherit.md`\n- section folders contain zero or one of `_index.md` or `_inherit.md`\n- `inherit.md` and `_inherit.md` remain empty marker files\n- version order in `website/data/docs-versions.toml` stays canonical\n- nav data remains ordering-only metadata\n\n## Real Content Stubs\n\nWhen the tool creates real content, it writes a minimal front matter stub.\n\nDefaults:\n\n- page `index.md`: `title` defaults to a humanized page slug unless `--title` is provided\n- section `_index.md`: `title` defaults to the section title from nav data unless `--title` is provided\n- book `_index.md`: `title` defaults to a humanized book slug unless `--title` is provided\n- version `_index.md`: `title` defaults to the version label unless `--title` is provided\n\n## Inherited Markers\n\nWhen the tool creates inherited content, it writes:\n\n- empty `inherit.md` files for pages\n- empty `_inherit.md` files for version, book, and section landing pages\n\nNo front matter or body content is written into marker files.\n\n## Output Formats\n\nHuman-readable preview output shows the operation, the target path or version, the planned file changes, and the metadata changes that will be made on apply.\n\nJSON preview output includes:\n\n- `result`\n- `destructive`\n- `apply`\n- `metadata`\n- `changes`\n\nFor propagated destructive operations, `metadata` includes `propagated_versions` when later inherited-only versions will follow the change.\n\n## Standalone Report Generator\n\nUse [Docs Editor Tool](../docs-editor-tool/) for the high-level explanation of when to use the report and what it shows.\n\nThis reference section keeps only the CLI-specific behavior.\n\nThe report generator command is `website/scripts/docs-report.py`.\n\nBehavior:\n\n1. reads version metadata, nav files, and docs content directly from the repository\n2. writes `website-meta/docs-reports/docs-structure-report.html` by default\n3. embeds the report data, CSS, and JavaScript into one standalone HTML file\n\nExample:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py\n```\n\nCheck mode compares the current repository state against the committed HTML report and exits non-zero when the report needs regeneration:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py --check\n```\n\n## Operation Reference\n\n### Version Operations\n\n`version create` adds a new docs version, creates the matching content tree, initializes the new version to inherit from the previous version, and creates a matching nav file.\n\nRequired input:\n\n- new version slug\n- one insertion selector: `--after \u003cexisting-version\u003e` or `--latest`\n\nOptional input:\n\n- `--label \u003clabel\u003e`\n- `--status \u003cstatus\u003e`: optional UI label appended in parentheses after the version label, for example `preview` or `current`\n- `--visible true|false`\n- `--searchable true|false`\n- `--set-current`\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 1.2 --after 1.1 --label \"1.2\"\n```\n\nBehavior:\n\n1. inserts the new version into `website/data/docs-versions.toml`\n2. creates `website/content/docs/\u003cnew-version\u003e/`\n3. creates `website/data/docs-nav/\u003cnew-version\u003e.toml` from the previous version's nav data\n4. mirrors the previous version's docs tree shape\n5. creates inherited markers instead of copying authored content\n\nBootstrap behavior:\n\n- if `docs-versions.toml` has no declared versions, `--latest` bootstraps the first version instead of inheriting from a base version\n- in that case, the tool creates an authored version root with `_index.md`, creates an empty nav file, and sets the new version as `current`\n- this bootstrap path only works for a truly empty docs workspace; if version directories or version nav files still exist on disk, reconcile or remove them first\n\nImportant details:\n\n- the new version slug must not collide with an existing version\n- the reference version must exist\n- `status` is display metadata only; it does not decide which version is current\n- the actual current docs version is controlled by the top-level `current = \"\u003cslug\u003e\"` entry in `website/data/docs-versions.toml`\n- the current docs version changes only when `--set-current` is passed\n- `searchable` defaults to `false` unless explicitly set otherwise\n\n`version delete` removes a version entry, its nav file, and its content directory.\n\nRequired input:\n\n- version slug\n\nOptional input:\n\n- `--new-current \u003cversion\u003e` when deleting the current version\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version delete 1.1\n```\n\nBehavior:\n\n1. removes the version from `website/data/docs-versions.toml`\n2. removes `website/data/docs-nav/\u003cversion\u003e.toml`\n3. removes `website/content/docs/\u003cversion\u003e/`\n4. revalidates inheritance resolution across remaining versions\n\nRefusal cases:\n\n- the version does not exist\n- the version is current and `--new-current` was not supplied\n- `--new-current` points to the deleted version\n- `--new-current` does not exist after deletion\n- `--new-current` was supplied while deleting a non-current version\n\n### Book Operations\n\n`book create` creates a book folder, writes `_index.md` by default or `_inherit.md` with `--inherit`, and inserts the book into the version nav file.\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create --version 1.1 --book tutorials --title \"Tutorials\" --position end\n```\n\n`book delete` removes the book folder, the book entry in nav data, and the matching `sections.\u003cbook\u003e` and `pages.\u003cbook\u003e` data.\n\n`book rename` renames the book directory, updates `books` ordering plus the associated `sections` and `pages` tables, and propagates inherited-only descendants when allowed.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book rename --version 1.1 --from end-user --to user-guide --title \"User Guide\"\n```\n\n`book materialize` replaces an inherited book `_inherit.md` marker with a real `_index.md` using the currently resolved landing-page content. Use `--title` to replace the title while materializing.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book materialize --version 0.9 --book admin-guide\n```\n\n### Section Operations\n\n`section create` creates a section directory, adds a section entry in nav data, and initializes an empty `pages.\u003cbook\u003e.\u003csection\u003e.items` array.\n\nBy default it creates `_index.md`. With `--inherit`, it creates `_inherit.md`. With `--structural-only`, it creates no landing file. Optional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create --version 1.1 --book admin --section authentication --title \"Authentication\" --position end\n```\n\n`section delete` removes the section directory, its nav entry, and the matching `pages.\u003cbook\u003e.\u003csection\u003e` table.\n\n`section rename` renames the section directory, updates `sections.\u003cbook\u003e.items`, moves the matching `pages.\u003cbook\u003e.\u003csection\u003e` table to the new key, and preserves structural-only descendants as structural-only when no landing file exists at the renamed path.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section rename --version 1.1 --book admin --from configuration --to authentication --title \"Authentication\"\n```\n\n### Page Operations\n\n`page create` creates the page directory, writes `index.md` by default or `inherit.md` with `--inherit`, and adds the page slug to `pages.\u003cbook\u003e.\u003csection\u003e.items`.\n\nUse `page create` only when the page does not already exist in that version.\n\nIf the page already exists as an inherited page marker:\n\n- the directory already exists\n- the nav entry already exists\n- the page folder contains an empty `inherit.md`\n\nThen use `page materialize` instead of `page create`.\n\n`page materialize` replaces `inherit.md` with a real `index.md`, using the currently resolved inherited page content as the starting point.\n\nOptional input:\n\n- `--title \u003ctitle\u003e`: replace the inherited page title while materializing the real content\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page materialize --version 0.8 --book website-dev-guide --section docs-platform --page website-and-docs-architecture-overview\n```\n\nManual fallback if you need to control the copy step yourself:\n\n1. remove the inherited marker\n1. add `index.md`\n1. copy the inherited page body as the starting point\n1. edit that authored copy for the version-specific behavior\n\nThis remains outside the scope of `page create`, because the page identity and nav structure already exist.\n\n`page inherit` does the reverse: it replaces a real `index.md` in the selected version with `inherit.md` so the page resolves from an earlier authored version again.\n\nImportant details:\n\n- it is destructive because it removes that version's authored page content\n- apply mode requires `--yes` in non-interactive shells\n- it refuses when no earlier version resolves the same path to real `index.md` content\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply --yes page inherit --version 0.8 --book website-dev-guide --section docs-platform --page website-and-docs-architecture-overview\n```\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create --version 1.1 --book developer --section architecture --page overview --title \"Architecture Overview\"\n```\n\n`page delete` removes the page directory and the matching page slug from nav data.\n\n`page rename` renames the page directory, updates `pages.\u003cbook\u003e.\u003csection\u003e.items`, and propagates inherited-only descendants when allowed.\n\nWhen a later version has independently authored the page, include it with `--also-version` to rename both versions in one atomic operation. Repeat the option for each independently authored version. The tool continues to move inherited-only versions automatically.\n\nA later version may already use the destination slug when it no longer contains the old slug. The tool refuses a version that contains both slugs, because that is an ambiguous page collision.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename --version 1.1 --also-version 1.3 --book end-user --section getting-started --from install --to setup --title \"Setup Sambee\"\n```\n\n`page move` moves a page to another section in the same book. It updates both page lists, materializes the selected version's destination page, and removes the source directory. `--to-page` optionally changes the slug; otherwise the source slug is retained. `--position` controls the destination order in the selected version.\n\nInherited-only descendants move automatically. The operation refuses if the destination exists, a later source page has real content, or a later version lacks the destination section. Links and managed redirects remain explicit content or deployment changes.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page move --version 0.9 --book admin-guide --from-section configuration --to-section reference --page configuration-key-reference --to-page configuration-file-reference --position start\n```\n\n## Notes\n\n- the tool does not edit `website/.generated/` directly\n- the tool does not run `materialize-inherited-docs.py` for you\n- the tool does not edit page body content or offer free-form front matter editing\n", "2.0": "+++\ntitle = \"Docs Editor Operation Reference\"\n+++\n\nUse this page when you already know you need the docs editor and want the detailed reference behavior.\n\n## Position Selectors\n\nOperations that insert books, sections, or pages use the same position syntax:\n\n- `\u003cindex\u003e`: insert at a zero-based numeric index\n- `before:\u003cslug\u003e`: insert immediately before the existing item\n- `after:\u003cslug\u003e`: insert immediately after the existing item\n- `start`: insert at the beginning\n- `end`: insert at the end\n\nIf the requested selector does not resolve cleanly in the target nav list, the operation refuses instead of guessing.\n\n## Global Options\n\nThe CLI supports these global options:\n\n- `--apply`: write changes to disk instead of previewing them\n- `--yes`: skip confirmation for destructive apply operations\n- `--json`: emit machine-readable preview or result output\n- `--quiet`: reduce non-error output\n- `--verbose`: reserved for future detailed output\n\n## Forward-Impact Analysis\n\nChanges in an older version can affect newer versions that still resolve through the same path. The tool analyzes that forward impact before destructive rename and delete operations.\n\nAffected newer versions fall into these categories:\n\n- inherited-only descendants: newer versions that contain only marker files for the affected path\n- structural descendants: newer versions that keep the path only as structure, without landing-page content\n- modified descendants: newer versions that contain real `_index.md` or `index.md` content at the affected path\n\nDefault behavior:\n\n- inherited-only descendants are updated automatically in apply mode\n- structural descendants are preserved where the operation allows it\n- modified descendants block destructive rename and delete operations\n\n## Content Rules the Tool Preserves\n\nThe docs editor preserves these invariants:\n\n- docs identity remains path-derived\n- `doc_id`, `product_version`, and `aliases` are not introduced\n- page folders contain exactly one of `index.md` or `inherit.md`\n- version and book folders contain exactly one of `_index.md` or `_inherit.md`\n- section folders contain zero or one of `_index.md` or `_inherit.md`\n- `inherit.md` and `_inherit.md` remain empty marker files\n- version order in `website/data/docs-versions.toml` stays canonical\n- nav data remains ordering-only metadata\n\n## Real Content Stubs\n\nWhen the tool creates real content, it writes a minimal front matter stub.\n\nDefaults:\n\n- page `index.md`: `title` defaults to a humanized page slug unless `--title` is provided\n- section `_index.md`: `title` defaults to the section title from nav data unless `--title` is provided\n- book `_index.md`: `title` defaults to a humanized book slug unless `--title` is provided\n- version `_index.md`: `title` defaults to the version label unless `--title` is provided\n\n## Inherited Markers\n\nWhen the tool creates inherited content, it writes:\n\n- empty `inherit.md` files for pages\n- empty `_inherit.md` files for version, book, and section landing pages\n\nNo front matter or body content is written into marker files.\n\n## Output Formats\n\nHuman-readable preview output shows the operation, the target path or version, the planned file changes, and the metadata changes that will be made on apply.\n\nJSON preview output includes:\n\n- `result`\n- `destructive`\n- `apply`\n- `metadata`\n- `changes`\n\nFor propagated destructive operations, `metadata` includes `propagated_versions` when later inherited-only versions will follow the change.\n\n## Standalone Report Generator\n\nUse [Docs Editor Tool](../docs-editor-tool/) for the high-level explanation of when to use the report and what it shows.\n\nThis reference section keeps only the CLI-specific behavior.\n\nThe report generator command is `website/scripts/docs-report.py`.\n\nBehavior:\n\n1. reads version metadata, nav files, and docs content directly from the repository\n2. writes `website-meta/docs-reports/docs-structure-report.html` by default\n3. embeds the report data, CSS, and JavaScript into one standalone HTML file\n\nExample:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py\n```\n\nCheck mode compares the current repository state against the committed HTML report and exits non-zero when the report needs regeneration:\n\n```bash\ncd /workspace\npython3 website/scripts/docs-report.py --check\n```\n\n## Operation Reference\n\n### Version Operations\n\n`version create` adds a new docs version, creates the matching content tree, initializes the new version to inherit from the previous version, and creates a matching nav file.\n\nRequired input:\n\n- new version slug\n- one insertion selector: `--after \u003cexisting-version\u003e` or `--latest`\n\nOptional input:\n\n- `--label \u003clabel\u003e`\n- `--status \u003cstatus\u003e`: optional UI label appended in parentheses after the version label, for example `preview` or `current`\n- `--visible true|false`\n- `--searchable true|false`\n- `--set-current`\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version create 1.2 --after 1.1 --label \"1.2\"\n```\n\nBehavior:\n\n1. inserts the new version into `website/data/docs-versions.toml`\n2. creates `website/content/docs/\u003cnew-version\u003e/`\n3. creates `website/data/docs-nav/\u003cnew-version\u003e.toml` from the previous version's nav data\n4. mirrors the previous version's docs tree shape\n5. creates inherited markers instead of copying authored content\n\nBootstrap behavior:\n\n- if `docs-versions.toml` has no declared versions, `--latest` bootstraps the first version instead of inheriting from a base version\n- in that case, the tool creates an authored version root with `_index.md`, creates an empty nav file, and sets the new version as `current`\n- this bootstrap path only works for a truly empty docs workspace; if version directories or version nav files still exist on disk, reconcile or remove them first\n\nImportant details:\n\n- the new version slug must not collide with an existing version\n- the reference version must exist\n- `status` is display metadata only; it does not decide which version is current\n- the actual current docs version is controlled by the top-level `current = \"\u003cslug\u003e\"` entry in `website/data/docs-versions.toml`\n- the current docs version changes only when `--set-current` is passed\n- `searchable` defaults to `false` unless explicitly set otherwise\n\n`version delete` removes a version entry, its nav file, and its content directory.\n\nRequired input:\n\n- version slug\n\nOptional input:\n\n- `--new-current \u003cversion\u003e` when deleting the current version\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py version delete 1.1\n```\n\nBehavior:\n\n1. removes the version from `website/data/docs-versions.toml`\n2. removes `website/data/docs-nav/\u003cversion\u003e.toml`\n3. removes `website/content/docs/\u003cversion\u003e/`\n4. revalidates inheritance resolution across remaining versions\n\nRefusal cases:\n\n- the version does not exist\n- the version is current and `--new-current` was not supplied\n- `--new-current` points to the deleted version\n- `--new-current` does not exist after deletion\n- `--new-current` was supplied while deleting a non-current version\n\n### Book Operations\n\n`book create` creates a book folder, writes `_index.md` by default or `_inherit.md` with `--inherit`, and inserts the book into the version nav file.\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book create --version 1.1 --book tutorials --title \"Tutorials\" --position end\n```\n\n`book delete` removes the book folder, the book entry in nav data, and the matching `sections.\u003cbook\u003e` and `pages.\u003cbook\u003e` data.\n\n`book rename` renames the book directory, updates `books` ordering plus the associated `sections` and `pages` tables, and propagates inherited-only descendants when allowed.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book rename --version 1.1 --from end-user --to user-guide --title \"User Guide\"\n```\n\n`book materialize` replaces an inherited book `_inherit.md` marker with a real `_index.md` using the currently resolved landing-page content. Use `--title` to replace the title while materializing.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py book materialize --version 0.9 --book admin-guide\n```\n\n### Section Operations\n\n`section create` creates a section directory, adds a section entry in nav data, and initializes an empty `pages.\u003cbook\u003e.\u003csection\u003e.items` array.\n\nBy default it creates `_index.md`. With `--inherit`, it creates `_inherit.md`. With `--structural-only`, it creates no landing file. Optional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section create --version 1.1 --book admin --section authentication --title \"Authentication\" --position end\n```\n\n`section delete` removes the section directory, its nav entry, and the matching `pages.\u003cbook\u003e.\u003csection\u003e` table.\n\n`section rename` renames the section directory, updates `sections.\u003cbook\u003e.items`, moves the matching `pages.\u003cbook\u003e.\u003csection\u003e` table to the new key, and preserves structural-only descendants as structural-only when no landing file exists at the renamed path.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py section rename --version 1.1 --book admin --from configuration --to authentication --title \"Authentication\"\n```\n\n### Page Operations\n\n`page create` creates the page directory, writes `index.md` by default or `inherit.md` with `--inherit`, and adds the page slug to `pages.\u003cbook\u003e.\u003csection\u003e.items`.\n\nUse `page create` only when the page does not already exist in that version.\n\nIf the page already exists as an inherited page marker:\n\n- the directory already exists\n- the nav entry already exists\n- the page folder contains an empty `inherit.md`\n\nThen use `page materialize` instead of `page create`.\n\n`page materialize` replaces `inherit.md` with a real `index.md`, using the currently resolved inherited page content as the starting point.\n\nOptional input:\n\n- `--title \u003ctitle\u003e`: replace the inherited page title while materializing the real content\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page materialize --version 0.8 --book website-dev-guide --section docs-platform --page website-and-docs-architecture-overview\n```\n\nManual fallback if you need to control the copy step yourself:\n\n1. remove the inherited marker\n1. add `index.md`\n1. copy the inherited page body as the starting point\n1. edit that authored copy for the version-specific behavior\n\nThis remains outside the scope of `page create`, because the page identity and nav structure already exist.\n\n`page inherit` does the reverse: it replaces a real `index.md` in the selected version with `inherit.md` so the page resolves from an earlier authored version again.\n\nImportant details:\n\n- it is destructive because it removes that version's authored page content\n- apply mode requires `--yes` in non-interactive shells\n- it refuses when no earlier version resolves the same path to real `index.md` content\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py --apply --yes page inherit --version 0.8 --book website-dev-guide --section docs-platform --page website-and-docs-architecture-overview\n```\n\nOptional input includes `--position \u003cindex|before:\u003cslug\u003e|after:\u003cslug\u003e|start|end\u003e`.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page create --version 1.1 --book developer --section architecture --page overview --title \"Architecture Overview\"\n```\n\n`page delete` removes the page directory and the matching page slug from nav data.\n\n`page rename` renames the page directory, updates `pages.\u003cbook\u003e.\u003csection\u003e.items`, and propagates inherited-only descendants when allowed.\n\nWhen a later version has independently authored the page, include it with `--also-version` to rename both versions in one atomic operation. Repeat the option for each independently authored version. The tool continues to move inherited-only versions automatically.\n\nA later version may already use the destination slug when it no longer contains the old slug. The tool refuses a version that contains both slugs, because that is an ambiguous page collision.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page rename --version 1.1 --also-version 1.3 --book end-user --section getting-started --from install --to setup --title \"Setup Sambee\"\n```\n\n`page move` moves a page to another section in the same book. It updates both page lists, materializes the selected version's destination page, and removes the source directory. `--to-page` optionally changes the slug; otherwise the source slug is retained. `--position` controls the destination order in the selected version.\n\nInherited-only descendants move automatically. The operation refuses if the destination exists, a later source page has real content, or a later version lacks the destination section. Links and managed redirects remain explicit content or deployment changes.\n\nExample:\n\n```bash\ncd website\npython3 scripts/docs-editor.py page move --version 0.9 --book admin-guide --from-section configuration --to-section reference --page configuration-key-reference --to-page configuration-file-reference --position start\n```\n\n## Notes\n\n- the tool does not edit `website/.generated/` directly\n- the tool does not run `materialize-inherited-docs.py` for you\n- the tool does not edit page body content or offer free-form front matter editing\n"}, "flags": {"has_branched": true, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:website-dev-guide/site-systems", "parent_id": "book:website-dev-guide", "depth": 1, "kind": "section", "label": "site-systems", "title": "Site Systems", "path": "website-dev-guide/site-systems", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:website-dev-guide/site-systems/media-publishing-workflow", "parent_id": "section:website-dev-guide/site-systems", "depth": 2, "kind": "page", "label": "media-publishing-workflow", "title": "Media Publishing Workflow", "path": "website-dev-guide/site-systems/media-publishing-workflow", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Media Publishing Workflow\"\n+++\n\nThe website media workflow is repository-driven. The source files and the generated derivatives both belong in the repo.\n\n## Goals\n\n- Source images are committed in the repository.\n- Pre-generated WebP derivatives are committed in the repository.\n- The committed social preview PNG is generated locally and committed in the repository.\n- Source images and generated derivatives are tracked with Git LFS.\n- Every raster source image has generated WebP derivatives.\n- Local development and CI pull media from Git LFS before building.\n- CI publishes built media from `website/public` rather than generating missing derivatives during deployment.\n\n## Required Tools\n\nYou need:\n\n- `git-lfs`\n- ImageMagick's `magick` command when generating derivatives locally\n\nAfter cloning, pull LFS objects before you work on the site:\n\n```bash\ngit lfs pull\n```\n\nIf the LFS objects are missing, a site build may appear to work while still producing broken image references or missing derivatives.\n\n## Source of Truth\n\nThe source of truth for website media is the checked-in asset tree:\n\n- `website/assets/images/` for source images and generated WebPs\n- `website/assets/images/` for source images and committed generated derivatives, including WebPs and the social preview PNG\n- `website/static/files/` for downloadable files\n\nHugo's cached outputs under `website/resources/_gen/images/` are build artifacts, not source content and not committed media.\n\nGenerated derivatives live in a sibling `generated/` directory next to the source image.\n\nExample:\n\n```text\nwebsite/assets/images/home/companion-screenshot.png\nwebsite/assets/images/home/generated/companion-screenshot_372w.webp\nwebsite/assets/images/home/generated/companion-screenshot_500w.webp\nwebsite/assets/images/home/generated/sambee-screenshot_1200w.png\n```\n\n## Authoring Workflow\n\nWhen you add or change a raster image:\n\n1. Add or update the source file under `website/assets/images/`.\n2. Start the website preview task or run `npm run dev`.\n3. Let the local watcher regenerate missing derivatives automatically, or generate them manually.\n4. Review the generated files in the matching `generated/` directory.\n5. Commit the source image and the generated derivatives together.\n\nThe local watcher covers two cases:\n\n- For ordinary raster images, it regenerates the matching WebP derivatives.\n- For `website/assets/images/home/sambee-screenshot.png`, it also regenerates the committed social preview PNG at `website/assets/images/home/generated/sambee-screenshot_1200w.png`.\n\nManual batch generation:\n\n```bash\ncd website\nnpm run images:generate\n```\n\nManual social preview generation:\n\n```bash\ncd website\nnpm run social:generate\n```\n\nDo not rely on CI to create missing derivatives. Missing generated media is a defect.\n\n## Build and Publish Expectations\n\nThe website build and deployment flow is set up around this behavior:\n\n- Local development pulls Git LFS objects before serving the site.\n- The local dev workflow runs the image watcher during `npm run dev`.\n- CI restores and pulls Git LFS objects before building the site.\n- CI validates that raster source images have generated WebP derivatives.\n- The shared head template fails the Hugo build if the committed social preview PNG is missing or is not `1200x630`.\n- CI uploads `website/public` as a short-lived artifact after the build.\n- The deploy job publishes `website/public` to Cloudflare Pages.\n\nThe project scripts that matter most here are:\n\n- `npm run images:generate`\n- `npm run images:validate`\n- `npm run social:generate`\n- `npm run build`\n\nThe workflow lives in `.github/workflows/website-deploy.yml`. The important steps include:\n\n- restore `.git/lfs` cache and run `git lfs pull`\n- restore `website/resources/_gen` cache for faster rebuilds\n- validate generated WebP coverage\n- build the Hugo site and Pagefind index inside `website/`\n- upload `website/public` as a short-lived artifact\n- deploy the built site from `website/public`\n\nFor the Cloudflare-side setup, GitHub Actions secrets, and deployment branch rules, see [Set Up Cloudflare Pages Publishing](../../setup-and-operations/set-up-cloudflare-pages-publishing/).\n", "0.8": "+++\ntitle = \"Media Publishing Workflow\"\n+++\n\nThe website media workflow is repository-driven. The source files and the generated derivatives both belong in the repo.\n\n## Goals\n\n- Source images are committed in the repository.\n- Pre-generated WebP derivatives are committed in the repository.\n- The committed social preview PNG is generated locally and committed in the repository.\n- Source images and generated derivatives are tracked with Git LFS.\n- Every raster source image has generated WebP derivatives.\n- Local development and CI pull media from Git LFS before building.\n- CI publishes built media from `website/public` rather than generating missing derivatives during deployment.\n\n## Required Tools\n\nYou need:\n\n- `git-lfs`\n- ImageMagick's `magick` command when generating derivatives locally\n\nAfter cloning, pull LFS objects before you work on the site:\n\n```bash\ngit lfs pull\n```\n\nIf the LFS objects are missing, a site build may appear to work while still producing broken image references or missing derivatives.\n\n## Source of Truth\n\nThe source of truth for website media is the checked-in asset tree:\n\n- `website/assets/images/` for source images and generated WebPs\n- `website/assets/images/` for source images and committed generated derivatives, including WebPs and the social preview PNG\n- `website/static/files/` for downloadable files\n\nHugo's cached outputs under `website/resources/_gen/images/` are build artifacts, not source content and not committed media.\n\nGenerated derivatives live in a sibling `generated/` directory next to the source image.\n\nExample:\n\n```text\nwebsite/assets/images/home/companion-screenshot.png\nwebsite/assets/images/home/generated/companion-screenshot_372w.webp\nwebsite/assets/images/home/generated/companion-screenshot_500w.webp\nwebsite/assets/images/home/generated/sambee-screenshot_1200w.png\n```\n\n## Authoring Workflow\n\nWhen you add or change a raster image:\n\n1. Add or update the source file under `website/assets/images/`.\n2. Start the website preview task or run `npm run dev`.\n3. Let the local watcher regenerate missing derivatives automatically, or generate them manually.\n4. Review the generated files in the matching `generated/` directory.\n5. Commit the source image and the generated derivatives together.\n\nThe local watcher covers two cases:\n\n- For ordinary raster images, it regenerates the matching WebP derivatives.\n- For `website/assets/images/home/sambee-screenshot.png`, it also regenerates the committed social preview PNG at `website/assets/images/home/generated/sambee-screenshot_1200w.png`.\n\nManual batch generation:\n\n```bash\ncd website\nnpm run images:generate\n```\n\nManual social preview generation:\n\n```bash\ncd website\nnpm run social:generate\n```\n\nDo not rely on CI to create missing derivatives. Missing generated media is a defect.\n\n## Build and Publish Expectations\n\nThe website build and deployment flow is set up around this behavior:\n\n- Local development pulls Git LFS objects before serving the site.\n- The local dev workflow runs the image watcher during `npm run dev`.\n- CI restores and pulls Git LFS objects before building the site.\n- CI validates that raster source images have generated WebP derivatives.\n- The shared head template fails the Hugo build if the committed social preview PNG is missing or is not `1200x630`.\n- CI uploads `website/public` as a short-lived artifact after the build.\n- The deploy job publishes `website/public` to Cloudflare Pages.\n\nThe project scripts that matter most here are:\n\n- `npm run images:generate`\n- `npm run images:validate`\n- `npm run social:generate`\n- `npm run build`\n\nThe workflow lives in `.github/workflows/website-deploy.yml`. The important steps include:\n\n- restore `.git/lfs` cache and run `git lfs pull`\n- restore `website/resources/_gen` cache for faster rebuilds\n- validate generated WebP coverage\n- build the Hugo site and Pagefind index inside `website/`\n- upload `website/public` as a short-lived artifact\n- deploy the built site from `website/public`\n\nFor the Cloudflare-side setup, GitHub Actions secrets, and deployment branch rules, see [Set Up Cloudflare Pages Publishing](../../setup-and-operations/set-up-cloudflare-pages-publishing/).\n", "0.9": "+++\ntitle = \"Media Publishing Workflow\"\n+++\n\nThe website media workflow is repository-driven. The source files and the generated derivatives both belong in the repo.\n\n## Goals\n\n- Source images are committed in the repository.\n- Pre-generated WebP derivatives are committed in the repository.\n- The committed social preview PNG is generated locally and committed in the repository.\n- Source images and generated derivatives are tracked with Git LFS.\n- Every raster source image has generated WebP derivatives.\n- Local development and CI pull media from Git LFS before building.\n- CI publishes built media from `website/public` rather than generating missing derivatives during deployment.\n\n## Required Tools\n\nYou need:\n\n- `git-lfs`\n- ImageMagick's `magick` command when generating derivatives locally\n\nAfter cloning, pull LFS objects before you work on the site:\n\n```bash\ngit lfs pull\n```\n\nIf the LFS objects are missing, a site build may appear to work while still producing broken image references or missing derivatives.\n\n## Source of Truth\n\nThe source of truth for website media is the checked-in asset tree:\n\n- `website/assets/images/` for source images and generated WebPs\n- `website/assets/images/` for source images and committed generated derivatives, including WebPs and the social preview PNG\n- `website/static/files/` for downloadable files\n\nHugo's cached outputs under `website/resources/_gen/images/` are build artifacts, not source content and not committed media.\n\nGenerated derivatives live in a sibling `generated/` directory next to the source image.\n\nExample:\n\n```text\nwebsite/assets/images/home/companion-screenshot.png\nwebsite/assets/images/home/generated/companion-screenshot_372w.webp\nwebsite/assets/images/home/generated/companion-screenshot_500w.webp\nwebsite/assets/images/home/generated/sambee-screenshot_1200w.png\n```\n\n## Authoring Workflow\n\nWhen you add or change a raster image:\n\n1. Add or update the source file under `website/assets/images/`.\n2. Start the website preview task or run `npm run dev`.\n3. Let the local watcher regenerate missing derivatives automatically, or generate them manually.\n4. Review the generated files in the matching `generated/` directory.\n5. Commit the source image and the generated derivatives together.\n\nThe local watcher covers two cases:\n\n- For ordinary raster images, it regenerates the matching WebP derivatives.\n- For `website/assets/images/home/sambee-screenshot.png`, it also regenerates the committed social preview PNG at `website/assets/images/home/generated/sambee-screenshot_1200w.png`.\n\nManual batch generation:\n\n```bash\ncd website\nnpm run images:generate\n```\n\nManual social preview generation:\n\n```bash\ncd website\nnpm run social:generate\n```\n\nDo not rely on CI to create missing derivatives. Missing generated media is a defect.\n\n## Build and Publish Expectations\n\nThe website build and deployment flow is set up around this behavior:\n\n- Local development pulls Git LFS objects before serving the site.\n- The local dev workflow runs the image watcher during `npm run dev`.\n- CI restores and pulls Git LFS objects before building the site.\n- CI validates that raster source images have generated WebP derivatives.\n- The shared head template fails the Hugo build if the committed social preview PNG is missing or is not `1200x630`.\n- CI uploads `website/public` as a short-lived artifact after the build.\n- The deploy job publishes `website/public` to Cloudflare Pages.\n\nThe project scripts that matter most here are:\n\n- `npm run images:generate`\n- `npm run images:validate`\n- `npm run social:generate`\n- `npm run build`\n\nThe workflow lives in `.github/workflows/website-deploy.yml`. The important steps include:\n\n- restore `.git/lfs` cache and run `git lfs pull`\n- restore `website/resources/_gen` cache for faster rebuilds\n- validate generated WebP coverage\n- build the Hugo site and Pagefind index inside `website/`\n- upload `website/public` as a short-lived artifact\n- deploy the built site from `website/public`\n\nFor the Cloudflare-side setup, GitHub Actions secrets, and deployment branch rules, see [Set Up Cloudflare Pages Publishing](../../setup-and-operations/set-up-cloudflare-pages-publishing/).\n", "1.0": "+++\ntitle = \"Media Publishing Workflow\"\n+++\n\nThe website media workflow is repository-driven. The source files and the generated derivatives both belong in the repo.\n\n## Goals\n\n- Source images are committed in the repository.\n- Pre-generated WebP derivatives are committed in the repository.\n- The committed social preview PNG is generated locally and committed in the repository.\n- Source images and generated derivatives are tracked with Git LFS.\n- Every raster source image has generated WebP derivatives.\n- Local development and CI pull media from Git LFS before building.\n- CI publishes built media from `website/public` rather than generating missing derivatives during deployment.\n\n## Required Tools\n\nYou need:\n\n- `git-lfs`\n- ImageMagick's `magick` command when generating derivatives locally\n\nAfter cloning, pull LFS objects before you work on the site:\n\n```bash\ngit lfs pull\n```\n\nIf the LFS objects are missing, a site build may appear to work while still producing broken image references or missing derivatives.\n\n## Source of Truth\n\nThe source of truth for website media is the checked-in asset tree:\n\n- `website/assets/images/` for source images and generated WebPs\n- `website/assets/images/` for source images and committed generated derivatives, including WebPs and the social preview PNG\n- `website/static/files/` for downloadable files\n\nHugo's cached outputs under `website/resources/_gen/images/` are build artifacts, not source content and not committed media.\n\nGenerated derivatives live in a sibling `generated/` directory next to the source image.\n\nExample:\n\n```text\nwebsite/assets/images/home/companion-screenshot.png\nwebsite/assets/images/home/generated/companion-screenshot_372w.webp\nwebsite/assets/images/home/generated/companion-screenshot_500w.webp\nwebsite/assets/images/home/generated/sambee-screenshot_1200w.png\n```\n\n## Authoring Workflow\n\nWhen you add or change a raster image:\n\n1. Add or update the source file under `website/assets/images/`.\n2. Start the website preview task or run `npm run dev`.\n3. Let the local watcher regenerate missing derivatives automatically, or generate them manually.\n4. Review the generated files in the matching `generated/` directory.\n5. Commit the source image and the generated derivatives together.\n\nThe local watcher covers two cases:\n\n- For ordinary raster images, it regenerates the matching WebP derivatives.\n- For `website/assets/images/home/sambee-screenshot.png`, it also regenerates the committed social preview PNG at `website/assets/images/home/generated/sambee-screenshot_1200w.png`.\n\nManual batch generation:\n\n```bash\ncd website\nnpm run images:generate\n```\n\nManual social preview generation:\n\n```bash\ncd website\nnpm run social:generate\n```\n\nDo not rely on CI to create missing derivatives. Missing generated media is a defect.\n\n## Build and Publish Expectations\n\nThe website build and deployment flow is set up around this behavior:\n\n- Local development pulls Git LFS objects before serving the site.\n- The local dev workflow runs the image watcher during `npm run dev`.\n- CI restores and pulls Git LFS objects before building the site.\n- CI validates that raster source images have generated WebP derivatives.\n- The shared head template fails the Hugo build if the committed social preview PNG is missing or is not `1200x630`.\n- CI uploads `website/public` as a short-lived artifact after the build.\n- The deploy job publishes `website/public` to Cloudflare Pages.\n\nThe project scripts that matter most here are:\n\n- `npm run images:generate`\n- `npm run images:validate`\n- `npm run social:generate`\n- `npm run build`\n\nThe workflow lives in `.github/workflows/website-deploy.yml`. The important steps include:\n\n- restore `.git/lfs` cache and run `git lfs pull`\n- restore `website/resources/_gen` cache for faster rebuilds\n- validate generated WebP coverage\n- build the Hugo site and Pagefind index inside `website/`\n- upload `website/public` as a short-lived artifact\n- deploy the built site from `website/public`\n\nFor the Cloudflare-side setup, GitHub Actions secrets, and deployment branch rules, see [Set Up Cloudflare Pages Publishing](../../setup-and-operations/set-up-cloudflare-pages-publishing/).\n", "2.0": "+++\ntitle = \"Media Publishing Workflow\"\n+++\n\nThe website media workflow is repository-driven. The source files and the generated derivatives both belong in the repo.\n\n## Goals\n\n- Source images are committed in the repository.\n- Pre-generated WebP derivatives are committed in the repository.\n- The committed social preview PNG is generated locally and committed in the repository.\n- Source images and generated derivatives are tracked with Git LFS.\n- Every raster source image has generated WebP derivatives.\n- Local development and CI pull media from Git LFS before building.\n- CI publishes built media from `website/public` rather than generating missing derivatives during deployment.\n\n## Required Tools\n\nYou need:\n\n- `git-lfs`\n- ImageMagick's `magick` command when generating derivatives locally\n\nAfter cloning, pull LFS objects before you work on the site:\n\n```bash\ngit lfs pull\n```\n\nIf the LFS objects are missing, a site build may appear to work while still producing broken image references or missing derivatives.\n\n## Source of Truth\n\nThe source of truth for website media is the checked-in asset tree:\n\n- `website/assets/images/` for source images and generated WebPs\n- `website/assets/images/` for source images and committed generated derivatives, including WebPs and the social preview PNG\n- `website/static/files/` for downloadable files\n\nHugo's cached outputs under `website/resources/_gen/images/` are build artifacts, not source content and not committed media.\n\nGenerated derivatives live in a sibling `generated/` directory next to the source image.\n\nExample:\n\n```text\nwebsite/assets/images/home/companion-screenshot.png\nwebsite/assets/images/home/generated/companion-screenshot_372w.webp\nwebsite/assets/images/home/generated/companion-screenshot_500w.webp\nwebsite/assets/images/home/generated/sambee-screenshot_1200w.png\n```\n\n## Authoring Workflow\n\nWhen you add or change a raster image:\n\n1. Add or update the source file under `website/assets/images/`.\n2. Start the website preview task or run `npm run dev`.\n3. Let the local watcher regenerate missing derivatives automatically, or generate them manually.\n4. Review the generated files in the matching `generated/` directory.\n5. Commit the source image and the generated derivatives together.\n\nThe local watcher covers two cases:\n\n- For ordinary raster images, it regenerates the matching WebP derivatives.\n- For `website/assets/images/home/sambee-screenshot.png`, it also regenerates the committed social preview PNG at `website/assets/images/home/generated/sambee-screenshot_1200w.png`.\n\nManual batch generation:\n\n```bash\ncd website\nnpm run images:generate\n```\n\nManual social preview generation:\n\n```bash\ncd website\nnpm run social:generate\n```\n\nDo not rely on CI to create missing derivatives. Missing generated media is a defect.\n\n## Build and Publish Expectations\n\nThe website build and deployment flow is set up around this behavior:\n\n- Local development pulls Git LFS objects before serving the site.\n- The local dev workflow runs the image watcher during `npm run dev`.\n- CI restores and pulls Git LFS objects before building the site.\n- CI validates that raster source images have generated WebP derivatives.\n- The shared head template fails the Hugo build if the committed social preview PNG is missing or is not `1200x630`.\n- CI uploads `website/public` as a short-lived artifact after the build.\n- The deploy job publishes `website/public` to Cloudflare Pages.\n\nThe project scripts that matter most here are:\n\n- `npm run images:generate`\n- `npm run images:validate`\n- `npm run social:generate`\n- `npm run build`\n\nThe workflow lives in `.github/workflows/website-deploy.yml`. The important steps include:\n\n- restore `.git/lfs` cache and run `git lfs pull`\n- restore `website/resources/_gen` cache for faster rebuilds\n- validate generated WebP coverage\n- build the Hugo site and Pagefind index inside `website/`\n- upload `website/public` as a short-lived artifact\n- deploy the built site from `website/public`\n\nFor the Cloudflare-side setup, GitHub Actions secrets, and deployment branch rules, see [Set Up Cloudflare Pages Publishing](../../setup-and-operations/set-up-cloudflare-pages-publishing/).\n"}, "page_contents": {"0.7": "+++\ntitle = \"Media Publishing Workflow\"\n+++\n\nThe website media workflow is repository-driven. The source files and the generated derivatives both belong in the repo.\n\n## Goals\n\n- Source images are committed in the repository.\n- Pre-generated WebP derivatives are committed in the repository.\n- The committed social preview PNG is generated locally and committed in the repository.\n- Source images and generated derivatives are tracked with Git LFS.\n- Every raster source image has generated WebP derivatives.\n- Local development and CI pull media from Git LFS before building.\n- CI publishes built media from `website/public` rather than generating missing derivatives during deployment.\n\n## Required Tools\n\nYou need:\n\n- `git-lfs`\n- ImageMagick's `magick` command when generating derivatives locally\n\nAfter cloning, pull LFS objects before you work on the site:\n\n```bash\ngit lfs pull\n```\n\nIf the LFS objects are missing, a site build may appear to work while still producing broken image references or missing derivatives.\n\n## Source of Truth\n\nThe source of truth for website media is the checked-in asset tree:\n\n- `website/assets/images/` for source images and generated WebPs\n- `website/assets/images/` for source images and committed generated derivatives, including WebPs and the social preview PNG\n- `website/static/files/` for downloadable files\n\nHugo's cached outputs under `website/resources/_gen/images/` are build artifacts, not source content and not committed media.\n\nGenerated derivatives live in a sibling `generated/` directory next to the source image.\n\nExample:\n\n```text\nwebsite/assets/images/home/companion-screenshot.png\nwebsite/assets/images/home/generated/companion-screenshot_372w.webp\nwebsite/assets/images/home/generated/companion-screenshot_500w.webp\nwebsite/assets/images/home/generated/sambee-screenshot_1200w.png\n```\n\n## Authoring Workflow\n\nWhen you add or change a raster image:\n\n1. Add or update the source file under `website/assets/images/`.\n2. Start the website preview task or run `npm run dev`.\n3. Let the local watcher regenerate missing derivatives automatically, or generate them manually.\n4. Review the generated files in the matching `generated/` directory.\n5. Commit the source image and the generated derivatives together.\n\nThe local watcher covers two cases:\n\n- For ordinary raster images, it regenerates the matching WebP derivatives.\n- For `website/assets/images/home/sambee-screenshot.png`, it also regenerates the committed social preview PNG at `website/assets/images/home/generated/sambee-screenshot_1200w.png`.\n\nManual batch generation:\n\n```bash\ncd website\nnpm run images:generate\n```\n\nManual social preview generation:\n\n```bash\ncd website\nnpm run social:generate\n```\n\nDo not rely on CI to create missing derivatives. Missing generated media is a defect.\n\n## Build and Publish Expectations\n\nThe website build and deployment flow is set up around this behavior:\n\n- Local development pulls Git LFS objects before serving the site.\n- The local dev workflow runs the image watcher during `npm run dev`.\n- CI restores and pulls Git LFS objects before building the site.\n- CI validates that raster source images have generated WebP derivatives.\n- The shared head template fails the Hugo build if the committed social preview PNG is missing or is not `1200x630`.\n- CI uploads `website/public` as a short-lived artifact after the build.\n- The deploy job publishes `website/public` to Cloudflare Pages.\n\nThe project scripts that matter most here are:\n\n- `npm run images:generate`\n- `npm run images:validate`\n- `npm run social:generate`\n- `npm run build`\n\nThe workflow lives in `.github/workflows/website-deploy.yml`. The important steps include:\n\n- restore `.git/lfs` cache and run `git lfs pull`\n- restore `website/resources/_gen` cache for faster rebuilds\n- validate generated WebP coverage\n- build the Hugo site and Pagefind index inside `website/`\n- upload `website/public` as a short-lived artifact\n- deploy the built site from `website/public`\n\nFor the Cloudflare-side setup, GitHub Actions secrets, and deployment branch rules, see [Set Up Cloudflare Pages Publishing](../../setup-and-operations/set-up-cloudflare-pages-publishing/).\n", "0.8": "+++\ntitle = \"Media Publishing Workflow\"\n+++\n\nThe website media workflow is repository-driven. The source files and the generated derivatives both belong in the repo.\n\n## Goals\n\n- Source images are committed in the repository.\n- Pre-generated WebP derivatives are committed in the repository.\n- The committed social preview PNG is generated locally and committed in the repository.\n- Source images and generated derivatives are tracked with Git LFS.\n- Every raster source image has generated WebP derivatives.\n- Local development and CI pull media from Git LFS before building.\n- CI publishes built media from `website/public` rather than generating missing derivatives during deployment.\n\n## Required Tools\n\nYou need:\n\n- `git-lfs`\n- ImageMagick's `magick` command when generating derivatives locally\n\nAfter cloning, pull LFS objects before you work on the site:\n\n```bash\ngit lfs pull\n```\n\nIf the LFS objects are missing, a site build may appear to work while still producing broken image references or missing derivatives.\n\n## Source of Truth\n\nThe source of truth for website media is the checked-in asset tree:\n\n- `website/assets/images/` for source images and generated WebPs\n- `website/assets/images/` for source images and committed generated derivatives, including WebPs and the social preview PNG\n- `website/static/files/` for downloadable files\n\nHugo's cached outputs under `website/resources/_gen/images/` are build artifacts, not source content and not committed media.\n\nGenerated derivatives live in a sibling `generated/` directory next to the source image.\n\nExample:\n\n```text\nwebsite/assets/images/home/companion-screenshot.png\nwebsite/assets/images/home/generated/companion-screenshot_372w.webp\nwebsite/assets/images/home/generated/companion-screenshot_500w.webp\nwebsite/assets/images/home/generated/sambee-screenshot_1200w.png\n```\n\n## Authoring Workflow\n\nWhen you add or change a raster image:\n\n1. Add or update the source file under `website/assets/images/`.\n2. Start the website preview task or run `npm run dev`.\n3. Let the local watcher regenerate missing derivatives automatically, or generate them manually.\n4. Review the generated files in the matching `generated/` directory.\n5. Commit the source image and the generated derivatives together.\n\nThe local watcher covers two cases:\n\n- For ordinary raster images, it regenerates the matching WebP derivatives.\n- For `website/assets/images/home/sambee-screenshot.png`, it also regenerates the committed social preview PNG at `website/assets/images/home/generated/sambee-screenshot_1200w.png`.\n\nManual batch generation:\n\n```bash\ncd website\nnpm run images:generate\n```\n\nManual social preview generation:\n\n```bash\ncd website\nnpm run social:generate\n```\n\nDo not rely on CI to create missing derivatives. Missing generated media is a defect.\n\n## Build and Publish Expectations\n\nThe website build and deployment flow is set up around this behavior:\n\n- Local development pulls Git LFS objects before serving the site.\n- The local dev workflow runs the image watcher during `npm run dev`.\n- CI restores and pulls Git LFS objects before building the site.\n- CI validates that raster source images have generated WebP derivatives.\n- The shared head template fails the Hugo build if the committed social preview PNG is missing or is not `1200x630`.\n- CI uploads `website/public` as a short-lived artifact after the build.\n- The deploy job publishes `website/public` to Cloudflare Pages.\n\nThe project scripts that matter most here are:\n\n- `npm run images:generate`\n- `npm run images:validate`\n- `npm run social:generate`\n- `npm run build`\n\nThe workflow lives in `.github/workflows/website-deploy.yml`. The important steps include:\n\n- restore `.git/lfs` cache and run `git lfs pull`\n- restore `website/resources/_gen` cache for faster rebuilds\n- validate generated WebP coverage\n- build the Hugo site and Pagefind index inside `website/`\n- upload `website/public` as a short-lived artifact\n- deploy the built site from `website/public`\n\nFor the Cloudflare-side setup, GitHub Actions secrets, and deployment branch rules, see [Set Up Cloudflare Pages Publishing](../../setup-and-operations/set-up-cloudflare-pages-publishing/).\n", "0.9": "+++\ntitle = \"Media Publishing Workflow\"\n+++\n\nThe website media workflow is repository-driven. The source files and the generated derivatives both belong in the repo.\n\n## Goals\n\n- Source images are committed in the repository.\n- Pre-generated WebP derivatives are committed in the repository.\n- The committed social preview PNG is generated locally and committed in the repository.\n- Source images and generated derivatives are tracked with Git LFS.\n- Every raster source image has generated WebP derivatives.\n- Local development and CI pull media from Git LFS before building.\n- CI publishes built media from `website/public` rather than generating missing derivatives during deployment.\n\n## Required Tools\n\nYou need:\n\n- `git-lfs`\n- ImageMagick's `magick` command when generating derivatives locally\n\nAfter cloning, pull LFS objects before you work on the site:\n\n```bash\ngit lfs pull\n```\n\nIf the LFS objects are missing, a site build may appear to work while still producing broken image references or missing derivatives.\n\n## Source of Truth\n\nThe source of truth for website media is the checked-in asset tree:\n\n- `website/assets/images/` for source images and generated WebPs\n- `website/assets/images/` for source images and committed generated derivatives, including WebPs and the social preview PNG\n- `website/static/files/` for downloadable files\n\nHugo's cached outputs under `website/resources/_gen/images/` are build artifacts, not source content and not committed media.\n\nGenerated derivatives live in a sibling `generated/` directory next to the source image.\n\nExample:\n\n```text\nwebsite/assets/images/home/companion-screenshot.png\nwebsite/assets/images/home/generated/companion-screenshot_372w.webp\nwebsite/assets/images/home/generated/companion-screenshot_500w.webp\nwebsite/assets/images/home/generated/sambee-screenshot_1200w.png\n```\n\n## Authoring Workflow\n\nWhen you add or change a raster image:\n\n1. Add or update the source file under `website/assets/images/`.\n2. Start the website preview task or run `npm run dev`.\n3. Let the local watcher regenerate missing derivatives automatically, or generate them manually.\n4. Review the generated files in the matching `generated/` directory.\n5. Commit the source image and the generated derivatives together.\n\nThe local watcher covers two cases:\n\n- For ordinary raster images, it regenerates the matching WebP derivatives.\n- For `website/assets/images/home/sambee-screenshot.png`, it also regenerates the committed social preview PNG at `website/assets/images/home/generated/sambee-screenshot_1200w.png`.\n\nManual batch generation:\n\n```bash\ncd website\nnpm run images:generate\n```\n\nManual social preview generation:\n\n```bash\ncd website\nnpm run social:generate\n```\n\nDo not rely on CI to create missing derivatives. Missing generated media is a defect.\n\n## Build and Publish Expectations\n\nThe website build and deployment flow is set up around this behavior:\n\n- Local development pulls Git LFS objects before serving the site.\n- The local dev workflow runs the image watcher during `npm run dev`.\n- CI restores and pulls Git LFS objects before building the site.\n- CI validates that raster source images have generated WebP derivatives.\n- The shared head template fails the Hugo build if the committed social preview PNG is missing or is not `1200x630`.\n- CI uploads `website/public` as a short-lived artifact after the build.\n- The deploy job publishes `website/public` to Cloudflare Pages.\n\nThe project scripts that matter most here are:\n\n- `npm run images:generate`\n- `npm run images:validate`\n- `npm run social:generate`\n- `npm run build`\n\nThe workflow lives in `.github/workflows/website-deploy.yml`. The important steps include:\n\n- restore `.git/lfs` cache and run `git lfs pull`\n- restore `website/resources/_gen` cache for faster rebuilds\n- validate generated WebP coverage\n- build the Hugo site and Pagefind index inside `website/`\n- upload `website/public` as a short-lived artifact\n- deploy the built site from `website/public`\n\nFor the Cloudflare-side setup, GitHub Actions secrets, and deployment branch rules, see [Set Up Cloudflare Pages Publishing](../../setup-and-operations/set-up-cloudflare-pages-publishing/).\n", "1.0": "+++\ntitle = \"Media Publishing Workflow\"\n+++\n\nThe website media workflow is repository-driven. The source files and the generated derivatives both belong in the repo.\n\n## Goals\n\n- Source images are committed in the repository.\n- Pre-generated WebP derivatives are committed in the repository.\n- The committed social preview PNG is generated locally and committed in the repository.\n- Source images and generated derivatives are tracked with Git LFS.\n- Every raster source image has generated WebP derivatives.\n- Local development and CI pull media from Git LFS before building.\n- CI publishes built media from `website/public` rather than generating missing derivatives during deployment.\n\n## Required Tools\n\nYou need:\n\n- `git-lfs`\n- ImageMagick's `magick` command when generating derivatives locally\n\nAfter cloning, pull LFS objects before you work on the site:\n\n```bash\ngit lfs pull\n```\n\nIf the LFS objects are missing, a site build may appear to work while still producing broken image references or missing derivatives.\n\n## Source of Truth\n\nThe source of truth for website media is the checked-in asset tree:\n\n- `website/assets/images/` for source images and generated WebPs\n- `website/assets/images/` for source images and committed generated derivatives, including WebPs and the social preview PNG\n- `website/static/files/` for downloadable files\n\nHugo's cached outputs under `website/resources/_gen/images/` are build artifacts, not source content and not committed media.\n\nGenerated derivatives live in a sibling `generated/` directory next to the source image.\n\nExample:\n\n```text\nwebsite/assets/images/home/companion-screenshot.png\nwebsite/assets/images/home/generated/companion-screenshot_372w.webp\nwebsite/assets/images/home/generated/companion-screenshot_500w.webp\nwebsite/assets/images/home/generated/sambee-screenshot_1200w.png\n```\n\n## Authoring Workflow\n\nWhen you add or change a raster image:\n\n1. Add or update the source file under `website/assets/images/`.\n2. Start the website preview task or run `npm run dev`.\n3. Let the local watcher regenerate missing derivatives automatically, or generate them manually.\n4. Review the generated files in the matching `generated/` directory.\n5. Commit the source image and the generated derivatives together.\n\nThe local watcher covers two cases:\n\n- For ordinary raster images, it regenerates the matching WebP derivatives.\n- For `website/assets/images/home/sambee-screenshot.png`, it also regenerates the committed social preview PNG at `website/assets/images/home/generated/sambee-screenshot_1200w.png`.\n\nManual batch generation:\n\n```bash\ncd website\nnpm run images:generate\n```\n\nManual social preview generation:\n\n```bash\ncd website\nnpm run social:generate\n```\n\nDo not rely on CI to create missing derivatives. Missing generated media is a defect.\n\n## Build and Publish Expectations\n\nThe website build and deployment flow is set up around this behavior:\n\n- Local development pulls Git LFS objects before serving the site.\n- The local dev workflow runs the image watcher during `npm run dev`.\n- CI restores and pulls Git LFS objects before building the site.\n- CI validates that raster source images have generated WebP derivatives.\n- The shared head template fails the Hugo build if the committed social preview PNG is missing or is not `1200x630`.\n- CI uploads `website/public` as a short-lived artifact after the build.\n- The deploy job publishes `website/public` to Cloudflare Pages.\n\nThe project scripts that matter most here are:\n\n- `npm run images:generate`\n- `npm run images:validate`\n- `npm run social:generate`\n- `npm run build`\n\nThe workflow lives in `.github/workflows/website-deploy.yml`. The important steps include:\n\n- restore `.git/lfs` cache and run `git lfs pull`\n- restore `website/resources/_gen` cache for faster rebuilds\n- validate generated WebP coverage\n- build the Hugo site and Pagefind index inside `website/`\n- upload `website/public` as a short-lived artifact\n- deploy the built site from `website/public`\n\nFor the Cloudflare-side setup, GitHub Actions secrets, and deployment branch rules, see [Set Up Cloudflare Pages Publishing](../../setup-and-operations/set-up-cloudflare-pages-publishing/).\n", "2.0": "+++\ntitle = \"Media Publishing Workflow\"\n+++\n\nThe website media workflow is repository-driven. The source files and the generated derivatives both belong in the repo.\n\n## Goals\n\n- Source images are committed in the repository.\n- Pre-generated WebP derivatives are committed in the repository.\n- The committed social preview PNG is generated locally and committed in the repository.\n- Source images and generated derivatives are tracked with Git LFS.\n- Every raster source image has generated WebP derivatives.\n- Local development and CI pull media from Git LFS before building.\n- CI publishes built media from `website/public` rather than generating missing derivatives during deployment.\n\n## Required Tools\n\nYou need:\n\n- `git-lfs`\n- ImageMagick's `magick` command when generating derivatives locally\n\nAfter cloning, pull LFS objects before you work on the site:\n\n```bash\ngit lfs pull\n```\n\nIf the LFS objects are missing, a site build may appear to work while still producing broken image references or missing derivatives.\n\n## Source of Truth\n\nThe source of truth for website media is the checked-in asset tree:\n\n- `website/assets/images/` for source images and generated WebPs\n- `website/assets/images/` for source images and committed generated derivatives, including WebPs and the social preview PNG\n- `website/static/files/` for downloadable files\n\nHugo's cached outputs under `website/resources/_gen/images/` are build artifacts, not source content and not committed media.\n\nGenerated derivatives live in a sibling `generated/` directory next to the source image.\n\nExample:\n\n```text\nwebsite/assets/images/home/companion-screenshot.png\nwebsite/assets/images/home/generated/companion-screenshot_372w.webp\nwebsite/assets/images/home/generated/companion-screenshot_500w.webp\nwebsite/assets/images/home/generated/sambee-screenshot_1200w.png\n```\n\n## Authoring Workflow\n\nWhen you add or change a raster image:\n\n1. Add or update the source file under `website/assets/images/`.\n2. Start the website preview task or run `npm run dev`.\n3. Let the local watcher regenerate missing derivatives automatically, or generate them manually.\n4. Review the generated files in the matching `generated/` directory.\n5. Commit the source image and the generated derivatives together.\n\nThe local watcher covers two cases:\n\n- For ordinary raster images, it regenerates the matching WebP derivatives.\n- For `website/assets/images/home/sambee-screenshot.png`, it also regenerates the committed social preview PNG at `website/assets/images/home/generated/sambee-screenshot_1200w.png`.\n\nManual batch generation:\n\n```bash\ncd website\nnpm run images:generate\n```\n\nManual social preview generation:\n\n```bash\ncd website\nnpm run social:generate\n```\n\nDo not rely on CI to create missing derivatives. Missing generated media is a defect.\n\n## Build and Publish Expectations\n\nThe website build and deployment flow is set up around this behavior:\n\n- Local development pulls Git LFS objects before serving the site.\n- The local dev workflow runs the image watcher during `npm run dev`.\n- CI restores and pulls Git LFS objects before building the site.\n- CI validates that raster source images have generated WebP derivatives.\n- The shared head template fails the Hugo build if the committed social preview PNG is missing or is not `1200x630`.\n- CI uploads `website/public` as a short-lived artifact after the build.\n- The deploy job publishes `website/public` to Cloudflare Pages.\n\nThe project scripts that matter most here are:\n\n- `npm run images:generate`\n- `npm run images:validate`\n- `npm run social:generate`\n- `npm run build`\n\nThe workflow lives in `.github/workflows/website-deploy.yml`. The important steps include:\n\n- restore `.git/lfs` cache and run `git lfs pull`\n- restore `website/resources/_gen` cache for faster rebuilds\n- validate generated WebP coverage\n- build the Hugo site and Pagefind index inside `website/`\n- upload `website/public` as a short-lived artifact\n- deploy the built site from `website/public`\n\nFor the Cloudflare-side setup, GitHub Actions secrets, and deployment branch rules, see [Set Up Cloudflare Pages Publishing](../../setup-and-operations/set-up-cloudflare-pages-publishing/).\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:website-dev-guide/site-systems/typography-system", "parent_id": "section:website-dev-guide/site-systems", "depth": 2, "kind": "page", "label": "typography-system", "title": "Typography System", "path": "website-dev-guide/site-systems/typography-system", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Typography System\"\n+++\n\nThis page documents the current typography architecture for the Hugo website theme under `website/themes/sambee`.\n\nIt is a reference for the live system, not a planning note.\n\n## Current Architecture\n\nThe shared typography system has two layers:\n\n1. a token layer in `@theme` in `website/themes/sambee/assets/css/main.css`\n2. a recipe layer in `@utility` in `website/themes/sambee/assets/css/shared.css`\n\nRules of the current implementation:\n\n- `@theme` owns reusable type scale, tracking, and leading values that should be available as Tailwind-native tokens\n- `@utility` owns repeated semantic text roles used across templates\n- each semantic recipe is complete on its own\n- templates apply one semantic `type-*` utility per text role\n- color, spacing, layout, and interaction state remain separate concerns\n- component-local CSS may keep typography local when the role is specific to one component, but it should consume shared tokens where that keeps the site scale aligned\n\n## Shared Token Layer\n\nThe current shared typography token block in `website/themes/sambee/assets/css/main.css` is:\n\n```css\n@theme {\n  --text-copy: var(--font-size-copy-base);\n  --text-label-xs: var(--font-size-label-xs);\n  --text-label-sm: var(--font-size-label-sm);\n  --text-list-item-label: var(--font-size-label-sm);\n  --text-list-index: var(--font-size-copy-sm);\n  --text-list-item-title: var(--font-size-copy-sm);\n  --text-docs-nav: var(--font-size-copy-sm);\n  --text-title-sm: 1.125rem;\n  --text-title-md: 1.5rem;\n  --text-title-xl: 2rem;\n  --text-hero-subtitle: 1.6rem;\n  --text-hero-sm: 2.85rem;\n  --text-hero-md: 3.55rem;\n\n  --tracking-label: 0.1em;\n  --tracking-label-strong: 0.14em;\n  --tracking-eyebrow: 0.22em;\n  --tracking-eyebrow-strong: 0.18em;\n  --tracking-list-item-label: 0.1em;\n  --tracking-hero-subtitle: -0.1rem;\n\n  --leading-copy: 1.625rem;\n  --leading-docs-nav: 1.375;\n  --leading-eyebrow: 1;\n  --leading-title-md: 1.2;\n}\n```\n\nSupporting primitives still come from the shared base and generated theme layers, including:\n\n- `--font-primary`, `--font-secondary`, and `--font-tertiary`\n- `--line-height-heading-tight`\n- `--line-height-copy-base`\n- `--tracking-tight`\n- `--text-4xl`, `--text-5xl`, and `--text-7xl`\n\nNotes:\n\n- `--text-docs-nav` and `--leading-docs-nav` are part of the shared scale because the docs interface reuses the same text role in multiple places\n- hero sizing still combines local tokens with the larger text tokens already exposed by the theme\n- values belong in `@theme` only when they are part of the shared site scale or reused across roles\n\n## Shared Recipe Layer\n\nThe current shared semantic typography utilities are:\n\n- `type-section-title`\n- `type-copy`\n- `type-label-sm`\n- `type-label-strong`\n- `type-label-eyebrow`\n- `type-label-eyebrow-strong`\n- `type-label-xs`\n- `type-list-item-label`\n- `type-list-item-title`\n- `type-docs-nav`\n- `type-hero`\n- `type-title-xl`\n- `type-hero-subtitle`\n- `type-title-md`\n- `type-title-md-tight`\n- `type-title-sm-tight`\n- `type-list-index`\n\nThese utilities are intended to be complete on their own. Do not stack two semantic typography utilities that both set font metrics.\n\nThe current system intentionally does not include:\n\n- `type-label` as a partial base class\n- `type-docs-nav-strong` as a separate semantic utility\n\nDocs current-item emphasis is handled by `type-docs-nav` plus local state styling such as color, weight, and surface treatment.\n\n## Usage and Boundaries\n\nThe detailed usage examples, intentionally absent patterns, and component-boundary rules now live on a separate page so this overview can stay focused on the shared system itself.\n\nContinue to [Typography Usage and Boundaries](../typography-usage-and-boundaries/) for:\n\n- representative `@utility` definitions\n- template usage examples\n- current-item emphasis rules for docs navigation\n- component-local versus shared typography boundaries\n- intentionally absent patterns that should not be reintroduced\n\n## Guardrails\n\nUse these rules for future typography work:\n\n1. use plain Tailwind utilities for one-off cases\n2. add a shared `type-*` utility only when the same semantic role appears in multiple templates\n3. keep each shared utility complete on its own\n4. keep layout, spacing, color, and interaction state outside the semantic typography utility unless the role truly requires them\n5. when a component-local class needs a shared scale value, consume the shared tokens instead of copying magic numbers\n", "0.8": "+++\ntitle = \"Typography System\"\n+++\n\nThis page documents the current typography architecture for the Hugo website theme under `website/themes/sambee`.\n\nIt is a reference for the live system, not a planning note.\n\n## Current Architecture\n\nThe shared typography system has two layers:\n\n1. a token layer in `@theme` in `website/themes/sambee/assets/css/main.css`\n2. a recipe layer in `@utility` in `website/themes/sambee/assets/css/shared.css`\n\nRules of the current implementation:\n\n- `@theme` owns reusable type scale, tracking, and leading values that should be available as Tailwind-native tokens\n- `@utility` owns repeated semantic text roles used across templates\n- each semantic recipe is complete on its own\n- templates apply one semantic `type-*` utility per text role\n- color, spacing, layout, and interaction state remain separate concerns\n- component-local CSS may keep typography local when the role is specific to one component, but it should consume shared tokens where that keeps the site scale aligned\n\n## Shared Token Layer\n\nThe current shared typography token block in `website/themes/sambee/assets/css/main.css` is:\n\n```css\n@theme {\n  --text-copy: var(--font-size-copy-base);\n  --text-label-xs: var(--font-size-label-xs);\n  --text-label-sm: var(--font-size-label-sm);\n  --text-list-item-label: var(--font-size-label-sm);\n  --text-list-index: var(--font-size-copy-sm);\n  --text-list-item-title: var(--font-size-copy-sm);\n  --text-docs-nav: var(--font-size-copy-sm);\n  --text-title-sm: 1.125rem;\n  --text-title-md: 1.5rem;\n  --text-title-xl: 2rem;\n  --text-hero-subtitle: 1.6rem;\n  --text-hero-sm: 2.85rem;\n  --text-hero-md: 3.55rem;\n\n  --tracking-label: 0.1em;\n  --tracking-label-strong: 0.14em;\n  --tracking-eyebrow: 0.22em;\n  --tracking-eyebrow-strong: 0.18em;\n  --tracking-list-item-label: 0.1em;\n  --tracking-hero-subtitle: -0.1rem;\n\n  --leading-copy: 1.625rem;\n  --leading-docs-nav: 1.375;\n  --leading-eyebrow: 1;\n  --leading-title-md: 1.2;\n}\n```\n\nSupporting primitives still come from the shared base and generated theme layers, including:\n\n- `--font-primary`, `--font-secondary`, and `--font-tertiary`\n- `--line-height-heading-tight`\n- `--line-height-copy-base`\n- `--tracking-tight`\n- `--text-4xl`, `--text-5xl`, and `--text-7xl`\n\nNotes:\n\n- `--text-docs-nav` and `--leading-docs-nav` are part of the shared scale because the docs interface reuses the same text role in multiple places\n- hero sizing still combines local tokens with the larger text tokens already exposed by the theme\n- values belong in `@theme` only when they are part of the shared site scale or reused across roles\n\n## Shared Recipe Layer\n\nThe current shared semantic typography utilities are:\n\n- `type-section-title`\n- `type-copy`\n- `type-label-sm`\n- `type-label-strong`\n- `type-label-eyebrow`\n- `type-label-eyebrow-strong`\n- `type-label-xs`\n- `type-list-item-label`\n- `type-list-item-title`\n- `type-docs-nav`\n- `type-hero`\n- `type-title-xl`\n- `type-hero-subtitle`\n- `type-title-md`\n- `type-title-md-tight`\n- `type-title-sm-tight`\n- `type-list-index`\n\nThese utilities are intended to be complete on their own. Do not stack two semantic typography utilities that both set font metrics.\n\nThe current system intentionally does not include:\n\n- `type-label` as a partial base class\n- `type-docs-nav-strong` as a separate semantic utility\n\nDocs current-item emphasis is handled by `type-docs-nav` plus local state styling such as color, weight, and surface treatment.\n\n## Usage and Boundaries\n\nThe detailed usage examples, intentionally absent patterns, and component-boundary rules now live on a separate page so this overview can stay focused on the shared system itself.\n\nContinue to [Typography Usage and Boundaries](../typography-usage-and-boundaries/) for:\n\n- representative `@utility` definitions\n- template usage examples\n- current-item emphasis rules for docs navigation\n- component-local versus shared typography boundaries\n- intentionally absent patterns that should not be reintroduced\n\n## Guardrails\n\nUse these rules for future typography work:\n\n1. use plain Tailwind utilities for one-off cases\n2. add a shared `type-*` utility only when the same semantic role appears in multiple templates\n3. keep each shared utility complete on its own\n4. keep layout, spacing, color, and interaction state outside the semantic typography utility unless the role truly requires them\n5. when a component-local class needs a shared scale value, consume the shared tokens instead of copying magic numbers\n", "0.9": "+++\ntitle = \"Typography System\"\n+++\n\nThis page documents the current typography architecture for the Hugo website theme under `website/themes/sambee`.\n\nIt is a reference for the live system, not a planning note.\n\n## Current Architecture\n\nThe shared typography system has two layers:\n\n1. a token layer in `@theme` in `website/themes/sambee/assets/css/main.css`\n2. a recipe layer in `@utility` in `website/themes/sambee/assets/css/shared.css`\n\nRules of the current implementation:\n\n- `@theme` owns reusable type scale, tracking, and leading values that should be available as Tailwind-native tokens\n- `@utility` owns repeated semantic text roles used across templates\n- each semantic recipe is complete on its own\n- templates apply one semantic `type-*` utility per text role\n- color, spacing, layout, and interaction state remain separate concerns\n- component-local CSS may keep typography local when the role is specific to one component, but it should consume shared tokens where that keeps the site scale aligned\n\n## Shared Token Layer\n\nThe current shared typography token block in `website/themes/sambee/assets/css/main.css` is:\n\n```css\n@theme {\n  --text-copy: var(--font-size-copy-base);\n  --text-label-xs: var(--font-size-label-xs);\n  --text-label-sm: var(--font-size-label-sm);\n  --text-list-item-label: var(--font-size-label-sm);\n  --text-list-index: var(--font-size-copy-sm);\n  --text-list-item-title: var(--font-size-copy-sm);\n  --text-docs-nav: var(--font-size-copy-sm);\n  --text-title-sm: 1.125rem;\n  --text-title-md: 1.5rem;\n  --text-title-xl: 2rem;\n  --text-hero-subtitle: 1.6rem;\n  --text-hero-sm: 2.85rem;\n  --text-hero-md: 3.55rem;\n\n  --tracking-label: 0.1em;\n  --tracking-label-strong: 0.14em;\n  --tracking-eyebrow: 0.22em;\n  --tracking-eyebrow-strong: 0.18em;\n  --tracking-list-item-label: 0.1em;\n  --tracking-hero-subtitle: -0.1rem;\n\n  --leading-copy: 1.625rem;\n  --leading-docs-nav: 1.375;\n  --leading-eyebrow: 1;\n  --leading-title-md: 1.2;\n}\n```\n\nSupporting primitives still come from the shared base and generated theme layers, including:\n\n- `--font-primary`, `--font-secondary`, and `--font-tertiary`\n- `--line-height-heading-tight`\n- `--line-height-copy-base`\n- `--tracking-tight`\n- `--text-4xl`, `--text-5xl`, and `--text-7xl`\n\nNotes:\n\n- `--text-docs-nav` and `--leading-docs-nav` are part of the shared scale because the docs interface reuses the same text role in multiple places\n- hero sizing still combines local tokens with the larger text tokens already exposed by the theme\n- values belong in `@theme` only when they are part of the shared site scale or reused across roles\n\n## Shared Recipe Layer\n\nThe current shared semantic typography utilities are:\n\n- `type-section-title`\n- `type-copy`\n- `type-label-sm`\n- `type-label-strong`\n- `type-label-eyebrow`\n- `type-label-eyebrow-strong`\n- `type-label-xs`\n- `type-list-item-label`\n- `type-list-item-title`\n- `type-docs-nav`\n- `type-hero`\n- `type-title-xl`\n- `type-hero-subtitle`\n- `type-title-md`\n- `type-title-md-tight`\n- `type-title-sm-tight`\n- `type-list-index`\n\nThese utilities are intended to be complete on their own. Do not stack two semantic typography utilities that both set font metrics.\n\nThe current system intentionally does not include:\n\n- `type-label` as a partial base class\n- `type-docs-nav-strong` as a separate semantic utility\n\nDocs current-item emphasis is handled by `type-docs-nav` plus local state styling such as color, weight, and surface treatment.\n\n## Usage and Boundaries\n\nThe detailed usage examples, intentionally absent patterns, and component-boundary rules now live on a separate page so this overview can stay focused on the shared system itself.\n\nContinue to [Typography Usage and Boundaries](../typography-usage-and-boundaries/) for:\n\n- representative `@utility` definitions\n- template usage examples\n- current-item emphasis rules for docs navigation\n- component-local versus shared typography boundaries\n- intentionally absent patterns that should not be reintroduced\n\n## Guardrails\n\nUse these rules for future typography work:\n\n1. use plain Tailwind utilities for one-off cases\n2. add a shared `type-*` utility only when the same semantic role appears in multiple templates\n3. keep each shared utility complete on its own\n4. keep layout, spacing, color, and interaction state outside the semantic typography utility unless the role truly requires them\n5. when a component-local class needs a shared scale value, consume the shared tokens instead of copying magic numbers\n", "1.0": "+++\ntitle = \"Typography System\"\n+++\n\nThis page documents the current typography architecture for the Hugo website theme under `website/themes/sambee`.\n\nIt is a reference for the live system, not a planning note.\n\n## Current Architecture\n\nThe shared typography system has two layers:\n\n1. a token layer in `@theme` in `website/themes/sambee/assets/css/main.css`\n2. a recipe layer in `@utility` in `website/themes/sambee/assets/css/shared.css`\n\nRules of the current implementation:\n\n- `@theme` owns reusable type scale, tracking, and leading values that should be available as Tailwind-native tokens\n- `@utility` owns repeated semantic text roles used across templates\n- each semantic recipe is complete on its own\n- templates apply one semantic `type-*` utility per text role\n- color, spacing, layout, and interaction state remain separate concerns\n- component-local CSS may keep typography local when the role is specific to one component, but it should consume shared tokens where that keeps the site scale aligned\n\n## Shared Token Layer\n\nThe current shared typography token block in `website/themes/sambee/assets/css/main.css` is:\n\n```css\n@theme {\n  --text-copy: var(--font-size-copy-base);\n  --text-label-xs: var(--font-size-label-xs);\n  --text-label-sm: var(--font-size-label-sm);\n  --text-list-item-label: var(--font-size-label-sm);\n  --text-list-index: var(--font-size-copy-sm);\n  --text-list-item-title: var(--font-size-copy-sm);\n  --text-docs-nav: var(--font-size-copy-sm);\n  --text-title-sm: 1.125rem;\n  --text-title-md: 1.5rem;\n  --text-title-xl: 2rem;\n  --text-hero-subtitle: 1.6rem;\n  --text-hero-sm: 2.85rem;\n  --text-hero-md: 3.55rem;\n\n  --tracking-label: 0.1em;\n  --tracking-label-strong: 0.14em;\n  --tracking-eyebrow: 0.22em;\n  --tracking-eyebrow-strong: 0.18em;\n  --tracking-list-item-label: 0.1em;\n  --tracking-hero-subtitle: -0.1rem;\n\n  --leading-copy: 1.625rem;\n  --leading-docs-nav: 1.375;\n  --leading-eyebrow: 1;\n  --leading-title-md: 1.2;\n}\n```\n\nSupporting primitives still come from the shared base and generated theme layers, including:\n\n- `--font-primary`, `--font-secondary`, and `--font-tertiary`\n- `--line-height-heading-tight`\n- `--line-height-copy-base`\n- `--tracking-tight`\n- `--text-4xl`, `--text-5xl`, and `--text-7xl`\n\nNotes:\n\n- `--text-docs-nav` and `--leading-docs-nav` are part of the shared scale because the docs interface reuses the same text role in multiple places\n- hero sizing still combines local tokens with the larger text tokens already exposed by the theme\n- values belong in `@theme` only when they are part of the shared site scale or reused across roles\n\n## Shared Recipe Layer\n\nThe current shared semantic typography utilities are:\n\n- `type-section-title`\n- `type-copy`\n- `type-label-sm`\n- `type-label-strong`\n- `type-label-eyebrow`\n- `type-label-eyebrow-strong`\n- `type-label-xs`\n- `type-list-item-label`\n- `type-list-item-title`\n- `type-docs-nav`\n- `type-hero`\n- `type-title-xl`\n- `type-hero-subtitle`\n- `type-title-md`\n- `type-title-md-tight`\n- `type-title-sm-tight`\n- `type-list-index`\n\nThese utilities are intended to be complete on their own. Do not stack two semantic typography utilities that both set font metrics.\n\nThe current system intentionally does not include:\n\n- `type-label` as a partial base class\n- `type-docs-nav-strong` as a separate semantic utility\n\nDocs current-item emphasis is handled by `type-docs-nav` plus local state styling such as color, weight, and surface treatment.\n\n## Usage and Boundaries\n\nThe detailed usage examples, intentionally absent patterns, and component-boundary rules now live on a separate page so this overview can stay focused on the shared system itself.\n\nContinue to [Typography Usage and Boundaries](../typography-usage-and-boundaries/) for:\n\n- representative `@utility` definitions\n- template usage examples\n- current-item emphasis rules for docs navigation\n- component-local versus shared typography boundaries\n- intentionally absent patterns that should not be reintroduced\n\n## Guardrails\n\nUse these rules for future typography work:\n\n1. use plain Tailwind utilities for one-off cases\n2. add a shared `type-*` utility only when the same semantic role appears in multiple templates\n3. keep each shared utility complete on its own\n4. keep layout, spacing, color, and interaction state outside the semantic typography utility unless the role truly requires them\n5. when a component-local class needs a shared scale value, consume the shared tokens instead of copying magic numbers\n", "2.0": "+++\ntitle = \"Typography System\"\n+++\n\nThis page documents the current typography architecture for the Hugo website theme under `website/themes/sambee`.\n\nIt is a reference for the live system, not a planning note.\n\n## Current Architecture\n\nThe shared typography system has two layers:\n\n1. a token layer in `@theme` in `website/themes/sambee/assets/css/main.css`\n2. a recipe layer in `@utility` in `website/themes/sambee/assets/css/shared.css`\n\nRules of the current implementation:\n\n- `@theme` owns reusable type scale, tracking, and leading values that should be available as Tailwind-native tokens\n- `@utility` owns repeated semantic text roles used across templates\n- each semantic recipe is complete on its own\n- templates apply one semantic `type-*` utility per text role\n- color, spacing, layout, and interaction state remain separate concerns\n- component-local CSS may keep typography local when the role is specific to one component, but it should consume shared tokens where that keeps the site scale aligned\n\n## Shared Token Layer\n\nThe current shared typography token block in `website/themes/sambee/assets/css/main.css` is:\n\n```css\n@theme {\n  --text-copy: var(--font-size-copy-base);\n  --text-label-xs: var(--font-size-label-xs);\n  --text-label-sm: var(--font-size-label-sm);\n  --text-list-item-label: var(--font-size-label-sm);\n  --text-list-index: var(--font-size-copy-sm);\n  --text-list-item-title: var(--font-size-copy-sm);\n  --text-docs-nav: var(--font-size-copy-sm);\n  --text-title-sm: 1.125rem;\n  --text-title-md: 1.5rem;\n  --text-title-xl: 2rem;\n  --text-hero-subtitle: 1.6rem;\n  --text-hero-sm: 2.85rem;\n  --text-hero-md: 3.55rem;\n\n  --tracking-label: 0.1em;\n  --tracking-label-strong: 0.14em;\n  --tracking-eyebrow: 0.22em;\n  --tracking-eyebrow-strong: 0.18em;\n  --tracking-list-item-label: 0.1em;\n  --tracking-hero-subtitle: -0.1rem;\n\n  --leading-copy: 1.625rem;\n  --leading-docs-nav: 1.375;\n  --leading-eyebrow: 1;\n  --leading-title-md: 1.2;\n}\n```\n\nSupporting primitives still come from the shared base and generated theme layers, including:\n\n- `--font-primary`, `--font-secondary`, and `--font-tertiary`\n- `--line-height-heading-tight`\n- `--line-height-copy-base`\n- `--tracking-tight`\n- `--text-4xl`, `--text-5xl`, and `--text-7xl`\n\nNotes:\n\n- `--text-docs-nav` and `--leading-docs-nav` are part of the shared scale because the docs interface reuses the same text role in multiple places\n- hero sizing still combines local tokens with the larger text tokens already exposed by the theme\n- values belong in `@theme` only when they are part of the shared site scale or reused across roles\n\n## Shared Recipe Layer\n\nThe current shared semantic typography utilities are:\n\n- `type-section-title`\n- `type-copy`\n- `type-label-sm`\n- `type-label-strong`\n- `type-label-eyebrow`\n- `type-label-eyebrow-strong`\n- `type-label-xs`\n- `type-list-item-label`\n- `type-list-item-title`\n- `type-docs-nav`\n- `type-hero`\n- `type-title-xl`\n- `type-hero-subtitle`\n- `type-title-md`\n- `type-title-md-tight`\n- `type-title-sm-tight`\n- `type-list-index`\n\nThese utilities are intended to be complete on their own. Do not stack two semantic typography utilities that both set font metrics.\n\nThe current system intentionally does not include:\n\n- `type-label` as a partial base class\n- `type-docs-nav-strong` as a separate semantic utility\n\nDocs current-item emphasis is handled by `type-docs-nav` plus local state styling such as color, weight, and surface treatment.\n\n## Usage and Boundaries\n\nThe detailed usage examples, intentionally absent patterns, and component-boundary rules now live on a separate page so this overview can stay focused on the shared system itself.\n\nContinue to [Typography Usage and Boundaries](../typography-usage-and-boundaries/) for:\n\n- representative `@utility` definitions\n- template usage examples\n- current-item emphasis rules for docs navigation\n- component-local versus shared typography boundaries\n- intentionally absent patterns that should not be reintroduced\n\n## Guardrails\n\nUse these rules for future typography work:\n\n1. use plain Tailwind utilities for one-off cases\n2. add a shared `type-*` utility only when the same semantic role appears in multiple templates\n3. keep each shared utility complete on its own\n4. keep layout, spacing, color, and interaction state outside the semantic typography utility unless the role truly requires them\n5. when a component-local class needs a shared scale value, consume the shared tokens instead of copying magic numbers\n"}, "page_contents": {"0.7": "+++\ntitle = \"Typography System\"\n+++\n\nThis page documents the current typography architecture for the Hugo website theme under `website/themes/sambee`.\n\nIt is a reference for the live system, not a planning note.\n\n## Current Architecture\n\nThe shared typography system has two layers:\n\n1. a token layer in `@theme` in `website/themes/sambee/assets/css/main.css`\n2. a recipe layer in `@utility` in `website/themes/sambee/assets/css/shared.css`\n\nRules of the current implementation:\n\n- `@theme` owns reusable type scale, tracking, and leading values that should be available as Tailwind-native tokens\n- `@utility` owns repeated semantic text roles used across templates\n- each semantic recipe is complete on its own\n- templates apply one semantic `type-*` utility per text role\n- color, spacing, layout, and interaction state remain separate concerns\n- component-local CSS may keep typography local when the role is specific to one component, but it should consume shared tokens where that keeps the site scale aligned\n\n## Shared Token Layer\n\nThe current shared typography token block in `website/themes/sambee/assets/css/main.css` is:\n\n```css\n@theme {\n  --text-copy: var(--font-size-copy-base);\n  --text-label-xs: var(--font-size-label-xs);\n  --text-label-sm: var(--font-size-label-sm);\n  --text-list-item-label: var(--font-size-label-sm);\n  --text-list-index: var(--font-size-copy-sm);\n  --text-list-item-title: var(--font-size-copy-sm);\n  --text-docs-nav: var(--font-size-copy-sm);\n  --text-title-sm: 1.125rem;\n  --text-title-md: 1.5rem;\n  --text-title-xl: 2rem;\n  --text-hero-subtitle: 1.6rem;\n  --text-hero-sm: 2.85rem;\n  --text-hero-md: 3.55rem;\n\n  --tracking-label: 0.1em;\n  --tracking-label-strong: 0.14em;\n  --tracking-eyebrow: 0.22em;\n  --tracking-eyebrow-strong: 0.18em;\n  --tracking-list-item-label: 0.1em;\n  --tracking-hero-subtitle: -0.1rem;\n\n  --leading-copy: 1.625rem;\n  --leading-docs-nav: 1.375;\n  --leading-eyebrow: 1;\n  --leading-title-md: 1.2;\n}\n```\n\nSupporting primitives still come from the shared base and generated theme layers, including:\n\n- `--font-primary`, `--font-secondary`, and `--font-tertiary`\n- `--line-height-heading-tight`\n- `--line-height-copy-base`\n- `--tracking-tight`\n- `--text-4xl`, `--text-5xl`, and `--text-7xl`\n\nNotes:\n\n- `--text-docs-nav` and `--leading-docs-nav` are part of the shared scale because the docs interface reuses the same text role in multiple places\n- hero sizing still combines local tokens with the larger text tokens already exposed by the theme\n- values belong in `@theme` only when they are part of the shared site scale or reused across roles\n\n## Shared Recipe Layer\n\nThe current shared semantic typography utilities are:\n\n- `type-section-title`\n- `type-copy`\n- `type-label-sm`\n- `type-label-strong`\n- `type-label-eyebrow`\n- `type-label-eyebrow-strong`\n- `type-label-xs`\n- `type-list-item-label`\n- `type-list-item-title`\n- `type-docs-nav`\n- `type-hero`\n- `type-title-xl`\n- `type-hero-subtitle`\n- `type-title-md`\n- `type-title-md-tight`\n- `type-title-sm-tight`\n- `type-list-index`\n\nThese utilities are intended to be complete on their own. Do not stack two semantic typography utilities that both set font metrics.\n\nThe current system intentionally does not include:\n\n- `type-label` as a partial base class\n- `type-docs-nav-strong` as a separate semantic utility\n\nDocs current-item emphasis is handled by `type-docs-nav` plus local state styling such as color, weight, and surface treatment.\n\n## Usage and Boundaries\n\nThe detailed usage examples, intentionally absent patterns, and component-boundary rules now live on a separate page so this overview can stay focused on the shared system itself.\n\nContinue to [Typography Usage and Boundaries](../typography-usage-and-boundaries/) for:\n\n- representative `@utility` definitions\n- template usage examples\n- current-item emphasis rules for docs navigation\n- component-local versus shared typography boundaries\n- intentionally absent patterns that should not be reintroduced\n\n## Guardrails\n\nUse these rules for future typography work:\n\n1. use plain Tailwind utilities for one-off cases\n2. add a shared `type-*` utility only when the same semantic role appears in multiple templates\n3. keep each shared utility complete on its own\n4. keep layout, spacing, color, and interaction state outside the semantic typography utility unless the role truly requires them\n5. when a component-local class needs a shared scale value, consume the shared tokens instead of copying magic numbers\n", "0.8": "+++\ntitle = \"Typography System\"\n+++\n\nThis page documents the current typography architecture for the Hugo website theme under `website/themes/sambee`.\n\nIt is a reference for the live system, not a planning note.\n\n## Current Architecture\n\nThe shared typography system has two layers:\n\n1. a token layer in `@theme` in `website/themes/sambee/assets/css/main.css`\n2. a recipe layer in `@utility` in `website/themes/sambee/assets/css/shared.css`\n\nRules of the current implementation:\n\n- `@theme` owns reusable type scale, tracking, and leading values that should be available as Tailwind-native tokens\n- `@utility` owns repeated semantic text roles used across templates\n- each semantic recipe is complete on its own\n- templates apply one semantic `type-*` utility per text role\n- color, spacing, layout, and interaction state remain separate concerns\n- component-local CSS may keep typography local when the role is specific to one component, but it should consume shared tokens where that keeps the site scale aligned\n\n## Shared Token Layer\n\nThe current shared typography token block in `website/themes/sambee/assets/css/main.css` is:\n\n```css\n@theme {\n  --text-copy: var(--font-size-copy-base);\n  --text-label-xs: var(--font-size-label-xs);\n  --text-label-sm: var(--font-size-label-sm);\n  --text-list-item-label: var(--font-size-label-sm);\n  --text-list-index: var(--font-size-copy-sm);\n  --text-list-item-title: var(--font-size-copy-sm);\n  --text-docs-nav: var(--font-size-copy-sm);\n  --text-title-sm: 1.125rem;\n  --text-title-md: 1.5rem;\n  --text-title-xl: 2rem;\n  --text-hero-subtitle: 1.6rem;\n  --text-hero-sm: 2.85rem;\n  --text-hero-md: 3.55rem;\n\n  --tracking-label: 0.1em;\n  --tracking-label-strong: 0.14em;\n  --tracking-eyebrow: 0.22em;\n  --tracking-eyebrow-strong: 0.18em;\n  --tracking-list-item-label: 0.1em;\n  --tracking-hero-subtitle: -0.1rem;\n\n  --leading-copy: 1.625rem;\n  --leading-docs-nav: 1.375;\n  --leading-eyebrow: 1;\n  --leading-title-md: 1.2;\n}\n```\n\nSupporting primitives still come from the shared base and generated theme layers, including:\n\n- `--font-primary`, `--font-secondary`, and `--font-tertiary`\n- `--line-height-heading-tight`\n- `--line-height-copy-base`\n- `--tracking-tight`\n- `--text-4xl`, `--text-5xl`, and `--text-7xl`\n\nNotes:\n\n- `--text-docs-nav` and `--leading-docs-nav` are part of the shared scale because the docs interface reuses the same text role in multiple places\n- hero sizing still combines local tokens with the larger text tokens already exposed by the theme\n- values belong in `@theme` only when they are part of the shared site scale or reused across roles\n\n## Shared Recipe Layer\n\nThe current shared semantic typography utilities are:\n\n- `type-section-title`\n- `type-copy`\n- `type-label-sm`\n- `type-label-strong`\n- `type-label-eyebrow`\n- `type-label-eyebrow-strong`\n- `type-label-xs`\n- `type-list-item-label`\n- `type-list-item-title`\n- `type-docs-nav`\n- `type-hero`\n- `type-title-xl`\n- `type-hero-subtitle`\n- `type-title-md`\n- `type-title-md-tight`\n- `type-title-sm-tight`\n- `type-list-index`\n\nThese utilities are intended to be complete on their own. Do not stack two semantic typography utilities that both set font metrics.\n\nThe current system intentionally does not include:\n\n- `type-label` as a partial base class\n- `type-docs-nav-strong` as a separate semantic utility\n\nDocs current-item emphasis is handled by `type-docs-nav` plus local state styling such as color, weight, and surface treatment.\n\n## Usage and Boundaries\n\nThe detailed usage examples, intentionally absent patterns, and component-boundary rules now live on a separate page so this overview can stay focused on the shared system itself.\n\nContinue to [Typography Usage and Boundaries](../typography-usage-and-boundaries/) for:\n\n- representative `@utility` definitions\n- template usage examples\n- current-item emphasis rules for docs navigation\n- component-local versus shared typography boundaries\n- intentionally absent patterns that should not be reintroduced\n\n## Guardrails\n\nUse these rules for future typography work:\n\n1. use plain Tailwind utilities for one-off cases\n2. add a shared `type-*` utility only when the same semantic role appears in multiple templates\n3. keep each shared utility complete on its own\n4. keep layout, spacing, color, and interaction state outside the semantic typography utility unless the role truly requires them\n5. when a component-local class needs a shared scale value, consume the shared tokens instead of copying magic numbers\n", "0.9": "+++\ntitle = \"Typography System\"\n+++\n\nThis page documents the current typography architecture for the Hugo website theme under `website/themes/sambee`.\n\nIt is a reference for the live system, not a planning note.\n\n## Current Architecture\n\nThe shared typography system has two layers:\n\n1. a token layer in `@theme` in `website/themes/sambee/assets/css/main.css`\n2. a recipe layer in `@utility` in `website/themes/sambee/assets/css/shared.css`\n\nRules of the current implementation:\n\n- `@theme` owns reusable type scale, tracking, and leading values that should be available as Tailwind-native tokens\n- `@utility` owns repeated semantic text roles used across templates\n- each semantic recipe is complete on its own\n- templates apply one semantic `type-*` utility per text role\n- color, spacing, layout, and interaction state remain separate concerns\n- component-local CSS may keep typography local when the role is specific to one component, but it should consume shared tokens where that keeps the site scale aligned\n\n## Shared Token Layer\n\nThe current shared typography token block in `website/themes/sambee/assets/css/main.css` is:\n\n```css\n@theme {\n  --text-copy: var(--font-size-copy-base);\n  --text-label-xs: var(--font-size-label-xs);\n  --text-label-sm: var(--font-size-label-sm);\n  --text-list-item-label: var(--font-size-label-sm);\n  --text-list-index: var(--font-size-copy-sm);\n  --text-list-item-title: var(--font-size-copy-sm);\n  --text-docs-nav: var(--font-size-copy-sm);\n  --text-title-sm: 1.125rem;\n  --text-title-md: 1.5rem;\n  --text-title-xl: 2rem;\n  --text-hero-subtitle: 1.6rem;\n  --text-hero-sm: 2.85rem;\n  --text-hero-md: 3.55rem;\n\n  --tracking-label: 0.1em;\n  --tracking-label-strong: 0.14em;\n  --tracking-eyebrow: 0.22em;\n  --tracking-eyebrow-strong: 0.18em;\n  --tracking-list-item-label: 0.1em;\n  --tracking-hero-subtitle: -0.1rem;\n\n  --leading-copy: 1.625rem;\n  --leading-docs-nav: 1.375;\n  --leading-eyebrow: 1;\n  --leading-title-md: 1.2;\n}\n```\n\nSupporting primitives still come from the shared base and generated theme layers, including:\n\n- `--font-primary`, `--font-secondary`, and `--font-tertiary`\n- `--line-height-heading-tight`\n- `--line-height-copy-base`\n- `--tracking-tight`\n- `--text-4xl`, `--text-5xl`, and `--text-7xl`\n\nNotes:\n\n- `--text-docs-nav` and `--leading-docs-nav` are part of the shared scale because the docs interface reuses the same text role in multiple places\n- hero sizing still combines local tokens with the larger text tokens already exposed by the theme\n- values belong in `@theme` only when they are part of the shared site scale or reused across roles\n\n## Shared Recipe Layer\n\nThe current shared semantic typography utilities are:\n\n- `type-section-title`\n- `type-copy`\n- `type-label-sm`\n- `type-label-strong`\n- `type-label-eyebrow`\n- `type-label-eyebrow-strong`\n- `type-label-xs`\n- `type-list-item-label`\n- `type-list-item-title`\n- `type-docs-nav`\n- `type-hero`\n- `type-title-xl`\n- `type-hero-subtitle`\n- `type-title-md`\n- `type-title-md-tight`\n- `type-title-sm-tight`\n- `type-list-index`\n\nThese utilities are intended to be complete on their own. Do not stack two semantic typography utilities that both set font metrics.\n\nThe current system intentionally does not include:\n\n- `type-label` as a partial base class\n- `type-docs-nav-strong` as a separate semantic utility\n\nDocs current-item emphasis is handled by `type-docs-nav` plus local state styling such as color, weight, and surface treatment.\n\n## Usage and Boundaries\n\nThe detailed usage examples, intentionally absent patterns, and component-boundary rules now live on a separate page so this overview can stay focused on the shared system itself.\n\nContinue to [Typography Usage and Boundaries](../typography-usage-and-boundaries/) for:\n\n- representative `@utility` definitions\n- template usage examples\n- current-item emphasis rules for docs navigation\n- component-local versus shared typography boundaries\n- intentionally absent patterns that should not be reintroduced\n\n## Guardrails\n\nUse these rules for future typography work:\n\n1. use plain Tailwind utilities for one-off cases\n2. add a shared `type-*` utility only when the same semantic role appears in multiple templates\n3. keep each shared utility complete on its own\n4. keep layout, spacing, color, and interaction state outside the semantic typography utility unless the role truly requires them\n5. when a component-local class needs a shared scale value, consume the shared tokens instead of copying magic numbers\n", "1.0": "+++\ntitle = \"Typography System\"\n+++\n\nThis page documents the current typography architecture for the Hugo website theme under `website/themes/sambee`.\n\nIt is a reference for the live system, not a planning note.\n\n## Current Architecture\n\nThe shared typography system has two layers:\n\n1. a token layer in `@theme` in `website/themes/sambee/assets/css/main.css`\n2. a recipe layer in `@utility` in `website/themes/sambee/assets/css/shared.css`\n\nRules of the current implementation:\n\n- `@theme` owns reusable type scale, tracking, and leading values that should be available as Tailwind-native tokens\n- `@utility` owns repeated semantic text roles used across templates\n- each semantic recipe is complete on its own\n- templates apply one semantic `type-*` utility per text role\n- color, spacing, layout, and interaction state remain separate concerns\n- component-local CSS may keep typography local when the role is specific to one component, but it should consume shared tokens where that keeps the site scale aligned\n\n## Shared Token Layer\n\nThe current shared typography token block in `website/themes/sambee/assets/css/main.css` is:\n\n```css\n@theme {\n  --text-copy: var(--font-size-copy-base);\n  --text-label-xs: var(--font-size-label-xs);\n  --text-label-sm: var(--font-size-label-sm);\n  --text-list-item-label: var(--font-size-label-sm);\n  --text-list-index: var(--font-size-copy-sm);\n  --text-list-item-title: var(--font-size-copy-sm);\n  --text-docs-nav: var(--font-size-copy-sm);\n  --text-title-sm: 1.125rem;\n  --text-title-md: 1.5rem;\n  --text-title-xl: 2rem;\n  --text-hero-subtitle: 1.6rem;\n  --text-hero-sm: 2.85rem;\n  --text-hero-md: 3.55rem;\n\n  --tracking-label: 0.1em;\n  --tracking-label-strong: 0.14em;\n  --tracking-eyebrow: 0.22em;\n  --tracking-eyebrow-strong: 0.18em;\n  --tracking-list-item-label: 0.1em;\n  --tracking-hero-subtitle: -0.1rem;\n\n  --leading-copy: 1.625rem;\n  --leading-docs-nav: 1.375;\n  --leading-eyebrow: 1;\n  --leading-title-md: 1.2;\n}\n```\n\nSupporting primitives still come from the shared base and generated theme layers, including:\n\n- `--font-primary`, `--font-secondary`, and `--font-tertiary`\n- `--line-height-heading-tight`\n- `--line-height-copy-base`\n- `--tracking-tight`\n- `--text-4xl`, `--text-5xl`, and `--text-7xl`\n\nNotes:\n\n- `--text-docs-nav` and `--leading-docs-nav` are part of the shared scale because the docs interface reuses the same text role in multiple places\n- hero sizing still combines local tokens with the larger text tokens already exposed by the theme\n- values belong in `@theme` only when they are part of the shared site scale or reused across roles\n\n## Shared Recipe Layer\n\nThe current shared semantic typography utilities are:\n\n- `type-section-title`\n- `type-copy`\n- `type-label-sm`\n- `type-label-strong`\n- `type-label-eyebrow`\n- `type-label-eyebrow-strong`\n- `type-label-xs`\n- `type-list-item-label`\n- `type-list-item-title`\n- `type-docs-nav`\n- `type-hero`\n- `type-title-xl`\n- `type-hero-subtitle`\n- `type-title-md`\n- `type-title-md-tight`\n- `type-title-sm-tight`\n- `type-list-index`\n\nThese utilities are intended to be complete on their own. Do not stack two semantic typography utilities that both set font metrics.\n\nThe current system intentionally does not include:\n\n- `type-label` as a partial base class\n- `type-docs-nav-strong` as a separate semantic utility\n\nDocs current-item emphasis is handled by `type-docs-nav` plus local state styling such as color, weight, and surface treatment.\n\n## Usage and Boundaries\n\nThe detailed usage examples, intentionally absent patterns, and component-boundary rules now live on a separate page so this overview can stay focused on the shared system itself.\n\nContinue to [Typography Usage and Boundaries](../typography-usage-and-boundaries/) for:\n\n- representative `@utility` definitions\n- template usage examples\n- current-item emphasis rules for docs navigation\n- component-local versus shared typography boundaries\n- intentionally absent patterns that should not be reintroduced\n\n## Guardrails\n\nUse these rules for future typography work:\n\n1. use plain Tailwind utilities for one-off cases\n2. add a shared `type-*` utility only when the same semantic role appears in multiple templates\n3. keep each shared utility complete on its own\n4. keep layout, spacing, color, and interaction state outside the semantic typography utility unless the role truly requires them\n5. when a component-local class needs a shared scale value, consume the shared tokens instead of copying magic numbers\n", "2.0": "+++\ntitle = \"Typography System\"\n+++\n\nThis page documents the current typography architecture for the Hugo website theme under `website/themes/sambee`.\n\nIt is a reference for the live system, not a planning note.\n\n## Current Architecture\n\nThe shared typography system has two layers:\n\n1. a token layer in `@theme` in `website/themes/sambee/assets/css/main.css`\n2. a recipe layer in `@utility` in `website/themes/sambee/assets/css/shared.css`\n\nRules of the current implementation:\n\n- `@theme` owns reusable type scale, tracking, and leading values that should be available as Tailwind-native tokens\n- `@utility` owns repeated semantic text roles used across templates\n- each semantic recipe is complete on its own\n- templates apply one semantic `type-*` utility per text role\n- color, spacing, layout, and interaction state remain separate concerns\n- component-local CSS may keep typography local when the role is specific to one component, but it should consume shared tokens where that keeps the site scale aligned\n\n## Shared Token Layer\n\nThe current shared typography token block in `website/themes/sambee/assets/css/main.css` is:\n\n```css\n@theme {\n  --text-copy: var(--font-size-copy-base);\n  --text-label-xs: var(--font-size-label-xs);\n  --text-label-sm: var(--font-size-label-sm);\n  --text-list-item-label: var(--font-size-label-sm);\n  --text-list-index: var(--font-size-copy-sm);\n  --text-list-item-title: var(--font-size-copy-sm);\n  --text-docs-nav: var(--font-size-copy-sm);\n  --text-title-sm: 1.125rem;\n  --text-title-md: 1.5rem;\n  --text-title-xl: 2rem;\n  --text-hero-subtitle: 1.6rem;\n  --text-hero-sm: 2.85rem;\n  --text-hero-md: 3.55rem;\n\n  --tracking-label: 0.1em;\n  --tracking-label-strong: 0.14em;\n  --tracking-eyebrow: 0.22em;\n  --tracking-eyebrow-strong: 0.18em;\n  --tracking-list-item-label: 0.1em;\n  --tracking-hero-subtitle: -0.1rem;\n\n  --leading-copy: 1.625rem;\n  --leading-docs-nav: 1.375;\n  --leading-eyebrow: 1;\n  --leading-title-md: 1.2;\n}\n```\n\nSupporting primitives still come from the shared base and generated theme layers, including:\n\n- `--font-primary`, `--font-secondary`, and `--font-tertiary`\n- `--line-height-heading-tight`\n- `--line-height-copy-base`\n- `--tracking-tight`\n- `--text-4xl`, `--text-5xl`, and `--text-7xl`\n\nNotes:\n\n- `--text-docs-nav` and `--leading-docs-nav` are part of the shared scale because the docs interface reuses the same text role in multiple places\n- hero sizing still combines local tokens with the larger text tokens already exposed by the theme\n- values belong in `@theme` only when they are part of the shared site scale or reused across roles\n\n## Shared Recipe Layer\n\nThe current shared semantic typography utilities are:\n\n- `type-section-title`\n- `type-copy`\n- `type-label-sm`\n- `type-label-strong`\n- `type-label-eyebrow`\n- `type-label-eyebrow-strong`\n- `type-label-xs`\n- `type-list-item-label`\n- `type-list-item-title`\n- `type-docs-nav`\n- `type-hero`\n- `type-title-xl`\n- `type-hero-subtitle`\n- `type-title-md`\n- `type-title-md-tight`\n- `type-title-sm-tight`\n- `type-list-index`\n\nThese utilities are intended to be complete on their own. Do not stack two semantic typography utilities that both set font metrics.\n\nThe current system intentionally does not include:\n\n- `type-label` as a partial base class\n- `type-docs-nav-strong` as a separate semantic utility\n\nDocs current-item emphasis is handled by `type-docs-nav` plus local state styling such as color, weight, and surface treatment.\n\n## Usage and Boundaries\n\nThe detailed usage examples, intentionally absent patterns, and component-boundary rules now live on a separate page so this overview can stay focused on the shared system itself.\n\nContinue to [Typography Usage and Boundaries](../typography-usage-and-boundaries/) for:\n\n- representative `@utility` definitions\n- template usage examples\n- current-item emphasis rules for docs navigation\n- component-local versus shared typography boundaries\n- intentionally absent patterns that should not be reintroduced\n\n## Guardrails\n\nUse these rules for future typography work:\n\n1. use plain Tailwind utilities for one-off cases\n2. add a shared `type-*` utility only when the same semantic role appears in multiple templates\n3. keep each shared utility complete on its own\n4. keep layout, spacing, color, and interaction state outside the semantic typography utility unless the role truly requires them\n5. when a component-local class needs a shared scale value, consume the shared tokens instead of copying magic numbers\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:website-dev-guide/site-systems/typography-usage-and-boundaries", "parent_id": "section:website-dev-guide/site-systems", "depth": 2, "kind": "page", "label": "typography-usage-and-boundaries", "title": "Typography Usage And Boundaries", "path": "website-dev-guide/site-systems/typography-usage-and-boundaries", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Typography Usage and Boundaries\"\n+++\n\nThis page covers the applied side of the website typography system.\n\nUse it when you need examples, implementation patterns, or boundary rules for deciding whether typography belongs in a shared utility or in component-local CSS.\n\n## Representative Definitions\n\nRepresentative implementations from `website/themes/sambee/assets/css/shared.css`:\n\n```css\n@utility type-copy {\n  font-family: var(--font-primary);\n  font-size: var(--text-copy);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-copy);\n}\n\n@utility type-label-sm {\n  font-family: var(--font-tertiary);\n  font-size: var(--text-label-sm);\n  font-weight: 400;\n  font-style: normal;\n  text-transform: uppercase;\n  letter-spacing: var(--tracking-label);\n}\n\n@utility type-docs-nav {\n  font-family: var(--font-primary);\n  font-size: var(--text-docs-nav);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-docs-nav);\n}\n\n@utility type-title-md {\n  font-family: var(--font-secondary);\n  font-size: var(--text-title-md);\n  font-weight: 700;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-title-md);\n}\n```\n\n## Template Usage Rules\n\nTemplates should apply one semantic typography utility per text role and then combine it with separate classes for color, layout, and interaction state.\n\nExamples from the live theme:\n\n```html\n\u003cspan class=\"type-label-eyebrow type-color-accent eyebrow-stack\"\u003eDocumentation\u003c/span\u003e\n\u003ch2 class=\"type-section-title type-color-ink\"\u003eFast local-first preview\u003c/h2\u003e\n\u003cspan class=\"docs-sidebar-link docs-sidebar-link-current type-docs-nav type-color-ink ui-current-primary-inset\"\u003eCurrent page\u003c/span\u003e\n\u003ca class=\"docs-sidebar-link type-docs-nav type-color-muted ui-transition-color type-hover-ink ui-hover-surface-mid\" href=\"/docs/\"\u003eDocumentation\u003c/a\u003e\n```\n\nCurrent usage rules:\n\n- apply exactly one semantic `type-*` utility to a text element\n- combine it with color helpers, layout helpers, and component-specific state classes as needed\n- do not stack two `type-*` utilities that both set size, weight, letter-spacing, line-height, or transform\n- do not reintroduce a partial base class such as `type-label`\n\nPatterns intentionally absent from the current theme include:\n\n```html\n\u003cspan class=\"type-label type-label-strong\"\u003e...\u003c/span\u003e\n\u003cspan class=\"type-label type-label-xs\"\u003e...\u003c/span\u003e\n\u003cli class=\"type-label type-list-item-label\"\u003e...\u003c/li\u003e\n```\n\n## Local Typography Boundaries\n\nNot every text treatment is shared.\n\n### Docs UI\n\n`website/themes/sambee/assets/css/docs.css` uses the shared `type-docs-nav` role for repeated documentation navigation text, including:\n\n- table of contents links\n- version switcher labels and options\n- nav tree links and current items\n- sequential navigation labels and titles\n\nLocal docs classes still own padding, indentation, and current-item state. For example, `.docs-sidebar-link-current` adds the stronger weight for the active item instead of relying on a separate semantic utility.\n\n### Navigation\n\n`website/themes/sambee/assets/css/navigation.css` keeps `.nav-link` as a component-local role. It consumes shared tracking values so the navigation remains aligned with the site-wide label scale.\n\n### Buttons\n\n`website/themes/sambee/assets/css/buttons.css` keeps `.btn` and `.btn-sm` as local button primitives. They consume shared typography tokens where it makes sense, but buttons are not modeled as shared text-role utilities.\n\n### Footer\n\nFooter layout classes remain local in `website/themes/sambee/assets/css/footer.css`. Shared typography utilities still supply the text role where that role is reused across templates.\n\n### Content-Specific Typography\n\nArticle-content semantics such as table headers, `figcaption`, `dt`, and admonition titles remain local to `content.css`. They belong to the content domain, not to shared site-wide text roles.\n", "0.8": "+++\ntitle = \"Typography Usage and Boundaries\"\n+++\n\nThis page covers the applied side of the website typography system.\n\nUse it when you need examples, implementation patterns, or boundary rules for deciding whether typography belongs in a shared utility or in component-local CSS.\n\n## Representative Definitions\n\nRepresentative implementations from `website/themes/sambee/assets/css/shared.css`:\n\n```css\n@utility type-copy {\n  font-family: var(--font-primary);\n  font-size: var(--text-copy);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-copy);\n}\n\n@utility type-label-sm {\n  font-family: var(--font-tertiary);\n  font-size: var(--text-label-sm);\n  font-weight: 400;\n  font-style: normal;\n  text-transform: uppercase;\n  letter-spacing: var(--tracking-label);\n}\n\n@utility type-docs-nav {\n  font-family: var(--font-primary);\n  font-size: var(--text-docs-nav);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-docs-nav);\n}\n\n@utility type-title-md {\n  font-family: var(--font-secondary);\n  font-size: var(--text-title-md);\n  font-weight: 700;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-title-md);\n}\n```\n\n## Template Usage Rules\n\nTemplates should apply one semantic typography utility per text role and then combine it with separate classes for color, layout, and interaction state.\n\nExamples from the live theme:\n\n```html\n\u003cspan class=\"type-label-eyebrow type-color-accent eyebrow-stack\"\u003eDocumentation\u003c/span\u003e\n\u003ch2 class=\"type-section-title type-color-ink\"\u003eFast local-first preview\u003c/h2\u003e\n\u003cspan class=\"docs-sidebar-link docs-sidebar-link-current type-docs-nav type-color-ink ui-current-primary-inset\"\u003eCurrent page\u003c/span\u003e\n\u003ca class=\"docs-sidebar-link type-docs-nav type-color-muted ui-transition-color type-hover-ink ui-hover-surface-mid\" href=\"/docs/\"\u003eDocumentation\u003c/a\u003e\n```\n\nCurrent usage rules:\n\n- apply exactly one semantic `type-*` utility to a text element\n- combine it with color helpers, layout helpers, and component-specific state classes as needed\n- do not stack two `type-*` utilities that both set size, weight, letter-spacing, line-height, or transform\n- do not reintroduce a partial base class such as `type-label`\n\nPatterns intentionally absent from the current theme include:\n\n```html\n\u003cspan class=\"type-label type-label-strong\"\u003e...\u003c/span\u003e\n\u003cspan class=\"type-label type-label-xs\"\u003e...\u003c/span\u003e\n\u003cli class=\"type-label type-list-item-label\"\u003e...\u003c/li\u003e\n```\n\n## Local Typography Boundaries\n\nNot every text treatment is shared.\n\n### Docs UI\n\n`website/themes/sambee/assets/css/docs.css` uses the shared `type-docs-nav` role for repeated documentation navigation text, including:\n\n- table of contents links\n- version switcher labels and options\n- nav tree links and current items\n- sequential navigation labels and titles\n\nLocal docs classes still own padding, indentation, and current-item state. For example, `.docs-sidebar-link-current` adds the stronger weight for the active item instead of relying on a separate semantic utility.\n\n### Navigation\n\n`website/themes/sambee/assets/css/navigation.css` keeps `.nav-link` as a component-local role. It consumes shared tracking values so the navigation remains aligned with the site-wide label scale.\n\n### Buttons\n\n`website/themes/sambee/assets/css/buttons.css` keeps `.btn` and `.btn-sm` as local button primitives. They consume shared typography tokens where it makes sense, but buttons are not modeled as shared text-role utilities.\n\n### Footer\n\nFooter layout classes remain local in `website/themes/sambee/assets/css/footer.css`. Shared typography utilities still supply the text role where that role is reused across templates.\n\n### Content-Specific Typography\n\nArticle-content semantics such as table headers, `figcaption`, `dt`, and admonition titles remain local to `content.css`. They belong to the content domain, not to shared site-wide text roles.\n", "0.9": "+++\ntitle = \"Typography Usage and Boundaries\"\n+++\n\nThis page covers the applied side of the website typography system.\n\nUse it when you need examples, implementation patterns, or boundary rules for deciding whether typography belongs in a shared utility or in component-local CSS.\n\n## Representative Definitions\n\nRepresentative implementations from `website/themes/sambee/assets/css/shared.css`:\n\n```css\n@utility type-copy {\n  font-family: var(--font-primary);\n  font-size: var(--text-copy);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-copy);\n}\n\n@utility type-label-sm {\n  font-family: var(--font-tertiary);\n  font-size: var(--text-label-sm);\n  font-weight: 400;\n  font-style: normal;\n  text-transform: uppercase;\n  letter-spacing: var(--tracking-label);\n}\n\n@utility type-docs-nav {\n  font-family: var(--font-primary);\n  font-size: var(--text-docs-nav);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-docs-nav);\n}\n\n@utility type-title-md {\n  font-family: var(--font-secondary);\n  font-size: var(--text-title-md);\n  font-weight: 700;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-title-md);\n}\n```\n\n## Template Usage Rules\n\nTemplates should apply one semantic typography utility per text role and then combine it with separate classes for color, layout, and interaction state.\n\nExamples from the live theme:\n\n```html\n\u003cspan class=\"type-label-eyebrow type-color-accent eyebrow-stack\"\u003eDocumentation\u003c/span\u003e\n\u003ch2 class=\"type-section-title type-color-ink\"\u003eFast local-first preview\u003c/h2\u003e\n\u003cspan class=\"docs-sidebar-link docs-sidebar-link-current type-docs-nav type-color-ink ui-current-primary-inset\"\u003eCurrent page\u003c/span\u003e\n\u003ca class=\"docs-sidebar-link type-docs-nav type-color-muted ui-transition-color type-hover-ink ui-hover-surface-mid\" href=\"/docs/\"\u003eDocumentation\u003c/a\u003e\n```\n\nCurrent usage rules:\n\n- apply exactly one semantic `type-*` utility to a text element\n- combine it with color helpers, layout helpers, and component-specific state classes as needed\n- do not stack two `type-*` utilities that both set size, weight, letter-spacing, line-height, or transform\n- do not reintroduce a partial base class such as `type-label`\n\nPatterns intentionally absent from the current theme include:\n\n```html\n\u003cspan class=\"type-label type-label-strong\"\u003e...\u003c/span\u003e\n\u003cspan class=\"type-label type-label-xs\"\u003e...\u003c/span\u003e\n\u003cli class=\"type-label type-list-item-label\"\u003e...\u003c/li\u003e\n```\n\n## Local Typography Boundaries\n\nNot every text treatment is shared.\n\n### Docs UI\n\n`website/themes/sambee/assets/css/docs.css` uses the shared `type-docs-nav` role for repeated documentation navigation text, including:\n\n- table of contents links\n- version switcher labels and options\n- nav tree links and current items\n- sequential navigation labels and titles\n\nLocal docs classes still own padding, indentation, and current-item state. For example, `.docs-sidebar-link-current` adds the stronger weight for the active item instead of relying on a separate semantic utility.\n\n### Navigation\n\n`website/themes/sambee/assets/css/navigation.css` keeps `.nav-link` as a component-local role. It consumes shared tracking values so the navigation remains aligned with the site-wide label scale.\n\n### Buttons\n\n`website/themes/sambee/assets/css/buttons.css` keeps `.btn` and `.btn-sm` as local button primitives. They consume shared typography tokens where it makes sense, but buttons are not modeled as shared text-role utilities.\n\n### Footer\n\nFooter layout classes remain local in `website/themes/sambee/assets/css/footer.css`. Shared typography utilities still supply the text role where that role is reused across templates.\n\n### Content-Specific Typography\n\nArticle-content semantics such as table headers, `figcaption`, `dt`, and admonition titles remain local to `content.css`. They belong to the content domain, not to shared site-wide text roles.\n", "1.0": "+++\ntitle = \"Typography Usage and Boundaries\"\n+++\n\nThis page covers the applied side of the website typography system.\n\nUse it when you need examples, implementation patterns, or boundary rules for deciding whether typography belongs in a shared utility or in component-local CSS.\n\n## Representative Definitions\n\nRepresentative implementations from `website/themes/sambee/assets/css/shared.css`:\n\n```css\n@utility type-copy {\n  font-family: var(--font-primary);\n  font-size: var(--text-copy);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-copy);\n}\n\n@utility type-label-sm {\n  font-family: var(--font-tertiary);\n  font-size: var(--text-label-sm);\n  font-weight: 400;\n  font-style: normal;\n  text-transform: uppercase;\n  letter-spacing: var(--tracking-label);\n}\n\n@utility type-docs-nav {\n  font-family: var(--font-primary);\n  font-size: var(--text-docs-nav);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-docs-nav);\n}\n\n@utility type-title-md {\n  font-family: var(--font-secondary);\n  font-size: var(--text-title-md);\n  font-weight: 700;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-title-md);\n}\n```\n\n## Template Usage Rules\n\nTemplates should apply one semantic typography utility per text role and then combine it with separate classes for color, layout, and interaction state.\n\nExamples from the live theme:\n\n```html\n\u003cspan class=\"type-label-eyebrow type-color-accent eyebrow-stack\"\u003eDocumentation\u003c/span\u003e\n\u003ch2 class=\"type-section-title type-color-ink\"\u003eFast local-first preview\u003c/h2\u003e\n\u003cspan class=\"docs-sidebar-link docs-sidebar-link-current type-docs-nav type-color-ink ui-current-primary-inset\"\u003eCurrent page\u003c/span\u003e\n\u003ca class=\"docs-sidebar-link type-docs-nav type-color-muted ui-transition-color type-hover-ink ui-hover-surface-mid\" href=\"/docs/\"\u003eDocumentation\u003c/a\u003e\n```\n\nCurrent usage rules:\n\n- apply exactly one semantic `type-*` utility to a text element\n- combine it with color helpers, layout helpers, and component-specific state classes as needed\n- do not stack two `type-*` utilities that both set size, weight, letter-spacing, line-height, or transform\n- do not reintroduce a partial base class such as `type-label`\n\nPatterns intentionally absent from the current theme include:\n\n```html\n\u003cspan class=\"type-label type-label-strong\"\u003e...\u003c/span\u003e\n\u003cspan class=\"type-label type-label-xs\"\u003e...\u003c/span\u003e\n\u003cli class=\"type-label type-list-item-label\"\u003e...\u003c/li\u003e\n```\n\n## Local Typography Boundaries\n\nNot every text treatment is shared.\n\n### Docs UI\n\n`website/themes/sambee/assets/css/docs.css` uses the shared `type-docs-nav` role for repeated documentation navigation text, including:\n\n- table of contents links\n- version switcher labels and options\n- nav tree links and current items\n- sequential navigation labels and titles\n\nLocal docs classes still own padding, indentation, and current-item state. For example, `.docs-sidebar-link-current` adds the stronger weight for the active item instead of relying on a separate semantic utility.\n\n### Navigation\n\n`website/themes/sambee/assets/css/navigation.css` keeps `.nav-link` as a component-local role. It consumes shared tracking values so the navigation remains aligned with the site-wide label scale.\n\n### Buttons\n\n`website/themes/sambee/assets/css/buttons.css` keeps `.btn` and `.btn-sm` as local button primitives. They consume shared typography tokens where it makes sense, but buttons are not modeled as shared text-role utilities.\n\n### Footer\n\nFooter layout classes remain local in `website/themes/sambee/assets/css/footer.css`. Shared typography utilities still supply the text role where that role is reused across templates.\n\n### Content-Specific Typography\n\nArticle-content semantics such as table headers, `figcaption`, `dt`, and admonition titles remain local to `content.css`. They belong to the content domain, not to shared site-wide text roles.\n", "2.0": "+++\ntitle = \"Typography Usage and Boundaries\"\n+++\n\nThis page covers the applied side of the website typography system.\n\nUse it when you need examples, implementation patterns, or boundary rules for deciding whether typography belongs in a shared utility or in component-local CSS.\n\n## Representative Definitions\n\nRepresentative implementations from `website/themes/sambee/assets/css/shared.css`:\n\n```css\n@utility type-copy {\n  font-family: var(--font-primary);\n  font-size: var(--text-copy);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-copy);\n}\n\n@utility type-label-sm {\n  font-family: var(--font-tertiary);\n  font-size: var(--text-label-sm);\n  font-weight: 400;\n  font-style: normal;\n  text-transform: uppercase;\n  letter-spacing: var(--tracking-label);\n}\n\n@utility type-docs-nav {\n  font-family: var(--font-primary);\n  font-size: var(--text-docs-nav);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-docs-nav);\n}\n\n@utility type-title-md {\n  font-family: var(--font-secondary);\n  font-size: var(--text-title-md);\n  font-weight: 700;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-title-md);\n}\n```\n\n## Template Usage Rules\n\nTemplates should apply one semantic typography utility per text role and then combine it with separate classes for color, layout, and interaction state.\n\nExamples from the live theme:\n\n```html\n\u003cspan class=\"type-label-eyebrow type-color-accent eyebrow-stack\"\u003eDocumentation\u003c/span\u003e\n\u003ch2 class=\"type-section-title type-color-ink\"\u003eFast local-first preview\u003c/h2\u003e\n\u003cspan class=\"docs-sidebar-link docs-sidebar-link-current type-docs-nav type-color-ink ui-current-primary-inset\"\u003eCurrent page\u003c/span\u003e\n\u003ca class=\"docs-sidebar-link type-docs-nav type-color-muted ui-transition-color type-hover-ink ui-hover-surface-mid\" href=\"/docs/\"\u003eDocumentation\u003c/a\u003e\n```\n\nCurrent usage rules:\n\n- apply exactly one semantic `type-*` utility to a text element\n- combine it with color helpers, layout helpers, and component-specific state classes as needed\n- do not stack two `type-*` utilities that both set size, weight, letter-spacing, line-height, or transform\n- do not reintroduce a partial base class such as `type-label`\n\nPatterns intentionally absent from the current theme include:\n\n```html\n\u003cspan class=\"type-label type-label-strong\"\u003e...\u003c/span\u003e\n\u003cspan class=\"type-label type-label-xs\"\u003e...\u003c/span\u003e\n\u003cli class=\"type-label type-list-item-label\"\u003e...\u003c/li\u003e\n```\n\n## Local Typography Boundaries\n\nNot every text treatment is shared.\n\n### Docs UI\n\n`website/themes/sambee/assets/css/docs.css` uses the shared `type-docs-nav` role for repeated documentation navigation text, including:\n\n- table of contents links\n- version switcher labels and options\n- nav tree links and current items\n- sequential navigation labels and titles\n\nLocal docs classes still own padding, indentation, and current-item state. For example, `.docs-sidebar-link-current` adds the stronger weight for the active item instead of relying on a separate semantic utility.\n\n### Navigation\n\n`website/themes/sambee/assets/css/navigation.css` keeps `.nav-link` as a component-local role. It consumes shared tracking values so the navigation remains aligned with the site-wide label scale.\n\n### Buttons\n\n`website/themes/sambee/assets/css/buttons.css` keeps `.btn` and `.btn-sm` as local button primitives. They consume shared typography tokens where it makes sense, but buttons are not modeled as shared text-role utilities.\n\n### Footer\n\nFooter layout classes remain local in `website/themes/sambee/assets/css/footer.css`. Shared typography utilities still supply the text role where that role is reused across templates.\n\n### Content-Specific Typography\n\nArticle-content semantics such as table headers, `figcaption`, `dt`, and admonition titles remain local to `content.css`. They belong to the content domain, not to shared site-wide text roles.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Typography Usage and Boundaries\"\n+++\n\nThis page covers the applied side of the website typography system.\n\nUse it when you need examples, implementation patterns, or boundary rules for deciding whether typography belongs in a shared utility or in component-local CSS.\n\n## Representative Definitions\n\nRepresentative implementations from `website/themes/sambee/assets/css/shared.css`:\n\n```css\n@utility type-copy {\n  font-family: var(--font-primary);\n  font-size: var(--text-copy);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-copy);\n}\n\n@utility type-label-sm {\n  font-family: var(--font-tertiary);\n  font-size: var(--text-label-sm);\n  font-weight: 400;\n  font-style: normal;\n  text-transform: uppercase;\n  letter-spacing: var(--tracking-label);\n}\n\n@utility type-docs-nav {\n  font-family: var(--font-primary);\n  font-size: var(--text-docs-nav);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-docs-nav);\n}\n\n@utility type-title-md {\n  font-family: var(--font-secondary);\n  font-size: var(--text-title-md);\n  font-weight: 700;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-title-md);\n}\n```\n\n## Template Usage Rules\n\nTemplates should apply one semantic typography utility per text role and then combine it with separate classes for color, layout, and interaction state.\n\nExamples from the live theme:\n\n```html\n\u003cspan class=\"type-label-eyebrow type-color-accent eyebrow-stack\"\u003eDocumentation\u003c/span\u003e\n\u003ch2 class=\"type-section-title type-color-ink\"\u003eFast local-first preview\u003c/h2\u003e\n\u003cspan class=\"docs-sidebar-link docs-sidebar-link-current type-docs-nav type-color-ink ui-current-primary-inset\"\u003eCurrent page\u003c/span\u003e\n\u003ca class=\"docs-sidebar-link type-docs-nav type-color-muted ui-transition-color type-hover-ink ui-hover-surface-mid\" href=\"/docs/\"\u003eDocumentation\u003c/a\u003e\n```\n\nCurrent usage rules:\n\n- apply exactly one semantic `type-*` utility to a text element\n- combine it with color helpers, layout helpers, and component-specific state classes as needed\n- do not stack two `type-*` utilities that both set size, weight, letter-spacing, line-height, or transform\n- do not reintroduce a partial base class such as `type-label`\n\nPatterns intentionally absent from the current theme include:\n\n```html\n\u003cspan class=\"type-label type-label-strong\"\u003e...\u003c/span\u003e\n\u003cspan class=\"type-label type-label-xs\"\u003e...\u003c/span\u003e\n\u003cli class=\"type-label type-list-item-label\"\u003e...\u003c/li\u003e\n```\n\n## Local Typography Boundaries\n\nNot every text treatment is shared.\n\n### Docs UI\n\n`website/themes/sambee/assets/css/docs.css` uses the shared `type-docs-nav` role for repeated documentation navigation text, including:\n\n- table of contents links\n- version switcher labels and options\n- nav tree links and current items\n- sequential navigation labels and titles\n\nLocal docs classes still own padding, indentation, and current-item state. For example, `.docs-sidebar-link-current` adds the stronger weight for the active item instead of relying on a separate semantic utility.\n\n### Navigation\n\n`website/themes/sambee/assets/css/navigation.css` keeps `.nav-link` as a component-local role. It consumes shared tracking values so the navigation remains aligned with the site-wide label scale.\n\n### Buttons\n\n`website/themes/sambee/assets/css/buttons.css` keeps `.btn` and `.btn-sm` as local button primitives. They consume shared typography tokens where it makes sense, but buttons are not modeled as shared text-role utilities.\n\n### Footer\n\nFooter layout classes remain local in `website/themes/sambee/assets/css/footer.css`. Shared typography utilities still supply the text role where that role is reused across templates.\n\n### Content-Specific Typography\n\nArticle-content semantics such as table headers, `figcaption`, `dt`, and admonition titles remain local to `content.css`. They belong to the content domain, not to shared site-wide text roles.\n", "0.8": "+++\ntitle = \"Typography Usage and Boundaries\"\n+++\n\nThis page covers the applied side of the website typography system.\n\nUse it when you need examples, implementation patterns, or boundary rules for deciding whether typography belongs in a shared utility or in component-local CSS.\n\n## Representative Definitions\n\nRepresentative implementations from `website/themes/sambee/assets/css/shared.css`:\n\n```css\n@utility type-copy {\n  font-family: var(--font-primary);\n  font-size: var(--text-copy);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-copy);\n}\n\n@utility type-label-sm {\n  font-family: var(--font-tertiary);\n  font-size: var(--text-label-sm);\n  font-weight: 400;\n  font-style: normal;\n  text-transform: uppercase;\n  letter-spacing: var(--tracking-label);\n}\n\n@utility type-docs-nav {\n  font-family: var(--font-primary);\n  font-size: var(--text-docs-nav);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-docs-nav);\n}\n\n@utility type-title-md {\n  font-family: var(--font-secondary);\n  font-size: var(--text-title-md);\n  font-weight: 700;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-title-md);\n}\n```\n\n## Template Usage Rules\n\nTemplates should apply one semantic typography utility per text role and then combine it with separate classes for color, layout, and interaction state.\n\nExamples from the live theme:\n\n```html\n\u003cspan class=\"type-label-eyebrow type-color-accent eyebrow-stack\"\u003eDocumentation\u003c/span\u003e\n\u003ch2 class=\"type-section-title type-color-ink\"\u003eFast local-first preview\u003c/h2\u003e\n\u003cspan class=\"docs-sidebar-link docs-sidebar-link-current type-docs-nav type-color-ink ui-current-primary-inset\"\u003eCurrent page\u003c/span\u003e\n\u003ca class=\"docs-sidebar-link type-docs-nav type-color-muted ui-transition-color type-hover-ink ui-hover-surface-mid\" href=\"/docs/\"\u003eDocumentation\u003c/a\u003e\n```\n\nCurrent usage rules:\n\n- apply exactly one semantic `type-*` utility to a text element\n- combine it with color helpers, layout helpers, and component-specific state classes as needed\n- do not stack two `type-*` utilities that both set size, weight, letter-spacing, line-height, or transform\n- do not reintroduce a partial base class such as `type-label`\n\nPatterns intentionally absent from the current theme include:\n\n```html\n\u003cspan class=\"type-label type-label-strong\"\u003e...\u003c/span\u003e\n\u003cspan class=\"type-label type-label-xs\"\u003e...\u003c/span\u003e\n\u003cli class=\"type-label type-list-item-label\"\u003e...\u003c/li\u003e\n```\n\n## Local Typography Boundaries\n\nNot every text treatment is shared.\n\n### Docs UI\n\n`website/themes/sambee/assets/css/docs.css` uses the shared `type-docs-nav` role for repeated documentation navigation text, including:\n\n- table of contents links\n- version switcher labels and options\n- nav tree links and current items\n- sequential navigation labels and titles\n\nLocal docs classes still own padding, indentation, and current-item state. For example, `.docs-sidebar-link-current` adds the stronger weight for the active item instead of relying on a separate semantic utility.\n\n### Navigation\n\n`website/themes/sambee/assets/css/navigation.css` keeps `.nav-link` as a component-local role. It consumes shared tracking values so the navigation remains aligned with the site-wide label scale.\n\n### Buttons\n\n`website/themes/sambee/assets/css/buttons.css` keeps `.btn` and `.btn-sm` as local button primitives. They consume shared typography tokens where it makes sense, but buttons are not modeled as shared text-role utilities.\n\n### Footer\n\nFooter layout classes remain local in `website/themes/sambee/assets/css/footer.css`. Shared typography utilities still supply the text role where that role is reused across templates.\n\n### Content-Specific Typography\n\nArticle-content semantics such as table headers, `figcaption`, `dt`, and admonition titles remain local to `content.css`. They belong to the content domain, not to shared site-wide text roles.\n", "0.9": "+++\ntitle = \"Typography Usage and Boundaries\"\n+++\n\nThis page covers the applied side of the website typography system.\n\nUse it when you need examples, implementation patterns, or boundary rules for deciding whether typography belongs in a shared utility or in component-local CSS.\n\n## Representative Definitions\n\nRepresentative implementations from `website/themes/sambee/assets/css/shared.css`:\n\n```css\n@utility type-copy {\n  font-family: var(--font-primary);\n  font-size: var(--text-copy);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-copy);\n}\n\n@utility type-label-sm {\n  font-family: var(--font-tertiary);\n  font-size: var(--text-label-sm);\n  font-weight: 400;\n  font-style: normal;\n  text-transform: uppercase;\n  letter-spacing: var(--tracking-label);\n}\n\n@utility type-docs-nav {\n  font-family: var(--font-primary);\n  font-size: var(--text-docs-nav);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-docs-nav);\n}\n\n@utility type-title-md {\n  font-family: var(--font-secondary);\n  font-size: var(--text-title-md);\n  font-weight: 700;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-title-md);\n}\n```\n\n## Template Usage Rules\n\nTemplates should apply one semantic typography utility per text role and then combine it with separate classes for color, layout, and interaction state.\n\nExamples from the live theme:\n\n```html\n\u003cspan class=\"type-label-eyebrow type-color-accent eyebrow-stack\"\u003eDocumentation\u003c/span\u003e\n\u003ch2 class=\"type-section-title type-color-ink\"\u003eFast local-first preview\u003c/h2\u003e\n\u003cspan class=\"docs-sidebar-link docs-sidebar-link-current type-docs-nav type-color-ink ui-current-primary-inset\"\u003eCurrent page\u003c/span\u003e\n\u003ca class=\"docs-sidebar-link type-docs-nav type-color-muted ui-transition-color type-hover-ink ui-hover-surface-mid\" href=\"/docs/\"\u003eDocumentation\u003c/a\u003e\n```\n\nCurrent usage rules:\n\n- apply exactly one semantic `type-*` utility to a text element\n- combine it with color helpers, layout helpers, and component-specific state classes as needed\n- do not stack two `type-*` utilities that both set size, weight, letter-spacing, line-height, or transform\n- do not reintroduce a partial base class such as `type-label`\n\nPatterns intentionally absent from the current theme include:\n\n```html\n\u003cspan class=\"type-label type-label-strong\"\u003e...\u003c/span\u003e\n\u003cspan class=\"type-label type-label-xs\"\u003e...\u003c/span\u003e\n\u003cli class=\"type-label type-list-item-label\"\u003e...\u003c/li\u003e\n```\n\n## Local Typography Boundaries\n\nNot every text treatment is shared.\n\n### Docs UI\n\n`website/themes/sambee/assets/css/docs.css` uses the shared `type-docs-nav` role for repeated documentation navigation text, including:\n\n- table of contents links\n- version switcher labels and options\n- nav tree links and current items\n- sequential navigation labels and titles\n\nLocal docs classes still own padding, indentation, and current-item state. For example, `.docs-sidebar-link-current` adds the stronger weight for the active item instead of relying on a separate semantic utility.\n\n### Navigation\n\n`website/themes/sambee/assets/css/navigation.css` keeps `.nav-link` as a component-local role. It consumes shared tracking values so the navigation remains aligned with the site-wide label scale.\n\n### Buttons\n\n`website/themes/sambee/assets/css/buttons.css` keeps `.btn` and `.btn-sm` as local button primitives. They consume shared typography tokens where it makes sense, but buttons are not modeled as shared text-role utilities.\n\n### Footer\n\nFooter layout classes remain local in `website/themes/sambee/assets/css/footer.css`. Shared typography utilities still supply the text role where that role is reused across templates.\n\n### Content-Specific Typography\n\nArticle-content semantics such as table headers, `figcaption`, `dt`, and admonition titles remain local to `content.css`. They belong to the content domain, not to shared site-wide text roles.\n", "1.0": "+++\ntitle = \"Typography Usage and Boundaries\"\n+++\n\nThis page covers the applied side of the website typography system.\n\nUse it when you need examples, implementation patterns, or boundary rules for deciding whether typography belongs in a shared utility or in component-local CSS.\n\n## Representative Definitions\n\nRepresentative implementations from `website/themes/sambee/assets/css/shared.css`:\n\n```css\n@utility type-copy {\n  font-family: var(--font-primary);\n  font-size: var(--text-copy);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-copy);\n}\n\n@utility type-label-sm {\n  font-family: var(--font-tertiary);\n  font-size: var(--text-label-sm);\n  font-weight: 400;\n  font-style: normal;\n  text-transform: uppercase;\n  letter-spacing: var(--tracking-label);\n}\n\n@utility type-docs-nav {\n  font-family: var(--font-primary);\n  font-size: var(--text-docs-nav);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-docs-nav);\n}\n\n@utility type-title-md {\n  font-family: var(--font-secondary);\n  font-size: var(--text-title-md);\n  font-weight: 700;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-title-md);\n}\n```\n\n## Template Usage Rules\n\nTemplates should apply one semantic typography utility per text role and then combine it with separate classes for color, layout, and interaction state.\n\nExamples from the live theme:\n\n```html\n\u003cspan class=\"type-label-eyebrow type-color-accent eyebrow-stack\"\u003eDocumentation\u003c/span\u003e\n\u003ch2 class=\"type-section-title type-color-ink\"\u003eFast local-first preview\u003c/h2\u003e\n\u003cspan class=\"docs-sidebar-link docs-sidebar-link-current type-docs-nav type-color-ink ui-current-primary-inset\"\u003eCurrent page\u003c/span\u003e\n\u003ca class=\"docs-sidebar-link type-docs-nav type-color-muted ui-transition-color type-hover-ink ui-hover-surface-mid\" href=\"/docs/\"\u003eDocumentation\u003c/a\u003e\n```\n\nCurrent usage rules:\n\n- apply exactly one semantic `type-*` utility to a text element\n- combine it with color helpers, layout helpers, and component-specific state classes as needed\n- do not stack two `type-*` utilities that both set size, weight, letter-spacing, line-height, or transform\n- do not reintroduce a partial base class such as `type-label`\n\nPatterns intentionally absent from the current theme include:\n\n```html\n\u003cspan class=\"type-label type-label-strong\"\u003e...\u003c/span\u003e\n\u003cspan class=\"type-label type-label-xs\"\u003e...\u003c/span\u003e\n\u003cli class=\"type-label type-list-item-label\"\u003e...\u003c/li\u003e\n```\n\n## Local Typography Boundaries\n\nNot every text treatment is shared.\n\n### Docs UI\n\n`website/themes/sambee/assets/css/docs.css` uses the shared `type-docs-nav` role for repeated documentation navigation text, including:\n\n- table of contents links\n- version switcher labels and options\n- nav tree links and current items\n- sequential navigation labels and titles\n\nLocal docs classes still own padding, indentation, and current-item state. For example, `.docs-sidebar-link-current` adds the stronger weight for the active item instead of relying on a separate semantic utility.\n\n### Navigation\n\n`website/themes/sambee/assets/css/navigation.css` keeps `.nav-link` as a component-local role. It consumes shared tracking values so the navigation remains aligned with the site-wide label scale.\n\n### Buttons\n\n`website/themes/sambee/assets/css/buttons.css` keeps `.btn` and `.btn-sm` as local button primitives. They consume shared typography tokens where it makes sense, but buttons are not modeled as shared text-role utilities.\n\n### Footer\n\nFooter layout classes remain local in `website/themes/sambee/assets/css/footer.css`. Shared typography utilities still supply the text role where that role is reused across templates.\n\n### Content-Specific Typography\n\nArticle-content semantics such as table headers, `figcaption`, `dt`, and admonition titles remain local to `content.css`. They belong to the content domain, not to shared site-wide text roles.\n", "2.0": "+++\ntitle = \"Typography Usage and Boundaries\"\n+++\n\nThis page covers the applied side of the website typography system.\n\nUse it when you need examples, implementation patterns, or boundary rules for deciding whether typography belongs in a shared utility or in component-local CSS.\n\n## Representative Definitions\n\nRepresentative implementations from `website/themes/sambee/assets/css/shared.css`:\n\n```css\n@utility type-copy {\n  font-family: var(--font-primary);\n  font-size: var(--text-copy);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-copy);\n}\n\n@utility type-label-sm {\n  font-family: var(--font-tertiary);\n  font-size: var(--text-label-sm);\n  font-weight: 400;\n  font-style: normal;\n  text-transform: uppercase;\n  letter-spacing: var(--tracking-label);\n}\n\n@utility type-docs-nav {\n  font-family: var(--font-primary);\n  font-size: var(--text-docs-nav);\n  font-weight: 400;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-docs-nav);\n}\n\n@utility type-title-md {\n  font-family: var(--font-secondary);\n  font-size: var(--text-title-md);\n  font-weight: 700;\n  font-style: normal;\n  letter-spacing: normal;\n  line-height: var(--leading-title-md);\n}\n```\n\n## Template Usage Rules\n\nTemplates should apply one semantic typography utility per text role and then combine it with separate classes for color, layout, and interaction state.\n\nExamples from the live theme:\n\n```html\n\u003cspan class=\"type-label-eyebrow type-color-accent eyebrow-stack\"\u003eDocumentation\u003c/span\u003e\n\u003ch2 class=\"type-section-title type-color-ink\"\u003eFast local-first preview\u003c/h2\u003e\n\u003cspan class=\"docs-sidebar-link docs-sidebar-link-current type-docs-nav type-color-ink ui-current-primary-inset\"\u003eCurrent page\u003c/span\u003e\n\u003ca class=\"docs-sidebar-link type-docs-nav type-color-muted ui-transition-color type-hover-ink ui-hover-surface-mid\" href=\"/docs/\"\u003eDocumentation\u003c/a\u003e\n```\n\nCurrent usage rules:\n\n- apply exactly one semantic `type-*` utility to a text element\n- combine it with color helpers, layout helpers, and component-specific state classes as needed\n- do not stack two `type-*` utilities that both set size, weight, letter-spacing, line-height, or transform\n- do not reintroduce a partial base class such as `type-label`\n\nPatterns intentionally absent from the current theme include:\n\n```html\n\u003cspan class=\"type-label type-label-strong\"\u003e...\u003c/span\u003e\n\u003cspan class=\"type-label type-label-xs\"\u003e...\u003c/span\u003e\n\u003cli class=\"type-label type-list-item-label\"\u003e...\u003c/li\u003e\n```\n\n## Local Typography Boundaries\n\nNot every text treatment is shared.\n\n### Docs UI\n\n`website/themes/sambee/assets/css/docs.css` uses the shared `type-docs-nav` role for repeated documentation navigation text, including:\n\n- table of contents links\n- version switcher labels and options\n- nav tree links and current items\n- sequential navigation labels and titles\n\nLocal docs classes still own padding, indentation, and current-item state. For example, `.docs-sidebar-link-current` adds the stronger weight for the active item instead of relying on a separate semantic utility.\n\n### Navigation\n\n`website/themes/sambee/assets/css/navigation.css` keeps `.nav-link` as a component-local role. It consumes shared tracking values so the navigation remains aligned with the site-wide label scale.\n\n### Buttons\n\n`website/themes/sambee/assets/css/buttons.css` keeps `.btn` and `.btn-sm` as local button primitives. They consume shared typography tokens where it makes sense, but buttons are not modeled as shared text-role utilities.\n\n### Footer\n\nFooter layout classes remain local in `website/themes/sambee/assets/css/footer.css`. Shared typography utilities still supply the text role where that role is reused across templates.\n\n### Content-Specific Typography\n\nArticle-content semantics such as table headers, `figcaption`, `dt`, and admonition titles remain local to `content.css`. They belong to the content domain, not to shared site-wide text roles.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "page:website-dev-guide/site-systems/managed-redirects", "parent_id": "section:website-dev-guide/site-systems", "depth": 2, "kind": "page", "label": "managed-redirects", "title": "Managed Redirects", "path": "website-dev-guide/site-systems/managed-redirects", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "authored"}, "1.0": {"state": "inherited", "source_version": "0.9"}, "2.0": {"state": "inherited", "source_version": "0.9"}}, "content_versions": {"0.9": "+++\ntitle = \"Managed Redirects\"\n+++\n\nManaged redirects provide stable `sambee.net` URLs for the product while allowing their destinations to change in a website deployment.\n\n## When To Use A Managed Redirect\n\nUse a managed redirect when product code, documentation, or external communication needs a durable public link whose destination may change. Product code should use a URL under `/mr/`, such as:\n\n```text\nhttps://sambee.net/mr/help-oidc-setup\n```\n\nDo not use a managed redirect for ordinary website navigation or a link whose destination is already a stable public contract.\n\n## Source Path Contract\n\nThe source path is immutable after release. Treat it as a public API:\n\n- Add a new path for each new long-lived product link.\n- Do not rename, remove, or reuse a released `/mr/` path.\n- Change the destination by updating its `target` value and deploying the website.\n\nManaged redirects use HTTP `302`, not `301`. This prevents browsers and intermediaries from permanently caching an old destination after the target changes.\n\n## Add A Redirect\n\nAdd an entry to `website/data/managed-redirects.toml`:\n\n```toml\n[[redirects]]\nid = \"help-oidc-setup\"\nsource = \"/mr/help-oidc-setup\"\ntarget = \"https://sambee.net/docs/admin-guide/authentication/openid-connect-authentication-setup/\"\n```\n\nEach entry requires:\n\n- A unique `id` for review and maintenance.\n- A unique literal `source` that starts with `/mr/` and has no trailing slash, query, fragment, or wildcard.\n- An absolute HTTPS `target` without credentials.\n\nThe source path is the immutable contract. Only `target` is expected to change after release.\n\n## Build Behavior\n\n`npm run redirects:generate` validates the registry and appends managed rules to the built `public/_redirects` artifact. The generator leaves `website/static/_redirects` unchanged because that file remains the source of legacy documentation redirects.\n\nThe normal website build and deployment workflow runs the generator automatically. To check the generated rules locally after a Hugo build, run:\n\n```bash\ncd website\nnpm run redirects:generate\n```\n\nThe generator fails the build when an entry is malformed, duplicates an ID or source path, or conflicts with an existing legacy redirect rule.\n\n", "1.0": "+++\ntitle = \"Managed Redirects\"\n+++\n\nManaged redirects provide stable `sambee.net` URLs for the product while allowing their destinations to change in a website deployment.\n\n## When To Use A Managed Redirect\n\nUse a managed redirect when product code, documentation, or external communication needs a durable public link whose destination may change. Product code should use a URL under `/mr/`, such as:\n\n```text\nhttps://sambee.net/mr/help-oidc-setup\n```\n\nDo not use a managed redirect for ordinary website navigation or a link whose destination is already a stable public contract.\n\n## Source Path Contract\n\nThe source path is immutable after release. Treat it as a public API:\n\n- Add a new path for each new long-lived product link.\n- Do not rename, remove, or reuse a released `/mr/` path.\n- Change the destination by updating its `target` value and deploying the website.\n\nManaged redirects use HTTP `302`, not `301`. This prevents browsers and intermediaries from permanently caching an old destination after the target changes.\n\n## Add A Redirect\n\nAdd an entry to `website/data/managed-redirects.toml`:\n\n```toml\n[[redirects]]\nid = \"help-oidc-setup\"\nsource = \"/mr/help-oidc-setup\"\ntarget = \"https://sambee.net/docs/admin-guide/authentication/openid-connect-authentication-setup/\"\n```\n\nEach entry requires:\n\n- A unique `id` for review and maintenance.\n- A unique literal `source` that starts with `/mr/` and has no trailing slash, query, fragment, or wildcard.\n- An absolute HTTPS `target` without credentials.\n\nThe source path is the immutable contract. Only `target` is expected to change after release.\n\n## Build Behavior\n\n`npm run redirects:generate` validates the registry and appends managed rules to the built `public/_redirects` artifact. The generator leaves `website/static/_redirects` unchanged because that file remains the source of legacy documentation redirects.\n\nThe normal website build and deployment workflow runs the generator automatically. To check the generated rules locally after a Hugo build, run:\n\n```bash\ncd website\nnpm run redirects:generate\n```\n\nThe generator fails the build when an entry is malformed, duplicates an ID or source path, or conflicts with an existing legacy redirect rule.\n\n", "2.0": "+++\ntitle = \"Managed Redirects\"\n+++\n\nManaged redirects provide stable `sambee.net` URLs for the product while allowing their destinations to change in a website deployment.\n\n## When To Use A Managed Redirect\n\nUse a managed redirect when product code, documentation, or external communication needs a durable public link whose destination may change. Product code should use a URL under `/mr/`, such as:\n\n```text\nhttps://sambee.net/mr/help-oidc-setup\n```\n\nDo not use a managed redirect for ordinary website navigation or a link whose destination is already a stable public contract.\n\n## Source Path Contract\n\nThe source path is immutable after release. Treat it as a public API:\n\n- Add a new path for each new long-lived product link.\n- Do not rename, remove, or reuse a released `/mr/` path.\n- Change the destination by updating its `target` value and deploying the website.\n\nManaged redirects use HTTP `302`, not `301`. This prevents browsers and intermediaries from permanently caching an old destination after the target changes.\n\n## Add A Redirect\n\nAdd an entry to `website/data/managed-redirects.toml`:\n\n```toml\n[[redirects]]\nid = \"help-oidc-setup\"\nsource = \"/mr/help-oidc-setup\"\ntarget = \"https://sambee.net/docs/admin-guide/authentication/openid-connect-authentication-setup/\"\n```\n\nEach entry requires:\n\n- A unique `id` for review and maintenance.\n- A unique literal `source` that starts with `/mr/` and has no trailing slash, query, fragment, or wildcard.\n- An absolute HTTPS `target` without credentials.\n\nThe source path is the immutable contract. Only `target` is expected to change after release.\n\n## Build Behavior\n\n`npm run redirects:generate` validates the registry and appends managed rules to the built `public/_redirects` artifact. The generator leaves `website/static/_redirects` unchanged because that file remains the source of legacy documentation redirects.\n\nThe normal website build and deployment workflow runs the generator automatically. To check the generated rules locally after a Hugo build, run:\n\n```bash\ncd website\nnpm run redirects:generate\n```\n\nThe generator fails the build when an entry is malformed, duplicates an ID or source path, or conflicts with an existing legacy redirect rule.\n\n"}, "page_contents": {"0.9": "+++\ntitle = \"Managed Redirects\"\n+++\n\nManaged redirects provide stable `sambee.net` URLs for the product while allowing their destinations to change in a website deployment.\n\n## When To Use A Managed Redirect\n\nUse a managed redirect when product code, documentation, or external communication needs a durable public link whose destination may change. Product code should use a URL under `/mr/`, such as:\n\n```text\nhttps://sambee.net/mr/help-oidc-setup\n```\n\nDo not use a managed redirect for ordinary website navigation or a link whose destination is already a stable public contract.\n\n## Source Path Contract\n\nThe source path is immutable after release. Treat it as a public API:\n\n- Add a new path for each new long-lived product link.\n- Do not rename, remove, or reuse a released `/mr/` path.\n- Change the destination by updating its `target` value and deploying the website.\n\nManaged redirects use HTTP `302`, not `301`. This prevents browsers and intermediaries from permanently caching an old destination after the target changes.\n\n## Add A Redirect\n\nAdd an entry to `website/data/managed-redirects.toml`:\n\n```toml\n[[redirects]]\nid = \"help-oidc-setup\"\nsource = \"/mr/help-oidc-setup\"\ntarget = \"https://sambee.net/docs/admin-guide/authentication/openid-connect-authentication-setup/\"\n```\n\nEach entry requires:\n\n- A unique `id` for review and maintenance.\n- A unique literal `source` that starts with `/mr/` and has no trailing slash, query, fragment, or wildcard.\n- An absolute HTTPS `target` without credentials.\n\nThe source path is the immutable contract. Only `target` is expected to change after release.\n\n## Build Behavior\n\n`npm run redirects:generate` validates the registry and appends managed rules to the built `public/_redirects` artifact. The generator leaves `website/static/_redirects` unchanged because that file remains the source of legacy documentation redirects.\n\nThe normal website build and deployment workflow runs the generator automatically. To check the generated rules locally after a Hugo build, run:\n\n```bash\ncd website\nnpm run redirects:generate\n```\n\nThe generator fails the build when an entry is malformed, duplicates an ID or source path, or conflicts with an existing legacy redirect rule.\n\n", "1.0": "+++\ntitle = \"Managed Redirects\"\n+++\n\nManaged redirects provide stable `sambee.net` URLs for the product while allowing their destinations to change in a website deployment.\n\n## When To Use A Managed Redirect\n\nUse a managed redirect when product code, documentation, or external communication needs a durable public link whose destination may change. Product code should use a URL under `/mr/`, such as:\n\n```text\nhttps://sambee.net/mr/help-oidc-setup\n```\n\nDo not use a managed redirect for ordinary website navigation or a link whose destination is already a stable public contract.\n\n## Source Path Contract\n\nThe source path is immutable after release. Treat it as a public API:\n\n- Add a new path for each new long-lived product link.\n- Do not rename, remove, or reuse a released `/mr/` path.\n- Change the destination by updating its `target` value and deploying the website.\n\nManaged redirects use HTTP `302`, not `301`. This prevents browsers and intermediaries from permanently caching an old destination after the target changes.\n\n## Add A Redirect\n\nAdd an entry to `website/data/managed-redirects.toml`:\n\n```toml\n[[redirects]]\nid = \"help-oidc-setup\"\nsource = \"/mr/help-oidc-setup\"\ntarget = \"https://sambee.net/docs/admin-guide/authentication/openid-connect-authentication-setup/\"\n```\n\nEach entry requires:\n\n- A unique `id` for review and maintenance.\n- A unique literal `source` that starts with `/mr/` and has no trailing slash, query, fragment, or wildcard.\n- An absolute HTTPS `target` without credentials.\n\nThe source path is the immutable contract. Only `target` is expected to change after release.\n\n## Build Behavior\n\n`npm run redirects:generate` validates the registry and appends managed rules to the built `public/_redirects` artifact. The generator leaves `website/static/_redirects` unchanged because that file remains the source of legacy documentation redirects.\n\nThe normal website build and deployment workflow runs the generator automatically. To check the generated rules locally after a Hugo build, run:\n\n```bash\ncd website\nnpm run redirects:generate\n```\n\nThe generator fails the build when an entry is malformed, duplicates an ID or source path, or conflicts with an existing legacy redirect rule.\n\n", "2.0": "+++\ntitle = \"Managed Redirects\"\n+++\n\nManaged redirects provide stable `sambee.net` URLs for the product while allowing their destinations to change in a website deployment.\n\n## When To Use A Managed Redirect\n\nUse a managed redirect when product code, documentation, or external communication needs a durable public link whose destination may change. Product code should use a URL under `/mr/`, such as:\n\n```text\nhttps://sambee.net/mr/help-oidc-setup\n```\n\nDo not use a managed redirect for ordinary website navigation or a link whose destination is already a stable public contract.\n\n## Source Path Contract\n\nThe source path is immutable after release. Treat it as a public API:\n\n- Add a new path for each new long-lived product link.\n- Do not rename, remove, or reuse a released `/mr/` path.\n- Change the destination by updating its `target` value and deploying the website.\n\nManaged redirects use HTTP `302`, not `301`. This prevents browsers and intermediaries from permanently caching an old destination after the target changes.\n\n## Add A Redirect\n\nAdd an entry to `website/data/managed-redirects.toml`:\n\n```toml\n[[redirects]]\nid = \"help-oidc-setup\"\nsource = \"/mr/help-oidc-setup\"\ntarget = \"https://sambee.net/docs/admin-guide/authentication/openid-connect-authentication-setup/\"\n```\n\nEach entry requires:\n\n- A unique `id` for review and maintenance.\n- A unique literal `source` that starts with `/mr/` and has no trailing slash, query, fragment, or wildcard.\n- An absolute HTTPS `target` without credentials.\n\nThe source path is the immutable contract. Only `target` is expected to change after release.\n\n## Build Behavior\n\n`npm run redirects:generate` validates the registry and appends managed rules to the built `public/_redirects` artifact. The generator leaves `website/static/_redirects` unchanged because that file remains the source of legacy documentation redirects.\n\nThe normal website build and deployment workflow runs the generator automatically. To check the generated rules locally after a Hugo build, run:\n\n```bash\ncd website\nnpm run redirects:generate\n```\n\nThe generator fails the build when an entry is malformed, duplicates an ID or source path, or conflicts with an existing legacy redirect rule.\n\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "section:website-dev-guide/setup-and-operations", "parent_id": "book:website-dev-guide", "depth": 1, "kind": "section", "label": "setup-and-operations", "title": "Setup and Operations", "path": "website-dev-guide/setup-and-operations", "has_children": true, "version_cells": {"0.7": {"state": "structural-only"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:website-dev-guide/setup-and-operations/set-up-cloudflare-pages-publishing", "parent_id": "section:website-dev-guide/setup-and-operations", "depth": 2, "kind": "page", "label": "set-up-cloudflare-pages-publishing", "title": "Set Up Cloudflare Pages Publishing", "path": "website-dev-guide/setup-and-operations/set-up-cloudflare-pages-publishing", "has_children": false, "version_cells": {"0.7": {"state": "authored"}, "0.8": {"state": "inherited", "source_version": "0.7"}, "0.9": {"state": "inherited", "source_version": "0.7"}, "1.0": {"state": "inherited", "source_version": "0.7"}, "2.0": {"state": "inherited", "source_version": "0.7"}}, "content_versions": {"0.7": "+++\ntitle = \"Set Up Cloudflare Pages Publishing\"\n+++\n\nUse this page to set up and maintain the website deployment workflow that publishes built website assets to Cloudflare Pages.\n\n## Overview\n\nThe repository uses a split deployment model:\n\n- Hugo builds the site into `website/public/`.\n- Built assets are published from there to Cloudflare Pages.\n- Source images and generated WebP derivatives remain in Git LFS.\n\nThe workflow builds on pull requests and pushes to `main`. The deploy job runs only on `main`.\n\n## Prepare Cloudflare\n\nComplete these Cloudflare steps first, then add the collected values to GitHub in the next section.\n\n1. Create a Cloudflare Pages project to receive the built HTML from `website/public/`:\n   - Go to **Workers \u0026 Pages** \u003e **Create application**\n   - Select **Looking to deploy Pages? Get started** \u003e **Drag and drop your files - Get started**\n   - Project name: `sambee-net` (to be stored in `CLOUDFLARE_PAGES_PROJECT`)\n   - Select **Create project**\n1. Go to the Pages project properties and set up a custom domain.\n1. In **My Profile** \u003e **API Tokens**, create a separate Cloudflare API token for the Pages deployment step:\n   - Name: `GitHub Actions - deploy Pages - sambee.net`\n   - Permissions: Account, Cloudflare Pages, edit\n1. Save that Pages API token for `CLOUDFLARE_API_TOKEN`\n1. Extract the Cloudflare account ID for the account that owns the Pages project from the URL: `https://dash.cloudflare.com/ACCOUNT_ID/home/overview`\n\n## Add GitHub Secrets\n\nAfter Cloudflare is ready, open the GitHub repository settings, go to **Secrets and variables** \u003e **Actions**, and add these repository secrets:\n\n- `CLOUDFLARE_API_TOKEN` for the Cloudflare API token used by the Pages deploy step.\n- `CLOUDFLARE_ACCOUNT_ID` for the Cloudflare account that owns the Pages project.\n- `CLOUDFLARE_PAGES_PROJECT` for the Cloudflare Pages project name passed to `wrangler pages deploy`.\n\n## CI Deploy\n\nThe deploy job publishes `website/public` to Cloudflare Pages from the `main` branch.\n\n## Repository Preconditions\n\nBefore deployment can publish correct media:\n\n- Source images live under `website/assets/images/`.\n- Generated WebP derivatives are committed in sibling `generated/` directories.\n- Downloadable files live under `website/static/files/`.\n- `npm run images:validate` passes.\n- The site build produces `website/public/images/` and `website/public/files/`.\n\nFor local verification:\n\n```bash\ncd website\ngit lfs pull\nnpm ci\nnpm run build\n```\n\n## Current Asset Behavior\n\nThe generated site still uses site-relative asset paths such as `/images/...` and `/files/...`.\n\nThat means this workflow deploys the website to Cloudflare Pages, but it does not rewrite asset URLs to a separate CDN hostname.\n", "0.8": "+++\ntitle = \"Set Up Cloudflare Pages Publishing\"\n+++\n\nUse this page to set up and maintain the website deployment workflow that publishes built website assets to Cloudflare Pages.\n\n## Overview\n\nThe repository uses a split deployment model:\n\n- Hugo builds the site into `website/public/`.\n- Built assets are published from there to Cloudflare Pages.\n- Source images and generated WebP derivatives remain in Git LFS.\n\nThe workflow builds on pull requests and pushes to `main`. The deploy job runs only on `main`.\n\n## Prepare Cloudflare\n\nComplete these Cloudflare steps first, then add the collected values to GitHub in the next section.\n\n1. Create a Cloudflare Pages project to receive the built HTML from `website/public/`:\n   - Go to **Workers \u0026 Pages** \u003e **Create application**\n   - Select **Looking to deploy Pages? Get started** \u003e **Drag and drop your files - Get started**\n   - Project name: `sambee-net` (to be stored in `CLOUDFLARE_PAGES_PROJECT`)\n   - Select **Create project**\n1. Go to the Pages project properties and set up a custom domain.\n1. In **My Profile** \u003e **API Tokens**, create a separate Cloudflare API token for the Pages deployment step:\n   - Name: `GitHub Actions - deploy Pages - sambee.net`\n   - Permissions: Account, Cloudflare Pages, edit\n1. Save that Pages API token for `CLOUDFLARE_API_TOKEN`\n1. Extract the Cloudflare account ID for the account that owns the Pages project from the URL: `https://dash.cloudflare.com/ACCOUNT_ID/home/overview`\n\n## Add GitHub Secrets\n\nAfter Cloudflare is ready, open the GitHub repository settings, go to **Secrets and variables** \u003e **Actions**, and add these repository secrets:\n\n- `CLOUDFLARE_API_TOKEN` for the Cloudflare API token used by the Pages deploy step.\n- `CLOUDFLARE_ACCOUNT_ID` for the Cloudflare account that owns the Pages project.\n- `CLOUDFLARE_PAGES_PROJECT` for the Cloudflare Pages project name passed to `wrangler pages deploy`.\n\n## CI Deploy\n\nThe deploy job publishes `website/public` to Cloudflare Pages from the `main` branch.\n\n## Repository Preconditions\n\nBefore deployment can publish correct media:\n\n- Source images live under `website/assets/images/`.\n- Generated WebP derivatives are committed in sibling `generated/` directories.\n- Downloadable files live under `website/static/files/`.\n- `npm run images:validate` passes.\n- The site build produces `website/public/images/` and `website/public/files/`.\n\nFor local verification:\n\n```bash\ncd website\ngit lfs pull\nnpm ci\nnpm run build\n```\n\n## Current Asset Behavior\n\nThe generated site still uses site-relative asset paths such as `/images/...` and `/files/...`.\n\nThat means this workflow deploys the website to Cloudflare Pages, but it does not rewrite asset URLs to a separate CDN hostname.\n", "0.9": "+++\ntitle = \"Set Up Cloudflare Pages Publishing\"\n+++\n\nUse this page to set up and maintain the website deployment workflow that publishes built website assets to Cloudflare Pages.\n\n## Overview\n\nThe repository uses a split deployment model:\n\n- Hugo builds the site into `website/public/`.\n- Built assets are published from there to Cloudflare Pages.\n- Source images and generated WebP derivatives remain in Git LFS.\n\nThe workflow builds on pull requests and pushes to `main`. The deploy job runs only on `main`.\n\n## Prepare Cloudflare\n\nComplete these Cloudflare steps first, then add the collected values to GitHub in the next section.\n\n1. Create a Cloudflare Pages project to receive the built HTML from `website/public/`:\n   - Go to **Workers \u0026 Pages** \u003e **Create application**\n   - Select **Looking to deploy Pages? Get started** \u003e **Drag and drop your files - Get started**\n   - Project name: `sambee-net` (to be stored in `CLOUDFLARE_PAGES_PROJECT`)\n   - Select **Create project**\n1. Go to the Pages project properties and set up a custom domain.\n1. In **My Profile** \u003e **API Tokens**, create a separate Cloudflare API token for the Pages deployment step:\n   - Name: `GitHub Actions - deploy Pages - sambee.net`\n   - Permissions: Account, Cloudflare Pages, edit\n1. Save that Pages API token for `CLOUDFLARE_API_TOKEN`\n1. Extract the Cloudflare account ID for the account that owns the Pages project from the URL: `https://dash.cloudflare.com/ACCOUNT_ID/home/overview`\n\n## Add GitHub Secrets\n\nAfter Cloudflare is ready, open the GitHub repository settings, go to **Secrets and variables** \u003e **Actions**, and add these repository secrets:\n\n- `CLOUDFLARE_API_TOKEN` for the Cloudflare API token used by the Pages deploy step.\n- `CLOUDFLARE_ACCOUNT_ID` for the Cloudflare account that owns the Pages project.\n- `CLOUDFLARE_PAGES_PROJECT` for the Cloudflare Pages project name passed to `wrangler pages deploy`.\n\n## CI Deploy\n\nThe deploy job publishes `website/public` to Cloudflare Pages from the `main` branch.\n\n## Repository Preconditions\n\nBefore deployment can publish correct media:\n\n- Source images live under `website/assets/images/`.\n- Generated WebP derivatives are committed in sibling `generated/` directories.\n- Downloadable files live under `website/static/files/`.\n- `npm run images:validate` passes.\n- The site build produces `website/public/images/` and `website/public/files/`.\n\nFor local verification:\n\n```bash\ncd website\ngit lfs pull\nnpm ci\nnpm run build\n```\n\n## Current Asset Behavior\n\nThe generated site still uses site-relative asset paths such as `/images/...` and `/files/...`.\n\nThat means this workflow deploys the website to Cloudflare Pages, but it does not rewrite asset URLs to a separate CDN hostname.\n", "1.0": "+++\ntitle = \"Set Up Cloudflare Pages Publishing\"\n+++\n\nUse this page to set up and maintain the website deployment workflow that publishes built website assets to Cloudflare Pages.\n\n## Overview\n\nThe repository uses a split deployment model:\n\n- Hugo builds the site into `website/public/`.\n- Built assets are published from there to Cloudflare Pages.\n- Source images and generated WebP derivatives remain in Git LFS.\n\nThe workflow builds on pull requests and pushes to `main`. The deploy job runs only on `main`.\n\n## Prepare Cloudflare\n\nComplete these Cloudflare steps first, then add the collected values to GitHub in the next section.\n\n1. Create a Cloudflare Pages project to receive the built HTML from `website/public/`:\n   - Go to **Workers \u0026 Pages** \u003e **Create application**\n   - Select **Looking to deploy Pages? Get started** \u003e **Drag and drop your files - Get started**\n   - Project name: `sambee-net` (to be stored in `CLOUDFLARE_PAGES_PROJECT`)\n   - Select **Create project**\n1. Go to the Pages project properties and set up a custom domain.\n1. In **My Profile** \u003e **API Tokens**, create a separate Cloudflare API token for the Pages deployment step:\n   - Name: `GitHub Actions - deploy Pages - sambee.net`\n   - Permissions: Account, Cloudflare Pages, edit\n1. Save that Pages API token for `CLOUDFLARE_API_TOKEN`\n1. Extract the Cloudflare account ID for the account that owns the Pages project from the URL: `https://dash.cloudflare.com/ACCOUNT_ID/home/overview`\n\n## Add GitHub Secrets\n\nAfter Cloudflare is ready, open the GitHub repository settings, go to **Secrets and variables** \u003e **Actions**, and add these repository secrets:\n\n- `CLOUDFLARE_API_TOKEN` for the Cloudflare API token used by the Pages deploy step.\n- `CLOUDFLARE_ACCOUNT_ID` for the Cloudflare account that owns the Pages project.\n- `CLOUDFLARE_PAGES_PROJECT` for the Cloudflare Pages project name passed to `wrangler pages deploy`.\n\n## CI Deploy\n\nThe deploy job publishes `website/public` to Cloudflare Pages from the `main` branch.\n\n## Repository Preconditions\n\nBefore deployment can publish correct media:\n\n- Source images live under `website/assets/images/`.\n- Generated WebP derivatives are committed in sibling `generated/` directories.\n- Downloadable files live under `website/static/files/`.\n- `npm run images:validate` passes.\n- The site build produces `website/public/images/` and `website/public/files/`.\n\nFor local verification:\n\n```bash\ncd website\ngit lfs pull\nnpm ci\nnpm run build\n```\n\n## Current Asset Behavior\n\nThe generated site still uses site-relative asset paths such as `/images/...` and `/files/...`.\n\nThat means this workflow deploys the website to Cloudflare Pages, but it does not rewrite asset URLs to a separate CDN hostname.\n", "2.0": "+++\ntitle = \"Set Up Cloudflare Pages Publishing\"\n+++\n\nUse this page to set up and maintain the website deployment workflow that publishes built website assets to Cloudflare Pages.\n\n## Overview\n\nThe repository uses a split deployment model:\n\n- Hugo builds the site into `website/public/`.\n- Built assets are published from there to Cloudflare Pages.\n- Source images and generated WebP derivatives remain in Git LFS.\n\nThe workflow builds on pull requests and pushes to `main`. The deploy job runs only on `main`.\n\n## Prepare Cloudflare\n\nComplete these Cloudflare steps first, then add the collected values to GitHub in the next section.\n\n1. Create a Cloudflare Pages project to receive the built HTML from `website/public/`:\n   - Go to **Workers \u0026 Pages** \u003e **Create application**\n   - Select **Looking to deploy Pages? Get started** \u003e **Drag and drop your files - Get started**\n   - Project name: `sambee-net` (to be stored in `CLOUDFLARE_PAGES_PROJECT`)\n   - Select **Create project**\n1. Go to the Pages project properties and set up a custom domain.\n1. In **My Profile** \u003e **API Tokens**, create a separate Cloudflare API token for the Pages deployment step:\n   - Name: `GitHub Actions - deploy Pages - sambee.net`\n   - Permissions: Account, Cloudflare Pages, edit\n1. Save that Pages API token for `CLOUDFLARE_API_TOKEN`\n1. Extract the Cloudflare account ID for the account that owns the Pages project from the URL: `https://dash.cloudflare.com/ACCOUNT_ID/home/overview`\n\n## Add GitHub Secrets\n\nAfter Cloudflare is ready, open the GitHub repository settings, go to **Secrets and variables** \u003e **Actions**, and add these repository secrets:\n\n- `CLOUDFLARE_API_TOKEN` for the Cloudflare API token used by the Pages deploy step.\n- `CLOUDFLARE_ACCOUNT_ID` for the Cloudflare account that owns the Pages project.\n- `CLOUDFLARE_PAGES_PROJECT` for the Cloudflare Pages project name passed to `wrangler pages deploy`.\n\n## CI Deploy\n\nThe deploy job publishes `website/public` to Cloudflare Pages from the `main` branch.\n\n## Repository Preconditions\n\nBefore deployment can publish correct media:\n\n- Source images live under `website/assets/images/`.\n- Generated WebP derivatives are committed in sibling `generated/` directories.\n- Downloadable files live under `website/static/files/`.\n- `npm run images:validate` passes.\n- The site build produces `website/public/images/` and `website/public/files/`.\n\nFor local verification:\n\n```bash\ncd website\ngit lfs pull\nnpm ci\nnpm run build\n```\n\n## Current Asset Behavior\n\nThe generated site still uses site-relative asset paths such as `/images/...` and `/files/...`.\n\nThat means this workflow deploys the website to Cloudflare Pages, but it does not rewrite asset URLs to a separate CDN hostname.\n"}, "page_contents": {"0.7": "+++\ntitle = \"Set Up Cloudflare Pages Publishing\"\n+++\n\nUse this page to set up and maintain the website deployment workflow that publishes built website assets to Cloudflare Pages.\n\n## Overview\n\nThe repository uses a split deployment model:\n\n- Hugo builds the site into `website/public/`.\n- Built assets are published from there to Cloudflare Pages.\n- Source images and generated WebP derivatives remain in Git LFS.\n\nThe workflow builds on pull requests and pushes to `main`. The deploy job runs only on `main`.\n\n## Prepare Cloudflare\n\nComplete these Cloudflare steps first, then add the collected values to GitHub in the next section.\n\n1. Create a Cloudflare Pages project to receive the built HTML from `website/public/`:\n   - Go to **Workers \u0026 Pages** \u003e **Create application**\n   - Select **Looking to deploy Pages? Get started** \u003e **Drag and drop your files - Get started**\n   - Project name: `sambee-net` (to be stored in `CLOUDFLARE_PAGES_PROJECT`)\n   - Select **Create project**\n1. Go to the Pages project properties and set up a custom domain.\n1. In **My Profile** \u003e **API Tokens**, create a separate Cloudflare API token for the Pages deployment step:\n   - Name: `GitHub Actions - deploy Pages - sambee.net`\n   - Permissions: Account, Cloudflare Pages, edit\n1. Save that Pages API token for `CLOUDFLARE_API_TOKEN`\n1. Extract the Cloudflare account ID for the account that owns the Pages project from the URL: `https://dash.cloudflare.com/ACCOUNT_ID/home/overview`\n\n## Add GitHub Secrets\n\nAfter Cloudflare is ready, open the GitHub repository settings, go to **Secrets and variables** \u003e **Actions**, and add these repository secrets:\n\n- `CLOUDFLARE_API_TOKEN` for the Cloudflare API token used by the Pages deploy step.\n- `CLOUDFLARE_ACCOUNT_ID` for the Cloudflare account that owns the Pages project.\n- `CLOUDFLARE_PAGES_PROJECT` for the Cloudflare Pages project name passed to `wrangler pages deploy`.\n\n## CI Deploy\n\nThe deploy job publishes `website/public` to Cloudflare Pages from the `main` branch.\n\n## Repository Preconditions\n\nBefore deployment can publish correct media:\n\n- Source images live under `website/assets/images/`.\n- Generated WebP derivatives are committed in sibling `generated/` directories.\n- Downloadable files live under `website/static/files/`.\n- `npm run images:validate` passes.\n- The site build produces `website/public/images/` and `website/public/files/`.\n\nFor local verification:\n\n```bash\ncd website\ngit lfs pull\nnpm ci\nnpm run build\n```\n\n## Current Asset Behavior\n\nThe generated site still uses site-relative asset paths such as `/images/...` and `/files/...`.\n\nThat means this workflow deploys the website to Cloudflare Pages, but it does not rewrite asset URLs to a separate CDN hostname.\n", "0.8": "+++\ntitle = \"Set Up Cloudflare Pages Publishing\"\n+++\n\nUse this page to set up and maintain the website deployment workflow that publishes built website assets to Cloudflare Pages.\n\n## Overview\n\nThe repository uses a split deployment model:\n\n- Hugo builds the site into `website/public/`.\n- Built assets are published from there to Cloudflare Pages.\n- Source images and generated WebP derivatives remain in Git LFS.\n\nThe workflow builds on pull requests and pushes to `main`. The deploy job runs only on `main`.\n\n## Prepare Cloudflare\n\nComplete these Cloudflare steps first, then add the collected values to GitHub in the next section.\n\n1. Create a Cloudflare Pages project to receive the built HTML from `website/public/`:\n   - Go to **Workers \u0026 Pages** \u003e **Create application**\n   - Select **Looking to deploy Pages? Get started** \u003e **Drag and drop your files - Get started**\n   - Project name: `sambee-net` (to be stored in `CLOUDFLARE_PAGES_PROJECT`)\n   - Select **Create project**\n1. Go to the Pages project properties and set up a custom domain.\n1. In **My Profile** \u003e **API Tokens**, create a separate Cloudflare API token for the Pages deployment step:\n   - Name: `GitHub Actions - deploy Pages - sambee.net`\n   - Permissions: Account, Cloudflare Pages, edit\n1. Save that Pages API token for `CLOUDFLARE_API_TOKEN`\n1. Extract the Cloudflare account ID for the account that owns the Pages project from the URL: `https://dash.cloudflare.com/ACCOUNT_ID/home/overview`\n\n## Add GitHub Secrets\n\nAfter Cloudflare is ready, open the GitHub repository settings, go to **Secrets and variables** \u003e **Actions**, and add these repository secrets:\n\n- `CLOUDFLARE_API_TOKEN` for the Cloudflare API token used by the Pages deploy step.\n- `CLOUDFLARE_ACCOUNT_ID` for the Cloudflare account that owns the Pages project.\n- `CLOUDFLARE_PAGES_PROJECT` for the Cloudflare Pages project name passed to `wrangler pages deploy`.\n\n## CI Deploy\n\nThe deploy job publishes `website/public` to Cloudflare Pages from the `main` branch.\n\n## Repository Preconditions\n\nBefore deployment can publish correct media:\n\n- Source images live under `website/assets/images/`.\n- Generated WebP derivatives are committed in sibling `generated/` directories.\n- Downloadable files live under `website/static/files/`.\n- `npm run images:validate` passes.\n- The site build produces `website/public/images/` and `website/public/files/`.\n\nFor local verification:\n\n```bash\ncd website\ngit lfs pull\nnpm ci\nnpm run build\n```\n\n## Current Asset Behavior\n\nThe generated site still uses site-relative asset paths such as `/images/...` and `/files/...`.\n\nThat means this workflow deploys the website to Cloudflare Pages, but it does not rewrite asset URLs to a separate CDN hostname.\n", "0.9": "+++\ntitle = \"Set Up Cloudflare Pages Publishing\"\n+++\n\nUse this page to set up and maintain the website deployment workflow that publishes built website assets to Cloudflare Pages.\n\n## Overview\n\nThe repository uses a split deployment model:\n\n- Hugo builds the site into `website/public/`.\n- Built assets are published from there to Cloudflare Pages.\n- Source images and generated WebP derivatives remain in Git LFS.\n\nThe workflow builds on pull requests and pushes to `main`. The deploy job runs only on `main`.\n\n## Prepare Cloudflare\n\nComplete these Cloudflare steps first, then add the collected values to GitHub in the next section.\n\n1. Create a Cloudflare Pages project to receive the built HTML from `website/public/`:\n   - Go to **Workers \u0026 Pages** \u003e **Create application**\n   - Select **Looking to deploy Pages? Get started** \u003e **Drag and drop your files - Get started**\n   - Project name: `sambee-net` (to be stored in `CLOUDFLARE_PAGES_PROJECT`)\n   - Select **Create project**\n1. Go to the Pages project properties and set up a custom domain.\n1. In **My Profile** \u003e **API Tokens**, create a separate Cloudflare API token for the Pages deployment step:\n   - Name: `GitHub Actions - deploy Pages - sambee.net`\n   - Permissions: Account, Cloudflare Pages, edit\n1. Save that Pages API token for `CLOUDFLARE_API_TOKEN`\n1. Extract the Cloudflare account ID for the account that owns the Pages project from the URL: `https://dash.cloudflare.com/ACCOUNT_ID/home/overview`\n\n## Add GitHub Secrets\n\nAfter Cloudflare is ready, open the GitHub repository settings, go to **Secrets and variables** \u003e **Actions**, and add these repository secrets:\n\n- `CLOUDFLARE_API_TOKEN` for the Cloudflare API token used by the Pages deploy step.\n- `CLOUDFLARE_ACCOUNT_ID` for the Cloudflare account that owns the Pages project.\n- `CLOUDFLARE_PAGES_PROJECT` for the Cloudflare Pages project name passed to `wrangler pages deploy`.\n\n## CI Deploy\n\nThe deploy job publishes `website/public` to Cloudflare Pages from the `main` branch.\n\n## Repository Preconditions\n\nBefore deployment can publish correct media:\n\n- Source images live under `website/assets/images/`.\n- Generated WebP derivatives are committed in sibling `generated/` directories.\n- Downloadable files live under `website/static/files/`.\n- `npm run images:validate` passes.\n- The site build produces `website/public/images/` and `website/public/files/`.\n\nFor local verification:\n\n```bash\ncd website\ngit lfs pull\nnpm ci\nnpm run build\n```\n\n## Current Asset Behavior\n\nThe generated site still uses site-relative asset paths such as `/images/...` and `/files/...`.\n\nThat means this workflow deploys the website to Cloudflare Pages, but it does not rewrite asset URLs to a separate CDN hostname.\n", "1.0": "+++\ntitle = \"Set Up Cloudflare Pages Publishing\"\n+++\n\nUse this page to set up and maintain the website deployment workflow that publishes built website assets to Cloudflare Pages.\n\n## Overview\n\nThe repository uses a split deployment model:\n\n- Hugo builds the site into `website/public/`.\n- Built assets are published from there to Cloudflare Pages.\n- Source images and generated WebP derivatives remain in Git LFS.\n\nThe workflow builds on pull requests and pushes to `main`. The deploy job runs only on `main`.\n\n## Prepare Cloudflare\n\nComplete these Cloudflare steps first, then add the collected values to GitHub in the next section.\n\n1. Create a Cloudflare Pages project to receive the built HTML from `website/public/`:\n   - Go to **Workers \u0026 Pages** \u003e **Create application**\n   - Select **Looking to deploy Pages? Get started** \u003e **Drag and drop your files - Get started**\n   - Project name: `sambee-net` (to be stored in `CLOUDFLARE_PAGES_PROJECT`)\n   - Select **Create project**\n1. Go to the Pages project properties and set up a custom domain.\n1. In **My Profile** \u003e **API Tokens**, create a separate Cloudflare API token for the Pages deployment step:\n   - Name: `GitHub Actions - deploy Pages - sambee.net`\n   - Permissions: Account, Cloudflare Pages, edit\n1. Save that Pages API token for `CLOUDFLARE_API_TOKEN`\n1. Extract the Cloudflare account ID for the account that owns the Pages project from the URL: `https://dash.cloudflare.com/ACCOUNT_ID/home/overview`\n\n## Add GitHub Secrets\n\nAfter Cloudflare is ready, open the GitHub repository settings, go to **Secrets and variables** \u003e **Actions**, and add these repository secrets:\n\n- `CLOUDFLARE_API_TOKEN` for the Cloudflare API token used by the Pages deploy step.\n- `CLOUDFLARE_ACCOUNT_ID` for the Cloudflare account that owns the Pages project.\n- `CLOUDFLARE_PAGES_PROJECT` for the Cloudflare Pages project name passed to `wrangler pages deploy`.\n\n## CI Deploy\n\nThe deploy job publishes `website/public` to Cloudflare Pages from the `main` branch.\n\n## Repository Preconditions\n\nBefore deployment can publish correct media:\n\n- Source images live under `website/assets/images/`.\n- Generated WebP derivatives are committed in sibling `generated/` directories.\n- Downloadable files live under `website/static/files/`.\n- `npm run images:validate` passes.\n- The site build produces `website/public/images/` and `website/public/files/`.\n\nFor local verification:\n\n```bash\ncd website\ngit lfs pull\nnpm ci\nnpm run build\n```\n\n## Current Asset Behavior\n\nThe generated site still uses site-relative asset paths such as `/images/...` and `/files/...`.\n\nThat means this workflow deploys the website to Cloudflare Pages, but it does not rewrite asset URLs to a separate CDN hostname.\n", "2.0": "+++\ntitle = \"Set Up Cloudflare Pages Publishing\"\n+++\n\nUse this page to set up and maintain the website deployment workflow that publishes built website assets to Cloudflare Pages.\n\n## Overview\n\nThe repository uses a split deployment model:\n\n- Hugo builds the site into `website/public/`.\n- Built assets are published from there to Cloudflare Pages.\n- Source images and generated WebP derivatives remain in Git LFS.\n\nThe workflow builds on pull requests and pushes to `main`. The deploy job runs only on `main`.\n\n## Prepare Cloudflare\n\nComplete these Cloudflare steps first, then add the collected values to GitHub in the next section.\n\n1. Create a Cloudflare Pages project to receive the built HTML from `website/public/`:\n   - Go to **Workers \u0026 Pages** \u003e **Create application**\n   - Select **Looking to deploy Pages? Get started** \u003e **Drag and drop your files - Get started**\n   - Project name: `sambee-net` (to be stored in `CLOUDFLARE_PAGES_PROJECT`)\n   - Select **Create project**\n1. Go to the Pages project properties and set up a custom domain.\n1. In **My Profile** \u003e **API Tokens**, create a separate Cloudflare API token for the Pages deployment step:\n   - Name: `GitHub Actions - deploy Pages - sambee.net`\n   - Permissions: Account, Cloudflare Pages, edit\n1. Save that Pages API token for `CLOUDFLARE_API_TOKEN`\n1. Extract the Cloudflare account ID for the account that owns the Pages project from the URL: `https://dash.cloudflare.com/ACCOUNT_ID/home/overview`\n\n## Add GitHub Secrets\n\nAfter Cloudflare is ready, open the GitHub repository settings, go to **Secrets and variables** \u003e **Actions**, and add these repository secrets:\n\n- `CLOUDFLARE_API_TOKEN` for the Cloudflare API token used by the Pages deploy step.\n- `CLOUDFLARE_ACCOUNT_ID` for the Cloudflare account that owns the Pages project.\n- `CLOUDFLARE_PAGES_PROJECT` for the Cloudflare Pages project name passed to `wrangler pages deploy`.\n\n## CI Deploy\n\nThe deploy job publishes `website/public` to Cloudflare Pages from the `main` branch.\n\n## Repository Preconditions\n\nBefore deployment can publish correct media:\n\n- Source images live under `website/assets/images/`.\n- Generated WebP derivatives are committed in sibling `generated/` directories.\n- Downloadable files live under `website/static/files/`.\n- `npm run images:validate` passes.\n- The site build produces `website/public/images/` and `website/public/files/`.\n\nFor local verification:\n\n```bash\ncd website\ngit lfs pull\nnpm ci\nnpm run build\n```\n\n## Current Asset Behavior\n\nThe generated site still uses site-relative asset paths such as `/images/...` and `/files/...`.\n\nThat means this workflow deploys the website to Cloudflare Pages, but it does not rewrite asset URLs to a separate CDN hostname.\n"}, "flags": {"has_branched": false, "has_inherited": true, "has_structural": false, "has_invalid": false}}, {"id": "book:release-info", "parent_id": null, "depth": 0, "kind": "book", "label": "release-info", "title": "Release Info", "path": "release-info", "has_children": true, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "section:release-info/news-and-changes", "parent_id": "book:release-info", "depth": 1, "kind": "section", "label": "news-and-changes", "title": "News and Changes", "path": "release-info/news-and-changes", "has_children": true, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "structural-only"}, "0.9": {"state": "structural-only"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:release-info/news-and-changes/whats-new", "parent_id": "section:release-info/news-and-changes", "depth": 2, "kind": "page", "label": "whats-new", "title": "Whats New", "path": "release-info/news-and-changes/whats-new", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "authored"}, "0.9": {"state": "branched", "source_version": "0.8", "diff_added": 47, "diff_removed": 46}, "1.0": {"state": "branched", "source_version": "0.9", "diff_added": 113, "diff_removed": 46}, "2.0": {"state": "branched", "source_version": "1.0", "diff_added": 143, "diff_removed": 117}}, "content_versions": {"0.8": "+++\ntitle = \"What's New\"\n+++\n\n## Quick Bar: UX\n\nThe [quick bar](../../../user-guide/browsing-and-navigation/smart-navigation-and-the-quick-bar/) is Sambee's main navigation element. It sits in the top bar above the file list and is designed to be the single point of control for directory navigation, file list filtering, and command lookup and execution.\n\nPreviously, those three functions were not clearly distinguished. The three modes are now separated more distinctly, and the current mode is shown directly in the quick bar through a dedicated button. This makes the feature easier to discover and also allows users to switch modes with the mouse or by touch (in addition to the existing keyboard shortcuts).\n\nIn addition, several bugs were fixed to improve the overall experience.\n\n## Companion: More Secure Pairing \u0026 Communication Flows\n\nThis release makes Sambee Companion connections more secure, from the first pairing step through ongoing communication during local-drive access and desktop editing.\n\n**Pairing** is now tracked per Sambee site instead of through one global paired state. Pending approvals can be cancelled cleanly, and the browser now shows clearer states when Companion is unavailable, waiting for local approval, needs repair, or has lost its editing session.\n\nSambee also now trusts only the specific Sambee site you approved, limits what the local Companion service exposes, and uses narrower one-task-at-a-time edit credentials behind the scenes.\n\n**Native editing** is also more resilient. Sambee now uses tighter, task-specific edit permissions, renews long-running edit sessions when needed, and returns you to the browser with a clearer next step if sign-in, lock ownership, or recovery fails, instead of leaving you stuck with a vague error.\n\n## File Opening: Speed \u0026 Flexibility\n\nWhen opening files for previewing or editing, you want quick previews, but you also want the ability to choose which app a file is opened in. Both paths are now efficiently available:\n\nOpen files in Sambee's browser-based viewers:\n\n- Click a file or press \u003ckbd\u003eEnter\u003c/kbd\u003e to open it in Sambee's associated viewer.\n- If no associated viewer exists, or if you press \u003ckbd\u003eShift + Enter\u003c/kbd\u003e, a viewer picker dialog appears.\n   - The picker lets you choose a Sambee browser viewer or a native app.\n\nOpen files in natively installed apps:\n\n- Press \u003ckbd\u003eCtrl + Enter\u003c/kbd\u003e to open a file in its associated native app, or right-click it and select **Open in Native App**.\n- If no associated native app has been chosen, or if you press \u003ckbd\u003eCtrl + Alt + Enter\u003c/kbd\u003e, an app picker dialog appears.\n\n## Markdown Editor: Strategy Change\n\nThe WYSIWYG Markdown editor is gone for a simple reason: UX. There is no open-source rich-text (WYSIWYG) Markdown editor that provides a great user experience. The previous editor was not up to the task.\n\nThe better option is CodeMirror, one of the best available editors, configured for Markdown. It provides a first-rate editing experience and battle-tested add-ons for many of the quality-of-life features people have come to expect from modern editors.\n\n### Interactive Markdown Table Editing\n\nEditing Markdown in a text editor works well for headings and lists, but tables are different. Markdown table syntax is unwieldy, especially when inserting a column in the middle, and the source is difficult to scan. Tables need an interactive WYSIWYG interface that looks and feels like a spreadsheet application. Sambee provides exactly that.\n\n## Text File Viewer and Editor\n\nSince we already have an excellent text editor (see the Markdown Editor note), we might as well put it to good use as a generic text file editor. Sambee can now open, display, and edit any kind of text-based file, with all the bells and whistles of a first-rate editor, for example syntax highlighting.\n\n## Miscellaneous\n\n### Home Screen\n\n- Added a help button next to the settings (gear) icon.\n\n### File List\n\n- Increased the font size on mobile.\n\n### PDF Viewer\n\n- Intra-document links now work correctly, e.g. from a table of contents.\n\n### Under the Hood\n\n- Major dependency upgrades across the board, including React 19 and MUI 9.\n- Improved suspend, resume, and reload resilience.\n\n## Internals\n\n### Documentation System\n\nSambee has a best-in-class documentation system that deduplicates content, inheriting unchanged text copy through versions. This enables us to provide complete and accurate docs for each product version while minimizing maintenance effort.\n\nThis release adds a docs reporting and visualization tool that creates an HTML report of every docs book, section, and page, including its properties, such as whether it is inherited or branched. The report also has a diff view that highlights changes between any two document versions.\n\nDocs editor tool improvements include:\n\n- UI improvements, including better help output.\n- New commands to convert pages between inherited and independent: `page materialize` and `page inherit`.\n- A test and validation suite that also runs in CI.\n", "0.9": "+++\ntitle = \"What's New\"\n+++\n\n## OpenID Connect (OIDC) Authentication and Single Sign-On (SSO)\n\nSingle sign-on was on my list of essential features from the very beginning. Having one source of truth for authentication and authorization is of great benefit even in the smallest networks with single-digit user counts.\n\nSambee includes a secure and comprehensive implementation of OpenID Connect for authentication through IAM servers such as Authelia or Keycloak. If OIDC is configured as the only authentication method, SSO happens behind the scenes and is fully transparent to users who are already logged in to the IAM server. Otherwise, users trying to access Sambee are redirected to the IAM server to authenticate. Once that has happened, they're redirected back to Sambee.\n\nSambee's [OIDC implementation](../../../admin-guide/authentication/openid-connect-authentication-setup/) comes with auto-provisioning, which creates Sambee user accounts automatically after successful OIDC authentication. This can (and often should) be gated by group membership so that only members of a specific group are allowed access to Sambee. Similarly, Sambee's user roles are assigned depending on group membership. This makes it possible to centrally manage access to Sambee's user roles (e.g., admin) in your IAM system.\n\n### Authentication Configuration Change\n\nAuthentication mode is selected only in **Settings** \u003e **Administration** \u003e **Authentication** and defaults to **Password only** for a new installation. The configuration file can only disable enforcement temporarily with `[auth] disable_enforcement = true`; the stored UI mode remains unchanged.\n\nThis is a breaking configuration change. `auth_method` is rejected in both `[auth]` and `[security]`, and existing installations are not migrated automatically. Remove the retired key before upgrading.\n\n## Settings \u0026 Dialogs Overhaul\n\nThe settings got a good UX overhaul that should make them consistent, accessible and, hopefully, much nicer to look at. They're fully responsive, of course, adapting flexibly to phone and desktop screen dimensions. They're also very optimized for efficient keyboard usage while offering touch-friendly sizing on mobile devices.\n\n### New Settings\n\nThe settings also gained several new category pages:\n\n- New personal **Account** settings page\n- New admin **About** settings page\n- New admin **Authentication** settings page\n- New admin **Network** settings page\n- New admin **SMB** settings page\n\nThe about page comes with a feature that may come in handy: creating a **support report** with redacted diagnostic information that's safe to post online.\n\n### User Management Page: Visibility Update\n\nThe user management page in settings was reimplemented to provide significantly better visibility through search, filtering, sorting, summary shortcuts, and a more compact presentation.\n\n### Dialog Look \u0026 Feel\n\nThe refreshed and improved look and feel from settings was applied to the various dialogs that are shown when you copy, move, create, or delete files and/or directories. These dialogs now convey more information in a better way than before.\n\n## Dark Theme Polishing\n\nThe dark theme got a good new coat of paint. The colors of all elements, including backgrounds, text, menus, and dialogs, were tweaked to ensure visual clarity and eye-soothing contrasts.\n\n## Markdown Editor Improvements\n\n- Lists are normalized (formatted) when saved, using `-` for unordered lists and `1.` for every ordered-list item.\n- The editor updates to display the normalized Markdown written to disk after a successful save.\n- Unsaved edits are stored in the browser's local storage so they're not lost when re-authenticating, for example.\n\n## SMB Hardening\n\nTaking a client session isolation bug as a cue, SMB connection handling has been thoroughly hardened. New settings let administrators require Kerberos authentication and SMB 3+ transport encryption. SMBv1 remains disabled and SMB signing is required for every connection.\n\n## Miscellaneous\n\n- **Deleting multiple files** works correctly.\n- The keyboard **shortcuts help** dialog is searchable and resizable.\n\n## Under the Hood\n\n- Security: updated all **dependencies** with known vulnerabilities to fixed versions\n- Docker container **logging**: severity reclassification\n\n## Internals\n\n### Release Workflow v2: Docker \u0026 Companion Version Lockstep\n\nSambee has a sophisticated build and release system (see the public [docs](../../../developer-guide/release-and-versioning/release-overview/)). Previously, releases and version numbers of the Docker image and the Companion app were deliberately independent. However, it turned out that it's more efficient and natural to increment the versions of both components in sync.\n\nThis led to a significant architectural change that started with a redefinition of the version number ([details](../../../developer-guide/release-and-versioning/product-versioning/)), followed by a second step in which the release processes were reworked to follow a straightforward pattern:\n\n 1. Increment the version number.\n 1. Create a build with that version (Docker image and/or Companion app).\n 1. Promote that build to the `test` channel and test.\n 1. Promote the build to the `beta` and/or `stable` channels.\n\n Crucially, in this new model a build is created only once. Releases happen through promoting existing builds. This guarantees that the version that was tested is exactly what is released later on.\n\n### Docker Dev/Prod Images: Shared Runtime Base Architecture\n\nThe development (devcontainer) and production Docker images are built off a common shared runtime base. This facilitates maintenance and ensures that the shipped image is identical to the environment the developer tested in.\n", "1.0": "+++\ntitle = \"What's New\"\n+++\n\n## Quick Bar\n\n### File Search\n\nWith the addition of file search (keyboard shortcut: \u003ckbd\u003e/\u003c/kbd\u003e), Sambee's quick bar is becoming a universal search and navigation tool.\n\nFile search complements the existing directory navigation (keyboard shortcut: \u003ckbd\u003eCtrl+K\u003c/kbd\u003e) by providing instant access to recently opened files across directories. File search supersedes file filtering mode, which was removed.\n\n### Directory Navigation History\n\nDirectory navigation now has a history. When you're looking for something, just open the quick bar in directory nav mode and it'll probably already be there. If not, typing a few characters of the name should bring it up in milliseconds.\n\n### Other Changes\n\n- Changed \u003ckbd\u003eF1\u003c/kbd\u003e to consistently invoke keyboard shortcuts help\n\n## Text and Markdown Editors\n\n### Search and Replace\n\nIn any editor, search and replace are essential functions that need to work efficiently while providing granular control. The text and the Markdown editors got just that: compact search and replace popouts with history, regex support and full keyboard usability.\n\n### Other Changes\n\n- Added keyboard shortcuts help\n- Added word wrap (toggled by keyboard shortcut \u003ckbd\u003eAlt+Z\u003c/kbd\u003e)\n- Added viewport scrolling (keyboard shortcut \u003ckbd\u003eCtrl+Arrow up/down\u003c/kbd\u003e)\n- Fixed text selection highlighting\n- Fixed `lock not found or expired` when saving\n\n### Markdown Editor\n\n- Added \u003ckbd\u003eCtrl+B\u003c/kbd\u003e and \u003ckbd\u003eCtrl+I\u003c/kbd\u003e keyboard shortcuts for bold and italic formatting\n\n## PDF Viewer\n\n### More Speed and Higher Fidelity: New Approach to Normalization\n\nEarlier versions normalized every PDF with Ghostscript. This introduced occasional issues and slowed down the viewer. Sambee now opens PDFs in their original form first. When a PDF cannot be displayed because its internal structure is incompatible with the viewer, Sambee can create a separate normalized version for viewing; the original file is never modified. Compatibility processing is limited by file size, processing time, memory, and temporary storage, and each normalized PDF is checked before use.\n\n### Other Changes\n\n- Mobile: swipe to move between pages\n- Encrypted PDFs: the user is now asked to enter a password\n- Large PDFs: better user feedback while loading\n- Color rendering: support for ICC profiles and CMYK\n- Image codecs: support for JPEG 2000 (JXL)\n- Bugfix: geometry changes between pages, e.g., from portrait to landscape, would create endless \"flicker loop\"\n- Bugfix: page rotation commands in the file were not honored\n\n## File List\n\n### ZIP Archive Creation, Inspection, and Extraction\n\nSambee lets you navigate seamlessly into ZIP archives the same way you'd navigate into subdirectories to explore their contents. The UX is instantaneous - only the relevant parts of the ZIP file are decoded. When extracting or compressing, the archive is streamed directly from source to target to minimize CPU, memory, and disk utilization. ZIP operations, like any other, are fully supported across backend boundaries, i.e., between SMB connections and local drives.\n\nThe addition of ZIP archive inspection was the right opportunity to implement storage and content provider abstraction layers. These new abstractions centralize knowledge of storage backends (e.g., SMB, Companion) and how to work with the data on the storage (e.g., regular files, archives), respectively. Introducing these abstractions significantly improves the product's architecture and will greatly simplify adding additional backends or container file types in the future.\n\n### Upload \u0026 Download\n\nA product like Sambee needs efficient ways to get files and folders in and out of the system. To upload files or folders to SMB or local drive destinations, either drag them to Sambee's file browser or select the **Upload** (\u003ckbd\u003eCtrl+U\u003c/kbd\u003e) command in the bottom toolbar. To download files or folders, choose files and/or folders and select the **Download** (\u003ckbd\u003eCtrl+D\u003c/kbd\u003e) command in the bottom toolbar.\n\nDownloading creates a temporary ZIP archive from the selected files and folders, which is then streamed to the browser and subsequently deleted. Sambee allows downloading from all locations: from SMB connections, from local drives, and even from inside ZIP archives.\n\n### Local Drives: Resolve .LNK Files\n\nShortcuts (`.lnk` files), symlinks, and junctions on local drives now show the target path in the status bar. The target information is pulled in asynchronously after the directory list has loaded - we don't want to give up on that snappy UI, after all. Paths are sensibly shortened to fit the available row width.\n\nWhen activated, file targets are opened whereas directory targets are navigated to.\n\n### File Copy and Move: Overwrite Options\n\nCopy and move operations can now overwrite an existing file or replace it only when the source is newer. The same choices work for batches and apply to all supported local and SMB transfers. Directories with the same name are merged safely, preserving destination-only content and resolving only conflicting files.\n\n### Command Toolbar (Desktop) \u0026 Per-Row Actions (Mobile)\n\nA new toolbar at the bottom of the file list makes available commands discoverable. On small screens, typical mobile controls are used instead: a \"+\" icon to create new files or directories and per-row action menus to access commands that operate on individual files or folders.\n\n### Item Selection on Small Screens (Mobile)\n\nOn phones and other small screen devices, files and folders can be selected either through a long press or via the item action menu. Once one item is selected, Sambee switches to multi-selection mode where additional items can be selected through a single tap. An action bar at the bottom of the screen provides access to commands.\n\n### File Metadata on Small Screens (Mobile)\n\nOn phones and other small screen devices, file size and modification time are now displayed in a two-line layout.\n\n### Other Changes\n\n- Added a toolbar button to switch between single-pane and dual-pane modes.\n- When keyboard shortcuts are ignored (because inapplicable in the current situation), Sambee now shows a toast message to make the user unobtrusively aware of the fact.\n- Keyboard navigation: removed delay after entering a new directory.\n- Typeahead buffer: cleared when \u003ckbd\u003eEsc\u003c/kbd\u003e is pressed.\n- The status bar is now always shown.\n\n## Settings\n\n### No More Save Button\n\nClicking a save button at the bottom of the page after adjusting some configuration settings is easily forgotten. So best get rid of that pesky save button altogether. Modern UIs like Sambee's are clever enough to apply config changes automatically and show the user that saving happened through subtle visual cues.\n\n### New Settings\n\nThe settings gained a new category page:\n\n- New admin settings page: **File Search**\n\nFile browser settings:\n\n- **Touch-friendly file selection:** controls how mobile-style file selection is enabled (auto, always on, off).\n\nSystem settings:\n\n- **Temporary archive download size limit:** sets the maximum size of the temporary ZIP archive created when multiple items are downloaded.\n\n### Other Changes\n\n- Localization: Timestamps weren't properly localized in some settings pages (account, user management).\n\n## Image Viewer\n\n- Large images: better user feedback while loading\n\n## Miscellaneous\n\n- Mobile UI: text size increase to improve readability\n- PWA on Chrome on Android: changed the system status bar color from the default blue to gold, matching Sambee's top bar\n- OIDC configuration fields now accept multiple group names as advertised\n- Bugfix: Concurrent OIDC token refreshes would cause SQLite database lock errors.\n- Unicode: file and directory names are normalized to Unicode NFC (single characters) when renamed or created/copied/moved.\n\n## Under the Hood\n\n- Frontend: improved recovery after network unavailability (e.g., after suspend/resume)\n- Security: updated all **dependencies** with known vulnerabilities to fixed versions\n\n## Internals\n\n### Release Workflow: Companion Alignment with Docker Image\n\nCompanion's release process has been simplified and aligned to match the Docker image workflow:\n\n1. When a new Companion build is created, its GitHub release is published automatically and promoted to the `test` channel.\n1. Interim Companion GitHub releases are deleted automatically when they're no longer needed.\n\n### Other Changes\n\n- Dependency security: The backend's lockfile update process was simplified so that Dependabot can now update lockfiles, too. This removes the need to check out Dependabot PRs locally just to run a lockfile update script.\n", "2.0": "+++\ntitle = \"What's New\"\n+++\n\n## \u26a0\ufe0f Action Required\n\nSambee's GitHub repository was moved to an organization account. This makes it necessary that you update the Docker Compose image URL to `ghcr.io/sambee-app/sambee` in your Docker Compose file (see the [Docker deployment docs](../../../admin-guide/installation-and-deployment/deploy-sambee-with-docker/) for details).\n\n## Theme Editor\n\nUI themes are an integral part of an app's visual presentation. As so often, flexibility is key. Some like it dark, others colorful, some require high-contrast, others prefer muted colors.\n\nSambee now has a multi-layer theme system. It differentiates between built-in themes, site-wide themes which only admins can manage, and users' personal themes. Any user can modify existing themes for their own use; admins can also provide themes for other users on the same Sambee server and designate a default theme for new users.\n\nWith Sambee's new theme editor, users can change all theme colors via hex values or the integrated RGBA color picker (which covers transparency in addition to color). Themes can be imported and exported, too.\n\n## File List\n\n### Mouse Selection on Desktop\n\nPrevious versions of Sambee introduced multi-selection for mobile users and keyboard aficionados on desktop. Mouse coverage was lacking. That has been rectified now: Selecting multiple files with a mouse is now straightforward. Click a file or folder icon to select it, then Shift-click another icon to add everything in between without losing your earlier selections. The pane's status bar keeps the count in view.\n\n### Other Changes\n\n- Native mobile sharing is now available for single or multiple files from the file list.\n- Single-file downloads are now streamed directly without buffering in memory. This speeds up downloads and effectively removes limits imposed by file size.\n- Item selection keyboard shortcuts now include \u003ckbd\u003eShift+Home\u003c/kbd\u003e and \u003ckbd\u003eShift+End\u003c/kbd\u003e.\n\n### Bugfixes\n\n#### File Copy/Move Fixes\n\n- Uploads and copy or move operations no longer interfere with each other's conflict decisions.\n- Moving files between SMB connections no longer leaves the original in place when it should have been deleted.\n- SMB moves now protect the source from concurrent edits and renames, preventing deletion of changes that weren't copied.\n- Overwriting an existing SMB file now replaces it atomically instead of failing.\n- Cancelling a move after copying finishes, but before source deletion starts, now correctly reports that both copies were kept.\n- Transfer results now show when a file was copied or replaced, even if removing or checking the original fails.\n- When transferring a folder, a problem with one file no longer hides files already copied, moved, or replaced from the summary.\n- Interrupted SMB moves now release files safely, without leaving them open or interrupting work still in progress.\n- Pressing Enter after a transfer finishes no longer starts the same transfer again.\n\n#### SMB Change Monitoring Fixes\n\nFile list:\n\n- File-list monitoring now watches only immediate children, so changes deeper in a folder don't trigger unnecessary refreshes.\n- When changes happen, the file list is now refreshed in the background.\n- File list refreshes are now coalesced and rate-limited.\n\nDirectory cache for instant navigation:\n\n- Quick directory navigation keeps its existing index when a background scan times out or fails.\n- Background scans keep the live directory index when a removal or rename overlaps a read, including when its notification arrives late. This prevents changes from being applied twice when a folder's name is reused.\n- Changing a connection's target or sign-in details no longer reuses directory suggestions from its old configuration.\n- Directory junctions remain searchable but are no longer followed recursively, preventing indexing loops. DFS referrals are still followed, keeping their subfolders searchable.\n- Startup verification and scheduled directory scans now stop cleanly when their cache is removed.\n\n#### Other Fixes\n\n- Invalid file browser URLs no longer break the page or prevent the other pane from loading.\n- Overlapping download requests were allowed.\n- A failed background connection refresh no longer hides a recovered file listing.\n- Renaming a file to a name that differed by case only failed on local drive connections.\n\n## OpenID Connect (OIDC)\n\n### Refresh Token \u0026 `offline_access` Are Now Optional\n\nMany identity providers require the `offline_access` scope to issue refresh tokens, but some (like OneLogin) rejects that scope in the authorization code flow and can issue a refresh token without it when refresh tokens are enabled for the app.\n\nSambee uses a provider refresh token when one is returned, whether or not `offline_access` was requested. If no refresh token is returned, Sambee can continue issuing short-lived API tokens from the browser session for up to 8 hours by default (configurable from 1 to 24 hours). After Sambee's user session expires, the user must sign in through the identity provider again.\n\n### Other Changes\n\n- When an OIDC login is necessary, all Sambee browser tabs switch to the login page. After a successful login in one tab, that tab now broadcasts a login complete hint. When other tabs on the login page receive that hint, they return to their respectice previous URLs.\n\n### Bugfixes\n\n- OIDC login failures after password reset: OIDC login now completes reliably after an administrator resets the account\u2019s password. Sambee ignores responses from the previous browser session while the new login finishes, reloads the user\u2019s themes and settings, and returns to the file browser instead of the login page.\n\n## Text and Markdown Editors\n\n### Syntax Highlighting and Rendering Performance Optimization\n\nSambee now uses a consolidated syntax highlighting system throughout all text and Markdown rendering surfaces: text viewer and editor, Markdown editor, fenced code blocks in Markdown viewer and editor. The syntax highlighting system is integrated with the theming system; highlight colors are now part of each theme and can be edited in the new theme editor.\n\nText viewer/editor and Markdown editor performance was significantly boosted, especially for long documents. This was achieved through virtualization and viewport rendering.\n\n## Markdown Viewer\n\n### Print / Save as PDF\n\nWhen you print or save as PDF from the browser, the Markdown viewer reformats the full rendered document to fit the page, spanning multiple pages as needed. A new print icon in the top bar makes the new functionality discoverable.\n\n### Other Changes\n\n- Closing the editor by clicking the X now works in the same way as pressing \u003ckbd\u003eEsc\u003c/kbd\u003e: it returns to the viewer. From there, another click returns to the file list.\n- When reloading a browser tab with an editor, Sambee now recovers the file lock. This prevents the error `Unable to enter edit mode. File is locked for editing by \u003cusername\u003e`.\n\n\n## Miscellaneous\n\n### Native Mobile Sharing\n\nConsolidated the native mobile sharing implementation across the file list and image, PDF, text, and Markdown viewers and editors. When sharing fails, a dialog with details can be invoked to facilitate issue reporting.\n\nText and Markdown viewers/editors now have an option to share the current content as text as an alternative to sharing the stored file. This helps circumvent Chrome restrictions that prevent sharing file types such as Markdown.\n\nImage and PDF viewers alway share the displayed content, which may have been normalized for viewing in the browser.\n\n### Full Browser History Navigation\n\nEvery navigation step is now encoded in the URL and recorded in browser history. This enables browser back/forward navigation across the entire Sambee workspace, including the file list, viewers, and editors.\n\n### Local Drive Acess\n\nSambee now checks local-drive access before saying the browser is ready to use Companion. If the check fails, Local Drives settings distinguish between an outdated Companion, an outdated Sambee page, and a pairing that needs to be restored.\n\nWhen Companion rejects a request while browsing a local drive, the file list points to the affected pane and offers a way to reload Sambee or open Local Drives, depending on what went wrong.\n\n### Unencrypted HTTP Support\n\nSambee now deals with unencrypted HTTP explicitly:\n\n- Companion pairing and operations are unavailable.\n- File copying caused a `crypto.randomUUID` error. This has been fixed by implementing a fallback.\n- File uploading would show `outcome uncertain` and not upload files on HTTP/1.1 connections (even over HTTPS). This has been fixed by sending files directly instead of using a streamed request body, so uploads work on HTTP/1.1 while still showing progress.\n- Copying to the clipboard (used in Settings) is now disabled.\n\nHTTP for development on `localhost` is treated as secure by browsers and continues to be supported by Sambee.\n\n### Supported Browser Detection\n\nIf your browser is too old or lacks features Sambee needs, you'll now see a clear message instead of a blank page. The message identifies missing capabilities and links to the browser requirements so you can choose a supported browser.\n\n### Password Login\n\n- When an admin configures a user to require a password change, that change is now enforced upon the next password login.\n- Local usernames are now evaluated case-insensitively.\n- The password field got an option to reveal the password.\n\n### Settings\n\n- User Management: Table column content could overflow into the next row. This was fixes with a comprehensive layout revision.\n\n## Under the Hood\n\n### Security Review\n\n- OIDC login now binds the callback and login grant to the browser that started the login flow, preventing a grant from being redeemed in another browser.\n- Only admins can list and download uploaded mobile logs; signed-in users can still upload logs for troubleshooting.\n- Companion requests now use signatures tied to the HTTP method and requested URL, so a signature can't be reused for another request.\n- Mobile log uploads have a size limit, and stored logs are pruned when they exceed the storage budget.\n- HTML, XHTML, and SVG files, including archive members, download instead of running as active content in the viewer.\n\n### Other Changes\n\n- The backend's Python environment was upgraded from 3.13 to 3.14.\n- Fixed the container startup warning: `AuthlibDeprecationWarning: The httpx module is deprecated; please use httpx2 instead.`\n\n### Dependency Security\n\n- Updated all **dependencies** with known issues or vulnerabilities to fixed versions.\n- Pinned all third-party GitHub Actions workflows to commit SHAs.\n- Frontend: removed `patch-package` to get rid of vulnerable transisitve dependency `braces`.\n\n### Frontend Type Correctness\n\nType correctness of frontend code and tests is now enforced. As part of this implementation, 1,152 diagnostics across 162 files were fixed: 840 in tests, 311 in application code,\nand one in an imported browser-test helper.\n\n## Internals\n\n- Companion build for Windows: Authenticode signing was removed from PR check builds and only remains on release workflows.\n- GitHub Actions: replaced `pull_request_target` as it will be removed on public repositories by default in November.\n- GitHub Actions: cache retention optimization.\n"}, "page_contents": {"0.8": "+++\ntitle = \"What's New\"\n+++\n\n## Quick Bar: UX\n\nThe [quick bar](../../../user-guide/browsing-and-navigation/smart-navigation-and-the-quick-bar/) is Sambee's main navigation element. It sits in the top bar above the file list and is designed to be the single point of control for directory navigation, file list filtering, and command lookup and execution.\n\nPreviously, those three functions were not clearly distinguished. The three modes are now separated more distinctly, and the current mode is shown directly in the quick bar through a dedicated button. This makes the feature easier to discover and also allows users to switch modes with the mouse or by touch (in addition to the existing keyboard shortcuts).\n\nIn addition, several bugs were fixed to improve the overall experience.\n\n## Companion: More Secure Pairing \u0026 Communication Flows\n\nThis release makes Sambee Companion connections more secure, from the first pairing step through ongoing communication during local-drive access and desktop editing.\n\n**Pairing** is now tracked per Sambee site instead of through one global paired state. Pending approvals can be cancelled cleanly, and the browser now shows clearer states when Companion is unavailable, waiting for local approval, needs repair, or has lost its editing session.\n\nSambee also now trusts only the specific Sambee site you approved, limits what the local Companion service exposes, and uses narrower one-task-at-a-time edit credentials behind the scenes.\n\n**Native editing** is also more resilient. Sambee now uses tighter, task-specific edit permissions, renews long-running edit sessions when needed, and returns you to the browser with a clearer next step if sign-in, lock ownership, or recovery fails, instead of leaving you stuck with a vague error.\n\n## File Opening: Speed \u0026 Flexibility\n\nWhen opening files for previewing or editing, you want quick previews, but you also want the ability to choose which app a file is opened in. Both paths are now efficiently available:\n\nOpen files in Sambee's browser-based viewers:\n\n- Click a file or press \u003ckbd\u003eEnter\u003c/kbd\u003e to open it in Sambee's associated viewer.\n- If no associated viewer exists, or if you press \u003ckbd\u003eShift + Enter\u003c/kbd\u003e, a viewer picker dialog appears.\n   - The picker lets you choose a Sambee browser viewer or a native app.\n\nOpen files in natively installed apps:\n\n- Press \u003ckbd\u003eCtrl + Enter\u003c/kbd\u003e to open a file in its associated native app, or right-click it and select **Open in Native App**.\n- If no associated native app has been chosen, or if you press \u003ckbd\u003eCtrl + Alt + Enter\u003c/kbd\u003e, an app picker dialog appears.\n\n## Markdown Editor: Strategy Change\n\nThe WYSIWYG Markdown editor is gone for a simple reason: UX. There is no open-source rich-text (WYSIWYG) Markdown editor that provides a great user experience. The previous editor was not up to the task.\n\nThe better option is CodeMirror, one of the best available editors, configured for Markdown. It provides a first-rate editing experience and battle-tested add-ons for many of the quality-of-life features people have come to expect from modern editors.\n\n### Interactive Markdown Table Editing\n\nEditing Markdown in a text editor works well for headings and lists, but tables are different. Markdown table syntax is unwieldy, especially when inserting a column in the middle, and the source is difficult to scan. Tables need an interactive WYSIWYG interface that looks and feels like a spreadsheet application. Sambee provides exactly that.\n\n## Text File Viewer and Editor\n\nSince we already have an excellent text editor (see the Markdown Editor note), we might as well put it to good use as a generic text file editor. Sambee can now open, display, and edit any kind of text-based file, with all the bells and whistles of a first-rate editor, for example syntax highlighting.\n\n## Miscellaneous\n\n### Home Screen\n\n- Added a help button next to the settings (gear) icon.\n\n### File List\n\n- Increased the font size on mobile.\n\n### PDF Viewer\n\n- Intra-document links now work correctly, e.g. from a table of contents.\n\n### Under the Hood\n\n- Major dependency upgrades across the board, including React 19 and MUI 9.\n- Improved suspend, resume, and reload resilience.\n\n## Internals\n\n### Documentation System\n\nSambee has a best-in-class documentation system that deduplicates content, inheriting unchanged text copy through versions. This enables us to provide complete and accurate docs for each product version while minimizing maintenance effort.\n\nThis release adds a docs reporting and visualization tool that creates an HTML report of every docs book, section, and page, including its properties, such as whether it is inherited or branched. The report also has a diff view that highlights changes between any two document versions.\n\nDocs editor tool improvements include:\n\n- UI improvements, including better help output.\n- New commands to convert pages between inherited and independent: `page materialize` and `page inherit`.\n- A test and validation suite that also runs in CI.\n", "0.9": "+++\ntitle = \"What's New\"\n+++\n\n## OpenID Connect (OIDC) Authentication and Single Sign-On (SSO)\n\nSingle sign-on was on my list of essential features from the very beginning. Having one source of truth for authentication and authorization is of great benefit even in the smallest networks with single-digit user counts.\n\nSambee includes a secure and comprehensive implementation of OpenID Connect for authentication through IAM servers such as Authelia or Keycloak. If OIDC is configured as the only authentication method, SSO happens behind the scenes and is fully transparent to users who are already logged in to the IAM server. Otherwise, users trying to access Sambee are redirected to the IAM server to authenticate. Once that has happened, they're redirected back to Sambee.\n\nSambee's [OIDC implementation](../../../admin-guide/authentication/openid-connect-authentication-setup/) comes with auto-provisioning, which creates Sambee user accounts automatically after successful OIDC authentication. This can (and often should) be gated by group membership so that only members of a specific group are allowed access to Sambee. Similarly, Sambee's user roles are assigned depending on group membership. This makes it possible to centrally manage access to Sambee's user roles (e.g., admin) in your IAM system.\n\n### Authentication Configuration Change\n\nAuthentication mode is selected only in **Settings** \u003e **Administration** \u003e **Authentication** and defaults to **Password only** for a new installation. The configuration file can only disable enforcement temporarily with `[auth] disable_enforcement = true`; the stored UI mode remains unchanged.\n\nThis is a breaking configuration change. `auth_method` is rejected in both `[auth]` and `[security]`, and existing installations are not migrated automatically. Remove the retired key before upgrading.\n\n## Settings \u0026 Dialogs Overhaul\n\nThe settings got a good UX overhaul that should make them consistent, accessible and, hopefully, much nicer to look at. They're fully responsive, of course, adapting flexibly to phone and desktop screen dimensions. They're also very optimized for efficient keyboard usage while offering touch-friendly sizing on mobile devices.\n\n### New Settings\n\nThe settings also gained several new category pages:\n\n- New personal **Account** settings page\n- New admin **About** settings page\n- New admin **Authentication** settings page\n- New admin **Network** settings page\n- New admin **SMB** settings page\n\nThe about page comes with a feature that may come in handy: creating a **support report** with redacted diagnostic information that's safe to post online.\n\n### User Management Page: Visibility Update\n\nThe user management page in settings was reimplemented to provide significantly better visibility through search, filtering, sorting, summary shortcuts, and a more compact presentation.\n\n### Dialog Look \u0026 Feel\n\nThe refreshed and improved look and feel from settings was applied to the various dialogs that are shown when you copy, move, create, or delete files and/or directories. These dialogs now convey more information in a better way than before.\n\n## Dark Theme Polishing\n\nThe dark theme got a good new coat of paint. The colors of all elements, including backgrounds, text, menus, and dialogs, were tweaked to ensure visual clarity and eye-soothing contrasts.\n\n## Markdown Editor Improvements\n\n- Lists are normalized (formatted) when saved, using `-` for unordered lists and `1.` for every ordered-list item.\n- The editor updates to display the normalized Markdown written to disk after a successful save.\n- Unsaved edits are stored in the browser's local storage so they're not lost when re-authenticating, for example.\n\n## SMB Hardening\n\nTaking a client session isolation bug as a cue, SMB connection handling has been thoroughly hardened. New settings let administrators require Kerberos authentication and SMB 3+ transport encryption. SMBv1 remains disabled and SMB signing is required for every connection.\n\n## Miscellaneous\n\n- **Deleting multiple files** works correctly.\n- The keyboard **shortcuts help** dialog is searchable and resizable.\n\n## Under the Hood\n\n- Security: updated all **dependencies** with known vulnerabilities to fixed versions\n- Docker container **logging**: severity reclassification\n\n## Internals\n\n### Release Workflow v2: Docker \u0026 Companion Version Lockstep\n\nSambee has a sophisticated build and release system (see the public [docs](../../../developer-guide/release-and-versioning/release-overview/)). Previously, releases and version numbers of the Docker image and the Companion app were deliberately independent. However, it turned out that it's more efficient and natural to increment the versions of both components in sync.\n\nThis led to a significant architectural change that started with a redefinition of the version number ([details](../../../developer-guide/release-and-versioning/product-versioning/)), followed by a second step in which the release processes were reworked to follow a straightforward pattern:\n\n 1. Increment the version number.\n 1. Create a build with that version (Docker image and/or Companion app).\n 1. Promote that build to the `test` channel and test.\n 1. Promote the build to the `beta` and/or `stable` channels.\n\n Crucially, in this new model a build is created only once. Releases happen through promoting existing builds. This guarantees that the version that was tested is exactly what is released later on.\n\n### Docker Dev/Prod Images: Shared Runtime Base Architecture\n\nThe development (devcontainer) and production Docker images are built off a common shared runtime base. This facilitates maintenance and ensures that the shipped image is identical to the environment the developer tested in.\n", "1.0": "+++\ntitle = \"What's New\"\n+++\n\n## Quick Bar\n\n### File Search\n\nWith the addition of file search (keyboard shortcut: \u003ckbd\u003e/\u003c/kbd\u003e), Sambee's quick bar is becoming a universal search and navigation tool.\n\nFile search complements the existing directory navigation (keyboard shortcut: \u003ckbd\u003eCtrl+K\u003c/kbd\u003e) by providing instant access to recently opened files across directories. File search supersedes file filtering mode, which was removed.\n\n### Directory Navigation History\n\nDirectory navigation now has a history. When you're looking for something, just open the quick bar in directory nav mode and it'll probably already be there. If not, typing a few characters of the name should bring it up in milliseconds.\n\n### Other Changes\n\n- Changed \u003ckbd\u003eF1\u003c/kbd\u003e to consistently invoke keyboard shortcuts help\n\n## Text and Markdown Editors\n\n### Search and Replace\n\nIn any editor, search and replace are essential functions that need to work efficiently while providing granular control. The text and the Markdown editors got just that: compact search and replace popouts with history, regex support and full keyboard usability.\n\n### Other Changes\n\n- Added keyboard shortcuts help\n- Added word wrap (toggled by keyboard shortcut \u003ckbd\u003eAlt+Z\u003c/kbd\u003e)\n- Added viewport scrolling (keyboard shortcut \u003ckbd\u003eCtrl+Arrow up/down\u003c/kbd\u003e)\n- Fixed text selection highlighting\n- Fixed `lock not found or expired` when saving\n\n### Markdown Editor\n\n- Added \u003ckbd\u003eCtrl+B\u003c/kbd\u003e and \u003ckbd\u003eCtrl+I\u003c/kbd\u003e keyboard shortcuts for bold and italic formatting\n\n## PDF Viewer\n\n### More Speed and Higher Fidelity: New Approach to Normalization\n\nEarlier versions normalized every PDF with Ghostscript. This introduced occasional issues and slowed down the viewer. Sambee now opens PDFs in their original form first. When a PDF cannot be displayed because its internal structure is incompatible with the viewer, Sambee can create a separate normalized version for viewing; the original file is never modified. Compatibility processing is limited by file size, processing time, memory, and temporary storage, and each normalized PDF is checked before use.\n\n### Other Changes\n\n- Mobile: swipe to move between pages\n- Encrypted PDFs: the user is now asked to enter a password\n- Large PDFs: better user feedback while loading\n- Color rendering: support for ICC profiles and CMYK\n- Image codecs: support for JPEG 2000 (JXL)\n- Bugfix: geometry changes between pages, e.g., from portrait to landscape, would create endless \"flicker loop\"\n- Bugfix: page rotation commands in the file were not honored\n\n## File List\n\n### ZIP Archive Creation, Inspection, and Extraction\n\nSambee lets you navigate seamlessly into ZIP archives the same way you'd navigate into subdirectories to explore their contents. The UX is instantaneous - only the relevant parts of the ZIP file are decoded. When extracting or compressing, the archive is streamed directly from source to target to minimize CPU, memory, and disk utilization. ZIP operations, like any other, are fully supported across backend boundaries, i.e., between SMB connections and local drives.\n\nThe addition of ZIP archive inspection was the right opportunity to implement storage and content provider abstraction layers. These new abstractions centralize knowledge of storage backends (e.g., SMB, Companion) and how to work with the data on the storage (e.g., regular files, archives), respectively. Introducing these abstractions significantly improves the product's architecture and will greatly simplify adding additional backends or container file types in the future.\n\n### Upload \u0026 Download\n\nA product like Sambee needs efficient ways to get files and folders in and out of the system. To upload files or folders to SMB or local drive destinations, either drag them to Sambee's file browser or select the **Upload** (\u003ckbd\u003eCtrl+U\u003c/kbd\u003e) command in the bottom toolbar. To download files or folders, choose files and/or folders and select the **Download** (\u003ckbd\u003eCtrl+D\u003c/kbd\u003e) command in the bottom toolbar.\n\nDownloading creates a temporary ZIP archive from the selected files and folders, which is then streamed to the browser and subsequently deleted. Sambee allows downloading from all locations: from SMB connections, from local drives, and even from inside ZIP archives.\n\n### Local Drives: Resolve .LNK Files\n\nShortcuts (`.lnk` files), symlinks, and junctions on local drives now show the target path in the status bar. The target information is pulled in asynchronously after the directory list has loaded - we don't want to give up on that snappy UI, after all. Paths are sensibly shortened to fit the available row width.\n\nWhen activated, file targets are opened whereas directory targets are navigated to.\n\n### File Copy and Move: Overwrite Options\n\nCopy and move operations can now overwrite an existing file or replace it only when the source is newer. The same choices work for batches and apply to all supported local and SMB transfers. Directories with the same name are merged safely, preserving destination-only content and resolving only conflicting files.\n\n### Command Toolbar (Desktop) \u0026 Per-Row Actions (Mobile)\n\nA new toolbar at the bottom of the file list makes available commands discoverable. On small screens, typical mobile controls are used instead: a \"+\" icon to create new files or directories and per-row action menus to access commands that operate on individual files or folders.\n\n### Item Selection on Small Screens (Mobile)\n\nOn phones and other small screen devices, files and folders can be selected either through a long press or via the item action menu. Once one item is selected, Sambee switches to multi-selection mode where additional items can be selected through a single tap. An action bar at the bottom of the screen provides access to commands.\n\n### File Metadata on Small Screens (Mobile)\n\nOn phones and other small screen devices, file size and modification time are now displayed in a two-line layout.\n\n### Other Changes\n\n- Added a toolbar button to switch between single-pane and dual-pane modes.\n- When keyboard shortcuts are ignored (because inapplicable in the current situation), Sambee now shows a toast message to make the user unobtrusively aware of the fact.\n- Keyboard navigation: removed delay after entering a new directory.\n- Typeahead buffer: cleared when \u003ckbd\u003eEsc\u003c/kbd\u003e is pressed.\n- The status bar is now always shown.\n\n## Settings\n\n### No More Save Button\n\nClicking a save button at the bottom of the page after adjusting some configuration settings is easily forgotten. So best get rid of that pesky save button altogether. Modern UIs like Sambee's are clever enough to apply config changes automatically and show the user that saving happened through subtle visual cues.\n\n### New Settings\n\nThe settings gained a new category page:\n\n- New admin settings page: **File Search**\n\nFile browser settings:\n\n- **Touch-friendly file selection:** controls how mobile-style file selection is enabled (auto, always on, off).\n\nSystem settings:\n\n- **Temporary archive download size limit:** sets the maximum size of the temporary ZIP archive created when multiple items are downloaded.\n\n### Other Changes\n\n- Localization: Timestamps weren't properly localized in some settings pages (account, user management).\n\n## Image Viewer\n\n- Large images: better user feedback while loading\n\n## Miscellaneous\n\n- Mobile UI: text size increase to improve readability\n- PWA on Chrome on Android: changed the system status bar color from the default blue to gold, matching Sambee's top bar\n- OIDC configuration fields now accept multiple group names as advertised\n- Bugfix: Concurrent OIDC token refreshes would cause SQLite database lock errors.\n- Unicode: file and directory names are normalized to Unicode NFC (single characters) when renamed or created/copied/moved.\n\n## Under the Hood\n\n- Frontend: improved recovery after network unavailability (e.g., after suspend/resume)\n- Security: updated all **dependencies** with known vulnerabilities to fixed versions\n\n## Internals\n\n### Release Workflow: Companion Alignment with Docker Image\n\nCompanion's release process has been simplified and aligned to match the Docker image workflow:\n\n1. When a new Companion build is created, its GitHub release is published automatically and promoted to the `test` channel.\n1. Interim Companion GitHub releases are deleted automatically when they're no longer needed.\n\n### Other Changes\n\n- Dependency security: The backend's lockfile update process was simplified so that Dependabot can now update lockfiles, too. This removes the need to check out Dependabot PRs locally just to run a lockfile update script.\n", "2.0": "+++\ntitle = \"What's New\"\n+++\n\n## \u26a0\ufe0f Action Required\n\nSambee's GitHub repository was moved to an organization account. This makes it necessary that you update the Docker Compose image URL to `ghcr.io/sambee-app/sambee` in your Docker Compose file (see the [Docker deployment docs](../../../admin-guide/installation-and-deployment/deploy-sambee-with-docker/) for details).\n\n## Theme Editor\n\nUI themes are an integral part of an app's visual presentation. As so often, flexibility is key. Some like it dark, others colorful, some require high-contrast, others prefer muted colors.\n\nSambee now has a multi-layer theme system. It differentiates between built-in themes, site-wide themes which only admins can manage, and users' personal themes. Any user can modify existing themes for their own use; admins can also provide themes for other users on the same Sambee server and designate a default theme for new users.\n\nWith Sambee's new theme editor, users can change all theme colors via hex values or the integrated RGBA color picker (which covers transparency in addition to color). Themes can be imported and exported, too.\n\n## File List\n\n### Mouse Selection on Desktop\n\nPrevious versions of Sambee introduced multi-selection for mobile users and keyboard aficionados on desktop. Mouse coverage was lacking. That has been rectified now: Selecting multiple files with a mouse is now straightforward. Click a file or folder icon to select it, then Shift-click another icon to add everything in between without losing your earlier selections. The pane's status bar keeps the count in view.\n\n### Other Changes\n\n- Native mobile sharing is now available for single or multiple files from the file list.\n- Single-file downloads are now streamed directly without buffering in memory. This speeds up downloads and effectively removes limits imposed by file size.\n- Item selection keyboard shortcuts now include \u003ckbd\u003eShift+Home\u003c/kbd\u003e and \u003ckbd\u003eShift+End\u003c/kbd\u003e.\n\n### Bugfixes\n\n#### File Copy/Move Fixes\n\n- Uploads and copy or move operations no longer interfere with each other's conflict decisions.\n- Moving files between SMB connections no longer leaves the original in place when it should have been deleted.\n- SMB moves now protect the source from concurrent edits and renames, preventing deletion of changes that weren't copied.\n- Overwriting an existing SMB file now replaces it atomically instead of failing.\n- Cancelling a move after copying finishes, but before source deletion starts, now correctly reports that both copies were kept.\n- Transfer results now show when a file was copied or replaced, even if removing or checking the original fails.\n- When transferring a folder, a problem with one file no longer hides files already copied, moved, or replaced from the summary.\n- Interrupted SMB moves now release files safely, without leaving them open or interrupting work still in progress.\n- Pressing Enter after a transfer finishes no longer starts the same transfer again.\n\n#### SMB Change Monitoring Fixes\n\nFile list:\n\n- File-list monitoring now watches only immediate children, so changes deeper in a folder don't trigger unnecessary refreshes.\n- When changes happen, the file list is now refreshed in the background.\n- File list refreshes are now coalesced and rate-limited.\n\nDirectory cache for instant navigation:\n\n- Quick directory navigation keeps its existing index when a background scan times out or fails.\n- Background scans keep the live directory index when a removal or rename overlaps a read, including when its notification arrives late. This prevents changes from being applied twice when a folder's name is reused.\n- Changing a connection's target or sign-in details no longer reuses directory suggestions from its old configuration.\n- Directory junctions remain searchable but are no longer followed recursively, preventing indexing loops. DFS referrals are still followed, keeping their subfolders searchable.\n- Startup verification and scheduled directory scans now stop cleanly when their cache is removed.\n\n#### Other Fixes\n\n- Invalid file browser URLs no longer break the page or prevent the other pane from loading.\n- Overlapping download requests were allowed.\n- A failed background connection refresh no longer hides a recovered file listing.\n- Renaming a file to a name that differed by case only failed on local drive connections.\n\n## OpenID Connect (OIDC)\n\n### Refresh Token \u0026 `offline_access` Are Now Optional\n\nMany identity providers require the `offline_access` scope to issue refresh tokens, but some (like OneLogin) rejects that scope in the authorization code flow and can issue a refresh token without it when refresh tokens are enabled for the app.\n\nSambee uses a provider refresh token when one is returned, whether or not `offline_access` was requested. If no refresh token is returned, Sambee can continue issuing short-lived API tokens from the browser session for up to 8 hours by default (configurable from 1 to 24 hours). After Sambee's user session expires, the user must sign in through the identity provider again.\n\n### Other Changes\n\n- When an OIDC login is necessary, all Sambee browser tabs switch to the login page. After a successful login in one tab, that tab now broadcasts a login complete hint. When other tabs on the login page receive that hint, they return to their respectice previous URLs.\n\n### Bugfixes\n\n- OIDC login failures after password reset: OIDC login now completes reliably after an administrator resets the account\u2019s password. Sambee ignores responses from the previous browser session while the new login finishes, reloads the user\u2019s themes and settings, and returns to the file browser instead of the login page.\n\n## Text and Markdown Editors\n\n### Syntax Highlighting and Rendering Performance Optimization\n\nSambee now uses a consolidated syntax highlighting system throughout all text and Markdown rendering surfaces: text viewer and editor, Markdown editor, fenced code blocks in Markdown viewer and editor. The syntax highlighting system is integrated with the theming system; highlight colors are now part of each theme and can be edited in the new theme editor.\n\nText viewer/editor and Markdown editor performance was significantly boosted, especially for long documents. This was achieved through virtualization and viewport rendering.\n\n## Markdown Viewer\n\n### Print / Save as PDF\n\nWhen you print or save as PDF from the browser, the Markdown viewer reformats the full rendered document to fit the page, spanning multiple pages as needed. A new print icon in the top bar makes the new functionality discoverable.\n\n### Other Changes\n\n- Closing the editor by clicking the X now works in the same way as pressing \u003ckbd\u003eEsc\u003c/kbd\u003e: it returns to the viewer. From there, another click returns to the file list.\n- When reloading a browser tab with an editor, Sambee now recovers the file lock. This prevents the error `Unable to enter edit mode. File is locked for editing by \u003cusername\u003e`.\n\n\n## Miscellaneous\n\n### Native Mobile Sharing\n\nConsolidated the native mobile sharing implementation across the file list and image, PDF, text, and Markdown viewers and editors. When sharing fails, a dialog with details can be invoked to facilitate issue reporting.\n\nText and Markdown viewers/editors now have an option to share the current content as text as an alternative to sharing the stored file. This helps circumvent Chrome restrictions that prevent sharing file types such as Markdown.\n\nImage and PDF viewers alway share the displayed content, which may have been normalized for viewing in the browser.\n\n### Full Browser History Navigation\n\nEvery navigation step is now encoded in the URL and recorded in browser history. This enables browser back/forward navigation across the entire Sambee workspace, including the file list, viewers, and editors.\n\n### Local Drive Acess\n\nSambee now checks local-drive access before saying the browser is ready to use Companion. If the check fails, Local Drives settings distinguish between an outdated Companion, an outdated Sambee page, and a pairing that needs to be restored.\n\nWhen Companion rejects a request while browsing a local drive, the file list points to the affected pane and offers a way to reload Sambee or open Local Drives, depending on what went wrong.\n\n### Unencrypted HTTP Support\n\nSambee now deals with unencrypted HTTP explicitly:\n\n- Companion pairing and operations are unavailable.\n- File copying caused a `crypto.randomUUID` error. This has been fixed by implementing a fallback.\n- File uploading would show `outcome uncertain` and not upload files on HTTP/1.1 connections (even over HTTPS). This has been fixed by sending files directly instead of using a streamed request body, so uploads work on HTTP/1.1 while still showing progress.\n- Copying to the clipboard (used in Settings) is now disabled.\n\nHTTP for development on `localhost` is treated as secure by browsers and continues to be supported by Sambee.\n\n### Supported Browser Detection\n\nIf your browser is too old or lacks features Sambee needs, you'll now see a clear message instead of a blank page. The message identifies missing capabilities and links to the browser requirements so you can choose a supported browser.\n\n### Password Login\n\n- When an admin configures a user to require a password change, that change is now enforced upon the next password login.\n- Local usernames are now evaluated case-insensitively.\n- The password field got an option to reveal the password.\n\n### Settings\n\n- User Management: Table column content could overflow into the next row. This was fixes with a comprehensive layout revision.\n\n## Under the Hood\n\n### Security Review\n\n- OIDC login now binds the callback and login grant to the browser that started the login flow, preventing a grant from being redeemed in another browser.\n- Only admins can list and download uploaded mobile logs; signed-in users can still upload logs for troubleshooting.\n- Companion requests now use signatures tied to the HTTP method and requested URL, so a signature can't be reused for another request.\n- Mobile log uploads have a size limit, and stored logs are pruned when they exceed the storage budget.\n- HTML, XHTML, and SVG files, including archive members, download instead of running as active content in the viewer.\n\n### Other Changes\n\n- The backend's Python environment was upgraded from 3.13 to 3.14.\n- Fixed the container startup warning: `AuthlibDeprecationWarning: The httpx module is deprecated; please use httpx2 instead.`\n\n### Dependency Security\n\n- Updated all **dependencies** with known issues or vulnerabilities to fixed versions.\n- Pinned all third-party GitHub Actions workflows to commit SHAs.\n- Frontend: removed `patch-package` to get rid of vulnerable transisitve dependency `braces`.\n\n### Frontend Type Correctness\n\nType correctness of frontend code and tests is now enforced. As part of this implementation, 1,152 diagnostics across 162 files were fixed: 840 in tests, 311 in application code,\nand one in an imported browser-test helper.\n\n## Internals\n\n- Companion build for Windows: Authenticode signing was removed from PR check builds and only remains on release workflows.\n- GitHub Actions: replaced `pull_request_target` as it will be removed on public repositories by default in November.\n- GitHub Actions: cache retention optimization.\n"}, "flags": {"has_branched": true, "has_inherited": false, "has_structural": false, "has_invalid": false}}, {"id": "section:release-info/system-requirements", "parent_id": "book:release-info", "depth": 1, "kind": "section", "label": "system-requirements", "title": "System Requirements", "path": "release-info/system-requirements", "has_children": true, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "missing"}, "1.0": {"state": "structural-only"}, "2.0": {"state": "structural-only"}}, "content_versions": {}, "flags": {"has_branched": false, "has_inherited": false, "has_structural": true, "has_invalid": false}}, {"id": "page:release-info/system-requirements/requirements", "parent_id": "section:release-info/system-requirements", "depth": 2, "kind": "page", "label": "requirements", "title": "Requirements", "path": "release-info/system-requirements/requirements", "has_children": false, "version_cells": {"0.7": {"state": "missing"}, "0.8": {"state": "missing"}, "0.9": {"state": "missing"}, "1.0": {"state": "authored"}, "2.0": {"state": "branched", "source_version": "1.0", "diff_added": 6, "diff_removed": 2}}, "content_versions": {"1.0": "+++\ntitle = \"System Requirements\"\n+++\n\n## Frontend\n\n### Web Browsers\n\nSambee's frontend supports the latest versions of desktop and mobile browsers, including:\n\n- Google Chrome (and derivatives)\n- Mozilla Firefox\n- Apple Safari\n\n### HTTPS\n\n**Accessing Sambee over HTTPS is very much recommended.** Typically, a reverse proxy such as Caddy is used for that purpose. See the [reverse proxy docs](https://sambee.net/docs/admin-guide/network-and-reverse-proxy/put-sambee-behind-a-reverse-proxy/) for more information, and [this blog post by Helge Klein](https://helgeklein.com/blog/automatic-https-certificates-for-services-on-internal-home-network-without-opening-firewall-port/) for a detailed configuration guide.\n\nCompanion pairing and operations are only available over HTTPS (or `http://localhost`, for local development).\n\n## Sambee Companion\n\nSambee Companion is available for Windows 11 on x64 and ARM64.\n", "2.0": "+++\ntitle = \"System Requirements\"\n+++\n\n## Frontend\n\n### Web Browsers\n\nSambee's frontend supports the latest versions of desktop and mobile browsers, including:\n\n- Google Chrome (and derivates)\n- Mozilla Firefox\n- Apple Safari\n\nWeb Workers must be available. If a browser lacks this or another required modern capability, Sambee shows a browser compatibility message instead of loading the app. This checks a few key capabilities, not every feature Sambee uses. Browser or security policies that prevent a worker from starting can still cause a feature-specific error after the app loads.\n\nTo preview this message on the development server, open `http://localhost:3000/browse/smb/demo?simulateUnsupportedBrowser`. Remove the query parameter to load the app normally. This flag has no effect in production builds.\n\n### HTTPS\n\n**Accessing Sambee over HTTPS is very much recommended.** Typically, a reverse proxy such as Caddy is used for that purpose. See the [reverse proxy docs](https://sambee.net/docs/admin-guide/network-and-reverse-proxy/put-sambee-behind-a-reverse-proxy/) for more information, and [this blog post by Helge Klein](https://helgeklein.com/blog/automatic-https-certificates-for-services-on-internal-home-network-without-opening-firewall-port/) for a detailed configuration guide.\n\nCompanion pairing and operations are only available over HTTPS (or `http://localhost`, for local development).\n\n## Sambee Companion\n\nSambee Companion is currently available for Windows 11 on x64 and ARM64.\n"}, "page_contents": {"1.0": "+++\ntitle = \"System Requirements\"\n+++\n\n## Frontend\n\n### Web Browsers\n\nSambee's frontend supports the latest versions of desktop and mobile browsers, including:\n\n- Google Chrome (and derivatives)\n- Mozilla Firefox\n- Apple Safari\n\n### HTTPS\n\n**Accessing Sambee over HTTPS is very much recommended.** Typically, a reverse proxy such as Caddy is used for that purpose. See the [reverse proxy docs](https://sambee.net/docs/admin-guide/network-and-reverse-proxy/put-sambee-behind-a-reverse-proxy/) for more information, and [this blog post by Helge Klein](https://helgeklein.com/blog/automatic-https-certificates-for-services-on-internal-home-network-without-opening-firewall-port/) for a detailed configuration guide.\n\nCompanion pairing and operations are only available over HTTPS (or `http://localhost`, for local development).\n\n## Sambee Companion\n\nSambee Companion is available for Windows 11 on x64 and ARM64.\n", "2.0": "+++\ntitle = \"System Requirements\"\n+++\n\n## Frontend\n\n### Web Browsers\n\nSambee's frontend supports the latest versions of desktop and mobile browsers, including:\n\n- Google Chrome (and derivates)\n- Mozilla Firefox\n- Apple Safari\n\nWeb Workers must be available. If a browser lacks this or another required modern capability, Sambee shows a browser compatibility message instead of loading the app. This checks a few key capabilities, not every feature Sambee uses. Browser or security policies that prevent a worker from starting can still cause a feature-specific error after the app loads.\n\nTo preview this message on the development server, open `http://localhost:3000/browse/smb/demo?simulateUnsupportedBrowser`. Remove the query parameter to load the app normally. This flag has no effect in production builds.\n\n### HTTPS\n\n**Accessing Sambee over HTTPS is very much recommended.** Typically, a reverse proxy such as Caddy is used for that purpose. See the [reverse proxy docs](https://sambee.net/docs/admin-guide/network-and-reverse-proxy/put-sambee-behind-a-reverse-proxy/) for more information, and [this blog post by Helge Klein](https://helgeklein.com/blog/automatic-https-certificates-for-services-on-internal-home-network-without-opening-firewall-port/) for a detailed configuration guide.\n\nCompanion pairing and operations are only available over HTTPS (or `http://localhost`, for local development).\n\n## Sambee Companion\n\nSambee Companion is currently available for Windows 11 on x64 and ARM64.\n"}, "flags": {"has_branched": true, "has_inherited": false, "has_structural": false, "has_invalid": false}}]}</script>
   <script>
     const report = JSON.parse(document.getElementById('report-data').textContent);
     const versions = report.versions;
diff --git a/website/content/docs/2.0/developer-guide/frontend-architecture/theming-system-and-theme-selection/index.md b/website/content/docs/2.0/developer-guide/frontend-architecture/theming-system-and-theme-selection/index.md
index 9094baa48..47d43807c 100644
--- a/website/content/docs/2.0/developer-guide/frontend-architecture/theming-system-and-theme-selection/index.md
+++ b/website/content/docs/2.0/developer-guide/frontend-architecture/theming-system-and-theme-selection/index.md
@@ -11,6 +11,8 @@ Sambee has two built-in themes (`sambee-light` and `sambee-dark`), user-owned th
 | `frontend/src/theme/types.ts` | Palette types and editor field labels |
 | `frontend/src/theme/themes.ts` | Built-in definitions with stable IDs |
 | `frontend/src/theme/themeDefinition.ts` | Editable color catalog, hex checks, and versioned import/export |
+| `frontend/src/theme/resolveSyntaxTheme.ts` | Non-mutating legacy syntax defaults and strict supplied-palette validation |
+| `frontend/src/theme/syntaxStyles.ts` | Shared token classes and locally inherited syntax variables |
 | `frontend/src/theme/palette.ts` | Shared effective palette for the app |
 | `frontend/src/theme/viewerStyles.ts` | Viewer and Markdown document surfaces |
 | `frontend/src/theme/ThemeContext.tsx` | Registry refresh and Material UI theme |
@@ -20,7 +22,9 @@ Sambee has two built-in themes (`sambee-light` and `sambee-dark`), user-owned th
 
 Each editable theme has its own server row with a globally unique ID, scope, owner (for user themes), and version. Built-in definitions remain in frontend code. A new theme ID is assigned by the server; an ID in an imported file does not claim or replace a stored theme.
 
-New and imported themes must define every editable color role. Colors use `#RRGGBB` or `#RRGGBBAA`; the server normalizes valid hex to uppercase. The role catalog includes primary, backgrounds, text, selection, links, viewer surfaces, Markdown document surfaces, search highlights, and alerts. File-type icons and document syntax colors aren't theme roles. Derived colors such as scrollbar shades, focus rings, and `background.paper` compatibility aren't editor fields. Keyboard focus rings follow the theme's primary text color: 57% opacity in light mode and 94% in dark mode. Changing that text color changes the focus color too, including in copied themes; legacy saved focus colors are ignored. Choose primary text that remains readable against the theme's surfaces.
+Colors use `#RRGGBB` or `#RRGGBBAA`; the server normalizes valid hex to uppercase. The role catalog includes primary, backgrounds, text, selection, links, viewer surfaces, Markdown document surfaces, syntax, search highlights, and alerts. File-type icons aren't theme roles. Derived colors such as scrollbar shades, focus rings, and `background.paper` compatibility aren't editor fields. Keyboard focus rings follow the theme's primary text color: 57% opacity in light mode and 94% in dark mode. Changing that text color changes the focus color too, including in copied themes; legacy saved focus colors are ignored. Choose primary text that remains readable against the theme's surfaces.
+
+Every existing editable role remains required. The additive `components.syntax` group has eight roles: `keyword`, `string`, `number`, `comment`, `type`, `function`, `operator`, and `punctuation`. If the entire group is absent from a stored definition or version-1 import, the frontend resolves the matching built-in light/dark palette without mutating or saving the original. A supplied group must contain exactly all eight valid colors; partial groups, nulls, unknown keys, and invalid colors are rejected by both frontend and backend. Save, copy, and export include the resolved group through the existing API and version-1 envelope. No database migration or separate syntax preferences are needed. Older application releases may reject these newer exports.
 
 ## Selection And Defaults
 
@@ -34,7 +38,7 @@ Appearance settings display Your themes, Site themes, then Built-in themes. Clic
 
 The editor uses a responsive dialog with collapsible color groups. A swatch opens an alpha-aware picker and each color has an editable hex field. Invalid text stays in the field without changing the valid draft. Changes in the editor aren't applied to the app until Save succeeds; Cancel discards the draft. Import replaces only the draft after validating a versioned JSON definition, and Export writes the same format.
 
-`POST /api/themes` creates a theme. Save copy opens a destination menu with Your themes for everyone and Site themes for administrators. It always creates a new theme in the chosen group without changing the applied selection. If its name already exists in that group, the editor adds ` (copy)` or a numbered copy suffix. Save updates only the opened theme in its existing group and cannot create a copy. `PUT /api/themes/{id}` and `DELETE /api/themes/{id}?version=...` require the version read by the client; a stale version returns HTTP 409. The server checks ownership, admin permissions, names, IDs, and palette completeness before committing. Bulk writes to `appearance.custom_themes` are no longer supported. There is no migration of older custom themes or compatibility promise for older exports.
+`POST /api/themes` creates a theme. Save copy opens a destination menu with Your themes for everyone and Site themes for administrators. It always creates a new theme in the chosen group without changing the applied selection. If its name already exists in that group, the editor adds ` (copy)` or a numbered copy suffix. Save updates only the opened theme in its existing group and cannot create a copy. `PUT /api/themes/{id}` and `DELETE /api/themes/{id}?version=...` require the version read by the client; a stale version returns HTTP 409. The server checks ownership, admin permissions, names, IDs, and palette completeness before committing. Bulk writes to `appearance.custom_themes` are no longer supported. Legacy syntax compatibility is limited to an entirely absent syntax group; it doesn't repair incomplete older definitions.
 
 Deleting a theme clears explicit selections referencing it. If it was the site default, that setting is cleared too; users without an override then fall back to Sambee light. An explicit selection of another theme is unaffected.
 
@@ -42,7 +46,25 @@ Deleting a theme clears explicit selections referencing it. If it was the site d
 
 Prefer the effective colors in `resolveThemePalette` and the MUI palette to hard-coded surfaces. `background.default` is the normal application surface; `background.paper` resolves to the same value for MUI compatibility. Dark chrome and dialogs use the editable `background.chrome` role. Markdown code, tables, blockquotes, and heading borders use the built-in theme's explicit document colors.
 
-Viewer toolbar foreground variants, scrollbars, and subdued states can still derive opacity-adjusted values from their source color. Keep fixed colors for assets, syntax/content rendering, and file-type icons separate from the editor palette.
+Viewer toolbar foreground variants, scrollbars, and subdued states can still derive opacity-adjusted values from their source color. Keep fixed colors for assets and file-type icons separate from the editor palette.
+
+## Shared Syntax Highlighting
+
+Text viewing/editing, Markdown source and rendered Markdown fences share the CodeMirror language registry and tag mapping in `codeMirrorHighlightingCore.ts`. `syntaxHighlighting.ts` defines application-owned language IDs, UTF-16 token ranges, categories and explicit plain-text outcomes. Native editors and the syntax worker reuse that implementation. Fence aliases resolve to existing lazy grammars, including `mssql` to MS SQL and `mariadb` to MariaDB SQL. A `.sql` filename continues to select standard SQL; unknown fence labels aren't guessed.
+
+The live Markdown viewer collects exact code occurrences from ReactMarkdown's existing AST, without another collection parse or embedded editors. A dedicated cancellable worker prepares syntax sequentially with acknowledged source chunks of at most 16,384 UTF-16 units and result pages of at most 512 ranges. Blocks above 100,000 UTF-16 units stay plain text. Nested Markdown fences use the configured Markdown parser, up to four Markdown levels including the outer block. Unknown, unlabelled and explicit plain-text fences remain neutral. A nested grammar load failure, or a parser error during static fence startup or advancement, leaves only the failed fence plain while retaining enclosing Markdown structure and successful siblings. The static adapter doesn't mutate cached grammars or retry parsing; later fences and preparations can still succeed. Closing during a pending grammar load terminates the generation's worker; reopening starts a fresh preparation. Cancellation still propagates, and exceeding the nesting limit intentionally keeps the whole outer block plain without suppressing unrelated blocks. There's no aggregate document-length or block-count cutoff. The pre-app browser capability gate requires the Web Worker API; Worker-less app operation isn't supported. The helper's defensive main-thread fallback isn't a supported browser mode or a responsiveness guarantee.
+
+Each preview generation owns cancellation and stale-result guards. After all requested blocks finish, the viewer paints at most 4,000 viewport syntax ranges through CSS Highlights. Vertical and horizontal clipping avoid publishing off-screen token ranges; scrolling, viewport resize, image loads and font readiness refresh presentation. Publication doesn't replace text nodes or insert token spans, preserving native text, whitespace, selection and the cached preview-search index. Missing highlight/visibility capabilities leave syntax plain instead of falling back to token DOM mutation. Disposal removes owned highlights, style, observers, listeners and queued frames. First visible syntax, complete preparation, memory and native interaction acceptance remain separate rollout gates; see [Viewer Architecture and Preview Contracts](../viewer-architecture-and-preview-contracts/).
+
+The existing theme provider installs stable application token rules once. Viewer/editor surfaces publish locally inherited CSS variables from the resolved MUI syntax palette, so changing theme colors doesn't require reparsing code or replacing token DOM. Identifiers and neutral code inherit the existing code foreground. Markdown source headings and structural markers use `keyword`; links use the existing link role; inline code uses the existing code foreground. Emphasis, strong text, and strikethrough change only their corresponding semantic treatment, not source font sizes or line geometry. Embedded code uses code categories, not Markdown prose styling.
+
+The shared mapping also preserves built-ins, properties and keys, booleans, null, regular expressions, escapes, and metadata/directives when the grammar supplies those tags. `TOKEN_COLOR_ROLES` maps these categories to the existing eight syntax colors: built-ins use `function`; properties and regular expressions use `type`; booleans, null, and metadata use `keyword`; escapes use `operator`. Editors and rendered fences share this mapping without another parse or a theme schema change. Built-in names aren't necessarily commands, and grammar classifications vary: PowerShell variables and bare words can both remain neutral identifiers. There are no language-specific classification overrides.
+
+Search matches use the viewer text foreground instead of syntax colors so matched keywords remain readable against their highlight backgrounds. Source editors apply that foreground to the match and its nested tokens. Preview search inherits `--sambee-search-foreground` from its own viewer; syntax highlights have priority -1, ordinary search highlights 0, and the current match 1. The shared search-color helper preserves the configured hues and uses 30%/36% opacity for ordinary/current matches in light mode and 40%/44% in dark mode. Custom theme validation checks color format and completeness, not contrast; choose text, syntax and surface colors that remain readable after alpha blending.
+
+Theme updates and lazy grammar completion preserve native selection, the active search match and both scroll axes on all four surfaces. Theme changes don't restart syntax preparation or renormalize unchanged Markdown. Late grammar completion can update editor token spans, while preview publication retains its original text nodes. These state guarantees don't establish scrolling performance, native clipboard behavior or close/navigation acceptance.
+
+Replacing an editor doesn't require replacing static highlighting. Replacing the engine requires preserving the application range/outcome contract, aliases where supported, and viewer lifecycle. Classification parity with a different engine isn't automatic. Removing CodeMirror entirely also requires migrating native editor integrations such as commands, autocomplete, and tables.
 
 ## Verification
 
@@ -55,3 +77,11 @@ cd backend && .venv/bin/python -m pytest tests/test_user_settings.py
 ```
 
 Check the Appearance grid and editor on a phone and desktop in both built-in modes. Verify selection and saved-theme refresh after focus, color picker keyboard use and placement, alpha values and export, Cancel without applying the draft, and stale-save feedback.
+
+For the production theme-dialog browser regressions, build the frontend first and keep the existing frontend/backend dev servers running. From `frontend/`, run:
+
+```bash
+SAMBEE_E2E_PRODUCTION=1 npm run test:e2e:all -- --grep 'production syntax theme dialog' --workers=1
+```
+
+The suite serves built assets and intercepts theme APIs at `http://localhost:3000/browse/smb/demo`; it doesn't change stored themes. Chromium and Firefox cover save/cancel/copy, validation focus, personal/site/built-in permissions, alpha values, unchanged selection after copying, and rejected-save feedback at 1543x900 and 390x600. Narrow desktop viewports don't replace testing on a physical phone or with assistive technology.
diff --git a/website/content/docs/2.0/developer-guide/frontend-architecture/viewer-architecture-and-preview-contracts/index.md b/website/content/docs/2.0/developer-guide/frontend-architecture/viewer-architecture-and-preview-contracts/index.md
new file mode 100644
index 000000000..94c5e785b
--- /dev/null
+++ b/website/content/docs/2.0/developer-guide/frontend-architecture/viewer-architecture-and-preview-contracts/index.md
@@ -0,0 +1,627 @@
++++
+title = "Viewer Architecture and Preview Contracts"
++++
+
+Preview behavior in Sambee is a cross-boundary contract, not just a frontend component choice.
+
+## The Core Contract
+
+The browser app decides how to render a file based on metadata and file-type information, but that depends on server-side classification staying aligned.
+
+Three rules matter most:
+
+- the backend and frontend file-type registries must describe the same extensions and MIME types
+- the backend decides whether an image format needs server-side conversion for browser compatibility
+- the frontend chooses the right viewer component and file icon based on the effective file type and MIME information it receives
+
+## Where the Main Decisions Live
+
+| Path | Responsibility |
+|---|---|
+| `backend/app/utils/file_type_registry.py` | backend source of truth for extensions, MIME types, categories, and whether an image requires conversion |
+| `frontend/src/utils/FileTypeRegistry.ts` | frontend source of truth for extensions, MIME types, categories, viewer components, icons, and colors |
+| `frontend/src/components/Viewer/` | viewer components and shared viewer UI |
+| `backend/app/services/image_converter.py` | server-side conversion for non-browser-native image formats |
+
+## Viewer Selection Model
+
+At a high level, the preview pipeline works like this:
+
+1. the backend determines file category and MIME behavior
+2. the backend decides whether the file can stream as-is or needs image conversion
+3. the frontend maps the file type to the appropriate viewer component
+4. the shared viewer controls keep the toolbar and common behavior consistent across viewers
+
+That is why a file-type change almost always touches both backend and frontend code.
+
+## Browser-Native Versus Server-Converted Images
+
+Sambee supports both browser-native formats and formats that need server-side conversion.
+
+- browser-native formats can be sent to the viewer directly
+- non-browser-native image formats are converted on the server before the browser renders them
+- special cases such as transparency preservation can change the output format choice
+
+If you change conversion rules, you are changing a product contract, not just an implementation detail.
+
+### Server-Side Conversion Contract
+
+The conversion path is owned by `backend/app/services/image_converter.py` and is exercised through the viewer API.
+
+The backend conversion service is responsible for:
+
+- deciding whether an image needs processing
+- converting unsupported or impractical browser formats into a viewer-safe output format
+- preserving transparency where the output contract requires it
+- applying optional downscaling so one preview request cannot explode memory usage casually
+- returning enough metadata for the viewer endpoint to send the correct MIME type back to the browser
+
+Representative service responsibilities include:
+
+- `needs_processing(filename)`
+- `convert_image_for_viewer(...)`
+- `is_image_file(filename)`
+- `get_image_info(...)`
+
+The viewer endpoint then follows this rule:
+
+- if the image can stream safely as-is, return a streaming response
+- if it requires conversion, read it, convert it, and return the converted bytes with the converted MIME type
+
+That means preview behavior for formats such as TIFF, HEIC, BMP, ICO, and similar formats depends on backend conversion policy, not just on frontend MIME recognition.
+
+### Local-Drive Preview Policy
+
+The Companion serves local-drive files and archive members as raw bytes. It does not copy local content to the backend for processing and does not bundle the backend image or PDF processing stack.
+
+- Browser-native images, text files, and original PDFs can preview from their raw local bytes.
+- Image formats that require server-side conversion, such as TIFF, HEIC, PSD, JPEG XL, and scientific image formats, show an explicit preview-unavailable state for local drives.
+- Image resizing and PDF compatibility normalization are unavailable for local drives.
+- Downloading and opening the original file locally remain available when a local preview is unavailable.
+
+The frontend resolves these capabilities before making a local viewer request. Local archive-member requests use the Companion's strict raw-stream contract, while SMB archive-member requests retain the full conversion and PDF-normalization request parameters.
+
+### Output Format Rules
+
+The backend does not always convert everything to the same output type.
+
+- JPEG is the common output for opaque images
+- PNG remains important when transparency must be preserved
+- ICO-like transparency handling is therefore different from ordinary opaque-photo conversion
+- alpha-bearing formats converted to JPEG need explicit compositing behavior rather than silent accidental loss
+
+If you change those rules, check both visual correctness and user-facing assumptions such as download behavior and gallery continuity.
+
+### Current Format-Specific Preview Semantics
+
+Several converted-image families have product-specific preview semantics that contributors should preserve unless the product intentionally changes.
+
+- multi-page TIFF currently previews the first page rather than exposing a document-style page stack
+- PSD and PSB preview the flattened composite instead of surfacing layer-edit semantics through the browser viewer
+- EPS and AI are rasterized through the preprocessing path at high quality, currently using the 300 DPI rendering baseline
+- HDR-oriented formats such as EXR and Radiance HDR are tone-mapped into ordinary browser-display output
+- whole-slide formats such as SVS, NDPI, SCN, MRXS, VMS, VMU, and BIF preview as an overview or first practical pyramid level rather than as a full pathology viewer
+- FITS and similar scientific-image formats apply visibility scaling so low-level pixel values become inspectable in a normal browser image surface
+
+These are not accidental implementation details. They define what users should expect from preview and therefore belong to the product contract.
+
+### Resizing and Resource Limits
+
+Server-side conversion can consume significant memory because the file must be read, decoded, and re-encoded.
+
+The current contract therefore includes:
+
+- configurable JPEG-quality behavior
+- maximum-dimension downscaling to avoid unbounded preview size
+- backend-side protection against excessive memory usage from large source images
+
+Contributors should treat those limits as operational safety controls, not as arbitrary defaults.
+
+### Dependency and Environment Expectations
+
+The conversion path depends on reviewed Python and system-image libraries.
+
+That includes the normal image stack plus HEIC/HEIF support through the reviewed dependency chain and corresponding system libraries in the container or runtime image.
+
+When conversion support seems to disappear unexpectedly, check:
+
+- the backend Python dependency set
+- the container or host system-image libraries
+- whether the format-specific support was actually installed in the current environment
+
+### Preprocessor Registry for Exotic Formats
+
+Some formats need a preprocessing step before the normal conversion path can handle them at all.
+
+That registry lives in:
+
+- `backend/app/services/preprocessor.py`
+
+It is consumed by:
+
+- `backend/app/services/image_converter.py`
+
+The preprocessor layer exists for formats that libvips should not or cannot decode directly for Sambee's preview contract.
+
+Current registered formats route through the ImageMagick-backed preprocessor:
+
+- `.psd`
+- `.psb`
+- `.eps`
+- `.ai`
+
+The registry is the single source of truth for which extensions require preprocessing before the final viewer-safe conversion step.
+
+For the backend service architecture behind that path, continue to [Image Preprocessing and Conversion Pipeline](../../backend-architecture/image-preprocessing-and-conversion-pipeline/).
+
+Representative registry operations include:
+
+- `PreprocessorRegistry.requires_preprocessing(extension)`
+- `PreprocessorRegistry.get_preprocessor_for_format(extension)`
+- `PreprocessorRegistry.get_supported_formats()`
+- `PreprocessorRegistry.register_format(extension, preprocessor_class)`
+
+### Preprocessor Design Rules
+
+The preprocessor layer has its own constraints:
+
+- one registry entry per preprocessable extension
+- direct in-memory conversion to the final browser-ready format rather than chained intermediate formats
+- no shell-mediated fallback chain logic in the registry itself
+- input validation and timeout enforcement happen in the preprocessor layer
+- failures should surface as explicit preprocessing or conversion errors rather than silent format drift
+
+The main abstraction is `PreprocessorInterface`, with `ImageMagickPreprocessor` as the current built-in implementation.
+
+### Adding a New Preprocessed Format
+
+If a new format cannot be handled by the normal conversion stack directly:
+
+1. implement a `PreprocessorInterface` subclass if the existing preprocessor is not appropriate
+2. register the extension in `PreprocessorRegistry`
+3. add or update file-type metadata if the format becomes user-visible in preview flows
+4. add tests for format recognition, tool availability, validation, and successful conversion
+
+Do not treat preprocessable formats as ordinary file-type additions. They change the backend conversion pipeline itself.
+
+### Error Surface Contributors Must Preserve
+
+Conversion failures are user-visible API behavior, not internal-only exceptions.
+
+Typical outcomes include:
+
+- not implemented when the current environment lacks support for a format family
+- unprocessable-content style failures when the file is corrupt or cannot be decoded
+- ordinary backend failures when an unexpected exception escapes the conversion path
+
+That means error wording, status behavior, and frontend fallback behavior should be reviewed together.
+
+## Shared Viewer UI
+
+The main viewer toolbar is intentionally centralized in `frontend/src/components/Viewer/ViewerControls.tsx`.
+
+This is no longer just an image-and-PDF convenience component. It is the canonical control surface for the current full-screen image, PDF, and Markdown viewers.
+
+- shared toolbar layout, styling, keyboard-tooltip behavior, and responsive behavior live in `ViewerControls`
+- each viewer turns features on through configuration and passes only the state objects it needs
+- future viewers should reuse that control shell where possible instead of creating another top-level toolbar implementation
+
+### Control-Surface Model
+
+`ViewerControls` uses a feature-flag configuration plus typed state objects.
+
+The configuration currently enables these capability groups:
+
+- `navigation` for gallery-style previous and next navigation
+- `pageNavigation` for PDF page input and page stepping
+- `zoom` for viewer-managed zoom actions
+- `rotation` for image and PDF rotation actions
+- `search` for the shared search row and match navigation affordances
+- `download` for explicit download actions
+- `share` for mobile-first share actions
+
+The component then accepts matching state surfaces:
+
+- `NavigationState` for item index, total items, and next or previous handlers
+- `PageNavigationState` for current page, total pages, and page-change handling
+- `ZoomState` for zoom-in and zoom-out handlers
+- `RotationState` for rotate-left and rotate-right handlers
+- `SearchState` for search text, match counts, search-panel state, open or close callbacks, and viewer-specific search navigation
+
+That split matters because `ViewerControls` owns the common UI, but it does not own viewer logic. It renders controls and delegates behavior back to the viewer that actually knows how to navigate pages, zoom, rotate, or search.
+
+### Current Consumers
+
+The current shared-toolbar consumers are:
+
+- `ImageViewer`, which enables gallery navigation, zoom, rotation, download, and optional mobile share
+- `PDFViewer`, which enables page navigation, zoom, rotation, search, download, and optional mobile share
+- `MarkdownViewer`, which reuses the same shell for download, optional mobile share, shared search UI, and viewer-specific action buttons such as editing flows
+
+`ViewerControls` also supports generic toolbar actions through the `actions` prop, which can render either text buttons or icon buttons. That is what allows Markdown-specific actions to live inside the same shared toolbar instead of forcing a second toolbar implementation.
+
+### Search UI Versus Search Engine
+
+The search row is shared, but the search backend is viewer-specific.
+
+- `PDFViewer` wires the search controls to PDF text extraction, page-aware match tracking, and PDF-specific next or previous navigation. Its text-layer markers use `frontend/src/utils/domTextSearch.ts`.
+- Rendered Markdown uses a preview-owned session in `frontend/src/utils/viewportDomTextSearch.ts`. It reuses the DOM index and matcher from `domTextSearch.ts`, preserving rendered-text boundaries, cross-inline matches and exact code whitespace.
+- Markdown edit mode doesn't reuse the rendered-view DOM search implementation. It bridges the same outer toolbar UI into the editor-specific search state and commands instead.
+
+The Markdown preview separates logical matches from their presentation. It retains exact match positions and text-node mappings, but paints at most 1,000 viewport search ranges plus one active-match range through CSS Highlights. Search doesn't insert markers, split text nodes or replace preview content. Navigation resolves the destination directly from the index and scrolls the content viewport, including for off-screen matches.
+
+Each preview generation owns its search session. Query changes reuse the unchanged DOM index; text replacement or character-data changes invalidate it. Syntax painting and theme-variable changes don't invalidate it. Scroll, resize, image loading and font readiness refresh presentation without matching the document again. Disposing the preview removes its highlights, style, observers, listeners, cached text and pending animation frame. PDF search remains independent.
+
+DOM capture collects text chunks and joins them once, preserving numeric offsets and block separators without repeatedly flattening the growing source. Syntax publication separately caps its viewport ranges and clips horizontally overflowing unwrapped code to visible columns. Both search and syntax skip vertical character-range lookup when the owning text box is wholly inside the viewport; partially clipped boxes retain exact boundary lookup. Horizontal clipping is independent of that fast path: the left lookup can stop at the first character, and the right lookup reuses the exact left boundary as its lower bound. Disjoint horizontal clips produce no ranges. These optimizations don't estimate character widths or cache geometry. Nested code-block scrolling refreshes syntax and search ranges without changing the source or search index.
+
+Search highlight colors inherit the preview's scoped theme variables. Browsers without CSS Highlights retain counts and indexed navigation without visual search highlighting; the viewer logs that limitation rather than falling back to whole-document marker insertion. Browser support and whole-viewer performance acceptance remain separate rollout gates. Cached indexing doesn't guarantee responsive capture or rendering for arbitrarily large documents.
+
+Use the existing production-viewer check in `frontend/e2e/markdown-viewer.spec.ts` to attribute performance within the ReactMarkdown path. Its User Timing entries separate preview-search lookup, geometry, scrolling and publication from syntax mapping, geometry, range construction and publication. Geometry reads may force layout; registry calls can include native browser work, but don't necessarily include deferred painting. Worker round trips include transfer and acknowledgements, not just parsing. Source-response, DOM-commit-observer and frame milestones narrow initial-load costs without claiming isolated React CPU or hardware input-to-visible-paint latency. Functional passes don't establish the responsiveness budgets.
+
+Initial-load Markdown normalization runs through the existing preparation worker in `frontend/src/utils/markdownCodePreparation.ts`. Each load owns a worker and transfers source, canonical text and an equivalent canonical MDAST in acknowledged, bounded chunks. Tree batches contain at most 512 records and 16,384 string UTF-16 units; individual field pieces are at most 2,048 units. Numeric/flag/position metadata is validated separately, and large text and table alignment fields use the chunk channel instead of content limits. Host acknowledgements yield between tree batches. Success, cancellation, decode failure and timeout terminate the worker; aborted loads can't publish content. Worker failures use the existing load-error path without a synchronous retry, and local preparation failures aren't reported as server overload. The pre-app capability gate requires a callable Web Worker API and otherwise shows the existing unsupported-browser screen without importing the app. The helper retains defensive synchronous normalization with a diagnostic, but Worker-less app operation isn't supported. API presence doesn't guarantee successful worker construction or execution; existing startup, timeout, crash and decode-error handling remains necessary. The shared protocol is DOM-free. Vite's shared resolver aliases the character decoder to its non-DOM implementation before dependency optimization, so development and production workers use the same implementation. A worker-build-only resolver isn't sufficient for development's prebundled dependencies.
+
+ReactMarkdown remains the only application whole-document renderer in every build mode. Its parser hook reuses a defensive clone of the prepared tree only when the tree matches the preview generation's exact source. All normal remark transforms, GFM, table-cell break handling, safe URL/raw HTML behavior and React rendering remain in that path. Cloning prevents those transforms from mutating the retained canonical tree. A successful Save that changes the source releases the superseded tree; edited content without a matching tree uses the normal parser.
+
+Rendered Markdown sources of at least 50,000 UTF-16 units use `ProgressiveMarkdown` to append the existing pipeline's fully transformed output. Document-wide references, headings and GFM are resolved once before staging. Chunks aren't parsed as independent Markdown documents. Ordinary sources keep their immediate rendering path. Staged batches use the same ReactMarkdown rendering and safe-link/raw-HTML handling, with at most 1,024 structural nodes or 8,192 text units. Oversized tables, containers and code blocks are subdivided internally, preserving one native table or code block rather than splitting it into separate documents. Already-published nodes aren't replaced by later appends.
+
+The viewer targets two viewport heights for the initial fill, then yields. Later frames use the 4 ms elapsed-work target without a height limit or repeated per-batch geometry reads. Each frame commits at most four batches, checking elapsed time after every commit to bound work accumulated before native layout. Neither the fill target nor these limits guarantee a maximum task duration: whole-document cloning/transforms, a single commit and native layout remain synchronous. Visible pages use animation frames; hidden pages use timers so completion doesn't wait indefinitely for a frame. Source or rendering-configuration changes and disposal cancel the old publication owner; a restarted generation resets document readiness. A 200 ms delayed, accessible loading indicator disappears immediately on completion and respects reduced motion.
+
+Reading published text and closing the viewer remain available during progressive loading. Document search/counts, editing, heading-link navigation and toolbar printing wait for complete publication; syntax painting and DOM search indexing also wait. Browser-menu printing while loading shows a loading notice instead of partial document content. Once complete, normal native selection, search, links and print behavior apply. These controls prevent partial results from being presented as complete; they don't promise that synchronous preparation can never block input.
+
+Markdown editing reuses the preparation worker for full-document canonical normalization when the editor source contains `<br`. The existing no-`<br` typing path still publishes immediately without normalization. If both the original baseline and edited document contain possible table syntax, a background preservation-only job compares their tables without changing that typing normalization policy. Identical sources or documents without a pipe character need no table comparison. Each editor owns at most one active job and one replaceable latest request. Only the current source, baseline, policy and generation can satisfy a prepared snapshot; obsolete success, failure and diagnostic messages are ignored. Worker acknowledgements never replace the native CodeMirror document, recreate table-cell editors or change transaction history. Pending table/IME publication and worker preparation keep the viewer dirty independently of canonical draft publication. External source changes and unmount dispose the old owner and its workers; a baseline change invalidates unmatched prepared bytes.
+
+Toolbar Save takes focus before its click handler captures selection. The rich editor therefore remembers the active nested table cell on native focus entry and departure, and refreshes that snapshot when selection is explicitly preserved inside the editor. Stay-edit Save restores the same connected cell within the current root instead of focusing the root and triggering native table-widget reconstruction. If the cell document changed while Save was pending, restoration keeps its newer native selection rather than replaying old offsets. Returning to root-text editing, replacing the external document and unmounting clear the remembered cell; disconnected or replaced cells use the existing root-selection fallback. This doesn't change native transactions, history grouping or composition handling. Production checks require retained cell identity/focus after Save, continued typing, and native undo/redo; these functional checks don't establish responsiveness acceptance.
+
+Async snapshot capture flushes table/IME publication and worker preparation within the existing transition deadline. It requires full-document normalization even after the typing fast path, so Save retains list, escape and table canonicalization. The same worker performs the unchanged AST-aware table comparison against the exact original baseline, preserving original source for semantically unchanged tables. Source and baseline transfer sequentially in acknowledged chunks of at most 16,384 UTF-16 units, with generation and sequence validation; result chunks retain the same bound. Edit preparation doesn't request a preview tree, whose offsets would no longer match preserved source. Save consumes immutable, complete source-preserving snapshot bytes; repeated serialization returns the captured string without parsing. A successful write acknowledges only its snapshot: newer pending edits stay dirty, and an unavailable newer snapshot doesn't turn the completed write into a failure. Worker failure preserves editing and dirty content; a subsequent explicit async snapshot request can retry, but failures never trigger a synchronous parsing fallback or an automatic retry loop.
+
+Synchronous snapshot capture and canonical getters reject pending or failed worker preparation, including an unmatched source-preservation baseline, rather than returning an older revision as current. Recovery retains its synchronous pagehide/pre-sign-in attempts, debounce and limits; failed capture logs the failure and shows the existing recovery warning. It doesn't mark content saved. Native text sharing is unavailable while publication is pending and reads a complete snapshot when ready. Worker-side normalization and source preservation don't establish whole-viewer timing or resource acceptance; native table editing, layout and preview reconstruction remain separately measured costs.
+
+The bounded `sambee:edit-preparation:*` entries separate queue wait, worker startup/first acknowledgement, source and baseline transfers, run-to-first-result, result delivery, total transport/job time and complete async snapshot flush. Numeric metadata records generation, source/baseline lengths, policy, chunk counts and whether a completed job is current or obsolete; it contains no source text. Transport completion also reports worker normalization and source-preservation durations separately. Host intervals include event-loop scheduling and acknowledgement delays, so startup isn't isolated worker boot time and transfer isn't pure wire time. Worker durations aren't main-thread CPU, and nested intervals mustn't be added to their enclosing job or snapshot flush. Each stage retains only its latest entry; the existing test observer collects individual samples. Use these measurements to distinguish Save wait from the native table/focus work that can follow write acknowledgement, not to infer a faster Save or passing keyboard/paint budgets from worker offload alone.
+
+The bounded `sambee:preview-preparation:*` entries separate asynchronous decode elapsed time, load normalization, tree cloning, code-block collection and ReactMarkdown transforms. `load-normalization-elapsed` includes worker startup, transfer, work, host tree assembly, acknowledgements and scheduling, not main-thread CPU time. `render-prepared-tree` measures the defensive clone; `render-parse` measures normal parsing when no matching tree is available. The initial-load production matrix requires the clone stage and rejects synchronous `render-parse` and standalone `collection-parse` stages. Live syntax request collection walks the renderer's existing tree; it doesn't parse source again or change markup. The `collection-walk` interval is included in `render-transform`, not additional time to sum. Each generation publishes its ordered requests after DOM commit, before the passive syntax preparation effect, which snapshots them and retains cancellation and stale-generation guards.
+
+The HAST-ready-to-layout-effect interval includes element construction, reconciliation, commit and scheduling, not just React CPU or paint. Entries contain no source text; each stage retains its latest measurement while the browser test observer collects individual samples. Normalization reuses its parsed tree when canonicalization leaves the source unchanged and reparses in the worker when edits change source offsets. Tree reuse doesn't close responsiveness, retained-memory, syntax-completion or native interaction acceptance.
+
+That separation is an important contract: contributors should reuse the shared search UI when possible, but should not assume every viewer can use the same search implementation under the hood.
+
+### Single-Renderer Acceptance
+
+The retained whole-document viewer integration and its special build-mode selection have been removed. Don't reconnect the historical publisher or add a second renderer to finish shared highlighting. Reuse ReactMarkdown, its parsed-tree code collection, the existing workers and viewport CSS highlights. Standalone renderer proofs are historical research, not application acceptance or a delivery dependency.
+
+Run `npm run build`, then `SAMBEE_E2E_PRODUCTION=1 SAMBEE_E2E_BUDGETS=1 npm run test:e2e:all -- --grep 'production syntax publication' --workers=1 --repeat-each=3` from `frontend/`. The existing matrix uses the approved demo connection and unchanged dense, near-safeguard, host-envelope, many-block and long-line fixtures in Chromium and Firefox at desktop and narrow widths. Add `PLAYWRIGHT_JSON_OUTPUT_FILE=/tmp/sambee-reactmarkdown-baseline.json` and `--reporter=json` to retain structured reports without npm's console preamble. Each fixture attaches `viewer-timing-budgets.json`, with observed values, numeric targets, pass/fail results and criteria that remain unmeasured.
+
+The timing gate evaluates file-click-to-text-completion, first exact search, changed query, last-match navigation and maximum viewer timer-service gap. Missing, non-finite or negative samples fail every run; `SAMBEE_E2E_BUDGETS=1` also fails over-budget samples. Omit that flag for functional-only runs, which still attach the budget result. Forced-GC and tracing runs are marked diagnostic and can't enforce timing acceptance. Run `npm run test -- src/utils/__tests__/viewerPerformanceBudgets.test.ts` from `frontend/` for the evaluator's boundary and error tests. These browser-independent checks also run in the normal Vitest CI suite, without repeating them for each browser project. To validate a recorded report, the existing Playwright entry point remains available: `SAMBEE_E2E_PRODUCTION=1 SAMBEE_E2E_REPORT=/tmp/report.json SAMBEE_E2E_SLICE=publication npm run test:e2e -- viewer-performance-budgets.spec.ts --workers=1`.
+
+Search/query/navigation probes start in browser event handlers, observe the expected count and active highlight in the existing small search controls, and finish after two frames. They avoid page-wide text queries and Playwright round-trip timing, but aren't hardware input-to-visible-paint measurements. The existing active-search fixture deliberately holds syntax preparation; text-load completion doesn't include syntax. Fresh/cached grammar isolation, first usable text/highlight completion, source editing, large prose/tables, resource acceptance and native interaction still require their own evidence. A passing timing subset isn't full rollout acceptance.
+
+The browser checks compare exact rendered text, native Select All, selected code text and accessibility-tree output. They also exercise keyboard focus, safe links/HTML, GFM tables/tasks, shared Find navigation, theme-variable updates without text-node replacement, native copy events and Chromium PDF generation. These don't establish OS clipboard payloads, browser-native Find reveal, assistive-technology behavior or visual full-document print/PDF correctness. Those remain manual gates.
+
+The separate native-constraint slice checks representative multiline, long-line and nested Markdown at widths 1543/390 in Chromium/Firefox. It compares cross-block selected text with a trusted keyboard copy/paste payload, exercises keyboard focus and native `window.find` selection/reveal, and attaches real Chromium PDFs. The native text-find API isn't the browser Find toolbar, and a narrow desktop viewport isn't a physical phone. From `frontend/`, after a normal production build, run:
+
+```sh
+PLAYWRIGHT_JSON_OUTPUT_FILE=/tmp/sambee-native-constraints.json SAMBEE_E2E_PRODUCTION=1 npm run test:e2e:all -- --grep 'production native Markdown constraints' --workers=1 --reporter=json
+```
+
+From the repository root, check the attached PDF text with the existing backend environment:
+
+```sh
+backend/.venv/bin/python -m scripts.check_native_markdown_pdf /tmp/sambee-native-constraints.json
+```
+
+The checker rejects missing/duplicate PDF cases, unsuccessful browser results and missing rendered-document lines. Heading IDs use a safe prefix and standard duplicate/Unicode slugging in the existing HAST pipeline; matching fragments are rewritten consistently. Native and printing matrices have independent checks. Chromium's `window.find` reveal is diagnostic-only because it can select without scrolling even outside Sambee; exact selection remains required in both engines, and Firefox reveal remains enforced. Don't add application scrolling to manufacture a native Find pass.
+
+The Markdown preview's Print icon calls the native browser print dialog; Save as PDF is a destination in that dialog, not a second renderer or server-side conversion. Print isn't offered in edit mode or enabled while loading has failed or is incomplete. Print-only styles hide controls/background UI, release fullscreen/scroll constraints, wrap code/table cells, retain images and use black text on white regardless of the screen theme. Native `beforeprint`/`afterprint` handlers preserve focus, selection and nested scroll, with pending callbacks removed on disposal. The fullscreen paper sizes against its fixed container rather than dynamic viewport units that can retain print-page dimensions.
+
+Run the independent print matrix from `frontend/`, then inspect the PDF attachments from the repository root:
+
+```sh
+PLAYWRIGHT_JSON_OUTPUT_FILE=/tmp/sambee-markdown-printing.json SAMBEE_E2E_PRODUCTION=1 npm run test:e2e:all -- --grep 'production Markdown printing' --workers=1 --reporter=json
+```
+
+```sh
+backend/.venv/bin/python -m scripts.check_native_markdown_pdf /tmp/sambee-markdown-printing.json --printing
+```
+
+The 24-case matrix covers three fixtures, both themes, both widths and both engines. It verifies action invocation, print CSS, wrapping/widths and actual Chromium PDF state restoration. The PDF gate requires all 12 Chromium outputs to contain every rendered non-whitespace text line and an embedded image. Clear any forced screen-media override before PDF generation; otherwise Playwright prints screen CSS. First/last-page raster inspection supplements text checks. Firefox CSS checks aren't actual Firefox PDF evidence. Actual Firefox PDF and desktop/physical printing were separately confirmed complete by the user on 2026-10-24; no detailed browser/printer support matrix is inferred. Browser destination, paper, margin and header/footer settings remain user-controlled.
+
+Keep performance changes local to measured costs in the current path. Distinguish first visible syntax from completion of all block preparation, and include serialization and parent updates when measuring typing or atomic replace-all. Configuration-only theme and grammar updates must not request caret reveal or replace the document, selection or editor. Don't add streaming, scheduling abstractions or new edit protocols without evidence that the existing path misses its target.
+
+The existing viewer harness also has a `production source responsiveness` slice for the 54,000-unit dense and 6,000-match long-line source fixtures. It verifies bounded worker delivery, one atomic replacement, undo/redo, exact saved file bytes and worker termination. Save assertions decode the complete multipart body received by the isolated test HTTP proxy; Playwright's request snapshot can omit uploaded file bytes. All traffic uses fixtures, never stored demo edits.
+
+Large Replace All operations may temporarily block the editor while CodeMirror applies their atomic change set. This latency is an accepted limitation under D5, not permission to truncate output, split history or replace the entire document instead of preserving logical changes. Text and Markdown editors share an editor-owned indeterminate replacement indicator. Worker preparation shows it only after 200 ms; completion before that threshold cancels it without a flash. Ordinary literal replacements stay synchronous and aren't given an artificial delay.
+
+Before a known-heavy apply, the indicator is shown and given two animation-frame callbacks so the browser has a paint opportunity before the native dispatch. The conservative workload gate requires at least 1,000 replacements and at least 50,000 UTF-16 units in the source or inserted payload. Literal commands inspect at most 1,000 matches for this estimate; worker commands use the completed change plan. This isn't a duration prediction: some fast workloads may be classified as heavy, and unexpectedly slow synchronous work cannot reveal a delayed indicator while blocking the main thread. Feedback already visible during preparation also receives a paint opportunity before application. There's no minimum visible duration or delayed completion, and the spinner doesn't promise continued animation or input responsiveness during synchronous apply.
+
+The same command boundary covers toolbar and keyboard Replace All. Pending replacements reject duplicate invocations. Any introduced yield revalidates the exact document, query, selection and writability; editing or switching state cancels obsolete work rather than applying stale replacements. Failure, timeout, cancellation and editor disposal release the indicator, animation, timers and listeners. Hidden documents don't wait indefinitely for throttled animation frames. The status uses the editor theme, exposes accessible busy/status semantics and respects reduced motion; physical assistive-technology behavior remains a separate manual check.
+
+The `production replacement feedback` slice checks quick no-flash behavior and captures visible feedback with the original source still present, then releases held frames and verifies atomic undo/redo, exact multipart Save and editor cleanup in both engines at widths 1543/390. Its held-frame evidence is functional, not timing acceptance.
+
+Source edits retain one bounded User Timing entry per stage: `sambee:source-editor:serialize`, `sambee:source-editor:publish`, `sambee:source-editor:normalize` and `sambee:source-editor:parent-update`. The enclosing publication includes normalization and the synchronous parent callback. These overlapping stages mustn't be added together. Entries contain lengths/revisions, not document contents. `sambee:source-search:commit` brackets the native atomic dispatch, including its synchronous listeners; deferred React work isn't isolated CPU time inside that measure. The separate click-to-completion probe waits for the parent dirty-state render and two subsequent frames. That boundary is a scheduling proxy, not hardware paint.
+
+From `frontend/`, after a normal production build, run:
+
+```sh
+PLAYWRIGHT_JSON_OUTPUT_FILE=/tmp/sambee-source-responsiveness.json SAMBEE_E2E_PRODUCTION=1 SAMBEE_E2E_BUDGETS=1 npm run test:e2e:all -- --grep 'production source responsiveness' --workers=1 --repeat-each=3 --reporter=json
+```
+
+Each sample attaches source-private measurements and explicit 50 ms atomic-dispatch, enclosing serialization/publication and maximum-timer-gap checks. Missing or invalid evidence fails even without `SAMBEE_E2E_BUDGETS`; that flag additionally enforces the original limits. Retain the failed native atomic-application timing results as diagnostic evidence of the D5 accepted limitation, not as passing samples or a reason to repeat performance-only matrices. Unrelated source timing, worker correctness and resource gates remain required. Transfer counts aren't retained/peak memory evidence, and these fixtures don't establish sustained typing, large-table normalization, dense output expansion or scrolling acceptance.
+
+The separate `production source typing` slice types 82 characters at a requested 10 ms inter-key delay into each 54,000-unit fixture, without per-key polling. It records trusted browser keydown-to-first/two-frame samples, timer gaps, all four edit stages and optional whole-renderer Long Tasks entries, then verifies exact saved source plus the payload. The `source-typing` attachment enforces two-frame p95 strictly below 50 ms and stage/gap maxima at most 50 ms. All 24 engine/width/repeat trials pass; the worst per-trial p95 is 35 ms. This is a scheduling proxy, not physical input-to-painted-pixel acceptance. Unsupported Long Tasks capability stays unmeasured, and observed tasks wouldn't establish application-owned CPU attribution.
+
+The `production prose table responsiveness` slice mounts the approved 4,000 formatted paragraphs or 2,400 two-column table rows. It checks every rendered paragraph/cell exactly, preserves native block whitespace, root/text-node identity and full rendered text through 60 programmatic scroll steps, and verifies cross-block native selection and close cleanup. Load timing runs from the browser's file-open click through two frames after all expected blocks mount. The `prose-table-responsiveness` attachment separates load budgets, the earlier two-viewport geometry milestone and diagnostic rAF scroll intervals, including the frame following the final scroll assignment. The final 24 trials complete within 1,110 ms, with the first viewport available within 761 ms. Nineteen trials exceed the unchanged 50 ms timer-gap limit, with a worst gap of 128 ms. These recorded loading pauses are accepted under D6, not passing timing samples or isolated CPU attribution. Headless rAF intervals don't establish physical refresh rate, wheel/touch, compositor or painted-frame acceptance. These fixtures have no fenced syntax and don't measure syntax readiness or large-table source normalization.
+
+The separate `production progressive Markdown loading cancellation` slice holds frame callbacks after two viewport heights exist. It requires visible feedback, disabled document controls, loading-only print output and a working Close action, then releases stale callbacks and verifies complete reopening. It runs in Chromium and Firefox at widths 1543/390. Its paused screenshots and functional passes aren't timing evidence. The existing large-code publication, native interaction and print matrices remain independent regression checks; their completion and acceptance boundaries are recorded below.
+
+Run these slices separately from forced GC and CPU profiling:
+
+```sh
+PLAYWRIGHT_JSON_OUTPUT_FILE=/tmp/sambee-source-typing.json SAMBEE_E2E_PRODUCTION=1 SAMBEE_E2E_BUDGETS=1 npm run test:e2e:all -- --grep 'production source typing' --workers=1 --repeat-each=3 --reporter=json
+PLAYWRIGHT_JSON_OUTPUT_FILE=/tmp/sambee-prose-table-responsiveness-final.json SAMBEE_E2E_PRODUCTION=1 SAMBEE_E2E_BUDGETS=1 npm run test:e2e:all -- --grep 'production prose table responsiveness' --workers=1 --repeat-each=3 --reporter=json
+```
+
+For separate Chromium load attribution, select the same prose/table slice with `SAMBEE_E2E_TRACE=1` and no budget enforcement or forced GC. The `viewer-load-cpu-profile` and `viewer-load-timeline` attachments span file open through completed mounting; nonempty CPU samples and both `sambee:viewer-load:start`/`sambee:viewer-load:complete` timeline markers are required. Budget status is diagnostic, never acceptance. Two desktop captures show one preview build, with a 126.05 ms prose render callback and a 53.69 ms table callback before native style/layout. The prose clone, transforms and HAST-to-layout-effect stages take 38.3, 37.5 and 44.5 ms; these overlap the encompassing callback and mustn't be added to it. Prose native style/layout takes a further 21.14/38.13 ms. Keep cached-tree isolation and native document semantics; neither deleting the clone nor an unapproved publication/renderer change is justified by this evidence. Firefox/mobile CPU attribution remains unverified.
+
+Chromium CPU sample deltas can be negative. Reconstruct cumulative sample timestamps, sort them, then clip nonoverlapping intervals to the load markers. Summing only positive deltas inflates CPU weights. Use the marker's renderer PID/thread for main-thread timeline attribution; worker processing and unclassified native samples aren't automatically application-owned blocking CPU.
+
+Repeated source-regex Next/Previous requests are queued in order while navigation is pending. The active navigation worker reuses its transferred document for that burst, applying each native CodeMirror command from the preceding result's selection with the current position's whole-word rules. It terminates when the queue drains; no idle worker is retained. Document/query changes, external selection changes, replacement commands, failures and disposal cancel obsolete queued navigation. Unit tests compare reused-worker navigation with native commands, including mixed directions, wraparound, overlapping matches and zero-length expressions.
+
+The independent `production source regex parity` slice compares counts and exact saved output with the installed CodeMirror commands for zero-length lookahead, case-sensitive and whole-word matching. A replacement exceeding two source-transfer chunks verifies continuation assembly without truncation. `production source regex lifecycle` injects worker-construction, error/decode-event and startup-timeout failures, requires actionable feedback and a successful retry, and preserves continued editing and exact Save bytes. A partial-delivery case lets one replacement chunk arrive before cancellation, then replays stale change/completion messages; no partial replacement may be committed. These are host-side fault injections, not actual browser-process crash or structured-clone failure evidence. Run both functional slices with:
+
+```sh
+SAMBEE_E2E_PRODUCTION=1 npm run test:e2e:all -- --grep 'production source regex (parity|lifecycle)' --workers=1
+```
+
+For optional source renderer footprint diagnostics, use `SAMBEE_E2E_MEMORY=1` without timing enforcement, select `production source responsiveness`, and run the Chromium-only `npm run test:e2e`. The `source-renderer-memory` attachment records CDP renderer heap after explicit GC at pre-open, counted-results, post-replacement and post-close boundaries. Its historical 64 MiB assertion isn't a release criterion under D11. These are whole-viewer post-GC observations, not isolated result-array bytes, peak/worker/native memory or proof of leak-free cleanup. Staged/peak-memory limits and a fixed close/reopen cycle protocol aren't required. The source budget status is diagnostic in memory mode.
+
+For a separate Chromium CPU diagnostic, use `SAMBEE_E2E_TRACE=1` without `SAMBEE_E2E_BUDGETS=1`, restrict the grep to `production source responsiveness long-line at 1543px`, and run `npm run test:e2e`. The `source-dispatch-cpu-profile` attachment contains the CDP CPU profile; its source budget status is diagnostic, never an acceptance pass. The source slice rejects combined profiling/GC and either diagnostic mode combined with timing enforcement.
+
+For separate controlled-memory trials, add `SAMBEE_E2E_MEMORY=1` and restrict the existing matrix to the many-block fixture and Chromium. Release harness-held node references before post-GC sampling. Renderer heap excludes worker heaps and aggregate/native memory; a single close isn't repeated-close leak acceptance. Keep forced GC separate from responsiveness timing.
+
+For diagnostic scheduling traces, add `SAMBEE_E2E_TRACE=1` to a single-fixture Chromium run. The `viewer-scheduling-trace` attachment contains a CDP timeline and V8 CPU profile. Align `sambee:viewer-trace:start` with browser timestamps; join CPU chunks by renderer PID and profile ID and count samples once. Firefox native profiling must use content-process User Timing markers rather than parent-only samples. Profiling adds overhead and isn't acceptance timing.
+
+To isolate native table input from application work, run the existing proof from `frontend/`:
+
+```sh
+SAMBEE_NATIVE_TABLE_REPORT=/tmp/sambee-native-table node scripts/source-search-containment-proof.mjs --native-table
+```
+
+This uses public CodeMirror/Lezer and `markdownTables` APIs at the approved demo URL, with an isolated HTML response and default package styling. It edits the middle cell of the fixed 2,400-row table at 1543x900 without React, application CSS, normalization, Save or workers. It requires exact complete native source, atomic full-table replacement spans, native undo/redo and disposal. Native table source uses `<br>`; application canonicalization to `<br />` isn't part of this proof. Root state materialization and view-update intervals are reported separately; input-to-root includes scheduling and deferred publication, not just model CPU. The unminified desktop diagnostic isn't a production acceptance trial or a replacement for mobile, composition and lifecycle checks.
+
+The optional report prefix writes per-engine JSON and the exact diagnostic bundle. For separate profiling, add `SAMBEE_E2E_TRACE=1` and configure `MOZ_PROFILER_STARTUP=1`, `MOZ_PROFILER_STARTUP_FILTERS=GeckoMain`, `MOZ_PROFILER_STARTUP_FEATURES=js,stackwalk,leaf` and `MOZ_PROFILER_SHUTDOWN` with an absolute output path. Chromium records input-only CPU samples; clip Firefox content-process samples between `sambee:native-table:input-start` and `sambee:native-table:input-end`, excluding construction and history checks. Profiling requires a report prefix and Firefox startup configuration; product-budget enforcement and controlled-GC modes are rejected. Inclusive model, parsing and native reflow samples overlap and mustn't be summed. Unclassified Chromium native samples aren't automatically package JavaScript CPU. Slow native input doesn't by itself establish slow atomic state application or justify private package patches, changed history, wrapping or selection semantics.
+
+Count assertions remain scoped to the existing search controls to avoid page-wide Playwright text caches inside measurement windows. Results are labelled `scoped-controls-v2`; older input figures aren't directly comparable. Handler-to-frame samples and synthetic event age don't establish hardware input-to-visible-paint latency. Removing the alternate renderer doesn't close any performance, memory or manual interaction gate.
+
+### Shared Highlighting Acceptance And Limitations
+
+The shared-highlighting implementation was approved by the user for merge and rollout on 2026-10-24. Approval doesn't turn failed measurements into passes or establish support for untested devices. Keep original targets, raw verdicts and these scoped acceptance decisions together:
+
+| Decision | Accepted scope | Boundaries |
+|---|---|---|
+| D5 | Noticeable large atomic Replace All latency with visible busy feedback. | Preserve complete output, logical change mapping, one native transaction and undo/redo. Unrelated source-search or typing pauses aren't accepted by this decision. |
+| D6 | The recorded progressive prose/table preview-loading pauses: 19/24 trials above 50 ms, worst 128 ms; all complete within 1,110 ms. | These remain failed gap samples. Longer future delays and other workloads aren't covered. Asynchronous preview preparation remains declined. |
+| D8 | Responsiveness limitations of the existing Markdown table editor. | Table-component timing is diagnostic and non-blocking; exact input, Save, composition, history and cleanup remain required. |
+| D9 | Ten recorded Firefox many-block syntax-color samples at 1,511-1,579 ms against the 1,500 ms target. | All 120 cold/warm samples were collected; 110 meet that target. Full syntax preparation stays within 3,000 ms. No broader delay exception is implied. |
+| D10 | Four recorded Firefox desktop code-display gaps at 51-59 ms against 50 ms. | Preserve the raw failures. Additional delayed-image/font/resize and scroll-anchor test coverage was removed, not passed. Correct content, selection and scrolling remain required. |
+| D11 | Leak investigation and fixes for demonstrated unwanted retention, rather than quantitative memory acceptance. | Staged/peak-memory limits and fixed-cycle shutdown checks were removed, not passed. No exhaustive leak-free claim is made. |
+| D12 | Removal of real-phone and physical keyboard/IME acceptance, including phone print UI and hardware-response measurements. | This isn't verified device support. Automated keyboard/composition, exact editing/Save/recovery and desktop native/print correctness remain required. |
+
+Browser-menu Find/reveal, OS clipboard, assistive-technology and physical-scrolling checks were confirmed complete by the user on 2026-10-23. Remaining Firefox PDF and desktop/physical printing checks were confirmed complete on 2026-10-24. These are user confirmations, not new automated measurements or a detailed device, browser, AT or printer support matrix. Don't reopen completed checks or rerun accepted timing failures solely to close a checklist; retest affected behavior after a relevant change or demonstrated regression.
+
+The final editing checks cover theme changes followed by editing exit and Close, late worker results, distinct documents, captured-revision Save with newer dirty edits, failed writes and recovery/snapshot failures. Source-regex terminal cleanup detaches worker handlers, releases terminated workers and clears obsolete replacement buffers, while retaining buffers needed for a pending atomic apply. Ownership review and lifecycle assertions establish the investigated cleanup, not a heap-retention proof for every browser object.
+
+Use `PLAYWRIGHT_JSON_OUTPUT_FILE`, not `PLAYWRIGHT_JSON_OUTPUT_NAME`, for an explicit report path with the JSON reporter. Preserve complete identities, both engines, widths 1543/390, original workloads and three trials per timing identity. Recorded-report evaluation must retain failed samples and reject missing, duplicate, invalid, skipped or retried identities. Functional-only runs and tracing/GC diagnostics don't establish timing passes. Retain local reports before temporary-file cleanup; overlapping runs aren't additive test totals.
+
+### Responsive and Accessibility Rules
+
+The centralized toolbar also encodes product behavior that should stay consistent across viewers.
+
+- filename display, optional filename adornments, and close behavior are shared
+- mobile layout uses safe-area-aware spacing and smaller controls
+- gallery arrows and desktop zoom controls are intentionally reduced on mobile, where gesture-based interaction is preferred
+- share is exposed as a mobile-first affordance, with optional early-intent warming through `onShareIntent`
+- buttons use explicit `aria-label` values and shortcut-oriented `title` text so the control surface remains navigable and self-describing
+- the shared search row manages focus when it opens and preserves consistent close behavior for toggle and Escape-driven exits
+
+### Legacy Components and Contributor Guidance
+
+Legacy `ImageControls.tsx` and `PDFControls.tsx` files still exist in the frontend tree, but `ViewerControls` is the current architectural direction and the shared component used by the active image, PDF, and Markdown viewers.
+
+If you add another viewer or extend an existing one:
+
+- prefer extending `ViewerControlsConfig`, the relevant state interfaces, or the generic `actions` surface
+- keep viewer-specific logic in the viewer component rather than teaching `ViewerControls` about file-format internals
+- preserve shared mobile, accessibility, and search-panel behavior unless the product intentionally changes that contract
+- add or update focused tests in `frontend/src/components/Viewer/__tests__/ViewerControls.test.tsx` when the shared toolbar contract changes
+
+## Adding a New File Type Safely
+
+File-type support is registry-driven. The safest way to add a new type is to treat backend and frontend changes as one contract update.
+
+### Main Files to Change
+
+| Path | Why it changes |
+|---|---|
+| `backend/app/utils/file_type_registry.py` | declare extensions, MIME types, category, description, and whether an image requires conversion |
+| `frontend/src/utils/FileTypeRegistry.ts` | declare extensions, MIME types, category, viewer component, icon, color, and description |
+| `frontend/src/components/Viewer/` | add or reuse a viewer component when the type needs a dedicated preview surface |
+
+If a file type is user-visible, update the published support docs that describe what Sambee can preview.
+
+### Quick Start for a New Image Format
+
+For an image format such as JPEG XL, the minimum workflow is:
+
+1. add a `FileTypeDefinition` entry to the backend registry
+2. add the matching entry to the frontend registry
+3. decide whether the image is browser-native or requires server-side conversion
+4. keep extensions and MIME types identical across both registries
+5. run the viewer and backend validation checks
+
+Backend example:
+
+```python
+FileTypeDefinition(
+		extensions=(".jxl",),
+		mime_types=("image/jxl",),
+		category=FileCategory.IMAGE,
+		requires_conversion=True,
+		description="JPEG XL Image",
+)
+```
+
+Frontend example:
+
+```typescript
+{
+	extensions: [".jxl"],
+	mimeTypes: ["image/jxl"],
+	category: "image",
+	viewerComponent: () => import("../components/Viewer/ImageViewer"),
+	icon: "image",
+	color: "#a855f7",
+	description: "JPEG XL Image",
+}
+```
+
+That registry update is what drives MIME matching, icon treatment, viewer routing, and image-gallery inclusion.
+
+### Backend Registry Rules
+
+Backend file-type definitions must stay explicit and type-safe.
+
+- `extensions` are tuples with a leading dot, such as `(".jpg", ".jpeg")`
+- `mime_types` are tuples of standard MIME strings
+- `category` uses `FileCategory` values such as `IMAGE`, `DOCUMENT`, `TEXT`, `VIDEO`, `AUDIO`, `ARCHIVE`, `CODE`, `SPREADSHEET`, or `OTHER`
+- `requires_conversion` matters for image formats that cannot be rendered directly by the browser
+- `description` should be the human-readable label contributors and users would expect
+
+How to decide `requires_conversion`:
+
+- set it to `False` for browser-native formats such as PNG, JPEG, GIF, WebP, SVG, and AVIF
+- set it to `True` for formats with limited browser support or formats that are not practical to render directly, such as TIFF, HEIC, BMP, JPEG 2000, or JPEG XL when browser support is not sufficient for the product baseline
+
+### Frontend Registry Rules
+
+Frontend file-type definitions control how the browser app presents the file.
+
+- keep `extensions` and `mimeTypes` aligned with the backend registry
+- set `viewerComponent` to the shared viewer that should render the type
+- choose an icon that matches the product language for that file category
+- choose a color that distinguishes the format without inventing a new palette on every addition
+
+For image formats, reusing `ImageViewer` is usually enough. For non-image formats, you may need a dedicated viewer such as `PdfViewer`, `VideoViewer`, `AudioViewer`, or `TextViewer`.
+
+### Non-Image File Types
+
+The overall process is the same for documents, video, audio, text, archives, and code files.
+
+1. add the backend registry entry
+2. add the frontend registry entry
+3. create or reuse the viewer component when preview support exists
+4. verify the file icon, viewer routing, and download behavior
+
+For non-image files, `requires_conversion` is usually `False`. The main design question is whether the product has a viewer component for that category or should fall back to download-only behavior.
+
+### Integration Checklist
+
+Use this checklist before you consider the file type integrated:
+
+- backend registry entry added
+- frontend registry entry added
+- extensions and MIME types match exactly across both registries
+- browser-native versus converted-image behavior decided intentionally
+- viewer component chosen or added
+- icon and color treatment chosen
+- user-visible support docs updated if the file type changes what Sambee can preview
+
+### Testing Checklist
+
+After the registry change, verify:
+
+- icon display in the file browser
+- file opening in the expected viewer
+- shared toolbar behavior if the preview uses `ViewerControls`
+- conversion output if the format is server-converted
+- gallery inclusion for image formats
+- MIME type behavior across extension variants such as upper-case filenames
+- download behavior with the correct MIME type
+- mobile and tablet behavior when the preview is expected to work there
+
+For server-converted formats, also verify:
+
+- the backend returns the converted MIME type you expect
+- transparency-sensitive formats still render correctly
+- resizing or quality settings do not degrade the preview contract unexpectedly
+- environment-specific format support failures surface in a controlled way
+
+For preprocessable formats, also verify:
+
+- the registry recognizes the extension regardless of case and leading-dot differences
+- the expected preprocessor is selected for that format
+- missing external-tool support fails cleanly
+- validation and timeout rules behave as intended under bad inputs and slow conversions
+
+### Architecture Notes
+
+These helper functions are the practical integration points contributors usually touch:
+
+- backend: `get_mime_type`, `needs_processing`, `is_image_file`, `get_file_type_by_extension`, `get_file_type_by_mime`
+- frontend: `getViewerComponent`, `isImageFile`, `getFileIcon`, `getFileTypeByExtension`, `getFileTypeByMime`
+
+At runtime, the flow is:
+
+1. the backend lists files and assigns MIME information
+2. the frontend receives `FileInfo` data with that MIME information
+3. the frontend chooses icon treatment from filename and type rules
+4. the frontend selects the viewer from MIME and file-type data
+5. the backend routes convertible images through the image-conversion pipeline when needed
+
+The frontend side still has work to do even when the backend owns the conversion:
+
+- viewer MIME recognition must include the input formats the backend classifies as previewable
+- file-type icon and color treatment must still reflect the original file type rather than the converted transport format
+- browser-side fallback MIME logic must not drift from the backend contract in ways that hide conversion bugs
+
+### Operational Characteristics
+
+Server-side conversion changes the runtime profile of preview requests.
+
+- large images can produce short CPU spikes during decode and encode
+- memory usage can rise well above compressed input size while the image is fully decoded
+- SMB-backed reads add their own latency before conversion even starts
+
+That is why preview regressions for large HEIC or TIFF files often need both backend and user-facing verification.
+
+### Future Extension Points
+
+The current conversion path leaves room for later enhancements such as:
+
+- caching converted preview outputs
+- queueing especially large conversions
+- dedicated thumbnail generation
+- richer multi-page image handling
+- conversion metrics for operational monitoring
+
+Those are extension points, not assumptions the current product already guarantees.
+
+The highest-risk mistake is still registry drift. If the backend and frontend disagree about extensions or MIME types, preview behavior becomes unreliable in ways that are easy to miss until users hit them.
+
+## Common Failure Modes
+
+- backend and frontend MIME types do not match
+- a format is marked browser-native when it really needs conversion
+- a viewer component is not registered even though the type is recognized
+- a conversion change improves one format but breaks gallery behavior, download semantics, or mobile viewing
+
+## Validation Expectations
+
+When you change viewer or file-type behavior, usually run:
+
+```bash
+cd frontend && npm test
+cd frontend && npm run typecheck
+cd frontend && npm run lint
+cd backend && pytest -v
+```
+
+If the change is image-conversion-specific, include the relevant backend tests around image conversion and preview behavior.
diff --git a/website/content/docs/2.0/developer-guide/frontend-architecture/viewer-architecture-and-preview-contracts/inherit.md b/website/content/docs/2.0/developer-guide/frontend-architecture/viewer-architecture-and-preview-contracts/inherit.md
deleted file mode 100644
index e69de29bb..000000000
diff --git a/website/content/docs/2.0/developer-guide/release-and-versioning/dependency-update-workflow/index.md b/website/content/docs/2.0/developer-guide/release-and-versioning/dependency-update-workflow/index.md
index f65495f1e..26e10a09f 100644
--- a/website/content/docs/2.0/developer-guide/release-and-versioning/dependency-update-workflow/index.md
+++ b/website/content/docs/2.0/developer-guide/release-and-versioning/dependency-update-workflow/index.md
@@ -110,7 +110,7 @@ Common examples:
 ```bash
 cd backend && pytest -v
 cd backend && mypy app
-cd frontend && npx tsc --noEmit && npm run lint
+cd frontend && npm run typecheck && npm run lint
 cd companion && npx tsc --noEmit && npm run lint
 ```
 
diff --git a/website/content/docs/2.0/developer-guide/testing-and-quality-gates/ci-workflows-and-repository-automation/index.md b/website/content/docs/2.0/developer-guide/testing-and-quality-gates/ci-workflows-and-repository-automation/index.md
index 3633c4061..2748db601 100644
--- a/website/content/docs/2.0/developer-guide/testing-and-quality-gates/ci-workflows-and-repository-automation/index.md
+++ b/website/content/docs/2.0/developer-guide/testing-and-quality-gates/ci-workflows-and-repository-automation/index.md
@@ -52,27 +52,32 @@ Those are not repository workflows, so their display names are not controlled by
 It first detects which top-level product areas changed, then fans out only the relevant jobs for:
 
 - backend
-- frontend
-- frontend Playwright Chromium smoke
-- frontend Playwright Firefox markdown coverage on pushes to `main` and manual runs
+- frontend, including Chromium and Firefox browser correctness
 - companion
+- website documentation
 
-Manual dispatch runs all three areas.
+Manual dispatch runs all areas. Changes to shared frontend CI infrastructure also select frontend validation.
 
 The workflow ends with a single gate job so branch protection can depend on one stable required check instead of a changing set of per-area jobs.
 
 In the backend job, regular tests run under `pytest-xdist` for throughput, while `@performance` tests run in a separate serial pass so wall-clock assertions are not distorted by parallel worker contention.
 
-For frontend coverage, the workflow is intentionally layered:
+Backend pytest runs treat unexpected warnings as errors, including resource-cleanup warnings. The shared policy in `backend/pyproject.toml` applies to both local and CI runs, and warning summaries aren't suppressed. Tests that deliberately trigger a warning must assert it with `pytest.warns(...)`, matching the warning category and message. Fix application warnings rather than ignoring them. Unavoidable dependency exceptions must be narrowly scoped and documented; the current exception covers Starlette's TestClient reference to AnyIO's deprecated `BlockingPortal` alias. Remove that exception when the dependency no longer needs it.
 
-- the `frontend` job keeps the fast TypeScript, lint, and Vitest checks in the main PR path
-- the `frontend-e2e` job runs a bounded Playwright Chromium smoke slice on frontend changes
-- the `frontend-e2e-firefox` job runs the markdown editor Playwright slice only on pushes to `main` and manual dispatch
+The `frontend` job requires a clean TypeScript check, runs Vitest, builds normal production assets, installs version-matched Playwright Chromium/Firefox binaries and their Linux dependencies, then runs `npm run test:browser:ci`. Both engines run on frontend pull requests, pushes, and manual dispatch. The same required checks run in release fallback when successful source CI cannot be reused.
 
-That split keeps pull-request runtime under control while still protecting the browser-sensitive editing workflows that unit tests do not cover.
+The browser command requires exactly 16 production cases: four scenarios at desktop and narrow widths in each engine. They protect real normalization/syntax workers, entity decoding, native selection/focus/heading links/search, regex replacement with undo/redo and exact Save content, and cancellation/reopen cleanup with stale-result replay. Two additional development-worker cases exercise Vite's dependency-resolution path. Browser APIs and workers are real; backend responses are mocked at `http://localhost:3000/browse/smb/demo`. This isn't full-stack SMB E2E or evidence of physical printing, browser-menu Find, hardware IME, or assistive-technology behavior.
+
+The correctness reporter rejects missing, duplicate, skipped, failed, and retried cases. Browser cases run with one worker and no retries. Reports and retained failure traces/screenshots are uploaded for seven days. Timing budgets, profiling, heap measurements, alternate renderers, and repeated cache/performance matrices remain separate opt-in diagnostics.
+
+`npm run typecheck` runs `tsc -b --noEmit` across the application, test/helper, and Node configuration projects. Browser code uses browser types; tests add Vitest and Node types; configuration tooling uses Node types. All source and declaration files remain checked with strict null/index and unused-code diagnostics enabled. The ES2023 library declarations describe existing APIs; the emitted target remains ES2020, and declarations don't provide runtime polyfills.
+
+Type correctness is mandatory in routine CI, release fallback, ordinary `npm run build`, `./scripts/test`, and the VS Code frontend validation task. The old root `tsc --noEmit` command checked no input files and mustn't be used as a substitute. Regression tests protect required command wiring, strict options, separate environments, and complete source coverage. Unit and browser correctness remain independent required gates.
+
+The required gate rejects an unexpectedly skipped selected job. Only unrelated, unselected areas may be skipped. Superseded pull-request test/lint runs are cancelled; main-branch validation runs aren't cancelled by that policy. Release reuse requires the exact source commit's successful frontend job, its successful browser-correctness step, and the new required `Verify frontend type correctness` step. Missing, skipped, or failed steps and legacy advisory type-check runs don't qualify.
 
 The current companion test job does not call `./scripts/test`.
-It runs explicit steps for Node install, companion TypeScript type checking, and `cargo test`.
+It runs explicit steps for Node install, companion TypeScript type checking, and the archive topology conformance script, including Rust tests, formatting, and Clippy.
 That means the local Windows GNU cross-check in `./scripts/test` does not currently run in `CI: Test`.
 
 ### Caching Model
@@ -81,12 +86,14 @@ The test workflow uses layered caching to reduce repeated setup work while keepi
 
 Current cache layers include:
 
-- `backend/.venv` caching keyed by the resolved backend requirement files and Python version.
-- `backend/.mypy_cache` caching keyed by backend Python source changes.
+- GitHub Actions BuildKit caching for the `backend-test` Docker target, with dependency layers before source copies.
 - `actions/setup-node` npm download caching for frontend and companion jobs.
-- `frontend/node_modules` caching keyed by `frontend/package-lock.json`.
 - Rust build caching for `companion/src-tauri`.
 
+Frontend jobs use clean `npm ci --prefer-offline` installs; they don't cache `node_modules` or Playwright browser downloads. The mypy cache inside the disposable backend test container isn't persisted separately.
+
+Vitest file parallelism is capped at four workers and further limited by the runner's available CPUs and RAM, reserving 2 GiB plus 2 GiB per worker. The CI command logs the actual resources and selected cap. Standard public Ubuntu runners currently provide 4 vCPUs/16 GB RAM; private runners provide 2 vCPUs/8 GB RAM. Local measurements on a larger machine aren't Actions performance guarantees.
+
 Treat those cache keys as reviewed dependency inputs, not as disposable generated noise.
 
 When dependency manifests or lockfiles change, commit the corresponding lockfile updates in the same pull request so cache invalidation and dependency review stay aligned.
@@ -107,8 +114,11 @@ When you want a closer CI-style pass, run the per-subsystem checks from [Test St
 
 For frontend work, that usually means:
 
-- `cd frontend && npm test` for the default Vitest suite
-- `cd frontend && npm run test:e2e` for the default Chromium browser pass
+- `cd frontend && npm run test` for the default Vitest suite
+- `cd frontend && npm run test:ci` for runner-aware Vitest concurrency
+- `cd frontend && npm run typecheck` for the complete strict compiler check
+- `cd frontend && npm run build` followed by `npm run test:browser:ci` for the exact production/development browser contract
+- `cd frontend && npm run test:e2e:install -- --with-deps` to install the matching browsers and Linux dependencies
 
 `./scripts/test` now includes a local companion Windows GNU target compatibility check.
 That check is intentionally a local validation aid, not part of the current `CI: Test` workflow contract.
@@ -123,6 +133,8 @@ Current coverage includes:
 - frontend Biome validation.
 - companion Clippy, Rustfmt, and Biome validation.
 
+Ruff's executable-script rules (`EXE`) also check Python files throughout the repository, including `.github/`. Any Python-file change selects backend lint, as do changes to the lint workflow or `scripts/test`. These checks fail CI and `./scripts/test` on errors; they aren't advisory. A script with a shebang must be executable. Files invoked explicitly through Python, and imported modules, don't need a shebang.
+
 The lint workflow does not run the local companion Windows GNU cross-check either.
 That cross-target validation is currently a local developer workflow check, while actual Windows artifact creation remains in the release workflow.
 
@@ -130,17 +142,9 @@ The workflow also ends with one gate job so branch protection can depend on a st
 
 ## Runner Distro Policy
 
-Sambee does not require every GitHub Actions job to run on the same base distro.
-
-Instead, the rule is:
-
-- jobs that validate production-like runtime behavior or install native runtime dependencies should follow the same Debian family used by the production image and the dev container
-- jobs that only run language-level checks, dependency audits, repository automation, or other host-agnostic validation can stay on `ubuntu-latest`
-
-Current Debian-family jobs include:
+All Ubuntu x64 host jobs use `ubuntu-latest`, following GitHub's managed OS migrations and runner-image updates. Native ARM64 image matrices use `ubuntu-26.04-arm`; GitHub doesn't currently document an `ubuntu-latest-arm` label. Windows and macOS coverage remains on its own platform runners.
 
-- the backend job in `CI: Test`
-- the `validate-tests` job in `Release: Create Docker Image`
+Host runner choice doesn't replace production-runtime validation. Debian-family checks still include the backend test container and the release `validate-tests` container.
 
 The backend job builds the `backend-test` Docker target, which inherits the same runtime base as production. It runs mypy and the backend test suites inside that target, including when a Python image or other runtime input changes. The release validation job uses the pinned Debian-based Python container because `scripts/install-system-deps` requires distro-provided ImageMagick 7, while the default Ubuntu GitHub-hosted runner image still resolves `imagemagick` to ImageMagick 6.
 
diff --git a/website/content/docs/2.0/release-info/news-and-changes/whats-new/index.md b/website/content/docs/2.0/release-info/news-and-changes/whats-new/index.md
index 5c428c1d6..46ee79c0d 100644
--- a/website/content/docs/2.0/release-info/news-and-changes/whats-new/index.md
+++ b/website/content/docs/2.0/release-info/news-and-changes/whats-new/index.md
@@ -79,6 +79,26 @@ Sambee uses a provider refresh token when one is returned, whether or not `offli
 
 - OIDC login failures after password reset: OIDC login now completes reliably after an administrator resets the account’s password. Sambee ignores responses from the previous browser session while the new login finishes, reloads the user’s themes and settings, and returns to the file browser instead of the login page.
 
+## Text and Markdown Editors
+
+### Syntax Highlighting and Rendering Performance Optimization
+
+Sambee now uses a consolidated syntax highlighting system throughout all text and Markdown rendering surfaces: text viewer and editor, Markdown editor, fenced code blocks in Markdown viewer and editor. The syntax highlighting system is integrated with the theming system; highlight colors are now part of each theme and can be edited in the new theme editor.
+
+Text viewer/editor and Markdown editor performance was significantly boosted, especially for long documents. This was achieved through virtualization and viewport rendering.
+
+## Markdown Viewer
+
+### Print / Save as PDF
+
+When you print or save as PDF from the browser, the Markdown viewer reformats the full rendered document to fit the page, spanning multiple pages as needed. A new print icon in the top bar makes the new functionality discoverable.
+
+### Other Changes
+
+- Closing the editor by clicking the X now works in the same way as pressing <kbd>Esc</kbd>: it returns to the viewer. From there, another click returns to the file list.
+- When reloading a browser tab with an editor, Sambee now recovers the file lock. This prevents the error `Unable to enter edit mode. File is locked for editing by <username>`.
+
+
 ## Miscellaneous
 
 ### Native Mobile Sharing
@@ -114,11 +134,6 @@ HTTP for development on `localhost` is treated as secure by browsers and continu
 
 If your browser is too old or lacks features Sambee needs, you'll now see a clear message instead of a blank page. The message identifies missing capabilities and links to the browser requirements so you can choose a supported browser.
 
-### Text and Markdown Editors
-
-- Closing the editor by clicking the X now works in the same way as pressing <kbd>Esc</kbd>: it returns to the viewer. From there, another click returns to the file list.
-- When reloading a browser tab with an editor, Sambee now recovers the file lock. This prevents the error `Unable to enter edit mode. File is locked for editing by <username>`.
-
 ### Password Login
 
 - When an admin configures a user to require a password change, that change is now enforced upon the next password login.
@@ -150,6 +165,11 @@ If your browser is too old or lacks features Sambee needs, you'll now see a clea
 - Pinned all third-party GitHub Actions workflows to commit SHAs.
 - Frontend: removed `patch-package` to get rid of vulnerable transisitve dependency `braces`.
 
+### Frontend Type Correctness
+
+Type correctness of frontend code and tests is now enforced. As part of this implementation, 1,152 diagnostics across 162 files were fixed: 840 in tests, 311 in application code,
+and one in an imported browser-test helper.
+
 ## Internals
 
 - Companion build for Windows: Authenticode signing was removed from PR check builds and only remains on release workflows.
diff --git a/website/content/docs/2.0/release-info/system-requirements/requirements/index.md b/website/content/docs/2.0/release-info/system-requirements/requirements/index.md
index 36a266b94..1aa33736c 100644
--- a/website/content/docs/2.0/release-info/system-requirements/requirements/index.md
+++ b/website/content/docs/2.0/release-info/system-requirements/requirements/index.md
@@ -12,7 +12,7 @@ Sambee's frontend supports the latest versions of desktop and mobile browsers, i
 - Mozilla Firefox
 - Apple Safari
 
-If a browser lacks a required modern capability, Sambee shows a browser compatibility message instead of loading the app. This checks a few key capabilities, not every feature Sambee uses.
+Web Workers must be available. If a browser lacks this or another required modern capability, Sambee shows a browser compatibility message instead of loading the app. This checks a few key capabilities, not every feature Sambee uses. Browser or security policies that prevent a worker from starting can still cause a feature-specific error after the app loads.
 
 To preview this message on the development server, open `http://localhost:3000/browse/smb/demo?simulateUnsupportedBrowser`. Remove the query parameter to load the app normally. This flag has no effect in production builds.
 
diff --git a/website/content/docs/2.0/user-guide/viewing-and-editing-files/edit-markdown/index.md b/website/content/docs/2.0/user-guide/viewing-and-editing-files/edit-markdown/index.md
index 47daa1abf..8b2c170d2 100644
--- a/website/content/docs/2.0/user-guide/viewing-and-editing-files/edit-markdown/index.md
+++ b/website/content/docs/2.0/user-guide/viewing-and-editing-files/edit-markdown/index.md
@@ -6,12 +6,30 @@ Markdown files are opened in Sambee's [Markdown viewer](../view-images-and-read-
 
 ## Entering Edit Mode
 
-In the Markdown viewer's toolbar, click the edit icon or press <kbd>E</kbd> to switch to the Markdown editor. It opens in rich-text mode, but you can switch to source mode if you prefer to edit raw Markdown.
+In the Markdown viewer's toolbar, click the edit icon or press <kbd>E</kbd> to switch to the Markdown editor. You edit Markdown source directly, with highlighted structure and fenced code. Highlighting doesn't change your source text or line layout.
+
+## Code Colors
+
+Code blocks use the same language highlighting as the text viewer and editor. A fence's language label selects its grammar; unknown or unlabelled blocks remain plain text. Preview highlighting loads in the background and waits while you're selecting preview text. Code text, whitespace, copying, and search remain unchanged.
+
+In **Settings** > **Appearance**, edit or copy a theme and open **Syntax** to adjust the shared keyword, string, number, comment, type, function, operator, and punctuation colors. The palette applies to text viewing/editing and Markdown source/code blocks. Identifiers keep the existing code text color. Changes stay local to the theme draft until saved; Cancel doesn't apply them. Only administrators can save site themes.
+
+Existing complete themes without a Syntax group use the built-in palette matching their light or dark mode. Saving or exporting includes the resolved colors. Updated Sambee versions can import those legacy version-1 exports, but older releases may reject exports containing the new roles. Very large code blocks can remain plain text without truncating their contents.
+
+## Large Documents
+
+Large Markdown previews appear progressively. You can read the text already displayed or close the viewer while loading continues. Search, editing, heading links and the toolbar's Print action become available when the complete document is ready. Printing from the browser menu before then shows a loading notice instead of an incomplete document.
+
+Large previews can briefly pause while loading, and code colors can arrive after the text. Large Replace All operations show busy feedback before applying the complete replacement, but the editor and indicator can pause during that step. Editing very large tables can also be slow. These limitations don't shorten the document or split a replacement into separate undo steps.
 
 ## Saving Changes
 
 A small indicator next to the file name shows whether the document has unsaved changes. Click the save icon or press <kbd>Ctrl</kbd> + <kbd>S</kbd> at any time to save the current state of the document.
 
+Finish any input-method composition before saving. Sambee waits for table-cell edits to reach the document before capturing the saved text. If that can't finish, the editor stays open with your changes rather than saving an incomplete cell. Retry Save after the edit finishes.
+
+You can keep editing during an ordinary Save. Save writes the revision it captured; edits made afterward remain unsaved. If preparation or writing fails, your changes remain available in the editor.
+
 If Sambee must send you through OIDC sign-in while you are editing, it saves an eligible unsaved Markdown draft in this browser tab before leaving the page. See [Recover Unsaved In-Browser Edits](../recover-unsaved-edits/) for how recovery works.
 
 ## Leaving Edit Mode
@@ -19,3 +37,11 @@ If Sambee must send you through OIDC sign-in while you are editing, it saves an
 Click the X icon or press <kbd>Esc</kbd> to leave the Markdown editor and return to the viewer. If there are unsaved changes, choose **Save** to save them and return to the viewer, **Discard** to return without saving, or **Cancel** to keep editing. If saving fails, the editor stays open with your changes.
 
 From the viewer, click the X icon again to return to the file list. The text editor uses the same two-step close sequence.
+
+## Print Or Save As PDF
+
+In the Markdown viewer, click the printer icon to open your browser's print dialog. Choose a printer or **Save as PDF** if your browser offers it. You can also use **Print** from the browser menu. Paper size, margins and headers/footers are controlled by that dialog.
+
+The output contains the rendered document, without Sambee's toolbar or file browser. Text prints black on white in both themes. Long code lines and table cells wrap to fit the page, and images are included. Printing doesn't modify the Markdown file.
+
+Print is available in the viewer, not the editor. To print your latest changes, save them and return to the viewer first. Closing or cancelling the print dialog leaves the viewer open.
diff --git a/website/content/docs/2.0/user-guide/viewing-and-editing-files/recover-unsaved-edits/index.md b/website/content/docs/2.0/user-guide/viewing-and-editing-files/recover-unsaved-edits/index.md
new file mode 100644
index 000000000..d70e69eb5
--- /dev/null
+++ b/website/content/docs/2.0/user-guide/viewing-and-editing-files/recover-unsaved-edits/index.md
@@ -0,0 +1,29 @@
++++
+title = "Recover Unsaved In-Browser Edits"
++++
+
+Sambee can preserve eligible unsaved Markdown and plain-text edits when a required OIDC sign-in takes you away from the editor.
+
+## When Sambee Saves A Draft
+
+Sambee saves a tab-scoped recovery draft before a controlled sign-in redirect and while you continue editing. This protects work when the browser session expires, an administrator revokes the session, or the identity provider requires you to sign in again.
+
+Drafts stay in the current browser tab. They are not uploaded to Sambee, shared with another browser, or shown after you sign in as a different account.
+
+The pre-sign-in snapshot is a best-effort attempt. Sign-in continues even if a draft cannot be stored; it does not wait for unfinished editor input or save the file. Save important work regularly.
+
+## Return To Your Edit
+
+After you finish signing in, Sambee returns you to the file you were editing.
+
+- When Sambee offers an unsaved local draft, choose **Resume editing** to return to it, or **Discard draft** to keep the saved file.
+- If the remote file changed, review the recovery choice carefully. Sambee doesn't overwrite the remote version automatically.
+- Save the restored draft when you're ready. Sambee removes its recovery copy once the current draft is saved or when you deliberately discard it. Edits made while an earlier save is still in progress remain unsaved.
+
+## Recovery Limits
+
+Draft recovery depends on browser tab storage. Sambee keeps recovery drafts only for a limited time and displays a warning when a draft is too large or the browser cannot store it. Save important work regularly; do not rely on draft recovery as a replacement for saving.
+
+Closing the tab, explicitly discarding the draft, or signing out can remove the recovery copy.
+
+An unfinished edit may not be recoverable when the browser suspends or terminates the page. A successful recovery checkpoint isn't a file save or a guarantee that the draft will survive closing the tab.
diff --git a/website/content/docs/2.0/user-guide/viewing-and-editing-files/recover-unsaved-edits/inherit.md b/website/content/docs/2.0/user-guide/viewing-and-editing-files/recover-unsaved-edits/inherit.md
deleted file mode 100644
index e69de29bb..000000000
diff --git a/website/scripts/docs_editor/core.py b/website/scripts/docs_editor/core.py
index 8a3aa8d3f..2d4ac4613 100644
--- a/website/scripts/docs_editor/core.py
+++ b/website/scripts/docs_editor/core.py
@@ -1,4 +1,3 @@
-#!/usr/bin/env python3
 """Editor-oriented automation for versioned website docs content."""
 
 from __future__ import annotations
@@ -11,13 +10,12 @@
 import sys
 import tempfile
 import textwrap
+import tomllib
 from dataclasses import dataclass, field
 from enum import Enum
 from pathlib import Path
 from typing import Any, Protocol, cast
 
-import tomllib
-
 DEFAULT_WEBSITE_DIR = Path(__file__).resolve().parent.parent.parent
 
 DOCS_ROOT_INDEX = "_index.md"
@@ -130,7 +128,7 @@ class EditorPaths:
     validator_script: Path
 
     @classmethod
-    def for_website(cls, website_dir: Path) -> "EditorPaths":
+    def for_website(cls, website_dir: Path) -> EditorPaths:
         """Build an EditorPaths object for one website root."""
         root = website_dir.resolve()
         return cls(
diff --git a/website/scripts/generate-managed-redirects.py b/website/scripts/generate-managed-redirects.py
index 0eb896bdc..2555cb579 100644
--- a/website/scripts/generate-managed-redirects.py
+++ b/website/scripts/generate-managed-redirects.py
@@ -1,17 +1,15 @@
-#!/usr/bin/env python3
 """Generate configurable managed redirects in the built Cloudflare Pages artifact."""
 
 from __future__ import annotations
 
 import argparse
 import sys
+import tomllib
 from dataclasses import dataclass
 from fnmatch import fnmatchcase
 from pathlib import Path
 from urllib.parse import urlparse
 
-import tomllib
-
 WEBSITE_DIR = Path(__file__).resolve().parent.parent
 DEFAULT_CONFIG_PATH = WEBSITE_DIR / "data" / "managed-redirects.toml"
 DEFAULT_LEGACY_REDIRECTS_PATH = WEBSITE_DIR / "static" / "_redirects"
diff --git a/website/scripts/generate-social-assets.py b/website/scripts/generate-social-assets.py
index 94162a740..d04e6f165 100644
--- a/website/scripts/generate-social-assets.py
+++ b/website/scripts/generate-social-assets.py
@@ -1,4 +1,3 @@
-#!/usr/bin/env python3
 """Generate committed social preview assets for the website.
 
 This script keeps social media preview images out of Hugo's ``resources/_gen``
diff --git a/website/scripts/generate-webp.py b/website/scripts/generate-webp.py
index 70dbbff16..24f97b7e4 100644
--- a/website/scripts/generate-webp.py
+++ b/website/scripts/generate-webp.py
@@ -1,4 +1,3 @@
-#!/usr/bin/env python3
 """Generate responsive WebP derivatives for website asset images.
 
 Source images live under ``website/assets/images``. For each JPG or PNG source,
diff --git a/website/scripts/materialize-inherited-docs.py b/website/scripts/materialize-inherited-docs.py
index 42b0101d1..50a276bce 100644
--- a/website/scripts/materialize-inherited-docs.py
+++ b/website/scripts/materialize-inherited-docs.py
@@ -1,11 +1,9 @@
-#!/usr/bin/env python3
 """Generate Hugo routing anchors for inherited and stable current docs routes."""
 
 from __future__ import annotations
 
-from pathlib import Path
-
 import tomllib
+from pathlib import Path
 
 WEBSITE_DIR = Path(__file__).resolve().parent.parent
 DOCS_CONTENT_DIR = WEBSITE_DIR / "content" / "docs"
diff --git a/website/scripts/validate-docs-content.py b/website/scripts/validate-docs-content.py
index c7ba0f0d3..84d869408 100644
--- a/website/scripts/validate-docs-content.py
+++ b/website/scripts/validate-docs-content.py
@@ -1,15 +1,13 @@
-#!/usr/bin/env python3
 """Validate website docs navigation, content bundles, and inheritance markers."""
 
 from __future__ import annotations
 
 import sys
+import tomllib
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Any
 
-import tomllib
-
 WEBSITE_DIR = Path(__file__).resolve().parent.parent
 DOCS_CONTENT_DIR = WEBSITE_DIR / "content" / "docs"
 DOCS_NAV_DIR = WEBSITE_DIR / "data" / "docs-nav"
diff --git a/website/scripts/validate-homepage-ctas.py b/website/scripts/validate-homepage-ctas.py
index c29d3338f..5858333f1 100644
--- a/website/scripts/validate-homepage-ctas.py
+++ b/website/scripts/validate-homepage-ctas.py
@@ -1,4 +1,3 @@
-#!/usr/bin/env python3
 """Validate homepage CTA targets in built website output."""
 
 from __future__ import annotations
diff --git a/website/scripts/validate-webp-assets.py b/website/scripts/validate-webp-assets.py
index fdb6e3545..be9472d4e 100644
--- a/website/scripts/validate-webp-assets.py
+++ b/website/scripts/validate-webp-assets.py
@@ -1,4 +1,3 @@
-#!/usr/bin/env python3
 """Validate that every website raster source image has generated WebP files."""
 
 from __future__ import annotations